Documentation: Dedicated database configuration

README.md

@@ -145,6 +145,52 @@ When receiving a `QUIT` signal, if workers still have jobs in-flight, these will
 
 If processes have no chance of cleaning up before exiting (e.g. if someone pulls a cable somewhere), in-flight jobs might remain claimed by the processes executing them. Processes send heartbeats, and the supervisor checks and prunes processes with expired heartbeats, which will release any claimed jobs back to their queues. You can configure both the frequency of heartbeats and the threshold to consider a process dead. See the section below for this.
 
+
+### Dedicated database configuration
+
+Solid Queue can be configured to run on a different database than the main application.
+
+Configure the `connects_to` option in `config/application.rb` or your environment config like so, where `:solid_queue` is the identifier for your dedicated Solid Queue database.
+
+```ruby
+config.solid_queue.connects_to = { database: { writing: :solid_queue, reading: :solid_queue } }
+```
+
+Add the dedicated database configuration to `config/database.yml`, differentiating between the main `:primary` database and the dedicated `:solid_queue` database. Make sure to include the `migrations_paths` for the solid queue database. This is where migration files for Solid Queue tables will reside.
+
+```yml
+default: &default
+  adapter: sqlite3
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
+  timeout: 5000
+
+solid_queue: &solid_queue
+  <<: *default
+  migrations_paths: db/solid_queue_migrate
+
+development:
+  primary:
+    <<: *default
+    database: storage/development.sqlite3
+  solid_queue:
+    <<: *solid_queue
+    database: storage/development_solid_queue.sqlite3
+```
+
+Install migrations and specify the dedicated database name with the `DATABASE` option. This will create the Solid Queue migration files in a separate directory, matching the value provided in `migrations_paths` in `config/database.yml`.
+
+```bash
+$ bin/rails solid_queue:install:migrations DATABASE=solid_queue
+```
+
+Note: If you've already run the solid queue install command (`bin/rails generate solid_queue:install`), the migration files will have already been generated under the primary database's `db/migrate/` directory. You can remove these files and keep the ones generated by the database-specific migration installation above.
+
+Finally, run the migrations:
+
+```bash
+$ bin/rails db:migrate
+```
+
 ### Other configuration settings
 _Note_: The settings in this section should be set in your `config/application.rb` or your environment config like this: `config.solid_queue.silence_polling = true`