testdb

type Db interface {
	// The Name of the test database.
	Name() string
	// Dsn is the data source name of the test database; a connection string.
	Dsn() string
	// Insert will insert the provided data into table within the test database.
	// Each data is expected to be a col => val mapping.
	// For convenience, multiple data entries may be provided; each will be inserted
	// separate as a new row.
	Insert(t testing.TB, table string, data ...map[string]any)
	// QueryValue will runs sql with args, writing a single value back to into. Provide
	// a pointer for into.
	QueryValue(t testing.TB, sql string, into any, args ...any)
	// QueryRow will scan the results of the first row of a query in to the pointer values
	// provided in the returned func. This will fatal the test if there is error scanning
	// in to the provided values, or if there are 0 rows.
	QueryRow(t testing.TB, sql string, args ...any) func(into ...any)
	// Exec applies arbitrary SQL commands on this test database. If the command produces
	// an error, the test will error.
	Exec(t testing.TB, sql string, args ...any) ExecResult
	// Drop forcefully removes the database. This is automatically done as part of database
	// cleanup.
	Drop(t testing.TB)
}

type ExecResult struct {
	RowsAffected int64
}

type Initializer[Conn any] interface {
	// Connect returns an active connection to the provided DSN.
	Connect(t testing.TB, dsn string) Conn

	// Lock provides some protection against concurrent migration application for parallel
	// tests. This should ensure that only one testdb initialization is happening. Should
	// lock against the provided name. This may be done with stdlib sync stuff, or better
	// yet, at the database itself if possible.
	// This will block until the lock is acquired.
	Lock(t testing.TB, conn Conn, name string)

	// Unlock releases the lock acquired in Lock.
	Unlock(t testing.TB, conn Conn, name string)

	// Exists checks if the database with name exists in the database already.
	Exists(t testing.TB, conn Conn, name string) bool

	// Create a new blank database with the given name.
	Create(t testing.TB, conn Conn, name string)

	// CreateFromTemplate creates a new database with name, using a template database
	// with name template.
	CreateFromTemplate(t testing.TB, conn Conn, template, name string)

	// NewDsn takes a base DSN and returns a new one with the given newName
	// as the database name. This will override the dbname portion of dsn
	// with the new name.
	NewDsn(t testing.TB, base string, newName string) string

	// NewDb creates a new Db. rootDsn is the connection to the database
	// used to manage database creation etc.; dsn is the connection string
	// for the newly-created test database.
	NewDb(t testing.TB, rootDsn, dsn string) Db

	// Remove removes the database given by name entirely using the provided
	// root connection.
	Remove(t testing.TB, conn Conn, name string)

	// Close a connection once we're done with.
	Close(conn Conn)
}

type Migrator interface {
	// Hash the current state of migrations. This should return a different value
	// any time the migration definitions are changed. Commonly, this involves hashing
	// the contents of a migrations directory.
	Hash(t testing.TB) string
	// Migrate applies the current migrations to the provided dsn (data source name).
	Migrate(t testing.TB, dsn string)
}

type Options struct {
	// TemplateNameStr is used when creating template databases. You can use this to
	// customise the name of template databases that are created. This must include
	// %s which will be replaced by a unique ID generated by this package.
	TemplateNameStr string
	// DatabaseNameStr is used when creating test databases. You can use this to
	// customise the name of the databases used for tests. This must include
	// %s which will be replaced by a unique ID generated by this package.
	DatabaseNameStr string
}

type PgDb struct {
	// contains filtered or unexported fields
}