gpa

type AdvancedKeyValueRepository[T any] interface {
	BasicKeyValueRepository[T]
	BatchKeyValueRepository[T]
	TTLKeyValueRepository[T]
	IncrementKeyValueRepository
	PatternKeyValueRepository
}

type AfterCreateHook interface {
	AfterCreate(ctx context.Context) error
}

type AfterDeleteHook interface {
	AfterDelete(ctx context.Context) error
}

type AfterFindHook interface {
	AfterFind(ctx context.Context) error
}

type AfterUpdateHook interface {
	AfterUpdate(ctx context.Context) error
}

type AssociationManager interface {
	// Count returns the number of associated records
	Count(ctx context.Context) (int64, error)

	// Find retrieves associated records
	Find(ctx context.Context, dest interface{}) error

	// Append adds one or more associations
	Append(ctx context.Context, values ...interface{}) error

	// Replace replaces all associations with the given values
	Replace(ctx context.Context, values ...interface{}) error

	// Delete removes associations (but not the records themselves)
	Delete(ctx context.Context, values ...interface{}) error

	// Clear removes all associations
	Clear(ctx context.Context) error
}

type BasicCondition struct {
	FieldName string
	Op        Operator
	Val       interface{}
}

type BasicKeyValueRepository[T any] interface {
	Repository[T]

	// Set stores a value with the given key.
	// Overwrites any existing value at that key.
	// Example: err := Set(ctx, "user:123", user)
	Set(ctx context.Context, key string, value *T) error

	// Get retrieves a value by key.
	// Returns the value with compile-time type safety.
	// Returns ErrorTypeNotFound if the key doesn't exist.
	// Example: user, err := Get(ctx, "user:123")
	Get(ctx context.Context, key string) (*T, error)

	// DeleteKey removes a key-value pair.
	// Returns ErrorTypeNotFound if the key doesn't exist.
	// Example: err := DeleteKey(ctx, "user:123")
	DeleteKey(ctx context.Context, key string) error

	// KeyExists checks if a key exists.
	// Returns true if the key exists, false otherwise.
	// Example: exists, err := KeyExists(ctx, "user:123")
	KeyExists(ctx context.Context, key string) (bool, error)
}

type BatchKeyValueRepository[T any] interface {
	BasicKeyValueRepository[T]

	// MSet sets multiple key-value pairs in a single operation.
	// More efficient than multiple individual Set calls.
	// Example: err := MSet(ctx, map[string]*T{"user:1": user1, "user:2": user2})
	MSet(ctx context.Context, pairs map[string]*T) error

	// MGet retrieves multiple values by their keys.
	// Returns a map of key-value pairs with compile-time type safety.
	// Missing keys are omitted from the result map.
	// Example: users, err := MGet(ctx, []string{"user:1", "user:2", "user:3"})
	MGet(ctx context.Context, keys []string) (map[string]*T, error)

	// MDelete removes multiple keys in a single operation.
	// More efficient than multiple individual DeleteKey calls.
	// Returns the number of keys that were actually deleted.
	// Example: deleted, err := MDelete(ctx, []string{"user:1", "user:2"})
	MDelete(ctx context.Context, keys []string) (int64, error)
}

type BeforeCreateHook interface {
	BeforeCreate(ctx context.Context) error
}

type BeforeDeleteHook interface {
	BeforeDelete(ctx context.Context) error
}

type BeforeFindHook interface {
	BeforeFind(ctx context.Context) error
}

type BeforeUpdateHook interface {
	BeforeUpdate(ctx context.Context) error
}

type ColumnInfo struct {
	Name         string
	Type         string
	IsNullable   bool
	DefaultValue interface{}
	IsPrimaryKey bool
	IsUnique     bool
	MaxLength    int
	Precision    int
	Scale        int
}

type CompositeCondition struct {
	Conditions []Condition
	Logic      LogicOperator
}

type CompositeConditionOption struct {
	Conditions []Condition
	Logic      LogicOperator
}

type Condition interface {
	Field() string
	Operator() Operator
	Value() interface{}
	String() string
}

