BCDA-8350: Add workflow to generate database docs

.github/workflows/dbdocs.yml

@@ -0,0 +1,44 @@
+# This workflow generates database documentation and ERD files.
+#
+name: Generate dbdocs
+
+on:
+  pull_request:
+    paths:
+      - .github/workflows/dbdocs.yml
+      - db/migrations/bcda
+      - db/migrations/bcda_queue
+
+env:
+  VAULT_PW: ${{ secrets.VAULT_PW }}
+
+jobs:
+  generate-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.ref }}
+
+      - name: Decrypt secrets
+        run: |
+          echo $VAULT_PW > .vault_password
+          bash ops/secrets --decrypt
+          mv -fv shared_files/encrypted/* shared_files/decrypted/
+
+      - name: Start DB
+        run: make reset-db
+
+      - name: Generate DB docs
+        run: make dbdocs
+
+      - uses: EndBug/add-and-commit@a94899bca583c204427a224a7af87c02f9b325d5 # v9.1.4
+        with:
+          add: dbdocs
+          message: "Generate dbdocs"
+          default_author: github_actions
+
+      - name: Cleanup secrets
+        if: always()
+        run: rm -r shared_files/decrypted shared_files/encrypted .vault_password

Makefile

@@ -93,7 +93,7 @@ test:
 	$(MAKE) postman env=local maintenanceMode=""
 	$(MAKE) smoke-test env=local maintenanceMode=""
 
-load-fixtures:
+reset-db:
 	# Rebuild the databases to ensure that we're starting in a fresh state
 	docker compose -f docker-compose.yml rm -fsv db queue
 
@@ -106,6 +106,7 @@ load-fixtures:
 	docker run --rm -v ${PWD}/db/migrations:/migrations --network bcda-app-net migrate/migrate -path=/migrations/bcda/ -database 'postgres://postgres:toor@db:5432/bcda?sslmode=disable&x-migrations-table=schema_migrations_bcda' up
 	docker run --rm -v ${PWD}/db/migrations:/migrations --network bcda-app-net migrate/migrate -path=/migrations/bcda_queue/ -database 'postgres://postgres:toor@queue:5432/bcda_queue?sslmode=disable&x-migrations-table=schema_migrations_bcda_queue' up
 
+load-fixtures: reset-db
 	docker compose run db psql -v ON_ERROR_STOP=1 "postgres://postgres:toor@db:5432/bcda?sslmode=disable" -f /var/db/fixtures.sql
 	$(MAKE) load-synthetic-cclf-data
 	$(MAKE) load-synthetic-suppression-data
@@ -189,7 +190,7 @@ bdt:
 	-e SECRET='${CLIENT_SECRET}' \
 	bdt
 
-.PHONY: api-shell debug-api debug-worker docker-bootstrap docker-build lint load-fixtures load-fixtures-ssas load-synthetic-cclf-data load-synthetic-suppression-data package performance-test postman release smoke-test test unit-test worker-shell bdt unit-test-db unit-test-db-snapshot
+.PHONY: api-shell debug-api debug-worker docker-bootstrap docker-build lint load-fixtures load-fixtures-ssas load-synthetic-cclf-data load-synthetic-suppression-data package performance-test postman release smoke-test test unit-test worker-shell bdt unit-test-db unit-test-db-snapshot reset-db dbdocs
 
 documentation:
 	docker compose up --build documentation
@@ -201,6 +202,9 @@ credentials:
 	# For example: ACO_CMS_ID=A9993 make credentials 
 	@docker compose run --rm api sh -c 'bcda reset-client-credentials --cms-id $(ACO_CMS_ID)'|tail -n2
 
+dbdocs:
+	docker run --rm -v $PWD:/work -w /work --network bcda-app-net ghcr.io/k1low/tbls doc --rm-dist "postgres://postgres:toor@db:5432/bcda?sslmode=disable" dbdocs/bcda
+	docker run --rm -v $PWD:/work -w /work --network bcda-app-net ghcr.io/k1low/tbls doc --force "postgres://postgres:toor@queue:5432/bcda_queue?sslmode=disable" dbdocs/bcda_queue
 
 # ==== Lambda ====
 

dbdocs/bcda/README.md

@@ -0,0 +1,30 @@
+# bcda
+
+## Tables
+
+| Name | Columns | Comment | Type |
+| ---- | ------- | ------- | ---- |
+| [public.schema_migrations_bcda](public.schema_migrations_bcda.md) | 2 |  | BASE TABLE |
+| [public.acos](public.acos.md) | 10 |  | BASE TABLE |
+| [public.cclf_beneficiaries](public.cclf_beneficiaries.md) | 7 |  | BASE TABLE |
+| [public.cclf_files](public.cclf_files.md) | 10 |  | BASE TABLE |
+| [public.job_keys](public.job_keys.md) | 7 |  | BASE TABLE |
+| [public.jobs](public.jobs.md) | 9 |  | BASE TABLE |
+| [public.suppression_files](public.suppression_files.md) | 6 |  | BASE TABLE |
+| [public.suppressions](public.suppressions.md) | 18 |  | BASE TABLE |
+| [public.alr](public.alr.md) | 12 |  | BASE TABLE |
+| [public.alr_meta](public.alr_meta.md) | 5 |  | BASE TABLE |
+
+## Stored procedures and functions
+
+| Name | ReturnType | Arguments | Type |
+| ---- | ------- | ------- | ---- |
+| public.trigger_set_timestamp | trigger |  | FUNCTION |
+
+## Relations
+
+![er](schema.svg)
+
+---
+
+> Generated by [tbls](https://github.com/k1LoW/tbls)

dbdocs/bcda/public.acos.md

@@ -0,0 +1,46 @@
+# public.acos
+
+## Description
+
+## Columns
+
+| Name | Type | Default | Nullable | Children | Parents | Comment |
+| ---- | ---- | ------- | -------- | -------- | ------- | ------- |
+| uuid | uuid |  | false | [public.jobs](public.jobs.md) |  |  |
+| name | text |  | false |  |  |  |
+| created_at | timestamp with time zone | now() | false |  |  |  |
+| updated_at | timestamp with time zone | now() | false |  |  |  |
+| id | integer | nextval('acos_id_seq'::regclass) | false |  |  |  |
+| client_id | text |  | true |  |  |  |
+| cms_id | varchar(8) |  | true |  |  |  |
+| group_id | text |  | true |  |  |  |
+| system_id | text |  | true |  |  |  |
+| termination_details | jsonb |  | true |  |  |  |
+
+## Constraints
+
+| Name | Type | Definition |
+| ---- | ---- | ---------- |
+| acos_pkey | PRIMARY KEY | PRIMARY KEY (uuid) |
+| acos_cms_id_key | UNIQUE | UNIQUE (cms_id) |
+
+## Indexes
+
+| Name | Definition |
+| ---- | ---------- |
+| acos_pkey | CREATE UNIQUE INDEX acos_pkey ON public.acos USING btree (uuid) |
+| acos_cms_id_key | CREATE UNIQUE INDEX acos_cms_id_key ON public.acos USING btree (cms_id) |
+
+## Triggers
+
+| Name | Definition |
+| ---- | ---------- |
+| set_timestamp | CREATE TRIGGER set_timestamp BEFORE UPDATE ON public.acos FOR EACH ROW EXECUTE FUNCTION trigger_set_timestamp() |
+
+## Relations
+
+![er](public.acos.svg)
+
+---
+
+> Generated by [tbls](https://github.com/k1LoW/tbls)

dbdocs/bcda/public.alr.md

@@ -0,0 +1,40 @@
+# public.alr
+
+## Description
+
+## Columns
+
+| Name | Type | Default | Nullable | Children | Parents | Comment |
+| ---- | ---- | ------- | -------- | -------- | ------- | ------- |
+| created_at | timestamp with time zone | now() | false |  |  |  |
+| updated_at | timestamp with time zone | now() | false |  |  |  |
+| id | bigint | nextval('alr_id_seq'::regclass) | false |  |  |  |
+| metakey | bigint |  | false |  | [public.alr_meta](public.alr_meta.md) |  |
+| mbi | character(11) |  | false |  |  |  |
+| hic | character(12) |  | true |  |  |  |
+| firstname | varchar(30) |  | true |  |  |  |
+| lastname | varchar(40) |  | true |  |  |  |
+| sex | character(1) |  | true |  |  |  |
+| dob | timestamp without time zone |  | true |  |  |  |
+| dod | timestamp without time zone |  | true |  |  |  |
+| keyvalue | bytea |  | true |  |  |  |
+
+## Constraints
+
+| Name | Type | Definition |
+| ---- | ---- | ---------- |
+| foreign_key_alr | FOREIGN KEY | FOREIGN KEY (metakey) REFERENCES alr_meta(id) ON UPDATE RESTRICT ON DELETE RESTRICT |
+
+## Triggers
+
+| Name | Definition |
+| ---- | ---------- |
+| set_timestamp | CREATE TRIGGER set_timestamp BEFORE UPDATE ON public.alr FOR EACH ROW EXECUTE FUNCTION trigger_set_timestamp() |
+
+## Relations
+
+![er](public.alr.svg)
+
+---
+
+> Generated by [tbls](https://github.com/k1LoW/tbls)