postgresqlmeta

package
v0.511.0 Latest Latest
Warning

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

 Go to latest Published: Sep 7, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

README

PostgreSQL Metadata Provider Module

PostgreSQL metadata provider used for optional metadata-aware DeltaScope audits against PostgreSQL.

Files

File Responsibility
open.go Formats PostgreSQL metadata connection DSNs and opens pgx stdlib database/sql handles
open_test.go Verifies TCP and unix-socket DSN/address formatting helpers
provider.go Loads normalized dialect, schema, instance-fact, table snapshot, and plain-EXPLAIN plan-estimate data from PostgreSQL catalogs and planner stats
provider_test.go Verifies catalog-backed schema discovery, reltuples/statistics loading, PK constraint truth, and plain-EXPLAIN estimation without a live database
resolve_object.go Resolves non-table database object metadata from PostgreSQL catalogs with schema-qualified ambiguity detection and privacy-safe attribute projection
resolve_object_test.go Verifies object resolver behavior for all supported lookup types, statuses, sensitive attribute exclusion, and annotation target verification
query_access_conn_resolver.go Thin caller-owned *sql.Conn-backed SchemaResolver adapter for same-session metadata resolution; no pool fallback
query_access_resolver_core.go Private stateless PostgreSQL catalog core behind the conn adapter: relation/column SQL, scanning, lookup errors, relkind mapping, and foreign-table fail-closed policy
query_access_resolver_test.go Conn-only behavior contract (relation kinds, errors, query order, foreign-table fail-closed) plus lifecycle and concrete-field coverage
query_access_conn_resolver_stub.go Empty QueryAccessConnResolver struct for non-postgresql builds
query_access_conn_resolver_test.go Adapter-specific conn lifecycle and concrete-field tests
query_access_conn_resolver_integration_test.go PG17 Docker integration: same-backend-PID proof
effect_identity_session.go Session-pinned *sql.Conn wrapper; live resolution context capture (db/role/version/backend/search_path OIDs)
effect_identity_resolver.go Facts-only EffectIdentityResolver adapter (operator/function/cast exact catalog lookup + dedicated COUNT(integer_one) catalog proof + TOCTOU gate)
effect_identity_resolver_test.go Unit tests with fake pinned catalog (no live PG claim)
effect_identity_resolver_integration_test.go Optional PG17 Docker integration (-tags postgresql,integration)

Exports

  • DefaultConnectTimeout
  • ConnectionConfig
  • OpenDBContext(ctx, config)
  • OpenDB(config)
  • Provider
  • NewProvider(db *sql.DB)
  • Provider.DetectDialect(ctx)
  • Provider.FindSchemasForTable(ctx, table)
  • Provider.LoadPlanEstimate(ctx, statement)
  • Provider.ResolveObject(ctx, dialect, request)
  • PinnedSession / NewPinnedSessionFromConn / PinSession / ErrSessionNotPinned
  • EffectIdentityAdapter / NewEffectIdentityAdapter (facts only; implements ControlledEffectIdentityResolver)
  • QueryAccessConnResolver / NewQueryAccessConnResolver (conn-backed SchemaResolver; no *sql.DB field)
  • QueryAccessConnResolver.ResolveRelation(ctx, dialect, schema, name)

Effect identity (T7)

  • Requires a single pinned session (*sql.Conn via PinnedSession). Do not run identity lookups on a multi-connection *sql.DB pool.
  • Implements ControlledEffectIdentityResolver: CaptureExecutionBoundContext returns the pinned session's live resolution context so the application can set explicit Resolution on the request.
  • Flow: application captures context → sets on request → capture live context → exact catalog lookup → re-capture live → GateIdentityBatchAgainstLiveContext.
  • Returns catalog facts only (OIDs, volatility, cast method, stamped database/server). Never Trusted, admission, or free-text errors on public Result JSON.
  • Unqualified names walk ordered NamespaceSearchOIDs; never invent pg_catalog.<name> without path/context.
  • Explicit schema skips search_path ranking only; still requires full session/db/role/server binding via gates.
  • Arity-0 functions (e.g. count(*)) bypass hasUnresolvedTypeKind star check — no type OIDs needed.
  • Exact COUNT(1) uses a dedicated session-bound pg_proc/pg_type catalog lookup for the count(any) aggregate; it never fabricates an operand OID or falls back to generic function overload resolution.
  • T8 owns version-scoped manifest proof and admission promotion. Runtime integration is validated against the repo's PostgreSQL 17 compose image; T2 research covered 14–17 for the closed manifest set, not as a multi-version CI claim for this adapter.

Dependencies

  • Upstream: internal/application/audit, internal/application/queryaccess
  • Downstream: database/sql, github.com/jackc/pgx/v5, github.com/jackc/pgx/v5/stdlib, internal/domain/spec

