metadata

type Column struct {
	Name         string    `json:"name" yaml:"name"`
	Position     int64     `json:"position" yaml:"position"`
	PrimaryKey   bool      `json:"primary_key" yaml:"primary_key"`
	BaseType     string    `json:"base_type" yaml:"base_type"`
	ColumnType   string    `json:"column_type" yaml:"column_type"`
	Kind         kind.Kind `json:"kind" yaml:"kind"`
	Nullable     bool      `json:"nullable" yaml:"nullable"`
	DefaultValue string    `json:"default_value,omitempty" yaml:"default_value,omitempty"`
	Comment      string    `json:"comment,omitempty" yaml:"comment,omitempty"`
}

type FKGroup struct {
	// Outgoing are the foreign-key constraints declared on the owning
	// table (constraints whose referencing side is this table).
	Outgoing []*ForeignKey `json:"outgoing,omitempty" yaml:"outgoing,omitempty"`

	// Incoming are the foreign-key constraints declared on other
	// tables whose referenced side is the owning table. Derived
	// cross-table by [LinkForeignKeys] for source-level inspect, or
	// loaded directly by per-table inspect.
	Incoming []*ForeignKey `json:"incoming,omitempty" yaml:"incoming,omitempty"`
}

type ForeignKey struct {
	// Name is the constraint name as reported by the source, such as
	// "fk_film_language". May be empty for sources that don't expose
	// a constraint name (e.g. some SQLite tables).
	Name string `json:"name,omitempty" yaml:"name,omitempty"`

	// Table is the name of the referencing table — the table on which
	// the constraint is declared. This is the bare table name (not
	// fully qualified) and matches the owning [Table.Name].
	Table string `json:"table" yaml:"table"`

	// Columns are the column names on the referencing table, in
	// positional order. For composite keys, the order must match
	// RefColumns.
	Columns []string `json:"columns" yaml:"columns"`

	// RefCatalog is the catalog of the referenced table, if known.
	// Empty when the reference is in the same catalog or the source
	// doesn't expose catalogs.
	RefCatalog string `json:"ref_catalog,omitempty" yaml:"ref_catalog,omitempty"`

	// RefSchema is the schema of the referenced table, if known.
	// Empty when the reference is in the same schema or the source
	// doesn't expose schemas.
	RefSchema string `json:"ref_schema,omitempty" yaml:"ref_schema,omitempty"`

	// RefTable is the name of the referenced table.
	RefTable string `json:"ref_table" yaml:"ref_table"`

	// RefColumns are the column names on the referenced table, in
	// positional order corresponding to Columns.
	RefColumns []string `json:"ref_columns" yaml:"ref_columns"`

	// OnDelete is the referential action on DELETE, such as
	// "NO ACTION", "CASCADE", "SET NULL", or "RESTRICT". Empty
	// when not reported by the source.
	OnDelete string `json:"on_delete,omitempty" yaml:"on_delete,omitempty"`

	// OnUpdate is the referential action on UPDATE. Empty when
	// not reported by the source.
	OnUpdate string `json:"on_update,omitempty" yaml:"on_update,omitempty"`
}

type Index struct {
	// Name is the index name as reported by the source.
	Name string `json:"name" yaml:"name"`

	// Table is the bare name of the owning table.
	Table string `json:"table" yaml:"table"`

	// Columns holds one entry per index key position, in key order. A
	// plain-column key is its column name; a functional or expression
	// key (e.g. lower(b)) is represented by the empty string "". Thus
	// len(Columns) equals the index's true key count, and the position
	// of an expression key is preserved. An index whose key positions
	// are all expressions is omitted from reported metadata entirely.
	// INCLUDE / covering columns are not key positions and do not
	// appear here. See [AllExpressionKeys].
	Columns []string `json:"columns" yaml:"columns"`

	// Unique reports whether the index enforces uniqueness on Columns.
	// True for primary-key and unique-constraint backing indexes as
	// well as for any user-declared UNIQUE INDEX.
	Unique bool `json:"unique" yaml:"unique"`

	// Primary reports whether the index backs this table's primary key.
	Primary bool `json:"primary,omitempty" yaml:"primary,omitempty"`

	// Type is the driver-specific access-method name, such as "BTREE",
	// "HASH", "GIN", or "NONCLUSTERED". Empty when the source doesn't
	// report it.
	Type string `json:"type,omitempty" yaml:"type,omitempty"`
}

type Schema struct {
	// Name is the schema name, such as "public".
	Name string `json:"schema" yaml:"schema"`

	// Catalog is the catalog name, such as "sakila".
	Catalog string `json:"catalog" yaml:"catalog"`

	// Owner is the schema owner, such as "alice".
	Owner string `json:"owner,omitempty" yaml:"owner,omitempty"`
}

