PHP: полный мануал с примерами, функциями и ООП

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$dsn = sprintf(
    'host=%s port=%s dbname=%s user=%s connect_timeout=5 application_name=php_manual_visible_connect',
    getenv('PGHOST'), getenv('PGPORT'), getenv('PGDATABASE'), getenv('PGUSER')
);
$connection = pg_connect($dsn, PGSQL_CONNECT_FORCE_NEW);
if ($connection === false) { throw new RuntimeException('Не удалось подключиться'); }
echo pg_dbname($connection), "\n";
var_dump($connection instanceof PgSql\Connection);
pg_close($connection);

php_manual
bool(true)

Строка подключения собрана из окружения без вывода пароля. Вызов pg_connect виден прямо в примере: объект подтверждает успешный вход, а имя базы помогает не выполнить учебный SQL не там. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$failed = @pg_connect('host=127.0.0.1 port=1 dbname=missing connect_timeout=1');
echo $failed === false ? "Соединения нет\n" : "Неожиданное соединение\n";

Соединения нет

Порт 1 выбран как заведомо отдельная локальная точка. При false таблицы и запросы ещё не существуют: приложение отвечает безопасно либо повторяет подключение по своей политике. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$dsn = sprintf('host=%s port=%s dbname=%s user=%s application_name=php_manual_persistent', getenv('PGHOST'), getenv('PGPORT'), getenv('PGDATABASE'), getenv('PGUSER'));
$first = pg_pconnect($dsn);
$second = pg_pconnect($dsn);
if ($first === false || $second === false) { throw new RuntimeException('Нет persistent-соединения'); }
var_dump(pg_get_pid($first) === pg_get_pid($second));

bool(true)

В одном CLI-процессе одинаковая строка подключения возвращает тот же persistent backend. В FPM жизненный цикл относится к worker, а не ко всем посетителям и не гарантирует один PID навсегда. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$dsn = sprintf('host=%s port=%s dbname=%s user=%s application_name=php_manual_persistent_state', getenv('PGHOST'), getenv('PGPORT'), getenv('PGDATABASE'), getenv('PGUSER'));
$first = pg_pconnect($dsn);
pg_query($first, 'CREATE TEMP TABLE persistent_probe (id integer)');
pg_query($first, 'INSERT INTO persistent_probe VALUES (1)');
pg_query($first, "SET search_path TO pg_catalog");
$second = pg_pconnect($dsn);
$path = pg_fetch_result(pg_query($second, 'SHOW search_path'), 0, 0);
$count = pg_fetch_result(pg_query($second, 'SELECT count(*) FROM pg_temp.persistent_probe'), 0, 0);
echo $path, "\n", $count, "\n";

"$user", public
1

При повторной выдаче persistent-соединения ext/pgsql выполняет RESET ALL: search_path вернулся к default. Но временная таблица той же backend-сессии осталась. Очистка GUC не равна полной изоляции состояния; транзакции, temp-объекты, LISTEN и другие сессионные ресурсы требуют политики. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$dsn = sprintf('host=%s port=%s dbname=%s user=%s application_name=php_manual_poll', getenv('PGHOST'), getenv('PGPORT'), getenv('PGDATABASE'), getenv('PGUSER'));
$async = pg_connect($dsn, PGSQL_CONNECT_ASYNC | PGSQL_CONNECT_FORCE_NEW);
if ($async === false) { throw new RuntimeException('Не удалось начать подключение'); }
try {
    $socket = pg_socket($async);
    if ($socket === false) { throw new RuntimeException('Нет сокета подключения'); }
    $deadline = hrtime(true) + 5_000_000_000;
    do {
        $state = pg_connect_poll($async);
        if ($state === PGSQL_POLLING_FAILED) { throw new RuntimeException('Подключение отклонено'); }
        if ($state === PGSQL_POLLING_OK) { break; }

        $remainingMs = (int) ceil(($deadline - hrtime(true)) / 1_000_000);
        if ($remainingMs <= 0) { throw new RuntimeException('Истёк таймаут подключения'); }
        if ($state === PGSQL_POLLING_READING || $state === PGSQL_POLLING_WRITING) {
            $ready = pg_socket_poll(
                $socket,
                $state === PGSQL_POLLING_READING ? 1 : 0,
                $state === PGSQL_POLLING_WRITING ? 1 : 0,
                $remainingMs,
            );
            if ($ready < 0) { throw new RuntimeException('Ошибка ожидания сокета'); }
            if ($ready === 0) { usleep(10_000); }
        } else {
            usleep(1_000);
        }
    } while (true);
    echo pg_dbname($async), "\n";
} finally {
    pg_close($async);
}

php_manual

ASYNC возвращает управление до завершения установления соединения. Один монотонный deadline ограничивает весь процесс. -1 от pg_socket_poll завершает опыт ошибкой, а ранний 0 повторяется с короткой паузой до deadline; незавершённое соединение закрывается в finally. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$dsn = sprintf('host=%s port=%s dbname=%s user=%s application_name=php_manual_poll_state', getenv('PGHOST'), getenv('PGPORT'), getenv('PGDATABASE'), getenv('PGUSER'));
$async = pg_connect($dsn, PGSQL_CONNECT_ASYNC | PGSQL_CONNECT_FORCE_NEW);
if ($async === false) { throw new RuntimeException('Не удалось начать подключение'); }
$seen = [];
try {
    $socket = pg_socket($async);
    if ($socket === false) { throw new RuntimeException('Нет сокета подключения'); }
    $deadline = hrtime(true) + 5_000_000_000;
    do {
        $state = pg_connect_poll($async);
        $seen[$state] = true;
        if ($state === PGSQL_POLLING_FAILED) { throw new RuntimeException('Подключение отклонено'); }
        if ($state === PGSQL_POLLING_OK) { break; }

        $remainingMs = (int) ceil(($deadline - hrtime(true)) / 1_000_000);
        if ($remainingMs <= 0) { throw new RuntimeException('Истёк таймаут подключения'); }
        if ($state === PGSQL_POLLING_READING || $state === PGSQL_POLLING_WRITING) {
            $ready = pg_socket_poll(
                $socket,
                $state === PGSQL_POLLING_READING ? 1 : 0,
                $state === PGSQL_POLLING_WRITING ? 1 : 0,
                $remainingMs,
            );
            if ($ready < 0) { throw new RuntimeException('Ошибка ожидания сокета'); }
            if ($ready === 0) { usleep(10_000); }
        } else {
            usleep(1_000);
        }
    } while (true);
    echo isset($seen[PGSQL_POLLING_OK]) ? "Готово\n" : "Не готово\n";
} finally {
    pg_close($async);
}

Готово

Набор промежуточных состояний зависит от сети и аутентификации, поэтому пример проверяет только достижение OK/FAILED. Монотонный deadline общий для всех стадий; -1 и ранний 0 различаются, а finally закрывает как готовое, так и незавершённое учебное соединение. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
echo pg_connection_status($db) === PGSQL_CONNECTION_OK ? "OK\n" : "BAD\n";

OK

Статус описывает транспортное состояние объекта. Он не доказывает, что конкретная таблица существует или что текущая транзакция пригодна к продолжению. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'BEGIN');
@pg_query($db, 'SELECT * FROM manual_missing_table');
echo pg_connection_status($db) === PGSQL_CONNECTION_OK ? "Связь жива\n" : "Связь потеряна\n";
echo pg_transaction_status($db) === PGSQL_TRANSACTION_INERROR ? "Транзакция сломана\n" : "Транзакция пригодна\n";
pg_query($db, 'ROLLBACK');

Связь жива
Транзакция сломана

После SQL-ошибки TCP-соединение остаётся OK, но транзакция принимает только ROLLBACK/ROLLBACK TO. Для этих вопросов нужны две разные функции. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, "SET application_name TO 'temporary_job'");
var_dump(pg_connection_reset($db));
$result = pg_query($db, "SELECT current_setting('application_name')");
echo pg_fetch_result($result, 0, 0), "\n";

bool(true)
php_manual_example

Reset переподключает объект с исходной строкой; временная настройка исчезает, application_name из bootstrap возвращается. Временные таблицы и незавершённое состояние тоже не следует считать сохранёнными. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$before = pg_get_pid($db);
if (!pg_connection_reset($db)) { throw new RuntimeException('Reset не удался'); }
$after = pg_get_pid($db);
var_dump($before !== $after);

bool(true)

Новый PID показывает, что reset не «очистил пару переменных» внутри прежнего backend, а установил новую сессию. PID позднее может переиспользоваться, поэтому это диагностический признак, не бизнес-ID. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
var_dump(pg_ping($db));

bool(true)

Успешный ping подтверждает, что libpq может связаться с сервером сейчас. Это не повод пропустить проверку следующего запроса. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$missing = @pg_query($db, 'SELECT * FROM manual_missing_table');
var_dump($missing === false);
var_dump(pg_ping($db));

bool(true)
bool(true)

Ошибка таблицы не означает падение сервера: SQL отказал, а соединение осталось доступным. Диагностика должна сообщать правильную причину. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$dsn = sprintf('host=%s port=%s dbname=%s user=%s application_name=php_manual_close', getenv('PGHOST'), getenv('PGPORT'), getenv('PGDATABASE'), getenv('PGUSER'));
$extra = pg_connect($dsn, PGSQL_CONNECT_FORCE_NEW);
var_dump(pg_close($extra));

bool(true)

Закрывается специально созданное соединение, а bootstrap-соединение остаётся для остальных действий примера. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$dsn = sprintf('host=%s port=%s dbname=%s user=%s application_name=php_manual_closed', getenv('PGHOST'), getenv('PGPORT'), getenv('PGDATABASE'), getenv('PGUSER'));
$extra = pg_connect($dsn, PGSQL_CONNECT_FORCE_NEW);
pg_close($extra);
try { pg_dbname($extra); } catch (Error $error) { echo $error::class, "\n"; }

Error

После закрытия тот же PgSql\Connection нельзя передавать функциям. В обычном коротком CLI PHP сам закрывает непостоянные соединения, но явное закрытие полезно при долгом процессе и большом числе независимых БД. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
echo pg_host($db), "\n";

127.0.0.1

Адрес полезен в диагностике нескольких окружений; он не заменяет проверку имени базы и пользователя. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$version = pg_version($db);
echo pg_host($db) === getenv('PGHOST') ? "Совпало\n" : "Проверьте socket/host\n";

Совпало

При Unix socket или DNS текст может отличаться от ожидания, поэтому это диагностическая подсказка, а не проверка подлинности сервера. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
echo pg_port($db), "\n";

55432

Проектный сервер намеренно не занимает системный 5432. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$port = (int) pg_port($db);
var_dump($port > 0 && $port <= 65535);

bool(true)

Функция возвращает строку. Числовое преобразование допустимо для сравнения диапазона, но исходное значение удобно хранить как часть DSN/журнала. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
echo pg_dbname($db), "\n";

php_manual

Проверка особенно полезна перед DDL в ручном инструменте; автоматический deploy дополнительно разделяет реквизиты и права. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
if (pg_dbname($db) !== 'php_manual') { throw new RuntimeException('Неверная база'); }
echo "Можно продолжать\n";

Можно продолжать

Guard защищает учебный скрипт от ошибки конфигурации, но имя нельзя считать единственной защитой — роль должна иметь минимальные права. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$options = pg_options($db);
echo $options === '' ? "Без startup-options\n" : $options . "\n";

Без startup-options

SET внутри сессии не обязан появляться здесь: функция показывает параметры командной строки backend/startup options, а не все текущие GUC. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, "SET statement_timeout TO '1500ms'");
$timeout = pg_fetch_result(pg_query($db, "SELECT current_setting('statement_timeout')"), 0, 0);
echo pg_options($db) === '' ? "options пусты\n" : pg_options($db) . "\n";
echo $timeout, "\n";
pg_query($db, 'RESET statement_timeout');

options пусты
1500ms

Текущие GUC читают SHOW/current_setting/pg_parameter_status, если сервер их сообщает. pg_options отвечает на другой вопрос. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$tty = pg_tty($db);
echo $tty === '' ? "TTY не задан\n" : $tty . "\n";

TTY не задан

Современное TCP-соединение обычно возвращает пустую строку; функция сохраняется для совместимости и редко определяет решение приложения. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
printf("tty=%s status=%s\n", pg_tty($db) === '' ? '<empty>' : pg_tty($db), pg_connection_status($db) === PGSQL_CONNECTION_OK ? 'OK' : 'BAD');

tty=<empty> status=OK

Пустой tty нормален: транспортное состояние проверяется отдельной функцией. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
echo pg_client_encoding($db), "\n";

UTF8

Кодировка описывает преобразование между клиентом и сервером. UTF8 позволяет передавать русский текст без смены режима на каждом запросе. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$before = pg_client_encoding($db);
var_dump(pg_set_client_encoding($db, 'UTF8') === 0);
echo pg_client_encoding($db), "\n";
pg_set_client_encoding($db, $before);

bool(true)
UTF8

Нулевой код — успех. Пример не выбирает LATIN1 ради демонстрации: неверная смена способна исказить реальные данные. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$before = pg_client_encoding($db);
var_dump(pg_set_client_encoding($db, 'UTF8') === 0);
echo pg_client_encoding($db), "\n";
pg_set_client_encoding($db, $before);

bool(true)
UTF8

Нулевой код — успех. Пример не выбирает LATIN1 ради демонстрации: неверная смена способна исказить реальные данные. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$before = pg_client_encoding($db);
$code = @pg_set_client_encoding($db, 'NO_SUCH_ENCODING');
var_dump($code === -1);
echo pg_client_encoding($db), "\n";
var_dump(pg_client_encoding($db) === $before);

bool(true)
UTF8
bool(true)

При отказе функция возвращает -1, а рабочая кодировка остаётся прежней. Не продолжайте импорт, если его контракт требует конкретную кодировку. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$version = pg_parameter_status($db, 'server_version');
echo is_string($version) && $version !== '' ? "Версия получена\n" : "Нет параметра\n";

Версия получена

Значение подходит для диагностики возможностей, но ветвление лучше строить по требуемой версии/feature check, а не по строковому сравнению. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$value = pg_parameter_status($db, 'manual.no_such_parameter');
var_dump($value === false);

bool(true)

false означает, что сервер не сообщил parameter status с таким именем. Не все GUC автоматически доступны этим API; для произвольного значения используют SHOW/current_setting при наличии права. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$version = pg_version($db);
echo 'client=', $version['client'], "\n";
echo 'server=', $version['server'], "\n";

client=16.15
server=18.6

Клиент — libpq внутри php_pgsql.dll, сервер — отдельный процесс PostgreSQL. Новая версия сервера не добавляет функции, отсутствующие в старой клиентской DLL. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$version = pg_version($db);
var_dump(isset($version['protocol']));
var_dump(version_compare($version['server'], '14', '>='));

bool(true)
bool(true)

Конкретный набор ключей зависит от libpq. Требование проекта формулируют как минимальную серверную версию/возможность и проверяют один раз при старте. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$pid = pg_get_pid($db);
var_dump($pid > 0);

bool(true)

PID относится к процессу PostgreSQL на сервере. Его можно сопоставить с pg_stat_activity при расследовании блокировки. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$fromPhp = pg_get_pid($db);
$fromSql = (int) pg_fetch_result(pg_query($db, 'SELECT pg_backend_pid()'), 0, 0);
var_dump($fromPhp === $fromSql);

bool(true)

Два пути описывают одну backend-сессию. После reset/reconnect номер меняется; со временем ОС может переиспользовать PID. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$socket = pg_socket($db);
echo get_resource_type($socket), "\n";

stream

Поток принадлежит соединению. Его используют в stream_select/event loop, но не читают протокол вручную и не закрывают отдельно. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$clean = false;
try {
    $socket = pg_socket($db);
    if ($socket === false) { throw new RuntimeException('Нет сокета'); }
    $deadline = hrtime(true) + 3_000_000_000;
    if (!pg_send_query($db, 'SELECT 42 AS answer')) { throw new RuntimeException('Запрос не принят'); }
    $flushed = pg_flush($db);
    if ($flushed === false) { throw new RuntimeException('Ошибка начала отправки'); }

    while ($flushed === 0) {
        $remainingNs = $deadline - hrtime(true);
        if ($remainingNs <= 0) { throw new RuntimeException('Таймаут отправки'); }
        $read = null;
        $write = [$socket];
        $except = null;
        $ready = stream_select($read, $write, $except, 0, (int) min(200_000, ceil($remainingNs / 1_000)));
        if ($ready === false) { throw new RuntimeException('Ошибка ожидания записи'); }
        if ($ready === 0) { continue; }
        $flushed = pg_flush($db);
        if ($flushed === false) { throw new RuntimeException('Ошибка досылки'); }
    }

    while (pg_connection_busy($db)) {
        $remainingNs = $deadline - hrtime(true);
        if ($remainingNs <= 0) { throw new RuntimeException('Таймаут ответа'); }
        $read = [$socket];
        $write = null;
        $except = null;
        $ready = stream_select($read, $write, $except, 0, (int) min(200_000, ceil($remainingNs / 1_000)));
        if ($ready === false) { throw new RuntimeException('Ошибка ожидания чтения'); }
        if ($ready === 0) { continue; }
        if (!pg_consume_input($db)) { throw new RuntimeException('Ошибка чтения libpq'); }
    }

    $result = pg_get_result($db);
    if (!$result instanceof PgSql\Result || pg_result_status($result) !== PGSQL_TUPLES_OK) {
        throw new RuntimeException('Нет успешного результата');
    }
    $answer = pg_fetch_result($result, 0, 'answer');
    while (pg_get_result($db) instanceof PgSql\Result) {}
    $clean = true;
    echo $answer, "\n";
} finally {
    if (!$clean) { @pg_close($db); }
}

