From 2153fc10f02924be22441f44094f4319c8693c5b Mon Sep 17 00:00:00 2001
From: Omid Andalib <24489388+oandalib@users.noreply.github.com>
Date: Sat, 26 Oct 2024 13:10:22 -0700
Subject: [PATCH] docs: update README for restoration

---
 README.md | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 3607bf3..103018a 100644
--- a/README.md
+++ b/README.md
@@ -155,20 +155,28 @@ The Litestream `replicate` command supports the following options, which can be
 
 ### Restoration
 
-You can restore any replicated database at any point using the gem's provided `litestream:restore` rake task. This rake task requires that you specify which specific database you want to restore. As with the `litestream:replicate` task, you pass arguments to the rake task via argument forwarding. For example, to restore the production database, you would run:
-
-```shell
-bin/rails litestream:restore -- --database=storage/production.sqlite3
-# or
-bundle exec rake litestream:restore -- --database=storage/production.sqlite3
-```
+You can restore any replicated database at any point using the gem's provided `litestream:restore` rake task. This rake task requires that you specify which specific database you want to restore. As with the `litestream:replicate` task, you pass arguments to the rake task via argument forwarding. For example, to restore the production database, you would do the following:
+
+Note: During the restoration process, you need to prevent any interaction with ActiveRecord/SQLite. If there is any interaction, Rails might regenerate the production database and prevent restoration via litestream. If this happens, you might get a "cannot restore, output path already exists" error.
+1. Rename the production databases (RECOMMENDED) or alternatively delete (production.sqlite3/production.sqlite3-shm/production.sqlite3-wal). To delete the production databases locally, you can run the following at your own risk:
+   ```shell
+   # DANGEROUS OPERATION, consider renaming database files instead
+   bin/rails db:drop DISABLE_DATABASE_ENVIRONMENT_CHECK=1
+   ```
+2. Run restore command:
+   ```shell
+   bin/rails litestream:restore -- --database=storage/production.sqlite3
+   # or
+   bundle exec rake litestream:restore -- --database=storage/production.sqlite3
+   ```
+3. Restart your Rails application or Docker container if applicable.
 
 You can restore any of the databases specified in your `config/litestream.yml` file. The `--database` argument should be the path to the database file you want to restore and must match the value for the `path` key of one of your configured databases. The `litestream:restore` rake task will automatically load the configuration file and set the environment variables before calling the Litestream executable.
 
 If you need to pass arguments through the rake task to the underlying `litestream` command, that can be done with additional forwarded arguments:
 
 ```shell
-bin/rails litestream:replicate -- --database=storage/production.sqlite3 --if-db-not-exists
+bin/rails litestream:restore -- --database=storage/production.sqlite3 --if-db-not-exists
 ```
 
 You can forward arguments in whatever order you like, you simply need to ensure that the `--database` argument is present. You can also use either a single-dash `-database` or double-dash `--database` argument format. The Litestream `restore` command supports the following options, which can be passed through the rake task: