ci-pg-restore
raw JSON → 1.4.1 verified Sat Apr 25 auth: no javascript
A cached, performance-optimized PostgreSQL database restoration tool designed for CI environments. Current stable version is 1.4.1. It creates a template database once from a dump and clones it using CREATE DATABASE WITH TEMPLATE, significantly speeding up repeated restores. Key differentiators: concurrent-safe with automatic waiting, cache invalidation based on dependency files, and automatic cleanup of old cached and restored databases. It requires only psql and PGUSER/PGPASSWORD environment variables, making it lightweight and suitable for integration test matrices.
Common errors
error psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL: database "testdb" does not exist ↓
cause The specified database name does not exist; ci-pg-restore expects to create it, but the error might occur if the tool fails to create it.
fix
Ensure the PostgreSQL server is running and the user has permissions to create databases. Alternatively, manually create an empty database with the same name.
error ERROR: ci-pg-restore: command failed with exit code 1: psql -f dump.sql ↓
cause The restoration command (psql) failed, likely due to SQL errors in the dump file.
fix
Check the dump file for syntax errors or missing dependencies; run the command manually to debug.
error ERROR: ci-pg-restore: dependency file 'some/**/file.sql' does not match any files ↓
cause The glob pattern in --deps-files did not match any existing files.
fix
Verify the path or glob pattern; ensure files exist before running the tool. Use --deps-files-cmd for more dynamic file discovery.
Warnings
gotcha The tool assumes psql is installed and PGUSER/PGPASSWORD are set; missing these will cause silent failures or authentication errors. ↓
fix Ensure PostgreSQL client tools are installed and environment variables are configured before running ci-pg-restore.
gotcha Cache database names are derived from --cache-name and dependency file digests; manually managing these databases may cause conflicts. ↓
fix Do not manually create or drop databases whose names start with 'ci-pg-restore-cache-' or contain '-template-' suffix; let the tool handle them.
gotcha The --cache-db-max-age and --restore-db-max-age options accept time suffixes (s, m, h, d, w) but not 'y' for years; using an unsupported suffix will be ignored or cause an error. ↓
fix Use only supported suffixes: s, m, h, d, w (e.g., 30m, 8h, 3d).
gotcha Concurrent processes share the same cache; if one process corrupts the template database, others may fail. ↓
fix Ensure restoration commands are idempotent and not destructive; consider using database transactions or consistent dump files.
Install
npm install ci-pg-restore yarn add ci-pg-restore pnpm add ci-pg-restore Quickstart
ci-pg-restore -d testdb --cache-name my-cache --deps-files "dump.sql" "psql -f dump.sql"