Provider / distributed SQL

Validated

TiDB

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.

Metadata

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.

Immutable blocks

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.

Logical file/docs/readme.mdinode 42 · size 8,192NodeMetadata → NodeData::File(FileLayout)
blocksmount_rs_tidb_blocksBlockId → raw bytes
Illustrative Namespace / FileLayout record (shape, not serialized bytes)
Namespace {
  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

4 active tables

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

PK volume_key

One row per volume: namespace LONGTEXT plus pessimistic-lock lease state.

ColumnTypeStored meaning
volume_keyVARBINARY(1020)PRIMARY KEY; volume scope
revisionBIGINTnamespace CAS revision
namespaceLONGTEXT NULLserialized Namespace
ownerVARBINARY(1020) NULLcurrent writer owner
fenceBIGINTmonotonic fencing token
expiresBIGINTprovider-clock lease expiry
write_modeVARBINARY(4) NULLNULL for the exclusive-writer mode; a mode tag otherwise
backing_idVARBINARY(32) NULLblock-authority ID the metadata is bound to
delegationLONGTEXT NULLdelegated-publication state, when used

mount_rs_tidb_inodes

PK (volume_key, inode)

One row per inode, only for volumes using independent inode publication.

ColumnTypeStored meaning
volume_keyVARBINARY(1020)volume scope
inodeBIGINTinode ID
generationBIGINTstructural generation the record belongs to
revisionBIGINTper-inode CAS revision
nodeLONGTEXTserialized node record
blocks

mount_rs_tidb_block_authority

PK volume_key

One server-generated ID per volume key, which concurrent-mode metadata binds to and verifies.

ColumnTypeStored meaning
volume_keyVARBINARY(1020)PRIMARY KEY; volume scope
backing_idVARBINARY(32)stable block-authority ID
blocks

mount_rs_tidb_blocks

PK (volume_key, id)

Content-derived immutable blocks scoped by volume.

ColumnTypeStored meaning
volume_keyVARBINARY(1020)volume scope
idVARBINARY(65)content-derived BlockId
bytesLONGBLOBraw immutable block bytes
Read the live relational schema
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;
Validated — scoped evidence

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

Read-only inspection example
-- 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.

← Back to providers