PostgreSQL development database management tool. Drop-in replacement for per-project database.sh / postgres-init.sh / postgres-cleanup.sh scripts. Provides database, postgres-init, and postgres-cleanup binaries.

Provided Binaries

Binary	Description
`database`	Main script for managing migrations, deployments, and logs.
`postgres-init`	Ephemeral PostgreSQL cluster initialization and startup.
`postgres-cleanup`	Graceful shutdown and cleanup of the PostgreSQL cluster.

Required Environment Variables

These variables must be set for db-tool to function.

Variable	Description
`LOCAL_DIR`	Absolute path to the project root directory.
`DB_URL`	Full PostgreSQL connection string (e.g., `postgresql://user@localhost/dbname?host=$PG_WORKING_DIR`).
`PG_WORKING_DIR`	Directory where the PostgreSQL cluster data and sockets are stored.

Optional Environment Variables

Variable	Default Value	Description
`DATABASE_DIR`	`${LOCAL_DIR}/db`	Root directory for database-related files.
`MIGRATION_DIR`	`${DATABASE_DIR}/migration`	Directory containing SQL migration files.
`DATABASE_SOURCE`	`${DATABASE_DIR}/src`	Directory containing source SQL files for hydration.
`PG_URL_VAR`	`PGURL`	The name of the environment variable where the computed PG URL will be exported.
`PG_LOG_PATH`	(unset)	Path to redirect PostgreSQL server logs.
`PG_CONF_FILE`	(unset)	Path to a `postgresql.conf` file. When set, replaces the script-generated config entirely on fresh init. `port` and `unix_socket_directories` are still appended at runtime (always overridden). When set, `PG_DISABLE_LOGGING` and `PG_SHARED_PRELOAD_LIBRARIES` are ignored.
`PG_SHARED_PRELOAD_LIBRARIES`	`pg_cron`	Comma-separated `shared_preload_libraries` value. Set to empty string to disable. Ignored when `PG_CONF_FILE` is set.
`PG_DISABLE_LOGGING`	`0`	Set to `1` to disable PostgreSQL logging collector. Ignored when `PG_CONF_FILE` is set.
`PG_HECTIC_INHERITANCE`	`1`	Apply the `hectic` inheritance bundle to the target database after init. Set to `0` to disable.
`HECTIC_INHERITANCE_SQL`	(auto)	Override path to the SQL file applied by `PG_HECTIC_INHERITANCE=1`. Defaults to the SQL shipped with `postgres-init`.
`PATCH_LOG`	(stdout)	Path to log the output of database patches.
`HYDRATE_LOG`	(stdout)	Path to log the output of database hydration.

Postgres Package Override

By default, db-tool/postgres-init/postgres-cleanup use plain postgresql_17 from nixpkgs. If you need extensions (e.g. pg_cron), override the postgres package per-output:

let
  myPg = pkgs.postgresql_17.withJIT.withPackages (_: [
    pkgs.postgresql_17.pkgs.pg_cron
  ]);
in {
  packages = [
    (pkgs.hectic."db-tool".override          { postgresql = myPg; })
    (pkgs.hectic."postgres-init".override    { postgresql = myPg; })
    (pkgs.hectic."postgres-cleanup".override { postgresql = myPg; })
  ];
}

pull_staging Contract

The pull_staging subcommand allows importing data from a remote staging environment into the local test-data.sql file. This functionality requires four specific environment variables to be defined:

STAGING_SSH_HOST: The SSH destination for the staging server.
STAGING_DB_URL: The PostgreSQL connection string for the remote staging database.
STAGING_DUMP_TABLES: A space-separated list of tables to include in the data dump.
STAGING_DUMP_FLAGS: Additional flags to pass to pg_dump (e.g., --column-inserts).

If any of these variables are missing when pull_staging is invoked, the tool will exit with code 3 and print the name of the missing variable to stderr.

Subcommands

deploy: Execute the full deployment flow (hydrate + patch). Supports --cleanup to teardown after success.
log: Inspect database logs. Supports list and index-based selection.
test: Execute database tests located in ${DATABASE_DIR}/test/test.sql.
check: Run a deployment validation in an isolated, temporary PostgreSQL cluster.
cleanup: Stop the local database cluster and remove the PG_WORKING_DIR.
pull_staging: Import data from the staging environment based on the env contract.
init: Wrapper around postgres-init to start the cluster.
migrator: Directly invoke the migration tool with the correct environment context.

