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