db.go

// Package relica provides a lightweight, type-safe database query builder for Go.
//
// Relica offers a fluent API for building SQL queries with support for:
//   - Multiple databases (PostgreSQL, MySQL, SQLite)
//   - Zero production dependencies
//   - Prepared statement caching
//   - Transaction management
//   - Advanced SQL features (JOINs, aggregates, subqueries, CTEs)
//
// # Quick Start
//
// Install:
//
//	go get github.com/coregx/relica
//
// Basic usage:
//
//	db, err := relica.Open("postgres", "user=postgres dbname=myapp")
//	if err != nil {
//	    log.Fatal(err)
//	}
//	defer db.Close()
//
//	var users []User
//	err = db.Select("id", "name").From("users").All(&users)
//
// # Features
//
// CRUD Operations:
//
//	// SELECT with Expression API
//	db.Select().From("users").Where(relica.Eq("id", 123)).One(&user)
//
//	// INSERT via Model API (recommended)
//	user := User{Name: "Alice", Email: "alice@example.com"}
//	db.Model(&user).Insert()
//
//	// UPDATE
//	db.Update("users").
//	    Set(map[string]any{"status": "active"}).
//	    Where(relica.Eq("id", 123)).
//	    Execute()
//
//	// DELETE
//	db.Delete("users").Where(relica.Eq("id", 123)).Execute()
package relica

import (
	"context"
	"database/sql"
	"errors"
	"log/slog"
	"reflect"
	"sort"
	"time"

	"github.com/coregx/relica/internal/core"
	"github.com/coregx/relica/internal/logger"
	"github.com/coregx/relica/internal/util"
)

// DB represents a database connection with query building capabilities.
//
// DB provides a fluent API for constructing and executing SQL queries
// in a type-safe manner. It wraps the underlying database/sql connection
// and adds features like:
//   - Prepared statement caching (LRU eviction, <60ns hit latency)
//   - Query builder with method chaining
//   - Transaction management (all isolation levels)
//   - Multi-database support (PostgreSQL, MySQL, SQLite)
//
// Example:
//
//	db, err := relica.Open("postgres", "user=postgres dbname=myapp")
//	if err != nil {
//	    log.Fatal(err)
//	}
//	defer db.Close()
//
//	var users []User
//	err = db.Builder().
//	    Select("id", "name", "email").
//	    From("users").
//	    Where("active = ?", true).
//	    OrderBy("name").
//	    All(&users)
type DB struct {
	db *core.DB
}

// QueryBuilder constructs type-safe queries.
//
// The query builder provides a fluent interface for building
// SELECT, INSERT, UPDATE, DELETE, UPSERT, and batch operations.
// All queries are cached and executed with prepared statements.
//
// Example:
//
//	qb := db.Builder()
//	qb.Select("*").From("users").Where("status = ?", 1).All(&users)
type QueryBuilder struct {
	qb *core.QueryBuilder
}

// QueryPlan represents a unified query execution plan from database EXPLAIN.
// It provides performance metrics, index usage analysis, and database-specific details.
// Returned by [SelectQuery.Explain] and [SelectQuery.ExplainAnalyze].
//
// Fields populated by EXPLAIN (always available):
//   - Cost, EstimatedRows, UsesIndex, IndexName, FullScan, RawOutput, Database
//
// Fields populated only by EXPLAIN ANALYZE (require actual execution):
//   - ActualRows, ActualTime, BuffersHit, BuffersMiss, RowsExamined, RowsProduced
type QueryPlan = core.QueryPlan

// SelectQuery represents a SELECT query being built.
//
// SelectQuery supports a wide range of SQL features including:
//   - JOINs (INNER, LEFT, RIGHT, FULL, CROSS)
//   - Aggregates (COUNT, SUM, AVG, MIN, MAX)
//   - GROUP BY and HAVING
//   - ORDER BY, LIMIT, OFFSET
//   - Set operations (UNION, INTERSECT, EXCEPT)
//   - Common Table Expressions (WITH, WITH RECURSIVE)
//   - Subqueries (in FROM, WHERE, SELECT clauses)
//
// Example:
//
//	sq := db.Builder().
//	    Select("u.name", "COUNT(*) as order_count").
//	    From("users u").
//	    InnerJoin("orders o", "o.user_id = u.id").
//	    GroupBy("u.id", "u.name").
//	    Having("COUNT(*) > ?", 10).
//	    OrderBy("order_count DESC")
//	sq.All(&results)
type SelectQuery struct {
	sq *core.SelectQuery
}

// Tx represents a database transaction.
//
// Transactions provide ACID guarantees and support all standard
// isolation levels. All queries executed through a transaction's
// builder automatically participate in that transaction.
//
// Example:
//
//	tx, err := db.Begin(ctx)
//	if err != nil {
//	    return err
//	}
//	defer tx.Rollback() // Safe to call even after Commit
//
//	_, err = tx.Insert("users", data).Execute()
//	if err != nil {
//	    return err
//	}
//
//	return tx.Commit()
type Tx struct {
	tx *core.Tx
}

// ModelQuery provides CRUD operations for struct models.
//
// ModelQuery simplifies database operations by automatically inferring
// table names and primary keys from struct definitions, similar to ozzo-dbx.
//
// The table name is determined by:
//  1. TableName() method if model implements interface{ TableName() string }
//  2. Otherwise: struct name lowercased with 's' suffix (e.g., User → users)
//
// The primary key is detected from:
//  1. Field with db:"id" tag
//  2. Field with db:"*_id" tag (e.g., db:"user_id")
//  3. Field named "ID"
//
// Example:
//
//	type User struct {
//	    ID    int    `db:"id"`
//	    Name  string `db:"name"`
//	    Email string `db:"email"`
//	}
//
//	func (User) TableName() string { return "users" }
//
//	user := User{Name: "Alice", Email: "alice@example.com"}
//	err := db.Model(&user).Insert()
//
//	user.Status = "active"
//	err = db.Model(&user).Update() // Auto WHERE by primary key.
//
//	err = db.Model(&user).Delete() // Auto WHERE by primary key.
type ModelQuery struct {
	mq *core.ModelQuery
}

// BeforeInserter is implemented by models that need pre-insert logic.
// If a struct implements this interface, Model().Insert() and Model().Upsert()
// call BeforeInsert() before autoid generation and query execution.
//
// Use cases: setting timestamps, generating custom IDs, validation.
//
// Example:
//
//	type User struct {
//	    ID        int64     `db:"id,pk"`
//	    PublicID  string    `db:"public_id,autoid:usr"`
//	    CreatedAt time.Time `db:"created_at"`
//	}
//
//	func (u *User) BeforeInsert() error {
//	    u.CreatedAt = time.Now()
//	    return nil
//	}
type BeforeInserter = core.BeforeInserter

// Query represents a built query ready for execution.
//
// Query encapsulates the SQL string, parameters, and execution context.
// It provides methods for executing the query and scanning results.
//
// Example:
//
//	q := db.Builder().Select("*").From("users").Where("id = ?", 123).Build()
//	var user User
//	err := q.One(&user)
type Query struct {
	q   *core.Query
	err error // Error from query construction (e.g., struct conversion).
}

// TxOptions represents transaction options including isolation level.
//
// Example:
//
//	opts := &relica.TxOptions{
//	    Isolation: sql.LevelSerializable,
//	    ReadOnly:  true,
//	}
//	tx, err := db.BeginTx(ctx, opts)
type TxOptions = core.TxOptions

// PoolStats represents database connection pool statistics.
// It provides insights into connection pool health and usage patterns.
type PoolStats = core.PoolStats

// Option is a functional option for configuring DB.
//
// Example:
//
//	db, err := relica.Open("postgres", dsn,
//	    relica.WithMaxOpenConns(100),
//	    relica.WithMaxIdleConns(50))
type Option = core.Option

// Expression represents a database expression for building complex WHERE clauses.
//
// Expressions provide a type-safe way to construct SQL conditions without
// writing raw SQL strings. They support nesting and composition.
//
// Example:
//
//	expr := relica.And(
//	    relica.Eq("status", 1),
//	    relica.Or(
//	        relica.GreaterThan("age", 18),
//	        relica.Eq("verified", true),
//	    ),
//	)
//	db.Builder().Select("*").From("users").Where(expr).All(&users)
type Expression = core.Expression

// HashExp represents a hash-based expression using column-value pairs.
//
// HashExp provides a convenient map syntax for simple equality conditions.
// Special values are handled automatically:
//   - nil → "column IS NULL"
//   - []any → "column IN (...)"
//
// Example:
//
//	db.Builder().Select("*").From("users").Where(relica.HashExp{
//	    "status": 1,
//	    "role": []string{"admin", "moderator"},
//	    "deleted_at": nil,
//	}).All(&users)
type HashExp = core.HashExp

// LikeExp represents a LIKE expression with automatic escaping.
//
// LikeExp provides pattern matching with automatic escaping of
// SQL wildcard characters (%, _).
//
// Example:
//
//	db.Builder().Select("*").From("users").Where(
//	    relica.Like("name", "john%"),
//	).All(&users)
type LikeExp = core.LikeExp

// ============================================================================
// DB Methods
// ============================================================================

// Open creates a new database connection with optional configuration.
//
// The driverName parameter specifies the database driver:
//   - "postgres" - PostgreSQL
//   - "mysql" - MySQL
//   - "sqlite3" - SQLite
//
// The dsn parameter is the database-specific connection string.
//
// Example:
//
//	db, err := relica.Open("postgres", "user=postgres dbname=myapp",
//	    relica.WithMaxOpenConns(100),
//	    relica.WithMaxIdleConns(50))
//	if err != nil {
//	    log.Fatal(err)
//	}
//	defer db.Close()
func Open(driverName, dsn string, opts ...Option) (*DB, error) {
	coreDB, err := core.Open(driverName, dsn, opts...)
	if err != nil {
		return nil, err
	}
	return &DB{db: coreDB}, nil
}

// NewDB creates a database connection.
//
// Deprecated: Use Open instead. NewDB will be removed in a future version.
//
// Example:
//
//	db, err := relica.NewDB("postgres", dsn)
func NewDB(driverName, dsn string) (*DB, error) {
	coreDB, err := core.NewDB(driverName, dsn)
	if err != nil {
		return nil, err
	}
	return &DB{db: coreDB}, nil
}

// WrapDB wraps an existing *sql.DB connection with Relica's query builder.
//
// The caller is responsible for managing the connection lifecycle (including Close()).
// This is useful when you need to:
//   - Use Relica with an externally managed connection pool
//   - Integrate with existing code that already has a *sql.DB instance
//   - Apply custom connection pool settings before wrapping
//
// Example:
//
//	sqlDB, _ := sql.Open("postgres", dsn)
//	sqlDB.SetMaxOpenConns(100)
//	sqlDB.SetConnMaxLifetime(time.Hour)
//	db := relica.WrapDB(sqlDB, "postgres")
//	defer sqlDB.Close() // Caller's responsibility
func WrapDB(sqlDB *sql.DB, driverName string) *DB {
	coreDB := core.WrapDB(sqlDB, driverName)
	return &DB{db: coreDB}
}

// Close releases all database resources including the connection pool
// and statement cache.
//
// After calling Close, the DB instance should not be used.
//
// Example:
//
//	db, _ := relica.Open("postgres", dsn)
//	defer db.Close()
func (d *DB) Close() error {
	return d.db.Close()
}

// SqlDB returns the underlying *sql.DB connection.
// Useful for connection pool tuning, health checks, or database/sql methods.
// Do NOT call Close() on the returned value — use [DB.Close] instead.
func (d *DB) SqlDB() *sql.DB {
	return d.db.SqlDB()
}

// PingContext verifies the database connection is alive.
// Use for health checks and connection validation at startup.
func (d *DB) PingContext(ctx context.Context) error {
	return d.db.PingContext(ctx)
}

// DriverName returns the database driver name (e.g., "postgres", "mysql", "sqlite3").
func (d *DB) DriverName() string {
	return d.db.DriverName()
}

// WithContext returns a new DB with the given context.
//
// The context will be used for all subsequent query operations
// unless overridden at the query level.
//
// Example:
//
//	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
//	defer cancel()
//	db := db.WithContext(ctx)
//	db.Builder().Select("*").From("users").All(&users)
func (d *DB) WithContext(ctx context.Context) *DB {
	return &DB{db: d.db.WithContext(ctx)}
}

// Stats returns database connection pool statistics.
//
// Stats provides insights into connection pool usage including:
//   - Number of open/idle/in-use connections
//   - Wait count and duration
//   - Connections closed due to max lifetime/idle time
//   - Health check status (if enabled)
//
// Example:
//
//	stats := db.Stats()
//	fmt.Printf("Open: %d, Idle: %d, InUse: %d\n",
//	    stats.OpenConnections, stats.Idle, stats.InUse)
//	if !stats.Healthy {
//	    log.Warn("Database health check failed")
//	}
func (d *DB) Stats() PoolStats {
	return d.db.Stats()
}