type ConditionOption struct {
	Condition Condition
}

type Config struct {
	// Connection details
	Driver        string `json:"driver" yaml:"driver"`
	ConnectionURL string `json:"connection_url" yaml:"connection_url"`
	Host          string `json:"host" yaml:"host"`
	Port          int    `json:"port" yaml:"port"`
	Database      string `json:"database" yaml:"database"`
	Username      string `json:"username" yaml:"username"`
	Password      string `json:"password" yaml:"password"`

	// Connection pool settings
	MaxOpenConns    int           `json:"max_open_conns" yaml:"max_open_conns"`
	MaxIdleConns    int           `json:"max_idle_conns" yaml:"max_idle_conns"`
	ConnMaxLifetime time.Duration `json:"conn_max_lifetime" yaml:"conn_max_lifetime"`
	ConnMaxIdleTime time.Duration `json:"conn_max_idle_time" yaml:"conn_max_idle_time"`

	// Additional options
	Options map[string]interface{} `json:"options" yaml:"options"`

	// SSL/TLS configuration
	SSL SSLConfig `json:"ssl" yaml:"ssl"`
}

type ConstraintInfo struct {
	Name       string
	Type       string
	Fields     []string
	References string
}

type DatabaseType string

type DistinctOption struct{}

type DocumentProvider interface {
	Provider

	// Database returns the underlying database instance
	Database() interface{}

	// Collection returns a collection instance
	Collection(name string) interface{}

	// CreateIndex creates an index on a collection
	CreateIndex(ctx context.Context, collection string, keys interface{}, options *IndexOptions) error

	// DropIndex drops an index from a collection
	DropIndex(ctx context.Context, collection string, name string) error

	// ListIndexes lists all indexes for a collection
	ListIndexes(ctx context.Context, collection string) ([]IndexInfo, error)

	// Aggregate runs an aggregation pipeline
	Aggregate(ctx context.Context, collection string, pipeline interface{}) (interface{}, error)

	// Watch starts a change stream
	Watch(ctx context.Context, collection string, pipeline interface{}) (interface{}, error)
}

type DocumentRepository[T any] interface {
	Repository[T]

	// FindByDocument retrieves entities matching a document-style query.
	// The query is a map representing the document structure to match.
	// Returns a slice of entity pointers with compile-time type safety.
	// Example: users, err := FindByDocument(ctx, map[string]interface{}{"status": "active", "age": map[string]interface{}{"$gte": 18}})
	FindByDocument(ctx context.Context, query map[string]interface{}) ([]*T, error)

	// UpdateDocument updates an entity using document-style operations.
	// The update parameter contains the update operations (e.g., $set, $unset, $inc).
	// Returns the number of documents modified.
	// Example: count, err := UpdateDocument(ctx, userID, map[string]interface{}{"$set": map[string]interface{}{"status": "inactive"}})
	UpdateDocument(ctx context.Context, id interface{}, update map[string]interface{}) (int64, error)

	// UpdateManyDocuments updates multiple entities using document-style operations.
	// Combines a query filter with update operations.
	// Returns the number of documents modified.
	// Example: count, err := UpdateManyDocuments(ctx, filter, update)
	UpdateManyDocuments(ctx context.Context, filter map[string]interface{}, update map[string]interface{}) (int64, error)

	// Aggregate performs aggregation operations using database-specific pipelines.
	// For MongoDB, this uses the aggregation pipeline. Other databases may use similar concepts.
	// Returns aggregated results as a slice of maps.
	// Example: results, err := Aggregate(ctx, []map[string]interface{}{{"$group": {"_id": "$status", "count": {"$sum": 1}}}})
	Aggregate(ctx context.Context, pipeline []map[string]interface{}) ([]map[string]interface{}, error)

	// CreateIndex creates an index on the specified fields.
	// The keys parameter maps field names to index direction (1 for ascending, -1 for descending).
	// For document databases, this might include text indexes, geospatial indexes, etc.
	// Example: err := CreateIndex(ctx, map[string]interface{}{"email": 1, "status": 1}, false)
	CreateIndex(ctx context.Context, keys map[string]interface{}, unique bool) error

	// DropIndex removes an index by name.
	// Example: err := DropIndex(ctx, "email_1_status_1")
	DropIndex(ctx context.Context, indexName string) error

	// TextSearch performs full-text search on indexed text fields.
	// The query string contains the search terms.
	// Returns entities matching the search criteria with compile-time type safety.
	// Example: users, err := TextSearch(ctx, "john developer", opts...)
	TextSearch(ctx context.Context, query string, opts ...QueryOption) ([]*T, error)

	// FindNear finds entities near a geographical point.
	// Requires geospatial indexes on the queried fields.
	// Returns entities sorted by distance with compile-time type safety.
	// Example: places, err := FindNear(ctx, "location", []float64{-73.9857, 40.7484}, 1000)
	FindNear(ctx context.Context, field string, point []float64, maxDistance float64) ([]*T, error)

	// FindWithinPolygon finds entities within a geographical polygon.
	// The polygon is defined by an array of coordinate points.
	// Returns matching entities with compile-time type safety.
	// Example: places, err := FindWithinPolygon(ctx, "location", polygon)
	FindWithinPolygon(ctx context.Context, field string, polygon [][]float64) ([]*T, error)
}

