Documentation
¶
Overview ¶
Package deploy implements `tr deploy`: it parses every .datasource/.pipe file in a project directory, validates them all before touching ClickHouse (ADR 0027 — validate-all-then-apply), diffs each datasource against the live ClickHouse schema, applies safe additive migrations, creates materialized views (ADR 0010), and registers the datasource definitions in the metadata registry (ADR 0001). Breaking changes (dropped columns, type changes) are refused by default; with AllowBreaking they are applied via the shadow-table → backfill → EXCHANGE TABLES path (ADR 0007). Options.Database targets a per-branch workspace database.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CH ¶
type CH interface {
model.CHQuerier // Query(ctx, sql, params, settings) ([]byte, error)
EnsureTable(ctx context.Context, ds *model.Datasource) error
CreateDatabase(ctx context.Context, name string) error
CreateMaterializedView(ctx context.Context, m *model.Materialization) error
CreateShadowTable(ctx context.Context, ds *model.Datasource, shadowName string) error
Backfill(ctx context.Context, dst, src string, cols []string) error
ExchangeTables(ctx context.Context, a, b string) error
DropTable(ctx context.Context, name string) error
}
CH is the slice of *clickhouse.Client deploy needs: read-only schema queries, table creation, materialized views, and the breaking-migration DDL (shadow create / backfill / exchange / drop). Declared as an interface so the diff/apply logic is unit testable with a fake; cmd/tr passes the concrete *clickhouse.Client.
type Options ¶
type Options struct {
// AllowBreaking acknowledges breaking schema changes. With it set, breaking
// datasource changes are applied via shadow-table → backfill → EXCHANGE
// TABLES (ADR 0007); without it they are refused and nothing is applied.
AllowBreaking bool
// Database, when non-empty, is the workspace database the deploy targets
// (the orchestrator passes the per-branch name tr_<branch>; ADR 0007). Run
// creates it (CREATE DATABASE IF NOT EXISTS) and re-scopes the client onto it
// before any table DDL. Empty keeps the client's configured database.
Database string
// Tokens, when non-nil, makes Run materialize the resource tokens declared via
// `TOKEN "name" READ|APPEND` lines in .pipe/.datasource files (ADR 0030). Nil
// skips token materialization entirely, keeping Run backward-compatible with
// callers that have no token store wired.
Tokens TokenStore
// DryRun computes the full plan — validation, schema diff, breaking-change
// detection, MVs, tokens — and populates the Report, but applies NOTHING: no
// ClickHouse DDL, no registry writes, no token mint. Backs `tr deploy --check`.
DryRun bool
}
Options controls a deploy run.
type Report ¶
type Report struct {
Datasources int
Pipes int
Created []string
AltersApplied []string
Breaking []string
BreakingApplied []string
MaterializedViews []string
CopyPipes []string
Tokens []string
}
Report summarizes a deploy. Created lists datasources whose tables were created; AltersApplied lists the additive ALTER statements run; Breaking lists detected breaking changes; BreakingApplied lists the breaking migrations actually performed (only when AllowBreaking); MaterializedViews lists the MVs ensured (ADR 0010); Tokens lists the resource-token names materialized (or, on a dry run, that would be materialized) from file declarations (ADR 0030).
func Run ¶
func Run(ctx context.Context, dir string, ch CH, dsReg model.DatasourceRegistry, opts Options) (*Report, error)
Run validates and applies the project in dir.
Order (ADR 0027): parse + validate ALL files first; abort before any mutation if any file is invalid. If Options.Database is set, create and target that workspace database (ADR 0007). Then diff every datasource against the live schema. If breaking changes exist and AllowBreaking is false, refuse before applying anything (ADR 0006). Otherwise apply creates, breaking shadow swaps, and additive alters; register each datasource; then ensure materialized views last, once their target tables exist (ADR 0010).
type TokenStore ¶
type TokenStore interface {
List(ctx context.Context) ([]*model.Token, error)
Put(ctx context.Context, t *model.Token) error
}
TokenStore is the subset of token operations deploy needs to materialize resource tokens (ADR 0030). It is wider than model.TokenStore (which only validates + puts, keyed by value) because the idempotent, never-rotate upsert must find an existing token by Name — and that requires List. *auth.Store satisfies it; cmd/tr passes auth.NewStore(rdb) into Options.Tokens.
Source Files