sqltest

README

SQL Testing Utilities

This is a Go library containing utilities that help when writing tests that use real SQL database servers.

It is only intended for use as a test dependencies for projects within the Dogmatiq organization.

The primary feature is the OpenTemporary() function which creates a temporary database that can be discarded at the end of each test.

Database Products

The database products in the table below are currently supported. Some products are supported via multiple different Go SQL drivers.

Each of these databases can be started using the provided Docker stack, and/or started within each project's Github Actions workflow. This project's CI workflow serves as an example of how to start each product under Github Actions.

Product	Supported Drivers	Notes
MySQL	mysql
MariaDB	mysql
PostgreSQL	pgx (preferred), postgres
SQLite	sqlite3	Embedded database, requires CGO

Documentation

Overview

Package sqltest contains internal utilities for testing Dogma projects that use SQL databases.

Index

• type DataSource
• type Database
  • func NewDatabase(ctx context.Context, d Driver, p Product) (_ *Database, err error)
  • func (db *Database) Close() error
  • func (db *Database) Open() (*sql.DB, error)
• type Driver
• type MultiDatabaseProduct
• type MySQLCompatibleProduct
  • func (MySQLCompatibleProduct) CreateDatabase(ctx context.Context, db *sql.DB, name string) error
  • func (p MySQLCompatibleProduct) DefaultDataSource(d Driver) (DataSource, error)
  • func (MySQLCompatibleProduct) DropDatabase(ctx context.Context, db *sql.DB, name string) error
  • func (p MySQLCompatibleProduct) IsCompatibleWith(d Driver) bool
  • func (p MySQLCompatibleProduct) Name() string
• type MySQLProtocol
• type Pair
  • func CompatiblePairs(products ...Product) []Pair
• type PostgresCompatibleProduct
  • func (PostgresCompatibleProduct) CreateDatabase(ctx context.Context, db *sql.DB, name string) error
  • func (p PostgresCompatibleProduct) DefaultDataSource(d Driver) (DataSource, error)
  • func (PostgresCompatibleProduct) DropDatabase(ctx context.Context, db *sql.DB, name string) error
  • func (p PostgresCompatibleProduct) IsCompatibleWith(d Driver) bool
  • func (p PostgresCompatibleProduct) Name() string
• type PostgresProtocol
• type Product
• type SQLiteProtocol

Types

type DataSource

type DataSource interface {
	// DriverName returns the name of the driver as used with sql.Open().
	DriverName() string

	// DSN returns the DSN string as used with sql.Open().
	DSN() string

	// DatabaseName returns the name of the database within the data source.
	DatabaseName() string

	// WithDatabaseName returns a clone of this data source that connects to a
	// different database.
	WithDatabaseName(name string) DataSource

	// Close releases any resources associated with the data source.
	Close() error
}

DataSource is a DSN tied to a specific driver.

type Database

type Database struct {
	Driver     Driver
	Product    Product
	DataSource DataSource
	// contains filtered or unexported fields
}

Database is a database created for the purposes of testing.

func NewDatabase

func NewDatabase(
	ctx context.Context,
	d Driver,
	p Product,
) (_ *Database, err error)

NewDatabase returns a new temporary test database for a specific pair of database product and SQL driver.

The returned Database is an io.Closer that must be closed when the database is no longer needed. It is safe to close the Database even if this function returns an error.

func (*Database) Close

func (db *Database) Close() error

Close releases any resources associated with the DSN.

func (*Database) Open

func (db *Database) Open() (*sql.DB, error)

Open returns a database pool that connects to this database.

The pool is closed when db.Close() is called.

type Driver

type Driver interface {
	// Name returns the name of the driver, as passed to sql.Open().
	Name() string

	// IsAvailable returns true if this driver is available for use.
	IsAvailable() bool

	// ParseDSN parses a DSN. It returns an error if this DSN string is not
	// compatible with this driver.
	ParseDSN(dsn string) (DataSource, error)
}

Driver is an interface for using a specific SQL driver with multiple database products.

var (
	// MySQLDriver is the "mysql" driver (https://github.com/go-sql-driver/mysql).
	MySQLDriver Driver = mysqlDriver{}

	// PGXDriver is the "pgx" driver (https://github.com/jackc/pgx).
	PGXDriver Driver = pgxDriver{}

	// PostgresDriver is the "postgres" driver (https://github.com/lib/pq).
	PostgresDriver Driver = postgresDriver{}

	// SQLite3Driver is the "sqlite3" driver (github.com/mattn/go-sqlite3).
	SQLite3Driver Driver = sqlite3Driver{}

	// Drivers is a slice containing all known products.
	Drivers = []Driver{
		MySQLDriver,
		PGXDriver,
		PostgresDriver,
		SQLite3Driver,
	}
)

type MultiDatabaseProduct

type MultiDatabaseProduct interface {
	Product

	// CreateDatabase creates a new database with the given name.
	CreateDatabase(ctx context.Context, db *sql.DB, name string) error

	// DropDatabase drops the database with the given name.
	DropDatabase(ctx context.Context, db *sql.DB, name string) error
}

MultiDatabaseProduct is a product that supports multiple databases on the same "server" or endpoint.

