diff options
author | Alyssa Ross <hi@alyssa.is> | 2022-12-06 19:57:55 +0000 |
---|---|---|
committer | Alyssa Ross <hi@alyssa.is> | 2023-02-08 13:48:30 +0000 |
commit | bf3aadfdd39aa197e18bade671fab6726349ffa4 (patch) | |
tree | 698567af766ed441d757b57a7b21e68d4a342a2b /nixpkgs/doc/hooks | |
parent | f4afc5a01d9539ce09e47494e679c51f80723d07 (diff) | |
parent | 99665eb45f58d959d2cb9e49ddb960c79d596f33 (diff) | |
download | nixlib-bf3aadfdd39aa197e18bade671fab6726349ffa4.tar nixlib-bf3aadfdd39aa197e18bade671fab6726349ffa4.tar.gz nixlib-bf3aadfdd39aa197e18bade671fab6726349ffa4.tar.bz2 nixlib-bf3aadfdd39aa197e18bade671fab6726349ffa4.tar.lz nixlib-bf3aadfdd39aa197e18bade671fab6726349ffa4.tar.xz nixlib-bf3aadfdd39aa197e18bade671fab6726349ffa4.tar.zst nixlib-bf3aadfdd39aa197e18bade671fab6726349ffa4.zip |
Merge commit '99665eb45f58d959d2cb9e49ddb960c79d596f33'
Diffstat (limited to 'nixpkgs/doc/hooks')
-rw-r--r-- | nixpkgs/doc/hooks/index.xml | 10 | ||||
-rw-r--r-- | nixpkgs/doc/hooks/postgresql-test-hook.section.md | 59 |
2 files changed, 69 insertions, 0 deletions
diff --git a/nixpkgs/doc/hooks/index.xml b/nixpkgs/doc/hooks/index.xml new file mode 100644 index 000000000000..6a046eae2885 --- /dev/null +++ b/nixpkgs/doc/hooks/index.xml @@ -0,0 +1,10 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + xml:id="chap-hooks"> + <title>Hooks reference</title> + <para> + Nixpkgs has several hook packages that augment the stdenv phases. + </para> + <xi:include href="./postgresql-test-hook.section.xml" /> +</chapter> diff --git a/nixpkgs/doc/hooks/postgresql-test-hook.section.md b/nixpkgs/doc/hooks/postgresql-test-hook.section.md new file mode 100644 index 000000000000..077fac14ebbf --- /dev/null +++ b/nixpkgs/doc/hooks/postgresql-test-hook.section.md @@ -0,0 +1,59 @@ + +# `postgresqlTestHook` {#sec-postgresqlTestHook} + +This hook starts a PostgreSQL server during the `checkPhase`. Example: + +```nix +{ stdenv, postgresql, postgresqlTestHook }: +stdenv.mkDerivation { + + # ... + + checkInputs = [ + postgresql + postgresqlTestHook + ]; +} +``` + +If you use a custom `checkPhase`, remember to add the `runHook` calls: +```nix + checkPhase '' + runHook preCheck + + # ... your tests + + runHook postCheck + '' +``` + +## Variables {#sec-postgresqlTestHook-variables} + +The hook logic will read a number of variables and set them to a default value if unset or empty. + +Exported variables: + + - `PGDATA`: location of server files. + - `PGHOST`: location of UNIX domain socket directory; the default `host` in a connection string. + - `PGUSER`: user to create / log in with, default: `test_user`. + - `PGDATABASE`: database name, default: `test_db`. + +Bash-only variables: + + - `postgresqlTestUserOptions`: SQL options to use when creating the `$PGUSER` role, default: `LOGIN`. + - `postgresqlTestSetupSQL`: SQL commands to run as database administrator after startup, default: statements that create `$PGUSER` and `$PGDATABASE`. + - `postgresqlTestSetupCommands`: bash commands to run after database start, defaults to running `$postgresqlTestSetupSQL` as database administrator. + - `postgresqlEnableTCP`: set to `1` to enable TCP listening. Flaky; not recommended. + - `postgresqlStartCommands`: defaults to `pg_ctl start`. + +## TCP and the Nix sandbox {#sec-postgresqlTestHook-tcp} + +`postgresqlEnableTCP` relies on network sandboxing, which is not available on macOS and some custom Nix installations, resulting in flaky tests. +For this reason, it is disabled by default. + +The preferred solution is to make the test suite use a UNIX domain socket connection. This is the default behavior when no `host` connection parameter is provided. +Some test suites hardcode a value for `host` though, so a patch may be required. If you can upstream the patch, you can make `host` default to the `PGHOST` environment variable when set. Otherwise, you can patch it locally to omit the `host` connection string parameter altogether. + +::: {.note} +The error `libpq: failed (could not receive data from server: Connection refused` is generally an indication that the test suite is trying to connect through TCP. +::: |