type EntityInfo struct {
	Name       string
	TableName  string
	Fields     []FieldInfo
	PrimaryKey []string
	Indexes    []IndexInfo
	Relations  []RelationInfo
}

type ErrorType string

type EventHook interface {
	// BeforeCreate is called before creating an entity
	BeforeCreate(ctx interface{}, entity interface{}) error

	// AfterCreate is called after creating an entity
	AfterCreate(ctx interface{}, entity interface{}) error

	// BeforeUpdate is called before updating an entity
	BeforeUpdate(ctx interface{}, entity interface{}) error

	// AfterUpdate is called after updating an entity
	AfterUpdate(ctx interface{}, entity interface{}) error

	// BeforeDelete is called before deleting an entity
	BeforeDelete(ctx interface{}, id interface{}) error

	// AfterDelete is called after deleting an entity
	AfterDelete(ctx interface{}, id interface{}) error
}

type Feature string

type FieldInfo struct {
	Name            string
	Type            reflect.Type
	DatabaseType    string
	Tag             string
	IsPrimaryKey    bool
	IsNullable      bool
	IsAutoIncrement bool
	DefaultValue    interface{}
	MaxLength       int
	Precision       int
	Scale           int
}

type FieldsOption struct {
	Fields []string
}

type GPAError struct {
	Type    ErrorType
	Message string
	Cause   error
	Code    string
}

type GraphProvider interface {
	Provider

	// Driver returns the underlying driver instance
	Driver() interface{}

	// Session returns a session for executing queries
	Session(ctx context.Context) (interface{}, error)

	// CypherQuery executes a Cypher query (for Neo4j-compatible databases)
	CypherQuery(ctx context.Context, query string, params map[string]interface{}) (interface{}, error)

	// CreateNode creates a node in the graph
	CreateNode(ctx context.Context, labels []string, properties map[string]interface{}) (interface{}, error)

	// CreateRelationship creates a relationship between two nodes
	CreateRelationship(ctx context.Context, fromNode, toNode interface{}, relType string, properties map[string]interface{}) (interface{}, error)

	// FindPath finds paths between nodes
	FindPath(ctx context.Context, from, to interface{}, maxDepth int) (interface{}, error)
}

type GraphRepository[T any] interface {
	Repository[T]

	// FindConnected finds entities connected to the given entity.
	// Follows rel based on the specified relationship type and direction.
	// Returns connected entities with compile-time type safety.
	// Example: friends, err := FindConnected(ctx, userID, "FRIEND", "outgoing", 1)
	FindConnected(ctx context.Context, entityID interface{}, relationshipType string, direction string, depth int) ([]*T, error)

	// FindPath finds the shortest path between two entities.
	// Returns a list of entities representing the path with compile-time type safety.
	// Example: path, err := FindPath(ctx, startID, endID, "CONNECTED")
	FindPath(ctx context.Context, startID, endID interface{}, relationshipType string) ([]*T, error)

	// TraverseGraph performs a custom graph traversal.
	// Uses a traversal specification to define the traversal pattern.
	// Returns entities found during traversal with compile-time type safety.
	// Example: results, err := TraverseGraph(ctx, startID, traversal)
	TraverseGraph(ctx context.Context, startID interface{}, traversal GraphTraversal) ([]*T, error)
}

