driver

type Conn interface {
	// Query runs a statement that returns rows; rows are streamed.
	Query(ctx context.Context, query string, args ...any) (Rows, error)
	// Exec runs a statement that does not return rows.
	Exec(ctx context.Context, query string, args ...any) (Result, error)
	// Close releases the connection.
	Close() error
}

type Driver interface {
	// Name is the unique identifier of the driver, e.g. "sqlite", "postgres".
	//
	// It doubles as the DSN scheme: callers select a driver by this name (see
	// Open/Get). An earlier design split this into Name() and Scheme(), but a
	// single value keeps registration and selection unambiguous and avoids a
	// second source of truth; we merge them deliberately.
	Name() string
	// Open establishes a connection using a driver-specific DSN.
	Open(ctx context.Context, dsn string) (Conn, error)
}

type Metadata interface {
	// Databases lists databases/schemas (\l).
	Databases(ctx context.Context) (Rows, error)
	// Tables lists tables in the current database (\dt).
	Tables(ctx context.Context) (Rows, error)
	// Columns describes the columns of a table (\d <table>).
	Columns(ctx context.Context, table string) (Rows, error)
}

type Result interface {
	// RowsAffected returns the number of rows affected by the statement.
	RowsAffected() (int64, error)
}

type Rows interface {
	// Columns returns the column names of the result set.
	Columns() []string
	// Next advances to the next row, returning false at end-of-rows or on
	// error (check Err afterwards).
	Next() bool
	// Values returns the current row's column values. A SQL NULL is
	// represented as a nil any.
	Values() ([]any, error)
	// Err returns the first non-EOF error encountered during iteration.
	Err() error
	// Close releases resources held by the cursor.
	Close() error
}