Database wire proxies
Gavel behavioral fixtures
The SQL Server service looks up connection://lab in commons-db's shared, sqlglot-go, and fixture working-directory connection layers. When that record exists it is reused, including its credentials; an unreachable or invalid saved connection fails the test. When absent, Gavel provisions SQL Server through the selected Docker context (DOCKER_CONTEXT=moshe-home). Both paths export FIXTURE_DSN and the same endpoint outputs. Borrowed servers are never stopped by fixture cleanup. Remove the service's connection setting to always provision. This requires a Gavel build with native service connection lookup support.
Run GOWORK=off gavel fixtures proxy/testdata/cli.fixture.md for CLI validation without databases. Run DOCKER_CONTEXT=moshe-home GOWORK=off gavel fixtures --max-concurrent 1 'proxy/testdata/*.fixture.yaml' for database behavior, or select postgres.fixture.yaml or sqlserver.fixture.yaml individually. Each fixture builds the CLI and its test client. PostgreSQL uses the native commons-db dbtest service; SQL Server uses an isolated SQL Server 2022 container through Gavel's mssql service. Use a Gavel build supporting inferred exec steps and remote Docker service endpoints. No production database URLs or fixed ports are used. Gavel owns reverse-order process and database cleanup.
CEL checks compare direct and proxied results, captured SQL and row counts, parameter opt-in, server errors, Unicode packet fragmentation, certificate-verified client TLS, plaintext rejection, invalid CLI settings, and interrupt shutdown. Each database service exports FIXTURE_DSN for subsequent queries and active-query services. Captures and ephemeral certificates live in the fixture's managed temporary directory. The suite clears ambient PostgreSQL URL overrides and uses COMMONS_DB_CREATE=true to acquire a scratch lease. Set DOCKER_CONTEXT in the Gavel process environment, since the container runtime runs in-process.
The aggregate definition of done is gavel fixtures proxy/testdata/verification.md; use the same Docker context when running it. Missing database or Docker prerequisites fail explicitly.
proxy/postgres and proxy/tds forward traffic to one upstream and observe queries without rewriting application SQL. The PostgreSQL implementation is derived from telltale's pkg/tracing/pgproxy at 507c01f9be71. TDS framing and RPC layouts are derived from Mori at 7e7223c1a5a3164d7145a608e5220d6991d53426; its MIT license is included in tds/LICENSE.mori.
CLI
Build with make build. Start either proxy, then point your application's database connection at the reported listener address:
.tmp/sqlglot proxy postgres --upstream localhost:5432 --listen 127.0.0.1:15432 --json
.tmp/sqlglot proxy tds --upstream localhost:1433 --listen 127.0.0.1:11433 --json
The default listener is 127.0.0.1:0, so the OS selects a free port. Readiness and connection diagnostics go to stderr; statements stream to stdout. --json emits one JSON record per line. --params includes bind values; by default arguments are omitted. Queries themselves retain SQL literals. Interrupt stops the listener and active connections. Commands are local-only and excluded from generated HTTP routes.
Upstream addresses are host:port, without credentials. The original client's authentication is forwarded. Both legs default to plaintext. Configure TLS independently:
.tmp/sqlglot proxy postgres --upstream db.example:5432 --client-tls allow --tls-cert proxy.pem --tls-key proxy-key.pem --upstream-tls require --upstream-ca upstream-ca.pem
.tmp/sqlglot proxy tds --upstream db.example:1433 --upstream-tls require --upstream-ca upstream-ca.pem --upstream-server-name db.example
--client-tls accepts disable, allow (TLS and plaintext clients), or require. Enabled modes require both --tls-cert and --tls-key PEM files. --upstream-tls require verifies upstream certificates against system roots or --upstream-ca; --upstream-server-name overrides the certificate hostname. For a self-signed server that no CA or hostname can verify, such as SQL Server's fallback certificate, --upstream-cert accepts only the exact certificate in a .pem or .der file. TLS uses version 1.2 or later and never retries in plaintext after a TLS failure. Supplied certificate files must already exist; the proxy does not generate production certificates.
Wire capture
proxy tds --capture <dir> also writes every TDS message to <dir>, one 0600 YAML file per connection. Messages are recorded after TLS termination with their original packet boundaries.
.tmp/sqlglot proxy tds --upstream db.example:1433 --upstream-tls require --upstream-ca upstream-ca.pem --capture .tmp/captures
LOGIN7 is rebuilt with placeholders, so credentials, host and application names are never written, not even their lengths. Server and database names are replaced in the login response and wherever later tokens length-prefix them. Everything else after login is recorded as sent: SQL text, parameter values, result rows and error text. Treat captures as sensitive. A connection that uses SSPI, routing or a password change, or whose login response cannot be scrubbed, is closed instead of recorded.
proxy/tds/testdata/captures holds SQL Server traffic recorded this way. GOWORK=off make tds-fixtures TDS_CONNECTION=connection://example TDS_UPSTREAM=db.example:1433 regenerates it. The fixture client trusts the certificate the server presents on that run, creates and drops its own database, runs each scenario through the proxy, and refuses to publish files that contain the password, host, server, machine or database name.
Go API
server, err := postgres.Start(ctx, proxy.Options{
Upstream: "localhost:5432",
OnStatement: func(statement proxy.Statement) error {
return json.NewEncoder(output).Encode(statement)
},
})
if err != nil {
return err
}
defer server.Close()
return server.Wait()
Import github.com/flanksource/sqlglot-go/proxy and either protocol subpackage. Start binds before returning; Addr reports the actual listener. Cancel the supplied context or call Close to stop. Wait reports fatal listener or callback errors. Callbacks are serialized, apply backpressure, and must not call Close or Wait. There is no retained capture database or event-drop queue.
Set ClientTLSMode and ClientTLS for incoming TLS. A non-nil UpstreamTLS requires verified upstream TLS; nil means plaintext. UpstreamCertificate names the exact certificate to accept instead. CaptureDir enables TDS wire capture. TLS configurations are cloned before use. Protocol errors are emitted as incomplete observations and close the affected connection. Callback errors stop the proxy.
Compatibility and capture limits
PostgreSQL supports password and SCRAM authentication with channel_binding=disable, simple and extended queries, pipelining, COPY, and cancellation. TDS supports version 7.4 SQL authentication without MARS; TDS 8, Windows/federated authentication, and channel-bound authentication are rejected. TDS captures SQL batches and RPC calls, including sp_executesql, prepare/execute/unprepare handles, nullable integers, floats, booleans, decimals, money, dates and times, GUIDs, strings, binary values, and PLP strings. Decimals, money, temporal values and GUIDs are reported as text. Other RPC parameter types fail explicitly.
Rows are -1 when unavailable. incomplete identifies missing completion metadata or bounded observations. TDS row counts come from the final DONE token; server failures without decoded details have a generic error. SQL parsing is not required, so unsupported SQL syntax still forwards. PostgreSQL observations above 1 MiB are reported and skipped while bytes continue forwarding; TDS messages above 1 MiB fail explicitly. Result rows and authentication messages are never included in statement output.
Run focused tests with GOWORK=off go test -race ./proxy/.... Real database tests are separate: provide disposable SQLGLOT_PROXY_POSTGRES_URL and SQLGLOT_PROXY_SQLSERVER_URL URLs and run GOWORK=off go test -tags integration ./proxy -ginkgo.focus='Disposable database integration'.