podil

library0.3.7jsnpmunverified

Podil is a lightweight and secure Postgres migration tool for Node.js, designed to run migrations automatically on application startup. The current stable version is 0.3.7, released with a focus on simplicity and security. It features checksum verification of migration scripts to prevent accidental schema corruption, and has no runtime dependencies beyond a PostgreSQL client (pg). Unlike other migration tools, Podil emphasizes minimalism and security, with built-in checksum storage and verification. It supports custom migration directories and optional checksum disabling. The package ships TypeScript types and requires the 'pg' package as a peer dependency. Release cadence is irregular; it is actively maintained.

database

npm install podil

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PODIL

podil

databasejavascriptv0.3.7

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.

podil

✓ import { podil } from 'podil'

✗ import podil from 'podil'

Named import required; podil is not a default export. Works with both ESM and TypeScript.

migrate

✓ import { podil } from 'podil'; await podil.migrate(...)

✗ import { migrate } from 'podil'

The `migrate` function is a method of the `podil` object, not a separate export.

PodilOptions

✓ import type { PodilOptions } from 'podil'

TypeScript only; provides type checking for the config object.

Demonstrates importing podil, calling migrate with a connection string and options, including error handling.

import { podil } from 'podil'; import 'pg'; const connectionString = process.env.DATABASE_URL ?? 'postgres://user:pass@localhost:5432/mydb'; async function runMigrations() { try { await podil.migrate(connectionString, { migrationsDir: './migrations', // Default is './migrations' verifyChecksum: true, // Default is true }); console.log('Migrations completed successfully'); } catch (err) { console.error('Migration failed:', err); process.exit(1); } } runMigrations();

Debug

Known issues

breakingBreaking change: In version 0.3.0, the `podil` function was replaced with a named export `podil` object and the `migrate` method. Previously, `import podil from 'podil'` returned a function. Now it must be `import { podil } from 'podil'`.

fix

Update import to `import { podil } from 'podil'` and call `podil.migrate()` instead of `podil()`.

affects: <0.3.0

breakingThe `pg` package is a required peer dependency and must be installed explicitly. Missing pg will cause runtime errors.

fix

Run `npm install pg` alongside podil.

affects: >=0.0.0

gotchaMigration scripts are executed in lexicographical order of filenames. Ensure filenames are prefixed with numbers or timestamps to maintain correct order.

fix

Name files like '001__init.sql', '002__add_table.sql', etc.

affects: >=0.0.0

gotchaChecksum verification is enabled by default. If you modify a previously executed migration script, the checksum won't match and migration will fail. Disable checksum verification with `{ verifyChecksum: false }` or reset the migration history.

fix

Optionally set `verifyChecksum: false` in options, or ensure scripts are never modified after execution.

affects: >=0.0.0

Errors

Common errors & fixes

ERROR: pg is not installed. Please install pg as a dependency.

Missing peer dependency 'pg'.

fix

Run `npm install pg`.

TypeError: podil is not a function

Using default import instead of named import in version >=0.3.0.

fix

Change `import podil from 'podil'` to `import { podil } from 'podil'` and call `podil.migrate()`.

Error: Checksum mismatch for migration script '...'

A previously executed migration script has been modified after execution.

fix

If intentional, disable checksum verification with `{ verifyChecksum: false }` or restore the original script content.

Error: Migration '...' failed: relation "..." already exists

Attempting to create a table or object that already exists in the database.

fix

Add IF NOT EXISTS to SQL statements or ensure migrations are idempotent.

Upgrade

Version history

0.3.7latest on npm

Audit

Dependencies

pgrequiredPeer dependency for PostgreSQL client connections

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/podiljs/podil ↗

packagepodil ↗

homepagehttps://github.com/podiljs/podil#readme ↗