[+] add "Bootstrapping the Configuration Database" how-to

Author: pashagolub

docs/howto/config_db_bootstrap.md

@@ -0,0 +1,90 @@
+---
+title: Bootstrapping the Configuration Database
+---
+
+## Choosing a Database
+
+pgwatch supports any database that supports the PostgreSQL wire protocol. This includes:
+
+- PostgreSQL
+- TimescaleDB
+- CitusDB
+- CockroachDB
+- many more
+
+We will use PostgreSQL in this guide. But the steps are similar for other databases. It's up to you to choose the database that best fits your needs and set it up accordingly.
+
+## Creating the Database
+
+First, we need to create a database for storing the configuration. We will use the `psql` command-line tool to create the database. You can also use a GUI tool like pgAdmin to create the database.
+
+Let's assume we want to create a database named `pgwatch` on a completely fresh PostgreSQL installation.
+It is wise to use a special role for the configuration database, so we will create a role named `pgwatch` and assign it to the `pgwatch` database.
+
+```terminal
+$ psql -U postgres -h localhost -p 5432 -d postgres
+psql (17.2)
+
+postgres=# CREATE ROLE pgwatch WITH LOGIN PASSWORD 'pgwatchadmin';
+CREATE ROLE
+
+postgres=# CREATE DATABASE pgwatch OWNER pgwatch;
+CREATE DATABASE
+```
+
+That's it! We have created a database named `pgwatch` with the owner `pgwatch`. Now we can proceed to the next step.
+
+## Init (optional)
+
+pgwatch will automatically create the necessary tables and indexes in the database when it starts. But in case
+you want to create the schema as a separate step, you can use the `config init` command-line command. The only thing you
+need is to provide the connection string to the database.
+
+```terminal
+pgwatch --sources=postgresql://pgwatch:pgwatchadmin@localhost/pgwatch config init
+```
+
+Or you can use the `config init` command with the `--metrics` flag, since metrics and sources share the same database.
+
+```terminal
+pgwatch --metrics=postgresql://pgwatch:pgwatchadmin@localhost/pgwatch config init
+```
+
+## Usage
+
+You can now configure pgwatch to use the `pgwatch` database as the configuration database for storing monitored sources,
+metric deinitions and presets.
+
+```terminal
+$ pgwatch --sources=postgresql://pgwatch:pgwatchadmin@localhost/pgwatch --sink=postgresql://[email protected]/measurements
+...
+[INFO] [metrics:75] [presets:17] [sources:2] sources and metrics refreshed
+...
+```
+
+!!! info
+    Even though configuration database can hold both sources and metrics definitions,
+    you are free to use any combination of configurations. For example, you can use a database
+    for metrics and YAML file for sources, or vice versa.
+
+That's it! You have successfully bootstrapped the configuration database for pgwatch.
+
+If now you want to see the tables created by pgwatch in the configuration database, you can connect to the database
+using the `psql` command-line tool and list the tables.
+
+```terminal
+$ psql postgresql://pgwatch:pgwatchadmin@localhost/pgwatch
+psql (17.2)
+
+pgwatch=# \dt pgwatch.*
+           List of relations
+ Schema  |   Name    | Type  |  Owner
+---------+-----------+-------+---------
+ pgwatch | metric    | table | pgwatch
+ pgwatch | migration | table | pgwatch
+ pgwatch | preset    | table | pgwatch
+ pgwatch | source    | table | pgwatch
+(4 rows)
+```
+
+You may examine these tables to understand how pgwatch stores metrics and presets definitions, as well as what sources and how to monitor in the database.

docs/howto/metrics_db_bootstrap.md

@@ -2,7 +2,7 @@
 title: Bootstrapping the Metrics Measurements Database (Sink)
 ---
 
-# Choosing a Database
+## Choosing a Database
 
 pgwatch supports multiple databases for storing metrics measurements. The following databases are supported:
 
@@ -14,14 +14,14 @@ pgwatch supports multiple databases for storing metrics measurements. The follow
 
 We will use PostgreSQL in this guide. But the steps are similar for other databases. It's up to you to choose the database that best fits your needs and set it up accordingly.
 
-# Creating the Database
+## Creating the Database
 
 First, we need to create a database for storing the metrics measurements. We will use the `psql` command-line tool to create the database. You can also use a GUI tool like pgAdmin to create the database.
 
-Let's assume we want to create a database named `measurements` on a completely fresh PostgreSQL installation. 
+Let's assume we want to create a database named `measurements` on a completely fresh PostgreSQL installation.
 It is wise to use a special role for the metrics database, so we will create a role named `pgwatch` and assign it to the `measurements` database.
 
-```
+```terminal
 $ psql -U postgres -h 10.0.0.42 -p 5432 -d postgres
 psql (17.2)
 
@@ -34,24 +34,24 @@ CREATE DATABASE
 
 That's it! We have created a database named `measurements` with the owner `pgwatch`. Now we can proceed to the next step.
 
-# Usage
+## Usage
 
 pgwatch will automatically create the necessary tables and indexes in the database when it starts. You don't need to create any tables or indexes manually.
 
-You can now configure pgwatch to use the `measurements` database as the sink for storing metrics measurements. 
+You can now configure pgwatch to use the `measurements` database as the sink for storing metrics measurements.
 
-```bash
+```terminal
 $ pgwatch --sources=/etc/sources.yaml --sink=postgresql://[email protected]/measurements
 [INFO] [sink:postgresql://[email protected]/measurements] Initialising measurements database...
 [INFO] [sink:postgresql://[email protected]/measurements] Measurements sink activated
 ...
 ```
 
-That's it! You have successfully bootstrapped the metrics measurements database for pgwatch. You can now start collecting metrics from your sources and storing them in the database. 
+That's it! You have successfully bootstrapped the metrics measurements database for pgwatch. You can now start collecting metrics from your sources and storing them in the database.
 
 If now you want to see the tables created by pgwatch in the `measurements` database, you can connect to the database using the `psql` command-line tool and list the tables.
 
-```
+```terminal
 $ psql -U pgwatch -h 10.0.0.42 -p 5432 -d measurements
 psql (17.2)
 
@@ -67,6 +67,6 @@ measurements=> \dn
 You can see that pgwatch has created the `admin` and `subpartitions` schemas in the `measurements` database. These schemas contain the tables and indexes used by pgwatch to store metrics measurements. You may examine these schemas to understand how pgwatch stores metrics measurements in the database.
 
 !!! tip
-    You can also add `--log-level=debug` command-line parameter to see every SQL query executed by pgwatch. 
-    This can be useful for debugging purposes. But remember that this will log a lot of information, 
-    so it is wise to use it with empty sources this time, meaning there are no database to monitor yet.
+    You can also add `--log-level=debug` command-line parameter to see every SQL query executed by pgwatch.
+    This can be useful for debugging purposes. But remember that this will log a lot of information,
+    so it is wise to use it with empty sources this time, meaning there are no database to monitor yet.

mkdocs.yml

@@ -62,6 +62,7 @@ nav:
   - How-To Guides:
     - Dashboarding and Alerting: howto/dashboarding_alerting.md
     - Using Managed Services: howto/using_managed_services.md
+    - Bootstrapping the Configuration Database: howto/config_db_bootstrap.md
     - Bootstraping the Metrics Measurements Database (Sink): howto/metrics_db_bootstrap.md
   - Reference:
     - Advanced Features: reference/advanced_features.md