{"id":18209,"library":"ci-pg-restore","title":"ci-pg-restore","description":"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.","status":"active","version":"1.4.1","language":"javascript","source_language":"en","source_url":"git://github.com/dimikot/ci-pg-restore","tags":["javascript","PostgreSQL","pg_dump","template","SQL"],"install":[{"cmd":"npm install ci-pg-restore","lang":"bash","label":"npm"},{"cmd":"yarn add ci-pg-restore","lang":"bash","label":"yarn"},{"cmd":"pnpm add ci-pg-restore","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"ci-pg-restore is a Python CLI tool, requires Python interpreter to run","package":"python","optional":false},{"reason":"Requires psql and pg_dump command-line tools for database operations","package":"postgresql-client","optional":false}],"imports":[],"quickstart":{"code":"ci-pg-restore -d testdb --cache-name my-cache --deps-files \"dump.sql\" \"psql -f dump.sql\"","lang":"javascript","description":"This shows how to restore a database dump from dump.sql into testdb using caching with name my-cache."},"warnings":[{"fix":"Ensure PostgreSQL client tools are installed and environment variables are configured before running ci-pg-restore.","message":"The tool assumes psql is installed and PGUSER/PGPASSWORD are set; missing these will cause silent failures or authentication errors.","severity":"gotcha","affected_versions":"all"},{"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.","message":"Cache database names are derived from --cache-name and dependency file digests; manually managing these databases may cause conflicts.","severity":"gotcha","affected_versions":"all"},{"fix":"Use only supported suffixes: s, m, h, d, w (e.g., 30m, 8h, 3d).","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure restoration commands are idempotent and not destructive; consider using database transactions or consistent dump files.","message":"Concurrent processes share the same cache; if one process corrupts the template database, others may fail.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"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.","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.","error":"psql: error: connection to server on socket \"/var/run/postgresql/.s.PGSQL.5432\" failed: FATAL:  database \"testdb\" does not exist"},{"fix":"Check the dump file for syntax errors or missing dependencies; run the command manually to debug.","cause":"The restoration command (psql) failed, likely due to SQL errors in the dump file.","error":"ERROR: ci-pg-restore: command failed with exit code 1: psql -f dump.sql"},{"fix":"Verify the path or glob pattern; ensure files exist before running the tool. Use --deps-files-cmd for more dynamic file discovery.","cause":"The glob pattern in --deps-files did not match any existing files.","error":"ERROR: ci-pg-restore: dependency file 'some/**/file.sql' does not match any files"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}