database

Documentation

Overview

Package database provides adapters for database template cloning. Supported adapters: PostgreSQL (server-side createdb --template) and SQLite (file copy). The adapter interface abstracts clone, drop, and existence checks across database types.

Index

• func LockTemplate(template string) (func(), error)
• type Adapter
  • func ForAdapter(name string, connArgs []string) (Adapter, error)
• type ExecError
  • func (e *ExecError) Error() string
  • func (e *ExecError) Unwrap() error
• type Extensions
• type PostgreSQL
  • func (pg *PostgreSQL) Clone(template, target string) error
  • func (pg *PostgreSQL) Create(name string) error
  • func (pg *PostgreSQL) Drop(target string) error
  • func (pg *PostgreSQL) Exists(name string) (bool, error)
  • func (pg *PostgreSQL) ListDatabases() ([]string, error)
  • func (pg *PostgreSQL) Rename(oldName, newName string) error
  • func (pg *PostgreSQL) Restore(target, dumpFile string) error
• type Puller
  • func NewPuller(localConnArgs []string) *Puller
  • func (p *Puller) Dump(remote *RemoteConn, dumpPath string) error
  • func (p *Puller) Refresh(target, dumpPath, listPath string, exts Extensions) error
• type RemoteConn
• type SQLite
  • func (s *SQLite) Clone(template, target string) error
  • func (s *SQLite) Create(name string) error
  • func (s *SQLite) Drop(target string) error
  • func (s *SQLite) Exists(name string) (bool, error)
  • func (s *SQLite) Rename(oldPath, newPath string) error
  • func (s *SQLite) Restore(target, dumpFile string) error

Functions

func LockTemplate

func LockTemplate(template string) (func(), error)

LockTemplate acquires an exclusive, cross-process advisory lock keyed on the template name and returns a release function. The lock file lives under the gtl config dir so every gtl invocation on the host agrees on the same path. Exported so setup's template auto-provisioning serializes against concurrent clones of the same template. Callers must validate template as an identifier first (dbIdentifierRe), so it is safe as a filename component (no path separators or traversal).

Types

type Adapter

type Adapter interface {
	Clone(template, target string) error
	Create(name string) error
	Drop(target string) error
	Exists(name string) (bool, error)
	Rename(oldName, newName string) error
	Restore(target, dumpFile string) error
}

Adapter defines the interface for database template cloning and cleanup. Implementations handle database-specific operations:

• Clone creates a new database from a template
• Create creates an empty database with no template
• Drop removes a database
• Exists checks if a database already exists
• Rename renames an existing database in place
• Restore loads a dump file into a database

func ForAdapter

func ForAdapter(name string, connArgs []string) (Adapter, error)

ForAdapter returns the adapter for the given name. Defaults to PostgreSQL for empty string (backward compatibility). connArgs are connection flags (e.g. ["-h", "localhost"]) prepended to every pg tool invocation; pass nil when no explicit connection is needed.

type ExecError

type ExecError struct {
	Stage  string // "dump", "drop", "create", "extension", "list", "restore"
	Output string // captured combined stderr (best effort)
	Err    error
}

ExecError carries the stage and captured stderr of a failed pg tool call so the cmd layer can classify it into a user-facing hint.

func (*ExecError) Error

func (e *ExecError) Error() string

func (*ExecError) Unwrap

func (e *ExecError) Unwrap() error

type Extensions

type Extensions struct {
	Require []string
	Strip   []string
}

Extensions captures the extension handling for a restore: Require names are pre-created (CREATE EXTENSION IF NOT EXISTS), Strip names are commented out of the restore TOC (for cloud-only extensions absent locally).

type PostgreSQL

type PostgreSQL struct {
	// ConnArgs are prepended to every pg tool invocation (e.g. ["-h", "localhost", "-p", "5432"]).
	// Setting -h forces TCP instead of Unix socket, which avoids Postgres.app's
	// socket authorization dialog when gtl is invoked from a native macOS app.
	ConnArgs []string
	// contains filtered or unexported fields
}

PostgreSQL implements the Adapter interface for PostgreSQL databases. Clone uses createdb --template, Drop uses dropdb --if-exists.

func (*PostgreSQL) Clone

func (pg *PostgreSQL) Clone(template, target string) error

func (*PostgreSQL) Create

func (pg *PostgreSQL) Create(name string) error

Create creates an empty database with no template — the degraded fallback when the configured template can't be cloned. Not serialized by LockTemplate: createdb without --template needs no session exclusivity.

func (*PostgreSQL) Drop

func (pg *PostgreSQL) Drop(target string) error

func (*PostgreSQL) Exists

func (pg *PostgreSQL) Exists(name string) (bool, error)

func (*PostgreSQL) ListDatabases

func (pg *PostgreSQL) ListDatabases() ([]string, error)

ListDatabases returns the names of all databases on the server. Used to find framework-derived parallel-test shards of auxiliary databases.

func (*PostgreSQL) Rename

func (pg *PostgreSQL) Rename(oldName, newName string) error

func (*PostgreSQL) Restore

func (pg *PostgreSQL) Restore(target, dumpFile string) error

type Puller

type Puller struct {
	// LocalConnArgs are prepended to local pg tool calls (same as PostgreSQL.ConnArgs).
	LocalConnArgs []string
	// Logf, when set, receives a redacted line for each exec (for --debug).
	Logf func(format string, a ...any)
	// Out receives the pg tools' stdout; nil means os.Stdout. Callers whose
	// stdout is a protocol or capture stream (MCP stdio, `gtl claim`) set it
	// to keep tool chatter out of that stream.
	Out io.Writer
	// contains filtered or unexported fields
}

Puller runs the remote-pull / refresh pipeline against a LOCAL target db. It reuses the same exec-seam pattern as PostgreSQL but adds an env-aware variant so PGPASSWORD/PGSSLMODE can be passed to the remote pg_dump via the process environment — never on argv.

func NewPuller

func NewPuller(localConnArgs []string) *Puller

NewPuller returns a Puller wired to real exec, prepending localConnArgs to local pg tool calls.

func (*Puller) Dump

func (p *Puller) Dump(remote *RemoteConn, dumpPath string) error

Dump writes a custom-format dump of the remote database to dumpPath. The remote password and sslmode travel via the environment, so they never appear in argv. The dump file must exist and be non-empty before any caller drops the local db.

func (*Puller) Refresh

func (p *Puller) Refresh(target, dumpPath, listPath string, exts Extensions) error

Refresh drops and recreates the local target, pre-creates required extensions, builds a stripped restore list when needed, and restores the dump. It performs no network access — pull calls Dump first, refresh reuses an already-retained dump. listPath is where a stripped TOC may be written.

type RemoteConn

type RemoteConn struct {
	Host     string
	Port     string
	User     string
	Password string
	DBName   string
	SSLMode  string
}

RemoteConn is a resolved remote PostgreSQL connection. It mirrors dbsource.ConnInfo; the cmd layer maps between them so this package stays a leaf (no dbsource import).

type SQLite

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

func (*SQLite) Clone

func (s *SQLite) Clone(template, target string) error

func (*SQLite) Create

func (s *SQLite) Create(name string) error

Create creates an empty database file — the degraded fallback when the configured template file is missing.

func (*SQLite) Drop

func (s *SQLite) Drop(target string) error

func (*SQLite) Exists

func (s *SQLite) Exists(name string) (bool, error)

func (*SQLite) Rename

func (s *SQLite) Rename(oldPath, newPath string) error

func (*SQLite) Restore

func (s *SQLite) Restore(target, dumpFile string) error