driver

type BulkIntrospector interface {
	BulkColumns(ctx context.Context, db *sql.DB, scope Scope) (map[string][]model.Column, error)
	BulkForeignKeys(ctx context.Context, db *sql.DB, scope Scope) (map[string][]model.ForeignKey, error)
}

type Capabilities struct {
	HasSchemas bool // PostgreSQL: true; MySQL/SQLite: false
	HasUsers   bool // privilege management
	// HasForeignKeys / HasStoredRoutines / HasTriggers / HasEvents / HasViews:
	// the engine has the object kind at all. The four with a Connection listing
	// gate it (ListViews / ListRoutines / ListTriggers / ListEvents return an
	// empty slice without a round-trip when false), so a dialect that lacks the
	// kind does not have to implement a stub that queries for nothing.
	HasForeignKeys           bool
	HasStoredRoutines        bool
	HasTriggers              bool
	HasEvents                bool // MySQL/MariaDB scheduled events
	HasViews                 bool
	SupportsExplain          bool
	SupportsTransactionalDDL bool // PG: true; MySQL: false; SQLite: partial
	SupportsCharset          bool // CREATE DATABASE ... CHARACTER SET (MySQL)
	SupportsColumnModify     bool // ALTER COLUMN type/null/default (MySQL/PG; not SQLite)
	SupportsColumnRename     bool // ALTER TABLE ... RENAME COLUMN (all three; MariaDB needs 10.5.2+)
	SupportsColumnPosition   bool // FIRST / AFTER col placement on ADD and MODIFY (MySQL only)
	SupportsForeignKeyDDL    bool // ALTER TABLE add/drop FK (MySQL/PG; not SQLite)
	CanManageDatabases       bool // CREATE/DROP DATABASE (MySQL/PG; not SQLite — one file)
	CanDropConnectedDatabase bool // DROP DATABASE works from a connection bound to that database (MySQL; PG needs a maintenance connection)
	ExecReportsChangedRows   bool // Exec's RowsAffected counts CHANGED rows, not matched (MySQL default protocol; PG/SQLite count matched)
	SupportsTruncate         bool // TRUNCATE TABLE (MySQL/PG; SQLite uses DELETE FROM)
	AccountHasHost           bool // account names carry a host part, 'user'@'host' (MySQL)
	SupportsRoleAttributes   bool // LOGIN/SUPERUSER/CREATEDB/CREATEROLE role attributes (PG)
	// SupportsRoles: role membership (GRANT role TO account) is available, so
	// the Users page renders its memberships section. Version-gated on
	// MySQL/MariaDB and failing CLOSED on an unknown version — the catalog
	// table is absent before MySQL 8.0 / MariaDB 10.0.5, so a wrong "yes" turns
	// the page into an error rather than hiding a section. Promises RoleManager.
	SupportsRoles        bool
	RestrictedDropColumn bool // dropping a PK/indexed/outgoing-FK column is refused (SQLite)
	// IsNetworkEngine: the connection target is a network address (host/port)
	// authenticated with credentials, rather than a local file the process
	// opens. It is the login path's single engine discriminator and carries
	// three consequences:
	//
	//   - Ad-hoc login is offered ONLY for network engines. A file-backed
	//     engine has no credentials, so letting a visitor type its connection
	//     target would be an unauthenticated arbitrary file open (and, for
	//     SQLite historically, create) on the host. File-backed engines are
	//     reachable only through an operator-configured predefined server.
	//   - Credentials are collected at login only for network engines.
	//   - The SSRF host policy (auth.CheckHost / DialControl) applies only to
	//     network engines — there is no host to resolve otherwise.
	//
	// A future engine that is network-attached but should still be barred from
	// ad-hoc login needs its own flag; today the two coincide exactly.
	IsNetworkEngine bool
	// ShowsSSLModeUI: the engine's AD-HOC LOGIN FORM exposes the sslmode
	// selector (PG). Deliberately not "UsesSSLMode": MySQL also consumes and
	// validates ConnParams.SSLMode from predefined-server config — the honest
	// distinction is which login form shows the selector.
	ShowsSSLModeUI bool
	// DatabasesShareConnection: every logical database is served by the ONE
	// server connection (SQLite: one file; ATTACH-ed names are session-scoped),
	// so ConnFor never opens per-database pools.
	DatabasesShareConnection bool

	// IdentifierMaxBytes bounds a new/renamed object name in bytes (0 = no hard
	// limit). PostgreSQL's 63 (NAMEDATALEN-1) is load-bearing: it silently
	// truncates a longer identifier, creating the object under an unexpected
	// name, so validate-first is a correctness requirement, not just politeness.
	// MySQL's 64 and SQLite's absence surface over-long names as clean errors.
	IdentifierMaxBytes int
}

type Collation struct {
	Name    string
	Charset string
	Default bool // the charset's default collation
}

type CollationLister interface {
	ListCollations(ctx context.Context, db *sql.DB) ([]Collation, error)
}

type CollationProber interface {
	CollationProbeSQL() string
}

type ColumnModifier interface {
	ModifyColumnSQL(t TableRef, old string, c ColumnSpec) ([]string, error)
}

type ColumnPlacement int

type ColumnPrivileger interface {
	PrivilegeManager
	// ColumnGrantablePrivileges is the subset of the table-scope allowlist that
	// accepts a column list — SQL restricts it to the privileges that read or
	// write column values (SELECT/INSERT/UPDATE/REFERENCES), and "GRANT DELETE
	// (col)" is a syntax error rather than a narrower DELETE. It is the single
	// source of truth for the form's column control and for grant validation,
	// exactly as GrantablePrivileges is for the keyword set.
	ColumnGrantablePrivileges() []string
}

type ColumnRenamer interface {
	RenameColumnSQL(t TableRef, old, newName string) ([]string, error)
}