type GraphTraversal struct {
	StartingPoints []interface{}
	MaxDepth       int
	Relationships  []string
	Direction      string
	Filters        []Condition
}

type GroupByOption struct {
	Fields []string
}

type HavingOption struct {
	Condition Condition
}

type IncrementKeyValueRepository interface {
	// Increment atomically increments a numeric value.
	// Creates the key with value 0 if it doesn't exist, then adds the delta.
	// Returns the new value after incrementing.
	// Example: newValue, err := Increment(ctx, "counter:visits", 1)
	Increment(ctx context.Context, key string, delta int64) (int64, error)

	// Decrement atomically decrements a numeric value.
	// Creates the key with value 0 if it doesn't exist, then subtracts the delta.
	// Returns the new value after decrementing.
	// Example: newValue, err := Decrement(ctx, "counter:items", 1)
	Decrement(ctx context.Context, key string, delta int64) (int64, error)
}

type IndexInfo struct {
	Name     string
	Fields   []string
	IsUnique bool
	Type     IndexType
}

type IndexOptions struct {
	Unique     bool
	Sparse     bool
	Background bool
	TTL        time.Duration
	Name       string
}

type IndexType string

type IsolationLevel string

type JoinClause struct {
	Type      JoinType
	Table     string
	Condition string
	Alias     string
}

type JoinOption struct {
	Join JoinClause
}

type JoinType string

type KeyValueProvider interface {
	Provider

	// Client returns the underlying client instance
	Client() interface{}

	// Set stores a key-value pair with optional TTL
	Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error

	// Get retrieves a value by key
	Get(ctx context.Context, key string) (interface{}, error)

	// Delete removes a key
	Delete(ctx context.Context, key string) error

	// Exists checks if a key exists
	Exists(ctx context.Context, key string) (bool, error)

	// Keys returns all keys matching a pattern
	Keys(ctx context.Context, pattern string) ([]string, error)

	// Expire sets TTL for a key
	Expire(ctx context.Context, key string, ttl time.Duration) error

	// TTL returns the remaining TTL for a key
	TTL(ctx context.Context, key string) (time.Duration, error)
}

type KeyspaceOptions struct {
	ReplicationFactor int
	ReplicationClass  string
	DurableWrites     bool
}

type LimitOption struct {
	Count int
}

type LockOption struct {
	Type LockType
}

type LockType string

type LogicOperator string

type MigratableRepository[T any] interface {
	SQLRepository[T]

	// MigrateTable performs automatic schema migration for entity type T.
	// Analyzes the current entity structure and updates the database schema accordingly.
	// Can add new columns, indexes, and constraints but typically won't remove existing ones.
	// Example: err := MigrateTable(ctx)
	MigrateTable(ctx context.Context) error

	// GetMigrationStatus returns the current migration status for entity type T.
	// Indicates whether the table exists, what version it's at, and if migration is needed.
	// Example: status, err := GetMigrationStatus(ctx)
	GetMigrationStatus(ctx context.Context) (MigrationStatus, error)

	// GetTableInfo returns detailed information about the current table structure.
	// Includes columns, indexes, constraints, and other database-specific metadata.
	// Example: info, err := GetTableInfo(ctx)
	GetTableInfo(ctx context.Context) (TableInfo, error)
}

type MigrationStatus struct {
	TableExists     bool
	CurrentVersion  string
	RequiredVersion string
	NeedsMigration  bool
	PendingChanges  []string
}

type OffsetOption struct {
	Count int
}

type Operator string

type Order struct {
	Field     string
	Direction OrderDirection
}

type OrderDirection string

type OrderOption struct {
	Order Order
}

