1 # pq\Connection: General Usage
3 What is needed to create, check and reset a connection.
5 ## Creating a connection:
7 Creating a connection to the PostgreSQL server is as simple as:
11 $connection = new pq\Connection("dbname=test user=test password=test");
15 The first argument to the Connection constructor is a ***connection string*** as described [in the PostgreSQL documentation](http://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING).
17 Optional ***flags*** are accepted as second argument. See [connection flag constants](pq/Connection#Connection.Flags:).
19 ### Creating a persistent connection:
23 $connection = new pq\Connection("dbname=test user=test password=test", pq\Connection::PERSISTENT);
27 ### Creating an asynchronously opened connection:
31 $connection = new pq\Connection("dbname=test user=test password=test", pq\Connection::ASYNC);
35 ## Checking the connection status:
37 The connection object provides a ***public readonly*** property pq\Connection::$status, which value can be one of the [connection status constants](pq/Connection#Connection.Status:).
41 switch ($connection->status) {
42 case pq\Connection::OK:
43 // connection complete
45 case pq\Connection::BAD:
49 // connection in progress
55 ## Resetting the connection:
63 Attempt to close the connection to the server and reestablish a new connection with the same connection parameters previously used.
65 ## Closing the connection:
73 ### Non-persistent connections:
75 A ***non-persistent*** connection will be closed when all references to the pq\Connection object are gone.
77 ### Persistent connections:
79 A ***persistent*** connection will be recycled, when it is not referenced any longer.
81 There is also some cleanup performed, so that subsequent usage is as unimpaired as possible:
83 * any active asynchronous queries are canceled
84 * any pending results of asynchronous queries are fetched and cleared
85 * ```ROLLBACK``` if pq\Connection::$transactionStatus is anything but pq\Connection::TRANS_IDLE
86 * ```RESET ALL``` to reset any changed session variables
87 * ```UNLISTEN``` for each listened notification channel