diff options
author | Robert Hensing <roberth@users.noreply.github.com> | 2022-04-18 11:58:34 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-04-18 11:58:34 +0200 |
commit | 33cf95ef36d9e2e7aec511297de9a845d6b729fe (patch) | |
tree | 4b3c1c77b3e120a6a81060ee4debb3f43113a9b0 /doc | |
parent | 790851c44defd6863fd8e9fde62885791d4a2f9e (diff) | |
parent | 99fed858bbb77490a70a3e33713b66b4ccae1b03 (diff) | |
download | nixpkgs-33cf95ef36d9e2e7aec511297de9a845d6b729fe.tar nixpkgs-33cf95ef36d9e2e7aec511297de9a845d6b729fe.tar.gz nixpkgs-33cf95ef36d9e2e7aec511297de9a845d6b729fe.tar.bz2 nixpkgs-33cf95ef36d9e2e7aec511297de9a845d6b729fe.tar.lz nixpkgs-33cf95ef36d9e2e7aec511297de9a845d6b729fe.tar.xz nixpkgs-33cf95ef36d9e2e7aec511297de9a845d6b729fe.tar.zst nixpkgs-33cf95ef36d9e2e7aec511297de9a845d6b729fe.zip |
Merge pull request #168932 from hercules-ci/init-postgresqlTestHook
`postgresqlTestHook`: init
Diffstat (limited to 'doc')
-rw-r--r-- | doc/hooks/index.xml | 10 | ||||
-rw-r--r-- | doc/hooks/postgresql-test-hook.section.md | 59 | ||||
-rw-r--r-- | doc/manual.xml | 1 |
3 files changed, 70 insertions, 0 deletions
diff --git a/doc/hooks/index.xml b/doc/hooks/index.xml new file mode 100644 index 00000000000..6a046eae288 --- /dev/null +++ b/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/doc/hooks/postgresql-test-hook.section.md b/doc/hooks/postgresql-test-hook.section.md new file mode 100644 index 00000000000..077fac14ebb --- /dev/null +++ b/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. +::: diff --git a/doc/manual.xml b/doc/manual.xml index b43021d85ca..e49ae67ec94 100644 --- a/doc/manual.xml +++ b/doc/manual.xml @@ -27,6 +27,7 @@ <xi:include href="builders/trivial-builders.chapter.xml" /> <xi:include href="builders/special.xml" /> <xi:include href="builders/images.xml" /> + <xi:include href="hooks/index.xml" /> <xi:include href="languages-frameworks/index.xml" /> <xi:include href="builders/packages/index.xml" /> </part> |