// IsHealthy returns true if the database connection is healthy.
// Always returns true if health checks are disabled.
//
// This is a convenience method that calls Stats() internally.
//
// Example:
//
//	if !db.IsHealthy() {
//	    log.Error("Database connection unhealthy")
//	    // Attempt reconnection or alert
//	}
func (d *DB) IsHealthy() bool {
	return d.db.IsHealthy()
}

// WarmCache pre-warms the statement cache by preparing frequently-used queries.
//
// This improves performance at startup by avoiding cache misses for common queries.
// The queries are prepared synchronously in the order provided.
// Returns the number of successfully prepared queries and any error encountered.
//
// Example:
//
//	n, err := db.WarmCache([]string{
//	    "SELECT * FROM users WHERE id = ?",
//	    "INSERT INTO logs (message, level) VALUES (?, ?)",
//	    "UPDATE users SET last_login = ? WHERE id = ?",
//	})
//	if err != nil {
//	    log.Warn("Failed to warm cache", "error", err, "warmed", n)
//	}
func (d *DB) WarmCache(queries []string) (int, error) {
	return d.db.WarmCache(queries)
}

// PinQuery marks a query as pinned in the statement cache, preventing eviction.
//
// Pinned queries remain in cache indefinitely, useful for frequently-used queries.
// Returns false if the query is not in cache (call WarmCache first).
//
// Example:
//
//	// Warm and pin critical queries
//	queries := []string{"SELECT * FROM users WHERE id = ?"}
//	db.WarmCache(queries)
//	db.PinQuery(queries[0])  // Will never be evicted
func (d *DB) PinQuery(query string) bool {
	return d.db.PinQuery(query)
}

// UnpinQuery removes the pin from a cached query, allowing normal LRU eviction.
//
// Returns false if the query is not in cache or not pinned.
//
// Example:
//
//	db.UnpinQuery("SELECT * FROM users WHERE id = ?")
func (d *DB) UnpinQuery(query string) bool {
	return d.db.UnpinQuery(query)
}

// Builder returns a new QueryBuilder for constructing queries.
//
// The query builder provides a fluent interface for building
// SELECT, INSERT, UPDATE, DELETE, and UPSERT queries.
//
// Example:
//
//	db.Builder().
//	    Select("*").
//	    From("users").
//	    Where("id = ?", 123).
//	    One(&user)
func (d *DB) Builder() *QueryBuilder {
	return &QueryBuilder{qb: d.db.Builder()}
}

// NewQuery creates a raw SQL query for execution.
// Use this for queries that don't fit the query builder pattern,
// or when you need manual control over prepared statement lifecycle.
//
// Example:
//
//	var count int
//	err := db.NewQuery("SELECT COUNT(*) FROM users").Row(&count)
//
//	// With parameters
//	var user User
//	err := db.NewQuery("SELECT * FROM users WHERE id = ?").Bind(1).One(&user)
//
//	// With Prepare for repeated execution
//	q := db.NewQuery("SELECT * FROM users WHERE status = ?").Prepare()
//	defer q.Close()
//	for _, status := range statuses {
//	    q.Bind(status).All(&users)
//	}
func (d *DB) NewQuery(query string) *Query {
	return &Query{q: d.db.NewQuery(query)}
}

// Model creates a ModelQuery for performing CRUD operations on a struct model.
//
// The model must be a pointer to a struct. The table name and primary key
// are automatically inferred from the struct definition.
//
// Table name resolution:
//  1. If model implements TableName() string, use that value
//  2. Otherwise, use struct name lowercased + 's' (e.g., User → users)
//
// Primary key detection:
//  1. Field with db:"id" tag
//  2. Field with db:"*_id" tag (e.g., db:"user_id")
//  3. Field named "ID"
//
// Example:
//
//	type User struct {
//	    ID    int    `db:"id"`
//	    Name  string `db:"name"`
//	    Email string `db:"email"`
//	}
//
//	func (User) TableName() string { return "users" }
//
//	// INSERT - auto table name.
//	user := User{Name: "Alice", Email: "alice@example.com"}
//	err := db.Model(&user).Insert()
//
//	// UPDATE - auto WHERE by primary key.
//	user.Status = "active"
//	err = db.Model(&user).Update()
//
//	// DELETE - auto WHERE by primary key.
//	err = db.Model(&user).Delete()
//
//	// Field control.
//	err = db.Model(&user).Exclude("CreatedAt", "UpdatedAt").Insert()
//	err = db.Model(&user).Table("users_archive").Insert()
func (d *DB) Model(model any) *ModelQuery {
	return &ModelQuery{mq: d.db.Model(model)}
}

// Select creates a new SELECT query.
//
// This is a convenience method equivalent to db.Builder().Select(cols...).
// For advanced queries (CTEs, subqueries, UNION), use db.Builder() directly.
//
// Example:
//
//	var users []User
//	err := db.Select("id", "name", "email").
//	    From("users").
//	    Where("active = ?", true).
//	    OrderBy("name").
//	    All(&users)
//
//	// For wildcard selection
//	err := db.Select("*").From("users").All(&users)
//
//	// For advanced features, use Builder()
//	err := db.Builder().
//	    With("stats", statsQuery).
//	    Select("*").
//	    From("stats").
//	    All(&results)
func (d *DB) Select(cols ...string) *SelectQuery {
	return d.Builder().Select(cols...)
}

// Insert creates a new INSERT query.
//
// This is a convenience method equivalent to db.Builder().Insert(table, data).
// For batch inserts, use db.Builder().BatchInsert().
//
// Example:
//
//	result, err := db.Insert("users", map[string]any{
//	    "name":  "Alice",
//	    "email": "alice@example.com",
//	}).Execute()
//	if err != nil {
//	    return err
//	}
//	rows, _ := result.RowsAffected()
//	fmt.Printf("Inserted %d row(s)\n", rows)
//
//	// For batch operations, use Builder()
//	result, err := db.Builder().
//	    BatchInsert("users", []string{"name", "email"}).
//	    Values("Alice", "alice@example.com").
//	    Values("Bob", "bob@example.com").
//	    Execute()
func (d *DB) Insert(table string, data map[string]any) *Query {
	return d.Builder().Insert(table, data)
}

// InsertStruct builds an INSERT query from a struct using db tags.
//
// The struct fields are mapped to database columns using the `db` struct tag.
// Fields without a `db` tag use the field name.
// Fields tagged with `db:"-"` are ignored.
// Unexported fields are automatically skipped.
//
// This method provides type-safe struct-based inserts without manually
// constructing maps. For batch struct inserts, use BatchInsertStruct.
//
// Example:
//
//	type User struct {
//	    ID    int    `db:"id"`
//	    Name  string `db:"name"`
//	    Email string `db:"email"`
//	    Skip  int    `db:"-"`  // ignored
//	}
//
//	user := User{Name: "Alice", Email: "alice@example.com"}
//	result, err := db.InsertStruct("users", &user).Execute()
//	if err != nil {
//	    return err
//	}
func (d *DB) InsertStruct(table string, data any) *Query {
	return d.Builder().InsertStruct(table, data)
}

// BatchInsertStruct builds a batch INSERT query from a slice of structs.
//
// This method performs batch insertion of multiple structs in a single query,
// which is significantly faster than individual inserts. All structs must
// have the same type and will be inserted with the same column set.
//
// The slice element type must be a struct or pointer to struct.
// Fields are mapped using the same rules as InsertStruct.
//
// Example:
//
//	users := []User{
//	    {Name: "Alice", Email: "alice@example.com"},
//	    {Name: "Bob", Email: "bob@example.com"},
//	}
//	result, err := db.BatchInsertStruct("users", users).Execute()
//	if err != nil {
//	    return err
//	}
//
// For single struct inserts, use InsertStruct instead.
func (d *DB) BatchInsertStruct(table string, data any) *Query {
	return d.Builder().BatchInsertStruct(table, data)
}

// UpdateStruct builds an UPDATE query from a struct using db tags.
//
// Similar to InsertStruct, but for UPDATE operations. The struct fields
// are converted to SET clauses. You must chain a Where() call to specify
// which rows to update.
//
// This method provides type-safe struct-based updates without manually
// constructing maps.
//
// Example:
//
//	user := User{Name: "Alice Updated", Status: "active"}
//	result, err := db.UpdateStruct("users", &user).
//	    Where("id = ?", user.ID).
//	    Execute()
//	if err != nil {
//	    return err
//	}
//
// For automatic WHERE clause based on primary key, consider using
// the Model() API (available in v0.6.0+).
func (d *DB) UpdateStruct(table string, data any) *UpdateQuery {
	return d.Builder().UpdateStruct(table, data)
}

// Update creates a new UPDATE query.
//
// This is a convenience method equivalent to db.Builder().Update(table).
// For batch updates, use db.Builder().BatchUpdate().
//
// Example:
//
//	_, err := db.Update("users").
//	    Set(map[string]any{"status": "active"}).
//	    Where("id = ?", 123).
//	    Execute()
//	if err != nil {
//	    return err
//	}
//
//	// For batch operations, use Builder()
//	_, err := db.Builder().
//	    BatchUpdate("users", "id").
//	    Set(1, map[string]any{"status": "active"}).
//	    Set(2, map[string]any{"status": "inactive"}).
//	    Execute()
func (d *DB) Update(table string) *UpdateQuery {
	return d.Builder().Update(table)
}

// Delete creates a new DELETE query.
//
// This is a convenience method equivalent to db.Builder().Delete(table).
//
// Example:
//
//	_, err := db.Delete("users").
//	    Where("id = ?", 123).
//	    Execute()
//	if err != nil {
//	    return err
//	}
//
//	// Delete multiple rows
//	_, err := db.Delete("users").
//	    Where("status = ?", "inactive").
//	    Execute()
func (d *DB) Delete(table string) *DeleteQuery {
	return d.Builder().Delete(table)
}

// BatchInsert creates a new batch INSERT query for inserting multiple rows efficiently.
//
// This is a convenience method equivalent to db.Builder().BatchInsert(table, columns).
//
// Example:
//
//	result, err := db.BatchInsert("users", []string{"name", "email"}).
//	    Values("Alice", "alice@example.com").
//	    Values("Bob", "bob@example.com").
//	    Execute()
func (d *DB) BatchInsert(table string, columns []string) *BatchInsertQuery {
	return d.Builder().BatchInsert(table, columns)
}

// BatchUpdate creates a new batch UPDATE query for updating multiple rows with different values.
//
// This is a convenience method equivalent to db.Builder().BatchUpdate(table, keyColumn).
//
// Example:
//
//	result, err := db.BatchUpdate("users", "id").
//	    Set(1, map[string]any{"name": "Alice"}).
//	    Set(2, map[string]any{"name": "Bob"}).
//	    Execute()
func (d *DB) BatchUpdate(table, keyColumn string) *BatchUpdateQuery {
	return d.Builder().BatchUpdate(table, keyColumn)
}

// Upsert creates a new UPSERT query (INSERT ... ON CONFLICT).
//
// This is a convenience method equivalent to db.Builder().Upsert(table, values).
//
// Example:
//
//	result, err := db.Upsert("users", map[string]any{
//	    "email": "alice@example.com",
//	    "name":  "Alice",
//	}).OnConflict("email").DoUpdate("name").Execute()
func (d *DB) Upsert(table string, values map[string]any) *UpsertQuery {
	return d.Builder().Upsert(table, values)
}

// Begin starts a transaction with default options.
//
// The transaction must be committed or rolled back to release resources.
// It's safe to call Rollback() even after Commit().
//
// Example:
//
//	tx, err := db.Begin(ctx)
//	if err != nil {
//	    return err
//	}
//	defer tx.Rollback() // Safe even after Commit
//
//	// Use transaction
//	_, err = tx.Insert("users", data).Execute()
//	if err != nil {
//	    return err
//	}
//
//	return tx.Commit()
func (d *DB) Begin(ctx context.Context) (*Tx, error) {
	coreTx, err := d.db.Begin(ctx)
	if err != nil {
		return nil, err
	}
	return &Tx{tx: coreTx}, nil
}

// BeginTx starts a transaction with specified options.
//
// Options can specify isolation level and read-only mode:
//   - Isolation: sql.LevelReadUncommitted, sql.LevelReadCommitted,
//     sql.LevelRepeatableRead, sql.LevelSerializable
//   - ReadOnly: true for read-only transactions (some databases optimize these)
//
// Example:
//
//	opts := &relica.TxOptions{
//	    Isolation: sql.LevelSerializable,
//	    ReadOnly:  false,
//	}
//	tx, err := db.BeginTx(ctx, opts)
func (d *DB) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error) {
	coreTx, err := d.db.BeginTx(ctx, opts)
	if err != nil {
		return nil, err
	}
	return &Tx{tx: coreTx}, nil
}

