database

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 ¶ added in v0.3.47

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, options ...UpsertOption) 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.

Options can be provided to customize upsert behavior, such as excluding specific columns.

func UpsertPartitioned ¶ added in v0.20.42

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

UpsertPartitioned is the in-transaction form of UpsertPartitionedWithTransaction. See that function for semantics.

func UpsertPartitionedWithTransaction ¶ added in v0.20.42

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

UpsertPartitionedWithTransaction is the partition-safe sibling of UpsertWithTransaction. It stages records via COPY, then performs DELETE-by-conflict-key followed by plain INSERT, in a single transaction.

Unlike UpsertWithTransaction, which relies on INSERT ... ON CONFLICT DO UPDATE, this variant correctly handles rows that move between partitions (e.g. a row whose partition-key column changes between calls). It is intended for tables partitioned by a column that forms part of the primary key, where ON CONFLICT on the non-partition-key alone is not possible.

conflictKey names the column(s) that identify "the same row" across upserts — typically the logical primary key (e.g. ["job_id"]) even when the physical primary key is composite (e.g. (job_id, state)). Duplicate conflict-key values within a single batch are not deduplicated; callers must dedupe.

func UpsertWithTransaction ¶ added in v0.3.63

func UpsertWithTransaction[T any](ctx *armadacontext.Context, db *pgxpool.Pool, tableName string, records []T, options ...UpsertOption) 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