Komodo Migration Guide: SQLite / PostgreSQL → FerretDB v2

[MickLesk]

🛠️ Komodo Migration Guide: SQLite / PostgreSQL → FerretDB v2

As of Komodo v1.18.0, official support for SQLite and the original PostgreSQL backend (used with FerretDB v1) has been removed.

This guide walks you through migrating your Komodo instance to FerretDB v2, which uses a custom PostgreSQL backend and offers improved performance and long-term support.

Official Guide: https://github.com/moghtech/komodo/blob/main/bin/util/docs/copy-database.md#ferretdb-v2-update-guide

---

❗ Why migrate?

• Komodo 1.18.0 requires FerretDB v2
• SQLite and PostgreSQL via FerretDB v1 are no longer supported
• Upgrading without migrating will result in startup failures or data loss

---

✅ Prerequisites

• You have a running Komodo installation under /opt/komodo
• Your setup uses either:
  • sqlite.compose.yaml
  • postgres.compose.yaml
• You want to retain all existing data (projects, users, deployments, etc.)

---

🔁 Migration Steps

1. Extend your existing Compose file

Edit your existing sqlite.compose.yaml or postgres.compose.yaml and add the following new services:

services:
  postgres2:
    image: ghcr.io/ferretdb/postgres-documentdb
    labels:
      komodo.skip:
    restart: unless-stopped
    volumes:
      - postgres-data:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: ${KOMODO_DB_USERNAME}
      POSTGRES_PASSWORD: ${KOMODO_DB_PASSWORD}
      POSTGRES_DB: postgres

  ferretdb2:
    image: ghcr.io/ferretdb/ferretdb
    labels:
      komodo.skip:
    restart: unless-stopped
    depends_on:
      - postgres2
    volumes:
      - ferretdb-state:/state
    environment:
      FERRETDB_POSTGRESQL_URL: postgres://${KOMODO_DB_USERNAME}:${KOMODO_DB_PASSWORD}@postgres2:5432/postgres

---

2. Add the migration utility

Add the following service to perform a one-time database copy:

  copy_database:
    image: ghcr.io/moghtech/komodo-util
    environment:
      MODE: CopyDatabase
      SOURCE_URI: mongodb://${KOMODO_DB_USERNAME}:${KOMODO_DB_PASSWORD}@ferretdb:27017/${KOMODO_DATABASE_DB_NAME:-komodo}?authMechanism=PLAIN
      SOURCE_DB_NAME: ${KOMODO_DATABASE_DB_NAME:-komodo}
      TARGET_URI: mongodb://${KOMODO_DB_USERNAME}:${KOMODO_DB_PASSWORD}@ferretdb2:27017
      TARGET_DB_NAME: ${KOMODO_DATABASE_DB_NAME:-komodo}

---

3. Extend the volume section

At the bottom of your Compose file, ensure these volumes are defined:

volumes:
  postgres-data:
  ferretdb-state:

---

4. Start the migration

Run:

cd /opt/komodo
docker compose -p komodo --env-file compose.env -f YOUR_COMPOSE_FILE.yaml up -d

Replace YOUR_COMPOSE_FILE.yaml with your actual compose file name (e.g. sqlite.compose.yaml)

Wait for the copy_database service to finish (it will stop automatically).

---

5. Rename and switch to FerretDB v2

After the migration completes, rename your compose file:

mv /opt/komodo/sqlite.compose.yaml /opt/komodo/ferretdb.compose.yaml
# or
mv /opt/komodo/postgres.compose.yaml /opt/komodo/ferretdb.compose.yaml

Then edit the renamed file and:

• Remove or comment out the old ferretdb, postgres, and copy_database services.
• In the core service, set the new database address:

  environment:
    KOMODO_DATABASE_ADDRESS: ferretdb2:27017
    KOMODO_DATABASE_USERNAME: ${KOMODO_DB_USERNAME}
    KOMODO_DATABASE_PASSWORD: ${KOMODO_DB_PASSWORD}

Start Komodo using the renamed configuration:

docker compose -p komodo -f /opt/komodo/ferretdb.compose.yaml --env-file /opt/komodo/compose.env up -d

---

6. Verify the new setup

Access your instance in the browser:

http://<your-ip>:9120

Check that everything works correctly and your data has been migrated.

---

You may also remove unused Docker volumes or containers as needed:

docker volume ls
docker volume rm <volume-name>

---

🔗 Official Docs

• FerretDB v2 Migration Documentation

---

🛑 Important

All community-based update scripts will block automatic updates if legacy sqlite.compose.yaml or postgres.compose.yaml are detected.

Migration is required before upgrading to Komodo v1.18.0 and newer.