db

Documentation

Overview

Package db provides the database driver registry and query execution engine.

Index

• func EnforceReadOnly(sql string, unsafeAllowWrite bool) *errors.XError
• func IsReadOnlySQL(sql string) (bool, string)
• func Register(name string, d Driver)
• func RegisteredNames() []string
• type Column
• type ConnOptions
• type Dialer
• type Driver
  • func Get(name string) (Driver, bool)
• type ForeignKey
• type Index
• type QueryOptions
• type QueryResult
  • func Query(ctx context.Context, db *sql.DB, query string, opts QueryOptions) (*QueryResult, *errors.XError)
  • func (r *QueryResult) ToTableData() (columns []string, rows []map[string]any, ok bool)
• type SQLToken
• type SchemaExplorerDriver
• type SchemaInfo
  • func DumpSchema(ctx context.Context, driverName string, db *sql.DB, opts SchemaOptions) (*SchemaInfo, *errors.XError)
  • func (s *SchemaInfo) ToSchemaData() (string, []output.SchemaTable, bool)
• type SchemaOptions
• type Table
  • func DescribeTable(ctx context.Context, driverName string, db *sql.DB, opts TableDescribeOptions) (*Table, *errors.XError)
• type TableDescribeOptions
• type TableList
  • func ListTables(ctx context.Context, driverName string, db *sql.DB, opts SchemaOptions) (*TableList, *errors.XError)
• type TableSummary
• type TokenType

Functions

func EnforceReadOnly

func EnforceReadOnly(sql string, unsafeAllowWrite bool) *errors.XError

func IsReadOnlySQL

func IsReadOnlySQL(sql string) (bool, string)

IsReadOnlySQL performs a conservative check: deny by default; only allow explicitly documented read-only statements. Uses lexical analysis instead of simple string matching to correctly handle strings and comments. Returns false on parse failure, multiple statements, or presence of forbidden keywords.

func Register

func Register(name string, d Driver)

func RegisteredNames

func RegisteredNames() []string

Types

type Column

type Column struct {
	Name       string `json:"name" yaml:"name"`
	Type       string `json:"type" yaml:"type"`                           // Data type, e.g. varchar(255), bigint
	Nullable   bool   `json:"nullable" yaml:"nullable"`                   // Whether NULL is allowed
	Default    string `json:"default,omitempty" yaml:"default,omitempty"` // Default value
	Comment    string `json:"comment,omitempty" yaml:"comment,omitempty"` // Column comment
	PrimaryKey bool   `json:"primary_key" yaml:"primary_key"`             // Whether this is a primary key
}

Column represents column information.

type ConnOptions

type ConnOptions struct {
	DSN      string // Raw DSN (highest priority)
	Host     string
	Port     int
	User     string
	Password string
	Database string
	Params   map[string]string // Extra parameters
	Dialer   Dialer            // Custom dialer (e.g. SSH tunnel)
	// RegisterCloseHook allows drivers to register cleanup callbacks that should run
	// when the owning connection is closed or setup fails.
	RegisterCloseHook func(fn func())
}

ConnOptions holds common connection parameters (merged from config/CLI/ENV).

type Dialer

type Dialer interface {
	DialContext(ctx context.Context, network, addr string) (net.Conn, error)
}

Dialer is used for custom network connections (e.g. SSH tunnel).

type Driver

type Driver interface {
	// Open returns a *sql.DB; connection parameter parsing is handled by each driver.
	Open(ctx context.Context, opts ConnOptions) (*sql.DB, *errors.XError)
}

Driver is the minimal abstraction for a database driver.

func Get

func Get(name string) (Driver, bool)

type ForeignKey

type ForeignKey struct {
	Name              string   `json:"name" yaml:"name"`                             // Foreign key name
	Columns           []string `json:"columns" yaml:"columns"`                       // Local columns
	ReferencedTable   string   `json:"referenced_table" yaml:"referenced_table"`     // Referenced table
	ReferencedColumns []string `json:"referenced_columns" yaml:"referenced_columns"` // Referenced columns
}

ForeignKey represents foreign key information.

type Index

type Index struct {
	Name    string   `json:"name" yaml:"name"`       // Index name
	Columns []string `json:"columns" yaml:"columns"` // Indexed columns
	Unique  bool     `json:"unique" yaml:"unique"`   // Whether this is a unique index
	Primary bool     `json:"primary" yaml:"primary"` // Whether this is a primary key index
}