42

stream_select обслуживает и возможную досылку, и чтение ответа в пределах одного монотонного deadline. Каждый результат send/select/consume проверяется; очередь результатов дочитывается. Если синхронизация не подтверждена, uncertain connection закрывается, а не возвращается в pool. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$socket = pg_socket($db);
$ready = pg_socket_poll($socket, 1, 0, 1);
var_dump($ready === 0 || $ready > 0);

bool(true)

На свободном соединении результат может зависеть от фоновых протокольных данных, поэтому договор — 0 timeout либо положительная readiness, а не фиксированный ответ. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$clean = false;
try {
    $socket = pg_socket($db);
    if ($socket === false) { throw new RuntimeException('Нет сокета'); }
    $deadline = hrtime(true) + 3_000_000_000;
    if (!pg_send_query($db, 'SELECT 7 * 6 AS answer')) { throw new RuntimeException('Запрос не принят'); }
    $flushed = pg_flush($db);
    if ($flushed === false) { throw new RuntimeException('Ошибка начала отправки'); }

    while ($flushed === 0) {
        $remainingMs = (int) ceil(($deadline - hrtime(true)) / 1_000_000);
        if ($remainingMs <= 0) { throw new RuntimeException('Таймаут отправки'); }
        $ready = pg_socket_poll($socket, 0, 1, $remainingMs);
        if ($ready < 0) { throw new RuntimeException('Ошибка ожидания записи'); }
        if ($ready === 0) { usleep(10_000); continue; }
        $flushed = pg_flush($db);
        if ($flushed === false) { throw new RuntimeException('Ошибка досылки'); }
    }

    while (pg_connection_busy($db)) {
        $remainingMs = (int) ceil(($deadline - hrtime(true)) / 1_000_000);
        if ($remainingMs <= 0) { throw new RuntimeException('Таймаут ответа'); }
        $ready = pg_socket_poll($socket, 1, 0, $remainingMs);
        if ($ready < 0) { throw new RuntimeException('Ошибка ожидания чтения'); }
        if ($ready === 0) { usleep(10_000); continue; }
        if (!pg_consume_input($db)) { throw new RuntimeException('Ошибка чтения libpq'); }
    }

    $result = pg_get_result($db);
    if (!$result instanceof PgSql\Result || pg_result_status($result) !== PGSQL_TUPLES_OK) {
        throw new RuntimeException('Нет успешного результата');
    }
    $answer = pg_fetch_result($result, 0, 'answer');
    while (pg_get_result($db) instanceof PgSql\Result) {}
    $clean = true;
    echo $answer, "\n";
} finally {
    if (!$clean) { @pg_close($db); }
}

42

Poll только сообщает readiness; после положительного ответа libpq явно потребляет input, busy проверяется повторно, а результаты дочитываются. На Windows/libpq ранний 0 повторяется до общего монотонного deadline. При ошибке или таймауте uncertain connection закрывается. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_send_query($db, 'SELECT pg_sleep(5)');
usleep(50_000);
var_dump(pg_cancel_query($db));
$result = pg_query($db, 'SELECT 1 AS ready');
echo pg_fetch_result($result, 0, 'ready'), "\n";

bool(true)
1

Cancel посылает серверу запрос отмены. В PHP 8.5 ext/pgsql pg_cancel_query затем забирает и очищает оставшиеся PGresult, поэтому пример проверяет готовность следующим запросом, а не вызывает pg_get_result. true означает отправку cancel request, не бизнес-откат уже зафиксированных действий. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
var_dump(pg_cancel_query($db));
echo pg_connection_status($db) === PGSQL_CONNECTION_OK ? "Соединение доступно\n" : "Соединение потеряно\n";

bool(true)
Соединение доступно

На idle-соединении cancel-запрос может успешно отправиться, но отменять нечего. Состояние своей задачи приложение отслеживает отдельно. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$password = getenv('PGPASSWORD');
if ($password === false) { throw new RuntimeException('Нет PGPASSWORD'); }
var_dump(pg_change_password($db, getenv('PGUSER'), $password));

bool(true)

Учебный пользователь меняет собственный пароль на то же значение, поэтому стенд остаётся доступным. В приложении новый секрет сначала безопасно доставляют потребителям и предусматривают ротацию/откат. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$changed = @pg_change_password($db, 'postgres', 'not-used-value');
var_dump($changed === false);
echo pg_connection_status($db) === PGSQL_CONNECTION_OK ? "Связь жива\n" : "Связь потеряна\n";

bool(true)
Связь жива

Непривилегированная роль не меняет пароль postgres. Ошибка прав не означает разрыв соединения; секрет не попадает в журнал примера. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, 'SELECT 2 + 3 AS total');
if ($result === false) { throw new RuntimeException(pg_last_error($db)); }
echo pg_fetch_result($result, 0, 'total'), "\n";

5

SQL полностью задан программой; результат проверяется до чтения. Для значений формы, URL или API нужен pg_query_params. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$created = pg_query($db, 'CREATE TEMP TABLE task_queue (id integer PRIMARY KEY, title text NOT NULL)');
if ($created === false) { throw new RuntimeException(pg_last_error($db)); }
echo pg_result_status($created, PGSQL_STATUS_STRING), "\n";

CREATE TABLE

DDL возвращает PgSql\Result без строк. Статус показывает выполненную команду; временная таблица исчезнет вместе с соединением. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE products (name text NOT NULL)');
$name = "Ручка'); DROP TABLE products; --";
$insert = pg_query_params($db, 'INSERT INTO products (name) VALUES ($1)', [$name]);
if ($insert === false) { throw new RuntimeException(pg_last_error($db)); }
$result = pg_query($db, 'SELECT name FROM products');
echo pg_fetch_result($result, 0, 'name'), "\n";

Ручка'); DROP TABLE products; --

Строка не становится частью SQL-синтаксиса: сервер получает команду и значение отдельно. Параметры защищают границу значений, а не разрешения пользователя или имена таблиц. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query_params($db, 'SELECT $1::integer AS qty, $2::boolean AS enabled, $3::text AS note', ['12', 'true', null]);
if ($result === false) { throw new RuntimeException(pg_last_error($db)); }
$row = pg_fetch_assoc($result);
echo $row['qty'], '|', $row['enabled'], '|', ($row['note'] === null ? 'NULL' : $row['note']), "\n";

12|t|NULL

ext/pgsql передаёт значения как строки/NULL без массива OID типов; явный cast делает договор понятным. PHP false превращается в пустую строку и часто не соответствует ожидаемой SQL-логике, поэтому boolean нормализуют явно. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE jobs (id integer PRIMARY KEY, title text NOT NULL)');
$prepared = pg_prepare($db, 'add_job', 'INSERT INTO jobs (id, title) VALUES ($1::integer, $2::text)');
if ($prepared === false) { throw new RuntimeException(pg_last_error($db)); }
echo pg_result_status($prepared) === PGSQL_COMMAND_OK ? "Подготовлено\n" : "Неожиданный статус\n";

Подготовлено

Подготовка разбирает SQL в текущей сессии, но ещё не вставляет строку. У результата подготовки строковый command tag пуст, поэтому проверяется числовой статус PGSQL_COMMAND_OK. Имя add_job существует только на этом соединении. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$first = pg_prepare($db, 'manual_duplicate', 'SELECT $1::integer');
$second = @pg_prepare($db, 'manual_duplicate', 'SELECT $1::text');
var_dump($first instanceof PgSql\Result);
var_dump($second === false);

bool(true)
bool(true)

Одно имя нельзя молча переопределить другой командой. Выберите уникальные имена, DEALLOCATE/pg_close_stmt при доступности либо держите каталог prepared statements в одном месте. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$first = pg_prepare($db, '', 'SELECT 1 AS value');
$second = pg_prepare($db, '', 'SELECT 2 AS value');
if ($first === false || $second === false) { throw new RuntimeException(pg_last_error($db)); }
$result = pg_execute($db, '', []);
if ($result === false) { throw new RuntimeException(pg_last_error($db)); }
echo pg_fetch_result($result, 0, 'value'), "\n";

2

Пустая строка — допустимое имя специальной безымянной statement. Следующий pg_prepare с пустым именем заменяет предыдущую; это отличается от конфликта двух одинаковых непустых имён. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE jobs (id integer PRIMARY KEY, title text NOT NULL)');
pg_prepare($db, 'add_job_twice', 'INSERT INTO jobs (id, title) VALUES ($1::integer, $2::text)');
foreach ([[1, 'Импорт'], [2, 'Отчёт']] as $params) {
    $result = pg_execute($db, 'add_job_twice', $params);
    if ($result === false) { throw new RuntimeException(pg_last_error($db)); }
}
echo pg_fetch_result(pg_query($db, 'SELECT count(*) FROM jobs'), 0, 0), "\n";

2

SQL подготовлен один раз, данные меняются. Это удобно внутри одного соединения/worker; между разными соединениями statement нужно подготовить отдельно. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_prepare($db, 'need_integer', 'SELECT $1::integer AS number');
$failed = @pg_execute($db, 'need_integer', ['twelve']);
var_dump($failed === false);
echo pg_connection_status($db) === PGSQL_CONNECTION_OK ? "Связь жива\n" : "Связь потеряна\n";

bool(true)
Связь жива

Сервер отверг значение типа integer, но соединение сохранилось. Если вызов был внутри BEGIN, транзакция станет INERROR и потребует ROLLBACK. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
if (!function_exists('pg_close_stmt')) {
    echo "Нужна PHP-сборка с libpq 17+\n";
    return;
}
pg_prepare($db, 'temporary_supported', 'SELECT 1');
$closed = pg_close_stmt($db, 'temporary_supported');
echo $closed instanceof PgSql\Result ? "Statement закрыта\n" : "Закрыть не удалось\n";

Нужна PHP-сборка с libpq 17+

На текущем стенде php_pgsql.dll собрана с libpq 16.15, поэтому честно выполняется capability-ветка. На поддерживаемой сборке тот же пример вызывает pg_close_stmt и проверяет реальный PgSql\Result. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
if (!function_exists('pg_close_stmt')) {
    echo "Нужна PHP-сборка с libpq 17+\n";
    return;
}
pg_prepare($db, 'reusable_stmt', 'SELECT 1 AS value');
$closed = pg_close_stmt($db, 'reusable_stmt');
if (!$closed instanceof PgSql\Result) { throw new RuntimeException(pg_last_error($db)); }
pg_prepare($db, 'reusable_stmt', 'SELECT 2 AS value');
$result = pg_execute($db, 'reusable_stmt', []);
echo pg_fetch_result($result, 0, 'value'), "\n";

Нужна PHP-сборка с libpq 17+

Текущая сборка показывает честную границу capability. При libpq 17+ пример выполняет саму функцию, затем доказывает документированный эффект: освобождённое имя можно подготовить заново. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
if (pg_prepare($db, 'temporary_calc', 'SELECT $1::integer * 2') === false) {
    throw new RuntimeException('Команда не подготовлена');
}
try {
    if (function_exists('pg_close_stmt')) {
        $closed = pg_close_stmt($db, 'temporary_calc');
        if (!$closed instanceof PgSql\Result) { throw new RuntimeException('Не закрыто через API'); }
        echo "Закрыто API\n";
    } else {
        $closed = pg_query($db, 'DEALLOCATE temporary_calc');
        if (!$closed instanceof PgSql\Result) { throw new RuntimeException('Не закрыто через SQL'); }
        echo "Закрыто SQL\n";
    }

    if (pg_prepare($db, 'temporary_calc', 'SELECT $1::integer * 3') === false) {
        throw new RuntimeException('Имя не освободилось');
    }
    $result = pg_execute($db, 'temporary_calc', [7]);
    if (!$result instanceof PgSql\Result) { throw new RuntimeException('Повторная команда не выполнена'); }
    echo 'Повторное имя: ', pg_fetch_result($result, 0, 0), "\n";
} finally {
    @pg_query($db, 'DEALLOCATE temporary_calc');
}

Закрыто SQL
Повторное имя: 21

И pg_close_stmt, и совместимый SQL DEALLOCATE освобождают server-side prepared statement в текущей сессии. Пример доказывает это повторной подготовкой и выполнением команды под тем же именем; финальный DEALLOCATE очищает учебное состояние. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$allowed = ['name', 'price_kopecks'];
$requested = 'name';
if (!in_array($requested, $allowed, true)) { throw new InvalidArgumentException('Неизвестная колонка'); }
$sql = 'SELECT ' . pg_escape_identifier($db, $requested) . " FROM (VALUES ('Ручка')) AS p(name)";
echo pg_fetch_result(pg_query($db, $sql), 0, 0), "\n";

Ручка

Allowlist решает, разрешена ли колонка, quoting — как записать уже разрешённое имя. Параметр $1 не может заменить identifier. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$schema = pg_escape_identifier($db, 'pg_temp');
$table = pg_escape_identifier($db, 'Order Items');
echo $schema, '.', $table, "\n";

"pg_temp"."Order Items"

Если передать строку pg_temp.Order Items целиком, точка станет частью одного identifier. Структуру schema.table задаёт программа, каждую часть цитирует отдельно. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$literal = pg_escape_literal($db, "O'Reilly");
echo $literal, "\n";

'O''Reilly'

Возвращаемая строка уже содержит внешние одинарные кавычки. Для обычного запроса pg_query_params понятнее; literal нужен главным образом при построении ограниченной SQL-структуры, где параметры невозможны. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE manual_literal (id integer)');
$comment = pg_escape_literal($db, "Учебная таблица O'Reilly");
$result = pg_query($db, 'COMMENT ON TABLE manual_literal IS ' . $comment);
echo pg_result_status($result, PGSQL_STATUS_STRING), "\n";

COMMENT

COMMENT ON не принимает $1 в utility-команде этого вида. Значение берётся из доверенной конфигурации и цитируется как literal; имя таблицы остаётся программной константой. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$escaped = pg_escape_string($db, "O'Reilly");
echo $escaped, "\n";
echo pg_escape_literal($db, "O'Reilly"), "\n";

O''Reilly
'O''Reilly'

pg_escape_string возвращает только внутреннее содержимое. Если вручную забыть внешние кавычки или применить строку в другом контексте, SQL сломается; поэтому параметризация предпочтительнее. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$value = "A'B";
$manual = "SELECT '" . pg_escape_string($db, $value) . "' AS value";
$first = pg_fetch_result(pg_query($db, $manual), 0, 0);
$second = pg_fetch_result(pg_query_params($db, 'SELECT $1::text AS value', [$value]), 0, 0);
var_dump($first === $second);

bool(true)

Оба дают один результат для простого text, но второй вариант отделяет структуру и значение и не требует помнить кавычки. Escape не решает identifiers, LIKE wildcards, JSON-path или regex semantics. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$table = 'manual_convert_items_' . pg_get_pid($db) . '_' . bin2hex(random_bytes(6));
$identifier = pg_escape_identifier($db, $table);
$created = false;
try {
    if (pg_query($db, "CREATE TABLE {$identifier} (qty integer NOT NULL, enabled boolean, note text)") === false) {
        throw new RuntimeException('Учебная таблица не создана');
    }
    $created = true;
    $converted = pg_convert($db, $table, ['qty' => 12, 'enabled' => true, 'note' => null]);
    if ($converted === false) { throw new RuntimeException('Не преобразовано'); }
    echo $converted['"qty"'], '|', $converted['"enabled"'], '|', $converted['"note"'], "\n";
} finally {
    if ($created && pg_query($db, "DROP TABLE {$identifier}") === false) {
        throw new RuntimeException('Своя учебная таблица не удалена');
    }
}

12|'t'|NULL

Функция читает каталог обычной таблицы и возвращает SQL-представления, а не «очищенный бизнес-массив». Имя постоянно только в пределах опыта, но получает PID и случайный суффикс; чужая таблица заранее не удаляется, а finally удаляет объект лишь после собственного успешного CREATE. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$table = 'manual_convert_numbers_' . pg_get_pid($db) . '_' . bin2hex(random_bytes(6));
$identifier = pg_escape_identifier($db, $table);
$created = false;
try {
    if (pg_query($db, "CREATE TABLE {$identifier} (qty integer NOT NULL)") === false) {
        throw new RuntimeException('Учебная таблица не создана');
    }
    $created = true;
    try {
        pg_convert($db, $table, ['qty' => ['not', 'scalar']]);
    } catch (TypeError|ValueError $error) {
        echo $error::class, "\n";
    }
} finally {
    if ($created && pg_query($db, "DROP TABLE {$identifier}") === false) {
        throw new RuntimeException('Своя учебная таблица не удалена');
    }
}

TypeError

С PHP 8.3 несовместимое значение вызывает TypeError/ValueError. Случайное имя исключает столкновение параллельных запусков; флаг created не позволяет cleanup удалить таблицу, которую этот запуск не создал. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$table = 'manual_metadata_items_' . pg_get_pid($db) . '_' . bin2hex(random_bytes(6));
$identifier = pg_escape_identifier($db, $table);
$created = false;
try {
    if (pg_query($db, "CREATE TABLE {$identifier} (id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY, title text NOT NULL, note text)") === false) {
        throw new RuntimeException('Учебная таблица не создана');
    }
    $created = true;
    $meta = pg_meta_data($db, $table);
    if ($meta === false) { throw new RuntimeException('Метаданные недоступны'); }
    echo $meta['title']['type'], '|', ($meta['title']['not null'] ? 'required' : 'optional'), "\n";
} finally {
    if ($created && pg_query($db, "DROP TABLE {$identifier}") === false) {
        throw new RuntimeException('Своя учебная таблица не удалена');
    }
}

text|required