// Transactional executes f within a transaction with automatic commit/rollback.
//
// If f returns an error, the transaction is rolled back and the error is returned.
// If f panics, the transaction is rolled back and the panic is re-raised.
// If f completes successfully, the transaction is committed.
//
// This helper simplifies transaction management and ensures proper cleanup
// in all code paths, including panics.
//
// Example:
//
//	err := db.Transactional(ctx, func(tx *relica.Tx) error {
//	    user := User{Name: "Alice", Email: "alice@example.com"}
//	    if err := tx.Model(&user).Insert(); err != nil {
//	        return err  // Auto rollback
//	    }
//
//	    account := Account{UserID: user.ID, Balance: 100}
//	    if err := tx.Model(&account).Insert(); err != nil {
//	        return err  // Auto rollback
//	    }
//
//	    return nil  // Auto commit
//	})
func (d *DB) Transactional(ctx context.Context, f func(*Tx) error) error {
	return d.db.Transactional(ctx, func(coreTx *core.Tx) error {
		return f(&Tx{tx: coreTx})
	})
}

// TransactionalTx executes f within a transaction with custom options.
//
// Options can specify isolation level and read-only mode.
// If f returns an error, the transaction is rolled back and the error is returned.
// If f panics, the transaction is rolled back and the panic is re-raised.
// If f completes successfully, the transaction is committed.
//
// Example:
//
//	opts := &relica.TxOptions{
//	    Isolation: sql.LevelSerializable,
//	    ReadOnly:  false,
//	}
//	err := db.TransactionalTx(ctx, opts, func(tx *relica.Tx) error {
//	    // Perform operations within serializable transaction.
//	    return tx.Model(&user).Update()
//	})
func (d *DB) TransactionalTx(ctx context.Context, opts *TxOptions, f func(*Tx) error) error {
	return d.db.TransactionalTx(ctx, opts, func(coreTx *core.Tx) error {
		return f(&Tx{tx: coreTx})
	})
}

// ExecContext executes a raw SQL query (INSERT/UPDATE/DELETE).
//
// This bypasses the query builder and executes SQL directly.
// Use this for queries that aren't supported by the query builder
// or when you need maximum control.
//
// Example:
//
//	result, err := db.ExecContext(ctx,
//	    "UPDATE users SET status = ? WHERE id = ?",
//	    1, 123)
//	if err != nil {
//	    return err
//	}
//	rowsAffected, _ := result.RowsAffected()
func (d *DB) ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error) {
	return d.db.ExecContext(ctx, query, args...)
}

// QueryContext executes a raw SQL query and returns rows.
//
// This bypasses the query builder and executes SQL directly.
// You are responsible for closing the returned rows.
//
// Example:
//
//	rows, err := db.QueryContext(ctx,
//	    "SELECT * FROM users WHERE status = ?", 1)
//	if err != nil {
//	    return err
//	}
//	defer rows.Close()
//
//	for rows.Next() {
//	    // Process rows
//	}
func (d *DB) QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error) {
	return d.db.QueryContext(ctx, query, args...)
}

// QueryRowContext executes a raw SQL query expected to return at most one row.
//
// This bypasses the query builder and executes SQL directly.
//
// Example:
//
//	var count int
//	err := db.QueryRowContext(ctx,
//	    "SELECT COUNT(*) FROM users").Scan(&count)
func (d *DB) QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row {
	return d.db.QueryRowContext(ctx, query, args...)
}

// QuoteTableName quotes a table name using the database's identifier quoting style.
//
// This is useful when building dynamic SQL queries.
//
// Example:
//
//	quoted := db.QuoteTableName("users")
//	// PostgreSQL: "users"
//	// MySQL: `users`
func (d *DB) QuoteTableName(table string) string {
	return d.db.QuoteTableName(table)
}

// QuoteColumnName quotes a column name using the database's identifier quoting style.
//
// This is useful when building dynamic SQL queries.
//
// Example:
//
//	quoted := db.QuoteColumnName("user_id")
//	// PostgreSQL: "user_id"
//	// MySQL: `user_id`
func (d *DB) QuoteColumnName(column string) string {
	return d.db.QuoteColumnName(column)
}

// GenerateParamName generates a dialect-specific parameter placeholder for the given index.
// For PostgreSQL, returns "$1", "$2", etc. For MySQL/SQLite, returns "?".
//
// This is useful when building dynamic SQL queries where you need
// the correct placeholder syntax for the active database driver.
//
// Example:
//
//	ph1 := db.GenerateParamName(1) // PostgreSQL: "$1", MySQL/SQLite: "?"
//	ph2 := db.GenerateParamName(2) // PostgreSQL: "$2", MySQL/SQLite: "?"
func (d *DB) GenerateParamName(index int) string {
	return d.db.GenerateParamName(index)
}

// Unwrap returns the underlying core.DB for advanced use cases.
//
// This method is provided for edge cases where direct access to
// internal types is needed. Most users should not need this.
//
// Example:
//
//	coreDB := db.Unwrap()
//	// Use coreDB for advanced operations
func (d *DB) Unwrap() *core.DB {
	return d.db
}

// ============================================================================
// Tx Methods
// ============================================================================

// Builder returns the query builder for this transaction.
//
// All queries built using this builder will execute within the transaction.
// The builder automatically inherits the transaction's context.
//
// Example:
//
//	tx.Builder().Insert("users", data).Execute()
func (t *Tx) Builder() *QueryBuilder {
	return &QueryBuilder{qb: t.tx.Builder()}
}

// Select creates a new SELECT query within the transaction.
//
// This is a convenience method equivalent to tx.Builder().Select(cols...).
//
// Example:
//
//	var users []User
//	err := tx.Select("*").From("users").Where("id = ?", 123).All(&users)
//	if err != nil {
//	    tx.Rollback()
//	    return err
//	}
//
//	// For advanced features, use Builder()
//	err := tx.Builder().
//	    With("stats", statsQuery).
//	    Select("*").
//	    From("stats").
//	    All(&results)
func (t *Tx) Select(cols ...string) *SelectQuery {
	return t.Builder().Select(cols...)
}

// Insert creates a new INSERT query within the transaction.
//
// This is a convenience method equivalent to tx.Builder().Insert(table, data).
//
// Example:
//
//	_, err := tx.Insert("users", map[string]any{
//	    "name":  "Alice",
//	    "email": "alice@example.com",
//	}).Execute()
//	if err != nil {
//	    tx.Rollback()
//	    return err
//	}
func (t *Tx) Insert(table string, data map[string]any) *Query {
	return t.Builder().Insert(table, data)
}

// InsertStruct creates an INSERT query from a struct within the transaction.
//
// This is a convenience method equivalent to tx.Builder().InsertStruct(table, data).
// See DB.InsertStruct for full documentation.
//
// Example:
//
//	user := User{Name: "Alice", Email: "alice@example.com"}
//	_, err := tx.InsertStruct("users", &user).Execute()
//	if err != nil {
//	    tx.Rollback()
//	    return err
//	}
func (t *Tx) InsertStruct(table string, data any) *Query {
	return t.Builder().InsertStruct(table, data)
}

// BatchInsertStruct creates a batch INSERT query from structs within the transaction.
//
// This is a convenience method equivalent to tx.Builder().BatchInsertStruct(table, data).
// See DB.BatchInsertStruct for full documentation.
//
// Example:
//
//	users := []User{
//	    {Name: "Alice", Email: "alice@example.com"},
//	    {Name: "Bob", Email: "bob@example.com"},
//	}
//	_, err := tx.BatchInsertStruct("users", users).Execute()
//	if err != nil {
//	    tx.Rollback()
//	    return err
//	}
func (t *Tx) BatchInsertStruct(table string, data any) *Query {
	return t.Builder().BatchInsertStruct(table, data)
}

// UpdateStruct creates an UPDATE query from a struct within the transaction.
//
// This is a convenience method equivalent to tx.Builder().UpdateStruct(table, data).
// See DB.UpdateStruct for full documentation.
//
// Example:
//
//	user := User{Name: "Alice Updated", Status: "active"}
//	_, err := tx.UpdateStruct("users", &user).
//	    Where("id = ?", user.ID).
//	    Execute()
//	if err != nil {
//	    tx.Rollback()
//	    return err
//	}
func (t *Tx) UpdateStruct(table string, data any) *UpdateQuery {
	return t.Builder().UpdateStruct(table, data)
}

// Update creates a new UPDATE query within the transaction.
//
// This is a convenience method equivalent to tx.Builder().Update(table).
//
// Example:
//
//	_, err := tx.Update("users").
//	    Set(map[string]any{"status": "active"}).
//	    Where("id = ?", 123).
//	    Execute()
//	if err != nil {
//	    tx.Rollback()
//	    return err
//	}
func (t *Tx) Update(table string) *UpdateQuery {
	return t.Builder().Update(table)
}

// Delete creates a new DELETE query within the transaction.
//
// This is a convenience method equivalent to tx.Builder().Delete(table).
//
// Example:
//
//	_, err := tx.Delete("users").Where("id = ?", 123).Execute()
//	if err != nil {
//	    tx.Rollback()
//	    return err
//	}
func (t *Tx) Delete(table string) *DeleteQuery {
	return t.Builder().Delete(table)
}

// Commit commits the transaction.
//
// After calling Commit, the transaction cannot be used for further queries.
//
// Example:
//
//	if err := tx.Commit(); err != nil {
//	    return err
//	}
func (t *Tx) Commit() error {
	return t.tx.Commit()
}

// Rollback rolls back the transaction.
//
// After calling Rollback, the transaction cannot be used for further queries.
// It's safe to call Rollback even after Commit (it will be a no-op).
//
// Example:
//
//	defer tx.Rollback() // Safe even after Commit
func (t *Tx) Rollback() error {
	return t.tx.Rollback()
}

// Unwrap returns the underlying core.Tx for advanced use cases.
//
// This method is provided for edge cases where direct access to
// internal types is needed. Most users should not need this.
func (t *Tx) Unwrap() *core.Tx {
	return t.tx
}

// ExecContext executes a raw SQL query within the transaction.
func (t *Tx) ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error) {
	return t.tx.ExecContext(ctx, query, args...)
}

// QueryContext executes a raw SQL query within the transaction and returns rows.
func (t *Tx) QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error) {
	return t.tx.QueryContext(ctx, query, args...)
}

// QueryRowContext executes a raw SQL query within the transaction returning one row.
func (t *Tx) QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row {
	return t.tx.QueryRowContext(ctx, query, args...)
}

// Model creates a ModelQuery within transaction context.
//
// All operations performed through this ModelQuery will execute
// within the transaction.
//
// Example:
//
//	tx, _ := db.Begin(ctx)
//	defer tx.Rollback()
//
//	user := User{Name: "Alice"}
//	err := tx.Model(&user).Insert()
//	if err != nil {
//	    return err
//	}
//
//	return tx.Commit()
func (t *Tx) Model(model any) *ModelQuery {
	return &ModelQuery{mq: t.tx.Model(model)}
}

// BatchInsert creates a new batch INSERT query within the transaction.
//
// This is a convenience method equivalent to tx.Builder().BatchInsert(table, columns).
//
// Example:
//
//	result, err := tx.BatchInsert("users", []string{"name", "email"}).
//	    Values("Alice", "alice@example.com").
//	    Values("Bob", "bob@example.com").
//	    Execute()
func (t *Tx) BatchInsert(table string, columns []string) *BatchInsertQuery {
	return t.Builder().BatchInsert(table, columns)
}

// BatchUpdate creates a new batch UPDATE query within the transaction.
//
// This is a convenience method equivalent to tx.Builder().BatchUpdate(table, keyColumn).
//
// Example:
//
//	result, err := tx.BatchUpdate("users", "id").
//	    Set(1, map[string]any{"name": "Alice"}).
//	    Set(2, map[string]any{"name": "Bob"}).
//	    Execute()
func (t *Tx) BatchUpdate(table, keyColumn string) *BatchUpdateQuery {
	return t.Builder().BatchUpdate(table, keyColumn)
}

// Upsert creates a new UPSERT query within the transaction.
//
// This is a convenience method equivalent to tx.Builder().Upsert(table, values).
//
// Example:
//
//	result, err := tx.Upsert("users", map[string]any{
//	    "email": "alice@example.com",
//	    "name":  "Alice",
//	}).OnConflict("email").DoUpdate("name").Execute()
func (t *Tx) Upsert(table string, values map[string]any) *UpsertQuery {
	return t.Builder().Upsert(table, values)
}

// NewQuery creates a raw SQL query within the transaction.
//
// This is a convenience method equivalent to tx.Builder()-based raw query execution.
//
// Example:
//
//	var count int
//	err := tx.NewQuery("SELECT COUNT(*) FROM users").Row(&count)
func (t *Tx) NewQuery(query string) *Query {
	return &Query{q: t.tx.NewQuery(query)}
}

// ============================================================================
// ModelQuery methods
// ============================================================================

