nexusql

Database migration toolkit for PostgreSQL with DBML schema support and TypeScript type generation.

Generate migration SQL by comparing your DBML schema against your live database using migra.

Installation

npm install -g nexusql
# or
npx nexusql

nexusql bundles most dependencies for seamless installation and to prevent module resolution issues across different package managers and Node.js environments.

Prerequisites

You need to have migra installed:

pip install migra

Note: migra is an external Python tool used for schema diffing and must be installed separately.

Quick Start

1. Initialize your project:

nexusql init

2. Set your database URL in .env:

DATABASE_URL=postgres://user:password@localhost:5432/mydb

3. Create your schema in schema.dbml:

Table users {
  id uuid [pk, default: `uuid_generate_v4()`]
  email varchar(255) [unique, not null]
  name varchar(255)
  created_at timestamp [default: `now()`]
}

4. Generate and apply migrations:

nexusql migrate

Commands

| Command | Description | | -------------------------------- | ------------------------------------------- | | nexusql init | Initialize configuration and directories | | nexusql test-connection | Test database connection | | nexusql gen | Generate migration SQL from DBML schema | | nexusql migrate | Interactive: generate → create file → apply | | nexusql up | Apply all pending migrations | | nexusql down | Rollback applied migrations | | nexusql status | Show migration status | | nexusql types | Generate TypeScript definitions | | nexusql mark-applied <version> | Mark migration as applied without running |

nexusql test-connection

Test your database connection and verify credentials:

nexusql test-connection

This command will:

• Parse and validate your DATABASE_URL
• Display connection details (protocol, user, host, port, database)
• Attempt to connect to the database
• Show server information if successful

Note: If your password contains special characters like @, #, :, etc., keep them unencoded in your .env file. The tool will handle URL encoding automatically.

Example output:

Testing database connection...

Connection details:
  Protocol: postgresql
  User: myuser
  Host: localhost
  Port: 5432
  Database: mydb
  Password: ***@123

✓ Connection successful!

Server info:
  Current user: myuser
  Current database: mydb
  PostgreSQL version: PostgreSQL 15.3

nexusql gen

Generate migration SQL by diffing your current database against the DBML schema.

nexusql gen                    # Output to stdout
nexusql gen -o migration.sql   # Write to file
nexusql gen -v                 # Verbose output
nexusql gen -v                 # Verbose output

nexusql types

Generate TypeScript interfaces from your DBML schema:

nexusql types                  # Defaults to src/types/schema.d.ts
nexusql types -o lib/db.d.ts   # Custom output path

nexusql migrate

Interactive workflow that combines generation and file creation:

nexusql migrate                # Interactive mode
nexusql migrate -n "add_users" # Specify migration name
nexusql migrate -a             # Apply immediately
nexusql migrate -y             # Skip confirmations

nexusql up

Apply all pending migrations:

nexusql up
nexusql up --dry-run           # Preview migrations without applying

nexusql down

Rollback applied migrations:

nexusql down                   # Rollback last migration
nexusql down -s 2              # Rollback last 2 migrations
nexusql down --to 20230101...  # Rollback to specific version
nexusql down --dry-run         # Preview rollback

nexusql status

Show which migrations have been applied and which are pending:

nexusql status

nexusql mark-applied

Mark a specific migration version as applied without running the SQL (useful for resolving inconsistencies):

nexusql mark-applied 20240101120000

Configuration

Create nexusql.config.js in your project root:

module.exports = {
  // Path to DBML schema file
  dbmlFile: "./schema.dbml",

  // Migration files directory
  migrations: "./db/migrations",

  // PostgreSQL extensions to install in temp database
  extensions: ["uuid-ossp", "vector"],

  // Restrict to specific PostgreSQL schemas (optional, default: ['public'])
  // targetDbSchemas: ['public'],
};

Environment variables:

• DATABASE_URL - PostgreSQL connection string

Migration Format

Migrations use dbmate-compatible format:

-- migrate:up
CREATE TABLE users (
  id uuid PRIMARY KEY DEFAULT uuid_generate_v4(),
  email varchar(255) UNIQUE NOT NULL
);

-- migrate:down
DROP TABLE users;

How It Works

1. Reads your DBML schema and converts it to SQL
2. Creates a temporary database and loads the target schema
3. Uses migra to generate the diff between current and target
4. Creates a timestamped migration file
5. Tracks applied migrations in schema_migrations table

License

MIT