Метаданные помогают универсальному импортеру, но не превращают любую колонку в разрешённое поле формы. PID и случайный суффикс изолируют параллельные запуски; cleanup удаляет только таблицу, успешно созданную этим запуском. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$table = 'manual_metadata_extended_' . pg_get_pid($db) . '_' . bin2hex(random_bytes(6));
$identifier = pg_escape_identifier($db, $table);
$created = false;
try {
    if (pg_query($db, "CREATE TABLE {$identifier} (id bigint GENERATED ALWAYS AS IDENTITY, created_at timestamptz NOT NULL DEFAULT now())") === false) {
        throw new RuntimeException('Учебная таблица не создана');
    }
    $created = true;
    $meta = pg_meta_data($db, $table, true);
    if ($meta === false) { throw new RuntimeException('Метаданные недоступны'); }
    var_dump($meta['created_at']['has default']);
    echo $meta['created_at']['type'], "\n";
} finally {
    if ($created && pg_query($db, "DROP TABLE {$identifier}") === false) {
        throw new RuntimeException('Своя учебная таблица не удалена');
    }
}

bool(true)
timestamptz

Набор полей extended зависит от версии; код проверяет нужный ключ. Случайное имя не пересекается с чужими объектами, а created-флаг ограничивает DROP объектом этого запуска. Runtime-introspection не заменяет миграции. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE helper_products (sku text PRIMARY KEY, price integer NOT NULL)');
$result = pg_insert($db, 'helper_products', ['sku' => 'PEN-01', 'price' => 120], PGSQL_DML_ESCAPE | PGSQL_DML_EXEC);
if (!$result instanceof PgSql\Result) { throw new RuntimeException('INSERT не выполнен'); }
echo pg_affected_rows($result), "\n";

1

Флаг ESCAPE обязателен для этого варианта с raw values. Для динамического приложения pg_query_params обычно яснее: виден SQL, типы, RETURNING и обработка конфликта. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE helper_preview (name text NOT NULL)');
$sql = pg_insert($db, 'helper_preview', ['name' => "O'Reilly"], PGSQL_DML_ESCAPE | PGSQL_DML_STRING);
echo str_starts_with((string) $sql, 'INSERT INTO'), "\n";
echo pg_fetch_result(pg_query($db, 'SELECT count(*) FROM helper_preview'), 0, 0), "\n";

1
0

STRING возвращает текст и не меняет таблицу. Не публикуйте SQL с персональными значениями в браузер/обычный лог; preview нужен для диагностики/миграции и требует тех же проверок. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE helper_orders (id integer PRIMARY KEY, status text NOT NULL)');
pg_query($db, "INSERT INTO helper_orders VALUES (1, 'new'), (2, 'paid')");
$rows = pg_select($db, 'helper_orders', ['status' => 'paid'], PGSQL_DML_ESCAPE | PGSQL_DML_EXEC);
echo count($rows), '|', $rows[0]['id'], "\n";

1|2

Помощник строит только равенства по переданным колонкам. Для диапазона, JOIN, ORDER BY и LIMIT нужен явный параметризованный SELECT. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE helper_customers (id integer PRIMARY KEY)');
pg_query($db, 'INSERT INTO helper_customers VALUES (1), (2)');
$conditions = [];
if ($conditions === []) { echo "Фильтр обязателен\n"; }
else { pg_select($db, 'helper_customers', $conditions); }

Фильтр обязателен

Пустой conditions может означать все строки. Решение — явная политика приложения, а не надежда на helper. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE helper_stock (sku text PRIMARY KEY, qty integer NOT NULL)');
pg_query($db, "INSERT INTO helper_stock VALUES ('PEN-01', 5)");
$updated = pg_update($db, 'helper_stock', ['qty' => 4], ['sku' => 'PEN-01'], PGSQL_DML_ESCAPE | PGSQL_DML_EXEC);
var_dump($updated);
echo pg_fetch_result(pg_query($db, "SELECT qty FROM helper_stock WHERE sku='PEN-01'"), 0, 0), "\n";

bool(true)
4

pg_update возвращает true при успешном выполнении, а не PgSql\Result, поэтому число изменённых строк из него получить нельзя. Для атомарного списания и точной проверки масштаба лучше явный UPDATE ... WHERE qty >= $1 RETURNING. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$conditions = [];
if ($conditions === []) { echo "UPDATE без WHERE запрещён\n"; } else { pg_update($db, 'some_table', ['status' => 'done'], $conditions); }

UPDATE без WHERE запрещён

Код делает политику видимой до обращения к БД. Даже если helper разрешает форму, массовое изменение требует отдельного намерения/права. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE helper_tokens (id integer PRIMARY KEY, label text NOT NULL)');
pg_query($db, "INSERT INTO helper_tokens VALUES (1, 'expired'), (2, 'active')");
$deleted = pg_delete($db, 'helper_tokens', ['id' => 1], PGSQL_DML_ESCAPE | PGSQL_DML_EXEC);
var_dump($deleted);
echo pg_fetch_result(pg_query($db, 'SELECT count(*) FROM helper_tokens'), 0, 0), "\n";

bool(true)
1

Удаление ограничено первичным ключом; true подтверждает выполнение helper, но не сообщает affected rows. В рабочем сервисе проверяют владельца/право и решают, требуется soft delete/audit. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE helper_cleanup (id integer PRIMARY KEY)');
pg_query($db, 'INSERT INTO helper_cleanup VALUES (1)');
$sql = pg_delete($db, 'helper_cleanup', ['id' => 1], PGSQL_DML_ESCAPE | PGSQL_DML_STRING);
echo str_starts_with((string) $sql, 'DELETE FROM'), "\n";
echo pg_fetch_result(pg_query($db, 'SELECT count(*) FROM helper_cleanup'), 0, 0), "\n";

1
1

STRING помогает увидеть действие, но лог с полными значениями может утечь. Preview не является разрешением на последующее выполнение. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE affected_items (sku text PRIMARY KEY)');
$result = pg_query_params($db, 'INSERT INTO affected_items (sku) VALUES ($1), ($2)', ['PEN-01', 'BOOK-02']);
echo pg_affected_rows($result), "\n";

2

Счётчик относится к конкретному INSERT-result. Он позволяет проверить ожидаемый масштаб изменения до перехода к следующему действию. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, 'SELECT n FROM generate_series(1, 3) AS n');
printf("affected=%d, rows=%d\n", pg_affected_rows($result), pg_num_rows($result));

affected=3, rows=3

Несмотря на название, libpq сообщает число выбранных строк и для SELECT. Для читаемости прикладного кода у SELECT обычно используют pg_num_rows, а у INSERT/UPDATE/DELETE — pg_affected_rows. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, "SELECT * FROM (VALUES ('PEN-01', 120), ('BOOK-02', 450)) AS p(sku, price) ORDER BY sku");
$rows = pg_fetch_all($result);
foreach ($rows as $row) { echo $row['sku'], '=', $row['price'], "\n"; }

BOOK-02=450
PEN-01=120

Каждая строка стала ассоциативным массивом. Числа PostgreSQL здесь приходят строками, поэтому бизнес-код явно преобразует их после проверки, если ему нужна арифметика. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, 'SELECT 1 AS id WHERE false');
$rows = pg_fetch_all($result);
printf("count=%d, empty=%s\n", count($rows), $rows === [] ? 'yes' : 'no');

count=0, empty=yes

Начиная с PHP 8.0 пустая выборка возвращает [], а не false. Ошибка запроса проверяется раньше по результату pg_query; пустой список — штатный бизнес-результат. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, "SELECT * FROM (VALUES (10, 'PEN-01'), (20, 'BOOK-02')) AS p(id, sku) ORDER BY id");
$skus = pg_fetch_all_columns($result, 1);
echo implode(',', $skus), "\n";

PEN-01,BOOK-02

Номер поля начинается с нуля: 1 означает вторую колонку SELECT. Это удобно для плоского списка ID/кодов, когда остальные поля не нужны PHP-коду. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, "SELECT * FROM (VALUES (NULL::text), ('ready')) AS x(note)");
$notes = pg_fetch_all_columns($result);
echo $notes[0] === null ? "NULL сохранён\n" : "Не NULL\n";
try { pg_fetch_all_columns($result, 2); } catch (ValueError $error) { echo "Нет такой колонки\n"; }

NULL сохранён
Нет такой колонки

SQL NULL не превращается в пустую строку. Номер за пределами результата вызывает ValueError, поэтому для динамического результата сначала находят колонку через pg_field_num и проверяют -1. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, "SELECT 'PEN-01'::text AS sku, 3::integer AS qty");
$row = pg_fetch_array($result, 0);
printf("%s|%s|keys=%d\n", $row[0], $row['sku'], count($row));

PEN-01|PEN-01|keys=4

По умолчанию два поля доступны и как 0/1, и как sku/qty, поэтому у массива четыре ключа. Обычно выбирают один режим, чтобы не путать чтение и сериализацию. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, "SELECT * FROM (VALUES (1, 'new'), (2, 'paid')) AS o(id, status) ORDER BY id");
while (($row = pg_fetch_array($result, null, PGSQL_ASSOC)) !== false) { echo $row['id'], ':', $row['status'], "\n"; }
var_dump(pg_fetch_array($result, null, PGSQL_ASSOC));

1:new
2:paid
bool(false)

null просит следующую строку внутреннего курсора. false после последней строки — нормальный сигнал окончания, а не обязательно ошибка БД. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, "SELECT 'A-17'::text AS order_no, 990::integer AS total");
$row = pg_fetch_assoc($result);
echo $row['order_no'], '|', $row['total'], "\n";

A-17|990

Имена берутся из SELECT aliases. Это делает код устойчивее к перестановке колонок, если сами alias сохраняются. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$bad = pg_fetch_assoc(pg_query($db, 'SELECT 1 AS id, 2 AS id'));
$good = pg_fetch_assoc(pg_query($db, 'SELECT 1 AS product_id, 2 AS order_id'));
echo $bad['id'], '|', $good['product_id'], '|', $good['order_id'], "\n";

2|1|2

В ассоциативном массиве одинаковый ключ id не может хранить два значения: последнее перезаписало первое. В JOIN каждой одноимённой колонке дают уникальный alias. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, "SELECT 'BOOK-02'::text AS sku, 450::integer AS price");
$product = pg_fetch_object($result);
echo $product->sku, '=', $product->price, "\n";

BOOK-02=450

stdClass лишь меняет синтаксис доступа с массива на свойства. Значение price всё равно строка и ещё не стало проверенным объектом предметной области. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
class ProductRow {
    public string $sku;
    public string $qty;
    public string $seenByConstructor = '';
    public function __construct(public string $source) { $this->seenByConstructor = $this->sku ?? '<unset>'; }
}
$result = pg_query($db, "SELECT 'PEN-01'::text AS sku, 4::integer AS qty");
$row = pg_fetch_object($result, 0, ProductRow::class, ['database']);
printf("%s|%s|%s|%s\n", $row->sku, $row->qty, $row->source, $row->seenByConstructor);

PEN-01|4|database|PEN-01

ext/pgsql присваивает свойства до вызова конструктора. Такое неявное hydration может нарушить типы/инварианты сложной модели; для доменного объекта безопаснее получить assoc-row, проверить данные и вызвать именованный factory. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, 'SELECT count(*) AS total FROM generate_series(1, 4)');
$total = pg_fetch_result($result, 0, 'total');
printf("value=%s, php-type=%s\n", $total, gettype($total));

value=4, php-type=string

Даже count(*) приходит строкой. После проверки диапазона приложение может привести значение к int; сама функция не знает бизнес-типа. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, 'SELECT true AS enabled, NULL::text AS note');
$enabled = pg_fetch_result($result, 0, 'enabled');
$note = pg_fetch_result($result, 0, 'note');
echo $enabled, '|', $note === null ? 'NULL' : $note, "\n";

t|NULL

PostgreSQL bool возвращается текстом t/f, а SQL NULL — PHP null. Проверка if ($enabled) была бы ошибочной для строки "f", потому что непустая строка truthy; значение преобразуют явно. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, "SELECT 'A-17'::text AS order_no, 990::integer AS total");
[$orderNo, $total] = pg_fetch_row($result);
echo $orderNo, '|', $total, "\n";

A-17|990

Числовые индексы повторяют порядок SELECT. Такой код короток, когда контракт колонок фиксирован и виден рядом. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, "SELECT * FROM (VALUES (1, 'new'), (2, 'paid')) AS o(id, status) ORDER BY id");
while (($row = pg_fetch_row($result)) !== false) { echo $row[0], ':', $row[1], "\n"; }

1:new
2:paid

Для экспорта без смысловых ключей числовой массив удобен. Если SELECT переставит колонки, индексы изменятся молча; прикладному коду чаще понятнее pg_fetch_assoc с aliases. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, "SELECT NULL::text AS missing, ''::text AS empty");
printf("missing=%d, empty=%d\n", pg_field_is_null($result, 0, 'missing'), pg_field_is_null($result, 0, 'empty'));

missing=1, empty=0

Обе величины могут выглядеть пустыми в HTML, но имеют разный смысл: NULL — значение отсутствует, пустая строка — значение задано и имеет нулевую длину. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, 'SELECT NULL::integer AS discount UNION ALL SELECT 0 ORDER BY discount NULLS FIRST');
for ($row = 0; $row < 2; $row++) { echo pg_field_is_null($result, $row, 'discount') === 1 ? "not-set\n" : pg_fetch_result($result, $row, 'discount') . "\n"; }

not-set
0

Проверка не подменяет значение оператором empty(): 0 — реальная скидка, NULL — отсутствие настройки. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, "SELECT 7 AS id, 'PEN-01'::text AS sku, 120::integer AS price");
$names = [];
for ($field = 0; $field < pg_num_fields($result); $field++) { $names[] = pg_field_name($result, $field); }
echo implode(',', $names), "\n";

id,sku,price

Имена описывают конкретный SELECT, а не всю таблицу. Для пользовательского CSV заголовки обычно переводят по allowlist, а не показывают внутренние имена напрямую. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, 'SELECT 1 AS id, 2 AS id');
echo pg_field_name($result, 0), '|', pg_field_name($result, 1), "\n";
echo pg_field_name(pg_query($db, 'SELECT 1 AS product_id, 2 AS order_id'), 1), "\n";

id|id
order_id

PostgreSQL допускает одинаковые подписи выходных колонок. pg_fetch_assoc потеряет одно значение, поэтому JOIN/вычисления получают уникальные aliases. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, 'SELECT 10 AS id, 20 AS qty, 30 AS price');
echo pg_field_num($result, 'price'), "\n";

2

Нумерация начинается с нуля. Результат можно проверить на -1, а затем передать в pg_fetch_all_columns или функции метаданных. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, 'SELECT 1 AS "OrderID"');
printf("plain=%d, quoted=%d\n", pg_field_num($result, 'OrderID'), pg_field_num($result, '"OrderID"'));

plain=-1, quoted=0

Имя аргумента разбирается как SQL identifier: без двойных кавычек оно приводится к нижнему регистру. Практичнее давать aliases в snake_case без кавычек. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, "SELECT 'ABC'::text AS code");
echo pg_field_prtlen($result, 0, 'code'), " bytes\n";

3 bytes

Функция читает PQgetlength для конкретной ячейки результата. Это размер её текстового представления в байтах, а не объявленная ширина SQL-типа. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, "SELECT 'Привет'::text AS greeting");
$value = pg_fetch_result($result, 0, 'greeting');
printf("bytes=%d, text=%s\n", pg_field_prtlen($result, 0, 'greeting'), $value);

bytes=12, text=Привет

В UTF-8 шесть русских букв занимают 12 байт. Для лимита интерфейса по символам нужна Unicode-aware функция, а pg_field_prtlen полезна для оценки конкретного wire-value. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, "SELECT 1::integer AS qty, 'A'::text AS note");
printf("qty=%d, note=%d\n", pg_field_size($result, 0), pg_field_size($result, 1));

qty=4, note=-1

4 — внутренняя ширина типа int4; -1 означает переменную ширину text. Это не размер текущих значений 1 и A и не расход PHP-массива. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, 'SELECT 1::bigint AS id, true::boolean AS enabled, current_date AS day');
for ($i = 0; $i < pg_num_fields($result); $i++) { printf("%s:%d\n", pg_field_name($result, $i), pg_field_size($result, $i)); }

id:8
enabled:1
day:4

Карта помогает диагностировать неожиданный cast запроса. Она не заменяет миграции и не годится для оценки размера строки на диске: там есть заголовки, NULL bitmap, TOAST и выравнивание. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE result_products (id integer PRIMARY KEY, title text)');
$result = pg_query($db, 'SELECT id, title FROM result_products');
echo pg_field_table($result, 0), "\n";
var_dump(is_int(pg_field_table($result, 0, true)));

result_products
bool(true)

В режиме oid_only возвращается OID без дополнительного поиска имени в каталоге. OID полезен внутри текущей БД, но не является переносимым ID между базами. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, 'SELECT 2 + 3 AS total');
var_dump(pg_field_table($result, 0));

bool(false)

Выражение total не является прямой колонкой таблицы, поэтому происхождение false. То же возможно для некоторых views/выражений: не стройте авторизацию по этому runtime-метаданному. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, "SELECT 7::integer AS qty, 12.50::numeric AS price, 'ok'::text AS note");
for ($i = 0; $i < 3; $i++) { echo pg_field_type($result, $i), $i === 2 ? "\n" : '|'; }

int4|numeric|text

Функция возвращает внутренние имена базовых типов PostgreSQL. Они помогают диагностике/универсальному импорту, но схема ожидаемых полей всё равно задаётся приложением. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, 'SELECT 42::integer AS qty, true::boolean AS enabled');
$row = pg_fetch_assoc($result);
printf("db=%s/%s, php=%s/%s, values=%s/%s\n", pg_field_type($result, 0), pg_field_type($result, 1), gettype($row['qty']), gettype($row['enabled']), $row['qty'], $row['enabled']);

