Data models

The persistent and in-memory data models that show up across multiple subsystems. For per-package types see the relevant systems page.

Persistent schema model

The most important persistent shapes live in pkg/meta/model/:

Type	Purpose
model.DBInfo	Database (schema) definition.
model.TableInfo	Table definition: columns, indexes, partition info, charset, FK refs.
model.ColumnInfo	Column metadata: type, default, charset, generated-column expr.
model.IndexInfo	Index definition: columns, type, visibility.
model.PartitionInfo, model.PartitionDefinition	Partition layouts.
model.ForeignKeyInfo	FK constraint.
model.SequenceInfo	CREATE SEQUENCE.
model.PolicyInfo	Placement policy.
model.ResourceGroup	Resource group definition.
model.Job	DDL job record (state, args, errors). Also persisted to mysql.tidb_ddl_job.

These are JSON-serialised and stored in TiKV via pkg/meta/. Layout decisions:

• Each database gets a meta-key carrying its DBInfo.
• Each table's TableInfo lives under m_DBs/<db_id>/Tables/<table_id>.
• DDL jobs live in two queues (mysql.tidb_ddl_job and reorg queues), drained by the elected DDL owner.

TiKV key layout

pkg/tablecodec/tablecodec.go is the source of truth for how SQL tables are encoded into TiKV's flat key space. Highlights:

• Row keys: t<table_id>_r<handle>. The handle is the clustered index value (or auto-id for non-clustered tables).
• Index keys: t<table_id>_i<index_id>_<encoded_index_columns>_<handle>.
• Memcomparable encoding for index keys ensures TiKV's byte order matches SQL's logical order.
• Padding bytes denote "infinity" markers for range scans.
• Generated columns and clustered-index variants change the encoding details; the file enumerates each case.

Statement-time runtime model

Type	Where	Purpose
sessionctx.Context	pkg/sessionctx/sessionctx.go	The Swiss-army-knife handed to planner/executor.
variable.SessionVars	pkg/sessionctx/variable/session_vars.go	Strongly-typed session variables.
stmtctx.StatementContext	pkg/sessionctx/stmtctx/stmtctx.go	Per-statement state: warnings, runtime stats, time zone.
expression.Expression	pkg/expression/expression.go	Expression tree node.
chunk.Chunk	pkg/util/chunk/chunk.go	The columnar batch passed between operators.
kv.Transaction, kv.Snapshot	pkg/kv/kv.go	TiKV transaction and snapshot handles.
core.LogicalPlan, core.PhysicalPlan	pkg/planner/core/base/	Plan tree node interfaces.
executor.Executor	pkg/executor/internal/exec/	Runtime operator interface.

DDL job model

A DDL job is a serialisable struct (model.Job) with:

• ID, Type (e.g., ActionAddColumn), SchemaID, TableID.
• State (queueing, running, done, rolling back, cancelled, paused).
• Args (per-action serialised parameters).
• Error, ErrorCount, Warning.
• RowCount, Mu, RawArgs, BinlogInfo.
• MultiSchemaInfo for atomic multi-action ALTERs.

Workers persist these atomically per state transition through pkg/meta/.

Statistics model

Type	File	Purpose
statistics.Table	pkg/statistics/table.go	Per-table stats container.
statistics.Column, statistics.Index	column.go, index.go	Per-column/index stats.
statistics.Histogram	histogram.go	Equi-depth histogram.
statistics.CMSketch, statistics.TopN, statistics.FMSketch	cmsketch.go, fmsketch.go	Sketches.

Persisted in mysql.stats_meta, mysql.stats_histograms, mysql.stats_buckets, mysql.stats_top_n, mysql.stats_fm_sketch, mysql.stats_extended, mysql.stats_table_locked, mysql.stats_history.

System tables

Bootstrapped by pkg/session/bootstrap.go. The most heavily referenced system tables:

Table	Purpose
mysql.user, mysql.db, mysql.tables_priv, mysql.columns_priv	Privileges.
mysql.global_variables	Persistent global system-variable values.
mysql.tidb	Bootstrap and upgrade tracking.
mysql.tidb_ddl_job, mysql.tidb_ddl_history, mysql.tidb_ddl_reorg	DDL framework state.
mysql.stats_*	Statistics (see above).
mysql.bind_info	SQL bindings.
mysql.tidb_runaway_queries, mysql.tidb_resource_groups	Resource control.
mysql.tidb_import_jobs	IMPORT INTO job tracking.
mysql.tidb_background_subtask*	DXF subtasks.
mysql.tidb_ttl_job_history, mysql.tidb_ttl_table_status	TTL job state.
mysql.GLOBAL_PRIV	TLS/JWT-aware privileges.
mysql.help_*	MySQL HELP scaffolding (mostly empty).

The full list and column definitions are in pkg/session/bootstrap.go and pkg/session/upgrade_def.go. Each new release that adds or modifies a system table appends a new "upgrade step" to upgrade_def.go.