hcl

type ChangeSet struct {
	Databases        []DatabaseChange
	NamedCollections []NamedCollectionChange
}

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

type ColumnChange struct {
	Name string
	Old  ColumnSpec
	New  ColumnSpec
}

type ColumnSpec struct {
	Name string `hcl:"name,label"`
	Type string `hcl:"type"`

	// Nullable wraps Type in Nullable(...) at SQL gen time. Combining
	// Nullable = true with a Type that already starts with "Nullable("
	// is rejected, matching ClickHouse's own behavior.
	Nullable bool `hcl:"nullable,optional"`

	// Default / Materialized / Ephemeral / Alias are mutually exclusive
	// default-value expressions, matching ClickHouse's
	// DEFAULT|MATERIALIZED|EPHEMERAL|ALIAS clauses. Ephemeral can be the
	// empty string, meaning a bare EPHEMERAL with no expression.
	Default      *string `hcl:"default,optional"`
	Materialized *string `hcl:"materialized,optional"`
	Ephemeral    *string `hcl:"ephemeral,optional"`
	Alias        *string `hcl:"alias,optional"`

	Comment *string `hcl:"comment,optional"`
	Codec   *string `hcl:"codec,optional"`
	TTL     *string `hcl:"ttl,optional"`

	// RenamedFrom declares that this column previously existed under another
	// name. The diff engine uses it to emit RENAME COLUMN instead of DROP +
	// ADD. Tagged diff:"-" because it's transient metadata, not part of the
	// schema being compared.
	RenamedFrom *string `hcl:"renamed_from,optional" diff:"-"`

	// After / First position a patch_table column add: the new column is
	// inserted immediately after the named column (or at the front) instead
	// of appended, so an env's mid-table extras can interleave without
	// redeclaring the table (#158). Patch-only — a declared table or MV
	// column carrying either is a resolve error, and modify_column rejects
	// them (repositioning base columns is genuine drift). Consumed and
	// cleared at patch application; the diff engine may also populate these
	// fields on its private AddColumns copies so SQL generation preserves the
	// target order. Tagged diff:"-" as transient placement metadata, like
	// RenamedFrom.
	After *string `hcl:"after,optional" diff:"-"`
	First bool    `hcl:"first,optional" diff:"-"`
}

type CompareSummary struct {
	TablesAdded             int `json:"tables_added"`
	TablesDropped           int `json:"tables_dropped"`
	TablesAltered           int `json:"tables_altered"`
	MVsAdded                int `json:"mvs_added"`
	MVsDropped              int `json:"mvs_dropped"`
	MVsAltered              int `json:"mvs_altered"`
	ViewsAdded              int `json:"views_added"`
	ViewsDropped            int `json:"views_dropped"`
	ViewsAltered            int `json:"views_altered"`
	DictsAdded              int `json:"dicts_added"`
	DictsDropped            int `json:"dicts_dropped"`
	DictsAltered            int `json:"dicts_altered"`
	RawsAdded               int `json:"raws_added"`
	RawsDropped             int `json:"raws_dropped"`
	RawsAltered             int `json:"raws_altered"`
	NamedCollectionsChanged int `json:"named_collections_changed"`
}

type ConstraintChange struct {
	Name string
	Old  ConstraintSpec
	New  ConstraintSpec
}

type ConstraintSpec struct {
	Name   string  `hcl:"name,label"`
	Check  *string `hcl:"check,optional"`
	Assume *string `hcl:"assume,optional"`
}

type DatabaseChange struct {
	Database    string
	AddTables   []TableSpec // emitted via CREATE TABLE
	DropTables  []TableSpec // emitted via DROP TABLE
	AlterTables []TableDiff

	AddMaterializedViews   []MaterializedViewSpec // emitted via CREATE MATERIALIZED VIEW
	DropMaterializedViews  []string               // emitted via DROP VIEW
	AlterMaterializedViews []MaterializedViewDiff

	AddDictionaries   []DictionarySpec // emitted via CREATE OR REPLACE DICTIONARY
	DropDictionaries  []string         // emitted via DROP DICTIONARY
	AlterDictionaries []DictionaryDiff

	AddViews   []ViewSpec // emitted via CREATE VIEW
	DropViews  []string   // emitted via DROP VIEW
	AlterViews []ViewDiff

	AddRaws   []RawSpec   // emitted verbatim via the stored CREATE DDL
	DropRaws  []RawSpec   // emitted via a kind-mapped DROP
	AlterRaws []RawChange // emitted as DROP + CREATE (recreate)
}