db=int4/bool, php=string/string, values=42/t

Метаданные говорят int4/bool, но text protocol отдаёт строки. Приведение в int/bool выполняют явно после проверки, а строку "f" нельзя передавать напрямую в if. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, "SELECT 1::integer AS id, 'x'::text AS note");
echo pg_field_type_oid($result, 0), '|', pg_field_type_oid($result, 1), "\n";

23|25

23 — OID int4, 25 — OID text в PostgreSQL. Для пользовательских типов OID относятся к конкретной базе и не должны сохраняться как глобальные константы приложения. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, 'SELECT 1::integer AS qty');
$oid = pg_field_type_oid($result, 0);
$nameResult = pg_query_params($db, 'SELECT format_type($1::oid, NULL) AS name', [$oid]);
echo pg_fetch_result($nameResult, 0, 'name'), "\n";

integer

OID передан параметром и расшифрован самим сервером. Для схемных инструментов можно читать pg_type, но бизнес-код обычно знает ожидаемый контракт без runtime-introspection. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, 'SELECT 1 AS id, 2 AS qty, 3 AS price');
echo pg_num_fields($result), "\n";

3

Считаются именно поля результата после aliases/выражений, а не количество колонок исходной таблицы. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, "SELECT 'A-17'::text AS order_no, 990::integer AS total");
for ($i = 0, $count = pg_num_fields($result); $i < $count; $i++) { printf("%d:%s\n", $i, pg_field_name($result, $i)); }

0:order_no
1:total

Граница i < count не передаёт несуществующий номер в pg_field_name. Такая схема нужна генератору CSV/таблицы, когда SELECT известен только во время выполнения. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, "SELECT * FROM (VALUES ('new'), ('paid')) AS o(status)");
echo pg_num_rows($result), "\n";

2

Число относится к уже полученному PgSql\Result и не выполняет отдельный SELECT count(*). Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, 'SELECT n, count(*) OVER () AS total FROM generate_series(1, 5) AS n ORDER BY n LIMIT 2');
$first = pg_fetch_assoc($result, 0);
printf("page=%d, total=%s\n", pg_num_rows($result), $first['total']);

page=2, total=5

pg_num_rows видит две строки после LIMIT, а window count сообщает пять подходящих строк. Для интерфейса пагинации эти числа отвечают на разные вопросы. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, "SELECT * FROM (VALUES ('A'), ('B'), ('C')) AS x(code)");
var_dump(pg_result_seek($result, 2));
echo pg_fetch_result($result, null, 'code'), "\n";

bool(true)
C

Номер 2 — третья строка. Следующий fetch без явного номера читает с новой внутренней позиции. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, 'SELECT n FROM generate_series(1, 2) AS n ORDER BY n');
pg_fetch_row($result);
pg_fetch_row($result);
pg_result_seek($result, 0);
echo pg_fetch_result($result, null, 0), "\n";
var_dump(pg_result_seek($result, pg_num_rows($result)));

1
bool(false)

Seek можно применить только к уже буферизованным строкам этого результата. Позиция, равная count, находится за последней строкой и возвращает false. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, 'SELECT n FROM generate_series(1, 2) AS n');
$status = pg_result_status($result);
$tag = pg_result_status($result, PGSQL_STATUS_STRING);
echo $status === PGSQL_TUPLES_OK ? 'TUPLES' : 'OTHER', '|', $tag, "\n";

TUPLES|SELECT 2

LONG возвращает константу для ветвления, STRING — командный tag сервера. Строка SELECT 2 содержит тип команды и число строк, но для количества в коде яснее pg_num_rows. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE status_jobs (id integer PRIMARY KEY, done boolean)');
pg_query($db, 'INSERT INTO status_jobs VALUES (1, false), (2, false)');
$result = pg_query($db, 'UPDATE status_jobs SET done=true WHERE id=2');
printf("%s|%s|affected=%d\n", pg_result_status($result) === PGSQL_COMMAND_OK ? 'COMMAND' : 'OTHER', pg_result_status($result, PGSQL_STATUS_STRING), pg_affected_rows($result));

COMMAND|UPDATE 1|affected=1

COMMAND_OK подтверждает класс успеха, а affected rows — ожидаемый масштаб. Успешный SQL ещё не доказывает бизнес-право или правильность выбранного WHERE. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, 'SELECT 42 AS answer');
var_dump(pg_result_error($result) === '');

bool(true)

Пустая строка означает, что с этим PgSql\Result не связано сообщение ошибки. Это не то же самое, что false от функции при невозможности прочитать результат. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$clean = false;
try {
    $socket = pg_socket($db);
    if ($socket === false) { throw new RuntimeException('Нет сокета'); }
    $deadline = hrtime(true) + 3_000_000_000;
    if (!pg_send_query($db, 'SELECT 1 / 0')) { throw new RuntimeException('Запрос не принят'); }
    $flushed = pg_flush($db);
    if ($flushed === false) { throw new RuntimeException('Ошибка начала отправки'); }
    while ($flushed === 0) {
        $remainingMs = (int) ceil(($deadline - hrtime(true)) / 1_000_000);
        if ($remainingMs <= 0) { throw new RuntimeException('Таймаут отправки'); }
        $ready = pg_socket_poll($socket, 0, 1, $remainingMs);
        if ($ready < 0) { throw new RuntimeException('Ошибка ожидания записи'); }
        if ($ready === 0) { usleep(10_000); continue; }
        $flushed = pg_flush($db);
        if ($flushed === false) { throw new RuntimeException('Ошибка досылки'); }
    }
    while (pg_connection_busy($db)) {
        $remainingMs = (int) ceil(($deadline - hrtime(true)) / 1_000_000);
        if ($remainingMs <= 0) { throw new RuntimeException('Таймаут ответа'); }
        $ready = pg_socket_poll($socket, 1, 0, $remainingMs);
        if ($ready < 0) { throw new RuntimeException('Ошибка ожидания чтения'); }
        if ($ready === 0) { usleep(10_000); continue; }
        if (!pg_consume_input($db)) { throw new RuntimeException('Ошибка чтения libpq'); }
    }
    $result = pg_get_result($db);
    if (!$result instanceof PgSql\Result || pg_result_status($result) !== PGSQL_FATAL_ERROR) {
        throw new RuntimeException('Не получен failed result');
    }
    while (pg_get_result($db) instanceof PgSql\Result) {}
    $clean = true;
    $message = pg_result_error($result);
    $state = pg_result_error_field($result, PGSQL_DIAG_SQLSTATE);
    echo is_string($message) && $message !== '' && $state === '22012' ? "Ошибка деления сохранена\n" : "Нет сообщения\n";
} finally {
    if (!$clean) { @pg_close($db); }
}

Ошибка деления сохранена

Синхронный pg_query при SQL-ошибке возвращает false и уничтожает PGresult, поэтому для привязанной диагностики нужен pg_send_query + pg_get_result. Отправка и чтение имеют общий монотонный deadline; ранний 0 poll повторяется, -1 прерывает ожидание, очередь результатов дочитывается, а uncertain connection закрывается. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$clean = false;
try {
    $socket = pg_socket($db);
    if ($socket === false) { throw new RuntimeException('Нет сокета'); }
    $deadline = hrtime(true) + 3_000_000_000;
    if (!pg_send_query($db, 'SELECT 1 / 0')) { throw new RuntimeException('Запрос не принят'); }
    $flushed = pg_flush($db);
    if ($flushed === false) { throw new RuntimeException('Ошибка начала отправки'); }
    while ($flushed === 0) {
        $remainingMs = (int) ceil(($deadline - hrtime(true)) / 1_000_000);
        if ($remainingMs <= 0) { throw new RuntimeException('Таймаут отправки'); }
        $ready = pg_socket_poll($socket, 0, 1, $remainingMs);
        if ($ready < 0) { throw new RuntimeException('Ошибка ожидания записи'); }
        if ($ready === 0) { usleep(10_000); continue; }
        $flushed = pg_flush($db);
        if ($flushed === false) { throw new RuntimeException('Ошибка досылки'); }
    }
    while (pg_connection_busy($db)) {
        $remainingMs = (int) ceil(($deadline - hrtime(true)) / 1_000_000);
        if ($remainingMs <= 0) { throw new RuntimeException('Таймаут ответа'); }
        $ready = pg_socket_poll($socket, 1, 0, $remainingMs);
        if ($ready < 0) { throw new RuntimeException('Ошибка ожидания чтения'); }
        if ($ready === 0) { usleep(10_000); continue; }
        if (!pg_consume_input($db)) { throw new RuntimeException('Ошибка чтения libpq'); }
    }
    $result = pg_get_result($db);
    if (!$result instanceof PgSql\Result || pg_result_status($result) !== PGSQL_FATAL_ERROR) {
        throw new RuntimeException('Не получен failed result');
    }
    while (pg_get_result($db) instanceof PgSql\Result) {}
    $clean = true;
    $state = pg_result_error_field($result, PGSQL_DIAG_SQLSTATE);
    $message = pg_result_error_field($result, PGSQL_DIAG_MESSAGE_PRIMARY);
    echo $state, '|message=', is_string($message) && $message !== '' ? 'yes' : 'no', "\n";
} finally {
    if (!$clean) { @pg_close($db); }
}

22012|message=yes

SQLSTATE 22012 предназначен для программного решения. Основное сообщение только проверяется на наличие. Один монотонный deadline ограничивает send/read; очередь полностью снимается, а соединение с неподтверждённой синхронизацией закрывается. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE diag_products (sku text PRIMARY KEY)');
pg_query($db, "INSERT INTO diag_products VALUES ('PEN-01')");
$clean = false;
try {
    $socket = pg_socket($db);
    if ($socket === false) { throw new RuntimeException('Нет сокета'); }
    $deadline = hrtime(true) + 3_000_000_000;
    if (!pg_send_query($db, "INSERT INTO diag_products VALUES ('PEN-01')")) { throw new RuntimeException('Запрос не принят'); }
    $flushed = pg_flush($db);
    if ($flushed === false) { throw new RuntimeException('Ошибка начала отправки'); }
    while ($flushed === 0) {
        $remainingMs = (int) ceil(($deadline - hrtime(true)) / 1_000_000);
        if ($remainingMs <= 0) { throw new RuntimeException('Таймаут отправки'); }
        $ready = pg_socket_poll($socket, 0, 1, $remainingMs);
        if ($ready < 0) { throw new RuntimeException('Ошибка ожидания записи'); }
        if ($ready === 0) { usleep(10_000); continue; }
        $flushed = pg_flush($db);
        if ($flushed === false) { throw new RuntimeException('Ошибка досылки'); }
    }
    while (pg_connection_busy($db)) {
        $remainingMs = (int) ceil(($deadline - hrtime(true)) / 1_000_000);
        if ($remainingMs <= 0) { throw new RuntimeException('Таймаут ответа'); }
        $ready = pg_socket_poll($socket, 1, 0, $remainingMs);
        if ($ready < 0) { throw new RuntimeException('Ошибка ожидания чтения'); }
        if ($ready === 0) { usleep(10_000); continue; }
        if (!pg_consume_input($db)) { throw new RuntimeException('Ошибка чтения libpq'); }
    }
    $result = pg_get_result($db);
    if (!$result instanceof PgSql\Result || pg_result_status($result) !== PGSQL_FATAL_ERROR) {
        throw new RuntimeException('Не получен failed result');
    }
    while (pg_get_result($db) instanceof PgSql\Result) {}
    $clean = true;
    $state = pg_result_error_field($result, PGSQL_DIAG_SQLSTATE);
    $detail = pg_result_error_field($result, PGSQL_DIAG_MESSAGE_DETAIL);
    printf("state=%s, detail=%s\n", $state, is_string($detail) && $detail !== '' ? 'yes' : 'no');
} finally {
    if (!$clean) { @pg_close($db); }
}

state=23505, detail=yes

23505 стабильно позволяет вернуть ответ «артикул уже существует». DETAIL лишь проверяется на наличие. Общий deadline и полный drain сохраняют протокольную границу; если это не удалось, соединение закрывается вместо повторного использования. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
@pg_query($db, 'SELECT * FROM manual_missing_results_table');
$message = pg_last_error($db);
echo $message !== '' ? "Сообщение получено\n" : "Сообщения нет\n";

Сообщение получено

Функция полезна после синхронного pg_query=false, когда объекта результата нет. В лог добавляют контекст операции, но не показывают сырой SQL/ошибку посетителю. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
@pg_query($db, 'SELECT * FROM manual_missing_results_table');
$saved = pg_last_error($db);
pg_query($db, 'SELECT 1');
$now = pg_last_error($db);
printf("saved=%s, now=%s\n", $saved !== '' ? 'yes' : 'no', $now === '' ? 'empty' : 'present');

saved=yes, now=empty

Успешный следующий запрос очистил последнее сообщение. Поэтому pg_last_error — изменяемый снимок соединения; сохраните его сразу или предпочитайте diagnostics конкретного result. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_last_notice($db, PGSQL_NOTICE_CLEAR);
pg_query($db, "DO $$ BEGIN RAISE NOTICE 'manual-ready'; END $$;");
$notice = pg_last_notice($db);
echo str_contains($notice, 'manual-ready') ? "NOTICE получен\n" : "NOTICE потерян\n";

NOTICE получен

NOTICE не является SQL-ошибкой: команда DO завершилась. Его можно записать для диагностики миграции, но не считать автоматическим отказом операции. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_last_notice($db, PGSQL_NOTICE_CLEAR);
pg_query($db, "DO $$ BEGIN RAISE NOTICE 'one'; RAISE NOTICE 'two'; END $$;");
$all = pg_last_notice($db, PGSQL_NOTICE_ALL);
$cleared = pg_last_notice($db, PGSQL_NOTICE_CLEAR);
$after = pg_last_notice($db, PGSQL_NOTICE_ALL);
printf("before=%d, cleared=%s, after=%d\n", count($all), $cleared ? 'yes' : 'no', count($after));

before=2, cleared=yes, after=0

В долгом процессе очередь иначе накапливается. Доступность сообщений зависит от pgsql.ignore_notice; приложение не должно строить обязательную бизнес-логику только на NOTICE. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, 'SELECT n FROM generate_series(1, 3) AS n');
echo pg_num_rows($result), " rows\n";
var_dump(pg_free_result($result));
try { pg_num_rows($result); } catch (Error $error) { echo "Результат уже закрыт\n"; }

3 rows
bool(true)
Результат уже закрыт

После освобождения тот же объект нельзя читать. В коротком запросе PHP освободит его автоматически; явный free нужен, когда большой результат больше не нужен, а процесс продолжает жить. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$freed = 0;
for ($batch = 1; $batch <= 3; $batch++) {
    $result = pg_query_params($db, 'SELECT repeat($1, 1000)', [(string) $batch]);
    pg_fetch_result($result, 0, 0);
    if (pg_free_result($result)) { $freed++; }
}
echo $freed, " results freed\n";

3 results freed

В queue worker результат каждого batch освобождается до следующего. Это не отменяет необходимости ограничивать размер SQL-выборки и измерять память процесса. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, 'SELECT n FROM generate_series(1, 10) AS n');
if (!function_exists('pg_result_memory_size')) { echo "pg_result_memory_size недоступна в этой DLL\n"; }
else { echo pg_result_memory_size($result), " bytes\n"; }

pg_result_memory_size недоступна в этой DLL

Стенд использует PHP 8.5.11 и libpq 16.15, но Windows php_pgsql.dll собрана без HAVE_PG_RESULT_MEMORY_SIZE. Версия PHP/сервера сама по себе не гарантирует capability. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, "SELECT repeat('x', 1000) FROM generate_series(1, 5)");
if (function_exists('pg_result_memory_size')) { echo 'measured=', pg_result_memory_size($result), "\n"; }
else { echo "measurement unavailable\n"; }
pg_free_result($result);
echo "result freed\n";

measurement unavailable
result freed

Отсутствие метрики не мешает управлять жизненным циклом. memory_get_usage не является эквивалентом: часть PGresult выделена libpq вне обычного учёта Zend memory manager. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$jit = pg_jit($db);
printf("provider=%s, jit=%s\n", $jit['jit_provider'] ?? 'none', $jit['jit'] ?? 'unknown');

provider=none, jit=on

Локальный PostgreSQL сообщает jit=on, но jit_provider=null: бинарная сборка не предоставляет provider. Значение on — настройка, а не доказательство, что конкретный запрос компилировался JIT. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$before = pg_jit($db)['jit'] ?? 'on';
pg_query($db, 'SET jit TO off');
$jit = pg_jit($db);
echo $jit['jit'], "\n";
pg_query($db, 'SET jit TO ' . ($before === 'off' ? 'off' : 'on'));

off

Пример возвращает прежнее значение после проверки. Не вызываем pg_jit внутри открытой транзакции на этой сборке: внутренний SHOW jit_provider не поддержан и способен перевести transaction block в INERROR. Отключать JIT глобально по одному примеру нельзя: решение принимают по EXPLAIN и нагрузочным измерениям. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
echo pg_transaction_status($db) === PGSQL_TRANSACTION_IDLE ? "IDLE\n" : "OTHER\n";
pg_query($db, 'BEGIN');
echo pg_transaction_status($db) === PGSQL_TRANSACTION_INTRANS ? "INTRANS\n" : "OTHER\n";
pg_query($db, 'ROLLBACK');

IDLE
INTRANS

После BEGIN соединение находится в исправном transaction block. В конце примера rollback возвращает bootstrap-соединение в чистое состояние. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'BEGIN');
@pg_query($db, 'SELECT * FROM manual_missing_tx_table');
echo pg_transaction_status($db) === PGSQL_TRANSACTION_INERROR ? "INERROR\n" : "OTHER\n";
pg_query($db, 'ROLLBACK');
echo pg_transaction_status($db) === PGSQL_TRANSACTION_IDLE ? "IDLE\n" : "OTHER\n";

