models

Documentation

Index

• func NormalizeColumnType(t string, aliases map[string]string) string
• func NormalizeDefaultExpression(expr string) string
• func NormalizeEngine(engine string) string
• type Column
• type ColumnProperties
• type CombinedColumn
• type CombinedDatabase
• type CombinedFunction
• type CombinedSchema
  • func NewCombinedSchema(from, to Schema) *CombinedSchema
• type CombinedTable
• type Database
• type Function
• type FunctionProperties
• type GeneratorConfig
• type Operation
• type OperationAction
• type OperationLevel
• type Presence
• type SQLStatements
  • func ParseFile(content string) (*SQLStatements, error)
  • func (stmts *SQLStatements) Add(s string)
  • func (stmts *SQLStatements) ToStatements() string
• type Schema
• type Strategy
• type SyncPlan
• type SyncPlanGenerator
  • func NewSyncPlanGenerator(config GeneratorConfig) *SyncPlanGenerator
  • func (g *SyncPlanGenerator) Generate(combined *CombinedSchema) *SyncPlan
• type Table
• type TableProperties

Functions

func NormalizeColumnType

func NormalizeColumnType(t string, aliases map[string]string) string

NormalizeColumnType resolves ClickHouse type aliases and formatting variants so that equivalent types compare equal.

aliases is a map of uppercase alias name → canonical type name, as returned by LoadTypeAliases (queried from system.data_type_families). Pass nil to skip alias resolution.

Two normalizations are always applied regardless of the alias map:

• DateTime64/DateTime timezone quotes: DateTime64(3, 'UTC') → DateTime64(3, UTC)

func NormalizeDefaultExpression

func NormalizeDefaultExpression(expr string) string

NormalizeDefaultExpression canonicalizes default expression representations. ClickHouse may quote simple literals differently across versions: '0' and 0 are equivalent for numeric columns; 'false' and false for Bool. Outer quotes are stripped only for simple numeric and boolean literals — complex string defaults like 'hello' are left untouched to avoid false equivalences.

func NormalizeEngine

func NormalizeEngine(engine string) string

NormalizeEngine strips cloud-specific prefixes from engine names. e.g. SharedMergeTree -> MergeTree, SharedReplacingMergeTree -> ReplacingMergeTree

Types

type Column

type Column struct {
	Name              string
	Type              string
	DefaultExpression string
	CompressionCodec  string
	Comment           string
}

Column represents a table column

type ColumnProperties

type ColumnProperties struct {
	Type              string
	Position          uint64
	DefaultKind       string
	DefaultExpression string
	CompressionCodec  string
	Comment           string
}

ColumnProperties contains properties of a column

type CombinedColumn

type CombinedColumn struct {
	Name     string
	Presence Presence
	Source   *ColumnProperties
	Target   *ColumnProperties
}

CombinedColumn represents a column that may exist in source, target, or both

type CombinedDatabase

type CombinedDatabase struct {
	Name     string
	Presence Presence
	Tables   []CombinedTable
}

CombinedDatabase represents a database that may exist in source, target, or both

type CombinedFunction

type CombinedFunction struct {
	Name     string
	Presence Presence
	Source   *FunctionProperties
	Target   *FunctionProperties
}

CombinedFunction represents a SQL UDF that may exist in source, target, or both

type CombinedSchema

type CombinedSchema struct {
	Databases []CombinedDatabase
	Functions []CombinedFunction
}

CombinedSchema represents a merged view of two schemas

func NewCombinedSchema

func NewCombinedSchema(from, to Schema) *CombinedSchema

NewCombinedSchema creates a CombinedSchema by comparing from (source) and to (target) schemas

type CombinedTable

type CombinedTable struct {
	Name     string
	Presence Presence
	Source   *TableProperties
	Target   *TableProperties
	Columns  []CombinedColumn
}

CombinedTable represents a table that may exist in source, target, or both

type Database

type Database struct {
	Name   string
	Tables []Table
}

Database represents a ClickHouse database with its tables

type Function

type Function struct {
	Name        string
	CreateQuery string
}

Function represents a SQL user-defined function

type FunctionProperties

type FunctionProperties struct {
	CreateQuery string
}

FunctionProperties contains properties of a SQL UDF

type GeneratorConfig

