postgres

package
v1.2.0 Latest Latest
Warning

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

 Go to latest Published: Jul 15, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source 
const DiscoverAllSchemaTablesQuery = "SELECT tablename FROM pg_tables WHERE schemaname=$1"
View Source 
const DiscoverAllSchemasQuery = "" /* 197-byte string literal not displayed */
View Source 
const MaxConns = 50

MaxConns is the default maximum number of connections in a Postgres connection pool. It also bounds the global concurrent-COPY budget in the bulk-ingest writer, so the two never drift.

View Source 
const PrimaryKeyColumnsQuery = `` /* 266-byte string literal not displayed */

PrimaryKeyColumnsQuery returns the primary-key columns of a table, ordered by their position in the primary-key definition.

View Source 
const (
	PublicSchema = "public"
)

Variables

View Source 
var (
	ErrConnTimeout = errors.New("connection timeout")
	ErrNoRows      = errors.New("no rows")
)
View Source 
var ErrInvalidTableName = errors.New("invalid table name format")
View Source 
var ErrUnsupportedCopyDataMessage = errors.New("unsupported copy data message")

Functions

func DefaultReplicationSlotName added in v0.3.0 

func DefaultReplicationSlotName(dbName string) string

func DiscoverAllSchemaTables added in v0.8.0 

func DiscoverAllSchemaTables(ctx context.Context, conn Querier, schema string) ([]string, error)

func DiscoverAllSchemas added in v0.8.0 

func DiscoverAllSchemas(ctx context.Context, conn Querier) ([]string, error)

func ExtensionTypeNames added in v1.2.0 

func ExtensionTypeNames() []string

