Skip to main content
🛠 This page is for engineering teams self-hosting their own Lightdash instance. If you’re on Lightdash Cloud, upgrades are handled for you automatically.
Lightdash uses semantic versioning in the form major.minor.patch. Each segment signals how significant the changes are and how much care to take when upgrading.

​
How Lightdash versioning works

  • Patch versions (x.x.PATCH) are small fixes. Safe to pick up as part of routine upgrades.
  • Minor versions (x.MINOR.x) introduce new features or larger changes that can be backwards incompatible. Review the release notes before upgrading.
  • Major versions (MAJOR.x.x) introduce breaking changes to the API or the self-hosted architecture. Expect to make configuration, infrastructure, or integration changes, and read the release notes before upgrading.
Lightdash ships continuously and does not publish an LTS or “stable” tag. Pin image.tag to a specific version in production and upgrade deliberately — pinning makes deployments repeatable and avoids unexpected changes. Using latest is fine for a local laptop instance.

​
Upgrade cadence

Upgrade at least monthly. Falling many minor versions behind makes the eventual migration jump riskier. Treat every upgrade as a controlled rollout: upgrade UAT / pre-production first, run your validation (SSO, warehouse connections, dbt refreshes, scheduled jobs, embeds, critical dashboards), then roll out to production. Your UAT environment should mirror production closely enough that upgrade testing is meaningful:
  • The same configuration and environment variables as production — feature flags, SSO, SMTP, object storage, license key, scheduler and headless browser config. Differences here are the most common reason an upgrade passes pre-production but fails in production.
  • A replica of the production Lightdash database (including pgvector), not an empty or hand-seeded one. Real data volume, migrations, and project/role/embed state are what surface upgrade regressions. Refresh the replica from production before each round of testing.

​
Upgrade mechanics

​
Local Docker deployments

If you’re running Lightdash on your own laptop with Docker, pull the latest image and restart:

​
Kubernetes / Helm deployments

If you install Lightdash into Kubernetes with the community Helm charts, update the chart repository and upgrade your deployment:
The upgrade path is: bump image.tag → helm upgrade → the migration job runs database migrations → the backend rolls out.

​
Database migrations

Migrations run automatically when the Lightdash server or workers start, so a routine upgrade applies them for you. Once you run multiple backend replicas, enable the migration job so replicas don’t race on the migration lock. It runs migrations as a Helm pre-install,pre-upgrade hook exactly once, and the backend then starts without migrating:
If a deploy is interrupted mid-migration, the lock lives in the knex_migrations_lock table in the Lightdash Postgres database — release it there before retrying.

​
Rollback

Roll back the image.tag only if the release notes say the migrations are backwards-compatible. If they are not, a lower image running against an already-migrated database can fail — restore the database from backup instead. Rebuilding an instance from scratch needs three things, so keep all three recoverable:
  • the Postgres backup,
  • the LIGHTDASH_SECRET (it decrypts data at rest — losing it means losing access to encrypted data), and
  • your Helm values.