#To 0.21

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 Self-host AFFiNE guide.

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.

#Overview

In this version update, the default database container for the AFFiNE Self Hosted backend has been changed from postgres:16 to pgvector/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.

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

#Preparation before the upgrade

#Backup data

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

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

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

#Docker Compose

#Download the latest compose.yml file

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

#Update pgvector version

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:

services:
  # ...
  postgres:
    image: postgres:16 
    image: pgvector/pgvector:pg16 ![code ++]
  #...

#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

#Standalone Postgres

For users deploying their own PostgreSQL instances, please install pgvector extension to your postgres instance.