driver

Documentation

Overview

Package driver defines the shared interface that all database drivers implement.

Index

• Variables
• func DetectCommand(sql string, commands []string) string
• func GuardReadOnly(sql string) error
• func IsConnectionURL(value string) bool
• func IsFilePath(value string) bool
• func NormalizeValue(v any) any
• func QuoteIdentDot(name string) string
• func SplitSchemaTable(name, defaultSchema string) (string, string)
• type ColumnInfo
• type ColumnMatch
• type Connection
• type ConstraintInfo
• type ConstraintType
  • func MapConstraintType(s string) ConstraintType
• type Driver
  • func DetectDriverFromURL(url string) Driver
• type IndexInfo
• type QueryOpts
• type QueryResult
• type SearchResult
• type TableInfo

Variables

var AllDrivers = []Driver{
	DriverPG, DriverCockroachDB, DriverSQLite, DriverDuckDB,
	DriverMySQL, DriverMariaDB, DriverSnowflake, DriverMSSQL,
}

AllDrivers lists all supported driver names for error messages and help text.

var WriteCommands = []string{
	"INSERT", "UPDATE", "DELETE", "CREATE", "ALTER", "DROP",
	"TRUNCATE", "MERGE", "GRANT", "REVOKE",
}

WriteCommands is the shared set of SQL write commands used by keyword guards.

Functions

func DetectCommand

func DetectCommand(sql string, commands []string) string

DetectCommand checks if SQL starts with a known write command. Returns the matched command (e.g. "INSERT") or empty string.

func GuardReadOnly

func GuardReadOnly(sql string) error

GuardReadOnly validates that a SQL statement is read-only using keyword matching. Used by PG, CockroachDB, and MSSQL drivers as defense-in-depth alongside server-side enforcement (BEGIN READ ONLY, db_datareader role, etc.).

func IsConnectionURL

func IsConnectionURL(value string) bool

IsConnectionURL returns true if the value looks like a database URL.

func IsFilePath

func IsFilePath(value string) bool

IsFilePath returns true if the value looks like a database file path.

func NormalizeValue

func NormalizeValue(v any) any

NormalizeValue converts database driver return types to JSON-friendly types. Drivers with additional type conversions (e.g., PG UUIDs) should use their own version.

func QuoteIdentDot

func QuoteIdentDot(name string) string

QuoteIdentDot quotes an identifier with dot-splitting for schema-qualified names. Uses double-quote style quoting (ANSI SQL).

func SplitSchemaTable

func SplitSchemaTable(name, defaultSchema string) (string, string)

SplitSchemaTable splits a potentially schema-qualified name into (schema, table). If the name contains no dot, defaultSchema is used.

Types

type ColumnInfo

type ColumnInfo struct {
	Name         string `json:"name"`
	Type         string `json:"type"`
	Nullable     bool   `json:"nullable"`
	DefaultValue string `json:"defaultValue,omitempty"`
	PrimaryKey   bool   `json:"primaryKey,omitempty"`
}

ColumnInfo describes a table column.

type ColumnMatch

type ColumnMatch struct {
	Table  string `json:"table"`
	Column string `json:"column"`
}

ColumnMatch is a column that matched a search pattern.

type Connection

type Connection interface {
	// Query executes a SQL statement and returns the result.
	Query(ctx context.Context, sql string, opts QueryOpts) (*QueryResult, error)

	// GetTables lists tables and views. When includeSystem is false, system tables are excluded.
	GetTables(ctx context.Context, includeSystem bool) ([]TableInfo, error)

	// DescribeTable returns column information for a table.
	DescribeTable(ctx context.Context, table string) ([]ColumnInfo, error)

	// GetIndexes returns indexes. If table is empty, returns indexes for all tables.
	GetIndexes(ctx context.Context, table string) ([]IndexInfo, error)

	// GetConstraints returns constraints. If table is empty, returns all constraints.
	GetConstraints(ctx context.Context, table string) ([]ConstraintInfo, error)

	// SearchSchema searches table and column names by pattern.
	SearchSchema(ctx context.Context, pattern string) (*SearchResult, error)

	// QuoteIdent quotes an identifier for safe use in SQL.
	QuoteIdent(name string) string

	// Close releases the connection resources.
	Close() error
}

Connection is the core driver interface. Every database driver implements this. All methods that perform I/O take context.Context for timeout and cancellation.

type ConstraintInfo

type ConstraintInfo struct {
	Name              string         `json:"name"`
	Table             string         `json:"table"`
	Schema            string         `json:"schema,omitempty"`
	Type              ConstraintType `json:"type"`
	Columns           []string       `json:"columns"`
	ReferencedTable   string         `json:"referencedTable,omitempty"`
	ReferencedColumns []string       `json:"referencedColumns,omitempty"`
	Definition        string         `json:"definition,omitempty"`
}

ConstraintInfo describes a database constraint.

type ConstraintType

type ConstraintType string

ConstraintType classifies a constraint.

const (
	ConstraintPrimaryKey ConstraintType = "primary_key"
	ConstraintForeignKey ConstraintType = "foreign_key"
	ConstraintUnique     ConstraintType = "unique"
	ConstraintCheck      ConstraintType = "check"
)

func MapConstraintType

func MapConstraintType(s string) ConstraintType

MapConstraintType maps database constraint type strings to ConstraintType. Returns empty string for unrecognized types.

type Driver

type Driver string

Driver identifies a database driver type.

const (
	DriverPG          Driver = "pg"
	DriverCockroachDB Driver = "cockroachdb"
	DriverMySQL       Driver = "mysql"
	DriverMariaDB     Driver = "mariadb"
	DriverSQLite      Driver = "sqlite"
	DriverDuckDB      Driver = "duckdb"
	DriverSnowflake   Driver = "snowflake"
	DriverMSSQL       Driver = "mssql"
)

func DetectDriverFromURL

func DetectDriverFromURL(url string) Driver

DetectDriverFromURL detects the driver type from a URL or file path. Returns empty string if unrecognized.

type IndexInfo

type IndexInfo struct {
	Name    string   `json:"name"`
	Table   string   `json:"table"`
	Schema  string   `json:"schema,omitempty"`
	Columns []string `json:"columns"`
	Unique  bool     `json:"unique"`
}

IndexInfo describes a database index.

type QueryOpts

type QueryOpts struct {
	Write bool
}

QueryOpts controls query execution behavior.

type QueryResult

type QueryResult struct {
	Columns      []string
	Rows         []map[string]any
	RowsAffected int64
	Command      string // e.g. "INSERT", empty for SELECT
}

QueryResult holds the result of a SQL query.

type SearchResult

type SearchResult struct {
	Tables  []TableInfo   `json:"tables"`
	Columns []ColumnMatch `json:"columns"`
}

SearchResult holds schema search results.

type TableInfo

type TableInfo struct {
	Name   string `json:"name"`
	Schema string `json:"schema,omitempty"`
	Type   string `json:"type,omitempty"` // "table" or "view"
}

TableInfo describes a database table or view.