pg-altergen

library3.4.0jsnpmunverified

A Node.js CLI tool for managing PostgreSQL schema changes by organizing database objects in SQL files and generating ordered migration scripts with automatic dependency resolution. Version 3.4.0. The tool automatically detects schemas, tables, views, functions, and procedures from source directories, resolves dependencies among them, and compiles an ordered alter.sql script. It can drop existing objects before recreating them, ensuring the target database matches definitions. Supports custom directory structures and multiple source directories. CLI-focused, designed for deterministic migrations with a binary search fallback for error isolation. Differentiators: automatic dependency ordering, object drop detection, and customizable config via altergen.json.

database

npm install pg-altergen

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PG-ALTERGEN

pg-altergen

databasejavascriptv3.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

pg-altergen CLI

✓ npx pg-altergen generate --config altergen.json

✗ pg-altergen --generate

The CLI is invoked via npx or global install. Use commands like 'generate' or 'migrate' with optional --config flag.

Programmatic API (if any)

✓ const altergen = require('pg-altergen');

✗ import altergen from 'pg-altergen';

The package is primarily a CLI tool. Check documentation for programmatic usage; may not be available or may be different.

Configuration file

✓ altergen.json

✗ pg-altergen.config.js

Configuration is via a JSON file named altergen.json by default, or specified with --config.

Shows the typical workflow: install, create SQL directory structure, configure altergen.json, generate migration script, then migrate.

// 1. Install globally npm install -g pg-altergen // 2. Create a project structure: // my-db-project/ // ├── altergen.json // └── sql/ // ├── 01_schemas/ // │ └── public.sql // ├── 02_tables/ // │ └── public.tbl_movie.sql // ├── 03_views/ // │ └── public.view_reviews_info.sql // ├── 04_functions/ // │ └── public.fn_insert_review.sql // ├── 05_procedures/ // │ └── public.pr_update_review.sql // └── ... // 3. altergen.json example: { "postgres": { "host": "localhost", "port": 5432, "database": "my_db", "user": "postgres", "password": "password" }, "source_dir": "./sql", "output_dir": "./migration", "drop_objects": true } // 4. Generate migration script: pnpx pg-altergen generate --config altergen.json // 5. Review generated script and migrate: pnpx pg-altergen migrate --config altergen.json

Debug

Known issues

gotchaAlways back up critical databases before running migration scripts. pg-altergen drops existing objects (if configured) and recreates them, which can lead to data loss.

fix

Run `pg_dump -h host -U user -d dbname > backup.sql` before using migrate command.

affects: >=0.0.0

gotchaSQL files must follow the naming convention: {schema}.{object_type_prefix}{name}.sql e.g., public.tbl_movie.sql. Object type prefixes are required for detection (tbl_, view_, fn_, pr_, etc.).

fix

Rename files to match the expected pattern. See documentation for valid prefixes.

affects: >=0.0.0

deprecatedThe '--generate' flag without command may be removed in future versions. Use 'generate' as a subcommand.

fix

Use `pg-altergen generate` instead of `pg-altergen --generate`.

affects: <4.0.0

gotchaDependency resolution may fail for complex or circular dependencies. In such cases, migration order might be incorrect.

fix

Manually order files within subdirectories if automated resolution fails. Use '--dry-run' to review order.

affects: >=0.0.0

breakingVersion 3.0.0 changed the configuration file format from `config.json` to `altergen.json`.

fix

Rename `config.json` to `altergen.json` and adjust structure. See migration guide.

affects: >=3.0.0 <3.0.0

Errors

Common errors & fixes

Error: Cannot find module 'pg-altergen'

pg-altergen is not installed globally or locally.

fix

Run `npm install -g pg-altergen` or `npm install --save-dev pg-altergen`.

No SQL files found in source directory

The source_dir in altergen.json does not contain the expected subdirectories or files.

fix

Ensure the source_dir exists and contains numbered subdirectories (e.g., 01_schemas) with SQL files matching naming conventions.

Migration failed: syntax error at or near ...

The generated SQL script contains invalid syntax, often due to ordering issues or missing dependencies.

fix

Review the generated alter.sql file and fix the problematic SQL statement. Use --dry-run to check for errors before actual migration.

Upgrade

Version history

3.4.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/Mrazbb/pg-altergen ↗

packagepg-altergen ↗

homepagehttps://github.com/Mrazbb/pg-altergen#readme ↗