INERROR
IDLE

В INERROR обычные команды будут отклоняться до ROLLBACK или ROLLBACK TO SAVEPOINT. Живое PGSQL_CONNECTION_OK не означает пригодную транзакцию. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE oid_orders (id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY)');
$result = pg_query($db, 'INSERT INTO oid_orders DEFAULT VALUES');
var_dump(pg_last_oid($result));
echo pg_result_status($result, PGSQL_STATUS_STRING), "\n";

bool(false)
INSERT 0 1

Современная таблица не имеет WITH OIDS, поэтому false ожидаем. Command tag подтверждает вставку, но не сообщает identity id. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE returning_orders (id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY, label text)');
$result = pg_query_params($db, 'INSERT INTO returning_orders (label) VALUES ($1) RETURNING id', ['first']);
var_dump(pg_last_oid($result));
$id = pg_fetch_result($result, 0, 'id');
echo "id={$id}\n";

bool(false)
id=1

Тот же result на современной identity-таблице даёт false из pg_last_oid, но содержит id через RETURNING. RETURNING связан именно с этой вставленной строкой, не зависит от имени sequence и служит современной заменой row OID. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$socket = pg_socket($db);
if ($socket === false) { throw new RuntimeException('Нет сокета'); }
$deadline = microtime(true) + 3.0;
$sent = pg_send_query($db, 'SELECT pg_sleep(0.05), 42 AS answer');
if ($sent === false) { throw new RuntimeException('Запрос не принят libpq'); }
$flushed = pg_flush($db);
if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка начальной отправки; соединение закрыто'); }
while ($flushed === 0) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут записи; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 0, 1, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания записи; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); continue; }
    $flushed = pg_flush($db);
    if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка досылки; соединение закрыто'); }
}
echo pg_connection_busy($db) ? "Занято\n" : "Уже готово\n";
while (pg_connection_busy($db)) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут ответа; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 1, 0, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания чтения; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); }
}
$result = pg_get_result($db);
if (!$result instanceof PgSql\Result) { throw new RuntimeException('Нет результата'); }
echo pg_connection_busy($db) ? "Занято\n" : "Свободно\n";
echo pg_fetch_result($result, 0, 'answer'), "\n";

Занято
Свободно
42

Состояние busy относится к одному соединению: пока сервер считает предыдущий запрос, новое действие на этом же $db отправлять нельзя. На проверенной Windows/libpq-связке pg_socket_poll способен немедленно вернуть 0 ещё до готовности, поэтому 0 повторяет ожидание с короткой паузой, а таймаут определяет один общий deadline. При таймауте или ошибке poll соединение закрывается: оставлять в пуле сессию с недочитанным протоколом нельзя. На очень быстром запросе первый статус может уже оказаться «готово», поэтому для демонстрации используется короткий pg_sleep. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$socket = pg_socket($db);
if ($socket === false) { throw new RuntimeException('Нет сокета'); }
$deadline = microtime(true) + 3.0;
$sent = pg_send_query($db, 'SELECT pg_sleep(0.03)');
if ($sent === false) { throw new RuntimeException('Запрос не принят'); }
$flushed = pg_flush($db);
if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка начальной отправки; соединение закрыто'); }
while ($flushed === 0) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут записи; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 0, 1, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания записи; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); continue; }
    $flushed = pg_flush($db);
    if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка досылки; соединение закрыто'); }
}
if (pg_connection_busy($db)) { echo "Сначала дочитаем первый результат\n"; }
while (pg_connection_busy($db)) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут ответа; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 1, 0, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания чтения; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); }
}
while (pg_get_result($db) instanceof PgSql\Result) {}

Сначала дочитаем первый результат

Проверка не ускоряет запрос, а защищает протокол. Если отправить новый запрос в занятое соединение, ext/pgsql может ждать предыдущий и отбросить его непрочитанные результаты. Нулевой pg_socket_poll на Windows/libpq не считается окончательным таймаутом: цикл повторяет его до общего deadline; -1 остаётся немедленной ошибкой. При ошибке ожидания или исчерпании deadline пример закрывает сессию с неопределённым состоянием протокола. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$socket = pg_socket($db);
if ($socket === false) { throw new RuntimeException('Нет сокета'); }
$deadline = microtime(true) + 3.0;
$sent = pg_send_query($db, 'SELECT pg_sleep(0.03), 7 AS value');
if ($sent === false) { throw new RuntimeException('Запрос не принят'); }
$flushed = pg_flush($db);
if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка начальной отправки; соединение закрыто'); }
while ($flushed === 0) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут записи; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 0, 1, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания записи; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); continue; }
    $flushed = pg_flush($db);
    if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка досылки; соединение закрыто'); }
}
while (true) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут ответа; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 1, 0, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания чтения; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); continue; }
    if (!pg_consume_input($db)) { pg_close($db); throw new RuntimeException('Соединение не прочитано; соединение закрыто'); }
    if (!pg_connection_busy($db)) { break; }
}
$result = pg_get_result($db);
echo pg_fetch_result($result, 0, 'value'), "\n";

7

true от pg_consume_input означает отсутствие ошибки чтения, а не наличие полного результата. Готовность определяет pg_connection_busy, а сам результат возвращает pg_get_result. Проверенная Windows/libpq-связка иногда возвращает из pg_socket_poll ранний 0; код повторяет ожидание с паузой и завершает его только по общему deadline. При таймауте или ошибке чтения соединение закрывается, чтобы недочитанный ответ не попал в следующий запрос. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$socket = pg_socket($db);
if ($socket === false) { throw new RuntimeException('Нет сокета'); }
$deadline = microtime(true) + 3.0;
$sent = pg_send_query($db, 'SELECT 9 AS value');
if ($sent === false) { throw new RuntimeException('Запрос не принят'); }
$flushed = pg_flush($db);
if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка начальной отправки; соединение закрыто'); }
while ($flushed === 0) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут записи; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 0, 1, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания записи; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); continue; }
    $flushed = pg_flush($db);
    if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка досылки; соединение закрыто'); }
}
while (true) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут ответа; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 1, 0, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания чтения; соединение закрыто'); }
    if ($ready > 0) { break; }
    usleep(10_000);
}
$ok = pg_consume_input($db);
var_dump($ok);
while (pg_connection_busy($db)) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут ответа; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 1, 0, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания чтения; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); continue; }
    if (!pg_consume_input($db)) { pg_close($db); throw new RuntimeException('Не удалось дочитать ответ; соединение закрыто'); }
}
$result = pg_get_result($db);
echo pg_fetch_result($result, 0, 'value'), "\n";

bool(true)
9

true подтверждает только отсутствие ошибки чтения уже доступных байтов. Пример отдельно проверяет busy, дочитывает ответ и лишь затем получает значение из PgSql\Result. Ранний 0 от pg_socket_poll на Windows/libpq повторяется до общего deadline; только -1 немедленно означает ошибку ожидания. При таймауте или ошибке сессия закрывается, потому что её очередь уже нельзя считать чистой. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$payload = str_repeat('x', 2_000_000);
$socket = pg_socket($db);
if ($socket === false) { throw new RuntimeException('Нет сокета'); }
$deadline = microtime(true) + 5.0;
$sent = pg_send_query_params($db, 'SELECT length($1::text) AS bytes', [$payload]);
if ($sent === false) { throw new RuntimeException('Не принято libpq'); }
$flushed = pg_flush($db);
if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка начальной отправки; соединение закрыто'); }
while ($flushed === 0) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут записи; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 0, 1, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания записи; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); continue; }
    $flushed = pg_flush($db);
    if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка досылки; соединение закрыто'); }
}
while (pg_connection_busy($db)) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут ответа; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 1, 0, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания чтения; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); }
}
$result = pg_get_result($db);
echo pg_fetch_result($result, 0, 'bytes'), "\n";

2000000

На loopback весь буфер часто отправляется сразу, но цикл учитывает и 0: часть данных ушла, часть ещё ждёт. Значение 0 сравнивается строго, потому что оно ложно в обычном if. На Windows/libpq сам pg_socket_poll также способен вернуть ранний 0; он повторяется с паузой, а предел всех стадий задаёт один deadline. Таймаут или ошибка закрывают соединение с частично отправленным либо недочитанным протоколом. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$flushed = pg_flush($db);
var_dump($flushed);

bool(true)

true также означает, что отправлять было нечего. Это не результат SQL и не число строк; SQL-результат всё равно получают через pg_get_result. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$socket = pg_socket($db);
if ($socket === false) { throw new RuntimeException('Нет сокета'); }
$deadline = microtime(true) + 3.0;
$sent = pg_send_query($db, 'SELECT 10 AS value; SELECT 20 AS value');
if ($sent === false) { throw new RuntimeException('Не принято libpq'); }
$flushed = pg_flush($db);
if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка начальной отправки; соединение закрыто'); }
while ($flushed === 0) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут записи; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 0, 1, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания записи; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); continue; }
    $flushed = pg_flush($db);
    if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка досылки; соединение закрыто'); }
}
$values = [];
while (($result = pg_get_result($db)) instanceof PgSql\Result) {
    if (pg_result_status($result) !== PGSQL_TUPLES_OK) { throw new RuntimeException(pg_result_error($result)); }
    $values[] = pg_fetch_result($result, 0, 'value');
}
echo implode(',', $values), "\n";

10,20

pg_send_query допускает несколько постоянных команд, а pg_get_result возвращает их результаты по одному. Цикл до false обязателен: непрочитанный результат ломает следующую операцию на соединении. На Windows/libpq ранний 0 от pg_socket_poll означает «ещё не готово»: пример повторяет ожидание с короткой паузой до одного общего deadline, отдельно обрабатывает -1 и закрывает соединение, если его состояние стало неопределённым. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$socket = pg_socket($db);
if ($socket === false) { throw new RuntimeException('Нет сокета'); }
$deadline = microtime(true) + 3.0;
$sent = pg_send_query($db, 'SELECT missing_column FROM missing_table');
if ($sent === false) { throw new RuntimeException('Не принято libpq'); }
$flushed = pg_flush($db);
if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка начальной отправки; соединение закрыто'); }
while ($flushed === 0) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут записи; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 0, 1, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания записи; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); continue; }
    $flushed = pg_flush($db);
    if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка досылки; соединение закрыто'); }
}
$result = pg_get_result($db);
if ($result instanceof PgSql\Result) {
    echo pg_result_status($result) === PGSQL_FATAL_ERROR ? "SQL отклонён\n" : "Другой статус\n";
}
var_dump(pg_get_result($db));

SQL отклонён
bool(false)

SQL-ошибка приходит как объект PgSql\Result со статусом PGSQL_FATAL_ERROR. false означает только, что очередь результатов закончилась; путать эти состояния нельзя. Ранний 0 от pg_socket_poll на Windows/libpq повторяет ожидание до общего deadline; -1 немедленно считается ошибкой. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$socket = pg_socket($db);
if ($socket === false) { throw new RuntimeException('Нет сокета'); }
$deadline = microtime(true) + 3.0;
$sent = pg_send_query($db, 'SELECT pg_sleep(0.03), 6 * 7 AS answer');
if ($sent === false) { throw new RuntimeException('Не принято libpq'); }
$flushed = pg_flush($db);
if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка начальной отправки; соединение закрыто'); }
while ($flushed === 0) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут записи; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 0, 1, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания записи; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); continue; }
    $flushed = pg_flush($db);
    if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка досылки; соединение закрыто'); }
}
$label = strtoupper('report');
while (pg_connection_busy($db)) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут ответа; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 1, 0, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания чтения; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); }
}
$result = pg_get_result($db);
echo $label, ':', pg_fetch_result($result, 0, 'answer'), "\n";

REPORT:42

Асинхронность полезна, только если PHP действительно делает независимую работу или обслуживает другие события. Последовательный busy-loop сам по себе не ускоряет запрос. На Windows/libpq ранний 0 от poll означает «пока не готово», поэтому ожидание повторяется до общего deadline, а -1 обрабатывается отдельно как ошибка. При таймауте или ошибке ожидания пример закрывает соединение, чтобы незавершённый ответ не загрязнил следующую операцию. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$socket = pg_socket($db);
if ($socket === false) { throw new RuntimeException('Нет сокета'); }
$deadline = microtime(true) + 3.0;
$sent = pg_send_query($db, 'SELECT 1 AS step; SELECT 2 AS step');
if ($sent === false) { throw new RuntimeException('Не принято libpq'); }
$flushed = pg_flush($db);
if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка начальной отправки; соединение закрыто'); }
while ($flushed === 0) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут записи; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 0, 1, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания записи; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); continue; }
    $flushed = pg_flush($db);
    if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка досылки; соединение закрыто'); }
}
$steps = [];
while (($result = pg_get_result($db)) instanceof PgSql\Result) {
    $steps[] = pg_fetch_result($result, 0, 'step');
}
echo implode(' -> ', $steps), "\n";

1 -> 2

Несколько команд допустимы здесь только для заранее заданного программой SQL. Для внешних значений используйте pg_send_query_params, который принимает одну команду и параметры отдельно. На Windows/libpq ранний 0 от poll повторяет ожидание до общего deadline; -1 означает ошибку ожидания. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$socket = pg_socket($db);
if ($socket === false) { throw new RuntimeException('Нет сокета'); }
$deadline = microtime(true) + 3.0;
$value = "x'); SELECT pg_sleep(10); --";
$sent = pg_send_query_params($db, 'SELECT $1::text AS value', [$value]);
if ($sent === false) { throw new RuntimeException('Не принято libpq'); }
$flushed = pg_flush($db);
if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка начальной отправки; соединение закрыто'); }
while ($flushed === 0) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут записи; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 0, 1, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания записи; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); continue; }
    $flushed = pg_flush($db);
    if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка досылки; соединение закрыто'); }
}
$result = pg_get_result($db);
echo pg_fetch_result($result, 0, 'value'), "\n";
while (pg_get_result($db) instanceof PgSql\Result) {}

x'); SELECT pg_sleep(10); --

Сервер получает одну SQL-команду и отдельное значение; вложенный текст не исполняется. Асинхронный вариант сохраняет ту же границу параметров, что pg_query_params. Ранний 0 от pg_socket_poll на Windows/libpq означает «пока не готово», поэтому код повторяет ожидание до общего deadline. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$socket = pg_socket($db);
if ($socket === false) { throw new RuntimeException('Нет сокета'); }
$deadline = microtime(true) + 3.0;
$sent = pg_send_query_params($db, 'SELECT $1::integer AS qty', ['twelve']);
if ($sent === false) { throw new RuntimeException('Не принято libpq'); }
$flushed = pg_flush($db);
if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка начальной отправки; соединение закрыто'); }
while ($flushed === 0) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут записи; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 0, 1, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания записи; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); continue; }
    $flushed = pg_flush($db);
    if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка досылки; соединение закрыто'); }
}
var_dump($sent === true);
$result = pg_get_result($db);
echo pg_result_status($result) === PGSQL_FATAL_ERROR ? "Значение отклонено сервером\n" : "Неожиданный статус\n";

bool(true)
Значение отклонено сервером

Успешная отправка не гарантирует успешный SQL. Несовместимый integer обнаруживается сервером позже и виден в PgSql\Result. Windows/libpq может рано вернуть 0 из pg_socket_poll; это повтор ожидания до общего deadline, тогда как -1 — немедленная ошибка. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$socket = pg_socket($db);
if ($socket === false) { throw new RuntimeException('Нет сокета'); }
$deadline = microtime(true) + 3.0;
$sent = pg_send_prepare($db, 'async_double', 'SELECT $1::integer * 2 AS value');
if ($sent === false) { throw new RuntimeException('Prepare не принят'); }
$flushed = pg_flush($db);
if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка начальной отправки; соединение закрыто'); }
while ($flushed === 0) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут записи; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 0, 1, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания записи; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); continue; }
    $flushed = pg_flush($db);
    if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка досылки; соединение закрыто'); }
}
$result = pg_get_result($db);
echo pg_result_status($result) === PGSQL_COMMAND_OK ? "Подготовлено\n" : "Ошибка\n";

Подготовлено

Возвращаемое значение отправки подтверждает только протокол; PGSQL_COMMAND_OK в полученном результате подтверждает, что сервер создал statement. Ранний 0 от pg_socket_poll на Windows/libpq повторяется до общего deadline; -1 немедленно завершает ожидание ошибкой. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_prepare($db, 'async_duplicate', 'SELECT 1');
$socket = pg_socket($db);
if ($socket === false) { throw new RuntimeException('Нет сокета'); }
$deadline = microtime(true) + 3.0;
$sent = pg_send_prepare($db, 'async_duplicate', 'SELECT 2');
if ($sent === false) { throw new RuntimeException('Prepare не принят'); }
$flushed = pg_flush($db);
if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка начальной отправки; соединение закрыто'); }
while ($flushed === 0) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут записи; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 0, 1, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания записи; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); continue; }
    $flushed = pg_flush($db);
    if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка досылки; соединение закрыто'); }
}
var_dump($sent === true);
$result = pg_get_result($db);
echo pg_result_status($result) === PGSQL_FATAL_ERROR ? "Имя уже занято\n" : "Неожиданный статус\n";

bool(true)
Имя уже занято

