How to Migrate from Older DB-GPT Versions to the v0.7+ Modular Architecture

To migrate to DB-GPT v0.7+, upgrade your Python packages to the latest modular release, convert legacy .env configuration files to TOML format, update Python imports to use the new package namespaces like dbgpt_core and dbgpt_ext, and execute the Alembic database migration commands via the dbgpt db migration CLI.

DB-GPT v0.7 introduced a complete architectural overhaul, replacing the monolithic dbgpt package with six specialized modules. This guide provides a step-by-step migration path from v0.5 or v0.6 to the latest modular architecture in the eosphoros-ai/DB-GPT repository, covering configuration changes, import path updates, and database schema migrations.

Understanding the v0.7 Modular Architecture

The v0.7 rewrite splits functionality across six independent packages. Understanding this structure is essential for updating your imports and dependencies:

• dbgpt-core: Core interfaces for AWEL, model, agent, RAG, storage, datasource, and base abstractions
• dbgpt-ext: Extension implementations including vector stores, graph stores, datasource plugins, and model adapters
• dbgpt-serve: RESTful service layer for each module (no Python SDK)
• dbgpt-app: Business-level applications such as Chat, DataAnalysis, and Dashboard
• dbgpt-client: Unified Python SDK for remote API calls
• dbgpt-accelerator: Model inference acceleration (vLLM, llama.cpp, quantization)

Because import paths and configuration formats changed fundamentally, migration requires a two-step process: upgrading the codebase and adapting the database schema.

Step 1: Upgrade Codebase and Configuration

Install the Latest Modular Release

Update your environment to pull the new packages and migration utilities:

pip install -U "db-gpt[all]"

Verify the CLI entry point remains accessible (it now forwards to dbgpt-app commands):

dbgpt --help

Convert Configuration from ENV to TOML

DB-GPT v0.7 removed the .env loader entirely in favor of a TOML-based configuration system. Each module now maintains its own section within TOML files.

Replace your legacy .env file with the new TOML structure. Refer to the official release documentation at docs/blog/2025-03-24-dbgpt-v0.7.0-release.md in the repository for the complete configuration schema.

Update Python Import Paths

The original import dbgpt.xxx namespace no longer resolves. You must update all import statements to reference the new modular packages:

# Before v0.7 (monolithic package)

from dbgpt.core import AWEL
from dbgpt.rag import VectorStore
from dbgpt.model import ModelFactory

# After v0.7 (modular architecture)

from dbgpt_core.core import AWEL
from dbgpt_ext.storage.vector_store import VectorStore
from dbgpt_core.model import ModelFactory

If you use only specific components (e.g., just the vector store), you can import directly from the relevant extension package without pulling the entire stack.

Install Optional Dependencies

Each storage extension declares its own optional extras in pyproject.toml. Install only the dependencies you require:

# For vector store support (Chroma, Milvus, etc.)

pip install "db-gpt[vector]"

# For graph store support (TuGraph)

pip install "db-gpt[graph]"

# For specific database drivers

pip install "db-gpt[datasource]"

Step 2: Migrate the Database Schema

DB-GPT uses Alembic for database migrations. In v0.7, these commands are exposed through the dbgpt db migration CLI group, implemented in packages/dbgpt-app/src/dbgpt_app/_cli.py.

Initialize Migration Files

Run this once after installing v0.7 to create the pilot/meta_data/alembic directory:

dbgpt db migration init

Generate and Apply Migrations

Create a new migration script reflecting current model definitions, then apply it:

# Generate migration script

dbgpt db migration migrate -m "Upgrade to v0.7"

# Apply all pending migrations

dbgpt db migration upgrade

The underlying utilities live in packages/dbgpt-core/src/dbgpt/util/_db_migration_utils.py, which provides functions including create_migration_script() and _check_database_migration_status().

Execute Migrations via Python API

For advanced use cases or embedded deployments, execute migrations programmatically:

from dbgpt.util._db_migration_utils import (
    create_migration_script,
    _check_database_migration_status,
)

# Generate migration script

create_migration_script(alembic_cfg, engine, "Upgrade to v0.7")

# Verify and apply pending migrations

_check_database_migration_status(alembic_cfg, engine)

Reset Migration History (Optional)

To remove all Alembic scripts and start fresh:

dbgpt db migration clean -y

To drop every DB-GPT table and recreate a fresh schema (useful for test environments):

dbgpt db migration clean --drop_all_tables -y --confirm_drop_all_tables

Verify Your DB-GPT v0.7 Upgrade

Confirm the migration succeeded by completing these verification steps:

1. Start the server: Run dbgpt serve start or your custom entry point
2. Check configuration: Open the UI at http://localhost:5670 and verify the Configuration page displays TOML sections for each module (core, serve, app, etc.)
3. Test functionality: Execute a RAG query or Chat workflow to confirm the database schema migration completed successfully

If you encounter missing table errors, re-run dbgpt db migration upgrade or clean and re-initialize the database using the commands in Step 2.

Summary

• Upgrade Python packages to v0.7+ using pip install -U "db-gpt[all]" and install specific extras like [vector] or [graph] as needed
• Convert configuration from .env files to the new TOML-based system with module-specific sections
• Update import statements from the legacy dbgpt.xxx namespace to dbgpt_core.xxx or dbgpt_ext.xxx as appropriate
• Execute database migrations using dbgpt db migration init, migrate, and upgrade commands powered by Alembic
• Validate the installation by starting the server and testing core Chat or RAG functionality

Frequently Asked Questions

What breaking changes were introduced in DB-GPT v0.7?

DB-GPT v0.7 replaced the monolithic package structure with six independent modules (dbgpt-core, dbgpt-ext, dbgpt-serve, dbgpt-app, dbgpt-client, dbgpt-accelerator), switched from .env to TOML configuration files, and relocated all Python imports to new namespaces. The migration utilities in packages/dbgpt-core/src/dbgpt/util/_db_migration_utils.py and CLI commands in packages/dbgpt-app/src/dbgpt_app/_cli.py manage the transition.

Do I need to migrate my database when upgrading from v0.6 to v0.7?

Yes. The v0.7 architecture requires updating your persistent database schema using the built-in Alembic migration commands. Run dbgpt db migration init followed by dbgpt db migration upgrade to ensure compatibility with the new modular table structures and relationships.

Can I keep using .env files for configuration in DB-GPT v0.7?

No. Version 0.7 removed the .env loader completely. You must migrate your configuration to the TOML-based system, where each module maintains its own configuration section. Refer to the release blog at docs/blog/2025-03-24-dbgpt-v0.7.0-release.md for the complete TOML schema.

Where are the migration CLI commands defined in the source code?

The dbgpt db migration CLI group is registered in packages/dbgpt-app/src/dbgpt_app/_cli.py, while the underlying Alembic utilities (including create_migration_script and _check_database_migration_status) are implemented in packages/dbgpt-core/src/dbgpt/util/_db_migration_utils.py. Migration scripts are stored in pilot/meta_data/alembic/ after initialization.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}