type ColumnSpec struct {
	Name     string
	Type     string
	Comment  string
	Nullable bool
	Default  *string
	// DefaultExpr marks Default as an expression carried verbatim from
	// introspection (CURRENT_TIMESTAMP, nextval(...), (uuid())), as opposed to a
	// literal the form produced. MySQL wraps non-temporal expression defaults in
	// the parentheses its grammar requires; without this flag an expression
	// default re-applied through the editor would be re-quoted into a string
	// literal ('CURRENT_TIMESTAMP').
	DefaultExpr bool

	// Attributes preserved across a whole-definition MODIFY (MySQL restates the
	// entire column, so anything omitted is dropped). The handler fills these
	// from the existing column before ModifyColumnSQL; the add path leaves them
	// zero. Engines that modify per-attribute (PostgreSQL) ignore them, except
	// Identity, which PostgreSQL needs to avoid DROP/SET DEFAULT on an identity
	// column (a hard error).
	AutoIncrement bool   // MySQL AUTO_INCREMENT
	Unsigned      bool   // MySQL UNSIGNED numeric attribute
	Zerofill      bool   // MySQL ZEROFILL numeric attribute
	OnUpdate      string // MySQL "ON UPDATE <expr>" (validated CURRENT_TIMESTAMP[(n)])
	Collation     string // column collation to preserve (bare identifier)
	Charset       string // MySQL column character set to preserve (bare identifier)
	Identity      string // PostgreSQL identity mode to preserve: "" / "always" / "default"

	// Placement moves the column within the table's column ORDER. Only engines
	// that set Capabilities.SupportsColumnPosition act on it; the others MUST
	// ignore it rather than approximate it — PostgreSQL and SQLite have no way
	// to reorder columns at all, and the only faithful alternative (rebuild the
	// table, copy the data, swap it in) is not something a column edit should
	// do behind the user's back.
	Placement ColumnPlacement
	// PlacementAfter names the EXISTING column that Placement == PlaceAfter
	// refers to. The caller validates it against introspection first, and must
	// reject the column being modified naming itself.
	PlacementAfter string

	// SameBaseType is set on a MODIFY when the new base type matches the existing
	// one (only length/precision/attributes changed). PostgreSQL uses it to omit
	// the "USING col::type" cast: a same-base change needs no cast and, on a
	// shrink that would lose data, errors cleanly instead of silently truncating.
	// Other engines ignore it; the add path leaves it false.
	SameBaseType bool
}

type ConnParams struct {
	Host     string
	Socket   string
	Port     int
	User     string
	Password string
	Database string            // optional for MySQL; required for PostgreSQL
	FilePath string            // SQLite database file path
	SSLMode  string            // engine-specific TLS preference (sslmode / tls)
	Params   map[string]string // extra driver params, merged last

	// DialControl, when non-nil, is installed as the net.Dialer.Control hook on
	// every TCP connection opened from these params. It re-validates the
	// *resolved peer IP* of each connection (the SSRF / DNS-rebinding backstop:
	// a rebinding DNS answer cannot slip past the pre-flight resolution because
	// the address actually dialed is re-checked). It is set only for ad-hoc
	// network logins; predefined servers are operator-trusted and carry no
	// dial-time restriction. SQLite ignores it (no network).
	DialControl func(network, address string, c syscall.RawConn) error

	// OnStatement, when non-nil, is notified after each statement this
	// connection runs — the audit trail's statement half. It rides ConnParams
	// rather than being set on a Connection so that every DERIVED dial inherits
	// it for free: the session stamps it once at login and the per-database
	// pools, pinned script connections and export connections all carry it.
	//
	// Which statements reach it is deliberately asymmetric, and the asymmetry is
	// the whole design: see StatementObserver.
	OnStatement StatementObserver

	// Tuning carries the operator's pool and statement-timeout settings down
	// every dial. It rides ConnParams rather than a package-level variable so
	// there is no shared mutable state and a test can dial with its own values:
	// the session's base params are stamped once at login, and every derived
	// dial (per-database pool, pinned script, export connection, maintenance
	// connection) copies them for free. A zero Tuning means "driver defaults".
	Tuning Tuning
}

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

type DDLErrorHint interface {
	DDLErrorHint(err error) (hint string, ok bool)
}

type DataScoper interface {
	DataSelectOnly(ctx context.Context, db *sql.DB, scope Scope, tables []string) (map[string]bool, error)
}

type DatabaseManager interface {
	// CreateDatabaseSQL creates the database. collation, when non-empty, is a
	// default collation for the new database (MySQL/MariaDB `COLLATE …`; the
	// charset is implied by the collation). It is emitted as a BARE identifier
	// (backtick-quoting is invalid in that position), so the handler MUST have
	// validated it against the server's introspected collation list
	// (CollationLister) — never pass raw user input. Engines whose Capabilities
	// lack SupportsCharset ignore it.
	CreateDatabaseSQL(name, collation string) string
	// DropDatabaseSQL drops the database. PostgreSQL emits WITH (FORCE) (13+) so
	// the drop terminates OTHER sessions still connected to it rather than
	// failing; it cannot drop the database its own session is connected to, so
	// the caller must run it on a connection bound elsewhere.
	DropDatabaseSQL(name string) string
}

type DatabaseRebinder interface {
	RebindDatabase(p ConnParams, database string) ConnParams
}

type DefinitionViewer interface {
	ObjectDefinition(ctx context.Context, db *sql.DB, scope Scope, kind ProgramKind, name string) (string, error)
}