// Insert inserts the model into the table.
//
// By default, all public fields are inserted. You can specify which fields
// to insert by passing their names, or use Exclude() to exclude specific fields.
//
// Example:
//
//	// Insert all fields.
//	err := db.Model(&user).Insert()
//
//	// Insert only specific fields.
//	err := db.Model(&user).Insert("name", "email")
//
//	// Exclude fields.
//	err := db.Model(&user).Exclude("created_at").Insert()
func (mq *ModelQuery) Insert(attrs ...string) error {
	return mq.mq.Insert(attrs...)
}

// Update updates the model in the table.
//
// The WHERE clause is automatically generated using the primary key.
// The primary key is detected from:
//  1. Field with db:"id" tag
//  2. Field with db:"*_id" tag (e.g., db:"user_id")
//  3. Field named "ID"
//
// Example:
//
//	user.Status = "active"
//	err := db.Model(&user).Update()
//	// UPDATE users SET name=?, email=?, status=? WHERE id=?
//
//	// Update only specific fields.
//	err := db.Model(&user).Update("status")
//	// UPDATE users SET status=? WHERE id=?
func (mq *ModelQuery) Update(attrs ...string) error {
	return mq.mq.Update(attrs...)
}

// Delete deletes the model from the table.
//
// The WHERE clause is automatically generated using the primary key.
//
// Example:
//
//	err := db.Model(&user).Delete()
//	// DELETE FROM users WHERE id=?
func (mq *ModelQuery) Delete() error {
	return mq.mq.Delete()
}

// Upsert performs an INSERT ... ON CONFLICT DO UPDATE for the model.
//
// Auto-detects the conflict column from the primary key.
// If fields are specified, only those fields are updated on conflict.
// If no fields are specified, all non-PK fields are updated on conflict.
//
// For PostgreSQL, the primary key is auto-populated after upsert (using RETURNING).
// For MySQL/SQLite, LastInsertId() is used when the PK is zero.
//
// Example:
//
//	user := User{ID: 1, Name: "Alice", Email: "alice@example.com"}
//	err := db.Model(&user).Upsert()
//	// INSERT INTO users (email, id, name) VALUES (?, ?, ?)
//	// ON CONFLICT (id) DO UPDATE SET email=EXCLUDED.email, name=EXCLUDED.name
//
//	// Update only specific fields on conflict:
//	err = db.Model(&user).Upsert("name")
//	// ON CONFLICT (id) DO UPDATE SET name=EXCLUDED.name
func (mq *ModelQuery) Upsert(fields ...string) error {
	return mq.mq.Upsert(fields...)
}

// UpsertOn performs INSERT ... ON CONFLICT with custom conflict columns.
// Use when the conflict target is a UNIQUE constraint, not the primary key.
//
// The first argument specifies conflict columns (the UNIQUE constraint).
// Remaining arguments specify which fields to update on conflict.
// If no fields are specified, all non-conflict columns are updated.
//
// Example:
//
//	// Schema: UNIQUE(project_id, qualified_name)
//	err := db.Model(&node).UpsertOn([]string{"project_id", "qualified_name"})
//	// ON CONFLICT ("project_id","qualified_name") DO UPDATE SET name=EXCLUDED.name, ...
//
//	// Selective update on conflict:
//	err := db.Model(&node).UpsertOn([]string{"email"}, "name", "status")
//	// ON CONFLICT ("email") DO UPDATE SET name=EXCLUDED.name, status=EXCLUDED.status
func (mq *ModelQuery) UpsertOn(conflictColumns []string, fields ...string) error {
	return mq.mq.UpsertOn(conflictColumns, fields...)
}

// Find fetches a record by primary key and populates the model.
// For single PK, pass one value. For composite PK, pass values
// in struct field declaration order. Returns ErrNotFound if not found.
//
// Example:
//
//	var user User
//	err := db.Model(&user).Find(42)
//	// SELECT * FROM users WHERE id = ? LIMIT 1
//
//	// Composite PK:
//	var item OrderItem
//	err := db.Model(&item).Find(orderId, itemId)
func (mq *ModelQuery) Find(pk ...any) error {
	return mq.mq.Find(pk...)
}

// UpdateChanged updates only the fields that differ between the current model
// and the original snapshot.
//
// It compares each field of the current model against original.
// Only changed fields are included in the UPDATE SET clause.
// Primary key fields are never included in the SET clause.
//
// If nothing has changed, no query is executed and nil is returned.
// The original parameter must be the same type as the model struct.
//
// Example:
//
//	var user User
//	db.Select().From("users").Where(relica.Eq("id", 1)).One(&user)
//
//	original := user
//	user.Name = "Alice Updated"
//	user.Status = "inactive"
//
//	err := db.Model(&user).UpdateChanged(&original)
//	// UPDATE users SET name=?, status=? WHERE id=?
func (mq *ModelQuery) UpdateChanged(original any) error {
	return mq.mq.UpdateChanged(original)
}

// Exclude excludes the specified fields from the operation.
//
// This is useful for auto-managed fields like timestamps.
//
// Example:
//
//	err := db.Model(&user).Exclude("created_at", "updated_at").Insert()
func (mq *ModelQuery) Exclude(attrs ...string) *ModelQuery {
	return &ModelQuery{mq: mq.mq.Exclude(attrs...)}
}

// Table overrides the table name for this operation.
//
// This is useful for partitioned tables or archival operations.
//
// Example:
//
//	err := db.Model(&user).Table("users_archive").Insert()
func (mq *ModelQuery) Table(name string) *ModelQuery {
	return &ModelQuery{mq: mq.mq.Table(name)}
}

// FindByPublicID finds a record by its autoid-tagged field value.
// Auto-detects the autoid column from struct tags and validates the prefix.
//
// This is the key method for the dual-key pattern: API handlers receive
// a public ID from the request and use this one-liner to find the record.
//
// Example:
//
//	var user User
//	err := db.Model(&user).FindByPublicID("usr_019078fa-b37e-7abc-...")
//	// Equivalent to: SELECT * FROM users WHERE public_id = ? LIMIT 1
//
//	// Prefix mismatch returns ErrAutoIDPrefixMismatch:
//	err = db.Model(&user).FindByPublicID("ord_019078fa-...")
//	// Error: autoid: prefix mismatch
func (mq *ModelQuery) FindByPublicID(publicID string) error {
	return mq.mq.FindByPublicID(publicID)
}

// WithContext sets the context for this model operation.
//
// The context is propagated to the underlying query execution,
// enabling cancellation and deadline support.
//
// Example:
//
//	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
//	defer cancel()
//	err := db.Model(&user).WithContext(ctx).Insert()
func (mq *ModelQuery) WithContext(ctx context.Context) *ModelQuery {
	return &ModelQuery{mq: mq.mq.WithContext(ctx)}
}

// ============================================================================
// QueryBuilder Methods
// ============================================================================

// WithContext sets the context for all queries built by this builder.
//
// The context will be used for all subsequent query operations unless
// overridden at the query level.
//
// Example:
//
//	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
//	defer cancel()
//	qb := db.Builder().WithContext(ctx)
//	qb.Select("*").From("users").All(&users)
func (qb *QueryBuilder) WithContext(ctx context.Context) *QueryBuilder {
	return &QueryBuilder{qb: qb.qb.WithContext(ctx)}
}

// Select starts a SELECT query with the specified columns.
//
// If no columns are provided, defaults to "*" (all columns).
//
// Example:
//
//	db.Builder().Select("id", "name", "email").From("users").All(&users)
func (qb *QueryBuilder) Select(cols ...string) *SelectQuery {
	return &SelectQuery{sq: qb.qb.Select(cols...)}
}

// Insert builds an INSERT query for a single row.
//
// The values parameter is a map of column names to values.
// Column order is deterministic (alphabetically sorted) for cache efficiency.
//
// Example:
//
//	result, err := db.Builder().Insert("users", map[string]any{
//	    "name": "Alice",
//	    "email": "alice@example.com",
//	    "status": 1,
//	}).Execute()
func (qb *QueryBuilder) Insert(table string, values map[string]any) *Query {
	return &Query{q: qb.qb.Insert(table, values)}
}

// InsertStruct builds an INSERT query from a struct using db tags.
//
// This is a convenience wrapper around Insert that converts the struct
// to a map using reflection. See DB.InsertStruct for full documentation.
//
// Example:
//
//	user := User{Name: "Alice", Email: "alice@example.com"}
//	result, err := db.Builder().InsertStruct("users", &user).Execute()
func (qb *QueryBuilder) InsertStruct(table string, data any) *Query {
	dataMap, err := util.StructToMap(data)
	if err != nil {
		return &Query{q: nil, err: err}
	}

	// Skip zero PK for auto-increment (same as Model().Insert())
	v := reflect.ValueOf(data)
	if v.Kind() == reflect.Pointer {
		v = v.Elem()
	}
	if v.Kind() == reflect.Struct {
		if pkInfo, err := util.FindPrimaryKeyFields(v); err == nil && pkInfo != nil && pkInfo.IsSingle() {
			if util.IsPrimaryKeyZero(pkInfo.Values[0]) {
				delete(dataMap, pkInfo.Columns[0])
			}
		}
	}

	return &Query{q: qb.qb.Insert(table, dataMap)}
}

// BatchInsertStruct builds a batch INSERT query from a slice of structs.
//
// This is a convenience wrapper that converts each struct in the slice
// to column values. See DB.BatchInsertStruct for full documentation.
//
// Example:
//
//	users := []User{
//	    {Name: "Alice", Email: "alice@example.com"},
//	    {Name: "Bob", Email: "bob@example.com"},
//	}
//	result, err := db.Builder().BatchInsertStruct("users", users).Execute()
//
//nolint:cyclop // Slice validation + PK detection + column extraction + row iteration require sequential steps.
func (qb *QueryBuilder) BatchInsertStruct(table string, data any) *Query {
	// Validate input is a slice.
	v := reflect.ValueOf(data)
	if v.Kind() != reflect.Slice {
		return &Query{q: nil, err: errors.New("BatchInsertStruct: expected slice, got " + v.Kind().String())}
	}

	if v.Len() == 0 {
		return &Query{q: nil, err: errors.New("BatchInsertStruct: empty slice")}
	}

	// Convert first element to get columns.
	firstMap, err := util.StructToMap(v.Index(0).Interface())
	if err != nil {
		return &Query{q: nil, err: err}
	}

	// Skip zero PK for auto-increment (same as Model().Insert())
	firstElem := v.Index(0)
	if firstElem.Kind() == reflect.Pointer {
		firstElem = firstElem.Elem()
	}
	if firstElem.Kind() == reflect.Struct {
		if pkInfo, err := util.FindPrimaryKeyFields(firstElem); err == nil && pkInfo != nil && pkInfo.IsSingle() {
			if util.IsPrimaryKeyZero(pkInfo.Values[0]) {
				delete(firstMap, pkInfo.Columns[0])
			}
		}
	}

	// Extract columns (sorted for consistency).
	columns := make([]string, 0, len(firstMap))
	for col := range firstMap {
		columns = append(columns, col)
	}
	sort.Strings(columns)

	// Build batch insert.
	biq := qb.qb.BatchInsert(table, columns)

	// Add all rows.
	for i := 0; i < v.Len(); i++ {
		rowMap, err := util.StructToMap(v.Index(i).Interface())
		if err != nil {
			return &Query{q: nil, err: err}
		}

		// Extract values in column order.
		values := make([]any, len(columns))
		for j, col := range columns {
			values[j] = rowMap[col]
		}

		biq = biq.Values(values...)
	}

	return &Query{q: biq.Build()}
}

// UpdateStruct builds an UPDATE query from a struct using db tags.
//
// This is a convenience wrapper around Update that converts the struct
// to a map using reflection. See DB.UpdateStruct for full documentation.
//
// Example:
//
//	user := User{Name: "Alice Updated", Status: "active"}
//	result, err := db.Builder().UpdateStruct("users", &user).
//	    Where("id = ?", user.ID).
//	    Execute()
func (qb *QueryBuilder) UpdateStruct(table string, data any) *UpdateQuery {
	dataMap, err := util.StructToMap(data)
	if err != nil {
		// Return UpdateQuery with error that will fail on Execute.
		return &UpdateQuery{uq: qb.qb.Update(table), err: err}
	}
	return &UpdateQuery{uq: qb.qb.Update(table).Set(dataMap)}
}

// Update creates an UPDATE query for the specified table.
//
// Use Set() to specify column values and Where() to filter rows.
//
// Example:
//
//	db.Builder().Update("users").
//	    Set(map[string]any{"status": 2}).
//	    Where("id = ?", 123).
//	    Execute()
func (qb *QueryBuilder) Update(table string) *UpdateQuery {
	return &UpdateQuery{uq: qb.qb.Update(table)}
}

// Delete creates a DELETE query for the specified table.
//
// Use Where() to filter rows to delete.
//
// Example:
//
//	db.Builder().Delete("users").
//	    Where("id = ?", 123).
//	    Execute()
func (qb *QueryBuilder) Delete(table string) *DeleteQuery {
	return &DeleteQuery{dq: qb.qb.Delete(table)}
}

