README.md (2252B)
1 [](https://godoc.org/github.com/jackc/pgconn) 2  3 4 --- 5 6 This version is used with pgx `v4`. In pgx `v5` it is part of the https://github.com/jackc/pgx repository. 7 8 --- 9 10 # pgconn 11 12 Package pgconn is a low-level PostgreSQL database driver. It operates at nearly the same level as the C library libpq. 13 It is primarily intended to serve as the foundation for higher level libraries such as https://github.com/jackc/pgx. 14 Applications should handle normal queries with a higher level library and only use pgconn directly when required for 15 low-level access to PostgreSQL functionality. 16 17 ## Example Usage 18 19 ```go 20 pgConn, err := pgconn.Connect(context.Background(), os.Getenv("DATABASE_URL")) 21 if err != nil { 22 log.Fatalln("pgconn failed to connect:", err) 23 } 24 defer pgConn.Close(context.Background()) 25 26 result := pgConn.ExecParams(context.Background(), "SELECT email FROM users WHERE id=$1", [][]byte{[]byte("123")}, nil, nil, nil) 27 for result.NextRow() { 28 fmt.Println("User 123 has email:", string(result.Values()[0])) 29 } 30 _, err = result.Close() 31 if err != nil { 32 log.Fatalln("failed reading result:", err) 33 } 34 ``` 35 36 ## Testing 37 38 The pgconn tests require a PostgreSQL database. It will connect to the database specified in the `PGX_TEST_CONN_STRING` 39 environment variable. The `PGX_TEST_CONN_STRING` environment variable can be a URL or DSN. In addition, the standard `PG*` 40 environment variables will be respected. Consider using [direnv](https://github.com/direnv/direnv) to simplify 41 environment variable handling. 42 43 ### Example Test Environment 44 45 Connect to your PostgreSQL server and run: 46 47 ``` 48 create database pgx_test; 49 ``` 50 51 Now you can run the tests: 52 53 ```bash 54 PGX_TEST_CONN_STRING="host=/var/run/postgresql dbname=pgx_test" go test ./... 55 ``` 56 57 ### Connection and Authentication Tests 58 59 Pgconn supports multiple connection types and means of authentication. These tests are optional. They 60 will only run if the appropriate environment variable is set. Run `go test -v | grep SKIP` to see if any tests are being 61 skipped. Most developers will not need to enable these tests. See `ci/setup_test.bash` for an example set up if you need change 62 authentication code.