Skip to content
The Things Stack documentation home
Getting Started Concepts Cloud Enterprise Integrations API Hardware
Getting Started Concepts
Cloud Enterprise
Integrations API Hardware
Get The Things Stack

    Recent searches

      Popular pages

      • Getting Started
      • Adding Gateways
      • Adding Devices
      • Payload Formatters
      • Webhooks
      • Authentication

      No results for “”.

      • Check the spelling, or try fewer or more general words.
      • Ask the community on The Things Network Forum
      • Contact support
      ↑↓ to navigate ↵ to open Esc to close

      The Things Stack Enterprise

      • Overview
      • AWS
      • Kubernetes
        • Generic
          • Prerequisites
          • Preparation
          • Configuration
          • Install Charts
          • Monitoring
          • Troubleshooting
          • Database Migrations
        • Azure
      • Docker
      • The Things Join Server
      • Manage The Things Stack

      Database Migrations

      Updated 23 June 2026 Edit on GitHub
      Copy page
      • View as MarkdownThis page as plain text
      • Open in ChatGPTAsk questions about this page
      • Open in ClaudeAsk questions about this page

      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

      On this page

      • General Procedure
      • Manual Procedure

      Sections

      Getting Started

      Concepts

      Cloud

      Enterprise

      Integrations

      API

      Hardware

      Sitemap

      View our Sitemap

      Contributing

      GitHub

      About Us

      The Things Industries

      Privacy Policy

      Cookie settings

      Cookie Settings

      We use cookies to enhance your experience, analyze site traffic and deliver personalized content. Read our Privacy Policy.

      Cookie categories