Upgrading to Appwrite 2.0: Postgres, Vectors, and Gotchas

Appwrite 2.0 landed on September 4 and the headline everyone repeated was "PostgreSQL is now the default." That is true, and it is also the least likely thing to affect you.

If you are already running Appwrite, the default does not touch you. Your install stays on the engine it is on. What will actually catch you out is the other half of the release: 2.0 ships two new database products and an embeddings API, and all three are switched off out of the box, two of them because a stock install does not even deploy the engine they need.

So here is what actually changed, in the order it will matter to you.

The Postgres default is for new installs only

New installs provision PostgreSQL out of the box with durability left on. MariaDB and MongoDB remain fully supported for both new and existing installs, and the upgrade notes are blunt about it: MariaDB and MongoDB installs stay on their current database.

There is no migration path being forced on you here, and no deprecation notice. If you are on MariaDB and happy, do nothing. The interesting part is that new projects can now hold relational, schemaless and vector data across PostgreSQL, MariaDB or MongoDB behind the same permissions, queries and realtime API you already use.

Check what you are actually running before you plan anything:

docker compose ps --format '{{.Image}}' | grep appwrite

The two new database products ship off

This is the part I would not have guessed from the announcement.

VectorsDB stores embeddings. You create a collection with a fixed dimension, every document holds a vector of that length plus optional metadata, and an HNSW index keeps similarity search fast as the collection grows. You pick cosine, dot product or Euclidean distance.

DocumentsDB stores schemaless JSON. Two documents in the same collection can have completely different fields, and adding a field is a write rather than a migration. Document-level permissions, queries, ordering and pagination all work through the same SDK patterns you already know.

Both need PostgreSQL and MongoDB engines that a stock install does not deploy. So they ship disabled, and turning them on is a two-step job: provision the engine, then set the flag. Be aware that the release notes state the requirement without walking you through the provisioning, so budget time for the self-hosting environment variable docs rather than expecting a one-line toggle.

The Embeddings API turns text into vectors without a separate embedding service in your stack, which is genuinely useful if you were about to bolt one on. Appwrite is upfront that the embedding container is resource heavy, which is why it sits behind a compose profile rather than just an environment variable. Size your VM accordingly before you enable it.

If you turn on VectorsDB and the Embeddings API together, you have a working RAG backend without adding a vector database or an embedding service to your architecture. That is the real story of this release, and it is buried three bullets down in the notes.

The upgrade from 1.9.x

It is genuinely a single command plus a migration. Back up your data first, and I mean that in the way everyone says it and fewer people do.

docker run -it --rm \
    --volume /var/run/docker.sock:/var/run/docker.sock \
    --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \
    --entrypoint="upgrade" \
    appwrite/appwrite:2.0.0

Then run the migration:

cd appwrite
docker compose exec appwrite migrate

Two upgrade details worth knowing. Build artifacts now survive the jump: the builds volume rename no longer strands existing function and site deployments, which was a real problem for people moving off older versions. And infrastructure migrations are versioned now, so volume and file changes run per release during an upgrade instead of being a single all-or-nothing step.

One removal to check for: GET /v1/health/executions is gone. If anything in your monitoring hits it, fix that before you upgrade rather than after.

The console rebuild

Console IV is a ground-up rebuild with a new navigation model, redesigned resource views, notifications and a realtime event tail. Two additions are more than cosmetic. Appwrite Terminal runs the CLI inside the console with your session and project already configured, so no local install and no auth dance. Appwrite Explorer loads your project's OpenAPI specification, builds requests through guided forms, and sends live calls from the browser.

Elsewhere: Gitea joins the VCS provider list, self-hosted GitLab works through _APP_VCS_GITLAB_ENDPOINT, and Git installations are now isolated per project with signed GitHub App installation state, so a callback cannot be replayed onto someone else's project. Realtime got cheaper per event too, encoding each document once per event instead of once per subscriber.

One addition aimed squarely at self-hosters: 2.0 adds a Usage service for self-hosted instances, with resource-scoped metrics for every product. If you have been guessing at which project is driving your load, that guesswork is over.

Troubleshooting

You set _APP_VECTORSDB and nothing works. The flag is the second step. The engine has to be provisioned first, because a stock install does not deploy it.

The embedding container is eating your VM. Expected. It is resource heavy by design, which is why it is behind a compose profile. Move it to a larger instance or leave it off and keep using an external embedding service.

Your console is on plain HTTP after upgrading. That is intentional. HTTPS now follows the hostname: off for loopback, .local, .internal and bare IPs, on for a real domain. Point a real domain at it.

Function deployments vanished after upgrading. They should not, on 2.0. If you jumped from an older version through an intermediate release, check the builds volume before assuming they are gone.

Monitoring alerts on a 404 after upgrade. Probably GET /v1/health/executions, which was removed.

Is it worth upgrading?

If you are on 1.9.x and using Appwrite as a straightforward backend, there is no urgency. The upgrade is low risk and the console is better, but nothing is being taken away from you.

If you are building anything with embeddings, upgrade. Being able to run vector storage and embedding generation inside the backend you already operate, instead of standing up two more services, is a real reduction in moving parts.

A managed Appwrite instance on Elestio starts at $16/month with backups, SSL and updates handled. Do check which version your instance is on before planning around 2.0 features, using the image command above.

Thanks for reading ❤️ See you in the next one 👋