diff --git a/benchmark/benchmark-sysbench-v5-vs-v4.md b/benchmark/benchmark-sysbench-v5-vs-v4.md new file mode 100644 index 0000000000000..87900a3a21222 --- /dev/null +++ b/benchmark/benchmark-sysbench-v5-vs-v4.md @@ -0,0 +1,223 @@ +--- +title: TiDB Sysbench Performance Test Report -- v5.0 vs. v4.0 +summary: TiDB v5.0 outperforms v4.0 in Sysbench performance tests. Point Select performance improved by 2.7%, Update Non-index by 81%, Update Index by 28%, and Read Write by 9%. The test aimed to compare performance in the OLTP scenario using AWS EC2. Test results were presented in tables and graphs. +--- + +# TiDB Sysbench Performance Test Report -- v5.0 vs. v4.0 + +## Test purpose + +This test aims at comparing the Sysbench performance of TiDB v5.0 and TiDB v4.0 in the Online Transactional Processing (OLTP) scenario. + +## Test environment (AWS EC2） + +### Hardware configuration + +| Service type | EC2 type | Instance count | +|:----------|:----------|:----------| +| PD | m5.xlarge | 3 | +| TiKV | i3.4xlarge| 3 | +| TiDB | c5.4xlarge| 3 | +| Sysbench | c5.9xlarge| 1 | + +### Software version + +| Service type | Software version | +|:----------|:-----------| +| PD | 4.0 and 5.0 | +| TiDB | 4.0 and 5.0 | +| TiKV | 4.0 and 5.0 | +| Sysbench | 1.0.20 | + +### Parameter configuration + +#### TiDB v4.0 configuration + +{{< copyable "" >}} + +```yaml +log.level: "error" +performance.max-procs: 20 +prepared-plan-cache.enabled: true +tikv-client.max-batch-wait-time: 2000000 +``` + +#### TiKV v4.0 configuration + +{{< copyable "" >}} + +```yaml +storage.scheduler-worker-pool-size: 5 +raftstore.store-pool-size: 3 +raftstore.apply-pool-size: 3 +rocksdb.max-background-jobs: 3 +raftdb.max-background-jobs: 3 +raftdb.allow-concurrent-memtable-write: true +server.grpc-concurrency: 6 +readpool.unified.min-thread-count: 5 +readpool.unified.max-thread-count: 20 +readpool.storage.normal-concurrency: 10 +pessimistic-txn.pipelined: true +``` + +#### TiDB v5.0 configuration + +{{< copyable "" >}} + +```yaml +log.level: "error" +performance.max-procs: 20 +prepared-plan-cache.enabled: true +tikv-client.max-batch-wait-time: 2000000 +``` + +#### TiKV v5.0 configuration + +{{< copyable "" >}} + +```yaml +storage.scheduler-worker-pool-size: 5 +raftstore.store-pool-size: 3 +raftstore.apply-pool-size: 3 +rocksdb.max-background-jobs: 8 +raftdb.max-background-jobs: 4 +raftdb.allow-concurrent-memtable-write: true +server.grpc-concurrency: 6 +readpool.unified.min-thread-count: 5 +readpool.unified.max-thread-count: 20 +readpool.storage.normal-concurrency: 10 +pessimistic-txn.pipelined: true +server.enable-request-batch: false +``` + +#### TiDB v4.0 global variable configuration + +{{< copyable "sql" >}} + +```sql +set global tidb_hashagg_final_concurrency=1; +set global tidb_hashagg_partial_concurrency=1; +``` + +#### TiDB v5.0 global variable configuration + +{{< copyable "sql" >}} + +```sql +set global tidb_hashagg_final_concurrency=1; +set global tidb_hashagg_partial_concurrency=1; +set global tidb_enable_async_commit = 1; +set global tidb_enable_1pc = 1; +set global tidb_guarantee_linearizability = 0; +set global tidb_enable_clustered_index = 1; + +``` + +## Test plan + +1. Deploy TiDB v5.0 and v4.0 using TiUP. +2. Use Sysbench to import 16 tables, each table with 10 million rows of data. +3. Execute the `analyze table` statement on each table. +4. Back up the data used for restore before different concurrency tests, which ensures data consistency for each test. +5. Start the Sysbench client to perform the `point_select`, `read_write`, `update_index`, and `update_non_index` tests. Perform stress tests on TiDB via AWS NLB. In each type of test, the warm-up takes 1 minute and the test takes 5 minutes. +6. After each type of test is completed, stop the cluster, overwrite the cluster with the backup data in step 4, and restart the cluster. + +### Prepare test data + +Execute the following command to prepare the test data: + +{{< copyable "shell-regular" >}} + +```bash +sysbench oltp_common \ + --threads=16 \ + --rand-type=uniform \ + --db-driver=mysql \ + --mysql-db=sbtest \ + --mysql-host=$aws_nlb_host \ + --mysql-port=$aws_nlb_port \ + --mysql-user=root \ + --mysql-password=password \ + prepare --tables=16 --table-size=10000000 +``` + +### Perform the test + +Execute the following command to perform the test. + +{{< copyable "shell-regular" >}} + +```bash +sysbench $testname \ + --threads=$threads \ + --time=300 \ + --report-interval=1 \ + --rand-type=uniform \ + --db-driver=mysql \ + --mysql-db=sbtest \ + --mysql-host=$aws_nlb_host \ + --mysql-port=$aws_nlb_port \ + run --tables=16 --table-size=10000000 +``` + +## Test results + +### Point Select performance + +| Threads | v4.0 QPS | v4.0 95% latency (ms) | v5.0 QPS | v5.0 95% latency (ms) | QPS improvement | +|:----------|:----------|:----------|:----------|:----------|:----------| +| 150 | 159451.19 | 1.32 | 177876.25 | 1.23 | 11.56% | +| 300 | 244790.38 | 1.96 | 252675.03 | 1.82 | 3.22% | +| 600 | 322929.05 | 3.75 | 331956.84 | 3.36 | 2.80% | +| 900 | 364840.05 | 5.67 | 365655.04 | 5.09 | 0.22% | +| 1200 | 376529.18 | 7.98 | 366507.47 | 7.04 | -2.66% | +| 1500 | 368390.52 | 10.84 | 372476.35 | 8.90 | 1.11% | + +Compared with v4.0, the Point Select performance of TiDB v5.0 has increased by 2.7%. + +![Point Select](/media/sysbench_v5vsv4_point_select.png) + +### Update Non-index performance + +| Threads | v4.0 QPS | v4.0 95% latency (ms) | v5.0 QPS | v5.0 95% latency (ms) | QPS improvement | +|:----------|:----------|:----------|:----------|:----------|:----------| +| 150 | 17243.78 | 11.04 | 30866.23 | 6.91 | 79.00% | +| 300 | 25397.06 | 15.83 | 45915.39 | 9.73 | 80.79% | +| 600 | 33388.08 | 25.28 | 60098.52 | 16.41 | 80.00% | +| 900 | 38291.75 | 36.89 | 70317.41 | 21.89 | 83.64% | +| 1200 | 41003.46 | 55.82 | 76376.22 | 28.67 | 86.27% | +| 1500 | 44702.84 | 62.19 | 80234.58 | 34.95 | 79.48% | + +Compared with v4.0, the Update Non-index performance of TiDB v5.0 has increased by 81%. + +![Update Non-index](/media/sysbench_v5vsv4_update_non_index.png) + +### Update Index performance + +| Threads | v4.0 QPS | v4.0 95% latency (ms) | v5.0 QPS | v5.0 95% latency (ms) | QPS improvement | +|:----------|:----------|:----------|:----------|:----------|:----------| +| 150 | 11736.21 | 17.01 | 15631.34 | 17.01 | 33.19% | +| 300 | 15435.95 | 28.67 | 19957.06 | 22.69 | 29.29% | +| 600 | 18983.21 | 49.21 | 23218.14 | 41.85 | 22.31% | +| 900 | 20855.29 | 74.46 | 26226.76 | 53.85 | 25.76% | +| 1200 | 21887.64 | 102.97 | 28505.41 | 69.29 | 30.24% | +| 1500 | 23621.15 | 110.66 | 30341.06 | 82.96 | 28.45% | + +Compared with v4.0, the Update Index performance of TiDB v5.0 has increased by 28%. + +![Update Index](/media/sysbench_v5vsv4_update_index.png) + +### Read Write performance + +| Threads | v4.0 QPS | v4.0 95% latency (ms) | v5.0 QPS | v5.0 95% latency (ms) | QPS improvement | +|:----------|:----------|:----------|:----------|:----------|:----------| +| 150 | 59979.91 | 61.08 | 66098.57 | 55.82 | 10.20% | +| 300 | 77118.32 | 102.97 | 84639.48 | 90.78 | 9.75% | +| 600 | 90619.52 | 183.21 | 101477.46 | 167.44 | 11.98% | +| 900 | 97085.57 | 267.41 | 109463.46 | 240.02 | 12.75% | +| 1200 | 106521.61 | 331.91 | 115416.05 | 320.17 | 8.35% | +| 1500 | 116278.96 | 363.18 | 118807.5 | 411.96 | 2.17% | + +Compared with v4.0, the read-write performance of TiDB v5.0 has increased by 9%. + +![Read Write](/media/sysbench_v5vsv4_read_write.png) diff --git a/benchmark/benchmark-sysbench-v5.1.0-vs-v5.0.2.md b/benchmark/benchmark-sysbench-v5.1.0-vs-v5.0.2.md new file mode 100644 index 0000000000000..a9d398939913f --- /dev/null +++ b/benchmark/benchmark-sysbench-v5.1.0-vs-v5.0.2.md @@ -0,0 +1,186 @@ +--- +title: TiDB Sysbench Performance Test Report -- v5.1.0 vs. v5.0.2 +summary: TiDB v5.1.0 shows a 19.4% improvement in Point Select performance compared to v5.0.2. However, the Read Write and Update Index performance is slightly reduced in v5.1.0. The test was conducted on AWS EC2 using Sysbench with specific hardware and software configurations. The test plan involved deploying, importing data, and performing stress tests. Overall, v5.1.0 demonstrates improved Point Select performance but reduced performance in other areas. +--- + +# TiDB Sysbench Performance Test Report -- v5.1.0 vs. v5.0.2 + +## Test overview + +This test aims at comparing the Sysbench performance of TiDB v5.1.0 and TiDB v5.0.2 in the Online Transactional Processing (OLTP) scenario. The results show that compared with v5.0.2, the Point Select performance of v5.1.0 is improved by 19.4%, and the performance of the Read Write and Update Index is slightly reduced. + +## Test environment (AWS EC2） + +### Hardware configuration + +| Service type | EC2 type | Instance count | +|:----------|:----------|:----------| +| PD | m5.xlarge | 3 | +| TiKV | i3.4xlarge| 3 | +| TiDB | c5.4xlarge| 3 | +| Sysbench | c5.9xlarge| 1 | + +### Software version + +| Service type | Software version | +|:----------|:-----------| +| PD | v5.0.2 and v5.1.0 | +| TiDB | v5.0.2 and v5.1.0 | +| TiKV | v5.0.2 and v5.1.0 | +| Sysbench | 1.0.20 | + +### Parameter configuration + +TiDB v5.1.0 and TiDB v5.0.2 use the same configuration. + +#### TiDB parameter configuration + +{{< copyable "" >}} + +```yaml +log.level: "error" +performance.max-procs: 20 +prepared-plan-cache.enabled: true +tikv-client.max-batch-wait-time: 2000000 +``` + +#### TiKV parameter configuration + +{{< copyable "" >}} + +```yaml +storage.scheduler-worker-pool-size: 5 +raftstore.store-pool-size: 3 +raftstore.apply-pool-size: 3 +rocksdb.max-background-jobs: 8 +raftdb.max-background-jobs: 4 +raftdb.allow-concurrent-memtable-write: true +server.grpc-concurrency: 6 +readpool.unified.min-thread-count: 5 +readpool.unified.max-thread-count: 20 +readpool.storage.normal-concurrency: 10 +pessimistic-txn.pipelined: true +server.enable-request-batch: false +``` + +#### TiDB global variable configuration + +{{< copyable "sql" >}} + +```sql +set global tidb_hashagg_final_concurrency=1; +set global tidb_hashagg_partial_concurrency=1; +set global tidb_enable_async_commit = 1; +set global tidb_enable_1pc = 1; +set global tidb_guarantee_linearizability = 0; +set global tidb_enable_clustered_index = 1; +``` + +## Test plan + +1. Deploy TiDB v5.1.0 and v5.0.2 using TiUP. +2. Use Sysbench to import 16 tables, each table with 10 million rows of data. +3. Execute the `analyze table` statement on each table. +4. Back up the data used for restore before different concurrency tests, which ensures data consistency for each test. +5. Start the Sysbench client to perform the `point_select`, `read_write`, `update_index`, and `update_non_index` tests. Perform stress tests on TiDB via HAProxy. The test takes 5 minutes. +6. After each type of test is completed, stop the cluster, overwrite the cluster with the backup data in step 4, and restart the cluster. + +### Prepare test data + +Execute the following command to prepare the test data: + +{{< copyable "shell-regular" >}} + +```bash +sysbench oltp_common \ + --threads=16 \ + --rand-type=uniform \ + --db-driver=mysql \ + --mysql-db=sbtest \ + --mysql-host=$aws_nlb_host \ + --mysql-port=$aws_nlb_port \ + --mysql-user=root \ + --mysql-password=password \ + prepare --tables=16 --table-size=10000000 +``` + +### Perform the test + +Execute the following command to perform the test: + +{{< copyable "shell-regular" >}} + +```bash +sysbench $testname \ + --threads=$threads \ + --time=300 \ + --report-interval=1 \ + --rand-type=uniform \ + --db-driver=mysql \ + --mysql-db=sbtest \ + --mysql-host=$aws_nlb_host \ + --mysql-port=$aws_nlb_port \ + run --tables=16 --table-size=10000000 +``` + +## Test results + +### Point Select performance + +| Threads | v5.0.2 QPS | v5.0.2 95% latency (ms) | v5.1.0 QPS | v5.1.0 95% latency (ms) | QPS improvement | +|:----------|:----------|:----------|:----------|:----------|:----------| +|150|137732.27|1.86|158861.67|2|15.34%| +|300|201420.58|2.91|238038.44|2.71|18.18%| +|600|303631.52|3.49|428573.21|2.07|41.15%| +|900|383628.13|3.55|464863.22|3.89|21.18%| +|1200|391451.54|5.28|413656.74|13.46|5.67%| +|1500|410276.93|7.43|471418.78|10.65|14.90%| + +Compared with v5.0.2, the Point Select performance of v5.1.0 is improved by 19.4%. + +![Point Select](/media/sysbench_v510vsv502_point_select.png) + +### Update Non-index performance + +| Threads | v5.0.2 QPS | v5.0.2 95% latency (ms) | v5.1.0 QPS | v5.1.0 95% latency (ms) | QPS improvement | +|:----------|:----------|:----------|:----------|:----------|:----------| +|150|29248.2|7.17|29362.7|8.13|0.39%| +|300|40316.09|12.52|39651.52|13.7|-1.65%| +|600|51011.11|22.28|47047.9|27.66|-7.77%| +|900|58814.16|27.66|59331.84|28.67|0.88%| +|1200|65286.52|32.53|67745.39|31.37|3.77%| +|1500|68300.86|39.65|67899.17|44.17|-0.59%| + +Compared with v5.0.2, the Update Non-index performance of v5.1.0 is reduced by 0.8%. + +![Update Non-index](/media/sysbench_v510vsv502_update_non_index.png) + +### Update Index performance + +| Threads | v5.0.2 QPS | v5.0.2 95% latency (ms) | v5.1.0 QPS | v5.1.0 95% latency (ms) | QPS improvement | +|:----------|:----------|:----------|:----------|:----------|:----------| +|150|15066.54|14.73|14829.31|14.73|-1.57%| +|300|18535.92|24.83|17401.01|29.72|-6.12%| +|600|22862.73|41.1|21923.78|44.98|-4.11%| +|900|25286.74|57.87|24916.76|58.92|-1.46%| +|1200|27566.18|70.55|27800.62|69.29|0.85%| +|1500|28184.76|92.42|28679.72|86|1.76%| + +Compared with v5.0.2, the Update Index performance of v5.1.0 is reduced by 1.8%. + +![Update Index](/media/sysbench_v510vsv502_update_index.png) + +### Read Write performance + +| Threads | v5.0.2 QPS | v5.0.2 95% latency (ms) | v5.1.0 QPS | v5.1.0 95% latency (ms) | QPS improvement | +|:----------|:----------|:----------|:----------|:----------|:----------| +|150|66415.33|56.84|66591.49|57.87|0.27%| +|300|82488.39|97.55|81226.41|101.13|-1.53%| +|600|99195.36|173.58|97357.86|179.94|-1.85%| +|900|107382.76|253.35|101665.95|267.41|-5.32%| +|1200|112389.23|337.94|107426.41|350.33|-4.42%| +|1500|113548.73|450.77|109805.26|442.73|-3.30%| + +Compared with v5.0.2, the Read Write performance of v5.1.0 is reduced by 2.7%. + +![Read Write](/media/sysbench_v510vsv502_read_write.png) diff --git a/benchmark/benchmark-sysbench-v5.2.0-vs-v5.1.1.md b/benchmark/benchmark-sysbench-v5.2.0-vs-v5.1.1.md new file mode 100644 index 0000000000000..ae539a95e551b --- /dev/null +++ b/benchmark/benchmark-sysbench-v5.2.0-vs-v5.1.1.md @@ -0,0 +1,186 @@ +--- +title: TiDB Sysbench Performance Test Report -- v5.2.0 vs. v5.1.1 +summary: TiDB v5.2.0 shows an 11.03% improvement in Point Select performance compared to v5.1.1. However, other scenarios show a slight reduction in performance. The hardware and software configurations, test plan, and results are detailed in the report. +--- + +# TiDB Sysbench Performance Test Report -- v5.2.0 vs. v5.1.1 + +## Test overview + +This test aims at comparing the Sysbench performance of TiDB v5.2.0 and TiDB v5.1.1 in the Online Transactional Processing (OLTP) scenario. The results show that compared with v5.1.1, the Point Select performance of v5.2.0 is improved by 11.03%, and the performance of other scenarios is slightly reduced. + +## Test environment (AWS EC2） + +### Hardware configuration + +| Service type | EC2 type | Instance count | +|:----------|:----------|:----------| +| PD | m5.xlarge | 3 | +| TiKV | i3.4xlarge| 3 | +| TiDB | c5.4xlarge| 3 | +| Sysbench | c5.9xlarge| 1 | + +### Software version + +| Service type | Software version | +|:----------|:-----------| +| PD | v5.1.1 and v5.2.0 | +| TiDB | v5.1.1 and v5.2.0 | +| TiKV | v5.1.1 and v5.2.0 | +| Sysbench | 1.1.0-ead2689 | + +### Parameter configuration + +TiDB v5.2.0 and TiDB v5.1.1 use the same configuration. + +#### TiDB parameter configuration + +{{< copyable "" >}} + +```yaml +log.level: "error" +performance.max-procs: 20 +prepared-plan-cache.enabled: true +tikv-client.max-batch-wait-time: 2000000 +``` + +#### TiKV parameter configuration + +{{< copyable "" >}} + +```yaml +storage.scheduler-worker-pool-size: 5 +raftstore.store-pool-size: 3 +raftstore.apply-pool-size: 3 +rocksdb.max-background-jobs: 8 +raftdb.max-background-jobs: 4 +raftdb.allow-concurrent-memtable-write: true +server.grpc-concurrency: 6 +readpool.unified.min-thread-count: 5 +readpool.unified.max-thread-count: 20 +readpool.storage.normal-concurrency: 10 +pessimistic-txn.pipelined: true +server.enable-request-batch: false +``` + +#### TiDB global variable configuration + +{{< copyable "sql" >}} + +```sql +set global tidb_hashagg_final_concurrency=1; +set global tidb_hashagg_partial_concurrency=1; +set global tidb_enable_async_commit = 1; +set global tidb_enable_1pc = 1; +set global tidb_guarantee_linearizability = 0; +set global tidb_enable_clustered_index = 1; +``` + +## Test plan + +1. Deploy TiDB v5.2.0 and v5.1.1 using TiUP. +2. Use Sysbench to import 16 tables, each table with 10 million rows of data. +3. Execute the `analyze table` statement on each table. +4. Back up the data used for restore before different concurrency tests, which ensures data consistency for each test. +5. Start the Sysbench client to perform the `point_select`, `read_write`, `update_index`, and `update_non_index` tests. Perform stress tests on TiDB via HAProxy. The test takes 5 minutes. +6. After each type of test is completed, stop the cluster, overwrite the cluster with the backup data in step 4, and restart the cluster. + +### Prepare test data + +Execute the following command to prepare the test data: + +{{< copyable "shell-regular" >}} + +```bash +sysbench oltp_common \ + --threads=16 \ + --rand-type=uniform \ + --db-driver=mysql \ + --mysql-db=sbtest \ + --mysql-host=$aws_nlb_host \ + --mysql-port=$aws_nlb_port \ + --mysql-user=root \ + --mysql-password=password \ + prepare --tables=16 --table-size=10000000 +``` + +### Perform the test + +Execute the following command to perform the test: + +{{< copyable "shell-regular" >}} + +```bash +sysbench $testname \ + --threads=$threads \ + --time=300 \ + --report-interval=1 \ + --rand-type=uniform \ + --db-driver=mysql \ + --mysql-db=sbtest \ + --mysql-host=$aws_nlb_host \ + --mysql-port=$aws_nlb_port \ + run --tables=16 --table-size=10000000 +``` + +## Test results + +### Point Select performance + +| Threads | v5.1.1 QPS | v5.1.1 95% latency (ms) | v5.2.0 QPS | v5.2.0 95% latency (ms) | QPS improvement | +|:----------|:----------|:----------|:----------|:----------|:----------| +|150|143014.13|2.35|174402.5|1.23|21.95%| +|300|199133.06|3.68|272018|1.64|36.60%| +|600|389391.65|2.18|393536.4|2.11|1.06%| +|900|468338.82|2.97|447981.98|3.3|-4.35%| +|1200|448348.52|5.18|468241.29|4.65|4.44%| +|1500|454376.79|7.04|483888.42|6.09|6.49%| + +Compared with v5.1.1, the Point Select performance of v5.2.0 is improved by 11.03%. + +![Point Select](/media/sysbench_v511vsv520_point_select.png) + +### Update Non-index performance + +| Threads | v5.1.1 QPS | v5.1.1 95% latency (ms) | v5.2.0 QPS | v5.2.0 95% latency (ms) | QPS improvement | +|:----------|:----------|:----------|:----------|:----------|:----------| +|150|31198.68|6.43|30714.73|6.09|-1.55%| +|300|43577.15|10.46|42997.92|9.73|-1.33%| +|600|57230.18|17.32|56168.81|16.71|-1.85%| +|900|65325.11|23.1|64098.04|22.69|-1.88%| +|1200|71528.26|28.67|69908.15|28.67|-2.26%| +|1500|76652.5|33.12|74371.79|33.72|-2.98%| + +Compared with v5.1.1, the Update Non-index performance of v5.2.0 is reduced by 1.98%. + +![Update Non-index](/media/sysbench_v511vsv520_update_non_index.png) + +### Update Index performance + +| Threads | v5.1.1 QPS | v5.1.1 95% latency (ms) | v5.2.0 QPS | v5.2.0 95% latency (ms) | QPS improvement | +|:----------|:----------|:----------|:----------|:----------|:----------| +|150|15641.04|13.22|15320|13.46|-2.05%| +|300|19787.73|21.89|19161.35|22.69|-3.17%| +|600|24566.74|36.89|23616.07|38.94|-3.87%| +|900|27516.57|50.11|26270.04|54.83|-4.53%| +|1200|29421.10|63.32|28002.65|69.29|-4.82%| +|1500|30957.84|77.19|28624.44|95.81|-7.54%| + +Compared with v5.0.2, the Update Index performance of v5.1.0 is reduced by 4.33%. + +![Update Index](/media/sysbench_v511vsv520_update_index.png) + +### Read Write performance + +| Threads | v5.1.1 QPS | v5.1.1 95% latency (ms) | v5.2.0 QPS | v5.2.0 95% latency (ms) | QPS improvement | +|:----------|:----------|:----------|:----------|:----------|:----------| +|150|68471.02|57.87|69246|54.83|1.13%| +|300|86573.09|97.55|85340.42|94.10|-1.42%| +|600|101760.75|176.73|102221.31|173.58|0.45%| +|900|111877.55|248.83|109276.45|257.95|-2.32%| +|1200|117479.4|337.94|114231.33|344.08|-2.76%| +|1500|119662.91|419.45|116663.28|434.83|-2.51%| + +Compared with v5.0.2, the Read Write performance of v5.1.0 is reduced by 1.24%. + +![Read Write](/media/sysbench_v511vsv520_read_write.png) diff --git a/benchmark/benchmark-sysbench-v5.3.0-vs-v5.2.2.md b/benchmark/benchmark-sysbench-v5.3.0-vs-v5.2.2.md new file mode 100644 index 0000000000000..8759d0928e53e --- /dev/null +++ b/benchmark/benchmark-sysbench-v5.3.0-vs-v5.2.2.md @@ -0,0 +1,203 @@ +--- +title: TiDB Sysbench Performance Test Report -- v5.3.0 vs. v5.2.2 +summary: TiDB v5.3.0 and v5.2.2 were compared in a Sysbench performance test for Online Transactional Processing (OLTP). Results show that v5.3.0 performance is nearly the same as v5.2.2. Point Select performance of v5.3.0 is reduced by 0.81%, Update Non-index performance is improved by 0.95%, Update Index performance is improved by 1.83%, and Read Write performance is reduced by 0.62%. +--- + +# TiDB Sysbench Performance Test Report -- v5.3.0 vs. v5.2.2 + +## Test overview + +This test aims at comparing the Sysbench performance of TiDB v5.3.0 and TiDB v5.2.2 in the Online Transactional Processing (OLTP) scenario. The results show that the performance of v5.3.0 is nearly the same as that of v5.2.2. + +## Test environment (AWS EC2） + +### Hardware configuration + +| Service type | EC2 type | Instance count | +|:----------|:----------|:----------| +| PD | m5.xlarge | 3 | +| TiKV | i3.4xlarge| 3 | +| TiDB | c5.4xlarge| 3 | +| Sysbench | c5.9xlarge| 1 | + +### Software version + +| Service type | Software version | +|:----------|:-----------| +| PD | v5.2.2 and v5.3.0 | +| TiDB | v5.2.2 and v5.3.0 | +| TiKV | v5.2.2 and v5.3.0 | +| Sysbench | 1.1.0-ead2689 | + +### Parameter configuration + +TiDB v5.3.0 and TiDB v5.2.2 use the same configuration. + +#### TiDB parameter configuration + +{{< copyable "" >}} + +```yaml +log.level: "error" +performance.max-procs: 20 +prepared-plan-cache.enabled: true +tikv-client.max-batch-wait-time: 2000000 +``` + +#### TiKV parameter configuration + +{{< copyable "" >}} + +```yaml +storage.scheduler-worker-pool-size: 5 +raftstore.store-pool-size: 3 +raftstore.apply-pool-size: 3 +rocksdb.max-background-jobs: 8 +raftdb.max-background-jobs: 4 +raftdb.allow-concurrent-memtable-write: true +server.grpc-concurrency: 6 +readpool.unified.min-thread-count: 5 +readpool.unified.max-thread-count: 20 +readpool.storage.normal-concurrency: 10 +pessimistic-txn.pipelined: true +``` + +#### TiDB global variable configuration + +{{< copyable "sql" >}} + +```sql +set global tidb_hashagg_final_concurrency=1; +set global tidb_hashagg_partial_concurrency=1; +set global tidb_enable_async_commit = 1; +set global tidb_enable_1pc = 1; +set global tidb_guarantee_linearizability = 0; +set global tidb_enable_clustered_index = 1; +``` + +#### HAProxy configuration - haproxy.cfg + +For more details about how to use HAProxy on TiDB, see [Best Practices for Using HAProxy in TiDB](/best-practices/haproxy-best-practices.md). + +```yaml +global # Global configuration. + chroot /var/lib/haproxy # Changes the current directory and sets superuser privileges for the startup process to improve security. + pidfile /var/run/haproxy.pid # Writes the PIDs of HAProxy processes into this file. + maxconn 4000 # The maximum number of concurrent connections for a single HAProxy process. + user haproxy # Same with the UID parameter. + group haproxy # Same with the GID parameter. A dedicated user group is recommended. + nbproc 64 # The number of processes created when going daemon. When starting multiple processes to forward requests, ensure that the value is large enough so that HAProxy does not block processes. + daemon # Makes the process fork into background. It is equivalent to the command line "-D" argument. It can be disabled by the command line "-db" argument. + +defaults # Default configuration. + log global # Inherits the settings of the global configuration. + retries 2 # The maximum number of retries to connect to an upstream server. If the number of connection attempts exceeds the value, the backend server is considered unavailable. + timeout connect 2s # The maximum time to wait for a connection attempt to a backend server to succeed. It should be set to a shorter time if the server is located on the same LAN as HAProxy. + timeout client 30000s # The maximum inactivity time on the client side. + timeout server 30000s # The maximum inactivity time on the server side. + +listen tidb-cluster # Database load balancing. + bind 0.0.0.0:3390 # The Floating IP address and listening port. + mode tcp # HAProxy uses layer 4, the transport layer. + balance roundrobin # The server with the fewest connections receives the connection. "leastconn" is recommended where long sessions are expected, such as LDAP, SQL and TSE, rather than protocols using short sessions, such as HTTP. The algorithm is dynamic, which means that server weights might be adjusted on the fly for slow starts for instance. + server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # Detects port 4000 at a frequency of once every 2000 milliseconds. If it is detected as successful twice, the server is considered available; if it is detected as failed three times, the server is considered unavailable. + server tidb-2 10.9.39.208:4000 check inter 2000 rise 2 fall 3 + server tidb-3 10.9.64.166:4000 check inter 2000 rise 2 fall 3 +``` + +## Test plan + +1. Deploy TiDB v5.3.0 and v5.2.2 using TiUP. +2. Use Sysbench to import 16 tables, each table with 10 million rows of data. +3. Execute the `analyze table` statement on each table. +4. Back up the data used for restore before different concurrency tests, which ensures data consistency for each test. +5. Start the Sysbench client to perform the `point_select`, `read_write`, `update_index`, and `update_non_index` tests. Perform stress tests on TiDB via HAProxy. For each concurrency under each workload, the test takes 20 minutes. +6. After each type of test is completed, stop the cluster, overwrite the cluster with the backup data in step 4, and restart the cluster. + +### Prepare test data + +Run the following command to prepare the test data: + +{{< copyable "shell-regular" >}} + +```bash +sysbench oltp_common \ + --threads=16 \ + --rand-type=uniform \ + --db-driver=mysql \ + --mysql-db=sbtest \ + --mysql-host=$aws_nlb_host \ + --mysql-port=$aws_nlb_port \ + --mysql-user=root \ + --mysql-password=password \ + prepare --tables=16 --table-size=10000000 +``` + +### Perform the test + +Run the following command to perform the test: + +{{< copyable "shell-regular" >}} + +```bash +sysbench $testname \ + --threads=$threads \ + --time=1200 \ + --report-interval=1 \ + --rand-type=uniform \ + --db-driver=mysql \ + --mysql-db=sbtest \ + --mysql-host=$aws_nlb_host \ + --mysql-port=$aws_nlb_port \ + run --tables=16 --table-size=10000000 +``` + +## Test results + +### Point Select performance + +| Threads | v5.2.2 TPS | v5.3.0 TPS | v5.2.2 95% latency (ms) | v5.3.0 95% latency (ms) | TPS improvement (%) | +|:----------|:----------|:----------|:----------|:----------|:----------| +|300|267673.17|267516.77|1.76|1.67|-0.06| +|600|369820.29|361672.56|2.91|2.97|-2.20| +|900|417143.31|416479.47|4.1|4.18|-0.16| + +Compared with v5.2.2, the Point Select performance of v5.3.0 is reduced slightly by 0.81%. + +![Point Select](/media/sysbench_v522vsv530_point_select.png) + +### Update Non-index performance + +| Threads | v5.2.2 TPS | v5.3.0 TPS | v5.2.2 95% latency (ms) | v5.3.0 95% latency (ms) | TPS improvement (%) | +|:----------|:----------|:----------|:----------|:----------|:----------| +|300|39715.31|40041.03|11.87|12.08|0.82| +|600|50239.42|51110.04|20.74|20.37|1.73| +|900|57073.97|57252.74|28.16|27.66|0.31| + +Compared with v5.2.2, the Update Non-index performance of v5.3.0 is improved slightly by 0.95%. + +![Update Non-index](/media/sysbench_v522vsv530_update_non_index.png) + +### Update Index performance + +| Threads | v5.2.2 TPS | v5.3.0 TPS | v5.2.2 95% latency (ms) | v5.3.0 95% latency (ms) | TPS improvement (%) | +|:----------|:----------|:----------|:----------|:----------|:----------| +|300|17634.03|17821.1|25.74|25.74|1.06| +|600|20998.59|21534.13|46.63|45.79|2.55| +|900|23420.75|23859.64|64.47|62.19|1.87| + +Compared with v5.2.2, the Update Index performance of v5.3.0 is improved slightly by 1.83%. + +![Update Index](/media/sysbench_v522vsv530_update_index.png) + +### Read Write performance + +| Threads | v5.2.2 TPS | v5.3.0 TPS | v5.2.2 95% latency (ms) | v5.3.0 95% latency (ms) | TPS improvement (%) | +|:----------|:----------|:----------|:----------|:----------|:----------| +|300|3872.01|3848.63|106.75|106.75|-0.60| +|600|4514.17|4471.77|200.47|196.89|-0.94| +|900|4877.05|4861.45|287.38|282.25|-0.32| + +Compared with v5.2.2, the Read Write performance of v5.3.0 is reduced slightly by 0.62%. + +![Read Write](/media/sysbench_v522vsv530_read_write.png) \ No newline at end of file diff --git a/benchmark/benchmark-sysbench-v5.4.0-vs-v5.3.0.md b/benchmark/benchmark-sysbench-v5.4.0-vs-v5.3.0.md new file mode 100644 index 0000000000000..c1b0c055e805f --- /dev/null +++ b/benchmark/benchmark-sysbench-v5.4.0-vs-v5.3.0.md @@ -0,0 +1,203 @@ +--- +title: TiDB Sysbench Performance Test Report -- v5.4.0 vs. v5.3.0 +summary: TiDB v5.4.0 shows improved performance of 2.59% to 4.85% in write-heavy workloads compared to v5.3.0. Results show performance improvements in point select, update non-index, update index, and read write scenarios. +--- + +# TiDB Sysbench Performance Test Report -- v5.4.0 vs. v5.3.0 + +## Test overview + +This test aims at comparing the Sysbench performance of TiDB v5.4.0 and TiDB v5.3.0 in the Online Transactional Processing (OLTP) scenario. The results show that performance of v5.4.0 is improved by 2.59% ~ 4.85% in the write-heavy workload. + +## Test environment (AWS EC2） + +### Hardware configuration + +| Service type | EC2 type | Instance count | +|:----------|:----------|:----------| +| PD | m5.xlarge | 3 | +| TiKV | i3.4xlarge| 3 | +| TiDB | c5.4xlarge| 3 | +| Sysbench | c5.9xlarge| 1 | + +### Software version + +| Service type | Software version | +|:----------|:-----------| +| PD | v5.3.0 and v5.4.0 | +| TiDB | v5.3.0 and v5.4.0 | +| TiKV | v5.3.0 and v5.4.0 | +| Sysbench | 1.1.0-ead2689 | + +### Parameter configuration + +TiDB v5.4.0 and TiDB v5.3.0 use the same configuration. + +#### TiDB parameter configuration + +{{< copyable "" >}} + +```yaml +log.level: "error" +performance.max-procs: 20 +prepared-plan-cache.enabled: true +tikv-client.max-batch-wait-time: 2000000 +``` + +#### TiKV parameter configuration + +{{< copyable "" >}} + +```yaml +storage.scheduler-worker-pool-size: 5 +raftstore.store-pool-size: 3 +raftstore.apply-pool-size: 3 +rocksdb.max-background-jobs: 8 +raftdb.max-background-jobs: 4 +raftdb.allow-concurrent-memtable-write: true +server.grpc-concurrency: 6 +readpool.unified.min-thread-count: 5 +readpool.unified.max-thread-count: 20 +readpool.storage.normal-concurrency: 10 +pessimistic-txn.pipelined: true +``` + +#### TiDB global variable configuration + +{{< copyable "sql" >}} + +```sql +set global tidb_hashagg_final_concurrency=1; +set global tidb_hashagg_partial_concurrency=1; +set global tidb_enable_async_commit = 1; +set global tidb_enable_1pc = 1; +set global tidb_guarantee_linearizability = 0; +set global tidb_enable_clustered_index = 1; +``` + +#### HAProxy configuration - haproxy.cfg + +For more details about how to use HAProxy on TiDB, see [Best Practices for Using HAProxy in TiDB](/best-practices/haproxy-best-practices.md). + +{{< copyable "" >}} + +```yaml +global # Global configuration. + chroot /var/lib/haproxy # Changes the current directory and sets superuser privileges for the startup process to improve security. + pidfile /var/run/haproxy.pid # Writes the PIDs of HAProxy processes into this file. + maxconn 4000 # The maximum number of concurrent connections for a single HAProxy process. + user haproxy # The same with the UID parameter. + group haproxy # The same with the GID parameter. A dedicated user group is recommended. + nbproc 64 # The number of processes created when going daemon. When starting multiple processes to forward requests, ensure that the value is large enough so that HAProxy does not block processes. + daemon # Makes the process fork into background. It is equivalent to the command line "-D" argument. It can be disabled by the command line "-db" argument. +defaults # Default configuration. + log global # Inherits the settings of the global configuration. + retries 2 # The maximum number of retries to connect to an upstream server. If the number of connection attempts exceeds the value, the backend server is considered unavailable. + timeout connect 2s # The maximum time to wait for a connection attempt to a backend server to succeed. It should be set to a shorter time if the server is located on the same LAN as HAProxy. + timeout client 30000s # The maximum inactivity time on the client side. + timeout server 30000s # The maximum inactivity time on the server side. +listen tidb-cluster # Database load balancing. + bind 0.0.0.0:3390 # The Floating IP address and listening port. + mode tcp # HAProxy uses layer 4, the transport layer. + balance roundrobin # The server with the fewest connections receives the connection. "leastconn" is recommended where long sessions are expected, such as LDAP, SQL and TSE, rather than protocols using short sessions, such as HTTP. The algorithm is dynamic, which means that server weights might be adjusted on the fly for slow starts for instance. + server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # Detects port 4000 at a frequency of once every 2000 milliseconds. If it is detected as successful twice, the server is considered available; if it is detected as failed three times, the server is considered unavailable. + server tidb-2 10.9.39.208:4000 check inter 2000 rise 2 fall 3 + server tidb-3 10.9.64.166:4000 check inter 2000 rise 2 fall 3 +``` + +## Test plan + +1. Deploy TiDB v5.4.0 and v5.3.0 using TiUP. +2. Use Sysbench to import 16 tables, each table with 10 million rows of data. +3. Execute the `analyze table` statement on each table. +4. Back up the data used for restore before different concurrency tests, which ensures data consistency for each test. +5. Start the Sysbench client to perform the `point_select`, `read_write`, `update_index`, and `update_non_index` tests. Perform stress tests on TiDB via HAProxy. For each concurrency under each workload, the test takes 20 minutes. +6. After each type of test is completed, stop the cluster, overwrite the cluster with the backup data in step 4, and restart the cluster. + +### Prepare test data + +Run the following command to prepare the test data: + +{{< copyable "shell-regular" >}} + +```bash +sysbench oltp_common \ + --threads=16 \ + --rand-type=uniform \ + --db-driver=mysql \ + --mysql-db=sbtest \ + --mysql-host=$aws_nlb_host \ + --mysql-port=$aws_nlb_port \ + --mysql-user=root \ + --mysql-password=password \ + prepare --tables=16 --table-size=10000000 +``` + +### Perform the test + +Run the following command to perform the test: + +{{< copyable "shell-regular" >}} + +```bash +sysbench $testname \ + --threads=$threads \ + --time=1200 \ + --report-interval=1 \ + --rand-type=uniform \ + --db-driver=mysql \ + --mysql-db=sbtest \ + --mysql-host=$aws_nlb_host \ + --mysql-port=$aws_nlb_port \ + run --tables=16 --table-size=10000000 +``` + +## Test results + +### Point Select performance + +| Threads | v5.3.0 TPS | v5.4.0 TPS | v5.3.0 95% latency (ms) | v5.4.0 95% latency (ms) | TPS improvement (%) | +|:----------|:----------|:----------|:----------|:----------|:----------| +|300|266041.84|264345.73|1.96|2.07|-0.64| +|600|351782.71|348715.98|3.43|3.49|-0.87| +|900|386553.31|399777.11|5.09|4.74|3.42| + +Compared with v5.3.0, the Point Select performance of v5.4.0 is slightly improved by 0.64%. + +![Point Select](/media/sysbench_v530vsv540_point_select.png) + +### Update Non-index performance + +| Threads | v5.3.0 TPS | v5.4.0 TPS | v5.3.0 95% latency (ms) | v5.4.0 95% latency (ms) | TPS improvement (%) | +|:----------|:----------|:----------|:----------|:----------|:----------| +|300|40804.31|41187.1|11.87|11.87|0.94| +|600|51239.4|53172.03|20.74|19.65|3.77| +|900|57897.56|59666.8|27.66|27.66|3.06| + +Compared with v5.3.0, the Update Non-index performance of v5.4.0 is improved by 2.59%. + +![Update Non-index](/media/sysbench_v530vsv540_update_non_index.png) + +### Update Index performance + +| Threads | v5.3.0 TPS | v5.4.0 TPS | v5.3.0 95% latency (ms) | v5.4.0 95% latency (ms) | TPS improvement (%) | +|:----------|:----------|:----------|:----------|:----------|:----------| +|300|17737.82|18716.5|26.2|24.83|5.52| +|600|21614.39|22670.74|44.98|42.61|4.89| +|900|23933.7|24922.05|62.19|61.08|4.13| + +Compared with v5.3.0, the Update Index performance of v5.4.0 is improved by 4.85%. + +![Update Index](/media/sysbench_v530vsv540_update_index.png) + +### Read Write performance + +| Threads | v5.3.0 TPS | v5.4.0 TPS | v5.3.0 95% latency (ms) | v5.4.0 95% latency (ms) | TPS improvement (%) | +|:----------|:----------|:----------|:----------|:----------|:----------| +|300|3810.78|3929.29|108.68|106.75|3.11| +|600|4514.28|4684.64|193.38|186.54|3.77| +|900|4842.49|4988.49|282.25|277.21|3.01| + +Compared with v5.3.0, the Read Write performance of v5.4.0 is improved by 3.30%. + +![Read Write](/media/sysbench_v530vsv540_read_write.png) diff --git a/benchmark/benchmark-sysbench-v6.0.0-vs-v5.4.0.md b/benchmark/benchmark-sysbench-v6.0.0-vs-v5.4.0.md new file mode 100644 index 0000000000000..0af44a97299aa --- /dev/null +++ b/benchmark/benchmark-sysbench-v6.0.0-vs-v5.4.0.md @@ -0,0 +1,199 @@ +--- +title: TiDB Sysbench Performance Test Report -- v6.0.0 vs. v5.4.0 +summary: TiDB v6.0.0 shows a 16.17% improvement in read-write workload performance compared to v5.4.0. Other workloads show similar performance between the two versions. Test results show performance comparisons for point select, update non-index, update index, and read-write workloads. +--- + +# TiDB Sysbench Performance Test Report -- v6.0.0 vs. v5.4.0 + +## Test overview + +This test aims at comparing the Sysbench performance of TiDB v6.0.0 and TiDB v5.4.0 in the Online Transactional Processing (OLTP) scenario. The results show that performance of v6.0.0 is significantly improved by 16.17% in the read-write workload. The performance of other workload is basically the same as in v5.4.0. + +## Test environment (AWS EC2） + +### Hardware configuration + +| Service type | EC2 type | Instance count | +|:----------|:----------|:----------| +| PD | m5.xlarge | 3 | +| TiKV | i3.4xlarge| 3 | +| TiDB | c5.4xlarge| 3 | +| Sysbench | c5.9xlarge| 1 | + +### Software version + +| Service type | Software version | +|:----------|:-----------| +| PD | v5.4.0 and v6.0.0 | +| TiDB | v5.4.0 and v6.0.0 | +| TiKV | v5.4.0 and v6.0.0 | +| Sysbench | 1.1.0-df89d34 | + +### Parameter configuration + +TiDB v6.0.0 and TiDB v5.4.0 use the same configuration. + +#### TiDB parameter configuration + +{{< copyable "" >}} + +```yaml +log.level: "error" +prepared-plan-cache.enabled: true +tikv-client.max-batch-wait-time: 2000000 +``` + +#### TiKV parameter configuration + +{{< copyable "" >}} + +```yaml +storage.scheduler-worker-pool-size: 5 +raftstore.store-pool-size: 3 +raftstore.apply-pool-size: 3 +rocksdb.max-background-jobs: 8 +raftdb.max-background-jobs: 4 +raftdb.allow-concurrent-memtable-write: true +server.grpc-concurrency: 6 +readpool.storage.normal-concurrency: 10 +pessimistic-txn.pipelined: true +``` + +#### TiDB global variable configuration + +{{< copyable "sql" >}} + +```sql +set global tidb_hashagg_final_concurrency=1; +set global tidb_hashagg_partial_concurrency=1; +set global tidb_enable_async_commit = 1; +set global tidb_enable_1pc = 1; +set global tidb_guarantee_linearizability = 0; +set global tidb_enable_clustered_index = 1; +``` + +#### HAProxy configuration - haproxy.cfg + +For more details about how to use HAProxy on TiDB, see [Best Practices for Using HAProxy in TiDB](/best-practices/haproxy-best-practices.md). + +{{< copyable "" >}} + +```yaml +global # Global configuration. + pidfile /var/run/haproxy.pid # Writes the PIDs of HAProxy processes into this file. + maxconn 4000 # The maximum number of concurrent connections for a single HAProxy process. + user haproxy # The same with the UID parameter. + group haproxy # The same with the GID parameter. A dedicated user group is recommended. + nbproc 64 # The number of processes created when going daemon. When starting multiple processes to forward requests, ensure that the value is large enough so that HAProxy does not block processes. + daemon # Makes the process fork into background. It is equivalent to the command line "-D" argument. It can be disabled by the command line "-db" argument. +defaults # Default configuration. + log global # Inherits the settings of the global configuration. + retries 2 # The maximum number of retries to connect to an upstream server. If the number of connection attempts exceeds the value, the backend server is considered unavailable. + timeout connect 2s # The maximum time to wait for a connection attempt to a backend server to succeed. It should be set to a shorter time if the server is located on the same LAN as HAProxy. + timeout client 30000s # The maximum inactivity time on the client side. + timeout server 30000s # The maximum inactivity time on the server side. +listen tidb-cluster # Database load balancing. + bind 0.0.0.0:3390 # The Floating IP address and listening port. + mode tcp # HAProxy uses layer 4, the transport layer. + balance leastconn # The server with the fewest connections receives the connection. "leastconn" is recommended where long sessions are expected, such as LDAP, SQL and TSE, rather than protocols using short sessions, such as HTTP. The algorithm is dynamic, which means that server weights might be adjusted on the fly for slow starts for instance. + server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # Detects port 4000 at a frequency of once every 2000 milliseconds. If it is detected as successful twice, the server is considered available; if it is detected as failed three times, the server is considered unavailable. + server tidb-2 10.9.39.208:4000 check inter 2000 rise 2 fall 3 + server tidb-3 10.9.64.166:4000 check inter 2000 rise 2 fall 3 +``` + +## Test plan + +1. Deploy TiDB v6.0.0 and v5.4.0 using TiUP. +2. Use Sysbench to import 16 tables, each table with 10 million rows of data. +3. Execute the `analyze table` statement on each table. +4. Back up the data used for restore before different concurrency tests, which ensures data consistency for each test. +5. Start the Sysbench client to perform the `point_select`, `read_write`, `update_index`, and `update_non_index` tests. Perform stress tests on TiDB via HAProxy. For each concurrency under each workload, the test takes 20 minutes. +6. After each type of test is completed, stop the cluster, overwrite the cluster with the backup data in step 4, and restart the cluster. + +### Prepare test data + +Run the following command to prepare the test data: + +{{< copyable "shell-regular" >}} + +```bash +sysbench oltp_common \ + --threads=16 \ + --rand-type=uniform \ + --db-driver=mysql \ + --mysql-db=sbtest \ + --mysql-host=$aws_nlb_host \ + --mysql-port=$aws_nlb_port \ + --mysql-user=root \ + --mysql-password=password \ + prepare --tables=16 --table-size=10000000 +``` + +### Perform the test + +Run the following command to perform the test: + +{{< copyable "shell-regular" >}} + +```bash +sysbench $testname \ + --threads=$threads \ + --time=1200 \ + --report-interval=1 \ + --rand-type=uniform \ + --db-driver=mysql \ + --mysql-db=sbtest \ + --mysql-host=$aws_nlb_host \ + --mysql-port=$aws_nlb_port \ + run --tables=16 --table-size=10000000 +``` + +## Test results + +### Point Select performance + +| Threads | v5.4.0 TPS | v6.0.0 TPS | v5.4.0 95% latency (ms) | v6.0.0 95% latency (ms) | TPS improvement (%) | +|:----------|:----------|:----------|:----------|:----------|:----------| +|300|260085.19|265207.73|1.82|1.93|1.97| +|600|378098.48|365173.66|2.48|2.61|-3.42| +|900|441294.61|424031.23|3.75|3.49|-3.91| + +Compared with v5.4.0, the Point Select performance of v6.0.0 is slightly dropped by 1.79%. + +![Point Select](/media/sysbench_v540vsv600_point_select.png) + +### Update Non-index performance + +| Threads | v5.4.0 TPS | v6.0.0 TPS | v5.4.0 95% latency (ms) | v6.0.0 95% latency (ms) | TPS improvement (%) | +|:----------|:----------|:----------|:----------|:----------|:----------| +|300|41528.7|40814.23|11.65|11.45|-1.72| +|600|53220.96|51746.21|19.29|20.74|-2.77| +|900|59977.58|59095.34|26.68|28.16|-1.47| + +Compared with v5.4.0, the Update Non-index performance of v6.0.0 is slightly dropped by 1.98%. + +![Update Non-index](/media/sysbench_v540vsv600_update_non_index.png) + +### Update Index performance + +| Threads | v5.4.0 TPS | v6.0.0 TPS | v5.4.0 95% latency (ms) | v6.0.0 95% latency (ms) | TPS improvement (%) | +|:----------|:----------|:----------|:----------|:----------|:----------| +|300|18659.11|18187.54|23.95|25.74|-2.53| +|600|23195.83|22270.81|40.37|44.17|-3.99| +|900|25798.31|25118.78|56.84|57.87|-2.63| + +Compared with v5.4.0, the Update Index performance of v6.0.0 is dropped by 3.05%. + +![Update Index](/media/sysbench_v540vsv600_update_index.png) + +### Read Write performance + +| Threads | v5.4.0 TPS | v6.0.0 TPS | v5.4.0 95% latency (ms) | v6.0.0 95% latency (ms) | TPS improvement (%) | +|:----------|:----------|:----------|:----------|:----------|:----------| +|300|4141.72|4829.01|97.55|82.96|16.59| +|600|4892.76|5693.12|173.58|153.02|16.36| +|900|5217.94|6029.95|257.95|235.74|15.56| + +Compared with v5.4.0, the Read Write performance of v6.0.0 is significantly improved by 16.17%. + +![Read Write](/media/sysbench_v540vsv600_read_write.png) diff --git a/benchmark/benchmark-sysbench-v6.1.0-vs-v6.0.0.md b/benchmark/benchmark-sysbench-v6.1.0-vs-v6.0.0.md new file mode 100644 index 0000000000000..a61d18baf57ea --- /dev/null +++ b/benchmark/benchmark-sysbench-v6.1.0-vs-v6.0.0.md @@ -0,0 +1,199 @@ +--- +title: TiDB Sysbench Performance Test Report -- v6.1.0 vs. v6.0.0 +summary: TiDB v6.1.0 shows improved performance in write-heavy workloads compared to v6.0.0, with a 2.33% ~ 4.61% improvement. The test environment includes AWS EC2 instances and Sysbench 1.1.0-df89d34. Both versions use the same parameter configuration. Test plan involves deploying, importing data, and performing stress tests. Results show slight drop in Point Select performance, while Update Non-index, Update Index, and Read Write performance are improved by 2.90%, 4.61%, and 2.23% respectively. +--- + +# TiDB Sysbench Performance Test Report -- v6.1.0 vs. v6.0.0 + +## Test overview + +This test aims at comparing the Sysbench performance of TiDB v6.1.0 and TiDB v6.0.0 in the Online Transactional Processing (OLTP) scenario. The results show that performance of v6.1.0 is improved in the write workload. The performance of write-heavy workload is improved by 2.33% ~ 4.61%. + +## Test environment (AWS EC2） + +### Hardware configuration + +| Service type | EC2 type | Instance count | +|:----------|:----------|:----------| +| PD | m5.xlarge | 3 | +| TiKV | i3.4xlarge| 3 | +| TiDB | c5.4xlarge| 3 | +| Sysbench | c5.9xlarge| 1 | + +### Software version + +| Service type | Software version | +|:----------|:-----------| +| PD | v6.0.0 and v6.1.0 | +| TiDB | v6.0.0 and v6.1.0 | +| TiKV | v6.0.0 and v6.1.0 | +| Sysbench | 1.1.0-df89d34 | + +### Parameter configuration + +TiDB v6.1.0 and TiDB v6.0.0 use the same configuration. + +#### TiDB parameter configuration + +{{< copyable "" >}} + +```yaml +log.level: "error" +prepared-plan-cache.enabled: true +tikv-client.max-batch-wait-time: 2000000 +``` + +#### TiKV parameter configuration + +{{< copyable "" >}} + +```yaml +storage.scheduler-worker-pool-size: 5 +raftstore.store-pool-size: 3 +raftstore.apply-pool-size: 3 +rocksdb.max-background-jobs: 8 +server.grpc-concurrency: 6 +readpool.storage.normal-concurrency: 10 +``` + +#### TiDB global variable configuration + +{{< copyable "sql" >}} + +```sql +set global tidb_hashagg_final_concurrency=1; +set global tidb_hashagg_partial_concurrency=1; +set global tidb_enable_async_commit = 1; +set global tidb_enable_1pc = 1; +set global tidb_guarantee_linearizability = 0; +set global tidb_enable_clustered_index = 1; +set global tidb_prepared_plan_cache_size=1000; +``` + +#### HAProxy configuration - haproxy.cfg + +For more details about how to use HAProxy on TiDB, see [Best Practices for Using HAProxy in TiDB](/best-practices/haproxy-best-practices.md). + +{{< copyable "" >}} + +```yaml +global # Global configuration. + pidfile /var/run/haproxy.pid # Writes the PIDs of HAProxy processes into this file. + maxconn 4000 # The maximum number of concurrent connections for a single HAProxy process. + user haproxy # The same with the UID parameter. + group haproxy # The same with the GID parameter. A dedicated user group is recommended. + nbproc 64 # The number of processes created when going daemon. When starting multiple processes to forward requests, ensure that the value is large enough so that HAProxy does not block processes. + daemon # Makes the process fork into background. It is equivalent to the command line "-D" argument. It can be disabled by the command line "-db" argument. + +defaults # Default configuration. + log global # Inherits the settings of the global configuration. + retries 2 # The maximum number of retries to connect to an upstream server. If the number of connection attempts exceeds the value, the backend server is considered unavailable. + timeout connect 2s # The maximum time to wait for a connection attempt to a backend server to succeed. It should be set to a shorter time if the server is located on the same LAN as HAProxy. + timeout client 30000s # The maximum inactivity time on the client side. + timeout server 30000s # The maximum inactivity time on the server side. + +listen tidb-cluster # Database load balancing. + bind 0.0.0.0:3390 # The Floating IP address and listening port. + mode tcp # HAProxy uses layer 4, the transport layer. + balance leastconn # The server with the fewest connections receives the connection. "leastconn" is recommended where long sessions are expected, such as LDAP, SQL and TSE, rather than protocols using short sessions, such as HTTP. The algorithm is dynamic, which means that server weights might be adjusted on the fly for slow starts for instance. + server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # Detects port 4000 at a frequency of once every 2000 milliseconds. If it is detected as successful twice, the server is considered available; if it is detected as failed three times, the server is considered unavailable. + server tidb-2 10.9.39.208:4000 check inter 2000 rise 2 fall 3 + server tidb-3 10.9.64.166:4000 check inter 2000 rise 2 fall 3 +``` + +## Test plan + +1. Deploy TiDB v6.1.0 and v6.0.0 using TiUP. +2. Use Sysbench to import 16 tables, each table with 10 million rows of data. +3. Execute the `analyze table` statement on each table. +4. Back up the data used for restore before different concurrency tests, which ensures data consistency for each test. +5. Start the Sysbench client to perform the `point_select`, `read_write`, `update_index`, and `update_non_index` tests. Perform stress tests on TiDB via HAProxy. For each concurrency under each workload, the test takes 20 minutes. +6. After each type of test is completed, stop the cluster, overwrite the cluster with the backup data in step 4, and restart the cluster. + +### Prepare test data + +Run the following command to prepare the test data: + +{{< copyable "shell-regular" >}} + +```bash +sysbench oltp_common \ + --threads=16 \ + --rand-type=uniform \ + --db-driver=mysql \ + --mysql-db=sbtest \ + --mysql-host=$aws_nlb_host \ + --mysql-port=$aws_nlb_port \ + --mysql-user=root \ + --mysql-password=password \ + prepare --tables=16 --table-size=10000000 +``` + +### Perform the test + +Run the following command to perform the test: + +{{< copyable "shell-regular" >}} + +```bash +sysbench $testname \ + --threads=$threads \ + --time=1200 \ + --report-interval=1 \ + --rand-type=uniform \ + --db-driver=mysql \ + --mysql-db=sbtest \ + --mysql-host=$aws_nlb_host \ + --mysql-port=$aws_nlb_port \ + run --tables=16 --table-size=10000000 +``` + +## Test results + +### Point Select performance + +| Threads | v6.0.0 TPS | v6.1.0 TPS | v6.0.0 95% latency (ms) | v6.1.0 95% latency (ms) | TPS improvement (%) | +|:----------|:----------|:----------|:----------|:----------|:----------| +|300|268934.84|265353.15|1.89|1.96|-1.33| +|600|365217.96|358976.94|2.57|2.66|-1.71| +|900|420799.64|407625.11|3.68|3.82|-3.13| + +Compared with v6.0.0, the Point Select performance of v6.1.0 slightly drops by 2.1%. + +![Point Select](/media/sysbench_v600vsv610_point_select.png) + +### Update Non-index performance + +| Threads | v6.0.0 TPS | v6.1.0 TPS | v6.0.0 95% latency (ms) | v6.1.0 95% latency (ms) | TPS improvement (%) | +|:----------|:----------|:----------|:----------|:----------|:----------| +|300|41778.95|42991.9|11.24|11.45|2.90 | +|600|52045.39|54099.58|20.74|20.37|3.95| +|900|59243.35|62084.65|27.66|26.68|4.80| + +Compared with v6.0.0, the Update Non-index performance of v6.1.0 is improved by 3.88%. + +![Update Non-index](/media/sysbench_v600vsv610_update_non_index.png) + +### Update Index performance + +| Threads | v6.0.0 TPS | v6.1.0 TPS | v6.0.0 95% latency (ms) | v6.1.0 95% latency (ms) | TPS improvement (%) | +|:----------|:----------|:----------|:----------|:----------|:----------| +|300|18085.79|19198.89|25.28|23.95|6.15| +|600|22210.8|22877.58|42.61|41.85|3.00| +|900|25249.81|26431.12|55.82|53.85|4.68| + +Compared with v6.0.0, the Update Index performance of v6.1.0 is improved by 4.61%. + +![Update Index](/media/sysbench_v600vsv610_update_index.png) + +### Read Write performance + +| Threads | v6.0.0 TPS | v6.1.0 TPS | v6.0.0 95% latency (ms) | v6.1.0 95% latency (ms) | TPS improvement (%) | +|:----------|:----------|:----------|:----------|:----------|:----------| +|300|4856.23|4914.11|84.47|82.96|1.19| +|600|5676.46|5848.09|161.51|150.29|3.02| +|900|6072.97|6223.95|240.02|223.34|2.49| + +Compared with v6.0.0, the Read Write performance of v6.1.0 is improved by 2.23%. + +![Read Write](/media/sysbench_v600vsv610_read_write.png) diff --git a/benchmark/benchmark-sysbench-v6.2.0-vs-v6.1.0.md b/benchmark/benchmark-sysbench-v6.2.0-vs-v6.1.0.md new file mode 100644 index 0000000000000..f98bbf3130b13 --- /dev/null +++ b/benchmark/benchmark-sysbench-v6.2.0-vs-v6.1.0.md @@ -0,0 +1,199 @@ +--- +title: TiDB Sysbench Performance Test Report -- v6.2.0 vs. v6.1.0 +summary: TiDB v6.2.0 and v6.1.0 show similar performance in the Sysbench test. Point Select performance slightly drops by 3.58%. Update Non-index and Update Index performance are basically unchanged, reduced by 0.85% and 0.47% respectively. Read Write performance is reduced by 1.21%. +--- + +# TiDB Sysbench Performance Test Report -- v6.2.0 vs. v6.1.0 + +## Test overview + +This test aims at comparing the Sysbench performance of TiDB v6.2.0 and TiDB v6.1.0 in the Online Transactional Processing (OLTP) scenario. The results show that performance of v6.2.0 is basically the same as that of v6.1.0. The performance of Point Select slightly drops by 3.58%. + +## Test environment (AWS EC2） + +### Hardware configuration + +| Service type | EC2 type | Instance count | +|:----------|:----------|:----------| +| PD | m5.xlarge | 3 | +| TiKV | i3.4xlarge| 3 | +| TiDB | c5.4xlarge| 3 | +| Sysbench | c5.9xlarge| 1 | + +### Software version + +| Service type | Software version | +|:----------|:-----------| +| PD | v6.1.0 and v6.2.0 | +| TiDB | v6.1.0 and v6.2.0 | +| TiKV | v6.1.0 and v6.2.0 | +| Sysbench | 1.1.0-df89d34 | + +### Parameter configuration + +TiDB v6.2.0 and TiDB v6.1.0 use the same configuration. + +#### TiDB parameter configuration + +{{< copyable "" >}} + +```yaml +log.level: "error" +prepared-plan-cache.enabled: true +tikv-client.max-batch-wait-time: 2000000 +``` + +#### TiKV parameter configuration + +{{< copyable "" >}} + +```yaml +storage.scheduler-worker-pool-size: 5 +raftstore.store-pool-size: 3 +raftstore.apply-pool-size: 3 +rocksdb.max-background-jobs: 8 +server.grpc-concurrency: 6 +readpool.unified.max-thread-count: 10 +``` + +#### TiDB global variable configuration + +{{< copyable "sql" >}} + +```sql +set global tidb_hashagg_final_concurrency=1; +set global tidb_hashagg_partial_concurrency=1; +set global tidb_enable_async_commit = 1; +set global tidb_enable_1pc = 1; +set global tidb_guarantee_linearizability = 0; +set global tidb_enable_clustered_index = 1; +set global tidb_prepared_plan_cache_size=1000; +``` + +#### HAProxy configuration - haproxy.cfg + +For more details about how to use HAProxy on TiDB, see [Best Practices for Using HAProxy in TiDB](/best-practices/haproxy-best-practices.md). + +{{< copyable "" >}} + +```yaml +global # Global configuration. + pidfile /var/run/haproxy.pid # Writes the PIDs of HAProxy processes into this file. + maxconn 4000 # The maximum number of concurrent connections for a single HAProxy process. + user haproxy # The same with the UID parameter. + group haproxy # The same with the GID parameter. A dedicated user group is recommended. + nbproc 64 # The number of processes created when going daemon. When starting multiple processes to forward requests, ensure that the value is large enough so that HAProxy does not block processes. + daemon # Makes the process fork into background. It is equivalent to the command line "-D" argument. It can be disabled by the command line "-db" argument. + +defaults # Default configuration. + log global # Inherits the settings of the global configuration. + retries 2 # The maximum number of retries to connect to an upstream server. If the number of connection attempts exceeds the value, the backend server is considered unavailable. + timeout connect 2s # The maximum time to wait for a connection attempt to a backend server to succeed. It should be set to a shorter time if the server is located on the same LAN as HAProxy. + timeout client 30000s # The maximum inactivity time on the client side. + timeout server 30000s # The maximum inactivity time on the server side. + +listen tidb-cluster # Database load balancing. + bind 0.0.0.0:3390 # The Floating IP address and listening port. + mode tcp # HAProxy uses layer 4, the transport layer. + balance leastconn # The server with the fewest connections receives the connection. "leastconn" is recommended where long sessions are expected, such as LDAP, SQL and TSE, rather than protocols using short sessions, such as HTTP. The algorithm is dynamic, which means that server weights might be adjusted on the fly for slow starts for instance. + server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # Detects port 4000 at a frequency of once every 2000 milliseconds. If it is detected as successful twice, the server is considered available; if it is detected as failed three times, the server is considered unavailable. + server tidb-2 10.9.39.208:4000 check inter 2000 rise 2 fall 3 + server tidb-3 10.9.64.166:4000 check inter 2000 rise 2 fall 3 +``` + +## Test plan + +1. Deploy TiDB v6.2.0 and v6.1.0 using TiUP. +2. Use Sysbench to import 16 tables, each table with 10 million rows of data. +3. Execute the `analyze table` statement on each table. +4. Back up the data used for restore before different concurrency tests, which ensures data consistency for each test. +5. Start the Sysbench client to perform the `point_select`, `read_write`, `update_index`, and `update_non_index` tests. Perform stress tests on TiDB via HAProxy. For each concurrency under each workload, the test takes 20 minutes. +6. After each type of test is completed, stop the cluster, overwrite the cluster with the backup data in step 4, and restart the cluster. + +### Prepare test data + +Run the following command to prepare the test data: + +{{< copyable "shell-regular" >}} + +```bash +sysbench oltp_common \ + --threads=16 \ + --rand-type=uniform \ + --db-driver=mysql \ + --mysql-db=sbtest \ + --mysql-host=$aws_nlb_host \ + --mysql-port=$aws_nlb_port \ + --mysql-user=root \ + --mysql-password=password \ + prepare --tables=16 --table-size=10000000 +``` + +### Perform the test + +Run the following command to perform the test: + +{{< copyable "shell-regular" >}} + +```bash +sysbench $testname \ + --threads=$threads \ + --time=1200 \ + --report-interval=1 \ + --rand-type=uniform \ + --db-driver=mysql \ + --mysql-db=sbtest \ + --mysql-host=$aws_nlb_host \ + --mysql-port=$aws_nlb_port \ + run --tables=16 --table-size=10000000 +``` + +## Test results + +### Point Select performance + +| Threads | v6.1.0 TPS | v6.2.0 TPS | v6.1.0 95% latency (ms) | v6.2.0 95% latency (ms) | TPS improvement (%) | +| :------ | :--------- | :--------- | :---------------------- | :---------------------- | :----------- | +| 300 | 243530.01 | 236885.24 | 1.93 | 2.07 | -2.73 | +| 600 | 304121.47 | 291395.84 | 3.68 | 4.03 | -4.18 | +| 900 | 327301.23 | 314720.02 | 5 | 5.47 | -3.84 | + +Compared with v6.1.0, the Point Select performance of v6.2.0 slightly drops by 3.58%. + +![Point Select](/media/sysbench_v610vsv620_point_select.png) + +### Update Non-index performance + +| Threads | v6.1.0 TPS | v6.2.0 TPS | v6.1.0 95% latency (ms) | v6.2.0 95% latency (ms) | TPS improvement (%) | +| :------ | :--------- | :--------- | :---------------------- | :---------------------- | :----------- | +| 300 | 42608.8 | 42372.82 | 11.45 | 11.24 | -0.55 | +| 600 | 54264.47 | 53672.69 | 18.95 | 18.95 | -1.09 | +| 900 | 60667.47 | 60116.14 | 26.2 | 26.68 | -0.91 | + +Compared with v6.1.0, the Update Non-index performance of v6.2.0 is basically unchanged, reduced by 0.85%. + +![Update Non-index](/media/sysbench_v610vsv620_update_non_index.png) + +### Update Index performance + +| Threads | v6.1.0 TPS | v6.2.0 TPS | v6.1.0 95% latency (ms) | v6.2.0 95% latency (ms) | TPS improvement (%) | +| :------ | :--------- | :--------- | :---------------------- | :---------------------- | :----------- | +| 300 | 19384.75 | 19353.58 | 23.52 | 23.52 | -0.16 | +| 600 | 24144.78 | 24007.57 | 38.25 | 37.56 | -0.57 | +| 900 | 26770.9 | 26589.84 | 51.94 | 52.89 | -0.68 | + +Compared with v6.1.0, the Update Index performance of v6.2.0 is basically unchanged, reduced by 0.47%. + +![Update Index](/media/sysbench_v610vsv620_update_index.png) + +### Read Write performance + +| Threads | v6.1.0 TPS | v6.2.0 TPS | v6.1.0 95% latency (ms) | v6.2.0 95% latency (ms) | TPS improvement (%) | +| :------ | :--------- | :--------- | :---------------------- | :---------------------- | :----------- | +| 300 | 4849.67 | 4797.59 | 86 | 84.47 | -1.07 | +| 600 | 5643.89 | 5565.17 | 161.51 | 161.51 | -1.39 | +| 900 | 5954.91 | 5885.22 | 235.74 | 235.74 | -1.17 | + +Compared with v6.1.0, the Read Write performance of v6.2.0 is reduced by 1.21%. + +![Read Write](/media/sysbench_v610vsv620_read_write.png) diff --git a/benchmark/v5.0-performance-benchmarking-with-tpcc.md b/benchmark/v5.0-performance-benchmarking-with-tpcc.md new file mode 100644 index 0000000000000..5472e67664cca --- /dev/null +++ b/benchmark/v5.0-performance-benchmarking-with-tpcc.md @@ -0,0 +1,149 @@ +--- +title: TiDB TPC-C Performance Test Report -- v5.0 vs. v4.0 +summary: TiDB v5.0 outperforms v4.0 in TPC-C performance, showing a 36% increase. +--- + +# TiDB TPC-C Performance Test Report -- v5.0 vs. v4.0 + +## Test purpose + +This test aims at comparing the TPC-C performance of TiDB v5.0 and TiDB v4.0 in the Online Transactional Processing (OLTP) scenario. + +## Test environment (AWS EC2) + +### Hardware configuration + +| Service type | EC2 type | Instance count | +|:----------|:----------|:----------| +| PD | m5.xlarge | 3 | +| TiKV | i3.4xlarge| 3 | +| TiDB | c5.4xlarge| 3 | +| TPC-C | c5.9xlarge| 1 | + +### Software version + +| Service type | Software version | +|:----------|:-----------| +| PD | 4.0 and 5.0 | +| TiDB | 4.0 and 5.0 | +| TiKV | 4.0 and 5.0 | +| BenchmarkSQL | None | + +### Parameter configuration + +#### TiDB v4.0 configuration + +{{< copyable "" >}} + +```yaml +log.level: "error" +performance.max-procs: 20 +prepared-plan-cache.enabled: true +tikv-client.max-batch-wait-time: 2000000 +``` + +#### TiKV v4.0 configuration + +{{< copyable "" >}} + +```yaml +pessimistic-txn.pipelined: true +raftdb.allow-concurrent-memtable-write: true +raftdb.max-background-jobs: 4 +raftstore.apply-max-batch-size: 2048 +raftstore.apply-pool-size: 3 +raftstore.store-max-batch-size: 2048 +raftstore.store-pool-size: 3 +readpool.storage.normal-concurrency: 10 +readpool.unified.max-thread-count: 20 +readpool.unified.min-thread-count: 5 +rocksdb.max-background-jobs: 8 +server.grpc-concurrency: 6 +storage.scheduler-worker-pool-size: 20 +``` + +#### TiDB v5.0 configuration + +{{< copyable "" >}} + +```yaml +log.level: "error" +performance.max-procs: 20 +prepared-plan-cache.enabled: true +tikv-client.max-batch-wait-time: 2000000 +``` + +#### TiKV v5.0 configuration + +{{< copyable "" >}} + +```yaml +pessimistic-txn.pipelined: true +raftdb.allow-concurrent-memtable-write: true +raftdb.max-background-jobs: 4 +raftstore.apply-max-batch-size: 2048 +raftstore.apply-pool-size: 3 +raftstore.store-max-batch-size: 2048 +raftstore.store-pool-size: 3 +readpool.storage.normal-concurrency: 10 +readpool.unified.max-thread-count: 20 +readpool.unified.min-thread-count: 5 +rocksdb.max-background-jobs: 8 +server.grpc-concurrency: 6 +storage.scheduler-worker-pool-size: 20 +server.enable-request-batch: false +``` + +#### TiDB v4.0 global variable configuration + +{{< copyable "sql" >}} + +```sql +set global tidb_hashagg_final_concurrency=1; +set global tidb_hashagg_partial_concurrency=1; +``` + +#### TiDB v5.0 global variable configuration + +{{< copyable "sql" >}} + +```sql +set global tidb_hashagg_final_concurrency=1; +set global tidb_hashagg_partial_concurrency=1; +set global tidb_enable_async_commit = 1; +set global tidb_enable_1pc = 1; +set global tidb_guarantee_linearizability = 0; +set global tidb_enable_clustered_index = 1; +``` + +## Test plan + +1. Deploy TiDB v5.0 and v4.0 using TiUP. + +2. Use BenchmarkSQL to import the TPC-C 5000 Warehouse data. + + 1. Compile BenchmarkSQL: + + {{< copyable "bash" >}} + + ```bash + git clone https://github.com/pingcap/benchmarksql && cd benchmarksql && ant + ``` + + 2. Enter the `run` directory, edit the `props.mysql` file according to the actual situation, and modify the `conn`, `warehouses`, `loadWorkers`, `terminals`, and `runMins` configuration items. + + 3. Execute the `runSQL.sh ./props.mysql sql.mysql/tableCreates.sql` command. + + 4. Execute the `runSQL.sh ./props.mysql sql.mysql/indexCreates.sql` command. + + 5. Run MySQL client and execute the `analyze table` statement on every table. + +3. Execute the `runBenchmark.sh ./props.mysql` command. + +4. Extract the tpmC data of New Order from the result. + +## Test result + +According to the test statistics, the TPC-C performance of TiDB v5.0 has **increased by 36%** compared with that of TiDB v4.0. + +![TPC-C](/media/tpcc_v5vsv4_corrected_v2.png) diff --git a/benchmark/v5.1-performance-benchmarking-with-tpcc.md b/benchmark/v5.1-performance-benchmarking-with-tpcc.md new file mode 100644 index 0000000000000..a9d8a26503b69 --- /dev/null +++ b/benchmark/v5.1-performance-benchmarking-with-tpcc.md @@ -0,0 +1,93 @@ +--- +title: TiDB TPC-C Performance Test Report -- v5.1.0 vs. v5.0.2 +summary: TiDB v5.1.0 TPC-C performance is 2.8% better than v5.0.2. Parameter configuration is the same for both versions. Test plan includes deployment, database creation, data import, stress testing, and result extraction. +--- + +# TiDB TPC-C Performance Test Report -- v5.1.0 vs. v5.0.2 + +## Test overview + +This test aims to compare the TPC-H performance of TiDB v5.1.0 and TiDB v5.0.2 in the online analytical processing (OLAP) scenario. The results show that compared with v5.0.2, the TPC-C performance of v5.1.0 is improved by 2.8%. + +## Test environment (AWS EC2) + +## Hardware configuration + +| Service type | EC2 type | Instance count | +|:----------|:----------|:----------| +| PD | m5.xlarge | 3 | +| TiKV | i3.4xlarge| 3 | +| TiDB | c5.4xlarge| 3 | +| TPC-C | c5.9xlarge| 1 | + +### Software version + +| Service type | Software version | +|:----------|:-----------| +| PD | v5.0.2 and v5.1.0 | +| TiDB | v5.0.2 and v5.1.0 | +| TiKV | v5.0.2 and v5.1.0 | +| TiUP | 1.5.1 | + +### Parameter configuration + +TiDB v5.1.0 and TiDB v5.0.2 use the same configuration. + +#### TiDB parameter configuration + +{{< copyable "" >}} + +```yaml +log.level: "error" +performance.max-procs: 20 +prepared-plan-cache.enabled: true +tikv-client.max-batch-wait-time: 2000000 +``` + +#### TiKV parameter configuration + +{{< copyable "" >}} + +```yaml +pessimistic-txn.pipelined: true +raftdb.allow-concurrent-memtable-write: true +raftdb.max-background-jobs: 4 +raftstore.apply-max-batch-size: 2048 +raftstore.apply-pool-size: 3 +raftstore.store-max-batch-size: 2048 +raftstore.store-pool-size: 3 +readpool.storage.normal-concurrency: 10 +readpool.unified.max-thread-count: 20 +readpool.unified.min-thread-count: 5 +rocksdb.max-background-jobs: 8 +server.grpc-concurrency: 6 +storage.scheduler-worker-pool-size: 20 +server.enable-request-batch: false +``` + +#### TiDB global variable configuration + +{{{< copyable "sql" >}} + +```sql +set global tidb_hashagg_final_concurrency=1; +set global tidb_hashagg_partial_concurrency=1; +set global tidb_enable_async_commit = 1; +set global tidb_enable_1pc = 1; +set global tidb_guarantee_linearizability = 0; +set global tidb_enable_clustered_index = 1; +``` + +## Test plan + +1. Deploy TiDB v5.1.0 and v5.0.2 using TiUP. +2. Create a database named `tpcc`: `create database tpcc;`. +3. Use BenchmarkSQL to import the TPC-C 5000 Warehouse data: `tiup bench tpcc prepare --warehouses 5000 --db tpcc -H 127.0.0.1 -p 4000`. +4. Execute the `tiup bench tpcc run -U root --db tpcc --host 127.0.0.1 --port 4000 --time 300s --warehouses 5000 --threads {{thread}}` command to perform stress tests on TiDB via HAProxy. +5. Extract the tpmC data of New Order from the result. + +## Test result + +Compared with v5.0.2, the TPC-C performance of v5.1.0 is **improved by 2.8%**. + +![TPC-C](/media/tpcc_v510_vs_v502.png) diff --git a/benchmark/v5.2-performance-benchmarking-with-tpcc.md b/benchmark/v5.2-performance-benchmarking-with-tpcc.md new file mode 100644 index 0000000000000..8d26565e7f607 --- /dev/null +++ b/benchmark/v5.2-performance-benchmarking-with-tpcc.md @@ -0,0 +1,93 @@ +--- +title: TiDB TPC-C Performance Test Report -- v5.2.0 vs. v5.1.1 +summary: TiDB v5.2.0 TPC-C performance is 4.22% lower than v5.1.1. Test environment AWS EC2. Hardware and software configurations are the same for both versions. Test plan includes deployment, database creation, data import, stress testing, and result extraction. +--- + +# TiDB TPC-C Performance Test Report -- v5.2.0 vs. v5.1.1 + +## Test overview + +This test aims to compare the TPC-C performance of TiDB v5.2.0 and TiDB v5.1.1 in the online transactional processing (OLTP) scenario. The results show that compared with v5.1.1, the TPC-C performance of v5.2.0 is reduced by 4.22%. + +## Test environment (AWS EC2) + +## Hardware configuration + +| Service type | EC2 type | Instance count | +|:----------|:----------|:----------| +| PD | m5.xlarge | 3 | +| TiKV | i3.4xlarge| 3 | +| TiDB | c5.4xlarge| 3 | +| TPC-C | c5.9xlarge| 1 | + +### Software version + +| Service type | Software version | +|:----------|:-----------| +| PD | v5.1.1 and v5.2.0 | +| TiDB | v5.1.1 and v5.2.0 | +| TiKV | v5.1.1 and v5.2.0 | +| TiUP | 1.5.1 | + +### Parameter configuration + +TiDB v5.2.0 and TiDB v5.1.1 use the same configuration. + +#### TiDB parameter configuration + +{{< copyable "" >}} + +```yaml +log.level: "error" +performance.max-procs: 20 +prepared-plan-cache.enabled: true +tikv-client.max-batch-wait-time: 2000000 +``` + +#### TiKV parameter configuration + +{{< copyable "" >}} + +```yaml +pessimistic-txn.pipelined: true +raftdb.allow-concurrent-memtable-write: true +raftdb.max-background-jobs: 4 +raftstore.apply-max-batch-size: 2048 +raftstore.apply-pool-size: 3 +raftstore.store-max-batch-size: 2048 +raftstore.store-pool-size: 3 +readpool.storage.normal-concurrency: 10 +readpool.unified.max-thread-count: 20 +readpool.unified.min-thread-count: 5 +rocksdb.max-background-jobs: 8 +server.grpc-concurrency: 6 +storage.scheduler-worker-pool-size: 20 +server.enable-request-batch: false +``` + +#### TiDB global variable configuration + +{{{< copyable "sql" >}} + +```sql +set global tidb_hashagg_final_concurrency=1; +set global tidb_hashagg_partial_concurrency=1; +set global tidb_enable_async_commit = 1; +set global tidb_enable_1pc = 1; +set global tidb_guarantee_linearizability = 0; +set global tidb_enable_clustered_index = 1; +``` + +## Test plan + +1. Deploy TiDB v5.2.0 and v5.1.1 using TiUP. +2. Create a database named `tpcc`: `create database tpcc;`. +3. Use BenchmarkSQL to import the TPC-C 5000 Warehouse data: `tiup bench tpcc prepare --warehouses 5000 --db tpcc -H 127.0.0.1 -p 4000`. +4. Execute the `tiup bench tpcc run -U root --db tpcc --host 127.0.0.1 --port 4000 --time 300s --warehouses 5000 --threads {{thread}}` command to perform stress tests on TiDB via HAProxy. +5. Extract the tpmC data of New Order from the result. + +## Test result + +Compared with v5.1.1, the TPC-C performance of v5.2.0 is **reduced by 4.22%**. + +![TPC-C](/media/tpcc_v511_vs_v520.png) diff --git a/benchmark/v5.3-performance-benchmarking-with-tpcc.md b/benchmark/v5.3-performance-benchmarking-with-tpcc.md new file mode 100644 index 0000000000000..a5a4c35261850 --- /dev/null +++ b/benchmark/v5.3-performance-benchmarking-with-tpcc.md @@ -0,0 +1,129 @@ +--- +title: TiDB TPC-C Performance Test Report -- v5.3.0 vs. v5.2.2 +summary: TiDB v5.3.0 TPC-C performance is slightly reduced by 2.99% compared to v5.2.2. The test used AWS EC2 with specific hardware and software configurations. The test plan involved deploying TiDB, creating a database, importing data, and running stress tests. The result showed a decrease in performance across different thread counts. +--- + +# TiDB TPC-C Performance Test Report -- v5.3.0 vs. v5.2.2 + +## Test overview + +This test aims at comparing the TPC-C performance of TiDB v5.3.0 and TiDB v5.2.2 in the online transactional processing (OLTP) scenario. The result shows that compared with v5.2.2, the TPC-C performance of v5.3.0 is reduced by 2.99%. + +## Test environment (AWS EC2) + +## Hardware configuration + +| Service type | EC2 type | Instance count | +|:----------|:----------|:----------| +| PD | m5.xlarge | 3 | +| TiKV | i3.4xlarge| 3 | +| TiDB | c5.4xlarge| 3 | +| TPC-C | c5.9xlarge| 1 | + +### Software version + +| Service type | Software version | +|:----------|:-----------| +| PD | v5.2.2 and v5.3.0 | +| TiDB | v5.2.2 and v5.3.0 | +| TiKV | v5.2.2 and v5.3.0 | +| TiUP | 1.5.1 | + +### Parameter configuration + +TiDB v5.3.0 and TiDB v5.2.2 use the same configuration. + +#### TiDB parameter configuration + +{{< copyable "" >}} + +```yaml +log.level: "error" +performance.max-procs: 20 +prepared-plan-cache.enabled: true +tikv-client.max-batch-wait-time: 2000000 +``` + +#### TiKV parameter configuration + +{{< copyable "" >}} + +```yaml +pessimistic-txn.pipelined: true +raftdb.allow-concurrent-memtable-write: true +raftdb.max-background-jobs: 4 +raftstore.apply-max-batch-size: 2048 +raftstore.apply-pool-size: 3 +raftstore.store-max-batch-size: 2048 +raftstore.store-pool-size: 3 +readpool.storage.normal-concurrency: 10 +readpool.unified.max-thread-count: 20 +readpool.unified.min-thread-count: 5 +rocksdb.max-background-jobs: 8 +server.grpc-concurrency: 6 +storage.scheduler-worker-pool-size: 20 +``` + +#### TiDB global variable configuration + +{{< copyable "sql" >}} + +```sql +set global tidb_hashagg_final_concurrency=1; +set global tidb_hashagg_partial_concurrency=1; +set global tidb_enable_async_commit = 1; +set global tidb_enable_1pc = 1; +set global tidb_guarantee_linearizability = 0; +set global tidb_enable_clustered_index = 1; +``` + +#### HAProxy configuration - haproxy.cfg + +For more details about how to use HAProxy on TiDB, see [Best Practices for Using HAProxy in TiDB](/best-practices/haproxy-best-practices.md). + +```yaml +global # Global configuration. + chroot /var/lib/haproxy # Changes the current directory and sets superuser privileges for the startup process to improve security. + pidfile /var/run/haproxy.pid # Writes the PIDs of HAProxy processes into this file. + maxconn 4000 # The maximum number of concurrent connections for a single HAProxy process. + user haproxy # Same with the UID parameter. + group haproxy # Same with the GID parameter. A dedicated user group is recommended. + nbproc 64 # The number of processes created when going daemon. When starting multiple processes to forward requests, ensure that the value is large enough so that HAProxy does not block processes. + daemon # Makes the process fork into background. It is equivalent to the command line "-D" argument. It can be disabled by the command line "-db" argument. + +defaults # Default configuration. + log global # Inherits the settings of the global configuration. + retries 2 # The maximum number of retries to connect to an upstream server. If the number of connection attempts exceeds the value, the backend server is considered unavailable. + timeout connect 2s # The maximum time to wait for a connection attempt to a backend server to succeed. It should be set to a shorter time if the server is located on the same LAN as HAProxy. + timeout client 30000s # The maximum inactivity time on the client side. + timeout server 30000s # The maximum inactivity time on the server side. + +listen tidb-cluster # Database load balancing. + bind 0.0.0.0:3390 # The Floating IP address and listening port. + mode tcp # HAProxy uses layer 4, the transport layer. + balance roundrobin # The server with the fewest connections receives the connection. "leastconn" is recommended where long sessions are expected, such as LDAP, SQL and TSE, rather than protocols using short sessions, such as HTTP. The algorithm is dynamic, which means that server weights might be adjusted on the fly for slow starts for instance. + server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # Detects port 4000 at a frequency of once every 2000 milliseconds. If it is detected as successful twice, the server is considered available; if it is detected as failed three times, the server is considered unavailable. + server tidb-2 10.9.39.208:4000 check inter 2000 rise 2 fall 3 + server tidb-3 10.9.64.166:4000 check inter 2000 rise 2 fall 3 +``` + +## Test plan + +1. Deploy TiDB v5.3.0 and v5.2.2 using TiUP. +2. Create a database named `tpcc`: `create database tpcc;`. +3. Use BenchmarkSQL to import the TPC-C 5000 Warehouse data: `tiup bench tpcc prepare --warehouses 5000 --db tpcc -H 127.0.0.1 -p 4000`. +4. Run the `tiup bench tpcc run -U root --db tpcc --host 127.0.0.1 --port 4000 --time 1800s --warehouses 5000 --threads {{thread}}` command to perform stress tests on TiDB via HAProxy. For each concurrency, the test takes 30 minutes. +5. Extract the tpmC data of New Order from the result. + +## Test result + +Compared with v5.2.2, the TPC-C performance of v5.3.0 is **reduced slightly by 2.99%**. + +| Threads | v5.2.2 tpmC | v5.3.0 tpmC | tpmC improvement (%) | +|:----------|:----------|:----------|:----------| +|50|42228.8|41580|-1.54| +|100|49400|48248.2|-2.33| +|200|54436.6|52809.4|-2.99| +|400|57026.7|54117.1|-5.10| + +![TPC-C](/media/tpcc_v522_vs_v530.png) \ No newline at end of file diff --git a/benchmark/v5.4-performance-benchmarking-with-tpcc.md b/benchmark/v5.4-performance-benchmarking-with-tpcc.md new file mode 100644 index 0000000000000..05be43f4ca314 --- /dev/null +++ b/benchmark/v5.4-performance-benchmarking-with-tpcc.md @@ -0,0 +1,129 @@ +--- +title: TiDB TPC-C Performance Test Report -- v5.4.0 vs. v5.3.0 +summary: TiDB v5.4.0 TPC-C performance is 3.16% better than v5.3.0. The improvement is consistent across different thread counts 2.80% (50 threads), 4.27% (100 threads), 3.45% (200 threads), and 2.11% (400 threads). +--- + +# TiDB TPC-C Performance Test Report -- v5.4.0 vs. v5.3.0 + +## Test overview + +This test aims at comparing the TPC-C performance of TiDB v5.4.0 and v5.3.0 in the Online Transactional Processing (OLTP) scenario. The results show that compared with v5.3.0, the TPC-C performance of v5.4.0 is improved by 3.16%. + +## Test environment (AWS EC2） + +### Hardware configuration + +| Service type | EC2 type | Instance count | +|:----------|:----------|:----------| +| PD | m5.xlarge | 3 | +| TiKV | i3.4xlarge| 3 | +| TiDB | c5.4xlarge| 3 | +| TPC-C | c5.9xlarge| 1 | + +### Software version + +| Service type | Software version | +|:----------|:-----------| +| PD | v5.3.0 and v5.4.0 | +| TiDB | v5.3.0 and v5.4.0 | +| TiKV | v5.3.0 and v5.4.0 | +| TiUP | 1.5.1 | + +### Parameter configuration + +TiDB v5.4.0 and TiDB v5.3.0 use the same configuration. + +#### TiDB parameter configuration + +{{< copyable "" >}} + +```yaml +log.level: "error" +performance.max-procs: 20 +prepared-plan-cache.enabled: true +tikv-client.max-batch-wait-time: 2000000 +``` + +#### TiKV parameter configuration + +{{< copyable "" >}} + +```yaml +pessimistic-txn.pipelined: true +raftdb.allow-concurrent-memtable-write: true +raftdb.max-background-jobs: 4 +raftstore.apply-max-batch-size: 2048 +raftstore.apply-pool-size: 3 +raftstore.store-max-batch-size: 2048 +raftstore.store-pool-size: 3 +readpool.storage.normal-concurrency: 10 +readpool.unified.max-thread-count: 20 +readpool.unified.min-thread-count: 5 +rocksdb.max-background-jobs: 8 +server.grpc-concurrency: 6 +storage.scheduler-worker-pool-size: 20 +``` + +#### TiDB global variable configuration + +{{< copyable "sql" >}} + +```sql +set global tidb_hashagg_final_concurrency=1; +set global tidb_hashagg_partial_concurrency=1; +set global tidb_enable_async_commit = 1; +set global tidb_enable_1pc = 1; +set global tidb_guarantee_linearizability = 0; +set global tidb_enable_clustered_index = 1; +``` + +#### HAProxy configuration - haproxy.cfg + +For more details about how to use HAProxy on TiDB, see [Best Practices for Using HAProxy in TiDB](/best-practices/haproxy-best-practices.md). + +{{< copyable "" >}} + +```yaml +global # Global configuration. + chroot /var/lib/haproxy # Changes the current directory and sets superuser privileges for the startup process to improve security. + pidfile /var/run/haproxy.pid # Writes the PIDs of HAProxy processes into this file. + maxconn 4000 # The maximum number of concurrent connections for a single HAProxy process. + user haproxy # The same with the UID parameter. + group haproxy # The same with the GID parameter. A dedicated user group is recommended. + nbproc 64 # The number of processes created when going daemon. When starting multiple processes to forward requests, ensure that the value is large enough so that HAProxy does not block processes. + daemon # Makes the process fork into background. It is equivalent to the command line "-D" argument. It can be disabled by the command line "-db" argument. +defaults # Default configuration. + log global # Inherits the settings of the global configuration. + retries 2 # The maximum number of retries to connect to an upstream server. If the number of connection attempts exceeds the value, the backend server is considered unavailable. + timeout connect 2s # The maximum time to wait for a connection attempt to a backend server to succeed. It should be set to a shorter time if the server is located on the same LAN as HAProxy. + timeout client 30000s # The maximum inactivity time on the client side. + timeout server 30000s # The maximum inactivity time on the server side. +listen tidb-cluster # Database load balancing. + bind 0.0.0.0:3390 # The Floating IP address and listening port. + mode tcp # HAProxy uses layer 4, the transport layer. + balance roundrobin # The server with the fewest connections receives the connection. "leastconn" is recommended where long sessions are expected, such as LDAP, SQL and TSE, rather than protocols using short sessions, such as HTTP. The algorithm is dynamic, which means that server weights might be adjusted on the fly for slow starts for instance. + server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # Detects port 4000 at a frequency of once every 2000 milliseconds. If it is detected as successful twice, the server is considered available; if it is detected as failed three times, the server is considered unavailable. + server tidb-2 10.9.39.208:4000 check inter 2000 rise 2 fall 3 + server tidb-3 10.9.64.166:4000 check inter 2000 rise 2 fall 3 +``` + +### Prepare test data + +1. Deploy TiDB v5.4.0 and v5.3.0 using TiUP. +2. Create a database named `tpcc`: `create database tpcc;`. +3. Use BenchmarkSQL to import the TPC-C 5000 Warehouse data: `tiup bench tpcc prepare --warehouses 5000 --db tpcc -H 127.0.0.1 -P 4000`. +4. Run the `tiup bench tpcc run -U root --db tpcc --host 127.0.0.1 --port 4000 --time 1800s --warehouses 5000 --threads {{thread}}` command to perform stress tests on TiDB via HAProxy. For each concurrency, the test takes 30 minutes. +5. Extract the tpmC data of New Order from the result. + +## Test result + +Compared with v5.3.0, the TPC-C performance of v5.4.0 is **improved by 3.16%**. + +| Threads | v5.3.0 tpmC | v5.4.0 tpmC | tpmC improvement (%) | +|:----------|:----------|:----------|:----------| +|50|43002.4|44204.4|2.80| +|100|50162.7|52305|4.27| +|200|55768.2|57690.7|3.45| +|400|56836.8|58034.6|2.11| + +![TPC-C](/media/tpcc_v530_vs_v540.png) diff --git a/benchmark/v5.4-performance-benchmarking-with-tpch.md b/benchmark/v5.4-performance-benchmarking-with-tpch.md new file mode 100644 index 0000000000000..c459c56268f35 --- /dev/null +++ b/benchmark/v5.4-performance-benchmarking-with-tpch.md @@ -0,0 +1,128 @@ +--- +title: TiDB TPC-H Performance Test Report -- v5.4 MPP mode vs. Greenplum 6.15.0 and Apache Spark 3.1.1 +summary: TiDB v5.4 MPP mode outperforms Greenplum 6.15.0 and Apache Spark 3.1.1 in TPC-H 100 GB performance test. TiDB's MPP mode is 2-3 times faster. Test results show TiDB v5.4 has significantly lower query execution times compared to Greenplum and Apache Spark. +--- + +# TiDB TPC-H Performance Test Report -- TiDB v5.4 MPP mode vs. Greenplum 6.15.0 and Apache Spark 3.1.1 + +## Test overview + +This test aims at comparing the TPC-H 100 GB performance of TiDB v5.4 in the MPP mode with that of Greenplum and Apache Spark, two mainstream analytics engines, in their latest versions. The test result shows that the performance of TiDB v5.4 in the MPP mode is two to three times faster than that of the other two solutions under TPC-H workload. + +In v5.0, TiDB introduces the MPP mode for [TiFlash](/tiflash/tiflash-overview.md), which significantly enhances TiDB's Hybrid Transactional and Analytical Processing (HTAP) capabilities. Test objects in this report are as follows: + ++ TiDB v5.4 columnar storage in the MPP mode ++ Greenplum 6.15.0 ++ Apache Spark 3.1.1 + Parquet + +## Test environment + +### Hardware prerequisite + +| Instance type | Instance count | +|:----------|:----------| +| PD | 1 | +| TiDB | 1 | +| TiKV | 3 | +| TiFlash | 3 | + ++ CPU: Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz, 40 cores ++ Memory: 189 GB ++ Disks: NVMe 3TB * 2 + +### Software version + +| Service type | Software version | +|:----------|:-----------| +| TiDB | 5.4 | +| Greenplum | 6.15.0 | +| Apache Spark | 3.1.1 | + +### Parameter configuration + +#### TiDB v5.4 + +For the v5.4 cluster, TiDB uses the default parameter configuration except for the following configuration items. + +In the configuration file `users.toml` of TiFlash, configure `max_memory_usage` as follows: + +```toml +[profiles.default] +max_memory_usage = 10000000000000 +``` + +Set session variables with the following SQL statements: + +```sql +set @@tidb_isolation_read_engines='tiflash'; +set @@tidb_allow_mpp=1; +set @@tidb_mem_quota_query = 10 << 30; +``` + +All TPC-H test tables are replicated to TiFlash in columnar format, with no additional partitions or indexes. + +#### Greenplum + +Except for the initial 3 nodes, the Greenplum cluster is deployed using an additional master node. Each segment server contains 8 segments, which means 4 segments per NVMe SSD. So there are 24 segments in total. The storage format is append-only/column-oriented storage and partition keys are used as primary keys. + +{{< copyable "" >}} + +``` +log_statement = all +gp_autostats_mode = none +statement_mem = 2048MB +gp_vmem_protect_limit = 16384 +``` + +#### Apache Spark + +The test of Apache Spark uses Apache Parquet as the storage format and stores the data on HDFS. The HDFS system consists of three nodes. Each node has two assigned NVMe SSD disks as the data disks. The Spark cluster is deployed in standalone mode, using NVMe SSD disks as the local directory of `spark.local.dir` to speed up the shuffle spill, with no additional partitions or indexes. + +{{< copyable "" >}} + +``` +--driver-memory 20G +--total-executor-cores 120 +--executor-cores 5 +--executor-memory 15G +``` + +## Test result + +> **Note:** +> +> The following test results are the average data of three tests. All numbers are in seconds. + +| Query ID | TiDB v5.4 | Greenplum 6.15.0 | Apache Spark 3.1.1 + Parquet | +| :-------- | :----------- | :------------ | :-------------- | +| 1 | 8.08 | 64.1307 | 52.64 | +| 2 | 2.53 | 4.76612 | 11.83 | +| 3 | 4.84 | 15.62898 | 13.39 | +| 4 | 10.94 | 12.88318 | 8.54 | +| 5 | 12.27 | 23.35449 | 25.23 | +| 6 | 1.32 | 6.033 | 2.21 | +| 7 | 5.91 | 12.31266 | 25.45 | +| 8 | 6.71 | 11.82444 | 23.12 | +| 9 | 44.19 | 22.40144 | 35.2 | +| 10 | 7.13 | 12.51071 | 12.18 | +| 11 | 2.18 | 2.6221 | 10.99 | +| 12 | 2.88 | 7.97906 | 6.99 | +| 13 | 6.84 | 10.15873 | 12.26 | +| 14 | 1.69 | 4.79394 | 3.89 | +| 15 | 3.29 | 10.48785 | 9.82 | +| 16 | 5.04 | 4.64262 | 6.76 | +| 17 | 11.7 | 74.65243 | 44.65 | +| 18 | 12.87 | 64.87646 | 30.27 | +| 19 | 4.75 | 8.08625 | 4.7 | +| 20 | 8.89 | 15.47016 | 8.4 | +| 21 | 24.44 | 39.08594 | 34.83 | +| 22 | 1.23 | 7.67476 | 4.59 | + +![TPC-H](/media/tidb-v5.4-tpch-100-vs-gp-spark.png) + +In the performance diagram above: + +- Blue lines represent TiDB v5.4; +- Red lines represent Greenplum 6.15.0; +- Yellow lines represent Apache Spark 3.1.1. +- The y-axis represents the execution time of the query. The less the time is, the better the performance is. diff --git a/benchmark/v6.0-performance-benchmarking-with-tpcc.md b/benchmark/v6.0-performance-benchmarking-with-tpcc.md new file mode 100644 index 0000000000000..e8fa4c4a9e278 --- /dev/null +++ b/benchmark/v6.0-performance-benchmarking-with-tpcc.md @@ -0,0 +1,125 @@ +--- +title: TiDB TPC-C Performance Test Report -- v6.0.0 vs. v5.4.0 +summary: TiDB v6.0.0 TPC-C performance is 24.20% better than v5.4.0. The improvement is consistent across different thread counts, with the highest improvement at 26.97% for 100 threads. +--- + +# TiDB TPC-C Performance Test Report -- v6.0.0 vs. v5.4.0 + +## Test overview + +This test aims at comparing the TPC-C performance of TiDB v6.0.0 and v5.4.0 in the Online Transactional Processing (OLTP) scenario. The results show that compared with v5.4.0, the TPC-C performance of v6.0.0 is improved by 24.20%. + +## Test environment (AWS EC2） + +### Hardware configuration + +| Service type | EC2 type | Instance count | +|:----------|:----------|:----------| +| PD | m5.xlarge | 3 | +| TiKV | i3.4xlarge| 3 | +| TiDB | c5.4xlarge| 3 | +| TPC-C | c5.9xlarge| 1 | + +### Software version + +| Service type | Software version | +| :----------- | :---------------- | +| PD | v5.4.0 and v6.0.0 | +| TiDB | v5.4.0 and v6.0.0 | +| TiKV | v5.4.0 and v6.0.0 | +| TiUP | 1.9.3 | +| HAProxy | 2.5.0 | + +### Parameter configuration + +TiDB v6.0.0 and TiDB v5.4.0 use the same configuration. + +#### TiDB parameter configuration + +{{< copyable "" >}} + +```yaml +log.level: "error" +prepared-plan-cache.enabled: true +tikv-client.max-batch-wait-time: 2000000 +``` + +#### TiKV parameter configuration + +{{< copyable "" >}} + +```yaml +pessimistic-txn.pipelined: true +raftdb.allow-concurrent-memtable-write: true +raftdb.max-background-jobs: 4 +raftstore.apply-max-batch-size: 2048 +raftstore.apply-pool-size: 3 +raftstore.store-max-batch-size: 2048 +raftstore.store-pool-size: 3 +readpool.storage.normal-concurrency: 10 +rocksdb.max-background-jobs: 8 +server.grpc-concurrency: 6 +``` + +#### TiDB global variable configuration + +{{< copyable "sql" >}} + +```sql +set global tidb_hashagg_final_concurrency=1; +set global tidb_hashagg_partial_concurrency=1; +set global tidb_enable_async_commit = 1; +set global tidb_enable_1pc = 1; +set global tidb_guarantee_linearizability = 0; +set global tidb_enable_clustered_index = 1; +``` + +#### HAProxy configuration - haproxy.cfg + +For more details about how to use HAProxy on TiDB, see [Best Practices for Using HAProxy in TiDB](/best-practices/haproxy-best-practices.md). + +{{< copyable "" >}} + +```yaml +global # Global configuration. + pidfile /var/run/haproxy.pid # Writes the PIDs of HAProxy processes into this file. + maxconn 4000 # The maximum number of concurrent connections for a single HAProxy process. + user haproxy # The same with the UID parameter. + group haproxy # The same with the GID parameter. A dedicated user group is recommended. + nbproc 64 # The number of processes created when going daemon. When starting multiple processes to forward requests, ensure that the value is large enough so that HAProxy does not block processes. + daemon # Makes the process fork into background. It is equivalent to the command line "-D" argument. It can be disabled by the command line "-db" argument. +defaults # Default configuration. + log global # Inherits the settings of the global configuration. + retries 2 # The maximum number of retries to connect to an upstream server. If the number of connection attempts exceeds the value, the backend server is considered unavailable. + timeout connect 2s # The maximum time to wait for a connection attempt to a backend server to succeed. It should be set to a shorter time if the server is located on the same LAN as HAProxy. + timeout client 30000s # The maximum inactivity time on the client side. + timeout server 30000s # The maximum inactivity time on the server side. +listen tidb-cluster # Database load balancing. + bind 0.0.0.0:3390 # The Floating IP address and listening port. + mode tcp # HAProxy uses layer 4, the transport layer. + balance leastconn # The server with the fewest connections receives the connection. "leastconn" is recommended where long sessions are expected, such as LDAP, SQL and TSE, rather than protocols using short sessions, such as HTTP. The algorithm is dynamic, which means that server weights might be adjusted on the fly for slow starts for instance. + server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # Detects port 4000 at a frequency of once every 2000 milliseconds. If it is detected as successful twice, the server is considered available; if it is detected as failed three times, the server is considered unavailable. + server tidb-2 10.9.39.208:4000 check inter 2000 rise 2 fall 3 + server tidb-3 10.9.64.166:4000 check inter 2000 rise 2 fall 3 +``` + +### Prepare test data + +1. Deploy TiDB v6.0.0 and v5.4.0 using TiUP. +2. Create a database named `tpcc`: `create database tpcc;`. +3. Use BenchmarkSQL to import the TPC-C 5000 Warehouse data: `tiup bench tpcc prepare --warehouse 5000 --db tpcc -H 127.0.0.1 -p 4000`. +4. Run the `tiup bench tpcc run -U root --db tpcc --host 127.0.0.1 --port 4000 --time 1800s --warehouses 5000 --threads {{thread}}` command to perform stress tests on TiDB via HAProxy. For each concurrency, the test takes 30 minutes. +5. Extract the tpmC data of New Order from the result. + +## Test result + +Compared with v5.4.0, the TPC-C performance of v6.0.0 is **improved by 24.20%**. + +| Threads | v5.4.0 tpmC | v6.0.0 tpmC | tpmC improvement (%) | +|:----------|:----------|:----------|:----------| +|50|44822.8|54956.6|22.61| +|100|52150.3|66216.6|26.97| +|200|57344.9|72116.7|25.76| +|400|58675|71254.8|21.44| + +![TPC-C](/media/tpcc_v540_vs_v600.png) diff --git a/benchmark/v6.0-performance-benchmarking-with-tpch.md b/benchmark/v6.0-performance-benchmarking-with-tpch.md new file mode 100644 index 0000000000000..b22e4e3b0afab --- /dev/null +++ b/benchmark/v6.0-performance-benchmarking-with-tpch.md @@ -0,0 +1,8 @@ +--- +title: Performance Comparison between TiFlash and Greenplum/Spark +summary: Performance Comparison between TiFlash and Greenplum/Spark. Refer to TiDB v5.4 TPC-H performance benchmarking report for details. +--- + +# Performance Comparison between TiFlash and Greenplum/Spark + +Refer to [TiDB v5.4 TPC-H performance benchmarking report](https://docs.pingcap.com/tidb/stable/v5.4-performance-benchmarking-with-tpch). \ No newline at end of file diff --git a/benchmark/v6.1-performance-benchmarking-with-tpcc.md b/benchmark/v6.1-performance-benchmarking-with-tpcc.md new file mode 100644 index 0000000000000..17265b670510b --- /dev/null +++ b/benchmark/v6.1-performance-benchmarking-with-tpcc.md @@ -0,0 +1,124 @@ +--- +title: TiDB TPC-C Performance Test Report -- v6.1.0 vs. v6.0.0 +summary: TiDB v6.1.0 TPC-C performance is 2.85% better than v6.0.0. TiDB and TiKV parameter configurations are the same for both versions. HAProxy is used for load balancing. Results show performance improvement across different thread counts. +--- + +# TiDB TPC-C Performance Test Report -- v6.1.0 vs. v6.0.0 + +## Test overview + +This test aims at comparing the TPC-C performance of TiDB v6.1.0 and v6.0.0 in the Online Transactional Processing (OLTP) scenario. The results show that compared with v6.0.0, the TPC-C performance of v6.1.0 is improved by 2.85%. + +## Test environment (AWS EC2） + +### Hardware configuration + +| Service type | EC2 type | Instance count | +|:----------|:----------|:----------| +| PD | m5.xlarge | 3 | +| TiKV | i3.4xlarge| 3 | +| TiDB | c5.4xlarge| 3 | +| TPC-C | c5.9xlarge| 1 | + +### Software version + +| Service type | Software version | +| :----------- | :---------------- | +| PD | v6.0.0 and v6.1.0 | +| TiDB | v6.0.0 and v6.1.0 | +| TiKV | v6.0.0 and v6.1.0 | +| TiUP | 1.9.3 | +| HAProxy | 2.5.0 | + +### Parameter configuration + +TiDB v6.1.0 and TiDB v6.0.0 use the same configuration. + +#### TiDB parameter configuration + +{{< copyable "" >}} + +```yaml +log.level: "error" +prepared-plan-cache.enabled: true +tikv-client.max-batch-wait-time: 2000000 +``` + +#### TiKV parameter configuration + +{{< copyable "" >}} + +```yaml +raftstore.apply-max-batch-size: 2048 +raftstore.apply-pool-size: 3 +raftstore.store-max-batch-size: 2048 +raftstore.store-pool-size: 2 +readpool.storage.normal-concurrency: 10 +server.grpc-concurrency: 6 +``` + +#### TiDB global variable configuration + +{{< copyable "sql" >}} + +```sql +set global tidb_hashagg_final_concurrency=1; +set global tidb_hashagg_partial_concurrency=1; +set global tidb_enable_async_commit = 1; +set global tidb_enable_1pc = 1; +set global tidb_guarantee_linearizability = 0; +set global tidb_enable_clustered_index = 1; +set global tidb_prepared_plan_cache_size=1000; +``` + +#### HAProxy configuration - haproxy.cfg + +For more details about how to use HAProxy on TiDB, see [Best Practices for Using HAProxy in TiDB](/best-practices/haproxy-best-practices.md). + +{{< copyable "" >}} + +```yaml +global # Global configuration. + pidfile /var/run/haproxy.pid # Writes the PIDs of HAProxy processes into this file. + maxconn 4000 # The maximum number of concurrent connections for a single HAProxy process. + user haproxy # The same with the UID parameter. + group haproxy # The same with the GID parameter. A dedicated user group is recommended. + nbproc 64 # The number of processes created when going daemon. When starting multiple processes to forward requests, ensure that the value is large enough so that HAProxy does not block processes. + daemon # Makes the process fork into background. It is equivalent to the command line "-D" argument. It can be disabled by the command line "-db" argument. + +defaults # Default configuration. + log global # Inherits the settings of the global configuration. + retries 2 # The maximum number of retries to connect to an upstream server. If the number of connection attempts exceeds the value, the backend server is considered unavailable. + timeout connect 2s # The maximum time to wait for a connection attempt to a backend server to succeed. It should be set to a shorter time if the server is located on the same LAN as HAProxy. + timeout client 30000s # The maximum inactivity time on the client side. + timeout server 30000s # The maximum inactivity time on the server side. + +listen tidb-cluster # Database load balancing. + bind 0.0.0.0:3390 # The Floating IP address and listening port. + mode tcp # HAProxy uses layer 4, the transport layer. + balance leastconn # The server with the fewest connections receives the connection. "leastconn" is recommended where long sessions are expected, such as LDAP, SQL and TSE, rather than protocols using short sessions, such as HTTP. The algorithm is dynamic, which means that server weights might be adjusted on the fly for slow starts for instance. + server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # Detects port 4000 at a frequency of once every 2000 milliseconds. If it is detected as successful twice, the server is considered available; if it is detected as failed three times, the server is considered unavailable. + server tidb-2 10.9.39.208:4000 check inter 2000 rise 2 fall 3 + server tidb-3 10.9.64.166:4000 check inter 2000 rise 2 fall 3 +``` + +### Prepare test data + +1. Deploy TiDB v6.1.0 and v6.0.0 using TiUP. +2. Create a database named `tpcc`: `create database tpcc;`. +3. Use BenchmarkSQL to import the TPC-C 5000 Warehouse data: `tiup bench tpcc prepare --warehouse 5000 --db tpcc -H 127.0.0.1 -p 4000`. +4. Run the `tiup bench tpcc run -U root --db tpcc --host 127.0.0.1 --port 4000 --time 1800s --warehouses 5000 --threads {{thread}}` command to perform stress tests on TiDB via HAProxy. For each concurrency, the test takes 30 minutes. +5. Extract the tpmC data of New Order from the result. + +## Test result + +Compared with v6.0.0, the TPC-C performance of v6.1.0 is **improved by 2.85%**. + +| Threads | v6.0.0 tpmC | v6.1.0 tpmC | tpmC improvement (%) | +|:----------|:----------|:----------|:----------| +|50|59059.2|60424.4|2.31| +|100|69357.6|71235.5|2.71| +|200|71364.8|74117.8|3.86| +|400|72694.3|74525.3|2.52| + +![TPC-C](/media/tpcc_v600_vs_v610.png) diff --git a/benchmark/v6.1-performance-benchmarking-with-tpch.md b/benchmark/v6.1-performance-benchmarking-with-tpch.md new file mode 100644 index 0000000000000..b22e4e3b0afab --- /dev/null +++ b/benchmark/v6.1-performance-benchmarking-with-tpch.md @@ -0,0 +1,8 @@ +--- +title: Performance Comparison between TiFlash and Greenplum/Spark +summary: Performance Comparison between TiFlash and Greenplum/Spark. Refer to TiDB v5.4 TPC-H performance benchmarking report for details. +--- + +# Performance Comparison between TiFlash and Greenplum/Spark + +Refer to [TiDB v5.4 TPC-H performance benchmarking report](https://docs.pingcap.com/tidb/stable/v5.4-performance-benchmarking-with-tpch). \ No newline at end of file diff --git a/benchmark/v6.2-performance-benchmarking-with-tpcc.md b/benchmark/v6.2-performance-benchmarking-with-tpcc.md new file mode 100644 index 0000000000000..455f3ca53a90f --- /dev/null +++ b/benchmark/v6.2-performance-benchmarking-with-tpcc.md @@ -0,0 +1,124 @@ +--- +title: TiDB TPC-C Performance Test Report -- v6.2.0 vs. v6.1.0 +summary: TiDB v6.2.0 TPC-C performance declined by 2.00% compared to v6.1.0. The test used AWS EC2 with specific hardware and software configurations. Test data was prepared and stress tests were conducted via HAProxy. Results showed a decline in performance across different thread counts. +--- + +# TiDB TPC-C Performance Test Report -- v6.2.0 vs. v6.1.0 + +## Test overview + +This test aims at comparing the TPC-C performance of TiDB v6.2.0 and v6.1.0 in the Online Transactional Processing (OLTP) scenario. The results show that compared with v6.1.0, the TPC-C performance of v6.2.0 is declined by 2.00%. + +## Test environment (AWS EC2） + +### Hardware configuration + +| Service type | EC2 type | Instance count | +|:----------|:----------|:----------| +| PD | m5.xlarge | 3 | +| TiKV | i3.4xlarge| 3 | +| TiDB | c5.4xlarge| 3 | +| TPC-C | c5.9xlarge| 1 | + +### Software version + +| Service type | Software version | +| :----------- | :---------------- | +| PD | v6.1.0 and v6.2.0 | +| TiDB | v6.1.0 and v6.2.0 | +| TiKV | v6.1.0 and v6.2.0 | +| TiUP | 1.9.3 | +| HAProxy | 2.5.0 | + +### Parameter configuration + +TiDB v6.2.0 and TiDB v6.1.0 use the same configuration. + +#### TiDB parameter configuration + +{{< copyable "" >}} + +```yaml +log.level: "error" +prepared-plan-cache.enabled: true +tikv-client.max-batch-wait-time: 2000000 +``` + +#### TiKV parameter configuration + +{{< copyable "" >}} + +```yaml +raftstore.apply-max-batch-size: 2048 +raftstore.apply-pool-size: 3 +raftstore.store-max-batch-size: 2048 +raftstore.store-pool-size: 2 +readpool.storage.normal-concurrency: 10 +server.grpc-concurrency: 6 +``` + +#### TiDB global variable configuration + +{{< copyable "sql" >}} + +```sql +set global tidb_hashagg_final_concurrency=1; +set global tidb_hashagg_partial_concurrency=1; +set global tidb_enable_async_commit = 1; +set global tidb_enable_1pc = 1; +set global tidb_guarantee_linearizability = 0; +set global tidb_enable_clustered_index = 1; +set global tidb_prepared_plan_cache_size=1000; +``` + +#### HAProxy configuration - haproxy.cfg + +For more details about how to use HAProxy on TiDB, see [Best Practices for Using HAProxy in TiDB](/best-practices/haproxy-best-practices.md). + +{{< copyable "" >}} + +```yaml +global # Global configuration. + pidfile /var/run/haproxy.pid # Writes the PIDs of HAProxy processes into this file. + maxconn 4000 # The maximum number of concurrent connections for a single HAProxy process. + user haproxy # The same with the UID parameter. + group haproxy # The same with the GID parameter. A dedicated user group is recommended. + nbproc 64 # The number of processes created when going daemon. When starting multiple processes to forward requests, ensure that the value is large enough so that HAProxy does not block processes. + daemon # Makes the process fork into background. It is equivalent to the command line "-D" argument. It can be disabled by the command line "-db" argument. + +defaults # Default configuration. + log global # Inherits the settings of the global configuration. + retries 2 # The maximum number of retries to connect to an upstream server. If the number of connection attempts exceeds the value, the backend server is considered unavailable. + timeout connect 2s # The maximum time to wait for a connection attempt to a backend server to succeed. It should be set to a shorter time if the server is located on the same LAN as HAProxy. + timeout client 30000s # The maximum inactivity time on the client side. + timeout server 30000s # The maximum inactivity time on the server side. + +listen tidb-cluster # Database load balancing. + bind 0.0.0.0:3390 # The Floating IP address and listening port. + mode tcp # HAProxy uses layer 4, the transport layer. + balance leastconn # The server with the fewest connections receives the connection. "leastconn" is recommended where long sessions are expected, such as LDAP, SQL and TSE, rather than protocols using short sessions, such as HTTP. The algorithm is dynamic, which means that server weights might be adjusted on the fly for slow starts for instance. + server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # Detects port 4000 at a frequency of once every 2000 milliseconds. If it is detected as successful twice, the server is considered available; if it is detected as failed three times, the server is considered unavailable. + server tidb-2 10.9.39.208:4000 check inter 2000 rise 2 fall 3 + server tidb-3 10.9.64.166:4000 check inter 2000 rise 2 fall 3 +``` + +### Prepare test data + +1. Deploy TiDB v6.2.0 and v6.1.0 using TiUP. +2. Create a database named `tpcc`: `create database tpcc;`. +3. Use BenchmarkSQL to import the TPC-C 5000 Warehouse data: `tiup bench tpcc prepare --warehouse 5000 --db tpcc -H 127.0.0.1 -P 4000`. +4. Run the `tiup bench tpcc run -U root --db tpcc --host 127.0.0.1 --port 4000 --time 1800s --warehouses 5000 --threads {{thread}}` command to perform stress tests on TiDB via HAProxy. For each concurrency, the test takes 30 minutes. +5. Extract the tpmC data of New Order from the result. + +## Test result + +Compared with v6.1.0, the TPC-C performance of v6.2.0 is **declined by 2.00%**. + +| Threads | v6.1.0 tpmC | v6.2.0 tpmC | tpmC improvement (%) | +| :------ | :---------- | :---------- | :------------ | +| 50 | 62212.4 | 61874.4 | -0.54 | +| 100 | 72790.7 | 71317.5 | -2.02 | +| 200 | 75818.6 | 73090.4 | -3.60 | +| 400 | 74515.3 | 73156.9 | -1.82 | + +![TPC-C](/media/tpcc_v610_vs_v620.png) diff --git a/benchmark/v6.2-performance-benchmarking-with-tpch.md b/benchmark/v6.2-performance-benchmarking-with-tpch.md new file mode 100644 index 0000000000000..834a7bb3276bf --- /dev/null +++ b/benchmark/v6.2-performance-benchmarking-with-tpch.md @@ -0,0 +1,8 @@ +--- +title: Performance Comparison between TiFlash and Greenplum/Spark +summary: Performance Comparison between TiFlash and Greenplum/Spark. Refer to TiDB v5.4 TPC-H performance benchmarking report at the provided link. +--- + +# Performance Comparison between TiFlash and Greenplum/Spark + +Refer to [TiDB v5.4 TPC-H performance benchmarking report](https://docs.pingcap.com/tidb/stable/v5.4-performance-benchmarking-with-tpch). diff --git a/develop/dev-guide-build-cluster-in-cloud.md b/develop/dev-guide-build-cluster-in-cloud.md index e37c632a2728a..71ec7bebb00be 100644 --- a/develop/dev-guide-build-cluster-in-cloud.md +++ b/develop/dev-guide-build-cluster-in-cloud.md @@ -1,77 +1,77 @@ --- -title: Build a {{{ .starter }}} Cluster -summary: Learn how to build a {{{ .starter }}} cluster in TiDB Cloud and connect to it. +title: 构建 TiDB Cloud Serverless 集群 +summary: 学习如何在 TiDB Cloud 中构建 TiDB Cloud Serverless 集群并连接到它。 --- -# Build a {{{ .starter }}} Cluster +# 构建 TiDB Cloud Serverless 集群 -This document walks you through the quickest way to get started with TiDB. You will use [TiDB Cloud](https://www.pingcap.com/tidb-cloud) to create a {{{ .starter }}} cluster, connect to it, and run a sample application on it. +本文档将带你快速上手 TiDB。你将使用 [TiDB Cloud](https://www.pingcap.com/tidb-cloud) 创建一个 TiDB Cloud Serverless（原 Serverless）集群，连接到该集群，并在其上运行一个示例应用程序。 -If you need to run TiDB on your local machine, see [Starting TiDB Locally](/quick-start-with-tidb.md). +如果你需要在本地机器上运行 TiDB，请参见 [本地启动 TiDB](/quick-start-with-tidb.md)。 -This document walks you through the quickest way to get started with TiDB Cloud. You will create a TiDB cluster, connect to it, and run a sample application on it. +本文档将带你快速上手 TiDB Cloud。你将创建一个 TiDB 集群，连接到该集群，并在其上运行一个示例应用程序。 -## Step 1. Create a {{{ .starter }}} cluster {#step-1-create-a-tidb-cloud-cluster} +## 第 1 步. 创建 TiDB Cloud Serverless 集群 {#step-1-create-a-tidb-cloud-cluster} -1. If you do not have a TiDB Cloud account, click [here](https://tidbcloud.com/free-trial) to sign up for an account. +1. 如果你还没有 TiDB Cloud 账号，请点击 [这里](https://tidbcloud.com/free-trial) 注册账号。 -2. [Log in](https://tidbcloud.com/) to your TiDB Cloud account. +2. [登录](https://tidbcloud.com/) 你的 TiDB Cloud 账号。 -3. On the [**Clusters**](https://tidbcloud.com/console/clusters) page, click **Create Cluster**. +3. 在 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击 **Create Cluster**。 -4. On the **Create Cluster** page, **Serverless** is selected by default. Update the default cluster name if necessary, and then select the region where you want to create your cluster. +4. 在 **Create Cluster** 页面，**Starter** 会被默认选中。根据需要修改默认集群名称，然后选择你希望创建集群的区域。 -5. Click **Create** to create a {{{ .starter }}} cluster. +5. 点击 **Create** 创建 TiDB Cloud Serverless 集群。 - Your TiDB Cloud cluster will be created in approximately 30 seconds. + 你的 TiDB Cloud 集群将在大约 30 秒内创建完成。 -6. After your TiDB Cloud cluster is created, click your cluster name to go to the cluster overview page, and then click **Connect** in the upper-right corner. A connection dialog box is displayed. +6. 集群创建完成后，点击你的集群名称进入集群概览页面，然后点击右上角的 **Connect**。此时会弹出连接对话框。 -7. In the dialog, select your preferred connection method and operating system to get the corresponding connection string. This document uses MySQL client as an example. +7. 在对话框中，选择你偏好的连接方式和操作系统，以获取对应的连接字符串。本文档以 MySQL 客户端为例。 -8. Click **Generate Password** to generate a random password. The generated password will not show again, so save your password in a secure location. If you do not set a root password, you cannot connect to the cluster. +8. 点击 **Generate Password** 生成一个随机密码。生成的密码只会显示一次，请妥善保存。如果你没有设置 root 密码，将无法连接到集群。 -> **Note:** +> **注意：** > -> For [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) clusters, when you connect to your cluster, you must include the prefix for your cluster in the user name and wrap the name with quotation marks. For more information, see [User name prefix](https://docs.pingcap.com/tidbcloud/select-cluster-tier#user-name-prefix). +> 对于 [TiDB Cloud Serverless](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) 集群，连接集群时，必须在用户名中包含集群的前缀，并用引号包裹用户名。更多信息请参见 [用户名前缀](https://docs.pingcap.com/tidbcloud/select-cluster-tier#user-name-prefix)。 -> **Note:** +> **注意：** > -> For [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) clusters, when you connect to your cluster, you must include the prefix for your cluster in the user name and wrap the name with quotation marks. For more information, see [User name prefix](/tidb-cloud/select-cluster-tier.md#user-name-prefix). +> 对于 [TiDB Cloud Serverless](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) 集群，连接集群时，必须在用户名中包含集群的前缀，并用引号包裹用户名。更多信息请参见 [用户名前缀](/tidb-cloud/select-cluster-tier.md#user-name-prefix)。 -## Step 2. Connect to a cluster +## 第 2 步. 连接到集群 -1. If the MySQL client is not installed, select your operating system and follow the steps below to install it. +1. 如果未安装 MySQL 客户端，请选择你的操作系统并按照以下步骤安装。
-For macOS, install [Homebrew](https://brew.sh/index) if you do not have it, and then run the following command to install the MySQL client: +对于 macOS，如果你还没有安装 [Homebrew](https://brew.sh/index)，请先安装，然后运行以下命令安装 MySQL 客户端： ```shell brew install mysql-client ``` -The output is as follows: +输出如下： ``` mysql-client is keg-only, which means it was not symlinked into /opt/homebrew, @@ -85,20 +85,20 @@ For compilers to find mysql-client you may need to set: export CPPFLAGS="-I/opt/homebrew/opt/mysql-client/include" ``` -To add the MySQL client to your PATH, locate the following command in the above output (if your output is inconsistent with the above output in the document, use the corresponding command in your output instead) and run it: +要将 MySQL 客户端添加到 PATH，请在上述输出中找到以下命令（如果你的输出与本文档中的输出不一致，请使用你输出中的对应命令）并运行： ```shell echo 'export PATH="/opt/homebrew/opt/mysql-client/bin:$PATH"' >> ~/.zshrc ``` -Then, declare the global environment variable by the `source` command and verify that the MySQL client is installed successfully: +然后，通过 `source` 命令声明全局环境变量，并验证 MySQL 客户端是否安装成功： ```shell source ~/.zshrc mysql --version ``` -An example of the expected output: +预期输出示例： ``` mysql Ver 8.0.28 for macos12.0 on arm64 (Homebrew) @@ -108,19 +108,19 @@ mysql Ver 8.0.28 for macos12.0 on arm64 (Homebrew)
-For Linux, the following takes Ubuntu as an example: +对于 Linux，这里以 Ubuntu 为例： ```shell apt-get install mysql-client ``` -Then, verify that the MySQL client is installed successfully: +然后，验证 MySQL 客户端是否安装成功： ```shell mysql --version ``` -An example of the expected output: +预期输出示例： ``` mysql Ver 15.1 Distrib 5.5.68-MariaDB, for Linux (x86_64) using readline 5.1 @@ -130,43 +130,42 @@ mysql Ver 15.1 Distrib 5.5.68-MariaDB, for Linux (x86_64) using readline 5.1 -2. Run the connection string obtained in [Step 1](#step-1-create-a-tidb-cloud-cluster). - - {{< copyable "shell-regular" >}} +2. 运行在 [第 1 步](#step-1-create-a-tidb-cloud-cluster) 获取的连接字符串。 + ```shell mysql --connect-timeout 15 -u '.root' -h -P 4000 -D test --ssl-mode=VERIFY_IDENTITY --ssl-ca=/etc/ssl/cert.pem -p ``` -> **Note:** +> **注意：** > -> - When you connect to a {{{ .starter }}} cluster, you must [use the TLS connection](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-clusters). -> - If you encounter problems when connecting to a {{{ .starter }}} cluster, you can read [Secure Connections to {{{ .starter }}} Clusters](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-clusters) for more information. +> - 连接 TiDB Cloud Serverless 集群时，必须 [使用 TLS 连接](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-clusters)。 +> - 如果在连接 TiDB Cloud Serverless 集群时遇到问题，可以参考 [安全连接到 TiDB Cloud Serverless 集群](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-clusters) 获取更多信息。 -> **Note:** +> **注意：** > -> - When you connect to a {{{ .starter }}} cluster, you must [use the TLS connection](/tidb-cloud/secure-connections-to-serverless-clusters.md). -> - If you encounter problems when connecting to a {{{ .starter }}} cluster, you can read [Secure Connections to {{{ .starter }}} Clusters](/tidb-cloud/secure-connections-to-serverless-clusters.md) for more information. +> - 连接 TiDB Cloud Serverless 集群时，必须 [使用 TLS 连接](/tidb-cloud/secure-connections-to-serverless-clusters.md)。 +> - 如果在连接 TiDB Cloud Serverless 集群时遇到问题，可以参考 [安全连接到 TiDB Cloud Serverless 集群](/tidb-cloud/secure-connections-to-serverless-clusters.md) 获取更多信息。 -3. Fill in the password to sign in. +3. 输入密码进行登录。 -## Step 3. Execute a SQL statement +## 第 3 步. 执行 SQL 语句 -Let's try to execute your first SQL statement on TiDB Cloud. +让我们尝试在 TiDB Cloud 上执行你的第一条 SQL 语句。 ```sql SELECT 'Hello TiDB Cloud!'; ``` -Expected output: +预期输出： ```sql +-------------------+ @@ -176,18 +175,18 @@ Expected output: +-------------------+ ``` -If your actual output is similar to the expected output, congratulations, you have successfully executed a SQL statement on TiDB Cloud. +如果你的实际输出与预期输出类似，恭喜你，已经在 TiDB Cloud 上成功执行了一条 SQL 语句。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +欢迎在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +欢迎在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](https://tidb.support.pingcap.com/)。 diff --git a/develop/dev-guide-connection-parameters.md b/develop/dev-guide-connection-parameters.md index 1b407d4fed24f..9424db4b281f1 100644 --- a/develop/dev-guide-connection-parameters.md +++ b/develop/dev-guide-connection-parameters.md @@ -1,81 +1,81 @@ --- -title: Connection Pools and Connection Parameters -summary: This document explains how to configure connection pools and parameters for TiDB. It covers connection pool size, probe configuration, and formulas for optimal throughput. It also discusses JDBC API usage and MySQL Connector/J parameter configurations for performance optimization. +title: 连接池与连接参数 +summary: 本文档介绍如何为 TiDB 配置连接池和连接参数。内容涵盖连接池大小、探测配置、最佳吞吐量的经验公式，同时讨论 JDBC API 的使用及 MySQL Connector/J 参数配置以优化性能。 --- -# Connection Pools and Connection Parameters +# 连接池与连接参数 -This document describes how to configure connection pools and connection parameters when you use a driver or ORM framework to connect to TiDB. +本文描述了当你使用驱动或 ORM 框架连接 TiDB 时，如何配置连接池和连接参数。 -If you are interested in more tips about Java application development, see [Best Practices for Developing Java Applications with TiDB](/best-practices/java-app-best-practices.md#connection-pool) +如果你对 Java 应用开发有更多兴趣，参见 [使用 TiDB 开发 Java 应用的最佳实践](/best-practices/java-app-best-practices.md#connection-pool) -If you are interested in more tips about Java application development, see [Best Practices for Developing Java Applications with TiDB](https://docs.pingcap.com/tidb/stable/java-app-best-practices) +如果你对 Java 应用开发有更多兴趣，参见 [使用 TiDB 开发 Java 应用的最佳实践](https://docs.pingcap.com/tidb/stable/java-app-best-practices) -## Connection pool +## 连接池 -Building TiDB (MySQL) connections is relatively expensive (for OLTP scenarios at least). Because in addition to building a TCP connection, connection authentication is also required. Therefore, the client usually saves the TiDB (MySQL) connections to the connection pool for reuse. +建立 TiDB（MySQL）连接的成本相对较高（至少在 OLTP 场景下如此）。因为除了建立 TCP 连接外，还需要进行连接认证。因此，客户端通常会将 TiDB（MySQL）连接保存在连接池中以复用。 -Java has many connection pool implementations such as [HikariCP](https://github.com/brettwooldridge/HikariCP), [tomcat-jdbc](https://tomcat.apache.org/tomcat-10.1-doc/jdbc-pool.html), [druid](https://github.com/alibaba/druid), [c3p0](https://www.mchange.com/projects/c3p0/), and [dbcp](https://commons.apache.org/proper/commons-dbcp/). TiDB does not limit which connection pool you use, so you can choose whichever you like for your application. +Java 有许多连接池实现，例如 [HikariCP](https://github.com/brettwooldridge/HikariCP)、[tomcat-jdbc](https://tomcat.apache.org/tomcat-10.1-doc/jdbc-pool.html)、[druid](https://github.com/alibaba/druid)、[c3p0](https://www.mchange.com/projects/c3p0/)、[dbcp](https://commons.apache.org/proper/commons-dbcp/)。TiDB 不限制你使用哪种连接池，因此你可以根据应用选择任意实现。 -### Configure the number of connections +### 配置连接数 -It is a common practice that the connection pool size is well adjusted according to the application's own needs. Take HikariCP as an example: +通常，连接池大小会根据应用自身需求进行合理调整。以 HikariCP 为例： -- **maximumPoolSize**: The maximum number of connections in the connection pool. If this value is too large, TiDB consumes resources to maintain useless connections. If this value is too small, the application gets slow connections. Therefore, you need to configure this value according to your application characteristics. For details, see [About Pool Sizing](https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing). -- **minimumIdle**: The minimum number of idle connections in the connection pool. It is mainly used to reserve some connections to respond to sudden requests when the application is idle. You also need to configure it according to your application characteristics. +- **maximumPoolSize**：连接池中的最大连接数。如果该值过大，TiDB 会消耗资源维护无用连接；如果该值过小，应用获取连接会变慢。因此，你需要根据应用特性配置该值。详情参见 [About Pool Sizing](https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing)。 +- **minimumIdle**：连接池中的最小空闲连接数。主要用于在应用空闲时预留部分连接以应对突发请求。你也需要根据应用特性进行配置。 -The application needs to return the connection after finishing using it. It is recommended that the application uses the corresponding connection pool monitoring (such as **metricRegistry**) to locate connection pool issues in time. +应用在使用完连接后需要归还连接。建议应用使用相应的连接池监控（如 **metricRegistry**）及时定位连接池问题。 -### Probe configuration +### 探测配置 -The connection pool maintains persistent connections from clients to TiDB as follows: +连接池会维护客户端到 TiDB 的持久连接，具体如下： -- Before v5.4, TiDB does not proactively close client connections by default (unless an error is reported). -- Starting from v5.4, TiDB automatically closes client connections after `28800` seconds (this is, `8` hours) of inactivity by default. You can control this timeout setting using the TiDB and MySQL compatible `wait_timeout` variable. For more information, see [JDBC Query Timeout](/develop/dev-guide-timeouts-in-tidb.md#jdbc-query-timeout). +- v5.4 之前，TiDB 默认不会主动关闭客户端连接（除非报错）。 +- 从 v5.4 开始，TiDB 默认在连接空闲 `28800` 秒（即 `8` 小时）后自动关闭客户端连接。你可以通过 TiDB 和 MySQL 兼容的 `wait_timeout` 变量控制该超时时间。更多信息参见 [JDBC 查询超时](/develop/dev-guide-timeouts-in-tidb.md#jdbc-query-timeout)。 -Moreover, there might be network proxies such as [LVS](https://en.wikipedia.org/wiki/Linux_Virtual_Server) or [HAProxy](https://en.wikipedia.org/wiki/HAProxy) between clients and TiDB. These proxies typically proactively clean up connections after a specific idle period (determined by the proxy's idle configuration). In addition to monitoring the proxy's idle configuration, connection pools also need to maintain or probe connections for keep-alive. +此外，客户端与 TiDB 之间可能存在如 [LVS](https://en.wikipedia.org/wiki/Linux_Virtual_Server) 或 [HAProxy](https://en.wikipedia.org/wiki/HAProxy) 等网络代理。这些代理通常会在连接空闲一段时间后（由代理的空闲配置决定）主动清理连接。除了关注代理的空闲配置外，连接池还需要维护或探测连接以保持存活。 -If you often see the following error in your Java application: +如果你在 Java 应用中经常看到如下错误： ``` The last packet sent successfully to the server was 3600000 milliseconds ago. The driver has not received any packets from the server. com.mysql.jdbc.exceptions.jdbc4.CommunicationsException: Communications link failure ``` -If `n` in `n milliseconds ago` is `0` or a very small value, it is usually because the executed SQL operation causes TiDB to exit abnormally. To find the cause, it is recommended to check the TiDB stderr log. +如果 `n milliseconds ago` 中的 `n` 为 `0` 或很小，通常是执行的 SQL 操作导致 TiDB 异常退出。建议检查 TiDB 的 stderr 日志以定位原因。 -If `n` is a very large value (such as `3600000` in the above example), it is likely that this connection was idle for a long time and then closed by the proxy. The usual solution is to increase the value of the proxy's idle configuration and allow the connection pool to: +如果 `n` 很大（如上述例子中的 `3600000`），很可能是该连接长时间空闲后被代理关闭。常见的解决方法是增大代理的空闲配置，并让连接池： -- Check whether the connection is available before using the connection every time. -- Regularly check whether the connection is available using a separate thread. -- Send a test query regularly to keep alive connections. +- 每次使用连接前检查连接是否可用。 +- 通过独立线程定期检查连接是否可用。 +- 定期发送测试查询以保持连接存活。 -Different connection pool implementations might support one or more of the above methods. You can check your connection pool documentation to find the corresponding configuration. +不同的连接池实现可能支持上述一种或多种方式。你可以查阅连接池文档，找到相应配置。 -### Formulas based on experience +### 经验公式 -According to the [About Pool Sizing](https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing) article of HikariCP, if you have no idea about how to set a proper size for the database connection pool, you can get started with a [formula based on experience](https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing#connections--core_count--2--effective_spindle_count). Then, based on the performance result of the pool size calculated from the formula, you can further adjust the size to achieve the best performance. +根据 HikariCP 的 [About Pool Sizing](https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing) 文章，如果你不确定如何设置数据库连接池的合适大小，可以先参考一个[经验公式](https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing#connections--core_count--2--effective_spindle_count)。然后根据公式计算出的池大小的性能结果，进一步调整以获得最佳性能。 -The formula based on experience is as follows: +经验公式如下： ``` connections = ((core_count * 2) + effective_spindle_count) ``` -The description of each parameter in the formula is as follows: +公式中各参数说明如下： -- **connections**: the size of connections obtained. -- **core_count**: the number of CPU cores. -- **effective_spindle_count**: the number of hard drives (not [SSD](https://en.wikipedia.org/wiki/Solid-state_drive)). Because each spinning hard disk can be called a spindle. For example, if you are using a server with a RAID of 16 disks, the **effective_spindle_count** should be 16. Because **HDD** usually can handle only one request at a time, the formula here is actually measuring how many concurrent I/O requests your server can manage. +- **connections**：得到的连接数大小。 +- **core_count**：CPU 核心数。 +- **effective_spindle_count**：硬盘数量（不包括 [SSD](https://en.wikipedia.org/wiki/Solid-state_drive)）。因为每个机械硬盘都可以称为一个 spindle。例如，如果你使用的是 16 盘位 RAID 服务器，**effective_spindle_count** 应为 16。由于 **HDD** 通常一次只能处理一个请求，这个公式实际上衡量的是服务器能管理的并发 I/O 请求数。 -In particular, pay attention to the following note below the [formula](https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing#the-formula). +特别需要注意 [公式](https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing#the-formula) 下方的说明： > ``` > A formula which has held up pretty well across a lot of benchmarks for years is @@ -87,129 +87,131 @@ In particular, pay attention to the following note below the [formula](https://g > how well the formula works with SSDs. > ``` -This note indicates that: +该说明指出： -- **core_count** is the number of physical cores, regardless of whether you enable [Hyper-Threading](https://en.wikipedia.org/wiki/Hyper-threading) or not. -- When data is fully cached, you need to set **effective_spindle_count** to `0`. As the hit rate of cache decreases, the count is closer to the actual number of `HDD`. -- **Whether the formula works for _SSD_ is not tested and unknown.** +- **core_count** 是物理核心数，无论是否开启 [超线程](https://en.wikipedia.org/wiki/Hyper-threading)。 +- 当数据完全被缓存时，**effective_spindle_count** 需设为 `0`。随着缓存命中率降低，该值接近实际 `HDD` 数量。 +- **该公式对 _SSD_ 是否适用尚未验证。** -When using SSDs, it is recommended that you use the following formula based on experience instead: +在使用 SSD 时，建议你采用如下经验公式： ``` connections = (number of cores * 4) ``` -Therefore, you can set the maximum connection size of the initial connection pool to `cores * 4` in the case of SSDs and further adjust the size to tune the performance. +因此，在 SSD 场景下，你可以将初始连接池的最大连接数设置为 `cores * 4`，并进一步调整以优化性能。 -### Tuning direction +### 调优方向 -As you can see, a size calculated from the [formulas based on experience](#formulas-based-on-experience) is just a recommended base value. To get the optimal size on a specific machine, you need to try other values around the base value and test the performance. +如你所见，基于[经验公式](#经验公式)计算出的大小只是推荐的基准值。要获得特定机器上的最优值，你需要在基准值附近尝试其他数值并测试性能。 -Here are some basic rules to help you get the optimal size: +以下是一些基本规则，帮助你获得最优大小： -- If your network or storage latency is high, increase your maximum number of connections to reduce the latency waiting time. Once a thread is blocked by latency, other threads can take over and continue processing. -- If you have multiple services deployed on your server and each service has a separate connection pool, consider the sum of the maximum number of connections to all connection pools. +- 如果你的网络或存储延迟较高，可以增加最大连接数以减少等待延迟。一旦某个线程因延迟阻塞，其他线程可以接管继续处理。 +- 如果你的服务器上部署了多个服务且每个服务有独立的连接池，需要考虑所有连接池最大连接数的总和。 -## Connection parameters +## 连接参数 -Java applications can be encapsulated with various frameworks. In most of the frameworks, JDBC API is called on the bottommost level to interact with the database server. For JDBC, it is recommended that you focus on the following things: +Java 应用可以被各种框架封装。在大多数框架中，底层都是通过 JDBC API 与数据库服务器交互。对于 JDBC，建议你关注以下内容： -- JDBC API usage choice -- API Implementer's parameter configuration +- JDBC API 的使用选择 +- API 实现者的参数配置 ### JDBC API -For JDBC API usage, see [JDBC official tutorial](https://docs.oracle.com/javase/tutorial/jdbc/). This section covers the usage of several important APIs. +关于 JDBC API 的使用，参见 [JDBC 官方教程](https://docs.oracle.com/javase/tutorial/jdbc/)。本节介绍几个重要 API 的用法。 -#### Use Prepare API +#### 使用 Prepare API -For OLTP (Online Transactional Processing) scenarios, the SQL statements sent by the program to the database are several types that can be exhausted after removing parameter changes. Therefore, it is recommended to use [Prepared Statements](https://docs.oracle.com/javase/tutorial/jdbc/basics/prepared.html) instead of regular [execution from a text file](https://docs.oracle.com/javase/tutorial/jdbc/basics/processingsqlstatements.html#executing_queries) and reuse Prepared Statements to execute directly. This avoids the overhead of repeatedly parsing and generating SQL execution plans in TiDB. +对于 OLTP（联机事务处理）场景，程序发送到数据库的 SQL 语句在去除参数变化后类型有限。因此，建议使用 [Prepared Statements](https://docs.oracle.com/javase/tutorial/jdbc/basics/prepared.html) 而不是普通的 [文本执行](https://docs.oracle.com/javase/tutorial/jdbc/basics/processingsqlstatements.html#executing_queries)，并复用 Prepared Statements 直接执行。这样可以避免 TiDB 反复解析和生成 SQL 执行计划的开销。 -At present, most upper-level frameworks call the Prepare API for SQL execution. If you use the JDBC API directly for development, pay attention to choosing the Prepare API. +目前，大多数上层框架都会调用 Prepare API 执行 SQL。如果你直接使用 JDBC API 开发，请注意选择 Prepare API。 -In addition, with the default implementation of MySQL Connector/J, only client-side statements are preprocessed, and the statements are sent to the server in a text file after `?` is replaced on the client. Therefore, in addition to using the Prepare API, you also need to configure `useServerPrepStmts = true` in JDBC connection parameters before you perform statement preprocessing on the TiDB server. For detailed parameter configuration, see [MySQL JDBC parameters](#mysql-jdbc-parameters). +另外，MySQL Connector/J 的默认实现只在客户端做语句预处理，`?` 替换后以文本方式发送到服务器。因此，除了使用 Prepare API 外，还需要在 JDBC 连接参数中配置 `useServerPrepStmts = true`，才能在 TiDB 服务器端进行语句预处理。详细参数配置参见 [MySQL JDBC 参数](#mysql-jdbc-参数)。 -#### Use Batch API +#### 使用 Batch API -For batch inserts, you can use the [`addBatch`/`executeBatch` API](https://www.tutorialspoint.com/jdbc/jdbc-batch-processing). The `addBatch()` method is used to cache multiple SQL statements first on the client, and then send them to the database server together when calling the `executeBatch` method. +对于批量插入，你可以使用 [`addBatch`/`executeBatch` API](https://www.tutorialspoint.com/jdbc/jdbc-batch-processing)。`addBatch()` 方法用于先在客户端缓存多条 SQL 语句，调用 `executeBatch` 方法时再一起发送到数据库服务器。 -> **Note:** +> **注意：** > -> In the default MySQL Connector/J implementation, the sending time of the SQL statements that are added to batch with `addBatch()` is delayed to the time when `executeBatch()` is called, but the statements will still be sent one by one during the actual network transfer. Therefore, this method usually does not reduce the amount of communication overhead. +> 在 MySQL Connector/J 的默认实现中，`addBatch()` 加入批量的 SQL 语句会延迟到调用 `executeBatch()` 时才发送，但实际网络传输时仍然是一条条发送。因此，这种方式通常不会减少通信开销。 > -> If you want to batch network transfer, you need to configure `rewriteBatchedStatements = true` in the JDBC connection parameters. For the detailed parameter configuration, see [Batch-related parameters](#batch-related-parameters). +> 如果你希望批量网络传输，需要在 JDBC 连接参数中配置 `rewriteBatchedStatements = true`。详细参数配置参见 [批量相关参数](#批量相关参数)。 -#### Use `StreamingResult` to get the execution result +#### 使用 `StreamingResult` 获取执行结果 -In most scenarios, to improve execution efficiency, JDBC obtains query results in advance and saves them in client memory by default. But when the query returns a super large result set, the client often wants the database server to reduce the number of records returned at a time and waits until the client's memory is ready and it requests for the next batch. +大多数场景下，为提升执行效率，JDBC 默认会提前获取查询结果并保存在客户端内存中。但当查询返回超大结果集时，客户端通常希望数据库服务器每次返回的记录数减少，等客户端内存准备好后再请求下一批。 -The following two processing methods are usually used in JDBC: +JDBC 通常有以下两种处理方式： -- The first method: [Set **FetchSize** to `Integer.MIN_VALUE`](https://dev.mysql.com/doc/connector-j/en/connector-j-reference-implementation-notes.html#ResultSet) to ensure that the client does not cache. The client will read the execution result from the network connection through `StreamingResult`. +- 第一种方式：[将 **FetchSize** 设置为 `Integer.MIN_VALUE`](https://dev.mysql.com/doc/connector-j/en/connector-j-reference-implementation-notes.html#ResultSet)，确保客户端不做缓存。客户端会通过 `StreamingResult` 从网络连接读取执行结果。 - When the client uses the streaming read method, it needs to finish reading or close `resultset` before continuing to use the statement to make a query. Otherwise, the error `No statements may be issued when any streaming result sets are open and in use on a given connection. Ensure that you have called .close() on any active streaming result sets before attempting more queries.` is returned. + 当客户端采用流式读取方式时，必须在继续使用 statement 查询前，先读取完或关闭 `resultset`。否则会报错：`No statements may be issued when any streaming result sets are open and in use on a given connection. Ensure that you have called .close() on any active streaming result sets before attempting more queries.` - To avoid such an error in queries before the client finishes reading or closes `resultset`, you can add the `clobberStreamingResults=true` parameter in the URL. Then, `resultset` is automatically closed but the result set to be read in the previous streaming query is lost. + 为避免客户端在未读取完或关闭 `resultset` 前查询时报错，可以在 URL 中添加 `clobberStreamingResults=true` 参数。这样会自动关闭 `resultset`，但会丢失前一次流式查询未读取的结果集。 -- The second method: Use Cursor Fetch by first [setting `FetchSize`](http://makejavafaster.blogspot.com/2015/06/jdbc-fetch-size-performance.html) as a positive integer and then configuring `useCursorFetch = true` in the JDBC URL. +- 第二种方式：通过先[设置 `FetchSize`](http://makejavafaster.blogspot.com/2015/06/jdbc-fetch-size-performance.html) 为正整数，再在 JDBC URL 中配置 `useCursorFetch = true`，使用 Cursor Fetch。 -TiDB supports both methods, but it is recommended that you use the first method that sets `FetchSize` to `Integer.MIN_VALUE`, because it is a simpler implementation and has better execution efficiency. +TiDB 支持这两种方式，但推荐你使用第一种将 `FetchSize` 设为 `Integer.MIN_VALUE` 的方式，因为实现更简单且执行效率更高。 -For the second method, TiDB first loads all data to the TiDB node, and then returns data to the client according to the `FetchSize`. Therefore, it usually consumes more memory than the first method. If [`tidb_enable_tmp_storage_on_oom`](/system-variables.md#tidb_enable_tmp_storage_on_oom) is set to `ON`, TiDB might temporarily write the result to the hard disk. +对于第二种方式，TiDB 会先将所有数据加载到 TiDB 节点，然后再按 `FetchSize` 返回给客户端。因此通常比第一种方式消耗更多内存。如果 [`tidb_enable_tmp_storage_on_oom`](/system-variables.md#tidb_enable_tmp_storage_on_oom) 设为 `ON`，TiDB 可能会临时将结果写入硬盘。 -If the [`tidb_enable_lazy_cursor_fetch`](/system-variables.md#tidb_enable_lazy_cursor_fetch-new-in-v830) system variable is set to `ON`, TiDB tries to read part of the data only when the client fetches it, which uses less memory. For more details and limitations, read the [complete descriptions for the `tidb_enable_lazy_cursor_fetch` system variable](/system-variables.md#tidb_enable_lazy_cursor_fetch-new-in-v830). +如果 [`tidb_enable_lazy_cursor_fetch`](/system-variables.md#tidb_enable_lazy_cursor_fetch-new-in-v830) 系统变量设为 `ON`，TiDB 会在客户端获取时只读取部分数据，从而占用更少内存。更多细节和限制，参见 [`tidb_enable_lazy_cursor_fetch` 系统变量完整说明](/system-variables.md#tidb_enable_lazy_cursor_fetch-new-in-v830)。 -### MySQL JDBC parameters +### MySQL JDBC 参数 -JDBC usually provides implementation-related configurations in the form of JDBC URL parameters. This section introduces [MySQL Connector/J's parameter configurations](https://dev.mysql.com/doc/connector-j/en/connector-j-reference-configuration-properties.html) (If you use MariaDB, see [MariaDB's parameter configurations](https://mariadb.com/kb/en/library/about-mariadb-connector-j/#optional-url-parameters)). Because this document cannot cover all configuration items, it mainly focuses on several parameters that might affect performance. +JDBC 通常以 JDBC URL 参数的形式提供实现相关配置。本节介绍 [MySQL Connector/J 的参数配置](https://dev.mysql.com/doc/connector-j/en/connector-j-reference-configuration-properties.html)（如果你使用 MariaDB，参见 [MariaDB 的参数配置](https://mariadb.com/docs/connectors/mariadb-connector-j/about-mariadb-connector-j#optional-url-parameters)）。由于本文无法覆盖所有配置项，主要关注可能影响性能的几个参数。 -#### Prepare-related parameters +#### Prepare 相关参数 -This section introduces parameters related to `Prepare`. +本节介绍与 `Prepare` 相关的参数。 - **useServerPrepStmts** - **useServerPrepStmts** is set to `false` by default, that is, even if you use the Prepare API, the "prepare" operation will be done only on the client. To avoid the parsing overhead of the server, if the same SQL statement uses the Prepare API multiple times, it is recommended to set this configuration to `true`. + **useServerPrepStmts** 默认设为 `false`，即使你使用 Prepare API，“prepare” 操作也只在客户端完成。为避免服务器端解析开销，如果同一 SQL 语句多次使用 Prepare API，建议将该配置设为 `true`。 - To verify that this setting already takes effect, you can do: + 验证该设置是否生效的方法： - - Go to TiDB monitoring dashboard and view the request command type through **Query Summary** > **CPS By Instance**. - - If `COM_QUERY` is replaced by `COM_STMT_EXECUTE` or `COM_STMT_PREPARE` in the request, it means this setting already takes effect. + - 进入 TiDB 监控面板，通过 **Query Summary** > **CPS By Instance** 查看请求命令类型。 + - 如果请求中的 `COM_QUERY` 被 `COM_STMT_EXECUTE` 或 `COM_STMT_PREPARE` 替代，说明该设置已生效。 - **cachePrepStmts** - Although `useServerPrepStmts=true` allows the server to execute Prepared Statements, by default, the client closes the Prepared Statements after each execution and does not reuse them. This means that the "prepare" operation is not even as efficient as text file execution. To solve this, it is recommended that after setting `useServerPrepStmts=true`, you should also configure `cachePrepStmts=true`. This allows the client to cache Prepared Statements. + 虽然 `useServerPrepStmts=true` 允许服务器执行 Prepared Statements，但默认情况下，客户端每次执行后都会关闭 Prepared Statements，不会复用。这意味着“prepare”操作效率甚至不如文本执行。为解决此问题，建议在设置 `useServerPrepStmts=true` 后，同时配置 `cachePrepStmts=true`，以便客户端缓存 Prepared Statements。 - To verify that this setting already takes effect, you can do: + 验证该设置是否生效的方法： - - Go to TiDB monitoring dashboard and view the request command type through **Query Summary** > **CPS By Instance**. - - If the number of `COM_STMT_EXECUTE` in the request is far more than the number of `COM_STMT_PREPARE`, it means this setting already takes effect. + - 进入 TiDB 监控面板，通过 **Query Summary** > **CPS By Instance** 查看请求命令类型。 + - 如果请求中的 `COM_STMT_EXECUTE` 数量远大于 `COM_STMT_PREPARE`，说明该设置已生效。 - In addition, configuring `useConfigs=maxPerformance` will configure multiple parameters at the same time, including `cachePrepStmts=true`. + 此外，配置 `useConfigs=maxPerformance` 会同时配置多个参数，包括 `cachePrepStmts=true`。 - **prepStmtCacheSqlLimit** - After configuring `cachePrepStmts`, also pay attention to the `prepStmtCacheSqlLimit` configuration (the default value is `256`). This configuration controls the maximum length of the Prepared Statements cached on the client. + 配置了 `cachePrepStmts` 后，还需关注 `prepStmtCacheSqlLimit` 配置（默认值为 `256`）。该配置控制客户端缓存的 Prepared Statements 的最大长度。 - The Prepared Statements that exceed this maximum length will not be cached, so they cannot be reused. In this case, you may consider increasing the value of this configuration depending on the actual SQL length of the application. + 超过该最大长度的 Prepared Statements 不会被缓存，无法复用。此时你可以根据应用实际 SQL 长度考虑增大该值。 - You need to check whether this setting is too small if you: + 如果你发现： - - Go to TiDB monitoring dashboard and view the request command type through **Query Summary** > **CPS By Instance**. - - And find that `cachePrepStmts=true` has been configured, but `COM_STMT_PREPARE` is still mostly equal to `COM_STMT_EXECUTE` and `COM_STMT_CLOSE` exists. + - 进入 TiDB 监控面板，通过 **Query Summary** > **CPS By Instance** 查看请求命令类型。 + - 并且已配置 `cachePrepStmts=true`，但 `COM_STMT_PREPARE` 仍与 `COM_STMT_EXECUTE` 数量接近且存在 `COM_STMT_CLOSE`。 + + 需要检查该设置是否过小。 - **prepStmtCacheSize** - **prepStmtCacheSize** controls the number of cached Prepared Statements (the default value is `25`). If your application requires "preparing" many types of SQL statements and wants to reuse Prepared Statements, you can increase this value. + **prepStmtCacheSize** 控制缓存的 Prepared Statements 数量（默认值为 `25`）。如果你的应用需要“prepare”多种 SQL 并希望复用 Prepared Statements，可以增大该值。 - To verify that this setting already takes effect, you can do: + 验证该设置是否生效的方法： - - Go to TiDB monitoring dashboard and view the request command type through **Query Summary** > **CPS By Instance**. - - If the number of `COM_STMT_EXECUTE` in the request is far more than the number of `COM_STMT_PREPARE`, it means this setting already takes effect. + - 进入 TiDB 监控面板，通过 **Query Summary** > **CPS By Instance** 查看请求命令类型。 + - 如果请求中的 `COM_STMT_EXECUTE` 数量远大于 `COM_STMT_PREPARE`，说明该设置已生效。 -#### Batch-related parameters +#### 批量相关参数 -While processing batch writes, it is recommended to configure `rewriteBatchedStatements=true`. After using `addBatch()` or `executeBatch()`, JDBC still sends SQL one by one by default, for example: +处理批量写入时，建议配置 `rewriteBatchedStatements=true`。在使用 `addBatch()` 或 `executeBatch()` 后，JDBC 默认仍然一条条发送 SQL，例如： ```java pstmt = prepare("INSERT INTO `t` (a) values(?)"); @@ -221,7 +223,7 @@ pstmt.setInt(1, 12); pstmt.executeBatch(); ``` -Although `Batch` methods are used, the SQL statements sent to TiDB are still individual `INSERT` statements: +虽然使用了 `Batch` 方法，发送到 TiDB 的 SQL 仍是单条 `INSERT` 语句： ```sql INSERT INTO `t` (`a`) VALUES(10); @@ -229,13 +231,13 @@ INSERT INTO `t` (`a`) VALUES(11); INSERT INTO `t` (`a`) VALUES(12); ``` -But if you set `rewriteBatchedStatements=true`, the SQL statements sent to TiDB will be a single `INSERT` statement: +但如果你设置了 `rewriteBatchedStatements=true`，发送到 TiDB 的 SQL 会变为一条 `INSERT` 语句： ```sql INSERT INTO `t` (`a`) values(10),(11),(12); ``` -Note that the rewrite of the `INSERT` statements is to concatenate the values after multiple "values" keywords into a whole SQL statement. If the `INSERT` statements have other differences, they cannot be rewritten, for example: +需要注意，`INSERT` 语句的重写是将多个 "values" 关键字后的值拼接为一条 SQL。如果 `INSERT` 语句有其他差异，则无法重写，例如： ```sql INSERT INTO `t` (`a`) VALUES (10) ON DUPLICATE KEY UPDATE `a` = 10; @@ -243,7 +245,7 @@ INSERT INTO `t` (`a`) VALUES (11) ON DUPLICATE KEY UPDATE `a` = 11; INSERT INTO `t` (`a`) VALUES (12) ON DUPLICATE KEY UPDATE `a` = 12; ``` -The above `INSERT` statements cannot be rewritten into one statement. But if you change the three statements into the following ones: +上述 `INSERT` 语句无法重写为一条。但如果你将三条语句改为： ```sql INSERT INTO `t` (`a`) VALUES (10) ON DUPLICATE KEY UPDATE `a` = VALUES(`a`); @@ -251,46 +253,46 @@ INSERT INTO `t` (`a`) VALUES (11) ON DUPLICATE KEY UPDATE `a` = VALUES(`a`); INSERT INTO `t` (`a`) VALUES (12) ON DUPLICATE KEY UPDATE `a` = VALUES(`a`); ``` -Then they meet the rewrite requirement. The above `INSERT` statements will be rewritten into the following one statement: +则满足重写要求，上述 `INSERT` 语句会被重写为： ```sql INSERT INTO `t` (`a`) VALUES (10), (11), (12) ON DUPLICATE KEY UPDATE a = VALUES(`a`); ``` -If there are three or more updates during the batch update, the SQL statements will be rewritten and sent as multiple queries. This effectively reduces the client-to-server request overhead, but the side effect is that a larger SQL statement is generated. For example: +如果批量更新时有三条及以上更新，SQL 会被重写并作为多条查询发送。这样可以有效减少客户端到服务器的请求开销，但副作用是生成更大的 SQL 语句。例如： ```sql UPDATE `t` SET `a` = 10 WHERE `id` = 1; UPDATE `t` SET `a` = 11 WHERE `id` = 2; UPDATE `t` SET `a` = 12 WHERE `id` = 3; ``` -In addition, because of a [client bug](https://bugs.mysql.com/bug.php?id=96623), if you want to configure `rewriteBatchedStatements=true` and `useServerPrepStmts=true` during batch update, it is recommended that you also configure the `allowMultiQueries=true` parameter to avoid this bug. +此外，由于 [客户端 bug](https://bugs.mysql.com/bug.php?id=96623)，如果你在批量更新时配置了 `rewriteBatchedStatements=true` 和 `useServerPrepStmts=true`，建议同时配置 `allowMultiQueries=true` 参数以避免该 bug。 -#### Integrate parameters +#### 集成参数 -Through monitoring, you might notice that although the application only performs `INSERT` operations to the TiDB cluster, there are a lot of redundant `SELECT` statements. Usually this happens because JDBC sends some SQL statements to query the settings, for example, `select @@session.transaction_read_only`. These SQL statements are useless for TiDB, so it is recommended that you configure `useConfigs=maxPerformance` to avoid extra overhead. +通过监控你可能会发现，虽然应用只对 TiDB 集群执行 `INSERT` 操作，但存在大量冗余的 `SELECT` 语句。通常这是因为 JDBC 会发送一些查询设置的 SQL，例如 `select @@session.transaction_read_only`。这些 SQL 对 TiDB 没有意义，因此建议你配置 `useConfigs=maxPerformance` 以避免额外开销。 -`useConfigs=maxPerformance` includes a group of configurations. To get the detailed configurations in MySQL Connector/J 8.0 and those in MySQL Connector/J 5.1, see [mysql-connector-j 8.0](https://github.com/mysql/mysql-connector-j/blob/release/8.0/src/main/resources/com/mysql/cj/configurations/maxPerformance.properties) and [mysql-connector-j 5.1](https://github.com/mysql/mysql-connector-j/blob/release/5.1/src/com/mysql/jdbc/configs/maxPerformance.properties) respectively. +`useConfigs=maxPerformance` 包含一组配置。MySQL Connector/J 8.0 和 5.1 的详细配置分别见 [mysql-connector-j 8.0](https://github.com/mysql/mysql-connector-j/blob/release/8.0/src/main/resources/com/mysql/cj/configurations/maxPerformance.properties) 和 [mysql-connector-j 5.1](https://github.com/mysql/mysql-connector-j/blob/release/5.1/src/com/mysql/jdbc/configs/maxPerformance.properties)。 -After it is configured, you can check the monitoring to see a decreased number of `SELECT` statements. +配置后，你可以通过监控看到 `SELECT` 语句数量减少。 -#### Timeout-related parameters +#### 超时相关参数 -TiDB provides two MySQL-compatible parameters to control the timeout: [`wait_timeout`](/system-variables.md#wait_timeout) and [`max_execution_time`](/system-variables.md#max_execution_time). These two parameters respectively control the connection idle timeout with the Java application and the timeout of the SQL execution in the connection; that is to say, these parameters control the longest idle time and the longest busy time for the connection between TiDB and the Java application. Since TiDB v5.4, the default value of `wait_timeout` is `28800` seconds, which is 8 hours. For TiDB versions earlier than v5.4, the default value is `0`, which means the timeout is unlimited. The default value of `max_execution_time` is `0`, which means the maximum execution time of a SQL statement is unlimited. +TiDB 提供了两个 MySQL 兼容参数用于控制超时：[`wait_timeout`](/system-variables.md#wait_timeout) 和 [`max_execution_time`](/system-variables.md#max_execution_time)。这两个参数分别控制 Java 应用连接的空闲超时和连接中 SQL 执行的超时；也就是说，这两个参数分别控制 TiDB 与 Java 应用之间连接的最长空闲时间和最长繁忙时间。自 TiDB v5.4 起，`wait_timeout` 默认值为 `28800` 秒，即 8 小时。v5.4 之前的 TiDB 版本默认值为 `0`，表示无限制。`max_execution_time` 默认值为 `0`，表示 SQL 语句最大执行时间无限制。 -The default value of [`wait_timeout`](/system-variables.md#wait_timeout) is relatively large. In scenarios where a transaction starts but is neither committed nor rolled back, you might need a finer-grained control and a shorter timeout to prevent prolonged lock holding. In this case, you can use [`tidb_idle_transaction_timeout`](/system-variables.md#tidb_idle_transaction_timeout-new-in-v760) (introduced in TiDB v7.6.0) to control the idle timeout for transactions in a user session. +[`wait_timeout`](/system-variables.md#wait_timeout) 的默认值相对较大。在事务已开启但未提交或回滚的场景下，你可能需要更细粒度、更短的超时以避免长时间持有锁。此时可以使用 [`tidb_idle_transaction_timeout`](/system-variables.md#tidb_idle_transaction_timeout-new-in-v760)（TiDB v7.6.0 引入）控制用户会话中事务的空闲超时。 -However, in an actual production environment, idle connections and SQL statements with excessively long execution time negatively affect databases and applications. To avoid idle connections and SQL statements that are executed for too long, you can configure these two parameters in your application's connection string. For example, set `sessionVariables=wait_timeout=3600` (1 hour) and `sessionVariables=max_execution_time=300000` (5 minutes). +但在实际生产环境中，空闲连接和执行时间过长的 SQL 语句会对数据库和应用产生负面影响。为避免空闲连接和长时间执行的 SQL，你可以在应用的连接字符串中配置这两个参数。例如，设置 `sessionVariables=wait_timeout=3600`（1 小时）和 `sessionVariables=max_execution_time=300000`（5 分钟）。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](https://tidb.support.pingcap.com/)。 \ No newline at end of file diff --git a/develop/dev-guide-gui-datagrip.md b/develop/dev-guide-gui-datagrip.md index 908358df31983..42ff72ace1897 100644 --- a/develop/dev-guide-gui-datagrip.md +++ b/develop/dev-guide-gui-datagrip.md @@ -1,113 +1,113 @@ --- -title: Connect to TiDB with JetBrains DataGrip -summary: Learn how to connect to TiDB using JetBrains DataGrip. This tutorial also applies to the Database Tools and SQL plugin available in other JetBrains IDEs, such as IntelliJ, PhpStorm, and PyCharm. +title: 使用 JetBrains DataGrip 连接 TiDB +summary: 学习如何使用 JetBrains DataGrip 连接 TiDB。此教程同样适用于其他 JetBrains IDE（如 IntelliJ、PhpStorm 和 PyCharm）中的 Database Tools and SQL 插件。 --- -# Connect to TiDB with JetBrains DataGrip +# 使用 JetBrains DataGrip 连接 TiDB -TiDB is a MySQL-compatible database, and [JetBrains DataGrip](https://www.jetbrains.com/help/datagrip/getting-started.html) is a powerful integrated development environment (IDE) for database and SQL. This tutorial walks you through the process of connecting to your TiDB cluster using DataGrip. +TiDB 是兼容 MySQL 的数据库，[JetBrains DataGrip](https://www.jetbrains.com/help/datagrip/getting-started.html) 是一款强大的数据库和 SQL 集成开发环境（IDE）。本教程将引导你使用 DataGrip 连接到你的 TiDB 集群。 -> **Note:** +> **注意：** > -> This tutorial is compatible with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed. +> 本教程适用于 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及自托管 TiDB。 -You can use DataGrip in two ways: +你可以通过以下两种方式使用 DataGrip： -- As the [DataGrip IDE](https://www.jetbrains.com/datagrip/download) standalone tool. -- As the [Database Tools and SQL plugin](https://www.jetbrains.com/help/idea/relational-databases.html) in JetBrains IDEs, such as IntelliJ, PhpStorm, and PyCharm. +- 作为独立工具 [DataGrip IDE](https://www.jetbrains.com/datagrip/download)。 +- 作为 JetBrains IDE（如 IntelliJ、PhpStorm 和 PyCharm）中的 [Database Tools and SQL 插件](https://www.jetbrains.com/help/idea/relational-databases.html)。 -This tutorial mainly focuses on the standalone DataGrip IDE. The steps of connecting to TiDB using the JetBrains Database Tools and SQL plugin in JetBrains IDEs are similar. You can also follow the steps in this document for reference when connecting to TiDB from any JetBrains IDE. +本教程主要以独立 DataGrip IDE 为例。通过 JetBrains IDE 中的 Database Tools and SQL 插件连接 TiDB 的步骤类似。你也可以参考本文档中的步骤，在任何 JetBrains IDE 中连接 TiDB。 -## Prerequisites +## 前置条件 -To complete this tutorial, you need: +完成本教程，你需要： -- [DataGrip **2023.2.1** or later](https://www.jetbrains.com/datagrip/download/) or a non-community edition [JetBrains](https://www.jetbrains.com/) IDE. -- A TiDB cluster. +- [DataGrip **2023.2.1** 或更高版本](https://www.jetbrains.com/datagrip/download/) 或非社区版 [JetBrains](https://www.jetbrains.com/) IDE。 +- 一个 TiDB 集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](/production-deployment-using-tiup.md) 创建本地集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) 创建本地集群。 -## Connect to TiDB +## 连接 TiDB -Connect to your TiDB cluster depending on the TiDB deployment option you've selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称，进入集群概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确认连接对话框中的配置与你的操作环境一致。 - - **Connection Type** is set to `Public` - - **Branch** is set to `main` - - **Connect With** is set to `DataGrip` - - **Operating System** matches your environment. + - **Connection Type** 设置为 `Public` + - **Branch** 设置为 `main` + - **Connect With** 设置为 `DataGrip` + - **Operating System** 与你的环境一致 -4. Click **Generate Password** to create a random password. +4. 点击 **Generate Password** 生成随机密码。 - > **Tip:** + > **提示：** > - > If you have created a password before, you can either use the original password or click **Reset Password** to generate a new one. + > 如果你之前已创建过密码，可以继续使用原密码，或点击 **Reset Password** 生成新密码。 -5. Launch DataGrip and create a project to manage your connections. +5. 启动 DataGrip 并创建一个项目用于管理你的连接。 ![Create a project in DataGrip](/media/develop/datagrip-create-project.jpg) -6. In the newly created project, click **+** in the upper-left corner of the **Database Explorer** panel, and select **Data Source** > **Other** > **TiDB**. +6. 在新建的项目中，点击 **Database Explorer** 面板左上角的 **+**，选择 **Data Source** > **Other** > **TiDB**。 ![Select a data source in DataGrip](/media/develop/datagrip-data-source-select.jpg) -7. Copy the connection string from the TiDB Cloud connection dialog. Then, paste it into the **URL** field, and the remaining parameters will be auto-populated. An example result is as follows: +7. 从 TiDB Cloud 连接对话框中复制连接字符串，粘贴到 **URL** 字段，其余参数会自动填充。示例如下： - ![Configure the URL field for {{{ .starter }}}](/media/develop/datagrip-url-paste.jpg) + ![Configure the URL field for TiDB Cloud Serverless](/media/develop/datagrip-url-paste.jpg) - If a **Download missing driver files** warning displays, click **Download** to acquire the driver files. + 如果出现 **Download missing driver files** 警告，点击 **Download** 获取驱动文件。 -8. Click **Test Connection** to validate the connection to the {{{ .starter }}} cluster. +8. 点击 **Test Connection** 验证与 TiDB Cloud Serverless 集群的连接。 - ![Test the connection to a {{{ .starter }}} cluster](/media/develop/datagrip-test-connection.jpg) + ![Test the connection to a TiDB Cloud Serverless cluster](/media/develop/datagrip-test-connection.jpg) -9. Click **OK** to save the connection configuration. +9. 点击 **OK** 保存连接配置。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称，进入集群概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还未配置 IP 访问列表，点击 **Configure IP Access List** 或参考 [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 进行配置后再首次连接。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息参见 [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Launch DataGrip and create a project to manage your connections. +4. 启动 DataGrip 并创建一个项目用于管理你的连接。 ![Create a project in DataGrip](/media/develop/datagrip-create-project.jpg) -5. In the newly created project, click **+** in the upper-left corner of the **Database Explorer** panel, and select **Data Source** > **Other** > **TiDB**. +5. 在新建的项目中，点击 **Database Explorer** 面板左上角的 **+**，选择 **Data Source** > **Other** > **TiDB**。 ![Select a data source in DataGrip](/media/develop/datagrip-data-source-select.jpg) -6. Copy and paste the appropriate connection string into the **Data Source and Drivers** window in DataGrip. The mappings between DataGrip fields and TiDB Cloud Dedicated connection string are as follows: +6. 将相应的连接字符串复制粘贴到 DataGrip 的 **Data Source and Drivers** 窗口。DataGrip 字段与 TiDB Cloud Dedicated 连接字符串的映射关系如下： | DataGrip field | TiDB Cloud Dedicated connection string | | -------------- | ------------------------------- | @@ -116,75 +116,75 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele | User | `{user}` | | Password | `{password}` | - An example is as follows: + 示例： ![Configure the connection parameters for TiDB Cloud Dedicated](/media/develop/datagrip-dedicated-connect.jpg) -7. Click the **SSH/SSL** tab, select the **Use SSL** checkbox, and input the CA certificate path into the **CA file** field. +7. 点击 **SSH/SSL** 标签页，勾选 **Use SSL**，并在 **CA file** 字段中填写 CA 证书路径。 ![Configure the CA for TiDB Cloud Dedicated](/media/develop/datagrip-dedicated-ssl.jpg) - If a **Download missing driver files** warning displays, click **Download** to acquire the driver files. + 如果出现 **Download missing driver files** 警告，点击 **Download** 获取驱动文件。 -8. Click the **Advanced** tab, scroll to find the **enabledTLSProtocols** parameter, and set its value to `TLSv1.2,TLSv1.3`. +8. 点击 **Advanced** 标签页，向下滚动找到 **enabledTLSProtocols** 参数，并将其值设置为 `TLSv1.2,TLSv1.3`。 ![Configure the TLS for TiDB Cloud Dedicated](/media/develop/datagrip-dedicated-advanced.jpg) -9. Click **Test Connection** to validate the connection to the TiDB Cloud Dedicated cluster. +9. 点击 **Test Connection** 验证与 TiDB Cloud Dedicated 集群的连接。 ![Test the connection to a TiDB Cloud Dedicated cluster](/media/develop/datagrip-dedicated-test-connection.jpg) -10. Click **OK** to save the connection configuration. +10. 点击 **OK** 保存连接配置。
-1. Launch DataGrip and create a project to manage your connections. +1. 启动 DataGrip 并创建一个项目用于管理你的连接。 ![Create a project in DataGrip](/media/develop/datagrip-create-project.jpg) -2. In the newly created project, click **+** in the upper-left corner of the **Database Explorer** panel, and select **Data Source** > **Other** > **TiDB**. +2. 在新建的项目中，点击 **Database Explorer** 面板左上角的 **+**，选择 **Data Source** > **Other** > **TiDB**。 ![Select a data source in DataGrip](/media/develop/datagrip-data-source-select.jpg) -3. Configure the following connection parameters: +3. 配置以下连接参数： - - **Host**: The IP address or domain name of your TiDB Self-Managed cluster. - - **Port**: The port number of your TiDB Self-Managed cluster. - - **User**: The username to use to connect to your TiDB Self-Managed cluster. - - **Password**: The password of the username. + - **Host**：你的自托管 TiDB 集群的 IP 地址或域名 + - **Port**：你的自托管 TiDB 集群的端口号 + - **User**：用于连接自托管 TiDB 集群的用户名 + - **Password**：该用户名的密码 - An example is as follows: + 示例： ![Configure the connection parameters for TiDB Self-Managed](/media/develop/datagrip-self-hosted-connect.jpg) - If a **Download missing driver files** warning displays, click **Download** to acquire the driver files. + 如果出现 **Download missing driver files** 警告，点击 **Download** 获取驱动文件。 -4. Click **Test Connection** to validate the connection to the TiDB Self-Managed cluster. +4. 点击 **Test Connection** 验证与自托管 TiDB 集群的连接。 ![Test the connection to a TiDB Self-Managed cluster](/media/develop/datagrip-self-hosted-test-connection.jpg) -5. Click **OK** to save the connection configuration. +5. 点击 **OK** 保存连接配置。
-## Next steps +## 后续步骤 -- Learn more usage of DataGrip from [the documentation of DataGrip](https://www.jetbrains.com/help/datagrip/getting-started.html). -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Single table reading](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), and [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. +- 通过 [DataGrip 官方文档](https://www.jetbrains.com/help/datagrip/getting-started.html) 了解更多 DataGrip 的用法。 +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节，学习 TiDB 应用开发最佳实践，例如 [插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md) 以及 [SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/) 学习，并在通过考试后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](https://tidb.support.pingcap.com/)。 diff --git a/develop/dev-guide-gui-dbeaver.md b/develop/dev-guide-gui-dbeaver.md index d3cb2b14d3032..00339a3589a89 100644 --- a/develop/dev-guide-gui-dbeaver.md +++ b/develop/dev-guide-gui-dbeaver.md @@ -1,106 +1,106 @@ --- -title: Connect to TiDB with DBeaver -summary: Learn how to connect to TiDB using DBeaver Community. +title: 使用 DBeaver 连接 TiDB +summary: 学习如何使用 DBeaver Community 连接 TiDB。 --- -# Connect to TiDB with DBeaver +# 使用 DBeaver 连接 TiDB -TiDB is a MySQL-compatible database, and [DBeaver Community](https://dbeaver.io/download/) is a free cross-platform database tool for developers, database administrators, analysts, and everyone working with data. +TiDB 是一个兼容 MySQL 的数据库，[DBeaver Community](https://dbeaver.io/download/) 是一款免费的跨平台数据库工具，适用于开发者、数据库管理员、分析师以及所有与数据打交道的人。 -In this tutorial, you can learn how to connect to your TiDB cluster using DBeaver Community. +在本教程中，你可以学习如何使用 DBeaver Community 连接到你的 TiDB 集群。 -> **Note:** +> **注意：** > -> This tutorial is compatible with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed. +> 本教程兼容 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及 TiDB 自建集群。 -## Prerequisites +## 前置条件 -To complete this tutorial, you need: +完成本教程，你需要： -- [DBeaver Community **23.0.3** or higher](https://dbeaver.io/download/). -- A TiDB cluster. +- [DBeaver Community **23.0.3** 或更高版本](https://dbeaver.io/download/)。 +- 一个 TiDB 集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参照[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参照[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster) 或[部署生产环境 TiDB 集群](/production-deployment-using-tiup.md) 创建本地集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参照[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参照[部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster) 或[部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) 创建本地集群。 -## Connect to TiDB +## 连接 TiDB -Connect to your TiDB cluster depending on the TiDB deployment option you've selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群的名称，进入其概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确认连接对话框中的配置与你的操作环境一致。 - - **Connection Type** is set to `Public` - - **Branch** is set to `main` - - **Connect With** is set to `DBeaver` - - **Operating System** matches your environment. + - **Connection Type** 设置为 `Public` + - **Branch** 设置为 `main` + - **Connect With** 设置为 `DBeaver` + - **Operating System** 与你的环境一致 -4. Click **Generate Password** to create a random password. +4. 点击 **Generate Password** 生成一个随机密码。 - > **Tip:** + > **提示：** > - > If you have created a password before, you can either use the original password or click **Reset Password** to generate a new one. + > 如果你之前已经创建过密码，可以继续使用原密码，或者点击 **Reset Password** 生成新密码。 -5. Launch DBeaver and click **New Database Connection** in the upper-left corner. In the **Connect to a database** dialog, select **TiDB** from the list, and then click **Next**. +5. 启动 DBeaver，点击左上角的 **New Database Connection**。在 **Connect to a database** 对话框中，从列表中选择 **TiDB**，然后点击 **Next**。 - ![Select TiDB as the database in DBeaver](/media/develop/dbeaver-select-database.jpg) + ![在 DBeaver 中选择 TiDB 作为数据库](/media/develop/dbeaver-select-database.jpg) -6. Copy the connection string from the TiDB Cloud connection dialog. In DBeaver, select **URL** for **Connect by** and paste the connection string into the **URL** field. +6. 从 TiDB Cloud 连接对话框中复制连接字符串。在 DBeaver 中，**Connect by** 选择 **URL**，并将连接字符串粘贴到 **URL** 字段。 -7. In the **Authentication (Database Native)** section, enter your **Username** and **Password**. An example is as follows: +7. 在 **Authentication (Database Native)** 部分，输入你的 **Username** 和 **Password**。示例如下： - ![Configure connection settings for {{{ .starter }}}](/media/develop/dbeaver-connection-settings-serverless.jpg) + ![配置 TiDB Cloud Serverless 的连接设置](/media/develop/dbeaver-connection-settings-serverless.jpg) -8. Click **Test Connection** to validate the connection to the {{{ .starter }}} cluster. +8. 点击 **Test Connection** 验证与 TiDB Cloud Serverless 集群的连接。 - If the **Download driver files** dialog is displayed, click **Download** to get the driver files. + 如果弹出 **Download driver files** 对话框，点击 **Download** 下载驱动文件。 - ![Download driver files](/media/develop/dbeaver-download-driver.jpg) + ![下载驱动文件](/media/develop/dbeaver-download-driver.jpg) - If the connection test is successful, the **Connection test** dialog is displayed as follows. Click **OK** to close it. + 如果连接测试成功，会弹出 **Connection test** 对话框，如下所示。点击 **OK** 关闭。 - ![Connection test result](/media/develop/dbeaver-connection-test.jpg) + ![连接测试结果](/media/develop/dbeaver-connection-test.jpg) -9. Click **Finish** to save the connection configuration. +9. 点击 **Finish** 保存连接配置。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群的名称，进入其概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表中选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还没有配置 IP 访问列表，点击 **Configure IP Access List**，或参照 [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 进行配置后再首次连接。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息参见 [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Launch DBeaver and click **New Database Connection** in the upper-left corner. In the **Connect to a database** dialog, select **TiDB** from the list, and then click **Next**. +4. 启动 DBeaver，点击左上角的 **New Database Connection**。在 **Connect to a database** 对话框中，从列表中选择 **TiDB**，然后点击 **Next**。 - ![Select TiDB as the database in DBeaver](/media/develop/dbeaver-select-database.jpg) + ![在 DBeaver 中选择 TiDB 作为数据库](/media/develop/dbeaver-select-database.jpg) -5. Copy and paste the appropriate connection string into the DBeaver connection panel. The mappings between DBeaver fields and TiDB Cloud Dedicated connection string are as follows: +5. 将相应的连接字符串复制并粘贴到 DBeaver 的连接面板。DBeaver 字段与 TiDB Cloud Dedicated 连接字符串的映射关系如下： | DBeaver field | TiDB Cloud Dedicated connection string | |---------------| ------------------------------- | @@ -109,71 +109,71 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele | Username | `{user}` | | Password | `{password}` | - An example is as follows: + 示例如下： - ![Configure connection settings for TiDB Cloud Dedicated](/media/develop/dbeaver-connection-settings-dedicated.jpg) + ![配置 TiDB Cloud Dedicated 的连接设置](/media/develop/dbeaver-connection-settings-dedicated.jpg) -6. Click **Test Connection** to validate the connection to the TiDB Cloud Dedicated cluster. +6. 点击 **Test Connection** 验证与 TiDB Cloud Dedicated 集群的连接。 - If the **Download driver files** dialog is displayed, click **Download** to get the driver files. + 如果弹出 **Download driver files** 对话框，点击 **Download** 下载驱动文件。 - ![Download driver files](/media/develop/dbeaver-download-driver.jpg) + ![下载驱动文件](/media/develop/dbeaver-download-driver.jpg) - If the connection test is successful, the **Connection test** dialog is displayed as follows. Click **OK** to close it. + 如果连接测试成功，会弹出 **Connection test** 对话框，如下所示。点击 **OK** 关闭。 - ![Connection test result](/media/develop/dbeaver-connection-test.jpg) + ![连接测试结果](/media/develop/dbeaver-connection-test.jpg) -7. Click **Finish** to save the connection configuration. +7. 点击 **Finish** 保存连接配置。
-1. Launch DBeaver and click **New Database Connection** in the upper-left corner. In the **Connect to a database** dialog, select **TiDB** from the list, and then click **Next**. +1. 启动 DBeaver，点击左上角的 **New Database Connection**。在 **Connect to a database** 对话框中，从列表中选择 **TiDB**，然后点击 **Next**。 - ![Select TiDB as the database in DBeaver](/media/develop/dbeaver-select-database.jpg) + ![在 DBeaver 中选择 TiDB 作为数据库](/media/develop/dbeaver-select-database.jpg) -2. Configure the following connection parameters: +2. 配置以下连接参数： - - **Server Host**: The IP address or domain name of your TiDB Self-Managed cluster. - - **Port**: The port number of your TiDB Self-Managed cluster. - - **Username**: The username to use to connect to your TiDB Self-Managed cluster. - - **Password**: The password of the username. + - **Server Host**：你的 TiDB 自建集群的 IP 地址或域名 + - **Port**：你的 TiDB 自建集群的端口号 + - **Username**：用于连接 TiDB 自建集群的用户名 + - **Password**：该用户名的密码 - An example is as follows: + 示例如下： - ![Configure connection settings for TiDB Self-Managed](/media/develop/dbeaver-connection-settings-self-hosted.jpg) + ![配置 TiDB 自建集群的连接设置](/media/develop/dbeaver-connection-settings-self-hosted.jpg) -3. Click **Test Connection** to validate the connection to the TiDB Self-Managed cluster. +3. 点击 **Test Connection** 验证与 TiDB 自建集群的连接。 - If the **Download driver files** dialog is displayed, click **Download** to get the driver files. + 如果弹出 **Download driver files** 对话框，点击 **Download** 下载驱动文件。 - ![Download driver files](/media/develop/dbeaver-download-driver.jpg) + ![下载驱动文件](/media/develop/dbeaver-download-driver.jpg) - If the connection test is successful, the **Connection test** dialog is displayed as follows. Click **OK** to close it. + 如果连接测试成功，会弹出 **Connection test** 对话框，如下所示。点击 **OK** 关闭。 - ![Connection test result](/media/develop/dbeaver-connection-test.jpg) + ![连接测试结果](/media/develop/dbeaver-connection-test.jpg) -4. Click **Finish** to save the connection configuration. +4. 点击 **Finish** 保存连接配置。
-## Next steps +## 后续步骤 -- Learn more usage of DBeaver from [the documentation of DBeaver](https://github.com/dbeaver/dbeaver/wiki). -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Single table reading](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), and [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. +- 通过 [DBeaver 的文档](https://github.com/dbeaver/dbeaver/wiki) 了解更多 DBeaver 的用法。 +- 通过 [开发者指南](/develop/dev-guide-overview.md) 中的各章节，学习 TiDB 应用开发的最佳实践，例如 [插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md) 以及 [SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/)，并在通过考试后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或[提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或[提交支持工单](https://tidb.support.pingcap.com/)。 - + \ No newline at end of file diff --git a/develop/dev-guide-gui-mysql-workbench.md b/develop/dev-guide-gui-mysql-workbench.md index 5825b345ea7a5..cecf8e0a9c152 100644 --- a/develop/dev-guide-gui-mysql-workbench.md +++ b/develop/dev-guide-gui-mysql-workbench.md @@ -1,185 +1,185 @@ --- -title: Connect to TiDB with MySQL Workbench -summary: Learn how to connect to TiDB using MySQL Workbench. +title: 使用 MySQL Workbench 连接 TiDB +summary: 学习如何使用 MySQL Workbench 连接 TiDB。 --- -# Connect to TiDB with MySQL Workbench +# 使用 MySQL Workbench 连接 TiDB -TiDB is a MySQL-compatible database, and [MySQL Workbench](https://www.mysql.com/products/workbench/) is a GUI tool set for MySQL database users. +TiDB 是兼容 MySQL 的数据库，[MySQL Workbench](https://www.mysql.com/products/workbench/) 是为 MySQL 数据库用户提供的图形化工具集。 > **Warning:** > -> - Although you can use MySQL Workbench to connect to TiDB due to its MySQL compatibility, MySQL Workbench does not fully support TiDB. You might encounter some issues during usage as it treats TiDB as MySQL. -> - It is recommended to use other GUI tools that officially support TiDB, such as [DataGrip](/develop/dev-guide-gui-datagrip.md), [DBeaver](/develop/dev-guide-gui-dbeaver.md), and [VS Code SQLTools](/develop/dev-guide-gui-vscode-sqltools.md). For a complete list of GUI tools that fully supported by TiDB, see [Third-party tools supported by TiDB](/develop/dev-guide-third-party-support.md#gui). +> - 虽然你可以因为 TiDB 的 MySQL 兼容性而使用 MySQL Workbench 连接 TiDB，但 MySQL Workbench 并不完全支持 TiDB。在使用过程中可能会遇到一些问题，因为它会将 TiDB 视为 MySQL。 +> - 推荐使用官方支持 TiDB 的其他 GUI 工具，如 [DataGrip](/develop/dev-guide-gui-datagrip.md)、[DBeaver](/develop/dev-guide-gui-dbeaver.md) 和 [VS Code SQLTools](/develop/dev-guide-gui-vscode-sqltools.md)。完整支持 TiDB 的 GUI 工具列表请参见 [TiDB 支持的第三方工具](/develop/dev-guide-third-party-support.md#gui)。 -In this tutorial, you can learn how to connect to your TiDB cluster using MySQL Workbench. +在本教程中，你可以学习如何使用 MySQL Workbench 连接到你的 TiDB 集群。 > **Note:** > -> This tutorial is compatible with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed. +> 本教程兼容 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及 TiDB 自建集群。 -## Prerequisites +## 前提条件 -To complete this tutorial, you need: +完成本教程，你需要： -- [MySQL Workbench](https://dev.mysql.com/downloads/workbench/) **8.0.31** or later versions. -- A TiDB cluster. +- [MySQL Workbench](https://dev.mysql.com/downloads/workbench/) **8.0.31** 或更高版本。 +- 一个 TiDB 集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参照 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参照 [部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](/production-deployment-using-tiup.md) 创建本地集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参照 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参照 [部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) 创建本地集群。 -## Connect to TiDB +## 连接 TiDB -Connect to your TiDB cluster depending on the TiDB deployment option you have selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称，进入该集群的概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确保连接对话框中的配置与你的操作环境一致。 - - **Connection Type** is set to `Public`. - - **Branch** is set to `main`. - - **Connect With** is set to `MySQL Workbench`. - - **Operating System** matches your environment. + - **Connection Type** 设置为 `Public`。 + - **Branch** 设置为 `main`。 + - **Connect With** 设置为 `MySQL Workbench`。 + - **Operating System** 与你的环境一致。 -4. Click **Generate Password** to create a random password. +4. 点击 **Generate Password** 生成一个随机密码。 > **Tip:** > - > If you have created a password before, you can either use the original password or click **Reset Password** to generate a new one. + > 如果你之前已经创建过密码，可以继续使用原密码，或者点击 **Reset Password** 生成新密码。 -5. Launch MySQL Workbench and click **+** near the **MySQL Connections** title. +5. 启动 MySQL Workbench，点击 **MySQL Connections** 标题旁的 **+**。 ![MySQL Workbench: add new connection](/media/develop/mysql-workbench-add-new-connection.png) -6. In the **Setup New Connection** dialog, configure the following connection parameters: +6. 在 **Setup New Connection** 对话框中，配置以下连接参数： - - **Connection Name**: give this connection a meaningful name. - - **Hostname**: enter the `HOST` parameter from the TiDB Cloud connection dialog. - - **Port**: enter the `PORT` parameter from the TiDB Cloud connection dialog. - - **Username**: enter the `USERNAME` parameter from the TiDB Cloud connection dialog. - - **Password**: click **Store in Keychain ...** or **Store in Vault**, enter the password of the {{{ .starter }}} cluster, and then click **OK** to store the password. + - **Connection Name**：为该连接起一个有意义的名称。 + - **Hostname**：输入 TiDB Cloud 连接对话框中的 `HOST` 参数。 + - **Port**：输入 TiDB Cloud 连接对话框中的 `PORT` 参数。 + - **Username**：输入 TiDB Cloud 连接对话框中的 `USERNAME` 参数。 + - **Password**：点击 **Store in Keychain ...** 或 **Store in Vault**，输入 TiDB Cloud Serverless 集群的密码，然后点击 **OK** 保存密码。 - ![MySQL Workbench: store the password of {{{ .starter }}} in keychain](/media/develop/mysql-workbench-store-password-in-keychain.png) + ![MySQL Workbench: store the password of TiDB Cloud Serverless in keychain](/media/develop/mysql-workbench-store-password-in-keychain.png) - The following figure shows an example of the connection parameters: + 下图展示了连接参数的示例： - ![MySQL Workbench: configure connection settings for {{{ .starter }}}](/media/develop/mysql-workbench-connection-config-serverless-parameters.png) + ![MySQL Workbench: configure connection settings for TiDB Cloud Serverless](/media/develop/mysql-workbench-connection-config-serverless-parameters.png) -7. Click **Test Connection** to validate the connection to the {{{ .starter }}} cluster. +7. 点击 **Test Connection** 验证与 TiDB Cloud Serverless 集群的连接。 -8. If the connection test is successful, you can see the **Successfully made the MySQL connection** message. Click **OK** to save the connection configuration. +8. 如果连接测试成功，你会看到 **Successfully made the MySQL connection** 消息。点击 **OK** 保存连接配置。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称，进入该集群的概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还没有配置 IP 访问列表，点击 **Configure IP Access List** 或参照 [配置 IP 访问列表](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 进行配置后再首次连接。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息参见 [连接到你的 TiDB Cloud Dedicated 集群](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Launch MySQL Workbench and click **+** near the **MySQL Connections** title. +4. 启动 MySQL Workbench，点击 **MySQL Connections** 标题旁的 **+**。 ![MySQL Workbench: add new connection](/media/develop/mysql-workbench-add-new-connection.png) -5. In the **Setup New Connection** dialog, configure the following connection parameters: +5. 在 **Setup New Connection** 对话框中，配置以下连接参数： - - **Connection Name**: give this connection a meaningful name. - - **Hostname**: enter the `HOST` parameter from the TiDB Cloud connection dialog. - - **Port**: enter the `PORT` parameter from the TiDB Cloud connection dialog. - - **Username**: enter the `USERNAME` parameter from the TiDB Cloud connection dialog. - - **Password**: click **Store in Keychain ...**, enter the password of the TiDB Cloud Dedicated cluster, and then click **OK** to store the password. + - **Connection Name**：为该连接起一个有意义的名称。 + - **Hostname**：输入 TiDB Cloud 连接对话框中的 `HOST` 参数。 + - **Port**：输入 TiDB Cloud 连接对话框中的 `PORT` 参数。 + - **Username**：输入 TiDB Cloud 连接对话框中的 `USERNAME` 参数。 + - **Password**：点击 **Store in Keychain ...**，输入 TiDB Cloud Dedicated 集群的密码，然后点击 **OK** 保存密码。 ![MySQL Workbench: store the password of TiDB Cloud Dedicated in keychain](/media/develop/mysql-workbench-store-dedicated-password-in-keychain.png) - The following figure shows an example of the connection parameters: + 下图展示了连接参数的示例： ![MySQL Workbench: configure connection settings for TiDB Cloud Dedicated](/media/develop/mysql-workbench-connection-config-dedicated-parameters.png) -6. Click **Test Connection** to validate the connection to the TiDB Cloud Dedicated cluster. +6. 点击 **Test Connection** 验证与 TiDB Cloud Dedicated 集群的连接。 -7. If the connection test is successful, you can see the **Successfully made the MySQL connection** message. Click **OK** to save the connection configuration. +7. 如果连接测试成功，你会看到 **Successfully made the MySQL connection** 消息。点击 **OK** 保存连接配置。
-1. Launch MySQL Workbench and click **+** near the **MySQL Connections** title. +1. 启动 MySQL Workbench，点击 **MySQL Connections** 标题旁的 **+**。 ![MySQL Workbench: add new connection](/media/develop/mysql-workbench-add-new-connection.png) -2. In the **Setup New Connection** dialog, configure the following connection parameters: +2. 在 **Setup New Connection** 对话框中，配置以下连接参数： - - **Connection Name**: give this connection a meaningful name. - - **Hostname**: enter the IP address or domain name of your TiDB Self-Managed cluster. - - **Port**: enter the port number of your TiDB Self-Managed cluster. - - **Username**: enter the username to use to connect to your TiDB. - - **Password**: click **Store in Keychain ...**, enter the password to use to connect to your TiDB cluster, and then click **OK** to store the password. + - **Connection Name**：为该连接起一个有意义的名称。 + - **Hostname**：输入你的 TiDB 自建集群的 IP 地址或域名。 + - **Port**：输入你的 TiDB 自建集群的端口号。 + - **Username**：输入用于连接 TiDB 的用户名。 + - **Password**：点击 **Store in Keychain ...**，输入用于连接 TiDB 集群的密码，然后点击 **OK** 保存密码。 ![MySQL Workbench: store the password of TiDB Self-Managed in keychain](/media/develop/mysql-workbench-store-self-hosted-password-in-keychain.png) - The following figure shows an example of the connection parameters: + 下图展示了连接参数的示例： ![MySQL Workbench: configure connection settings for TiDB Self-Managed](/media/develop/mysql-workbench-connection-config-self-hosted-parameters.png) -3. Click **Test Connection** to validate the connection to the TiDB Self-Managed cluster. +3. 点击 **Test Connection** 验证与 TiDB 自建集群的连接。 -4. If the connection test is successful, you can see the **Successfully made the MySQL connection** message. Click **OK** to save the connection configuration. +4. 如果连接测试成功，你会看到 **Successfully made the MySQL connection** 消息。点击 **OK** 保存连接配置。
-## FAQs +## 常见问题 -### How to handle the connection timeout error "Error Code: 2013. Lost connection to MySQL server during query"? +### 如何处理连接超时错误 "Error Code: 2013. Lost connection to MySQL server during query"？ -This error indicates that the query execution time exceeds the timeout limit. To resolve this issue, you can adjust the timeout settings by the following steps: +该错误表示查询执行时间超过了超时时间限制。为解决此问题，你可以通过以下步骤调整超时设置： -1. Launch MySQL Workbench and navigate to the **Workbench Preferences** page. -2. In the **SQL Editor** > **MySQL Session** section, configure the **DBMS connection read timeout interval (in seconds)** option. This sets the maximum amount of time (in seconds) that a query can take before MySQL Workbench disconnects from the server. +1. 启动 MySQL Workbench，进入 **Workbench Preferences** 页面。 +2. 在 **SQL Editor** > **MySQL Session** 部分，配置 **DBMS connection read timeout interval (in seconds)** 选项。该选项设置了查询最大允许执行时间（秒），超时后 MySQL Workbench 会断开与服务器的连接。 ![MySQL Workbench: adjust timeout option in SQL Editor settings](/media/develop/mysql-workbench-adjust-sqleditor-read-timeout.jpg) -For more information, see [MySQL Workbench frequently asked questions](https://dev.mysql.com/doc/workbench/en/workbench-faq.html). +更多信息请参见 [MySQL Workbench 常见问题](https://dev.mysql.com/doc/workbench/en/workbench-faq.html)。 -## Next steps +## 后续步骤 -- Learn more usage of MySQL Workbench from [the documentation of MySQL Workbench](https://dev.mysql.com/doc/workbench/en/). -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Single table reading](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), and [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. +- 通过 [MySQL Workbench 官方文档](https://dev.mysql.com/doc/workbench/en/) 了解更多 MySQL Workbench 的用法。 +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节学习 TiDB 应用开发最佳实践，例如 [插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md) 以及 [SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/) 学习，并在通过考试后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](https://tidb.support.pingcap.com/)。 diff --git a/develop/dev-guide-gui-navicat.md b/develop/dev-guide-gui-navicat.md index 1c76b93d99b1e..4b8351e18717d 100644 --- a/develop/dev-guide-gui-navicat.md +++ b/develop/dev-guide-gui-navicat.md @@ -1,165 +1,165 @@ --- -title: Connect to TiDB with Navicat -summary: Learn how to connect to TiDB using Navicat. +title: 使用 Navicat 连接 TiDB +summary: 学习如何使用 Navicat 连接 TiDB。 --- -# Connect to TiDB with Navicat +# 使用 Navicat 连接 TiDB -TiDB is a MySQL-compatible database, and [Navicat](https://www.navicat.com) is a GUI tool set for database users. This tutorial uses the [Navicat Premium](https://www.navicat.com/en/products/navicat-premium) tool to connect to TiDB. +TiDB 是一个兼容 MySQL 的数据库，[Navicat](https://www.navicat.com) 是为数据库用户提供的图形化工具集。本教程使用 [Navicat Premium](https://www.navicat.com/en/products/navicat-premium) 工具连接 TiDB。 -In this tutorial, you can learn how to connect to your TiDB cluster using Navicat. +在本教程中，你可以学习如何使用 Navicat 连接到你的 TiDB 集群。 -> **Note:** +> **注意：** > -> This tutorial is compatible with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed. +> 本教程兼容 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及自托管 TiDB。 -## Prerequisites +## 前提条件 -To complete this tutorial, you need: +完成本教程，你需要： -- [Navicat Premium](https://www.navicat.com) **17.1.6** or later versions. -- A paid account for Navicat Premium. -- A TiDB cluster. +- [Navicat Premium](https://www.navicat.com) **17.1.6** 或更高版本。 +- 一个 Navicat Premium 付费账号。 +- 一个 TiDB 集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参照 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建你自己的 TiDB Cloud 集群。 +- 参照 [部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](/production-deployment-using-tiup.md) 创建本地集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参照 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建你自己的 TiDB Cloud 集群。 +- 参照 [部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) 创建本地集群。 -## Connect to TiDB +## 连接 TiDB -Connect to your TiDB cluster depending on the TiDB deployment option you have selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称，进入集群概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确保连接对话框中的配置与你的操作环境一致。 - - **Connection Type** is set to `Public`. - - **Branch** is set to `main`. - - **Connect With** is set to `Navicat`. - - **Operating System** matches your environment. + - **Connection Type** 设置为 `Public`。 + - **Branch** 设置为 `main`。 + - **Connect With** 设置为 `Navicat`。 + - **Operating System** 与你的环境一致。 -4. Click **Generate Password** to create a random password. +4. 点击 **Generate Password** 生成一个随机密码。 - > **Tip:** + > **提示：** > - > If you have created a password before, you can either use the original password or click **Reset Password** to generate a new one. + > 如果你之前已经创建过密码，可以继续使用原密码，或者点击 **Reset Password** 生成新密码。 -5. Launch Navicat Premium, click **Connection** in the upper-left corner, select **PingCAP** from the **Vendor Filter** list, and double-click **TiDB** in the right panel. +5. 启动 Navicat Premium，点击左上角的 **Connection**，在 **Vendor Filter** 列表中选择 **PingCAP**，在右侧面板双击 **TiDB**。 ![Navicat: add new connection](/media/develop/navicat-premium-add-new-connection.png) -6. In the **New Connection (TiDB)** dialog, configure the following connection parameters: +6. 在 **New Connection (TiDB)** 对话框中，配置以下连接参数： - - **Connection Name**: give this connection a meaningful name. - - **Host**: enter the `HOST` parameter from the TiDB Cloud connection dialog. - - **Port**: enter the `PORT` parameter from the TiDB Cloud connection dialog. - - **User Name**: enter the `USERNAME` parameter from the TiDB Cloud connection dialog. - - **Password**: enter the password of the {{{ .starter }}} cluster. + - **Connection Name**：为该连接命名，便于识别。 + - **Host**：输入 TiDB Cloud 连接对话框中的 `HOST` 参数。 + - **Port**：输入 TiDB Cloud 连接对话框中的 `PORT` 参数。 + - **User Name**：输入 TiDB Cloud 连接对话框中的 `USERNAME` 参数。 + - **Password**：输入 TiDB Cloud Serverless 集群的密码。 - ![Navicat: configure connection general panel for {{{ .starter }}}](/media/develop/navicat-premium-connection-config-serverless-general.png) + ![Navicat: configure connection general panel for TiDB Cloud Serverless](/media/develop/navicat-premium-connection-config-serverless-general.png) -7. Click the **SSL** tab and select **Use SSL**, **Use authentication**, and **Verify server certificate against CA** checkboxes. Then, select the `CA` file from the TiDB Cloud connection dialog into the **CA Certificate** field. +7. 点击 **SSL** 标签页，勾选 **Use SSL**、**Use authentication** 和 **Verify server certificate against CA** 复选框。然后，将 TiDB Cloud 连接对话框中的 `CA` 文件选择到 **CA Certificate** 字段。 - ![Navicat: configure connection SSL panel for {{{ .starter }}}](/media/develop/navicat-premium-connection-config-serverless-ssl.png) + ![Navicat: configure connection SSL panel for TiDB Cloud Serverless](/media/develop/navicat-premium-connection-config-serverless-ssl.png) -8. Click **Test Connection** to validate the connection to the {{{ .starter }}} cluster. +8. 点击 **Test Connection** 验证与 TiDB Cloud Serverless 集群的连接。 -9. If the connection test is successful, you can see the **Connection Successful** message. Click **OK** to finish the connection configuration. +9. 如果连接测试成功，你会看到 **Connection Successful** 消息。点击 **OK** 完成连接配置。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称，进入集群概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还未配置 IP 访问列表，点击 **Configure IP Access List** 或参照 [配置 IP 访问列表](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 进行配置后再首次连接。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息参见 [连接 TiDB Cloud Dedicated 集群](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Click **CA cert** to download the CA certificate. +4. 点击 **CA cert** 下载 CA 证书。 -5. Launch Navicat Premium, click **Connection** in the upper-left corner, select **PingCAP** from the **Vendor Filter** list, and double-click **TiDB** in the right panel. +5. 启动 Navicat Premium，点击左上角的 **Connection**，在 **Vendor Filter** 列表中选择 **PingCAP**，在右侧面板双击 **TiDB**。 ![Navicat: add new connection](/media/develop/navicat-premium-add-new-connection.png) -6. In the **New Connection (TiDB)** dialog, configure the following connection parameters: +6. 在 **New Connection (TiDB)** 对话框中，配置以下连接参数： - - **Connection Name**: give this connection a meaningful name. - - **Host**: enter the `HOST` parameter from the TiDB Cloud connection dialog. - - **Port**: enter the `PORT` parameter from the TiDB Cloud connection dialog. - - **User Name**: enter the `USERNAME` parameter from the TiDB Cloud connection dialog. - - **Password**: enter the password of the TiDB Cloud Dedicated cluster. + - **Connection Name**：为该连接命名，便于识别。 + - **Host**：输入 TiDB Cloud 连接对话框中的 `HOST` 参数。 + - **Port**：输入 TiDB Cloud 连接对话框中的 `PORT` 参数。 + - **User Name**：输入 TiDB Cloud 连接对话框中的 `USERNAME` 参数。 + - **Password**：输入 TiDB Cloud Dedicated 集群的密码。 ![Navicat: configure connection general panel for TiDB Cloud Dedicated](/media/develop/navicat-premium-connection-config-dedicated-general.png) -7. Click the **SSL** tab and select **Use SSL**, **Use authentication**, and **Verify server certificate against CA** checkboxes. Then, select the CA file downloaded in step 4 into the **CA Certificate** field. +7. 点击 **SSL** 标签页，勾选 **Use SSL**、**Use authentication** 和 **Verify server certificate against CA** 复选框。然后，将第 4 步下载的 CA 文件选择到 **CA Certificate** 字段。 ![Navicat: configure connection SSL panel for TiDB Cloud Dedicated](/media/develop/navicat-premium-connection-config-dedicated-ssl.png) -8. **Test Connection** to validate the connection to the TiDB Cloud Dedicated cluster. +8. **Test Connection** 验证与 TiDB Cloud Dedicated 集群的连接。 -9. If the connection test is successful, you can see the **Connection Successful** message. Click **OK** to finish the connection configuration. +9. 如果连接测试成功，你会看到 **Connection Successful** 消息。点击 **OK** 完成连接配置。
-1. Launch Navicat Premium, click **Connection** in the upper-left corner, select **PingCAP** from the **Vendor Filter** list, and double-click **TiDB** in the right panel. +1. 启动 Navicat Premium，点击左上角的 **Connection**，在 **Vendor Filter** 列表中选择 **PingCAP**，在右侧面板双击 **TiDB**。 ![Navicat: add new connection](/media/develop/navicat-premium-add-new-connection.png) -2. In the **New Connection (TiDB)** dialog, configure the following connection parameters: +2. 在 **New Connection (TiDB)** 对话框中，配置以下连接参数： - - **Connection Name**: give this connection a meaningful name. - - **Host**: enter the IP address or domain name of your TiDB Self-Managed cluster. - - **Port**: enter the port number of your TiDB Self-Managed cluster. - - **User Name**: enter the username to use to connect to your TiDB. - - **Password**: enter the password to use to connect to your TiDB. + - **Connection Name**：为该连接命名，便于识别。 + - **Host**：输入你的自托管 TiDB 集群的 IP 地址或域名。 + - **Port**：输入你的自托管 TiDB 集群的端口号。 + - **User Name**：输入连接 TiDB 所用的用户名。 + - **Password**：输入连接 TiDB 所用的密码。 ![Navicat: configure connection general panel for self-hosted TiDB](/media/develop/navicat-premium-connection-config-self-hosted-general.png) -3. Click **Test Connection** to validate the connection to the TiDB Self-Managed cluster. +3. 点击 **Test Connection** 验证与自托管 TiDB 集群的连接。 -4. If the connection test is successful, you can see the **Connection Successful** message. Click **OK** to finish the connection configuration. +4. 如果连接测试成功，你会看到 **Connection Successful** 消息。点击 **OK** 完成连接配置。
-## Next steps +## 后续步骤 -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Single table reading](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), and [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节，学习 TiDB 应用开发最佳实践，例如 [插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md) 以及 [SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/)，考试通过后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](https://tidb.support.pingcap.com/)。 diff --git a/develop/dev-guide-gui-vscode-sqltools.md b/develop/dev-guide-gui-vscode-sqltools.md index 172391b85e2e6..fa7bb205acc66 100644 --- a/develop/dev-guide-gui-vscode-sqltools.md +++ b/develop/dev-guide-gui-vscode-sqltools.md @@ -1,208 +1,208 @@ --- -title: Connect to TiDB with Visual Studio Code -summary: Learn how to connect to TiDB using Visual Studio Code or GitHub Codespaces. +title: 使用 Visual Studio Code 连接 TiDB +summary: 学习如何使用 Visual Studio Code 或 GitHub Codespaces 连接 TiDB。 --- -# Connect to TiDB with Visual Studio Code +# 使用 Visual Studio Code 连接 TiDB -TiDB is a MySQL-compatible database, and [Visual Studio Code (VS Code)](https://code.visualstudio.com/) is a lightweight but powerful source code editor. This tutorial uses the [SQLTools](https://marketplace.visualstudio.com/items?itemName=mtxr.sqltools) extension which supports TiDB as an [official driver](https://marketplace.visualstudio.com/items?itemName=mtxr.sqltools-driver-mysql). +TiDB 是一个兼容 MySQL 的数据库，[Visual Studio Code (VS Code)](https://code.visualstudio.com/) 是一款轻量级但功能强大的源代码编辑器。本教程使用了 [SQLTools](https://marketplace.visualstudio.com/items?itemName=mtxr.sqltools) 扩展，该扩展将 TiDB 作为[官方驱动](https://marketplace.visualstudio.com/items?itemName=mtxr.sqltools-driver-mysql)支持。 -In this tutorial, you can learn how to connect to your TiDB cluster using Visual Studio Code. +在本教程中，你可以学习如何使用 Visual Studio Code 连接到你的 TiDB 集群。 -> **Note:** +> **注意：** > -> - This tutorial is compatible with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed. -> - This tutorial also works with Visual Studio Code Remote Development environments, such as [GitHub Codespaces](https://github.com/features/codespaces), [Visual Studio Code Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers), and [Visual Studio Code WSL](https://code.visualstudio.com/docs/remote/wsl). +> - 本教程兼容 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及 TiDB 自建集群。 +> - 本教程同样适用于 Visual Studio Code 远程开发环境，如 [GitHub Codespaces](https://github.com/features/codespaces)、[Visual Studio Code Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) 和 [Visual Studio Code WSL](https://code.visualstudio.com/docs/remote/wsl)。 -## Prerequisites +## 前置条件 -To complete this tutorial, you need: +完成本教程，你需要： -- [Visual Studio Code](https://code.visualstudio.com/#alt-downloads) **1.72.0** or later versions. -- [SQLTools MySQL/MariaDB/TiDB](https://marketplace.visualstudio.com/items?itemName=mtxr.sqltools-driver-mysql) extension for Visual Studio Code. To install it, you can use one of the following methods: - - Click this link to launch VS Code and install the extension directly. - - Navigate to [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=mtxr.sqltools-driver-mysql) and click **Install**. - - On the **Extensions** tab of your VS Code, search for `mtxr.sqltools-driver-mysql` to get the **SQLTools MySQL/MariaDB/TiDB** extension, and then click **Install**. -- A TiDB cluster. +- [Visual Studio Code](https://code.visualstudio.com/#alt-downloads) **1.72.0** 或更高版本。 +- Visual Studio Code 的 [SQLTools MySQL/MariaDB/TiDB](https://marketplace.visualstudio.com/items?itemName=mtxr.sqltools-driver-mysql) 扩展。你可以通过以下任一方式安装： + - 点击 此链接 直接启动 VS Code 并安装扩展。 + - 访问 [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=mtxr.sqltools-driver-mysql) 并点击 **Install**。 + - 在 VS Code 的 **Extensions** 标签页中，搜索 `mtxr.sqltools-driver-mysql` 获取 **SQLTools MySQL/MariaDB/TiDB** 扩展，然后点击 **Install**。 +- 一个 TiDB 集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参照[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参照[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster) 或[部署生产环境 TiDB 集群](/production-deployment-using-tiup.md) 创建本地集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参照[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参照[部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster) 或[部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) 创建本地集群。 -## Connect to TiDB +## 连接 TiDB -Connect to your TiDB cluster depending on the TiDB deployment option you have selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称，进入其概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确保连接对话框中的配置与你的操作环境一致。 - - **Connection Type** is set to `Public`. - - **Branch** is set to `main`. - - **Connect With** is set to `VS Code`. - - **Operating System** matches your environment. + - **Connection Type** 设置为 `Public`。 + - **Branch** 设置为 `main`。 + - **Connect With** 设置为 `VS Code`。 + - **Operating System** 与你的环境一致。 - > **Tip:** + > **提示：** > - > If your VS Code is running on a remote development environment, select the remote operating system from the list. For example, if you are using Windows Subsystem for Linux (WSL), switch to the corresponding Linux distribution. This is not necessary if you are using GitHub Codespaces. + > 如果你的 VS Code 运行在远程开发环境中，请从列表中选择远程操作系统。例如，如果你使用 Windows Subsystem for Linux (WSL)，请切换到对应的 Linux 发行版。如果你使用 GitHub Codespaces，则无需此操作。 -4. Click **Generate Password** to create a random password. +4. 点击 **Generate Password** 生成一个随机密码。 - > **Tip:** + > **提示：** > - > If you have created a password before, you can either use the original password or click **Reset Password** to generate a new one. + > 如果你之前已经创建过密码，可以继续使用原密码，或者点击 **Reset Password** 生成新密码。 -5. Launch VS Code and select the **SQLTools** extension on the navigation pane. Under the **CONNECTIONS** section, click **Add New Connection** and select **TiDB** as the database driver. +5. 启动 VS Code，在导航栏选择 **SQLTools** 扩展。在 **CONNECTIONS** 区域，点击 **Add New Connection**，并选择 **TiDB** 作为数据库驱动。 ![VS Code SQLTools: add new connection](/media/develop/vsc-sqltools-add-new-connection.jpg) -6. In the setting pane, configure the following connection parameters: +6. 在设置面板中，配置以下连接参数： - - **Connection name**: give this connection a meaningful name. - - **Connection group**: (optional) give this group of connections a meaningful name. Connections with the same group name will be grouped together. - - **Connect using**: select **Server and Port**. - - **Server Address**: enter the `HOST` parameter from the TiDB Cloud connection dialog. - - **Port**: enter the `PORT` parameter from the TiDB Cloud connection dialog. - - **Database**: enter the database that you want to connect to. - - **Username**: enter the `USERNAME` parameter from the TiDB Cloud connection dialog. - - **Password mode**: select **SQLTools Driver Credentials**. - - In the **MySQL driver specific options** area, configure the following parameters: + - **Connection name**：为该连接起一个有意义的名称。 + - **Connection group**：（可选）为该连接组起一个有意义的名称。相同组名的连接会被归为一组。 + - **Connect using**：选择 **Server and Port**。 + - **Server Address**：填写 TiDB Cloud 连接对话框中的 `HOST` 参数。 + - **Port**：填写 TiDB Cloud 连接对话框中的 `PORT` 参数。 + - **Database**：填写你要连接的数据库名称。 + - **Username**：填写 TiDB Cloud 连接对话框中的 `USERNAME` 参数。 + - **Password mode**：选择 **SQLTools Driver Credentials**。 + - 在 **MySQL driver specific options** 区域，配置以下参数： - - **Authentication Protocol**: select **default**. - - **SSL**: select **Enabled**. {{{ .starter }}} requires a secure connection. In the **SSL Options (node.TLSSocket)** area, configure the **Certificate Authority (CA) Certificate File** field as the `CA` parameter from the TiDB Cloud connection dialog. + - **Authentication Protocol**：选择 **default**。 + - **SSL**：选择 **Enabled**。TiDB Cloud Serverless 要求安全连接。在 **SSL Options (node.TLSSocket)** 区域，将 **Certificate Authority (CA) Certificate File** 字段配置为 TiDB Cloud 连接对话框中的 `CA` 参数。 - > **Note:** + > **注意：** > - > If you are running on Windows or GitHub Codespaces, you can leave **SSL** blank. By default SQLTools trusts well-known CAs curated by Let's Encrypt. For more information, see [{{{ .starter }}} root certificate management](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-clusters#root-certificate-management). + > 如果你在 Windows 或 GitHub Codespaces 上运行，可以将 **SSL** 留空。SQLTools 默认信任 Let's Encrypt 提供的知名 CA。更多信息参见 [TiDB Cloud Serverless 根证书管理](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-clusters#root-certificate-management)。 - ![VS Code SQLTools: configure connection settings for {{{ .starter }}}](/media/develop/vsc-sqltools-connection-config-serverless.jpg) + ![VS Code SQLTools: configure connection settings for TiDB Cloud Serverless](/media/develop/vsc-sqltools-connection-config-serverless.jpg) -7. Click **TEST CONNECTION** to validate the connection to the {{{ .starter }}} cluster. +7. 点击 **TEST CONNECTION** 验证与 TiDB Cloud Serverless 集群的连接。 - 1. In the pop-up window, click **Allow**. - 2. In the **SQLTools Driver Credentials** dialog, enter the password you created in step 4. + 1. 在弹窗中点击 **Allow**。 + 2. 在 **SQLTools Driver Credentials** 对话框中，输入你在第 4 步创建的密码。 - ![VS Code SQLTools: enter password to connect to {{{ .starter }}}](/media/develop/vsc-sqltools-password.jpg) + ![VS Code SQLTools: enter password to connect to TiDB Cloud Serverless](/media/develop/vsc-sqltools-password.jpg) -8. If the connection test is successful, you can see the **Successfully connected!** message. Click **SAVE CONNECTION** to save the connection configuration. +8. 如果连接测试成功，你会看到 **Successfully connected!** 消息。点击 **SAVE CONNECTION** 保存连接配置。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称，进入其概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还未配置 IP 访问列表，点击 **Configure IP Access List**，或参照 [配置 IP 访问列表](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 进行配置后再首次连接。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息参见 [连接到你的 TiDB Cloud Dedicated 集群](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Launch VS Code and select the **SQLTools** extension on the navigation pane. Under the **CONNECTIONS** section, click **Add New Connection** and select **TiDB** as the database driver. +4. 启动 VS Code，在导航栏选择 **SQLTools** 扩展。在 **CONNECTIONS** 区域，点击 **Add New Connection**，并选择 **TiDB** 作为数据库驱动。 ![VS Code SQLTools: add new connection](/media/develop/vsc-sqltools-add-new-connection.jpg) -5. In the setting pane, configure the following connection parameters: +5. 在设置面板中，配置以下连接参数： - - **Connection name**: give this connection a meaningful name. - - **Connection group**: (optional) give this group of connections a meaningful name. Connections with the same group name will be grouped together. - - **Connect using**: select **Server and Port**. - - **Server Address**: enter the `host` parameter from the TiDB Cloud connection dialog. - - **Port**: enter the `port` parameter from the TiDB Cloud connection dialog. - - **Database**: enter the database that you want to connect to. - - **Username**: enter the `user` parameter from the TiDB Cloud connection dialog. - - **Password mode**: select **SQLTools Driver Credentials**. - - In the **MySQL driver specific options** area, configure the following parameters: + - **Connection name**：为该连接起一个有意义的名称。 + - **Connection group**：（可选）为该连接组起一个有意义的名称。相同组名的连接会被归为一组。 + - **Connect using**：选择 **Server and Port**。 + - **Server Address**：填写 TiDB Cloud 连接对话框中的 `host` 参数。 + - **Port**：填写 TiDB Cloud 连接对话框中的 `port` 参数。 + - **Database**：填写你要连接的数据库名称。 + - **Username**：填写 TiDB Cloud 连接对话框中的 `user` 参数。 + - **Password mode**：选择 **SQLTools Driver Credentials**。 + - 在 **MySQL driver specific options** 区域，配置以下参数： - - **Authentication Protocol**: select **default**. - - **SSL**: select **Disabled**. + - **Authentication Protocol**：选择 **default**。 + - **SSL**：选择 **Disabled**。 ![VS Code SQLTools: configure connection settings for TiDB Cloud Dedicated](/media/develop/vsc-sqltools-connection-config-dedicated.jpg) -6. Click **TEST CONNECTION** to validate the connection to the TiDB Cloud Dedicated cluster. +6. 点击 **TEST CONNECTION** 验证与 TiDB Cloud Dedicated 集群的连接。 - 1. In the pop-up window, click **Allow**. - 2. In the **SQLTools Driver Credentials** dialog, enter the password of the TiDB Cloud Dedicated cluster. + 1. 在弹窗中点击 **Allow**。 + 2. 在 **SQLTools Driver Credentials** 对话框中，输入 TiDB Cloud Dedicated 集群的密码。 ![VS Code SQLTools: enter password to connect to TiDB Cloud Dedicated](/media/develop/vsc-sqltools-password.jpg) -7. If the connection test is successful, you can see the **Successfully connected!** message. Click **SAVE CONNECTION** to save the connection configuration. +7. 如果连接测试成功，你会看到 **Successfully connected!** 消息。点击 **SAVE CONNECTION** 保存连接配置。
-1. Launch VS Code and select the **SQLTools** extension on the navigation pane. Under the **CONNECTIONS** section, click **Add New Connection** and select **TiDB** as the database driver. +1. 启动 VS Code，在导航栏选择 **SQLTools** 扩展。在 **CONNECTIONS** 区域，点击 **Add New Connection**，并选择 **TiDB** 作为数据库驱动。 ![VS Code SQLTools: add new connection](/media/develop/vsc-sqltools-add-new-connection.jpg) -2. In the setting pane, configure the following connection parameters: +2. 在设置面板中，配置以下连接参数： - - **Connection name**: give this connection a meaningful name. - - **Connection group**: (optional) give this group of connections a meaningful name. Connections with the same group name will be grouped together. - - **Connect using**: select **Server and Port**. - - **Server Address**: enter the IP address or domain name of your TiDB Self-Managed cluster. - - **Port**: enter the port number of your TiDB Self-Managed cluster. - - **Database**: enter the database that you want to connect to. - - **Username**: enter the username to use to connect to your TiDB Self-Managed cluster. - - **Password mode**: + - **Connection name**：为该连接起一个有意义的名称。 + - **Connection group**：（可选）为该连接组起一个有意义的名称。相同组名的连接会被归为一组。 + - **Connect using**：选择 **Server and Port**。 + - **Server Address**：填写你的 TiDB 自建集群的 IP 地址或域名。 + - **Port**：填写你的 TiDB 自建集群的端口号。 + - **Database**：填写你要连接的数据库名称。 + - **Username**：填写用于连接 TiDB 自建集群的用户名。 + - **Password mode**： - - If the password is empty, select **Use empty password**. - - Otherwise, select **SQLTools Driver Credentials**. + - 如果密码为空，选择 **Use empty password**。 + - 否则，选择 **SQLTools Driver Credentials**。 - - In the **MySQL driver specific options** area, configure the following parameters: + - 在 **MySQL driver specific options** 区域，配置以下参数： - - **Authentication Protocol**: select **default**. - - **SSL**: select **Disabled**. + - **Authentication Protocol**：选择 **default**。 + - **SSL**：选择 **Disabled**。 ![VS Code SQLTools: configure connection settings for TiDB Self-Managed](/media/develop/vsc-sqltools-connection-config-self-hosted.jpg) -3. Click **TEST CONNECTION** to validate the connection to the TiDB Self-Managed cluster. +3. 点击 **TEST CONNECTION** 验证与 TiDB 自建集群的连接。 - If the password is not empty, click **Allow** in the pop-up window, and then enter the password of the TiDB Self-Managed cluster. + 如果密码不为空，在弹窗中点击 **Allow**，然后输入 TiDB 自建集群的密码。 ![VS Code SQLTools: enter password to connect to TiDB Self-Managed](/media/develop/vsc-sqltools-password.jpg) -4. If the connection test is successful, you can see the **Successfully connected!** message. Click **SAVE CONNECTION** to save the connection configuration. +4. 如果连接测试成功，你会看到 **Successfully connected!** 消息。点击 **SAVE CONNECTION** 保存连接配置。
-## Next steps +## 后续步骤 -- Learn more usage of Visual Studio Code from [the documentation of Visual Studio Code](https://code.visualstudio.com/docs). -- Learn more usage of VS Code SQLTools extension from [the documentation](https://marketplace.visualstudio.com/items?itemName=mtxr.sqltools) and [GitHub repository](https://github.com/mtxr/vscode-sqltools) of SQLTools. -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Single table reading](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), and [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. +- 通过 [Visual Studio Code 官方文档](https://code.visualstudio.com/docs) 学习更多 VS Code 的用法。 +- 通过 [SQLTools 扩展文档](https://marketplace.visualstudio.com/items?itemName=mtxr.sqltools) 和 [GitHub 仓库](https://github.com/mtxr/vscode-sqltools) 学习更多 VS Code SQLTools 扩展的用法。 +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节学习 TiDB 应用开发最佳实践，例如 [插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md) 和 [SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/) 学习，并在通过考试后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或[提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或[提交支持工单](https://tidb.support.pingcap.com/)。 \ No newline at end of file diff --git a/develop/dev-guide-sample-application-cs.md b/develop/dev-guide-sample-application-cs.md index 62280c068be83..3bf4badd70cc0 100644 --- a/develop/dev-guide-sample-application-cs.md +++ b/develop/dev-guide-sample-application-cs.md @@ -1,23 +1,23 @@ --- -title: Connect to TiDB with C# -summary: Learn how to connect to TiDB using C#. This tutorial provides sample C# code snippets for interacting with TiDB. +title: 使用 C# 连接 TiDB +summary: 学习如何使用 C# 连接 TiDB。本教程提供了与 TiDB 交互的 C# 代码示例片段。 --- -# Connect to TiDB with C\# +# 使用 C\# 连接 TiDB -C# (pronounced "C-Sharp") is one of the programming languages in the .NET family, developed by Microsoft. Other .NET languages include VB.NET and F#. In this tutorial, you will use C# along with MySQL Connector/NET to connect a C# application to TiDB using the MySQL protocol. This works because TiDB is highly [compatible with MySQL](/mysql-compatibility.md). +C#（发音为 “C-Sharp”）是 .NET 家族中的一种编程语言，由 Microsoft 开发。其他 .NET 语言还包括 VB.NET 和 F#。在本教程中，你将使用 C# 结合 MySQL Connector/NET，通过 MySQL 协议将 C# 应用程序连接到 TiDB。这是可行的，因为 TiDB 高度 [兼容 MySQL](/mysql-compatibility.md)。 -While .NET is commonly used on Windows, it is also available for macOS and Linux. Across all platforms, the commands and code are largely the same, with only minor differences in prompts and file paths. +虽然 .NET 通常在 Windows 上使用，但它同样适用于 macOS 和 Linux。在所有平台上，命令和代码基本相同，仅在提示符和文件路径上有细微差别。 -## Prerequisites +## 前置条件 -- Download the [.NET 9.0 SDK](https://dotnet.microsoft.com/en-us/download). -- This tutorial uses the `dotnet` command-line tool. Alternatively, you can use the Visual Studio Code IDE to work with C# code. -- To complete this tutorial, you need access to a TiDB instance. You can use a [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier/#tidb-cloud-serverless) or [TiDB Cloud Dedicated](https://docs.pingcap.com/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated) cluster on TiDB Cloud, or a TiDB Self-Managed cluster, such as one started using `tiup playground`. +- 下载 [.NET 9.0 SDK](https://dotnet.microsoft.com/en-us/download)。 +- 本教程使用 `dotnet` 命令行工具。你也可以使用 Visual Studio Code IDE 来编写 C# 代码。 +- 要完成本教程，你需要有一个 TiDB 实例的访问权限。你可以使用 TiDB Cloud 上的 [TiDB Cloud Serverless](https://docs.pingcap.com/tidbcloud/select-cluster-tier/#tidb-cloud-serverless) 或 [TiDB Cloud Dedicated](https://docs.pingcap.com/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated) 集群，或者使用自建的 TiDB 集群，例如通过 `tiup playground` 启动的集群。 -## Step 1. Set up a console project +## 第 1 步：创建控制台项目 -Create a new project using the `console` template. This will generate a new directory named `tidb_cs`. Before running the following command, either navigate to the location where you want this directory to be created, or specify a full path. +使用 `console` 模板创建一个新项目。这会生成一个名为 `tidb_cs` 的新目录。在运行以下命令前，请先切换到你希望创建该目录的位置，或者指定完整路径。 ``` $ dotnet new console -o tidb_cs @@ -28,9 +28,9 @@ Restoring /home/dvaneeden/tidb_cs/tidb_cs.csproj: Restore succeeded. ``` -## Step 2. Add the MySql.Data package +## 第 2 步：添加 MySql.Data 包 -The package manager for .NET is called NuGet. The NuGet package name for MySQL Connector/NET is [MySql.Data](https://www.nuget.org/packages/MySql.Data), which provides support for the MySQL protocol in .NET applications. If you do not specify a version, NuGet installs the latest stable version (for example, version 9.3.0). +.NET 的包管理器叫做 NuGet。MySQL Connector/NET 的 NuGet 包名称为 [MySql.Data](https://www.nuget.org/packages/MySql.Data)，它为 .NET 应用程序提供了 MySQL 协议的支持。如果你没有指定版本，NuGet 会安装最新的稳定版本（例如 9.3.0 版本）。 ``` $ cd tidb_cs @@ -56,9 +56,9 @@ info : Writing assets file to disk. Path: /home/dvaneeden/tidb_cs/obj/project.as log : Restored /home/dvaneeden/tidb_cs/tidb_cs.csproj (in 551 ms). ``` -## Step 3. Update the code +## 第 3 步：更新代码 -Replace the "Hello World" example in `Program.cs` with the following code. +将 `Program.cs` 中的 “Hello World” 示例替换为以下代码。 ```cs using System; @@ -97,20 +97,20 @@ public class Tutorial1 } ``` -This connects to a TiDB instance on the specified IP and port. If you use TiDB Cloud, replace connection string parameters (such as hostname, port, user, and password) with the details provided in the [TiDB Cloud console](https://tidbcloud.com/). +这段代码会连接到指定 IP 和端口的 TiDB 实例。如果你使用 TiDB Cloud，请将连接字符串参数（如 hostname、port、user 和 password）替换为 [TiDB Cloud 控制台](https://tidbcloud.com/) 中提供的详细信息。 -The code connects to the database, prints its version, then executes a SQL query using [`TIDB_VERSION()`](/functions-and-operators/tidb-functions.md#tidb_version) to retrieve more detailed version information, and finally prints this result. +该代码会连接到数据库，打印其版本信息，然后通过执行 [`TIDB_VERSION()`](/functions-and-operators/tidb-functions.md#tidb_version) SQL 查询获取更详细的版本信息，并最终打印该结果。 -## Step 4. Run the program +## 第 4 步：运行程序 ``` $ dotnet run Connecting to TiDB... -Connected to: 8.0.11-TiDB-{{{ .tidb-version }}} +Connected to: 8.0.11-TiDB-vv8.5.2 Version details: -Release Version: {{{ .tidb-version }}} +Release Version: vv8.5.2 Edition: Community Git Commit Hash: f43a13324440f92209e2a9f04c0bbe9cf763978d Git Branch: HEAD @@ -120,4 +120,4 @@ Race Enabled: false Check Table Before Drop: false Store: tikv Done. -``` +``` \ No newline at end of file diff --git a/develop/dev-guide-sample-application-golang-gorm.md b/develop/dev-guide-sample-application-golang-gorm.md index 47fa580d5efed..55dbd5b2e20fc 100644 --- a/develop/dev-guide-sample-application-golang-gorm.md +++ b/develop/dev-guide-sample-application-golang-gorm.md @@ -1,95 +1,95 @@ --- -title: Connect to TiDB with GORM -summary: Learn how to connect to TiDB using GORM. This tutorial gives Golang sample code snippets that work with TiDB using GORM. +title: 使用 GORM 连接 TiDB +summary: 学习如何使用 GORM 连接 TiDB。本教程提供了可与 TiDB 搭配使用的 Golang 示例代码片段。 --- -# Connect to TiDB with GORM +# 使用 GORM 连接 TiDB -TiDB is a MySQL-compatible database, and [GORM](https://gorm.io/index.html) is a popular open-source ORM framework for Golang. GORM adapts to TiDB features such as `AUTO_RANDOM` and [supports TiDB as a default database option](https://gorm.io/docs/connecting_to_the_database.html#TiDB). +TiDB 是兼容 MySQL 的数据库，[GORM](https://gorm.io/index.html) 是 Golang 领域流行的开源 ORM 框架。GORM 适配了 TiDB 的特性，如 `AUTO_RANDOM`，并且[默认支持 TiDB 作为数据库选项](https://gorm.io/docs/connecting_to_the_database.html#TiDB)。 -In this tutorial, you can learn how to use TiDB and GORM to accomplish the following tasks: +在本教程中，你可以学习如何使用 TiDB 和 GORM 完成以下任务： -- Set up your environment. -- Connect to your TiDB cluster using GORM. -- Build and run your application. Optionally, you can find [sample code snippets](#sample-code-snippets) for basic CRUD operations. +- 搭建你的开发环境。 +- 使用 GORM 连接到你的 TiDB 集群。 +- 构建并运行你的应用程序。你还可以在[示例代码片段](#sample-code-snippets)中找到基本的 CRUD 操作示例。 > **Note:** > -> This tutorial works with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed. +> 本教程适用于 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及自建 TiDB 集群。 -## Prerequisites +## 前置条件 -To complete this tutorial, you need: +完成本教程，你需要： -- [Go](https://go.dev/) **1.20** or higher. -- [Git](https://git-scm.com/downloads). -- A TiDB cluster. +- [Go](https://go.dev/) **1.20** 或更高版本。 +- [Git](https://git-scm.com/downloads)。 +- 一个 TiDB 集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md)来创建属于你自己的 TiDB Cloud 集群。 +- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署生产环境 TiDB 集群](/production-deployment-using-tiup.md)来创建本地集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md)来创建属于你自己的 TiDB Cloud 集群。 +- 参考[部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster)或[部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup)来创建本地集群。 -## Run the sample app to connect to TiDB +## 运行示例应用并连接 TiDB -This section demonstrates how to run the sample application code and connect to TiDB. +本节演示如何运行示例应用代码并连接到 TiDB。 -### Step 1: Clone the sample app repository +### 第 1 步：克隆示例应用仓库 -Run the following commands in your terminal window to clone the sample code repository: +在终端窗口中运行以下命令，克隆示例代码仓库： ```shell git clone https://github.com/tidb-samples/tidb-golang-gorm-quickstart.git cd tidb-golang-gorm-quickstart ``` -### Step 2: Configure connection information +### 第 2 步：配置连接信息 -Connect to your TiDB cluster depending on the TiDB deployment option you've selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确保连接对话框中的配置与你的操作环境一致。 - - **Connection Type** is set to `Public` - - **Branch** is set to `main` - - **Connect With** is set to `General` - - **Operating System** matches your environment. + - **Connection Type** 设置为 `Public` + - **Branch** 设置为 `main` + - **Connect With** 设置为 `General` + - **Operating System** 与你的环境一致 > **Tip:** > - > If your program is running in Windows Subsystem for Linux (WSL), switch to the corresponding Linux distribution. + > 如果你的程序运行在 Windows Subsystem for Linux (WSL) 中，请切换到对应的 Linux 发行版。 -4. Click **Generate Password** to create a random password. +4. 点击 **Generate Password** 生成随机密码。 > **Tip:** > - > If you have created a password before, you can either use the original password or click **Reset Password** to generate a new one. + > 如果你之前已经创建过密码，可以继续使用原密码，或者点击 **Reset Password** 生成新密码。 -5. Run the following command to copy `.env.example` and rename it to `.env`: +5. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： ```shell cp .env.example .env ``` -6. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +6. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例结果如下： ```dotenv TIDB_HOST='{host}' # e.g. gateway01.ap-northeast-1.prod.aws.tidbcloud.com @@ -100,32 +100,32 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele USE_SSL='true' ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog. + 请务必将 `{}` 占位符替换为连接对话框中获取的参数。 - {{{ .starter }}} requires a secure connection. Therefore, you need to set the value of `USE_SSL` to `true`. + TiDB Cloud Serverless 需要安全连接，因此你需要将 `USE_SSL` 的值设置为 `true`。 -7. Save the `.env` file. +7. 保存 `.env` 文件。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还未配置 IP 访问列表，请点击 **Configure IP Access List**，或参考 [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 进行首次连接前的配置。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息请参见 [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Run the following command to copy `.env.example` and rename it to `.env`: +4. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： ```shell cp .env.example .env ``` -5. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +5. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例结果如下： ```dotenv TIDB_HOST='{host}' # e.g. tidb.xxxx.clusters.tidb-cloud.com @@ -136,20 +136,20 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele USE_SSL='false' ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog. + 请务必将 `{}` 占位符替换为连接对话框中获取的参数。 -6. Save the `.env` file. +6. 保存 `.env` 文件。
-
+
-1. Run the following command to copy `.env.example` and rename it to `.env`: +1. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： ```shell cp .env.example .env ``` -2. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +2. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例结果如下： ```dotenv TIDB_HOST='{host}' @@ -160,30 +160,30 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele USE_SSL='false' ``` - Be sure to replace the placeholders `{}` with the connection parameters, and set `USE_SSL` to `false`. If you are running TiDB locally, the default host address is `127.0.0.1`, and the password is empty. + 请务必将 `{}` 占位符替换为实际的连接参数，并将 `USE_SSL` 设置为 `false`。如果你在本地运行 TiDB，默认主机地址为 `127.0.0.1`，密码为空。 -3. Save the `.env` file. +3. 保存 `.env` 文件。
-### Step 3: Run the code and check the result +### 第 3 步：运行代码并检查结果 -1. Execute the following command to run the sample code: +1. 执行以下命令运行示例代码： ```shell make ``` -2. Check the [Expected-Output.txt](https://github.com/tidb-samples/tidb-golang-gorm-quickstart/blob/main/Expected-Output.txt) to see if the output matches. +2. 检查 [Expected-Output.txt](https://github.com/tidb-samples/tidb-golang-gorm-quickstart/blob/main/Expected-Output.txt) 文件，确认输出是否一致。 -## Sample code snippets +## 示例代码片段 -You can refer to the following sample code snippets to complete your own application development. +你可以参考以下示例代码片段，完成你自己的应用开发。 -For complete sample code and how to run it, check out the [tidb-samples/tidb-golang-gorm-quickstart](https://github.com/tidb-samples/tidb-golang-gorm-quickstart) repository. +完整示例代码及运行方式请参考 [tidb-samples/tidb-golang-gorm-quickstart](https://github.com/tidb-samples/tidb-golang-gorm-quickstart) 仓库。 -### Connect to TiDB +### 连接 TiDB ```golang func createDB() *gorm.DB { @@ -201,57 +201,57 @@ func createDB() *gorm.DB { } ``` -When using this function, you need to replace `${tidb_host}`, `${tidb_port}`, `${tidb_user}`, `${tidb_password}`, and `${tidb_db_name}` with the actual values of your TiDB cluster. {{{ .starter }}} requires a secure connection. Therefore, you need to set the value of `${use_ssl}` to `true`. +使用该函数时，你需要将 `${tidb_host}`、`${tidb_port}`、`${tidb_user}`、`${tidb_password}` 和 `${tidb_db_name}` 替换为你 TiDB 集群的实际值。TiDB Cloud Serverless 需要安全连接，因此你需要将 `${use_ssl}` 的值设置为 `true`。 -### Insert data +### 插入数据 ```golang db.Create(&Player{ID: "id", Coins: 1, Goods: 1}) ``` -For more information, refer to [Insert data](/develop/dev-guide-insert-data.md). +更多信息请参考 [插入数据](/develop/dev-guide-insert-data.md)。 -### Query data +### 查询数据 ```golang var queryPlayer Player db.Find(&queryPlayer, "id = ?", "id") ``` -For more information, refer to [Query data](/develop/dev-guide-get-data-from-single-table.md). +更多信息请参考 [查询数据](/develop/dev-guide-get-data-from-single-table.md)。 -### Update data +### 更新数据 ```golang db.Save(&Player{ID: "id", Coins: 100, Goods: 1}) ``` -For more information, refer to [Update data](/develop/dev-guide-update-data.md). +更多信息请参考 [更新数据](/develop/dev-guide-update-data.md)。 -### Delete data +### 删除数据 ```golang db.Delete(&Player{ID: "id"}) ``` -For more information, refer to [Delete data](/develop/dev-guide-delete-data.md). +更多信息请参考 [删除数据](/develop/dev-guide-delete-data.md)。 -## Next steps +## 后续步骤 -- Learn more usage of GORM from [the documentation of GORM](https://gorm.io/docs/index.html) and the [TiDB section in the documentation of GORM](https://gorm.io/docs/connecting_to_the_database.html#TiDB). -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Single table reading](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), and [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. +- 通过 [GORM 官方文档](https://gorm.io/docs/index.html) 以及 [GORM 文档中的 TiDB 章节](https://gorm.io/docs/connecting_to_the_database.html#TiDB) 学习更多 GORM 的用法。 +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节，学习 TiDB 应用开发最佳实践，例如 [插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md) 以及 [SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/)，并在通过考试后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +欢迎在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或[提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +欢迎在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或[提交支持工单](https://tidb.support.pingcap.com/)。 diff --git a/develop/dev-guide-sample-application-golang-sql-driver.md b/develop/dev-guide-sample-application-golang-sql-driver.md index 30e09365f3b94..4461ef8e9137f 100644 --- a/develop/dev-guide-sample-application-golang-sql-driver.md +++ b/develop/dev-guide-sample-application-golang-sql-driver.md @@ -1,95 +1,95 @@ --- -title: Connect to TiDB with Go-MySQL-Driver -summary: Learn how to connect to TiDB using Go-MySQL-Driver. This tutorial gives Golang sample code snippets that work with TiDB using Go-MySQL-Driver. +title: 使用 Go-MySQL-Driver 连接 TiDB +summary: 学习如何使用 Go-MySQL-Driver 连接 TiDB。本教程提供了适用于 TiDB 的 Golang 示例代码片段，演示如何使用 Go-MySQL-Driver 进行操作。 --- -# Connect to TiDB with Go-MySQL-Driver +# 使用 Go-MySQL-Driver 连接 TiDB -TiDB is a MySQL-compatible database, and [Go-MySQL-Driver](https://github.com/go-sql-driver/mysql) is a MySQL implementation for the [database/sql](https://pkg.go.dev/database/sql) interface. +TiDB 是兼容 MySQL 的数据库，[Go-MySQL-Driver](https://github.com/go-sql-driver/mysql) 是 [database/sql](https://pkg.go.dev/database/sql) 接口的 MySQL 实现。 -In this tutorial, you can learn how to use TiDB and Go-MySQL-Driver to accomplish the following tasks: +在本教程中，你可以学习如何使用 TiDB 和 Go-MySQL-Driver 完成以下任务： -- Set up your environment. -- Connect to your TiDB cluster using Go-MySQL-Driver. -- Build and run your application. Optionally, you can find [sample code snippets](#sample-code-snippets) for basic CRUD operations. +- 搭建你的开发环境。 +- 使用 Go-MySQL-Driver 连接到你的 TiDB 集群。 +- 构建并运行你的应用程序。你还可以在 [示例代码片段](#sample-code-snippets) 中找到基本的 CRUD 操作示例。 > **Note:** > -> This tutorial works with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed. +> 本教程适用于 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及自建 TiDB 集群。 -## Prerequisites +## 前置条件 -To complete this tutorial, you need: +完成本教程，你需要： -- [Go](https://go.dev/) **1.20** or higher. -- [Git](https://git-scm.com/downloads). -- A TiDB cluster. +- [Go](https://go.dev/) **1.20** 或更高版本。 +- [Git](https://git-scm.com/downloads)。 +- 一个 TiDB 集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](/production-deployment-using-tiup.md) 创建本地集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) 创建本地集群。 -## Run the sample app to connect to TiDB +## 运行示例应用连接 TiDB -This section demonstrates how to run the sample application code and connect to TiDB. +本节演示如何运行示例应用代码并连接到 TiDB。 -### Step 1: Clone the sample app repository +### 步骤 1：克隆示例应用仓库 -Run the following commands in your terminal window to clone the sample code repository: +在终端窗口中运行以下命令，克隆示例代码仓库： ```shell git clone https://github.com/tidb-samples/tidb-golang-sql-driver-quickstart.git cd tidb-golang-sql-driver-quickstart ``` -### Step 2: Configure connection information +### 步骤 2：配置连接信息 -Connect to your TiDB cluster depending on the TiDB deployment option you've selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称，进入集群概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确保连接对话框中的配置与你的操作环境一致。 - - **Connection Type** is set to `Public` - - **Branch** is set to `main` - - **Connect With** is set to `General` - - **Operating System** matches your environment. + - **Connection Type** 设置为 `Public` + - **Branch** 设置为 `main` + - **Connect With** 设置为 `General` + - **Operating System** 与你的环境一致 > **Tip:** > - > If your program is running in Windows Subsystem for Linux (WSL), switch to the corresponding Linux distribution. + > 如果你的程序运行在 Windows Subsystem for Linux (WSL) 中，请切换到对应的 Linux 发行版。 -4. Click **Generate Password** to create a random password. +4. 点击 **Generate Password** 生成随机密码。 > **Tip:** > - > If you have created a password before, you can either use the original password or click **Reset Password** to generate a new one. + > 如果你之前已经创建过密码，可以继续使用原密码，或者点击 **Reset Password** 生成新密码。 -5. Run the following command to copy `.env.example` and rename it to `.env`: +5. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -6. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +6. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例结果如下： ```dotenv TIDB_HOST='{host}' # e.g. gateway01.ap-northeast-1.prod.aws.tidbcloud.com @@ -100,32 +100,32 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele USE_SSL='true' ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog. + 请务必将 `{}` 占位符替换为连接对话框中获取的连接参数。 - {{{ .starter }}} requires a secure connection. Therefore, you need to set the value of `USE_SSL` to `true`. + TiDB Cloud Serverless 需要安全连接，因此你需要将 `USE_SSL` 设置为 `true`。 -7. Save the `.env` file. +7. 保存 `.env` 文件。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称，进入集群概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还未配置 IP 访问列表，请点击 **Configure IP Access List**，或参考 [配置 IP 访问列表](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 进行配置，以便首次连接。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息请参考 [连接到你的 TiDB Cloud Dedicated 集群](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Run the following command to copy `.env.example` and rename it to `.env`: +4. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -5. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +5. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例结果如下： ```dotenv TIDB_HOST='{host}' # e.g. tidb.xxxx.clusters.tidb-cloud.com @@ -136,20 +136,20 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele USE_SSL='false' ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog. + 请务必将 `{}` 占位符替换为连接对话框中获取的连接参数。 -6. Save the `.env` file. +6. 保存 `.env` 文件。
-1. Run the following command to copy `.env.example` and rename it to `.env`: +1. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -2. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +2. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例结果如下： ```dotenv TIDB_HOST='{host}' @@ -160,30 +160,30 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele USE_SSL='false' ``` - Be sure to replace the placeholders `{}` with the connection parameters, and set `USE_SSL` to `false`. If you are running TiDB locally, the default host address is `127.0.0.1`, and the password is empty. + 请务必将 `{}` 占位符替换为连接参数，并将 `USE_SSL` 设置为 `false`。如果你在本地运行 TiDB，默认主机地址为 `127.0.0.1`，密码为空。 -3. Save the `.env` file. +3. 保存 `.env` 文件。
-### Step 3: Run the code and check the result +### 步骤 3：运行代码并检查结果 -1. Execute the following command to run the sample code: +1. 执行以下命令运行示例代码： ```shell make ``` -2. Check the [Expected-Output.txt](https://github.com/tidb-samples/tidb-golang-sql-driver-quickstart/blob/main/Expected-Output.txt) to see if the output matches. +2. 检查 [Expected-Output.txt](https://github.com/tidb-samples/tidb-golang-sql-driver-quickstart/blob/main/Expected-Output.txt) 文件，确认输出是否一致。 -## Sample code snippets +## 示例代码片段 -You can refer to the following sample code snippets to complete your own application development. +你可以参考以下示例代码片段，完成你自己的应用开发。 -For complete sample code and how to run it, check out the [tidb-samples/tidb-golang-sql-driver-quickstart](https://github.com/tidb-samples/tidb-golang-sql-driver-quickstart) repository. +完整示例代码及运行方法请参考 [tidb-samples/tidb-golang-sql-driver-quickstart](https://github.com/tidb-samples/tidb-golang-sql-driver-quickstart) 仓库。 -### Connect to TiDB +### 连接 TiDB ```golang func openDB(driverName string, runnable func(db *sql.DB)) { @@ -199,9 +199,9 @@ func openDB(driverName string, runnable func(db *sql.DB)) { } ``` -When using this function, you need to replace `${tidb_host}`, `${tidb_port}`, `${tidb_user}`, `${tidb_password}`, and `${tidb_db_name}` with the actual values of your TiDB cluster. {{{ .starter }}} requires a secure connection. Therefore, you need to set the value of `${use_ssl}` to `true`. +使用该函数时，你需要将 `${tidb_host}`、`${tidb_port}`、`${tidb_user}`、`${tidb_password}` 和 `${tidb_db_name}` 替换为你 TiDB 集群的实际值。TiDB Cloud Serverless 和 TiDB Cloud Essential 需要安全连接，因此你需要将 `${use_ssl}` 设置为 `true`。 -### Insert data +### 插入数据 ```golang openDB("mysql", func(db *sql.DB) { @@ -214,9 +214,9 @@ openDB("mysql", func(db *sql.DB) { }) ``` -For more information, refer to [Insert data](/develop/dev-guide-insert-data.md). +更多信息请参考 [插入数据](/develop/dev-guide-insert-data.md)。 -### Query data +### 查询数据 ```golang openDB("mysql", func(db *sql.DB) { @@ -239,9 +239,9 @@ openDB("mysql", func(db *sql.DB) { }) ``` -For more information, refer to [Query data](/develop/dev-guide-get-data-from-single-table.md). +更多信息请参考 [查询数据](/develop/dev-guide-get-data-from-single-table.md)。 -### Update data +### 更新数据 ```golang openDB("mysql", func(db *sql.DB) { @@ -254,9 +254,9 @@ openDB("mysql", func(db *sql.DB) { }) ``` -For more information, refer to [Update data](/develop/dev-guide-update-data.md). +更多信息请参考 [更新数据](/develop/dev-guide-update-data.md)。 -### Delete data +### 删除数据 ```golang openDB("mysql", func(db *sql.DB) { @@ -269,39 +269,39 @@ openDB("mysql", func(db *sql.DB) { }) ``` -For more information, refer to [Delete data](/develop/dev-guide-delete-data.md). +更多信息请参考 [删除数据](/develop/dev-guide-delete-data.md)。 -## Useful notes +## 实用说明 -### Using driver or ORM framework? +### 使用驱动还是 ORM 框架？ -The Golang driver provides low-level access to the database, but it requires the developers to: +Golang 驱动提供了对数据库的底层访问，但这要求开发者： -- Manually establish and release database connections. -- Manually manage database transactions. -- Manually map data rows to data objects. +- 手动建立和释放数据库连接。 +- 手动管理数据库事务。 +- 手动将数据行映射为数据对象。 -Unless you need to write complex SQL statements, it is recommended to use [ORM](https://en.wikipedia.org/w/index.php?title=Object-relational_mapping) framework for development, such as [GORM](/develop/dev-guide-sample-application-golang-gorm.md). It can help you: +除非你需要编写复杂的 SQL 语句，否则推荐使用 [ORM](https://en.wikipedia.org/w/index.php?title=Object-relational_mapping) 框架进行开发，例如 [GORM](/develop/dev-guide-sample-application-golang-gorm.md)。它可以帮助你： -- Reduce [boilerplate code](https://en.wikipedia.org/wiki/Boilerplate_code) for managing connections and transactions. -- Manipulate data with data objects instead of a number of SQL statements. +- 减少管理连接和事务的 [样板代码](https://en.wikipedia.org/wiki/Boilerplate_code)。 +- 通过数据对象操作数据，而不是大量 SQL 语句。 -## Next steps +## 后续步骤 -- Learn more usage of Go-MySQL-Driver from [the documentation of Go-MySQL-Driver](https://github.com/go-sql-driver/mysql/blob/master/README.md). -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Single table reading](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), and [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. +- 通过 [Go-MySQL-Driver 文档](https://github.com/go-sql-driver/mysql/blob/master/README.md) 学习更多 Go-MySQL-Driver 的用法。 +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节学习 TiDB 应用开发最佳实践，例如 [插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md) 以及 [SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/) 学习，并在通过考试后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](https://tidb.support.pingcap.com/)。 diff --git a/develop/dev-guide-sample-application-java-hibernate.md b/develop/dev-guide-sample-application-java-hibernate.md index 89e1edd34b7b3..3e8dd5feca5c3 100644 --- a/develop/dev-guide-sample-application-java-hibernate.md +++ b/develop/dev-guide-sample-application-java-hibernate.md @@ -1,96 +1,96 @@ --- -title: Connect to TiDB with Hibernate -summary: Learn how to connect to TiDB using Hibernate. This tutorial gives Java sample code snippets that work with TiDB using Hibernate. +title: 使用 Hibernate 连接 TiDB +summary: 学习如何使用 Hibernate 连接 TiDB。本教程提供了可与 TiDB 搭配使用的 Java 示例代码片段。 --- -# Connect to TiDB with Hibernate +# 使用 Hibernate 连接 TiDB -TiDB is a MySQL-compatible database, and [Hibernate](https://hibernate.org/orm/) is a popular open-source Java ORM. Starting from version `6.0.0.Beta2`, Hibernate supports TiDB dialect, which fits TiDB features well. +TiDB 是一个兼容 MySQL 的数据库，[Hibernate](https://hibernate.org/orm/) 是一个流行的开源 Java ORM。从 `6.0.0.Beta2` 版本开始，Hibernate 支持 TiDB 方言，能够很好地适配 TiDB 的特性。 -In this tutorial, you can learn how to use TiDB and Hibernate to accomplish the following tasks: +在本教程中，你可以学习如何使用 TiDB 和 Hibernate 完成以下任务： -- Set up your environment. -- Connect to your TiDB cluster using Hibernate. -- Build and run your application. Optionally, you can find [sample code snippets](#sample-code-snippets) for basic CRUD operations. +- 搭建你的环境。 +- 使用 Hibernate 连接到你的 TiDB 集群。 +- 构建并运行你的应用程序。你还可以在 [示例代码片段](#sample-code-snippets) 中找到基本 CRUD 操作的示例代码。 > **Note:** > -> This tutorial works with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed. +> 本教程适用于 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及 TiDB 自建集群。 -## Prerequisites +## 前置条件 -To complete this tutorial, you need: +完成本教程，你需要： -- **Java Development Kit (JDK) 17** or higher. You can choose [OpenJDK](https://openjdk.org/) or [Oracle JDK](https://www.oracle.com/hk/java/technologies/downloads/) based on your business and personal requirements. -- [Maven](https://maven.apache.org/install.html) **3.8** or higher. -- [Git](https://git-scm.com/downloads). -- A TiDB cluster. +- **Java Development Kit (JDK) 17** 或更高版本。你可以根据业务和个人需求选择 [OpenJDK](https://openjdk.org/) 或 [Oracle JDK](https://www.oracle.com/hk/java/technologies/downloads/)。 +- [Maven](https://maven.apache.org/install.html) **3.8** 或更高版本。 +- [Git](https://git-scm.com/downloads)。 +- 一个 TiDB 集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](/production-deployment-using-tiup.md) 创建本地集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) 创建本地集群。 -## Run the sample app to connect to TiDB +## 运行示例应用连接 TiDB -This section demonstrates how to run the sample application code and connect to TiDB. +本节演示如何运行示例应用代码并连接到 TiDB。 -### Step 1: Clone the sample app repository +### 第 1 步：克隆示例应用仓库 -Run the following commands in your terminal window to clone the sample code repository: +在终端窗口中运行以下命令，克隆示例代码仓库： ```shell git clone https://github.com/tidb-samples/tidb-java-hibernate-quickstart.git cd tidb-java-hibernate-quickstart ``` -### Step 2: Configure connection information +### 第 2 步：配置连接信息 -Connect to your TiDB cluster depending on the TiDB deployment option you've selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，然后点击目标集群名称进入其概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确保连接对话框中的配置与你的操作环境一致。 - - **Connection Type** is set to `Public` - - **Branch** is set to `main` - - **Connect With** is set to `General` - - **Operating System** matches your environment. + - **Connection Type** 设置为 `Public` + - **Branch** 设置为 `main` + - **Connect With** 设置为 `General` + - **Operating System** 与你的环境一致 > **Tip:** > - > If your program is running in Windows Subsystem for Linux (WSL), switch to the corresponding Linux distribution. + > 如果你的程序运行在 Windows Subsystem for Linux (WSL) 中，请切换到对应的 Linux 发行版。 -4. Click **Generate Password** to create a random password. +4. 点击 **Generate Password** 生成一个随机密码。 > **Tip:** > - > If you have created a password before, you can either use the original password or click **Reset Password** to generate a new one. + > 如果你之前已经创建过密码，可以继续使用原密码，或者点击 **Reset Password** 生成新密码。 -5. Run the following command to copy `env.sh.example` and rename it to `env.sh`: +5. 运行以下命令，复制 `env.sh.example` 并重命名为 `env.sh`： ```shell cp env.sh.example env.sh ``` -6. Copy and paste the corresponding connection string into the `env.sh` file. The example result is as follows: +6. 将对应的连接字符串复制粘贴到 `env.sh` 文件中。示例结果如下： ```shell export TIDB_HOST='{host}' # e.g. gateway01.ap-northeast-1.prod.aws.tidbcloud.com @@ -101,32 +101,32 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele export USE_SSL='true' ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog. + 请务必将 `{}` 占位符替换为连接对话框中获得的连接参数。 - {{{ .starter }}} requires a secure connection. Therefore, you need to set the value of `USE_SSL` to `true`. + TiDB Cloud Serverless 需要安全连接，因此你需要将 `USE_SSL` 的值设置为 `true`。 -7. Save the `env.sh` file. +7. 保存 `env.sh` 文件。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，然后点击目标集群名称进入其概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还未配置 IP 访问列表，请点击 **Configure IP Access List**，或参考 [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 进行首次连接前的配置。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息请参考 [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Run the following command to copy `env.sh.example` and rename it to `env.sh`: +4. 运行以下命令，复制 `env.sh.example` 并重命名为 `env.sh`： ```shell cp env.sh.example env.sh ``` -5. Copy and paste the corresponding connection string into the `env.sh` file. The example result is as follows: +5. 将对应的连接字符串复制粘贴到 `env.sh` 文件中。示例结果如下： ```shell export TIDB_HOST='{host}' # e.g. tidb.xxxx.clusters.tidb-cloud.com @@ -137,20 +137,20 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele export USE_SSL='false' ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog. + 请务必将 `{}` 占位符替换为连接对话框中获得的连接参数。 -6. Save the `env.sh` file. +6. 保存 `env.sh` 文件。
-
+
-1. Run the following command to copy `env.sh.example` and rename it to `env.sh`: +1. 运行以下命令，复制 `env.sh.example` 并重命名为 `env.sh`： ```shell cp env.sh.example env.sh ``` -2. Copy and paste the corresponding connection string into the `env.sh` file. The example result is as follows: +2. 将对应的连接字符串复制粘贴到 `env.sh` 文件中。示例结果如下： ```shell export TIDB_HOST='{host}' @@ -161,32 +161,32 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele export USE_SSL='false' ``` - Be sure to replace the placeholders `{}` with the connection parameters, and set `USE_SSL` to `false`. If you are running TiDB locally, the default host address is `127.0.0.1`, and the password is empty. + 请务必将 `{}` 占位符替换为连接参数，并将 `USE_SSL` 设置为 `false`。如果你在本地运行 TiDB，默认主机地址为 `127.0.0.1`，密码为空。 -3. Save the `env.sh` file. +3. 保存 `env.sh` 文件。
-### Step 3: Run the code and check the result +### 第 3 步：运行代码并检查结果 -1. Execute the following command to run the sample code: +1. 执行以下命令运行示例代码： ```shell make ``` -2. Check the [Expected-Output.txt](https://github.com/tidb-samples/tidb-java-hibernate-quickstart/blob/main/Expected-Output.txt) to see if the output matches. +2. 检查 [Expected-Output.txt](https://github.com/tidb-samples/tidb-java-hibernate-quickstart/blob/main/Expected-Output.txt) 文件，确认输出是否一致。 -## Sample code snippets +## 示例代码片段 -You can refer to the following sample code snippets to complete your own application development. +你可以参考以下示例代码片段，完成你自己的应用开发。 -For complete sample code and how to run it, check out the [tidb-samples/tidb-java-hibernate-quickstart](https://github.com/tidb-samples/tidb-java-hibernate-quickstart) repository. +完整示例代码及运行方法请参考 [tidb-samples/tidb-java-hibernate-quickstart](https://github.com/tidb-samples/tidb-java-hibernate-quickstart) 仓库。 -### Connect to TiDB +### 连接 TiDB -Edit the Hibernate configuration file `hibernate.cfg.xml`: +编辑 Hibernate 配置文件 `hibernate.cfg.xml`： ```xml @@ -214,7 +214,7 @@ Edit the Hibernate configuration file `hibernate.cfg.xml`: ``` -Be sure to replace `${tidb_jdbc_url}`, `${tidb_user}`, and `${tidb_password}` with the actual values of your TiDB cluster. Then, define the following function: +请务必将 `${tidb_jdbc_url}`、`${tidb_user}` 和 `${tidb_password}` 替换为你 TiDB 集群的实际值。然后，定义如下函数： ```java public SessionFactory getSessionFactory() { @@ -225,9 +225,9 @@ public SessionFactory getSessionFactory() { } ``` -When using this function, you need to replace `${your_entity_class}` with your own data entity class. For multiple entity classes, you need to add a `.addAnnotatedClass(${your_entity_class})` statement for each. The preceding function is just one way to configure Hibernate. If you encounter any issues in the configuration or want to learn more about Hibernate, refer to the [Hibernate official documentation](https://hibernate.org/orm/documentation). +在使用该函数时，需要将 `${your_entity_class}` 替换为你自己的数据实体类。对于多个实体类，需要为每个实体类添加一条 `.addAnnotatedClass(${your_entity_class})` 语句。上述函数只是配置 Hibernate 的一种方式。如果你在配置过程中遇到问题，或想了解更多 Hibernate 相关内容，请参考 [Hibernate 官方文档](https://hibernate.org/orm/documentation)。 -### Insert or update data +### 插入或更新数据 ```java try (Session session = sessionFactory.openSession()) { @@ -235,9 +235,9 @@ try (Session session = sessionFactory.openSession()) { } ``` -For more information, refer to [Insert data](/develop/dev-guide-insert-data.md) and [Update data](/develop/dev-guide-update-data.md). +更多信息请参考 [插入数据](/develop/dev-guide-insert-data.md) 和 [更新数据](/develop/dev-guide-update-data.md)。 -### Query data +### 查询数据 ```java try (Session session = sessionFactory.openSession()) { @@ -246,9 +246,9 @@ try (Session session = sessionFactory.openSession()) { } ``` -For more information, refer to [Query data](/develop/dev-guide-get-data-from-single-table.md). +更多信息请参考 [查询数据](/develop/dev-guide-get-data-from-single-table.md)。 -### Delete data +### 删除数据 ```java try (Session session = sessionFactory.openSession()) { @@ -256,25 +256,25 @@ try (Session session = sessionFactory.openSession()) { } ``` -For more information, refer to [Delete data](/develop/dev-guide-delete-data.md). +更多信息请参考 [删除数据](/develop/dev-guide-delete-data.md)。 -## Next steps +## 后续步骤 -- Learn more usage of Hibernate from [the documentation of Hibernate](https://hibernate.org/orm/documentation). -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Single table reading](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), and [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. -- Learn through the course for Java developers: [Working with TiDB from Java](https://eng.edu.pingcap.com/catalog/info/id:212). +- 通过 [Hibernate 文档](https://hibernate.org/orm/documentation) 学习更多 Hibernate 的用法。 +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节学习 TiDB 应用开发最佳实践，例如 [插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md) 以及 [SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/) 学习，并在通过考试后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 +- 通过 Java 开发者课程学习：[Working with TiDB from Java](https://eng.edu.pingcap.com/catalog/info/id:212)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](https://tidb.support.pingcap.com/)。 diff --git a/develop/dev-guide-sample-application-java-jdbc.md b/develop/dev-guide-sample-application-java-jdbc.md index 0105c1983ce4a..c5350e340cc67 100644 --- a/develop/dev-guide-sample-application-java-jdbc.md +++ b/develop/dev-guide-sample-application-java-jdbc.md @@ -1,24 +1,24 @@ --- -title: Connect to TiDB with JDBC -summary: Learn how to connect to TiDB using JDBC. This tutorial gives Java sample code snippets that work with TiDB using JDBC. +title: 使用 JDBC 连接 TiDB +summary: 学习如何使用 JDBC 连接 TiDB。本教程提供了可用于 TiDB 的 Java 示例代码片段。 --- -# Connect to TiDB with JDBC +# 使用 JDBC 连接 TiDB -TiDB is a MySQL-compatible database, and JDBC (Java Database Connectivity) is the data access API for Java. [MySQL Connector/J](https://dev.mysql.com/downloads/connector/j/) is MySQL's implementation of JDBC. +TiDB 是一个兼容 MySQL 的数据库，JDBC（Java Database Connectivity）是 Java 的数据访问 API。[MySQL Connector/J](https://dev.mysql.com/downloads/connector/j/) 是 MySQL 的 JDBC 实现。 -In this tutorial, you can learn how to use TiDB and JDBC to accomplish the following tasks: +在本教程中，你可以学习如何使用 TiDB 和 JDBC 完成以下任务： -- Set up your environment. -- Connect to your TiDB cluster using JDBC. -- Build and run your application. Optionally, you can find [sample code snippets](#sample-code-snippets) for basic CRUD operations. +- 搭建你的环境。 +- 使用 JDBC 连接到你的 TiDB 集群。 +- 构建并运行你的应用程序。你还可以在 [示例代码片段](#sample-code-snippets) 中找到基本 CRUD 操作的示例代码。 > **Note:** > -> - This tutorial works with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed. -> - Starting from TiDB v7.4, if `connectionCollation` is not configured, and `characterEncoding` is either not configured or set to `UTF-8` in the JDBC URL, the collation used in a JDBC connection depends on the JDBC driver version. For more information, see [Collation used in JDBC connections](/faq/sql-faq.md#collation-used-in-jdbc-connections). +> - 本教程适用于 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及 TiDB 自建集群。 +> - 从 TiDB v7.4 开始，如果在 JDBC URL 中未配置 `connectionCollation`，且 `characterEncoding` 未配置或设置为 `UTF-8`，则 JDBC 连接中使用的排序规则取决于 JDBC 驱动版本。更多信息请参见 [JDBC 连接中使用的排序规则](/faq/sql-faq.md#collation-used-in-jdbc-connections)。 @@ -26,89 +26,89 @@ In this tutorial, you can learn how to use TiDB and JDBC to accomplish the follo > **Note:** > -> - This tutorial works with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed. -> - Starting from TiDB v7.4, if `connectionCollation` is not configured, and `characterEncoding` is either not configured or set to `UTF-8` in the JDBC URL, the collation used in a JDBC connection depends on the JDBC driver version. For more information, see [Collation used in JDBC connections](https://docs.pingcap.com/tidb/stable/sql-faq#collation-used-in-jdbc-connections). +> - 本教程适用于 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及 TiDB 自建集群。 +> - 从 TiDB v7.4 开始，如果在 JDBC URL 中未配置 `connectionCollation`，且 `characterEncoding` 未配置或设置为 `UTF-8`，则 JDBC 连接中使用的排序规则取决于 JDBC 驱动版本。更多信息请参见 [JDBC 连接中使用的排序规则](https://docs.pingcap.com/tidb/stable/sql-faq#collation-used-in-jdbc-connections)。 -## Prerequisites +## 前置条件 -To complete this tutorial, you need: +完成本教程，你需要： -- **Java Development Kit (JDK) 17** or higher. You can choose [OpenJDK](https://openjdk.org/) or [Oracle JDK](https://www.oracle.com/hk/java/technologies/downloads/) based on your business and personal requirements. -- [Maven](https://maven.apache.org/install.html) **3.8** or higher. -- [Git](https://git-scm.com/downloads). -- A TiDB cluster. +- **Java Development Kit (JDK) 17** 或更高版本。你可以根据业务和个人需求选择 [OpenJDK](https://openjdk.org/) 或 [Oracle JDK](https://www.oracle.com/hk/java/technologies/downloads/)。 +- [Maven](https://maven.apache.org/install.html) **3.8** 或更高版本。 +- [Git](https://git-scm.com/downloads)。 +- 一个 TiDB 集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](/production-deployment-using-tiup.md) 创建本地集群。 > **Note:** > -> For security considerations, it is recommended that you use `VERIFY_IDENTITY` to establish TLS connections to TiDB clusters when connecting over the internet. Both {{{ .starter }}} and TiDB Cloud Dedicated use Subject Alternative Name (SAN) certificates, which require MySQL Connector/J version to be greater than or equal to [8.0.22](https://dev.mysql.com/doc/relnotes/connector-j/en/news-8-0-22.html). +> 出于安全考虑，建议你在通过互联网连接 TiDB 集群时，使用 `VERIFY_IDENTITY` 建立 TLS 连接。TiDB Cloud Serverless、TiDB Cloud Essential 和 TiDB Cloud Dedicated 使用 Subject Alternative Name (SAN) 证书，要求 MySQL Connector/J 版本大于等于 [8.0.22](https://dev.mysql.com/doc/relnotes/connector-j/en/news-8-0-22.html)。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) 创建本地集群。 -## Run the sample app to connect to TiDB +## 运行示例应用连接 TiDB -This section demonstrates how to run the sample application code and connect to TiDB. +本节演示如何运行示例应用代码并连接到 TiDB。 -### Step 1: Clone the sample app repository +### 步骤 1：克隆示例应用仓库 -Run the following commands in your terminal window to clone the sample code repository: +在终端窗口中运行以下命令，克隆示例代码仓库： ```shell git clone https://github.com/tidb-samples/tidb-java-jdbc-quickstart.git cd tidb-java-jdbc-quickstart ``` -### Step 2: Configure connection information +### 步骤 2：配置连接信息 -Connect to your TiDB cluster depending on the TiDB deployment option you've selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确保连接对话框中的配置与你的操作环境一致。 - - **Connection Type** is set to `Public` - - **Branch** is set to `main` - - **Connect With** is set to `General` - - **Operating System** matches your environment. + - **Connection Type** 设置为 `Public` + - **Branch** 设置为 `main` + - **Connect With** 设置为 `General` + - **Operating System** 与你的环境一致 > **Tip:** > - > If your program is running in Windows Subsystem for Linux (WSL), switch to the corresponding Linux distribution. + > 如果你的程序运行在 Windows Subsystem for Linux (WSL) 中，请切换到对应的 Linux 发行版。 -4. Click **Generate Password** to create a random password. +4. 点击 **Generate Password** 生成随机密码。 > **Tip:** > - > If you have created a password before, you can either use the original password or click **Reset Password** to generate a new one. + > 如果你之前已创建过密码，可以继续使用原密码，或点击 **Reset Password** 生成新密码。 -5. Run the following command to copy `env.sh.example` and rename it to `env.sh`: +5. 运行以下命令，复制 `env.sh.example` 并重命名为 `env.sh`： ```shell cp env.sh.example env.sh ``` -6. Copy and paste the corresponding connection string into the `env.sh` file. The example result is as follows: +6. 将对应的连接字符串复制粘贴到 `env.sh` 文件中。示例结果如下： ```shell export TIDB_HOST='{host}' # e.g. gateway01.ap-northeast-1.prod.aws.tidbcloud.com @@ -119,32 +119,32 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele export USE_SSL='true' ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog. + 请确保将 `{}` 占位符替换为连接对话框中获取的连接参数。 - {{{ .starter }}} requires a secure connection. Therefore, you need to set the value of `USE_SSL` to `true`. + TiDB Cloud Serverless 需要安全连接，因此你需要将 `USE_SSL` 的值设置为 `true`。 -7. Save the `env.sh` file. +7. 保存 `env.sh` 文件。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还未配置 IP 访问列表，请点击 **Configure IP Access List**，或参考 [配置 IP 访问列表](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 进行首次连接前的配置。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息请参见 [连接到你的 TiDB Cloud Dedicated 集群](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Run the following command to copy `env.sh.example` and rename it to `env.sh`: +4. 运行以下命令，复制 `env.sh.example` 并重命名为 `env.sh`： ```shell cp env.sh.example env.sh ``` -5. Copy and paste the corresponding connection string into the `env.sh` file. The example result is as follows: +5. 将对应的连接字符串复制粘贴到 `env.sh` 文件中。示例结果如下： ```shell export TIDB_HOST='{host}' # e.g. tidb.xxxx.clusters.tidb-cloud.com @@ -155,20 +155,20 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele export USE_SSL='false' ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog. + 请确保将 `{}` 占位符替换为连接对话框中获取的连接参数。 -6. Save the `env.sh` file. +6. 保存 `env.sh` 文件。
-
+
-1. Run the following command to copy `env.sh.example` and rename it to `env.sh`: +1. 运行以下命令，复制 `env.sh.example` 并重命名为 `env.sh`： ```shell cp env.sh.example env.sh ``` -2. Copy and paste the corresponding connection string into the `env.sh` file. The example result is as follows: +2. 将对应的连接字符串复制粘贴到 `env.sh` 文件中。示例结果如下： ```shell export TIDB_HOST='{host}' @@ -179,30 +179,30 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele export USE_SSL='false' ``` - Be sure to replace the placeholders `{}` with the connection parameters, and set `USE_SSL` to `false`. If you are running TiDB locally, the default host address is `127.0.0.1`, and the password is empty. + 请确保将 `{}` 占位符替换为连接参数，并将 `USE_SSL` 设置为 `false`。如果你在本地运行 TiDB，默认主机地址为 `127.0.0.1`，密码为空。 -3. Save the `env.sh` file. +3. 保存 `env.sh` 文件。
-### Step 3: Run the code and check the result +### 步骤 3：运行代码并检查结果 -1. Execute the following command to run the sample code: +1. 执行以下命令运行示例代码： ```shell make ``` -2. Check the [Expected-Output.txt](https://github.com/tidb-samples/tidb-java-jdbc-quickstart/blob/main/Expected-Output.txt) to see if the output matches. +2. 检查 [Expected-Output.txt](https://github.com/tidb-samples/tidb-java-jdbc-quickstart/blob/main/Expected-Output.txt) 以确认输出是否一致。 -## Sample code snippets +## 示例代码片段 -You can refer to the following sample code snippets to complete your own application development. +你可以参考以下示例代码片段，完成你自己的应用开发。 -For complete sample code and how to run it, check out the [tidb-samples/tidb-java-jdbc-quickstart](https://github.com/tidb-samples/tidb-java-jdbc-quickstart) repository. +完整示例代码及运行方法请参考 [tidb-samples/tidb-java-jdbc-quickstart](https://github.com/tidb-samples/tidb-java-jdbc-quickstart) 仓库。 -### Connect to TiDB +### 连接 TiDB ```java public MysqlDataSource getMysqlDataSource() throws SQLException { @@ -222,9 +222,9 @@ public MysqlDataSource getMysqlDataSource() throws SQLException { } ``` -When using this function, you need to replace `${tidb_host}`, `${tidb_port}`, `${tidb_user}`, `${tidb_password}`, and `${tidb_db_name}` with the actual values of your TiDB cluster. +使用该函数时，你需要将 `${tidb_host}`、`${tidb_port}`、`${tidb_user}`、`${tidb_password}` 和 `${tidb_db_name}` 替换为你 TiDB 集群的实际值。 -### Insert data +### 插入数据 ```java public void createPlayer(PlayerBean player) throws SQLException { @@ -240,9 +240,9 @@ public void createPlayer(PlayerBean player) throws SQLException { } ``` -For more information, refer to [Insert data](/develop/dev-guide-insert-data.md). +更多信息请参考 [插入数据](/develop/dev-guide-insert-data.md)。 -### Query data +### 查询数据 ```java public void getPlayer(String id) throws SQLException { @@ -261,9 +261,9 @@ public void getPlayer(String id) throws SQLException { } ``` -For more information, refer to [Query data](/develop/dev-guide-get-data-from-single-table.md). +更多信息请参考 [查询数据](/develop/dev-guide-get-data-from-single-table.md)。 -### Update data +### 更新数据 ```java public void updatePlayer(String id, int amount, int price) throws SQLException { @@ -278,9 +278,9 @@ public void updatePlayer(String id, int amount, int price) throws SQLException { } ``` -For more information, refer to [Update data](/develop/dev-guide-update-data.md). +更多信息请参考 [更新数据](/develop/dev-guide-update-data.md)。 -### Delete data +### 删除数据 ```java public void deletePlayer(String id) throws SQLException { @@ -293,40 +293,40 @@ public void deletePlayer(String id) throws SQLException { } ``` -For more information, refer to [Delete data](/develop/dev-guide-delete-data.md). +更多信息请参考 [删除数据](/develop/dev-guide-delete-data.md)。 -## Useful notes +## 实用说明 -### Using driver or ORM framework? +### 使用驱动还是 ORM 框架？ -The Java driver provides low-level access to the database, but it requires the developers to: +Java 驱动提供了对数据库的底层访问，但这要求开发者： -- Manually establish and release database connections. -- Manually manage database transactions. -- Manually map data rows to data objects. +- 手动建立和释放数据库连接。 +- 手动管理数据库事务。 +- 手动将数据行映射为数据对象。 -Unless you need to write complex SQL statements, it is recommended to use [ORM](https://en.wikipedia.org/w/index.php?title=Object-relational_mapping) framework for development, such as [Hibernate](/develop/dev-guide-sample-application-java-hibernate.md), [MyBatis](/develop/dev-guide-sample-application-java-mybatis.md), or [Spring Data JPA](/develop/dev-guide-sample-application-java-spring-boot.md). It can help you: +除非你需要编写复杂的 SQL 语句，否则推荐使用 [ORM](https://en.wikipedia.org/w/index.php?title=Object-relational_mapping) 框架进行开发，例如 [Hibernate](/develop/dev-guide-sample-application-java-hibernate.md)、[MyBatis](/develop/dev-guide-sample-application-java-mybatis.md) 或 [Spring Data JPA](/develop/dev-guide-sample-application-java-spring-boot.md)。这样可以帮助你： -- Reduce [boilerplate code](https://en.wikipedia.org/wiki/Boilerplate_code) for managing connections and transactions. -- Manipulate data with data objects instead of a number of SQL statements. +- 减少用于管理连接和事务的 [样板代码](https://en.wikipedia.org/wiki/Boilerplate_code)。 +- 通过数据对象操作数据，而不是大量 SQL 语句。 -## Next steps +## 后续步骤 -- Learn more usage of MySQL Connector/J from [the documentation of MySQL Connector/J](https://dev.mysql.com/doc/connector-j/en/). -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Single table reading](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), and [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. -- Learn through the course for Java developers: [Working with TiDB from Java](https://eng.edu.pingcap.com/catalog/info/id:212). +- 通过 [MySQL Connector/J 文档](https://dev.mysql.com/doc/connector-j/en/) 了解更多 MySQL Connector/J 的用法。 +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节学习 TiDB 应用开发最佳实践，例如 [插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md) 以及 [SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/) 学习，并在通过考试后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 +- 通过 Java 开发者课程学习：[Working with TiDB from Java](https://eng.edu.pingcap.com/catalog/info/id:212)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +欢迎在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +欢迎在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](https://tidb.support.pingcap.com/)。 diff --git a/develop/dev-guide-sample-application-java-mybatis.md b/develop/dev-guide-sample-application-java-mybatis.md index 297bbcd000048..3d300af3e8531 100644 --- a/develop/dev-guide-sample-application-java-mybatis.md +++ b/develop/dev-guide-sample-application-java-mybatis.md @@ -1,96 +1,96 @@ --- -title: Connect to TiDB with MyBatis -summary: Learn how to connect to TiDB using MyBatis. This tutorial gives Java sample code snippets that work with TiDB using MyBatis. +title: 使用 MyBatis 连接 TiDB +summary: 学习如何使用 MyBatis 连接 TiDB。本教程提供了可与 TiDB 搭配使用的 Java 示例代码片段。 --- -# Connect to TiDB with MyBatis +# 使用 MyBatis 连接 TiDB -TiDB is a MySQL-compatible database, and [MyBatis](https://mybatis.org/mybatis-3/index.html) is a popular open-source Java ORM. +TiDB 是一个兼容 MySQL 的数据库，[MyBatis](https://mybatis.org/mybatis-3/index.html) 是一个流行的开源 Java ORM 框架。 -In this tutorial, you can learn how to use TiDB and MyBatis to accomplish the following tasks: +在本教程中，你可以学习如何使用 TiDB 和 MyBatis 完成以下任务： -- Set up your environment. -- Connect to your TiDB cluster using MyBatis. -- Build and run your application. Optionally, you can find [sample code snippets](#sample-code-snippets) for basic CRUD operations. +- 搭建你的开发环境。 +- 使用 MyBatis 连接到你的 TiDB 集群。 +- 构建并运行你的应用程序。你还可以在 [示例代码片段](#sample-code-snippets) 中找到基本的 CRUD 操作示例。 -> **Note:** +> **注意：** > -> This tutorial works with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed. +> 本教程适用于 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及自建 TiDB 集群。 -## Prerequisites +## 前置条件 -To complete this tutorial, you need: +完成本教程，你需要： -- **Java Development Kit (JDK) 17** or higher. You can choose [OpenJDK](https://openjdk.org/) or [Oracle JDK](https://www.oracle.com/hk/java/technologies/downloads/) based on your business and personal requirements. -- [Maven](https://maven.apache.org/install.html) **3.8** or higher. -- [Git](https://git-scm.com/downloads). -- A TiDB cluster. +- **Java Development Kit (JDK) 17** 或更高版本。你可以根据业务和个人需求选择 [OpenJDK](https://openjdk.org/) 或 [Oracle JDK](https://www.oracle.com/hk/java/technologies/downloads/)。 +- [Maven](https://maven.apache.org/install.html) **3.8** 或更高版本。 +- [Git](https://git-scm.com/downloads)。 +- 一个 TiDB 集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster) 或[部署生产环境 TiDB 集群](/production-deployment-using-tiup.md) 创建本地集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考[部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster) 或[部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) 创建本地集群。 -## Run the sample app to connect to TiDB +## 运行示例应用连接 TiDB -This section demonstrates how to run the sample application code and connect to TiDB. +本节演示如何运行示例应用代码并连接到 TiDB。 -### Step 1: Clone the sample app repository +### 步骤 1：克隆示例应用仓库 -Run the following commands in your terminal window to clone the sample code repository: +在终端窗口中运行以下命令，克隆示例代码仓库： ```shell git clone https://github.com/tidb-samples/tidb-java-mybatis-quickstart.git cd tidb-java-mybatis-quickstart ``` -### Step 2: Configure connection information +### 步骤 2：配置连接信息 -Connect to your TiDB cluster depending on the TiDB deployment option you've selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确保连接对话框中的配置与你的操作环境一致。 - - **Connection Type** is set to `Public` - - **Branch** is set to `main` - - **Connect With** is set to `General` - - **Operating System** matches your environment. + - **Connection Type** 设置为 `Public` + - **Branch** 设置为 `main` + - **Connect With** 设置为 `General` + - **Operating System** 与你的环境一致 - > **Tip:** + > **提示：** > - > If your program is running in Windows Subsystem for Linux (WSL), switch to the corresponding Linux distribution. + > 如果你的程序运行在 Windows Subsystem for Linux (WSL) 中，请切换到对应的 Linux 发行版。 -4. Click **Generate Password** to create a random password. +4. 点击 **Generate Password** 生成一个随机密码。 - > **Tip:** + > **提示：** > - > If you have created a password before, you can either use the original password or click **Reset Password** to generate a new one. + > 如果你之前已经创建过密码，可以继续使用原密码，或点击 **Reset Password** 生成新密码。 -5. Run the following command to copy `env.sh.example` and rename it to `env.sh`: +5. 运行以下命令，复制 `env.sh.example` 并重命名为 `env.sh`： ```shell cp env.sh.example env.sh ``` -6. Copy and paste the corresponding connection string into the `env.sh` file. The example result is as follows: +6. 将对应的连接字符串复制粘贴到 `env.sh` 文件中。示例结果如下： ```shell export TIDB_HOST='{host}' # e.g. gateway01.ap-northeast-1.prod.aws.tidbcloud.com @@ -101,32 +101,32 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele export USE_SSL='true' ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog. + 请务必将 `{}` 占位符替换为连接对话框中获得的连接参数。 - {{{ .starter }}} requires a secure connection. Therefore, you need to set the value of `USE_SSL` to `true`. + TiDB Cloud Serverless 需要安全连接，因此你需要将 `USE_SSL` 的值设置为 `true`。 -7. Save the `env.sh` file. +7. 保存 `env.sh` 文件。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还未配置 IP 访问列表，请点击 **Configure IP Access List**，或参考 [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 进行首次连接前的配置。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息请参考 [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Run the following command to copy `env.sh.example` and rename it to `env.sh`: +4. 运行以下命令，复制 `env.sh.example` 并重命名为 `env.sh`： ```shell cp env.sh.example env.sh ``` -5. Copy and paste the corresponding connection string into the `env.sh` file. The example result is as follows: +5. 将对应的连接字符串复制粘贴到 `env.sh` 文件中。示例结果如下： ```shell export TIDB_HOST='{host}' # e.g. tidb.xxxx.clusters.tidb-cloud.com @@ -137,20 +137,20 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele export USE_SSL='false' ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog. + 请务必将 `{}` 占位符替换为连接对话框中获得的连接参数。 -6. Save the `env.sh` file. +6. 保存 `env.sh` 文件。
-
+
-1. Run the following command to copy `env.sh.example` and rename it to `env.sh`: +1. 运行以下命令，复制 `env.sh.example` 并重命名为 `env.sh`： ```shell cp env.sh.example env.sh ``` -2. Copy and paste the corresponding connection string into the `env.sh` file. The example result is as follows: +2. 将对应的连接字符串复制粘贴到 `env.sh` 文件中。示例结果如下： ```shell export TIDB_HOST='{host}' @@ -161,32 +161,32 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele export USE_SSL='false' ``` - Be sure to replace the placeholders `{}` with the connection parameters, and set `USE_SSL` to `false`. If you are running TiDB locally, the default host address is `127.0.0.1`, and the password is empty. + 请务必将 `{}` 占位符替换为连接参数，并将 `USE_SSL` 设置为 `false`。如果你在本地运行 TiDB，默认主机地址为 `127.0.0.1`，密码为空。 -3. Save the `env.sh` file. +3. 保存 `env.sh` 文件。
-### Step 3: Run the code and check the result +### 步骤 3：运行代码并检查结果 -1. Execute the following command to run the sample code: +1. 执行以下命令运行示例代码： ```shell make ``` -2. Check the [Expected-Output.txt](https://github.com/tidb-samples/tidb-java-mybatis-quickstart/blob/main/Expected-Output.txt) to see if the output matches. +2. 检查 [Expected-Output.txt](https://github.com/tidb-samples/tidb-java-mybatis-quickstart/blob/main/Expected-Output.txt) 文件，确认输出是否一致。 -## Sample code snippets +## 示例代码片段 -You can refer to the following sample code snippets to complete your own application development. +你可以参考以下示例代码片段，完成你自己的应用开发。 -For complete sample code and how to run it, check out the [tidb-samples/tidb-java-mybatis-quickstart](https://github.com/tidb-samples/tidb-java-mybatis-quickstart) repository. +完整示例代码及运行方法请参考 [tidb-samples/tidb-java-mybatis-quickstart](https://github.com/tidb-samples/tidb-java-mybatis-quickstart) 仓库。 -### Connect to TiDB +### 连接 TiDB -Edit the MyBatis configuration file `mybatis-config.xml`: +编辑 MyBatis 配置文件 `mybatis-config.xml`： ```xml @@ -220,7 +220,7 @@ Edit the MyBatis configuration file `mybatis-config.xml`: ``` -Be sure to replace `${tidb_jdbc_url}`, `${tidb_user}`, and `${tidb_password}` with the actual values of your TiDB cluster. Also, replace `${mapper_location}` with the path of your mapper XML configuration file. For multiple mapper XML configuration files, you need to add a `` tag for each. Then, define the following function: +请务必将 `${tidb_jdbc_url}`、`${tidb_user}` 和 `${tidb_password}` 替换为你 TiDB 集群的实际值。同时，将 `${mapper_location}` 替换为你的 mapper XML 配置文件路径。如果有多个 mapper XML 配置文件，需要为每个文件添加一个 `` 标签。然后，定义如下函数： ```java public SqlSessionFactory getSessionFactory() { @@ -229,9 +229,9 @@ public SqlSessionFactory getSessionFactory() { } ``` -### Insert data +### 插入数据 -Add a node in the mapper XML and add a function with the same name in the interface class configured in the `mapper.namespace` attribute of the XML configuration file: +在 mapper XML 中添加一个节点，并在 XML 配置文件的 `mapper.namespace` 属性对应的接口类中添加同名函数： ```xml @@ -244,11 +244,11 @@ Add a node in the mapper XML and add a function with the same name in the interf ``` -For more information, refer to [Insert data](/develop/dev-guide-insert-data.md). +更多信息请参考 [插入数据](/develop/dev-guide-insert-data.md)。 -### Query data +### 查询数据 -Add a node in the mapper XML and add a function with the same name in the interface class configured in the `mapper.namespace` attribute of the XML configuration file. Specifically, if you use `resultMap` as the return type for MyBatis query functions, make sure that the `` node is configured correctly. +在 mapper XML 中添加一个节点，并在 XML 配置文件的 `mapper.namespace` 属性对应的接口类中添加同名函数。特别地，如果你使用 `resultMap` 作为 MyBatis 查询函数的返回类型，请确保 `` 节点配置正确。 ```xml @@ -270,11 +270,11 @@ Add a node in the mapper XML and add a function with the same name in the interf ``` -For more information, refer to [Query data](/develop/dev-guide-get-data-from-single-table.md). +更多信息请参考 [查询数据](/develop/dev-guide-get-data-from-single-table.md)。 -### Update data +### 更新数据 -Add a node in the mapper XML and add a function with the same name in the interface class configured in the `mapper.namespace` attribute of the XML configuration file: +在 mapper XML 中添加一个节点，并在 XML 配置文件的 `mapper.namespace` 属性对应的接口类中添加同名函数： ```xml @@ -289,11 +289,11 @@ Add a node in the mapper XML and add a function with the same name in the interf ``` -For more information, refer to [Update data](/develop/dev-guide-update-data.md). +更多信息请参考 [更新数据](/develop/dev-guide-update-data.md)。 -### Delete data +### 删除数据 -Add a node in the mapper XML and add a function with the same name in the interface class configured in the `mapper.namespace` attribute of the XML configuration file: +在 mapper XML 中添加一个节点，并在 XML 配置文件的 `mapper.namespace` 属性对应的接口类中添加同名函数： ```xml @@ -306,25 +306,25 @@ Add a node in the mapper XML and add a function with the same name in the interf ``` -For more information, refer to [Delete data](/develop/dev-guide-delete-data.md). +更多信息请参考 [删除数据](/develop/dev-guide-delete-data.md)。 -## Next steps +## 后续步骤 -- Learn more usage of MyBatis from [the documentation of MyBatis](http://www.mybatis.org/mybatis-3/). -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Single table reading](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), and [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. -- Learn through the course for Java developers: [Working with TiDB from Java](https://eng.edu.pingcap.com/catalog/info/id:212). +- 通过 [MyBatis 官方文档](http://www.mybatis.org/mybatis-3/) 学习更多 MyBatis 的用法。 +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节学习 TiDB 应用开发最佳实践，例如 [插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md) 以及 [SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/) 学习，并在通过考试后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 +- 通过 Java 开发者课程学习：[Working with TiDB from Java](https://eng.edu.pingcap.com/catalog/info/id:212)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或[提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或[提交支持工单](https://tidb.support.pingcap.com/)。 diff --git a/develop/dev-guide-sample-application-java-spring-boot.md b/develop/dev-guide-sample-application-java-spring-boot.md index 60166ce6a56f2..b989be239b5a1 100644 --- a/develop/dev-guide-sample-application-java-spring-boot.md +++ b/develop/dev-guide-sample-application-java-spring-boot.md @@ -1,96 +1,96 @@ --- -title: Connect to TiDB with Spring Boot -summary: Learn how to connect to TiDB using Spring Boot. This tutorial gives Java sample code snippets that work with TiDB using Spring Boot. +title: 使用 Spring Boot 连接 TiDB +summary: 学习如何使用 Spring Boot 连接 TiDB。本教程提供了可与 TiDB 协同工作的 Java 示例代码片段，基于 Spring Boot 实现。 --- -# Connect to TiDB with Spring Boot +# 使用 Spring Boot 连接 TiDB -TiDB is a MySQL-compatible database, and [Spring](https://spring.io/) is a popular open-source container framework for Java. This document uses [Spring Boot](https://spring.io/projects/spring-boot) as the way to use Spring. +TiDB 是一个兼容 MySQL 的数据库，[Spring](https://spring.io/) 是 Java 领域流行的开源容器框架。本文档以 [Spring Boot](https://spring.io/projects/spring-boot) 作为使用 Spring 的方式进行讲解。 -In this tutorial, you can learn how to use TiDB along with [Spring Data JPA](https://spring.io/projects/spring-data-jpa) and [Hibernate](https://hibernate.org/orm/) as the JPA provider to accomplish the following tasks: +在本教程中，你将学习如何结合 TiDB、[Spring Data JPA](https://spring.io/projects/spring-data-jpa) 以及作为 JPA 提供者的 [Hibernate](https://hibernate.org/orm/)，完成以下任务： -- Set up your environment. -- Connect to your TiDB cluster using Hibernate and Spring Data JPA. -- Build and run your application. Optionally, you can find [sample code snippets](#sample-code-snippets) for basic CRUD operations. +- 搭建开发环境 +- 使用 Hibernate 和 Spring Data JPA 连接 TiDB 集群 +- 构建并运行应用程序。你还可以在 [示例代码片段](#sample-code-snippets) 中找到基本的 CRUD 操作示例。 > **Note:** > -> This tutorial works with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed. +> 本教程适用于 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及 TiDB 自建集群。 -## Prerequisites +## 前置条件 -To complete this tutorial, you need: +完成本教程，你需要： -- **Java Development Kit (JDK) 17** or higher. You can choose [OpenJDK](https://openjdk.org/) or [Oracle JDK](https://www.oracle.com/hk/java/technologies/downloads/) based on your business and personal requirements. -- [Maven](https://maven.apache.org/install.html) **3.8** or higher. -- [Git](https://git-scm.com/downloads). -- A TiDB cluster. +- **Java Development Kit (JDK) 17** 或更高版本。你可以根据业务和个人需求选择 [OpenJDK](https://openjdk.org/) 或 [Oracle JDK](https://www.oracle.com/hk/java/technologies/downloads/)。 +- [Maven](https://maven.apache.org/install.html) **3.8** 或更高版本。 +- [Git](https://git-scm.com/downloads)。 +- 一个 TiDB 集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](/production-deployment-using-tiup.md) 创建本地集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) 创建本地集群。 -## Run the sample app to connect to TiDB +## 运行示例应用并连接 TiDB -This section demonstrates how to run the sample application code and connect to TiDB. +本节演示如何运行示例应用代码并连接 TiDB。 -### Step 1: Clone the sample app repository +### 第 1 步：克隆示例应用仓库 -Run the following commands in your terminal window to clone the sample code repository: +在终端窗口中运行以下命令，克隆示例代码仓库： ```shell git clone https://github.com/tidb-samples/tidb-java-springboot-jpa-quickstart.git cd tidb-java-springboot-jpa-quickstart ``` -### Step 2: Configure connection information +### 第 2 步：配置连接信息 -Connect to your TiDB cluster depending on the TiDB deployment option you've selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称，进入集群概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确保连接对话框中的配置与你的操作环境一致。 - - **Connection Type** is set to `Public` - - **Branch** is set to `main` - - **Connect With** is set to `General` - - **Operating System** matches your environment. + - **Connection Type** 设置为 `Public` + - **Branch** 设置为 `main` + - **Connect With** 设置为 `General` + - **Operating System** 与你的环境一致 > **Tip:** > - > If your program is running in Windows Subsystem for Linux (WSL), switch to the corresponding Linux distribution. + > 如果你的程序运行在 Windows Subsystem for Linux (WSL) 中，请切换到对应的 Linux 发行版。 -4. Click **Generate Password** to create a random password. +4. 点击 **Generate Password** 生成随机密码。 > **Tip:** > - > If you have created a password before, you can either use the original password or click **Reset Password** to generate a new one. + > 如果你之前已经创建过密码，可以继续使用原有密码，或点击 **Reset Password** 生成新密码。 -5. Run the following command to copy `env.sh.example` and rename it to `env.sh`: +5. 运行以下命令，将 `env.sh.example` 复制并重命名为 `env.sh`： ```shell cp env.sh.example env.sh ``` -6. Copy and paste the corresponding connection string into the `env.sh` file. The example result is as follows: +6. 将对应的连接字符串复制粘贴到 `env.sh` 文件中。示例结果如下： ```shell export TIDB_HOST='{host}' # e.g. gateway01.ap-northeast-1.prod.aws.tidbcloud.com @@ -101,32 +101,32 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele export USE_SSL='true' ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog. + 请务必将 `{}` 占位符替换为连接对话框中获取的实际参数。 - {{{ .starter }}} requires a secure connection. Therefore, you need to set the value of `USE_SSL` to `true`. + TiDB Cloud Serverless 需要安全连接，因此你需要将 `USE_SSL` 的值设置为 `true`。 -7. Save the `env.sh` file. +7. 保存 `env.sh` 文件。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称，进入集群概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还未配置 IP 访问列表，请点击 **Configure IP Access List**，或参考 [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 进行首次连接前的配置。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息请参考 [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Run the following command to copy `env.sh.example` and rename it to `env.sh`: +4. 运行以下命令，将 `env.sh.example` 复制并重命名为 `env.sh`： ```shell cp env.sh.example env.sh ``` -5. Copy and paste the corresponding connection string into the `env.sh` file. The example result is as follows: +5. 将对应的连接字符串复制粘贴到 `env.sh` 文件中。示例结果如下： ```shell export TIDB_HOST='{host}' # e.g. tidb.xxxx.clusters.tidb-cloud.com @@ -137,20 +137,20 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele export USE_SSL='false' ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog. + 请务必将 `{}` 占位符替换为连接对话框中获取的实际参数。 -6. Save the `env.sh` file. +6. 保存 `env.sh` 文件。
-1. Run the following command to copy `env.sh.example` and rename it to `env.sh`: +1. 运行以下命令，将 `env.sh.example` 复制并重命名为 `env.sh`： ```shell cp env.sh.example env.sh ``` -2. Copy and paste the corresponding connection string into the `env.sh` file. The example result is as follows: +2. 将对应的连接字符串复制粘贴到 `env.sh` 文件中。示例结果如下： ```shell export TIDB_HOST='{host}' @@ -161,38 +161,38 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele export USE_SSL='false' ``` - Be sure to replace the placeholders `{}` with the connection parameters, and set `USE_SSL` to `false`. If you are running TiDB locally, the default host address is `127.0.0.1`, and the password is empty. + 请务必将 `{}` 占位符替换为实际的连接参数，并将 `USE_SSL` 设置为 `false`。如果你在本地运行 TiDB，默认主机地址为 `127.0.0.1`，密码为空。 -3. Save the `env.sh` file. +3. 保存 `env.sh` 文件。
-### Step 3: Run the code and check the result +### 第 3 步：运行代码并检查结果 -1. Execute the following command to run the sample code: +1. 执行以下命令运行示例代码： ```shell make ``` -2. Run the request script in another terminal session: +2. 在另一个终端会话中运行请求脚本： ```shell make request ``` -3. Check the [Expected-Output.txt](https://github.com/tidb-samples/tidb-java-springboot-jpa-quickstart/blob/main/Expected-Output.txt) to see if the output matches. +3. 检查 [Expected-Output.txt](https://github.com/tidb-samples/tidb-java-springboot-jpa-quickstart/blob/main/Expected-Output.txt) 文件，确认输出是否一致。 -## Sample code snippets +## 示例代码片段 -You can refer to the following sample code snippets to complete your own application development. +你可以参考以下示例代码片段，完成你自己的应用开发。 -For complete sample code and how to run it, check out the [tidb-samples/tidb-java-springboot-jpa-quickstart](https://github.com/tidb-samples/tidb-java-springboot-jpa-quickstart) repository. +完整示例代码及运行方式请参考 [tidb-samples/tidb-java-springboot-jpa-quickstart](https://github.com/tidb-samples/tidb-java-springboot-jpa-quickstart) 仓库。 -### Connect to TiDB +### 连接 TiDB -Edit the configuration file `application.yml`: +编辑配置文件 `application.yml`： ```yaml spring: @@ -208,15 +208,15 @@ spring: ddl-auto: create-drop ``` -After configuration, set the environment variables `TIDB_JDBC_URL`, `TIDB_USER`, and `TIDB_PASSWORD` to the actual values of your TiDB cluster. The configuration file provides default settings for these environment variables. If you do not configure the environment variables, the default values are as follows: +配置完成后，将环境变量 `TIDB_JDBC_URL`、`TIDB_USER` 和 `TIDB_PASSWORD` 设置为你 TiDB 集群的实际值。配置文件为这些环境变量提供了默认值。如果你未配置环境变量，默认值如下： -- `TIDB_JDBC_URL`: `"jdbc:mysql://localhost:4000/test"` -- `TIDB_USER`: `"root"` -- `TIDB_PASSWORD`: `""` +- `TIDB_JDBC_URL`：`"jdbc:mysql://localhost:4000/test"` +- `TIDB_USER`：`"root"` +- `TIDB_PASSWORD`：`""` -### Data management: `@Repository` +### 数据管理：`@Repository` -Spring Data JPA manages data through the `@Repository` interface. To use the CRUD operations provided by `JpaRepository`, you need to extend the `JpaRepository` interface: +Spring Data JPA 通过 `@Repository` 接口进行数据管理。要使用 `JpaRepository` 提供的 CRUD 操作，需要继承 `JpaRepository` 接口： ```java @Repository @@ -224,60 +224,60 @@ public interface PlayerRepository extends JpaRepository { } ``` -Then, you can use `@Autowired` for automatic dependency injection in any class that requires the `PlayerRepository`. This enables you to directly use CRUD functions. The following is an example: +然后，你可以在需要 `PlayerRepository` 的任何类中使用 `@Autowired` 进行自动依赖注入，从而直接使用 CRUD 功能。示例如下： ```java @Autowired private PlayerRepository playerRepository; ``` -### Insert or update data +### 插入或更新数据 ```java playerRepository.save(player); ``` -For more information, refer to [Insert data](/develop/dev-guide-insert-data.md) and [Update data](/develop/dev-guide-update-data.md). +更多信息请参考 [插入数据](/develop/dev-guide-insert-data.md) 和 [更新数据](/develop/dev-guide-update-data.md)。 -### Query data +### 查询数据 ```java PlayerBean player = playerRepository.findById(id).orElse(null); ``` -For more information, refer to [Query data](/develop/dev-guide-get-data-from-single-table.md). +更多信息请参考 [查询数据](/develop/dev-guide-get-data-from-single-table.md)。 -### Delete data +### 删除数据 ```java playerRepository.deleteById(id); ``` -For more information, refer to [Delete data](/develop/dev-guide-delete-data.md). +更多信息请参考 [删除数据](/develop/dev-guide-delete-data.md)。 -## Next steps +## 后续步骤 -- Learn more usage about the third-party libraries and frameworks used in this document, refer to their official documentation: +- 了解本文档中使用的第三方库和框架的更多用法，请参考其官方文档： - - [The documentation of Spring Framework](https://spring.io/projects/spring-framework) - - [The documentation of Spring Boot](https://spring.io/projects/spring-boot) - - [The documentation of Spring Data JPA](https://spring.io/projects/spring-data-jpa) - - [The documentation of Hibernate](https://hibernate.org/orm/documentation) + - [Spring Framework 官方文档](https://spring.io/projects/spring-framework) + - [Spring Boot 官方文档](https://spring.io/projects/spring-boot) + - [Spring Data JPA 官方文档](https://spring.io/projects/spring-data-jpa) + - [Hibernate 官方文档](https://hibernate.org/orm/documentation) -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Single table reading](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), and [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. -- Learn through the course for Java developers: [Working with TiDB from Java](https://eng.edu.pingcap.com/catalog/info/id:212). +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节，学习 TiDB 应用开发最佳实践，例如 [插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md) 以及 [SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/)，并在通过考试后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 +- 通过 Java 开发者课程学习：[Working with TiDB from Java](https://eng.edu.pingcap.com/catalog/info/id:212)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](https://tidb.support.pingcap.com/)。 diff --git a/develop/dev-guide-sample-application-nodejs-mysql2.md b/develop/dev-guide-sample-application-nodejs-mysql2.md index e843d0726b034..7a5a8afeb5fa1 100644 --- a/develop/dev-guide-sample-application-nodejs-mysql2.md +++ b/develop/dev-guide-sample-application-nodejs-mysql2.md @@ -1,70 +1,70 @@ --- -title: Connect to TiDB with node-mysql2 -summary: Learn how to connect to TiDB using node-mysql2. This tutorial gives Node.js sample code snippets that work with TiDB using node-mysql2. +title: 使用 node-mysql2 连接 TiDB +summary: 学习如何使用 node-mysql2 连接 TiDB。本教程提供了适用于 TiDB 的 Node.js 示例代码片段，演示如何使用 node-mysql2 进行操作。 --- -# Connect to TiDB with node-mysql2 +# 使用 node-mysql2 连接 TiDB -TiDB is a MySQL-compatible database, and [node-mysql2](https://github.com/sidorares/node-mysql2) is a fast [mysqljs/mysql](https://github.com/mysqljs/mysql) compatible MySQL driver for Node.js. +TiDB 是一个兼容 MySQL 的数据库，[node-mysql2](https://github.com/sidorares/node-mysql2) 是一个快速的、兼容 [mysqljs/mysql](https://github.com/mysqljs/mysql) 的 Node.js MySQL 驱动。 -In this tutorial, you can learn how to use TiDB and node-mysql2 to accomplish the following tasks: +在本教程中，你可以学习如何使用 TiDB 和 node-mysql2 完成以下任务： -- Set up your environment. -- Connect to your TiDB cluster using node-mysql2. -- Build and run your application. Optionally, you can find [sample code snippets](#sample-code-snippets) for basic CRUD operations. +- 搭建你的开发环境。 +- 使用 node-mysql2 连接到你的 TiDB 集群。 +- 构建并运行你的应用程序。你还可以在 [示例代码片段](#sample-code-snippets) 中找到基本的 CRUD 操作示例。 > **Note:** > -> This tutorial works with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed. +> 本教程适用于 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及自建 TiDB 集群。 -## Prerequisites +## 前置条件 -To complete this tutorial, you need: +完成本教程，你需要： -- [Node.js](https://nodejs.org/en) >= 16.x installed on your machine. -- [Git](https://git-scm.com/downloads) installed on your machine. -- A TiDB cluster running. +- 在你的机器上安装 [Node.js](https://nodejs.org/en) >= 16.x。 +- 在你的机器上安装 [Git](https://git-scm.com/downloads)。 +- 一个正在运行的 TiDB 集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](/production-deployment-using-tiup.md) 创建本地集群。 -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) 创建本地集群。 -## Run the sample app to connect to TiDB +## 运行示例应用连接 TiDB -This section demonstrates how to run the sample application code and connect to TiDB. +本节演示如何运行示例应用代码并连接到 TiDB。 -### Step 1: Clone the sample app repository +### 第 1 步：克隆示例应用仓库 -Run the following commands in your terminal window to clone the sample code repository: +在终端窗口中运行以下命令，克隆示例代码仓库： ```shell git clone https://github.com/tidb-samples/tidb-nodejs-mysql2-quickstart.git cd tidb-nodejs-mysql2-quickstart ``` -### Step 2: Install dependencies +### 第 2 步：安装依赖 -Run the following command to install the required packages (including `mysql2` and `dotenv`) for the sample app: +运行以下命令，为示例应用安装所需的依赖包（包括 `mysql2` 和 `dotenv`）： ```shell npm install ```
-Install dependencies to existing project +为已有项目安装依赖 -For your existing project, run the following command to install the packages: +如果你是在已有项目中使用，运行以下命令安装依赖包： ```shell npm install mysql2 dotenv --save @@ -72,33 +72,33 @@ npm install mysql2 dotenv --save
-### Step 3: Configure connection information +### 第 3 步：配置连接信息 -Connect to your TiDB cluster depending on the TiDB deployment option you've selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接信息对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确认连接对话框中的配置与你的操作环境一致。 - - **Connection Type** is set to `Public`. - - **Branch** is set to `main`. - - **Connect With** is set to `General`. - - **Operating System** matches the operating system where you run the application. + - **Connection Type** 设置为 `Public`。 + - **Branch** 设置为 `main`。 + - **Connect With** 设置为 `General`。 + - **Operating System** 选择与你运行应用的操作系统一致。 -4. If you have not set a password yet, click **Generate Password** to generate a random password. +4. 如果你还没有设置密码，点击 **Generate Password** 生成一个随机密码。 -5. Run the following command to copy `.env.example` and rename it to `.env`: +5. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -6. Edit the `.env` file, set up the environment variables as follows, replace the corresponding placeholders `{}` with connection parameters on the connection dialog: +6. 编辑 `.env` 文件，按如下方式设置环境变量，并将对应的占位符 `{}` 替换为连接对话框中的参数： ```dotenv TIDB_HOST={host} @@ -111,30 +111,30 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele > **Note** > - > For {{{ .starter }}}, TLS connection **MUST** be enabled via `TIDB_ENABLE_SSL` when using public endpoint. + > 对于 TiDB Cloud Serverless，使用公共连接地址时，**必须** 通过 `TIDB_ENABLE_SSL` 启用 TLS 连接。 -7. Save the `.env` file. +7. 保存 `.env` 文件。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接信息对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还没有配置 IP 访问列表，点击 **Configure IP Access List**，或参考 [配置 IP 访问列表](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 进行配置后再首次连接。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息参见 [连接到你的 TiDB Cloud Dedicated 集群](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Run the following command to copy `.env.example` and rename it to `.env`: +4. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -5. Edit the `.env` file, set up the environment variables as follows, replace the corresponding placeholders `{}` with connection parameters on the connection dialog: +5. 编辑 `.env` 文件，按如下方式设置环境变量，并将对应的占位符 `{}` 替换为连接对话框中的参数： ```dotenv TIDB_HOST={host} @@ -148,22 +148,22 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele > **Note** > - > It is recommended to enable TLS connection when using the public endpoint to connect to TiDB Cloud Dedicated. + > 推荐在使用公共连接地址连接 TiDB Cloud Dedicated 时启用 TLS 连接。 > - > To enable TLS connection, modify `TIDB_ENABLE_SSL` to `true` and using `TIDB_CA_PATH` to specify the file path of CA certificate downloaded from the connection dialog. + > 启用 TLS 连接时，将 `TIDB_ENABLE_SSL` 设置为 `true`，并通过 `TIDB_CA_PATH` 指定从连接对话框下载的 CA 证书文件路径。 -6. Save the `.env` file. +6. 保存 `.env` 文件。
-
+
-1. Run the following command to copy `.env.example` and rename it to `.env`: +1. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -2. Edit the `.env` file, set up the environment variables as follows, replace the corresponding placeholders `{}` with connection parameters on the connection dialog: +2. 编辑 `.env` 文件，按如下方式设置环境变量，并将对应的占位符 `{}` 替换为连接对话框中的参数： ```dotenv TIDB_HOST={host} @@ -173,25 +173,25 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele TIDB_DATABASE=test ``` - If you are running TiDB locally, the default host address is `127.0.0.1`, and the password is empty. + 如果你在本地运行 TiDB，默认主机地址为 `127.0.0.1`，密码为空。 -3. Save the `.env` file. +3. 保存 `.env` 文件。
-### Step 4: Run the code and check the result +### 第 4 步：运行代码并查看结果 -Run the following command to execute the sample code: +运行以下命令执行示例代码： ```shell npm start ``` -If the connection is successful, the console will output the version of the TiDB cluster as follows: +如果连接成功，控制台会输出 TiDB 集群的版本信息，如下所示： ``` -🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-{{{ .tidb-version }}}) +🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-vv8.5.2) ⏳ Loading sample game data... ✅ Loaded sample game data. @@ -201,15 +201,15 @@ If the connection is successful, the console will output the version of the TiDB 🚮 Deleted 1 player data. ``` -## Sample code snippets +## 示例代码片段 -You can refer to the following sample code snippets to complete your own application development. +你可以参考以下示例代码片段，完成你自己的应用开发。 -For complete sample code and how to run it, check out the [tidb-samples/tidb-nodejs-mysql2-quickstart](https://github.com/tidb-samples/tidb-nodejs-mysql2-quickstart) repository. +完整示例代码及运行方法请参考 [tidb-samples/tidb-nodejs-mysql2-quickstart](https://github.com/tidb-samples/tidb-nodejs-mysql2-quickstart) 仓库。 -### Connect with connection options +### 使用连接参数连接 -The following code establishes a connection to TiDB with options defined in the environment variables: +以下代码通过环境变量中定义的参数连接到 TiDB： ```javascript // Step 1. Import the 'mysql' and 'dotenv' packages. @@ -246,33 +246,33 @@ void main(); > **Note** > -> For {{{ .starter }}}, you **MUST** enable TLS connection via `TIDB_ENABLE_SSL` when using public endpoint. However, you **don't** have to specify an SSL CA certificate via `TIDB_CA_PATH`, because Node.js uses the built-in [Mozilla CA certificate](https://wiki.mozilla.org/CA/Included_Certificates) by default, which is trusted by {{{ .starter }}}. +> 对于 TiDB Cloud Serverless 和 TiDB Cloud Essential，使用公共连接地址时，**必须** 通过 `TIDB_ENABLE_SSL` 启用 TLS 连接。但你**不需要**通过 `TIDB_CA_PATH` 指定 SSL CA 证书，因为 Node.js 默认使用内置的 [Mozilla CA 证书](https://wiki.mozilla.org/CA/Included_Certificates)，该证书已被 TiDB Cloud Serverless 信任。 -### Insert data +### 插入数据 -The following query creates a single `Player` record and returns a `ResultSetHeader` object: +以下语句创建一条 `Player` 记录，并返回一个 `ResultSetHeader` 对象： ```javascript const [rsh] = await conn.query('INSERT INTO players (coins, goods) VALUES (?, ?);', [100, 100]); console.log(rsh.insertId); ``` -For more information, refer to [Insert data](/develop/dev-guide-insert-data.md). +更多信息请参考 [插入数据](/develop/dev-guide-insert-data.md)。 -### Query data +### 查询数据 -The following query returns a single `Player` record by ID `1`: +以下语句根据 ID `1` 查询一条 `Player` 记录： ```javascript const [rows] = await conn.query('SELECT id, coins, goods FROM players WHERE id = ?;', [1]); console.log(rows[0]); ``` -For more information, refer to [Query data](/develop/dev-guide-get-data-from-single-table.md). +更多信息请参考 [查询数据](/develop/dev-guide-get-data-from-single-table.md)。 -### Update data +### 更新数据 -The following query adds `50` coins and `50` goods to the `Player` with ID `1`: +以下语句为 ID 为 `1` 的 `Player` 增加 `50` 个 coins 和 `50` 个 goods： ```javascript const [rsh] = await conn.query( @@ -282,43 +282,43 @@ const [rsh] = await conn.query( console.log(rsh.affectedRows); ``` -For more information, refer to [Update data](/develop/dev-guide-update-data.md). +更多信息请参考 [更新数据](/develop/dev-guide-update-data.md)。 -### Delete data +### 删除数据 -The following query deletes the `Player` record with ID `1`: +以下语句删除 ID 为 `1` 的 `Player` 记录： ```javascript const [rsh] = await conn.query('DELETE FROM players WHERE id = ?;', [1]); console.log(rsh.affectedRows); ``` -For more information, refer to [Delete data](/develop/dev-guide-delete-data.md). +更多信息请参考 [删除数据](/develop/dev-guide-delete-data.md)。 -## Useful notes +## 实用说明 -- Using [connection pools](https://github.com/sidorares/node-mysql2#using-connection-pools) to manage database connections can reduce the performance overhead caused by frequently establishing and destroying connections. -- To avoid SQL injection, it is recommended to use [prepared statements](https://github.com/sidorares/node-mysql2#using-prepared-statements). -- In scenarios where there are not many complex SQL statements involved, using ORM frameworks like [Sequelize](https://sequelize.org/), [TypeORM](https://typeorm.io/), or [Prisma](https://www.prisma.io/) can greatly improve development efficiency. -- It is recommended to enable the `supportBigNumbers: true` option when dealing with big numbers (`BIGINT` and `DECIMAL` columns) in the database. -- It is recommended to enable the `enableKeepAlive: true` option to avoid socket error `read ECONNRESET` due to network problems. (Related issue: [sidorares/node-mysql2#683](https://github.com/sidorares/node-mysql2/issues/683)) +- 使用 [连接池](https://github.com/sidorares/node-mysql2#using-connection-pools) 管理数据库连接，可以减少频繁建立和销毁连接带来的性能开销。 +- 为了避免 SQL 注入，推荐使用 [预处理语句](https://github.com/sidorares/node-mysql2#using-prepared-statements)。 +- 在 SQL 语句不复杂的场景下，使用如 [Sequelize](https://sequelize.org/)、[TypeORM](https://typeorm.io/) 或 [Prisma](https://www.prisma.io/) 等 ORM 框架可以大幅提升开发效率。 +- 在处理数据库中的大数（`BIGINT` 和 `DECIMAL` 列）时，推荐启用 `supportBigNumbers: true` 选项。 +- 推荐启用 `enableKeepAlive: true` 选项，以避免因网络问题导致的 socket 错误 `read ECONNRESET`。（相关 issue：[sidorares/node-mysql2#683](https://github.com/sidorares/node-mysql2/issues/683)） -## Next steps +## 后续学习 -- Learn more usage of node-mysql2 driver from [the documentation of node-mysql2](https://github.com/sidorares/node-mysql2#readme). -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as: [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Query data](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. +- 通过 [node-mysql2 的文档](https://github.com/sidorares/node-mysql2#readme) 学习更多 node-mysql2 驱动的用法。 +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节学习 TiDB 应用开发最佳实践，例如：[插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[查询数据](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md)、[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/) 学习，并在通过考试后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](https://tidb.support.pingcap.com/)。 diff --git a/develop/dev-guide-sample-application-nodejs-mysqljs.md b/develop/dev-guide-sample-application-nodejs-mysqljs.md index 90e4dfa8777ac..7f539c755be09 100644 --- a/develop/dev-guide-sample-application-nodejs-mysqljs.md +++ b/develop/dev-guide-sample-application-nodejs-mysqljs.md @@ -1,70 +1,70 @@ --- -title: Connect to TiDB with mysql.js -summary: Learn how to connect to TiDB using mysql.js. This tutorial gives Node.js sample code snippets that work with TiDB using mysql.js. +title: 使用 mysql.js 连接 TiDB +summary: 学习如何使用 mysql.js 连接 TiDB。本教程提供了适用于 TiDB 的 Node.js 示例代码片段，基于 mysql.js 实现。 --- -# Connect to TiDB with mysql.js +# 使用 mysql.js 连接 TiDB -TiDB is a MySQL-compatible database, and [mysql.js](https://github.com/mysqljs/mysql) driver is a pure Node.js JavaScript client implementing the MySQL protocol. +TiDB 是兼容 MySQL 的数据库，[mysql.js](https://github.com/mysqljs/mysql) 驱动是一个纯 Node.js JavaScript 客户端，实现了 MySQL 协议。 -In this tutorial, you can learn how to use TiDB and mysql.js driver to accomplish the following tasks: +在本教程中，你可以学习如何使用 TiDB 和 mysql.js 驱动完成以下任务： -- Set up your environment. -- Connect to your TiDB cluster using mysql.js driver. -- Build and run your application. Optionally, you can find [sample code snippets](#sample-code-snippets) for basic CRUD operations. +- 搭建你的开发环境。 +- 使用 mysql.js 驱动连接到你的 TiDB 集群。 +- 构建并运行你的应用程序。你还可以在 [示例代码片段](#sample-code-snippets) 中找到基本 CRUD 操作的代码示例。 > **Note:** > -> This tutorial works with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed. +> 本教程适用于 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及自建 TiDB 集群。 -## Prerequisites +## 前置条件 -To complete this tutorial, you need: +完成本教程，你需要： -- [Node.js](https://nodejs.org/en) >= 16.x installed on your machine. -- [Git](https://git-scm.com/downloads) installed on your machine. -- A TiDB cluster running. +- 在你的机器上安装 [Node.js](https://nodejs.org/en) >= 16.x。 +- 在你的机器上安装 [Git](https://git-scm.com/downloads)。 +- 一个正在运行的 TiDB 集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参照 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参照 [部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](/production-deployment-using-tiup.md) 创建本地集群。 -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参照 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参照 [部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) 创建本地集群。 -## Run the sample app to connect to TiDB +## 运行示例应用连接 TiDB -This section demonstrates how to run the sample application code and connect to TiDB. +本节演示如何运行示例应用代码并连接到 TiDB。 -### Step 1: Clone the sample app repository +### 步骤 1：克隆示例应用仓库 -Run the following commands in your terminal window to clone the sample code repository: +在终端窗口中运行以下命令，克隆示例代码仓库： ```shell git clone https://github.com/tidb-samples/tidb-nodejs-mysqljs-quickstart.git cd tidb-nodejs-mysqljs-quickstart ``` -### Step 2: Install dependencies +### 步骤 2：安装依赖 -Run the following command to install the required packages (including `mysql` and `dotenv`) for the sample app: +运行以下命令，为示例应用安装所需的依赖包（包括 `mysql` 和 `dotenv`）： ```shell npm install ```
-Install dependencies to existing project +为已有项目安装依赖 -For your existing project, run the following command to install the packages: +如果是你的已有项目，运行以下命令安装依赖包： ```shell npm install mysql dotenv --save @@ -72,33 +72,33 @@ npm install mysql dotenv --save
-### Step 3: Configure connection information +### 步骤 3：配置连接信息 -Connect to your TiDB cluster depending on the TiDB deployment option you've selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确认连接对话框中的配置与你的操作环境一致。 - - **Connection Type** is set to `Public`. - - **Branch** is set to `main`. - - **Connect With** is set to `General`. - - **Operating System** matches the operating system where you run the application. + - **Connection Type** 设置为 `Public`。 + - **Branch** 设置为 `main`。 + - **Connect With** 设置为 `General`。 + - **Operating System** 选择你运行应用的操作系统。 -4. If you have not set a password yet, click **Generate Password** to generate a random password. +4. 如果你还未设置密码，点击 **Generate Password** 生成随机密码。 -5. Run the following command to copy `.env.example` and rename it to `.env`: +5. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -6. Edit the `.env` file, set up the environment variables as follows, replace the corresponding placeholders `{}` with connection parameters on the connection dialog: +6. 编辑 `.env` 文件，按如下方式设置环境变量，将对应的占位符 `{}` 替换为连接对话框中的参数： ```dotenv TIDB_HOST={host} @@ -111,30 +111,30 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele > **Note** > - > For {{{ .starter }}}, TLS connection **MUST** be enabled via `TIDB_ENABLE_SSL` when using public endpoint. + > 对于 TiDB Cloud Serverless，使用公共连接地址时，**必须** 通过 `TIDB_ENABLE_SSL` 启用 TLS 连接。 -7. Save the `.env` file. +7. 保存 `.env` 文件。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还未配置 IP 访问列表，点击 **Configure IP Access List**，或参照 [配置 IP 访问列表](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 完成首次连接前的配置。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息参见 [连接到你的 TiDB Cloud Dedicated 集群](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Run the following command to copy `.env.example` and rename it to `.env`: +4. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -5. Edit the `.env` file, set up the environment variables as follows, replace the corresponding placeholders `{}` with connection parameters on the connection dialog: +5. 编辑 `.env` 文件，按如下方式设置环境变量，将对应的占位符 `{}` 替换为连接对话框中的参数： ```dotenv TIDB_HOST={host} @@ -148,22 +148,22 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele > **Note** > - > It is recommended to enable TLS connection when using the public endpoint to connect to TiDB Cloud Dedicated. + > 推荐在使用公共连接地址连接 TiDB Cloud Dedicated 时启用 TLS 连接。 > - > To enable TLS connection, modify `TIDB_ENABLE_SSL` to `true` and using `TIDB_CA_PATH` to specify the file path of CA certificate downloaded from the connection dialog. + > 启用 TLS 连接时，将 `TIDB_ENABLE_SSL` 设置为 `true`，并通过 `TIDB_CA_PATH` 指定从连接对话框下载的 CA 证书文件路径。 -6. Save the `.env` file. +6. 保存 `.env` 文件。
-
+
-1. Run the following command to copy `.env.example` and rename it to `.env`: +1. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -2. Edit the `.env` file, replace the corresponding placeholders `{}` with connection parameters of your cluster. The example configuration is as follows: +2. 编辑 `.env` 文件，将对应的占位符 `{}` 替换为你的集群连接参数。示例配置如下： ```dotenv TIDB_HOST={host} @@ -173,25 +173,25 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele TIDB_DATABASE=test ``` - If you are running TiDB locally, the default host address is `127.0.0.1`, and the password is empty. + 如果你在本地运行 TiDB，默认主机地址为 `127.0.0.1`，密码为空。 -3. Save the `.env` file. +3. 保存 `.env` 文件。
-### Step 4: Run the code and check the result +### 步骤 4：运行代码并查看结果 -Run the following command to execute the sample code: +运行以下命令执行示例代码： ```shell npm start ``` -If the connection is successful, the console will output the version of the TiDB cluster as follows: +如果连接成功，控制台会输出 TiDB 集群的版本信息，如下所示： ``` -🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-{{{ .tidb-version }}}) +🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-vv8.5.2) ⏳ Loading sample game data... ✅ Loaded sample game data. @@ -201,15 +201,15 @@ If the connection is successful, the console will output the version of the TiDB 🚮 Deleted 1 player data. ``` -## Sample code snippets +## 示例代码片段 -You can refer to the following sample code snippets to complete your own application development. +你可以参考以下示例代码片段，完成你自己的应用开发。 -For complete sample code and how to run it, check out the [tidb-samples/tidb-nodejs-mysqljs-quickstart](https://github.com/tidb-samples/tidb-nodejs-mysqljs-quickstart) repository. +完整示例代码及运行方式请参考 [tidb-samples/tidb-nodejs-mysqljs-quickstart](https://github.com/tidb-samples/tidb-nodejs-mysqljs-quickstart) 仓库。 -### Connect with connection options +### 使用连接参数连接 -The following code establishes a connection to TiDB with options defined in the environment variables: +以下代码通过环境变量定义的参数建立到 TiDB 的连接： ```javascript // Step 1. Import the 'mysql' and 'dotenv' packages. @@ -242,11 +242,11 @@ conn.end(); > **Note** > -> For {{{ .starter }}}, you **MUST** enable TLS connection via `TIDB_ENABLE_SSL` when using public endpoint. However, you **don't** have to specify an SSL CA certificate via `TIDB_CA_PATH`, because Node.js uses the built-in [Mozilla CA certificate](https://wiki.mozilla.org/CA/Included_Certificates) by default, which is trusted by {{{ .starter }}}. +> 对于 TiDB Cloud Serverless 和 TiDB Cloud Essential，使用公共连接地址时，**必须** 通过 `TIDB_ENABLE_SSL` 启用 TLS 连接。但你**不需要**通过 `TIDB_CA_PATH` 指定 SSL CA 证书，因为 Node.js 默认使用内置的 [Mozilla CA 证书](https://wiki.mozilla.org/CA/Included_Certificates)，该证书已被 TiDB Cloud Serverless 信任。 -### Insert data +### 插入数据 -The following query creates a single `Player` record and returns the ID of the newly created record: +以下查询会创建一条 `Player` 记录，并返回新建记录的 ID： ```javascript conn.query('INSERT INTO players (coins, goods) VALUES (?, ?);', [100, 100], (err, ok) => { @@ -258,11 +258,11 @@ conn.query('INSERT INTO players (coins, goods) VALUES (?, ?);', [100, 100], (err }); ``` -For more information, refer to [Insert data](/develop/dev-guide-insert-data.md). +更多信息请参考 [插入数据](/develop/dev-guide-insert-data.md)。 -### Query data +### 查询数据 -The following query returns a single `Player` record by ID `1`: +以下查询会根据 ID `1` 返回一条 `Player` 记录： ```javascript conn.query('SELECT id, coins, goods FROM players WHERE id = ?;', [1], (err, rows) => { @@ -274,11 +274,11 @@ conn.query('SELECT id, coins, goods FROM players WHERE id = ?;', [1], (err, rows }); ``` -For more information, refer to [Query data](/develop/dev-guide-get-data-from-single-table.md). +更多信息请参考 [查询数据](/develop/dev-guide-get-data-from-single-table.md)。 -### Update data +### 更新数据 -The following query adds `50` coins and `50` goods to the `Player` with ID `1`: +以下查询会为 ID 为 `1` 的 `Player` 增加 `50` 个 coins 和 `50` 个 goods： ```javascript conn.query( @@ -294,11 +294,11 @@ conn.query( ); ``` -For more information, refer to [Update data](/develop/dev-guide-update-data.md). +更多信息请参考 [更新数据](/develop/dev-guide-update-data.md)。 -### Delete data +### 删除数据 -The following query deletes the `Player` record with ID `1`: +以下查询会删除 ID 为 `1` 的 `Player` 记录： ```javascript conn.query('DELETE FROM players WHERE id = ?;', [1], (err, ok) => { @@ -310,38 +310,38 @@ conn.query('DELETE FROM players WHERE id = ?;', [1], (err, ok) => { }); ``` -For more information, refer to [Delete data](/develop/dev-guide-delete-data.md). +更多信息请参考 [删除数据](/develop/dev-guide-delete-data.md)。 -## Useful notes +## 实用说明 -- Using [connection pools](https://github.com/mysqljs/mysql#pooling-connections) to manage database connections can reduce the performance overhead caused by frequently establishing and destroying connections. -- To avoid SQL injection attacks, it is recommended to use [Escaping query values](https://github.com/mysqljs/mysql#escaping-query-values) before executing SQL. +- 使用 [连接池](https://github.com/mysqljs/mysql#pooling-connections) 管理数据库连接，可以减少频繁建立和销毁连接带来的性能开销。 +- 为避免 SQL 注入攻击，建议在执行 SQL 前使用 [转义查询参数](https://github.com/mysqljs/mysql#escaping-query-values)。 > **Note** > - > The `mysqljs/mysql` package does not yet support prepared statements, it only escapes values on the client side (related issue: [mysqljs/mysql#274](https://github.com/mysqljs/mysql/issues/274)). + > `mysqljs/mysql` 包目前尚不支持预处理语句，仅在客户端对参数进行转义（相关 issue：[mysqljs/mysql#274](https://github.com/mysqljs/mysql/issues/274)）。 > - > If you want to use this feature to avoid SQL injection or improve efficiency of batch insert/update, it is recommended to use [mysql2](https://github.com/sidorares/node-mysql2) package instead. + > 如果你希望通过该特性避免 SQL 注入或提升批量插入/更新效率，建议使用 [mysql2](https://github.com/sidorares/node-mysql2) 包。 -- Using ORM frameworks to improve development efficiency in scenarios without a number of complex SQL statements, such as: [Sequelize](https://sequelize.org/), [TypeORM](https://typeorm.io/), and [Prisma](/develop/dev-guide-sample-application-nodejs-prisma.md). -- It is recommended to enable the `supportBigNumbers: true` option when dealing with big numbers (`BIGINT` and `DECIMAL` columns) in the database. +- 在 SQL 语句不复杂的场景下，使用 ORM 框架可以提升开发效率，例如：[Sequelize](https://sequelize.org/)、[TypeORM](https://typeorm.io/)、[Prisma](/develop/dev-guide-sample-application-nodejs-prisma.md)。 +- 在处理数据库中的大数（`BIGINT` 和 `DECIMAL` 列）时，建议启用 `supportBigNumbers: true` 选项。 -## Next steps +## 后续步骤 -- Learn more usage of mysql.js driver from [the documentation of mysql.js](https://github.com/mysqljs/mysql#readme). -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as: [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Query data](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. +- 通过 [mysql.js 文档](https://github.com/mysqljs/mysql#readme) 学习更多 mysql.js 驱动的用法。 +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节学习 TiDB 应用开发最佳实践，例如：[插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[查询数据](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md)、[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/)，考试通过后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](https://tidb.support.pingcap.com/)。 diff --git a/develop/dev-guide-sample-application-nodejs-prisma.md b/develop/dev-guide-sample-application-nodejs-prisma.md index 80b5701afb973..cf14758b04f56 100644 --- a/develop/dev-guide-sample-application-nodejs-prisma.md +++ b/develop/dev-guide-sample-application-nodejs-prisma.md @@ -1,70 +1,70 @@ --- -title: Connect to TiDB with Prisma -summary: Learn how to connect to TiDB using Prisma. This tutorial gives Node.js sample code snippets that work with TiDB using Prisma. +title: 使用 Prisma 连接 TiDB +summary: 学习如何使用 Prisma 连接 TiDB。本教程提供了适用于 Node.js 的示例代码片段，演示如何通过 Prisma 操作 TiDB。 --- -# Connect to TiDB with Prisma +# 使用 Prisma 连接 TiDB -TiDB is a MySQL-compatible database, and [Prisma](https://github.com/prisma/prisma) is a popular open-source ORM framework for Node.js. +TiDB 是一个兼容 MySQL 的数据库，[Prisma](https://github.com/prisma/prisma) 是一个流行的开源 Node.js ORM 框架。 -In this tutorial, you can learn how to use TiDB and Prisma to accomplish the following tasks: +在本教程中，你可以学习如何使用 TiDB 和 Prisma 完成以下任务： -- Set up your environment. -- Connect to your TiDB cluster using Prisma. -- Build and run your application. Optionally, you can find [sample code snippets](#sample-code-snippets) for basic CRUD operations. +- 搭建你的开发环境。 +- 使用 Prisma 连接到你的 TiDB 集群。 +- 构建并运行你的应用程序。你还可以在 [示例代码片段](#sample-code-snippets) 中找到基本 CRUD 操作的代码示例。 > **Note:** > -> This tutorial works with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed. +> 本教程适用于 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及自建 TiDB 集群。 -## Prerequisites +## 前置条件 -To complete this tutorial, you need: +完成本教程，你需要： -- [Node.js](https://nodejs.org/en) >= 16.x installed on your machine. -- [Git](https://git-scm.com/downloads) installed on your machine. -- A TiDB cluster running. +- 在你的机器上安装 [Node.js](https://nodejs.org/en) >= 16.x。 +- 在你的机器上安装 [Git](https://git-scm.com/downloads)。 +- 一个正在运行的 TiDB 集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](/production-deployment-using-tiup.md) 创建本地集群。 -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) 创建本地集群。 -## Run the sample app to connect to TiDB +## 运行示例应用连接 TiDB -This section demonstrates how to run the sample application code and connect to TiDB. +本节演示如何运行示例应用代码并连接到 TiDB。 -### Step 1: Clone the sample app repository +### 步骤 1：克隆示例应用仓库 -Run the following commands in your terminal window to clone the sample code repository: +在终端窗口中运行以下命令，克隆示例代码仓库： ```shell git clone https://github.com/tidb-samples/tidb-nodejs-prisma-quickstart.git cd tidb-nodejs-prisma-quickstart ``` -### Step 2: Install dependencies +### 步骤 2：安装依赖 -Run the following command to install the required packages (including `prisma`) for the sample app: +运行以下命令，为示例应用安装所需的依赖包（包括 `prisma`）： ```shell npm install ```
-Install dependencies to existing project +为已有项目安装依赖 -For your existing project, run the following command to install the packages: +如果是你的已有项目，运行以下命令安装依赖包： ```shell npm install prisma typescript ts-node @types/node --save-dev @@ -72,33 +72,33 @@ npm install prisma typescript ts-node @types/node --save-dev
-### Step 3: Provide connection Parameters +### 步骤 3：配置连接参数 -Connect to your TiDB cluster depending on the TiDB deployment option you've selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确认连接对话框中的配置与你的操作环境一致。 - - **Connection Type** is set to `Public`. - - **Branch** is set to `main`. - - **Connect With** is set to `Prisma`. - - **Operating System** matches the operating system where you run the application. + - **Connection Type** 设置为 `Public`。 + - **Branch** 设置为 `main`。 + - **Connect With** 设置为 `Prisma`。 + - **Operating System** 选择你运行应用的操作系统。 -4. If you have not set a password yet, click **Generate Password** to generate a random password. +4. 如果你还未设置密码，点击 **Generate Password** 生成一个随机密码。 -5. Run the following command to copy `.env.example` and rename it to `.env`: +5. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： ```shell cp .env.example .env ``` -6. Edit the `.env` file, set up the environment variable `DATABASE_URL` as follows, and replace the corresponding placeholders `{}` with the connection string in the connection dialog: +6. 编辑 `.env` 文件，按如下方式设置环境变量 `DATABASE_URL`，并将对应的占位符 `{}` 替换为连接对话框中的连接字符串： ```dotenv DATABASE_URL='{connection_string}' @@ -106,10 +106,10 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele > **Note** > - > For {{{ .starter }}}, you **MUST** enable TLS connection by setting `sslaccept=strict` when using public endpoint. + > 对于 TiDB Cloud Serverless，使用 public endpoint 时，你 **必须** 通过设置 `sslaccept=strict` 启用 TLS 连接。 -7. Save the `.env` file. -8. In the `prisma/schema.prisma`, set up `mysql` as the connection provider and `env("DATABASE_URL")` as the connection URL: +7. 保存 `.env` 文件。 +8. 在 `prisma/schema.prisma` 文件中，将 `mysql` 设置为连接 provider，并将 `env("DATABASE_URL")` 作为连接 URL： ```prisma datasource db { @@ -121,23 +121,23 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还未配置 IP 访问列表，点击 **Configure IP Access List** 或参考 [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 进行配置，以便首次连接。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息请参见 [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Run the following command to copy `.env.example` and rename it to `.env`: +4. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： ```shell cp .env.example .env ``` -5. Edit the `.env` file, set up the environment variable `DATABASE_URL` as follows, replace the corresponding placeholders `{}` with connection parameters on the connection dialog: +5. 编辑 `.env` 文件，按如下方式设置环境变量 `DATABASE_URL`，并将对应的占位符 `{}` 替换为连接对话框中的连接参数： ```dotenv DATABASE_URL='mysql://{user}:{password}@{host}:4000/test?sslaccept=strict&sslcert={downloaded_ssl_ca_path}' @@ -145,10 +145,10 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele > **Note** > - > For {{{ .starter }}}, It is **RECOMMENDED** to enable TLS connection by setting `sslaccept=strict` when using public endpoint. When you set up `sslaccept=strict` to enable TLS connection, you **MUST** specify the file path of the CA certificate downloaded from connection dialog via `sslcert=/path/to/ca.pem`. + > 对于 TiDB Cloud Serverless，**推荐**在使用 public endpoint 时通过设置 `sslaccept=strict` 启用 TLS 连接。当你设置 `sslaccept=strict` 启用 TLS 连接时，**必须**通过 `sslcert=/path/to/ca.pem` 指定从连接对话框下载的 CA 证书文件路径。 -6. Save the `.env` file. -7. In the `prisma/schema.prisma`, set up `mysql` as the connection provider and `env("DATABASE_URL")` as the connection URL: +6. 保存 `.env` 文件。 +7. 在 `prisma/schema.prisma` 文件中，将 `mysql` 设置为连接 provider，并将 `env("DATABASE_URL")` 作为连接 URL： ```prisma datasource db { @@ -160,23 +160,23 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele
-1. Run the following command to copy `.env.example` and rename it to `.env`: +1. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： ```shell cp .env.example .env ``` -2. Edit the `.env` file, set up the environment variable `DATABASE_URL` as follows, replace the corresponding placeholders `{}` with connection parameters of your TiDB cluster: +2. 编辑 `.env` 文件，按如下方式设置环境变量 `DATABASE_URL`，并将对应的占位符 `{}` 替换为你的 TiDB 集群连接参数： ```dotenv DATABASE_URL='mysql://{user}:{password}@{host}:4000/test' ``` - If you are running TiDB locally, the default host address is `127.0.0.1`, and the password is empty. + 如果你在本地运行 TiDB，默认主机地址为 `127.0.0.1`，密码为空。 -3. Save the `.env` file. +3. 保存 `.env` 文件。 -4. In the `prisma/schema.prisma`, set up `mysql` as the connection provider and `env("DATABASE_URL")` as the connection URL: +4. 在 `prisma/schema.prisma` 文件中，将 `mysql` 设置为连接 provider，并将 `env("DATABASE_URL")` 作为连接 URL： ```prisma datasource db { @@ -188,15 +188,15 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele
-### Step 4. Initialize the database schema +### 步骤 4：初始化数据库 schema -Run following command to invoke [Prisma Migrate](https://www.prisma.io/docs/concepts/components/prisma-migrate) to initialize the database with the data models defined in `prisma/prisma.schema`. +运行以下命令，调用 [Prisma Migrate](https://www.prisma.io/docs/concepts/components/prisma-migrate) 根据 `prisma/prisma.schema` 中定义的数据模型初始化数据库： ```shell npx prisma migrate dev ``` -**Data models defined in `prisma.schema`:** +**`prisma.schema` 中定义的数据模型：** ```prisma // Define a Player model, which represents the `players` table. @@ -223,9 +223,9 @@ model Profile { } ``` -To learn how to define data models in Prisma, please check the [Data model](https://www.prisma.io/docs/concepts/components/prisma-schema/data-model) documentation. +如需了解如何在 Prisma 中定义数据模型，请查阅 [Data model](https://www.prisma.io/docs/concepts/components/prisma-schema/data-model) 文档。 -**Expected execution output:** +**预期执行输出：** ``` Your database is now in sync with your schema. @@ -233,17 +233,17 @@ Your database is now in sync with your schema. ✔ Generated Prisma Client (5.1.1 | library) to ./node_modules/@prisma/client in 54ms ``` -This command will also generate [Prisma Client](https://www.prisma.io/docs/concepts/components/prisma-client) for TiDB database accessing based on the `prisma/prisma.schema`. +该命令还会基于 `prisma/prisma.schema` 为 TiDB 数据库访问生成 [Prisma Client](https://www.prisma.io/docs/concepts/components/prisma-client)。 -### Step 5: Run the code +### 步骤 5：运行代码 -Run the following command to execute the sample code: +运行以下命令执行示例代码： ```shell npm start ``` -**Main logic in the sample code:** +**示例代码的主要逻辑：** ```typescript // Step 1. Import the auto-generated `@prisma/client` package. @@ -265,27 +265,27 @@ async function main(): Promise { void main(); ``` -**Expected execution output:** +**预期执行输出：** -If the connection is successful, the terminal will output the version of the TiDB cluster as follows: +如果连接成功，终端会输出 TiDB 集群的版本信息，如下所示： ``` -🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-{{{ .tidb-version }}}) +🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-vv8.5.2) 🆕 Created a new player with ID 1. ℹ️ Got Player 1: Player { id: 1, coins: 100, goods: 100 } 🔢 Added 50 coins and 50 goods to player 1, now player 1 has 150 coins and 150 goods. 🚮 Player 1 has been deleted. ``` -## Sample code snippets +## 示例代码片段 -You can refer to the following sample code snippets to complete your own application development. +你可以参考以下示例代码片段，完成你自己的应用开发。 -For complete sample code and how to run it, check out the [tidb-samples/tidb-nodejs-prisma-quickstart](https://github.com/tidb-samples/tidb-nodejs-prisma-quickstart) repository. +完整示例代码及运行方式请参考 [tidb-samples/tidb-nodejs-prisma-quickstart](https://github.com/tidb-samples/tidb-nodejs-prisma-quickstart) 仓库。 -### Insert data +### 插入数据 -The following query creates a single `Player` record, and returns the created `Player` object, which contains the `id` field generated by TiDB: +以下查询会创建一条 `Player` 记录，并返回包含 TiDB 生成的 `id` 字段的 `Player` 对象： ```javascript const player: Player = await prisma.player.create({ @@ -298,11 +298,11 @@ const player: Player = await prisma.player.create({ }); ``` -For more information, refer to [Insert data](/develop/dev-guide-insert-data.md). +更多信息请参考 [插入数据](/develop/dev-guide-insert-data.md)。 -### Query data +### 查询数据 -The following query returns a single `Player` object with ID `101` or `null` if no record is found: +以下查询会返回 ID 为 `101` 的 `Player` 对象，如果未找到则返回 `null`： ```javascript const player: Player | null = prisma.player.findUnique({ @@ -312,11 +312,11 @@ const player: Player | null = prisma.player.findUnique({ }); ``` -For more information, refer to [Query data](/develop/dev-guide-get-data-from-single-table.md). +更多信息请参考 [查询数据](/develop/dev-guide-get-data-from-single-table.md)。 -### Update data +### 更新数据 -The following query adds `50` coins and `50` goods to the `Player` with ID `101`: +以下查询会为 ID 为 `101` 的 `Player` 增加 `50` 个 coins 和 `50` 个 goods： ```javascript await prisma.player.update({ @@ -334,11 +334,11 @@ await prisma.player.update({ }); ``` -For more information, refer to [Update data](/develop/dev-guide-update-data.md). +更多信息请参考 [更新数据](/develop/dev-guide-update-data.md)。 -### Delete data +### 删除数据 -The following query deletes the `Player` with ID `101`: +以下查询会删除 ID 为 `101` 的 `Player`： ```javascript await prisma.player.delete({ @@ -348,38 +348,38 @@ await prisma.player.delete({ }); ``` -For more information, refer to [Delete data](/develop/dev-guide-delete-data.md). +更多信息请参考 [删除数据](/develop/dev-guide-delete-data.md)。 -## Useful notes +## 实用说明 -### Foreign key constraints vs Prisma relation mode +### 外键约束 vs Prisma relation mode -To check [referential integrity](https://en.wikipedia.org/wiki/Referential_integrity?useskin=vector), you can use foreign key constraints or Prisma relation mode: +要检查 [参照完整性](https://en.wikipedia.org/wiki/Referential_integrity?useskin=vector)，你可以使用外键约束或 Prisma relation mode： -- [Foreign key](https://docs.pingcap.com/tidb/stable/foreign-key) is a feature supported starting from TiDB v6.6.0, and generally available starting from v8.5.0. Foreign keys allow cross-table references of related data, while foreign key constraints ensure the consistency of related data. +- [外键](https://docs.pingcap.com/tidb/stable/foreign-key) 是 TiDB v6.6.0 开始支持的特性，并在 v8.5.0 起正式可用。外键允许跨表引用相关数据，外键约束可保证相关数据的一致性。 > **Warning:** > - > **Foreign keys are suitable for small and medium-volumes data scenarios.** Using foreign keys in large data volumes might lead to serious performance issues and could have unpredictable effects on the system. If you plan to use foreign keys, conduct thorough validation first and use them with caution. + > **外键适用于中小数据量场景。** 在大数据量场景下使用外键可能导致严重的性能问题，并可能对系统产生不可预期的影响。如果你计划使用外键，请务必充分验证并谨慎使用。 -- [Prisma relation mode](https://www.prisma.io/docs/concepts/components/prisma-schema/relations/relation-mode) is the emulation of referential integrity in Prisma Client side. However, it should be noted that there are performance implications, as it requires additional database queries to maintain referential integrity. +- [Prisma relation mode](https://www.prisma.io/docs/concepts/components/prisma-schema/relations/relation-mode) 是在 Prisma Client 端模拟参照完整性。但需要注意的是，这会带来性能影响，因为它需要额外的数据库查询来维护参照完整性。 -## Next steps +## 后续步骤 -- Learn more usage of the ORM framework Prisma driver from [the documentation of Prisma](https://www.prisma.io/docs). -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as: [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Query data](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. +- 通过 [Prisma 官方文档](https://www.prisma.io/docs) 学习更多 ORM 框架 Prisma driver 的用法。 +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节学习 TiDB 应用开发最佳实践，例如：[插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[查询数据](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md)、[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/) 学习，并在通过考试后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](https://tidb.support.pingcap.com/)。 diff --git a/develop/dev-guide-sample-application-nodejs-sequelize.md b/develop/dev-guide-sample-application-nodejs-sequelize.md index afc4ba3904de5..76419e452dd27 100644 --- a/develop/dev-guide-sample-application-nodejs-sequelize.md +++ b/develop/dev-guide-sample-application-nodejs-sequelize.md @@ -1,108 +1,108 @@ --- -title: Connect to TiDB with Sequelize -summary: Learn how to connect to TiDB using Sequelize. This tutorial gives Node.js sample code snippets that work with TiDB using Sequelize. +title: 使用 Sequelize 连接 TiDB +summary: 学习如何使用 Sequelize 连接 TiDB。本教程提供了可在 Node.js 中通过 Sequelize 操作 TiDB 的示例代码片段。 --- -# Connect to TiDB with Sequelize +# 使用 Sequelize 连接 TiDB -TiDB is a MySQL-compatible database, and [Sequelize](https://sequelize.org/) is a popular ORM framework for Node.js. +TiDB 是一个兼容 MySQL 的数据库，[Sequelize](https://sequelize.org/) 是 Node.js 中流行的 ORM 框架。 -In this tutorial, you can learn how to use TiDB and Sequelize to accomplish the following tasks: +在本教程中，你可以学习如何使用 TiDB 和 Sequelize 完成以下任务： -- Set up your environment. -- Connect to your TiDB cluster using Sequelize. -- Build and run your application. Optionally, you can find [sample code snippets](#sample-code-snippets) for basic CRUD operations. +- 搭建你的开发环境。 +- 使用 Sequelize 连接到你的 TiDB 集群。 +- 构建并运行你的应用程序。你还可以在 [示例代码片段](#sample-code-snippets) 中找到基本 CRUD 操作的代码示例。 > **Note** > -> This tutorial works with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed. +> 本教程适用于 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及自建 TiDB 集群。 -## Prerequisites +## 前置条件 -To complete this tutorial, you need: +完成本教程，你需要： -- [Node.js **18**](https://nodejs.org/en/download/) or later. -- [Git](https://git-scm.com/downloads). -- A TiDB cluster. +- [Node.js **18**](https://nodejs.org/en/download/) 或更高版本。 +- [Git](https://git-scm.com/downloads)。 +- 一个 TiDB 集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](/production-deployment-using-tiup.md) 创建本地集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) 创建本地集群。 -## Run the sample app to connect to TiDB +## 运行示例应用连接 TiDB -This section demonstrates how to run the sample application code and connect to TiDB. +本节演示如何运行示例应用代码并连接到 TiDB。 > **Note** > -> For complete code snippets and running instructions, refer to the [tidb-samples/tidb-nodejs-sequelize-quickstart](https://github.com/tidb-samples/tidb-nodejs-sequelize-quickstart) GitHub repository. +> 完整代码片段及运行说明请参考 [tidb-samples/tidb-nodejs-sequelize-quickstart](https://github.com/tidb-samples/tidb-nodejs-sequelize-quickstart) GitHub 仓库。 -### Step 1: Clone the sample app repository +### 步骤 1：克隆示例应用仓库 -Run the following commands in your terminal window to clone the sample code repository: +在终端窗口中运行以下命令，克隆示例代码仓库： ```bash git clone git@github.com:tidb-samples/tidb-nodejs-sequelize-quickstart.git cd tidb-nodejs-sequelize-quickstart ``` -### Step 2: Install dependencies +### 步骤 2：安装依赖 -Run the following command to install the required packages (including `sequelize`) for the sample app: +运行以下命令，为示例应用安装所需的依赖包（包括 `sequelize`）： ```bash npm install ``` -### Step 3: Configure connection information +### 步骤 3：配置连接信息 -Connect to your TiDB cluster depending on the TiDB deployment option you've selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确保连接对话框中的配置与你的操作环境一致。 - - **Connection Type** is set to `Public` - - **Branch** is set to `main` - - **Connect With** is set to `General` - - **Operating System** matches your environment. + - **Connection Type** 设置为 `Public` + - **Branch** 设置为 `main` + - **Connect With** 设置为 `General` + - **Operating System** 与你的环境一致 > **Note** > - > In Node.js applications, you don't have to provide an SSL CA certificate, because Node.js uses the built-in [Mozilla CA certificate](https://wiki.mozilla.org/CA/Included_Certificates) by default when establishing the TLS (SSL) connection. + > 在 Node.js 应用中，无需单独提供 SSL CA 证书，因为 Node.js 在建立 TLS（SSL）连接时默认使用内置的 [Mozilla CA 证书](https://wiki.mozilla.org/CA/Included_Certificates)。 -4. Click **Generate Password** to create a random password. +4. 点击 **Generate Password** 生成一个随机密码。 > **Tip** > - > If you have generated a password before, you can either use the original password or click **Reset Password** to generate a new one. + > 如果你之前已经生成过密码，可以继续使用原密码，或点击 **Reset Password** 生成新密码。 -5. Run the following command to copy `.env.example` and rename it to `.env`: +5. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： ```shell cp .env.example .env ``` -6. Edit the `.env` file, set up the environment variables as follows, replace the corresponding placeholders `{}` with connection parameters on the connection dialog: +6. 编辑 `.env` 文件，按如下方式设置环境变量，并将对应的占位符 `{}` 替换为连接对话框中的参数： ```dotenv TIDB_HOST='{host}' @@ -113,29 +113,29 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele TIDB_ENABLE_SSL='true' ``` -7. Save the `.env` file. +7. 保存 `.env` 文件。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还未配置 IP 访问列表，请点击 **Configure IP Access List**，或参考 [配置 IP 访问列表](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 进行配置后再首次连接。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息请参考 [连接到你的 TiDB Cloud Dedicated 集群](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Run the following command to copy `.env.example` and rename it to `.env`: +4. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： ```shell cp .env.example .env ``` -5. Edit the `.env` file, set up the environment variables as follows, replace the corresponding placeholders `{}` with connection parameters on the connection dialog: +5. 编辑 `.env` 文件，按如下方式设置环境变量，并将对应的占位符 `{}` 替换为连接对话框中的参数： ```shell TIDB_HOST='{host}' @@ -147,19 +147,19 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele TIDB_CA_PATH='{path/to/ca}' ``` -6. Save the `.env` file. +6. 保存 `.env` 文件。
-
+
-1. Run the following command to copy `.env.example` and rename it to `.env`: +1. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： ```shell cp .env.example .env ``` -2. Edit the `.env` file, set up the environment variables as follows, replace the corresponding placeholders `{}` with connection parameters on the connection dialog: +2. 编辑 `.env` 文件，按如下方式设置环境变量，并将对应的占位符 `{}` 替换为连接对话框中的参数： ```shell TIDB_HOST='{host}' @@ -169,24 +169,24 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele TIDB_DB_NAME='test' ``` - If you are running TiDB locally, the default host address is `127.0.0.1`, and the password is empty. + 如果你在本地运行 TiDB，默认主机地址为 `127.0.0.1`，密码为空。 -3. Save the `.env` file. +3. 保存 `.env` 文件。
-### Step 4: Run the sample app +### 步骤 4：运行示例应用 -Run the following command to execute the sample code: +运行以下命令执行示例代码： ```shell npm start ```
-**Expected output(partial):** +**预期输出（部分）：** ```shell INFO (app/10117): Getting sequelize instance... @@ -202,15 +202,15 @@ Executing (default): DELETE FROM `players` WHERE `id` = 6
-## Sample code snippets +## 示例代码片段 -You can refer to the following sample code snippets to complete your own application development. +你可以参考以下示例代码片段，完成你自己的应用开发。 -For complete sample code and how to run it, check out the [tidb-samples/tidb-nodejs-sequelize-quickstart](https://github.com/tidb-samples/tidb-nodejs-sequelize-quickstart) repository. +完整示例代码及运行方式请参考 [tidb-samples/tidb-nodejs-sequelize-quickstart](https://github.com/tidb-samples/tidb-nodejs-sequelize-quickstart) 仓库。 -### Connect to TiDB +### 连接 TiDB -The following code establish a connection to TiDB with options defined in the environment variables: +以下代码通过环境变量中定义的参数建立 TiDB 连接： ```typescript // src/lib/tidb.ts @@ -254,9 +254,9 @@ export async function getSequelize() { } ``` -### Insert data +### 插入数据 -The following query creates a single `Players` record and returns a `Players` object: +以下查询会创建一条 `Players` 记录，并返回一个 `Players` 对象： ```typescript logger.info('Creating a new player...'); @@ -269,11 +269,11 @@ logger.info('Created a new player.'); logger.info(newPlayer.toJSON()); ``` -For more information, refer to [Insert data](/develop/dev-guide-insert-data.md). +更多信息请参考 [插入数据](/develop/dev-guide-insert-data.md)。 -### Query data +### 查询数据 -The following query returns a single `Players` record those coins are greater than `300`: +以下查询会返回所有 `coins` 大于 `300` 的 `Players` 记录： ```typescript logger.info('Reading all players with coins > 300...'); @@ -288,11 +288,11 @@ logger.info('Read all players with coins > 300.'); logger.info(allPlayersWithCoinsGreaterThan300.map((p) => p.toJSON())); ``` -For more information, refer to [Query data](/develop/dev-guide-get-data-from-single-table.md). +更多信息请参考 [查询数据](/develop/dev-guide-get-data-from-single-table.md)。 -### Update data +### 更新数据 -The following query set `700` coins and `700` goods to the `Players` with ID `6` that was created in the [Insert data](#insert-data) section: +以下查询会将 [插入数据](#insert-data) 部分创建的 ID 为 `6` 的 `Players` 的 `coins` 和 `goods` 字段都设置为 `700`： ```typescript logger.info('Updating the new player...'); @@ -301,11 +301,11 @@ logger.info('Updated the new player.'); logger.info(newPlayer.toJSON()); ``` -For more information, refer to [Update data](/develop/dev-guide-update-data.md). +更多信息请参考 [更新数据](/develop/dev-guide-update-data.md)。 -### Delete data +### 删除数据 -The following query deletes the `Player` record with ID `6` that was created in the [Insert data](#insert-data) section: +以下查询会删除 [插入数据](#insert-data) 部分创建的 ID 为 `6` 的 `Player` 记录： ```typescript logger.info('Deleting the new player...'); @@ -315,24 +315,24 @@ logger.info('Deleted the new player.'); logger.info(deletedNewPlayer?.toJSON()); ``` -For more information, refer to [Delete data](/develop/dev-guide-delete-data.md). +更多信息请参考 [删除数据](/develop/dev-guide-delete-data.md)。 -## Next steps +## 后续步骤 -- Learn more usage of the ORM framework Sequelize driver from [the documentation of Sequelize](https://sequelize.org/). -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Single table reading](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), and [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. +- 通过 [Sequelize 官方文档](https://sequelize.org/) 学习更多 ORM 框架 Sequelize 的用法。 +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节，学习 TiDB 应用开发最佳实践，例如 [插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md) 以及 [SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/) 学习，并在通过考试后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +欢迎在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +欢迎在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](https://tidb.support.pingcap.com/)。 diff --git a/develop/dev-guide-sample-application-nodejs-typeorm.md b/develop/dev-guide-sample-application-nodejs-typeorm.md index 55fd3b40f8c5e..d5590411fa46b 100644 --- a/develop/dev-guide-sample-application-nodejs-typeorm.md +++ b/develop/dev-guide-sample-application-nodejs-typeorm.md @@ -1,77 +1,77 @@ --- -title: Connect to TiDB with TypeORM -summary: Learn how to connect to TiDB using TypeORM. This tutorial gives Node.js sample code snippets that work with TiDB using TypeORM. +title: 使用 TypeORM 连接 TiDB +summary: 学习如何使用 TypeORM 连接 TiDB。本教程提供了适用于 TiDB 的 Node.js 示例代码片段，演示如何通过 TypeORM 进行操作。 --- -# Connect to TiDB with TypeORM +# 使用 TypeORM 连接 TiDB -TiDB is a MySQL-compatible database, and [TypeORM](https://github.com/TypeORM/TypeORM) is a popular open-source ORM framework for Node.js. +TiDB 是一个兼容 MySQL 的数据库，[TypeORM](https://github.com/TypeORM/TypeORM) 是 Node.js 领域流行的开源 ORM 框架。 -In this tutorial, you can learn how to use TiDB and TypeORM to accomplish the following tasks: +在本教程中，你可以学习如何结合 TiDB 和 TypeORM 完成以下任务： -- Set up your environment. -- Connect to your TiDB cluster using TypeORM. -- Build and run your application. Optionally, you can find [sample code snippets](#sample-code-snippets) for basic CRUD operations. +- 搭建开发环境 +- 使用 TypeORM 连接到你的 TiDB 集群 +- 构建并运行你的应用程序。你还可以在 [示例代码片段](#sample-code-snippets) 中找到基本的 CRUD 操作示例。 > **Note** > -> This tutorial works with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed. +> 本教程适用于 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及自建 TiDB 集群。 -## Prerequisites +## 前置条件 -To complete this tutorial, you need: +完成本教程，你需要： -- [Node.js](https://nodejs.org/en) >= 16.x installed on your machine. -- [Git](https://git-scm.com/downloads) installed on your machine. -- A TiDB cluster running. +- 在本地安装 [Node.js](https://nodejs.org/en) >= 16.x +- 在本地安装 [Git](https://git-scm.com/downloads) +- 已有一个正在运行的 TiDB 集群 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](/production-deployment-using-tiup.md) 创建本地集群。 -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) 创建本地集群。 -## Run the sample app to connect to TiDB +## 运行示例应用并连接 TiDB -This section demonstrates how to run the sample application code and connect to TiDB. +本节演示如何运行示例应用代码并连接到 TiDB。 -### Step 1: Clone the sample app repository +### 第 1 步：克隆示例应用仓库 -Run the following commands in your terminal window to clone the sample code repository: +在终端窗口中运行以下命令，克隆示例代码仓库： ```shell git clone https://github.com/tidb-samples/tidb-nodejs-typeorm-quickstart.git cd tidb-nodejs-typeorm-quickstart ``` -### Step 2: Install dependencies +### 第 2 步：安装依赖 -Run the following command to install the required packages (including `typeorm` and `mysql2`) for the sample app: +运行以下命令，为示例应用安装所需的依赖包（包括 `typeorm` 和 `mysql2`）： ```shell npm install ```
-Install dependencies to an existing project +为已有项目安装依赖 -For your existing project, run the following command to install the packages: +如果你是在已有项目中集成，运行以下命令安装相关依赖： -- `typeorm`: the ORM framework for Node.js. -- `mysql2`: the MySQL driver for Node.js. You can also use the `mysql` driver. -- `dotenv`: loads environment variables from the `.env` file. -- `typescript`: compiles TypeScript code to JavaScript. -- `ts-node`: runs TypeScript code directly without compiling. -- `@types/node`: provides TypeScript type definitions for Node.js. +- `typeorm`：Node.js 的 ORM 框架 +- `mysql2`：Node.js 的 MySQL 驱动。你也可以使用 `mysql` 驱动 +- `dotenv`：从 `.env` 文件加载环境变量 +- `typescript`：将 TypeScript 代码编译为 JavaScript +- `ts-node`：无需编译即可直接运行 TypeScript 代码 +- `@types/node`：为 Node.js 提供 TypeScript 类型定义 ```shell npm install typeorm mysql2 dotenv --save @@ -80,33 +80,33 @@ npm install @types/node ts-node typescript --save-dev
-### Step 3: Configure connection information +### 第 3 步：配置连接信息 -Connect to your TiDB cluster depending on the TiDB deployment option you've selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接信息对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确认连接对话框中的配置与你的操作环境一致： - - **Connection Type** is set to `Public`. - - **Branch** is set to `main`. - - **Connect With** is set to `General`. - - **Operating System** matches the operating system where you run the application. + - **Connection Type** 选择 `Public` + - **Branch** 选择 `main` + - **Connect With** 选择 `General` + - **Operating System** 选择你运行应用的操作系统 -4. If you have not set a password yet, click **Generate Password** to generate a random password. +4. 如果你还未设置密码，点击 **Generate Password** 生成随机密码。 -5. Run the following command to copy `.env.example` and rename it to `.env`: +5. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -6. Edit the `.env` file, set up the environment variables as follows, replace the corresponding placeholders `{}` with connection parameters on the connection dialog: +6. 编辑 `.env` 文件，按如下格式设置环境变量，并将对应的占位符 `{}` 替换为连接对话框中的参数： ```dotenv TIDB_HOST={host} @@ -119,30 +119,30 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele > **Note** > - > For {{{ .starter }}}, you **MUST** enable TLS connection via `TIDB_ENABLE_SSL` when using public endpoint. + > 对于 TiDB Cloud Serverless 和 TiDB Cloud Essential，当使用公网连接时，**必须** 通过 `TIDB_ENABLE_SSL` 启用 TLS 连接。 -7. Save the `.env` file. +7. 保存 `.env` 文件。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接信息对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还未配置 IP 访问列表，点击 **Configure IP Access List**，或参考 [配置 IP 访问列表](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 完成首次连接前的配置。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息参见 [连接 TiDB Cloud Dedicated 集群](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Run the following command to copy `.env.example` and rename it to `.env`: +4. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -5. Edit the `.env` file, set up the environment variables as follows, replace the corresponding placeholders `{}` with connection parameters on the connection dialog: +5. 编辑 `.env` 文件，按如下格式设置环境变量，并将对应的占位符 `{}` 替换为连接对话框中的参数： ```dotenv TIDB_HOST={host} @@ -156,20 +156,20 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele > **Note** > - > For TiDB Cloud Dedicated, it is **RECOMMENDED** to enable TLS connection via `TIDB_ENABLE_SSL` when using public endpoint. When you set up `TIDB_ENABLE_SSL=true`, you **MUST** specify the path of the CA certificate downloaded from connection dialog via `TIDB_CA_PATH=/path/to/ca.pem`. + > 对于 TiDB Cloud Dedicated，**推荐** 在使用公网连接时启用 TLS 连接（`TIDB_ENABLE_SSL`）。当你设置 `TIDB_ENABLE_SSL=true` 时，**必须** 通过 `TIDB_CA_PATH=/path/to/ca.pem` 指定从连接对话框下载的 CA 证书路径。 -6. Save the `.env` file. +6. 保存 `.env` 文件。
-
+
-1. Run the following command to copy `.env.example` and rename it to `.env`: +1. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -2. Edit the `.env` file, set up the environment variables as follows, replace the corresponding placeholders `{}` with connection parameters of your TiDB cluster: +2. 编辑 `.env` 文件，按如下格式设置环境变量，并将对应的占位符 `{}` 替换为你的 TiDB 集群连接参数： ```dotenv TIDB_HOST={host} @@ -179,25 +179,25 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele TIDB_DATABASE=test ``` - If you are running TiDB locally, the default host address is `127.0.0.1`, and the password is empty. + 如果你在本地运行 TiDB，默认主机地址为 `127.0.0.1`，密码为空。 -3. Save the `.env` file. +3. 保存 `.env` 文件。
-### Step 4: Initialize the database schema +### 第 4 步：初始化数据库结构 -Run the following command to invoke TypeORM CLI to initialize the database with the SQL statements written in the migration files in the `src/migrations` folder: +运行以下命令，调用 TypeORM CLI，根据 `src/migrations` 文件夹下的 migration 文件中的 SQL 语句初始化数据库： ```shell npm run migration:run ```
-Expected execution output +预期执行输出 -The following SQL statements create a `players` table and a `profiles` table, and the two tables are associated through foreign keys. +以下 SQL 语句会创建 `players` 表和 `profiles` 表，并通过外键将两张表关联起来。 ```sql query: SELECT VERSION() AS `version` @@ -218,37 +218,37 @@ query: COMMIT
-Migration files are generated from the entities defined in the `src/entities` folder. To learn how to define entities in TypeORM, refer to [TypeORM: Entities](https://typeorm.io/entities). +Migration 文件是根据 `src/entities` 文件夹下定义的实体自动生成的。关于如何在 TypeORM 中定义实体，参考 [TypeORM: Entities](https://typeorm.io/entities)。 -### Step 5: Run the code and check the result +### 第 5 步：运行代码并查看结果 -Run the following command to execute the sample code: +运行以下命令，执行示例代码： ```shell npm start ``` -**Expected execution output:** +**预期执行输出：** -If the connection is successful, the terminal will output the version of the TiDB cluster as follows: +如果连接成功，终端会输出 TiDB 集群的版本信息，如下所示： ``` -🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-{{{ .tidb-version }}}) +🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-vv8.5.2) 🆕 Created a new player with ID 2. ℹ️ Got Player 2: Player { id: 2, coins: 100, goods: 100 } 🔢 Added 50 coins and 50 goods to player 2, now player 2 has 100 coins and 150 goods. 🚮 Deleted 1 player data. ``` -## Sample code snippets +## 示例代码片段 -You can refer to the following sample code snippets to complete your own application development. +你可以参考以下示例代码片段，完成你自己的应用开发。 -For complete sample code and how to run it, check out the [tidb-samples/tidb-nodejs-typeorm-quickstart](https://github.com/tidb-samples/tidb-nodejs-typeorm-quickstart) repository. +完整示例代码及运行方式请参考 [tidb-samples/tidb-nodejs-typeorm-quickstart](https://github.com/tidb-samples/tidb-nodejs-typeorm-quickstart) 仓库。 -### Connect with connection options +### 使用连接参数连接 -The following code establishes a connection to TiDB with options defined in the environment variables: +以下代码通过环境变量定义的参数建立到 TiDB 的连接： ```typescript // src/dataSource.ts @@ -276,24 +276,24 @@ export const AppDataSource = new DataSource({ > **Note** > -> For {{{ .starter }}}, you MUST enable TLS connection when using public endpoint. In this sample code, please set up the environment variable `TIDB_ENABLE_SSL` in the `.env` file to `true`. +> 对于 TiDB Cloud Serverless 和 TiDB Cloud Essential，当使用公网连接时，**必须** 启用 TLS 连接。在本示例代码中，请在 `.env` 文件中将环境变量 `TIDB_ENABLE_SSL` 设置为 `true`。 > -> However, you **don't** have to specify an SSL CA certificate via `TIDB_CA_PATH`, because Node.js uses the built-in [Mozilla CA certificate](https://wiki.mozilla.org/CA/Included_Certificates) by default, which is trusted by {{{ .starter }}}. +> 但你**不需要**通过 `TIDB_CA_PATH` 指定 SSL CA 证书，因为 Node.js 默认使用内置的 [Mozilla CA 证书](https://wiki.mozilla.org/CA/Included_Certificates)，该证书已被 TiDB Cloud Serverless 和 TiDB Cloud Essential 信任。 -### Insert data +### 插入数据 -The following query creates a single `Player` record, and returns the created `Player` object, which contains the `id` field generated by TiDB: +以下查询会创建一条 `Player` 记录，并返回包含 TiDB 生成的 `id` 字段的 `Player` 对象： ```typescript const player = new Player('Alice', 100, 100); await this.dataSource.manager.save(player); ``` -For more information, refer to [Insert data](/develop/dev-guide-insert-data.md). +更多信息参考 [插入数据](/develop/dev-guide-insert-data.md)。 -### Query data +### 查询数据 -The following query returns a single `Player` object with ID 101 or `null` if no record is found: +以下查询会返回 ID 为 101 的 `Player` 对象，如果未找到则返回 `null`： ```typescript const player: Player | null = await this.dataSource.manager.findOneBy(Player, { @@ -301,11 +301,11 @@ const player: Player | null = await this.dataSource.manager.findOneBy(Player, { }); ``` -For more information, refer to [Query data](/develop/dev-guide-get-data-from-single-table.md). +更多信息参考 [查询数据](/develop/dev-guide-get-data-from-single-table.md)。 -### Update data +### 更新数据 -The following query adds `50` goods to the `Player` with ID `101`: +以下查询会为 ID 为 `101` 的 `Player` 增加 `50` 个 goods： ```typescript const player = await this.dataSource.manager.findOneBy(Player, { @@ -315,11 +315,11 @@ player.goods += 50; await this.dataSource.manager.save(player); ``` -For more information, refer to [Update data](/develop/dev-guide-update-data.md). +更多信息参考 [更新数据](/develop/dev-guide-update-data.md)。 -### Delete data +### 删除数据 -The following query deletes the `Player` with ID `101`: +以下查询会删除 ID 为 `101` 的 `Player`： ```typescript await this.dataSource.manager.delete(Player, { @@ -327,26 +327,26 @@ await this.dataSource.manager.delete(Player, { }); ``` -For more information, refer to [Delete data](/develop/dev-guide-delete-data.md). +更多信息参考 [删除数据](/develop/dev-guide-delete-data.md)。 -### Execute raw SQL queries +### 执行原生 SQL 查询 -The following query executes a raw SQL statement (`SELECT VERSION() AS tidb_version;`) and returns the version of the TiDB cluster: +以下查询会执行一条原生 SQL 语句（`SELECT VERSION() AS tidb_version;`），并返回 TiDB 集群的版本号： ```typescript const rows = await dataSource.query('SELECT VERSION() AS tidb_version;'); console.log(rows[0]['tidb_version']); ``` -For more information, refer to [TypeORM: DataSource API](https://typeorm.io/data-source-api). +更多信息参考 [TypeORM: DataSource API](https://typeorm.io/data-source-api)。 -## Useful notes +## 实用说明 -### Foreign key constraints +### 外键约束 -Using [foreign key constraints](https://docs.pingcap.com/tidb/stable/foreign-key) ensures the [referential integrity](https://en.wikipedia.org/wiki/Referential_integrity) of data by adding checks on the database side. However, this might lead to serious performance issues in scenarios with large data volumes. +使用 [外键约束](https://docs.pingcap.com/tidb/stable/foreign-key) 可以通过在数据库端增加校验，保证数据的 [引用完整性](https://en.wikipedia.org/wiki/Referential_integrity)。但在大数据量场景下，可能会带来严重的性能问题。 -You can control whether foreign key constraints are created when constructing relationships between entities by using the `createForeignKeyConstraints` option (default value is `true`). +你可以通过 `createForeignKeyConstraints` 选项（默认值为 `true`）控制在实体间建立关系时是否创建外键约束。 ```typescript @Entity() @@ -361,24 +361,24 @@ export class ActionLog { } ``` -For more information, refer to the [TypeORM FAQ](https://typeorm.io/relations-faq#avoid-foreign-key-constraint-creation) and [Foreign key constraints](https://docs.pingcap.com/tidbcloud/foreign-key#foreign-key-constraints). +更多信息参考 [TypeORM FAQ](https://typeorm.io/relations-faq#avoid-foreign-key-constraint-creation) 以及 [外键约束](https://docs.pingcap.com/tidbcloud/foreign-key#foreign-key-constraints)。 -## Next steps +## 后续步骤 -- Learn more usage of TypeORM from the [documentation of TypeORM](https://typeorm.io/). -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as: [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Query data](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. +- 通过 [TypeORM 官方文档](https://typeorm.io/) 学习更多 TypeORM 的用法。 +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节，学习 TiDB 应用开发最佳实践，例如：[插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[查询数据](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md)、[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/)，考试通过后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +欢迎在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +欢迎在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](https://tidb.support.pingcap.com/)。 diff --git a/develop/dev-guide-sample-application-python-django.md b/develop/dev-guide-sample-application-python-django.md index 1b88310d22689..263129cf6a435 100644 --- a/develop/dev-guide-sample-application-python-django.md +++ b/develop/dev-guide-sample-application-python-django.md @@ -1,113 +1,113 @@ --- -title: Connect to TiDB with Django -summary: Learn how to connect to TiDB using Django. This tutorial gives Python sample code snippets that work with TiDB using Django. +title: 使用 Django 连接 TiDB +summary: 学习如何使用 Django 连接 TiDB。本教程提供了可与 TiDB 搭配使用的 Python 示例代码片段。 --- -# Connect to TiDB with Django +# 使用 Django 连接 TiDB -TiDB is a MySQL-compatible database, and [Django](https://www.djangoproject.com) is a popular web framework for Python, which includes a powerful Object Relational Mapper (ORM) library. +TiDB 是一个兼容 MySQL 的数据库，[Django](https://www.djangoproject.com) 是一个流行的 Python Web 框架，内置了强大的对象关系映射（ORM）库。 -In this tutorial, you can learn how to use TiDB and Django to accomplish the following tasks: +在本教程中，你可以学习如何使用 TiDB 和 Django 完成以下任务： -- Set up your environment. -- Connect to your TiDB cluster using Django. -- Build and run your application. Optionally, you can find sample code snippets for basic CRUD operations. +- 搭建你的开发环境。 +- 使用 Django 连接到你的 TiDB 集群。 +- 构建并运行你的应用程序。你还可以找到基本 CRUD 操作的示例代码片段。 > **Note:** > -> This tutorial works with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed clusters. +> 本教程适用于 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及 TiDB 自建集群。 -## Prerequisites +## 前置条件 -To complete this tutorial, you need: +完成本教程，你需要： -- [Python 3.8 or higher](https://www.python.org/downloads/). -- [Git](https://git-scm.com/downloads). -- A TiDB cluster. +- [Python 3.8 或更高版本](https://www.python.org/downloads/)。 +- [Git](https://git-scm.com/downloads)。 +- 一个 TiDB 集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md)来创建你自己的 TiDB Cloud 集群。 +- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署生产环境 TiDB 集群](/production-deployment-using-tiup.md)来创建本地集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md)来创建你自己的 TiDB Cloud 集群。 +- 参考[部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster)或[部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup)来创建本地集群。 -## Run the sample app to connect to TiDB +## 运行示例应用并连接 TiDB -This section demonstrates how to run the sample application code and connect to TiDB. +本节演示如何运行示例应用代码并连接到 TiDB。 -### Step 1: Clone the sample app repository +### 步骤 1：克隆示例应用仓库 -Run the following commands in your terminal window to clone the sample code repository: +在终端窗口中运行以下命令，克隆示例代码仓库： ```shell git clone https://github.com/tidb-samples/tidb-python-django-quickstart.git cd tidb-python-django-quickstart ``` -### Step 2: Install dependencies +### 步骤 2：安装依赖 -Run the following command to install the required packages (including Django, django-tidb, and mysqlclient) for the sample app: +运行以下命令，安装示例应用所需的依赖包（包括 Django、django-tidb 和 mysqlclient）： ```shell pip install -r requirements.txt ``` -If you encounter installation issues with mysqlclient, refer to the [mysqlclient official documentation](https://github.com/PyMySQL/mysqlclient#install). +如果在安装 mysqlclient 时遇到问题，请参考 [mysqlclient 官方文档](https://github.com/PyMySQL/mysqlclient#install)。 -#### What is `django-tidb`? +#### 什么是 `django-tidb`？ -`django-tidb` is a TiDB dialect for Django that resolves compatibility issues between TiDB and Django. +`django-tidb` 是 Django 的 TiDB 方言，用于解决 TiDB 与 Django 之间的兼容性问题。 -To install `django-tidb`, choose a version that matches your Django version. For example, if you are using `django==4.2.*`, install `django-tidb==4.2.*`. The minor version does not need to be the same. It is recommended to use the latest minor version. +安装 `django-tidb` 时，请选择与你的 Django 版本相匹配的版本。例如，如果你使用的是 `django==4.2.*`，则安装 `django-tidb==4.2.*`。小版本号无需完全一致，建议使用最新的小版本。 -For more information, refer to [django-tidb repository](https://github.com/pingcap/django-tidb). +更多信息请参考 [django-tidb 仓库](https://github.com/pingcap/django-tidb)。 -### Step 3: Configure connection information +### 步骤 3：配置连接信息 -Connect to your TiDB cluster depending on the TiDB deployment option you've selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确保连接对话框中的配置与你的操作环境一致。 - - **Connection Type** is set to `Public` - - **Branch** is set to `main` - - **Connect With** is set to `General` - - **Operating System** matches your environment. + - **Connection Type** 设置为 `Public` + - **Branch** 设置为 `main` + - **Connect With** 设置为 `General` + - **Operating System** 与你的环境一致 > **Tip:** > - > If your program is running in Windows Subsystem for Linux (WSL), switch to the corresponding Linux distribution. + > 如果你的程序运行在 Windows Subsystem for Linux (WSL) 中，请切换到对应的 Linux 发行版。 -4. Click **Generate Password** to create a random password. +4. 点击 **Generate Password** 生成一个随机密码。 > **Tip:** > - > If you have created a password before, you can either use the original password or click **Reset Password** to generate a new one. + > 如果你之前已经创建过密码，可以继续使用原密码，或点击 **Reset Password** 生成新密码。 -5. Run the following command to copy `.env.example` and rename it to `.env`: +5. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -6. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +6. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例如下： ```dotenv TIDB_HOST='{host}' # e.g. gateway01.ap-northeast-1.prod.aws.tidbcloud.com @@ -118,32 +118,32 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele CA_PATH='{ssl_ca}' # e.g. /etc/ssl/certs/ca-certificates.crt (Debian / Ubuntu / Arch) ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog. + 请务必将 `{}` 占位符替换为连接对话框中获取的连接参数。 - {{{ .starter }}} 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 {{{ .starter }}}](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-clusters) to get the certificate paths for different operating systems. + TiDB Cloud Serverless 要求安全连接。由于 mysqlclient 的 `ssl_mode` 默认是 `PREFERRED`，你无需手动指定 `CA_PATH`，只需留空即可。但如果你有特殊需求需要手动指定 `CA_PATH`，可参考 [TLS 连接到 TiDB Cloud Serverless](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-clusters) 获取不同操作系统的证书路径。 -7. Save the `.env` file. +7. 保存 `.env` 文件。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还未配置 IP 访问列表，请点击 **Configure IP Access List**，或参考 [配置 IP 访问列表](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 进行配置后再首次连接。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息请参考 [连接到你的 TiDB Cloud Dedicated 集群](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Run the following command to copy `.env.example` and rename it to `.env`: +4. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -5. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +5. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例如下： ```dotenv TIDB_HOST='{host}' # e.g. tidb.xxxx.clusters.tidb-cloud.com @@ -154,20 +154,20 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele CA_PATH='{your-downloaded-ca-path}' ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog, and configure `CA_PATH` with the certificate path downloaded in the previous step. + 请务必将 `{}` 占位符替换为连接对话框中获取的连接参数，并将 `CA_PATH` 配置为上一步下载的证书路径。 -6. Save the `.env` file. +6. 保存 `.env` 文件。
-
+
-1. Run the following command to copy `.env.example` and rename it to `.env`: +1. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -2. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +2. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例如下： ```dotenv TIDB_HOST='{tidb_server_host}' @@ -177,53 +177,53 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele TIDB_DB_NAME='test' ``` - Be sure to replace the placeholders `{}` with the connection parameters, and remove the `CA_PATH` line. If you are running TiDB locally, the default host address is `127.0.0.1`, and the password is empty. + 请务必将 `{}` 占位符替换为连接参数，并删除 `CA_PATH` 这一行。如果你在本地运行 TiDB，默认主机地址为 `127.0.0.1`，密码为空。 -3. Save the `.env` file. +3. 保存 `.env` 文件。
-### Step 4: Initialize the database +### 步骤 4：初始化数据库 -In the root directory of the project, run the following command to initialize the database: +在项目根目录下，运行以下命令初始化数据库： ```shell python manage.py migrate ``` -### Step 5: Run the sample application +### 步骤 5：运行示例应用 -1. Run the application in the development mode: +1. 以开发模式运行应用： ```shell python manage.py runserver ``` - The application runs on port `8000` by default. To use a different port, you can append the port number to the command. The following is an example: + 应用默认运行在 `8000` 端口。如需使用其他端口，可在命令后追加端口号。例如： ```shell python manage.py runserver 8080 ``` -2. To access the application, open your browser and go to `http://localhost:8000/`. In the sample application, you can: +2. 访问应用，在浏览器中打开 `http://localhost:8000/`。在示例应用中，你可以： - - Create a new player. - - Bulk create players. - - View all players. - - Update a player. - - Delete a player. - - Trade goods between two players. + - 创建新玩家 + - 批量创建玩家 + - 查看所有玩家 + - 更新玩家信息 + - 删除玩家 + - 在两个玩家之间交易物品 -## Sample code snippets +## 示例代码片段 -You can refer to the following sample code snippets to complete your own application development. +你可以参考以下示例代码片段，完成你自己的应用开发。 -For complete sample code and how to run it, check out the [tidb-samples/tidb-python-django-quickstart](https://github.com/tidb-samples/tidb-python-django-quickstart) repository. +完整示例代码及运行方法请参考 [tidb-samples/tidb-python-django-quickstart](https://github.com/tidb-samples/tidb-python-django-quickstart) 仓库。 -### Connect to TiDB +### 连接 TiDB -In the file `sample_project/settings.py`, add the following configurations: +在 `sample_project/settings.py` 文件中，添加如下配置： ```python DATABASES = { @@ -248,9 +248,9 @@ if TIDB_CA_PATH: } ``` -You need to replace `${tidb_host}`, `${tidb_port}`, `${tidb_user}`, `${tidb_password}`, `${tidb_db_name}`, and `${ca_path}` with the actual values of your TiDB cluster. +你需要将 `${tidb_host}`、`${tidb_port}`、`${tidb_user}`、`${tidb_password}`、`${tidb_db_name}` 和 `${ca_path}` 替换为你的 TiDB 集群的实际值。 -### Define the data model +### 定义数据模型 ```python from django.db import models @@ -263,9 +263,9 @@ class Player(models.Model): updated_at = models.DateTimeField(auto_now=True) ``` -For more information, refer to [Django models](https://docs.djangoproject.com/en/dev/topics/db/models/). +更多信息请参考 [Django models](https://docs.djangoproject.com/en/dev/topics/db/models/)。 -### Insert data +### 插入数据 ```python # insert a single object @@ -279,9 +279,9 @@ Player.objects.bulk_create([ ]) ``` -For more information, refer to [Insert data](/develop/dev-guide-insert-data.md). +更多信息请参考 [插入数据](/develop/dev-guide-insert-data.md)。 -### Query data +### 查询数据 ```python # get a single object @@ -294,9 +294,9 @@ filtered_players = Player.objects.filter(name="player1") all_players = Player.objects.all() ``` -For more information, refer to [Query data](/develop/dev-guide-get-data-from-single-table.md). +更多信息请参考 [查询数据](/develop/dev-guide-get-data-from-single-table.md)。 -### Update data +### 更新数据 ```python # update a single object @@ -308,9 +308,9 @@ player.save() Player.objects.filter(coins=100).update(coins=200) ``` -For more information, refer to [Update data](/develop/dev-guide-update-data.md). +更多信息请参考 [更新数据](/develop/dev-guide-update-data.md)。 -### Delete data +### 删除数据 ```python # delete a single object @@ -321,24 +321,24 @@ player.delete() Player.objects.filter(coins=100).delete() ``` -For more information, refer to [Delete data](/develop/dev-guide-delete-data.md). +更多信息请参考 [删除数据](/develop/dev-guide-delete-data.md)。 -## Next steps +## 后续步骤 -- Learn more usage of Django from [the documentation of Django](https://www.djangoproject.com/). -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Single table reading](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), and [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. +- 通过 [Django 官方文档](https://www.djangoproject.com/) 学习更多 Django 的用法。 +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节学习 TiDB 应用开发最佳实践，例如 [插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md) 以及 [SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/)学习，并在通过考试后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或[提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或[提交支持工单](https://tidb.support.pingcap.com/)。 diff --git a/develop/dev-guide-sample-application-python-mysql-connector.md b/develop/dev-guide-sample-application-python-mysql-connector.md index 8d8c6ee24e61c..491b79bc10bf2 100644 --- a/develop/dev-guide-sample-application-python-mysql-connector.md +++ b/develop/dev-guide-sample-application-python-mysql-connector.md @@ -1,103 +1,103 @@ --- -title: Connect to TiDB with MySQL Connector/Python -summary: Learn how to connect to TiDB using MySQL Connector/Python. This tutorial gives Python sample code snippets that work with TiDB using MySQL Connector/Python. +title: 使用 MySQL Connector/Python 连接 TiDB +summary: 学习如何使用 MySQL Connector/Python 连接 TiDB。本教程提供了可用于 TiDB 的 Python 示例代码片段，基于 MySQL Connector/Python。 --- -# Connect to TiDB with MySQL Connector/Python +# 使用 MySQL Connector/Python 连接 TiDB -TiDB is a MySQL-compatible database, and [MySQL Connector/Python](https://dev.mysql.com/doc/connector-python/en/) is the official MySQL driver for Python. +TiDB 是兼容 MySQL 的数据库，[MySQL Connector/Python](https://dev.mysql.com/doc/connector-python/en/) 是官方提供的 Python MySQL 驱动。 -In this tutorial, you can learn how to use TiDB and MySQL Connector/Python to accomplish the following tasks: +在本教程中，你可以学习如何使用 TiDB 和 MySQL Connector/Python 完成以下任务： -- Set up your environment. -- Connect to your TiDB cluster using MySQL Connector/Python. -- Build and run your application. Optionally, you can find sample code snippets for basic CRUD operations. +- 搭建你的开发环境。 +- 使用 MySQL Connector/Python 连接到你的 TiDB 集群。 +- 构建并运行你的应用程序。你还可以找到用于基本 CRUD 操作的示例代码片段。 > **Note:** > -> This tutorial works with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed clusters. +> 本教程适用于 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及 TiDB 自建集群。 -## Prerequisites +## 前置条件 -To complete this tutorial, you need: +完成本教程，你需要： -- [Python 3.8 or higher](https://www.python.org/downloads/). -- [Git](https://git-scm.com/downloads). -- A TiDB cluster. +- [Python 3.8 或更高版本](https://www.python.org/downloads/)。 +- [Git](https://git-scm.com/downloads)。 +- 一个 TiDB 集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](/production-deployment-using-tiup.md) 创建本地集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) 创建本地集群。 -## Run the sample app to connect to TiDB +## 运行示例应用连接 TiDB -This section demonstrates how to run the sample application code and connect to TiDB. +本节演示如何运行示例应用代码并连接到 TiDB。 -### Step 1: Clone the sample app repository +### 步骤 1：克隆示例应用仓库 -Run the following commands in your terminal window to clone the sample code repository: +在终端窗口中运行以下命令，克隆示例代码仓库： ```shell git clone https://github.com/tidb-samples/tidb-python-mysqlconnector-quickstart.git cd tidb-python-mysqlconnector-quickstart ``` -### Step 2: Install dependencies +### 步骤 2：安装依赖 -Run the following command to install the required packages (including mysql-connector-python) for the sample app: +运行以下命令，为示例应用安装所需的依赖包（包括 mysql-connector-python）： ```shell pip install -r requirements.txt ``` -### Step 3: Configure connection information +### 步骤 3：配置连接信息 -Connect to your TiDB cluster depending on the TiDB deployment option you've selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称，进入集群概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确保连接对话框中的配置与你的操作环境一致。 - - **Connection Type** is set to `Public` - - **Branch** is set to `main` - - **Connect With** is set to `General` - - **Operating System** matches your environment. + - **Connection Type** 设置为 `Public` + - **Branch** 设置为 `main` + - **Connect With** 设置为 `General` + - **Operating System** 与你的环境一致 > **Tip:** > - > If your program is running in Windows Subsystem for Linux (WSL), switch to the corresponding Linux distribution. + > 如果你的程序运行在 Windows Subsystem for Linux (WSL) 中，请切换到对应的 Linux 发行版。 -4. Click **Generate Password** to create a random password. +4. 点击 **Generate Password** 生成随机密码。 > **Tip:** > - > If you have created a password before, you can either use the original password or click **Reset Password** to generate a new one. + > 如果你之前已经创建过密码，可以继续使用原密码，或点击 **Reset Password** 生成新密码。 -5. Run the following command to copy `.env.example` and rename it to `.env`: +5. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： ```shell cp .env.example .env ``` -6. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +6. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例结果如下： ```dotenv TIDB_HOST='{host}' # e.g. gateway01.ap-northeast-1.prod.aws.tidbcloud.com @@ -108,30 +108,30 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele CA_PATH='{ssl_ca}' # e.g. /etc/ssl/certs/ca-certificates.crt (Debian / Ubuntu / Arch) ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog. + 请务必将 `{}` 占位符替换为连接对话框中获取的连接参数。 -7. Save the `.env` file. +7. 保存 `.env` 文件。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称，进入集群概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还未配置 IP 访问列表，请点击 **Configure IP Access List**，或参考 [配置 IP 访问列表](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 进行配置，以便首次连接。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息请参考 [连接到你的 TiDB Cloud Dedicated 集群](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Run the following command to copy `.env.example` and rename it to `.env`: +4. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： ```shell cp .env.example .env ``` -5. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +5. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例结果如下： ```dotenv TIDB_HOST='{host}' # e.g. tidb.xxxx.clusters.tidb-cloud.com @@ -142,20 +142,20 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele CA_PATH='{your-downloaded-ca-path}' ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog, and configure `CA_PATH` with the certificate path downloaded in the previous step. + 请务必将 `{}` 占位符替换为连接对话框中获取的连接参数，并将 `CA_PATH` 配置为上一步下载的证书路径。 -6. Save the `.env` file. +6. 保存 `.env` 文件。
-1. Run the following command to copy `.env.example` and rename it to `.env`: +1. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： ```shell cp .env.example .env ``` -2. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +2. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例结果如下： ```dotenv TIDB_HOST='{tidb_server_host}' @@ -165,30 +165,30 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele TIDB_DB_NAME='test' ``` - Be sure to replace the placeholders `{}` with the connection parameters, and remove the `CA_PATH` line. If you are running TiDB locally, the default host address is `127.0.0.1`, and the password is empty. + 请务必将 `{}` 占位符替换为连接参数，并删除 `CA_PATH` 这一行。如果你在本地运行 TiDB，默认主机地址为 `127.0.0.1`，密码为空。 -3. Save the `.env` file. +3. 保存 `.env` 文件。
-### Step 4: Run the code and check the result +### 步骤 4：运行代码并检查结果 -1. Execute the following command to run the sample code: +1. 执行以下命令运行示例代码： ```shell python mysql_connector_example.py ``` -2. Check the [Expected-Output.txt](https://github.com/tidb-samples/tidb-python-mysqlconnector-quickstart/blob/main/Expected-Output.txt) to see if the output matches. +2. 检查 [Expected-Output.txt](https://github.com/tidb-samples/tidb-python-mysqlconnector-quickstart/blob/main/Expected-Output.txt) 文件，确认输出是否一致。 -## Sample code snippets +## 示例代码片段 -You can refer to the following sample code snippets to complete your own application development. +你可以参考以下示例代码片段，完成你自己的应用开发。 -For complete sample code and how to run it, check out the [tidb-samples/tidb-python-mysqlconnector-quickstart](https://github.com/tidb-samples/tidb-python-mysqlconnector-quickstart) repository. +完整示例代码及运行方法请参考 [tidb-samples/tidb-python-mysqlconnector-quickstart](https://github.com/tidb-samples/tidb-python-mysqlconnector-quickstart) 仓库。 -### Connect to TiDB +### 连接 TiDB ```python def get_connection(autocommit: bool = True) -> MySQLConnection: @@ -210,9 +210,9 @@ def get_connection(autocommit: bool = True) -> MySQLConnection: return mysql.connector.connect(**db_conf) ``` -When using this function, you need to replace `${tidb_host}`, `${tidb_port}`, `${tidb_user}`, `${tidb_password}`, `${tidb_db_name}` and `${ca_path}` with the actual values of your TiDB cluster. +使用该函数时，需要将 `${tidb_host}`、`${tidb_port}`、`${tidb_user}`、`${tidb_password}`、`${tidb_db_name}` 和 `${ca_path}` 替换为你 TiDB 集群的实际值。 -### Insert data +### 插入数据 ```python with get_connection(autocommit=True) as conn: @@ -221,9 +221,9 @@ with get_connection(autocommit=True) as conn: cursor.execute("INSERT INTO players (id, coins, goods) VALUES (%s, %s, %s)", player) ``` -For more information, refer to [Insert data](/develop/dev-guide-insert-data.md). +更多信息请参考 [插入数据](/develop/dev-guide-insert-data.md)。 -### Query data +### 查询数据 ```python with get_connection(autocommit=True) as conn: @@ -232,9 +232,9 @@ with get_connection(autocommit=True) as conn: print(cur.fetchone()[0]) ``` -For more information, refer to [Query data](/develop/dev-guide-get-data-from-single-table.md). +更多信息请参考 [查询数据](/develop/dev-guide-get-data-from-single-table.md)。 -### Update data +### 更新数据 ```python with get_connection(autocommit=True) as conn: @@ -246,9 +246,9 @@ with get_connection(autocommit=True) as conn: ) ``` -For more information, refer to [Update data](/develop/dev-guide-update-data.md). +更多信息请参考 [更新数据](/develop/dev-guide-update-data.md)。 -### Delete data +### 删除数据 ```python with get_connection(autocommit=True) as conn: @@ -257,39 +257,39 @@ with get_connection(autocommit=True) as conn: cursor.execute("DELETE FROM players WHERE id = %s", (player_id,)) ``` -For more information, refer to [Delete data](/develop/dev-guide-delete-data.md). +更多信息请参考 [删除数据](/develop/dev-guide-delete-data.md)。 -## Useful notes +## 实用说明 -### Using driver or ORM framework? +### 使用驱动还是 ORM 框架？ -The Python driver provides low-level access to the database, but it requires the developers to: +Python 驱动提供了对数据库的底层访问，但这要求开发者： -- Manually establish and release database connections. -- Manually manage database transactions. -- Manually map data rows (represented as a tuple or dict in `mysql-connector-python`) to data objects. +- 手动建立和释放数据库连接。 +- 手动管理数据库事务。 +- 手动将数据行（在 `mysql-connector-python` 中表现为元组或字典）映射为数据对象。 -Unless you need to write complex SQL statements, it is recommended to use [ORM](https://en.wikipedia.org/w/index.php?title=Object-relational_mapping) framework for development, such as [SQLAlchemy](/develop/dev-guide-sample-application-python-sqlalchemy.md), [Peewee](/develop/dev-guide-sample-application-python-peewee.md), and Django ORM. It can help you: +除非你需要编写复杂的 SQL 语句，否则推荐使用 [ORM](https://en.wikipedia.org/w/index.php?title=Object-relational_mapping) 框架进行开发，例如 [SQLAlchemy](/develop/dev-guide-sample-application-python-sqlalchemy.md)、[Peewee](/develop/dev-guide-sample-application-python-peewee.md) 和 Django ORM。这样可以帮助你： -- Reduce [boilerplate code](https://en.wikipedia.org/wiki/Boilerplate_code) for managing connections and transactions. -- Manipulate data with data objects instead of a number of SQL statements. +- 减少用于管理连接和事务的 [样板代码](https://en.wikipedia.org/wiki/Boilerplate_code)。 +- 通过数据对象操作数据，而不是大量 SQL 语句。 -## Next steps +## 后续步骤 -- Learn more usage of mysql-connector-python from [the documentation of MySQL Connector/Python](https://dev.mysql.com/doc/connector-python/en/). -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Single table reading](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), and [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. +- 通过 [MySQL Connector/Python 官方文档](https://dev.mysql.com/doc/connector-python/en/) 学习更多 mysql-connector-python 的用法。 +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节，学习 TiDB 应用开发最佳实践，例如 [插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md) 以及 [SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/) 学习，并在通过考试后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](https://tidb.support.pingcap.com/)。 diff --git a/develop/dev-guide-sample-application-python-mysqlclient.md b/develop/dev-guide-sample-application-python-mysqlclient.md index a8e17e36f5cf0..29dbf701d388a 100644 --- a/develop/dev-guide-sample-application-python-mysqlclient.md +++ b/develop/dev-guide-sample-application-python-mysqlclient.md @@ -1,105 +1,105 @@ --- -title: Connect to TiDB with mysqlclient -summary: Learn how to connect to TiDB using mysqlclient. This tutorial gives Python sample code snippets that work with TiDB using mysqlclient. +title: 使用 mysqlclient 连接 TiDB +summary: 学习如何使用 mysqlclient 连接 TiDB。本教程提供了可与 TiDB 搭配使用的 Python 代码示例片段。 --- -# Connect to TiDB with mysqlclient +# 使用 mysqlclient 连接 TiDB -TiDB is a MySQL-compatible database, and [mysqlclient](https://github.com/PyMySQL/mysqlclient) is a popular open-source driver for Python. +TiDB 是一个兼容 MySQL 的数据库，[mysqlclient](https://github.com/PyMySQL/mysqlclient) 是 Python 中流行的开源驱动程序。 -In this tutorial, you can learn how to use TiDB and mysqlclient to accomplish the following tasks: +在本教程中，你可以学习如何使用 TiDB 和 mysqlclient 完成以下任务： -- Set up your environment. -- Connect to your TiDB cluster using mysqlclient. -- Build and run your application. Optionally, you can find sample code snippets for basic CRUD operations. +- 搭建你的环境。 +- 使用 mysqlclient 连接到你的 TiDB 集群。 +- 构建并运行你的应用程序。你还可以找到基本 CRUD 操作的代码示例片段。 > **Note:** > -> This tutorial works with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed. +> 本教程适用于 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及 TiDB 自建集群。 -## Prerequisites +## 前置条件 -To complete this tutorial, you need: +完成本教程，你需要： -- [Python **3.10** or higher](https://www.python.org/downloads/). -- [Git](https://git-scm.com/downloads). -- A TiDB cluster. +- [Python **3.10** 或更高版本](https://www.python.org/downloads/)。 +- [Git](https://git-scm.com/downloads)。 +- 一个 TiDB 集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参照[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md)来创建你自己的 TiDB Cloud 集群。 +- 参照[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署生产环境 TiDB 集群](/production-deployment-using-tiup.md)来创建本地集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参照[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md)来创建你自己的 TiDB Cloud 集群。 +- 参照[部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster)或[部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup)来创建本地集群。 -## Run the sample app to connect to TiDB +## 运行示例应用连接 TiDB -This section demonstrates how to run the sample application code and connect to TiDB. +本节演示如何运行示例应用代码并连接到 TiDB。 -### Step 1: Clone the sample app repository +### 步骤 1：克隆示例应用仓库 -Run the following commands in your terminal window to clone the sample code repository: +在终端窗口中运行以下命令，克隆示例代码仓库： ```shell git clone https://github.com/tidb-samples/tidb-python-mysqlclient-quickstart.git cd tidb-python-mysqlclient-quickstart; ``` -### Step 2: Install dependencies +### 步骤 2：安装依赖 -Run the following command to install the required packages (including `mysqlclient`) for the sample app: +运行以下命令安装示例应用所需的依赖包（包括 `mysqlclient`）： ```shell pip install -r requirements.txt ``` -If you encounter installation issues, refer to the [mysqlclient official documentation](https://github.com/PyMySQL/mysqlclient#install). +如果你在安装过程中遇到问题，请参考 [mysqlclient 官方文档](https://github.com/PyMySQL/mysqlclient#install)。 -### Step 3: Configure connection information +### 步骤 3：配置连接信息 -Connect to your TiDB cluster depending on the TiDB deployment option you've selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，然后点击目标集群名称，进入其概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确保连接对话框中的配置与你的操作环境一致。 - - **Connection Type** is set to `Public` - - **Branch** is set to `main` - - **Connect With** is set to `General` - - **Operating System** matches your environment. + - **Connection Type** 设置为 `Public` + - **Branch** 设置为 `main` + - **Connect With** 设置为 `General` + - **Operating System** 与你的环境一致 > **Tip:** > - > If your program is running in Windows Subsystem for Linux (WSL), switch to the corresponding Linux distribution. + > 如果你的程序运行在 Windows Subsystem for Linux (WSL) 中，请切换到对应的 Linux 发行版。 -4. Click **Generate Password** to create a random password. +4. 点击 **Generate Password** 生成一个随机密码。 > **Tip:** > - > If you have created a password before, you can either use the original password or click **Reset Password** to generate a new one. + > 如果你之前已经创建过密码，可以继续使用原密码，或者点击 **Reset Password** 生成新密码。 -5. Run the following command to copy `.env.example` and rename it to `.env`: +5. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -6. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +6. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例结果如下： ```dotenv TIDB_HOST='{gateway-region}.aws.tidbcloud.com' @@ -110,32 +110,32 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele CA_PATH='' ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog. + 请务必将 `{}` 占位符替换为你在连接对话框中获得的连接参数。 - {{{ .starter }}} 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 {{{ .starter }}}](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-clusters) to get the certificate paths for different operating systems. + TiDB Cloud Serverless 需要安全连接。由于 mysqlclient 的 `ssl_mode` 默认是 `PREFERRED`，你无需手动指定 `CA_PATH`，保持为空即可。但如果你有特殊需求需要手动指定 `CA_PATH`，可以参考 [TLS 连接到 TiDB Cloud Serverless](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-clusters) 获取不同操作系统下的证书路径。 -7. Save the `.env` file. +7. 保存 `.env` 文件。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，然后点击目标集群名称，进入其概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还未配置 IP 访问列表，请点击 **Configure IP Access List**，或参照 [配置 IP 访问列表](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 完成首次连接前的配置。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息请参见 [连接到你的 TiDB Cloud Dedicated 集群](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Run the following command to copy `.env.example` and rename it to `.env`: +4. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -5. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +5. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例结果如下： ```dotenv TIDB_HOST='{host}.clusters.tidb-cloud.com' @@ -146,20 +146,20 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele CA_PATH='{your-downloaded-ca-path}' ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog, and configure `CA_PATH` with the certificate path downloaded in the previous step. + 请务必将 `{}` 占位符替换为你在连接对话框中获得的连接参数，并将 `CA_PATH` 配置为上一步下载的证书路径。 -6. Save the `.env` file. +6. 保存 `.env` 文件。
-
+
-1. Run the following command to copy `.env.example` and rename it to `.env`: +1. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -2. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +2. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例结果如下： ```dotenv TIDB_HOST='{tidb_server_host}' @@ -169,30 +169,30 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele TIDB_DB_NAME='test' ``` - Be sure to replace the placeholders `{}` with the connection parameters, and remove the `CA_PATH` line. If you are running TiDB locally, the default host address is `127.0.0.1`, and the password is empty. + 请务必将 `{}` 占位符替换为你的连接参数，并删除 `CA_PATH` 这一行。如果你在本地运行 TiDB，默认主机地址为 `127.0.0.1`，密码为空。 -3. Save the `.env` file. +3. 保存 `.env` 文件。
-### Step 4: Run the code and check the result +### 步骤 4：运行代码并检查结果 -1. Execute the following command to run the sample code: +1. 执行以下命令运行示例代码： ```shell python mysqlclient_example.py ``` -2. Check the [Expected-Output.txt](https://github.com/tidb-samples/tidb-python-mysqlclient-quickstart/blob/main/Expected-Output.txt) to see if the output matches. +2. 检查 [Expected-Output.txt](https://github.com/tidb-samples/tidb-python-mysqlclient-quickstart/blob/main/Expected-Output.txt) 文件，确认输出是否一致。 -## Sample code snippets +## 代码示例片段 -You can refer to the following sample code snippets to complete your own application development. +你可以参考以下代码示例片段，完成你自己的应用开发。 -For complete sample code and how to run it, check out the [tidb-samples/tidb-python-mysqlclient-quickstart](https://github.com/tidb-samples/tidb-python-mysqlclient-quickstart) repository. +完整示例代码及运行方法请参考 [tidb-samples/tidb-python-mysqlclient-quickstart](https://github.com/tidb-samples/tidb-python-mysqlclient-quickstart) 仓库。 -### Connect to TiDB +### 连接 TiDB ```python def get_mysqlclient_connection(autocommit:bool=True) -> MySQLdb.Connection: @@ -212,9 +212,9 @@ def get_mysqlclient_connection(autocommit:bool=True) -> MySQLdb.Connection: return MySQLdb.connect(**db_conf) ``` -When using this function, you need to replace `${tidb_host}`, `${tidb_port}`, `${tidb_user}`, `${tidb_password}`, `${tidb_db_name}` and `${ca_path}` with the actual values of your TiDB cluster. +使用该函数时，你需要将 `${tidb_host}`、`${tidb_port}`、`${tidb_user}`、`${tidb_password}`、`${tidb_db_name}` 和 `${ca_path}` 替换为你 TiDB 集群的实际值。 -### Insert data +### 插入数据 ```python with get_mysqlclient_connection(autocommit=True) as conn: @@ -223,9 +223,9 @@ with get_mysqlclient_connection(autocommit=True) as conn: cursor.execute("INSERT INTO players (id, coins, goods) VALUES (%s, %s, %s)", player) ``` -For more information, refer to [Insert data](/develop/dev-guide-insert-data.md). +更多信息请参考 [插入数据](/develop/dev-guide-insert-data.md)。 -### Query data +### 查询数据 ```python with get_mysqlclient_connection(autocommit=True) as conn: @@ -234,9 +234,9 @@ with get_mysqlclient_connection(autocommit=True) as conn: print(cur.fetchone()[0]) ``` -For more information, refer to [Query data](/develop/dev-guide-get-data-from-single-table.md). +更多信息请参考 [查询数据](/develop/dev-guide-get-data-from-single-table.md)。 -### Update data +### 更新数据 ```python with get_mysqlclient_connection(autocommit=True) as conn: @@ -248,9 +248,9 @@ with get_mysqlclient_connection(autocommit=True) as conn: ) ``` -For more information, refer to [Update data](/develop/dev-guide-update-data.md). +更多信息请参考 [更新数据](/develop/dev-guide-update-data.md)。 -### Delete data +### 删除数据 ```python with get_mysqlclient_connection(autocommit=True) as conn: @@ -259,39 +259,39 @@ with get_mysqlclient_connection(autocommit=True) as conn: cursor.execute("DELETE FROM players WHERE id = %s", (player_id,)) ``` -For more information, refer to [Delete data](/develop/dev-guide-delete-data.md). +更多信息请参考 [删除数据](/develop/dev-guide-delete-data.md)。 -## Useful notes +## 实用说明 -### Using driver or ORM framework? +### 使用驱动还是 ORM 框架？ -The Python driver provides low-level access to the database, but it requires the developers to: +Python 驱动提供了对数据库的底层访问，但这要求开发者： -- Manually establish and release database connections. -- Manually manage database transactions. -- Manually map data rows (represented as tuples in `mysqlclient`) to data objects. +- 手动建立和释放数据库连接。 +- 手动管理数据库事务。 +- 手动将数据行（在 `mysqlclient` 中表现为元组）映射为数据对象。 -Unless you need to write complex SQL statements, it is recommended to use [ORM](https://en.wikipedia.org/w/index.php?title=Object-relational_mapping) framework for development, such as [SQLAlchemy](/develop/dev-guide-sample-application-python-sqlalchemy.md), [Peewee](/develop/dev-guide-sample-application-python-peewee.md), and Django ORM. It can help you: +除非你需要编写复杂的 SQL 语句，否则推荐使用 [ORM](https://en.wikipedia.org/w/index.php?title=Object-relational_mapping) 框架进行开发，例如 [SQLAlchemy](/develop/dev-guide-sample-application-python-sqlalchemy.md)、[Peewee](/develop/dev-guide-sample-application-python-peewee.md) 和 Django ORM。它可以帮助你： -- Reduce [boilerplate code](https://en.wikipedia.org/wiki/Boilerplate_code) for managing connections and transactions. -- Manipulate data with data objects instead of a number of SQL statements. +- 减少管理连接和事务的[样板代码](https://en.wikipedia.org/wiki/Boilerplate_code)。 +- 通过数据对象操作数据，而不是大量 SQL 语句。 -## Next steps +## 后续步骤 -- Learn more usage of `mysqlclient` from [the documentation of mysqlclient](https://mysqlclient.readthedocs.io/). -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Single table reading](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), and [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. +- 通过 [mysqlclient 的文档](https://mysqlclient.readthedocs.io/) 了解更多 `mysqlclient` 的用法。 +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节学习 TiDB 应用开发最佳实践，例如 [插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md) 以及 [SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/)学习，并在通过考试后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或[提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或[提交支持工单](https://tidb.support.pingcap.com/)。 diff --git a/develop/dev-guide-sample-application-python-peewee.md b/develop/dev-guide-sample-application-python-peewee.md index 2c59cd0a3cd5b..3248b5a1a5a6e 100644 --- a/develop/dev-guide-sample-application-python-peewee.md +++ b/develop/dev-guide-sample-application-python-peewee.md @@ -1,107 +1,107 @@ --- -title: Connect to TiDB with peewee -summary: Learn how to connect to TiDB using peewee. This tutorial gives Python sample code snippets that work with TiDB using peewee. +title: 使用 peewee 连接 TiDB +summary: 学习如何使用 peewee 连接 TiDB。本教程提供了适用于 TiDB 的 peewee Python 示例代码片段。 --- -# Connect to TiDB with peewee +# 使用 peewee 连接 TiDB -TiDB is a MySQL-compatible database, and [peewee](https://docs.peewee-orm.com/) is a popular Object Relational Mapper (ORM) for Python. +TiDB 是一个兼容 MySQL 的数据库，[peewee](https://docs.peewee-orm.com/) 是 Python 中流行的对象关系映射（ORM）工具。 -In this tutorial, you can learn how to use TiDB and peewee to accomplish the following tasks: +在本教程中，你可以学习如何使用 TiDB 和 peewee 完成以下任务： -- Set up your environment. -- Connect to your TiDB cluster using peewee. -- Build and run your application. Optionally, you can find sample code snippets for basic CRUD operations. +- 搭建你的开发环境。 +- 使用 peewee 连接到你的 TiDB 集群。 +- 构建并运行你的应用程序。你还可以找到基本 CRUD 操作的示例代码片段。 > **Note:** > -> This tutorial works with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed clusters. +> 本教程适用于 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及 TiDB 自建集群。 -## Prerequisites +## 前置条件 -To complete this tutorial, you need: +完成本教程，你需要： -- [Python 3.8 or higher](https://www.python.org/downloads/). -- [Git](https://git-scm.com/downloads). -- A TiDB cluster. +- [Python 3.8 或更高版本](https://www.python.org/downloads/)。 +- [Git](https://git-scm.com/downloads)。 +- 一个 TiDB 集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参照[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md)来创建你自己的 TiDB Cloud 集群。 +- 参照[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署生产环境 TiDB 集群](/production-deployment-using-tiup.md)来创建本地集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参照[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md)来创建你自己的 TiDB Cloud 集群。 +- 参照[部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster)或[部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup)来创建本地集群。 -## Run the sample app to connect to TiDB +## 运行示例应用连接 TiDB -This section demonstrates how to run the sample application code and connect to TiDB. +本节演示如何运行示例应用代码并连接到 TiDB。 -### Step 1: Clone the sample app repository +### 步骤 1：克隆示例应用仓库 -Run the following commands in your terminal window to clone the sample code repository: +在终端窗口中运行以下命令，克隆示例代码仓库： ```shell git clone https://github.com/tidb-samples/tidb-python-peewee-quickstart.git cd tidb-python-peewee-quickstart ``` -### Step 2: Install dependencies +### 步骤 2：安装依赖 -Run the following command to install the required packages (including peewee and PyMySQL) for the sample app: +运行以下命令，安装示例应用所需的依赖包（包括 peewee 和 PyMySQL）： ```shell pip install -r requirements.txt ``` -#### Why use PyMySQL? +#### 为什么使用 PyMySQL？ -peewee is an ORM library that works with multiple databases. It provides a high-level abstraction of the database, which helps developers write SQL statements in a more object-oriented way. However, peewee does not include a database driver. To connect to a database, you need to install a database driver. This sample application uses PyMySQL as the database driver, which is a pure Python MySQL client library that is compatible with TiDB and can be installed on all platforms. For more information, refer to [peewee official documentation](https://docs.peewee-orm.com/en/latest/peewee/database.html?highlight=mysql#using-mysql). +peewee 是一个支持多种数据库的 ORM 库。它为数据库提供了高级抽象，帮助开发者以更面向对象的方式编写 SQL 语句。但 peewee 并不自带数据库驱动。要连接数据库，你需要安装数据库驱动。本示例应用使用 PyMySQL 作为数据库驱动，它是一个纯 Python 的 MySQL 客户端库，兼容 TiDB，并可在所有平台上安装。更多信息请参考 [peewee 官方文档](https://docs.peewee-orm.com/en/latest/peewee/database.html?highlight=mysql#using-mysql)。 -### Step 3: Configure connection information +### 步骤 3：配置连接信息 -Connect to your TiDB cluster depending on the TiDB deployment option you've selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://{{{.console-url}}}/project/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确保连接对话框中的配置与你的操作环境一致。 - - **Connection Type** is set to `Public` - - **Branch** is set to `main` - - **Connect With** is set to `General` - - **Operating System** matches your environment. + - **Connection Type** 设置为 `Public` + - **Branch** 设置为 `main` + - **Connect With** 设置为 `General` + - **Operating System** 与你的环境一致 > **Tip:** > - > If your program is running in Windows Subsystem for Linux (WSL), switch to the corresponding Linux distribution. + > 如果你的程序运行在 Windows Subsystem for Linux (WSL) 中，请切换到对应的 Linux 发行版。 -4. Click **Generate Password** to create a random password. +4. 点击 **Generate Password** 生成随机密码。 > **Tip:** > - > If you have created a password before, you can either use the original password or click **Reset Password** to generate a new one. + > 如果你之前已经创建过密码，可以继续使用原密码，或点击 **Reset Password** 生成新密码。 -5. Run the following command to copy `.env.example` and rename it to `.env`: +5. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -6. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +6. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例结果如下： ```dotenv TIDB_HOST='{host}' # e.g. gateway01.ap-northeast-1.prod.aws.tidbcloud.com @@ -112,30 +112,30 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele CA_PATH='{ssl_ca}' # e.g. /etc/ssl/certs/ca-certificates.crt (Debian / Ubuntu / Arch) ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog. + 请务必将 `{}` 占位符替换为连接对话框中获取的连接参数。 -7. Save the `.env` file. +7. 保存 `.env` 文件。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还未配置 IP 访问列表，请点击 **Configure IP Access List** 或参照 [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 完成配置后再进行首次连接。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息请参见 [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Run the following command to copy `.env.example` and rename it to `.env`: +4. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -5. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +5. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例结果如下： ```dotenv TIDB_HOST='{host}' # e.g. tidb.xxxx.clusters.tidb-cloud.com @@ -146,20 +146,20 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele CA_PATH='{your-downloaded-ca-path}' ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog, and configure `CA_PATH` with the certificate path downloaded in the previous step. + 请务必将 `{}` 占位符替换为连接对话框中获取的连接参数，并将 `CA_PATH` 配置为上一步下载的证书路径。 -6. Save the `.env` file. +6. 保存 `.env` 文件。
-
+
-1. Run the following command to copy `.env.example` and rename it to `.env`: +1. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -2. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +2. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例结果如下： ```dotenv TIDB_HOST='{tidb_server_host}' @@ -169,30 +169,30 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele TIDB_DB_NAME='test' ``` - Be sure to replace the placeholders `{}` with the connection parameters, and remove the `CA_PATH` line. If you are running TiDB locally, the default host address is `127.0.0.1`, and the password is empty. + 请务必将 `{}` 占位符替换为连接参数，并删除 `CA_PATH` 这一行。如果你在本地运行 TiDB，默认主机地址为 `127.0.0.1`，密码为空。 -3. Save the `.env` file. +3. 保存 `.env` 文件。
-### Step 4: Run the code and check the result +### 步骤 4：运行代码并检查结果 -1. Execute the following command to run the sample code: +1. 执行以下命令运行示例代码： ```shell python peewee_example.py ``` -2. Check the [Expected-Output.txt](https://github.com/tidb-samples/tidb-python-peewee-quickstart/blob/main/Expected-Output.txt) to see if the output matches. +2. 检查 [Expected-Output.txt](https://github.com/tidb-samples/tidb-python-peewee-quickstart/blob/main/Expected-Output.txt) 文件，确认输出是否一致。 -## Sample code snippets +## 示例代码片段 -You can refer to the following sample code snippets to complete your own application development. +你可以参考以下示例代码片段，完成你自己的应用开发。 -For complete sample code and how to run it, check out the [tidb-samples/tidb-python-peewee-quickstart](https://github.com/tidb-samples/tidb-python-peewee-quickstart) repository. +完整示例代码及运行方法请参见 [tidb-samples/tidb-python-peewee-quickstart](https://github.com/tidb-samples/tidb-python-peewee-quickstart) 仓库。 -### Connect to TiDB +### 连接 TiDB ```python from peewee import MySQLDatabase @@ -216,9 +216,9 @@ def get_db_engine(): ) ``` -When using this function, you need to replace `${tidb_host}`, `${tidb_port}`, `${tidb_user}`, `${tidb_password}`, `${tidb_db_name}` and `${ca_path}` with the actual values of your TiDB cluster. +使用该函数时，你需要将 `${tidb_host}`、`${tidb_port}`、`${tidb_user}`、`${tidb_password}`、`${tidb_db_name}` 和 `${ca_path}` 替换为你 TiDB 集群的实际值。 -### Define a table +### 定义数据表 ```python from peewee import Model, CharField, IntegerField @@ -238,15 +238,15 @@ class Player(BaseModel): table_name = "players" ``` -For more information, refer to [peewee documentation: Models and Fields](https://docs.peewee-orm.com/en/latest/peewee/models.html). +更多信息请参考 [peewee 文档：Models and Fields](https://docs.peewee-orm.com/en/latest/peewee/models.html)。 -### Insert data +### 插入数据 ```python -# Insert a single record +# 插入单条记录 Player.create(name="test", coins=100, goods=100) -# Insert multiple records +# 插入多条记录 Player.insert_many( [ {"name": "test1", "coins": 100, "goods": 100}, @@ -255,66 +255,66 @@ Player.insert_many( ).execute() ``` -For more information, refer to [Insert data](/develop/dev-guide-insert-data.md). +更多信息请参考 [插入数据](/develop/dev-guide-insert-data.md)。 -### Query data +### 查询数据 ```python -# Query all records +# 查询所有记录 players = Player.select() -# Query a single record +# 查询单条记录 player = Player.get(Player.name == "test") -# Query multiple records +# 查询多条记录 players = Player.select().where(Player.coins == 100) ``` -For more information, refer to [Query data](/develop/dev-guide-get-data-from-single-table.md). +更多信息请参考 [查询数据](/develop/dev-guide-get-data-from-single-table.md)。 -### Update data +### 更新数据 ```python -# Update a single record +# 更新单条记录 player = Player.get(Player.name == "test") player.coins = 200 player.save() -# Update multiple records +# 更新多条记录 Player.update(coins=200).where(Player.coins == 100).execute() ``` -For more information, refer to [Update data](/develop/dev-guide-update-data.md). +更多信息请参考 [更新数据](/develop/dev-guide-update-data.md)。 -### Delete data +### 删除数据 ```python -# Delete a single record +# 删除单条记录 player = Player.get(Player.name == "test") player.delete_instance() -# Delete multiple records +# 删除多条记录 Player.delete().where(Player.coins == 100).execute() ``` -For more information, refer to [Delete data](/develop/dev-guide-delete-data.md). +更多信息请参考 [删除数据](/develop/dev-guide-delete-data.md)。 -## Next steps +## 后续步骤 -- Learn more usage of peewee from [the documentation of peewee](https://docs.peewee-orm.com/). -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Single table reading](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), and [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. +- 通过 [peewee 官方文档](https://docs.peewee-orm.com/) 学习更多 peewee 的用法。 +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节，学习 TiDB 应用开发最佳实践，例如 [插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md) 以及 [SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/)，考试通过后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或[提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或[提交支持工单](https://tidb.support.pingcap.com/)。 diff --git a/develop/dev-guide-sample-application-python-pymysql.md b/develop/dev-guide-sample-application-python-pymysql.md index f1f7876d11e6a..39fc1e3ed12a3 100644 --- a/develop/dev-guide-sample-application-python-pymysql.md +++ b/develop/dev-guide-sample-application-python-pymysql.md @@ -1,103 +1,103 @@ --- -title: Connect to TiDB with PyMySQL -summary: Learn how to connect to TiDB using PyMySQL. This tutorial gives Python sample code snippets that work with TiDB using PyMySQL. +title: 使用 PyMySQL 连接 TiDB +summary: 学习如何使用 PyMySQL 连接 TiDB。本教程提供了可用于 TiDB 的 Python 示例代码片段。 --- -# Connect to TiDB with PyMySQL +# 使用 PyMySQL 连接 TiDB -TiDB is a MySQL-compatible database, and [PyMySQL](https://github.com/PyMySQL/PyMySQL) is a popular open-source driver for Python. +TiDB 是一个兼容 MySQL 的数据库，[PyMySQL](https://github.com/PyMySQL/PyMySQL) 是一个流行的开源 Python 驱动。 -In this tutorial, you can learn how to use TiDB and PyMySQL to accomplish the following tasks: +在本教程中，你可以学习如何使用 TiDB 和 PyMySQL 完成以下任务： -- Set up your environment. -- Connect to your TiDB cluster using PyMySQL. -- Build and run your application. Optionally, you can find sample code snippets for basic CRUD operations. +- 搭建你的开发环境。 +- 使用 PyMySQL 连接到你的 TiDB 集群。 +- 构建并运行你的应用程序。你还可以参考基本 CRUD 操作的示例代码片段。 -> **Note:** +> **注意：** > -> This tutorial works with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed clusters. +> 本教程适用于 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及 TiDB 自建集群。 -## Prerequisites +## 前置条件 -To complete this tutorial, you need: +完成本教程，你需要： -- [Python 3.8 or higher](https://www.python.org/downloads/). -- [Git](https://git-scm.com/downloads). -- A TiDB cluster. +- [Python 3.8 或更高版本](https://www.python.org/downloads/)。 +- [Git](https://git-scm.com/downloads)。 +- 一个 TiDB 集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](/production-deployment-using-tiup.md) 创建本地集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) 创建本地集群。 -## Run the sample app to connect to TiDB +## 运行示例应用连接 TiDB -This section demonstrates how to run the sample application code and connect to TiDB. +本节演示如何运行示例应用代码并连接到 TiDB。 -### Step 1: Clone the sample app repository +### 步骤 1：克隆示例应用仓库 -Run the following commands in your terminal window to clone the sample code repository: +在终端窗口中运行以下命令，克隆示例代码仓库： ```shell git clone https://github.com/tidb-samples/tidb-python-pymysql-quickstart.git cd tidb-python-pymysql-quickstart ``` -### Step 2: Install dependencies +### 步骤 2：安装依赖 -Run the following command to install the required packages (including PyMySQL) for the sample app: +运行以下命令，安装示例应用所需的依赖包（包括 PyMySQL）： ```shell pip install -r requirements.txt ``` -### Step 3: Configure connection information +### 步骤 3：配置连接信息 -Connect to your TiDB cluster depending on the TiDB deployment option you've selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称，进入集群概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确保连接对话框中的配置与你的操作环境一致。 - - **Connection Type** is set to `Public` - - **Branch** is set to `main` - - **Connect With** is set to `General` - - **Operating System** matches your environment. + - **Connection Type** 设置为 `Public` + - **Branch** 设置为 `main` + - **Connect With** 设置为 `General` + - **Operating System** 与你的环境一致 - > **Tip:** + > **提示：** > - > If your program is running in Windows Subsystem for Linux (WSL), switch to the corresponding Linux distribution. + > 如果你的程序运行在 Windows Subsystem for Linux (WSL) 中，请切换到对应的 Linux 发行版。 -4. Click **Generate Password** to create a random password. +4. 点击 **Generate Password** 生成一个随机密码。 - > **Tip:** + > **提示：** > - > If you have created a password before, you can either use the original password or click **Reset Password** to generate a new one. + > 如果你之前已经创建过密码，可以继续使用原密码，或点击 **Reset Password** 生成新密码。 -5. Run the following command to copy `.env.example` and rename it to `.env`: +5. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -6. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +6. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例结果如下： ```dotenv TIDB_HOST='{host}' # e.g. gateway01.ap-northeast-1.prod.aws.tidbcloud.com @@ -108,30 +108,30 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele CA_PATH='{ssl_ca}' # e.g. /etc/ssl/certs/ca-certificates.crt (Debian / Ubuntu / Arch) ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog. + 请确保将 `{}` 占位符替换为连接对话框中获取的连接参数。 -7. Save the `.env` file. +7. 保存 `.env` 文件。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称，进入集群概览页面。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还未配置 IP 访问列表，请点击 **Configure IP Access List**，或参考 [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 进行配置后再首次连接。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息请参考 [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Run the following command to copy `.env.example` and rename it to `.env`: +4. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -5. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +5. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例结果如下： ```dotenv TIDB_HOST='{host}' # e.g. tidb.xxxx.clusters.tidb-cloud.com @@ -142,20 +142,20 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele CA_PATH='{your-downloaded-ca-path}' ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog, and configure `CA_PATH` with the certificate path downloaded in the previous step. + 请确保将 `{}` 占位符替换为连接对话框中获取的连接参数，并将 `CA_PATH` 配置为上一步下载的证书路径。 -6. Save the `.env` file. +6. 保存 `.env` 文件。
-
+
-1. Run the following command to copy `.env.example` and rename it to `.env`: +1. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -2. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +2. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例结果如下： ```dotenv TIDB_HOST='{tidb_server_host}' @@ -165,30 +165,30 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele TIDB_DB_NAME='test' ``` - Be sure to replace the placeholders `{}` with the connection parameters, and remove the `CA_PATH` line. If you are running TiDB locally, the default host address is `127.0.0.1`, and the password is empty. + 请确保将 `{}` 占位符替换为连接参数，并删除 `CA_PATH` 这一行。如果你在本地运行 TiDB，默认主机地址为 `127.0.0.1`，密码为空。 -3. Save the `.env` file. +3. 保存 `.env` 文件。
-### Step 4: Run the code and check the result +### 步骤 4：运行代码并检查结果 -1. Execute the following command to run the sample code: +1. 执行以下命令运行示例代码： ```shell python pymysql_example.py ``` -2. Check the [Expected-Output.txt](https://github.com/tidb-samples/tidb-python-pymysql-quickstart/blob/main/Expected-Output.txt) to see if the output matches. +2. 检查 [Expected-Output.txt](https://github.com/tidb-samples/tidb-python-pymysql-quickstart/blob/main/Expected-Output.txt) 文件，确认输出是否一致。 -## Sample code snippets +## 示例代码片段 -You can refer to the following sample code snippets to complete your own application development. +你可以参考以下示例代码片段，完成你自己的应用开发。 -For complete sample code and how to run it, check out the [tidb-samples/tidb-python-pymysql-quickstart](https://github.com/tidb-samples/tidb-python-pymysql-quickstart) repository. +完整示例代码及运行方法请参考 [tidb-samples/tidb-python-pymysql-quickstart](https://github.com/tidb-samples/tidb-python-pymysql-quickstart) 仓库。 -### Connect to TiDB +### 连接 TiDB ```python from pymysql import Connection @@ -215,9 +215,9 @@ def get_connection(autocommit: bool = True) -> Connection: return pymysql.connect(**db_conf) ``` -When using this function, you need to replace `${tidb_host}`, `${tidb_port}`, `${tidb_user}`, `${tidb_password}`, `${tidb_db_name}` and `${ca_path}` with the actual values of your TiDB cluster. +使用该函数时，你需要将 `${tidb_host}`、`${tidb_port}`、`${tidb_user}`、`${tidb_password}`、`${tidb_db_name}` 和 `${ca_path}` 替换为你 TiDB 集群的实际值。 -### Insert data +### 插入数据 ```python with get_connection(autocommit=True) as conn: @@ -226,9 +226,9 @@ with get_connection(autocommit=True) as conn: cursor.execute("INSERT INTO players (id, coins, goods) VALUES (%s, %s, %s)", player) ``` -For more information, refer to [Insert data](/develop/dev-guide-insert-data.md). +更多信息请参考 [插入数据](/develop/dev-guide-insert-data.md)。 -### Query data +### 查询数据 ```python with get_connection(autocommit=True) as conn: @@ -237,9 +237,9 @@ with get_connection(autocommit=True) as conn: print(cursor.fetchone()["count(*)"]) ``` -For more information, refer to [Query data](/develop/dev-guide-get-data-from-single-table.md). +更多信息请参考 [查询数据](/develop/dev-guide-get-data-from-single-table.md)。 -### Update data +### 更新数据 ```python with get_connection(autocommit=True) as conn: @@ -251,9 +251,9 @@ with get_connection(autocommit=True) as conn: ) ``` -For more information, refer to [Update data](/develop/dev-guide-update-data.md). +更多信息请参考 [更新数据](/develop/dev-guide-update-data.md)。 -### Delete data +### 删除数据 ```python with get_connection(autocommit=True) as conn: @@ -262,39 +262,39 @@ with get_connection(autocommit=True) as conn: cursor.execute("DELETE FROM players WHERE id = %s", (player_id,)) ``` -For more information, refer to [Delete data](/develop/dev-guide-delete-data.md). +更多信息请参考 [删除数据](/develop/dev-guide-delete-data.md)。 -## Useful notes +## 实用说明 -### Using driver or ORM framework? +### 使用驱动还是 ORM 框架？ -The Python driver provides low-level access to the database, but it requires the developers to: +Python 驱动提供了对数据库的底层访问，但这要求开发者： -- Manually establish and release database connections. -- Manually manage database transactions. -- Manually map data rows (represented as a tuple or dict in `pymysql`) to data objects. +- 手动建立和释放数据库连接。 +- 手动管理数据库事务。 +- 手动将数据行（在 `pymysql` 中表现为元组或字典）映射为数据对象。 -Unless you need to write complex SQL statements, it is recommended to use [ORM](https://en.wikipedia.org/w/index.php?title=Object-relational_mapping) framework for development, such as [SQLAlchemy](/develop/dev-guide-sample-application-python-sqlalchemy.md), [Peewee](/develop/dev-guide-sample-application-python-peewee.md), and Django ORM. It can help you: +除非你需要编写复杂的 SQL 语句，否则推荐使用 [ORM](https://en.wikipedia.org/w/index.php?title=Object-relational_mapping) 框架进行开发，例如 [SQLAlchemy](/develop/dev-guide-sample-application-python-sqlalchemy.md)、[Peewee](/develop/dev-guide-sample-application-python-peewee.md) 和 Django ORM。这样可以帮助你： -- Reduce [boilerplate code](https://en.wikipedia.org/wiki/Boilerplate_code) for managing connections and transactions. -- Manipulate data with data objects instead of a number of SQL statements. +- 减少用于管理连接和事务的 [样板代码](https://en.wikipedia.org/wiki/Boilerplate_code)。 +- 通过数据对象操作数据，而不是大量 SQL 语句。 -## Next steps +## 后续步骤 -- Learn more usage of PyMySQL from [the documentation of PyMySQL](https://pymysql.readthedocs.io). -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Single table reading](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), and [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. +- 通过 [PyMySQL 官方文档](https://pymysql.readthedocs.io) 学习更多 PyMySQL 的用法。 +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节学习 TiDB 应用开发最佳实践，例如 [插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md) 以及 [SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/) 学习，并在通过考试后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](https://tidb.support.pingcap.com/)。 - + \ No newline at end of file diff --git a/develop/dev-guide-sample-application-python-sqlalchemy.md b/develop/dev-guide-sample-application-python-sqlalchemy.md index 2823758a6e846..b3028f7e16c88 100644 --- a/develop/dev-guide-sample-application-python-sqlalchemy.md +++ b/develop/dev-guide-sample-application-python-sqlalchemy.md @@ -1,113 +1,113 @@ --- -title: Connect to TiDB with SQLAlchemy -summary: Learn how to connect to TiDB using SQLAlchemy. This tutorial gives Python sample code snippets that work with TiDB using SQLAlchemy. +title: 使用 SQLAlchemy 连接 TiDB +summary: 学习如何使用 SQLAlchemy 连接 TiDB。本教程提供了可与 TiDB 搭配使用的 Python 示例代码片段。 --- -# Connect to TiDB with SQLAlchemy +# 使用 SQLAlchemy 连接 TiDB -TiDB is a MySQL-compatible database, and [SQLAlchemy](https://www.sqlalchemy.org/) is a popular Python SQL toolkit and Object Relational Mapper (ORM). +TiDB 是一个兼容 MySQL 的数据库，[SQLAlchemy](https://www.sqlalchemy.org/) 是一个流行的 Python SQL 工具包和对象关系映射（ORM）库。 -In this tutorial, you can learn how to use TiDB and SQLAlchemy to accomplish the following tasks: +在本教程中，你可以学习如何使用 TiDB 和 SQLAlchemy 完成以下任务： -- Set up your environment. -- Connect to your TiDB cluster using SQLAlchemy. -- Build and run your application. Optionally, you can find sample code snippets for basic CRUD operations. +- 搭建你的开发环境。 +- 使用 SQLAlchemy 连接到你的 TiDB 集群。 +- 构建并运行你的应用程序。你还可以参考基本 CRUD 操作的示例代码片段。 > **Note:** > -> This tutorial works with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed clusters. +> 本教程适用于 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及 TiDB 自建集群。 -## Prerequisites +## 前置条件 -To complete this tutorial, you need: +完成本教程，你需要： -- [Python 3.8 or higher](https://www.python.org/downloads/). -- [Git](https://git-scm.com/downloads). -- A TiDB cluster. +- [Python 3.8 或更高版本](https://www.python.org/downloads/)。 +- [Git](https://git-scm.com/downloads)。 +- 一个 TiDB 集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md)来创建你自己的 TiDB Cloud 集群。 +- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署生产环境 TiDB 集群](/production-deployment-using-tiup.md)来创建本地集群。 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md)来创建你自己的 TiDB Cloud 集群。 +- 参考[部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster)或[部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup)来创建本地集群。 -## Run the sample app to connect to TiDB +## 运行示例应用连接 TiDB -This section demonstrates how to run the sample application code and connect to TiDB. +本节演示如何运行示例应用代码并连接到 TiDB。 -### Step 1: Clone the sample app repository +### 步骤 1：克隆示例应用仓库 -Run the following commands in your terminal window to clone the sample code repository: +在终端窗口中运行以下命令，克隆示例代码仓库： ```shell git clone https://github.com/tidb-samples/tidb-python-sqlalchemy-quickstart.git cd tidb-python-sqlalchemy-quickstart ``` -### Step 2: Install dependencies +### 步骤 2：安装依赖 -Run the following command to install the required packages (including SQLAlchemy and PyMySQL) for the sample app: +运行以下命令安装示例应用所需的依赖包（包括 SQLAlchemy 和 PyMySQL）： ```shell pip install -r requirements.txt ``` -#### Why use PyMySQL? +#### 为什么使用 PyMySQL？ -SQLAlchemy is an ORM library that works with multiple databases. It provides a high-level abstraction of the database, which helps developers write SQL statements in a more object-oriented way. However, SQLAlchemy does not include a database driver. To connect to a database, you need to install a database driver. This sample application uses PyMySQL as the database driver, which is a pure Python MySQL client library that is compatible with TiDB and can be installed on all platforms. +SQLAlchemy 是一个支持多种数据库的 ORM 库。它为数据库提供了高级抽象，帮助开发者以更面向对象的方式编写 SQL 语句。但 SQLAlchemy 并不自带数据库驱动。要连接数据库，你需要安装数据库驱动。本示例应用使用 PyMySQL 作为数据库驱动，它是一个纯 Python 的 MySQL 客户端库，兼容 TiDB，并可在所有平台上安装。 -You can also use other database drivers, such as [mysqlclient](https://github.com/PyMySQL/mysqlclient) and [mysql-connector-python](https://dev.mysql.com/doc/connector-python/en/). But they are not pure Python libraries and require the corresponding C/C++ compiler and MySQL client for compiling. For more information, refer to [SQLAlchemy official documentation](https://docs.sqlalchemy.org/en/20/core/engines.html#mysql). +你也可以使用其他数据库驱动，如 [mysqlclient](https://github.com/PyMySQL/mysqlclient) 和 [mysql-connector-python](https://dev.mysql.com/doc/connector-python/en/)。但它们不是纯 Python 库，需要相应的 C/C++ 编译器和 MySQL 客户端进行编译。更多信息请参考 [SQLAlchemy 官方文档](https://docs.sqlalchemy.org/en/20/core/engines.html#mysql)。 -### Step 3: Configure connection information +### 步骤 3：配置连接信息 -Connect to your TiDB cluster depending on the TiDB deployment option you've selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
> **Note:** > -> Currently, {{{ .starter }}} clusters have a limitation: if there are no active connections for 5 minutes, they will shut down, which closes all connections. Therefore, when using SQLAlchemy with {{{ .starter }}} clusters, pooled connections might encounter `OperationalError` such as `Lost connection to MySQL server during query` or `MySQL Connection not available`. To avoid this error, you can set the `pool_recycle` parameter to `300`. For more information, see [Dealing with Disconnects](https://docs.sqlalchemy.org/en/20/core/pooling.html#dealing-with-disconnects) in SQLAlchemy documentation. +> 目前，TiDB Cloud Serverless 集群有如下限制：如果 5 分钟内没有活跃连接，集群会自动关闭，所有连接会被断开。因此，当你在 TiDB Cloud Serverless 集群中使用 SQLAlchemy 时，连接池可能会遇到 `OperationalError`，如 `Lost connection to MySQL server during query` 或 `MySQL Connection not available`。为避免此类错误，你可以将 `pool_recycle` 参数设置为 `300`。更多信息请参见 SQLAlchemy 文档中的 [Dealing with Disconnects](https://docs.sqlalchemy.org/en/20/core/pooling.html#dealing-with-disconnects)。 -1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确保连接对话框中的配置与你的操作环境一致。 - - **Connection Type** is set to `Public` - - **Branch** is set to `main` - - **Connect With** is set to `General` - - **Operating System** matches your environment. + - **Connection Type** 设置为 `Public` + - **Branch** 设置为 `main` + - **Connect With** 设置为 `General` + - **Operating System** 与你的环境一致 > **Tip:** > - > If your program is running in Windows Subsystem for Linux (WSL), switch to the corresponding Linux distribution. + > 如果你的程序运行在 Windows Subsystem for Linux (WSL) 中，请切换到对应的 Linux 发行版。 -4. Click **Generate Password** to create a random password. +4. 点击 **Generate Password** 生成随机密码。 > **Tip:** > - > If you have created a password before, you can either use the original password or click **Reset Password** to generate a new one. + > 如果你之前已创建过密码，可以继续使用原密码，或点击 **Reset Password** 生成新密码。 -5. Run the following command to copy `.env.example` and rename it to `.env`: +5. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -6. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +6. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例结果如下： ```dotenv TIDB_HOST='{host}' # e.g. gateway01.ap-northeast-1.prod.aws.tidbcloud.com @@ -118,30 +118,30 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele CA_PATH='{ssl_ca}' # e.g. /etc/ssl/certs/ca-certificates.crt (Debian / Ubuntu / Arch) ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog. + 请务必将 `{}` 占位符替换为连接对话框中获取的连接参数。 -7. Save the `.env` file. +7. 保存 `.env` 文件。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还未配置 IP 访问列表，请点击 **Configure IP Access List**，或参考 [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 进行配置，以便首次连接。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息请参见 [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Run the following command to copy `.env.example` and rename it to `.env`: +4. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -5. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +5. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例结果如下： ```dotenv TIDB_HOST='{host}' # e.g. tidb.xxxx.clusters.tidb-cloud.com @@ -152,20 +152,20 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele CA_PATH='{your-downloaded-ca-path}' ``` - Be sure to replace the placeholders `{}` with the connection parameters obtained from the connection dialog, and configure `CA_PATH` with the certificate path downloaded in the previous step. + 请务必将 `{}` 占位符替换为连接对话框中获取的连接参数，并将 `CA_PATH` 配置为上一步下载的证书路径。 -6. Save the `.env` file. +6. 保存 `.env` 文件。
-
+
-1. Run the following command to copy `.env.example` and rename it to `.env`: +1. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -2. Copy and paste the corresponding connection string into the `.env` file. The example result is as follows: +2. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例结果如下： ```dotenv TIDB_HOST='{tidb_server_host}' @@ -175,30 +175,30 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele TIDB_DB_NAME='test' ``` - Be sure to replace the placeholders `{}` with the connection parameters, and remove the `CA_PATH` line. If you are running TiDB locally, the default host address is `127.0.0.1`, and the password is empty. + 请务必将 `{}` 占位符替换为连接参数，并删除 `CA_PATH` 这一行。如果你在本地运行 TiDB，默认主机地址为 `127.0.0.1`，密码为空。 -3. Save the `.env` file. +3. 保存 `.env` 文件。
-### Step 4: Run the code and check the result +### 步骤 4：运行代码并检查结果 -1. Execute the following command to run the sample code: +1. 执行以下命令运行示例代码： ```shell python sqlalchemy_example.py ``` -2. Check the [Expected-Output.txt](https://github.com/tidb-samples/tidb-python-sqlalchemy-quickstart/blob/main/Expected-Output.txt) to see if the output matches. +2. 检查 [Expected-Output.txt](https://github.com/tidb-samples/tidb-python-sqlalchemy-quickstart/blob/main/Expected-Output.txt) 文件，确认输出是否一致。 -## Sample code snippets +## 示例代码片段 -You can refer to the following sample code snippets to complete your own application development. +你可以参考以下示例代码片段，完成你自己的应用开发。 -For complete sample code and how to run it, check out the [tidb-samples/tidb-python-sqlalchemy-quickstart](https://github.com/tidb-samples/tidb-python-sqlalchemy-quickstart) repository. +完整示例代码及运行方法请参考 [tidb-samples/tidb-python-sqlalchemy-quickstart](https://github.com/tidb-samples/tidb-python-sqlalchemy-quickstart) 仓库。 -### Connect to TiDB +### 连接 TiDB ```python from sqlalchemy import create_engine, URL @@ -228,9 +228,9 @@ engine = get_db_engine() Session = sessionmaker(bind=engine) ``` -When using this function, you need to replace `${tidb_host}`, `${tidb_port}`, `${tidb_user}`, `${tidb_password}`, `${tidb_db_name}` and `${ca_path}` with the actual values of your TiDB cluster. +使用该函数时，你需要将 `${tidb_host}`、`${tidb_port}`、`${tidb_user}`、`${tidb_password}`、`${tidb_db_name}` 和 `${ca_path}` 替换为你 TiDB 集群的实际值。 -### Define a table +### 定义数据表 ```python from sqlalchemy import Column, Integer, String @@ -247,9 +247,9 @@ class Player(Base): __tablename__ = "players" ``` -For more information, refer to [SQLAlchemy documentation: Mapping classes with declarative](https://docs.sqlalchemy.org/en/20/orm/declarative_mapping.html). +更多信息请参考 [SQLAlchemy 文档：使用 declarative 进行类映射](https://docs.sqlalchemy.org/en/20/orm/declarative_mapping.html)。 -### Insert data +### 插入数据 ```python with Session() as session: @@ -258,9 +258,9 @@ with Session() as session: session.commit() ``` -For more information, refer to [Insert data](/develop/dev-guide-insert-data.md). +更多信息请参考 [插入数据](/develop/dev-guide-insert-data.md)。 -### Query data +### 查询数据 ```python with Session() as session: @@ -268,9 +268,9 @@ with Session() as session: print(player) ``` -For more information, refer to [Query data](/develop/dev-guide-get-data-from-single-table.md). +更多信息请参考 [查询数据](/develop/dev-guide-get-data-from-single-table.md)。 -### Update data +### 更新数据 ```python with Session() as session: @@ -279,9 +279,9 @@ with Session() as session: session.commit() ``` -For more information, refer to [Update data](/develop/dev-guide-update-data.md). +更多信息请参考 [更新数据](/develop/dev-guide-update-data.md)。 -### Delete data +### 删除数据 ```python with Session() as session: @@ -290,24 +290,24 @@ with Session() as session: session.commit() ``` -For more information, refer to [Delete data](/develop/dev-guide-delete-data.md). +更多信息请参考 [删除数据](/develop/dev-guide-delete-data.md)。 -## Next steps +## 后续步骤 -- Learn more usage of SQLAlchemy from [the documentation of SQLAlchemy](https://www.sqlalchemy.org/). -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Single table reading](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), and [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. +- 通过 [SQLAlchemy 官方文档](https://www.sqlalchemy.org/) 学习更多 SQLAlchemy 的用法。 +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节，学习 TiDB 应用开发最佳实践，例如 [插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md) 以及 [SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/)，并在通过考试后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或[提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或[提交支持工单](https://tidb.support.pingcap.com/)。 diff --git a/develop/dev-guide-sample-application-ruby-mysql2.md b/develop/dev-guide-sample-application-ruby-mysql2.md index e12b0e58059e6..d42b92bebe0b8 100644 --- a/develop/dev-guide-sample-application-ruby-mysql2.md +++ b/develop/dev-guide-sample-application-ruby-mysql2.md @@ -1,71 +1,71 @@ --- -title: Connect to TiDB with mysql2 -summary: Learn how to connect to TiDB using Ruby mysql2. This tutorial gives Ruby sample code snippets that work with TiDB using mysql2 gem. +title: 使用 mysql2 连接 TiDB +summary: 学习如何使用 Ruby 的 mysql2 连接 TiDB。本教程提供了可与 TiDB 协同工作的 Ruby 示例代码片段，基于 mysql2 gem。 --- -# Connect to TiDB with mysql2 +# 使用 mysql2 连接 TiDB -TiDB is a MySQL-compatible database, and [mysql2](https://github.com/brianmario/mysql2) is one of the most popular MySQL drivers for Ruby. +TiDB 是兼容 MySQL 的数据库，[mysql2](https://github.com/brianmario/mysql2) 是 Ruby 生态中最流行的 MySQL 驱动之一。 -In this tutorial, you can learn how to use TiDB and mysql2 to accomplish the following tasks: +在本教程中，你可以学习如何使用 TiDB 和 mysql2 完成以下任务： -- Set up your environment. -- Connect to your TiDB cluster using mysql2. -- Build and run your application. Optionally, you can find [sample code snippets](#sample-code-snippets) for basic CRUD operations. +- 搭建你的开发环境。 +- 使用 mysql2 连接到你的 TiDB 集群。 +- 构建并运行你的应用程序。你还可以在 [示例代码片段](#sample-code-snippets) 中找到基本 CRUD 操作的代码示例。 > **Note:** > -> This tutorial works with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed. +> 本教程适用于 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及自建 TiDB 集群。 -## Prerequisites +## 前置条件 -To complete this tutorial, you need: +完成本教程，你需要： -- [Ruby](https://www.ruby-lang.org/en/) >= 3.0 installed on your machine -- [Bundler](https://bundler.io/) installed on your machine -- [Git](https://git-scm.com/downloads) installed on your machine -- A TiDB cluster running +- 在你的机器上安装 [Ruby](https://www.ruby-lang.org/en/)，版本 >= 3.0 +- 在你的机器上安装 [Bundler](https://bundler.io/) +- 在你的机器上安装 [Git](https://git-scm.com/downloads) +- 已有一个正在运行的 TiDB 集群 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](/production-deployment-using-tiup.md) 创建本地集群。 -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) 创建本地集群。 -## Run the sample app to connect to TiDB +## 运行示例应用连接 TiDB -This section demonstrates how to run the sample application code and connect to TiDB. +本节演示如何运行示例应用代码并连接到 TiDB。 -### Step 1: Clone the sample app repository +### 步骤 1：克隆示例应用仓库 -Run the following commands in your terminal window to clone the sample code repository: +在终端窗口中运行以下命令，克隆示例代码仓库： ```shell git clone https://github.com/tidb-samples/tidb-ruby-mysql2-quickstart.git cd tidb-ruby-mysql2-quickstart ``` -### Step 2: Install dependencies +### 步骤 2：安装依赖 -Run the following command to install the required packages (including `mysql2` and `dotenv`) for the sample app: +运行以下命令，为示例应用安装所需的依赖包（包括 `mysql2` 和 `dotenv`）： ```shell bundle install ```
-Install dependencies for existing projects +为已有项目安装依赖 -For your existing project, run the following command to install the packages: +对于你自己的项目，运行以下命令安装依赖包： ```shell bundle add mysql2 dotenv @@ -73,33 +73,33 @@ bundle add mysql2 dotenv
-### Step 3: Configure connection information +### 步骤 3：配置连接信息 -Connect to your TiDB cluster depending on the TiDB deployment option you've selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接信息对话框。 -3. Ensure the configurations in the connection dialog match your operating environment. +3. 确保连接对话框中的配置与你的操作环境一致。 - - **Connection Type** is set to `Public`. - - **Branch** is set to `main`. - - **Connect With** is set to `General`. - - **Operating System** matches the operating system where you run the application. + - **Connection Type** 设置为 `Public`。 + - **Branch** 设置为 `main`。 + - **Connect With** 设置为 `General`。 + - **Operating System** 选择你运行应用的操作系统。 -4. If you have not set a password yet, click **Generate Password** to generate a random password. +4. 如果你还未设置密码，点击 **Generate Password** 生成一个随机密码。 -5. Run the following command to copy `.env.example` and rename it to `.env`: +5. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： ```shell cp .env.example .env ``` -6. Edit the `.env` file, set up the environment variables as follows, and replace the corresponding placeholders `{}` with connection parameters in the connection dialog: +6. 编辑 `.env` 文件，按如下方式设置环境变量，并将对应的占位符 `{}` 替换为连接对话框中的参数： ```dotenv DATABASE_HOST={host} @@ -112,30 +112,30 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele > **Note** > - > For {{{ .starter }}}, TLS connection **MUST** be enabled via `DATABASE_ENABLE_SSL` when using public endpoint. + > 对于 [TiDB Cloud Serverless](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) 和 [TiDB Cloud Essential](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential)，使用公共连接地址时，**必须** 通过 `DATABASE_ENABLE_SSL` 启用 TLS 连接。 -7. Save the `.env` file. +7. 保存 `.env` 文件。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接信息对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还未配置 IP 访问列表，点击 **Configure IP Access List**，或参考 [配置 IP 访问列表](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 进行配置，以便首次连接。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息请参考 [连接到 TiDB Cloud Dedicated 集群](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Run the following command to copy `.env.example` and rename it to `.env`: +4. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： ```shell cp .env.example .env ``` -5. Edit the `.env` file, set up the environment variables as follows, and replace the corresponding placeholders `{}` with connection parameters in the connection dialog: +5. 编辑 `.env` 文件，按如下方式设置环境变量，并将对应的占位符 `{}` 替换为连接对话框中的参数： ```dotenv DATABASE_HOST={host} @@ -149,22 +149,22 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele > **Note** > - > It is recommended to enable TLS connection when using the public endpoint to connect to a TiDB Cloud Dedicated cluster. + > 推荐在使用公共连接地址连接 TiDB Cloud Dedicated 集群时启用 TLS 连接。 > - > To enable TLS connection, modify `DATABASE_ENABLE_SSL` to `true` and use `DATABASE_SSL_CA` to specify the file path of CA certificate downloaded from the connection dialog. + > 启用 TLS 连接时，请将 `DATABASE_ENABLE_SSL` 设置为 `true`，并通过 `DATABASE_SSL_CA` 指定从连接对话框下载的 CA 证书文件路径。 -6. Save the `.env` file. +6. 保存 `.env` 文件。
-
+
-1. Run the following command to copy `.env.example` and rename it to `.env`: +1. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： ```shell cp .env.example .env ``` -2. Edit the `.env` file, set up the environment variables as follows, and replace the corresponding placeholders `{}` with your own TiDB connection information: +2. 编辑 `.env` 文件，按如下方式设置环境变量，并将对应的占位符 `{}` 替换为你自己的 TiDB 连接信息： ```dotenv DATABASE_HOST={host} @@ -174,25 +174,25 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele DATABASE_NAME=test ``` - If you are running TiDB locally, the default host address is `127.0.0.1`, and the password is empty. + 如果你在本地运行 TiDB，默认主机地址为 `127.0.0.1`，密码为空。 -3. Save the `.env` file. +3. 保存 `.env` 文件。
-### Step 4: Run the code and check the result +### 步骤 4：运行代码并查看结果 -Run the following command to execute the sample code: +运行以下命令执行示例代码： ```shell ruby app.rb ``` -If the connection is successful, the console will output the version of the TiDB cluster as follows: +如果连接成功，控制台会输出 TiDB 集群的版本信息，如下所示： ``` -🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-{{{ .tidb-version }}}) +🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-vv8.5.2) ⏳ Loading sample game data... ✅ Loaded sample game data. @@ -202,15 +202,15 @@ If the connection is successful, the console will output the version of the TiDB 🚮 Deleted 1 player data. ``` -## Sample code snippets +## 示例代码片段 -You can refer to the following sample code snippets to complete your own application development. +你可以参考以下示例代码片段，完成你自己的应用开发。 -For complete sample code and how to run it, check out the [tidb-samples/tidb-ruby-mysql2-quickstart](https://github.com/tidb-samples/tidb-ruby-mysql2-quickstart) repository. +完整示例代码及运行方法请参考 [tidb-samples/tidb-ruby-mysql2-quickstart](https://github.com/tidb-samples/tidb-ruby-mysql2-quickstart) 仓库。 -### Connect to TiDB with connection options +### 使用连接参数连接 TiDB -The following code establishes a connection to TiDB with options defined in the environment variables: +以下代码通过环境变量中定义的参数建立 TiDB 连接： ```ruby require 'dotenv/load' @@ -231,11 +231,11 @@ client = Mysql2::Client.new(options) > **Note** > -> For {{{ .starter }}}, TLS connection **MUST** be enabled via `DATABASE_ENABLE_SSL` when using public endpoint, but you **don't** have to specify an SSL CA certificate via `DATABASE_SSL_CA`, because mysql2 gem will search for existing CA certificates in a particular order until a file is discovered. +> 对于 [TiDB Cloud Serverless](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) 和 [TiDB Cloud Essential](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential)，使用公共连接地址时，**必须** 通过 `DATABASE_ENABLE_SSL` 启用 TLS 连接，但**不需要**通过 `DATABASE_SSL_CA` 指定 SSL CA 证书，因为 mysql2 gem 会按特定顺序自动查找本地已存在的 CA 证书文件。 -### Insert data +### 插入数据 -The following query creates a single player with two fields and returns the `last_insert_id`: +以下查询语句创建一个包含两个字段的玩家，并返回 `last_insert_id`： ```ruby def create_player(client, coins, goods) @@ -246,11 +246,11 @@ def create_player(client, coins, goods) end ``` -For more information, refer to [Insert data](/develop/dev-guide-insert-data.md). +更多信息请参考 [插入数据](/develop/dev-guide-insert-data.md)。 -### Query data +### 查询数据 -The following query returns the record of a specific player by ID: +以下查询语句根据 ID 返回指定玩家的记录： ```ruby def get_player_by_id(client, id) @@ -261,11 +261,11 @@ def get_player_by_id(client, id) end ``` -For more information, refer to [Query data](/develop/dev-guide-get-data-from-single-table.md). +更多信息请参考 [查询数据](/develop/dev-guide-get-data-from-single-table.md)。 -### Update data +### 更新数据 -The following query updated the record of a specific player by ID: +以下查询语句根据 ID 更新指定玩家的记录： ```ruby def update_player(client, player_id, inc_coins, inc_goods) @@ -276,11 +276,11 @@ def update_player(client, player_id, inc_coins, inc_goods) end ``` -For more information, refer to [Update data](/develop/dev-guide-update-data.md). +更多信息请参考 [更新数据](/develop/dev-guide-update-data.md)。 -### Delete data +### 删除数据 -The following query deletes the record of a specific player: +以下查询语句删除指定玩家的记录： ```ruby def delete_player_by_id(client, id) @@ -291,35 +291,35 @@ def delete_player_by_id(client, id) end ``` -For more information, refer to [Delete data](/develop/dev-guide-delete-data.md). +更多信息请参考 [删除数据](/develop/dev-guide-delete-data.md)。 -## Best practices +## 最佳实践 -By default, the mysql2 gem can search for existing CA certificates in a particular order until a file is discovered. +默认情况下，mysql2 gem 会按如下顺序查找本地已存在的 CA 证书文件，直到找到为止： -1. `/etc/ssl/certs/ca-certificates.crt` for Debian, Ubuntu, Gentoo, Arch, or Slackware -2. `/etc/pki/tls/certs/ca-bundle.crt` for RedHat, Fedora, CentOS, Mageia, Vercel, or Netlify -3. `/etc/ssl/ca-bundle.pem` for OpenSUSE -4. `/etc/ssl/cert.pem` for macOS or Alpine (docker container) +1. `/etc/ssl/certs/ca-certificates.crt`（适用于 Debian、Ubuntu、Gentoo、Arch 或 Slackware） +2. `/etc/pki/tls/certs/ca-bundle.crt`（适用于 RedHat、Fedora、CentOS、Mageia、Vercel 或 Netlify） +3. `/etc/ssl/ca-bundle.pem`（适用于 OpenSUSE） +4. `/etc/ssl/cert.pem`（适用于 macOS 或 Alpine（docker 容器）） -While it is possible to specify the CA certificate path manually, doing so might cause significant inconvenience in multi-environment deployment scenarios, because different machines and environments might store the CA certificate in different locations. Therefore, setting `sslca` to `nil` is recommended for flexibility and ease of deployment across different environments. +虽然你可以手动指定 CA 证书路径，但在多环境部署场景下，不同机器和环境可能存储 CA 证书的位置不同，这样做会带来较大不便。因此，推荐将 `sslca` 设置为 `nil`，以便在不同环境下灵活部署和使用。 -## Next steps +## 后续步骤 -- Learn more usage of mysql2 driver from [the documentation of mysql2](https://github.com/brianmario/mysql2#readme). -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as: [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Query data](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), and [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. +- 通过 [mysql2 官方文档](https://github.com/brianmario/mysql2#readme) 学习更多 mysql2 驱动的用法。 +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节，学习 TiDB 应用开发最佳实践，例如：[插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[查询数据](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md) 以及 [SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/)，并在通过考试后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +欢迎在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +欢迎在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](https://tidb.support.pingcap.com/)。 \ No newline at end of file diff --git a/develop/dev-guide-sample-application-ruby-rails.md b/develop/dev-guide-sample-application-ruby-rails.md index a496ecbadfe70..f0ed1c7ebddec 100644 --- a/develop/dev-guide-sample-application-ruby-rails.md +++ b/develop/dev-guide-sample-application-ruby-rails.md @@ -1,71 +1,71 @@ --- -title: Connect to TiDB with Rails framework and ActiveRecord ORM -summary: Learn how to connect to TiDB using the Rails framework. This tutorial gives Ruby sample code snippets that work with TiDB using the Rails framework and ActiveRecord ORM. +title: 使用 Rails 框架和 ActiveRecord ORM 连接 TiDB +summary: 学习如何使用 Rails 框架连接 TiDB。本教程提供了可在 Rails 框架下通过 ActiveRecord ORM 操作 TiDB 的 Ruby 示例代码片段。 --- -# Connect to TiDB with Rails Framework and ActiveRecord ORM +# 使用 Rails 框架和 ActiveRecord ORM 连接 TiDB -TiDB is a MySQL-compatible database, [Rails](https://github.com/rails/rails) is a popular web application framework written in Ruby, and [ActiveRecord ORM](https://github.com/rails/rails/tree/main/activerecord) is the object-relational mapping in Rails. +TiDB 是一个兼容 MySQL 的数据库，[Rails](https://github.com/rails/rails) 是一个流行的 Ruby Web 应用框架，[ActiveRecord ORM](https://github.com/rails/rails/tree/main/activerecord) 是 Rails 中的对象关系映射组件。 -In this tutorial, you can learn how to use TiDB and Rails to accomplish the following tasks: +在本教程中，你可以学习如何使用 TiDB 和 Rails 完成以下任务： -- Set up your environment. -- Connect to your TiDB cluster using Rails. -- Build and run your application. Optionally, you can find [sample code snippets](#sample-code-snippets) for basic CRUD operations using ActiveRecord ORM. +- 搭建你的开发环境。 +- 使用 Rails 连接到你的 TiDB 集群。 +- 构建并运行你的应用程序。你还可以在 [示例代码片段](#sample-code-snippets) 中找到基于 ActiveRecord ORM 的基本 CRUD 操作示例。 > **Note:** > -> This tutorial works with {{{ .starter }}}, TiDB Cloud Dedicated, and TiDB Self-Managed. +> 本教程适用于 TiDB Cloud Serverless、TiDB Cloud Essential、TiDB Cloud Dedicated 以及自建 TiDB 集群。 -## Prerequisites +## 前置条件 -To complete this tutorial, you need: +完成本教程，你需要： -- [Ruby](https://www.ruby-lang.org/en/) >= 3.0 installed on your machine -- [Bundler](https://bundler.io/) installed on your machine -- [Git](https://git-scm.com/downloads) installed on your machine -- A TiDB cluster running +- 在你的机器上安装 [Ruby](https://www.ruby-lang.org/en/)，版本 >= 3.0 +- 在你的机器上安装 [Bundler](https://bundler.io/) +- 在你的机器上安装 [Git](https://git-scm.com/downloads) +- 已有一个正在运行的 TiDB 集群 -**If you don't have a TiDB cluster, you can create one as follows:** +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- (Recommended) Follow [Creating a {{{ .starter }}} 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](/production-deployment-using-tiup.md) 创建本地集群。 -- (Recommended) Follow [Creating a {{{ .starter }}} cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud 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. +- （推荐）参考 [创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建属于你自己的 TiDB Cloud 集群。 +- 参考 [部署本地测试 TiDB 集群](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster) 或 [部署生产环境 TiDB 集群](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) 创建本地集群。 -## Run the sample app to connect to TiDB +## 运行示例应用连接 TiDB -This section demonstrates how to run the sample application code and connect to TiDB. +本节演示如何运行示例应用代码并连接到 TiDB。 -### Step 1: Clone the sample app repository +### 第 1 步：克隆示例应用仓库 -Run the following commands in your terminal window to clone the sample code repository: +在终端窗口中运行以下命令，克隆示例代码仓库： ```shell git clone https://github.com/tidb-samples/tidb-ruby-rails-quickstart.git cd tidb-ruby-rails-quickstart ``` -### Step 2: Install dependencies +### 第 2 步：安装依赖 -Run the following command to install the required packages (including `mysql2` and `dotenv`) for the sample app: +运行以下命令，为示例应用安装所需的依赖包（包括 `mysql2` 和 `dotenv`）： ```shell bundle install ```
-Install dependencies for existing projects +为已有项目安装依赖 -For your existing project, run the following command to install the packages: +对于你已有的项目，运行以下命令安装依赖包： ```shell bundle add mysql2 dotenv @@ -73,28 +73,28 @@ bundle add mysql2 dotenv
-### Step 3: Configure connection information +### 第 3 步：配置连接信息 -Connect to your TiDB cluster depending on the TiDB deployment option you've selected. +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 -
+
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. In the connection dialog, select `Rails` from the **Connect With** drop-down list and keep the default setting of the **Connection Type** as `Public`. +3. 在连接对话框中，从 **Connect With** 下拉列表选择 `Rails`，**Connection Type** 保持默认的 `Public`。 -4. If you have not set a password yet, click **Generate Password** to generate a random password. +4. 如果你还未设置密码，点击 **Generate Password** 生成一个随机密码。 -5. Run the following command to copy `.env.example` and rename it to `.env`: +5. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -6. Edit the `.env` file, set up the `DATABASE_URL` environment variable as follows, and copy the connection string from the connection dialog as the variable value. +6. 编辑 `.env` 文件，按如下格式设置 `DATABASE_URL` 环境变量，并将连接对话框中的连接字符串复制为变量值。 ```dotenv DATABASE_URL='mysql2://{user}:{password}@{host}:{port}/{database_name}?ssl_mode=verify_identity' @@ -102,30 +102,30 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele > **Note** > - > For {{{ .starter }}}, TLS connection **MUST** be enabled with the `ssl_mode=verify_identity` query parameter when using public endpoint. + > 对于 [TiDB Cloud Serverless](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) 和 [TiDB Cloud Essential](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential)，使用公共连接地址时，**必须** 通过 `ssl_mode=verify_identity` 参数启用 TLS 连接。 -7. Save the `.env` file. +7. 保存 `.env` 文件。
-1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -2. Click **Connect** in the upper-right corner. A connection dialog is displayed. +2. 点击右上角的 **Connect**，弹出连接对话框。 -3. In the connection dialog, select **Public** from the **Connection Type** drop-down list, and then click **CA cert** to download the CA certificate. +3. 在连接对话框中，从 **Connection Type** 下拉列表选择 **Public**，然后点击 **CA cert** 下载 CA 证书。 - If you have not configured the IP access list, click **Configure IP Access List** or follow the steps in [Configure an IP Access List](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) to configure it before your first connection. + 如果你还未配置 IP 访问列表，点击 **Configure IP Access List**，或参考 [配置 IP 访问列表](https://docs.pingcap.com/tidbcloud/configure-ip-access-list) 进行首次连接前的配置。 - In addition to the **Public** connection type, TiDB Cloud Dedicated supports **Private Endpoint** and **VPC Peering** connection types. For more information, see [Connect to Your TiDB Cloud Dedicated Cluster](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster). + 除了 **Public** 连接类型，TiDB Cloud Dedicated 还支持 **Private Endpoint** 和 **VPC Peering** 连接类型。更多信息请参考 [连接到你的 TiDB Cloud Dedicated 集群](https://docs.pingcap.com/tidbcloud/connect-to-tidb-cluster)。 -4. Run the following command to copy `.env.example` and rename it to `.env`: +4. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -5. Edit the `.env` file, set up the `DATABASE_URL` environment variable as follows, copy the connection string from the connection dialog as the variable value, and set the `sslca` query parameter to the file path of the CA certificate downloaded from the connection dialog: +5. 编辑 `.env` 文件，按如下格式设置 `DATABASE_URL` 环境变量，将连接对话框中的连接字符串复制为变量值，并将 `sslca` 参数设置为刚才下载的 CA 证书文件路径： ```dotenv DATABASE_URL='mysql2://{user}:{password}@{host}:{port}/{database}?ssl_mode=verify_identity&sslca=/path/to/ca.pem' @@ -133,59 +133,59 @@ Connect to your TiDB cluster depending on the TiDB deployment option you've sele > **Note** > - > It is recommended to enable TLS connection when using the public endpoint to connect to TiDB Cloud Dedicated. + > 推荐在使用公共连接地址连接 TiDB Cloud Dedicated 时启用 TLS 连接。 > - > To enable TLS connection, modify the value of the `ssl_mode` query parameter to `verify_identity` and the value of `sslca` to the file path of CA certificate downloaded from the connection dialog. + > 启用 TLS 连接时，请将 `ssl_mode` 参数值设置为 `verify_identity`，`sslca` 参数值设置为从连接对话框下载的 CA 证书文件路径。 -6. Save the `.env` file. +6. 保存 `.env` 文件。
-
+
-1. Run the following command to copy `.env.example` and rename it to `.env`: +1. 运行以下命令，复制 `.env.example` 并重命名为 `.env`： ```shell cp .env.example .env ``` -2. Edit the `.env` file, set up the `DATABASE_URL` environment variable as follows, and replace the `{user}`, `{password}`, `{host}`, `{port}`, and `{database}` with your own TiDB connection information: +2. 编辑 `.env` 文件，按如下格式设置 `DATABASE_URL` 环境变量，并将 `{user}`、`{password}`、`{host}`、`{port}`、`{database}` 替换为你自己的 TiDB 连接信息： ```dotenv DATABASE_URL='mysql2://{user}:{password}@{host}:{port}/{database}' ``` - If you are running TiDB locally, the default host address is `127.0.0.1`, and the password is empty. + 如果你在本地运行 TiDB，默认主机地址为 `127.0.0.1`，密码为空。 -3. Save the `.env` file. +3. 保存 `.env` 文件。
-### Step 4: Run the code and check the result +### 第 4 步：运行代码并检查结果 -1. Create the database and table: +1. 创建数据库和数据表： ```shell bundle exec rails db:create bundle exec rails db:migrate ``` -2. Seed the sample data: +2. 初始化示例数据： ```shell bundle exec rails db:seed ``` -3. Run the following command to execute the sample code: +3. 运行以下命令执行示例代码： ```shell bundle exec rails runner ./quickstart.rb ``` -If the connection is successful, the console will output the version of the TiDB cluster as follows: +如果连接成功，控制台会输出 TiDB 集群的版本信息，如下所示： ``` -🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-{{{ .tidb-version }}}) +🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-vv8.5.2) ⏳ Loading sample game data... ✅ Loaded sample game data. @@ -195,15 +195,15 @@ If the connection is successful, the console will output the version of the TiDB 🚮 Deleted 1 player data. ``` -## Sample code snippets +## 示例代码片段 -You can refer to the following sample code snippets to complete your own application development. +你可以参考以下示例代码片段，完成你自己的应用开发。 -For complete sample code and how to run it, check out the [tidb-samples/tidb-ruby-rails-quickstart](https://github.com/tidb-samples/tidb-ruby-rails-quickstart) repository. +完整示例代码及运行方法请参考 [tidb-samples/tidb-ruby-rails-quickstart](https://github.com/tidb-samples/tidb-ruby-rails-quickstart) 仓库。 -### Connect to TiDB with connection options +### 通过连接参数连接 TiDB -The following code in `config/database.yml` establishes a connection to TiDB with options defined in the environment variables: +以下 `config/database.yml` 文件中的代码，通过环境变量定义的参数建立与 TiDB 的连接： ```yml default: &default @@ -225,75 +225,75 @@ production: > **Note** > -> For {{{ .starter }}}, TLS connection **MUST** be enabled via setting the `ssl_mode` query parameter to `verify_identity` in `DATABASE_URL` when using public endpoint, but you **don't** have to specify an SSL CA certificate via `DATABASE_URL`, because mysql2 gem will search for existing CA certificates in a particular order until a file is discovered. +> 对于 [TiDB Cloud Serverless](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) 和 [TiDB Cloud Essential](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential)，使用公共连接地址时，**必须** 在 `DATABASE_URL` 中通过设置 `ssl_mode` 参数为 `verify_identity` 启用 TLS 连接，但你**不需要**通过 `DATABASE_URL` 指定 SSL CA 证书，因为 mysql2 gem 会按特定顺序自动查找本地已存在的 CA 证书文件。 -### Insert data +### 插入数据 -The following query creates a single Player with two fields and returns the created `Player` object: +以下语句创建一个包含两个字段的 Player，并返回新建的 `Player` 对象： ```ruby new_player = Player.create!(coins: 100, goods: 100) ``` -For more information, refer to [Insert data](/develop/dev-guide-insert-data.md). +更多信息请参考 [插入数据](/develop/dev-guide-insert-data.md)。 -### Query data +### 查询数据 -The following query returns the record of a specific player by ID: +以下语句根据 ID 查询指定玩家的记录： ```ruby player = Player.find_by(id: new_player.id) ``` -For more information, refer to [Query data](/develop/dev-guide-get-data-from-single-table.md). +更多信息请参考 [查询数据](/develop/dev-guide-get-data-from-single-table.md)。 -### Update data +### 更新数据 -The following query updates a `Player` object: +以下语句更新一个 `Player` 对象： ```ruby player.update(coins: 50, goods: 50) ``` -For more information, refer to [Update data](/develop/dev-guide-update-data.md). +更多信息请参考 [更新数据](/develop/dev-guide-update-data.md)。 -### Delete data +### 删除数据 -The following query deletes a `Player` object: +以下语句删除一个 `Player` 对象： ```ruby player.destroy ``` -For more information, refer to [Delete data](/develop/dev-guide-delete-data.md). +更多信息请参考 [删除数据](/develop/dev-guide-delete-data.md)。 -## Best practices +## 最佳实践 -By default, the mysql2 gem (used by ActiveRecord ORM to connect TiDB) will search for existing CA certificates in a particular order until a file is discovered. +默认情况下，ActiveRecord ORM 通过 mysql2 gem 连接 TiDB 时，会按如下顺序查找本地已存在的 CA 证书文件，直到找到为止： 1. /etc/ssl/certs/ca-certificates.crt # Debian / Ubuntu / Gentoo / Arch / Slackware 2. /etc/pki/tls/certs/ca-bundle.crt # RedHat / Fedora / CentOS / Mageia / Vercel / Netlify 3. /etc/ssl/ca-bundle.pem # OpenSUSE 4. /etc/ssl/cert.pem # MacOS / Alpine (docker container) -While it is possible to specify the CA certificate path manually, this approach may cause significant inconvenience in multi-environment deployment scenarios, as different machines and environments may store the CA certificate in varying locations. Therefore, setting `sslca` to `nil` is recommended for flexibility and ease of deployment across different environments. +虽然可以手动指定 CA 证书路径，但在多环境部署场景下，不同机器和环境的 CA 证书存放路径可能不同，这种方式会带来较大不便。因此，推荐将 `sslca` 设置为 `nil`，以便在不同环境下灵活部署和使用。 -## Next steps +## 后续步骤 -- Learn more usage of ActiveRecord ORM from [the documentation of ActiveRecord](https://guides.rubyonrails.org/active_record_basics.html). -- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as: [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Query data](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), and [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). -- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. +- 通过 [ActiveRecord 官方文档](https://guides.rubyonrails.org/active_record_basics.html) 学习更多 ActiveRecord ORM 的用法。 +- 通过 [开发者指南](/develop/dev-guide-overview.md) 各章节，学习 TiDB 应用开发最佳实践，例如：[插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[查询数据](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md) 以及 [SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)。 +- 通过专业的 [TiDB 开发者课程](https://www.pingcap.com/education/)，并在通过考试后获得 [TiDB 认证](https://www.pingcap.com/education/certification/)。 -## Need help? +## 需要帮助？ -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](/support.md). +欢迎在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](/support.md)。 -Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). +欢迎在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问，或 [提交支持工单](https://tidb.support.pingcap.com/)。 \ No newline at end of file diff --git a/follower-read.md b/follower-read.md index 6a8f413bea93e..3282f18da4476 100644 --- a/follower-read.md +++ b/follower-read.md @@ -1,68 +1,71 @@ --- title: Follower Read -summary: This document describes the use and implementation of Follower Read. +summary: 本文档介绍了 Follower Read 的使用和实现机制。 --- # Follower Read -When a read hotspot appears in a Region, the Region leader can become a read bottleneck for the entire system. In this situation, enabling the Follower Read feature can significantly reduce the load of the leader, and improve the throughput of the whole system by balancing the load among multiple followers. This document introduces the use and implementation mechanism of Follower Read. +当某个 Region 出现读热点时，该 Region 的 leader 可能会成为整个系统的读瓶颈。在这种情况下，开启 Follower Read 功能可以显著降低 leader 的负载，并通过在多个 follower 之间均衡负载，提高整个系统的吞吐量。本文档将介绍 Follower Read 的使用方法及其实现机制。 -## Overview +## 概述 -The Follower Read feature refers to using any follower replica of a Region to serve a read request under the premise of strongly consistent reads. This feature improves the throughput of the TiDB cluster and reduces the load of the leader. It contains a series of load balancing mechanisms that offload TiKV read loads from the leader replica to the follower replica in a Region. TiKV's Follower Read implementation provides users with strongly consistent reads. +Follower Read 功能指的是在保证强一致性读的前提下，允许使用 Region 的任意 follower 副本来处理读请求。该功能提升了 TiDB 集群的吞吐能力，并降低了 leader 的负载。它包含一系列负载均衡机制，将 TiKV 的读负载从 leader 副本分担到 Region 的 follower 副本。TiKV 的 Follower Read 实现为用户提供了强一致性读。 > **Note:** > -> To achieve strongly consistent reads, the follower node currently needs to request the current execution progress from the leader node (that is `ReadIndex`), which causes an additional network request overhead. Therefore, the main benefits of Follower Read are to isolate read requests from write requests in the cluster and to increase overall read throughput. +> 为了实现强一致性读，follower 节点目前需要向 leader 节点请求当前的执行进度（即 `ReadIndex`），这会带来一次额外的网络请求开销。因此，Follower Read 的主要收益在于将集群中的读请求与写请求隔离，并提升整体读吞吐量。 -## Usage +## 使用方法 -To enable TiDB's Follower Read feature, modify the value of the `tidb_replica_read` variable as follows: - -{{< copyable "sql" >}} +要启用 TiDB 的 Follower Read 功能，可以按如下方式修改 `tidb_replica_read` 变量的值： ```sql set [session | global] tidb_replica_read = ''; ``` -Scope: SESSION | GLOBAL +作用域：SESSION | GLOBAL -Default: leader +默认值：leader -This variable is used to set the expected data read mode. +该变量用于设置期望的数据读取模式。 -- When the value of `tidb_replica_read` is set to `leader` or an empty string, TiDB maintains its default behavior and sends all read operations to the leader replica to perform. -- When the value of `tidb_replica_read` is set to `follower`, TiDB selects a follower replica of the Region to perform all read operations. -- When the value of `tidb_replica_read` is set to `leader-and-follower`, TiDB can select any replicas to perform read operations. In this mode, read requests are load balanced between the leader and follower. -- When the value of `tidb_replica_read` is set to `prefer-leader`, TiDB prefers to select the leader replica to perform read operations. If the leader replica is obviously slow in processing read operations (such as caused by disk or network performance jitter), TiDB will select other available follower replicas to perform read operations. -- When the value of `tidb_replica_read` is set to `closest-replicas`, TiDB prefers to select a replica in the same availability zone to perform read operations, which can be a leader or a follower. If there is no replica in the same availability zone, TiDB reads from the leader replica. -- When the value of `tidb_replica_read` is set to `closest-adaptive`: +- 当你将 `tidb_replica_read` 的值设置为 `leader` 或空字符串时，TiDB 保持默认行为，所有读操作都发送到 leader 副本执行。 +- 当你将 `tidb_replica_read` 的值设置为 `follower` 时，TiDB 会选择 Region 的某个 follower 副本来执行读操作。如果该 Region 存在 learner 副本，TiDB 也会以同等优先级考虑使用 learner 副本进行读取。如果当前 Region 没有可用的 follower 或 learner 副本，TiDB 会从 leader 副本读取数据。 +- 当 `tidb_replica_read` 的值设置为 `leader-and-follower` 时，TiDB 可以选择任意副本执行读操作。在该模式下，读请求会在 leader 和 follower 之间进行负载均衡。 +- 当 `tidb_replica_read` 的值设置为 `prefer-leader` 时，TiDB 优先选择 leader 副本执行读操作。如果 leader 副本在处理读操作时明显变慢（如磁盘或网络性能抖动导致），TiDB 会选择其他可用的 follower 副本执行读操作。 +- 当 `tidb_replica_read` 的值设置为 `closest-replicas` 时，TiDB 优先选择同一可用区内的副本执行读操作，该副本可以是 leader 也可以是 follower。如果同一可用区内没有副本，TiDB 会从 leader 副本读取数据。 +- 当 `tidb_replica_read` 的值设置为 `closest-adaptive` 时： - - If the estimated result of a read request is greater than or equal to the value of [`tidb_adaptive_closest_read_threshold`](/system-variables.md#tidb_adaptive_closest_read_threshold-new-in-v630), TiDB prefers to select a replica in the same availability zone for read operations. To avoid unbalanced distribution of read traffic across availability zones, TiDB dynamically detects the distribution of availability zones for all online TiDB and TiKV nodes. In each availability zone, the number of TiDB nodes whose `closest-adaptive` configuration takes effect is limited, which is always the same as the number of TiDB nodes in the availability zone with the fewest TiDB nodes, and the other TiDB nodes automatically read from the leader replica. For example, if TiDB nodes are distributed across 3 availability zones (A, B, and C), where A and B each contains 3 TiDB nodes and C contains only 2 TiDB nodes, the number of TiDB nodes whose `closest-adaptive` configuration takes effect in each availability zone is 2, and the other TiDB node in each of the A and B availability zones automatically selects the leader replica for read operations. - - If the estimated result of a read request is less than the value of [`tidb_adaptive_closest_read_threshold`](/system-variables.md#tidb_adaptive_closest_read_threshold-new-in-v630), TiDB can only select the leader replica for read operations. + - 如果某次读请求的预估结果大于或等于 [`tidb_adaptive_closest_read_threshold`](/system-variables.md#tidb_adaptive_closest_read_threshold-new-in-v630) 的值，TiDB 优先选择同一可用区内的副本进行读操作。为避免读流量在各可用区分布不均，TiDB 会动态检测所有在线 TiDB 和 TiKV 节点的可用区分布。在每个可用区内，`closest-adaptive` 配置生效的 TiDB 节点数量始终等于 TiDB 节点最少的可用区中的节点数，其他 TiDB 节点会自动从 leader 副本读取。例如，TiDB 节点分布在 3 个可用区（A、B、C），A 和 B 各有 3 个 TiDB 节点，C 只有 2 个 TiDB 节点，则每个可用区 `closest-adaptive` 配置生效的 TiDB 节点数为 2，A 和 B 的另外 1 个 TiDB 节点会自动选择 leader 副本进行读操作。 + - 如果某次读请求的预估结果小于 [`tidb_adaptive_closest_read_threshold`](/system-variables.md#tidb_adaptive_closest_read_threshold-new-in-v630) 的值，TiDB 只能选择 leader 副本进行读操作。 -- When the value of `tidb_replica_read` is set to `learner`, TiDB reads data from the learner replica. If there is no learner replica in the Region, TiDB returns an error. +- 当你将 `tidb_replica_read` 的值设置为 `learner` 时，TiDB 会从 learner 副本读取数据。如果当前 Region 没有可用的 learner 副本，TiDB 会从可用的 leader 或 follower 副本读取数据。 > **Note:** > -> When the value of `tidb_replica_read` is set to `closest-replicas` or `closest-adaptive`, you need to configure the cluster to ensure that replicas are distributed across availability zones according to the specified configuration. To configure `location-labels` for PD and set the correct `labels` for TiDB and TiKV, refer to [Schedule replicas by topology labels](/schedule-replicas-by-topology-labels.md). TiDB depends on the `zone` label to match TiKV nodes in the same availability zone, so you need to make sure that the `zone` label is included in the `location-labels` of PD and `zone` is included in the configuration of each TiDB and TiKV node. If your cluster is deployed using TiDB Operator, refer to [High availability of data](https://docs.pingcap.com/tidb-in-kubernetes/v1.4/configure-a-tidb-cluster#high-availability-of-data). +> 当你将 `tidb_replica_read` 设置为 `closest-replicas` 或 `closest-adaptive` 时，为确保副本按照指定配置分布在各可用区，需要为 PD 配置 `location-labels`，并根据 [Schedule replicas by topology labels](/schedule-replicas-by-topology-labels.md) 为 TiDB 和 TiKV 设置正确的 `labels`。TiDB 依赖 `zone` label 匹配同一可用区的 TiKV 节点，因此需要确保 PD 的 `location-labels` 中包含 `zone`，且每个 TiDB 和 TiKV 节点的配置中都包含 `zone`。如果你的集群是通过 TiDB Operator 部署的，请参考 [High availability of data](https://docs.pingcap.com/tidb-in-kubernetes/stable/configure-a-tidb-cluster#high-availability-of-data)。 +> +> 对于 TiDB v7.5.0 及更早版本： +> +> - 如果你将 `tidb_replica_read` 设置为 `follower`，且没有可用的 follower 或 learner 副本，TiDB 会返回错误。 +> - 如果你将 `tidb_replica_read` 设置为 `learner`，且没有可用的 learner 副本，TiDB 会返回错误。 -## Implementation mechanism +## 实现机制 -Before the Follower Read feature was introduced, TiDB applied the strong leader principle and submitted all read and write requests to the leader node of a Region to handle. Although TiKV can distribute Regions evenly on multiple physical nodes, for each Region, only the leader can provide external services. The other followers can do nothing to handle read requests but receive the data replicated from the leader at all times and prepare for voting to elect a leader in case of a failover. +在引入 Follower Read 功能之前，TiDB 遵循强 leader 原则，所有读写请求都提交给 Region 的 leader 节点处理。虽然 TiKV 可以将 Region 均匀分布在多个物理节点上，但对于每个 Region，只有 leader 能对外提供服务，其他 follower 只能持续接收 leader 复制过来的数据，并在发生故障时准备参与 leader 选举。 -To allow data reading in the follower node without violating linearizability or affecting Snapshot Isolation in TiDB, the follower node needs to use `ReadIndex` of the Raft protocol to ensure that the read request can read the latest data that has been committed on the leader. At the TiDB level, the Follower Read feature simply needs to send the read request of a Region to a follower replica based on the load balancing policy. +为了在不违反线性一致性或影响 TiDB 的快照隔离的前提下允许 follower 节点读取数据，follower 节点需要使用 Raft 协议的 `ReadIndex`，以确保读请求能够读取到 leader 已提交的最新数据。在 TiDB 层面，Follower Read 只需根据负载均衡策略将 Region 的读请求发送到 follower 副本。 -### Strongly consistent reads +### 强一致性读 -When the follower node processes a read request, it first uses `ReadIndex` of the Raft protocol to interact with the leader of the Region, to obtain the latest commit index of the current Raft group. After the latest commit index of the leader is applied locally to the follower, the processing of a read request starts. +当 follower 节点处理读请求时，会首先通过 Raft 协议的 `ReadIndex` 与 Region 的 leader 交互，获取当前 Raft group 的最新提交索引。在该提交索引被应用到本地 follower 后，才开始处理读请求。 -### Follower replica selection strategy +### Follower 副本选择策略 -Because the Follower Read feature does not affect TiDB's Snapshot Isolation transaction isolation level, TiDB adopts the round-robin strategy to select the follower replica. Currently, for the coprocessor requests, the granularity of the Follower Read load balancing policy is at the connection level. For a TiDB client connected to a specific Region, the selected follower is fixed, and is switched only when it fails or the scheduling policy is adjusted. +由于 Follower Read 不影响 TiDB 的快照隔离事务隔离级别，TiDB 采用轮询（round-robin）策略选择 follower 副本。目前，对于 coprocessor 请求，Follower Read 负载均衡策略的粒度为连接级。对于连接到某个 Region 的 TiDB 客户端，所选的 follower 是固定的，只有在失败或调度策略调整时才会切换。 -However, for the non-coprocessor requests, such as a point query, the granularity of the Follower Read load balancing policy is at the transaction level. For a TiDB transaction on a specific Region, the selected follower is fixed, and is switched only when it fails or the scheduling policy is adjusted. If a transaction contains both point queries and coprocessor requests, the two types of requests are scheduled for reading separately according to the preceding scheduling policy. In this case, even if a coprocessor request and a point query are for the same Region, TiDB processes them as independent events. +而对于非 coprocessor 请求（如点查），Follower Read 负载均衡策略的粒度为事务级。对于某个 Region 上的 TiDB 事务，所选的 follower 也是固定的，只有在失败或调度策略调整时才会切换。如果一个事务同时包含点查和 coprocessor 请求，这两类请求会按照上述调度策略分别进行读调度。在这种情况下，即使 coprocessor 请求和点查针对同一个 Region，TiDB 也会将它们视为独立事件分别处理。 \ No newline at end of file diff --git a/functions-and-operators/json-functions/json-functions-validate.md b/functions-and-operators/json-functions/json-functions-validate.md index 850c5022d6e02..ba1d1c80812fb 100644 --- a/functions-and-operators/json-functions/json-functions-validate.md +++ b/functions-and-operators/json-functions/json-functions-validate.md @@ -3,58 +3,58 @@ title: JSON Functions That Validate JSON Documents summary: Learn about JSON functions that validate JSON documents. --- -# JSON Functions That Validate JSON Documents +# 用于校验 JSON 文档的 JSON 函数 -This document describes JSON functions that validate JSON documents. +本文档介绍了用于校验 JSON 文档的 JSON 函数。 > **Note:** > -> Currently, this feature is not available on [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) clusters. +> 目前，该功能尚不支持 [TiDB Cloud Serverless](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) 和 [TiDB Cloud Essential](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential) 集群。 ## [JSON_SCHEMA_VALID()](https://dev.mysql.com/doc/refman/8.0/en/json-validation-functions.html#function_json-schema-valid) -The `JSON_SCHEMA_VALID(schema, json_doc)` function validate a JSON document against a schema to ensure data integrity and consistency. +`JSON_SCHEMA_VALID(schema, json_doc)` 函数用于根据 schema 校验 JSON 文档，以确保数据的完整性和一致性。 -This can be used together with a [CHECK](/constraints.md#check) constraint to do automatic schema validation when a table is modified. +该函数可以与 [CHECK](/constraints.md#check) 约束结合使用，在表被修改时自动进行 schema 校验。 -This function follows the [JSON Schema specification](https://json-schema.org/specification). +此函数遵循 [JSON Schema 规范](https://json-schema.org/specification)。 -The supported validation keywords are as follows: +支持的校验关键字如下： -| Validation keyword | Applied type | Description | +| 校验关键字 | 适用类型 | 描述 | |---|---|---| -| `type` | Any | Tests the type (such as `array` and `string`) | -| `enum` | Any | Tests if a value is in the specified array of values | -| `const` | Any | Similar to `enum`, but for a single value | -| `allOf` | Any | Matches all of the specified schemas | -| `anyOf` | Any | Matches any of the specified schemas | -| `multipleOf` | `number`/`integer` | Tests if the value is a multiple of the specified value | -| `maximum` | `number`/`integer` | Tests if the value is below the maximum (inclusive) | -| `exclusiveMaximum` | `number`/`integer` | Tests if the value is below the maximum (exclusive) | -| `minimum` | `number`/`integer` | Tests if the value is above the minimum (inclusive) | -| `exclusiveMinimum` | `number`/`integer` | Tests if the value is above the minimum (exclusive) | -| `maxlength` | `string` | Tests if the length of the value is not exceeding the specified value | -| `minLength` | `string` | Tests if the length of the value is at least the specified value | -| `format` | `string` | Tests if a string matches a named format | -| `pattern` | `string` | Tests if a string matches a pattern | -| `items` | `array` | Schema to apply to the items of an array | -| `prefixItems` | `array` | Schema to apply to positional items of an array | -| `maxItems` | `array` | Tests if the number of items in the array is not exceeding the specified value | -| `minItems` | `array` | Tests if the number of items in the array is at least the specified value | -| `uniqueItems` | `array` | Tests if the items in the array are unique, `true`/`false`| -| `contains` | `array` | Sets schema for items contained in the array | -| `maxContains` | `array` | Used together with `contains` to test the maximum times an item can be present | -| `minContains` | `array` | Used together with `contains` to test the minimum times an item can be present | -| `properties` | `object` | Schema to apply to the properties of an object | -| `patternProperties` | `object` | Schema to apply to certain properties based on pattern matching of the property name | -| `additionalProperties` | `object` | Whether additional properties are allowed or not, `true`/`false` | -| `minProperties` | `object` | Tests the minimum number of properties that an object can have | -| `maxProperties` | `object` | Tests the maximum number of properties that an object can have | -| `required` | `object` | Tests if the specified property names exist in an object | - -Examples: - -For some of the examples, use this JSON document: +| `type` | Any | 检查类型（如 `array` 和 `string`） | +| `enum` | Any | 检查值是否在指定的值数组中 | +| `const` | Any | 类似于 `enum`，但只针对单个值 | +| `allOf` | Any | 匹配所有指定的 schema | +| `anyOf` | Any | 匹配任意一个指定的 schema | +| `multipleOf` | `number`/`integer` | 检查值是否为指定值的倍数 | +| `maximum` | `number`/`integer` | 检查值是否小于等于最大值（包含） | +| `exclusiveMaximum` | `number`/`integer` | 检查值是否小于最大值（不包含） | +| `minimum` | `number`/`integer` | 检查值是否大于等于最小值（包含） | +| `exclusiveMinimum` | `number`/`integer` | 检查值是否大于最小值（不包含） | +| `maxlength` | `string` | 检查值的长度是否不超过指定值 | +| `minLength` | `string` | 检查值的长度是否至少为指定值 | +| `format` | `string` | 检查字符串是否匹配命名格式 | +| `pattern` | `string` | 检查字符串是否匹配正则表达式 | +| `items` | `array` | 应用于数组元素的 schema | +| `prefixItems` | `array` | 应用于数组位置元素的 schema | +| `maxItems` | `array` | 检查数组元素数量是否不超过指定值 | +| `minItems` | `array` | 检查数组元素数量是否至少为指定值 | +| `uniqueItems` | `array` | 检查数组元素是否唯一，`true`/`false`| +| `contains` | `array` | 设置数组中包含元素的 schema | +| `maxContains` | `array` | 与 `contains` 一起使用，检查某元素最多出现的次数 | +| `minContains` | `array` | 与 `contains` 一起使用，检查某元素最少出现的次数 | +| `properties` | `object` | 应用于对象属性的 schema | +| `patternProperties` | `object` | 基于属性名模式匹配应用于特定属性的 schema | +| `additionalProperties` | `object` | 是否允许额外属性，`true`/`false` | +| `minProperties` | `object` | 检查对象最少拥有的属性数量 | +| `maxProperties` | `object` | 检查对象最多拥有的属性数量 | +| `required` | `object` | 检查对象中是否存在指定的属性名 | + +示例： + +部分示例中，使用如下 JSON 文档： ```json { @@ -70,13 +70,13 @@ For some of the examples, use this JSON document: } ``` -Use a [user defined variable](/user-defined-variables.md) to hold the JSON document. +使用 [用户自定义变量](/user-defined-variables.md) 来保存该 JSON 文档。 ```sql SET @j := '{"fruits": ["orange", "apple", "pear"], "vegetables": ["carrot", "pepper", "kale"]}'; ``` -Start by testing the type: +首先测试类型： ```sql SELECT JSON_SCHEMA_VALID('{"type": "object"}',@j); @@ -117,9 +117,9 @@ mysql> SELECT JSON_TYPE(@j); 1 row in set (0.00 sec) ``` -As you can see in the preceding output, the type of `@j` is `object`. This matches with the output of [`JSON_TYPE()`](/functions-and-operators/json-functions/json-functions-return.md#json_type). +如上输出所示，`@j` 的类型为 `object`。这与 [`JSON_TYPE()`](/functions-and-operators/json-functions/json-functions-return.md#json_type) 的输出一致。 -Now validate the presence of certain attributes. +现在校验某些属性的存在性。 ```sql SELECT JSON_SCHEMA_VALID('{"required": ["fruits","vegetables"]}',@j); @@ -134,7 +134,7 @@ SELECT JSON_SCHEMA_VALID('{"required": ["fruits","vegetables"]}',@j); 1 row in set (0.00 sec) ``` -In the preceding output, you can see that the validation of the presence of the `fruits` and `vegetables` attributes succeeds. +如上输出所示，`fruits` 和 `vegetables` 属性的存在性校验通过。 ```sql SELECT JSON_SCHEMA_VALID('{"required": ["fruits","vegetables","grains"]}',@j); @@ -149,9 +149,9 @@ SELECT JSON_SCHEMA_VALID('{"required": ["fruits","vegetables","grains"]}',@j); 1 row in set (0.00 sec) ``` -In the preceding output, you can see that the validation of the presence of the `fruits`, `vegetables` and `grains` attributes fails because `grains` is not present. +如上输出所示，`fruits`、`vegetables` 和 `grains` 属性的存在性校验失败，因为 `grains` 不存在。 -Now validate that `fruits` is an array. +现在校验 `fruits` 是否为数组。 ```sql SELECT JSON_SCHEMA_VALID('{"properties": {"fruits": {"type": "array"}}}',@j); @@ -166,7 +166,7 @@ SELECT JSON_SCHEMA_VALID('{"properties": {"fruits": {"type": "array"}}}',@j); 1 row in set (0.01 sec) ``` -The preceding output confirms that `fruits` is an array. +如上输出确认了 `fruits` 是一个数组。 ```sql SELECT JSON_SCHEMA_VALID('{"properties": {"fruits": {"type": "string"}}}',@j); @@ -181,9 +181,9 @@ SELECT JSON_SCHEMA_VALID('{"properties": {"fruits": {"type": "string"}}}',@j); 1 row in set (0.00 sec) ``` -The preceding output shows that `fruits` is **not** a string. +如上输出表明 `fruits` **不是** 字符串。 -Now verify the number of items in the array. +现在校验数组中的元素数量。 ```sql SELECT JSON_SCHEMA_VALID('{"properties": {"fruits": {"type": "array", "minItems": 3}}}',@j); @@ -198,7 +198,7 @@ SELECT JSON_SCHEMA_VALID('{"properties": {"fruits": {"type": "array", "minItems" 1 row in set (0.00 sec) ``` -The preceding output shows that `fruits` is an array with at least 3 items. +如上输出表明 `fruits` 是一个包含至少 3 个元素的数组。 ```sql SELECT JSON_SCHEMA_VALID('{"properties": {"fruits": {"type": "array", "minItems": 4}}}',@j); @@ -213,9 +213,9 @@ SELECT JSON_SCHEMA_VALID('{"properties": {"fruits": {"type": "array", "minItems" 1 row in set (0.00 sec) ``` -The preceding output shows that `fruits` is **not** an array with at least 4 items. This is because it does not meet the minimum number of items. +如上输出表明 `fruits` **不是** 一个包含至少 4 个元素的数组。因为它不满足最小元素数量的要求。 -For integers values, you can check if they are in a certain range. +对于整数值，可以检查其是否在某个范围内。 ```sql SELECT JSON_SCHEMA_VALID('{"type": "integer", "minimum": 40, "maximum": 45}', '42'); @@ -240,7 +240,7 @@ SELECT JSON_SCHEMA_VALID('{"type": "integer", "minimum": 40, "maximum": 45}', '1 1 row in set (0.00 sec) ``` -For a string, you can validate whether it matches a certain pattern. +对于字符串，可以校验其是否匹配某个模式。 ```sql SELECT JSON_SCHEMA_VALID('{"type": "string", "pattern": "^Ti"}', '"TiDB"'); @@ -268,7 +268,7 @@ SELECT JSON_SCHEMA_VALID('{"type": "string", "pattern": "^Ti"}', '"PingCAP"'); 1 row in set (0.00 sec) ``` -You can check whether a value matches a certain named format. The formats that can be validated include `ipv4`, `ipv6`, `time`, `date`, `duration`, `email`, `hostname`, `uuid`, and `uri`. +你可以校验值是否匹配某个命名格式。可校验的格式包括 `ipv4`、`ipv6`、`time`、`date`、`duration`、`email`、`hostname`、`uuid` 和 `uri`。 ```sql SELECT JSON_SCHEMA_VALID('{"format": "ipv4"}', '"127.0.0.1"'); @@ -296,7 +296,7 @@ SELECT JSON_SCHEMA_VALID('{"format": "ipv4"}', '"327.0.0.1"'); 1 row in set (0.00 sec) ``` -You can also use `enum` to check if a string is in an array. +你还可以使用 `enum` 检查字符串是否在数组中。 ```sql SELECT JSON_SCHEMA_VALID('{"enum": ["TiDB", "MySQL"]}', '"TiDB"'); @@ -337,7 +337,7 @@ SELECT JSON_SCHEMA_VALID('{"enum": ["TiDB", "MySQL"]}', '"SQLite"'); 1 row in set (0.00 sec) ``` -With `anyOf`, you can combine certain requirements and validate whether any of the requirements is met. +通过 `anyOf`，你可以组合多个要求，并校验是否满足其中任意一个要求。 ```sql SELECT JSON_SCHEMA_VALID('{"anyOf": [{"type": "string"},{"type": "integer"}]}', '"TiDB"'); @@ -378,13 +378,13 @@ SELECT JSON_SCHEMA_VALID('{"anyOf": [{"type": "string"},{"type": "integer"}]}', 1 row in set (0.00 sec) ``` -## MySQL compatibility +## MySQL 兼容性 -- If the schema to be validated in `JSON_SCHEMA_VALID()` is invalid (such as `{"type": "sting"}`), MySQL might accept it, but TiDB returns an error. Note that there is a spelling mistake in `"sting"`, which should be `"string"`. -- MySQL uses an older draft version of the JSON Schema standard. +- 如果 `JSON_SCHEMA_VALID()` 中用于校验的 schema 是无效的（如 `{"type": "sting"}`），MySQL 可能会接受，但 TiDB 会返回错误。注意 `"sting"` 拼写错误，正确应为 `"string"`。 +- MySQL 使用的是较早的 JSON Schema 标准草案版本。 -## See also +## 参见 -- [JSON Schema Reference](https://json-schema.org/understanding-json-schema/reference) -- [JSON Functions Overview](/functions-and-operators/json-functions.md) -- [JSON Data Type](/data-type-json.md) \ No newline at end of file +- [JSON Schema 参考](https://json-schema.org/understanding-json-schema/reference) +- [JSON 函数总览](/functions-and-operators/json-functions.md) +- [JSON 数据类型](/data-type-json.md) diff --git a/functions-and-operators/miscellaneous-functions.md b/functions-and-operators/miscellaneous-functions.md index 239c0bdf90f27..2f861a718862c 100644 --- a/functions-and-operators/miscellaneous-functions.md +++ b/functions-and-operators/miscellaneous-functions.md @@ -1,38 +1,38 @@ --- -title: Miscellaneous Functions -summary: Learn about miscellaneous functions in TiDB. +title: 杂项函数 +summary: 了解 TiDB 中的杂项函数。 --- -# Miscellaneous Functions +# 杂项函数 -TiDB supports most of the [miscellaneous functions](https://dev.mysql.com/doc/refman/8.0/en/miscellaneous-functions.html) available in MySQL 8.0. +TiDB 支持 MySQL 8.0 中大多数的 [杂项函数](https://dev.mysql.com/doc/refman/8.0/en/miscellaneous-functions.html)。 -## Supported functions +## 支持的函数 -| Name | Description | +| 名称 | 描述 | |:------------|:-----------------------------------------------------------------------------------------------| -| [`ANY_VALUE()`](#any_value) | Suppress `ONLY_FULL_GROUP_BY` value rejection | -| [`BIN_TO_UUID()`](#bin_to_uuid) | Convert UUID from binary format to text format | -| [`DEFAULT()`](#default) | Returns the default value for a table column | -| [`GROUPING()`](#grouping) | Modifier for `GROUP BY` operations | -| [`INET_ATON()`](#inet_aton) | Return the numeric value of an IP address | -| [`INET_NTOA()`](#inet_ntoa) | Return the IP address from a numeric value | -| [`INET6_ATON()`](#inet6_aton) | Return the numeric value of an IPv6 address | -| [`INET6_NTOA()`](#inet6_ntoa) | Return the IPv6 address from a numeric value | -| [`IS_IPV4()`](#is_ipv4) | Whether argument is an IPv4 address | -| [`IS_IPV4_COMPAT()`](#is_ipv4_compat) | Whether argument is an IPv4-compatible address | -| [`IS_IPV4_MAPPED()`](#is_ipv4_mapped) | Whether argument is an IPv4-mapped address | -| [`IS_IPV6()`](#is_ipv6) | Whether argument is an IPv6 address | -| [`IS_UUID()`](#is_uuid) | Whether argument is an UUID | -| [`NAME_CONST()`](#name_const) | Can be used to rename a column name | -| [`SLEEP()`](#sleep) | Sleep for a number of seconds. Note that for [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) clusters, the `SLEEP()` function has a limitation wherein it can only support a maximum sleep time of 300 seconds. | -| [`UUID()`](#uuid) | Return a Universal Unique Identifier (UUID) | -| [`UUID_TO_BIN()`](#uuid_to_bin) | Convert UUID from text format to binary format | -| [`VALUES()`](#values) | Defines the values to be used during an INSERT | +| [`ANY_VALUE()`](#any_value) | 抑制 `ONLY_FULL_GROUP_BY` 对值的拒绝 | +| [`BIN_TO_UUID()`](#bin_to_uuid) | 将 UUID 从二进制格式转换为文本格式 | +| [`DEFAULT()`](#default) | 返回数据表列的默认值 | +| [`GROUPING()`](#grouping) | 用于 `GROUP BY` 操作的修饰符 | +| [`INET_ATON()`](#inet_aton) | 返回 IP 地址的数值 | +| [`INET_NTOA()`](#inet_ntoa) | 根据数值返回 IP 地址 | +| [`INET6_ATON()`](#inet6_aton) | 返回 IPv6 地址的数值 | +| [`INET6_NTOA()`](#inet6_ntoa) | 根据数值返回 IPv6 地址 | +| [`IS_IPV4()`](#is_ipv4) | 判断参数是否为 IPv4 地址 | +| [`IS_IPV4_COMPAT()`](#is_ipv4_compat) | 判断参数是否为 IPv4 兼容地址 | +| [`IS_IPV4_MAPPED()`](#is_ipv4_mapped) | 判断参数是否为 IPv4 映射地址 | +| [`IS_IPV6()`](#is_ipv6) | 判断参数是否为 IPv6 地址 | +| [`IS_UUID()`](#is_uuid) | 判断参数是否为 UUID | +| [`NAME_CONST()`](#name_const) | 可用于重命名列名 | +| [`SLEEP()`](#sleep) | 休眠指定秒数。注意，对于 [TiDB Cloud Serverless](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) 和 [TiDB Cloud Essential](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential) 集群，`SLEEP()` 函数有最大 300 秒的休眠时间限制。 | +| [`UUID()`](#uuid) | 返回全局唯一标识符（UUID） | +| [`UUID_TO_BIN()`](#uuid_to_bin) | 将 UUID 从文本格式转换为二进制格式 | +| [`VALUES()`](#values) | 定义在 INSERT 期间要使用的值 | ### ANY_VALUE() -The `ANY_VALUE()` function returns any value from a group of values. Typically, it is used in scenarios where you need to include non-aggregated columns in your `SELECT` statement along with a `GROUP BY` clause. +`ANY_VALUE()` 函数从一组值中返回任意一个值。通常用于在带有 `GROUP BY` 子句的 `SELECT` 语句中，需要包含非聚合列的场景。 ```sql CREATE TABLE fruits (id INT PRIMARY KEY, name VARCHAR(255)); @@ -57,14 +57,14 @@ SELECT ANY_VALUE(id),GROUP_CONCAT(id),name FROM fruits GROUP BY name; 4 rows in set (0.00 sec) ``` -In the preceding example, TiDB returns an error for the first `SELECT` statement because the `id` column is non-aggregated and not included in the `GROUP BY` clause. To address the issue, the second `SELECT` query uses `ANY_VALUE()` to get any value from each group and uses `GROUP_CONCAT()` to concatenate all values of the `id` column within each group into a single string. This approach enables you to get one value from each group and all values of the group without changing the SQL mode for non-aggregated columns. +在上述示例中，TiDB 对第一个 `SELECT` 语句返回错误，因为 `id` 列是非聚合列且未包含在 `GROUP BY` 子句中。为了解决该问题，第二个 `SELECT` 查询使用 `ANY_VALUE()` 从每个分组中获取任意一个值，并使用 `GROUP_CONCAT()` 将每个分组内的所有 `id` 列的值拼接为一个字符串。该方法可以在不更改 SQL 模式的情况下，获取每个分组的一个值以及该分组的所有值。 ### BIN_TO_UUID() -`BIN_TO_UUID()` and `UUID_TO_BIN()` can be used to convert between a textual format UUID and a binary format. Both functions accept two arguments. +`BIN_TO_UUID()` 和 `UUID_TO_BIN()` 可用于在文本格式 UUID 和二进制格式之间进行转换。两个函数都接受两个参数。 -- The first argument specifies the value to be converted. -- The second argument (optional) controls the ordering of the fields in the binary format. +- 第一个参数指定要转换的值。 +- 第二个参数（可选）用于控制二进制格式中字段的排序。 ```sql SET @a := UUID(); @@ -111,11 +111,11 @@ SELECT BIN_TO_UUID(0x11EEEB6D9A17B457BACF5405DB7AAD56, 1); 1 row in set (0.00 sec) ``` -See also [UUID()](#uuid) and [Best practices for UUID](/best-practices/uuid.md). +另请参阅 [UUID()](#uuid) 及 [UUID 最佳实践](/best-practices/uuid.md)。 ### DEFAULT() -The `DEFAULT()` function is used to get the default value of a column. +`DEFAULT()` 函数用于获取某一列的默认值。 ```sql CREATE TABLE t1 (id INT PRIMARY KEY, c1 INT DEFAULT 5); @@ -137,15 +137,15 @@ TABLE t1; 1 row in set (0.00 sec) ``` -In the preceding example, the `UPDATE` statement sets the value of the `c1` column to the default value of the column (which is `5`) plus `3`, resulting in a new value of `8`. +在上述示例中，`UPDATE` 语句将 `c1` 列的值设置为该列的默认值（即 `5`）加上 `3`，最终结果为 `8`。 ### GROUPING() -See [`GROUP BY` modifiers](/functions-and-operators/group-by-modifier.md). +参见 [`GROUP BY` 修饰符](/functions-and-operators/group-by-modifier.md)。 ### INET_ATON() -The `INET_ATON()` function converts an IPv4 address in dotted-quad notation into a binary version that can be stored efficiently. +`INET_ATON()` 函数将点分十进制表示的 IPv4 地址转换为可高效存储的数值版本。 ```sql SELECT INET_ATON('127.0.0.1'); @@ -162,7 +162,7 @@ SELECT INET_ATON('127.0.0.1'); ### INET_NTOA() -The `INET_NTOA()` function converts a binary IPv4 address into a dotted-quad notation. +`INET_NTOA()` 函数将数值型 IPv4 地址转换为点分十进制表示。 ```sql SELECT INET_NTOA(2130706433); @@ -179,7 +179,7 @@ SELECT INET_NTOA(2130706433); ### INET6_ATON() -The `INET6_ATON()` function is similar to [`INET_ATON()`](#inet_aton), but `INET6_ATON()` can also handle IPv6 addresses. +`INET6_ATON()` 函数与 [`INET_ATON()`](#inet_aton) 类似，但 `INET6_ATON()` 还可以处理 IPv6 地址。 ```sql SELECT INET6_ATON('::1'); @@ -196,7 +196,7 @@ SELECT INET6_ATON('::1'); ### INET6_NTOA() -The `INET6_NTOA()` function is similar to [`INET_NTOA()`](#inet_ntoa), but `INET6_NTOA()` can also handle IPv6 addresses. +`INET6_NTOA()` 函数与 [`INET_NTOA()`](#inet_ntoa) 类似，但 `INET6_NTOA()` 还可以处理 IPv6 地址。 ```sql SELECT INET6_NTOA(0x00000000000000000000000000000001); @@ -213,7 +213,7 @@ SELECT INET6_NTOA(0x00000000000000000000000000000001); ### IS_IPV4() -The `IS_IPV4()` function tests whether the given argument is an IPv4 address or not. +`IS_IPV4()` 函数用于判断给定参数是否为 IPv4 地址。 ```sql SELECT IS_IPV4('127.0.0.1'); @@ -243,7 +243,7 @@ SELECT IS_IPV4('300.0.0.1'); ### IS_IPV4_COMPAT() -The `IS_IPV4_COMPAT()` function tests whether the given argument is an IPv4-compatible address. +`IS_IPV4_COMPAT()` 函数用于判断给定参数是否为 IPv4 兼容地址。 ```sql SELECT IS_IPV4_COMPAT(INET6_ATON('::127.0.0.1')); @@ -260,7 +260,7 @@ SELECT IS_IPV4_COMPAT(INET6_ATON('::127.0.0.1')); ### IS_IPV4_MAPPED() -The `IS_IPV4_MAPPED()` function tests whether the given argument is an IPv4-mapped address. +`IS_IPV4_MAPPED()` 函数用于判断给定参数是否为 IPv4 映射地址。 ```sql SELECT IS_IPV4_MAPPED(INET6_ATON('::ffff:127.0.0.1')); @@ -277,7 +277,7 @@ SELECT IS_IPV4_MAPPED(INET6_ATON('::ffff:127.0.0.1')); ### IS_IPV6() -The `IS_IPV6()` function tests whether the given argument is an IPv6 address. +`IS_IPV6()` 函数用于判断给定参数是否为 IPv6 地址。 ```sql SELECT IS_IPV6('::1'); @@ -294,7 +294,7 @@ SELECT IS_IPV6('::1'); ### IS_UUID() -The `IS_UUID()` function tests whether the given argument is a [UUID](/best-practices/uuid.md). +`IS_UUID()` 函数用于判断给定参数是否为 [UUID](/best-practices/uuid.md)。 ```sql SELECT IS_UUID('eb48c08c-eb71-11ee-bacf-5405db7aad56'); @@ -311,7 +311,7 @@ SELECT IS_UUID('eb48c08c-eb71-11ee-bacf-5405db7aad56'); ### NAME_CONST() -The `NAME_CONST()` function is used to name columns. It is recommended to use column aliases instead. +`NAME_CONST()` 函数用于为列命名。推荐使用列别名的方式代替。 ```sql SELECT NAME_CONST('column name', 'value') UNION ALL SELECT 'another value'; @@ -327,7 +327,7 @@ SELECT NAME_CONST('column name', 'value') UNION ALL SELECT 'another value'; 2 rows in set (0.00 sec) ``` -The preceding statement uses `NAME_CONST()` and the following statement uses the recommended way of aliasing columns. +上述语句使用了 `NAME_CONST()`，而下述语句则采用了推荐的列别名方式。 ```sql SELECT 'value' AS 'column name' UNION ALL SELECT 'another value'; @@ -345,7 +345,7 @@ SELECT 'value' AS 'column name' UNION ALL SELECT 'another value'; ### SLEEP() -The `SLEEP()` function is used to pause the execution of queries for a specified number of seconds. +`SLEEP()` 函数用于让查询暂停指定的秒数。 ```sql SELECT SLEEP(1.5); @@ -362,7 +362,7 @@ SELECT SLEEP(1.5); ### UUID() -The `UUID()` function returns a universally unique identifier (UUID) version 1 as defined in [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122). +`UUID()` 函数返回一个符合 [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122) 定义的版本 1 全局唯一标识符（UUID）。 ```sql SELECT UUID(); @@ -377,15 +377,15 @@ SELECT UUID(); 1 row in set (0.00 sec) ``` -See also [Best practices for UUID](/best-practices/uuid.md). +另请参阅 [UUID 最佳实践](/best-practices/uuid.md)。 ### UUID_TO_BIN -See [BIN_TO_UUID()](#bin_to_uuid). +参见 [BIN_TO_UUID()](#bin_to_uuid)。 ### VALUES() -The `VALUES(col_name)` function is used to reference the value of a specific column in the `ON DUPLICATE KEY UPDATE` clause of an [`INSERT`](/sql-statements/sql-statement-insert.md) statement. +`VALUES(col_name)` 函数用于在 [`INSERT`](/sql-statements/sql-statement-insert.md) 语句的 `ON DUPLICATE KEY UPDATE` 子句中引用指定列的值。 ```sql CREATE TABLE t1 (id INT PRIMARY KEY, c1 INT); @@ -412,8 +412,8 @@ TABLE t1; 5 rows in set (0.00 sec) ``` -## Unsupported functions +## 不支持的函数 -| Name | Description | +| 名称 | 描述 | |:------------|:-----------------------------------------------------------------------------------------------| -| [`UUID_SHORT()`](https://dev.mysql.com/doc/refman/8.0/en/miscellaneous-functions.html#function_uuid-short) | Provides a UUID that is unique given certain assumptions not present in TiDB [TiDB #4620](https://github.com/pingcap/tidb/issues/4620) | \ No newline at end of file +| [`UUID_SHORT()`](https://dev.mysql.com/doc/refman/8.0/en/miscellaneous-functions.html#function_uuid-short) | 在特定假设下提供唯一 UUID，但这些假设在 TiDB 中不成立 [TiDB #4620](https://github.com/pingcap/tidb/issues/4620) | \ No newline at end of file diff --git a/functions-and-operators/tidb-functions.md b/functions-and-operators/tidb-functions.md index 82f74b1cf02b5..3ba54e20651d6 100644 --- a/functions-and-operators/tidb-functions.md +++ b/functions-and-operators/tidb-functions.md @@ -1,71 +1,71 @@ --- -title: TiDB Specific Functions -summary: Learn about the usage of TiDB specific functions. +title: TiDB 专有函数 +summary: 了解 TiDB 专有函数的用法。 --- -# TiDB Specific Functions +# TiDB 专有函数 -The following functions are TiDB extensions, and are not present in MySQL: +以下函数是 TiDB 的扩展，在 MySQL 中不存在： -| Function name | Function description | +| 函数名 | 函数描述 | | :-------------- | :------------------------------------- | -| [`CURRENT_RESOURCE_GROUP()`](#current_resource_group) | Returns the name of the resource group that the current session is bound to. See [Use Resource Control to Achieve Resource Group Limitation and Flow Control](/tidb-resource-control-ru-groups.md). | -| [`TIDB_BOUNDED_STALENESS()`](#tidb_bounded_staleness) | Instructs TiDB to read the most recent data within a specified time range. See [reading historical data using the `AS OF TIMESTAMP` clause](/as-of-timestamp.md). | -| [`TIDB_CURRENT_TSO()`](#tidb_current_tso) | Returns the current [TimeStamp Oracle (TSO) in TiDB](/tso.md). | -| [`TIDB_DECODE_BINARY_PLAN()`](#tidb_decode_binary_plan) | Decodes binary plans. | -| [`TIDB_DECODE_KEY()`](#tidb_decode_key) | Decodes a TiDB-encoded key entry into a JSON structure containing `_tidb_rowid` and `table_id`. These encoded keys can be found in some system tables and logging outputs. | -| [`TIDB_DECODE_PLAN()`](#tidb_decode_plan) | Decodes a TiDB execution plan. | -| [`TIDB_DECODE_SQL_DIGESTS()`](#tidb_decode_sql_digests) | Queries the normalized SQL statements (a form without formats and arguments) corresponding to a set of SQL digests in the cluster. | -| [`TIDB_ENCODE_INDEX_KEY()`](#tidb_encode_index_key) | Encodes an index key. | -| [`TIDB_ENCODE_RECORD_KEY()`](#tidb_encode_record_key) | Encodes a record key. | -| [`TIDB_ENCODE_SQL_DIGEST()`](#tidb_encode_sql_digest) | Gets a digest for a query string. | -| [`TIDB_IS_DDL_OWNER()`](#tidb_is_ddl_owner) | Checks whether or not the TiDB instance you are connected to is the DDL Owner. The DDL Owner is the TiDB instance that is tasked with executing DDL statements on behalf of all other nodes in the cluster. | -| [`TIDB_MVCC_INFO()`](#tidb_mvcc_info) | Returns the [MVCC (Multi-Version Concurrency Control)](https://docs.pingcap.com/tidb/stable/glossary#multi-version-concurrency-control-mvcc) information about a key. | -| [`TIDB_PARSE_TSO()`](#tidb_parse_tso) | Extracts the physical timestamp from a TiDB TSO timestamp. See also: [`tidb_current_ts`](/system-variables.md#tidb_current_ts). | -| [`TIDB_PARSE_TSO_LOGICAL()`](#tidb_parse_tso_logical) | Extracts the logical timestamp from a TiDB TSO timestamp. | -| [`TIDB_ROW_CHECKSUM()`](#tidb_row_checksum) | Queries the checksum value of a row. This function can only be used in `SELECT` statements within the FastPlan process. That is, you can query through statements like `SELECT TIDB_ROW_CHECKSUM() FROM t WHERE id = ?` or `SELECT TIDB_ROW_CHECKSUM() FROM t WHERE id IN (?, ?, ...)`. See also: [Data integrity validation for single-row data](/ticdc/ticdc-integrity-check.md). | -| [`TIDB_SHARD()`](#tidb_shard) | Creates a shard index to scatter the index hotspot. A shard index is an expression index with a `TIDB_SHARD` function as the prefix.| -| [`TIDB_VERSION()`](#tidb_version) | Returns the TiDB version with additional build information. | -| [`VITESS_HASH()`](#vitess_hash) | Returns the hash of a number. This function is compatible with the `HASH` function of Vitess, and is intended to help the data migration from Vitess. | +| [`CURRENT_RESOURCE_GROUP()`](#current_resource_group) | 返回当前会话绑定的资源组名称。参见 [使用资源管控实现资源组限制与流控](/tidb-resource-control-ru-groups.md)。 | +| [`TIDB_BOUNDED_STALENESS()`](#tidb_bounded_staleness) | 指示 TiDB 在指定的时间范围内读取最新的数据。参见 [使用 `AS OF TIMESTAMP` 子句读取历史数据](/as-of-timestamp.md)。 | +| [`TIDB_CURRENT_TSO()`](#tidb_current_tso) | 返回当前 [TiDB 的 TimeStamp Oracle (TSO)](/tso.md)。 | +| [`TIDB_DECODE_BINARY_PLAN()`](#tidb_decode_binary_plan) | 解码二进制执行计划。 | +| [`TIDB_DECODE_KEY()`](#tidb_decode_key) | 将 TiDB 编码的 key 条目解码为包含 `_tidb_rowid` 和 `table_id` 的 JSON 结构。这些编码的 key 可在部分系统表和日志输出中找到。 | +| [`TIDB_DECODE_PLAN()`](#tidb_decode_plan) | 解码 TiDB 执行计划。 | +| [`TIDB_DECODE_SQL_DIGESTS()`](#tidb_decode_sql_digests) | 查询集群中一组 SQL 摘要对应的标准化 SQL 语句（无格式和参数的形式）。 | +| [`TIDB_ENCODE_INDEX_KEY()`](#tidb_encode_index_key) | 编码索引 key。 | +| [`TIDB_ENCODE_RECORD_KEY()`](#tidb_encode_record_key) | 编码记录 key。 | +| [`TIDB_ENCODE_SQL_DIGEST()`](#tidb_encode_sql_digest) | 获取查询字符串的摘要。 | +| [`TIDB_IS_DDL_OWNER()`](#tidb_is_ddl_owner) | 检查你所连接的 TiDB 实例是否为 DDL Owner。DDL Owner 是负责代表集群中所有其他节点执行 DDL 语句的 TiDB 实例。 | +| [`TIDB_MVCC_INFO()`](#tidb_mvcc_info) | 返回某个 key 的 [MVCC（多版本并发控制）](https://docs.pingcap.com/tidb/stable/glossary#multi-version-concurrency-control-mvcc) 信息。 | +| [`TIDB_PARSE_TSO()`](#tidb_parse_tso) | 从 TiDB TSO 时间戳中提取物理时间戳。参见：[`tidb_current_ts`](/system-variables.md#tidb_current_ts)。 | +| [`TIDB_PARSE_TSO_LOGICAL()`](#tidb_parse_tso_logical) | 从 TiDB TSO 时间戳中提取逻辑时间戳。 | +| [`TIDB_ROW_CHECKSUM()`](#tidb_row_checksum) | 查询某一行的校验和值。该函数只能在 FastPlan 流程内的 `SELECT` 语句中使用。即，你可以通过 `SELECT TIDB_ROW_CHECKSUM() FROM t WHERE id = ?` 或 `SELECT TIDB_ROW_CHECKSUM() FROM t WHERE id IN (?, ?, ...)` 这样的语句进行查询。参见：[单行数据的数据完整性校验](/ticdc/ticdc-integrity-check.md)。 | +| [`TIDB_SHARD()`](#tidb_shard) | 创建分片索引以打散索引热点。分片索引是以 `TIDB_SHARD` 函数为前缀的表达式索引。| +| [`TIDB_VERSION()`](#tidb_version) | 返回带有额外构建信息的 TiDB 版本。 | +| [`VITESS_HASH()`](#vitess_hash) | 返回数字的哈希值。该函数兼容 Vitess 的 `HASH` 函数，旨在帮助从 Vitess 迁移数据。 | -| Function name | Function description | +| 函数名 | 函数描述 | | :-------------- | :------------------------------------- | -| [`CURRENT_RESOURCE_GROUP()`](#current_resource_group) | Returns the resource group name that the current session is bound to. See [Use Resource Control to Achieve Resource Group Limitation and Flow Control](/tidb-resource-control-ru-groups.md). | -| [`TIDB_BOUNDED_STALENESS()`](#tidb_bounded_staleness) | Instructs TiDB to read most recent data within a specified time range. See [reading historical data using the `AS OF TIMESTAMP` clause](/as-of-timestamp.md). | -| [`TIDB_CURRENT_TSO()`](#tidb_current_tso) | Returns the current [TimeStamp Oracle (TSO) in TiDB](/tso.md). | -| [`TIDB_DECODE_BINARY_PLAN()`](#tidb_decode_binary_plan) | Decodes binary plans. | -| [`TIDB_DECODE_KEY()`](#tidb_decode_key) | Decodes a TiDB-encoded key entry into a JSON structure containing `_tidb_rowid` and `table_id`. These encoded keys can be found in some system tables and logging outputs. | -| [`TIDB_DECODE_PLAN()`](#tidb_decode_plan) | Decodes a TiDB execution plan. | -| [`TIDB_DECODE_SQL_DIGESTS()`](#tidb_decode_sql_digests) | Queries the normalized SQL statements (a form without formats and arguments) corresponding to a set of SQL digests in the cluster. | -| [`TIDB_ENCODE_INDEX_KEY()`](#tidb_encode_index_key) | Encodes an index key. | -| [`TIDB_ENCODE_RECORD_KEY()`](#tidb_encode_record_key) | Encodes a record key. | -| [`TIDB_ENCODE_SQL_DIGEST()`](#tidb_encode_sql_digest) | Gets a digest for a query string. | -| [`TIDB_IS_DDL_OWNER()`](#tidb_is_ddl_owner) | Checks whether or not the TiDB instance you are connected to is the DDL Owner. The DDL Owner is the TiDB instance that is tasked with executing DDL statements on behalf of all other nodes in the cluster. | -| [`TIDB_PARSE_TSO()`](#tidb_parse_tso) | Extracts the physical timestamp from a TiDB TSO timestamp. See also: [`tidb_current_ts`](/system-variables.md#tidb_current_ts). | -| [`TIDB_MVCC_INFO()`](#tidb_mvcc_info) | Returns the [MVCC (Multi-Version Concurrency Control)](https://docs.pingcap.com/tidb/stable/glossary#multi-version-concurrency-control-mvcc) information about a key. | -| [`TIDB_PARSE_TSO_LOGICAL()`](#tidb_parse_tso_logical) | Extracts the logical timestamp from a TiDB TSO timestamp. | -| [`TIDB_ROW_CHECKSUM()`](#tidb_row_checksum) | Queries the checksum value of a row. This function can only be used in `SELECT` statements within the FastPlan process. That is, you can query through statements like `SELECT TIDB_ROW_CHECKSUM() FROM t WHERE id = ?` or `SELECT TIDB_ROW_CHECKSUM() FROM t WHERE id IN (?, ?, ...)`. See also: [Data integrity validation for single-row data](https://docs.pingcap.com/tidb/stable/ticdc-integrity-check). | -| [`TIDB_SHARD()`](#tidb_shard) | Creates a shard index to scatter the index hotspot. A shard index is an expression index with a `TIDB_SHARD` function as the prefix.| -| [`TIDB_VERSION()`](#tidb_version) | Returns the TiDB version with additional build information. | -| [`VITESS_HASH()`](#vitess_hash) | Returns the hash of a number. This function is compatible with the `HASH` function of Vitess, and is intended to help the data migration from Vitess. | +| [`CURRENT_RESOURCE_GROUP()`](#current_resource_group) | 返回当前会话绑定的资源组名称。参见 [使用资源管控实现资源组限制与流控](/tidb-resource-control-ru-groups.md)。 | +| [`TIDB_BOUNDED_STALENESS()`](#tidb_bounded_staleness) | 指示 TiDB 在指定的时间范围内读取最新的数据。参见 [使用 `AS OF TIMESTAMP` 子句读取历史数据](/as-of-timestamp.md)。 | +| [`TIDB_CURRENT_TSO()`](#tidb_current_tso) | 返回当前 [TiDB 的 TimeStamp Oracle (TSO)](/tso.md)。 | +| [`TIDB_DECODE_BINARY_PLAN()`](#tidb_decode_binary_plan) | 解码二进制执行计划。 | +| [`TIDB_DECODE_KEY()`](#tidb_decode_key) | 将 TiDB 编码的 key 条目解码为包含 `_tidb_rowid` 和 `table_id` 的 JSON 结构。这些编码的 key 可在部分系统表和日志输出中找到。 | +| [`TIDB_DECODE_PLAN()`](#tidb_decode_plan) | 解码 TiDB 执行计划。 | +| [`TIDB_DECODE_SQL_DIGESTS()`](#tidb_decode_sql_digests) | 查询集群中一组 SQL 摘要对应的标准化 SQL 语句（无格式和参数的形式）。 | +| [`TIDB_ENCODE_INDEX_KEY()`](#tidb_encode_index_key) | 编码索引 key。 | +| [`TIDB_ENCODE_RECORD_KEY()`](#tidb_encode_record_key) | 编码记录 key。 | +| [`TIDB_ENCODE_SQL_DIGEST()`](#tidb_encode_sql_digest) | 获取查询字符串的摘要。 | +| [`TIDB_IS_DDL_OWNER()`](#tidb_is_ddl_owner) | 检查你所连接的 TiDB 实例是否为 DDL Owner。DDL Owner 是负责代表集群中所有其他节点执行 DDL 语句的 TiDB 实例。 | +| [`TIDB_PARSE_TSO()`](#tidb_parse_tso) | 从 TiDB TSO 时间戳中提取物理时间戳。参见：[`tidb_current_ts`](/system-variables.md#tidb_current_ts)。 | +| [`TIDB_MVCC_INFO()`](#tidb_mvcc_info) | 返回某个 key 的 [MVCC（多版本并发控制）](https://docs.pingcap.com/tidb/stable/glossary#multi-version-concurrency-control-mvcc) 信息。 | +| [`TIDB_PARSE_TSO_LOGICAL()`](#tidb_parse_tso_logical) | 从 TiDB TSO 时间戳中提取逻辑时间戳。 | +| [`TIDB_ROW_CHECKSUM()`](#tidb_row_checksum) | 查询某一行的校验和值。该函数只能在 FastPlan 流程内的 `SELECT` 语句中使用。即，你可以通过 `SELECT TIDB_ROW_CHECKSUM() FROM t WHERE id = ?` 或 `SELECT TIDB_ROW_CHECKSUM() FROM t WHERE id IN (?, ?, ...)` 这样的语句进行查询。参见：[单行数据的数据完整性校验](https://docs.pingcap.com/tidb/stable/ticdc-integrity-check)。 | +| [`TIDB_SHARD()`](#tidb_shard) | 创建分片索引以打散索引热点。分片索引是以 `TIDB_SHARD` 函数为前缀的表达式索引。| +| [`TIDB_VERSION()`](#tidb_version) | 返回带有额外构建信息的 TiDB 版本。 | +| [`VITESS_HASH()`](#vitess_hash) | 返回数字的哈希值。该函数兼容 Vitess 的 `HASH` 函数，旨在帮助从 Vitess 迁移数据。 | ## CURRENT_RESOURCE_GROUP -The `CURRENT_RESOURCE_GROUP()` function is used to show the resource group name that the current session is bound to. When the [Resource control](/tidb-resource-control-ru-groups.md) feature is enabled, the available resources that can be used by SQL statements are restricted by the resource quota of the bound resource group. +`CURRENT_RESOURCE_GROUP()` 函数用于显示当前会话绑定的资源组名称。当启用 [资源管控](/tidb-resource-control-ru-groups.md) 功能时，SQL 语句可用的资源会受到所绑定资源组的资源配额限制。 -When a session is established, TiDB binds the session to the resource group that the login user is bound to by default. If the user is not bound to any resource groups, the session is bound to the `default` resource group. Once the session is established, the bound resource group will not change by default, even if the bound resource group of the user is changed via [modifying the resource group bound to the user](/sql-statements/sql-statement-alter-user.md#modify-basic-user-information). To change the bound resource group of the current session, you can use [`SET RESOURCE GROUP`](/sql-statements/sql-statement-set-resource-group.md). +当会话建立时，TiDB 默认将会话绑定到登录用户所绑定的资源组。如果用户未绑定任何资源组，则会话绑定到 `default` 资源组。会话建立后，默认情况下绑定的资源组不会改变，即使通过 [修改用户绑定的资源组](/sql-statements/sql-statement-alter-user.md#modify-basic-user-information) 更改了用户的资源组。要更改当前会话绑定的资源组，可以使用 [`SET RESOURCE GROUP`](/sql-statements/sql-statement-set-resource-group.md)。 -Examples: +示例： -Create a user `user1`, create two resource groups `rg1` and `rg2`, and bind the user `user1` to the resource group `rg1`: +创建用户 `user1`，创建两个资源组 `rg1` 和 `rg2`，并将用户 `user1` 绑定到资源组 `rg1`： ```sql CREATE USER 'user1'; @@ -74,7 +74,7 @@ CREATE RESOURCE GROUP rg2 RU_PER_SEC = 2000; ALTER USER 'user1' RESOURCE GROUP `rg1`; ``` -Use `user1` to log in and view the resource group bound to the current user: +使用 `user1` 登录并查看当前用户绑定的资源组： ```sql SELECT CURRENT_RESOURCE_GROUP(); @@ -89,7 +89,7 @@ SELECT CURRENT_RESOURCE_GROUP(); 1 row in set (0.00 sec) ``` -Execute `SET RESOURCE GROUP` to set the resource group for the current session to `rg2`, and then view the resource group bound to the current user: +执行 `SET RESOURCE GROUP` 将当前会话的资源组设置为 `rg2`，然后查看当前用户绑定的资源组： ```sql SET RESOURCE GROUP `rg2`; @@ -107,11 +107,11 @@ SELECT CURRENT_RESOURCE_GROUP(); ## TIDB_BOUNDED_STALENESS -The `TIDB_BOUNDED_STALENESS()` function is used as part of [`AS OF TIMESTAMP`](/as-of-timestamp.md) syntax. +`TIDB_BOUNDED_STALENESS()` 函数作为 [`AS OF TIMESTAMP`](/as-of-timestamp.md) 语法的一部分使用。 ## TIDB_CURRENT_TSO -The `TIDB_CURRENT_TSO()` function returns the [TSO](/tso.md) for the current transaction. This is similar to the [`tidb_current_ts`](/system-variables.md#tidb_current_ts) system variable. +`TIDB_CURRENT_TSO()` 函数返回当前事务的 [TSO](/tso.md)。这类似于 [`tidb_current_ts`](/system-variables.md#tidb_current_ts) 系统变量。 ```sql BEGIN; @@ -149,11 +149,11 @@ SELECT @@tidb_current_ts; ## TIDB_DECODE_BINARY_PLAN -The `TIDB_DECODE_BINARY_PLAN(binary_plan)` function decodes binary plans, like the ones in the `BINARY_PLAN` column of the [`STATEMENTS_SUMMARY`](/statement-summary-tables.md) table. +`TIDB_DECODE_BINARY_PLAN(binary_plan)` 函数用于解码二进制执行计划，例如 [`STATEMENTS_SUMMARY`](/statement-summary-tables.md) 表中的 `BINARY_PLAN` 列。 -The [`tidb_generate_binary_plan`](/system-variables.md#tidb_generate_binary_plan-new-in-v620) variable must be set to `ON` for the binary plans to be available. +要使二进制执行计划可用，必须将 [`tidb_generate_binary_plan`](/system-variables.md#tidb_generate_binary_plan-new-in-v620) 变量设置为 `ON`。 -Example: +示例： ```sql SELECT BINARY_PLAN,TIDB_DECODE_BINARY_PLAN(BINARY_PLAN) FROM information_schema.STATEMENTS_SUMMARY LIMIT 1\G @@ -172,9 +172,9 @@ TIDB_DECODE_BINARY_PLAN(BINARY_PLAN): ## TIDB_DECODE_KEY -The `TIDB_DECODE_KEY()` function decodes a TiDB-encoded key entry into a JSON structure containing `_tidb_rowid` and `table_id`. These encoded keys exist in some system tables and logging outputs. +`TIDB_DECODE_KEY()` 函数将 TiDB 编码的 key 条目解码为包含 `_tidb_rowid` 和 `table_id` 的 JSON 结构。这些编码的 key 存在于部分系统表和日志输出中。 -In the following example, the table `t1` has a hidden `rowid` that is generated by TiDB. The `TIDB_DECODE_KEY()` function is used in the statement. From the result, you can see that the hidden `rowid` is decoded and output, which is a typical result for the non-clustered primary key. +在以下示例中，表 `t1` 有一个由 TiDB 生成的隐藏 `rowid`。在语句中使用了 `TIDB_DECODE_KEY()` 函数。从结果可以看到，隐藏的 `rowid` 被解码并输出，这是非聚簇主键的典型结果。 ```sql SELECT START_KEY, TIDB_DECODE_KEY(START_KEY) FROM information_schema.tikv_region_status WHERE table_name='t1' AND REGION_ID=2\G @@ -187,7 +187,7 @@ TIDB_DECODE_KEY(START_KEY): {"_tidb_rowid":1958897,"table_id":"59"} 1 row in set (0.00 sec) ``` -In the following example, the table `t2` has a compound clustered primary key. From the JSON output, you can see a `handle` that contains the name and value for both of the columns that are part of the primary key. +在以下示例中，表 `t2` 有一个复合聚簇主键。从 JSON 输出可以看到 `handle`，其中包含主键中各列的名称和值。 ```sql SHOW CREATE TABLE t2\G @@ -244,7 +244,7 @@ SELECT tidb_decode_key('7480000000000000FF3E5F720400000000FF0000000601633430FF33 1 row in set (0.001 sec) ``` -In the following example, the first Region of a table starts with a key that only has the `table_id` of the table. The last Region of the table ends with `table_id + 1`. Any Regions in between have longer keys that includes a `_tidb_rowid` or `handle`. +在以下示例中，表的第一个 Region 以仅包含该表 `table_id` 的 key 开始。表的最后一个 Region 以 `table_id + 1` 结束。中间的 Region key 更长，包含 `_tidb_rowid` 或 `handle`。 ```sql SELECT @@ -272,13 +272,13 @@ ORDER BY 4 rows in set (0.031 sec) ``` -`TIDB_DECODE_KEY` returns valid JSON on success and returns the argument value if it fails to decode. +`TIDB_DECODE_KEY` 解码成功时返回有效的 JSON，解码失败时返回参数值本身。 ## TIDB_DECODE_PLAN -You can find TiDB execution plans in encoded form in the slow query log. The `TIDB_DECODE_PLAN()` function is then used to decode the encoded plans into a human-readable form. +你可以在慢查询日志中找到编码形式的 TiDB 执行计划。`TIDB_DECODE_PLAN()` 函数可用于将编码的执行计划解码为可读形式。 -This function is useful because a plan is captured at the time the statement is executed. Re-executing the statement in `EXPLAIN` might produce different results as data distribution and statistics evolves over time. +该函数的作用在于，执行计划是在语句执行时捕获的。重新用 `EXPLAIN` 执行语句可能会因为数据分布和统计信息的变化而产生不同的结果。 ```sql SELECT tidb_decode_plan('8QIYMAkzMV83CQEH8E85LjA0CWRhdGE6U2VsZWN0aW9uXzYJOTYwCXRpbWU6NzEzLjHCtXMsIGxvb3BzOjIsIGNvcF90YXNrOiB7bnVtOiAxLCBtYXg6IDU2OC41wgErRHByb2Nfa2V5czogMCwgcnBjXxEpAQwFWBAgNTQ5LglZyGNvcHJfY2FjaGVfaGl0X3JhdGlvOiAwLjAwfQkzLjk5IEtCCU4vQQoxCTFfNgkxXzAJMwm2SGx0KHRlc3QudC5hLCAxMDAwMCkNuQRrdgmiAHsFbBQzMTMuOMIBmQnEDDk2MH0BUgEEGAoyCTQzXzUFVwX1oGFibGU6dCwga2VlcCBvcmRlcjpmYWxzZSwgc3RhdHM6cHNldWRvCTk2ISE2aAAIMTUzXmYA')\G @@ -294,19 +294,19 @@ SELECT tidb_decode_plan('8QIYMAkzMV83CQEH8E85LjA0CWRhdGE6U2VsZWN0aW9uXzYJOTYwCXR ## TIDB_DECODE_SQL_DIGESTS -The `TIDB_DECODE_SQL_DIGESTS()` function is used to query the normalized SQL statements (a form without formats and arguments) corresponding to the set of SQL digests in the cluster. This function accepts 1 or 2 arguments: +`TIDB_DECODE_SQL_DIGESTS()` 函数用于查询集群中一组 SQL 摘要对应的标准化 SQL 语句（无格式和参数的形式）。该函数接受 1 或 2 个参数： -* `digests`: A string. This parameter is in the format of a JSON string array, and each string in the array is a SQL digest. -* `stmtTruncateLength`: An integer (optional). It is used to limit the length of each SQL statement in the returned result. If a SQL statement exceeds the specified length, the statement is truncated. `0` means that the length is unlimited. +* `digests`：字符串。该参数为 JSON 字符串数组格式，数组中的每个字符串为一个 SQL 摘要。 +* `stmtTruncateLength`：整数（可选）。用于限制返回结果中每条 SQL 语句的长度。如果某条 SQL 语句超过指定长度，则会被截断。`0` 表示长度不受限制。 -This function returns a string, which is in the format of a JSON string array. The *i*-th item in the array is the normalized SQL statement corresponding to the *i*-th element in the `digests` parameter. If an element in the `digests` parameter is not a valid SQL digest or the system cannot find the corresponding SQL statement, the corresponding item in the returned result is `null`. If the truncation length is specified (`stmtTruncateLength > 0`), for each statement in the returned result that exceeds this length, the first `stmtTruncateLength` characters are retained and the suffix `"..."` is added at the end to indicate the truncation. If the `digests` parameter is `NULL`, the returned value of the function is `NULL`. +该函数返回一个字符串，格式为 JSON 字符串数组。数组中的第 *i* 项为 `digests` 参数中第 *i* 个元素对应的标准化 SQL 语句。如果 `digests` 参数中的某个元素不是有效的 SQL 摘要，或系统无法找到对应的 SQL 语句，则返回结果中对应项为 `null`。如果指定了截断长度（`stmtTruncateLength > 0`），则返回结果中每条超出该长度的语句只保留前 `stmtTruncateLength` 个字符，并在末尾添加 `"..."` 表示被截断。如果 `digests` 参数为 `NULL`，则函数返回值为 `NULL`。 -> **Note:** +> **注意：** > -> * Only users with the [PROCESS](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_process) privilege can use this function. -> * When `TIDB_DECODE_SQL_DIGESTS` is executed, TiDB queries the statement corresponding to each SQL digest from the statement summary tables, so there is no guarantee that the corresponding statement can always be found for any SQL digest. Only the statements that have been executed in the cluster can be found, and whether these SQL statements can be queried or not is also affected by the related configuration of the statement summary tables. For the detailed description of the statement summary table, see [Statement Summary Tables](/statement-summary-tables.md). -> * This function has a high overhead. In queries with a large number of rows (for example, querying the full table of `information_schema.cluster_tidb_trx` on a large and busy cluster), using this function might cause the queries to run for too long. Use it with caution. -> * This function has a high overhead because every time it is called, it internally queries the `STATEMENTS_SUMMARY`, `STATEMENTS_SUMMARY_HISTORY`, `CLUSTER_STATEMENTS_SUMMARY`, and `CLUSTER_STATEMENTS_SUMMARY_HISTORY` tables, and the query involves the `UNION` operation. This function currently does not support vectorization, that is, when calling this function for multiple rows of data, the above query is performed separately for each row. +> * 只有拥有 [PROCESS](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_process) 权限的用户才能使用该函数。 +> * 执行 `TIDB_DECODE_SQL_DIGESTS` 时，TiDB 会从语句概要表中查询每个 SQL 摘要对应的语句，因此不能保证任何 SQL 摘要都能查到对应的语句。只能查到集群中已执行过的语句，且能否查询到还受语句概要表相关配置影响。关于语句概要表的详细说明，参见 [语句概要表](/statement-summary-tables.md)。 +> * 该函数开销较大。在大数据量场景下（如在大型繁忙集群上查询 `information_schema.cluster_tidb_trx` 全表），使用该函数可能导致查询耗时过长，请谨慎使用。 +> * 该函数开销较大，是因为每次调用时，内部都会查询 `STATEMENTS_SUMMARY`、`STATEMENTS_SUMMARY_HISTORY`、`CLUSTER_STATEMENTS_SUMMARY` 和 `CLUSTER_STATEMENTS_SUMMARY_HISTORY` 表，并涉及 `UNION` 操作。该函数目前不支持向量化，即对多行数据调用时，每行都会单独执行上述查询。 ```sql SET @digests = '["e6f07d43b5c21db0fbb9a31feac2dc599787763393dd5acbfad80e247eb02ad5","38b03afa5debbdf0326a014dbe5012a62c51957f1982b3093e748460f8b00821","e5796985ccafe2f71126ed6c0ac939ffa015a8c0744a24b7aee6d587103fd2f7"]'; @@ -323,7 +323,7 @@ SELECT TIDB_DECODE_SQL_DIGESTS(@digests); 1 row in set (0.00 sec) ``` -In the above example, the parameter is a JSON array containing 3 SQL digests, and the corresponding SQL statements are the three items in the query results. But the SQL statement corresponding to the second SQL digest cannot be found from the cluster, so the second item in the result is `null`. +上述示例中，参数为包含 3 个 SQL 摘要的 JSON 数组，查询结果中对应的 SQL 语句为三项。但第二个 SQL 摘要在集群中查不到对应语句，因此结果中第二项为 `null`。 ```sql SELECT TIDB_DECODE_SQL_DIGESTS(@digests, 10); @@ -338,18 +338,18 @@ SELECT TIDB_DECODE_SQL_DIGESTS(@digests, 10); 1 row in set (0.01 sec) ``` -The above call specifies the second parameter (that is, the truncation length) as 10, and the length of the third statement in the query result is greater than 10. Therefore, only the first 10 characters are retained, and `"..."` is added at the end, which indicates the truncation. +上述调用指定了第二个参数（即截断长度）为 10，查询结果中第三条语句长度大于 10，因此只保留前 10 个字符，并在末尾添加 `"..."`，表示被截断。 -See also: +参见： -- [Statement summary tables](/statement-summary-tables.md) +- [语句概要表](/statement-summary-tables.md) - [`INFORMATION_SCHEMA.TIDB_TRX`](/information-schema/information-schema-tidb-trx.md) ## TIDB_ENCODE_SQL_DIGEST -The `TIDB_ENCODE_SQL_DIGEST(query_str)` returns the SQL digest for a query string. +`TIDB_ENCODE_SQL_DIGEST(query_str)` 返回查询字符串的 SQL 摘要。 -In the following example you can see that both queries get the same query digest, which is because the digest will be `select ?` for both of them. +在以下示例中可以看到，两条查询语句得到相同的查询摘要，因为它们的摘要都是 `select ?`。 ```sql SELECT TIDB_ENCODE_SQL_DIGEST('SELECT 1'); @@ -379,7 +379,7 @@ SELECT TIDB_ENCODE_SQL_DIGEST('SELECT 2'); ## TIDB_IS_DDL_OWNER -The `TIDB_IS_DDL_OWNER()` function returns `1` if the instance you are connected to is the DDL owner. +`TIDB_IS_DDL_OWNER()` 函数如果你所连接的实例为 DDL owner，则返回 `1`。 ```sql SELECT TIDB_IS_DDL_OWNER(); @@ -396,12 +396,12 @@ SELECT TIDB_IS_DDL_OWNER(); ## TIDB_PARSE_TSO -The `TIDB_PARSE_TSO()` function extracts the physical timestamp from a TiDB TSO timestamp. [TSO](/tso.md) stands for Time Stamp Oracle and is a monotonically increasing timestamp given out by PD (Placement Driver) for every transaction. +`TIDB_PARSE_TSO()` 函数用于从 TiDB TSO 时间戳中提取物理时间戳。[TSO](/tso.md) 即 Time Stamp Oracle，是 PD（Placement Driver）为每个事务分配的单调递增时间戳。 -A TSO is a number that consists of two parts: +TSO 是一个由两部分组成的数字： -- A physical timestamp -- A logical counter +- 物理时间戳 +- 逻辑计数器 ```sql BEGIN; @@ -418,11 +418,11 @@ ROLLBACK; 1 row in set (0.0012 sec) ``` -Here `TIDB_PARSE_TSO` is used to extract the physical timestamp from the timestamp number that is available in the `tidb_current_ts` session variable. Because timestamps are given out per transaction, this function is running in a transaction. +这里 `TIDB_PARSE_TSO` 用于从 `tidb_current_ts` 会话变量中的时间戳数字提取物理时间戳。由于时间戳是按事务分配的，因此该函数需在事务中运行。 ## TIDB_PARSE_TSO_LOGICAL -The `TIDB_PARSE_TSO_LOGICAL(tso)` function returns the logical part of a [TSO](/tso.md) timestamp. +`TIDB_PARSE_TSO_LOGICAL(tso)` 函数返回 [TSO](/tso.md) 时间戳的逻辑部分。 ```sql SELECT TIDB_PARSE_TSO_LOGICAL(450456244814610433); @@ -452,17 +452,17 @@ SELECT TIDB_PARSE_TSO_LOGICAL(450456244814610434); ## TIDB_ROW_CHECKSUM -The `TIDB_ROW_CHECKSUM()` function is used to query the checksum value of a row. This function can only be used in `SELECT` statements within the FastPlan process. That is, you can query through statements like `SELECT TIDB_ROW_CHECKSUM() FROM t WHERE id = ?` or `SELECT TIDB_ROW_CHECKSUM() FROM t WHERE id IN (?, ?, ...)`. +`TIDB_ROW_CHECKSUM()` 函数用于查询某一行的校验和值。该函数只能在 FastPlan 流程内的 `SELECT` 语句中使用。即，你可以通过 `SELECT TIDB_ROW_CHECKSUM() FROM t WHERE id = ?` 或 `SELECT TIDB_ROW_CHECKSUM() FROM t WHERE id IN (?, ?, ...)` 这样的语句进行查询。 -To enable the checksum feature of single-row data in TiDB (controlled by the system variable [`tidb_enable_row_level_checksum`](/system-variables.md#tidb_enable_row_level_checksum-new-in-v710)), run the following statement: +要启用 TiDB 单行数据的校验和功能（由系统变量 [`tidb_enable_row_level_checksum`](/system-variables.md#tidb_enable_row_level_checksum-new-in-v710) 控制），可执行如下语句： ```sql SET GLOBAL tidb_enable_row_level_checksum = ON; ``` -This configuration only takes effect for newly created sessions, so you need to reconnect to TiDB. +该配置仅对新建会话生效，因此需要重新连接 TiDB。 -Create table `t` and insert data: +创建表 `t` 并插入数据： ```sql USE test; @@ -470,13 +470,13 @@ CREATE TABLE t (id INT PRIMARY KEY, k INT, c CHAR(1)); INSERT INTO t VALUES (1, 10, 'a'); ``` -The following statement shows how to query the checksum value of the row where `id = 1` in table `t`: +以下语句展示了如何查询表 `t` 中 `id = 1` 行的校验和值： ```sql SELECT *, TIDB_ROW_CHECKSUM() FROM t WHERE id = 1; ``` -The output is as follows: +输出如下： ```sql +----+------+------+---------------------+ @@ -489,41 +489,41 @@ The output is as follows: ## TIDB_SHARD -The `TIDB_SHARD()` function creates a shard index to scatter the index hotspot. A shard index is an expression index prefixed with a `TIDB_SHARD()` function. +`TIDB_SHARD()` 函数用于创建分片索引以打散索引热点。分片索引是以 `TIDB_SHARD()` 函数为前缀的表达式索引。 -- Creation: +- 创建方式： - To create a shard index for the index field `a`, you can use `uk((tidb_shard(a)), a))`. When there is a hotspot caused by monotonically increasing or decreasing data on the index field `a` in the unique secondary index `uk((tidb_shard(a)), a))`, the index's prefix `tidb_shard(a)` can scatter the hotspot to improve the scalability of the cluster. + 若要为索引字段 `a` 创建分片索引，可以使用 `uk((tidb_shard(a)), a))`。当唯一二级索引 `uk((tidb_shard(a)), a))` 的索引字段 `a` 上因数据单调递增或递减导致热点时，索引前缀 `tidb_shard(a)` 可打散热点，提高集群扩展性。 -- Scenarios: +- 适用场景： - - There is a write hotspot caused by monotonically increasing or decreasing keys on the unique secondary index, and the index contains integer type fields. - - The SQL statement executes an equality query based on all fields of the secondary index, either as a separate `SELECT` or as an internal query generated by `UPDATE`, `DELETE` and so on. The equality query includes two ways: `a = 1` or `a IN (1, 2, ......)`. + - 唯一二级索引上因 key 单调递增或递减导致写入热点，且索引包含整型字段。 + - SQL 语句基于二级索引所有字段执行等值查询，无论是单独的 `SELECT`，还是 `UPDATE`、`DELETE` 等内部生成的查询。等值查询包括 `a = 1` 或 `a IN (1, 2, ......)` 两种方式。 -- Limitations: +- 限制说明： - - Cannot be used in inequality queries. - - Cannot be used in queries that contain `OR` mixed with an outmost `AND` operator. - - Cannot be used in the `GROUP BY` clause. - - Cannot be used in the `ORDER BY` clause. - - Cannot be used in the `ON` clause. - - Cannot be used in the `WHERE` subquery. - - Can be used to scatter unique indexes of only the integer fields. - - Might not take effect in composite indexes. - - Cannot go through FastPlan process, which affects optimizer performance. - - Cannot be used to prepare the execution plan cache. + - 不能用于不等值查询。 + - 不能用于包含外层 `AND` 运算符混合 `OR` 的查询。 + - 不能用于 `GROUP BY` 子句。 + - 不能用于 `ORDER BY` 子句。 + - 不能用于 `ON` 子句。 + - 不能用于 `WHERE` 子查询。 + - 只能用于打散整型字段的唯一索引。 + - 在复合索引中可能不生效。 + - 不能走 FastPlan 流程，影响优化器性能。 + - 不能用于准备执行计划缓存。 -The following example shows how to use the `TIDB_SHARD()` function. +以下示例展示了如何使用 `TIDB_SHARD()` 函数。 -- Use the `TIDB_SHARD()` function to calculate the SHARD value. +- 使用 `TIDB_SHARD()` 函数计算 SHARD 值。 - The following statement shows how to use the `TIDB_SHARD()` function to calculate the SHARD value of `12373743746`: + 以下语句展示了如何使用 `TIDB_SHARD()` 函数计算 `12373743746` 的 SHARD 值： ```sql SELECT TIDB_SHARD(12373743746); ``` -- The SHARD value is: +- SHARD 值为： ```sql +-------------------------+ @@ -534,7 +534,7 @@ The following example shows how to use the `TIDB_SHARD()` function. 1 row in set (0.00 sec) ``` -- Create a shard index using the `TIDB_SHARD()` function: +- 使用 `TIDB_SHARD()` 函数创建分片索引： ```sql CREATE TABLE test(id INT PRIMARY KEY CLUSTERED, a INT, b INT, UNIQUE KEY uk((tidb_shard(a)), a)); @@ -542,7 +542,7 @@ The following example shows how to use the `TIDB_SHARD()` function. ## TIDB_VERSION -The `TIDB_VERSION()` function is used to get the version and build details of the TiDB server that you are connected to. You can use this function when reporting issues on GitHub. +`TIDB_VERSION()` 函数用于获取你所连接的 TiDB 服务器的版本和构建详情。你可以在 GitHub 上报告问题时使用该函数。 ```sql SELECT TIDB_VERSION()\G @@ -550,11 +550,11 @@ SELECT TIDB_VERSION()\G ```sql *************************** 1. row *************************** -TIDB_VERSION(): Release Version: {{{ .tidb-version }}} +TIDB_VERSION(): Release Version: vv8.5.2 Edition: Community Git Commit Hash: 821e491a20fbab36604b36b647b5bae26a2c1418 Git Branch: HEAD -UTC Build Time: {{{ .tidb-release-date }}} 19:16:25 +UTC Build Time: 2025-06-12 19:16:25 GoVersion: go1.21.10 Race Enabled: false Check Table Before Drop: false @@ -564,9 +564,9 @@ Store: tikv ## VITESS_HASH -The `VITESS_HASH(num)` function is used to hash a number in the same way Vitess does this. This is to aid migration from Vitess to TiDB. +`VITESS_HASH(num)` 函数用于以 Vitess 的方式对数字进行哈希。该函数用于从 Vitess 迁移到 TiDB 时的数据兼容。 -Example: +示例： ```sql SELECT VITESS_HASH(123); @@ -583,7 +583,7 @@ SELECT VITESS_HASH(123); ## TIDB_ENCODE_INDEX_KEY -Encodes an index key. +编码索引 key。 ```sql CREATE TABLE t(id int PRIMARY KEY, a int, KEY `idx` (a)); @@ -616,7 +616,7 @@ SELECT TIDB_ENCODE_INDEX_KEY('test', 't', 'idx', 1, 1); ## TIDB_ENCODE_RECORD_KEY -Encodes a record key. +编码记录 key。 ```sql CREATE TABLE t(id int PRIMARY KEY, a int, KEY `idx` (a)); @@ -662,7 +662,7 @@ SELECT TIDB_DECODE_KEY('7480000000000000845f728000000000000001'); ## TIDB_MVCC_INFO -Returns the [MVCC (Multi-Version Concurrency Control)](https://docs.pingcap.com/tidb/stable/glossary#multi-version-concurrency-control-mvcc) information for a key. You can use the [`TIDB_ENCODE_INDEX_KEY`](#tidb_encode_index_key) function to obtain a key. +返回某个 key 的 [MVCC（多版本并发控制）](https://docs.pingcap.com/tidb/stable/glossary#multi-version-concurrency-control-mvcc) 信息。你可以使用 [`TIDB_ENCODE_INDEX_KEY`](#tidb_encode_index_key) 函数获取 key。 ```sql SELECT JSON_PRETTY(TIDB_MVCC_INFO('74800000000000007f5f698000000000000001038000000000000001038000000000000001')) AS info\G @@ -693,4 +693,4 @@ info: [ } ] 1 row in set (0.00 sec) -``` +``` \ No newline at end of file diff --git a/garbage-collection-configuration.md b/garbage-collection-configuration.md index 3d5cc532df7a6..32ace282ae38a 100644 --- a/garbage-collection-configuration.md +++ b/garbage-collection-configuration.md @@ -1,81 +1,75 @@ --- -title: Garbage Collection Configuration -summary: Learn about GC configuration parameters. +title: 垃圾回收配置 +summary: 了解 GC 配置参数。 --- -# Garbage Collection Configuration +# 垃圾回收配置 -You can configure garbage collection (GC) using the following system variables: +你可以通过以下系统变量配置垃圾回收（GC）： -* [`tidb_gc_enable`](/system-variables.md#tidb_gc_enable-new-in-v50): controls whether to enable garbage collection for TiKV. -* [`tidb_gc_run_interval`](/system-variables.md#tidb_gc_run_interval-new-in-v50): specifies the GC interval. -* [`tidb_gc_life_time`](/system-variables.md#tidb_gc_life_time-new-in-v50): specifies the time limit during which data is retained for each GC. -* [`tidb_gc_concurrency`](/system-variables.md#tidb_gc_concurrency-new-in-v50): specifies the number of threads in the [Resolve Locks](/garbage-collection-overview.md#resolve-locks) step of GC. -* [`tidb_gc_scan_lock_mode`](/system-variables.md#tidb_gc_scan_lock_mode-new-in-v50): specifies the way of scanning locks in the Resolve Locks step of GC. -* [`tidb_gc_max_wait_time`](/system-variables.md#tidb_gc_max_wait_time-new-in-v610): specifies the maximum time that active transactions block the GC safe point. +* [`tidb_gc_enable`](/system-variables.md#tidb_gc_enable-new-in-v50)：控制是否为 TiKV 启用垃圾回收。 +* [`tidb_gc_run_interval`](/system-variables.md#tidb_gc_run_interval-new-in-v50)：指定 GC 的运行间隔。 +* [`tidb_gc_life_time`](/system-variables.md#tidb_gc_life_time-new-in-v50)：指定每次 GC 保留数据的时间上限。 +* [`tidb_gc_concurrency`](/system-variables.md#tidb_gc_concurrency-new-in-v50)：指定 GC 的 [Resolve Locks](/garbage-collection-overview.md#resolve-locks) 步骤中线程的数量。 +* [`tidb_gc_scan_lock_mode`](/system-variables.md#tidb_gc_scan_lock_mode-new-in-v50)：指定 GC 的 Resolve Locks 步骤中扫描锁的方式。 +* [`tidb_gc_max_wait_time`](/system-variables.md#tidb_gc_max_wait_time-new-in-v610)：指定活跃事务阻塞 GC safe point 的最长时间。 -For more information about how to modify the value of a system variable, see [System variables](/system-variables.md). +关于如何修改系统变量的值，详见 [系统变量](/system-variables.md)。 -## GC I/O limit +## GC I/O 限制 > **Note:** > -> This section is only applicable to TiDB Self-Managed. TiDB Cloud does not have a GC I/O limit by default. +> 本节仅适用于 TiDB 自建集群。TiDB Cloud 默认没有 GC I/O 限制。 -TiKV supports the GC I/O limit. You can configure `gc.max-write-bytes-per-sec` to limit writes of a GC worker per second, and thus to reduce the impact on normal requests. +TiKV 支持 GC I/O 限制。你可以通过配置 `gc.max-write-bytes-per-sec`，限制每秒 GC worker 的写入量，从而减少对正常请求的影响。 -`0` indicates disabling this feature. +`0` 表示禁用此功能。 -You can dynamically modify this configuration using tikv-ctl: - -{{< copyable "shell-regular" >}} +你可以使用 tikv-ctl 动态修改该配置： ```bash tikv-ctl --host=ip:port modify-tikv-config -n gc.max-write-bytes-per-sec -v 10MB ``` -## Changes in TiDB 5.0 +## TiDB 5.0 的变更 -In previous releases of TiDB, garbage collection was configured via the `mysql.tidb` system table. While changes to this table continue to be supported, it is recommended to use the system variables provided. This helps ensure that any changes to configuration can be validated, and prevent unexpected behavior ([#20655](https://github.com/pingcap/tidb/issues/20655)). +在 TiDB 早期版本中，垃圾回收通过 `mysql.tidb` 系统表进行配置。虽然对该表的修改仍然受支持，但推荐使用提供的系统变量进行配置。这样可以确保配置变更能够被校验，并防止出现意外行为（[#20655](https://github.com/pingcap/tidb/issues/20655)）。 -The `CENTRAL` garbage collection mode is no longer supported. The `DISTRIBUTED` GC mode (which has been the default since TiDB 3.0) will automatically be used in its place. This mode is more efficient, since TiDB no longer needs to send requests to each TiKV region to trigger garbage collection. +`CENTRAL` 垃圾回收模式已不再支持。将自动使用 `DISTRIBUTED` GC 模式（自 TiDB 3.0 起为默认模式）。该模式更高效，因为 TiDB 不再需要向每个 TiKV region 发送请求来触发垃圾回收。 -For information on changes in previous releases, refer to earlier versions of this document using the _TIDB version selector_ in the left hand menu. +关于早期版本的变更信息，请通过左侧菜单的 _TIDB 版本选择器_ 查看本文件的历史版本。 -## Changes in TiDB 6.1.0 +## TiDB 6.1.0 的变更 -Before TiDB v6.1.0, the transaction in TiDB does not affect the GC safe point. Starting from v6.1.0, TiDB considers the startTS of the transaction when calculating the GC safe point, to resolve the problem that the data to be accessed has been cleared. If the transaction is too long, the safe point will be blocked for a long time, which affects the application performance. +在 TiDB v6.1.0 之前，TiDB 中的事务不会影响 GC safe point。从 v6.1.0 开始，TiDB 在计算 GC safe point 时会考虑事务的 startTS，以解决访问数据已被清理的问题。如果事务持续时间过长，safe point 会被长时间阻塞，进而影响应用性能。 -In TiDB v6.1.0, the system variable [`tidb_gc_max_wait_time`](/system-variables.md#tidb_gc_max_wait_time-new-in-v610) is introduced to control the maximum time that active transactions block the GC safe point. After the value is exceeded, the GC safe point is forwarded forcefully. +在 TiDB v6.1.0 中，引入了系统变量 [`tidb_gc_max_wait_time`](/system-variables.md#tidb_gc_max_wait_time-new-in-v610)，用于控制活跃事务阻塞 GC safe point 的最长时间。超过该值后，GC safe point 会被强制推进。 -### GC in Compaction Filter +### Compaction Filter 中的 GC -Based on the `DISTRIBUTED` GC mode, the mechanism of GC in Compaction Filter uses the compaction process of RocksDB, instead of a separate GC worker thread, to run GC. This new GC mechanism helps to avoid extra disk read caused by GC. Also, after clearing the obsolete data, it avoids a large number of left tombstone marks which degrade the sequential scan performance. +基于 `DISTRIBUTED` GC 模式，Compaction Filter 中的 GC 机制利用 RocksDB 的 compaction 过程，而不是单独的 GC worker 线程来执行 GC。该新机制有助于避免 GC 带来的额外磁盘读取。同时，在清理过期数据后，能够避免大量残留的 tombstone 标记，从而提升顺序扫描性能。 > **Note:** > -> The following examples of modifying TiKV configurations are only applicable to TiDB Self-Managed. For TiDB Cloud, the mechanism of GC in Compaction Filter is enabled by default. +> 以下 TiKV 配置修改示例仅适用于 TiDB 自建集群。对于 TiDB Cloud，Compaction Filter 中的 GC 机制默认已启用。 -The following example shows how to enable the mechanism in the TiKV configuration file: - -{{< copyable "" >}} +以下示例展示了如何在 TiKV 配置文件中启用该机制： ```toml [gc] enable-compaction-filter = true ``` -You can also enable this GC mechanism by modifying the configuration dynamically. See the following example: - -{{< copyable "sql" >}} +你也可以通过动态修改配置来启用该 GC 机制。示例如下： ```sql show config where type = 'tikv' and name like '%enable-compaction-filter%'; @@ -91,8 +85,6 @@ show config where type = 'tikv' and name like '%enable-compaction-filter%'; +------+-------------------+-----------------------------+-------+ ``` -{{< copyable "sql" >}} - ```sql set config tikv gc.enable-compaction-filter = true; show config where type = 'tikv' and name like '%enable-compaction-filter%'; @@ -106,4 +98,16 @@ show config where type = 'tikv' and name like '%enable-compaction-filter%'; | tikv | 172.16.5.36:20163 | gc.enable-compaction-filter | true | | tikv | 172.16.5.35:20163 | gc.enable-compaction-filter | true | +------+-------------------+-----------------------------+-------+ -``` \ No newline at end of file +``` + + + +> **Note:** +> +> 当使用 Compaction Filter 机制时，GC 进度可能会延迟，进而影响 TiKV 的扫描性能。如果你的负载中包含大量 coprocessor 请求，并且在 [**TiKV-Details > Coprocessor Detail**](/grafana-tikv-dashboard.md#coprocessor-detail) 面板中观察到 **Total Ops Details** 下的 `next()` 或 `prev()` 调用次数明显超过 `processed_keys` 调用次数的三倍，可以采取以下措施： +> +> - 对于 v7.1.3 之前的 TiDB 版本，建议关闭 Compaction Filter 以加快 GC。 +> - 对于 v7.1.3 到 v7.5.6 的 TiDB 版本，TiDB 会根据每个 Region 的冗余版本数量 [`region-compact-min-redundant-rows`](/tikv-configuration-file.md#region-compact-min-redundant-rows-new-in-v710) 和冗余版本百分比 [`region-compact-redundant-rows-percent`](/tikv-configuration-file.md#region-compact-redundant-rows-percent-new-in-v710) 自动触发 compaction，以提升 Compaction Filter GC 性能。此时建议调整这些配置项，而不是关闭 Compaction Filter。 +> - 从 v7.5.7 起，[`region-compact-min-redundant-rows`](/tikv-configuration-file.md#region-compact-min-redundant-rows-new-in-v710) 和 [`region-compact-redundant-rows-percent`](/tikv-configuration-file.md#region-compact-redundant-rows-percent-new-in-v710) 已废弃。TiDB 现在会根据 [`gc.auto-compaction.redundant-rows-threshold`](/tikv-configuration-file.md#redundant-rows-threshold-new-in-v757) 和 [`gc.auto-compaction.redundant-rows-percent-threshold`](/tikv-configuration-file.md#redundant-rows-percent-threshold-new-in-v757) 自动触发 compaction。此时建议调整这些配置项，而不是关闭 Compaction Filter。 + + \ No newline at end of file diff --git a/index-advisor.md b/index-advisor.md index 9f71978a2d5ba..8e533bbcbdab9 100644 --- a/index-advisor.md +++ b/index-advisor.md @@ -1,31 +1,31 @@ --- title: Index Advisor -summary: Learn how to optimize query performance with TiDB Index Advisor. +summary: 了解如何使用 TiDB Index Advisor 优化查询性能。 --- # Index Advisor -In v8.5.0, TiDB introduces the Index Advisor feature, which helps optimize your workload by recommending indexes that improve query performance. Using the new SQL statement, `RECOMMEND INDEX`, you can generate index recommendations for a single query or an entire workload. To avoid the resource-intensive process of physically creating indexes for evaluation, TiDB supports [hypothetical indexes](#hypothetical-indexes), which are logical indexes that are not materialized. +在 v8.5.0 版本中，TiDB 引入了 Index Advisor（索引顾问）功能，帮助你通过推荐索引来优化工作负载并提升查询性能。通过新的 SQL 语句 `RECOMMEND INDEX`，你可以为单条查询或整个工作负载生成索引推荐。为避免物理创建索引进行评估时的高资源消耗，TiDB 支持 [假设索引](#hypothetical-indexes)，即不会实际落地的逻辑索引。 > **Note:** > -> Currently, this feature is not available on [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) clusters. +> 目前，该功能尚不支持 [TiDB Cloud Serverless](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) 和 [TiDB Cloud Essential](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential) 集群。 -The Index Advisor analyzes queries to identify indexable columns from clauses such as `WHERE`, `GROUP BY`, and `ORDER BY`. Then, it generates index candidates and estimates their performance benefits using hypothetical indexes. TiDB uses a genetic search algorithm to select the optimal set of indexes starting with single-column indexes and iteratively exploring multi-column indexes, leveraging a "What-If" analysis to evaluate potential indexes based on their impact on optimizer plan costs. The advisor recommends indexes when they reduce the overall cost compared to executing queries without them. +Index Advisor 会分析查询，识别如 `WHERE`、`GROUP BY` 和 `ORDER BY` 等子句中的可建索引列。随后，它会生成索引候选项，并利用假设索引评估其性能收益。TiDB 采用遗传搜索算法，从单列索引出发，迭代探索多列索引，并通过 “What-If” 分析根据优化器执行计划的成本评估潜在索引。只有当推荐的索引能降低整体查询成本时，Index Advisor 才会推荐这些索引。 -In addition to [recommending new indexes](#recommend-indexes-using-the-recommend-index-statement), the Index Advisor also suggests [removing inactive indexes](#remove-unused-indexes) to ensure efficient index management. +除了 [推荐新索引](#recommend-indexes-using-the-recommend-index-statement) 外，Index Advisor 还会建议 [移除不活跃索引](#remove-unused-indexes)，以确保索引管理的高效性。 -## Recommend indexes using the `RECOMMEND INDEX` statement +## 使用 `RECOMMEND INDEX` 语句推荐索引 -TiDB introduces the `RECOMMEND INDEX` SQL statement for index advisor tasks. The `RUN` subcommand analyzes historical workloads and saves recommendations in system tables. With the `FOR` option, you can target a specific SQL statement, even if it was not executed previously. You can also use additional [options](#recommend-index-options) for advanced control. The syntax is as follows: +TiDB 引入了 `RECOMMEND INDEX` SQL 语句用于索引顾问相关任务。`RUN` 子命令会分析历史工作负载，并将推荐结果保存到系统表中。通过 `FOR` 选项，你可以针对特定 SQL 语句生成推荐，即使该语句之前未被执行过。你还可以使用额外的 [选项](#recommend-index-options) 进行高级控制。语法如下： ```sql RECOMMEND INDEX RUN [ FOR ] [] ``` -### Recommend indexes for a single query +### 为单条查询推荐索引 -The following example shows how to generate an index recommendation for a query on table `t`, which contains 5,000 rows. For brevity, the `INSERT` statements are omitted. +以下示例展示了如何为包含 5,000 行的表 `t` 的查询生成索引推荐。为简洁起见，省略了 `INSERT` 语句。 ```sql CREATE TABLE t (a INT, b INT, c INT); @@ -41,9 +41,9 @@ RECOMMEND INDEX RUN for "SELECT a, b FROM t WHERE a = 1 AND b = 1"\G create_index_statement: CREATE INDEX idx_a_b ON t(a,b); ``` -The Index Advisor evaluates single-column indexes on `a` and `b` separately and ultimately combines them into a single index for optimal performance. +Index Advisor 会分别评估 `a` 和 `b` 的单列索引，并最终将它们合并为一个多列索引以获得最佳性能。 -The following `EXPLAIN` results compare the query execution without indexes and with the recommended two-column hypothetical index. The Index Advisor internally evaluates both cases and selects the option with the minimum cost. The Index Advisor also considers single-column hypothetical indexes on `a` and `b`, but these do not provide better performance than the combined two-column index. For brevity, the execution plans are omitted. +以下 `EXPLAIN` 结果对比了无索引和使用推荐的双列假设索引时的查询执行情况。Index Advisor 会在内部评估两种情况，并选择成本最低的方案。同时，Index Advisor 也会考虑 `a` 和 `b` 的单列假设索引，但这些索引的性能不如组合的双列索引。为简洁起见，省略了执行计划的详细内容。 ```sql EXPLAIN FORMAT='VERBOSE' SELECT a, b FROM t WHERE a=1 AND b=1; @@ -65,9 +65,9 @@ EXPLAIN FORMAT='VERBOSE' SELECT /*+ HYPO_INDEX(t, idx_ab, a, b) */ a, b FROM t W +------------------------+---------+---------+-----------+-----------------------------+-------------------------------------------------+ ``` -### Recommend indexes for a workload +### 为工作负载推荐索引 -The following example shows how to generate index recommendations for an entire workload. Assume tables `t1` and `t2` each contain 5,000 rows: +以下示例展示了如何为整个工作负载生成索引推荐。假设表 `t1` 和 `t2` 各包含 5,000 行： ```sql CREATE TABLE t1 (a INT, b INT, c INT, d INT); @@ -88,11 +88,11 @@ RECOMMEND INDEX RUN; +----------+-------+------------+---------------+------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------+ ``` -In this case, the Index Advisor identifies optimal indexes for the entire workload rather than a single query. The workload queries are sourced from the TiDB system table `INFORMATION_SCHEMA.STATEMENTS_SUMMARY`. +在此场景下，Index Advisor 针对整个工作负载（而非单条查询）识别出最优索引。工作负载中的查询来源于 TiDB 系统表 `INFORMATION_SCHEMA.STATEMENTS_SUMMARY`。 -This table can contain tens of thousands to hundreds of thousands of queries, which might affect the performance of the Index Advisor. To address this issue, the Index Advisor prioritizes the most frequently executed queries, as these queries have a greater impact on overall workload performance. By default, the Index Advisor selects the top 1,000 queries. You can adjust this value using the [`max_num_query`](#recommend-index-options) parameter. +该表可能包含数万到数十万条查询，这可能会影响 Index Advisor 的性能。为解决此问题，Index Advisor 会优先分析执行频率最高的查询，因为这些查询对整体工作负载性能影响更大。默认情况下，Index Advisor 会选择前 1,000 条查询。你可以通过 [`max_num_query`](#recommend-index-options) 参数调整该值。 -The results of the `RECOMMEND INDEX` statements are stored in the `mysql.index_advisor_results` table. You can query this table to view the recommended indexes. The following example shows the contents of this system table after the previous two `RECOMMEND INDEX` statements are executed: +`RECOMMEND INDEX` 语句的结果会存储在 `mysql.index_advisor_results` 表中。你可以查询该表以查看推荐的索引。以下示例展示了前述两次 `RECOMMEND INDEX` 语句执行后的系统表内容： ```sql SELECT * FROM mysql.index_advisor_results; @@ -105,23 +105,23 @@ SELECT * FROM mysql.index_advisor_results; +----+---------------------+---------------------+-------------+------------+------------+---------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+-------+ ``` -### `RECOMMEND INDEX` options +### `RECOMMEND INDEX` 选项 -You can configure and view options for the `RECOMMEND INDEX` statement to fine-tune its behavior for your workloads as follows: +你可以通过如下方式配置和查看 `RECOMMEND INDEX` 语句的选项，以便针对你的工作负载进行精细化调整： ```sql RECOMMEND INDEX SET