Class Postgres.

Implements the PostgreSQL 3.0 Frontend-Backend protocol.

This is our interface to PostgreSQL. As a subclass of Database, it accepts Query objects, sends queries to the database, and notifies callers about any resulting data. As a descendant of Connection, it is responsible for all network communications with the server.

The network protocol is documented at <doc/src/sgml/protocol.sgml> and <http://www.postgresql.org/docs/current/static/protocol.html>. The version implemented here is used by PostgreSQL 7.4 and later.

At the time of writing, there do not seem to be any other suitable PostgreSQL client libraries available. For example, libpqxx doesn't support asynchronous operation or prepared statements. Its interface would be difficult to wrap in a database-agnostic manner, and it depends on the untested libpq. The others aren't much better.

Postgres::Postgres()

Creates a Postgres object, initiates a TCP connection to the server, registers with the main loop, and adds this Database to the list of available handles.

Reimplements Database::Database().

void Postgres::authentication( char type )

This function handles the authentication phase of the protocol. It expects and responds to an authentication request, and waits for a positive response before entering the backend startup phase. It is called by react with the type of the message to process.

void Postgres::backendStartup( char type )

This function negotiates the backend startup phase of the protocol (storing any messages the server sends us), concluding the startup process when the server indicates that it is ready for queries. It is called by react() with the type of the message to process.

void Postgres::cancel( Query * q )

Issues a cancel request for the query q if it is being executed by this Postgres object. If not, it does nothing.

Reimplements Database::cancel().

void Postgres::countQueries( Query * q )

Updates the statistics when q is done.

void Postgres::error( const EString & s )

Handles all protocol/socket errors by logging the error message s and closing the connection after emptying the write buffer and notifying any pending queries of the failure.

EString Postgres::mapped( const EString & s ) const

Looks for constraint names in s and returns an error message corresponding to the relevant constraint. Returns s if it finds none.

void Postgres::process( char type )

This function handles interaction with the server once the startup phase is complete. It is called by react() with the type of the message to process.

void Postgres::processQuery( Query * q )

Sends whatever messages are required to make the backend process the query q.

EString Postgres::queryString( Query * q )

Returns the query string for q, after possibly applying version-specific hacks and workarounds.

void Postgres::sendListen()

Makes sure Postgres sends as many LISTEN commands as necessary, see DatabaseSignal and http://www.postgresql.org/docs/8.1/static/sql-listen.html

void Postgres::serverMessage()

This function handles errors and other messages from the server.

Uses the sqlstates specified http://www.postgresql.org/docs/current/static/protocol.html extensively.

void Postgres::shutdown()

Sends a termination message and takes this database handle out of circulation gracefully.

void Postgres::unknown( char type )

This function handles unknown or unwanted messages that some other function declined to process (by setting d->unknownMessage). It is called by react() with the type of the unknown message.

bool Postgres::usable() const

Returns true if this handle is willing to process new queries: i.e. if it has an active and error-free connection to the server, and no outstanding queries; and false otherwise.

Reimplements Database::usable().

static uint Postgres::version()

Returns the Postgres server's declared version number as an integer. 8.1.0 is returned as 80100, 8.3.2 as 80302.

The version number is learned immediately after connecting. version() returns 0 until the first Postgres instance learns the server version.