Отправка прошла, но сервер отклонил повтор statement_name. Это наглядно разделяет транспортный успех и результат операции. Ранний 0 от poll на Windows/libpq — повод повторить ожидание до общего deadline, а не объявлять таймаут. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_prepare($db, 'async_total', 'SELECT $1::integer + $2::integer AS total');
$socket = pg_socket($db);
if ($socket === false) { throw new RuntimeException('Нет сокета'); }
$deadline = microtime(true) + 3.0;
$sent = pg_send_execute($db, 'async_total', [20, 22]);
if ($sent === false) { throw new RuntimeException('Execute не принят'); }
$flushed = pg_flush($db);
if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка начальной отправки; соединение закрыто'); }
while ($flushed === 0) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут записи; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 0, 1, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания записи; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); continue; }
    $flushed = pg_flush($db);
    if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка досылки; соединение закрыто'); }
}
$result = pg_get_result($db);
echo pg_fetch_result($result, 0, 'total'), "\n";

42

Statement подготовлена на том же соединении. Значения меняются при каждом execute; SQL повторно не передаётся. На Windows/libpq ранний 0 от pg_socket_poll повторяется с паузой до общего deadline; -1 считается ошибкой. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$socket = pg_socket($db);
if ($socket === false) { throw new RuntimeException('Нет сокета'); }
$deadline = microtime(true) + 3.0;
$sent = pg_send_execute($db, 'not_prepared_here', [1]);
if ($sent === false) { throw new RuntimeException('Execute не принят'); }
$flushed = pg_flush($db);
if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка начальной отправки; соединение закрыто'); }
while ($flushed === 0) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут записи; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 0, 1, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания записи; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); continue; }
    $flushed = pg_flush($db);
    if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка досылки; соединение закрыто'); }
}
var_dump($sent === true);
$result = pg_get_result($db);
echo pg_result_status($result) === PGSQL_FATAL_ERROR ? "Statement не найдена\n" : "Неожиданный статус\n";

bool(true)
Statement не найдена

И здесь dispatch может пройти успешно, а ошибка обнаружится сервером. Prepared statements живут в конкретной сессии и не появляются автоматически в другом соединении. Ранний 0 от poll на Windows/libpq повторяет ожидание до общего deadline; -1 завершает его немедленно. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
if (!function_exists('pg_set_chunked_rows_size')) {
    echo "Нужна PHP-сборка с libpq 17+\n";
    return;
}
$socket = pg_socket($db);
if ($socket === false) { throw new RuntimeException('Нет сокета'); }
$deadline = microtime(true) + 3.0;
$sent = pg_send_query($db, 'SELECT generate_series(1, 5) AS id');
if ($sent === false) { throw new RuntimeException('Запрос не принят'); }
$flushed = pg_flush($db);
if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка начальной отправки; соединение закрыто'); }
while ($flushed === 0) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут записи; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 0, 1, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания записи; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); continue; }
    $flushed = pg_flush($db);
    if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка досылки; соединение закрыто'); }
}
if (!pg_set_chunked_rows_size($db, 2)) {
    pg_close($db);
    throw new RuntimeException('Chunk mode не включён; соединение закрыто');
}
$sizes = [];
$ids = [];
$finalReceived = false;
$error = null;
while (true) {
    while (pg_connection_busy($db)) {
        $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
        if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут ответа; соединение закрыто'); }
        $ready = pg_socket_poll($socket, 1, 0, $remainingMs);
        if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания чтения; соединение закрыто'); }
        if ($ready === 0) { usleep(10_000); }
    }
    $chunk = pg_get_result($db);
    if (!$chunk instanceof PgSql\Result) { break; }
    $status = pg_result_status($chunk);
    if ($status === PGSQL_TUPLES_CHUNK) {
        $sizes[] = pg_num_rows($chunk);
        foreach (pg_fetch_all($chunk) ?: [] as $row) { $ids[] = $row['id']; }
    } elseif ($status === PGSQL_TUPLES_OK && pg_num_rows($chunk) === 0) {
        $finalReceived = true;
    } elseif ($status === PGSQL_FATAL_ERROR) {
        $error = pg_result_error($chunk) ?: 'PostgreSQL отклонил запрос';
    } else {
        $error = 'Неожиданный статус chunk-результата';
    }
}
if ($error !== null) { throw new RuntimeException($error); }
if (!$finalReceived) { throw new RuntimeException('Нет финального пустого PGSQL_TUPLES_OK'); }
echo implode(',', $sizes), "\n";

Нужна PHP-сборка с libpq 17+

На текущем стенде честно выполняется capability-ветка: php_pgsql.dll связана с libpq 16.15. На libpq 17+ код включает режим строго после pg_send_query и до первого pg_get_result. Прикладные строки принимаются только из PGSQL_TUPLES_CHUNK; финальный пустой PGSQL_TUPLES_OK подтверждает полное завершение. Ошибка запоминается, вся очередь дочитывается, и лишь затем код публикует размеры 2,2,1. Ранний 0 от pg_socket_poll на Windows/libpq повторяется до общего deadline; -1 немедленно считается ошибкой. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
if (!function_exists('pg_set_chunked_rows_size')) {
    echo "Нужна PHP-сборка с libpq 17+\n";
    return;
}
$socket = pg_socket($db);
if ($socket === false) { throw new RuntimeException('Нет сокета'); }
$deadline = microtime(true) + 3.0;
$sent = pg_send_query($db, 'SELECT generate_series(1, 3) AS id');
if ($sent === false) { throw new RuntimeException('Запрос не принят'); }
$flushed = pg_flush($db);
if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка начальной отправки; соединение закрыто'); }
while ($flushed === 0) {
    $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
    if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут записи; соединение закрыто'); }
    $ready = pg_socket_poll($socket, 0, 1, $remainingMs);
    if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания записи; соединение закрыто'); }
    if ($ready === 0) { usleep(10_000); continue; }
    $flushed = pg_flush($db);
    if ($flushed === false) { pg_close($db); throw new RuntimeException('Ошибка досылки; соединение закрыто'); }
}
if (!pg_set_chunked_rows_size($db, 1)) {
    pg_close($db);
    throw new RuntimeException('Chunk mode не включён; соединение закрыто');
}
$firstSize = null;
$lateChange = null;
$finalReceived = false;
$error = null;
while (true) {
    while (pg_connection_busy($db)) {
        $remainingMs = (int) ceil(($deadline - microtime(true)) * 1000);
        if ($remainingMs <= 0) { pg_close($db); throw new RuntimeException('Таймаут ответа; соединение закрыто'); }
        $ready = pg_socket_poll($socket, 1, 0, $remainingMs);
        if ($ready < 0) { pg_close($db); throw new RuntimeException('Ошибка ожидания чтения; соединение закрыто'); }
        if ($ready === 0) { usleep(10_000); }
    }
    $chunk = pg_get_result($db);
    if (!$chunk instanceof PgSql\Result) { break; }
    $status = pg_result_status($chunk);
    if ($status === PGSQL_TUPLES_CHUNK) {
        if ($firstSize === null) {
            $firstSize = pg_num_rows($chunk);
            $lateChange = pg_set_chunked_rows_size($db, 10);
        }
    } elseif ($status === PGSQL_TUPLES_OK && pg_num_rows($chunk) === 0) {
        $finalReceived = true;
    } elseif ($status === PGSQL_FATAL_ERROR) {
        $error = pg_result_error($chunk) ?: 'PostgreSQL отклонил запрос';
    } else {
        $error = 'Неожиданный статус chunk-результата';
    }
}
if ($error !== null) { throw new RuntimeException($error); }
if ($firstSize === null || !$finalReceived) { throw new RuntimeException('Неполная последовательность chunk-результатов'); }
if ($lateChange !== false) { throw new RuntimeException('Позднее изменение неожиданно принято'); }
echo 'rows=', $firstSize, "\n";
var_dump($lateChange);

Нужна PHP-сборка с libpq 17+

На поддерживаемой сборке первый PGSQL_TUPLES_CHUNK содержит одну строку, а поздняя попытка изменить size возвращает false: режим задаётся только между отправкой запроса и первым pg_get_result. Код всё равно дочитывает очередь, требует финальный пустой PGSQL_TUPLES_OK и только после этого показывает результат. PGSQL_FATAL_ERROR также запоминается и сообщается после drain. На текущей DLL capability-ветка честно сообщает недоступность. Ранний 0 от poll на Windows/libpq повторяется до общего deadline. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE copy_products (id integer, name text, note text)');
$rows = [
    "1\tРучка\tсиняя\n",
    "2\tБлокнот\t\\N\n",
    "3\tЛинейка\t30 см\n",
];
$ok = pg_copy_from($db, 'copy_products', $rows);
if (!$ok) { throw new RuntimeException(pg_last_error($db)); }
$result = pg_query($db, 'SELECT count(*) AS total, count(note) AS with_note FROM copy_products');
echo pg_fetch_result($result, 0, 'total'), '|', pg_fetch_result($result, 0, 'with_note'), "\n";

3|2

Каждый элемент — уже сформированная строка COPY text с переводом строки. Стандартный маркер \N стал SQL NULL, а не текстом; count(note) поэтому равен двум. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE copy_events (id integer, label text)');
$rows = (function (): Generator {
    for ($id = 1; $id <= 4; $id++) {
        yield $id . "\tevent-" . $id . "\n";
    }
})();
var_dump(pg_copy_from($db, 'copy_events', $rows));
echo pg_fetch_result(pg_query($db, 'SELECT count(*) FROM copy_events'), 0, 0), "\n";

bool(true)
4

Начиная с PHP 8.5 rows принимает iterable, поэтому строки можно генерировать по одной. Это экономит PHP-память, но весь COPY остаётся одной операцией: ошибка одной строки отклоняет импорт. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE export_products (id integer, note text)');
pg_query($db, "INSERT INTO export_products VALUES (1, 'ok'), (2, NULL)");
$rows = pg_copy_to($db, 'export_products', "|", "<NULL>");
if ($rows === false) { throw new RuntimeException(pg_last_error($db)); }
foreach ($rows as $row) { echo rtrim($row, "\r\n"), "\n"; }

1|ok
2|<NULL>

Функция возвращает транспортные строки, а не ассоциативные массивы. Явный null_as позволяет отличить SQL NULL от пустого текста в выгрузке. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE source_rows (id integer, title text)');
pg_query($db, 'CREATE TEMP TABLE restored_rows (id integer, title text)');
pg_query($db, "INSERT INTO source_rows VALUES (1, 'one'), (2, 'two')");
$dump = pg_copy_to($db, 'source_rows');
if ($dump === false || !pg_copy_from($db, 'restored_rows', $dump)) { throw new RuntimeException('COPY не выполнен'); }
echo pg_fetch_result(pg_query($db, 'SELECT string_agg(title, chr(44) ORDER BY id) FROM restored_rows'), 0, 0), "\n";

one,two

Round trip работает при одинаковой структуре и одинаковых separator/null_as. Это не полноценный backup: здесь нет схемы, индексов, прав, sequence и согласованного snapshot; для резервной копии нужны pg_dump/pg_restore. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE legacy_copy (id integer, label text)');
$copy = pg_query($db, 'COPY legacy_copy FROM STDIN');
if (!$copy instanceof PgSql\Result) { throw new RuntimeException(pg_last_error($db)); }
pg_put_line($db, "1\talpha\n");
pg_put_line($db, "2\tbeta\n");
pg_put_line($db, "\\.\n");
if (!pg_end_copy($db)) { throw new RuntimeException(pg_last_error($db)); }
echo pg_fetch_result(pg_query($db, 'SELECT count(*) FROM legacy_copy'), 0, 0), "\n";

2

У legacy-пары pg_put_line/pg_end_copy приложение само посылает строку \. и затем синхронизирует соединение. Для обычного массива pg_copy_from проще и меньше подвержен протокольным ошибкам. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE legacy_nulls (id integer, value text)');
pg_query($db, 'COPY legacy_nulls FROM STDIN');
pg_put_line($db, "1\t\\N\n");
pg_put_line($db, "2\t\n");
pg_put_line($db, "\\.\n");
pg_end_copy($db);
$result = pg_query($db, "SELECT count(*) FILTER (WHERE value IS NULL), count(*) FILTER (WHERE value = '') FROM legacy_nulls");
echo pg_fetch_result($result, 0, 0), '|', pg_fetch_result($result, 0, 1), "\n";

1|1

В COPY text \N — SQL NULL, а пустое поле — пустая строка. Эта разница критична для импортов: «нет значения» и «значение есть, но пустое» часто означают разные бизнес-состояния. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE end_copy_items (id integer)');
pg_query($db, 'COPY end_copy_items FROM STDIN');
pg_put_line($db, "7\n");
pg_put_line($db, "\\.\n");
var_dump(pg_end_copy($db));
echo pg_fetch_result(pg_query($db, 'SELECT id FROM end_copy_items'), 0, 0), "\n";

bool(true)
7

Успешный pg_end_copy означает, что COPY завершён и соединение снова принимает обычный SQL. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE end_copy_numbers (id integer)');
pg_query($db, 'COPY end_copy_numbers FROM STDIN');
pg_put_line($db, "not-an-integer\n");
pg_put_line($db, "\\.\n");
$ok = @pg_end_copy($db);
var_dump($ok);
echo pg_fetch_result(pg_query($db, 'SELECT count(*) FROM end_copy_numbers'), 0, 0), "\n";

bool(false)
0

COPY выполняется как одна операция: несовместимая строка делает pg_end_copy false, и ранее переданные строки этой операции не появляются в таблице. Подробность берут из закрытого журнала, не показывают пользователю. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
function waitCopySocket(PgSql\Connection $connection, int $read, int $write, int $deadline): void
{
    $socket = pg_socket($connection);
    if ($socket === false) { throw new RuntimeException('Нет COPY-сокета'); }
    while (true) {
        $remainingMs = (int) ceil(($deadline - hrtime(true)) / 1_000_000);
        if ($remainingMs <= 0) { throw new RuntimeException('Истёк COPY deadline'); }
        $ready = pg_socket_poll($socket, $read, $write, $remainingMs);
        if ($ready < 0) { throw new RuntimeException('Ошибка ожидания COPY-сокета'); }
        if ($ready > 0) { return; }
        usleep(10_000);
    }
}

function flushCopyOutput(PgSql\Connection $connection, int $deadline): void
{
    while (true) {
        $flushed = pg_flush($connection);
        if ($flushed === false) { throw new RuntimeException('Ошибка отправки COPY'); }
        if ($flushed === true) { return; }
        waitCopySocket($connection, 0, 1, $deadline);
    }
}

function drainCopyResults(PgSql\Connection $connection, int $deadline): array
{
    while (pg_connection_busy($connection)) {
        waitCopySocket($connection, 1, 0, $deadline);
        if (!pg_consume_input($connection)) { throw new RuntimeException('Ошибка чтения COPY-ответа'); }
    }
    $results = [];
    while (($result = pg_get_result($connection)) instanceof PgSql\Result) {
        $results[] = $result;
    }
    return $results;
}

function queueCopyEnd(PgSql\Connection $connection, int $deadline, ?string $error = null): PgSql\Result
{
    try {
        do {
            $status = pg_put_copy_end($connection, $error);
            if ($status === 0) { waitCopySocket($connection, 0, 1, $deadline); }
        } while ($status === 0);
        if ($status !== 1) { throw new RuntimeException('Сигнал COPY end не поставлен'); }
        flushCopyOutput($connection, $deadline);
        $results = drainCopyResults($connection, $deadline);
        if ($results === []) { throw new RuntimeException('Нет финального COPY result'); }
        return $results[array_key_last($results)];
    } catch (Throwable $errorObject) {
        try { pg_close($connection); } catch (Throwable) {}
        throw $errorObject;
    }
}

function abortCopy(PgSql\Connection $connection, string $message): void
{
    $cleanupDeadline = hrtime(true) + 2_000_000_000;
    try {
        queueCopyEnd($connection, $cleanupDeadline, $message);
    } catch (Throwable) {
        try { pg_close($connection); } catch (Throwable) {}
    }
}

function queueCopyData(PgSql\Connection $connection, string $data, int $deadline): void
{
    try {
        do {
            $status = pg_put_copy_data($connection, $data);
            if ($status === 0) { waitCopySocket($connection, 0, 1, $deadline); }
        } while ($status === 0);
        if ($status !== 1) { throw new RuntimeException('Порция COPY отклонена'); }
    } catch (Throwable $error) {
        abortCopy($connection, 'Клиент не смог отправить порцию');
        throw $error;
    }
}

pg_query($db, 'CREATE TEMP TABLE modern_copy (id integer, label text)');
$copy = pg_query($db, 'COPY modern_copy FROM STDIN');
if (pg_result_status($copy) !== PGSQL_COPY_IN) { throw new RuntimeException('COPY не открыт'); }
$deadline = hrtime(true) + 5_000_000_000;
foreach (["1\talpha\n", "2\tbeta\n"] as $line) { queueCopyData($db, $line, $deadline); }
$final = queueCopyEnd($db, $deadline);
if (!$final instanceof PgSql\Result || pg_result_status($final) !== PGSQL_COMMAND_OK) { throw new RuntimeException('Сервер не подтвердил COPY'); }
echo pg_fetch_result(pg_query($db, 'SELECT count(*) FROM modern_copy'), 0, 0), "\n";

2

Каждая строка заканчивается явным newline. Краткая официальная страница утверждает, что newline добавляется автоматически, но фактический PHP 8.5.11/php-src передаёт PQputCopyData буфер ровно заданной длины: без \n две порции склеились бы. В отличие от pg_put_line строка \. не отправляется: завершение сигнализирует pg_put_copy_end. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
function waitCopySocket(PgSql\Connection $connection, int $read, int $write, int $deadline): void
{
    $socket = pg_socket($connection);
    if ($socket === false) { throw new RuntimeException('Нет COPY-сокета'); }
    while (true) {
        $remainingMs = (int) ceil(($deadline - hrtime(true)) / 1_000_000);
        if ($remainingMs <= 0) { throw new RuntimeException('Истёк COPY deadline'); }
        $ready = pg_socket_poll($socket, $read, $write, $remainingMs);
        if ($ready < 0) { throw new RuntimeException('Ошибка ожидания COPY-сокета'); }
        if ($ready > 0) { return; }
        usleep(10_000);
    }
}

