nexusql

library0.9.10jsnpmunverified

nexusql is a database migration toolkit for PostgreSQL that uses DBML (Database Markup Language) schema definitions to generate and apply migration SQL. Current stable version is 0.9.10. It is actively maintained with weekly releases. Unlike other migration tools, nexusql integrates with migra (a Python diffing engine) to produce accurate migration SQL by comparing the live database schema against the DBML file. It also generates TypeScript type definitions from the schema, making it particularly useful for full-stack TypeScript projects. Major features include CLI commands for initialization, migration generation, applying/rolling back migrations, and type generation. The tool bundles most dependencies except migra, which must be installed separately via pip.

database devops

npm install nexusql

package ↗

INSTALL

IMPORT

SIG · NEXUSQL

nexusql

databasejavascriptv0.9.10

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.

cli

✓ npx nexusql <command>

✗ npm install -g nexusql && nexusql (works but npx avoids global install)

nexusql is primarily a CLI tool; no programmatic API is exposed. Use npx for one-off usage.

DBML schema syntax

✓ Table users { id uuid [pk] }

✗ Table users { id uuid PRIMARY KEY }

nexusql uses DBML syntax (square brackets for annotations), not raw SQL DDL. Common mistake: using SQL keywords like PRIMARY KEY, NOT NULL instead of DBML equivalents.

TypeScript type generation

✓ nexusql types -o types/db.d.ts

✗ npm run types (custom script required)

nexusql does not expose a JavaScript/TypeScript API; type generation is via CLI command only.

Shows complete setup: install migra, nexusql, init project, configure DB URL, create DBML schema, and run migration.

# Ensure migra is installed pip install migra # Install nexusql globally (or use npx) npm install -g nexusql # Initialize project nexusql init # Set your database URL in .env cat > .env <<EOF DATABASE_URL=postgres://user:password@localhost:5432/mydb EOF # Create schema.dbml cat > schema.dbml <<EOF Table users { id uuid [pk, default: `uuid_generate_v4()`] email varchar(255) [unique, not null] name varchar(255) created_at timestamp [default: `now()`] } EOF # Generate and apply migrations nexusql migrate -a -y

Debug

Known issues

breakingNode.js version must be >=18.

fix

Upgrade Node.js to version 18 or later.

affects: >=0.9.0

gotchamigra is an external Python dependency that must be installed via pip.

fix

Run 'pip install migra' before using nexusql.

affects: >=0.1.0

gotchaSpecial characters in DATABASE_URL password are handled automatically but must not be URL-encoded in the .env file.

fix

Set the password as-is in .env (e.g., password@123) and nexusql will encode it.

affects: >=0.9.4

deprecatedUsing SQL DDL keywords in schema.dbml is not supported; use DBML syntax.

fix

Replace SQL keywords like NOT NULL with DBML attributes such as [not null].

affects: >=0.1.0

Errors

Common errors & fixes

Error: Could not connect to database: getaddrinfo ENOTFOUND localhost

Database host not resolvable; local server not running or wrong host.

fix

Ensure PostgreSQL is running on localhost and check DATABASE_URL spelling.

Error: 'migra' is not recognized as an internal or external command

migra Python package not installed.

fix

Run 'pip install migra' and ensure Python is in PATH.

Error: Invalid schema: unexpected token 'PRIMARY'

Used SQL keywords instead of DBML syntax in schema.dbml.

fix

Replace 'PRIMARY KEY' with '[pk]' and use [unique, not null] etc.

Upgrade

Version history

0.9.10latest on npm

Audit

Dependencies

migra (Python)requiredExternal tool for diffing database schemas, required by nexusql to generate migration SQL

Node.js >=18requiredRuntime requirement; older versions not supported

Agent activity

16 hits · last 30 days

node

Resources

packagenexusql ↗