type PatternKeyValueRepository interface {
	// Keys returns all keys matching the given pattern.
	// Uses glob-style patterns (*, ?, [abc], etc.).
	// WARNING: Can be slow with large datasets - use with caution.
	// Example: keys, err := Keys(ctx, "user:*")
	Keys(ctx context.Context, pattern string) ([]string, error)

	// Scan iterates over keys matching a pattern using cursor-based pagination.
	// More efficient than Keys() for large datasets as it doesn't load all keys at once.
	// Returns matching keys and a cursor for the next iteration.
	// Example: keys, cursor, err := Scan(ctx, 0, "user:*", 10)
	Scan(ctx context.Context, cursor uint64, pattern string, count int64) ([]string, uint64, error)
}

type PreloadOption struct {
	Relations []string
}

type Provider interface {
	// Configure applies new configuration to the provider.
	// Can be used to change connection settings, pool sizes, etc. at runtime.
	// May require reconnection depending on what settings changed.
	Configure(config Config) error

	// Health checks if the database connection is healthy and responsive.
	// Returns error if the database is unreachable or not functioning properly.
	// Useful for health check endpoints and monitoring.
	Health() error

	// Close shuts down the provider and releases all resources.
	// Closes database providers, stops background tasks, etc.
	// Should be called during application shutdown.
	Close() error

	// SupportedFeatures returns a list of features this provider supports.
	// Features include things like transactions, full-text search, pub/sub, etc.
	// Use this to check capabilities before using advanced features.
	SupportedFeatures() []Feature

	// ProviderInfo returns metadata about this provider.
	// Includes provider name, version, database type, and supported features.
	// Useful for debugging, logging, and feature detection.
	ProviderInfo() ProviderInfo
}

type ProviderFunc func(...string) Provider

type ProviderInfo struct {
	Name         string
	Version      string
	DatabaseType DatabaseType
	Features     []Feature
}

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

type Query struct {
	Conditions []Condition
	Orders     []Order
	Limit      *int
	Offset     *int
	Fields     []string
	Joins      []JoinClause
	Groups     []string
	Having     []Condition
	Distinct   bool
	Lock       LockType
	Preloads   []string
	SubQueries []SubQuery
}

type QueryBuilder[T any] struct {
	// contains filtered or unexported fields
}

type QueryOption interface {
	Apply(query *Query)
}

type RelationInfo struct {
	Name         string
	Type         RelationType
	TargetEntity string
	ForeignKey   string
	References   string
}

type RelationType string

