Documentation
Atomic Database Imports
Servd's database import, clone and backup restore features are now able to perform zero-downtime, atomic imports. Either they successfully complete or they revert back to their original state.
Toggling Atomic Database Imports #
Perform the following steps to turn atomic database imports on or off:
-
Navigate to any of your environment import pages (e.g. staging or production)
-
Scroll down to the "Atomic Database Imports" section.
-
Flip the slider switch to turn atomic database imports on or off. This will enable or disable atomic imports for all your project environments.
The Process #
Previously, importing, cloning or restoring a project's database would first delete all the original database's tables, and then import the new data. There's a couple downsides of this approach:
- If the import fails, deleting the original tables straight away will leave the database in a half-imported state and cause the project to go down. In the worst case scenario, it could result in data loss if the latest backup was taken a long time ago.
- Whilst the new data is being imported, the database won't have all the necessary tables Craft needs, so uncached requests will fail.
Steps
To avoid these issues, atomic imports perform the following steps:
- A new database is created. It's name is suffixed with the timestamp of when it was created, e.g. foo_bar_production_1677583919
- The data being imported is added to this database. Craft is not connected to it at this point and continues to communicate with the original database.
- Craft is then redeployed with updated database environment variables via a rolling, zero-downtime update. The new data is now available via the control panel and front-end requests.
- Behind the scenes, the original database is dropped to free up database space.
This sequence keeps Craft connected to a complete database at all times, and thus avoids any database-related downtime.
Automatic Rollback
If any errors occur before the original database is dropped, then automatic revert steps kick in, which will:
- Restore the original database.
- Redeploy Craft with the original database environment variables.
What Database Operations Are Atomic? #
When enabled, the following operations are made atomic:
- Uploading a database dump via an environment's Import page.
- Cloning a database from one environment to another via it's Import page.
- Restoring a database backup from an environment's Backups page.
It's worth noting that any assets changed via a clone or backup restore aren't atomic and are updated in-place. In most circumstances this won't cause requests to fail, but may cause newer images to briefly fail to load as they're copied over.
When Shouldn't I Enable Atomic Imports? #
Each time an atomic import happens, it creates a new database whose name is suffixed with the current timestamp. If your project requires a static database name (e.g. maybe an external service connects and adds data to it), then you may want to disable atomic imports.