Skip to main content
Version: v0.8.3

Upgrade To v0.8.3

Overview​

This guide walks you through upgrading from v0.8.2 to v0.8.3. If you are using an earlier version, first follow the historical upgrade guides to upgrade sequentially to v0.8.2.

  • SQLite users: Back up your metadata database before upgrading. ORM-managed metadata tables and columns are created or migrated automatically when the DB-GPT service starts.
  • MySQL users: A database migration is required before starting the new version. Apply the incremental script under assets/schema/upgrade/v0_8_3/.
  • Frontend source builds: Next.js 16 requires Node.js >= 20.9.0. Node.js 20.19 is recommended and is the frontend build baseline for this release.

Observability data is stored separately in logs/observability.db by default and is not written to the primary business database.

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

ScriptPurpose
upgrade_to_v0.8.3.sqlIncremental script for upgrading an existing v0.8.2 MySQL metadata database.
v0.8.3.sqlFull v0.8.3 schema for fresh installations.

Use upgrade_to_v0.8.3.sql when upgrading from v0.8.2. Do not run the full schema file against an existing database. After running the full schema for a fresh installation, you do not need to run the incremental script.

Upgrade​

Step 1 — Stop DB-GPT Service​

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

Existing MySQL deployments must complete the incremental upgrade before starting the new version. Skipping the migration leaves scheduled tasks without fields such as owner_id, resource_*, and lease_*, as well as the scheduled-run idempotency index. This can cause errors such as Unknown column and affect existing Scheduled Tasks and Dashboard functionality.

Step 2 — Upgrade Database​

The v0.8.3 metadata upgrade adds 10 columns and related indexes to 3 existing tables and creates 19 new metadata tables.

Column and Index Changes

ObjectChangeDescription
dbgpt_serve_scheduled_taskAdd owner_id, resource_type, resource_id, lease_owner, and lease_expires_at, with related indexesSupports stable authorization identities, resource associations, mutually exclusive execution, and lease renewal.
dbgpt_serve_scheduled_runAdd output_resource_id, attempt_count, result_json, and idempotency_key, plus a unique (task_id, idempotency_key) indexRecords result resources, retry counts, and structured results while preventing duplicate execution.
chat_history_messageAdd trace_id and its indexAssociates chat messages with Agent execution traces.

New Dashboard and Uploaded-Dataset Tables

TableDescription
dbgpt_dashboardStores dashboard identity, ownership, source conversation, data source, current Schema, revision, status, and publication information.
dbgpt_dashboard_annotationStores AI annotation requests, target content, prompts, base revisions, review status, and proposed changes.
dbgpt_dashboard_auditRecords dashboard actions, actors, targets, request IDs, and audit details.
dbgpt_dashboard_coverStores owner-scoped dashboard cover images and their source revisions.
dbgpt_dashboard_edit_versionStores saved editing revisions, Schema snapshots, actors, sources, and operation IDs.
dbgpt_dashboard_folderStores owner-scoped dashboard folders.
dbgpt_dashboard_folder_itemStores dashboard membership in folders.
dbgpt_dashboard_live_shareStores continuously shared published definitions, cached results, expiration times, and revocation state.
dbgpt_dashboard_memberStores dashboard members and their access roles.
dbgpt_dashboard_operationStores editing operations and patches for idempotent application and revision tracking.
dbgpt_dashboard_revisionStores published Schema revisions, frozen data snapshots, validation results, and share-token hashes.
dbgpt_dashboard_shareStores fixed-revision share records, token hashes, expiration times, and revocation state.
dbgpt_dashboard_share_secretSeparately stores encrypted secrets used by authorized publishers to recover share links.
dbgpt_uploaded_datasetStores uploaded-dataset ownership, source conversations, materialized database information, manifests, relationships, and processing status.

New Traceable-Report Tables

TableDescription
dbgpt_reportStores owner-scoped report identity, source conversation, title, latest run, and latest revision.
dbgpt_report_runStores immutable report-run snapshots, revisions, protocol versions, trigger types, and complete report documents.
dbgpt_report_artifactStores execution artifacts and their producing conversations, steps, messages, tasks, and execution runs.
dbgpt_report_artifact_dependencyStores execution-lineage relationships between input and dependent artifacts.
dbgpt_report_evidenceStores evidence bindings between report blocks and artifacts, including evidence roles and source/target selectors.

For MySQL metadata databases, run the incremental upgrade script:

mysql -u <user> -p dbgpt < assets/schema/upgrade/v0_8_3/upgrade_to_v0.8.3.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.

warning

The incremental script uses direct ALTER TABLE ... ADD COLUMN and ADD INDEX statements on existing tables. These statements are not repeatable. Run the script only once against a clean v0.8.2 database. If you previously ran an older Dashboard SQL script or manually applied part of the DDL, compare the existing columns and indexes first and apply only the missing items.

Step 3 — Install Dependencies​

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

uv sync --all-packages

To use the Qdrant vector store and configurable metadata Payload indexes, install the corresponding extra:

uv sync --all-packages --extra "storage_qdrant"

If you build the frontend from source, use Node.js 20.19 or another version compatible with Next.js 16, then reinstall dependencies and run the production build:

cd web
yarn install
yarn build

LocalRuntime remains the default Sandbox runtime. Explicitly select a container backend only when container isolation is required, and prepare an available daemon and Agent image in advance:

export SANDBOX_RUNTIME=docker
export SANDBOX_AGENT_IMAGE=dbgpt-sandbox-agent:latest

An explicitly selected container runtime does not fall back to local execution when initialization or execution fails.

To create Payload indexes for Qdrant metadata filtering fields, configure them as needed. No additional indexes are created when this setting is unset:

export QDRANT_METADATA_INDEXES="session_id,page:integer"

For both new and existing collections, DB-GPT creates configured indexes that are missing when the service starts.

For production Dashboard deployments, configure trusted authentication and a data-source authorization policy when enabling Dashboard production mode. Production collaboration requires Redis; without collaboration configuration, the related API is unavailable, but standard chat and Dashboard services can still start.

Step 4 — Start DB-GPT Service​

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

After startup, verify that:

  • Existing conversations and Scheduled Tasks load without missing-column or missing-index database errors.
  • Traceable reports can be generated, reopened, and reviewed through SQL, Python, knowledge citations, and evidence graphs.
  • Dashboards can complete plan confirmation, draft editing, saving, publishing, and sharing, with data-source authorization and revision-conflict checks working as expected.
  • The observability overview, Trace list, Trace details, and in-conversation Trace are available.
  • Wiki-enabled knowledge spaces generate directories, pages, and link graphs, and incrementally update them when documents are added.
  • Model providers connect successfully, model enablement takes effect, and enabled models are restored after a service restart.
  • The Sandbox runtime reported in tool-execution logs matches your configuration; an explicitly selected unavailable container runtime returns an error instead of falling back to local execution.

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

If the incremental script stops partway through, do not rerun the entire script against the partially upgraded database. Restore the clean v0.8.2 backup before correcting the issue and running the migration again, or manually reconcile the remaining statements after verifying exactly which columns, indexes, and tables already exist.