Upgrade

A new build of kslate can carry a new database schema. The binary applies it itself when it starts. This page says how that works, what order to upgrade in, and what you can and cannot roll back.

How the schema moves

The schema is a list of numbered SQL migrations compiled into the kslate binary. When the gateway or the worker starts, it does three things:

1. It takes an advisory lock in Postgres, so replicas that start at the same time apply migrations one at a time. A replica waits up to five minutes for the lock, then exits with an error that names it.

2. It applies every migration that has not been applied yet, in number order, each in its own transaction.

3. It checks the recorded checksum of every migration that was already applied. If the file for an applied migration has changed since, the binary refuses to start, and the error says which one. A change in what a migration does is always a new migration.

   The checksum covers the whole file, so a reworded comment trips this too. Before 1.0 the answer is to recreate the database rather than to reconcile it: nothing is released, so no data is worth preserving. The release notes will say if that ever changes.

/readyz on the gateway answers 200 only when every migration this binary carries has been applied. A gateway that finds the schema missing re-runs the migrations in the background and answers 503 until they are in place. That happens when the development Postgres is replaced under it.

Every migration so far adds a column, an index or a constraint. None removes or renames anything. That is what lets old and new pods overlap during a roll.

Order

There is no required order between the gateway and the worker. Both apply the schema at start, and the lock keeps them from colliding.

With the Helm chart:

1. Build the new image and get it onto the cluster, as on the Install on Kubernetes page.

2. Apply the CRD by hand. Helm installs crds/ once and does not change it on upgrade.

   kubectl apply -f deploy/helm/kslate/crds/

3. Upgrade the release. The chart rolls the gateway Deployment and the worker. The first new pod to start applies the schema. Old gateway pods keep serving until they are replaced.

   helm upgrade kslate deploy/helm/kslate -n kslate --reuse-values --set image.tag=<new tag>

4. Check a new gateway pod answers 200 on /readyz, and that kubectl -n kslate get sharedcontexts shows every class Ready.

From source, run make build and restart kslate serve and kslate worker. The schema applies on start.

Upgrade the gateway before the clients. The Python and Go clients speak HTTP/JSON, and the error bodies are the contract between them and the gateway. See Status and compatibility.

Rollback

kslate never rolls a migration back. There is no down migration. An older binary checks only the migrations it carries, so against a newer schema it reports ready and runs. That holds as long as the migrations between the two releases only added things, which is true of every migration so far. The release notes say when a release breaks that pattern. A rollback does not undo writes made by the newer build.

The bundled development Postgres keeps its data on an emptyDir, so an upgrade that restarts that pod starts from an empty schema. Use your own Postgres for anything you want to keep.