driver

type ColumnInfo struct {
	Name         string `json:"name"`
	DataType     string `json:"data_type"` // 类型名，如 NUMBER、VARCHAR2
	Length       int64  `json:"length,omitempty"`
	Precision    int    `json:"precision,omitempty"`
	Scale        int    `json:"scale,omitempty"`
	Nullable     bool   `json:"nullable"`
	DefaultValue string `json:"default_value,omitempty"`
	Position     int    `json:"position"`
	Comment      string `json:"comment,omitempty"`
}

type Conn interface {
	// Query 执行返回结果集的语句（SELECT 及各 DB 的等价物）。
	Query(ctx context.Context, sql string, args ...any) (*Result, error)
	// Exec 执行不返回结果集的语句（INSERT/UPDATE/DELETE/DDL）。
	// 注意：是否允许到达此方法由 cli 层的 guard 决定（见 guard.go），
	// 驱动实现本身不做权限判断，保持单一职责。
	Exec(ctx context.Context, sql string, args ...any) (ExecResult, error)
	// Version 探测并返回数据库版本。
	Version(ctx context.Context) (*DBVersion, error)
	// Metadata 返回该连接的元数据查询提供者。
	Metadata() MetadataProvider
	// Ping 验证连接是否真实可用（database/sql 的 Ping 语义）。
	// sql.Open 通常是惰性的，Ping 用于在打开后尽早暴露连接错误。
	Ping(ctx context.Context) error
	// Close 释放连接资源。
	Close() error
}

type DBVersion struct {
	Product    string // 产品名，如 "Oracle"
	Version    string // 完整版本字符串，如 "Oracle Database 19c Enterprise Edition Release 19.0.0.0.0"
	Major      int    // 主版本号，如 19
	Minor      int    // 次版本号，如 0
	Banner     string // v$version banner 原文（如可获取）
	DetectedAt time.Time
}

type DatasourceConfig struct {
	// 通用字段
	Type         string        `yaml:"type"`          // 驱动名，如 "oracle"/"mysql"，对应 Driver.Name()
	Description  string        `yaml:"description"`   // 可选：数据源的人类/AI 可读说明（职责、用途），帮助 AI 区分同类型数据源
	Host         string        `yaml:"host"`          // 主机
	Port         int           `yaml:"port"`          // 端口
	User         string        `yaml:"user"`          // 用户名
	Password     string        `yaml:"password"`      // 密码（已展开环境变量占位）
	Database     string        `yaml:"database"`      // 数据库名（MySQL 等；Oracle 用 service_name/sid）
	AllowWrite   bool          `yaml:"allow_write"`   // 是否允许写操作，默认 false（只读）
	ForceVersion string        `yaml:"force_version"` // 可选：跳过版本探测，强制指定版本标识（如 "11g"/"8.0"）
	TLS          string        `yaml:"tls"`           // 可选 TLS 配置：skip-verify / true / 自定义名；空表示不启用
	Timeout      time.Duration `yaml:"timeout"`       // 连接超时（如 "10s"）；0 表示用默认 30s

	// Oracle 相关（其它驱动可在此扩展或使用 Raw）
	ServiceName string `yaml:"service_name"` // Oracle service_name（与 SID 二选一）
	SID         string `yaml:"sid"`          // Oracle SID
	FetchSize   int    `yaml:"fetch_size"`   // 行预取大小，0 表示用驱动默认

	// 连接池
	MaxOpenConns int `yaml:"max_open_conns"` // 最大打开连接数，0 表示驱动默认
	MaxIdleConns int `yaml:"max_idle_conns"` // 最大空闲连接数

	// Raw 保留原始 map，供需要私有字段的驱动读取（如 SSL 参数等）。
	Raw map[string]any `yaml:",inline"`
}

type Driver interface {
	// Name 返回驱动名，需与 DatasourceConfig.Type 一致，如 "oracle"。
	Name() string
	// SupportedVersions 返回该驱动支持的数据库版本描述，如 "10.2+"。
	SupportedVersions() string
	// Description 返回面向人类的简短描述，用于 manifest / help。
	Description() string
	// Open 依据配置建立连接，返回统一的 Conn 抽象。
	Open(cfg *DatasourceConfig) (Conn, error)
}

type ExecResult struct {
	RowsAffected int64
	LastInsertID int64 // 部分数据库支持
}

type IndexInfo struct {
	Name      string   `json:"name"`
	IsUnique  bool     `json:"is_unique"`
	IsPrimary bool     `json:"is_primary"`
	Columns   []string `json:"columns"`
}

type MetadataProvider interface {
	// Databases 返回「库」列表。
	// Oracle: 非 CDB 通常返回单元素（当前库）；CDB 返回各 PDB 名称。
	Databases(ctx context.Context) ([]string, error)
	// Schemas 返回 schema / user 列表。
	Schemas(ctx context.Context) ([]string, error)
	// Tables 返回指定 schema 下的表。
	Tables(ctx context.Context, schema string) ([]TableInfo, error)
	// Columns 返回指定表的列定义。
	Columns(ctx context.Context, schema, table string) ([]ColumnInfo, error)
	// Indexes 返回指定表的索引。
	Indexes(ctx context.Context, schema, table string) ([]IndexInfo, error)
	// Views 返回指定 schema 下的视图。
	Views(ctx context.Context, schema string) ([]ViewInfo, error)
	// RowCount 返回指定表的近似行数（可能使用字典统计值）。
	RowCount(ctx context.Context, schema, table string) (int64, error)
}

type PagedDataProvider interface {
	// QueryTable 分页读取某张表的数据。
	// schema 为空表示用当前用户；limit<=0 表示驱动默认值；orderCol 为排序列（空则不排序）。
	QueryTable(ctx context.Context, schema, table string, limit, offset int64, orderCol string) (*Result, error)
}

type Result struct {
	Columns  []string // 列名
	Rows     [][]any  // 按行的值；每行元素顺序与 Columns 一致
	Affected int64    // 受影响行数（仅 Exec 相关，Query 时为 0）
}

type TableInfo struct {
	Schema   string `json:"schema"`
	Name     string `json:"name"`
	Type     string `json:"type"` // TABLE / VIEW / MATERIALIZED VIEW ...
	Comment  string `json:"comment,omitempty"`
	RowCount int64  `json:"row_count,omitempty"` // 近似行数（按需填充）
}

type ViewInfo struct {
	Schema  string `json:"schema"`
	Name    string `json:"name"`
	Comment string `json:"comment,omitempty"`
}

type WriteDisabledError struct {
	// Detail 是面向用户的中文说明（含语句类别、数据源名、修改建议）。
	Detail string
}

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