introspect

Documentation

Overview

Package introspect connects to a database, reads the schema using engine-specific SQL queries, and renders the result as DBML.

Index

• func GenerateDBML(schema *DBSchema, databaseType string, normalize bool) string
• func Run(dsn string, opts Options, normalize bool) (string, error)
• type CheckConstraint
• type Column
• type Constraint
• type DBSchema
  • func Introspect(ctx context.Context, db *sql.DB, engine Engine, schema string) (*DBSchema, error)
• type Engine
• type Enum
• type ForeignKey
• type Index
• type Options
• type ParsedDSN
  • func ParseDSN(rawDSN string) (*ParsedDSN, error)
• type Record
• type Table

Functions

func GenerateDBML

func GenerateDBML(schema *DBSchema, databaseType string, normalize bool) string

GenerateDBML converts a DBSchema to a DBML string. databaseType, if non-empty, is emitted as a Project block header (e.g. "PostgreSQL", "MySQL"). When normalize is true, column types are mapped to canonical DBML equivalents; otherwise the raw SQL types from the database are preserved.

func Run

func Run(dsn string, opts Options, normalize bool) (string, error)

Run is a convenience entry point for the CLI. It parses dsn, opens its own database connection, introspects the schema, and returns DBML output. When normalize is true, column types are mapped to canonical DBML equivalents and database_type is set to "normalized"; otherwise native types are preserved and database_type reflects the actual engine. The driver named by the DSN scheme must be registered (blank-imported) by the calling binary.

Types

type CheckConstraint

type CheckConstraint struct {
	Name       string
	ColumnName string // empty if table-level
	Expression string
}

CheckConstraint represents a CHECK constraint.

type Column

type Column struct {
	Name         string
	Type         string
	Default      *string // nil when no default
	DefaultType  string  // "number", "string", "boolean", "expression", "increment", "null"
	IsNullable   bool
	IsPrimaryKey bool
	IsUnique     bool
	IsIncrement  bool
	Comment      string
	Generated    string
}

Column represents a single column in a table.

type Constraint

type Constraint struct {
	Name      string
	Columns   []string
	IsPrimary bool
}

Constraint represents a PRIMARY KEY or UNIQUE constraint.

type DBSchema

type DBSchema struct {
	Tables []*Table
	Enums  []*Enum
	FKs    []*ForeignKey
}

DBSchema holds the full introspected schema.

func Introspect

func Introspect(ctx context.Context, db *sql.DB, engine Engine, schema string) (*DBSchema, error)

Introspect reads the schema of an already-open database using engine-specific catalog queries and returns it as a DBSchema. The caller owns the connection (its lifetime, pooling and the identity it authenticates as), which lets a server reuse its own pool instead of opening a fresh connection. For PostgreSQL and MariaDB, schema is the schema/database name to read; for SQLite it is ignored. Every query is bound to ctx. Pair it with GenerateDBML to render DBML.

type Engine

type Engine int

Engine identifies a supported database backend.

const (
	EngineMariaDB Engine = iota
	EnginePostgres
	EngineSQLite
)

type Enum

type Enum struct {
	Schema string
	Name   string
	Values []string
}

Enum represents a named enum type (PostgreSQL) or an inline enum column (MariaDB).

type ForeignKey

type ForeignKey struct {
	Name       string
	TableName  string
	Schema     string // empty for MariaDB/SQLite
	Columns    []string
	RefSchema  string
	RefTable   string
	RefColumns []string
	OnDelete   string
	OnUpdate   string
}

ForeignKey represents a FOREIGN KEY constraint.

type Index

type Index struct {
	Name       string
	Columns    []string
	IsUnique   bool
	Type       string // "btree", "hash", etc.
	Expression string // for functional/expression indexes
}

Index represents a non-constraint index on a table.

type Options

type Options struct {
	// Include: if non-empty, only tables whose names match one of these patterns are emitted.
	Include []string
	// Exclude: tables whose names match any of these patterns are omitted.
	Exclude []string
	// Data: when true, also fetch row data for each table.
	Data bool
}

Options controls which tables are included in the output.

type ParsedDSN

type ParsedDSN struct {
	Engine Engine
	DSN    string // driver-specific data-source name
	Schema string // schema / database name to introspect
}

ParsedDSN carries the normalised connection info.

func ParseDSN

func ParseDSN(rawDSN string) (*ParsedDSN, error)

ParseDSN parses a URL-form connection string and returns a ParsedDSN.

Supported schemes:

mariadb://user:pass@host:port/dbname
mysql://user:pass@host:port/dbname
postgres://user:pass@host:port/dbname[?schema=myschema]
postgresql://user:pass@host:port/dbname[?schema=myschema]
sqlite:///path/to/file.db
sqlite3:///path/to/file.db

type Record

type Record struct {
	Columns []string
	Rows    [][]string // each inner slice is one row of string-encoded values
}

Record holds the column names and row values for a table's data.

type Table

type Table struct {
	Schema           string // empty for MariaDB/SQLite
	Name             string
	Comment          string
	Columns          []*Column
	Indexes          []*Index
	Constraints      []*Constraint
	CheckConstraints []*CheckConstraint
	Records          *Record // populated when --data is used
}

Table represents a database table.