Skip to content
Back

Help understanding what "upgrade" and "migrate" do

  • 0
  • Self Hosted
  • Databases
ÙwÚ
13 Sep, 2025, 06:50

Hello, I'm currently running appwrite with k8s (well, a dirty "hack" of converting each container to a deployment). And I have some trouble understand what "upgrade" do in this doc: https://appwrite.io/docs/advanced/self-hosting/production/updates

This will pull the docker-compose.yml for the selected version/tag and perform the upgrade steps. Once the setup completes, verify that you have the latest version of Appwrite.

Well, since k8s (or in my case I'm running a k3s instance) is running with containerd, I think this "upgrade" will fail.

TypeScript
apiVersion: apps/v1
kind: Deployment
metadata:
  name: appwrite
  namespace: appwrite
  annotations:
    keel.sh/policy: "glob:v*-1.8.x"
    keel.sh/trigger: poll
    keel.sh/pollSchedule: '@weekly'
spec:
  replicas: 1
  selector:
    matchLabels:
      app: appwrite
  template:
    metadata:
      labels:
        app: appwrite
      annotations:
        backup.velero.io/backup-volumes: appwrite-config,appwrite-uploads,appwrite-functions,appwrite-sites,appwrite-builds
    spec:
      imagePullSecrets:
      - name: pull-creds
      containers:
      - name: appwrite
        image: my.private.registry/username/appwrite:v1.1.0-1.8.x

Here is what my deployment file looks like. I'm manually build appwrite form 1.8.x branch, and have CI/CD pipeline to upgrade image (newly built with latest commit from 1.8.x branch). Things works fine so far WITHOUT upgrade or migrate commands. But I'm worry about potential issue in the future if just leave it like this.

so

  1. what does "upgrade" command do? is it the same as pull new code from appwrite/appwrite->build-> deploy to docker container?
  2. I perhaps can run "migrate" before appwrite run, or does it need to be run as the same time as appwrite (new version) running?
TL;DR
1. Upgrade = updating the Appwrite instance to a newer version, while Migrate = updating the internal data structure in databases for new features. 2. Upgrade pulls the latest docker-compose.yml file for the selected version and performs necessary steps for the upgrade. Migrate is for updating the database structure for new features. You can run Migrate separately before Appwrite starts, but it's recommended to do it when Appwrite is running the new version.
Darshan Pandya
13 Sep, 2025, 07:10

upgrade -> upgrade appwrite instances from an older version to new. example: 1.6.x > 1.7.x, etc.

migrate -> migrating the internal data structure for databases for addition of new features on existing services or addition of new services altogether. This is required so that when you upgrade, your data structure inside the underlying database is up to date with backend sources.

Reply

Reply to this thread by joining our Discord

Reply on Discord

Need support?

Join our Discord

Get community support by joining our Discord server.

Join Discord

Get premium support

Join Appwrite Pro and get email support from our team.

Learn more