Upgrade To v0.8.1

Overview

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

• SQLite users: Back up your metadata database before upgrading. The new metadata tables 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_1/.

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.1 upgrade scripts are maintained in the repository under assets/schema/upgrade/v0_8_1/:

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

Use upgrade_to_v0.8.1.sql when upgrading from v0.8.0. 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.1 metadata upgrade contains one column change and three new metadata tables.

Column Changes

Object	Change	Description
gpts_messages.content	Change column type to longtext	Allows longer Agent messages and execution traces to be stored.

New Tables

Table	Description
connector_instance	Stores MCP connector instances, encrypted credentials, transport/extra configuration, lifecycle status, user name, and system code.
dbgpt_serve_scheduled_task	Stores scheduled task definitions, cron expressions, enabled status, and frozen conversation snapshots for chat replay tasks.
dbgpt_serve_scheduled_run	Stores scheduled task run history, including status, start/end time, result summary, error message, and generated conversation ID.

For MySQL metadata databases, run the incremental upgrade script:

mysql -u <user> -p dbgpt < assets/schema/upgrade/v0_8_1/upgrade_to_v0.8.1.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.1, install the corresponding extras as needed:

# LiteLLM proxy provider
uv sync --all-packages --extra "proxy_litellm"

# Qdrant vector store
uv sync --all-packages --extra "storage_qdrant"

# Valkey cache / vector store
uv sync --all-packages --extra "storage_valkey"

Step 4 — Start DB-GPT Service

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

After startup, verify that:

• Existing conversations can still be loaded.
• MCP Connector pages can list, activate, and test connectors.
• Scheduled Tasks can be saved from completed conversations and show run history.
• Long-running ReAct/Data Agent conversations show task-plan and context-usage status.

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.1 changes metadata schema, do not continue running a partially upgraded database.