> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asktable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration

> Version migration for self-hosted deployments — routine upgrade, plus per-version steps that need extra manual work (such as the v4.1.x → v4.2.x Qdrant→pgvector migration).

## Routine upgrade

```bash theme={null}
docker compose pull && docker compose down && docker compose up -d
```

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.

## 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:

<Steps>
  <Step title="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):

    ```yaml docker-compose.yaml theme={null}
    asktable-pg:
      image: pgvector/pgvector:pg17   # was postgres:17
    ```
  </Step>

  <Step title="Remove Qdrant">
    Against the latest compose in [Docker deployment](/en/deploy/docker), remove the `asktable_vdb` service, the `VDB_ADDRESS`/`VDB_API_KEY` env vars, and the `qdrant_storage`/`qdrant_snapshots` volumes.
  </Step>

  <Step title="Bring it up">
    ```bash theme={null}
    docker compose pull && docker compose down && docker compose up -d
    ```

    Migrations run and the pgvector extension is installed. If the `asktable_workbook` database is missing, create it per [Docker deployment](/en/deploy/docker).
  </Step>

  <Step title="Rebuild embeddings">
    Existing data sources have empty vectors — open each data source page and click **Rebuild Embedding** to backfill.
  </Step>
</Steps>

### 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.

<Warning>
  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.
</Warning>

```bash theme={null}
docker compose exec asktable-pg psql -U asktable -d asktable -c "REINDEX DATABASE asktable;"
docker compose exec asktable-pg psql -U asktable -d asktable -c "ALTER DATABASE asktable REFRESH COLLATION VERSION;"
docker compose exec asktable-pg psql -U asktable -d postgres -c "ALTER DATABASE template1 REFRESH COLLATION 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**).