Index represents index information.

type QueryOptions

type QueryOptions struct {
	UnsafeAllowWrite bool   // Allow write operations (bypass read-only protection)
	DBType           string // Database type: mysql or pg
}

QueryOptions contains options for query execution.

type QueryResult

type QueryResult struct {
	Columns []string         `json:"columns" yaml:"columns"`
	Rows    []map[string]any `json:"rows" yaml:"rows"`
}

QueryResult represents a generic query result.

func Query

func Query(ctx context.Context, db *sql.DB, query string, opts QueryOptions) (*QueryResult, *errors.XError)

Query executes a SQL query and returns the result. When opts.UnsafeAllowWrite is false, dual read-only protection is enabled: 1. SQL statement static analysis (client-side) 2. Database transaction-level read-only mode (server-side) When opts.UnsafeAllowWrite is true, all read-only protections are bypassed.

func (*QueryResult) ToTableData

func (r *QueryResult) ToTableData() (columns []string, rows []map[string]any, ok bool)

ToTableData implements the output.TableFormatter interface for table output without JSON encoding/decoding.

type SQLToken

type SQLToken struct {
	Type  TokenType
	Value string
}

SQLToken represents a tokenized SQL element

type SchemaExplorerDriver

type SchemaExplorerDriver interface {
	Driver
	// ListTables returns the lightweight table list for the target database.
	ListTables(ctx context.Context, db *sql.DB, opts SchemaOptions) (*TableList, *errors.XError)
	// DescribeTable returns the schema details for a single table.
	DescribeTable(ctx context.Context, db *sql.DB, opts TableDescribeOptions) (*Table, *errors.XError)
}

SchemaExplorerDriver is the schema browsing interface. A Driver may optionally implement this interface to support table listing and description.

type SchemaInfo

type SchemaInfo struct {
	Database string  `json:"database" yaml:"database"`
	Tables   []Table `json:"tables" yaml:"tables"`
}

SchemaInfo represents database schema information.

func DumpSchema

func DumpSchema(ctx context.Context, driverName string, db *sql.DB, opts SchemaOptions) (*SchemaInfo, *errors.XError)

DumpSchema exports the database schema. It composes the full schema dump from table listing and per-table descriptions.

func (*SchemaInfo) ToSchemaData

func (s *SchemaInfo) ToSchemaData() (string, []output.SchemaTable, bool)

ToSchemaData implements the output.SchemaFormatter interface.

type SchemaOptions

type SchemaOptions struct {
	TablePattern  string // Table name filter (supports wildcards)
	IncludeSystem bool   // Whether to include system tables
}

SchemaOptions holds options for schema export.

type Table

type Table struct {
	Schema      string       `json:"schema" yaml:"schema"` // PostgreSQL schema; database name for MySQL
	Name        string       `json:"name" yaml:"name"`     // Table name
	Comment     string       `json:"comment,omitempty" yaml:"comment,omitempty"`
	Columns     []Column     `json:"columns" yaml:"columns"`
	Indexes     []Index      `json:"indexes,omitempty" yaml:"indexes,omitempty"`
	ForeignKeys []ForeignKey `json:"foreign_keys,omitempty" yaml:"foreign_keys,omitempty"`
}

Table represents table information.

func DescribeTable

func DescribeTable(ctx context.Context, driverName string, db *sql.DB, opts TableDescribeOptions) (*Table, *errors.XError)

DescribeTable returns the schema details for a single table.

type TableDescribeOptions

type TableDescribeOptions struct {
	Schema string
	Name   string
}

TableDescribeOptions identifies a single table to describe.

type TableList

type TableList struct {
	Database string         `json:"database" yaml:"database"`
	Tables   []TableSummary `json:"tables" yaml:"tables"`
}

TableList contains the lightweight table listing for a database.

func ListTables

func ListTables(ctx context.Context, driverName string, db *sql.DB, opts SchemaOptions) (*TableList, *errors.XError)

ListTables returns the lightweight table list for the target database.

type TableSummary

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

TableSummary represents a lightweight table entry for object navigation.

type TokenType

type TokenType int

TokenType represents the type of SQL token

const (
	TokenUnknown TokenType = iota
	TokenKeyword
	TokenIdentifier
	TokenString
	TokenNumber
	TokenComment
	TokenOperator
	TokenSemicolon
	TokenEOF
)