Connection
class Connection (View source)
The connection to the PostgreSQL server.
See the [General Usage](pq/Connection/: General Usage) page for an introduction on how to use this class.
Constants
| PERSISTENT |
(Re-)open a persistent connection. |
| ASYNC |
If the connection is not already open, perform the connection attempt [asynchronously](pq/Connection/: Asynchronous Usage). |
| OK |
Everything well; if a connection has been newly and synchronously created, the connection will always have this status right after creation. |
| BAD |
Broken connection; consider pq\Connection::reset() or recreation. |
| STARTED |
Waiting for connection to be made. |
| MADE |
Connection okay; waiting to send. |
| AWAITING_RESPONSE |
Waiting for a response from the server. |
| AUTH_OK |
Received authentication; waiting for backend start-up to finish. |
| SSL_STARTUP |
Negotiating SSL encryption. |
| SETENV |
Negotiating environment-driven parameter settings. |
| TRANS_IDLE |
No active transaction. |
| TRANS_ACTIVE |
A transaction command is in progress. |
| TRANS_INTRANS |
Idling in a valid transaction block. |
| TRANS_INERROR |
Idling in a failed transaction block. |
| TRANS_UNKNOWN |
Bad connection. |
| POLLING_FAILED |
The connection procedure has failed. |
| POLLING_READING |
Select for read-readiness. |
| POLLING_WRITING |
Select for write-readiness. |
| POLLING_OK |
The connection has been successfully made. |
| EVENT_NOTICE |
Register the event handler for notices. |
| EVENT_RESULT |
Register the event handler for any created results. |
| EVENT_RESET |
Register the event handler for connection resets. |
Properties
| int read-only | $status | A connection status constant value. |
|
| int read-only | $transactionStatus | A transaction status constant value. |
|
| resource read-only | $socket | The server socket resource. |
|
| bool read-only | $busy | Whether the connection is busy with [asynchronous operations](pq/Connection/: Asynchronous Usage). |
|
| string read-only | $errorMessage | Any error message on failure. |
|
| array read-only | $eventHandlers | List of registered event handlers. |
|
| string | $encoding | Connection character set. |
|
| bool | $unbuffered | Whether to fetch [asynchronous](pq/Connection/: Asynchronous Usage) results in unbuffered mode, i.e. each row generates a distinct pq\Result. |
|
| bool | $nonblocking | Whether to set the underlying socket nonblocking, useful for asynchronous handling of writes. See also pq\Connection::flush(). |
|
| string read-only | $db | The database name of the connection. |
|
| string read-only | $user | The user name of the connection. |
|
| string read-only | $pass | The password of the connection. |
|
| string read-only | $host | The server host name of the connection. |
|
| string read-only | $port | The port of the connection. |
|
| string read-only | $options | The command-line options passed in the connection request. |
|
| int | $defaultFetchType | Default fetch type for future pq\Result instances. |
|
| int | $defaultAutoConvert | Default conversion bitmask for future pq\Result instances. |
|
| int | $defaultTransactionIsolation | Default transaction isolation level for future pq\Transaction instances. |
|
| bool | $defaultTransactionReadonly | Default transaction readonlyness for future pq\Transaction instances. |
|
| bool | $defaultTransactionDeferrable | Default transaction deferrability for future pq\Transaction instances. |
Methods
Create a new PostgreSQL connection.
[Asynchronously](pq/Connection/: Asynchronous Usage) declare a cursor for a query.
Escape binary data for use within a query with the type bytea.
[Execute one or multiple SQL queries](pq/Connection/: Executing Queries) on the connection.
[Asynchronously](pq/Connection/: Asynchronous Usage) [execute an SQL query](pq/Connection: Executing Queries) on the connection.
[Execute an SQL query](pq/Connection: Executing Queries) with properly escaped parameters substituted.
[Asynchronously](pq/Connection/: Asynchronous Usage) [execute an SQL query](pq/Connection: Executing Queries) with properly escaped parameters substituted.
Flush pending writes on the connection.
Fetch the result of an [asynchronous](pq/Connection/: Asynchronous Usage) query.
Listen on $channel for notifications.
[Asynchronously](pq/Connection/: Asynchronous Usage) start listening on $channel for notifications.
Notify all listeners on $channel with $message.
[Asynchronously](pq/Connection/: Asynchronous Usage) start notifying all listeners on $channel with $message.
Stops listening for an event type.
Listen for an event.
Poll an [asynchronously](pq/Connection/: Asynchronous Usage) operating connection.
Prepare a named statement for later execution with pq\Statement::execute().
[Asynchronously](pq/Connection/: Asynchronous Usage) prepare a named statement for later execution with pq\Statement::exec().
Quote a string for safe use in a query.
Quote an identifier for safe usage as name.
Attempt to reset a possibly broken connection to a working state.
[Asynchronously](pq/Connection/: Asynchronous Usage) reset a possibly broken connection to a working state.
Begin a transaction.
[Asynchronously](pq/Connection/: Asynchronous Usage) begin a transaction.
Trace protocol communication with the server.
Unescape bytea data retrieved from the server.
Stop listening for notifications on channel $channel.
[Asynchronously](pq/Connection/: Asynchronous Usage) stop listening for notifications on channel $channel.
Details
__construct(string $dsn = "", int $flags = 0)
Create a new PostgreSQL connection.
See also [General Usage](pq/Connection/: General Usage).
Cursor
declare(string $name, int $flags, string $query)
Declare a cursor for a query.
Cursor
declareAsync(string $name, int $flags, string $query)
[Asynchronously](pq/Connection/: Asynchronous Usage) declare a cursor for a query.
NOTE: If pq\Connection::$unbuffered is TRUE, each call to pq\Connection::getResult() will generate a distinct pq\Result containing exactly one row.
string|false
escapeBytea(string $binary)
Escape binary data for use within a query with the type bytea.
NOTE: The result is not wrapped in single quotes.
Result
exec(string $query)
[Execute one or multiple SQL queries](pq/Connection/: Executing Queries) on the connection.
NOTE: Only the last result will be returned, if the query string contains more than one SQL query.
execAsync(string $query, callable $callback = null)
[Asynchronously](pq/Connection/: Asynchronous Usage) [execute an SQL query](pq/Connection: Executing Queries) on the connection.
NOTE: If pq\Connection::$unbuffered is TRUE, each call to pq\Connection::getResult() will generate a distinct pq\Result containing exactly one row.
Result
execParams(string $query, array $params, array $types = null)
[Execute an SQL query](pq/Connection: Executing Queries) with properly escaped parameters substituted.
execParamsAsync(string $query, array $params, array $types = null, callable $cb = null)
[Asynchronously](pq/Connection/: Asynchronous Usage) [execute an SQL query](pq/Connection: Executing Queries) with properly escaped parameters substituted.
NOTE: If pq\Connection::$unbuffered is TRUE, each call to pq\Connection::getResult() will generate a distinct pq\Result containing exactly one row.
bool
flush()
Flush pending writes on the connection.
Call after sending any command or data on a nonblocking connection.
If it returns FALSE, wait for the socket to become read or write-ready. If it becomes write-ready, call pq\Connection::flush() again. If it becomes read-ready, call pq\Connection::poll(), then call pq\Connection::flush() again. Repeat until pq\Connection::flush() returns TRUE.
NOTE: This method was added in v1.1.0, resp. v2.1.0.
Result|null
getResult()
Fetch the result of an [asynchronous](pq/Connection/: Asynchronous Usage) query.
If the query hasn't finished yet, the call will block until the result is available.
listen(string $channel, callable $listener)
Listen on $channel for notifications.
See pq\Connection::unlisten().
listenAsync(string $channel, callable $listener)
[Asynchronously](pq/Connection/: Asynchronous Usage) start listening on $channel for notifications.
See pq\Connection::listen().
notify(string $channel, string $message)
Notify all listeners on $channel with $message.
notifyAsync(string $channel, string $message)
[Asynchronously](pq/Connection/: Asynchronous Usage) start notifying all listeners on $channel with $message.
bool
off(string $event)
Stops listening for an event type.
int
on(string $event, callable $callback)
Listen for an event.
int
poll()
Poll an [asynchronously](pq/Connection/: Asynchronous Usage) operating connection.
See pq\Connection::resetAsync() for an usage example.
Statement
prepare(string $name, string $query, array $types = null)
Prepare a named statement for later execution with pq\Statement::execute().
Statement
prepareAsync(string $name, string $query, array $types = null)
[Asynchronously](pq/Connection/: Asynchronous Usage) prepare a named statement for later execution with pq\Statement::exec().
NOTE: If pq\Connection::$unbuffered is TRUE, each call to pq\Connection::getResult() will generate a distinct pq\Result containing exactly one row.
string|false
quote(string $payload)
Quote a string for safe use in a query.
The result is truncated at any zero byte and wrapped in single quotes.
NOTE: Beware of matching character encodings.
string|false
quoteName(string $name)
Quote an identifier for safe usage as name.
NOTE: Beware of case-sensitivity.
reset()
Attempt to reset a possibly broken connection to a working state.
resetAsync()
[Asynchronously](pq/Connection/: Asynchronous Usage) reset a possibly broken connection to a working state.
setConverter(Converter $converter)
Set a data type converter.
Transaction
startTransaction(int $isolation = \pq\Transaction::READ_COMMITTED, bool $readonly = false, bool $deferrable = false)
Begin a transaction.
Transaction
startTransactionAsync(int $isolation = \pq\Transaction::READ_COMMITTED, bool $readonly = false, bool $deferrable = false)
[Asynchronously](pq/Connection/: Asynchronous Usage) begin a transaction.
bool
trace(resource $stream = null)
Trace protocol communication with the server.
NOTE: Calling pq\Connection::trace() without argument or NULL stops tracing.
string|false
unescapeBytea(string $bytea)
Unescape bytea data retrieved from the server.
unlisten(string $channel)
Stop listening for notifications on channel $channel.
See pq\Connection::listen().
unlistenAsync(string $channel)
[Asynchronously](pq/Connection/: Asynchronous Usage) stop listening for notifications on channel $channel.
See pq\Connection::unlisten() and pq\Connection::listenAsync().
unsetConverter(Converter $converter)
Stop applying a data type converter.