Migrate from SurrealDB 2 to 3
NullWard 0.6.88 and later run on SurrealDB 3 as well as SurrealDB 2. A SurrealDB 2 database keeps working, so there's no deadline to migrate. This page moves an existing NullWard database from SurrealDB 2 to 3 for the Docker Compose setup in Deploy with Docker Compose. SurrealDB 3 can't open a SurrealDB 2 data directory. You export the database from SurrealDB 2 in SurrealDB 3's format, start SurrealDB 3 on a new volume and import the export. The old volume isn't touched, so you can go back to it. Before you start NullWard 0.6.88 or later, already running on your SurrealDB 2 database. Start it at least once on SurrealDB 2: that start converts the database's tables to the layout SurrealDB 3 needs. Earlier NullWard versions don't run on SurrealDB 3. SurrealDB 2.6.0 or later. The SurrealDB 3 export format was added in 2.6.0. Check the version: If it's older than 2.6.0, update SurrealDB 2 first. Downtime: NullWard is stopped from step 2 until step 8, usually a few minutes. While it's stopped, nothing is proxied. A cluster: each node has its own SurrealDB. Migrate one node at a time, with these steps on each node, and check the node before you move on to the next. 1. Load the database credentials The commands below read the database user and password from your .env file: If your .env doesn't set NULLWARD_DB_USERNAME or NULLWARD_DB_PASSWORD, the defaults are root / root: run export NULLWARD_DB_USERNAME=root NULLWARD_DB_PASSWORD=root. If a value in .env contains spaces or $, set the two variables by hand the same way. 2. Stop NullWard SurrealDB keeps running. 3. Export the database Make a normal SurrealDB 2 backup first, then the export for SurrealDB 3: Each one ends with The SurrealQL file was exported successfully. If you changed NULLWARD_DB_NAMESPACE or NULLWARD_DB_DATABASE from nullward / waf, use your values for --ns and --db, here and in step 6. Copy both files out of the container: Keep nullward-v2-backup.surql with your other backups. Both files hold your configuration, so protect them like the database. 4. Stop SurrealDB 2 5. Switch the Compose file to SurrealDB 3 Keep a copy of the current file for a rollback: In docker-compose.yml, change three lines in the surrealdb service and the volumes list: the image, and a new volume, so the SurrealDB 2 data stays as it is. Leave the rest of the service as it is, including command: start ... rocksdb:/data/nullward.db. 6. Start SurrealDB 3 and import The import ends with Import executed with no errors. SurrealDB 3 starts with your database user from .env; the import creates the namespace and database. The copy in /tmp goes away the next time the container is recreated. If the import fails, don't start NullWard: roll back and try again. 7. Start NullWard The last command should print nothing. 8. Check Sign in with your usual admin account and check: Services > Services: your services and their settings are there. Security Events > WAF Events: past events are listed. Settings > License: your license is still active. A request to one of your sites is answered as before. Roll back The SurrealDB 2 volume isn't changed by the migration, so you can return to it at any time. Changes made while running on SurrealDB 3 (new services, edited settings, new events) aren't in it. Clean up Once you're happy with SurrealDB 3, you can free the old volume's disk space: Delete the surrealdb_data: line from the volumes list in docker-compose.yml. Run docker compose up -d. Find the old volume with docker volume ls: it's <project>_surrealdb_data, for example nullward_surrealdb_data for a stack in /opt/nullward. Remove it with docker volume rm nullward_surrealdb_data. After that, a rollback needs nullward-v2-backup.surql and a fresh SurrealDB 2 volume, so keep that file. Back up surrealdb3_data from now on instead of surrealdb_data (see Back up).
NullWard documentation