Improve testing / contributing instructions

* Extract CONTRIBUTING.md
* Add instructions and scripts to setup standalone PostgreSQL server
  that tests the various connection and authentication types.

.gitignore

@@ -22,3 +22,4 @@ _testmain.go
 *.exe
 
 .envrc
+/.testdb

CONTRIBUTING.md

@@ -0,0 +1,114 @@
+# Contributing
+
+## Development Environment Setup
+
+pgx tests naturally require a PostgreSQL database. It will connect to the database specified in the `PGX_TEST_DATABASE`
+environment variable. The `PGX_TEST_DATABASE` environment variable can either be a URL or key-value pairs. In addition,
+the standard `PG*` environment variables will be respected. Consider using [direnv](https://github.com/direnv/direnv) to
+simplify environment variable handling.
+
+### Using an Existing PostgreSQL Cluster
+
+If you already have a PostgreSQL development server this is the quickest way to start and run the majority of the pgx
+test suite. Some tests will be skipped that require server configuration changes (e.g. those testing different
+authentication methods).
+
+Create and setup a test database:
+
+```
+export PGDATABASE=pgx_test
+createdb
+psql -c 'create extension hstore;'
+psql -c 'create domain uint64 as numeric(20,0);'
+```
+
+Ensure a `postgres` user exists. This happens by default in normal PostgreSQL installs, but some installation methods
+such as Homebrew do not.
+
+```
+createuser -s postgres
+```
+
+Ensure your `PGX_TEST_DATABASE` environment variable points to the database you just created and run the tests.
+
+```
+export PGX_TEST_DATABASE="host=/private/tmp database=pgx_test"
+go test ./...
+```
+
+This will run the vast majority of the tests, but some tests will be skipped (e.g. those testing different connection methods).
+
+### Creating a New PostgreSQL Cluster Exclusively for Testing
+
+The following environment variables need to be set both for initial setup and whenever the tests are run. (direnv is
+highly recommended):
+
+```
+export PGPORT=5015
+export PGUSER=postgres
+export PGDATABASE=pgx_test
+export POSTGRESQL_DATA_DIR=postgresql
+
+export PGX_TEST_DATABASE="host=/private/tmp database=pgx_test"
+export PGX_TEST_UNIX_SOCKET_CONN_STRING="host=/private/tmp database=pgx_test"
+export PGX_TEST_TCP_CONN_STRING="host=127.0.0.1 database=pgx_test user=pgx_md5 password=secret"
+export PGX_TEST_MD5_PASSWORD_CONN_STRING="host=127.0.0.1 database=pgx_test user=pgx_md5 password=secret"
+export PGX_TEST_PLAIN_PASSWORD_CONN_STRING=postgres://pgx_pw:secret@127.0.0.1/pgx_test
+export PGX_TEST_TLS_CONN_STRING=postgres://pgx_ssl:secret@127.0.0.1/pgx_test?sslmode=require
+export PGX_TEST_SCRAM_PASSWORD_CONN_STRING="host=127.0.0.1 user=pgx_scram password=secret database=pgx_test"
+```
+
+Create a new database cluster.
+
+```
+initdb --locale=en_US -E UTF-8 --username=postgres .testdb/$POSTGRESQL_DATA_DIR
+echo "port = $PGPORT" >> .testdb/$POSTGRESQL_DATA_DIR/postgresql.conf
+cat testsetup/postgresql_ssl.conf >> .testdb/$POSTGRESQL_DATA_DIR/postgresql.conf
+cp testsetup/pg_hba.conf .testdb/$POSTGRESQL_DATA_DIR/pg_hba.conf
+
+cp testsetup/localhost.cnf .testdb
+
+cd .testdb
+
+# Generate a CA public / private key pair.
+openssl genrsa -out ca.key 4096
+openssl req -x509 -new -nodes -key ca.key -sha256 -days 3650 -subj '/O=pgx-test-root' -out ca.pem
+
+# Generate the certificate for localhost (the server).
+openssl genrsa -out localhost.key 2048
+openssl req -new -config localhost.cnf -key localhost.key -out localhost.csr
+openssl x509 -req -in localhost.csr -CA ca.pem -CAkey ca.key -CAcreateserial -out localhost.crt -days 3650 -sha256 -extfile localhost.cnf -extensions v3_req
+
+# Copy certificates to server directory and set permissions.
+cp ca.pem $POSTGRESQL_DATA_DIR/root.crt
+cp localhost.key $POSTGRESQL_DATA_DIR/server.key
+chmod 600 $POSTGRESQL_DATA_DIR/server.key
+cp localhost.crt $POSTGRESQL_DATA_DIR/server.crt
+
+cd ..
+```
+
+
+Start the new cluster. This will be necessary whenever you are running pgx tests.
+
+```
+postgres -D .testdb/$POSTGRESQL_DATA_DIR
+```
+
+Setup the test database in the new cluster.
+
+```
+createdb
+psql --no-psqlrc -f testsetup/postgresql_setup.sql
+```
+
+### PgBouncer
+
+There are tests specific for PgBouncer that will be executed if `PGX_TEST_PGBOUNCER_CONN_STRING` is set.
+
+### Optional Tests
+
+pgx supports multiple connection types and means of authentication. These tests are optional. They will only run if the
+appropriate environment variables are set. In addition, there may be tests specific to particular PostgreSQL versions,
+non-PostgreSQL servers (e.g. CockroachDB), or connection poolers (e.g. PgBouncer). `go test ./... -v | grep SKIP` to see
+if any tests are being skipped.

README.md

@@ -84,32 +84,7 @@ It is also possible to use the `database/sql` interface and convert a connection
 
 ## Testing
 
-pgx tests naturally require a PostgreSQL database. It will connect to the database specified in the `PGX_TEST_DATABASE` environment
+See CONTRIBUTING.md for setup instructions.
-variable. The `PGX_TEST_DATABASE` environment variable can either be a URL or DSN. In addition, the standard `PG*` environment
-variables will be respected. Consider using [direnv](https://github.com/direnv/direnv) to simplify environment variable
-handling.
-
-### Example Test Environment
-
-Connect to your PostgreSQL server and run:
-
-```
-create database pgx_test;
-```
-
-Connect to the newly-created database and run:
-
-```
-create domain uint64 as numeric(20,0);
-```
-
-Now, you can run the tests:
-
-```
-PGX_TEST_DATABASE="host=/var/run/postgresql database=pgx_test" go test ./...
-```
-
-In addition, there are tests specific for PgBouncer that will be executed if `PGX_TEST_PGBOUNCER_CONN_STRING` is set.
 
 ## Supported Go and PostgreSQL Versions
 

pgconn/README.md

@@ -26,28 +26,4 @@ if err != nil {
 
 ## Testing
 
-The pgconn tests require a PostgreSQL database. It will connect to the database specified in the `PGX_TEST_DATABASE`
+See CONTRIBUTING.md for setup instructions.
-environment variable. The `PGX_TEST_DATABASE` environment variable can be a URL or DSN. In addition, the standard `PG*`
-environment variables will be respected. Consider using [direnv](https://github.com/direnv/direnv) to simplify
-environment variable handling.
-
-### Example Test Environment
-
-Connect to your PostgreSQL server and run:
-
-```
-create database pgx_test;
-```
-
-Now you can run the tests:
-
-```bash
-PGX_TEST_DATABASE="host=/var/run/postgresql dbname=pgx_test" go test ./...
-```
-
-### Connection and Authentication Tests
-
-Pgconn supports multiple connection types and means of authentication. These tests are optional. They
-will only run if the appropriate environment variable is set. Run `go test -v | grep SKIP` to see if any tests are being
-skipped. Most developers will not need to enable these tests. See `ci/setup_test.bash` for an example set up if you need change
-authentication code.

testsetup/README.md

@@ -0,0 +1,3 @@
+# Test Setup
+
+This directory contains miscellaneous files used to setup a test database.

testsetup/localhost.cnf

@@ -0,0 +1,13 @@
+[ req ]
+default_bits       = 2048
+distinguished_name = dn
+req_extensions     = v3_req
+prompt             = no
+[ dn ]
+commonName         = localhost
+[ v3_req ]
+subjectAltName     = @alt_names
+keyUsage           = digitalSignature
+extendedKeyUsage   = serverAuth
+[alt_names]
+DNS.1              = localhost

testsetup/pg_hba.conf

@@ -0,0 +1,6 @@
+local     all         postgres                          trust
+local     all         all                               trust
+host      all         pgx_md5     127.0.0.1/32          md5
+host      all         pgx_scram   127.0.0.1/32          scram-sha-256
+host      all         pgx_pw      127.0.0.1/32          password
+hostssl   all         pgx_ssl     127.0.0.1/32          scram-sha-256

testsetup/postgresql_setup.sql

@@ -0,0 +1,15 @@
+-- Create extensions and types.
+create extension hstore;
+create domain uint64 as numeric(20,0);
+
+-- Create users for different types of connections and authentication.
+create user pgx_ssl PASSWORD 'secret';
+set password_encryption = md5;
+create user pgx_md5 PASSWORD 'secret';
+set password_encryption = 'scram-sha-256';
+create user pgx_pw PASSWORD 'secret';
+create user pgx_scram PASSWORD 'secret';
+
+-- The tricky test user, below, has to actually exist so that it can be used in a test
+-- of aclitem formatting. It turns out aclitems cannot contain non-existing users/roles.
+create user " tricky, ' } "" \\ test user " superuser password 'secret';

testsetup/postgresql_ssl.conf

@@ -0,0 +1,4 @@
+ssl = on
+ssl_cert_file = 'server.crt'
+ssl_key_file = 'server.key'
+ssl_ca_file = 'root.crt'