datarepo

type AppTableSetter interface {
	// SetAppTables specifies the schemata of the specified app's
	// tables, which this interface creates and/or manages.
	//  - Multiple calls, whether with tables previously specified
	//    or not before seen do not conflict
	//  - If a table name is repeated but with a different schema,
	//    the result is undefined
	//  - If the tables already exist in the DB, it is not verified
	//    that their structure matches what this schema specifies
	SetAppTables(string, []DRM.TableDetails) error
	// EmptyAllTables deletes (app-level) data from the app's tables
	// but does not delete any tables (i.e. no DROP TABLE are done).
	EmptyAppTables() error
	// CreateTables creates the app's tables per already-supplied
	// schema(ta); if the tables exist, they are emptied of data.
	CreateAppTables() error
}

type Backupable interface {
	MoveToBackup() (string, error)
	CopyToBackup() (string, error)
	RestoreFromMostRecentBackup() (string, error)
}

type DBManager interface {
	// OpenAtPath should be
	// OpenAtPath(string) (SimpleRepo, error) // recommended
	OpenAtPath(string) (*sqlite.SqliteRepo, error) // recommended
	// NewAtPath should be
	// NewAtPath(string) (SimpleRepo, error)
	NewAtPath(string) (*sqlite.SqliteRepo, error)
	// OpenExistingAtPath should be
	// OpenExistingAtPath(string) (SimpleRepo, error)
	OpenExistingAtPath(string) (*sqlite.SqliteRepo, error)
	// InitznPragmas is assumed to be multiline
	InitznPragmas() string
	// ReadonlyPragma is assumed to be a single pragma that
	// returns some sort of status message
	ReadonlyPragma() string
}

type Entity interface {
	// Handle (noun) is the handle to the DB.
	Handle() *sql.DB
	// Type has value DB_SQLite ("sqlite", equiv.to "sqlite3").
	Type() D.DB_type
	// Path is the file/URL (or dir/URL, if uses multiple files) to the DB.
	Path() string
	// IsURL is false for a local SQLite file.
	IsURL() bool
	// IsSingleFile is true for SQLite.
	IsSingleFile() bool
}

type Init9nArgs struct {
	// D.DB_type is so far only D.DB_SQLite = "sqlite"
	D.DB_type
	// BaseFilename defaults to "m5.db"
	BaseFilename string
	Dir          string
	// LogWriter is (so far) used only by package [datarepo/sqlite]
	// and is initialized to [io.Discard]. If it is an open file, it
	// is passed using func [datarepo/sqlite.SqliteRepo.SetLogWriter].
	// It could actually be just an io.WriterCloser.
	// LogWriter *os.File
	// DoImport requires DB access, so it is present
	// here, but it is not otherwise processed here.
	DoImport bool
	// DoZeroOut says initialize the DB with the
	// app's tables but with no data in them
	DoZeroOut bool
	// DoBackup says before DoingZeroOut on an
	// existing DB, first copy it to a backup
	// copy using a hard-coded naming scheme
	DoBackup bool
	// TableDetailz are app tables' details
	TableDetailz []DRM.TableDetails
}

type QueryRunner interface {
	RunQuery0(*DRU.QuerySpec) (any, error)   // ie. Exec()
	RunQuery1(*DRU.QuerySpec) (any, error)   // One row, like by_ID
	RunQueryN(*DRU.QuerySpec) ([]any, error) // Multiple rows
}

type SessionLifecycler interface {
	// Open is called on an existing repo file, and can be called
	// multiple times in a sessions, so it should not pragma-style
	// initialization; however, options passed in the connection
	// string (such as SQLite's "...?foreign_keys=on") are kosher.
	Open() error
	SetLogWriter(io.Writer) io.Writer
	// DoPragmas is provided mainly for use in initialization,
	// but it is not included by default in any other functions
	// in this interface because of variations in usage of pragmas.
	// It is the therefore the sole responsibility of a caller to
	// determine which pragmas(s) to execute, and when.
	DoPragmas(string) (string, error)
	// IsOpen also pings the DB as a health check.
	IsOpen() bool
	// Verify runs app-level sanity & consistency checks (but things
	// like foreign key integtrity should be delegated to DB setup).
	Verify() error
	Flush() error
	// Close remembers the path (like os.File does).
	Close() error
	CloseLogWriter()
}

type SimpleRepo interface {
	// Implementation is func [DBImplementationName]
	// is currently limited to "sqlite"
	// Implementation
	// Entity is type, path, etc.
	Entity
	// Backupable is copy, move, restoreFrom
	Backupable
	// SessionLifecycler is open, close, etc.
	SessionLifecycler
	// StatementBuilder uses [TableDescriptor] and [QuerySpec]
	StatementBuilder
	// Transactioner is for transactions
	Transactioner

	// QueryRunner is for generics and has funcs that return 0,1,N rows
	QueryRunner

	AppTableSetter
}

type StatementBuilder interface {
	// BuildQueryStmt(*DRU.QuerySpec) (string, error)
	NewCreateTableStmt(*DRM.TableDetails) (string, error)
}

type StatementBuilder_generics[T DRM.RowModel] interface {
	// BuildQueryStmt(*DRU.QuerySpec) (string, error)
	NewCreateTableStmt(T) (string, error)
	NewSelectByIdStmt(T, int) (string, error)
}

type StatementRunner interface {
	ExecInsertStmt(string) (int, error)
	ExecSelectOneStmt(stmt string) (DRM.RowModel, error)
}

type StatementRunner_generics[T DRM.RowModel] interface {
	ExecSelectOneStmt(string) (T, error)
}

type Transactioner interface {
	GetTx() *sql.Tx
	IsInTx() bool
	// Begin on an sql.DB is: func (db *DB) Begin() (*Tx, error).
	// This method signature here has problems with re-entrancy,
	// and a re-entrant version would have a signature like:
	// Begin() (Transactioner, error)
	Begin() error
	BeginImmed() error
	Commit() error
	Rollback() error
	Exec(query string, args ...any) (sql.Result, error)
	Query(query string, args ...any) (*sql.Rows, error)
	QueryRow(query string, args ...any) *sql.Row
}