NAME

Solstice::Database - Wrapper around DBI.

SYNOPSIS

  use Solstice::Database;

  my $db = new Solstice::Database()

  # For a read only query that can be sent to any read only servers
  # that are syncronized, or the write master otherwise.
  $db->readQuery("SELECT fname, lname FROM solstice.Person WHERE person_id=?", 15);

  while (my $data_ref = $db->fetchRow()) {
    warn "First: ".$data_ref->{'fname'};
    warn "Last:".$data_ref->{'lname'};
  }

  # For any inserts/updates/deletes, that
  # must go to the master
  $db->writeQuery("INSERT INTO solstice.Person (fname, lname) VALUES (?, ?)", 'Patrick', 'Michaud');

  # Get the id of that person
  my $id = $db->getLastInsertID();

  # Get a read lock (that is, lock other people from reading)
  $db->readLock('solstice.Person');

  # Get a write lock (that is, lock other people from writing)
  $db->writeLock('solstice.Person');

  # Unlock any locks
  $db->unlockTable('solstice.Person');

DESCRIPTION

This object is here to make the database connections reliable and consistent across the Solstice tools source tree. Unlike the most generic methods for database connectivity, these methods are reliable and efficient in the mod_perl environment.

**It is strongly recommended that you use this object to make all of your database connections when programming perl source for the Solstice Tools**

Export

No symbols exported.

Methods

new()

Constructor. Creates a database handle and caches it.

readQuery($sqlCommand [, $param]*)

For a read only query that can be sent to any read only servers that are synchronized, or the write master. Dies on error, and returns undef.

getSlave

Returns the database handle to a slave db. If there are no slaves, returns the master database handle.

hasSlaves

Returns a count of slaves available for connecting.

fetchRow()

After a read query, fetches a row of results. Returns undef when there aren't any more rows to read, otherwise returns a hash ref.

rowCount()

Return a count of rows returned by the last read query, or undef if a read cursor is not defined.

writeQuery($sql_command [, $param]*)

For any inserts/updates/deletes that must go to the master. Dies on error, and returns undef.

getLastInsertID()

Gets the id of the most recently inserted row.

readLock($table_name)

Gets a read lock (lock other people from reading). Dies on error, and returns undef.

writeLock($table_name)

Gets a write lock (lock other people from writing or reading). Dies on error, and returns undef.

unlockTables()

Release any table locks. Dies on error, and returns undef.

DESTROY()

Destructor.

Private methods

_isSlaveCurrent($dbh)

Takes a database handle and returns true or false if it is caught up with the master

_releaseCursor()

Releases the statement handle that was used for reading.

_connect()

Opens and returns the database handle.

_connectToSlave(\%slave_params)

Private functions

_reportErrorAndDie($function, $error, $caller, $sql)

Sends an email to the admin, and dies.

Modules Used

DBI, Date::Dumper, Time::HiRes, Solstice::Configure, Solstice::Email.

AUTHOR

Catalyst Group, <catalyst@u.washington.edu>

VERSION

$Revision: 2998 $

COPYRIGHT

Copyright 1998-2007 Office of Learning Technologies, University of Washington

Licensed under the Educational Community License, Version 1.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: http://www.opensource.org/licenses/ecl1.php

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.