chore(test): document DB_HOST and TEST_DBHOST variables (#646)

Because

- The names of these variables are similar but they have different uses
(coverage vs integration tests).

This commit

- Documents such variables.

.env

@@ -13,5 +13,11 @@ DOCKER_BUILDKIT=1
 COMPOSE_DOCKER_CLI_BUILD=1
 
 # test
+
+# TEST_DBHOST and TEST_DBNAME are used to initialize a separate database for
+# coverage tests. In general, test queries will be run within a transaction
+# that will be rolled back on cleanup, but there might be cases where this
+# isn't possible (e.g. lock tests). We want to keep these queries isolated from
+# the main database.
 TEST_DBHOST=localhost
 TEST_DBNAME=pipeline_test

.github/CONTRIBUTING.md

@@ -67,13 +67,35 @@ $ docker exec -it pipeline-backend /bin/bash
 $ go run ./cmd/worker
 ```
 
+### Run the unit tests
+
+```bash
+$ make coverate DBTEST=true
+```
+
+The repository tests in `make coverage` run against a real database (in contrast
+to a mocked one) in order to increase the confidence of the tests. `DBTEST=true`
+will create and migrate a test database to keep these queries isolated from the
+main DB. You can set the database host and name by overriding the `TEST_DBHOST`
+and `TEST_DBNAME` values.
+
 ### Run the integration test
 
 ```bash
 $ docker exec -it pipeline-backend /bin/bash
-$ make integration-test
+$ make integration-test API_GATEWAY_URL=api-gateway:8080 DB_HOST=pg-sql
 ```
 
+`API_GATEWAY_URL` points to the `api-gateway` container and triggers the public
+API tests. If this variable is empty, the private API tests will be run.
+
+At the end of the tests, some SQL queries are run to clean up the data.
+`DB_HOST` points to the database host so the SQL connection can be established.
+If empty, tests will try to connect to `localhost:5432`.
+
+```bash
+$ make integration-test API_GATEWAY_URL=api-gateway:8080 DB_HOST=pg-sql
+`
 ### Stop the dev container
 
 ```bash

Makefile

@@ -96,6 +96,8 @@ coverage:
 
 .PHONY: integration-test
 integration-test:				## Run integration test
+	@ # DB_HOST points to localhost by default. Override this variable if
+	@ # pipeline-backend's database isn't accessible at that host.
 	@TEST_FOLDER_ABS_PATH=${PWD} k6 run \
 		-e API_GATEWAY_PROTOCOL=${API_GATEWAY_PROTOCOL} \
 		-e API_GATEWAY_URL=${API_GATEWAY_URL} \