README
¶
pgxstdlib
A PostgreSQL database/sql driver that works under TinyGo as well as standard
Go, so application code is shared between compilers.
import "github.com/shibukawa/tinygodriver/database/sql/pgxstdlib"
db, err := pgxstdlib.Open("postgres://user:pass@localhost:5432/db?sslmode=verify-full")
Both builds are pgx's stdlib driver:
| Build | Backend |
|---|---|
| Standard Go | upstream pgx, unmodified |
TinyGo or -tags force_tinygo_logic |
vendored pgx with TLS rerouted |
TinyGo ships crypto/tls as a stub that cannot be linked, so the vendored copy
routes TLS through the https package instead. That is three patched files out
of 145; see internal/PATCHES.md.
TLS
sslmode works on both builds, including verify-full with a custom
sslrootcert. On TinyGo the handshake runs on the already-connected socket
after PostgreSQL's SSLRequest, using the platform's native TLS stack.
| Platform | Upgrade backend | Max version |
|---|---|---|
| Standard Go | crypto/tls |
TLS 1.3 |
| macOS | Secure Transport | TLS 1.2 |
macOS with -tags darwinstarttlswith13 |
mbedTLS | TLS 1.3 |
| Linux | mbedTLS | TLS 1.3 |
Two differences from libpq are deliberate:
verify-cais treated asverify-full. libpq skips the host name check there; the native backends cannot express that, and checking the name too is stricter, never weaker.sslcertandsslkeyare rejected rather than ignored, because the native backends cannot offer a client certificate.
A platform with no TLS backend refuses any mode but disable, and never falls
back to plaintext silently.
TinyGo notes
Build with -scheduler=threads. Under the cooperative scheduler a blocking
socket call holds the whole runtime, so background goroutines never run and
query cancellation stops working without any error.
Blank-import netdev, as with any TinyGo program that uses the network:
import _ "github.com/shibukawa/tinygodriver/netdev"
Unix domain sockets and IPv6 are unavailable there, so connect over TCP to an IPv4 host.
Cancellation
context cancellation is wired to PostgreSQL's CancelRequest, which opens a
second connection to ask the server to stop. pgx's default instead moves the
deadline on the in-flight connection, which does nothing under TinyGo: netdev
reads the deadline once when a read begins, so a later change cannot interrupt
it and the query runs to completion with no error. This package installs the
CancelRequest handler on both builds so behavior does not differ by compiler.
Reaching pgx directly
Batch, CopyFrom and LISTEN/NOTIFY have no database/sql equivalent.
They stay reachable on both compilers:
conn, err := db.Conn(ctx)
err = conn.Raw(func(dc any) error {
pgxConn := dc.(*stdlib.Conn).Conn()
_, err := pgxConn.CopyFrom(ctx, ...)
return err
})
Updating the vendored pgx
go mod download github.com/jackc/pgx/v5@vX.Y.Z # after bumping PGX_VERSION
python3 internal/vendor.py && python3 internal/patch.py
patch.py anchors every edit on an exact upstream string and fails loudly if
one is gone, so a version bump reports what needs attention instead of quietly
producing a tree that still links crypto/tls.
Tests
The integration tests skip unless a server is configured:
docker run -d --name pgtest -e POSTGRES_PASSWORD=pass -e POSTGRES_USER=user \
-e POSTGRES_DB=db -p 55432:5432 postgres:17
PGXSTDLIB_TEST_DSN='postgres://user:pass@localhost:55432/db?sslmode=disable' \
go test ./database/sql/pgxstdlib/
Add -tags force_tinygo_logic to run the same suite against the vendored
backend without a TinyGo toolchain. The TLS tests need a server with ssl=on;
tls_test.go documents the setup.
Documentation
¶
Overview ¶
Package pgxstdlib provides a PostgreSQL database/sql driver that works under both TinyGo and standard Go.
Both builds are pgx/stdlib. Standard Go uses upstream pgx unmodified; TinyGo uses a vendored copy with TLS removed, because TinyGo ships crypto/tls as a stub that cannot be linked. See internal/PATCHES.md.
db, err := pgxstdlib.Open("postgres://user:pass@localhost:5432/db?sslmode=disable")
if err != nil { ... }
defer db.Close()
var n int
err = db.QueryRowContext(ctx, "SELECT 1").Scan(&n)
Everything database/sql offers works on both compilers: parameters, prepared statements, transactions, column metadata, and context cancellation.
Reaching pgx directly ¶
Batch, CopyFrom and LISTEN/NOTIFY have no database/sql equivalent. They stay reachable through the standard escape hatch, on both compilers:
conn, err := db.Conn(ctx)
err = conn.Raw(func(dc any) error {
pgxConn := dc.(*stdlib.Conn).Conn()
_, err := pgxConn.CopyFrom(ctx, ...)
return err
})
TinyGo notes ¶
Build with -scheduler=threads. Under the cooperative scheduler a blocking socket call holds the whole runtime, so background goroutines never run and query cancellation silently stops working.
Import netdev for its side effect, as with any TinyGo program using the network:
import _ "github.com/shibukawa/tinygodriver/netdev"
Unix domain sockets and IPv6 are unavailable there, so connect over TCP to an IPv4 host. TLS support depends on the platform; see Open.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Open ¶
Open opens a database handle for a libpq-style URL or keyword DSN.
The handle is lazy in the usual database/sql way: no connection is made until the first use. Call db.PingContext to verify the settings eagerly.
sslmode is honored on both builds. On TinyGo it is served by the platform's native TLS stack, which starts TLS on the already-connected socket after PostgreSQL's SSLRequest, so verify-full and a custom sslrootcert both work. Two differences from libpq are deliberate:
- verify-ca is treated as verify-full. libpq would skip the host name check; the native backends cannot express that, and checking the name as well is stricter, never weaker.
- sslcert and sslkey are rejected rather than ignored, because the native backends cannot offer a client certificate.
A platform with no TLS backend refuses any mode but disable. It never falls back to plaintext silently.
Types ¶
This section is empty.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
pgx
Package pgx is a PostgreSQL database driver.
|
Package pgx is a PostgreSQL database driver. |
|
pgx/internal/iobufpool
Package iobufpool implements a global segregated-fit pool of buffers for IO.
|
Package iobufpool implements a global segregated-fit pool of buffers for IO. |
|
pgx/internal/pgio
Package pgio is a low-level toolkit building messages in the PostgreSQL wire protocol.
|
Package pgio is a low-level toolkit building messages in the PostgreSQL wire protocol. |
|
pgx/internal/stmtcache
Package stmtcache is a cache for statement descriptions.
|
Package stmtcache is a cache for statement descriptions. |
|
pgx/pgconn
Package pgconn is a low-level PostgreSQL database driver.
|
Package pgconn is a low-level PostgreSQL database driver. |
|
pgx/pgconn/internal/bgreader
Package bgreader provides a io.Reader that can optionally buffer reads in the background.
|
Package bgreader provides a io.Reader that can optionally buffer reads in the background. |
|
pgx/pgproto3
Package pgproto3 is an encoder and decoder of the PostgreSQL wire protocol version 3.
|
Package pgproto3 is an encoder and decoder of the PostgreSQL wire protocol version 3. |
|
pgx/pgtype
Package pgtype converts between Go and PostgreSQL values.
|
Package pgtype converts between Go and PostgreSQL values. |
|
pgx/pgxpool
Package pgxpool is a concurrency-safe connection pool for pgx.
|
Package pgxpool is a concurrency-safe connection pool for pgx. |
|
pgx/stdlib
Package stdlib is the compatibility layer from pgx to database/sql.
|
Package stdlib is the compatibility layer from pgx to database/sql. |