danvics/selfhostblocks
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

postgresql: add usage documentation

Browse source
This commit is contained in:
ibizaman 2025-12-29 09:28:11 +01:00 committed by Pierre Penninckx
parent 7c457c7226
commit f204c98230
2 changed files with 43 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
docs/redirects.json
View file

@ -1148,6 +1148,9 @@
"blocks-postgresql-contract-databasebackup-all": [
"blocks-postgresql.html#blocks-postgresql-contract-databasebackup-all"
],
"blocks-postgresql-ensures": [
"blocks-postgresql.html#blocks-postgresql-ensures"
],
"blocks-postgresql-options": [
"blocks-postgresql.html#blocks-postgresql-options"
],
@ -1199,6 +1202,9 @@
"blocks-postgresql-tests": [
"blocks-postgresql.html#blocks-postgresql-tests"
],
"blocks-postgresql-usage": [
"blocks-postgresql.html#blocks-postgresql-usage"
],
"blocks-restic": [
"blocks-restic.html#blocks-restic"
],

41
modules/blocks/postgresql/docs/default.md
View file

@ -6,17 +6,46 @@ This block sets up a [PostgreSQL][] database.
[postgresql]: https://www.postgresql.org/
## Tests {#blocks-postgresql-tests}
Compared to the upstream nixpkgs module, this module also sets up:
Specific integration tests are defined in [`/test/blocks/postgresql.nix`](@REPO@/test/blocks/postgresql.nix).
- Enabling TCP/IP login and also accepting password authentication from localhost with [`shb.postgresql.enableTCPIP`](#blocks-postgresql-options-shb.postgresql.enableTCPIP).
- Enhance the `ensure*` upstream option by setting up a database's password from a password file with [`shb.postgresql.ensures`](#blocks-postgresql-options-shb.postgresql.ensures).
- Debug logging with `auto_explain` and `pg_stat_statements` with [`shb.postgresql.debug`](#blocks-postgresql-options-shb.postgresql.debug).
## Database Backup Requester Contracts {#blocks-postgresql-contract-databasebackup}
## Usage {#blocks-postgresql-usage}
### Ensure User and Database {#blocks-postgresql-ensures}
Ensure a database and user exists:
```nix
shb.postgresql.ensures = [
{
username = "firefly-iii";
database = "firefly-iii";
}
];
```
Also set up the database password from a file path:
```nix
shb.postgresql.ensures = [
{
username = "firefly-iii";
database = "firefly-iii";
passwordFile = "/run/secrets/firefly-iii_db_password";
}
];
```
### Database Backup Requester Contracts {#blocks-postgresql-contract-databasebackup}
This block can be backed up using the [database backup](contracts-databasebackup.html) contract.
Contract integration tests are defined in [`/test/contracts/databasebackup.nix`](@REPO@/test/contracts/databasebackup.nix).
### Backing up All Databases {#blocks-postgresql-contract-databasebackup-all}
#### Backing up All Databases {#blocks-postgresql-contract-databasebackup-all}
```nix
{
@ -30,6 +59,10 @@ Contract integration tests are defined in [`/test/contracts/databasebackup.nix`]
}
```
## Tests {#blocks-postgresql-tests}
Specific integration tests are defined in [`/test/blocks/postgresql.nix`](@REPO@/test/blocks/postgresql.nix).
## Options Reference {#blocks-postgresql-options}
```{=include=} options