Class Database.

Inherits Connection. Inherited by Postgres.

This class represents a connection to the database server.

The Query and Transaction classes provide the recommended database interface. You should never need to use this class directly.

This is the abstract base class for Postgres (and any other database interface classes we implement). It's responsible for validating the database configuration, maintaining a pool of database handles, and accepting queries into a common queue via submit().

static void Database::addHandle( Database * d )

Adds d to the pool of active database connections.

static String Database::address()

Returns the address of the database server (db-address).

static void Database::checkAccess( EventHandler * owner )

This function checks that the server doesn't have privileged access to the database. It notifies owner when the check is complete. A disaster is logged if the server is connected to the database as an unduly privileged user.

The function expects to be called from ::main() after Database::checkSchema().

static void Database::checkSchema( EventHandler * owner )

This function is called by a database client to ensure that the schema is as they expect; for the moment all it does is to check that the revision matches the latest known. owner is notified when the check is completed.

The function expects to be called from ::main() after Database::setup(). It needs a runnning EventLoop.

uint Database::connectionNumber() const

Returns an nonzero positive integer which is unique to this database handler.

static uint Database::currentRevision()

This static function returns the schema revision current at the time this server was compiled.

static void Database::disconnect()

This extremely evil function shuts down all Database handles. It's used only by lib/installer to reconnect to the database. Once it's done, setup() may be called again with an appropriately altered configuration.

Don't try this at home, kids.

static uint Database::handlesNeeded()

Returns the number of handles we think we need at this time. Mostly computed based on recent work.

static bool Database::idle()

Returns true if all database handles are idle and there's no queued work for them. Returns false in all other cases.

static User Database::loginAs()

This function returns DbOwner or DbUser, as specified in the call to Database::setup().

static String Database::name()

Returns the configured database name (db-name).

static void Database::notifyWhenIdle( class EventHandler * h )

Instructs the database system to call h once as soon as the database system becomes completely idle (no queries queued or executing).

h is not executed right away, even if the database is currently idle, but rather the next time the database system becomes idle.

static uint Database::numHandles()

Returns the number of database handles currently connected to the database.

static String Database::password()

Returns the configured database password (db-password or db-owner-password).

static uint Database::port()

Returns the database server port (db-port).

void Database::processQueue()

Instructs the Database object to send any queries whose state is Query::Submitted to the server.

static void Database::reactToIdleness()

Checks whether all handles are idle and usable, and there's no queued work. If the database system really is idle, calls and forgets the EventHandler objects recorded by notifyWhenIdle().

static void Database::recordExecution()

This static function records the time at which a Database subclass issues a query to the database server. It is used to manage the creation of new database handles.

static void Database::removeHandle( Database * d )

Removes d from the pool of active database connections.

static void Database::runQueue()

This private function is used to make idle handles process the queue of queries, and is called by the two variants of submit().

static Endpoint Database::server()

Returns an Endpoint representing the address of the database server (as specified by db-address and db-port). The Endpoint may not be valid.

void Database::setState( State s )

Sets the state of this Database handle to s, which must be one of Connecting, Idle, InTransaction, FailedTransaction.

static void Database::setup( int desired, Database::User login )

This function is provided as a convenience for the (majority of) callers that use the default values for desired (0) and login (Database::DbUser). It infers the correct username and password and forwards the call to setup() with the appropriate parameters.

static void Database::setup( int desired, const String & user, const String & pass )

This setup function reads and validates the database configuration to the best of its limited ability (since connection negotiation must be left to subclasses). It logs a disaster if it fails.

It creates desired database handles (3 by default) at startup and will log in as user with the password pass.

This function expects to be called from ::main().

State Database::state() const

Returns the current state of this Database object.

Reimplements Connection::state().

static void Database::submit( List< Query > * q )

Adds the queries in the list q to the queue of submitted queries, and sets their state to Query::Submitted. The first available handle will process them (but it's not guaranteed that the same handle will process them all. Use a Transaction if you depend on ordering).

static void Database::submit( Query * q )

Adds q to the queue of submitted queries and sets its state to Query::Submitted. The first available handle will process it.

static String Database::type()

Returns the configured Database type, which may currently be only postgres.

bool Database::usable() const

Returns true if this Database handle is currently able to process queries, and false if it's busy processing queries, is shutting down, or for any other reason unwilling to process new queries. The default implementation always returns true; subclasses may override that behaviour.

static String Database::user()

Returns the database username used for this connection, as specified to (or inferred by) setup().