Update Rule

  • If members/interfaces/dependencies change, update this file in same change.

Documentation

Overview

Package postgresqlmeta implements metadata-aware audit adapters over PostgreSQL. input: connection configs for PostgreSQL metadata reads output: pgx stdlib database/sql handles for metadata providers pos: infrastructure connection opener for PostgreSQL metadata access note: if this file changes, update this header and module README.md.

Package postgresqlmeta implements metadata-aware audit adapters over PostgreSQL. input: sql.DB access plus version/schema/table lookup requests and PostgreSQL catalog queries output: normalized instance facts, dialect detection, schema discovery, table snapshots, and plan estimates for application-level audit enrichment pos: infrastructure metadata adapter between database/sql and domain metadata specs note: if this file changes, update this header and module README.md.

Package postgresqlmeta provides a stub QueryAccessConnResolver when built without the postgresql tag. input: none (stub only) output: empty struct satisfying build constraints pos: infrastructure stub for non-PostgreSQL builds note: if this file changes, update this header and module README.md.

Index

Constants

View Source 
const DefaultConnectTimeout = 5 * time.Second

DefaultConnectTimeout is the default timeout for initial metadata connection.

Variables

This section is empty.

Functions

func OpenDB 

func OpenDB(config ConnectionConfig) (*sql.DB, error)

OpenDB connects to a PostgreSQL database for metadata reads using a background context. The caller is responsible for closing the returned *sql.DB.

func OpenDBContext added in v0.62.0 

func OpenDBContext(ctx context.Context, config ConnectionConfig) (*sql.DB, error)

OpenDBContext connects to a PostgreSQL database for metadata reads, respecting the caller's context for cancellation and applying the configured connect timeout as a deadline. The caller is responsible for closing the returned *sql.DB.

Types

type ConnectionConfig 

type ConnectionConfig struct {
	Host           string
	Port           int
	Socket         string
	Database       string
	User           string
	Password       string
	SSLMode        string
	CACert         *x509.CertPool // pre-parsed CA pool; only used when sslmode requires verification
	ConnectTimeout time.Duration
}

ConnectionConfig describes one PostgreSQL metadata connection.

func (ConnectionConfig) Address 

func (c ConnectionConfig) Address() string

Address reports the driver address for the connection.

func (ConnectionConfig) DSN 

func (c ConnectionConfig) DSN() string

DSN formats the config for the pgx database/sql driver.

func (ConnectionConfig) DatabaseName 

func (c ConnectionConfig) DatabaseName() string

DatabaseName reports the configured database or the PostgreSQL default.

type Provider 

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

Provider loads metadata facts through a PostgreSQL SQL connection.

func NewProvider 

func NewProvider(db *sql.DB) *Provider

NewProvider builds a metadata provider on top of an existing SQL handle.

func (*Provider) DetectDialect 

func (p *Provider) DetectDialect(ctx context.Context) (spec.Dialect, error)

DetectDialect reads server version information and classifies the SQL dialect.

func (*Provider) FindSchemasForTable 

func (p *Provider) FindSchemasForTable(ctx context.Context, table string) ([]string, error)

FindSchemasForTable lists schemas that currently contain the named table.

func (*Provider) LoadInstanceFacts 

func (p *Provider) LoadInstanceFacts(ctx context.Context, _ spec.Dialect, _ string) (*spec.InstanceFacts, error)

LoadInstanceFacts reads server-level settings that influence audit behavior.

func (*Provider) LoadPlanEstimate 

func (p *Provider) LoadPlanEstimate(ctx context.Context, statement spec.Statement) (*spec.ImpactEstimate, error)

LoadPlanEstimate reads a conservative row estimate using plain EXPLAIN output.

func (*Provider) LoadTableSnapshot 

func (p *Provider) LoadTableSnapshot(ctx context.Context, _ spec.Dialect, schema string, table string) (*spec.TableSnapshot, error)

func (*Provider) ResolveObject added in v0.90.0 

func (p *Provider) ResolveObject(ctx context.Context, _ spec.Dialect, req spec.ObjectLookupRequest) (*spec.ObjectSnapshot, error)

ResolveObject looks up non-table database object metadata from PostgreSQL catalogs.

func (*Provider) ResolveTableForIndex 

func (p *Provider) ResolveTableForIndex(ctx context.Context, _ spec.Dialect, schema string, index string) (string, error)

LoadTableSnapshot reads one target table shape from PostgreSQL catalogs.

type QueryAccessConnResolver added in v0.390.0 

type QueryAccessConnResolver struct{}

QueryAccessConnResolver is not available without postgresql build tag.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.