Skip to main content

Django backend for TiDB

Project description

TiDB dialect for Django

PyPI PyPI - Python Version PyPI - Downloads .github/workflows/ci.yml

This adds compatibility for TiDB to Django.

Installation Guide


Before installing django-tidb, ensure you have a MySQL driver installed. You can choose either mysqlclient(recommended) or pymysql(at your own risk).

Install mysqlclient (Recommended)

Please refer to the mysqlclient official guide

Install pymysql (At your own risk)

django-tidb has not been tested with pymysql

pip install pymysql

Then add the following code at the beginning of your Django's

import pymysql


Installing django-tidb

To install django-tidb, you need to select the version that corresponds with your Django version. Please refer to the table below for guidance:

The minor release number of Django doesn't correspond to the minor release number of django-tidb. Use the latest minor release of each.

django django-tidb install command
v4.2.x v4.2.x pip install 'django-tidb>=4.2.0,<4.3.0'
v4.1.x v4.1.x pip install 'django-tidb>=4.1.0,<4.2.0'
v3.2.x v3.2.x pip install 'django-tidb>=3.2.0,<3.3.0'


Set 'ENGINE': 'django_tidb' in your settings to this:

    'default': {
        'ENGINE': 'django_tidb',
        'NAME': 'django',
        'USER': 'root',
        'PASSWORD': '',
        'HOST': '',
        'PORT': 4000,
DEFAULT_AUTO_FIELD = 'django.db.models.AutoField'
USE_TZ = False
SECRET_KEY = 'django_tests_secret_key'

Supported versions

  • TiDB 4.0 and newer
  • Django 3.2, 4.1 and 4.2
  • Python 3.6 and newer(must match Django's Python version requirement)


create your virtualenv with:

$ virtualenv venv
$ source venv/bin/activate

you can use the command deactivate to exit from the virtual environment.

run all integration tests.

$ DJANGO_VERSION=3.2.12 python

Migrate from previous versions

Releases on PyPi before 3.0.0 are published from repository This repository is a new implementation and released under versions from 3.0.0. No backwards compatibility is ensured. The most significant points are:

  • Only Django 3.2 and 4.0 are tested and supported.
  • Engine name is django_tidb instead of django_tidb.tidb.

Known issues

  • TiDB before v6.6.0 does not support FOREIGN KEY constraints(#18209).
  • TiDB before v6.2.0 does not support SAVEPOINT(#6840).

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-tidb-4.2.1.tar.gz (17.6 kB view hashes)

Uploaded Source

Built Distribution

django_tidb-4.2.1-py3-none-any.whl (19.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page