Version upgrades and migration

Read the sections below that apply to your upgrade range and prepare environment variables, database images, and other requirements before starting the target version.

docker compose down
docker compose up -d

Containers run database schema migrations at startup; you do not need to run SQL manually.

Bottom-left avatar → “System settings” → “About” on the left → System version should show the target version; docker compose logs asktable should contain no migration errors.

Check login, project permissions, historical content, and an actual query according to the relevant migration section before ending the maintenance window.

Confirm that the old instance has at least one system administrator and that all existing projects have valid owners. If users exist but there is no system administrator, private deployment migration stops rather than choosing an organization Owner arbitrarily. Restore the correct administrative identity in the old version first.

Follow this page's backup steps to stop application writes and back up the main database, the Workbook database if enabled, and asktable_data. Record the original image version. Migration removes ownerless projects; repair owner relationships before upgrading if those projects must be retained.

Keep AT_DEPLOY_MODE=local for private deployment and explicitly set AT_REGION: cn or AT_REGION: global in the main service environment. Region defaults to cn; later changes require identity data migration. Local always uses email as the account identifier.

Convert the old version's Google, GitHub, WeChat, email login, SMTP, and SMS settings that are still needed into environment variables. Fill OAuth ID/Secret and SMS URL/Key in pairs; see Deployment authentication configuration. Old database authentication configuration keys and the mandatory-phone-number switch are no longer configuration sources.

Existing Local WeCom/WPS integrations migrate into the default organization. Migration reports an error if existing enterprise configuration is incomplete; complete the original configuration first and retain a backup. After upgrading, the organization Owner/Admin manages these integrations under Profile → Organization → Enterprise integrations.

After confirming image tags and environment configuration, pull the target images and start them for online deployment. For offline deployment, use installation scripts and offline packages from the same release; see Private deployment (Docker).

docker compose pull
docker compose up -d
docker compose logs --since=10m asktable

Database migration runs before the application starts. If it fails, save the error logs and identify the cause; do not skip migration and open the service directly.

Log in with the original administrator account and confirm the default organization, members, and project ownership. New instances enter the organization name during initialization; upgraded instances can change the migration-generated name in organization settings.

Check that each project has exactly one owner, public/private categories are correct, and default permissions and explicit roles match expectations. Spot-check API Keys, historical conversations, analysis canvases, and Workbooks. Have an imported enterprise member verify the full login URL and organization membership, then verify email delivery and business queries.

The official postgres image does not include the pgvector extension. Switch to an image that includes it (the migration script installs the extension automatically):

asktable-pg:
  image: registry.cn-shanghai.aliyuncs.com/dminfra/pgvector:pg17   # Previously postgres:17

Compare against the latest Compose file in Private deployment (Docker). Remove the asktable_vdb service, the VDB_ADDRESS and VDB_API_KEY environment variables, and the qdrant_storage and qdrant_snapshots volumes.

docker compose pull
docker compose down
docker compose up -d

Startup automatically runs migration and installs the pgvector extension. If logs say the asktable_workbook database does not exist, create it as described in Private deployment (Docker).

Field vectors in old data sources are empty. Open each data source page and select “Settings” in the top bar → “Index maintenance” → “Rebuild Embedding”. A message indicates that rebuilding has started; semantic retrieval takes effect automatically when it finishes.