Skip to main content

​
Routine upgrade

The backend runs database migrations automatically on start. Below, migrations that need extra manual work are listed by version — only do the versions you cross.

​
Upgrade to the Organization release

This release places all users and projects in one default organization. The first SYS_ADMIN becomes the organization Owner; all other users become Members, and legacy public/private projects map to organization-public/private visibility. Existing project, API key, conversation, and dashboard IDs and content are preserved.
Back up PostgreSQL and asktable_data before upgrading. If the instance has no SYS_ADMIN, the migration fails instead of choosing an arbitrary Owner. Restore a system administrator on the old release first.
1

Back up and stop services

2

Pin the Region

Set AT_REGION: cn or AT_REGION: global in the asktable environment. It defaults to cn and is a static deployment setting; changing it later requires an identity-data migration. Local sign-in remains email-based regardless of Region.
3

Move deployment-level login configuration

Google, GitHub, WeChat, email login, SMTP, and SMS are no longer read from system settings or the database, and the legacy force-phone toggle is removed. Before starting the new release, put every configuration you still need into environment variables. OAuth IDs and secrets, plus the SMS URL and key, must be supplied as complete pairs. China cloud production requires complete WeChat and SMS configuration. See Deployment authentication.WeCom/WPS configuration is moved into the default organization and is managed under Personal settings → Organization → Enterprise integrations after the upgrade. The migration deletes the legacy authentication keys; rollback depends on the database backup taken before this step.
4

Pull and start the new release

The backend completes the Organization database migration before serving requests. If migration fails, do not loop restarts or bypass it; keep the logs and restore the backup.
5

Verify

Sign in as the existing administrator and verify the organization name, members, projects, API keys, conversations, and dashboards. Every project should have exactly one project owner, each legacy is_public value should map to the corresponding public or private category, and no VIEWER or anonymous project access should remain.
Fresh self-hosted installs ask for the organization name during setup. Upgraded instances receive a generated default-organization name, which the Owner can change from Organization settings inside personal settings. After the upgrade, projects and users are governed from the Organization section in personal settings; system settings no longer expose global project or user pages.
Cloud subscription, balance, and order migration must first pass preflight and reconciliation against a production snapshot, then run once in a maintenance window with web and workers paused. If preflight reports cloud_legacy_enterprise_credentials or cloud_legacy_enterprise_config, stop the upgrade, export the affected data, and have the migration owner decide its organization assignment. The migration does not delete this Cloud data or guess its target organization. Empty historical WeCom/WPS configuration placeholders are not blockers. That is not part of the normal self-hosted upgrade path.

​
v4.1.x → v4.2.x (Qdrant → pgvector)

Across this range, field vectors move from a standalone Qdrant store to pgvector in the main database. Upgrading from v4.1.x to v4.2.x requires:
1

Switch to the pgvector image

The official postgres image lacks the pgvector extension, so you must switch (the extension is installed automatically by the migrations):
docker-compose.yaml
2

Remove Qdrant

Against the latest compose in Docker deployment, remove the asktable_vdb service, the VDB_ADDRESS/VDB_API_KEY env vars, and the qdrant_storage/qdrant_snapshots volumes.
3

Bring it up

Migrations run and the pgvector extension is installed. If the asktable_workbook database is missing, create it per Docker deployment.
4

Rebuild embeddings

Existing data sources have empty vectors — open each data source page and click Rebuild Embedding to backfill.

​
Collation-version warning

This only happens when you change the PostgreSQL image and the underlying glibc version changes — the signal is a collation version mismatch line in the startup log.
  • Installed the pgvector extension on your existing PostgreSQL yourself, without changing the image → not triggered, skip this section.
  • Switched an old image (e.g. the postgres image from an earlier deployment) to the pgvector image while reusing the old postgres_data volume → triggered, handle it below.
Don’t just refresh the version number. A different glibc version changes text sort order, so old text indexes no longer match the data and queries silently miss rows. You must reindex first, then refresh the version.
If Workbook is enabled, do the same two steps for the asktable_workbook database. When the data is disposable, just recreate the volume: docker compose down -v then up again (never in production — it erases all data).