type Repository[T any] interface {

	// Create inserts a new entity into the database.
	// Returns error if the entity already exists or validation fails.
	// Example: err := Create(ctx, &user)
	Create(ctx context.Context, entity *T) error

	// CreateBatch inserts multiple entities in a single operation for better performance.
	// May not be atomic depending on the database implementation.
	// Example: err := CreateBatch(ctx, []*User{user1, user2, user3})
	CreateBatch(ctx context.Context, entities []*T) error

	// FindByID retrieves a single entity by its primary key.
	// Returns the entity directly with compile-time type safety.
	// Returns ErrorTypeNotFound if the entity doesn't exist.
	// Example: user, err := FindByID(ctx, 123)
	FindByID(ctx context.Context, id interface{}) (*T, error)

	// FindAll retrieves all entities of type T, optionally filtered by query options.
	// Returns a slice of entity pointers with compile-time type safety.
	// Use QueryOptions like Where(), Limit(), OrderBy() to filter and sort results.
	// Example: users, err := FindAll(ctx, Where("active", "=", true), Limit(10))
	FindAll(ctx context.Context, opts ...QueryOption) ([]*T, error)

	// Update modifies an existing entity. The entity must have an ID field.
	// Replaces the entire entity with the new values.
	// Returns ErrorTypeNotFound if the entity doesn't exist.
	// Example: err := Update(ctx, &user)
	Update(ctx context.Context, entity *T) error

	// UpdatePartial modifies specific fields of an entity without replacing the whole entity.
	// The updates map contains field names as keys and new values as values.
	// Returns ErrorTypeNotFound if the entity doesn't exist.
	// Example: err := UpdatePartial(ctx, 123, map[string]interface{}{"status": "inactive"})
	UpdatePartial(ctx context.Context, id interface{}, updates map[string]interface{}) error

	// Delete removes an entity by its primary key.
	// Returns ErrorTypeNotFound if the entity doesn't exist.
	// Example: err := Delete(ctx, 123)
	Delete(ctx context.Context, id interface{}) error

	// DeleteByCondition removes all entities matching the given condition.
	// Use Where() conditions to specify which entities to delete.
	// Example: err := DeleteByCondition(ctx, Where("status", "=", "inactive"))
	DeleteByCondition(ctx context.Context, condition Condition) error

	// Query retrieves entities based on the provided query options.
	// More flexible than FindAll, supports complex conditions, joins, subqueries.
	// Returns a slice of entity pointers with compile-time type safety.
	// Example: users, err := Query(ctx, Where("age", ">", 18), OrderBy("name", "ASC"))
	Query(ctx context.Context, opts ...QueryOption) ([]*T, error)

	// QueryOne retrieves a single entity based on query options.
	// Equivalent to Query() with Limit(1) but returns ErrorTypeNotFound if no match.
	// Returns the entity directly with compile-time type safety.
	// Example: user, err := QueryOne(ctx, Where("email", "=", "user@example.com"))
	QueryOne(ctx context.Context, opts ...QueryOption) (*T, error)

	// Count returns the number of entities matching the query options.
	// Does not retrieve the actual entities, just counts them.
	// Useful for pagination and analytics.
	// Example: count, err := Count(ctx, Where("active", "=", true))
	Count(ctx context.Context, opts ...QueryOption) (int64, error)

	// Exists checks if any entities match the query options.
	// More efficient than Count() when you only need to know if matches exist.
	// Returns true if at least one entity matches, false otherwise.
	// Example: exists, err := Exists(ctx, Where("email", "=", "user@example.com"))
	Exists(ctx context.Context, opts ...QueryOption) (bool, error)

	// Transaction executes a function within a database transaction.
	// If the function returns an error, the transaction is rolled back.
	// If the function completes successfully, the transaction is committed.
	// Not all databases support transactions (e.g., some NoSQL databases).
	// Example: err := Transaction(ctx, func(tx Transaction[T]) error { return tx.Create(ctx, &user) })
	Transaction(ctx context.Context, fn TransactionFunc[T]) error

	// RawQuery executes a database-specific query and returns results.
	// Returns a slice of entity pointers with compile-time type safety.
	// The query string and args format depend on the database type.
	// Example: users, err := RawQuery(ctx, "SELECT * FROM users WHERE age > ?", []interface{}{18})
	RawQuery(ctx context.Context, query string, args []interface{}) ([]*T, error)

	// RawExec executes a database-specific command that doesn't return data.
	// Used for database-specific operations like creating indexes, triggers, etc.
	// Returns a Result object with information about rows affected, etc.
	// Example: result, err := RawExec(ctx, "UPDATE users SET last_login = NOW()", nil)
	RawExec(ctx context.Context, query string, args []interface{}) (Result, error)

	// GetEntityInfo returns metadata about the entity type T.
	// Includes field information, primary keys, indexes, and rel.
	// Useful for reflection, validation, and building dynamic UIs.
	// Example: info, err := GetEntityInfo()
	GetEntityInfo() (*EntityInfo, error)

	// Close closes the repository and releases any resources.
	// Should be called when the repository is no longer needed.
	// May close database providers, file handles, etc.
	// Example: err := Close()
	Close() error
}

type Result interface {
	// LastInsertId returns the integer generated by the database
	// in response to a command. Typically this will be from an
	// "auto increment" column when inserting a new row.
	LastInsertId() (int64, error)

	// RowsAffected returns the number of rows affected by an
	// update, insert, or delete. Not every database or database
	// driver may support this.
	RowsAffected() (int64, error)
}

