Package: django-tidb
TiDB dialect for DjangoThis adds compatibility forTiDBto Django.Installation GuidePrerequisitesBefore installing django-tidb, ensure you have a MySQL driver installed. You can choose eithermysqlclient(recommended) orpymysql(at your own risk).Install mysqlclient (Recommended)Please refer to themysqlclient official guideInstall pymysql (At your own risk)django-tidb has not been tested with pymysqlpipinstallpymysqlThen add the following code at the beginning of your Django'ssettings.py:importpymysqlpymysql.install_as_MySQLdb()Installing django-tidbTo 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.djangodjango-tidbinstall commandv4.2.xv4.2.xpip install 'django-tidb>=4.2.0,<4.3.0'v4.1.xv4.1.xpip install 'django-tidb>=4.1.0,<4.2.0'v3.2.xv3.2.xpip install 'django-tidb>=3.2.0,<3.3.0'UsageSet'ENGINE': 'django_tidb'in your settings to this:DATABASES={'default':{'ENGINE':'django_tidb','NAME':'django','USER':'root','PASSWORD':'','HOST':'127.0.0.1','PORT':4000,},}DEFAULT_AUTO_FIELD='django.db.models.AutoField'USE_TZ=FalseSECRET_KEY='django_tests_secret_key'UsingAUTO_RANDOMAUTO_RANDOMis a feature in TiDB that generates unique IDs for a table automatically. It is similar toAUTO_INCREMENT, but it can avoid write hotspot in a single storage node caused by TiDB assigning consecutive IDs. It also have some restrictions, please refer to thedocumentation.To useAUTO_RANDOMin Django, you can do it by following two ways:Declare globally insettings.pyas shown below, it will affect all models:DEFAULT_AUTO_FIELD='django_tidb.fields.BigAutoRandomField'Manually declare it in the model as shown below:fromdjango_tidb.fieldsimportBigAutoRandomFieldclassMyModel(models.Model):id=BigAutoRandomField(primary_key=True)title=models.CharField(max_length=200)BigAutoRandomFieldis a subclass ofBigAutoField, it can only be used for primary key and its behavior can be controlled by setting the parametersshard_bitsandrange. For detailed information, please refer to thedocumentation.Migrate fromAUTO_INCREMENTtoAUTO_RANDOM:Check if the original column isBigAutoField(bigint), if not, migrate it toBigAutoField(bigint)first.In the database configuration (settings.py), defineSET @@tidb_allow_remove_auto_inc = ONin theinit_command. You can remove it after completing the migration.# settings.pyDATABASES={'default':{'ENGINE':'django_tidb',...'OPTIONS':{'init_command':'SET @@tidb_allow_remove_auto_inc = ON',}}}Finnaly, migrate it toBigAutoRandomField(bigint).NoteAUTO_RANDOMis supported after TiDB v3.1.0, and only support define withrangeafter v6.3.0, sorangewill be ignored if TiDB version is lower than v6.3.0UsingAUTO_ID_CACHEAUTO_ID_CACHEallow users to set the cache size for allocating the auto-increment ID, as you may know, TiDB guarantees that AUTO_INCREMENT values are monotonic (always increasing) on a per-server basis, but its value may appear to jump dramatically if an INSERT operation is performed against another TiDB Server, This is caused by the fact that each server has its own cache which is controlled byAUTO_ID_CACHE. But from TiDB v6.4.0, it introduces a centralized auto-increment ID allocating service, you can enableMySQL compatibility modeby setAUTO_ID_CACHEto1when creating a table without losing performance.To useAUTO_ID_CACHEin Django, you can specifytidb_auto_id_cachein the model'sMetaclass as shown below when creating a new table:classMyModel(models.Model):title=models.CharField(max_length=200)classMeta:tidb_auto_id_cache=1But there are some limitations:tidb_auto_id_cachecan only affect the table creation, after that it will be ignored even if you change it.tidb_auto_id_cacheonly affects theAUTO_INCREMENTcolumn.Supported versionsTiDB 4.0 and newerDjango 3.2, 4.1 and 4.2Python 3.6 and newer(must match Django's Python version requirement)Testcreate your virtualenv with:$virtualenvvenv
$sourcevenv/bin/activateyou can use the commanddeactivateto exit from the virtual environment.run all integration tests.$DJANGO_VERSION=3.2.12pythonrun_testing_worker.pyMigrate from previous versionsReleases on PyPi before 3.0.0 are published from repositoryhttps://github.com/blacktear23/django_tidb. 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 isdjango_tidbinstead ofdjango_tidb.tidb.Known issuesTiDB before v6.6.0 does not support FOREIGN KEY constraints(#18209).TiDB before v6.2.0 does not support SAVEPOINT(#6840).