MatrixOne architecture

Implementation baseline: MatrixOne v4.2.5. Separating service responsibilities does not make active transactions, sessions, or recovery freely movable.

Components and data flow

client → optional Proxy → CN: Frontend → Plan → Compile/Pipeline
                               │                  │
                               │                  └→ FileService → object storage
                               └→ DistTAE → TN/TAE → WAL → LogService/Raft
                                            │
                                            └→ Logtail → subscribed CN read state

Component

Responsibility

Boundary

CN

Protocol, authentication, SQL planning/execution, transaction workspace, reads and caches

Caches are not authoritative; sessions, active transactions and queries still have lifetimes

TN/TAE

Transaction decisions, Catalog/MVCC, WAL, Logtail, Flush, Checkpoint and Merge

Reconstructible state still requires recovery and readiness before service

LogService

Raft-backed durable log append, read and truncation

WAL carries recovery information; Logtail synchronizes TN state to CNs

FileService

File/object I/O and local/remote caches

Fetching remote cached bytes does not forward SQL execution

Proxy

Tenant/label routing and connection migration

Session routing differs from distributed operator placement

HAKeeper

Cluster state and scheduling commands

Kubernetes resource readiness does not replace database readiness

Writes, commits and visibility

  1. CN organizes changes in its transaction workspace. Small writes may travel to TN; bulk paths may write objects first and submit their metadata.

  2. TN prepares and decides transactions, recording the recovery information in the WAL backend. The commit application path waits for WAL completion; an asynchronous pipeline does not bypass durability.

  3. TN supplies committed row changes, deletions and object metadata through Logtail. A CN needs the state required by its snapshot timestamp before reading.

  4. Background Flush/Merge/Checkpoint changes layout and the recovery starting point. Transaction commit, object flush, Logtail application and checkpoint completion are separate events.

Invariants: committed changes have a durable recovery basis; a snapshot combines visible objects, memory changes and deletion information. Listing S3 files is not a SQL snapshot reconstruction method.

Reads and failures

CN reads the workspace, Logtail-reconstructed state and timestamp-visible objects according to the plan. FileService can use memory, disk or remote cached bytes. Cache loss mainly affects performance; interrupted Logtail, unknown transaction outcomes and loss of a log quorum affect correctness conditions or availability.

CN restarts affect connections and running work. TN restarts require Checkpoint/WAL recovery and may change lock bindings. LogService replica count and quorum follow deployment configuration; three replicas are an example, not a universal constant.

Reading path

Read TAE and transactions, then WAL, Logtail, FileService, Proxy and Operator. SQL references describe interfaces; architecture describes their implementation. Check actual build/configuration for thresholds and experimental features.

Source and regression entry points