coresql

README

Core SQL

This package is used to wrap the SQL standard library to satisfy the health checking server in the LUSH core service library. We use golang-migrate/migrate version 4 for migrations and treats it as a direct dependency.

Examples

Use in conjunction with readysrv

database := coresql.MustOpen("mysql", "tcp(localhost:3306)/mydb")
readysrv.New(readysrv.Checks{
    "mysql": database,
})

Ensure database is migrated up

_, migrations := coresql.MustOpenWithMigrations("mysql", "tcp(localhost:3306)/mydb", "file://path/to/migrations")
coresql.MustMigrateUp(migrations)

Handle migration arguments

You can force your application to respect migration command line arguments:

• migrate up: attempt to migrate up
• migrate down: attempt to migrate down

_, migrations := coresql.MustOpenWithMigrations("mysql", "tcp(localhost:3306)/mydb", "file://path/to/migrations")
coresql.HandleMigrationArgs(migrations)

Documentation

Index

• Constants
• func CockroachURLFromEnv() string
• func HandleMigrationArgs(mig Migrate)
• func MustMigrateUp(mig Migrate)
• func MustOpenMigration(driverName, dsn, sourceURL string) *migrate.Migrate
• func MySQLURLFromEnv() string
• func OpenMigration(driverName, dsn, sourceURL string) (*migrate.Migrate, error)
• type Agent
• type Connector
• type DB
  • func MustOpen(driverName, dsn string) *DB
  • func MustOpenCockroachWithMigration(dsn, sourceURL string) (*DB, *migrate.Migrate)
  • func MustOpenWithMigrations(driverName, dsn, sourceURL string) (*DB, *migrate.Migrate)
  • func Open(driverName, dsn string) (*DB, error)
  • func OpenCockroachWithMigration(dsn, sourceURL string) (*DB, *migrate.Migrate, error)
  • func OpenWithMigrations(driverName, dsn, sourceURL string) (*DB, *migrate.Migrate, error)
  • func (db *DB) Check() ([]string, bool)
  • func (db *DB) MustWait()
  • func (db *DB) Wait() error
• type Executor
• type Migrate
• type Operator
• type Pinger
• type Preparer
• type Querier
• type Transactor

Constants

const (
	// DefaultCockroachURL is the default url to a CockroachDB database.
	DefaultCockroachURL = "tcp(127.0.0.1:26257)/defaultdb"
)

const (
	// DefaultMySQLURL is the default url to a MYSQL database.
	DefaultMySQLURL = "tcp(127.0.0.1:3306)/service"
)

Functions

func CockroachURLFromEnv

func CockroachURLFromEnv() string

CockroachURLFromEnv tries to retrieve the cockroach url from the environment.

func HandleMigrationArgs

func HandleMigrationArgs(mig Migrate)

HandleMigrationArgs should be invoked to handle command line arguments for running migrations.

func MustMigrateUp

func MustMigrateUp(mig Migrate)

MustMigrateUp will attempt to migrate your database up.

func MustOpenMigration

func MustOpenMigration(driverName, dsn, sourceURL string) *migrate.Migrate

MustOpenMigration will open a migration instance with and crashes if unsuccessful.

func MySQLURLFromEnv

func MySQLURLFromEnv() string

MySQLURLFromEnv tries to retrieve the redis url from the environment.

func OpenMigration

func OpenMigration(driverName, dsn, sourceURL string) (*migrate.Migrate, error)

OpenMigration will open a migration instance.

Types

type Agent

type Agent interface {
	Preparer
	Transactor
	Executor
	Querier
}

Agent defines a common set of methods for interacting with the data in an SQL database.

type Connector

type Connector interface {
	Driver() driver.Driver
	SetMaxIdleConns(n int)
	SetMaxOpenConns(n int)
	SetConnMaxLifetime(d time.Duration)
	Conn(ctx context.Context) (*sql.Conn, error)
	Stats() sql.DBStats
}

Connector defines a common set of methods for dealing with the connection to an SQL database.

type DB

type DB struct {
	*sql.DB
}

DB represents a wrapper for SQL DB providing extra methods.

func MustOpen

func MustOpen(driverName, dsn string) *DB

MustOpen will crash your program unless a database could be retrieved.

func MustOpenCockroachWithMigration

func MustOpenCockroachWithMigration(dsn, sourceURL string) (*DB, *migrate.Migrate)

MustOpenCockroachWithMigration opens a cockroach database connection with an associated migration instance and craches if the connection cannot be obtained. This assumes you use a postgres driver like https://github.com/lib/pq to interact with your postgres database.

func MustOpenWithMigrations

func MustOpenWithMigrations(driverName, dsn, sourceURL string) (*DB, *migrate.Migrate)

MustOpenWithMigrations opens a database connection with an associated migration instance and crashes if unsuccessful.

func Open

func Open(driverName, dsn string) (*DB, error)

Open will attempt to open a new database connection.

func OpenCockroachWithMigration

func OpenCockroachWithMigration(dsn, sourceURL string) (*DB, *migrate.Migrate, error)

OpenCockroachWithMigration opens a cockroach database connection with an associated migration instance. This assumes you use a postgres driver like https://github.com/lib/pq to interact with your postgres database.

func OpenWithMigrations

func OpenWithMigrations(driverName, dsn, sourceURL string) (*DB, *migrate.Migrate, error)

OpenWithMigrations opens a database connection with an associated migration instance.

func (*DB) Check

func (db *DB) Check() ([]string, bool)

Check will attempt to ping the database to see if the connection is still alive.

func (*DB) MustWait

func (db *DB) MustWait()

MustWait will call the Wait method and crash if it cant be performed.

func (*DB) Wait

func (db *DB) Wait() error

Wait will attempt to connect to a database and block until it connects.

type Executor

type Executor interface {
	ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)
	Exec(query string, args ...interface{}) (sql.Result, error)
}

Executor defines a common set of methods for executing stored procedures, statements or queries.

type Migrate

type Migrate interface {
	Up() error
	Down() error
}

Migrate represents functionality for

type Operator

type Operator interface {
	Pinger
	Connector
}

Operator defines a common set of methods for operating a connection with an SQL database.

type Pinger

type Pinger interface {
	PingContext(ctx context.Context) error
	Ping() error
}

Pinger defines a common set of methods for pinging an SQL database.

type Preparer

type Preparer interface {
	PrepareContext(ctx context.Context, query string) (*sql.Stmt, error)
	Prepare(query string) (*sql.Stmt, error)
}

Preparer defines a common set of methods for preparing statements in an SQL database.

type Querier

type Querier interface {
	QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)
	Query(query string, args ...interface{}) (*sql.Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...interface{}) *sql.Row
	QueryRow(query string, args ...interface{}) *sql.Row
}

Querier defines a common set of methods for querying an SQL database.

type Transactor

type Transactor interface {
	BeginTx(ctx context.Context, opts *sql.TxOptions) (*sql.Tx, error)
	Begin() (*sql.Tx, error)
}

Transactor defines a common set of methods for working with database transactions.