// BatchInsert creates a batch INSERT query for multiple rows.
//
// This is 3.3x faster than individual INSERTs for 100 rows.
// Use Values() or ValuesMap() to add rows.
//
// Example:
//
//	db.Builder().BatchInsert("users", []string{"name", "email"}).
//	    Values("Alice", "alice@example.com").
//	    Values("Bob", "bob@example.com").
//	    Execute()
func (qb *QueryBuilder) BatchInsert(table string, columns []string) *BatchInsertQuery {
	return &BatchInsertQuery{biq: qb.qb.BatchInsert(table, columns)}
}

// BatchUpdate creates a batch UPDATE query for multiple rows.
//
// This is 2.5x faster than individual UPDATEs for 100 rows.
// Uses CASE-WHEN logic to update multiple rows with different values.
//
// Example:
//
//	db.Builder().BatchUpdate("users", "id").
//	    Set(1, map[string]any{"status": 2}).
//	    Set(2, map[string]any{"status": 3}).
//	    Execute()
func (qb *QueryBuilder) BatchUpdate(table, keyColumn string) *BatchUpdateQuery {
	return &BatchUpdateQuery{buq: qb.qb.BatchUpdate(table, keyColumn)}
}

// Upsert creates an UPSERT query (INSERT with conflict resolution).
//
// Supported strategies:
//   - PostgreSQL/SQLite: ON CONFLICT ... DO UPDATE
//   - MySQL: ON DUPLICATE KEY UPDATE
//
// Example:
//
//	db.Builder().Upsert("users", map[string]any{
//	    "id": 1,
//	    "name": "Alice",
//	    "email": "alice@example.com",
//	}).OnConflict("id").DoUpdate("name", "email").Execute()
func (qb *QueryBuilder) Upsert(table string, values map[string]any) *UpsertQuery {
	return &UpsertQuery{uq: qb.qb.Upsert(table, values)}
}

// Unwrap returns the underlying core.QueryBuilder for advanced use cases.
//
// This method is provided for edge cases where direct access to
// internal types is needed. Most users should not need this.
func (qb *QueryBuilder) Unwrap() *core.QueryBuilder {
	return qb.qb
}

// ============================================================================
// SelectQuery Methods (40+ methods)
// ============================================================================

// WithContext sets the context for this SELECT query.
//
// This overrides any context set on the QueryBuilder.
//
// Example:
//
//	sq.WithContext(ctx).All(&users)
func (sq *SelectQuery) WithContext(ctx context.Context) *SelectQuery {
	return &SelectQuery{sq: sq.sq.WithContext(ctx)}
}

// From specifies the table to select from.
//
// Supports table aliases: From("users u")
//
// Example:
//
//	db.Builder().Select("*").From("users").All(&users)
func (sq *SelectQuery) From(table string) *SelectQuery {
	sq.sq.From(table)
	return sq
}

// FromSelect specifies a subquery as the FROM source.
//
// The alias parameter is required for the subquery.
//
// Example:
//
//	sub := db.Builder().Select("user_id", "COUNT(*) as cnt").
//	    From("orders").GroupBy("user_id")
//	db.Builder().Select("*").FromSelect(sub, "order_counts").
//	    Where("cnt > ?", 10).All(&results)
func (sq *SelectQuery) FromSelect(subquery *SelectQuery, alias string) *SelectQuery {
	sq.sq.FromSelect(subquery.sq, alias)
	return sq
}

// SelectExpr adds a raw SQL expression to the SELECT clause.
//
// Useful for scalar subqueries, window functions, or complex expressions.
//
// Example:
//
//	db.Builder().Select("id", "name").
//	    SelectExpr("(SELECT COUNT(*) FROM orders WHERE orders.user_id = users.id)", "order_count").
//	    From("users").All(&results)
func (sq *SelectQuery) SelectExpr(expr string, args ...any) *SelectQuery {
	sq.sq.SelectExpr(expr, args...)
	return sq
}

// AndSelect appends additional columns to the SELECT clause.
// Useful for conditional column building where columns are added based on runtime conditions.
//
// Example:
//
//	q := db.Select("id", "name").From("users")
//	if includeEmail {
//	    q = q.AndSelect("email")
//	}
//	if includePhone {
//	    q = q.AndSelect("phone")
//	}
func (sq *SelectQuery) AndSelect(cols ...string) *SelectQuery {
	sq.sq.AndSelect(cols...)
	return sq
}

// SelectSub adds a type-safe subquery or computed expression to the SELECT clause with a quoted alias.
// The expression is built with the correct dialect so identifiers are properly quoted.
// Prefer SelectSub over SelectExpr when you have an Expression (e.g. a correlated subquery).
//
// Example:
//
//	sub := db.Builder().Select("COUNT(*)").From("orders").Where(relica.EqCol("orders.user_id", "users.id"))
//	db.Builder().Select("id", "name").SelectSub(sub.AsExpression(), "order_count").From("users").All(&results)
//
// Generates (PostgreSQL):
//
//	SELECT "id", "name", (SELECT COUNT(*) FROM "orders" WHERE "orders"."user_id" = "users"."id") AS "order_count" FROM "users"
func (sq *SelectQuery) SelectSub(exp Expression, alias string) *SelectQuery {
	sq.sq.SelectSub(exp, alias)
	return sq
}

// Where adds a WHERE condition.
//
// Accepts either a string with placeholders or an Expression.
// Multiple Where() calls are combined with AND.
//
// String example:
//
//	Where("status = ? AND age > ?", 1, 18)
//
// Expression example:
//
//	Where(relica.And(
//	    relica.Eq("status", 1),
//	    relica.GreaterThan("age", 18),
//	))
func (sq *SelectQuery) Where(condition any, params ...any) *SelectQuery {
	sq.sq.Where(condition, params...)
	return sq
}

// AndWhere adds a WHERE condition with AND logic.
// If no existing WHERE clause exists, behaves like Where().
//
// Example:
//
//	db.Builder().Select("*").From("users").
//	    Where("status = ?", 1).
//	    AndWhere("age > ?", 18)
func (sq *SelectQuery) AndWhere(condition any, params ...any) *SelectQuery {
	sq.sq.AndWhere(condition, params...)
	return sq
}

// OrWhere adds a WHERE condition with OR logic.
// If no existing WHERE clause exists, behaves like Where().
//
// Example:
//
//	db.Builder().Select("*").From("users").
//	    Where("status = ?", 1).
//	    OrWhere("role = ?", "admin")
func (sq *SelectQuery) OrWhere(condition any, params ...any) *SelectQuery {
	sq.sq.OrWhere(condition, params...)
	return sq
}

// InnerJoin adds an INNER JOIN clause.
//
// Example:
//
//	db.Builder().Select("u.name", "o.total").
//	    From("users u").
//	    InnerJoin("orders o", "o.user_id = u.id").
//	    All(&results)
func (sq *SelectQuery) InnerJoin(table string, on any) *SelectQuery {
	sq.sq.InnerJoin(table, on)
	return sq
}

// LeftJoin adds a LEFT JOIN clause.
//
// Example:
//
//	db.Builder().Select("u.name", "o.total").
//	    From("users u").
//	    LeftJoin("orders o", "o.user_id = u.id").
//	    All(&results)
func (sq *SelectQuery) LeftJoin(table string, on any) *SelectQuery {
	sq.sq.LeftJoin(table, on)
	return sq
}

// RightJoin adds a RIGHT JOIN clause.
//
// Example:
//
//	db.Builder().Select("u.name", "o.total").
//	    From("users u").
//	    RightJoin("orders o", "o.user_id = u.id").
//	    All(&results)
func (sq *SelectQuery) RightJoin(table string, on any) *SelectQuery {
	sq.sq.RightJoin(table, on)
	return sq
}

// FullJoin adds a FULL OUTER JOIN clause.
//
// Note: Not supported by MySQL.
//
// Example:
//
//	db.Builder().Select("u.name", "o.total").
//	    From("users u").
//	    FullJoin("orders o", "o.user_id = u.id").
//	    All(&results)
func (sq *SelectQuery) FullJoin(table string, on any) *SelectQuery {
	sq.sq.FullJoin(table, on)
	return sq
}

// CrossJoin adds a CROSS JOIN clause (Cartesian product).
//
// Example:
//
//	db.Builder().Select("*").
//	    From("colors").
//	    CrossJoin("sizes").
//	    All(&results)
func (sq *SelectQuery) CrossJoin(table string) *SelectQuery {
	sq.sq.CrossJoin(table)
	return sq
}

// OrderBy adds ORDER BY clause with optional direction (ASC/DESC).
//
// Supports multiple columns. Multiple OrderBy() calls are additive.
//
// Example:
//
//	OrderBy("age DESC", "name ASC")
func (sq *SelectQuery) OrderBy(columns ...string) *SelectQuery {
	sq.sq.OrderBy(columns...)
	return sq
}

// OrderByExpr adds a raw SQL expression to the ORDER BY clause.
// The expression is used as-is without quoting — useful for CASE WHEN,
// complex functions, or any expression that shouldn't be treated as a column name.
//
// Example:
//
//	OrderByExpr("CASE WHEN status = ? THEN 0 ELSE 1 END", "active")
//	OrderByExpr("FIELD(id, ?, ?, ?)", 3, 1, 2)
func (sq *SelectQuery) OrderByExpr(expr string, args ...any) *SelectQuery {
	sq.sq.OrderByExpr(expr, args...)
	return sq
}

// OrderBySub adds a type-safe expression to the ORDER BY clause.
// Use with CaseWhen() or any Expression builder instead of raw SQL strings.
//
// Example:
//
//	db.Select("id", "title").From("tasks t").
//	    OrderBySub(relica.CaseWhen().
//	        When("t.due_date < CURRENT_DATE", 0).
//	        When("t.due_date IS NULL", 3).
//	        Else(1)).
//	    OrderBy("t.due_date ASC").
//	    All(&rows)
func (sq *SelectQuery) OrderBySub(exp Expression) *SelectQuery {
	sq.sq.OrderBySub(exp)
	return sq
}

// Limit sets the LIMIT clause.
//
// Example:
//
//	Limit(100)  // Return at most 100 rows
func (sq *SelectQuery) Limit(limit int64) *SelectQuery {
	sq.sq.Limit(limit)
	return sq
}

// Offset sets the OFFSET clause.
//
// Example:
//
//	Offset(200)  // Skip first 200 rows
func (sq *SelectQuery) Offset(offset int64) *SelectQuery {
	sq.sq.Offset(offset)
	return sq
}

// GroupBy adds GROUP BY clause.
//
// Multiple columns supported. Multiple GroupBy() calls are additive.
//
// Example:
//
//	GroupBy("user_id", "status")
func (sq *SelectQuery) GroupBy(columns ...string) *SelectQuery {
	sq.sq.GroupBy(columns...)
	return sq
}

// GroupByExpr adds a raw SQL expression to the GROUP BY clause.
// The expression is used as-is without quoting.
//
// Example:
//
//	GroupByExpr("DATE(created_at)")
//	GroupByExpr("EXTRACT(YEAR FROM order_date)")
func (sq *SelectQuery) GroupByExpr(expr string, args ...any) *SelectQuery {
	sq.sq.GroupByExpr(expr, args...)
	return sq
}

// GroupBySub adds a type-safe expression to the GROUP BY clause.
func (sq *SelectQuery) GroupBySub(exp Expression) *SelectQuery {
	sq.sq.GroupBySub(exp)
	return sq
}

// Having adds HAVING clause (WHERE for aggregates).
//
// Accepts string or Expression. Multiple calls are combined with AND.
//
// Example:
//
//	Having("COUNT(*) > ?", 100)
func (sq *SelectQuery) Having(condition any, args ...any) *SelectQuery {
	sq.sq.Having(condition, args...)
	return sq
}

// Distinct adds the DISTINCT keyword to the SELECT clause, eliminating duplicate rows.
//
// Example:
//
//	db.Builder().Select("category").From("products").Distinct().All(&categories)
//	// SELECT DISTINCT "category" FROM "products"
func (sq *SelectQuery) Distinct() *SelectQuery {
	sq.sq.Distinct()
	return sq
}

// ForUpdate adds FOR UPDATE clause for pessimistic row-level exclusive locking.
// Silently ignored for SQLite (uses database-level locking).
func (sq *SelectQuery) ForUpdate() *SelectQuery {
	sq.sq.ForUpdate()
	return sq
}

// ForShare adds FOR SHARE clause for shared row-level locking.
// Silently ignored for SQLite.
func (sq *SelectQuery) ForShare() *SelectQuery {
	sq.sq.ForShare()
	return sq
}

// ForUpdateSkipLocked adds FOR UPDATE SKIP LOCKED for non-blocking lock acquisition.
// Useful for job queue patterns. PostgreSQL 9.5+ and MySQL 8.0+. Silently ignored for SQLite.
func (sq *SelectQuery) ForUpdateSkipLocked() *SelectQuery {
	sq.sq.ForUpdateSkipLocked()
	return sq
}

