MySQL Compatibility

TiDB speaks the MySQL 8.0 wire protocol. Your existing MySQL clients, drivers, and ORMs connect to TiDB the same way they connect to MySQL — same port, same authentication, same SQL syntax. Most applications can migrate with zero or minimal code changes.

Connecting to TiDB

TiDB listens on port 4000 by default (configurable). You can also run it on the standard MySQL port 3306. Any MySQL client or driver works:

# mysql CLI
mysql -h 127.0.0.1 -P 4000 -u root

# With password and database
mysql -h tidb-host -P 4000 -u appuser -p myapp_db

# Using a connection string (same format as MySQL)
mysql://appuser:password@tidb-host:4000/myapp_db

TiDB supports MySQL-compatible authentication methods including mysql_native_password and caching_sha2_password.

ORM and framework compatibility

TiDB works with all major ORMs and frameworks that support MySQL 8.0.

Java
Python
Go
Ruby
Node.js

// Hibernate / Spring Data JPA — use the MySQL 8 dialect
spring.datasource.url=jdbc:mysql://tidb-host:4000/myapp?useSSL=false
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
spring.jpa.database-platform=org.hibernate.dialect.MySQL8Dialect

<!-- pom.xml — standard MySQL connector works unchanged -->
<dependency>
  <groupId>mysql</groupId>
  <artifactId>mysql-connector-java</artifactId>
  <version>8.0.33</version>
</dependency>

# SQLAlchemy
from sqlalchemy import create_engine

engine = create_engine(
    "mysql+pymysql://user:password@tidb-host:4000/myapp",
    pool_pre_ping=True,
)

# Django settings.py
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.mysql",
        "NAME": "myapp",
        "USER": "user",
        "PASSWORD": "password",
        "HOST": "tidb-host",
        "PORT": "4000",
    }
}

// GORM
import (
    "gorm.io/driver/mysql"
    "gorm.io/gorm"
)

dsn := "user:password@tcp(tidb-host:4000)/myapp?charset=utf8mb4&parseTime=True&loc=Local"
db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})

# config/database.yml (Rails with ActiveRecord)
default: &default
  adapter: mysql2
  encoding: utf8mb4
  host: tidb-host
  port: 4000
  username: user
  password: password

development:
  <<: *default
  database: myapp_development

// mysql2
const mysql = require('mysql2/promise');

const connection = await mysql.createConnection({
  host: 'tidb-host',
  port: 4000,
  user: 'user',
  password: 'password',
  database: 'myapp',
});

Supported SQL features

TiDB supports the vast majority of MySQL 8.0 SQL, including: DDL: CREATE/ALTER/DROP TABLE, ADD/DROP INDEX, ADD COLUMN, MODIFY COLUMN, RENAME TABLE, TRUNCATE, partitioning, views, generated columns. DML: INSERT, UPDATE, DELETE, REPLACE, INSERT ... ON DUPLICATE KEY UPDATE, SELECT ... FOR UPDATE, SELECT ... FOR SHARE. Data types: All MySQL numeric, string, date/time, JSON, and spatial types. Functions: Most MySQL built-in functions, window functions, CTEs (WITH), JSON functions, and full-text search. Stored procedures and triggers: Basic stored procedures, functions, and triggers are supported. System variables: TiDB supports most MySQL system variables (@@global.*, @@session.*). Some variables are accepted for compatibility but have no effect because TiDB handles the underlying behavior differently.

-- System variable example — same syntax as MySQL
SET SESSION sql_mode = 'STRICT_TRANS_TABLES,NO_ZERO_IN_DATE';
SET GLOBAL max_connections = 1000;
SHOW VARIABLES LIKE 'tidb_%'; -- TiDB-specific variables

Differences from MySQL

TiDB is not a drop-in replacement in every case. The following differences are the most commonly encountered.

Foreign key enforcement

TiDB parses FOREIGN KEY constraints but does not enforce them by default. Referential integrity must be maintained by the application or enforced with tidb_enable_foreign_key = ON (available in recent TiDB versions).

-- This executes without error, foreign key is stored but not enforced by default
CREATE TABLE orders (
  id BIGINT PRIMARY KEY,
  customer_id BIGINT,
  FOREIGN KEY (customer_id) REFERENCES customers(id)
);

-- Enable enforcement (if your TiDB version supports it)
SET GLOBAL tidb_enable_foreign_key = ON;

AUTO_INCREMENT behavior

TiDB’s AUTO_INCREMENT allocates IDs in batches per TiDB server node to avoid a single-point bottleneck. This means:

