github.com/jackc/pgx/v5@v5.5.5/CONTRIBUTING.md (about)

     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  
    83  cd .testdb
    84  
    85  # Generate CA, server, and encrypted client certificates.
    86  go run ../testsetup/generate_certs.go
    87  
    88  # Copy certificates to server directory and set permissions.
    89  cp ca.pem $POSTGRESQL_DATA_DIR/root.crt
    90  cp localhost.key $POSTGRESQL_DATA_DIR/server.key
    91  chmod 600 $POSTGRESQL_DATA_DIR/server.key
    92  cp localhost.crt $POSTGRESQL_DATA_DIR/server.crt
    93  
    94  cd ..
    95  ```
    96  
    97  
    98  Start the new cluster. This will be necessary whenever you are running pgx tests.
    99  
   100  ```
   101  postgres -D .testdb/$POSTGRESQL_DATA_DIR
   102  ```
   103  
   104  Setup the test database in the new cluster.
   105  
   106  ```
   107  createdb
   108  psql --no-psqlrc -f testsetup/postgresql_setup.sql
   109  ```
   110  
   111  ### PgBouncer
   112  
   113  There are tests specific for PgBouncer that will be executed if `PGX_TEST_PGBOUNCER_CONN_STRING` is set.
   114  
   115  ### Optional Tests
   116  
   117  pgx supports multiple connection types and means of authentication. These tests are optional. They will only run if the
   118  appropriate environment variables are set. In addition, there may be tests specific to particular PostgreSQL versions,
   119  non-PostgreSQL servers (e.g. CockroachDB), or connection poolers (e.g. PgBouncer). `go test ./... -v | grep SKIP` to see
   120  if any tests are being skipped.