// Union combines this query with another using UNION (removes duplicates).
//
// Example:
//
//	q1 := db.Builder().Select("name").From("users")
//	q2 := db.Builder().Select("name").From("archived_users")
//	q1.Union(q2).All(&names)
func (sq *SelectQuery) Union(other *SelectQuery) *SelectQuery {
	sq.sq.Union(other.sq)
	return sq
}

// UnionAll combines this query with another using UNION ALL (keeps duplicates).
//
// Example:
//
//	q1 := db.Builder().Select("id").From("orders_2023")
//	q2 := db.Builder().Select("id").From("orders_2024")
//	q1.UnionAll(q2).All(&orderIDs)
func (sq *SelectQuery) UnionAll(other *SelectQuery) *SelectQuery {
	sq.sq.UnionAll(other.sq)
	return sq
}

// Intersect combines queries using INTERSECT (rows in both).
//
// Database support: PostgreSQL 9.1+, MySQL 8.0.31+, SQLite 3.25+
//
// Example:
//
//	q1 := db.Builder().Select("id").From("users")
//	q2 := db.Builder().Select("user_id").From("orders")
//	q1.Intersect(q2).All(&ids)  // Users who have placed orders
func (sq *SelectQuery) Intersect(other *SelectQuery) *SelectQuery {
	sq.sq.Intersect(other.sq)
	return sq
}

// Except combines queries using EXCEPT (rows in first but not second).
//
// Database support: PostgreSQL 9.1+, MySQL 8.0.31+, SQLite 3.25+
//
// Example:
//
//	q1 := db.Builder().Select("id").From("all_users")
//	q2 := db.Builder().Select("user_id").From("banned_users")
//	q1.Except(q2).All(&activeUsers)
func (sq *SelectQuery) Except(other *SelectQuery) *SelectQuery {
	sq.sq.Except(other.sq)
	return sq
}

// With adds a Common Table Expression (CTE).
//
// Example:
//
//	cte := db.Builder().Select("user_id", "SUM(total) as total").
//	    From("orders").GroupBy("user_id")
//	db.Builder().Select("*").With("order_totals", cte).
//	    From("order_totals").Where("total > ?", 1000).All(&users)
func (sq *SelectQuery) With(name string, query *SelectQuery) *SelectQuery {
	sq.sq.With(name, query.sq)
	return sq
}

// WithRecursive adds a recursive Common Table Expression.
//
// The query MUST use UNION or UNION ALL.
// Database support: PostgreSQL (all), MySQL 8.0+, SQLite 3.25+
//
// Example:
//
//	anchor := db.Builder().Select("id", "name", "manager_id", "1 as level").
//	    From("employees").Where("manager_id IS NULL")
//	recursive := db.Builder().Select("e.id", "e.name", "e.manager_id", "h.level + 1").
//	    From("employees e").InnerJoin("hierarchy h", "e.manager_id = h.id")
//	cte := anchor.UnionAll(recursive)
//	db.Builder().Select("*").WithRecursive("hierarchy", cte).
//	    From("hierarchy").OrderBy("level", "name").All(&employees)
func (sq *SelectQuery) WithRecursive(name string, query *SelectQuery) *SelectQuery {
	sq.sq.WithRecursive(name, query.sq)
	return sq
}

// Build constructs the Query object from SelectQuery.
//
// Example:
//
//	q := db.Builder().Select("*").From("users").Where("id = ?", 123).Build()
//	sql, params := q.SQL(), q.Params()
func (sq *SelectQuery) Build() *Query {
	return &Query{q: sq.sq.Build()}
}

// Model reads PK values from dest struct, auto-detects table (if From not set),
// appends PK WHERE conditions, and scans a single row into dest.
// Terminal method — executes the query and returns error.
//
// Example:
//
//	// Simple PK fetch
//	user := User{ID: 42}
//	err := db.Select().Model(&user)
//
//	// Partial read with WHERE filter
//	user := User{ID: 42}
//	err := db.Select("name", "email").Where(relica.IsNull("deleted_at")).Model(&user)
//
//	// Composite PK
//	item := OrderItem{OrderID: 100, ItemID: 20}
//	err := db.Select().Model(&item)
func (sq *SelectQuery) Model(dest any) error {
	return sq.sq.Model(dest)
}

// One scans a single row into dest.
//
// Returns sql.ErrNoRows if no row is found.
//
// Example:
//
//	var user User
//	err := db.Builder().Select("*").From("users").
//	    Where("id = ?", 123).One(&user)
func (sq *SelectQuery) One(dest any) error {
	return sq.sq.One(dest)
}

// All scans all rows into dest slice.
//
// Example:
//
//	var users []User
//	err := db.Builder().Select("*").From("users").All(&users)
func (sq *SelectQuery) All(dest any) error {
	return sq.sq.All(dest)
}

// Row scans a single row into individual variables.
// Returns sql.ErrNoRows if no rows are found.
//
// Example:
//
//	var name string
//	var age int
//	err := db.Builder().Select("name", "age").From("users").
//	    Where("id = ?", 1).Row(&name, &age)
func (sq *SelectQuery) Row(dest ...any) error {
	return sq.sq.Row(dest...)
}

// Column scans the first column of all rows into a slice.
// The slice parameter must be a pointer to a slice of the appropriate type.
//
// Example:
//
//	var ids []int
//	err := db.Builder().Select("id").From("users").
//	    Where("status = ?", "active").Column(&ids)
func (sq *SelectQuery) Column(slice any) error {
	return sq.sq.Column(slice)
}

// Count executes a COUNT(*) query and returns the number of matching rows.
// Any columns specified in Select() are ignored; COUNT(*) is always used.
//
// Example:
//
//	count, err := db.Select().From("users").Where(relica.Eq("status", 1)).Count()
func (sq *SelectQuery) Count() (int64, error) {
	return sq.sq.Count()
}

// Exists executes the query wrapped in SELECT EXISTS(...) and returns true if any rows match.
//
// Example:
//
//	exists, err := db.Select().From("users").Where(relica.Eq("email", email)).Exists()
func (sq *SelectQuery) Exists() (bool, error) {
	return sq.sq.Exists()
}

// ToSQL returns the SQL string and parameters without executing the query.
// This is useful for debugging, logging, or passing the query to another layer.
//
// Example:
//
//	sql, params := db.Select().From("users").Where(relica.Eq("id", 1)).ToSQL()
func (sq *SelectQuery) ToSQL() (string, []any) {
	return sq.sq.ToSQL()
}

// Explain analyzes the query execution plan without executing the query.
// Returns [QueryPlan] with estimated metrics (cost, rows, index usage).
// Supported databases: PostgreSQL, MySQL, SQLite.
//
// Example:
//
//	plan, err := db.Select("*").From("users").Where(relica.Eq("email", "alice@example.com")).Explain()
//	if err != nil {
//	    return err
//	}
//	fmt.Printf("Cost: %.2f, Rows: %d, Uses Index: %v\n",
//	    plan.Cost, plan.EstimatedRows, plan.UsesIndex)
func (sq *SelectQuery) Explain() (*QueryPlan, error) {
	return sq.sq.Explain()
}

// ExplainAnalyze analyzes the query execution plan AND executes the query.
// Returns [QueryPlan] with both estimated and actual execution metrics.
// Supported databases: PostgreSQL, MySQL 8.0.18+.
//
// WARNING: This method ACTUALLY EXECUTES the query, including any side effects
// (INSERT, UPDATE, DELETE in CTEs, triggers, etc.). Use with caution in production.
//
// Example:
//
//	plan, err := db.Select("*").From("users").Where(relica.Eq("status", 1)).ExplainAnalyze()
//	if err != nil {
//	    return err
//	}
//	fmt.Printf("Actual Time: %v, Actual Rows: %d, Buffers Hit: %d\n",
//	    plan.ActualTime, plan.ActualRows, plan.BuffersHit)
func (sq *SelectQuery) ExplainAnalyze() (*QueryPlan, error) {
	return sq.sq.ExplainAnalyze()
}

// AsExpression converts a SelectQuery to an Expression for subquery use.
//
// Example:
//
//	sub := db.Builder().Select("user_id").From("orders").Where("total > ?", 100)
//	db.Builder().Select("*").From("users").
//	    Where(relica.In("id", sub.AsExpression())).All(&users)
func (sq *SelectQuery) AsExpression() Expression {
	return sq.sq.AsExpression()
}

// Unwrap returns the underlying core.SelectQuery for advanced use cases.
//
// This method is provided for edge cases where direct access to
// internal types is needed. Most users should not need this.
func (sq *SelectQuery) Unwrap() *core.SelectQuery {
	return sq.sq
}

// ============================================================================
// UpdateQuery Methods
// ============================================================================

// UpdateQuery represents an UPDATE query being built.
type UpdateQuery struct {
	uq  *core.UpdateQuery
	err error // Error from query construction (e.g., struct conversion).
}

// WithContext sets the context for this UPDATE query.
func (uq *UpdateQuery) WithContext(ctx context.Context) *UpdateQuery {
	return &UpdateQuery{uq: uq.uq.WithContext(ctx), err: uq.err}
}

// Set specifies the columns and values to update.
//
// Example:
//
//	Update("users").Set(map[string]any{"status": 2})
func (uq *UpdateQuery) Set(values map[string]any) *UpdateQuery {
	uq.uq.Set(values)
	return uq
}

// Where adds a WHERE condition to the UPDATE query.
//
// Example:
//
//	Update("users").Set(...).Where("id = ?", 123)
func (uq *UpdateQuery) Where(condition any, params ...any) *UpdateQuery {
	uq.uq.Where(condition, params...)
	return uq
}

// AndWhere adds a WHERE condition with AND logic.
// If no existing WHERE clause exists, behaves like Where().
//
// Example:
//
//	db.Builder().Update("users").
//	    Set(map[string]any{"status": 2}).
//	    Where("id > ?", 100).
//	    AndWhere("active = ?", true)
func (uq *UpdateQuery) AndWhere(condition any, params ...any) *UpdateQuery {
	uq.uq.AndWhere(condition, params...)
	return uq
}

// OrWhere adds a WHERE condition with OR logic.
// If no existing WHERE clause exists, behaves like Where().
//
// Example:
//
//	db.Builder().Update("users").
//	    Set(map[string]any{"status": 0}).
//	    Where("banned = ?", true).
//	    OrWhere("deleted = ?", true)
func (uq *UpdateQuery) OrWhere(condition any, params ...any) *UpdateQuery {
	uq.uq.OrWhere(condition, params...)
	return uq
}

// Build constructs the Query object.
func (uq *UpdateQuery) Build() *Query {
	if uq.err != nil {
		return &Query{q: nil, err: uq.err}
	}
	return &Query{q: uq.uq.Build()}
}

// Execute executes the UPDATE query.
func (uq *UpdateQuery) Execute() (sql.Result, error) {
	if uq.err != nil {
		return nil, uq.err
	}
	return uq.Build().Execute()
}

// ToSQL returns the SQL string and parameters without executing the query.
// This is useful for debugging, logging, or passing the query to another layer.
//
// Example:
//
//	sql, params := db.Update("users").Set(map[string]any{"status": 1}).Where(relica.Eq("id", 1)).ToSQL()
func (uq *UpdateQuery) ToSQL() (string, []any) {
	if uq.err != nil {
		return "", nil
	}
	return uq.uq.ToSQL()
}

// ============================================================================
// DeleteQuery Methods
// ============================================================================

// DeleteQuery represents a DELETE query being built.
type DeleteQuery struct {
	dq *core.DeleteQuery
}

// WithContext sets the context for this DELETE query.
func (dq *DeleteQuery) WithContext(ctx context.Context) *DeleteQuery {
	return &DeleteQuery{dq: dq.dq.WithContext(ctx)}
}

// Where adds a WHERE condition to the DELETE query.
//
// Example:
//
//	Delete("users").Where("id = ?", 123)
func (dq *DeleteQuery) Where(condition any, params ...any) *DeleteQuery {
	dq.dq.Where(condition, params...)
	return dq
}

// AndWhere adds a WHERE condition with AND logic.
// If no existing WHERE clause exists, behaves like Where().
//
// Example:
//
//	db.Builder().Delete("users").
//	    Where("status = ?", 0).
//	    AndWhere("created_at < ?", "2020-01-01")
func (dq *DeleteQuery) AndWhere(condition any, params ...any) *DeleteQuery {
	dq.dq.AndWhere(condition, params...)
	return dq
}

// OrWhere adds a WHERE condition with OR logic.
// If no existing WHERE clause exists, behaves like Where().
//
// Example:
//
//	db.Builder().Delete("users").
//	    Where("banned = ?", true).
//	    OrWhere("deleted = ?", true)
func (dq *DeleteQuery) OrWhere(condition any, params ...any) *DeleteQuery {
	dq.dq.OrWhere(condition, params...)
	return dq
}

// Build constructs the Query object.
func (dq *DeleteQuery) Build() *Query {
	return &Query{q: dq.dq.Build()}
}

