migrations

type Source struct {
	// Name labels the source in logs and errors (e.g. "core", "vector").
	Name string
	// Schema is the Postgres schema the track lives in. Empty means the
	// connection's default schema (resolved via search_path / current_schema),
	// which is what the built-in tracks use. A non-empty value scopes the
	// tracking table and migration objects to that schema: the orchestrator
	// creates it (CREATE SCHEMA IF NOT EXISTS) and sets search_path on the
	// connection. Schema is treated as an untrusted identifier and validated.
	//
	// When Schema is empty (the built-in tracks), the DSN is left untouched:
	// the connection keeps the server's default search_path ("$user", public), so
	// migration objects and the tracking table land in public exactly as before
	// this orchestrator existed. The schema handling below applies only when
	// Schema is set.
	//
	// When Schema is set, search_path is pinned to it alone (pg_catalog is always
	// implicitly searched, so built-in types and functions still resolve). public
	// is NOT on the path, which keeps a schema-scoped track strictly isolated. A
	// migration that needs a shared extension installed in public (e.g. the
	// pgvector "vector" type) must therefore either install/relocate the extension
	// into this schema or schema-qualify the reference; it cannot rely on public.
	//
	// Do not register two sources whose schemas resolve to the same value with the
	// same TrackingTable — e.g. one source with Schema == "" and another naming the
	// connection's current_schema() explicitly. They would share one tracking-table
	// row and one advisory lock and corrupt each other's state. The collision unit
	// is (resolved schema, TrackingTable). validateSources catches collisions on the
	// literal Schema; RunUp additionally resolves "" to current_schema() and rejects
	// collisions that only appear after resolution.
	Schema string
	// TrackingTable is the golang-migrate bookkeeping table for this track.
	TrackingTable string
	// FS holds the embedded migration files.
	FS fs.FS
	// Dir is the subdirectory within FS that holds this track's files.
	Dir string
	// PreCheck, if set, runs before any source is applied. A non-nil error
	// aborts the whole run before any migration executes (fail-fast).
	PreCheck func(url string) error
}