Database Migrations

The Things Stack database schema is managed between minor versions using database migrations.

User are informed of required migrations for each version via the Release Notes. It’s mandatory to run required database migrations for The Things Stack to function properly.

This page describes the steps for performing database operations on a The Things Stack Kubernetes Cluster.

General Procedure

Warning:
Run migrations with the same PostgreSQL role that owns the existing The Things Stack tables (or with a superuser role). Migrations execute DDL statements such as CREATE, ALTER and DROP, so a role with only read/write table privileges is not sufficient.

Set the respective Helm chart values to true to perform database migrations during Helm chart upgrade.

Service Variable
IS is.database.migrate
NOC noc.store.database.migrate
AS as.storage.migrate
Note:

For example to migrate Identity Server use the following config.

is:
  database:
    migrate: true

Manual Procedure

  1. Delete current Jobs (if any).
$ kubectl delete jobs --all=true
  1. Do a dry run of a Helm update and store the evaluation to a file.
$ helm upgrade <name> oci://registry-1.docker.io/thethingsindustries/<repo> --version <version> --values <deployment>.values.yaml --dry-run --debug > dryrun.txt

You can also use a local Helm chart.

$ helm upgrade <name> <path-to-chart> --values <deployment>.values.yaml --dry-run --debug > dryrun.txt
  1. In the dryrun.txt file look for a job with the name <name>-<component>-migrate.

For example a migration job for the Identity Server database would look like this.

apiVersion: batch/v1
kind: Job
metadata:
  name: <name>-is-migrate
  ...

  1. Copy the entire yaml content of this Job; until the --- lines to a new file <name>-<component>-migrate.yaml.

  2. Deploy this Job manually.

kubectl apply -f <name>-<component>-migrate.yaml

  1. Wait for the Job to complete.

  2. Once successfully completed, this can be deleted.

kubectl delete -f <name>-<component>-migrate.yaml

Repeat the above process for all the components required. Currently the IS, NOC (when the NOC is enabled) and AS (when the storage integration is enabled) components require migrations.

← Troubleshooting