AFFiNE Self Hosted 0.21 upgrade guide

Starting from version 0.21, AFFiNE added support for local vector indexing, so the backend database container was replaced from the official PostgreSQL container to the pgvector container.

This document aims to guide users in upgrading the AFFiNE Self Hosted server previously deployed based on the official tutorial .

If you deploy using other methods, only part of this article applies. You can refer to the content of this document to make corresponding adjustments to your configuration, or visit our Discord  / Telegram  community for help.

1. Overview

In this version update, the default database container for the AFFiNE Self Hosted backend has been changed from postgres:16 to pgvector:pg16 to support the storage and querying of vector data types.

If you redeploy the server, simply follow the steps in the Self-Hosted deployment documentation.

If you are upgrading from an existing server, you need to follow the steps in this tutorial.

2. Important Notice

• Important Information for Major Version Upgrades

  • If the current version of PostgreSQL you are using does not match the major version of the target pgvector container (for example, upgrading from 15 to 16 or 17), be sure to perform a manual intervention upgrade.

  • For replacement within the same major version (e.g., 15 to 15), you can directly replace the container image without additional operations.

• How to check the current PostgreSQL major version

  • Execute the following command to confirm the current version information of the database:

  • Based on the output information, confirm the major version of the database (15, 16, or 17), and select the corresponding version of the pgvector container.

  • If you have modified the container name of postgres, please change “postgres” in the command line to the corresponding container name.

$ docker exec -it postgres pg_config --version
PostgreSQL 16.6 (Debian 16.6-1.pgdg120+1)

3. Preparation before the upgrade

3.1 Backup data

• Perform a full backup of the PostgreSQL database to ensure data can be recovered in case of issues during the upgrade.

• Backup your docker-compose.yml file and custom environment variable configuration file (.env).

3.2 Stop existing services

• Stop running services using the Docker Compose command:

docker compose -f compose.yml down

• Confirm that all relevant containers have stopped running to avoid data write conflicts.

4. Upgrade method

This upgrade supports two deployment methods: using the Docker Compose script we provide and self-deployment.

Please choose the appropriate solution based on your actual situation.

4.1 Upgrade via Docker Compose

4.1.1 Modify the compose file

• Download the latest compose.yml file:

wget -O compose.yml https://github.com/toeverything/affine/releases/latest/download/docker-compose.yml

• Edit the .env file, add the DB_VERSION variable, and set its value to the major version number of the PostgreSQL server used by the AFFiNE service, for example:

DB_VERSION=16

4.1.2 Pay attention to major version upgrades

• Replace with the same major version: If the current PostgreSQL major version is consistent with the target version (for example, both are 15), you can directly replace the container image and start the service.

• Major version upgrade: If you need to upgrade from 15 to 16 or 17, you must use pg_upgrade for data migration:

  1. According to the official PostgreSQL documentation , use the pg_upgrade tool to prepare the old and new data directories.

  2. Run pg_upgrade to complete the migration of system tables and user data.

  3. Check the upgrade log to confirm that all steps have been successfully completed.

4.1.3 Pull the new image and start the service

# pull the latest image
docker compose -f compose.yml pull
# start service
docker compose -f compose.yml up -d

4.2 Self-deployment upgrade

For users deploying their own PostgreSQL instances, please follow these steps:

4.2.1 Replace container image

• Replace the official PostgreSQL container in the current deployment with the target version of the pgvector container, ensuring that the image version matches the current major database version.

• Modify the container startup script or configuration file to update the image name to pgvector:pg15, pgvector:pg16, or pgvector:pg17, depending on your current database major version.

4.2.2 Major version upgrade

• If you need to upgrade across major versions (for example, from 15 to 16/17), please:

• Refer to the PostgreSQL pg_upgrade  documentation and follow the steps to perform data migration using the pg_upgrade tool.

• After the upgrade is complete, update the container image to the target pgvector container version.

4.2.3 Restart service and verify

• After replacing the image and completing the necessary data migration, restart the PostgreSQL service to ensure the new container starts normally and maintains a connection with the business services.

5. FAQ

5.1 What to do if a major version upgrade fails?

• Please ensure that all data is backed up before the upgrade and strictly follow the usage documentation of the pg_upgrade tool. It is recommended to first verify the upgrade process in a test environment.

5.2 How to confirm the current major version of PostgreSQL in use?

• Enter the PostgreSQL container and execute the command pg_config --version to obtain version information.

• Use a database connection tool to connect to the PostgreSQL database and obtain detailed version information using the command SELECT version();

5.3 What is the difference between the pgvector container and the official PostgreSQL container?

• The pgvector extension adds support for vector data types while retaining the official features of PostgreSQL.