Improve v0.16 migration instructions
This commit is contained in:
@@ -523,30 +523,32 @@ Most failures come from trying to create an object whose parent does not exist y
|
||||
|
||||
`apply` runs operations in plan order and stops on the first error. When a `create` fails halfway through, every prior `create` in the same run has already been committed to the database. Re-running the same plan now fails with `primaryKeyViolation` (the objects exist) or `invalidForeignKey` (a parent that did not get created the first time is still missing).
|
||||
|
||||
The cleanest recovery is to wipe the registry and apply again. While the server is still in recovery mode, list and delete the migrated objects:
|
||||
> **Do not bulk-delete `Account` objects to recover.** The migration plan creates each account with its original v0.15 account id (the `restore-<id>` mechanism), so a migrated `Account` points at the existing v0.15 mailbox data in the data store. Deleting that `Account` schedules account destruction, which unlinks and erases all mail, calendars, and contacts stored under that id. On the community edition this runs immediately, with no retention window. Never run `delete Account` against a data store that already contains v0.15 mail.
|
||||
|
||||
Recovery does not require deleting accounts. An account that a partial `apply` already created is correct and is reused as-is on the next run; the only objects that need clearing are the registry-only ones that carry no mailbox data and whose re-creation would otherwise raise `primaryKeyViolation`. While the server is still in recovery mode:
|
||||
|
||||
```bash
|
||||
$ stalwart-cli query Domain --json | jq -r '.[].id' \
|
||||
| stalwart-cli delete Domain --stdin
|
||||
$ stalwart-cli query Account --json | jq -r '.[].id' \
|
||||
| stalwart-cli delete Account --stdin
|
||||
$ stalwart-cli query Tenant --json | jq -r '.[].id' \
|
||||
| stalwart-cli delete Tenant --stdin
|
||||
$ stalwart-cli query DkimSignature --json | jq -r '.[].id' \
|
||||
| stalwart-cli delete DkimSignature --stdin
|
||||
$ stalwart-cli query Certificate --json | jq -r '.[].id' \
|
||||
| stalwart-cli delete Certificate --stdin
|
||||
$ stalwart-cli query Domain --json | jq -r '.[].id' \
|
||||
| stalwart-cli delete Domain --stdin
|
||||
$ stalwart-cli query Tenant --json | jq -r '.[].id' \
|
||||
| stalwart-cli delete Tenant --stdin
|
||||
```
|
||||
|
||||
Then fix the underlying cause in `export.json` (most often a domain that fails the v0.16 hostname check, an account whose local-part contains `@`, or a stale `/opt/stalwart` path embedded by the migration script) and rerun:
|
||||
`Domain` and `Tenant` hold only directory metadata and are safe to delete and recreate; `Account` is deliberately omitted. Then fix the underlying cause in `export.json` (most often a domain that fails the v0.16 hostname check, an account whose local-part contains `@`, or a stale `/opt/stalwart` path embedded by the migration script), remove from `export.json` the `create` operation for `Account` (and any other object that already committed before the failure, so re-applying it does not raise `primaryKeyViolation`), and rerun:
|
||||
|
||||
```bash
|
||||
$ stalwart-cli apply --file export.json
|
||||
```
|
||||
|
||||
If the failure was caused by data that the migration script itself produced incorrectly, also rerun the script with the latest version from `main` before applying. Fixes during the v0.16.0 / v0.16.1 window addressed several edge cases (group names containing `@`, ACME base64 padding, single-URL Redis stores, paths embedded in custom storage backends).
|
||||
If you must start over with the accounts as well, do not delete them: point the new deployment at an empty data store (or restore the v0.15 data-store backup) before re-running `apply`, so that destroying and recreating accounts cannot reach live mail.
|
||||
|
||||
For deployments where individual objects are easier to identify than to wipe wholesale, use `stalwart-cli query <type>` to list ids and `stalwart-cli delete <type> --ids <id>` to remove a specific one.
|
||||
If the failure was caused by data that the migration script itself produced incorrectly, also rerun the script with the latest version from `main` before applying. Fixes during the v0.16.0 / v0.16.1 window addressed several edge cases (group names containing `@`, ACME base64 padding, single-URL Redis stores, paths embedded in custom storage backends, and `%{file:...}%` / `%{env:...}%` macros in DKIM private keys and certificates, which are now expanded by the script instead of being passed through verbatim and aborting the `apply`).
|
||||
|
||||
For deployments where individual objects are easier to identify than to wipe wholesale, use `stalwart-cli query <type>` to list ids and `stalwart-cli delete <type> --ids <id>` to remove a specific one. The same warning applies: deleting an `Account` destroys the mail stored under it. Only `Domain`, `Tenant`, `DkimSignature`, and `Certificate` are safe to delete and recreate during recovery.
|
||||
|
||||
### Bootstrapping a real administrator from the CLI
|
||||
|
||||
|
||||
Reference in New Issue
Block a user