database

package
v3.1.0+incompatible Latest Latest
Warning

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

Go to latest
Published: Jan 21, 2018 License: MIT Imports: 5 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

Examples

Constants

View Source
const NilVersion int = -1

Variables

View Source
var (
	ErrLocked = fmt.Errorf("can't acquire lock")
)

Functions

func GenerateAdvisoryLockId

func GenerateAdvisoryLockId(databaseName string) (string, error)

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

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 so that only one migration process
	// can run at a time. Migrate will call this function before Run is called.
	// If the implementation can't provide this functionality, return nil.
	// Return database.ErrLocked if database is already locked.
	Lock() error

	// Unlock should release the lock. Migrate will call this function after
	// all migrations have been run.
	Unlock() error

	// Run applies a migration to the database. migration is garantueed to be not nil.
	Run(migration io.Reader) error

	// SetVersion saves version and dirty state.
	// Migrate will call this function before and after each call to Run.
	// version must be >= -1. -1 means NilVersion.
	SetVersion(version int, dirty bool) error

	// Version returns the currently active version and if the database is dirty.
	// When no migration has been applied, it must return version -1.
	// Dirty means, a previous migration failed and user interaction is required.
	Version() (version int, dirty bool, err error)

	// Drop deletes everything in the database.
	Drop() 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().
Example
// see database/stub for an example

// database/stub/stub.go has the driver implementation
// database/stub/stub_test.go runs database/testing/test.go:Test
Output:

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