type DatabaseSpec struct {
	Name string `hcl:"name,label"`

	// Cluster is the default ON CLUSTER target for every table declared in
	// this database. Tables can override via TableSpec.Cluster. Inheritance
	// happens during resolution; after Resolve, every TableSpec.Cluster
	// reflects the effective value.
	Cluster *string `hcl:"cluster,optional"`

	Tables  []TableSpec      `hcl:"table,block"`
	Patches []PatchTableSpec `hcl:"patch_table,block" diff:"-"`

	// ViewPatches and DictionaryPatches are the patch_view /
	// patch_dictionary counterparts of Patches. Like table patches they
	// accumulate across layers and are consumed during resolution.
	MaterializedViewPatches []PatchMaterializedViewSpec `hcl:"patch_materialized_view,block" diff:"-"`
	ViewPatches             []PatchViewSpec             `hcl:"patch_view,block"              diff:"-"`
	DictionaryPatches       []PatchDictionarySpec       `hcl:"patch_dictionary,block"        diff:"-"`

	// MaterializedViews are a sibling collection to Tables, not a flavored
	// TableSpec. They may `extend` an `abstract = true` table to inherit
	// its column list (and optionally cluster/comment).
	MaterializedViews []MaterializedViewSpec `hcl:"materialized_view,block"`

	// Dictionaries are a third sibling collection. Like MVs, they do not
	// participate in the table inheritance system.
	Dictionaries []DictionarySpec `hcl:"dictionary,block"`

	// Views are plain (non-materialized) views. Like MVs and dictionaries
	// they live as a sibling collection and do not participate in the
	// table inheritance system.
	Views []ViewSpec `hcl:"view,block"`

	// Raws are escape-hatch objects whose CREATE DDL could not be parsed
	// or expressed in this schema language. They are stored verbatim,
	// round-tripped unchanged, and recreated (DROP+CREATE) on change.
	Raws []RawSpec `hcl:"raw,block"`
}

type Declaration struct {
	ObjectType string // KindTable, KindMaterializedView, KindView, KindDictionary, KindRaw, KindNamedCollection
	Database   string // empty for named collections (cluster-scoped)
	Name       string
	File       string
	Line       int

	Abstract bool
	Override bool
	Patch    bool   // declared via patch_table (strictly additive)
	Extends  string // the extend = "<parent>" attribute, when present
	RawKind  string // raw blocks only: the kind label
}

type DeclaredColumn struct {
	Name string
	Type string
}

type Dependency struct {
	From ObjectRef // the dependent object (a materialized view or Distributed table)
	To   ObjectRef // the object it requires
	Kind string    // one of the Dep* constants

	// Cluster is the ClickHouse cluster the remote is expected on. It is set
	// only for DepDistributedRemote (from EngineDistributed.ClusterName) and
	// is the discriminator for cross-cluster resolution: the remote database
	// is almost always "posthog" on every cluster. Empty for all other kinds.
	Cluster string
}

type DictionaryAttribute struct {
	Name         string  `hcl:"name,label"`
	Type         string  `hcl:"type"`
	Default      *string `hcl:"default,optional"`
	Expression   *string `hcl:"expression,optional"`
	Hierarchical bool    `hcl:"hierarchical,optional"`
	Injective    bool    `hcl:"injective,optional"`
	IsObjectID   bool    `hcl:"is_object_id,optional"`
}

type DictionaryDiff struct {
	Name    string
	Changed []string

	// Old is the source spec. Dictionary reconciliation rewrites the whole
	// object, so sqlgen needs the old source as well as the target to detect a
	// credential that exists on the live object but was redacted to [HIDDEN].
	// Without it, a target that omits the credential looks safe even though
	// CREATE OR REPLACE would silently remove the unknown live value (#178).
	Old DictionarySpec

	// New is the target spec. The CREATE OR REPLACE DICTIONARY that
	// reconciles the change is rendered from it.
	New DictionarySpec

	// SkippedRedactedSecrets names source fields (the DDL argument name, e.g.
	// "password") whose comparison was suppressed because one side holds the
	// RedactedValue marker and the other a real value. hclexp cannot tell
	// whether they differ, so it says so rather than guessing. Mirrors
	// NamedCollectionChange.SkippedRedactedParams.
	SkippedRedactedSecrets []string
}

type DictionaryLayout interface{ Kind() string }

type DictionaryLayoutSpec struct {
	Kind string   `hcl:"kind,label" diff:"-"`
	Body hcl.Body `hcl:",remain"    diff:"-"`

	Decoded DictionaryLayout
}

type DictionaryLifetime struct {
	Min *int64 `hcl:"min,optional"`
	Max *int64 `hcl:"max,optional"`
}

type DictionaryRange struct {
	Min string `hcl:"min"`
	Max string `hcl:"max"`
}

type DictionarySource interface{ Kind() string }

type DictionarySourceSpec struct {
	Kind string   `hcl:"kind,label" diff:"-"`
	Body hcl.Body `hcl:",remain"    diff:"-"`

	Decoded DictionarySource
}

type DictionarySpec struct {
	Name       string                `hcl:"name,label"`
	Override   bool                  `hcl:"override,optional" diff:"-"`
	PrimaryKey []string              `hcl:"primary_key"`
	Attributes []DictionaryAttribute `hcl:"attribute,block"`
	Source     *DictionarySourceSpec `hcl:"source,block"`
	Layout     *DictionaryLayoutSpec `hcl:"layout,block"`
	Lifetime   *DictionaryLifetime   `hcl:"lifetime,block"`
	Range      *DictionaryRange      `hcl:"range,block"`
	Settings   map[string]string     `hcl:"settings,optional"`
	Cluster    *string               `hcl:"cluster,optional"`
	Comment    *string               `hcl:"comment,optional"`
}

type DiffJSON struct {
	Objects    []ObjectComparison `json:"objects"`
	Operations []JSONOperation    `json:"operations"`
	Unsafe     []JSONUnsafe       `json:"unsafe,omitempty"`
	Summary    CompareSummary     `json:"summary"`
}

type DiffOptions struct {
	IgnoreColumnOrder bool
}

