Download the PHP package php-pg/pgconn without Composer

pgconn

Package pgconn is a low-level PostgreSQL database driver. It operates at nearly the same level as the C library libpq. Applications should handle normal queries with a higher level library and only use pgconn directly when needed for low-level access to PostgreSQL functionality.

Connecting

This library follows libpq behavior as much as possible. This means that you can use almost all libpq connection options and both connection string formats.

Supported libpq features:

• .pgpass file
• .pg_service.conf file
• Environment Variables
• Multiple connection hosts

Using connection string

Read about libpq connection string format 34.1.1. Connection Strings.

Supported connection strings:

• Keyword/Value, example: host=localhost port=5432 user=user password=secret dbname=mydb connect_timeout=10
  • Multi-hosts, example: host=localhost,otherhost port=5432,5433 user=user password=secret dbname=mydb connect_timeout=10
• URI, example: postgresql://user:secret@localhost:5432/mydb?connect_timeout=10
  • Multi-hosts, example: postgresql://user:secret@localhost:5432,otherhost:5433/mydb?connect_timeout=10

Read about supported connection options 34.1.2. Parameter Key Words

By instantiating config manually

API

PgConn is not concurrency safe, it should be used inside a connection pool.

Methods:

• PgConn::close(): void - Disconnect from the server
• PgConn::getConfig(): Config - Get config that was used to establish the connection
• PgConn::getHostConfig(): HostConfig - Get config for the currently connected host
• PgConn::getSocket(): Socket - Get underlying socket connection
• PgConn::getStatus(): PgConnStatus - Get current connection state
• PgConn::getPid(): int - Get backend process id
• PgConn::getSecretKey(): int - Get secret key to cancel requests
• PgConn::getTxStatus(): string (1 byte) - Get transaction status (see ReadyForQuery message for details)
• PgConn::getParameterStatuses(): array<string, string> - Get current session runtime parameters
• PgConn::getParameterStatus(string $paramName): string - Get current session runtime parameter
• PgConn::cancelRequest - Cancel running in-progress request (might not have effect, see Cancelling API calls section)

• PgConn::exec - Execute query using simple protocol (multiple queries can be specified at once).

  See example

• PgConn::execParams - Execute query using extended protocol (parameter bindings allowed), multiple queries are not allowed

  See example

• PgConn::prepare - Prepare statement

  See example

• PgConn:execPrepared - Execute prepared statement

  See example

• PgConn::copyFrom - Copy data from readable stream to the PostgreSQL server

  See example

• PgConn::copyTo - Copy data from the PostgreSQL server to writable stream

  See example

Cancelling API calls

Any of API calls can be canceled using AMPHP cancellation objects. \ When cancellation occurs, library sends CancelRequest message to the PostgreSQL server.

But there is an important note from the PostgreSQL Protocol Flow:

The cancellation signal might or might not have any effect — for example, if it arrives after the backend has finished processing the query, then it will have no effect. \ If the cancellation is effective, it results in the current command being terminated early with an error message.

The upshot of all this is that for reasons of both security and efficiency, the frontend has no direct way to tell whether a cancel request has succeeded. \ It must continue to wait for the backend to respond to the query. \ Issuing a cancel simply improves the odds that the current query will finish soon, and improves the odds that it will fail with an error message instead of succeeding.

This means that a Cancellation object may not immediately cancel a running query.

See for more information 53.2.7. Canceling Requests in Progress

Inspired by Golang package jackc/pgconn