Skip to content

A local-first personal finance app

instructions on manual db updates (#226)

Michael Gillett2277b12be8a7
diff --git a/docs/backup-restore/restore.md b/docs/backup-restore/restore.md
index c30b656523..bcf7163b49 100644
--- a/docs/backup-restore/restore.md
+++ b/docs/backup-restore/restore.md
@@ -1,6 +1,6 @@
# Restoring Backups
-## Restoring a manual backup
+## Restoring a Manual Backup
If you previously followed the [steps](./backup.md) to back up your data and have an Actual
zip export, you can now import that using the web version of Actual.
@@ -30,6 +30,29 @@ To do this,
That is it. A fresh budget will show in your budget list. If the imported data is a copy of your current budget, you may want to rename the new budget by clicking on it's name so you can tell them apart. Once you verify the new imported budget is correct, you can navigate back to the budget selection screen by closing the current budget and deleting the old copy.
+## Errors When Restoring Database From Backup
+It is possible that you may encounter an error during restoration that says:
+
+`This budget cannot be loaded with this version of the app. Make sure the app is up-to-date.`
+
+This should only happen when you're upgrading from a Docker image with the `edge` tag to a stable release, such as `latest`. This should not happen in other instances. If you find yourself seeing this bug, please submit a bug report.
+
+**IMPORTANT NOTE**: You *MUST* download a backup of each of your budgets using the process outlined above **before** continuing. It's always good practice to backup your data before upgrading to a new verison.
+
+The fix for this is to manually migrate the your sqlite database in the steps outlined below:
+
+1. Download and install [SQLite Browser](https://sqlitebrowser.org/)
+1. Unzip the backup budget `.zip` file. The filename should look like: `yyyy-mm-dd-My-Finances-abcd1234.zip`
+1. Open SQLite Browser. Click on the "Open Database" button and navigate to the file you just unzipped. You're looking for a file named `db.sqlite`.
+1. Load the file and click on the `Browse Data` tab. Select the `__migrations__` table from the table dropdown menu.
+1. You should see a list of integers under the column labeled `id`. Cross-reference the entries in this table with the list of [database migrations](https://github.com/actualbudget/actual/tree/master/packages/loot-core/migrations) in the main Actual repository.
+1. For every integer that's missing, you'll want to click on the `.sql` file associated with it and copy the raw data.
+1. Run the sql query in the Execute tab of SQLite Browser. Be sure to check the output that the command was successful.
+1. If the sql query that you copied is successful, you'll want to insert the migration command's id into the `__migrations__` table by executing `insert into __migrations__ values(id_of_missing_migration_command);`.
+1. Once your `__migrations__` table matches the database migrations folder, commit and close the database.
+1. Rezip your modified `db.sqlite` and `metadata.json` files into a zip file.
+1. Retry the restore process outlined above.
+
## Automatic Backups
:::caution