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

> Migrate to DB-GPT v0.7+ easily. Update configurations, import statements, and run database migrations with our clear guide for a seamless transition to the new modular architecture.

- Repository: [eosphoros/DB-GPT](https://github.com/eosphoros-ai/db-gpt)
- Tags: migration-guide
- Published: 2026-02-23

---

**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:

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

```

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

```bash
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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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:

```python

# 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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/pyproject.toml). Install only the dependencies you require:

```bash

# 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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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:

```bash
dbgpt db migration init

```

### Generate and Apply Migrations

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

```bash

# 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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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:

```python
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:

```bash
dbgpt db migration clean -y

```

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

```bash
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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-core/src/dbgpt/util/_db_migration_utils.py) and CLI commands in [`packages/dbgpt-app/src/dbgpt_app/_cli.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-core/src/dbgpt/util/_db_migration_utils.py). Migration scripts are stored in `pilot/meta_data/alembic/` after initialization.