// Execute executes the DELETE query.
func (dq *DeleteQuery) Execute() (sql.Result, error) {
	return dq.Build().Execute()
}

// ToSQL returns the SQL string and parameters without executing the query.
// This is useful for debugging, logging, or passing the query to another layer.
//
// Example:
//
//	sql, params := db.Delete("users").Where(relica.Eq("id", 1)).ToSQL()
func (dq *DeleteQuery) ToSQL() (string, []any) {
	return dq.dq.ToSQL()
}

// ============================================================================
// UpsertQuery Methods
// ============================================================================

// UpsertQuery represents an UPSERT query being built.
type UpsertQuery struct {
	uq *core.UpsertQuery
}

// WithContext sets the context for this UPSERT query.
func (uq *UpsertQuery) WithContext(ctx context.Context) *UpsertQuery {
	return &UpsertQuery{uq: uq.uq.WithContext(ctx)}
}

// OnConflict specifies the columns that determine a conflict.
//
// Example:
//
//	Upsert(...).OnConflict("id", "email")
func (uq *UpsertQuery) OnConflict(columns ...string) *UpsertQuery {
	uq.uq.OnConflict(columns...)
	return uq
}

// DoUpdate specifies which columns to update on conflict.
//
// Example:
//
//	Upsert(...).OnConflict("id").DoUpdate("name", "email")
func (uq *UpsertQuery) DoUpdate(columns ...string) *UpsertQuery {
	uq.uq.DoUpdate(columns...)
	return uq
}

// DoNothing ignores conflicts (no update).
//
// Example:
//
//	Upsert(...).OnConflict("id").DoNothing()
func (uq *UpsertQuery) DoNothing() *UpsertQuery {
	uq.uq.DoNothing()
	return uq
}

// Build constructs the Query object.
func (uq *UpsertQuery) Build() *Query {
	return &Query{q: uq.uq.Build()}
}

// Execute executes the UPSERT query.
func (uq *UpsertQuery) Execute() (sql.Result, error) {
	return uq.Build().Execute()
}

// ToSQL returns the SQL string and parameters without executing the query.
// This is useful for debugging, logging, or passing the query to another layer.
//
// Example:
//
//	sql, params := db.Upsert("users", map[string]any{"id": 1, "name": "Alice"}).
//	    OnConflict("id").DoUpdate("name").ToSQL()
func (uq *UpsertQuery) ToSQL() (string, []any) {
	q := uq.Build()
	return q.SQL(), q.Params()
}

// ============================================================================
// BatchInsertQuery Methods
// ============================================================================

// BatchInsertQuery represents a batch INSERT query being built.
type BatchInsertQuery struct {
	biq *core.BatchInsertQuery
}

// WithContext sets the context for this batch INSERT query.
func (biq *BatchInsertQuery) WithContext(ctx context.Context) *BatchInsertQuery {
	return &BatchInsertQuery{biq: biq.biq.WithContext(ctx)}
}

// Values adds a row of values to the batch insert.
//
// Example:
//
//	BatchInsert("users", []string{"name", "email"}).
//	    Values("Alice", "alice@example.com").
//	    Values("Bob", "bob@example.com")
func (biq *BatchInsertQuery) Values(values ...any) *BatchInsertQuery {
	biq.biq.Values(values...)
	return biq
}

// ValuesMap adds a row from a map.
//
// Example:
//
//	BatchInsert("users", []string{"name", "email"}).
//	    ValuesMap(map[string]any{"name": "Alice", "email": "alice@example.com"})
func (biq *BatchInsertQuery) ValuesMap(values map[string]any) *BatchInsertQuery {
	biq.biq.ValuesMap(values)
	return biq
}

// Build constructs the Query object.
func (biq *BatchInsertQuery) Build() *Query {
	return &Query{q: biq.biq.Build()}
}

// OnConflict specifies the conflict columns for upsert behavior.
//
// Example:
//
//	db.BatchInsert("nodes", []string{"name", "label"}).
//	    Values("Foo", "struct").
//	    OnConflict("project_id", "qualified_name").
//	    DoUpdate("name", "label").
//	    Execute()
func (biq *BatchInsertQuery) OnConflict(columns ...string) *BatchInsertQuery {
	biq.biq.OnConflict(columns...)
	return biq
}

// DoUpdate specifies which columns to update on conflict.
// If not called (but OnConflict is set), all non-conflict columns are updated.
func (biq *BatchInsertQuery) DoUpdate(columns ...string) *BatchInsertQuery {
	biq.biq.DoUpdate(columns...)
	return biq
}

// DoNothing specifies that conflicting rows should be silently ignored.
func (biq *BatchInsertQuery) DoNothing() *BatchInsertQuery {
	biq.biq.DoNothing()
	return biq
}

// Execute executes the batch INSERT query.
func (biq *BatchInsertQuery) Execute() (sql.Result, error) {
	return biq.Build().Execute()
}

// ToSQL returns the SQL string and parameters without executing the query.
// This is useful for debugging, logging, or passing the query to another layer.
//
// Example:
//
//	sql, params := db.BatchInsert("users", []string{"name", "email"}).
//	    Values("Alice", "alice@example.com").ToSQL()
func (biq *BatchInsertQuery) ToSQL() (string, []any) {
	q := biq.Build()
	return q.SQL(), q.Params()
}

// ============================================================================
// BatchUpdateQuery Methods
// ============================================================================

// BatchUpdateQuery represents a batch UPDATE query being built.
type BatchUpdateQuery struct {
	buq *core.BatchUpdateQuery
}

// WithContext sets the context for this batch UPDATE query.
func (buq *BatchUpdateQuery) WithContext(ctx context.Context) *BatchUpdateQuery {
	return &BatchUpdateQuery{buq: buq.buq.WithContext(ctx)}
}

// Set adds a row update to the batch.
//
// Example:
//
//	BatchUpdate("users", "id").
//	    Set(1, map[string]any{"status": 2}).
//	    Set(2, map[string]any{"status": 3})
func (buq *BatchUpdateQuery) Set(keyValue any, values map[string]any) *BatchUpdateQuery {
	buq.buq.Set(keyValue, values)
	return buq
}

// Build constructs the Query object.
func (buq *BatchUpdateQuery) Build() *Query {
	return &Query{q: buq.buq.Build()}
}

// Execute executes the batch UPDATE query.
func (buq *BatchUpdateQuery) Execute() (sql.Result, error) {
	return buq.Build().Execute()
}

// ToSQL returns the SQL string and parameters without executing the query.
// This is useful for debugging, logging, or passing the query to another layer.
//
// Example:
//
//	sql, params := db.BatchUpdate("users", "id").
//	    Set(1, map[string]any{"status": 2}).ToSQL()
func (buq *BatchUpdateQuery) ToSQL() (string, []any) {
	q := buq.Build()
	return q.SQL(), q.Params()
}

// ============================================================================
// Query Methods
// ============================================================================

// Execute runs the query and returns results.
func (q *Query) Execute() (sql.Result, error) {
	if q.err != nil {
		return nil, q.err
	}
	result, err := q.q.Execute()
	if err != nil {
		return nil, err
	}
	return result, nil
}

// One fetches a single row into dest.
func (q *Query) One(dest any) error {
	if q.err != nil {
		return q.err
	}
	return q.q.One(dest)
}

// All fetches all rows into dest slice.
func (q *Query) All(dest any) error {
	if q.err != nil {
		return q.err
	}
	return q.q.All(dest)
}

// Row scans a single row into individual variables.
// Returns sql.ErrNoRows if no rows are found.
//
// Example:
//
//	var name string
//	var age int
//	err := db.Select("name", "age").From("users").Where("id = ?", 1).Row(&name, &age)
func (q *Query) Row(dest ...any) error {
	if q.err != nil {
		return q.err
	}
	return q.q.Row(dest...)
}

// Column scans the first column of all rows into a slice.
// The slice parameter must be a pointer to a slice of the appropriate type.
//
// Example:
//
//	var ids []int
//	err := db.Select("id").From("users").Where("status = ?", "active").Column(&ids)
func (q *Query) Column(slice any) error {
	if q.err != nil {
		return q.err
	}
	return q.q.Column(slice)
}

// Prepare prepares the query for repeated execution.
// Call Close() when done to release the prepared statement.
// The prepared statement bypasses the automatic statement cache,
// giving you full control over the statement lifecycle.
//
// Example:
//
//	q := db.NewQuery("SELECT * FROM users WHERE status = ?").Prepare()
//	defer q.Close()
//
//	for _, status := range statuses {
//	    var users []User
//	    q.Bind(status).All(&users)
//	    // process users...
//	}
func (q *Query) Prepare() *Query {
	if q.err != nil {
		return q
	}
	q.q.Prepare()
	return q
}

// Close releases the prepared statement.
// Safe to call multiple times or on non-prepared queries.
// Returns nil if query was not prepared or already closed.
func (q *Query) Close() error {
	if q.q != nil {
		return q.q.Close()
	}
	return nil
}

// IsPrepared returns true if Prepare() was called successfully.
func (q *Query) IsPrepared() bool {
	if q.q == nil {
		return false
	}
	return q.q.IsPrepared()
}

// Bind sets positional parameters for the query.
// Parameters replace ? placeholders in order.
//
// Example:
//
//	db.NewQuery("SELECT * FROM users WHERE id = ? AND status = ?").
//	    Bind(1, "active").
//	    One(&user)
func (q *Query) Bind(params ...any) *Query {
	if q.err != nil {
		return q
	}
	q.q.Bind(params...)
	return q
}

// BindParams binds named parameters using Params map.
// Named parameters are specified using {:name} syntax.
//
// Example:
//
//	db.NewQuery("SELECT * FROM users WHERE id = {:id}").
//	    BindParams(relica.Params{"id": 1}).
//	    One(&user)
func (q *Query) BindParams(params Params) *Query {
	if q.err != nil {
		return q
	}
	q.q.BindParams(params)
	return q
}

// ToSQL returns the SQL string and parameters without executing the query.
// This provides a consistent interface across all query types (Select, Insert, Update, Delete, Upsert).
//
// Example:
//
//	sql, params := db.Insert("users", map[string]any{
//	    "name": "Alice", "email": "alice@example.com",
//	}).ToSQL()
//	// sql: INSERT INTO "users" ("email", "name") VALUES ($1, $2)
//	// params: [alice@example.com Alice]
func (q *Query) ToSQL() (string, []any) {
	if q.q == nil {
		return "", nil
	}
	return q.q.ToSQL()
}

// SQL returns the SQL query string.
func (q *Query) SQL() string {
	if q.q == nil {
		return ""
	}
	return q.q.SQL()
}

// Params returns the query parameters.
func (q *Query) Params() []any {
	if q.q == nil {
		return nil
	}
	return q.q.Params()
}

// QueryParams returns the query parameters.
//
// Deprecated: Use Params instead.
func (q *Query) QueryParams() []any {
	return q.Params()
}

// ============================================================================
// Re-export errors and error classification helpers
// ============================================================================

// ErrNotFound is returned by One() when no rows match the query.
// It wraps sql.ErrNoRows so both errors.Is(err, relica.ErrNotFound)
// and errors.Is(err, sql.ErrNoRows) return true.
//
// Example:
//
//	var user User
//	err := db.Select().From("users").Where(relica.Eq("id", 999)).One(&user)
//	if errors.Is(err, relica.ErrNotFound) {
//	    // handle not found
//	}
var ErrNotFound = core.ErrNotFound

// ErrAutoIDPrefixMismatch is returned by FindByPublicID when the provided ID's
// prefix doesn't match the model's autoid tag prefix.
// This prevents accidentally looking up an order ID in the users table.
//
// Example:
//
//	// User has autoid:usr, but we pass an order ID:
//	err := db.Model(&user).FindByPublicID("ord_019078fa-...")
//	if errors.Is(err, relica.ErrAutoIDPrefixMismatch) {
//	    // wrong ID type for this model
//	}
var ErrAutoIDPrefixMismatch = util.ErrAutoIDPrefixMismatch

// RegisterIDGenerator registers a custom ID generator for use with the autoid tag.
// The default generator is UUID v7. Custom generators enable ULID, Snowflake, or any format.
//
// The generator function returns the ID body (without prefix).
// The prefix is added automatically by Relica based on the autoid tag.
//
// Example:
//
//	// Register once at startup:
//	relica.RegisterIDGenerator("ulid", func() string {
//	    return ulid.Make().String()
//	})
//
//	// Use in struct tag:
//	type Event struct {
//	    ID       int64  `db:"id,pk"`
//	    PublicID string `db:"public_id,autoid:evt,gen=ulid"`
//	}
//
//	event := Event{}
//	db.Model(&event).Insert()
//	// event.PublicID = "evt_01H9XZ..." (ULID with prefix)
func RegisterIDGenerator(name string, fn func() string) {
	util.RegisterIDGenerator(name, fn)
}

