Database & Migrations

This boilerplate uses Drizzle ORM alongside PostgreSQL. Drizzle provides a true SQL-like experience with complete Type Safety, without the heavy overhead of traditional ORMs.

Architecture

Our schema definition is spread across the Domain pattern. Instead of having a massive schema.ts file in the infrastructure folder, each domain has its own entity.ts file.

Press enter or space to select a node. You can then use the arrow keys to move the node around. You can then use the arrow keys to move the node around, press delete to remove it and press escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or press escape to cancel.

The drizzle.config.ts file is configured to scan src/domain/**/entity.ts automatically to build the complete database schema.

---

Migration Workflow

When you modify an entity.ts file (e.g., adding a new column to a table), you need to synchronize those changes with the actual database.

1. Generate the Migration

Generates a .sql file in src/infrastructure/migrations/ containing the exact SQL commands needed to update the database.

bun db:migrate

It is highly recommended to commit these generated .sql files to your version control.

2. Apply (Push) the Migration

Executes the generated SQL files against your target PostgreSQL database.

bun db:migrate:push

3. Visualizing the Data (Drizzle Studio)

Drizzle comes with a built-in database visualizer. You can start it locally to inspect your tables and data directly from your browser.

bun db:studio

---

Best Practices

The CLI Generator

The fastest and safest way to create new tables and schemas is to use the built-in domain generator. It automatically creates the entity.ts ready for Drizzle.

bun gen:domain customer

Prepared Statements

For maximum performance, the boilerplate rules require using Prepared Statements for repetitive queries instead of raw dynamic queries. This is usually done inside your Domain Actions (src/domain/*/actions/*.ts).

CI/CD Pipeline

In a production deployment (like via Docker or GitHub Actions), migrations should be automatically applied BEFORE the new application version accepts traffic.

If deploying via Docker, you can run the migrations directly inside the container before starting the main process:

docker exec -it app_server bun db:migrate:push