Postgres Admin

@thomas/postgres-adminv2026.10.11.1· 15d agoBEHAVIORS

01README

Non-destructive PostgreSQL administration over a direct TCP connection (node-postgres). Reads databases, roles, permissions, tables, connections, and extensions. Runs admin DDL that does not touch data: create database/role, grant/revoke, rotate passwords, and an idempotent app_provision method that combines them. Never reads or writes table rows, never runs DROP or TRUNCATE, and does not accept arbitrary SQL.

02Behaviors1

@thomas/postgres-adminv2026.10.11.1postgres-admin.ts

Global Arguments

Argument	Type	Required	Description
host	string	yes	Postgres host or IP, e.g. postgres-host or 192.0.2.10
adminUser?	string	no	Admin/superuser login role used for every connection
adminPassword	string	yes	Admin password. Supply via vault: ${{ vault.get(<vault>, postgres/admin_password) }}
maintenanceDb?	string	no	DB to connect to for cluster-wide ops (CREATE DATABASE, role/db catalog reads)
identifierPattern?	string	no	Safe-identifier regex enforced (in addition to escaping) before any DDL

fn database_list(includeTemplates?: boolean)

List databases with owner/encoding/size (factory: one `database` per db). Read-only.

Argument	Type	Required	Description
includeTemplates?	boolean	no	Include template databases (template0/template1)

fn role_list()

List roles with attributes + memberships (factory: one `role` per role). Read-only; never reads passwords.

fn permissions_audit(database: string, role?: string)

Audit privileges for a database (optionally a single role). databasePrivileges and

Argument	Type	Required	Description
database	string	yes	Database to audit (connects to it)
role?	string	no	Role to scope the audit to; omit to list every role's table/usage grants

fn table_inspect(database: string, schema?: string, table: string)

Describe a table (or view, materialised view, foreign table): columns, primary key,

Argument	Type	Required	Description
database	string	yes	Database holding the table (connects to it)
schema?	string	no	Schema of the table
table	string	yes	Table, view or foreign table to describe

fn connections_list(database?: string, includeQuery?: boolean)

List backends from pg_stat_activity (factory: one `connection` per pid),

Argument	Type	Required	Description
database?	string	no	Filter to one database's backends
includeQuery?	boolean	no	Include the current `query` text, cut to its first 2,000 characters.

fn extension_list(database?: string)

List installed extensions per database (factory: one `extension` per db+ext).

Argument	Type	Required	Description
database?	string	no	One database; omit to fan out across all connectable databases

fn database_create(name: string, owner?: string, encoding?: string, template?: string, locale?: string)