type Dialect interface {
	// Identity.
	Name() string        // canonical id: "mysql", "postgres", "sqlite"
	DisplayName() string // human label: "MySQL / MariaDB", "PostgreSQL", "SQLite"
	DefaultPort() int    // 0 for engines without a network port (SQLite)

	// Connection.
	SQLDriverName() string                 // database/sql driver name: "mysql", "pgx", "sqlite"
	BuildDSN(p ConnParams) (string, error) // engine-specific DSN/connection string

	// SQL syntax.
	QuoteIdent(name string) string // `name` / "name" with correct escaping
	QuoteString(s string) string   // 'literal' with correct escaping (for generated DDL/dumps)
	Placeholder(n int) string      // "?" (n ignored) / "$1"
	// LimitClause renders "LIMIT x OFFSET y" (or the engine equivalent). The
	// offset is int64 end-to-end: browse positions on >2^31-row tables must
	// not truncate through a 32-bit int.
	LimitClause(limit int, offset int64) string
	QualifyTable(t TableRef) string // engine-correct "[db|schema.]table", quoted
	// InsertDefaultRowSQL renders an INSERT that adds one all-defaults row, for a
	// table with NO insertable (non-generated) columns — a zero-column table, or
	// one whose every column is generated (both legal in PostgreSQL). Without it a
	// SQL dump silently loses every such row. PostgreSQL/SQLite use DEFAULT VALUES;
	// MySQL uses the empty () VALUES () form. qualified is already quoted.
	InsertDefaultRowSQL(qualified string) string

	// Connection-scoped helpers.
	ServerInfo(ctx context.Context, db *sql.DB) (ServerInfo, error)

	// Introspection — each takes ctx + *sql.DB and returns neutral model types.
	ListDatabases(ctx context.Context, db *sql.DB) ([]model.Database, error)
	ListSchemas(ctx context.Context, db *sql.DB, database string) ([]model.Schema, error)
	ListTables(ctx context.Context, db *sql.DB, scope Scope) ([]model.Table, error)
	Columns(ctx context.Context, db *sql.DB, t TableRef) ([]model.Column, error)
	Indexes(ctx context.Context, db *sql.DB, t TableRef) ([]model.Index, error)
	ForeignKeys(ctx context.Context, db *sql.DB, t TableRef) ([]model.ForeignKey, error)
	CreateSQL(ctx context.Context, db *sql.DB, t TableRef) (string, error)

	// Extended introspection. Implementations whose Capabilities report the
	// feature absent should return an empty slice (not an error).
	ListViews(ctx context.Context, db *sql.DB, scope Scope) ([]model.View, error)
	ListRoutines(ctx context.Context, db *sql.DB, scope Scope) ([]model.Routine, error)
	ListTriggers(ctx context.Context, db *sql.DB, scope Scope) ([]model.Trigger, error)
	ListEvents(ctx context.Context, db *sql.DB, scope Scope) ([]model.Event, error)
	ListUsers(ctx context.Context, db *sql.DB) ([]model.User, error)

	// ExplainSQL wraps a query for EXPLAIN; ok is false when unsupported.
	ExplainSQL(query string, analyze bool) (sql string, ok bool)

	Capabilities() Capabilities
}

type DropForm struct {
	// Class is the DROP command class whose grammar accepts a comma-separated
	// object list ("FUNCTION", "TYPE", …). "" — the zero value — means the
	// object's DROP has single-object syntax only (COLLATION, CAST, OPERATOR
	// CLASS, USER MAPPING) and can never be grouped: such a cycle is RETAINED
	// (drops omitted + warned) instead.
	Class string
	// Ref is this object's reference inside such a list: everything the command
	// needs after the class keyword and IF EXISTS.
	Ref string
	// RoutineRef, when non-empty, is this object's reference inside a grouped
	// DROP ROUTINE — the FLAT input signature (IN/INOUT/VARIADIC types only, no
	// ORDER BY split), which is the one spelling that matches functions,
	// procedures and aggregates alike, so an all-routine cycle of mixed kinds
	// drops in ONE statement. It is NOT interchangeable with Ref: an ordered-set
	// aggregate's identity arguments render an `ORDER BY` split that only DROP
	// AGGREGATE accepts.
	RoutineRef string
}

type DumpClause struct {
	Text     string       // appended to the script's SQL when the clause is kept
	Deps     []string     // node ids this clause (and only this clause) requires
	Finalize []DumpScript // the deferred DDL emitted instead when the clause is cut
	PreData  bool         // true: Finalize runs in the pre-data finalizer lane (domain defaults/constraints must precede consuming types/tables and data); false: post-data
}

type DumpMarker struct {
	Kind      string // "routine", "trigger" or "event"
	Name      string // object name, decoded
	Collation string // the source database's collation as recorded at dump time
}

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

