Session and transactions

The session subsystem owns the lifecycle of a single connection: authentication state, system variables, transaction handling, prepared statements, and the link from the MySQL protocol layer to the rest of the SQL stack.

Purpose

pkg/session/ runs the per-connection state machine and drives transactions. It works closely with:

• pkg/sessionctx/ — typed context carried by every layer (planner/executor/expression).
• pkg/sessionctx/variable/ — system variable definitions.
• pkg/sessiontxn/ — transaction provider abstractions for pessimistic/optimistic/snapshot reads.
• pkg/server/ — the wire-protocol layer that calls into a session per packet.

Directory layout

pkg/session/
├── session.go             # The Session struct, Execute/ExecutePreparedStmt entry points
├── txn.go                 # LazyTxn — wraps kv.Transaction with deferred initialisation
├── txnmanager.go          # Per-session transaction manager
├── txninfo/               # Snapshot of in-flight transactions for INFORMATION_SCHEMA
├── nontransactional.go    # Non-transactional DML batching
├── advisory_locks.go      # GET_LOCK / RELEASE_LOCK
├── bootstrap.go           # First-time cluster bootstrap (system tables, default users)
├── upgrade_def.go         # All upgrade-step definitions
├── upgrade_run.go         # Runs upgrade steps on bootstrap
├── sync_upgrade.go        # Cross-instance synchronisation during upgrades
├── tidb.go                # Library entry points (tidb.RunStmt, tidb.Parse, …)
├── contextimpl.go         # Wires Session into sessionctx.Context
├── cursor/                # Cursor protocol (server-side cursors)
├── sessionapi/            # Public API surface re-exported for embedders
├── sessmgr/               # Session manager (used by Domain to enumerate sessions)
└── syssession/            # System-table-backed sessions used internally

Related directories:

pkg/sessionctx/
├── sessionctx.go          # Context interface
├── variable/              # System variable definitions and storage
├── stmtctx/               # Per-statement context (warnings, runtime stats)
└── ...

pkg/sessiontxn/
├── txn.go                 # TxnManager interface
├── isolation/             # Isolation-level providers (RC, RR, snapshot)
├── staleread/             # Stale-read providers
└── internal/

Key abstractions

Type	Where	Purpose
session.Session	pkg/session/session.go	Per-connection runtime: vars, infoschema snapshot, transaction, prepared statements.
session.LazyTxn	pkg/session/txn.go	Wraps kv.Transaction; defers actually starting one until needed.
sessionctx.Context	pkg/sessionctx/sessionctx.go	Interface that all SQL layers depend on. Implemented by Session.
variable.SessionVars	pkg/sessionctx/variable/session_vars.go	Strongly typed view of session variables.
variable.SysVar	pkg/sessionctx/variable/sysvar.go	Definition of every system variable.
stmtctx.StatementContext	pkg/sessionctx/stmtctx/stmtctx.go	Per-statement state: warnings, time zone, runtime stats.
sessiontxn.TxnManager	pkg/sessiontxn/txn.go	Manages transaction providers across statements.
bootstrap.BootstrapSession	pkg/session/bootstrap.go	Idempotent cluster bootstrap.

Lifecycle of a connection

sequenceDiagram
  participant C as Client
  participant Srv as pkg/server
  participant S as Session
  participant P as Parser
  participant Plan as Planner
  participant Exec as Executor
  participant KV as KV / Storage

  C->>Srv: TCP connect
  Srv->>S: createSession (CreateSession4Test or session.CreateSession)
  C->>Srv: COM_QUERY "SELECT ..."
  Srv->>S: Execute(ctx, sql)
  S->>P: Parse
  S->>Plan: Compile/Optimize
  S->>Exec: Build executor tree
  Exec->>KV: snapshot reads, txn writes
  Exec-->>S: Chunks
  S-->>Srv: ResultSet
  Srv-->>C: result rows

Transaction handling

LazyTxn (pkg/session/txn.go) is the central abstraction. Key behaviours:

• The session does not start a TiKV transaction at BEGIN. Instead, LazyTxn records a "pending" intent and lazily starts the transaction on the first read or write.
• Auto-commit transactions wrap a single statement; explicit BEGIN ... COMMIT/ROLLBACK or implicit BEGIN (e.g., issuing a DML with auto-commit off) hold the transaction across statements.
• Pessimistic vs optimistic transactions are selected by tidb_txn_mode and the global default. Transaction providers in pkg/sessiontxn/isolation/ translate that into the right kv.Transaction flags.
• Stale reads (AS OF TIMESTAMP, tidb_read_staleness) go through pkg/sessiontxn/staleread/.

System variables that affect transaction semantics are defined in pkg/sessionctx/variable/sysvar.go. Notable ones include tidb_txn_mode, tidb_constraint_check_in_place, tidb_disable_txn_auto_retry, tidb_retry_limit.

Bootstrap and upgrade

• On first start of a fresh cluster, bootstrap.BootstrapSession (pkg/session/bootstrap.go) creates the mysql system database, default users (root@%), and tables.
• Each TiDB version may add new system tables or migrate existing ones. The full ordered list of "upgrade steps" lives in pkg/session/upgrade_def.go. pkg/session/upgrade_run.go walks the list and runs each step that has not yet been applied (tracked by mysql.tidb rows).
• sync_upgrade.go coordinates so that only one instance runs the upgrade at a time across the cluster.

Statement execution path

session.Session.Execute is the entry point for queries:

1. Parse via session.tidb.go → pkg/parser/.
2. Compile via pkg/executor/compiler.go → planner.
3. Execute via the executor tree.
4. Update statement summary, slow log, stats deltas.

Prepared-statement execution goes through session.ExecutePreparedStmt, which consults pkg/planner/core/plan_cache*.go first.

System variables

pkg/sessionctx/variable/sysvar.go is one of the largest files in the repo (~240 KB) and is the source of truth for every tidb_*, tidb_opt_*, MySQL-compatible, and resource-control variable. Each entry declares scope (SESSION/GLOBAL/INSTANCE), default value, validation, and an optional SetSession/SetGlobal callback.

When adding a new variable:

1. Define it in sysvar.go.
2. If session-scoped, add a typed field on variable.SessionVars.
3. If global, add a watcher in pkg/domain/sysvar_cache.go so other instances pick it up.
4. Document defaults in pkg/sessionctx/variable/vardef/.

Integration points

• Server (pkg/server/) drives sessions via Server.GetTiDBContext/createSession.
• Domain (pkg/domain/) gives the session its current infoschema.InfoSchema and is the source of stats handles.
• Planner receives the session as sessionctx.Context.
• DDL uses syssession/ to run system-level SQL on its own internal session.
• Plan cache lives partially on the session (PreparedStmt.PreparedAst) and partially on a global cache.

Entry points for modification

• New session variable → sysvar.go + SessionVars field + domain/sysvar_cache.go (for global vars).
• New transaction provider → pkg/sessiontxn/<name>/, registered in txnmanager.go.
• Change to upgrade behaviour → add a new step to pkg/session/upgrade_def.go (never edit existing entries) and a unit test in bootstrap_test.go/upgrade_test.go.
• Cursor protocol → pkg/session/cursor/.

The validation matrix in AGENTS.md requires targeted package tests plus SQL integration tests for any user-visible change to session/variable/protocol behaviour.