Aegis documentation

#PostgreSQL

The PostgreSQL cube owns the server, its cluster and the databases the platform creates. It renders postgresql.conf, pg_hba.conf and pg_ident.conf (all mode 0600) under postgresql.config_dir (/aegis/config/postgresql), keeps the cluster in postgresql.data_dir (/aegis/data/postgresql), the socket and pid in postgresql.run_dir and the server log in postgresql.log_dir. configure runs initdb once, when the data directory is empty, then creates the platform superuser from aegis.user / aegis.password.

The server runs as the keeper service aegis-postgresql under the postgresql.user account. Local connections use peer authentication, TCP uses scram-sha-256; every administrative statement runs through psql as the OS user over the socket.

#Common commands

Cube operations share one wrapper: ✔ postgresql: <detail> on success, ✖ <message> on failure (exit 1), and {"ok": true, "cube": "postgresql", "result": "<detail>"} with global --json.

expose is the only verb that prints a block instead of that line.

VerbEffect
configurecreate the service account, initialise the cluster if empty, render the three files, start, ensure the platform role
validaterun pg_isready against the socket and port
reloadsend SIGHUP to the postmaster: settings reload, connections stay
statusread data/postmaster.pid: running (pid N) or stopped
startstart the server through the keeper
stopSIGTERM, then SIGKILL after 15 seconds
restartstop, then start
exposeprint paths, port and socket, then publish the client tools
helpprint the command list with examples

#configure

bash
aegis cubes postgresql configureaegis --json cubes postgresql configure

Refuses a non-empty data directory that is not a cluster (data directory is not empty: <path>), so a mount point is never overwritten.

text
✔ postgresql: configuration written, server accepts connections{"ok": true, "cube": "postgresql", "result": "configuration written, server accepts connections"}

#validate

bash
aegis cubes postgresql validateaegis --json cubes postgresql validate

pg_isready only proves the server accepts connections; it does not authenticate.

text
✔ postgresql: server accepts connections{"ok": true, "cube": "postgresql", "result": "server accepts connections"}

#reload

bash
aegis cubes postgresql reloadaegis --json cubes postgresql reload

Sends SIGHUP; a stopped server fails with postgresql is not running.

text
✔ postgresql: configuration reloaded{"ok": true, "cube": "postgresql", "result": "configuration reloaded"}

#status

bash
aegis cubes postgresql statusaegis --json cubes postgresql status
text
✔ postgresql: running (pid 1601){"ok": true, "cube": "postgresql", "result": "running (pid 1601)"}

#start

bash
aegis cubes postgresql startaegis --json cubes postgresql start
text
✔ postgresql: started (pid 1601){"ok": true, "cube": "postgresql", "result": "started (pid 1601)"}

#stop

bash
aegis cubes postgresql stopaegis --json cubes postgresql stop

An immediate stop is not requested: the postmaster is asked to shut down and is killed only if it ignores the signal for fifteen seconds.

text
✔ postgresql: stopped (pid 1601){"ok": true, "cube": "postgresql", "result": "stopped (pid 1601)"}

#restart

bash
aegis cubes postgresql restartaegis --json cubes postgresql restart
text
✔ postgresql: stopped (pid 1601), started (pid 1633){"ok": true, "cube": "postgresql", "result": "stopped (pid 1601), started (pid 1633)"}

#expose

bash
aegis cubes postgresql exposeaegis --json cubes postgresql expose
text
cube           postgresqlinstalled      /aegis/apps/data/postgresql/18.7configuration  /aegis/config/postgresqlstate          running (pid 1601)pid            1601log            /aegis/logs/postgresql/postgresql.logconfig         /aegis/config/postgresql/postgresql.confdata           /aegis/data/postgresqlport           5432socket         /aegis/run/postgresqlpublished      /aegis/bin/psql, /aegis/bin/pg_dump, /aegis/bin/pg_restore, /aegis/bin/createdb, /aegis/bin/dropdb, /aegis/bin/pg_isready, /aegis/bin/initdb
text
{"ok": true, "cube": "postgresql", "installed": "/aegis/apps/data/postgresql/18.7", "configuration": "/aegis/config/postgresql", "state": "running (pid 1601)", "pid": "1601", "log": "/aegis/logs/postgresql/postgresql.log", "config": "/aegis/config/postgresql/postgresql.conf", "data": "/aegis/data/postgresql", "port": "5432", "socket": "/aegis/run/postgresql", "published": "/aegis/bin/psql, /aegis/bin/pg_dump, /aegis/bin/pg_restore, /aegis/bin/createdb, /aegis/bin/dropdb, /aegis/bin/pg_isready, /aegis/bin/initdb"}

#help

bash
aegis cubes postgresql helpaegis cubes help postgresql
text
ℹ Postgresql — PostgreSQL server, its cluster and databasesCommands  validate   Check the configuration  reload     Reload the running daemon  configure  Prepare the cluster and write config  start      Start the server  stop       Stop the server  status     Show whether the server runs  restart    Restart the server  expose     Show where it is installed and how it runs  databases  Manage databases

The list continues with users, tables, sequences and help, then the examples.

#Databases

#databases list

bash
aegis cubes postgresql databases listaegis --json cubes postgresql databases list

Lists every database whose datistemplate is false. The two templates are therefore absent; postgres is not a template and appears in the list.

text
✔ postgresql: aegis, postgres, shop{"ok": true, "cube": "postgresql", "result": "aegis, postgres, shop"}

#databases create

bash
aegis cubes postgresql databases create shopaegis --json cubes postgresql databases create analytics
ArgumentMeaning
namedatabase name; quotes and semicolons are refused

