PGConnection

Pointer to PGconn object that encapsulates a connection to the backend.

Makes a new connection to the database server.

Undocumented

Closes the connection to the server. Also frees memory used by the PGconn object.

Note that even if the server connection attempt fails (as indicated by status()), the application should call finish() to free the memory used by the PGconn object. The PGconn pointer must not be used again after finish() has been called.

Status of the connection

At any time during connection, the status of the connection can be checked by calling status(). If this call returns PGConnStatus.bad, then the connection procedure has failed; if the call returns PGConnStatus.ok, then the connection is ready. Other states might also occur during (and only during) an asynchronous connection procedure. These indicate the current stage of the connection procedure and might be useful to provide feedback to the user for example.

Resets the communication channel to the server.

This function will close the connection to the server and attempt to reestablish a new connection to the same server, using all the same parameters previously used. This might be useful for error recovery if a working connection is lost.

Database name of the connection.

User name of the connection.

Password of the connection.

Server host name of the connection.

This can be a host name, an IP address, or a directory path if the connection is via Unix socket. (The path case can be distinguished because it will always be an absolute path, beginning with /.)

Port of the connection.

Command-line options passed in the connection request.

Returns the current in-transaction status of the server.

Interrogates the frontend/backend protocol being used.

Applications might wish to use this function to determine whether certain features are supported. Currently, the possible values are 2 (2.0 protocol), 3 (3.0 protocol), or zero (connection bad). The protocol version will not change after connection startup is complete, but it could theoretically change during a connection reset. The 3.0 protocol will normally be used when communicating with PostgreSQL 7.4 or later servers; pre-7.4 servers support only protocol 2.0. (Protocol 1.0 is obsolete and not supported by libpq.)

Returns an integer representing the server version.

Example version 10.1 -> 100001 -> major: 10, submajor: 0, minor: 1 Example version 11.0 -> 110000 -> major: 11, submajor: 0, minor: 0 Example version 9.2.0 -> 90200 -> major: 9, submajor: 2: minor: 0 Example version 9.1.5 -> 90105 -> major: 9, submajor: 1, minor: 5

Returns the server version number.

Applications might use this function to determine the version of the database server they are connected to. The result is formed by multiplying the server’s major version number by 10000 and adding the minor version number. For example, version 10.1 will be returned as 100001, and version 11.0 will be returned as 110000. Zero is returned if the connection is bad.

Prior to major version 10, PostgreSQL used three-part version numbers in which the first two parts together represented the major version. For those versions, serverVersion() uses two digits for each part; for example version 9.1.5 will be returned as 90105, and version 9.2.0 will be returned as 90200.

Therefore, for purposes of determining feature compatibility, applications should divide the result of serverVersion() by 100 not 10000 to determine a logical major version number. In all release series, only the last two digits differ between minor releases (bug-fix releases).

Returns the error message most recently generated by an operation on the connection.

Nearly all libpq functions will set a message for PQerrorMessage if they fail. Note that by libpq convention, a nonempty PQerrorMessage result can consist of multiple lines, and will include a trailing newline.

Obtains the file descriptor number of the connection socket to the server.

A valid descriptor will be greater than or equal to 0; a result of -1 indicates that no server connection is currently open. (This will not change during normal operation, but could change during connection setup or reset.)

The process ID (PID) of the backend process handling this connection.

The backend PID is useful for debugging purposes and for comparison to NOTIFY messages (which include the PID of the notifying backend process). Note that the PID belongs to a process executing on the database server host, not the local host!

True if the connection authentication method required a password, but none was available

True if connections uses SSL.

Submits a command to the server and waits for the result.

The result status should be checked for any errors. Use result errorMessage to get more information about such errors.

The command string can include multiple SQL commands (separated by semicolons). Multiple queries sent in a single exec() call are processed in a single transaction, unless there are explicit BEGIN/COMMIT commands included in the query string to divide it into multiple transactions. Note however that the returned PGResult object describes only the result of the last command executed from the string. Should one of the commands fail, processing of the string stops with it and the returned PGResult describes the error condition.

Submits a command to the server without waiting for the result(s).

After successfully calling sendQuery(), call result() one or more times to obtain the results. sendQuery() cannot be called again (on the same connection) until getResult() has returned nil, indicating that the command is done.

Waits for the next result.

Nil is returned when the command is complete and there will be no more results.

Waits for the next result and returns all result(s).

Undocumented

If input is available from the server, consume it.

If there was some kind of trouble consumeInput() throws PostgreSQLError. A successful return does not say whether any input data was actually collected. After calling consumeInput(), the application can check isBusy() and/or notifies() to see if their state has changed.

Returns true if a command is busy.

Busy means, getResult() would block waiting for input. false indicates that getResult() can be called with assurance of not blocking. isBusy() will not itself attempt to read data from the server; therefore consumeInput() must be invoked first, or the busy state will never end.

notifies() returns the next notification from a list of unhandled notification messages received from the server.

It returns nil if there are no pending notifications. Once a notification is returned from notifies(), it is considered handled and will be removed from the list of notifications.

Undocumented

Returns the client encoding.

Note that it returns the encoding ID, not a symbolic string such as EUC_JP. If unsuccessful, it returns -1.

Returns the client encoding as String.

Enables tracing of the client/server communication to a debugging file stream.

Disables tracing started by PQtrace.