proxy

package
v1.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 22, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

README

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'.

Documentation

Overview

Package proxy contains shared lifecycle and observation types for database wire proxies.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Relay

func Relay(client, server net.Conn, frontend, backend io.Writer) error

Relay observes bytes before forwarding them, so a fast reply cannot precede its request.

Types

type Handler

type Handler func(context.Context, *Server, net.Conn) error

Handler serves an accepted connection. Dial must be used for tracked upstream connections.

type Options

type Options struct {
	Upstream      string
	Listen        string
	Params        bool
	ClientTLSMode string
	ClientTLS     *tls.Config
	UpstreamTLS   *tls.Config
	// UpstreamCertificate is a .pem or .der file with the exact certificate the
	// upstream must present. It replaces chain and hostname verification for
	// self-signed servers and cannot be combined with UpstreamTLS.
	UpstreamCertificate string
	// CaptureDir receives one file of decrypted wire messages per connection.
	CaptureDir  string
	OnStatement func(Statement) error
}

Options are copied at startup. Callbacks are serialized and must not call Close. Nil UpstreamTLS selects plaintext; non-nil requires verified TLS without fallback.

type Server

type Server struct {
	Options Options
	// contains filtered or unexported fields
}

func Start

func Start(ctx context.Context, opts Options, handler Handler) (*Server, error)

func (*Server) Addr

func (s *Server) Addr() string

func (*Server) Close

func (s *Server) Close() error

func (*Server) Dial

func (s *Server) Dial(ctx context.Context) (net.Conn, error)

func (*Server) Emit

func (s *Server) Emit(row Statement)

func (*Server) Release

func (s *Server) Release(conn net.Conn)

Release closes and removes a connection created with Dial.

func (*Server) Wait

func (s *Server) Wait() error

type Statement

type Statement struct {
	Connection string        `json:"connection"`
	Driver     string        `json:"driver"`
	SQL        string        `json:"sql,omitempty"`
	RPC        string        `json:"rpc,omitempty"`
	Args       []any         `json:"args,omitempty"`
	StartedAt  time.Time     `json:"startedAt"`
	Duration   time.Duration `json:"duration"`
	Rows       int64         `json:"rows"`
	Error      string        `json:"error,omitempty"`
	Incomplete bool          `json:"incomplete,omitempty"`
}

Directories

Path Synopsis
internal
testcert
Package testcert creates ephemeral certificates for transport tests.
Package testcert creates ephemeral certificates for transport tests.
Package postgres provides an observing PostgreSQL wire proxy, derived from flanksource/telltale pkg/tracing/pgproxy (507c01f9be71).
Package postgres provides an observing PostgreSQL wire proxy, derived from flanksource/telltale pkg/tracing/pgproxy (507c01f9be71).
Package tds provides an observing TDS 7.4 proxy for SQL Server SQL authentication.
Package tds provides an observing TDS 7.4 proxy for SQL Server SQL authentication.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL