introspect

type Options struct {
	// Schema is the Postgres schema to read. Defaults to "public".
	Schema string

	// Module, when set, produces a module registry (schema.NewModule) and
	// strips the module's prefix from every table name it finds, so that a
	// database whose tables are called billing_invoices imports as a module
	// named billing holding a table called invoices.
	//
	// Tables without the prefix are left alone and reported, since a module
	// registry would silently rename them on the way back out.
	Module string

	// Only limits the import to the named tables. Empty reads everything,
	// which is what an import of a database sqlb is taking over wants.
	//
	// A drift gate wants the opposite. An incremental adoption declares a
	// handful of tables while the database holds dozens, and diffing a
	// declaration of five tables against an import of sixty-nine reports the
	// other sixty-four as tables to drop — so the gate has to narrow one side,
	// and this is where it is narrowed (issue #54). Names are storage names,
	// before any module prefix is stripped, because that is what the database
	// calls them.
	//
	// A named table that is not in the database is reported rather than
	// ignored: a typo in this list would otherwise silently shrink what the
	// gate checks, which is the one failure a gate must not have.
	Only []string

	// Exclude drops the named tables from the import. It applies after Only,
	// so the two compose — read this schema except the queue tables — and it
	// is the right shape for the migration-history table every runner keeps,
	// which no declaration will ever describe.
	Exclude []string
}

type Report struct {
	Skipped []Skip

	// Notes records a construct that survived, but not in the shape the
	// database holds it — a decision this package made rather than a gap it
	// left. A foreign key on an import-breaking cycle is the case: it is
	// imported as the enforced ExternalRef a declaration would also be forced
	// to write, which is faithful, but the reader should know which side was
	// chosen.
	//
	// Deliberately not Skipped. Empty and Err are about whether the registry
	// describes the database, and a note does not change that answer — putting
	// one there would fail a round-trip that is in fact clean.
	Notes []string

	// Extensions is every non-plpgsql extension the database has installed.
	//
	// It is here because an extension is *invisible* to this package's normal
	// contract rather than skipped by it. A construct the DSL cannot express
	// gets a Skip and the reader reconciles it; an extension was never read at
	// all, so a clean Report and a clean Diff both claimed everything was
	// represented about a schema that could not be created — the DDL naming
	// uuid_generate_v4() applies only where uuid-ossp already exists.
	//
	// The failure that produced this field surfaced at the furthest possible
	// point from its cause and in the wrong vocabulary: 228 identical "function
	// uuid_generate_v4() does not exist" errors, one per dependent table, with
	// the actual cause — two missing extensions — named nowhere (issue #115).
	//
	// Deliberately not Skipped, for the same reason Notes is not: Empty and Err
	// answer whether the registry describes the *tables*, and every adoption
	// using pgvector would otherwise report a gap it cannot close. Diff still
	// renders no CREATE EXTENSION; this is the list to create first.
	Extensions []string
}

type Skip struct {
	Table  string
	Object string // the constraint, index or column it concerns
	Reason string
	// Def is the definition Postgres reports, so the construct can be carried
	// across by hand without going back to the database to look it up.
	Def string
}