core

type ApplyModeler interface {
	ApplyModel(*Model) error
}

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

type Column struct {
	Name       string // 数据库的字段名
	AI         bool
	Nullable   bool
	HasDefault bool
	Default    any
	Length     []int

	PrimitiveType PrimitiveType
	GoName        string // Go 中的字段名
}

type Constraint struct {
	Name    string
	Columns []*Column
}

type ConstraintType int8

type Dialect interface {
	// Name 当前关联实例的名称
	//
	// 一般为该数据库的官方名称。
	// 实例名称和驱动名未必相同。比如 mysql 和 mariadb 可能采用相同的驱动名；
	Name() string

	// DriverName 与当前实例关联的驱动名称
	//
	// 原则上驱动名和 Dialect 应该是一一对应的，但是也会有例外，比如：
	// github.com/lib/pq 和 github.com/jackc/pgx/v4/stdlib 功能上是相同的，
	// 仅注册的名称的不同。
	DriverName() string

	Quotes() (left, right byte)

	// SQLType 将列转换成数据支持的类型表达式
	//
	// 必须实现对所有 [PrimitiveType] 类型的转换。
	SQLType(*Column) (string, error)

	// TransactionalDDL 是否允许在事务中执行 DDL
	//
	// 比如在 postgresql 中，如果创建一个带索引的表，会采用在事务中，
	// 分多条语句创建表。
	// 而像 mysql 等不支持事务内 DDL 的数据库，则会采用普通的方式，
	// 依次提交语句。
	TransactionalDDL() bool

	// VersionSQL 查询服务器版本号的 SQL 语句
	VersionSQL() string

	// ExistsSQL 查询数据库中是否存在指定名称的表或是视图 SQL 语句
	//
	// 返回的 SQL语句中，其执行结果如果存在，则应该返回 name 字段表示表名，否则返回空。
	ExistsSQL(name string, view bool) (string, []any)

	// LimitSQL 生成 `LIMIT N OFFSET M` 或是相同的语意的语句片段
	//
	// offset 值为一个可选参数，若不指定，则表示 `LIMIT N` 语句。
	// 返回的是对应数据库的 limit 语句以及语句中占位符对应的值。
	//
	// limit 和 offset 可以是 SQL.NamedArg 类型。
	LimitSQL(limit any, offset ...any) (string, []any)

	// LastInsertIDSQL 自定义获取 LastInsertID 的获取方式
	//
	// 类似于 postgresql 等都需要额外定义。
	//
	// sql 表示额外的语句，如果为空，则执行的是标准的 SQL 插入语句；
	// append 表示在 sql 不为空的情况下，sql 与现有的插入语句的结合方式，
	// 如果为 true 表示直接添加在插入语句之后，否则为一条新的语句。
	LastInsertIDSQL(table, col string) (sql string, append bool)

	// CreateTableOptionsSQL 创建表时根据附加信息返回的部分 SQL 语句
	CreateTableOptionsSQL(sql *Builder, options map[string][]string) error

	// TruncateTableSQL 生成清空数据表并重置自增列的语句
	//
	// ai 表示自增列的名称，可以为空，表示没有自去列。
	TruncateTableSQL(table, ai string) ([]string, error)

	// CreateViewSQL 生成创建视图的 SQL 语句
	CreateViewSQL(replace, temporary bool, name, selectQuery string, cols []string) ([]string, error)

	// DropIndexSQL 生成删除索引的语句
	//
	// table 为表名，部分数据库需要；
	// index 表示索引名；
	DropIndexSQL(table, index string) (string, error)

	// Fix 对 sql 语句作调整
	//
	// 比如处理 [sql.NamedArgs]，postgresql 需要将 ? 改成 $1 等形式。
	// 以及对 args 的参数作校正，比如 lib/pq 对 time.Time 处理有问题，也可以在此处作调整。
	//
	// NOTE: query 中不能同时存在 ? 和命名参数。因为如果是命名参数，则 args 的顺序可以是随意的。
	Fix(query string, args []any) (string, []any, error)

	// Prepare 对预编译的内容进行处理
	//
	// 目前大部分驱动都不支持 [sql.NamedArgs]，为了支持该功能，
	// 需要在预编译之前，对语句进行如下处理：
	//  1. 将 sql 中的 @xx 替换成 ?
	//  2. 将 sql 中的 @xx 在 sql 中的位置进行记录，并通过 orders 返回。
	// query 为处理后的 SQL 语句；
	// orders 为参数名在 query 中对应的位置，第一个位置为 0，依次增加。
	//
	// NOTE: query 中不能同时存在 ? 和命名参数。因为如果是命名参数，则 Exec 等的参数顺序可以是随意的。
	Prepare(sql string) (query string, orders map[string]int, err error)
}

type Engine interface {
	Query(query string, args ...any) (*sql.Rows, error)
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)

	QueryRow(query string, args ...any) *sql.Row
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row

	Exec(query string, args ...any) (sql.Result, error)
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)

	Prepare(query string) (*Stmt, error)
	PrepareContext(ctx context.Context, query string) (*Stmt, error)

	Dialect() Dialect

	// Debug 启用调试输出
	//
	// 如果传递了一个非空值，那么会将生成的 SQL 输出到 l。
	Debug(l func(string))
}

type ForeignKey struct {
	Name                     string // 约束名
	Column                   *Column
	RefTableName, RefColName string
	UpdateRule, DeleteRule   string
}

type IndexType int8

type Model struct {
	GoType reflect.Type

	// 模型的名称
	Name string

	// 视图的 select 语句
	//
	// 仅在 ModelType == View 时有效果，可由 [Engine.Query] 等处理。
	ViewAs string

	Type    ModelType
	Columns []*Column

	// 约束与索引
	//
	// NOTE: 如果是视图模式，理论上是不存在约束信息的，
	// 但是依然可以指定约束，这些信息主要是给 ORM 查看，以便构建搜索语句。
	Checks        map[string]string
	ForeignKeys   []*ForeignKey
	Indexes       []*Constraint // 目前不支持唯一索引，如果需要唯一索引，可以设置成唯一约束。
	Uniques       []*Constraint
	AutoIncrement *Column
	PrimaryKey    *Constraint

	OCC *Column // 乐观锁

	// 表级别的数据
	//
	// 如存储引擎，表名和字符集等，在创建表时，可能会用到这此数据。
	// 可以采用 [Dialect.Name] 限定数据库，比如 mysql_charset 限定为 mysql 下的 charset 属性。
	// 具体可参考各个 dialect 实现的介绍。
	Options map[string][]string
}

type ModelType int8

type PrimitiveType int

type PrimitiveTyper interface {

	// PrimitiveType 返回当前对象所表示的 [PrimitiveType] 值
	//
	// NOTE: 每个对象在任何时间返回的值应该都是固定的。
	PrimitiveType() PrimitiveType
}

type Stmt struct {
	*sql.Stmt
	// contains filtered or unexported fields
}

type TableNamer interface {
	// TableName 返回表或是视图的名称
	TableName() string
}

type Viewer interface {
	// ViewAs 返回视图所需的 SELECT 语句
	ViewAs() (string, error)
}