postgres

Documentation

Overview

Package postgres provides PostgreSQL helpers for golembic.

Index

• Constants
• Variables
• func SetTimeoutMilliseconds(q url.Values, name string, d time.Duration) error
• func SetTimeoutSeconds(q url.Values, name string, d time.Duration) error
• type Config
  • func (c Config) GetConnectionString() (string, error)
• type Option
  • func OptAlwaysError(err error) Option
  • func OptConnectTimeout(d time.Duration) Option
  • func OptDatabase(database string) Option
  • func OptDriverName(name string) Option
  • func OptHost(host string) Option
  • func OptIdleConnections(count int) Option
  • func OptLockTimeout(d time.Duration) Option
  • func OptMaxConnections(count int) Option
  • func OptMaxLifetime(d time.Duration) Option
  • func OptPassword(password string) Option
  • func OptPort(port string) Option
  • func OptSSLMode(sslMode string) Option
  • func OptSchema(schema string) Option
  • func OptStatementTimeout(d time.Duration) Option
  • func OptUsername(username string) Option
• type SQLProvider
  • func New(opts ...Option) (*SQLProvider, error)
  • func (*SQLProvider) NewCreateTableParameters() golembic.CreateTableParameters
  • func (sp *SQLProvider) Open() (*sql.DB, error)
  • func (*SQLProvider) QueryParameter(index int) string
  • func (*SQLProvider) QuoteIdentifier(name string) string
  • func (*SQLProvider) QuoteLiteral(literal string) string
  • func (sp *SQLProvider) TableExistsSQL() string
  • func (*SQLProvider) TimestampColumn() golembic.TimestampColumn

Constants

const (
	// DefaultHost is the default database hostname, typically used
	// when developing locally.
	DefaultHost = "localhost"
	// DefaultPort is the default postgres port.
	DefaultPort = "5432"
	// DefaultDatabase is the default database to connect to, we use
	// `postgres` to not pollute the template databases.
	DefaultDatabase = "postgres"

	// DefaultDriverName is the default SQL driver to be used when creating
	// a new database connection pool via `sql.Open()`. This default driver
	// is expected to be registered by importing `github.com/lib/pq`.
	DefaultDriverName = "postgres"

	// DefaultLockTimeout is the default timeout to use when attempting to
	// acquire a lock.
	DefaultLockTimeout = 4 * time.Second
	// DefaultStatementTimeout is the default timeout to use when invoking a
	// SQL statement.
	DefaultStatementTimeout = 5 * time.Second
	// DefaultIdleConnections is the default number of idle connections.
	DefaultIdleConnections = 16
	// DefaultMaxConnections is the default maximum number of connections.
	DefaultMaxConnections = 32
	// DefaultMaxLifetime is the default maximum lifetime of driver connections.
	//
	// If max lifetime <= 0, connections are not closed due to a connection's age.
	// See: https://github.com/golang/go/blob/go1.15/src/database/sql/sql.go#L940
	DefaultMaxLifetime = time.Duration(0)
)

Variables

var (
	// ErrNegativeTimeout is the error returned when a timeout duration cannot
	// be negative.
	ErrNegativeTimeout = errors.New("Negative values not allowed for timeouts")
	// ErrNegativeCount is the error returned when a configured count cannot
	// be negative.
	ErrNegativeCount = errors.New("Negative values not allowed for count")
)

Functions

func SetTimeoutMilliseconds

func SetTimeoutMilliseconds(q url.Values, name string, d time.Duration) error

SetTimeoutMilliseconds sets a timeout value in connection string query parameters.

Valid units for this parameter in PostgresSQL are "ms", "s", "min", "h" and "d" and the value should be between 0 and 2147483647ms. We explicitly cast to milliseconds but leave validation on the value to PostgreSQL.

golembic=> BEGIN;
BEGIN
golembic=> SET LOCAL lock_timeout TO '4000ms';
SET
golembic=> SHOW lock_timeout;
 lock_timeout
--------------
 4s
(1 row)
--
golembic=> SET LOCAL lock_timeout TO '4500ms';
SET
golembic=> SHOW lock_timeout;
 lock_timeout
--------------
 4500ms
(1 row)
--
golembic=> COMMIT;
COMMIT

See: - https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-LOCK-TIMEOUT - https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-STATEMENT-TIMEOUT

func SetTimeoutSeconds

func SetTimeoutSeconds(q url.Values, name string, d time.Duration) error

SetTimeoutSeconds sets a timeout value in connection string query parameters.

This timeout is expected to be an exact number of seconds (as an integer) so we convert `d` to an integer first and set the value as a query parameter without units.

See: - https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-LOCK-TIMEOUT

Types

type Config