type SQLProvider interface {
	Provider

	// DB returns the underlying database/sql.DB instance
	// This allows direct access to the native SQL connection for advanced operations
	DB() interface{}

	// BeginTx starts a transaction with specific isolation level
	BeginTx(ctx context.Context, opts *TxOptions) (interface{}, error)

	// Migrate runs database migrations
	Migrate(models ...interface{}) error

	// RawQuery executes raw SQL and returns results
	RawQuery(ctx context.Context, query string, args ...interface{}) (interface{}, error)

	// RawExec executes raw SQL without returning results
	RawExec(ctx context.Context, query string, args ...interface{}) (Result, error)
}

type SQLRepository[T any] interface {
	Repository[T]

	// FindBySQL executes a raw SQL SELECT query and returns typed results.
	// Returns a slice of entity pointers with compile-time type safety.
	// Example: users, err := FindBySQL(ctx, "SELECT * FROM users WHERE age > ?", []interface{}{18})
	FindBySQL(ctx context.Context, sql string, args []interface{}) ([]*T, error)

	// ExecSQL executes a raw SQL command that doesn't return entities (INSERT, UPDATE, DELETE, DDL).
	// Returns a Result with information about rows affected, last insert ID, etc.
	// Example: result, err := ExecSQL(ctx, "UPDATE users SET status = ? WHERE active = ?", "inactive", false)
	ExecSQL(ctx context.Context, sql string, args ...interface{}) (Result, error)

	// FindWithRelations retrieves entities with their related entities preloaded.
	// Returns a slice of entity pointers with compile-time type safety.
	// The relations slice specifies which rel to load.
	// Example: users, err := FindWithRelations(ctx, []string{"Posts", "Profile"}, Where("active", "=", true))
	FindWithRelations(ctx context.Context, relations []string, opts ...QueryOption) ([]*T, error)

	// FindByIDWithRelations retrieves a single entity by ID with rel preloaded.
	// Returns the entity directly with compile-time type safety.
	// Example: user, err := FindByIDWithRelations(ctx, userID, []string{"Posts", "Comments"})
	FindByIDWithRelations(ctx context.Context, id interface{}, relations []string) (*T, error)

	// CreateTable creates a new table based on the entity structure.
	// Analyzes the entity type T's fields, tags, and rel to generate appropriate SQL.
	// May create foreign key constraints, indexes, and other database objects.
	// Example: err := CreateTable(ctx)
	CreateTable(ctx context.Context) error

	// DropTable removes the table for entity type T from the database.
	// WARNING: This permanently deletes all data in the table.
	// May fail if there are foreign key constraints pointing to this table.
	// Example: err := DropTable(ctx)
	DropTable(ctx context.Context) error

	// CreateIndex creates a database index on the specified fields of entity type T.
	// Improves query performance for the specified field combinations.
	// The unique parameter determines if the index should enforce uniqueness.
	// Example: err := CreateIndex(ctx, []string{"email", "status"}, true)
	CreateIndex(ctx context.Context, fields []string, unique bool) error

	// DropIndex removes a database index.
	// The indexName should match an existing index on the table for entity type T.
	// Example: err := DropIndex(ctx, "idx_users_email_status")
	DropIndex(ctx context.Context, indexName string) error
}

type SSLConfig struct {
	Enabled  bool   `json:"enabled" yaml:"enabled"`
	Mode     string `json:"mode" yaml:"mode"`
	CertFile string `json:"cert_file" yaml:"cert_file"`
	KeyFile  string `json:"key_file" yaml:"key_file"`
	CAFile   string `json:"ca_file" yaml:"ca_file"`
}

type SubQuery struct {
	Query    *Query
	Type     SubQueryType
	Field    string
	Operator Operator
	Args     []interface{}
}

type SubQueryCondition struct {
	SubQuery  SubQuery
	FieldName string
}

type SubQueryOption struct {
	SubQuery SubQuery
}

type SubQueryType string

