postgres

Documentation

Overview

Package postgres is liteorm's Postgres backend over the NATIVE pgx/v5 API (pgxpool, not the database/sql shim), giving the binary protocol scan path and the native fast-paths (CopyFrom bulk, savepoints). It adapts pgx to liteorm's core contracts while keeping pgx types off the public surface: pgconn.CommandTag becomes liteorm.Result, pgconn.PgError is normalized to liteorm sentinels, and Scan (not Values) is the primary, leak-free read path.

Index

• func Notify(ctx context.Context, sess liteorm.Session, channel, payload string) error
• func Open(ctx context.Context, dsn string, opts ...liteorm.Option) (*liteorm.DB, error)
• func Pool(sess liteorm.Session) (*pgxpool.Pool, bool)
• type Listener
  • func Listen(ctx context.Context, sess liteorm.Session, channels ...string) (*Listener, error)
  • func (l *Listener) Add(ctx context.Context, channel string) error
  • func (l *Listener) Close(context.Context) error
  • func (l *Listener) Receive(ctx context.Context) (Notification, error)
  • func (l *Listener) Remove(ctx context.Context, channel string) error
• type Notification

Functions

func Notify

func Notify(ctx context.Context, sess liteorm.Session, channel, payload string) error

Notify sends an asynchronous notification on channel with an optional payload, using any pooled connection. Listeners on the same database receive it. The channel name is an identifier, so it is passed through pg_notify's first argument as a bound parameter (no identifier interpolation).

func Open

func Open(ctx context.Context, dsn string, opts ...liteorm.Option) (*liteorm.DB, error)

Open creates a pgx connection pool for dsn and returns a liteorm.DB on the Postgres dialect.

func Pool

func Pool(sess liteorm.Session) (*pgxpool.Pool, bool)

Pool returns the underlying *pgxpool.Pool for a liteorm.Session opened by this package, so Postgres-specific features (LISTEN/NOTIFY) can acquire a dedicated connection. The second result is false for any other backend. The pgx type stays out of the core: this lives in the Postgres backend, which owns it.

Types

type Listener

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

Listener subscribes to one or more LISTEN channels on a single dedicated connection (LISTEN is connection-scoped, so it cannot use the pool's round-robin). Receive blocks until a notification arrives or ctx is cancelled. A Listener is not safe for concurrent use; run one Receive loop per Listener. Always Close it to UNLISTEN and return the connection to the pool.

func Listen

func Listen(ctx context.Context, sess liteorm.Session, channels ...string) (*Listener, error)

Listen acquires a dedicated connection from sess's pool and issues LISTEN for each channel. sess must be a *liteorm.DB opened by this package.

func (*Listener) Add

func (l *Listener) Add(ctx context.Context, channel string) error

Add subscribes to an additional channel on the same connection.

func (*Listener) Close

func (l *Listener) Close(context.Context) error

Close releases the dedicated connection back to the pool; pgx resets the connection on release, which clears its subscriptions. A Listener is not safe for concurrent use — do not call Close while a Receive is in flight.

func (*Listener) Receive

func (l *Listener) Receive(ctx context.Context) (Notification, error)

Receive blocks until the next notification arrives on a subscribed channel or ctx is done. The returned error is ctx.Err() on cancellation.

func (*Listener) Remove

func (l *Listener) Remove(ctx context.Context, channel string) error

Remove unsubscribes from a channel.

type Notification

type Notification struct {
	Channel string // the channel the payload arrived on
	Payload string // the NOTIFY payload (possibly empty)
	PID     uint32 // backend PID that issued the NOTIFY
}

Notification is a delivered LISTEN/NOTIFY message. It is a liteorm value type — pgconn.Notification is copied into it so no driver type leaks.