function flushCopyOutput(PgSql\Connection $connection, int $deadline): void
{
    while (true) {
        $flushed = pg_flush($connection);
        if ($flushed === false) { throw new RuntimeException('Ошибка отправки COPY'); }
        if ($flushed === true) { return; }
        waitCopySocket($connection, 0, 1, $deadline);
    }
}

function drainCopyResults(PgSql\Connection $connection, int $deadline): array
{
    while (pg_connection_busy($connection)) {
        waitCopySocket($connection, 1, 0, $deadline);
        if (!pg_consume_input($connection)) { throw new RuntimeException('Ошибка чтения COPY-ответа'); }
    }
    $results = [];
    while (($result = pg_get_result($connection)) instanceof PgSql\Result) {
        $results[] = $result;
    }
    return $results;
}

function queueCopyEnd(PgSql\Connection $connection, int $deadline, ?string $error = null): PgSql\Result
{
    try {
        do {
            $status = pg_put_copy_end($connection, $error);
            if ($status === 0) { waitCopySocket($connection, 0, 1, $deadline); }
        } while ($status === 0);
        if ($status !== 1) { throw new RuntimeException('Сигнал COPY end не поставлен'); }
        flushCopyOutput($connection, $deadline);
        $results = drainCopyResults($connection, $deadline);
        if ($results === []) { throw new RuntimeException('Нет финального COPY result'); }
        return $results[array_key_last($results)];
    } catch (Throwable $errorObject) {
        try { pg_close($connection); } catch (Throwable) {}
        throw $errorObject;
    }
}

function abortCopy(PgSql\Connection $connection, string $message): void
{
    $cleanupDeadline = hrtime(true) + 2_000_000_000;
    try {
        queueCopyEnd($connection, $cleanupDeadline, $message);
    } catch (Throwable) {
        try { pg_close($connection); } catch (Throwable) {}
    }
}

function queueCopyData(PgSql\Connection $connection, string $data, int $deadline): void
{
    try {
        do {
            $status = pg_put_copy_data($connection, $data);
            if ($status === 0) { waitCopySocket($connection, 0, 1, $deadline); }
        } while ($status === 0);
        if ($status !== 1) { throw new RuntimeException('Порция COPY отклонена'); }
    } catch (Throwable $error) {
        abortCopy($connection, 'Клиент не смог отправить порцию');
        throw $error;
    }
}

pg_query($db, 'CREATE TEMP TABLE copy_status (value text)');
pg_query($db, 'COPY copy_status FROM STDIN');
$deadline = hrtime(true) + 5_000_000_000;
queueCopyData($db, "hello\n", $deadline);
echo "Строка принята клиентской библиотекой\n";
$final = queueCopyEnd($db, $deadline);
if (!$final instanceof PgSql\Result || pg_result_status($final) !== PGSQL_COMMAND_OK) { throw new RuntimeException('Сервер не подтвердил COPY'); }

Строка принята клиентской библиотекой

Код 1 относится к постановке данных в очередь libpq. Окончательный успех COPY подтверждается только после завершения операции; 0 возможен в non-blocking mode, -1 означает ошибку. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
function waitCopySocket(PgSql\Connection $connection, int $read, int $write, int $deadline): void
{
    $socket = pg_socket($connection);
    if ($socket === false) { throw new RuntimeException('Нет COPY-сокета'); }
    while (true) {
        $remainingMs = (int) ceil(($deadline - hrtime(true)) / 1_000_000);
        if ($remainingMs <= 0) { throw new RuntimeException('Истёк COPY deadline'); }
        $ready = pg_socket_poll($socket, $read, $write, $remainingMs);
        if ($ready < 0) { throw new RuntimeException('Ошибка ожидания COPY-сокета'); }
        if ($ready > 0) { return; }
        usleep(10_000);
    }
}

function flushCopyOutput(PgSql\Connection $connection, int $deadline): void
{
    while (true) {
        $flushed = pg_flush($connection);
        if ($flushed === false) { throw new RuntimeException('Ошибка отправки COPY'); }
        if ($flushed === true) { return; }
        waitCopySocket($connection, 0, 1, $deadline);
    }
}

function drainCopyResults(PgSql\Connection $connection, int $deadline): array
{
    while (pg_connection_busy($connection)) {
        waitCopySocket($connection, 1, 0, $deadline);
        if (!pg_consume_input($connection)) { throw new RuntimeException('Ошибка чтения COPY-ответа'); }
    }
    $results = [];
    while (($result = pg_get_result($connection)) instanceof PgSql\Result) {
        $results[] = $result;
    }
    return $results;
}

function queueCopyEnd(PgSql\Connection $connection, int $deadline, ?string $error = null): PgSql\Result
{
    try {
        do {
            $status = pg_put_copy_end($connection, $error);
            if ($status === 0) { waitCopySocket($connection, 0, 1, $deadline); }
        } while ($status === 0);
        if ($status !== 1) { throw new RuntimeException('Сигнал COPY end не поставлен'); }
        flushCopyOutput($connection, $deadline);
        $results = drainCopyResults($connection, $deadline);
        if ($results === []) { throw new RuntimeException('Нет финального COPY result'); }
        return $results[array_key_last($results)];
    } catch (Throwable $errorObject) {
        try { pg_close($connection); } catch (Throwable) {}
        throw $errorObject;
    }
}

function abortCopy(PgSql\Connection $connection, string $message): void
{
    $cleanupDeadline = hrtime(true) + 2_000_000_000;
    try {
        queueCopyEnd($connection, $cleanupDeadline, $message);
    } catch (Throwable) {
        try { pg_close($connection); } catch (Throwable) {}
    }
}

function queueCopyData(PgSql\Connection $connection, string $data, int $deadline): void
{
    try {
        do {
            $status = pg_put_copy_data($connection, $data);
            if ($status === 0) { waitCopySocket($connection, 0, 1, $deadline); }
        } while ($status === 0);
        if ($status !== 1) { throw new RuntimeException('Порция COPY отклонена'); }
    } catch (Throwable $error) {
        abortCopy($connection, 'Клиент не смог отправить порцию');
        throw $error;
    }
}

pg_query($db, 'CREATE TEMP TABLE copy_end_ok (id integer)');
pg_query($db, 'COPY copy_end_ok FROM STDIN');
$deadline = hrtime(true) + 5_000_000_000;
queueCopyData($db, "9\n", $deadline);
$final = queueCopyEnd($db, $deadline);
echo "Конец поставлен в очередь\n";
echo $final instanceof PgSql\Result && pg_result_status($final) === PGSQL_COMMAND_OK ? "COPY подтверждён\n" : "COPY не подтверждён\n";
echo pg_fetch_result(pg_query($db, 'SELECT id FROM copy_end_ok'), 0, 0), "\n";

Конец поставлен в очередь
COPY подтверждён
9

1 означает, что сигнал окончания принят клиентской библиотекой. Финальный PgSql\Result нужно обязательно снять через pg_get_result; только его PGSQL_COMMAND_OK подтверждает серверный успех. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
function waitCopySocket(PgSql\Connection $connection, int $read, int $write, int $deadline): void
{
    $socket = pg_socket($connection);
    if ($socket === false) { throw new RuntimeException('Нет COPY-сокета'); }
    while (true) {
        $remainingMs = (int) ceil(($deadline - hrtime(true)) / 1_000_000);
        if ($remainingMs <= 0) { throw new RuntimeException('Истёк COPY deadline'); }
        $ready = pg_socket_poll($socket, $read, $write, $remainingMs);
        if ($ready < 0) { throw new RuntimeException('Ошибка ожидания COPY-сокета'); }
        if ($ready > 0) { return; }
        usleep(10_000);
    }
}

function flushCopyOutput(PgSql\Connection $connection, int $deadline): void
{
    while (true) {
        $flushed = pg_flush($connection);
        if ($flushed === false) { throw new RuntimeException('Ошибка отправки COPY'); }
        if ($flushed === true) { return; }
        waitCopySocket($connection, 0, 1, $deadline);
    }
}

function drainCopyResults(PgSql\Connection $connection, int $deadline): array
{
    while (pg_connection_busy($connection)) {
        waitCopySocket($connection, 1, 0, $deadline);
        if (!pg_consume_input($connection)) { throw new RuntimeException('Ошибка чтения COPY-ответа'); }
    }
    $results = [];
    while (($result = pg_get_result($connection)) instanceof PgSql\Result) {
        $results[] = $result;
    }
    return $results;
}

function queueCopyEnd(PgSql\Connection $connection, int $deadline, ?string $error = null): PgSql\Result
{
    try {
        do {
            $status = pg_put_copy_end($connection, $error);
            if ($status === 0) { waitCopySocket($connection, 0, 1, $deadline); }
        } while ($status === 0);
        if ($status !== 1) { throw new RuntimeException('Сигнал COPY end не поставлен'); }
        flushCopyOutput($connection, $deadline);
        $results = drainCopyResults($connection, $deadline);
        if ($results === []) { throw new RuntimeException('Нет финального COPY result'); }
        return $results[array_key_last($results)];
    } catch (Throwable $errorObject) {
        try { pg_close($connection); } catch (Throwable) {}
        throw $errorObject;
    }
}

function abortCopy(PgSql\Connection $connection, string $message): void
{
    $cleanupDeadline = hrtime(true) + 2_000_000_000;
    try {
        queueCopyEnd($connection, $cleanupDeadline, $message);
    } catch (Throwable) {
        try { pg_close($connection); } catch (Throwable) {}
    }
}

function queueCopyData(PgSql\Connection $connection, string $data, int $deadline): void
{
    try {
        do {
            $status = pg_put_copy_data($connection, $data);
            if ($status === 0) { waitCopySocket($connection, 0, 1, $deadline); }
        } while ($status === 0);
        if ($status !== 1) { throw new RuntimeException('Порция COPY отклонена'); }
    } catch (Throwable $error) {
        abortCopy($connection, 'Клиент не смог отправить порцию');
        throw $error;
    }
}

pg_query($db, 'CREATE TEMP TABLE copy_end_abort (id integer)');
pg_query($db, 'COPY copy_end_abort FROM STDIN');
$deadline = hrtime(true) + 5_000_000_000;
queueCopyData($db, "1\n", $deadline);
$final = queueCopyEnd($db, $deadline, 'Проверка файла не пройдена');
echo "Отмена отправлена\n";
echo $final instanceof PgSql\Result && pg_result_status($final) === PGSQL_FATAL_ERROR ? "Импорт отклонён\n" : "Неожиданный статус\n";
echo pg_fetch_result(pg_query($db, 'SELECT count(*) FROM copy_end_abort'), 0, 0), "\n";

Отмена отправлена
Импорт отклонён
0

Непустой error просит сервер провалить COPY. Финальный PgSql\Result имеет PGSQL_FATAL_ERROR, уже переданные строки не фиксируются; это удобно, если поздняя проверка файла обнаружила нарушение. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'LISTEN manual_events');
pg_query($db, "NOTIFY manual_events, 'order-42'");
$notify = pg_get_notify($db, PGSQL_ASSOC);
if ($notify === false) { throw new RuntimeException('Уведомление не получено'); }
echo $notify['message'], '|', $notify['payload'], "\n";

manual_events|order-42

LISTEN действует до конца сессии, а payload — короткий сигнал, не очередь задач. Обработчик по order-42 обычно перечитывает актуальное состояние из таблицы. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'LISTEN empty_manual_channel');
var_dump(pg_get_notify($db, PGSQL_ASSOC));

bool(false)

false означает, что сейчас готового NOTIFY нет. В event loop сначала ждут readable через pg_socket; затем можно сразу вызвать pg_get_notify, потому что текущая php-src сама выполняет PQconsumeInput. Явный pg_consume_input нужен, когда цикл отдельно обслуживает общий входной буфер, но не является обязательной парой перед каждым get_notify. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$path = tempnam(sys_get_temp_dir(), 'php-pgsql-trace-');
if ($path === false || !chmod($path, 0600)) { throw new RuntimeException('Закрытый temp-файл не создан'); }
try {
    $started = pg_trace($path, 'w', $db, PGSQL_TRACE_SUPPRESS_TIMESTAMPS);
    if (!$started) { throw new RuntimeException('Trace не включён'); }
    if (pg_query($db, 'SELECT 42') === false) { throw new RuntimeException('Учебный запрос не выполнен'); }
    pg_untrace($db);
    clearstatcache(true, $path);
    echo is_file($path) && filesize($path) > 0 ? "Trace записан\n" : "Trace пуст\n";
} finally {
    pg_untrace($db);
    if (is_file($path) && !unlink($path)) { throw new RuntimeException('Trace-файл не удалён'); }
}

Trace записан

Trace может содержать SQL и значения протокола, поэтому tempnam создаёт уникальный файл вне web-root, chmod ограничивает доступ, а finally удаляет путь. Это диагностика libpq, а не обычный application log. Внутри ext/pgsql поток trace зарегистрирован для автоматического закрытия при завершении запроса: на Windows отдельный временный подкаталог нельзя надёжно удалить до этого момента, поэтому пример не создаёт такой каталог. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$started = @pg_trace(__DIR__, 'w', $db);
var_dump($started);

bool(false)

Путь к каталогу нельзя открыть как файл. Проверяйте false и права заранее; не продолжайте с предположением, что диагностические данные записываются. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$path = tempnam(sys_get_temp_dir(), 'php-pgsql-untrace-');
if ($path === false || !chmod($path, 0600)) { throw new RuntimeException('Закрытый temp-файл не создан'); }
try {
    if (!pg_trace($path, 'w', $db, PGSQL_TRACE_SUPPRESS_TIMESTAMPS)) { throw new RuntimeException('Trace не включён'); }
    if (pg_query($db, 'SELECT 1') === false) { throw new RuntimeException('Учебный запрос не выполнен'); }
    var_dump(pg_untrace($db));
} finally {
    pg_untrace($db);
    if (is_file($path) && !unlink($path)) { throw new RuntimeException('Trace-файл не удалён'); }
}

bool(true)

С PHP 8.2 функция имеет return type true. finally нужен, чтобы служебный файл удалился и при исключении. Уникальный системный temp-файл безопаснее отдельного каталога: ext/pgsql закрывает связанный PHP-поток только при завершении запроса, что на Windows мешает немедленно удалить родительский каталог. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
var_dump(pg_untrace($db));
var_dump(pg_untrace($db));

bool(true)
bool(true)

Функция всегда возвращает true, поэтому это подтверждение вызова, а не доказательство, что trace прежде был активен или файл содержал данные. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$bytes = "A\x00B\xFFC";
$escaped = pg_escape_bytea($db, $bytes);
$result = pg_query($db, "SELECT '{$escaped}'::bytea AS payload");
$raw = pg_fetch_result($result, 0, 'payload');
$restored = pg_unescape_bytea($raw);
echo bin2hex($restored), "\n";

410042ff43

bin2hex делает бинарный результат видимым и безопасным для терминала. pg_escape_bytea подготавливает содержимое bytea для ручного SQL literal; для нового кода удобнее передавать hex через параметр и decode($1, 'hex'). Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
pg_query($db, 'CREATE TEMP TABLE bytea_assets (id integer, payload bytea)');
$bytes = "PNG\x00demo";
$escaped = pg_escape_bytea($db, $bytes);
pg_query($db, "INSERT INTO bytea_assets VALUES (1, '{$escaped}'::bytea)");
$stored = pg_fetch_result(pg_query($db, 'SELECT octet_length(payload) FROM bytea_assets'), 0, 0);
echo $stored, " bytes\n";

8 bytes

bytea подходит небольшим бинарным данным, которые должны быть транзакционно связаны со строкой. Большие файлы часто выгоднее хранить в object storage, а в БД — путь, размер, MIME и hash. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$result = pg_query($db, "SELECT decode('000aff', 'hex') AS payload");
$wire = pg_fetch_result($result, 0, 'payload');
$bytes = pg_unescape_bytea($wire);
echo bin2hex($bytes), "\n";

000aff

pg_fetch_result возвращает текстовое представление bytea протокола; pg_unescape_bytea превращает его в PHP-строку из трёх байтов. Выводится hex, иначе NUL и 0xFF были бы невидимы/небезопасны. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
$original = "file\x00contents";
$escaped = pg_escape_bytea($db, $original);
$wire = pg_fetch_result(pg_query($db, "SELECT '{$escaped}'::bytea"), 0, 0);
$restored = pg_unescape_bytea($wire);
echo hash_equals(hash('sha256', $original), hash('sha256', $restored)) ? "Hash совпал\n" : "Данные повреждены\n";

Hash совпал

Для файла сравнивают сохранённый hash и размер, а затем уже отдают байты с проверенным Content-Type. Сама функция не распознаёт формат и не проверяет содержимое на безопасность. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
function verbosityName(int|false $mode): string
{
    return match ($mode) {
        PGSQL_ERRORS_DEFAULT => 'DEFAULT',
        PGSQL_ERRORS_VERBOSE => 'VERBOSE',
        false => 'FAILURE',
        default => "mode={$mode}",
    };
}

$original = pg_set_error_verbosity($db, PGSQL_ERRORS_DEFAULT);
if ($original === false) {
    throw new RuntimeException('Не удалось зафиксировать исходный режим');
}