type DriftGroup struct {
	Key       string      `json:"key"`
	Reference string      `json:"reference"`
	Nodes     int         `json:"nodes"`
	Drifters  []DriftNode `json:"drifters"`
}

type DriftJSON struct {
	Groups  []DriftGroup    `json:"groups"`
	Summary DriftRunSummary `json:"summary"`
}

type DriftNode struct {
	Node    string             `json:"node"`
	File    string             `json:"file"`
	Macros  map[string]string  `json:"macros,omitempty"`
	Objects []ObjectComparison `json:"objects"`
	Summary CompareSummary     `json:"summary"`
}

type DriftRunSummary struct {
	Nodes           int `json:"nodes"`
	Groups          int `json:"groups"`
	GroupsWithDrift int `json:"groups_with_drift"`
	DriftingNodes   int `json:"drifting_nodes"`
}

type DuplicateGroup struct {
	Database     string
	Name         string
	Declarations []Declaration // every site for the name, legitimate ones included
}

type Engine interface {
	Kind() string
}

type EngineAggregatingMergeTree struct{}

type EngineBuffer struct {
	Database  string `hcl:"database"`
	Table     string `hcl:"table"`
	NumLayers int64  `hcl:"num_layers"`
	MinTime   int64  `hcl:"min_time"`
	MaxTime   int64  `hcl:"max_time"`
	MinRows   int64  `hcl:"min_rows"`
	MaxRows   int64  `hcl:"max_rows"`
	MinBytes  int64  `hcl:"min_bytes"`
	MaxBytes  int64  `hcl:"max_bytes"`

	FlushTime  *int64 `hcl:"flush_time,optional"`
	FlushRows  *int64 `hcl:"flush_rows,optional"`
	FlushBytes *int64 `hcl:"flush_bytes,optional"`
}

type EngineChange struct {
	Old Engine
	New Engine
}

type EngineCollapsingMergeTree struct {
	SignColumn string `hcl:"sign_column"`
}

type EngineDistributed struct {
	ClusterName    string  `hcl:"cluster_name"`
	RemoteDatabase string  `hcl:"remote_database"`
	RemoteTable    string  `hcl:"remote_table"`
	ShardingKey    *string `hcl:"sharding_key,optional"`
	PolicyName     *string `hcl:"policy_name,optional"`
}

type EngineJoin struct {
	Strictness string   `hcl:"strictness"` // ANY | ALL | SEMI | ANTI
	JoinType   string   `hcl:"type"`       // LEFT | INNER | RIGHT | FULL
	Keys       []string `hcl:"keys"`
}

type EngineKafka struct {
	// Collection is the named-collection reference. The remaining fields are
	// optional per-table overrides when Collection is set.
	Collection *string `hcl:"collection,optional"`

	// BrokerList, TopicList, GroupName, and Format are required only when
	// Collection is nil.
	BrokerList *string `hcl:"broker_list,optional"`
	TopicList  *string `hcl:"topic_list,optional"`
	GroupName  *string `hcl:"group_name,optional"`
	Format     *string `hcl:"format,optional"`

	// Optional auth.
	SecurityProtocol *string `hcl:"security_protocol,optional"`
	SaslMechanism    *string `hcl:"sasl_mechanism,optional"`
	SaslUsername     *string `hcl:"sasl_username,optional"`
	SaslPassword     *string `hcl:"sasl_password,optional"`

	// Optional numeric tuning.
	NumConsumers         *int64 `hcl:"num_consumers,optional"`
	MaxBlockSize         *int64 `hcl:"max_block_size,optional"`
	SkipBrokenMessages   *int64 `hcl:"skip_broken_messages,optional"`
	PollTimeoutMs        *int64 `hcl:"poll_timeout_ms,optional"`
	PollMaxBatchSize     *int64 `hcl:"poll_max_batch_size,optional"`
	FlushIntervalMs      *int64 `hcl:"flush_interval_ms,optional"`
	ConsumerRescheduleMs *int64 `hcl:"consumer_reschedule_ms,optional"`
	MaxRowsPerMessage    *int64 `hcl:"max_rows_per_message,optional"`
	CompressionLevel     *int64 `hcl:"compression_level,optional"`

	// Optional booleans (introspected as 0/1, presented as bool in HCL).
	CommitEveryBatch  *bool `hcl:"commit_every_batch,optional"`
	ThreadPerConsumer *bool `hcl:"thread_per_consumer,optional"`
	CommitOnSelect    *bool `hcl:"commit_on_select,optional"`

	// Optional strings.
	ClientID             *string `hcl:"client_id,optional"`
	Schema               *string `hcl:"schema,optional"`
	HandleErrorMode      *string `hcl:"handle_error_mode,optional"`
	CompressionCodec     *string `hcl:"compression_codec,optional"`
	AutodetectClientRack *string `hcl:"autodetect_client_rack,optional"`

	// Extra is the escape valve for kafka_* settings ClickHouse adds in
	// versions we don't yet model. Keys are passed through verbatim and
	// MUST include the `kafka_` prefix (the typed fields above strip it).
	Extra map[string]string `hcl:"extra,optional"`
}

type EngineLog struct{}

type EngineMemory struct{}

type EngineMerge struct {
	DBRegex    string `hcl:"db_regex"`
	TableRegex string `hcl:"table_regex"`
}

type EngineMergeTree struct{}

type EngineNull struct{}