IDs are guaranteed to be unique and monotonically increasing per node, but not globally monotonic across all nodes.
Gaps in the sequence are possible when a batch is allocated but not fully consumed.
If you need a globally monotonic sequence, use AUTO_RANDOM instead.

-- AUTO_RANDOM: globally unique, distributed-friendly primary keys
CREATE TABLE users (
  id BIGINT PRIMARY KEY AUTO_RANDOM,
  name VARCHAR(255)
);

Some DDL behaviors

TiDB uses an online DDL mechanism similar to MySQL’s online DDL, but the implementation differs:

ALTER TABLE operations that add columns are non-blocking and do not populate new column data immediately; the default value is returned at read time for existing rows.
Only one DDL owner processes DDL jobs cluster-wide; DDL operations are serialized per table (though different tables can be altered in parallel).
INSTANT algorithm for ADD COLUMN is supported.

Repeatable Read semantics

TiDB’s Repeatable Read is implemented with MVCC snapshots rather than MySQL’s gap locks. As a result:

Phantom reads are prevented within a snapshot, but via snapshot isolation rather than range locks.
SELECT ... FOR UPDATE reads the latest committed version of a row (not the transaction snapshot), which can differ from MySQL’s behavior in some edge cases.

Unsupported or partially supported features

The following features are not supported or only partially supported:

FULLTEXT indexes have limited support; consider using dedicated search solutions for production full-text search.
GET_LOCK() / RELEASE_LOCK() advisory locks are supported.
LOAD DATA INFILE is supported with some restrictions.
CREATE TABLE ... SELECT is supported.
User-defined functions (UDFs) compiled as shared libraries are not supported.
XA transactions have limited support.

Migrating from MySQL

Export your schema and data

Use mysqldump or TiDB’s migration tool (Dumpling) to export your MySQL database.

# Using Dumpling (recommended for large databases)
tiup dumpling -h mysql-host -P 3306 -u root -p \
  --filetype sql --output ./dump/ --database myapp

# Using mysqldump for smaller databases
mysqldump -h mysql-host -u root -p myapp > myapp.sql

Import into TiDB

Use TiDB Lightning for fast bulk imports, or pipe the SQL dump directly.

# Fast bulk import with TiDB Lightning
tiup tidb-lightning -config lightning.toml

# Small database: pipe directly
mysql -h tidb-host -P 4000 -u root < myapp.sql

Verify compatibility

Run your application’s test suite against TiDB. Check for foreign key enforcement differences, AUTO_INCREMENT gaps, and any MySQL-specific syntax your application uses.

-- Check if TiDB version meets your requirements
SELECT tidb_version();

-- List any warnings from your imported schema
SHOW WARNINGS;

Update connection strings

Point your application at TiDB. Only the host and port need to change; the driver and connection string format remain identical.

# Before (MySQL)
DB_URL=mysql://user:pass@mysql-host:3306/myapp

# After (TiDB)
DB_URL=mysql://user:pass@tidb-host:4000/myapp

For large-scale migrations or continuous replication from MySQL, use TiDB Data Migration (DM). DM reads MySQL binlogs and applies changes to TiDB in near real time, enabling zero-downtime cutovers.

System variables

TiDB exposes its own configuration through session and global variables, using the same SET/SHOW VARIABLES syntax as MySQL.

-- View TiDB-specific variables
SHOW VARIABLES LIKE 'tidb_%';

-- Common variables
SET SESSION tidb_txn_mode = 'pessimistic';    -- transaction mode
SET SESSION tidb_replica_read = 'follower';   -- read from follower replicas
SET GLOBAL tidb_mem_quota_query = 1073741824; -- 1 GB per-query memory limit

-- Check transaction isolation level (same as MySQL)
SELECT @@SESSION.transaction_isolation;

Get Started

Core Concepts

Deployment

Data Management

Operations

MySQL Compatibility

Connecting to TiDB

ORM and framework compatibility

Supported SQL features

Differences from MySQL

Migrating from MySQL

System variables

Build docs developers (and LLMs) love

Get Started

Core Concepts

Deployment

Data Management

Operations

Documentation Index

​Connecting to TiDB

​ORM and framework compatibility

​Supported SQL features

​Differences from MySQL

​Migrating from MySQL

​System variables

Build docs developers (and LLMs) love

Connecting to TiDB

ORM and framework compatibility

Supported SQL features

Differences from MySQL

Migrating from MySQL

System variables