dbutil

Documentation

Index

• Constants
• Variables
• func CloseAllConnections(ctx context.Context, conn *db.Connection, databaseName string) error
• func CreateDatabase(ctx context.Context, name string, opts ...db.Option) (err error)
• func CreateDatabaseIfNotExists(ctx context.Context, database string, opts ...db.Option) error
• func DatabaseExists(ctx context.Context, name string, opts ...db.Option) (exists bool, err error)
• func DropDatabase(ctx context.Context, name string, opts ...db.Option) (err error)
• func OpenManagementConnection(options ...db.Option) (*db.Connection, error)
• func PoolCloseFinalizer(pool *db.Connection, err error) error
• func ValidateDatabaseName(name string) error
• type BaseManager
  • func NewBaseManager(conn *db.Connection, opts ...db.InvocationOption) BaseManager
  • func (m BaseManager) Invoke(ctx context.Context, opts ...db.InvocationOption) *db.Invocation
• type QueryFormatter
  • func (qf *QueryFormatter) FormatQuery(body string, vars any) (output string, err error)
  • func (qf *QueryFormatter) Initialize() *QueryFormatter
  • func (qf *QueryFormatter) MustFormat(body string, vars any) (output string)
  • func (qf *QueryFormatter) WithFunc(name string, fn any) *QueryFormatter
  • func (qf *QueryFormatter) WithModels(models ...any) *QueryFormatter
  • func (qf *QueryFormatter) WithTemplates(templates ...string) *QueryFormatter

Constants

const (
	// DatabaseNameMaxLength is the maximum length of a database name.
	DatabaseNameMaxLength = 63
)

Variables

var (
	// ErrDatabaseNameReserved is a validation failure.
	ErrDatabaseNameReserved = errors.New("dbutil; database name is reserved")
	// ErrDatabaseNameEmpty is a validation failure.
	ErrDatabaseNameEmpty = errors.New("dbutil; database name is empty")
	// ErrDatabaseNameInvalidFirstRune is a validation failure.
	ErrDatabaseNameInvalidFirstRune = errors.New("dbutil; database name must start with a letter or underscore")
	// ErrDatabaseNameInvalid is a validation failure.
	ErrDatabaseNameInvalid = errors.New("dbutil; database name must be composed of (in regex form) [a-zA-Z0-9_]")
	// ErrDatabaseNameTooLong is a validation failure.
	ErrDatabaseNameTooLong = errors.New("dbutil; database name must be 63 characters or fewer")
)

var (
	ErrDatabaseDoesntExist = errors.New("pgutil; database doesnt exist")
)

Error constants

var (
	// ReservedDatabaseNames are names you cannot use to create a database with.
	ReservedDatabaseNames = []string{
		"postgres",
		"defaultdb",
		"template0",
		"template1",
	}
)

Functions

func CloseAllConnections

func CloseAllConnections(ctx context.Context, conn *db.Connection, databaseName string) error

CloseAllConnections closes all other connections to a database.

func CreateDatabase

func CreateDatabase(ctx context.Context, name string, opts ...db.Option) (err error)

CreateDatabase creates a database with a given name.

Note: the `name` parameter is passed to the statement directly (not via. a parameter). You should use extreme care to not pass user submitted inputs to this function.

func CreateDatabaseIfNotExists

func CreateDatabaseIfNotExists(ctx context.Context, database string, opts ...db.Option) error

CreateDatabaseIfNotExists creates a databse if it doesn't exist.

It will check if a given `serviceEnv` is prodlike, and if the database doesn't exist, and the `serviceEnv` is prodlike, an `ErrDatabaseDoesntExist` will be returned.

If a given `serviceEnv` is not prodlike, the database will be created with a management connection.

func DatabaseExists

func DatabaseExists(ctx context.Context, name string, opts ...db.Option) (exists bool, err error)

DatabaseExists returns if a database exists or not.

func DropDatabase

func DropDatabase(ctx context.Context, name string, opts ...db.Option) (err error)

DropDatabase drops a database.

func OpenManagementConnection

func OpenManagementConnection(options ...db.Option) (*db.Connection, error)

OpenManagementConnection creates a database connection to the default database (typically postgres).

func PoolCloseFinalizer

func PoolCloseFinalizer(pool *db.Connection, err error) error

PoolCloseFinalizer is intended to be used in `defer` blocks with a named `error` return. It ensures a pool is closed after usage in contexts where a "limited use" pool is created.

> func queries() (err error) { > var pool *db.Connection > defer func() { > err = db.PoolCloseFinalizer(pool, err) > }() > // ... > }

func ValidateDatabaseName

func ValidateDatabaseName(name string) error

ValidateDatabaseName validates a database name.

Types

type BaseManager

type BaseManager struct {
	Conn    *db.Connection
	Options []db.InvocationOption
}

BaseManager is the manager for database tasks.

It is a base type you can use to build your own models that provides an `Invoke` method that will add default invocation options to a given invocation.

func NewBaseManager

func NewBaseManager(conn *db.Connection, opts ...db.InvocationOption) BaseManager

NewBaseManager creates a new manager.

func (BaseManager) Invoke

func (m BaseManager) Invoke(ctx context.Context, opts ...db.InvocationOption) *db.Invocation

Invoke runs a command with a given set of options merged with the manager defaults.

type QueryFormatter

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

QueryFormatter is a type that can format queries.

func (*QueryFormatter) FormatQuery

func (qf *QueryFormatter) FormatQuery(body string, vars any) (output string, err error)

FormatQuery formats a query with a given variadic set of options.

func (*QueryFormatter) Initialize

func (qf *QueryFormatter) Initialize() *QueryFormatter

func (*QueryFormatter) MustFormat

func (qf *QueryFormatter) MustFormat(body string, vars any) (output string)

MustFormatQuery formats a query with a given variadic set of options and panics on error.

func (*QueryFormatter) WithFunc

func (qf *QueryFormatter) WithFunc(name string, fn any) *QueryFormatter

WithFunc adds a view func to the formatter.

func (*QueryFormatter) WithModels

func (qf *QueryFormatter) WithModels(models ...any) *QueryFormatter

WithModels registers model types for use in view func helpers.

func (*QueryFormatter) WithTemplates

func (qf *QueryFormatter) WithTemplates(templates ...string) *QueryFormatter

WithTemplates adds snippets or template to the formatter.