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.