guzu

library0.0.8jsnpmunverified

SQL-only migration manager for PostgreSQL that enforces immutable migrations with hash verification. Current version is 0.0.8, actively developed. Key differentiators: zero configuration, timestamped migration files, SQL-only (no ORM), built-in hash integrity checking to prevent tampering, and a seed command for migrating from other tools. Inspired by goose. Requires only PostgreSQL as a dependency.

database

npm install guzu

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GUZU

guzu

databasejavascriptv0.0.8

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.

default

✓ import guzu from 'guzu'

✗ const guzu = require('guzu')

ESM-only; package.json has type:module. CommonJS require will fail.

run

✓ import { run } from 'guzu'

run is the primary programmatic API. as of v0.0.8.

create

✓ import { create } from 'guzu'

create is an exported function for programmatic use, but CLI is the common usage.

Demonstrates programmatic creation and application of migrations with guzu.

// Ensure you have a PostgreSQL instance running // Create a migration file import { create, run } from 'guzu'; await create('add_users', { dsn: 'postgres://admin:password@localhost:5432', dir: './migrations' }); // Apply pending migrations await run({ dsn: 'postgres://admin:password@localhost:5432', dir: './migrations' });

Debug

Known issues

breakingMigration files are immutable once applied; hash mismatch prevents re-application.

fix

Use --force or redo command during development, or manually update the guzu_migrations table.

affects: >=0.0.0

gotchaThe -- +guzu up annotation is mandatory; missing it will cause migration to be ignored.

fix

Ensure every migration file starts with -- +guzu up.

affects: >=0.0.0

gotchaMigrations run inside a transaction by default; disabling transactions may leave partial state.

fix

Use -- +guzu NO TRANSACTION only if you understand the risks.

affects: >=0.0.0

gotchaDSN must be a valid PostgreSQL connection string; no error message hints at format issues.

fix

Verify DSN format: postgres://username:password@host:port/database

affects: >=0.0.0

deprecatedNo known deprecations in v0.0.8.

fix

N/A

affects: >=0.0.8

Errors

Common errors & fixes

Error: connect ECONNREFUSED ::1:5432

PostgreSQL not running or wrong host.

fix

Start PostgreSQL and verify DSN. Use localhost instead of ::1 if IPv6 is disabled.

Error: no migration files found

Migrations directory does not exist or contains no .sql files.

fix

Create the migrations directory and add .sql files with -- +guzu up annotation.

Error: migration file xxx.sql has no +guzu up annotation

Missing required annotation in migration file.

fix

Add -- +guzu up at the top of the SQL file.

Upgrade

Version history

0.0.8latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/garriguv/guzu ↗

packageguzu ↗

homepagehttps://github.com/garriguv/guzu ↗