postgres

README

helix.go - PostgreSQL integration

The PostgreSQL integration provides an opinionated way to interact with PostgreSQL as OLTP database for helix services.

The integration works with all PostgreSQL-compatible databases, such as:

• Citus
• Timescale
• CockroachDB
• YugabyteDB
• Neon
• Google AlloyDB
• Amazon Aurora

Documentation

Overview

Package postgres exposes an opinionated way to interact with PostgreSQL.

Index

• type Config
• type PostgreSQL
  • func Connect(cfg Config) (PostgreSQL, error)
• type Tx

Types

type Config

type Config struct {

	// Addresses are PostgreSQL addresses to connect to.
	//
	// Default:
	//
	//   "127.0.0.1:5432"
	Address string `json:"address"`

	// Database is the database to connect to.
	//
	// Required.
	Database string `json:"-"`

	// User is the user to use to connect to the database.
	//
	// Required.
	User string `json:"-"`

	// Password is the user's password to connect to the database.
	//
	// Required.
	Password string `json:"-"`

	// TLSConfig configures TLS to communicate with the PostgreSQL server.
	TLS integration.ConfigTLS `json:"tls"`

	// OnNotification is a callback function called when a notification from the
	// LISTEN/NOTIFY system is received.
	OnNotification func(notif *pgconn.Notification) `json:"-"`
}

Config is used to configure the PostgreSQL integration.

type PostgreSQL

type PostgreSQL interface {
	BeginTx(ctx context.Context, txOptions pgx.TxOptions) (Tx, error)
	Exec(ctx context.Context, query string, args ...any) (pgconn.CommandTag, error)
	Query(ctx context.Context, query string, args ...any) (pgx.Rows, error)
	QueryRow(ctx context.Context, query string, args ...any) pgx.Row
	SendBatch(ctx context.Context, batch *pgx.Batch) pgx.BatchResults
}

PostgreSQL exposes an opinionated way to interact with PostgreSQL, by bringing automatic distributed tracing as well as error recording within traces.

func Connect

func Connect(cfg Config) (PostgreSQL, error)

Connect tries to connect to the PostgreSQL server given the Config. Returns an error if Config is not valid or if the connection failed.

type Tx

type Tx interface {
	Begin(ctx context.Context) (Tx, error)
	Commit(ctx context.Context) error
	Rollback(ctx context.Context) error
	Exec(ctx context.Context, query string, args ...any) (commandTag pgconn.CommandTag, err error)
	Prepare(ctx context.Context, id string, query string) (*pgconn.StatementDescription, error)
	Query(ctx context.Context, query string, args ...any) (pgx.Rows, error)
	QueryRow(ctx context.Context, query string, args ...any) pgx.Row
	SendBatch(ctx context.Context, b *pgx.Batch) pgx.BatchResults
	LargeObjects(ctx context.Context) pgx.LargeObjects
}

Tx represents a database transaction.