pg

Documentation

Overview

Package pg is the external boundary over the pg_dump / pg_restore / psql command-line tools. It implements dump.PGTool so the orchestrator depends on the narrow interface it defines, not on os/exec directly. Every invocation builds an explicit []string argv (never a shell string) and runs under a context whose deadline is enforced here, so "every external call is bounded" holds at the boundary rather than by convention.

The argv construction and exit-code handling follow patterns proven in orgrim/pg_back (BSD-2-Clause); see CREDITS. The connect-vs-auth probe (dial-then-psql) is original to this project.

Index

• Variables
• func BinariesPresent() error
• type Tool
  • func New(pgPassFile string, stmtTimeout time.Duration) *Tool
  • func (t *Tool) Dump(ctx context.Context, c dump.Conn, w io.Writer) (exitCode int, stderrTail string, err error)
  • func (t *Tool) Probe(ctx context.Context, c dump.Conn) (int, dump.FailKind, error)
  • func (t *Tool) VerifyTOC(ctx context.Context, path string) error

Variables

var ErrNoDeadline = errors.New("pg: context has no deadline")

ErrNoDeadline is returned by every boundary method when handed a context without a deadline, enforcing Property 3 (every external call is bounded) at the boundary instead of trusting callers.

Functions

func BinariesPresent

func BinariesPresent() error

BinariesPresent reports whether pg_dump, pg_restore, and psql resolve on PATH. The health probe calls it; a missing binary is an image/build error.

Types

type Tool

type Tool struct {
	// contains filtered or unexported fields
}

Tool runs the PostgreSQL client binaries as a network client. Credentials flow only through the child environment (PGPASSFILE), never argv.

func New

func New(pgPassFile string, stmtTimeout time.Duration) *Tool

New builds a Tool. pgPassFile is exported into each child as PGPASSFILE; stmtTimeout becomes the server-side statement_timeout (via PGOPTIONS).

func (*Tool) Dump

func (t *Tool) Dump(ctx context.Context, c dump.Conn, w io.Writer) (exitCode int, stderrTail string, err error)

Dump streams a network custom-format pg_dump for c into w. pg_dump is a local child process, so ctx cancellation (cmd.Cancel via CommandContext) kills it directly and Postgres tears down the server backend when the client TCP connection drops. Returns the process exit code and a bounded stderr tail.

func (*Tool) Probe

func (t *Tool) Probe(ctx context.Context, c dump.Conn) (int, dump.FailKind, error)

Probe classifies one database before a dump is attempted. It separates connect from auth without matching stderr: a TCP dial that fails is a definitive connect_error; if the dial succeeds but the authenticated psql round-trip fails, the server is reachable so the fault is auth/database (auth_error). On success it reads server_version_num and reports version_mismatch when the shipped client major is older than the server.

func (*Tool) VerifyTOC

func (t *Tool) VerifyTOC(ctx context.Context, path string) error

VerifyTOC runs a local `pg_restore --list` against the custom-format file at path: no network, no daemon. A readable table-of-contents proves the file is structurally intact (not truncated mid-stream). Returns nil iff readable.