ExtensionTypeNames returns the names of every postgres extension type pgstream teaches pgx about on each connection (see extensionTypes), including the additional types a single entry registers (e.g. pgvector's halfvec and sparsevec). Callers that need to know whether pgstream can handle a type beyond pgx's built-in set — such as the preflight schema compatibility check — consult this list so it stays in sync with what pgstream actually registers.

func GetPrimaryKeyColumns added in v1.2.0 

func GetPrimaryKeyColumns(ctx context.Context, conn Querier, schema, table string) ([]string, error)

func IsQuotedIdentifier added in v0.7.6 

func IsQuotedIdentifier(s string) bool

func IsValidReplicationSlotName added in v0.9.3 

func IsValidReplicationSlotName(name string) error

IsValidReplicationSlotName checks if the provided replication slot name is valid. Replication slot names may only contain lower case letters, numbers, and the underscore character.

func MapError added in v0.8.10 

func MapError(err error) error

MapError maps a Postgres error to a more specific error type

func ParseConfig added in v0.8.4 

func ParseConfig(pgurl string) (*pgx.ConnConfig, error)

func QuoteIdentifier added in v0.5.0 

func QuoteIdentifier(s string) string

QuoteIdentifier quotes an identifier (e.g. table or schema name) if it is not already quoted. Trailing and leading quotes are added, and any embedded double quotes are escaped by doubling them. For example: - my_table -> "my_table" - "my_table" -> "my_table" (already quoted, returned as-is) - my"table -> "my""table"

func QuoteQualifiedIdentifier added in v0.5.0 

func QuoteQualifiedIdentifier(schema, table string) string

func RunPGDump added in v0.4.0 

func RunPGDump(_ context.Context, opts PGDumpOptions) ([]byte, error)

Func RunPGDump runs pg_dump command with the given options and returns the result.

func RunPGDumpAll added in v0.7.9 

func RunPGDumpAll(_ context.Context, opts PGDumpAllOptions) ([]byte, error)

Func RunPGDumpAll runs pg_dumpall command with the given options and returns the result.

func RunPGRestore added in v0.4.0 

func RunPGRestore(ctx context.Context, opts PGRestoreOptions, dump []byte) (string, error)

Func RunPGRestore runs pg_restore command with the given options and returns the result.

func UnquoteIdentifier added in v1.0.1 

func UnquoteIdentifier(s string) string

UnquoteIdentifier reverses the quoting applied by QuoteIdentifier. If the string is not a quoted identifier, it is returned as-is. If it is a quoted identifier, the leading and trailing quotes are removed, and any embedded double quotes are unescaped by replacing "" with ". For example: - `my_table`-> `my_table` (not quoted, returned as-is) - `"my_table"` -> `my_table` (quotes removed) - `"my""table"` -> `my"table` (quotes removed, embedded quotes unescaped)

func ValidateWildcardSchemaTables added in v1.2.0 

func ValidateWildcardSchemaTables(schemaTables map[string][]string) error

ValidateWildcardSchemaTables is the schema->table-list counterpart of ValidateWildcardSchema, for callers operating on map[string][]string.

Types

type AcquireFunc added in v1.2.0 

type AcquireFunc func(ctx context.Context) (Querier, error)

AcquireFunc lazily yields a Postgres connection. Useful when a set of related callers want to share a single TCP connection without each one having to think about lifecycle.

type CommandTag 

type CommandTag struct {
	pgconn.CommandTag
}

type Conn 

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

func NewConn 

func NewConn(ctx context.Context, url string) (*Conn, error)

func (*Conn) Close 

func (c *Conn) Close(ctx context.Context) error

func (*Conn) CopyFrom added in v0.6.0 

func (c *Conn) CopyFrom(ctx context.Context, tableName string, columnNames []string, srcRows [][]any) (int64, error)

func (*Conn) Exec 

func (c *Conn) Exec(ctx context.Context, query string, args ...any) (CommandTag, error)

func (*Conn) ExecInTx added in v0.3.0 

func (c *Conn) ExecInTx(ctx context.Context, fn func(Tx) error) error

func (*Conn) ExecInTxWithOptions added in v0.3.0 

func (c *Conn) ExecInTxWithOptions(ctx context.Context, fn func(Tx) error, opts TxOptions) error

func (*Conn) Ping added in v0.5.0 

func (c *Conn) Ping(ctx context.Context) error

func (*Conn) Query 

func (c *Conn) Query(ctx context.Context, query string, args ...any) (Rows, error)

func (*Conn) QueryRow 

func (c *Conn) QueryRow(ctx context.Context, dest []any, query string, args ...any) error

type ErrCacheLookupFailed added in v0.9.6 

type ErrCacheLookupFailed struct {
	Details string
}

func (*ErrCacheLookupFailed) Error added in v0.9.6 

func (e *ErrCacheLookupFailed) Error() string

type ErrConstraintViolation added in v0.4.0 

type ErrConstraintViolation struct {
	Details string
}

func (*ErrConstraintViolation) Error added in v0.4.0 

func (e *ErrConstraintViolation) Error() string

type ErrDataException added in v0.4.1 

type ErrDataException struct {
	Details string
}

func (*ErrDataException) Error added in v0.4.1 

func (e *ErrDataException) Error() string

type ErrFeatureNotSupported added in v1.0.0 

type ErrFeatureNotSupported struct {
	Details string
}

func (*ErrFeatureNotSupported) Error added in v1.0.0 

func (e *ErrFeatureNotSupported) Error() string

type ErrPermissionDenied added in v0.8.4 

type ErrPermissionDenied struct {
	Details string
}

func (*ErrPermissionDenied) Error added in v0.8.4 

func (e *ErrPermissionDenied) Error() string

type ErrPreconditionFailed added in v0.9.1 

type ErrPreconditionFailed struct {
	Details string
}

func (*ErrPreconditionFailed) Error added in v0.9.1 

func (e *ErrPreconditionFailed) Error() string

type ErrProgramLimitExceeded added in v0.9.6 

type ErrProgramLimitExceeded struct {
	Details string
}

func (*ErrProgramLimitExceeded) Error added in v0.9.6 

func (e *ErrProgramLimitExceeded) Error() string

type ErrRelationAlreadyExists added in v0.5.0 

type ErrRelationAlreadyExists struct {
	Details string
}

func (*ErrRelationAlreadyExists) Error added in v0.5.0 

func (e *ErrRelationAlreadyExists) Error() string

type ErrRelationDoesNotExist added in v0.4.0 

type ErrRelationDoesNotExist struct {
	Details string
}

func (*ErrRelationDoesNotExist) Error added in v0.4.0 

func (e *ErrRelationDoesNotExist) Error() string

type ErrRuleViolation added in v0.9.0 

type ErrRuleViolation struct {
	Details string
}

func (*ErrRuleViolation) Error added in v0.9.0 

func (e *ErrRuleViolation) Error() string

type ErrSyntaxError added in v0.4.0 

type ErrSyntaxError struct {
	Details string
}

func (*ErrSyntaxError) Error added in v0.4.0 

func (e *ErrSyntaxError) Error() string

type Error 

type Error struct {
	Severity string
	Msg      string
}

func (*Error) Error 

func (e *Error) Error() string

type IdentifySystemResult 

type IdentifySystemResult pglogrepl.IdentifySystemResult

type LazyConn added in v1.2.0 

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

LazyConn memoises a single *Conn (or its dial error) for a URL. Cheap to construct: nothing is opened until Acquire is called for the first time. Not safe for concurrent use — designed for the sequential case (e.g. a preflight check engine that runs checks one after another).

func NewLazyConn added in v1.2.0 

func NewLazyConn(url string) *LazyConn

NewLazyConn returns a LazyConn that will open a connection to url on first Acquire.

func (*LazyConn) Acquire added in v1.2.0 

func (l *LazyConn) Acquire(ctx context.Context) (Querier, error)

Acquire returns the cached conn, opening it on the first call. A dial failure is cached too — subsequent calls return the same error without retrying.

func (*LazyConn) Close added in v1.2.0 

func (l *LazyConn) Close(ctx context.Context) error

Close releases the underlying connection if one was opened.

type Mapper added in v0.3.0 

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

Mapper provides PostgreSQL type information mapping from OIDs to type names. It uses a combination of the pgx type map for standard types and a custom cache for user-defined types, querying the database when necessary.

func NewMapper added in v0.3.0 

func NewMapper(conn Querier) *Mapper

NewMapper creates a new Mapper instance with the given database querier. The mapper is initialized with the standard pgx type map and an empty custom type cache.

func (*Mapper) TypeForOID added in v0.3.0 

func (m *Mapper) TypeForOID(ctx context.Context, oid uint32) (string, error)

TypeForOID returns the PostgreSQL type name for the given OID. It first checks the standard pgx type map, then the custom type cache, and finally queries the database if the type is not found in either cache. Note: This method may acquire a database connection if the type is not cached.

type PGDumpAllFn added in v0.7.9 

type PGDumpAllFn func(context.Context, PGDumpAllOptions) ([]byte, error)

type PGDumpAllOptions added in v0.7.9 

type PGDumpAllOptions struct {
	// ConnectionString
	ConnectionString string
	// RolesOnly if true, only roles will be exported (no schema)
	RolesOnly bool
	// Clean if true, the target database will be cleaned before the dump is restored
	Clean bool
	// NoPasswords if true, no role passwords will be included in the dump
	NoPasswords bool
	// Role specifies the role to be used for the dump
	Role string
	// Do not output commands to set ownership of objects to match the original database
	NoOwner bool
	// Do not dump privileges (grant/revoke)
	NoPrivileges bool
	// Options to pass to pg_dumpall
	Options []string
}

func (*PGDumpAllOptions) ToArgs added in v0.7.9 

func (opts *PGDumpAllOptions) ToArgs() []string

type PGDumpFn added in v0.6.0 

type PGDumpFn func(context.Context, PGDumpOptions) ([]byte, error)

type PGDumpOptions added in v0.4.0 

type PGDumpOptions struct {
	// ConnectionString
	ConnectionString string
	// Format (c custom, d directory, t tar, p plain text)
	Format string
	// Schemas to export
	Schemas []string
	// Schemas to be excluded from the dump, regex patterns supported
	ExcludeSchemas []string
	// Tables to export
	Tables []string
	// Tables to be excluded from the dump, regex patterns supported
	ExcludeTables []string
	// SchemaOnly if true, only schema will be exported (no data)
	SchemaOnly bool
	// DataOnly if true, only data will be exported (no schema)
	DataOnly bool
	// Do not dump privileges (grant/revoke)
	NoPrivileges bool
	// Do not output commands to set ownership of objects to match the original database
	NoOwner bool
	// Clean all the objects that will be dumped
	Clean bool
	// Create the database
	Create bool
	// Specifies a role name to be used to create the dump
	Role string
	// Options to pass to pg_dump
	Options []string
}

func (*PGDumpOptions) ToArgs added in v0.4.0 

func (opts *PGDumpOptions) ToArgs() []string

type PGRestoreErrors added in v0.5.0 

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

func NewPGRestoreErrors added in v0.5.0 

func NewPGRestoreErrors(errs ...error) *PGRestoreErrors

func (PGRestoreErrors) Error added in v0.5.0 

func (e PGRestoreErrors) Error() string

func (*PGRestoreErrors) GetIgnoredErrors added in v0.5.0 

func (e *PGRestoreErrors) GetIgnoredErrors() []error

func (*PGRestoreErrors) HasCriticalErrors added in v0.5.0 

func (e *PGRestoreErrors) HasCriticalErrors() bool

func (PGRestoreErrors) HasErrors added in v0.8.4 

func (e PGRestoreErrors) HasErrors() bool

type PGRestoreFn added in v0.6.0 

type PGRestoreFn func(context.Context, PGRestoreOptions, []byte) (string, error)

type PGRestoreOptions added in v0.4.0 

type PGRestoreOptions struct {
	// ConnectionString
	ConnectionString string
	// SchemaOnly if true, only schema will be restored (no data)
	SchemaOnly bool
	// Clean all the objects that will be restored
	Clean bool
	// Create target database
	Create bool
	// Format (c custom, d directory, t tar, p plain text)
	Format string
	// Options to pass to pg_restore
	Options []string
}

type Pool 

type Pool struct {
	*pgxpool.Pool
}

func NewConnPool 

func NewConnPool(ctx context.Context, url string, opts ...PoolOption) (*Pool, error)

func (*Pool) Close 

func (c *Pool) Close(_ context.Context) error

func (*Pool) CopyFrom added in v0.6.0 

func (c *Pool) CopyFrom(ctx context.Context, tableName string, columnNames []string, srcRows [][]any) (int64, error)

func (*Pool) Exec 

func (c *Pool) Exec(ctx context.Context, query string, args ...any) (CommandTag, error)

func (*Pool) ExecInTx added in v0.3.0 

func (c *Pool) ExecInTx(ctx context.Context, fn func(Tx) error) error

func (*Pool) ExecInTxWithOptions added in v0.3.0 

func (c *Pool) ExecInTxWithOptions(ctx context.Context, fn func(Tx) error, opts TxOptions) error

func (*Pool) Ping added in v0.5.0 

func (c *Pool) Ping(ctx context.Context) error

func (*Pool) Query 

func (c *Pool) Query(ctx context.Context, query string, args ...any) (Rows, error)

func (*Pool) QueryRow 

func (c *Pool) QueryRow(ctx context.Context, dest []any, query string, args ...any) error

type PoolOption added in v0.8.8 

type PoolOption func(*pgxpool.Config)

func WithMaxConnections added in v0.8.8 

func WithMaxConnections(maxConns int32) PoolOption

func WithRawJSONDecoding added in v1.2.0 

func WithRawJSONDecoding() PoolOption

WithRawJSONDecoding makes json/jsonb column values decode to their raw text representation (Go string) instead of being unmarshalled into Go values (maps, slices, nil). Intended for read paths that need byte-faithful values: the default unmarshalling turns the JSON null value ('null'::jsonb) into Go nil, making it indistinguishable from SQL NULL, and re-marshalling can reorder object keys.

Write paths must not use this option: it rebinds json/jsonb to a text-only codec, which would corrupt binary COPY encoding of those types.

type QualifiedName added in v0.6.2 

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

func NewQualifiedName added in v0.6.2 

func NewQualifiedName(s string) (*QualifiedName, error)

func (*QualifiedName) Name added in v0.6.2 

func (qn *QualifiedName) Name() string

func (*QualifiedName) Schema added in v0.6.2 

func (qn *QualifiedName) Schema() string

func (*QualifiedName) String added in v0.7.5 

func (qn *QualifiedName) String() string

type Querier 

type Querier interface {
	Query(ctx context.Context, query string, args ...any) (Rows, error)
	QueryRow(ctx context.Context, dest []any, query string, args ...any) error
	Exec(ctx context.Context, query string, args ...any) (CommandTag, error)
	ExecInTx(ctx context.Context, fn func(tx Tx) error) error
	ExecInTxWithOptions(ctx context.Context, fn func(tx Tx) error, txOpts TxOptions) error
	CopyFrom(ctx context.Context, tableName string, columnNames []string, srcRows [][]any) (int64, error)
	Ping(ctx context.Context) error
	Close(ctx context.Context) error
}

func ConnBuilder added in v0.4.1 

func ConnBuilder(ctx context.Context, url string) (Querier, error)

func ConnPoolBuilder added in v0.4.1 

func ConnPoolBuilder(ctx context.Context, url string) (Querier, error)

type QuerierBuilder added in v0.4.1 

type QuerierBuilder func(context.Context, string) (Querier, error)

type ReplicationConfig 

type ReplicationConfig struct {
	SlotName        string
	StartPos        uint64
	PluginArguments []string
}

type ReplicationConn 

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

func NewReplicationConn 

func NewReplicationConn(ctx context.Context, url string) (*ReplicationConn, error)

func (*ReplicationConn) Close 

func (c *ReplicationConn) Close(ctx context.Context) error

func (*ReplicationConn) IdentifySystem 

func (c *ReplicationConn) IdentifySystem(ctx context.Context) (IdentifySystemResult, error)

func (*ReplicationConn) ReceiveMessage 

func (c *ReplicationConn) ReceiveMessage(ctx context.Context) (*ReplicationMessage, error)

func (*ReplicationConn) SendStandbyStatusUpdate 

func (c *ReplicationConn) SendStandbyStatusUpdate(ctx context.Context, lsn uint64) error

func (*ReplicationConn) StartReplication 

func (c *ReplicationConn) StartReplication(ctx context.Context, cfg ReplicationConfig) error

type ReplicationMessage 

type ReplicationMessage struct {
	LSN            uint64
	ServerTime     time.Time
	WALData        []byte
	ReplyRequested bool
}

type ReplicationQuerier added in v0.8.8 

type ReplicationQuerier interface {
	IdentifySystem(ctx context.Context) (IdentifySystemResult, error)
	StartReplication(ctx context.Context, cfg ReplicationConfig) error
	SendStandbyStatusUpdate(ctx context.Context, lsn uint64) error
	ReceiveMessage(ctx context.Context) (*ReplicationMessage, error)
	Close(ctx context.Context) error
}

type Row 

type Row interface {
	pgx.Row
}

type Rows 

type Rows interface {
	pgx.Rows
}

type SchemaTableMap added in v0.7.8 

type SchemaTableMap map[string]map[string]struct{}

func NewSchemaTableMap added in v0.7.8 

func NewSchemaTableMap(tables []string) (SchemaTableMap, error)

func (SchemaTableMap) Add added in v0.7.8 

func (t SchemaTableMap) Add(table string) error

func (SchemaTableMap) ContainsExactSchemaTable added in v1.2.0 

func (t SchemaTableMap) ContainsExactSchemaTable(schema, table string) bool

ContainsExactSchemaTable returns true only if the table is listed by its exact name under the exact schema. Wildcard entries do not match.

func (SchemaTableMap) ContainsSchemaTable added in v0.7.8 

func (t SchemaTableMap) ContainsSchemaTable(schema, table string) bool

func (SchemaTableMap) GetSchemaTables added in v0.7.8 

func (t SchemaTableMap) GetSchemaTables(schema string) map[string]struct{}

func (SchemaTableMap) ValidateWildcardSchema added in v1.2.0 

func (t SchemaTableMap) ValidateWildcardSchema() error

ValidateWildcardSchema returns an error when the wildcard schema entry lists anything other than the wildcard table ("*.*"): the snapshot generators can't resolve a specific table name across all schemas.

type Tx added in v0.3.0 

type Tx interface {
	Query(ctx context.Context, query string, args ...any) (Rows, error)
	QueryRow(ctx context.Context, dest []any, query string, args ...any) error
	Exec(ctx context.Context, query string, args ...any) (CommandTag, error)
	CopyFrom(ctx context.Context, tableName string, columnNames []string, srcRows [][]any) (int64, error)
	CopyFromText(ctx context.Context, tableName string, columnNames []string, srcRows [][]any) (int64, error)
}

type TxAccessMode added in v0.3.0 

type TxAccessMode string
const (
	ReadWrite TxAccessMode = "read write"
	ReadOnly  TxAccessMode = "read only"
)

type TxIsolationLevel added in v0.3.0 

type TxIsolationLevel string
const (
	Serializable    TxIsolationLevel = "serializable"
	RepeatableRead  TxIsolationLevel = "repeatable read"
	ReadCommitted   TxIsolationLevel = "read committed"
	ReadUncommitted TxIsolationLevel = "read uncommitted"
)

type TxOptions added in v0.3.0 

type TxOptions struct {
	IsolationLevel TxIsolationLevel
	AccessMode     TxAccessMode
}

type Txn added in v0.3.0 

type Txn struct {
	pgx.Tx
}

func (*Txn) CopyFrom added in v0.6.2 

func (t *Txn) CopyFrom(ctx context.Context, tableName string, columnNames []string, srcRows [][]any) (int64, error)

CopyFrom uses pgx's binary-format COPY, which is the fast path for any column type pgx has a binary codec for. Callers must use CopyFromText instead when the target table contains extension columns whose binary representation pgx cannot produce.

func (*Txn) CopyFromText added in v1.1.0 

func (t *Txn) CopyFromText(ctx context.Context, tableName string, columnNames []string, srcRows [][]any) (int64, error)

CopyFromText runs the postgres COPY protocol in text format, rather than the binary format pgx defaults to. Text format makes the destination Postgres parse each value through the per-type input function. This matches pg_dump/pg_restore behaviour at the cost of a modest serialisation/wire-size overhead vs. binary COPY.

func (*Txn) Exec added in v0.3.0 

func (t *Txn) Exec(ctx context.Context, query string, args ...any) (CommandTag, error)

func (*Txn) Query added in v0.3.0 

func (t *Txn) Query(ctx context.Context, query string, args ...any) (Rows, error)

func (*Txn) QueryRow added in v0.3.0 

func (t *Txn) QueryRow(ctx context.Context, dest []any, query string, args ...any) error

Source Files

View all Source files

Directories

Path Synopsis

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.