Create a database (idempotent: returns the existing one as `unchanged`, not altered;

Argument	Type	Required	Description
name	string	yes	Database to create
owner?	string	no	Owning role; defaults to the admin login
encoding?	string	no	Only emitted when set; a non-default encoding usually needs template0
template?	string	no	Template database to copy; defaults to template1
locale?	string	no	Sets both LC_COLLATE and LC_CTYPE, e.g. en_GB.UTF-8

fn role_create(name: string, login?: boolean, password?: string, validUntil?: string, createDb?: boolean, createRole?: boolean, memberOf?: array)

Create a login/group role (idempotent: existing role returned as `unchanged`, not altered;

Argument	Type	Required	Description
name	string	yes	Role to create
login?	boolean	no	LOGIN (a user) when true, NOLOGIN (a group role) when false
password?	string	no	Supply via vault expression. Sent only as a SCRAM-SHA-256 verifier, never logged/echoed. Must not be empty
validUntil?	string	no	e.g. 2027-01-01 (a timestamp literal)
createDb?	boolean	no	Give the role CREATEDB
createRole?	boolean	no	Give the role CREATEROLE
memberOf?	array	no	Parent roles to GRANT to this role

fn role_password_set(name: string, password: string)

Set/rotate a role's password (ALTER ROLE … PASSWORD) from a vault value. Never echoes it.

Argument	Type	Required	Description
name	string	yes	Existing role whose password to set
password	string	yes	New password; supply via vault expression. Sent only as a SCRAM-SHA-256 verifier. Must not be empty

fn grant(database: string, privileges: array, role: string, schema?: string, objects?: array, allInSchema?: boolean, includeFuture?: boolean, defaultForRole?: string)

GRANT privileges on a database/schema/table/sequence to a role (optionally ALTER DEFAULT

Argument	Type	Required	Description
database	string	yes	Database the privileges apply in (or to, for database scope)
privileges	array	yes	Privileges to grant or revoke; TRUNCATE and ALL are not allowed
role	string	yes	Role that receives (or loses) the privileges
schema?	string	no	Required for schema/table/sequence scope
objects?	array	no	Specific table/sequence names. Leave empty when allInSchema=true
allInSchema?	boolean	no	Target every existing table/sequence in `schema` instead of `objects`
includeFuture?	boolean	no	Also ALTER DEFAULT PRIVILEGES for future objects in the schema.
defaultForRole?	string	no	FOR ROLE in ALTER DEFAULT PRIVILEGES: the role whose future objects the

fn revoke(database: string, privileges: array, role: string, schema?: string, objects?: array, allInSchema?: boolean, includeFuture?: boolean, defaultForRole?: string)

REVOKE privileges (mirror of grant). Idempotent (revoking an absent grant is a no-op).

Argument	Type	Required	Description
database	string	yes	Database the privileges apply in (or to, for database scope)
privileges	array	yes	Privileges to grant or revoke; TRUNCATE and ALL are not allowed
role	string	yes	Role that receives (or loses) the privileges
schema?	string	no	Required for schema/table/sequence scope
objects?	array	no	Specific table/sequence names. Leave empty when allInSchema=true
allInSchema?	boolean	no	Target every existing table/sequence in `schema` instead of `objects`
includeFuture?	boolean	no	Also ALTER DEFAULT PRIVILEGES for future objects in the schema.
defaultForRole?	string	no	FOR ROLE in ALTER DEFAULT PRIVILEGES: the role whose future objects the

fn app_provision(database: string, role: string, password?: string, owner?: string, schema?: string, createSchema?: boolean, tablePrivs?: array, includeFuture?: boolean)

Composite, idempotent 'new application' setup: create database + login role (vault password) +

Argument	Type	Required	Description
database	string	yes	Database to create (or reuse) for the app
role	string	yes	Login role to create (or reuse) for the app
password?	string	no	Login password for a NEW role (ignored if the role already exists). Must not be empty
owner?	string	no	Database/schema owner; defaults to `role`
schema?	string	no	Schema the role is provisioned in
createSchema?	boolean	no	CREATE SCHEMA IF NOT EXISTS, owned by `owner` (not for public)
tablePrivs?	array	no	Table privileges to grant. Defaults to SELECT, INSERT, UPDATE, DELETE
includeFuture?	boolean	no	Also grant on future tables and sequences. Defaults to true until the

Resources

database(infinite)— A database catalog record (owner/encoding/size)

role(infinite)— A role/user record (attributes + memberships); no password is ever read

permissions-audit(infinite)— Privilege audit for a database (optionally scoped to a role)

table(infinite)— A table's structure (columns/PK/indexes/constraints) — catalog only, no row data

connection(1h)— A backend from pg_stat_activity (point-in-time)

extension(infinite)— An installed extension in a database

grant-result(infinite)— Result of a grant/revoke operation

role-result(infinite)— Result of a role create / password rotation

app-provision(infinite)— Result of the composite app_provision (db + role + grants)

03Previous Versions2

2026.06.01.1May 31, 2026

Republish to clear a transient dependency-trust B from the 2026.05.30 publish (pg@8.21.0 was freshly released and not yet past the trust gate; pin unchanged). No code or README behavior changes.

2026.05.30.1May 29, 2026

04Stats

93 / 100

Downloads

Archive size

75.3 KB

Has README or module doc2/2earned
README has a code example1/1earned
README is substantive1/1earned
Most symbols documented1/1earned
No slow types (deprecated)1/1earned
Dependencies pass trust audit2/2earned
Has description1/1earned
Platform support declared (or universal)2/2earned
License1/2partial
no SPDX license declared
Verified public repository2/2earned

Repository

https://github.com/thomas-elliott/swamp-extensions

05Platforms

linux · x86_64 linux · aarch64 macOS · x86_64 macOS · aarch64 windows · x86_64

06Labels

#postgres #database #admin #rbac