type DumpPlan struct {
	// Types are user-defined types (PostgreSQL enums, domains, composites)
	// emitted BEFORE routines and tables, which may reference them — without
	// this pass a restore into an empty server fails at the first CREATE TABLE
	// naming an enum/domain. Their Drops run in teardown AFTER the tables, so a
	// column using the type is already gone. Only PostgreSQL populates this, and
	// the writer emits it only when structure is dumped.
	Types []DumpScript
	// Collations are user-defined collations (PostgreSQL) emitted BEFORE the types
	// and tables — a domain, composite attribute or column COLLATE may reference
	// one. Their Drops run in teardown AFTER the types (a domain over a collated
	// base type drops first). Only PostgreSQL populates this, structure-gated.
	Collations []DumpScript
	// Routines are emitted before the tables: functions/procedures may be
	// referenced by views, triggers or generated columns.
	Routines []DumpScript
	// Sequences (CREATE SEQUENCE) are emitted after teardown, before the
	// tables, so a serial/standalone column DEFAULT nextval(...) resolves at
	// CREATE TABLE time. Their Drops run in teardown AFTER the DROP TABLEs:
	// an owned sequence is auto-dropped with its table, and an OWNED BY /
	// default dependency would block an earlier DROP. Only PostgreSQL populates
	// this; the writer emits it only when structure is dumped.
	Sequences []DumpScript
	// ForeignData (C4.3) holds foreign-table creates (schema plans) and rides
	// the pre-data slot between sequences and tables (pg_dump's foreign-data
	// priority; a foreign table can INHERIT a local parent — the edge hoists
	// the parent). Structure-only: foreign tables have NO data pass — their
	// rows live on the remote server.
	ForeignData []DumpScript
	// Views (and materialized views) are emitted after the tables,
	// dependency-ordered so a view referencing another view restores.
	Views []DumpScript
	// PostData is emitted after all rows: foreign-key ALTERs (PostgreSQL),
	// NOT VALID constraints, secondary indexes (SQLite), triggers (so restored
	// INSERTs do not fire them), events, materialized-view refreshes and
	// sequence synchronization, in that order.
	PostData []DumpScript
	// Warnings are best-effort advisories (skipped objects, unsynchronized
	// external state, dependency hazards) the writer emits as inert `-- WARNING:`
	// comment lines — routed through commentSafe — at the top of the dump body in
	// every mode. They never fail the export.
	Warnings []string
	// SchemaComment is the COMMENT ON SCHEMA text (PostgreSQL), emitted in the
	// structure phase INDEPENDENTLY of the CREATE SCHEMA line (the default/public
	// section writes no CREATE SCHEMA, but a comment on it must still round-trip).
	SchemaComment string
	// ViewEdges (C3) are the DATABASE-WIDE (dependent, source) edges among
	// views/matviews, as qualified "schema.name" pairs resolved by relation OID
	// through pg_rewrite — the planner topo-orders cross-schema matview
	// REFRESHes with them. Only PostgreSQL populates this.
	ViewEdges [][2]string
	// TableNodes (C3) maps each dumped table's BARE name to its dependency-graph
	// metadata (tables are not DumpScripts — the handler owns their emission —
	// so their edges ride here). Only PostgreSQL populates this.
	TableNodes map[string]DumpTableNode
	// DataOnlyTables (C4.3) names tables whose ROWS are dumped but whose
	// STRUCTURE is not: the local leaves of a partition tree containing a
	// FOREIGN leaf. The tree's root emits every child's structure recursively,
	// but its data scan cannot run (a plain FROM on the root would query the
	// foreign leaf's REMOTE server), so the local leaves are read individually
	// (FROM ONLY) instead — emitting their creates too would duplicate the DDL.
	DataOnlyTables []string
	// SuppressedRelations (C4.3) names relations classified state (c) —
	// unreproducible under the redaction policy, emitted only as inert
	// templates — whose dependents (triggers/comments/rules) were suppressed
	// with them.
	SuppressedRelations []string
	// StructureOnlyTables (C4.3) names tables whose STRUCTURE is dumped but
	// whose DATA scan must not run: a mixed local/foreign partition tree's
	// ROOT (its plain FROM would recurse into the foreign leaf and query the
	// remote server; the local leaves in DataOnlyTables carry the rows).
	StructureOnlyTables []string
	// SequenceRewrites (C5.1/C5.2) maps an out-of-scope source sequence (keyed
	// SeqRefKey(schema, name)) to the replacement sequence materialized in its
	// place (a SeqRefKey-shaped value). The handler routes every emitted table's
	// DDL through RewriteSequenceRefs so early-bound ('s'::regclass) and
	// resolvable late-bound ('s'::text) default references bind to the
	// replacement. Only PostgreSQL populates this, and only for scoped
	// (non-database) exports — a database-scope dump emits every sequence.
	SequenceRewrites map[string]string
	// StagedDefaultColumns (C5.3) names, per BARE table, columns whose inline
	// DEFAULT must be suppressed at CREATE time and re-established post-data
	// (Kind "staged-default"): the multi-parent divergent-default conflict —
	// CREATE … INHERITS fails on conflicting parent defaults before any staged
	// DDL could run, so every affected hierarchy member creates default-less
	// and re-emits its own state via ALTER TABLE ONLY. The handler renders
	// these tables through StagedTableDumper. Only PostgreSQL populates this.
	StagedDefaultColumns map[string][]string
}

type DumpScript struct {
	// Kind classifies the object: "routine", "view", "matview", "trigger",
	// "event", "index", "constraint", "sequence", "sequence-def",
	// "sequence-own", "refresh". The exporter uses it for teardown ordering
	// (constraints drop before tables) and to keep the data-section items
	// (setval "sequence" / matview "refresh") in data-only dumps while dropping
	// structure-only items ("sequence-def" CREATE SEQUENCE lives in DumpPlan.
	// Sequences; "sequence-own" ALTER SEQUENCE … OWNED BY is post-data structure).
	Kind           string
	Comment        string // short human label for the dump ("Trigger trg_audit")
	Drop           string // optional teardown statement (DROP ... IF EXISTS), emitted when the user asked to drop first
	SQL            string
	NeedsDelimiter bool // MySQL routine/trigger/event body: internal ';' needs DELIMITER wrapping

	// DropInline marks an object whose Drop is emitted INLINE, immediately
	// before its own CREATE (mysqldump parity for routines and events), instead
	// of in the reverse-ordered teardown block. PostgreSQL leaves it false for
	// every class: a routine's drop must precede the DROP TYPE of a type in its
	// signature, which only the reverse teardown order guarantees.
	DropInline bool
	// StageOf, on a script that is one CREATION STAGE of a larger logical object
	// (a shell type and the CREATE that completes it), is that object's
	// canonical node id. Creation ordering uses the per-stage Name — the whole
	// point of staging is that the stages sort separately — but TEARDOWN
	// collapses them back onto this id: the RESTORED catalog holds one object
	// whose dependencies close the very cycle staging broke, so the drop graph
	// must see it as one node.
	StageOf string
	// DropForm describes how this object's Drop may be merged into a
	// multi-object DROP — the only non-CASCADE way to drop a dependency cycle
	// (see DropForm). Zero value: ungroupable.
	DropForm DropForm

	// Name is this script's node id in the C3 dump dependency graph:
	// "<catalog-kind>:<qualified name>[(identity args)]" — e.g.
	// "type:public.mood", "relation:public.emp", "routine:public.f(integer)".
	// Identity arguments / operand types / access method are part of the id so
	// overloads and cross-type members never collapse. A staged object's later
	// stage appends "-final" ("type-final:…", "routine…-final"). Empty means the
	// script takes no part in graph ordering (MySQL/SQLite plans) and keeps its
	// stable class-priority position.
	Name string
	// DependsOn lists node ids this script requires created first. An id
	// missing from the emitted set is a BOUNDARY edge (a reference to an
	// out-of-scope object): the topological sort ignores it and the planner
	// surfaces it as a restore-prerequisite diagnostic, never a failure.
	DependsOn []string
	// Clauses are deferrable trailing clauses (a domain's DEFAULT / CHECK):
	// normally each Text is appended to SQL in order, but when a clause's Deps
	// close a dependency cycle the planner CUTS it — the clause text is omitted
	// and its Finalize scripts (ALTER … SET DEFAULT / ADD CONSTRAINT, plus any
	// moved COMMENT) run later in the lane PreData selects.
	Clauses []DumpClause
	// Stub, when non-empty, is a dependency-reduced replacement create for a
	// routine caught in a dependency cycle: the same signature with every
	// argument default omitted (the whole trailing default group — a partial
	// omission would be invalid DDL) and an unchecked placeholder body
	// (check_function_bodies=false stores string bodies verbatim, and
	// CREATE OR REPLACE may change language/body/defaults, so the original SQL
	// — already CREATE OR REPLACE — restores the real object as the "-final"
	// stage). StubDeps are the edges the stub RETAINS (signature types); if
	// those still form a cycle the plan preflight-fails.
	Stub     string
	StubDeps []string

	// OpaqueFrame marks SQL as raw bytes fetched under
	// character_set_results=binary (MySQL object bodies): the writer wraps it
	// in a TableX opaque frame — a frame marker plus a body-derived DELIMITER
	// — and the splitter replays the framed bytes verbatim with no
	// string/comment interpretation, so a non-UTF-8 or NO_BACKSLASH_ESCAPES
	// body cannot be mangled or mis-split. Implies DELIMITER wrapping.
	OpaqueFrame bool
	// Pre/Post are complete session-guard statements the writer emits around
	// SQL (outside any DELIMITER wrap): mysqldump-style save/set/restore of
	// the object's creation context (sql_mode, character_set_client,
	// collation_connection, event time_zone). Save variables MUST use
	// object-local @saved_* names, never the preamble's @OLD_* names, which
	// the postamble restores last.
	Pre  []string
	Post []string
	// Markers are pre-formatted inert TableX marker lines (FormatCollationMarker)
	// emitted verbatim before the script — disclosure comments to external
	// clients, warning events to TableX's own importer.
	Markers []string
}

