{"id":16484,"library":"pg-god","title":"pg-god: PostgreSQL Database Management","description":"pg-god is a focused JavaScript/TypeScript library (current stable version 1.0.12) designed to simplify the creation and deletion of PostgreSQL databases, both programmatically and via a command-line interface. Its primary function is to manage database lifecycles, often in development or testing environments where databases need to be frequently spun up and torn down. Key differentiators include its minimalist API for direct database creation/dropping, support for connection URLs (added in v1.0.9), and a default behavior since v1.0.6 to automatically terminate active connections before dropping a database, preventing common errors. It also provides explicit integration guidance for TypeORM users. The project appears to have a moderate release cadence, with recent updates refining CLI behavior and adding new features.","status":"active","version":"1.0.12","language":"javascript","source_language":"en","source_url":"https://github.com/ivawzh/pg-god","tags":["javascript","oclif","typescript"],"install":[{"cmd":"npm install pg-god","lang":"bash","label":"npm"},{"cmd":"yarn add pg-god","lang":"bash","label":"yarn"},{"cmd":"pnpm add pg-god","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"pg-god is primarily used with ES Modules due to its TypeScript origins and shipped types. While CommonJS might technically work, named imports are the idiomatic approach.","wrong":"const { createDatabase } = require('pg-god')","symbol":"createDatabase","correct":"import { createDatabase } from 'pg-god'"},{"note":"Use named imports for programmatic API functions.","wrong":"const dropDatabase = require('pg-god').dropDatabase","symbol":"dropDatabase","correct":"import { dropDatabase } from 'pg-god'"},{"note":"DbCredential is a TypeScript type; use 'import type' for type-only imports to ensure it's stripped from the JavaScript output.","wrong":"import { DbCredential } from 'pg-god'","symbol":"DbCredential","correct":"import type { DbCredential } from 'pg-god'"}],"quickstart":{"code":"import { createDatabase, dropDatabase, DbCredential } from 'pg-god';\n\nasync function main() {\n  const dbConfig = { databaseName: 'my_app_test_db' };\n  const credentials: Partial<DbCredential> = {\n    user: process.env.PG_USER ?? 'postgres',\n    password: process.env.PG_PASSWORD ?? '',\n    host: process.env.PG_HOST ?? 'localhost',\n    port: parseInt(process.env.PG_PORT ?? '5432', 10),\n    database: process.env.PG_INITIAL_DB ?? 'postgres', // Initial database to connect to\n  };\n\n  try {\n    console.log(`Attempting to create database: ${dbConfig.databaseName}`);\n    await createDatabase(dbConfig, credentials);\n    console.log(`Database '${dbConfig.databaseName}' created successfully.`);\n\n    // --- Your application logic or tests would go here ---\n\n    console.log(`Attempting to drop database: ${dbConfig.databaseName}`);\n    // dropConnections: true is default since v1.0.6, but explicit for clarity\n    await dropDatabase({ ...dbConfig, dropConnections: true }, credentials);\n    console.log(`Database '${dbConfig.databaseName}' dropped successfully.`);\n  } catch (error) {\n    console.error('An error occurred during database operation:', error);\n    // Attempt to clean up even if an error occurred after creation\n    try {\n        await dropDatabase({ ...dbConfig, dropConnections: true, errorIfNonExist: false }, credentials);\n        console.log(`Attempted cleanup for database '${dbConfig.databaseName}'.`);\n    } catch (cleanupError) {\n        console.warn(`Failed to clean up database '${dbConfig.databaseName}':`, cleanupError);\n    }\n    process.exit(1);\n  }\n}\n\nmain();","lang":"typescript","description":"Demonstrates programmatic creation and immediate dropping of a PostgreSQL database using environment variables for credentials and handling potential errors."},"warnings":[{"fix":"If you relied on `dropDatabase` failing when connections were active, you must now explicitly set `dropConnections: false` in the API call or use `--no-dropConnections` with the CLI. For most users, this change improves reliability and is the desired default.","message":"The default behavior for `dropDatabase` (both API and CLI `db-drop` command) changed in v1.0.6. It now automatically kills all active connections to the target database before dropping it. Previously, this required manual intervention or would fail if connections existed.","severity":"breaking","affected_versions":">=1.0.6"},{"fix":"Always provide explicit `DbCredential` objects to the API calls or use environment variables/CLI flags to specify correct user, password, host, and port for your PostgreSQL instance. For the CLI, consider using a connection URL with `--url`.","message":"By default, `pg-god` uses 'postgres' for the user and 'localhost:5432' for the host/port, with an empty password. This often works for local development setups, but will likely cause 'Password authentication failed' errors in production or secured environments if not explicitly configured.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Be mindful of these options. If you need strict behavior (e.g., ensuring a database is *only* created if it doesn't exist), set `errorIfExist: true`. For idempotent scripts where you don't care if the database exists or not, the defaults are usually fine.","message":"When using `createDatabase` or `dropDatabase`, the `errorIfExist` (for create) and `errorIfNonExist` (for drop) options default to `false` for the programmatic API, meaning it will silently succeed even if the database state doesn't change. However, if set to `true`, attempting to create an existing DB or drop a non-existent DB will throw an error.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure the `user` and `password` in your `DbCredential` object (or CLI flags/environment variables) match the PostgreSQL server configuration. Verify `pg_hba.conf` allows connections from your host with the specified authentication method.","cause":"The PostgreSQL server rejected the connection attempt due to incorrect credentials (username or password) or an invalid entry in `pg_hba.conf`.","error":"Password authentication failed for user \"your_user\""},{"fix":"If it's acceptable for the database not to exist, set `errorIfNonExist: false` in the `dropDatabase` call. Otherwise, ensure the database exists before attempting to drop it.","cause":"You are attempting to drop a database that does not exist, and `errorIfNonExist` is set to `true` (or implied by CLI usage).","error":"database \"your-db-name\" does not exist"},{"fix":"Ensure `dropConnections: true` (the default since v1.0.6) is used when calling `dropDatabase`. If this is not an option, you must manually terminate all connections to the database before dropping it.","cause":"Despite the default behavior since v1.0.6, this error can still occur if `dropConnections: false` is explicitly set, and there are active connections to the database you are trying to drop.","error":"cannot drop a database that is currently in use"}],"ecosystem":"npm"}