Connection

public class Connection : CustomStringConvertible

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.