type DumpTableNode struct {
	Name                  string // the table's node id ("relation:<schema>\x00<name>")
	Deps                  []string
	DeferrableDefaults    map[string][]string // column name → node ids its DEFAULT expression references
	DeferrableConstraints map[string][]string // constraint name → node ids its expression references
}

type Dumper interface {
	// DumpTableCreate returns the restore-oriented CREATE statement(s) for one
	// table, ending without a trailing terminator on the last statement.
	DumpTableCreate(ctx context.Context, db *sql.DB, t TableRef) (string, error)

	// DumpDataTables returns the subset of tables whose rows the data phase
	// reads directly, preserving order. PostgreSQL excludes partition children:
	// their structure rides with the parent and a SELECT on the parent already
	// returns their rows (dumping both would duplicate every row).
	DumpDataTables(ctx context.Context, db *sql.DB, scope Scope, tables []string) ([]string, error)

	// DumpObjects returns everything beyond table DDL and data for the given
	// tables. dbScope and structure are independent: dbScope=false (table-scope
	// export) returns only objects belonging to the listed tables (triggers,
	// indexes, constraints, owned sequences), while dbScope=true also covers
	// database-scope objects (routines, views, events, standalone sequences).
	// structure=false (data-only export) suppresses ALL structure-only DDL
	// (routines/views/triggers/indexes/constraints/sequence ownership) so a
	// data-only dump neither fails on nor wastes introspection it would
	// discard, while still collecting the data-section items (sequence setval,
	// matview refresh) pg_dump emits in a --data-only run.
	DumpObjects(ctx context.Context, db *sql.DB, scope Scope, tables []string, dbScope, structure bool) (DumpPlan, error)

	// ValueLiteral renders a scanned cell as an engine-correct SQL literal for
	// the dump's INSERT statements: the binary form (X'…' vs '\x…'), MySQL's
	// zero-date sentinel, and non-finite float handling all live here rather
	// than in engine switches at the call site.
	ValueLiteral(col ResultColumn, v Value) string

	// DumpPreamble writes the session state a restore needs pinned before the
	// script body (FK checks, sql_mode, string-escape settings, time zone);
	// DumpPostamble restores it for sessions that outlive the script. Either
	// may write nothing.
	DumpPreamble(w io.Writer)
	DumpPostamble(w io.Writer)
}

type EventManager interface {
	DropEventSQL(s Scope, e model.Event) ([]string, error)
	NewEventTemplate() string
}

type ExecResult struct {
	RowsAffected int64
}

type ExportConnAdjuster interface {
	ExportConnParams(p ConnParams) ConnParams
}

type FilePathValidator interface {
	ValidateFilePath(path string) error
}

type ForeignKeyEditor interface {
	AddForeignKeySQL(t TableRef, name string, cols []string, refTable string, refCols []string, onUpdate, onDelete string) ([]string, error)
	DropForeignKeySQL(t TableRef, name string) ([]string, error)
}

type ForeignTableDumper interface {
	IsForeignTable(ctx context.Context, db *sql.DB, scope Scope, name string) (bool, error)
	DumpForeignTable(ctx context.Context, db *sql.DB, scope Scope, name string) (DumpPlan, error)
}

type GlobalDumper interface {
	DumpGlobalObjects(ctx context.Context, db *sql.DB, structure bool) (DumpPlan, error)
}

type GrantSpec struct {
	Privileges []string
	Database   string
	Schema     string // PostgreSQL table scope; ignored elsewhere
	Table      string // "" → database scope
	Grantee    string
	Host       string // MySQL grantee host part
	WithGrant  bool
	// Columns restricts the grant to specific columns of Table
	// (GRANT SELECT (a, b) ON t). Empty — the default — is an object-wide
	// grant. Names must have been matched against live introspection by the
	// caller; the builders only quote them.
	//
	// Dropping this list does not fail safe, it WIDENS: "SELECT on two columns"
	// silently becomes "SELECT on every column". So a dialect that cannot
	// express column scope must not receive it — Connection.Grant/Revoke refuse
	// a non-empty Columns unless the dialect is a ColumnPrivileger, and the
	// builders re-check.
	Columns []string
	// DatabasePatterns carries the stored grant pattern(s) exactly as
	// introspected (model.Privilege.StoredObject) for a MySQL database-scope
	// REVOKE: pre-escaped as stored, used verbatim, one REVOKE per pattern.
	// Empty (the default, and always for GRANT and other engines) falls back
	// to escaping Database.
	DatabasePatterns []string
}

type Grouper[K comparable, T any] struct {
	// contains filtered or unexported fields
}

type IndexColumn struct {
	Name string
	// Desc orders this key part descending. Only set it when
	// IndexOptions().SupportsDesc — MariaDB, for one, PARSES the keyword and
	// then ignores it, which is worse than refusing it.
	Desc bool
	// Prefix indexes only the leading Prefix characters/bytes of the column
	// (MySQL's col(10)). Zero indexes the whole value. Only set it when
	// IndexOptions().SupportsPrefix.
	Prefix int
}

