postgres

README

Postgres

Using Config

// config.go
pkg config

type Config struct {
    cfgPkg.BaseConfig `mapstructure:",squash"`
    Postgres postgresPkg.Config `mapstructure:"postgres"`
}

// main.go
var conf config.Config
config.LoadConfig("WELLKNOWN", &conf, nil)

pgDb, err := postgresPkg.ConnectRetry(ctx, conf.Postgres, time.Minute)

Using ConnectRetry

ConnectRetry is a function that tries to establish a db connection for the given maxDuration time.Duration. It will periodically retry, using a fibonacci backoff pattern.

For usage example, see above.

Using MigrateUp

Given the following folder structure:

src/
├─ postgres/
│  ├─ postgres.go
│  ├─ migrations/
│  │  ├─ 001_init.down.sql
│  │  ├─ 001_init.up.sql
├─ main.go     

First, create a variable of type embed.FS and annotate it with //go:embed relative-path, pointing to the folder containing the migration files (no . or .. allowed):

// postgres/postgres.go
pkg postgres 

//go:embed migrations
var Migrations embed.FS

Then, when you established the DB connection (here in main.go), pass the variable and path to MigrateUP()

// main.go
pkg main

func main() {
	// ...
	pgDb, _ := postgresPkg.ConnectRetry(...)
	postgres.MigrateUP(pgDb, postgres.Migrations, "migrations")
} 

The last parameter is the path relative to the embedded file system.

Documentation

Index

• func ConnectRetry(ctx context.Context, conf Config, maxDuration time.Duration, ...) (conn *pgxpool.Pool, err error)
• func MigrateUP(pool *pgxpool.Pool, migrations embed.FS, migrationsPath string) error
• type Config
  • func (c Config) DSN() string

Functions

func ConnectRetry

func ConnectRetry(ctx context.Context, conf Config, maxDuration time.Duration, errChan chan<- error) (conn *pgxpool.Pool, err error)

ConnectRetry tries to connect to the database given by Config. If the connection can't be established, it will retry periodically for maxDuration, using a fibonacci backoff starting with 500ms. It also uses a jitter of +/-50ms to avoid all instances trying to connect at the very same time. All errors not returned immediately (retryable errors) will be sent through errChan

func MigrateUP

func MigrateUP(pool *pgxpool.Pool, migrations embed.FS, migrationsPath string) error

Types

type Config

type Config struct {
	Host     string            `mapstructure:"host" envconfig:"HOST" default:"127.0.0.1"`
	Port     int               `mapstructure:"port" envconfig:"PORT" default:"5432"`
	Database string            `mapstructure:"database" envconfig:"DATABASE" default:"postgres"`
	User     string            `mapstructure:"user" envconfig:"USER" default:"postgres"`
	Password string            `mapstructure:"password" envconfig:"PASSWORD" default:"postgres"`
	Params   map[string]string `mapstructure:"params" envconfig:"PARAMS" default:"sslmode:require"`
}

func (Config) DSN

func (c Config) DSN() string

DSN assembles the connection string for the given Config. e.g. postgres://user:password@host:port/database?param1=value1