dialect

type Conn interface {
	// Exec runs one statement. DDL, so nothing is returned.
	Exec(ctx context.Context, statement string) error

	// Scalar runs a query of one row and one column. A query matching no row
	// returns nil, nil -- that is "nothing is there", which is an ANSWER on
	// this path and not a failure.
	Scalar(ctx context.Context, query string) (any, error)

	// Target names a relation the way the CATALOG does:
	// `bigquery://project/dataset/table`, `postgres://database/schema/table`.
	//
	// ON Conn AND NOT ON Dialect, because only a live connection knows the
	// first segment: the project for BigQuery, the database for Postgres,
	// and the latter is inside a DSN this package never sees in one piece.
	//
	// It is what puts a model on `/data`. The engine takes it on a `landed`
	// line and refuses anything that does not match its own rule -- counting
	// the refusal rather than failing the step, deliberately, because a
	// target the engine repaired would be a target the engine inferred. A
	// wrong one here is therefore a model that builds, reports success and
	// never appears, which is why the conformance suite asserts its shape.
	Target(ref string) string

	Close(ctx context.Context) error
}

type Dialect interface {
	// Name is what `--dialect` is given, and it is also the name the
	// reference extractor is given: a project cannot read its SQL as one
	// dialect and build it as another.
	Name() string

	// Open connects. The DSN comes from an environment variable named in the
	// command line, never from a file -- a connection string carries a
	// password and a project directory is in git.
	Open(ctx context.Context, dsn string) (Conn, error)

	// EnsureSchema is run before the models of that schema, and has to be
	// safe to run when the schema is already there.
	EnsureSchema(schema string) []string

	// KindOf is a query whose single value is "table", "view" or NULL.
	KindOf(ref string) string

	// Literal is a Go string as this warehouse's SQL spells it, quotes
	// included.
	//
	// ON THE INTERFACE BECAUSE IT MEASURABLY DIFFERS, and for no other
	// reason -- with one backslash in the statement, on 2026-10-08:
	//
	//	postgres   SELECT LENGTH('a\bc')  ->  4   a backslash is a character
	//	bigquery   SELECT LENGTH('a\bc')  ->  3   \b is a backspace
	//
	// A value a consumer wrote in an `accepted_values` test therefore means
	// two different things depending on where the project runs, and the
	// check built from it would pass against data it should refuse.
	Literal(s string) string

	// ColumnsOf is a query whose single value is the relation's column
	// names, in ordinal order, comma-separated.
	//
	// ONE VALUE AND NOT A ROW SET, so Conn keeps its two methods. `MERGE ...
	// WHEN MATCHED THEN UPDATE SET` has to name every column -- BigQuery has
	// no `SET *`, measured 2026-10-08 -- so the list has to be asked for, and
	// `STRING_AGG(column_name, ',' ORDER BY ordinal_position)` is what both
	// warehouses answer it with. A third Conn method for one caller would
	// have been the thing this package's own comment argues against.
	ColumnsOf(ref string) string

	// Build is every statement that turns the model into what its header
	// says, in order, given what is in the warehouse NOW.
	Build(m model.Model, st State) ([]string, error)
}

type Disposable interface {
	// ExpireSchema is the statement that makes everything in this schema
	// expire. Run by a test right after EnsureSchema, and by nothing else.
	ExpireSchema(schema string) string
}

type Kind string

type Merge struct {
	// On is `t.k = s.k AND t.j = s.j`.
	On string
	// Set is `c = s.c, d = s.d`, the columns that are NOT keys.
	//
	// Empty when every column is a key. A MERGE then has nothing to update
	// and the WHEN MATCHED clause is omitted entirely -- `SET` with no
	// assignment is a syntax error in both warehouses, and "the row is
	// already exactly this row" is not a failure.
	Set string
	// Columns and Values are the INSERT's two halves, in the target's own
	// ordinal order.
	Columns string
	Values  string
}

type State struct {
	// Current is what the relation IS right now.
	Current Kind

	// FullRefresh is `--full-refresh`: build it as if nothing were there.
	FullRefresh bool

	// Columns is the TARGET's column names in ordinal order, from ColumnsOf.
	//
	// Read only when it is going to be used -- an incremental model that is
	// adding to an existing table -- and nil otherwise. A list read on every
	// build would be a query per model for an answer three materialisations
	// out of four never look at.
	Columns []string
}