type TTLKeyValueRepository[T any] interface {
	BasicKeyValueRepository[T]

	// SetWithTTL stores a value with an expiration time.
	// The value will be automatically deleted after the TTL expires.
	// Example: err := SetWithTTL(ctx, "session:abc123", session, 30*time.Minute)
	SetWithTTL(ctx context.Context, key string, value *T, ttl time.Duration) error

	// GetTTL returns the remaining time-to-live for a key.
	// Returns 0 if the key doesn't exist or has no TTL.
	// Example: ttl, err := GetTTL(ctx, "session:abc123")
	GetTTL(ctx context.Context, key string) (time.Duration, error)

	// SetTTL sets or updates the TTL for an existing key.
	// Returns ErrorTypeNotFound if the key doesn't exist.
	// Example: err := SetTTL(ctx, "session:abc123", 15*time.Minute)
	SetTTL(ctx context.Context, key string, ttl time.Duration) error

	// RemoveTTL removes the TTL from a key, making it persistent.
	// The key will no longer expire automatically.
	// Example: err := RemoveTTL(ctx, "permanent:key")
	RemoveTTL(ctx context.Context, key string) error
}

type TableInfo struct {
	Name        string
	Columns     []ColumnInfo
	Indexes     []IndexInfo
	Constraints []ConstraintInfo
}

type Transaction[T any] interface {
	Repository[T]

	// Commit permanently saves all changes made within this transaction.
	// Once committed, changes cannot be rolled back.
	// Returns error if the commit fails (e.g., constraint violations).
	Commit() error

	// Rollback discards all changes made within this transaction.
	// Can be called manually or automatically when the transaction function returns an error.
	// Returns error if the rollback fails.
	Rollback() error

	// SetSavepoint creates a savepoint within the transaction.
	// Allows partial rollback to a specific point without rolling back the entire transaction.
	// Not supported by all databases.
	SetSavepoint(name string) error

	// RollbackToSavepoint rolls back to a previously created savepoint.
	// Only changes made after the savepoint are discarded.
	// Not supported by all databases.
	RollbackToSavepoint(name string) error
}

type TransactionFunc[T any] func(tx Transaction[T]) error

type TxOptions struct {
	IsolationLevel IsolationLevel
	ReadOnly       bool
	Timeout        time.Duration
}

type ValidationHook interface {
	Validate(ctx context.Context) error
}

type WideColumnProvider interface {
	Provider

	// Session returns the underlying session instance
	Session() interface{}

	// CreateKeyspace creates a keyspace
	CreateKeyspace(ctx context.Context, name string, options *KeyspaceOptions) error

	// CreateTable creates a table in a keyspace
	CreateTable(ctx context.Context, keyspace string, table string, schema interface{}) error

	// PrepareStatement prepares a statement for execution
	PrepareStatement(ctx context.Context, query string) (interface{}, error)

	// BatchExecute executes multiple statements as a batch
	BatchExecute(ctx context.Context, statements []interface{}) error
}

type WideColumnRepository[T any] interface {
	Repository[T]

	// FindByPartitionKey retrieves entities by partition key.
	// Partition keys determine data distribution across nodes.
	// Returns entities within the same partition with compile-time type safety.
	// Example: events, err := FindByPartitionKey(ctx, partitionKey, opts...)
	FindByPartitionKey(ctx context.Context, partitionKey interface{}, opts ...QueryOption) ([]*T, error)

	// FindByRange retrieves entities within a clustering key range.
	// Clustering keys determine sort order within partitions.
	// Returns entities within the specified range with compile-time type safety.
	// Example: events, err := FindByRange(ctx, partitionKey, startKey, endKey)
	FindByRange(ctx context.Context, partitionKey, startKey, endKey interface{}) ([]*T, error)

	// FindByTimeRange retrieves entities within a time range.
	// Optimized for time-series data queries.
	// Returns time-ordered entities with compile-time type safety.
	// Example: metrics, err := FindByTimeRange(ctx, startTime, endTime, opts...)
	FindByTimeRange(ctx context.Context, startTime, endTime interface{}, opts ...QueryOption) ([]*T, error)

	// Compact triggers compaction of the underlying storage.
	// Improves read performance by merging and organizing data files.
	// Returns when compaction is complete or fails.
	// Example: err := Compact(ctx)
	Compact(ctx context.Context) error
}