mirror of https://github.com/status-im/migrate.git
add comments for database
This commit is contained in:
parent
e69e0de9c9
commit
2da976155a
|
@ -1,3 +1,7 @@
|
|||
// 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.
|
||||
package database
|
||||
|
||||
import (
|
||||
|
@ -8,7 +12,7 @@ import (
|
|||
)
|
||||
|
||||
var (
|
||||
ErrLocked = fmt.Errorf("unable to acquire lock")
|
||||
ErrLocked = fmt.Errorf("can't acquire lock")
|
||||
)
|
||||
|
||||
const NilVersion int = -1
|
||||
|
@ -16,27 +20,47 @@ const NilVersion int = -1
|
|||
var driversMu sync.RWMutex
|
||||
var drivers = make(map[string]Driver)
|
||||
|
||||
// Driver is an interface every driver must implement.
|
||||
// The driver implementation must pass the `Test` in database/testing.
|
||||
// Optionally provide a `WithInstance` function, so users can bypass `Open`
|
||||
// and use an existing database instance.
|
||||
//
|
||||
// Implementations must not assume things nor try to correct user input.
|
||||
// If in doubt, return an error.
|
||||
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.
|
||||
Lock() error
|
||||
|
||||
// Unlock should release the lock. Migrate will call this function after
|
||||
// all migrations have been run.
|
||||
Unlock() error
|
||||
|
||||
// when version = NilVersion, "deinitialize"
|
||||
// migration can be nil, in that case, just store version
|
||||
// Run applies a migration to the database. Run the migration and store
|
||||
// the version. migration can be nil. In that case, just store the version.
|
||||
// When version -1 is given, the state should be as if no migration had been run.
|
||||
Run(version int, migration io.Reader) error
|
||||
|
||||
// version > 0: regular version
|
||||
// version -1: nil version (const NilVersion)
|
||||
// version < -1: will panic
|
||||
// Version returns the currently active version.
|
||||
// When no migration has been run yet, it must return -1.
|
||||
// If the returned version is < -1 it will panic (in the test).
|
||||
Version() (int, error)
|
||||
|
||||
// Drop deletes everyting in the database.
|
||||
Drop() error
|
||||
}
|
||||
|
||||
// Open returns a new driver instance.
|
||||
func Open(url string) (Driver, error) {
|
||||
u, err := nurl.Parse(url)
|
||||
if err != nil {
|
||||
|
@ -57,6 +81,7 @@ func Open(url string) (Driver, error) {
|
|||
return d.Open(url)
|
||||
}
|
||||
|
||||
// Register globally registers a driver.
|
||||
func Register(name string, driver Driver) {
|
||||
driversMu.Lock()
|
||||
defer driversMu.Unlock()
|
||||
|
|
|
@ -0,0 +1,8 @@
|
|||
package database
|
||||
|
||||
func ExampleDriver() {
|
||||
// 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
|
||||
}
|
Loading…
Reference in New Issue