Merge branch 'multiple-databases-gdk' into 'master'

Add instructions how to setup GDK for multiple databases

See merge request gitlab-org/gitlab!74968

doc/development/database/multiple_databases.md

@@ -15,10 +15,46 @@ To scale GitLab, the we are
 database for CI/CD tables was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64289)
 in GitLab 14.1. This feature is still under development, and is not ready for production use.
 
+### Development setup
+
 By default, GitLab is configured to use only one main database. To
 opt-in to use a main database, and CI database, modify the
 `config/database.yml` file to have a `main` and a `ci` database
-configurations. For example, given a `config/database.yml` like below:
+configurations.
+
+You can set this up using [GDK](#gdk-configuration) or by
+[manually configuring `config/database.yml`](#manually-set-up-the-cicd-database).
+
+#### GDK configuration
+
+If you are using GDK, you can follow the following steps:
+
+1. On the GDK root directory, run:
+
+   ```shell
+   gdk config set gitlab.rails.multiple_databases true
+   ```
+
+1. Open your `gdk.yml`, and confirm that it has the following lines:
+
+   ```yaml
+   gitlab:
+     rails:
+       multiple_databases: true
+   ```
+
+1. Reconfigure GDK:
+
+   ```shell
+   gdk reconfigure
+   ```
+
+1. [Create the new CI/CD database](#create-the-new-database).
+
+#### Manually set up the CI/CD database
+
+You can manually edit `config/database.yml` to split the databases.
+To do so, consider a `config/database.yml` file like the example below:
 
 ```yaml
 development:
@@ -44,7 +80,7 @@ test: &test
       statement_timeout: 120s
 ```
 
-Edit the `config/database.yml` to look like this:
+Edit it to split the databases into `main` and `ci`:
 
 ```yaml
 development:
@@ -88,6 +124,25 @@ test: &test
       statement_timeout: 120s
 ```
 
+Next, [create the new CI/CD database](#create-the-new-database).
+
+#### Create the new database
+
+After configuring GitLab for the two databases, create the new CI/CD database:
+
+1. Create the new `ci:` database, load the DB schema into the `ci:` database,
+   and run any pending migrations:
+
+    ```shell
+    bundle exec rails rails db:create db:schema:load:ci db:migrate
+    ```
+
+1. Restart GDK:
+
+    ```shell
+    gdk restart
+    ```
+
 <!--
 NOTE: The `validate_cross_joins!` method in `spec/support/database/prevent_cross_joins.rb` references
       the following heading in the code, so if you make a change to this heading, make sure to update