type EngineReplacingMergeTree struct {
	VersionColumn *string `hcl:"version_column,optional"`
	// IsDeletedColumn is ClickHouse's optional is_deleted parameter (1 = the
	// row is a delete marker). ClickHouse only accepts it together with ver,
	// so version_column must be set too (enforced at resolve time).
	IsDeletedColumn *string `hcl:"is_deleted_column,optional"`
}

type EngineReplicatedAggregatingMergeTree struct {
	ZooPath     string `hcl:"zoo_path"`
	ReplicaName string `hcl:"replica_name"`
}

type EngineReplicatedCollapsingMergeTree struct {
	ZooPath     string `hcl:"zoo_path"`
	ReplicaName string `hcl:"replica_name"`
	SignColumn  string `hcl:"sign_column"`
}

type EngineReplicatedMergeTree struct {
	ZooPath     string `hcl:"zoo_path"`
	ReplicaName string `hcl:"replica_name"`
}

type EngineReplicatedReplacingMergeTree struct {
	ZooPath         string  `hcl:"zoo_path"`
	ReplicaName     string  `hcl:"replica_name"`
	VersionColumn   *string `hcl:"version_column,optional"`
	IsDeletedColumn *string `hcl:"is_deleted_column,optional"`
}

type EngineReplicatedSummingMergeTree struct {
	ZooPath     string   `hcl:"zoo_path"`
	ReplicaName string   `hcl:"replica_name"`
	SumColumns  []string `hcl:"sum_columns,optional"`
}

type EngineSharedAggregatingMergeTree struct {
	ZooPath     string `hcl:"zoo_path"`
	ReplicaName string `hcl:"replica_name"`
}

type EngineSharedCollapsingMergeTree struct {
	ZooPath     string `hcl:"zoo_path"`
	ReplicaName string `hcl:"replica_name"`
	SignColumn  string `hcl:"sign_column"`
}

type EngineSharedMergeTree struct {
	ZooPath     string `hcl:"zoo_path"`
	ReplicaName string `hcl:"replica_name"`
}

type EngineSharedReplacingMergeTree struct {
	ZooPath         string  `hcl:"zoo_path"`
	ReplicaName     string  `hcl:"replica_name"`
	VersionColumn   *string `hcl:"version_column,optional"`
	IsDeletedColumn *string `hcl:"is_deleted_column,optional"`
}

type EngineSharedSummingMergeTree struct {
	ZooPath     string   `hcl:"zoo_path"`
	ReplicaName string   `hcl:"replica_name"`
	SumColumns  []string `hcl:"sum_columns,optional"`
}

type EngineSpec struct {
	Kind string   `hcl:"kind,label"   diff:"-"`
	Body hcl.Body `hcl:",remain"      diff:"-"`

	// Decoded is populated post-parse via DecodeEngine; gohcl ignores it
	// because it has no hcl tag.
	Decoded Engine
}

type EngineSummingMergeTree struct {
	SumColumns []string `hcl:"sum_columns,optional"`
}

type EngineTimeSeries struct {
	// Settings declared via `engine "time_series" { settings = {...} }`.
	// Free-form for forward compatibility. Only two are ALTER-able
	// (id_generator, filter_by_min_time_and_max_time); the rest are
	// baked into the CREATE.
	Settings map[string]string `hcl:"settings,optional"`

	// TagsToColumns shapes the inner tags-target table by promoting
	// specific label keys into their own columns. CH treats this as a
	// setting at the SQL level; promoted here for HCL clarity. sqlgen
	// folds it back into the SETTINGS clause at emit time.
	TagsToColumns map[string]string `hcl:"tags_to_columns,optional"`

	// Target sub-blocks. Nil = CH default applies (auto-generate the
	// inner target for that kind).
	Samples *TimeSeriesTarget `hcl:"samples,block"`
	Tags    *TimeSeriesTarget `hcl:"tags,block"`
	Metrics *TimeSeriesTarget `hcl:"metrics,block"`
	// RecentSamples is the RECENT SAMPLES target (ClickHouse 26.8+): a
	// short-lived copy of the newest samples, on by default
	// (recent_samples_ttl_seconds).
	RecentSamples *TimeSeriesTarget `hcl:"recent_samples,block"`

	// KeywordHint preserves whether the samples target's source SQL used
	// SAMPLES or DATA. Populated by the introspector; sqlgen reads it to
	// round-trip the same word. HCL authors never set this — no hcl tag
	// so gohcl ignores it during decode.
	KeywordHint string `diff:"-"`
}

type EngineWithDynamicVirtuals interface {
	Engine
	DynamicVirtuals(r TableResolver) []DeclaredColumn
}

type EngineWithVirtuals interface {
	Engine
	Virtuals() []DeclaredColumn
}

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

type FieldChange struct {
	Field  string `json:"field"`
	Change string `json:"change"` // add | drop | modify | rename
	Old    string `json:"old,omitempty"`
	New    string `json:"new,omitempty"`
}

type GeneratedSQL struct {
	Statements []string
	Ops        []Operation
	Unsafe     []UnsafeChange
}

type IndexSpec struct {
	Name        string `hcl:"name,label"`
	Expr        string `hcl:"expr"`
	Type        string `hcl:"type"`
	Granularity int    `hcl:"granularity,optional"`

	// After / First position a patch_table index add, exactly like the
	// column placement fields (#158/#160): patch-only, consumed and
	// cleared at application, so the composed table renders identically
	// to a flat declaration in that order. A declared table index
	// carrying either is a resolve error.
	After *string `hcl:"after,optional" diff:"-"`
	First bool    `hcl:"first,optional" diff:"-"`
}

