Package database

Constants

const NilVersion int = -1

Variables

var (
    ErrLocked    = fmt.Errorf("can't acquire lock")
    ErrNotLocked = fmt.Errorf("can't unlock, as not currently locked")
)

func CasRestoreOnErr ¶

func CasRestoreOnErr(lock *atomic.Bool, o, n bool, casErr error, f func() error) error

CasRestoreOnErr CAS wrapper to automatically restore the lock state on error

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.

type Driver ¶

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 internal/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().

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 guaranteed 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.
    // Note that this is a breaking action, a new call to Open() is necessary to
    // ensure subsequent calls work as expected.
    Drop() error
}

// 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

func Open ¶

func Open(url string) (Driver, error)

Open returns a new driver instance.

type Error ¶

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

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
}

func (Error) Error ¶

func (e Error) Error() string

Subdirectories