How to upgrade to Chatwoot v4?

Chatwoot v4 requires PostgreSQL with pgvector support. You need to ensure that the version of PostgreSQL you are running supports pgvector before upgrading.

​

Type of Deployment

​

Linux

• If you are using managed PostgreSQL, refer to the Managed PostgreSQL section below.
• If you are using self-hosted PostgreSQL, read along.

​

Docker

• If you are using managed PostgreSQL, refer to the Managed PostgreSQL section below.
• If you are using self-hosted PostgreSQL, read along.

​

Kubernetes (Helm)

• If you are using managed PostgreSQL, refer to the Managed PostgreSQL section below.
• If you are using self-hosted PostgreSQL, read along.

​

Heroku

• No action is needed if you are using Heroku PostgreSQL.
• If you are using another managed PostgreSQL, refer to the Managed PostgreSQL section below.

​

PostgreSQL

The PostgreSQL section is divided into parts based on how you are running PostgreSQL:

1. Managed PostgreSQL from cloud vendors like AWS, GCP, Azure, Heroku, etc.
2. Self-hosted PostgreSQL on Linux, Docker, or Kubernetes via Helm charts.

​

Managed PostgreSQL

​

AWS RDS

No action is needed if you are on the latest version of RDS.
Learn more

​

Google Cloud (Cloud SQL)

No action is needed.
Learn more

​

Heroku PostgreSQL

The pgvector extension is supported. No action is needed.
Learn more

​

Azure PostgreSQL

To enable pgvector on your Azure Database for PostgreSQL flexible server instance:

1. Add pgvector to your allowlist as described in the PostgreSQL extensions documentation.
2. Verify if it is correctly added by running:
   Copy

   SHOW azure.extensions;
   

Learn more

​

Self-hosted PostgreSQL

​

Linux VM

​

Existing Installation

Install the pgvector extension for your version of PostgreSQL and run the upgrade:

# Find your PostgreSQL version
psql --version

# If its version 16, use the following command
# Replace "16" with your PostgreSQL version
sudo apt install postgresql-16-pgvector

​

Docker Container

​

Existing Installation

1. Replace the PostgreSQL image with the pgvector image. The pgvector image is a drop-in replacement and works with your existing data:

   Copy

   docker compose down
   
   # Edit and replace the PostgreSQL image in docker-compose.yaml
   vi docker-compose.yaml
   
   # Replace PostgreSQL image tag
   # Example: replace
   # image: postgres:12
   # with
   # image: pgvector/pgvector:pg12
   
   # Ensure the pg tag number matches your PostgreSQL version
   docker compose pull
   
   # Verify the updated setup
   docker compose up -d
   

2. After verifying that the existing installation works with the pgvector image, proceed with the regular upgrade steps. Learn more

​

Kubernetes (Helm Chart)

If you use the built-in PostgreSQL via the official Helm chart, follow the steps below. The Bitnami-packaged PostgreSQL used in the Helm chart does not support the pgvector extension. To address this, we have built a custom Postgres image with pgvector support.

1. Create a values.v4-upgrade.yaml file with the following contents:

   Copy

   image:
     repository: chatwoot/chatwoot
     tag: v4.0.1
     pullPolicy: IfNotPresent
   
   postgresql:
     image:
       registry: ghcr.io
       repository: chatwoot/pgvector
   

2. Run helm upgrade with this custom values.yaml file.