driver

type ConnAcquirer interface {
	// AcquireConn acquires a dedicated connection from the pool.
	// The returned DedicatedConn provides Exec/Query/QueryRow methods
	// that are guaranteed to run on the same underlying connection.
	// The caller MUST call Release() when done.
	AcquireConn(ctx context.Context) (DedicatedConn, error)
}

type DedicatedConn interface {
	Exec(ctx context.Context, query string, args ...any) (Result, error)
	Query(ctx context.Context, query string, args ...any) (Rows, error)
	QueryRow(ctx context.Context, query string, args ...any) Row
	Release()
}

type Dialect interface {
	// Name returns the dialect name (e.g., "pg", "mysql", "sqlite").
	Name() string

	// Quote quotes an identifier (table or column name) using the dialect's
	// quoting convention. For example, PostgreSQL uses double quotes while
	// MySQL uses backticks.
	Quote(ident string) string

	// Placeholder returns the nth parameter placeholder for prepared
	// statements. n is 1-indexed.
	// Examples:
	//   PostgreSQL -> "$1", "$2", ...
	//   MySQL      -> "?", "?", ...
	Placeholder(n int) string

	// GoToDBType maps a Go reflect.Type to the appropriate database-native
	// column type string, taking field options (e.g., explicit SQLType) into
	// account.
	GoToDBType(goType reflect.Type, opts schema.FieldOptions) string

	// AppendBytes appends a byte-escaped representation of v to the byte
	// slice b and returns the extended slice. The encoding is
	// dialect-specific (e.g., hex encoding for PostgreSQL bytea).
	AppendBytes(b []byte, v []byte) []byte

	// AppendTime appends a time value formatted for the dialect to b and
	// returns the extended slice.
	AppendTime(b []byte, t time.Time) []byte
}

type Driver interface {
	// Name returns the driver identifier (e.g., "pg", "mysql", "mongo").
	Name() string

	// Open initializes a connection using the given DSN.
	Open(ctx context.Context, dsn string, opts ...Option) error

	// Close terminates all connections.
	Close() error

	// Dialect returns the driver's SQL/query dialect.
	Dialect() Dialect

	// Ping checks connectivity.
	Ping(ctx context.Context) error

	// BeginTx starts a transaction.
	BeginTx(ctx context.Context, opts *TxOptions) (Tx, error)

	// Exec executes a query that doesn't return rows.
	Exec(ctx context.Context, query string, args ...any) (Result, error)

	// Query executes a query that returns rows.
	Query(ctx context.Context, query string, args ...any) (Rows, error)

	// QueryRow executes a query that returns at most one row.
	QueryRow(ctx context.Context, query string, args ...any) Row

	// SupportsReturning indicates if INSERT...RETURNING is supported.
	SupportsReturning() bool
}

type DriverOptions struct {
	PoolSize          int
	MinConns          int32
	MaxConnLifetime   time.Duration
	MaxConnIdleTime   time.Duration
	HealthCheckPeriod time.Duration
	QueryTimeout      time.Duration
	Logger            log.Logger
	Extra             map[string]any // driver-specific options
}

type IsolationLevel int

type Option func(*DriverOptions)

type Preparer interface {
	Prepare(ctx context.Context, query string) (Stmt, error)
}

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

	// LastInsertId returns the last auto-generated ID (if supported by the
	// driver). Drivers that do not support auto-increment IDs (e.g.,
	// PostgreSQL without RETURNING) may return 0 and an error.
	LastInsertId() (int64, error)
}

type Row interface {
	// Scan copies the row's columns into dest.
	Scan(dest ...any) error
}

type Rows interface {
	// Next advances to the next row. It returns false when no more rows are
	// available or an error occurred during iteration.
	Next() bool

	// Scan copies the current row's columns into dest. The number of dest
	// values must match the number of columns in the result set.
	Scan(dest ...any) error

	// Columns returns the column names of the result set.
	Columns() ([]string, error)

	// Close closes the rows iterator, releasing any held resources.
	Close() error

	// Err returns any error encountered during iteration (other than
	// io.EOF). It should be checked after the Next loop completes.
	Err() error
}

type Stmt interface {
	Exec(ctx context.Context, args ...any) (Result, error)
	Close() error
}

type StreamCapable interface {
	// SupportsStreaming returns true if the driver supports server-side cursors
	// or equivalent streaming mechanisms.
	SupportsStreaming() bool

	// SupportsCDC returns true if the driver supports change data capture
	// (e.g., PG logical replication, Mongo change streams, MySQL binlog).
	SupportsCDC() bool
}

type Tx interface {
	// Exec executes a query within the transaction.
	Exec(ctx context.Context, query string, args ...any) (Result, error)

	// Query executes a query that returns rows within the transaction.
	Query(ctx context.Context, query string, args ...any) (Rows, error)

	// QueryRow executes a query that returns a single row within the
	// transaction.
	QueryRow(ctx context.Context, query string, args ...any) Row

	// Commit commits the transaction. After Commit returns successfully,
	// all changes made within the transaction are durable.
	Commit() error

	// Rollback rolls back the transaction, discarding all changes.
	// Rollback is safe to call after Commit; it will be a no-op if the
	// transaction has already been committed.
	Rollback() error
}

type TxOptions struct {
	// IsolationLevel sets the isolation level for the transaction.
	IsolationLevel IsolationLevel
	// ReadOnly marks the transaction as read-only when true. The database
	// may use this hint for optimisation.
	ReadOnly bool
}