type IndexOptioner interface {
	IndexOptions() IndexOptions
}

type IndexOptions struct {
	// Methods are the offerable access methods, engine spelling. Empty means
	// the engine has no choice to make (MySQL: the storage engine decides).
	Methods []string
	// SupportsDesc: a descending key part is honoured, not merely parsed.
	SupportsDesc bool
	// SupportsPrefix: a key part may index a leading prefix of the value.
	SupportsPrefix bool
	// SupportsPartial: the index may carry a WHERE predicate.
	SupportsPartial bool
}

type IndexSpec struct {
	Name    string
	Columns []IndexColumn
	Unique  bool
	// Method is the access method / index type: an entry from
	// IndexOptions().Methods, or "" for the engine default. It is emitted as a
	// keyword, so only an allowlisted value may reach it.
	Method string
	// Where is a partial index's predicate, already guarded by the caller. It
	// is the one part of an index that is user-written SQL rather than an
	// identifier or a keyword — see docs/security.md.
	Where string
}

type Inheritor interface {
	InheritanceParents(ctx context.Context, db *sql.DB, scope Scope, tables []string) (map[string][]string, error)
	DumpInheritsChildCreate(ctx context.Context, db *sql.DB, t TableRef, parents []string) (string, error)
}

type LexerProfile struct {
	// BackslashStrings: a backslash escapes the next character inside '…' and
	// "…" string literals (MySQL default mode; never backtick identifiers).
	BackslashStrings bool
	// EscapeStringE: E'…' literals honor backslash escapes even though plain
	// '…' strings do not (PostgreSQL).
	EscapeStringE bool
	// DollarQuotes: $tag$…$tag$ dollar-quoted literals (PostgreSQL). Engines
	// where '$' is an identifier character must leave this off, or a$$b would
	// open a quote.
	DollarQuotes bool
	// HashComments: '#' starts a line comment (MySQL).
	HashComments bool
	// DashCommentNeedsSpace: a `--` line comment requires following whitespace
	// or end-of-line (MySQL); otherwise any `--` starts a comment.
	DashCommentNeedsSpace bool
	// NestedBlockComments: /* … */ block comments nest (PostgreSQL).
	NestedBlockComments bool
	// DelimiterDirectives: mysql-client DELIMITER directives are recognized,
	// including the TableX opaque frames dumped routine bodies travel in.
	DelimiterDirectives bool
	// DollarInWords: '$' is an ordinary identifier character (MySQL/SQLite).
	DollarInWords bool
	// BracketIdentifiers: [name] is a quoted identifier, with ]] escaping a
	// literal ']' — the T-SQL / Microsoft Access convention, which SQLite also
	// accepts. Engines where '[' is an operator (PostgreSQL array subscripts)
	// must leave this off. Without it a separator inside a bracket-quoted name
	// (`[a;b]`) splits the statement.
	BracketIdentifiers bool
	// BatchSeparator, when non-empty, is a CLIENT-SIDE batch terminator
	// recognized as the only content on its own line, case-insensitively —
	// T-SQL's `GO`. It ends the current statement the way the statement
	// separator does, but the word itself is never sent to the server. Empty
	// (every engine here today) means the engine has none.
	BatchSeparator string
	// RoutineBodyRe, when non-nil, matches routine-creating statements whose
	// BEGIN…END bodies hold internal semicolons, so the splitter tracks block
	// depth instead of splitting inside the body. Engines whose bodies are
	// quoted strings (PostgreSQL dollar quoting) leave it nil.
	RoutineBodyRe *regexp.Regexp
	// Returning describes which DML statement kinds support a RETURNING clause
	// on this engine+version, so the SQL console can classify a RETURNING-bearing
	// INSERT/UPDATE/DELETE/REPLACE/MERGE as row-returning (grid) rather than a
	// bare Exec. Populated per dialect from flavor/version.
	Returning ReturningCaps
}

type LoginDatabaseHint struct {
	Label       string // field label ("" = the generic "Database")
	Placeholder string
	// Default is the value the form may pre-fill into an EMPTY field (and
	// clear again when switching engines, never touching a user-typed value).
	// The server-side authority for the same default is NormalizeParams.
	Default string
	// Note is a plain-text help sentence under the field ("" = none).
	Note string
}

type LoginFormHinter interface {
	LoginDatabaseHint() LoginDatabaseHint
}

type MaintenanceDatabaseLister interface {
	MaintenanceDatabases() []string
}

type Monitor interface {
	Status(ctx context.Context, db *sql.DB) ([]model.Variable, error)
	Variables(ctx context.Context, db *sql.DB) ([]model.Variable, error)
	Processes(ctx context.Context, db *sql.DB) (*ResultSet, error)
}

type NameLister interface {
	ListDatabaseNames(ctx context.Context, db *sql.DB) ([]model.Database, error)
	ListTableNames(ctx context.Context, db *sql.DB, scope Scope) ([]model.Table, error)
}

type NestedGrouper[K1, K2 comparable, T any] struct {
	// contains filtered or unexported fields
}

type Pagination struct {
	Limit  int
	Offset int64
}

type ParamsNormalizer interface {
	NormalizeParams(p ConnParams) ConnParams
}

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

type PoolOpener interface {
	OpenPool(p ConnParams) (*sql.DB, error)
}

type PrivilegeManager interface {
	GrantablePrivileges(table bool) []string // curated allowlist: table or database scope
	GrantSQL(g GrantSpec) ([]string, error)
	RevokeSQL(g GrantSpec) ([]string, error)
}

type Privileger interface {
	Privileges(ctx context.Context, db *sql.DB, ref TableRef) ([]model.Privilege, error)
}

type ProcessManager interface {
	// ProcessIDColumn is the Processes() column whose value KillProcessSQL
	// takes ("Id" on MySQL, "pid" on PostgreSQL).
	ProcessIDColumn() string
	// KillProcessSQL terminates the session with this identifier.
	//
	// The id is an int64, not a string, and that is a deliberate part of the
	// contract rather than a convenience: neither engine accepts a placeholder
	// where the identifier goes (MySQL's KILL takes no parameters at all), so
	// the value is formatted into the statement — and an integer parsed by the
	// caller cannot carry anything else. Do not widen this to a string.
	KillProcessSQL(id int64) string
}