The owner is aegis.user, the platform superuser created by configure.

text
✔ postgresql: created shop (owner aegis){"ok": true, "cube": "postgresql", "result": "created analytics (owner aegis)"}

#databases drop

Destructive. Drops the database and everything in it. postgres, template0 and template1 are refused explicitly.

bash
aegis cubes postgresql databases drop shopaegis --json cubes postgresql databases drop analytics
ArgumentMeaning
namethe database to drop
text
✔ postgresql: dropped shop{"ok": true, "cube": "postgresql", "result": "dropped analytics"}

#Users

A role is cluster-wide; a grant is per database. users grant gives the role the database plus full rights on the tables, sequences and functions in its public schema, including default privileges for objects created later.

#users list

bash
aegis cubes postgresql users listaegis --json cubes postgresql users list

Login roles only, excluding pg_* internals and postgres.

text
✔ postgresql: aegis, app{"ok": true, "cube": "postgresql", "result": "aegis, app"}

#users add

bash
aegis cubes postgresql users add app --database shopaegis cubes postgresql users add reporting
OptionMeaning
namerole name; letters, digits, _, $, -
--passwordpassword; generated and printed when omitted
--databaseoptional database to grant immediately
text
✔ postgresql: user app created; app granted on shop{"ok": true, "cube": "postgresql", "result": "user reporting created; password: 3Jc9xQ2mR7tLk0pW"}

#users remove

Destructive. Drops the role. A role that still owns objects is refused with the count, so DROP OWNED BY never deletes data behind your back; only ACL entries and default privileges are cleared first.

bash
aegis cubes postgresql users remove appaegis --json cubes postgresql users remove reporting
ArgumentMeaning
namethe role to drop
text
✔ postgresql: user app dropped{"ok": true, "cube": "postgresql", "result": "user reporting dropped"}

#users password

bash
aegis cubes postgresql users password app --password 'new-secret'aegis --json cubes postgresql users password app --password 'new-secret'
OptionMeaning
namethe role
--passwordrequired new password
text
✔ postgresql: password changed for app{"ok": true, "cube": "postgresql", "result": "password changed for app"}

#users grant

bash
aegis cubes postgresql users grant app shopaegis --json cubes postgresql users grant reporting analytics
ArgumentMeaning
namethe role
databasethe database to grant
text
✔ postgresql: app granted on shop{"ok": true, "cube": "postgresql", "result": "reporting granted on analytics"}

#users revoke

Destructive. Revokes the database grant and the schema privileges. It does not drop objects the role owns.

bash
aegis cubes postgresql users revoke app shopaegis --json cubes postgresql users revoke reporting analytics
text
✔ postgresql: app revoked on shop{"ok": true, "cube": "postgresql", "result": "reporting revoked on analytics"}

#Tables

#tables list

bash
aegis cubes postgresql tables list shopaegis --json cubes postgresql tables list shop
ArgumentMeaning
databasethe database to inspect

Live row estimates from pg_stat_user_tables and total relation size.

text
✔ postgresql: orders (1204 rows, 8192 kB); sessions (12 rows, 48 kB){"ok": true, "cube": "postgresql", "result": "orders (1204 rows, 8192 kB); sessions (12 rows, 48 kB)"}

#tables vacuum

bash
aegis cubes postgresql tables vacuum shopaegis cubes postgresql tables vacuum shop --full
OptionMeaning
databasethe database
--fullrewrite the tables instead of only reclaiming dead rows

VACUUM (ANALYZE) without --full; VACUUM (FULL, ANALYZE) with it. A full rewrite takes an exclusive lock per table and needs free disk equal to the table size. The client timeout is one hour.

text
✔ postgresql: vacuum (analyze) done on shop{"ok": true, "cube": "postgresql", "result": "vacuum (full, analyze) done on shop"}

#tables analyze

bash
aegis cubes postgresql tables analyze shopaegis --json cubes postgresql tables analyze shop

Refreshes planner statistics without rewriting anything.

text
✔ postgresql: analyze done on shop{"ok": true, "cube": "postgresql", "result": "analyze done on shop"}

#tables reindex

bash
aegis cubes postgresql tables reindex shopaegis --json cubes postgresql tables reindex shop

Runs REINDEX DATABASE, outside a transaction, with the one-hour timeout.

text
✔ postgresql: reindexed shop{"ok": true, "cube": "postgresql", "result": "reindexed shop"}

#Sequences

Rows restored from a dump keep their ids while the sequence behind the column starts again at 1, so the next insert fails on a duplicate key. These commands find those sequences and move them past MAX(column).

#sequences list

bash
aegis cubes postgresql sequences list shopaegis cubes postgresql sequences list shop --schema public --table orders
OptionMeaning
databasethe database
--schemaonly sequences in this schema
--tableonly sequences owned by this table

Report only: it never calls setval. It prints ok lines as well, so an empty answer means there are no owned sequences at all.

text
✔ postgresql: public.orders.id seq=41 max=57 behind{"ok": true, "cube": "postgresql", "result": "public.orders.id seq=41 max=57 behind"}

#sequences sync

bash
aegis cubes postgresql sequences sync shopaegis cubes postgresql sequences sync shop --dry-run
OptionMeaning
databasethe database
--schemarestrict to one schema
--tablerestrict to one table
--dry-runreport what would change, write nothing
--allalso list sequences that are already in sync

Only sequences that are behind are moved; each is set to the current maximum, so the next insert gets the following value.

text
✔ postgresql: fixed 1 of 3 sequencespublic.orders.id seq=41 max=57 -> setval(57)
text
✔ postgresql: would fix 1 of 3 sequencespublic.orders.id seq=41 max=57 behind