Classes

A connection to a Postgres server.

The ConnectionConfiguration used to create a Connection specifies the hostname and port number of the Postgres server, the username and database to use, and other characteristics of the connection.

Connections are used to perform SQL statements. To perform a SQL statement:

• Call Connection.prepareStatement(text:) to parse the SQL text and return a Statement.
• Call Statement.execute(parameterValues:retrieveColumnMetadata:) to execute the statement and return a Cursor.
• Iterate over the Cursor to retrieve the rows in the result.
• Close the Cursor and the Statement to release resources on the Postgres server.

A Statement can be repeatedly executed, and the values of its parameters can be different each time. This is more efficient than having the Postgres server repeatedly parse the same SQL text.

A Connection performs no more than one SQL statement at a time. When Connection.prepareStatement(text:) or Statement.execute(parameterValues:retrieveColumnMetadata:) is called, any previous Cursor for the Connection is closed.

The following methods also close any previous Cursor for the Connection:

• Connection.beginTransaction()
• Connection.commitTransaction()
• Connection.rollbackTransaction()
• Statement.close()
• Cursor.close()

To concurrently perform more than one SQL statement, use multiple connections.

By default, each Statement is executed in its own transaction. The statement’s transaction is automatically rolled back if an error occurs in executing the statement, and is automatically commited upon any of the following events:

• if there are no rows in the result: upon completion of Statement.execute()
• if the result has one or more rows: after the final row has been retrieved (in other words, when Cursor.next() returns nil)
• when the Cursor is closed (in any of the ways listed above)

Alternately, transactions can be explicitly demarcated by performing the SQL BEGIN, COMMIT, and ROLLBACK commands (or equivalently, the Connection.beginTransaction(), Connection.commitTransaction(), and Connection.rollbackTransaction() methods).

No more than one thread may concurrently operate against a Connection (including its Statement and Cursor instances). However, multiple threads may concurrently operate against different connections.

When a Connection is no longer required, call Connection.close() to release its Postgres server resources and close the network socket. A Connection is automatically closed by its deinitializer, or if an unrecoverable error occurs (for example, if the Postgres server closes the network socket). Use Connection.isClosed to test whether a Connection is closed.

A pool of re-usable, interchangeable Connection instances.

Using a ConnectionPool allows an application to acquire an existing Connection from the pool, use that connection to perform one or more SQL statements, and then release it for use elsewhere in the application.

The ConnectionPoolConfiguration used to create a ConnectionPool specifies the number of connections in the pool, how long a request for a connection will wait for a connection to become available, and other characteristics of the pool.

All connections in a ConnectionPool are created from the same ConnectionConfiguration. They also have the same ConnectionDelegate (if a delegate is specified). Consequently any connection in a pool is interchangeable with any other.

Use ConnectionPool.acquireConnection(completionHandler:) to request a connection from a ConnectionPool. This method is non-blocking: its completion handler is asynchronously executed when a connection is successfully allocated to the request or if an error occurs. To release the connection back to the pool, call ConnectionPool.releaseConnection(_:).

Alternately, use ConnectionPool.withConnection(completionHandler:) to acquire a connection that is automatically released after execution of the completion handler.

When a connection is released to a ConnectionPool, there should be no transaction underway. Pair each SQL BEGIN command with either a COMMIT or ROLLBACK command (or equivalently, use the Connection.beginTransaction(), Connection.commitTransaction(), and Connection.rollbackTransaction() methods).

In general, do not close a Connection acquired from a ConnectionPool. If a connection is closed (whether explicitly or because of an unrecoverable error) then, when that connection is released, it will be discarded from the pool, allowing a new connection to be created and added to the pool.

The ConnectionPool class is threadsafe: multiple threads may concurrently operate against a ConnectionPool instance. Connections acquired from the pool are subject to the threadsafety constraints described by the API documentation for Connection.

The result of successfully executing a Statement.

When a Cursor is no longer required, call Cursor.close() to release its Postgres server resources. A Cursor is implicitly closed as a side effect of certain operations on a connection; refer to the Connection documentation for a full list. A Cursor is also automatically closed by its deinitializer.

A Cursor in PostgresClientKit corresponds to the unnamed portal of the connection on the Postgres server.

A log handler that prints log records to standard output.

Logs events of interest.

A LogRecord describes a loggable event. Each record has a level which reflects the importance of the event. If the log level of a record is at least as high as the level of the logger, the logger dispatches the record to the logger’s current handler.

Example:

let logger = Logger()
logger.level = .warning
logger.handler = ConsoleLogHandler()

let record = LogRecord(level: .warning,
                       message: "Watch out!",
                       context: "Session-14",
                       timestamp: Date(),
                       file: #file,
                       function: #function,
                       line: #line)

logger.log(record) // the record is logged (because LogLevel.warning >= logger.level)

// Convenience methods make logging more concise.
logger.warning("Watch out!", context: "Session-14")

// Examples of other log levels:
logger.severe("This is also logged") // because LogLevel.severe >= logger.level
logger.info("This is not logged")    // because LogLevel.info < logger.level

Logger is threadsafe.

A prepared SQL statement.

Use Connection.prepareStatement(text:) to create a Statement.

Call Statement.execute(parameterValues:retrieveColumnMetadata:) to execute the Statement, specifying the values of any parameters.

A Statement can be repeatedly executed, and the values of its parameters can be different each time.

When a Statement is no longer required, call Statement.close() to release its Postgres server resources. A Statement is automatically closed by its deinitializer.

A Statement in PostgresClientKit corresponds to a prepared statement on the Postgres server whose name is the id of the Statement.