Skip to main content

Chatwoot v4 migration

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

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

NOTE: This is only applicable if you are using the built-in Postgres with helm charts. Refer, to the managed docs section if you are using AWS RDS or something similar.

  1. Create a values.v4-upgrade.yaml file with the following contents
image:
  repository: chatwoot/chatwoot
  tag: v4.0.1
  pullPolicy: IfNotPresent

postgresql:
  image:
    registry: ghcr.io
    repository: chatwoot/pgvector
  1. Run helm upgrade with this custom values.yaml file.