type GeneratorConfig struct {
	// Similarity thresholds for detecting potential renames (0.0-1.0)
	TableRenameSimilarityThreshold  float64 // e.g., 0.80 = 80% column match
	ColumnRenameSimilarityThreshold float64

	// TypeAliases maps uppercase alias names to their canonical ClickHouse type names.
	// Loaded at runtime from system.data_type_families via LoadTypeAliases.
	// When set, equivalent types (e.g. INTEGER vs Int32) will not generate MODIFY COLUMN.
	TypeAliases map[string]string
}

GeneratorConfig configures how the sync plan generator interprets differences.

type Operation

type Operation struct {
	Level       OperationLevel  // what entity is affected (database, table, column)
	Action      OperationAction // what action is performed (create, drop, rename, alter)
	CanLoseData bool            // whether this operation can cause data loss
	Statements  []string        // SQL statements to execute
	Explanation string          // e.g., "Rename table1→table11 (85% column match)"
}

Operation represents a single schema change operation within a strategy.

type OperationAction

type OperationAction string

OperationAction identifies what action a schema operation performs.

const (
	ActionCreate OperationAction = "create"
	ActionDrop   OperationAction = "drop"
	ActionRename OperationAction = "rename"
	ActionAlter  OperationAction = "alter"
)

type OperationLevel

type OperationLevel string

OperationLevel identifies what entity a schema operation affects.

const (
	LevelDatabase OperationLevel = "database"
	LevelTable    OperationLevel = "table"
	LevelColumn   OperationLevel = "column"
	LevelIndex    OperationLevel = "index"
	LevelFunction OperationLevel = "function"
)

type Presence

type Presence string

Presence indicates where an element exists

const (
	Source Presence = "Source" // exists only in source instance
	Target Presence = "Target" // exists only in target instance
	Both   Presence = "Both"   // exists in both instances
)

type SQLStatements

type SQLStatements struct {
	Version           string
	StatementsCleaned []string
}

func ParseFile

func ParseFile(content string) (*SQLStatements, error)

ParseFile splits raw SQL file content into individual CREATE statements. Returns an error if the file is not a valid chsync schema snapshot (missing header).

func (*SQLStatements) Add

func (stmts *SQLStatements) Add(s string)

func (*SQLStatements) ToStatements

func (stmts *SQLStatements) ToStatements() string

type Schema

type Schema struct {
	Databases []Database
	Functions []Function
}

Schema represents a complete ClickHouse schema

type Strategy

type Strategy struct {
	Name        string      // e.g., "Optimistic (with renames)", "Conservative"
	Description string      // human-readable explanation of this strategy
	Operations  []Operation // ordered list of operations to execute
}

Strategy represents one complete interpretation of how to synchronize schemas. Examples: "Optimistic (with renames)", "Conservative (drop/create only)", "Hybrid"

type SyncPlan

type SyncPlan struct {
	Strategies []Strategy
}

SyncPlan represents a schema synchronization plan with multiple complete strategies.

Design rationale: When comparing schemas (e.g., instance A has table1, instance B has table11), the same atomic differences can be interpreted in multiple ways:

• Optimistic: "RENAME table1 TO table11" (if columns are similar)
• Conservative: "DROP table1; CREATE table11" (separate operations)

These interpretations are mutually exclusive - you cannot mix operations from different strategies. Therefore, we model complete alternative strategies rather than per-difference options. This avoids combinatorial explosion while giving users sensible choices.

Users select one complete Strategy, not individual operations.

type SyncPlanGenerator

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

SyncPlanGenerator builds migration strategies from a combined schema diff.

func NewSyncPlanGenerator

func NewSyncPlanGenerator(config GeneratorConfig) *SyncPlanGenerator

NewSyncPlanGenerator creates a new sync plan generator with the given configuration.

func (*SyncPlanGenerator) Generate

func (g *SyncPlanGenerator) Generate(combined *CombinedSchema) *SyncPlan

Generate creates a SyncPlan with multiple strategies from a combined schema diff.

type Table

type Table struct {
	Name        string
	Engine      string
	Columns     []Column
	OrderBy     []string
	PrimaryKey  []string
	PartitionBy string
	Settings    map[string]string
}

Table represents a ClickHouse table with its columns Includes all table types: Table, View, MaterializedView, Dictionary, etc.

type TableProperties

type TableProperties struct {
	Engine      string
	OrderBy     []string
	PrimaryKey  []string
	PartitionBy string
	Settings    map[string]string
}

TableProperties contains properties of a table