try {
    $previous = pg_set_error_verbosity($db, PGSQL_ERRORS_VERBOSE);
    echo 'До переключения: ', verbosityName($previous), "
";
} finally {
    $beforeRestore = pg_set_error_verbosity($db, $original);
    echo 'Перед восстановлением: ', verbosityName($beforeRestore), "
";
    echo 'Восстановлен: ', verbosityName($original), "
";
}

До переключения: DEFAULT
Перед восстановлением: VERBOSE
Восстановлен: DEFAULT

Функция возвращает не новый, а прежний режим соединения. Поэтому первое возвращённое значение можно сохранить, временно усилить журналирование и восстановить настройку в finally даже при исключении между этими действиями. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
function failedResult(PgSql\Connection $db, string $sql): PgSql\Result
{
    if (pg_send_query($db, $sql) === false) {
        throw new RuntimeException('Не удалось отправить запрос');
    }
    $result = pg_get_result($db);
    if (!$result instanceof PgSql\Result) {
        throw new RuntimeException('Сервер не вернул PGresult');
    }
    return $result;
}

$original = pg_set_error_verbosity($db, PGSQL_ERRORS_DEFAULT);
if ($original === false) {
    throw new RuntimeException('Не удалось зафиксировать исходный режим');
}

try {
    $defaultResult = failedResult(
        $db,
        'SELECT * FROM manual_missing_error_verbosity'
    );
    $defaultText = pg_result_error($defaultResult);

    pg_set_error_verbosity($db, PGSQL_ERRORS_VERBOSE);
    $verboseResult = failedResult(
        $db,
        'SELECT * FROM manual_missing_error_verbosity'
    );
    $verboseText = pg_result_error($verboseResult);

    echo 'DEFAULT содержит SQLSTATE в тексте: ',
        str_contains($defaultText, '42P01') ? 'да' : 'нет', "
";
    echo 'VERBOSE содержит SQLSTATE в тексте: ',
        str_contains($verboseText, '42P01') ? 'да' : 'нет', "
";
    echo 'VERBOSE содержит LOCATION: ',
        str_contains($verboseText, 'LOCATION:') ? 'да' : 'нет', "
";
    echo 'SQLSTATE из поля PGresult: ',
        pg_result_error_field($verboseResult, PGSQL_DIAG_SQLSTATE), "
";
    echo 'Старый PGresult изменился: ',
        pg_result_error($defaultResult) === $defaultText ? 'нет' : 'да', "
";
} finally {
    pg_set_error_verbosity($db, $original);
}

DEFAULT содержит SQLSTATE в тексте: нет
VERBOSE содержит SQLSTATE в тексте: да
VERBOSE содержит LOCATION: да
SQLSTATE из поля PGresult: 42P01
Старый PGresult изменился: нет

Один и тот же ошибочный SQL создаёт два разных объекта результата. VERBOSE добавляет SQLSTATE и место в исходниках PostgreSQL к форматированной строке, но структурированный SQLSTATE лучше читать отдельным diagnostic field. Уже созданный PGresult после переключения не переписывается. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
function contextModeName(int $mode): string
{
    return match ($mode) {
        PGSQL_SHOW_CONTEXT_NEVER => 'NEVER',
        PGSQL_SHOW_CONTEXT_ERRORS => 'ERRORS',
        PGSQL_SHOW_CONTEXT_ALWAYS => 'ALWAYS',
        default => "mode={$mode}",
    };
}

$original = pg_set_error_context_visibility(
    $db,
    PGSQL_SHOW_CONTEXT_NEVER
);

try {
    $previous = pg_set_error_context_visibility(
        $db,
        PGSQL_SHOW_CONTEXT_ALWAYS
    );
    echo 'До переключения: ', contextModeName($previous), "
";
} finally {
    $beforeRestore = pg_set_error_context_visibility($db, $original);
    echo 'Перед восстановлением: ', contextModeName($beforeRestore), "
";
    echo 'Восстановлен: ', contextModeName($original), "
";
}

До переключения: NEVER
Перед восстановлением: ALWAYS
Восстановлен: ERRORS

Новое соединение по умолчанию использует ERRORS. Первый вызов временно ставит NEVER и возвращает прежний ERRORS; второй возвращает NEVER. finally получает состояние перед восстановлением и возвращает соединению исходный ERRORS. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';
function contextFailure(PgSql\Connection $db): PgSql\Result
{
    $sql = <<<'SQL'
DO $$
BEGIN
    PERFORM 1 / 0;
END
$$
SQL;
    if (pg_send_query($db, $sql) === false) {
        throw new RuntimeException('Не удалось отправить DO');
    }
    $result = pg_get_result($db);
    if (!$result instanceof PgSql\Result) {
        throw new RuntimeException('Сервер не вернул PGresult');
    }
    return $result;
}

$original = pg_set_error_context_visibility(
    $db,
    PGSQL_SHOW_CONTEXT_NEVER
);

try {
    $withoutContext = contextFailure($db);
    $withoutText = pg_result_error($withoutContext);

    pg_set_error_context_visibility($db, PGSQL_SHOW_CONTEXT_ALWAYS);
    $withContext = contextFailure($db);
    $withText = pg_result_error($withContext);

    echo 'NEVER, строка CONTEXT: ',
        str_contains($withoutText, 'CONTEXT:') ? 'показана' : 'скрыта', "
";
    echo 'ALWAYS, строка CONTEXT: ',
        str_contains($withText, 'CONTEXT:') ? 'показана' : 'скрыта', "
";
    echo 'Сырое PGSQL_DIAG_CONTEXT при NEVER: ',
        pg_result_error_field($withoutContext, PGSQL_DIAG_CONTEXT) !== null
            ? 'доступно'
            : 'отсутствует',
        "
";
    echo 'Старый PGresult изменился: ',
        pg_result_error($withoutContext) === $withoutText ? 'нет' : 'да', "
";
} finally {
    pg_set_error_context_visibility($db, $original);
}

NEVER, строка CONTEXT: скрыта
ALWAYS, строка CONTEXT: показана
Сырое PGSQL_DIAG_CONTEXT при NEVER: доступно
Старый PGresult изменился: нет

Деление на ноль внутри DO создаёт настоящий серверный context: какой SQL выполнялся и на какой строке PL/pgSQL. Visibility меняет форматированную строку pg_result_error, но не стирает структурированное поле PGSQL_DIAG_CONTEXT из PGresult. Для машинной диагностики читайте fields, для закрытого журнала выбирайте разумную полноту. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';

        if (pg_query($db, 'BEGIN') === false) { throw new RuntimeException('BEGIN не выполнен'); }
        try {
            $oid = pg_lo_create($db);
            if ($oid === false) { throw new RuntimeException('Large object не создан'); }
            echo (is_int($oid) || is_string($oid)) ? "Получен OID\n" : "Неожиданный тип\n";

            $lob = pg_lo_open($db, $oid, 'w+');
            if ($lob === false) { throw new RuntimeException('Large object не открыт'); }
            pg_lo_write($lob, 'invoice.pdf bytes');
            pg_lo_close($lob);

            var_dump((string) $oid !== 'invoice.pdf bytes');
            if (!pg_lo_unlink($db, $oid)) { throw new RuntimeException('OID не удалён'); }
            pg_query($db, 'COMMIT');
        } catch (Throwable $error) {
            pg_query($db, 'ROLLBACK');
            throw $error;
        }

Получен OID
bool(true)

Сервер выдаёт числовой идентификатор. Он позволяет позже открыть отдельный объект, но сам не содержит имя, MIME-тип или байты документа; эти метаданные приложение хранит в обычной таблице. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';

        $transaction = false;
        $lob = null;
        try {
            if (pg_query($db, 'BEGIN') === false) { throw new RuntimeException('BEGIN не выполнен'); }
            $transaction = true;
            $oid = pg_lo_create($db);
            if ($oid === false) { throw new RuntimeException('Large object не создан'); }
            if (pg_query($db, 'ROLLBACK') === false) { throw new RuntimeException('ROLLBACK не выполнен'); }
            $transaction = false;

            if (pg_query($db, 'BEGIN') === false) { throw new RuntimeException('Проверочная транзакция не начата'); }
            $transaction = true;
            $lob = @pg_lo_open($db, $oid, 'r');
            var_dump($lob === false);
            if ($lob instanceof PgSql\Lob) {
                if (!pg_lo_close($lob)) { throw new RuntimeException('Дескриптор не закрыт'); }
                $lob = null;
            }
            if (pg_query($db, 'ROLLBACK') === false) { throw new RuntimeException('Проверочный ROLLBACK не выполнен'); }
            $transaction = false;
        } finally {
            if ($lob instanceof PgSql\Lob) { @pg_lo_close($lob); }
            if ($transaction) { @pg_query($db, 'ROLLBACK'); }
        }

bool(true)

Создание transactional: после ROLLBACK прежний OID нельзя открыть. Это полезно при загрузке документа вместе с записью заказа — неудачная операция не оставляет бесхозный объект. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';

        pg_query($db, 'BEGIN');
        try {
            $oid = pg_lo_create($db);
            $writer = pg_lo_open($db, $oid, 'w+');
            if ($writer === false) { throw new RuntimeException('Нет дескриптора'); }
            pg_lo_write($writer, 'manual.pdf');
            pg_lo_close($writer);

            $reader = pg_lo_open($db, $oid, 'r');
            if ($reader === false) { throw new RuntimeException('Нет чтения'); }
            echo pg_lo_read($reader, 64), "\n";
            pg_lo_close($reader);
            pg_lo_unlink($db, $oid);
            pg_query($db, 'COMMIT');
        } catch (Throwable $error) {
            pg_query($db, 'ROLLBACK');
            throw $error;
        }

manual.pdf

Режим r открывает существующий OID только для чтения. Соединение остаётся открытым до pg_lo_close, затем объект явно удаляется из учебной базы. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';

        pg_query($db, 'BEGIN');
        $missingOid = '4294967294';
        $lob = @pg_lo_open($db, $missingOid, 'r');
        var_dump($lob === false);
        pg_query($db, 'ROLLBACK');

bool(true)

OID мог остаться в строке после неправильного удаления файла. pg_lo_open возвращает false и серверная транзакция после ошибки требует ROLLBACK; посетителю дают понятное «файл недоступен», а техническую причину журналируют. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';

        pg_query($db, 'BEGIN');
        try {
            $oid = pg_lo_create($db);
            try {
                pg_lo_open($db, $oid, 'rw');
            } catch (ValueError $error) {
                echo "Для чтения и записи нужен r+\n";
            }
            pg_lo_unlink($db, $oid);
            pg_query($db, 'COMMIT');
        } catch (Throwable $error) {
            pg_query($db, 'ROLLBACK');
            throw $error;
        }

Для чтения и записи нужен r+

Страница PHP Manual всё ещё называет режим rw, но php-src 8.5.11 и живой runtime принимают r, w, r+ и w+. Карточка следует проверенному поведению текущей версии. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';

        pg_query($db, 'BEGIN');
        $requestedOid = pg_lo_create($db);
        if ($requestedOid === false || !pg_lo_unlink($db, $requestedOid)) {
            pg_query($db, 'ROLLBACK');
            throw new RuntimeException('Не удалось подготовить отсутствующий OID');
        }

        $lob = @pg_lo_open($db, $requestedOid, 'w');
        var_dump($lob === false);
        echo pg_transaction_status($db) === PGSQL_TRANSACTION_INERROR
            ? "Транзакция требует ROLLBACK\n"
            : "Неожиданное состояние\n";
        if ($lob instanceof PgSql\Lob) { pg_lo_close($lob); }
        pg_query($db, 'ROLLBACK');

bool(true)
Транзакция требует ROLLBACK

Страница PHP Manual и fallback в php-src предполагают попытку создать large object для w/w+, если первый lo_open не нашёл OID. На проверенной связке PostgreSQL 18.6, PHP 8.5 и ext/pgsql первый отказ уже переводит транзакцию в error state, поэтому последующий lo_creat возвращает 0, pg_lo_open предупреждает и возвращает false. @ скрывает только ожидаемое предупреждение учебного опыта; состояние проверяется явно и затем выполняется ROLLBACK. Даже на стеке, где fallback сработает, PgSql\Lob не сообщает выбранный сервером новый OID. Надёжный путь один: pg_lo_create, сохранить его OID и открыть именно этот объект. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';

        pg_query($db, 'BEGIN');
        try {
            $oid = pg_lo_create($db);
            $lob = pg_lo_open($db, $oid, 'w+');
            $written = pg_lo_write($lob, 'ABCDEF');
            echo "Записано: {$written} байт\n";
            pg_lo_close($lob);
            pg_lo_unlink($db, $oid);
            pg_query($db, 'COMMIT');
        } catch (Throwable $error) {
            pg_query($db, 'ROLLBACK');
            throw $error;
        }

Записано: 6 байт

Возврат — фактическое число записанных байт, поэтому его проверяют, а не предполагают успешную полную запись. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';

        pg_query($db, 'BEGIN');
        try {
            $oid = pg_lo_create($db);
            $lob = pg_lo_open($db, $oid, 'w+');
            $written = pg_lo_write($lob, 'ёж', 2);
            pg_lo_seek($lob, 0, PGSQL_SEEK_SET);
            $saved = pg_lo_read($lob, 10);
            echo $saved, '|bytes=', $written, "\n";
            pg_lo_close($lob);
            pg_lo_unlink($db, $oid);
            pg_query($db, 'COMMIT');
        } catch (Throwable $error) {
            pg_query($db, 'ROLLBACK');
            throw $error;
        }

ё|bytes=2

В UTF-8 буква «ё» занимает два байта. Не передавайте mb_strlen как length: граница, попавшая внутрь многобайтного символа, сохранит повреждённую последовательность. Для бинарных данных считают именно байты. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';

        pg_query($db, 'BEGIN');
        try {
            $oid = pg_lo_create($db);
            $lob = pg_lo_open($db, $oid, 'w+');
            try {
                pg_lo_write($lob, "A\0B");
            } catch (ValueError $error) {
                echo "NUL отклонён до записи\n";
            }
            pg_lo_close($lob);
            pg_lo_unlink($db, $oid);
            pg_query($db, 'COMMIT');
        } catch (Throwable $error) {
            pg_query($db, 'ROLLBACK');
            throw $error;
        }

NUL отклонён до записи

Живой PHP 8.5.11/ext/pgsql выбрасывает ValueError для NUL внутри $data: реализация разбирает аргумент как path string. Для произвольного бинарного файла с NUL используйте pg_lo_import либо передавайте безопасные блоки без NUL после осознанного выбора формата. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';

        pg_query($db, 'BEGIN');
        try {
            $oid = pg_lo_create($db);
            $lob = pg_lo_open($db, $oid, 'w+');
            $written = pg_lo_write($lob, 'ABC', 0);
            echo 'written=', $written, '|position=', pg_lo_tell($lob), "\n";
            pg_lo_close($lob);
            pg_lo_unlink($db, $oid);
            pg_query($db, 'COMMIT');
        } catch (Throwable $error) {
            pg_query($db, 'ROLLBACK');
            throw $error;
        }

written=0|position=0

Исходник и живой PHP 8.5.11 разрешают length=0: ничего не записано и курсор не сдвинулся. Это точнее официальной фразы «greater than zero» на текущей странице. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';

        pg_query($db, 'BEGIN');
        try {
            $oid = pg_lo_create($db);
            $lob = pg_lo_open($db, $oid, 'w+');
            pg_lo_write($lob, 'ABCDEFGHIJ');
            pg_lo_seek($lob, 0, PGSQL_SEEK_SET);
            while (true) {
                $chunk = pg_lo_read($lob, 4);
                if ($chunk === false) { throw new RuntimeException('Ошибка чтения large object'); }
                if ($chunk === '') { break; }
                echo '[', $chunk, ']';
            }
            echo "\n";
            pg_lo_close($lob);
            pg_lo_unlink($db, $oid);
            pg_query($db, 'COMMIT');
        } catch (Throwable $error) {
            pg_query($db, 'ROLLBACK');
            throw $error;
        }

[ABCD][EFGH][IJ]

Цикл получает 4, 4 и 2 байта; пустая строка означает конец. Сначала отдельно проверяйте false, если отказ нужно отличать от EOF. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.

<?php
declare(strict_types=1);

require __DIR__ . '/pgsql-bootstrap.php';

        $source = tempnam(__DIR__, 'pglo-read-');
        if ($source === false) { throw new RuntimeException('Нет временного файла'); }
        file_put_contents($source, "A\0B\xFF");
        pg_query($db, 'BEGIN');
        try {
            $oid = pg_lo_import($db, $source);
            if ($oid === false) { throw new RuntimeException('Импорт не выполнен'); }
            $lob = pg_lo_open($db, $oid, 'r');
            $data = pg_lo_read($lob, 4);
            if ($data === false) { throw new RuntimeException('Ошибка чтения large object'); }
            echo bin2hex($data), '|bytes=', strlen($data), "\n";
            pg_lo_close($lob);
            pg_lo_unlink($db, $oid);
            pg_query($db, 'COMMIT');
        } catch (Throwable $error) {
            pg_query($db, 'ROLLBACK');
            throw $error;
        } finally {
            if (is_file($source)) { unlink($source); }
        }

410042ff|bytes=4

Строка PHP сохраняет NUL и 0xFF; echo бинарного содержимого в диагностический терминал неудобен, поэтому пример показывает hex. В HTTP сначала задают корректный Content-Type и контролируют доступ. Пример выполнен на изолированной учебной базе PostgreSQL 18.6 через PHP 8.5.11/ext/pgsql (libpq 16.15). Для своего запуска задайте PGHOST, PGPORT, PGDATABASE, PGUSER и PGPASSWORD; скачиваемый пример содержит pgsql-bootstrap.php. Не подставляйте рабочие реквизиты в код.