database

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 30, 2019 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package database provides the Database interface. All database drivers must implement this interface, register themselves, optionally provide a `WithInstance` function and pass the tests in package database/testing.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrLocked should be returned if a lock cannot be required on the database
	// when requested.
	ErrLocked = fmt.Errorf("can't acquire lock")
)

Functions

func GenerateAdvisoryLockId

func GenerateAdvisoryLockId(databaseName string, additionalNames ...string) (string, error)

GenerateAdvisoryLockId inspired by rails migrations, see https://goo.gl/8o9bCT

func List

func List() []string

List lists the registered drivers

func Register

func Register(name string, driver Driver)

Register globally registers a driver.

Types

type Driver

type Driver interface {
	// Open returns a new driver instance configured with parameters
	// coming from the URL string. Migrate will call this function
	// only once per instance.
	Open(url string) (Driver, error)

	// Close closes the underlying database instance managed by the driver.
	// Migrate will call this function only once per instance.
	Close() error

	// Lock should acquire a database lock to control concurrency if required by
	// the application.
	Lock() error

	// Unlock should release the lock. Applications should call this when they
	// have completed interacting with the driver.
	Unlock() error

	// Begin should begin a transaction in the database. It should return an error if there is
	// already an active transaction in the database.
	Begin() error

	// Rollback should rollback a transaction in the database. It should return an error
	// if there is currently no active transaction.
	Rollback() error

	// Commit should commit the active transaction in the database. It should return an error
	// if there is currently no active transaction.
	Commit() error

	// Execute should execute the given command against the database.
	Exec(command io.Reader, params ...interface{}) error

	// ImportCSV imports a csv file into the database.
	ImportCSV(filePath, schemaName, tableName, delimiter string, header bool) error
}

Driver is the interface every database driver must implement.

How to implement a database driver?

  1. Implement this interface.
  2. Optionally, add a function named `WithInstance`. This function should accept an existing DB instance and a Config{} struct and return a driver instance.
  3. Add a test that calls database/testing.go:Test()
  4. Add own tests for Open(), WithInstance() (when provided) and Close(). All other functions are tested by tests in database/testing. Saves you some time and makes sure all database drivers behave the same way.
  5. Call Register in init().
  6. Create a migrate/cli/build_<driver-name>.go file
  7. Add driver name in 'DATABASE' variable in Makefile

Guidelines:

  • Don't try to correct user input. Don't assume things. When in doubt, return an error and explain the situation to the user.
  • All configuration input must come from the URL string in func Open() or the Config{} struct in WithInstance. Don't os.Getenv().

func Open

func Open(url string) (Driver, error)

Open returns a new driver instance.

type Error

type Error struct {
	// Optional: the line number
	Line uint

	// Query is a query excerpt
	Query []byte

	// Err is a useful/helping error message for humans
	Err string

	// OrigErr is the underlying error
	OrigErr error
}

Error should be used for errors involving queries ran against the database

func (Error) Error

func (e Error) Error() string

Directories

Path Synopsis
Package testing has the database tests.
Package testing has the database tests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL