1# Contributing
2
3## Discuss Significant Changes
4
5Before you invest a significant amount of time on a change, please create a discussion or issue describing your
6proposal. This will help to ensure your proposed change has a reasonable chance of being merged.
7
8## Avoid Dependencies
9
10Adding a dependency is a big deal. While on occasion a new dependency may be accepted, the default answer to any change
11that adds a dependency is no.
12
13## Development Environment Setup
14
15pgx tests naturally require a PostgreSQL database. It will connect to the database specified in the `PGX_TEST_DATABASE`
16environment variable. The `PGX_TEST_DATABASE` environment variable can either be a URL or key-value pairs. In addition,
17the standard `PG*` environment variables will be respected. Consider using [direnv](https://github.com/direnv/direnv) to
18simplify environment variable handling.
19
20### Using an Existing PostgreSQL Cluster
21
22If you already have a PostgreSQL development server this is the quickest way to start and run the majority of the pgx
23test suite. Some tests will be skipped that require server configuration changes (e.g. those testing different
24authentication methods).
25
26Create and setup a test database:
27
28```
29export PGDATABASE=pgx_test
30createdb
31psql -c 'create extension hstore;'
32psql -c 'create domain uint64 as numeric(20,0);'
33```
34
35Ensure a `postgres` user exists. This happens by default in normal PostgreSQL installs, but some installation methods
36such as Homebrew do not.
37
38```
39createuser -s postgres
40```
41
42Ensure your `PGX_TEST_DATABASE` environment variable points to the database you just created and run the tests.
43
44```
45export PGX_TEST_DATABASE="host=/private/tmp database=pgx_test"
46go test ./...
47```
48
49This will run the vast majority of the tests, but some tests will be skipped (e.g. those testing different connection methods).
50
51### Creating a New PostgreSQL Cluster Exclusively for Testing
52
53The following environment variables need to be set both for initial setup and whenever the tests are run. (direnv is
54highly recommended). Depending on your platform, you may need to change the host for `PGX_TEST_UNIX_SOCKET_CONN_STRING`.
55
56```
57export PGPORT=5015
58export PGUSER=postgres
59export PGDATABASE=pgx_test
60export POSTGRESQL_DATA_DIR=postgresql
61
62export PGX_TEST_DATABASE="host=127.0.0.1 database=pgx_test user=pgx_md5 password=secret"
63export PGX_TEST_UNIX_SOCKET_CONN_STRING="host=/private/tmp database=pgx_test"
64export PGX_TEST_TCP_CONN_STRING="host=127.0.0.1 database=pgx_test user=pgx_md5 password=secret"
65export PGX_TEST_SCRAM_PASSWORD_CONN_STRING="host=127.0.0.1 user=pgx_scram password=secret database=pgx_test"
66export PGX_TEST_MD5_PASSWORD_CONN_STRING="host=127.0.0.1 database=pgx_test user=pgx_md5 password=secret"
67export PGX_TEST_PLAIN_PASSWORD_CONN_STRING="host=127.0.0.1 user=pgx_pw password=secret"
68export PGX_TEST_TLS_CONN_STRING="host=localhost user=pgx_ssl password=secret sslmode=verify-full sslrootcert=`pwd`/.testdb/ca.pem"
69export PGX_SSL_PASSWORD=certpw
70export PGX_TEST_TLS_CLIENT_CONN_STRING="host=localhost user=pgx_sslcert sslmode=verify-full sslrootcert=`pwd`/.testdb/ca.pem database=pgx_test sslcert=`pwd`/.testdb/pgx_sslcert.crt sslkey=`pwd`/.testdb/pgx_sslcert.key"
71```
72
73Create a new database cluster.
74
75```
76initdb --locale=en_US -E UTF-8 --username=postgres .testdb/$POSTGRESQL_DATA_DIR
77
78echo "listen_addresses = '127.0.0.1'" >> .testdb/$POSTGRESQL_DATA_DIR/postgresql.conf
79echo "port = $PGPORT" >> .testdb/$POSTGRESQL_DATA_DIR/postgresql.conf
80cat testsetup/postgresql_ssl.conf >> .testdb/$POSTGRESQL_DATA_DIR/postgresql.conf
81cp testsetup/pg_hba.conf .testdb/$POSTGRESQL_DATA_DIR/pg_hba.conf
82
83cd .testdb
84
85# Generate CA, server, and encrypted client certificates.
86go run ../testsetup/generate_certs.go
87
88# Copy certificates to server directory and set permissions.
89cp ca.pem $POSTGRESQL_DATA_DIR/root.crt
90cp localhost.key $POSTGRESQL_DATA_DIR/server.key
91chmod 600 $POSTGRESQL_DATA_DIR/server.key
92cp localhost.crt $POSTGRESQL_DATA_DIR/server.crt
93
94cd ..
95```
96
97
98Start the new cluster. This will be necessary whenever you are running pgx tests.
99
100```
101postgres -D .testdb/$POSTGRESQL_DATA_DIR
102```
103
104Setup the test database in the new cluster.
105
106```
107createdb
108psql --no-psqlrc -f testsetup/postgresql_setup.sql
109```
110
111### PgBouncer
112
113There are tests specific for PgBouncer that will be executed if `PGX_TEST_PGBOUNCER_CONN_STRING` is set.
114
115### Optional Tests
116
117pgx supports multiple connection types and means of authentication. These tests are optional. They will only run if the
118appropriate environment variables are set. In addition, there may be tests specific to particular PostgreSQL versions,
119non-PostgreSQL servers (e.g. CockroachDB), or connection poolers (e.g. PgBouncer). `go test ./... -v | grep SKIP` to see
120if any tests are being skipped.
View as plain text