Upgrade To v0.8.2

Overview

This guide walks you through upgrading from v0.8.1 to v0.8.2.

• SQLite users: Back up your metadata database before upgrading. The new metadata tables and columns are created automatically when the DB-GPT service starts.
• MySQL users: A database migration is required. Apply the incremental script under assets/schema/upgrade/v0_8_2/.

Prepare

Back Up Your Database

warning

To prevent data loss, always back up your metadata database before upgrading. Choose the backup method that matches your database type, such as mysqldump for MySQL or a file copy for SQLite.

Review the Upgrade Scripts

The v0.8.2 upgrade scripts are maintained in the repository under assets/schema/upgrade/v0_8_2/:

Script	Purpose
upgrade_to_v0.8.2.sql	Incremental script for upgrading an existing v0.8.1 MySQL metadata database.
v0.8.2.sql	Full v0.8.2 schema for fresh installations.

Use upgrade_to_v0.8.2.sql when upgrading from v0.8.1. Do not run the full schema file against an existing database.

Upgrade

Step 1 — Stop DB-GPT Service

Stop the running DB-GPT service using the same method you used to start it.

Step 2 — Upgrade Database

The v0.8.2 metadata upgrade adds one column, widens one column, and creates four new metadata tables.

Column Changes

Object	Change	Description
knowledge_space.index_methods	New nullable varchar(500) column	Stores the JSON list of selected index methods (for example ["VectorStore", "FullText", "KnowledgeGraph"]) used by Agentic Knowledge-Base Search.
gpts_messages.content	Change column type to longtext	Allows longer Agent messages and action reports to be stored. It also reconciles databases fresh-installed from v0.8.1.sql, where this column was still text.

New Tables

Table	Description
dbgpt_session_file	Stores owner-bound session and scheduled-task file metadata, stable public file IDs, managed storage URIs, inspection status, and task-file lineage.
code_graph_vertex	Stores AST-extracted code nodes (classes, functions, modules, etc.) for code-graph retrieval.
code_graph_edge	Stores structural relationships between code nodes (contains, calls, imports, etc.).
code_graph_meta	Stores per-knowledge-space graph metadata such as vertex/edge counts, build source, and build status.

For MySQL metadata databases, run the incremental upgrade script:

mysql -u <user> -p dbgpt < assets/schema/upgrade/v0_8_2/upgrade_to_v0.8.2.sql

If your metadata database name is not dbgpt, replace dbgpt with your actual database name or execute the SQL file in the correct database context.

tip

The incremental script starts with USE dbgpt;. If your metadata database uses a different name, update that line before running the script, or select the target database explicitly in your MySQL session.

Step 3 — Install Dependencies

Install or update dependencies according to your installation method. If you installed from source using the default setup, run:

uv sync --all-packages

If you plan to use the new optional integrations introduced in v0.8.2, install the corresponding extras as needed:

# Agentic Knowledge-Base Search and RAG dependencies
uv sync --all-packages --extra "rag"

# Milvus vector store
uv sync --all-packages --extra "storage_milvus"

Step 4 — Start DB-GPT Service

Restart the DB-GPT service using your preferred start method.

After startup, verify that:

• Existing conversations and knowledge spaces can still be loaded.
• Multiple files can be uploaded, previewed, removed, and analyzed in one conversation.
• Scheduled Tasks created from a conversation with attachments can access their frozen task files.
• Agentic Knowledge-Base Search can retrieve from the configured index methods and display source references.
• Parallel sub-agent tasks and interactive questions update correctly in the frontend.

Rollback Notes

If the upgrade fails, stop the DB-GPT service and restore the metadata database from the backup taken before the upgrade. Because v0.8.2 changes metadata schema, do not continue running a partially upgraded database.