type JSONOperation struct {
	Order        int    `json:"order"`
	Kind         string `json:"kind"`        // CREATE | ALTER | DROP | RENAME
	ObjectType   string `json:"object_type"` // table | materialized_view | view | dictionary | named_collection | raw
	Database     string `json:"database"`    // empty for named collections
	Object       string `json:"object"`
	Engine       string `json:"engine"`     // ClickHouse engine family, tables only (e.g. ReplicatedMergeTree)
	Replicated   bool   `json:"replicated"` // true when the engine family is a Replicated* variant
	SQL          string `json:"sql"`        // statement without trailing ';'
	Manual       bool   `json:"manual"`     // operator-run only (e.g. MATERIALIZE INDEX); executors must skip it
	Unsafe       bool   `json:"unsafe"`     // this object has a change that can't be applied in place
	UnsafeReason string `json:"unsafe_reason"`
}

type JSONUnsafe struct {
	Database string `json:"database"`
	Object   string `json:"object"`
	Reason   string `json:"reason"`
}

type LayoutCache struct {
	SizeInCells int64 `hcl:"size_in_cells"`
}

type LayoutComplexKeyCache struct {
	SizeInCells int64 `hcl:"size_in_cells"`
}

type LayoutComplexKeyDirect struct{}

type LayoutComplexKeyHashed struct {
	// Preallocate is accepted by ClickHouse for backwards compatibility
	// but no longer documented; kept so old DDL introspects faithfully.
	Preallocate           *int64   `hcl:"preallocate,optional"`
	Shards                *int64   `hcl:"shards,optional"`
	ShardLoadQueueBacklog *int64   `hcl:"shard_load_queue_backlog,optional"`
	MaxLoadFactor         *float64 `hcl:"max_load_factor,optional"`
}

type LayoutComplexKeyHashedArray struct {
	Shards *int64 `hcl:"shards,optional"`
}

type LayoutComplexKeyRangeHashed struct {
	RangeLookupStrategy *string `hcl:"range_lookup_strategy,optional"`
}

type LayoutComplexKeySparseHashed struct {
	Shards                *int64   `hcl:"shards,optional"`
	ShardLoadQueueBacklog *int64   `hcl:"shard_load_queue_backlog,optional"`
	MaxLoadFactor         *float64 `hcl:"max_load_factor,optional"`
}

type LayoutDirect struct{}

type LayoutFlat struct {
	InitialArraySize *int64 `hcl:"initial_array_size,optional"`
	MaxArraySize     *int64 `hcl:"max_array_size,optional"`
}

type LayoutHashed struct {
	Shards                *int64   `hcl:"shards,optional"`
	ShardLoadQueueBacklog *int64   `hcl:"shard_load_queue_backlog,optional"`
	MaxLoadFactor         *float64 `hcl:"max_load_factor,optional"`
}

type LayoutHashedArray struct {
	Shards *int64 `hcl:"shards,optional"`
}

type LayoutIPTrie struct {
	AccessToKeyFromAttributes *bool `hcl:"access_to_key_from_attributes,optional"`
}

type LayoutRangeHashed struct {
	RangeLookupStrategy *string `hcl:"range_lookup_strategy,optional"`
}

type LayoutRegexpTree struct{}

type LayoutSparseHashed struct {
	Shards                *int64   `hcl:"shards,optional"`
	ShardLoadQueueBacklog *int64   `hcl:"shard_load_queue_backlog,optional"`
	MaxLoadFactor         *float64 `hcl:"max_load_factor,optional"`
}

type MaterializedViewDiff struct {
	Name        string
	QueryChange *StringChange // the AS SELECT body changed
	Recreate    bool          // the change cannot be applied with MODIFY QUERY

	// Detail fields used by renderers. ColumnsChanged can accompany a safe
	// QueryChange when the desired output is a compatible additive projection.
	ToTableChange *StringChange

	// ColumnOrderChange is populated when the column names and definitions are
	// identical and declaration order is the only column difference. The view
	// still requires recreation; this field makes that reason diagnosable.
	ColumnOrderChange *OrderByChange
	ColumnsChanged    bool
}

type MaterializedViewSpec struct {
	Name string `hcl:"name,label"`

	// Inheritance fields. Consumed during resolution; not part of the
	// schema for diff purposes. Extend names an abstract table whose
	// columns (and optionally cluster/comment) are merged into this MV.
	// Abstract MVs are dropped before diff, like abstract tables.
	Extend   *string `hcl:"extend,optional"   diff:"-"`
	Abstract bool    `hcl:"abstract,optional" diff:"-"`
	Override bool    `hcl:"override,optional" diff:"-"`

	ToTable string       `hcl:"to_table,optional"` // TO <db.>table target (required when not abstract)
	Columns []ColumnSpec `hcl:"column,block"`      // explicit column list (may be empty; merged with parent on extend)
	Query   string       `hcl:"query,optional"`    // the AS SELECT ... body (required when not abstract)
	Cluster *string      `hcl:"cluster,optional"`  // ON CLUSTER
	Comment *string      `hcl:"comment,optional"`
}

