ci-pg-restore

library1.4.1jsnpmunverified

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.

database devops testing

npm install ci-pg-restore

github ↗package ↗

INSTALL

IMPORT

SIG · CI-PG-RESTORE

ci-pg-restore

databasejavascriptv1.4.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

This shows how to restore a database dump from dump.sql into testdb using caching with name my-cache.

ci-pg-restore -d testdb --cache-name my-cache --deps-files "dump.sql" "psql -f dump.sql"

ci-pg-restore --version

Debug

Known issues

gotchaThe 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.

affects: all

gotchaCache 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.

affects: all

gotchaThe --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).

affects: all

gotchaConcurrent 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.

affects: all

Errors

Common errors & fixes

psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL: database "testdb" does not exist

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: ci-pg-restore: command failed with exit code 1: psql -f dump.sql

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: ci-pg-restore: dependency file 'some/**/file.sql' does not match any files

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.

Upgrade

Version history

1.4.1latest on npm

Audit

Dependencies

pythonrequiredci-pg-restore is a Python CLI tool, requires Python interpreter to run

postgresql-clientrequiredRequires psql and pg_dump command-line tools for database operations

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/dimikot/ci-pg-restore ↗

packagehttps://www.npmjs.com/package/ci-pg-restore ↗