dbplug

Databases as Packages.

dbplug is a beginner-friendly backend infrastructure CLI that helps you set up and use databases with a simple package-like workflow.

Docs

https://dbplug-docs.eklavyas.works/

Current MVP Status

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

Install

npm install

Usage

Initialize dbplug in your project:

node ./bin/dbplug.js init --js --db mongodb --alias main

Add another database:

node ./bin/dbplug.js add postgresql --alias analytics
node ./bin/dbplug.js add mysql --alias reporting

Use a specific profile with commands:

node ./bin/dbplug.js connect test --env local
node ./bin/dbplug.js connect test --env staging
node ./bin/dbplug.js connect test --env production

Show config:

node ./bin/dbplug.js config --show

Generate schema placeholders:

node ./bin/dbplug.js generate schema

Generate schema for one DB alias:

node ./bin/dbplug.js generate schema --db main

Run live introspection report:

node ./bin/dbplug.js introspect

Choose introspection output mode:

node ./bin/dbplug.js introspect --format json
node ./bin/dbplug.js introspect --format markdown
node ./bin/dbplug.js introspect --format both

Markdown reports are exported to docs/db-introspection/*.introspection.md.

Run introspection and schema diff against local schema files:

node ./bin/dbplug.js introspect --diff

Run health diagnostics:

node ./bin/dbplug.js doctor --env local

Doctor checks:

• Missing environment variables
• Invalid URL format
• Network reachability
• Driver version mismatch

Run migration workflow (dry-run by default):

node ./bin/dbplug.js migration create sync-schema --db main
node ./bin/dbplug.js migration status --db main
node ./bin/dbplug.js migration up --db main
node ./bin/dbplug.js migration up --db main --apply
node ./bin/dbplug.js migration down --db main --count 1
node ./bin/dbplug.js migration down --db main --count 1 --apply

Migration safety guardrails:

node ./bin/dbplug.js migration up --db main --apply --lock-timeout 45000
node ./bin/dbplug.js migration up --db main --apply --force
node ./bin/dbplug.js migration down --db main --count 1 --apply --yes

Guardrails enabled on apply:

• Preflight schema drift check (fails unless --force)
• File lock + SQL advisory lock (where supported)
• SQL transactional execution (PostgreSQL/MySQL)
• Destructive operation confirmation (or --yes in non-interactive mode)

All migration commands also support --env <local|staging|production>.

Seed workflow (dry-run by default):

node ./bin/dbplug.js seed create bootstrap --db main
node ./bin/dbplug.js seed status --db main
node ./bin/dbplug.js seed run --db main
node ./bin/dbplug.js seed run --db main --apply
node ./bin/dbplug.js seed reset --db main
node ./bin/dbplug.js seed reset --db main --apply

CI-friendly JSON output mode:

node ./bin/dbplug.js seed status --db main --format json
node ./bin/dbplug.js seed run --db main --format json
node ./bin/dbplug.js seed run --db main --apply --format json
node ./bin/dbplug.js seed reset --db main --apply --format json

seed reset clears seed history only and does not delete database data.

Test configured connections (live connectivity):

node ./bin/dbplug.js connect test

The command now uses official drivers:

• mongodb for MongoDB
• pg for PostgreSQL
• mysql2 for MySQL

If a connection fails, dbplug prints an error code and a fix hint.

Local Readiness Checks

Run baseline checks before publishing:

npm test
npm run test:smoke
npm run pack:check

pack:check shows what would be published to npm.

Generated Files

After init:

• db/dbplug.config.json
• db/index.js
• db/schemas/*.schema.js
• .env.local
• .env.staging.local
• .env.production.local

After introspect / migrations:

• db/introspection/*.introspection.json
• db/introspection/*.diff.json (when --diff is used)
• docs/db-introspection/*.introspection.md
• db/migrations/*.json
• db/migrations/.migration-state.json

After seed workflow:

• db/seeds/<alias>/*.json
• db/seeds/.seed-state.json

Extended Schema Metadata

Schema models can now include richer metadata for diff/migration planning:

export default {
	models: {
		users: {
			fields: {
				id: { type: "uuid", primaryKey: true, nullable: false },
				email: { type: "string", nullable: false, unique: true },
				status: { type: "string", enum: ["active", "disabled"], default: "active" },
				org_id: {
					type: "uuid",
					references: { model: "orgs", field: "id", onDelete: "CASCADE" }
				}
			},
			indexes: [{ name: "idx_users_email", fields: ["email"], unique: true }],
			relations: [
				{
					name: "fk_users_org_id",
					fromField: "org_id",
					toModel: "orgs",
					toField: "id",
					onDelete: "CASCADE"
				}
			],
			enums: {
				users_status_enum: { values: ["active", "disabled"] }
			}
		}
	}
};

Next Milestones

1. Migration operation expansion (indexes, constraints, type-alter execution).
2. Typed query helpers and runtime validation.
3. Integration tests with containerized databases.
4. CI release workflow and prerelease channel.