Browse documentation

#Client Connection

The PostgreSQL client uses the ext-pgsql extension to connect to the database. You can give the connection parameters as connection strings, DSN URLs, or individual parameters.

#Connection String

The most common approach uses libpq-style connection strings:

<?php

use function Flow\PostgreSql\DSL\{pgsql_client, pgsql_connection};

// Basic connection
$client = pgsql_client(
    pgsql_connection('host=localhost dbname=mydb user=postgres password=secret')
);

// With additional options
$client = pgsql_client(
    pgsql_connection('host=localhost port=5432 dbname=mydb user=postgres sslmode=require')
);

// Unix socket connection
$client = pgsql_client(
    pgsql_connection('host=/var/run/postgresql dbname=mydb user=postgres')
);

#DSN URL

Parse the standard PostgreSQL DSN format that environment variables often use:

<?php

use function Flow\PostgreSql\DSL\{pgsql_client, pgsql_connection_dsn};

// Standard PostgreSQL DSN
$client = pgsql_client(
    pgsql_connection_dsn('postgres://myuser:secret@localhost:5432/mydb')
);

// With SSL mode
$client = pgsql_client(
    pgsql_connection_dsn('postgresql://user:pass@db.example.com/app?sslmode=require')
);

// Symfony/Doctrine format
$client = pgsql_client(
    pgsql_connection_dsn('pgsql://user:pass@localhost/mydb')
);

// From environment variable
$client = pgsql_client(
    pgsql_connection_dsn(getenv('DATABASE_URL'))
);

Supported schemes: postgres://, postgresql://, pgsql://

#Explicit Parameters

For better type safety and IDE support:

<?php

use function Flow\PostgreSql\DSL\{pgsql_client, pgsql_connection_params};

$client = pgsql_client(
    pgsql_connection_params(
        database: 'mydb',
        host: 'localhost',
        port: 5432,
        user: 'myuser',
        password: 'secret',
    )
);

// With additional libpq options
$client = pgsql_client(
    pgsql_connection_params(
        database: 'mydb',
        host: 'db.example.com',
        user: 'myuser',
        password: 'secret',
        options: [
            'sslmode' => 'require',
            'connect_timeout' => '10',
        ],
    )
);

#Overriding Parsed Parameters

ConnectionParameters is immutable. Each with*() method returns a new instance, so you can change a parsed DSN without a new parse.

<?php

use Flow\PostgreSql\Client\DsnParser;

$params = (new DsnParser())->parse('postgresql://user:pass@localhost:5432/mydb')
    ->withHost('db.internal')
    ->withPort(5544)
    ->withUser('svc')
    ->withPassword('secret')
    ->withDatabase('analytics');

#Database Suffix

withDatabaseSuffix() appends a suffix to the configured database name. The base DSN stays the same, and only the suffix changes for each environment. Parallel-test databases for each worker then work without a second DSN (mydb → mydb_test7). The suffix is appended exactly as it is. Nothing is inserted automatically, so add a separator yourself, for example _test7. An empty suffix is a no-op:

<?php

use Flow\PostgreSql\Client\DsnParser;

$params = (new DsnParser())->parse('postgresql://user:pass@localhost:5432/mydb')
    ->withDatabaseSuffix('_test7'); // database() === 'mydb_test7'

With withDatabase(), apply the override first. The suffix is then appended to the overridden name (withDatabase('other')->withDatabaseSuffix('_test') ⇒ other_test).

#Connection Lifecycle

#Checking Connection Status

<?php

if ($client->isConnected()) {
    // Connection is alive
}

#Closing Connections

Always close connections at the end:

<?php

$client->close();

For long-running applications, think about connection pooling at the infrastructure level, for example PgBouncer.

#Connection Parameters Reference

For the full list of libpq connection parameters, read the PostgreSQL documentation.

Found a typo or an outdated section? Edit this page on GitHub ↗