From 2c4f2df515d4de825b4edcb26b2c1587ed7d126e Mon Sep 17 00:00:00 2001 From: github-actions Date: Wed, 23 Aug 2023 07:55:53 +0000 Subject: [PATCH] Preview PR https://github.com/pingcap/docs/pull/14544 and this preview is triggered from commit https://github.com/pingcap/docs/pull/14544/commits/1fbf497083ff04460fd573da3a3c723a82900579 --- .../develop/dev-guide-choose-driver-or-orm.md | 300 +++++++++++++++++ .../master/develop/dev-guide-insert-data.md | 303 ++++++++++++++++++ ...e-sample-application-python-mysqlclient.md | 26 +- 3 files changed, 623 insertions(+), 6 deletions(-) create mode 100644 markdown-pages/en/tidb/master/develop/dev-guide-choose-driver-or-orm.md create mode 100644 markdown-pages/en/tidb/master/develop/dev-guide-insert-data.md diff --git a/markdown-pages/en/tidb/master/develop/dev-guide-choose-driver-or-orm.md b/markdown-pages/en/tidb/master/develop/dev-guide-choose-driver-or-orm.md new file mode 100644 index 000000000..f3b216e10 --- /dev/null +++ b/markdown-pages/en/tidb/master/develop/dev-guide-choose-driver-or-orm.md @@ -0,0 +1,300 @@ +--- +title: Choose Driver or ORM +summary: Learn how to choose a driver or ORM framework to connect to TiDB. +--- + +# Choose Driver or ORM + +> **Note:** +> +> TiDB provides the following two support levels for drivers and ORMs: +> +> - **Full**: indicates that TiDB is compatible with most features of the tool and maintains compatibility with its newer versions. PingCAP will periodically conduct compatibility tests with the latest version of [Third-party tools supported by TiDB](/develop/dev-guide-third-party-support.md). +> - **Compatible**: indicates that because the corresponding third-party tool is adapted to MySQL and TiDB is highly compatible with the MySQL protocol, so TiDB can use most features of the tool. However, PingCAP has not completed a full test on all features of the tool, which might lead to some unexpected behaviors. +> +> For more information, refer to [Third-Party Tools Supported by TiDB](/develop/dev-guide-third-party-support.md). + +TiDB is highly compatible with the MySQL protocol but some features are incompatible with MySQL. For a full list of compatibility differences, see [MySQL Compatibility](/mysql-compatibility.md). + +## Java + +This section describes how to use drivers and ORM frameworks in Java. + +### Java drivers + + +
+ +Support level: **Full** + +You can follow the [MySQL documentation](https://dev.mysql.com/doc/connector-j/8.0/en/) to download and configure a Java JDBC driver. It is recommended to use MySQL Connector/J 8.0.33 or later with TiDB v6.3.0 and newer. + +> **Tip:** +> +> There is a [bug](https://bugs.mysql.com/bug.php?id=106252) in the Connector/J 8.0 versions before 8.0.32, which might cause threads to hang when using TiDB versions earlier than v6.3.0. To avoid this issue, it is recommended that you use either MySQL Connector/J 8.0.32 or a later version, or the TiDB JDBC (see the *TiDB-JDBC* tab). + +For an example of how to build a complete application, see [Build a simple CRUD app with TiDB and JDBC](/develop/dev-guide-sample-application-java-jdbc.md). + +
+
+ +Support level: **Full** + +[TiDB-JDBC](https://github.com/pingcap/mysql-connector-j) is a customized Java driver based on MySQL 8.0.29. Compiled based on MySQL official version 8.0.29, TiDB-JDBC fixes the bug of multi-parameter and multi-field EOF in the prepare mode in the original JDBC, and adds features such as automatic TiCDC snapshot maintenance and the SM3 authentication plugin. + +Using SM3-based authentication is only supported with the TiDB version of MySQL Connector/J. + +If you use Maven, add the following content to the `` section in the `pom.xml` file: + +```xml + + io.github.lastincisor + mysql-connector-java + 8.0.29-tidb-1.0.0 + +``` + +If you need to enable SM3 authentication, add the following content to the `` section in the `pom.xml` file: + +```xml + + io.github.lastincisor + mysql-connector-java + 8.0.29-tidb-1.0.0 + + + org.bouncycastle + bcprov-jdk15on + 1.67 + + + org.bouncycastle + bcpkix-jdk15on + 1.67 + +``` + +If you use Gradle, add the following content to `dependencies`: + +```gradle +implementation group: 'io.github.lastincisor', name: 'mysql-connector-java', version: '8.0.29-tidb-1.0.0' +implementation group: 'org.bouncycastle', name: 'bcprov-jdk15on', version: '1.67' +implementation group: 'org.bouncycastle', name: 'bcpkix-jdk15on', version: '1.67' +``` + +
+ + +### Java ORM frameworks + +> **Note:** +> +> - Currently, Hibernate does [not support nested transactions](https://stackoverflow.com/questions/37927208/nested-transaction-in-spring-app-with-jpa-postgres). +> +> - Since v6.2.0, TiDB supports [savepoint](/sql-statements/sql-statement-savepoint.md). To use the `Propagation.NESTED` transaction propagation option in `@Transactional`, that is, to set `@Transactional(propagation = Propagation.NESTED)`, make sure that your TiDB is v6.2.0 or later. + + +
+ +Support level: **Full** + +To avoid manually managing complex relationships between different dependencies of an application, you can use [Gradle](https://gradle.org/install) or [Maven](https://maven.apache.org/install.html) to get all dependencies of your application, including those indirect ones. Note that only Hibernate `6.0.0.Beta2` or above supports the TiDB dialect. + +If you are using **Maven**, add the following to your ``: + +```xml + + org.hibernate.orm + hibernate-core + 6.0.0.CR2 + + + + mysql + mysql-connector-java + 5.1.49 + +``` + +If you are using **Gradle**, add the following to your `dependencies`: + +```gradle +implementation 'org.hibernate:hibernate-core:6.0.0.CR2' +implementation 'mysql:mysql-connector-java:5.1.49' +``` + +- For an example of using Hibernate to build a TiDB application by native Java, see [Build a simple CRUD app with TiDB and Hibernate](/develop/dev-guide-sample-application-java-hibernate.md). +- For an example of using Spring Data JPA or Hibernate to build a TiDB application by Spring, see [Build a TiDB app using Spring Boot](/develop/dev-guide-sample-application-java-spring-boot.md). + +In addition, you need to specify the TiDB dialect in your [Hibernate configuration file](https://www.tutorialspoint.com/hibernate/hibernate_configuration.htm): `org.hibernate.dialect.TiDBDialect`, which is only supported by Hibernate `6.0.0.Beta2` or above. If your `Hibernate` version is earlier than `6.0.0.Beta2`, upgrade it first. + +> **Note:** +> +> If you are unable to upgrade your `Hibernate` version, use the MySQL 5.7 dialect `org.hibernate.dialect.MySQL57Dialect` instead. However, this setting might cause unpredictable results and the absence of some TiDB-specific features, such as [sequences](/sql-statements/sql-statement-create-sequence.md). + +
+ +
+ +Support level: **Full** + +To avoid manually managing complex relationships between different dependencies of an application, you can use [Gradle](https://gradle.org/install) or [Maven](https://maven.apache.org/install.html) to get all dependencies of your application, including those indirect dependencies. + +If you are using Maven, add the following to your ``: + +```xml + + org.mybatis + mybatis + 3.5.9 + + + + mysql + mysql-connector-java + 5.1.49 + +``` + +If you are using Gradle, add the following to your `dependencies`: + +```gradle +implementation 'org.mybatis:mybatis:3.5.9' +implementation 'mysql:mysql-connector-java:5.1.49' +``` + +For an example of using MyBatis to build a TiDB application, see [Build a simple CRUD app with TiDB and MyBatis](/develop/dev-guide-sample-application-java-mybatis.md). + +
+ + + +### Java client load balancing + +**tidb-loadbalance** + +Support level: **Full** + +[tidb-loadbalance](https://github.com/pingcap/tidb-loadbalance) is a load balancing component on the application side. With tidb-loadbalance, you can automatically maintain the node information of TiDB server and distribute JDBC connections on the client using the tidb-loadbalance policies. Using a direct JDBC connection between the client application and TiDB server has higher performance than using the load balancing component. + +Currently, tidb-loadbalance supports the following policies: roundrobin, random, and weight. + +> **Note:** +> +> tidb-loadbalance must be used with [mysql-connector-j](https://github.com/pingcap/mysql-connector-j). + +If you use Maven, add the following content to the element body of `` in the `pom.xml` file: + +```xml + + io.github.lastincisor + mysql-connector-java + 8.0.29-tidb-1.0.0 + + + io.github.lastincisor + tidb-loadbalance + 0.0.5 + +``` + +If you use Gradle, add the following content to `dependencies`: + +```gradle +implementation group: 'io.github.lastincisor', name: 'mysql-connector-java', version: '8.0.29-tidb-1.0.0' +implementation group: 'io.github.lastincisor', name: 'tidb-loadbalance', version: '0.0.5' +``` + +## Golang + +This section describes how to use drivers and ORM frameworks in Golang. + +### Golang drivers + +**go-sql-driver/mysql** + +Support level: **Full** + +To download and configure a Golang driver, refer to the [go-sql-driver/mysql documentation](https://github.com/go-sql-driver/mysql). + +For an example of how to build a complete application, see [Build a simple CRUD app with TiDB and Go-MySQL-Driver](/develop/dev-guide-sample-application-golang-sql-driver.md). + +### Golang ORM frameworks + +**GORM** + +Support level: **Full** + +GORM is a popular ORM framework for Golang. To get all dependencies in your application, you can use the `go get` command. + +```shell +go get -u gorm.io/gorm +go get -u gorm.io/driver/mysql +``` + +For an example of using GORM to build a TiDB application, see [Build a simple CRUD app with TiDB and GORM](/develop/dev-guide-sample-application-golang-gorm.md). + +## Python + +This section describes how to use drivers and ORM frameworks in Python. + +### Python drivers + + +
+ +Support level: **Compatible** + +You can follow the [PyMySQL documentation](https://pypi.org/project/PyMySQL/) to download and configure the driver. It is recommended to use PyMySQL 1.0.2 or later versions. + +For an example of using PyMySQL to build a TiDB application, see [Build a simple CRUD app with TiDB and PyMySQL](/develop/dev-guide-sample-application-python-pymysql.md#step-2-get-the-code). + +
+
+ +Support level: **Compatible** + +You can follow the [mysqlclient documentation](https://pypi.org/project/mysqlclient/) to download and configure the driver. It is recommended to use mysqlclient 2.1.1 or later versions. + +For an example of using mysqlclient to build a TiDB application, see [Connect TiDB with mysqlclient](/develop/dev-guide-sample-application-python-mysqlclient.md). + +
+
+ +Support level: **Compatible** + +You can follow the [MySQL Connector/Python documentation](https://dev.mysql.com/doc/connector-python/en/connector-python-installation-binary.html) to download and configure the driver. It is recommended to use Connector/Python 8.0.31 or later versions. + +For an example of using MySQL Connector/Python to build a TiDB application, see [Build a simple CRUD app with TiDB and MySQL Connector/Python](/develop/dev-guide-sample-application-python-mysql-connector.md#step-2-get-the-code). + +
+ + +### Python ORM frameworks + + +
+ +Support level: **Full** + +[SQLAlchemy](https://www.sqlalchemy.org/) is a popular ORM framework for Python. To get all dependencies in your application, you can use the `pip install SQLAlchemy==1.4.44` command. It is recommended to use SQLAlchemy 1.4.44 or later versions. + +For an example of using SQLAlchemy to build a TiDB application, see [Build a simple CRUD app with TiDB and SQLAlchemy](/develop/dev-guide-sample-application-python-sqlalchemy.md#step-2-get-the-code). + +
+
+ +Support level: **Compatible** + +[peewee](http://docs.peewee-orm.com/en/latest/) is a popular ORM framework for Python. To get all dependencies in your application, you can use the `pip install peewee==3.15.4` command. It is recommended to use peewee 3.15.4 or later versions. + +For an example of using peewee to build a TiDB application, see [Build a simple CRUD app with TiDB and peewee](/develop/dev-guide-sample-application-python-peewee.md#step-2-get-the-code). + +
+ + + + +After you have determined the driver or ORM, you can [connect to your TiDB cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + + diff --git a/markdown-pages/en/tidb/master/develop/dev-guide-insert-data.md b/markdown-pages/en/tidb/master/develop/dev-guide-insert-data.md new file mode 100644 index 000000000..ef869a49d --- /dev/null +++ b/markdown-pages/en/tidb/master/develop/dev-guide-insert-data.md @@ -0,0 +1,303 @@ +--- +title: Insert Data +summary: Learn about how to insert data. +--- + + + +# Insert Data + +This document describes how to insert data into TiDB by using the SQL language with different programming languages. + +## Before you start + +Before reading this document, you need to prepare the following: + +- [Build a TiDB Serverless Cluster](/develop/dev-guide-build-cluster-in-cloud.md). +- Read [Schema Design Overview](/develop/dev-guide-schema-design-overview.md), [Create a Database](/develop/dev-guide-create-database.md), [Create a Table](/develop/dev-guide-create-table.md), and [Create Secondary Indexes](/develop/dev-guide-create-secondary-indexes.md) + +## Insert rows + +There are two ways to insert multiple rows of data. For example, if you need to insert **3** players' data. + +- A **multi-line insertion statement**: + + {{< copyable "sql" >}} + + ```sql + INSERT INTO `player` (`id`, `coins`, `goods`) VALUES (1, 1000, 1), (2, 230, 2), (3, 300, 5); + ``` + +- Multiple **single-line insertion statements**: + + {{< copyable "sql" >}} + + ```sql + INSERT INTO `player` (`id`, `coins`, `goods`) VALUES (1, 1000, 1); + INSERT INTO `player` (`id`, `coins`, `goods`) VALUES (2, 230, 2); + INSERT INTO `player` (`id`, `coins`, `goods`) VALUES (3, 300, 5); + ``` + +Generally the `multi-line insertion statement` runs faster than the multiple `single-line insertion statements`. + + +
+ +```sql +CREATE TABLE `player` (`id` INT, `coins` INT, `goods` INT); +INSERT INTO `player` (`id`, `coins`, `goods`) VALUES (1, 1000, 1), (2, 230, 2); +``` + +For more information on how to use this SQL, see [Connecting to a TiDB Cluster](/develop/dev-guide-build-cluster-in-cloud.md#step-2-connect-to-a-cluster) and follow the steps to enter the SQL statement after connecting to a TiDB cluster using a client. + +
+ +
+ +```java +// ds is an entity of com.mysql.cj.jdbc.MysqlDataSource +try (Connection connection = ds.getConnection()) { + connection.setAutoCommit(false); + + PreparedStatement pstmt = connection.prepareStatement("INSERT INTO player (id, coins, goods) VALUES (?, ?, ?)")) + + // first player + pstmt.setInt(1, 1); + pstmt.setInt(2, 1000); + pstmt.setInt(3, 1); + pstmt.addBatch(); + + // second player + pstmt.setInt(1, 2); + pstmt.setInt(2, 230); + pstmt.setInt(3, 2); + pstmt.addBatch(); + + pstmt.executeBatch(); + connection.commit(); +} catch (SQLException e) { + e.printStackTrace(); +} +``` + +Due to the default MySQL JDBC Driver settings, you need to change some parameters to get better bulk insert performance. + +| Parameter | Means | Recommended Scenario | Recommended Configuration| +| :------------------------: | :-----------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------: | +| `useServerPrepStmts` | Whether to use the server side to enable prepared statements | When you need to use a prepared statement more than once | `true` | +| `cachePrepStmts` | Whether the client caches prepared statements | `useServerPrepStmts=true` 时 | `true` | +| `prepStmtCacheSqlLimit` | Maximum size of a prepared statement (256 characters by default) | When the prepared statement is greater than 256 characters | Configured according to the actual size of the prepared statement | +| `prepStmtCacheSize` | Maximum number of prepared statement caches (25 by default) | When the number of prepared statements is greater than 25 | Configured according to the actual number of prepared statements | +| `rewriteBatchedStatements` | Whether to rewrite **Batched** statements | When batch operations are required | `true` | +| `allowMultiQueries` | Start batch operations | Because a [client bug](https://bugs.mysql.com/bug.php?id=96623) requires this to be set when `rewriteBatchedStatements = true` and `useServerPrepStmts = true` | `true` | + +MySQL JDBC Driver also provides an integrated configuration: `useConfigs`. When it is configured with `maxPerformance`, it is equivalent to configuring a set of configurations. Taking `mysql:mysql-connector-java:8.0.28` as an example, `useConfigs=maxPerformance` contains: + +```properties +cachePrepStmts=true +cacheCallableStmts=true +cacheServerConfiguration=true +useLocalSessionState=true +elideSetAutoCommits=true +alwaysSendSetIsolation=false +enableQueryTimeouts=false +connectionAttributes=none +useInformationSchema=true +``` + +You can check `mysql-connector-java-{version}.jar!/com/mysql/cj/configurations/maxPerformance.properties` to get the configurations contained in `useConfigs=maxPerformance` for the corresponding version of MySQL JDBC Driver. + +The following is a typical scenario of JDBC connection string configurations. In this example, Host: `127.0.0.1`, Port: `4000`, User name: `root`, Password: null, Default database: `test`: + +``` +jdbc:mysql://127.0.0.1:4000/test?user=root&useConfigs=maxPerformance&useServerPrepStmts=true&prepStmtCacheSqlLimit=2048&prepStmtCacheSize=256&rewriteBatchedStatements=true&allowMultiQueries=true +``` + +For complete examples in Java, see: + +- [Build a simple CRUD app with TiDB and JDBC](/develop/dev-guide-sample-application-java-jdbc.md#step-2-get-the-code) +- [Build a simple CRUD app with TiDB and Hibernate](/develop/dev-guide-sample-application-java-hibernate.md#step-2-get-the-code) +- [Build the TiDB app using Spring Boot](/develop/dev-guide-sample-application-java-spring-boot.md) + +
+ +
+ +```go +package main + +import ( + "database/sql" + "strings" + + _ "github.com/go-sql-driver/mysql" +) + +type Player struct { + ID string + Coins int + Goods int +} + +func bulkInsertPlayers(db *sql.DB, players []Player, batchSize int) error { + tx, err := db.Begin() + if err != nil { + return err + } + + stmt, err := tx.Prepare(buildBulkInsertSQL(batchSize)) + if err != nil { + return err + } + + defer stmt.Close() + + for len(players) > batchSize { + if _, err := stmt.Exec(playerToArgs(players[:batchSize])...); err != nil { + tx.Rollback() + return err + } + + players = players[batchSize:] + } + + if len(players) != 0 { + if _, err := tx.Exec(buildBulkInsertSQL(len(players)), playerToArgs(players)...); err != nil { + tx.Rollback() + return err + } + } + + if err := tx.Commit(); err != nil { + tx.Rollback() + return err + } + + return nil +} + +func playerToArgs(players []Player) []interface{} { + var args []interface{} + for _, player := range players { + args = append(args, player.ID, player.Coins, player.Goods) + } + return args +} + +func buildBulkInsertSQL(amount int) string { + return "INSERT INTO player (id, coins, goods) VALUES (?, ?, ?)" + strings.Repeat(",(?,?,?)", amount-1) +} +``` + +For complete examples in Golang, see: + +- [Use Go-MySQL-Driver to build a simple CRUD app with TiDB and Golang](/develop/dev-guide-sample-application-golang-sql-driver.md#step-2-get-the-code) +- [Use GORM to build a simple CRUD app with TiDB and Golang](/develop/dev-guide-sample-application-golang-gorm.md#step-2-get-the-code) + +
+ +
+ +```python +import MySQLdb +connection = MySQLdb.connect( + host="127.0.0.1", + port=4000, + user="root", + password="", + database="bookshop", + autocommit=True +) + +with get_connection(autocommit=True) as connection: + with connection.cursor() as cur: + player_list = random_player(1919) + for idx in range(0, len(player_list), 114): + cur.executemany("INSERT INTO player (id, coins, goods) VALUES (%s, %s, %s)", player_list[idx:idx + 114]) +``` + +For complete examples in Python, see: + +- [Use PyMySQL to build a simple CRUD app with TiDB and Python](/develop/dev-guide-sample-application-python-pymysql.md#step-2-get-the-code) +- [Use MySQL Connector/Python to build a simple CRUD app with TiDB and Python](/develop/dev-guide-sample-application-python-mysql-connector.md#step-2-get-the-code) +- [Use SQLAlchemy to build a simple CRUD app with TiDB and Python](/develop/dev-guide-sample-application-python-sqlalchemy.md#step-2-get-the-code) +- [Use peewee to build a simple CRUD app with TiDB and Python](/develop/dev-guide-sample-application-python-peewee.md#step-2-get-the-code) + +
+ + + +## Bulk-Insert + +If you need to quickly import a large amount of data into a TiDB cluster, it is recommended that you use a range of tools provided by **PingCAP** for data migration. Using the `INSERT` statement is not the best way, because it is not efficient and requires to handle exceptions and other issues on your own. + +The following are the recommended tools for bulk-insert: + +- Data export: [Dumpling](/dumpling-overview.md). You can export MySQL or TiDB data to local or Amazon S3. + + + +- Data import: [TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md). You can import **Dumpling** exported data, a **CSV** file, or [Migrate Data from Amazon Aurora to TiDB](/migrate-aurora-to-tidb.md). It also supports reading data from a local disk or Amazon S3 cloud disk. +- Data replication: [TiDB Data Migration](/dm/dm-overview.md). You can replicate MySQL, MariaDB, and Amazon Aurora databases to TiDB. It also supports merging and migrating the sharded instances and tables from the source databases. +- Data backup and restore: [Backup & Restore (BR)](/br/backup-and-restore-overview.md). Compared to **Dumpling**, **BR** is more suitable for **_big data_** scenario. + + + + + +- Data import: [Data Import Task](/tidb-cloud/import-sample-data.md) page in the TiDB Cloud console. You can import **Dumpling** exported data, a **CSV** file, or [Migrate Data from Amazon Aurora to TiDB](/tidb-cloud/migrate-from-aurora-bulk-import.md). It also supports reading data from a local disk, Amazon S3 cloud disk, or GCS cloud disk. +- Data replication: [TiDB Data Migration](https://docs.pingcap.com/tidb/stable/dm-overview). You can replicate MySQL, MariaDB, and Amazon Aurora databases to TiDB. It also supports merging and migrating the sharded instances and tables from the source databases. +- Data backup and restore: [Backup](/tidb-cloud/backup-and-restore.md) page in the TiDB Cloud console. Compared to **Dumpling**, backup and restore is more suitable for **_big data_** scenario. + + + +## Avoid hotspots + +When designing a table, you need to consider if there is a large number of insert operations. If so, you need to avoid hotspots during table design. See the [Select primary key](/develop/dev-guide-create-table.md#select-primary-key) section and follow the [Rules when selecting primary key](/develop/dev-guide-create-table.md#guidelines-to-follow-when-selecting-primary-key). + + + +For more information on how to handle hotspot issues, see [Troubleshoot Hotspot Issues](/troubleshoot-hot-spot-issues.md). + + + +## Insert data to a table with the `AUTO_RANDOM` primary key + +If the primary key of the table you insert has the `AUTO_RANDOM` attribute, then by default the primary key cannot be specified. For example, in the [`bookshop`](/develop/dev-guide-bookshop-schema-design.md) database, you can see that the `id` field of the [`users` table](/develop/dev-guide-bookshop-schema-design.md#users-table) contains the `AUTO_RANDOM` attribute. + +In this case, you **cannot** use SQL like the following to insert: + +```sql +INSERT INTO `bookshop`.`users` (`id`, `balance`, `nickname`) VALUES (1, 0.00, 'nicky'); +``` + +An error will occur: + +``` +ERROR 8216 (HY000): Invalid auto random: Explicit insertion on auto_random column is disabled. Try to set @@allow_auto_random_explicit_insert = true. +``` + +It is not recommended to manually specify the `AUTO_RANDOM` column during insertion time. + +There are two solutions to handle this error: + +- (Recommended) Remove this column from the insert statement and use the `AUTO_RANDOM` value that TiDB initialized for you. This fits the semantics of `AUTO_RANDOM`. + + {{< copyable "sql" >}} + + ```sql + INSERT INTO `bookshop`.`users` (`balance`, `nickname`) VALUES (0.00, 'nicky'); + ``` + +- If you are sure that you **_must_** specify this column, then you can use the [`SET` statement](https://docs.pingcap.com/zh/tidb/stable/sql-statement-set-variable) to allow the column of `AUTO_RANDOM` to be specified during insertion time by changing the user variable. + + {{< copyable "sql" >}} + + ```sql + SET @@allow_auto_random_explicit_insert = true; + INSERT INTO `bookshop`.`users` (`id`, `balance`, `nickname`) VALUES (1, 0.00, 'nicky'); + ``` + +## Use HTAP + +In TiDB, HTAP capabilities save you from performing additional operations when inserting data. There is no additional insertion logic. TiDB automatically guarantees data consistency. All you need to do is [turn on column-oriented replica synchronization](/develop/dev-guide-create-table.md#use-htap-capabilities) after creating the table, and use the column-oriented replica to speed up your queries directly. diff --git a/markdown-pages/en/tidb/master/develop/dev-guide-sample-application-python-mysqlclient.md b/markdown-pages/en/tidb/master/develop/dev-guide-sample-application-python-mysqlclient.md index 2e9beda8d..962b87081 100644 --- a/markdown-pages/en/tidb/master/develop/dev-guide-sample-application-python-mysqlclient.md +++ b/markdown-pages/en/tidb/master/develop/dev-guide-sample-application-python-mysqlclient.md @@ -17,6 +17,7 @@ In this tutorial, use TiDB and mysqlclient to complete the following tasks: - Build and run your app. Optionally, you can find sample code snippets for basic CRUD operations. > **Note:** +> > This tutorial works with TiDB Serverless, TiDB Dedicated and TiDB Self-Hosted. ## Prerequisites @@ -27,10 +28,22 @@ To complete this tutorial, you need: - [Git](https://git-scm.com/downloads). - A TiDB cluster. + + +**If you don't have a TiDB cluster, you can create one as follows:** + +- (Recommended) Follow [Creating a TiDB Serverless Cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud cluster. +- Follow [Deploy a Local Test TiDB Cluster](/quick-start-with-tidb.md#deploy-a-local-test-cluster) or [Deploy a Production TiDB Cluster](/production-deployment-using-tiup.md) to create a local cluster. + + + + **If you don't have a TiDB cluster, you can create one as follows:** - (Recommended) Follow [Creating a TiDB Serverless Cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud cluster. -- Follow [Deploy a Local Test TiDB Cluster](/quick-start-with-tidb.md#deploy-a-local-test-cluster.md) or [Deploy a Production TiDB Cluster](/production-deployment-using-tiup.md) to create a local cluster. +- Follow [Deploy a Local Test TiDB Cluster](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster) or [Deploy a Production TiDB Cluster](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) to create a local cluster. + + ## Run sample app to connect to TiDB @@ -53,7 +66,7 @@ Run the following commands to install required packages for the sample app. pip install -r requirements.txt ``` - If you encounter installation issues, please refer to the [mysqlclient official documentation](https://github.com/PyMySQL/mysqlclient#install). +If you encounter installation issues, please refer to the [mysqlclient official documentation](https://github.com/PyMySQL/mysqlclient#install). ### Step 3: Configure connection information @@ -74,7 +87,7 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele 3. Click **Create password** to create a random password. - If you have created a password before, you can either use the original password or click **Reset password** to generate a new one. + If you have created a password before, you can either use the original password or click "Reset password" to generate a new one. 4. Run the following command to copy `.env.example` and rename it to `.env`: @@ -95,7 +108,7 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele Be sure to replace the placeholders `{}` with the values obtained from the connection dialog. - TiDB Serverless requires a secure connection. Since the `ssl_mode` of mysqlclient defaults to `PREFERRED`, you don't need to manually specify `CA_PATH`. Just leave it empty. But if you have a special reason to specify `CA_PATH` manually, you can refer to the [TLS Connections to TiDB Serverless](/tidb-cloud/secure-connections-to-serverless-tier-clusters.md) to get the certificate paths for different operating systems. + TiDB Serverless requires a secure connection. Since the `ssl_mode` of mysqlclient defaults to `PREFERRED`, you don't need to manually specify `CA_PATH`. Just leave it empty. But if you have a special reason to specify `CA_PATH` manually, you can refer to the [TLS Connections to TiDB Serverless](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-clusters) to get the certificate paths for different operating systems. 6. Save the `.env` file. @@ -103,7 +116,8 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele
1. In the TiDB Cloud, select your TiDB Dedicated cluster. Go to the **Overview** page, and click the **Connect** button in the upper right corner. Click **Allow Access from Anywhere** and then click **Download TiDB cluster CA** to download the certificate. - For more configuration details, refer to [TiDB Dedicated Standard Connection](/tidb-cloud/connect-via-standard-connection.md). + + For more configuration details, refer to [TiDB Dedicated Standard Connection](https://docs.pingcap.com/tidbcloud/connect-via-standard-connection). 2. Run the following command to copy `.env.example` and rename it to `.env`: @@ -156,7 +170,7 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele You can refer to the following sample code snippets to complete your own application development. -For complete code and how to run it, see the [tidb-python-mysqlclient-quickstart GitHub repository](https://github.com/tidb-samples/tidb-python-mysqlclient-quickstart). +For complete code and how to run it, see the [tidb-python-mysqlclient-quickstart GitHub repository](https://github.com/tidb-samples/tidb-python-mysqlclient-quickstart). ### Connect to TiDB