pgproxy

README

Copyrights

• Copyright (c) 2023 Encore (www.encore.dev) - pgproxy.go
• Copyright (c) 2019-2021 Jack Christensen - scram.go

pgproxy

pgproxy is a flexible proxy for the Postgres wire protocol that allows for customizing authentication and backend selection by breaking apart the startup message flow between frontend and backend.

Once authenticated, it falls back to being a dumb proxy that simple shuffles bytes back and forth.

Documentation

Index

• func AuthenticateClient(be *pgproto3.Backend) error
• func CopySteadyState(client *pgproto3.Backend, server *pgproto3.Frontend) error
• func FinalizeInitialHandshake(client *pgproto3.Backend, server *pgproto3.Frontend) (*pgproto3.BackendKeyData, error)
• func SendCancelRequest(conn io.ReadWriter, req *pgproto3.CancelRequest) error
• func SetupServer(server net.Conn, cfg *ServerConfig) (*pgproto3.Frontend, error)
• type AuthData
• type CancelData
• type Client
  • func SetupClient(client net.Conn, cfg *ClientConfig) (*Client, error)
• type ClientConfig
• type DatabaseNotFoundError
  • func (e DatabaseNotFoundError) Error() string
• type HelloData
• type LogicalConn
• type ServerConfig
• type SingleBackendProxy
  • func (p *SingleBackendProxy) ProxyConn(ctx context.Context, client net.Conn)
  • func (p *SingleBackendProxy) Serve(ctx context.Context, ln net.Listener) error
• type StartupData

Functions

func AuthenticateClient

func AuthenticateClient(be *pgproto3.Backend) error

AuthenticateClient tells the client they've successfully authenticated.

func CopySteadyState

func CopySteadyState(client *pgproto3.Backend, server *pgproto3.Frontend) error

CopySteadyState copies messages back and forth after the initial handshake.

func FinalizeInitialHandshake

func FinalizeInitialHandshake(client *pgproto3.Backend, server *pgproto3.Frontend) (*pgproto3.BackendKeyData, error)

FinalizeInitialHandshake completes the handshake between client and server, snooping the BackendKeyData from the server if sent. It is nil if the server did not send any backend key data.

func SendCancelRequest

func SendCancelRequest(conn io.ReadWriter, req *pgproto3.CancelRequest) error

func SetupServer

func SetupServer(server net.Conn, cfg *ServerConfig) (*pgproto3.Frontend, error)

SetupServer sets up a frontend connected to the given server.

Types

type AuthData

type AuthData struct {
	Username string
	Password string
}

type CancelData

type CancelData struct {
	Raw *pgproto3.CancelRequest
}

type Client

type Client struct {
	Backend *pgproto3.Backend
	Hello   HelloData
}

func SetupClient

func SetupClient(client net.Conn, cfg *ClientConfig) (*Client, error)

SetupClient sets up a backend connected to the given client. If tlsConfig is non-nil it negotiates TLS if requested by the client.

On successful startup the returned message is either *pgproto3.StartupMessage or *pgproto3.CancelRequest.

It is up to the caller to authenticate the client using AuthenticateClient.

type ClientConfig

type ClientConfig struct {
	// TLS, if non-nil, indicates we support TLS connections.
	TLS *tls.Config

	// WantPassword, if true, indicates we want to capture
	// the password sent by the frontend.
	WantPassword bool

	// Password, if not empty, sets the password override for the connection
	PasswordOverride string
}

type DatabaseNotFoundError

type DatabaseNotFoundError struct {
	Database string
}

func (DatabaseNotFoundError) Error

func (e DatabaseNotFoundError) Error() string

type HelloData

type HelloData interface {
	// contains filtered or unexported methods
}

type LogicalConn

type LogicalConn interface {
	net.Conn
	Cancel(*CancelData) error
}

type ServerConfig

type ServerConfig struct {
	TLS     *tls.Config // nil indicates no TLS
	Startup *StartupData
}

type SingleBackendProxy

type SingleBackendProxy struct {
	Log              zerolog.Logger
	RequirePassword  bool
	FrontendTLS      *tls.Config
	BackendTLS       *tls.Config
	DialBackend      func(context.Context, *StartupData) (LogicalConn, error)
	PasswordOverride string
	// contains filtered or unexported fields
}

func (*SingleBackendProxy) ProxyConn

func (p *SingleBackendProxy) ProxyConn(ctx context.Context, client net.Conn)

func (*SingleBackendProxy) Serve

func (p *SingleBackendProxy) Serve(ctx context.Context, ln net.Listener) error

type StartupData

type StartupData struct {
	Raw      *pgproto3.StartupMessage
	Database string
	Username string
	Password string // may be empty if RequirePassword is false
}