dbd

A CLI tool for managing SQL database schemas. Apply individual DDL scripts to databases, load staging data, export data, and generate DBML documentation for dbdocs.io.

• Apply a set of individual DDL scripts to a database
• Load staging data with post-process scripts for development/testing
• Export data from tables & views
• Generate dbdocs DBML for all (or subset) tables
• Support for multiple schemas where names are unique across all schemas
• Parse files and identify dependencies (e.g. views depend on tables)
• Combine all scripts into a single file for deployment
• Support for multiple databases (e.g. postgres, mysql, mssql)
• Support for multiple schemas with the same names in multiple schemas

Architecture

DBD is organized as a monorepo with focused packages:

packages/
  cli/       @jerrythomas/dbd                  — CLI, config, design orchestrator
  db/        @jerrythomas/dbd-db               — Database operations abstraction
  dbml/      @jerrythomas/dbd-dbml             — DBML conversion & documentation
  postgres/  @jerrythomas/dbd-postgres-adapter — PostgreSQL adapter (parser + psql)
config/      — Tool configs (vitest, eslint, prettier, bumpp)

Dependency Flow

dbd (cli) -> dbd-db -> dbd-postgres-adapter
          -> dbd-dbml

Pre-requisites

Refer to the pre-requisites document for setting up the dbd cli.

Usage

Install the CLI globally using npm (or pnpm/yarn):

npm i --global @jerrythomas/dbd

Folder Structure

Individual DDL scripts are expected to be placed under folders with names of the database object types. Subfolders are used to specify the schema names. Files are expected to have the same name as the object.

example

Note: The CLI relies on dependencies mentioned in a YAML file (design.yaml) to execute scripts in sequence. Refer to the example folder.

Commands

Command	Action
dbd init	Create an example repo
dbd inspect	Inspect and report issues
dbd combine	Combine all into single script
dbd apply	Apply the creation scripts
dbd import	Load seed/staging files
dbd export	Export tables/views
dbd dbml	Generate DBML files
dbd graph	Output dependency graph as JSON

LLM Documentation

Machine-readable docs for using dbd with AI assistants: docs/llms/

Development

# Install dependencies
bun install

# Run all unit tests
bun run test

# Run specific package tests
bun test:cli
bun test:db
bun test:dbml
bun test:postgres

# Coverage
bun run coverage

# Format and lint
bun run format
bun run lint

Packages

Package	Description
@jerrythomas/dbd	CLI commands, configuration loading, Design class orchestration
@jerrythomas/dbd-db	Database adapter abstraction, entity processing, dependency resolution
@jerrythomas/dbd-dbml	DBML conversion via @dbml/core with schema qualification
@jerrythomas/dbd-postgres-adapter	PostgreSQL adapter with SQL parser and reference classifier