package database

Import Path
	github.com/golang-migrate/migrate/v4/database (on go.dev)

Dependency Relation
	imports 6 packages, and imported by 2 packages

Involved Source Files

	   d➜ driver.go
		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.

	      error.go
	      util.go
Package-Level Type Names (total 2, both are exported)

	/* sort exporteds by: alphabet | popularity */
	 type Driver (interface)
		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().

		Methods (total 8, all are exported)
			( T) Close() error
				Close closes the underlying database instance managed by the driver.
				Migrate will call this function only once per instance.

			( T) Drop() 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.

			( T) Lock() 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.

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

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

			( T) SetVersion(version int, dirty bool) 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.

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

			( T) Version() (version int, dirty bool, err 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.

		Implemented By (at least one exported)
			*github.com/golang-migrate/migrate/v4/database/postgres.Postgres
		Implements (at least one exported)
			 T : io.Closer
		As Outputs Of (at least 4, all are exported)
			func Open(url string) (Driver, error)
			func Driver.Open(url string) (Driver, error)
			func github.com/golang-migrate/migrate/v4/database/postgres.WithInstance(instance *sql.DB, config *postgres.Config) (Driver, error)
			func github.com/golang-migrate/migrate/v4/database/postgres.(*Postgres).Open(url string) (Driver, error)
		As Inputs Of (at least 3, all are exported)
			func Register(name string, driver Driver)
			func github.com/golang-migrate/migrate/v4.NewWithDatabaseInstance(sourceURL string, databaseName string, databaseInstance Driver) (*migrate.Migrate, error)
			func github.com/golang-migrate/migrate/v4.NewWithInstance(sourceName string, sourceInstance source.Driver, databaseName string, databaseInstance Driver) (*migrate.Migrate, error)

	 type Error (struct)
		Error should be used for errors involving queries ran against the database

		Fields (total 4, all are exported)
			Err string
				Err is a useful/helping error message for humans

			Line uint
				Optional: the line number

			OrigErr error
				OrigErr is the underlying error

			Query []byte
				Query is a query excerpt

		Methods (only one, which is exported)
			( T) Error() string
		Implements (at least one exported)
			 T : error


Package-Level Functions (total 4, all are exported)

	 func GenerateAdvisoryLockId(databaseName string, additionalNames ...string) (string, error)
		GenerateAdvisoryLockId inspired by rails migrations, see https://goo.gl/8o9bCT

	 func List() []string
		List lists the registered drivers

	 func Open(url string) (Driver, error)
		Open returns a new driver instance.

	 func Register(name string, driver Driver)
		Register globally registers a driver.


Package-Level Variables (total 3, in which 1 are exported)

	  var ErrLocked error
	/* 2 unexporteds ... *//* 2 unexporteds: */
	  var drivers map[string]Driver
	  var driversMu sync.RWMutex
Package-Level Constants (total 2, in which 1 are exported)

	const NilVersion int = -1
	/* one unexported ... *//* one unexported: */
	const advisoryLockIDSalt uint = 1486364155

The pages are generated with Golds v0.3.2-preview. (GOOS=darwin GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds.