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