type Source struct {
	// Handle is the source handle.
	Handle string `json:"handle" yaml:"handle"`

	// Location is the source location such as a DB connection string,
	// a file path, or a URL.
	Location string `json:"location" yaml:"location"`

	// Name is the base name of the source, e.g. the base filename
	// or DB name etc. For example, "sakila".
	Name string `json:"name" yaml:"name"`

	// FQName is the full name of the data source, typically
	// including catalog/schema etc. For example, "sakila.public"
	FQName string `json:"name_fq" yaml:"name_fq"`

	// Schema is the schema name, for example "public".
	// This may be empty for some sources.
	Schema string `json:"schema,omitempty" yaml:"schema,omitempty"`

	// Catalog is the catalog name, for example "sakila".
	Catalog string `json:"catalog,omitempty" yaml:"catalog,omitempty"`

	// Driver is the source driver type.
	Driver drivertype.Type `json:"driver" yaml:"driver"`

	// DBDriver is the type of the underling DB driver.
	// This is the same value as Driver for SQL database types.
	DBDriver drivertype.Type `json:"db_driver" yaml:"db_driver"`

	// DBProduct is the DB product string, such as "PostgreSQL 9.6.17 on x86_64-pc-linux-gnu".
	DBProduct string `json:"db_product" yaml:"db_product"`

	// DBVersion is the DB version.
	DBVersion string `json:"db_version" yaml:"db_version"`

	// User is the username, if applicable.
	User string `json:"user,omitempty" yaml:"user,omitempty"`

	// Size is the physical size of the source in bytes, e.g. DB file size.
	// A nil value means the size is not reported by the driver, distinct
	// from a non-nil pointer to 0 (a genuinely zero-sized source).
	// Mirrors [Table.Size].
	Size *int64 `json:"size,omitempty" yaml:"size,omitempty"`

	// TableCount is the count of tables (excluding views).
	TableCount int64 `json:"table_count" yaml:"table_count"`

	// ViewCount is the count of views.
	ViewCount int64 `json:"view_count" yaml:"view_count"`

	// Tables is the metadata for each table/view in the source.
	Tables []*Table `json:"tables" yaml:"tables"`

	// DBProperties are name-value pairs from the DB.
	// Typically the value is a scalar such as integer or string, but
	// it can be a nested value such as map or array.
	DBProperties map[string]any `json:"db_properties,omitempty" yaml:"db_properties,omitempty"`

	// SecretsResolved indicates that Location holds resolved literal
	// bytes rather than a placeholder template, mirroring
	// [source.Source.SecretsResolved]. Drivers leave it false; the CLI
	// inspect path sets it from the source so the --expand writer
	// decorator can skip re-expanding an already-resolved location
	// (which would double-unescape "$$"). Never persisted or serialized.
	SecretsResolved bool `json:"-" yaml:"-"`
}

type Table struct {
	// Name is the table name, such as "actor".
	Name string `json:"name" yaml:"name"`

	// FQName is the fully-qualified name, such as "sakila.public.actor"
	FQName string `json:"name_fq,omitempty" yaml:"name_fq,omitempty"`

	// TableType indicates if this is a "table" or "view". The value
	// is driver-independent. See DBTableType for the driver-dependent
	// value.
	TableType string `json:"table_type,omitempty" yaml:"table_type,omitempty"`

	// DBTableType indicates if this is a table or view, etc.
	// The value is driver-dependent, e.g. "BASE TABLE" or "VIEW" for postgres.
	DBTableType string `json:"table_type_db,omitempty" yaml:"table_type_db,omitempty"`

	// RowCount is the number of rows in the table.
	RowCount int64 `json:"row_count" yaml:"row_count"`

	// Size is the physical size of the table in bytes. For a view, this
	// may be nil.
	Size *int64 `json:"size,omitempty" yaml:"size,omitempty"`

	// Comment is the comment for the table. Typically empty.
	Comment string `json:"comment,omitempty" yaml:"comment,omitempty"`

	// Columns holds the metadata for the table's columns.
	Columns []*Column `json:"columns" yaml:"columns"`

	// FK groups the foreign-key relationships for this table: outgoing
	// constraints declared on it, and incoming constraints declared on
	// other tables that reference it. Nil for sources that don't
	// support foreign keys or tables with no FK relationships in
	// either direction.
	FK *FKGroup `json:"fk,omitempty" yaml:"fk,omitempty"`

	// UniqueConstraints are the unique-constraint declarations on this
	// table (UNIQUE in CREATE TABLE, or ALTER TABLE ADD CONSTRAINT ...
	// UNIQUE). Primary keys are *not* repeated here — they are reported
	// via [Column.PrimaryKey] and also appear in [Table.Indexes] as
	// an entry with [Index.Primary]=true. Composite unique constraints
	// are returned with their columns in declaration order.
	UniqueConstraints []*UniqueConstraint `json:"unique_constraints,omitempty" yaml:"unique_constraints,omitempty"`

	// Indexes are the physical indexes that back this table. Use
	// [Index.Unique] / [Index.Primary] to distinguish kinds. Non-unique
	// secondary indexes (e.g. created via CREATE INDEX for performance)
	// always appear here. Driver coverage of implicit constraint-backing
	// indexes varies:
	//
	//   - postgres, mysql, sqlserver, sqlite3: the implicit unique index
	//     that backs each primary key and unique constraint is reported.
	//   - oracle: only user-named indexes are reported (auto-named
	//     SYS_C… indexes from inline PRIMARY KEY / UNIQUE declarations
	//     are filtered out). PK membership is still available via
	//     [Column.PrimaryKey].
	//   - duckdb: only indexes from explicit CREATE INDEX statements are
	//     reported. PK / UNIQUE-backing indexes are not surfaced by the
	//     duckdb_indexes() catalog; PK / unique info is still available
	//     via [Column.PrimaryKey] and [Table.UniqueConstraints].
	Indexes []*Index `json:"indexes,omitempty" yaml:"indexes,omitempty"`
}

type UniqueConstraint struct {
	// Name is the constraint name as reported by the source, such as
	// "address_postal_code_key". May be empty when the source doesn't
	// expose a user-visible constraint name (some SQLite cases).
	Name string `json:"name,omitempty" yaml:"name,omitempty"`

	// Table is the bare name of the owning table (matches the owning
	// [Table.Name]).
	Table string `json:"table" yaml:"table"`

	// Columns are the column names that participate in the constraint,
	// in declaration order.
	Columns []string `json:"columns" yaml:"columns"`
}