serened psql
serened psql is a PostgreSQL-compatible command-line client built into the serened binary — no separate installation required. It connects to a running SereneDB server over the PostgreSQL wire protocol and behaves like the standard psql client: on startup it attaches to the server and switches to the requested database, so you can run queries interactively or in batch.
To work with a local database file directly, without a running server, use serened shell instead.
Connect
serened psql -h localhost -p 7890 -d postgres
When an option is omitted, the client falls back to the corresponding environment variable, then a built-in default:
| Setting | Flag | Default |
|---|---|---|
| Host | -h | $PGHOST, otherwise localhost |
| Port | -p | $PGPORT, otherwise 5432 |
| User | -U | $PGUSER, $USER, otherwise postgres |
| Database | -d | $PGDATABASE, otherwise the user name |
The first two positional arguments are taken as DBNAME and USERNAME when the matching flags are not given:
serened psql -h localhost -p 7890 postgres alice
The bootstrap superuser postgres connects locally without a password; other roles (and remote connections) authenticate with their role password. -W forces a password prompt, -w never prompts.
Running a single command
Use -c to run one statement and exit:
serened psql -h localhost -p 7890 -d postgres -c "SELECT 1 + 1 AS sum;"
┌───────┐
│ sum │
│ int32 │
├───────┤
│ 2 │
└───────┘
Browsing the documentation
.docs renders this documentation set inside the client, exactly as it does in
serened shell — same arguments, same
output. The pages come from the index compiled into the serened binary rather than from
the server, so a newer client shows its own documentation when connected to an older
server. That holds for --search too: it ranks in-process and never queries the
connected server.
serened psql -h localhost -p 7890 -d postgres -c ".docs BM25"
The sdb_docs tables and functions answer from that same
copy when you query them in serened psql, because queries run in the client. To read
the server's copy instead, the version that server actually runs, pass the query
through postgres_query with the database you connected to:
serened psql -h localhost -p 7890 -d postgres -c "SELECT path, title FROM postgres_query('postgres', 'SELECT path, title FROM sdb_docs.search(''vacuum'', 5)')"
Dot commands
serened psql accepts the same dot commands as
serened shell, from .mode and .timer to .docs. .help lists them.
Connection options
| Option | Description |
|---|---|
-h, --host=HOSTNAME | Server host (default: $PGHOST or localhost) |
-p, --port=PORT | Server port (default: $PGPORT or 5432) |
-d, --dbname=DBNAME | Database name (default: $PGDATABASE or the user name) |
-U, --username=NAME | User name (default: $PGUSER, $USER, or postgres) |
-w, --no-password | Never prompt for a password |
-W, --password | Force a password prompt |
General options
| Option | Description |
|---|---|
-c, --command=COMMAND | Run a single command (SQL or dot-command) and exit |
-f, --file=FILENAME | Execute commands from a file, then exit |
-l, --list | List the available databases, then exit |
-1, --single-transaction | Run the -c / -f batch inside a single transaction |
-X, --no-psqlrc | Do not read the startup file (~/.duckdbrc) |
-q, --quiet | Suppress startup and informational messages |
-V, --version | Print the SereneDB version and exit |
-?, --help | Show the help message and exit |
Output format options
The default output is the aligned duckbox table. These options change how results are rendered:
| Option | Description |
|---|---|
-A, --no-align | Unaligned output |
--csv | CSV output |
-H, --html | HTML output |
-t, --tuples-only | Print rows only, without column headers |
-x, --expanded | Expanded output (one value per line) |
-F, --field-separator=STR | Field separator for unaligned output (default |) |
-R, --record-separator=STR | Record separator for unaligned output (default newline) |
-o, --output=FILENAME | Send query results to a file |
-P, --pset=VAR[=ARG] | Set a printing option (format, expanded, null, tuples_only, pager) |
--MODE | Set the output mode directly (box, csv, json, markdown, line, …) |
Examples
List the databases on the server:
serened psql -h localhost -p 7890 -l
Run a SQL script and exit:
serened psql -h localhost -p 7890 -d postgres -f schema.sql
Export a query result as CSV:
serened psql -h localhost -p 7890 -d postgres --csv -c "SELECT 'a' AS x, 1 AS y;"
x,y
a,1
Run a script as a single transaction, writing the output to a file:
serened psql -h localhost -p 7890 -d postgres -1 -f migrate.sql -o result.txt