Provider / distributed SQL
ValidatedTiDB
TiDB can supply either side of the split store using the MySQL wire protocol. Its transaction and replication behavior must be qualified from the actual TiDB/TiKV/PD deployment rather than inferred from a connection URL.
mount_rs_tidb_metadata stores the namespace LONGTEXT, revision, writer owner/fence/expiry, the write mode and its block-authority binding, keyed by the caller's volume_key. mount_rs_tidb_inodes holds one row per inode (generation, revision and the node record) for a volume that has opted in to independent inode publication (inode_updates); other volumes have no rows there.
mount_rs_tidb_blocks stores volume_key, a content-derived block ID, and LONGBLOB bytes. mount_rs_tidb_block_authority holds one server-generated ID per volume key; a concurrent-mode volume binds its metadata to that ID and verifies it on reopen, so metadata is never paired with a different block scope. Metadata and blocks may use separate TiDB options or different providers.
Storage anatomy
Follow one file through both planes.
A mount-rs namespace stores names, attributes, directory entries, layouts, and block references. The bytes stay in the independent block plane. The example below is illustrative; the provider-specific schema, keys, and prefixes are the inspectable contract.
inode 42 · size 8,192NodeMetadata → NodeData::File(FileLayout)BlockId → raw bytesNamespace {
nodes[42] = NodeMetadata {
stats: { ino: 42, size: 8192, mode: regular },
data: File(FileLayout {
chunker: { algorithm: "fixed-size", version: 1, chunk_size: 4096 },
extents: [
{ file_offset: 0, block: "b012...", block_offset: 0, length: 4096 },
{ file_offset: 4096, block: "bfed...", block_offset: 0, length: 4096 }
]
})
}
}
BlockId "b012..." -> [4 KiB raw bytes]
BlockId "bfed..." -> [4 KiB raw bytes]Relational storage
TiDB / MySQL wire schema
TiDB keeps the split provider small: one metadata row per volume and one content-addressed block table, plus a per-inode table used only by volumes that opt in to independent inode publication and a one-row-per-volume block-authority table. There are no hidden version tables in this adapter.
mount_rs_tidb_metadata
One row per volume: namespace LONGTEXT plus pessimistic-lock lease state.
| Column | Type | Stored meaning |
|---|---|---|
volume_key | VARBINARY(1020) | PRIMARY KEY; volume scope |
revision | BIGINT | namespace CAS revision |
namespace | LONGTEXT NULL | serialized Namespace |
owner | VARBINARY(1020) NULL | current writer owner |
fence | BIGINT | monotonic fencing token |
expires | BIGINT | provider-clock lease expiry |
write_mode | VARBINARY(4) NULL | NULL for the exclusive-writer mode; a mode tag otherwise |
backing_id | VARBINARY(32) NULL | block-authority ID the metadata is bound to |
delegation | LONGTEXT NULL | delegated-publication state, when used |
mount_rs_tidb_inodes
One row per inode, only for volumes using independent inode publication.
| Column | Type | Stored meaning |
|---|---|---|
volume_key | VARBINARY(1020) | volume scope |
inode | BIGINT | inode ID |
generation | BIGINT | structural generation the record belongs to |
revision | BIGINT | per-inode CAS revision |
node | LONGTEXT | serialized node record |
mount_rs_tidb_block_authority
One server-generated ID per volume key, which concurrent-mode metadata binds to and verifies.
| Column | Type | Stored meaning |
|---|---|---|
volume_key | VARBINARY(1020) | PRIMARY KEY; volume scope |
backing_id | VARBINARY(32) | stable block-authority ID |
mount_rs_tidb_blocks
Content-derived immutable blocks scoped by volume.
| Column | Type | Stored meaning |
|---|---|---|
volume_key | VARBINARY(1020) | volume scope |
id | VARBINARY(65) | content-derived BlockId |
bytes | LONGBLOB | raw immutable block bytes |
SELECT TABLE_NAME, COLUMN_NAME, COLUMN_TYPE, COLUMN_KEY
FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME LIKE 'mount_rs_tidb_%'
ORDER BY TABLE_NAME, ORDINAL_POSITION;The provider contract passes against a durable 3PD/3TiKV TiDB in CI, before and after component restarts, with fencing, ambiguous commits, trace parity, a real TLS handshake and its refusals, and composition with RustFS and Ozone blocks. Validated describes the software, not a deployment: topology, IAM, backup and restore drills, capacity and rollout remain the operator’s job. CI run 44270883958 on main at source e0ee93a0 is the current evidence, on the pinned TiDB v8.5.7 images. The tidb job ends with TIDB_ACCEPTANCE evidence=durable-multinode-restart: the split-store contract, provider-clock fencing, concurrent publication and an ambiguous commit that is reported as an unknown outcome and not replayed, before and after TiDB, TiKV and PD restarts on a 3PD/3TiKV topology. The same job passes the seeded trace-parity harness for five seeds against the mountx oracle, and provokes error codes 9007, 1205 and 1213 for autocommit statements, checking that none that reported one had committed. tidb-tls completes a verified TLS session and four refused ones (unrelated authority, public roots only, wrong host name, plaintext). tidb-rustfs composes TiDB metadata with RustFS blocks, hosts SQLite on a FUSE mount before and after the restarts, and fails a drive over between two servers with the writer lease in TiDB. ozone-tidb composes TiDB metadata with Apache Ozone blocks and measured 4,332 operations a second against its 1,000 floor; that figure is a gate on shared runners, not a capacity number. tidb-gc-life-time provokes error code 9006 for an autocommit statement on a TiDB of its own and checks that the statement did not commit; the provider still reports 9006 as an unknown outcome. The tidb and tidb-rustfs jobs kill every PD, TiKV and TiDB process at once with SIGKILL while a writer publishes, restart them, and check that every acknowledged publication survived, the one in flight is whole or absent and was not replayed, and the dead writer is fenced. tidb-rustfs also kills the mount-rs process with SIGKILL while SQLite is inside a transaction on the mount, and after a remount SQLite's integrity check passes with every committed transaction present.
Layout and chunking
Fixed-size chunks are represented as block rows and references in the namespace JSON. Defaults cap block and namespace payloads at 4 MiB to stay below common TiDB/TiKV entry and packet limits; deployments that raise those limits must make the matching chunk choice explicit.
Durability and consistency
Metadata operations require pessimistic transactions and a provider clock, with a volume-row SELECT ... FOR UPDATE. A flush is an acknowledgement round trip, not an fsync command. Setdurable only when the TiDB/TiKV replication and sync-log policy supports that assertion. Every statement, COMMIT and connection attempt is bounded: 120 seconds by default, or the statement_timeout_ms parameter of the connection URL. A timeout is never retried. When it ends a COMMIT or a single-statement publication, TiDB may already have committed, so the error reports an unknown outcome, exactly as for a lost connection, and the operation fails closed.
Across every split-store composition, new blocks are flushed before metadata references are published. A provider acknowledgement is not automatically a power-loss or distributed-locking guarantee.
Query only the owned volume key
-- Run through an authenticated TiDB SQL client.
SELECT volume_key, revision, OCTET_LENGTH(namespace) AS namespace_bytes
FROM mount_rs_tidb_metadata
WHERE volume_key = '<owned-volume-key>';
SELECT volume_key, id, OCTET_LENGTH(bytes) AS block_bytes
FROM mount_rs_tidb_blocks
WHERE volume_key = '<owned-volume-key>'
ORDER BY id
LIMIT 20;
-- Only populated for volumes using independent inode publication.
SELECT inode, generation, revision
FROM mount_rs_tidb_inodes
WHERE volume_key = '<owned-volume-key>'
ORDER BY inode
LIMIT 20;
SELECT volume_key, HEX(backing_id) AS backing_id
FROM mount_rs_tidb_block_authority
WHERE volume_key = '<owned-volume-key>';Credentials, cleanup, and safe operations
Use a dedicated database/user and keep the MySQL/TiDB URL in an environment variable. With require_ssl=true the server certificate and host name are verified against the built-in public roots; a TiDB whose certificate comes from a private authority adds it with the tls_ca_file URL parameter, which names a PEM file and is rejected without require_ssl=true. The integration tests use a unique volume key; clean only that key's metadata and blocks after all clients close, then close the pool. Do not drop provider tables shared by another run.
Current limits
A MySQL-compatible server is not TiDB acceptance. The durable 3PD/3TiKV restart sequence passes in hosted Linux CI, which is the authoritative result; it has not been run on the local development host, which lacks the memory the three-node topology needs. The TLS lane uses a throwaway authority against a single-node TiDB and does not cover a managed endpoint, certificate rotation or client certificates. A bounded Node/CLI consumer slice now covers configuration, partial write, truncate, shutdown/reopen, and owned RustFS-prefix cleanup. The terminal W08 hosted packet qualifies the defined Linux/macOS consumer and durable-service scope, but native mount beyond that matrix and production deployment remain separate. Its live TiDB/RustFS rows require MOUNT_RS_TIDB_URL and loopback RustFS credentials; do not treat those credentials or hosted fixtures as production IAM. The crash tests use SIGKILL, which leaves the page cache and disks alone: real power loss and host fsync are not tested and need hardware or a block device that drops unsynced writes. The mounted SQLite tests, including the mount crash, run on Linux FUSE only, and the backup, upgrade and observability policies under W08 are static checks, not drills.
Sources: Current CI evidence on main (run 44270883958) · Durable restart and trace-parity job · TLS handshake and refusal job · TiDB with RustFS blocks, SQLite hosting and failover job · TiDB with Ozone blocks job · TiDB readiness notes · Maturity levels · TiDB provider README · TiDB provider source · TiDB/RustFS consumer matrix · Durable Ozone/TiDB CI gate · TiDB progress ledger · TiDB production rollout contract · W08.39 backup and restore policy · W08.40 upgrade and rollback policy · W08.41 observability and alerting policy