Moving the Superset metadata database to PostgreSQL

Not always, but a dump and restore almost always does. A dump and restore stops writes to Superset while the data is exported and loaded, so the window grows with the size of the metadata database, the number of objects and the speed of the network and disks between the old and new hosts. A replication approach keeps the source writable while the copy catches up, then needs only a short switch-over. PostgreSQL's upgrading documentation says logical replication works between different major versions and can allow a major upgrade with only several seconds of downtime. That applies to moving PostgreSQL data between PostgreSQL servers. Moving from SQLite or from a Compose container also changes the source, so confirm with your database team which path the source supports before you plan the window. Stop Celery workers and beat during any cutover so no background task writes to the old store.

It lets the new server subscribe to changes from the old one, so the bulk copy runs while Superset keeps working and only the final changes must be applied during the cutover. The PostgreSQL upgrading documentation describes logical replication as working between different major versions, which is the basis for its very short downtime claim. The source-to-SQLite case does not fit this model, because SQLite has no replication stream. Ask your DBA to confirm the details for your PostgreSQL versions, including which objects need to be added to publications, how sequences are handled and whether the source is version 10 or later. Superset supports PostgreSQL 10 to 17 for the metadata database, so check that the target version is inside the supported range in the configuration documentation before you choose it.

Compare counts and object lists per table on both sides before users return. Check the main Superset tables for users, roles, databases, datasets, tables, columns, slices (charts), dashboards, saved queries, alerts and reports, and the Alembic migration version in the alembic_version table. Matching counts alone are not enough, so also compare primary key ranges and a checksum or hash of selected text columns, and confirm that sequences were advanced past the largest copied id so new rows do not collide. Record the results in a signed cutover checklist. Expect some tables to change between the snapshot and the switch, such as logs or query history, and agree beforehand which tables are expected to differ.

Superset encrypts stored database connection passwords with the SECRET_KEY, so the new instance must use the same key as the old one, or it must be started with PREVIOUS_SECRET_KEY set to the old value. Supported key rotation through PREVIOUS_SECRET_KEY is documented in the configuration guide, and the key is required at startup since version 2.1.0. Test decryption by opening several database connections in the UI and running a test connection on each, then run a query through SQL Lab. Confirm that the key value is stored in your secrets manager and not in a file in the repository. A mismatch usually shows up as connection errors that look like credential failures, so check the key before you reset any passwords.

Sign in with a set of test accounts that cover each role and each authentication path your users rely on, such as local database users, OAuth2 or LDAP. Confirm that group-to-role mapping through AUTH_ROLES_MAPPING still assigns the expected roles, and that row-level security rules still apply to the test users. Check password hashes indirectly by logging in with existing local accounts, and check that sessions and API tokens behave as expected. Reset no passwords as part of the test unless the SECRET_KEY check above has already passed, because a reset hides the failure you are looking for.

Open a representative set of dashboards chosen by business owners, including the most used, the most complex and any embedded or public dashboards, then compare the charts and filters to a baseline captured before the cutover. Run a set of saved SQL Lab queries and check that they return the same row counts and results against the warehouse. Check that cached results are rebuilt correctly and that alerts and reports still send. Keep the old metadata database available for a rollback period agreed in advance, since changes made in the new instance will not be copied back automatically.

Watch the Superset web and worker logs for database connection errors, decryption or invalid token messages, migration warnings, and repeated failed logins. On the PostgreSQL side, check the server log for authentication failures, connection limit errors, slow queries and replication lag if you used a replication approach. Confirm that the sequences and indexes are in place and that the server is not running out of connection slots once workers reconnect. Keep the logs for the rollback window so you can trace a problem to the time of the switch.

Your team can do the verification if it has someone who knows the Superset tables, the PostgreSQL server and the secrets process. A partner adds value when the scope includes a fixed plan, a rehearsed cutover and written acceptance criteria. DeployOpen plans, implements, backs up and documents self-hosted open-source platforms in the client's own infrastructure, and most engagements are fixed-scope with scope and timelines agreed in writing before work starts. Cost depends on the number of environments, the size of the metadata database, the migration path, the number of dashboards to check and the amount of rehearsal required. Ask for a quote that lists each verification step, who runs it and what evidence is handed over.

The main cost drivers are the size and age of the existing metadata, how many environments need the move, how much downtime the business will accept, and how much verification the team wants before cutover. A small internal instance on SQLite with few dashboards is a different job from a multi-environment deployment with Celery workers, scheduled reports and a database that has been upgraded several times. Part of the cost is one-time (planning, the cutover itself, verification) and part recurs (backups and the managed database service you run afterward). Ask any partner for a written scope that separates these, names who performs each task, and lists what the client team must provide, such as database credentials, network access and a staging copy to test against.

No duration is fixed in advance because it depends on the size of the metadata, the number of Superset environments, the network path to the new database and the downtime window agreed with stakeholders. Two approaches have very different timing. An export and import of Superset assets is usually planned around a maintenance window, while a database-level copy or logical replication can keep downtime short but adds setup and validation work before cutover. Ask for a timeline that breaks the work into staging rehearsal, cutover and post-move verification, and confirm which steps stop users from logging in.

Expect to provide a named owner for the Superset instance, access to the current deployment and its configuration files, a staging environment that mirrors production, and a managed PostgreSQL instance inside your network controls. The team also needs the business owner to approve a downtime window and someone who can confirm dashboards and users work after cutover. Plan for access to the secret store where SECRET_KEY is kept, because the new deployment must start with the same value or existing encrypted data becomes unreadable.

Yes, if your team already runs Superset and PostgreSQL in production, has tested backup and restore procedures, and can rehearse the move in staging. The work is mostly careful sequencing: back up, stop writes, move the data, run the Superset database upgrade commands, and verify. Teams without recent PostgreSQL operations experience often choose a partner for the database side, while keeping Superset configuration and dashboard checks in-house. Whichever route you choose, the written scope should say who owns each step and how rollback works if verification fails.

Use the same SECRET_KEY on the new deployment that the old instance used. Superset requires a user-specified SECRET_KEY to start, a requirement added in version 2.1.0, and the value protects data stored in the metadata database, including database connection credentials. If you need to change the key, the configuration documentation describes rotation with PREVIOUS_SECRET_KEY, which should be planned and tested in staging before cutover. Confirm where the key is stored, who can read it, and that it is backed up separately from the database dump.

The Superset configuration documentation lists supported metadata database versions as PostgreSQL 10 to 17 and MySQL 5.7 and 8.x. PostgreSQL 18 is not in that list, so confirm current support with the Superset release you will run before choosing it. Also check the PostgreSQL versioning policy, since PostgreSQL 14 is listed as supported only until November 12, 2026. Choose a version that is inside both the Superset support list and the PostgreSQL support window for the life of the deployment.

No. The Superset architecture documentation says the SQLite default and the Docker Compose PostgreSQL container are not recommended for production. Moving to a managed PostgreSQL instance with tested backups, access control and a planned upgrade path is the reason this migration exists. Plan the move so the database has its own backup schedule, restore test and monitoring, and so the Superset application connects to it through a stable hostname that survives later changes.