datus-tidb

TiDB database adapter for Datus.

TiDB speaks the MySQL wire protocol, so this adapter builds on datus-mysql and overrides only what genuinely differs: the METRICS_SCHEMA system database, the absence of materialized views, TiFlash columnar replicas, and the two DDL clauses TiDB accepts without honouring.

Timeouts

timeout_seconds (default 30, positive seconds) bounds pool checkout and is also the default for PyMySQL connect, read, and write timeouts. Override these independently with connect_timeout_seconds, read_timeout_seconds, and write_timeout_seconds. None inherits the finite default. Long queries may need a larger read timeout. Optional query_timeout_seconds configures the server's SELECT deadline on every physical connection; it defaults to None (preserve server settings). Socket inactivity timeouts are not total query deadlines. See timeout semantics and adapter audit.

Installation

pip install datus-tidb

Configuration

namespace:
  my_tidb:
    type: tidb
    host: 127.0.0.1
    port: 4000          # TiDB's own default; 3306 is a different server
    username: root
    password: ""
    database: analytics

TLS is not supported yet: the semantic layer's MySQL-wire executor has no TLS either, so accepting the keys here would let a datasource connect for metadata and then fail at query time. TiDB Cloud endpoints that require TLS are therefore out of reach for now.

Usage

from datus_tidb import TiDBConfig, TiDBConnector

connector = TiDBConnector(TiDBConfig(username="root", database="analytics"))
result = connector.execute({"sql_query": "SELECT 1"}, result_format="list")

TiFlash

TiFlash is TiDB's columnar replica engine, granted per table with ALTER TABLE t SET TIFLASH REPLICA 1. It needs nothing from this adapter: replicas are transparent to SQL — the optimizer chooses between row store and columnar on its own — and their state is a plain SELECT * FROM information_schema.TIFLASH_REPLICA, which the packaged SQL skill points the model at.

The skill also tells the model to prefer GROUP BY aggregation over an equivalent aggregate window function: the latter does not run in parallel on TiFlash.

Known TiDB behaviors

validate_ddl() flags the first two, which are the ones that fail silently.

Testing

# Unit tests (no database)
pytest datus-tidb/tests/unit -v

# Integration tests (four-container cluster with TiFlash)
docker compose -f datus-tidb/docker-compose.yml up -d --wait
pytest datus-tidb/tests/integration -m integration -v
docker compose -f datus-tidb/docker-compose.yml down -v

The compose file runs PD, TiKV, TiDB and TiFlash rather than the single-container --store=unistore form: unistore starts in about a second but has no TiFlash, so it cannot cover the columnar and MPP paths this adapter exposes.

License

Apache License 2.0