slam/psql-php

PHP version of psql cli that comes with PostgreSQL

v2.1.1 2025-10-29 08:15 UTC

Requires

• php: ~8.4.0 || ~8.5.0
• ext-pgsql: *

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.89.1
• phpstan/phpstan: ^2.1.31
• phpstan/phpstan-phpunit: ^2.0.7
• phpstan/phpstan-strict-rules: ^2.0.7
• phpunit/phpunit: ^12.4.1

MIT

• Filippo Tessarotto

• postgres
• psql

README

PHP light version of psql that comes with PostgreSQL.

Why

1. You are inside a PHP only environment, like a PHP Docker image
2. You need to import a large pg_dump --inserts dump
3. You don't have access to the native psql client

Performance

Speed is exactly the same of the original psql binary thanks to streams usage.

Supported formats

Input type	Example	Supported?
pg_dump output (with COPY commands)	as is	❌
pg_dump --inserts output	as is	✔️
Single query on single line	SELECT NOW();	✔️
Single query on multiple lines	SELECT NOW();	✔️
Multiple queries on separated single or multiple lines	SELECT NOW(); SELECT NOW();	✔️
Multiple queries on single line	SELECT NOW();SELECT NOW();	❌

When using pg_dump --inserts it is highly recommended to also set --rows-per-insert=1000 to speed performances up.

Usage

The library provides two usages, the binary and the \SlamPsql\Psql class.

From CLI

$ ./psql -h
Usage: psql [OPTIONS]
  -h, --host              Connect to host
  -p, --port              Port number
  -U, --username          User for login
  -d, --dbname            Database to use
	  --connect_timeout   Connect timeout to use, in seconds

  Use `PGPASSWORD` env variable to set the connection password.

$ printf "CREATE DATABASE foobar;\nSELECT datname FROM pg_database;" | ./psql
foobar

$ ./psql --database foobar < foobar_huge_dump.sql

From PHP

$psql = new \SlamPsql\Psql('localhost', 5432, 'my_username', 'my_password', 'my_database');
$return = $psql->run(\STDIN, \STDOUT, \STDERR);
exit((int) (true !== $return));

// With the connect_timeout argument
$psql = new \SlamPsql\Psql('localhost', 5432, 'my_username', 'my_password', 'my_database', 5);
$return = $psql->run(\STDIN, \STDOUT, \STDERR);
exit((int) (true !== $return));

\SlamPsql\Psql::run accepts any type of resource consumable by fgets/fwrite functions.