type MySQLCompatibleProduct

type MySQLCompatibleProduct struct {
	ProductName string
	DefaultPort string
}

MySQLCompatibleProduct is a Product that is compatible with MySQL.

func (MySQLCompatibleProduct) CreateDatabase

func (MySQLCompatibleProduct) CreateDatabase(
	ctx context.Context,
	db *sql.DB,
	name string,
) error

CreateDatabase creates a new database with the given name.

func (MySQLCompatibleProduct) DefaultDataSource

func (p MySQLCompatibleProduct) DefaultDataSource(d Driver) (DataSource, error)

DefaultDataSource returns the default data source to use to connect to the product.

func (MySQLCompatibleProduct) DropDatabase

func (MySQLCompatibleProduct) DropDatabase(
	ctx context.Context,
	db *sql.DB,
	name string,
) error

DropDatabase drops the database with the given name.

func (MySQLCompatibleProduct) IsCompatibleWith

func (p MySQLCompatibleProduct) IsCompatibleWith(d Driver) bool

IsCompatibleWith return true if the product is compatible with d.

func (MySQLCompatibleProduct) Name

func (p MySQLCompatibleProduct) Name() string

Name returns the human-readable name of the product.

type MySQLProtocol

type MySQLProtocol interface {
	DataSourceForMySQL(
		user, pass,
		host, port,
		database string,
	) (DataSource, error)
}

MySQLProtocol is an interface for drivers that use the MySQL wire protocol.

type Pair

type Pair struct {
	Driver  Driver
	Product Product
}

Pair is a struct containing a driver and product that are compatible with each other.

func CompatiblePairs

func CompatiblePairs(products ...Product) []Pair

CompatiblePairs returns all compatible driver/product pairs for the given set of products.

If no products are provided compatible pairs are given for all products.

type PostgresCompatibleProduct

type PostgresCompatibleProduct struct {
	ProductName string
	DefaultPort string
}

PostgresCompatibleProduct is a Product that is compatible with PostgreSQL.

func (PostgresCompatibleProduct) CreateDatabase

func (PostgresCompatibleProduct) CreateDatabase(
	ctx context.Context,
	db *sql.DB,
	name string,
) error

CreateDatabase creates a new database with the given name.

func (PostgresCompatibleProduct) DefaultDataSource

func (p PostgresCompatibleProduct) DefaultDataSource(d Driver) (DataSource, error)

DefaultDataSource returns the default data source to use to connect to the product.

func (PostgresCompatibleProduct) DropDatabase

func (PostgresCompatibleProduct) DropDatabase(
	ctx context.Context,
	db *sql.DB,
	name string,
) error

DropDatabase drops the database with the given name.

func (PostgresCompatibleProduct) IsCompatibleWith

func (p PostgresCompatibleProduct) IsCompatibleWith(d Driver) bool

IsCompatibleWith return true if the product is compatible with d.

func (PostgresCompatibleProduct) Name

func (p PostgresCompatibleProduct) Name() string

Name returns the human-readable name of the product.

type PostgresProtocol

type PostgresProtocol interface {
	DataSourceForPostgres(
		user, pass,
		host, port,
		database string,
	) (DataSource, error)
}

PostgresProtocol is an interface for drivers that use the PostgreSQL wire protocol.

type Product

type Product interface {
	// Name returns the human-readable name of the product.
	Name() string

	// IsCompatibleWith return true if the product is compatible with d.
	IsCompatibleWith(d Driver) bool

	// DefaultDataSource returns the default data source to use to connect to
	// the product.
	//
	// The returned data source must contain enough information to connect to
	// the product when running under the sqltest Docker stack or under a CI
	// workflow.
	//
	// d is the driver that is being used to connect to the product. If the
	// driver can not be used to connect to this product it returns
	// ErrIncompatibleDriver.
	DefaultDataSource(d Driver) (DataSource, error)
}

Product is a specific database product such as MySQL or MariaDB.

The product correlates with a running service that tests are run against. Many products share a common wire protocol or are even entirely compatible.

var (
	// MySQL is the Product for MySQL (https://www.mysql.com).
	MySQL Product = MySQLCompatibleProduct{
		ProductName: "MySQL",
		DefaultPort: "23306",
	}

	// MariaDB is the Product for MariaDB (https://mariadb.org).
	MariaDB Product = MySQLCompatibleProduct{
		ProductName: "MariaDB",
		DefaultPort: "23307",
	}

	// PostgreSQL is the Product for PostgreSQL (https://www.postgresql.org).
	PostgreSQL Product = PostgresCompatibleProduct{
		ProductName: "PostgreSQL",
		DefaultPort: "25432",
	}

	// SQLite is the Product for SQLite (https://www.sqlite.org).
	SQLite Product = sqliteProduct{}

	// Products is a slice containing all known products.
	Products = []Product{
		MySQL,
		MariaDB,
		PostgreSQL,
		SQLite,
	}
)

type SQLiteProtocol

type SQLiteProtocol interface {
	DataSourceForSQLite(filename string) (DataSource, error)
}

SQLiteProtocol is an interface for drivers that use SQLite 3 database files.