type NamedCollectionChange struct {
	Name string

	// Add is set for fresh adds AND for the create-half of a recreate
	// (so the create has the full target spec).
	Add *NamedCollectionSpec

	// Drop is true for pure drops AND for the drop-half of a recreate.
	Drop bool

	// Recreate is true when ON CLUSTER changed; sqlgen emits
	// DROP then CREATE adjacently.
	Recreate bool

	// Surgical (non-recreate) changes:
	SetParams     []NamedCollectionParam
	DeleteParams  []string
	CommentChange *StringChange

	// SkippedRedactedParams lists param keys whose diff was suppressed
	// because the value is the redacted "[HIDDEN]" placeholder on one side
	// while the other side holds a real value, differs in flags, or lacks
	// the param entirely. Identically-redacted params (hidden on both
	// sides, flags equal) are not a difference and are not listed. The CLI
	// surfaces these so operators know hclexp couldn't verify equality.
	SkippedRedactedParams []string

	// Error is non-empty when the diff describes an unsupported transition.
	// sqlgen emits no DDL; the CLI surfaces it.
	Error string
}

type NamedCollectionParam struct {
	Key         string `hcl:"name,label"`
	Value       string `hcl:"value"`
	Overridable *bool  `hcl:"overridable,optional"`
}

type NamedCollectionSpec struct {
	Name     string                 `hcl:"name,label"`
	External bool                   `hcl:"external,optional"`
	Override bool                   `hcl:"override,optional" diff:"-"`
	Cluster  *string                `hcl:"cluster,optional"`
	Comment  *string                `hcl:"comment,optional"`
	Params   []NamedCollectionParam `hcl:"param,block"`
}

type NodeSpec struct {
	Name   string            `hcl:"name,label"`
	Macros map[string]string `hcl:"macros,optional"`
}

type ObjectComparison struct {
	Database   string `json:"database"` // empty for named collections
	Object     string `json:"object"`
	ObjectType string `json:"object_type"` // table | materialized_view | view | dictionary | named_collection | raw

	// RawKind is a raw{} block's inner object kind (table | view |
	// dictionary | materialized_view). Only a raw table holds rows on disk,
	// so its DROP+CREATE recreate is the destructive one — the kind is what
	// tells a consumer that apart.
	RawKind string `json:"raw_kind,omitempty"`

	Status       string          `json:"status"`            // added | dropped | altered
	Changes      []FieldChange   `json:"changes,omitempty"` // altered only
	Operations   []JSONOperation `json:"operations"`        // the DDL that reconciles this object; may be empty (unsafe-only changes)
	Unsafe       bool            `json:"unsafe"`
	UnsafeReason string          `json:"unsafe_reason,omitempty"`
	Error        string          `json:"error,omitempty"` // unsupported transition
}

type ObjectRef struct {
	Database string
	Name     string
}

type Operation struct {
	Kind       string // OpCreate | OpAlter | OpDrop | OpRename
	ObjectType string // table | materialized_view | view | dictionary | named_collection | raw
	Database   string // empty for named collections (cluster-scoped)
	Object     string
	SQL        string // the statement, without a trailing ';'
	Manual     bool   // operator-run only (heavy mutation, e.g. MATERIALIZE INDEX); never execute automatically
}

type OrderByChange struct {
	Old []string
	New []string
}

type PatchColumnSpec struct {
	Name string `hcl:"name,label"`

	Type     *string `hcl:"type,optional"`
	Nullable *bool   `hcl:"nullable,optional"`

	Default      *string `hcl:"default,optional"`
	Materialized *string `hcl:"materialized,optional"`
	Ephemeral    *string `hcl:"ephemeral,optional"`
	Alias        *string `hcl:"alias,optional"`

	Comment *string `hcl:"comment,optional"`
	Codec   *string `hcl:"codec,optional"`
	TTL     *string `hcl:"ttl,optional"`
}

type PatchDictionarySpec struct {
	Name     string                `hcl:"name,label"`
	Source   *DictionarySourceSpec `hcl:"source,block"`
	Layout   *DictionaryLayoutSpec `hcl:"layout,block"`
	Lifetime *DictionaryLifetime   `hcl:"lifetime,block"`
	Settings map[string]string     `hcl:"settings,optional"`
}

type PatchMaterializedViewSpec struct {
	Name          string       `hcl:"name,label"`
	ToTable       *string      `hcl:"to_table,optional"`
	Columns       []ColumnSpec `hcl:"column,block"`
	ModifyColumns []ColumnSpec `hcl:"modify_column,block"`
	DropColumns   []string     `hcl:"drop_columns,optional"`
	Query         *string      `hcl:"query,optional"`
}

type PatchTableSpec struct {
	Name          string            `hcl:"name,label"`
	Columns       []ColumnSpec      `hcl:"column,block"`
	ModifyColumns []ColumnSpec      `hcl:"modify_column,block"`
	DropColumns   []string          `hcl:"drop_columns,optional"`
	Indexes       []IndexSpec       `hcl:"index,block"`
	DropIndexes   []string          `hcl:"drop_indexes,optional"`
	Projections   []ProjectionSpec  `hcl:"projection,block"`
	OrderBy       []string          `hcl:"order_by,optional"`
	PartitionBy   *string           `hcl:"partition_by,optional"`
	SampleBy      *string           `hcl:"sample_by,optional"`
	TTL           *string           `hcl:"ttl,optional"`
	Settings      map[string]string `hcl:"settings,optional"`
	Engine        *EngineSpec       `hcl:"engine,block"`
}

