pgterra

library0.2.19jsnpmunverified

pgterra (v0.2.19) is a declarative PostgreSQL schema management tool that generates SQL migration statements by comparing a target schema.sql file against the current state of a PostgreSQL database. Unlike imperative migration tools (e.g., knex, node-pg-migrate), users define the desired schema in a single SQL file and Terra computes the ALTER TABLE, CREATE INDEX, etc. statements needed to reach that state. Written in TypeScript with ESM-only distribution, it supports tables, columns, functions, triggers, sequences, constraints, indexes, enums, views, and procedures. Released under an MIT license with low release cadence, it is primarily a CLI tool (pgterra plan / apply) but can also be used programmatically. Requires Node >=18 and TypeScript ^5.8.3 as a peer dependency.

database devops

npm install pgterra

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PGTERRA

pgterra

databasejavascriptv0.2.19

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.

Terra

✓ import { Terra } from 'pgterra'

✗ import Terra from 'pgterra'

Named export since v0.2.0; default export was removed.

generateMigrationSQL

✓ import { generateMigrationSQL } from 'pgterra'

✗ const generateMigrationSQL = require('pgterra')

ESM-only package; require() will throw an error.

TerraOptions

✓ import type { TerraOptions } from 'pgterra'

Type export; use 'import type' to avoid runtime overhead.

Demonstrates programmatic usage: create a Terra instance, preview changes with plan(), then apply via apply().

// target.sql: CREATE TABLE users (id SERIAL PRIMARY KEY, email TEXT NOT NULL); import { Terra } from 'pgterra'; async function syncSchema() { const terra = new Terra({ connectionString: process.env.DATABASE_URL ?? 'postgres://user:pass@localhost:5432/mydb', schemaPath: './target.sql' }); const plan = await terra.plan(); console.log('Changes to apply:', plan); await terra.apply(); console.log('Schema up to date'); } syncSchema().catch(console.error);

Debug

Known issues

breakingTerra class must be instantiated with new – cannot call as function.

fix

Use `new Terra(options)` instead of `Terra(options)`.

affects: >=0.1.0

deprecatedDefault export deprecated in v0.2.0.

fix

Use named import: `import { Terra } from 'pgterra'`.

affects: >=0.2.0

gotchaPackage is ESM-only; CommonJS require() fails with ERR_REQUIRE_ESM.

fix

Use `import` syntax or dynamic import() in CommonJS projects.

affects: >=0.1.0

gotchaschema.sql must contain exactly the desired schema – Terra does not automatically merge multiple schema files.

fix

Combine all schema definitions into a single .sql file.

affects: >=0.1.0

gotchaDatabase connection uses DATABASE_URL env variable as fallback; individual env vars (DB_HOST, etc.) may cause connection failures if not all set.

fix

Prefer DATABASE_URL or ensure all DB_* variables are set.

affects: >=0.1.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/pgterra/dist/index.js from /path/to/yourfile.js not supported.

pgterra is ESM-only, but project uses CommonJS require().

fix

Convert to ES module (type: 'module' in package.json) or use dynamic import: `const { Terra } = await import('pgterra')`.

TypeError: Terra is not a constructor

Using Terra as a function instead of instantiating with new.

fix

Use `const terra = new Terra(options)`.

Error: No database connection provided

Missing DATABASE_URL or DB_* environment variables.

fix

Set DATABASE_URL or ensure DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD are all set.

Upgrade

Version history

0.2.19latest on npm

Audit

Dependencies

typescriptoptionalRequired as a peer dependency for type definitions and compilation.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/elitan/pgterra ↗

packagepgterra ↗

homepagehttps://github.com/elitan/pgterra#readme ↗