postgres

Documentation

Overview

Package postgres provides the Postgres concrete DialectAdapter.

Index

• func NormalizeDSN(pgString string) (string, error)
• type Adapter
  • func New() *Adapter
  • func (a *Adapter) AdvisoryLock(ctx context.Context, db *gorm.DB, id int64) (func(), error)
  • func (*Adapter) IsRelationAlreadyExistsErr(err error) bool
  • func (*Adapter) Name() string
  • func (*Adapter) NormalizeDSN(raw string) (string, error)
  • func (a *Adapter) OpenConnection(ctx context.Context, dsn string, opts dialect.ConnectionOptions) (gorm.Dialector, *sql.DB, func() error, error)
  • func (*Adapter) QuoteIdentifier(name string) string
  • func (a *Adapter) RegisterAcquireHook(fn dialect.AcquireHook) error
  • func (a *Adapter) RegisterReleaseHook(fn dialect.ReleaseHook) error

Functions

func NormalizeDSN

func NormalizeDSN(pgString string) (string, error)

NormalizeDSN converts a postgres:// or postgresql:// URI into the libpq keyword=value DSN form. If the input already looks like libpq form — heuristically, contains '=' and does not start with a postgres scheme — it is returned unchanged.

Returns an error if the URI scheme is not postgres / postgresql.

Caveats inherited from the legacy implementation (preserved here for behavioural parity; tracked as follow-up):

• IPv6 host literals lose their square brackets.
• Query parameter values containing spaces or '=' are emitted verbatim and may break the libpq parser.
• Empty input returns an "invalid scheme" error rather than a specific empty-DSN error.

Types

type Adapter

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

Adapter is the Postgres concrete implementation of dialect.DialectAdapter. Construct with New; hook registration must happen BEFORE OpenConnection.

Hook dispatch design: at OpenConnection time the current hook chain is captured into per-pool closures (see makeAcquireDispatcher / makeReleaseDispatcher). Each pool runs against its own immutable snapshot — no lock taken on the hot path, no allocation per acquire/release, and a second OpenConnection on the same adapter cannot mutate state observed by an in-flight first pool's hooks.

func New

func New() *Adapter

New returns a fresh Adapter with no registered hooks.

func (*Adapter) AdvisoryLock

func (a *Adapter) AdvisoryLock(ctx context.Context, db *gorm.DB, id int64) (func(), error)

AdvisoryLock implements dialect.DialectAdapter using Postgres pg_try_advisory_lock semantics. Pins a single *sql.Conn for the duration of the lock so that pg_try_advisory_lock (session-level) and pg_advisory_unlock run against the same Postgres session. Retries every migrationLockRetryInterval until ctx is cancelled or the lock is acquired.

The pinned conn is acquired through pgxpool, so any registered acquire hooks fire (e.g., the tenancy provider's beforeAcquire). This is safe: migrations typically run without tenancy claims, so the hook is a no-op. When the pinned conn is closed, AfterRelease runs and clears any session state it may have set.

func (*Adapter) IsRelationAlreadyExistsErr

func (*Adapter) IsRelationAlreadyExistsErr(err error) bool

IsRelationAlreadyExistsErr implements dialect.DialectAdapter. Detects SQLSTATE 42P07 ("relation already exists"), used to gracefully handle concurrent migration startup races.

func (*Adapter) Name

func (*Adapter) Name() string

Name implements dialect.DialectAdapter.

func (*Adapter) NormalizeDSN

func (*Adapter) NormalizeDSN(raw string) (string, error)

NormalizeDSN implements dialect.DialectAdapter.

func (*Adapter) OpenConnection

func (a *Adapter) OpenConnection(
	ctx context.Context,
	dsn string,
	opts dialect.ConnectionOptions,
) (gorm.Dialector, *sql.DB, func() error, error)

OpenConnection implements dialect.DialectAdapter.

Pool sizing notes:

• MaxIdleConns is forced to 0 on the *sql.DB so every release goes through pgxpool — this is the property the hook chain relies on to guarantee PrepareConn fires per query, never leaking session state between requests.
• MaxOpenConns mirrors pgxpool.MaxConns so sql.DB never tries to open more conns than the pool allows.

func (*Adapter) QuoteIdentifier

func (*Adapter) QuoteIdentifier(name string) string

QuoteIdentifier implements dialect.DialectAdapter.

func (*Adapter) RegisterAcquireHook

func (a *Adapter) RegisterAcquireHook(fn dialect.AcquireHook) error

RegisterAcquireHook implements dialect.DialectAdapter.

func (*Adapter) RegisterReleaseHook

func (a *Adapter) RegisterReleaseHook(fn dialect.ReleaseHook) error

RegisterReleaseHook implements dialect.DialectAdapter.