shellHook Example

To use db-tool in a Nix development shell, add the following to your flake.nix or shell.nix:

{
  # ...
  devShells.default = pkgs.mkShell {
    packages = [
      pkgs.hectic.db-tool
      pkgs.hectic.postgres-init
      pkgs.hectic.postgres-cleanup
    ];

    shellHook = ''
      export LOCAL_DIR="$PWD"
      export DATABASE_DIR="$LOCAL_DIR/db"
      export MIGRATION_DIR="$DATABASE_DIR/migration"
      export DATABASE_SOURCE="$DATABASE_DIR/src"
      export PG_WORKING_DIR="$LOCAL_DIR/focus/postgresql"
      export DB_URL="postgresql://user@localhost/dbname?host=$PG_WORKING_DIR&port=5432"
      
      # for other non-db scripts (deploy.sh, task.sh, etc.):
      export HECTIC_LIB="${pkgs.hectic.helpers.posix-shell.log}"

      # Initialize and start the ephemeral database cluster
      . ${pkgs.hectic.postgres-init}/bin/postgres-init
    '';
  };
}

hectic Inheritance Bundle

pkgs.hectic.hectic-inheritance ships a SQL artifact that bootstraps a hectic schema with three parent tables and DDL event triggers:

hectic.created_at(created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()) — every user table must INHERITS (hectic.created_at). The event trigger hectic_enforce_created_at_inheritance raises an exception on CREATE TABLE otherwise.
hectic.updated_at(updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()) — optional. Any table that inherits from it automatically gets a BEFORE UPDATE FOR EACH ROW trigger calling hectic.set_updated_at() attached by hectic_attach_updated_at_trigger.
hectic.immutable() — pure marker. Tables inheriting it are blocked from INSERT/UPDATE/DELETE/TRUNCATE outside migration mode by triggers attached by hectic_attach_immutable_triggers. Useful for reference data that must only change via migrations. To allow DML inside a migration, wrap it in a transaction:
```
BEGIN;
SET LOCAL hectic.migration_mode = 'on';
INSERT INTO public.frozen (id, label) VALUES (1, 'x');
COMMIT;
```
SET LOCAL is required so the permission cannot leak past COMMIT.

Always-exempt schemas: hectic, information_schema, anything matching pg_*. Declarative partitions (relispartition = true) and temporary tables are also auto-exempt.

Per-database opt-out for additional schemas via the hectic.inheritance_extra_excluded_schemas GUC (comma-separated):

ALTER DATABASE mydb SET hectic.inheritance_extra_excluded_schemas = 'legacy,etl';

`db-tool diff` and immutable tables

database diff already includes immutable tables in its schema-level comparison (via pg_dump --schema-only). On top of that, when a hectic schema is present in either side, it appends an --- IMMUTABLE TABLE DATA --- section to the diff with a per-table unified diff of the rows of every table inheriting hectic.immutable. Drift in "frozen" reference data therefore surfaces in the same pager view as schema drift, and the subcommand exits non-zero when either differs.

Apply via `postgres-init`

Applied automatically. Set PG_HECTIC_INHERITANCE=0 to opt out.

Apply via `migrator` or any psql pipeline

# in your devshell
shellHook = ''
  export HECTIC_INHERITANCE_SQL=${pkgs.hectic.hectic-inheritance}/share/hectic/hectic-inheritance.sql
'';

psql "$DB_URL" -v ON_ERROR_STOP=1 -f "$HECTIC_INHERITANCE_SQL"

The SQL is also exposed via self.lib.hecticInheritance.sql (string) and self.lib.hecticInheritance.path (Nix path) for inline pipelines.

Exit Codes

Code	Meaning
1	Generic error.
2	Ambiguous arguments or state.
3	Missing required argument or environment variable.
5	Provided table does not exist.
9	Argument or command not found.
13	Program bug or unexpected system state.
127	Command not found (missing dependency).

README.md

db-tool