// IsUniqueViolation reports whether err represents a unique constraint violation.
// Works with PostgreSQL, MySQL, and SQLite. Returns false for nil errors.
//
// Example:
//
//	_, err := db.Model(&user).Insert()
//	if relica.IsUniqueViolation(err) {
//	    // handle duplicate key
//	}
func IsUniqueViolation(err error) bool { return core.IsUniqueViolation(err) }

// IsForeignKeyViolation reports whether err represents a foreign key constraint violation.
// Works with PostgreSQL, MySQL, and SQLite. Returns false for nil errors.
//
// Example:
//
//	_, err := db.Model(&order).Insert()
//	if relica.IsForeignKeyViolation(err) {
//	    // handle missing referenced row
//	}
func IsForeignKeyViolation(err error) bool { return core.IsForeignKeyViolation(err) }

// IsNotNullViolation reports whether err represents a NOT NULL constraint violation.
// Works with PostgreSQL, MySQL, and SQLite. Returns false for nil errors.
//
// Example:
//
//	_, err := db.Model(&user).Insert()
//	if relica.IsNotNullViolation(err) {
//	    // handle missing required field
//	}
func IsNotNullViolation(err error) bool { return core.IsNotNullViolation(err) }

// IsCheckViolation reports whether err represents a CHECK constraint violation.
// Works with PostgreSQL, MySQL, and SQLite. Returns false for nil errors.
//
// Example:
//
//	_, err := db.Model(&product).Insert()
//	if relica.IsCheckViolation(err) {
//	    // handle check constraint failure
//	}
func IsCheckViolation(err error) bool { return core.IsCheckViolation(err) }

// ============================================================================
// Re-export configuration options
// ============================================================================

// WithMaxOpenConns sets the maximum number of open connections.
func WithMaxOpenConns(n int) Option { return core.WithMaxOpenConns(n) }

// WithMaxIdleConns sets the maximum number of idle connections.
func WithMaxIdleConns(n int) Option { return core.WithMaxIdleConns(n) }

// WithConnMaxLifetime sets the maximum amount of time a connection may be reused.
// Expired connections may be closed lazily before reuse.
// If duration <= 0, connections are not closed due to a connection's age.
//
// Example:
//
//	db, err := relica.Open("postgres", dsn,
//	    relica.WithConnMaxLifetime(5*time.Minute))
func WithConnMaxLifetime(d time.Duration) Option { return core.WithConnMaxLifetime(d) }

// WithConnMaxIdleTime sets the maximum amount of time a connection may be idle.
// Expired connections may be closed lazily before reuse.
// If duration <= 0, connections are not closed due to a connection's idle time.
//
// Example:
//
//	db, err := relica.Open("postgres", dsn,
//	    relica.WithConnMaxIdleTime(1*time.Minute))
func WithConnMaxIdleTime(d time.Duration) Option { return core.WithConnMaxIdleTime(d) }

// WithHealthCheck enables periodic health checks on database connections.
// The health checker pings the database at the specified interval to detect dead connections.
// If interval <= 0, health checks are disabled.
//
// Example:
//
//	db, err := relica.Open("postgres", dsn,
//	    relica.WithHealthCheck(30*time.Second))
func WithHealthCheck(interval time.Duration) Option { return core.WithHealthCheck(interval) }

// WithStmtCacheCapacity sets the prepared statement cache capacity.
func WithStmtCacheCapacity(capacity int) Option { return core.WithStmtCacheCapacity(capacity) }

// WithLogger sets the logger for database query logging.
// The logger is wrapped as a QueryHook: errors are logged at Error level,
// successful queries at Info level.
// If not set, no logging is performed (zero overhead).
//
// Example:
//
//	import "log/slog"
//	l := slog.New(slog.NewJSONHandler(os.Stdout, nil))
//	db, err := relica.Open("postgres", dsn,
//	    relica.WithLogger(relica.NewSlogAdapter(l)))
func WithLogger(l Logger) Option { return core.WithLogger(l) }

// WithQueryHook sets a callback function that is invoked after each query execution.
// Use this for logging, metrics, distributed tracing, or debugging.
// If not set, no hook is called (zero overhead).
//
// Example:
//
//	db, _ := relica.Open("postgres", dsn,
//	    relica.WithQueryHook(func(ctx context.Context, e relica.QueryEvent) {
//	        slog.Info("query", "sql", e.SQL, "duration", e.Duration, "err", e.Error)
//	    }))
func WithQueryHook(hook QueryHook) Option { return core.WithQueryHook(hook) }

// Logger defines the logging interface for Relica.
// Implementations should handle structured logging with key-value pairs.
type Logger = logger.Logger

// NoopLogger is a logger that does nothing (zero overhead when logging is disabled).
type NoopLogger = logger.NoopLogger

// SlogAdapter wraps log/slog.Logger to implement the Logger interface.
type SlogAdapter = logger.SlogAdapter

// NewSlogAdapter creates a new logger adapter wrapping an slog.Logger.
func NewSlogAdapter(l *slog.Logger) *SlogAdapter { return logger.NewSlogAdapter(l) }

// QueryEvent contains information about an executed query.
// This is passed to QueryHook callbacks for logging, metrics, or tracing.
type QueryEvent = core.QueryEvent

// QueryHook is a callback function invoked after each query execution.
// Use this for logging, metrics, distributed tracing, or debugging.
type QueryHook = core.QueryHook

// Params represents named parameter values for query binding.
// Named parameters are specified in SQL using {:name} syntax.
//
// Example:
//
//	db.NewQuery("SELECT * FROM users WHERE id={:id} AND status={:status}").
//	    BindParams(relica.Params{"id": 1, "status": "active"}).
//	    All(&users)
type Params = core.Params

// DetectOperation detects the SQL operation type (SELECT, INSERT, UPDATE, DELETE, UNKNOWN).
func DetectOperation(query string) string { return core.DetectOperation(query) }

// NullStringMap represents a map of nullable string values scanned from database rows.
// Each value is a sql.NullString that can be checked for NULL.
// This type is useful for dynamic queries where the schema is not known at compile time.
//
// Example:
//
//	var result relica.NullStringMap
//	db.Select("*").From("users").Where("id = ?", 1).One(&result)
//	name := result.String("name")   // returns empty string if NULL
//	if !result.IsNull("email") {
//	    email := result.String("email")
//	}
//
//	// Multiple rows
//	var results []relica.NullStringMap
//	db.Select("*").From("users").All(&results)
type NullStringMap = core.NullStringMap

// defaultSanitizer is a package-level singleton to avoid recompiling 20 regexps per call.
var defaultSanitizer = logger.NewSanitizer(nil)

// MaskArgs masks sensitive parameter values (passwords, tokens, API keys) in query args.
// If the SQL references a sensitive column (password, token, api_key, etc.), ALL parameters
// of that statement are masked — not just the sensitive one. This is a conservative heuristic.
// Use this in custom QueryHook implementations to safely log parameters.
//
// Example:
//
//	relica.WithQueryHook(func(ctx context.Context, e relica.QueryEvent) {
//	    masked := relica.MaskArgs(e.SQL, e.Args)
//	    slog.Info("query", "sql", e.SQL, "args", masked)
//	})
func MaskArgs(query string, args []any) []any {
	return defaultSanitizer.MaskParams(query, args)
}

// ============================================================================
// Re-export expression builders
// ============================================================================

// NewExp creates a new raw SQL expression.
func NewExp(rawSQL string, args ...any) Expression { return core.NewExp(rawSQL, args...) }

// Eq creates an equality expression (column = value).
func Eq(col string, value any) Expression { return core.Eq(col, value) }

// NotEq creates a not-equal expression (column != value).
func NotEq(col string, value any) Expression { return core.NotEq(col, value) }

// GreaterThan creates a greater-than expression (column > value).
func GreaterThan(col string, value any) Expression { return core.GreaterThan(col, value) }

// LessThan creates a less-than expression (column < value).
func LessThan(col string, value any) Expression { return core.LessThan(col, value) }

// EqCol creates a column-to-column equality expression (col1 = col2).
// Both identifiers are quoted using the current dialect.
// Useful for JOIN ON conditions and correlated subquery WHERE clauses.
//
// Example:
//
//	relica.EqCol("orders.user_id", "users.id")  →  "orders"."user_id" = "users"."id"
func EqCol(col1, col2 string) Expression { return core.EqCol(col1, col2) }

// NotEqCol creates a column-to-column inequality expression (col1 <> col2).
func NotEqCol(col1, col2 string) Expression { return core.NotEqCol(col1, col2) }

// GreaterThanCol creates a column-to-column greater-than expression (col1 > col2).
func GreaterThanCol(col1, col2 string) Expression { return core.GreaterThanCol(col1, col2) }

// LessThanCol creates a column-to-column less-than expression (col1 < col2).
func LessThanCol(col1, col2 string) Expression { return core.LessThanCol(col1, col2) }

// GreaterOrEqualCol creates a column-to-column >= expression (col1 >= col2).
func GreaterOrEqualCol(col1, col2 string) Expression { return core.GreaterOrEqualCol(col1, col2) }

// LessOrEqualCol creates a column-to-column <= expression (col1 <= col2).
func LessOrEqualCol(col1, col2 string) Expression { return core.LessOrEqualCol(col1, col2) }

// IsNull creates an IS NULL expression. Equivalent to Eq(col, nil) but more explicit.
func IsNull(col string) Expression { return core.Eq(col, nil) }

// IsNotNull creates an IS NOT NULL expression. Equivalent to NotEq(col, nil) but more explicit.
func IsNotNull(col string) Expression { return core.NotEq(col, nil) }

// GreaterOrEqual creates a greater-or-equal expression (column >= value).
func GreaterOrEqual(col string, value any) Expression {
	return core.GreaterOrEqual(col, value)
}

// LessOrEqual creates a less-or-equal expression (column <= value).
func LessOrEqual(col string, value any) Expression { return core.LessOrEqual(col, value) }

// In creates an IN expression (column IN (values...)).
func In(col string, values ...any) Expression { return core.In(col, values...) }

// NotIn creates a NOT IN expression (column NOT IN (values...)).
func NotIn(col string, values ...any) Expression { return core.NotIn(col, values...) }

// Between creates a BETWEEN expression (column BETWEEN low AND high).
func Between(col string, from, to any) Expression { return core.Between(col, from, to) }

// NotBetween creates a NOT BETWEEN expression.
func NotBetween(col string, from, to any) Expression {
	return core.NotBetween(col, from, to)
}

// Like creates a LIKE expression with automatic escaping.
func Like(col string, values ...string) *LikeExp { return core.Like(col, values...) }

// NotLike creates a NOT LIKE expression.
func NotLike(col string, values ...string) *LikeExp { return core.NotLike(col, values...) }

// OrLike creates a LIKE expression combined with OR.
func OrLike(col string, values ...string) *LikeExp { return core.OrLike(col, values...) }

// OrNotLike creates a NOT LIKE expression combined with OR.
func OrNotLike(col string, values ...string) *LikeExp { return core.OrNotLike(col, values...) }

// And combines expressions with AND.
func And(exps ...Expression) Expression { return core.And(exps...) }

// Or combines expressions with OR.
func Or(exps ...Expression) Expression { return core.Or(exps...) }

// Not negates an expression.
func Not(exp Expression) Expression { return core.Not(exp) }

// Exists creates an EXISTS subquery expression.
func Exists(exp Expression) Expression { return core.Exists(exp) }

// NotExists creates a NOT EXISTS subquery expression.
func NotExists(exp Expression) Expression { return core.NotExists(exp) }

// ============================================================================
// Re-export functional expressions (CASE, COALESCE, NULLIF, etc.)
// ============================================================================

// Case creates a simple CASE expression.
func Case(column string) *CaseExp { return core.Case(column) }

// CaseWhen creates a searched CASE expression (without column).
func CaseWhen() *CaseExp { return core.CaseWhen() }

// Coalesce creates a COALESCE expression.
func Coalesce(values ...any) *CoalesceExp { return core.Coalesce(values...) }

// NullIf creates a NULLIF expression.
func NullIf(expr1, expr2 any) *NullIfExp { return core.NullIf(expr1, expr2) }

// Greatest creates a GREATEST expression.
func Greatest(values ...any) *GreatestLeastExp { return core.Greatest(values...) }

// Least creates a LEAST expression.
func Least(values ...any) *GreatestLeastExp { return core.Least(values...) }

// Concat creates a string concatenation expression.
func Concat(values ...any) *ConcatExp { return core.Concat(values...) }

// CaseExp represents a SQL CASE expression.
type CaseExp = core.CaseExp

// CoalesceExp represents a SQL COALESCE expression.
type CoalesceExp = core.CoalesceExp

// NullIfExp represents a SQL NULLIF expression.
type NullIfExp = core.NullIfExp

// GreatestLeastExp represents a SQL GREATEST or LEAST expression.
type GreatestLeastExp = core.GreatestLeastExp

// ConcatExp represents a SQL string concatenation expression.
type ConcatExp = core.ConcatExp