type PatchViewSpec struct {
	Name    string  `hcl:"name,label"`
	Query   *string `hcl:"query,optional"`
	Comment *string `hcl:"comment,optional"`
}

type PlanOperation struct {
	Order        int      `json:"order"`
	Kind         string   `json:"kind"`
	ObjectType   string   `json:"object_type"`
	Database     string   `json:"database"`
	Object       string   `json:"object"`
	Engine       string   `json:"engine"`
	Replicated   bool     `json:"replicated"`
	SQL          string   `json:"sql"`
	Manual       bool     `json:"manual"` // operator-run only (e.g. MATERIALIZE INDEX); executors must skip it
	Roles        []string `json:"roles"`
	Unsafe       bool     `json:"unsafe"`
	UnsafeReason string   `json:"unsafe_reason"`
}

type PlanResult struct {
	Operations []PlanOperation  `json:"operations"`
	Unsafe     []JSONUnsafe     `json:"unsafe,omitempty"`
	Roles      []RoleComparison `json:"roles"`
}

type ProjectionSpec struct {
	Name     string            `hcl:"name,label"`
	Query    string            `hcl:"query"`
	Settings map[string]string `hcl:"settings,optional"`
}

type RawChange struct {
	Kind   string
	Name   string
	OldSQL string
	NewSQL string
}

type RawSpec struct {
	Kind     string `hcl:"kind,label"` // table | materialized_view | view | dictionary
	Name     string `hcl:"name,label"`
	Override bool   `hcl:"override,optional" diff:"-"`
	SQL      string `hcl:"sql"`
}

type RenameColumn struct {
	Old string
	New string
}

type RoleComparison struct {
	Role    string             `json:"role"`
	Objects []ObjectComparison `json:"objects"`
	Summary CompareSummary     `json:"summary"`
}

type RoleDiff struct {
	Role    string
	Desired *Schema
	Current *Schema
}

type Schema struct {
	Databases        []DatabaseSpec
	NamedCollections []NamedCollectionSpec

	// Nodes carries per-node identity captured at introspection time:
	// the node hostname (label) and its ClickHouse macros (shard,
	// replica, hostClusterRole, hostClusterType, …). It is metadata only
	// — Diff() ignores it — and exists so multi-node drift analysis can
	// group nodes by their authoritative macros rather than by filename.
	Nodes []NodeSpec
}

type SettingChange struct {
	Key      string
	OldValue string
	NewValue string
}

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

type SourceClickHouse struct {
	Collection      *string `hcl:"collection,optional"`
	Host            *string `hcl:"host,optional"`
	Port            *int64  `hcl:"port,optional"`
	User            *string `hcl:"user,optional"`
	Password        *string `hcl:"password,optional"`
	DB              *string `hcl:"db,optional"`
	Table           *string `hcl:"table,optional"`
	Query           *string `hcl:"query,optional"`
	InvalidateQuery *string `hcl:"invalidate_query,optional"`
	UpdateField     *string `hcl:"update_field,optional"`
	UpdateLag       *int64  `hcl:"update_lag,optional"`
}

type SourceExecutable struct {
	Command     string `hcl:"command"`
	Format      string `hcl:"format"`
	ImplicitKey *bool  `hcl:"implicit_key,optional"`
}

type SourceFile struct {
	Path   string `hcl:"path"`
	Format string `hcl:"format"`
}

type SourceHTTP struct {
	Collection          *string `hcl:"collection,optional"`
	URL                 string  `hcl:"url,optional"`
	Format              string  `hcl:"format,optional"`
	CredentialsUser     *string `hcl:"credentials_user,optional"`
	CredentialsPassword *string `hcl:"credentials_password,optional"`
}

type SourceMySQL struct {
	Collection      *string `hcl:"collection,optional"`
	Host            *string `hcl:"host,optional"`
	Port            *int64  `hcl:"port,optional"`
	User            *string `hcl:"user,optional"`
	Password        *string `hcl:"password,optional"`
	DB              *string `hcl:"db,optional"`
	Table           *string `hcl:"table,optional"`
	Query           *string `hcl:"query,optional"`
	InvalidateQuery *string `hcl:"invalidate_query,optional"`
	UpdateField     *string `hcl:"update_field,optional"`
	UpdateLag       *int64  `hcl:"update_lag,optional"`
}

type SourceNull struct{}

type SourcePostgreSQL struct {
	Collection      *string `hcl:"collection,optional"`
	Host            *string `hcl:"host,optional"`
	Port            *int64  `hcl:"port,optional"`
	User            *string `hcl:"user,optional"`
	Password        *string `hcl:"password,optional"`
	DB              *string `hcl:"db,optional"`
	Table           *string `hcl:"table,optional"`
	Query           *string `hcl:"query,optional"`
	InvalidateQuery *string `hcl:"invalidate_query,optional"`
	UpdateField     *string `hcl:"update_field,optional"`
	UpdateLag       *int64  `hcl:"update_lag,optional"`
}

type StringChange struct {
	Old *string
	New *string
}

