database

Documentation

Index

• func CreateConnectionString(values map[string]string) string
• func NamesValuesFromRecord(x interface{}) ([]string, []interface{})
• func OpenPgxConn(config configuration.PostgresConfig) (*pgx.Conn, error)
• func OpenPgxPool(config configuration.PostgresConfig) (*pgxpool.Pool, error)
• func ParseNullInt32(nullInt sql.NullInt32) *int32
• func ParseNullString(nullString sql.NullString) *string
• func ParseNullStringDefault(nullString sql.NullString) string
• func ParseNullTime(nullTime sql.NullTime) *time.Time
• func ReadInt(rows pgx.Rows) (int, error)
• func UniqueTableName(table string) string
• func UpdateDatabase(ctx *armadacontext.Context, db Querier, migrations []Migration) error
• func Upsert[T any](ctx *armadacontext.Context, tx pgx.Tx, tableName string, records []T) error
• func UpsertWithTransaction[T any](ctx *armadacontext.Context, db *pgxpool.Pool, tableName string, records []T) error
• func WithTestDb(migrations []Migration, action func(db *pgxpool.Pool) error) error
• func WithTestDbCustom(migrations []Migration, config configuration.PostgresConfig, ...) error
• type Migration
  • func NewMigration(id int, name string, sql string) Migration
  • func ReadMigrations(fsys fs.FS, basePath string) ([]Migration, error)
  • func ReadMigrationsFromStatik(namespace string) ([]Migration, error)
• type Querier

Functions

func CreateConnectionString

func CreateConnectionString(values map[string]string) string

func NamesValuesFromRecord

func NamesValuesFromRecord(x interface{}) ([]string, []interface{})

NamesValuesFromRecord returns a slice composed of the field names and another composed of the corresponding values for fields of a struct marked with "db" tags.

For example, if x is an instance of a struct with definition

type Rectangle struct {
	Width int  `db:"width"`
	Height int `db:"height"`
},

where Width = 10 and Height = 5, it returns ["width", "height"], [10, 5].

This function does not handle pointers to structs, i.e., x must be Rectangle{} and not &Rectangle{}.

func OpenPgxConn

func OpenPgxConn(config configuration.PostgresConfig) (*pgx.Conn, error)

func OpenPgxPool

func OpenPgxPool(config configuration.PostgresConfig) (*pgxpool.Pool, error)

func ParseNullInt32

func ParseNullInt32(nullInt sql.NullInt32) *int32

func ParseNullString

func ParseNullString(nullString sql.NullString) *string

func ParseNullStringDefault

func ParseNullStringDefault(nullString sql.NullString) string

func ParseNullTime

func ParseNullTime(nullTime sql.NullTime) *time.Time

func ReadInt

func ReadInt(rows pgx.Rows) (int, error)

func UniqueTableName

func UniqueTableName(table string) string

func UpdateDatabase

func UpdateDatabase(ctx *armadacontext.Context, db Querier, migrations []Migration) error

func Upsert

func Upsert[T any](ctx *armadacontext.Context, tx pgx.Tx, tableName string, records []T) error

Upsert is an optimised SQL call for bulk upserts.

For efficiency, this function: 1. Creates an empty temporary SQL table. 2. Inserts all records into the temporary table using the postgres-specific COPY wire protocol. 3. Upserts all records from the temporary table into the target table (as specified by tableName).

The COPY protocol can be faster than repeated inserts for as little as 5 rows; see https://www.postgresql.org/docs/current/populate.html https://pkg.go.dev/github.com/jackc/pgx/v5#hdr-Copy_Protocol

The records to write should be structs with fields marked with "db" tags. Field names and values are extracted using the NamesValuesFromRecord function; see its definition for details. The first field is used as the primary key in SQL.

The temporary table is created with the provided schema, which should be of the form (

id UUID PRIMARY KEY,
width int NOT NULL,
height int NOT NULL

) I.e., it should omit everything before and after the "(" and ")", respectively.

func UpsertWithTransaction

func UpsertWithTransaction[T any](ctx *armadacontext.Context, db *pgxpool.Pool, tableName string, records []T) error

func WithTestDb

func WithTestDb(migrations []Migration, action func(db *pgxpool.Pool) error) error

WithTestDb spins up a Postgres database for testing migrations: perform the list of migrations before entering the action callback action: callback for client code

func WithTestDbCustom

func WithTestDbCustom(migrations []Migration, config configuration.PostgresConfig, action func(db *pgxpool.Pool) error) error

WithTestDbCustom connects to specified database for testing migrations: perform the list of migrations before entering the action callback config: PostgresConfig to specify connection details to database action: callback for client code

Types

type Migration

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

Migration represents a single, versioned database migration script

func NewMigration

func NewMigration(id int, name string, sql string) Migration

func ReadMigrations

func ReadMigrations(fsys fs.FS, basePath string) ([]Migration, error)

func ReadMigrationsFromStatik

func ReadMigrationsFromStatik(namespace string) ([]Migration, error)

TODO: remove this when we've migrated over to iofs

type Querier

type Querier interface {
	Exec(context.Context, string, ...any) (pgconn.CommandTag, error)
	Query(context.Context, string, ...any) (pgx.Rows, error)
	QueryRow(context.Context, string, ...any) pgx.Row
}

This is a temporary interface to act as a bridge between upgrading from pgx/v4 to pgx/v5 TODO (Mo-Fatah): Remove this after https://github.com/armadaproject/armada/pull/2659 is ready to be used in the code.