Database migration toolkit for PostgreSQL with DBML schema support
npm install 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.
``bash`
npm install -g nexusqlor
npx nexusql
nexusql bundles most dependencies for seamless installation and to prevent module resolution issues across different package managers and Node.js environments.
You need to have migra installed:
`bash`
pip install migra
Note: migra is an external Python tool used for schema diffing and must be installed separately.
1. Initialize your project:
`bash`
nexusql init
2. Set your database URL in .env:
`bash`
DATABASE_URL=postgres://user:password@localhost:5432/mydb
3. Create your schema in schema.dbml:
`dbmluuid_generate_v4()
Table users {
id uuid [pk, default: ]now()
email varchar(255) [unique, not null]
name varchar(255)
created_at timestamp [default: ]`
}
4. Generate and apply migrations:
`bash`
nexusql migrate
| 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
| | Mark migration as applied without running |
Test your database connection and verify credentials:
`bash`
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
`
Generate migration SQL by diffing your current database against the DBML schema.
`bash`
nexusql gen # Output to stdout
nexusql gen -o migration.sql # Write to file
nexusql gen -v # Verbose output
nexusql gen -v # Verbose output
Generate TypeScript interfaces from your DBML schema:
`bash`
nexusql types # Defaults to src/types/schema.d.ts
nexusql types -o lib/db.d.ts # Custom output path
Interactive workflow that combines generation and file creation:
`bash`
nexusql migrate # Interactive mode
nexusql migrate -n "add_users" # Specify migration name
nexusql migrate -a # Apply immediately
nexusql migrate -y # Skip confirmations
Apply all pending migrations:
`bash`
nexusql up
nexusql up --dry-run # Preview migrations without applying
Rollback applied migrations:
`bash`
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
Show which migrations have been applied and which are pending:
`bash`
nexusql status
Mark a specific migration version as applied without running the SQL (useful for resolving inconsistencies):
`bash`
nexusql mark-applied 20240101120000
Create nexusql.config.js in your project root:
`js
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
Migrations use dbmate-compatible format:
`sql
-- migrate:up
CREATE TABLE users (
id uuid PRIMARY KEY DEFAULT uuid_generate_v4(),
email varchar(255) UNIQUE NOT NULL
);
-- migrate:down
DROP TABLE users;
`
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 targetschema_migrations` table
4. Creates a timestamped migration file
5. Tracks applied migrations in
MIT