type TableDiff struct {
	Table string

	RenameColumns []RenameColumn
	AddColumns    []ColumnSpec
	DropColumns   []string
	ModifyColumns []ColumnChange

	AddIndexes  []IndexSpec
	DropIndexes []string

	// Projections keyed by name; a modify is emitted as DROP + ADD (there
	// is no ALTER MODIFY PROJECTION). Adding one to an existing table also
	// generates a manual MATERIALIZE PROJECTION.
	AddProjections  []ProjectionSpec
	DropProjections []string

	EngineChange *EngineChange
	// ColumnOrderChange records a reorder among columns present on both
	// sides. New columns carry FIRST/AFTER on AddColumns instead.
	ColumnOrderChange *OrderByChange
	OrderByChange     *OrderByChange
	PartitionByChange *StringChange
	SampleByChange    *StringChange
	TTLChange         *StringChange

	SettingsAdded   map[string]string
	SettingsRemoved []string
	SettingsChanged []SettingChange

	// Constraints keyed by name; a modify is emitted as DROP + ADD. All
	// in-place ALTER-able.
	AddConstraints    []ConstraintSpec
	DropConstraints   []string
	ModifyConstraints []ConstraintChange

	// PrimaryKeyChange is in-place-impossible (surfaced via unsafeReasons,
	// like ORDER BY). CommentChange is ALTER-able (MODIFY COMMENT).
	PrimaryKeyChange *OrderByChange
	CommentChange    *StringChange
}

type TableResolver interface {
	LookupTable(db, name string) (TableSpec, bool)
}

type TableSpec struct {
	Name string `hcl:"name,label"`

	// Inheritance / control fields. Consumed during resolution; not part
	// of the schema for diff purposes.
	Extend   *string `hcl:"extend,optional"   diff:"-"`
	Abstract bool    `hcl:"abstract,optional" diff:"-"`
	Override bool    `hcl:"override,optional" diff:"-"`

	PrimaryKey  []string          `hcl:"primary_key,optional"`
	OrderBy     []string          `hcl:"order_by,optional"`
	PartitionBy *string           `hcl:"partition_by,optional"`
	SampleBy    *string           `hcl:"sample_by,optional"`
	TTL         *string           `hcl:"ttl,optional"`
	Settings    map[string]string `hcl:"settings,optional"`
	Comment     *string           `hcl:"comment,optional"`

	// Cluster is the ON CLUSTER target. May be set on the table itself, or
	// inherited from DatabaseSpec.Cluster during resolution.
	Cluster *string `hcl:"cluster,optional"`

	Columns []ColumnSpec `hcl:"column,block"`

	// ColumnPatches partially specialize columns inherited through Extend.
	// They are applied after the parent has resolved, preserve the inherited
	// column's position and every field they do not set, then are consumed.
	// A patch may only target an inherited column; ordinary column blocks
	// remain additions and still collide with inherited names.
	ColumnPatches []PatchColumnSpec `hcl:"patch_column,block" diff:"-"`

	Indexes     []IndexSpec      `hcl:"index,block"`
	Projections []ProjectionSpec `hcl:"projection,block"`
	Constraints []ConstraintSpec `hcl:"constraint,block"`
	Engine      *EngineSpec      `hcl:"engine,block"`
}

type TimeSeriesInnerTable struct {
	Columns     []ColumnSpec      `hcl:"column,block"`
	Engine      *EngineSpec       `hcl:"engine,block"`
	PrimaryKey  []string          `hcl:"primary_key,optional"`
	OrderBy     []string          `hcl:"order_by,optional"`
	PartitionBy *string           `hcl:"partition_by,optional"`
	TTL         *string           `hcl:"ttl,optional"`
	Settings    map[string]string `hcl:"settings,optional"`
}

type TimeSeriesTarget struct {
	Target *string               `hcl:"target,optional"`
	Inner  *TimeSeriesInnerTable `hcl:"inner,block"`
}

type UnsafeChange struct {
	Database string
	Table    string
	Reason   string
}

type ValidateOptions struct {
	// StrictProxyColumns requires a Distributed table and its remote to have
	// exactly the same set of columns. When false (default), the proxy's
	// columns need only be a subset of the remote's (every proxy column must
	// exist on the remote with a matching type) — a proxy may legitimately
	// omit columns.
	StrictProxyColumns bool

	// StrictClusters requires every Distributed remote to resolve against a
	// real composition: a remote on an @absent cluster is an error instead of
	// being satisfied. Use it to enforce full validation when the whole fleet
	// is composed, so a stale @absent (a cluster that has since been mapped)
	// cannot silently pass.
	StrictClusters bool
}

type ValidationError struct {
	Object  ObjectRef // the dependent object
	Missing ObjectRef // the unresolved reference
	Kind    string
	Cluster string // Distributed cluster name; empty for non-Distributed findings
	Reason  string
}

type ViewDiff struct {
	Name        string
	QueryChange *StringChange
	Comment     *StringChange
	Recreate    bool

	// RecreateChanged names the attributes that forced Recreate, in a fixed
	// order, so consumers can report which one moved.
	RecreateChanged []string
}

type ViewSpec struct {
	Name          string   `hcl:"name,label"`
	Override      bool     `hcl:"override,optional" diff:"-"`
	Query         string   `hcl:"query"`
	ColumnAliases []string `hcl:"column_aliases,optional"`
	SQLSecurity   *string  `hcl:"sql_security,optional"`
	Definer       *string  `hcl:"definer,optional"`
	Cluster       *string  `hcl:"cluster,optional"`
	Comment       *string  `hcl:"comment,optional"`
}