LobeHub utilizes Drizzle ORM for its database schema management and migration workflows. This system ensures that the PostgreSQL schema remains consistent across different deployment environments, including Vercel Serverless, Docker standalone, and local development setups.
The migration workflow is built around the drizzle-kit CLI and a custom migration runner. It follows a declarative approach where the TypeScript schema definitions in packages/database/src/schemas/ serve as the source of truth packages/database/src/schemas/index.ts1-40
The following scripts in the root package.json drive the migration lifecycle:
| Command | Action | Description |
|---|---|---|
npm run db:generate | drizzle-kit generate && npm run workflow:dbml | Compares TypeScript schemas against the last snapshot, generates SQL files, and updates DBML package.json57 |
npm run db:migrate | cross-env MIGRATION_DB=1 tsx ./scripts/migrateServerDB/index.ts | Executes pending SQL migrations against the target database package.json58 |
npm run db:studio | drizzle-kit studio | Opens a GUI for exploring and editing the database locally package.json59 |
npm run db:visualize | dbdocs build docs/development/database-schema.dbml --project lobe-chat | Generates visual schema documentation from the DBML file package.json60 |
Sources:
The following diagram illustrates how a schema change moves from code to a deployed database.
Migration Lifecycle Diagram
Sources:
LobeHub maintains a strict history of database changes within packages/database/migrations/.
The _journal.json file acts as the manifest for all migration entries. Each entry includes an index, a version, a timestamp, and a unique tag.
0000_init was recorded at timestamp 1716982944425 packages/database/migrations/meta/_journal.json3-100005_pgvector added support for embedding storage packages/database/migrations/meta/_journal.json40-450006_add_knowledge_base introduced RAG infrastructure packages/database/migrations/meta/_journal.json47-520012_add_thread and 0030_add_group_chat expanded the conversation hierarchy packages/database/migrations/meta/_journal.json90-2200020_add_oidc and 0024_add_rbac_tables packages/database/migrations/meta/_journal.json146-178For every entry in the journal, there is a corresponding .sql file.
0121_add_work_registry_tables.sql contains the DDL for the latest work and task tracking entities packages/database/migrations/0121_add_work_registry_tables.sql which is tracked in the journal packages/database/migrations/meta/_journal.json306-310Sources:
To facilitate architectural reviews, LobeHub automates the generation of a Database Markup Language (DBML) file.
When npm run db:generate is executed, it automatically triggers npm run workflow:dbml package.json57 This ensures the docs/development/database-schema.dbml file is always in sync with the latest migrations.
The DBML file defines tables, columns, and relationships using a clean syntax:
id, slug, user_id, and chat_config docs/development/database-schema.dbml1-31threads reference topics.id via topic_id docs/development/database-schema.dbml140-142agents_user_id_idx docs/development/database-schema.dbml36 and topics_user_id_idx docs/development/database-schema.dbml89Sources:
The migration system is designed to handle different deployment constraints:
On Vercel, migrations are executed as part of the build process via build:vercel, which runs bun run db:migrate package.json53 This ensures the database is ready before the new application version goes live.
For Docker builds, the migration script is part of the deployment lifecycle. Developers can use npm run dev:docker:reset to clear and re-migrate a local Docker-based database environment package.json74
Deployment Data Flow
Sources:
Refresh this wiki