dbplug

Databases as Packages — A simple CLI to set up, manage, and migrate databases without complex configuration.

Perfect for small teams and solo developers who want a fast, safe way to work with MongoDB, PostgreSQL, or MySQL.

Documentation

Complete guides and references: https://dbplug-docs.eklavyas.works/

This includes:

• Installation guides for each database (PostgreSQL, MySQL, MongoDB)
• Environment setup tutorials
• Detailed CLI command reference
• Data migration best practices
• Troubleshooting guides
• FAQ and advanced topics

What dbplug Does

• ✅ One-command setup for multiple databases in local, staging, and production
• ✅ Safe migrations with dry-run by default (no accidental data loss)
• ✅ Live schema inspection — see exactly what's in your database
• ✅ Data migration between databases (Postgres → Postgres, Postgres → MySQL, etc.)
• ✅ Environment management — local dev, staging, and production configs in one place

System Requirements

Before installing dbplug, make sure you have:

• Node.js 18+ (Download)
• npm 9+ (comes with Node.js)
• At least one database installed locally or accessible remotely:
  • PostgreSQL 12+ (Install)
  • MySQL 8+ (Install)
  • MongoDB 4.4+ (Install)

Installation

Option 1: Global Install (Recommended)

npm install -g dbplug

Then use from any project:

dbplug init --js --db postgresql --alias main

Option 2: Local Install in Project

npm install dbplug

Run with npx:

npx dbplug init --js --db postgresql --alias main

Option 3: Clone and Build from Source

git clone https://github.com/eklavyasingh/dbplug.git
cd dbplug
npm install
node ./bin/dbplug.js init --js --db postgresql --alias main

Quick Start (5 Minutes)

1. Initialize your project

dbplug init --js --db postgresql --alias main

This creates:

• db/dbplug.config.json — your database config
• .env.local — local database credentials
• db/schemas/main.schema.js — schema template

2. Connect to your database

Edit .env.local and add your database URL:

# For PostgreSQL
MAIN_POSTGRESQL_URL_LOCAL=postgresql://user:password@localhost:5432/mydb

# For MySQL
MAIN_MYSQL_URL_LOCAL=mysql://user:password@localhost:3306/mydb

# For MongoDB
MAIN_MONGODB_URL_LOCAL=mongodb://localhost:27017/mydb

3. Test the connection

dbplug connect test --env local

Expected output:

✓ main: ok

4. View your schema

dbplug introspect --env local

Shows all tables, columns, and indexes in your database.

This repository contains the initial implementation slice:

• CLI command surface
• Multi-database config
• Built-in environments: local, staging, production
• Starter schema generation
• Live introspection output for MongoDB/PostgreSQL/MySQL
• Schema diff mode (introspect --diff)
• Introspection output modes: json, markdown, both
• Diagnostics command (doctor)
• Migration engine with dry-run safe defaults
• Official driver-based connection checks for MongoDB, PostgreSQL, and MySQL

Data Migration v2.1 Features:

• Full cross-adapter migration (any DB → any DB: PostgreSQL ↔ MySQL ↔ MongoDB)
• Auto-schema creation from source table definitions
• Batched read/write with keyset pagination for scalability
• Persistent migration state and per-table progress tracking
• Resume capability for interrupted migrations
• Row filtering with SQL WHERE clauses
• Parallel multi-table migration
• Post-migration verification (row count matching)
• Conflict handling strategies (skip, replace)

Usage Guide

Database Management

Add another database to your project:

dbplug add postgresql --alias analytics
dbplug add mysql --alias reporting

Show current config:

dbplug config --show

Working with Different Environments

Use local, staging, or production with any command:

# Local development (uses .env.local)
dbplug connect test --env local

# Staging (uses .env.staging.local)
dbplug connect test --env staging

# Production (uses .env.production.local)
dbplug connect test --env production

Schema Inspection

View your database schema:

# JSON format (machine-readable)
dbplug introspect --env local --format json

# Markdown (human-readable report)
dbplug introspect --env local --format markdown

# Both formats
dbplug introspect --env local --format both

Compare your database against your schema files:

dbplug introspect --diff --env local

Running Health Checks

Check for common configuration issues:

dbplug doctor --env local

Checks:

• ✓ Missing environment variables
• ✓ Invalid connection URLs
• ✓ Network reachability
• ✓ Database driver versions

Database Migrations

Create a new migration:

dbplug migration create add_users_table --db main --env local

View pending migrations:

dbplug migration status --db main --env local

Run migrations (dry-run first):

# Preview what will change
dbplug migration up --db main --env local

# Actually apply the migrations
dbplug migration up --db main --env local --apply

Roll back migrations:

# Preview rollback
dbplug migration down --db main --env local --count 1

# Actually rollback
dbplug migration down --db main --env local --count 1 --apply

Data Seeds

Create a seed file:

dbplug seed create bootstrap --db main --env local

Run seeds:

# Preview
dbplug seed run --db main --env local

# Apply
dbplug seed run --db main --env local --apply

Data Migration (Moving Data Between Databases)