type ProgramKind string

type ResultColumn struct {
	Name    string
	DBType  string // DatabaseTypeName(), e.g. "VARCHAR", "INT4", "BLOB"
	Numeric bool
	Binary  bool
}

type ResultSet struct {
	Columns   []ResultColumn
	Rows      [][]Value
	Truncated bool // true when more rows existed than the cap returned
}

type ReturningCaps struct {
	Insert, Update, Delete, Replace, Merge bool
}

type RoleGrant struct {
	Role       string
	RoleHost   string // MySQL 8 role account host; ignored by MariaDB and PostgreSQL
	Member     string
	MemberHost string // MySQL/MariaDB grantee host
	// AdminOption lets the member grant the role onward. Ignored by REVOKE,
	// which removes the membership entirely.
	AdminOption bool
}

type RoleManager interface {
	RoleMemberships(ctx context.Context, db *sql.DB) ([]model.RoleMembership, error)
	GrantRoleSQL(g RoleGrant) ([]string, error)
	RevokeRoleSQL(g RoleGrant) ([]string, error)
}

type RoutineGrant struct {
	Scope      Scope
	Routine    model.Routine
	Privileges []string
	Grantee    string
	Host       string // MySQL grantee host part
	WithGrant  bool
}

type RoutineManager interface {
	DropRoutineSQL(s Scope, r model.Routine) ([]string, error)
	NewRoutineTemplate(kind ProgramKind) string
}

type RoutinePrivileger interface {
	// RoutineGrantablePrivileges is the curated allowlist for routine scope —
	// EXECUTE everywhere, plus MySQL's ALTER ROUTINE.
	RoutineGrantablePrivileges() []string
	RoutinePrivileges(ctx context.Context, db *sql.DB, s Scope, r model.Routine) ([]model.Privilege, error)
	GrantRoutineSQL(g RoutineGrant) ([]string, error)
	RevokeRoutineSQL(g RoutineGrant) ([]string, error)
}

type RowEstimator interface {
	EstimateRows(ctx context.Context, db *sql.DB, t TableRef) (int64, error)
}

type SchemaEditor interface {
	ColumnTypes() []string // curated base-type allowlist for the UI + validation
	// CreateTableSQL builds the statements for a NEW table: t names it (the
	// handler validates the name and non-existence first), cols is the full
	// ordered column list, pk the PRIMARY KEY column names (each must appear in
	// cols; empty for no PK). One CREATE TABLE statement — PK inline or as a
	// table constraint — plus any trailing comment statements the engine needs.
	// Implementations reject empty cols and unknown pk entries via
	// ValidateCreateTable.
	CreateTableSQL(t TableRef, cols []ColumnSpec, pk []string) ([]string, error)
	AddColumnSQL(t TableRef, c ColumnSpec) ([]string, error)
	DropColumnSQL(t TableRef, col string) ([]string, error)
	// DropObjectSQL emits the DROP for a table, view or materialized view. kind
	// is one of the Object* constants; matview is PostgreSQL-only (other engines
	// treat it as a view). Routing DROP through the dialect keeps a
	// DROP TABLE-on-a-view (which errors on every engine) from ever being emitted.
	DropObjectSQL(t TableRef, kind string) ([]string, error)
	// RenameObjectSQL renames a table, view or materialized view to newName. kind
	// selects the correct statement where engines differ: a MySQL view cannot be
	// renamed with ALTER TABLE (error 1347) and needs RENAME TABLE; a PostgreSQL
	// materialized view uses ALTER MATERIALIZED VIEW.
	RenameObjectSQL(t TableRef, newName, kind string) ([]string, error)
	AddIndexSQL(t TableRef, spec IndexSpec) ([]string, error)
	DropIndexSQL(t TableRef, name string) ([]string, error)
}

type SchemaManager interface {
	CreateSchemaSQL(name string) string
	// DropSchemaSQL drops the schema and every object in it (CASCADE); the
	// handler shows an explicit confirmation before invoking it.
	DropSchemaSQL(name string) string
}

type Scope struct {
	Database string
	Schema   string
}

type SearchCaster interface {
	SearchExpr(quotedIdent string) string
}

type ServerDumpFramer interface {
	ServerDumpProfile() ServerDumpProfile
	// WriteServerDumpHeader writes the engine's help comment lines for the
	// dump header (may write nothing).
	WriteServerDumpHeader(w io.Writer)
	// WriteDatabaseSectionHeader introduces one database's section: the
	// executable CREATE DATABASE …/USE pair (MySQL, preserving the
	// introspected default collation), the \connect meta-command (PostgreSQL),
	// or nothing (SQLite). collation is the database's introspected default
	// collation ("" when unknown/unsupported).
	WriteDatabaseSectionHeader(w io.Writer, name, collation string)
	// UnaddressableDatabase reports a human-readable reason the named database
	// cannot be addressed by this dump format ("" = addressable). PostgreSQL
	// skips names containing \r or \n: a psql \connect argument cannot
	// continue past end-of-line, and the residual fragment would leak into the
	// next section as executable SQL (the pg_dumpall CVE-2016-5424 class).
	UnaddressableDatabase(name string) string
}

type ServerDumpProfile struct {
	// PerSectionPreamble: the session preamble/postamble must be re-emitted
	// inside each database section (PostgreSQL: session SETs do not survive
	// \connect) instead of once globally.
	PerSectionPreamble bool
	// UsesConnectMarkers: sections switch databases via psql-style \connect
	// meta-commands, which the server-scope import honors (the import-side
	// mirror of this flag — export and import share it).
	UsesConnectMarkers bool
	// FormNote is the plain-text help sentence the export form shows for a
	// server-scope dump ("" = none).
	FormNote string
}

type ServerInfo struct {
	Engine    string // dialect Name(): "mysql", "postgres", "sqlite"
	Flavor    string // "MySQL", "MariaDB", "PostgreSQL", "SQLite"
	Version   string // full version string
	User      string // CURRENT_USER as reported by the server
	Charset   string // server/connection default charset
	Collation string // server/connection default collation
	Host      string // connection target host (for display only)
	Port      int
	Database  string // current database, when bound to one
	// SQLMode carries the MySQL/MariaDB @@SESSION.sql_mode at connect time, so a
	// dialect can specialize string escaping for NO_BACKSLASH_ESCAPES via the
	// optional WithServerInfo hook. Empty for engines that do not report it.
	SQLMode string
}

