Skip to content

Schema migration

As applications evolve, they may at a certain moment require a schema migration that transforms old data into a new format.

In a standalone application without Lightning Stream, it is safe to simply rewrite all data on startup, and then continue working with the new data. With Lightning Stream and other active instances, things can get a bit more complicated: you do not want Lightning Stream to merge in data in a format from a previous schema version.

The recommended way to ensure that schema upgrades of PowerDNS Authoritative Server do not cause issues like those described above is to perform the following steps.

Note

The following is not relevant for PowerDNS Cloud Control deployments which use Lightning Stream Enterprise, because that includes a migrator component that handles migrations to new schemas automatically.

Initial Configuration

To ensure that your deployment is capable of handling schema upgrades, you should add a prefix to the Lightning Stream Enterprise configuration. This prefix will contain the schema version in use by the Authoritative Server. The schema version for different versions of PowerDNS Authoritative Server can be found here.

Example configuration including the schema in the prefix:

storage:
  type: s3
  options:
    global_prefix: 'v6'
    access_key: minioadmin
    secret_key: minioadmin
    region: us-east-1
    bucket: lightningstream
    endpoint_url: http://localhost:9000

Upgrading to an Authoritative Server version that Updates the Schema

Note that the following steps do not need to be followed if the Authoritative Server does not update the LMDB schema version, or if you have set the Authoritative Server lmdb-schema-version to a specific version number (which disables automatic upgrades)

When upgrading to a new version of the PowerDNS Authoritative Server that includes a new schema version, the following steps should be followed. This will enable the schema to be safely migrated to a new version, without losing data, and without causing data to be merged from a previous schema version (which would cause undefined behaviour).

Firstly, you can optionally plan for the upgrade to take place during a maintenance window, although if you follow the below procedure, a full maintenance window is not strictly necessary.

Each of the following steps should be applied to a single Authoritative Server and its associated Lightning Stream instance at a time. Once the process has been completed for one server, continue the process until all the servers that use the same S3 bucket are upgraded. If you do plan a maintenance window, you can apply the following steps to all servers at the same time during the window, rather than one at a time.

Step 1 - Stop the Lightning Stream Enterprise Instance and Modify Configuration

Stop the Lightning Stream Enterprise instance associated with your Authoritative Server, to ensure that no updates are attempted during the upgrade.

After it has stopped, modify the configuration (or for example the group_vars in your Ansible configuration) so that the global_prefix field now reflects the LMDB schema version of the Authoritative Server version you are about to upgrade to. For example change from v5 to v6.

Step 2 - Stop and Upgrade the Authoritative Server Instance

Stop the Authoritative Server instance, run the upgrade procedure, and then start the instance with the upgraded version. The Authoritative Server will automatically upgrade the schema of the local LMDB to the latest schema version.

Step 3 - Start the Lightning Stream Enterprise Instance

Start the Lightning Stream Enterprise instance, ensuring it will be using the modified configuration with the new global_prefix.

Step 4 - Ensure Correct Operation and Rollback if Necessary

Once you have completed the above steps for all instance, perform your usual steps to ensure that Lightning Stream Enterprise is functioning correctly (for example you may want to check that they all have the same SOA for each zone). If so, the upgrade was successful.

If for some reason there was an error, then you can rollback to the previous version by performing the following steps for each instance in turn:

  • Stop the Lightning Stream Enterprise and Authoritative Server instances
  • Delete the LMDB database locally on the Authoritative Server
  • Modify the Lightning Stream Enterprise configuration to use the old global_prefix
  • Downgrade the Authoritative Server to the previous version
  • Start the Lightning Stream Enterprise instance, and wait for the local LMDB to be recreated from S3
  • Start the Authoritive Server instance