pg

README

pg

Documentation

Official godoc documentation (with examples) can be found at the Package Registry.

Usage

Add Package Dependency

go get -u github.com/x-ethr/pg

Import & Implement

main.go

package main

import (
    "fmt"

    "github.com/x-ethr/pg"
)

func main() {
    ctx, level := context.Background(), slog.LevelInfo

    uri := pg.DSN()
    connection, e := database.Connection(ctx, uri)
    if e != nil {
        panic(e)
    }
}

• Please refer to the code examples for additional usage and implementation details.
• See https://pkg.go.dev/github.com/x-ethr/environment for additional documentation.

Contributions

See the Contributing Guide for additional details on getting started.

Documentation

Overview

Package pg provides postgresql abstractions for connecting and maintaining database connections.

Index

• Variables
• func Connection(ctx context.Context, uri string) (*pgxpool.Conn, error)
• func DSN() (v string)
• func Disconnect(ctx context.Context, connection *pgxpool.Conn, tx pgx.Tx)
• type Options
  • func Settings() *Options
• type Variadic
• type Warnings

Variables

var Pool atomic.Pointer[pgxpool.Pool]

Functions

func Connection

func Connection(ctx context.Context, uri string) (*pgxpool.Conn, error)

Connection establishes a connection to the database using pgxpool. If a connection pool does not exist, a new one is created and stored in the pool variable. Returns a connection from the connection pool. If an error occurs during connection creation, nil and the error are returned.

func DSN

func DSN() (v string)

DSN represents the postgresql connection string. pool_max_conns: integer greater than 0 pool_min_conns: integer 0 or greater pool_max_conn_lifetime: duration string pool_max_conn_idle_time: duration string pool_health_check_period: duration string pool_max_conn_lifetime_jitter: duration string

• https://www.postgresql.org/docs/current/libpq-envars.html
• https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS

func Disconnect

func Disconnect(ctx context.Context, connection *pgxpool.Conn, tx pgx.Tx)

Disconnect closes the transaction and releases the connection back to the pool. If `tx` is not nil, it rolls back the transaction and logs any error. If `connection` is not nil, it releases the connection back to the pool.

Types

type Options

type Options struct {
	Variables []string  // Variables represents an array of environment variables (as returned by [os.Environ]), to selectively log.
	Warnings  *Warnings // Warnings represents logging options relating to [slog.Warn] logs. Defaults to a non-nil [Warnings] reference with all attributes set to false.
}

Options is the configuration structure optionally mutated via the Variadic constructor used throughout the package.

func Settings

func Settings() *Options

Settings represents a default constructor for Options.

type Variadic

type Variadic func(o *Options)

Variadic represents a functional constructor for the Options type. Typical callers of Variadic won't need to perform nil checks as all implementations first construct an Options reference using packaged default(s).

• However, see Settings for construction of an Options type.

type Warnings

type Warnings struct {
	Empty   bool // Empty represents a logging option to warn if a given environment variable is set to any empty string. Requires [Options.Variables]. Defaults to false.
	Missing bool // Missing represents a logging option to warn if a given environment variable isn't found. Requires [Options.Variables]. Defaults to false.
}