Laravel Tidb Laravel Package

Getting Started

• Install with composer require colopl/laravel-tidb. The service provider is auto-discovered, so no manual registration is required on modern Laravel.
• Add a connection to config/database.php using 'driver' => 'tidb'. Copy the standard mysql block (host, port — typically 4000 for TiDB — database, username, password, charset, collation). The driver name is the only meaningful change; it is what swaps in the package's TiDB connection and schema grammar.
• TiDB speaks the MySQL wire protocol, so the app code does not change. Point Eloquent models or DB::connection('tidb') at it and proceed as you would on MySQL.
• First use case: point an existing Laravel app at a TiDB cluster (local pingcap/tidb Docker image or TiDB Cloud) and run php artisan migrate to validate that your schema builder calls survive TiDB DDL.

Implementation Patterns

• Treat tidb as the canonical connection for both the app and the test suite. Keep a separate mysql connection only when you genuinely target MySQL as well.
• Use Schema::create / Schema::table normally. The package's grammar adapts the emitted DDL to TiDB; you should not need to hand-write DDL for standard column/index definitions.
• For high-write tables, consider TiDB's AUTO_RANDOM or shard_row_id_bits to avoid auto-increment hotspots across regions. Laravel does not emit AUTO_RANDOM natively — either subclass the grammar (see extension points below) or issue raw DDL inside the migration.
• Multi-connection apps: keep a mysql connection for reporting/legacy workloads and tidb for the OLTP path; select per model with protected $connection = 'tidb';.
• Testing: run migrations against a real TiDB instance (testcontainers or a docker-compose service) in CI. SQLite/MySQL-only tests will not catch DDL divergence, because the interesting behavior lives in the TiDB grammar.
• Local dev: use pingcap/tidb (plus PD/TiKV, or a single-node tidb image for quick iteration). Match the charset/collation to production to avoid surprises.
• Deployment: php artisan migrate returns before DDL necessarily completes in TiDB — DDL is online and asynchronous. For release gating, poll ADMIN SHOW DDL JOBS rather than assuming the schema is live the moment the command exits.

Gotchas and Tips

• Driver name is not cosmetic. Use 'driver' => 'tidb'. Falling back to the plain mysql driver bypasses the package's grammar and re-exposes TiDB to unsupported MySQL DDL.
• Unsupported index types. TiDB (especially older versions) does not support FULLTEXT or SPATIAL indexes. Audit migrations for $table->fullText() and $table->spatialIndex() before shipping.
• ->change() / column modifications. TiDB's ALTER TABLE … MODIFY semantics differ from MySQL 8. The package handles common cases, but compound changes (multiple columns, type + default + collation in one call) may still need raw SQL.
• Foreign keys. Newer TiDB enforces FKs only when tidb_enable_foreign_key is set. Do not rely on them for integrity across all deployments — enforce at the application layer or via constraints you control.
• Transactions. TiDB supports optimistic and pessimistic modes. DB::transaction() maps fine, but automatic retry on write conflicts (optimistic mode) is not built in — wrap contended writes in an explicit retry loop.
• Version constraints. v5.0.0 adds Laravel 12 support. The major bump typically tightens illuminate/* constraints and may drop Laravel 10/11 — verify composer.json before upgrading a running app, and note Laravel 12 requires PHP 8.2+.
• Debugging. Run SHOW CREATE TABLE \table`` on TiDB to see exactly what the grammar emitted and diff it against what MySQL would produce. Use the TiDB slow query log for query-level issues.
• Config quirks. Keep charset and collation consistent with the cluster (utf8mb4). Mismatches usually surface as comparison or connection errors, not DDL errors, which makes them easy to misattribute to the package.
• Extension points. The package's connection and schema grammar classes are replaceable. Subclass the grammar if you need custom DDL (e.g. auto-emitting AUTO_RANDOM), then rebind via a custom resolver in a service provider.
• Guard no-op migrations. Statements that do nothing meaningful on TiDB (engine changes, table options) should be wrapped in if (DB::connection()->getDriverName() === 'tidb') blocks or Schema::hasTable checks to keep migrations idempotent across drivers.