type Config struct {
	// ConnectionString is a fully formed connection string.
	ConnectionString string
	// Host is the server to connect to.
	Host string
	// Port is the port to connect to.
	Port string
	// Database is the database name
	Database string
	// Schema is the application schema within the database, defaults to `public`.
	Schema string
	// Username is the username for the connection via password auth.
	Username string
	// Password is the password for the connection via password auth.
	Password string
	// SSLMode is the SSL mode for the connection.
	SSLMode string

	// DriverName specifies the name of SQL driver to be used when creating
	// a new database connection pool via `sql.Open()`. The default driver
	// is expected to be registered by importing `github.com/lib/pq`, however
	// we may want to support other drivers that are wire compatible, such
	// as `github.com/jackc/pgx`.
	DriverName string

	// ConnectTimeout determines the maximum wait for connection. The minimum
	// allowed timeout is 2 seconds, so anything below is treated the same
	// as unset.
	//
	// See: https://www.postgresql.org/docs/10/libpq-connect.html#LIBPQ-CONNECT-CONNECT-TIMEOUT
	ConnectTimeout time.Duration
	// LockTimeout is the timeout to use when attempting to acquire a lock.
	//
	// See: https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-LOCK-TIMEOUT
	LockTimeout time.Duration
	// StatementTimeout is the timeout to use when invoking a SQL statement.
	//
	// See: https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-STATEMENT-TIMEOUT
	StatementTimeout time.Duration
	// IdleConnections is the number of idle connections.
	IdleConnections int
	// MaxConnections is the maximum number of connections.
	MaxConnections int
	// MaxLifetime is the maximum time a connection can be open.
	MaxLifetime time.Duration
}

Config is a set of connection config options.

func (Config) GetConnectionString

func (c Config) GetConnectionString() (string, error)

GetConnectionString creates a PostgreSQL connection string from the config. If `ConnectionString` is already cached on the `Config`, it will be returned immediately.

type Option

type Option = func(*Config) error

Option describes options used to create a new config for a SQL provider.

func OptAlwaysError

func OptAlwaysError(err error) Option

OptAlwaysError returns an option that always returns an error.

func OptConnectTimeout

func OptConnectTimeout(d time.Duration) Option

OptConnectTimeout sets the `ConnectTimeout` on a `Config`.

func OptDatabase

func OptDatabase(database string) Option

OptDatabase sets the `Database` on a `Config`.

func OptDriverName

func OptDriverName(name string) Option

OptDriverName sets the `DriverName` on a `Config`.

func OptHost

func OptHost(host string) Option

OptHost sets the `Host` on a `Config`.

func OptIdleConnections

func OptIdleConnections(count int) Option

OptIdleConnections sets the `IdleConnections` on a `Config`.

func OptLockTimeout

func OptLockTimeout(d time.Duration) Option

OptLockTimeout sets the `LockTimeout` on a `Config`.

func OptMaxConnections

func OptMaxConnections(count int) Option

OptMaxConnections sets the `MaxConnections` on a `Config`.

func OptMaxLifetime

func OptMaxLifetime(d time.Duration) Option

OptMaxLifetime sets the `MaxLifetime` on a `Config`.

func OptPassword

func OptPassword(password string) Option

OptPassword sets the `Password` on a `Config`.

func OptPort

func OptPort(port string) Option

OptPort sets the `Port` on a `Config`.

func OptSSLMode

func OptSSLMode(sslMode string) Option

OptSSLMode sets the `SSLMode` on a `Config`.

func OptSchema

func OptSchema(schema string) Option

OptSchema sets the `Schema` on a `Config`.

func OptStatementTimeout

func OptStatementTimeout(d time.Duration) Option

OptStatementTimeout sets the `StatementTimeout` on a `Config`.

func OptUsername

func OptUsername(username string) Option

OptUsername sets the `Username` on a `Config`.

type SQLProvider

type SQLProvider struct {
	Config *Config
}

SQLProvider is a PostgreSQL-specific database engine provider.

func New

func New(opts ...Option) (*SQLProvider, error)

New creates a PostgreSQL-specific database engine provider from some options.

func (*SQLProvider) NewCreateTableParameters

func (*SQLProvider) NewCreateTableParameters() golembic.CreateTableParameters

NewCreateTableParameters produces the SQL expressions used in the the `CREATE TABLE` statement used to create the migrations table.

func (*SQLProvider) Open

func (sp *SQLProvider) Open() (*sql.DB, error)

Open creates a database connection pool to a PostgreSQL instance.

func (*SQLProvider) QueryParameter

func (*SQLProvider) QueryParameter(index int) string

QueryParameter produces a placeholder like `$1` for a numbered parameter in a PostgreSQL query.

func (*SQLProvider) QuoteIdentifier

func (*SQLProvider) QuoteIdentifier(name string) string

QuoteIdentifier quotes an identifier, such as a table name, for usage in a query.

func (*SQLProvider) QuoteLiteral

func (*SQLProvider) QuoteLiteral(literal string) string

QuoteLiteral quotes a literal, such as `2023-01-05 15:00:00Z`, for usage in a query.

func (*SQLProvider) TableExistsSQL

func (sp *SQLProvider) TableExistsSQL() string

TableExistsSQL returns a SQL query that can be used to determine if a table exists.

func (*SQLProvider) TimestampColumn

func (*SQLProvider) TimestampColumn() golembic.TimestampColumn

TimestampColumn produces a value that can be used for reading / writing a `TIMESTAMP` column to a `time.Time` in PostgreSQL.