type ServerSpecializer interface {
	WithServerInfo(info ServerInfo) Dialect
}

type Sort struct {
	Column     string // must be validated against real columns before use
	Descending bool
}

type StagedTableDumper interface {
	DumpTableCreateStaged(ctx context.Context, db *sql.DB, t TableRef, parents []string, stripDefaults, stripConstraints []string) (string, []DumpScript, error)
}

type StatementEvent struct {
	// SQL is the statement as it was sent. The caller bounds its length before
	// recording it: an import statement can be megabytes.
	SQL string
	// Rows is the affected-row count for a mutation, or -1 where the engine or
	// the code path does not report one.
	Rows     int64
	Duration time.Duration
	// Err is the statement's error, or nil. A statement error may echo the
	// statement itself, which is already being recorded, so it carries nothing
	// the trail does not already hold.
	Err error
	// UserSQL distinguishes SQL the USER wrote (the console, an import) from SQL
	// TableX generated on their behalf (the Drop button, the structure editor).
	// An auditor reading "DROP TABLE orders" wants to know which it was.
	UserSQL bool
}

type StatementLexer interface {
	LexerProfile() LexerProfile
}

type StatementObserver func(ctx context.Context, ev StatementEvent)

type StorageDDL struct {
	// ID types a short ASCII identifier — at most 64 characters — that must be
	// usable as a PRIMARY KEY and inside an index. That requirement is why it is
	// not simply Text: MySQL cannot index a TEXT column without a prefix length.
	ID string
	// Text types unbounded UTF-8 text.
	Text string
	// Int64 types a signed 64-bit integer.
	Int64 string
	// TableOptions is appended verbatim to every CREATE TABLE (empty for engines
	// that need nothing). It must begin with a space if non-empty. MySQL pins
	// both the character set — a server defaulting to latin1 would otherwise
	// silently mangle non-ASCII text — and a transactional engine, which the
	// storage layer's atomic updates require.
	TableOptions string
}

type StorageHost interface {
	StorageDDL() StorageDDL
}

type TableMaintainer interface {
	TableMaintenanceOps() []TableMaintenanceOp
	TableMaintenanceSQL(t TableRef, op string) (string, error)
}

type TableMaintenanceOp struct {
	Name  string // stable key the form posts back ("optimize")
	Label string // button text ("Optimize")
	Note  string // one line explaining what it does, shown as the button's title
	// Confirm, when non-empty, is the prompt shown before running. Set it for
	// anything that takes a heavy lock or rewrites the table — these operations
	// are not destructive, but running one on a large production table by
	// accident is its own kind of damage.
	Confirm string
}

type TableRef struct {
	Database string
	Schema   string
	Table    string
}

type TeardownAuditor interface {
	AuditTeardown(ctx context.Context, db *sql.DB, planned []TeardownDrop) ([]string, error)
}

type TeardownDrop struct {
	Node string
	SQL  string
}

type TriggerManager interface {
	DropTriggerSQL(s Scope, t model.Trigger) ([]string, error)
	// table is the table the editor was opened from, or "" at database level.
	NewTriggerTemplate(table string) string
}

type Tuning struct {
	// MaxOpenConns / MaxIdleConns size a pool. OpenPinned ignores both: a pinned
	// script is one physical session by definition.
	MaxOpenConns int
	MaxIdleConns int
	// ReadStmtTimeout overrides the per-statement budget for generated reads
	// (see the ReadStmtTimeout constant for exactly which statements).
	ReadStmtTimeout time.Duration
}

type UserManager interface {
	CreateUserSQL(u UserSpec) ([]string, error)
	AlterUserSQL(u UserSpec) ([]string, error) // set password and/or role attributes
	DropUserSQL(name, host string) ([]string, error)
}

type UserSpec struct {
	Name        string
	Host        string // MySQL account host part ('user'@'host'); ignored by role engines
	Password    string
	SetPassword bool // distinguishes "set this password (possibly blank)" from "leave unchanged"
	CanLogin    bool // PostgreSQL LOGIN attribute; MySQL accounts always log in
	Super       bool // PostgreSQL SUPERUSER
	CreateDB    bool // PostgreSQL CREATEDB
	CreateRole  bool // PostgreSQL CREATEROLE
}

type Value struct {
	Null   bool
	Binary bool
	Str    string
	Bytes  []byte // raw binary content; populated only by StreamResult
}

type ValueListTyper interface {
	// ValueListTypes returns the base types requiring a value list, spelled as
	// they appear in ColumnTypes().
	ValueListTypes() []string
	// ValueListType assembles the type. base is an allowlisted ColumnTypes()
	// entry; values is the user's list, non-empty, in order. It returns an
	// error for a list this engine cannot accept (a duplicate, or more members
	// than the type allows).
	ValueListType(base string, values []string) (string, error)
}

type ValueLiteralHooks struct {
	// BinaryLiteral spells a binary cell's raw bytes as an SQL literal.
	BinaryLiteral func(b []byte) string
	// TextSpecial, when non-nil, may short-circuit a non-null, non-binary
	// value with an engine literal (ok=true) before any numeric handling.
	TextSpecial func(col ResultColumn, s string) (lit string, ok bool)
	// NonFinite maps a NonFiniteFloat class ("nan", "+inf", "-inf") to the
	// engine literal. nil applies the fallback finite guard: a non-finite
	// token is not a valid bare numeric literal, so it is emitted as quoted
	// text.
	NonFinite func(class string) string
}

type VersionFloor interface {
	// ServerBelowFloor reports the documented floor for the connected flavor, and
	// whether this server is older than it. An implementation that cannot parse
	// the version must answer false: guessing "too old" would cry wolf on every
	// unfamiliar build string.
	ServerBelowFloor() (floor string, below bool)
}

type ViewDumper interface {
	DumpView(ctx context.Context, db *sql.DB, scope Scope, name string, withData bool) (DumpPlan, error)
}