NAME
Langertha::Holmgang::Sim::Linux::Postgres - PostgreSQL on a simulated Linux server — psql, an SQL subset, pg_hba, settings, slots
VERSION
version 0.001
SYNOPSIS
# from the Linux simulator: psql, pg_lsclusters, pg_ctlcluster
my ( $out, $ok ) = Langertha::Holmgang::Sim::Linux::Postgres::psql( $dev, \@argv, $ctx, $as_user );
DESCRIPTION
A PostgreSQL cluster (Debian 12, version 15) on a device of type linux (cai-platform docs/entwurf-evals.md §3.3.1): the state lives under postgres of the device, configuration files under files, the service under services (name in postgres.service).
postgres:
service: postgresql@15-main
cluster: 15/main
port: 5432
conf: /etc/postgresql/15/main/postgresql.conf
auto_conf: /var/lib/postgresql/15/main/postgresql.auto.conf
hba: /etc/postgresql/15/main/pg_hba.conf
wal: /var/lib/postgresql/15/main/pg_wal # file with size (takes up space)
wal_base: 1G # what remains without slots
settings: { max_connections: 100, fsync: "on", … } # running values
hba_loaded: [ "local all postgres peer", … ] # loaded lines
roles: { postgres: { superuser: true, login: true }, app: { login: true, password: true } }
members: { app_rw: [ alice ] }
databases: { appdb: { owner: app_owner } }
schemas: { appdb.app: { owner: app_owner } }
tables: { appdb.app.orders: { owner: app_owner, n_live_tup: 1200, n_dead_tup: 0, size: 80M, reloptions: [] } }
grants: { "table:appdb.app.orders": { report: [SELECT] }, "schema:appdb.app": {…}, "database:appdb": {…} }
default_acl: [ { role: app_owner, schema: app, db: appdb, on: tables, grantee: report, privs: [SELECT] } ]
slots: { replica_a: { type: physical, active: true, retained: 64M } }
activity: [ { pid: 4001, count: 96, usename: api, datname: appdb, client_addr: 10.20.0.11, application_name: api,
state: idle, host: app1, service: api } ] # count: this many identical connections from pid on
Commands: psql (-U, -d, -h, -p, -c repeatable, -t, -A, -x, -X, -q, -l; user from sudo -u/su), within it SQL and \du, \dp, \ddp, \l, \dn, \dt, \d[+] table (columns from columns, options), \c, \conninfo; pg_lsclusters, pg_ctlcluster VER NAME start|stop|restart|reload|status.
SQL subset: SELECT over the views pg_stat_activity, pg_replication_slots, pg_stat_user_tables, pg_settings, pg_roles, pg_hba_file_rules, pg_database (datallowconn, datacl), pg_tables, pg_class, pg_file_settings (every line of the files, applied), pg_authid (superuser only) and real tables (row count), with WHERE, GROUP BY, ORDER BY, LIMIT and the functions count(*), pg_size_pretty, pg_wal_lsn_diff, pg_current_wal_lsn, pg_terminate_backend, pg_cancel_backend, pg_drop_replication_slot, pg_reload_conf, current_setting, version, pg_sleep(x) (also FROM pg_sleep(x): from log_min_duration_statement on, a line LOG: duration: … ms statement: … in the cluster's log, a runtime trace); pg_settings shows unit, vartype, boot_val, values in the base unit and the common settings with their default (source default); SHOW, ALTER SYSTEM SET|RESET, CHECKPOINT, VACUUM [FULL] [ANALYZE], ANALYZE, ALTER TABLE … SET|RESET (…), CREATE|ALTER|DROP ROLE/USER, GRANT/REVOKE (tables, all tables of a schema, schema, database, roles), ALTER DEFAULT PRIVILEGES [FOR ROLE r] [IN SCHEMA s] GRANT|REVOKE … ON TABLES, DROP TABLE|DATABASE|SCHEMA, TRUNCATE, DELETE FROM (change the state — the rules see it), CREATE [UNIQUE] INDEX [CONCURRENTLY] [name] ON table [USING method] (columns) and DROP INDEX (list indexes of the table: name, columns, method, unique). Anything beyond that is a simulation gap (neutral answer).
Effect: reload (systemctl reload, pg_ctlcluster … reload, SELECT pg_reload_conf()) rereads postgresql.conf, postgresql.auto.conf and pg_hba.conf; settings with context postmaster (max_connections, shared_buffers, listen_addresses …) take effect only after a restart (pending_restart). A restart ends all connections. Connections check the service, the role, pg_hba (loaded lines, first match wins) and the number of connections against max_connections. A dropped slot frees its WAL at the next CHECKPOINT.
Pure functions on the state, neutral.
service_event
service_event( $dev, $service, $verb ); # from the Linux simulator
Effect of start/restart/reload/stop of a service on PostgreSQL: its own service reads the configuration, a restart ends the connections; another service with pg_connect reconnects.
psql
my ( $out, $ok ) = psql( $dev, \@argv, $ctx, $os_user );
pg_lsclusters
my ( $out, $ok ) = pg_lsclusters( $dev, \@argv, $ctx );
Output of pg_lsclusters: header line and one line for the device's cluster with version, name, port and online/down per the service; empty without PostgreSQL on the device.
SUPPORT
Issues
Please report bugs and feature requests at https://github.com/Getty/langertha-holmgang/issues.
IRC
Join #langertha on irc.perl.org or message Getty directly.
CONTRIBUTING
Contributions are welcome! Please fork the repository and submit a pull request.
AUTHOR
Torsten Raudssus <torsten@raudssus.de>
COPYRIGHT AND LICENSE
This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.