Copy data from one database to another (e.g., syncing to analytics DB or migrating to a different provider).

Basic migration:

# Preview (dry-run)
dbplug migrate --source main --target analytics --tables users,orders --env local

# Actually copy the data
dbplug migrate --source main --target analytics --tables users,orders --env local --apply

Advanced options:

# Copy only specific rows (e.g., active users)
dbplug migrate --source main --target analytics --tables users --where "status='active'" --env local --apply

# Migrate multiple tables in parallel (faster for large migrations)
dbplug migrate --source main --target analytics --tables users,orders,products --env local --parallel --apply

# Verify data integrity after migration (compare row counts)
dbplug migrate --source main --target analytics --tables users --env local --apply --verify

# Optimize for large tables with custom batch size
dbplug migrate --source main --target analytics --tables users --batch-size 2000 --env local --apply

# Resume an interrupted migration
dbplug migrate --source main --target analytics --tables users --env local --apply --resume

How it works:

1. Reads data from source table in batches
2. Automatically creates matching table in target database
3. Writes data with conflict handling (skip duplicates or replace)
4. Saves progress per table (can resume if interrupted)
5. Optionally verifies row counts match

Supported conversions:

• ✅ PostgreSQL ↔ PostgreSQL
• ✅ PostgreSQL ↔ MySQL
• ✅ PostgreSQL ↔ MongoDB
• ✅ MySQL ↔ PostgreSQL
• ✅ MySQL ↔ MySQL
• ✅ MySQL ↔ MongoDB
• ✅ MongoDB ↔ PostgreSQL
• ✅ MongoDB ↔ MySQL
• ✅ MongoDB ↔ MongoDB
• Any combination supported!

Troubleshooting

"Module not found" or "Cannot find package"

Issue: Missing Node.js or npm

# Check Node version
node --version    # Should be v18.0.0 or higher
npm --version     # Should be v9.0.0 or higher

Fix: Install Node.js from https://nodejs.org/

"Connection refused" or "ECONNREFUSED"

Issue: Database is not running or wrong connection string

# Check your .env.local file
cat .env.local

# Test the connection
dbplug connect test --env local

Fix:

• Make sure your database is running locally or accessible remotely
• Update connection URL in .env.local with correct host, port, username, password

"relation does not exist" during migration

Issue: Table name doesn't match exactly (schema mismatch)

# View all tables in source database
dbplug introspect --env local

# Look for the exact schema.table name, then use it:
dbplug migrate --source main --target analytics --tables schema_name.table_name --env local

"Access denied" or authentication errors

Issue: Wrong username or password in connection URL

Fix: Update .env.local with correct credentials:

# PostgreSQL format
MAIN_POSTGRESQL_URL_LOCAL=postgresql://username:password@localhost:5432/dbname

# MySQL format  
MAIN_MYSQL_URL_LOCAL=mysql://username:password@localhost:3306/dbname

# Make sure special characters in password are URL-encoded
# @ becomes %40, : becomes %3A, etc.

Slow migration for large tables

Issue: Default batch size might be too small

# Use larger batch size
dbplug migrate --source main --target analytics --tables big_table --batch-size 5000 --env local --apply

# Or use parallel migration for multiple tables
dbplug migrate --source main --target analytics --tables table1,table2,table3 --parallel --env local --apply

Configuration Files

After init, dbplug creates:

| File | Purpose | |------|---------| | db/dbplug.config.json | Database aliases and connections | | .env.local | Local database credentials | | .env.staging.local | Staging database credentials | | .env.production.local | Production database credentials | | db/schemas/ | Your database schema definitions | | db/migrations/ | Migration files created by you | | db/seeds/ | Seed data files | | db/data-migrations/ | Data migration state and progress |

Common Workflows

1. Local Development Setup

# Initialize with PostgreSQL
dbplug init --js --db postgresql --alias main

# Add .env.local with your local Postgres URL
echo 'MAIN_POSTGRESQL_URL_LOCAL=postgresql://user:pass@localhost:5432/mydb' >> .env.local

# Test connection
dbplug connect test --env local

# View schema
dbplug introspect --env local

2. Creating a New Database Schema

# Generate schema placeholder
dbplug generate schema --db main

# Edit db/schemas/main.schema.js with your models

# Create and run migrations
dbplug migration create init-schema --db main
# Edit the migration file...
dbplug migration up --db main --apply

3. Migrating Data Between Environments

# Copy production data to staging for testing
dbplug migrate --source main --target staging --tables users,orders --env production --apply --verify

4. Syncing to Analytics Database

# Keep analytics DB in sync with production
dbplug migrate --source main --target analytics --tables users,orders,events --env production --parallel --apply --verify

Documentation

Complete guides and references: https://dbplug-docs.eklavyas.works/

This includes:

• Installation guides for each database (PostgreSQL, MySQL, MongoDB)
• Environment setup tutorials
• Detailed CLI command reference
• Data migration best practices
• Troubleshooting guides
• FAQ and advanced topics

Support

• Issues: Open a GitHub issue
• Discussions: Start a GitHub discussion
• Email: [email protected]