diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 74bdf5437450..8265e07a0b3f 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -2,7 +2,7 @@ ### First-time contributors' checklist -- [ ] I've signed [**Contributor License Agreement**](https://cla-assistant.io/pingcap/docs-cn) that's required for repo owners to accept my contribution. +- [ ] I've signed the [**Contributor License Agreement**](https://cla.pingcap.net/pingcap/docs), which is required for the repository owners to accept my contribution. ### What is changed, added or deleted? (Required) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 1bee97b00b18..af917da90877 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -7,17 +7,55 @@ concurrency: cancel-in-progress: true jobs: - pull: + duplicated-file-names: runs-on: ubuntu-latest steps: - name: Check out uses: actions/checkout@v4 - - uses: actions/setup-node@v4 - with: - node-version: "16" - name: Verify duplicated file names run: ./scripts/verify-duplicated-file-name.sh - - name: Verify internal links + + internal-links-files: + runs-on: ubuntu-latest + steps: + - name: Check out + uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "18" + cache: npm + cache-dependency-path: package-lock.json + - name: Install Node dependencies + run: npm ci + - name: Verify internal links (full repo) - files run: ./scripts/verify-links.sh - - name: Verify internal link anchors + + internal-links-anchors: + runs-on: ubuntu-latest + steps: + - name: Check out + uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "18" + cache: npm + cache-dependency-path: package-lock.json + - name: Install Node dependencies + run: npm ci + - name: Verify internal links (full repo) - anchors run: ./scripts/verify-link-anchors.sh + + internal-links-toc: + runs-on: ubuntu-latest + steps: + - name: Check out + uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "18" + cache: npm + cache-dependency-path: package-lock.json + - name: Install Node dependencies + run: npm ci + - name: Verify internal links (full repo) - TOC membership + run: node ./scripts/verify-internal-links-in-toc.js diff --git a/.github/workflows/dispatch.yml b/.github/workflows/dispatch.yml index 35c5683680f5..38a0a8708223 100644 --- a/.github/workflows/dispatch.yml +++ b/.github/workflows/dispatch.yml @@ -6,6 +6,7 @@ on: - ".github/**" branches: - master + - release-8.5 - release-7.2 - release-7.1 - release-7.0 diff --git a/.github/workflows/link-fail-fast.yaml b/.github/workflows/link-fail-fast.yaml index a5e4677d0897..9f3466d0c899 100644 --- a/.github/workflows/link-fail-fast.yaml +++ b/.github/workflows/link-fail-fast.yaml @@ -17,15 +17,11 @@ jobs: CHANGED_FILES=$(git diff-tree --name-only --diff-filter 'AM' -r HEAD^1 HEAD -- "*.md" | sed -z "s/\n$//;s/\n/' '/g") echo "all_changed_files=${CHANGED_FILES}" >> $GITHUB_OUTPUT - - name: Download Exclude Path - run: | - curl https://raw.githubusercontent.com/pingcap/docs/master/.lycheeignore -O - - name: Link Checker if: ${{ steps.changed-files.outputs.all_changed_files }} - uses: lycheeverse/lychee-action@v1.6.1 + uses: lycheeverse/lychee-action@v2.3.0 with: fail: true - args: -E --exclude-mail -i -n -t 45 -- '${{ steps.changed-files.outputs.all_changed_files }}' + args: --root-dir $(pwd) -E -i -n -t 45 -- '${{ steps.changed-files.outputs.all_changed_files }}' env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} diff --git a/.github/workflows/media.yml b/.github/workflows/media.yml index df5fb691cc15..b0020320e507 100644 --- a/.github/workflows/media.yml +++ b/.github/workflows/media.yml @@ -7,7 +7,7 @@ on: paths: - media/** jobs: - run: + upload: name: Upload media files runs-on: ubuntu-latest steps: @@ -34,3 +34,42 @@ jobs: # printf "%s\n" ${{ secrets.AWS_ACCESS_KEY }} ${{ secrets.AWS_SECRET_KEY }} ${{ secrets.AWS_REGION }} "json" | aws configure - name: Upload run: cloud-assets-utils verify-and-sync -qiniu true -qiniu-bucket ${{ secrets.QINIU_BUCKET_NAME }} media -replace-first-path-to images/docs-cn -cdn-refresh https://download.pingcap.com/ + + - name: Install coscli + run: | + wget https://cosbrowser.cloud.tencent.com/software/coscli/coscli-linux-amd64 + mv coscli-linux-amd64 coscli + chmod 755 coscli + + - name: Upload to COS + run: | + ./coscli sync media/ cos://${{ secrets.TENCENTCLOUD_BUCKET_ID }}/media/images/docs-cn \ + --init-skip \ + --recursive \ + --routines 16 \ + --secret-id ${{ secrets.TENCENTCLOUD_SECRET_ID }} \ + --secret-key ${{ secrets.TENCENTCLOUD_SECRET_KEY }} \ + --endpoint cos.ap-beijing.myqcloud.com + + cdn-refresh: + needs: upload + runs-on: ubuntu-latest + name: Refresh CDN Cache + env: + TENCENTCLOUD_SECRET_ID: ${{ secrets.TENCENTCLOUD_SECRET_ID }} + TENCENTCLOUD_SECRET_KEY: ${{ secrets.TENCENTCLOUD_SECRET_KEY }} + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Python environment + uses: actions/setup-python@v5 + with: + python-version: '3.12' + architecture: 'x64' + + - name: Install Tencent Cloud CLI + run: pipx install tccli + + - name: Purge production CDN cache + run: tccli cdn PurgePathCache --Paths '["https://docs-download.pingcap.com/media/images/docs-cn/"]' --FlushType delete diff --git a/.github/workflows/sync-doc-pr-en-to-zh.yml b/.github/workflows/sync-doc-pr-en-to-zh.yml new file mode 100644 index 000000000000..483bc2888c96 --- /dev/null +++ b/.github/workflows/sync-doc-pr-en-to-zh.yml @@ -0,0 +1,185 @@ +name: Sync Docs Changes from EN PR to ZH PR + +on: + workflow_dispatch: + inputs: + source_pr_url: + description: 'Source PR URL (English docs repository)' + required: true + type: string + default: '' + target_pr_url: + description: 'Target PR URL (Chinese docs repository)' + required: true + type: string + default: '' + ai_provider: + description: 'AI Provider to use for translation' + required: false + type: choice + options: + - deepseek + - gemini + default: 'gemini' + +jobs: + sync-docs: + runs-on: ubuntu-latest + + steps: + - name: Checkout current repository + uses: actions/checkout@v4 + with: + token: ${{ secrets.GITHUB_TOKEN }} + fetch-depth: 0 + + - name: Checkout ai-pr-translator repository + uses: actions/checkout@v4 + with: + repository: "qiancai/ai-pr-translator" + ref: "main" + path: "ai-pr-translator" + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.9' + + - name: Install dependencies + run: pip install -r ai-pr-translator/scripts/requirements.txt + + - name: Extract PR information + id: extract_info + env: + SOURCE_URL: ${{ github.event.inputs.source_pr_url }} + TARGET_URL: ${{ github.event.inputs.target_pr_url }} + run: | + if [[ ! "$SOURCE_URL" =~ ^https://github\.com/[^/]+/[^/]+/pull/[0-9]+$ ]]; then + echo "❌ Invalid source PR URL format"; exit 1 + fi + if [[ ! "$TARGET_URL" =~ ^https://github\.com/[^/]+/[^/]+/pull/[0-9]+$ ]]; then + echo "❌ Invalid target PR URL format"; exit 1 + fi + + SOURCE_OWNER=$(echo "$SOURCE_URL" | cut -d'/' -f4) + SOURCE_REPO=$(echo "$SOURCE_URL" | cut -d'/' -f5) + SOURCE_PR=$(echo "$SOURCE_URL" | cut -d'/' -f7) + TARGET_OWNER=$(echo "$TARGET_URL" | cut -d'/' -f4) + TARGET_REPO=$(echo "$TARGET_URL" | cut -d'/' -f5) + TARGET_PR=$(echo "$TARGET_URL" | cut -d'/' -f7) + + { + echo "source_owner<> $GITHUB_OUTPUT + + echo "Source: ${SOURCE_OWNER}/${SOURCE_REPO}#${SOURCE_PR}" + echo "Target: ${TARGET_OWNER}/${TARGET_REPO}#${TARGET_PR}" + + - name: Get target PR branch info + id: target_branch + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + TARGET_OWNER: ${{ steps.extract_info.outputs.target_owner }} + TARGET_REPO: ${{ steps.extract_info.outputs.target_repo }} + TARGET_PR: ${{ steps.extract_info.outputs.target_pr }} + run: | + PR_INFO=$(curl -s -H "Authorization: token ${GH_TOKEN}" -H "Accept: application/vnd.github.v3+json" \ + "https://api.github.com/repos/${TARGET_OWNER}/${TARGET_REPO}/pulls/${TARGET_PR}") + TARGET_BRANCH=$(echo "$PR_INFO" | jq -r '.head.ref') + HEAD_REPO=$(echo "$PR_INFO" | jq -r '.head.repo.full_name') + echo "target_branch=${TARGET_BRANCH}" >> $GITHUB_OUTPUT + echo "head_repo=${HEAD_REPO}" >> $GITHUB_OUTPUT + echo "Target branch: ${TARGET_BRANCH}, Head repo: ${HEAD_REPO}" + + - name: Clone target repository + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + HEAD_REPO: ${{ steps.target_branch.outputs.head_repo }} + TARGET_BRANCH: ${{ steps.target_branch.outputs.target_branch }} + run: | + git clone "https://x-access-token:${GITHUB_TOKEN}@github.com/${HEAD_REPO}.git" target_repo + cd target_repo && git checkout "$TARGET_BRANCH" + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + + - name: Run sync script + id: sync_script + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + DEEPSEEK_API_TOKEN: ${{ secrets.DEEPSEEK_API_TOKEN }} + GEMINI_API_TOKEN: ${{ secrets.GEMINI_API_TOKEN }} + SOURCE_PR_URL: ${{ github.event.inputs.source_pr_url }} + TARGET_PR_URL: ${{ github.event.inputs.target_pr_url }} + AI_PROVIDER: ${{ github.event.inputs.ai_provider }} + TARGET_REPO_PATH: ${{ github.workspace }}/target_repo + run: | + cd ai-pr-translator/scripts + if python main_workflow.py; then + echo "sync_success=true" >> $GITHUB_OUTPUT + echo "✅ Sync script completed successfully" + else + echo "sync_success=false" >> $GITHUB_OUTPUT + echo "❌ Sync script failed" + exit 1 + fi + + - name: Commit and push changes + if: steps.sync_script.outputs.sync_success == 'true' + env: + SOURCE_PR_URL: ${{ github.event.inputs.source_pr_url }} + TARGET_PR_URL: ${{ github.event.inputs.target_pr_url }} + AI_PROVIDER: ${{ github.event.inputs.ai_provider }} + TARGET_BRANCH: ${{ steps.target_branch.outputs.target_branch }} + run: | + cd target_repo && git add . + if ! git diff --staged --quiet; then + printf "Auto-sync: Update Chinese docs from English PR\n\nSynced from: %s\nTarget PR: %s\nAI Provider: %s\n\nCo-authored-by: github-actions[bot] " \ + "$SOURCE_PR_URL" "$TARGET_PR_URL" "$AI_PROVIDER" | git commit -F - + git push origin "$TARGET_BRANCH" + echo "Changes pushed to $TARGET_BRANCH" + else + echo "No changes to commit" + fi + + - name: Add success comment to target PR + if: steps.sync_script.outputs.sync_success == 'true' + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + SOURCE_PR_URL: ${{ github.event.inputs.source_pr_url }} + TARGET_PR_URL: ${{ github.event.inputs.target_pr_url }} + TARGET_OWNER: ${{ steps.extract_info.outputs.target_owner }} + TARGET_REPO: ${{ steps.extract_info.outputs.target_repo }} + TARGET_PR: ${{ steps.extract_info.outputs.target_pr }} + run: | + BODY=$(printf '%s\n\n%s\n%s\n%s\n\n%s' "**Auto-sync completed successfully**" \ + "**Source PR**: ${SOURCE_PR_URL}" "**Target PR**: ${TARGET_PR_URL}" \ + "Chinese documentation has been updated based on English documentation changes." ) + PAYLOAD=$(jq -n --arg body "$BODY" '{body: $body}') + curl -X POST -H "Authorization: token ${GITHUB_TOKEN}" \ + -H "Accept: application/vnd.github.v3+json" \ + "https://api.github.com/repos/${TARGET_OWNER}/${TARGET_REPO}/issues/${TARGET_PR}/comments" \ + -d "$PAYLOAD" + + - name: Add failure comment to target PR + if: steps.sync_script.outputs.sync_success == 'false' + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + SOURCE_PR_URL: ${{ github.event.inputs.source_pr_url }} + TARGET_PR_URL: ${{ github.event.inputs.target_pr_url }} + TARGET_OWNER: ${{ steps.extract_info.outputs.target_owner }} + TARGET_REPO: ${{ steps.extract_info.outputs.target_repo }} + TARGET_PR: ${{ steps.extract_info.outputs.target_pr }} + run: | + BODY=$(printf '%s\n\n%s\n%s\n%s\n\n%s' "**Auto-sync failed**" \ + "**Source PR**: ${SOURCE_PR_URL}" "**Target PR**: ${TARGET_PR_URL}" \ + "The sync process encountered an error. Please check the workflow logs for details.") + PAYLOAD=$(jq -n --arg body "$BODY" '{body: $body}') + curl -X POST -H "Authorization: token ${GITHUB_TOKEN}" \ + -H "Accept: application/vnd.github.v3+json" \ + "https://api.github.com/repos/${TARGET_OWNER}/${TARGET_REPO}/issues/${TARGET_PR}/comments" \ + -d "$PAYLOAD" diff --git a/.gitignore b/.gitignore index a94ad24ecd4e..8078e4fa4af5 100644 --- a/.gitignore +++ b/.gitignore @@ -12,5 +12,4 @@ gen .DS_Store /node_modules/ -package.json yarn.lock diff --git a/.lycheeignore b/.lycheeignore new file mode 100644 index 000000000000..548358b75079 --- /dev/null +++ b/.lycheeignore @@ -0,0 +1,37 @@ +https://mvnrepository\.com/artifact/mysql/mysql-connector-java/8\.0\.28 +https://github\.com/.*/issues/? +https://github\.com/.*/pull/? +https://github\.com/.*/pull/[0-9]+ +https://github\.com/.*/issues/[0-9]+ +https?://\$?\{host}/dashboard.* +http://xn--\$?\{ip}-m86ht9t5l1bhz9ayu7b:3000.* +http://ip:2379.* +http://grafana_ip:3000.* +http://\$?\{remote-server-ip}:3000.* +file:///home/runner/work/(docs|docs-cn)/(docs|docs-cn)/develop/.* +file://.*https:/%7BnodeIP%7D:%7BnodePort%7D/dashboard +file://.*?http:/\$%7BPD_IP%7D:\$%7BPD_PORT%7D/dashboard.* +http://\{grafana-ip\}:3000 +http://\{pd-ip\}:2379/dashboard +http://localhost:\d+/ +https://github\.com/\$user/(docs|docs-cn) +https://linux\.die\.net/man.* +https://dev\.mysql\.com/doc/.+/5.7/en/.* +https://dev\.mysql\.com/doc/.+/8\.0/en/.* +https://dev\.mysql\.com/doc/.+/8\.4/en/.* +https://dev\.mysql\.com/doc/[a-z\-]+/en/.* +https://dev\.mysql\.com/doc/relnotes/[a-z\-]+/en/.* +https://dev\.mysql\.com/doc/dev/mysql-server/.* +https://dev\.mysql\.com/downloads/.* +https://bugs\.mysql\.com/bug\.php.* +https://www\.mysql\.com/products/.* +https://help\.openai\.com/en/articles/.* +https://platform\.openai\.com/docs/.* +https://openai\.com/.* +https://jwt\.io/ +https://typeorm\.io/.* +https://dash\.cloudflare\.com/.* +https://centminmod\.com/mydumper\.html +https://learn\.pingcap\.com/learner/ +https://zhuanlan\.zhihu\.com/p/ +https://developers\.redhat\.com/blog/2021/01/05/building-red-hat-enterprise-linux-9-for-the-x86-64-v2-microarchitecture-level diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a6d6e70f9983..f58b724608f0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -81,7 +81,7 @@ TiDB 文档的修改需要遵循一定的流程，具体如下。考虑到有些 ### 第 0 步：签署 Contributor License Agreement -首次在本仓库提 PR 时，请务必签署 [Contributor License Agreement](https://cla-assistant.io/pingcap/docs-cn) (CLA)，否则我们将无法合并你的 PR。成功签署 CLA 后，可继续进行后续操作。 +首次在本仓库提 PR 时，请务必签署 [Contributor License Agreement](https://cla.pingcap.net/pingcap/docs-cn) (CLA)，否则我们将无法合并你的 PR。成功签署 CLA 后，可继续进行后续操作。 ### 第 1 步：Fork pingcap/docs-cn 仓库 diff --git a/TOC-ai.md b/TOC-ai.md new file mode 100644 index 000000000000..098447fd04fd --- /dev/null +++ b/TOC-ai.md @@ -0,0 +1,86 @@ + + + +# 目录 + +## 快速开始 + +- [使用 Python 快速上手](/ai/quickstart-via-python.md) +- [使用 SQL 快速上手](/ai/quickstart-via-sql.md) + +## 基础概念 + +- [向量搜索](/ai/concepts/vector-search-overview.md) + +## 使用指南 + +- [连接 TiDB](/ai/guides/connect.md) +- [使用表](/ai/guides/tables.md) +- 搜索功能 + - [向量搜索](/ai/guides/vector-search.md) + - 全文搜索 + - [使用 Python 进行全文搜索](/ai/guides/vector-search-full-text-search-python.md) + - [使用 SQL 进行全文搜索](/ai/guides/vector-search-full-text-search-sql.md) + - [混合搜索](/ai/guides/vector-search-hybrid-search.md) + - [图片搜索](/ai/guides/image-search.md) +- 高级功能 + - [自动生成向量](/ai/guides/auto-embedding.md) + - [过滤](/ai/guides/filtering.md) + - [重排序](/ai/guides/reranking.md) + - [Join 查询](/ai/guides/join-queries.md) + - [Raw SQL 查询](/ai/guides/raw-queries.md) + - [事务](/ai/guides/transactions.md) + +## 代码示例 + +- [增删改查](/ai/examples/basic-with-pytidb.md) +- [自动生成向量](/ai/examples/auto-embedding-with-pytidb.md) +- 搜索与检索 + - [向量搜索](/ai/examples/vector-search-with-pytidb.md) + - [全文搜索](/ai/examples/fulltext-search-with-pytidb.md) + - [混合搜索](/ai/examples/hybrid-search-with-pytidb.md) + - [图片搜索](/ai/examples/image-search-with-pytidb.md) +- AI 应用 + - [RAG 应用](/ai/examples/rag-with-pytidb.md) + - [对话记忆](/ai/examples/memory-with-pytidb.md) + - [文本转 SQL](/ai/examples/text2sql-with-pytidb.md) + +## 集成指南 + +- [集成概览](/ai/integrations/vector-search-integration-overview.md) +- 自动生成向量 + - [概览](/ai/integrations/vector-search-auto-embedding-overview.md) + - [OpenAI](/ai/integrations/vector-search-auto-embedding-openai.md) + - [OpenAI 兼容](/ai/integrations/embedding-openai-compatible.md) + - [Jina AI](/ai/integrations/vector-search-auto-embedding-jina-ai.md) + - [Cohere](/ai/integrations/vector-search-auto-embedding-cohere.md) + - [Google Gemini](/ai/integrations/vector-search-auto-embedding-gemini.md) + - [Hugging Face](/ai/integrations/vector-search-auto-embedding-huggingface.md) + - [NVIDIA NIM](/ai/integrations/vector-search-auto-embedding-nvidia-nim.md) + - [Amazon Titan](/ai/integrations/vector-search-auto-embedding-amazon-titan.md) +- AI 框架 + - [LangChain](/ai/integrations/vector-search-integrate-with-langchain.md) + - [LlamaIndex](/ai/integrations/vector-search-integrate-with-llamaindex.md) +- ORM 库 + - [SQLAlchemy](/ai/integrations/vector-search-integrate-with-sqlalchemy.md) + - [Django ORM](/ai/integrations/vector-search-integrate-with-django-orm.md) + - [Peewee](/ai/integrations/vector-search-integrate-with-peewee.md) +- 云服务 + - [Jina AI Embedding](/ai/integrations/vector-search-integrate-with-jinaai-embedding.md) + - [Amazon Bedrock](/ai/integrations/vector-search-integrate-with-amazon-bedrock.md) +- MCP Server + - [概览](/ai/integrations/tidb-mcp-server.md) + - [Claude Code](/ai/integrations/tidb-mcp-claude-code.md) + - [Claude Desktop](/ai/integrations/tidb-mcp-claude-desktop.md) + - [Cursor](/ai/integrations/tidb-mcp-cursor.md) + - [VS Code](/ai/integrations/tidb-mcp-vscode.md) + - [Windsurf](/ai/integrations/tidb-mcp-windsurf.md) + +## 参考指南 + +- [向量数据类型](/ai/reference/vector-search-data-types.md) +- [函数和运算符](/ai/reference/vector-search-functions-and-operators.md) +- [向量搜索索引](/ai/reference/vector-search-index.md) +- [性能调优](/ai/reference/vector-search-improve-performance.md) +- [限制](/ai/reference/vector-search-limitations.md) +- [更新记录](/ai/reference/vector-search-changelogs.md) diff --git a/TOC-api.md b/TOC-api.md new file mode 100644 index 000000000000..e88631caa65e --- /dev/null +++ b/TOC-api.md @@ -0,0 +1,18 @@ + + + +# Table of Contents + +## TIDB CLOUD + +- [API 概览](/api/tidb-cloud-api-overview.md) +- [v1beta1 API](/api/tidb-cloud-api-v1beta1.md) +- [v1beta API](/api/tidb-cloud-api-v1beta.md) + +## TIDB + +- [TiProxy API](/api/tiproxy-api-overview.md) +- [Data Migration API](/api/dm-api-overview.md) +- [监控 API](/api/monitoring-api-overview.md) +- [TiCDC API](/api/ticdc-api-overview.md) +- [TiDB Operator API](/api/tidb-operator-api-overview.md) diff --git a/TOC-best-practices.md b/TOC-best-practices.md new file mode 100644 index 000000000000..77734d2f3772 --- /dev/null +++ b/TOC-best-practices.md @@ -0,0 +1,34 @@ + + + +# 目录 + +## 使用概览 + +- [TiDB 最佳实践](/best-practices/tidb-best-practices.md) + +## 库表设计 + +- [DDL 最佳实践](/best-practices/ddl-introduction.md) +- [将 UUID 用作主键的最佳实践](/best-practices/uuid.md) +- [多列索引优化最佳实践](/best-practices/multi-column-index-best-practices.md) +- [管理索引和识别未使用索引的最佳实践](/best-practices/index-management-best-practices.md) + +## 集群部署 + +- [在公有云上部署 TiDB 的最佳实践](/best-practices/best-practices-on-public-cloud.md) +- [三节点混合部署的最佳实践](/best-practices/three-nodes-hybrid-deployment.md) +- [在三数据中心下就近读取数据的最佳实践](/best-practices/three-dc-local-read.md) + +## 运维管理 + +- [HAProxy 最佳实践](/best-practices/haproxy-best-practices.md) +- [只读存储节点最佳实践](/best-practices/readonly-nodes.md) +- [Grafana 监控最佳实践](/best-practices/grafana-monitor-best-practices.md) + +## 性能调优 + +- [SaaS 多租户场景下处理百万张表的最佳实践](/best-practices/saas-best-practices.md) +- [高并发写入场景最佳实践](/best-practices/high-concurrency-best-practices.md) +- [海量 Region 集群调优最佳实践](/best-practices/massive-regions-best-practices.md) +- [PD 调度策略最佳实践](/best-practices/pd-scheduling-best-practices.md) diff --git a/TOC-develop.md b/TOC-develop.md new file mode 100644 index 000000000000..824e9580444f --- /dev/null +++ b/TOC-develop.md @@ -0,0 +1,116 @@ + + + +# 目录 + +## 快速上手 + +- [创建 {{{ .starter }}} 集群](/develop/dev-guide-build-cluster-in-cloud.md) +- [TiDB 基础](/develop/dev-guide-tidb-basics.md) +- [使用 TiDB 的增删改查 SQL](/develop/dev-guide-tidb-crud-sql.md) + +## 开发指南 + +- 连接到 TiDB + - [概览](/develop/dev-guide-connect-to-tidb.md) + - 通过 CLI 或 GUI 连接 + - [MySQL CLI 工具](/develop/dev-guide-mysql-tools.md) + - [MySQL Workbench](/develop/dev-guide-gui-mysql-workbench.md) + - [Navicat](/develop/dev-guide-gui-navicat.md) + - 通过驱动或 ORM 框架连接 + - [选择驱动或 ORM 框架](/develop/dev-guide-choose-driver-or-orm.md) + - Java + - [JDBC](/develop/dev-guide-sample-application-java-jdbc.md) + - [MyBatis](/develop/dev-guide-sample-application-java-mybatis.md) + - [Hibernate](/develop/dev-guide-sample-application-java-hibernate.md) + - [Spring Boot](/develop/dev-guide-sample-application-java-spring-boot.md) + - [配置连接池与连接参数](/develop/dev-guide-connection-parameters.md) + - [开发 Java 应用的最佳实践](/develop/java-app-best-practices.md) + - Go + - [Go-MySQL-Driver](/develop/dev-guide-sample-application-golang-sql-driver.md) + - [GORM](/develop/dev-guide-sample-application-golang-gorm.md) + - Python + - [mysqlclient](/develop/dev-guide-sample-application-python-mysqlclient.md) + - [MySQL Connector/Python](/develop/dev-guide-sample-application-python-mysql-connector.md) + - [PyMySQL](/develop/dev-guide-sample-application-python-pymysql.md) + - [SQLAlchemy](/develop/dev-guide-sample-application-python-sqlalchemy.md) + - [peewee](/develop/dev-guide-sample-application-python-peewee.md) + - [Django](/develop/dev-guide-sample-application-python-django.md) + - Node.js + - [node-mysql2](/develop/dev-guide-sample-application-nodejs-mysql2.md) + - [mysql.js](/develop/dev-guide-sample-application-nodejs-mysqljs.md) + - [Prisma](/develop/dev-guide-sample-application-nodejs-prisma.md) + - [Sequelize](/develop/dev-guide-sample-application-nodejs-sequelize.md) + - [TypeORM](/develop/dev-guide-sample-application-nodejs-typeorm.md) + - [Next.js](/develop/dev-guide-sample-application-nextjs.md) + - [AWS Lambda](/develop/dev-guide-sample-application-aws-lambda.md) + - Ruby + - [mysql2](/develop/dev-guide-sample-application-ruby-mysql2.md) + - [Rails](/develop/dev-guide-sample-application-ruby-rails.md) + - C# + - [C#](/develop/dev-guide-sample-application-cs.md) + - 通过 TiDB Cloud Serverless Driver 连接 ![BETA](/media/blank_transparent_placeholder.png) + - [概览](/develop/serverless-driver.md) + - [Node.js 示例](/develop/serverless-driver-node-example.md) + - [Prisma 示例](/develop/serverless-driver-prisma-example.md) + - [Kysely 示例](/develop/serverless-driver-kysely-example.md) + - [Drizzle 示例](/develop/serverless-driver-drizzle-example.md) +- 数据库模式设计 + - [概览](/develop/dev-guide-schema-design-overview.md) + - [创建数据库](/develop/dev-guide-create-database.md) + - [创建表](/develop/dev-guide-create-table.md) + - [创建二级索引](/develop/dev-guide-create-secondary-indexes.md) +- 数据写入 + - [插入数据](/develop/dev-guide-insert-data.md) + - [更新数据](/develop/dev-guide-update-data.md) + - [删除数据](/develop/dev-guide-delete-data.md) + - [使用 TTL (Time to Live) 定期删除过期数据](/develop/dev-guide-time-to-live.md) + - [预处理语句](/develop/dev-guide-prepared-statement.md) +- 数据读取 + - [单表读取](/develop/dev-guide-get-data-from-single-table.md) + - [多表连接查询](/develop/dev-guide-join-tables.md) + - [子查询](/develop/dev-guide-use-subqueries.md) + - [查询结果分页](/develop/dev-guide-paginate-results.md) + - [视图](/develop/dev-guide-use-views.md) + - [临时表](/develop/dev-guide-use-temporary-tables.md) + - [公共表表达式](/develop/dev-guide-use-common-table-expression.md) + - 读取副本数据 + - [Follower Read](/develop/dev-guide-use-follower-read.md) + - [Stale Read](/develop/dev-guide-use-stale-read.md) + - [HTAP 查询](/develop/dev-guide-hybrid-oltp-and-olap-queries.md) +- [向量搜索](/develop/dev-guide-vector-search.md) ![BETA](/media/blank_transparent_placeholder.png) +- 事务处理 + - [概览](/develop/dev-guide-transaction-overview.md) + - [乐观事务和悲观事务](/develop/dev-guide-optimistic-and-pessimistic-transaction.md) + - [事务限制](/develop/dev-guide-transaction-restraints.md) + - [事务错误处理](/develop/dev-guide-transaction-troubleshoot.md) +- 优化 SQL 性能 + - [概览](/develop/dev-guide-optimize-sql-overview.md) + - [SQL 性能调优](/develop/dev-guide-optimize-sql.md) + - [性能调优最佳实践](/develop/dev-guide-optimize-sql-best-practices.md) + - [索引的最佳实践](/develop/dev-guide-index-best-practice.md) + - 其他优化 + - [避免隐式类型转换](/develop/dev-guide-implicit-type-conversion.md) + - [唯一序列号生成方案](/develop/dev-guide-unique-serial-number-generation.md) +- 故障诊断 + - [SQL 或事务问题](/develop/dev-guide-troubleshoot-overview.md) + - [结果集不稳定](/develop/dev-guide-unstable-result-set.md) + - [超时](/develop/dev-guide-timeouts-in-tidb.md) + +## 集成指南 + +- 第三方工具支持 + - [TiDB 支持的第三方工具](/develop/dev-guide-third-party-support.md) + - [已知的第三方工具兼容问题](/develop/dev-guide-third-party-tools-compatibility.md) +- [ProxySQL](/develop/dev-guide-proxysql-integration.md) +- [Amazon AppFlow](/develop/dev-guide-aws-appflow-integration.md) +- [WordPress](/develop/dev-guide-wordpress.md) + +## 参考指南 + +- 开发规范 + - [命名规范](/develop/dev-guide-object-naming-guidelines.md) + - [SQL 开发规范](/develop/dev-guide-sql-development-specification.md) +- [Bookshop 示例应用](/develop/dev-guide-bookshop-schema-design.md) +- 云原生开发环境 + - [Gitpod](/develop/dev-guide-playground-gitpod.md) \ No newline at end of file diff --git a/TOC-pingkai.md b/TOC-pingkai.md new file mode 100644 index 000000000000..7b35c1e41633 --- /dev/null +++ b/TOC-pingkai.md @@ -0,0 +1,1331 @@ + + + + +- 关于 TiDB + - [TiDB 简介](/overview.md) + - [TiDB 8.5 Release Notes](/releases/release-8.5.0.md) + - [功能概览](/basic-features.md) + - [与 MySQL 的兼容性](/mysql-compatibility.md) + - [使用限制](/tidb-limitations.md) + - [荣誉列表](/credits.md) +- 快速上手 + - [快速上手 TiDB](/quick-start-with-tidb.md) + - [快速上手 HTAP](/quick-start-with-htap.md) + - [SQL 基本操作](/basic-sql-operations.md) + - [深入探索 HTAP](/explore-htap.md) +- 应用开发 + - 快速开始 + - [使用 {{{ .starter }}} 构建 TiDB 集群](/develop/dev-guide-build-cluster-in-cloud.md) + - [使用 TiDB 的增删改查 SQL](/develop/dev-guide-tidb-crud-sql.md) + - 示例程序 + - Java + - [JDBC](/develop/dev-guide-sample-application-java-jdbc.md) + - [MyBatis](/develop/dev-guide-sample-application-java-mybatis.md) + - [Hibernate](/develop/dev-guide-sample-application-java-hibernate.md) + - [Spring Boot](/develop/dev-guide-sample-application-java-spring-boot.md) + - [连接池与连接参数](/develop/dev-guide-connection-parameters.md) + - [开发 Java 应用的最佳实践](/develop/java-app-best-practices.md) + - Go + - [Go-MySQL-Driver](/develop/dev-guide-sample-application-golang-sql-driver.md) + - [GORM](/develop/dev-guide-sample-application-golang-gorm.md) + - Python + - [mysqlclient](/develop/dev-guide-sample-application-python-mysqlclient.md) + - [MySQL Connector/Python](/develop/dev-guide-sample-application-python-mysql-connector.md) + - [PyMySQL](/develop/dev-guide-sample-application-python-pymysql.md) + - [SQLAlchemy](/develop/dev-guide-sample-application-python-sqlalchemy.md) + - [peewee](/develop/dev-guide-sample-application-python-peewee.md) + - [Django](/develop/dev-guide-sample-application-python-django.md) + - Node.js + - [node-mysql2](/develop/dev-guide-sample-application-nodejs-mysql2.md) + - [mysql.js](/develop/dev-guide-sample-application-nodejs-mysqljs.md) + - [Prisma](/develop/dev-guide-sample-application-nodejs-prisma.md) + - [Sequelize](/develop/dev-guide-sample-application-nodejs-sequelize.md) + - [TypeORM](/develop/dev-guide-sample-application-nodejs-typeorm.md) + - [Next.js](/develop/dev-guide-sample-application-nextjs.md) + - [AWS Lambda](/develop/dev-guide-sample-application-aws-lambda.md) + - Ruby + - [mysql2](/develop/dev-guide-sample-application-ruby-mysql2.md) + - [Rails](/develop/dev-guide-sample-application-ruby-rails.md) + - C# + - [C#](/develop/dev-guide-sample-application-cs.md) + - 连接到 TiDB + - [概览](/develop/dev-guide-connect-to-tidb.md) + - 通过 CLI 或 GUI 连接 + - [MySQL CLI 工具](/develop/dev-guide-mysql-tools.md) + - [MySQL Workbench](/develop/dev-guide-gui-mysql-workbench.md) + - [Navicat](/develop/dev-guide-gui-navicat.md) + - [选择驱动或 ORM 框架](/develop/dev-guide-choose-driver-or-orm.md) + - 数据库模式设计 + - [概览](/develop/dev-guide-schema-design-overview.md) + - [创建数据库](/develop/dev-guide-create-database.md) + - [创建表](/develop/dev-guide-create-table.md) + - [创建二级索引](/develop/dev-guide-create-secondary-indexes.md) + - 数据写入 + - [插入数据](/develop/dev-guide-insert-data.md) + - [更新数据](/develop/dev-guide-update-data.md) + - [删除数据](/develop/dev-guide-delete-data.md) + - [使用 TTL (Time to Live) 定期删除过期数据](/develop/dev-guide-time-to-live.md) + - [预处理语句](/develop/dev-guide-prepared-statement.md) + - 数据读取 + - [单表读取](/develop/dev-guide-get-data-from-single-table.md) + - [多表连接查询](/develop/dev-guide-join-tables.md) + - [子查询](/develop/dev-guide-use-subqueries.md) + - [查询结果分页](/develop/dev-guide-paginate-results.md) + - [视图](/develop/dev-guide-use-views.md) + - [临时表](/develop/dev-guide-use-temporary-tables.md) + - [公共表表达式](/develop/dev-guide-use-common-table-expression.md) + - 读取副本数据 + - [Follower Read](/develop/dev-guide-use-follower-read.md) + - [Stale Read](/develop/dev-guide-use-stale-read.md) + - [HTAP 查询](/develop/dev-guide-hybrid-oltp-and-olap-queries.md) + - 向量搜索 + - [概述](/ai/concepts/vector-search-overview.md) + - 快速入门 + - [使用 SQL 开始向量搜索](/ai/quickstart-via-sql.md) + - [使用 Python 开始向量搜索](/ai/quickstart-via-python.md) + - 集成 + - [集成概览](/ai/integrations/vector-search-integration-overview.md) + - AI 框架 + - [LlamaIndex](/ai/integrations/vector-search-integrate-with-llamaindex.md) + - [Langchain](/ai/integrations/vector-search-integrate-with-langchain.md) + - 嵌入模型/服务 + - [Jina AI](/ai/integrations/vector-search-integrate-with-jinaai-embedding.md) + - ORM 库 + - [SQLAlchemy](/ai/integrations/vector-search-integrate-with-sqlalchemy.md) + - [peewee](/ai/integrations/vector-search-integrate-with-peewee.md) + - [Django](/ai/integrations/vector-search-integrate-with-django-orm.md) + - [优化搜索性能](/ai/reference/vector-search-improve-performance.md) + - [使用限制](/ai/reference/vector-search-limitations.md) + - 事务 + - [概览](/develop/dev-guide-transaction-overview.md) + - [乐观事务和悲观事务](/develop/dev-guide-optimistic-and-pessimistic-transaction.md) + - [事务限制](/develop/dev-guide-transaction-restraints.md) + - [事务错误处理](/develop/dev-guide-transaction-troubleshoot.md) + - 优化 SQL 性能 + - [概览](/develop/dev-guide-optimize-sql-overview.md) + - [SQL 性能调优](/develop/dev-guide-optimize-sql.md) + - [性能调优最佳实践](/develop/dev-guide-optimize-sql-best-practices.md) + - [索引的最佳实践](/develop/dev-guide-index-best-practice.md) + - 其他优化 + - [避免隐式类型转换](/develop/dev-guide-implicit-type-conversion.md) + - [唯一序列号生成方案](/develop/dev-guide-unique-serial-number-generation.md) + - 故障诊断 + - [SQL 或事务问题](/develop/dev-guide-troubleshoot-overview.md) + - [结果集不稳定](/develop/dev-guide-unstable-result-set.md) + - [超时](/develop/dev-guide-timeouts-in-tidb.md) + - 引用文档 + - [Bookshop 示例应用](/develop/dev-guide-bookshop-schema-design.md) + - 规范 + - [命名规范](/develop/dev-guide-object-naming-guidelines.md) + - [SQL 开发规范](/develop/dev-guide-sql-development-specification.md) + - 云原生开发环境 + - [Gitpod](/develop/dev-guide-playground-gitpod.md) + - 第三方工具支持 + - [TiDB 支持的第三方工具](/develop/dev-guide-third-party-support.md) + - [已知的第三方工具兼容问题](/develop/dev-guide-third-party-tools-compatibility.md) + - [ProxySQL 集成指南](/develop/dev-guide-proxysql-integration.md) +- 部署标准集群 + - [软硬件环境需求](/hardware-and-software-requirements.md) + - [环境与系统配置检查](/check-before-deployment.md) + - 规划集群拓扑 + - [最小部署拓扑结构](/minimal-deployment-topology.md) + - [TiFlash 部署拓扑](/tiflash-deployment-topology.md) + - [PD 微服务部署拓扑](/pd-microservices-deployment-topology.md) + - [TiProxy 部署拓扑](/tiproxy/tiproxy-deployment-topology.md) + - [TiCDC 部署拓扑](/ticdc-deployment-topology.md) + - [跨机房部署拓扑结构](/geo-distributed-deployment-topology.md) + - [混合部署拓扑结构](/hybrid-deployment-topology.md) + - [使用 TiUP 部署](/production-deployment-using-tiup.md) + - [在 Kubernetes 上部署](/tidb-in-kubernetes.md) + - [验证集群状态](/post-installation-check.md) + - 测试集群性能 + - [用 Sysbench 测试 TiDB](/benchmark/benchmark-tidb-using-sysbench.md) + - [对 TiDB 进行 TPC-C 测试](/benchmark/benchmark-tidb-using-tpcc.md) + - [对 TiDB 进行 CH-benCHmark 测试](/benchmark/benchmark-tidb-using-ch.md) +- 数据迁移 + - [数据迁移概述](/migration-overview.md) + - [数据迁移工具](/migration-tools.md) + - [数据导入最佳实践](/tidb-lightning/data-import-best-practices.md) + - 数据迁移场景 + - [从 Aurora 迁移数据到 TiDB](/migrate-aurora-to-tidb.md) + - [从小数据量 MySQL 迁移数据到 TiDB](/migrate-small-mysql-to-tidb.md) + - [从大数据量 MySQL 迁移数据到 TiDB](/migrate-large-mysql-to-tidb.md) + - [从小数据量分库分表 MySQL 合并迁移数据到 TiDB](/migrate-small-mysql-shards-to-tidb.md) + - [从大数据量分库分表 MySQL 合并迁移数据到 TiDB](/migrate-large-mysql-shards-to-tidb.md) + - [从 Vitess 迁移数据到 TiDB](/migrate-from-vitess.md) + - [从 MariaDB 迁移数据到 TiDB](/migrate-from-mariadb.md) + - [从 CSV 文件迁移数据到 TiDB](/migrate-from-csv-files-to-tidb.md) + - [从 SQL 文件迁移数据到 TiDB](/migrate-from-sql-files-to-tidb.md) + - [从 Parquet 文件迁移数据到 TiDB](/migrate-from-parquet-files-to-tidb.md) + - [从 TiDB 集群迁移数据至另一 TiDB 集群](/migrate-from-tidb-to-tidb.md) + - [从 TiDB 集群迁移数据至兼容 MySQL 的数据库](/migrate-from-tidb-to-mysql.md) + - 复杂迁移场景 + - [上游使用 pt/gh-ost 工具的持续同步场景](/migrate-with-pt-ghost.md) + - [下游存在更多列的迁移场景](/migrate-with-more-columns-downstream.md) + - [如何根据类型或 DDL 内容过滤 binlog 事件](/filter-binlog-event.md) + - [如何通过 SQL 表达式过滤 DML binlog 事件](/filter-dml-event.md) +- 数据同步 + - [TiCDC 概述](/ticdc/ticdc-overview.md) + - [安装部署与集群运维](/ticdc/deploy-ticdc.md) + - Changefeed + - [Changefeed 概述](/ticdc/ticdc-changefeed-overview.md) + - 创建 Changefeed + - [同步数据到 MySQL 兼容的数据库](/ticdc/ticdc-sink-to-mysql.md) + - [同步数据到 Kafka](/ticdc/ticdc-sink-to-kafka.md) + - [同步数据到 Pulsar](/ticdc/ticdc-sink-to-pulsar.md) + - [同步数据到存储服务](/ticdc/ticdc-sink-to-cloud-storage.md) + - [管理 Changefeed](/ticdc/ticdc-manage-changefeed.md) + - [日志过滤器](/ticdc/ticdc-filter.md) + - [DDL 同步](/ticdc/ticdc-ddl.md) + - [双向复制](/ticdc/ticdc-bidirectional-replication.md) + - 监控告警 + - [基本监控指标](/ticdc/ticdc-summary-monitor.md) + - [详细监控指标](/ticdc/monitor-ticdc.md) + - [报警规则](/ticdc/ticdc-alert-rules.md) + - 数据集成场景 + - [数据集成概述](/integration-overview.md) + - [与 Confluent Cloud 和 Snowflake、ksqlDB、SQL Server 进行数据集成](/ticdc/integrate-confluent-using-ticdc.md) + - [与 Apache Kafka 和 Apache Flink 进行数据集成](/replicate-data-to-kafka.md) + - 参考指南 + - TiCDC 架构设计与原理 + - [TiCDC 新架构](/ticdc/ticdc-architecture.md) + - [TiCDC 老架构](/ticdc/ticdc-classic-architecture.md) + - [TiCDC 数据同步能力详解](/ticdc/ticdc-data-replication-capabilities.md) + - [TiCDC Server 配置参数](/ticdc/ticdc-server-config.md) + - [TiCDC Changefeed 配置参数](/ticdc/ticdc-changefeed-config.md) + - [TiCDC 客户端鉴权](/ticdc/ticdc-client-authentication.md) + - [单行数据正确性校验](/ticdc/ticdc-integrity-check.md) + - [主从集群数据校验和快照读](/ticdc/ticdc-upstream-downstream-check.md) + - [拆分 UPDATE 事件行为说明](/ticdc/ticdc-split-update-behavior.md) + - 输出数据协议 + - [TiCDC Avro Protocol](/ticdc/ticdc-avro-protocol.md) + - [TiCDC Canal-JSON Protocol](/ticdc/ticdc-canal-json.md) + - [TiCDC CSV Protocol](/ticdc/ticdc-csv.md) + - [TiCDC Debezium Protocol](/ticdc/ticdc-debezium.md) + - [TiCDC Open Protocol](/ticdc/ticdc-open-protocol.md) + - [TiCDC Simple Protocol](/ticdc/ticdc-simple-protocol.md) + - [TiCDC Open API v2](/ticdc/ticdc-open-api-v2.md) + - [TiCDC Open API v1](/ticdc/ticdc-open-api.md) + - TiCDC 数据消费 + - [基于 Avro 的 TiCDC 行数据 Checksum 校验](/ticdc/ticdc-avro-checksum-verification.md) + - [Storage sink 消费程序编写指引](/ticdc/ticdc-storage-consumer-dev-guide.md) + - [TiCDC 兼容性](/ticdc/ticdc-compatibility.md) + - [故障处理](/ticdc/troubleshoot-ticdc.md) + - [常见问题解答](/ticdc/ticdc-faq.md) + - [术语表](/ticdc/ticdc-glossary.md) +- 运维操作 + - 安全加固 + - [TiDB 安全配置最佳实践](/best-practices-for-security-configuration.md) + - [为 TiDB 客户端服务端间通信开启加密传输](/enable-tls-between-clients-and-servers.md) + - [为 TiDB 组件间通信开启加密传输](/enable-tls-between-components.md) + - [生成自签名证书](/generate-self-signed-certificates.md) + - [静态加密](/encryption-at-rest.md) + - [为 TiDB 落盘文件开启加密](/enable-disk-spill-encrypt.md) + - [日志脱敏](/log-redaction.md) + - 升级 TiDB 版本 + - [使用 TiUP 升级](/upgrade-tidb-using-tiup.md) + - [使用 TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/upgrade-a-tidb-cluster) + - [平滑升级 TiDB](/smooth-upgrade-tidb.md) + - [迁移升级 TiDB](/tidb-upgrade-migration-guide.md) + - [TiFlash 升级帮助](/tiflash-upgrade-guide.md) + - 扩缩容 + - [使用 TiUP（推荐）](/scale-tidb-using-tiup.md) + - [使用 TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/scale-a-tidb-cluster) + - 备份与恢复 + - [备份与恢复概述](/br/backup-and-restore-overview.md) + - 架构设计 + - [架构概述](/br/backup-and-restore-design.md) + - [快照备份与恢复架构](/br/br-snapshot-architecture.md) + - [日志备份与 PITR 架构](/br/br-log-architecture.md) + - 使用 BR 进行备份与恢复 + - [使用概述](/br/br-use-overview.md) + - [快照备份与恢复](/br/br-snapshot-guide.md) + - [日志备份与 PITR](/br/br-pitr-guide.md) + - [压缩日志备份](/br/br-compact-log-backup.md) + - [实践示例](/br/backup-and-restore-use-cases.md) + - [备份存储](/br/backup-and-restore-storages.md) + - br cli 命令手册 + - [命令概述](/br/use-br-command-line-tool.md) + - [快照备份与恢复命令手册](/br/br-snapshot-manual.md) + - [日志备份与 PITR 命令手册](/br/br-pitr-manual.md) + - 参考指南 + - BR 特性 + - [自动调节](/br/br-auto-tune.md) + - [批量建表](/br/br-batch-create-table.md) + - [断点备份](/br/br-checkpoint-backup.md) + - [断点恢复](/br/br-checkpoint-restore.md) + - [使用 Dumpling 和 TiDB Lightning 备份与恢复](/backup-and-restore-using-dumpling-lightning.md) + - [备份与恢复 RawKV](/br/rawkv-backup-and-restore.md) + - [增量备份与恢复](/br/br-incremental-guide.md) + - 集群容灾 + - [容灾方案介绍](/dr-solution-introduction.md) + - [基于主备集群的容灾](/dr-secondary-cluster.md) + - [基于多副本的单集群容灾](/dr-multi-replica.md) + - [基于备份与恢复的容灾](/dr-backup-restore.md) + - 资源管控 + - [使用资源管控 (Resource Control) 实现资源组限制和流控](/tidb-resource-control-ru-groups.md) + - [管理资源消耗超出预期的查询 (Runaway Queries)](/tidb-resource-control-runaway-queries.md) + - [限制后台任务资源使用](/tidb-resource-control-background-tasks.md) + - [修改时区](/configure-time-zone.md) + - [日常巡检](/daily-check.md) + - [TiFlash 常用运维操作](/tiflash/maintain-tiflash.md) + - [使用 TiUP 运维集群](/maintain-tidb-using-tiup.md) + - [在线修改集群配置](/dynamic-config.md) + - [在线有损恢复](/online-unsafe-recovery.md) + - [搭建双集群主从复制](/replicate-between-primary-and-secondary-clusters.md) +- 监控与告警 + - [监控框架概述](/tidb-monitoring-framework.md) + - [监控 API](/tidb-monitoring-api.md) + - [手动部署监控](/deploy-monitoring-services.md) + - [升级监控组件](/upgrade-monitoring-services.md) + - TiDB Dashboard + - [简介](/dashboard/dashboard-intro.md) + - 运维 + - [部署](/dashboard/dashboard-ops-deploy.md) + - [反向代理](/dashboard/dashboard-ops-reverse-proxy.md) + - [用户管理](/dashboard/dashboard-user.md) + - [安全](/dashboard/dashboard-ops-security.md) + - [访问](/dashboard/dashboard-access.md) + - [概况页面](/dashboard/dashboard-overview.md) + - [集群信息页面](/dashboard/dashboard-cluster-info.md) + - [Top SQL 页面](/dashboard/top-sql.md) + - [流量可视化页面](/dashboard/dashboard-key-visualizer.md) + - [监控关系图](/dashboard/dashboard-metrics-relation.md) + - SQL 语句分析 + - [列表页面](/dashboard/dashboard-statement-list.md) + - [执行详情页面](/dashboard/dashboard-statement-details.md) + - [慢查询页面](/dashboard/dashboard-slow-query.md) + - 集群诊断页面 + - [访问](/dashboard/dashboard-diagnostics-access.md) + - [查看报告](/dashboard/dashboard-diagnostics-report.md) + - [使用示例](/dashboard/dashboard-diagnostics-usage.md) + - [监控指标页面](/dashboard/dashboard-monitoring.md) + - [日志搜索页面](/dashboard/dashboard-log-search.md) + - [资源管控页面](/dashboard/dashboard-resource-manager.md) + - 实例性能分析 + - [手动分析页面](/dashboard/dashboard-profiling.md) + - [持续分析页面](/dashboard/continuous-profiling.md) + - 会话管理与配置 + - [分享会话](/dashboard/dashboard-session-share.md) + - [配置 SSO 登录](/dashboard/dashboard-session-sso.md) + - [常见问题](/dashboard/dashboard-faq.md) + - [将 Grafana 监控数据导出成快照](/exporting-grafana-snapshots.md) + - [TiDB 集群报警规则与处理方法](/alert-rules.md) + - [TiFlash 报警规则与处理方法](/tiflash/tiflash-alert-rules.md) + - [自定义监控组件的配置](/tiup/customized-montior-in-tiup-environment.md) + - [BR 监控告警](/br/br-monitoring-and-alert.md) +- 故障诊断 + - 故障诊断问题汇总 + - [TiDB 集群问题导图](/tidb-troubleshooting-map.md) + - [TiDB 集群常见问题](/troubleshoot-tidb-cluster.md) + - [TiFlash 常见问题](/tiflash/troubleshoot-tiflash.md) + - 故障场景 + - 慢查询 + - [定位慢查询](/identify-slow-queries.md) + - [分析慢查询](/analyze-slow-queries.md) + - [TiDB OOM 故障排查](/troubleshoot-tidb-oom.md) + - [热点问题处理](/troubleshoot-hot-spot-issues.md) + - [读写延迟增加](/troubleshoot-cpu-issues.md) + - [写冲突与写性能下降](/troubleshoot-write-conflicts.md) + - [磁盘 I/O 过高](/troubleshoot-high-disk-io.md) + - [锁冲突与 TTL 超时](/troubleshoot-lock-conflicts.md) + - [数据索引不一致报错](/troubleshoot-data-inconsistency-errors.md) + - 故障诊断方法 + - [通过 SQL 诊断获取集群诊断信息](/information-schema/information-schema-sql-diagnostics.md) + - [通过 Statement Summary 排查 SQL 性能问题](/statement-summary-tables.md) + - [使用 Top SQL 定位系统资源消耗过多的查询](/dashboard/top-sql.md) + - [通过日志定位消耗系统资源多的查询](/identify-expensive-queries.md) + - [保存和恢复集群现场信息](/sql-plan-replayer.md) + - [理解 TiKV 中的 Stale Read 和 safe-ts](/troubleshoot-stale-read.md) + - [获取支持](/support.md) +- 性能调优 + - 优化手册 + - [优化概述](/performance-tuning-overview.md) + - [优化方法](/performance-tuning-methods.md) + - [OLTP 负载性能优化实践](/performance-tuning-practices.md) + - [TiFlash 性能分析方法](/tiflash-performance-tuning-methods.md) + - [TiCDC 性能分析方法](/ticdc-performance-tuning-methods.md) + - [延迟的拆解分析](/latency-breakdown.md) + - [在公有云上部署 TiDB 的最佳实践](/best-practices/best-practices-on-public-cloud.md) + - 配置调优 + - [操作系统性能参数调优](/tune-operating-system.md) + - [TiDB 内存调优](/configure-memory-usage.md) + - [TiKV 线程调优](/tune-tikv-thread-performance.md) + - [TiKV 内存调优](/tune-tikv-memory-performance.md) + - [TiKV Follower Read](/follower-read.md) + - [TiKV MVCC 内存引擎](/tikv-in-memory-engine.md) + - [Region 性能调优](/tune-region-performance.md) + - [TiFlash 调优](/tiflash/tune-tiflash-performance.md) + - [下推计算结果缓存](/coprocessor-cache.md) + - 垃圾回收 (GC) + - [GC 机制简介](/garbage-collection-overview.md) + - [GC 配置](/garbage-collection-configuration.md) + - SQL 性能调优 + - [SQL 性能调优概览](/sql-tuning-overview.md) + - 理解 TiDB 执行计划 + - [TiDB 执行计划概览](/explain-overview.md) + - [使用 `EXPLAIN` 解读执行计划](/explain-walkthrough.md) + - [MPP 模式查询的执行计划](/explain-mpp.md) + - [索引查询的执行计划](/explain-indexes.md) + - [Join 查询的执行计划](/explain-joins.md) + - [子查询的执行计划](/explain-subqueries.md) + - [聚合查询的执行计划](/explain-aggregation.md) + - [视图查询的执行计划](/explain-views.md) + - [分区查询的执行计划](/explain-partitions.md) + - [开启 IndexMerge 查询的执行计划](/explain-index-merge.md) + - SQL 优化流程 + - [SQL 优化流程概览](/sql-optimization-concepts.md) + - 逻辑优化 + - [逻辑优化概览](/sql-logical-optimization.md) + - [子查询相关的优化](/subquery-optimization.md) + - [列裁剪](/column-pruning.md) + - [关联子查询去关联](/correlated-subquery-optimization.md) + - [Max/Min 消除](/max-min-eliminate.md) + - [谓词下推](/predicate-push-down.md) + - [分区裁剪](/partition-pruning.md) + - [TopN 和 Limit 下推](/topn-limit-push-down.md) + - [Join Reorder](/join-reorder.md) + - [从窗口函数中推导 TopN 或 Limit](/derive-topn-from-window.md) + - 物理优化 + - [物理优化概览](/sql-physical-optimization.md) + - [索引的选择](/choose-index.md) + - [常规统计信息](/statistics.md) + - [扩展统计信息](/extended-statistics.md) + - [错误索引的解决方案](/wrong-index-solution.md) + - [Distinct 优化](/agg-distinct-optimization.md) + - [代价模型](/cost-model.md) + - [Runtime Filter](/runtime-filter.md) + - [Prepare 语句执行计划缓存](/sql-prepared-plan-cache.md) + - [非 Prepare 语句执行计划缓存](/sql-non-prepared-plan-cache.md) + - 控制执行计划 + - [控制执行计划概览](/control-execution-plan.md) + - [Optimizer Hints](/optimizer-hints.md) + - [执行计划管理](/sql-plan-management.md) + - [优化规则及表达式下推的黑名单](/blocklist-control-plan.md) + - [Optimizer Fix Controls](/optimizer-fix-controls.md) + - [索引推荐 (Index Advisor)](/index-advisor.md) +- 教程 + - [单区域多 AZ 部署](/multi-data-centers-in-one-city-deployment.md) + - [双区域多 AZ 部署](/three-data-centers-in-two-cities-deployment.md) + - [单区域双 AZ 部署](/two-data-centers-in-one-city-deployment.md) + - 读取历史数据 + - 使用 Stale Read 功能读取历史数据（推荐） + - [Stale Read 使用场景介绍](/stale-read.md) + - [使用 `AS OF TIMESTAMP` 语法读取历史数据](/as-of-timestamp.md) + - [使用系统变量 `tidb_read_staleness` 读取历史数据](/tidb-read-staleness.md) + - [使用系统变量 `tidb_external_ts` 读取历史数据](/tidb-external-ts.md) + - [使用系统变量 `tidb_snapshot` 读取历史数据](/read-historical-data.md) + - [Placement Rules 使用文档](/configure-placement-rules.md) + - [Load Base Split 使用文档](/configure-load-base-split.md) + - [Store Limit 使用文档](/configure-store-limit.md) + - [数据批量处理](/batch-processing.md) + - PD 微服务使用文档 + - [PD 微服务概览](/pd-microservices.md) + - [使用 TiUP 扩容缩容 PD 微服务节点](/scale-microservices-using-tiup.md) + - [TSO 配置文件描述](/tso-configuration-file.md) + - [TSO 配置参数](/command-line-flags-for-tso-configuration.md) + - [Scheduling 配置文件描述](/scheduling-configuration-file.md) + - [Scheduling 配置参数](/command-line-flags-for-scheduling-configuration.md) +- 最佳实践 + - [TiDB 最佳实践](/best-practices/tidb-best-practices.md) + - [DDL 最佳实践](/best-practices/ddl-introduction.md) + - [多列索引优化最佳实践](/best-practices/multi-column-index-best-practices.md) + - [管理索引和识别未使用索引的最佳实践](/best-practices/index-management-best-practices.md) + - [SaaS 多租户场景下处理百万张表](/best-practices/saas-best-practices.md) + - [将 UUID 用作主键的最佳实践](/best-practices/uuid.md) + - [高并发写入场景最佳实践](/best-practices/high-concurrency-best-practices.md) + - [海量 Region 集群调优最佳实践](/best-practices/massive-regions-best-practices.md) + - [PD 调度策略最佳实践](/best-practices/pd-scheduling-best-practices.md) + - [只读存储节点最佳实践](/best-practices/readonly-nodes.md) + - [HAProxy 最佳实践](/best-practices/haproxy-best-practices.md) + - [Grafana 监控最佳实践](/best-practices/grafana-monitor-best-practices.md) + - [三节点混合部署最佳实践](/best-practices/three-nodes-hybrid-deployment.md) + - [在三数据中心下就近读取数据](/best-practices/three-dc-local-read.md) +- TiDB 工具 + - [功能概览](/ecosystem-tool-user-guide.md) + - [使用场景](/ecosystem-tool-user-case.md) + - [工具下载](/download-ecosystem-tools.md) + - TiUP + - [文档地图](/tiup/tiup-documentation-guide.md) + - [概览](/tiup/tiup-overview.md) + - [术语及核心概念](/tiup/tiup-terminology-and-concepts.md) + - [TiUP 组件管理](/tiup/tiup-component-management.md) + - [FAQ](/tiup/tiup-faq.md) + - [故障排查](/tiup/tiup-troubleshooting-guide.md) + - TiUP 命令参考手册 + - [命令概览](/tiup/tiup-reference.md) + - TiUP 命令 + - [tiup clean](/tiup/tiup-command-clean.md) + - [tiup completion](/tiup/tiup-command-completion.md) + - [tiup env](/tiup/tiup-command-env.md) + - [tiup help](/tiup/tiup-command-help.md) + - [tiup install](/tiup/tiup-command-install.md) + - [tiup list](/tiup/tiup-command-list.md) + - tiup mirror + - [tiup mirror 概览](/tiup/tiup-command-mirror.md) + - [tiup mirror clone](/tiup/tiup-command-mirror-clone.md) + - [tiup mirror genkey](/tiup/tiup-command-mirror-genkey.md) + - [tiup mirror grant](/tiup/tiup-command-mirror-grant.md) + - [tiup mirror init](/tiup/tiup-command-mirror-init.md) + - [tiup mirror merge](/tiup/tiup-command-mirror-merge.md) + - [tiup mirror modify](/tiup/tiup-command-mirror-modify.md) + - [tiup mirror publish](/tiup/tiup-command-mirror-publish.md) + - [tiup mirror rotate](/tiup/tiup-command-mirror-rotate.md) + - [tiup mirror set](/tiup/tiup-command-mirror-set.md) + - [tiup mirror sign](/tiup/tiup-command-mirror-sign.md) + - [tiup status](/tiup/tiup-command-status.md) + - [tiup telemetry](/tiup/tiup-command-telemetry.md) + - [tiup uninstall](/tiup/tiup-command-uninstall.md) + - [tiup update](/tiup/tiup-command-update.md) + - TiUP Cluster 命令 + - [TiUP Cluster 命令概览](/tiup/tiup-component-cluster.md) + - [tiup cluster audit](/tiup/tiup-component-cluster-audit.md) + - [tiup cluster audit cleanup](/tiup/tiup-component-cluster-audit-cleanup.md) + - [tiup cluster check](/tiup/tiup-component-cluster-check.md) + - [tiup cluster clean](/tiup/tiup-component-cluster-clean.md) + - [tiup cluster deploy](/tiup/tiup-component-cluster-deploy.md) + - [tiup cluster destroy](/tiup/tiup-component-cluster-destroy.md) + - [tiup cluster disable](/tiup/tiup-component-cluster-disable.md) + - [tiup cluster display](/tiup/tiup-component-cluster-display.md) + - [tiup cluster edit-config](/tiup/tiup-component-cluster-edit-config.md) + - [tiup cluster enable](/tiup/tiup-component-cluster-enable.md) + - [tiup cluster help](/tiup/tiup-component-cluster-help.md) + - [tiup cluster import](/tiup/tiup-component-cluster-import.md) + - [tiup cluster list](/tiup/tiup-component-cluster-list.md) + - [tiup cluster meta backup](/tiup/tiup-component-cluster-meta-backup.md) + - [tiup cluster meta restore](/tiup/tiup-component-cluster-meta-restore.md) + - [tiup cluster patch](/tiup/tiup-component-cluster-patch.md) + - [tiup cluster prune](/tiup/tiup-component-cluster-prune.md) + - [tiup cluster reload](/tiup/tiup-component-cluster-reload.md) + - [tiup cluster rename](/tiup/tiup-component-cluster-rename.md) + - [tiup cluster replay](/tiup/tiup-component-cluster-replay.md) + - [tiup cluster restart](/tiup/tiup-component-cluster-restart.md) + - [tiup cluster scale-in](/tiup/tiup-component-cluster-scale-in.md) + - [tiup cluster scale-out](/tiup/tiup-component-cluster-scale-out.md) + - [tiup cluster start](/tiup/tiup-component-cluster-start.md) + - [tiup cluster stop](/tiup/tiup-component-cluster-stop.md) + - [tiup cluster template](/tiup/tiup-component-cluster-template.md) + - [tiup cluster tls](/tiup/tiup-component-cluster-tls.md) + - [tiup cluster upgrade](/tiup/tiup-component-cluster-upgrade.md) + - TiUP DM 命令 + - [TiUP DM 命令概览](/tiup/tiup-component-dm.md) + - [tiup dm audit](/tiup/tiup-component-dm-audit.md) + - [tiup dm deploy](/tiup/tiup-component-dm-deploy.md) + - [tiup dm destroy](/tiup/tiup-component-dm-destroy.md) + - [tiup dm disable](/tiup/tiup-component-dm-disable.md) + - [tiup dm display](/tiup/tiup-component-dm-display.md) + - [tiup dm edit-config](/tiup/tiup-component-dm-edit-config.md) + - [tiup dm enable](/tiup/tiup-component-dm-enable.md) + - [tiup dm help](/tiup/tiup-component-dm-help.md) + - [tiup dm import](/tiup/tiup-component-dm-import.md) + - [tiup dm list](/tiup/tiup-component-dm-list.md) + - [tiup dm patch](/tiup/tiup-component-dm-patch.md) + - [tiup dm prune](/tiup/tiup-component-dm-prune.md) + - [tiup dm reload](/tiup/tiup-component-dm-reload.md) + - [tiup dm replay](/tiup/tiup-component-dm-replay.md) + - [tiup dm restart](/tiup/tiup-component-dm-restart.md) + - [tiup dm scale-in](/tiup/tiup-component-dm-scale-in.md) + - [tiup dm scale-out](/tiup/tiup-component-dm-scale-out.md) + - [tiup dm start](/tiup/tiup-component-dm-start.md) + - [tiup dm stop](/tiup/tiup-component-dm-stop.md) + - [tiup dm template](/tiup/tiup-component-dm-template.md) + - [tiup dm upgrade](/tiup/tiup-component-dm-upgrade.md) + - [TiDB 集群拓扑文件配置](/tiup/tiup-cluster-topology-reference.md) + - [DM 集群拓扑文件配置](/tiup/tiup-dm-topology-reference.md) + - [TiUP 镜像参考指南](/tiup/tiup-mirror-reference.md) + - TiUP 组件文档 + - [tiup-playground 运行本地测试集群](/tiup/tiup-playground.md) + - [tiup-cluster 部署运维生产集群](/tiup/tiup-cluster.md) + - [使用 no-sudo 模式部署运维生产集群](/tiup/tiup-cluster-no-sudo-mode.md) + - [tiup-mirror 定制离线镜像](/tiup/tiup-mirror.md) + - [tiup-bench 进行 TPCC/TPCH 压力测试](/tiup/tiup-bench.md) + - [TiDB Operator](/tidb-operator-overview.md) + - TiDB Data Migration + - [关于 Data Migration](/dm/dm-overview.md) + - [架构简介](/dm/dm-arch.md) + - [快速上手](/dm/quick-start-with-dm.md) + - [最佳实践](/dm/dm-best-practices.md) + - 部署 DM 集群 + - [软硬件要求](/dm/dm-hardware-and-software-requirements.md) + - [使用 TiUP 联网部署（推荐）](/dm/deploy-a-dm-cluster-using-tiup.md) + - [使用 TiUP 离线部署](/dm/deploy-a-dm-cluster-using-tiup-offline.md) + - [使用 Binary 部署](/dm/deploy-a-dm-cluster-using-binary.md) + - [在 Kubernetes 环境中部署](https://docs.pingcap.com/zh/tidb-in-kubernetes/v1.6/deploy-tidb-dm) + - 入门指南 + - [创建数据源](/dm/quick-start-create-source.md) + - [数据源操作](/dm/dm-manage-source.md) + - [任务配置向导](/dm/dm-task-configuration-guide.md) + - [分库分表合并](/dm/dm-shard-merge.md) + - [表路由](/dm/dm-table-routing.md) + - [黑白名单](/dm/dm-block-allow-table-lists.md) + - [过滤 binlog 事件](/dm/dm-binlog-event-filter.md) + - [通过 SQL 表达式过滤 DML](/dm/feature-expression-filter.md) + - [Online DDL 工具支持](/dm/dm-online-ddl-tool-support.md) + - [自定义加解密 key](/dm/dm-customized-secret-key.md) + - 迁移任务操作 + - [任务前置检查](/dm/dm-precheck.md) + - [创建任务](/dm/dm-create-task.md) + - [查询状态](/dm/dm-query-status.md) + - [暂停任务](/dm/dm-pause-task.md) + - [恢复任务](/dm/dm-resume-task.md) + - [停止任务](/dm/dm-stop-task.md) + - 进阶教程 + - 分库分表合并迁移 + - [概述](/dm/feature-shard-merge.md) + - [悲观模式](/dm/feature-shard-merge-pessimistic.md) + - [乐观模式](/dm/feature-shard-merge-optimistic.md) + - [手动处理 Sharding DDL Lock](/dm/manually-handling-sharding-ddl-locks.md) + - [迁移使用 GH-ost/PT-osc 的数据源](/dm/feature-online-ddl.md) + - [上下游列数量不一致的迁移](/migrate-with-more-columns-downstream.md) + - [增量数据校验](/dm/dm-continuous-data-validation.md) + - 运维管理 + - 集群版本升级 + - [使用 TiUP 运维集群（推荐）](/dm/maintain-dm-using-tiup.md) + - [1.0.x 到 2.0+ 手动升级](/dm/manually-upgrade-dm-1.0-to-2.0.md) + - [在线应用 Hotfix 到 DM 集群](/tiup/tiup-component-dm-patch.md) + - 集群运维工具 + - [使用 WebUI 管理迁移任务](/dm/dm-webui-guide.md) + - [使用 dmctl 管理迁移任务](/dm/dmctl-introduction.md) + - 性能调优 + - [性能数据](/dm/dm-benchmark-v5.4.0.md) + - [配置调优](/dm/dm-tune-configuration.md) + - [如何进行压力测试](/dm/dm-performance-test.md) + - [性能问题及处理方法](/dm/dm-handle-performance-issues.md) + - 数据源管理 + - [变更同步的数据源地址](/dm/usage-scenario-master-slave-switch.md) + - 任务管理 + - [处理出错的 DDL 语句](/dm/handle-failed-ddl-statements.md) + - [管理迁移表的表结构](/dm/dm-manage-schema.md) + - [导出和导入集群的数据源和任务配置](/dm/dm-export-import-config.md) + - [处理告警](/dm/dm-handle-alerts.md) + - [日常巡检](/dm/dm-daily-check.md) + - 参考手册 + - 架构组件 + - [DM-worker 说明](/dm/dm-worker-intro.md) + - [安全模式](/dm/dm-safe-mode.md) + - [Relay Log](/dm/relay-log.md) + - 运行机制 + - [DML 同步机制](/dm/dm-dml-replication-logic.md) + - [高可用机制](/dm/dm-high-availability.md) + - [DDL 特殊处理说明](/dm/dm-ddl-compatible.md) + - 命令行 + - [DM-master & DM-worker](/dm/dm-command-line-flags.md) + - 配置文件 + - [概述](/dm/dm-config-overview.md) + - [数据源配置](/dm/dm-source-configuration-file.md) + - [迁移任务配置](/dm/task-configuration-file-full.md) + - [DM-master 配置](/dm/dm-master-configuration-file.md) + - [DM-worker 配置](/dm/dm-worker-configuration-file.md) + - [Table Selector](/dm/table-selector.md) + - [OpenAPI](/dm/dm-open-api.md) + - [兼容性目录](/dm/dm-compatibility-catalog.md) + - 安全 + - [为 DM 的连接开启加密传输](/dm/dm-enable-tls.md) + - [生成自签名证书](/dm/dm-generate-self-signed-certificates.md) + - 监控告警 + - [监控指标](/dm/monitor-a-dm-cluster.md) + - [告警信息](/dm/dm-alert-rules.md) + - [错误码](/dm/dm-error-handling.md#常见故障处理方法) + - [术语表](/dm/dm-glossary.md) + - 使用示例 + - [使用 DM 迁移数据](/dm/migrate-data-using-dm.md) + - [快速创建迁移任务](/dm/quick-start-create-task.md) + - [分表合并数据迁移最佳实践](/dm/shard-merge-best-practices.md) + - 异常解决 + - [常见问题](/dm/dm-faq.md) + - [错误处理及恢复](/dm/dm-error-handling.md) + - [版本发布历史](/dm/dm-release-notes.md) + - TiDB Lightning + - [概述](/tidb-lightning/tidb-lightning-overview.md) + - [`IMPORT INTO` 和 TiDB Lightning 对比](/tidb-lightning/import-into-vs-tidb-lightning.md) + - [`IMPORT INTO` 和 TiDB Lightning 与日志备份和 TiCDC 的兼容性](/tidb-lightning/tidb-lightning-compatibility-and-scenarios.md) + - [快速上手](/get-started-with-tidb-lightning.md) + - [部署 TiDB Lightning](/tidb-lightning/deploy-tidb-lightning.md) + - [目标数据库要求](/tidb-lightning/tidb-lightning-requirements.md) + - 数据源 + - [文件匹配规则](/tidb-lightning/tidb-lightning-data-source.md) + - [表库重命名](/tidb-lightning/tidb-lightning-data-source.md#表库重命名) + - [CSV](/tidb-lightning/tidb-lightning-data-source.md#csv) + - [SQL](/tidb-lightning/tidb-lightning-data-source.md#sql) + - [Parquet](/tidb-lightning/tidb-lightning-data-source.md#parquet) + - [压缩文件](/tidb-lightning/tidb-lightning-data-source.md#压缩文件) + - [自定义文件匹配](/tidb-lightning/tidb-lightning-data-source.md#自定义文件匹配) + - [从 Amazon S3 导入数据](/tidb-lightning/tidb-lightning-data-source.md#从-amazon-s3-导入数据) + - 物理导入模式 + - [概述](/tidb-lightning/tidb-lightning-physical-import-mode.md) + - [必要条件及限制](/tidb-lightning/tidb-lightning-physical-import-mode.md#必要条件及限制) + - [配置及使用](/tidb-lightning/tidb-lightning-physical-import-mode-usage.md) + - [冲突检测](/tidb-lightning/tidb-lightning-physical-import-mode-usage.md#冲突数据检测) + - [性能调优](/tidb-lightning/tidb-lightning-physical-import-mode-usage.md#性能调优) + - 逻辑导入模式 + - [概述](/tidb-lightning/tidb-lightning-logical-import-mode.md) + - [必要条件及限制](/tidb-lightning/tidb-lightning-logical-import-mode.md#必要条件) + - [配置及使用](/tidb-lightning/tidb-lightning-logical-import-mode-usage.md) + - [冲突检测](/tidb-lightning/tidb-lightning-logical-import-mode-usage.md#冲突数据检测) + - [性能调优](/tidb-lightning/tidb-lightning-logical-import-mode-usage.md#性能调优) + - [前置检查](/tidb-lightning/tidb-lightning-prechecks.md) + - [表库过滤](/table-filter.md) + - [断点续传](/tidb-lightning/tidb-lightning-checkpoints.md) + - [并行导入](/tidb-lightning/tidb-lightning-distributed-import.md) + - [可容忍错误](/tidb-lightning/tidb-lightning-error-resolution.md) + - [故障处理](/tidb-lightning/troubleshoot-tidb-lightning.md) + - 参考手册 + - [完整配置文件](/tidb-lightning/tidb-lightning-configuration.md) + - [命令行参数](/tidb-lightning/tidb-lightning-command-line-full.md) + - [监控告警](/tidb-lightning/monitor-tidb-lightning.md) + - [Web 界面](/tidb-lightning/tidb-lightning-web-interface.md) + - [FAQ](/tidb-lightning/tidb-lightning-faq.md) + - [术语表](/tidb-lightning/tidb-lightning-glossary.md) + - [Dumpling](/dumpling-overview.md) + - PingCAP Clinic 诊断服务 + - [概述](/clinic/clinic-introduction.md) + - [快速上手](/clinic/quick-start-with-clinic.md) + - [使用 PingCAP Clinic 诊断集群](/clinic/clinic-user-guide-for-tiup.md) + - [使用 PingCAP Clinic 生成诊断报告](/clinic/clinic-report.md) + - [采集 SQL 查询计划信息](/clinic/clinic-collect-sql-query-plan.md) + - [数据采集说明](/clinic/clinic-data-instruction-for-tiup.md) + - sync-diff-inspector + - [概述](/sync-diff-inspector/sync-diff-inspector-overview.md) + - [不同库名或表名的数据校验](/sync-diff-inspector/route-diff.md) + - [分库分表场景下的数据校验](/sync-diff-inspector/shard-diff.md) + - [基于 DM 同步场景下的数据校验](/sync-diff-inspector/dm-diff.md) + - TiProxy + - [概述](/tiproxy/tiproxy-overview.md) + - [负载均衡策略](/tiproxy/tiproxy-load-balance.md) + - [流量回放](/tiproxy/tiproxy-traffic-replay.md) + - [配置文件](/tiproxy/tiproxy-configuration.md) + - [命令行参数](/tiproxy/tiproxy-command-line-flags.md) + - [监控指标](/tiproxy/tiproxy-grafana.md) + - [API](/tiproxy/tiproxy-api.md) + - [故障诊断](/tiproxy/troubleshoot-tiproxy.md) + - [性能测试报告](/tiproxy/tiproxy-performance-test.md) +- 参考指南 + - 架构 + - [概述](/tidb-architecture.md) + - [存储](/tidb-storage.md) + - [计算](/tidb-computing.md) + - [调度](/tidb-scheduling.md) + - [TSO](/tso.md) + - 存储引擎 TiKV + - [TiKV 简介](/tikv-overview.md) + - [RocksDB 简介](/storage-engine/rocksdb-overview.md) + - [Titan 简介](/storage-engine/titan-overview.md) + - [Titan 配置说明](/storage-engine/titan-configuration.md) + - [Partitioned Raft KV](/partitioned-raft-kv.md) + - 存储引擎 TiFlash + - [TiFlash 简介](/tiflash/tiflash-overview.md) + - [构建 TiFlash 副本](/tiflash/create-tiflash-replicas.md) + - [使用 TiDB 读取 TiFlash](/tiflash/use-tidb-to-read-tiflash.md) + - [使用 MPP 模式](/tiflash/use-tiflash-mpp-mode.md) + - [TiFlash 存算分离架构与 S3 支持](/tiflash/tiflash-disaggregated-and-s3.md) + - [使用 FastScan 功能](/tiflash/use-fastscan.md) + - [TiFlash 支持的计算下推](/tiflash/tiflash-supported-pushdown-calculations.md) + - [TiFlash 查询结果物化](/tiflash/tiflash-results-materialization.md) + - [TiFlash 延迟物化](/tiflash/tiflash-late-materialization.md) + - [TiFlash 数据落盘](/tiflash/tiflash-spill-disk.md) + - [TiFlash 数据校验](/tiflash/tiflash-data-validation.md) + - [TiFlash MinTSO 调度器](/tiflash/tiflash-mintso-scheduler.md) + - [TiFlash 兼容性说明](/tiflash/tiflash-compatibility.md) + - [TiFlash Pipeline Model 执行模型](/tiflash/tiflash-pipeline-model.md) + - TiDB 分布式执行框架 + - [TiDB 分布式执行框架介绍](/tidb-distributed-execution-framework.md) + - [TiDB 全局排序](/tidb-global-sort.md) + - [系统变量](/system-variables.md) + - [系统变量索引](/system-variable-reference.md) + - [服务器状态变量](/status-variables.md) + - 配置文件参数 + - [tidb-server](/tidb-configuration-file.md) + - [tikv-server](/tikv-configuration-file.md) + - [tiflash-server](/tiflash/tiflash-configuration.md) + - [pd-server](/pd-configuration-file.md) + - CLI + - [tikv-ctl](/tikv-control.md) + - [pd-ctl](/pd-control.md) + - [tidb-ctl](/tidb-control.md) + - [pd-recover](/pd-recover.md) + - 命令行参数 + - [tidb-server](/command-line-flags-for-tidb-configuration.md) + - [tikv-server](/command-line-flags-for-tikv-configuration.md) + - [tiflash-server](/tiflash/tiflash-command-line-flags.md) + - [pd-server](/command-line-flags-for-pd-configuration.md) + - 监控指标 + - [Overview 面板](/grafana-overview-dashboard.md) + - [Performance Overview 面板](/grafana-performance-overview-dashboard.md) + - [TiDB 面板](/grafana-tidb-dashboard.md) + - [PD 面板](/grafana-pd-dashboard.md) + - [TiKV 面板](/grafana-tikv-dashboard.md) + - [TiFlash 监控指标](/tiflash/monitor-tiflash.md) + - [TiCDC 监控指标](/ticdc/monitor-ticdc.md) + - [Resource Control 监控指标](/grafana-resource-control-dashboard.md) + - 权限 + - [与 MySQL 安全特性差异](/security-compatibility-with-mysql.md) + - [权限管理](/privilege-management.md) + - [TiDB 用户账户管理](/user-account-management.md) + - [TiDB 密码管理](/password-management.md) + - [基于角色的访问控制](/role-based-access-control.md) + - [TiDB 证书鉴权使用指南](/certificate-authentication.md) + - SQL + - SQL 语言结构和语法 + - 属性 + - [AUTO_INCREMENT](/auto-increment.md) + - [AUTO_RANDOM](/auto-random.md) + - [SHARD_ROW_ID_BITS](/shard-row-id-bits.md) + - [字面值](/literal-values.md) + - [Schema 对象名](/schema-object-names.md) + - [关键字](/keywords.md) + - [用户自定义变量](/user-defined-variables.md) + - [表达式语法](/expression-syntax.md) + - [注释语法](/comment-syntax.md) + - SQL 语句 + - [概览](/sql-statements/sql-statement-overview.md) + - [`ADMIN`](/sql-statements/sql-statement-admin.md) + - [`ADMIN ALTER DDL JOBS`](/sql-statements/sql-statement-admin-alter-ddl.md) + - [`ADMIN CANCEL DDL`](/sql-statements/sql-statement-admin-cancel-ddl.md) + - [`ADMIN CHECKSUM TABLE`](/sql-statements/sql-statement-admin-checksum-table.md) + - [`ADMIN CHECK [TABLE|INDEX]`](/sql-statements/sql-statement-admin-check-table-index.md) + - [`ADMIN CLEANUP`](/sql-statements/sql-statement-admin-cleanup.md) + - [`ADMIN PAUSE DDL`](/sql-statements/sql-statement-admin-pause-ddl.md) + - [`ADMIN RECOVER INDEX`](/sql-statements/sql-statement-admin-recover.md) + - [`ADMIN RESUME DDL`](/sql-statements/sql-statement-admin-resume-ddl.md) + - [`ADMIN [SET|SHOW|UNSET] BDR ROLE`](/sql-statements/sql-statement-admin-bdr-role.md) + - [`ADMIN SHOW DDL [JOBS|JOB QUERIES]`](/sql-statements/sql-statement-admin-show-ddl.md) + - [`ALTER DATABASE`](/sql-statements/sql-statement-alter-database.md) + - [`ALTER INSTANCE`](/sql-statements/sql-statement-alter-instance.md) + - [`ALTER PLACEMENT POLICY`](/sql-statements/sql-statement-alter-placement-policy.md) + - [`ALTER RANGE`](/sql-statements/sql-statement-alter-range.md) + - [`ALTER RESOURCE GROUP`](/sql-statements/sql-statement-alter-resource-group.md) + - [`ALTER SEQUENCE`](/sql-statements/sql-statement-alter-sequence.md) + - `ALTER TABLE` + - [概述](/sql-statements/sql-statement-alter-table.md) + - [`ADD COLUMN`](/sql-statements/sql-statement-add-column.md) + - [`ADD INDEX`](/sql-statements/sql-statement-add-index.md) + - [`ALTER INDEX`](/sql-statements/sql-statement-alter-index.md) + - [`CHANGE COLUMN`](/sql-statements/sql-statement-change-column.md) + - [`COMPACT`](/sql-statements/sql-statement-alter-table-compact.md) + - [`DROP COLUMN`](/sql-statements/sql-statement-drop-column.md) + - [`DROP INDEX`](/sql-statements/sql-statement-drop-index.md) + - [`MODIFY COLUMN`](/sql-statements/sql-statement-modify-column.md) + - [`RENAME INDEX`](/sql-statements/sql-statement-rename-index.md) + - [`ALTER USER`](/sql-statements/sql-statement-alter-user.md) + - [`ANALYZE TABLE`](/sql-statements/sql-statement-analyze-table.md) + - [`BACKUP`](/sql-statements/sql-statement-backup.md) + - [`BATCH`](/sql-statements/sql-statement-batch.md) + - [`BEGIN`](/sql-statements/sql-statement-begin.md) + - [`CALIBRATE RESOURCE`](/sql-statements/sql-statement-calibrate-resource.md) + - [`CANCEL DISTRIBUTION JOB`](/sql-statements/sql-statement-cancel-distribution-job.md) + - [`CANCEL IMPORT JOB`](/sql-statements/sql-statement-cancel-import-job.md) + - [`COMMIT`](/sql-statements/sql-statement-commit.md) + - [`CREATE BINDING`](/sql-statements/sql-statement-create-binding.md) + - [`CREATE DATABASE`](/sql-statements/sql-statement-create-database.md) + - [`CREATE INDEX`](/sql-statements/sql-statement-create-index.md) + - [`CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-create-placement-policy.md) + - [`CREATE RESOURCE GROUP`](/sql-statements/sql-statement-create-resource-group.md) + - [`CREATE ROLE`](/sql-statements/sql-statement-create-role.md) + - [`CREATE SEQUENCE`](/sql-statements/sql-statement-create-sequence.md) + - [`CREATE TABLE LIKE`](/sql-statements/sql-statement-create-table-like.md) + - [`CREATE TABLE`](/sql-statements/sql-statement-create-table.md) + - [`CREATE USER`](/sql-statements/sql-statement-create-user.md) + - [`CREATE VIEW`](/sql-statements/sql-statement-create-view.md) + - [`DEALLOCATE`](/sql-statements/sql-statement-deallocate.md) + - [`DELETE`](/sql-statements/sql-statement-delete.md) + - [`DESC`](/sql-statements/sql-statement-desc.md) + - [`DESCRIBE`](/sql-statements/sql-statement-describe.md) + - [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md) + - [`DO`](/sql-statements/sql-statement-do.md) + - [`DROP BINDING`](/sql-statements/sql-statement-drop-binding.md) + - [`DROP DATABASE`](/sql-statements/sql-statement-drop-database.md) + - [`DROP PLACEMENT POLICY`](/sql-statements/sql-statement-drop-placement-policy.md) + - [`DROP RESOURCE GROUP`](/sql-statements/sql-statement-drop-resource-group.md) + - [`DROP ROLE`](/sql-statements/sql-statement-drop-role.md) + - [`DROP SEQUENCE`](/sql-statements/sql-statement-drop-sequence.md) + - [`DROP STATS`](/sql-statements/sql-statement-drop-stats.md) + - [`DROP TABLE`](/sql-statements/sql-statement-drop-table.md) + - [`DROP USER`](/sql-statements/sql-statement-drop-user.md) + - [`DROP VIEW`](/sql-statements/sql-statement-drop-view.md) + - [`EXECUTE`](/sql-statements/sql-statement-execute.md) + - [`EXPLAIN ANALYZE`](/sql-statements/sql-statement-explain-analyze.md) + - [`EXPLAIN`](/sql-statements/sql-statement-explain.md) + - [`FLASHBACK CLUSTER`](/sql-statements/sql-statement-flashback-cluster.md) + - [`FLASHBACK DATABASE`](/sql-statements/sql-statement-flashback-database.md) + - [`FLASHBACK TABLE`](/sql-statements/sql-statement-flashback-table.md) + - [`FLUSH PRIVILEGES`](/sql-statements/sql-statement-flush-privileges.md) + - [`FLUSH STATUS`](/sql-statements/sql-statement-flush-status.md) + - [`FLUSH TABLES`](/sql-statements/sql-statement-flush-tables.md) + - [`GRANT `](/sql-statements/sql-statement-grant-privileges.md) + - [`GRANT `](/sql-statements/sql-statement-grant-role.md) + - [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md) + - [`INSERT`](/sql-statements/sql-statement-insert.md) + - [`KILL`](/sql-statements/sql-statement-kill.md) + - [`LOAD DATA`](/sql-statements/sql-statement-load-data.md) + - [`LOAD STATS`](/sql-statements/sql-statement-load-stats.md) + - [`LOCK STATS`](/sql-statements/sql-statement-lock-stats.md) + - [`[LOCK|UNLOCK] TABLES`](/sql-statements/sql-statement-lock-tables-and-unlock-tables.md) + - [`PREPARE`](/sql-statements/sql-statement-prepare.md) + - [`QUERY WATCH`](/sql-statements/sql-statement-query-watch.md) + - [`RECOVER TABLE`](/sql-statements/sql-statement-recover-table.md) + - [`RENAME USER`](/sql-statements/sql-statement-rename-user.md) + - [`RENAME TABLE`](/sql-statements/sql-statement-rename-table.md) + - [`REPLACE`](/sql-statements/sql-statement-replace.md) + - [`RESTORE`](/sql-statements/sql-statement-restore.md) + - [`REVOKE `](/sql-statements/sql-statement-revoke-privileges.md) + - [`REVOKE `](/sql-statements/sql-statement-revoke-role.md) + - [`ROLLBACK`](/sql-statements/sql-statement-rollback.md) + - [`SAVEPOINT`](/sql-statements/sql-statement-savepoint.md) + - [`SELECT`](/sql-statements/sql-statement-select.md) + - [`SET DEFAULT ROLE`](/sql-statements/sql-statement-set-default-role.md) + - [`SET [NAMES|CHARACTER SET]`](/sql-statements/sql-statement-set-names.md) + - [`SET PASSWORD`](/sql-statements/sql-statement-set-password.md) + - [`SET RESOURCE GROUP`](/sql-statements/sql-statement-set-resource-group.md) + - [`SET ROLE`](/sql-statements/sql-statement-set-role.md) + - [`SET TRANSACTION`](/sql-statements/sql-statement-set-transaction.md) + - [`SET `](/sql-statements/sql-statement-set-variable.md) + - [`SHOW AFFINITY`](/sql-statements/sql-statement-show-affinity.md) + - [`SHOW [BACKUPS|RESTORES]`](/sql-statements/sql-statement-show-backups.md) + - [`SHOW ANALYZE STATUS`](/sql-statements/sql-statement-show-analyze-status.md) + - [`SHOW BINDINGS`](/sql-statements/sql-statement-show-bindings.md) + - [`SHOW BUILTINS`](/sql-statements/sql-statement-show-builtins.md) + - [`SHOW CHARACTER SET`](/sql-statements/sql-statement-show-character-set.md) + - [`SHOW COLLATION`](/sql-statements/sql-statement-show-collation.md) + - [`SHOW COLUMN_STATS_USAGE`](/sql-statements/sql-statement-show-column-stats-usage.md) + - [`SHOW COLUMNS FROM`](/sql-statements/sql-statement-show-columns-from.md) + - [`SHOW CONFIG`](/sql-statements/sql-statement-show-config.md) + - [`SHOW CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-show-create-placement-policy.md) + - [`SHOW CREATE RESOURCE GROUP`](/sql-statements/sql-statement-show-create-resource-group.md) + - [`SHOW CREATE SEQUENCE`](/sql-statements/sql-statement-show-create-sequence.md) + - [`SHOW CREATE TABLE`](/sql-statements/sql-statement-show-create-table.md) + - [`SHOW CREATE DATABASE`](/sql-statements/sql-statement-show-create-database.md) + - [`SHOW CREATE USER`](/sql-statements/sql-statement-show-create-user.md) + - [`SHOW DATABASES`](/sql-statements/sql-statement-show-databases.md) + - [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md) + - [`SHOW ENGINES`](/sql-statements/sql-statement-show-engines.md) + - [`SHOW ERRORS`](/sql-statements/sql-statement-show-errors.md) + - [`SHOW FIELDS FROM`](/sql-statements/sql-statement-show-fields-from.md) + - [`SHOW GRANTS`](/sql-statements/sql-statement-show-grants.md) + - [`SHOW IMPORT JOB`](/sql-statements/sql-statement-show-import-job.md) + - [`SHOW INDEXES`](/sql-statements/sql-statement-show-indexes.md) + - [`SHOW MASTER STATUS`](/sql-statements/sql-statement-show-master-status.md) + - [`SHOW PLACEMENT`](/sql-statements/sql-statement-show-placement.md) + - [`SHOW PLACEMENT FOR`](/sql-statements/sql-statement-show-placement-for.md) + - [`SHOW PLACEMENT LABELS`](/sql-statements/sql-statement-show-placement-labels.md) + - [`SHOW PLUGINS`](/sql-statements/sql-statement-show-plugins.md) + - [`SHOW PRIVILEGES`](/sql-statements/sql-statement-show-privileges.md) + - [`SHOW PROCESSLIST`](/sql-statements/sql-statement-show-processlist.md) + - [`SHOW PROFILES`](/sql-statements/sql-statement-show-profiles.md) + - [`SHOW SCHEMAS`](/sql-statements/sql-statement-show-schemas.md) + - [`SHOW STATS_BUCKETS`](/sql-statements/sql-statement-show-stats-buckets.md) + - [`SHOW STATS_HEALTHY`](/sql-statements/sql-statement-show-stats-healthy.md) + - [`SHOW STATS_HISTOGRAMS`](/sql-statements/sql-statement-show-stats-histograms.md) + - [`SHOW STATS_LOCKED`](/sql-statements/sql-statement-show-stats-locked.md) + - [`SHOW STATS_META`](/sql-statements/sql-statement-show-stats-meta.md) + - [`SHOW STATS_TOPN`](/sql-statements/sql-statement-show-stats-topn.md) + - [`SHOW STATUS`](/sql-statements/sql-statement-show-status.md) + - [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.md) + - [`SHOW TABLE NEXT_ROW_ID`](/sql-statements/sql-statement-show-table-next-rowid.md) + - [`SHOW TABLE REGIONS`](/sql-statements/sql-statement-show-table-regions.md) + - [`SHOW TABLE STATUS`](/sql-statements/sql-statement-show-table-status.md) + - [`SHOW TABLES`](/sql-statements/sql-statement-show-tables.md) + - [`SHOW VARIABLES`](/sql-statements/sql-statement-show-variables.md) + - [`SHOW WARNINGS`](/sql-statements/sql-statement-show-warnings.md) + - [`SHUTDOWN`](/sql-statements/sql-statement-shutdown.md) + - [`SPLIT REGION`](/sql-statements/sql-statement-split-region.md) + - [`START TRANSACTION`](/sql-statements/sql-statement-start-transaction.md) + - [`TABLE`](/sql-statements/sql-statement-table.md) + - [`TRACE`](/sql-statements/sql-statement-trace.md) + - [`TRUNCATE`](/sql-statements/sql-statement-truncate.md) + - [`UNLOCK STATS`](/sql-statements/sql-statement-unlock-stats.md) + - [`UPDATE`](/sql-statements/sql-statement-update.md) + - [`USE`](/sql-statements/sql-statement-use.md) + - [`WITH`](/sql-statements/sql-statement-with.md) + - 数据类型 + - [数据类型概述](/data-type-overview.md) + - [数据类型默认值](/data-type-default-values.md) + - [数值类型](/data-type-numeric.md) + - [日期和时间类型](/data-type-date-and-time.md) + - [字符串类型](/data-type-string.md) + - [JSON 类型](/data-type-json.md) + - [向量数据类型](/ai/reference/vector-search-data-types.md) + - 函数与操作符 + - [函数与操作符概述](/functions-and-operators/functions-and-operators-overview.md) + - [表达式求值的类型转换](/functions-and-operators/type-conversion-in-expression-evaluation.md) + - [操作符](/functions-and-operators/operators.md) + - [控制流程函数](/functions-and-operators/control-flow-functions.md) + - [字符串函数](/functions-and-operators/string-functions.md) + - [数值函数与操作符](/functions-and-operators/numeric-functions-and-operators.md) + - [日期和时间函数](/functions-and-operators/date-and-time-functions.md) + - [位函数和操作符](/functions-and-operators/bit-functions-and-operators.md) + - [Cast 函数和操作符](/functions-and-operators/cast-functions-and-operators.md) + - [加密和压缩函数](/functions-and-operators/encryption-and-compression-functions.md) + - [锁函数](/functions-and-operators/locking-functions.md) + - [信息函数](/functions-and-operators/information-functions.md) + - [向量函数和操作符](/ai/reference/vector-search-functions-and-operators.md) + - JSON 函数 + - [概览](/functions-and-operators/json-functions.md) + - [创建 JSON 的函数](/functions-and-operators/json-functions/json-functions-create.md) + - [搜索 JSON 的函数](/functions-and-operators/json-functions/json-functions-search.md) + - [修改 JSON 的函数](/functions-and-operators/json-functions/json-functions-modify.md) + - [返回 JSON 的函数](/functions-and-operators/json-functions/json-functions-return.md) + - [JSON 效用函数](/functions-and-operators/json-functions/json-functions-utility.md) + - [聚合 JSON 的函数](/functions-and-operators/json-functions/json-functions-aggregate.md) + - [验证 JSON 的函数](/functions-and-operators/json-functions/json-functions-validate.md) + - [GROUP BY 聚合函数](/functions-and-operators/aggregate-group-by-functions.md) + - [GROUP BY 修饰符](/functions-and-operators/group-by-modifier.md) + - [窗口函数](/functions-and-operators/window-functions.md) + - [序列函数](/functions-and-operators/sequence-functions.md) + - [效用函数](/functions-and-operators/utility-functions.md) + - [其它函数](/functions-and-operators/miscellaneous-functions.md) + - [TiDB 特有的函数](/functions-and-operators/tidb-functions.md) + - [精度数学](/functions-and-operators/precision-math.md) + - [集合运算](/functions-and-operators/set-operators.md) + - [下推到 TiKV 的表达式列表](/functions-and-operators/expressions-pushed-down.md) + - [Oracle 与 TiDB 函数和语法差异对照](/oracle-functions-to-tidb.md) + - [聚簇索引](/clustered-indexes.md) + - [全局索引](/global-indexes.md) + - [向量索引](/ai/reference/vector-search-index.md) + - [约束](/constraints.md) + - [生成列](/generated-columns.md) + - [SQL 模式](/sql-mode.md) + - [表属性](/table-attributes.md) + - 事务 + - [事务概览](/transaction-overview.md) + - [隔离级别](/transaction-isolation-levels.md) + - [乐观事务](/optimistic-transaction.md) + - [悲观事务](/pessimistic-transaction.md) + - [非事务 DML 语句](/non-transactional-dml.md) + - [Pipelined DML](/pipelined-dml.md) + - [视图](/views.md) + - [分区表](/partitioned-table.md) + - [临时表](/temporary-tables.md) + - [缓存表](/cached-tables.md) + - [外键约束](/foreign-key.md) + - [表级数据亲和性](/table-affinity.md) + - 字符集和排序规则 + - [概述](/character-set-and-collation.md) + - [GBK](/character-set-gbk.md) + - [TTL (Time to Live)](/time-to-live.md) + - [Placement Rules in SQL](/placement-rules-in-sql.md) + - 系统表 + - `mysql` Schema + - [概述](/mysql-schema/mysql-schema.md) + - [`tidb_mdl_view`](/mysql-schema/mysql-schema-tidb-mdl-view.md) + - [`user`](/mysql-schema/mysql-schema-user.md) + - INFORMATION_SCHEMA + - [概述](/information-schema/information-schema.md) + - [`ANALYZE_STATUS`](/information-schema/information-schema-analyze-status.md) + - [`CHECK_CONSTRAINTS`](/information-schema/information-schema-check-constraints.md) + - [`CLIENT_ERRORS_SUMMARY_BY_HOST`](/information-schema/client-errors-summary-by-host.md) + - [`CLIENT_ERRORS_SUMMARY_BY_USER`](/information-schema/client-errors-summary-by-user.md) + - [`CLIENT_ERRORS_SUMMARY_GLOBAL`](/information-schema/client-errors-summary-global.md) + - [`CHARACTER_SETS`](/information-schema/information-schema-character-sets.md) + - [`CLUSTER_CONFIG`](/information-schema/information-schema-cluster-config.md) + - [`CLUSTER_HARDWARE`](/information-schema/information-schema-cluster-hardware.md) + - [`CLUSTER_INFO`](/information-schema/information-schema-cluster-info.md) + - [`CLUSTER_LOAD`](/information-schema/information-schema-cluster-load.md) + - [`CLUSTER_LOG`](/information-schema/information-schema-cluster-log.md) + - [`CLUSTER_SYSTEMINFO`](/information-schema/information-schema-cluster-systeminfo.md) + - [`COLLATIONS`](/information-schema/information-schema-collations.md) + - [`COLLATION_CHARACTER_SET_APPLICABILITY`](/information-schema/information-schema-collation-character-set-applicability.md) + - [`COLUMNS`](/information-schema/information-schema-columns.md) + - [`DATA_LOCK_WAITS`](/information-schema/information-schema-data-lock-waits.md) + - [`DDL_JOBS`](/information-schema/information-schema-ddl-jobs.md) + - [`DEADLOCKS`](/information-schema/information-schema-deadlocks.md) + - [`ENGINES`](/information-schema/information-schema-engines.md) + - [`INSPECTION_RESULT`](/information-schema/information-schema-inspection-result.md) + - [`INSPECTION_RULES`](/information-schema/information-schema-inspection-rules.md) + - [`INSPECTION_SUMMARY`](/information-schema/information-schema-inspection-summary.md) + - [`KEYWORDS`](/information-schema/information-schema-keywords.md) + - [`KEY_COLUMN_USAGE`](/information-schema/information-schema-key-column-usage.md) + - [`MEMORY_USAGE`](/information-schema/information-schema-memory-usage.md) + - [`MEMORY_USAGE_OPS_HISTORY`](/information-schema/information-schema-memory-usage-ops-history.md) + - [`METRICS_SUMMARY`](/information-schema/information-schema-metrics-summary.md) + - [`METRICS_TABLES`](/information-schema/information-schema-metrics-tables.md) + - [`PARTITIONS`](/information-schema/information-schema-partitions.md) + - [`PLACEMENT_POLICIES`](/information-schema/information-schema-placement-policies.md) + - [`PROCESSLIST`](/information-schema/information-schema-processlist.md) + - [`REFERENTIAL_CONSTRAINTS`](/information-schema/information-schema-referential-constraints.md) + - [`RESOURCE_GROUPS`](/information-schema/information-schema-resource-groups.md) + - [`RUNAWAY_WATCHES`](/information-schema/information-schema-runaway-watches.md) + - [`SCHEMATA`](/information-schema/information-schema-schemata.md) + - [`SEQUENCES`](/information-schema/information-schema-sequences.md) + - [`SESSION_VARIABLES`](/information-schema/information-schema-session-variables.md) + - [`SLOW_QUERY`](/information-schema/information-schema-slow-query.md) + - [`STATISTICS`](/information-schema/information-schema-statistics.md) + - [`TABLES`](/information-schema/information-schema-tables.md) + - [`TABLE_CONSTRAINTS`](/information-schema/information-schema-table-constraints.md) + - [`TABLE_STORAGE_STATS`](/information-schema/information-schema-table-storage-stats.md) + - [`TIDB_CHECK_CONSTRAINTS`](/information-schema/information-schema-tidb-check-constraints.md) + - [`TIDB_HOT_REGIONS`](/information-schema/information-schema-tidb-hot-regions.md) + - [`TIDB_HOT_REGIONS_HISTORY`](/information-schema/information-schema-tidb-hot-regions-history.md) + - [`TIDB_INDEXES`](/information-schema/information-schema-tidb-indexes.md) + - [`TIDB_INDEX_USAGE`](/information-schema/information-schema-tidb-index-usage.md) + - [`TIDB_SERVERS_INFO`](/information-schema/information-schema-tidb-servers-info.md) + - [`TIDB_TRX`](/information-schema/information-schema-tidb-trx.md) + - [`TIFLASH_INDEXES`](/information-schema/information-schema-tiflash-indexes.md) + - [`TIFLASH_REPLICA`](/information-schema/information-schema-tiflash-replica.md) + - [`TIFLASH_SEGMENTS`](/information-schema/information-schema-tiflash-segments.md) + - [`TIFLASH_TABLES`](/information-schema/information-schema-tiflash-tables.md) + - [`TIKV_REGION_PEERS`](/information-schema/information-schema-tikv-region-peers.md) + - [`TIKV_REGION_STATUS`](/information-schema/information-schema-tikv-region-status.md) + - [`TIKV_STORE_STATUS`](/information-schema/information-schema-tikv-store-status.md) + - [`USER_ATTRIBUTES`](/information-schema/information-schema-user-attributes.md) + - [`USER_PRIVILEGES`](/information-schema/information-schema-user-privileges.md) + - [`VARIABLES_INFO`](/information-schema/information-schema-variables-info.md) + - [`VIEWS`](/information-schema/information-schema-views.md) + - [`METRICS_SCHEMA`](/metrics-schema.md) + - PERFORMANCE_SCHEMA + - [概述](/performance-schema/performance-schema.md) + - [`SESSION_CONNECT_ATTRS`](/performance-schema/performance-schema-session-connect-attrs.md) + - SYS + - [概述](/sys-schema/sys-schema.md) + - [`schema_unused_indexes`](/sys-schema/sys-schema-unused-indexes.md) + - [元数据锁](/metadata-lock.md) + - [TiDB 加速建表](/accelerated-table-creation.md) + - [Schema 缓存](/schema-cache.md) + - [遥测](/telemetry.md) + - [错误码](/error-codes.md) + - [通过拓扑 label 进行副本调度](/schedule-replicas-by-topology-labels.md) + - [外部存储服务的 URI 格式](/external-storage-uri.md) + - [线上负载与 `ADD INDEX` 相互影响测试](/benchmark/online-workloads-and-add-index-operations.md) + - [内嵌于 DDL 的 Analyze](/ddl_embedded_analyze.md) +- 常见问题解答 (FAQ) + - [FAQ 汇总](/faq/faq-overview.md) + - [产品 FAQ](/faq/tidb-faq.md) + - [SQL FAQ](/faq/sql-faq.md) + - [安装部署 FAQ](/faq/deploy-and-maintain-faq.md) + - [迁移 FAQ](/faq/migration-tidb-faq.md) + - [升级 FAQ](/faq/upgrade-faq.md) + - [监控 FAQ](/faq/monitor-faq.md) + - [集群管理 FAQ](/faq/manage-cluster-faq.md) + - [高可用 FAQ](/faq/high-availability-faq.md) + - [高可靠 FAQ](/faq/high-reliability-faq.md) + - [备份恢复 FAQ](/faq/backup-and-restore-faq.md) +- 版本发布历史 + - [版本发布时间线](/releases/release-timeline.md) + - [TiDB 版本规则](/releases/versioning.md) + - [版本周期支持策略](https://pingkai.cn/tidb-release-support-policy) + - [TiDB 离线包](/binary-package.md) + - v8.5 + - [8.5.5](/releases/release-8.5.5.md) + - [8.5.4](/releases/release-8.5.4.md) + - [8.5.3](/releases/release-8.5.3.md) + - [8.5.2](/releases/release-8.5.2.md) + - [8.5.1](/releases/release-8.5.1.md) + - [8.5.0](/releases/release-8.5.0.md) + - v8.4 + - [8.4.0-DMR](/releases/release-8.4.0.md) + - v8.3 + - [8.3.0-DMR](/releases/release-8.3.0.md) + - v8.2 + - [8.2.0-DMR](/releases/release-8.2.0.md) + - v8.1 + - [8.1.2](/releases/release-8.1.2.md) + - [8.1.1](/releases/release-8.1.1.md) + - [8.1.0](/releases/release-8.1.0.md) + - v8.0 + - [8.0.0-DMR](/releases/release-8.0.0.md) + - v7.6 + - [7.6.0-DMR](/releases/release-7.6.0.md) + - v7.5 + - [7.5.7](/releases/release-7.5.7.md) + - [7.5.6](/releases/release-7.5.6.md) + - [7.5.5](/releases/release-7.5.5.md) + - [7.5.4](/releases/release-7.5.4.md) + - [7.5.3](/releases/release-7.5.3.md) + - [7.5.2](/releases/release-7.5.2.md) + - [7.5.1](/releases/release-7.5.1.md) + - [7.5.0](/releases/release-7.5.0.md) + - v7.4 + - [7.4.0-DMR](/releases/release-7.4.0.md) + - v7.3 + - [7.3.0-DMR](/releases/release-7.3.0.md) + - v7.2 + - [7.2.0-DMR](/releases/release-7.2.0.md) + - v7.1 + - [7.1.6](/releases/release-7.1.6.md) + - [7.1.5](/releases/release-7.1.5.md) + - [7.1.4](/releases/release-7.1.4.md) + - [7.1.3](/releases/release-7.1.3.md) + - [7.1.2](/releases/release-7.1.2.md) + - [7.1.1](/releases/release-7.1.1.md) + - [7.1.0](/releases/release-7.1.0.md) + - v7.0 + - [7.0.0-DMR](/releases/release-7.0.0.md) + - v6.6 + - [6.6.0-DMR](/releases/release-6.6.0.md) + - v6.5 + - [6.5.12](/releases/release-6.5.12.md) + - [6.5.11](/releases/release-6.5.11.md) + - [6.5.10](/releases/release-6.5.10.md) + - [6.5.9](/releases/release-6.5.9.md) + - [6.5.8](/releases/release-6.5.8.md) + - [6.5.7](/releases/release-6.5.7.md) + - [6.5.6](/releases/release-6.5.6.md) + - [6.5.5](/releases/release-6.5.5.md) + - [6.5.4](/releases/release-6.5.4.md) + - [6.5.3](/releases/release-6.5.3.md) + - [6.5.2](/releases/release-6.5.2.md) + - [6.5.1](/releases/release-6.5.1.md) + - [6.5.0](/releases/release-6.5.0.md) + - v6.4 + - [6.4.0-DMR](/releases/release-6.4.0.md) + - v6.3 + - [6.3.0-DMR](/releases/release-6.3.0.md) + - v6.2 + - [6.2.0-DMR](/releases/release-6.2.0.md) + - v6.1 + - [6.1.7](/releases/release-6.1.7.md) + - [6.1.6](/releases/release-6.1.6.md) + - [6.1.5](/releases/release-6.1.5.md) + - [6.1.4](/releases/release-6.1.4.md) + - [6.1.3](/releases/release-6.1.3.md) + - [6.1.2](/releases/release-6.1.2.md) + - [6.1.1](/releases/release-6.1.1.md) + - [6.1.0](/releases/release-6.1.0.md) + - v6.0 + - [6.0.0-DMR](/releases/release-6.0.0-dmr.md) + - v5.4 + - [5.4.3](/releases/release-5.4.3.md) + - [5.4.2](/releases/release-5.4.2.md) + - [5.4.1](/releases/release-5.4.1.md) + - [5.4.0](/releases/release-5.4.0.md) + - v5.3 + - [5.3.4](/releases/release-5.3.4.md) + - [5.3.3](/releases/release-5.3.3.md) + - [5.3.2](/releases/release-5.3.2.md) + - [5.3.1](/releases/release-5.3.1.md) + - [5.3.0](/releases/release-5.3.0.md) + - v5.2 + - [5.2.4](/releases/release-5.2.4.md) + - [5.2.3](/releases/release-5.2.3.md) + - [5.2.2](/releases/release-5.2.2.md) + - [5.2.1](/releases/release-5.2.1.md) + - [5.2.0](/releases/release-5.2.0.md) + - v5.1 + - [5.1.5](/releases/release-5.1.5.md) + - [5.1.4](/releases/release-5.1.4.md) + - [5.1.3](/releases/release-5.1.3.md) + - [5.1.2](/releases/release-5.1.2.md) + - [5.1.1](/releases/release-5.1.1.md) + - [5.1.0](/releases/release-5.1.0.md) + - v5.0 + - [5.0.6](/releases/release-5.0.6.md) + - [5.0.5](/releases/release-5.0.5.md) + - [5.0.4](/releases/release-5.0.4.md) + - [5.0.3](/releases/release-5.0.3.md) + - [5.0.2](/releases/release-5.0.2.md) + - [5.0.1](/releases/release-5.0.1.md) + - [5.0 GA](/releases/release-5.0.0.md) + - [5.0.0-rc](/releases/release-5.0.0-rc.md) + - v4.0 + - [4.0.16](/releases/release-4.0.16.md) + - [4.0.15](/releases/release-4.0.15.md) + - [4.0.14](/releases/release-4.0.14.md) + - [4.0.13](/releases/release-4.0.13.md) + - [4.0.12](/releases/release-4.0.12.md) + - [4.0.11](/releases/release-4.0.11.md) + - [4.0.10](/releases/release-4.0.10.md) + - [4.0.9](/releases/release-4.0.9.md) + - [4.0.8](/releases/release-4.0.8.md) + - [4.0.7](/releases/release-4.0.7.md) + - [4.0.6](/releases/release-4.0.6.md) + - [4.0.5](/releases/release-4.0.5.md) + - [4.0.4](/releases/release-4.0.4.md) + - [4.0.3](/releases/release-4.0.3.md) + - [4.0.2](/releases/release-4.0.2.md) + - [4.0.1](/releases/release-4.0.1.md) + - [4.0 GA](/releases/release-4.0-ga.md) + - [4.0.0-rc.2](/releases/release-4.0.0-rc.2.md) + - [4.0.0-rc.1](/releases/release-4.0.0-rc.1.md) + - [4.0.0-rc](/releases/release-4.0.0-rc.md) + - [4.0.0-beta.2](/releases/release-4.0.0-beta.2.md) + - [4.0.0-beta.1](/releases/release-4.0.0-beta.1.md) + - [4.0.0-beta](/releases/release-4.0.0-beta.md) + - v3.1 + - [3.1.2](/releases/release-3.1.2.md) + - [3.1.1](/releases/release-3.1.1.md) + - [3.1.0 GA](/releases/release-3.1.0-ga.md) + - [3.1.0-rc](/releases/release-3.1.0-rc.md) + - [3.1.0-beta.2](/releases/release-3.1.0-beta.2.md) + - [3.1.0-beta.1](/releases/release-3.1.0-beta.1.md) + - [3.1.0-beta](/releases/release-3.1.0-beta.md) + - v3.0 + - [3.0.20](/releases/release-3.0.20.md) + - [3.0.19](/releases/release-3.0.19.md) + - [3.0.18](/releases/release-3.0.18.md) + - [3.0.17](/releases/release-3.0.17.md) + - [3.0.16](/releases/release-3.0.16.md) + - [3.0.15](/releases/release-3.0.15.md) + - [3.0.14](/releases/release-3.0.14.md) + - [3.0.13](/releases/release-3.0.13.md) + - [3.0.12](/releases/release-3.0.12.md) + - [3.0.11](/releases/release-3.0.11.md) + - [3.0.10](/releases/release-3.0.10.md) + - [3.0.9](/releases/release-3.0.9.md) + - [3.0.8](/releases/release-3.0.8.md) + - [3.0.7](/releases/release-3.0.7.md) + - [3.0.6](/releases/release-3.0.6.md) + - [3.0.5](/releases/release-3.0.5.md) + - [3.0.4](/releases/release-3.0.4.md) + - [3.0.3](/releases/release-3.0.3.md) + - [3.0.2](/releases/release-3.0.2.md) + - [3.0.1](/releases/release-3.0.1.md) + - [3.0 GA](/releases/release-3.0-ga.md) + - [3.0.0-rc.3](/releases/release-3.0.0-rc.3.md) + - [3.0.0-rc.2](/releases/release-3.0.0-rc.2.md) + - [3.0.0-rc.1](/releases/release-3.0.0-rc.1.md) + - [3.0.0-beta.1](/releases/release-3.0.0-beta.1.md) + - [3.0.0-beta](/releases/release-3.0-beta.md) + - v2.1 + - [2.1.19](/releases/release-2.1.19.md) + - [2.1.18](/releases/release-2.1.18.md) + - [2.1.17](/releases/release-2.1.17.md) + - [2.1.16](/releases/release-2.1.16.md) + - [2.1.15](/releases/release-2.1.15.md) + - [2.1.14](/releases/release-2.1.14.md) + - [2.1.13](/releases/release-2.1.13.md) + - [2.1.12](/releases/release-2.1.12.md) + - [2.1.11](/releases/release-2.1.11.md) + - [2.1.10](/releases/release-2.1.10.md) + - [2.1.9](/releases/release-2.1.9.md) + - [2.1.8](/releases/release-2.1.8.md) + - [2.1.7](/releases/release-2.1.7.md) + - [2.1.6](/releases/release-2.1.6.md) + - [2.1.5](/releases/release-2.1.5.md) + - [2.1.4](/releases/release-2.1.4.md) + - [2.1.3](/releases/release-2.1.3.md) + - [2.1.2](/releases/release-2.1.2.md) + - [2.1.1](/releases/release-2.1.1.md) + - [2.1 GA](/releases/release-2.1-ga.md) + - [2.1 RC5](/releases/release-2.1-rc.5.md) + - [2.1 RC4](/releases/release-2.1-rc.4.md) + - [2.1 RC3](/releases/release-2.1-rc.3.md) + - [2.1 RC2](/releases/release-2.1-rc.2.md) + - [2.1 RC1](/releases/release-2.1-rc.1.md) + - [2.1 Beta](/releases/release-2.1-beta.md) + - v2.0 + - [2.0.11](/releases/release-2.0.11.md) + - [2.0.10](/releases/release-2.0.10.md) + - [2.0.9](/releases/release-2.0.9.md) + - [2.0.8](/releases/release-2.0.8.md) + - [2.0.7](/releases/release-2.0.7.md) + - [2.0.6](/releases/release-2.0.6.md) + - [2.0.5](/releases/release-2.0.5.md) + - [2.0.4](/releases/release-2.0.4.md) + - [2.0.3](/releases/release-2.0.3.md) + - [2.0.2](/releases/release-2.0.2.md) + - [2.0.1](/releases/release-2.0.1.md) + - [2.0](/releases/release-2.0-ga.md) + - [2.0 RC5](/releases/release-2.0-rc.5.md) + - [2.0 RC4](/releases/release-2.0-rc.4.md) + - [2.0 RC3](/releases/release-2.0-rc.3.md) + - [2.0 RC1](/releases/release-2.0-rc.1.md) + - [1.1 Beta](/releases/release-1.1-beta.md) + - [1.1 Alpha](/releases/release-1.1-alpha.md) + - v1.0 + - [1.0](/releases/release-1.0-ga.md) + - [Pre-GA](/releases/release-pre-ga.md) + - [RC4](/releases/release-rc.4.md) + - [RC3](/releases/release-rc.3.md) + - [RC2](/releases/release-rc.2.md) + - [RC1](/releases/release-rc.1.md) +- [术语表](/glossary.md) diff --git a/TOC-tidb-releases.md b/TOC-tidb-releases.md new file mode 100644 index 000000000000..c28fb01594b0 --- /dev/null +++ b/TOC-tidb-releases.md @@ -0,0 +1,238 @@ + + + +# 目录 + +## 版本概览 + +- [版本发布时间线](/releases/release-timeline.md) +- [TiDB 版本规则](/releases/versioning.md) +- [版本周期支持策略](https://pingkai.cn/tidb-release-support-policy) + +## 版本发布说明 + +- v8.5 + - [8.5.5](/releases/release-8.5.5.md) + - [8.5.4](/releases/release-8.5.4.md) + - [8.5.3](/releases/release-8.5.3.md) + - [8.5.2](/releases/release-8.5.2.md) + - [8.5.1](/releases/release-8.5.1.md) + - [8.5.0](/releases/release-8.5.0.md) +- v8.4 + - [8.4.0-DMR](/releases/release-8.4.0.md) +- v8.3 + - [8.3.0-DMR](/releases/release-8.3.0.md) +- v8.2 + - [8.2.0-DMR](/releases/release-8.2.0.md) +- v8.1 + - [8.1.2](/releases/release-8.1.2.md) + - [8.1.1](/releases/release-8.1.1.md) + - [8.1.0](/releases/release-8.1.0.md) +- v8.0 + - [8.0.0-DMR](/releases/release-8.0.0.md) +- v7.6 + - [7.6.0-DMR](/releases/release-7.6.0.md) +- v7.5 + - [7.5.7](/releases/release-7.5.7.md) + - [7.5.6](/releases/release-7.5.6.md) + - [7.5.5](/releases/release-7.5.5.md) + - [7.5.4](/releases/release-7.5.4.md) + - [7.5.3](/releases/release-7.5.3.md) + - [7.5.2](/releases/release-7.5.2.md) + - [7.5.1](/releases/release-7.5.1.md) + - [7.5.0](/releases/release-7.5.0.md) +- v7.4 + - [7.4.0-DMR](/releases/release-7.4.0.md) +- v7.3 + - [7.3.0-DMR](/releases/release-7.3.0.md) +- v7.2 + - [7.2.0-DMR](/releases/release-7.2.0.md) +- v7.1 + - [7.1.6](/releases/release-7.1.6.md) + - [7.1.5](/releases/release-7.1.5.md) + - [7.1.4](/releases/release-7.1.4.md) + - [7.1.3](/releases/release-7.1.3.md) + - [7.1.2](/releases/release-7.1.2.md) + - [7.1.1](/releases/release-7.1.1.md) + - [7.1.0](/releases/release-7.1.0.md) +- v7.0 + - [7.0.0-DMR](/releases/release-7.0.0.md) +- v6.6 + - [6.6.0-DMR](/releases/release-6.6.0.md) +- v6.5 + - [6.5.12](/releases/release-6.5.12.md) + - [6.5.11](/releases/release-6.5.11.md) + - [6.5.10](/releases/release-6.5.10.md) + - [6.5.9](/releases/release-6.5.9.md) + - [6.5.8](/releases/release-6.5.8.md) + - [6.5.7](/releases/release-6.5.7.md) + - [6.5.6](/releases/release-6.5.6.md) + - [6.5.5](/releases/release-6.5.5.md) + - [6.5.4](/releases/release-6.5.4.md) + - [6.5.3](/releases/release-6.5.3.md) + - [6.5.2](/releases/release-6.5.2.md) + - [6.5.1](/releases/release-6.5.1.md) + - [6.5.0](/releases/release-6.5.0.md) +- v6.4 + - [6.4.0-DMR](/releases/release-6.4.0.md) +- v6.3 + - [6.3.0-DMR](/releases/release-6.3.0.md) +- v6.2 + - [6.2.0-DMR](/releases/release-6.2.0.md) +- v6.1 + - [6.1.7](/releases/release-6.1.7.md) + - [6.1.6](/releases/release-6.1.6.md) + - [6.1.5](/releases/release-6.1.5.md) + - [6.1.4](/releases/release-6.1.4.md) + - [6.1.3](/releases/release-6.1.3.md) + - [6.1.2](/releases/release-6.1.2.md) + - [6.1.1](/releases/release-6.1.1.md) + - [6.1.0](/releases/release-6.1.0.md) +- v6.0 + - [6.0.0-DMR](/releases/release-6.0.0-dmr.md) +- v5.4 + - [5.4.3](/releases/release-5.4.3.md) + - [5.4.2](/releases/release-5.4.2.md) + - [5.4.1](/releases/release-5.4.1.md) + - [5.4.0](/releases/release-5.4.0.md) +- End of Life 版本 + - v5.3 + - [5.3.4](/releases/release-5.3.4.md) + - [5.3.3](/releases/release-5.3.3.md) + - [5.3.2](/releases/release-5.3.2.md) + - [5.3.1](/releases/release-5.3.1.md) + - [5.3.0](/releases/release-5.3.0.md) + - v5.2 + - [5.2.4](/releases/release-5.2.4.md) + - [5.2.3](/releases/release-5.2.3.md) + - [5.2.2](/releases/release-5.2.2.md) + - [5.2.1](/releases/release-5.2.1.md) + - [5.2.0](/releases/release-5.2.0.md) + - v5.1 + - [5.1.5](/releases/release-5.1.5.md) + - [5.1.4](/releases/release-5.1.4.md) + - [5.1.3](/releases/release-5.1.3.md) + - [5.1.2](/releases/release-5.1.2.md) + - [5.1.1](/releases/release-5.1.1.md) + - [5.1.0](/releases/release-5.1.0.md) + - v5.0 + - [5.0.6](/releases/release-5.0.6.md) + - [5.0.5](/releases/release-5.0.5.md) + - [5.0.4](/releases/release-5.0.4.md) + - [5.0.3](/releases/release-5.0.3.md) + - [5.0.2](/releases/release-5.0.2.md) + - [5.0.1](/releases/release-5.0.1.md) + - [5.0 GA](/releases/release-5.0.0.md) + - [5.0.0-rc](/releases/release-5.0.0-rc.md) + - v4.0 + - [4.0.16](/releases/release-4.0.16.md) + - [4.0.15](/releases/release-4.0.15.md) + - [4.0.14](/releases/release-4.0.14.md) + - [4.0.13](/releases/release-4.0.13.md) + - [4.0.12](/releases/release-4.0.12.md) + - [4.0.11](/releases/release-4.0.11.md) + - [4.0.10](/releases/release-4.0.10.md) + - [4.0.9](/releases/release-4.0.9.md) + - [4.0.8](/releases/release-4.0.8.md) + - [4.0.7](/releases/release-4.0.7.md) + - [4.0.6](/releases/release-4.0.6.md) + - [4.0.5](/releases/release-4.0.5.md) + - [4.0.4](/releases/release-4.0.4.md) + - [4.0.3](/releases/release-4.0.3.md) + - [4.0.2](/releases/release-4.0.2.md) + - [4.0.1](/releases/release-4.0.1.md) + - [4.0 GA](/releases/release-4.0-ga.md) + - [4.0.0-rc.2](/releases/release-4.0.0-rc.2.md) + - [4.0.0-rc.1](/releases/release-4.0.0-rc.1.md) + - [4.0.0-rc](/releases/release-4.0.0-rc.md) + - [4.0.0-beta.2](/releases/release-4.0.0-beta.2.md) + - [4.0.0-beta.1](/releases/release-4.0.0-beta.1.md) + - [4.0.0-beta](/releases/release-4.0.0-beta.md) + - v3.1 + - [3.1.2](/releases/release-3.1.2.md) + - [3.1.1](/releases/release-3.1.1.md) + - [3.1.0 GA](/releases/release-3.1.0-ga.md) + - [3.1.0-rc](/releases/release-3.1.0-rc.md) + - [3.1.0-beta.2](/releases/release-3.1.0-beta.2.md) + - [3.1.0-beta.1](/releases/release-3.1.0-beta.1.md) + - [3.1.0-beta](/releases/release-3.1.0-beta.md) + - v3.0 + - [3.0.20](/releases/release-3.0.20.md) + - [3.0.19](/releases/release-3.0.19.md) + - [3.0.18](/releases/release-3.0.18.md) + - [3.0.17](/releases/release-3.0.17.md) + - [3.0.16](/releases/release-3.0.16.md) + - [3.0.15](/releases/release-3.0.15.md) + - [3.0.14](/releases/release-3.0.14.md) + - [3.0.13](/releases/release-3.0.13.md) + - [3.0.12](/releases/release-3.0.12.md) + - [3.0.11](/releases/release-3.0.11.md) + - [3.0.10](/releases/release-3.0.10.md) + - [3.0.9](/releases/release-3.0.9.md) + - [3.0.8](/releases/release-3.0.8.md) + - [3.0.7](/releases/release-3.0.7.md) + - [3.0.6](/releases/release-3.0.6.md) + - [3.0.5](/releases/release-3.0.5.md) + - [3.0.4](/releases/release-3.0.4.md) + - [3.0.3](/releases/release-3.0.3.md) + - [3.0.2](/releases/release-3.0.2.md) + - [3.0.1](/releases/release-3.0.1.md) + - [3.0 GA](/releases/release-3.0-ga.md) + - [3.0.0-rc.3](/releases/release-3.0.0-rc.3.md) + - [3.0.0-rc.2](/releases/release-3.0.0-rc.2.md) + - [3.0.0-rc.1](/releases/release-3.0.0-rc.1.md) + - [3.0.0-beta.1](/releases/release-3.0.0-beta.1.md) + - [3.0.0-beta](/releases/release-3.0-beta.md) + - v2.1 + - [2.1.19](/releases/release-2.1.19.md) + - [2.1.18](/releases/release-2.1.18.md) + - [2.1.17](/releases/release-2.1.17.md) + - [2.1.16](/releases/release-2.1.16.md) + - [2.1.15](/releases/release-2.1.15.md) + - [2.1.14](/releases/release-2.1.14.md) + - [2.1.13](/releases/release-2.1.13.md) + - [2.1.12](/releases/release-2.1.12.md) + - [2.1.11](/releases/release-2.1.11.md) + - [2.1.10](/releases/release-2.1.10.md) + - [2.1.9](/releases/release-2.1.9.md) + - [2.1.8](/releases/release-2.1.8.md) + - [2.1.7](/releases/release-2.1.7.md) + - [2.1.6](/releases/release-2.1.6.md) + - [2.1.5](/releases/release-2.1.5.md) + - [2.1.4](/releases/release-2.1.4.md) + - [2.1.3](/releases/release-2.1.3.md) + - [2.1.2](/releases/release-2.1.2.md) + - [2.1.1](/releases/release-2.1.1.md) + - [2.1 GA](/releases/release-2.1-ga.md) + - [2.1 RC5](/releases/release-2.1-rc.5.md) + - [2.1 RC4](/releases/release-2.1-rc.4.md) + - [2.1 RC3](/releases/release-2.1-rc.3.md) + - [2.1 RC2](/releases/release-2.1-rc.2.md) + - [2.1 RC1](/releases/release-2.1-rc.1.md) + - [2.1 Beta](/releases/release-2.1-beta.md) + - v2.0 + - [2.0.11](/releases/release-2.0.11.md) + - [2.0.10](/releases/release-2.0.10.md) + - [2.0.9](/releases/release-2.0.9.md) + - [2.0.8](/releases/release-2.0.8.md) + - [2.0.7](/releases/release-2.0.7.md) + - [2.0.6](/releases/release-2.0.6.md) + - [2.0.5](/releases/release-2.0.5.md) + - [2.0.4](/releases/release-2.0.4.md) + - [2.0.3](/releases/release-2.0.3.md) + - [2.0.2](/releases/release-2.0.2.md) + - [2.0.1](/releases/release-2.0.1.md) + - [2.0](/releases/release-2.0-ga.md) + - [2.0 RC5](/releases/release-2.0-rc.5.md) + - [2.0 RC4](/releases/release-2.0-rc.4.md) + - [2.0 RC3](/releases/release-2.0-rc.3.md) + - [2.0 RC1](/releases/release-2.0-rc.1.md) + - [1.1 Beta](/releases/release-1.1-beta.md) + - [1.1 Alpha](/releases/release-1.1-alpha.md) + - v1.0 + - [1.0](/releases/release-1.0-ga.md) + - [Pre-GA](/releases/release-pre-ga.md) + - [RC4](/releases/release-rc.4.md) + - [RC3](/releases/release-rc.3.md) + - [RC2](/releases/release-rc.2.md) + - [RC1](/releases/release-rc.1.md) diff --git a/TOC.md b/TOC.md index 9e288abf7d06..0f4e27c25b0e 100644 --- a/TOC.md +++ b/TOC.md @@ -1,128 +1,18 @@ -- [文档中心](https://docs.pingcap.com/zh) - 关于 TiDB - [TiDB 简介](/overview.md) - - [TiDB 8.4 Release Notes](/releases/release-8.4.0.md) + - [TiDB 8.5 Release Notes](/releases/release-8.5.0.md) - [功能概览](/basic-features.md) - [与 MySQL 的兼容性](/mysql-compatibility.md) - [使用限制](/tidb-limitations.md) - [荣誉列表](/credits.md) - - [路线图](/tidb-roadmap.md) - 快速上手 - [快速上手 TiDB](/quick-start-with-tidb.md) - [快速上手 HTAP](/quick-start-with-htap.md) - [SQL 基本操作](/basic-sql-operations.md) - [深入探索 HTAP](/explore-htap.md) -- 应用开发 - - [概览](/develop/dev-guide-overview.md) - - 快速开始 - - [使用 TiDB Cloud Serverless 构建 TiDB 集群](/develop/dev-guide-build-cluster-in-cloud.md) - - [使用 TiDB 的增删改查 SQL](/develop/dev-guide-tidb-crud-sql.md) - - 示例程序 - - Java - - [JDBC](/develop/dev-guide-sample-application-java-jdbc.md) - - [MyBatis](/develop/dev-guide-sample-application-java-mybatis.md) - - [Hibernate](/develop/dev-guide-sample-application-java-hibernate.md) - - [Spring Boot](/develop/dev-guide-sample-application-java-spring-boot.md) - - Go - - [Go-MySQL-Driver](/develop/dev-guide-sample-application-golang-sql-driver.md) - - [GORM](/develop/dev-guide-sample-application-golang-gorm.md) - - Python - - [mysqlclient](/develop/dev-guide-sample-application-python-mysqlclient.md) - - [MySQL Connector/Python](/develop/dev-guide-sample-application-python-mysql-connector.md) - - [PyMySQL](/develop/dev-guide-sample-application-python-pymysql.md) - - [SQLAlchemy](/develop/dev-guide-sample-application-python-sqlalchemy.md) - - [peewee](/develop/dev-guide-sample-application-python-peewee.md) - - [Django](/develop/dev-guide-sample-application-python-django.md) - - Node.js - - [node-mysql2](/develop/dev-guide-sample-application-nodejs-mysql2.md) - - [mysql.js](/develop/dev-guide-sample-application-nodejs-mysqljs.md) - - [Prisma](/develop/dev-guide-sample-application-nodejs-prisma.md) - - [Sequelize](/develop/dev-guide-sample-application-nodejs-sequelize.md) - - [TypeORM](/develop/dev-guide-sample-application-nodejs-typeorm.md) - - [Next.js](/develop/dev-guide-sample-application-nextjs.md) - - [AWS Lambda](/develop/dev-guide-sample-application-aws-lambda.md) - - Ruby - - [mysql2](/develop/dev-guide-sample-application-ruby-mysql2.md) - - [Rails](/develop/dev-guide-sample-application-ruby-rails.md) - - 连接到 TiDB - - GUI 数据库工具 - - [MySQL Workbench](/develop/dev-guide-gui-mysql-workbench.md) - - [Navicat](/develop/dev-guide-gui-navicat.md) - - [选择驱动或 ORM 框架](/develop/dev-guide-choose-driver-or-orm.md) - - [连接到 TiDB](/develop/dev-guide-connect-to-tidb.md) - - [连接池与连接参数](/develop/dev-guide-connection-parameters.md) - - 数据库模式设计 - - [概览](/develop/dev-guide-schema-design-overview.md) - - [创建数据库](/develop/dev-guide-create-database.md) - - [创建表](/develop/dev-guide-create-table.md) - - [创建二级索引](/develop/dev-guide-create-secondary-indexes.md) - - 数据写入 - - [插入数据](/develop/dev-guide-insert-data.md) - - [更新数据](/develop/dev-guide-update-data.md) - - [删除数据](/develop/dev-guide-delete-data.md) - - [使用 TTL (Time to Live) 定期删除过期数据](/time-to-live.md) - - [预处理语句](/develop/dev-guide-prepared-statement.md) - - 数据读取 - - [单表读取](/develop/dev-guide-get-data-from-single-table.md) - - [多表连接查询](/develop/dev-guide-join-tables.md) - - [子查询](/develop/dev-guide-use-subqueries.md) - - [查询结果分页](/develop/dev-guide-paginate-results.md) - - [视图](/develop/dev-guide-use-views.md) - - [临时表](/develop/dev-guide-use-temporary-tables.md) - - [公共表表达式](/develop/dev-guide-use-common-table-expression.md) - - 读取副本数据 - - [Follower Read](/develop/dev-guide-use-follower-read.md) - - [Stale Read](/develop/dev-guide-use-stale-read.md) - - [HTAP 查询](/develop/dev-guide-hybrid-oltp-and-olap-queries.md) - - 向量搜索 - - [概述](/vector-search-overview.md) - - 快速入门 - - [使用 SQL 开始向量搜索](/vector-search-get-started-using-sql.md) - - [使用 Python 开始向量搜索](/vector-search-get-started-using-python.md) - - 集成 - - [集成概览](/vector-search-integration-overview.md) - - AI 框架 - - [LlamaIndex](/vector-search-integrate-with-llamaindex.md) - - [Langchain](/vector-search-integrate-with-langchain.md) - - 嵌入模型/服务 - - [Jina AI](/vector-search-integrate-with-jinaai-embedding.md) - - ORM 库 - - [SQLAlchemy](/vector-search-integrate-with-sqlalchemy.md) - - [peewee](/vector-search-integrate-with-peewee.md) - - [Django](/vector-search-integrate-with-django-orm.md) - - [优化搜索性能](/vector-search-improve-performance.md) - - [使用限制](/vector-search-limitations.md) - - 事务 - - [概览](/develop/dev-guide-transaction-overview.md) - - [乐观事务和悲观事务](/develop/dev-guide-optimistic-and-pessimistic-transaction.md) - - [事务限制](/develop/dev-guide-transaction-restraints.md) - - [事务错误处理](/develop/dev-guide-transaction-troubleshoot.md) - - 优化 SQL 性能 - - [概览](/develop/dev-guide-optimize-sql-overview.md) - - [SQL 性能调优](/develop/dev-guide-optimize-sql.md) - - [性能调优最佳实践](/develop/dev-guide-optimize-sql-best-practices.md) - - [索引的最佳实践](/develop/dev-guide-index-best-practice.md) - - 其他优化 - - [避免隐式类型转换](/develop/dev-guide-implicit-type-conversion.md) - - [唯一序列号生成方案](/develop/dev-guide-unique-serial-number-generation.md) - - 故障诊断 - - [SQL 或事务问题](/develop/dev-guide-troubleshoot-overview.md) - - [结果集不稳定](/develop/dev-guide-unstable-result-set.md) - - [超时](/develop/dev-guide-timeouts-in-tidb.md) - - 引用文档 - - [Bookshop 示例应用](/develop/dev-guide-bookshop-schema-design.md) - - 规范 - - [命名规范](/develop/dev-guide-object-naming-guidelines.md) - - [SQL 开发规范](/develop/dev-guide-sql-development-specification.md) - - 云原生开发环境 - - [Gitpod](/develop/dev-guide-playground-gitpod.md) - - 第三方工具支持 - - [TiDB 支持的第三方工具](/develop/dev-guide-third-party-support.md) - - [已知的第三方工具兼容问题](/develop/dev-guide-third-party-tools-compatibility.md) - - [ProxySQL 集成指南](/develop/dev-guide-proxysql-integration.md) - 部署标准集群 - [软硬件环境需求](/hardware-and-software-requirements.md) - [环境与系统配置检查](/check-before-deployment.md) @@ -132,7 +22,6 @@ - [PD 微服务部署拓扑](/pd-microservices-deployment-topology.md) - [TiProxy 部署拓扑](/tiproxy/tiproxy-deployment-topology.md) - [TiCDC 部署拓扑](/ticdc-deployment-topology.md) - - [TiSpark 部署拓扑](/tispark-deployment-topology.md) - [跨机房部署拓扑结构](/geo-distributed-deployment-topology.md) - [混合部署拓扑结构](/hybrid-deployment-topology.md) - [使用 TiUP 部署](/production-deployment-using-tiup.md) @@ -184,10 +73,13 @@ - [报警规则](/ticdc/ticdc-alert-rules.md) - 数据集成场景 - [数据集成概述](/integration-overview.md) - - [与 Confluent Cloud 和 Snowflake 进行数据集成](/ticdc/integrate-confluent-using-ticdc.md) + - [与 Confluent Cloud 和 Snowflake、ksqlDB、SQL Server 进行数据集成](/ticdc/integrate-confluent-using-ticdc.md) - [与 Apache Kafka 和 Apache Flink 进行数据集成](/replicate-data-to-kafka.md) - 参考指南 - - [TiCDC 架构设计与原理](/ticdc/ticdc-architecture.md) + - TiCDC 架构设计与原理 + - [TiCDC 新架构](/ticdc/ticdc-architecture.md) + - [TiCDC 老架构](/ticdc/ticdc-classic-architecture.md) + - [TiCDC 数据同步能力详解](/ticdc/ticdc-data-replication-capabilities.md) - [TiCDC Server 配置参数](/ticdc/ticdc-server-config.md) - [TiCDC Changefeed 配置参数](/ticdc/ticdc-changefeed-config.md) - [TiCDC 客户端鉴权](/ticdc/ticdc-client-authentication.md) @@ -223,6 +115,7 @@ - [使用 TiUP 升级](/upgrade-tidb-using-tiup.md) - [使用 TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/upgrade-a-tidb-cluster) - [平滑升级 TiDB](/smooth-upgrade-tidb.md) + - [迁移升级 TiDB](/tidb-upgrade-migration-guide.md) - [TiFlash 升级帮助](/tiflash-upgrade-guide.md) - 扩缩容 - [使用 TiUP（推荐）](/scale-tidb-using-tiup.md) @@ -237,6 +130,7 @@ - [使用概述](/br/br-use-overview.md) - [快照备份与恢复](/br/br-snapshot-guide.md) - [日志备份与 PITR](/br/br-pitr-guide.md) + - [压缩日志备份](/br/br-compact-log-backup.md) - [实践示例](/br/backup-and-restore-use-cases.md) - [备份存储](/br/backup-and-restore-storages.md) - br cli 命令手册 @@ -257,7 +151,10 @@ - [基于主备集群的容灾](/dr-secondary-cluster.md) - [基于多副本的单集群容灾](/dr-multi-replica.md) - [基于备份与恢复的容灾](/dr-backup-restore.md) - - [使用资源管控 (Resource Control) 实现资源隔离](/tidb-resource-control.md) + - 资源管控 + - [使用资源管控 (Resource Control) 实现资源组限制和流控](/tidb-resource-control-ru-groups.md) + - [管理资源消耗超出预期的查询 (Runaway Queries)](/tidb-resource-control-runaway-queries.md) + - [限制后台任务资源使用](/tidb-resource-control-background-tasks.md) - [修改时区](/configure-time-zone.md) - [日常巡检](/daily-check.md) - [TiFlash 常用运维操作](/tiflash/maintain-tiflash.md) @@ -270,6 +167,37 @@ - [监控 API](/tidb-monitoring-api.md) - [手动部署监控](/deploy-monitoring-services.md) - [升级监控组件](/upgrade-monitoring-services.md) + - TiDB Dashboard + - [简介](/dashboard/dashboard-intro.md) + - 运维 + - [部署](/dashboard/dashboard-ops-deploy.md) + - [反向代理](/dashboard/dashboard-ops-reverse-proxy.md) + - [用户管理](/dashboard/dashboard-user.md) + - [安全](/dashboard/dashboard-ops-security.md) + - [访问](/dashboard/dashboard-access.md) + - [概况页面](/dashboard/dashboard-overview.md) + - [集群信息页面](/dashboard/dashboard-cluster-info.md) + - [Top SQL 页面](/dashboard/top-sql.md) + - [流量可视化页面](/dashboard/dashboard-key-visualizer.md) + - [监控关系图](/dashboard/dashboard-metrics-relation.md) + - SQL 语句分析 + - [列表页面](/dashboard/dashboard-statement-list.md) + - [执行详情页面](/dashboard/dashboard-statement-details.md) + - [慢查询页面](/dashboard/dashboard-slow-query.md) + - 集群诊断页面 + - [访问](/dashboard/dashboard-diagnostics-access.md) + - [查看报告](/dashboard/dashboard-diagnostics-report.md) + - [使用示例](/dashboard/dashboard-diagnostics-usage.md) + - [监控指标页面](/dashboard/dashboard-monitoring.md) + - [日志搜索页面](/dashboard/dashboard-log-search.md) + - [资源管控页面](/dashboard/dashboard-resource-manager.md) + - 实例性能分析 + - [手动分析页面](/dashboard/dashboard-profiling.md) + - [持续分析页面](/dashboard/continuous-profiling.md) + - 会话管理与配置 + - [分享会话](/dashboard/dashboard-session-share.md) + - [配置 SSO 登录](/dashboard/dashboard-session-sso.md) + - [常见问题](/dashboard/dashboard-faq.md) - [将 Grafana 监控数据导出成快照](/exporting-grafana-snapshots.md) - [TiDB 集群报警规则与处理方法](/alert-rules.md) - [TiFlash 报警规则与处理方法](/tiflash/tiflash-alert-rules.md) @@ -307,13 +235,13 @@ - [TiFlash 性能分析方法](/tiflash-performance-tuning-methods.md) - [TiCDC 性能分析方法](/ticdc-performance-tuning-methods.md) - [延迟的拆解分析](/latency-breakdown.md) - - [在公有云上部署 TiDB 的最佳实践](/best-practices-on-public-cloud.md) - 配置调优 - [操作系统性能参数调优](/tune-operating-system.md) - [TiDB 内存调优](/configure-memory-usage.md) - [TiKV 线程调优](/tune-tikv-thread-performance.md) - [TiKV 内存调优](/tune-tikv-memory-performance.md) - [TiKV Follower Read](/follower-read.md) + - [TiKV MVCC 内存引擎](/tikv-in-memory-engine.md) - [Region 性能调优](/tune-region-performance.md) - [TiFlash 调优](/tiflash/tune-tiflash-performance.md) - [下推计算结果缓存](/coprocessor-cache.md) @@ -363,6 +291,7 @@ - [执行计划管理](/sql-plan-management.md) - [优化规则及表达式下推的黑名单](/blocklist-control-plan.md) - [Optimizer Fix Controls](/optimizer-fix-controls.md) + - [索引推荐 (Index Advisor)](/index-advisor.md) - 教程 - [单区域多 AZ 部署](/multi-data-centers-in-one-city-deployment.md) - [双区域多 AZ 部署](/three-data-centers-in-two-cities-deployment.md) @@ -374,22 +303,10 @@ - [使用系统变量 `tidb_read_staleness` 读取历史数据](/tidb-read-staleness.md) - [使用系统变量 `tidb_external_ts` 读取历史数据](/tidb-external-ts.md) - [使用系统变量 `tidb_snapshot` 读取历史数据](/read-historical-data.md) - - 最佳实践 - - [TiDB 最佳实践](/best-practices/tidb-best-practices.md) - - [Java 应用开发最佳实践](/best-practices/java-app-best-practices.md) - - [HAProxy 最佳实践](/best-practices/haproxy-best-practices.md) - - [高并发写入场景最佳实践](/best-practices/high-concurrency-best-practices.md) - - [Grafana 监控最佳实践](/best-practices/grafana-monitor-best-practices.md) - - [PD 调度策略最佳实践](/best-practices/pd-scheduling-best-practices.md) - - [海量 Region 集群调优](/best-practices/massive-regions-best-practices.md) - - [三节点混合部署最佳实践](/best-practices/three-nodes-hybrid-deployment.md) - - [在三数据中心下就近读取数据](/best-practices/three-dc-local-read.md) - - [使用 UUID](/best-practices/uuid.md) - - [只读存储节点最佳实践](/best-practices/readonly-nodes.md) - [Placement Rules 使用文档](/configure-placement-rules.md) - [Load Base Split 使用文档](/configure-load-base-split.md) - [Store Limit 使用文档](/configure-store-limit.md) - - [DDL 执行原理及最佳实践](/ddl-introduction.md) + - [数据批量处理](/batch-processing.md) - PD 微服务使用文档 - [PD 微服务概览](/pd-microservices.md) - [使用 TiUP 扩容缩容 PD 微服务节点](/scale-microservices-using-tiup.md) @@ -461,6 +378,7 @@ - [tiup cluster start](/tiup/tiup-component-cluster-start.md) - [tiup cluster stop](/tiup/tiup-component-cluster-stop.md) - [tiup cluster template](/tiup/tiup-component-cluster-template.md) + - [tiup cluster tls](/tiup/tiup-component-cluster-tls.md) - [tiup cluster upgrade](/tiup/tiup-component-cluster-upgrade.md) - TiUP DM 命令 - [TiUP DM 命令概览](/tiup/tiup-component-dm.md) @@ -491,20 +409,21 @@ - TiUP 组件文档 - [tiup-playground 运行本地测试集群](/tiup/tiup-playground.md) - [tiup-cluster 部署运维生产集群](/tiup/tiup-cluster.md) + - [使用 no-sudo 模式部署运维生产集群](/tiup/tiup-cluster-no-sudo-mode.md) - [tiup-mirror 定制离线镜像](/tiup/tiup-mirror.md) - [tiup-bench 进行 TPCC/TPCH 压力测试](/tiup/tiup-bench.md) - [TiDB Operator](/tidb-operator-overview.md) - TiDB Data Migration - [关于 Data Migration](/dm/dm-overview.md) - [架构简介](/dm/dm-arch.md) - - [快速开始](/dm/quick-start-with-dm.md) + - [快速上手](/dm/quick-start-with-dm.md) - [最佳实践](/dm/dm-best-practices.md) - 部署 DM 集群 - [软硬件要求](/dm/dm-hardware-and-software-requirements.md) - [使用 TiUP 联网部署（推荐）](/dm/deploy-a-dm-cluster-using-tiup.md) - [使用 TiUP 离线部署](/dm/deploy-a-dm-cluster-using-tiup-offline.md) - [使用 Binary 部署](/dm/deploy-a-dm-cluster-using-binary.md) - - [在 Kubernetes 环境中部署](https://docs.pingcap.com/zh/tidb-in-kubernetes/dev/deploy-tidb-dm) + - [在 Kubernetes 环境中部署](https://docs.pingcap.com/zh/tidb-in-kubernetes/v1.6/deploy-tidb-dm) - 入门指南 - [创建数据源](/dm/quick-start-create-source.md) - [数据源操作](/dm/dm-manage-source.md) @@ -638,8 +557,6 @@ - [使用 PingCAP Clinic 生成诊断报告](/clinic/clinic-report.md) - [采集 SQL 查询计划信息](/clinic/clinic-collect-sql-query-plan.md) - [数据采集说明](/clinic/clinic-data-instruction-for-tiup.md) - - TiSpark - - [TiSpark 用户指南](/tispark-overview.md) - sync-diff-inspector - [概述](/sync-diff-inspector/sync-diff-inspector-overview.md) - [不同库名或表名的数据校验](/sync-diff-inspector/route-diff.md) @@ -672,7 +589,6 @@ - [TiFlash 简介](/tiflash/tiflash-overview.md) - [构建 TiFlash 副本](/tiflash/create-tiflash-replicas.md) - [使用 TiDB 读取 TiFlash](/tiflash/use-tidb-to-read-tiflash.md) - - [使用 TiSpark 读取 TiFlash](/tiflash/use-tispark-to-read-tiflash.md) - [使用 MPP 模式](/tiflash/use-tiflash-mpp-mode.md) - [TiFlash 存算分离架构与 S3 支持](/tiflash/tiflash-disaggregated-and-s3.md) - [使用 FastScan 功能](/tiflash/use-fastscan.md) @@ -688,6 +604,7 @@ - [TiDB 分布式执行框架介绍](/tidb-distributed-execution-framework.md) - [TiDB 全局排序](/tidb-global-sort.md) - [系统变量](/system-variables.md) + - [系统变量索引](/system-variable-reference.md) - [服务器状态变量](/status-variables.md) - 配置文件参数 - [tidb-server](/tidb-configuration-file.md) @@ -725,6 +642,7 @@ - 属性 - [AUTO_INCREMENT](/auto-increment.md) - [AUTO_RANDOM](/auto-random.md) + - [_tidb_rowid](/tidb-rowid.md) - [SHARD_ROW_ID_BITS](/shard-row-id-bits.md) - [字面值](/literal-values.md) - [Schema 对象名](/schema-object-names.md) @@ -735,6 +653,7 @@ - SQL 语句 - [概览](/sql-statements/sql-statement-overview.md) - [`ADMIN`](/sql-statements/sql-statement-admin.md) + - [`ADMIN ALTER DDL JOBS`](/sql-statements/sql-statement-admin-alter-ddl.md) - [`ADMIN CANCEL DDL`](/sql-statements/sql-statement-admin-cancel-ddl.md) - [`ADMIN CHECKSUM TABLE`](/sql-statements/sql-statement-admin-checksum-table.md) - [`ADMIN CHECK [TABLE|INDEX]`](/sql-statements/sql-statement-admin-check-table-index.md) @@ -767,6 +686,7 @@ - [`BATCH`](/sql-statements/sql-statement-batch.md) - [`BEGIN`](/sql-statements/sql-statement-begin.md) - [`CALIBRATE RESOURCE`](/sql-statements/sql-statement-calibrate-resource.md) + - [`CANCEL DISTRIBUTION JOB`](/sql-statements/sql-statement-cancel-distribution-job.md) - [`CANCEL IMPORT JOB`](/sql-statements/sql-statement-cancel-import-job.md) - [`COMMIT`](/sql-statements/sql-statement-commit.md) - [`CREATE BINDING`](/sql-statements/sql-statement-create-binding.md) @@ -784,6 +704,7 @@ - [`DELETE`](/sql-statements/sql-statement-delete.md) - [`DESC`](/sql-statements/sql-statement-desc.md) - [`DESCRIBE`](/sql-statements/sql-statement-describe.md) + - [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md) - [`DO`](/sql-statements/sql-statement-do.md) - [`DROP BINDING`](/sql-statements/sql-statement-drop-binding.md) - [`DROP DATABASE`](/sql-statements/sql-statement-drop-database.md) @@ -832,6 +753,7 @@ - [`SET ROLE`](/sql-statements/sql-statement-set-role.md) - [`SET TRANSACTION`](/sql-statements/sql-statement-set-transaction.md) - [`SET `](/sql-statements/sql-statement-set-variable.md) + - [`SHOW AFFINITY`](/sql-statements/sql-statement-show-affinity.md) - [`SHOW [BACKUPS|RESTORES]`](/sql-statements/sql-statement-show-backups.md) - [`SHOW ANALYZE STATUS`](/sql-statements/sql-statement-show-analyze-status.md) - [`SHOW BINDINGS`](/sql-statements/sql-statement-show-bindings.md) @@ -848,6 +770,7 @@ - [`SHOW CREATE DATABASE`](/sql-statements/sql-statement-show-create-database.md) - [`SHOW CREATE USER`](/sql-statements/sql-statement-show-create-user.md) - [`SHOW DATABASES`](/sql-statements/sql-statement-show-databases.md) + - [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md) - [`SHOW ENGINES`](/sql-statements/sql-statement-show-engines.md) - [`SHOW ERRORS`](/sql-statements/sql-statement-show-errors.md) - [`SHOW FIELDS FROM`](/sql-statements/sql-statement-show-fields-from.md) @@ -870,6 +793,7 @@ - [`SHOW STATS_META`](/sql-statements/sql-statement-show-stats-meta.md) - [`SHOW STATS_TOPN`](/sql-statements/sql-statement-show-stats-topn.md) - [`SHOW STATUS`](/sql-statements/sql-statement-show-status.md) + - [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.md) - [`SHOW TABLE NEXT_ROW_ID`](/sql-statements/sql-statement-show-table-next-rowid.md) - [`SHOW TABLE REGIONS`](/sql-statements/sql-statement-show-table-regions.md) - [`SHOW TABLE STATUS`](/sql-statements/sql-statement-show-table-status.md) @@ -893,7 +817,7 @@ - [日期和时间类型](/data-type-date-and-time.md) - [字符串类型](/data-type-string.md) - [JSON 类型](/data-type-json.md) - - [向量数据类型](/vector-search-data-types.md) + - [向量数据类型](/ai/reference/vector-search-data-types.md) - 函数与操作符 - [函数与操作符概述](/functions-and-operators/functions-and-operators-overview.md) - [表达式求值的类型转换](/functions-and-operators/type-conversion-in-expression-evaluation.md) @@ -907,7 +831,7 @@ - [加密和压缩函数](/functions-and-operators/encryption-and-compression-functions.md) - [锁函数](/functions-and-operators/locking-functions.md) - [信息函数](/functions-and-operators/information-functions.md) - - [向量函数和操作符](/vector-search-functions-and-operators.md) + - [向量函数和操作符](/ai/reference/vector-search-functions-and-operators.md) - JSON 函数 - [概览](/functions-and-operators/json-functions.md) - [创建 JSON 的函数](/functions-and-operators/json-functions/json-functions-create.md) @@ -920,15 +844,17 @@ - [GROUP BY 聚合函数](/functions-and-operators/aggregate-group-by-functions.md) - [GROUP BY 修饰符](/functions-and-operators/group-by-modifier.md) - [窗口函数](/functions-and-operators/window-functions.md) + - [序列函数](/functions-and-operators/sequence-functions.md) + - [效用函数](/functions-and-operators/utility-functions.md) - [其它函数](/functions-and-operators/miscellaneous-functions.md) + - [TiDB 特有的函数](/functions-and-operators/tidb-functions.md) - [精度数学](/functions-and-operators/precision-math.md) - [集合运算](/functions-and-operators/set-operators.md) - - [序列函数](/functions-and-operators/sequence-functions.md) - - [下推到 TiKV 的表达式列表](/functions-and-operators/expressions-pushed-down.md) - - [TiDB 特有的函数](/functions-and-operators/tidb-functions.md) + - [下推到 TiKV 的表达式列表](/functions-and-operators/expressions-pushed-down.md) - [Oracle 与 TiDB 函数和语法差异对照](/oracle-functions-to-tidb.md) - [聚簇索引](/clustered-indexes.md) - - [向量索引](/vector-search-index.md) + - [全局索引](/global-indexes.md) + - [向量索引](/ai/reference/vector-search-index.md) - [约束](/constraints.md) - [生成列](/generated-columns.md) - [SQL 模式](/sql-mode.md) @@ -939,18 +865,22 @@ - [乐观事务](/optimistic-transaction.md) - [悲观事务](/pessimistic-transaction.md) - [非事务 DML 语句](/non-transactional-dml.md) + - [Pipelined DML](/pipelined-dml.md) - [视图](/views.md) - [分区表](/partitioned-table.md) - [临时表](/temporary-tables.md) - [缓存表](/cached-tables.md) - [外键约束](/foreign-key.md) + - [表级数据亲和性](/table-affinity.md) - 字符集和排序规则 - [概述](/character-set-and-collation.md) - [GBK](/character-set-gbk.md) + - [TTL (Time to Live)](/time-to-live.md) - [Placement Rules in SQL](/placement-rules-in-sql.md) - 系统表 - `mysql` Schema - [概述](/mysql-schema/mysql-schema.md) + - [`tidb_mdl_view`](/mysql-schema/mysql-schema-tidb-mdl-view.md) - [`user`](/mysql-schema/mysql-schema-user.md) - INFORMATION_SCHEMA - [概述](/information-schema/information-schema.md) @@ -1003,6 +933,7 @@ - [`TIDB_INDEX_USAGE`](/information-schema/information-schema-tidb-index-usage.md) - [`TIDB_SERVERS_INFO`](/information-schema/information-schema-tidb-servers-info.md) - [`TIDB_TRX`](/information-schema/information-schema-tidb-trx.md) + - [`TIFLASH_INDEXES`](/information-schema/information-schema-tiflash-indexes.md) - [`TIFLASH_REPLICA`](/information-schema/information-schema-tiflash-replica.md) - [`TIFLASH_SEGMENTS`](/information-schema/information-schema-tiflash-segments.md) - [`TIFLASH_TABLES`](/information-schema/information-schema-tiflash-tables.md) @@ -1023,42 +954,14 @@ - [元数据锁](/metadata-lock.md) - [TiDB 加速建表](/accelerated-table-creation.md) - [Schema 缓存](/schema-cache.md) - - UI - - TiDB Dashboard - - [简介](/dashboard/dashboard-intro.md) - - 运维 - - [部署](/dashboard/dashboard-ops-deploy.md) - - [反向代理](/dashboard/dashboard-ops-reverse-proxy.md) - - [用户管理](/dashboard/dashboard-user.md) - - [安全](/dashboard/dashboard-ops-security.md) - - [访问](/dashboard/dashboard-access.md) - - [概况页面](/dashboard/dashboard-overview.md) - - [集群信息页面](/dashboard/dashboard-cluster-info.md) - - [Top SQL 页面](/dashboard/top-sql.md) - - [流量可视化页面](/dashboard/dashboard-key-visualizer.md) - - [监控关系图](/dashboard/dashboard-metrics-relation.md) - - SQL 语句分析 - - [列表页面](/dashboard/dashboard-statement-list.md) - - [执行详情页面](/dashboard/dashboard-statement-details.md) - - [慢查询页面](/dashboard/dashboard-slow-query.md) - - 集群诊断页面 - - [访问](/dashboard/dashboard-diagnostics-access.md) - - [查看报告](/dashboard/dashboard-diagnostics-report.md) - - [使用示例](/dashboard/dashboard-diagnostics-usage.md) - - [监控指标页面](/dashboard/dashboard-monitoring.md) - - [日志搜索页面](/dashboard/dashboard-log-search.md) - - [资源管控页面](/dashboard/dashboard-resource-manager.md) - - 实例性能分析 - - [手动分析页面](/dashboard/dashboard-profiling.md) - - [持续分析页面](/dashboard/continuous-profiling.md) - - 会话管理与配置 - - [分享会话](/dashboard/dashboard-session-share.md) - - [配置 SSO 登录](/dashboard/dashboard-session-sso.md) - - [常见问题](/dashboard/dashboard-faq.md) - [遥测](/telemetry.md) - [错误码](/error-codes.md) + - [表库过滤](/table-filter.md) + - [TiDB 离线包](/binary-package.md) - [通过拓扑 label 进行副本调度](/schedule-replicas-by-topology-labels.md) - [外部存储服务的 URI 格式](/external-storage-uri.md) + - [线上负载与 `ADD INDEX` 相互影响测试](/benchmark/online-workloads-and-add-index-operations.md) + - [内嵌于 DDL 的 Analyze](/ddl_embedded_analyze.md) - 常见问题解答 (FAQ) - [FAQ 汇总](/faq/faq-overview.md) - [产品 FAQ](/faq/tidb-faq.md) @@ -1071,221 +974,4 @@ - [高可用 FAQ](/faq/high-availability-faq.md) - [高可靠 FAQ](/faq/high-reliability-faq.md) - [备份恢复 FAQ](/faq/backup-and-restore-faq.md) -- 版本发布历史 - - [发布版本汇总](/releases/release-notes.md) - - [版本发布时间线](/releases/release-timeline.md) - - [TiDB 版本规则](/releases/versioning.md) - - [TiDB 离线包](/binary-package.md) - - v8.4 - - [8.4.0-DMR](/releases/release-8.4.0.md) - - v8.3 - - [8.3.0-DMR](/releases/release-8.3.0.md) - - v8.2 - - [8.2.0-DMR](/releases/release-8.2.0.md) - - v8.1 - - [8.1.1](/releases/release-8.1.1.md) - - [8.1.0](/releases/release-8.1.0.md) - - v8.0 - - [8.0.0-DMR](/releases/release-8.0.0.md) - - v7.6 - - [7.6.0-DMR](/releases/release-7.6.0.md) - - v7.5 - - [7.5.4](/releases/release-7.5.4.md) - - [7.5.3](/releases/release-7.5.3.md) - - [7.5.2](/releases/release-7.5.2.md) - - [7.5.1](/releases/release-7.5.1.md) - - [7.5.0](/releases/release-7.5.0.md) - - v7.4 - - [7.4.0-DMR](/releases/release-7.4.0.md) - - v7.3 - - [7.3.0-DMR](/releases/release-7.3.0.md) - - v7.2 - - [7.2.0-DMR](/releases/release-7.2.0.md) - - v7.1 - - [7.1.6](/releases/release-7.1.6.md) - - [7.1.5](/releases/release-7.1.5.md) - - [7.1.4](/releases/release-7.1.4.md) - - [7.1.3](/releases/release-7.1.3.md) - - [7.1.2](/releases/release-7.1.2.md) - - [7.1.1](/releases/release-7.1.1.md) - - [7.1.0](/releases/release-7.1.0.md) - - v7.0 - - [7.0.0-DMR](/releases/release-7.0.0.md) - - v6.6 - - [6.6.0-DMR](/releases/release-6.6.0.md) - - v6.5 - - [6.5.11](/releases/release-6.5.11.md) - - [6.5.10](/releases/release-6.5.10.md) - - [6.5.9](/releases/release-6.5.9.md) - - [6.5.8](/releases/release-6.5.8.md) - - [6.5.7](/releases/release-6.5.7.md) - - [6.5.6](/releases/release-6.5.6.md) - - [6.5.5](/releases/release-6.5.5.md) - - [6.5.4](/releases/release-6.5.4.md) - - [6.5.3](/releases/release-6.5.3.md) - - [6.5.2](/releases/release-6.5.2.md) - - [6.5.1](/releases/release-6.5.1.md) - - [6.5.0](/releases/release-6.5.0.md) - - v6.4 - - [6.4.0-DMR](/releases/release-6.4.0.md) - - v6.3 - - [6.3.0-DMR](/releases/release-6.3.0.md) - - v6.2 - - [6.2.0-DMR](/releases/release-6.2.0.md) - - v6.1 - - [6.1.7](/releases/release-6.1.7.md) - - [6.1.6](/releases/release-6.1.6.md) - - [6.1.5](/releases/release-6.1.5.md) - - [6.1.4](/releases/release-6.1.4.md) - - [6.1.3](/releases/release-6.1.3.md) - - [6.1.2](/releases/release-6.1.2.md) - - [6.1.1](/releases/release-6.1.1.md) - - [6.1.0](/releases/release-6.1.0.md) - - v6.0 - - [6.0.0-DMR](/releases/release-6.0.0-dmr.md) - - v5.4 - - [5.4.3](/releases/release-5.4.3.md) - - [5.4.2](/releases/release-5.4.2.md) - - [5.4.1](/releases/release-5.4.1.md) - - [5.4.0](/releases/release-5.4.0.md) - - v5.3 - - [5.3.4](/releases/release-5.3.4.md) - - [5.3.3](/releases/release-5.3.3.md) - - [5.3.2](/releases/release-5.3.2.md) - - [5.3.1](/releases/release-5.3.1.md) - - [5.3.0](/releases/release-5.3.0.md) - - v5.2 - - [5.2.4](/releases/release-5.2.4.md) - - [5.2.3](/releases/release-5.2.3.md) - - [5.2.2](/releases/release-5.2.2.md) - - [5.2.1](/releases/release-5.2.1.md) - - [5.2.0](/releases/release-5.2.0.md) - - v5.1 - - [5.1.5](/releases/release-5.1.5.md) - - [5.1.4](/releases/release-5.1.4.md) - - [5.1.3](/releases/release-5.1.3.md) - - [5.1.2](/releases/release-5.1.2.md) - - [5.1.1](/releases/release-5.1.1.md) - - [5.1.0](/releases/release-5.1.0.md) - - v5.0 - - [5.0.6](/releases/release-5.0.6.md) - - [5.0.5](/releases/release-5.0.5.md) - - [5.0.4](/releases/release-5.0.4.md) - - [5.0.3](/releases/release-5.0.3.md) - - [5.0.2](/releases/release-5.0.2.md) - - [5.0.1](/releases/release-5.0.1.md) - - [5.0 GA](/releases/release-5.0.0.md) - - [5.0.0-rc](/releases/release-5.0.0-rc.md) - - v4.0 - - [4.0.16](/releases/release-4.0.16.md) - - [4.0.15](/releases/release-4.0.15.md) - - [4.0.14](/releases/release-4.0.14.md) - - [4.0.13](/releases/release-4.0.13.md) - - [4.0.12](/releases/release-4.0.12.md) - - [4.0.11](/releases/release-4.0.11.md) - - [4.0.10](/releases/release-4.0.10.md) - - [4.0.9](/releases/release-4.0.9.md) - - [4.0.8](/releases/release-4.0.8.md) - - [4.0.7](/releases/release-4.0.7.md) - - [4.0.6](/releases/release-4.0.6.md) - - [4.0.5](/releases/release-4.0.5.md) - - [4.0.4](/releases/release-4.0.4.md) - - [4.0.3](/releases/release-4.0.3.md) - - [4.0.2](/releases/release-4.0.2.md) - - [4.0.1](/releases/release-4.0.1.md) - - [4.0 GA](/releases/release-4.0-ga.md) - - [4.0.0-rc.2](/releases/release-4.0.0-rc.2.md) - - [4.0.0-rc.1](/releases/release-4.0.0-rc.1.md) - - [4.0.0-rc](/releases/release-4.0.0-rc.md) - - [4.0.0-beta.2](/releases/release-4.0.0-beta.2.md) - - [4.0.0-beta.1](/releases/release-4.0.0-beta.1.md) - - [4.0.0-beta](/releases/release-4.0.0-beta.md) - - v3.1 - - [3.1.2](/releases/release-3.1.2.md) - - [3.1.1](/releases/release-3.1.1.md) - - [3.1.0 GA](/releases/release-3.1.0-ga.md) - - [3.1.0-rc](/releases/release-3.1.0-rc.md) - - [3.1.0-beta.2](/releases/release-3.1.0-beta.2.md) - - [3.1.0-beta.1](/releases/release-3.1.0-beta.1.md) - - [3.1.0-beta](/releases/release-3.1.0-beta.md) - - v3.0 - - [3.0.20](/releases/release-3.0.20.md) - - [3.0.19](/releases/release-3.0.19.md) - - [3.0.18](/releases/release-3.0.18.md) - - [3.0.17](/releases/release-3.0.17.md) - - [3.0.16](/releases/release-3.0.16.md) - - [3.0.15](/releases/release-3.0.15.md) - - [3.0.14](/releases/release-3.0.14.md) - - [3.0.13](/releases/release-3.0.13.md) - - [3.0.12](/releases/release-3.0.12.md) - - [3.0.11](/releases/release-3.0.11.md) - - [3.0.10](/releases/release-3.0.10.md) - - [3.0.9](/releases/release-3.0.9.md) - - [3.0.8](/releases/release-3.0.8.md) - - [3.0.7](/releases/release-3.0.7.md) - - [3.0.6](/releases/release-3.0.6.md) - - [3.0.5](/releases/release-3.0.5.md) - - [3.0.4](/releases/release-3.0.4.md) - - [3.0.3](/releases/release-3.0.3.md) - - [3.0.2](/releases/release-3.0.2.md) - - [3.0.1](/releases/release-3.0.1.md) - - [3.0 GA](/releases/release-3.0-ga.md) - - [3.0.0-rc.3](/releases/release-3.0.0-rc.3.md) - - [3.0.0-rc.2](/releases/release-3.0.0-rc.2.md) - - [3.0.0-rc.1](/releases/release-3.0.0-rc.1.md) - - [3.0.0-beta.1](/releases/release-3.0.0-beta.1.md) - - [3.0.0-beta](/releases/release-3.0-beta.md) - - v2.1 - - [2.1.19](/releases/release-2.1.19.md) - - [2.1.18](/releases/release-2.1.18.md) - - [2.1.17](/releases/release-2.1.17.md) - - [2.1.16](/releases/release-2.1.16.md) - - [2.1.15](/releases/release-2.1.15.md) - - [2.1.14](/releases/release-2.1.14.md) - - [2.1.13](/releases/release-2.1.13.md) - - [2.1.12](/releases/release-2.1.12.md) - - [2.1.11](/releases/release-2.1.11.md) - - [2.1.10](/releases/release-2.1.10.md) - - [2.1.9](/releases/release-2.1.9.md) - - [2.1.8](/releases/release-2.1.8.md) - - [2.1.7](/releases/release-2.1.7.md) - - [2.1.6](/releases/release-2.1.6.md) - - [2.1.5](/releases/release-2.1.5.md) - - [2.1.4](/releases/release-2.1.4.md) - - [2.1.3](/releases/release-2.1.3.md) - - [2.1.2](/releases/release-2.1.2.md) - - [2.1.1](/releases/release-2.1.1.md) - - [2.1 GA](/releases/release-2.1-ga.md) - - [2.1 RC5](/releases/release-2.1-rc.5.md) - - [2.1 RC4](/releases/release-2.1-rc.4.md) - - [2.1 RC3](/releases/release-2.1-rc.3.md) - - [2.1 RC2](/releases/release-2.1-rc.2.md) - - [2.1 RC1](/releases/release-2.1-rc.1.md) - - [2.1 Beta](/releases/release-2.1-beta.md) - - v2.0 - - [2.0.11](/releases/release-2.0.11.md) - - [2.0.10](/releases/release-2.0.10.md) - - [2.0.9](/releases/release-2.0.9.md) - - [2.0.8](/releases/release-2.0.8.md) - - [2.0.7](/releases/release-2.0.7.md) - - [2.0.6](/releases/release-2.0.6.md) - - [2.0.5](/releases/release-2.0.5.md) - - [2.0.4](/releases/release-2.0.4.md) - - [2.0.3](/releases/release-2.0.3.md) - - [2.0.2](/releases/release-2.0.2.md) - - [2.0.1](/releases/release-2.0.1.md) - - [2.0](/releases/release-2.0-ga.md) - - [2.0 RC5](/releases/release-2.0-rc.5.md) - - [2.0 RC4](/releases/release-2.0-rc.4.md) - - [2.0 RC3](/releases/release-2.0-rc.3.md) - - [2.0 RC1](/releases/release-2.0-rc.1.md) - - [1.1 Beta](/releases/release-1.1-beta.md) - - [1.1 Alpha](/releases/release-1.1-alpha.md) - - v1.0 - - [1.0](/releases/release-1.0-ga.md) - - [Pre-GA](/releases/release-pre-ga.md) - - [RC4](/releases/release-rc.4.md) - - [RC3](/releases/release-rc.3.md) - - [RC2](/releases/release-rc.2.md) - - [RC1](/releases/release-rc.1.md) - [术语表](/glossary.md) diff --git a/_docHome.md b/_docHome.md index a6b53f12b2ec..09670473006f 100644 --- a/_docHome.md +++ b/_docHome.md @@ -10,7 +10,7 @@ summary: TiDB 文档中心为您提供丰富的操作指南和参考资料，助 -TiDB 是 PingCAP 公司自主设计、研发的开源分布式关系型数据库，是一款同时支持在线事务处理与在线分析处理 (Hybrid Transactional and Analytical Processing, HTAP) 的融合型分布式数据库产品，具备水平扩容或者缩容、金融级高可用、实时 HTAP、云原生的分布式数据库、兼容 MySQL 协议和 MySQL 生态等重要特性，支持在本地和云上部署。 +TiDB 是平凯星辰公司自主设计、研发的开源分布式关系型数据库，是一款同时支持在线事务处理与在线分析处理 (Hybrid Transactional and Analytical Processing, HTAP) 的融合型分布式数据库产品，具备水平扩容或者缩容、金融级高可用、实时 HTAP、云原生的分布式数据库、兼容 MySQL 协议和 MySQL 生态等重要特性，支持在本地和云上部署。 @@ -32,9 +32,9 @@ TiDB 简介，核心特性与应用场景 - + -为应用程序开发者编写的开发者手册 +用熟悉的语言或框架连接到 TiDB @@ -44,12 +44,6 @@ TiDB 高度兼容 MySQL 协议，以及 MySQL 5.7 和 MySQL 8.0 常用的功能 - - -提前了解 TiDB 的未来规划，关注开发进展，了解关键里程碑，并对开发工作提出反馈 - - - @@ -66,15 +60,15 @@ TiDB Cloud 核心特性与应用场景简介 - + 快速了解和使用 TiDB Cloud - + -使用你熟悉的语言或框架连接到 TiDB Cloud Serverless +使用你熟悉的语言或框架连接到 {{{ .starter }}} @@ -90,7 +84,7 @@ TiDB Cloud 核心特性与应用场景简介 - + 提供众多免费课程，助您深入学习 TiDB，成为 TiDB 技术专家 @@ -102,7 +96,7 @@ TiDB Cloud 核心特性与应用场景简介 - + 满满的技术干货、深度解读、技术分享 diff --git a/_index.md b/_index.md index 7995570d1084..4711fd995681 100644 --- a/_index.md +++ b/_index.md @@ -1,48 +1,47 @@ --- title: TiDB 产品文档 -aliases: ['/docs-cn/dev/','/docs-cn/','/docs-cn/stable/'] hide_sidebar: true hide_commit: true -summary: TiDB 是 PingCAP 公司自主设计、研发的开源分布式关系型数据库。产品文档包括了 TiDB 简介、功能概览、TiFlash、快速上手 TiDB、HTAP、开发者手册概览、软硬件环境需求、使用 TiUP 部署 TiDB、数据迁移概览、运维、监控、调优、工具、TiDB 路线图、配置文件参数、命令行参数、TiDB Control、系统变量、发布历史、常见问题。 +summary: TiDB 是平凯星辰公司自主设计、研发的开源分布式关系型数据库。产品文档包括了 TiDB 简介、功能概览、TiFlash、快速上手 TiDB、HTAP、开发者手册概览、软硬件环境需求、使用 TiUP 部署 TiDB、数据迁移概览、运维、监控、调优、工具、TiDB 路线图、配置文件参数、命令行参数、TiDB Control、系统变量、发布历史、常见问题。 --- - + -[TiDB 简介](https://docs.pingcap.com/zh/tidb/dev/overview) +[TiDB 简介](https://docs.pingcap.com/zh/tidb/v8.5/overview) -[功能概览](https://docs.pingcap.com/zh/tidb/dev/basic-features) +[功能概览](https://docs.pingcap.com/zh/tidb/v8.5/basic-features) -[TiFlash](https://docs.pingcap.com/zh/tidb/dev/tiflash-overview) +[TiFlash](https://docs.pingcap.com/zh/tidb/v8.5/tiflash-overview) -[快速上手 TiDB](https://docs.pingcap.com/zh/tidb/dev/quick-start-with-tidb) +[快速上手 TiDB](https://docs.pingcap.com/zh/tidb/v8.5/quick-start-with-tidb) -[快速上手 HTAP](https://docs.pingcap.com/zh/tidb/dev/quick-start-with-htap) +[快速上手 HTAP](https://docs.pingcap.com/zh/tidb/v8.5/quick-start-with-htap) -[深入探索 HTAP](https://docs.pingcap.com/zh/tidb/dev/explore-htap) +[深入探索 HTAP](https://docs.pingcap.com/zh/tidb/v8.5/explore-htap) -[开发者手册概览](https://docs.pingcap.com/zh/tidb/dev/dev-guide-overview) +[开发者手册概览](https://docs.pingcap.com/zh/tidb/v8.5/dev-guide-overview) -[快速开始](https://docs.pingcap.com/zh/tidb/dev/dev-guide-build-cluster-in-cloud) +[快速开始](https://docs.pingcap.com/zh/tidb/v8.5/dev-guide-build-cluster-in-cloud) -[示例程序](https://docs.pingcap.com/zh/tidb/dev/dev-guide-sample-application-spring-boot) +[示例程序](https://docs.pingcap.com/zh/tidb/v8.5/dev-guide-sample-application-spring-boot) -[软硬件环境需求](https://docs.pingcap.com/zh/tidb/dev/hardware-and-software-requirements) +[软硬件环境需求](https://docs.pingcap.com/zh/tidb/v8.5/hardware-and-software-requirements) -[使用 TiUP 部署 TiDB（推荐）](https://docs.pingcap.com/zh/tidb/dev/production-deployment-using-tiup) +[使用 TiUP 部署 TiDB（推荐）](https://docs.pingcap.com/zh/tidb/v8.5/production-deployment-using-tiup) [在 Kubernetes 上部署 TiDB](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable) @@ -50,89 +49,87 @@ summary: TiDB 是 PingCAP 公司自主设计、研发的开源分布式关系型 -[数据迁移概览](https://docs.pingcap.com/zh/tidb/dev/migration-overview) +[数据迁移概览](https://docs.pingcap.com/zh/tidb/v8.5/migration-overview) -[迁移工具](https://docs.pingcap.com/zh/tidb/dev/migration-tools) +[迁移工具](https://docs.pingcap.com/zh/tidb/v8.5/migration-tools) -[应用场景](https://docs.pingcap.com/zh/tidb/dev/migrate-aurora-to-tidb) +[应用场景](https://docs.pingcap.com/zh/tidb/v8.5/migrate-aurora-to-tidb) -[升级集群](https://docs.pingcap.com/zh/tidb/dev/upgrade-tidb-using-tiup) +[升级集群](https://docs.pingcap.com/zh/tidb/v8.5/upgrade-tidb-using-tiup) -[扩容集群](https://docs.pingcap.com/zh/tidb/dev/scale-tidb-using-tiup) +[扩容集群](https://docs.pingcap.com/zh/tidb/v8.5/scale-tidb-using-tiup) -[备份与恢复](https://docs.pingcap.com/zh/tidb/dev/backup-and-restore-overview) +[备份与恢复](https://docs.pingcap.com/zh/tidb/v8.5/backup-and-restore-overview) -[日常巡检](https://docs.pingcap.com/zh/tidb/dev/daily-check) +[日常巡检](https://docs.pingcap.com/zh/tidb/v8.5/daily-check) -[使用 TiUP 运维](https://docs.pingcap.com/zh/tidb/dev/maintain-tidb-using-tiup) +[使用 TiUP 运维](https://docs.pingcap.com/zh/tidb/v8.5/maintain-tidb-using-tiup) -[使用 Prometheus 和 Grafana](https://docs.pingcap.com/zh/tidb/dev/tidb-monitoring-framework) +[使用 Prometheus、Grafana 和 TiDB Dashboard](https://docs.pingcap.com/zh/tidb/v8.5/tidb-monitoring-framework) -[监控 API](https://docs.pingcap.com/zh/tidb/dev/tidb-monitoring-api) +[监控 API](https://docs.pingcap.com/zh/tidb/v8.5/tidb-monitoring-api) -[报警规则](https://docs.pingcap.com/zh/tidb/dev/alert-rules) +[报警规则](https://docs.pingcap.com/zh/tidb/v8.5/alert-rules) -[调优概述](https://docs.pingcap.com/zh/tidb/dev/performance-tuning-overview) +[调优概述](https://docs.pingcap.com/zh/tidb/v8.5/performance-tuning-overview) -[调优方法](https://docs.pingcap.com/zh/tidb/dev/performance-tuning-methods) +[调优方法](https://docs.pingcap.com/zh/tidb/v8.5/performance-tuning-methods) -[调优实践](https://docs.pingcap.com/zh/tidb/dev/performance-tuning-practices) +[调优实践](https://docs.pingcap.com/zh/tidb/v8.5/performance-tuning-practices) -[操作系统性能参数调优](https://docs.pingcap.com/zh/tidb/dev/tune-operating-system) +[操作系统性能参数调优](https://docs.pingcap.com/zh/tidb/v8.5/tune-operating-system) -[内存调优](https://docs.pingcap.com/zh/tidb/dev/configure-memory-usage) +[内存调优](https://docs.pingcap.com/zh/tidb/v8.5/configure-memory-usage) -[SQL 调优](https://docs.pingcap.com/zh/tidb/dev/sql-tuning-overview) +[SQL 调优](https://docs.pingcap.com/zh/tidb/v8.5/sql-tuning-overview) -[TiUP](https://docs.pingcap.com/zh/tidb/dev/tiup-overview) +[TiUP](https://docs.pingcap.com/zh/tidb/v8.5/tiup-overview) -[TiDB Operator](https://docs.pingcap.com/zh/tidb/dev/tidb-operator-overview) +[TiDB Operator](https://docs.pingcap.com/zh/tidb/v8.5/tidb-operator-overview) -[TiDB Data Migration (DM)](https://docs.pingcap.com/zh/tidb/dev/dm-overview) +[TiDB Data Migration (DM)](https://docs.pingcap.com/zh/tidb/v8.5/dm-overview) -[TiDB Lightning](https://docs.pingcap.com/zh/tidb/dev/tidb-lightning-overview) +[TiDB Lightning](https://docs.pingcap.com/zh/tidb/v8.5/tidb-lightning-overview) -[Dumpling](https://docs.pingcap.com/zh/tidb/dev/dumpling-overview) +[Dumpling](https://docs.pingcap.com/zh/tidb/v8.5/dumpling-overview) -[TiCDC](https://docs.pingcap.com/zh/tidb/dev/ticdc-overview) +[TiCDC](https://docs.pingcap.com/zh/tidb/v8.5/ticdc-overview) -[Backup & Restore (BR)](https://docs.pingcap.com/zh/tidb/dev/backup-and-restore-overview) +[Backup & Restore (BR)](https://docs.pingcap.com/zh/tidb/v8.5/backup-and-restore-overview) -[PingCAP Clinic](https://docs.pingcap.com/zh/tidb/dev/clinic-introduction) +[PingCAP Clinic](https://docs.pingcap.com/zh/tidb/v8.5/clinic-introduction) -[TiDB 路线图](https://docs.pingcap.com/zh/tidb/dev/tidb-roadmap) +[TiDB 配置文件参数](https://docs.pingcap.com/zh/tidb/v8.5/tidb-configuration-file) -[TiDB 配置文件参数](https://docs.pingcap.com/zh/tidb/dev/tidb-configuration-file) +[TiDB 命令行参数](https://docs.pingcap.com/zh/tidb/v8.5/command-line-flags-for-tidb-configuration) -[TiDB 命令行参数](https://docs.pingcap.com/zh/tidb/dev/command-line-flags-for-tidb-configuration) +[TiDB Control](https://docs.pingcap.com/zh/tidb/v8.5/tidb-control) -[TiDB Control](https://docs.pingcap.com/zh/tidb/dev/tidb-control) +[系统变量](https://docs.pingcap.com/zh/tidb/v8.5/system-variables) -[系统变量](https://docs.pingcap.com/zh/tidb/dev/system-variables) +[发布历史](https://docs.pingcap.com/zh/tidb/v8.5/release-notes) -[发布历史](https://docs.pingcap.com/zh/tidb/dev/release-notes) - -[常见问题](https://docs.pingcap.com/zh/tidb/dev/faq-overview) +[常见问题](https://docs.pingcap.com/zh/tidb/v8.5/faq-overview) diff --git a/accelerated-table-creation.md b/accelerated-table-creation.md index 72148de25ac0..8dc306dcff4c 100644 --- a/accelerated-table-creation.md +++ b/accelerated-table-creation.md @@ -1,7 +1,6 @@ --- title: 提升 TiDB 建表性能 summary: 介绍 TiDB 加速建表中的概念、原理、实现和影响。 -aliases: ['/zh/tidb/dev/ddl-v2/'] --- # 提升 TiDB 建表性能 diff --git a/agg-distinct-optimization.md b/agg-distinct-optimization.md index 9117474982ad..6b3068e31191 100644 --- a/agg-distinct-optimization.md +++ b/agg-distinct-optimization.md @@ -1,6 +1,5 @@ --- title: Distinct 优化 -aliases: ['/docs-cn/dev/agg-distinct-optimization/'] summary: 本文介绍了对于 DISTINCT 的优化，包括简单 DISTINCT 和聚合函数 DISTINCT 的优化。简单的 DISTINCT 通常会被优化成 GROUP BY 来执行。而带有 DISTINCT 的聚合函数会在 TiDB 侧单线程执行，可以通过系统变量或 TiDB 配置项控制优化器是否执行。在优化后，DISTINCT 被下推到了 Coprocessor，在 HashAgg 里新增了一个 group by 列。 --- diff --git a/ai/_index.md b/ai/_index.md new file mode 100644 index 000000000000..4a23349cb212 --- /dev/null +++ b/ai/_index.md @@ -0,0 +1,77 @@ +--- +title: TiDB for AI +summary: 利用 TiDB 的向量搜索、全文搜索和 Python SDK 构建现代 AI 应用。 +--- + +# TiDB for AI + +TiDB 是面向 AI 应用的分布式 SQL 数据库，支持向量搜索、全文搜索及混合搜索功能。本文介绍利用 TiDB 开发 AI 应用时可用的 AI 功能与工具。 + +## 快速开始 + +快速体验 TiDB 的 AI 能力。 + +| 文档 | 描述 | +| --- | --- | +| [使用 Python 快速上手](/ai/quickstart-via-python.md) | 使用 Python 在几分钟内构建你的第一个基于 TiDB 的 AI 应用。 | +| [使用 SQL 快速上手](/ai/quickstart-via-sql.md) | 使用 SQL 快速开始向量搜索。 | + +## 基础概念 + +了解 TiDB AI 搜索的基础概念。 + +| 文档 | 描述 | +| --- | --- | +| [向量搜索](/ai/concepts/vector-search-overview.md) | 向量搜索的全面概述，包括概念、工作原理和应用场景。 | + +## 使用指南 + +使用 TiDB Python SDK [`pytidb`](https://github.com/pingcap/pytidb) 或 SQL 构建 AI 应用的分步指南。 + +| 文档 | 描述 | +| --- | --- | +| [连接 TiDB](/ai/guides/connect.md) | 使用 `pytidb` 连接 TiDB Cloud 或自建集群。 | +| [使用表](/ai/guides/tables.md) | 创建、查询和管理包含向量字段的表。 | +| [向量搜索](/ai/guides/vector-search.md) | 使用 `pytidb` 进行语义相似度搜索。 | +| [全文搜索](/ai/guides/vector-search-full-text-search-python.md) | 基于关键字的文本搜索，支持 BM25 排序。 | +| [混合搜索](/ai/guides/vector-search-hybrid-search.md) | 结合向量搜索与全文搜索，获得更优结果。 | +| [图片搜索](/ai/guides/image-search.md) | 利用多模态嵌入进行 image 搜索。 | +| [Auto Embedding（自动生成向量）](/ai/guides/auto-embedding.md) | 数据插入时自动生成嵌入向量。 | +| [过滤](/ai/guides/filtering.md) | 通过元信息条件过滤搜索结果。 | + +## 代码示例 + +完整代码示例和演示，展示 TiDB 的 AI 能力。 + +| 文档 | 描述 | +| --- | --- | +| [基本 CRUD 操作](/ai/examples/basic-with-pytidb.md) | 使用 `pytidb` 进行基础表操作。 | +| [向量搜索](/ai/examples/vector-search-with-pytidb.md) | 语义相似度搜索示例。 | +| [RAG 应用](/ai/examples/rag-with-pytidb.md) | 构建检索增强生成（RAG）应用。 | +| [图片搜索](/ai/examples/image-search-with-pytidb.md) | 基于 Jina AI 嵌入的多模态 image 搜索。 | +| [对话记忆](/ai/examples/memory-with-pytidb.md) | 为 AI agent 和聊天机器人提供持久 memory。 | +| [文本转 SQL](/ai/examples/text2sql-with-pytidb.md) | 将自然语言转换为 SQL 查询。 | + +## 集成指南 + +将 TiDB 集成到主流 AI framework、嵌入提供商和开发工具中。 + +| 文档 | 描述 | +| --- | --- | +| [集成概览](/ai/integrations/vector-search-integration-overview.md) | 所有可用集成的概览。 | +| [Embedding Providers](/ai/integrations/vector-search-auto-embedding-overview.md#available-text-embedding-models) | 为 OpenAI、Cohere、Jina AI 等提供统一接口。 | +| [LangChain](/ai/integrations/vector-search-integrate-with-langchain.md) | 将 TiDB 作为 LangChain 的向量存储。 | +| [LlamaIndex](/ai/integrations/vector-search-integrate-with-llamaindex.md) | 将 TiDB 作为 LlamaIndex 的向量存储。 | +| [MCP Server](/ai/integrations/tidb-mcp-server.md) | 将 TiDB 连接到 Claude Code、Cursor 及其他 AI 驱动的 IDE。 | + +## 参考指南 + +TiDB AI 与向量搜索特性的技术参考文档。 + +| 文档 | 描述 | +| --- | --- | +| [向量数据类型](/ai/reference/vector-search-data-types.md) | 向量列类型及其用法。 | +| [函数和运算符](/ai/reference/vector-search-functions-and-operators.md) | 距离函数与向量运算符。 | +| [向量搜索索引](/ai/reference/vector-search-index.md) | 创建和管理向量索引以提升性能。 | +| [性能调优](/ai/reference/vector-search-improve-performance.md) | 优化向量搜索性能。 | +| [限制](/ai/reference/vector-search-limitations.md) | 当前的限制与约束。 | \ No newline at end of file diff --git a/ai/concepts/vector-search-overview.md b/ai/concepts/vector-search-overview.md new file mode 100644 index 000000000000..fb796ee374b6 --- /dev/null +++ b/ai/concepts/vector-search-overview.md @@ -0,0 +1,74 @@ +--- +title: Vector Search Overview +summary: 了解 TiDB 中的向量搜索功能。该功能为文档、图片、音频和视频等多种数据类型提供了先进的语义相似性搜索解决方案。 +aliases: ['/zh/tidb/stable/vector-search-overview/','/zh/tidb/dev/vector-search-overview/','/zh/tidbcloud/vector-search-overview/'] +--- + +# 向量搜索概述 + +向量搜索为文档、图片、音频和视频等多种数据类型提供了强大的语义相似性搜索解决方案。它允许开发者利用 MySQL 的专业知识，构建具备生成式 AI 能力的可扩展应用，简化高级搜索功能的集成。 + +> **注意：** +> +> - 向量搜索功能目前为 Beta 版本，可能会在未提前通知的情况下发生变更。如果你发现了 bug，可以在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues)。 +> - 向量搜索功能适用于 [TiDB 自托管](/overview.md)、[TiDB Cloud Starter](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#starter)、[TiDB Cloud Essential](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#essential) 和 [TiDB Cloud Dedicated](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated)。对于 TiDB 自托管和 TiDB Cloud Dedicated，TiDB 版本需为 v8.4.0 或更高（推荐 v8.5.0 或更高）。 + +## 概念 + +向量搜索是一种以数据语义为核心、提供相关性结果的搜索方法。 + +与传统的全文搜索依赖于精确关键字匹配和词频不同，向量搜索会将多种数据类型（如文本、图片或音频）转换为高维向量，并基于这些向量之间的相似性进行查询。这种搜索方法能够捕捉数据的语义含义和上下文信息，从而更准确地理解用户意图。 + +即使搜索词与数据库中的内容并不完全匹配，向量搜索也可以通过分析数据的语义，返回符合用户意图的结果。 + +例如，使用全文搜索查询 “a swimming animal” 只会返回包含这些精确关键字的结果。而向量搜索则可以返回其他游泳动物（如鱼或鸭子）的结果，即使这些结果中并不包含完全相同的关键字。 + +### 向量嵌入 {#vector-embedding} + +向量嵌入（vector embedding），也称为 embedding，是一组数字序列，用于在高维空间中表示现实世界的对象。它能够捕捉非结构化数据（如文档、图片、音频和视频）的语义和上下文信息。 + +向量嵌入在机器学习中至关重要，是语义相似性搜索的基础。 + +TiDB 引入了专为优化向量嵌入存储与搜索设计的 [向量数据类型](/ai/reference/vector-search-data-types.md) 和 [向量搜索索引](/ai/reference/vector-search-index.md)，提升其在 AI 应用中的使用效率。你可以将向量嵌入存储在 TiDB 中，并通过这些数据类型执行向量搜索查询，查找最相关的数据。 + +### 嵌入模型 {#embedding-model} + +嵌入模型（embedding model）是一种将数据转换为 [向量嵌入](#vector-embedding) 的算法。 + +选择合适的嵌入模型对于确保语义搜索结果的准确性和相关性至关重要。对于非结构化文本数据，你可以在 [Massive Text Embedding Benchmark (MTEB) Leaderboard](https://huggingface.co/spaces/mteb/leaderboard) 上查找表现优异的文本嵌入模型。 + +如需了解如何为你的特定数据类型生成向量嵌入，请参考集成教程或嵌入模型示例。 + +## 向量搜索的工作原理 + +在将原始数据转换为向量嵌入并存储到 TiDB 后，你的应用可以执行向量搜索查询，查找与用户查询在语义或上下文上最相关的数据。 + +TiDB 向量搜索通过使用 [距离函数](/ai/reference/vector-search-functions-and-operators.md) 计算给定向量与数据库中已存储向量之间的距离，从而识别出 top-k 最近邻（KNN）向量。与查询向量距离最近的向量，代表在语义上最相似的数据。 + +![The Schematic TiDB Vector Search](/media/vector-search/embedding-search.png) + +作为一款集成了向量搜索能力的关系型数据库，TiDB 允许你将数据及其对应的向量表示（即向量嵌入）一同存储在同一个数据库中。你可以选择以下任意一种存储方式： + +- 在同一张表的不同列中存储数据及其对应的向量表示。 +- 在不同的表中分别存储数据及其对应的向量表示。此时，搜索数据时需要使用 `JOIN` 查询将表进行关联。 + +## 应用场景 + +### 检索增强生成（RAG） + +检索增强生成（Retrieval-Augmented Generation，RAG）是一种旨在优化大语言模型（LLM）输出的架构。通过向量搜索，RAG 应用可以将向量嵌入存储在数据库中，并在 LLM 生成响应时搜索相关文档作为额外上下文，从而提升答案的质量和相关性。 + +### 语义搜索 + +语义搜索是一种基于查询语义返回结果的搜索技术，而不仅仅是关键字匹配。它通过嵌入理解不同语言和多种类型数据（如文本、图片和音频）的含义。向量搜索算法随后利用这些嵌入，查找最能满足用户查询需求的相关数据。 + +### 推荐引擎 + +推荐引擎是一种能够主动为用户推荐相关且个性化内容、产品或服务的系统。它通过创建表示用户行为和偏好的嵌入，帮助系统识别其他用户曾经互动或感兴趣的相似项目，从而提升推荐的相关性和吸引力。 + +## 另请参阅 + +如需开始使用 TiDB 向量搜索，请参阅以下文档： + +- [使用 Python 快速上手向量搜索](/ai/quickstart-via-python.md) +- [使用 SQL 快速上手向量搜索](/ai/quickstart-via-sql.md) diff --git a/ai/examples/auto-embedding-with-pytidb.md b/ai/examples/auto-embedding-with-pytidb.md new file mode 100644 index 000000000000..d10415e7ccc9 --- /dev/null +++ b/ai/examples/auto-embedding-with-pytidb.md @@ -0,0 +1,87 @@ +--- +title: Auto Embedding 示例 +summary: 使用内置嵌入模型为你的文本数据自动生成嵌入向量。 +--- + +# Auto Embedding 示例 + +本示例展示如何通过 [Auto Embedding](/ai/integrations/vector-search-auto-embedding-overview.md) 功能，结合 [pytidb](https://github.com/pingcap/pytidb) client 使用 Auto Embedding。 + +1. 使用 `pytidb` client 连接 TiDB。 +2. 定义一个配置了 Auto Embedding 的 VectorField 的表。 +3. 插入纯文本数据：嵌入向量会在后台自动填充。 +4. 使用自然语言查询进行向量搜索：嵌入向量会透明地生成。 + +## 前置条件 + +在开始之前，请确保你具备以下条件： + +- **Python (>=3.10)**：安装 [Python](https://www.python.org/downloads/) 3.10 或以上版本。 +- **TiDB Cloud Starter 集群**：你可以在 [TiDB Cloud](https://tidbcloud.com/free-trial) 上创建一个免费的 TiDB 集群。 + +## 运行方法 + +### 步骤 1. 克隆 `pytidb` 仓库 + +```bash +git clone https://github.com/pingcap/pytidb.git +cd pytidb/examples/auto_embedding/ +``` + +### 步骤 2. 安装所需依赖包 + +```bash +python -m venv .venv +source .venv/bin/activate +pip install -r reqs.txt +``` + +### 步骤 3. 设置环境变量 + +1. 在 [TiDB Cloud 控制台](https://tidbcloud.com/)中，进入 [**Clusters**](https://tidbcloud.com/clusters) 页面，然后点击目标集群名称，进入其概览页面。 +2. 点击右上角的 **Connect**。会弹出连接对话框，显示连接参数。 +3. 根据连接参数如下设置环境变量： + +```bash +cat > .env <=3.10)**：安装 [Python](https://www.python.org/downloads/) 3.10 或以上版本。 +- **一个 TiDB Cloud Starter 集群**：你可以在 [TiDB Cloud](https://tidbcloud.com/free-trial) 上免费创建 TiDB 集群。 + +## 运行方法 + +### 步骤 1. 克隆 `pytidb` 仓库 + +```bash +git clone https://github.com/pingcap/pytidb.git +cd pytidb/examples/basic/ +``` + +### 步骤 2. 安装所需依赖包 + +```bash +python -m venv .venv +source .venv/bin/activate +pip install -r reqs.txt +``` + +### 步骤 3. 设置环境变量 + +1. 在 [TiDB Cloud 控制台](https://tidbcloud.com/)中，进入 [**Clusters**](https://tidbcloud.com/clusters) 页面，然后点击目标集群名称进入其概览页面。 +2. 点击右上角的 **Connect**，会弹出连接对话框，显示连接参数。 +3. 根据连接参数设置环境变量，如下所示： + +```bash +cat > .env < + E-commerce product search with full-text search +

基于全文搜索的电商产品搜索

+

+ +## 前置条件 + +在开始之前，请确保你具备以下条件： + +- **Python (>=3.10)**：安装 [Python](https://www.python.org/downloads/) 3.10 或以上版本。 +- **TiDB Cloud Starter 集群**：你可以在 [TiDB Cloud](https://tidbcloud.com/free-trial) 上创建一个免费的 TiDB 集群。 + +## 运行方法 + +### 步骤 1. 克隆 `pytidb` 仓库 + +[`pytidb`](https://github.com/pingcap/pytidb) 是官方的 TiDB Python SDK，旨在帮助开发者高效构建 AI 应用。 + +```bash +git clone https://github.com/pingcap/pytidb.git +cd pytidb/examples/fulltext_search/ +``` + +### 步骤 2. 安装所需依赖并设置环境 + +```bash +python -m venv .venv +source .venv/bin/activate +pip install -r reqs.txt +``` + +### 步骤 3. 设置环境变量 + +1. 在 [TiDB Cloud 控制台](https://tidbcloud.com/)中，进入 [**Clusters**](https://tidbcloud.com/clusters) 页面，然后点击目标集群名称，进入其概览页面。 +2. 点击右上角的 **Connect**。此时会弹出连接对话框，显示连接参数。 +3. 根据连接参数设置环境变量，如下所示： + +```bash +cat > .env < + TiDB Hybrid Search Demo +

TiDB Hybrid Search Demo

+

+ +## 前置条件 + +在开始之前，请确保你具备以下条件： + +- **Python (>=3.10)**：安装 [Python](https://www.python.org/downloads/) 3.10 或以上版本。 +- **TiDB Cloud Starter 集群**：你可以在 [TiDB Cloud](https://tidbcloud.com/free-trial) 上创建一个免费的 TiDB 集群。 +- **OpenAI API key**：从 [OpenAI](https://platform.openai.com/api-keys) 获取 OpenAI API key。 + +> **注意** +> +> 目前，全文搜索仅在以下产品选项和区域中可用： +> +> - TiDB Cloud Starter：法兰克福（`eu-central-1`）、新加坡（`ap-southeast-1`） + +## 如何运行 + +### 步骤 1. 克隆 `pytidb` 仓库 + +[pytidb](https://github.com/pingcap/pytidb) 是 TiDB 的官方 Python SDK，旨在帮助开发者高效构建 AI 应用。 + +```bash +git clone https://github.com/pingcap/pytidb.git +cd pytidb/examples/hybrid_search +``` + +### 步骤 2. 安装所需包并设置环境 + +```bash +python -m venv .venv +source .venv/bin/activate +pip install -r reqs.txt +``` + +### 步骤 3. 设置环境变量 + +1. 在 [TiDB Cloud 控制台](https://tidbcloud.com/)中，进入 [**Clusters**](https://tidbcloud.com/clusters) 页面，然后点击目标集群名称，进入其概览页面。 +2. 点击右上角的 **Connect**。会弹出连接对话框，显示连接参数。 +3. 根据连接参数设置环境变量，如下所示： + +```bash +cat > .env < +EOF +``` + +### 步骤 4. 运行演示 + +### 选项 1. 运行 Streamlit 应用 + +如果你希望通过 Web UI 查看演示，可以运行以下命令： + +```bash +streamlit run app.py +``` + +在浏览器中访问 `http://localhost:8501`。 + +### 选项 2. 运行演示脚本 + +如果你希望通过脚本查看演示，可以运行以下命令： + +```bash +python example.py +``` + +预期输出： + +``` +=== CONNECT TO TIDB === +Connected to TiDB. + +=== CREATE TABLE === +Table created. + +=== INSERT SAMPLE DATA === +Inserted 3 rows. + +=== PERFORM HYBRID SEARCH === +Search results: +[ + { + "_distance": 0.4740166257687124, + "_match_score": 1.6804268, + "_score": 0.03278688524590164, + "id": 60013, + "text": "TiDB is a distributed database that supports OLTP, OLAP, HTAP and AI workloads." + }, + { + "_distance": 0.6428459116216618, + "_match_score": 0.78427225, + "_score": 0.03200204813108039, + "id": 60015, + "text": "LlamaIndex is a Python library for building AI-powered applications." + }, + { + "_distance": 0.641581407158715, + "_match_score": null, + "_score": 0.016129032258064516, + "id": 60014, + "text": "PyTiDB is a Python library for developers to connect to TiDB." + } +] +``` + +## 相关资源 + +- **源代码**：[在 GitHub 上查看](https://github.com/pingcap/pytidb/tree/main/examples/hybrid_search) \ No newline at end of file diff --git a/ai/examples/image-search-with-pytidb.md b/ai/examples/image-search-with-pytidb.md new file mode 100644 index 000000000000..74701fb120b5 --- /dev/null +++ b/ai/examples/image-search-with-pytidb.md @@ -0,0 +1,102 @@ +--- +title: 图像搜索示例 +summary: 使用多模态嵌入构建一个支持文本到图像和图像到图像搜索的图像搜索应用。 +--- + +# 图像搜索示例 + +本示例展示了如何通过结合 TiDB 向量搜索能力与多模态嵌入模型，构建一个图像搜索应用。 + +只需几行代码，你就可以创建一个能够理解文本和图像的搜索系统。 + +- **Text-to-image search**：通过自然语言描述（如 “fluffy orange cat”）查找宠物照片 +- **Image-to-image search**：上传一张照片，根据品种、颜色、姿势等查找视觉上相似的宠物 + +

+ PyTiDB Image Search Demo +

通过多模态嵌入进行宠物图像搜索

+

+ +## 前置条件 + +在开始之前，请确保你已具备以下条件： + +- **Python (>=3.10)**：安装 [Python](https://www.python.org/downloads/) 3.10 或以上版本。 +- **TiDB Cloud Starter 集群**：你可以在 [TiDB Cloud](https://tidbcloud.com/free-trial) 上创建一个免费的 TiDB 集群。 +- **Jina AI API key**：你可以从 [Jina AI Embeddings](https://jina.ai/embeddings/) 免费获取 API key。 + +## 运行方法 + +### 步骤 1. 克隆 `pytidb` 仓库 + +[`pytidb`](https://github.com/pingcap/pytidb) 是 TiDB 的官方 Python SDK，旨在帮助开发者高效构建 AI 应用。 + +```bash +git clone https://github.com/pingcap/pytidb.git +cd pytidb/examples/image_search/ +``` + +### 步骤 2. 安装所需依赖包 + +```bash +python -m venv .venv +source .venv/bin/activate # Windows: .venv\Scripts\activate +pip install -r reqs.txt +``` + +### 步骤 3. 设置环境变量 + +1. 在 [TiDB Cloud 控制台](https://tidbcloud.com/)中，进入 [**Clusters**](https://tidbcloud.com/clusters) 页面，然后点击目标集群名称进入其概览页面。 +2. 点击右上角的 **Connect**。此时会弹出连接对话框，显示连接参数。 +3. 根据连接参数设置环境变量，如下所示： + +```bash +cat > .env < + AI Agent with memory powered by TiDB +

AI Agent with memory powered by TiDB

+

+ +## Prerequisites + +在开始之前，请确保你已具备以下条件： + +- **Python (>=3.10)**：安装 [Python](https://www.python.org/downloads/) 3.10 或以上版本。 +- **A TiDB Cloud Starter cluster**：你可以在 [TiDB Cloud](https://tidbcloud.com/free-trial) 上创建免费的 TiDB 集群。 +- **OpenAI API key**：从 [OpenAI](https://platform.openai.com/api-keys) 获取 OpenAI API key。 + +## How to run + +### Step 1. 克隆 `pytidb` repository + +[`pytidb`](https://github.com/pingcap/pytidb) 是 TiDB 官方 Python SDK，旨在帮助开发者高效构建 AI 应用。 + +```bash +git clone https://github.com/pingcap/pytidb.git +cd pytidb/examples/memory/ +``` + +### Step 2. 安装所需依赖包 + +```bash +python -m venv .venv +source .venv/bin/activate # Windows: .venv\Scripts\activate +pip install -r reqs.txt +``` + +### Step 3. 设置 environment variables + +1. 在 [TiDB Cloud 控制台](https://tidbcloud.com/)中，进入 [**Clusters**](https://tidbcloud.com/clusters) 页面，然后点击目标集群名称进入其概览页面。 +2. 点击右上角的 **Connect**。此时会弹出连接对话框，显示连接参数。 +3. 根据连接参数设置 environment variables，如下所示： + +```bash +cat > .env < + RAG application built with PyTiDB +

基于 PyTiDB 构建的 RAG 应用

+

+ +## 前置条件 + +在开始之前，请确保你已具备以下条件： + +- **Python (>=3.10)**：安装 [Python](https://www.python.org/downloads/) 3.10 或以上版本。 +- **TiDB Cloud Starter 集群**：你可以在 [TiDB Cloud](https://tidbcloud.com/free-trial) 上创建一个免费的 TiDB 集群。 +- **Ollama**：从 [Ollama](https://ollama.com/download) 安装。 + +## 运行方法 + +### 步骤 1. 准备推理 API + +使用 Ollama CLI 拉取 embedding 和 LLM 镜像： + +```bash +ollama pull mxbai-embed-large +ollama pull gemma3:4b +ollama run gemma3:4b +``` + +验证 `/embed` 和 `/generate` 接口是否已启动： + +```bash +curl http://localhost:11434/api/embed -d '{ + "model": "mxbai-embed-large", + "input": "Llamas are members of the camelid family" +}' +``` + +```bash +curl http://localhost:11434/api/generate -d '{ + "model": "gemma3:4b", + "prompt": "Hello, Who are you?" +}' +``` + +### 步骤 2. 克隆仓库 + +```bash +git clone https://github.com/pingcap/pytidb.git +cd pytidb/examples/rag/ +``` + +### 步骤 3. 安装所需依赖并设置环境 + +```bash +python -m venv .venv +source .venv/bin/activate +pip install -r reqs.txt +``` + +### 步骤 4. 设置环境变量 + +1. 在 [TiDB Cloud 控制台](https://tidbcloud.com/)中，进入 [**Clusters**](https://tidbcloud.com/clusters) 页面，然后点击目标集群名称，进入其概览页面。 +2. 点击右上角的 **Connect**。此时会弹出连接对话框，显示连接参数。 +3. 根据连接参数设置环境变量，如下所示： + +```bash +cat > .env <=3.10)**：安装 [Python](https://www.python.org/downloads/) 3.10 或以上版本。 +- **TiDB Cloud Starter 集群**：你可以在 [TiDB Cloud](https://tidbcloud.com/free-trial) 上创建一个免费的 TiDB 集群。 +- **OpenAI API key**：从 [OpenAI](https://platform.openai.com/api-keys) 获取 OpenAI API key。 + +## 运行方法 + +### 第 1 步. 克隆 `pytidb` 仓库 + +```bash +git clone https://github.com/pingcap/pytidb.git +cd pytidb/examples/text2sql/ +``` + +### 第 2 步. 安装所需依赖包 + +```bash +python -m venv .venv +source .venv/bin/activate +pip install -r reqs.txt +``` + +### 第 3 步. 运行 Streamlit 应用 + +```bash +streamlit run app.py +``` + +### 第 4 步. 使用应用 + +打开浏览器并访问 `http://localhost:8501`。 + +1. 在左侧边栏输入你的 OpenAI API key +2. 在左侧边栏输入 TiDB 连接字符串，例如：`mysql+pymysql://root@localhost:4000/test` + +## 相关资源 + +- **源代码**：[在 GitHub 上查看](https://github.com/pingcap/pytidb/tree/main/examples/text2sql) \ No newline at end of file diff --git a/ai/examples/vector-search-with-pytidb.md b/ai/examples/vector-search-with-pytidb.md new file mode 100644 index 000000000000..eee5c8472d65 --- /dev/null +++ b/ai/examples/vector-search-with-pytidb.md @@ -0,0 +1,85 @@ +--- +title: 向量搜索示例 +summary: 使用向量嵌入实现语义搜索，查找相似内容。 +--- + +# 向量搜索示例 + +本示例演示如何使用 TiDB 和本地嵌入模型构建语义搜索应用。它通过向量搜索，根据含义（而不仅仅是关键字）查找相似项。 + +该应用使用 [Ollama](https://ollama.com/download) 进行本地嵌入生成，使用 [Streamlit](https://streamlit.io/) 构建 Web UI，并使用 [`pytidb`](https://github.com/pingcap/pytidb)（TiDB 官方 Python SDK）搭建 RAG 流程。 + +

+ Semantic search with vector embeddings +

基于向量嵌入的语义搜索

+

+ +## 前置条件 + +在开始之前，请确保你具备以下条件： + +- **Python (>=3.10)**：安装 [Python](https://www.python.org/downloads/) 3.10 或以上版本。 +- **TiDB Cloud Starter 集群**：你可以在 [TiDB Cloud](https://tidbcloud.com/free-trial) 上创建免费的 TiDB 集群。 +- **Ollama**：从 [Ollama](https://ollama.com/download) 安装。 + +## 运行方法 + +### 步骤 1. 使用 Ollama 启动嵌入服务 + +拉取嵌入模型： + +```bash +ollama pull mxbai-embed-large +``` + +验证嵌入服务是否正在运行： + +```bash +curl http://localhost:11434/api/embed -d '{ + "model": "mxbai-embed-large", + "input": "Llamas are members of the camelid family" +}' +``` + +### 步骤 2. 克隆仓库 + +```bash +git clone https://github.com/pingcap/pytidb.git +cd pytidb/examples/vector_search/ +``` + +### 步骤 3. 安装所需依赖并配置环境 + +```bash +python -m venv .venv +source .venv/bin/activate +pip install -r reqs.txt +``` + +### 步骤 4. 设置环境变量 + +1. 在 [TiDB Cloud 控制台](https://tidbcloud.com/)中，进入 [**Clusters**](https://tidbcloud.com/clusters) 页面，然后点击目标集群名称，进入其概览页面。 +2. 点击右上角的 **Connect**。会弹出连接对话框，显示连接参数。 +3. 根据连接参数设置环境变量，如下所示： + + ```bash + cat > .env < **注意：** +> +> 有关 Auto Embedding 的完整示例，请参见 [Auto Embedding Example](/ai/examples/auto-embedding-with-pytidb.md)。 + +## 基本用法 + +本文档使用 TiDB Cloud 托管的嵌入模型进行演示。有关支持的全部提供商列表，请参见 [Auto Embedding Overview](/ai/integrations/vector-search-auto-embedding-overview.md#available-text-embedding-models)。 + +### 第 1 步. 定义嵌入函数 + +定义一个嵌入函数，用于为你的文本数据生成向量嵌入。 + +```python +from pytidb.embeddings import EmbeddingFunction + +embed_func = EmbeddingFunction( + model_name="tidbcloud_free/amazon/titan-embed-text-v2", +) +``` + +### 第 2 步. 创建表和向量字段 + +使用 `embed_func.VectorField()` 在表结构中创建一个向量字段。 + +要启用 Auto Embedding，请将 `source_field` 设置为你想要嵌入的字段。 + +```python hl_lines="7" +from pytidb.schema import TableModel, Field +from pytidb.datatype import TEXT + +class Chunk(TableModel): + id: int = Field(primary_key=True) + text: str = Field(sa_type=TEXT) + text_vec: list[float] = embed_func.VectorField(source_field="text") + +table = client.create_table(schema=Chunk, if_exists="overwrite") +``` + +你无需指定 `dimensions` 参数，因为嵌入模型会自动确定维度。 + +不过，你也可以设置 `dimensions` 参数来覆盖默认维度。 + +### 第 3 步. 插入一些示例数据 + +向表中插入一些示例数据。 + +```python +table.bulk_insert([ + Chunk(text="TiDB is a distributed database that supports OLTP, OLAP, HTAP and AI workloads."), + Chunk(text="PyTiDB is a Python library for developers to connect to TiDB."), + Chunk(text="LlamaIndex is a Python library for building AI-powered applications."), +]) +``` + +插入数据时，`text_vec` 字段会自动被由 `text` 生成的嵌入向量填充。 + +### 第 4 步. 执行向量查询 + +你可以将查询文本直接传递给 `search()` 方法。查询文本会被 Auto Embedding，然后用于向量查询。 + +```python +table.search("HTAP database").limit(3).to_list() +``` \ No newline at end of file diff --git a/ai/guides/connect.md b/ai/guides/connect.md new file mode 100644 index 000000000000..515bfc3aa76c --- /dev/null +++ b/ai/guides/connect.md @@ -0,0 +1,145 @@ +--- +title: 连接 TiDB +summary: 学习如何使用 `pytidb` 客户端连接到 TiDB 数据库。 +--- + +# 连接 TiDB + +本指南介绍如何使用 `pytidb` 客户端连接到 TiDB 数据库。 + +## 安装依赖项 + +[`pytidb`](https://github.com/pingcap/pytidb) 是一个基于 [SQLAlchemy](https://sqlalchemy.org/) 构建的 Python 客户端。它提供了一系列高级 API，帮助你存储和搜索向量嵌入，无需编写原始 SQL。 + +要安装 Python 客户端，请运行以下命令： + +```bash +pip install pytidb +``` + +## 使用连接参数进行连接 + +请根据你的 TiDB 部署类型选择相应步骤： + + +
+ +你可以[创建一个 TiDB Cloud Starter 集群](https://tidbcloud.com/free-trial/)，然后按照以下步骤在 Web 控制台获取连接参数： + +1. 进入 [Clusters 页面](https://tidbcloud.com/clusters)，点击目标集群名称，进入其概览页面。 +2. 点击右上角的 **Connect**。此时会弹出连接对话框，显示连接参数。 +3. 将连接参数复制到你的代码或环境变量中。 + +示例代码： + +```python title="main.py" +from pytidb import TiDBClient + +db = TiDBClient.connect( + host="{gateway-region}.prod.aws.tidbcloud.com", + port=4000, + username="{prefix}.root", + password="{password}", + database="test", +) +``` + +> **注意：** +> +> 对于 TiDB Cloud Starter，当使用公共端点时，[连接数据库必须使用 TLS](https://docs.pingcap.com/tidbcloud/secure-connections-to-starter-clusters/)。`pytidb` 客户端会**自动**为 TiDB Cloud Starter 集群启用 TLS。 + +
+
+ +按照 [TiDB 快速上手](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb/#deploy-a-local-test-cluster) 部署一个 TiDB 集群用于测试。 + +示例代码： + +```python title="main.py" +from pytidb import TiDBClient + +db = TiDBClient.connect( + host="{tidb_server_host}", + port=4000, + username="root", + password="{password}", + database="test", +) +``` + +> **注意：** +> +> 如果你使用 `tiup playground` 部署 TiDB 集群进行测试，默认主机为 `127.0.0.1`，默认密码为空。 + +
+ + +连接成功后，你可以使用 `db` 对象进行表操作、数据查询等。 + +## 使用连接字符串进行连接 + +如果你更喜欢使用连接字符串（数据库 URL），可以根据你的部署类型参考以下格式： + + +
+ +你可以[创建一个 TiDB Cloud Starter 集群](https://tidbcloud.com/free-trial/)，然后按照以下步骤在 Web 控制台获取连接参数： + +1. 进入 [Clusters 页面](https://tidbcloud.com/clusters)，点击目标集群名称，进入其概览页面。 +2. 点击右上角的 **Connect**。此时会弹出连接对话框，显示连接参数。 +3. 复制连接参数，并按以下格式构建连接字符串： + +```python title="main.py" +from pytidb import TiDBClient + +db = TiDBClient.connect( + database_url="mysql+pymysql://{USERNAME}:{PASSWORD}@{HOST}:{PORT}/{DATABASE}?ssl_verify_cert=true&ssl_verify_identity=true", +) +``` + +> **注意：** +> +> 对于 TiDB Cloud Starter，当使用公共端点时，[连接数据库必须使用 TLS](https://docs.pingcap.com/tidbcloud/secure-connections-to-starter-clusters/)，因此需要在连接字符串中设置 `ssl_verify_cert=true&ssl_verify_identity=true`。 + +
+
+ +你可以按照以下格式构建连接字符串： + +```python title="main.py" +from pytidb import TiDBClient + +db = TiDBClient.connect( + database_url="mysql+pymysql://{USERNAME}:{PASSWORD}@{HOST}:{PORT}/{DATABASE}", +) +``` + +> **注意：** +> +> 如果你使用 `tiup playground` 部署 TiDB 集群进行测试，连接字符串为： +> +> ``` +> mysql+pymysql://root:@127.0.0.1:4000/test +> ``` + +
+ + +## 使用 SQLAlchemy 数据库引擎连接 + +如果你的应用已经有 SQLAlchemy 数据库引擎，可以通过 `db_engine` 参数复用： + +```python title="main.py" +from pytidb import TiDBClient + +db = TiDBClient(db_engine=db_engine) +``` + +## 后续步骤 + +连接到 TiDB 数据库后，你可以参考以下指南，学习如何操作你的数据： + +- [表操作](/ai/guides/tables.md)：学习如何在 TiDB 中定义和管理表。 +- [向量搜索](/ai/guides/vector-search.md)：使用向量嵌入进行语义搜索。 +- [全文搜索](/ai/guides/vector-search-full-text-search-python.md)：通过关键字搜索文档。 +- [混合搜索](/ai/guides/vector-search-hybrid-search.md)：结合向量和全文搜索，获得更相关的结果。 \ No newline at end of file diff --git a/ai/guides/filtering.md b/ai/guides/filtering.md new file mode 100644 index 000000000000..dfb0b9353caa --- /dev/null +++ b/ai/guides/filtering.md @@ -0,0 +1,190 @@ +--- +title: 过滤 +summary: 了解如何在你的应用中使用过滤功能。 +--- + +# 过滤 + +作为一款关系型数据库，TiDB 支持丰富的 [SQL 运算符](https://docs.pingcap.com/tidbcloud/operators/) 以及灵活组合的过滤条件，用于实现精确查询。 + +## 概述 + +你可以对标量字段和 JSON 字段进行过滤。对 JSON 字段的过滤通常用于向量搜索中的 [元信息过滤](/ai/guides/vector-search.md#metadata-filtering)。 + +[`pytidb`](https://github.com/pingcap/pytidb) 是 TiDB 的官方 Python SDK，旨在帮助开发者高效构建 AI 应用。 + +在使用 `pytidb` 时，你可以通过将 **filters** 参数传递给 `table.query()`、`table.delete()`、`table.update()` 和 `table.search()` 方法来实现过滤。 + +**filters** 参数支持两种格式：[字典过滤器](#dictionary-filters) 和 [SQL 字符串过滤器](#sql-string-filters)。 + +## 字典过滤器 {#dictionary-filters} + +`pytidb` 允许你使用带有运算符的 Python 字典来定义过滤条件，并作为 **filters** 参数传入。 + +**filters** 的字典结构如下： + +```python +{ + "": { + "": + }, + ... +} +``` + +- ``：可以是列名、用于访问 JSON 字段的 JSON 路径表达式（参见 [元信息过滤](/ai/guides/vector-search.md#metadata-filtering)），或 [逻辑运算符](#logical-operators)。 +- ``：可以是 [比较运算符](#compare-operators) 或 [包含运算符](#inclusion-operators)。 +- ``：根据运算符，可以是标量值或数组。 + +**示例：过滤 `created_at` 大于 2024-01-01 的记录** + +```python +table.query({ + # `created_at` 是 DATETIME 类型的标量字段 + "created_at": { + "$gt": "2024-01-01" + } +}) +``` + +**示例：过滤 `meta.category` 在 ["tech", "science"] 数组中的记录** + +```python +results = ( + table.search("some query", search_type="vector") + .filter({ + # `meta` 是 JSON 字段，其值为类似 {"category": "tech"} 的 JSON 对象 + "meta.category": { + "$in": ["tech", "science"] + } + }) + .limit(10) + .to_list() +) +``` + +### 比较运算符 {#compare-operators} + +你可以使用以下比较运算符来过滤记录： + +| 运算符 | 描述 | +|----------|----------------------------| +| `$eq` | 等于指定值 | +| `$ne` | 不等于指定值 | +| `$gt` | 大于指定值 | +| `$gte` | 大于等于指定值 | +| `$lt` | 小于指定值 | +| `$lte` | 小于等于指定值 | + +**示例：过滤 `user_id` 等于 1 的记录** + +```python +{ + "user_id": { + "$eq": 1 + } +} +``` + +你可以省略 `$eq` 运算符。以下过滤条件与上例等价： + +```python +{ + "user_id": 1 +} +``` + +### 包含运算符 {#inclusion-operators} + +你可以使用以下包含运算符来过滤记录： + +| 运算符 | 描述 | +|----------|--------------------------------------| +| `$in` | 在数组中（string、整数型或 float） | +| `$nin` | 不在数组中（string、整数型、float） | + +**示例：过滤 `category` 在 ["tech", "science"] 数组中的记录** + +```python +{ + "category": { + "$in": ["tech", "science"] + } +} +``` + +### 逻辑运算符 {#logical-operators} + +你可以使用逻辑运算符 `$and` 和 `$or` 组合多个过滤条件。 + +| 运算符 | 描述 | +|----------|----------------------------------------------| +| `$and` | 返回同时满足列表中**所有**过滤条件的结果 | +| `$or` | 返回满足列表中**任意**过滤条件的结果 | + +**`$and` 或 `$or` 的语法：** + +```python +{ + "$and|$or": [ + { + "field_name": { + : + } + }, + { + "field_name": { + : + } + } + ... + ] +} +``` + +**示例：使用 `$and` 组合多个过滤条件：** + +```python +{ + "$and": [ + { + "created_at": { + "$gt": "2024-01-01" + } + }, + { + "meta.category": { + "$in": ["tech", "science"] + } + } + ] +} +``` + +## SQL 字符串过滤器 {#sql-string-filters} + +你也可以将 SQL 字符串作为 `filters` 使用。该字符串必须是符合 TiDB SQL 语法的有效 SQL `WHERE` 子句（不包含 `WHERE` 关键字）。 + +**示例：过滤 `created_at` 大于 2024-01-01 的记录** + +```python +results = table.query( + filters="created_at > '2024-01-01'", + limit=10 +).to_list() +``` + +**示例：过滤 JSON 字段 `meta.category` 等于 'tech' 的记录** + +```python +results = table.query( + filters="meta->>'$.category' = 'tech'", + limit=10 +).to_list() +``` + +你可以使用 `AND`、`OR` 和括号组合多个条件，并使用任何 TiDB 支持的 [SQL 运算符](https://docs.pingcap.com/tidbcloud/operators/)。 + +> **警告：** +> +> 当使用带有动态用户输入的 SQL 字符串过滤器时，务必校验输入，以防止 [SQL 注入](https://en.wikipedia.org/wiki/SQL_injection) 漏洞。 \ No newline at end of file diff --git a/ai/guides/image-search.md b/ai/guides/image-search.md new file mode 100644 index 000000000000..e4c6c47ada9c --- /dev/null +++ b/ai/guides/image-search.md @@ -0,0 +1,111 @@ +--- +title: 图像搜索 +summary: 了解如何在你的应用中使用图像搜索。 +--- + +# 图像搜索 + +**图像搜索** 通过比较图像的视觉内容（而不仅仅是文本或元信息）来帮助你查找相似的镜像。该功能适用于电商、内容审核、数字资产管理，以及任何需要基于外观搜索或去重镜像的场景。 + +TiDB 通过 **向量搜索** 实现图像搜索。借助 Auto Embedding，你可以使用多模态嵌入模型，从镜像 URL、PIL 镜像或关键字文本生成镜像嵌入。TiDB 随后可以在扩展下搜索相似的向量。 + +> **注意：** +> +> 有关图像搜索的完整示例，请参见 [Image Search Example](/ai/examples/image-search-with-pytidb.md)。 + +## 基本用法 + +### 第 1 步. 定义嵌入函数 + +要生成镜像嵌入，你需要一个支持镜像输入的嵌入模型。 + +演示中，你可以使用 Jina AI 的多模态嵌入模型。 + +前往 [Jina AI](https://jina.ai/embeddings) 创建 API key，然后按如下方式初始化嵌入函数： + +```python hl_lines="7" +from pytidb.embeddings import EmbeddingFunction + +image_embed = EmbeddingFunction( + # Or another provider/model that supports multimodal input + model_name="jina_ai/jina-embedding-v4", + api_key="{your-jina-api-key}", + multimodal=True, +) +``` + +### 第 2 步. 创建表和向量字段 + +使用 `VectorField()` 定义用于存储镜像嵌入的向量字段。通过设置 `source_field` 参数，指定存储镜像 URL 的字段。 + +```python +from pytidb.schema import TableModel, Field + +class ImageItem(TableModel): + __tablename__ = "image_items" + id: int = Field(primary_key=True) + image_uri: str = Field() + image_vec: list[float] = image_embed.VectorField( + source_field="image_uri" + ) + +table = client.create_table(schema=ImageItem, if_exists="overwrite") +``` + +### 第 3 步. 插入镜像数据 + +当你插入数据时，`image_vec` 字段会自动用从 `image_uri` 生成的嵌入进行填充。 + +```python +table.bulk_insert([ + ImageItem(image_uri="https://example.com/image1.jpg"), + ImageItem(image_uri="https://example.com/image2.jpg"), + ImageItem(image_uri="https://example.com/image3.jpg"), +]) +``` + +### 第 4 步. 执行图像搜索 + +图像搜索是一种向量搜索。借助 Auto Embedding，你可以直接提供镜像 URL、PIL 镜像或关键字文本，每种输入都会被转换为嵌入用于相似性匹配。 + +#### 选项 1：通过镜像 URL 搜索 + +通过提供镜像 URL 搜索相似镜像： + +```python +results = table.search("https://example.com/query.jpg").limit(3).to_list() +``` + +客户端会将镜像 URL 转换为向量。TiDB 随后通过比较向量返回最相似的镜像。 + +#### 选项 2：通过 PIL 镜像搜索 + +你也可以通过提供镜像文件或字节流来搜索相似镜像： + +```python +from PIL import Image + +image = Image.open("/path/to/query.jpg") + +results = table.search(image).limit(3).to_list() +``` + +客户端会在发送给嵌入模型前，将 PIL 镜像对象转换为 Base64 字符串。 + +#### 选项 3：通过关键字文本搜索 + +你还可以通过提供关键字文本来搜索相似镜像。 + +例如，如果你在处理宠物镜像数据集，可以通过 “orange tabby cat” 或 “golden retriever puppy” 等关键字来查找相似镜像。 + +```python +results = table.search("orange tabby cat").limit(3).to_list() +``` + +然后，多模态嵌入模型会将关键字文本转换为能够表达其语义含义的嵌入，TiDB 会执行向量搜索，查找嵌入与该关键字嵌入最相似的镜像。 + +## 另请参阅 + +- [Auto Embedding 指南](/ai/guides/auto-embedding.md) +- [向量搜索指南](/ai/concepts/vector-search-overview.md) +- [Image Search Example](/ai/examples/image-search-with-pytidb.md) diff --git a/ai/guides/join-queries.md b/ai/guides/join-queries.md new file mode 100644 index 000000000000..5c443aa46126 --- /dev/null +++ b/ai/guides/join-queries.md @@ -0,0 +1,124 @@ +--- +title: 多表连接 +summary: 学习如何在你的应用中使用多表连接。 +--- + +# 多表连接 + +作为一个关系型数据库，TiDB 允许你在同一个数据库中以不同结构（例如，`chunks`、`documents`、`users`、`chats`）存储多样化的数据。你还可以使用连接操作，将来自多个表的数据组合在一起，执行复杂的查询。 + +## 基本用法 + +### 第 1 步：创建表并插入示例数据 + + +
+ +假设你已经使用 `TiDBClient` [连接到 TiDB](/ai/guides/connect.md)： + +创建一个 `documents` 表并插入一些示例数据： + +```python +from pytidb import Session +from pytidb.schema import TableModel, Field +from pytidb.sql import select + +class Document(TableModel): + __tablename__ = "documents" + id: int = Field(primary_key=True) + title: str = Field(max_length=255) + +client.create_table(schema=Document, if_exists="overwrite") +client.table("documents").truncate() +client.table("documents").bulk_insert([ + Document(id=1, title="The Power of Positive Thinking"), + Document(id=2, title="The Happiness Advantage"), + Document(id=3, title="The Art of Happiness"), +]) +``` + +创建一个 `chunks` 表并插入一些示例数据： + +```python +class Chunk(TableModel): + __tablename__ = "chunks" + id: int = Field(primary_key=True) + text: str = Field(max_length=255) + document_id: int = Field(foreign_key="documents.id") + +client.create_table(schema=Chunk, if_exists="overwrite") +client.table("chunks").truncate() +client.table("chunks").bulk_insert([ + Chunk(id=1, text="Positive thinking can change your life", document_id=1), + Chunk(id=2, text="Happiness leads to success", document_id=2), + Chunk(id=3, text="Finding joy in everyday moments", document_id=3), +]) +``` + +
+
+ +创建一个 `documents` 表并插入一些示例数据： + +```sql +CREATE TABLE documents ( + id INT PRIMARY KEY, + title VARCHAR(255) NOT NULL +); + +INSERT INTO documents (id, title) VALUES + (1, 'The Power of Positive Thinking'), + (2, 'The Happiness Advantage'), + (3, 'The Art of Happiness'); +``` + +创建一个 `chunks` 表并插入一些示例数据： + +```sql +CREATE TABLE chunks ( + id INT PRIMARY KEY, + text VARCHAR(255) NOT NULL, + document_id INT NOT NULL, + FOREIGN KEY (document_id) REFERENCES documents(id) +); + +INSERT INTO chunks (id, text, document_id) VALUES + (1, 'Positive thinking can change your life', 1), + (2, 'Happiness leads to success', 2), + (3, 'Finding joy in everyday moments', 3); +``` + +
+ + +### 第 2 步：执行连接查询 + + +
+ +```python +with Session(client.db_engine) as db_session: + query = ( + select(Chunk) + .join(Document, Chunk.document_id == Document.id) + .where(Document.title == "The Power of Positive Thinking") + ) + chunks = db_session.exec(query).all() + +[(c.id, c.text, c.document_id) for c in chunks] +``` + +
+
+ +执行连接查询，将 `chunks` 和 `documents` 表中的数据组合在一起： + +```sql +SELECT c.id, c.text, c.document_id +FROM chunks c +JOIN documents d ON c.document_id = d.id +WHERE d.title = 'The Power of Positive Thinking'; +``` + +
+ \ No newline at end of file diff --git a/ai/guides/raw-queries.md b/ai/guides/raw-queries.md new file mode 100644 index 000000000000..9f343a5a7d67 --- /dev/null +++ b/ai/guides/raw-queries.md @@ -0,0 +1,89 @@ +--- +title: 原始查询 +summary: 学习如何在你的应用程序中使用原始查询。 +--- + +# 原始查询 + +本指南介绍如何在你的应用程序中运行原始 SQL 查询。 + +## 使用原始 SQL 操作数据 + +使用 `客户端.执行()` 方法来执行 `INSERT`、`UPDATE`、`DELETE` 以及其他数据操作语句。 + +```python +client.execute("INSERT INTO chunks(text, user_id) VALUES ('sample text', 5)") +``` + +### SQL 注入防护 + +`执行()` 和 `查询()` 方法都支持 **参数化 SQL** 功能，这有助于你在构建动态 SQL 语句时避免 [SQL 注入](https://en.wikipedia.org/wiki/SQL_injection)。 + +```python +client.execute( + "INSERT INTO chunks(text, user_id) VALUES (:text, :user_id)", + { + "text": "sample text", + "user_id": 6, + }, +) +``` + +## 使用原始 SQL 查询数据 + +使用 `客户端.查询()` 方法来执行 `SELECT`、`SHOW` 以及其他查询语句。 + +### 输出查询结果 + +`客户端.查询()` 方法会返回一个 `SQLQueryResult` 实例，并带有一些辅助方法： + +- `to_pydantic()` +- `to_list()` +- `to_pandas()` +- `to_rows()` +- `scalar()` + +#### 作为 Pydantic 模型 + +`to_pydantic()` 方法会返回一个 Pydantic 模型列表。 + +```python +client.query("SELECT id, text, user_id FROM chunks").to_pydantic() +``` + +#### 作为 SQLAlchemy 结果行 + +`to_rows()` 方法会返回一个元组列表，每个元组代表一行数据。 + +```python +client.query("SHOW TABLES;").to_rows() +``` + +#### 作为字典列表 + +`to_list()` 方法会将查询结果转换为字典列表。 + +```python +client.query( + "SELECT id, text, user_id FROM chunks WHERE user_id = :user_id", + { + "user_id": 3 + } +).to_list() +``` + +#### 作为 pandas DataFrame + +`to_pandas()` 方法会将查询结果转换为 `pandas.DataFrame`，在 notebook 中以更易读的格式展示： + +```python +client.query("SELECT id, text, user_id FROM chunks").to_pandas() +``` + +#### 作为标量值 + +`scalar()` 方法会返回结果集第一行的第一列。 + +```python +client.query("SELECT COUNT(*) FROM chunks;").scalar() +``` \ No newline at end of file diff --git a/ai/guides/reranking.md b/ai/guides/reranking.md new file mode 100644 index 000000000000..343127273167 --- /dev/null +++ b/ai/guides/reranking.md @@ -0,0 +1,53 @@ +--- +title: Reranking +summary: 了解如何在你的应用中使用 reranking。 +--- + +# Reranking + +Reranking（重排序）是一种通过使用专用的重排序模型对搜索结果进行重新评估和排序，以提升结果相关性和准确性的技术。 + +搜索过程分为两个阶段： + +1. **初始搜索**：向量搜索从集合中识别出最相似的前 `k` 个文档。 +2. **重排序**：重排序模型根据查询与这些 `k` 个文档之间的相关性进行评估，并重新排序，生成最终的前 `n` 个结果（其中 `n` ≤ `k`）。 + +这种两阶段搜索方法能显著提升文档的相关性和准确性。 + +## 基本用法 + +[`pytidb`](https://github.com/pingcap/pytidb) 是 TiDB 官方的 Python SDK，旨在帮助开发者高效构建 AI 应用。 + +`pytidb` 提供了 `Reranker` 类，让你可以使用来自多个第三方提供商的重排序模型。 + +1. 创建一个重排序实例： + + ```python + from pytidb.rerankers import Reranker + + reranker = Reranker(model_name="{provider}/{model_name}") + ``` + +2. 通过 `.rerank()` 方法应用重排序： + + ```python + table.search("{query}").rerank(reranker, "{field_to_rerank}").limit(3) + ``` + +## 支持的提供商 + +以下示例展示了如何使用第三方提供商的重排序模型。 + +### Jina AI + +要使用 Jina AI 的重排序器，请前往其 [官网](https://jina.ai/reranker) 创建 API 密钥。 + +例如： + +```python +jinaai = Reranker( + # 使用 `jina-reranker-m0` 模型 + model_name="jina_ai/jina-reranker-m0", + api_key="{your-jinaai-api-key}" +) +``` \ No newline at end of file diff --git a/ai/guides/tables.md b/ai/guides/tables.md new file mode 100644 index 000000000000..7b518eebfc05 --- /dev/null +++ b/ai/guides/tables.md @@ -0,0 +1,448 @@ +--- +title: 使用表 +summary: 了解如何在 TiDB 中使用表。 +--- + +# 使用表 + +TiDB 使用表来组织和存储相关数据集合。它提供了灵活的 schema 定义能力，因此你可以根据具体需求设计表结构。 + +一个表可以包含多个不同数据类型的列。支持的数据类型包括文本、数字、向量、二进制数据（`BLOB`）、JSON 等。 + +本文档展示了如何使用 [`pytidb`](https://github.com/pingcap/pytidb) 操作表。 + +`pytidb` 是 TiDB 官方的 Python SDK，旨在帮助开发者高效构建 AI 应用。 + +> **注意：** +> +> 完整的可运行示例请参见我们仓库中的 [basic example](https://github.com/pingcap/pytidb/tree/main/examples/basic)。 + +## 创建表 + +### 使用 TableModel + +`pytidb` 提供了一个 `TableModel` class，用于表示表的 schema。该 class 兼容 [Pydantic model](https://docs.pydantic.dev/latest/concepts/models/)，可以让你以声明式方式定义表。 + +在以下示例中，你将创建一个名为 `items` 的表，包含以下列： + +- `id`：主键列，整数型 +- `content`：文本类型列 +- `embedding`：3 维向量类型列 +- `meta`：JSON 类型列 + + +
+ +在你使用 `pytidb` [连接数据库](/ai/guides/connect.md) 并获取 `client` instance 后，可以通过 `create_table` method 创建表。 + +```python hl_lines="12" +from pytidb.schema import TableModel, Field, VectorField +from pytidb.datatype import TEXT, JSON + +class Item(TableModel): + __tablename__ = "items" + + id: int = Field(primary_key=True) + content: str = Field(sa_type=TEXT) + embedding: list[float] = VectorField(dimensions=3) + meta: dict = Field(sa_type=JSON, default_factory=dict) + +table = client.create_table(schema=Item, if_exists="overwrite") +``` + +`create_table` method 接受以下参数： + +- `schema`：定义表结构的 `TableModel` class。 +- `if_exists`：表创建模式。 + - `raise`（默认）：如果表不存在则创建；如果已存在则抛出错误。 + - `skip`：如果表不存在则创建；如果已存在则不做任何操作。 + - `overwrite`：删除已存在的表并新建。这适用于**测试和开发**，不建议在生产环境中使用。 + +表创建完成后，你可以使用 `table` 对象进行数据插入、修改、删除和查询。 + +
+
+ +使用 `CREATE TABLE` 语句创建表。 + +```sql +CREATE TABLE items ( + id INT PRIMARY KEY, + content TEXT, + embedding VECTOR(3), + meta JSON +); +``` + +
+ + +## 向表中添加数据 + +### 使用 TableModel + +你可以使用 `TableModel` instance 表示一行数据并插入到表中。 + +插入单条记录： + + +
+ +使用 `table.insert()` method 向表中插入单条记录。 + +```python +table.insert( + Item( + id=1, + content="TiDB is a distributed SQL database", + embedding=[0.1, 0.2, 0.3], + meta={"category": "database"}, + ) +) +``` + +
+
+ +使用 `INSERT INTO` 语句向表中插入单条记录。 + +```sql +INSERT INTO items(id, content, embedding, meta) +VALUES (1, 'TiDB is a distributed SQL database', '[0.1, 0.2, 0.3]', '{"category": "database"}'); +``` + +
+ + +插入多条记录： + + +
+ +使用 `table.bulk_insert()` method 向表中插入多条记录。 + +```python +table.bulk_insert([ + Item( + id=2, + content="GPT-4 is a large language model", + embedding=[0.4, 0.5, 0.6], + meta={"category": "llm"}, + ), + Item( + id=3, + content="LlamaIndex is a Python library for building AI-powered applications", + embedding=[0.7, 0.8, 0.9], + meta={"category": "rag"}, + ), +]) +``` + +
+
+ +使用 `INSERT INTO` 语句向表中插入多条记录。 + +```sql +INSERT INTO items(id, content, embedding, meta) +VALUES + (2, 'GPT-4 is a large language model', '[0.4, 0.5, 0.6]', '{"category": "llm"}'), + (3, 'LlamaIndex is a Python library for building AI-powered applications', '[0.7, 0.8, 0.9]', '{"category": "rag"}'); +``` + +
+ + +### 使用 Dict + +你也可以使用 `dict` 表示行并插入到表中。这种方式更灵活，无需定义 `TableModel` 即可插入数据。 + +插入单条记录： + + +
+ +使用 `table.insert()` method 并传入字典，向表中插入单条记录。 + +```python +table.insert({ + "id": 1, + "content": "TiDB is a distributed SQL database", + "embedding": [0.1, 0.2, 0.3], + "meta": {"category": "database"}, +}) +``` + +
+
+ +使用 `INSERT INTO` 语句向表中插入单条记录。 + +```sql +INSERT INTO items(id, content, embedding, meta) +VALUES (1, 'TiDB is a distributed SQL database', '[0.1, 0.2, 0.3]', '{"category": "database"}'); +``` + +
+ + +## 保存数据到表 + +`save` method 提供了一种便捷方式来插入或更新单行数据。对于一行数据，如果主键在表中不存在，则插入为新行；如果记录已存在，则覆盖整行数据。 + +> **注意：** +> +> 如果记录 ID 已存在于表中，`table.save()` 会覆盖整个记录。如需只修改部分字段，请使用 `table.update()`。 + + +
+ +使用 `table.save()` method 将单条记录保存到表中。 + +**示例：保存新记录** + +```python +saved_record = table.save( + Item( + id=4, + content="Vector databases enable AI applications", + embedding=[1.0, 1.1, 1.2], + meta={"category": "vector-db"}, + ) +) +``` + +**示例：保存已存在的记录（覆盖整行）** + +```python +# 这将覆盖 id=1 的整行记录 +updated_record = table.save( + Item( + id=1, # 已存在的 ID + content="Updated content for TiDB", + embedding=[0.2, 0.3, 0.4], + meta={"category": "updated"}, + ) +) +``` + +
+
+ +使用 `INSERT ... ON DUPLICATE KEY UPDATE` 语句保存记录。 + +**示例：保存新记录或已存在则更新** + +```sql +INSERT INTO items(id, content, embedding, meta) +VALUES (4, 'Vector databases enable AI applications', '[1.0, 1.1, 1.2]', '{"category": "vector-db"}') +ON DUPLICATE KEY UPDATE + content = VALUES(content), + embedding = VALUES(embedding), + meta = VALUES(meta; +``` + +
+ + +## 从表中查询数据 + +要从表中获取记录： + + +
+ +使用 `table.query()` method 从表中查询记录。 + +**示例：获取前 10 条记录** + +```python +result = table.query(limit=10).to_list() +``` + +
+
+ +使用 `SELECT` 语句从表中查询记录。 + +**示例：获取前 10 条记录** + +```sql +SELECT * FROM items LIMIT 10; +``` + +
+ + +根据查询条件获取记录： + + +
+ +将 `filters` 参数传递给 `table.query()` method。 + +```python +result = table.query( + filters={"meta.category": "database"}, + limit=10 +).to_list() +``` + +
+
+ +使用 `WHERE` 子句过滤记录。 + +**示例：获取 category 为 "database" 的 10 条记录** + +```sql +SELECT * FROM items WHERE meta->>'$.category' = 'database' LIMIT 10; +``` + +
+ + +完整的过滤操作及示例请参考 [Filtering](/ai/guides/filtering.md) 指南。 + +## 修改表中数据 + + +
+ +使用 `table.update()` method 结合 [filters](/ai/guides/filtering.md) 修改记录。 + +**示例：修改 `id` 等于 1 的记录** + +```python +table.update( + values={ + "content": "TiDB Cloud Starter is a fully managed, auto-scaling cloud database service", + "embedding": [0.1, 0.2, 0.4], + "meta": {"category": "dbaas"}, + }, + filters={ + "id": 1 + }, +) +``` + +
+
+ +使用 `UPDATE` 语句结合 [filters](/ai/guides/filtering.md) 修改记录。 + +**示例：修改 `id` 等于 1 的记录** + +```sql +UPDATE items +SET + content = 'TiDB Cloud Starter is a fully managed, auto-scaling cloud database service', + embedding = '[0.1, 0.2, 0.4]', + meta = '{"category": "dbaas"}' +WHERE + id = 1; +``` + +
+ + +## 从表中删除数据 + + +
+ +使用 `table.delete()` method 结合 [filters](/ai/guides/filtering.md) 删除记录。 + +**示例：删除 `id` 等于 2 的记录** + +```python +table.delete( + filters={ + "id": 2 + } +) +``` + +
+
+ +使用 `DELETE` 语句结合 [filters](/ai/guides/filtering.md) 删除记录。 + +**示例：删除 `id` 等于 2 的记录** + +```sql +DELETE FROM items WHERE id = 2; +``` + +
+ + +## 清空表 + + +
+ +如需删除表中所有数据但保留表结构，可使用 `table.truncate()` method。 + +```python +table.truncate() +``` + +你可以通过验证表中行数为 0 来确认表已被清空。 + +```python +table.rows() +``` + +
+
+ +如需删除表中所有数据但保留表结构，可使用 `TRUNCATE TABLE` 语句。 + +```sql +TRUNCATE TABLE items; +``` + +你可以通过验证表中行数为 0 来确认表已被清空。 + +```sql +SELECT COUNT(*) FROM items; +``` + +
+ + +## 删除表 + + +
+ +如需永久从数据库中删除表，可使用 `client.drop_table()` method。 + +```python +client.drop_table("items") +``` + +你可以通过以下方式验证表已从数据库中移除： + +```python +client.table_names() +``` + +
+
+ +如需永久从数据库中删除表，可使用 `DROP TABLE` 语句。 + +```sql +DROP TABLE items; +``` + +你可以通过以下方式验证表已从数据库中移除： + +```sql +SHOW TABLES; +``` + +
+ \ No newline at end of file diff --git a/ai/guides/transactions.md b/ai/guides/transactions.md new file mode 100644 index 000000000000..3a4a5a013e19 --- /dev/null +++ b/ai/guides/transactions.md @@ -0,0 +1,30 @@ +--- +title: 事务 +summary: 了解如何在你的应用中使用事务。 +--- + +# 事务 + +TiDB 支持 ACID 事务，以确保数据一致性和可靠性。 + +## 基本用法 + +```python +with client.session() as session: + initial_total_balance = session.query("SELECT SUM(balance) FROM players").scalar() + + # Transfer 10 coins from player 1 to player 2 + session.execute("UPDATE players SET balance = balance - 10 WHERE id = 1") + session.execute("UPDATE players SET balance = balance + 10 WHERE id = 2") + + session.commit() + # or session.rollback() + + final_total_balance = session.query("SELECT SUM(balance) FROM players").scalar() + assert final_total_balance == initial_total_balance +``` + +## 另请参阅 + +- [TiDB Developer Guide - Transactions](/develop/dev-guide-transaction-overview.md) +- [TiDB Documentation - SQL Reference - Transactions](/transaction-overview.md) \ No newline at end of file diff --git a/ai/guides/vector-search-full-text-search-python.md b/ai/guides/vector-search-full-text-search-python.md new file mode 100644 index 000000000000..0206dbc60b8a --- /dev/null +++ b/ai/guides/vector-search-full-text-search-python.md @@ -0,0 +1,163 @@ +--- +title: 使用 Python 进行全文搜索 +summary: 全文搜索允许你通过精确关键字搜索文档。在检索增强生成（RAG）场景中，你可以将全文搜索与向量搜索结合使用，以提升搜索质量。 +aliases: ['/zh/tidbcloud/vector-search-full-text-search-python/'] +--- + +# 使用 Python 进行全文搜索 + +与关注语义相似度的 [向量搜索](/ai/concepts/vector-search-overview.md) 不同，全文搜索允许你通过精确关键字搜索文档。在检索增强生成（RAG）场景中，你可以将全文搜索与向量搜索结合使用，以提升搜索质量。 + +TiDB 的全文搜索功能提供以下能力： + +- **直接查询文本数据**：你可以直接搜索任意 string 列，无需进行 embedding 过程。 + +- **支持多语言**：无需指定语言即可获得高质量搜索。TiDB 支持在同一张表中存储多种语言的文档，并会为每个文档自动选择最佳文本分析器。 + +- **按相关性排序**：搜索结果可通过被广泛采用的 [BM25 排序](https://en.wikipedia.org/wiki/Okapi_BM25) algorithm 按相关性排序。 + +- **完全兼容 SQL**：所有 SQL 功能，如预过滤、后过滤、分组和关联查询等，都可与全文搜索结合使用。 + +> **提示：** +> +> 有关 SQL 用法，参见 [使用 SQL 进行全文搜索](/ai/guides/vector-search-full-text-search-sql.md)。 +> +> 如需在 AI 应用中同时使用全文搜索和向量搜索，参见 [混合搜索](/ai/guides/vector-search-hybrid-search.md)。 + +## 前提条件 + +全文搜索仍处于早期阶段，我们正在持续向更多用户开放。目前，全文搜索仅在以下区域的 TiDB Cloud Starter 和 TiDB Cloud Essential 上可用： + +- AWS: `法兰克福 (eu-central-1)` 和 `新加坡 (ap-southeast-1)` + +要完成本教程，请确保你在支持的区域拥有一个 TiDB Cloud Starter 集群。如果还没有，请按照 [创建 TiDB Cloud Starter 集群](/develop/dev-guide-build-cluster-in-cloud.md) 创建。 + +## 快速开始 + +### 步骤 1. 安装 [pytidb](https://github.com/pingcap/pytidb) Python SDK + +[pytidb](https://github.com/pingcap/pytidb) 是 TiDB 官方的 Python SDK，旨在帮助开发者高效构建 AI 应用。该 SDK 内置支持向量搜索和全文搜索。 + +安装 SDK，请运行以下命令： + +```shell +pip install pytidb + +# （可选）如需使用内置 embedding 函数和 reranker： +# pip install "pytidb[models]" + +# （可选）如需将查询结果转换为 pandas DataFrame： +# pip install pandas +``` + +### 步骤 2. 连接 TiDB + +```python +from pytidb import TiDBClient + +db = TiDBClient.connect( + host="HOST_HERE", + port=4000, + username="USERNAME_HERE", + password="PASSWORD_HERE", + database="DATABASE_HERE", +) +``` + +你可以通过以下方式在 [TiDB Cloud 控制台](https://tidbcloud.com) 获取这些连接参数： + +1. 进入 [**Clusters**](https://tidbcloud.com/project/clusters) 页面，点击目标集群名称进入其概览页面。 + +2. 点击右上角的 **Connect**。此时会弹出连接对话框，显示连接参数。 + + 例如，连接参数如下所示： + + ```text + HOST: gateway01.us-east-1.prod.shared.aws.tidbcloud.com + PORT: 4000 + USERNAME: 4EfqPF23YKBxaQb.root + PASSWORD: abcd1234 + DATABASE: test + CA: /etc/ssl/cert.pem + ``` + + 对应的 Python 代码如下，用于连接 TiDB Cloud Starter 集群： + + ```python + db = TiDBClient.connect( + host="gateway01.us-east-1.prod.shared.aws.tidbcloud.com", + port=4000, + username="4EfqPF23YKBxaQb.root", + password="abcd1234", + database="test", + ) + ``` + + 注意，上述示例仅用于演示。你需要用自己的参数替换，并妥善保管这些信息。 + +### 步骤 3. 创建表和全文索引 + +例如，创建一个名为 `chunks` 的表，包含以下列： + +- `id` (int)：chunk 的 ID。 +- `text` (text)：chunk 的文本内容。 +- `user_id` (int)：创建该 chunk 的用户 ID。 + +```python +from pytidb.schema import TableModel, Field + +class Chunk(TableModel, table=True): + __tablename__ = "chunks" + + id: int = Field(primary_key=True) + text: str = Field() + user_id: int = Field() + +table = db.create_table(schema=Chunk) + +if not table.has_fts_index("text"): + table.create_fts_index("text") # 👈 在 text 列上创建全文索引。 +``` + +### 步骤 4. 插入数据 + +```python +table.bulk_insert( + [ + Chunk(id=2, text="the quick brown", user_id=2), + Chunk(id=3, text="fox jumps", user_id=3), + Chunk(id=4, text="over the lazy dog", user_id=4), + ] +) +``` + +### 步骤 5. 执行全文搜索 + +插入数据后，你可以按如下方式执行全文搜索： + +```python +df = ( + table.search("brown fox", search_type="fulltext") + .limit(2) + .to_pandas() # optional +) + +# id text user_id +# 0 3 fox jumps 3 +# 1 2 the quick brown 2 +``` + +完整示例参见 [pytidb 全文搜索演示](https://github.com/pingcap/pytidb/blob/main/examples/fulltext_search)。 + +## 另请参阅 + +- [pytidb Python SDK 文档](https://github.com/pingcap/pytidb) + +- [混合搜索](/ai/guides/vector-search-hybrid-search.md) + +## 反馈与帮助 + +全文搜索仍处于早期阶段，开放范围有限。如果你希望在尚未开放的区域体验全文搜索，或有任何反馈和帮助需求，欢迎联系我们： + +- 在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问。 +- [提交 TiDB Cloud 支持工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) \ No newline at end of file diff --git a/ai/guides/vector-search-full-text-search-sql.md b/ai/guides/vector-search-full-text-search-sql.md new file mode 100644 index 000000000000..e1f6f40c1d59 --- /dev/null +++ b/ai/guides/vector-search-full-text-search-sql.md @@ -0,0 +1,210 @@ +--- +title: 使用 SQL 进行全文搜索 +summary: 全文搜索允许你根据精确关键字搜索文档。在检索增强生成（RAG）场景中，你可以将全文搜索与向量搜索结合使用，以提升搜索质量。 +aliases: ['/zh/tidbcloud/vector-search-full-text-search-sql/'] +--- + +# 使用 SQL 进行全文搜索 + +与关注语义相似度的 [向量搜索](/ai/concepts/vector-search-overview.md) 不同，全文搜索允许你根据精确关键字搜索文档。在检索增强生成（RAG）场景中，你可以将全文搜索与向量搜索结合使用，以提升搜索质量。 + +TiDB 的全文搜索功能提供以下能力： + +- **直接查询文本数据**：你可以直接在任意 string 列上进行搜索，无需 embedding 过程。 + +- **支持多语言**：无需指定语言即可获得高质量搜索。TiDB 的文本分析器支持同一张表中多种语言混合的文档，并会自动为每个文档选择最佳分析器。 + +- **按相关性排序**：搜索结果可通过广泛采用的 [BM25 排序](https://en.wikipedia.org/wiki/Okapi_BM25) algorithm 按相关性排序。 + +- **完全兼容 SQL**：所有 SQL 功能，如预过滤、后过滤、分组和 join，都可与全文搜索结合使用。 + +> **提示：** +> +> 如需在 Python 中使用，请参见 [使用 Python 进行全文搜索](/ai/guides/vector-search-full-text-search-python.md)。 +> +> 如需在 AI 应用中同时使用全文搜索和向量搜索，请参见 [混合搜索](/ai/guides/vector-search-hybrid-search.md)。 + +## 快速开始 + +全文搜索仍处于早期阶段，我们正在持续向更多用户开放。目前，全文搜索仅在以下区域的 TiDB Cloud Starter 和 TiDB Cloud Essential 上可用： + +- AWS: `Frankfurt (eu-central-1)` 和 `Singapore (ap-southeast-1)` + +在使用全文搜索前，请确保你的 TiDB Cloud Starter 集群已创建在支持的区域。如果还没有，请按照 [创建 TiDB Cloud Starter 集群](/develop/dev-guide-build-cluster-in-cloud.md) 进行创建。 + +要进行全文搜索，请按照以下步骤操作： + +1. [**创建全文索引**](#创建全文索引)：创建带有全文索引的表，或为已有表添加全文索引。 + +2. [**插入文本数据**](#插入文本数据)：向表中插入文本数据。 + +3. [**执行全文搜索**](#执行全文搜索)：使用文本查询和全文搜索函数进行全文搜索。 + +### 创建全文索引 + +要进行全文搜索，需要创建全文索引，它为高效搜索和排序提供必要的数据结构。全文索引既可以在新表上创建，也可以添加到已有表上。 + +创建带有全文索引的表： + +```sql +CREATE TABLE stock_items( + id INT, + title TEXT, + FULLTEXT INDEX (title) WITH PARSER MULTILINGUAL +); +``` + +或为已有表添加全文索引： + +```sql +CREATE TABLE stock_items( + id INT, + title TEXT +); + +-- 你可以在这里插入一些数据。 +-- 即使表中已有数据，也可以创建全文索引。 + +ALTER TABLE stock_items ADD FULLTEXT INDEX (title) WITH PARSER MULTILINGUAL ADD_COLUMNAR_REPLICA_ON_DEMAND; +``` + +`WITH PARSER ` 子句中可用的 parser 包括： + +- `STANDARD`：速度快，适用于英文内容，通过空格和标点切分单词。 + +- `MULTILINGUAL`：支持多种语言，包括英文、中文、日文和韩文。 + +### 插入文本数据 + +向带有全文索引的表插入数据，与向其他表插入数据完全相同。 + +例如，你可以执行以下 SQL 语句插入多语言数据。TiDB 的多语言 parser 会自动处理文本。 + +```sql +INSERT INTO stock_items VALUES (1, "イヤホン bluetooth ワイヤレスイヤホン "); +INSERT INTO stock_items VALUES (2, "完全ワイヤレスイヤホン/ウルトラノイズキャンセリング 2.0 "); +INSERT INTO stock_items VALUES (3, "ワイヤレス ヘッドホン Bluetooth 5.3 65時間再生 ヘッドホン 40mm HD "); +INSERT INTO stock_items VALUES (4, "楽器用 オンイヤーヘッドホン 密閉型【国内正規品】"); +INSERT INTO stock_items VALUES (5, "ワイヤレスイヤホン ハイブリッドANC搭載 40dBまでアクティブノイズキャンセル"); +INSERT INTO stock_items VALUES (6, "Lightweight Bluetooth Earbuds with 48 Hours Playtime"); +INSERT INTO stock_items VALUES (7, "True Wireless Noise Cancelling Earbuds - Compatible with Apple & Android, Built-in Microphone"); +INSERT INTO stock_items VALUES (8, "In-Ear Earbud Headphones with Mic, Black"); +INSERT INTO stock_items VALUES (9, "Wired Headphones, HD Bass Driven Audio, Lightweight Aluminum Wired in Ear Earbud Headphones"); +INSERT INTO stock_items VALUES (10, "LED Light Bar, Music Sync RGB Light Bar, USB Ambient Lamp"); +INSERT INTO stock_items VALUES (11, "无线消噪耳机-黑色 手势触控蓝牙降噪 主动降噪头戴式耳机（智能降噪 长久续航）"); +INSERT INTO stock_items VALUES (12, "专业版USB7.1声道游戏耳机电竞耳麦头戴式电脑网课办公麦克风带线控"); +INSERT INTO stock_items VALUES (13, "投影仪家用智能投影机便携卧室手机投影"); +INSERT INTO stock_items VALUES (14, "无线蓝牙耳机超长续航42小时快速充电 流光金属耳机"); +INSERT INTO stock_items VALUES (15, "皎月银 国家补贴 心率血氧监测 蓝牙通话 智能手表 男女表"); +``` + +### 执行全文搜索 + +要执行全文搜索，可以使用 `FTS_MATCH_WORD()` function。 + +**示例：搜索最相关的 10 个文档** + +```sql +SELECT * FROM stock_items + WHERE fts_match_word("bluetoothイヤホン", title) + ORDER BY fts_match_word("bluetoothイヤホン", title) + DESC LIMIT 10; + +-- 结果按相关性排序，最相关的文档排在最前面。 + ++------+-----------------------------------------------------------------------------------------------------------+ +| id | title | ++------+-----------------------------------------------------------------------------------------------------------+ +| 1 | イヤホン bluetooth ワイヤレスイヤホン | +| 6 | Lightweight Bluetooth Earbuds with 48 Hours Playtime | +| 2 | 完全ワイヤレスイヤホン/ウルトラノイズキャンセリング 2.0 | +| 3 | ワイヤレス ヘッドホン Bluetooth 5.3 65時間再生 ヘッドホン 40mm HD | +| 5 | ワイヤレスイヤホン ハイブリッドANC搭載 40dBまでアクティブノイズキャンセル | ++------+-----------------------------------------------------------------------------------------------------------+ + +-- 尝试用另一种语言搜索： +SELECT * FROM stock_items + WHERE fts_match_word("蓝牙耳机", title) + ORDER BY fts_match_word("蓝牙耳机", title) + DESC LIMIT 10; + +-- 结果按相关性排序，最相关的文档排在最前面。 + ++------+---------------------------------------------------------------------------------------------------------------+ +| id | title | ++------+---------------------------------------------------------------------------------------------------------------+ +| 14 | 无线蓝牙耳机超长续航42小时快速充电 流光金属耳机 | +| 11 | 无线消噪耳机-黑色 手势触控蓝牙降噪 主动降噪头戴式耳机（智能降噪 长久续航） | +| 15 | 皎月银 国家补贴 心率血氧监测 蓝牙通话 智能手表 男女表 | ++------+---------------------------------------------------------------------------------------------------------------+ +``` + +**示例：统计匹配用户查询的文档数量** + +```sql +SELECT COUNT(*) FROM stock_items + WHERE fts_match_word("bluetoothイヤホン", title); + ++----------+ +| COUNT(*) | ++----------+ +| 5 | ++----------+ +``` + +## 高级示例：与其他表 join 搜索结果 + +你可以将全文搜索与其他 SQL 功能（如 join 和子查询）结合使用。 + +假设你有一张 `users` 表和一张 `tickets` 表，并希望基于作者姓名的全文搜索结果查找其创建的工单： + +```sql +CREATE TABLE users( + id INT, + name TEXT, + FULLTEXT INDEX (name) WITH PARSER STANDARD +); + +INSERT INTO users VALUES (1, "Alice Smith"); +INSERT INTO users VALUES (2, "Bob Johnson"); + +CREATE TABLE tickets( + id INT, + title TEXT, + author_id INT +); + +INSERT INTO tickets VALUES (1, "Ticket 1", 1); +INSERT INTO tickets VALUES (2, "Ticket 2", 1); +INSERT INTO tickets VALUES (3, "Ticket 3", 2); +``` + +你可以使用子查询根据作者姓名查找匹配的用户 ID，然后在外层查询中使用这些 ID 搜索并 join 相关工单信息： + +```sql +SELECT t.title AS TICKET_TITLE, u.id AS AUTHOR_ID, u.name AS AUTHOR_NAME FROM tickets t +LEFT JOIN users u ON t.author_id = u.id +WHERE t.author_id IN +( + SELECT id FROM users + WHERE fts_match_word("Alice", name) +); + ++--------------+-----------+-------------+ +| TICKET_TITLE | AUTHOR_ID | AUTHOR_NAME | ++--------------+-----------+-------------+ +| Ticket 1 | 1 | Alice Smith | +| Ticket 2 | 1 | Alice Smith | ++--------------+-----------+-------------+ +``` + +## 另请参阅 + +- [混合搜索](/ai/guides/vector-search-hybrid-search.md) + +## 反馈与帮助 + +全文搜索仍处于早期阶段，开放区域有限。如果你希望在尚未开放的区域体验全文搜索，或有任何反馈与帮助需求，欢迎联系我们： + +- 在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问。 +- [提交 TiDB Cloud 支持工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) diff --git a/ai/guides/vector-search-hybrid-search.md b/ai/guides/vector-search-hybrid-search.md new file mode 100644 index 000000000000..68dc9297ee08 --- /dev/null +++ b/ai/guides/vector-search-hybrid-search.md @@ -0,0 +1,247 @@ +--- +title: 混合搜索 +summary: 同时使用全文搜索和向量搜索，以提升搜索质量。 +aliases: ['/zh/tidbcloud/vector-search-hybrid-search/'] +--- + +# 混合搜索 + +通过使用全文搜索，你可以基于精确关键字搜索文档。通过使用向量搜索，你可以基于语义相似性搜索文档。我们能否将这两种搜索方法结合起来，以提升搜索质量并应对更多场景？答案是肯定的，这种方法被称为混合搜索（hybrid search），并在 AI 应用中被广泛采用。 + +在 TiDB 中，混合搜索的一般工作流程如下： + +1. 使用 TiDB 进行**全文搜索**和**向量搜索**。 +2. 使用**重排序器**（reranker）将两种搜索的结果进行融合。 + +![Hybrid Search](/media/vector-search/hybrid-search-overview.svg) + +本教程演示如何在 TiDB 中使用 [pytidb](https://github.com/pingcap/pytidb) Python SDK 实现混合搜索，该 SDK 内置了 embedding 和重排序支持。使用 pytidb 并非强制要求——你也可以直接使用 SQL 进行搜索，并根据需要使用自定义的重排序模型。 + +## 前提条件 + +全文搜索目前仍处于早期阶段，我们正在持续向更多用户开放。目前，全文搜索仅在以下区域的 TiDB Cloud Starter 和 TiDB Cloud Essential 上可用： + +- AWS: `Frankfurt (eu-central-1)` 和 `Singapore (ap-southeast-1)` + +要完成本教程，请确保你在受支持的区域拥有一个 TiDB Cloud Starter 集群。如果还没有，请参阅[创建 TiDB Cloud Starter 集群](/develop/dev-guide-build-cluster-in-cloud.md)进行创建。 + +## 快速开始 + +### 步骤 1. 安装 [pytidb](https://github.com/pingcap/pytidb) Python SDK + +```shell +pip install "pytidb[models]" + +# （可选）如果你不想使用内置 embedding 函数和重排序器： +# pip install pytidb + +# （可选）如需将查询结果转换为 pandas DataFrame： +# pip install pandas +``` + +### 步骤 2. 连接 TiDB + +```python +from pytidb import TiDBClient + +db = TiDBClient.connect( + host="HOST_HERE", + port=4000, + username="USERNAME_HERE", + password="PASSWORD_HERE", + database="DATABASE_HERE", +) +``` + +你可以通过以下方式在 [TiDB Cloud 控制台](https://tidbcloud.com) 获取这些连接参数： + +1. 进入 [**Clusters**](https://tidbcloud.com/project/clusters) 页面，然后点击目标集群名称，进入其概览页面。 + +2. 点击右上角的 **Connect**。此时会弹出连接对话框，显示连接参数。 + + 例如，连接参数如下所示： + + ```text + HOST: gateway01.us-east-1.prod.shared.aws.tidbcloud.com + PORT: 4000 + USERNAME: 4EfqPF23YKBxaQb.root + PASSWORD: abcd1234 + DATABASE: test + CA: /etc/ssl/cert.pem + ``` + + 连接到 TiDB Cloud Starter 集群的 Python 代码如下： + + ```python + db = TiDBClient.connect( + host="gateway01.us-east-1.prod.shared.aws.tidbcloud.com", + port=4000, + username="4EfqPF23YKBxaQb.root", + password="abcd1234", + database="test", + ) + ``` + + 注意，上述示例仅用于演示。你需要用自己的参数替换，并妥善保管这些信息。 + +### 步骤 3. 创建表 + +以创建名为 `chunks` 的表为例，包含以下字段： + +- `id`（int）：chunk 的 ID。 +- `text`（text）：chunk 的文本内容。 +- `text_vec`（vector）：文本的向量表示，由 pytidb 中的 embedding model 自动生成。 +- `user_id`（int）：创建该 chunk 的用户 ID。 + +```python +from pytidb.schema import TableModel, Field +from pytidb.embeddings import EmbeddingFunction + +text_embed = EmbeddingFunction("openai/text-embedding-3-small") + +class Chunk(TableModel, table=True): + __tablename__ = "chunks" + + id: int = Field(primary_key=True) + text: str = Field() + text_vec: list[float] = text_embed.VectorField( + source_field="text" + ) # 👈 定义向量字段。 + user_id: int = Field() + +table = db.create_table(schema=Chunk) +``` + +### 步骤 4. 插入数据 + +```python +table.bulk_insert( + [ + Chunk(id=2, text="bar", user_id=2), # 👈 text 字段会被自动 embedding， + Chunk(id=3, text="baz", user_id=3), # 并以向量形式存储到 "text_vec" 字段 + Chunk(id=4, text="qux", user_id=4), # 中。 + ] +) +``` + +### 步骤 5. 执行混合搜索 + +本例中，使用 [jina-reranker](https://huggingface.co/jinaai/jina-reranker-m0) 模型对搜索结果进行重排序。 + +```python +from pytidb.rerankers import Reranker + +jinaai = Reranker(model_name="jina_ai/jina-reranker-m0") + +df = ( + table.search("", search_type="hybrid") + .rerank(jinaai, "text") # 👈 使用 jinaai 模型对查询结果重排序。 + .limit(2) + .to_pandas() +) +``` + +完整示例请参见 [pytidb hybrid search demo](https://github.com/pingcap/pytidb/tree/main/examples/hybrid_search)。 + +## 融合方法 + +融合方法将向量（语义）搜索和全文（关键字）搜索的结果合并为统一的排序结果。这确保最终结果既考虑语义相关性，也兼顾关键字匹配。 + +`pytidb` 支持两种融合方法： + +- `rrf`：倒数排名融合（Reciprocal Rank Fusion，默认） +- `weighted`：加权分数融合 + +你可以根据实际场景选择最适合的融合方法，以优化混合搜索结果。 + +### 倒数排名融合（RRF） + +倒数排名融合（Reciprocal Rank Fusion，RRF）是一种利用文档在多个结果集中的排名来评估搜索结果的算法。 + +详细信息请参见 [RRF 论文](https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf)。 + +通过在 `.fusion()` 方法中将 `method` 参数指定为 `"rrf"`，即可启用倒数排名融合。 + +```python +results = ( + table.search( + "AI database", search_type="hybrid" + ) + .fusion(method="rrf") + .limit(3) + .to_list() +) +``` + +参数说明： + +- `k`：常数（默认值：60），用于防止除零错误，并控制高排名文档的影响。 + +### 加权分数融合 + +加权分数融合通过加权求和的方式，将向量搜索和全文搜索的分数结合起来： + +```python +final_score = vs_weight * vector_score + fts_weight * fulltext_score +``` + +通过在 `.fusion()` 方法中将 `method` 参数指定为 `"weighted"`，即可启用加权分数融合。 + +例如，如需让向量搜索权重更高，可将 `vs_weight` 设置为 0.7，`fts_weight` 设置为 0.3： + +```python +results = ( + table.search( + "AI database", search_type="hybrid" + ) + .fusion(method="weighted", vs_weight=0.7, fts_weight=0.3) + .limit(3) + .to_list() +) +``` + +参数说明： + +- `vs_weight`：向量搜索分数的权重。 +- `fts_weight`：全文搜索分数的权重。 + +## 重排序方法 + +混合搜索还支持使用特定模型进行重排序。 + +通过 `rerank()` 方法，可以指定重排序器，根据 query 与文档之间的相关性对搜索结果进行排序。 + +**示例：使用 Jina AI Reranker 对混合搜索结果重排序** + +```python +reranker = Reranker( + # 使用 `jina-reranker-m0` 模型 + model_name="jina_ai/jina-reranker-m0", + api_key="{your-jinaai-api-key}" +) + +results = ( + table.search( + "AI database", search_type="hybrid" + ) + .fusion(method="rrf", k=60) + .rerank(reranker, "text") + .limit(3) + .to_list() +) +``` + +如需查看更多重排序模型，请参见 [Reranking](/ai/guides/reranking.md)。 + +## 另请参阅 + +- [pytidb Python SDK 文档](https://github.com/pingcap/pytidb) + +- [使用 Python 进行全文搜索](/ai/guides/vector-search-full-text-search-python.md) + +## 反馈与帮助 + +全文搜索目前仍处于早期阶段，开放范围有限。如果你希望在尚未开放的区域体验全文搜索，或有任何反馈或需要帮助，欢迎联系我们： + +- 在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问。 +- [提交 TiDB Cloud 支持工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) diff --git a/ai/guides/vector-search.md b/ai/guides/vector-search.md new file mode 100644 index 000000000000..932fa43cec65 --- /dev/null +++ b/ai/guides/vector-search.md @@ -0,0 +1,505 @@ +--- +title: 向量搜索 +summary: 了解如何在你的应用中使用向量搜索。 +--- + +# 向量搜索 + +向量搜索利用语义相似性，帮助你找到最相关的记录，即使你的查询没有明确包含所有关键字。 + +> **注意：** +> +> 有关向量搜索的完整示例，请参见 [向量搜索示例](/ai/examples/vector-search-with-pytidb.md)。 + +## 基本用法 + +本节展示了如何通过几个简单步骤在你的应用中使用向量搜索。在开始之前，你需要先[连接到数据库](/ai/guides/connect.md)。 + +### 步骤 1. 创建包含向量字段的表 + + +
+ +你可以使用 `client.create_table()` 创建表，并用 `VectorField` 定义向量字段。 + +以下示例创建了一个包含四个列的 `documents` 表： + +- `id`：表的主键。 +- `text`：文档的文本内容。 +- `text_vec`：文本内容的向量嵌入。 +- `meta`：文档的元信息，是一个 JSON 对象。 + +```python hl_lines="9" +from pytidb.schema import TableModel, Field, VectorField +from pytidb.datatype import TEXT, JSON + +class Document(TableModel): + __tablename__ = "documents" + + id: int = Field(primary_key=True) + text: str = Field(sa_type=TEXT) + text_vec: list[float] = VectorField(dimensions=3) + meta: dict = Field(sa_type=JSON, default_factory=dict) + +table = client.create_table(schema=Document, if_exists="overwrite") +``` + +`VectorField` 类接受以下参数： + +- `dimensions`：向量的维度。指定后，该字段只能存储具有该精确维度的向量。 +- `index`：是否为该向量字段创建[向量索引](https://docs.pingcap.com/tidbcloud/vector-search-index/)。默认为 `True`。 +- `distance_metric`：用于向量索引的距离度量。支持的取值： + - `DistanceMetric.COSINE`（默认）：余弦距离度量，适合衡量文本相似性 + - `DistanceMetric.L2`：L2 距离度量，适合衡量整体差异 + +
+
+ +使用 `CREATE TABLE` 语句创建表，并用 `VECTOR` 类型定义向量列。 + +```sql hl_lines="4 5" +CREATE TABLE documents ( + id INT PRIMARY KEY, + text TEXT, + text_vec VECTOR(3), + VECTOR INDEX `vec_idx_text_vec`((VEC_COSINE_DISTANCE(`text_vec`))) +); +``` + +在本示例中： + +- `text_vec` 列被定义为 `VECTOR(3)`，因此存储在该列的向量必须为 3 维。 +- 使用 `VEC_COSINE_DISTANCE` 函数创建了向量索引，以优化向量搜索性能。 + +TiDB 支持两种用于向量索引的距离函数： + +- `VEC_COSINE_DISTANCE`：计算两个向量的余弦距离 +- `VEC_L2_DISTANCE`：计算两个向量的 L2 距离（欧氏距离） + +
+ + +### 步骤 2. 向表中插入向量数据 + +为了演示，向表中插入一些文本及其对应的嵌入向量。 + +以下示例插入了三条文档记录，每条都带有一个简单的 3 维向量嵌入： + +- `dog` 的向量嵌入为 `[1, 2, 1]` +- `fish` 的向量嵌入为 `[1, 2, 4]` +- `tree` 的向量嵌入为 `[1, 0, 0]` + + +
+ +```python +table.bulk_insert([ + Document(text="dog", text_vec=[1,2,1], meta={"category": "animal"}), + Document(text="fish", text_vec=[1,2,4], meta={"category": "animal"}), + Document(text="tree", text_vec=[1,0,0], meta={"category": "plant"}), +]) +``` + +
+
+ +```sql +INSERT INTO documents (id, text, text_vec, meta) +VALUES + (1, 'dog', '[1,2,1]', '{"category": "animal"}'), + (2, 'fish', '[1,2,4]', '{"category": "animal"}'), + (3, 'tree', '[1,0,0]', '{"category": "plant"}'); +``` + +> **注意：** +> +> 在实际应用中，嵌入通常由[嵌入模型](/ai/concepts/vector-search-overview.md#embedding-model)生成。 + +为方便起见，pytidb 提供了 Auto Embedding 功能，可以在插入、修改或查询时自动为你的文本字段生成向量嵌入，无需手动处理。 + +详细信息请参见 [Auto Embedding](/ai/guides/auto-embedding.md) 指南。 + +
+ + +### 步骤 3. 执行向量搜索 + +向量搜索使用向量距离度量来衡量向量之间的相似性和相关性。距离越近，记录越相关。要在表中查找最相关的文档，你需要指定一个查询向量。 + +以下示例假设查询为 `A swimming animal`，其向量嵌入为 `[1, 2, 3]`。 + + +
+ +使用 `table.search()` 方法执行向量搜索。默认使用 `search_mode="vector"`。 + +```python +table.search([1, 2, 3]).limit(3).to_list() +``` + +```python title="执行结果" +[ + {"id": 2, "text": "fish", "text_vec": [1,2,4], "_distance": 0.00853986601633272}, + {"id": 1, "text": "dog", "text_vec": [1,2,1], "_distance": 0.12712843905603044}, + {"id": 3, "text": "tree", "text_vec": [1,0,0], "_distance": 0.7327387580875756}, +] +``` + +结果显示，最相关的文档是 `fish`，其距离为 `0.00853986601633272`。 + +
+
+ +在 `SELECT` 语句中使用 `ORDER BY (, ) LIMIT ` 子句，可以获取查询向量的 n 个最近邻。 + +以下示例使用 `vec_cosine_distance` 函数计算 `text_vec` 列中存储的向量与提供的查询向量 `[1, 2, 3]` 之间的余弦距离。 + +```sql +SELECT id, text, vec_cosine_distance(text_vec, '[1,2,3]') AS distance +FROM documents +ORDER BY distance +LIMIT 3; +``` + +```plain title="执行结果" ++----+----------+---------------------+ +| id | text | distance | ++----+----------+---------------------+ +| 2 | fish | 0.00853986601633272 | +| 1 | dog | 0.12712843905603044 | +| 3 | tree | 0.7327387580875756 | ++----+----------+---------------------+ +3 rows in set (0.15 sec) +``` + +结果显示，最相关的文档是 `fish`，其距离为 `0.00853986601633272`。 + +
+ + +## 距离度量 + +距离度量用于衡量一对向量之间的相似性。目前，TiDB 支持以下距离度量： + + +
+ +`table.search()` API 支持以下距离度量： + +| 度量名称 | 描述 | 最佳应用场景 | +|--------------------------|---------------------------------------------------------------------|--------------| +| `DistanceMetric.COSINE` | 计算两个向量的余弦距离（默认）。衡量向量之间的夹角。 | 文本嵌入、语义搜索 | +| `DistanceMetric.L2` | 计算两个向量的 L2 距离（欧氏距离）。衡量直线距离。 | 图像特征 | + +要更改向量搜索使用的距离度量，可使用 `.distance_metric()` 方法。 + +**示例：使用 L2 距离度量** + +```python +from pytidb.schema import DistanceMetric + +results = ( + table.search([1, 2, 3]) + .distance_metric(DistanceMetric.L2) + .limit(10) + .to_list() +) +``` + +
+
+ +在 SQL 中，你可以在查询中直接使用以下内置函数计算向量距离： + +| 函数名称 | 描述 | +|--------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------| +| [`VEC_L2_DISTANCE`](https://docs.pingcap.com/tidbcloud/vector-search-functions-and-operators/#vec_l2_distance) | 计算两个向量的 L2 距离（欧氏距离） | +| [`VEC_COSINE_DISTANCE`](https://docs.pingcap.com/tidbcloud/vector-search-functions-and-operators/#vec_cosine_distance) | 计算两个向量的余弦距离 | +| [`VEC_NEGATIVE_INNER_PRODUCT`](https://docs.pingcap.com/tidbcloud/vector-search-functions-and-operators/#vec_negative_inner_product) | 计算两个向量的内积的相反数 | +| [`VEC_L1_DISTANCE`](https://docs.pingcap.com/tidbcloud/vector-search-functions-and-operators/#vec_l1_distance) | 计算两个向量的 L1 距离（曼哈顿距离） | + +
+ + +## 距离阈值 + +`table.search()` API 允许你设置距离阈值，以控制返回结果的相似性。通过指定该阈值，你可以排除不够相似的向量，仅返回满足相关性标准的结果。 + + +
+ +使用 `.distance_threshold()` 方法为搜索结果设置最大距离。只有距离小于该阈值的记录才会被返回。 + +**示例：仅返回距离小于 0.5 的文档** + +```python +results = table.search([1, 2, 3]).distance_threshold(0.5).limit(10).to_list() +``` + +
+
+ +在 SQL 中，使用带有距离函数的 `HAVING` 子句按距离过滤结果： + +**示例：仅返回距离小于 0.1 的文档** + +```sql +SELECT id, text, vec_cosine_distance(text_vec, '[1,2,3]') AS distance +FROM documents +HAVING distance < 0.1 +ORDER BY distance +LIMIT 10; +``` + +
+ + +## 距离范围 + +`table.search()` API 还支持指定距离范围，以进一步细化结果。 + + +
+ +使用 `.distance_range()` 方法同时设置最小和最大距离值。只有距离在该范围内的记录才会被返回。 + +**示例：仅返回距离在 0.01 到 0.05 之间的文档** + +```python +results = table.search([1, 2, 3]).distance_range(0.01, 0.05).limit(10).to_list() +``` + +
+
+ +在 SQL 中，可在 `HAVING` 子句中使用 `BETWEEN` 或其他比较运算符指定距离范围： + +**示例：仅返回距离在 0.01 到 0.05 之间的文档** + +```sql +SELECT id, text, vec_l2_distance(text_vec, '[1,2,3]') AS distance +FROM documents +HAVING distance BETWEEN 0.01 AND 0.05 +ORDER BY distance +LIMIT 10; +``` + +
+ + +## 元信息过滤 {#metadata-filtering} + +作为关系型数据库，TiDB 支持丰富的 [SQL 运算符](https://docs.pingcap.com/tidbcloud/operators/)，并允许灵活组合过滤条件。 + +在 TiDB 中进行向量搜索时，你可以对标量字段（如整数型和字符串）或 JSON 字段进行元信息过滤。 + +通常，向量搜索结合元信息过滤有两种模式： + +- **后过滤**：TiDB 首先在整个向量空间中执行向量搜索，获取 top-k 候选，然后对候选集应用过滤条件。向量搜索阶段通常会使用向量索引以提升性能。 +- **预过滤**：TiDB 在向量搜索前先应用过滤条件。如果过滤条件选择性高，且被过滤字段有标量索引，该模式可以减少搜索空间并提升性能。 + +### 后过滤 + + +
+ +使用 `.filter()` 方法和过滤字典为向量搜索添加过滤条件。 + +默认情况下，`table.search()` API 使用后过滤模式，以最大化向量索引的搜索性能。 + +**示例：向量搜索结合后过滤** + +```python +results = ( + table.search([1, 2, 3]) + # `meta` 是 JSON 字段，其值为类似 {"category": "animal"} 的 JSON 对象 + .filter({"meta.category": "animal"}) + .num_candidate(50) + .limit(10) + .to_list() +) +``` + +> **注意：** +> +> 使用向量索引时，如果最终的 `limit` 很小，结果的准确性可能会降低。你可以通过 `.num_candidate()` 方法控制向量搜索阶段从向量索引中获取多少候选，而不改变 `limit` 参数。 + +> 较大的 `num_candidate` 值通常可以提升召回率，但可能降低查询性能。请根据你的数据集和准确性需求调整该值。 + +
+
+ +目前，向量索引仅在严格的 ANN（近似最近邻）查询中生效，例如： + +```sql +SELECT * FROM ORDER BY () LIMIT +``` + +换句话说，不能在同一个查询中同时使用 `WHERE` 子句和向量索引。 + +如果你需要将向量搜索与其他过滤条件结合，可以采用后过滤模式。在该模式下，ANN 查询会被拆分为两部分： + +- 内层查询使用向量索引执行向量搜索。 +- 外层查询应用 `WHERE` 条件过滤结果。 + +```sql hl_lines="8" +SELECT * +FROM ( + SELECT id, text, meta, vec_cosine_distance(text_vec, '[1,2,3]') AS distance + FROM documents + ORDER BY distance + LIMIT 50 +) candidates +WHERE meta->>'$.category' = 'animal' +ORDER BY distance +LIMIT 10; +``` + +> **注意：** +> +> 后过滤模式可能导致结果为空。例如，内层查询搜索到 top 50 最相似的记录，但这些记录都不满足 `WHERE` 条件。 +> +> 为避免这种情况，可以适当增大**内层查询**的 `LIMIT`（如 50），以提升过滤后返回足够有效结果的概率。 + +有关支持的 SQL 运算符，请参见 TiDB Cloud 文档中的 [运算符](https://docs.pingcap.com/tidbcloud/operators/)。 + + + + +### 预过滤 + + +
+ +要启用预过滤，在 `.filter()` 方法中设置 `prefilter=True`。 + +**示例：向量搜索结合预过滤** + +```python +results = ( + table.search([1, 2, 3]) + .filter({"meta.category": "animal"}, prefilter=True) + .limit(10) + .to_list() +) +``` + +有关支持的过滤运算符，请参见 [过滤](/ai/guides/filtering.md)。 + +
+
+ +在 SQL 中，可在 `WHERE` 子句中使用 `->>` 运算符或 `JSON_EXTRACT` 访问 JSON 字段： + +```sql +SELECT id, text, meta, vec_cosine_distance(text_vec, '[1,2,3]') AS distance +FROM documents +WHERE meta->>'$.category' = 'animal' +ORDER BY distance +LIMIT 10; +``` + +有关支持的 SQL 运算符，请参见 TiDB Cloud 文档中的 [运算符](https://docs.pingcap.com/tidbcloud/operators/)。 + +
+ + +## 多向量字段 + +TiDB 支持在单个表中定义多个向量列，便于存储和搜索不同类型的向量嵌入。 + +例如，你可以在同一张表中同时存储文本嵌入和图像嵌入，方便管理多模态数据。 + + +
+ +你可以在 schema 中定义多个向量字段，并通过 `.vector_column()` 方法指定要搜索的向量字段。 + +**示例：指定搜索的向量字段** + +```python hl_lines="6 8 17" +# 创建包含多个向量字段的表 +class RichTextDocument(TableModel): + __tablename__ = "rich_text_documents" + id: int = Field(primary_key=True) + text: str = Field(sa_type=TEXT) + text_vec: list[float] = VectorField(dimensions=3) + image_url: str + image_vec: list[float] = VectorField(dimensions=3) + +table = client.create_table(schema=RichTextDocument, if_exists="overwrite") + +# 插入示例数据 ... + +# 使用图像向量字段进行搜索 +results = ( + table.search([1, 2, 3]) + .vector_column("image_vec") + .distance_metric(DistanceMetric.COSINE) + .limit(10) + .to_list() +) +``` + +
+
+ +你可以在表中创建多个向量列，并使用合适的距离函数进行搜索： + +```sql +-- 创建包含多个向量字段的表 +CREATE TABLE rich_text_documents ( + id BIGINT PRIMARY KEY, + text TEXT, + text_vec VECTOR(3), + image_url VARCHAR(255), + image_vec VECTOR(3) +); + +-- 插入示例数据 ... + +-- 使用文本向量进行搜索 +SELECT id, image_url, vec_l2_distance(image_vec, '[4,5,6]') AS image_distance +FROM rich_text_documents +ORDER BY image_distance +LIMIT 10; +``` + +
+ + +## 输出搜索结果 + +`table.search()` API 支持将搜索结果转换为多种常见数据处理格式： + +### 作为 SQLAlchemy 结果行 + +如需处理原始 SQLAlchemy 结果行，可使用： + +```python +table.search([1, 2, 3]).limit(10).to_rows() +``` + +### 作为 Python 字典列表 + +如需在 Python 中便于操作，可将结果转换为字典列表： + +```python +table.search([1, 2, 3]).limit(10).to_list() +``` + +### 作为 pandas DataFrame + +如需以用户友好的表格方式展示结果（尤其适用于 Jupyter notebook），可转换为 pandas DataFrame： + +```python +table.search([1, 2, 3]).limit(10).to_pandas() +``` + +### 作为 Pydantic 模型实例列表 + +`TableModel` 类也可作为 Pydantic 模型用于表示数据实体。如需以 Pydantic 模型实例处理结果，可使用： + +```python +table.search([1, 2, 3]).limit(10).to_pydantic() +``` \ No newline at end of file diff --git a/ai/integrations/embedding-openai-compatible.md b/ai/integrations/embedding-openai-compatible.md new file mode 100644 index 000000000000..7b07f890c37f --- /dev/null +++ b/ai/integrations/embedding-openai-compatible.md @@ -0,0 +1,131 @@ +--- +title: OpenAI-Compatible Embeddings +summary: 了解如何将 TiDB 向量搜索与 OpenAI 兼容的 embedding 模型集成，以存储 embedding 并执行语义搜索。 +--- + +# OpenAI-Compatible Embeddings + +本教程演示如何使用 OpenAI 兼容的 embedding 服务生成文本 embedding，将其存储到 TiDB，并执行语义搜索。 + +> **注意：** +> +> 目前，[Auto Embedding](/ai/integrations/vector-search-auto-embedding-overview.md) 仅在托管于 AWS 的 TiDB Cloud Starter 集群上可用。 + +## OpenAI 兼容的 embedding 服务 + +由于 OpenAI Embedding API 被广泛使用，许多提供商都提供兼容的 API，例如： + +- [Ollama](https://ollama.com/) +- [vLLM](https://vllm.ai/) + +TiDB Python SDK [pytidb](https://github.com/pingcap/pytidb) 提供了 `EmbeddingFunction` 类，用于集成 OpenAI 兼容的 embedding 服务。 + +## 使用示例 + +本示例展示如何创建向量表、插入文档，并使用 OpenAI 兼容的 embedding 模型进行相似度搜索。 + +### 步骤 1：连接数据库 + +```python +from pytidb import TiDBClient + +tidb_client = TiDBClient.connect( + host="{gateway-region}.prod.aws.tidbcloud.com", + port=4000, + username="{prefix}.root", + password="{password}", + database="{database}", + ensure_db=True, +) +``` + +### 步骤 2：定义 embedding 函数 + +要集成 OpenAI 兼容的 embedding 服务，需要初始化 `EmbeddingFunction` 类，并将 `model_name` 参数设置为带有 `openai/` 前缀的值。 + +```python +from pytidb.embeddings import EmbeddingFunction + +openai_like_embed = EmbeddingFunction( + model_name="openai/{model_name}", + api_base="{your-api-base}", + api_key="{your-api-key}", +) +``` + +参数说明： + +- `model_name`：指定要使用的模型。格式为 `openai/{model_name}`。 +- `api_base`：你的 OpenAI 兼容 embedding API 服务的基础 URL。 +- `api_key`：用于认证 embedding API 服务的 API 密钥。 + +**示例：使用 Ollama 的 `nomic-embed-text` 模型** + +```python +openai_like_embed = EmbeddingFunction( + model_name="openai/nomic-embed-text", + api_base="http://localhost:11434/v1", +) +``` + +**示例：使用 vLLM 的 `intfloat/e5-mistral-7b-instruct` 模型** + +```python +openai_like_embed = EmbeddingFunction( + model_name="openai/intfloat/e5-mistral-7b-instruct", + api_base="http://localhost:8000/v1" +) +``` + +### 步骤 3：创建向量表 + +创建一个包含向量字段的表，使用 Ollama 和 `nomic-embed-text` 模型。 + +```python +from pytidb.schema import TableModel, Field +from pytidb.embeddings import EmbeddingFunction +from pytidb.datatype import TEXT + +openai_like_embed = EmbeddingFunction( + model_name="openai/nomic-embed-text", + api_base="{your-api-base}", +) + +class Document(TableModel): + __tablename__ = "sample_documents" + id: int = Field(primary_key=True) + content: str = Field(sa_type=TEXT) + embedding: list[float] = openai_like_embed.VectorField(source_field="content") + +table = tidb_client.create_table(schema=Document, if_exists="overwrite") +``` + +### 步骤 4：向表中插入数据 + +使用 `table.insert()` 或 `table.bulk_insert()` API 添加数据： + +```python +documents = [ + Document(id=1, content="Java: Object-oriented language for cross-platform development."), + Document(id=2, content="Java coffee: Bold Indonesian beans with low acidity."), + Document(id=3, content="Java island: Densely populated, home to Jakarta."), + Document(id=4, content="Java's syntax is used in Android apps."), + Document(id=5, content="Dark roast Java beans enhance espresso blends."), +] +table.bulk_insert(documents) +``` + +启用 [Auto Embedding](/ai/integrations/vector-search-auto-embedding-overview.md) 后，TiDB 会在插入数据时自动生成向量值。 + +### 步骤 5：搜索相似文档 + +使用 `table.search()` API 执行向量搜索： + +```python +results = table.search("How to start learning Java programming?") \ + .limit(2) \ + .to_list() +print(results) +``` + +启用 [Auto Embedding](/ai/integrations/vector-search-auto-embedding-overview.md) 后，TiDB 会在向量搜索时自动为查询文本生成 embedding。 \ No newline at end of file diff --git a/ai/integrations/tidb-mcp-claude-code.md b/ai/integrations/tidb-mcp-claude-code.md new file mode 100644 index 000000000000..a41a9b934ab3 --- /dev/null +++ b/ai/integrations/tidb-mcp-claude-code.md @@ -0,0 +1,74 @@ +--- +title: 开始使用 Claude Code 和 TiDB MCP Server +summary: 本指南将向你展示如何在 Claude Code 中配置 TiDB MCP Server。 +--- + +# 开始使用 Claude Code 和 TiDB MCP Server + +本指南将介绍如何在 Claude Code 中配置 TiDB MCP Server。 + +## 前置条件 + +在开始之前，请确保你已具备以下条件： + +- **Claude Code**：可从 [claude.com](https://claude.com/product/claude-code) 安装。 +- **Python (>=3.10) 和 uv**：确保已安装 Python（3.10 或更高版本）和 `uv`。可按照 [安装指南](https://docs.astral.sh/uv/getting-started/installation/) 安装 `uv`。 +- **一个 TiDB Cloud Starter 集群**：你可以在 [TiDB Cloud](https://tidbcloud.com/free-trial) 上创建一个免费的 TiDB 集群。 + +## 连接到 TiDB Cloud Starter（推荐） + +使用 TiDB Cloud 控制台生成可直接运行的 Claude Code 命令。 + +1. 进入 [Clusters](https://tidbcloud.com/console/clusters) 页面，选择你的集群，然后点击右上角的 **Use with AI Tools**。 +2. 在 **Access `your_cluster_name` with AI tools** 对话框中，选择 Claude Code 需要访问的 **Branch** 和 **Database**。 +3. 查看对话框中的 **Prerequisites** 列表，并安装所有缺失的依赖项。 +4. 配置 root 密码： + + - 如果你尚未设置密码，点击 **Generate Password** 并将其保存在安全的位置（该密码只会显示一次）。 + - 如果已存在密码，在 **Enter the password for easy setup** 字段中输入该密码。 + - 如果忘记密码，在 **Prerequisites** 部分点击 **Reset password** 以生成新密码。 + +5. 选择 **Claude Code** 标签页，复制设置命令，并在终端中运行。 + +## 手动配置（任意 TiDB 集群） + +如果你更倾向于手动设置，可使用以下任一方法，并将占位符替换为你的连接参数。 + +### 方法 1：CLI 命令 + +```bash +claude mcp add --transport stdio TiDB \ + --env TIDB_HOST='' \ + --env TIDB_PORT= \ + --env TIDB_USERNAME='' \ + --env TIDB_PASSWORD='' \ + --env TIDB_DATABASE='' \ + -- uvx --from 'pytidb[mcp]' 'tidb-mcp-server' +``` + +### 方法 2：项目配置文件 + +将以下配置添加到你的项目级 `.mcp.json` 文件中。详细信息请参见 [Claude Code MCP 文档](https://code.claude.com/docs/en/mcp#project-scope)。 + +```json +{ + "mcpServers": { + "TiDB": { + "type": "stdio", + "command": "uvx", + "args": ["--from", "pytidb[mcp]", "tidb-mcp-server"], + "env": { + "TIDB_HOST": "", + "TIDB_PORT": "", + "TIDB_USERNAME": "", + "TIDB_PASSWORD": "", + "TIDB_DATABASE": "" + } + } + } +} +``` + +## 另请参阅 + +- [TiDB MCP Server](/ai/integrations/tidb-mcp-server.md) diff --git a/ai/integrations/tidb-mcp-claude-desktop.md b/ai/integrations/tidb-mcp-claude-desktop.md new file mode 100644 index 000000000000..32e5ac41fecf --- /dev/null +++ b/ai/integrations/tidb-mcp-claude-desktop.md @@ -0,0 +1,48 @@ +--- +title: 开始使用 Claude Desktop 和 TiDB MCP Server +summary: 本指南将向你展示如何在 Claude Desktop 中配置 TiDB MCP Server。 +--- + +# 开始使用 Claude Desktop 和 TiDB MCP Server + +本指南将介绍如何在 Claude Desktop 中配置 TiDB MCP Server。 + +## 前置条件 + +在开始之前，请确保你已具备以下条件： + +- **Claude Desktop**：从 [claude.ai](https://claude.ai/download) 下载并安装 Claude Desktop。 +- **Python (>=3.10) 和 uv**：确保已安装 Python（3.10 或更高版本）和 `uv`。请按照 [安装指南](https://docs.astral.sh/uv/getting-started/installation/) 安装 `uv`。 +- **TiDB Cloud Starter 集群**：你可以在 [TiDB Cloud](https://tidbcloud.com/free-trial) 上创建一个免费的 TiDB 集群。 + +## 设置步骤 + +按照以下步骤在 Claude Desktop 中设置 TiDB MCP Server： + +1. 打开 **Settings** 对话框。 +2. 在对话框中点击 **Developers** 标签页。 +3. 点击 **Edit Config** 按钮，打开 MCP 配置文件 `claude_desktop_config.json`。 +4. 将以下配置复制到 `claude_desktop_config.json` 文件中。 + + ```json + { + "mcpServers": { + "TiDB": { + "command": "uvx --from pytidb[mcp] tidb-mcp-server", + "env": { + "TIDB_HOST": "localhost", + "TIDB_PORT": "4000", + "TIDB_USERNAME": "root", + "TIDB_PASSWORD": "", + "TIDB_DATABASE": "test" + } + } + } + } + ``` + +5. 前往 [TiDB Cloud 集群页面](https://tidbcloud.com/console/clusters)，并导航到你想要连接的集群。 +6. 点击右上角的 **Connect**，获取连接参数，并将 `TIDB_HOST`、`TIDB_PORT`、`TIDB_USERNAME`、`TIDB_PASSWORD` 和 `TIDB_DATABASE` 的值替换为你自己的。 +7. 重启 Claude Desktop。 + +如需了解更多详情，请参阅 [如何在 Claude Desktop 中配置 MCP server](https://modelcontextprotocol.io/quickstart/user)。 \ No newline at end of file diff --git a/ai/integrations/tidb-mcp-cursor.md b/ai/integrations/tidb-mcp-cursor.md new file mode 100644 index 000000000000..a6d37d69b89b --- /dev/null +++ b/ai/integrations/tidb-mcp-cursor.md @@ -0,0 +1,66 @@ +--- +title: 开始使用 Cursor 和 TiDB MCP Server +summary: 本指南将演示如何在 Cursor 编辑器中配置 TiDB MCP Server。 +--- + +# 开始使用 Cursor 和 TiDB MCP Server + +本指南将演示如何在 Cursor 编辑器中配置 TiDB MCP Server。 + +如需一键安装，请点击下方按钮： + +

Install TiDB MCP Server

+ +## 前置条件 + +在开始之前，请确保你已具备以下条件： + +- **Cursor**：从 [cursor.com](https://cursor.com) 下载并安装 Cursor。 +- **Python (>=3.10) 和 uv**：确保已安装 Python（3.10 或更高版本）和 `uv`。可参考 [安装指南](https://docs.astral.sh/uv/getting-started/installation/) 安装 `uv`。 +- **一个 TiDB Cloud Starter 集群**：你可以在 [TiDB Cloud](https://tidbcloud.com/free-trial) 上创建一个免费的 TiDB 集群。 + +## 连接到 TiDB Cloud Starter（推荐） + +使用 TiDB Cloud 控制台，通过你的集群凭证创建 Cursor 配置。 + +1. 进入 [Clusters](https://tidbcloud.com/console/clusters) 页面，选择你的集群，然后点击右上角的 **Use with AI Tools**。 +2. 在 **Access `your_cluster_name` with AI tools** 对话框中，选择 Cursor 需要访问的 **Branch** 和 **Database**。 +3. 查看对话框中的 **Prerequisites** 列表，并安装任何缺失的依赖项。 +4. 配置 root 密码： + + - 如果你尚未设置密码，点击 **Generate Password** 并将其保存在安全的位置（该密码只会显示一次）。 + - 如果已存在密码，在 **Enter the password for easy setup** 字段中输入该密码。 + - 如果忘记密码，在 **Prerequisites** 部分点击 **Reset password** 以生成新密码。 + +5. 选择 **Cursor** 标签页，点击 **Add to Cursor**，然后在 Cursor 中点击 **Install**。 + +## 手动配置（适用于任意 TiDB 集群） + +如果你更倾向于手动配置，请将以下配置添加到你的 `.cursor/mcp.json` 文件中，并将占位符替换为你的连接参数： + +```json +{ + "mcpServers": { + "TiDB": { + "command": "uvx --from pytidb[mcp] tidb-mcp-server", + "env": { + "TIDB_HOST": "", + "TIDB_PORT": "", + "TIDB_USERNAME": "", + "TIDB_PASSWORD": "", + "TIDB_DATABASE": "" + } + } + } +} +``` + +更多详情请参阅 [Model Context Protocol 文档](https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers)。 + +## 故障排查 + +如果你在安装 TiDB MCP Server 时遇到问题，请在 Cursor 中查看 MCP 日志。 + +1. 在编辑器顶部主菜单点击 **View** > **Output**。 +2. 在 **Output** 面板的下拉菜单中选择 **MCP**。 +3. 如果你看到类似 `[error] Could not start MCP server tidb-mcp-server: Error: spawn uvx ENOENT` 的错误，说明你的系统 `$PATH` 环境变量中可能不存在 `uvx` 命令。对于 macOS 用户，可以通过运行 `brew install uv` 安装 `uvx`。 \ No newline at end of file diff --git a/ai/integrations/tidb-mcp-server.md b/ai/integrations/tidb-mcp-server.md new file mode 100644 index 000000000000..65492ecf4aa6 --- /dev/null +++ b/ai/integrations/tidb-mcp-server.md @@ -0,0 +1,163 @@ +--- +title: TiDB MCP Server +summary: 使用自然语言指令，通过 TiDB MCP Server 管理你的 TiDB 数据库。 +--- + +# TiDB MCP Server + +TiDB MCP Server 是一个开源工具，可以让你通过自然语言指令与 TiDB 数据库进行交互。 + +## 理解 MCP 及 TiDB MCP Server + +[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) 是一种标准化 LLM 与外部工具之间通信的协议。 + +MCP 采用 client-server 架构，允许主机应用连接到多个外部 server： + +- **Hosts**：由 AI 驱动的应用，例如 Claude Desktop 或像 Cursor 这样的 IDE，会主动发起与 MCP server 的连接。 + +- **Clients**：嵌入在主机应用中的组件，用于与单个 MCP server 建立一对一连接。 + +- **Servers**：外部 service，例如 **TiDB MCP Server**，为 client 提供工具、上下文和 prompt，以便与外部系统交互。 + +**TiDB MCP Server** 是一个 MCP 兼容的 server，为 MCP client 提供与 TiDB 数据库交互所需的工具和上下文。 + +## 前置条件 + +在开始之前，请确保你具备以下条件： + +- **一个 MCP 兼容的 client**：例如 [Cursor](/ai/integrations/tidb-mcp-cursor.md) 或 [Claude Desktop](/ai/integrations/tidb-mcp-claude-desktop.md)。 +- **Python (>=3.10) 和 uv**：确保已安装 Python（3.10 或更高版本）和 `uv`。请按照 [安装指南](https://docs.astral.sh/uv/getting-started/installation/) 安装 `uv`。 +- **一个 TiDB Cloud Starter 集群**：你可以在 [TiDB Cloud](https://tidbcloud.com/free-trial) 上创建一个免费的 TiDB 集群。 + +## 支持的 MCP client + +请参考以下指南，了解如何在特定 MCP client 中使用 TiDB MCP Server 的详细示例： + +- [Cursor](/ai/integrations/tidb-mcp-cursor.md) +- [Claude Desktop](/ai/integrations/tidb-mcp-claude-desktop.md) + +如果上述列表中没有你的 MCP client，请按照下方的设置步骤进行配置。 + +## 设置步骤 + +TiDB MCP Server 支持两种与 MCP client 集成的模式： + +- 标准输入/输出（STDIO）模式（默认） +- Server-Sent Events（SSE）模式 + +TiDB MCP Server 默认使用 STDIO 模式，因此你无需提前启动独立的 server。 + +你可以根据需要选择其中一种模式，在 MCP client 中设置 TiDB MCP Server。 + +### STDIO 模式 + +要在 MCP client 中以 STDIO 模式设置 TiDB MCP Server，请按照以下步骤操作： + +1. 参考你的 MCP client 文档，了解如何配置 MCP server。 + +2. 进入你的 [TiDB Cloud 集群](https://tidbcloud.com/console/clusters)页面，导航到你的集群概览页。 + +3. 在集群概览页点击 **Connect**，获取连接参数。 + +4. 在 AI 应用的 `mcpServers` 配置文件 section 中，使用你的连接参数配置 TiDB MCP Server。 + + MCP 配置文件示例： + + ```json + { + "mcpServers": { + "TiDB": { + "command": "uvx --from pytidb[mcp] tidb-mcp-server", + "env": { + "TIDB_HOST": "localhost", + "TIDB_PORT": "4000", + "TIDB_USERNAME": "root", + "TIDB_PASSWORD": "", + "TIDB_DATABASE": "test" + } + } + } + } + ``` + +### Server-Sent Events（SSE）模式 + +要在 MCP client 中以 SSE 模式设置 TiDB MCP Server，请按照以下步骤操作： + +1. 参考你的 MCP client 文档，了解如何配置 MCP server。 + +2. 进入你的 [TiDB Cloud 集群](https://tidbcloud.com/console/clusters)页面，选择你的集群。 + +3. 在集群页面点击 **Connect**，获取连接参数。 + +4. 使用你的连接参数创建一个 `.env` 文件。 + + `.env` 文件示例： + + ```bash + cat > .env <=3.10) 和 uv**：确保已安装 Python（3.10 或更高版本）和 `uv`。按照 [安装指南](https://docs.astral.sh/uv/getting-started/installation/) 安装 `uv`。 +- **一个 TiDB Cloud Starter 集群**：你可以在 [TiDB Cloud](https://tidbcloud.com/free-trial) 上创建一个免费的 TiDB 集群。 + +## 连接到 TiDB Cloud Starter（推荐） + +使用 TiDB Cloud 控制台生成 VS Code 配置。 + +1. 进入 [Clusters](https://tidbcloud.com/console/clusters) 页面，选择你的集群，然后点击右上角的 **Use with AI Tools**。 +2. 在 **Access `your_cluster_name` with AI tools** 对话框中，选择 VS Code 需要访问的 **Branch** 和 **Database**。 +3. 查看对话框中的 **Prerequisites** 列表，并安装任何缺失的依赖项。 +4. 配置 root 密码： + + - 如果你尚未设置密码，点击 **Generate Password** 并将其保存在安全的位置（该密码只会显示一次）。 + - 如果已存在密码，在 **Enter the password for easy setup** 字段中输入该密码。 + - 如果忘记了密码，在 **Prerequisites** 部分点击 **Reset password** 以生成新密码。 + +5. 选择 **VS Code** 标签页，点击 **Add to VS Code**，然后在 VS Code 中点击 **Install**。 + +## 手动配置（适用于任意 TiDB 集群） + +如果你更喜欢手动设置，请将以下配置添加到你的 `.vscode/mcp.json` 文件中，并将占位符替换为你的连接参数： + +```json +{ + "mcpServers": { + "TiDB": { + "type": "stdio", + "command": "uvx", + "args": ["--from", "pytidb[mcp]", "tidb-mcp-server"], + "env": { + "TIDB_HOST": "", + "TIDB_PORT": "", + "TIDB_USERNAME": "", + "TIDB_PASSWORD": "", + "TIDB_DATABASE": "" + } + } + } +} +``` + +## 另请参阅 + +- [TiDB MCP Server](/ai/integrations/tidb-mcp-server.md) diff --git a/ai/integrations/tidb-mcp-windsurf.md b/ai/integrations/tidb-mcp-windsurf.md new file mode 100644 index 000000000000..9a37c3f24dce --- /dev/null +++ b/ai/integrations/tidb-mcp-windsurf.md @@ -0,0 +1,58 @@ +--- +title: 开始使用 Windsurf 和 TiDB MCP Server +summary: 本指南将向你展示如何在 Windsurf 中配置 TiDB MCP Server。 +--- + +# 开始使用 Windsurf 和 TiDB MCP Server + +本指南将介绍如何在 Windsurf 中配置 TiDB MCP Server。 + +## 前置条件 + +在开始之前，请确保你已具备以下条件： + +- **Windsurf**：从 [windsurf.com](https://windsurf.com) 下载并安装 Windsurf。 +- **Python (>=3.10) 和 uv**：确保已安装 Python（3.10 或更高版本）和 `uv`。请按照 [安装指南](https://docs.astral.sh/uv/getting-started/installation/) 安装 `uv`。 +- **一个 TiDB Cloud Starter 集群**：你可以在 [TiDB Cloud](https://tidbcloud.com/free-trial) 上创建一个免费的 TiDB 集群。 + +## 连接到 TiDB Cloud Starter（推荐） + +使用 TiDB Cloud 控制台收集连接信息，然后更新 Windsurf 的 MCP 配置。 + +1. 进入 [Clusters](https://tidbcloud.com/console/clusters) 页面，选择你的集群，然后点击右上角的 **Use with AI Tools**。 +2. 在 **Access `your_cluster_name` with AI tools** 对话框中，选择 Windsurf 需要访问的 **Branch** 和 **Database**。 +3. 查看对话框中的 **Prerequisites** 列表，并安装任何缺失的依赖项。 +4. 配置 root 密码： + + - 如果你尚未设置密码，点击 **Generate Password** 并将其保存在安全的位置（该密码只会显示一次）。 + - 如果已存在密码，在 **Enter the password for easy setup** 字段中输入该密码。 + - 如果忘记了密码，在 **Prerequisites** 部分点击 **Reset password** 以生成新密码。 + +5. 选择 **Windsurf** 标签页，并复制提供的连接参数。 +6. 使用复制的参数更新你的 `mcp_config.json` 文件。更多信息请参见 [Windsurf MCP 文档](https://docs.windsurf.com/windsurf/cascade/mcp#adding-a-new-mcp-plugin)。 + +## 手动配置（任意 TiDB 集群） + +如果你更倾向于手动配置，请按如下方式更新你的 `mcp_config.json` 文件，并将占位符替换为你的连接参数： + +```json +{ + "mcpServers": { + "TiDB": { + "command": "uvx", + "args": ["--from", "pytidb[mcp]", "tidb-mcp-server"], + "env": { + "TIDB_HOST": "", + "TIDB_PORT": "", + "TIDB_USERNAME": "", + "TIDB_PASSWORD": "", + "TIDB_DATABASE": "" + } + } + } +} +``` + +## 另请参阅 + +- [TiDB MCP Server](/ai/integrations/tidb-mcp-server.md) diff --git a/ai/integrations/vector-search-auto-embedding-amazon-titan.md b/ai/integrations/vector-search-auto-embedding-amazon-titan.md new file mode 100644 index 000000000000..98d2dff0b716 --- /dev/null +++ b/ai/integrations/vector-search-auto-embedding-amazon-titan.md @@ -0,0 +1,135 @@ +--- +title: Amazon Titan Embeddings +summary: 了解如何在 TiDB Cloud 中使用 Amazon Titan 嵌入模型。 +aliases: ['/zh/tidbcloud/vector-search-auto-embedding-amazon-titan/'] +--- + +# Amazon Titan Embeddings + +本文档介绍如何在 TiDB Cloud 中结合 [Auto Embedding](/ai/integrations/vector-search-auto-embedding-overview.md) 使用 Amazon Titan 嵌入模型，通过文本查询实现语义搜索。 + +> **注意：** +> +> [Auto Embedding](/ai/integrations/vector-search-auto-embedding-overview.md) 仅适用于托管在 AWS 上的 TiDB Cloud Starter 集群。 + +## 可用模型 + +TiDB Cloud 原生提供以下 [Amazon Titan 嵌入模型](https://docs.aws.amazon.com/bedrock/latest/userguide/titan-embedding-models.html)。无需 API 密钥。 + +**Amazon Titan Text Embedding V2 模型** + +- 名称：`tidbcloud_free/amazon/titan-embed-text-v2` +- 维度：1024（默认）、512、256 +- 距离度量：Cosine、L2 +- 支持语言：英语（预览版支持 100+ 种语言） +- 典型用例：RAG、文档搜索、重排序、分类 +- 最大输入文本 token 数：8,192 +- 最大输入文本字符数：50,000 +- 价格：免费 +- 由 TiDB Cloud 托管：✅ +- 支持 Bring Your Own Key（BYOK，由用户自行提供 API 密钥）：❌ + +关于该模型的更多信息，请参见 [Amazon Bedrock 文档](https://docs.aws.amazon.com/bedrock/latest/userguide/titan-embedding-models.html)。 + +## SQL 使用示例 + +以下示例展示了如何结合 Auto Embedding 使用 Amazon Titan 嵌入模型。 + +```sql +CREATE TABLE sample ( + `id` INT, + `content` TEXT, + `embedding` VECTOR(1024) GENERATED ALWAYS AS (EMBED_TEXT( + "tidbcloud_free/amazon/titan-embed-text-v2", + `content` + )) STORED +); + + +INSERT INTO sample + (`id`, `content`) +VALUES + (1, "Java: Object-oriented language for cross-platform development."), + (2, "Java coffee: Bold Indonesian beans with low acidity."), + (3, "Java island: Densely populated, home to Jakarta."), + (4, "Java's syntax is used in Android apps."), + (5, "Dark roast Java beans enhance espresso blends."); + + +SELECT `id`, `content` FROM sample +ORDER BY + VEC_EMBED_COSINE_DISTANCE( + embedding, + "How to start learning Java programming?" + ) +LIMIT 2; +``` + +结果： + +``` ++------+----------------------------------------------------------------+ +| id | content | ++------+----------------------------------------------------------------+ +| 1 | Java: Object-oriented language for cross-platform development. | +| 4 | Java's syntax is used in Android apps. | ++------+----------------------------------------------------------------+ +``` + +## 选项 + +你可以通过 `EMBED_TEXT()` 函数的 `additional_json_options` 参数指定以下选项： + +- `normalize`（可选）：是否对输出 embedding 进行归一化。默认为 `true`。 +- `dimensions`（可选）：输出 embedding 的维度数。支持的取值：`1024`（默认）、`512`、`256`。 + +**示例：使用其他维度** + +```sql +CREATE TABLE sample ( + `id` INT, + `content` TEXT, + `embedding` VECTOR(512) GENERATED ALWAYS AS (EMBED_TEXT( + "tidbcloud_free/amazon/titan-embed-text-v2", + `content`, + '{"dimensions": 512}' + )) STORED +); + + +INSERT INTO sample + (`id`, `content`) +VALUES + (1, "Java: Object-oriented language for cross-platform development."), + (2, "Java coffee: Bold Indonesian beans with low acidity."), + (3, "Java island: Densely populated, home to Jakarta."), + (4, "Java's syntax is used in Android apps."), + (5, "Dark roast Java beans enhance espresso blends."); + + +SELECT `id`, `content` FROM sample +ORDER BY + VEC_EMBED_COSINE_DISTANCE( + embedding, + "How to start learning Java programming?" + ) +LIMIT 2; +``` + +结果： + +``` ++------+----------------------------------------------------------------+ +| id | content | ++------+----------------------------------------------------------------+ +| 1 | Java: Object-oriented language for cross-platform development. | +| 4 | Java's syntax is used in Android apps. | ++------+----------------------------------------------------------------+ +``` + +## 另请参阅 + +- [Auto Embedding 概览](/ai/integrations/vector-search-auto-embedding-overview.md) +- [向量搜索](/ai/concepts/vector-search-overview.md) +- [向量函数与操作符](/ai/reference/vector-search-functions-and-operators.md) +- [混合搜索](/ai/guides/vector-search-hybrid-search.md) diff --git a/ai/integrations/vector-search-auto-embedding-cohere.md b/ai/integrations/vector-search-auto-embedding-cohere.md new file mode 100644 index 000000000000..87b037b3d2bb --- /dev/null +++ b/ai/integrations/vector-search-auto-embedding-cohere.md @@ -0,0 +1,341 @@ +--- +title: Cohere 向量嵌入 +summary: 了解如何在 TiDB Cloud 中使用 Cohere 向量嵌入模型。 +aliases: ['/zh/tidbcloud/vector-search-auto-embedding-cohere/'] +--- + +# Cohere 向量嵌入 + +本文档介绍如何在 TiDB Cloud 中结合 [Auto Embedding](/ai/integrations/vector-search-auto-embedding-overview.md) 使用 Cohere 向量嵌入模型，通过文本查询实现语义搜索。 + +> **注意：** +> +> [Auto Embedding](/ai/integrations/vector-search-auto-embedding-overview.md) 仅适用于托管在 AWS 上的 TiDB Cloud Starter 集群。 + +## 可用模型 + +TiDB Cloud 原生提供以下 [Cohere](https://cohere.com/) 向量嵌入模型，无需 API 密钥。 + +**Cohere Embed v3 模型** + +- 名称：`tidbcloud_free/cohere/embed-english-v3` +- 维度：1024 +- 距离度量：Cosine，L2 +- 语言：英语 +- 最大输入文本 token 数：512（约每个 token 4 个字符） +- 最大输入文本字符数：2,048 +- 价格：免费 +- 由 TiDB Cloud 托管：✅ `tidbcloud_free/cohere/embed-english-v3` +- 自带密钥（BYOK）：✅ `cohere/embed-english-v3.0` + +**Cohere Multilingual Embed v3 模型** + +- 名称：`tidbcloud_free/cohere/embed-multilingual-v3` +- 维度：1024 +- 距离度量：Cosine，L2 +- 语言：100+ 种语言 +- 最大输入文本 token 数：512（约每个 token 4 个字符） +- 最大输入文本字符数：2,048 +- 价格：免费 +- 由 TiDB Cloud 托管：✅ `tidbcloud_free/cohere/embed-multilingual-v3` +- 自带密钥（BYOK）：✅ `cohere/embed-multilingual-v3.0` + +另外，如果你自带 Cohere API 密钥（BYOK），也可以通过 `cohere/` 前缀使用所有 Cohere 模型。例如： + +**Cohere Embed v4 模型** + +- 名称：`cohere/embed-v4.0` +- 维度：256、512、1024、1536（默认） +- 距离度量：Cosine，L2 +- 最大输入文本 token 数：128,000 +- 价格：由 Cohere 收费 +- 由 TiDB Cloud 托管：❌ +- 自带密钥（BYOK）：✅ + +完整 Cohere 模型列表请参见 [Cohere Documentation](https://docs.cohere.com/docs/cohere-embed)。 + +## SQL 使用示例（TiDB Cloud 托管） + +以下示例展示了如何结合 Auto Embedding 使用 TiDB Cloud 托管的 Cohere 向量嵌入模型。 + +```sql +CREATE TABLE sample ( + `id` INT, + `content` TEXT, + `embedding` VECTOR(1024) GENERATED ALWAYS AS (EMBED_TEXT( + "tidbcloud_free/cohere/embed-multilingual-v3", + `content`, + '{"input_type": "search_document", "input_type@search": "search_query"}' + )) STORED +); +``` + +> **注意：** +> +> - 对于 Cohere 向量嵌入模型，定义表时必须在 `EMBED_TEXT()` 函数中指定 `input_type`。例如，`'{"input_type": "search_document", "input_type@search": "search_query"}'` 表示插入数据时 `input_type` 设为 `search_document`，而在向量搜索时会自动应用 `search_query`。 +> - `@search` 后缀表示该字段仅在向量搜索查询时生效，因此在查询时无需再次指定 `input_type`。 + +插入和查询数据： + +```sql +INSERT INTO sample + (`id`, `content`) +VALUES + (1, "Java: Object-oriented language for cross-platform development."), + (2, "Java coffee: Bold Indonesian beans with low acidity."), + (3, "Java island: Densely populated, home to Jakarta."), + (4, "Java's syntax is used in Android apps."), + (5, "Dark roast Java beans enhance espresso blends."); + + +SELECT `id`, `content` FROM sample +ORDER BY + VEC_EMBED_COSINE_DISTANCE( + embedding, + "How to start learning Java programming?" + ) +LIMIT 2; +``` + +结果： + +``` ++------+----------------------------------------------------------------+ +| id | content | ++------+----------------------------------------------------------------+ +| 1 | Java: Object-oriented language for cross-platform development. | +| 4 | Java's syntax is used in Android apps. | ++------+----------------------------------------------------------------+ +``` + +## 选项（TiDB Cloud 托管） + +**Embed v3** 和 **Multilingual Embed v3** 两个模型均支持以下选项，你可以通过 `EMBED_TEXT()` 函数的 `additional_json_options` 参数进行指定。 + +- `input_type`（必填）：在嵌入前添加特殊 token，用于指示嵌入的用途。对于同一任务，生成嵌入时必须始终使用相同的 input_type，否则嵌入会被映射到不同的语义空间，导致不兼容。唯一的例外是语义搜索，文档嵌入使用 `search_document`，查询嵌入使用 `search_query`。 + + - `search_document`：从文档生成嵌入，用于存储到向量数据库。 + - `search_query`：从查询生成嵌入，用于在向量数据库中搜索已存储的嵌入。 + - `classification`：生成嵌入，作为文本分类器的输入。 + - `clustering`：生成嵌入，用于聚类任务。 + +- `truncate`（可选）：控制 API 如何处理超出最大 token 长度的输入。可选值如下： + + - `NONE`（默认）：当输入超过最大 token 长度时返回错误。 + - `START`：从开头截断文本，直到输入长度符合要求。 + - `END`：从结尾截断文本，直到输入长度符合要求。 + +## 使用示例（BYOK） + +本示例展示如何使用自带密钥（BYOK）的 Cohere 模型创建向量表、插入文档并进行相似度搜索。 + +### 步骤 1：连接数据库 + + +
+ +```python +from pytidb import TiDBClient + +tidb_client = TiDBClient.connect( + host="{gateway-region}.prod.aws.tidbcloud.com", + port=4000, + username="{prefix}.root", + password="{password}", + database="{database}", + ensure_db=True, +) +``` + +
+
+ +```bash +mysql -h {gateway-region}.prod.aws.tidbcloud.com \ + -P 4000 \ + -u {prefix}.root \ + -p{password} \ + -D {database} +``` + +
+ + +### 步骤 2：配置 API 密钥 + +在 [Cohere Dashboard](https://dashboard.cohere.com/api-keys) 创建你的 API 密钥，并自带密钥（BYOK）使用嵌入服务。 + + +
+ +使用 TiDB Client 配置 Cohere 嵌入提供方的 API 密钥： + +```python +tidb_client.configure_embedding_provider( + provider="cohere", + api_key="{your-cohere-api-key}", +) +``` + +
+
+ +通过 SQL 设置 Cohere 嵌入提供方的 API 密钥： + +```sql +SET @@GLOBAL.TIDB_EXP_EMBED_COHERE_API_KEY = "{your-cohere-api-key}"; +``` + +
+ + +### 步骤 3：创建向量表 + +创建一个包含向量字段的表，使用 `cohere/embed-v4.0` 模型生成 1536 维（默认维度）向量： + + +
+ +```python +from pytidb.schema import TableModel, Field +from pytidb.embeddings import EmbeddingFunction +from pytidb.datatype import TEXT + +class Document(TableModel): + __tablename__ = "sample_documents" + id: int = Field(primary_key=True) + content: str = Field(sa_type=TEXT) + embedding: list[float] = EmbeddingFunction( + model_name="cohere/embed-v4.0" + ).VectorField(source_field="content") + +table = tidb_client.create_table(schema=Document, if_exists="overwrite") +``` + +
+
+ +```sql +CREATE TABLE sample_documents ( + `id` INT PRIMARY KEY, + `content` TEXT, + `embedding` VECTOR(1536) GENERATED ALWAYS AS (EMBED_TEXT( + "cohere/embed-v4.0", + `content` + )) STORED +); +``` + +
+ + +### 步骤 4：向表中插入数据 + + +
+ +使用 `table.insert()` 或 `table.bulk_insert()` API 添加数据： + +```python +documents = [ + Document(id=1, content="Python: High-level programming language for data science and web development."), + Document(id=2, content="Python snake: Non-venomous constrictor found in tropical regions."), + Document(id=3, content="Python framework: Django and Flask are popular web frameworks."), + Document(id=4, content="Python libraries: NumPy and Pandas for data analysis."), + Document(id=5, content="Python ecosystem: Rich collection of packages and tools."), +] +table.bulk_insert(documents) +``` + +
+
+ +使用 `INSERT INTO` 语句插入数据： + +```sql +INSERT INTO sample_documents (id, content) +VALUES + (1, "Python: High-level programming language for data science and web development."), + (2, "Python snake: Non-venomous constrictor found in tropical regions."), + (3, "Python framework: Django and Flask are popular web frameworks."), + (4, "Python libraries: NumPy and Pandas for data analysis."), + (5, "Python ecosystem: Rich collection of packages and tools."); +``` + +
+ + +### 步骤 5：搜索相似文档 + + +
+ +使用 `table.search()` API 进行向量搜索： + +```python +results = table.search("How to learn Python programming?") \ + .limit(2) \ + .to_list() +print(results) +``` + +
+
+ +使用 `VEC_EMBED_COSINE_DISTANCE` 函数基于余弦距离进行向量搜索： + +```sql +SELECT + `id`, + `content`, + VEC_EMBED_COSINE_DISTANCE(embedding, "How to learn Python programming?") AS _distance +FROM sample_documents +ORDER BY _distance ASC +LIMIT 2; +``` + +
+ + +## 选项（BYOK） + +所有 [Cohere 嵌入选项](https://docs.cohere.com/v2/reference/embed) 均可通过 `EMBED_TEXT()` 函数的 `additional_json_options` 参数进行设置。 + +**示例：为搜索和插入操作分别指定不同的 `input_type`** + +使用 `@search` 后缀，表示该字段仅在向量搜索查询时生效。 + +```sql +CREATE TABLE sample ( + `id` INT, + `content` TEXT, + `embedding` VECTOR(1024) GENERATED ALWAYS AS (EMBED_TEXT( + "cohere/embed-v4.0", + `content`, + '{"input_type": "search_document", "input_type@search": "search_query"}' + )) STORED +); +``` + +**示例：使用不同的维度** + +```sql +CREATE TABLE sample ( + `id` INT, + `content` TEXT, + `embedding` VECTOR(512) GENERATED ALWAYS AS (EMBED_TEXT( + "cohere/embed-v4.0", + `content`, + '{"output_dimension": 512}' + )) STORED +); +``` + +所有可用选项请参见 [Cohere Documentation](https://docs.cohere.com/v2/reference/embed)。 + +## 另请参阅 + +- [Auto Embedding 概览](/ai/integrations/vector-search-auto-embedding-overview.md) +- [向量搜索](/ai/concepts/vector-search-overview.md) +- [向量函数与运算符](/ai/reference/vector-search-functions-and-operators.md) +- [混合搜索](/ai/guides/vector-search-hybrid-search.md) diff --git a/ai/integrations/vector-search-auto-embedding-gemini.md b/ai/integrations/vector-search-auto-embedding-gemini.md new file mode 100644 index 000000000000..e23b4221fb42 --- /dev/null +++ b/ai/integrations/vector-search-auto-embedding-gemini.md @@ -0,0 +1,287 @@ +--- +title: Gemini 向量嵌入 +summary: 了解如何在 TiDB Cloud 中使用 Google Gemini 向量嵌入模型。 +aliases: ['/zh/tidbcloud/vector-search-auto-embedding-gemini/'] +--- + +# Gemini 向量嵌入 + +本文档介绍如何在 TiDB Cloud 中结合 [Auto Embedding](/ai/integrations/vector-search-auto-embedding-overview.md) 使用 Gemini 向量嵌入模型，通过文本查询实现语义搜索。 + +> **注意：** +> +> [Auto Embedding](/ai/integrations/vector-search-auto-embedding-overview.md) 仅适用于托管在 AWS 上的 TiDB Cloud Starter 集群。 + +## 可用模型 + +如果你自带 Gemini API 密钥（BYOK），则所有 Gemini 模型均可通过 `gemini/` 前缀使用。例如： + +**gemini-embedding-001** + +- 名称：`gemini/gemini-embedding-001` +- 维度：128–3072（默认：3072） +- 距离度量：Cosine，L2 +- 最大输入文本 token 数：2,048 +- 价格：由 Google 收费 +- 由 TiDB Cloud 托管：❌ +- 支持 Bring Your Own Key（BYOK，由用户自行提供 API 密钥）：✅ + +完整可用模型列表请参见 [Gemini 文档](https://ai.google.dev/gemini-api/docs/embeddings)。 + +## 使用示例 + +以下示例展示如何创建向量表、插入文档，并使用 Google Gemini 向量嵌入模型进行相似度搜索。 + +### 步骤 1：连接数据库 + + +
+ +```python +from pytidb import TiDBClient + +tidb_client = TiDBClient.connect( + host="{gateway-region}.prod.aws.tidbcloud.com", + port=4000, + username="{prefix}.root", + password="{password}", + database="{database}", + ensure_db=True, +) +``` + +
+
+ +```bash +mysql -h {gateway-region}.prod.aws.tidbcloud.com \ + -P 4000 \ + -u {prefix}.root \ + -p{password} \ + -D {database} +``` + +
+ + +### 步骤 2：配置 API 密钥 + +在 [Google AI Studio](https://makersuite.google.com/app/apikey) 创建你的 API 密钥，并自带密钥（BYOK）以使用向量嵌入服务。 + + +
+ +使用 TiDB Client 配置 Google Gemini 向量嵌入提供方的 API 密钥： + +```python +tidb_client.configure_embedding_provider( + provider="google_gemini", + api_key="{your-google-api-key}", +) +``` + +
+
+ +通过 SQL 设置 Google Gemini 向量嵌入提供方的 API 密钥： + +```sql +SET @@GLOBAL.TIDB_EXP_EMBED_GEMINI_API_KEY = "{your-google-api-key}"; +``` + +
+ + +### 步骤 3：创建向量表 + +创建一个包含向量字段的表，使用 `gemini-embedding-001` 模型生成 3072 维（默认）向量： + + +
+ +```python +from pytidb.schema import TableModel, Field +from pytidb.embeddings import EmbeddingFunction +from pytidb.datatype import TEXT + +class Document(TableModel): + __tablename__ = "sample_documents" + id: int = Field(primary_key=True) + content: str = Field(sa_type=TEXT) + embedding: list[float] = EmbeddingFunction( + model_name="gemini-embedding-001" + ).VectorField(source_field="content") + +table = tidb_client.create_table(schema=Document, if_exists="overwrite") +``` + +
+
+ +```sql +CREATE TABLE sample_documents ( + `id` INT PRIMARY KEY, + `content` TEXT, + `embedding` VECTOR(3072) GENERATED ALWAYS AS (EMBED_TEXT( + "gemini-embedding-001", + `content` + )) STORED +); +``` + +
+ + +### 步骤 4：向表中插入数据 + + +
+ +使用 `table.insert()` 或 `table.bulk_insert()` API 添加数据： + +```python +documents = [ + Document(id=1, content="Java: Object-oriented language for cross-platform development."), + Document(id=2, content="Java coffee: Bold Indonesian beans with low acidity."), + Document(id=3, content="Java island: Densely populated, home to Jakarta."), + Document(id=4, content="Java's syntax is used in Android apps."), + Document(id=5, content="Dark roast Java beans enhance espresso blends."), +] +table.bulk_insert(documents) +``` + +
+
+ +使用 `INSERT INTO` 语句插入数据： + +```sql +INSERT INTO sample_documents (id, content) +VALUES + (1, "Java: Object-oriented language for cross-platform development."), + (2, "Java coffee: Bold Indonesian beans with low acidity."), + (3, "Java island: Densely populated, home to Jakarta."), + (4, "Java's syntax is used in Android apps."), + (5, "Dark roast Java beans enhance espresso blends."); +``` + +
+ + +### 步骤 5：搜索相似文档 + + +
+ +使用 `table.search()` API 进行向量搜索： + +```python +results = table.search("How to start learning Java programming?") \ + .limit(2) \ + .to_list() +print(results) +``` + +
+
+ +使用 `VEC_EMBED_COSINE_DISTANCE` 函数基于余弦距离进行向量搜索： + +```sql +SELECT + `id`, + `content`, + VEC_EMBED_COSINE_DISTANCE(embedding, "How to start learning Java programming?") AS _distance +FROM sample_documents +ORDER BY _distance ASC +LIMIT 2; +``` + +
+ + +## 自定义向量嵌入维度 + +`gemini-embedding-001` 模型通过 Matryoshka Representation Learning (MRL) 支持灵活的维度。你可以在向量嵌入函数中指定所需的维度： + + +
+ +```python +# 1536 维 +embedding: list[float] = EmbeddingFunction( + model_name="gemini-embedding-001", + dimensions=1536 +).VectorField(source_field="content") + +# 768 维 +embedding: list[float] = EmbeddingFunction( + model_name="gemini-embedding-001", + dimensions=768 +).VectorField(source_field="content") +``` + +
+
+ +```sql +-- 1536 维 +`embedding` VECTOR(1536) GENERATED ALWAYS AS (EMBED_TEXT( + "gemini-embedding-001", + `content`, + '{"embedding_config": {"output_dimensionality": 1536}}' +)) STORED + +-- 768 维 +`embedding` VECTOR(768) GENERATED ALWAYS AS (EMBED_TEXT( + "gemini-embedding-001", + `content`, + '{"embedding_config": {"output_dimensionality": 768}}' +)) STORED +``` + +
+ + +请根据你的性能需求和存储约束选择合适的维度。更高的维度可以提升准确性，但会占用更多存储和计算资源。 + +## 选项 + +所有 [Gemini 选项](https://ai.google.dev/gemini-api/docs/embeddings) 均可通过 `EMBED_TEXT()` 函数的 `additional_json_options` 参数进行设置。 + +**示例：指定任务类型以提升质量** + +```sql +CREATE TABLE sample ( + `id` INT, + `content` TEXT, + `embedding` VECTOR(1024) GENERATED ALWAYS AS (EMBED_TEXT( + "gemini/gemini-embedding-001", + `content`, + '{"task_type": "SEMANTIC_SIMILARITY"}' + )) STORED +); +``` + +**示例：使用不同维度** + +```sql +CREATE TABLE sample ( + `id` INT, + `content` TEXT, + `embedding` VECTOR(768) GENERATED ALWAYS AS (EMBED_TEXT( + "gemini/gemini-embedding-001", + `content`, + '{"output_dimensionality": 768}' + )) STORED +); +``` + +所有可用选项请参见 [Gemini 文档](https://ai.google.dev/gemini-api/docs/embeddings)。 + +## 另请参阅 + +- [Auto Embedding 概览](/ai/integrations/vector-search-auto-embedding-overview.md) +- [向量搜索](/ai/concepts/vector-search-overview.md) +- [向量函数与操作符](/ai/reference/vector-search-functions-and-operators.md) +- [混合搜索](/ai/guides/vector-search-hybrid-search.md) diff --git a/ai/integrations/vector-search-auto-embedding-huggingface.md b/ai/integrations/vector-search-auto-embedding-huggingface.md new file mode 100644 index 000000000000..256d57703eff --- /dev/null +++ b/ai/integrations/vector-search-auto-embedding-huggingface.md @@ -0,0 +1,329 @@ +--- +title: Hugging Face 向量嵌入 +summary: 了解如何在 TiDB Cloud 中使用 Hugging Face 向量嵌入模型。 +aliases: ['/zh/tidbcloud/vector-search-auto-embedding-huggingface/'] +--- + +# Hugging Face 向量嵌入 + +本文档介绍如何在 TiDB Cloud 中结合 [Auto Embedding](/ai/integrations/vector-search-auto-embedding-overview.md) 使用 Hugging Face 向量嵌入模型，通过文本查询实现语义搜索。 + +> **注意：** +> +> [Auto Embedding](/ai/integrations/vector-search-auto-embedding-overview.md) 仅适用于托管在 AWS 上的 TiDB Cloud Starter 集群。 + +## 可用模型 + +如果你自带 [Hugging Face Inference API](https://huggingface.co/docs/inference-providers/index) 密钥（BYOK），则可以通过 `huggingface/` 前缀使用 Hugging Face 模型。 + +为方便起见，以下章节以几个流行模型为例。完整可用模型列表请参见 [Hugging Face models](https://huggingface.co/models?library=sentence-transformers&inference_provider=hf-inference&sort=trending)。请注意，并非所有模型都可通过 Hugging Face Inference API 获取，或都能稳定运行。 + +## multilingual-e5-large + +- 名称：`huggingface/intfloat/multilingual-e5-large` +- 维度：1024 +- 距离度量：Cosine，L2 +- 价格：由 Hugging Face 收费 +- TiDB Cloud 托管：❌ +- Bring Your Own Key（BYOK，由用户自行提供 API 密钥）：✅ +- 项目主页： + +示例： + +```sql +SET @@GLOBAL.TIDB_EXP_EMBED_HUGGINGFACE_API_KEY = 'your-huggingface-api-key-here'; + +CREATE TABLE sample ( + `id` INT, + `content` TEXT, + `embedding` VECTOR(1024) GENERATED ALWAYS AS (EMBED_TEXT( + "huggingface/intfloat/multilingual-e5-large", + `content` + )) STORED +); + + +INSERT INTO sample + (`id`, `content`) +VALUES + (1, "Java: Object-oriented language for cross-platform development."), + (2, "Java coffee: Bold Indonesian beans with low acidity."), + (3, "Java island: Densely populated, home to Jakarta."), + (4, "Java's syntax is used in Android apps."), + (5, "Dark roast Java beans enhance espresso blends."); + + +SELECT `id`, `content` FROM sample +ORDER BY + VEC_EMBED_COSINE_DISTANCE( + embedding, + "How to start learning Java programming?" + ) +LIMIT 2; +``` + +## bge-m3 + +- 名称：`huggingface/BAAI/bge-m3` +- 维度：1024 +- 距离度量：Cosine，L2 +- 价格：由 Hugging Face 收费 +- TiDB Cloud 托管：❌ +- Bring Your Own Key（BYOK，由用户自行提供 API 密钥）：✅ +- 项目主页： + +```sql +SET @@GLOBAL.TIDB_EXP_EMBED_HUGGINGFACE_API_KEY = 'your-huggingface-api-key-here'; + +CREATE TABLE sample ( + `id` INT, + `content` TEXT, + `embedding` VECTOR(1024) GENERATED ALWAYS AS (EMBED_TEXT( + "huggingface/BAAI/bge-m3", + `content` + )) STORED +); + + +INSERT INTO sample + (`id`, `content`) +VALUES + (1, "Java: Object-oriented language for cross-platform development."), + (2, "Java coffee: Bold Indonesian beans with low acidity."), + (3, "Java island: Densely populated, home to Jakarta."), + (4, "Java's syntax is used in Android apps."), + (5, "Dark roast Java beans enhance espresso blends."); + + +SELECT `id`, `content` FROM sample +ORDER BY + VEC_EMBED_COSINE_DISTANCE( + embedding, + "How to start learning Java programming?" + ) +LIMIT 2; +``` + +## all-MiniLM-L6-v2 + +- 名称：`huggingface/sentence-transformers/all-MiniLM-L6-v2` +- 维度：384 +- 距离度量：Cosine，L2 +- 价格：由 Hugging Face 收费 +- TiDB Cloud 托管：❌ +- Bring Your Own Key（BYOK，由用户自行提供 API 密钥）：✅ +- 项目主页： + +示例： + +```sql +SET @@GLOBAL.TIDB_EXP_EMBED_HUGGINGFACE_API_KEY = 'your-huggingface-api-key-here'; + +CREATE TABLE sample ( + `id` INT, + `content` TEXT, + `embedding` VECTOR(384) GENERATED ALWAYS AS (EMBED_TEXT( + "huggingface/sentence-transformers/all-MiniLM-L6-v2", + `content` + )) STORED +); + + +INSERT INTO sample + (`id`, `content`) +VALUES + (1, "Java: Object-oriented language for cross-platform development."), + (2, "Java coffee: Bold Indonesian beans with low acidity."), + (3, "Java island: Densely populated, home to Jakarta."), + (4, "Java's syntax is used in Android apps."), + (5, "Dark roast Java beans enhance espresso blends."); + + +SELECT `id`, `content` FROM sample +ORDER BY + VEC_EMBED_COSINE_DISTANCE( + embedding, + "How to start learning Java programming?" + ) +LIMIT 2; +``` + +## all-mpnet-base-v2 + +- 名称：`huggingface/sentence-transformers/all-mpnet-base-v2` +- 维度：768 +- 距离度量：Cosine，L2 +- 价格：由 Hugging Face 收费 +- TiDB Cloud 托管：❌ +- Bring Your Own Key（BYOK，由用户自行提供 API 密钥）：✅ +- 项目主页： + +```sql +SET @@GLOBAL.TIDB_EXP_EMBED_HUGGINGFACE_API_KEY = 'your-huggingface-api-key-here'; + +CREATE TABLE sample ( + `id` INT, + `content` TEXT, + `embedding` VECTOR(768) GENERATED ALWAYS AS (EMBED_TEXT( + "huggingface/sentence-transformers/all-mpnet-base-v2", + `content` + )) STORED +); + + +INSERT INTO sample + (`id`, `content`) +VALUES + (1, "Java: Object-oriented language for cross-platform development."), + (2, "Java coffee: Bold Indonesian beans with low acidity."), + (3, "Java island: Densely populated, home to Jakarta."), + (4, "Java's syntax is used in Android apps."), + (5, "Dark roast Java beans enhance espresso blends."); + + +SELECT `id`, `content` FROM sample +ORDER BY + VEC_EMBED_COSINE_DISTANCE( + embedding, + "How to start learning Java programming?" + ) +LIMIT 2; +``` + +## Qwen3-Embedding-0.6B + +> **注意：** +> +> Hugging Face Inference API 在该模型上可能不稳定。 + +- 名称：`huggingface/Qwen/Qwen3-Embedding-0.6B` +- 维度：1024 +- 距离度量：Cosine，L2 +- 最大输入文本 tokens：512 +- 价格：由 Hugging Face 收费 +- TiDB Cloud 托管：❌ +- Bring Your Own Key（BYOK，由用户自行提供 API 密钥）：✅ +- 项目主页： + +```sql +SET @@GLOBAL.TIDB_EXP_EMBED_HUGGINGFACE_API_KEY = 'your-huggingface-api-key-here'; + +CREATE TABLE sample ( + `id` INT, + `content` TEXT, + `embedding` VECTOR(1024) GENERATED ALWAYS AS (EMBED_TEXT( + "huggingface/Qwen/Qwen3-Embedding-0.6B", + `content` + )) STORED +); + + +INSERT INTO sample + (`id`, `content`) +VALUES + (1, "Java: Object-oriented language for cross-platform development."), + (2, "Java coffee: Bold Indonesian beans with low acidity."), + (3, "Java island: Densely populated, home to Jakarta."), + (4, "Java's syntax is used in Android apps."), + (5, "Dark roast Java beans enhance espresso blends."); + + +SELECT `id`, `content` FROM sample +ORDER BY + VEC_EMBED_COSINE_DISTANCE( + embedding, + "How to start learning Java programming?" + ) +LIMIT 2; +``` + +## Python 使用示例 + +本示例展示如何创建向量表、插入文档，并使用 Hugging Face 向量嵌入模型进行相似度搜索。 + +### 步骤 1：连接数据库 + +```python +from pytidb import TiDBClient + +tidb_client = TiDBClient.connect( + host="{gateway-region}.prod.aws.tidbcloud.com", + port=4000, + username="{prefix}.root", + password="{password}", + database="{database}", + ensure_db=True, +) +``` + +### 步骤 2：配置 API 密钥 + +如果你使用私有模型或需要更高的速率限制，可以配置你的 Hugging Face API token。你可以在 [Hugging Face Token Settings](https://huggingface.co/settings/tokens) 页面创建 token： + +通过 TiDB Client 为 Hugging Face 模型配置 API token： + +```python +tidb_client.configure_embedding_provider( + provider="huggingface", + api_key="{your-huggingface-token}", +) +``` + +### 步骤 3：创建向量表 + +创建一个包含向量字段的表，使用 Hugging Face 模型生成向量嵌入： + +```python +from pytidb.schema import TableModel, Field +from pytidb.embeddings import EmbeddingFunction +from pytidb.datatype import TEXT + +class Document(TableModel): + __tablename__ = "sample_documents" + id: int = Field(primary_key=True) + content: str = Field(sa_type=TEXT) + embedding: list[float] = EmbeddingFunction( + model_name="huggingface/sentence-transformers/all-MiniLM-L6-v2" + ).VectorField(source_field="content") + +table = tidb_client.create_table(schema=Document, if_exists="overwrite") +``` + +> **提示：** +> +> 向量维度取决于你选择的模型。例如，`huggingface/sentence-transformers/all-MiniLM-L6-v2` 生成 384 维向量，而 `huggingface/sentence-transformers/all-mpnet-base-v2` 生成 768 维向量。 + +### 步骤 4：向表中插入数据 + +使用 `table.insert()` 或 `table.bulk_insert()` API 添加数据： + +```python +documents = [ + Document(id=1, content="Machine learning algorithms can identify patterns in data."), + Document(id=2, content="Deep learning uses neural networks with multiple layers."), + Document(id=3, content="Natural language processing helps computers understand text."), + Document(id=4, content="Computer vision enables machines to interpret images."), + Document(id=5, content="Reinforcement learning learns through trial and error."), +] +table.bulk_insert(documents) +``` + +### 步骤 5：搜索相似文档 + +使用 `table.search()` API 进行向量搜索： + +```python +results = table.search("How do neural networks work?") \ + .limit(3) \ + .to_list() + +for doc in results: + print(f"ID: {doc.id}, Content: {doc.content}") +``` + +## 另请参阅 + +- [Auto Embedding 概览](/ai/integrations/vector-search-auto-embedding-overview.md) +- [向量搜索](/ai/concepts/vector-search-overview.md) +- [向量函数与运算符](/ai/reference/vector-search-functions-and-operators.md) +- [混合搜索](/ai/guides/vector-search-hybrid-search.md) diff --git a/ai/integrations/vector-search-auto-embedding-jina-ai.md b/ai/integrations/vector-search-auto-embedding-jina-ai.md new file mode 100644 index 000000000000..5a5b6f0c4805 --- /dev/null +++ b/ai/integrations/vector-search-auto-embedding-jina-ai.md @@ -0,0 +1,265 @@ +--- +title: Jina AI Embeddings +summary: 了解如何在 TiDB Cloud 中使用 Jina AI 嵌入模型。 +aliases: ['/zh/tidbcloud/vector-search-auto-embedding-jina-ai/'] +--- + +# Jina AI Embeddings + +本文档介绍如何在 TiDB Cloud 中结合 [Auto Embedding](/ai/integrations/vector-search-auto-embedding-overview.md) 使用 [Jina AI 嵌入模型](https://jina.ai/embeddings/)，以便通过文本查询执行语义搜索。 + +> **注意：** +> +> [Auto Embedding](/ai/integrations/vector-search-auto-embedding-overview.md) 仅适用于托管在 AWS 上的 TiDB Cloud Starter 集群。 + +## 可用模型 + +Jina AI 提供高性能、多模态、多语言、长上下文的嵌入模型，适用于搜索、RAG 和智能体应用。 + +如果你自带 Jina AI API 密钥（BYOK），所有 Jina AI 模型均可通过 `jina_ai/` 前缀使用。例如： + +**jina-embeddings-v4** + +- 名称: `jina_ai/jina-embeddings-v4` +- 维度: 2048 +- 距离度量: Cosine, L2 +- 最大输入文本 token 数: 32,768 +- 价格: 由 Jina AI 收费 +- 由 TiDB Cloud 托管: ❌ +- 支持 Bring Your Own Key（BYOK，由用户自行提供 API 密钥）: ✅ + +**jina-embeddings-v3** + +- 名称: `jina_ai/jina-embeddings-v3` +- 维度: 1024 +- 距离度量: Cosine, L2 +- 最大输入文本 token 数: 8,192 +- 价格: 由 Jina AI 收费 +- 由 TiDB Cloud 托管: ❌ +- 支持 Bring Your Own Key（BYOK，由用户自行提供 API 密钥）: ✅ + +完整可用模型列表请参见 [Jina AI 文档](https://jina.ai/embeddings/)。 + +## 使用示例 + +本示例展示如何创建向量表、插入文档，并使用 Jina AI 嵌入模型进行相似度搜索。 + +### 步骤 1：连接数据库 + + +
+ +```python +from pytidb import TiDBClient + +tidb_client = TiDBClient.connect( + host="{gateway-region}.prod.aws.tidbcloud.com", + port=4000, + username="{prefix}.root", + password="{password}", + database="{database}", + ensure_db=True, +) +``` + +
+
+ +```bash +mysql -h {gateway-region}.prod.aws.tidbcloud.com \ + -P 4000 \ + -u {prefix}.root \ + -p{password} \ + -D {database} +``` + +
+ + +### 步骤 2：配置 API 密钥 + +在 [Jina AI Platform](https://jina.ai/embeddings/) 创建你的 API 密钥，并自带密钥（BYOK）以使用嵌入服务。 + + +
+ +使用 TiDB Client 为 Jina AI 嵌入提供方配置 API 密钥： + +```python +tidb_client.configure_embedding_provider( + provider="jina_ai", + api_key="{your-jina-api-key}", +) +``` + +
+
+ +通过 SQL 为 Jina AI 嵌入提供方设置 API 密钥： + +```sql +SET @@GLOBAL.TIDB_EXP_EMBED_JINA_AI_API_KEY = "{your-jina-api-key}"; +``` + +
+ + +### 步骤 3：创建向量表 + +创建一个包含向量字段的表，使用 `jina_ai/jina-embeddings-v4` 模型生成 2048 维向量： + + +
+ +```python +from pytidb.schema import TableModel, Field +from pytidb.embeddings import EmbeddingFunction +from pytidb.datatype import TEXT + +class Document(TableModel): + __tablename__ = "sample_documents" + id: int = Field(primary_key=True) + content: str = Field(sa_type=TEXT) + embedding: list[float] = EmbeddingFunction( + model_name="jina_ai/jina-embeddings-v4" + ).VectorField(source_field="content") + +table = tidb_client.create_table(schema=Document, if_exists="overwrite") +``` + +
+
+ +```sql +CREATE TABLE sample_documents ( + `id` INT PRIMARY KEY, + `content` TEXT, + `embedding` VECTOR(2048) GENERATED ALWAYS AS (EMBED_TEXT( + "jina_ai/jina-embeddings-v4", + `content` + )) STORED +); +``` + +
+ + +### 步骤 4：向表中插入数据 + + +
+ +使用 `table.insert()` 或 `table.bulk_insert()` API 添加数据： + +```python +documents = [ + Document(id=1, content="Java: Object-oriented language for cross-platform development."), + Document(id=2, content="Java coffee: Bold Indonesian beans with low acidity."), + Document(id=3, content="Java island: Densely populated, home to Jakarta."), + Document(id=4, content="Java's syntax is used in Android apps."), + Document(id=5, content="Dark roast Java beans enhance espresso blends."), +] +table.bulk_insert(documents) +``` + +
+
+ +使用 `INSERT INTO` 语句插入数据： + +```sql +INSERT INTO sample_documents (id, content) +VALUES + (1, "Java: Object-oriented language for cross-platform development."), + (2, "Java coffee: Bold Indonesian beans with low acidity."), + (3, "Java island: Densely populated, home to Jakarta."), + (4, "Java's syntax is used in Android apps."), + (5, "Dark roast Java beans enhance espresso blends."); +``` + +
+ + +### 步骤 5：搜索相似文档 + + +
+ +使用 `table.search()` API 进行向量搜索： + +```python +results = table.search("How to start learning Java programming?") \ + .limit(2) \ + .to_list() +print(results) +``` + +
+
+ +使用 `VEC_EMBED_COSINE_DISTANCE` 函数基于余弦距离度量进行向量搜索： + +```sql +SELECT + `id`, + `content`, + VEC_EMBED_COSINE_DISTANCE(embedding, "How to start learning Java programming?") AS _distance +FROM sample_documents +ORDER BY _distance ASC +LIMIT 2; +``` + +结果： + +``` ++------+----------------------------------------------------------------+ +| id | content | ++------+----------------------------------------------------------------+ +| 1 | Java: Object-oriented language for cross-platform development. | +| 4 | Java's syntax is used in Android apps. | ++------+----------------------------------------------------------------+ +``` + +
+ + +## 选项 + +所有 [Jina AI 选项](https://jina.ai/embeddings/) 均可通过 `EMBED_TEXT()` 函数的 `additional_json_options` 参数进行设置。 + +**示例：为更优性能指定 “下游任务”** + +```sql +CREATE TABLE sample ( + `id` INT, + `content` TEXT, + `embedding` VECTOR(2048) GENERATED ALWAYS AS (EMBED_TEXT( + "jina_ai/jina-embeddings-v4", + `content`, + '{"task": "retrieval.passage", "task@search": "retrieval.query"}' + )) STORED +); +``` + +**示例：使用其他维度** + +```sql +CREATE TABLE sample ( + `id` INT, + `content` TEXT, + `embedding` VECTOR(768) GENERATED ALWAYS AS (EMBED_TEXT( + "jina_ai/jina-embeddings-v3", + `content`, + '{"dimensions":768}' + )) STORED +); +``` + +所有可用选项请参见 [Jina AI 文档](https://jina.ai/embeddings/)。 + +## 另请参阅 + +- [Auto Embedding 概览](/ai/integrations/vector-search-auto-embedding-overview.md) +- [向量搜索](/ai/concepts/vector-search-overview.md) +- [向量函数与操作符](/ai/reference/vector-search-functions-and-operators.md) +- [混合搜索](/ai/guides/vector-search-hybrid-search.md) diff --git a/ai/integrations/vector-search-auto-embedding-nvidia-nim.md b/ai/integrations/vector-search-auto-embedding-nvidia-nim.md new file mode 100644 index 000000000000..85c2c7926024 --- /dev/null +++ b/ai/integrations/vector-search-auto-embedding-nvidia-nim.md @@ -0,0 +1,255 @@ +--- +title: NVIDIA NIM Embeddings +summary: 了解如何在 TiDB Cloud 中使用 NVIDIA NIM embedding 模型。 +aliases: ['/zh/tidbcloud/vector-search-auto-embedding-nvidia-nim/'] +--- + +# NVIDIA NIM Embeddings + +本文档介绍如何在 TiDB Cloud 中结合 [Auto Embedding](/ai/integrations/vector-search-auto-embedding-overview.md) 使用 NVIDIA NIM embedding 模型，通过文本查询实现语义搜索。 + +> **注意：** +> +> [Auto Embedding](/ai/integrations/vector-search-auto-embedding-overview.md) 仅适用于托管在 AWS 上的 TiDB Cloud Starter 集群。 + +## 可用模型 + +托管在 NVIDIA NIM 上的 embedding 模型可通过 `nvidia_nim/` 前缀使用，前提是你自带 [NVIDIA NIM API key](https://build.nvidia.com/settings/api-keys)（BYOK）。 + +为方便起见，以下章节以一个流行模型为例，展示如何结合 Auto Embedding 使用。如需完整模型列表，请参见 [NVIDIA NIM Text-to-embedding Models](https://build.nvidia.com/models?filters=usecase%3Ausecase_text_to_embedding)。 + +## bge-m3 + +- 名称：`nvidia_nim/baai/bge-m3` +- 维度：1024 +- 距离度量：Cosine，L2 +- 最大输入文本 token 数：8,192 +- 价格：由 NVIDIA 收费 +- TiDB Cloud 托管：❌ +- 支持 Bring Your Own Key（BYOK，由用户自行提供 API 密钥）：✅ +- 文档： + +示例： + +```sql +SET @@GLOBAL.TIDB_EXP_EMBED_NVIDIA_NIM_API_KEY = 'your-nvidia-nim-api-key-here'; + +CREATE TABLE sample ( + `id` INT, + `content` TEXT, + `embedding` VECTOR(1024) GENERATED ALWAYS AS (EMBED_TEXT( + "nvidia_nim/baai/bge-m3", + `content` + )) STORED +); + +INSERT INTO sample + (`id`, `content`) +VALUES + (1, "Java: Object-oriented language for cross-platform development."), + (2, "Java coffee: Bold Indonesian beans with low acidity."), + (3, "Java island: Densely populated, home to Jakarta."), + (4, "Java's syntax is used in Android apps."), + (5, "Dark roast Java beans enhance espresso blends."); + + +SELECT `id`, `content` FROM sample +ORDER BY + VEC_EMBED_COSINE_DISTANCE( + embedding, + "How to start learning Java programming?" + ) +LIMIT 2; +``` + +结果： + +``` ++------+----------------------------------------------------------------+ +| id | content | ++------+----------------------------------------------------------------+ +| 1 | Java: Object-oriented language for cross-platform development. | +| 4 | Java's syntax is used in Android apps. | ++------+----------------------------------------------------------------+ +``` + +## nv-embed-v1 + +本示例展示如何使用 `nvidia/nv-embed-v1` 模型创建向量表、插入文档并进行相似度搜索。 + +### 步骤 1：连接数据库 + + +
+ +```python +from pytidb import TiDBClient + +tidb_client = TiDBClient.connect( + host="{gateway-region}.prod.aws.tidbcloud.com", + port=4000, + username="{prefix}.root", + password="{password}", + database="{database}", + ensure_db=True, +) +``` + +
+
+ +```bash +mysql -h {gateway-region}.prod.aws.tidbcloud.com \ + -P 4000 \ + -u {prefix}.root \ + -p{password} \ + -D {database} +``` + +
+ + +### 步骤 2：配置 API key + +如果你使用需要身份验证的 NVIDIA NIM 模型，可以配置你的 API key。你可以通过 [NVIDIA Developer Program](https://developer.nvidia.com/nim) 免费访问 NIM API 端点，或在 [NVIDIA Build Platform](https://build.nvidia.com/settings/api-keys) 创建你的 API key： + + +
+ +使用 TiDB Client 为 NVIDIA NIM 模型配置 API key： + +```python +tidb_client.configure_embedding_provider( + provider="nvidia_nim", + api_key="{your-nvidia-api-key}", +) +``` + +
+
+ +使用 SQL 为 NVIDIA NIM 模型设置 API key： + +```sql +SET @@GLOBAL.TIDB_EXP_EMBED_NVIDIA_NIM_API_KEY = "{your-nvidia-api-key}"; +``` + +
+ + +### 步骤 3：创建向量表 + +创建包含向量字段的表，使用 NVIDIA NIM 模型生成 embedding： + + +
+ +```python +from pytidb.schema import TableModel, Field +from pytidb.embeddings import EmbeddingFunction +from pytidb.datatype import TEXT + +class Document(TableModel): + __tablename__ = "sample_documents" + id: int = Field(primary_key=True) + content: str = Field(sa_type=TEXT) + embedding: list[float] = EmbeddingFunction( + model_name="nvidia/nv-embed-v1" + ).VectorField(source_field="content") + +table = tidb_client.create_table(schema=Document, if_exists="overwrite") +``` + +
+
+ +```sql +CREATE TABLE sample_documents ( + `id` INT PRIMARY KEY, + `content` TEXT, + `embedding` VECTOR(4096) GENERATED ALWAYS AS (EMBED_TEXT( + "nvidia/nv-embed-v1", + `content` + )) STORED +); +``` + +
+ + +### 步骤 4：向表中插入数据 + + +
+ +使用 `table.insert()` 或 `table.bulk_insert()` API 添加数据： + +```python +documents = [ + Document(id=1, content="Machine learning algorithms can identify patterns in data."), + Document(id=2, content="Deep learning uses neural networks with multiple layers."), + Document(id=3, content="Natural language processing helps computers understand text."), + Document(id=4, content="Computer vision enables machines to interpret images."), + Document(id=5, content="Reinforcement learning learns through trial and error."), +] +table.bulk_insert(documents) +``` + +
+
+ +使用 `INSERT INTO` 语句插入数据： + +```sql +INSERT INTO sample_documents (id, content) +VALUES + (1, "Machine learning algorithms can identify patterns in data."), + (2, "Deep learning uses neural networks with multiple layers."), + (3, "Natural language processing helps computers understand text."), + (4, "Computer vision enables machines to interpret images."), + (5, "Reinforcement learning learns through trial and error."); +``` + +
+ + +### 步骤 5：搜索相似文档 + + +
+ +使用 `table.search()` API 进行向量搜索： + +```python +results = table.search("How do neural networks work?") \ + .limit(3) \ + .to_list() + +for doc in results: + print(f"ID: {doc.id}, Content: {doc.content}") +``` + +
+
+ +使用 `VEC_EMBED_COSINE_DISTANCE` 函数结合余弦距离进行向量搜索： + +```sql +SELECT + `id`, + `content`, + VEC_EMBED_COSINE_DISTANCE(embedding, "How do neural networks work?") AS _distance +FROM sample_documents +ORDER BY _distance ASC +LIMIT 3; +``` + +
+ + +## 另请参阅 + +- [Auto Embedding 概览](/ai/integrations/vector-search-auto-embedding-overview.md) +- [向量搜索](/ai/concepts/vector-search-overview.md) +- [向量函数与运算符](/ai/reference/vector-search-functions-and-operators.md) +- [混合搜索](/ai/guides/vector-search-hybrid-search.md) diff --git a/ai/integrations/vector-search-auto-embedding-openai.md b/ai/integrations/vector-search-auto-embedding-openai.md new file mode 100644 index 000000000000..639efbadb96a --- /dev/null +++ b/ai/integrations/vector-search-auto-embedding-openai.md @@ -0,0 +1,297 @@ +--- +title: OpenAI 向量嵌入 +summary: 了解如何在 TiDB Cloud 中使用 OpenAI 向量嵌入模型。 +aliases: ['/zh/tidbcloud/vector-search-auto-embedding-openai/'] +--- + +# OpenAI 向量嵌入 + +本文档介绍如何在 TiDB Cloud 中结合 [Auto Embedding](/ai/integrations/vector-search-auto-embedding-overview.md) 使用 OpenAI 向量嵌入模型，通过文本查询实现语义搜索。 + +> **注意：** +> +> [Auto Embedding](/ai/integrations/vector-search-auto-embedding-overview.md) 仅适用于托管在 AWS 上的 TiDB Cloud Starter 集群。 + +## 可用模型 + +如果你自带 OpenAI API 密钥（BYOK），则所有 OpenAI 模型均可通过 `openai/` 前缀使用。例如： + +**text-embedding-3-small** + +- 名称：`openai/text-embedding-3-small` +- 维度：512-1536（默认：1536） +- 距离度量：Cosine，L2 +- 价格：由 OpenAI 收费 +- 由 TiDB Cloud 托管：❌ +- 支持 Bring Your Own Key（BYOK，由用户自行提供 API 密钥）：✅ + +**text-embedding-3-large** + +- 名称：`openai/text-embedding-3-large` +- 维度：256-3072（默认：3072） +- 距离度量：Cosine，L2 +- 价格：由 OpenAI 收费 +- 由 TiDB Cloud 托管：❌ +- 支持 Bring Your Own Key（BYOK，由用户自行提供 API 密钥）：✅ + +完整可用模型列表请参见 [OpenAI Documentation](https://platform.openai.com/docs/guides/embeddings)。 + +## 使用示例 + +本示例展示如何创建向量表、插入文档，并使用 OpenAI 向量嵌入模型进行相似度搜索。 + +你可以通过 AI SDK 或原生 SQL 函数，将 OpenAI 向量嵌入 API 集成到 TiDB，实现 Auto Embedding 生成。 + +### 步骤 1：连接数据库 + + +
+ +```python +from pytidb import TiDBClient + +tidb_client = TiDBClient.connect( + host="{gateway-region}.prod.aws.tidbcloud.com", + port=4000, + username="{prefix}.root", + password="{password}", + database="{database}", + ensure_db=True, +) +``` + +
+
+ +```bash +mysql -h {gateway-region}.prod.aws.tidbcloud.com \ + -P 4000 \ + -u {prefix}.root \ + -p{password} \ + -D {database} +``` + +
+ + +### 步骤 2：配置 API 密钥 + +在 [OpenAI API Platform](https://platform.openai.com/api-keys) 创建 API 密钥，并自带密钥（BYOK）以使用嵌入服务。 + + +
+ +使用 TiDB 客户端为 OpenAI 嵌入提供方配置 API 密钥： + +```python +tidb_client.configure_embedding_provider( + provider="openai", + api_key="{your-openai-api-key}", +) +``` + +
+
+ +通过 SQL 为 OpenAI 嵌入提供方设置 API 密钥： + +```sql +SET @@GLOBAL.TIDB_EXP_EMBED_OPENAI_API_KEY = "{your-openai-api-key}"; +``` + +
+ + +### 步骤 3：创建向量表 + +创建一个包含向量字段的表，使用 `openai/text-embedding-3-small` 模型生成 1536 维向量： + + +
+ +```python +from pytidb.schema import TableModel, Field +from pytidb.embeddings import EmbeddingFunction +from pytidb.datatype import TEXT + +class Document(TableModel): + __tablename__ = "sample_documents" + id: int = Field(primary_key=True) + content: str = Field(sa_type=TEXT) + embedding: list[float] = EmbeddingFunction( + model_name="openai/text-embedding-3-small" + ).VectorField(source_field="content") + +table = tidb_client.create_table(schema=Document, if_exists="overwrite") +``` + +
+
+ +```sql +CREATE TABLE sample_documents ( + `id` INT PRIMARY KEY, + `content` TEXT, + `embedding` VECTOR(1536) GENERATED ALWAYS AS (EMBED_TEXT( + "openai/text-embedding-3-small", + `content` + )) STORED +); +``` + +
+ + +### 步骤 4：向表中插入数据 + + +
+ +使用 `table.insert()` 或 `table.bulk_insert()` API 添加数据： + +```python +documents = [ + Document(id=1, content="Java: Object-oriented language for cross-platform development."), + Document(id=2, content="Java coffee: Bold Indonesian beans with low acidity."), + Document(id=3, content="Java island: Densely populated, home to Jakarta."), + Document(id=4, content="Java's syntax is used in Android apps."), + Document(id=5, content="Dark roast Java beans enhance espresso blends."), +] +table.bulk_insert(documents) +``` + +
+
+ +使用 `INSERT INTO` 语句插入数据： + +```sql +INSERT INTO sample_documents (id, content) +VALUES + (1, "Java: Object-oriented language for cross-platform development."), + (2, "Java coffee: Bold Indonesian beans with low acidity."), + (3, "Java island: Densely populated, home to Jakarta."), + (4, "Java's syntax is used in Android apps."), + (5, "Dark roast Java beans enhance espresso blends."); +``` + +
+ + +### 步骤 5：搜索相似文档 + + +
+ +使用 `table.search()` API 进行向量搜索： + +```python +results = table.search("How to start learning Java programming?") \ + .limit(2) \ + .to_list() +print(results) +``` + +
+
+ +使用 `VEC_EMBED_COSINE_DISTANCE` 函数，通过余弦距离进行向量搜索： + +```sql +SELECT + `id`, + `content`, + VEC_EMBED_COSINE_DISTANCE(embedding, "How to start learning Java programming?") AS _distance +FROM sample_documents +ORDER BY _distance ASC +LIMIT 2; +``` + +结果： + +``` ++------+----------------------------------------------------------------+ +| id | content | ++------+----------------------------------------------------------------+ +| 1 | Java: Object-oriented language for cross-platform development. | +| 4 | Java's syntax is used in Android apps. | ++------+----------------------------------------------------------------+ +``` + +
+ + +## 使用 Azure OpenAI + +如需在 Azure 上使用 OpenAI 嵌入模型，请将全局变量 `TIDB_EXP_EMBED_OPENAI_API_BASE` 设置为你的 Azure 资源的 URL。例如： + +```sql +SET @@GLOBAL.TIDB_EXP_EMBED_OPENAI_API_KEY = 'your-openai-api-key-here'; +SET @@GLOBAL.TIDB_EXP_EMBED_OPENAI_API_BASE = 'https://.openai.azure.com/openai/v1'; + +CREATE TABLE sample ( + `id` INT, + `content` TEXT, + `embedding` VECTOR(3072) GENERATED ALWAYS AS (EMBED_TEXT( + "openai/text-embedding-3-large", + `content` + )) STORED +); + +INSERT INTO sample + (`id`, `content`) +VALUES + (1, "Java: Object-oriented language for cross-platform development."), + (2, "Java coffee: Bold Indonesian beans with low acidity."), + (3, "Java island: Densely populated, home to Jakarta."), + (4, "Java's syntax is used in Android apps."), + (5, "Dark roast Java beans enhance espresso blends."); + +SELECT `id`, `content` FROM sample +ORDER BY + VEC_EMBED_COSINE_DISTANCE( + embedding, + "How to start learning Java programming?" + ) +LIMIT 2; +``` + +即使你的资源 URL 形如 `https://.cognitiveservices.azure.com/`，也必须使用 `https://.openai.azure.com/openai/v1` 作为 API base，以保持 OpenAI 兼容的请求和响应格式。 + +如需从 Azure OpenAI 切换回 OpenAI 官方服务，将 `TIDB_EXP_EMBED_OPENAI_API_BASE` 设置为空字符串： + +```sql +SET @@GLOBAL.TIDB_EXP_EMBED_OPENAI_API_BASE = ''; +``` + +> **注意：** +> +> - 出于安全考虑，API base 只能设置为 Azure OpenAI URL 或 OpenAI URL。不允许设置为任意 base URL。 +> - 如需使用其他 OpenAI 兼容的嵌入服务，请联系 [TiDB Cloud Support](https://docs.pingcap.com/zh/tidbcloud/tidb-cloud-support/)。 + +## 选项 + +所有 [OpenAI 嵌入选项](https://platform.openai.com/docs/api-reference/embeddings/create) 均可通过 `EMBED_TEXT()` 函数的 `additional_json_options` 参数支持。 + +**示例：为 text-embedding-3-large 使用自定义维度** + +```sql +CREATE TABLE sample ( + `id` INT, + `content` TEXT, + `embedding` VECTOR(1024) GENERATED ALWAYS AS (EMBED_TEXT( + "openai/text-embedding-3-large", + `content`, + '{"dimensions": 1024}' + )) STORED +); +``` + +所有可用选项请参见 [OpenAI Documentation](https://platform.openai.com/docs/api-reference/embeddings/create)。 + +## 另请参阅 + +- [Auto Embedding 概览](/ai/integrations/vector-search-auto-embedding-overview.md) +- [向量搜索](/ai/concepts/vector-search-overview.md) +- [向量函数与操作符](/ai/reference/vector-search-functions-and-operators.md) +- [混合搜索](/ai/guides/vector-search-hybrid-search.md) \ No newline at end of file diff --git a/ai/integrations/vector-search-auto-embedding-overview.md b/ai/integrations/vector-search-auto-embedding-overview.md new file mode 100644 index 000000000000..6f5164aba27d --- /dev/null +++ b/ai/integrations/vector-search-auto-embedding-overview.md @@ -0,0 +1,205 @@ +--- +title: Auto Embedding 概述 +summary: 了解如何使用 Auto Embedding 通过纯文本而非向量进行语义搜索。 +aliases: ['/zh/tidbcloud/vector-search-auto-embedding-overview/'] +--- + +# Auto Embedding 概述 + +Auto Embedding 功能允许你直接使用纯文本进行向量搜索，无需自行提供向量。通过该功能，你可以直接插入文本数据，并使用文本 query 进行语义搜索，TiDB 会在后台自动将文本转换为向量。 + +要使用 Auto Embedding，基本流程如下： + +1. **定义一张表**，包含一个文本列和一个使用 `EMBED_TEXT()` 生成的向量列。 +2. **插入文本数据** —— 向量会自动生成并存储。 +3. **使用文本进行查询** —— 使用 `VEC_EMBED_COSINE_DISTANCE()` 或 `VEC_EMBED_L2_DISTANCE()` 查找语义相似的内容。 + +> **注意：** +> +> Auto Embedding 仅在托管于 AWS 的 TiDB Cloud Starter 集群上可用。 + +## 快速入门示例 + +> **提示：** +> +> 关于 Python 用法，参见 [在 Python 中使用 Auto Embedding](#use-auto-embedding-in-python)。 + +以下示例展示了如何结合余弦距离使用 Auto Embedding 进行语义搜索。本示例无需 API key。 + +```sql +-- 创建带有 Auto Embedding 的表 +-- 向量列的维度必须与嵌入模型的维度一致； +-- 否则，TiDB 在插入数据时会返回错误。 +CREATE TABLE documents ( + id INT PRIMARY KEY AUTO_INCREMENT, + content TEXT, + content_vector VECTOR(1024) GENERATED ALWAYS AS ( + EMBED_TEXT("tidbcloud_free/amazon/titan-embed-text-v2", content) + ) STORED +); + +-- 插入文本数据（向量会自动生成） +INSERT INTO documents (content) VALUES + ("Electric vehicles reduce air pollution in cities."), + ("Solar panels convert sunlight into renewable energy."), + ("Plant-based diets lower carbon footprints significantly."), + ("Deep learning algorithms improve medical diagnosis accuracy."), + ("Blockchain technology enhances data security systems."); + +-- 使用文本 query 搜索语义相似内容 +SELECT id, content FROM documents +ORDER BY VEC_EMBED_COSINE_DISTANCE( + content_vector, + "Renewable energy solutions for environmental protection" +) +LIMIT 3; +``` + +输出如下： + +``` ++----+--------------------------------------------------------------+ +| id | content | ++----+--------------------------------------------------------------+ +| 2 | Solar panels convert sunlight into renewable energy. | +| 1 | Electric vehicles reduce air pollution in cities. | +| 4 | Deep learning algorithms improve medical diagnosis accuracy. | ++----+--------------------------------------------------------------+ +``` + +上述示例使用了 Amazon Titan 模型。关于其他模型，参见 [可用文本嵌入模型](#available-text-embedding-models)。 + +## Auto Embedding + 向量索引 + +Auto Embedding 可与 [向量索引](/ai/reference/vector-search-index.md) 结合使用，以提升查询性能。你可以在生成的向量列上定义向量索引，系统会自动使用该索引： + +```sql +-- 创建带有 Auto Embedding 和向量索引的表 +CREATE TABLE documents ( + id INT PRIMARY KEY AUTO_INCREMENT, + content TEXT, + content_vector VECTOR(1024) GENERATED ALWAYS AS ( + EMBED_TEXT("tidbcloud_free/amazon/titan-embed-text-v2", content) + ) STORED, + VECTOR INDEX ((VEC_COSINE_DISTANCE(content_vector))) +); + +-- 插入文本数据（向量会自动生成） +INSERT INTO documents (content) VALUES + ("Electric vehicles reduce air pollution in cities."), + ("Solar panels convert sunlight into renewable energy."), + ("Plant-based diets lower carbon footprints significantly."), + ("Deep learning algorithms improve medical diagnosis accuracy."), + ("Blockchain technology enhances data security systems."); + +-- 在向量索引上使用相同的 VEC_EMBED_COSINE_DISTANCE() 函数进行文本 query 的语义相似内容搜索 +SELECT id, content FROM documents +ORDER BY VEC_EMBED_COSINE_DISTANCE( + content_vector, + "Renewable energy solutions for environmental protection" +) +LIMIT 3; +``` + +> **注意：** +> +> - 定义向量索引时，使用 `VEC_COSINE_DISTANCE()` 或 `VEC_L2_DISTANCE()`。 +> - 查询时，使用 `VEC_EMBED_COSINE_DISTANCE()` 或 `VEC_EMBED_L2_DISTANCE()`。 + +## 可用文本嵌入模型 {#available-text-embedding-models} + +TiDB Cloud 支持多种嵌入模型。请选择最适合你需求的模型： + +| 嵌入模型 | 文档 | TiDB Cloud 托管 1 | BYOK 2 | +| --------------- | ----------------------------------------------------------------------------------- | ---------------------------- | ----------------- | +| Amazon Titan | [Amazon Titan Embeddings](/ai/integrations/vector-search-auto-embedding-amazon-titan.md) | ✅ | | +| Cohere | [Cohere Embeddings](/ai/integrations/vector-search-auto-embedding-cohere.md) | ✅ | ✅ | +| Jina AI | [Jina AI Embeddings](/ai/integrations/vector-search-auto-embedding-jina-ai.md) | | ✅ | +| OpenAI | [OpenAI Embeddings](/ai/integrations/vector-search-auto-embedding-openai.md) | | ✅ | +| Gemini | [Gemini Embeddings](/ai/integrations/vector-search-auto-embedding-gemini.md) | | ✅ | + +你还可以通过 TiDB Cloud 支持的以下推理服务，使用 open-source 嵌入模型： + +| 嵌入模型 | 文档 | TiDB Cloud 托管 1 | BYOK 2 | 示例支持模型 | +| ---------------------- | ----------------------------------------------------------------------------------- | ---------------------------- | ----------------- | --------------------------------- | +| Hugging Face Inference | [Hugging Face Embeddings](/ai/integrations/vector-search-auto-embedding-huggingface.md) | | ✅ | `bge-m3`, `multilingual-e5-large` | +| NVIDIA NIM | [NVIDIA NIM Embeddings](/ai/integrations/vector-search-auto-embedding-nvidia-nim.md) | | ✅ | `bge-m3`, `nv-embed-v1` | + +​1 托管模型由 TiDB Cloud 托管，无需任何 API key。目前这些托管模型可免费使用，但可能会施加一定的使用限制，以保证所有用户的可用性。 + +​2 BYOK（Bring Your Own Key）模型需要你从相应嵌入服务提供商处获取并提供 API key。TiDB Cloud 不会对 BYOK 模型的使用收费。你需自行管理和监控使用这些模型所产生的费用。 + +## Auto Embedding 的工作原理 + +Auto Embedding 使用 [`EMBED_TEXT()`](#embed_text) 函数，结合你选择的嵌入模型，将文本转换为向量嵌入。生成的向量存储在 `VECTOR` 列中，并可通过 [`VEC_EMBED_COSINE_DISTANCE()`](#vec_embed_cosine_distance) 或 [`VEC_EMBED_L2_DISTANCE()`](#vec_embed_l2_distance) 使用纯文本进行查询。 + +在内部，[`VEC_EMBED_COSINE_DISTANCE()`](#vec_embed_cosine_distance) 和 [`VEC_EMBED_L2_DISTANCE()`](#vec_embed_l2_distance) 实际执行的是 [`VEC_COSINE_DISTANCE()`](/ai/reference/vector-search-functions-and-operators.md#vec_cosine_distance) 和 [`VEC_L2_DISTANCE()`](/ai/reference/vector-search-functions-and-operators.md#vec_l2_distance)，文本 query 会自动转换为向量嵌入。 + +## 关键函数 + +### `EMBED_TEXT()` + +将文本转换为向量嵌入： + +```sql +EMBED_TEXT("model_name", text_content[, additional_json_options]) +``` + +在 `GENERATED ALWAYS AS` 子句中使用该函数，可在插入或更新文本数据时自动生成嵌入。 + +### `VEC_EMBED_COSINE_DISTANCE()` + +计算向量列中已存储向量与文本 query 之间的余弦相似度： + +```sql +VEC_EMBED_COSINE_DISTANCE(vector_column, "query_text") +``` + +在 `ORDER BY` 子句中使用该函数，可按余弦距离对结果排序。其计算方式与 [`VEC_COSINE_DISTANCE()`](/ai/reference/vector-search-functions-and-operators.md#vec_cosine_distance) 相同，但会自动为 query 文本生成嵌入。 + +### `VEC_EMBED_L2_DISTANCE()` + +计算已存储向量与文本 query 之间的 L2（欧氏）距离： + +```sql +VEC_EMBED_L2_DISTANCE(vector_column, "query_text") +``` + +在 `ORDER BY` 子句中使用该函数，可按 L2 距离对结果排序。其计算方式与 [`VEC_L2_DISTANCE()`](/ai/reference/vector-search-functions-and-operators.md#vec_l2_distance) 相同，但会自动为 query 文本生成嵌入。 + +## 在 Python 中使用 Auto Embedding {#use-auto-embedding-in-python} + +TiDB 提供了统一的接口，便于集成多种嵌入服务商和模型： + +- **编程方式**：通过 AI SDK 的 `EmbeddingFunction` 类，为特定服务商或模型创建嵌入函数。 +- **SQL 方式**：使用 `EMBED_TEXT` 函数，直接从文本数据生成嵌入。 + +使用 `EmbeddingFunction` 类可对接不同的嵌入服务商和模型。 + + ```python + from pytidb.embeddings import EmbeddingFunction + + embed_func = EmbeddingFunction( + model_name="/", + ) + ``` + +**参数说明：** + +- `model_name` *(必填)*：指定要使用的嵌入模型，格式为 `{provider_name}/{model_name}`。 + +- `dimensions` *(可选)*：输出向量嵌入的维度。如果未指定且模型无默认维度，则初始化时会嵌入一条测试字符串以自动推断实际维度。 + +- `api_key` *(可选)*：访问嵌入服务的 API key。如果未显式设置，则从服务商的默认环境变量中获取。 + +- `api_base` *(可选)*：嵌入 API 服务的基础 URL。 + +- `use_server` *(可选)*：是否使用 TiDB Cloud 托管的嵌入服务。对于 TiDB Cloud Starter，默认为 `True`。 + +- `multimodal` *(可选)*：是否使用多模态嵌入模型。启用后，`use_server` 会自动设为 `False`，嵌入服务将在客户端侧调用。 + +## 另请参阅 + +- [向量数据类型](/ai/reference/vector-search-data-types.md) +- [向量函数与操作符](/ai/reference/vector-search-functions-and-operators.md) +- [向量搜索索引](/ai/reference/vector-search-index.md) diff --git a/ai/integrations/vector-search-integrate-with-amazon-bedrock.md b/ai/integrations/vector-search-integrate-with-amazon-bedrock.md new file mode 100644 index 000000000000..afb85e2d3c19 --- /dev/null +++ b/ai/integrations/vector-search-integrate-with-amazon-bedrock.md @@ -0,0 +1,319 @@ +--- +title: 集成 TiDB 向量搜索与 Amazon Bedrock +summary: 学习如何集成 TiDB 向量搜索与 Amazon Bedrock，构建基于 RAG（检索增强生成）的问答机器人。 +aliases: ['/zh/tidbcloud/vector-search-integrate-with-amazon-bedrock/'] +--- + +# 集成 TiDB 向量搜索与 Amazon Bedrock + +> **注意：** +> +> 本文档仅适用于 TiDB Cloud，不适用 TiDB 自托管。 + +本教程演示如何将 [TiDB 向量搜索](/ai/concepts/vector-search-overview.md) 与 [Amazon Bedrock](https://aws.amazon.com/bedrock/) 集成，以构建基于 RAG（检索增强生成）的问答机器人。 + +> **注意：** +> +> - 向量搜索功能目前为 beta 版本，可能会在未提前通知的情况下发生变更。如果你发现了 bug，可以在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues)。 +> - 向量搜索功能适用于 [TiDB 自托管](/overview.md)、[TiDB Cloud Starter](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#starter)、[TiDB Cloud Essential](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#essential) 和 [TiDB Cloud Dedicated](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated)。对于 TiDB 自托管和 TiDB Cloud Dedicated，TiDB 版本需为 v8.4.0 或更高（推荐 v8.5.0 或更高）。 + +> **提示** +> +> 你可以在 Notebook 格式下查看完整的 [示例代码](https://github.com/aws-samples/aws-generativeai-partner-samples/blob/main/tidb/samples/tidb-bedrock-boto3-rag.ipynb)。 + +## 前置条件 + +完成本教程，你需要： + +- 已安装 [Python 3.11 或更高版本](https://www.python.org/downloads/) +- 已安装 [Pip](https://pypi.org/project/pip/) +- 已安装 [AWS CLI](https://aws.amazon.com/cli/) + + 确保你的 AWS CLI 配置文件已设置为受支持的 [Amazon Bedrock](https://aws.amazon.com/bedrock/) Region。你可以在 [Amazon Bedrock Regions](https://docs.aws.amazon.com/bedrock/latest/userguide/models-regions.html) 查看受支持的 Region 列表。要切换到受支持的 Region，请运行以下命令： + + ```shell + aws configure set region + ``` + +- 一个 TiDB Cloud Starter 集群 + + 如果你还没有 TiDB Cloud 集群，请参考[创建 TiDB Cloud Starter 集群](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#starter) 创建属于你自己的 TiDB Cloud 集群。 + +- 一个具有 [Amazon Bedrock 所需权限](https://docs.aws.amazon.com/bedrock/latest/userguide/security_iam_id-based-policy-examples.html) 的 AWS 账户，并且能够访问以下模型： + + - **Amazon Titan Embeddings**（`amazon.titan-embed-text-v2:0`），用于生成文本嵌入向量 + - **Meta Llama 3**（`us.meta.llama3-2-3b-instruct-v1:0`），用于文本生成 + + 如果你尚未获得访问权限，请按照 [申请访问 Amazon Bedrock 基础模型](https://docs.aws.amazon.com/bedrock/latest/userguide/getting-started.html#getting-started-model-access) 的说明操作。 + +## 开始使用 + +本节将提供分步指南，帮助你集成 TiDB 向量搜索与 Amazon Bedrock，构建基于 RAG 的问答机器人。 + +### 步骤 1. 设置环境变量 + +从 [TiDB Cloud 控制台](https://tidbcloud.com/) 获取 TiDB 连接信息，并在你的开发环境中设置环境变量，操作如下： + +1. 进入 [**Clusters**](https://tidbcloud.com/project/clusters) 页面，点击目标集群名称，进入该集群的概览页面。 + +2. 点击右上角的 **Connect**，弹出连接对话框。 + +3. 确认连接对话框中的配置与你的运行环境一致。 + + - **Connection Type** 设置为 `Public` + - **Branch** 设置为 `main` + - **Connect With** 设置为 `General` + - **Operating System** 与你的环境一致 + + > **提示：** + > + > 如果你的程序运行在 Windows Subsystem for Linux (WSL) 中，请切换到对应的 Linux 发行版。 + +4. 点击 **Generate Password** 生成随机密码。 + + > **提示：** + > + > 如果你之前已创建过密码，可以继续使用原密码，或点击 **Reset Password** 生成新密码。 + +5. 在终端中运行以下命令设置环境变量。你需要将命令中的占位符替换为连接对话框中获取的对应连接参数。 + + ```shell + export TIDB_HOST= + export TIDB_PORT=4000 + export TIDB_USER= + export TIDB_PASSWORD= + export TIDB_DB_NAME=test + ``` + +### 步骤 2. 配置 Python 虚拟环境 + +1. 创建名为 `demo.py` 的 Python 文件： + + ```shell + touch demo.py + ``` + +2. 创建并激活虚拟环境以管理依赖： + + ```shell + python3 -m venv env + source env/bin/activate # Windows 下使用 env\Scripts\activate + ``` + +3. 安装所需依赖： + + ```shell + pip install SQLAlchemy==2.0.30 PyMySQL==1.1.0 tidb-vector==0.0.9 pydantic==2.7.1 boto3 + ``` + +### 步骤 3. 导入所需库 + +在 `demo.py` 文件开头添加以下代码，导入所需库： + +```python +import os +import json +import boto3 +from sqlalchemy import Column, Integer, Text, create_engine +from sqlalchemy.orm import declarative_base, Session +from tidb_vector.sqlalchemy import VectorType +``` + +### 步骤 4. 配置数据库连接 + +在 `demo.py` 中添加以下代码，配置数据库连接： + +```python +# ---- Configuration Setup ---- +# Set environment variables: TIDB_HOST, TIDB_PORT, TIDB_USER, TIDB_PASSWORD, TIDB_DB_NAME +TIDB_HOST = os.environ.get("TIDB_HOST") +TIDB_PORT = os.environ.get("TIDB_PORT") +TIDB_USER = os.environ.get("TIDB_USER") +TIDB_PASSWORD = os.environ.get("TIDB_PASSWORD") +TIDB_DB_NAME = os.environ.get("TIDB_DB_NAME") + +# ---- Database Setup ---- +def get_db_url(): + """Build the database connection URL.""" + return f"mysql+pymysql://{TIDB_USER}:{TIDB_PASSWORD}@{TIDB_HOST}:{TIDB_PORT}/{TIDB_DB_NAME}?ssl_verify_cert=True&ssl_verify_identity=True" + +# Create engine +engine = create_engine(get_db_url(), pool_recycle=300) +Base = declarative_base() +``` + +### 步骤 5. 使用 Bedrock 运行时客户端调用 Amazon Titan Text Embeddings V2 模型 + +Amazon Bedrock 运行时客户端为你提供了 `invoke_model` API，支持以下参数： + +- `modelId`：Amazon Bedrock 可用基础模型的模型 ID。 +- `accept`：输入请求的类型。 +- `contentType`：输入的内容类型。 +- `body`：包含 prompt 和配置的 JSON 字符串负载。 + +在 `demo.py` 中添加以下代码，调用 `invoke_model` API，使用 Amazon Titan Text Embeddings 生成文本嵌入向量，并从 Meta Llama 3 获取响应： + +```python +# Bedrock Runtime Client Setup +bedrock_runtime = boto3.client('bedrock-runtime') + +# ---- Model Invocation ---- +embedding_model_name = "amazon.titan-embed-text-v2:0" +dim_of_embedding_model = 512 +llm_name = "us.meta.llama3-2-3b-instruct-v1:0" + + +def embedding(content): + """Invoke Amazon Bedrock to get text embeddings.""" + payload = { + "modelId": embedding_model_name, + "contentType": "application/json", + "accept": "*/*", + "body": { + "inputText": content, + "dimensions": dim_of_embedding_model, + "normalize": True, + } + } + + body_bytes = json.dumps(payload['body']).encode('utf-8') + + response = bedrock_runtime.invoke_model( + body=body_bytes, + contentType=payload['contentType'], + accept=payload['accept'], + modelId=payload['modelId'] + ) + + result_body = json.loads(response.get("body").read()) + return result_body.get("embedding") + + +def generate_result(query: str, info_str: str): + """Generate answer using Meta Llama 3 model.""" + prompt = f""" + ONLY use the content below to generate an answer: + {info_str} + + ---- + Please carefully think about the question: {query} + """ + + payload = { + "modelId": llm_name, + "contentType": "application/json", + "accept": "application/json", + "body": { + "prompt": prompt, + "temperature": 0 + } + } + + body_bytes = json.dumps(payload['body']).encode('utf-8') + + response = bedrock_runtime.invoke_model( + body=body_bytes, + contentType=payload['contentType'], + accept=payload['accept'], + modelId=payload['modelId'] + ) + + result_body = json.loads(response.get("body").read()) + completion = result_body["generation"] + return completion +``` + +### 步骤 6. 创建向量表 + +在 `demo.py` 中添加以下代码，创建用于存储文本及其向量嵌入的向量表： + +```python +# ---- TiDB Setup and Vector Index Creation ---- +class Entity(Base): + """Define the Entity table with a vector index.""" + __tablename__ = "entity" + id = Column(Integer, primary_key=True) + content = Column(Text) + content_vec = Column(VectorType(dim=dim_of_embedding_model), comment="hnsw(distance=l2)") + +# Create the table in TiDB +Base.metadata.create_all(engine) +``` + +### 步骤 7. 将向量数据保存到 TiDB Cloud Starter + +在 `demo.py` 中添加以下代码，将向量数据保存到你的 TiDB Cloud Starter 集群： + +```python +# ---- Saving Vectors to TiDB ---- +def save_entities_with_embedding(session, contents): + """Save multiple entities with their embeddings to the TiDB database.""" + for content in contents: + entity = Entity(content=content, content_vec=embedding(content)) + session.add(entity) + session.commit() +``` + +### 步骤 8. 运行应用 + +1. 在 `demo.py` 中添加以下代码，建立数据库会话，将嵌入向量保存到 TiDB，提出示例问题（如 "What is TiDB?"），并从模型生成结果： + + ```python + if __name__ == "__main__": + # Establish a database session + with Session(engine) as session: + # Example data + contents = [ + "TiDB is a distributed SQL database compatible with MySQL.", + "TiDB supports Hybrid Transactional and Analytical Processing (HTAP).", + "TiDB can scale horizontally and provides high availability.", + "Amazon Bedrock allows seamless integration with foundation models.", + "Meta Llama 3 is a powerful model for text generation." + ] + + # Save embeddings to TiDB + save_entities_with_embedding(session, contents) + + # Example query + query = "What is TiDB?" + info_str = " ".join(contents) + + # Generate result from Meta Llama 3 + result = generate_result(query, info_str) + print(f"Generated answer: {result}") + ``` + +2. 保存所有对 `demo.py` 的更改并运行脚本： + + ```shell + python3 demo.py + ``` + + 预期输出类似如下： + + ``` + Generated answer: What is the main purpose of TiDB? + What are the key features of TiDB? + What are the key benefits of TiDB? + + ---- + Based on the provided text, here is the answer to the question: + What is TiDB? + TiDB is a distributed SQL database compatible with MySQL. + + ## Step 1: Understand the question + The question asks for the definition of TiDB. + + ## Step 2: Identify the key information + The key information provided in the text is that TiDB is a distributed SQL database compatible with MySQL. + + ## Step 3: Provide the answer + Based on the provided text, TiDB is a distributed SQL database compatible with MySQL. + + The final answer is: TiDB is a distributed SQL database compatible with MySQL. + ``` + +## 另请参阅 + +- [向量数据类型](/ai/reference/vector-search-data-types.md) +- [向量搜索索引](/ai/reference/vector-search-index.md) diff --git a/ai/integrations/vector-search-integrate-with-django-orm.md b/ai/integrations/vector-search-integrate-with-django-orm.md new file mode 100644 index 000000000000..08b7ad3a8ab4 --- /dev/null +++ b/ai/integrations/vector-search-integrate-with-django-orm.md @@ -0,0 +1,262 @@ +--- +title: 将 TiDB 向量搜索集成到 Django ORM +summary: 学习如何将 TiDB 向量搜索集成到 Django ORM，用于存储嵌入向量并执行语义搜索。 +aliases: ['/zh/tidb/stable/vector-search-integrate-with-django-orm/','/zh/tidb/dev/vector-search-integrate-with-django-orm/','/zh/tidbcloud/vector-search-integrate-with-django-orm/'] +--- + +# 将 TiDB 向量搜索集成到 Django ORM + +本教程将指导你如何使用 [Django](https://www.djangoproject.com/) ORM 与 [TiDB 向量搜索](/ai/concepts/vector-search-overview.md) 进行交互，存储嵌入向量，并执行向量搜索查询。 + +> **注意：** +> +> - 向量搜索功能目前为 Beta 版本，可能会在没有提前通知的情况下发生变更。如果你发现了 bug，可以在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues)。 +> - 向量搜索功能适用于 [TiDB 自托管](/overview.md)、[TiDB Cloud Starter](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#starter)、[TiDB Cloud Essential](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#essential) 和 [TiDB Cloud Dedicated](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated)。对于 TiDB 自托管和 TiDB Cloud Dedicated，TiDB 版本需为 v8.4.0 或更高（推荐 v8.5.0 或更高）。 + +## 前置条件 + +完成本教程，你需要： + +- 已安装 [Python 3.8 或更高版本](https://www.python.org/downloads/)。 +- 已安装 [Git](https://git-scm.com/downloads)。 +- 一个 TiDB 集群。 + +**如果你还没有 TiDB 集群，可以按如下方式创建：** + +- （推荐）参考 [创建 TiDB Cloud Starter 集群](/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) 创建本地集群。 + +## 运行示例应用 + +你可以按照以下步骤快速学习如何将 TiDB 向量搜索集成到 Django ORM。 + +### 第 1 步：克隆仓库 + +将 `tidb-vector-python` 仓库克隆到本地： + +```shell +git clone https://github.com/pingcap/tidb-vector-python.git +``` + +### 第 2 步：创建虚拟环境 + +为你的项目创建一个虚拟环境： + +```bash +cd tidb-vector-python/examples/orm-django-quickstart +python3 -m venv .venv +source .venv/bin/activate +``` + +### 第 3 步：安装所需依赖 + +为示例项目安装所需依赖： + +```bash +pip install -r requirements.txt +``` + +或者，你也可以为你的项目单独安装以下包： + +```bash +pip install Django django-tidb mysqlclient numpy python-dotenv +``` + +如果在安装 mysqlclient 时遇到问题，请参考 mysqlclient 官方文档。 + +#### 什么是 `django-tidb`？ + +`django-tidb` 是 Django 的 TiDB 方言，增强了 Django ORM 对 TiDB 特性的支持（例如向量搜索），并解决了 TiDB 与 Django 之间的兼容性问题。 + +安装 `django-tidb` 时，请选择与你的 Django 版本相匹配的版本。例如，如果你使用的是 `django==4.2.*`，则安装 `django-tidb==4.2.*`。小版本号无需完全一致，建议使用最新的小版本。 + +更多信息请参考 [django-tidb 仓库](https://github.com/pingcap/django-tidb)。 + +### 第 4 步：配置环境变量 + +根据你选择的 TiDB 部署方式，配置环境变量。 + + +
+ +对于 TiDB Cloud Starter 集群，按如下步骤获取集群连接字符串并配置环境变量： + +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 + +2. 点击右上角的 **Connect**，弹出连接对话框。 + +3. 确保连接对话框中的配置与你的运行环境一致。 + + - **Connection Type** 设置为 `Public` + - **Branch** 设置为 `main` + - **Connect With** 设置为 `General` + - **Operating System** 与你的环境一致 + + > **提示：** + > + > 如果你的程序运行在 Windows Subsystem for Linux (WSL) 中，请切换到对应的 Linux 发行版。 + +4. 从连接对话框中复制连接参数。 + + > **提示：** + > + > 如果你还未设置密码，可点击 **Generate Password** 生成随机密码。 + +5. 在你的 Python 项目根目录下创建 `.env` 文件，并将连接参数粘贴到对应的环境变量中。 + + - `TIDB_HOST`：TiDB 集群的主机。 + - `TIDB_PORT`：TiDB 集群的端口。 + - `TIDB_USERNAME`：连接 TiDB 集群的用户名。 + - `TIDB_PASSWORD`：连接 TiDB 集群的密码。 + - `TIDB_DATABASE`：要连接的数据库名。 + - `TIDB_CA_PATH`：根证书文件的路径。 + + 以下是 macOS 的示例： + + ```dotenv + TIDB_HOST=gateway01.****.prod.aws.tidbcloud.com + TIDB_PORT=4000 + TIDB_USERNAME=********.root + TIDB_PASSWORD=******** + TIDB_DATABASE=test + TIDB_CA_PATH=/etc/ssl/cert.pem + ``` + +
+
+ +对于 TiDB 自建集群，在你的 Python 项目根目录下创建 `.env` 文件。将以下内容复制到 `.env` 文件中，并根据你的 TiDB 集群连接参数修改环境变量的值： + +```dotenv +TIDB_HOST=127.0.0.1 +TIDB_PORT=4000 +TIDB_USERNAME=root +TIDB_PASSWORD= +TIDB_DATABASE=test +``` + +如果你在本地运行 TiDB，`TIDB_HOST` 默认为 `127.0.0.1`。初始 `TIDB_PASSWORD` 为空，因此如果是首次启动集群，可以省略该字段。 + +各参数说明如下： + +- `TIDB_HOST`：TiDB 集群的主机。 +- `TIDB_PORT`：TiDB 集群的端口。 +- `TIDB_USERNAME`：连接 TiDB 集群的用户名。 +- `TIDB_PASSWORD`：连接 TiDB 集群的密码。 +- `TIDB_DATABASE`：要连接的数据库名。 + +
+ + + +### 第 5 步：运行示例 + +迁移数据库 schema： + +```bash +python manage.py migrate +``` + +运行 Django 开发服务器： + +```bash +python manage.py runserver +``` + +在浏览器中访问 `http://127.0.0.1:8000` 体验示例应用。可用的 API 路径如下： + +| API Path | 说明 | +| --------------------------------------- | -------------------------------------- | +| `POST: /insert_documents` | 插入带有嵌入向量的文档。 | +| `GET: /get_nearest_neighbors_documents` | 获取 3 个最近邻文档。 | +| `GET: /get_documents_within_distance` | 获取距离在指定范围内的文档。 | + +## 示例代码片段 + +你可以参考以下示例代码片段，完成你自己的应用开发。 + +### 连接 TiDB 集群 + +在 `sample_project/settings.py` 文件中添加如下配置： + +```python +dotenv.load_dotenv() + +DATABASES = { + "default": { + # https://github.com/pingcap/django-tidb + "ENGINE": "django_tidb", + "HOST": os.environ.get("TIDB_HOST", "127.0.0.1"), + "PORT": int(os.environ.get("TIDB_PORT", 4000)), + "USER": os.environ.get("TIDB_USERNAME", "root"), + "PASSWORD": os.environ.get("TIDB_PASSWORD", ""), + "NAME": os.environ.get("TIDB_DATABASE", "test"), + "OPTIONS": { + "charset": "utf8mb4", + }, + } +} + +TIDB_CA_PATH = os.environ.get("TIDB_CA_PATH", "") +if TIDB_CA_PATH: + DATABASES["default"]["OPTIONS"]["ssl_mode"] = "VERIFY_IDENTITY" + DATABASES["default"]["OPTIONS"]["ssl"] = { + "ca": TIDB_CA_PATH, + } +``` + +你可以在项目根目录下创建 `.env` 文件，并将 `TIDB_HOST`、`TIDB_PORT`、`TIDB_USERNAME`、`TIDB_PASSWORD`、`TIDB_DATABASE` 和 `TIDB_CA_PATH` 等环境变量设置为你实际的 TiDB 集群参数。 + +### 创建向量表 + +#### 定义向量列 + +`tidb-django` 提供了 `VectorField`，用于在表中存储向量嵌入。 + +创建一个包含名为 `embedding` 的 3 维向量列的表。 + +```python +class Document(models.Model): + content = models.TextField() + embedding = VectorField(dimensions=3) +``` + +### 存储带嵌入向量的文档 + +```python +Document.objects.create(content="dog", embedding=[1, 2, 1]) +Document.objects.create(content="fish", embedding=[1, 2, 4]) +Document.objects.create(content="tree", embedding=[1, 0, 0]) +``` + +### 搜索最近邻文档 + +TiDB 向量搜索支持以下距离函数： + +- `L1Distance` +- `L2Distance` +- `CosineDistance` +- `NegativeInnerProduct` + +基于余弦距离函数，搜索与查询向量 `[1, 2, 3]` 语义最接近的前 3 个文档。 + +```python +results = Document.objects.annotate( + distance=CosineDistance('embedding', [1, 2, 3]) +).order_by('distance')[:3] +``` + +### 搜索距离在指定范围内的文档 + +搜索与查询向量 `[1, 2, 3]` 余弦距离小于 0.2 的文档。 + +```python +results = Document.objects.annotate( + distance=CosineDistance('embedding', [1, 2, 3]) +).filter(distance__lt=0.2).order_by('distance')[:3] +``` + +## 另请参阅 + +- [向量数据类型](/ai/reference/vector-search-data-types.md) +- [向量搜索索引](/ai/reference/vector-search-index.md) diff --git a/ai/integrations/vector-search-integrate-with-jinaai-embedding.md b/ai/integrations/vector-search-integrate-with-jinaai-embedding.md new file mode 100644 index 000000000000..23bd76078db6 --- /dev/null +++ b/ai/integrations/vector-search-integrate-with-jinaai-embedding.md @@ -0,0 +1,277 @@ +--- +title: 集成 TiDB 向量搜索与 Jina AI Embeddings API +summary: 学习如何将 TiDB 向量搜索与 Jina AI Embeddings API 集成，实现 embedding 存储与语义搜索。 +aliases: ['/zh/tidb/stable/vector-search-integrate-with-jinaai-embedding/','/zh/tidb/dev/vector-search-integrate-with-jinaai-embedding/','/zh/tidbcloud/vector-search-integrate-with-jinaai-embedding/'] +--- + +# 集成 TiDB 向量搜索与 Jina AI Embeddings API + +本教程将指导你如何使用 [Jina AI](https://jina.ai/) 生成文本 embedding，将其存储到 TiDB 中，并基于 embedding 实现相似文本搜索。 + +> **注意：** +> +> - 向量搜索功能目前为 beta 版本，可能会在未提前通知的情况下发生变更。如果你发现 bug，可以在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues)。 +> - 向量搜索功能适用于 [TiDB 自托管](/overview.md)、[TiDB Cloud Starter](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#starter)、[TiDB Cloud Essential](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#essential) 和 [TiDB Cloud Dedicated](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated)。对于 TiDB 自托管和 TiDB Cloud Dedicated，TiDB 版本需为 v8.4.0 或更高（推荐 v8.5.0 或更高）。 + +## 前置条件 + +完成本教程，你需要： + +- 已安装 [Python 3.8 或更高版本](https://www.python.org/downloads/)。 +- 已安装 [Git](https://git-scm.com/downloads)。 +- 一个 TiDB 集群。 + +**如果你还没有 TiDB 集群，可以按如下方式创建：** + +- （推荐）参考 [创建 TiDB Cloud Starter 集群](/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) 创建本地集群。 + +## 运行示例应用 + +你可以按照以下步骤，快速学习如何将 TiDB 向量搜索与 Jina AI embedding 集成。 + +### 步骤 1. 克隆仓库 + +将 `tidb-vector-python` 仓库克隆到本地： + +```shell +git clone https://github.com/pingcap/tidb-vector-python.git +``` + +### 步骤 2. 创建虚拟环境 + +为你的项目创建一个虚拟环境： + +```bash +cd tidb-vector-python/examples/jina-ai-embeddings-demo +python3 -m venv .venv +source .venv/bin/activate +``` + +### 步骤 3. 安装依赖 + +为示例项目安装所需依赖： + +```bash +pip install -r requirements.txt +``` + +### 步骤 4. 配置环境变量 + +从 [Jina AI Embeddings API](https://jina.ai/embeddings/) 页面获取 Jina AI API key，然后根据你选择的 TiDB 部署方式配置环境变量。 + + +
+ +对于 TiDB Cloud Starter 集群，按以下步骤获取集群连接字符串并配置环境变量： + +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 + +2. 点击右上角的 **Connect**，弹出连接对话框。 + +3. 确保连接对话框中的配置与你的运行环境一致。 + + - **Connection Type** 设置为 `Public` + - **Branch** 设置为 `main` + - **Connect With** 设置为 `SQLAlchemy` + - **Operating System** 与你的环境一致 + + > **提示：** + > + > 如果你的程序运行在 Windows Subsystem for Linux (WSL) 中，请切换到对应的 Linux 发行版。 + +4. 切换到 **PyMySQL** 标签页，点击 **Copy** 图标复制连接字符串。 + + > **提示：** + > + > 如果你还未设置密码，请点击 **Create password** 生成随机密码。 + +5. 在终端中将 Jina AI API key 和 TiDB 连接字符串设置为环境变量，或创建 `.env` 文件，内容如下： + + ```dotenv + JINAAI_API_KEY="****" + TIDB_DATABASE_URL="{tidb_connection_string}" + ``` + + 以下是 macOS 下的连接字符串示例： + + ```dotenv + TIDB_DATABASE_URL="mysql+pymysql://.root:@gateway01..prod.aws.tidbcloud.com:4000/test?ssl_ca=/etc/ssl/cert.pem&ssl_verify_cert=true&ssl_verify_identity=true" + ``` + +
+
+ +对于 TiDB Self-Managed 集群，在终端中设置连接 TiDB 集群的环境变量： + +```shell +export JINA_API_KEY="****" +export TIDB_DATABASE_URL="mysql+pymysql://:@:/" +# 例如：export TIDB_DATABASE_URL="mysql+pymysql://root@127.0.0.1:4000/test" +``` + +你需要根据自己的 TiDB 集群替换上述命令中的参数。如果你在本地运行 TiDB，`` 默认为 `127.0.0.1`。初始 `` 为空，如果是首次启动集群，可以省略该字段。 + +各参数说明如下： + +- ``：连接 TiDB 集群的用户名。 +- ``：连接 TiDB 集群的密码。 +- ``：TiDB 集群的主机。 +- ``：TiDB 集群的端口。 +- ``：你要连接的数据库名称。 + +
+ + + +### 步骤 5. 运行示例 + +```bash +python jina-ai-embeddings-demo.py +``` + +示例输出： + +```text +- Inserting Data to TiDB... + - Inserting: Jina AI offers best-in-class embeddings, reranker and prompt optimizer, enabling advanced multimodal AI. + - Inserting: TiDB is an open-source MySQL-compatible database that supports Hybrid Transactional and Analytical Processing (HTAP) workloads. +- List All Documents and Their Distances to the Query: + - distance: 0.3585317326132522 + content: Jina AI offers best-in-class embeddings, reranker and prompt optimizer, enabling advanced multimodal AI. + - distance: 0.10858102967720984 + content: TiDB is an open-source MySQL-compatible database that supports Hybrid Transactional and Analytical Processing (HTAP) workloads. +- The Most Relevant Document and Its Distance to the Query: + - distance: 0.10858102967720984 + content: TiDB is an open-source MySQL-compatible database that supports Hybrid Transactional and Analytical Processing (HTAP) workloads. +``` + +## 示例代码片段 + +### 从 Jina AI 获取 embedding + +定义 `generate_embeddings` 辅助函数，调用 Jina AI embedding API： + +```python +import os +import requests +import dotenv + +dotenv.load_dotenv() + +JINAAI_API_KEY = os.getenv('JINAAI_API_KEY') + +def generate_embeddings(text: str): + JINAAI_API_URL = 'https://api.jina.ai/v1/embeddings' + JINAAI_HEADERS = { + 'Content-Type': 'application/json', + 'Authorization': f'Bearer {JINAAI_API_KEY}' + } + JINAAI_REQUEST_DATA = { + 'input': [text], + 'model': 'jina-embeddings-v2-base-en' # with dimension 768. + } + response = requests.post(JINAAI_API_URL, headers=JINAAI_HEADERS, json=JINAAI_REQUEST_DATA) + return response.json()['data'][0]['embedding'] +``` + +### 连接 TiDB 集群 + +通过 SQLAlchemy 连接 TiDB 集群： + +```python +import os +import dotenv + +from tidb_vector.sqlalchemy import VectorType +from sqlalchemy.orm import Session, declarative_base + +dotenv.load_dotenv() + +TIDB_DATABASE_URL = os.getenv('TIDB_DATABASE_URL') +assert TIDB_DATABASE_URL is not None +engine = create_engine(url=TIDB_DATABASE_URL, pool_recycle=300) +``` + +### 定义向量表结构 + +创建名为 `jinaai_tidb_demo_documents` 的表，包含用于存储文本的 `content` 字段和用于存储 embedding 的向量字段 `content_vec`： + +```python +from sqlalchemy import Column, Integer, String, create_engine +from sqlalchemy.orm import declarative_base + +Base = declarative_base() + +class Document(Base): + __tablename__ = "jinaai_tidb_demo_documents" + + id = Column(Integer, primary_key=True) + content = Column(String(255), nullable=False) + content_vec = Column( + # DIMENSIONS is determined by the embedding model, + # for Jina AI's jina-embeddings-v2-base-en model it's 768. + VectorType(dim=768), + comment="hnsw(distance=cosine)" +``` + +> **注意：** +> +> - 向量字段的维度必须与 embedding 模型生成的 embedding 维度一致。 +> - 本示例中，`jina-embeddings-v2-base-en` 模型生成的 embedding 维度为 `768`。 + +### 使用 Jina AI 生成 embedding 并存储到 TiDB + +使用 Jina AI Embeddings API 为每条文本生成 embedding，并将 embedding 存储到 TiDB： + +```python +TEXTS = [ + 'Jina AI offers best-in-class embeddings, reranker and prompt optimizer, enabling advanced multimodal AI.', + 'TiDB is an open-source MySQL-compatible database that supports Hybrid Transactional and Analytical Processing (HTAP) workloads.', +] +data = [] + +for text in TEXTS: + # Generate embeddings for the texts via Jina AI API. + embedding = generate_embeddings(text) + data.append({ + 'text': text, + 'embedding': embedding + }) + +with Session(engine) as session: + print('- Inserting Data to TiDB...') + for item in data: + print(f' - Inserting: {item["text"]}') + session.add(Document( + content=item['text'], + content_vec=item['embedding'] + )) + session.commit() +``` + +### 在 TiDB 中基于 Jina AI embedding 进行语义搜索 + +通过 Jina AI embedding API 为查询文本生成 embedding，然后基于 **查询文本的 embedding** 与 **向量表中每条 embedding** 的余弦距离，搜索最相关的文档： + +```python +query = 'What is TiDB?' +# Generate the embedding for the query via Jina AI API. +query_embedding = generate_embeddings(query) + +with Session(engine) as session: + print('- The Most Relevant Document and Its Distance to the Query:') + doc, distance = session.query( + Document, + Document.content_vec.cosine_distance(query_embedding).label('distance') + ).order_by( + 'distance' + ).limit(1).first() + print(f' - distance: {distance}\n' + f' content: {doc.content}') +``` + +## 另请参阅 + +- [向量数据类型](/ai/reference/vector-search-data-types.md) +- [向量搜索索引](/ai/reference/vector-search-index.md) diff --git a/vector-search-integrate-with-langchain.md b/ai/integrations/vector-search-integrate-with-langchain.md similarity index 61% rename from vector-search-integrate-with-langchain.md rename to ai/integrations/vector-search-integrate-with-langchain.md index b91a7591935d..7618f1224be1 100644 --- a/vector-search-integrate-with-langchain.md +++ b/ai/integrations/vector-search-integrate-with-langchain.md @@ -1,58 +1,60 @@ --- -title: 在 LangChain 中使用 TiDB 向量搜索 -summary: 展示如何在 LangChain 中使用 TiDB 向量搜索 +title: 集成向量搜索与 LangChain +summary: 学习如何将 TiDB 向量搜索集成到 LangChain。 +aliases: ['/zh/tidb/stable/vector-search-integrate-with-langchain/','/zh/tidb/dev/vector-search-integrate-with-langchain/','/zh/tidbcloud/vector-search-integrate-with-langchain/'] --- -# 在 LangChain 中使用 TiDB 向量搜索 +# 集成向量搜索与 LangChain -本文档将展示如何在 [LangChain](https://python.langchain.com/) 中使用 [TiDB 向量搜索](/vector-search-overview.md)。 +本教程演示如何将 [TiDB 向量搜索](/ai/concepts/vector-search-overview.md) 集成到 [LangChain](https://python.langchain.com/)。 -> **警告：** +> **注意：** > -> 向量搜索目前为实验特性，不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化。如果发现 bug，请在 GitHub 上提 [issue](https://github.com/pingcap/tidb/issues) 反馈。 +> - 向量搜索功能目前为 beta 版本，可能会在未提前通知的情况下发生变更。如果你发现了 bug，可以在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues)。 +> - 向量搜索功能适用于 [TiDB 自托管](/overview.md)、[TiDB Cloud Starter](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#starter)、[TiDB Cloud Essential](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#essential) 和 [TiDB Cloud Dedicated](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated)。对于 TiDB 自托管和 TiDB Cloud Dedicated，TiDB 版本需为 v8.4.0 或更高（推荐 v8.5.0 或更高）。 -> **Tip** +> **提示** > -> 你可以在 Jupyter Notebook 上查看完整的[示例代码](https://github.com/langchain-ai/langchain/blob/master/docs/docs/integrations/vectorstores/tidb_vector.ipynb)，也可以直接在 [Colab](https://colab.research.google.com/github/langchain-ai/langchain/blob/master/docs/docs/integrations/vectorstores/tidb_vector.ipynb) 在线环境中运行示例代码。 +> 你可以在 Jupyter Notebook 中查看完整的 [示例代码](https://github.com/langchain-ai/langchain/blob/master/docs/docs/integrations/vectorstores/tidb_vector.ipynb)，或直接在 [Colab](https://colab.research.google.com/github/langchain-ai/langchain/blob/master/docs/docs/integrations/vectorstores/tidb_vector.ipynb) 在线环境中运行。 -## 前置需求 +## 前置条件 -为了能够顺利完成本文中的操作，你需要提前： +完成本教程，你需要： -- 在你的机器上安装 [Python 3.8](https://www.python.org/downloads/) 或更高版本 -- 在你的机器上安装 [Jupyter Notebook](https://jupyter.org/install) -- 在你的机器上安装 [Git](https://git-scm.com/downloads) -- 准备一个 TiDB 集群 +- 已安装 [Python 3.8 或更高版本](https://www.python.org/downloads/)。 +- 已安装 [Jupyter Notebook](https://jupyter.org/install)。 +- 已安装 [Git](https://git-scm.com/downloads)。 +- 一个 TiDB 集群。 -如果你还没有 TiDB 集群，可以按照以下任一种方式创建： +**如果你还没有 TiDB 集群，可以按如下方式创建：** -- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 -- 参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)，创建 TiDB Cloud 集群。 +- （推荐）参考 [创建 TiDB Cloud Starter 集群](/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) 创建本地集群。 ## 快速开始 -本节将详细介绍如何将 TiDB 的向量搜索功能与 LangChain 结合使用，以实现语义搜索。 +本节将提供将 TiDB 向量搜索与 LangChain 集成以进行语义搜索的分步指导。 -### 第 1 步：新建 Jupyter Notebook 文件 +### 步骤 1. 新建 Jupyter Notebook 文件 -在根目录下，新建一个名为 `integrate_with_langchain.ipynb` 的 Jupyter Notebook 文件： +在你选择的目录下，新建一个名为 `integrate_with_langchain.ipynb` 的 Jupyter Notebook 文件： ```shell touch integrate_with_langchain.ipynb ``` -### 第 2 步：安装所需的依赖 +### 步骤 2. 安装所需依赖 -在你的项目目录下，运行以下命令安装所需的软件包： +在你的项目目录下，运行以下命令安装所需依赖包： ```shell -pip install langchain langchain-community -pip install langchain-openai -pip install pymysql -pip install tidb-vector +!pip install langchain langchain-community +!pip install langchain-openai +!pip install pymysql +!pip install tidb-vector ``` -在 Jupyter Notebook 中打开 `integrate_with_langchain.ipynb` 文件，添加以下代码以导入所需的软件包： +在 Jupyter Notebook 中打开 `integrate_with_langchain.ipynb` 文件，然后添加以下代码以导入所需包： ```python from langchain_community.document_loaders import TextLoader @@ -61,103 +63,101 @@ from langchain_openai import OpenAIEmbeddings from langchain_text_splitters import CharacterTextSplitter ``` -### 第 3 步：配置环境变量 +### 步骤 3. 配置环境 -根据 TiDB 集群的部署方式不同，选择对应的环境变量配置方式。 +根据你选择的 TiDB 部署方式，配置环境变量。 +
-
+对于 TiDB Cloud Starter 集群，按如下步骤获取集群连接字符串并配置环境变量： -本文档使用 [OpenAI](https://platform.openai.com/docs/introduction) 作为嵌入模型生成向量嵌入。在此步骤中，你需要提供集群的连接字符串和 [OpenAI API 密钥](https://platform.openai.com/docs/quickstart/step-2-set-up-your-api-key)。 +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 -运行以下代码，配置环境变量。代码运行后，系统会提示输入连接字符串和 OpenAI API 密钥： +2. 点击右上角的 **Connect**，弹出连接对话框。 -```python -# Use getpass to securely prompt for environment variables in your terminal. -import getpass -import os +3. 确认连接对话框中的配置与你的运行环境一致。 -# Connection string format: "mysql+pymysql://:@:4000/?ssl_ca=/etc/ssl/cert.pem&ssl_verify_cert=true&ssl_verify_identity=true" -tidb_connection_string = getpass.getpass("TiDB Connection String:") -os.environ["OPENAI_API_KEY"] = getpass.getpass("OpenAI API Key:") -``` + - **Connection Type** 选择 `Public`。 + - **Branch** 选择 `main`。 + - **Connect With** 选择 `SQLAlchemy`。 + - **Operating System** 选择与你环境一致的操作系统。 -以 macOS 为例，集群的连接字符串如下所示： - -```dotenv -TIDB_DATABASE_URL="mysql+pymysql://:@:/" -# 例如：TIDB_DATABASE_URL="mysql+pymysql://root@127.0.0.1:4000/test" -``` +4. 点击 **PyMySQL** 标签页，复制连接字符串。 -请替换连接字符串中的参数为你的 TiDB 实际对应的值。如果你在本机运行 TiDB，默认 `` 地址为 `127.0.0.1`。`` 初始密码为空，若你是第一次启动集群，则无需带上此字段。 + > **提示：** + > + > 如果你还未设置密码，可点击 **Generate Password** 生成随机密码。 -以下为各参数的解释： - -- ``：连接 TiDB 集群的用户名。 -- ``：连接 TiDB 集群的密码。 -- ``：TiDB 集群的主机地址。 -- ``：TiDB 集群的端口号。 -- ``：要连接的数据库名称。 +5. 配置环境变量。 -
+ 本文档以 [OpenAI](https://platform.openai.com/docs/introduction) 作为嵌入模型提供方。在此步骤，你需要提供上一步获取的连接字符串和你的 [OpenAI API key](https://platform.openai.com/docs/quickstart/step-2-set-up-your-api-key)。 -
+ 运行以下代码配置环境变量。你将被提示输入连接字符串和 OpenAI API key： -对于 TiDB Cloud Serverless 集群，请按照以下步骤获取集群的连接字符串，然后配置环境变量： + ```python + # 使用 getpass 在终端安全地输入环境变量。 + import getpass + import os -1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，单击你的 TiDB Cloud Serverless 集群名，进入集群的 **Overview** 页面。 + # 从 TiDB Cloud 控制台复制你的连接字符串。 + # 连接字符串格式："mysql+pymysql://:@:4000/?ssl_ca=/etc/ssl/cert.pem&ssl_verify_cert=true&ssl_verify_identity=true" + tidb_connection_string = getpass.getpass("TiDB Connection String:") + os.environ["OPENAI_API_KEY"] = getpass.getpass("OpenAI API Key:") + ``` -2. 点击右上角的 **Connect** 按钮，将会弹出连接对话框。 +
+
-3. 确认对话框中的配置和你的运行环境一致。 +本文档以 [OpenAI](https://platform.openai.com/docs/introduction) 作为嵌入模型提供方。在此步骤，你需要提供上一步获取的连接字符串和你的 [OpenAI API key](https://platform.openai.com/docs/quickstart/step-2-set-up-your-api-key)。 - - **Connection Type** 为 `Public`。 - - **Branch** 选择 `main`。 - - **Connect With** 选择 `SQLAlchemy`。 - - **Operating System** 为你的运行环境。 +运行以下代码配置环境变量。你将被提示输入连接字符串和 OpenAI API key： -4. 点击 **PyMySQL** 选项卡，复制连接字符串。 +```python +# 使用 getpass 在终端安全地输入环境变量。 +import getpass +import os - > **Tip:** - > - > 如果你还没有设置密码，点击 **Generate Password** 生成一个随机密码。 +# 连接字符串格式："mysql+pymysql://:@:4000/?ssl_ca=/etc/ssl/cert.pem&ssl_verify_cert=true&ssl_verify_identity=true" +tidb_connection_string = getpass.getpass("TiDB Connection String:") +os.environ["OPENAI_API_KEY"] = getpass.getpass("OpenAI API Key:") +``` -5. 配置环境变量。 +以 macOS 为例，集群连接字符串如下： - 本文档使用 [OpenAI](https://platform.openai.com/docs/introduction) 作为嵌入模型生成向量嵌入。在此步骤中，你需要提供从上一步中获取的连接字符串和 [OpenAI API 密钥](https://platform.openai.com/docs/quickstart/step-2-set-up-your-api-key)。 +```dotenv +TIDB_DATABASE_URL="mysql+pymysql://:@:/" +# 例如：TIDB_DATABASE_URL="mysql+pymysql://root@127.0.0.1:4000/test" +``` - 运行以下代码，配置环境变量。代码运行后，系统会提示输入连接字符串和 OpenAI API 密钥： +你需要根据你的 TiDB 集群实际情况修改连接参数的值。如果你在本地运行 TiDB，`` 默认为 `127.0.0.1`。初始 `` 为空，因此首次启动集群时可以省略该字段。 - ```python - # Use getpass to securely prompt for environment variables in your terminal. - import getpass - import os +各参数说明如下： - # Copy your connection string from the TiDB Cloud console. - # Connection string format: "mysql+pymysql://:@:4000/?ssl_ca=/etc/ssl/cert.pem&ssl_verify_cert=true&ssl_verify_identity=true" - tidb_connection_string = getpass.getpass("TiDB Connection String:") - os.environ["OPENAI_API_KEY"] = getpass.getpass("OpenAI API Key:") - ``` +- ``：连接 TiDB 集群的用户名。 +- ``：连接 TiDB 集群的密码。 +- ``：TiDB 集群的主机。 +- ``：TiDB 集群的端口。 +- ``：你要连接的数据库名称。
-### 第 4 步：加载样本文档 +### 步骤 4. 加载示例文档 -#### 4.1 下载样本文档 +#### 步骤 4.1 下载示例文档 -在你的项目目录中创建一个名为 `data/how_to/` 的目录，然后从 [langchain-ai/langchain](https://github.com/langchain-ai/langchain) 代码库中下载样本文档 [`state_of_the_union.txt`](https://github.com/langchain-ai/langchain/blob/master/docs/docs/how_to/state_of_the_union.txt)。 +在你的项目目录下，新建 `data/how_to/` 目录，并从 [langchain-ai/langchain](https://github.com/langchain-ai/langchain) GitHub 仓库下载示例文档 [`state_of_the_union.txt`](https://github.com/langchain-ai/langchain/blob/master/docs/docs/how_to/state_of_the_union.txt)。 ```shell -mkdir -p 'data/how_to/' -wget 'https://raw.githubusercontent.com/langchain-ai/langchain/master/docs/docs/how_to/state_of_the_union.txt' -O 'data/how_to/state_of_the_union.txt' +!mkdir -p 'data/how_to/' +!wget 'https://raw.githubusercontent.com/langchain-ai/langchain/master/docs/docs/how_to/state_of_the_union.txt' -O 'data/how_to/state_of_the_union.txt' ``` -#### 4.2 加载并分割文档 +#### 步骤 4.2 加载并切分文档 -从 `data/how_to/state_of_the_union.txt` 中加载示例文档，并使用 `CharacterTextSplitter` 将其分割成每块约 1000 个字符的文本块。 +从 `data/how_to/state_of_the_union.txt` 加载示例文档，并使用 `CharacterTextSplitter` 将其切分为约 1,000 个字符的块。 ```python loader = TextLoader("data/how_to/state_of_the_union.txt") @@ -166,11 +166,11 @@ text_splitter = CharacterTextSplitter(chunk_size=1000, chunk_overlap=0) docs = text_splitter.split_documents(documents) ``` -### 第 5 步：生成并存储文档向量 +### 步骤 5. 嵌入并存储文档向量 -TiDB 支持使用余弦距离 (`cosine`) 和欧式距离 (`L2`) 来评估向量之间的相似性。在存储向量时，默认使用余弦距离。 +TiDB 向量存储支持余弦距离（`cosine`）和欧氏距离（`l2`）两种向量相似度度量方式。默认策略为余弦距离。 -以下代码将在 TiDB 中创建一个 `embedded_documents` 表，该表针对向量搜索进行了优化。 +以下代码将在 TiDB 中创建一个名为 `embedded_documents` 的表，该表已针对向量搜索进行了优化。 ```python embeddings = OpenAIEmbeddings() @@ -179,23 +179,23 @@ vector_store = TiDBVectorStore.from_documents( embedding=embeddings, table_name="embedded_documents", connection_string=tidb_connection_string, - distance_strategy="cosine", # default, another option is "l2" + distance_strategy="cosine", # 默认，另一个选项为 "l2" ) ``` -成功执行后，你可以直接查看和访问 TiDB 数据库中的 `embedded_documents` 表。 +执行成功后，你可以直接在 TiDB 数据库中查看和访问 `embedded_documents` 表。 -### 第 6 步：执行向量搜索 +### 步骤 6. 执行向量搜索 -本节将展示如何在 `state_of_the_union.txt` 文档中查询 "What did the president say about Ketanji Brown Jackson"。 +本步骤演示如何在文档 `state_of_the_union.txt` 中搜索 “What did the president say about Ketanji Brown Jackson”。 ```python query = "What did the president say about Ketanji Brown Jackson" ``` -#### 方式一：使用 `similarity_search_with_score()` +#### 选项 1：使用 `similarity_search_with_score()` -`similarity_search_with_score()` 方法用于计算文档内容与查询语句之间的向量距离。该距离是一个相似度的得分，其计算方式由所选的 `distance_strategy` 决定。该方法会返回得分最低的前 `k` 个文档。得分越低，说明文档与你的查询语句之间的相似度越高。 +`similarity_search_with_score()` 方法会计算文档与查询在向量空间中的距离。该距离作为相似度分数，由所选的 `distance_strategy` 决定。该方法返回分数最低的前 `k` 个文档。分数越低，文档与查询的相似度越高。 ```python docs_with_score = vector_store.similarity_search_with_score(query, k=3) @@ -252,9 +252,9 @@ First, beat the opioid epidemic. -#### 方式二：使用 `similarity_search_with_relevance_scores()` 方法 +#### 选项 2：使用 `similarity_search_with_relevance_scores()` -`similarity_search_with_relevance_scores()` 方法会返回相关性得分最高的前 `k`个文档。分数越高，说明文档内容与你的查询语句之间的相似度越高。 +`similarity_search_with_relevance_scores()` 方法返回相关性分数最高的前 `k` 个文档。分数越高，文档与查询的相似度越高。 ```python docs_with_relevance_score = vector_store.similarity_search_with_relevance_scores(query, k=2) @@ -297,9 +297,9 @@ We’re securing commitments and supporting partners in South and Central Americ -### 用作检索器 +### 作为检索器使用 -在 Langchain 中，[检索器](https://python.langchain.com/v0.2/docs/concepts/#retrievers)是一个接口，用于响应非结构化查询，检索相关文档。相比于向量存储，检索器可以为你提供更多的功能。以下代码演示了如何将 TiDB 向量存储用作检索器。 +在 LangChain 中，[retriever](https://python.langchain.com/v0.2/docs/concepts/#retrievers) 是一个用于非结构化查询搜索文档的接口，功能比向量存储更丰富。以下代码演示如何将 TiDB 向量存储作为检索器使用。 ```python retriever = vector_store.as_retriever( @@ -329,25 +329,25 @@ And I did that 4 days ago, when I nominated Circuit Court of Appeals Judge Ketan ### 移除向量存储 -要删除现有的 TiDB 向量存储，可以使用 `drop_vectorstore()` 方法： +如需移除已存在的 TiDB 向量存储，可使用 `drop_vectorstore()` 方法： ```python vector_store.drop_vectorstore() ``` -## 使用元数据过滤器进行搜索 +## 使用元信息过滤进行搜索 -为了优化搜索，你可以使用元数据过滤器来筛选出符合特定条件的近邻结果。 +你可以通过元信息过滤，进一步筛选搜索结果，仅返回符合过滤条件的最近邻结果。 -### 支持的元数据类型 +### 支持的元信息类型 -在 TiDB 向量存储中，每个文档都可以与元数据配对。元数据的结构是 JSON 对象中的键值对 (key-value pairs) 形式。键 (key) 的类型是字符串，而值 (value) 可以是以下任何类型： +TiDB 向量存储中的每个文档都可以携带元信息，结构为 JSON 对象的键值对。键始终为字符串，值可以是以下类型之一： - 字符串 -- 数值：整数或浮点数 -- Boolean：`true` 或 `false` +- 数值：整数型或浮点型 +- 布尔型：`true` 或 `false` -例如，下面是一个有效的元数据格式： +例如，以下是一个有效的元信息负载： ```json { @@ -356,22 +356,22 @@ vector_store.drop_vectorstore() } ``` -### 元数据过滤器语法 +### 元信息过滤语法 可用的过滤器包括： -- `$or`：选择符合任意一个指定条件的向量。 -- `$and`：选择符合所有指定条件的向量。 +- `$or`：匹配任意一个条件的向量。 +- `$and`：同时匹配所有条件的向量。 - `$eq`：等于指定值。 - `$ne`：不等于指定值。 - `$gt`：大于指定值。 -- `$gte`：大于或等于指定值。 +- `$gte`：大于等于指定值。 - `$lt`：小于指定值。 -- `$lte`：小于或等于指定值。 -- `$in`：在指定的值数组中。 +- `$lte`：小于等于指定值。 +- `$in`：在指定值数组中。 - `$nin`：不在指定值数组中。 -假如一个文档的元数据如下： +如果某文档的元信息如下： ```json { @@ -380,7 +380,7 @@ vector_store.drop_vectorstore() } ``` -以下元数据筛选器均可匹配到该文档： +以下元信息过滤器均可匹配该文档： ```json { "page": 12 } @@ -413,11 +413,11 @@ vector_store.drop_vectorstore() } ``` -TiDB 会将元数据过滤器中的每个键值对视为一个独立的过滤条件，并使用 `AND` 逻辑操作符将这些条件组合起来。 +在元信息过滤器中，TiDB 会将每个键值对视为独立的过滤子句，并使用 `AND` 逻辑运算符将这些子句组合。 ### 示例 -以下示例代码向 `TiDBVectorStore` 添加了两个文档，并为每个文档添加了一个 `title` 字段作为元数据： +以下示例向 `TiDBVectorStore` 添加两个文档，并为每个文档添加 `title` 字段作为元信息： ```python vector_store.add_texts( @@ -439,7 +439,7 @@ vector_store.add_texts( UUID('08dcd2ba-9f16-4f29-a9b7-18141f8edae3')] ``` -使用元数据过滤器进行相似性搜索： +使用元信息过滤器进行相似度搜索： ```python docs_with_score = vector_store.similarity_search_with_score( @@ -461,21 +461,21 @@ TiDB Vector offers advanced, high-speed vector processing capabilities, enhancin -------------------------------------------------------------------------------- ``` -## 进阶用法示例：旅行代理 +## 高级用例示例：旅行社 -本节演示如何将 Langchain 和 TiDB 向量搜索相结合，应用于旅行代理的场景。该场景的目标是为客户创建个性化的旅行报告，帮助他们找到具备特定设施（例如干净的休息室和素食选项）的机场。 +本节演示将向量搜索与 LangChain 集成的旅行社场景。目标是为客户生成个性化旅行报告，帮助他们查找拥有特定设施（如干净的休息室和素食选项）的机场。 -该示例包括两个主要步骤： +流程主要分为两步： -1. 对机场介绍中进行语义搜索，以找出符合所需设施的机场代码。 -2. 执行 SQL 查询，将这些代码与航线信息相结合，以便突出显示符合用户偏好的航空公司和目的地。 +1. 对机场评论进行语义搜索，找出符合所需设施的机场代码。 +2. 执行 SQL 查询，将这些代码与航线信息关联，突出显示符合用户偏好的航空公司和目的地。 ### 准备数据 -首先，创建一个表来存储机场航线数据： +首先，创建用于存储机场航线数据的表： ```python -# 创建表格以存储飞行计划数据。 +# 创建用于存储航班计划数据的表。 vector_store.tidb_vector_client.execute( """CREATE TABLE airplan_routes ( id INT AUTO_INCREMENT PRIMARY KEY, @@ -491,7 +491,7 @@ vector_store.tidb_vector_client.execute( );""" ) -# 在 airplan_routes 和向量表中插入一些样本数据。 +# 向 airplan_routes 和向量表插入一些示例数据。 vector_store.tidb_vector_client.execute( """INSERT INTO airplan_routes ( airport_code, @@ -533,7 +533,7 @@ vector_store.add_texts( ### 执行语义搜索 -以下代码可以搜索到有清洁设施和素食选择的机场： +以下代码搜索拥有干净设施和素食选项的机场： ```python retriever = vector_store.as_retriever( @@ -562,15 +562,15 @@ Comfortable seating in lounge areas and diverse food selections, including veget -------------------------------------------------------------------------------- ``` -### 检索详细的机场信息 +### 获取机场详细信息 -从搜索结果中提取机场代码，查询数据库中的详细航线信息： +从搜索结果中提取机场代码，并查询数据库获取详细航线信息： ```python -# Extracting airport codes from the metadata +# 从元信息中提取机场代码 airport_codes = [review.metadata["airport_code"] for review in reviews] -# Executing a query to get the airport details +# 执行查询获取机场详情 search_query = "SELECT * FROM airplan_routes WHERE airport_code IN :codes" params = {"codes": tuple(airport_codes)} @@ -585,14 +585,14 @@ airport_details.get("result") (2, 'LAX', 'AA', 'ORD', 'Direct LAX to ORD route.', datetime.timedelta(seconds=14400), 3, 'Airbus A320', Decimal('149.99'), 'None')] ``` -### 简化流程 +### 流程简化 -你也可以使用单个 SQL 查询来简化整个流程： +你也可以通过单条 SQL 查询简化整个流程： ```python search_query = f""" SELECT - VEC_Cosine_Distance(se.embedding, :query_vector) as distance, + VEC_COSINE_DISTANCE(se.embedding, :query_vector) as distance, ar.*, se.document as airport_review FROM @@ -618,7 +618,7 @@ airport_details.get("result") ### 清理数据 -最后，删除创建的表，清理资源： +最后，通过删除创建的表来清理资源： ```python vector_store.tidb_vector_client.execute("DROP TABLE airplan_routes") @@ -630,7 +630,7 @@ vector_store.tidb_vector_client.execute("DROP TABLE airplan_routes") {'success': True, 'result': 0, 'error': None} ``` -## 另请参阅 +## 相关文档 -- [向量数据类型](/vector-search-data-types.md) -- [向量搜索索引](/vector-search-index.md) \ No newline at end of file +- [向量数据类型](/ai/reference/vector-search-data-types.md) +- [向量搜索索引](/ai/reference/vector-search-index.md) diff --git a/ai/integrations/vector-search-integrate-with-llamaindex.md b/ai/integrations/vector-search-integrate-with-llamaindex.md new file mode 100644 index 000000000000..5b24c3276e0d --- /dev/null +++ b/ai/integrations/vector-search-integrate-with-llamaindex.md @@ -0,0 +1,316 @@ +--- +title: 集成向量搜索与 LlamaIndex +summary: 学习如何将 TiDB 向量搜索与 LlamaIndex 集成。 +aliases: ['/zh/tidb/stable/vector-search-integrate-with-llamaindex/','/zh/tidb/dev/vector-search-integrate-with-llamaindex/','/zh/tidbcloud/vector-search-integrate-with-llamaindex/'] +--- + +# 集成向量搜索与 LlamaIndex + +本教程演示如何将 [TiDB 向量搜索](/ai/concepts/vector-search-overview.md) 与 [LlamaIndex](https://www.llamaindex.ai) 集成。 + +> **注意：** +> +> - 向量搜索功能目前为 beta 版本，可能会在未提前通知的情况下发生变更。如果你发现了 bug，可以在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues)。 +> - 向量搜索功能适用于 [TiDB 自托管](/overview.md)、[TiDB Cloud Starter](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#starter)、[TiDB Cloud Essential](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#essential) 和 [TiDB Cloud Dedicated](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated)。对于 TiDB 自托管和 TiDB Cloud Dedicated，TiDB 版本需为 v8.4.0 或更高（推荐 v8.5.0 或更高）。 + +> **提示** +> +> 你可以在 Jupyter Notebook 中查看完整的 [示例代码](https://github.com/run-llama/llama_index/blob/main/docs/docs/examples/vector_stores/TiDBVector.ipynb)，或直接在 [Colab](https://colab.research.google.com/github/run-llama/llama_index/blob/main/docs/docs/examples/vector_stores/TiDBVector.ipynb) 在线环境中运行。 + +## 前置条件 + +完成本教程，你需要： + +- 已安装 [Python 3.8 或更高版本](https://www.python.org/downloads/)。 +- 已安装 [Jupyter Notebook](https://jupyter.org/install)。 +- 已安装 [Git](https://git-scm.com/downloads)。 +- 一个 TiDB 集群。 + +**如果你还没有 TiDB 集群，可以按如下方式创建：** + +- （推荐）参照 [创建 TiDB Cloud Starter 集群](/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) 创建本地集群。 + +## 快速开始 + +本节将提供分步指导，帮助你将 TiDB 向量搜索与 LlamaIndex 集成，实现语义搜索。 + +### 步骤 1. 新建 Jupyter Notebook 文件 + +在根目录下新建一个名为 `integrate_with_llamaindex.ipynb` 的 Jupyter Notebook 文件： + +```shell +touch integrate_with_llamaindex.ipynb +``` + +### 步骤 2. 安装所需依赖 + +在你的项目目录下，运行以下命令安装所需的依赖包： + +```shell +pip install llama-index-vector-stores-tidbvector +pip install llama-index +``` + +在 Jupyter Notebook 中打开 `integrate_with_llamaindex.ipynb` 文件，并添加以下代码以导入所需包： + +```python +import textwrap + +from llama_index.core import SimpleDirectoryReader, StorageContext +from llama_index.core import VectorStoreIndex +from llama_index.vector_stores.tidbvector import TiDBVectorStore +``` + +### 步骤 3. 配置环境变量 + +根据你选择的 TiDB 部署方式，配置环境变量。 + + +
+ +对于 TiDB Cloud Starter 集群，按以下步骤获取集群连接字符串并配置环境变量： + +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入其概览页面。 + +2. 点击右上角的 **Connect**，弹出连接对话框。 + +3. 确认连接对话框中的配置与你的运行环境一致。 + + - **Connection Type** 设置为 `Public`。 + - **Branch** 设置为 `main`。 + - **Connect With** 设置为 `SQLAlchemy`。 + - **Operating System** 与你的环境一致。 + +4. 点击 **PyMySQL** 标签页，复制连接字符串。 + + > **提示：** + > + > 如果你还未设置密码，可点击 **Generate Password** 生成随机密码。 + +5. 配置环境变量。 + + 本文档以 [OpenAI](https://platform.openai.com/docs/introduction) 作为嵌入模型提供方。在此步骤中，你需要提供上一步获取的连接字符串和你的 [OpenAI API key](https://platform.openai.com/docs/quickstart/step-2-set-up-your-api-key)。 + + 运行以下代码配置环境变量。你将被提示输入连接字符串和 OpenAI API key： + + ```python + # 使用 getpass 在终端安全地输入环境变量。 + import getpass + import os + + # 从 TiDB Cloud 控制台复制你的连接字符串。 + # 连接字符串格式："mysql+pymysql://:@:4000/?ssl_ca=/etc/ssl/cert.pem&ssl_verify_cert=true&ssl_verify_identity=true" + tidb_connection_string = getpass.getpass("TiDB Connection String:") + os.environ["OPENAI_API_KEY"] = getpass.getpass("OpenAI API Key:") + ``` + +
+
+ +本文档以 [OpenAI](https://platform.openai.com/docs/introduction) 作为嵌入模型提供方。在此步骤中，你需要提供 TiDB 集群的连接字符串和你的 [OpenAI API key](https://platform.openai.com/docs/quickstart/step-2-set-up-your-api-key)。 + +运行以下代码配置环境变量。你将被提示输入连接字符串和 OpenAI API key： + +```python +# 使用 getpass 在终端安全地输入环境变量。 +import getpass +import os + +# 连接字符串格式："mysql+pymysql://:@:4000/?ssl_ca=/etc/ssl/cert.pem&ssl_verify_cert=true&ssl_verify_identity=true" +tidb_connection_string = getpass.getpass("TiDB Connection String:") +os.environ["OPENAI_API_KEY"] = getpass.getpass("OpenAI API Key:") +``` + +以 macOS 为例，集群连接字符串如下： + +```dotenv +TIDB_DATABASE_URL="mysql+pymysql://:@:/" +# 例如：TIDB_DATABASE_URL="mysql+pymysql://root@127.0.0.1:4000/test" +``` + +你需要根据自己的 TiDB 集群修改连接字符串中的参数。如果你在本地运行 TiDB，`` 默认为 `127.0.0.1`。初始 `` 为空，因此首次启动集群时可以省略该字段。 + +各参数说明如下： + +- ``：连接 TiDB 集群的用户名。 +- ``：连接 TiDB 集群的密码。 +- ``：TiDB 集群的主机。 +- ``：TiDB 集群的端口。 +- ``：你要连接的数据库名称。 + +
+ + + +### 步骤 4. 加载示例文档 + +#### 步骤 4.1 下载示例文档 + +在你的项目目录下，新建 `data/paul_graham/` 目录，并从 [run-llama/llama_index](https://github.com/run-llama/llama_index) GitHub 仓库下载示例文档 [`paul_graham_essay.txt`](https://github.com/run-llama/llama_index/blob/main/docs/docs/examples/data/paul_graham/paul_graham_essay.txt)。 + +```shell +!mkdir -p 'data/paul_graham/' +!wget 'https://raw.githubusercontent.com/run-llama/llama_index/main/docs/docs/examples/data/paul_graham/paul_graham_essay.txt' -O 'data/paul_graham/paul_graham_essay.txt' +``` + +#### 步骤 4.2 加载文档 + +使用 `SimpleDirectoryReader` 类从 `data/paul_graham/paul_graham_essay.txt` 加载示例文档。 + +```python +documents = SimpleDirectoryReader("./data/paul_graham").load_data() +print("Document ID:", documents[0].doc_id) + +for index, document in enumerate(documents): + document.metadata = {"book": "paul_graham"} +``` + +### 步骤 5. 嵌入并存储文档向量 + +#### 步骤 5.1 初始化 TiDB 向量存储 + +以下代码将在 TiDB 中创建一个名为 `paul_graham_test` 的表，并针对向量搜索进行了优化。 + +```python +tidbvec = TiDBVectorStore( + connection_string=tidb_connection_string, + table_name="paul_graham_test", + distance_strategy="cosine", + vector_dimension=1536, + drop_existing_table=False, +) +``` + +执行成功后，你可以在 TiDB 数据库中直接查看和访问 `paul_graham_test` 表。 + +#### 步骤 5.2 生成并存储嵌入向量 + +以下代码将解析文档、生成嵌入向量，并将其存储到 TiDB 向量存储中。 + +```python +storage_context = StorageContext.from_defaults(vector_store=tidbvec) +index = VectorStoreIndex.from_documents( + documents, storage_context=storage_context, show_progress=True +) +``` + +预期输出如下： + +```plain +Parsing nodes: 100%|██████████| 1/1 [00:00<00:00, 8.76it/s] +Generating embeddings: 100%|██████████| 21/21 [00:02<00:00, 8.22it/s] +``` + +### 步骤 6. 执行向量搜索 + +以下代码基于 TiDB 向量存储创建查询引擎，并执行语义相似度搜索。 + +```python +query_engine = index.as_query_engine() +response = query_engine.query("What did the author do?") +print(textwrap.fill(str(response), 100)) +``` + +> **注意** +> +> `TiDBVectorStore` 仅支持 [`default`](https://docs.llamaindex.ai/en/stable/api_reference/storage/vector_store/?h=vectorstorequerymode#llama_index.core.vector_stores.types.VectorStoreQueryMode) 查询模式。 + +预期输出如下： + +```plain +The author worked on writing, programming, building microcomputers, giving talks at conferences, +publishing essays online, developing spam filters, painting, hosting dinner parties, and purchasing +a building for office use. +``` + +### 步骤 7. 使用元信息过滤器进行搜索 + +为了进一步优化搜索结果，你可以使用元信息过滤器，仅搜索符合过滤条件的最近邻结果。 + +#### 使用 `book != "paul_graham"` 过滤器查询 + +以下示例将排除 `metadata` 字段 `book` 为 `"paul_graham"` 的结果： + +```python +from llama_index.core.vector_stores.types import ( + MetadataFilter, + MetadataFilters, +) + +query_engine = index.as_query_engine( + filters=MetadataFilters( + filters=[ + MetadataFilter(key="book", value="paul_graham", operator="!="), + ] + ), + similarity_top_k=2, +) +response = query_engine.query("What did the author learn?") +print(textwrap.fill(str(response), 100)) +``` + +预期输出如下： + +```plain +Empty Response +``` + +#### 使用 `book == "paul_graham"` 过滤器查询 + +以下示例仅返回 `metadata` 字段 `book` 为 `"paul_graham"` 的文档： + +```python +from llama_index.core.vector_stores.types import ( + MetadataFilter, + MetadataFilters, +) + +query_engine = index.as_query_engine( + filters=MetadataFilters( + filters=[ + MetadataFilter(key="book", value="paul_graham", operator="=="), + ] + ), + similarity_top_k=2, +) +response = query_engine.query("What did the author learn?") +print(textwrap.fill(str(response), 100)) +``` + +预期输出如下： + +```plain +The author learned programming on an IBM 1401 using an early version of Fortran in 9th grade, then +later transitioned to working with microcomputers like the TRS-80 and Apple II. Additionally, the +author studied philosophy in college but found it unfulfilling, leading to a switch to studying AI. +Later on, the author attended art school in both the US and Italy, where they observed a lack of +substantial teaching in the painting department. +``` + +### 步骤 8. 删除文档 + +从索引中删除第一个文档： + +```python +tidbvec.delete(documents[0].doc_id) +``` + +检查文档是否已被删除： + +```python +query_engine = index.as_query_engine() +response = query_engine.query("What did the author learn?") +print(textwrap.fill(str(response), 100)) +``` + +预期输出如下： + +```plain +Empty Response +``` + +## 另请参阅 + +- [向量数据类型](/ai/reference/vector-search-data-types.md) +- [向量搜索索引](/ai/reference/vector-search-index.md) diff --git a/ai/integrations/vector-search-integrate-with-peewee.md b/ai/integrations/vector-search-integrate-with-peewee.md new file mode 100644 index 000000000000..3c43d6ec5f87 --- /dev/null +++ b/ai/integrations/vector-search-integrate-with-peewee.md @@ -0,0 +1,252 @@ +--- +title: 集成 TiDB 向量搜索与 peewee +summary: 学习如何将 TiDB 向量搜索与 peewee 集成，以存储嵌入向量并执行语义搜索。 +aliases: ['/zh/tidb/stable/vector-search-integrate-with-peewee/','/zh/tidb/dev/vector-search-integrate-with-peewee/','/zh/tidbcloud/vector-search-integrate-with-peewee/'] +--- + +# 集成 TiDB 向量搜索与 peewee + +本教程将指导你如何使用 [peewee](https://docs.peewee-orm.com/) 与 [TiDB 向量搜索](/ai/concepts/vector-search-overview.md) 进行交互，存储嵌入向量，并执行向量搜索查询。 + +> **注意：** +> +> - 向量搜索功能目前为 beta 版本，可能会在未提前通知的情况下发生变更。如果你发现了 bug，可以在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues)。 +> - 向量搜索功能适用于 [TiDB 自托管](/overview.md)、[TiDB Cloud Starter](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#starter)、[TiDB Cloud Essential](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#essential) 和 [TiDB Cloud Dedicated](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated)。对于 TiDB 自托管和 TiDB Cloud Dedicated，TiDB 版本需为 v8.4.0 或更高（推荐 v8.5.0 或更高）。 + +## 前置条件 + +完成本教程，你需要： + +- 已安装 [Python 3.8 或更高版本](https://www.python.org/downloads/)。 +- 已安装 [Git](https://git-scm.com/downloads)。 +- 一个 TiDB 集群。 + +**如果你还没有 TiDB 集群，可以按如下方式创建：** + +- （推荐）参考 [创建 TiDB Cloud Starter 集群](/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) 创建本地集群。 + +## 运行示例应用 + +你可以按照以下步骤快速学习如何将 TiDB 向量搜索与 peewee 集成。 + +### 第 1 步：克隆仓库 + +将 [`tidb-vector-python`](https://github.com/pingcap/tidb-vector-python) 仓库克隆到本地： + +```shell +git clone https://github.com/pingcap/tidb-vector-python.git +``` + +### 第 2 步：创建虚拟环境 + +为你的项目创建虚拟环境： + +```bash +cd tidb-vector-python/examples/orm-peewee-quickstart +python3 -m venv .venv +source .venv/bin/activate +``` + +### 第 3 步：安装所需依赖 + +为示例项目安装所需依赖： + +```bash +pip install -r requirements.txt +``` + +或者，你也可以为你的项目单独安装以下包： + +```bash +pip install peewee pymysql python-dotenv tidb-vector +``` + +### 第 4 步：配置环境变量 + +根据你选择的 TiDB 部署方式配置环境变量。 + + +
+ +对于 TiDB Cloud Starter 集群，按如下步骤获取集群连接字符串并配置环境变量： + +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入其概览页面。 + +2. 点击右上角的 **Connect**，弹出连接对话框。 + +3. 确保连接对话框中的配置与你的运行环境一致。 + + - **Connection Type** 设置为 `Public`。 + - **Branch** 设置为 `main`。 + - **Connect With** 设置为 `General`。 + - **Operating System** 与你的环境一致。 + + > **提示：** + > + > 如果你的程序运行在 Windows Subsystem for Linux (WSL) 中，请切换到对应的 Linux 发行版。 + +4. 从连接对话框中复制连接参数。 + + > **提示：** + > + > 如果你还未设置密码，请点击 **Generate Password** 生成随机密码。 + +5. 在 Python 项目的根目录下创建 `.env` 文件，并将连接参数粘贴到对应的环境变量中。 + + - `TIDB_HOST`：TiDB 集群的主机。 + - `TIDB_PORT`：TiDB 集群的端口。 + - `TIDB_USERNAME`：连接 TiDB 集群的用户名。 + - `TIDB_PASSWORD`：连接 TiDB 集群的密码。 + - `TIDB_DATABASE`：要连接的数据库名称。 + - `TIDB_CA_PATH`：根证书文件的路径。 + + 以下为 macOS 示例： + + ```dotenv + TIDB_HOST=gateway01.****.prod.aws.tidbcloud.com + TIDB_PORT=4000 + TIDB_USERNAME=********.root + TIDB_PASSWORD=******** + TIDB_DATABASE=test + TIDB_CA_PATH=/etc/ssl/cert.pem + ``` + +
+
+ +对于自托管的 TiDB 集群，在 Python 项目的根目录下创建 `.env` 文件。将以下内容复制到 `.env` 文件中，并根据你的 TiDB 集群连接参数修改环境变量的值： + +```dotenv +TIDB_HOST=127.0.0.1 +TIDB_PORT=4000 +TIDB_USERNAME=root +TIDB_PASSWORD= +TIDB_DATABASE=test +``` + +如果你在本地运行 TiDB，`TIDB_HOST` 默认为 `127.0.0.1`。初始 `TIDB_PASSWORD` 为空，因此如果是首次启动集群，可以省略该字段。 + +各参数说明如下： + +- `TIDB_HOST`：TiDB 集群的主机。 +- `TIDB_PORT`：TiDB 集群的端口。 +- `TIDB_USERNAME`：连接 TiDB 集群的用户名。 +- `TIDB_PASSWORD`：连接 TiDB 集群的密码。 +- `TIDB_DATABASE`：你要连接的数据库名称。 + +
+ + + +### 第 5 步：运行示例 + +```bash +python peewee-quickstart.py +``` + +示例输出： + +```text +Get 3-nearest neighbor documents: + - distance: 0.00853986601633272 + document: fish + - distance: 0.12712843905603044 + document: dog + - distance: 0.7327387580875756 + document: tree +Get documents within a certain distance: + - distance: 0.00853986601633272 + document: fish + - distance: 0.12712843905603044 + document: dog +``` + +## 示例代码片段 + +你可以参考以下示例代码片段开发你的应用。 + +### 创建向量表 + +#### 连接 TiDB 集群 + +```python +import os +import dotenv + +from peewee import Model, MySQLDatabase, SQL, TextField +from tidb_vector.peewee import VectorField + +dotenv.load_dotenv() + +# Using `pymysql` as the driver. +connect_kwargs = { + 'ssl_verify_cert': True, + 'ssl_verify_identity': True, +} + +# Using `mysqlclient` as the driver. +# connect_kwargs = { +# 'ssl_mode': 'VERIFY_IDENTITY', +# 'ssl': { +# # Root certificate default path +# # https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-clusters/#root-certificate-default-path +# 'ca': os.environ.get('TIDB_CA_PATH', '/path/to/ca.pem'), +# }, +# } + +db = MySQLDatabase( + database=os.environ.get('TIDB_DATABASE', 'test'), + user=os.environ.get('TIDB_USERNAME', 'root'), + password=os.environ.get('TIDB_PASSWORD', ''), + host=os.environ.get('TIDB_HOST', 'localhost'), + port=int(os.environ.get('TIDB_PORT', '4000')), + **connect_kwargs, +) +``` + +#### 定义向量列 + +创建一个包含名为 `peewee_demo_documents` 的表，并存储 3 维向量。 + +```python +class Document(Model): + class Meta: + database = db + table_name = 'peewee_demo_documents' + + content = TextField() + embedding = VectorField(3) +``` + +### 存储带嵌入向量的文档 + +```python +Document.create(content='dog', embedding=[1, 2, 1]) +Document.create(content='fish', embedding=[1, 2, 4]) +Document.create(content='tree', embedding=[1, 0, 0]) +``` + +### 搜索最近邻文档 + +基于余弦距离函数，搜索与查询向量 `[1, 2, 3]` 语义最接近的前 3 个文档。 + +```python +distance = Document.embedding.cosine_distance([1, 2, 3]).alias('distance') +results = Document.select(Document, distance).order_by(distance).limit(3) +``` + +### 搜索距离在指定范围内的文档 + +搜索与查询向量 `[1, 2, 3]` 的余弦距离小于 0.2 的文档。 + +```python +distance_expression = Document.embedding.cosine_distance([1, 2, 3]) +distance = distance_expression.alias('distance') +results = Document.select(Document, distance).where(distance_expression < 0.2).order_by(distance).limit(3) +``` + +## 另请参阅 + +- [向量数据类型](/ai/reference/vector-search-data-types.md) +- [向量搜索索引](/ai/reference/vector-search-index.md) diff --git a/ai/integrations/vector-search-integrate-with-sqlalchemy.md b/ai/integrations/vector-search-integrate-with-sqlalchemy.md new file mode 100644 index 000000000000..2d87de409c6e --- /dev/null +++ b/ai/integrations/vector-search-integrate-with-sqlalchemy.md @@ -0,0 +1,223 @@ +--- +title: 集成 TiDB 向量搜索与 SQLAlchemy +summary: 学习如何将 TiDB 向量搜索与 SQLAlchemy 集成，以存储嵌入向量并执行语义搜索。 +aliases: ['/zh/tidb/stable/vector-search-integrate-with-sqlalchemy/','/zh/tidb/dev/vector-search-integrate-with-sqlalchemy/','/zh/tidbcloud/vector-search-integrate-with-sqlalchemy/'] +--- + +# 集成 TiDB 向量搜索与 SQLAlchemy + +本教程将指导你如何使用 [SQLAlchemy](https://www.sqlalchemy.org/) 与 [TiDB 向量搜索](/ai/concepts/vector-search-overview.md) 进行交互，存储嵌入向量，并执行向量搜索查询。 + +> **注意：** +> +> - 向量搜索功能目前为 beta 版本，可能会在无提前通知的情况下发生变更。如果你发现了 bug，可以在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues)。 +> - 向量搜索功能适用于 [TiDB 自托管](/overview.md)、[TiDB Cloud Starter](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#starter)、[TiDB Cloud Essential](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#essential) 和 [TiDB Cloud Dedicated](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated)。对于 TiDB 自托管和 TiDB Cloud Dedicated，TiDB 版本需为 v8.4.0 或更高（推荐 v8.5.0 及以上）。 + +## 前置条件 + +完成本教程，你需要： + +- 已安装 [Python 3.8 或更高版本](https://www.python.org/downloads/)。 +- 已安装 [Git](https://git-scm.com/downloads)。 +- 一个 TiDB 集群。 + +**如果你还没有 TiDB 集群，可以按如下方式创建：** + +- （推荐）参考 [创建 TiDB Cloud Starter 集群](/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) 创建本地集群。 + +## 运行示例应用 + +你可以按照以下步骤快速学习如何将 TiDB 向量搜索与 SQLAlchemy 集成。 + +### 第 1 步：克隆仓库 + +将 `tidb-vector-python` 仓库克隆到本地： + +```shell +git clone https://github.com/pingcap/tidb-vector-python.git +``` + +### 第 2 步：创建虚拟环境 + +为你的项目创建一个虚拟环境： + +```bash +cd tidb-vector-python/examples/orm-sqlalchemy-quickstart +python3 -m venv .venv +source .venv/bin/activate +``` + +### 第 3 步：安装所需依赖 + +为示例项目安装所需依赖： + +```bash +pip install -r requirements.txt +``` + +或者，你也可以为你的项目单独安装以下包： + +```bash +pip install pymysql python-dotenv sqlalchemy tidb-vector +``` + +### 第 4 步：配置环境变量 + +根据你选择的 TiDB 部署方式配置环境变量。 + + +
+ +对于 TiDB Cloud Starter 集群，按以下步骤获取集群连接字符串并配置环境变量： + +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 + +2. 点击右上角的 **Connect**，弹出连接对话框。 + +3. 确认连接对话框中的配置与你的环境一致。 + + - **Connection Type** 设置为 `Public`。 + - **Branch** 设置为 `main`。 + - **Connect With** 设置为 `SQLAlchemy`。 + - **Operating System** 与你的环境一致。 + + > **提示：** + > + > 如果你的程序运行在 Windows Subsystem for Linux (WSL) 中，请切换到对应的 Linux 发行版。 + +4. 点击 **PyMySQL** 标签页并复制连接字符串。 + + > **提示：** + > + > 如果你还未设置密码，可点击 **Generate Password** 生成随机密码。 + +5. 在你的 Python 项目根目录下创建 `.env` 文件，并将连接字符串粘贴进去。 + + 以下为 macOS 示例： + + ```dotenv + TIDB_DATABASE_URL="mysql+pymysql://.root:@gateway01..prod.aws.tidbcloud.com:4000/test?ssl_ca=/etc/ssl/cert.pem&ssl_verify_cert=true&ssl_verify_identity=true" + ``` + +
+
+ +对于自托管的 TiDB 集群，在你的 Python 项目根目录下创建 `.env` 文件。将以下内容复制到 `.env` 文件中，并根据你的 TiDB 集群连接参数修改环境变量的值： + +```dotenv +TIDB_DATABASE_URL="mysql+pymysql://:@:/" +# 例如：TIDB_DATABASE_URL="mysql+pymysql://root@127.0.0.1:4000/test" +``` + +如果你在本地运行 TiDB，`` 默认为 `127.0.0.1`。初始 `` 为空，因此如果是首次启动集群，可以省略该字段。 + +各参数说明如下： + +- ``：连接 TiDB 集群的用户名。 +- ``：连接 TiDB 集群的密码。 +- ``：TiDB 集群的主机。 +- ``：TiDB 集群的端口。 +- ``：你要连接的数据库名称。 + +
+ + + +### 第 5 步：运行示例 + +```bash +python sqlalchemy-quickstart.py +``` + +示例输出： + +```text +Get 3-nearest neighbor documents: + - distance: 0.00853986601633272 + document: fish + - distance: 0.12712843905603044 + document: dog + - distance: 0.7327387580875756 + document: tree +Get documents within a certain distance: + - distance: 0.00853986601633272 + document: fish + - distance: 0.12712843905603044 + document: dog +``` + +## 示例代码片段 + +你可以参考以下示例代码片段开发你的应用。 + +### 创建向量表 + +#### 连接 TiDB 集群 + +```python +import os +import dotenv + +from sqlalchemy import Column, Integer, create_engine, Text +from sqlalchemy.orm import declarative_base, Session +from tidb_vector.sqlalchemy import VectorType + +dotenv.load_dotenv() + +tidb_connection_string = os.environ['TIDB_DATABASE_URL'] +engine = create_engine(tidb_connection_string) +``` + +#### 定义向量列 + +创建一个包含名为 `embedding` 的 3 维向量列的表。 + +```python +Base = declarative_base() + +class Document(Base): + __tablename__ = 'sqlalchemy_demo_documents' + id = Column(Integer, primary_key=True) + content = Column(Text) + embedding = Column(VectorType(3)) +``` + +### 存储带嵌入向量的文档 + +```python +with Session(engine) as session: + session.add(Document(content="dog", embedding=[1, 2, 1])) + session.add(Document(content="fish", embedding=[1, 2, 4])) + session.add(Document(content="tree", embedding=[1, 0, 0])) + session.commit() +``` + +### 搜索最近邻文档 + +基于余弦距离函数，搜索与查询向量 `[1, 2, 3]` 语义最接近的前 3 个文档。 + +```python +with Session(engine) as session: + distance = Document.embedding.cosine_distance([1, 2, 3]).label('distance') + results = session.query( + Document, distance + ).order_by(distance).limit(3).all() +``` + +### 搜索距离在指定范围内的文档 + +搜索与查询向量 `[1, 2, 3]` 余弦距离小于 0.2 的文档。 + +```python +with Session(engine) as session: + distance = Document.embedding.cosine_distance([1, 2, 3]).label('distance') + results = session.query( + Document, distance + ).filter(distance < 0.2).order_by(distance).limit(3).all() +``` + +## 另请参阅 + +- [向量数据类型](/ai/reference/vector-search-data-types.md) +- [向量搜索索引](/ai/reference/vector-search-index.md) diff --git a/ai/integrations/vector-search-integration-overview.md b/ai/integrations/vector-search-integration-overview.md new file mode 100644 index 000000000000..38547e5b9b77 --- /dev/null +++ b/ai/integrations/vector-search-integration-overview.md @@ -0,0 +1,50 @@ +--- +title: 向量搜索集成概览 +summary: TiDB 向量搜索集成的概览，包括支持的 AI 框架、嵌入模型和 ORM 库。 +aliases: ['/zh/tidb/stable/vector-search-integration-overview/','/zh/tidb/dev/vector-search-integration-overview/','/zh/tidbcloud/vector-search-integration-overview/'] +--- + +# 向量搜索集成概览 + +本文档概述了 TiDB 向量搜索的集成方式，包括支持的 AI 框架、嵌入模型和对象关系映射（ORM）库。 + +> **注意：** +> +> - 向量搜索功能目前为 beta 版本，可能会在未提前通知的情况下发生变更。如果你发现了 bug，可以在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues)。 +> - 向量搜索功能适用于 [TiDB 自托管](/overview.md)、[TiDB Cloud Starter](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#starter)、[TiDB Cloud Essential](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#essential) 和 [TiDB Cloud Dedicated](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated)。对于 TiDB 自托管和 TiDB Cloud Dedicated，TiDB 版本需为 v8.4.0 或更高（推荐 v8.5.0 或更高）。 + +## AI 框架 + +TiDB 官方支持以下 AI 框架，帮助你轻松将基于这些框架开发的 AI 应用与 TiDB 向量搜索集成。 + +| AI 框架 | 教程 | +|--------------|----------------------------------------------------------------------------------------------| +| LangChain | [与 LangChain 集成向量搜索](/ai/integrations/vector-search-integrate-with-langchain.md) | +| LlamaIndex | [与 LlamaIndex 集成向量搜索](/ai/integrations/vector-search-integrate-with-llamaindex.md) | + +你还可以将 TiDB 用于 AI 应用的文档存储、知识图谱存储等多种场景。 + +## 嵌入模型与服务 + +TiDB 向量搜索支持存储最多 16383 维的向量，能够满足大多数嵌入模型的需求。 + +你可以使用自部署的开源嵌入模型，或第三方嵌入 API 生成向量。 + +下表列出了一些主流嵌入服务提供商及其对应的集成教程。 + +| 嵌入服务提供商 | 教程 | +|----------------|-------------------------------------------------------------------------------------------------------------| +| Jina AI | [与 Jina AI Embeddings API 集成向量搜索](/ai/integrations/vector-search-integrate-with-jinaai-embedding.md) | + +## 对象关系映射（ORM）库 + +你可以将 TiDB 向量搜索与 ORM 库集成，以便与 TiDB 数据库进行交互。 + +下表列出了支持的 ORM 库及其对应的集成教程： + +| 语言 | ORM/客户端 | 安装说明 | 教程 | +|----------|--------------------|-----------------------------------|----------| +| Python | TiDB Vector Client | `pip install tidb-vector[client]` | [使用 Python 开始向量搜索](/ai/quickstart-via-python.md) | +| Python | SQLAlchemy | `pip install tidb-vector` | [集成 TiDB 向量搜索与 SQLAlchemy](/ai/integrations/vector-search-integrate-with-sqlalchemy.md) +| Python | peewee | `pip install tidb-vector` | [集成 TiDB 向量搜索与 peewee](/ai/integrations/vector-search-integrate-with-peewee.md) | +| Python | Django | `pip install django-tidb[vector]` | [将 TiDB 向量搜索集成到 Django ORM](/ai/integrations/vector-search-integrate-with-django-orm.md) \ No newline at end of file diff --git a/ai/quickstart-via-python.md b/ai/quickstart-via-python.md new file mode 100644 index 000000000000..25903f6ead98 --- /dev/null +++ b/ai/quickstart-via-python.md @@ -0,0 +1,245 @@ +--- +title: 使用 Python 快速上手 TiDB + AI +summary: 学习如何使用 Python SDK 在 TiDB 中开始向量搜索。 +aliases: ['/zh/tidb/stable/vector-search-get-started-using-python/','/zh/tidb/dev/vector-search-get-started-using-python/','/zh/tidbcloud/vector-search-get-started-using-python/'] +--- + +# 使用 Python 快速上手 TiDB + AI + +本文档演示了如何使用 Python SDK 在 TiDB 中开始 [向量搜索](/ai/concepts/vector-search-overview.md)。跟随本文中的步骤，你将构建你的第一个基于 TiDB 的 AI 应用。 + +通过学习本教程，你将掌握： + +- 使用 TiDB Python SDK 连接 TiDB。 +- 利用主流嵌入模型生成文本嵌入向量。 +- 将向量存储到 TiDB 表中。 +- 使用向量相似度进行语义搜索。 + +> **注意：** +> +> - 向量搜索功能目前为 beta 版本，可能会在未提前通知的情况下发生变更。如果你发现了 bug，可以在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues)。 +> - 向量搜索功能适用于 [TiDB 自托管](/overview.md)、[TiDB Cloud Starter](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#starter)、[TiDB Cloud Essential](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#essential) 和 [TiDB Cloud Dedicated](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated)。对于 TiDB 自托管和 TiDB Cloud Dedicated，TiDB 版本需为 v8.4.0 或更高（推荐 v8.5.0 及以上）。 + +## 前置条件 + +- 访问 [tidbcloud.com](https://tidbcloud.com/) 免费创建一个 TiDB Cloud Starter 集群，或使用 [tiup playground](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb/#deploy-a-local-test-cluster) 在本地部署一个 TiDB 集群进行测试。 + +## 安装 + +[pytidb](https://github.com/pingcap/pytidb) 是官方的 TiDB Python SDK，旨在帮助开发者高效构建 AI 应用。 + +安装 Python SDK，请运行以下命令： + +```bash +pip install pytidb +``` + +如需使用内置嵌入 function，可安装 `models` 扩展（可选）： + +```bash +pip install "pytidb[models]" +``` + +## 连接数据库 + + +
+ +你可以在 [TiDB Cloud 控制台](https://tidbcloud.com/clusters) 获取这些连接参数： + +1. 进入 [Clusters 页面](https://tidbcloud.com/clusters)，点击目标集群名称进入其概览页面。 +2. 点击右上角的 **Connect**。此时会弹出连接对话框，显示连接参数。 + +例如，连接参数如下所示： + +```text +HOST: gateway01.us-east-1.prod.shared.aws.tidbcloud.com +PORT: 4000 +USERNAME: 4EfqPF23YKBxaQb.root +PASSWORD: abcd1234 +DATABASE: test +CA: /etc/ssl/cert.pem +``` + +对应的 Python 代码如下，用于连接 TiDB Cloud Starter 集群： + +```python +from pytidb import TiDBClient + +client = TiDBClient.connect( + host="gateway01.us-east-1.prod.shared.aws.tidbcloud.com", + port=4000, + username="4EfqPF23YKBxaQb.root", + password="abcd1234", + database="test", +) +``` + +> **注意：** +> +> 上述示例仅用于演示。你需要使用你自己的参数，并妥善保管。 + +
+
+ +以下是连接 TiDB 自托管的基本示例： + +```python +from pytidb import TiDBClient + +client = TiDBClient.connect( + host="localhost", + port=4000, + username="root", + password="", + database="test", + ensure_db=True, +) +``` + +> **注意：** +> +> 请根据你的实际部署情况 update 连接参数。 + +
+ + +连接成功后，你可以使用 `client` 对象进行表操作、数据查询等。 + +## 创建嵌入 function + +在使用 [嵌入模型](/ai/concepts/vector-search-overview.md#embedding-model) 时，你可以利用嵌入 function 在插入和查询阶段自动将数据向量化。该功能原生支持 OpenAI、Jina AI、Hugging Face、Sentence Transformers 等主流嵌入模型。 + + +
+ +前往 [OpenAI 平台](https://platform.openai.com/api-keys) 创建你的 API key 用于嵌入。 + +```python +from pytidb.embeddings import EmbeddingFunction + +text_embed = EmbeddingFunction( + model_name="openai/text-embedding-3-small", + api_key="", +) +``` + +
+
+ +前往 [Jina AI](https://jina.ai/embeddings/) 创建你的 API key 用于嵌入。 + +```python +from pytidb.embeddings import EmbeddingFunction + +text_embed = EmbeddingFunction( + model_name="jina/jina-embeddings-v3", + api_key="", +) +``` + +
+ + +## 创建表 + +例如，创建一个名为 `chunks` 的表，包含以下字段： + +- `id` (int)：chunk 的 ID。 +- `text` (text)：chunk 的文本内容。 +- `text_vec` (vector)：文本的向量嵌入。 +- `user_id` (int)：创建该 chunk 的用户 ID。 + +```python hl_lines="6" +from pytidb.schema import TableModel, Field, VectorField + +class Chunk(TableModel): + id: int | None = Field(default=None, primary_key=True) + text: str = Field() + text_vec: list[float] = text_embed.VectorField(source_field="text") + user_id: int = Field() + +table = client.create_table(schema=Chunk, if_exists="overwrite") +``` + +创建完成后，你可以使用 `table` 对象插入数据、搜索数据等。 + +## 插入数据 + +现在让我们向表中添加一些示例数据。 + +```python +table.bulk_insert([ + # 👇 文本会被 Auto Embedding 并填充到 `text_vec` 字段中。 + Chunk(text="PyTiDB is a Python library for developers to connect to TiDB.", user_id=2), + Chunk(text="LlamaIndex is a framework for building AI applications.", user_id=2), + Chunk(text="OpenAI is a company and platform that provides AI models service and tools.", user_id=3), +]) +``` + +## 搜索最近邻 + +要搜索给定 query 的最近邻，可以使用 `table.search()` method。该 method 默认执行 [向量搜索](/ai/guides/vector-search.md)。 + +```python +table.search( + # 👇 直接传入 query 文本，会 Auto Embedding 为 query 向量。 + "A library for my artificial intelligence software" +) +.limit(3).to_list() +``` + +在本例中，向量搜索会将 query 向量与 `chunks` 表中 `text_vec` 字段存储的向量进行比较，并根据相似度得分返回最相关的前 3 条结果。 + +`_distance` 越小，表示两个向量越相似。 + +```json title="期望输出" +[ + { + 'id': 2, + 'text': 'LlamaIndex is a framework for building AI applications.', + 'text_vec': [...], + 'user_id': 2, + '_distance': 0.5719928358786761, + '_score': 0.4280071641213239 + }, + { + 'id': 3, + 'text': 'OpenAI is a company and platform that provides AI models service and tools.', + 'text_vec': [...], + 'user_id': 3, + '_distance': 0.603133726213383, + '_score': 0.396866273786617 + }, + { + 'id': 1, + 'text': 'PyTiDB is a Python library for developers to connect to TiDB.', + 'text_vec': [...], + 'user_id': 2, + '_distance': 0.6202191842385758, + '_score': 0.3797808157614242 + } +] +``` + +## 删除数据 + +要从表中删除指定行，可以使用 `table.delete()` method： + +```python +table.delete({ + "id": 1 +}) +``` + +## 删除表 + +当你不再需要某个表时，可以使用 `client.drop_table()` method 删除： + +```python +client.drop_table("chunks") +``` + +## 后续步骤 + +- 了解 TiDB 中 [向量搜索](/ai/guides/vector-search.md)、[全文搜索](/ai/guides/vector-search-full-text-search-python.md) 和 [混合搜索](/ai/guides/vector-search-hybrid-search.md) 的更多细节。 \ No newline at end of file diff --git a/ai/quickstart-via-sql.md b/ai/quickstart-via-sql.md new file mode 100644 index 000000000000..c960d3e9a477 --- /dev/null +++ b/ai/quickstart-via-sql.md @@ -0,0 +1,177 @@ +--- +title: 通过 SQL 快速上手 TiDB + AI +summary: 学习如何仅使用 SQL 语句快速上手 TiDB 向量搜索，为你的生成式 AI 应用提供支持。 +aliases: ['/zh/tidb/stable/vector-search-get-started-using-sql/','/zh/tidb/dev/vector-search-get-started-using-sql/','/zh/tidbcloud/vector-search-get-started-using-sql/'] +--- + +# 通过 SQL 快速上手 TiDB + AI + +TiDB 扩展了 MySQL 语法以支持[向量搜索](/ai/concepts/vector-search-overview.md)，并引入了新的[向量数据类型](/ai/reference/vector-search-data-types.md)以及若干[向量函数](/ai/reference/vector-search-functions-and-operators.md)。 + +本文档演示了如何仅使用 SQL 语句快速上手 TiDB 向量搜索。你将学习如何使用 [MySQL 命令行客户端](https://dev.mysql.com/doc/refman/8.4/en/mysql.html)完成以下操作： + +- 连接到你的 TiDB 集群。 +- 创建向量表。 +- 存储向量嵌入。 +- 执行向量搜索查询。 + +> **注意：** +> +> - 向量搜索功能目前为 beta 版本，可能会在未提前通知的情况下发生变更。如果你发现了 bug，可以在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues)。 +> - 向量搜索功能适用于 [TiDB 自托管](/overview.md)、[TiDB Cloud Starter](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#starter)、[TiDB Cloud Essential](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#essential) 和 [TiDB Cloud Dedicated](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated)。对于 TiDB 自托管和 TiDB Cloud Dedicated，TiDB 版本需为 v8.4.0 或更高（推荐 v8.5.0 或更高）。 + +## 前置条件 + +要完成本文档中的步骤，你需要： + +- 在本地安装 [MySQL 命令行客户端](https://dev.mysql.com/doc/refman/8.4/en/mysql.html)（MySQL CLI）。 +- 一个 TiDB 集群。 + +**如果你还没有 TiDB 集群，可以按如下方式创建：** + +- （推荐）参考[创建 TiDB Cloud Starter 集群](/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)来创建本地集群。 + +## 快速上手 + +### 步骤 1. 连接到 TiDB 集群 + +根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。 + + +
+ +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，然后点击目标集群名称进入其概览页面。 + +2. 点击右上角的 **Connect**，弹出连接对话框。 + +3. 在连接对话框中，从 **Connect With** 下拉列表中选择 **MySQL CLI**，并保持 **Connection Type** 的默认设置为 **Public**。 + +4. 如果你还未设置密码，点击 **Generate Password** 生成一个随机密码。 + +5. 复制连接命令并粘贴到你的终端中。以下是 macOS 的示例： + + ```bash + mysql -u '.root' -h '' -P 4000 -D 'test' --ssl-mode=VERIFY_IDENTITY --ssl-ca=/etc/ssl/cert.pem -p'' + ``` + +
+
+ +当你自托管的 TiDB 集群启动后，在终端中执行集群连接命令。 + +以下是 macOS 的示例连接命令： + +```bash +mysql --comments --host 127.0.0.1 --port 4000 -u root +``` + +
+ + + +### 步骤 2. 创建向量表 + +在创建表时，你可以通过指定 `VECTOR` 数据类型，将某一列定义为[向量](/ai/concepts/vector-search-overview.md#vector-embedding)列。 + +例如，要创建一个包含三维 `VECTOR` 列的 `embedded_documents` 表，可在 MySQL CLI 中执行如下 SQL 语句： + +```sql +USE test; +CREATE TABLE embedded_documents ( + id INT PRIMARY KEY, + -- Column to store the original content of the document. + document TEXT, + -- Column to store the vector representation of the document. + embedding VECTOR(3) +); +``` + +预期输出如下： + +```text +Query OK, 0 rows affected (0.27 sec) +``` + +### 步骤 3. 向表中插入向量嵌入 + +向 `embedded_documents` 表中插入三条带有[向量嵌入](/ai/concepts/vector-search-overview.md#vector-embedding)的文档： + +```sql +INSERT INTO embedded_documents +VALUES + (1, 'dog', '[1,2,1]'), + (2, 'fish', '[1,2,4]'), + (3, 'tree', '[1,0,0]'); +``` + +预期输出如下： + +``` +Query OK, 3 rows affected (0.15 sec) +Records: 3 Duplicates: 0 Warnings: 0 +``` + +> **注意** +> +> 本示例简化了向量嵌入的维度，仅使用三维向量进行演示。 +> +> 在实际应用中，[嵌入模型](/ai/concepts/vector-search-overview.md#embedding-model)通常会生成数百甚至数千维的向量嵌入。 + +### 步骤 4. 查询向量表 + +为验证文档是否已正确插入，可查询 `embedded_documents` 表： + +```sql +SELECT * FROM embedded_documents; +``` + +预期输出如下： + +```sql ++----+----------+-----------+ +| id | document | embedding | ++----+----------+-----------+ +| 1 | dog | [1,2,1] | +| 2 | fish | [1,2,4] | +| 3 | tree | [1,0,0] | ++----+----------+-----------+ +3 rows in set (0.15 sec) +``` + +### 步骤 5. 执行向量搜索查询 + +与全文搜索类似，用户在使用向量搜索时会向应用提供搜索词。 + +本例中，搜索词为 “a swimming animal”，其对应的向量嵌入假定为 `[1,2,3]`。在实际应用中，你需要使用嵌入模型将用户的搜索词转换为向量嵌入。 + +执行如下 SQL 语句，TiDB 会通过计算并排序表中向量嵌入与 `[1,2,3]` 的余弦距离（`vec_cosine_distance`），找出距离最近的三条文档。 + +```sql +SELECT id, document, vec_cosine_distance(embedding, '[1,2,3]') AS distance +FROM embedded_documents +ORDER BY distance +LIMIT 3; +``` + +预期输出如下： + +```plain ++----+----------+---------------------+ +| id | document | distance | ++----+----------+---------------------+ +| 2 | fish | 0.00853986601633272 | +| 1 | dog | 0.12712843905603044 | +| 3 | tree | 0.7327387580875756 | ++----+----------+---------------------+ +3 rows in set (0.15 sec) +``` + +搜索结果中的三条数据按照与查询向量的距离升序排列：距离越小，`document` 与搜索向量的相关性越高。 + +因此，根据输出，最有可能的“swimming animal”是 fish，其次可能是会游泳的 dog。 + +## 另请参阅 + +- [向量数据类型](/ai/reference/vector-search-data-types.md) +- [向量搜索索引](/ai/reference/vector-search-index.md) diff --git a/ai/reference/vector-search-changelogs.md b/ai/reference/vector-search-changelogs.md new file mode 100644 index 000000000000..17632e056500 --- /dev/null +++ b/ai/reference/vector-search-changelogs.md @@ -0,0 +1,19 @@ +--- +title: 向量搜索更新日志 +summary: 了解 TiDB 向量搜索功能的新特性、兼容性变更、改进和缺陷修复。 +aliases: ['/zh/tidbcloud/vector-search-changelogs/'] +--- + +# 向量搜索更新日志 + +## 2025 年 7 月 15 日 + +- TiDB 向量搜索（beta）现已在 TiDB Cloud Dedicated（TiDB >= v8.4）集群中可用。 + +## 2024 年 6 月 25 日 + +- TiDB 向量搜索（beta）现已在所有区域的 TiDB Cloud Starter 集群中对所有用户开放。 + +## 2024 年 4 月 1 日 + +- TiDB 向量搜索（beta）现已在 EU 区域的 TiDB Cloud Starter 集群中对受邀用户开放。 \ No newline at end of file diff --git a/ai/reference/vector-search-data-types.md b/ai/reference/vector-search-data-types.md new file mode 100644 index 000000000000..eeb6c03d66ba --- /dev/null +++ b/ai/reference/vector-search-data-types.md @@ -0,0 +1,248 @@ +--- +title: 向量数据类型 +summary: 了解 TiDB 中的向量数据类型。 +aliases: ['/zh/tidb/stable/vector-search-data-types/','/zh/tidb/dev/vector-search-data-types/','/zh/tidbcloud/vector-search-data-types/'] +--- + +# 向量数据类型 + +向量是一组浮点数序列，例如 `[0.3, 0.5, -0.1, ...]`。TiDB 提供了向量数据类型，专门针对高效存储和查询在 AI 应用中广泛使用的向量嵌入进行了优化。 + +> **注意：** +> +> - 向量数据类型目前为 Beta 版本，可能会在未提前通知的情况下发生变更。如果你发现了 bug，可以在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues)。 +> - 向量数据类型适用于 [TiDB 自托管](/overview.md)、[TiDB Cloud Starter](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#starter)、[TiDB Cloud Essential](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#essential) 和 [TiDB Cloud Dedicated](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated)。对于 TiDB 自托管和 TiDB Cloud Dedicated，TiDB 版本需为 v8.4.0 或更高（推荐 v8.5.0 或更高）。 + +目前支持以下向量数据类型： + +- `VECTOR`：任意维度的单精度浮点数序列。 +- `VECTOR(D)`：固定维度 `D` 的单精度浮点数序列。 + +与使用 [`JSON`](/data-type-json.md) 类型相比，使用向量数据类型具有以下优势： + +- 支持向量索引：你可以构建 [向量搜索索引](/ai/reference/vector-search-index.md) 来加速向量搜索。 +- 维度约束：你可以指定维度，禁止插入不同维度的向量。 +- 优化的存储格式：向量数据类型针对向量数据进行了优化，空间效率和性能优于 `JSON` 类型。 + +## 语法 + +你可以使用如下语法的字符串来表示一个向量值： + +```sql +'[, , ...]' +``` + +示例： + +```sql +CREATE TABLE vector_table ( + id INT PRIMARY KEY, + embedding VECTOR(3) +); + +INSERT INTO vector_table VALUES (1, '[0.3, 0.5, -0.1]'); + +INSERT INTO vector_table VALUES (2, NULL); +``` + +插入语法不合法的向量值会报错： + +```sql +[tidb]> INSERT INTO vector_table VALUES (3, '[5, ]'); +ERROR 1105 (HY000): Invalid vector text: [5, ] +``` + +在下例中，由于在建表时为 `embedding` 列指定了维度 `3`，插入不同维度的向量会报错： + +```sql +[tidb]> INSERT INTO vector_table VALUES (4, '[0.3, 0.5]'); +ERROR 1105 (HY000): vector has 2 dimensions, does not fit VECTOR(3) +``` + +关于向量数据类型可用的函数和运算符，参见 [向量函数与运算符](/ai/reference/vector-search-functions-and-operators.md)。 + +关于如何构建和使用向量搜索索引，参见 [向量搜索索引](/ai/reference/vector-search-index.md)。 + +## 存储不同维度的向量 + +你可以通过在 `VECTOR` 类型中省略维度参数，在同一列中存储不同维度的向量： + +```sql +CREATE TABLE vector_table ( + id INT PRIMARY KEY, + embedding VECTOR +); + +INSERT INTO vector_table VALUES (1, '[0.3, 0.5, -0.1]'); -- 3 维向量，OK +INSERT INTO vector_table VALUES (2, '[0.3, 0.5]'); -- 2 维向量，OK +``` + +但需要注意的是，你无法为该列构建 [向量搜索索引](/ai/reference/vector-search-index.md)，因为只有相同维度的向量之间才能计算向量距离。 + +## 比较 {#comparison} + +你可以使用 [比较运算符](/functions-and-operators/operators.md)（如 `=`, `!=`, `<`, `>`, `<=`, `>=`）对向量数据类型进行比较。关于向量数据类型的完整比较运算符和函数列表，参见 [向量函数与运算符](/ai/reference/vector-search-functions-and-operators.md)。 + +向量数据类型按元素逐一进行数值比较。例如： + +- `[1] < [12]` +- `[1,2,3] < [1,2,5]` +- `[1,2,3] = [1,2,3]` +- `[2,2,3] > [1,2,3]` + +对于不同维度的两个向量，采用字典序比较，规则如下： + +- 两个向量从头开始逐元素比较，每个元素按数值比较。 +- 第一个不相等的元素决定哪个向量在字典序上 _更小_ 或 _更大_。 +- 如果一个向量是另一个向量的前缀，则较短的向量在字典序上 _更小_。例如，`[1,2,3] < [1,2,3,0]`。 +- 长度相同且元素完全相同的两个向量在字典序上 _相等_。 +- 空向量在字典序上 _小于_ 任何非空向量。例如，`[] < [1]`。 +- 两个空向量在字典序上 _相等_。 + +在比较向量常量时，建议进行 [显式类型转换](#cast)，将字符串转换为向量，以避免基于字符串值的比较： + +```sql +-- 由于传入的是字符串，TiDB 按字符串比较： +[tidb]> SELECT '[12.0]' < '[4.0]'; ++--------------------+ +| '[12.0]' < '[4.0]' | ++--------------------+ +| 1 | ++--------------------+ +1 row in set (0.01 sec) + +-- 显式转换为向量后按向量比较： +[tidb]> SELECT VEC_FROM_TEXT('[12.0]') < VEC_FROM_TEXT('[4.0]'); ++--------------------------------------------------+ +| VEC_FROM_TEXT('[12.0]') < VEC_FROM_TEXT('[4.0]') | ++--------------------------------------------------+ +| 0 | ++--------------------------------------------------+ +1 row in set (0.01 sec) +``` + +## 算术运算 {#arithmetic} + +向量数据类型支持 `+`（加法）和 `-`（减法）算术运算。但不同维度的向量之间不支持算术运算，否则会报错。 + +示例： + +```sql +[tidb]> SELECT VEC_FROM_TEXT('[4]') + VEC_FROM_TEXT('[5]'); ++---------------------------------------------+ +| VEC_FROM_TEXT('[4]') + VEC_FROM_TEXT('[5]') | ++---------------------------------------------+ +| [9] | ++---------------------------------------------+ +1 row in set (0.01 sec) + +[tidb]> SELECT VEC_FROM_TEXT('[2,3,4]') - VEC_FROM_TEXT('[1,2,3]'); ++-----------------------------------------------------+ +| VEC_FROM_TEXT('[2,3,4]') - VEC_FROM_TEXT('[1,2,3]') | ++-----------------------------------------------------+ +| [1,1,1] | ++-----------------------------------------------------+ +1 row in set (0.01 sec) + +[tidb]> SELECT VEC_FROM_TEXT('[4]') + VEC_FROM_TEXT('[1,2,3]'); +ERROR 1105 (HY000): vectors have different dimensions: 1 and 3 +``` + +## 类型转换 {#cast} + +### 向量 ⇔ 字符串 的类型转换 + +要在向量和字符串之间进行类型转换，可以使用以下函数： + +- `CAST(... AS VECTOR)`：字符串 ⇒ 向量 +- `CAST(... AS CHAR)`：向量 ⇒ 字符串 +- `VEC_FROM_TEXT`：字符串 ⇒ 向量 +- `VEC_AS_TEXT`：向量 ⇒ 字符串 + +为提升易用性，如果你调用的函数只支持向量数据类型（如向量相关性距离函数），也可以直接传入符合格式的字符串。此时 TiDB 会自动进行隐式类型转换。 + +```sql +-- VEC_DIMS 函数只接受 VECTOR 参数，因此可以直接传入字符串进行隐式转换。 +[tidb]> SELECT VEC_DIMS('[0.3, 0.5, -0.1]'); ++------------------------------+ +| VEC_DIMS('[0.3, 0.5, -0.1]') | ++------------------------------+ +| 3 | ++------------------------------+ +1 row in set (0.01 sec) + +-- 你也可以先用 VEC_FROM_TEXT 显式将字符串转换为向量，再传递给 VEC_DIMS 函数。 +[tidb]> SELECT VEC_DIMS(VEC_FROM_TEXT('[0.3, 0.5, -0.1]')); ++---------------------------------------------+ +| VEC_DIMS(VEC_FROM_TEXT('[0.3, 0.5, -0.1]')) | ++---------------------------------------------+ +| 3 | ++---------------------------------------------+ +1 row in set (0.01 sec) + +-- 也可以用 CAST(... AS VECTOR) 显式转换： +[tidb]> SELECT VEC_DIMS(CAST('[0.3, 0.5, -0.1]' AS VECTOR)); ++----------------------------------------------+ +| VEC_DIMS(CAST('[0.3, 0.5, -0.1]' AS VECTOR)) | ++----------------------------------------------+ +| 3 | ++----------------------------------------------+ +1 row in set (0.01 sec) +``` + +当你使用接受多种数据类型的运算符或函数时，需要在将字符串传递给该运算符或函数前，显式将字符串类型转换为向量类型，因为此时 TiDB 不会进行隐式类型转换。例如，在进行比较运算前，需要显式将字符串转换为向量，否则 TiDB 会按字符串值进行比较，而不是按向量数值进行比较： + +```sql +-- 由于传入的是字符串，TiDB 按字符串比较： +[tidb]> SELECT '[12.0]' < '[4.0]'; ++--------------------+ +| '[12.0]' < '[4.0]' | ++--------------------+ +| 1 | ++--------------------+ +1 row in set (0.01 sec) + +-- 显式转换为向量后按向量比较： +[tidb]> SELECT VEC_FROM_TEXT('[12.0]') < VEC_FROM_TEXT('[4.0]'); ++--------------------------------------------------+ +| VEC_FROM_TEXT('[12.0]') < VEC_FROM_TEXT('[4.0]') | ++--------------------------------------------------+ +| 0 | ++--------------------------------------------------+ +1 row in set (0.01 sec) +``` + +你也可以将向量显式转换为其字符串表示。例如，使用 `VEC_AS_TEXT()` 函数： + +```sql +-- 字符串首先被隐式转换为向量，然后向量被显式转换为字符串，因此返回标准化格式的字符串： +[tidb]> SELECT VEC_AS_TEXT('[0.3, 0.5, -0.1]'); ++--------------------------------------+ +| VEC_AS_TEXT('[0.3, 0.5, -0.1]') | ++--------------------------------------+ +| [0.3,0.5,-0.1] | ++--------------------------------------+ +1 row in set (0.01 sec) +``` + +更多类型转换函数，参见 [向量函数与运算符](/ai/reference/vector-search-functions-and-operators.md)。 + +### 向量 ⇔ 其他数据类型的类型转换 + +目前不支持向量与其他数据类型（如 `JSON`）之间的直接类型转换。你可以在 SQL 语句中通过字符串作为中间类型进行转换来规避此限制。 + +需要注意的是，表中存储的向量数据类型列，无法通过 `ALTER TABLE ... MODIFY COLUMN ...` 转换为其他数据类型。 + +## 限制 + +关于向量数据类型的限制，参见 [向量搜索限制](/ai/reference/vector-search-limitations.md) 和 [向量索引限制](/ai/reference/vector-search-index.md#restrictions)。 + +## MySQL 兼容性 + +向量数据类型为 TiDB 特有，MySQL 不支持。 + +## 另请参阅 + +- [向量函数与运算符](/ai/reference/vector-search-functions-and-operators.md) +- [向量搜索索引](/ai/reference/vector-search-index.md) +- [提升向量搜索性能](/ai/reference/vector-search-improve-performance.md) diff --git a/ai/reference/vector-search-functions-and-operators.md b/ai/reference/vector-search-functions-and-operators.md new file mode 100644 index 000000000000..f0926e51b431 --- /dev/null +++ b/ai/reference/vector-search-functions-and-operators.md @@ -0,0 +1,317 @@ +--- +title: 向量函数与运算符 +summary: 了解可用于向量数据类型的函数与运算符。 +aliases: ['/zh/tidb/stable/vector-search-functions-and-operators/','/zh/tidb/dev/vector-search-functions-and-operators/','/zh/tidbcloud/vector-search-functions-and-operators/'] +--- + +# 向量函数与运算符 + +本文档列出了可用于向量数据类型的函数与运算符。 + +> **注意：** +> +> - 向量函数与运算符目前为 Beta 版本，可能会在未提前通知的情况下发生变更。如果你发现了 bug，可以在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues)。 +> - 向量数据类型及这些向量函数适用于 [TiDB 自托管](/overview.md)、[TiDB Cloud Starter](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#starter)、[TiDB Cloud Essential](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#essential) 和 [TiDB Cloud Dedicated](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated)。对于 TiDB 自托管和 TiDB Cloud Dedicated，TiDB 版本需为 v8.4.0 或更高（推荐 v8.5.0 或更高）。 + +## 向量函数 + +以下函数专为 [向量数据类型](/ai/reference/vector-search-data-types.md) 设计。 + +**向量距离函数：** + +| 函数名 | 描述 | [向量索引](/ai/reference/vector-search-index.md)支持 | +| ---------------------------------------------------- | --------------------------------------------------------- |---------------------------| +| [`VEC_L2_DISTANCE`](#vec_l2_distance) | 计算两个向量之间的 L2 距离（欧氏距离） | 是 | +| [`VEC_COSINE_DISTANCE`](#vec_cosine_distance) | 计算两个向量之间的余弦距离 | 是 | +| [`VEC_NEGATIVE_INNER_PRODUCT`](#vec_negative_inner_product) | 计算两个向量内积的相反数 | 否 | +| [`VEC_L1_DISTANCE`](#vec_l1_distance) | 计算两个向量之间的 L1 距离（曼哈顿距离） | 否 | + +**其他向量函数：** + +| 函数名 | 描述 | +| ----------------------------- | -------------------------------------------- | +| [`VEC_DIMS`](#vec_dims) | 返回向量的维度 | +| [`VEC_L2_NORM`](#vec_l2_norm) | 计算向量的 L2 范数（欧氏范数） | +| [`VEC_FROM_TEXT`](#vec_from_text) | 将字符串转换为向量 | +| [`VEC_AS_TEXT`](#vec_as_text) | 将向量转换为字符串 | + +## 扩展内置函数与运算符 + +以下内置函数与运算符已扩展以支持对 [向量数据类型](/ai/reference/vector-search-data-types.md) 的操作。 + +**算术运算符：** + +| 名称 | 描述 | +| :------------------------------------------------------------------------------------- | :------------------------------- | +| [`+`](https://dev.mysql.com/doc/refman/8.0/en/arithmetic-functions.html#operator_plus) | 向量按元素加法运算符 | +| [`-`](https://dev.mysql.com/doc/refman/8.0/en/arithmetic-functions.html#operator_minus) | 向量按元素减法运算符 | + +关于向量算术运算的更多信息，参见 [向量数据类型 | 算术运算](/ai/reference/vector-search-data-types.md#arithmetic)。 + +**聚合（GROUP BY）函数：** + +| 名称 | 描述 | +| :----------------------- | :---------------------------------------- | +| [`COUNT()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_count) | 返回结果行数 | +| [`COUNT(DISTINCT)`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_count-distinct) | 返回不同值的数量 | +| [`MAX()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_max) | 返回最大值 | +| [`MIN()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_min) | 返回最小值 | + +**比较函数与运算符：** + +| 名称 | 描述 | +| ---------------------------------------- | ---------------------------------------------- | +| [`BETWEEN ... AND ...`](https://dev.mysql.com/doc/refman/8.0/en/comparison-operators.html#operator_between) | 检查值是否在某个范围内 | +| [`COALESCE()`](https://dev.mysql.com/doc/refman/8.0/en/comparison-operators.html#function_coalesce) | 返回第一个非空值参数 | +| [`=`](https://dev.mysql.com/doc/refman/8.0/en/comparison-operators.html#operator_equal) | 等于运算符 | +| [`<=>`](https://dev.mysql.com/doc/refman/8.0/en/comparison-operators.html#operator_equal-to) | NULL 安全等于运算符 | +| [`>`](https://dev.mysql.com/doc/refman/8.0/en/comparison-operators.html#operator_greater-than) | 大于运算符 | +| [`>=`](https://dev.mysql.com/doc/refman/8.0/en/comparison-operators.html#operator_greater-than-or-equal) | 大于等于运算符 | +| [`GREATEST()`](https://dev.mysql.com/doc/refman/8.0/en/comparison-operators.html#function_greatest) | 返回最大参数 | +| [`IN()`](https://dev.mysql.com/doc/refman/8.0/en/comparison-operators.html#operator_in) | 检查值是否在某个集合中 | +| [`IS NULL`](https://dev.mysql.com/doc/refman/8.0/en/comparison-operators.html#operator_is-null) | 测试值是否为 `NULL` | +| [`ISNULL()`](https://dev.mysql.com/doc/refman/8.0/en/comparison-operators.html#function_isnull) | 测试参数是否为 `NULL` | +| [`LEAST()`](https://dev.mysql.com/doc/refman/8.0/en/comparison-operators.html#function_least) | 返回最小参数 | +| [`<`](https://dev.mysql.com/doc/refman/8.0/en/comparison-operators.html#operator_less-than) | 小于运算符 | +| [`<=`](https://dev.mysql.com/doc/refman/8.0/en/comparison-operators.html#operator_less-than-or-equal) | 小于等于运算符 | +| [`NOT BETWEEN ... AND ...`](https://dev.mysql.com/doc/refman/8.0/en/comparison-operators.html#operator_not-between) | 检查值是否不在某个范围内 | +| [`!=`, `<>`](https://dev.mysql.com/doc/refman/8.0/en/comparison-operators.html#operator_not-equal) | 不等于运算符 | +| [`NOT IN()`](https://dev.mysql.com/doc/refman/8.0/en/comparison-operators.html#operator_not-in) | 检查值是否不在某个集合中 | + +关于向量比较的更多信息，参见 [向量数据类型 | 比较](/ai/reference/vector-search-data-types.md#comparison)。 + +**流程控制函数：** + +| 名称 | 描述 | +| :------------------------------------------------------------------------------------------------ | :-------------------- | +| [`CASE`](https://dev.mysql.com/doc/refman/8.0/en/flow-control-functions.html#operator_case) | CASE 运算符 | +| [`IF()`](https://dev.mysql.com/doc/refman/8.0/en/flow-control-functions.html#function_if) | if/else 结构 | +| [`IFNULL()`](https://dev.mysql.com/doc/refman/8.0/en/flow-control-functions.html#function_ifnull) | null if/else 结构 | +| [`NULLIF()`](https://dev.mysql.com/doc/refman/8.0/en/flow-control-functions.html#function_nullif) | 如果 expr1 = expr2 则返回 `NULL` | + +**类型转换函数：** + +| 名称 | 描述 | +| :------------------------------------------------------------------------------------------ | :-------------------------- | +| [`CAST()`](https://dev.mysql.com/doc/refman/8.0/en/cast-functions.html#function_cast) | 将值转换为字符串或向量 | +| [`CONVERT()`](https://dev.mysql.com/doc/refman/8.0/en/cast-functions.html#function_convert) | 将值转换为字符串 | + +关于如何使用 `CAST()` 的更多信息，参见 [向量数据类型 | 类型转换](/ai/reference/vector-search-data-types.md#cast)。 + +## 完整参考 + +### VEC_L2_DISTANCE + +```sql +VEC_L2_DISTANCE(vector1, vector2) +``` + +使用以下公式计算两个向量之间的 [L2 距离](https://en.wikipedia.org/wiki/Euclidean_distance)（欧氏距离）： + +$DISTANCE(p,q)=\sqrt {\sum \limits _{i=1}^{n}{(p_{i}-q_{i})^{2}}}$ + +两个向量必须具有相同的维度，否则会返回错误。 + +示例： + +```sql +SELECT VEC_L2_DISTANCE('[0, 3]', '[4, 0]'); +``` + +``` ++-------------------------------------+ +| VEC_L2_DISTANCE('[0, 3]', '[4, 0]') | ++-------------------------------------+ +| 5 | ++-------------------------------------+ +``` + +### VEC_COSINE_DISTANCE + +```sql +VEC_COSINE_DISTANCE(vector1, vector2) +``` + +使用以下公式计算两个向量之间的 [余弦距离](https://en.wikipedia.org/wiki/Cosine_similarity)： + +$DISTANCE(p,q)=1.0 - {\frac {\sum \limits _{i=1}^{n}{p_{i}q_{i}}}{{\sqrt {\sum \limits _{i=1}^{n}{p_{i}^{2}}}}\cdot {\sqrt {\sum \limits _{i=1}^{n}{q_{i}^{2}}}}}}$ + +两个向量必须具有相同的维度，否则会返回错误。 + +对于来自 OpenAI 的 embedding，[推荐](https://help.openai.com/en/articles/6824809-embeddings-faq)使用此函数。 + +示例： + +```sql +SELECT VEC_COSINE_DISTANCE('[1, 1]', '[-1, -1]'); +``` + +``` ++-------------------------------------------+ +| VEC_COSINE_DISTANCE('[1, 1]', '[-1, -1]') | ++-------------------------------------------+ +| 2 | ++-------------------------------------------+ +``` + +### VEC_NEGATIVE_INNER_PRODUCT + +```sql +VEC_NEGATIVE_INNER_PRODUCT(vector1, vector2) +``` + +使用以下公式，通过计算两个向量 [内积](https://en.wikipedia.org/wiki/Dot_product) 的相反数来计算距离： + +$DISTANCE(p,q)=- INNER\_PROD(p,q)=-\sum \limits _{i=1}^{n}{p_{i}q_{i}}$ + +两个向量必须具有相同的维度，否则会返回错误。 + +示例： + +```sql +SELECT VEC_NEGATIVE_INNER_PRODUCT('[1, 2]', '[3, 4]'); +``` + +``` ++------------------------------------------------+ +| VEC_NEGATIVE_INNER_PRODUCT('[1, 2]', '[3, 4]') | ++------------------------------------------------+ +| -11 | ++------------------------------------------------+ +``` + +### VEC_L1_DISTANCE + +```sql +VEC_L1_DISTANCE(vector1, vector2) +``` + +使用以下公式计算两个向量之间的 [L1 距离](https://en.wikipedia.org/wiki/Taxicab_geometry)（曼哈顿距离）： + +$DISTANCE(p,q)=\sum \limits _{i=1}^{n}{|p_{i}-q_{i}|}$ + +两个向量必须具有相同的维度，否则会返回错误。 + +示例： + +```sql +SELECT VEC_L1_DISTANCE('[0, 0]', '[3, 4]'); +``` + +``` ++-------------------------------------+ +| VEC_L1_DISTANCE('[0, 0]', '[3, 4]') | ++-------------------------------------+ +| 7 | ++-------------------------------------+ +``` + +### VEC_DIMS + +```sql +VEC_DIMS(vector) +``` + +返回向量的维度。 + +示例： + +```sql +SELECT VEC_DIMS('[1, 2, 3]'); +``` + +``` ++-----------------------+ +| VEC_DIMS('[1, 2, 3]') | ++-----------------------+ +| 3 | ++-----------------------+ +``` + +```sql +SELECT VEC_DIMS('[]'); +``` + +``` ++----------------+ +| VEC_DIMS('[]') | ++----------------+ +| 0 | ++----------------+ +``` + +### VEC_L2_NORM + +```sql +VEC_L2_NORM(vector) +``` + +使用以下公式计算向量的 [L2 范数](https://en.wikipedia.org/wiki/Norm_(mathematics))（欧氏范数）： + +$NORM(p)=\sqrt {\sum \limits _{i=1}^{n}{p_{i}^{2}}}$ + +示例： + +```sql +SELECT VEC_L2_NORM('[3, 4]'); +``` + +``` ++-----------------------+ +| VEC_L2_NORM('[3, 4]') | ++-----------------------+ +| 5 | ++-----------------------+ +``` + +### VEC_FROM_TEXT + +```sql +VEC_FROM_TEXT(string) +``` + +将字符串转换为向量。在许多场景下，此转换会被隐式执行，例如向 `VECTOR` 数据类型的列插入数据时。然而，在某些不支持隐式转换的表达式中（如向量的算术运算），你需要显式调用此函数。 + +示例： + +```sql +SELECT VEC_FROM_TEXT('[1, 2]') + VEC_FROM_TEXT('[3, 4]'); +``` + +``` ++-------------------------------------------------+ +| VEC_FROM_TEXT('[1,2]') + VEC_FROM_TEXT('[3,4]') | ++-------------------------------------------------+ +| [4,6] | ++-------------------------------------------------+ +``` + +### VEC_AS_TEXT + +```sql +VEC_AS_TEXT(vector) +``` + +将向量转换为字符串。 + +示例： + +```sql +SELECT VEC_AS_TEXT('[1.000, 2.5]'); +``` + +``` ++-----------------------------+ +| VEC_AS_TEXT('[1.000, 2.5]') | ++-----------------------------+ +| [1,2.5] | ++-----------------------------+ +``` + +## MySQL 兼容性 + +向量函数以及内置函数和运算符在向量数据类型上的扩展用法为 TiDB 特有，MySQL 不支持。 + +## 另请参阅 + +- [向量数据类型](/ai/reference/vector-search-data-types.md) diff --git a/ai/reference/vector-search-improve-performance.md b/ai/reference/vector-search-improve-performance.md new file mode 100644 index 000000000000..06b110736d6c --- /dev/null +++ b/ai/reference/vector-search-improve-performance.md @@ -0,0 +1,42 @@ +--- +title: 提升向量搜索性能 +summary: 学习提升 TiDB 向量搜索性能的最佳实践。 +aliases: ['/zh/tidb/stable/vector-search-improve-performance/','/zh/tidb/dev/vector-search-improve-performance/','/zh/tidbcloud/vector-search-improve-performance/'] +--- + +# 提升向量搜索性能 + +TiDB 向量搜索支持执行近似最近邻（ANN）查询，用于查找与某个镜像、文档或其他输入相似的结果。要提升查询性能，请参考以下最佳实践。 + +> **注意：** +> +> - 向量搜索功能目前为 beta 版本，可能会在未提前通知的情况下发生变更。如果你发现了 bug，可以在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues)。 +> - 向量搜索功能适用于 [TiDB 自托管](/overview.md)、[TiDB Cloud Starter](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#starter)、[TiDB Cloud Essential](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#essential) 和 [TiDB Cloud Dedicated](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated)。对于 TiDB 自托管和 TiDB Cloud Dedicated，TiDB 版本需为 v8.4.0 或更高（推荐 v8.5.0 或更高）。 + +## 为向量列添加向量搜索索引 + +[向量搜索索引](/ai/reference/vector-search-index.md) 能显著提升向量搜索查询的性能，通常可提升 10 倍或以上，仅以极小的召回率下降为代价。 + +## 确保向量索引已完全构建 + +在你插入大量向量数据后，部分数据可能仍处于 Delta 层，等待持久化。TiDB 会在数据持久化后为这些数据构建向量索引。在所有向量数据都被索引之前，向量搜索性能会处于次优状态。要查看索引构建进度，请参见 [查看索引构建进度](/ai/reference/vector-search-index.md#view-index-build-progress)。 + +## 降低向量维度或缩短 embedding + +随着向量维度的增加，向量搜索索引和查询的计算复杂度会显著提升，需要进行更多的浮点数比较。 + +为优化性能，建议在可行的情况下降低向量维度。这通常需要切换到其他 embedding 模型。切换模型时，你需要评估模型变更对向量查询准确性的影响。 + +某些 embedding 模型（如 OpenAI 的 `text-embedding-3-large`）支持[缩短 embedding](https://openai.com/index/new-embedding-models-and-api-updates/)，即在不丢失 embedding 概念表达能力的前提下，从向量序列末尾移除部分数值。你也可以使用此类 embedding 模型来降低向量维度。 + +## 从结果中排除向量列 + +向量 embedding 数据通常较大，仅在搜索过程中使用。通过在查询结果中排除向量列，可以大幅减少 TiDB 服务器与 SQL 客户端之间传输的数据量，从而提升查询性能。 + +要排除向量列，请在 `SELECT` 子句中显式列出你需要获取的列，而不是使用 `SELECT *` 获取所有列。 + +## 预热索引 + +当访问从未被使用过或长时间未被访问（冷访问）的索引时，TiDB 需要从云存储或磁盘（而非内存）加载整个索引。此过程需要一定时间，通常会导致更高的查询延时。此外，如果长时间（如数小时）没有 SQL 查询，计算资源会被回收，导致后续访问变为冷访问。 + +为避免此类查询延时，在实际负载前，可以通过执行命中向量索引的类似向量搜索查询来预热索引。 \ No newline at end of file diff --git a/ai/reference/vector-search-index.md b/ai/reference/vector-search-index.md new file mode 100644 index 000000000000..4773e633a097 --- /dev/null +++ b/ai/reference/vector-search-index.md @@ -0,0 +1,259 @@ +--- +title: 向量搜索索引 +summary: 了解如何在 TiDB 中构建和使用向量搜索索引，以加速 K-最近邻（KNN）查询。 +aliases: ['/zh/tidb/stable/vector-search-index/','/zh/tidb/dev/vector-search-index/','/zh/tidbcloud/vector-search-index/'] +--- + +# 向量搜索索引 + +如 [向量搜索](/ai/concepts/vector-search-overview.md) 文档所述，向量搜索通过计算给定向量与数据库中所有向量之间的距离，找出 Top K-最近邻（KNN）。这种方式能够提供准确的结果，但当表中包含大量向量时，查询速度较慢，因为需要进行全表扫描。[^1] + +为了提升搜索效率，你可以在 TiDB 中为近似 KNN（ANN）搜索创建向量搜索索引。使用向量索引进行向量搜索时，TiDB 可以大幅提升查询性能，准确性仅有轻微下降，通常搜索召回率可保持在 90% 以上。 + +> **注意：** +> +> - 向量搜索功能目前为 beta 版本，可能会在未提前通知的情况下发生变更。如果你发现 bug，可以在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues)。 +> - 向量搜索功能适用于 [TiDB 自托管](/overview.md)、[TiDB Cloud Starter](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#starter)、[TiDB Cloud Essential](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#essential) 和 [TiDB Cloud Dedicated](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated)。对于 TiDB 自托管和 TiDB Cloud Dedicated，TiDB 版本需为 v8.4.0 及以上（推荐 v8.5.0 及以上）。 + +目前，TiDB 支持 [HNSW（Hierarchical Navigable Small World）](https://en.wikipedia.org/wiki/Hierarchical_navigable_small_world) 向量搜索索引算法。 + +## 限制 {#restrictions} + +- 你的集群中必须提前部署 TiFlash 节点。 +- 向量搜索索引不能作为主键或唯一索引使用。 +- 向量搜索索引只能创建在单个向量列上，不能与其他列（如整数型或字符串）组合为组合索引。 +- 创建和使用向量搜索索引时，必须指定距离函数。目前仅支持余弦距离 `VEC_COSINE_DISTANCE()` 和 L2 距离 `VEC_L2_DISTANCE()` 函数。 +- 对于同一列，不支持使用相同距离函数创建多个向量搜索索引。 +- 不支持直接删除带有向量搜索索引的列。你可以先删除该列上的向量搜索索引，再删除该列。 +- 不支持修改带有向量索引的列的类型。 +- 不支持将向量搜索索引设置为 [不可见](/sql-statements/sql-statement-alter-index.md)。 +- 不支持在启用 [静态加密](/encryption-at-rest.md) 的 TiFlash 节点上构建向量搜索索引。 + +## 创建 HNSW 向量索引 + +[HNSW](https://en.wikipedia.org/wiki/Hierarchical_navigable_small_world) 是最流行的向量索引算法之一。HNSW 索引在保持较高准确性的同时，能够提供良好的性能，在特定场景下准确率可达 98%。 + +在 TiDB 中，你可以通过以下任一方式为具有 [向量数据类型](/ai/reference/vector-search-data-types.md) 的列创建 HNSW 索引： + +- 创建表时，使用如下语法为向量列指定 HNSW 索引： + + ```sql + CREATE TABLE foo ( + id INT PRIMARY KEY, + embedding VECTOR(5), + VECTOR INDEX idx_embedding ((VEC_COSINE_DISTANCE(embedding))) + ); + ``` + +- 对于已存在且包含向量列的表，使用如下语法为该向量列创建 HNSW 索引： + + ```sql + CREATE VECTOR INDEX idx_embedding ON foo ((VEC_COSINE_DISTANCE(embedding))); + ALTER TABLE foo ADD VECTOR INDEX idx_embedding ((VEC_COSINE_DISTANCE(embedding))); + + -- 你也可以显式指定 "USING HNSW" 来构建向量搜索索引。 + CREATE VECTOR INDEX idx_embedding ON foo ((VEC_COSINE_DISTANCE(embedding))) USING HNSW; + ALTER TABLE foo ADD VECTOR INDEX idx_embedding ((VEC_COSINE_DISTANCE(embedding))) USING HNSW; + ``` + +> **注意：** +> +> 向量搜索索引功能依赖于表的 TiFlash 副本。 +> +> - 如果在创建表时定义了向量搜索索引，TiDB 会自动为该表创建 TiFlash 副本。 +> - 如果在创建表时未定义向量搜索索引，且当前表没有 TiFlash 副本，则需要在为表添加向量搜索索引前，手动创建 TiFlash 副本。例如：`ALTER TABLE 'table_name' SET TIFLASH REPLICA 1;`。 + +创建 HNSW 向量索引时，你需要为向量指定距离函数： + +- 余弦距离：`((VEC_COSINE_DISTANCE(embedding)))` +- L2 距离：`((VEC_L2_DISTANCE(embedding)))` + +向量索引只能创建在定长向量列上，例如定义为 `VECTOR(3)` 的列。不能为非定长向量列（如定义为 `VECTOR` 的列）创建索引，因为只有维度相同的向量之间才能计算距离。 + +关于向量搜索索引的限制，详见 [限制](#restrictions)。 + +## 使用向量索引 + +在 K-最近邻搜索查询中，可以通过如下 `ORDER BY ... LIMIT` 语句使用向量搜索索引： + +```sql +SELECT * +FROM foo +ORDER BY VEC_COSINE_DISTANCE(embedding, '[1, 2, 3, 4, 5]') +LIMIT 10 +``` + +要在向量搜索中使用索引，确保 `ORDER BY ... LIMIT` 子句使用的距离函数与创建向量索引时指定的距离函数一致。 + +## 向量索引与过滤条件联合使用 + +包含预过滤（使用 `WHERE` 子句）的查询无法利用向量索引，因为根据 SQL 语义，这类查询并非在全表范围内查找 K-最近邻。例如： + +```sql +-- 对于以下查询，`WHERE` 过滤在 KNN 之前执行，因此无法使用向量索引： + +SELECT * FROM vec_table +WHERE category = "document" +ORDER BY VEC_COSINE_DISTANCE(embedding, '[1, 2, 3]') +LIMIT 5; +``` + +要在带有过滤条件的场景下使用向量索引，应先通过向量搜索查询 K-最近邻，再对结果进行过滤： + +```sql +-- 对于以下查询，`WHERE` 过滤在 KNN 之后执行，因此可以使用向量索引： + +SELECT * FROM +( + SELECT * FROM vec_table + ORDER BY VEC_COSINE_DISTANCE(embedding, '[1, 2, 3]') + LIMIT 5 +) t +WHERE category = "document"; + +-- 注意，如果部分结果被过滤，最终返回的结果可能少于 5 条。 +``` + +## 查看索引构建进度 {#view-index-build-progress} + +在你插入大量数据后，部分数据可能不会立即持久化到 TiFlash。对于已持久化的向量数据，向量搜索索引会同步构建；对于尚未持久化的数据，索引会在数据持久化后再构建。此过程不会影响数据的准确性和一致性，你可以随时进行向量搜索并获得完整结果。但在向量索引完全构建前，性能会低于最佳状态。 + +你可以通过查询 `INFORMATION_SCHEMA.TIFLASH_INDEXES` 表来查看索引构建进度： + +```sql +SELECT * FROM INFORMATION_SCHEMA.TIFLASH_INDEXES; ++---------------+------------+----------+-------------+---------------+-----------+----------+------------+---------------------+-------------------------+--------------------+------------------------+---------------+------------------+ +| TIDB_DATABASE | TIDB_TABLE | TABLE_ID | COLUMN_NAME | INDEX_NAME | COLUMN_ID | INDEX_ID | INDEX_KIND | ROWS_STABLE_INDEXED | ROWS_STABLE_NOT_INDEXED | ROWS_DELTA_INDEXED | ROWS_DELTA_NOT_INDEXED | ERROR_MESSAGE | TIFLASH_INSTANCE | ++---------------+------------+----------+-------------+---------------+-----------+----------+------------+---------------------+-------------------------+--------------------+------------------------+---------------+------------------+ +| test | tcff1d827 | 219 | col1fff | 0a452311 | 7 | 1 | HNSW | 29646 | 0 | 0 | 0 | | 127.0.0.1:3930 | +| test | foo | 717 | embedding | idx_embedding | 2 | 1 | HNSW | 0 | 0 | 0 | 3 | | 127.0.0.1:3930 | ++---------------+------------+----------+-------------+---------------+-----------+----------+------------+---------------------+-------------------------+--------------------+------------------------+---------------+------------------+ +``` + +- 你可以通过 `ROWS_STABLE_INDEXED` 和 `ROWS_STABLE_NOT_INDEXED` 列查看索引构建进度。当 `ROWS_STABLE_NOT_INDEXED` 为 0 时，索引构建完成。 + + 作为参考，对 500 MiB、768 维的向量数据集进行索引，可能需要长达 20 分钟。索引器可并行为多个表构建索引。目前不支持调整索引器优先级或速度。 + +- 你可以通过 `ROWS_DELTA_NOT_INDEXED` 列查看 Delta 层中的行数。TiFlash 存储层的数据分为 Delta 层和 Stable 层。Delta 层存储最近插入或更新的行，并会根据写入负载定期合并到 Stable 层。该合并过程称为 Compaction。 + + Delta 层始终不会被索引。为获得最佳性能，你可以强制将 Delta 层合并到 Stable 层，使所有数据都能被索引： + + ```sql + ALTER TABLE COMPACT; + ``` + + 详细信息参见 [`ALTER TABLE ... COMPACT`](/sql-statements/sql-statement-alter-table-compact.md)。 + +此外，你还可以通过执行 `ADMIN SHOW DDL JOBS;` 并查看 `row count`，监控 DDL 任务的执行进度。但该方法并不完全准确，因为 `row count` 的值来自 `TIFLASH_INDEXES` 中的 `rows_stable_indexed` 字段。你可以将此方法作为索引进度的参考。 + +## 检查是否使用了向量索引 + +使用 [`EXPLAIN`](/sql-statements/sql-statement-explain.md) 或 [`EXPLAIN ANALYZE`](/sql-statements/sql-statement-explain-analyze.md) 语句，可以检查查询是否使用了向量索引。当 `TableFullScan` 执行器的 `operator info` 列中出现 `annIndex:` 时，表示该表扫描正在利用向量索引。 + +**示例：已使用向量索引** + +```sql +[tidb]> EXPLAIN SELECT * FROM vector_table_with_index +ORDER BY VEC_COSINE_DISTANCE(embedding, '[1, 2, 3]') +LIMIT 10; ++-----+-------------------------------------------------------------------------------------+ +| ... | operator info | ++-----+-------------------------------------------------------------------------------------+ +| ... | ... | +| ... | Column#5, offset:0, count:10 | +| ... | ..., vec_cosine_distance(test.vector_table_with_index.embedding, [1,2,3])->Column#5 | +| ... | MppVersion: 1, data:ExchangeSender_16 | +| ... | ExchangeType: PassThrough | +| ... | ... | +| ... | Column#4, offset:0, count:10 | +| ... | ..., vec_cosine_distance(test.vector_table_with_index.embedding, [1,2,3])->Column#4 | +| ... | annIndex:COSINE(test.vector_table_with_index.embedding..[1,2,3], limit:10), ... | ++-----+-------------------------------------------------------------------------------------+ +9 rows in set (0.01 sec) +``` + +**示例：未指定 Top K，未使用向量索引** + +```sql +[tidb]> EXPLAIN SELECT * FROM vector_table_with_index + -> ORDER BY VEC_COSINE_DISTANCE(embedding, '[1, 2, 3]'); ++--------------------------------+-----+--------------------------------------------------+ +| id | ... | operator info | ++--------------------------------+-----+--------------------------------------------------+ +| Projection_15 | ... | ... | +| └─Sort_4 | ... | Column#4 | +| └─Projection_16 | ... | ..., vec_cosine_distance(..., [1,2,3])->Column#4 | +| └─TableReader_14 | ... | MppVersion: 1, data:ExchangeSender_13 | +| └─ExchangeSender_13 | ... | ExchangeType: PassThrough | +| └─TableFullScan_12 | ... | keep order:false, stats:pseudo | ++--------------------------------+-----+--------------------------------------------------+ +6 rows in set, 1 warning (0.01 sec) +``` + +当无法使用向量索引时，部分场景下会出现 warning，帮助你了解原因： + +```sql +-- 使用了错误的距离函数： +[tidb]> EXPLAIN SELECT * FROM vector_table_with_index +ORDER BY VEC_L2_DISTANCE(embedding, '[1, 2, 3]') +LIMIT 10; + +[tidb]> SHOW WARNINGS; +ANN index not used: not ordering by COSINE distance + +-- 使用了错误的排序方式： +[tidb]> EXPLAIN SELECT * FROM vector_table_with_index +ORDER BY VEC_COSINE_DISTANCE(embedding, '[1, 2, 3]') DESC +LIMIT 10; + +[tidb]> SHOW WARNINGS; +ANN index not used: index can be used only when ordering by vec_cosine_distance() in ASC order +``` + +## 分析向量搜索性能 + +要了解向量索引的详细使用信息，可以执行 [`EXPLAIN ANALYZE`](/sql-statements/sql-statement-explain-analyze.md) 语句，并查看输出中的 `execution info` 列： + +```sql +[tidb]> EXPLAIN ANALYZE SELECT * FROM vector_table_with_index +ORDER BY VEC_COSINE_DISTANCE(embedding, '[1, 2, 3]') +LIMIT 10; ++-----+--------------------------------------------------------+-----+ +| | execution info | | ++-----+--------------------------------------------------------+-----+ +| ... | time:339.1ms, loops:2, RU:0.000000, Concurrency:OFF | ... | +| ... | time:339ms, loops:2 | ... | +| ... | time:339ms, loops:3, Concurrency:OFF | ... | +| ... | time:339ms, loops:3, cop_task: {...} | ... | +| ... | tiflash_task:{time:327.5ms, loops:1, threads:4} | ... | +| ... | tiflash_task:{time:327.5ms, loops:1, threads:4} | ... | +| ... | tiflash_task:{time:327.5ms, loops:1, threads:4} | ... | +| ... | tiflash_task:{time:327.5ms, loops:1, threads:4} | ... | +| ... | tiflash_task:{...}, vector_idx:{ | ... | +| | load:{total:68ms,from_s3:1,from_disk:0,from_cache:0},| | +| | search:{total:0ms,visited_nodes:2,discarded_nodes:0},| | +| | read:{vec_total:0ms,others_total:0ms}},...} | | ++-----+--------------------------------------------------------+-----+ +``` + +> **注意：** +> +> 执行信息为内部信息，字段及格式可能随时变更，恕不另行通知。请勿依赖这些信息。 + +部分重要字段说明： + +- `vector_index.load.total`：索引加载总耗时。该值可能大于实际查询时间，因为可能有多个向量索引并行加载。 +- `vector_index.load.from_s3`：从 S3 加载的索引数量。 +- `vector_index.load.from_disk`：从磁盘加载的索引数量。该索引此前已从 S3 下载到本地磁盘。 +- `vector_index.load.from_cache`：从缓存加载的索引数量。该索引此前已从 S3 下载到缓存。 +- `vector_index.search.total`：在索引中搜索的总耗时。较大的延时通常意味着索引为冷数据（从未访问或长时间未访问），导致搜索时有大量 I/O 操作。该值可能大于实际查询时间，因为可能有多个向量索引并行搜索。 +- `vector_index.search.discarded_nodes`：搜索过程中访问但被丢弃的向量行数。这些被丢弃的向量不会计入搜索结果。该值较大通常说明存在大量因 `UPDATE` 或 `DELETE` 语句产生的陈旧行。 + +关于输出的解读，参见 [`EXPLAIN`](/sql-statements/sql-statement-explain.md)、[`EXPLAIN ANALYZE`](/sql-statements/sql-statement-explain-analyze.md) 及 [EXPLAIN 使用指南](/explain-walkthrough.md)。 + +## 另请参阅 + +- [提升向量搜索性能](/ai/reference/vector-search-improve-performance.md) +- [向量数据类型](/ai/reference/vector-search-data-types.md) + +[^1]: KNN 搜索的解释改编自 ClickHouse 文档中 [Approximate Nearest Neighbor Search Indexes](https://github.com/ClickHouse/ClickHouse/pull/50661/files#diff-7ebd9e71df96e74230c9a7e604fa7cb443be69ba5e23bf733fcecd4cc51b7576) 一文，作者为 [rschu1ze](https://github.com/rschu1ze)，遵循 Apache License 2.0 许可协议。 \ No newline at end of file diff --git a/ai/reference/vector-search-limitations.md b/ai/reference/vector-search-limitations.md new file mode 100644 index 000000000000..b820ba8a375b --- /dev/null +++ b/ai/reference/vector-search-limitations.md @@ -0,0 +1,50 @@ +--- +title: 向量搜索限制 +summary: 了解 TiDB 向量搜索的限制。 +aliases: ['/zh/tidb/stable/vector-search-limitations/','/zh/tidb/dev/vector-search-limitations/','/zh/tidbcloud/vector-search-limitations/'] +--- + +# 向量搜索限制 + +本文档描述了 TiDB 向量搜索已知的限制。 + +> **注意：** +> +> - 向量搜索功能目前为 beta 版本，可能会在没有提前通知的情况下发生变更。如果你发现了 bug，可以在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues)。 +> - 向量搜索功能适用于 [TiDB 自托管](/overview.md)、[TiDB Cloud Starter](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#starter)、[TiDB Cloud Essential](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#essential) 和 [TiDB Cloud Dedicated](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated)。对于 TiDB 自托管和 TiDB Cloud Dedicated，TiDB 版本必须为 v8.4.0 或以上版本（推荐使用 v8.5.0 或以上版本）。 + +## 向量数据类型限制 + +- 每个 [vector](/ai/reference/vector-search-data-types.md) 最多支持 16383 维。 +- 向量数据类型无法存储 `NaN`、`Infinity` 或 `-Infinity` 值。 +- 向量数据类型无法存储双精度浮点数。如果你在向量列中插入或存储双精度浮点数，TiDB 会将其转换为单精度浮点数。 +- 向量列不能作为主键或主键的一部分。 +- 向量列不能作为唯一索引或唯一索引的一部分。 +- 向量列不能作为分区键或分区键的一部分。 +- 目前，TiDB 不支持将向量列修改为其他数据类型（如 `JSON` 和 `VARCHAR`）。 + +## 向量索引限制 + +参见 [向量搜索限制](/ai/reference/vector-search-index.md#restrictions)。 + +## 与 TiDB 工具的兼容性 + +在使用向量搜索时，请注意以下兼容性问题： + +- TiDB Cloud 功能： + + - [TiDB Cloud 控制台的数据迁移功能](https://docs.pingcap.com/zh/tidbcloud/migrate-from-mysql-using-data-migration/) 不支持将 MySQL 向量数据类型迁移或同步到 TiDB Cloud。 + +- TiDB 工具： + + - 请确保你使用的是 v8.4.0 或以上版本的 [BR](/br/backup-and-restore-overview.md) 进行数据备份和恢复。不支持将包含向量数据类型的表恢复到低于 v8.4.0 的 TiDB 集群。 + - [TiDB Data Migration (DM)](/dm/dm-overview.md) 不支持将 MySQL 向量数据类型迁移或同步到 TiDB。 + - 当 [TiCDC](/ticdc/ticdc-overview.md) 将向量数据同步到不支持向量数据类型的下游时，会将向量数据类型转换为其他类型。更多信息，参见 [与向量数据类型的兼容性](/ticdc/ticdc-compatibility.md#compatibility-with-vector-data-types)。 + +## 反馈 + +我们非常重视你的反馈，并随时为你提供帮助： + +- 在 [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) 或 [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs) 社区提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [提交 TiDB 工单](/support.md) diff --git a/ai/vector-search-get-started-using-python.md b/ai/vector-search-get-started-using-python.md new file mode 100644 index 000000000000..b74adad37f4c --- /dev/null +++ b/ai/vector-search-get-started-using-python.md @@ -0,0 +1,233 @@ +--- +title: 使用 Python 快速入门 TiDB + AI +summary: 学习如何使用 Python 和 TiDB 向量搜索快速开发一个实现语义搜索的 AI 应用。 +aliases: ['/zh/tidb/stable/vector-search-get-started-using-python/','/zh/tidb/dev/vector-search-get-started-using-python/','/zh/tidbcloud/vector-search-get-started-using-python/'] +--- + +# 使用 Python 快速入门 TiDB + AI + +本教程演示如何开发一个简单的 AI 应用，提供 **语义搜索** 功能。与传统的关键字搜索不同，语义搜索能够智能理解你的查询背后的含义，并返回最相关的结果。例如，如果你有标题为 "dog"、"fish" 和 "tree" 的文档，当你搜索 "a swimming animal" 时，应用会识别出 "fish" 是最相关的结果。 + +在本教程中，你将使用 [TiDB 向量搜索](/ai/concepts/vector-search-overview.md)、Python、[TiDB Vector SDK for Python](https://github.com/pingcap/tidb-vector-python) 以及 AI 模型来开发该 AI 应用。 + +> **注意：** +> +> - 向量搜索功能目前为 beta 版本，可能会在不提前通知的情况下发生变更。如果你发现了 bug，可以在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues)。 +> - 向量搜索功能适用于 [TiDB 自托管](/overview.md)、[TiDB Cloud Starter](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#starter)、[TiDB Cloud Essential](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#essential) 和 [TiDB Cloud Dedicated](https://docs.pingcap.com/zh/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated)。对于 TiDB 自托管和 TiDB Cloud Dedicated，TiDB 版本需为 v8.4.0 或更高（推荐 v8.5.0 或更高）。 + +## 前置条件 + +完成本教程，你需要： + +- 已安装 [Python 3.8 或更高版本](https://www.python.org/downloads/)。 +- 已安装 [Git](https://git-scm.com/downloads)。 +- 一个 TiDB 集群。 + +**如果你还没有 TiDB 集群，可以按如下方式创建：** + +- （推荐）参考 [创建 TiDB Cloud Starter 集群](/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) 创建本地集群。 + +## 快速开始 + +以下步骤展示了如何从零开发该应用。如果你想直接运行示例，可以在 [pingcap/tidb-vector-python](https://github.com/pingcap/tidb-vector-python/blob/main/examples/python-client-quickstart) 仓库中查看示例代码。 + +### 步骤 1. 创建新的 Python 项目 + +在你喜欢的目录下，创建一个新的 Python 项目，并新建名为 `example.py` 的文件： + +```shell +mkdir python-client-quickstart +cd python-client-quickstart +touch example.py +``` + +### 步骤 2. 安装所需依赖 + +在你的项目目录下，运行以下命令安装所需的依赖包： + +```shell +pip install sqlalchemy pymysql sentence-transformers tidb-vector python-dotenv +``` + +- `tidb-vector`：用于与 TiDB 向量搜索交互的 Python 客户端。 +- [`sentence-transformers`](https://sbert.net)：一个 Python 库，提供用于从文本生成 [向量嵌入](/ai/concepts/vector-search-overview.md#vector-embedding) 的预训练模型。 + +### 步骤 3. 配置 TiDB 集群连接字符串 + +根据你选择的 TiDB 部署方式，配置集群连接字符串。 + + +
+ +对于 TiDB Cloud Starter 集群，按以下步骤获取集群连接字符串并配置环境变量： + +1. 进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，点击目标集群名称进入集群概览页。 + +2. 点击右上角的 **Connect**，弹出连接对话框。 + +3. 确认连接对话框中的配置与你的运行环境一致。 + + - **Connection Type** 设置为 `Public`。 + - **Branch** 设置为 `main`。 + - **Connect With** 设置为 `SQLAlchemy`。 + - **Operating System** 与你的环境一致。 + + > **提示：** + > + > 如果你的程序运行在 Windows Subsystem for Linux (WSL) 中，请切换到对应的 Linux 发行版。 + +4. 点击 **PyMySQL** 标签页，复制连接字符串。 + + > **提示：** + > + > 如果你还未设置密码，可点击 **Generate Password** 生成随机密码。 + +5. 在你的 Python 项目根目录下，创建 `.env` 文件，并将连接字符串粘贴进去。 + + 以下为 macOS 示例： + + ```dotenv + TIDB_DATABASE_URL="mysql+pymysql://.root:@gateway01..prod.aws.tidbcloud.com:4000/test?ssl_ca=/etc/ssl/cert.pem&ssl_verify_cert=true&ssl_verify_identity=true" + ``` + +
+
+ +对于 TiDB 自建集群，在你的 Python 项目根目录下创建 `.env` 文件。将以下内容复制到 `.env` 文件中，并根据你的 TiDB 集群连接参数修改环境变量的值： + +```dotenv +TIDB_DATABASE_URL="mysql+pymysql://:@:/" +# 例如：TIDB_DATABASE_URL="mysql+pymysql://root@127.0.0.1:4000/test" +``` + +如果你在本地机器上运行 TiDB，`` 默认为 `127.0.0.1`。初始 `` 为空，因此如果是首次启动集群，可以省略该字段。 + +各参数说明如下： + +- ``：连接 TiDB 集群的用户名。 +- ``：连接 TiDB 集群的密码。 +- ``：TiDB 集群的主机。 +- ``：TiDB 集群的端口。 +- ``：你要连接的数据库名称。 + +
+ + + +### 步骤 4. 初始化嵌入模型 + +[嵌入模型](/ai/concepts/vector-search-overview.md#embedding-model) 用于将数据转换为 [向量嵌入](/ai/concepts/vector-search-overview.md#vector-embedding)。本示例使用预训练模型 [**msmarco-MiniLM-L12-cos-v5**](https://huggingface.co/sentence-transformers/msmarco-MiniLM-L12-cos-v5) 进行文本嵌入。该轻量级模型由 `sentence-transformers` 库提供，可将文本数据转换为 384 维的向量嵌入。 + +要设置模型，将以下代码复制到 `example.py` 文件中。该代码初始化了一个 `SentenceTransformer` 实例，并定义了后续使用的 `text_to_embedding()` 函数。 + +```python +from sentence_transformers import SentenceTransformer + +print("Downloading and loading the embedding model...") +embed_model = SentenceTransformer("sentence-transformers/msmarco-MiniLM-L12-cos-v5", trust_remote_code=True) +embed_model_dims = embed_model.get_sentence_embedding_dimension() + +def text_to_embedding(text): + """Generates vector embeddings for the given text.""" + embedding = embed_model.encode(text) + return embedding.tolist() +``` + +### 步骤 5. 连接 TiDB 集群 + +使用 `TiDBVectorClient` 类连接 TiDB 集群，并创建包含向量列的 `embedded_documents` 表。 + +> **注意** +> +> 请确保表中向量列的维度与嵌入模型生成的向量维度一致。例如，**msmarco-MiniLM-L12-cos-v5** 模型生成的向量为 384 维，因此 `embedded_documents` 表中向量列的维度也应为 384。 + +```python +import os +from tidb_vector.integrations import TiDBVectorClient +from dotenv import load_dotenv + +# Load the connection string from the .env file +load_dotenv() + +vector_store = TiDBVectorClient( + # The 'embedded_documents' table will store the vector data. + table_name='embedded_documents', + # The connection string to the TiDB cluster. + connection_string=os.environ.get('TIDB_DATABASE_URL'), + # The dimension of the vector generated by the embedding model. + vector_dimension=embed_model_dims, + # Recreate the table if it already exists. + drop_existing_table=True, +) +``` + +### 步骤 6. 嵌入文本数据并存储向量 + +本步骤将准备包含单词的示例文档，如 "dog"、"fish" 和 "tree"。以下代码使用 `text_to_embedding()` 函数将这些文本文档转换为向量嵌入，并插入到向量存储中。 + +```python +documents = [ + { + "id": "f8e7dee2-63b6-42f1-8b60-2d46710c1971", + "text": "dog", + "embedding": text_to_embedding("dog"), + "metadata": {"category": "animal"}, + }, + { + "id": "8dde1fbc-2522-4ca2-aedf-5dcb2966d1c6", + "text": "fish", + "embedding": text_to_embedding("fish"), + "metadata": {"category": "animal"}, + }, + { + "id": "e4991349-d00b-485c-a481-f61695f2b5ae", + "text": "tree", + "embedding": text_to_embedding("tree"), + "metadata": {"category": "plant"}, + }, +] + +vector_store.insert( + ids=[doc["id"] for doc in documents], + texts=[doc["text"] for doc in documents], + embeddings=[doc["embedding"] for doc in documents], + metadatas=[doc["metadata"] for doc in documents], +) +``` + +### 步骤 7. 执行语义搜索 + +本步骤将搜索 "a swimming animal"，该查询与现有文档中的单词并不直接匹配。 + +以下代码再次使用 `text_to_embedding()` 函数将查询文本转换为向量嵌入，并用该嵌入向量查询，找出距离最近的前三个结果。 + +```python +def print_result(query, result): + print(f"Search result (\"{query}\"):") + for r in result: + print(f"- text: \"{r.document}\", distance: {r.distance}") + +query = "a swimming animal" +query_embedding = text_to_embedding(query) +search_result = vector_store.query(query_embedding, k=3) +print_result(query, search_result) +``` + +运行 `example.py` 文件，输出如下： + +```plain +Search result ("a swimming animal"): +- text: "fish", distance: 0.4562914811223072 +- text: "dog", distance: 0.6469335836410557 +- text: "tree", distance: 0.798545178640937 +``` + +搜索结果中的三个词根据与查询向量的距离进行排序：距离越小，`document` 越相关。 + +因此，根据输出，最有可能的游泳动物是 fish，或者是一只擅长游泳的 dog。 + +## 另请参阅 + +- [向量数据类型](/ai/reference/vector-search-data-types.md) +- [向量搜索索引](/ai/reference/vector-search-index.md) diff --git a/alert-rules.md b/alert-rules.md index 49dfcd753e14..d8460951b761 100644 --- a/alert-rules.md +++ b/alert-rules.md @@ -1,7 +1,6 @@ --- title: TiDB 集群报警规则 summary: TiDB 集群中各组件的报警规则详解。 -aliases: ['/docs-cn/dev/alert-rules/','/docs-cn/dev/reference/alert-rules/'] --- # TiDB 集群报警规则 @@ -554,7 +553,7 @@ aliases: ['/docs-cn/dev/alert-rules/','/docs-cn/dev/reference/alert-rules/'] 1. 从 TiDB 日志中查看慢查询日志，看查询是否用到了索引或全表扫，或者看是否需要做 analyze。 2. 排查是否有热点。 - 3. 查看 Coprocessor 监控，看 `coporcessor table/index scan` 里 `total` 和 `process` 是否匹配。如果相差太大，表明做了太多的无效查询。看是否有 `over seek bound`，如果有，表明版本太多，GC 工作不及时，需要增大并行 GC 的线程数。 + 3. 查看 Coprocessor 监控，看 `coprocessor table/index scan` 里 `total` 和 `process` 是否匹配。如果相差太大，表明做了太多的无效查询。看是否有 `over seek bound`，如果有，表明版本太多，GC 工作不及时，需要增大并行 GC 的线程数。 #### `TiKV_raftstore_thread_cpu_seconds_total` @@ -604,8 +603,8 @@ aliases: ['/docs-cn/dev/alert-rules/','/docs-cn/dev/reference/alert-rules/'] * 处理方法： - 1. 查看 Scheduler-All 监控中的 scheduler command duration，看哪一个命令耗时最大。 - 2. 查看 Scheduler-All 监控中的 scheduler scan details，看 `total` 和 `process` 是否匹配。如果相差太大，表明有很多无效的扫描，另外观察是否有 `over seek bound`，如果太多，表明 GC 不及时。 + 1. 查看 `Scheduler` 和 `Scheduler-${cmd}`（`${cmd}` 为指定待查询的写命令）监控中的 scheduler command duration，看哪一个命令耗时最大。 + 2. 查看 `Scheduler` 和 `Scheduler-${cmd}` 监控中的 scheduler scan details，检查 `total` 和 `process` 是否匹配。如果相差太大，表明有很多无效的扫描。同时观察是否有 `over seek bound`，如果太多，表明 GC 不及时。 3. 查看 Storage 监控中的 storage async snapshot/write duration，看是否 Raft 操作不及时。 #### `TiKV_thread_apply_worker_cpu_seconds` diff --git a/analyze-slow-queries.md b/analyze-slow-queries.md index 17dcbc6d70a2..8005c593560e 100644 --- a/analyze-slow-queries.md +++ b/analyze-slow-queries.md @@ -96,9 +96,9 @@ summary: 学习如何定位和分析慢查询。 如上图，发给 `10.6.131.78` 的一个 `cop-task` 等待了 110ms 才被执行，可以判断是当时该实例忙，此时可以打开当时的 CPU 监控辅助判断。 -#### 过期 key 多 +#### 过期 MVCC 版本和 key 过多 -如果 TiKV 上过期的数据比较多，在扫描的时候则需要处理这些不必要的数据，影响处理速度。 +如果 TiKV 上过期 MVCC 版本过多，或 GC 历史版本数据的保留时间长，导致累积了过多 MVCC。处理这些不必要的 MVCC 版本会影响扫描速度。 这可以通过 `Total_keys` 和 `Processed_keys` 判断，如果两者相差较大，则说明旧版本的 key 太多： @@ -108,6 +108,8 @@ summary: 学习如何定位和分析慢查询。 ... ``` +TiDB v8.5.0 引入了内存引擎功能，可以加速这类慢查询。详见 [TiKV MVCC 内存引擎](/tikv-in-memory-engine.md)。 + ### 其他关键阶段慢 #### 取 TS 慢 diff --git a/api/_index.md b/api/_index.md new file mode 100644 index 000000000000..f88d6575d1a1 --- /dev/null +++ b/api/_index.md @@ -0,0 +1,29 @@ +--- +title: TiDB API 概览 +summary: 了解 TiDB Cloud 和 TiDB 可用的 API。 +--- + +# TiDB API 概览 + +TiDB 提供了多种 API，可用于查询和运维集群、管理数据同步、监控系统状态等场景。本文介绍 [TiDB Cloud](https://docs.pingcap.com/zh/tidbcloud/) 和 [TiDB](https://docs.pingcap.com/zh/tidb/stable/) 的可用 API。 + +## TiDB Cloud API (beta) + +[TiDB Cloud API](/api/tidb-cloud-api-overview.md) 是一个 [REST 接口](https://zh.wikipedia.org/wiki/表现层状态转换)。通过该 API，你可以以编程方式访问和操作 TiDB Cloud 中的各类管理资源，例如项目、集群、备份、恢复、导入、账单以及 Data Service。 + +| API | 描述 | +| --- | --- | +| [v1beta1](/api/tidb-cloud-api-v1beta1.md) | 管理 TiDB Cloud Starter、Essential 与 Dedicated 集群，以及账单、Data Service 与 IAM 资源。 | +| [v1beta](/api/tidb-cloud-api-v1beta.md) | 管理 TiDB Cloud 的项目、集群、备份、导入与恢复。 | + +## TiDB API + +TiDB 为相关 TiDB 工具提供了多种 API。通过这些 API，你可以管理集群组件、监控系统状态，并控制数据同步工作流。 + +| API | 描述 | +| --- | --- | +| [TiProxy API](/tiproxy/tiproxy-api.md) | 获取 TiProxy 配置、健康状况以及监控数据。 | +| [Data Migration API](/dm/dm-open-api.md) | 管理 DM-master 与 DM-worker 节点、数据源以及数据同步任务。 | +| [监控 API](/tidb-monitoring-api.md) | 获取 TiDB Server 运行状态、数据表的存储信息以及 TiKV 集群的详细信息。 | +| [TiCDC API](/ticdc/ticdc-open-api-v2.md) | 查询 TiCDC 节点状态并管理数据同步任务，包括任务的创建、暂停、恢复与更新等操作。 | +| [TiDB Operator API](https://github.com/pingcap/tidb-operator/blob/{{{.tidb-operator-version}}}/docs/api-references/docs.md) | 管理 Kubernetes 上的 TiDB 集群，包括集群部署、升级、扩缩容、备份与故障转移等操作。 | diff --git a/api/dm-api-overview.md b/api/dm-api-overview.md new file mode 100644 index 000000000000..ac50f1600d8d --- /dev/null +++ b/api/dm-api-overview.md @@ -0,0 +1,18 @@ +--- +title: Data Migration API 概览 +summary: 了解 Data Migration (DM) 的 API。 +--- + +# Data Migration API 概览 + +[TiDB Data Migration](/dm/dm-overview.md) (DM) 是一款便捷的数据迁移工具，支持从与 MySQL 协议兼容的数据库（例如 MySQL、MariaDB、Aurora MySQL）到 TiDB 的全量数据迁移和增量数据同步。 + +DM 提供了用于查询与操作 DM 集群的 OpenAPI，其功能范围与 [dmctl 工具](/dm/dmctl-introduction.md)相当。 + +你可以使用 DM API 对 DM 集群执行以下运维操作： + +- [集群管理](/dm/dm-open-api.md#集群相关-api)：获取 DM-master 与 DM-worker 节点信息，或下线相应节点。 +- [数据源管理](/dm/dm-open-api.md#数据源相关-api)：创建、更新、删除、启用或停用数据源，管理 relay-log 功能，更新数据源与 DM-worker 的绑定关系。 +- [同步任务管理](/dm/dm-open-api.md#同步任务相关-api)：创建、更新、删除、开始或停止同步任务；管理 schema 与迁移规则。 + +关于各个 API 的请求参数、响应示例与使用说明，请参阅[使用 OpenAPI 运维 TiDB Data Migration 集群](/dm/dm-open-api.md)。 diff --git a/api/monitoring-api-overview.md b/api/monitoring-api-overview.md new file mode 100644 index 000000000000..146e1f592644 --- /dev/null +++ b/api/monitoring-api-overview.md @@ -0,0 +1,15 @@ +--- +title: TiDB 监控 API 概览 +summary: 了解 TiDB 监控服务的 API。 +--- + +# TiDB 监控 API 概览 + +TiDB 的监控框架基于 [Prometheus](https://prometheus.io) 和 [Grafana](https://grafana.com/grafana) 这两个开源项目。TiDB 使用 Prometheus 存储监控和性能指标，使用 Grafana 可视化展示这些指标，并提供内置的 [TiDB Dashboard](/dashboard/dashboard-intro.md) 图形化界面，用于监控及诊断 TiDB 集群。 + +你可以使用以下 API 监控 TiDB 集群状态： + +- [状态接口](/tidb-monitoring-api.md#使用状态接口)：监控当前 TiDB Server 的[运行状态](/tidb-monitoring-api.md#运行状态)，以及某张表的[存储信息](/tidb-monitoring-api.md#存储信息)。 +- [Metrics 接口](/tidb-monitoring-api.md#使用-metrics-接口)：获取各组件中不同操作的详细指标信息，可通过 Grafana 查看这些指标。 + +关于各个 API 的请求参数、响应示例与使用说明，请参阅 [TiDB 监控 API](/tidb-monitoring-api.md)。 diff --git a/api/ticdc-api-overview.md b/api/ticdc-api-overview.md new file mode 100644 index 000000000000..53925e686bd8 --- /dev/null +++ b/api/ticdc-api-overview.md @@ -0,0 +1,19 @@ +--- +title: TiCDC API 概览 +summary: 了解 TiCDC 的 API。 +--- + +# TiCDC API 概览 + +[TiCDC](/ticdc/ticdc-overview.md) 是一款 TiDB 增量数据同步工具，通过拉取上游 TiKV 的数据变更日志，TiCDC 可以将数据解析为有序的行级变更数据输出到下游。 + +TiCDC 提供以下两个版本的 API，用于查询与运维 TiCDC 集群： + +- [TiCDC OpenAPI v1](/ticdc/ticdc-open-api.md) +- [TiCDC OpenAPI v2](/ticdc/ticdc-open-api-v2.md) + +> **注意：** +> +> TiCDC OpenAPI v1 将在未来版本中被删除。推荐使用 TiCDC OpenAPI v2。 + +关于各个 API 的请求参数、响应示例与使用说明，请参阅 [TiCDC OpenAPI v1](/ticdc/ticdc-open-api.md) 与 [TiCDC OpenAPI v2](/ticdc/ticdc-open-api-v2.md)。 diff --git a/api/tidb-cloud-api-overview.md b/api/tidb-cloud-api-overview.md new file mode 100644 index 000000000000..43e13161030c --- /dev/null +++ b/api/tidb-cloud-api-overview.md @@ -0,0 +1,24 @@ +--- +title: TiDB Cloud API 概览 +summary: 了解 TiDB Cloud API 的定义、特性，以及如何使用该 API 管理 TiDB Cloud 集群。 +aliases: ['/zh/tidbcloud/api-overview/'] +--- + +# TiDB Cloud API 概览 + +> **注意：** +> +> TiDB Cloud API 目前处于 beta 阶段。 + +TiDB Cloud API 是一个 [REST 接口](https://zh.wikipedia.org/wiki/表现层状态转换)，提供了以编程方式访问和操作 TiDB Cloud 中的各类管理资源的能力。通过该 API，你可以自动且高效地管理项目、集群、备份、恢复、导入、账单，以及 [Data Service](https://docs.pingcap.com/tidbcloud/data-service-overview) 中的相关资源。 + +该 API 具有以下特性： + +- **JSON 实体 (JSON entities)**：API 中的所有资源和数据均使用 JSON 格式。 +- **仅支持 HTTPS**：仅支持通过 HTTPS 访问该 API，从而确保所有通过网络传输的数据均经过 TLS 加密。 +- **基于密钥的访问与摘要认证**：在访问 TiDB Cloud API 之前，你需要先生成一个 API key。具体步骤请参阅 [API Key Management](https://docs.pingcap.com/tidbcloud/api/v1beta#section/Authentication/API-key-management)。所有请求都会通过 [HTTP 摘要认证](https://zh.wikipedia.org/wiki/HTTPP摘要认证)进行身份验证，从而确保 API key 不会以明文形式在网络中传输。 + +TiDB Cloud API 提供以下两个版本： + +- [v1beta1](/api/tidb-cloud-api-v1beta1.md)：管理 TiDB Cloud Starter、Essential 与 Dedicated 集群，以及账单、Data Service 与 IAM 资源。 +- [v1beta](/api/tidb-cloud-api-v1beta.md)：管理 TiDB Cloud 的项目、集群、备份、导入与恢复。 diff --git a/api/tidb-cloud-api-v1beta.md b/api/tidb-cloud-api-v1beta.md new file mode 100644 index 000000000000..6b1f9969cc7a --- /dev/null +++ b/api/tidb-cloud-api-v1beta.md @@ -0,0 +1,16 @@ +--- +title: TiDB Cloud API v1beta 概览 +summary: 了解 TiDB Cloud 的 v1beta API。 +--- + +# TiDB Cloud API v1beta 概览 + +[v1beta API](https://docs.pingcap.com/tidbcloud/api/v1beta) 是一个 RESTful API，提供了以编程方式访问和操作 TiDB Cloud 中的各类管理资源的能力。通过该 API，你可以自动且高效地管理项目、集群、备份、恢复与导入等资源。 + +目前，你可以使用以下 v1beta API 来管理 TiDB Cloud 中的资源： + +- [Project](https://docs.pingcap.com/tidbcloud/api/v1beta/#tag/Project) +- [Cluster](https://docs.pingcap.com/tidbcloud/api/v1beta/#tag/Cluster) +- [Backup](https://docs.pingcap.com/tidbcloud/api/v1beta/#tag/Backup) +- [Import（已弃用）](https://docs.pingcap.com/tidbcloud/api/v1beta/#tag/Import) +- [Restore](https://docs.pingcap.com/tidbcloud/api/v1beta/#tag/Restore) \ No newline at end of file diff --git a/api/tidb-cloud-api-v1beta1.md b/api/tidb-cloud-api-v1beta1.md new file mode 100644 index 000000000000..2986c2ce0814 --- /dev/null +++ b/api/tidb-cloud-api-v1beta1.md @@ -0,0 +1,19 @@ +--- +title: TiDB Cloud API v1beta1 概览 +summary: 了解 TiDB Cloud 的 v1beta1 API。 +--- + +# TiDB Cloud API v1beta1 概览 + +TiDB Cloud API v1beta1 是一个 RESTful API，提供了以编程方式访问和操作 TiDB Cloud 中的各类管理资源的能力。通过该 API，你可以自动且高效地管理集群级的资源（如集群与分支），以及组织或项目级的资源（如计费、Data Service 与 IAM）。 + +目前，你可以使用以下 v1beta1 API 来管理 TiDB Cloud 中的资源： + +- 集群级资源： + - [TiDB Cloud Starter 或 Essential 集群](https://docs.pingcap.com/tidbcloud/api/v1beta1/serverless)：管理 TiDB Cloud Starter 或 Essential 的集群、分支、数据导出任务与数据导入任务。 + - [TiDB Cloud Dedicated 集群](https://docs.pingcap.com/tidbcloud/api/v1beta1/dedicated)：管理 TiDB Cloud Dedicated 的集群、区域 (region)、Private Endpoint 连接以及数据导入任务。 +- 组织或项目级资源： + - [Billing](https://docs.pingcap.com/tidbcloud/api/v1beta1/billing)：管理 TiDB Cloud 集群的账单。 + - [Data Service](https://docs.pingcap.com/tidbcloud/api/v1beta1/dataservice)：管理 TiDB Cloud 集群 Data Service 中的资源。 + - [IAM](https://docs.pingcap.com/tidbcloud/api/v1beta1/iam)：管理 TiDB Cloud 集群的 API key。 + - [MSP（已弃用）](https://docs.pingcap.com/tidbcloud/api/v1beta1/msp) \ No newline at end of file diff --git a/api/tidb-operator-api-overview.md b/api/tidb-operator-api-overview.md new file mode 100644 index 000000000000..fddff41c4ec6 --- /dev/null +++ b/api/tidb-operator-api-overview.md @@ -0,0 +1,20 @@ +--- +title: TiDB Operator API 概览 +summary: 了解 TiDB Operator 的 API 接口。 +--- + +# TiDB Operator API 概览 + +[TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/) 是 Kubernetes 上的 TiDB 集群自动运维系统，提供包括部署、升级、扩缩容、备份恢复、配置变更的 TiDB 全生命周期管理。借助 TiDB Operator，TiDB 可以无缝运行在公有云或自托管的 Kubernetes 集群上。 + +要在 Kubernetes 上管理 TiDB 集群，你可以使用以下 TiDB Operator API： + +- [Backup](https://github.com/pingcap/tidb-operator/blob/{{{.tidb-operator-version}}}/docs/api-references/docs.md#backup) +- [BackupSchedule](https://github.com/pingcap/tidb-operator/blob/{{{.tidb-operator-version}}}/docs/api-references/docs.md#backupschedule) +- [DMCluster](https://github.com/pingcap/tidb-operator/blob/{{{.tidb-operator-version}}}/docs/api-references/docs.md#dmcluster) +- [Restore](https://github.com/pingcap/tidb-operator/blob/{{{.tidb-operator-version}}}/docs/api-references/docs.md#restore) +- [TidbCluster](https://github.com/pingcap/tidb-operator/blob/{{{.tidb-operator-version}}}/docs/api-references/docs.md#tidbcluster) +- [TidbInitializer](https://github.com/pingcap/tidb-operator/blob/{{{.tidb-operator-version}}}/docs/api-references/docs.md#tidbinitializer) +- [TidbMonitor](https://github.com/pingcap/tidb-operator/blob/{{{.tidb-operator-version}}}/docs/api-references/docs.md#tidbmonitor) + +更多信息，请参阅 [TiDB Operator API 文档](https://github.com/pingcap/tidb-operator/blob/{{{.tidb-operator-version}}}/docs/api-references/docs.md)。 diff --git a/api/tiproxy-api-overview.md b/api/tiproxy-api-overview.md new file mode 100644 index 000000000000..362fdf9fa904 --- /dev/null +++ b/api/tiproxy-api-overview.md @@ -0,0 +1,19 @@ +--- +title: TiProxy API 概览 +summary: 了解 TiProxy 的 API。 +--- + +# TiProxy API 概览 + +[TiProxy](/tiproxy/tiproxy-overview.md) 是 PingCAP 的官方代理组件，它放置在客户端和 TiDB server 之间，为 TiDB 提供负载均衡、连接保持、服务发现等功能。 + +TiProxy 是可选组件，你也可以使用第三方的代理组件，或者直接连接到 TiDB server。 + +通过 TiProxy API，你可以对 TiProxy 集群执行以下操作： + +- [获取 TiProxy 配置](/tiproxy/tiproxy-api.md#获取-tiproxy-的配置) +- [设置 TiProxy 配置](/tiproxy/tiproxy-api.md#设置-tiproxy-的配置) +- [获取 TiProxy 健康状况](/tiproxy/tiproxy-api.md#获取-tiproxy-的健康状况) +- [获取 TiProxy 监控数据](/tiproxy/tiproxy-api.md#获取-tiproxy-的监控数据) + +关于各个 API 的请求参数、响应示例与使用说明，请参阅 [TiProxy API](/tiproxy/tiproxy-api.md)。 \ No newline at end of file diff --git a/auto-increment.md b/auto-increment.md index c5250a9dc6af..00a54783fd47 100644 --- a/auto-increment.md +++ b/auto-increment.md @@ -1,7 +1,6 @@ --- title: AUTO_INCREMENT summary: 介绍 TiDB 的 `AUTO_INCREMENT` 列属性。 -aliases: ['/docs-cn/dev/auto-increment/'] --- # AUTO_INCREMENT @@ -22,7 +21,7 @@ aliases: ['/docs-cn/dev/auto-increment/'] > **注意：** > -> 如果要求自增编号在所有 TiDB 实例上具有单调性，并且你的 TiDB 版本在 v6.5.0 及以上，推荐使用 [MySQL 兼容模式](#mysql-兼容模式)。 +> 如果要求自增编号在所有 TiDB 实例上具有单调性，并且你的 TiDB 版本在 v6.5.0 及以上，推荐使用[兼容 MySQL 的自增列模式](#兼容-mysql-的自增列模式)。 {{< copyable "sql" >}} @@ -334,6 +333,7 @@ SELECT * FROM t; 在一些场景中，你可能需要清除自增 ID 缓存，以保证数据一致性。例如： - 使用 [Data Migration (DM)](/dm/dm-overview.md) 进行增量同步，当同步结束后，下游 TiDB 的数据写入方式将从 DM 切换回正常的业务数据写入，此时自增列 ID 的写入模式通常由显式写入转换成隐式分配。 +- TiDB Lightning 完成数据导入后会自动清除自增 ID 缓存，但 TiCDC 在增量同步后不会自动清除。因此，在停止 TiCDC 并进行主备切换之前，需要手动清除下游集群的自增 ID 缓存。 - 当业务同时使用了显式写入和隐式分配时，需要清除自增 ID 缓存，以防止后续隐式分配的自增 ID 与已显式写入的 ID 发生冲突，导致主键冲突错误。具体场景参考[唯一性保证](/auto-increment.md#唯一性保证)。 你可以执行 `ALTER TABLE` 语句设置 `AUTO_INCREMENT = 0` 来清除集群中所有 TiDB 节点的自增 ID 缓存。例如： @@ -388,27 +388,51 @@ SELECT * FROM t; 从 v3.0.9 和 v4.0.rc-1 开始，和 MySQL 的行为类似，自增列隐式分配的值遵循 session 变量 `@@auto_increment_increment` 和 `@@auto_increment_offset` 的控制，其中自增列隐式分配的值 (ID) 将满足式子 `(ID - auto_increment_offset) % auto_increment_increment == 0`。 -## MySQL 兼容模式 +## 兼容 MySQL 的自增列模式 -从 v6.4.0 开始，TiDB 实现了中心化分配自增 ID 的服务，可以支持 TiDB 实例不缓存数据，而是每次请求都访问中心化服务获取 ID。 +TiDB 提供了一种兼容 MySQL 的自增列模式，该模式能确保 ID 严格递增且间隙最小。要启用此模式，需在建表时将 `AUTO_ID_CACHE` 设置为 `1`： -当前中心化分配服务内置在 TiDB 进程，类似于 DDL Owner 的工作模式。有一个 TiDB 实例将充当“主”的角色提供 ID 分配服务，而其它的 TiDB 实例将充当“备”角色。当“主”节点发生故障时，会自动进行“主备切换”，从而保证中心化服务的高可用。 +```sql +CREATE TABLE t(a int AUTO_INCREMENT key) AUTO_ID_CACHE 1; +``` + +当 `AUTO_ID_CACHE` 设置为 `1` 时，所有 TiDB 实例生成的 ID 严格全局递增，每个 ID 保证全局唯一，相较于默认缓存模式（`AUTO_ID_CACHE 0` 具有 30000 个缓存值），ID 间隙显著缩小。 -MySQL 兼容模式的使用方式是，建表时将 `AUTO_ID_CACHE` 设置为 `1`： +例如，启用 `AUTO_ID_CACHE 1` 后可以生成如下序列： ```sql -CREATE TABLE t(a int AUTO_INCREMENT key) AUTO_ID_CACHE 1; +INSERT INTO t VALUES (); -- Returns ID 1 +INSERT INTO t VALUES (); -- Returns ID 2 +INSERT INTO t VALUES (); -- Returns ID 3 +-- After failover +INSERT INTO t VALUES (); -- Might return ID 5 +``` + +相比之下，使用默认缓存（`AUTO_ID_CACHE 0`）时可能出现较大间隙： + +```sql +INSERT INTO t VALUES (); -- Returns ID 1 +INSERT INTO t VALUES (); -- Returns ID 2 +-- New TiDB instance allocates next batch +INSERT INTO t VALUES (); -- Returns ID 30001 ``` +尽管 `AUTO_ID_CACHE 1` 能保证 ID 严格递增且不会出现类似 `AUTO_ID_CACHE 0` 的大幅间隙，但在以下场景中仍可能出现微小间隙。这些间隙是维持 ID 全局唯一性和严格递增特性的必要代价： + +- 主实例退出或崩溃的故障恢复期间 + + 使用兼容 MySQL 的自增列模式后，能保证 ID **唯一**、**单调递增**，行为几乎跟 MySQL 完全一致。即使跨 TiDB 实例访问，ID 也不会出现回退。只有在中心化分配自增 ID 服务的“主” TiDB 实例进程退出（如该 TiDB 节点重启）或者异常崩溃时，才有可能造成部分 ID 不连续。这是因为主备切换时，“备” 节点需要丢弃一部分之前的“主” 节点已经分配的 ID，以保证 ID 不出现重复。 + +- TiDB 节点滚动升级期间 +- 正常并发事务场景（与 MySQL 类似） + > **注意：** > -> 在 TiDB 各个版本中，`AUTO_ID_CACHE` 设置为 `1` 都表明 TiDB 不再缓存 ID，但是不同版本的实现方式不一样： +> `AUTO_ID_CACHE 1` 的行为和性能在不同 TiDB 版本中的演进如下： > -> - 对于 TiDB v6.4.0 之前的版本，由于每次分配 ID 都需要通过一个 TiKV 事务完成 `AUTO_INCREMENT` 值的持久化修改，因此设置 `AUTO_ID_CACHE` 为 `1` 会出现性能下降。 -> - 对于 v6.4.0 及以上版本，由于引入了中心化的分配服务，`AUTO_INCREMENT` 值的修改只是在 TiDB 服务进程中的一个内存操作，相较于之前版本更快。 -> - 将 `AUTO_ID_CACHE` 设置为 `0` 表示 TiDB 使用默认的缓存大小 `30000`。 - -使用 MySQL 兼容模式后，能保证 ID **唯一**、**单调递增**，行为几乎跟 MySQL 完全一致。即使跨 TiDB 实例访问，ID 也不会出现回退。只有在中心化分配自增 ID 服务的“主” TiDB 实例进程退出（如该 TiDB 节点重启）或者异常崩溃时，才有可能造成部分 ID 不连续。这是因为主备切换时，“备” 节点需要丢弃一部分之前的“主” 节点已经分配的 ID，以保证 ID 不出现重复。 +> - v6.4.0 之前：每次 ID 分配需通过一个 TiKV 事务完成，会影响性能。 +> - v6.4.0 起：引入集中式分配服务，ID 分配转为内存操作，性能显著提升。 +> - v8.1.0 起：移除主节点退出时的自动 `forceRebase` 操作以实现快速重启。虽然故障恢复时可能产生额外非连续 ID，但可避免大量表使用 `AUTO_ID_CACHE 1` 时可能出现的写入阻塞。 ## 使用限制 diff --git a/auto-random.md b/auto-random.md index 14995980c9fa..f067f1a5e7dc 100644 --- a/auto-random.md +++ b/auto-random.md @@ -1,7 +1,6 @@ --- title: AUTO_RANDOM summary: 本文介绍了 TiDB 的 `AUTO_RANDOM` 列属性。 -aliases: ['/docs-cn/dev/auto-random/','/docs-cn/dev/reference/sql/attributes/auto-random/'] --- # AUTO_RANDOM 从 v3.1.0 版本开始引入 @@ -159,6 +158,42 @@ SHOW WARNINGS; `AUTO_RANDOM` 列隐式分配的值和自增列类似，也遵循 session 变量 [`auto_increment_increment`](/system-variables.md#auto_increment_increment) 和 [`auto_increment_offset`](/system-variables.md#auto_increment_offset) 的控制，其中隐式分配值的自增位 (ID) 满足等式 `(ID - auto_increment_offset) % auto_increment_increment == 0`。 +## 清除自增 ID 缓存 + +在部署了多个 TiDB 实例的集群中，向 `AUTO_RANDOM` 列插入显式值时，可能会发生 ID 冲突，与 `AUTO_INCREMENT` 列类似。如果显式插入的 ID 值与 TiDB 用于自动生成的内部计数器冲突，可能会导致错误。 + +冲突发生的原因如下：每个 `AUTO_RANDOM` ID 由随机位 (Random Bits) 和自增部分组成。TiDB 使用内部计数器来生成自增部分。如果显式插入的 ID 的自增部分恰好等于计数器的下一个值，则此后当 TiDB 尝试自动生成该相同 ID 时，可能会发生重复键错误。更多详细信息，请参阅 [`AUTO_INCREMENT` 唯一性保证](/auto-increment.md#唯一性保证)。 + +在单个 TiDB 实例中，该问题不会发生，因为节点在处理显式插入时会自动调整其内部计数器，从而防止冲突。相比之下，在有多个 TiDB 节点的环境中，每个节点维护自己的 ID 缓存，所以你需要清除这些缓存以防止显式插入后发生冲突。要清除这些未分配的缓存 ID 并避免潜在的冲突，有以下两种方法： + +### 方法 1：自动重置基值（推荐方式） + +```sql +ALTER TABLE t AUTO_RANDOM_BASE=0; +``` + +该语句会自动确定一个合适的基值。尽管执行后会返回类似于 `Can't reset AUTO_INCREMENT to 0 without FORCE option, using XXX instead` 的警告信息，但基值确实会被更新，因此你可以忽略此警告。 + +> **注意：** +> +> 不能使用 `FORCE` 关键字将 `AUTO_RANDOM_BASE` 设置为 `0`，否则会导致错误。 + +### 方法 2：手动设置特定的基值 + +如果需要设置一个特定的基值（例如 `1000`），可以使用 `FORCE` 关键字： + +```sql +ALTER TABLE t FORCE AUTO_RANDOM_BASE = 1000; +``` + +但是这种方法并不方便，因为你需要自行确定合适的基值。 + +> **注意：** +> +> 使用 `FORCE` 时，必须指定一个非零的正整数。 + +以上两个方法中的语句均会修改所有 TiDB 节点上生成 `AUTO_RANDOM` 值时使用的自增位起始值，但不会影响已经分配的 ID。 + ## 使用限制 目前在 TiDB 中使用 `AUTO_RANDOM` 有以下限制： diff --git a/basic-features.md b/basic-features.md index 291b9d1fed82..0ad6e4319678 100644 --- a/basic-features.md +++ b/basic-features.md @@ -1,7 +1,6 @@ --- title: TiDB 功能概览 summary: 了解 TiDB 的功能概览。 -aliases: ['/docs-cn/dev/basic-features/','/docs-cn/dev/experimental-features-4.0/','/zh/tidb/dev/experimental-features-4.0/','/zh/tidb/dev/experimental-features'] --- # TiDB 功能概览 @@ -20,253 +19,255 @@ aliases: ['/docs-cn/dev/basic-features/','/docs-cn/dev/experimental-features-4.0 ## 数据类型，函数和操作符 -| 数据类型，函数，操作符 | 8.4 | 8.3 | 8.2 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | 5.3 | 5.2 | 5.1 | -|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| [数值类型](/data-type-numeric.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [日期和时间类型](/data-type-date-and-time.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [字符串类型](/data-type-string.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [JSON 类型](/data-type-json.md) | Y | Y | Y | Y | Y | Y | Y | E | E | E | E | E | -| [向量数据类型](/vector-search-data-types.md) | E | N | N | N | N | N | N | N | N | N | N | N | -| [控制流程函数](/functions-and-operators/control-flow-functions.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [字符串函数](/functions-and-operators/string-functions.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [数值函数与操作符](/functions-and-operators/numeric-functions-and-operators.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [日期和时间函数](/functions-and-operators/date-and-time-functions.md)| Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [位函数和操作符](/functions-and-operators/bit-functions-and-operators.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [Cast 函数和操作符](/functions-and-operators/cast-functions-and-operators.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [加密和压缩函数](/functions-and-operators/encryption-and-compression-functions.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [向量函数和操作符](/vector-search-functions-and-operators.md) | E | N | N | N | N | N | N | N | N | N | N | N | -| [信息函数](/functions-and-operators/information-functions.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [JSON 函数](/functions-and-operators/json-functions.md) | Y | Y | Y | Y | Y | Y | Y | E | E | E | E | E | -| [聚合函数](/functions-and-operators/aggregate-group-by-functions.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [窗口函数](/functions-and-operators/window-functions.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [其他函数](/functions-and-operators/miscellaneous-functions.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [操作符](/functions-and-operators/operators.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [字符集和排序规则](/character-set-and-collation.md) [^1] | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [用户级别锁](/functions-and-operators/locking-functions.md) | Y | Y | Y | Y | Y | Y | Y | Y | N | N | N | N | +| 数据类型，函数，操作符 | 8.5 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | +|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| [数值类型](/data-type-numeric.md) | Y | Y | Y | Y | Y | Y | Y | +| [日期和时间类型](/data-type-date-and-time.md) | Y | Y | Y | Y | Y | Y | Y | +| [字符串类型](/data-type-string.md) | Y | Y | Y | Y | Y | Y | Y | +| [JSON 类型](/data-type-json.md) | Y | Y | Y | Y | Y | E | E | +| [向量数据类型](/ai/reference/vector-search-data-types.md) | E | N | N | N | N | N | N | +| [控制流程函数](/functions-and-operators/control-flow-functions.md) | Y | Y | Y | Y | Y | Y | Y | +| [字符串函数](/functions-and-operators/string-functions.md) | Y | Y | Y | Y | Y | Y | Y | +| [数值函数与操作符](/functions-and-operators/numeric-functions-and-operators.md) | Y | Y | Y | Y | Y | Y | Y | +| [日期和时间函数](/functions-and-operators/date-and-time-functions.md)| Y | Y | Y | Y | Y | Y | Y | +| [位函数和操作符](/functions-and-operators/bit-functions-and-operators.md) | Y | Y | Y | Y | Y | Y | Y | +| [Cast 函数和操作符](/functions-and-operators/cast-functions-and-operators.md) | Y | Y | Y | Y | Y | Y | Y | +| [加密和压缩函数](/functions-and-operators/encryption-and-compression-functions.md) | Y | Y | Y | Y | Y | Y | Y | +| [向量函数和操作符](/ai/reference/vector-search-functions-and-operators.md) | E | N | N | N | N | N | N | +| [信息函数](/functions-and-operators/information-functions.md) | Y | Y | Y | Y | Y | Y | Y | +| [JSON 函数](/functions-and-operators/json-functions.md) | Y | Y | Y | Y | Y | E | E | +| [聚合函数](/functions-and-operators/aggregate-group-by-functions.md) | Y | Y | Y | Y | Y | Y | Y | +| [窗口函数](/functions-and-operators/window-functions.md) | Y | Y | Y | Y | Y | Y | Y | +| [其他函数](/functions-and-operators/miscellaneous-functions.md) | Y | Y | Y | Y | Y | Y | Y | +| [操作符](/functions-and-operators/operators.md) | Y | Y | Y | Y | Y | Y | Y | +| [字符集和排序规则](/character-set-and-collation.md) [^1] | Y | Y | Y | Y | Y | Y | Y | +| [用户级别锁](/functions-and-operators/locking-functions.md) | Y | Y | Y | Y | Y | Y | N | ## 索引和约束 -| 索引和约束 | 8.4 | 8.3 | 8.2 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | 5.3 | 5.2 | 5.1 | -|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| [表达式索引](/sql-statements/sql-statement-create-index.md#表达式索引) [^2] | Y | Y | Y | Y | Y | Y | Y | E | E | E | E | E | -| [列式存储 (TiFlash)](/tiflash/tiflash-overview.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [使用 FastScan 加速 OLAP 场景下的查询](/tiflash/use-fastscan.md) | Y | Y | Y | Y | Y | Y | E | N | N | N | N | N | -| [RocksDB 引擎](/storage-engine/rocksdb-overview.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [Titan 插件](/storage-engine/titan-overview.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [Titan Level Merge](/storage-engine/titan-configuration.md#level-merge实验功能) | E | E | E | E | E | E | E | E | E | E | E | E | -| [使用 bucket 提高数据扫描并发度](/tune-region-performance.md#使用-bucket-增加并发) | E | E | E | E | E | E | E | E | N | N | N | N | -| [不可见索引](/sql-statements/sql-statement-create-index.md#不可见索引) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [复合主键](/constraints.md#主键约束) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [`CHECK` 约束](/constraints.md#check-约束) | Y | Y | Y | Y | Y | N | N | N | N | N | N | N | -| [唯一约束](/constraints.md#唯一约束) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [整型主键上的聚簇索引](/clustered-indexes.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [复合或非整型主键上的聚簇索引](/clustered-indexes.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [多值索引](/sql-statements/sql-statement-create-index.md#多值索引) | Y | Y | Y | Y | Y | Y | N | N | N | N | N | N | -| [外键约束](/constraints.md#外键约束) | E | E | E | E | E | E | N | N | N | N | N | N | -| [TiFlash 延迟物化](/tiflash/tiflash-late-materialization.md) | Y | Y | Y | Y | Y | Y | N | N | N | N | N | N | -| [全局索引 (Global Index)](/partitioned-table.md#全局索引) | Y | E | N | N | N | N | N | N | N | N | N | N | -| [向量索引](/vector-search-index.md) | E | N | N | N | N | N | N | N | N | N | N | N | +| 索引和约束 | 8.5 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | +|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| [表达式索引](/sql-statements/sql-statement-create-index.md#表达式索引) [^2] | Y | Y | Y | Y | Y | E | E | +| [列式存储 (TiFlash)](/tiflash/tiflash-overview.md) | Y | Y | Y | Y | Y | Y | Y | +| [使用 FastScan 加速 OLAP 场景下的查询](/tiflash/use-fastscan.md) | Y | Y | Y | Y | E | N | N | +| [RocksDB 引擎](/storage-engine/rocksdb-overview.md) | Y | Y | Y | Y | Y | Y | Y | +| [Titan 插件](/storage-engine/titan-overview.md) | Y | Y | Y | Y | Y | Y | Y | +| [Titan Level Merge](/storage-engine/titan-configuration.md#level-merge实验功能) | E | E | E | E | E | E | E | +| [使用 bucket 提高数据扫描并发度](/tune-region-performance.md#使用-bucket-增加并发) | E | E | E | E | E | E | N | +| [不可见索引](/sql-statements/sql-statement-create-index.md#不可见索引) | Y | Y | Y | Y | Y | Y | Y | +| [复合主键](/constraints.md#主键约束) | Y | Y | Y | Y | Y | Y | Y | +| [`CHECK` 约束](/constraints.md#check-约束) | Y | Y | Y | N | N | N | N | +| [唯一约束](/constraints.md#唯一约束) | Y | Y | Y | Y | Y | Y | Y | +| [整型主键上的聚簇索引](/clustered-indexes.md) | Y | Y | Y | Y | Y | Y | Y | +| [复合或非整型主键上的聚簇索引](/clustered-indexes.md) | Y | Y | Y | Y | Y | Y | Y | +| [多值索引](/sql-statements/sql-statement-create-index.md#多值索引) | Y | Y | Y | Y | N | N | N | +| [外键约束](/foreign-key.md) | Y | E | E | E | N | N | N | +| [TiFlash 延迟物化](/tiflash/tiflash-late-materialization.md) | Y | Y | Y | Y | N | N | N | +| [全局索引 (Global Index)](/global-indexes.md) | Y | N | N | N | N | N | N | +| [向量索引](/ai/reference/vector-search-index.md) | E | N | N | N | N | N | N | ## SQL 语句 -| SQL 语句 [^3] | 8.4 | 8.3 | 8.2 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | 5.3 | 5.2 | 5.1 | -|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| `SELECT`，`INSERT`，`UPDATE`，`DELETE`，`REPLACE` | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| `INSERT ON DUPLICATE KEY UPDATE` | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| `LOAD DATA INFILE` | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| `SELECT INTO OUTFILE` | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| `INNER JOIN`, LEFT\|RIGHT [OUTER] JOIN | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| `UNION`，`UNION ALL` | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [`EXCEPT` 和 `INTERSECT` 运算符](/functions-and-operators/set-operators.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| `GROUP BY`，`ORDER BY` | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [`GROUP BY` 修饰符](/functions-and-operators/group-by-modifier.md) | Y | Y | Y | Y | Y | N | N | N | N | N | N | N | -| [窗口函数](/functions-and-operators/window-functions.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [公共表表达式 (CTE)](/sql-statements/sql-statement-with.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| `START TRANSACTION`，`COMMIT`，`ROLLBACK` | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [`EXPLAIN`](/sql-statements/sql-statement-explain.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [`EXPLAIN ANALYZE`](/sql-statements/sql-statement-explain-analyze.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [用户自定义变量](/user-defined-variables.md) | E | E | E | E | E | E | E | E | E | E | E | E | -| [`BATCH [ON COLUMN] LIMIT INTEGER DELETE`](/sql-statements/sql-statement-batch.md) | Y | Y | Y | Y | Y | Y | Y | Y | N | N | N | N | -| [`BATCH [ON COLUMN] LIMIT INTEGER INSERT/UPDATE/REPLACE`](/sql-statements/sql-statement-batch.md) | Y | Y | Y | Y | Y | Y | Y | N | N | N | N | N | -| [`ALTER TABLE ... COMPACT`](/sql-statements/sql-statement-alter-table-compact.md) | Y | Y | Y | Y | Y | Y | Y | E | N | N | N | N | -| [表级锁 (Table Lock)](/sql-statements/sql-statement-lock-tables-and-unlock-tables.md) | E | E | E | E | E | E | E | E | E | E | E | E | -| [物化列式存储的查询结果](/tiflash/tiflash-results-materialization.md) | Y | Y | Y | Y | Y | Y | E | N | N | N | N | N | +| SQL 语句 [^3] | 8.5 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | +|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| `SELECT`，`INSERT`，`UPDATE`，`DELETE`，`REPLACE` | Y | Y | Y | Y | Y | Y | Y | +| `INSERT ON DUPLICATE KEY UPDATE` | Y | Y | Y | Y | Y | Y | Y | +| `LOAD DATA INFILE` | Y | Y | Y | Y | Y | Y | Y | +| `SELECT INTO OUTFILE` | Y | Y | Y | Y | Y | Y | Y | +| `INNER JOIN`, LEFT\|RIGHT [OUTER] JOIN | Y | Y | Y | Y | Y | Y | Y | +| `UNION`，`UNION ALL` | Y | Y | Y | Y | Y | Y | Y | +| [`EXCEPT` 和 `INTERSECT` 运算符](/functions-and-operators/set-operators.md) | Y | Y | Y | Y | Y | Y | Y | +| `GROUP BY`，`ORDER BY` | Y | Y | Y | Y | Y | Y | Y | +| [`GROUP BY` 修饰符](/functions-and-operators/group-by-modifier.md) | Y | Y | Y | N | N | N | N | +| [窗口函数](/functions-and-operators/window-functions.md) | Y | Y | Y | Y | Y | Y | Y | +| [公共表表达式 (CTE)](/sql-statements/sql-statement-with.md) | Y | Y | Y | Y | Y | Y | Y | +| `START TRANSACTION`，`COMMIT`，`ROLLBACK` | Y | Y | Y | Y | Y | Y | Y | +| [`EXPLAIN`](/sql-statements/sql-statement-explain.md) | Y | Y | Y | Y | Y | Y | Y | +| [`EXPLAIN ANALYZE`](/sql-statements/sql-statement-explain-analyze.md) | Y | Y | Y | Y | Y | Y | Y | +| [用户自定义变量](/user-defined-variables.md) | E | E | E | E | E | E | E | +| [`BATCH [ON COLUMN] LIMIT INTEGER DELETE`](/sql-statements/sql-statement-batch.md) | Y | Y | Y | Y | Y | Y | N | +| [`BATCH [ON COLUMN] LIMIT INTEGER INSERT/UPDATE/REPLACE`](/sql-statements/sql-statement-batch.md) | Y | Y | Y | Y | Y | N | N | +| [`ALTER TABLE ... COMPACT`](/sql-statements/sql-statement-alter-table-compact.md) | Y | Y | Y | Y | Y | E | N | +| [表级锁 (Table Lock)](/sql-statements/sql-statement-lock-tables-and-unlock-tables.md) | E | E | E | E | E | E | E | +| [物化列式存储的查询结果](/tiflash/tiflash-results-materialization.md) | Y | Y | Y | Y | E | N | N | ## 高级 SQL 功能 -| 高级 SQL 功能 | 8.4 | 8.3 | 8.2 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | 5.3 | 5.2 | 5.1 | -|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| [向量搜索](/vector-search-overview.md) | E | N | N | N | N | N | N | N | N | N | N | N | -| [Prepare 语句执行计划缓存](/sql-prepared-plan-cache.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | E | E | -| [非 Prepare 语句执行计划缓存](/sql-non-prepared-plan-cache.md) | Y | Y | Y | Y | Y | E | N | N | N | N | N | N | -| [实例级执行计划缓存](/system-variables.md#tidb_enable_instance_plan_cache-从-v840-版本开始引入) | E | N | N | N | N | N | N | N | N | N | N | N | -| [执行计划绑定 (SQL Binding)](/sql-plan-management.md#执行计划绑定-sql-binding) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [跨数据库执行计划绑定 (Cross-DB Binding)](/sql-plan-management.md#跨数据库绑定执行计划-cross-db-binding) | Y | Y | Y | Y | N | N | N | N | N | N | N | N | -| [根据历史执行计划创建绑定](/sql-plan-management.md#根据历史执行计划创建绑定) | Y | Y | Y | Y | Y | Y | E | N | N | N | N | N | -| [下推计算结果缓存 (Coprocessor Cache)](/coprocessor-cache.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [Stale Read](/stale-read.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [Follower Read](/follower-read.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [通过系统变量 `tidb_snapshot` 读取历史数据](/read-historical-data.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [Optimizer hints](/optimizer-hints.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [MPP 执行引擎](/explain-mpp.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [MPP 执行引擎 - compression exchange](/explain-mpp.md#mpp-version-和-exchange-数据压缩) | Y | Y | Y | Y | Y | Y | N | N | N | N | N | N | -| [TiFlash Pipeline 执行模型](/tiflash/tiflash-pipeline-model.md) | Y | Y | Y | Y | Y | N | N | N | N | N | N | N | -| [TiFlash 副本选择策略](/system-variables.md#tiflash_replica_read-从-v730-版本开始引入) | Y | Y | Y | Y | Y | N | N | N | N | N | N | N | -| [索引合并](/explain-index-merge.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | E | E | E | -| [基于 SQL 的数据放置规则](/placement-rules-in-sql.md) | Y | Y | Y | Y | Y | Y | Y | Y | E | E | N | N | -| [Cascades Planner](/system-variables.md#tidb_enable_cascades_planner) | E | E | E | E | E | E | E | E | E | E | E | E | -| [Runtime Filter](/runtime-filter.md) | Y | Y | Y | Y | Y | N | N | N | N | N | N | N | +| 高级 SQL 功能 | 8.5 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | +|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| [向量搜索](/develop/dev-guide-vector-search.md) | E | N | N | N | N | N | N | +| [Prepare 语句执行计划缓存](/sql-prepared-plan-cache.md) | Y | Y | Y | Y | Y | Y | Y | +| [非 Prepare 语句执行计划缓存](/sql-non-prepared-plan-cache.md) | Y | Y | Y | E | N | N | N | +| [实例级执行计划缓存](/system-variables.md#tidb_enable_instance_plan_cache-从-v840-版本开始引入) | E | N | N | N | N | N | N | +| [执行计划绑定 (SQL Binding)](/sql-plan-management.md#执行计划绑定-sql-binding) | Y | Y | Y | Y | Y | Y | Y | +| [跨数据库执行计划绑定 (Cross-DB Binding)](/sql-plan-management.md#跨数据库绑定执行计划-cross-db-binding) | Y | Y | N | N | N | N | N | +| [根据历史执行计划创建绑定](/sql-plan-management.md#根据历史执行计划创建绑定) | Y | Y | Y | Y | E | N | N | +| [下推计算结果缓存 (Coprocessor Cache)](/coprocessor-cache.md) | Y | Y | Y | Y | Y | Y | Y | +| [Stale Read](/stale-read.md) | Y | Y | Y | Y | Y | Y | Y | +| [Follower Read](/follower-read.md) | Y | Y | Y | Y | Y | Y | Y | +| [通过系统变量 `tidb_snapshot` 读取历史数据](/read-historical-data.md) | Y | Y | Y | Y | Y | Y | Y | +| [Optimizer hints](/optimizer-hints.md) | Y | Y | Y | Y | Y | Y | Y | +| [MPP 执行引擎](/explain-mpp.md) | Y | Y | Y | Y | Y | Y | Y | +| [MPP 执行引擎 - compression exchange](/explain-mpp.md#mpp-version-和-exchange-数据压缩) | Y | Y | Y | Y | N | N | N | +| [TiFlash Pipeline 执行模型](/tiflash/tiflash-pipeline-model.md) | Y | Y | Y | N | N | N | N | +| [TiFlash 副本选择策略](/system-variables.md#tiflash_replica_read-从-v730-版本开始引入) | Y | Y | Y | N | N | N | N | +| [索引合并](/explain-index-merge.md) | Y | Y | Y | Y | Y | Y | Y | +| [基于 SQL 的数据放置规则](/placement-rules-in-sql.md) | Y | Y | Y | Y | Y | Y | E | +| [Cascades Planner](/system-variables.md#tidb_enable_cascades_planner) | E | E | E | E | E | E | E | +| [Runtime Filter](/runtime-filter.md) | Y | Y | Y | N | N | N | N | ## 数据定义语言 (DDL) -| 数据定义语言 (DDL) | 8.4 | 8.3 | 8.2 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | 5.3 | 5.2 | 5.1 | -|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| `CREATE`，`DROP`，`ALTER`，`RENAME`，`TRUNCATE` | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [生成列](/generated-columns.md) | Y | Y | Y | Y | Y | Y | E | E | E | E | E | E | -| [视图](/views.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [序列](/sql-statements/sql-statement-create-sequence.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [`AUTO_INCREMENT` 列](/auto-increment.md) | Y | Y | Y | Y | Y | Y | Y[^4] | Y | Y | Y | Y | Y | -| [`AUTO_RANDOM` 列](/auto-random.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [TTL (Time to Live)](/time-to-live.md) | Y | Y | Y | Y | Y | Y | E | N | N | N | N | N | -| [DDL 算法断言](/sql-statements/sql-statement-alter-table.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| 在单条语句中添加多列 | Y | Y | Y | Y | Y | Y | Y | E | E | E | E | E | -| [更改列类型](/sql-statements/sql-statement-modify-column.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [临时表](/temporary-tables.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | N | N | -| 并行 DDL | Y | Y | Y | Y | Y | Y | Y | N | N | N | N | N | -| [添加索引加速](/system-variables.md#tidb_ddl_enable_fast_reorg-从-v630-版本开始引入) | Y | Y | Y | Y | Y | Y | Y | N | N | N | N | N | -| [元数据锁](/metadata-lock.md) | Y | Y | Y | Y | Y | Y | N | N | N | N | N | -| [`FLASHBACK CLUSTER`](/sql-statements/sql-statement-flashback-cluster.md) | Y | Y | Y | Y | Y | Y | Y | N | N | N | N | N | -| [暂停](/sql-statements/sql-statement-admin-pause-ddl.md)/[恢复](/sql-statements/sql-statement-admin-resume-ddl.md) DDL | Y | Y | Y | Y | Y | N | N | N | N | N | N | N | -| [TiDB 加速建表](/accelerated-table-creation.md) | E | E | E | E | N | N | N | N | N | N | N | N | -| [设置 BDR Role 用于 TiCDC 双向同步时同步 DDL](/sql-statements/sql-statement-admin-bdr-role.md#admin-setshowunset-bdr-role) | Y | Y | E | E | N | N | N | N | N | N | N | N | +| 数据定义语言 (DDL) | 8.5 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | +|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| `CREATE`，`DROP`，`ALTER`，`RENAME`，`TRUNCATE` | Y | Y | Y | Y | Y | Y | Y | +| [生成列](/generated-columns.md) | Y | Y | Y | Y | E | E | E | +| [视图](/views.md) | Y | Y | Y | Y | Y | Y | Y | +| [序列](/sql-statements/sql-statement-create-sequence.md) | Y | Y | Y | Y | Y | Y | Y | +| [`AUTO_INCREMENT` 列](/auto-increment.md) | Y | Y | Y | Y | Y[^4] | Y | Y | +| [`AUTO_RANDOM` 列](/auto-random.md) | Y | Y | Y | Y | Y | Y | Y | +| [TTL (Time to Live)](/time-to-live.md) | Y | Y | Y | Y | E | N | N | +| [DDL 算法断言](/sql-statements/sql-statement-alter-table.md) | Y | Y | Y | Y | Y | Y | Y | +| 在单条语句中添加多列 | Y | Y | Y | Y | Y | E | E | +| [更改列类型](/sql-statements/sql-statement-modify-column.md) | Y | Y | Y | Y | Y | Y | Y | +| [临时表](/temporary-tables.md) | Y | Y | Y | Y | Y | Y | Y | +| 并行 DDL | Y | Y | Y | Y | Y | N | N | +| [添加索引加速](/system-variables.md#tidb_ddl_enable_fast_reorg-从-v630-版本开始引入) | Y | Y | Y | Y | Y | N | N | +| [元数据锁](/metadata-lock.md) | Y | Y | Y | Y | Y | N | N | +| [`FLASHBACK CLUSTER`](/sql-statements/sql-statement-flashback-cluster.md) | Y | Y | Y | Y | Y | N | N | +| [暂停](/sql-statements/sql-statement-admin-pause-ddl.md)/[恢复](/sql-statements/sql-statement-admin-resume-ddl.md) DDL | Y | Y | Y | N | N | N | N | +| [TiDB 加速建表](/accelerated-table-creation.md) | Y | E | N | N | N | N | N | +| [设置 BDR Role 用于 TiCDC 双向同步时同步 DDL](/sql-statements/sql-statement-admin-bdr-role.md#admin-setshowunset-bdr-role) | Y | E | N | N | N | N | N | ## 事务 -| 事务 | 8.4 | 8.3 | 8.2 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | 5.3 | 5.2 | 5.1 | -|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| [Async commit](/system-variables.md#tidb_enable_async_commit-从-v50-版本开始引入) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [1PC](/system-variables.md#tidb_enable_1pc-从-v50-版本开始引入) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [大事务 (1 TiB)](/transaction-overview.md#事务限制) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [悲观事务](/pessimistic-transaction.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [乐观事务](/optimistic-transaction.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [可重复读隔离（快照隔离）](/transaction-isolation-levels.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [读已提交隔离](/transaction-isolation-levels.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [自动终止长时间未提交的空闲事务](/system-variables.md#tidb_idle_transaction_timeout-从-v760-版本开始引入) | Y | Y | Y | Y | N | N | N | N | N | N | N | N | -| [批量 DML 语句的执行方式 (`tidb_dml_type = "bulk"`)](/system-variables.md#tidb_dml_type-从-v800-版本开始引入) | E | E | E | N | N | N | N | N | N | N | N | +| 事务 | 8.5 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | +|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| [Async commit](/system-variables.md#tidb_enable_async_commit-从-v50-版本开始引入) | Y | Y | Y | Y | Y | Y | Y | +| [1PC](/system-variables.md#tidb_enable_1pc-从-v50-版本开始引入) | Y | Y | Y | Y | Y | Y | Y | +| [大事务 (1 TiB)](/transaction-overview.md#事务限制) | Y | Y | Y | Y | Y | Y | Y | +| [悲观事务](/pessimistic-transaction.md) | Y | Y | Y | Y | Y | Y | Y | +| [乐观事务](/optimistic-transaction.md) | Y | Y | Y | Y | Y | Y | Y | +| [可重复读隔离（快照隔离）](/transaction-isolation-levels.md) | Y | Y | Y | Y | Y | Y | Y | +| [读已提交隔离](/transaction-isolation-levels.md) | Y | Y | Y | Y | Y | Y | Y | +| [自动终止长时间未提交的空闲事务](/system-variables.md#tidb_idle_transaction_timeout-从-v760-版本开始引入) | Y | Y | N | N | N | N | N | +| [批量 DML 语句的执行方式 (`tidb_dml_type = "bulk"`)](/system-variables.md#tidb_dml_type-从-v800-版本开始引入) | E | E | N | N | N | N | N | ## 分区 -| 分区 | 8.4 | 8.3 | 8.2 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | 5.3 | 5.2 | 5.1 | -|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| [Range 分区](/partitioned-table.md#range-分区) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [Hash 分区](/partitioned-table.md#hash-分区) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [Key 分区](/partitioned-table.md#key-分区) | Y | Y | Y | Y | Y | Y | N | N | N | N | N | N | -| [List 分区](/partitioned-table.md#list-分区) | Y | Y | Y | Y | Y | Y | Y | Y | E | E | E | E | -| [List COLUMNS 分区](/partitioned-table.md#list-columns-分区) | Y | Y | Y | Y | Y | Y | Y | Y | E | E | E | E | -| [List 和 List COLUMNS 分区表的默认分区](/partitioned-table.md#默认的-list-分区) | Y | Y | Y | Y | Y | N | N | N | N | N | N | N | -| [`EXCHANGE PARTITION`](/partitioned-table.md) | Y | Y | Y | Y | Y | Y | Y | E | E | E | E | E | -| [`REORGANIZE PARTITION`](/partitioned-table.md#重组分区) | Y | Y | Y | Y | Y | Y | N | N | N | N | N | N | -| [`COALESCE PARTITION`](/partitioned-table.md#减少分区数量) | Y | Y | Y | Y | Y | Y | N | N | N | N | N | N | -| [动态裁剪](/partitioned-table.md#动态裁剪模式) | Y | Y | Y | Y | Y | Y | Y | Y | E | E | E | E | -| [Range COLUMNS 分区](/partitioned-table.md#range-columns-分区) | Y | Y | Y | Y | Y | Y | Y | N | N | N | N | N | -| [Range INTERVAL 分区](/partitioned-table.md#range-interval-分区) | Y | Y | Y | Y | Y | Y | E | N | N | N | N | N | -| [分区表转换为非分区表](/partitioned-table.md#将分区表转换为非分区表) | Y | Y | Y | Y | Y | N | N | N | N | N | N | N | -| [对现有表进行分区](/partitioned-table.md#对现有表进行分区) | Y | Y | Y | Y | Y | N | N | N | N | N | N | N | +| 分区 | 8.5 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | +|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| [Range 分区](/partitioned-table.md#range-分区) | Y | Y | Y | Y | Y | Y | Y | +| [Hash 分区](/partitioned-table.md#hash-分区) | Y | Y | Y | Y | Y | Y | Y | +| [Key 分区](/partitioned-table.md#key-分区) | Y | Y | Y | Y | N | N | N | +| [List 分区](/partitioned-table.md#list-分区) | Y | Y | Y | Y | Y | Y | E | +| [List COLUMNS 分区](/partitioned-table.md#list-columns-分区) | Y | Y | Y | Y | Y | Y | E | +| [List 和 List COLUMNS 分区表的默认分区](/partitioned-table.md#默认的-list-分区) | Y | Y | Y | N | N | N | N | +| [`EXCHANGE PARTITION`](/partitioned-table.md) | Y | Y | Y | Y | Y | E | E | +| [`REORGANIZE PARTITION`](/partitioned-table.md#重组分区) | Y | Y | Y | Y | N | N | N | +| [`COALESCE PARTITION`](/partitioned-table.md#减少分区数量) | Y | Y | Y | Y | N | N | N | +| [动态裁剪](/partitioned-table.md#动态裁剪模式) | Y | Y | Y | Y | Y | Y | E | +| [Range COLUMNS 分区](/partitioned-table.md#range-columns-分区) | Y | Y | Y | Y | Y | N | N | +| [Range INTERVAL 分区](/partitioned-table.md#range-interval-分区) | Y | Y | Y | Y | E | N | N | +| [分区表转换为非分区表](/partitioned-table.md#将分区表转换为非分区表) | Y | Y | Y | N | N | N | N | +| [对现有表进行分区](/partitioned-table.md#对现有表进行分区) | Y | Y | Y | N | N | N | N | +| [全局索引 (Global Index)](/global-indexes.md) | Y | N | N | N | N | N | N | ## 统计信息 -| 统计信息 | 8.4 | 8.3 | 8.2 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | 5.3 | 5.2 | 5.1 | -|---|:----:|:----:|:----:|:----:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| [CM-Sketch](/statistics.md) | 默认关闭| 默认关闭| 默认关闭| 默认关闭| 默认关闭 | 默认关闭 | 默认关闭 | 默认关闭 | 默认关闭 | 默认关闭 | Y | Y | -| [直方图](/statistics.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [扩展统计信息](/extended-statistics.md) | E | E | E | E | E | E | E | E | E | E | E | E | -| 统计反馈 | N | N | N | N | N | N | N | 已废弃 | 已废弃 | E | E | E | -| [统计信息自动更新](/statistics.md#自动更新) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [动态裁剪](/partitioned-table.md#动态裁剪模式) | Y | Y | Y | Y | Y | Y | Y | Y | E | E | E | E | -| [收集部分列的统计信息](/statistics.md#收集部分列的统计信息) | Y | Y | E | E | E | E | E | E | E | N | N | N | -| [限制统计信息的内存使用量](/statistics.md#统计信息收集的内存限制) | E | E | E | E | E | E | E | E | N | N | N | N | -| [随机采样约 10000 行数据来快速构建统计信息](/system-variables.md#tidb_enable_fast_analyze) | 已废弃 | 已废弃 | 已废弃 | 已废弃 | 已废弃 | E | E | E | E | E | E | E | -| [锁定统计信息](/statistics.md#锁定统计信息) | Y | Y | Y | Y | Y | E | E | N | N | N | N | N | -| [轻量级统计信息初始化](/statistics.md#加载统计信息) | Y | Y | Y | Y | Y | E | N | N | N | N | N | N | -| [显示统计信息收集的进度](/sql-statements/sql-statement-show-analyze-status.md) | Y | Y | Y | Y | Y | N | N | N | N | N | N | N | +| 统计信息 | 8.5 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | +|---|:----:|:----:|:---:|:---:|:---:|:---:|:---:| +| [CM-Sketch](/statistics.md) | 默认关闭| 默认关闭| 默认关闭 | 默认关闭 | 默认关闭 | 默认关闭 | 默认关闭 | +| [直方图](/statistics.md) | Y | Y | Y | Y | Y | Y | Y | +| [扩展统计信息](/extended-statistics.md) | E | E | E | E | E | E | E | +| 统计反馈 | N | N | N | N | N | 已废弃 | 已废弃 | +| [统计信息自动更新](/statistics.md#自动更新) | Y | Y | Y | Y | Y | Y | Y | +| [动态裁剪](/partitioned-table.md#动态裁剪模式) | Y | Y | Y | Y | Y | Y | E | +| [收集部分列的统计信息](/statistics.md#收集部分列的统计信息) | Y | E | E | E | E | E | E | +| [限制统计信息的内存使用量](/statistics.md#统计信息收集的内存限制) | E | E | E | E | E | E | N | +| [随机采样约 10000 行数据来快速构建统计信息](/system-variables.md#tidb_enable_fast_analyze) | 已废弃 | 已废弃 | 已废弃 | E | E | E | E | +| [锁定统计信息](/statistics.md#锁定统计信息) | Y | Y | Y | E | E | N | N | +| [轻量级统计信息初始化](/statistics.md#加载统计信息) | Y | Y | Y | E | N | N | N | +| [显示统计信息收集的进度](/sql-statements/sql-statement-show-analyze-status.md) | Y | Y | Y | N | N | N | N | ## 安全 -| 安全 | 8.4 | 8.3 | 8.2 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | 5.3 | 5.2 | 5.1 | -|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| [传输层加密 (TLS)](/enable-tls-between-clients-and-servers.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [静态加密 (TDE)](/encryption-at-rest.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [基于角色的访问控制 (RBAC)](/role-based-access-control.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [证书鉴权](/certificate-authentication.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [`caching_sha2_password` 认证](/system-variables.md#default_authentication_plugin) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | N | -| [`tidb_sm3_password` 认证](/system-variables.md#default_authentication_plugin) | Y | Y | Y | Y | Y | Y | Y | N | N | N | N | N | -| [`tidb_auth_token` 认证](/security-compatibility-with-mysql.md#tidb_auth_token) | Y | Y | Y | Y | Y | Y | Y | N | N | N | N | N | -| [`authentication_ldap_sasl` 认证](/system-variables.md#default_authentication_plugin) | Y | Y | Y | Y | Y | Y | N | N | N | N | N | N | -| [`authentication_ldap_simple` 认证](/system-variables.md#default_authentication_plugin) | Y | Y | Y | Y | Y | Y | N | N | N | N | N | N | -| [密码管理](/password-management.md) | Y | Y | Y | Y | Y | Y | Y | N | N | N | N | N | -| [与 MySQL 兼容的 `GRANT` 权限管理](/privilege-management.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [动态权限](/privilege-management.md#动态权限) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [安全增强模式](/system-variables.md#tidb_enable_enhanced_security) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [日志脱敏](/log-redaction.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | +| 安全 | 8.5 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | +|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| [传输层加密 (TLS)](/enable-tls-between-clients-and-servers.md) | Y | Y | Y | Y | Y | Y | Y | +| [静态加密 (TDE)](/encryption-at-rest.md) | Y | Y | Y | Y | Y | Y | Y | +| [基于角色的访问控制 (RBAC)](/role-based-access-control.md) | Y | Y | Y | Y | Y | Y | Y | +| [证书鉴权](/certificate-authentication.md) | Y | Y | Y | Y | Y | Y | Y | +| [`caching_sha2_password` 认证](/system-variables.md#default_authentication_plugin) | Y | Y | Y | Y | Y | Y | Y | +| [`tidb_sm3_password` 认证](/system-variables.md#default_authentication_plugin) | Y | Y | Y | Y | Y | N | N | +| [`tidb_auth_token` 认证](/security-compatibility-with-mysql.md#tidb_auth_token) | Y | Y | Y | Y | Y | N | N | +| [`authentication_ldap_sasl` 认证](/system-variables.md#default_authentication_plugin) | Y | Y | Y | Y | N | N | N | +| [`authentication_ldap_simple` 认证](/system-variables.md#default_authentication_plugin) | Y | Y | Y | Y | N | N | N | +| [密码管理](/password-management.md) | Y | Y | Y | Y | Y | N | N | +| [与 MySQL 兼容的 `GRANT` 权限管理](/privilege-management.md) | Y | Y | Y | Y | Y | Y | Y | +| [动态权限](/privilege-management.md#动态权限) | Y | Y | Y | Y | Y | Y | Y | +| [安全增强模式](/system-variables.md#tidb_enable_enhanced_security) | Y | Y | Y | Y | Y | Y | Y | +| [日志脱敏](/log-redaction.md) | Y | Y | Y | Y | Y | Y | Y | ## 数据导入和导出 -| 数据导入和导出 | 8.4 | 8.3 | 8.2 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | 5.3 | 5.2 | 5.1 | -|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| [快速导入 (TiDB Lightning)](/tidb-lightning/tidb-lightning-overview.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [快速导入 (`IMPORT INTO`)](/sql-statements/sql-statement-import-into.md) | Y | Y | Y | Y | Y | N | N | N | N | N | N | N | -| mydumper 逻辑导出 | 已废弃 | 已废弃 | 已废弃 | 已废弃 | 已废弃 | 已废弃 | 已废弃 | 已废弃 | 已废弃 | 已废弃 | 已废弃 | 已废弃 | -| [Dumpling 逻辑导出](/dumpling-overview.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [事务 `LOAD DATA`](/sql-statements/sql-statement-load-data.md) [^5] | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [数据迁移工具](/migration-overview.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [TiDB Binlog](https://docs.pingcap.com/zh/tidb/v8.3/tidb-binlog-overview) [^6] | 已移除 | 已废弃 | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [Change data capture (CDC)](/ticdc/ticdc-overview.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [TiCDC 支持保存数据到存储服务 (Amazon S3/GCS/Azure Blob Storage/NFS)](/ticdc/ticdc-sink-to-cloud-storage.md) | Y | Y | Y | Y | Y | Y | E | N | N | N | N | N | -| [TiCDC 支持在两个 TiDB 集群之间进行双向复制](/ticdc/ticdc-bidirectional-replication.md) | Y | Y | Y | Y | Y | Y | Y | N | N | N | N | N | -| [TiCDC OpenAPI v2](/ticdc/ticdc-open-api-v2.md) | Y | Y | Y | Y | Y | Y | N | N | N | N | N | N | -| [DM](/dm/dm-overview.md) 支持迁移 MySQL 8.0 | Y | Y | Y | Y | E | E | E | E | N | N | N | N | +| 数据导入和导出 | 8.5 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | +|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| [快速导入 (TiDB Lightning)](/tidb-lightning/tidb-lightning-overview.md) | Y | Y | Y | Y | Y | Y | Y | +| [快速导入 (`IMPORT INTO`)](/sql-statements/sql-statement-import-into.md) | Y | Y | Y | N | N | N | N | +| mydumper 逻辑导出 | 已废弃 | 已废弃 | 已废弃 | 已废弃 | 已废弃 | 已废弃 | 已废弃 | +| [Dumpling 逻辑导出](/dumpling-overview.md) | Y | Y | Y | Y | Y | Y | Y | +| [事务 `LOAD DATA`](/sql-statements/sql-statement-load-data.md) [^5] | Y | Y | Y | Y | Y | Y | Y | +| [数据迁移工具](/migration-overview.md) | Y | Y | Y | Y | Y | Y | Y | +| [TiDB Binlog](https://docs.pingcap.com/zh/tidb/v8.3/tidb-binlog-overview) [^6] | 已移除 | Y | Y | Y | Y | Y | Y | +| [Change data capture (CDC)](/ticdc/ticdc-overview.md) | Y | Y | Y | Y | Y | Y | Y | +| [TiCDC 支持保存数据到存储服务 (Amazon S3/GCS/Azure Blob Storage/NFS)](/ticdc/ticdc-sink-to-cloud-storage.md) | Y | Y | Y | Y | E | N | N | +| [TiCDC 支持在两个 TiDB 集群之间进行双向复制](/ticdc/ticdc-bidirectional-replication.md) | Y | Y | Y | Y | Y | N | N | +| [TiCDC OpenAPI v2](/ticdc/ticdc-open-api-v2.md) | Y | Y | Y | Y | N | N | N | +| [DM](/dm/dm-overview.md) 支持迁移 MySQL 8.0 | Y | Y | E | E | E | E | N | ## 管理，可视化和工具 -| 管理，可视化和工具 | 8.4 | 8.3 | 8.2 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | 5.3 | 5.2 | 5.1 | -|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| [TiDB Dashboard 图形化展示](/dashboard/dashboard-intro.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [TiDB Dashboard 持续性能分析功能](/dashboard/continuous-profiling.md) | Y | Y | Y | Y | Y | Y | Y | Y | E | E | N | N | -| [TiDB Dashboard Top SQL 功能](/dashboard/top-sql.md) | Y | Y | Y | Y | Y | Y | Y | Y | E | N | N | N | -| [TiDB Dashboard SQL 诊断功能](/information-schema/information-schema-sql-diagnostics.md) | Y | Y | Y | Y | Y | Y | Y | E | E | E | E | E | -| [TiDB Dashboard 集群诊断功能](/dashboard/dashboard-diagnostics-access.md) | Y | Y | Y | Y | Y | Y | Y | E | E | E | E | E | -| [Grafana 中的 TiKV-FastTune 面板](/grafana-tikv-dashboard.md#tikv-fasttune-面板) | E | E | E | E | E | E | E | E | E | E | E | E | -| [Information schema](/information-schema/information-schema.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [Metrics schema](/metrics-schema.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [Statements summary tables](/statement-summary-tables.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [Statements summary tables - 持久化 statements summary](/statement-summary-tables.md#持久化-statements-summary) | E | E | E | E | E | E | N | N | N | N | N | N | -| [慢查询日志](/identify-slow-queries.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [TiUP 部署](/tiup/tiup-overview.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [Kubernetes operator](https://docs.pingcap.com/tidb-in-kubernetes/stable) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [内置物理备份](/br/backup-and-restore-use-cases.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [Global Kill](/sql-statements/sql-statement-kill.md) | Y | Y | Y | Y | Y | Y | Y | Y | E | E | E | E | -| [Lock View](/information-schema/information-schema-data-lock-waits.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | E | -| [`SHOW CONFIG`](/sql-statements/sql-statement-show-config.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [`SET CONFIG`](/dynamic-config.md) | Y | Y | Y | Y | Y | Y | Y | Y | E | E | E | E | -| [DM WebUI](/dm/dm-webui-guide.md) | E | E | E | E | E | E | E | E | N | N | N | N | -| [前台限流](/tikv-configuration-file.md#前台限流) | Y | Y | Y | Y | Y | Y | Y | E | N | N | N | N | -| [后台限流](/tikv-configuration-file.md#后台限流) | E | E | E | E | E | E | E | N | N | N | N | N | -| [基于 EBS 的备份和恢复](https://docs.pingcap.com/zh/tidb-in-kubernetes/v1.4/volume-snapshot-backup-restore) | Y | Y | Y | Y | Y | Y | Y | N | N | N | N | N | -| [PITR](/br/br-pitr-guide.md) | Y | Y | Y | Y | Y | Y | Y | N | N | N | N | N | -| [全局内存控制](/configure-memory-usage.md#如何配置-tidb-server-实例使用内存的阈值) | Y | Y | Y | Y | Y | Y | Y | N | N | N | N | N | -| [RawKV 跨集群复制](/tikv-configuration-file.md#api-version-从-v610-版本开始引入) | E | E | E | E | E| E | E | N | N | N | N | N | -| [Green GC](/system-variables.md#tidb_gc_scan_lock_mode-从-v50-版本开始引入) | E | E | E | E | E | E | E | E | E | E | E | E | -| [资源管控 (Resource Control)](/tidb-resource-control.md) | Y | Y | Y | Y | Y | Y | N | N | N | N | N | N | -| [Runaway Queries 自动管理](/tidb-resource-control.md#管理资源消耗超出预期的查询-runaway-queries) | Y | Y | Y | Y | E | N | N | N | N | N | N | N | -| [后台任务资源管控](/tidb-resource-control.md#管理后台任务) | E | E | E | E | E | N | N | N | N | N | N | N | -| [TiFlash 存算分离架构与 S3 支持](/tiflash/tiflash-disaggregated-and-s3.md) | Y | Y | Y | Y | Y | E | N | N | N | N | N | N | -| [选择执行分布式执行框架任务的 TiDB 节点](/system-variables.md#tidb_service_scope-从-v740-版本开始引入) | Y | Y | Y | Y | Y | N | N | N | N | N | N | N | -| 通过系统变量 [`tidb_enable_tso_follower_proxy`](/system-variables.md#tidb_enable_tso_follower_proxy-从-v530-版本开始引入) 控制 PD Follower Proxy 功能 | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | N | N | -| 通过系统变量 [`pd_enable_follower_handle_region`](/system-variables.md#pd_enable_follower_handle_region-从-v760-版本开始引入) 控制 [Active PD Follower](/tune-region-performance.md#通过-active-pd-follower-提升-pd-region-信息查询服务的扩展能力) 功能 | E | E | E | E | N | N | N | N | N | N | N | N | -| [PD 微服务](/pd-microservices.md) | E | E | E | E | N | N | N | N | N | N | N | N | -| [TiDB 分布式执行框架](/tidb-distributed-execution-framework.md) | Y | Y | Y | Y | Y | E | N | N | N | N | N | N | -| [全局排序](/tidb-global-sort.md) | Y | Y | Y | Y | E | N | N | N | N | N | N | N | -| [TiProxy](/tiproxy/tiproxy-overview.md) | Y | Y | Y | Y | N | N | N | N | N | N | N | N | +| 管理，可视化和工具 | 8.5 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | +|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| [TiDB Dashboard 图形化展示](/dashboard/dashboard-intro.md) | Y | Y | Y | Y | Y | Y | Y | +| [TiDB Dashboard 持续性能分析功能](/dashboard/continuous-profiling.md) | Y | Y | Y | Y | Y | Y | E | +| [TiDB Dashboard Top SQL 功能](/dashboard/top-sql.md) | Y | Y | Y | Y | Y | Y | E | +| [TiDB Dashboard SQL 诊断功能](/information-schema/information-schema-sql-diagnostics.md) | Y | Y | Y | Y | Y | E | E | +| [TiDB Dashboard 集群诊断功能](/dashboard/dashboard-diagnostics-access.md) | Y | Y | Y | Y | Y | E | E | +| [Grafana 中的 TiKV-FastTune 面板](/grafana-tikv-dashboard.md#tikv-fasttune-面板) | E | E | E | E | E | E | E | +| [Information schema](/information-schema/information-schema.md) | Y | Y | Y | Y | Y | Y | Y | +| [Metrics schema](/metrics-schema.md) | Y | Y | Y | Y | Y | Y | Y | +| [Statements summary tables](/statement-summary-tables.md) | Y | Y | Y | Y | Y | Y | Y | +| [Statements summary tables - 持久化 statements summary](/statement-summary-tables.md#持久化-statements-summary) | E | E | E | E | N | N | N | +| [慢查询日志](/identify-slow-queries.md) | Y | Y | Y | Y | Y | Y | Y | +| [TiUP 部署](/tiup/tiup-overview.md) | Y | Y | Y | Y | Y | Y | Y | +| [Kubernetes operator](https://docs.pingcap.com/tidb-in-kubernetes/stable) | Y | Y | Y | Y | Y | Y | Y | +| [内置物理备份](/br/backup-and-restore-use-cases.md) | Y | Y | Y | Y | Y | Y | Y | +| [Global Kill](/sql-statements/sql-statement-kill.md) | Y | Y | Y | Y | Y | Y | E | +| [Lock View](/information-schema/information-schema-data-lock-waits.md) | Y | Y | Y | Y | Y | Y | Y | +| [`SHOW CONFIG`](/sql-statements/sql-statement-show-config.md) | Y | Y | Y | Y | Y | Y | Y | +| [`SET CONFIG`](/dynamic-config.md) | Y | Y | Y | Y | Y | Y | E | +| [DM WebUI](/dm/dm-webui-guide.md) | E | E | E | E | E | E | N | +| [前台限流](/tikv-configuration-file.md#前台限流) | Y | Y | Y | Y | Y | E | N | +| [后台限流](/tikv-configuration-file.md#后台限流) | E | E | E | E | E | N | N | +| [基于 EBS 的备份和恢复](https://docs.pingcap.com/zh/tidb-in-kubernetes/v1.4/volume-snapshot-backup-restore) | Y | Y | Y | Y | Y | N | N | +| [PITR](/br/br-pitr-guide.md) | Y | Y | Y | Y | Y | N | N | +| [全局内存控制](/configure-memory-usage.md#如何配置-tidb-server-实例使用内存的阈值) | Y | Y | Y | Y | Y | N | N | +| [RawKV 跨集群复制](/tikv-configuration-file.md#api-version-从-v610-版本开始引入) | E | E | E| E | E | N | N | +| [Green GC](/system-variables.md#tidb_gc_scan_lock_mode-从-v50-版本开始引入) | E | E | E | E | E | E | E | +| [资源管控 (Resource Control)](/tidb-resource-control-ru-groups.md) | Y | Y | Y | Y | N | N | N | +| [Runaway Queries 自动管理](/tidb-resource-control-runaway-queries.md) | Y | Y | E | N | N | N | N | +| [后台任务资源管控](/tidb-resource-control-background-tasks.md) | E | E | E | N | N | N | N | +| [TiFlash 存算分离架构与 S3 支持](/tiflash/tiflash-disaggregated-and-s3.md) | Y | Y | Y | E | N | N | N | +| [选择执行分布式执行框架任务的 TiDB 节点](/system-variables.md#tidb_service_scope-从-v740-版本开始引入) | Y | Y | Y | N | N | N | N | +| 通过系统变量 [`tidb_enable_tso_follower_proxy`](/system-variables.md#tidb_enable_tso_follower_proxy-从-v530-版本开始引入) 控制 PD Follower Proxy 功能 | Y | Y | Y | Y | Y | Y | Y | +| 通过系统变量 [`pd_enable_follower_handle_region`](/system-variables.md#pd_enable_follower_handle_region-从-v760-版本开始引入) 控制 [Active PD Follower](/tune-region-performance.md#通过-active-pd-follower-提升-pd-region-信息查询服务的扩展能力) 功能 | Y | E | N | N | N | N | N | +| [PD 微服务](/pd-microservices.md) | E | E | N | N | N | N | N | +| [TiDB 分布式执行框架](/tidb-distributed-execution-framework.md) | Y | Y | Y | E | N | N | N | +| [全局排序](/tidb-global-sort.md) | Y | Y | E | N | N | N | N | +| [TiProxy](/tiproxy/tiproxy-overview.md) | Y | Y | N | N | N | N | N | +| [Schema 缓存](/schema-cache.md) | Y | N | N | N | N | N | N | [^1]: TiDB 误将 latin1 处理为 utf8 的子集。见 [TiDB #18955](https://github.com/pingcap/tidb/issues/18955)。 @@ -274,7 +275,7 @@ aliases: ['/docs-cn/dev/basic-features/','/docs-cn/dev/experimental-features-4.0 [^3]: TiDB 支持的完整 SQL 列表，见[语句参考](/sql-statements/sql-statement-select.md)。 -[^4]: 从 [TiDB v6.4.0](/releases/release-6.4.0.md) 开始，支持[高性能、全局单调递增的 `AUTO_INCREMENT` 列](/auto-increment.md#mysql-兼容模式)。 +[^4]: 从 [TiDB v6.4.0](/releases/release-6.4.0.md) 开始，支持[高性能、全局单调递增的 `AUTO_INCREMENT` 列](/auto-increment.md#兼容-mysql-的自增列模式)。 [^5]: 从 [TiDB v7.0.0](/releases/release-7.0.0.md) 开始新增的参数 `FIELDS DEFINED NULL BY` 以及新增支持从 S3 和 GCS 导入数据，均为实验特性。从 [TiDB v7.6.0](/releases/release-7.6.0.md) 开始 `LOAD DATA` 的事务行为与 MySQL 的事务行为一致，包括事务内的 `LOAD DATA` 语句本身不再自动提交当前事务，也不会开启新事务，并且事务内的 `LOAD DATA` 语句可以被显式提交或者回滚。此外，`LOAD DATA` 语句会受 TiDB 事务模式设置（乐观/悲观）影响。 diff --git a/basic-sql-operations.md b/basic-sql-operations.md index aa2ec72dbf04..ca2a0ea4c098 100644 --- a/basic-sql-operations.md +++ b/basic-sql-operations.md @@ -1,6 +1,5 @@ --- title: SQL 基本操作 -aliases: ['/docs-cn/dev/basic-sql-operations/','/docs-cn/dev/how-to/get-started/explore-sql/'] summary: TiDB 是一个兼容 MySQL 的数据库，可以执行 DDL、DML、DQL 和 DCL 操作。可以使用 SHOW DATABASES 查看数据库列表，使用 CREATE DATABASE 创建数据库，使用 DROP DATABASE 删除数据库。使用 CREATE TABLE 创建表，使用 SHOW CREATE TABLE 查看建表语句，使用 DROP TABLE 删除表。使用 CREATE INDEX 创建索引，使用 SHOW INDEX 查看表内所有索引，使用 DROP INDEX 删除索引。使用 INSERT 向表内插入记录，使用 UPDATE 修改记录，使用 DELETE 删除记录。使用 SELECT 检索表内数据，使用 WHERE 子句进行筛选。使用 CREATE USER 创建用户，使用 GRANT 授权用户，使用 DROP USER 删除用户。 --- diff --git a/batch-processing.md b/batch-processing.md new file mode 100644 index 000000000000..96623010cbdb --- /dev/null +++ b/batch-processing.md @@ -0,0 +1,97 @@ +--- +title: 数据批量处理 +summary: 介绍了 TiDB 为数据批量处理场景提供的功能，包括 Pipelined DML、非事务性 DML、IMPORT INTO 语句以及已被废弃的 batch-dml。 +--- + +# 数据批量处理 + +批量数据处理是实际业务中常见且重要的操作，它涉及到对大量数据进行高效操作，如数据迁移、批量导入、归档操作或大规模更新等。 + +为了提升批量处理性能，TiDB 随着版本的演进提供了多种数据批量处理功能： + +- 数据导入 + - `IMPORT INTO` 语句（从 TiDB v7.2.0 开始引入，在 v7.5.0 成为正式功能） +- 数据增删改 + - Pipelined DML（从 TiDB v8.0.0 开始引入，实验特性） + - 非事务性 DML（从 TiDB v6.1.0 开始引入） + - 已废弃的 batch-dml 功能 + +本文分别介绍这些功能的主要优势、限制和使用场景，帮助你根据实际需求选择合适的方案，从而更高效地完成批量数据处理任务。 + +## 数据导入 + +`IMPORT INTO` 语句专为数据导入设计，使你无需单独部署 [TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md)，即可将 CSV、SQL 或 PARQUET 等格式的数据快速导入到 TiDB 的一张空表中。 + +主要优势： + +- 导入速度非常快。 +- 比 TiDB Lightning 更易用。 + +主要限制： + +- 不满足事务 [ACID](/glossary.md#acid) 性质。 +- 使用限制较多。 + +适用场景： + +- 数据导入场景，例如数据迁移、数据恢复等。建议在合适的场景下，使用 IMPORT INTO 代替 TiDB Lightning。 + +更多信息，请参考 [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md)。 + +## 数据增删改 + +### Pipelined DML + +Pipelined DML 是从 TiDB v8.0.0 开始引入的实验特性。在 v8.5.0 中，TiDB 对该功能进行了完善，其性能得到大幅提升。 + +主要优势： + +- 在事务执行过程中，通过将数据持续写入存储层，而不是全部缓存在内存中，使得事务大小不再受到 TiDB 内存限制，支持处理超大规模数据。 +- 性能比标准 DML 更好。 +- 通过系统变量启用，无需修改 SQL 语句。 + +主要限制： + +- 只适用于[自动提交](/transaction-overview.md#自动提交)的 `INSERT`、`REPLACE`、`UPDATE`、`DELETE` 语句。 + +适用场景： + +- 通用的批量数据处理场景，例如大量数据的插入、更新、删除等。 + +更多信息，请参考 [Pipelined DML](/pipelined-dml.md)。 + +### 非事务 DML 语句 + +非事务 DML 语句是从 TiDB v6.1.0 开始引入的功能。在 v6.1.0 中，该功能仅支持 `DELETE` 语句。从 v6.5.0 起，该功能新增支持 `INSERT`、`REPLACE`、`UPDATE` 语句。 + +主要优势： + +- 通过将一条 SQL 语句拆为多条语句执行，使得每个语句的事务更小，绕开内存限制。 +- 处理速度比标准 DML 稍快或相当。 + +主要限制： + +- 只适用于[自动提交](/transaction-overview.md#自动提交)的语句。 +- 需要修改 SQL 语句。 +- 对 SQL 语句本身限制较多，不符合条件的语句可能需要改写。 +- 因为 SQL 语句被拆分执行，不具有完整的事务 ACID 性质，在失败时语句可能部分完成。 + +适用场景： + +- 大量数据的插入、更新、删除等场景。由于限制较多，建议在 Pipelined DML 不适用的场景下考虑使用。 + +更多信息，请参考[非事务 DML 语句](/non-transactional-dml.md)。 + +### 已被废弃的 batch-dml + +TiDB 在 v4.0 之前提供了 batch-dml 功能，用于批量数据处理。该功能已被废弃，不再推荐使用。batch-dml 功能由以下这些系统变量控制： + +- `tidb_batch_insert` +- `tidb_batch_delete` +- `tidb_batch_commit` +- `tidb_enable_batch_dml` +- `tidb_dml_batch_size` + +因为该功能可能引起数据索引不一致，导致数据损坏或丢失，以上变量已被废弃，并计划将在未来的版本中逐渐移除。 + +不建议在任何场景下使用已被废弃的 batch-dml 功能。建议选择上面描述的其它方案。 \ No newline at end of file diff --git a/benchmark/benchmark-sysbench-v2.md b/benchmark/benchmark-sysbench-v2.md index 5e8a1b86018b..ef5ce303a384 100644 --- a/benchmark/benchmark-sysbench-v2.md +++ b/benchmark/benchmark-sysbench-v2.md @@ -1,6 +1,5 @@ --- title: TiDB Sysbench 性能对比测试报告 - v2.0.0 对比 v1.0.0 -aliases: ['/docs-cn/dev/benchmark/benchmark-sysbench-v2/','/docs-cn/dev/benchmark/sysbench-v2/'] summary: TiDB 2.0 版本和 1.0 版本在 OLTP 场景下进行性能对比测试。测试结果显示，GA 2.0 在 Select 查询性能上提升了约 10%，在 OLTP 性能上基本一致，而在 Insert 性能上略有提升。 --- diff --git a/benchmark/benchmark-sysbench-v3.md b/benchmark/benchmark-sysbench-v3.md index f320cd97e7df..30c8f7050118 100644 --- a/benchmark/benchmark-sysbench-v3.md +++ b/benchmark/benchmark-sysbench-v3.md @@ -1,6 +1,5 @@ --- title: TiDB Sysbench 性能对比测试报告 - v2.1 对比 v2.0 -aliases: ['/docs-cn/dev/benchmark/benchmark-sysbench-v3/','/docs-cn/dev/benchmark/sysbench-v3/'] summary: TiDB 2.1 版本在 Point Select 查询性能上提升了 50%，而在 Update Non-Index 和 Update Index 写入性能上与 2.0 版本基本一致。 --- diff --git a/benchmark/benchmark-sysbench-v4-vs-v3.md b/benchmark/benchmark-sysbench-v4-vs-v3.md index 4fc8c49771b4..c97c849a18c0 100644 --- a/benchmark/benchmark-sysbench-v4-vs-v3.md +++ b/benchmark/benchmark-sysbench-v4-vs-v3.md @@ -1,6 +1,5 @@ --- title: TiDB Sysbench 性能对比测试报告 - v4.0 对比 v3.0 -aliases: ['/docs-cn/dev/benchmark/benchmark-sysbench-v4-vs-v3/'] summary: TiDB v4.0 在 OLTP 场景下的性能优于 v3.0。Point Select、Update Non-index、Update Index 和 Read Write 性能分别提升了 14%、15%、17% 和 31%。 --- diff --git a/benchmark/benchmark-sysbench-v5-vs-v4.md b/benchmark/benchmark-sysbench-v5-vs-v4.md deleted file mode 100644 index 12cae52e7780..000000000000 --- a/benchmark/benchmark-sysbench-v5-vs-v4.md +++ /dev/null @@ -1,223 +0,0 @@ ---- -title: TiDB Sysbench 性能对比测试报告 - v5.0 对比 v4.0 -summary: TiDB v5.0 在 OLTP 场景下的性能测试结果显示，Point Select 性能提升了 2.7%，Update Non-index 性能提升了 81%，Update Index 性能提升了 28%，Read Write 性能提升了 9%。这表明在 AWS EC2 环境下，TiDB v5.0 相对于 v4.0 在各项性能指标上都有所提升。 ---- - -# TiDB Sysbench 性能对比测试报告 - v5.0 对比 v4.0 - -## 测试目的 - -测试对比 TiDB v5.0 和 v4.0 在 OLTP 场景下的性能。 - -## 测试环境 (AWS EC2) - -### 硬件配置 - -| 服务类型 | EC2 类型 | 实例数 | -|:----------|:----------|:----------| -| PD | m5.xlarge | 3 | -| TiKV | i3.4xlarge| 3 | -| TiDB | c5.4xlarge| 3 | -| Sysbench | c5.9xlarge| 1 | - -### 软件版本 - -| 服务类型 | 软件版本 | -|:----------|:-----------| -| PD | 4.0、5.0 | -| TiDB | 4.0、5.0 | -| TiKV | 4.0、5.0 | -| Sysbench | 1.0.20 | - -### 参数配置 - -#### TiDB v4.0 参数配置 - -{{< copyable "" >}} - -```yaml -log.level: "error" -performance.max-procs: 20 -prepared-plan-cache.enabled: true -tikv-client.max-batch-wait-time: 2000000 -``` - -#### TiKV v4.0 参数配置 - -{{< 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 参数配置 - -{{< copyable "" >}} - -```yaml -log.level: "error" -performance.max-procs: 20 -prepared-plan-cache.enabled: true -tikv-client.max-batch-wait-time: 2000000 -``` - -#### TiKV v5.0 参数配置 - -{{< 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 全局变量配置 - -{{< copyable "sql" >}} - -```sql -set global tidb_hashagg_final_concurrency=1; -set global tidb_hashagg_partial_concurrency=1; -``` - -#### TiDB v5.0 全局变量配置 - -{{< 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; - -``` - -## 测试方案 - -1. 通过 TiUP 部署 TiDB v5.0 和 v4.0。 -2. 通过 Sysbench 导入 16 张表，每张表有 1000 万行数据。 -3. 分别对每个表执行 `analyze table` 命令。 -4. 备份数据，用于不同并发测试前进行数据恢复，以保证每次数据一致。 -5. 启动 Sysbench 客户端，进行 `point_select`、`read_write`、`update_index` 和 `update_non_index` 测试。通过 AWS NLB 向 TiDB 加压，单轮预热 1 分钟，测试 5 分钟。 -6. 每轮完成后停止集群，使用之前的备份的数据覆盖，再启动集群。 - -### 准备测试数据 - -执行以下命令来准备测试数据： - -{{< 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 -``` - -### 执行测试命令 - -执行以下命令来执行测试： - -{{< 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 -``` - -## 测试结果 - -### Point Select 性能 - -| Threads | v4.0 QPS | v4.0 95% latency (ms) | v5.0 QPS | v5.0 95% latency (ms) | QPS 提升 | -|:----------|:----------|:----------|:----------|:----------|:----------| -| 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% | - -v5.0 对比 v4.0，Point Select 性能提升了 2.7%。 - -![Point Select](/media/sysbench_v5vsv4_point_select.png) - -### Update Non-index 性能 - -| Threads | v4.0 QPS | v4.0 95% latency (ms) | v5.0 QPS | v5.0 95% latency (ms) | QPS 提升 | -|:----------|:----------|:----------|:----------|:----------|:----------| -| 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% | - -v5.0 对比 v4.0，Update Non-index 性能提升了 81%。 - -![Update Non-index](/media/sysbench_v5vsv4_update_non_index.png) - -### Update Index 性能 - -| Threads | v4.0 QPS | v4.0 95% latency (ms) | v5.0 QPS | v5.0 95% latency (ms) | QPS 提升 | -|:----------|:----------|:----------|:----------|:----------|:----------| -| 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% | - -v5.0 对比 v4.0，Update Index 性能提升了 28%。 - -![Update Index](/media/sysbench_v5vsv4_update_index.png) - -### Read Write 性能 - -| Threads | v4.0 QPS | v4.0 95% latency (ms) | v5.0 QPS | v5.0 95% latency (ms) | QPS 提升 | -|:----------|:----------|:----------|:----------|:----------|:----------| -| 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% | - -v5.0 对比 v4.0，Read Write 性能提升了 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 deleted file mode 100644 index a45240256eb9..000000000000 --- a/benchmark/benchmark-sysbench-v5.1.0-vs-v5.0.2.md +++ /dev/null @@ -1,187 +0,0 @@ ---- -title: TiDB Sysbench 性能对比测试报告 - v5.1.0 对比 v5.0.2 -summary: TiDB v5.1.0 在 OLTP 场景下的 Sysbench 性能表现对比 v5.0.2。Point Select 性能提升了 19.4%，Read Write 和 Update Index 性能略有下降。测试环境为 AWS EC2，硬件配置包括 PD、TiKV、TiDB 和 Sysbench。软件版本为 v5.0.2、v5.1.0。参数配置相同。测试方案包括部署、数据准备和执行测试。测试结果显示各场景性能对比情况。 ---- - -# TiDB Sysbench 性能对比测试报告 - v5.1.0 对比 v5.0.2 - -## 测试概况 - -本次测试对比了 TiDB v5.1.0 和 v5.0.2 在 OLTP 场景下的 Sysbench 性能表现。结果显示，v5.1.0 相比于 v5.0.2，Point Select 场景性能提升了 19.4%，Read Write 和 Update Index 场景性能略有下降。 - -## 测试环境 (AWS EC2) - -### 硬件配置 - -| 服务类型 | EC2 类型 | 实例数 | -|:----------|:----------|:----------| -| PD | m5.xlarge | 3 | -| TiKV | i3.4xlarge| 3 | -| TiDB | c5.4xlarge| 3 | -| Sysbench | c5.9xlarge| 1 | - -### 软件版本 - -| 服务类型 | 软件版本 | -|:----------|:-----------| -| PD | v5.0.2、v5.1.0 | -| TiDB | v5.0.2、v5.1.0 | -| TiKV | v5.0.2、v5.1.0 | -| Sysbench | 1.0.20 | - -### 参数配置 - -两个版本使用相同的配置 - -#### TiDB 参数配置 - -{{< copyable "" >}} - -```yaml -log.level: "error" -performance.max-procs: 20 -prepared-plan-cache.enabled: true -tikv-client.max-batch-wait-time: 2000000 -``` - -#### TiKV 参数配置 - -{{< 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 全局变量配置 - -{{< 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; - -``` - -## 测试方案 - -1. 通过 TiUP 部署 TiDB v5.1.0 和 v5.0.2。 -2. 通过 Sysbench 导入 16 张表，每张表有 1000 万行数据。 -3. 分别对每个表执行 `analyze table` 命令。 -4. 备份数据，用于不同并发测试前进行数据恢复，以保证每次数据一致。 -5. 启动 Sysbench 客户端，进行 `point_select`、`read_write`、`update_index` 和 `update_non_index` 测试。通过 HAProxy 向 TiDB 加压，测试 5 分钟。 -6. 每轮完成后停止集群，使用之前的备份的数据覆盖，再启动集群。 - -### 准备测试数据 - -执行以下命令来准备测试数据： - -{{< 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 -``` - -### 执行测试命令 - -执行以下命令来执行测试： - -{{< 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 -``` - -## 测试结果 - -### Point Select 性能 - -| Threads | v5.0.2 QPS | v5.0.2 95% latency (ms) | v5.1.0 QPS | v5.1.0 95% latency (ms) | QPS 提升 | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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%| - -v5.1.0 对比 v5.0.2，Point Select 性能提升了 19.4%。 - -![Point Select](/media/sysbench_v510vsv502_point_select.png) - -### Update Non-index 性能 - -| Threads | v5.0.2 QPS | v5.0.2 95% latency (ms) | v5.1.0 QPS | v5.1.0 95% latency (ms) | QPS 提升 | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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%| - -v5.1.0 对比 v5.0.2，Update Non-index 性能下降了 0.8%。 - -![Update Non-index](/media/sysbench_v510vsv502_update_non_index.png) - -### Update Index 性能 - -| Threads | v5.0.2 QPS | v5.0.2 95% latency (ms) | v5.1.0 QPS | v5.1.0 95% latency (ms) | QPS 提升 | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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%| - -v5.1.0 对比 v5.0.2，Update Index 性能下降了 1.8%。 - -![Update Index](/media/sysbench_v510vsv502_update_index.png) - -### Read Write 性能 - -| Threads | v5.0.2 QPS | v5.0.2 95% latency (ms) | v5.1.0 QPS | v5.1.0 95% latency (ms) | QPS 提升 | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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%| - -v5.1.0 对比 v5.0.2，Read Write 性能下降了 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 deleted file mode 100644 index e7c4769ac2fe..000000000000 --- a/benchmark/benchmark-sysbench-v5.2.0-vs-v5.1.1.md +++ /dev/null @@ -1,187 +0,0 @@ ---- -title: TiDB Sysbench 性能对比测试报告 - v5.2.0 对比 v5.1.1 -summary: TiDB v5.2.0 在 OLTP 场景下的 Sysbench 性能对比测试显示，Point Select 性能提升了 11.03%，但其余场景性能略有下降。硬件配置为 PD m5.xlarge 3 台、TiKV i3.4xlarge 3 台、TiDB c5.4xlarge 3 台、Sysbench c5.9xlarge 1 台。软件版本为 PD v5.1.1、v5.2.0、TiDB v5.1.1、v5.2.0、TiKV v5.1.1、v5.2.0、Sysbench 1.1.0-ead2689。测试方案包括数据准备、执行测试命令和测试结果。Point Select 性能提升 11.03%，Update Non-index 性能下降 1.98%，Update Index 性能下降 4.33%，Read Write 性能下降 1.24%。 ---- - -# TiDB Sysbench 性能对比测试报告 - v5.2.0 对比 v5.1.1 - -## 测试概况 - -本次测试对比了 TiDB v5.2.0 和 v5.1.1 在 OLTP 场景下的 Sysbench 性能表现。结果显示，v5.2.0 相比于 v5.1.1，Point Select 场景性能提升了 11.03%，其余场景性能略有下降。 - -## 测试环境 (AWS EC2) - -### 硬件配置 - -| 服务类型 | EC2 类型 | 实例数 | -|:----------|:----------|:----------| -| PD | m5.xlarge | 3 | -| TiKV | i3.4xlarge| 3 | -| TiDB | c5.4xlarge| 3 | -| Sysbench | c5.9xlarge| 1 | - -### 软件版本 - -| 服务类型 | 软件版本 | -|:----------|:-----------| -| PD | v5.1.1、v5.2.0 | -| TiDB | v5.1.1、v5.2.0 | -| TiKV | v5.1.1、v5.2.0 | -| Sysbench | 1.1.0-ead2689 | - -### 参数配置 - -两个版本使用相同的配置 - -#### TiDB 参数配置 - -{{< copyable "" >}} - -```yaml -log.level: "error" -performance.max-procs: 20 -prepared-plan-cache.enabled: true -tikv-client.max-batch-wait-time: 2000000 -``` - -#### TiKV 参数配置 - -{{< 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 全局变量配置 - -{{< 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; - -``` - -## 测试方案 - -1. 通过 TiUP 部署 TiDB v5.2.0 和 v5.1.1。 -2. 通过 Sysbench 导入 16 张表，每张表有 1000 万行数据。 -3. 分别对每个表执行 `analyze table` 命令。 -4. 备份数据，用于不同并发测试前进行数据恢复，以保证每次数据一致。 -5. 启动 Sysbench 客户端，进行 `point_select`、`read_write`、`update_index` 和 `update_non_index` 测试。通过 HAProxy 向 TiDB 加压，测试 5 分钟。 -6. 每轮完成后停止集群，使用之前的备份的数据覆盖，再启动集群。 - -### 准备测试数据 - -执行以下命令来准备测试数据： - -{{< 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 -``` - -### 执行测试命令 - -执行以下命令来执行测试： - -{{< 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 -``` - -## 测试结果 - -### Point Select 性能 - -| Threads | v5.1.1 QPS | v5.1.1 95% latency (ms) | v5.2.0 QPS | v5.2.0 95% latency (ms) | QPS 提升 | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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%| - -v5.2.0 对比 v5.1.1，Point Select 性能提升了 11.03%。 - -![Point Select](/media/sysbench_v511vsv520_point_select.png) - -### Update Non-index 性能 - -| Threads | v5.1.1 QPS | v5.1.1 95% latency (ms) | v5.2.0 QPS | v5.2.0 95% latency (ms) | QPS 提升 | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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%| - -v5.2.0 对比 v5.1.1，Update Non-index 性能下降了 1.98%。 - -![Update Non-index](/media/sysbench_v511vsv520_update_non_index.png) - -### Update Index 性能 - -| Threads | v5.1.1 QPS | v5.1.1 95% latency (ms) | v5.2.0 QPS | v5.2.0 95% latency (ms) | QPS 提升 | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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%| - -v5.2.0 对比 v5.1.1，Update Index 性能下降了 4.33%。 - -![Update Index](/media/sysbench_v511vsv520_update_index.png) - -### Read Write 性能 - -| Threads | v5.1.1 QPS | v5.1.1 95% latency (ms) | v5.2.0 QPS | v5.2.0 95% latency (ms) | QPS 提升 | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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%| - -v5.2.0 对比 v5.1.1，Read Write 性能下降了 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 deleted file mode 100644 index 6ab0cb0d16d2..000000000000 --- a/benchmark/benchmark-sysbench-v5.3.0-vs-v5.2.2.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -title: TiDB Sysbench 性能对比测试报告 - v5.3.0 对比 v5.2.2 -summary: TiDB v5.3.0 和 v5.2.2 在 OLTP 场景下的 Sysbench 性能对比测试结果显示，v5.3.0 相比于 v5.2.2，性能基本持平。具体测试结果如下：Point Select 性能：v5.3.0 略下降了 0.81%、Update Non-index 性能：v5.3.0 略上升了 0.95%、Update Index 性能：v5.3.0 略上升了 1.83%、Read Write 性能：v5.3.0 略下降了 0.62%。 ---- - -# TiDB Sysbench 性能对比测试报告 - v5.3.0 对比 v5.2.2 - -## 测试概况 - -本次测试对比了 TiDB v5.3.0 和 v5.2.2 在 OLTP 场景下的 Sysbench 性能表现。结果显示，v5.3.0 相比于 v5.2.2，性能基本持平。 - -## 测试环境 (AWS EC2) - -### 硬件配置 - -| 服务类型 | EC2 类型 | 实例数 | -|:----------|:----------|:----------| -| PD | m5.xlarge | 3 | -| TiKV | i3.4xlarge| 3 | -| TiDB | c5.4xlarge| 3 | -| Sysbench | c5.9xlarge| 1 | - -### 软件版本 - -| 服务类型 | 软件版本 | -|:----------|:-----------| -| PD | v5.2.2、v5.3.0 | -| TiDB | v5.2.2、v5.3.0 | -| TiKV | v5.2.2、v5.3.0 | -| Sysbench | 1.1.0-ead2689 | - -### 参数配置 - -两个版本使用相同的配置 - -#### TiDB 参数配置 - -{{< copyable "" >}} - -```yaml -log.level: "error" -performance.max-procs: 20 -prepared-plan-cache.enabled: true -tikv-client.max-batch-wait-time: 2000000 -``` - -#### TiKV 参数配置 - -{{< 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 全局变量配置 - -{{< 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 配置 - haproxy.cfg 文件 - -更多有关 HAProxy 在 TiDB 上的使用，可参阅 [HAProxy 在 TiDB 中的最佳实践](/best-practices/haproxy-best-practices.md)。 - -{{< copyable "" >}} - -```yaml -global # 全局配置。 - chroot /var/lib/haproxy # 更改当前目录并为启动进程设置超级用户权限，从而提高安全性。 - pidfile /var/run/haproxy.pid # 将 HAProxy 进程的 PID 写入 pidfile。 - maxconn 4000 # 每个 HAProxy 进程所接受的最大并发连接数。 - user haproxy # 同 UID 参数。 - group haproxy # 同 GID 参数，建议使用专用用户组。 - nbproc 64 # 在后台运行时创建的进程数。在启动多个进程转发请求时，确保该值足够大，保证 HAProxy 不会成为瓶颈。 - daemon # 让 HAProxy 以守护进程的方式工作于后台，等同于命令行参数“-D”的功能。当然，也可以在命令行中用“-db”参数将其禁用。 - -defaults # 默认配置。 - log global # 日志继承全局配置段的设置。 - retries 2 # 向上游服务器尝试连接的最大次数，超过此值便认为后端服务器不可用。 - timeout connect 2s # HAProxy 与后端服务器连接超时时间。如果在同一个局域网内，可设置成较短的时间。 - timeout client 30000s # 客户端与 HAProxy 连接后，数据传输完毕，即非活动连接的超时时间。 - timeout server 30000s # 服务器端非活动连接的超时时间。 - -listen tidb-cluster # 配置 database 负载均衡。 - bind 0.0.0.0:3390 # 浮动 IP 和 监听端口。 - mode tcp # HAProxy 要使用第 4 层的传输层。 - balance roundrobin # 连接数最少的服务器优先接收连接。`leastconn` 建议用于长会话服务，例如 LDAP、SQL、TSE 等，而不是短会话协议，如 HTTP。该算法是动态的，对于启动慢的服务器，服务器权重会在运行中作调整。 - server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # 检测 4000 端口，检测频率为每 2000 毫秒一次。如果 2 次检测为成功，则认为服务器可用；如果 3 次检测为失败，则认为服务器不可用。 - 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 -``` - -## 测试方案 - -1. 通过 TiUP 部署 TiDB v5.3.0 和 v5.2.2。 -2. 通过 Sysbench 导入 16 张表，每张表有 1000 万行数据。 -3. 分别对每个表执行 `analyze table` 命令。 -4. 备份数据，用于不同并发测试前进行数据恢复，以保证每次数据一致。 -5. 启动 Sysbench 客户端，进行 `point_select`、`read_write`、`update_index` 和 `update_non_index` 测试。通过 HAProxy 向 TiDB 加压，每种负载每个并发数各测试 20 分钟。 -6. 每轮完成后停止集群，使用之前的备份的数据覆盖，再启动集群。 - -### 准备测试数据 - -执行以下命令来准备测试数据： - -{{< 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 -``` - -### 执行测试命令 - -执行以下命令来执行测试： - -{{< 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 -``` - -## 测试结果 - -### Point Select 性能 - -| Threads | v5.2.2 TPS | v5.3.0 TPS | v5.2.2 95% latency (ms) | v5.3.0 95% latency (ms) | TPS 提升 (%) | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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| - -v5.3.0 对比 v5.2.2，Point Select 性能基本持平，略下降了 0.81%。 - -![Point Select](/media/sysbench_v522vsv530_point_select.png) - -### Update Non-index 性能 - -| Threads | v5.2.2 TPS | v5.3.0 TPS | v5.2.2 95% latency (ms) | v5.3.0 95% latency (ms) | TPS 提升 (%) | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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| - -v5.3.0 对比 v5.2.2，Update Non-index 性能基本持平，略上升了 0.95%。 - -![Update Non-index](/media/sysbench_v522vsv530_update_non_index.png) - -### Update Index 性能 - -| Threads | v5.2.2 TPS | v5.3.0 TPS | v5.2.2 95% latency (ms) | v5.3.0 95% latency (ms) | TPS 提升 (%) | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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| - -v5.3.0 对比 v5.2.2，Update Index 性能基本持平，略上升了 1.83%。 - -![Update Index](/media/sysbench_v522vsv530_update_index.png) - -### Read Write 性能 - -| Threads | v5.2.2 TPS | v5.3.0 TPS | v5.2.2 95% latency (ms) | v5.3.0 95% latency (ms) | TPS 提升 (%) | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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| - -v5.3.0 对比 v5.2.2，Read Write 性能基本持平，略下降了 0.62%。 - -![Read Write](/media/sysbench_v522vsv530_read_write.png) 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 deleted file mode 100644 index edf021fb5224..000000000000 --- a/benchmark/benchmark-sysbench-v5.4.0-vs-v5.3.0.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -title: TiDB Sysbench 性能对比测试报告 - v5.4.0 对比 v5.3.0 -summary: TiDB v5.4.0 在 OLTP 场景下的 Sysbench 性能比 v5.3.0 有所提升，其中写负载性能提升了 2.59% ~ 4.85%。测试环境为 AWS EC2，硬件配置包括 PD、TiKV、TiDB 和 Sysbench 实例。两个版本使用相同的配置，通过 TiUP 部署。测试结果显示 Point Select 性能基本持平，Update Non-index 性能提升了 2.59%，Update Index 性能提升了 4.85%，Read Write 性能提升了 3.30%。 ---- - -# TiDB Sysbench 性能对比测试报告 - v5.4.0 对比 v5.3.0 - -## 测试概况 - -本次测试对比了 TiDB v5.4.0 和 v5.3.0 在 OLTP 场景下的 Sysbench 性能表现。结果显示，相比于 v5.3.0，v5.4.0 的写负载 (Write-heavy Workload) 性能有 2.59% ~ 4.85% 的提升。 - -## 测试环境 (AWS EC2) - -### 硬件配置 - -| 服务类型 | EC2 类型 | 实例数 | -|:----------|:----------|:----------| -| PD | m5.xlarge | 3 | -| TiKV | i3.4xlarge| 3 | -| TiDB | c5.4xlarge| 3 | -| Sysbench | c5.9xlarge| 1 | - -### 软件版本 - -| 服务类型 | 软件版本 | -|:----------|:-----------| -| PD | v5.3.0、v5.4.0 | -| TiDB | v5.3.0、v5.4.0 | -| TiKV | v5.3.0、v5.4.0 | -| Sysbench | 1.1.0-ead2689 | - -### 参数配置 - -两个版本使用相同的配置 - -#### TiDB 参数配置 - -{{< copyable "" >}} - -```yaml -log.level: "error" -performance.max-procs: 20 -prepared-plan-cache.enabled: true -tikv-client.max-batch-wait-time: 2000000 -``` - -#### TiKV 参数配置 - -{{< 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 全局变量配置 - -{{< 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 配置 - haproxy.cfg 文件 - -更多有关 HAProxy 在 TiDB 上的使用，可参阅 [HAProxy 在 TiDB 中的最佳实践](/best-practices/haproxy-best-practices.md)。 - -{{< copyable "" >}} - -```yaml -global # 全局配置。 - chroot /var/lib/haproxy # 更改当前目录并为启动进程设置超级用户权限，从而提高安全性。 - pidfile /var/run/haproxy.pid # 将 HAProxy 进程的 PID 写入 pidfile。 - maxconn 4000 # 每个 HAProxy 进程所接受的最大并发连接数。 - user haproxy # 同 UID 参数。 - group haproxy # 同 GID 参数，建议使用专用用户组。 - nbproc 64 # 在后台运行时创建的进程数。在启动多个进程转发请求时，确保该值足够大，保证 HAProxy 不会成为瓶颈。 - daemon # 让 HAProxy 以守护进程的方式工作于后台，等同于命令行参数“-D”的功能。当然，也可以在命令行中用“-db”参数将其禁用。 - -defaults # 默认配置。 - log global # 日志继承全局配置段的设置。 - retries 2 # 向上游服务器尝试连接的最大次数，超过此值便认为后端服务器不可用。 - timeout connect 2s # HAProxy 与后端服务器连接超时时间。如果在同一个局域网内，可设置成较短的时间。 - timeout client 30000s # 客户端与 HAProxy 连接后，数据传输完毕，即非活动连接的超时时间。 - timeout server 30000s # 服务器端非活动连接的超时时间。 - -listen tidb-cluster # 配置 database 负载均衡。 - bind 0.0.0.0:3390 # 浮动 IP 和 监听端口。 - mode tcp # HAProxy 要使用第 4 层的传输层。 - balance roundrobin # 连接数最少的服务器优先接收连接。`leastconn` 建议用于长会话服务，例如 LDAP、SQL、TSE 等，而不是短会话协议，如 HTTP。该算法是动态的，对于启动慢的服务器，服务器权重会在运行中作调整。 - server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # 检测 4000 端口，检测频率为每 2000 毫秒一次。如果 2 次检测为成功，则认为服务器可用；如果 3 次检测为失败，则认为服务器不可用。 - 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 -``` - -## 测试方案 - -1. 通过 TiUP 部署 TiDB v5.4.0 和 v5.3.0。 -2. 通过 Sysbench 导入 16 张表，每张表有 1000 万行数据。 -3. 分别对每个表执行 `analyze table` 命令。 -4. 备份数据，用于不同并发测试前进行数据恢复，以保证每次数据一致。 -5. 启动 Sysbench 客户端，进行 `point_select`、`read_write`、`update_index` 和 `update_non_index` 测试。通过 HAProxy 向 TiDB 加压，每种负载每个并发数各测试 20 分钟。 -6. 每轮完成后停止集群，使用之前的备份的数据覆盖，再启动集群。 - -### 准备测试数据 - -执行以下命令来准备测试数据： - -{{< 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 -``` - -### 执行测试命令 - -执行以下命令来执行测试： - -{{< 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 -``` - -## 测试结果 - -### Point Select 性能 - -| Threads | v5.3.0 TPS | v5.4.0 TPS | v5.3.0 95% latency (ms) | v5.4.0 95% latency (ms) | TPS 提升 (%) | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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| - -v5.4.0 对比 v5.3.0，Point Select 性能基本持平，略提升了 0.64%。 - -![Point Select](/media/sysbench_v530vsv540_point_select.png) - -### Update Non-index 性能 - -| Threads | v5.3.0 TPS | v5.4.0 TPS | v5.3.0 95% latency (ms) | v5.4.0 95% latency (ms) | TPS 提升 (%) | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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| - -v5.4.0 对比 v5.3.0，Update Non-index 性能提升了 2.59%。 - -![Update Non-index](/media/sysbench_v530vsv540_update_non_index.png) - -### Update Index 性能 - -| Threads | v5.3.0 TPS | v5.4.0 TPS | v5.3.0 95% latency (ms) | v5.4.0 95% latency (ms) | TPS 提升 (%) | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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| - -v5.4.0 对比 v5.3.0，Update Index 性能提升了 4.85%。 - -![Update Index](/media/sysbench_v530vsv540_update_index.png) - -### Read Write 性能 - -| Threads | v5.3.0 TPS | v5.4.0 TPS | v5.3.0 95% latency (ms) | v5.4.0 95% latency (ms) | TPS 提升 (%) | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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| - -v5.4.0 对比 v5.3.0，Read Write 性能提升了 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 deleted file mode 100644 index 4a9ea0df0ebc..000000000000 --- a/benchmark/benchmark-sysbench-v6.0.0-vs-v5.4.0.md +++ /dev/null @@ -1,201 +0,0 @@ ---- -title: TiDB Sysbench 性能对比测试报告 - v6.0.0 对比 v5.4.0 -summary: TiDB v6.0.0 在 OLTP 场景下的 Sysbench 性能表现对比 v5.4.0。结果显示，Read Write 负载性能有大幅提升，提升了 16.17%，其他负载性能基本持平。测试环境为 AWS EC2，硬件配置包括 PD、TiKV、TiDB 和 Sysbench 实例。软件版本为 v5.4.0 和 v6.0.0，参数配置相同。测试方案包括部署 TiDB、导入数据、执行测试命令和备份数据。测试结果显示 Point Select 性能基本持平，Update Non-index 性能基本持平，Update Index 性能下降了 3.05%。Update Index 性能下降了 3.05%。 ---- - -# TiDB Sysbench 性能对比测试报告 - v6.0.0 对比 v5.4.0 - -## 测试概况 - -本次测试对比了 TiDB v6.0.0 和 v5.4.0 在 OLTP 场景下的 Sysbench 性能表现。结果显示，相比于 v5.4.0，v6.0.0 的 Read Write 负载性能有大幅提升，提升了 16.17%。其他负载性能基本与 v5.4.0 的持平。 - -## 测试环境 (AWS EC2) - -### 硬件配置 - -| 服务类型 | EC2 类型 | 实例数 | -|:----------|:----------|:----------| -| PD | m5.xlarge | 3 | -| TiKV | i3.4xlarge| 3 | -| TiDB | c5.4xlarge| 3 | -| Sysbench | c5.9xlarge| 1 | - -### 软件版本 - -| 服务类型 | 软件版本 | -|:----------|:-----------| -| PD | v5.4.0、v6.0.0 | -| TiDB | v5.4.0、v6.0.0 | -| TiKV | v5.4.0、v6.0.0 | -| Sysbench | 1.1.0-df89d34 | - -### 参数配置 - -两个版本使用相同的配置 - -#### TiDB 参数配置 - -{{< copyable "" >}} - -```yaml -log.level: "error" -prepared-plan-cache.enabled: true -tikv-client.max-batch-wait-time: 2000000 -``` - -#### TiKV 参数配置 - -{{< 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 全局变量配置 - -{{< 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 配置 - haproxy.cfg 文件 - -更多有关 HAProxy 在 TiDB 上的使用，可参阅 [HAProxy 在 TiDB 中的最佳实践](/best-practices/haproxy-best-practices.md)。 - -{{< copyable "" >}} - -```yaml -global # 全局配置。 - pidfile /var/run/haproxy.pid # 将 HAProxy 进程的 PID 写入 pidfile。 - maxconn 4000 # 每个 HAProxy 进程所接受的最大并发连接数。 - user haproxy # 同 UID 参数。 - group haproxy # 同 GID 参数，建议使用专用用户组。 - nbproc 64 # 在后台运行时创建的进程数。在启动多个进程转发请求时，确保该值足够大，保证 HAProxy 不会成为瓶颈。 - daemon # 让 HAProxy 以守护进程的方式工作于后台，等同于命令行参数“-D”的功能。当然，也可以在命令行中用“-db”参数将其禁用。 - -defaults # 默认配置。 - log global # 日志继承全局配置段的设置。 - retries 2 # 向上游服务器尝试连接的最大次数，超过此值便认为后端服务器不可用。 - timeout connect 2s # HAProxy 与后端服务器连接超时时间。如果在同一个局域网内，可设置成较短的时间。 - timeout client 30000s # 客户端与 HAProxy 连接后，数据传输完毕，即非活动连接的超时时间。 - timeout server 30000s # 服务器端非活动连接的超时时间。 - -listen tidb-cluster # 配置 database 负载均衡。 - bind 0.0.0.0:3390 # 浮动 IP 和 监听端口。 - mode tcp # HAProxy 要使用第 4 层的传输层。 - balance leastconn # 连接数最少的服务器优先接收连接。`leastconn` 建议用于长会话服务，例如 LDAP、SQL、TSE 等，而不是短会话协议，如 HTTP。该算法是动态的，对于启动慢的服务器，服务器权重会在运行中作调整。 - server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # 检测 4000 端口，检测频率为每 2000 毫秒一次。如果 2 次检测为成功，则认为服务器可用；如果 3 次检测为失败，则认为服务器不可用。 - 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 -``` - -## 测试方案 - -1. 通过 TiUP 部署 TiDB v6.0.0 和 v5.4.0。 -2. 通过 Sysbench 导入 16 张表，每张表有 1000 万行数据。 -3. 分别对每个表执行 `analyze table` 命令。 -4. 备份数据，用于不同并发测试前进行数据恢复，以保证每次数据一致。 -5. 启动 Sysbench 客户端，进行 `point_select`、`read_write`、`update_index` 和 `update_non_index` 测试。通过 HAProxy 向 TiDB 加压，每种负载每个并发数各测试 20 分钟。 -6. 每轮完成后停止集群，使用之前的备份的数据覆盖，再启动集群。 - -### 准备测试数据 - -执行以下命令来准备测试数据： - -{{< 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 -``` - -### 执行测试命令 - -执行以下命令来执行测试： - -{{< 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 -``` - -## 测试结果 - -### Point Select 性能 - -| Threads | v5.4.0 TPS | v6.0.0 TPS | v5.4.0 95% latency (ms) | v6.0.0 95% latency (ms) | TPS 提升 (%) | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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| - -v6.0.0 对比 v5.4.0，Point Select 性能基本持平，略下降了 1.79%。 - -![Point Select](/media/sysbench_v540vsv600_point_select.png) - -### Update Non-index 性能 - -| Threads | v5.4.0 TPS | v6.0.0 TPS | v5.4.0 95% latency (ms) | v6.0.0 95% latency (ms) | TPS 提升 (%) | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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| - -v6.0.0 对比 v5.4.0，Update Non-index 性能基本持平，略下降了 1.98%。 - -![Update Non-index](/media/sysbench_v540vsv600_update_non_index.png) - -### Update Index 性能 - -| Threads | v5.4.0 TPS | v6.0.0 TPS | v5.4.0 95% latency (ms) | v6.0.0 95% latency (ms) | TPS 提升 (%) | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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| - -v6.0.0 对比 v5.4.0，Update Index 性能下降了 3.05%。 - -![Update Index](/media/sysbench_v540vsv600_update_index.png) - -### Read Write 性能 - -| Threads | v5.4.0 TPS | v6.0.0 TPS | v5.4.0 95% latency (ms) | v6.0.0 95% latency (ms) | TPS 提升 (%) | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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| - -v6.0.0 对比 v5.4.0，Read Write 性能有大幅提升，提升了 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 deleted file mode 100644 index 3b8953af1e02..000000000000 --- a/benchmark/benchmark-sysbench-v6.1.0-vs-v6.0.0.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -title: TiDB Sysbench 性能对比测试报告 - v6.1.0 对比 v6.0.0 -summary: TiDB v6.1.0 在 OLTP 场景下的 Sysbench 性能表现优于 v6.0.0。写性能有提升，Write-heavy 负载性能提升了 2.33% 到 4.61%。Point Select 性能基本持平，略下降了 2.1%。Update Non-index 性能提升了 3.88%。Update Index 性能提升了 4.61%。Read Write 性能提升了 2.23%。 ---- - -# TiDB Sysbench 性能对比测试报告 - v6.1.0 对比 v6.0.0 - -## 测试概况 - -本次测试对比了 TiDB v6.1.0 和 v6.0.0 在 OLTP 场景下的 Sysbench 性能表现。结果显示，相比于 v6.0.0，v6.1.0 的写性能有提升，Write-heavy 负载性能有 2.33% 到 4.61% 的提升。 - -## 测试环境 (AWS EC2) - -### 硬件配置 - -| 服务类型 | EC2 类型 | 实例数 | -|:----------|:----------|:----------| -| PD | m5.xlarge | 3 | -| TiKV | i3.4xlarge| 3 | -| TiDB | c5.4xlarge| 3 | -| Sysbench | c5.9xlarge| 1 | - -### 软件版本 - -| 服务类型 | 软件版本 | -|:----------|:-----------| -| PD | v6.0.0、v6.1.0 | -| TiDB | v6.0.0、v6.1.0 | -| TiKV | v6.0.0、v6.1.0 | -| Sysbench | 1.1.0-df89d34 | - -### 参数配置 - -两个版本使用相同的配置。 - -#### TiDB 参数配置 - -{{< copyable "" >}} - -```yaml -log.level: "error" -prepared-plan-cache.enabled: true -tikv-client.max-batch-wait-time: 2000000 -``` - -#### TiKV 参数配置 - -{{< 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 全局变量配置 - -{{< 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 配置 - haproxy.cfg 文件 - -更多有关 HAProxy 在 TiDB 上的使用，可参阅 [HAProxy 在 TiDB 中的最佳实践](/best-practices/haproxy-best-practices.md)。 - -{{< copyable "" >}} - -```yaml -global # 全局配置。 - pidfile /var/run/haproxy.pid # 将 HAProxy 进程的 PID 写入 pidfile。 - maxconn 4000 # 每个 HAProxy 进程所接受的最大并发连接数。 - user haproxy # 同 UID 参数。 - group haproxy # 同 GID 参数，建议使用专用用户组。 - nbproc 64 # 在后台运行时创建的进程数。在启动多个进程转发请求时，确保该值足够大，保证 HAProxy 不会成为瓶颈。 - daemon # 让 HAProxy 以守护进程的方式工作于后台，等同于命令行参数“-D”的功能。当然，也可以在命令行中用“-db”参数将其禁用。 - -defaults # 默认配置。 - log global # 日志继承全局配置段的设置。 - retries 2 # 向上游服务器尝试连接的最大次数，超过此值便认为后端服务器不可用。 - timeout connect 2s # HAProxy 与后端服务器连接超时时间。如果在同一个局域网内，可设置成较短的时间。 - timeout client 30000s # 客户端与 HAProxy 连接后，数据传输完毕，即非活动连接的超时时间。 - timeout server 30000s # 服务器端非活动连接的超时时间。 - -listen tidb-cluster # 配置 database 负载均衡。 - bind 0.0.0.0:3390 # 浮动 IP 和 监听端口。 - mode tcp # HAProxy 要使用第 4 层的传输层。 - balance leastconn # 连接数最少的服务器优先接收连接。`leastconn` 建议用于长会话服务，例如 LDAP、SQL、TSE 等，而不是短会话协议，如 HTTP。该算法是动态的，对于启动慢的服务器，服务器权重会在运行中作调整。 - server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # 检测 4000 端口，检测频率为每 2000 毫秒一次。如果 2 次检测为成功，则认为服务器可用；如果 3 次检测为失败，则认为服务器不可用。 - 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 -``` - -## 测试方案 - -1. 通过 TiUP 部署 TiDB v6.1.0 和 v6.0.0。 -2. 通过 Sysbench 导入 16 张表，每张表有 1000 万行数据。 -3. 分别对每个表执行 `analyze table` 命令。 -4. 备份数据，用于不同并发测试前进行数据恢复，以保证每次数据一致。 -5. 启动 Sysbench 客户端，进行 `point_select`、`read_write`、`update_index` 和 `update_non_index` 测试。通过 HAProxy 向 TiDB 加压，每种负载每个并发数各测试 20 分钟。 -6. 每轮完成后停止集群，使用之前的备份的数据覆盖，再启动集群。 - -### 准备测试数据 - -执行以下命令来准备测试数据： - -{{< 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 -``` - -### 执行测试命令 - -执行以下命令来执行测试： - -{{< 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 -``` - -## 测试结果 - -### Point Select 性能 - -| Threads | v6.0.0 TPS | v6.1.0 TPS | v6.0.0 95% latency (ms) | v6.1.0 95% latency (ms) | TPS 提升 (%) | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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| - -v6.1.0 对比 v6.0.0，Point Select 性能基本持平，略下降了 2.1%。 - -![Point Select](/media/sysbench_v600vsv610_point_select.png) - -### Update Non-index 性能 - -| Threads | v6.0.0 TPS | v6.1.0 TPS | v6.0.0 95% latency (ms) | v6.1.0 95% latency (ms) | TPS 提升 (%) | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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| - -v6.1.0 对比 v6.0.0，Update Non-index 性能提升了 3.88%。 - -![Update Non-index](/media/sysbench_v600vsv610_update_non_index.png) - -### Update Index 性能 - -| Threads | v6.0.0 TPS | v6.1.0 TPS | v6.0.0 95% latency (ms) | v6.1.0 95% latency (ms) | TPS 提升 (%) | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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| - -v6.1.0 对比 v6.0.0，Update Index 性能提升 4.61%。 - -![Update Index](/media/sysbench_v600vsv610_update_index.png) - -### Read Write 性能 - -| Threads | v6.0.0 TPS | v6.1.0 TPS | v6.0.0 95% latency (ms) | v6.1.0 95% latency (ms) | TPS 提升 (%) | -|:----------|:----------|:----------|:----------|:----------|:----------| -|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| - -v6.1.0 对比 v6.0.0，Read Write 性能提升了 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 deleted file mode 100644 index 37c4b5ae941f..000000000000 --- a/benchmark/benchmark-sysbench-v6.2.0-vs-v6.1.0.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -title: TiDB Sysbench 性能对比测试报告 - v6.2.0 对比 v6.1.0 -summary: TiDB v6.2.0 和 v6.1.0 在 OLTP 场景下的 Sysbench 性能对比测试结果显示，两个版本性能基本持平。然而，v6.2.0 的 Point Select 性能下降了 3.58%，而 Update Non-index、Update Index 和 Read Write 性能基本持平或下降了不到 1.5%。 ---- - -# TiDB Sysbench 性能对比测试报告 - v6.2.0 对比 v6.1.0 - -## 测试概况 - -本次测试对比了 TiDB v6.2.0 和 v6.1.0 在 OLTP 场景下的 Sysbench 性能表现。结果显示，两个版本性能基本持平，相比于 v6.1.0，v6.2.0 的 Point Select 性能下降了 3.58%。 - -## 测试环境 (AWS EC2) - -### 硬件配置 - -| 服务类型 | EC2 类型 | 实例数 | -| :------- | :--------- | :----- | -| PD | m5.xlarge | 3 | -| TiKV | i3.4xlarge | 3 | -| TiDB | c5.4xlarge | 3 | -| Sysbench | c5.9xlarge | 1 | - -### 软件版本 - -| 服务类型 | 软件版本 | -| :------- | :------------- | -| PD | v6.1.0、v6.2.0 | -| TiDB | v6.1.0、v6.2.0 | -| TiKV | v6.1.0、v6.2.0 | -| Sysbench | 1.1.0-df89d34 | - -### 参数配置 - -两个版本使用相同的配置。 - -#### TiDB 参数配置 - -{{< copyable "" >}} - -```yaml -log.level: "error" -prepared-plan-cache.enabled: true -tikv-client.max-batch-wait-time: 2000000 -``` - -#### TiKV 参数配置 - -{{< 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 全局变量配置 - -{{< 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 配置 - haproxy.cfg 文件 - -更多有关 HAProxy 在 TiDB 上的使用，可参阅 [HAProxy 在 TiDB 中的最佳实践](/best-practices/haproxy-best-practices.md)。 - -{{< copyable "" >}} - -```yaml -global # 全局配置。 - pidfile /var/run/haproxy.pid # 将 HAProxy 进程的 PID 写入 pidfile。 - maxconn 4000 # 每个 HAProxy 进程所接受的最大并发连接数。 - user haproxy # 同 UID 参数。 - group haproxy # 同 GID 参数，建议使用专用用户组。 - nbproc 64 # 在后台运行时创建的进程数。在启动多个进程转发请求时，确保该值足够大，保证 HAProxy 不会成为瓶颈。 - daemon # 让 HAProxy 以守护进程的方式工作于后台，等同于命令行参数“-D”的功能。当然，也可以在命令行中用“-db”参数将其禁用。 - -defaults # 默认配置。 - log global # 日志继承全局配置段的设置。 - retries 2 # 向上游服务器尝试连接的最大次数，超过此值便认为后端服务器不可用。 - timeout connect 2s # HAProxy 与后端服务器连接超时时间。如果在同一个局域网内，可设置成较短的时间。 - timeout client 30000s # 客户端与 HAProxy 连接后，数据传输完毕，即非活动连接的超时时间。 - timeout server 30000s # 服务器端非活动连接的超时时间。 - -listen tidb-cluster # 配置 database 负载均衡。 - bind 0.0.0.0:3390 # 浮动 IP 和 监听端口。 - mode tcp # HAProxy 要使用第 4 层的传输层。 - balance leastconn # 连接数最少的服务器优先接收连接。`leastconn` 建议用于长会话服务，例如 LDAP、SQL、TSE 等，而不是短会话协议，如 HTTP。该算法是动态的，对于启动慢的服务器，服务器权重会在运行中作调整。 - server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # 检测 4000 端口，检测频率为每 2000 毫秒一次。如果 2 次检测为成功，则认为服务器可用；如果 3 次检测为失败，则认为服务器不可用。 - 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 -``` - -## 测试方案 - -1. 通过 TiUP 部署 TiDB v6.2.0 和 v6.1.0。 -2. 通过 Sysbench 导入 16 张表，每张表有 1000 万行数据。 -3. 分别对每个表执行 `analyze table` 命令。 -4. 备份数据，用于不同并发测试前进行数据恢复，以保证每次数据一致。 -5. 启动 Sysbench 客户端，进行 `point_select`、`read_write`、`update_index` 和 `update_non_index` 测试。通过 HAProxy 向 TiDB 加压，每种负载每个并发数各测试 20 分钟。 -6. 每轮完成后停止集群，使用之前的备份的数据覆盖，再启动集群。 - -### 准备测试数据 - -执行以下命令来准备测试数据： - -{{< 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 -``` - -### 执行测试命令 - -执行以下命令来执行测试： - -{{< 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 -``` - -## 测试结果 - -### Point Select 性能 - -| Threads | v6.1.0 TPS | v6.2.0 TPS | v6.1.0 95% latency (ms) | v6.2.0 95% latency (ms) | TPS 提升 (%) | -| :------ | :--------- | :--------- | :---------------------- | :---------------------- | :----------- | -| 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 | - -v6.2.0 对比 v6.1.0，Point Select 性能下降了 3.58%。 - -![Point Select](/media/sysbench_v610vsv620_point_select.png) - -### Update Non-index 性能 - -| Threads | v6.1.0 TPS | v6.2.0 TPS | v6.1.0 95% latency (ms) | v6.2.0 95% latency (ms) | TPS 提升 (%) | -| :------ | :--------- | :--------- | :---------------------- | :---------------------- | :----------- | -| 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 | - -v6.2.0 对比 v6.1.0，Update Non-index 性能基本持平，下降了 0.85%。 - -![Update Non-index](/media/sysbench_v610vsv620_update_non_index.png) - -### Update Index 性能 - -| Threads | v6.1.0 TPS | v6.2.0 TPS | v6.1.0 95% latency (ms) | v6.2.0 95% latency (ms) | TPS 提升 (%) | -| :------ | :--------- | :--------- | :---------------------- | :---------------------- | :----------- | -| 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 | - -v6.2.0 对比 v6.1.0，Update Index 性能基本持平，下降了 0.47%。 - -![Update Index](/media/sysbench_v610vsv620_update_index.png) - -### Read Write 性能 - -| Threads | v6.1.0 TPS | v6.2.0 TPS | v6.1.0 95% latency (ms) | v6.2.0 95% latency (ms) | TPS 提升 (%) | -| :------ | :--------- | :--------- | :---------------------- | :---------------------- | :----------- | -| 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 | - -v6.2.0 对比 v6.1.0，Read Write 性能下降了 1.21%。 - -![Read Write](/media/sysbench_v610vsv620_read_write.png) diff --git a/benchmark/benchmark-tidb-using-sysbench.md b/benchmark/benchmark-tidb-using-sysbench.md index 420e347d402c..a12be2bcf992 100644 --- a/benchmark/benchmark-tidb-using-sysbench.md +++ b/benchmark/benchmark-tidb-using-sysbench.md @@ -1,6 +1,5 @@ --- title: 如何用 Sysbench 测试 TiDB -aliases: ['/docs-cn/dev/benchmark/benchmark-tidb-using-sysbench/','/docs-cn/dev/benchmark/how-to-run-sysbench/'] summary: 使用 Sysbench 1.0 或更新版本测试 TiDB 性能。调整 TiDB 和 TiKV 的日志级别以提高性能。配置 RocksDB 的 block cache 以充分利用内存。调整 Sysbench 配置文件并导入数据。进行数据预热和统计信息收集。执行 Point select、Update index 和 Read-only 测试命令。解决可能出现的性能问题。 --- diff --git a/benchmark/benchmark-tidb-using-tpcc.md b/benchmark/benchmark-tidb-using-tpcc.md index 7e923e4331fe..b53217be3696 100644 --- a/benchmark/benchmark-tidb-using-tpcc.md +++ b/benchmark/benchmark-tidb-using-tpcc.md @@ -1,6 +1,5 @@ --- title: 如何对 TiDB 进行 TPC-C 测试 -aliases: ['/docs-cn/dev/benchmark/benchmark-tidb-using-tpcc/','/docs-cn/dev/benchmark/how-to-run-tpcc/'] summary: 本文介绍了如何对 TiDB 进行 TPC-C 测试。TPC-C 是一个对 OLTP 系统进行测试的规范，使用商品销售模型对系统进行测试，包含五类事务：NewOrder、Payment、OrderStatus、Delivery、StockLevel。测试使用 tpmC 值衡量系统最大有效吞吐量，以 NewOrder Transaction 为准。使用 go-tpc 进行测试实现，通过 TiUP 命令下载测试程序。测试包括数据导入、运行测试和清理测试数据。 --- diff --git a/benchmark/benchmark-tpch.md b/benchmark/benchmark-tpch.md index 14720a389b69..d9bd01120f39 100644 --- a/benchmark/benchmark-tpch.md +++ b/benchmark/benchmark-tpch.md @@ -1,6 +1,5 @@ --- title: TiDB TPC-H 50G 性能测试报告 -aliases: ['/docs-cn/dev/benchmark/benchmark-tpch/','/docs-cn/dev/benchmark/tpch/'] summary: TiDB TPC-H 50G 性能测试报告显示，TiDB 2.0 在大部分查询中表现优于 TiDB 1.0。然而，部分查询在 TiDB 1.0 中未能完成或因内存占用过多而被终止。测试环境包括不同操作系统和硬件信息，测试结果以图表形式展示。 --- diff --git a/benchmark/online-workloads-and-add-index-operations.md b/benchmark/online-workloads-and-add-index-operations.md index 15379f39366a..1a894ee40b48 100644 --- a/benchmark/online-workloads-and-add-index-operations.md +++ b/benchmark/online-workloads-and-add-index-operations.md @@ -1,6 +1,5 @@ --- title: 线上负载与 `ADD INDEX` 相互影响测试 -aliases: ['/docs-cn/dev/benchmark/online-workloads-and-add-index-operations/','/docs-cn/dev/benchmark/add-index-with-load/'] summary: 线上负载与 ADD INDEX 相互影响测试结果显示，当目标列频繁更新时，会造成写冲突和长时间完成。目标列仅涉及查询负载或与线上负载不相关时，可以直接使用默认配置。 --- diff --git a/benchmark/v3.0-performance-benchmarking-with-sysbench.md b/benchmark/v3.0-performance-benchmarking-with-sysbench.md index 048fc8bf9add..de7ed220039f 100644 --- a/benchmark/v3.0-performance-benchmarking-with-sysbench.md +++ b/benchmark/v3.0-performance-benchmarking-with-sysbench.md @@ -1,6 +1,5 @@ --- title: TiDB Sysbench 性能对比测试报告 - v3.0 对比 v2.1 -aliases: ['/docs-cn/dev/benchmark/v3.0-performance-benchmarking-with-sysbench/','/docs-cn/dev/benchmark/sysbench-v4/'] summary: TiDB 3.0 版本和 2.1 版本在 OLTP 场景下进行了性能对比测试。测试环境为 AWS EC2，使用 Sysbench 向集群导入 16 张表，每张数据 1000 万。测试结果显示，v3.0 在 Point Select、Update Non-Index、Update Index 和 Read Write 测试中的性能均优于 v2.1。 --- diff --git a/benchmark/v3.0-performance-benchmarking-with-tpcc.md b/benchmark/v3.0-performance-benchmarking-with-tpcc.md index 63b3ac78c966..b01fa9692b8a 100644 --- a/benchmark/v3.0-performance-benchmarking-with-tpcc.md +++ b/benchmark/v3.0-performance-benchmarking-with-tpcc.md @@ -1,6 +1,5 @@ --- title: TiDB TPC-C 性能对比测试报告 - v3.0 对比 v2.1 -aliases: ['/docs-cn/dev/benchmark/v3.0-performance-benchmarking-with-tpcc/','/docs-cn/dev/benchmark/tpcc/'] summary: TiDB 3.0 版本在 TPC-C 性能上提升了 450%，性能表现明显优于 2.1 版本。 --- diff --git a/benchmark/v4.0-performance-benchmarking-with-tpcc.md b/benchmark/v4.0-performance-benchmarking-with-tpcc.md index 0ccfef075ec1..976d8328f5a4 100644 --- a/benchmark/v4.0-performance-benchmarking-with-tpcc.md +++ b/benchmark/v4.0-performance-benchmarking-with-tpcc.md @@ -1,6 +1,5 @@ --- title: TiDB TPC-C 性能对比测试报告 - v4.0 对比 v3.0 -aliases: ['/docs-cn/dev/benchmark/v4.0-performance-benchmarking-with-tpcc/'] summary: TiDB v4.0 在 TPC-C 性能上提升了 50%，比 v3.0 高出一半。 --- diff --git a/benchmark/v4.0-performance-benchmarking-with-tpch.md b/benchmark/v4.0-performance-benchmarking-with-tpch.md index c4f46626e29e..a2fe3fdc0680 100644 --- a/benchmark/v4.0-performance-benchmarking-with-tpch.md +++ b/benchmark/v4.0-performance-benchmarking-with-tpch.md @@ -1,6 +1,5 @@ --- title: TiDB TPC-H 性能对比测试报告 - v4.0 对比 v3.0 -aliases: ['/docs-cn/dev/benchmark/v4.0-performance-benchmarking-with-tpch/'] summary: TiDB v4.0 和 v3.0 在 OLAP 场景下的性能对比测试报告显示，v4.0 通过智能选择混合读取 TiKV、TiFlash 的数据，性能明显优于 v3.0 仅从 TiKV 读取数据。在完整的 HTAP 形态下，v4.0 的性能得到了显著提升。 --- diff --git a/benchmark/v5.0-performance-benchmarking-with-tpcc.md b/benchmark/v5.0-performance-benchmarking-with-tpcc.md deleted file mode 100644 index aef70a124bd0..000000000000 --- a/benchmark/v5.0-performance-benchmarking-with-tpcc.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -title: TiDB TPC-C 性能对比测试报告 - v5.0 对比 v4.0 -summary: TiDB v5.0 在 TPC-C 性能上提升了 36%，比 v4.0 更优。 ---- - -# TiDB TPC-C 性能对比测试报告 - v5.0 对比 v4.0 - -## 测试目的 - -测试对比 TiDB v5.0 和 v4.0 OLTP 场景下的性能。 - -## 测试环境 (AWS EC2) - -### 硬件配置 - -| 服务类型 | EC2 类型 | 实例数 | -|:----------|:----------|:----------| -| PD | m5.xlarge | 3 | -| TiKV | i3.4xlarge| 3 | -| TiDB | c5.4xlarge| 3 | -| TPC-C | c5.9xlarge| 1 | - -### 软件版本 - -| 服务类型 | 软件版本 | -|:----------|:-----------| -| PD | 4.0、5.0 | -| TiDB | 4.0、5.0 | -| TiKV | 4.0、5.0 | -| BenchmarkSQL | 无 | - -### 配置参数 - -#### TiDB v4.0 参数配置 - -{{< copyable "" >}} - -```yaml -log.level: "error" -performance.max-procs: 20 -prepared-plan-cache.enabled: true -tikv-client.max-batch-wait-time: 2000000 -``` - -#### TiKV v4.0 参数配置 - -{{< 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 参数配置 - -{{< copyable "" >}} - -```yaml -log.level: "error" -performance.max-procs: 20 -prepared-plan-cache.enabled: true -tikv-client.max-batch-wait-time: 2000000 -``` - -#### TiKV v5.0 参数配置 - -{{< 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 全局变量配置 - -{{< copyable "sql" >}} - -```sql -set global tidb_hashagg_final_concurrency=1; -set global tidb_hashagg_partial_concurrency=1; -``` - -#### TiDB v5.0 全局变量配置 - -{{< 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; -``` - -## 测试方案 - -1. 通过 TiUP 部署 TiDB v5.0 和 v4.0。 - -2. 通过 BenchmarkSQL 导入 TPC-C 5000 Warehouse 数据。 - - 1. 编译 BenchmarkSQL： - - {{< copyable "bash" >}} - - ```bash - git clone https://github.com/pingcap/benchmarksql && cd benchmarksql && ant - ``` - - 2. 进入 `run` 目录，根据实际情况编辑 `props.mysql` 文件，调整 `conn`、`warehouses`、`loadWorkers`、`terminals`、`runMins` 配置项。 - - 3. 运行 `runSQL.sh ./props.mysql sql.mysql/tableCreates.sql` 命令。 - - 4. 运行 `runSQL.sh ./props.mysql sql.mysql/indexCreates.sql` 命令。 - - 5. 运行 MySQL client 并对每个表执行 `analyze table` 语句。 - -3. 运行 `runBenchmark.sh ./props.mysql` 命令。 - -4. 从结果中提取 New Order 的 tpmC 的数据。 - -## 测试结果 - -v5.0 比 v4.0 在 TPC-C 性能上**提升了 36%**。 - -![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 deleted file mode 100644 index 8a523f3cf0a3..000000000000 --- a/benchmark/v5.1-performance-benchmarking-with-tpcc.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: TiDB TPC-C 性能对比测试报告 - v5.1.0 对比 v5.0.2 -summary: TiDB v5.1.0 在 TPC-C 性能上提升了 2.8%，测试环境为 AWS EC2，硬件配置包括 PD、TiKV、TiDB 和 TPC-C 实例，软件版本为 v5.0.2 和 v5.1.0，配置参数相同。测试方案包括部署、创建数据库、导入数据和运行压力测试，结果显示性能提升。 ---- - -# TiDB TPC-C 性能对比测试报告 - v5.1.0 对比 v5.0.2 - -## 测试概况 - -本次测试对比了 TiDB v5.1.0 和 v5.0.2 在 OLTP 场景下的 TPC-C 性能表现。结果显示，v5.1.0 相比于 v5.0.2 在 TPC-C 性能上提升了 2.8%。 - -## 测试环境 (AWS EC2) - -### 硬件配置 - -| 服务类型 | EC2 类型 | 实例数 | -|:----------|:----------|:----------| -| PD | m5.xlarge | 3 | -| TiKV | i3.4xlarge| 3 | -| TiDB | c5.4xlarge| 3 | -| TPC-C | c5.9xlarge| 1 | - -### 软件版本 - -| 服务类型 | 软件版本 | -|:----------|:-----------| -| PD | v5.0.2、v5.1.0 | -| TiDB | v5.0.2、v5.1.0 | -| TiKV | v5.0.2、v5.1.0 | -| TiUP | 1.5.1 | - -### 配置参数 - -两个版本使用同样的配置 - -#### TiDB 参数配置 - -{{< copyable "" >}} - -```yaml -log.level: "error" -performance.max-procs: 20 -prepared-plan-cache.enabled: true -tikv-client.max-batch-wait-time: 2000000 -``` - -#### TiKV 参数配置 - -{{< 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 全局变量配置 - -{{< 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; -``` - -## 测试方案 - -1. 通过 TiUP 部署 TiDB v5.1.0 和 v5.0.2。 -2. 创建数据库 tpcc：`create database tpcc;` -3. 通过 tiup bench 导入 TPC-C 5000 Warehouse 数据：`tiup bench tpcc prepare --warehouses 5000 --db tpcc -H 127.0.0.1 -p 4000`。 -4. 运行 `tiup bench tpcc run -U root --db tpcc --host 127.0.0.1 --port 4000 --time 300s --warehouses 5000 --threads {{thread}}` 命令，通过 HAProxy 向 TiDB 加压。 -5. 从结果中提取 New Order 的 tpmC 的数据。 - -## 测试结果 - -v5.1.0 比 v5.0.2 在 TPC-C 性能上**提升了 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 deleted file mode 100644 index f82f66b87c69..000000000000 --- a/benchmark/v5.2-performance-benchmarking-with-tpcc.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: TiDB TPC-C 性能对比测试报告 - v5.2.0 对比 v5.1.1 -summary: TiDB v5.2.0 在 TPC-C 性能上下降了 4.22%，测试环境为 AWS EC2，硬件配置包括 PD、TiKV、TiDB 和 TPC-C 实例，软件版本为 v5.1.1 和 v5.2.0，配置参数相同。测试方案包括部署、创建数据库、导入数据和运行压力测试，结果显示性能下降。 ---- - -# TiDB TPC-C 性能对比测试报告 - v5.2.0 对比 v5.1.1 - -## 测试概况 - -本次测试对比了 TiDB v5.2.0 和 v5.1.1 在 OLTP 场景下的 TPC-C 性能表现。结果显示，v5.2.0 相比于 v5.1.1 在 TPC-C 性能上下降了 4.22%。 - -## 测试环境 (AWS EC2) - -### 硬件配置 - -| 服务类型 | EC2 类型 | 实例数 | -|:----------|:----------|:----------| -| PD | m5.xlarge | 3 | -| TiKV | i3.4xlarge| 3 | -| TiDB | c5.4xlarge| 3 | -| TPC-C | c5.9xlarge| 1 | - -### 软件版本 - -| 服务类型 | 软件版本 | -|:----------|:-----------| -| PD | v5.1.1、v5.2.0 | -| TiDB | v5.1.1、v5.2.0 | -| TiKV | v5.1.1、v5.2.0 | -| TiUP | 1.5.1 | - -### 配置参数 - -两个版本使用同样的配置 - -#### TiDB 参数配置 - -{{< copyable "" >}} - -```yaml -log.level: "error" -performance.max-procs: 20 -prepared-plan-cache.enabled: true -tikv-client.max-batch-wait-time: 2000000 -``` - -#### TiKV 参数配置 - -{{< 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 全局变量配置 - -{{< 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; -``` - -## 测试方案 - -1. 通过 TiUP 部署 TiDB v5.2.0 和 v5.1.1。 -2. 创建数据库 tpcc：`create database tpcc;` -3. 通过 tiup bench 导入 TPC-C 5000 Warehouse 数据：`tiup bench tpcc prepare --warehouses 5000 --db tpcc -H 127.0.0.1 -p 4000`。 -4. 运行 `tiup bench tpcc run -U root --db tpcc --host 127.0.0.1 --port 4000 --time 300s --warehouses 5000 --threads {{thread}}` 命令，通过 HAProxy 向 TiDB 加压。 -5. 从结果中提取 New Order 的 tpmC 的数据。 - -## 测试结果 - -v5.2.0 相比 v5.1.1 在 TPC-C 性能上**下降了 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 deleted file mode 100644 index 2130833a9c44..000000000000 --- a/benchmark/v5.3-performance-benchmarking-with-tpcc.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: TiDB TPC-C 性能对比测试报告 - v5.3.0 对比 v5.2.2 -summary: TiDB v5.3.0 在 TPC-C 性能上略下降了 2.99%，与 v5.2.2 相比。测试结果显示，不同线程下，v5.3.0 的 tpmC 提升率分别为 -1.54%，-2.33%，-2.99%，-5.10%。 ---- - -# TiDB TPC-C 性能对比测试报告 - v5.3.0 对比 v5.2.2 - -## 测试概况 - -本次测试对比了 TiDB v5.3.0 和 v5.2.2 在 OLTP 场景下的 TPC-C 性能表现。结果显示，v5.3.0 相比于 v5.2.2 在 TPC-C 性能上略下降了 2.99%。 - -## 测试环境 (AWS EC2) - -### 硬件配置 - -| 服务类型 | EC2 类型 | 实例数 | -|:----------|:----------|:----------| -| PD | m5.xlarge | 3 | -| TiKV | i3.4xlarge| 3 | -| TiDB | c5.4xlarge| 3 | -| TPC-C | c5.9xlarge| 1 | - -### 软件版本 - -| 服务类型 | 软件版本 | -|:----------|:-----------| -| PD | v5.2.2、v5.3.0 | -| TiDB | v5.2.2、v5.3.0 | -| TiKV | v5.2.2、v5.3.0 | -| TiUP | 1.5.1 | - -### 配置参数 - -两个版本使用同样的配置 - -#### TiDB 参数配置 - -{{< copyable "" >}} - -```yaml -log.level: "error" -performance.max-procs: 20 -prepared-plan-cache.enabled: true -tikv-client.max-batch-wait-time: 2000000 -``` - -#### TiKV 参数配置 - -{{< 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 全局变量配置 - -{{< 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 配置 - haproxy.cfg 文件 - -更多有关 HAProxy 在 TiDB 上的使用，可参阅 [HAProxy 在 TiDB 中的最佳实践](/best-practices/haproxy-best-practices.md)。 - -{{< copyable "" >}} - -```yaml -global # 全局配置。 - chroot /var/lib/haproxy # 更改当前目录并为启动进程设置超级用户权限，从而提高安全性。 - pidfile /var/run/haproxy.pid # 将 HAProxy 进程的 PID 写入 pidfile。 - maxconn 4000 # 每个 HAProxy 进程所接受的最大并发连接数。 - user haproxy # 同 UID 参数。 - group haproxy # 同 GID 参数，建议使用专用用户组。 - nbproc 64 # 在后台运行时创建的进程数。在启动多个进程转发请求时，确保该值足够大，保证 HAProxy 不会成为瓶颈。 - daemon # 让 HAProxy 以守护进程的方式工作于后台，等同于命令行参数“-D”的功能。当然，也可以在命令行中用“-db”参数将其禁用。 - -defaults # 默认配置。 - log global # 日志继承全局配置段的设置。 - retries 2 # 向上游服务器尝试连接的最大次数，超过此值便认为后端服务器不可用。 - timeout connect 2s # HAProxy 与后端服务器连接超时时间。如果在同一个局域网内，可设置成较短的时间。 - timeout client 30000s # 客户端与 HAProxy 连接后，数据传输完毕，即非活动连接的超时时间。 - timeout server 30000s # 服务器端非活动连接的超时时间。 - -listen tidb-cluster # 配置 database 负载均衡。 - bind 0.0.0.0:3390 # 浮动 IP 和 监听端口。 - mode tcp # HAProxy 要使用第 4 层的传输层。 - balance roundrobin # 连接数最少的服务器优先接收连接。`leastconn` 建议用于长会话服务，例如 LDAP、SQL、TSE 等，而不是短会话协议，如 HTTP。该算法是动态的，对于启动慢的服务器，服务器权重会在运行中作调整。 - server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # 检测 4000 端口，检测频率为每 2000 毫秒一次。如果 2 次检测为成功，则认为服务器可用；如果 3 次检测为失败，则认为服务器不可用。 - 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 -``` - -## 测试方案 - -1. 通过 TiUP 部署 TiDB v5.3.0 和 v5.2.2。 -2. 创建数据库 tpcc：`create database tpcc;` -3. 通过 tiup bench 导入 TPC-C 5000 Warehouse 数据：`tiup bench tpcc prepare --warehouses 5000 --db tpcc -H 127.0.0.1 -p 4000`。 -4. 运行 `tiup bench tpcc run -U root --db tpcc --host 127.0.0.1 --port 4000 --time 1800s --warehouses 5000 --threads {{thread}}` 命令，通过 HAProxy 向 TiDB 加压，每个并发数各测试 30 分钟。 -5. 从结果中提取 New Order 的 tpmC 的数据。 - -## 测试结果 - -v5.3.0 相比 v5.2.2 在 TPC-C 性能上**略下降了 2.99%**。 - -| Threads | v5.2.2 tpmC | v5.3.0 tpmC | tpmC 提升 (%) | -|:----------|:----------|:----------|:----------| -|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) diff --git a/benchmark/v5.4-performance-benchmarking-with-tpcc.md b/benchmark/v5.4-performance-benchmarking-with-tpcc.md deleted file mode 100644 index 3831300d64f6..000000000000 --- a/benchmark/v5.4-performance-benchmarking-with-tpcc.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: TiDB TPC-C 性能对比测试报告 - v5.4.0 对比 v5.3.0 -summary: TiDB v5.4.0 在 TPC-C 性能上提升了 3.16%，测试结果显示不同并发下，性能均有提升。 ---- - -# TiDB TPC-C 性能对比测试报告 - v5.4.0 对比 v5.3.0 - -## 测试概况 - -本次测试对比了 TiDB v5.4.0 和 v5.3.0 在 OLTP 场景下的 TPC-C 性能表现。结果显示，v5.4.0 相比于 v5.3.0 在 TPC-C 性能提升了 3.16%。 - -## 测试环境 (AWS EC2) - -### 硬件配置 - -| 服务类型 | EC2 类型 | 实例数 | -|:----------|:----------|:----------| -| PD | m5.xlarge | 3 | -| TiKV | i3.4xlarge| 3 | -| TiDB | c5.4xlarge| 3 | -| TPC-C | c5.9xlarge| 1 | - -### 软件版本 - -| 服务类型 | 软件版本 | -|:----------|:-----------| -| PD | v5.3.0、v5.4.0 | -| TiDB | v5.3.0、v5.4.0 | -| TiKV | v5.3.0、v5.4.0 | -| TiUP | 1.5.1 | - -### 配置参数 - -两个版本使用同样的配置 - -#### TiDB 参数配置 - -{{< copyable "" >}} - -```yaml -log.level: "error" -performance.max-procs: 20 -prepared-plan-cache.enabled: true -tikv-client.max-batch-wait-time: 2000000 -``` - -#### TiKV 参数配置 - -{{< 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 全局变量配置 - -{{< 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 配置 - haproxy.cfg 文件 - -更多有关 HAProxy 在 TiDB 上的使用，可参阅 [HAProxy 在 TiDB 中的最佳实践](/best-practices/haproxy-best-practices.md)。 - -{{< copyable "" >}} - -```yaml -global # 全局配置。 - chroot /var/lib/haproxy # 更改当前目录并为启动进程设置超级用户权限，从而提高安全性。 - pidfile /var/run/haproxy.pid # 将 HAProxy 进程的 PID 写入 pidfile。 - maxconn 4000 # 每个 HAProxy 进程所接受的最大并发连接数。 - user haproxy # 同 UID 参数。 - group haproxy # 同 GID 参数，建议使用专用用户组。 - nbproc 64 # 在后台运行时创建的进程数。在启动多个进程转发请求时，确保该值足够大，保证 HAProxy 不会成为瓶颈。 - daemon # 让 HAProxy 以守护进程的方式工作于后台，等同于命令行参数“-D”的功能。当然，也可以在命令行中用“-db”参数将其禁用。 - -defaults # 默认配置。 - log global # 日志继承全局配置段的设置。 - retries 2 # 向上游服务器尝试连接的最大次数，超过此值便认为后端服务器不可用。 - timeout connect 2s # HAProxy 与后端服务器连接超时时间。如果在同一个局域网内，可设置成较短的时间。 - timeout client 30000s # 客户端与 HAProxy 连接后，数据传输完毕，即非活动连接的超时时间。 - timeout server 30000s # 服务器端非活动连接的超时时间。 - -listen tidb-cluster # 配置 database 负载均衡。 - bind 0.0.0.0:3390 # 浮动 IP 和 监听端口。 - mode tcp # HAProxy 要使用第 4 层的传输层。 - balance roundrobin # 连接数最少的服务器优先接收连接。`leastconn` 建议用于长会话服务，例如 LDAP、SQL、TSE 等，而不是短会话协议，如 HTTP。该算法是动态的，对于启动慢的服务器，服务器权重会在运行中作调整。 - server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # 检测 4000 端口，检测频率为每 2000 毫秒一次。如果 2 次检测为成功，则认为服务器可用；如果 3 次检测为失败，则认为服务器不可用。 - 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 -``` - -## 测试方案 - -1. 通过 TiUP 部署 TiDB v5.4.0 和 v5.3.0。 -2. 创建数据库 tpcc：`create database tpcc;`。 -3. 通过 tiup bench 导入 TPC-C 5000 Warehouse 数据：`tiup bench tpcc prepare --warehouses 5000 --db tpcc -H 127.0.0.1 -P 4000`。 -4. 运行 `tiup bench tpcc run -U root --db tpcc --host 127.0.0.1 --port 4000 --time 1800s --warehouses 5000 --threads {{thread}}` 命令，通过 HAProxy 向 TiDB 加压，每个并发数各测试 30 分钟。 -5. 从结果中提取 New Order 的 tpmC 的数据。 - -## 测试结果 - -v5.4.0 相比 v5.3.0 在 TPC-C 性能上**提升了 3.16%**。 - -| Threads | v5.3.0 tpmC | v5.4.0 tpmC | tpmC 提升 (%) | -|:----------|:----------|:----------|:----------| -|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 deleted file mode 100644 index f3fedd1e231c..000000000000 --- a/benchmark/v5.4-performance-benchmarking-with-tpch.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: TiDB TPC-H 性能对比测试报告 - v5.4 MPP 模式对比 Greenplum 6.15.0 以及 Apache Spark 3.1.1 -summary: TiDB v5.4 MPP 模式在 TPC-H 100 GB 数据下的性能测试结果显示，相对于 Greenplum 6.15.0 和 Apache Spark 3.1.1，有 2-3 倍的性能提升。测试环境包括 TiDB v5.4 MPP、Greenplum 6.15.0 和 Apache Spark 3.1.1 + Parquet。测试结果显示 TiDB v5.4 在各个查询中的处理时间明显低于其他两者，表现更优。 ---- - -# TiDB TPC-H 性能对比测试报告 - v5.4 MPP 模式对比 Greenplum 6.15.0 以及 Apache Spark 3.1.1 - -## 测试概况 - -本次测试对比了 TiDB v5.4 MPP 模式下和主流分析引擎例如 Greenplum 和 Apache Spark 最新版本在 TPC-H 100 GB 数据下的性能表现。结果显示，TiDB v5.4 MPP 模式下相对这些方案有 2-3 倍的性能提升。 - -TiDB v5.0 中引入的 [TiFlash](/tiflash/tiflash-overview.md) 组件的 MPP 模式大大幅增强了 TiDB HTAP 形态。本文的测试对象如下： - -+ TiDB v5.4 MPP 执行模式下的列式存储 -+ Greenplum 6.15.0 -+ Apache Spark 3.1.1 + Parquet - -## 测试环境 - -### 硬件配置 - -| 实例类型 | 实例数 | -|:----------|:----------| -| PD | 1 | -| TiDB | 1 | -| TiKV | 3 | -| TiFlash | 3 | - -+ CPU：Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz，40 核 -+ 内存：189 GB -+ 磁盘：NVMe 3TB * 2 - -### 软件版本 - -| 服务类型 | 软件版本 | -|:----------|:-----------| -| TiDB | 5.4 | -| Greenplum | 6.15.0 | -| Apache Spark | 3.1.1 | - -### 配置参数 - -#### TiDB v5.4 配置 - -v5.4 的 TiDB 集群除以下配置项外均使用默认参数配置。所有 TPC-H 测试表均以 TiFlash 列存进行同步，无额外分区和索引。 - -在 TiFlash 的 `users.toml` 配置文件中进行如下配置： - -```toml -[profiles.default] -max_memory_usage = 10000000000000 -``` - -使用 SQL 语句设置以下会话变量： - -```sql -set @@tidb_isolation_read_engines='tiflash'; -set @@tidb_allow_mpp=1; -set @@tidb_mem_quota_query = 10 << 30; -``` - -#### Greenplum 配置 - -Greenplum 集群使用额外的一台 Master 节点部署（共四台），每台 Segment Server 部署 8 Segments（每个 NVMe SSD 各 4 个），总共 24 Segments。存储格式为 append-only / 列式存储，分区键为主键。 - -{{< copyable "" >}} - -``` -log_statement = all -gp_autostats_mode = none -statement_mem = 2048MB -gp_vmem_protect_limit = 16384 -``` - -#### Apache Spark 配置 - -Apache Spark 测试使用 Apache Parquet 作为存储格式，数据存储在 HDFS 上。HDFS 为三节点，为每个节点指定两块 NVMe SSD 盘作为数据盘。通过 Standalone 方式启动 Spark 集群，使用 NVMe SSD 盘作为 `spark.local.dir` 本地目录以借助快速盘加速 Shuffle Spill 过程，无额外分区和索引。 - -{{< copyable "" >}} - -``` ---driver-memory 20G ---total-executor-cores 120 ---executor-cores 5 ---executor-memory 15G -``` - -## 测试结果 - -> **注意：** -> -> 以下测试结果均为 3 次测试的平均值，单位均为秒。 - -| 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) - -以上性能图中蓝色为 TiDB v5.4，红色为 Greenplum 6.15.0，黄色为 Apache Spark 3.1.1，纵坐标是查询的处理时间。纵坐标数值越低，表示 TPC-H 性能越好。 diff --git a/benchmark/v6.0-performance-benchmarking-with-tpcc.md b/benchmark/v6.0-performance-benchmarking-with-tpcc.md deleted file mode 100644 index 033c382ddc37..000000000000 --- a/benchmark/v6.0-performance-benchmarking-with-tpcc.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: TiDB TPC-C 性能对比测试报告 - v6.0.0 对比 v5.4.0 -summary: TiDB v6.0.0 在 TPC-C 性能上比 v5.4.0 提升了 24.20%，表现更好。测试环境为 AWS EC2，硬件配置包括 PD、TiKV、TiDB 和 TPC-C 实例。软件版本为 v5.4.0 和 v6.0.0，配置参数相同。测试方案包括通过 TiUP 部署 TiDB，创建数据库 tpcc，导入数据，运行压力测试，提取结果。测试结果显示 v6.0.0 在不同并发下的 tpmC 均有提升，最高达 26.97%。 ---- - -# TiDB TPC-C 性能对比测试报告 - v6.0.0 对比 v5.4.0 - -## 测试概况 - -本次测试对比了 TiDB v6.0.0 和 v5.4.0 在 OLTP 场景下的 TPC-C 性能表现。结果显示，v6.0.0 相比于 v5.4.0 在 TPC-C 性能提升了 24.20%。 - -## 测试环境 (AWS EC2) - -### 硬件配置 - -| 服务类型 | EC2 类型 | 实例数 | -|:----------|:----------|:----------| -| PD | m5.xlarge | 3 | -| TiKV | i3.4xlarge| 3 | -| TiDB | c5.4xlarge| 3 | -| TPC-C | c5.9xlarge| 1 | - -### 软件版本 - -| 服务类型 | 软件版本 | -|:----------|:-----------| -| PD | v5.4.0、v6.0.0 | -| TiDB | v5.4.0、v6.0.0 | -| TiKV | v5.4.0、v6.0.0 | -| TiUP | 1.9.3 | -| HAProxy | 2.5.0 | - -### 配置参数 - -两个版本使用同样的配置 - -#### TiDB 参数配置 - -{{< copyable "" >}} - -```yaml -log.level: "error" -prepared-plan-cache.enabled: true -tikv-client.max-batch-wait-time: 2000000 -``` - -#### TiKV 参数配置 - -{{< 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 全局变量配置 - -{{< 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 配置 - haproxy.cfg 文件 - -更多有关 HAProxy 在 TiDB 上的使用，可参阅 [HAProxy 在 TiDB 中的最佳实践](/best-practices/haproxy-best-practices.md)。 - -{{< copyable "" >}} - -```yaml -global # 全局配置。 - pidfile /var/run/haproxy.pid # 将 HAProxy 进程的 PID 写入 pidfile。 - maxconn 4000 # 每个 HAProxy 进程所接受的最大并发连接数。 - user haproxy # 同 UID 参数。 - group haproxy # 同 GID 参数，建议使用专用用户组。 - nbproc 64 # 在后台运行时创建的进程数。在启动多个进程转发请求时，确保该值足够大，保证 HAProxy 不会成为瓶颈。 - daemon # 让 HAProxy 以守护进程的方式工作于后台，等同于命令行参数“-D”的功能。当然，也可以在命令行中用“-db”参数将其禁用。 - -defaults # 默认配置。 - log global # 日志继承全局配置段的设置。 - retries 2 # 向上游服务器尝试连接的最大次数，超过此值便认为后端服务器不可用。 - timeout connect 2s # HAProxy 与后端服务器连接超时时间。如果在同一个局域网内，可设置成较短的时间。 - timeout client 30000s # 客户端与 HAProxy 连接后，数据传输完毕，即非活动连接的超时时间。 - timeout server 30000s # 服务器端非活动连接的超时时间。 - -listen tidb-cluster # 配置 database 负载均衡。 - bind 0.0.0.0:3390 # 浮动 IP 和 监听端口。 - mode tcp # HAProxy 要使用第 4 层的传输层。 - balance leastconn # 连接数最少的服务器优先接收连接。`leastconn` 建议用于长会话服务，例如 LDAP、SQL、TSE 等，而不是短会话协议，如 HTTP。该算法是动态的，对于启动慢的服务器，服务器权重会在运行中作调整。 - server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # 检测 4000 端口，检测频率为每 2000 毫秒一次。如果 2 次检测为成功，则认为服务器可用；如果 3 次检测为失败，则认为服务器不可用。 - 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 -``` - -## 测试方案 - -1. 通过 TiUP 部署 TiDB v6.0.0 和 v5.4.0。 -2. 创建数据库 tpcc：`create database tpcc;`。 -3. 通过 tiup bench 导入 TPC-C 5000 Warehouse 数据：`tiup bench tpcc prepare --warehouses 5000 --db tpcc -H 127.0.0.1 -p 4000`。 -4. 运行 `tiup bench tpcc run -U root --db tpcc --host 127.0.0.1 --port 4000 --time 1800s --warehouses 5000 --threads {{thread}}` 命令，通过 HAProxy 向 TiDB 加压，每个并发数各测试 30 分钟。 -5. 从结果中提取 New Order 的 tpmC 的数据。 - -## 测试结果 - -v6.0.0 相比 v5.4.0 在 TPC-C 性能上有大幅提升，**平均提升了 24.20%**。 - -| Threads | v5.4.0 tpmC | v6.0.0 tpmC | tpmC 提升 (%) | -|:----------|:----------|:----------|:----------| -|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 deleted file mode 100644 index 0d20f8c38b76..000000000000 --- a/benchmark/v6.0-performance-benchmarking-with-tpch.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: TiFlash 与 Greenplum/Spark 性能比较 -summary: TiFlash 与 Greenplum/Spark 性能进行了比较。请参考 TiDB v5.4 TPC-H 性能对比测试报告。 ---- - -# TiFlash 与 Greenplum/Spark 性能比较 - -请参考 [TiDB v5.4 TPC-H 性能对比测试报告](https://docs.pingcap.com/zh/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 deleted file mode 100644 index 045caf09cc99..000000000000 --- a/benchmark/v6.1-performance-benchmarking-with-tpcc.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: TiDB TPC-C 性能对比测试报告 - v6.1.0 对比 v6.0.0 -summary: TiDB v6.1.0 在 TPC-C 性能上平均提升了 2.85%，分别为：50 线程提升 2.31%，100 线程提升 2.71%，200 线程提升 3.86%，400 线程提升 2.52%。 ---- - -# TiDB TPC-C 性能对比测试报告 - v6.1.0 对比 v6.0.0 - -## 测试概况 - -本次测试对比了 TiDB v6.1.0 和 v6.0.0 在 OLTP 场景下的 TPC-C 性能表现。结果显示，v6.1.0 相比于 v6.0.0 在 TPC-C 性能提升了 2.85%。 - -## 测试环境 (AWS EC2) - -### 硬件配置 - -| 服务类型 | EC2 类型 | 实例数 | -|:----------|:----------|:----------| -| PD | m5.xlarge | 3 | -| TiKV | i3.4xlarge| 3 | -| TiDB | c5.4xlarge| 3 | -| TPC-C | c5.9xlarge| 1 | - -### 软件版本 - -| 服务类型 | 软件版本 | -|:----------|:-----------| -| PD | v6.0.0、v6.1.0 | -| TiDB | v6.0.0、v6.1.0 | -| TiKV | v6.0.0、v6.1.0 | -| TiUP | 1.9.3 | -| HAProxy | 2.5.0 | - -### 配置参数 - -两个版本使用同样的配置。 - -#### TiDB 参数配置 - -{{< copyable "" >}} - -```yaml -log.level: "error" -prepared-plan-cache.enabled: true -tikv-client.max-batch-wait-time: 2000000 -``` - -#### TiKV 参数配置 - -{{< 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 全局变量配置 - -{{< 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 配置 - haproxy.cfg 文件 - -更多有关 HAProxy 在 TiDB 上的使用，可参阅 [HAProxy 在 TiDB 中的最佳实践](/best-practices/haproxy-best-practices.md)。 - -{{< copyable "" >}} - -```yaml -global # 全局配置。 - pidfile /var/run/haproxy.pid # 将 HAProxy 进程的 PID 写入 pidfile。 - maxconn 4000 # 每个 HAProxy 进程所接受的最大并发连接数。 - user haproxy # 同 UID 参数。 - group haproxy # 同 GID 参数，建议使用专用用户组。 - nbproc 64 # 在后台运行时创建的进程数。在启动多个进程转发请求时，确保该值足够大，保证 HAProxy 不会成为瓶颈。 - daemon # 让 HAProxy 以守护进程的方式工作于后台，等同于命令行参数“-D”的功能。当然，也可以在命令行中用“-db”参数将其禁用。 - -defaults # 默认配置。 - log global # 日志继承全局配置段的设置。 - retries 2 # 向上游服务器尝试连接的最大次数，超过此值便认为后端服务器不可用。 - timeout connect 2s # HAProxy 与后端服务器连接超时时间。如果在同一个局域网内，可设置成较短的时间。 - timeout client 30000s # 客户端与 HAProxy 连接后，数据传输完毕，即非活动连接的超时时间。 - timeout server 30000s # 服务器端非活动连接的超时时间。 - -listen tidb-cluster # 配置 database 负载均衡。 - bind 0.0.0.0:3390 # 浮动 IP 和 监听端口。 - mode tcp # HAProxy 要使用第 4 层的传输层。 - balance leastconn # 连接数最少的服务器优先接收连接。`leastconn` 建议用于长会话服务，例如 LDAP、SQL、TSE 等，而不是短会话协议，如 HTTP。该算法是动态的，对于启动慢的服务器，服务器权重会在运行中作调整。 - server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # 检测 4000 端口，检测频率为每 2000 毫秒一次。如果 2 次检测为成功，则认为服务器可用；如果 3 次检测为失败，则认为服务器不可用。 - 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 -``` - -## 测试方案 - -1. 通过 TiUP 部署 TiDB v6.1.0 和 v6.0.0。 -2. 创建数据库 tpcc：`create database tpcc;`。 -3. 通过 tiup bench 导入 TPC-C 5000 Warehouse 数据：`tiup bench tpcc prepare --warehouses 5000 --db tpcc -H 127.0.0.1 -p 4000`。 -4. 运行 `tiup bench tpcc run -U root --db tpcc --host 127.0.0.1 --port 4000 --time 1800s --warehouses 5000 --threads {{thread}}` 命令，通过 HAProxy 向 TiDB 加压，每个并发数各测试 30 分钟。 -5. 从结果中提取 New Order 的 tpmC 的数据。 - -## 测试结果 - -v6.1.0 相比 v6.0.0 在 TPC-C 性能上**平均提升了 2.85%**。 - -| Threads | v6.0.0 tpmC | v6.1.0 tpmC | tpmC 提升 (%) | -|:----------|:----------|:----------|:----------| -|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 deleted file mode 100644 index 6533d99ced5c..000000000000 --- a/benchmark/v6.1-performance-benchmarking-with-tpch.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: TiFlash 与 Greenplum/Spark 性能比较 -summary: TiFlash 与 Greenplum/Spark 性能比较。请参考 TiDB v5.4 TPC-H 性能对比测试报告。 ---- - -# TiFlash 与 Greenplum/Spark 性能比较 - -请参考 [TiDB v5.4 TPC-H 性能对比测试报告](https://docs.pingcap.com/zh/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 deleted file mode 100644 index 0b83fbe7e552..000000000000 --- a/benchmark/v6.2-performance-benchmarking-with-tpcc.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: TiDB TPC-C 性能对比测试报告 - v6.2.0 对比 v6.1.0 -summary: TiDB v6.2.0 在 TPC-C 性能测试中相比 v6.1.0 下降了 2.00%，平均性能下降了 2.00%。在不同并发数下，v6.2.0 的性能都有所下降，最高下降达到 3.60%。 ---- - -# TiDB TPC-C 性能对比测试报告 - v6.2.0 对比 v6.1.0 - -## 测试概况 - -本次测试对比了 TiDB v6.2.0 和 v6.1.0 在 OLTP 场景下的 TPC-C 性能表现。结果显示，v6.2.0 相比于 v6.1.0 在 TPC-C 性能下降了 2.00%。 - -## 测试环境 (AWS EC2) - -### 硬件配置 - -| 服务类型 | EC2 类型 | 实例数 | -| :------- | :--------- | :----- | -| PD | m5.xlarge | 3 | -| TiKV | i3.4xlarge | 3 | -| TiDB | c5.4xlarge | 3 | -| TPC-C | c5.9xlarge | 1 | - -### 软件版本 - -| 服务类型 | 软件版本 | -| :------- | :------------- | -| PD | v6.1.0、v6.2.0 | -| TiDB | v6.1.0、v6.2.0 | -| TiKV | v6.1.0、v6.2.0 | -| TiUP | 1.9.3 | -| HAProxy | 2.5.0 | - -### 配置参数 - -两个版本使用同样的配置。 - -#### TiDB 参数配置 - -{{< copyable "" >}} - -```yaml -log.level: "error" -prepared-plan-cache.enabled: true -tikv-client.max-batch-wait-time: 2000000 -``` - -#### TiKV 参数配置 - -{{< 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 全局变量配置 - -{{< 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 配置 - haproxy.cfg 文件 - -更多有关 HAProxy 在 TiDB 上的使用，可参阅 [HAProxy 在 TiDB 中的最佳实践](/best-practices/haproxy-best-practices.md)。 - -{{< copyable "" >}} - -```yaml -global # 全局配置。 - pidfile /var/run/haproxy.pid # 将 HAProxy 进程的 PID 写入 pidfile。 - maxconn 4000 # 每个 HAProxy 进程所接受的最大并发连接数。 - user haproxy # 同 UID 参数。 - group haproxy # 同 GID 参数，建议使用专用用户组。 - nbproc 64 # 在后台运行时创建的进程数。在启动多个进程转发请求时，确保该值足够大，保证 HAProxy 不会成为瓶颈。 - daemon # 让 HAProxy 以守护进程的方式工作于后台，等同于命令行参数“-D”的功能。当然，也可以在命令行中用“-db”参数将其禁用。 - -defaults # 默认配置。 - log global # 日志继承全局配置段的设置。 - retries 2 # 向上游服务器尝试连接的最大次数，超过此值便认为后端服务器不可用。 - timeout connect 2s # HAProxy 与后端服务器连接超时时间。如果在同一个局域网内，可设置成较短的时间。 - timeout client 30000s # 客户端与 HAProxy 连接后，数据传输完毕，即非活动连接的超时时间。 - timeout server 30000s # 服务器端非活动连接的超时时间。 - -listen tidb-cluster # 配置 database 负载均衡。 - bind 0.0.0.0:3390 # 浮动 IP 和 监听端口。 - mode tcp # HAProxy 要使用第 4 层的传输层。 - balance leastconn # 连接数最少的服务器优先接收连接。`leastconn` 建议用于长会话服务，例如 LDAP、SQL、TSE 等，而不是短会话协议，如 HTTP。该算法是动态的，对于启动慢的服务器，服务器权重会在运行中作调整。 - server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # 检测 4000 端口，检测频率为每 2000 毫秒一次。如果 2 次检测为成功，则认为服务器可用；如果 3 次检测为失败，则认为服务器不可用。 - 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 -``` - -## 测试方案 - -1. 通过 TiUP 部署 TiDB v6.2.0 和 v6.1.0。 -2. 创建数据库 tpcc：`create database tpcc;`。 -3. 通过 tiup bench 导入 TPC-C 5000 Warehouse 数据：`tiup bench tpcc prepare --warehouses 5000 --db tpcc -H 127.0.0.1 -P 4000`。 -4. 运行 `tiup bench tpcc run -U root --db tpcc --host 127.0.0.1 --port 4000 --time 1800s --warehouses 5000 --threads {{thread}}` 命令，通过 HAProxy 向 TiDB 加压，每个并发数各测试 30 分钟。 -5. 从结果中提取 New Order 的 tpmC 的数据。 - -## 测试结果 - -v6.2.0 相比 v6.1.0 在 TPC-C 性能上**平均下降了 2.00%**。 - -| Threads | v6.1.0 tpmC | v6.2.0 tpmC | tpmC 提升 (%) | -| :------ | :---------- | :---------- | :------------ | -| 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 deleted file mode 100644 index 50487b04284f..000000000000 --- a/benchmark/v6.2-performance-benchmarking-with-tpch.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: TiFlash 与 Greenplum/Spark 性能比较 -summary: TiFlash 与 Greenplum/Spark 性能进行了比较。请参考 TiDB v5.4 TPC-H 性能对比测试报告。 ---- - -# TiFlash 与 Greenplum/Spark 性能比较 - -请参考 [TiDB v5.4 TPC-H 性能对比测试报告](https://docs.pingcap.com/zh/tidb/stable/v5.4-performance-benchmarking-with-tpch)。 diff --git a/best-practices-for-security-configuration.md b/best-practices-for-security-configuration.md index daca3966fd3e..8a059df2d0eb 100644 --- a/best-practices-for-security-configuration.md +++ b/best-practices-for-security-configuration.md @@ -20,6 +20,8 @@ TiDB 的安全性对于保护数据完整性和机密性至关重要。本文提 - 使用 TiUP 部署时，参考[使用 TiUP 部署 TiDB 集群](/production-deployment-using-tiup.md#第-7-步启动集群)为 root 用户生成随机密码。 - 使用 TiDB Operator 部署时，参考[初始化账号和密码设置](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/initialize-a-cluster#初始化账号和密码设置)为 root 用户设置密码。 +你也可以使用 [`--initialize-secure`](/command-line-flags-for-tidb-configuration.md#--initialize-secure) 选项来限制初始 root 用户的网络访问。 + ## 启用密码复杂性检查 默认情况下，TiDB 未启用密码复杂性策略，这可能导致使用弱密码或空密码，增加安全风险。 @@ -64,7 +66,7 @@ TiDB Dashboard 的账号体系与 TiDB SQL 用户一致，并基于 TiDB SQL 用 TiDB 的默认安装中存在许多用于组件间通信的特权接口。这些端口通常不需要向用户端开放，因为它们主要用于内部通信。当这些端口直接暴露在公共网络上时，会增加潜在的攻击面，违反了安全最小化原则，增加了安全风险的产生。下表列出了 TiDB 集群默认监听端口的详细情况： -| 组件 | 默认监听端口 | 协议 | +| 组件 | 默认监听端口 | 协议 | |-------------------|--------------|------------| | TiDB | 4000 | MySQL | | TiDB | 10080 | HTTP | @@ -76,14 +78,13 @@ TiDB 的默认安装中存在许多用于组件间通信的特权接口。这些 | TiFlash | 20170 | Protocol | | TiFlash | 20292 | HTTP | | TiFlash | 8234 | HTTP | -| TiFlow | 8261/8291 | HTTP | -| TiFlow | 8262 | HTTP | -| TiFlow | 8300 | HTTP | +| DM master | 8261 | HTTP | +| DM master | 8291 | HTTP | +| DM worker | 8262 | HTTP | +| TiCDC | 8300 | HTTP | | TiDB Lightning | 8289 | HTTP | | TiDB Operator | 6060 | HTTP | | TiDB Dashboard | 2379 | HTTP | -| TiDB Binlog | 8250 | HTTP | -| TiDB Binlog | 8249 | HTTP | | TMS | 8082 | HTTP | | TEM | 8080 | HTTP | | TEM | 8000 | HTTP | @@ -97,18 +98,18 @@ TiDB 的默认安装中存在许多用于组件间通信的特权接口。这些 | AlertManager | 9093 | HTTP | | AlertManager | 9094 | Protocol | | Node Exporter | 9100 | HTTP | -| Blackbox Exporter | 9115 | HTTP | +| Blackbox Exporter | 9115 | HTTP | | NG Monitoring | 12020 | HTTP | -建议向普通用户只公开数据库的 `4000` 端口和 Grafana 面板的 `9000` 端口，并通过网络安全策略组或防火墙限制其他端口。以下是使用 `iptables` 限制端口访问的示例： +建议向普通用户只公开数据库的 `4000` 端口和 Grafana 面板的 `3000` 端口，并通过网络安全策略组或防火墙限制其他端口。以下是使用 `iptables` 限制端口访问的示例： ```shell # 允许来自各组件白名单 IP 地址范围的内部端口通讯 sudo iptables -A INPUT -s 内网 IP 地址范围 -j ACCEPT -# 仅对外部用户开放 4000 和 9000 端口 +# 仅对外部用户开放 4000 和 3000 端口 sudo iptables -A INPUT -p tcp --dport 4000 -j ACCEPT -sudo iptables -A INPUT -p tcp --dport 9000 -j ACCEPT +sudo iptables -A INPUT -p tcp --dport 3000 -j ACCEPT # 默认拒绝所有其他流量 sudo iptables -P INPUT DROP diff --git a/best-practices/_index.md b/best-practices/_index.md new file mode 100644 index 000000000000..b4f1550974bb --- /dev/null +++ b/best-practices/_index.md @@ -0,0 +1,58 @@ +--- +title: TiDB 最佳实践 +summary: 了解部署、配置和使用 TiDB 的最佳实践。 +--- + +# TiDB 最佳实践 + +通过遵循 TiDB 在部署、配置和使用方面的最佳实践，你可以有效优化 TiDB 集群的性能、可靠性和可扩展性。本文档对 TiDB 的各类最佳实践进行了总体介绍，帮助你更高效地使用 TiDB。 + +## 使用概览 + +从使用 TiDB 的基本原则和通用建议入手，快速了解如何高效使用 TiDB。 + +| 最佳实践主题 | 说明 | +| ------------- | ---- | +| [TiDB 最佳实践](/best-practices/tidb-best-practices.md) | TiDB 使用最佳实践的整体概览。 | + +## 库表设计 + +了解 TiDB 库表设计最佳实践，包括 DDL 管理、主键选择，以及索引的设计与维护，以兼顾系统的性能、可扩展性和可维护性。 + +| 最佳实践主题 | 说明 | +| ------------- | ---- | +| [DDL 最佳实践](/best-practices/ddl-introduction.md) | 在 TiDB 中管理数据定义语言 (DDL) 操作的最佳实践。 | +| [将 UUID 用作主键的最佳实践](/best-practices/uuid.md) | 使用 UUID（通用唯一标识符）作为主键时，高效存储和索引 UUID 的最佳实践。 | +| [多列索引优化最佳实践](/best-practices/multi-column-index-best-practices.md) | 通过合理设计和使用多列索引来提升 TiDB 查询性能的最佳实践。 | +| [管理索引和识别未使用索引的最佳实践](/best-practices/index-management-best-practices.md) | 管理和优化索引、识别并清理未使用索引，以提升 TiDB 性能的最佳实践。 | + +## 集群部署 + +探索适用于不同场景的推荐部署模式，例如在公有云上部署和多数据中心部署，以确保高可用性和资源使用效率。 + +| 最佳实践主题 | 说明 | +| ------------- | ---- | +| [在公有云上部署 TiDB 的最佳实践](/best-practices/best-practices-on-public-cloud.md) | 在公有云环境中部署 TiDB 的最佳实践，以兼顾性能、成本、可靠性和可扩展性。 | +| [三节点混合部署的最佳实践](/best-practices/three-nodes-hybrid-deployment.md) | 在保证系统稳定性的前提下，实现高性价比、三节点混合部署的最佳实践。 | +| [在三数据中心下就近读取数据的最佳实践](/best-practices/three-dc-local-read.md) | 通过使用 Stale Read 减少跨数据中心访问延迟的最佳实践。 | + +## 运维管理 + +掌握 TiDB 在生产环境中的运维最佳实践，包括流量路由、负载均衡和监控，以确保系统稳定性和可观测性。 + +| 最佳实践主题 | 说明 | +| ------------- | ---- | +| [HAProxy 最佳实践](/best-practices/haproxy-best-practices.md) | 配置 HAProxy 将应用流量分发到多个 TiDB 节点的最佳实践。 | +| [只读存储节点最佳实践](/best-practices/readonly-nodes.md) | 使用只读节点将分析型或重读负载与 OLTP 流量隔离的最佳实践。 | +| [Grafana 监控最佳实践](/best-practices/grafana-monitor-best-practices.md) | 通过关键指标和面板配置实现故障诊断的最佳实践。 | + +## 性能调优 + +深入了解如何通过对 TiKV 和 PD 等 TiDB 核心组件进行调优，以及利用只读存储节点等特性，提升不同业务负载下的系统性能。 + +| 最佳实践主题 | 说明 | +| ------------- | ---- | +| [SaaS 多租户场景下处理百万张表的最佳实践](/best-practices/saas-best-practices.md) | TiDB 在 SaaS 多租户环境的最佳实践，尤其适用于单集群表数量超过百万级别的场景。 | +| [高并发写入场景最佳实践](/best-practices/high-concurrency-best-practices.md) | 在高并发写入场景下避免写入热点、优化 TiDB 性能的最佳实践。 | +| [海量 Region 集群调优最佳实践](/best-practices/massive-regions-best-practices.md) | 在管理百万级 Region 时，优化 TiKV 性能并降低心跳开销的最佳实践。 | +| [PD 调度策略最佳实践](/best-practices/pd-scheduling-best-practices.md) | 通过调整 PD 调度策略实现负载均衡并加快故障恢复的最佳实践。 | diff --git a/best-practices-on-public-cloud.md b/best-practices/best-practices-on-public-cloud.md similarity index 96% rename from best-practices-on-public-cloud.md rename to best-practices/best-practices-on-public-cloud.md index 619ffc0e0e7f..c67b5408284f 100644 --- a/best-practices-on-public-cloud.md +++ b/best-practices/best-practices-on-public-cloud.md @@ -1,6 +1,7 @@ --- title: 在公有云上部署 TiDB 的最佳实践 summary: 了解在公有云上部署 TiDB 的最佳实践。 +aliases: ['/zh/tidb/stable/best-practices-on-public-cloud/','/zh/tidb/dev/best-practices-on-public-cloud/'] --- # 在公有云上部署 TiDB 的最佳实践 @@ -13,7 +14,7 @@ summary: 了解在公有云上部署 TiDB 的最佳实践。 [RocksDB](https://rocksdb.org/) 是 TiKV 的存储引擎，负责存储用户数据。出于成本考虑，云上提供的 EBS IO 吞吐量通常比较有限，因此 RocksDB 可能会表现出较高的写放大，导致磁盘吞吐量成为负载的瓶颈。随着时间的推移，待 compaction 的字节总量会不断增加从而触发流量控制，这意味着此时 TiKV 缺乏足够的磁盘带宽来处理前台写入流量。 -要缓解由磁盘吞吐量受限引起的瓶颈，你可以通过[启用 Titan](#启用-titan) 来改善性能。如果数据的平均行大小低于 512 字节，Titan 并不适用，此时你可以通过[提高所有压缩级别](#提高所有压缩级别) 来改善性能。 +要缓解由磁盘吞吐量受限引起的瓶颈，你可以通过[启用 Titan](#启用-titan) 来改善性能。如果数据的平均行大小低于 512 字节，Titan 并不适用，此时你可以通过[提高所有压缩级别](#提高所有压缩级别)来改善性能。 ### 启用 Titan @@ -136,14 +137,6 @@ tikv: 要减少跨可用区的读取流量，你可以启用 [Follower Read 功能](/follower-read.md)，该功能允许 TiDB 优先选择在同一可用区内的副本进行读取。要启用该功能，请将 [`tidb_replica_read`](/system-variables.md#tidb_replica_read-从-v40-版本开始引入) 变量设置为 `closest-replicas` 或 `closest-adaptive`。 -要减少 TiKV 实例中跨可用区的写入流量，你可以启用 gRPC 压缩功能，该功能在网络传输数据之前会对其进行压缩。以下配置示例展示了如何为 TiKV 启用 gzip gRPC 压缩： - -``` -server_configs: - tikv: - server.grpc-compression-type: gzip -``` - 要减少 TiFlash MPP 任务中数据交换（data shuffle 过程）所带来的网络流量，建议在同一可用区内部署多个 TiFlash 实例。从 v6.6.0 开始，[Exchange 数据压缩](/explain-mpp.md#mpp-version-和-exchange-数据压缩)功能默认启用，以减少 MPP 数据交换导致的网络流量。 ## 缓解 Google Cloud 上的实时迁移维护事件带来的性能影响 @@ -156,7 +149,7 @@ Google Cloud 的[实时迁移功能](https://cloud.google.com/compute/docs/insta - TiKV：在维护期间驱逐受影响的 TiKV 存储上的 Leader。 - PD：如果当前 PD 实例是 PD Leader，则会重新分配 Leader。 -需要注意的是，此监控脚本是专门为 [TiDB Operator](https://docs.pingcap.com/tidb-in-kubernetes/dev/tidb-operator-overview) 部署的 TiDB 集群设计的，TiDB Operator 为 Kubernetes 环境中的 TiDB 提供了增强的管理功能。 +需要注意的是，此监控脚本是专门为 [TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/v1.6/tidb-operator-overview) 部署的 TiDB 集群设计的，TiDB Operator 为 Kubernetes 环境中的 TiDB 提供了增强的管理功能。 通过使用该监控脚本，并在维护事件期间采取必要的措施，TiDB 集群可以更好地应对 Google Cloud 上的实时迁移事件，确保对查询处理和响应时间的影响最小以及系统的平稳运行。 diff --git a/ddl-introduction.md b/best-practices/ddl-introduction.md similarity index 93% rename from ddl-introduction.md rename to best-practices/ddl-introduction.md index 32d810258406..d35bf5639b0f 100644 --- a/ddl-introduction.md +++ b/best-practices/ddl-introduction.md @@ -1,6 +1,7 @@ --- title: DDL 语句的执行原理及最佳实践 summary: 介绍 TiDB 中 DDL 语句的实现原理、在线变更过程、最佳实践等内容。 +aliases: ['/zh/tidb/stable/ddl-introduction/','/zh/tidb/dev/ddl-introduction/','/zh/tidbcloud/ddl-introduction/'] --- # DDL 语句的执行原理及最佳实践 @@ -13,11 +14,9 @@ TiDB 采用在线异步变更的方式执行 DDL 语句，从而实现 DDL 语 ### DDL 语句类型简介 -按照执行期间是否阻塞用户业务，DDL 语句可以划分为： +TiDB 支持在线 DDL (Online DDL)，即在执行 DDL 语句时，数据库通过特定的机制确保 DDL 操作不会阻塞用户业务。你可以在 DDL 执行期间提交数据修改，数据库会保证数据的一致性和正确性。 -- **离线 DDL 语句**：即数据库接收到用户的 DDL 语句后，会先对要修改的数据库对象进行加锁，再执行元数据变更，在 DDL 执行过程中将阻塞用户业务对数据的修改。 - -- **在线 DDL 语句**：即数据库在执行 DDL 语句时，通过一定的方法，使得 DDL 执行不阻塞用户业务，且能够保证用户业务可在 DDL 执行期间提交修改，在执行过程中保证对应对象的数据正确性与一致性。 +相比之下，离线 DDL (Offline DDL) 在执行期间会对数据库对象加锁，阻塞用户对数据的修改操作，直到 DDL 操作完成。TiDB 不支持离线 DDL。 按照是否需要操作 DDL 目标对象所包括的数据来划分，DDL 语句可以划分为： @@ -88,7 +87,7 @@ absent -> delete only -> write only -> write reorg -> public + 涉及同一张表的 DDL 相互阻塞。 + `DROP DATABASE` 和数据库内所有对象的 DDL 互相阻塞。 + 涉及不同表的加索引和列类型变更可以并发执行。 -+ 逻辑 DDL 需要等待之前正在执行的逻辑 DDL 执行完才能执行。 ++ 从 v8.2.0 版本开始，支持并行执行不同表的[逻辑 DDL 语句](/best-practices/ddl-introduction.md#ddl-语句类型简介)。 + 其他情况下 DDL 可以根据 Concurrent DDL 并行度可用情况确定是否可以执行。 具体来说，TiDB 在 v6.2.0 中对 DDL 执行框架进行了如下升级： @@ -186,6 +185,11 @@ absent -> delete only -> write only -> write reorg -> public 你只能对暂停状态的 DDL 任务进行恢复操作，否则会在 `RESULT` 列看到 `Job 3 can't be resumed`。 +## DDL 相关的表 + +- [`information_schema.DDL_JOBS`](/information-schema/information-schema-ddl-jobs.md)：当前正在运行和已完成的 DDL 任务信息。 +- [`mysql.tidb_mdl_view`](/mysql-schema/mysql-schema-tidb-mdl-view.md)：元数据锁的信息。可帮助识别哪个查询阻塞了 DDL 的执行进程。 + ## 常见问题 DDL 语句执行相关的常见问题，参考 [SQL FAQ - DDL 执行](/faq/sql-faq.md#ddl-执行)。 diff --git a/best-practices/grafana-monitor-best-practices.md b/best-practices/grafana-monitor-best-practices.md index b1613f940c70..01c083d220af 100644 --- a/best-practices/grafana-monitor-best-practices.md +++ b/best-practices/grafana-monitor-best-practices.md @@ -1,7 +1,7 @@ --- title: 使用 Grafana 监控 TiDB 的最佳实践 summary: 了解高效利用 Grafana 监控 TiDB 的七个技巧。 -aliases: ['/docs-cn/dev/best-practices/grafana-monitor-best-practices/','/docs-cn/dev/reference/best-practices/grafana-monitor/'] +aliases: ['/docs-cn/dev/best-practices/grafana-monitor-best-practices/','/docs-cn/dev/reference/best-practices/grafana-monitor/','/zh/tidb/stable/grafana-monitor-best-practices/','/zh/tidb/dev/grafana-monitor-best-practices/'] --- # 使用 Grafana 监控 TiDB 的最佳实践 diff --git a/best-practices/haproxy-best-practices.md b/best-practices/haproxy-best-practices.md index 313036cd8f97..525473659a93 100644 --- a/best-practices/haproxy-best-practices.md +++ b/best-practices/haproxy-best-practices.md @@ -1,7 +1,7 @@ --- title: HAProxy 在 TiDB 中的最佳实践 -aliases: ['/docs-cn/dev/best-practices/haproxy-best-practices/','/docs-cn/dev/reference/best-practices/haproxy/'] summary: HAProxy 是 TiDB 中实现负载均衡的最佳实践。它提供 TCP 协议下的负载均衡能力，通过连接 HAProxy 提供的浮动 IP 对数据进行操作，实现 TiDB Server 层的负载均衡。HAProxy 提供高可用性、负载均衡、健康检查、会话保持、SSL 支持和监控统计等核心功能。部署 HAProxy 需要满足一定的硬件和软件要求，配置和启动 HAProxy 后即可实现数据库负载均衡。 +aliases: ['/docs-cn/dev/best-practices/haproxy-best-practices/','/docs-cn/dev/reference/best-practices/haproxy/','/zh/tidb/stable/haproxy-best-practices/','/zh/tidb/dev/haproxy-best-practices/'] --- # HAProxy 在 TiDB 中的最佳实践 @@ -69,8 +69,6 @@ HAProxy 由 Linux 内核的核心贡献者 Willy Tarreau 于 2000 年编写， 执行如下命令安装依赖包： -{{< copyable "shell-regular" >}} - ```bash yum -y install epel-release gcc systemd-devel ``` @@ -81,28 +79,22 @@ HAProxy 配置 Database 负载均衡场景操作简单，以下部署操作具 ### 安装 HAProxy -1. 下载 HAProxy 2.6.2 的源码包： - - {{< copyable "shell-regular" >}} +1. 下载 HAProxy 2.6.21 的源码包： ```bash - wget https://www.haproxy.org/download/2.6/src/haproxy-2.6.2.tar.gz + wget https://www.haproxy.org/download/2.6/src/haproxy-2.6.21.tar.gz ``` 2. 解压源码包： - {{< copyable "shell-regular" >}} - ```bash - tar zxf haproxy-2.6.2.tar.gz + tar zxf haproxy-2.6.21.tar.gz ``` 3. 从源码编译 HAProxy 应用： - {{< copyable "shell-regular" >}} - ```bash - cd haproxy-2.6.2 + cd haproxy-2.6.21 make clean make -j 8 TARGET=linux-glibc USE_THREAD=1 make PREFIX=${/app/haproxy} SBINDIR=${/app/haproxy/bin} install # 将 `${/app/haproxy}` 和 `${/app/haproxy/bin}` 替换为自定义的实际路径。 @@ -110,8 +102,6 @@ HAProxy 配置 Database 负载均衡场景操作简单，以下部署操作具 4. 重新配置 `profile` 文件： - {{< copyable "shell-regular" >}} - ```bash echo 'export PATH=/app/haproxy/bin:$PATH' >> /etc/profile . /etc/profile @@ -119,8 +109,6 @@ HAProxy 配置 Database 负载均衡场景操作简单，以下部署操作具 5. 检查 HAProxy 是否安装成功： - {{< copyable "shell-regular" >}} - ```bash which haproxy ``` @@ -129,8 +117,6 @@ HAProxy 配置 Database 负载均衡场景操作简单，以下部署操作具 执行如下命令查看命令行参数及基本用法： -{{< copyable "shell-regular" >}} - ```bash haproxy --help ``` @@ -202,7 +188,7 @@ listen admin_stats # frontend 和 backend 的组合体 stats admin if TRUE # 手工启用或禁用后端服务器（HAProxy 1.4.9 及之后版本开始支持）。 listen tidb-cluster # 配置 database 负载均衡。 - bind 0.0.0.0:3390 # 浮动 IP 和 监听端口。 + bind 0.0.0.0:3390 # 浮动 IP 和监听端口。 mode tcp # HAProxy 要使用第 4 层的传输层。 balance leastconn # 连接数最少的服务器优先接收连接。`leastconn` 建议用于长会话服务，例如 LDAP、SQL、TSE 等，而不是短会话协议，如 HTTP。该算法是动态的，对于启动慢的服务器，服务器权重会在运行中作调整。 server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # 检测 4000 端口，检测频率为每 2000 毫秒一次。如果 2 次检测为成功，则认为服务器可用；如果 3 次检测为失败，则认为服务器不可用。 @@ -226,8 +212,6 @@ listen tidb-cluster # 配置 database 负载均衡。 要启动 HAProxy，执行 `haproxy` 命令。默认读取 `/etc/haproxy/haproxy.cfg`（推荐）。 -{{< copyable "shell-regular" >}} - ```bash haproxy -f /etc/haproxy/haproxy.cfg ``` @@ -238,16 +222,12 @@ haproxy -f /etc/haproxy/haproxy.cfg 1. 执行如下命令： - {{< copyable "shell-regular" >}} - ```bash ps -ef | grep haproxy ``` 2. 终止 HAProxy 相关的 PID 进程： - {{< copyable "shell-regular" >}} - ```bash kill -9 ${haproxy.pid} ``` diff --git a/best-practices/high-concurrency-best-practices.md b/best-practices/high-concurrency-best-practices.md index 3b6c6fff413b..3f9e82853f5d 100644 --- a/best-practices/high-concurrency-best-practices.md +++ b/best-practices/high-concurrency-best-practices.md @@ -1,7 +1,7 @@ --- title: TiDB 高并发写入场景最佳实践 summary: 了解 TiDB 在高并发写入场景下的最佳实践。 -aliases: ['/docs-cn/dev/best-practices/high-concurrency-best-practices/','/docs-cn/dev/reference/best-practices/high-concurrency/'] +aliases: ['/docs-cn/dev/best-practices/high-concurrency-best-practices/','/docs-cn/dev/reference/best-practices/high-concurrency/','/zh/tidb/stable/high-concurrency-best-practices/','/zh/tidb/dev/high-concurrency-best-practices/'] --- # TiDB 高并发写入场景最佳实践 @@ -10,7 +10,7 @@ aliases: ['/docs-cn/dev/best-practices/high-concurrency-best-practices/','/docs- ## 目标读者 -本文假设你已对 TiDB 有一定的了解，推荐先阅读 TiDB 原理相关的三篇文章（[讲存储](https://pingcap.com/blog-cn/tidb-internal-1/)，[说计算](https://pingcap.com/blog-cn/tidb-internal-2/)，[谈调度](https://pingcap.com/blog-cn/tidb-internal-3/)），以及 [TiDB Best Practice](https://pingcap.com/blog-cn/tidb-best-practice/)。 +本文假设你已对 TiDB 有一定的了解，推荐先阅读 TiDB 原理相关的三篇文章（[讲存储](https://tidb.net/blog/dbe4f467)，[说计算](https://tidb.net/blog/8427565a)，[谈调度](https://tidb.net/blog/a558961f)），以及 [TiDB Best Practice](https://tidb.net/blog/7f818fc0)。 ## 高并发批量插入场景 @@ -29,7 +29,7 @@ aliases: ['/docs-cn/dev/best-practices/high-concurrency-best-practices/','/docs- ## TiDB 数据分布原理 -如果要解决以上挑战，需要从 TiDB 数据切分以及调度的原理开始讲起。这里只作简单说明，详情可参阅[谈调度](https://pingcap.com/blog-cn/tidb-internal-3/)。 +如果要解决以上挑战，需要从 TiDB 数据切分以及调度的原理开始讲起。这里只作简单说明，详情可参阅[谈调度](https://tidb.net/blog/a558961f)。 TiDB 以 Region 为单位对数据进行切分，每个 Region 有大小限制（默认 96M）。Region 的切分方式是范围切分。每个 Region 会有多副本，每一组副本，称为一个 Raft Group。每个 Raft Group 中由 Leader 负责执行这块数据的读 & 写（TiDB 支持 [Follower-Read](/follower-read.md)）。Leader 会自动地被 PD 组件均匀调度在不同的物理节点上，用以均分读写压力。 diff --git a/best-practices/index-management-best-practices.md b/best-practices/index-management-best-practices.md new file mode 100644 index 000000000000..a8a31084052b --- /dev/null +++ b/best-practices/index-management-best-practices.md @@ -0,0 +1,320 @@ +--- +title: 管理索引和识别未使用索引的最佳实践 +summary: 了解在 TiDB 中管理和优化索引、识别并移除未使用索引的最佳实践。 +aliases: ['/zh/tidb/stable/index-management-best-practices/','/zh/tidb/dev/index-management-best-practices/'] +--- + +# 管理索引和识别未使用索引的最佳实践 + +索引对于优化数据库查询性能至关重要，能够减少大规模数据扫描的需求。然而，随着应用的演进、业务逻辑的变化以及数据规模的增长，原有的索引设计也可能会遇到问题，包括以下两类： + +- 未使用索引：这些索引曾经有用，但现在查询优化器已不再选择它们，却仍占用存储空间，并给写入操作带来不必要的开销。 +- 低效索引：某些索引虽然被优化器使用，但扫描的数据量远超预期，导致磁盘 I/O 增加，查询速度变慢。 + +如果不及时处理，这些索引问题会导致存储成本上升、性能下降和运维效率降低。在 TiDB 这样的分布式 SQL 数据库中，索引效率低下的影响更大，因为分布式查询规模大且多节点协同更复杂。因此，定期进行索引审计对于保持数据库优化至关重要。 + +主动识别并优化索引有助于： + +- 降低存储开销：移除未使用索引可释放磁盘空间，降低长期存储成本。 +- 提升写入性能：写密集型场景（如 `INSERT`、`UPDATE`、`DELETE`）下，移除不必要的索引维护可以提升性能。 +- 优化查询执行：高效的索引能够减少扫描的行数，从而加快查询速度、缩短响应时间。 +- 简化数据库管理：减少并优化索引可以简化备份、恢复和 schema 变更。 + +由于索引会随着业务逻辑的变化而不断演进，定期进行索引审计已成为数据库维护的标准流程。TiDB 提供了内置的可观测性手段，帮助你安全高效地观测、评估和优化索引。 + +TiDB v8.0.0 引入了 [`INFORMATION_SCHEMA.TIDB_INDEX_USAGE`](/information-schema/information-schema-tidb-index-usage.md) 表和 [`sys.schema_unused_indexes`](/sys-schema/sys-schema-unused-indexes.md) 表，来帮助你追踪索引使用情况，并根据运行数据做出正确判断。 + +本文介绍如何使用观测工具检测并移除未使用或低效索引，从而提升 TiDB 的性能与稳定性。 + +## TiDB 索引优化：数据驱动的方法 + +索引对于查询性能至关重要，但如果没有充分分析就移除索引，可能导致意想不到的性能回退，甚至引发系统不稳定。为确保索引管理的安全性与有效性，TiDB 提供了内置的可观测性手段，支持以下操作： + +- 实时追踪索引使用情况：识别索引的访问频率，并判断其是否有助于性能提升。 +- 检测未使用索引：定位自数据库上次重启以来从未被使用过的索引。 +- 评估索引效率：判断索引是否能有效过滤数据，或是否导致 I/O 开销过多。 +- 安全测试索引移除：在删除索引前，可将其暂时设为不可见，确认无查询依赖该索引后再删除。 + +TiDB 通过以下手段简化了索引优化： + +- `INFORMATION_SCHEMA.TIDB_INDEX_USAGE`：监控索引使用模式和查询频率。 +- `sys.schema_unused_indexes`：列出自数据库上次重启以来未被使用过的索引。 +- 不可见索引：在永久删除索引之前，你可以先测试移除索引的影响。 + +借助这些可观测性工具，你可以放心清理冗余索引，避免性能下降风险。 + +## 使用 `TIDB_INDEX_USAGE` 追踪索引使用情况 + +从 [TiDB v8.0.0](/releases/release-8.0.0.md) 开始，你可以使用 `TIDB_INDEX_USAGE` 系统表实时观测索引使用情况，帮助你优化查询性能并移除不必要的索引。 + +具体来说，你可以通过 `TIDB_INDEX_USAGE` 进行以下操作： + +- 检测未使用索引：识别未被查询访问过的索引，帮助判断哪些索引可以安全移除。 +- 分析索引效率：追踪索引使用频率，评估其是否有助于提升查询执行效率。 +- 评估查询模式：了解索引对读操作、数据扫描和 KV 请求的影响。 + +从 [TiDB v8.4.0](/releases/release-8.4.0.md) 开始，`TIDB_INDEX_USAGE` 还包含聚簇表的主键，进一步提升了索引性能可见性。 + +### `TIDB_INDEX_USAGE` 关键指标 + +如需查看 `TIDB_INDEX_USAGE` 系统表字段，可执行以下 SQL 语句： + +```sql +USE INFORMATION_SCHEMA; +DESC TIDB_INDEX_USAGE; +``` + +```sql ++--------------------------+-------------+------+------+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++--------------------------+-------------+------+------+---------+-------+ +| TABLE_SCHEMA | varchar(64) | YES | | NULL | | +| TABLE_NAME | varchar(64) | YES | | NULL | | +| INDEX_NAME | varchar(64) | YES | | NULL | | +| QUERY_TOTAL | bigint(21) | YES | | NULL | | +| KV_REQ_TOTAL | bigint(21) | YES | | NULL | | +| ROWS_ACCESS_TOTAL | bigint(21) | YES | | NULL | | +| PERCENTAGE_ACCESS_0 | bigint(21) | YES | | NULL | | +| PERCENTAGE_ACCESS_0_1 | bigint(21) | YES | | NULL | | +| PERCENTAGE_ACCESS_1_10 | bigint(21) | YES | | NULL | | +| PERCENTAGE_ACCESS_10_20 | bigint(21) | YES | | NULL | | +| PERCENTAGE_ACCESS_20_50 | bigint(21) | YES | | NULL | | +| PERCENTAGE_ACCESS_50_100 | bigint(21) | YES | | NULL | | +| PERCENTAGE_ACCESS_100 | bigint(21) | YES | | NULL | | +| LAST_ACCESS_TIME | datetime | YES | | NULL | | ++--------------------------+-------------+------+------+---------+-------+ +共 14 行 +``` + +关于这些列的详细说明，参见 [`TIDB_INDEX_USAGE`](/information-schema/information-schema-tidb-index-usage.md)。 + +### 利用 `TIDB_INDEX_USAGE` 识别未使用和低效索引 + +本节介绍如何利用 `TIDB_INDEX_USAGE` 系统表识别未使用和低效索引。 + +- 未使用索引： + + - 如果 `QUERY_TOTAL = 0`，说明该索引未被任何查询使用。 + - 如果 `LAST_ACCESS_TIME` 显示的时间距今较久，说明该索引可能已无用。 + +- 低效索引： + + - 如果 `PERCENTAGE_ACCESS_100` 数值较大，说明存在全索引扫描，可能为低效索引。 + - 对比 `ROWS_ACCESS_TOTAL` 与 `QUERY_TOTAL`，判断索引在查询中扫描的行数是否过多。 + +通过 `TIDB_INDEX_USAGE` 系统表，你可以详细了解索引性能，以便移除冗余索引、优化查询执行。 + +### 高效使用 `TIDB_INDEX_USAGE` + +以下要点可以帮助你正确理解并使用 `TIDB_INDEX_USAGE` 系统表。 + +#### 数据更新存在延迟 + +为降低性能影响，`TIDB_INDEX_USAGE` 的数据并非实时更新，索引使用指标可能会有最多 5 分钟的延迟。在分析查询时，需要考虑这一延迟。 + +#### 索引使用数据不持久化 + +`TIDB_INDEX_USAGE` 系统表的数据存储在每个 TiDB 实例的内存中，不会持久化，在节点重启后数据会丢失。 + +#### 跟踪历史数据 + +你可以定期使用以下 SQL 语句导出索引使用快照： + +```sql +SELECT * FROM INFORMATION_SCHEMA.TIDB_INDEX_USAGE INTO OUTFILE '/backup/index_usage_snapshot.csv'; +``` + +通过比较不同时间的快照，可以进行历史追踪，帮助你发现索引使用趋势，从而做出更有依据的索引优化或清理决策。 + +## 使用 `CLUSTER_TIDB_INDEX_USAGE` 汇总全集群索引数据 + +由于 TiDB 是分布式 SQL 数据库，查询负载会分布于多个节点。每个 TiDB 节点独立追踪本地索引使用情况。为获得全局索引性能，TiDB 提供了 [`CLUSTER_TIDB_INDEX_USAGE`](/information-schema/information-schema-tidb-index-usage.md#cluster_tidb_index_usage) 系统表，汇总了所有节点的索引使用数据，确保在优化索引策略时充分考虑分布式查询负载。 + +不同 TiDB 节点的查询负载可能不同。某个索引在部分节点看似未被使用，但在其他节点可能仍然至关重要。如果要按查询负载对索引分析进行划分，执行以下 SQL 语句： + +```sql +SELECT INSTANCE, TABLE_NAME, INDEX_NAME, SUM(QUERY_TOTAL) AS total_queries +FROM INFORMATION_SCHEMA.CLUSTER_TIDB_INDEX_USAGE +GROUP BY INSTANCE, TABLE_NAME, INDEX_NAME +ORDER BY total_queries DESC; +``` + +这样可以帮助判断一个索引是在所有节点上都未被使用，还是仅在特定节点未被使用，从而帮助你在删除索引时做出更明智的决策。 + +### `TIDB_INDEX_USAGE` 与 `CLUSTER_TIDB_INDEX_USAGE` 的区别 + +`TIDB_INDEX_USAGE` 与 `CLUSTER_TIDB_INDEX_USAGE` 的区别如下表所示： + +| 功能 | `TIDB_INDEX_USAGE` | `CLUSTER_TIDB_INDEX_USAGE` | +| -------------- | ----------------------------------------- | -------------------------------------------- | +| 作用范围 | 追踪单个数据库实例内的索引使用情况 | 汇总整个 TiDB 集群的索引使用情况 | +| 索引追踪 | 数据为本地实例级 | 提供集群级统一视图 | +| 主要用途 | 调试数据库实例级的索引使用情况 | 分析全局索引模式及多节点行为 | + +### 高效使用 `CLUSTER_TIDB_INDEX_USAGE` + +由于 `CLUSTER_TIDB_INDEX_USAGE` 系统表汇总了多个节点的数据，使用时需注意以下事项： + +- 数据更新存在延迟 + + 为将对性能的影响降到最低，`CLUSTER_TIDB_INDEX_USAGE` 不会实时更新。索引使用指标可能会有最多 5 分钟的延迟。在分析查询时，需要考虑这一延迟。 + +- 内存存储 + + 与 `TIDB_INDEX_USAGE` 一样，在节点重启后，储存在内存中的索引使用数据会丢失。 + +通过 `CLUSTER_TIDB_INDEX_USAGE`，可获得全局视角的索引行为，确保索引策略与分布式查询负载匹配。 + +## 使用 `schema_unused_indexes` 快速识别未使用索引 + +手动分析索引使用数据可能会非常耗时。为简化该过程，TiDB 提供了 [`schema_unused_indexes`](/sys-schema/sys-schema-unused-indexes.md) 系统视图，用于列出自数据库上次重启以来未被使用过的索引。 + +使用该视图，你可以： + +- 快速识别不再使用的索引，降低不必要的存储成本。 +- 通过移除无用索引，加速 DML 操作（如 `INSERT`、`UPDATE`、`DELETE`）。 +- 无需手动分析查询模式，简化索引审计。 + +通过使用 `schema_unused_indexes`，你可以快速识别不必要的索引，轻松降低数据库开销。 + +### `schema_unused_indexes` 的工作原理 + +`schema_unused_indexes` 视图基于 `TIDB_INDEX_USAGE`，可以自动筛选出自上次 TiDB 重启以来查询次数为零的索引。 + +查询未使用索引： + +```sql +SELECT * FROM sys.schema_unused_indexes; +``` + +返回类似如下结果： + +``` ++-----------------+---------------+--------------------+ +| object_schema | object_name | index_name | ++---------------- + ------------- + -------------------+ +| bookshop | users | nickname | +| bookshop | ratings | uniq_book_user_idx | ++---------------- + ------------- + -------------------+ +``` + +### 使用 `schema_unused_indexes` 的注意事项 + +使用 `schema_unused_indexes` 时，需注意以下事项。 + +#### 仅统计自上次重启以来的未使用索引 + +- 如果 TiDB 节点重启，索引使用数据会被重置。 +- 在使用索引数据之前，确保系统已经运行了足够长的时间，以便捕获具有代表性的业务负载。 + +#### 并非所有未使用索引都可立即删除 + +有些索引可能使用频率很低，但对于特定查询、批处理或报表任务仍然至关重要。在删除索引之前，请考虑它是否支持以下场景： + +- 低频但关键的查询，如月度报表、分析任务 +- 非每日运行的批处理作业 +- 临时排查故障用的查询 + +如果索引在重要但不频繁的查询中出现，建议先保留或设为不可见。 + +你可以使用[不可见索引](#使用不可见索引安全测试索引移除)来安全地验证某个索引是否可以删除，而不会影响系统性能。 + +### 手动创建 `schema_unused_indexes` 视图 + +对于从较早版本升级到 TiDB v8.0.0 或更高版本的集群，需要手动创建系统 schema 及相关视图。 + +详见[手动创建 `schema_unused_indexes` 视图](/sys-schema/sys-schema-unused-indexes.md#手动创建-schema_unused_indexes-视图)。 + +## 使用不可见索引安全测试索引移除 + +在未经充分验证的情况下直接删除索引可能带来性能风险，尤其是那些虽不常用但对特定查询仍至关重要的索引。 + +为降低风险，TiDB 提供了不可见索引，可以临时禁用索引但不删除。通过使用不可见索引，你可以安全地验证索引删除决策，确保数据库优化过程更加可控和可预测。 + +### 什么是不可见索引？ + +不可见索引仍然存在于数据库中，但 TiDB 优化器会忽略它。你可以使用 [`ALTER TABLE ... INVISIBLE`](/sql-statements/sql-statement-alter-table.md) 将索引设为不可见，从而在不永久删除索引的情况下测试该索引是否真的无用。 + +不可见索引的主要优势如下： + +- **安全测试索引**：查询将不再使用该索引，但相关的优化器统计信息仍然会被维护，必要时可随时快速恢复。 +- **不影响索引存储**：索引结构未变，无需重新创建，避免额外开销。 +- **性能监控**：数据库管理员可观察禁用索引后的查询表现，辅助决策。 + +### 设置索引为不可见 + +要在不删除索引的情况下使其不可见，可执行以下 SQL 语句： + +```sql +ALTER TABLE bookshop.users ALTER INDEX nickname INVISIBLE; +``` + +设置索引为不可见后，观察系统的查询性能： + +- 如果性能保持不变，说明该索引可能不必要，可以安全删除。 +- 如果查询延迟增加，说明该索引可能仍有必要保留。 + +### 高效使用不可见索引 + +- **建议在业务低峰期测试**：便于在可控环境中监控对性能的影响。 +- **结合查询监控工具**：对比分析索引可见与不可见时的执行计划。 +- **在多种业务场景进行验证**：确保索引不被特定报表或定时任务依赖。 + +### 不可见索引建议保留多久？ + +- OLTP 负载：建议至少观察一周，覆盖日常波动。 +- 批处理或 ETL 负载：建议覆盖一个完整的报表周期，如月度财务报表。 +- 临时分析查询：结合查询日志确认不依赖该索引后再删除。 + +安全起见，建议至少保持索引在一个完整业务周期内处于不可见状态，以确保所有工作负载都已经过验证，再做最终决定。 + +## 索引优化的五大最佳实践 + +为了保持高性能和高效的资源利用，定期进行索引优化是数据库运维的常规工作。以下是 TiDB 中有效管理索引的最佳实践： + +1. **定期监控索引使用。** + + - 使用 [`TIDB_INDEX_USAGE`](/information-schema/information-schema-tidb-index-usage.md) 和 [`CLUSTER_TIDB_INDEX_USAGE`](/information-schema/information-schema-tidb-index-usage.md#cluster_tidb_index_usage) 追踪索引使用情况。 + - 通过 [`schema_unused_indexes`](/sys-schema/sys-schema-unused-indexes.md) 识别未使用的索引，并评估是否可删除。 + - 监控查询执行计划，识别可能导致高 I/O 的低效索引。 + +2. **在删除索引前，务必进行验证。** + + - 使用 [`ALTER TABLE ... INVISIBLE`](/sql-statements/sql-statement-alter-table.md) 将索引设为不可见，临时禁用索引，观察影响后再决定是否永久删除。 + - 若查询性能保持稳定，可考虑删除索引。 + - 确保有足够的观察周期，以覆盖所有业务场景或查询模式后再做最终决策。 + +3. **优化现有索引。** + + - 合并冗余索引。合并冗余索引可以减少存储开销、提升写入性能。如果多个索引服务于相似的查询，可以考虑将它们合并为单个更高效的复合索引。 + + - 执行以下 SQL 语句，查找前缀重叠的索引（表明可能存在冗余）： + + ```sql + SELECT TABLE_SCHEMA, TABLE_NAME, INDEX_NAME, COLUMN_NAME, SEQ_IN_INDEX + FROM INFORMATION_SCHEMA.STATISTICS + WHERE TABLE_NAME = 'your_table' + ORDER BY TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, SEQ_IN_INDEX; + ``` + + - 若两个索引的前导列相同，建议考虑将它们合并为复合索引。 + + - 提高选择性。可以通过以下方式优化低选择性索引（即那些过滤行数过多的索引）： + + - 增加额外的列，以提升过滤效率。 + - 调整索引结构（如前缀索引、复合索引）。 + + - 分析索引选择性。利用 `TIDB_INDEX_USAGE` 的 `PERCENTAGE_ACCESS_*` 字段评估索引过滤数据的效果。 + +4. **关注 DML 性能影响。** + + - 避免过度索引。每增加一个索引，`INSERT`、`UPDATE` 和 `DELETE` 操作的开销都会增加。 + - 仅为查询所必需的字段建立索引，以减少写入密集型负载的维护成本。 + +5. **定期测试与调优。** + + - 定期进行索引审计，尤其在业务负载发生重大变化后。 + - 利用 TiDB 执行计划分析工具，验证索引是否被高效使用。 + - 新增索引时，建议先在隔离环境中测试，避免出现意外的性能回退。 + +通过遵循以上这些最佳实践，你可以确保查询高效执行，减少不必要的存储开销，并保持数据库性能最优。 diff --git a/best-practices/massive-regions-best-practices.md b/best-practices/massive-regions-best-practices.md index afc4d6748e26..eb8d996fc21b 100644 --- a/best-practices/massive-regions-best-practices.md +++ b/best-practices/massive-regions-best-practices.md @@ -1,7 +1,7 @@ --- title: 海量 Region 集群调优最佳实践 summary: 了解海量 Region 导致性能问题的原因和优化方法。 -aliases: ['/docs-cn/dev/best-practices/massive-regions-best-practices/','/docs-cn/dev/reference/best-practices/massive-regions/'] +aliases: ['/docs-cn/dev/best-practices/massive-regions-best-practices/','/docs-cn/dev/reference/best-practices/massive-regions/','/zh/tidb/stable/massive-regions-best-practices/','/zh/tidb/dev/massive-regions-best-practices/'] --- # 海量 Region 集群调优最佳实践 @@ -146,7 +146,7 @@ Region 的默认大小为 256 MiB，将其调大可以减少 Region 个数，详 ### 方法七：提高 Raft 通信的的最大连接数 -TiKV 节点间用于 Raft 通信的最大连接数默认为 1，将其调大可以减少因为海量 Region 通信量过大而导致的阻塞情况。具体的配置说明可以参考 [`grpc-raft-conn-num`](/tikv-configuration-file.md#grpc-raft-conn-num)。 +TiKV 节点间用于 Raft 通信的最大连接数可以通过 [`server.grpc-raft-conn-num`](/tikv-configuration-file.md#grpc-raft-conn-num) 配置项调整，将其值调大可以减少因为海量 Region 通信量过大而导致的阻塞情况。 > **注意：** > diff --git a/best-practices/multi-column-index-best-practices.md b/best-practices/multi-column-index-best-practices.md new file mode 100644 index 000000000000..1ee1d1d3ebff --- /dev/null +++ b/best-practices/multi-column-index-best-practices.md @@ -0,0 +1,264 @@ +--- +title: 多列索引优化最佳实践 +summary: 了解如何在 TiDB 中高效使用多列索引，并应用高级优化技巧。 +aliases: ['/zh/tidb/stable/multi-column-index-best-practices/','/zh/tidb/dev/multi-column-index-best-practices/'] +--- + +# 多列索引优化最佳实践 + +在当今数据驱动的世界中，高效处理大数据集上的复杂查询对于保持应用响应和性能至关重要。对于 TiDB 这样专为高规模、高需求环境设计的分布式 SQL 数据库来说，优化数据访问路径是实现高效查询的关键。 + +索引是提升查询性能的重要工具，可以避免全表扫描。TiDB 的查询优化器能够利用多列索引 (Multi-Column Indexes) 智能过滤数据，处理复杂的查询条件，这在传统数据库（如 MySQL）中往往难以实现。 + +本文将介绍多列索引的工作原理、重要性，以及 TiDB 如何将复杂的查询条件优化为高效的数据访问路径。通过这些优化，即使在大规模场景下，你也能获得更快的响应速度、最小化的表扫描，以及更流畅的性能。 + +如果没有这些优化，大型 TiDB 数据库中的查询性能可能会迅速下降。全表扫描和低效过滤会让毫秒级的查询变成分钟级，内存消耗过大还可能导致内存溢出 (Out of Memory, OOM) 错误，尤其是在资源受限的环境下。TiDB 的针对性优化方式确保只访问相关数据，从而保持低延迟和高效的内存使用，即使面对最复杂的查询也能应对自如。 + +## 前提条件 + +- 多列索引功能在 TiDB v8.3.0 及以上版本可用。 +- 使用该功能前，需将[优化器 Fix Control **54337**](/optimizer-fix-controls.md#54337-从-v830-版本开始引入) 设置为 `ON`。 + +## 背景：多列索引 + +本文以一个租房信息表为例，每条记录包含唯一 ID、城市、卧室数、租金和可入住日期： + +```sql +CREATE TABLE listings ( + listing_id INT PRIMARY KEY AUTO_INCREMENT, + city VARCHAR(100) NOT NULL, + bedrooms INT NOT NULL, + price DECIMAL(10, 2) NOT NULL, + availability_date DATE NOT NULL +); +``` + +假设该表在全中国有 2000 万条房源。如果你想查找租金低于 2000 元的房源，可以在 `price` 列上建索引。这样优化器只需扫描 `[-inf, 2000.00)` 范围的数据，假设 70% 房源高于 2000 元，实际扫描量约为 1400 万行。执行计划如下： + +```sql +-- 查询 1：查找租金低于 2000 的房源 +EXPLAIN FORMAT = "brief" SELECT * FROM listings WHERE price < 2000; +``` + +``` ++-----------------------------+---------+----------------------------------------------+---------------------------+ +| id | task | access object | operator info | ++-----------------------------+---------+----------------------------------------------+---------------------------+ +| IndexLookUp | root | | | +| ├─IndexRangeScan(Build) | root | table: listings, index: price_idx(price) | range: [-inf, 2000.00) | +| └─TableRowIDScan(Probe) | root | table: listings | | ++-----------------------------+---------+----------------------------------------------+---------------------------+ +``` + +虽然这样能提升性能，但返回的结果仍然数量庞大。若你需要更精确的房源，可以增加过滤条件，如指定城市、卧室数和最高租金。例如，查找北京两居室且租金低于 2000 元的房源，结果会大大缩小，可能只剩几十条。 + +为优化此查询，可以在 `city`、`bedrooms` 和 `price` 上创建一个多列索引： + +```sql +CREATE INDEX idx_city_bedrooms_price ON listings (city, bedrooms, price); +``` + +SQL 中的多列索引按字典序排序。以 `(city, bedrooms, price)` 为例，数据先按 `city` 排序，再在每个 `city` 内按 `bedrooms` 排序，最后在每个 `(city, bedrooms)` 内按 `price` 排序。这样 TiDB 能高效利用每个条件： + +1. 先按 `city` 过滤； +2. 再按 `bedrooms` 过滤； +3. 最后按 `price` 过滤。 + +## 示例数据 + +下表展示了多列索引如何细化搜索结果： + +| City | Bedrooms| Price | +| -------- | ------- | ------| +| Beijing | 1 | 1000 | +| Beijing | 1 | 1500 | +| Beijing | 2 | 1000 | +| Beijing | 2 | 1500 | +| Beijing | 3 | 2500 | +| Beijing | 3 | 3000 | +| Shanghai | 1 | 1000 | +| Shanghai | 1 | 1500 | +| Shanghai | 2 | 1000 | +| Shanghai | 2 | 2500 | +| Shanghai | 3 | 1000 | +| Shanghai | 3 | 2500 | + +## 优化查询与结果 + +利用多列索引，TiDB 能高效定位北京两居室且租金低于 2000 元的房源： + +```sql +-- 查询 2：查找北京两居室且租金低于 2000 的房源 +EXPLAIN FORMAT = "brief" + SELECT * FROM listings + WHERE city = 'Beijing' AND bedrooms = 2 AND price < 2000; +``` + +``` ++------------------------+------+---------------------------------------------------------------------------------------------+---------------------------------+ +| id | task | access object | operator info | ++------------------------+------+---------------------------------------------------------------------------------------------+---------------------------------+ +| IndexLookUp | root | | | +| ├─IndexRangeScan(Build)| root |table:listings,index:idx_city_bedrooms_price ["Beijing" 2 -inf,(city, bedrooms, price)]|range:["Beijing" 2 2000.00)| +| └─TableRowIDScan(Probe)| root |table:listings | | ++------------------------+------+---------------------------------------------------------------------------------------------+---------------------------------+ +``` + +该查询在示例数据中返回： + +| City | Bedrooms| Price | +| -------------- | ------- | ------ | +| Beijing | 2 | 1000 | +| Beijing | 2 | 1500 | + +通过多列索引，TiDB 避免了不必要的行扫描，大幅提升查询性能。 + +## 索引范围推导 (Index Range Derivation) + +TiDB 优化器内置了强大的范围推导组件。该组件会根据查询条件和相关索引列，生成高效的索引范围，并传递给表访问组件，来决定最优的数据访问方式。 + +对于查询中的每个表，表访问组件会评估所有可用索引，以确定最佳的访问方式，无论是全表扫描还是索引扫描。它会计算每个相关索引的范围，评估访问代价，选择代价最低的路径。这一过程结合了范围推导和代价评估，确保数据检索既高效又节省资源。 + +下图展示了 TiDB 如何通过范围推导和代价评估协同工作，以选择最优的表访问路径： + +![表访问路径选择](/media/best-practices/multi-column-index-table-access-path-selection.png) + +多列过滤条件往往比上述示例更复杂，可能包含 **AND**、**OR** 或两者组合。TiDB 的范围推导子系统能高效处理这些情况，生成最具选择性或最有效的索引范围。 + +一般来说，该子系统会对 **OR** 条件生成的范围执行 **UNION** 操作，对 **AND** 条件生成的范围执行 **INTERSECT** 操作。通过这种方式，TiDB 即使在面对复杂的过滤逻辑时，也能尽可能精确地筛选数据。 + +## 多列索引中的析取条件（`OR` 条件） + +当查询中包含 `OR` 条件（Disjunctive Predicates，析取谓词）时，优化器会分别处理每个条件，为每部分生成范围。如果范围有重叠，则合并为一个连续范围；否则保留为多个独立范围，均可用于索引扫描。 + +### 示例 1：重叠范围 + +假设要查找杭州两居室，租金在以下两个重叠区间的房源： + +- 租金在 1000~2000 元之间 +- 租金在 1500~2500 元之间 + +优化器会将两个区间合并为 1000 ~ 2500。查询及执行计划如下： + +```sql +-- 查询 3：重叠租金区间 +EXPLAIN FORMAT = "brief" + SELECT * FROM listings + WHERE (city = 'Hangzhou' AND bedrooms = 2 AND price >= 1000 AND price < 2000) + OR (city = 'Hangzhou' AND bedrooms = 2 AND price >= 1500 AND price < 2500); +``` + +``` ++-------------------------+------+----------------------------------------------------------------------+--------------------------------------------------+ +| id | task | access object | operator info | ++-------------------------+------+----------------------------------------------------------------------+--------------------------------------------------+ +| IndexLookUp | root | | | +| ├─IndexRangeScan(Build) | root | table:listings,index:idx_city_bedrooms_price(city, bedrooms, price) | range:["Hangzhou" 2 1000.00,"Hangzhou" 2 2500.00)| +| └─TableRowIDScan(Probe) | root | table:listings | | ++-------------------------+------+----------------------------------------------------------------------+--------------------------------------------------+ +``` + +### 示例 2：不重叠范围 + +再比如查找北京或上海的一居室，分别在不同租金区间： + +- 北京一居室，租金 1500 ~ 2500 +- 上海一居室，租金 1000 ~ 1500 + +由于区间不重叠，执行计划中会保留两个独立范围： + +```sql +-- 查询 4：不同城市的不重叠区间 + +EXPLAIN FORMAT = "brief" + SELECT * FROM listings + WHERE + (city = 'Beijing' AND bedrooms = 1 AND price >= 1500 AND price < 2500) + OR (city = 'Shanghai' AND bedrooms = 1 AND price >= 1000 AND price < 1500); +``` + +``` ++-------------------------+------+--------------------------------------------------------------------+------------------------------------------------------------+ +| id | task | access object | operator info | ++-------------------------+------+--------------------------------------------------------------------+------------------------------------------------------------+ +| IndexLookUp | root | | | +| ├─IndexRangeScan(Build) | root | table:listings,index:idx_city_bedrooms_price(city, bedrooms, price)| range:["Beijing" 1 1500.00,"Beijing" 1 2500.00) ["Shanghai" 1 1000, "Shanghai" 1 1500) | +| └─TableRowIDScan(Probe) | root | table:listings | | ++-------------------------+------+--------------------------------------------------------------------+------------------------------------------------------------+ +``` + +通过合并或保留独立范围，优化器能高效利用索引处理 `OR` 条件，避免无谓扫描，提升性能。 + +## 多列索引中的合取条件（`AND` 条件） + +对于 **AND** 条件（合取条件），TiDB 优化器会为每个条件生成范围，并取其交集 (`INTERSECT`)，得到最精确的索引访问范围。如果某条件包含多个范围，TiDB 会组合这些范围，确保结果最优。 + +### 示例 1：表结构 + +假设有如下表 t1： + +```sql +CREATE TABLE t1 ( + a1 INT, + b1 INT, + c1 INT, + KEY iab (a1,b1) +); +``` + +有如下查询条件： + +```sql +(a1, b1) > (1, 10) AND (a1, b1) < (10, 20) +``` + +该查询涉及多列比较，TiDB 优化器的处理步骤如下： + +1. 拆解表达式。 + + - `(a1, b1) > (1, 10)` 转换为 `(a1 > 1) OR (a1 = 1 AND b1 > 10)`，表示包括所有 `a1` 大于 `1` 的情况，或 `a1` 等于 `1` 且 `b1` 大于 `10` 的情况。 + - `(a1, b1) < (10, 20)` 转换为 `(a1 < 10) OR (a1 = 10 AND b1 < 20)`，表示包括所有 `a1` 小于 `10` 的情况，或 `a1` 等于 `10` 且 `b1` 小于 `20` 的情况。 + + 合并后为： + + ```sql + ((a1 > 1) OR (a1 = 1 AND b1 > 10)) AND ((a1 < 10) OR (a1 = 10 AND b1 < 20)) + ``` + +2. 推导并组合范围。 + + - `(a1, b1) > (1, 10)`：推导出的范围包括 `(1, +inf]`（`a1 > 1` 的情况）和 `(1, 10, 1, +inf]`（`a1 = 1` 且 `b1 > 10` 的情况）。 + - `(a1, b1) < (10, 20)`：推导出的范围包括 `[-inf, 10)`（`a1 < 10` 的情况）和 `[10, -inf, 10, 20)`（`a1 = 10` 且 `b1 < 20` 的情况）。 + + 组合范围后，最终的索引范围为 `(1, 10, 1, +inf] UNION (1, 10) UNION [10, -inf, 10, 20)`。 + +### 示例 2：查询计划 + +查询计划如下： + +```sql +-- 查询 5：多列合取条件 +EXPLAIN FORMAT = "brief" + SELECT * FROM t1 + WHERE (a1, b1) > (1, 10) AND (a1, b1) < (10, 20); +``` + +``` ++-------------------------+------+----------------------------+-------------------------------------------+ +| id | task | access object | operator info | ++-------------------------+------+----------------------------+-------------------------------------------+ +| IndexLookUp | root | | | +| ├─IndexRangeScan(Build) | root | table:t1,index:iab(a1, b1) | range:(1 10,1 +inf],(1,10)[10 -inf,10 20) | +| └─TableRowIDScan(Probe) | root | table:t1 | | ++-------------------------+------+----------------------------+-------------------------------------------+ +``` + +假设表有 5 亿行，通过优化后只需访问约 4000 行，仅占总数据的 0.0008%。查询延迟从两分钟降至几毫秒。 + +与 MySQL 需全表扫描不同，TiDB 优化器可高效处理复杂行表达式，充分利用推导范围。 + +## 总结 + +TiDB 优化器通过多列索引和高级范围推导，可大幅降低复杂 SQL 查询的数据访问代价。无论是合取 (`AND`) 还是析取 (`OR`) 条件，TiDB 都能将行表达式转化为最优访问路径，缩短查询时间，提升性能。与 MySQL 不同，TiDB 支持多列索引上的并集与交集操作，能高效处理复杂过滤条件。在实际应用中，优化后查询可在几毫秒内完成，而未优化时可能需两分钟以上，极大降低了延迟。 + +更多 TiDB 与 MySQL 架构差异及其对可扩展性、可靠性和 HTAP 工作负载的影响，详见 [MySQL vs. TiDB: A Guide to Open Source Database Selection](https://www.pingcap.com/ebook-whitepaper/tidb-vs-mysql-product-comparison-guide/)。 diff --git a/best-practices/pd-scheduling-best-practices.md b/best-practices/pd-scheduling-best-practices.md index 2b9681d151c0..286860e8270c 100644 --- a/best-practices/pd-scheduling-best-practices.md +++ b/best-practices/pd-scheduling-best-practices.md @@ -1,7 +1,7 @@ --- title: PD 调度策略最佳实践 summary: 了解 PD 调度策略的最佳实践和调优方式 -aliases: ['/docs-cn/dev/best-practices/pd-scheduling-best-practices/','/docs-cn/dev/reference/best-practices/pd-scheduling/'] +aliases: ['/docs-cn/dev/best-practices/pd-scheduling-best-practices/','/docs-cn/dev/reference/best-practices/pd-scheduling/','/zh/tidb/stable/pd-scheduling-best-practices/','/zh/tidb/dev/pd-scheduling-best-practices/'] --- # PD 调度策略最佳实践 @@ -254,7 +254,7 @@ PD 的打分机制决定了一般情况下，不同 Store 的 Leader Count 和 R - 从 PD 的统计来看没有热点，但是从 TiKV 的相关 Metrics 可以看出部分节点负载明显高于其他节点，成为整个系统的瓶颈。这是因为目前 PD 统计热点 Region 的维度比较单一，仅针对流量进行分析，在某些场景下无法准确定位热点。例如部分 Region 有大量的点查请求，从流量上来看并不显著，但是过高的 QPS 导致关键模块达到瓶颈。 - **解决方法**：首先从业务层面确定形成热点的 table，然后添加 `scatter-range-scheduler` 调度器使这个 table 的所有 Region 均匀分布。TiDB 也在其 HTTP API 中提供了相关接口来简化这个操作，具体可以参考 [TiDB HTTP API](https://github.com/pingcap/tidb/blob/master/docs/tidb_http_api.md) 文档。 + **解决方法**：首先从业务层面确定形成热点的 table，然后添加 `scatter-range-scheduler` 调度器使这个 table 的所有 Region 均匀分布。TiDB 也在其 HTTP API 中提供了相关接口来简化这个操作，具体可以参考 [TiDB HTTP API](https://github.com/pingcap/tidb/blob/release-8.5/docs/tidb_http_api.md) 文档。 ### Region Merge 速度慢 @@ -297,7 +297,9 @@ Region Merge 速度慢也很有可能是受到 limit 配置的限制（`merge-sc 实践中，如果能确定这个节点的故障是不可恢复的，可以立即做下线处理，这样 PD 能尽快补齐副本，降低数据丢失的风险。与之相对，如果确定这个节点是能恢复的，但可能半小时之内来不及，则可以把 `max-store-down-time` 临时调整为比较大的值，这样能避免超时之后产生不必要的副本补充，造成资源浪费。 -自 v5.2.0 起，TiKV 引入了慢节点检测机制。通过对 TiKV 中的请求进行采样，计算出一个范围在 1~100 的分数。当分数大于等于 80 时，该 TiKV 节点会被设置为 slow 状态。可以通过添加 [`evict-slow-store-scheduler`](/pd-control.md#scheduler-show--add--remove--pause--resume--config--describe) 来针对慢节点进行对应的检测和调度。当检测到有且只有一个 TiKV 节点为慢节点，并且该 TiKV 的 slow score 到达限定值（默认 80）时，将节点上的 Leader 驱逐（其作用类似于 `evict-leader-scheduler`）。 +自 v5.2.0 起，TiKV 引入了磁盘的慢节点检测机制。通过对 TiKV 中的请求进行采样，计算出一个范围在 1~100 的分数。当分数大于等于 80 时，该 TiKV 节点会被设置为 slow 状态。可以通过添加 [`evict-slow-store-scheduler`](/pd-control.md#scheduler-show--add--remove--pause--resume--config--describe) 来针对慢节点进行对应的调度。当检测到有且只有一个 TiKV 节点为慢节点，并且该 TiKV 的 slow score 到达限定值（默认 80）时，将节点上的 Leader 驱逐（其作用类似于 `evict-leader-scheduler`）。 + +自 v8.5.5 起，TiKV 引入了网络的慢节点检测机制。与磁盘慢节点检测类似，该机制通过在 TiKV 节点之间进行网络延时探测并计算分数，来判断节点的网络是否出现异常。可以通过 [`enable-network-slow-store`](/pd-control.md#scheduler-config-evict-slow-store-scheduler) 来开启该机制（默认关闭）。 > **注意：** > diff --git a/best-practices/readonly-nodes.md b/best-practices/readonly-nodes.md index c43f1fbb3093..5d857ccf01e0 100644 --- a/best-practices/readonly-nodes.md +++ b/best-practices/readonly-nodes.md @@ -1,6 +1,7 @@ --- title: 只读存储节点最佳实践 summary: 介绍如何通过使用只读存储节点，达到物理隔离部分流量的目的。 +aliases: ['/zh/tidb/stable/readonly-nodes/','/zh/tidb/dev/readonly-nodes/'] --- # 只读存储节点最佳实践 @@ -115,15 +116,7 @@ tikv_servers: set tidb_replica_read=learner; ``` -#### 3.2 在 TiSpark 中使用 Follower Read - -你可以在 Spark 配置文件中设置 `spark.tispark.replica_read = learner` 来读取只读节点上的数据： - -``` -spark.tispark.replica_read learner -``` - -#### 3.3 在备份集群数据时只备份 Follower 节点 +#### 3.2 在备份集群数据时只备份 Follower 节点 你可以在 br 命令行中添加 `--replica-read-label` 参数，来读取只读节点上的数据。注意，在 shell 中运行如下命令时需使用单引号包裹 label，以防止 `$` 被 shell 解析。 diff --git a/best-practices/saas-best-practices.md b/best-practices/saas-best-practices.md new file mode 100644 index 000000000000..59dcabc93ed8 --- /dev/null +++ b/best-practices/saas-best-practices.md @@ -0,0 +1,100 @@ +--- +title: SaaS 多租户场景下处理百万张表的最佳实践 +summary: 介绍 TiDB 在 SaaS (Software as a service) 多租户场景的最佳实践，特别适用于单集群表数量超过百万级别的场景。 +aliases: ['/zh/tidb/stable/saas-best-practices/','/zh/tidb/dev/saas-best-practices/'] +--- + +# SaaS 多租户场景下处理百万张表的最佳实践 + +本文档介绍 TiDB 在 SaaS (Software as a service) 多租户环境中的最佳实践，特别适用于**单集群表数量超过百万级别**的场景。通过合理的配置和选择，可以实现 TiDB 在 SaaS 场景下的高效稳定运行，同时降低资源消耗和成本。 + +> **注意：** +> +> 推荐使用 TiDB v8.5.0 及以上版本。 + +关于该最佳实践的实操案例，请参阅博客 [Scaling 3 Million Tables: How TiDB Powers Atlassian Forge's SaaS Platform](https://www.pingcap.com/blog/scaling-3-million-tables-how-tidb-powers-atlassian-forge-saas-platform/)。 + +## 硬件配置建议 + +建议使用高内存规格的 TiDB 实例，例如： + +- 100 万张表：使用 32 GiB 或更高内存。 +- 300 万张表：使用 64 GiB 或更高内存。 + +高内存规格的 TiDB 实例可以为 Infoschema、Statistics 和执行计划缓存分配更多的缓存空间，提高缓存命中率，从而提升业务性能。同时，更大的内存可以缓解 TiDB GC 带来的性能波动和稳定性问题。 + +TiKV 和 PD 推荐的硬件配置如下： + +* **TiKV**：8 vCPU 和 32 GiB 或更高内存。 +* **PD**：8 CPU 和 16 GiB 或更高内存。 + +## 控制 Region 数量 + +如果需要创建大量的表（例如 10 万张以上），建议将 TiDB 的配置 [`split-table`](/tidb-configuration-file.md#split-table) 设置为 `false`，减少集群 Region 数量，从而降低 TiKV 内存压力。 + +## 缓存配置 + +* 从 TiDB v8.4.0 开始，TiDB 在执行 SQL 语句时，会按需将 SQL 语句涉及的表信息加载到 Infoschema 缓存中。 + + * 通过 TiDB 监控中 **Schema Load** 面板下的 **Infoschema v2 Cache Size** 和 **Infoschema v2 Cache Operation** 子面板，可以查看 Infoschema 缓存的大小和命中率。 + * 使用系统变量 [`tidb_schema_cache_size`](/system-variables.md#tidb_schema_cache_size-从-v800-版本开始引入) 可以调整 Infoschema 缓存的内存上限，以满足业务需求。Infoschema 缓存大小与执行 SQL 语句涉及的不同表数量呈线性关系。在实际测试中，全量缓存 100 万张表（每张表含 4 列、1 个主键和 1 个索引）的元数据大约需要 2.4 GiB 内存。 + +* TiDB 在执行 SQL 语句时，也会按需将相关表的统计信息加载到 Statistics 缓存中。 + + * 通过 TiDB 监控中 **Statistics & Plan Management** 面板下的 **Stats Cache Cost** 和 **Stats Cache OPS** 子面板，可以查看 Statistics 缓存的使用情况。 + * 使用系统变量 [`tidb_stats_cache_mem_quota`](/system-variables.md#tidb_stats_cache_mem_quota-从-v610-版本开始引入) 可以调整 Statistics 缓存的内存上限，以满足业务需求。在实际测试中，执行 10 万张表的简单 SQL（使用 IndexRangeScan 操作符）时，Statistics 缓存大约消耗 3.96 GiB 内存。 + +## 统计信息收集 + +* 从 TiDB v8.4.0 开始，TiDB 引入了 [`tidb_auto_analyze_concurrency`](/system-variables.md#tidb_auto_analyze_concurrency-从-v840-版本开始引入) 系统变量，用来设置 TiDB 集群中自动更新统计信息操作的并发度。多表场景下，适当提升并发度可提高自动分析吞吐量。随着并发值的增加，自动分析的吞吐量和 TiDB Owner 节点的 CPU 使用率会线性增加。在实际测试中，使用并发度 16 时，每分钟可自动分析 320 张表（每张表有 1 万行数据、4 列和 1 个索引），占用 TiDB Owner 节点一个 CPU 核心。 +* [`tidb_auto_build_stats_concurrency`](/system-variables.md#tidb_auto_build_stats_concurrency-从-v650-版本开始引入) 和 [`tidb_build_sampling_stats_concurrency`](/system-variables.md#tidb_build_sampling_stats_concurrency-从-v750-版本开始引入) 影响 TiDB 统计信息构建的并发度，需根据具体场景调整： + - 分区表较多时，优先提高 `tidb_auto_build_stats_concurrency` 的值。 + - 列数较多时，优先提高 `tidb_build_sampling_stats_concurrency` 的值。 +* 建议确保 `tidb_auto_analyze_concurrency`、`tidb_auto_build_stats_concurrency` 和 `tidb_build_sampling_stats_concurrency` 三个变量的值的乘积不超过 TiDB CPU 核心数，避免过度占用资源。 + +## 系统表查询 + +在查询系统表时，建议添加 `TABLE_SCHEMA` 和 `TABLE_NAME` 或 `TIDB_TABLE_ID` 等过滤条件，以避免扫描大量无关数据，从而提高查询速度并降低资源消耗。 + +例如，在 300 万表的场景下： + +- 执行以下 SQL 语句要消耗约 8 GiB 内存： + + ```sql + SELECT COUNT(*) FROM information_schema.tables; + ``` + +- 执行以下 SQL 语句需要约 20 分钟： + + ```sql + SELECT COUNT(*) FROM information_schema.views; + ``` + +在以上示例中的两个 SQL 语句加上建议的查询条件之后，内存消耗可以忽略不计，查询耗时降至毫秒级别。 + +## 大量连接场景 + +在 SaaS 多租户场景中，通常每个用户连接到 TiDB 操作各自租户 (database) 的数据。为支持更多连接数，建议： + +* 调高 TiDB 的配置项 [`token-limit`](/tidb-configuration-file.md#token-limit)（默认值为 `1000`）以支持更多并发请求。 +* TiDB 内存使用量与连接数基本上呈线性关系。在实际测试中，20 万个空闲连接将使 TiDB 进程增加约 30 GiB 内存。建议根据实际连接数调整 TiDB 内存规格。 +* 使用 `PREPARED` 语句时，每个连接都会维护一个会话级的 Prepared Plan Cache。如果长时间未执行 `DEALLOCATE` 预编译语句，可能导致缓存中的计划数量过多，增加内存消耗。在实际测试中，40 万条涉及 IndexRangeScan 的执行计划占用约 5 GiB 内存。建议相应提高内存规格。 + +## Stale Read + +使用 [Stale Read](/stale-read.md) 时，如果使用的 schema 版本过于陈旧，可能触发历史 schema 全量加载，影响性能。建议通过提高 [`tidb_schema_version_cache_limit`](/system-variables.md#tidb_schema_version_cache_limit-从-v740-版本开始引入) 的值（例如 `255`）来缓解此问题。 + +## BR 备份恢复 + +* 在全量恢复百万张表的场景中，建议使用高内存 BR 实例。例如： + - 100 万张表：使用 32 GiB 或更高内存的 BR 实例 + - 300 万张表：使用 64 GiB 或更高内存的 BR 实例 +* BR 日志备份和快照恢复会额外消耗 TiKV 内存，建议 TiKV 使用 32 GiB 或更高规格的内存。 +* 可根据业务需求，适当增加 BR 的 [`pitr-batch-count` 和 `pitr-concurrency`](/br/br-pitr-manual.md#恢复到指定时间点-pitr) 配置以提升 BR 日志恢复速度。 + +## TiDB Lightning 数据导入 + +在使用 [TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md) 导入百万张表数据时，建议： + +- 对大表（超过 100 GiB）使用 TiDB Lightning [物理导入模式](/tidb-lightning/tidb-lightning-physical-import-mode.md)。 +- 对小表（通常数量较多）使用 TiDB Lightning [逻辑导入模式](/tidb-lightning/tidb-lightning-logical-import-mode.md)。 diff --git a/best-practices/three-dc-local-read.md b/best-practices/three-dc-local-read.md index 00209d00e2d6..5bde68135262 100644 --- a/best-practices/three-dc-local-read.md +++ b/best-practices/three-dc-local-read.md @@ -1,6 +1,7 @@ --- title: 在三数据中心下就近读取数据 summary: 了解通过 Stale Read 功能在三数据中心下就近读取数据，减少跨数据中心请求。 +aliases: ['/zh/tidb/stable/three-dc-local-read/','/zh/tidb/dev/three-dc-local-read/'] --- # 在三数据中心下就近读取数据 diff --git a/best-practices/three-nodes-hybrid-deployment.md b/best-practices/three-nodes-hybrid-deployment.md index 44cceebffbb3..b8a4646b3776 100644 --- a/best-practices/three-nodes-hybrid-deployment.md +++ b/best-practices/three-nodes-hybrid-deployment.md @@ -1,7 +1,7 @@ --- title: 三节点混合部署最佳实践 summary: 了解三节点混合部署最佳实践。 -aliases: ['/docs-cn/dev/best-practices/three-nodes-hybrid-deployment/'] +aliases: ['/docs-cn/dev/best-practices/three-nodes-hybrid-deployment/','/zh/tidb/stable/three-nodes-hybrid-deployment/','/zh/tidb/dev/three-nodes-hybrid-deployment/'] --- # 三节点混合部署的最佳实践 @@ -62,7 +62,7 @@ tikv: #### `server.grpc-concurrency` -该参数默认为 `4`。因为现有部署方案的 CPU 资源有限，实际请求数也不会很多。可以把该参数值调低，后续观察监控面板保持其使用率在 80% 以下即可。 +因为现有部署方案的 CPU 资源有限，实际请求数也不会很多，可以把 [`server.grpc-concurrency`](/tikv-configuration-file.md#grpc-concurrency) 参数值调低，后续观察监控面板保持其使用率在 80% 以下即可。 本次测试最后选择设置该参数值为 `2`，通过 **gRPC poll CPU** 面板观察，利用率正好在 80% 左右。 diff --git a/best-practices/tidb-best-practices.md b/best-practices/tidb-best-practices.md index 9bd160c060b0..9120c27b2af7 100644 --- a/best-practices/tidb-best-practices.md +++ b/best-practices/tidb-best-practices.md @@ -1,14 +1,14 @@ --- title: TiDB 最佳实践 -aliases: ['/docs-cn/dev/best-practices/tidb-best-practices/'] summary: TiDB 最佳实践总结了使用 TiDB 的一些优化技巧，包括 Raft 一致性协议、分布式事务、数据分片、负载均衡、SQL 到 KV 的映射方案、二级索引的实现方法等。建议阅读官方文档和知乎专栏了解更多细节。部署时推荐使用 TiUP，导入数据时可对 TiKV 参数进行调优。在写入和查询时需注意事务大小限制和并发度设置。监控系统和日志查看也是了解系统状态的重要方法。适用场景包括数据量大、不希望做 Sharding、需要事务和强一致性等。 +aliases: ['/zh/tidb/stable/tidb-best-practices/','/zh/tidb/dev/tidb-best-practices/','/docs-cn/dev/best-practices/tidb-best-practices/'] --- # TiDB 最佳实践 本文档总结使用 TiDB 时的一些最佳实践，主要涉及 SQL 使用和 OLAP/OLTP 优化技巧，特别是一些 TiDB 专有的优化开关。 -建议先阅读讲解 TiDB 原理的三篇文章（[讲存储](https://pingcap.com/blog-cn/tidb-internal-1/)，[说计算](https://pingcap.com/blog-cn/tidb-internal-2/)，[谈调度](https://pingcap.com/blog-cn/tidb-internal-3/)），再来看这篇文章。 +建议先阅读讲解 TiDB 原理的三篇文章（[讲存储](https://tidb.net/blog/dbe4f467)，[说计算](https://tidb.net/blog/8427565a)，[谈调度](https://tidb.net/blog/a558961f)），再来看这篇文章。 ## 前言 @@ -28,7 +28,7 @@ Raft 是一种一致性协议，能提供强一致的数据复制保证，TiDB ### 分布式事务 -TiDB 提供完整的分布式事务，事务模型是在 [Google Percolator](https://research.google.com/pubs/pub36726.html) 的基础上做了一些优化。具体的实现可以参考[《Percolator 和 TiDB 事务算法》](https://pingcap.com/blog-cn/percolator-and-txn/)这篇文章。本文档只讨论以下几点： +TiDB 提供完整的分布式事务，事务模型是在 [Google Percolator](https://research.google/pubs/large-scale-incremental-processing-using-distributed-transactions-and-notifications/) 的基础上做了一些优化。具体的实现可以参考[《Percolator 和 TiDB 事务算法》](https://tidb.net/blog/f537be2c)这篇文章。本文档只讨论以下几点： + 乐观锁 @@ -58,7 +58,7 @@ PD 会根据整个 TiKV 集群的状态，对集群的负载进行调度。调 ### SQL on KV -TiDB 自动将 SQL 结构映射为 KV 结构。具体的可以参考[《三篇文章了解 TiDB 技术内幕 - 说计算》](https://pingcap.com/blog-cn/tidb-internal-2/)这篇文档。简单来说，TiDB 执行了以下操作： +TiDB 自动将 SQL 结构映射为 KV 结构。具体的可以参考[《三篇文章了解 TiDB 技术内幕 - 说计算》](https://tidb.net/blog/8427565a)这篇文档。简单来说，TiDB 执行了以下操作： + 一行数据映射为一个 KV，Key 以 `TableID` 构造前缀，以行 ID 为后缀 + 一条索引映射为一个 KV，Key 以 `TableID+IndexID` 构造前缀，以索引值构造后缀 @@ -84,7 +84,7 @@ TiDB 支持完整的二级索引，并且是全局索引，很多查询可以通 + 通过索引查询和直接扫描 Table 的区别 - TiDB 实现了全局索引，所以索引和 Table 中的数据并不一定在一个数据分片上。通过索引查询的时候，需要先扫描索引，得到对应的行 ID，然后通过行 ID 去取数据，所以可能会涉及到两次网络请求，会有一定的性能开销。 + TiDB 实现了[全局索引](/global-indexes.md)，所以索引和 Table 中的数据并不一定在一个数据分片上。通过索引查询的时候，需要先扫描索引，得到对应的行 ID，然后通过行 ID 去取数据，所以可能会涉及到两次网络请求，会有一定的性能开销。 如果查询涉及到大量的行，那么扫描索引是并发进行，只要第一批结果已经返回，就可以开始去取 Table 的数据，所以这里是一个并行 + Pipeline 的模式，虽然有两次访问的开销，但是延迟并不会很大。 @@ -186,7 +186,7 @@ TiDB [使用 Grafana + Prometheus 监控系统状态](/tidb-monitoring-framework + 公众号：微信搜索 PingCAP + 知乎专栏：[TiDB 的后花园](https://zhuanlan.zhihu.com/newsql) -+ [官方博客](https://pingcap.com/blog-cn/) ++ [官方博客](https://tidb.net/blog) ## TiDB 的最佳适用场景 diff --git a/best-practices/uuid.md b/best-practices/uuid.md index ab4bd2e15984..a55ac82a700a 100644 --- a/best-practices/uuid.md +++ b/best-practices/uuid.md @@ -1,13 +1,16 @@ --- -title: UUID 最佳实践 -summary: 了解在 TiDB 中使用 UUID 的最佳实践和策略。 +title: 将 UUID 用作主键的最佳实践 +summary: 了解在 TiDB 中将 UUID 用作主键的最佳实践。 +aliases: ['/zh/tidb/stable/uuid/','/zh/tidb/dev/uuid/','/zh/tidbcloud/uuid/'] --- -# UUID 最佳实践 +# 将 UUID 用作主键的最佳实践 + +通用唯一标识符 (UUID) 是分布式数据库中常用的主键替代方案，相较于自增整数，它具有独特优势。本文将介绍在 TiDB 中使用 UUID 的优势，并提供高效存储和索引 UUID 的最佳实践。 ## UUID 概述 -通用唯一标识符 (UUID) 用作主键而不是 [`AUTO_INCREMENT`](/auto-increment.md) 整数值时，可以提供以下好处： +当用作主键时，UUID 相较于 [`AUTO_INCREMENT`](/auto-increment.md) 整数具有以下优势： - UUID 可以在多个系统生成，而不会产生冲突。某些情况下可以减少到 TiDB 的网络往返次数，从而提高性能。 - 绝大多数编程语言和数据库系统都支持 UUID。 @@ -15,6 +18,8 @@ summary: 了解在 TiDB 中使用 UUID 的最佳实践和策略。 ## 最佳实践 +本节介绍在 TiDB 中存储和索引 UUID 的最佳实践。 + ### 二进制存储 UUID 文本是一个包含 36 字符的字符串，如 `ab06f63e-8fe7-11ec-a514-5405db7aad56`。使用 [`UUID_TO_BIN()`](/functions-and-operators/miscellaneous-functions.md#uuid_to_bin) 可将 UUID 文本格式转换为 16 字节的二进制格式。这样，你可以将文本存储在 [`BINARY(16)`](/data-type-string.md#binary-类型) 列中。检索 UUID 时，可以使用 [`BIN_TO_UUID()`](/functions-and-operators/miscellaneous-functions.md#bin_to_uuid) 函数再将其转换回文本格式。 @@ -27,7 +32,7 @@ UUID 文本是一个包含 36 字符的字符串，如 `ab06f63e-8fe7-11ec-a514- 为了演示 `swap_flag` 的效果，本文以表结构相同的两张表为例。区别在于，`uuid_demo_1` 表中插入的数据使用 `UUID_TO_BIN(?, 0)`，而 `uuid_demo_2` 表中使用 `UUID_TO_BIN(?, 1)`。 -在如下的[流量可视化页面](/dashboard/dashboard-key-visualizer.md)，你可以看到写入操作集中在 `uuid_demo_2` 表的单个 Region 中，而这个表中的二进制格式字段顺序被调换过。 +在如下的[流量可视化页面](/dashboard/dashboard-key-visualizer.md) (Key Visualizer)，你可以看到写入操作集中在 `uuid_demo_2` 表的单个 Region 中，而这个表中的二进制格式字段顺序被调换过。 ![Key Visualizer](/media/best-practices/uuid_keyviz.png) @@ -47,6 +52,11 @@ CREATE TABLE `uuid_demo_2` ( ) ``` +关于流量可视化页面的更多信息，参见： + +- TiDB 的[流量可视化页面](/dashboard/dashboard-key-visualizer.md) +- TiDB Cloud 的[流量可视化页面](https://docs.pingcap.com/zh/tidbcloud/tune-performance/#key-visualizer) + ## 与 MySQL 兼容性 UUID 也可以在 MySQL 中使用。MySQL 8.0 引入了 `BIN_TO_UUID()` 和 `UUID_TO_BIN()` 函数。`UUID()` 函数在较早的 MySQL 版本中也可以使用。 diff --git a/binary-package.md b/binary-package.md index bbc355251a4a..faf4c3997c25 100644 --- a/binary-package.md +++ b/binary-package.md @@ -5,7 +5,7 @@ summary: 了解 TiDB 离线包及其包含的内容。 # TiDB 离线包 -在[使用 TiUP 离线部署 TiDB](/production-deployment-using-tiup.md#离线部署) 前，你需要在[官方下载页面](https://cn.pingcap.com/product-community/)选择对应版本的 TiDB server 离线镜像包（包含 TiUP 离线组件包）。 +在[使用 TiUP 离线部署 TiDB](/production-deployment-using-tiup.md#离线部署) 前，你需要在[软件下载中心](https://pingkai.cn/download#tidb-community)选择对应版本的 TiDB server 离线镜像包（包含 TiUP 离线组件包）。 TiDB 提供了 amd64 和 arm64 两种架构的离线包。对于每种架构，TiDB 提供了两个二进制离线包：`TiDB-community-server` 软件包和 `TiDB-community-toolkit` 软件包。 diff --git a/blocklist-control-plan.md b/blocklist-control-plan.md index f13e441ba527..b8a7de827137 100644 --- a/blocklist-control-plan.md +++ b/blocklist-control-plan.md @@ -1,7 +1,6 @@ --- title: 优化规则与表达式下推的黑名单 summary: 了解优化规则与表达式下推的黑名单。 -aliases: ['/docs-cn/dev/blacklist-control-plan/','/zh/tidb/dev/blacklist-control-plan'] --- # 优化规则与表达式下推的黑名单 diff --git a/br/backup-and-restore-overview.md b/br/backup-and-restore-overview.md index 4facc4de6482..6cb03507356e 100644 --- a/br/backup-and-restore-overview.md +++ b/br/backup-and-restore-overview.md @@ -1,7 +1,6 @@ --- title: TiDB 备份与恢复概述 summary: 了解不同场景下如何使用 TiDB 的备份与恢复功能，以及不同功能、版本间的兼容性。 -aliases: ['/docs-cn/dev/br/backup-and-restore-tool/','/docs-cn/dev/reference/tools/br/br/','/docs-cn/dev/how-to/maintain/backup-and-restore/br/','/zh/tidb/dev/backup-and-restore-tool/','/zh/tidb/dev/point-in-time-recovery/'] --- # TiDB 备份与恢复概述 @@ -17,15 +16,14 @@ TiDB 备份恢复功能可以用于满足以下业务的需求： ## 使用须知 -本部分介绍使用 TiDB 备份恢复功能前的注意事项，包括使用限制和使用建议。 +本部分介绍使用 TiDB 备份恢复功能前的注意事项，包括使用限制和使用建议。有关 BR 工具与其他功能或版本间的兼容性，请参考[兼容性](#兼容性)。 ### 使用限制 - PITR 仅支持恢复到**全新的空集群**。 -- PITR 仅支持集群粒度的恢复，不支持对单个 database 或 table 的恢复。 - PITR 不支持恢复系统表中用户表和权限表的数据。 - 不支持在一个集群上**同时**运行多个数据备份任务。 -- 不支持在一个集群上**同时**运行快照备份任务和数据恢复任务。 +- 不建议备份正在恢复的表，这样备份的数据可能存在异常。 - PITR 数据恢复任务运行期间，不支持同时运行日志备份任务，也不支持通过 TiCDC 同步数据到下游集群。 ### 使用建议 @@ -94,7 +92,7 @@ TiDB 备份恢复功能可以用于满足以下业务的需求： #### 恢复的性能 -- 恢复集群快照数据备份，速度可以达到单 TiKV 存储节点 100 MiB/s，恢复速度具有可扩展性。更详细说明请参考[恢复性能和影响](/br/br-snapshot-guide.md#快照恢复的性能与影响)。 +- 恢复集群快照数据备份，速度可以达到单 TiKV 存储节点 1 GiB/s，恢复速度具有可扩展性。更详细说明请参考[恢复性能和影响](/br/br-snapshot-guide.md#快照恢复的性能与影响)。 - 恢复日志备份数据，速度可以达到 30 GiB/h。更详细说明请参考 [PITR 的性能指标](/br/br-pitr-guide.md#pitr-的性能指标)。 ## 备份存储 @@ -119,8 +117,8 @@ TiDB 支持将数据备份到 Amazon S3、Google Cloud Storage (GCS)、Azure Blo | New collation | [#352](https://github.com/pingcap/br/issues/352) | 确保恢复时集群的 `mysql.tidb` 表中 `new_collation_enabled` 变量值和备份时的一致，否则会导致数据索引不一致和 checksum 通不过。更多信息，请参考 [FAQ - BR 为什么会报 `new_collations_enabled_on_first_bootstrap` 不匹配？](/faq/backup-and-restore-faq.md#恢复时为什么会报-new_collation_enabled-不匹配)。 | | 全局临时表 | | 确保使用 BR v5.3.0 及以上版本进行备份和恢复，否则会导致全局临时表的表定义错误。 | | TiDB Lightning 物理导入模式| |上游数据库使用 TiDB Lightning 物理导入模式导入的数据，无法作为数据日志备份下来。推荐在数据导入后执行一次全量备份，细节参考[上游数据库使用 TiDB Lightning 物理导入模式导入数据的恢复](/faq/backup-and-restore-faq.md#上游数据库使用-tidb-lightning-物理导入模式导入数据时为什么无法使用日志备份功能)。| -| TiCDC | | BR v8.2.0 及以上版本：如果在恢复的目标集群有 [CheckpointTS](/ticdc/ticdc-architecture.md#checkpointts) 早于 BackupTS 的 Changefeed，BR 会拒绝执行恢复。BR v8.2.0 之前的版本：如果在恢复的目标集群有任何活跃的 TiCDC Changefeed，BR 会拒绝执行恢复。 | -| 向量搜索 | | 确保使用 BR v8.4.0 及以上版本进行备份与恢复。不支持将带有[向量数据类型](/vector-search-data-types.md)的表恢复至 v8.4.0 之前的 TiDB 集群。 | +| TiCDC | | BR v8.2.0 及以上版本：如果在恢复的目标集群有 [CheckpointTS](/ticdc/ticdc-classic-architecture.md#checkpointts) 早于 BackupTS 的 Changefeed，BR 会拒绝执行恢复。BR v8.2.0 之前的版本：如果在恢复的目标集群有任何活跃的 TiCDC Changefeed，BR 会拒绝执行恢复。 | +| 向量搜索 | | 确保使用 BR v8.4.0 及以上版本进行备份与恢复。不支持将带有[向量数据类型](/ai/reference/vector-search-data-types.md)的表恢复至 v8.4.0 之前的 TiDB 集群。 | ### 版本间兼容性 @@ -132,6 +130,8 @@ TiDB 支持将数据备份到 Amazon S3、Google Cloud Storage (GCS)、Azure Blo 从 v7.0.0 开始，TiDB 逐步支持通过 SQL 语句来执行备份和恢复操作。因此，强烈建议在备份和恢复集群时使用与 TiDB 集群相同大版本的 BR 工具，并避免跨大版本进行数据备份和恢复操作。这有助于确保恢复操作的顺利执行和数据的一致性。特别是从 v7.6.0 起，BR 默认支持在恢复数据的同时恢复 `mysql` 库下的系统表，即恢复时默认配置为 `--with-sys-table=true`。在跨版本进行数据恢复时，如果遇到 `mysql` 库的系统表结构不同导致类似 `[BR:Restore:ErrRestoreIncompatibleSys]incompatible system table` 异常，你可以通过设置 `--with-sys-table=false` 跳过恢复系统表以规避该问题。 +#### TiDB v6.6.0 版本之前的 BR 版本兼容性矩阵 + TiDB v6.6.0 版本之前的 BR 版本兼容性矩阵： | 备份版本（纵向）\ 恢复版本（横向） | 恢复到 TiDB v6.0 | 恢复到 TiDB v6.1| 恢复到 TiDB v6.2 | 恢复到 TiDB v6.3、v6.4 或 v6.5 | 恢复到 TiDB v6.6 | @@ -139,6 +139,41 @@ TiDB v6.6.0 版本之前的 BR 版本兼容性矩阵： | TiDB v6.0、v6.1、v6.2、v6.3、v6.4 或 v6.5 快照备份 | 兼容（已知问题，如果备份数据中包含空库可能导致报错，参考 [#36379](https://github.com/pingcap/tidb/issues/36379)） | 兼容 | 兼容 | 兼容 | 兼容（需使用 v6.6 的 BR） | | TiDB v6.3、v6.4、v6.5 或 v6.6 日志备份| 不兼容 | 不兼容 | 不兼容 | 兼容 | 兼容 | +#### TiDB v6.5.0 版本到 v8.5.0 之间的 BR 版本兼容性矩阵 + +本节列出了 TiDB v6.5.0 版本到 v8.5.0 之间所有[长期支持版本 (LTS)](/releases/versioning.md#长期支持版本)（包括 v6.5.0、v7.1.0、v7.5.0、v8.1.0、v8.5.0）的 BR 兼容性矩阵。这个矩阵中的 BR 版本与对应的 TiDB Server 的大版本一致。 + +> **注意：** +> +> - 已知问题：从 v7.2.0 开始，新建集群的部分系统表字段变为大小写不敏感。然而，对于从 v7.2.0 之前的版本**在线升级**到 v7.2.0 及以上版本的集群，对应的系统表字段仍然大小写敏感。如果在这两类集群之间进行包含系统表的备份和恢复操作，可能会失败。详情参见 [Issue #43717](https://github.com/pingcap/tidb/issues/43717)。 +> - 从 v8.5.5 起，BR 在恢复系统表时支持通过参数 `--sys-check-collation` 检查排序规则 (Collation) 兼容性。在恢复过程中，BR 会验证系统表数据在目标集群排序规则下是否存在大小写冲突。如果数据在目标序规则下兼容，则可以成功恢复旧版本备份。否则，BR 会报错并终止恢复。 + +下表列出了全量备份的兼容性矩阵，表格中所有信息均适用于新建集群。如果备份集群是从 v7.2.0 之前升级过来的集群，行为等同于 v7.1.0： + +| 备份集群版本 | 兼容的恢复目标集群版本 | 不兼容的恢复目标集群版本 | +|:--|:--|:--| +| v6.5.0 | v7.1.0 | v7.5.0 及以上 | +| v7.1.0 | - | v7.5.0 及以上 | +| v7.5.0 | v7.5.0 及以上 | - | +| v8.1.0 | v8.1.0 及以上 | - | +| v8.5.0 | v8.5.0 及以上 | - | + +下表列出了日志备份的兼容性矩阵，表格中所有信息均适用于新建集群。如果备份集群是从 v7.2.0 之前升级过来的集群，行为等同于 v7.1.0： + +| 备份集群版本 | 兼容的恢复目标集群版本 | 不兼容的恢复目标集群版本 | +|:--|:--|:--| +| v6.5.0 | v7.1.0 | v7.5.0 及以上 | +| v7.1.0 | - | v7.5.0 及以上 | +| v7.5.0 | v7.5.0 及以上 | - | +| v8.1.0 | v8.1.0 及以上 | - | +| v8.5.0 | v8.5.0 及以上 | - | + +> **注意：** +> +> - 当仅备份非系统表的业务数据时（全量备份或日志备份），所有版本之间均兼容。 +> - 在恢复 `mysql` 系统表时，可能会出现不兼容情况。为避免此问题，你可以通过设置 `--with-sys-table=false` 跳过恢复所有系统表，或者使用更精细的过滤器仅仅跳过不兼容的系统表，例如：`--filter '*.*' --filter "__TiDB_BR_Temporary_*.*" --filter '!mysql.*' --filter 'mysql.bind_info' --filter 'mysql.user' --filter 'mysql.global_priv' --filter 'mysql.global_grants' --filter 'mysql.default_roles' --filter 'mysql.role_edges' --filter '!sys.*' --filter '!INFORMATION_SCHEMA.*' --filter '!PERFORMANCE_SCHEMA.*' --filter '!METRICS_SCHEMA.*' --filter '!INSPECTION_SCHEMA.*'`。 +> - "-" 表示该版本在对应场景下没有兼容性限制。 + ## 探索更多 - [TiDB 快照备份与恢复使用指南](/br/br-snapshot-guide.md) diff --git a/br/backup-and-restore-storages.md b/br/backup-and-restore-storages.md index 177e280d175f..db456a6db067 100644 --- a/br/backup-and-restore-storages.md +++ b/br/backup-and-restore-storages.md @@ -1,7 +1,6 @@ --- title: 备份存储 summary: 了解 BR 支持的备份存储服务的 URI 格式、鉴权方案和使用方式。 -aliases: ['/docs-cn/dev/br/backup-and-restore-storages/','/zh/tidb/dev/backup-storage-S3/','/zh/tidb/dev/backup-storage-azblob/','/zh/tidb/dev/backup-storage-gcs/','/zh/tidb/dev/external-storage/'] --- # 备份存储 @@ -203,6 +202,66 @@ tiup br restore db --db test -u "${PD_IP}:2379" \ --storage "azure://external/backup-20220915?account-name=${account-name}" ``` +- 方式四：使用 Azure 托管标识 (Managed Identity) + + 从 v8.5.5 起，如果你的 TiDB 集群和 br 命令行工具运行在 Azure 虚拟机 (VM) 或 Azure Kubernetes Service (AKS) 环境中，并且已为节点分配了 Azure 托管标识，则可以使用 Azure 托管标识进行鉴权。 + + 使用此方式前，请确保已在 [Azure Portal](https://azure.microsoft.com/) 中为对应的托管标识授予目标存储账户的访问权限（如 `Storage Blob Data Contributor`）。 + + - **系统分配的托管标识 (System-assigned)**： + + 使用系统分配的托管标识时，无需配置任何 Azure 相关环境变量，直接运行 br 备份命令即可。 + + ```shell + tiup br backup full -u "${PD_IP}:2379" \ + --storage "azure://external/backup-20220915?account-name=${account-name}" + ``` + + > **注意：** + > + > 请确保运行环境中**不存在** `AZURE_CLIENT_ID`、`AZURE_TENANT_ID` 或 `AZURE_CLIENT_SECRET` 环境变量，否则 Azure SDK 可能会优先使用其他认证方式，导致托管标识未生效。 + + - **用户分配的托管标识 (User-assigned)**： + + 使用用户分配的托管标识时，需要在 TiKV 运行环境和 br 命令行工具运行环境中配置环境变量 `AZURE_CLIENT_ID` （其值为该托管标识的 Client ID），然后再执行 br 备份命令。具体步骤如下： + + 1. 使用 TiUP 启动时为 TiKV 配置 Client ID： + + 以下步骤以 TiKV 端口 `24000`、systemd 服务名 `tikv-24000` 为例： + + 1. 执行以下命令进入服务配置编辑界面： + + ```shell + systemctl edit tikv-24000 + ``` + + 2. 配置 `AZURE_CLIENT_ID` 环境变量： + + ```ini + [Service] + Environment="AZURE_CLIENT_ID=" + ``` + + 3. 重新加载 systemd 配置并重启 TiKV： + + ```shell + systemctl daemon-reload + systemctl restart tikv-24000 + ``` + + 2. 为 br 命令行工具配置 `AZURE_CLIENT_ID` 环境变量： + + ```shell + export AZURE_CLIENT_ID="" + ``` + + 3. 使用 br 命令行工具将数据备份至 Azure Blob Storage： + + ```shell + tiup br backup full -u "${PD_IP}:2379" \ + --storage "azure://external/backup-20220915?account-name=${account-name}" + ``` +
@@ -218,7 +277,7 @@ TiDB 备份恢复功能支持对备份到 Azure Blob Storage 的数据设置 Azu ## 存储服务其他功能支持 -Amazon [S3 对象锁定](https://docs.aws.amazon.com/zh_cn/AmazonS3/latest/userguide/object-lock.html) 功能支持用户通过设置数据留存期，有效防止备份数据在指定时间内被意外或故意删除，提升了数据的安全性和完整性。从 v6.3.0 起，BR 为快照备份引入了对 Amazon S3 对象锁定功能的支持，为全量备份增加了额外的安全性保障。从 v8.0.0 起，PITR 也引入了对 Amazon S3 对象锁定功能的支持，无论是全量备份还是日志数据备份，都可以通过对象锁定功能提供更可靠的数据保护，进一步加强了数据备份和恢复的安全性，并满足了监管方面的需求。 +Amazon [S3 对象锁定](https://docs.aws.amazon.com/zh_cn/AmazonS3/latest/userguide/object-lock.html)功能支持用户通过设置数据留存期，有效防止备份数据在指定时间内被意外或故意删除，提升了数据的安全性和完整性。从 v6.3.0 起，BR 为快照备份引入了对 Amazon S3 对象锁定功能的支持，为全量备份增加了额外的安全性保障。从 v8.0.0 起，PITR 也引入了对 Amazon S3 对象锁定功能的支持，无论是全量备份还是日志数据备份，都可以通过对象锁定功能提供更可靠的数据保护，进一步加强了数据备份和恢复的安全性，并满足了监管方面的需求。 BR 和 PITR 将自动检测 Amazon S3 对象锁定功能的开启或关闭状态，你无需进行任何额外的操作。 diff --git a/br/backup-and-restore-use-cases.md b/br/backup-and-restore-use-cases.md index b0717afcf407..5112ce4c7050 100644 --- a/br/backup-and-restore-use-cases.md +++ b/br/backup-and-restore-use-cases.md @@ -1,7 +1,6 @@ --- title: TiDB 备份与恢复实践示例 summary: 介绍 TiDB 备份与恢复的具体使用示例，包括推荐环境配置、存储配置、备份策略及如何进行备份与恢复。 -aliases: ['/docs-cn/dev/br/backup-and-restore-use-cases/','/docs-cn/dev/reference/tools/br/use-cases/','/docs-cn/dev/how-to/maintain/backup-and-restore/br-best-practices/','/docs-cn/dev/reference/tools/br/br-best-practices/','/zh/tidb/dev/backup-and-restore-use-cases-for-maintain/'] --- # TiDB 备份与恢复实践示例 @@ -17,7 +16,7 @@ aliases: ['/docs-cn/dev/br/backup-and-restore-use-cases/','/docs-cn/dev/referenc ## 部署 TiDB 集群和 br 命令行工具 -使用 PITR 功能，需要部署 v6.2.0 或以上版本的 TiDB 集群，并且更新 br 命令行工具到与 TiDB 集群相同的版本，本文假设使用的是 v8.4.0 版本。 +使用 PITR 功能，需要部署 v6.2.0 或以上版本的 TiDB 集群，并且更新 br 命令行工具到与 TiDB 集群相同的版本，本文假设使用的是 v{{{ .tidb-version }}} 版本。 下表介绍了在 TiDB 集群中使用日志备份功能的推荐配置。 @@ -44,13 +43,13 @@ aliases: ['/docs-cn/dev/br/backup-and-restore-use-cases/','/docs-cn/dev/referenc - 安装： ```shell - tiup install br:v8.4.0 + tiup install br:v{{{ .tidb-version }}} ``` - 升级： ```shell - tiup update br:v8.4.0 + tiup update br:v{{{ .tidb-version }}} ``` ## 配置备份存储 (Amazon S3) @@ -141,7 +140,9 @@ tiup br restore point --pd="${PD_IP}:2379" \ --full-backup-storage='s3://tidb-pitr-bucket/backup-data/snapshot-20220514000000' \ --restored-ts '2022-05-15 18:00:00+0800' -Full Restore <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% +Split&Scatter Region <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% +Download&Ingest SST <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% +Restore Pipeline <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% [2022/05/29 18:15:39.132 +08:00] [INFO] [collector.go:69] ["Full Restore success summary"] [total-ranges=12] [ranges-succeed=xxx] [ranges-failed=0] [split-region=xxx.xxxµs] [restore-ranges=xxx] [total-take=xxx.xxxs] [restore-data-size(after-compressed)=xxx.xxx] [Size=xxxx] [BackupTS={TS}] [total-kv=xxx] [total-kv-size=xxx] [average-speed=xxx] Restore Meta Files <--------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% Restore KV Files <----------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% diff --git a/br/br-checkpoint-backup.md b/br/br-checkpoint-backup.md index 22f50c3071a2..c98059a377a6 100644 --- a/br/br-checkpoint-backup.md +++ b/br/br-checkpoint-backup.md @@ -1,7 +1,6 @@ --- title: 断点备份 summary: 了解断点备份功能，包括它的使用场景、实现原理以及使用方法。 -aliases: ["/zh/tidb/dev/br-checkpoint"] --- # 断点备份 diff --git a/br/br-checkpoint-restore.md b/br/br-checkpoint-restore.md index 691b119e7022..40427d85216b 100644 --- a/br/br-checkpoint-restore.md +++ b/br/br-checkpoint-restore.md @@ -15,7 +15,7 @@ summary: 了解断点恢复功能，包括它的使用场景、实现原理以 ## 实现原理 -断点恢复的实现原理分为快照恢复和日志恢复两部分。具体实现细节请参考[实现细节](#实现细节)。 +断点恢复的实现原理分为快照恢复和日志恢复两部分。具体实现细节请参考[实现细节：将断点数据存储在下游集群](#实现细节将断点数据存储在下游集群)和[实现细节：将断点数据存储在外部存储](#实现细节将断点数据存储在外部存储)。 ### 快照恢复 @@ -61,7 +61,15 @@ br 工具暂停 GC 的原理是通过执行 `SET config tikv gc.ratio-threshold 在恢复失败后，请避免向集群写入或删除数据、删除或创建表。由于备份数据中可能包含重命名表的 DDL 操作，断点恢复无法确认被删除的表或已存在的表是否是外部操作引起的，这会影响下次重试恢复的准确性。 -## 实现细节 +### 不建议跨大版本重新恢复 + +不建议进行跨大版本的断点恢复操作。对于使用 v8.5.0 之前长期支持 (Long-Term Support, LTS) 版本 br 恢复失败的集群，无法通过 v8.5.0 或更新的 LTS 版本 br 继续恢复，反之亦然。 + +## 实现细节：将断点数据存储在下游集群 + +> **注意：** +> +> 从 v8.5.5 开始，默认将断点数据存储在下游集群。你可以通过参数 `--checkpoint-storage` 来指定断点数据存储的外部存储。 断点恢复的具体操作细节分为快照恢复和 PITR 恢复两部分。 @@ -77,8 +85,78 @@ br 工具暂停 GC 的原理是通过执行 `SET config tikv gc.ratio-threshold [PITR (Point-in-time recovery)](/br/br-pitr-guide.md) 恢复分为快照恢复和日志恢复两个阶段。 -在第一次执行恢复时，br 工具首先进入快照恢复阶段。该阶段与上述只进行[快照恢复](#快照恢复-1)操作相同，断点数据，以及备份数据的上游集群的 ID 和备份数据的 BackupTS（即日志恢复的起始时间点 `start-ts`）会被记录到 `__TiDB_BR_Temporary_Snapshot_Restore_Checkpoint` 数据库中。如果在此阶段恢复失败，尝试继续断点恢复时无法再调整日志恢复的起始时间点 `start-ts`。 +在第一次执行恢复时，br 工具首先进入快照恢复阶段。断点数据、备份数据的上游集群的 ID、备份数据的 BackupTS（即日志恢复的起始时间点 `start-ts`）和 PITR 恢复的 `restored-ts` 会被记录到 `__TiDB_BR_Temporary_Snapshot_Restore_Checkpoint` 数据库中。如果在此阶段恢复失败，尝试继续断点恢复时无法再调整日志恢复的起始时间点 `start-ts` 和 `restored-ts`。 在第一次执行恢复并且进入日志恢复阶段时，br 工具会在恢复集群中创建 `__TiDB_BR_Temporary_Log_Restore_Checkpoint` 数据库，用于记录断点数据，以及这次恢复的上游集群 ID 和恢复的时间范围 `start-ts` 与 `restored-ts`。如果在此阶段恢复失败，重新执行恢复命令时，你需要指定与断点记录相同的 `start-ts` 和 `restored-ts` 参数，否则 br 工具会报错，并提示上游集群 ID 或恢复的时间范围与断点记录不同。如果恢复集群已被清理，你可以手动删除 `__TiDB_BR_Temporary_Log_Restore_Checkpoint` 数据库，然后使用其他备份重试。 -在第一次执行恢复并且进入日志恢复阶段前，br 工具会构造出在 `restored-ts` 时间点的上下游集群库表 ID 映射关系，并将其持久化到系统表 `mysql.tidb_pitr_id_map` 中，以避免库表 ID 被重复分配。如果删除 `mysql.tidb_pitr_id_map` 中的数据，可能会导致 PITR 恢复数据不一致。 +注意在第一次执行恢复并且进入日志恢复阶段前，br 工具会构造出在 `restored-ts` 时间点的上下游集群库表 ID 映射关系，并将其持久化到系统表 `mysql.tidb_pitr_id_map` 中，以避免库表 ID 被重复分配。**如果随意删除 `mysql.tidb_pitr_id_map` 中的数据，可能会导致 PITR 恢复数据不一致。** + +> **注意：** +> +> 为了兼容旧版本集群，从 v8.5.5 开始，当恢复集群不存在系统表 `mysql.tidb_pitr_id_map` 时，`pitr_id_map` 数据会写到日志备份目录下，文件名为 `pitr_id_maps/pitr_id_map.cluster_id:{downstream-cluster-ID}.restored_ts:{restored-ts}`。 + +## 实现细节：将断点数据存储在外部存储 + +> **注意：** +> +> 从 v8.5.5 开始，默认将断点数据存储在下游集群。你可以通过参数 `--checkpoint-storage` 来指定断点数据存储的外部存储。例如： +> +> ```shell +> ./br restore full -s "s3://backup-bucket/backup-prefix" --checkpoint-storage "s3://temp-bucket/checkpoints" +> ``` + +在外部存储中，断点数据的目录结构如下： + +- 主路径 `restore-{downstream-cluster-ID}` 中的下游集群 ID `{downstream-cluster-ID}` 用于区分不同的恢复集群 +- 路径 `restore-{downstream-cluster-ID}/log` 存储日志恢复阶段的日志文件断点数据 +- 路径 `restore-{downstream-cluster-ID}/sst` 存储日志恢复阶段中未被日志备份覆盖的 SST 文件的断点数据 +- 路径 `restore-{downstream-cluster-ID}/snapshot` 存储快照恢复阶段的断点数据 + +``` +. +`-- restore-{downstream-cluster-ID} + |-- log + | |-- checkpoint.meta + | |-- data + | | |-- {uuid}.cpt + | | |-- {uuid}.cpt + | | `-- {uuid}.cpt + | |-- ingest_index.meta + | `-- progress.meta + |-- snapshot + | |-- checkpoint.meta + | |-- checksum + | | |-- {uuid}.cpt + | | |-- {uuid}.cpt + | | `-- {uuid}.cpt + | `-- data + | |-- {uuid}.cpt + | |-- {uuid}.cpt + | `-- {uuid}.cpt + `-- sst + `-- checkpoint.meta +``` + +断点恢复的具体操作细节分为快照恢复和 PITR 恢复两部分。 + +### 快照恢复 + +在第一次执行恢复时，br 工具会在恢复集群中创建路径 `restore-{downstream-cluster-ID}/snapshot`，用于记录断点数据，以及这次恢复的上游集群 ID 和备份的 BackupTS。 + +如果恢复执行失败，你可以使用相同的命令再次执行恢复，br 工具会从指定的存储断点数据的外部存储中读取断点信息，并从上次中断的位置继续恢复。 + +当恢复执行失败后，如果你尝试将与断点记录不同的备份数据恢复到同一集群，br 工具会报错，并提示上游集群 ID 或 BackupTS 与断点记录不同。如果恢复集群已被清理，你可以手动删除存储在外部存储的断点数据或更换指定的断点数据存储路径，然后使用其他备份重试。 + +### PITR 恢复 + +[PITR (Point-in-time recovery)](/br/br-pitr-guide.md) 恢复分为快照恢复和日志恢复两个阶段。 + +在第一次执行恢复时，br 工具首先进入快照恢复阶段。断点数据，以及备份数据的上游集群的 ID、备份数据的 BackupTS（即日志恢复的起始时间点 `start-ts`）和 PITR 恢复的 `restored-ts` 会被记录到路径 `restore-{downstream-cluster-ID}/snapshot` 中。如果在此阶段恢复失败，尝试继续断点恢复时无法再调整日志恢复的起始时间点 `start-ts` 和 `restored-ts`。 + +在第一次执行恢复并且进入日志恢复阶段时，br 工具会在恢复集群中创建路径 `restore-{downstream-cluster-ID}/log`，用于记录断点数据，以及这次恢复的上游集群 ID 和恢复的时间范围 `start-ts` 与 `restored-ts`。如果在此阶段恢复失败，重新执行恢复命令时，你需要指定与断点记录相同的 `start-ts` 和 `restored-ts` 参数，否则 br 工具会报错，并提示上游集群 ID 或恢复的时间范围与断点记录不同。如果恢复集群已被清理，你可以手动删除 存储在外部存储的断点数据或更换指定的断点数据存储路径，然后使用其他备份重试。 + +注意在第一次执行恢复并且进入日志恢复阶段前，br 工具会构造出在 `restored-ts` 时间点的上下游集群库表 ID 映射关系，并将其持久化到存放断点数据的外部存储中（文件名为 `pitr_id_maps/pitr_id_map.cluster_id:{downstream-cluster-ID}.restored_ts:{restored-ts}`），以避免库表 ID 被重复分配。**如果随意删除 `pitr_id_maps` 目录中的文件，可能会导致 PITR 恢复数据不一致。** + +> **注意：** +> +> 为了兼容旧版本集群，从 v8.5.5 开始，当恢复集群不存在系统表 `mysql.tidb_pitr_id_map` 且未指定参数 `--checkpoint-storage` 时，`pitr_id_map` 数据会写到日志备份目录下，文件名为 `pitr_id_maps/pitr_id_map.cluster_id:{downstream-cluster-ID}.restored_ts:{restored-ts}`。 diff --git a/br/br-compact-log-backup.md b/br/br-compact-log-backup.md new file mode 100644 index 000000000000..3f6f2efe02c3 --- /dev/null +++ b/br/br-compact-log-backup.md @@ -0,0 +1,85 @@ +--- +title: 压缩日志备份 +summary: 了解如何通过压缩日志备份为 SST 格式来提升按时间点恢复 (Point-in-time recovery, PITR) 的效率。 +--- + +# 压缩日志备份 + +本文介绍如何通过压缩日志备份 (Compact Log Backup) 为 [SST](/glossary.md#static-sorted-table--sorted-string-table-sst) 格式来提升按时间点恢复 (Point-in-time recovery, [PITR](/glossary.md#point-in-time-recovery-pitr)) 的效率。 + +## 功能概述 + +传统日志备份以一种高度非结构化的方式存储写入操作，可能导致以下问题： + +- 恢复性能下降：无序数据需通过 Raft 协议逐条写入集群。 +- 写放大：所有写入必须从 LSM Tree 的 L0 开始被逐级别 compact 到底层。 +- 全量备份依赖：需频繁执行全量备份以控制恢复数据量，对业务有一定影响。 + +从 v8.5.5 开始，压缩日志备份功能提供了离线压缩能力，可将日志备份的非结构化数据转换为结构化的 SST 文件，从而实现以下改进： + +- SST 可以被快速导入集群，从而提升恢复性能。 +- 压缩过程中消除重复记录，从而减少空间消耗。 +- 在确保 RTO (Recovery Time Objective) 的前提下允许用户设置更长的全量备份间隔，从而降低对业务的影响。 + +## 使用限制 + +- 压缩日志备份并不是全量备份的替代方案，需与定期全量备份配合使用。为了保证能进行 PITR，日志备份的压缩过程会保留所有 MVCC 版本，长期不进行全量备份将导致存储膨胀并且可能在未来恢复时遇到问题。 +- 目前不支持压缩启用了 Local Encryption 的备份。 + +## 使用方法 + +目前仅支持手动压缩日志备份，流程较为复杂。**建议在生产中使用后续发布的 TiDB Operator 方案来压缩日志备份**。 + +### 手动压缩 + +本节介绍手动压缩日志备份的操作步骤。 + +#### 前提条件 + +手动压缩日志备份需要两个工具：`tikv-ctl` 和 `br`。 + +#### 第 1 步：将存储编码为 Base64 + +执行以下编码命令： + +```shell +br operator base64ify --storage "s3://your/log/backup/storage/here" --load-creds +``` + +> **注意：** +> +> - 如果执行以上命令时带了 `--load-cerds` 这个选项，编码出来的 Base64 中会包含从 BR 当前环境中加载的密钥信息，请注意安全保护和权限管控。 +> - 此处的 `--storage` 值应该和日志备份任务的 `log status` 命令输出的 storage 相同。 + +#### 第 2 步：执行日志压缩 + +有了存储的 Base64 之后，你可以执行以下命令通过 `tikv-ctl` 发起压缩，注意 `tikv-ctl` 默认日志等级为 `warning`，启用 `--log-level info` 来获得更多信息： + +```shell +tikv-ctl --log-level info compact-log-backup \ + --from "" --until "" \ + -s 'bAsE64==' -N 8 +``` + +参数解释如下： + +- `-s`：已获得的存储的 Base64。 +- `-N`：最大并发压缩日志任务的数量。 +- `--from`：压缩开始的时间戳。 +- `--until`：压缩结束的时间戳。 + +`--from` 和 `--until` 这对参数指定了压缩操作的时间范围。压缩操作将处理所有包含指定时间范围内任意写入的日志文件，因此最终生成的 SST 文件可能包含该范围外的写入数据。 + +要获取某个特定时间点的时间戳，请执行以下命令： + +```shell +echo $(( $(date --date '2004-05-06 15:02:01Z' +%s%3N) << 18 )) +``` + +> **注意：** +> +> 如果你是 macOS 用户，需要先使用 Homebrew 安装 `coreutils`，并且使用 `gdate` 而非 `date`。 +> +> ```shell +> echo $(( $(gdate --date '2004-05-06 15:02:01Z' +%s%3N) << 18 )) +> ``` diff --git a/br/br-log-architecture.md b/br/br-log-architecture.md index 9e3eed959724..a25990fa073b 100644 --- a/br/br-log-architecture.md +++ b/br/br-log-architecture.md @@ -87,9 +87,9 @@ PITR 的流程如下： 日志备份会产生如下类型文件： -- `{min_ts}-{uuid}.log` 文件：存储备份下来的 kv 数据变更记录。其中 `{min_ts}` 是该文件中所有 kv 数据变更记录数对应的最小 ts；`{uuid}` 是生成该文件的时候随机生成的。 -- `{checkpoint_ts}-{uuid}.meta` 文件：每个 TiKV 节点每次上传日志备份数据时会生成一个该文件，保存本次上传的所有日志备份数据文件。其中 `{checkpoint_ts}` 是本节点的日志备份的 checkpoint，所有 TiKV 节点的最小的 checkpoint 就是日志备份任务最新的 checkpoint；`{uuid}` 是生成该文件的时候随机生成的。 +- `{flushTs}-{minDefaultTs}-{minTs}-{maxTs}.meta` 文件：每个 TiKV 节点每次上传日志备份数据时会生成一个该文件，保存本次上传的所有日志备份数据文件。文件名中的字段含义请参考[备份文件目录结构](#备份文件目录结构)。 - `{store_id}.ts` 文件：每个 TiKV 节点每次上传日志备份数据时会使用 global checkpoint ts 更新该文件。其中 `{store_id}` 是 TiKV 的 store ID。 +- `{min_ts}-{uuid}.log` 文件：存储备份下来的 kv 数据变更记录。其中 `{min_ts}` 是该文件中所有 kv 数据变更记录数对应的最小 ts；`{uuid}` 是在生成该文件时随机生成的。 - `v1_stream_truncate_safepoint.txt` 文件：保存最近一次通过 `br log truncate` 删除日志备份数据后，存储中最早的日志备份数据对应的 ts。 ### 备份文件目录结构 @@ -98,45 +98,57 @@ PITR 的流程如下： . ├── v1 │   ├── backupmeta -│   │   ├── {min_restored_ts}-{uuid}.meta -│   │   ├── {checkpoint}-{uuid}.meta +│   │   ├── ... +│   │   └── {flushTs}-{minDefaultTs}-{minTs}-{maxTs}.meta │   ├── global_checkpoint -│   │   ├── {store_id}.ts -│   ├── {date} -│   │   ├── {hour} -│   │   │   ├── {store_id} -│   │   │   │   ├── {min_ts}-{uuid}.log -│   │   │   │   ├── {min_ts}-{uuid}.log -├── v1_stream_truncate_safepoint.txt +│   │   └── {store_id}.ts +│   └── {date} +│      └── {hour} +│         └── {store_id} +│            ├── ... +│            └── {min_ts}-{uuid}.log +└── v1_stream_truncate_safepoint.txt ``` +备份文件目录结构的说明如下： + +- `backupmeta` 目录：存储备份的元数据文件。从 v8.5.3 起，该文件命名格式从 `{resolved_ts}-{uuid}.meta` 修改为 `{flushTs}-{minDefaultTs}-{minTs}-{maxTs}.meta`。文件名中包含以下时间戳字段： + + - `flushTs`：该备份文件被定期上传至外部存储的时间戳。该值从 PD 获取，具有全局唯一性。 + - `minDefaultTs`：仅针对 Write CF 文件，表示该备份所覆盖的最早事务起始时间。 + - `minTs` 和 `maxTs`：该备份文件内包含的所有 key-value 数据的最小时间戳和最大时间戳。 + + 这些时间戳均采用 16 位固定长度的十六进制字符串编码，左侧补零以保证长度一致。这样的编码设计可以确保文件名按照字典序自然排序，方便在外部存储系统中高效执行批量列举和范围过滤操作。 + +- `global_checkpoint`：备份的全局进度。它记录了可以被 `br restore point` 恢复到的最晚时间点。 +- `{date}/{hour}`：对应日期和小时的备份数据。注意在清理存储的时候，需使用 `br log truncate`，不能手动删除数据。这是因为 metadata 会指向这里的数据，手动删除它们会导致恢复失败或恢复后数据不一致等问题。 + 具体示例如下： ``` -. ├── v1 │   ├── backupmeta │   │   ├── ... -│   │   ├── 435213818858112001-e2569bda-a75a-4411-88de-f469b49d6256.meta -│   │   ├── 435214043785779202-1780f291-3b8a-455e-a31d-8a1302c43ead.meta -│   │   ├── 435214443785779202-224f1408-fff5-445f-8e41-ca4fcfbd2a67.meta +│   │   ├── 060c4bc7b0cdd582-06097a780d1ba138-060ab960016d2f00-060c0b9e47d4787b.meta +│   │   ├── 06123bc6a0cdd591-060c3d24585be000-060c4453954a4000-060c4bc7b0cdcfa4.meta +│   │   └── 063c2ac1c0cdd5c3-0609d2e6b3bcb064-060ab960016d2f84-060c0b9e47d47a77.meta │   ├── global_checkpoint │   │   ├── 1.ts │   │   ├── 2.ts -│   │   ├── 3.ts -│   ├── 20220811 -│   │   ├── 03 -│   │   │   ├── 1 -│   │   │   │   ├── ... -│   │   │   │   ├── 435213866703257604-60fcbdb6-8f55-4098-b3e7-2ce604dafe54.log -│   │   │   │   ├── 435214023989657606-72ce65ff-1fa8-4705-9fd9-cb4a1e803a56.log -│   │   │   ├── 2 -│   │   │   │   ├── ... -│   │   │   │   ├── 435214102632857605-11deba64-beff-4414-bc9c-7a161b6fb22c.log -│   │   │   │   ├── 435214417205657604-e6980303-cbaa-4629-a863-1e745d7b8aed.log -│   │   │   ├── 3 -│   │   │   │   ├── ... -│   │   │   │   ├── 435214495848857605-7bf65e92-8c43-427e-b81e-f0050bd40be0.log -│   │   │   │   ├── 435214574492057604-80d3b15e-3d9f-4b0c-b133-87ed3f6b2697.log -├── v1_stream_truncate_safepoint.txt +│   │   └── 3.ts +│   └── 20220811 +│      └── 03 +│         ├── 1 +│         │   ├── ... +│         │   ├── 435213866703257604-60fcbdb6-8f55-4098-b3e7-2ce604dafe54.log +│         │   └── 435214023989657606-72ce65ff-1fa8-4705-9fd9-cb4a1e803a56.log +│         ├── 2 +│         │   ├── ... +│         │   ├── 435214102632857605-11deba64-beff-4414-bc9c-7a161b6fb22c.log +│         │   └── 435214417205657604-e6980303-cbaa-4629-a863-1e745d7b8aed.log +│         └── 3 +│            ├── ... +│            ├── 435214495848857605-7bf65e92-8c43-427e-b81e-f0050bd40be0.log +│            └── 435214574492057604-80d3b15e-3d9f-4b0c-b133-87ed3f6b2697.log +└── v1_stream_truncate_safepoint.txt ``` diff --git a/br/br-monitoring-and-alert.md b/br/br-monitoring-and-alert.md index 1b187e1311ac..93e736261447 100644 --- a/br/br-monitoring-and-alert.md +++ b/br/br-monitoring-and-alert.md @@ -1,7 +1,6 @@ --- title: 备份恢复监控告警 summary: 了解备份恢复的监控告警。 -aliases: ['/zh/tidb/dev/pitr-monitoring-and-alert/'] --- # 备份恢复监控告警 @@ -22,7 +21,7 @@ aliases: ['/zh/tidb/dev/pitr-monitoring-and-alert/'] - 通过 TiUP 部署的集群，[Grafana](https://grafana.com/) 中内置了 Backup log 的面板。 -- 手动部署的集群，需要参考[导入 Grafana 面板](/deploy-monitoring-services.md#第-2-步导入-grafana-面板)，将 [tikv_details.json](https://github.com/tikv/tikv/blob/master/metrics/grafana/tikv_details.json) 文件上传到 Grafana 中。之后在 TiKV-Details Dashboard 中找到 Backup Log 面板即可。 +- 手动部署的集群，需要参考[导入 Grafana 面板](/deploy-monitoring-services.md#第-2-步导入-grafana-面板)，将 [tikv_details.json](https://github.com/tikv/tikv/blob/release-8.5/metrics/grafana/tikv_details.json) 文件上传到 Grafana 中。之后在 TiKV-Details Dashboard 中找到 Backup Log 面板即可。 ### 监控指标 @@ -59,7 +58,7 @@ aliases: ['/zh/tidb/dev/pitr-monitoring-and-alert/'] 告警规则配置可以参考下面的步骤： -1. 在 Prometheus 所在节点上创建告警规则的配置文件（例如 `pitr.rules.yml`），参考 [Prometheus 文档](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/) 和下列推荐的告警项及配置样例填写告警规则。 +1. 在 Prometheus 所在节点上创建告警规则的配置文件（例如 `pitr.rules.yml`），参考 [Prometheus 文档](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/)和下列推荐的告警项及配置样例填写告警规则。 2. 在 Prometheus 配置文件中的 `rule_files` 字段填入告警规则文件的路径。 3. 通过向 Prometheus 进程发送 `SIGHUP` 信号（`kill -HUP pid`）或向 `http://prometheus-addr/-/reload` 发送 HTTP `POST` 请求（使用 HTTP 请求方式前需要在启动 Prometheus 时指定 `--web.enable-lifecycle` 参数）。 diff --git a/br/br-pitr-guide.md b/br/br-pitr-guide.md index edf4459baf2b..cf978f35845d 100644 --- a/br/br-pitr-guide.md +++ b/br/br-pitr-guide.md @@ -1,7 +1,6 @@ --- title: TiDB 日志备份与 PITR 使用指南 summary: 了解 TiDB 的日志备份与 PITR 功能使用。 -aliases: ['/zh/tidb/dev/pitr-usage/'] --- # TiDB 日志备份与 PITR 使用指南 @@ -26,6 +25,8 @@ tiup br log start --task-name=pitr --pd "${PD_IP}:2379" \ --storage 's3://backup-101/logbackup?access-key=${access-key}&secret-access-key=${secret-access-key}' ``` +### 查询日志备份状态 + 日志备份任务启动后，会在 TiDB 集群后台持续地运行，直到你手动将其暂停。在这过程中，TiDB 变更数据将以小批量的形式定期备份到指定存储中。如果你需要查询日志备份任务当前状态，执行如下命令： ```shell @@ -37,15 +38,38 @@ tiup br log status --task-name=pitr --pd "${PD_IP}:2379" ``` ● Total 1 Tasks. > #1 < - name: pitr - status: ● NORMAL - start: 2022-05-13 11:09:40.7 +0800 - end: 2035-01-01 00:00:00 +0800 - storage: s3://backup-101/log-backup + name: pitr + status: ● NORMAL + start: 2022-05-13 11:09:40.7 +0800 + end: 2035-01-01 00:00:00 +0800 + storage: s3://backup-101/log-backup speed(est.): 0.00 ops/s checkpoint[global]: 2022-05-13 11:31:47.2 +0800; gap=4m53s ``` +其中，各个字段含义如下： + +- `name`：Log Backup 任务的名字。 +- `status`：Log Backup 的状态，包括 `NORMAL`、`PAUSED`、`ERROR`。 +- `start`：Log Backup 的起始时间戳。 +- `end`：Log Backup 的结束时间戳，目前这个字段并不会生效。 +- `storage`：Log Backup 的外部存储的 URI。 +- `speed(est.)`：Log Backup 目前的流量。这个值是取最近数秒内的流量采样估算而成。如需更加精确的流量统计，你可以通过 Grafana 的 **[TiKV-Details](/grafana-tikv-dashboard.md#tikv-details-面板)** 监控面板中的 `Log Backup` 行查看。 +- `checkpoint[global]`：Log Backup 目前的进度。你可以使用 PiTR 恢复到这个时间戳前的时间点。 + +如果 Log Backup 任务暂停，`log status` 会输出以下额外的字段来展示暂停的细节： + +- `pause-time`：执行暂停操作的时间。 +- `pause-operator`：执行暂停操作的机器的 hostname。 +- `pause-operator-pid`：执行暂停操作的进程的 PID。 +- `pause-payload`：暂停时所附带的额外信息。 + +如果 Log Backup 任务的暂停是由于 TiKV 发生错误导致的，你可能还会额外看到 TiKV 上报的错误： + +- `error[store=*]`：TiKV 处的错误代码。 +- `error-happen-at[store=*]`：在 TiKV 处发生错误的时间。 +- `error-message[store=*]`：在 TiKV 处的错误消息。 + ### 定期执行全量备份 快照备份功能可作为全量备份的方法，运行 `tiup br backup full` 命令可以按照固定的周期（比如 2 天）进行全量备份。 @@ -69,13 +93,17 @@ tiup br restore point --pd "${PD_IP}:2379" \ 恢复期间，可通过终端中的进度条查看进度，如下。恢复分为两个阶段：全量恢复 (Full Restore) 和日志恢复（Restore Meta Files 和 Restore KV Files）。每个阶段完成恢复后，br 命令行工具都会输出恢复耗时和恢复数据大小等信息。 ```shell -Full Restore <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% +Split&Scatter Region <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% +Download&Ingest SST <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% +Restore Pipeline <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% *** ["Full Restore success summary"] ****** [total-take=xxx.xxxs] [restore-data-size(after-compressed)=xxx.xxx] [Size=xxxx] [BackupTS={TS}] [total-kv=xxx] [total-kv-size=xxx] [average-speed=xxx] Restore Meta Files <--------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% Restore KV Files <----------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% *** ["restore log success summary"] [total-take=xxx.xx] [restore-from={TS}] [restore-to={TS}] [total-kv-count=xxx] [total-size=xxx] ``` +在数据恢复期间，目标表的 Table Mode 会自动设置为 `restore`，处于 `restore` 模式的表禁止用户执行任何读写操作。当数据恢复完成后，Table Mode 会自动切换为 `normal` 状态，用户可以正常读写该表，从而确保数据恢复期间的任务稳定性和数据一致性。 + ## 清理过期的日志备份数据 如[使用指南概览](/br/br-use-overview.md)所述： @@ -105,19 +133,25 @@ Restore KV Files <-------------------------------------------------------------- ## PITR 的性能指标 -- PITR 恢复速度，平均到单台 TiKV 节点：全量恢复 (Full Restore) 为 280 GB/h，日志恢复（Restore Meta Files 和 Restore KV Files）为 30 GB/h +- PITR 恢复速度，平均到单台 TiKV 节点：全量恢复 (Full Restore) 为 2 TiB/h，日志恢复（Restore Meta Files 和 Restore KV Files）为 30 GiB/h - 使用 `tiup br log truncate` 清理过期的日志备份数据速度为 600 GB/h > **注意：** > > 以上功能指标是根据下述两个场景测试得出的结论，如有出入，建议以实际测试结果为准： > -> - 全量恢复速度 = 全量恢复数据量 /（时间 * TiKV 数量） -> - 日志恢复速度 = 日志恢复总量 /（时间 * TiKV 数量） +> - 全量恢复速度 = 集群中所有 TiKV 节点恢复数据总量 /（时间 * TiKV 数量） +> - 日志恢复速度 = 集群中所有 TiKV 节点日志恢复总量 /（时间 * TiKV 数量） > -> 其中全量恢复数据量，是指单个副本中所有 KV 的逻辑大小，并不代表实际恢复的数据量。BR 恢复数据时会根据集群设置的副本数来恢复全部副本，当副本数越多时，实际恢复的数据量也就越多。 +> 外部存储中只存放单个副本中的 KV 数据，因此外部存储上的数据量并不代表集群实际恢复后的数据量。BR 恢复数据时会根据集群设置的副本数来恢复全部副本，当副本数越多时，实际恢复的数据量也就越多。 > 所有测试集群默认设置 3 副本。 -> 如果想提升整体恢复的性能，可以通过根据实际情况调整 TiKV 配置文件中的 [`import.num-threads`](/tikv-configuration-file.md#import) 配置项以及 BR 命令的 [`pitr-concurrency`](/br/use-br-command-line-tool.md#常用选项) 参数。 +> 如果想提升整体恢复的性能，可以通过根据实际情况调整 TiKV 配置文件中的 [`import.num-threads`](/tikv-configuration-file.md#import) 配置项以及 BR 命令的 [`pitr-concurrency`](/br/br-pitr-manual.md#恢复到指定时间点-pitr) 参数。 +> 当上游集群有**大量 Region** 且 **flush 间隔较短**时，PITR 会生成大量小文件，这会增加恢复过程中的批处理和分发开销。如需提高每个批次处理的文件数量，可以**适度**调高以下参数值： +> +> - `pitr-batch-size`：每个批次的累计**字节数**（默认为 **16 MiB**）。 +> - `pitr-batch-count`：每个批次的**文件数量**（默认为 **8**）。 +> +> 在判断是否开启下一个批次时，这两个阈值会被分别评估：一旦任意一个阈值先达到，当前批次就会结束并开启下一个批次，另一个阈值在该批次中则不再生效。 测试场景 1（[TiDB Cloud](https://tidbcloud.com) 上部署）如下： diff --git a/br/br-pitr-manual.md b/br/br-pitr-manual.md index aa36fc257a1e..091e6e90d5e4 100644 --- a/br/br-pitr-manual.md +++ b/br/br-pitr-manual.md @@ -1,7 +1,6 @@ --- title: TiDB 日志备份与 PITR 命令行手册 summary: 介绍 TiDB 日志备份与 PITR 的命令行。 -aliases: ['/zh/tidb/dev/br-log-command-line/'] --- # TiDB 日志备份与 PITR 命令行手册 @@ -425,6 +424,9 @@ Usage: Flags: --full-backup-storage string specify the backup full storage. fill it if want restore full backup before restore log. -h, --help help for point + --pitr-batch-count uint32 specify the batch count to restore log. (default 8) + --pitr-batch-size uint32 specify the batch size to retore log. (default 16777216) + --pitr-concurrency uint32 specify the concurrency to restore log. (default 16) --restored-ts string the point of restore, used for log restore. support TSO or datetime, e.g. '400036290571534337' or '2018-05-11 01:42:23+0800' --start-ts string the start timestamp which log restore from. support TSO or datetime, e.g. '400036290571534337' or '2018-05-11 01:42:23+0800' @@ -440,6 +442,9 @@ Global Flags: 以上示例只展示了常用的参数，这些参数作用如下： - `--full-backup-storage`：指定快照（全量）备份的存储地址。如果你要使用 PITR，需要指定该参数，并选择恢复时间点之前最近的快照备份；如果只恢复日志备份数据，则不需要指定该参数。需要注意的是，第一次初始化恢复集群时，必须指定快照备份，快照备份支持以 Amazon S3、Google Cloud Storage (GCS)、Azure Blob Storage 为备份存储。关于 URI 格式的详细信息，请参考[外部存储服务的 URI 格式](/external-storage-uri.md)。 +- `--pitr-batch-count`：指定日志恢复时单个批次包含的最大文件数。一旦达到该阈值，当前批次会立即结束并开始下一个批次。 +- `--pitr-batch-size`：指定日志恢复时单个批次的最大数据量（字节数）。一旦达到该阈值，当前批次会立即结束并开始下一个批次。 +- `--pitr-concurrency`：指定日志恢复过程中的并发任务数。每个并发任务对应一个批次的日志数据恢复。 - `--restored-ts`：指定恢复到的时间点。如果没有指定该参数，则恢复到日志备份数据最后的可恢复时间点（备份数据的 checkpoint）。 - `--start-ts`：指定日志备份恢复的起始时间点。如果你只恢复日志备份数据，不恢复快照备份，需要指定这个参数。 - `ca`、`cert`、`key`：指定使用 mTLS 加密方式与 TiKV 和 PD 进行通讯。 @@ -453,7 +458,9 @@ tiup br restore point --pd="${PD_IP}:2379" --storage='s3://backup-101/logbackup?access-key=${access-key}&secret-access-key=${secret-access-key}' --full-backup-storage='s3://backup-101/snapshot-202205120000?access-key=${access-key}&secret-access-key=${secret-access-key}' -Full Restore <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% +Split&Scatter Region <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% +Download&Ingest SST <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% +Restore Pipeline <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% *** ***["Full Restore success summary"] ****** [total-take=3.112928252s] [restore-data-size(after-compressed)=5.056kB] [Size=5056] [BackupTS=434693927394607136] [total-kv=4] [total-kv-size=290B] [average-speed=93.16B/s] Restore Meta Files <--------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% Restore KV Files <----------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% @@ -492,4 +499,157 @@ tiup br restore point --pd="${PD_IP}:2379" --crypter.key 0123456789abcdef0123456789abcdef --master-key-crypter-method aes128-ctr --master-key "local:///path/to/master.key" -``` \ No newline at end of file +``` + +### 使用过滤器恢复 + +从 TiDB v8.5.5 开始，在按时间点恢复 (PITR) 过程中，你可以使用过滤器恢复特定的数据库或表，从而更精细地控制要恢复的数据。 + +过滤器采用与其他 BR 操作相同的[表库过滤语法](/table-filter.md)： + +- `'*.*'`：匹配所有数据库和表。 +- `'db1.*'`：匹配数据库 `db1` 中的所有表。 +- `'db1.table1'`：匹配数据库 `db1` 中的特定表 `table1`。 +- `'db*.tbl*'`：匹配以 `db` 开头的数据库和以 `tbl` 开头的表。 +- `'!mysql.*'`：排除 `mysql` 数据库中的所有表。 + +使用示例： + +```shell +# 恢复特定数据库 +tiup br restore point --pd="${PD_IP}:2379" \ +--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--start-ts "2025-06-02 00:00:00+0800" \ +--restored-ts "2025-06-03 18:00:00+0800" \ +--filter 'db1.*' --filter 'db2.*' + +# 恢复特定表 +tiup br restore point --pd="${PD_IP}:2379" \ +--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--start-ts "2025-06-02 00:00:00+0800" \ +--restored-ts "2025-06-03 18:00:00+0800" \ +--filter 'db1.users' --filter 'db1.orders' + +# 使用模式匹配恢复 +tiup br restore point --pd="${PD_IP}:2379" \ +--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--start-ts "2025-06-02 00:00:00+0800" \ +--restored-ts "2025-06-03 18:00:00+0800" \ +--filter 'db*.tbl*' +``` + +> **注意：** +> +> - 使用过滤器恢复前，请确保目标集群中不存在与过滤器匹配的数据库或表，否则恢复将失败并报错。 +> - 过滤器选项适用于快照备份和日志备份的恢复阶段。 +> - 可以指定多个 `--filter` 选项来包含或排除不同的模式。 +> - PITR 过滤暂不支持系统表。如果需要恢复特定的系统表，请使用 `br restore full` 命令并配合过滤器，注意该命令仅恢复快照备份数据（而非日志备份数据）。 +> - 恢复任务中的正则表达式匹配的是 `restored-ts` 时刻的表名，有以下三种情况： +> - 表 A (table id = 1) 在 `restored-ts` 时刻及之前，表名始终匹配 `--filter` 正则表达式，则 PITR 会恢复这张表。 +> - 表 B (table id = 2) 在 `restored-ts` 前的某个时刻，表名不匹配 `--filter` 正则表达式，但在 `restored-ts` 时刻匹配，则 PITR 会恢复这张表。 +> - 表 C (table id = 3) 在 `restored-ts` 前的某个时刻，表名匹配 `--filter` 正则表达式，但在 `restored-ts` 时刻**不**匹配，则 PITR **不会**恢复这张表。 +> - 你可以使用库表过滤功能在线恢复部分数据。在线恢复过程中，不要创建与恢复对象同名的库表，否则恢复任务会因冲突而失败。在该恢复过程中，由 PITR 创建的表都不可读写，直至恢复完成后，这些表才可正常读写。 + +### 并发恢复操作 + +从 TiDB v8.5.5 开始，你可以同时执行多个 PITR 恢复任务。该功能允许你并行恢复不同的数据集，从而提升大规模恢复场景下的效率。 + +并发恢复的使用示例： + +```shell +# 终端 1 - 恢复数据库 db1 +tiup br restore point --pd="${PD_IP}:2379" \ +--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--start-ts "2025-06-02 00:00:00+0800" \ +--restored-ts "2025-06-03 18:00:00+0800" \ +--filter 'db1.*' + +# 终端 2 - 恢复数据库 db2（可同时运行） +tiup br restore point --pd="${PD_IP}:2379" \ +--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--start-ts "2025-06-02 00:00:00+0800" \ +--restored-ts "2025-06-03 18:00:00+0800" \ +--filter 'db2.*' +``` + +> **注意：** +> +> - 每个并发恢复操作必须作用于不同的数据库或不重叠的表集合。尝试并发恢复重叠数据集将导致错误。 +> - 多个恢复任务会占用大量系统资源。仅在 CPU 和 I/O 资源充足时，才建议并行执行恢复任务。 + +### 进行中的日志备份与快照恢复的兼容性 + +从 v8.5.5 开始，当存在日志备份任务时，如果**同时满足**以下条件，则可以正常进行快照恢复 (`br restore [full|database|table]`)，并且恢复的数据可以被进行中的日志备份（下称“日志备份”）正常记录： + +- 执行备份恢复操作的节点需要同时具备以下权限： + - 对备份来源外部存储的读取权限，用于执行快照恢复 + - 对日志备份目标外部存储的写入权限 +- 日志备份的目标外部存储类型是 Amazon S3 (`s3://`)、Google Cloud Storage (`gcs://`) 或 Azure Blob Storage (`azblob://`)。 +- 待恢复的数据与日志备份的目标存储拥有相同的外部存储类型。 +- 待恢复的数据和日志备份均未开启本地加密，参考[日志备份加密](#加密日志备份数据)和[快照备份加密](/br/br-snapshot-manual.md#备份数据加密)。 + +如果不能同时满足上述条件，你可以通过以下步骤完成数据恢复： + +1. [停止日志备份任务](#停止日志备份任务)。 +2. 进行数据恢复。 +3. 恢复完成后，重新进行快照备份。 +4. [重新启动备份任务](#重新启动备份任务)。 + +> **注意：** +> +> 当恢复记录了快照（全量）恢复数据的日志备份时，需要使用 v8.5.5 及之后版本的 BR，否则可能导致记录下来的全量恢复数据无法被恢复。 + +### 进行中的日志备份与 PITR 操作的兼容性 + +从 TiDB v8.5.5 开始，默认情况下，你可以在日志备份任务运行期间执行 PITR 操作。系统会自动处理这些操作之间的兼容性。 + +#### 进行中的日志备份与 PITR 的重要限制 + +当在运行日志备份的同时执行 PITR 操作时，恢复的数据也会被记录到日志备份中。但是，在恢复操作的时间窗口内，由于日志恢复操作的特性，可能存在数据不一致的风险。系统会将元数据写入外部存储，以标记无法保证一致性的时间范围和数据范围。 + +如果在时间范围 `[t1, t2)` 期间发生此类不一致，你无法直接恢复该时间段的数据，需选择以下替代方案： + +- 恢复到 `t1` 时间点（获取不一致时期之前的数据） +- 或在 `t2` 时间点后执行新的快照备份，并基于此备份进行后续 PITR 操作 + +### 中止恢复操作 + +当恢复操作失败时，你可以使用 `tiup br abort` 命令来清理注册表条目和检查点数据。该命令会根据提供的原始恢复参数自动找到并删除相关的元数据，包括 `mysql.tidb_restore_registry` 表中的条目以及检查点数据（无论存储在本地数据库还是外部存储中）。 + +> **注意：** +> +> `abort` 命令仅清理元数据，任何实际恢复的数据需要手动从集群中删除。 + +使用与原始恢复命令相同的参数来中止恢复操作的示例如下： + +```shell +# 中止 PITR 操作 +tiup br abort restore point --pd="${PD_IP}:2379" \ +--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' + +# 中止带过滤器的 PITR 操作 +tiup br abort restore point --pd="${PD_IP}:2379" \ +--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--filter 'db1.*' + +# 中止全量恢复 +tiup br abort restore full --pd="${PD_IP}:2379" \ +--storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' + +# 中止数据库恢复 +tiup br abort restore db --pd="${PD_IP}:2379" \ +--storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--db database_name + +# 中止表恢复 +tiup br abort restore table --pd="${PD_IP}:2379" \ +--storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--db database_name --table table_name +``` diff --git a/br/br-snapshot-architecture.md b/br/br-snapshot-architecture.md index b5ba576dbe18..800a8e34ab1e 100644 --- a/br/br-snapshot-architecture.md +++ b/br/br-snapshot-architecture.md @@ -77,7 +77,7 @@ summary: 了解 TiDB 快照备份与恢复功能的架构设计。 * 如果存在备份数据不可重试的恢复失败，则恢复任务失败。 * 全部备份都恢复成功后，则整个恢复任务成功。 -详细的快照数据备份恢与恢复流程设计，可以参考[备份恢复设计方案](https://github.com/pingcap/tidb/blob/master/br/docs/cn/2019-08-05-new-design-of-backup-restore.md)。 +详细的快照数据备份恢与恢复流程设计，可以参考[备份恢复设计方案](https://github.com/pingcap/tidb/blob/release-8.5/br/docs/cn/2019-08-05-new-design-of-backup-restore.md)。 ## 备份文件 diff --git a/br/br-snapshot-guide.md b/br/br-snapshot-guide.md index 305ae8b8fa4f..85c0bb0b3c0d 100644 --- a/br/br-snapshot-guide.md +++ b/br/br-snapshot-guide.md @@ -1,7 +1,6 @@ --- title: TiDB 快照备份与恢复使用指南 summary: 了解如何使用 br 命令行工具进行 TiDB 快照备份与恢复。 -aliases: ['/zh/tidb/dev/br-usage-backup/','/zh/tidb/dev/br-usage-restore/','/zh/tidb/dev/br-usage-restore-for-maintain/', '/zh/tidb/dev/br-usage-backup-for-maintain/'] --- # TiDB 快照备份与恢复使用指南 @@ -28,21 +27,26 @@ aliases: ['/zh/tidb/dev/br-usage-backup/','/zh/tidb/dev/br-usage-restore/','/zh/ tiup br backup full --pd "${PD_IP}:2379" \ --backupts '2022-09-08 13:30:00 +08:00' \ --storage "s3://backup-101/snapshot-202209081330?access-key=${access-key}&secret-access-key=${secret-access-key}" \ - --ratelimit 128 \ ``` 以上命令中： - `--backupts`：快照对应的物理时间点，格式可以是 [TSO](/tso.md) 或者时间戳，例如 `400036290571534337` 或者 `2018-05-11 01:42:23 +08:00`。如果该快照的数据被垃圾回收 (GC) 了，那么 `tiup br backup` 命令会报错并退出。使用日期方式备份时，建议同时指定时区，否则 br 默认使用本地时间构造时间戳，可能导致备份时间点错误。如果你没有指定该参数，那么 br 会选取备份开始的时间点所对应的快照。 - `--storage`：数据备份到的存储地址。快照备份支持以 Amazon S3、Google Cloud Storage、Azure Blob Storage 为备份存储，以上命令以 Amazon S3 为示例。详细存储地址格式请参考[外部存储服务的 URI 格式](/external-storage-uri.md)。 -- `--ratelimit`：**每个 TiKV** 备份数据的速度上限，单位为 MiB/s。 -在快照备份过程中，终端会显示备份进度条。在备份完成后，会输出备份耗时、速度、备份数据大小等信息。 +在快照备份过程中，终端会显示备份进度条。在备份完成后，会输出备份耗时、速度、备份数据大小等信息。其中： + +- `total-ranges`：备份的文件总数量 +- `ranges-succeed`：备份成功的文件数量 +- `ranges-failed`：备份失败的文件数量 +- `backup-total-ranges`：备份的表（包括分区表）与索引的数量 +- `write-CF-files`：备份文件中含有 `write CF` 数据的 SST 文件数量 +- `default-CF-files`：备份文件中含有 `default CF` 数据的 SST 文件数量 ```shell Full Backup <-------------------------------------------------------------------------------> 100.00% Checksum <----------------------------------------------------------------------------------> 100.00% -*** ["Full Backup success summary"] *** [backup-checksum=3.597416ms] [backup-fast-checksum=2.36975ms] *** [total-take=4.715509333s] [BackupTS=435844546560000000] [total-kv=1131] [total-kv-size=250kB] [average-speed=53.02kB/s] [backup-data-size(after-compressed)=71.33kB] [Size=71330] +*** ["Full Backup success summary"] *** [total-ranges=20] [ranges-succeed=20] [ranges-failed=0] [backup-checksum=3.597416ms] [backup-fast-checksum=2.36975ms] [backup-total-ranges=11] [backup-total-regions=10] [write-CF-files=14] [default-CF-files=6] [total-take=4.715509333s] [BackupTS=435844546560000000] [total-kv=1131] [total-kv-size=250kB] [average-speed=53.02kB/s] [backup-data-size(after-compressed)=71.33kB] [Size=71330] ``` ## 查询快照备份的时间点信息 @@ -79,13 +83,27 @@ tiup br restore full --pd "${PD_IP}:2379" \ --storage "s3://backup-101/snapshot-202209081330?access-key=${access-key}&secret-access-key=${secret-access-key}" ``` -在恢复快照备份数据过程中，终端会显示恢复进度条。在完成恢复后，会输出恢复耗时、速度、恢复数据大小等信息。 +在恢复快照备份数据过程中，终端会显示恢复进度条。在完成恢复后，会输出恢复耗时、速度、恢复数据大小等信息。其中： + +- `total-ranges`：恢复的文件总数量 +- `ranges-succeed`：恢复成功的文件数量 +- `ranges-failed`：恢复失败的文件数量 +- `merge-ranges`：合并数据范围的耗时 +- `split-region`：切分和打散 Region 的耗时 +- `restore-files`： TiKV 恢复 SST 文件的耗时 +- `write-CF-files`：恢复文件中含有 `write CF` 数据的 SST 文件数量 +- `default-CF-files`：恢复文件中含有 `default CF` 数据的 SST 文件数量 +- `split-keys`：生成的用于切分 Region 的 key 数量 ```shell -Full Restore <------------------------------------------------------------------------------> 100.00% -*** ["Full Restore success summary"] *** [total-take=4.344617542s] [total-kv=5] [total-kv-size=327B] [average-speed=75.27B/s] [restore-data-size(after-compressed)=4.813kB] [Size=4813] [BackupTS=435844901803917314] +Split&Scatter Region <--------------------------------------------------------------------> 100.00% +Download&Ingest SST <---------------------------------------------------------------------> 100.00% +Restore Pipeline <------------------------------------------------------------------------> 100.00% +*** ["Full Restore success summary"] [total-ranges=20] [ranges-succeed=20] [ranges-failed=0] [merge-ranges=7.546971ms] [split-region=343.594072ms] [restore-files=1.57662s] [default-CF-files=6] [write-CF-files=14] [split-keys=9] [total-take=4.344617542s] [total-kv=5] [total-kv-size=327B] [average-speed=75.27B/s] [restore-data-size(after-compressed)=4.813kB] [Size=4813] [BackupTS=435844901803917314] ``` +在数据恢复期间，目标表的 Table Mode 会自动设置为 `restore`，处于 `restore` 模式的表禁止用户执行任何读写操作。当数据恢复完成后，Table Mode 会自动切换为 `normal` 状态，用户可以正常读写该表，从而确保数据恢复期间的任务稳定性和数据一致性。 + ### 恢复备份数据中指定库表的数据 br 命令行工具支持只恢复备份数据中指定库、表的部分数据，该功能用于在恢复过程中过滤不需要的数据。 @@ -132,6 +150,7 @@ tiup br restore full \ - `br` v5.1.0 开始，快照备份时默认自动备份 **mysql schema 下的系统表数据**，但恢复数据时默认不恢复系统表数据。 - `br` v6.2.0 开始，增加恢复参数 `--with-sys-table` 支持恢复数据的同时恢复**部分系统表相关数据**。 - `br` v7.6.0 开始，恢复参数 `--with-sys-table` 默认开启，即默认支持恢复数据的同时恢复**部分系统表相关数据**。 +- `br` v8.5.5 开始，增加恢复参数 `--fast-load-sys-tables` 支持物理恢复系统表，该参数默认开启。通过 `RENAME TABLE` DDL 将 `__TiDB_BR_Temporary_mysql` 下的系统表和 `mysql` 库下的系统表进行原子交换。与通过 `REPLACE INTO` SQL 写入的逻辑恢复系统表方式不同，物理恢复系统表将会完全覆盖系统表中原有的数据。 **可恢复的部分系统表**： @@ -153,7 +172,7 @@ tiup br restore full \ - 统计信息表 (`mysql.stat_*`) (但可以恢复统计信息，详细参考[备份统计信息](/br/br-snapshot-manual.md#备份统计信息)) - 系统变量表 (`mysql.tidb`、`mysql.global_variables`) -- [其他系统表](https://github.com/pingcap/tidb/blob/master/br/pkg/restore/snap_client/systable_restore.go#L31) +- [其他系统表](https://github.com/pingcap/tidb/blob/release-8.5/br/pkg/restore/snap_client/systable_restore.go#L31) ``` +-----------------------------------------------------+ @@ -197,15 +216,23 @@ TiDB 备份功能对集群性能（事务延迟和 QPS）有一定的影响， 你可以通过如下方案手动控制备份对集群性能带来的影响。但是，这两种方案在减少备份对集群的影响的同时，也会降低备份任务的速度。 -- 使用 `--ratelimit` 参数对备份任务进行限速。请注意，这个参数限制的是**把备份文件存储到外部存储**的速度。计算备份文件的大小时，请以备份日志中的 `backup data size(after compressed)` 为准。设置 `--ratelimit` 后，为了避免任务数过多导致限速失效，br 的 `concurrency` 参数会自动调整为 1。 -- 调节 TiKV 配置项 [`backup.num-threads`](/tikv-configuration-file.md#num-threads-1)，限制备份任务使用的工作线程数量。内部测试数据表明，当备份的线程数量不大于 `8`、集群总 CPU 利用率不超过 60% 时，备份任务对集群（无论读写负载）几乎没有影响。 +- 优先推荐: 调节 TiKV 配置项 [`backup.num-threads`](/tikv-configuration-file.md#num-threads-1)，该配置用于限制备份任务使用的工作线程数。由于备份过程属于 CPU 密集型操作，通过控制线程数可以更精确地限制备份对 TiKV 的 CPU 使用，从而实现更可控、更可预测的资源隔离。在绝大多数场景中，仅调整 `num-threads` 就足以控制备份对集群的影响。内部测试表明，当线程数小于或等于 8、且集群总 CPU 利用率小于 60% 时，备份对业务负载的影响可忽略不计。 + +- 次选方案：如果你已将 `num-threads` 设置为较低值（如 `1`），但仍希望进一步降低备份对集群的影响，此时可以考虑使用 `--ratelimit` 参数。该参数限制的是备份文件写入外部存储的带宽，单位为 MiB/s。实际限速效果取决于压缩后的数据体积。详情请参考日志中的 `backup data size (after compressed)` 字段。启用后，BR 会自动将 `--concurrency` 调整为 `1`，以减少并发请求数量。 + +> **注意：** +> +> 开启 `--ratelimit` 会进一步降低备份速度。在大多数情况下，如果你在业务低峰期执行备份，并且已经将 `num-threads` 降为 `1`，但仍然担心备份影响业务，通常说明**集群资源已接近瓶颈**。此时，建议考虑以下替代方案： +> +> - [扩容 TiKV 节点](/tiup/tiup-cluster.md#扩容节点)以提升可用资源。 +> - 开启日志备份 [`Log Backup`](/br/br-log-architecture.md)，以降低对在线业务的干扰。 通过限制备份的线程数量可以降低备份对集群性能的影响，但是这会影响到备份的性能，以上的多次备份测试结果显示，单 TiKV 存储节点上备份速度和备份线程数量呈正比。在线程数量较少的时候，备份速度约为 20 MiB/线程数。例如，单 TiKV 节点 5 个备份线程可达到 100 MiB/s 的备份速度。 ### 快照恢复的性能与影响 - TiDB 恢复的时候会尽可能打满 TiKV CPU、磁盘 IO、网络带宽等资源，所以推荐在空的集群上执行备份数据的恢复，避免对正在运行的业务产生影响。 -- 备份数据的恢复速度与集群配置、部署、运行的业务都有比较大的关系。在内部多场景仿真测试中，单 TiKV 存储节点上备份数据恢复速度能够达到 100 MiB/s。在不同用户场景下，快照恢复的性能和影响应以实际测试结论为准。 +- 备份数据的恢复速度与集群配置、部署、运行的业务都有比较大的关系。在不同用户场景下，快照恢复的性能和影响应以实际测试结论为准。 - BR 提供了粗粒度的 Region 打散算法，用于提升大规模 Region 场景下的 Region 恢复速度。在这个方式下每个 TiKV 节点会得到均匀稳定的下载任务，从而充分利用每个 TiKV 节点的所有资源实现并行快速恢复。在实际案例中，大规模 Region 场景下，集群快照恢复速度最高提升约 3 倍。 - 从 v8.0.0 起，`br` 命令行工具新增 `--tikv-max-restore-concurrency` 参数，用于控制每个 TiKV 节点的最大 download 和 ingest 文件数量。此外，通过调整此参数，可以控制作业队列的最大长度（作业队列的最大长度 = 32 \* TiKV 节点数量 \* `--tikv-max-restore-concurrency`），进而控制 BR 节点的内存消耗。 diff --git a/br/br-snapshot-manual.md b/br/br-snapshot-manual.md index e526e68718dc..ea398e15982d 100644 --- a/br/br-snapshot-manual.md +++ b/br/br-snapshot-manual.md @@ -36,19 +36,18 @@ tiup br backup full \ --pd "${PD_IP}:2379" \ --backupts '2022-09-08 13:30:00 +08:00' \ --storage "s3://${backup_collection_addr}/snapshot-${date}?access-key=${access-key}&secret-access-key=${secret-access-key}" \ - --ratelimit 128 \ --log-file backupfull.log ``` 以上命令中： - `--backupts`：快照对应的物理时间点，格式可以是 [TSO](/tso.md) 或者时间戳，例如 `400036290571534337` 或者 `2024-06-28 13:30:00 +08:00`。如果该快照的数据已经被 GC，那么 `tiup br backup` 命令会报错退出；如果没有指定该参数，br 命令行工具会选取备份开始的时间点所对应的快照。 -- `--ratelimit`：**每个 TiKV** 执行备份任务的速度上限（单位 MiB/s）。 - `--log-file`：备份日志写入的目标文件。 > **注意：** > -> BR 工具已支持自适应 GC，会自动将 `backupTS`（默认是最新的 PD timestamp）注册到 PD 的 `safePoint`，保证 TiDB 的 GC Safe Point 在备份期间不会向前移动，即可避免手动设置 GC。 +> - 从 v8.5.0 起，在进行全量备份时，BR 工具默认不计算表级别的 checksum (`--checksum=false`) 以提升备份性能。 +> - BR 工具已支持自适应 GC，会自动将 `backupTS`（默认是最新的 PD timestamp）注册到 PD 的 `safePoint`，保证 TiDB 的 GC Safe Point 在备份期间不会向前移动，即可避免手动设置 GC。 备份期间终端会显示进度条，效果如下。当进度条达到 100% 时，表示备份完成。 @@ -71,7 +70,6 @@ tiup br backup db \ --pd "${PD_IP}:2379" \ --db test \ --storage "s3://${backup_collection_addr}/snapshot-${date}?access-key=${access-key}&secret-access-key=${secret-access-key}" \ - --ratelimit 128 \ --log-file backuptable.log ``` @@ -89,7 +87,6 @@ tiup br backup table \ --db test \ --table usertable \ --storage "s3://${backup_collection_addr}/snapshot-${date}?access-key=${access-key}&secret-access-key=${secret-access-key}" \ - --ratelimit 128 \ --log-file backuptable.log ``` @@ -106,7 +103,6 @@ tiup br backup full \ --pd "${PD_IP}:2379" \ --filter 'db*.tbl*' \ --storage "s3://${backup_collection_addr}/snapshot-${date}?access-key=${access-key}&secret-access-key=${secret-access-key}" \ - --ratelimit 128 \ --log-file backupfull.log ``` @@ -131,8 +127,19 @@ tiup br restore full \ --storage local:///br_data/ --pd "${PD_IP}:2379" --log-file restore.log ``` +> **注意：** +> +> 从 v8.5.5 开始，当参数 `--load-stats` 设置为 `false` 时，br 不再向 `mysql.stats_meta` 表写入恢复表的统计信息。你可以在恢复完成后手动执行 [`ANALYZE TABLE`](/sql-statements/sql-statement-analyze-table.md)，以更新相关统计信息。 + 备份恢复功能在备份时，将统计信息通过 JSON 格式存储在 `backupmeta` 文件中。在恢复时，将 JSON 格式的统计信息导入到集群中。详情请参考 [LOAD STATS](/sql-statements/sql-statement-load-stats.md)。 +从 v8.5.5 开始，BR 引入参数 `--fast-load-sys-tables`，该参数默认开启。在使用 br 命令行工具将数据恢复到一个全新集群，且上下游的表和分区 ID 能够复用的前提下（否则会自动回退为逻辑导入统计信息），开启 `--fast-load-sys-tables` 后，br 会先将统计信息相关表恢复至临时系统库 `__TiDB_BR_Temporary_mysql` 中，再通过 `RENAME TABLE` 语句将这些表与 `mysql` 库下的原有表进行原子性替换。使用示例如下： + +```shell +tiup br restore full \ +--storage local:///br_data/ --pd "${PD_IP}:2379" --log-file restore.log --load-stats --fast-load-sys-tables +``` + ## 备份数据加密 br 命令行工具支持在备份端，或备份到 Amazon S3 的时候在[存储服务端进行备份数据加密](/br/backup-and-restore-storages.md#amazon-s3-存储服务端加密备份数据)，你可以根据自己情况选择其中一种使用。 @@ -180,9 +187,27 @@ tiup br restore full \ 恢复期间终端会显示进度条，效果如下。当进度条达到 100% 时，表示恢复完成。在完成恢复后，br 工具为了确保数据安全性，还会校验恢复数据。 ```shell -Full Restore <---------/...............................................> 17.12%. +Split&Scatter Region <--------------------------------------------------------------------> 100.00% +Download&Ingest SST <---------------------------------------------------------------------> 100.00% +Restore Pipeline <-------------------------/...............................................> 17.12% ``` +从 TiDB v8.5.5 开始，你可以通过指定参数 `--fast-load-sys-tables` 在全新的集群上进行物理恢复系统表： + +```shell +tiup br restore full \ + --pd "${PD_IP}:2379" \ + --with-sys-table \ + --fast-load-sys-tables \ + --storage "s3://${backup_collection_addr}/snapshot-${date}?access-key=${access-key}&secret-access-key=${secret-access-key}" \ + --ratelimit 128 \ + --log-file restorefull.log +``` + +> **注意：** +> +> 与通过 `REPLACE INTO` SQL 语句执行的逻辑恢复系统表方式不同，物理恢复系统表会完全覆盖系统表中的原有数据。 + ## 恢复备份数据中指定库表的数据 br 命令行工具支持只恢复备份数据中指定库/表的局部数据。该功能在恢复过程中过滤掉不需要的数据，可以用于往 TiDB 集群上恢复指定库/表的数据。 diff --git a/br/br-use-overview.md b/br/br-use-overview.md index 1268ac22f9da..aa260efd00cd 100644 --- a/br/br-use-overview.md +++ b/br/br-use-overview.md @@ -1,7 +1,6 @@ --- title: TiDB 备份与恢复功能使用概述 summary: 了解如何部署和使用 TiDB 集群的备份与恢复。 -aliases: ['/zh/tidb/dev/br-deployment/'] --- # TiDB 备份与恢复功能使用概述 diff --git a/br/use-br-command-line-tool.md b/br/use-br-command-line-tool.md index 7898877186a0..c49d8c20319c 100644 --- a/br/use-br-command-line-tool.md +++ b/br/use-br-command-line-tool.md @@ -57,7 +57,7 @@ tiup br backup full --pd "${PD_IP}:2379" \ * `--cert`：指定 PEM 格式的 SSL 证书文件路径。 * `--key`：指定 PEM 格式的 SSL 证书密钥文件路径。 * `--status-addr`：向 Prometheus 提供统计数据的监听地址。 -* `--concurrency`：备份阶段的任务并发数。 +* `--concurrency`：控制备份阶段如何将任务拆分为多个请求，并以指定的并发数 (Concurrency) 发送到同一个 TiKV 节点。该参数主要影响 BR 发送给 TiKV 的请求拆分粒度，而不再直接决定备份的吞吐性能。通常无需修改默认值，如需提升备份性能，建议通过调整 [`tikv.backup.num-threads`](/tikv-configuration-file.md#num-threads-1) 参数来优化。 * `--pitr-concurrency`：日志恢复阶段的任务并发数。 * `--tikv-max-restore-concurrency`：快照恢复阶段的单个 TiKV 节点的任务最大并发数。 * `--compression`：备份生成文件的压缩算法，支持 `lz4`、`snappy`、`zstd`，默认 `zstd`（多数情况下无须修改）。如何选择不同的压缩算法，可以参考[文档](https://github.com/EighteenZi/rocksdb_wiki/blob/master/Compression.md)。 diff --git a/cached-tables.md b/cached-tables.md index 5d9d88abbdf9..a8557727e784 100644 --- a/cached-tables.md +++ b/cached-tables.md @@ -215,7 +215,7 @@ Query OK, 0 rows affected (0.00 sec) 由于 TiDB 将整张缓存表的数据加载到 TiDB 进程的内存中，并且执行修改操作后缓存会失效，需要重新加载，所以 TiDB 缓存表只适用于表比较小的场景。 -目前 TiDB 对于每张缓存表的大小限制为 64 MB。如果表的数据超过了 64 MB，执行 `ALTER TABLE t CACHE` 会失败。 +目前 TiDB 对于每张缓存表的大小限制为 64 MiB。如果表的数据超过了 64 MiB，执行 `ALTER TABLE t CACHE` 会失败。 ## 与其他 TiDB 功能的兼容性限制 diff --git a/certificate-authentication.md b/certificate-authentication.md index acfc6c077125..90b347b98860 100644 --- a/certificate-authentication.md +++ b/certificate-authentication.md @@ -1,7 +1,6 @@ --- title: TiDB 证书鉴权使用指南 summary: 了解使用 TiDB 的证书鉴权功能。 -aliases: ['/docs-cn/dev/certificate-authentication/','/docs-cn/dev/reference/security/cert-based-authentication/'] --- # TiDB 证书鉴权使用指南 @@ -25,16 +24,12 @@ TiDB 支持基于证书鉴权的登录方式。采用这种方式，TiDB 对不 1. 执行以下命令生成 CA 密钥： - {{< copyable "shell-regular" >}} - ```bash sudo openssl genrsa 2048 > ca-key.pem ``` 命令执行后输出以下结果： - {{< copyable "shell-regular" >}} - ```bash Generating RSA private key, 2048 bit long modulus (2 primes) ....................+++++ @@ -44,16 +39,12 @@ TiDB 支持基于证书鉴权的登录方式。采用这种方式，TiDB 对不 2. 执行以下命令生成该密钥对应的证书： - {{< copyable "shell-regular" >}} - ```bash sudo openssl req -new -x509 -nodes -days 365000 -key ca-key.pem -out ca-cert.pem ``` 3. 输入证书细节信息，示例如下： - {{< copyable "shell-regular" >}} - ```bash Country Name (2 letter code) [AU]:US State or Province Name (full name) [Some-State]:California @@ -72,16 +63,12 @@ TiDB 支持基于证书鉴权的登录方式。采用这种方式，TiDB 对不 1. 执行以下命令生成服务端的密钥： - {{< copyable "shell-regular" >}} - ```bash sudo openssl req -newkey rsa:2048 -days 365000 -nodes -keyout server-key.pem -out server-req.pem ``` 2. 输入证书细节信息，示例如下： - {{< copyable "shell-regular" >}} - ```bash Country Name (2 letter code) [AU]:US State or Province Name (full name) [Some-State]:California @@ -99,8 +86,6 @@ TiDB 支持基于证书鉴权的登录方式。采用这种方式，TiDB 对不 3. 执行以下命令生成服务端的 RSA 密钥： - {{< copyable "shell-regular" >}} - ```bash sudo openssl rsa -in server-key.pem -out server-key.pem ``` @@ -113,8 +98,6 @@ TiDB 支持基于证书鉴权的登录方式。采用这种方式，TiDB 对不 4. 使用 CA 证书签名来生成服务端的证书： - {{< copyable "shell-regular" >}} - ```bash sudo openssl x509 -req -in server-req.pem -days 365000 -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out server-cert.pem ``` @@ -137,16 +120,12 @@ TiDB 支持基于证书鉴权的登录方式。采用这种方式，TiDB 对不 1. 执行以下命令生成客户端的密钥： - {{< copyable "shell-regular" >}} - ```bash sudo openssl req -newkey rsa:2048 -days 365000 -nodes -keyout client-key.pem -out client-req.pem ``` 2. 输入证书细节信息，示例如下： - {{< copyable "shell-regular" >}} - ```bash Country Name (2 letter code) [AU]:US State or Province Name (full name) [Some-State]:California @@ -164,8 +143,6 @@ TiDB 支持基于证书鉴权的登录方式。采用这种方式，TiDB 对不 3. 执行以下命令生成客户端 RSA 证书： - {{< copyable "shell-regular" >}} - ```bash sudo openssl rsa -in client-key.pem -out client-key.pem ``` @@ -178,8 +155,6 @@ TiDB 支持基于证书鉴权的登录方式。采用这种方式，TiDB 对不 4. 执行以下命令，使用 CA 证书签名来生成客户端证书： - {{< copyable "shell-regular" >}} - ```bash sudo openssl x509 -req -in client-req.pem -days 365000 -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out client-cert.pem ``` @@ -194,14 +169,12 @@ TiDB 支持基于证书鉴权的登录方式。采用这种方式，TiDB 对不 > **注意：** > - > 以上结果中，`subject` 部分后的信息会被用来在 `require` 中配置和要求验证。 + > 以上结果中，`subject` 部分后的信息会被用来在 `REQUIRE` 中配置和要求验证。 ### 验证证书 执行以下命令验证证书： -{{< copyable "shell-regular" >}} - ```bash openssl verify -CAfile ca-cert.pem server-cert.pem client-cert.pem ``` @@ -221,13 +194,11 @@ client-cert.pem: OK 修改 TiDB 配置文件中的 `[security]` 段。这一步指定 CA 证书、服务端密钥和服务端证书存放的路径。可将 `path/to/server-cert.pem`、`path/to/server-key.pem` 和 `path/to/ca-cert.pem` 替换成实际的路径。 -{{< copyable "" >}} - -``` +```toml [security] -ssl-cert ="path/to/server-cert.pem" -ssl-key ="path/to/server-key.pem" -ssl-ca="path/to/ca-cert.pem" +ssl-cert = "path/to/server-cert.pem" +ssl-key = "path/to/server-key.pem" +ssl-ca = "path/to/ca-cert.pem" ``` 启动 TiDB 日志。如果日志中有以下内容，即代表配置生效： @@ -242,10 +213,8 @@ ssl-ca="path/to/ca-cert.pem" 以 MySQL 客户端为例，可以通过指定 `ssl-cert`、`ssl-key`、`ssl-ca` 来使用新的 CA 证书、客户端密钥和证书： -{{< copyable "shell-regular" >}} - ```bash -mysql -utest -h0.0.0.0 -P4000 --ssl-cert /path/to/client-cert.new.pem --ssl-key /path/to/client-key.new.pem --ssl-ca /path/to/ca-cert.pem +mysql -u test -h 0.0.0.0 -P 4000 --ssl-cert /path/to/client-cert.new.pem --ssl-key /path/to/client-key.new.pem --ssl-ca /path/to/ca-cert.pem ``` > **注意：** @@ -260,12 +229,10 @@ mysql -utest -h0.0.0.0 -P4000 --ssl-cert /path/to/client-cert.new.pem --ssl-key 用户证书信息可由 `REQUIRE SUBJECT`、`REQUIRE ISSUER`、`REQUIRE SAN` 和 `REQUIRE CIPHER` 来指定，用于检查 X.509 certificate attributes。 -+ `REQUIRE SUBJECT`：指定用户在连接时需要提供客户端证书的 `subject` 内容。指定该选项后，不需要再配置 `require ssl` 或 x509。配置内容对应[生成客户端密钥和证书](#生成客户端密钥和证书)中的录入信息。 ++ `REQUIRE SUBJECT`：指定用户在连接时需要提供客户端证书的 `subject` 内容。指定该选项后，不需要再配置 `REQUIRE SSL` 或 `REQUIRE X509`。配置内容对应[生成客户端密钥和证书](#生成客户端密钥和证书)中的录入信息。 可以执行以下命令来获取该项的信息： - {{< copyable "shell-regular" >}} - ``` openssl x509 -noout -subject -in client-cert.pem | sed 's/.\{8\}//' | sed 's/, /\//g' | sed 's/ = /=/g' | sed 's/^/\//' ``` @@ -274,8 +241,6 @@ mysql -utest -h0.0.0.0 -P4000 --ssl-cert /path/to/client-cert.new.pem --ssl-key 可以执行以下命令来获取该项的信息： - {{< copyable "shell-regular" >}} - ``` openssl x509 -noout -subject -in ca-cert.pem | sed 's/.\{8\}//' | sed 's/, /\//g' | sed 's/ = /=/g' | sed 's/^/\//' ``` @@ -284,8 +249,6 @@ mysql -utest -h0.0.0.0 -P4000 --ssl-cert /path/to/client-cert.new.pem --ssl-key + 可以执行以下命令来获取已生成证书中的 `REQUIRE SAN` 项的信息： - {{< copyable "shell-regular" >}} - ```shell openssl x509 -noout -extensions subjectAltName -in client.crt ``` @@ -298,8 +261,6 @@ mysql -utest -h0.0.0.0 -P4000 --ssl-cert /path/to/client-cert.new.pem --ssl-key + 多个检查项可通过逗号连接后进行配置。例如，对用户 `u1` 进行以下配置： - {{< copyable "sql" >}} - ```sql CREATE USER 'u1'@'%' REQUIRE SAN 'DNS:d1,URI:spiffe://example.org/myservice1,URI:spiffe://example.org/myservice2'; ``` @@ -318,16 +279,12 @@ mysql -utest -h0.0.0.0 -P4000 --ssl-cert /path/to/client-cert.new.pem --ssl-key + 可以在创建用户 (`CREATE USER`) 时配置登录时需要校验的证书信息： - {{< copyable "sql" >}} - ```sql CREATE USER 'u1'@'%' REQUIRE ISSUER '' SUBJECT '' SAN '' CIPHER ''; ``` + 可以在修改已有用户 (`ALTER USER`) 时配置登录时需要校验的证书信息： - {{< copyable "sql" >}} - ```sql ALTER USER 'u1'@'%' REQUIRE ISSUER '' SUBJECT '' SAN '' CIPHER ''; ``` @@ -336,7 +293,7 @@ mysql -utest -h0.0.0.0 -P4000 --ssl-cert /path/to/client-cert.new.pem --ssl-key + 使用 SSL 登录，且证书为服务器配置的 CA 证书所签发 + 证书的 `issuer` 信息和权限配置里的 `REQUIRE ISSUER` 信息相匹配 -+ 证书的 `subject` 信息和权限配置里的 `REQUIRE CIPHER` 信息相匹配 ++ 连接使用的加密套件与 `REQUIRE CIPHER` 中指定的套件一致。 + 证书的 `Subject Alternative Name` 信息和权限配置里的 `REQUIRE SAN` 信息相匹配 全部验证通过后用户才能登录，否则会报 `ERROR 1045 (28000): Access denied` 错误。登录后，可以通过以下命令来查看当前链接是否使用证书登录、TLS 版本和 Cipher 算法。 @@ -351,7 +308,7 @@ mysql -utest -h0.0.0.0 -P4000 --ssl-cert /path/to/client-cert.new.pem --ssl-key ``` -------------- -mysql Ver 8.4.0 for Linux on x86_64 (MySQL Community Server - GPL) +mysql Ver {{{ .tidb-version }}} for Linux on x86_64 (MySQL Community Server - GPL) Connection id: 1 Current database: test @@ -391,8 +348,6 @@ CA 证书是客户端和服务端相互校验的依据，所以如果需要替 1. 以替换 CA 密钥为例（假设 `ca-key.pem` 被盗），将旧的 CA 密钥和证书进行备份： - {{< copyable "shell-regular" >}} - ```bash mv ca-key.pem ca-key.old.pem && \ mv ca-cert.pem ca-cert.old.pem @@ -400,28 +355,22 @@ CA 证书是客户端和服务端相互校验的依据，所以如果需要替 2. 生成新的 CA 密钥： - {{< copyable "shell-regular" >}} - ```bash sudo openssl genrsa 2048 > ca-key.pem ``` 3. 用新的密钥生成新的 CA 证书： - {{< copyable "shell-regular" >}} - ```bash sudo openssl req -new -x509 -nodes -days 365000 -key ca-key.pem -out ca-cert.new.pem ``` > **注意：** > - > 生成新的 CA 证书是为了替换密钥和证书，保证在线用户不受影响。所以以上命令中填写的附加信息必须与已配置的 `require issuer` 信息一致。 + > 生成新的 CA 证书是为了替换密钥和证书，保证在线用户不受影响。所以以上命令中填写的附加信息必须与已配置的 `REQUIRE ISSUER` 信息一致。 4. 生成组合 CA 证书： - {{< copyable "shell-regular" >}} - ```bash cat ca-cert.new.pem ca-cert.old.pem > ca-cert.pem ``` @@ -438,8 +387,6 @@ CA 证书是客户端和服务端相互校验的依据，所以如果需要替 1. 生成新的客户端 RSA 密钥： - {{< copyable "shell-regular" >}} - ```bash sudo openssl req -newkey rsa:2048 -days 365000 -nodes -keyout client-key.new.pem -out client-req.new.pem && \ sudo openssl rsa -in client-key.new.pem -out client-key.new.pem @@ -447,22 +394,18 @@ CA 证书是客户端和服务端相互校验的依据，所以如果需要替 > **注意：** > - > 以上命令是为了替换密钥和证书，保证在线用户不受影响，所以以上命令中填写的附加信息必须与已配置的 `require subject` 信息一致。 + > 以上命令是为了替换密钥和证书，保证在线用户不受影响，所以以上命令中填写的附加信息必须与已配置的 `REQUIRE SUBJECT` 信息一致。 2. 使用新的组合 CA 证书和新 CA 密钥生成新客户端证书： - {{< copyable "shell-regular" >}} - ```bash sudo openssl x509 -req -in client-req.new.pem -days 365000 -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out client-cert.new.pem ``` 3. 让客户端使用新的客户端密钥和证书来连接 TiDB （以 MySQL 客户端为例）： - {{< copyable "shell-regular" >}} - ```bash - mysql -utest -h0.0.0.0 -P4000 --ssl-cert /path/to/client-cert.new.pem --ssl-key /path/to/client-key.new.pem --ssl-ca /path/to/ca-cert.pem + mysql -u test -h 0.0.0.0 -P 4000 --ssl-cert /path/to/client-cert.new.pem --ssl-key /path/to/client-key.new.pem --ssl-ca /path/to/ca-cert.pem ``` > **注意：** @@ -473,8 +416,6 @@ CA 证书是客户端和服务端相互校验的依据，所以如果需要替 1. 生成新的服务端 RSA 密钥： - {{< copyable "shell-regular" >}} - ```bash sudo openssl req -newkey rsa:2048 -days 365000 -nodes -keyout server-key.new.pem -out server-req.new.pem && \ sudo openssl rsa -in server-key.new.pem -out server-key.new.pem @@ -482,14 +423,16 @@ CA 证书是客户端和服务端相互校验的依据，所以如果需要替 2. 使用新的组合 CA 证书和新 CA 密钥生成新服务端证书： - {{< copyable "shell-regular" >}} - ```bash sudo openssl x509 -req -in server-req.new.pem -days 365000 -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out server-cert.new.pem ``` -3. 配置 TiDB 使用上面新生成的服务端密钥和证书并重启。参见[配置 TiDB 服务端](#配置-tidb-服务端)。 +3. 配置 TiDB 使用上面新生成的服务端密钥和证书并重启。将文件放置在[配置 TiDB 服务端](#配置-tidb-服务端)一节中指定的目录中。 + + ```sql + ALTER INSTANCE RELOAD TLS; + ``` ## 基于策略的证书访问控制 -TiDB 支持基于策略的证书访问控制 (PBAC)，利用底层密钥管理服务器定义的策略。这使得用户能够根据各种条件进行细粒度的访问控制，例如基于时间的策略（如证书仅在特定时间段内有效）、基于位置的策略（如限制对特定地理位置的访问）以及其他可自定义的条件，从而确保在证书管理中提供更高的安全性和灵活性。 \ No newline at end of file +TiDB 支持基于策略的证书访问控制 (PBAC)，利用底层密钥管理服务器定义的策略。这使得用户能够根据各种条件进行细粒度的访问控制，例如基于时间的策略（如证书仅在特定时间段内有效）、基于位置的策略（如限制对特定地理位置的访问）以及其他可自定义的条件，从而确保在证书管理中提供更高的安全性和灵活性。 diff --git a/character-set-and-collation.md b/character-set-and-collation.md index 87083a2e4010..8a98f6639846 100644 --- a/character-set-and-collation.md +++ b/character-set-and-collation.md @@ -1,6 +1,5 @@ --- title: 字符集和排序规则 -aliases: ['/docs-cn/dev/character-set-and-collation/','/docs-cn/dev/reference/sql/characterset-and-collation/','/docs-cn/dev/reference/sql/character-set/'] summary: TiDB 支持的字符集包括 ascii、binary、gbk、latin1、utf8 和 utf8mb4。排序规则包括 ascii_bin、binary、gbk_bin、gbk_chinese_ci、latin1_bin、utf8_bin、utf8_general_ci、utf8_unicode_ci、utf8mb4_0900_ai_ci、utf8mb4_0900_bin、utf8mb4_bin、utf8mb4_general_ci 和 utf8mb4_unicode_ci。TiDB 强烈建议使用 utf8mb4 字符集，因为它支持更多字符。在 TiDB 中，默认的排序规则受到客户端的连接排序规则设置的影响。如果客户端使用 utf8mb4_0900_ai_ci 作为连接排序规则，TiDB 将遵循客户端的配置。TiDB 还支持新的排序规则框架，用于在语义上支持不同的排序规则。 --- @@ -14,8 +13,6 @@ summary: TiDB 支持的字符集包括 ascii、binary、gbk、latin1、utf8 和 排序规则 (collation) 是在字符集中比较字符以及字符排序顺序的规则。例如，在二进制排序规则中，比较 `A` 和 `a` 的结果是不一样的： -{{< copyable "sql" >}} - ```sql SET NAMES utf8mb4 COLLATE utf8mb4_bin; SELECT 'A' = 'a'; @@ -27,7 +24,7 @@ SELECT 'A' = 'a'; SELECT 'A' = 'a'; ``` -```sql +``` +-----------+ | 'A' = 'a' | +-----------+ @@ -40,7 +37,7 @@ SELECT 'A' = 'a'; SET NAMES utf8mb4 COLLATE utf8mb4_general_ci; ``` -```sql +``` Query OK, 0 rows affected (0.00 sec) ``` @@ -48,7 +45,7 @@ Query OK, 0 rows affected (0.00 sec) SELECT 'A' = 'a'; ``` -```sql +``` +-----------+ | 'A' = 'a' | +-----------+ @@ -57,23 +54,56 @@ SELECT 'A' = 'a'; 1 row in set (0.00 sec) ``` +以下示例展示了不同 Unicode 排序规则如何比较德语中的 `ß` 和 `ss`。可以看到，只有较为严格的 Unicode 排序规则会将它们视为等价，从而返回 `1`（表示 TRUE）。 + +```sql +SELECT + 'ss' COLLATE utf8mb4_general_ci = 'ß', + 'ss' COLLATE utf8mb4_unicode_ci = 'ß', + 'ss' COLLATE utf8mb4_0900_ai_ci = 'ß', + 'ss' COLLATE utf8mb4_0900_bin = 'ß' +\G +``` + +``` +*************************** 1. row *************************** +'ss' COLLATE utf8mb4_general_ci = 'ß': 0 +'ss' COLLATE utf8mb4_unicode_ci = 'ß': 1 +'ss' COLLATE utf8mb4_0900_ai_ci = 'ß': 1 + 'ss' COLLATE utf8mb4_0900_bin = 'ß': 0 +1 row in set (0.01 sec) +``` + +### 字符集和排序规则的命名 + +一个字符集可以有多种排序规则。排序规则的命名格式为 `_`。例如，`utf8mb4` 字符集有一个名为 `utf8mb4_bin` 的排序规则，它是 `utf8mb4` 字符集的二进制排序规则。排序规则名称中可以包含多个属性 (collation properties)，以 `_` 进行分隔。 + +下表介绍了字符集和排序规则的后缀和含义。 + +| 后缀 | 含义 | +|---|---| +| `_bin` | 二进制排序规则 | +| `_ci` | 不区分大小写 | +| `_ai_ci` | 不区分重音和大小写 | +| `_0900_bin` | Unicode UCA 9.0.0，二进制排序规则 | +| `_unicode_ci` | （较旧的）Unicode UCA 排序规则，不区分大小写 | +| `_general_ci` | 较宽松的 Unicode 排序规则，不区分大小写 | + ## 支持的字符集和排序规则 目前 TiDB 支持以下字符集： -{{< copyable "sql" >}} - ```sql SHOW CHARACTER SET; ``` -```sql +``` +---------+-------------------------------------+-------------------+--------+ | Charset | Description | Default collation | Maxlen | +---------+-------------------------------------+-------------------+--------+ | ascii | US ASCII | ascii_bin | 1 | | binary | binary | binary | 1 | -| gbk | Chinese Internal Code Specification | gbk_bin | 2 | +| gbk | Chinese Internal Code Specification | gbk_chinese_ci | 2 | | latin1 | Latin1 | latin1_bin | 1 | | utf8 | UTF-8 Unicode | utf8_bin | 3 | | utf8mb4 | UTF-8 Unicode | utf8mb4_bin | 4 | @@ -87,24 +117,24 @@ TiDB 支持以下排序规则： SHOW COLLATION; ``` -```sql -+--------------------+---------+------+---------+----------+---------+ -| Collation | Charset | Id | Default | Compiled | Sortlen | -+--------------------+---------+------+---------+----------+---------+ -| ascii_bin | ascii | 65 | Yes | Yes | 1 | -| binary | binary | 63 | Yes | Yes | 1 | -| gbk_bin | gbk | 87 | | Yes | 1 | -| gbk_chinese_ci | gbk | 28 | Yes | Yes | 1 | -| latin1_bin | latin1 | 47 | Yes | Yes | 1 | -| utf8_bin | utf8 | 83 | Yes | Yes | 1 | -| utf8_general_ci | utf8 | 33 | | Yes | 1 | -| utf8_unicode_ci | utf8 | 192 | | Yes | 1 | -| utf8mb4_0900_ai_ci | utf8mb4 | 255 | | Yes | 1 | -| utf8mb4_0900_bin | utf8mb4 | 309 | | Yes | 1 | -| utf8mb4_bin | utf8mb4 | 46 | Yes | Yes | 1 | -| utf8mb4_general_ci | utf8mb4 | 45 | | Yes | 1 | -| utf8mb4_unicode_ci | utf8mb4 | 224 | | Yes | 1 | -+--------------------+---------+------+---------+----------+---------+ +``` ++--------------------+---------+-----+---------+----------+---------+---------------+ +| Collation | Charset | Id | Default | Compiled | Sortlen | Pad_attribute | ++--------------------+---------+-----+---------+----------+---------+---------------+ +| ascii_bin | ascii | 65 | Yes | Yes | 1 | PAD SPACE | +| binary | binary | 63 | Yes | Yes | 1 | NO PAD | +| gbk_bin | gbk | 87 | | Yes | 1 | PAD SPACE | +| gbk_chinese_ci | gbk | 28 | Yes | Yes | 1 | PAD SPACE | +| latin1_bin | latin1 | 47 | Yes | Yes | 1 | PAD SPACE | +| utf8_bin | utf8 | 83 | Yes | Yes | 1 | PAD SPACE | +| utf8_general_ci | utf8 | 33 | | Yes | 1 | PAD SPACE | +| utf8_unicode_ci | utf8 | 192 | | Yes | 8 | PAD SPACE | +| utf8mb4_0900_ai_ci | utf8mb4 | 255 | | Yes | 0 | NO PAD | +| utf8mb4_0900_bin | utf8mb4 | 309 | | Yes | 1 | NO PAD | +| utf8mb4_bin | utf8mb4 | 46 | Yes | Yes | 1 | PAD SPACE | +| utf8mb4_general_ci | utf8mb4 | 45 | | Yes | 1 | PAD SPACE | +| utf8mb4_unicode_ci | utf8mb4 | 224 | | Yes | 8 | PAD SPACE | ++--------------------+---------+-----+---------+----------+---------+---------------+ 13 rows in set (0.00 sec) ``` @@ -122,32 +152,32 @@ SHOW COLLATION; 利用以下的语句可以查看字符集对应的排序规则（以下是[新的排序规则框架](#新框架下的排序规则支持)）下的结果： -{{< copyable "sql" >}} - ```sql SHOW COLLATION WHERE Charset = 'utf8mb4'; ``` -```sql -+--------------------+---------+------+---------+----------+---------+ -| Collation | Charset | Id | Default | Compiled | Sortlen | -+--------------------+---------+------+---------+----------+---------+ -| utf8mb4_0900_ai_ci | utf8mb4 | 255 | | Yes | 1 | -| utf8mb4_0900_bin | utf8mb4 | 309 | | Yes | 1 | -| utf8mb4_bin | utf8mb4 | 46 | Yes | Yes | 1 | -| utf8mb4_general_ci | utf8mb4 | 45 | | Yes | 1 | -| utf8mb4_unicode_ci | utf8mb4 | 224 | | Yes | 1 | -+--------------------+---------+------+---------+----------+---------+ -5 rows in set (0.00 sec) +``` ++--------------------+---------+-----+---------+----------+---------+---------------+ +| Collation | Charset | Id | Default | Compiled | Sortlen | Pad_attribute | ++--------------------+---------+-----+---------+----------+---------+---------------+ +| utf8mb4_0900_ai_ci | utf8mb4 | 255 | | Yes | 0 | NO PAD | +| utf8mb4_0900_bin | utf8mb4 | 309 | | Yes | 1 | NO PAD | +| utf8mb4_bin | utf8mb4 | 46 | Yes | Yes | 1 | PAD SPACE | +| utf8mb4_general_ci | utf8mb4 | 45 | | Yes | 1 | PAD SPACE | +| utf8mb4_unicode_ci | utf8mb4 | 224 | | Yes | 8 | PAD SPACE | ++--------------------+---------+-----+---------+----------+---------+---------------+ +5 rows in set (0.001 sec) ``` TiDB 对 GBK 字符集的支持详情见 [GBK](/character-set-gbk.md)。 ## TiDB 中的 `utf8` 和 `utf8mb4` -MySQL 限制字符集 `utf8` 为最多 3 个字节。这足以存储在基本多语言平面 (BMP) 中的字符，但不足以存储表情符号 (emoji) 等字符。因此，建议改用字符集`utf8mb4`。 +MySQL 限制字符集 `utf8` 为最多 3 个字节。这足以存储在基本多语言平面 (Basic Multilingual Plane, BMP) 中的字符，但不足以存储表情符号 (emoji) 等字符。对于新安装的系统，建议使用 `utf8mb4` 字符集，并逐步迁移停止使用 `utf8`。 + +在 MySQL 和 TiDB 中，`utf8` 和 `utf8mb3` 是同一字符集的别名。 -默认情况下，TiDB 同样限制字符集 `utf8` 为最多 3 个字节，以确保 TiDB 中创建的数据可以在 MySQL 中顺利恢复。你可以禁用此功能，方法是将系统变量 [`tidb_check_mb4_value_in_utf8`](/system-variables.md#tidb_check_mb4_value_in_utf8) 的值更改为 `OFF`。 +默认情况下，TiDB 也将 `utf8` 字符集限制为最多 3 个字节，以确保在 TiDB 中创建的数据仍能安全地恢复到 MySQL 中。尽管你可以通过将系统变量 [`tidb_check_mb4_value_in_utf8`](/system-variables.md#tidb_check_mb4_value_in_utf8) 的值更改为 `OFF` 来禁用此限制，但建议使用 `utf8mb4` 以获得完整的 Unicode 支持和更好的兼容性。 以下示例演示了在表中插入 4 字节的表情符号字符（emoji 字符）时的默认行为。`utf8` 字符集下 `INSERT` 语句不能执行，`utf8mb4` 字符集下可以执行 `INSERT` 语句： @@ -157,7 +187,7 @@ CREATE TABLE utf8_test ( ) CHARACTER SET utf8; ``` -```sql +``` Query OK, 0 rows affected (0.09 sec) ``` @@ -167,7 +197,7 @@ CREATE TABLE utf8m4_test ( ) CHARACTER SET utf8mb4; ``` -```sql +``` Query OK, 0 rows affected (0.09 sec) ``` @@ -175,7 +205,7 @@ Query OK, 0 rows affected (0.09 sec) INSERT INTO utf8_test VALUES ('😉'); ``` -```sql +``` ERROR 1366 (HY000): incorrect utf8 value f09f9889(😉) for column c ``` @@ -183,7 +213,7 @@ ERROR 1366 (HY000): incorrect utf8 value f09f9889(😉) for column c INSERT INTO utf8m4_test VALUES ('😉'); ``` -```sql +``` Query OK, 1 row affected (0.02 sec) ``` @@ -191,7 +221,7 @@ Query OK, 1 row affected (0.02 sec) SELECT char_length(c), length(c), c FROM utf8_test; ``` -```sql +``` Empty set (0.01 sec) ``` @@ -199,7 +229,7 @@ Empty set (0.01 sec) SELECT char_length(c), length(c), c FROM utf8m4_test; ``` -```sql +``` +----------------+-----------+------+ | char_length(c) | length(c) | c | +----------------+-----------+------+ @@ -232,18 +262,14 @@ ALTER DATABASE db_name 通过系统变量 `character_set_database` 和 `collation_database` 可以查看到当前数据库的字符集以及排序规则： -{{< copyable "sql" >}} - ```sql CREATE SCHEMA test1 CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; ``` -```sql +``` Query OK, 0 rows affected (0.09 sec) ``` -{{< copyable "sql" >}} - ```sql USE test1; ``` @@ -252,13 +278,11 @@ USE test1; Database changed ``` -{{< copyable "sql" >}} - ```sql SELECT @@character_set_database, @@collation_database; ``` -```sql +``` +--------------------------|----------------------+ | @@character_set_database | @@collation_database | +--------------------------|----------------------+ @@ -267,33 +291,27 @@ SELECT @@character_set_database, @@collation_database; 1 row in set (0.00 sec) ``` -{{< copyable "sql" >}} - ```sql CREATE SCHEMA test2 CHARACTER SET latin1 COLLATE latin1_bin; ``` -```sql +``` Query OK, 0 rows affected (0.09 sec) ``` -{{< copyable "sql" >}} - ```sql USE test2; ``` -```sql +``` Database changed ``` -{{< copyable "sql" >}} - ```sql SELECT @@character_set_database, @@collation_database; ``` -```sql +``` +--------------------------|----------------------+ | @@character_set_database | @@collation_database | +--------------------------|----------------------+ @@ -304,8 +322,6 @@ SELECT @@character_set_database, @@collation_database; 在 INFORMATION_SCHEMA 中也可以查看到这两个值： -{{< copyable "sql" >}} - ```sql SELECT DEFAULT_CHARACTER_SET_NAME, DEFAULT_COLLATION_NAME FROM INFORMATION_SCHEMA.SCHEMATA WHERE SCHEMA_NAME = 'db_name'; @@ -327,13 +343,11 @@ ALTER TABLE tbl_name 例如： -{{< copyable "sql" >}} - ```sql CREATE TABLE t1(a int) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; ``` -```sql +``` Query OK, 0 rows affected (0.08 sec) ``` @@ -365,8 +379,6 @@ col_name {ENUM | SET} (val_list) 示例如下： -{{< copyable "sql" >}} - ```sql SELECT 'string'; SELECT _utf8mb4'string'; @@ -394,8 +406,6 @@ SELECT _utf8mb4'string' COLLATE utf8mb4_general_ci; `SET NAMES` 用来设定客户端会在之后的请求中使用的字符集。`SET NAMES utf8mb4` 表示客户端会在接下来的请求中，都使用 utf8mb4 字符集。服务端也会在之后返回结果的时候使用 utf8mb4 字符集。`SET NAMES 'charset_name'` 语句其实等于下面语句的组合： - {{< copyable "sql" >}} - ```sql SET character_set_client = charset_name; SET character_set_results = charset_name; @@ -408,8 +418,6 @@ SELECT _utf8mb4'string' COLLATE utf8mb4_general_ci; 跟 `SET NAMES` 类似，等价于下面语句的组合： - {{< copyable "sql" >}} - ```sql SET character_set_client = charset_name; SET character_set_results = charset_name; @@ -451,13 +459,11 @@ SELECT _utf8mb4'string' COLLATE utf8mb4_general_ci; 在 4.0 版本之前，TiDB 中可以指定大部分 MySQL 中的排序规则，并把这些排序规则按照默认排序规则处理，即以编码字节序为字符定序。和 MySQL 不同的是，TiDB 不会处理字符末尾的空格，因此会造成以下的行为区别： -{{< copyable "sql" >}} - ```sql CREATE TABLE t(a varchar(20) charset utf8mb4 collate utf8mb4_general_ci PRIMARY KEY); ``` -```sql +``` Query OK, 0 rows affected ``` @@ -465,7 +471,7 @@ Query OK, 0 rows affected INSERT INTO t VALUES ('A'); ``` -```sql +``` Query OK, 1 row affected ``` @@ -473,7 +479,7 @@ Query OK, 1 row affected INSERT INTO t VALUES ('a'); ``` -```sql +``` Query OK, 1 row affected ``` @@ -483,7 +489,7 @@ Query OK, 1 row affected INSERT INTO t VALUES ('a '); ``` -```sql +``` Query OK, 1 row affected ``` @@ -499,13 +505,11 @@ TiDB 4.0 新增了完整的排序规则支持框架，从语义上支持了排 > > 当 `mysql.tidb` 表查询结果和 `new_collations_enabled_on_first_bootstrap` 的值不同时，以 `mysql.tidb` 表的结果为准。 -{{< copyable "sql" >}} - ```sql SELECT VARIABLE_VALUE FROM mysql.tidb WHERE VARIABLE_NAME='new_collation_enabled'; ``` -```sql +``` +----------------+ | VARIABLE_VALUE | +----------------+ @@ -518,13 +522,11 @@ SELECT VARIABLE_VALUE FROM mysql.tidb WHERE VARIABLE_NAME='new_collation_enabled 使用 `utf8_general_ci`、`utf8mb4_general_ci`、`utf8_unicode_ci`、`utf8mb4_unicode_ci`、`utf8mb4_0900_ai_ci` 和 `gbk_chinese_ci` 中任一种时，字符串之间的比较是大小写不敏感 (case-insensitive) 和口音不敏感 (accent-insensitive) 的。同时，TiDB 还修正了排序规则的 `PADDING` 行为： -{{< copyable "sql" >}} - ```sql CREATE TABLE t(a varchar(20) charset utf8mb4 collate utf8mb4_general_ci PRIMARY KEY); ``` -```sql +``` Query OK, 0 rows affected (0.00 sec) ``` @@ -532,7 +534,7 @@ Query OK, 0 rows affected (0.00 sec) INSERT INTO t VALUES ('A'); ``` -```sql +``` Query OK, 1 row affected (0.00 sec) ``` @@ -540,7 +542,7 @@ Query OK, 1 row affected (0.00 sec) INSERT INTO t VALUES ('a'); ``` -```sql +``` ERROR 1062 (23000): Duplicate entry 'a' for key 't.PRIMARY' ``` @@ -550,7 +552,7 @@ TiDB 兼容了 MySQL 的 case insensitive collation。 INSERT INTO t VALUES ('a '); ``` -```sql +``` ERROR 1062 (23000): Duplicate entry 'a ' for key 't.PRIMARY' ``` @@ -585,13 +587,11 @@ binary > utf8mb4_bin > (utf8mb4_general_ci = utf8mb4_unicode_ci) > utf8_bin > (u TiDB 支持使用 `COLLATE` 子句来指定一个表达式的排序规则，该表达式的 coercibility 值为 `0`，具有最高的优先级。示例如下： -{{< copyable "sql" >}} - ```sql SELECT 'a' = _utf8mb4 'A' collate utf8mb4_general_ci; ``` -```sql +``` +-----------------------------------------------+ | 'a' = _utf8mb4 'A' collate utf8mb4_general_ci | +-----------------------------------------------+ diff --git a/character-set-gbk.md b/character-set-gbk.md index 6c99cc3bbcec..28c072d44f8e 100644 --- a/character-set-gbk.md +++ b/character-set-gbk.md @@ -7,22 +7,33 @@ summary: 本文介绍 TiDB 对 GBK 字符集的支持情况。 TiDB 从 v5.4.0 开始支持 GBK 字符集。本文档介绍 TiDB 对 GBK 字符集的支持和兼容情况。 +从 TiDB v6.0.0 开始，[新的排序规则框架](/character-set-and-collation.md#新框架下的排序规则支持)默认启用，即 TiDB GBK 字符集的默认排序规则为 `gbk_chinese_ci`，与 MySQL 保持一致。 + ```sql SHOW CHARACTER SET WHERE CHARSET = 'gbk'; +``` + +``` +---------+-------------------------------------+-------------------+--------+ | Charset | Description | Default collation | Maxlen | +---------+-------------------------------------+-------------------+--------+ -| gbk | Chinese Internal Code Specification | gbk_bin | 2 | +| gbk | Chinese Internal Code Specification | gbk_chinese_ci | 2 | +---------+-------------------------------------+-------------------+--------+ 1 row in set (0.00 sec) +``` +```sql SHOW COLLATION WHERE CHARSET = 'gbk'; -+----------------+---------+------+---------+----------+---------+ -| Collation | Charset | Id | Default | Compiled | Sortlen | -+----------------+---------+------+---------+----------+---------+ -| gbk_bin | gbk | 87 | | Yes | 1 | -+----------------+---------+------+---------+----------+---------+ -1 rows in set (0.00 sec) +``` + +``` ++----------------+---------+----+---------+----------+---------+---------------+ +| Collation | Charset | Id | Default | Compiled | Sortlen | Pad_attribute | ++----------------+---------+----+---------+----------+---------+---------------+ +| gbk_bin | gbk | 87 | | Yes | 1 | PAD SPACE | +| gbk_chinese_ci | gbk | 28 | Yes | Yes | 1 | PAD SPACE | ++----------------+---------+----+---------+----------+---------+---------------+ +2 rows in set (0.00 sec) ``` ## 与 MySQL 的兼容性 @@ -31,30 +42,12 @@ SHOW COLLATION WHERE CHARSET = 'gbk'; ### 排序规则兼容性 -MySQL 的字符集默认排序规则是 `gbk_chinese_ci`。与 MySQL 不同，TiDB GBK 字符集的默认排序规则为 `gbk_bin`。另外，TiDB 支持的 `gbk_bin` 与 MySQL 支持的 `gbk_bin` 排序规则也不一致，TiDB 是将 GBK 转换成 UTF8MB4 然后做二进制排序。 - -如果要使 TiDB 兼容 MySQL 的 GBK 字符集排序规则，你需要在初次初始化 TiDB 集群时设置 TiDB 配置项[`new_collations_enabled_on_first_bootstrap`](/tidb-configuration-file.md#new_collations_enabled_on_first_bootstrap) 为 `true` 来开启[新的排序规则框架](/character-set-and-collation.md#新框架下的排序规则支持)。 - -开启新的排序规则框架后，如果查看 GBK 字符集对应的排序规则，你可以看到 TiDB GBK 默认排序规则已经切换为 `gbk_chinese_ci`。 +MySQL 的 GBK 字符集默认排序规则是 `gbk_chinese_ci`。TiDB 的 GBK 字符集的默认排序规则取决于 TiDB 配置项 [`new_collations_enabled_on_first_bootstrap`](/tidb-configuration-file.md#new_collations_enabled_on_first_bootstrap) 的值： -```sql -SHOW CHARACTER SET WHERE CHARSET = 'gbk'; -+---------+-------------------------------------+-------------------+--------+ -| Charset | Description | Default collation | Maxlen | -+---------+-------------------------------------+-------------------+--------+ -| gbk | Chinese Internal Code Specification | gbk_chinese_ci | 2 | -+---------+-------------------------------------+-------------------+--------+ -1 row in set (0.00 sec) +- 默认情况下，TiDB 配置项 [`new_collations_enabled_on_first_bootstrap`](/tidb-configuration-file.md#new_collations_enabled_on_first_bootstrap) 为 `true`，表示开启[新的排序规则框架](/character-set-and-collation.md#新框架下的排序规则支持)。GBK 字符集的默认排序规则是 `gbk_chinese_ci`。 +- 当 TiDB 配置项 [`new_collations_enabled_on_first_bootstrap`](/tidb-configuration-file.md#new_collations_enabled_on_first_bootstrap) 为 `false` 时，表示关闭新的排序规则框架，GBK 字符集的默认排序规则是 `gbk_bin`。 -SHOW COLLATION WHERE CHARSET = 'gbk'; -+----------------+---------+------+---------+----------+---------+ -| Collation | Charset | Id | Default | Compiled | Sortlen | -+----------------+---------+------+---------+----------+---------+ -| gbk_bin | gbk | 87 | | Yes | 1 | -| gbk_chinese_ci | gbk | 28 | Yes | Yes | 1 | -+----------------+---------+------+---------+----------+---------+ -2 rows in set (0.00 sec) -``` +另外，TiDB 支持的 `gbk_bin` 与 MySQL 支持的 `gbk_bin` 排序规则不一致，TiDB 是将 GBK 转换成 `utf8mb4`，然后再进行二进制排序。 ### 非法字符兼容性 @@ -98,4 +91,9 @@ SHOW COLLATION WHERE CHARSET = 'gbk'; * TiCDC 在 v6.1.0 之前不支持同步 `charset=GBK` 的表。另外，任何版本的 TiCDC 都不支持同步 `charset=GBK` 的表到 6.1.0 之前的 TiDB 集群。 -* TiDB Backup & Restore（BR）在 v5.4.0 之前不支持恢复 `charset=GBK` 的表。另外，任何版本的 BR 都不支持恢复 `charset=GBK` 的表到 5.4.0 之前的 TiDB 集群。 \ No newline at end of file +* TiDB Backup & Restore（BR）在 v5.4.0 之前不支持恢复 `charset=GBK` 的表。另外，任何版本的 BR 都不支持恢复 `charset=GBK` 的表到 5.4.0 之前的 TiDB 集群。 + +## 另请参阅 + +* [`SHOW CHARACTER SET`](/sql-statements/sql-statement-show-character-set.md) +* [字符集和排序规则](/character-set-and-collation.md) diff --git a/check-before-deployment.md b/check-before-deployment.md index b0634db7eb8e..ad9ee6f4b368 100644 --- a/check-before-deployment.md +++ b/check-before-deployment.md @@ -1,7 +1,6 @@ --- title: TiDB 环境与系统配置检查 summary: 了解部署 TiDB 前的环境检查操作。 -aliases: ['/docs-cn/dev/check-before-deployment/'] --- # TiDB 环境与系统配置检查 @@ -22,8 +21,6 @@ aliases: ['/docs-cn/dev/check-before-deployment/'] 1. 查看数据盘。 - {{< copyable "shell-root" >}} - ```bash fdisk -l ``` @@ -34,8 +31,6 @@ aliases: ['/docs-cn/dev/check-before-deployment/'] 2. 创建分区。 - {{< copyable "shell-root" >}} - ```bash parted -s -a optimal /dev/nvme0n1 mklabel gpt -- mkpart primary ext4 1 -1 ``` @@ -53,8 +48,6 @@ aliases: ['/docs-cn/dev/check-before-deployment/'] 3. 格式化文件系统。 - {{< copyable "shell-root" >}} - ```bash mkfs.ext4 /dev/nvme0n1p1 ``` @@ -63,8 +56,6 @@ aliases: ['/docs-cn/dev/check-before-deployment/'] 本例中 `nvme0n1p1` 的 UUID 为 `c51eb23b-195c-4061-92a9-3fad812cc12f`。 - {{< copyable "shell-root" >}} - ```bash lsblk -f ``` @@ -82,8 +73,6 @@ aliases: ['/docs-cn/dev/check-before-deployment/'] 5. 编辑 `/etc/fstab` 文件，添加 `nodelalloc` 挂载参数。 - {{< copyable "shell-root" >}} - ```bash vi /etc/fstab ``` @@ -94,8 +83,6 @@ aliases: ['/docs-cn/dev/check-before-deployment/'] 6. 挂载数据盘。 - {{< copyable "shell-root" >}} - ```bash mkdir /data1 && \ systemctl daemon-reload && \ @@ -104,8 +91,6 @@ aliases: ['/docs-cn/dev/check-before-deployment/'] 7. 执行以下命令，如果文件系统为 ext4，并且挂载参数中包含 `nodelalloc`，则表示已生效。 - {{< copyable "shell-root" >}} - ```bash mount -t ext4 ``` @@ -116,7 +101,7 @@ aliases: ['/docs-cn/dev/check-before-deployment/'] ## 检测及关闭系统 swap -TiDB 运行需要有足够的内存。如果想保持性能稳定，则建议永久关闭系统 swap，但可能在内存偏小时触发 OOM 问题；如果想避免此类 OOM 问题，则可只将 swap 优先级调低，但不做永久关闭。 +TiDB 需要充足的内存来运行。如果 TiDB 使用的内存被换出 (swapped out) 然后再换入 (swapped back in)，这可能会导致延迟激增。如果您想保持稳定的性能，建议永久禁用系统 swap，但可能在内存偏小时触发 OOM 问题。如果想避免此类 OOM 问题，则可只将 swap 优先级调低，但不做永久关闭。 - 开启并使用 swap 可能会引入性能抖动问题，对于低延迟、稳定性要求高的数据库服务，建议永久关闭操作系统层 swap。要永久关闭 swap，可使用以下方法： @@ -125,8 +110,8 @@ TiDB 运行需要有足够的内存。如果想保持性能稳定，则建议永 ```bash echo "vm.swappiness = 0">> /etc/sysctl.conf - swapoff -a sysctl -p + swapoff -a && swapon -a ``` - 如果主机内存偏小，关闭系统 swap 可能会更容易触发 OOM 问题，可参考以如下方法将 swap 优先级调低，但不做永久关闭： @@ -166,30 +151,28 @@ TiDB 的部分操作需要向服务器写入临时文件，因此需要确保运 > > 如果目录不存在，TiDB 在启动时会自动创建该目录。如果目录创建失败，或者 TiDB 对该目录没有读写权限，[Fast Online DDL](/system-variables.md#tidb_ddl_enable_fast_reorg-从-v630-版本开始引入) 在运行时会被禁用。 -## 检测及关闭目标部署机器的防火墙 +## 检测目标部署机器的防火墙 -本段介绍如何关闭目标主机防火墙配置，因为在 TiDB 集群中，需要将节点间的访问端口打通才可以保证读写请求、数据心跳等信息的正常的传输。在普遍线上场景中，数据库到业务服务和数据库节点的网络联通都是在安全域内完成数据交互。如果没有特殊安全的要求，建议将目标节点的防火墙进行关闭。否则建议[按照端口使用规则](/hardware-and-software-requirements.md#网络要求)，将端口信息配置到防火墙服务的白名单中。 +在 TiDB 集群中，必须将节点间的访问端口打通才可以保证读写请求、数据心跳等信息的正常的传输。在普遍线上场景中，数据库到业务服务和数据库节点的网络联通都是在安全域内完成数据交互。如果没有特殊安全的要求，建议将目标节点的防火墙进行关闭。如不关闭防火墙，建议[按照端口使用规则](/hardware-and-software-requirements.md#网络要求)，将端口信息配置到防火墙服务的白名单中。 -1. 检查防火墙状态（以 CentOS Linux release 7.7.1908 (Core) 为例） +### 停止并禁用防火墙 - {{< copyable "shell-regular" >}} +本节介绍如何停止并禁用目标部署机器的防火墙服务。 + +1. 检查防火墙状态（以 CentOS Linux release 7.7.1908 (Core) 为例） ```shell sudo firewall-cmd --state sudo systemctl status firewalld.service ``` -2. 关闭防火墙服务 - - {{< copyable "shell-regular" >}} +2. 停止防火墙服务 ```bash sudo systemctl stop firewalld.service ``` -3. 关闭防火墙自动启动服务 - - {{< copyable "shell-regular" >}} +3. 禁用防火墙自动启动服务 ```bash sudo systemctl disable firewalld.service @@ -197,12 +180,97 @@ TiDB 的部分操作需要向服务器写入临时文件，因此需要确保运 4. 检查防火墙状态 - {{< copyable "shell-regular" >}} - ```bash sudo systemctl status firewalld.service ``` +### 更改防火墙区域 + +如果不希望完全禁用防火墙，可以使用限制较少的区域。默认的 `public` 区域仅允许特定的服务和端口，而 `trusted` 区域默认允许所有流量。 + +将默认区域设置为 `trusted`： + +```bash +firewall-cmd --set-default-zone trusted +``` + +查看默认区域： + +```bash +firewall-cmd --get-default-zone +# trusted +``` + +列出某个区域的策略： + +```bash +firewall-cmd --zone=trusted --list-all +# trusted +# target: ACCEPT +# icmp-block-inversion: no +# interfaces: +# sources: +# services: +# ports: +# protocols: +# forward: yes +# masquerade: no +# forward-ports: +# source-ports: +# icmp-blocks: +# rich rules: +``` + +### 配置防火墙 + +使用以下命令为 TiDB 集群组件配置防火墙。这些示例仅供参考，请根据实际环境调整区域名称、端口和服务。 + +为 TiDB 组件配置防火墙： + +```bash +firewall-cmd --permanent --new-service tidb +firewall-cmd --permanent --service tidb --set-description="TiDB Server" +firewall-cmd --permanent --service tidb --set-short="TiDB" +firewall-cmd --permanent --service tidb --add-port=4000/tcp +firewall-cmd --permanent --service tidb --add-port=10080/tcp +firewall-cmd --permanent --zone=public --add-service=tidb +``` + +为 TiKV 组件配置防火墙： + +```bash +firewall-cmd --permanent --new-service tikv +firewall-cmd --permanent --service tikv --set-description="TiKV Server" +firewall-cmd --permanent --service tikv --set-short="TiKV" +firewall-cmd --permanent --service tikv --add-port=20160/tcp +firewall-cmd --permanent --service tikv --add-port=20180/tcp +firewall-cmd --permanent --zone=public --add-service=tikv +``` + +为 PD 组件配置防火墙： + +```bash +firewall-cmd --permanent --new-service pd +firewall-cmd --permanent --service pd --set-description="PD Server" +firewall-cmd --permanent --service pd --set-short="PD" +firewall-cmd --permanent --service pd --add-port=2379/tcp +firewall-cmd --permanent --service pd --add-port=2380/tcp +firewall-cmd --permanent --zone=public --add-service=pd +``` + +为 Prometheus 配置防火墙： + +```bash +firewall-cmd --permanent --zone=public --add-service=prometheus +firewall-cmd --permanent --service=prometheus --add-port=12020/tcp +``` + +为 Grafana 配置防火墙： + +```bash +firewall-cmd --permanent --zone=public --add-service=grafana +``` + ## 检测及安装 NTP 服务 TiDB 是一套分布式数据库系统，需要节点间保证时间的同步，从而确保 ACID 模型的事务线性一致性。目前解决授时的普遍方案是采用 NTP 服务，可以通过互联网中的 `pool.ntp.org` 授时服务来保证节点的时间同步，也可以使用离线环境自己搭建的 NTP 服务来解决授时。 @@ -211,8 +279,6 @@ TiDB 是一套分布式数据库系统，需要节点间保证时间的同步， 1. 执行以下命令，如果输出 `running` 表示 NTP 服务正在运行： - {{< copyable "shell-regular" >}} - ```bash sudo systemctl status ntpd.service ``` @@ -225,8 +291,6 @@ TiDB 是一套分布式数据库系统，需要节点间保证时间的同步， - 若返回报错信息 `Unit ntpd.service could not be found.`，请尝试执行以下命令，以查看与 NTP 进行时钟同步所使用的系统配置是 `chronyd` 还是 `ntpd`： - {{< copyable "shell-regular" >}} - ```bash sudo systemctl status chronyd.service ``` @@ -247,8 +311,6 @@ TiDB 是一套分布式数据库系统，需要节点间保证时间的同步， > > Ubuntu 系统需安装 `ntpstat` 软件包。 - {{< copyable "shell-regular" >}} - ```bash ntpstat ``` @@ -279,8 +341,6 @@ TiDB 是一套分布式数据库系统，需要节点间保证时间的同步， > > 该操作仅适用于使用 Chrony 的系统，不适用于使用 NTPd 的系统。 - {{< copyable "shell-regular" >}} - ```bash chronyc tracking ``` @@ -317,8 +377,6 @@ TiDB 是一套分布式数据库系统，需要节点间保证时间的同步， 如果要使 NTP 服务尽快开始同步，执行以下命令。可以将 `pool.ntp.org` 替换为你的 NTP 服务器： -{{< copyable "shell-regular" >}} - ```bash sudo systemctl stop ntpd.service && \ sudo ntpdate pool.ntp.org && \ @@ -327,8 +385,6 @@ sudo systemctl start ntpd.service 如果要在 CentOS 7 系统上手动安装 NTP 服务，可执行以下命令： -{{< copyable "shell-regular" >}} - ```bash sudo yum install ntp ntpdate && \ sudo systemctl start ntpd.service && \ @@ -339,20 +395,18 @@ sudo systemctl enable ntpd.service 在生产系统的 TiDB 中，建议对操作系统进行如下的配置优化： -1. 关闭透明大页（即 Transparent Huge Pages，缩写为 THP）。数据库的内存访问模式往往是稀疏的而非连续的。当高阶内存碎片化比较严重时，分配 THP 页面会出现较高的延迟。 -2. 设置存储介质的 I/O 调度器。 +- 关闭[内存——透明大页](/tune-operating-system.md#内存透明大页) (Transparent Huge Pages, THP)。数据库的内存访问通常较为稀疏，当高阶内存出现明显碎片化时，THP 分配可能导致较高的内存分配延迟，因此建议关闭 THP 以避免性能抖动。 +- 设置存储介质的 [I/O 调度器](/tune-operating-system.md#io-调度器)。 - 对于高速 SSD 存储介质，内核默认的 I/O 调度器可能会导致性能损失。建议将闪存存储的 I/O 调度器设置为先入先出 (First-in-first-out, FIFO) 的调度器，如 `noop` 或 `none`，这样内核将不做调度操作，直接将 I/O 请求传递给硬件，从而提升性能。 - 对于 NVMe 存储介质，默认的 I/O 调度器为 `none`，无需进行调整。 -3. 为调整 CPU 频率的 cpufreq 模块选用 performance 模式。将 CPU 频率固定在其支持的最高运行频率上，不进行动态调节，可获取最佳的性能。 +- 将动态调整 CPU 频率的 [cpufreq 模块](/tune-operating-system.md#处理器动态节能技术)设置为 `performance` 模式。该模式会将 CPU 频率固定在其支持的最高运行频率上，不进行动态调节，因此可获得最佳性能。 -采用如下步骤检查操作系统的当前配置，并配置系统优化参数： +具体的检查和配置步骤如下： 1. 执行以下命令查看透明大页的开启状态。 - {{< copyable "shell-regular" >}} - ```bash cat /sys/kernel/mm/transparent_hugepage/enabled ``` @@ -399,8 +453,6 @@ sudo systemctl enable ntpd.service 3. 执行以下命令查看磁盘的唯一标识 `ID_SERIAL`。 - {{< copyable "shell-regular" >}} - ```bash udevadm info --name=/dev/sdb | grep ID_SERIAL ``` @@ -417,8 +469,6 @@ sudo systemctl enable ntpd.service 4. 执行以下命令查看 cpufreq 模块选用的节能策略。 - {{< copyable "shell-regular" >}} - ```bash cpupower frequency-info --policy ``` @@ -439,8 +489,6 @@ sudo systemctl enable ntpd.service 1. 执行 `tuned-adm list` 命令查看当前操作系统的 tuned 策略。 - {{< copyable "shell-regular" >}} - ```bash tuned-adm list ``` @@ -464,8 +512,6 @@ sudo systemctl enable ntpd.service 2. 创建新的 tuned 策略。 - {{< copyable "shell-regular" >}} - ```bash mkdir /etc/tuned/balanced-tidb-optimal/ vi /etc/tuned/balanced-tidb-optimal/tuned.conf @@ -494,8 +540,6 @@ sudo systemctl enable ntpd.service > > 如果已经使用 `noop` 或 `none` I/O 调度器，则无需在 tuned 策略中配置调度器相关的内容，可以跳过此步骤。 - {{< copyable "shell-regular" >}} - ```bash tuned-adm profile balanced-tidb-optimal ``` @@ -508,8 +552,6 @@ sudo systemctl enable ntpd.service > > 需安装 `grubby` 软件包。 - {{< copyable "shell-regular" >}} - ```bash grubby --default-kernel ``` @@ -520,20 +562,16 @@ sudo systemctl enable ntpd.service 2. 执行 `grubby --update-kernel` 命令修改内核配置。 - {{< copyable "shell-regular" >}} - ```bash grubby --args="transparent_hugepage=never" --update-kernel `grubby --default-kernel` ``` > **注意：** > - > 你也可以在 `--update-kernel` 后指定实际的版本号，例如：`--update-kernel /boot/vmlinuz-3.10.0-957.el7.x86_64`。 + > 你也可以在 `--update-kernel` 后指定实际的版本号，例如：`--update-kernel /boot/vmlinuz-3.10.0-957.el7.x86_64` 或 `ALL`。 3. 执行 `grubby --info` 命令查看修改后的默认内核配置。 - {{< copyable "shell-regular" >}} - ```bash grubby --info /boot/vmlinuz-3.10.0-957.el7.x86_64 ``` @@ -553,8 +591,6 @@ sudo systemctl enable ntpd.service 4. 修改当前的内核配置立即关闭透明大页。 - {{< copyable "shell-regular" >}} - ```bash echo never > /sys/kernel/mm/transparent_hugepage/enabled echo never > /sys/kernel/mm/transparent_hugepage/defrag @@ -562,8 +598,6 @@ sudo systemctl enable ntpd.service 5. 配置 udev 脚本应用 IO 调度器策略。 - {{< copyable "shell-regular" >}} - ```bash vi /etc/udev/rules.d/60-tidb-schedulers.rules ``` @@ -580,8 +614,6 @@ sudo systemctl enable ntpd.service > > 对于已经使用 `noop` 或 `none` I/O 调度器的设备，无需配置 udev 规则，可以跳过此步骤。 - {{< copyable "shell-regular" >}} - ```bash udevadm control --reload-rules udevadm trigger --type=devices --action=change @@ -589,8 +621,6 @@ sudo systemctl enable ntpd.service 7. 创建 CPU 节能策略配置服务。 - {{< copyable "shell-regular" >}} - ```bash cat >> /etc/systemd/system/cpupower.service << EOF [Unit] @@ -605,8 +635,6 @@ sudo systemctl enable ntpd.service 8. 应用 CPU 节能策略配置服务。 - {{< copyable "shell-regular" >}} - ```bash systemctl daemon-reload systemctl enable cpupower.service @@ -615,8 +643,6 @@ sudo systemctl enable ntpd.service 6. 执行以下命令验证透明大页的状态。 - {{< copyable "shell-regular" >}} - ```bash cat /sys/kernel/mm/transparent_hugepage/enabled ``` @@ -627,8 +653,6 @@ sudo systemctl enable ntpd.service 7. 执行以下命令验证数据目录所在磁盘的 I/O 调度器。 - {{< copyable "shell-regular" >}} - ```bash cat /sys/block/sd[bc]/queue/scheduler ``` @@ -640,8 +664,6 @@ sudo systemctl enable ntpd.service 8. 执行以下命令查看 cpufreq 模块选用的节能策略。 - {{< copyable "shell-regular" >}} - ```bash cpupower frequency-info --policy ``` @@ -654,56 +676,57 @@ sudo systemctl enable ntpd.service 9. 执行以下命令修改 sysctl 参数。 - {{< copyable "shell-regular" >}} - ```bash echo "fs.file-max = 1000000">> /etc/sysctl.conf echo "net.core.somaxconn = 32768">> /etc/sysctl.conf - echo "net.ipv4.tcp_tw_recycle = 0">> /etc/sysctl.conf echo "net.ipv4.tcp_syncookies = 0">> /etc/sysctl.conf echo "vm.overcommit_memory = 1">> /etc/sysctl.conf echo "vm.min_free_kbytes = 1048576">> /etc/sysctl.conf sysctl -p ``` + > **警告：** + > + > 不建议在内存小于 16 GiB 的系统上调大 `vm.min_free_kbytes` 的值，否则可能导致系统不稳定或启动失败。 + > **注意：** > > - `vm.min_free_kbytes` 是 Linux 内核的一个参数，用于控制系统预留的最小空闲内存量，单位为 KiB。 > - `vm.min_free_kbytes` 的设置会影响内存回收机制。设置得过大，会导致可用内存变少，设置得过小，可能会导致内存的申请速度超过后台的回收速度，进而导致内存回收并引起内存分配延迟。 > - 建议将 `vm.min_free_kbytes` 最小设置为 `1048576` KiB（即 1 GiB）。如果[安装了 NUMA](/check-before-deployment.md#安装-numactl-工具)，建议设置为 `NUMA 节点个数 * 1048576` KiB。 - > - 对于内存小于 16 GiB 的小规格服务器，保持 `vm.min_free_kbytes` 的默认值即可。 - > - `tcp_tw_recycle` 从 Linux 4.12 内核版本开始移除，在使用高版本内核时无需配置该项。 + > - 对于运行 Linux 内核 4.11 或更早版本的系统，建议将 `net.ipv4.tcp_tw_recycle` 设置为 `0`。 10. 执行以下命令配置用户的 limits.conf 文件。 - {{< copyable "shell-regular" >}} - ```bash cat << EOF >>/etc/security/limits.conf - tidb soft nofile 1000000 - tidb hard nofile 1000000 + tidb soft nofile 1000000 + tidb hard nofile 1000000 tidb soft stack 32768 tidb hard stack 32768 + tidb soft core unlimited + tidb hard core unlimited EOF ``` ## 手动配置 SSH 互信及 sudo 免密码 -对于有需求，通过手动配置中控机至目标节点互信的场景，可参考本段。通常推荐使用 TiUP 部署工具会自动配置 SSH 互信及免密登录，可忽略本段内容。 +本节介绍如何手动配置中控机到目标节点的 SSH 互信。如果你使用 TiUP 部署工具，SSH 互信和免密码登录会自动完成配置，可跳过本节。 -1. 以 `root` 用户依次登录到部署目标机器创建 `tidb` 用户并设置登录密码。 +在配置 SSH 互信时，建议在所有目标节点上创建并使用 `tidb` 用户。一般情况下，系统并不强制要求各节点上的用户相同。但在以下场景中，请注意用户一致性的要求： - {{< copyable "shell-root" >}} +- 使用备份恢复工具 (BR)：强烈建议使用同一用户执行所有 BR 和 TiDB 相关操作。 +- 使用 NFS 等网络存储：需要确保该用户在所有节点上的 UID 和 GID 相同。NFS 通过底层 UID 和 GID 来识别文件访问权限，如果各节点的 UID 或 GID 不一致，或者执行 BR 的用户与运行 TiDB 的用户不同（尤其是在没有 `sudo` 权限时），备份或恢复过程中可能会出现权限被拒绝 (Permission Denied) 错误。 + +1. 以 `root` 用户依次登录到部署目标机器创建 `tidb` 用户并设置登录密码。 ```bash - useradd tidb && \ + useradd -m -d /home/tidb tidb passwd tidb ``` 2. 执行以下命令，将 `tidb ALL=(ALL) NOPASSWD: ALL` 添加到文件末尾，即配置好 sudo 免密码。 - {{< copyable "shell-root" >}} - ```bash visudo ``` @@ -714,8 +737,6 @@ sudo systemctl enable ntpd.service 3. 以 `tidb` 用户登录到中控机，执行以下命令。将 `10.0.1.1` 替换成你的部署目标机器 IP，按提示输入部署目标机器 `tidb` 用户密码，执行成功后即创建好 SSH 互信，其他机器同理。新建的 `tidb` 用户下没有 `.ssh` 目录，需要执行生成 rsa 密钥的命令来生成 `.ssh` 目录。如果要在中控机上部署 TiDB 组件，需要为中控机和中控机自身配置互信。 - {{< copyable "shell-regular" >}} - ```bash ssh-keygen -t rsa ssh-copy-id -i ~/.ssh/id_rsa.pub 10.0.1.1 @@ -723,8 +744,6 @@ sudo systemctl enable ntpd.service 4. 以 `tidb` 用户登录中控机，通过 `ssh` 的方式登录目标机器 IP。如果不需要输入密码并登录成功，即表示 SSH 互信配置成功。 - {{< copyable "shell-regular" >}} - ```bash ssh 10.0.1.1 ``` @@ -735,8 +754,6 @@ sudo systemctl enable ntpd.service 5. 以 `tidb` 用户登录到部署目标机器后，执行以下命令，不需要输入密码并切换到 `root` 用户，表示 `tidb` 用户 sudo 免密码配置成功。 - {{< copyable "shell-regular" >}} - ```bash sudo -su root ``` @@ -777,3 +794,11 @@ sudo yum -y install numactl ``` 你可以执行 `tiup cluster exec --help` 查看的 `tiup cluster exec` 命令的说明信息。 + +## 关闭 SELinux + +SELinux 必须关闭或设置为 `permissive` 模式。你可以使用 [getenforce(8)](https://linux.die.net/man/8/getenforce) 工具来检查 SELinux 的当前状态。 + +如果 SELinux 未关闭，请打开 `/etc/selinux/config` 文件，找到以 `SELINUX=` 开头的行，并将其修改为 `SELINUX=disabled`。修改完成后，你需要重启系统，因为从 `enforcing` 或 `permissive` 切换到 `disabled` 模式只有在重启后才会生效。 + +在某些系统（如 Ubuntu）上，`/etc/selinux/config` 文件可能不存在，且 getenforce 工具可能未安装。在这种情况下，可以跳过此检查步骤。 diff --git a/choose-index.md b/choose-index.md index ac5b53a5e92d..78db9ebd2f49 100644 --- a/choose-index.md +++ b/choose-index.md @@ -1,7 +1,6 @@ --- title: 索引的选择 summary: 介绍 TiDB 如何选择索引去读入数据，以及相关的一些控制索引选择的方式。 -aliases: ['/docs-cn/dev/choose-index/'] --- # 索引的选择 @@ -82,7 +81,7 @@ Skyline-Pruning 是一个针对索引的启发式过滤规则，能降低错误 - 选择该索引是否能满足一定的顺序。因为索引的读取可以保证某些列集合的顺序，所以满足查询要求顺序的索引在这个维度上优于不满足的索引。 -- 该索引是否为[全局索引](/partitioned-table.md#全局索引)。在分区表中，全局索引相比普通索引能有效的降低一个 SQL 的 cop task 数量，进而提升整体性能。 +- 该索引是否为[全局索引](/global-indexes.md)。在分区表中，全局索引相比普通索引能有效的降低一个 SQL 的 cop task 数量，进而提升整体性能。 对于上述维度，如果索引 `idx_a` 在这四个维度上都不比 `idx_b` 差，且有一个维度比 `idx_b` 好，那么 TiDB 会优先选择 `idx_a`。在执行 `EXPLAIN FORMAT = 'verbose' ...` 语句时，如果 Skyline-Pruning 排除了某些索引，TiDB 会输出一条 NOTE 级别的 warning 提示哪些索引在 Skyline-Pruning 排除之后保留下来。 diff --git a/clinic/clinic-data-instruction-for-tiup.md b/clinic/clinic-data-instruction-for-tiup.md index f06d1a5bd525..c74f2c6a1051 100644 --- a/clinic/clinic-data-instruction-for-tiup.md +++ b/clinic/clinic-data-instruction-for-tiup.md @@ -32,6 +32,7 @@ Clinic Server 是部署在云端的云服务，根据数据存储的位置不同 | 日志 | `tidb.log` | `--include=log` | | Error 日志 | `tidb_stderr.log` | `--include=log` | | 慢日志| `tidb_slow_query.log` | `--include=log` | +| 审计日志 | `tidb-audit.log.json` | `--include=log` | | 配置文件 | `tidb.toml` | `--include=config` | | 实时配置| `config.json` | `--include=config` | @@ -140,3 +141,14 @@ Clinic Server 是部署在云端的云服务，根据数据存储的位置不同 | 系统 `/etc/security/limits.conf` 中的内容 | `limits.conf` | `--include=system` | | 内核参数列表 | `sysctl.conf` | `--include=system` | | socket 统计信息（即 ss 的命令结果） | `ss.txt` | `--include=system` | + +### 日志文件分类 + +你可以使用 `--include=log.` 参数来指定要采集的日志类型。 + +日志类型包括： + +- `std`：文件名中包含 `stderr` 的日志文件。 +- `rocksdb`：以 `rocksdb` 为前缀、以 `.info` 为后缀的日志文件。 +- `slow`：慢查询日志文件。 +- `unknown`：不属于以上任何类型的日志文件。 diff --git a/clinic/clinic-introduction.md b/clinic/clinic-introduction.md index 2a6061eb7296..629e25ae1160 100644 --- a/clinic/clinic-introduction.md +++ b/clinic/clinic-introduction.md @@ -56,7 +56,7 @@ PingCAP Clinic 服务提供以下两个组件进行集群诊断： > **注意：** > -> - Clinic Server 诊断服务在 2022 年 7 月 15 日至 2024 年 12 月 31 日期间提供免费服务。后续如需收取相关费用，PingCAP Clinic 运营团队将在 2024 年 12 月 31 日前通过邮件通知用户。 +> - Clinic Server 诊断服务在 2022 年 7 月 15 日至 2025 年 4 月 15 日期间提供免费服务。后续如需收取相关费用，PingCAP Clinic 运营团队将在 2025 年 4 月 15 日前通过邮件通知用户。 > - 如果需要调整使用限制，可以[联系 PingCAP 技术支持](/support.md)。 | 诊断服务类型| 使用限制 | diff --git a/clustered-indexes.md b/clustered-indexes.md index a48325ae9fb9..d452656eb9ca 100644 --- a/clustered-indexes.md +++ b/clustered-indexes.md @@ -5,11 +5,11 @@ summary: 本文档介绍了聚簇索引的概念、使用场景、使用方法 # 聚簇索引 -聚簇索引 (clustered index) 是 TiDB 从 v5.0 开始支持的特性，用于控制含有主键的表数据的存储方式。通过使用聚簇索引，TiDB 可以更好地组织数据表，从而提高某些查询的性能。有些数据库管理系统也将聚簇索引称为“索引组织表” (index-organized tables)。 +聚簇索引 (clustered index) 是 TiDB 从 v5.0 开始支持的特性，用于控制含有主键的表数据的存储方式。通过使用聚簇索引，TiDB 可以更好地组织数据表，从而提高某些查询的性能。有些数据库管理系统将聚簇索引表称为“索引组织表” (index-organized tables)。 目前 TiDB 中含有主键的表分为以下两类： -- `NONCLUSTERED`，表示该表的主键为非聚簇索引。在非聚簇索引表中，行数据的键由 TiDB 内部隐式分配的 `_tidb_rowid` 构成，而主键本质上是唯一索引，因此非聚簇索引表存储一行至少需要两个键值对，分别为 +- `NONCLUSTERED`，表示该表的主键为非聚簇索引。在非聚簇索引表中，行数据的键由 TiDB 内部隐式分配的 [`_tidb_rowid`](/tidb-rowid.md) 值构成，而主键本质上是唯一索引，因此非聚簇索引表存储一行至少需要两个键值对，分别为 - `_tidb_rowid`（键）- 行数据（值） - 主键列数据（键） - `_tidb_rowid`（值） - `CLUSTERED`，表示该表的主键为聚簇索引。在聚簇索引表中，行数据的键由用户给定的主键列数据构成，因此聚簇索引表存储一行至少只要一个键值对，即 @@ -141,7 +141,7 @@ mysql> SELECT TIDB_PK_TYPE FROM information_schema.tables WHERE table_schema = ' 目前 TiDB 的聚簇索引具有以下几类限制： - 明确不支持且没有支持计划的使用限制： - - 不支持与 [`SHARD_ROW_ID_BITS`](/shard-row-id-bits.md) 一起使用；[`PRE_SPLIT_REGIONS`](/sql-statements/sql-statement-split-region.md#pre_split_regions) 在聚簇索引表上不生效。 + - 不支持与 [`SHARD_ROW_ID_BITS`](/shard-row-id-bits.md) 一起使用；[`PRE_SPLIT_REGIONS`](/sql-statements/sql-statement-split-region.md#pre_split_regions) 在非 [`AUTO_RANDOM`](/auto-random.md) 的聚簇索引表上不生效。 - 不支持对聚簇索引表进行降级。如需降级，请使用逻辑备份工具迁移数据。 - 尚未支持，但未来有计划支持的使用限制： - 尚未支持通过 `ALTER TABLE` 语句增加、删除、修改聚簇索引。 diff --git a/column-pruning.md b/column-pruning.md index 948a11147409..64184eb23442 100644 --- a/column-pruning.md +++ b/column-pruning.md @@ -1,6 +1,5 @@ --- title: 列裁剪 -aliases: ['/docs-cn/dev/column-pruning/'] summary: 列裁剪是优化器在优化过程中删除不需要的列的基本思想。这样可以减少 I/O 资源占用并为后续优化带来便利。TiDB 会在逻辑优化阶段进行列裁剪，减少资源浪费。该扫描过程称作“列裁剪”，对应逻辑优化规则中的 columnPruner。如果要关闭这个规则，可以参照优化规则及表达式下推的黑名单中的关闭方法。 --- diff --git a/command-line-flags-for-pd-configuration.md b/command-line-flags-for-pd-configuration.md index dfa27ebf917d..ecb75805d7d0 100644 --- a/command-line-flags-for-pd-configuration.md +++ b/command-line-flags-for-pd-configuration.md @@ -1,6 +1,5 @@ --- title: PD 配置参数 -aliases: ['/docs-cn/dev/command-line-flags-for-pd-configuration/','/docs-cn/dev/reference/configuration/pd-server/configuration/'] summary: PD 配置参数可以通过命令行参数或环境变量配置。包括外部访问 PD 的 URL 列表，其他 PD 节点访问某个 PD 节点的 URL 列表，PD 监听的客户端 URL 列表，PD 节点监听其他 PD 节点的 URL 列表，配置文件，PD 存储数据路径，初始化 PD 集群配置，动态加入 PD 集群，Log 级别，Log 文件，是否开启日志切割，当前 PD 的名字，CA 文件路径，包含 X509 证书的 PEM 文件路径，包含 X509 key 的 PEM 文件路径，指定 Prometheus Pushgateway 的地址，强制使用当前节点创建新的集群，输出版本信息并退出。 --- diff --git a/command-line-flags-for-tidb-configuration.md b/command-line-flags-for-tidb-configuration.md index c82595a39077..6ea9e826188f 100644 --- a/command-line-flags-for-tidb-configuration.md +++ b/command-line-flags-for-tidb-configuration.md @@ -1,6 +1,5 @@ --- title: TiDB 配置参数 -aliases: ['/docs-cn/dev/command-line-flags-for-tidb-configuration/','/docs-cn/dev/reference/configuration/tidb-server/configuration/'] summary: TiDB 配置参数包括启动参数和环境变量。启动参数包括 advertise-address、config、config-check、config-strict、cors 等。其中默认端口为 4000 和 10080。其他参数包括 log-file、metrics-addr、metrics-interval 等。注意配置文件的有效性和安全模式下的启动。 --- @@ -10,7 +9,7 @@ summary: TiDB 配置参数包括启动参数和环境变量。启动参数包括 要快速了解 TiDB 的参数体系与参数作用域，建议先观看下面的培训视频（时长 17 分钟）。 - + 本文将详细介绍 TiDB 的命令行启动参数。TiDB 的默认端口为 4000（客户端请求）与 10080（状态报告）。 @@ -54,7 +53,7 @@ summary: TiDB 配置参数包括启动参数和环境变量。启动参数包括 ## `--initialize-secure` -- 在安全模式下启动 tidb-server +- 控制在 tidb-server 初始化过程中是否使用 `auth_socket` 认证方式创建 `root` 账户。如果设置为 `true`，首次连接 TiDB 时必须使用 socket 连接，这样安全性更高。 - 默认：false ## `--initialize-sql-file` diff --git a/command-line-flags-for-tikv-configuration.md b/command-line-flags-for-tikv-configuration.md index d176ddcd2837..23db9db33c61 100644 --- a/command-line-flags-for-tikv-configuration.md +++ b/command-line-flags-for-tikv-configuration.md @@ -1,6 +1,5 @@ --- title: TiKV 配置参数 -aliases: ['/docs-cn/dev/command-line-flags-for-tikv-configuration/','/docs-cn/dev/reference/configuration/tikv-server/configuration/'] summary: TiKV 配置参数支持文件大小和时间的可读性好的单位转换。命令行参数包括监听地址、对外访问地址、服务状态监听端口、对外访问服务状态地址、配置文件、存储数据的容量、配置信息输出格式、数据存储路径、日志级别、日志文件、PD 地址列表。需要注意的是，PD 地址列表需要使用逗号分隔多个地址。 --- diff --git a/comment-syntax.md b/comment-syntax.md index e8cffd06be2e..4130d2564883 100644 --- a/comment-syntax.md +++ b/comment-syntax.md @@ -1,7 +1,6 @@ --- title: 注释语法 summary: 本文介绍 TiDB 支持的注释语法。 -aliases: ['/docs-cn/dev/comment-syntax/','/docs-cn/dev/reference/sql/language-structure/comment-syntax/'] --- # 注释语法 diff --git a/configure-load-base-split.md b/configure-load-base-split.md index e05e62e016c3..52f3f2abd3c4 100644 --- a/configure-load-base-split.md +++ b/configure-load-base-split.md @@ -1,7 +1,6 @@ --- title: Load Base Split summary: 介绍 Load Base Split 功能。 -aliases: ['/docs-cn/dev/configure-load-base-split/'] --- # Load Base Split diff --git a/configure-memory-usage.md b/configure-memory-usage.md index 986f9b2551b5..14dda46a8405 100644 --- a/configure-memory-usage.md +++ b/configure-memory-usage.md @@ -1,6 +1,5 @@ --- title: TiDB 内存控制文档 -aliases: ['/docs-cn/dev/configure-memory-usage/','/docs-cn/dev/how-to/configure/memory-control/'] summary: TiDB 内存控制文档介绍了如何追踪和控制 SQL 查询过程中的内存使用情况，以及配置内存使用阈值和 tidb-server 实例的内存使用阈值。还介绍了使用 INFORMATION_SCHEMA 系统表查看内存使用情况，以及降低写入事务内存使用的方法。另外还介绍了流量控制和数据落盘的内存控制策略，以及通过设置环境变量 GOMEMLIMIT 缓解 OOM 问题。 --- diff --git a/configure-placement-rules.md b/configure-placement-rules.md index baafb3208334..ff92b2cbe52e 100644 --- a/configure-placement-rules.md +++ b/configure-placement-rules.md @@ -1,7 +1,6 @@ --- title: Placement Rules 使用文档 summary: 如何配置 Placement Rules -aliases: ['/docs-cn/dev/configure-placement-rules/','/docs-cn/dev/how-to/configure/placement-rules/'] --- # Placement Rules 使用文档 diff --git a/configure-store-limit.md b/configure-store-limit.md index db1f59136d11..b49ad596c2b5 100644 --- a/configure-store-limit.md +++ b/configure-store-limit.md @@ -1,12 +1,11 @@ --- title: Store Limit summary: 介绍 Store Limit 功能。 -aliases: ['/docs-cn/dev/configure-store-limit/'] --- # Store Limit -Store Limit 是 PD 在 3.0 版本引入的特性，旨在能够更加细粒度地控制调度的速度，针对不同调度场景进行调优。 +Store Limit 是一个 PD 特性，旨在更精细地控制调度速度，以在不同场景下实现更好的性能。 ## 实现原理 @@ -28,48 +27,51 @@ Store Limit 是通过在内存中维护了一个 store ID 到令牌桶的映射 Store Limit 与 PD 其他 limit 相关的参数（如 `region-schedule-limit`，`leader-schedule-limit` 等）不同的是，Store Limit 限制的主要是 operator 的消费速度，而其他的 limit 主要是限制 operator 的产生速度。引入 Store Limit 特性之前，调度的限速主要是全局的，所以即使限制了全局的速度，但还是有可能存在调度都集中在部分 store 上面，因而影响集群的性能。而 Store Limit 通过将限速的粒度进一步细化，可以更好的控制调度的行为。 +Store Limit 定义了每分钟操作的最大数量。假设 Store Limit 为每分钟 5 次操作，向集群添加新节点将以每分钟 5 个 Region（`add-peer` 操作）的速度进行。如果需要为 15 个 Region 执行 `add-peer`，则该操作将需要 3 分钟 (15 / 5 = 3)，并且如果每个 Region 为 96 MiB，将消耗最高 8 MiB/s ((5 × 96) / 60 = 8)。 + ## 使用方法 -Store Limit 相关的参数可以通过 `pd-ctl` 进行设置。 +Store Limit 相关的参数可以通过 [`PD Control`](/pd-control.md) 进行设置。 ### 查看当前 store 的 limit 设置 查看当前 store 的 limit 示例如下： -{{< copyable "shell-regular" >}} - ```bash -store limit // 显示所有 store 添加和删除 peer 的速度上限。 -store limit add-peer // 显示所有 store 添加 peer 的速度上限。 -store limit remove-peer // 显示所有 store 删除 peer 的速度上限。 +tiup ctl:v pd store limit // 显示所有 store 添加和删除 peer 的速度上限。 +tiup ctl:v pd store limit add-peer // 显示所有 store 添加 peer 的速度上限。 +tiup ctl:v pd store limit remove-peer // 显示所有 store 删除 peer 的速度上限。 ``` ### 设置全部 store 的 limit 设置全部 store 的 limit 示例如下： -{{< copyable "shell-regular" >}} +```bash +tiup ctl:v pd store limit all 5 // 设置所有 store 添加和删除 peer 的速度上限为每分钟 5 个。 +tiup ctl:v pd store limit all 5 add-peer // 设置所有 store 添加 peer 的速度上限为每分钟 5 个。 +tiup ctl:v pd store limit all 5 remove-peer // 设置所有 store 删除 peer 的速度上限为每分钟 5 个。 +``` + +从 v8.5.5 起，PD 支持按存储引擎类型为所有 store 设置删除 peer 的 limit，示例如下： ```bash -store limit all 5 // 设置所有 store 添加和删除 peer 的速度上限为每分钟 5 个。 -store limit all 5 add-peer // 设置所有 store 添加 peer 的速度上限为每分钟 5 个。 -store limit all 5 remove-peer // 设置所有 store 删除 peer 的速度上限为每分钟 5 个。 +tiup ctl:v pd store limit all engine tikv 5 remove-peer // 设置所有 TiKV store 删除 peer 的速度上限为每分钟 5 个 +tiup ctl:v pd store limit all engine tiflash 5 remove-peer // 设置所有 TiFlash store 删除 peer 的速度上限为每分钟 5 个 ``` ### 设置单个 store 的 limit 设置单个 store 的 limit 示例如下： -{{< copyable "shell-regular" >}} - ```bash -store limit 1 5 // 设置 store 1 添加和删除 peer 的速度上限为每分钟 5 个。 -store limit 1 5 add-peer // 设置 store 1 添加 peer 的速度上限为每分钟 5 个。 -store limit 1 5 remove-peer // 设置 store 1 删除 peer 的速度上限为每分钟 5 个。 +tiup ctl:v pd store limit 1 5 // 设置 store 1 添加和删除 peer 的速度上限为每分钟 5 个。 +tiup ctl:v pd store limit 1 5 add-peer // 设置 store 1 添加 peer 的速度上限为每分钟 5 个。 +tiup ctl:v pd store limit 1 5 remove-peer // 设置 store 1 删除 peer 的速度上限为每分钟 5 个。 ``` ## Store Limit v2 原理 当 [`store-limit-version`](/pd-configuration-file.md#store-limit-version-从-v710-版本开始引入) 设置为 `v2` 时，Store Limit v2 生效。在此模式下，Operator 调度限制将根据 TiKV Snapshot 执行情况进行动态调整。当 TiKV 积压的任务较少时，PD 会增加其调度任务。相反，PD 会减少对该节点的调度任务。此时，你无需关注如何设置 `store limit` 以加快调度进度。 -在该模式下，TiKV 执行速度成为迁移进度的主要瓶颈。你可以通过 **TiKV Details** > **Snapshot** > **Snapshot Speed** 面板判断当前调度速度是否达到 TiKV 限流设置。通过调整 TiKV Snapshot Limit ([`snap-io-max-bytes-per-sec`](/tikv-configuration-file.md#snap-io-max-bytes-per-sec)) 来增加或减少该节点的调度速度。 \ No newline at end of file +在该模式下，TiKV 执行速度成为迁移进度的主要瓶颈。你可以通过 **TiKV Details** > **Snapshot** > **Snapshot Speed** 面板判断当前调度速度是否达到 TiKV 限流设置。通过调整 TiKV Snapshot Limit ([`snap-io-max-bytes-per-sec`](/tikv-configuration-file.md#snap-io-max-bytes-per-sec)) 来增加或减少该节点的调度速度。 diff --git a/configure-time-zone.md b/configure-time-zone.md index 6423bb81fd85..58bc97ffd2e3 100644 --- a/configure-time-zone.md +++ b/configure-time-zone.md @@ -1,56 +1,65 @@ --- title: 时区支持 -aliases: ['/docs-cn/dev/configure-time-zone/','/docs-cn/dev/how-to/configure/time-zone/'] -summary: TiDB 使用的时区由全局变量和 session 变量决定。全局变量的默认值是 System，实际时区在集群初始化时设置。可以通过设置全局时区和 session 变量来修改时区。Timestamp 数据类型受时区影响，而 Datetime/Date/Time 不受影响。在导数据时需注意主从库的时区设定是否一致。 +summary: TiDB 的时区设置由 `time_zone` 系统变量控制，可以在会话级别或全局级别进行设置。`TIMESTAMP` 数据类型的的显示值受时区设置影响，但 `DATETIME`、`DATE` 或 `TIME` 数据类型不受影响。在数据迁移时，需要特别注意主库和从库的时区设置是否一致。 --- # 时区支持 -TiDB 使用的时区由 `time_zone` 全局变量和 session 变量决定。`time_zone` 的默认值是 `System`，`System` 对应的实际时区在 `TiDB` 集群 bootstrap 初始化时设置。具体逻辑如下： +TiDB 使用的时区由 [`time_zone`](/system-variables.md#time_zone) 系统变量决定，该变量可以在会话级别或全局级别设置。`time_zone` 的默认值为 `SYSTEM`。`SYSTEM` 对应的实际时区是在 TiDB 集群 bootstrap 初始化时配置的，具体逻辑如下： -* 优先使用 `TZ` 环境变量 -* 如果失败，则从 `/etc/localtime` 的实际软链地址提取。 -* 如果上面两种都失败则使用 `UTC` 作为系统时区。 +1. TiDB 优先使用 `TZ` 环境变量。 +2. 如果 `TZ` 环境变量不可用，TiDB 会从 `/etc/localtime` 的软链接中读取时区信息。 +3. 如果上述方法均失败，TiDB 将使用 `UTC` 作为系统时区。 -在运行过程中可以修改全局时区： +## 查看时区 -{{< copyable "sql" >}} +要查看当前全局时区、客户端时区或系统时区的值，可以执行以下语句： ```sql -SET GLOBAL time_zone = timezone; +SELECT @@global.time_zone, @@session.time_zone, @@global.system_time_zone; ``` -TiDB 还可以通过设置 session 变量 `time_zone` 为每个连接维护各自的时区。默认条件下，这个值取的是全局变量 `time_zone` 的值。修改 session 使用的时区： +## 设置时区 -{{< copyable "sql" >}} +在 TiDB 中，`time_zone` 系统变量的值可以设置为以下格式之一： -```sql -SET time_zone = timezone; -``` +- `SYSTEM`（默认值），表示使用系统时间。 +- 相对于 UTC 时间的偏移，比如 `'+10:00'` 或 `'-6:00'`。 +- 某个时区的名字，比如 `'Europe/Helsinki'`、`'US/Eastern'` 或 `'MET'`。 -使用以下 SQL 语句查看当前全局时区、客户端时区和系统时区的值： +根据需要，你可以在全局级别或会话级别设置 TiDB 的时区： -{{< copyable "sql" >}} +- 设置全局时区： -```sql -SELECT @@global.time_zone, @@session.time_zone, @@global.system_time_zone; -``` + ```sql + SET GLOBAL time_zone = ${time-zone-value}; + ``` + + 例如，执行以下语句可以将全局时区设置为 UTC： + + ```sql + SET GLOBAL time_zone = 'UTC'; + ``` -设置 `time_zone` 的值的格式： +- 设置会话的时区： -* 'SYSTEM' 表明使用系统时间 -* 相对于 UTC 时间的偏移，比如 '+10:00' 或者 '-6:00' -* 某个时区的名字，比如 'Europe/Helsinki'，'US/Eastern' 或 'MET' + ```sql + SET time_zone = ${time-zone-value}; + ``` -`NOW()` 和 `CURTIME()` 的返回值都受到时区设置的影响。 + 例如，执行以下语句可以将当前会话的时区设置为 US/Pacific： -> **注意：** -> -> 只有 Timestamp 数据类型的值是受时区影响的。可以理解为，Timestamp 数据类型的实际表示使用的是（字面值 + 时区信息）。其它时间和日期类型，比如 Datetime/Date/Time 是不包含时区信息的，所以也不受到时区变化的影响。 + ```sql + SET time_zone = 'US/Pacific'; + ``` -{{< copyable "sql" >}} +## 受时区设置影响的函数和数据类型 -{{< copyable "sql" >}} +对于时区敏感的时间值，例如由 [`NOW()`](/functions-and-operators/date-and-time-functions.md) 和 `CURTIME()` 函数返回的值，它们的显示和处理会受到当前会话时区设置的影响。如需进行时区转换，可以使用 `CONVERT_TZ()` 函数。若要获取基于 UTC 的时间戳以避免时区相关问题，可以使用 `UTC_TIMESTAMP()` 函数。 + +在 TiDB 中，`TIMESTAMP` 数据类型会记录时间戳的具体数值和时区信息，因此它的显示值会受到时区设置的影响。其他数据类型（如 `DATETIME`、`DATE` 和 `TIME`）不记录时区信息，因此它们的值不会受到时区变化的影响。 + +例如： ```sql create table t (ts timestamp, dt datetime); @@ -60,8 +69,6 @@ create table t (ts timestamp, dt datetime); Query OK, 0 rows affected (0.02 sec) ``` -{{< copyable "sql" >}} - ```sql set @@time_zone = 'UTC'; ``` @@ -70,8 +77,6 @@ set @@time_zone = 'UTC'; Query OK, 0 rows affected (0.00 sec) ``` -{{< copyable "sql" >}} - ```sql insert into t values ('2017-09-30 11:11:11', '2017-09-30 11:11:11'); ``` @@ -80,8 +85,6 @@ insert into t values ('2017-09-30 11:11:11', '2017-09-30 11:11:11'); Query OK, 1 row affected (0.00 sec) ``` -{{< copyable "sql" >}} - ```sql set @@time_zone = '+8:00'; ``` @@ -90,8 +93,6 @@ set @@time_zone = '+8:00'; Query OK, 0 rows affected (0.00 sec) ``` -{{< copyable "sql" >}} - ```sql select * from t; ``` @@ -105,8 +106,17 @@ select * from t; 1 row in set (0.00 sec) ``` -上面的例子中，无论怎么调整时区的值，Datetime 类型字段的值是不受影响的，而 Timestamp 则随着时区改变，显示的值会发生变化。其实 Timestamp 持久化到存储的值始终没有变化过，只是根据时区的不同显示值不同。 +在以上示例中，无论如何调整时区值，`DATETIME` 数据类型的值不会受到影响。然而，`TIMESTAMP` 数据类型的显示值会根据时区的变化而变化。事实上，存储在数据库中的 `TIMESTAMP` 值始终没有变化过，只是根据时区的不同显示的值不同。 + +## 时区设置的注意事项 + +- 在 `TIMESTAMP` 和 `DATETIME` 值的转换过程中，会涉及到时区。这种情况一律基于当前会话的 `time_zone` 时区处理。 +- 数据迁移时，需要特别注意主库和从库的时区设置是否一致。 +- 为了获取准确的时间戳，强烈建议使用网络时间协议 (NTP) 或精确时间协议 (PTP) 服务配置可靠的时钟。有关如何检查 NTP 服务的信息，请参考[检测及安装 NTP 服务](/check-before-deployment.md#检测及安装-ntp-服务)。 +- 当使用遵循夏令时 (Daylight Saving Time, DST) 的时区时，请注意可能出现时间戳不明确或不存在的情况，特别是在对这些时间戳进行计算时。 +- MySQL 需要使用 [`mysql_tzinfo_to_sql`](https://dev.mysql.com/doc/refman/8.4/en/mysql-tzinfo-to-sql.html) 将操作系统的时区数据库转换为 `mysql` 数据库中的表。TiDB 则可以利用 Go 编程语言的内置时区处理能力，直接从操作系统的时区数据库中读取时区数据文件。 -Timestamp 类型和 Datetime 等类型的值，两者相互转换的过程中，会涉及到时区。这种情况一律基于 session 的当前 `time_zone` 时区处理。 +## 另请参阅 -另外，用户在导数据的过程中，也要需注意主库和从库之间的时区设定是否一致。 +- [日期和时间类型](/data-type-date-and-time.md) +- [日期和时间函数](/functions-and-operators/date-and-time-functions.md) \ No newline at end of file diff --git a/constraints.md b/constraints.md index afac6d153e1e..fd1fa56d56f8 100644 --- a/constraints.md +++ b/constraints.md @@ -1,6 +1,5 @@ --- title: 约束 -aliases: ['/docs-cn/dev/constraints/','/docs-cn/dev/reference/sql/constraints/'] summary: TiDB 支持的约束与 MySQL 基本相同，包括非空约束和 CHECK 约束。非空约束规则与 MySQL 相同，而 CHECK 约束需要在 tidb_enable_check_constraint 设置为 ON 后才能开启。可以通过 CREATE TABLE 或 ALTER TABLE 语句添加 CHECK 约束。唯一约束和主键约束也与 MySQL 相似，但 TiDB 目前仅支持对 NONCLUSTERED 的主键进行添加和删除操作。外键约束从 v6.6.0 开始支持，可以使用 CREATE TABLE 和 ALTER TABLE 命令来添加和删除外键。 --- diff --git a/control-execution-plan.md b/control-execution-plan.md index 5b74ffbd30e0..36505dd03fbd 100644 --- a/control-execution-plan.md +++ b/control-execution-plan.md @@ -1,6 +1,5 @@ --- title: 控制执行计划 -aliases: ['/docs-cn/dev/control-execution-plan/'] summary: 本章节介绍了控制执行计划的方法，包括使用提示指导执行计划、执行计划管理、优化规则及表达式下推的黑名单。此外，还介绍了一些系统变量对执行计划的影响，以及引入的特殊变量 `tidb_opt_fix_control`，用于更细粒度地控制优化器的行为。 --- diff --git a/coprocessor-cache.md b/coprocessor-cache.md index 9012673355ff..6d64580ce759 100644 --- a/coprocessor-cache.md +++ b/coprocessor-cache.md @@ -1,6 +1,5 @@ --- title: 下推计算结果缓存 -aliases: ['/docs-cn/dev/coprocessor-cache/'] summary: TiDB 4.0 支持下推计算结果缓存，配置位于 `tikv-client.copr-cache`，缓存仅存储在 TiDB 内存中，不共享缓存，对 Region 写入会导致缓存失效。缓存命中率可通过 `EXPLAIN ANALYZE` 或 Grafana 监控面板查看。 --- diff --git a/correlated-subquery-optimization.md b/correlated-subquery-optimization.md index 099b87868c46..650b79452480 100644 --- a/correlated-subquery-optimization.md +++ b/correlated-subquery-optimization.md @@ -1,7 +1,6 @@ --- title: 关联子查询去关联 summary: 了解如何给关联子查询解除关联。 -aliases: ['/docs-cn/dev/correlated-subquery-optimization/'] --- # 关联子查询去关联 diff --git a/credits.md b/credits.md index b14d4d3f5d82..77131e33d3df 100644 --- a/credits.md +++ b/credits.md @@ -1,7 +1,6 @@ --- title: TiDB 社区荣誉列表 summary: 了解 TiDB 社区贡献者列表及角色。 -aliases: ['/docs-cn/dev/credits/'] --- # TiDB 社区荣誉列表 @@ -21,7 +20,6 @@ TiDB 开发者为 TiDB 的新功能开发、性能优化、稳定性保障做出 - [pingcap/tidb-dashboard](https://github.com/pingcap/tidb-dashboard/graphs/contributors) - [pingcap/tiflow](https://github.com/pingcap/tiflow/graphs/contributors) - [pingcap/tidb-tools](https://github.com/pingcap/tidb-tools/graphs/contributors) -- [pingcap/tispark](https://github.com/pingcap/tispark/graphs/contributors) - [tikv/client-java](https://github.com/tikv/client-java/graphs/contributors) - [tidb-incubator/TiBigData](https://github.com/tidb-incubator/TiBigData/graphs/contributors) - [ti-community-infra](https://github.com/orgs/ti-community-infra/people) diff --git a/daily-check.md b/daily-check.md index 3aa85f8fae72..3f5b3df09dfc 100644 --- a/daily-check.md +++ b/daily-check.md @@ -1,7 +1,6 @@ --- title: 日常巡检 summary: 介绍 TiDB 集群需要常关注的性能指标。 -aliases: ['/docs-cn/dev/daily-check/','/docs-cn/dev/daily-inspection/','/zh/tidb/dev/daily-inspection'] --- # 日常巡检 @@ -52,7 +51,7 @@ TiDB 作为分布式数据库，对比单机数据库机制更加复杂，其自 + `pending-peer-region-count`：Raft log 落后的 Region 数量。由于调度产生少量的 pending peer 是正常的，但是如果 pending peer 的数量持续（超过 30 分钟）很高，可能存在问题。 + `undersized-region-count`：Region 大小小于 `max-merge-region-size` 或 `max-merge-region-keys` 的 Region 数量。 -原则上来说，该监控面板偶尔有数据是符合预期的。但长期有数据，需要排查是否存在问题。 +这些指标显示较小的非零值一般是正常的。 ### KV Request Duration diff --git a/dashboard/dashboard-access.md b/dashboard/dashboard-access.md index cbf8543e1ac6..cd144fa54ee2 100644 --- a/dashboard/dashboard-access.md +++ b/dashboard/dashboard-access.md @@ -1,6 +1,5 @@ --- title: 访问 TiDB Dashboard -aliases: ['/docs-cn/dev/dashboard/dashboard-access/'] summary: TiDB Dashboard 可通过浏览器访问，支持多 PD 实例访问。浏览器兼容性包括 Chrome、Firefox 和 Edge。登录界面可使用 root 用户或自定义 SQL 用户登录。支持简体中文和英文语言切换。可在用户页面登出当前用户。 --- @@ -10,7 +9,7 @@ summary: TiDB Dashboard 可通过浏览器访问，支持多 PD 实例访问。 > **注意：** > -> TiDB v6.5.0 且 TiDB Operator v1.4.0 之后，在 Kubernetes 上支持将 TiDB Dashboard 作为独立的 Pod 部署。在 TiDB Operator 环境，可直接访问该 Pod 的 IP 来打开 TiDB Dashboard。具体信息，参考 [TiDB Operator 部署独立的 TiDB Dashboard](https://docs.pingcap.com/zh/tidb-in-kubernetes/dev/get-started#部署独立的-tidb-dashboard)。 +> TiDB v6.5.0 且 TiDB Operator v1.4.0 之后，在 Kubernetes 上支持将 TiDB Dashboard 作为独立的 Pod 部署。在 TiDB Operator 环境，可直接访问该 Pod 的 IP 来打开 TiDB Dashboard。具体信息，参考 [TiDB Operator 部署独立的 TiDB Dashboard](https://docs.pingcap.com/zh/tidb-in-kubernetes/v1.6/get-started#部署独立的-tidb-dashboard)。 ## 多 PD 实例访问 diff --git a/dashboard/dashboard-cluster-info.md b/dashboard/dashboard-cluster-info.md index 126c00031487..8199b9c21d66 100644 --- a/dashboard/dashboard-cluster-info.md +++ b/dashboard/dashboard-cluster-info.md @@ -1,7 +1,6 @@ --- title: TiDB Dashboard 集群信息页面 summary: 查看整个集群中 TiDB、TiKV、PD、TiFlash 组件的运行状态及其所在主机的运行状态 -aliases: ['/docs-cn/dev/dashboard/dashboard-cluster-info/'] --- # TiDB Dashboard 集群信息页面 @@ -86,3 +85,7 @@ aliases: ['/docs-cn/dev/dashboard/dashboard-cluster-info/'] - 磁盘容量 (Disk Capacity)：主机上运行实例所在磁盘的总空间大小 - 磁盘使用率 (Disk Usage)：主机上运行实例所在磁盘的空间使用率 - 实例 (Instance)：主机上运行的实例 + +> **注意：** +> +> **磁盘**列表可能无法显示某些主机的磁盘信息，具体取决于组件类型、分区配置和部署方式。在这种情况下，会显示一个黄色警告图标（⚠️）。将鼠标悬停在该图标上，会显示提示信息“获取主机信息失败”。这是预期行为。 diff --git a/dashboard/dashboard-diagnostics-access.md b/dashboard/dashboard-diagnostics-access.md index 73ee75234b32..b57824a051cd 100644 --- a/dashboard/dashboard-diagnostics-access.md +++ b/dashboard/dashboard-diagnostics-access.md @@ -1,6 +1,5 @@ --- title: TiDB Dashboard 集群诊断页面 -aliases: ['/docs-cn/dev/dashboard/dashboard-diagnostics-access/'] summary: TiDB Dashboard 集群诊断页面是用于诊断集群问题并生成诊断报告的工具。可以通过 TiDB Dashboard 或浏览器访问诊断页面。生成诊断报告的步骤包括设置时间范围和长度，然后点击开始。还可以生成对比报告来比较异常时间段和正常时间段的情况。已生成的报告会显示在主页列表中，可随时查看。 --- diff --git a/dashboard/dashboard-diagnostics-report.md b/dashboard/dashboard-diagnostics-report.md index bb941bb9ecf0..8f31ed10328e 100644 --- a/dashboard/dashboard-diagnostics-report.md +++ b/dashboard/dashboard-diagnostics-report.md @@ -1,6 +1,5 @@ --- title: TiDB Dashboard 诊断报告 -aliases: ['/docs-cn/dev/dashboard/dashboard-diagnostics-report/'] summary: TiDB Dashboard 诊断报告介绍了诊断报告的内容和查看技巧。报告包括基本信息、诊断信息、负载信息、概览信息、TiDB/PD/TiKV 监控信息和配置信息。对比报告显示两个时间段的差异，通过 DIFF_RATIO 和 Maximum Different Item 报表可以快速发现监控项的差异。 --- diff --git a/dashboard/dashboard-diagnostics-usage.md b/dashboard/dashboard-diagnostics-usage.md index ed6c9193a0c1..7daa6f9aab7b 100644 --- a/dashboard/dashboard-diagnostics-usage.md +++ b/dashboard/dashboard-diagnostics-usage.md @@ -1,6 +1,5 @@ --- title: 使用 TiDB Dashboard 诊断报告定位问题 -aliases: ['/docs-cn/dev/dashboard/dashboard-diagnostics-usage/'] summary: 本文介绍了使用 TiDB Dashboard 诊断报告定位问题的方法。通过对比两个时间段的监控项差异来帮助 DBA 定位问题。示例中展示了大查询/写入导致 QPS 抖动或延迟上升的诊断方法，以及如何用对比报告定位问题。对比报告可以帮助 DBA 更快速地定位问题，例如通过查看监控项的差异大小排序来发现异常。通过对比报告定位问题，可以更准确地诊断可能的慢查询和影响查询执行的负载。 --- diff --git a/dashboard/dashboard-faq.md b/dashboard/dashboard-faq.md index cdf1b3558c6b..ce72814fff7c 100644 --- a/dashboard/dashboard-faq.md +++ b/dashboard/dashboard-faq.md @@ -1,6 +1,5 @@ --- title: TiDB Dashboard 常见问题 -aliases: ['/docs-cn/dev/dashboard/dashboard-faq/'] summary: TiDB Dashboard 常见问题汇总，包括访问、界面功能方面的常见问题与解决办法。若无法解决，请获取官方或社区支持。 --- @@ -57,7 +56,7 @@ QPS 及 Latency 监控依赖于集群中已正常部署 Prometheus 监控实例 ### 界面提示 `集群中未启动必要组件 NgMonitoring` -NgMonitoring 是 TiDB v5.4.0 及以上集群中内置的高级监控组件，用于支撑 TiDB Dashboard 的 **持续性能分析** 和 **Top SQL** 等功能。使用较新版本 TiUP 部署或升级集群时，NgMonitoring 会自动部署；使用 TiDB Operator 部署集群时，需要依据[启用持续性能分析](https://docs.pingcap.com/zh/tidb-in-kubernetes/dev/access-dashboard#启用持续性能分析)手动部署 NgMonitoring。 +NgMonitoring 是 TiDB v5.4.0 及以上集群中内置的高级监控组件，用于支撑 TiDB Dashboard 的 **持续性能分析** 和 **Top SQL** 等功能。使用较新版本 TiUP 部署或升级集群时，NgMonitoring 会自动部署；使用 TiDB Operator 部署集群时，需要依据[启用持续性能分析](https://docs.pingcap.com/zh/tidb-in-kubernetes/v1.6/access-dashboard#启用持续性能分析)手动部署 NgMonitoring。 如果界面提示 `集群中未启动必要组件 NgMonitoring`，可按以下方式排查部署问题。 @@ -123,7 +122,7 @@ NgMonitoring 是 TiDB v5.4.0 及以上集群中内置的高级监控组件，用
使用 TiDB Operator 部署的集群 -请参见 TiDB Operator 文档中[启用持续性能分析](https://docs.pingcap.com/zh/tidb-in-kubernetes/dev/access-dashboard#启用持续性能分析)的步骤部署 NgMonitoring 组件。 +请参见 TiDB Operator 文档中[启用持续性能分析](https://docs.pingcap.com/zh/tidb-in-kubernetes/v1.6/access-dashboard#启用持续性能分析)的步骤部署 NgMonitoring 组件。
diff --git a/dashboard/dashboard-intro.md b/dashboard/dashboard-intro.md index 798f67342805..3950b1d8c5a4 100644 --- a/dashboard/dashboard-intro.md +++ b/dashboard/dashboard-intro.md @@ -1,6 +1,5 @@ --- title: TiDB Dashboard 介绍 -aliases: ['/docs-cn/dev/dashboard/dashboard-intro/'] summary: TiDB Dashboard 是 TiDB 4.0 版本后提供的图形化界面，用于监控和诊断集群。它内置于 TiDB 的 PD 组件中，无需独立部署。可以查看集群整体运行概况、组件及主机运行状态、集群读写流量分布、SQL 查询的执行信息、耗时较长的 SQL 语句执行信息、诊断集群问题并生成报告、查询所有组件日志、预估资源管控容量、收集分析各个组件的性能数据。 --- @@ -10,7 +9,7 @@ TiDB Dashboard 是 TiDB 自 4.0 版本起提供的图形化界面，可用于监 > **注意：** > -> TiDB v6.5.0 且 TiDB Operator v1.4.0 之后，在 Kubernetes 上支持将 TiDB Dashboard 作为独立的 Pod 部署。具体信息，参考 [TiDB Operator 部署独立的 TiDB Dashboard](https://docs.pingcap.com/zh/tidb-in-kubernetes/dev/get-started#部署独立的-tidb-dashboard)。 +> TiDB v6.5.0 且 TiDB Operator v1.4.0 之后，在 Kubernetes 上支持将 TiDB Dashboard 作为独立的 Pod 部署。具体信息，参考 [TiDB Operator 部署独立的 TiDB Dashboard](https://docs.pingcap.com/zh/tidb-in-kubernetes/v1.6/get-started#部署独立的-tidb-dashboard)。 ![界面](/media/dashboard/dashboard-intro.gif) @@ -62,7 +61,7 @@ TiDB Dashboard 在 GitHub 上[开源](https://github.com/pingcap-incubator/tidb- ## 预估资源管控容量 -为使用[资源管控 (Resource Control)](/tidb-resource-control.md) 特性实现资源隔离，集群管理员可以定义资源组 (Resource Group)，通过资源组限定配额。 +为使用[资源管控 (Resource Control)](/tidb-resource-control-ru-groups.md) 特性实现资源隔离，集群管理员可以定义资源组 (Resource Group)，通过资源组限定配额。 在进行资源规划之前，你需要了解集群的整体容量。参阅[资源管控页面](/dashboard/dashboard-resource-manager.md)了解详情。 diff --git a/dashboard/dashboard-key-visualizer.md b/dashboard/dashboard-key-visualizer.md index 815f0d5f4025..86cf32e60a99 100644 --- a/dashboard/dashboard-key-visualizer.md +++ b/dashboard/dashboard-key-visualizer.md @@ -1,6 +1,5 @@ --- title: TiDB Dashboard 流量可视化页面 -aliases: ['/docs-cn/dev/dashboard/dashboard-key-visualizer/','/docs-cn/dev/how-to/monitor/key-visualizer/','/docs-cn/dev/key-visualizer-monitoring-tool/'] summary: TiDB Dashboard 的流量可视化页面可用于分析 TiDB 集群的使用模式和排查流量热点。通过登录 TiDB Dashboard 或在浏览器中访问指定链接，可以查看流量可视化页面。页面展示了流量热力图，可观察到整体访问流量随时间的变化情况，以及热力图某个坐标的详细信息。流量可视化页面涉及的基本概念包括 Region、热点、热力图和 Region 压缩。使用介绍包括设置、观察时间段或 Region 范围、调整亮度、选择指标、刷新与自动刷新以及查看详情。常见热力图解读包括均衡结果、X 轴明暗交替、Y 轴明暗交替和明亮斜线。解决热点问题可参考 TiDB 高并发写入场景最佳实践。 --- @@ -40,7 +39,7 @@ summary: TiDB Dashboard 的流量可视化页面可用于分析 TiDB 集群的 > **注意：** > -> 关于 Region 的详细介绍，请参考[三篇文章了解 TiDB 技术内幕 - 说存储](https://pingcap.com/blog-cn/tidb-internal-1/#region) +> 关于 Region 的详细介绍，请参考[三篇文章了解 TiDB 技术内幕 - 说存储](https://tidb.net/blog/dbe4f467#保存数据/Region) ### 热点 diff --git a/dashboard/dashboard-log-search.md b/dashboard/dashboard-log-search.md index 5e58b690422f..94ac264139cf 100644 --- a/dashboard/dashboard-log-search.md +++ b/dashboard/dashboard-log-search.md @@ -1,7 +1,6 @@ --- title: TiDB Dashboard 日志搜索页面 summary: 在集群中搜索所有节点上的日志 -aliases: ['/docs-cn/dev/dashboard/dashboard-log-search/'] --- # TiDB Dashboard 日志搜索页面 diff --git a/dashboard/dashboard-monitoring.md b/dashboard/dashboard-monitoring.md index 6d9ee13204aa..a3669040e632 100644 --- a/dashboard/dashboard-monitoring.md +++ b/dashboard/dashboard-monitoring.md @@ -21,99 +21,119 @@ summary: 介绍如何通过 TiDB Dashboard 监控页面查看 Performance Overvi Performance Overview 面板按总分结构对 TiDB、TiKV 和 PD 的性能指标进行了编排组织，包含以下三部分内容： -- 总的概览：数据库时间和 SQL 执行时间概览。通过颜色优化法，你可以快速识别数据库负载特征和性能瓶颈。 -- 资源负载：关键指标和资源利用率，包含数据库 QPS、应用和数据库的连接信息和请求命令类型、数据库内部 TSO 和 KV 请求 OPS、TiDB 和 TiKV 的资源使用概况。 -- 自上而下的延迟分解：Query 延迟和连接空闲时间对比、Query 延迟分解、execute 阶段 TSO 请求和 KV 请求的延迟、TiKV 内部写延迟的分解等。 +- **总体概览**：数据库时间和 SQL 执行时间概览。通过颜色优化法，你可以快速识别数据库负载特征和性能瓶颈。 +- **资源负载**：关键指标和资源利用率，包含数据库 QPS、应用和数据库的连接信息和请求命令类型、数据库内部 TSO 和 KV 请求 OPS、TiDB 和 TiKV 的资源使用概况。 +- **自上而下的延迟分解**：Query 延迟和连接空闲时间对比、Query 延迟分解、execute 阶段 TSO 请求和 KV 请求的延迟、TiKV 内部写延迟的分解等。 以下为 Performance Overview 面板监控说明： ### Database Time by SQL Type -- database time: 每秒的总数据库时间 -- sql_type: 每种 SQL 语句每秒消耗的数据库时间 +- `database time`：每秒的总数据库时间 +- `sql_type`：每种 SQL 语句每秒消耗的数据库时间 ### Database Time by SQL Phase -- database time: 每秒的总数据库时间 -- get token/parse/compile/execute: 4 个 SQL 处理阶段每秒消耗的数据库时间 +- `database time`：每秒的总数据库时间 +- `get token/parse/compile/execute`：4 个 SQL 处理阶段每秒消耗的数据库时间 execute 执行阶段为绿色，其他三个阶段偏红色系，如果非绿色的颜色占比明显，意味着在执行阶段之外数据库消耗了过多时间，需要进一步分析根源。 ### SQL Execute Time Overview -- execute time: execute 阶段每秒消耗的数据库时间 -- tso_wait: execute 阶段每秒同步等待 TSO 的时间 -- kv request type: execute 阶段每秒等待每种 KV 请求类型的时间，总的 KV request 等待时间可能超过 execute time，因为 KV request 是并发的。 +- `execute time`：execute 阶段每秒消耗的数据库时间 +- `tso_wait`：execute 阶段每秒同步等待 TSO 的时间 +- `kv request type`：execute 阶段每秒等待每种 KV 请求类型的时间，总的 KV 请求等待时间可能超过 execute time，因为 KV 请求是并发的。 绿色系标识代表常规的写 KV 请求（例如 Prewrite 和 Commit），蓝色系标识代表常规的读 KV 请求，其他色系标识需要注意的问题。例如，悲观锁加锁请求为红色，TSO 等待为深褐色。如果非蓝色系或者非绿色系占比明显，意味着执行阶段存在异常的瓶颈。例如，当发生严重锁冲突时，红色的悲观锁时间会占比明显；当负载中 TSO 等待的消耗时间过长时，深褐色会占比明显。 ### QPS -QPS：按 `SELECT`、`INSERT`、`UPDATE` 等类型统计所有 TiDB 实例上每秒执行的 SQL 语句数量 +- `QPS`：按 `SELECT`、`INSERT`、`UPDATE` 等类型统计所有 TiDB 实例上每秒执行的 SQL 语句数量 ### CPS By Type -CPS By Type：按照类型统计所有 TiDB 实例每秒处理的命令数（Command Per Second） +- `CPS By Type`：按照类型统计所有 TiDB 实例每秒处理的命令数（Command Per Second） ### Queries Using Plan Cache OPS -Queries Using Plan Cache OPS：所有 TiDB 实例每秒使用 Plan Cache 的查询数量 +- `Queries Using Plan Cache OPS`：所有 TiDB 实例每秒使用 Plan Cache 的查询数量 ### KV/TSO Request OPS -- kv request total: 所有 TiDB 实例每秒总的 KV 请求数量 -- kv request by type: 按 `Get`、`Prewrite`、 `Commit` 等类型统计在所有 TiDB 实例每秒的请求数据 -- tso - cmd：所有 TiDB 实例每秒发送的 gRPC 请求的数量，每个 gRPC 请求包含一批 (batch) TSO 请求 -- tso - request：所有 TiDB 实例每秒的 TSO 请求数量 +- `kv request total`：所有 TiDB 实例每秒总的 KV 请求数量 +- `kv request by type`：按 `Get`、`Prewrite`、 `Commit` 等类型统计在所有 TiDB 实例每秒的请求数据 +- `tso - cmd`：所有 TiDB 实例每秒发送的 gRPC 请求的数量，每个 gRPC 请求包含一批 (batch) TSO 请求 +- `tso - request`：所有 TiDB 实例每秒的 TSO 请求数量 通常 tso - request 除以 tso - cmd 等于 TSO 请求 batch 的平均大小。 ### Connection Count -- total：所有 TiDB 的连接数 -- active connections：所有 TiDB 总的活跃连接数 -- 各个 TiDB 的连接数 +- `total`：所有 TiDB 的连接数 +- `active connections`：所有 TiDB 总的活跃连接数 +- 各个 TiDB 实例的连接数 -### TiDB CPU +### TiDB CPU/Memory -- avg：所有 TiDB 实例平均 CPU 利用率 -- delta：所有 TiDB 实例中最大 CPU 利用率减去所有 TiDB 实例中最小 CPU 利用率 -- max：所有 TiDB 实例中最大 CPU 利用率 +- `CPU-Avg`：所有 TiDB 实例的平均 CPU 利用率 +- `CPU-Delta`：所有 TiDB 实例中最大 CPU 利用率减去所有 TiDB 实例中最小 CPU 利用率 +- `CPU-Max`：所有 TiDB 实例中最大 CPU 利用率 +- `CPU-Quota`：TiDB 可以使用的 CPU 核数 +- `Mem-Max`：所有 TiDB 实例中最大内存利用率 -### TiKV CPU/IO MBps +### TiKV CPU/Memory -- CPU-Avg：所有 TiKV 实例平均 CPU 利用率 -- CPU-Delta：所有 TiKV 实例中最大 CPU 利用率减去所有 TiKV 实例中最小 CPU 利用率 -- CPU-MAX：所有 TiKV 实例中最大 CPU 利用率 -- IO-Avg：所有 TiKV 实例平均 MBps -- IO-Delta：所有 TiKV 实例中最大 MBps 减去所有 TiKV 实例中最小 MBps -- IO-MAX：所有 TiKV 实例中最大 MBps +- `CPU-Avg`：所有 TiKV 实例的平均 CPU 利用率 +- `CPU-Delta`：所有 TiKV 实例中最大 CPU 利用率减去所有 TiKV 实例中最小 CPU 利用率 +- `CPU-Max`：所有 TiKV 实例中最大 CPU 利用率 +- `CPU-Quota`：TiKV 可以使用的 CPU 核数 +- `Mem-Max`：所有 TiKV 实例中最大内存利用率 + +### PD CPU/Memory + +- `CPU-Max`：所有 PD 实例中最大 CPU 利用率 +- `CPU-Quota`：PD 可以使用的 CPU 核数 +- `Mem-Max`：所有 PD 实例中最大内存利用率 + +### Read Traffic + +- `TiDB -> Client`：从 TiDB 到客户端的出站流量统计 +- `Rocksdb -> TiKV`：TiKV 在存储层读操作过程中从 RocksDB 读取的数据流量 + +### Write Traffic + +- `Client -> TiDB`：从客户端到 TiDB 的入站流量统计 +- `TiDB -> TiKV: general`：前台事务从 TiDB 写入到 TiKV 的速率 +- `TiDB -> TiKV: internal`：后台事务从 TiDB 写入到 TiKV 的速率 +- `TiKV -> Rocksdb`：从 TiKV 写入到 RocksDB 的流量 +- `RocksDB Compaction`：RocksDB compaction 操作产生的总读写 I/O 流量。 ### Duration -- Duration：执行时间解释 +- `Duration`：执行时间解释 - 从客户端网络请求发送到 TiDB，到 TiDB 执行结束后返回给客户端的时间。一般情况下，客户端请求都是以 SQL 语句的形式发送，但也可以包含 `COM_PING`、`COM_SLEEP`、`COM_STMT_FETCH`、`COM_SEND_LONG_DATA` 之类的命令执行时间。 - 由于 TiDB 支持 Multi-Query，因此，客户端可以一次性发送多条 SQL 语句，如 `select 1; select 1; select 1;`。此时的执行时间是所有 SQL 语句执行完成的总时间。 -- avg：所有请求命令的平均执行时间 -- 99： 所有请求命令的 P99 执行时间 -- avg by type：按 `SELECT`、`INSERT`、`UPDATE` 类型统计所有 TiDB 实例上所有请求命令的平均执行时间 +- `avg`：所有请求命令的平均执行时间 +- `99`：所有请求命令的 P99 执行时间 +- `avg by type`：按 `SELECT`、`INSERT`、`UPDATE` 类型统计所有 TiDB 实例上所有请求命令的平均执行时间 ### Connection Idle Duration Connection Idle Duration 指空闲连接的持续时间。 -- avg-in-txn：处于事务中，空闲连接的平均持续时间 -- avg-not-in-txn：没有处于事务中，空闲连接的平均持续时间 -- 99-in-txn：处于事务中，空闲连接的 P99 持续时间 -- 99-not-in-txn：没有处于事务中，空闲连接的 P99 持续时间 +- `avg-in-txn`：处于事务中，空闲连接的平均持续时间 +- `avg-not-in-txn`：没有处于事务中，空闲连接的平均持续时间 +- `99-in-txn`：处于事务中，空闲连接的 P99 持续时间 +- `99-not-in-txn`：没有处于事务中，空闲连接的 P99 持续时间 ### Parse Duration、Compile Duration 和 Execute Duration -- Parse Duration：SQL 语句解析耗时统计 -- Compile Duration：将解析后的 SQL AST 编译成执行计划的耗时 -- Execution Duration：执行 SQL 语句执行计划耗时 +- `Parse Duration`：SQL 语句解析耗时统计 +- `Compile Duration`：将解析后的 SQL AST 编译成执行计划的耗时 +- `Execution Duration`：执行 SQL 语句执行计划耗时 这三个时间指标均包含均所有 TiDB 实例的平均值和 P99 值。 @@ -127,16 +147,16 @@ Connection Idle Duration 指空闲连接的持续时间。 ### PD TSO Wait/RPC Duration -- wait - avg：所有 TiDB 实例等待从 PD 返回 TSO 的平均时间 -- rpc - avg：所有 TiDB 实例从向 PD 发送获取 TSO 的请求到接收到 TSO 的平均耗时 -- wait - 99：所有 TiDB 实例等待从 PD 返回 TSO 的 P99 时间 -- rpc - 99：所有 TiDB 实例从向 PD 发送获取 TSO 的请求到接收到 TSO 的 P99 耗时 +- `wait - avg`：所有 TiDB 实例等待从 PD 返回 TSO 的平均时间 +- `rpc - avg`：所有 TiDB 实例从向 PD 发送获取 TSO 的请求到接收到 TSO 的平均耗时 +- `wait - 99`：所有 TiDB 实例等待从 PD 返回 TSO 的 P99 时间 +- `rpc - 99`：所有 TiDB 实例从向 PD 发送获取 TSO 的请求到接收到 TSO 的 P99 耗时 ### Storage Async Write Duration、Store Duration 和 Apply Duration -- Storage Async Write Duration：异步写所花费的时间 -- Store Duration：异步写 Store 步骤所花费的时间 -- Apply Duration：异步写 Apply 步骤所花费的时间 +- `Storage Async Write Duration`：异步写所花费的时间 +- `Store Duration`：异步写入过程中，在存储循环 (store loop) 中所花费的时间 +- `Apply Duration`：异步写入过程中，在应用循环 (apply loop) 中所花费的时间 这三个时间指标都包含所有 TiKV 实例的平均值和 P99 值 @@ -144,8 +164,8 @@ Connection Idle Duration 指空闲连接的持续时间。 ### Append Log Duration、Commit Log Duration 和 Apply Log Duration -- Append Log Duration：Raft append 日志所花费的时间 -- Commit Log Duration：Raft commit 日志所花费的时间 -- Apply Log Duration：Raft apply 日志所花费的时间 +- `Append Log Duration`：Raft append 日志所花费的时间 +- `Commit Log Duration`：Raft commit 日志所花费的时间 +- `Apply Log Duration`：Raft apply 日志所花费的时间 这三个时间指标均包含所有 TiKV 实例的平均值和 P99 值。 \ No newline at end of file diff --git a/dashboard/dashboard-ops-deploy.md b/dashboard/dashboard-ops-deploy.md index 3146a91e6355..59e6857a801e 100644 --- a/dashboard/dashboard-ops-deploy.md +++ b/dashboard/dashboard-ops-deploy.md @@ -1,6 +1,5 @@ --- title: 部署 TiDB Dashboard -aliases: ['/docs-cn/dev/dashboard/dashboard-ops-deploy/'] summary: TiDB Dashboard 是内置于 TiDB 4.0 或更高版本的 PD 组件中的界面，无需额外部署。对于 TiDB v6.5.0 及 TiDB Operator v1.4.0 之后的版本，在 Kubernetes 上支持将 TiDB Dashboard 作为独立的 Pod 部署。部署标准 TiDB 集群的文档可参考快速试用 TiDB 集群、生产环境部署和 Kubernetes 环境部署。当集群中部署了多个 PD 实例时，仅有一个 PD 实例会提供 TiDB Dashboard 服务。可通过 TiUP 查看实际运行 TiDB Dashboard 服务的 PD 实例，并切换其他 PD 实例提供 TiDB Dashboard 服务。也可以禁用和重新启用 TiDB Dashboard。 --- @@ -10,7 +9,7 @@ TiDB Dashboard 界面内置于 TiDB 4.0 或更高版本的 PD 组件中，无需 > **注意：** > -> TiDB v6.5.0 且 TiDB Operator v1.4.0 之后，在 Kubernetes 上支持将 TiDB Dashboard 作为独立的 Pod 部署。具体信息，参考 [TiDB Operator 部署独立的 TiDB Dashboard](https://docs.pingcap.com/zh/tidb-in-kubernetes/dev/get-started#部署独立的-tidb-dashboard)。 +> TiDB v6.5.0 且 TiDB Operator v1.4.0 之后，在 Kubernetes 上支持将 TiDB Dashboard 作为独立的 Pod 部署。具体信息，参考 [TiDB Operator 部署独立的 TiDB Dashboard](https://docs.pingcap.com/zh/tidb-in-kubernetes/v1.6/get-started#部署独立的-tidb-dashboard)。 请参阅下列文档了解如何部署标准 TiDB 集群： diff --git a/dashboard/dashboard-ops-reverse-proxy.md b/dashboard/dashboard-ops-reverse-proxy.md index a9154a959f75..7a698a65ce3f 100644 --- a/dashboard/dashboard-ops-reverse-proxy.md +++ b/dashboard/dashboard-ops-reverse-proxy.md @@ -1,6 +1,5 @@ --- title: 通过反向代理使用 TiDB Dashboard -aliases: ['/docs-cn/dev/dashboard/dashboard-ops-reverse-proxy/'] summary: TiDB Dashboard 可通过反向代理安全提供给外部网络。首先获取实际地址，然后配置反向代理，最后修改路径前缀。详细步骤可参考官方文档。 --- diff --git a/dashboard/dashboard-ops-security.md b/dashboard/dashboard-ops-security.md index bb3d3befff72..a85138909425 100644 --- a/dashboard/dashboard-ops-security.md +++ b/dashboard/dashboard-ops-security.md @@ -1,6 +1,5 @@ --- title: 提高 TiDB Dashboard 安全性 -aliases: ['/docs-cn/dev/dashboard/dashboard-ops-security/'] summary: TiDB Dashboard 需要提高安全性。建议为 `root` 用户设置强密码或禁用 `root` 账户，并为 TiDB Dashboard 创建最小权限用户。使用防火墙阻止不可信访问，配置反向代理仅代理 TiDB Dashboard，并为反向代理开启 TLS。其他建议的安全措施包括为组件间通信和客户端服务端间通信开启加密传输。 --- @@ -30,7 +29,7 @@ TiDB Dashboard 的账号体系与 TiDB SQL 用户一致，并基于 TiDB SQL 用 > **注意：** > -> TiDB v6.5.0 且 TiDB Operator v1.4.0 之后，在 Kubernetes 上支持将 TiDB Dashboard 作为独立的 Pod 部署。在 TiDB Operator 环境，可直接访问该 Pod 的 IP 来打开 TiDB Dashboard，该端口不与其他 PD 内部特权接口关联，对外提供该端口不需要额外的防火墙操作。具体信息，参考 [TiDB Operator 部署独立的 TiDB Dashboard](https://docs.pingcap.com/zh/tidb-in-kubernetes/dev/get-started#部署独立的-tidb-dashboard)。 +> TiDB v6.5.0 且 TiDB Operator v1.4.0 之后，在 Kubernetes 上支持将 TiDB Dashboard 作为独立的 Pod 部署。在 TiDB Operator 环境，可直接访问该 Pod 的 IP 来打开 TiDB Dashboard，该端口不与其他 PD 内部特权接口关联，对外提供该端口不需要额外的防火墙操作。具体信息，参考 [TiDB Operator 部署独立的 TiDB Dashboard](https://docs.pingcap.com/zh/tidb-in-kubernetes/v1.6/get-started#部署独立的-tidb-dashboard)。 TiDB Dashboard 通过 PD Client 端口提供服务，默认为 。尽管 TiDB Dashboard 需要验证身份，但 PD Client 端口上承载的其他 PD 内部特权接口不需要验证身份，且能进行特权操作，例如 。因此，将 PD Client 端口直接暴露给外部网络具有极大的风险。 diff --git a/dashboard/dashboard-overview.md b/dashboard/dashboard-overview.md index 6adcf1ac5412..a4848c08bafe 100644 --- a/dashboard/dashboard-overview.md +++ b/dashboard/dashboard-overview.md @@ -1,6 +1,5 @@ --- title: TiDB Dashboard 概况页面 -aliases: ['/docs-cn/dev/dashboard/dashboard-overview/'] summary: TiDB Dashboard 概况页面显示整个集群的 QPS、查询延迟、Top SQL 语句、最近的慢查询、实例状态和监控及告警信息。登录后默认进入该页面，也可通过左侧导航条点击概况进入。包含最近一小时整个集群的 QPS 和查询延迟，以及最近一段时间内累计耗时最多的 SQL 语句和运行时间超过一定阈值的慢查询。还显示各个实例的节点数和状态，以及提供了便捷的链接方便用户查看详细监控或告警。 --- diff --git a/dashboard/dashboard-profiling.md b/dashboard/dashboard-profiling.md index ef47cedb403c..11b2b5e7fe80 100644 --- a/dashboard/dashboard-profiling.md +++ b/dashboard/dashboard-profiling.md @@ -1,7 +1,6 @@ --- title: TiDB Dashboard 实例性能分析 - 手动分析页面 summary: 了解如何收集集群各个实例当前性能数据，从而分析复杂问题 -aliases: ['/docs-cn/dev/dashboard/dashboard-profiling/'] --- # TiDB Dashboard 实例性能分析 - 手动分析页面 diff --git a/dashboard/dashboard-resource-manager.md b/dashboard/dashboard-resource-manager.md index 4e2f4157485a..6858dd93e63e 100644 --- a/dashboard/dashboard-resource-manager.md +++ b/dashboard/dashboard-resource-manager.md @@ -5,7 +5,7 @@ summary: 介绍如何使用 TiDB Dashboard 的资源管控页面查看资源管 # TiDB Dashboard 资源管控页面 -为使用[资源管控 (Resource Control)](/tidb-resource-control.md) 特性实现资源隔离，集群管理员可以定义资源组 (Resource Group)，通过资源组限定配额。在进行资源规划之前，你需要了解集群的整体容量。该页面可以帮助你查看资源管控相关信息，以便预估集群容量，更好地进行资源配置。 +为使用[资源管控 (Resource Control)](/tidb-resource-control-ru-groups.md) 特性实现资源隔离，集群管理员可以定义资源组 (Resource Group)，通过资源组限定配额。在进行资源规划之前，你需要了解集群的整体容量。该页面可以帮助你查看资源管控相关信息，以便预估集群容量，更好地进行资源配置。 ## 访问方式 @@ -34,7 +34,7 @@ summary: 介绍如何使用 TiDB Dashboard 的资源管控页面查看资源管 ## 容量估算 -在进行资源规划之前，你需要了解集群的整体容量。目前提供两种估算方式预估当前集群的 [Request Unit (RU)](/tidb-resource-control.md#什么是-request-unit-ru#什么是-request-unit-ru) 的容量： +在进行资源规划之前，你需要了解集群的整体容量。目前提供两种估算方式预估当前集群的 [Request Unit (RU)](/tidb-resource-control-ru-groups.md#什么是-request-unit-ru#什么是-request-unit-ru) 的容量： - [基于硬件部署估算容量](/sql-statements/sql-statement-calibrate-resource.md#基于硬件部署估算容量) (Calibrate by Hardware) @@ -47,7 +47,7 @@ summary: 介绍如何使用 TiDB Dashboard 的资源管控页面查看资源管 ![基于硬件部署估算容量](/media/dashboard/dashboard-resource-manager-calibrate-by-hardware.png) - 用户资源分组总请求单元 (Total RU of user resource groups) 表示当前除 `default` 用户外的 RU 总量。当该数值小于容量估算值时，系统会发出提醒。系统预定义的 `default` 资源组默认拥有无限用量。当所有用户都属于 `default` 资源组时，资源分配方式与关闭资源管控时相同。 + 用户资源分组总请求单元 (Total RU of user resource groups) 表示当前除 `default` 用户外的 RU 总量。当该数值大于容量估算值时，系统会发出提醒。系统预定义的 `default` 资源组默认拥有无限用量。当所有用户都属于 `default` 资源组时，资源分配方式与关闭资源管控时相同。 - [根据实际负载估算容量](/sql-statements/sql-statement-calibrate-resource.md#根据实际负载估算容量) (Calibrate by Workload) diff --git a/dashboard/dashboard-session-sso.md b/dashboard/dashboard-session-sso.md index aed36167704b..887d0ddf402d 100644 --- a/dashboard/dashboard-session-sso.md +++ b/dashboard/dashboard-session-sso.md @@ -17,6 +17,10 @@ TiDB Dashboard 支持基于 [OIDC](https://openid.net/connect/) 协议的单点 3. 在**单点登录** (Single Sign-On) 区域下，开启**允许使用 SSO 登录到 TiDB Dashboard** (Enable to use SSO when sign into TiDB Dashboard)。 + > **注意：** + > + > 如果你的账号没有 `SYSTEM_VARIABLES_ADMIN` 权限，**允许使用 SSO 登录到 TiDB Dashboard** (Enable to use SSO when sign into TiDB Dashboard) 选项会被禁用。有关权限的更多信息，请参考 [TiDB Dashboard 用户管理](/dashboard/dashboard-user.md)。 + 4. 在表单中填写 **OIDC Client ID** 和 **OIDC Discovery URL** 字段。 一般可以从 SSO 服务的提供商处获取到这两个字段信息： diff --git a/dashboard/dashboard-slow-query.md b/dashboard/dashboard-slow-query.md index bb0aefb06699..60a155b7e7f3 100644 --- a/dashboard/dashboard-slow-query.md +++ b/dashboard/dashboard-slow-query.md @@ -1,7 +1,6 @@ --- title: TiDB Dashboard 慢查询页面 summary: 了解如何在 TiDB Dashboard 中查看慢查询。 -aliases: ['/docs-cn/dev/dashboard/dashboard-slow-query/'] --- # TiDB Dashboard 慢查询页面 diff --git a/dashboard/dashboard-statement-details.md b/dashboard/dashboard-statement-details.md index 9b1904f3622a..09b8b6a42647 100644 --- a/dashboard/dashboard-statement-details.md +++ b/dashboard/dashboard-statement-details.md @@ -1,7 +1,6 @@ --- title: TiDB Dashboard SQL 语句分析执行详情页面 summary: 查看单个 SQL 语句执行的详细情况 -aliases: ['/docs-cn/dev/dashboard/dashboard-statement-details/','/docs-cn/dev/dashboard/dashboard-statement-detail/'] --- # TiDB Dashboard SQL 语句分析执行详情页面 diff --git a/dashboard/dashboard-statement-list.md b/dashboard/dashboard-statement-list.md index f6ffc351b00b..f8142553dfd3 100644 --- a/dashboard/dashboard-statement-list.md +++ b/dashboard/dashboard-statement-list.md @@ -1,7 +1,6 @@ --- title: TiDB Dashboard SQL 语句分析列表页面 summary: 查看所有 SQL 语句在集群上执行情况 -aliases: ['/docs-cn/dev/dashboard/dashboard-statement-list/'] --- # TiDB Dashboard SQL 语句分析执行详情页面 @@ -70,7 +69,7 @@ SQL 语句分析页面所展示的所有数据都来自于 TiDB Statement 系统 ### Others -[`tidb_stmt_summary_max_stmt_count`](/system-variables.md#tidb_stmt_summary_max_stmt_count-从-v40-版本开始引入) 控制 Statement Summary 系统表保存的 SQL 种类数量。当 SQL 种类超过该值时，会移除最近没有出现的 SQL。这些 SQL 将会被 `DIGEST` 为 `NULL` 的行数据统计。`DIGEST` 为 `NULL` 的行数据在 TiDB Dashboard SQL 语句分析列表页面中将会显示为 `Others`，如下所示： +[`tidb_stmt_summary_max_stmt_count`](/system-variables.md#tidb_stmt_summary_max_stmt_count-从-v40-版本开始引入) 用于限制 [`statements_summary`](/statement-summary-tables.md#statements_summary) 和 [`statements_summary_history`](/statement-summary-tables.md#statements_summary_history) 这两张表在内存中可存储的 SQL digest 总数。当超出该限制时，TiDB 会移除最近没有使用的 SQL。这些 SQL 将会被 `DIGEST` 为 `NULL` 的行数据统计。`DIGEST` 为 `NULL` 的行数据在 TiDB Dashboard SQL 语句分析列表页面中将会显示为 `Others`，如下所示： ![Others 行](/media/dashboard/dashboard-statement-other-row.png) diff --git a/data-type-date-and-time.md b/data-type-date-and-time.md index c0eaf5ff0235..87ca9b493a64 100644 --- a/data-type-date-and-time.md +++ b/data-type-date-and-time.md @@ -1,6 +1,5 @@ --- title: 日期和时间类型 -aliases: ['/docs-cn/dev/data-type-date-and-time/','/docs-cn/dev/reference/sql/data-types/date-and-time/'] summary: TiDB 支持 MySQL 的所有日期和时间类型，包括 DATE、TIME、DATETIME、TIMESTAMP 和 YEAR。每种类型都有有效值范围，值为 0 表示无效值。TIMESTAMP 和 DATETIME 类型能自动生成新的时间值。关于日期和时间值类型，需要注意日期部分必须是“年 - 月 - 日”的格式，如果日期的年份部分是 2 位数，TiDB 会根据具体规则进行转换。不同类型的零值如下表所示：DATE:0000-00-00, TIME:00:00:00, DATETIME:0000-00-00 00:00:00, TIMESTAMP:0000-00-00 00:00:00, YEAR:0000。如果 SQL 模式允许使用无效的 DATE、DATETIME、TIMESTAMP 值，无效值会自动转换为相应的零值。 --- diff --git a/data-type-default-values.md b/data-type-default-values.md index 0039a4b21001..136cc5d1b224 100644 --- a/data-type-default-values.md +++ b/data-type-default-values.md @@ -1,6 +1,5 @@ --- title: 数据类型的默认值 -aliases: ['/docs-cn/dev/data-type-default-values/','/docs-cn/dev/reference/sql/data-types/default-values/'] summary: 数据类型的默认值描述了列的默认值设置规则。默认值必须是常量，对于时间类型可以使用特定函数。从 v8.0.0 开始，BLOB、TEXT 和 JSON 可以设置表达式默认值。如果列没有设置 DEFAULT，TiDB 会根据规则添加隐式默认值。对于 NOT NULL 列，根据 SQL_MODE 进行不同行为。表达式默认值是实验特性，不建议在生产环境中使用。MySQL 8.0.13 开始支持在 DEFAULT 子句中指定表达式为默认值。TiDB 支持为 BLOB、TEXT 和 JSON 数据类型分配默认值，但仅支持通过表达式来设置。 --- @@ -36,7 +35,7 @@ summary: 数据类型的默认值描述了列的默认值设置规则。默认 MySQL 从 8.0.13 开始支持在 `DEFAULT` 子句中指定表达式为默认值。具体可参考 [Explicit Default Handling as of MySQL 8.0.13](https://dev.mysql.com/doc/refman/8.0/en/data-type-defaults.html#data-type-defaults-explicit)。 -从 v8.0.0 开始，TiDB 在 `DEFAULT` 子句中新增支持指定以下表达式作为字段的默认值： +TiDB 支持在 `DEFAULT` 子句中指定以下表达式作为字段的默认值： * `UPPER(SUBSTRING_INDEX(USER(), '@', 1))` * `REPLACE(UPPER(UUID()), '-', '')` @@ -46,9 +45,50 @@ MySQL 从 8.0.13 开始支持在 `DEFAULT` 子句中指定表达式为默认值 * `DATE_FORMAT(NOW(), '%Y-%m-%d %H.%i.%s')` * `DATE_FORMAT(NOW(), '%Y-%m-%d %H:%i:%s')` * `STR_TO_DATE('1980-01-01', '%Y-%m-%d')` +* [`CURRENT_TIMESTAMP()`](/functions-and-operators/date-and-time-functions.md) 和 [`CURRENT_DATE()`](/functions-and-operators/date-and-time-functions.md)：均使用默认的时间精度(fractional seconds precision, fsp) +* [`JSON_OBJECT()`](/functions-and-operators/json-functions.md)，[`JSON_ARRAY()`](/functions-and-operators/json-functions.md)，[`JSON_QUOTE()`](/functions-and-operators/json-functions.md) +* [`NEXTVAL()`](/functions-and-operators/sequence-functions.md#nextval) +* [`RAND()`](/functions-and-operators/numeric-functions-and-operators.md) +* [`UUID()`](/functions-and-operators/miscellaneous-functions.md#uuid)，[`UUID_TO_BIN()`](/functions-and-operators/miscellaneous-functions.md#uuid_to_bin) +* [`VEC_FROM_TEXT()`](/ai/reference/vector-search-functions-and-operators.md#vec_from_text) -此外，从 v8.0.0 开始，TiDB 额外支持 `BLOB`、`TEXT` 以及 `JSON` 数据类型分配默认值，但是默认值仅支持通过表达式来设置。以下是 `BLOB` 的示例： +TiDB 支持为 `BLOB`、`TEXT` 以及 `JSON` 数据类型分配默认值，但是，你只能使用表达式来设置这些数据类型的默认值，而不能使用字面量。 + +以下是 `BLOB` 的示例： + +```sql +CREATE TABLE t2 ( + b BLOB DEFAULT (RAND()) +); +``` + +以下是使用 UUID 的示例： ```sql -CREATE TABLE t2 (b BLOB DEFAULT (RAND())); +CREATE TABLE t3 ( + uuid BINARY(16) DEFAULT (UUID_TO_BIN(UUID())), + name VARCHAR(255) +); ``` + +更多关于如何使用 UUID 的内容，请参考 [UUID 最佳实践](/best-practices/uuid.md)。 + +以下是使用 `JSON` 的示例： + +```sql +CREATE TABLE t4 ( + id bigint AUTO_RANDOM PRIMARY KEY, + j json DEFAULT (JSON_OBJECT("a", 1, "b", 2)) +); +``` + +以下是使用 `JSON` 时不被允许的示例： + +```sql +CREATE TABLE t5 ( + id bigint AUTO_RANDOM PRIMARY KEY, + j json DEFAULT ('{"a": 1, "b": 2}') +); +``` + +最后两个示例都描述了相似的默认值，但只有第一个是允许的，因为它使用的是表达式而不是字面量。 diff --git a/data-type-json.md b/data-type-json.md index df8b1e5fc657..61ccf346fe03 100644 --- a/data-type-json.md +++ b/data-type-json.md @@ -1,6 +1,5 @@ --- title: JSON 数据类型 -aliases: ['/docs-cn/dev/data-type-json/','/docs-cn/dev/reference/sql/data-types/json/'] summary: JSON 类型存储半结构化数据，使用 Binary 格式序列化，加快查询和解析速度。JSON 字段不能创建索引，但可以对 JSON 文档中的子字段创建索引。TiDB 仅支持下推部分 JSON 函数到 TiFlash，不建议使用 BR 恢复包含 JSON 列的数据到 v6.3.0 之前的 TiDB 集群。请勿同步非标准 JSON 类型的数据。MySQL 误标记二进制类型数据为 STRING 类型，TiDB 保持正确的二进制类型。ENUM 或 SET 数据类型转换为 JSON 时，TiDB 会检查格式正确性。TiDB 支持使用 ORDER BY 对 JSON Array 或 JSON Object 进行排序。在 INSERT JSON 列时，TiDB 会将值隐式转换为 JSON。 --- diff --git a/data-type-numeric.md b/data-type-numeric.md index 6a609d9b505d..a1672461b114 100644 --- a/data-type-numeric.md +++ b/data-type-numeric.md @@ -1,6 +1,5 @@ --- title: 数值类型 -aliases: ['/docs-cn/dev/data-type-numeric/','/docs-cn/dev/reference/sql/data-types/numeric/'] summary: TiDB 支持 MySQL 的所有数值类型，包括整数类型、浮点类型和定点类型。整数类型包括 BIT、BOOLEAN、TINYINT、SMALLINT、MEDIUMINT、INTEGER 和 BIGINT，存储空间和取值范围各不相同。浮点类型包括 FLOAT 和 DOUBLE，存储空间分别为 4 和 8 字节。定点类型包括 DECIMAL 和 NUMERIC，可设置小数位数和小数点后位数。建议使用 DECIMAL 类型存储精确值。 --- diff --git a/data-type-overview.md b/data-type-overview.md index 90e50acd8499..3becd9672911 100644 --- a/data-type-overview.md +++ b/data-type-overview.md @@ -1,6 +1,5 @@ --- title: 数据类型概述 -aliases: ['/docs-cn/dev/data-type-overview/','/docs-cn/dev/reference/sql/data-types/overview/'] summary: TiDB 支持除了空间类型（SPATIAL）之外的所有 MySQL 数据类型，包括数值型类型、字符串类型、时间和日期类型、JSON 类型。数据类型定义一般为 T(M[, D])，其中 T 表示具体的类型，M 在整数类型中表示最大显示长度，在浮点数或者定点数中表示精度，在字符类型中表示最大长度，D 表示浮点数、定点数的小数位长度，fsp 在时间和日期类型里的 TIME、DATETIME 以及 TIMESTAMP 中表示秒的精度，其取值范围是 0 到 6，值为 0 表示没有小数部分，如果省略，则默认精度为 0。 --- diff --git a/data-type-string.md b/data-type-string.md index e602ececfbc3..6895af7a2ed1 100644 --- a/data-type-string.md +++ b/data-type-string.md @@ -1,6 +1,5 @@ --- title: 字符串类型 -aliases: ['/docs-cn/dev/data-type-string/','/docs-cn/dev/reference/sql/data-types/string/'] summary: TiDB 支持 MySQL 所有字符串类型，包括 CHAR、VARCHAR、BINARY、VARBINARY、BLOB、TEXT、ENUM 和 SET。CHAR 是定长字符串，长度固定为创建表时声明的长度。VARCHAR 是变长字符串，空间占用大小不得超过 65535 字节。TEXT 是文本串，最大列长为 65535 字节。TINYTEXT 最大列长度为 255。MEDIUMTEXT 最大列长度为 16777215。LONGTEXT 最大列长度为 4294967295。BINARY 存储二进制字符串。VARBINARY 存储二进制字符串。BLOB 是二进制大文件，最大列长度为 65535 字节。TINYBLOB 最大列长度为 255。MEDIUMBLOB 最大列长度为 16777215。LONGBLOB 最大列长度为 4294967295。ENUM 是枚举类型，值必须从固定集合中选取。SET 是集合类型，包含零个或多个值的字符串。 --- diff --git a/ddl_embedded_analyze.md b/ddl_embedded_analyze.md new file mode 100644 index 000000000000..7d7d4ae13d3d --- /dev/null +++ b/ddl_embedded_analyze.md @@ -0,0 +1,177 @@ +--- +title: 内嵌于 DDL 的 Analyze +summary: 本文介绍内嵌于新建或重组索引的 DDL 中的 Analyze 特性，用于确保新索引的统计信息及时更新。 +--- + +# 内嵌于 DDL 的 Analyze 从 v8.5.4 开始引入 + +本文介绍内嵌于以下两类 DDL 的 Analyze 特性： + +- 新建索引的 DDL：[`ADD INDEX`](/sql-statements/sql-statement-add-index.md) +- 重组已有索引的 DDL：[`MODIFY COLUMN`](/sql-statements/sql-statement-modify-column.md) 和 [`CHANGE COLUMN`](/sql-statements/sql-statement-change-column.md) + +开启该特性后，TiDB 会在新索引对用户可见前自动执行一次 Analyze（统计信息收集），以避免新建或重组索引后因统计信息暂不可用而导致优化器估算不准，从而引起执行计划变更的问题。 + +## 使用场景 + +在一些交替执行索引新增或修改的 DDL 操作场景中，已有的稳定查询可能因为新索引缺乏统计信息而出现代价估算偏差，导致优化器生成次优计划。详情可参考 [Issue #57948](https://github.com/pingcap/tidb/issues/57948)。 + +例如： + +```sql +CREATE TABLE t (a INT, b INT); +INSERT INTO t VALUES (1, 1), (2, 2), (3, 3); +INSERT INTO t SELECT * FROM t; -- * N times + +ALTER TABLE t ADD INDEX idx_a (a); + +EXPLAIN SELECT * FROM t WHERE a > 4; +``` + +``` ++-------------------------+-----------+-----------+---------------+--------------------------------+ +| id | estRows | task | access object | operator info | ++-------------------------+-----------+-----------+---------------+--------------------------------+ +| TableReader_8 | 131072.00 | root | | data:Selection_7 | +| └─Selection_7 | 131072.00 | cop[tikv] | | gt(test.t.a, 4) | +| └─TableFullScan_6 | 393216.00 | cop[tikv] | table:t | keep order:false, stats:pseudo | ++-------------------------+-----------+-----------+---------------+--------------------------------+ +3 rows in set (0.002 sec) +``` + +从以上执行计划可以看到，由于新建索引尚未生成统计信息，TiDB 在路径估算时只能依赖启发式规则。除非索引访问路径无需回表且代价显著更低，否则优化器倾向于选择估算更稳定的现有路径，因此上述示例中使用了全表扫描。然而，从数据分布角度来看，`t.a > 4` 实际返回 0 行，如果能使用新建索引 `idx_a`，查询可以快速定位到相关行，从而避免全表扫描。在该示例中，由于 DDL 创建索引后 TiDB 未能及时收集索引统计信息，生成的执行计划不是最优的，但优化器会继续沿用原有计划，因此查询性能不会出现突变或退化。然而，根据 [Issue #57948](https://github.com/pingcap/tidb/issues/57948)，在某些情况下，启发式规则可能会导致新旧索引进行不合理的比较，从而裁剪原查询计划依赖的索引，最终 fallback 到全表扫描。 + +从 v8.5.0 起，TiDB 对索引的启发式比较和统计信息缺失时的行为进行了优化。但在部分复杂场景中，在 DDL 执行过程中内嵌 Analyze 仍是防止执行计划变更的最佳方案。你可以通过系统变量 [`tidb_stats_update_during_ddl`](/system-variables.md#tidb_stats_update_during_ddl-从-v854-版本开始引入) 控制在索引创建或重组阶段是否执行内嵌 Analyze。该变量默认值为 `OFF`。 + +## 新建索引 `ADD INDEX` 的 DDL + +当 `tidb_stats_update_during_ddl` 设置为 `ON` 时，执行 [`ADD INDEX`](/sql-statements/sql-statement-add-index.md) 操作将在 Reorg 阶段结束后自动执行内嵌的 Analyze 命令。此 Analyze 命令会在新索引对用户可见前，分析相关新建索引的统计信息，然后再继续执行 `ADD INDEX` 的剩余阶段。 + +考虑到 Analyze 可能会有一定的耗时，TiDB 会以首次 Reorg 的执行时间为参考设置超时阈值。若 Analyze 超时，`ADD INDEX` 将不再同步等待 Analyze 完成，而是继续执行后续流程，使索引提前对用户可见。这意味着，该新索引的统计信息会在 Analyze 异步完成后更新。 + +示例： + +```sql +CREATE TABLE t (a INT, b INT, c INT); +Query OK, 0 rows affected (0.011 sec) + +INSERT INTO t VALUES (1, 1, 1), (2, 2, 2), (3, 3, 3); +Query OK, 3 rows affected (0.003 sec) +Records: 3 Duplicates: 0 Warnings: 0 + +SET @@tidb_stats_update_during_ddl = 1; +Query OK, 0 rows affected (0.001 sec) + +ALTER TABLE t ADD INDEX idx (a, b); +Query OK, 0 rows affected (0.049 sec) +``` + +```sql +EXPLAIN SELECT a FROM t WHERE a > 1; +``` + +``` ++------------------------+---------+-----------+--------------------------+----------------------------------+ +| id | estRows | task | access object | operator info | ++------------------------+---------+-----------+--------------------------+----------------------------------+ +| IndexReader_7 | 4.00 | root | | index:IndexRangeScan_6 | +| └─IndexRangeScan_6 | 4.00 | cop[tikv] | table:t, index:idx(a, b) | range:(1,+inf], keep order:false | ++------------------------+---------+-----------+--------------------------+----------------------------------+ +2 rows in set (0.002 sec) +``` + +```sql +SHOW STATS_HISTOGRAMS WHERE table_name = "t"; +``` + +``` ++---------+------------+----------------+-------------+----------+---------------------+----------------+------------+--------------+-------------+-------------+-----------------+----------------+----------------+---------------+ +| Db_name | Table_name | Partition_name | Column_name | Is_index | Update_time | Distinct_count | Null_count | Avg_col_size | Correlation | Load_status | Total_mem_usage | Hist_mem_usage | Topn_mem_usage | Cms_mem_usage | ++---------+------------+----------------+-------------+----------+---------------------+----------------+------------+--------------+-------------+-------------+-----------------+----------------+----------------+---------------+ +| test | t | | a | 0 | 2025-10-30 20:17:57 | 3 | 0 | 0.5 | 1 | allLoaded | 155 | 0 | 155 | 0 | +| test | t | | idx | 1 | 2025-10-30 20:17:57 | 3 | 0 | 0 | 0 | allLoaded | 182 | 0 | 182 | 0 | ++---------+------------+----------------+-------------+----------+---------------------+----------------+------------+--------------+-------------+-------------+-----------------+----------------+----------------+---------------+ +2 rows in set (0.013 sec) +``` + +```sql +ADMIN SHOW DDL JOBS 1; +``` + +``` ++--------+---------+--------------------------+---------------+----------------------+-----------+----------+-----------+----------------------------+----------------------------+----------------------------+---------+----------------------------------------+ +| JOB_ID | DB_NAME | TABLE_NAME | JOB_TYPE | SCHEMA_STATE | SCHEMA_ID | TABLE_ID | ROW_COUNT | CREATE_TIME | START_TIME | END_TIME | STATE | COMMENTS | ++--------+---------+--------------------------+---------------+----------------------+-----------+----------+-----------+----------------------------+----------------------------+----------------------------+---------+----------------------------------------+ +| 151 | test | t | add index | write reorganization | 2 | 148 | 6291456 | 2025-10-29 00:14:47.181000 | 2025-10-29 00:14:47.183000 | NULL | running | analyzing, txn-merge, max_node_count=3 | ++--------+---------+--------------------------+---------------+----------------------+-----------+----------+-----------+----------------------------+----------------------------+----------------------------+---------+----------------------------------------+ +1 rows in set (0.001 sec) +``` + +从 `ADD INDEX` 示例来看，当 `tidb_stats_update_during_ddl` 设置为 `ON` 时，在 `ADD INDEX` DDL 执行结束后，可以看到其之后运行的 `EXPLAIN` 查询中，相关索引 `idx` 的统计信息已经被自动收集并加载到内存中（可通过 `SHOW STATS_HISTOGRAMS` 语句的输出结果得到验证）。因此，优化器可以立即在范围扫描（Range Scan）中使用这些统计信息。如果索引的创建或重组以及 Analyze 过程耗时较长，可以通过 `ADMIN SHOW DDL JOBS` 查看 DDL Job 的状态。当输出结果中的 `COMMENTS` 列包含 `analyzing` 时，表示该 DDL Job 正在执行统计信息收集。 + +## 重组已有索引的 DDL + +当 `tidb_stats_update_during_ddl` 设置为 `ON` 时，执行 [`MODIFY COLUMN`](/sql-statements/sql-statement-modify-column.md) 或 [`CHANGE COLUMN`](/sql-statements/sql-statement-change-column.md) 操作重组索引时，TiDB 也会在 Reorg 阶段结束后执行内嵌的 Analyze 命令。其机制与 `ADD INDEX` 相同： + +- 在索引可见前开始进行统计信息收集。 +- 若 Analyze 超时，[`MODIFY COLUMN`](/sql-statements/sql-statement-modify-column.md) 和 [`CHANGE COLUMN`](/sql-statements/sql-statement-change-column.md) 将不会同步等待 Analyze 完成，而是继续执行后续流程，使索引提前对用户可见。这意味着，该新索引的统计信息会在 Analyze 异步完成后更新。 + +示例： + +```sql +CREATE TABLE s (a VARCHAR(10), INDEX idx (a)); +Query OK, 0 rows affected (0.012 sec) + +INSERT INTO s VALUES (1), (2), (3); +Query OK, 3 rows affected (0.003 sec) +Records: 3 Duplicates: 0 Warnings: 0 + +SET @@tidb_stats_update_during_ddl = 1; +Query OK, 0 rows affected (0.001 sec) + +ALTER TABLE s MODIFY COLUMN a INT; +Query OK, 0 rows affected (0.056 sec) + +EXPLAIN SELECT * FROM s WHERE a > 1; +``` + +``` ++------------------------+---------+-----------+-----------------------+----------------------------------+ +| id | estRows | task | access object | operator info | ++------------------------+---------+-----------+-----------------------+----------------------------------+ +| IndexReader_7 | 2.00 | root | | index:IndexRangeScan_6 | +| └─IndexRangeScan_6 | 2.00 | cop[tikv] | table:s, index:idx(a) | range:(1,+inf], keep order:false | ++------------------------+---------+-----------+-----------------------+----------------------------------+ +2 rows in set (0.005 sec) +``` + +```sql +SHOW STATS_HISTOGRAMS WHERE table_name = "s"; +``` + +``` ++---------+------------+----------------+-------------+----------+---------------------+----------------+------------+--------------+-------------+-------------+-----------------+----------------+----------------+---------------+ +| Db_name | Table_name | Partition_name | Column_name | Is_index | Update_time | Distinct_count | Null_count | Avg_col_size | Correlation | Load_status | Total_mem_usage | Hist_mem_usage | Topn_mem_usage | Cms_mem_usage | ++---------+------------+----------------+-------------+----------+---------------------+----------------+------------+--------------+-------------+-------------+-----------------+----------------+----------------+---------------+ +| test | s | | a | 0 | 2025-10-30 20:10:18 | 3 | 0 | 2 | 1 | allLoaded | 158 | 0 | 158 | 0 | +| test | s | | a | 0 | 2025-10-30 20:10:18 | 3 | 0 | 1 | 1 | allLoaded | 155 | 0 | 155 | 0 | +| test | s | | idx | 1 | 2025-10-30 20:10:18 | 3 | 0 | 0 | 0 | allLoaded | 158 | 0 | 158 | 0 | +| test | s | | idx | 1 | 2025-10-30 20:10:18 | 3 | 0 | 0 | 0 | allLoaded | 155 | 0 | 155 | 0 | ++---------+------------+----------------+-------------+----------+---------------------+----------------+------------+--------------+-------------+-------------+-----------------+----------------+----------------+---------------+ +4 rows in set (0.008 sec) +``` + +```sql +ADMIN SHOW DDL JOBS 1; +``` + +``` ++--------+---------+------------------+---------------+----------------------+-----------+----------+-----------+----------------------------+----------------------------+----------------------------+---------+-----------------------------+ +| JOB_ID | DB_NAME | TABLE_NAME | JOB_TYPE | SCHEMA_STATE | SCHEMA_ID | TABLE_ID | ROW_COUNT | CREATE_TIME | START_TIME | END_TIME | STATE | COMMENTS | ++--------+---------+------------------+---------------+----------------------+-----------+----------+-----------+----------------------------+----------------------------+----------------------------+---------+-----------------------------+ +| 153 | test | s | modify column | write reorganization | 2 | 148 | 12582912 | 2025-10-29 00:26:49.240000 | 2025-10-29 00:26:49.244000 | NULL | running | analyzing | ++--------+---------+------------------+---------------+----------------------+-----------+----------+-----------+----------------------------+----------------------------+----------------------------+---------+-----------------------------+ +1 rows in set (0.001 sec) +``` + +从 `MODIFY COLUMN` 示例来看，当 `tidb_stats_update_during_ddl` 设置为 `ON` 时，在 `MODIFY COLUMN` DDL 执行结束后，可以看到其之后运行的 `EXPLAIN` 查询中，相关索引 `idx` 的统计信息已经被自动收集并加载到内存中（可通过 `SHOW STATS_HISTOGRAMS` 语句的输出结果得到验证），因此优化器能够立即在范围扫描（Range Scan）中使用这些统计信息。如果索引的创建或重组以及 Analyze 过程耗时较长，可以通过 `ADMIN SHOW DDL JOBS` 查看 DDL Job 的状态。当输出结果中的 `COMMENTS` 列包含 `analyzing` 时，表示该 DDL Job 正在执行统计信息收集。 diff --git a/deploy-monitoring-services.md b/deploy-monitoring-services.md index ee5505148b98..bfa5acbb14ff 100644 --- a/deploy-monitoring-services.md +++ b/deploy-monitoring-services.md @@ -1,12 +1,11 @@ --- title: 集群监控部署 -aliases: ['/docs-cn/dev/deploy-monitoring-services/','/docs-cn/dev/monitor-a-tidb-cluster/','/docs-cn/dev/how-to/monitor/monitor-a-cluster/'] summary: 本文适用于手动部署 TiDB 监控报警系统的用户。假设 TiDB 的拓扑结构如下：Node1 主机 IP 为 192.168.199.113，服务包括 PD1、TiDB、node_export、Prometheus、Grafana；Node2 主机 IP 为 192.168.199.114，服务包括 PD2、node_export；Node3 主机 IP 为 192.168.199.115，服务包括 PD3、node_export；Node4 主机 IP 为 192.168.199.116，服务包括 TiKV1、node_export；Node5 主机 IP 为 192.168.199.117，服务包括 TiKV2、node_export；Node6 主机 IP 为 192.168.199.118，服务包括 TiKV3、node_export。具体部署步骤包括下载二进制包、启动 node_exporter 服务、启动 Prometheus 服务、启动 Grafana 服务、配置 Grafana 数据源和导入 Grafana 面板。可查看 TiDB Server、PD Server 和 TiKV Server 的监控信息。 --- # TiDB 集群监控部署 -本文档适用于希望手动部署 TiDB 监控报警系统的用户。TiUP 部署方式，会同时自动部署监控报警系统，无需手动部署。 +本文档适用于希望手动部署 TiDB 监控报警系统的用户。TiUP 部署方式，会同时自动部署监控报警系统，无需手动部署。[TiDB Dashboard](/dashboard/dashboard-intro.md) 内置于 TiDB 的 PD 组件中，无需独立部署。 ## 部署 Prometheus 和 Grafana @@ -29,8 +28,8 @@ summary: 本文适用于手动部署 TiDB 监控报警系统的用户。假设 T ```bash wget https://github.com/prometheus/prometheus/releases/download/v2.49.1/prometheus-2.49.1.linux-amd64.tar.gz -wget https://download.pingcap.org/node_exporter-v1.3.1-linux-amd64.tar.gz -wget https://download.pingcap.org/grafana-7.5.17.linux-amd64.tar.gz +wget https://download.pingcap.com/node_exporter-v1.3.1-linux-amd64.tar.gz +wget https://download.pingcap.com/grafana-7.5.17.linux-amd64.tar.gz ``` 解压二进制包： @@ -121,12 +120,12 @@ scrape_configs: 如需开启 TiDB、PD 和 TiKV 等组件的报警规则，请单独下载组件对应的报警规则文件，并在 Prometheus 的配置文件中添加报警规则文件的配置。 -- TiDB：[`tidb.rules.yml`](https://github.com/pingcap/tidb/blob/master/pkg/metrics/alertmanager/tidb.rules.yml) -- PD：[`pd.rules.yml`](https://github.com/tikv/pd/blob/master/metrics/alertmanager/pd.rules.yml) -- TiKV：[`tikv.rules.yml`](https://github.com/tikv/tikv/blob/master/metrics/alertmanager/tikv.rules.yml) -- TiFlash：[`tiflash.rules.yml`](https://github.com/pingcap/tiflash/blob/master/metrics/alertmanager/tiflash.rules.yml) -- TiCDC：[`ticdc.rules.yml`](https://github.com/pingcap/tiflow/blob/master/metrics/alertmanager/ticdc.rules.yml) -- TiDB Lightning：[`lightning.rules.yml`](https://github.com/pingcap/tidb/blob/master/br/metrics/alertmanager/lightning.rules.yml) +- TiDB：[`tidb.rules.yml`](https://github.com/pingcap/tidb/blob/release-8.5/pkg/metrics/alertmanager/tidb.rules.yml) +- PD：[`pd.rules.yml`](https://github.com/tikv/pd/blob/release-8.5/metrics/alertmanager/pd.rules.yml) +- TiKV：[`tikv.rules.yml`](https://github.com/tikv/tikv/blob/release-8.5/metrics/alertmanager/tikv.rules.yml) +- TiFlash：[`tiflash.rules.yml`](https://github.com/pingcap/tiflash/blob/release-8.5/metrics/alertmanager/tiflash.rules.yml) +- TiCDC：[`ticdc.rules.yml`](https://github.com/pingcap/tiflow/blob/release-8.5/metrics/alertmanager/ticdc.rules.yml) +- TiDB Lightning：[`lightning.rules.yml`](https://github.com/pingcap/tidb/blob/release-8.5/br/metrics/alertmanager/lightning.rules.yml) ```ini rule_files: @@ -251,7 +250,7 @@ url = https://grafana.net 2. 在侧边栏菜单中，依次点击 **Dashboards** > **Import** 打开 **Import Dashboard** 窗口。 -3. 点击 **Upload .json File** 上传对应的 JSON 文件（从 [pingcap/tidb](https://github.com/pingcap/tidb/tree/master/pkg/metrics/grafana)、[tikv/tikv](https://github.com/tikv/tikv/tree/master/metrics/grafana) 和 [tikv/pd](https://github.com/tikv/pd/tree/master/metrics/grafana) 下载 TiDB Grafana 配置文件）。 +3. 点击 **Upload .json File** 上传对应的 JSON 文件（从 [pingcap/tidb](https://github.com/pingcap/tidb/tree/release-8.5/pkg/metrics/grafana)、[tikv/tikv](https://github.com/tikv/tikv/tree/release-8.5/metrics/grafana) 和 [tikv/pd](https://github.com/tikv/pd/tree/release-8.5/metrics/grafana) 下载 TiDB Grafana 配置文件）。 > **注意：** > diff --git a/develop/_index.md b/develop/_index.md new file mode 100644 index 000000000000..5b3fd2597f92 --- /dev/null +++ b/develop/_index.md @@ -0,0 +1,183 @@ +--- +title: 应用开发概览 +summary: TiDB Cloud 和 TiDB 的开发者指南概览。 +aliases: ['zh/tidbcloud/dev-guide-overview/','zh/tidb/dev/dev-guide-overview/','zh/stable/dev/dev-guide-overview/'] +--- + +# 应用开发概览 + +[TiDB](https://github.com/pingcap/tidb) 是一款开源的分布式 SQL 数据库，同时支持在线事务处理与在线分析处理 (Hybrid Transactional and Analytical Processing, HTAP)。 + +本指南旨在帮助应用开发者快速掌握如何连接 TiDB、设计数据库、读写数据，并基于 TiDB 构建可靠且高性能的应用程序。 + +> **注意：** +> +> 本指南是为应用程序开发者所编写的，如果你对 TiDB 的内部原理感兴趣，或希望参与到 TiDB 的开发中来，那么可前往阅读 [TiDB Kernel Development Guide](https://pingcap.github.io/tidb-dev-guide/) 来获取更多 TiDB 的相关信息。 + +此外，你还可以通过视频的形式学习免费的 [TiDB SQL 开发在线课程](https://pingkai.cn/learn)。 + +## 按语言和框架分类 + +你可以使用自己熟悉的编程语言，结合以下包含示例代码的文档来构建你的应用程序。 + + + + +在边缘环境中通过 HTTPS 连接到 TiDB（仅适用于 TiDB Cloud）。 + + + + +通过 mysql2 将 Next.js 连接到 TiDB。 + + + + +使用 Prisma ORM 连接 TiDB。 + + + + +使用 TypeORM 连接 TiDB。 + + + + +使用 Sequelize ORM 连接 TiDB。 + + + + +通过 mysql.js 模块将 Node.js 连接到 TiDB。 + + + + +通过 node-mysql2 模块将 Node.js 连接到 TiDB。 + + + + +在 AWS Lambda 函数中使用 mysql2 连接 TiDB。 + + + + + + + +通过 django-tidb 将 Django 应用连接 TiDB。 + + + + +使用 MySQL Connector/Python 连接 TiDB。 + + + + +使用 PyMySQL 包连接 TiDB。 + + + + +使用 mysqlclient 包连接 TiDB。 + + + + +使用 SQLAlchemy ORM 连接 TiDB。 + + + + +使用 Peewee ORM 连接 TiDB。 + + + + + + + +使用 JDBC（MySQL Connector/J）连接 TiDB。 + + + + +使用 MyBatis ORM 连接 TiDB。 + + + + +使用 Hibernate ORM 连接 TiDB。 + + + + +使用 Spring Boot 连接 TiDB。 + + + + + + + +使用 Go-MySQL-Driver 连接 TiDB。 + + + + +使用 GORM 连接 TiDB。 + + + + + + + +使用 Rails 框架和 ActiveRecord ORM 连接 TiDB。 + + + + +使用 mysql2 驱动连接 TiDB。 + + + + +除了上述指南之外，PingCAP 还与社区合作，支持[第三方 MySQL 驱动、ORM 以及工具](/develop/dev-guide-third-party-support.md)。 + +## 使用 MySQL 客户端软件 + +TiDB 与 MySQL 高度兼容，你可以使用许多熟悉的 MySQL 客户端工具来连接 TiDB 并管理数据库。对于 TiDB Cloud 用户，你还可以使用 [TiDB Cloud CLI](https://docs.pingcap.com/tidbcloud/get-started-with-cli) 来连接和管理数据库。 + + + + +使用 MySQL Workbench 连接并管理 TiDB 数据库。 + + + + +使用 VS Code 中的 SQLTools 扩展连接并管理 TiDB 数据库。 + + + + +使用 DBeaver 连接并管理 TiDB 数据库。 + + + + +使用 JetBrains 的 DataGrip 连接并管理 TiDB 数据库。 + + + + +## 其他资源 + +了解关于应用开发的更多信息。 + +- 参考 [TiDB 数据库模式设计](/develop/dev-guide-schema-design-overview.md) 来设计数据结构、与数据交互、进行性能优化以及故障排查。 +- 参加 [TiDB 开发者课程](https://pingkai.cn/learn)。 +- 探索 TiDB Cloud 支持的常见[服务集成](https://docs.pingcap.com/tidbcloud/integrate-tidbcloud-with-airbyte)。 \ No newline at end of file diff --git a/develop/dev-guide-aws-appflow-integration.md b/develop/dev-guide-aws-appflow-integration.md new file mode 100644 index 000000000000..ab70c5035142 --- /dev/null +++ b/develop/dev-guide-aws-appflow-integration.md @@ -0,0 +1,255 @@ +--- +title: TiDB 与 Amazon AppFlow 集成指南 +summary: 了解如何将 TiDB 集成到 Amazon AppFlow。 +aliases: ['/zh/tidbcloud/dev-guide-aws-appflow-integration/'] +--- + +# TiDB 与 Amazon AppFlow 集成指南 + +[Amazon AppFlow](https://aws.amazon.com/appflow/) 是一项全托管的 API 集成服务，可用于将软件即服务 (SaaS) 应用与 AWS 服务连接，并安全地传输数据。通过 Amazon AppFlow，你可以在 TiDB 与多种数据提供方之间导入和导出数据，例如 Salesforce、Amazon S3、LinkedIn 和 GitHub。更多信息请参见 AWS 文档中的[支持的源和目标应用](https://docs.aws.amazon.com/appflow/latest/userguide/app-specific.html)。 + +本文档介绍了如何将 TiDB 与 Amazon AppFlow 进行集成，并以集成 TiDB Cloud Starter 集群为例进行说明。 + +如果你还没有 TiDB 集群，可以创建一个 [TiDB Cloud Starter](https://tidbcloud.com/console/clusters) 集群，该集群免费，且大约 30 秒即可创建完成。 + +## 前提条件 + +- [Git](https://git-scm.com/) +- [JDK](https://openjdk.org/install/) 11 或更高版本 +- [Maven](https://maven.apache.org/install.html) 3.8 或更高版本 +- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) 版本 2 +- [AWS Serverless Application Model Command Line Interface (AWS SAM CLI)](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) 1.58.0 或更高版本 +- 一个满足以下要求的 AWS [Identity and Access Management (IAM) 用户](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html)： + + - 该用户可以通过 [access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) 访问 AWS。 + - 该用户拥有以下权限： + + - `AWSCertificateManagerFullAccess`：用于读写 [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/)。 + - `AWSCloudFormationFullAccess`：SAM CLI 使用 [AWS CloudFormation](https://aws.amazon.com/cloudformation/) 来声明 AWS 资源。 + - `AmazonS3FullAccess`：AWS CloudFormation 使用 [Amazon S3](https://aws.amazon.com/s3/?nc2=h_ql_prod_fs_s3) 进行发布。 + - `AWSLambda_FullAccess`：目前，[AWS Lambda](https://aws.amazon.com/lambda/?nc2=h_ql_prod_fs_lbd) 是为 Amazon AppFlow 实现新连接器的唯一方式。 + - `IAMFullAccess`：SAM CLI 需要为连接器创建 `ConnectorFunctionRole`。 + +- 一个 [SalesForce](https://developer.salesforce.com) 账号。 + +## 第 1 步：注册 TiDB 连接器 + +### 克隆代码 + +克隆 TiDB 与 Amazon AppFlow 的[集成示例代码仓库](https://github.com/pingcap-inc/tidb-appflow-integration)： + +```bash +git clone https://github.com/pingcap-inc/tidb-appflow-integration +``` + +### 构建并上传 Lambda + +1. 构建包： + + ```bash + cd tidb-appflow-integration + mvn clean package + ``` + +2. （可选）如果你还没有配置 AWS access key ID 和 secret access key，请进行配置。 + + ```bash + aws configure + ``` + +3. 将你的 JAR 包上传为 Lambda： + + ```bash + sam deploy --guided + ``` + + > **注意：** + > + > - `--guided` 选项会通过提示引导你完成部署。你的输入会被存储在配置文件中，默认是 `samconfig.toml`。 + > - `stack_name` 用于指定正在部署的 AWS Lambda 的名称。 + > - 引导流程默认使用 AWS 作为 TiDB Cloud Starter 的云服务商。如果你要将 Amazon S3 作为源或目标，需要将 AWS Lambda 的 `region` 设置为与 Amazon S3 相同。 + > - 如果你之前已经运行过 `sam deploy --guided`，可以直接运行 `sam deploy`，SAM CLI 会使用 `samconfig.toml` 配置文件简化交互。 + + 如果你看到类似如下输出，说明 Lambda 部署成功。 + + ``` + Successfully created/updated stack - in + ``` + +4. 进入 [AWS Lambda 控制台](https://console.aws.amazon.com/lambda/home)，你可以看到刚刚上传的 Lambda。注意需要在窗口右上角选择正确的 region。 + + ![lambda dashboard](/media/develop/aws-appflow-step-lambda-dashboard.png) + +### 使用 Lambda 注册连接器 + +1. 在 [AWS 管理控制台](https://console.aws.amazon.com) 中，前往 [Amazon AppFlow > Connectors](https://console.aws.amazon.com/appflow/home#/gallery)，然后点击 **Register new connector**。 + + ![register connector](/media/develop/aws-appflow-step-register-connector.png) + +2. 在 **Register a new connector** 对话框中，选择你上传的 Lambda 函数，并使用连接器名称指定 connector label。 + + ![register connector dialog](/media/develop/aws-appflow-step-register-connector-dialog.png) + +3. 点击 **Register**。此时，TiDB 连接器注册成功。 + +## 第 2 步：创建 flow + +前往 [Amazon AppFlow > Flows](https://console.aws.amazon.com/appflow/home#/list)，点击 **Create flow**。 + +![create flow](/media/develop/aws-appflow-step-create-flow.png) + +### 设置 flow 名称 + +输入 flow 名称，然后点击 **Next**。 + +![name flow](/media/develop/aws-appflow-step-name-flow.png) + +### 设置源表和目标表 + +选择 **Source details** 和 **Destination details**。TiDB 连接器可以在这两者中使用。 + +1. 选择源名称。本文档以 **Salesforce** 作为示例源。 + + ![salesforce source](/media/develop/aws-appflow-step-salesforce-source.png) + + 注册 Salesforce 后，Salesforce 会在你的平台中添加一些示例数据。接下来的步骤将以 **Account** 对象作为示例源对象。 + + ![salesforce data](/media/develop/aws-appflow-step-salesforce-data.png) + +2. 点击 **Connect**。 + + 1. 在 **Connect to Salesforce** 对话框中，指定该连接的名称，然后点击 **Continue**。 + + ![connect to salesforce](/media/develop/aws-appflow-step-connect-to-salesforce.png) + + 2. 点击 **Allow**，以确认 AWS 可以读取你的 Salesforce 数据。 + + ![allow salesforce](/media/develop/aws-appflow-step-allow-salesforce.png) + + > **注意：** + > + > 如果你的公司已经在使用 Salesforce 专业版 (Professional Edition)，默认情况下未启用 REST API。你可能需要注册一个新的 Salesforce 开发者版 (Developer Edition) 才能使用 REST API。更多信息请参考 [Salesforce 论坛相关话题](https://developer.salesforce.com/forums/?id=906F0000000D9Y2IAK)。 + +3. 在 **Destination details** 区域，选择 **TiDB-Connector** 作为目标端。此时会显示 **Connect** 按钮。 + + ![tidb dest](/media/develop/aws-appflow-step-tidb-dest.png) + +4. 在点击 **Connect** 之前，你需要在 TiDB 中为 Salesforce 的 **Account** 对象创建一个 `sf_account` 表。注意该表结构与 [Tutorial of Amazon AppFlow](https://docs.aws.amazon.com/appflow/latest/userguide/flow-tutorial-set-up-source.html) 中的示例数据不同。 + + ```sql + CREATE TABLE `sf_account` ( + `id` varchar(255) NOT NULL, + `name` varchar(150) NOT NULL DEFAULT '', + `type` varchar(150) NOT NULL DEFAULT '', + `billing_state` varchar(255) NOT NULL DEFAULT '', + `rating` varchar(255) NOT NULL DEFAULT '', + `industry` varchar(255) NOT NULL DEFAULT '', + PRIMARY KEY (`id`) + ); + ``` + +5. 创建好 `sf_account` 表后，点击 **Connect**。会弹出连接对话框。 +6. 在 **Connect to TiDB-Connector** 对话框中，输入 TiDB 集群的连接属性。如果你使用的是 TiDB Cloud Starter 集群，需要将 **TLS** 选项设置为 `Yes`，这样 TiDB 连接器会使用 TLS 连接。然后点击 **Connect**。 + + ![tidb connection message](/media/develop/aws-appflow-step-tidb-connection-message.png) + +7. 现在你可以获取到在连接中指定的数据库里的所有表。从下拉列表中选择 **sf_account** 表。 + + ![database](/media/develop/aws-appflow-step-database.png) + + 下图展示了将 Salesforce **Account** 对象的数据传输到 TiDB 中 `sf_account` 表的配置： + + ![complete flow](/media/develop/aws-appflow-step-complete-flow.png) + +8. 在 **Error handling** 区域，选择 **Stop the current flow run**。在 **Flow trigger** 区域，选择 **Run on demand** 触发类型，表示你需要手动运行 flow。然后点击 **Next**。 + + ![complete step1](/media/develop/aws-appflow-step-complete-step1.png) + +### 设置映射规则 + +将 Salesforce 中 **Account** 对象的字段映射到 TiDB 的 `sf_account` 表，然后点击 **Next**。 + +- `sf_account` 表是新建的，当前为空。 + + ```sql + test> SELECT * FROM sf_account; + +----+------+------+---------------+--------+----------+ + | id | name | type | billing_state | rating | industry | + +----+------+------+---------------+--------+----------+ + +----+------+------+---------------+--------+----------+ + ``` + +- 设置映射规则时，你可以在左侧选择源字段名，在右侧选择目标字段名。然后点击 **Map fields**，即可设置一条规则。 + + ![add mapping rule](/media/develop/aws-appflow-step-add-mapping-rule.png) + +- 本文示例需要以下映射规则（源字段名 -> 目标字段名）： + + - Account ID -> id + - Account Name -> name + - Account Type -> type + - Billing State/Province -> billing_state + - Account Rating -> rating + - Industry -> industry + + ![mapping a rule](/media/develop/aws-appflow-step-mapping-a-rule.png) + + ![show all mapping rules](/media/develop/aws-appflow-step-show-all-mapping-rules.png) + +### （可选）设置过滤器 + +如果你想为数据字段添加一些过滤条件，可以在此处设置。否则，跳过此步骤，并点击 **Next**。 + +![filters](/media/develop/aws-appflow-step-filters.png) + +### 确认并创建 flow + +确认即将创建的 flow 的信息。如果一切无误，点击 **Create flow**。 + +![review](/media/develop/aws-appflow-step-review.png) + +## 第 3 步：运行 flow + +在新建 flow 的页面右上角，点击 **Run flow**。 + +![run flow](/media/develop/aws-appflow-step-run-flow.png) + +下图展示了 flow 成功运行的示例： + +![run success](/media/develop/aws-appflow-step-run-success.png) + +查询 `sf_account` 表，你可以看到 Salesforce **Account** 对象中的记录已经写入该表： + +```sql +test> SELECT * FROM sf_account; ++--------------------+-------------------------------------+--------------------+---------------+--------+----------------+ +| id | name | type | billing_state | rating | industry | ++--------------------+-------------------------------------+--------------------+---------------+--------+----------------+ +| 001Do000003EDTlIAO | Sample Account for Entitlements | null | null | null | null | +| 001Do000003EDTZIA4 | Edge Communications | Customer - Direct | TX | Hot | Electronics | +| 001Do000003EDTaIAO | Burlington Textiles Corp of America | Customer - Direct | NC | Warm | Apparel | +| 001Do000003EDTbIAO | Pyramid Construction Inc. | Customer - Channel | null | null | Construction | +| 001Do000003EDTcIAO | Dickenson plc | Customer - Channel | KS | null | Consulting | +| 001Do000003EDTdIAO | Grand Hotels & Resorts Ltd | Customer - Direct | IL | Warm | Hospitality | +| 001Do000003EDTeIAO | United Oil & Gas Corp. | Customer - Direct | NY | Hot | Energy | +| 001Do000003EDTfIAO | Express Logistics and Transport | Customer - Channel | OR | Cold | Transportation | +| 001Do000003EDTgIAO | University of Arizona | Customer - Direct | AZ | Warm | Education | +| 001Do000003EDThIAO | United Oil & Gas, UK | Customer - Direct | UK | null | Energy | +| 001Do000003EDTiIAO | United Oil & Gas, Singapore | Customer - Direct | Singapore | null | Energy | +| 001Do000003EDTjIAO | GenePoint | Customer - Channel | CA | Cold | Biotechnology | +| 001Do000003EDTkIAO | sForce | null | CA | null | null | ++--------------------+-------------------------------------+--------------------+---------------+--------+----------------+ +``` + +## 注意事项 + +- 如果遇到问题，可以在 AWS 管理控制台的 [CloudWatch](https://console.aws.amazon.com/cloudwatch/home) 页面查看日志。 +- 本文档中的步骤基于 [Building custom connectors using the Amazon AppFlow Custom Connector SDK](https://aws.amazon.com/blogs/compute/building-custom-connectors-using-the-amazon-appflow-custom-connector-sdk/)。 +- [TiDB Cloud Starter](https://docs.pingcap.com/tidbcloud/select-cluster-tier#starter) **不是**生产环境。 +- 为避免篇幅过长，本文档示例仅展示了 `Insert` 策略，`Update` 和 `Upsert` 策略也已测试并可用。 + +## 需要帮助？ + +- 在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [提交 TiDB 工单](/support.md) diff --git a/develop/dev-guide-bookshop-schema-design.md b/develop/dev-guide-bookshop-schema-design.md index 4f4001915cbf..da1b94a64a90 100644 --- a/develop/dev-guide-bookshop-schema-design.md +++ b/develop/dev-guide-bookshop-schema-design.md @@ -1,7 +1,7 @@ --- title: Bookshop 应用 summary: Bookshop 应用设计、数据导入、连接数据库等操作。 -aliases: ['/zh/tidb/dev/bookshop-schema-design'] +aliases: ['/zh/tidb/dev/bookshop-schema-design','/zh/tidb/stable/dev-guide-bookshop-schema-design/','/zh/tidb/dev/dev-guide-bookshop-schema-design/','/zh/tidbcloud/dev-guide-bookshop-schema-design/'] --- # Bookshop 应用 @@ -12,9 +12,12 @@ Bookshop 是一个虚拟的在线书店应用，你可以在 Bookshop 当中便 ## 导入表结构和数据 -你可以[通过 TiUP](#方法一通过-tiup-demo-命令行) 或[通过 TiDB Cloud Import](#方法二通过-tidb-cloud-import-功能) 两种方式导入 Bookshop 应用的表结构和数据。 +选择以下一种方式导入 Bookshop 应用的表结构和数据： -### 方法一：通过 `tiup demo` 命令行 +- [本地部署的 TiDB：通过 `tiup demo` 命令行](#本地部署的-tidb通过-tiup-demo-命令行) +- [TiDB Cloud：通过 Import 功能](#tidb-cloud通过-import-功能) + +### 本地部署的 TiDB：通过 `tiup demo` 命令行 如果你使用 [TiUP](/tiup/tiup-reference.md#tiup-命令概览) 部署 TiDB 集群或者你可以直接连接到你的 TiDB 服务器，你可以通过如下命令快速生成并导入 Bookshop 应用的示例数据： @@ -62,7 +65,7 @@ tiup demo bookshop prepare --users=200000 --books=500000 --authors=100000 --rati 通过 `--drop-tables` 参数你可以删除原有的表结构，更多的参数说明你可以通过命令 `tiup demo bookshop --help` 进行了解。 -### 方法二：通过 TiDB Cloud Import 功能 +### TiDB Cloud：通过 Import 功能 1. 打开目标集群的 **Import** 页面。 @@ -74,13 +77,11 @@ tiup demo bookshop prepare --users=200000 --books=500000 --authors=100000 --rati 2. 点击目标集群的名称，进入集群的 **Overview** 页面，然后在左侧导航栏中点击 **Import**。 -2. 选择 **Import data from S3**。 - - 如果这是你第一次使用 TiDB Cloud 的导入功能，选择 **Import From Amazon S3**。 +2. 选择 **Import data from Cloud Storage**，然后点击 **Amazon S3**. 3. 在 **Import Data from Amazon S3** 页面，配置以下源数据信息： - - **Import File Count**：选择 **Multiple files** + - **Import File Count**：对于 {{{ .starter }}}，选择 **Multiple files**。TiDB Cloud Dedicated 中没有该字段。 - **Included Schema Files**：选择 **Yes** - **Data Format**：选择 **SQL** - **Folder URI**：输入 `s3://developer.pingcap.com/bookshop/` diff --git a/develop/dev-guide-build-cluster-in-cloud.md b/develop/dev-guide-build-cluster-in-cloud.md index d0fb55ba942a..11971a81f4d6 100644 --- a/develop/dev-guide-build-cluster-in-cloud.md +++ b/develop/dev-guide-build-cluster-in-cloud.md @@ -1,30 +1,30 @@ --- -title: 使用 TiDB Cloud Serverless 构建 TiDB 集群 -summary: 使用 TiDB Cloud Serverless 构建 TiDB 集群，并连接 TiDB Cloud Serverless 集群。 -aliases: ['/zh/tidb/dev/build-cluster-in-cloud'] +title: 创建 {{{ .starter }}} 集群 +summary: 使用 {{{ .starter }}} 构建 TiDB 集群，并连接 {{{ .starter }}} 集群。 +aliases: ['/zh/tidb/dev/build-cluster-in-cloud','/zh/tidb/stable/dev-guide-build-cluster-in-cloud/','/zh/tidb/dev/dev-guide-build-cluster-in-cloud/','/zh/tidbcloud/dev-guide-build-cluster-in-cloud/'] --- -# 使用 TiDB Cloud Serverless 构建 TiDB 集群 +# 创建 {{{ .starter }}} 集群 -本文将介绍如何以最快的方式开始使用 TiDB。你将创建并启动一个 [TiDB Cloud Serverless](https://www.pingcap.com/tidb-serverless/) 集群，使用 TiDB SQL 客户端，插入数据。随后将从示例程序读取出数据。 +本文将介绍如何以最快的方式开始使用 TiDB。你将创建并启动一个 [{{{ .starter }}}](https://www.pingcap.com/tidb-cloud-starter/) 集群，使用 TiDB SQL 客户端，插入数据。随后将从示例程序读取出数据。 若你需要在本地计算机上启动 TiDB，请参阅[本地启动 TiDB](/quick-start-with-tidb.md)。 -## 第 1 步：创建 TiDB Cloud Serverless 集群 +## 第 1 步：创建 {{{ .starter }}} 集群 {#step-1-create-a-tidb-cloud-cluster} 1. 如果你还未拥有 TiDB Cloud 账号，请先在此[注册](https://tidbcloud.com/free-trial)。 2. 使用你的 TiDB Cloud 账号[登录](https://tidbcloud.com/)。 登录后，默认进入 [**Clusters**](https://tidbcloud.com/console/clusters) 页面。 -3. 对于新注册的用户，TiDB Cloud 会自动为你创建一个 TiDB Cloud Serverless 集群 `Cluster0`。你可以使用这个默认集群进行后续操作，也可以自行创建一个新的 TiDB Cloud Serverless 集群。 +3. 对于新注册的用户，TiDB Cloud 会自动为你创建一个 {{{ .starter }}} 集群 `Cluster0`。你可以使用这个默认集群进行后续操作，也可以自行创建一个新的 {{{ .starter }}} 集群。 - 如果你想创建一个新的 TiDB Cloud Serverless 集群，请进行以下操作： + 如果你想创建一个新的 {{{ .starter }}} 集群，请进行以下操作： 1. 点击 **Create Cluster**。 - 2. **Create Cluster** 页面默认选择 **Serverless**。你可以根据需要修改集群名称、选择可用区，然后点击 **Create**。你的 TiDB Cloud Serverless 集群将于 30 秒后创建完毕。 + 2. **Create Cluster** 页面默认选择 **Starter**。你可以根据需要修改集群名称、选择可用区，然后点击 **Create**。你的 {{{ .starter }}} 集群将于 30 秒后创建完毕。 4. 点击目标集群名称，进入集群概览页面，然后点击右上角的 **Connect** 按钮，弹出连接对话框。 @@ -34,7 +34,7 @@ aliases: ['/zh/tidb/dev/build-cluster-in-cloud'] > **注意：** > - > 在连接到 [TiDB Cloud Serverless](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) 集群时，你需要给用户名加上前缀并使用单引号包裹用户名。你可以在 [TiDB Cloud Serverless 用户名前缀](https://docs.pingcap.com/tidbcloud/select-cluster-tier#user-name-prefix) 中获得更多信息。 + > 在连接到 [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#starter) 集群时，你需要给用户名加上前缀并使用单引号包裹用户名。你可以在 [{{{ .starter }}} 用户名前缀](https://docs.pingcap.com/tidbcloud/select-cluster-tier#user-name-prefix)中获得更多信息。 ## 第 2 步：连接到集群 @@ -117,8 +117,8 @@ aliases: ['/zh/tidb/dev/build-cluster-in-cloud'] > **注意：** > -> - 在连接 TiDB Cloud Serverless 集群时，[必须使用 TLS 连接](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-tier-clusters)。 -> - 如果你在连接时遇到问题，可阅读 [TiDB Cloud Serverless 集群安全连接](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-tier-clusters) 来获得更多信息。 +> - 在连接 {{{ .starter }}} 集群时，[必须使用 TLS 连接](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-tier-clusters)。 +> - 如果你在连接时遇到问题，可阅读 [{{{ .starter }}} 集群安全连接](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-tier-clusters)来获得更多信息。 3. 填写密码，完成登录。 diff --git a/develop/dev-guide-choose-driver-or-orm.md b/develop/dev-guide-choose-driver-or-orm.md index 83d11b005670..ecbebe47aa1e 100644 --- a/develop/dev-guide-choose-driver-or-orm.md +++ b/develop/dev-guide-choose-driver-or-orm.md @@ -1,7 +1,7 @@ --- title: 选择驱动或 ORM 框架 summary: 选择驱动或 ORM 框架连接 TiDB。 -aliases: ['/zh/tidb/dev/choose-driver-or-orm'] +aliases: ['/zh/tidb/dev/choose-driver-or-orm','/zh/tidb/stable/dev-guide-choose-driver-or-orm/','/zh/tidb/dev/dev-guide-choose-driver-or-orm/','/zh/tidbcloud/dev-guide-choose-driver-or-orm/'] --- # 选择驱动或 ORM 框架 @@ -51,7 +51,7 @@ TiDB 兼容 MySQL 的协议，但存在部分与 MySQL 不兼容或有差异的 io.github.lastincisor mysql-connector-java - 8.0.29-tidb-1.0.0 + 8.0.29-tidb-1.0.2 ``` @@ -61,7 +61,7 @@ TiDB 兼容 MySQL 的协议，但存在部分与 MySQL 不兼容或有差异的 io.github.lastincisor mysql-connector-java - 8.0.29-tidb-1.0.0 + 8.0.29-tidb-1.0.2 org.bouncycastle @@ -78,7 +78,7 @@ TiDB 兼容 MySQL 的协议，但存在部分与 MySQL 不兼容或有差异的 如果你使用的是 Gradle，请将以下内容添加到你的 `dependencies`： ```gradle -implementation group: 'io.github.lastincisor', name: 'mysql-connector-java', version: '8.0.29-tidb-1.0.0' +implementation group: 'io.github.lastincisor', name: 'mysql-connector-java', version: '8.0.29-tidb-1.0.2' implementation group: 'org.bouncycastle', name: 'bcprov-jdk15on', version: '1.67' implementation group: 'org.bouncycastle', name: 'bcpkix-jdk15on', version: '1.67' ``` @@ -185,7 +185,7 @@ implementation 'mysql:mysql-connector-java:8.0.33' io.github.lastincisor mysql-connector-java - 8.0.29-tidb-1.0.0 + 8.0.29-tidb-1.0.2 io.github.lastincisor @@ -197,7 +197,7 @@ implementation 'mysql:mysql-connector-java:8.0.33' 如果你使用的是 Gradle，请将以下内容添加到你的 `dependencies`： ```gradle -implementation group: 'io.github.lastincisor', name: 'mysql-connector-java', version: '8.0.29-tidb-1.0.0' +implementation group: 'io.github.lastincisor', name: 'mysql-connector-java', version: '8.0.29-tidb-1.0.2' implementation group: 'io.github.lastincisor', name: 'tidb-loadbalance', version: '0.0.5' ``` diff --git a/develop/dev-guide-client-connection-parameters.md b/develop/dev-guide-client-connection-parameters.md deleted file mode 100644 index c867cfb922ff..000000000000 --- a/develop/dev-guide-client-connection-parameters.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: 客户端连接参数 -summary: 介绍客户端连接参数。 -aliases: ['/zh/tidb/dev/client-connection-parameters'] ---- - -# 客户端连接参数 - - - -| 参数名称 | 描述 | 是否符合预期 | 验证版本 | -| :----------------------------: | :-------------------------------------------------------------------------------: | :----------: | :------: | -| --auto-rehash | Enable automatic rehashing | -| --auto-vertical-output | Enable automatic vertical result set display | -| --batch | Do not use history file | -| --binary-as-hex | Display binary values in hexadecimal notation | -| --binary-mode | Disable \r\n - to - \n translation and treatment of \0 as end-of-query | -| --bind-address | Use specified network interface to connect to MySQL Server | -| --character-sets-dir | Directory where character sets are installed | -| --column-names | Write column names in results | -| --column-type-info | Display result set metadata | -| --comments | Whether to retain or strip comments in statements sent to the server | -| --compress | Compress all information sent between client and server | -| --connect-expired-password | Indicate to server that client can handle expired-password sandbox mode | -| --connect-timeout | Number of seconds before connection timeout | -| --database | The database to use | -| --debug | Write debugging log; supported only if MySQL was built with debugging support | -| --debug-check | Print debugging information when program exits | -| --debug-info | Print debugging information, memory, and CPU statistics when program exits | -| --default-auth | Authentication plugin to use | -| --default-character-set | Specify default character set | -| --defaults-extra-file | Read named option file in addition to usual option files | -| --defaults-file | Read only named option file | -| --defaults-group-suffix | Option group suffix value | -| --delimiter | Set the statement delimiter | -| --enable-cleartext-plugin | Enable cleartext authentication plugin | -| --execute | Execute the statement and quit | -| --force | Continue even if an SQL error occurs | -| --get-server-public-key | Request RSA public key from server | -| --help | Display help message and exit | -| --histignore | Patterns specifying which statements to ignore for logging | -| --host | Host on which MySQL server is located | -| --html | Produce HTML output | -| --ignore-spaces | Ignore spaces after function names | -| --init-command | SQL statement to execute after connecting | -| --line-numbers | Write line numbers for errors | -| --local-infile | Enable or disable for LOCAL capability for LOAD DATA | -| --login-path | Read login path options from .mylogin.cnf | -| --max-allowed-packet | Maximum packet length to send to or receive from server | -| --max-join-size | The automatic limit for rows in a join when using --safe-updates | -| --named-commands | Enable named mysql commands | -| --net-buffer-length | Buffer size for TCP/IP and socket communication | -| --no-auto-rehash | Disable automatic rehashing | -| --no-beep | Do not beep when errors occur | -| --no-defaults | Read no option files | -| --one-database | Ignore statements except those for the default database named on the command line | -| --pager | Use the given command for paging query output | -| --password | Password to use when connecting to server | -| --pipe | Connect to server using named pipe (Windows only) | -| --plugin-dir | Directory where plugins are installed | -| --port | TCP/IP port number for connection | -| --print-defaults | Print default options | -| --prompt | Set the prompt to the specified format | -| --protocol | Transport protocol to use | -| --quick | Do not cache each query result | -| --raw | Write column values without escape conversion | -| --reconnect | If the connection to the server is lost, automatically try to reconnect | -| --safe-updates, --i-am-a-dummy | Allow only UPDATE and DELETE statements that specify key values | -| --secure-auth | Do not send passwords to server in old (pre-4.1) format | -| --select-limit | The automatic limit for SELECT statements when using --safe-updates | -| --server-public-key-path | Path name to file containing RSA public key | -| --shared-memory-base-name | Shared-memory name for shared-memory connections (Windows only) | -| --show-warnings | Show warnings after each statement if there are any | -| --sigint-ignore | Ignore SIGINT signals (typically the result of typing Control+C) | -| --silent | Silent mode | -| --skip-auto-rehash | Disable automatic rehashing | -| --skip-column-names | Do not write column names in results | -| --skip-line-numbers | Skip line numbers for errors | -| --skip-named-commands | Disable named mysql commands | -| --skip-pager | Disable paging | -| --skip-reconnect | Disable reconnecting | -| --socket | Unix socket file or Windows named pipe to use | -| --ssl | Enable connection encryption | -| --ssl-ca | File that contains list of trusted SSL Certificate Authorities | -| --ssl-capath | Directory that contains trusted SSL Certificate Authority certificate files | -| --ssl-cert | File that contains X.509 certificate | -| --ssl-cipher | Permissible ciphers for connection encryption | -| --ssl-crl | File that contains certificate revocation lists | -| --ssl-crlpath | Directory that contains certificate revocation-list files | -| --ssl-key | File that contains X.509 key | -| --ssl-mode | Desired security state of connection to server | -| --ssl-verify-server-cert | Verify host name against server certificate Common Name identity | -| --syslog | Log interactive statements to syslog | -| --table | Display output in tabular format | -| --tee | Append a copy of output to named file | -| --tls-version | Permissible TLS protocols for encrypted connections | -| --unbuffered | Flush the buffer after each query | -| --user | MySQL user name to use when connecting to server | -| --verbose | Verbose mode | -| --version | Display version information and exit | -| --vertical | Print query output rows vertically (one line per column value) | -| --wait | If the connection cannot be established, wait and retry instead of aborting | -| --xml | Produce XML output | diff --git a/develop/dev-guide-connect-to-tidb.md b/develop/dev-guide-connect-to-tidb.md index 0956ff06b7d6..7c345cb632bb 100644 --- a/develop/dev-guide-connect-to-tidb.md +++ b/develop/dev-guide-connect-to-tidb.md @@ -1,112 +1,26 @@ --- title: 连接到 TiDB -summary: 介绍连接到 TiDB 的方法。 -aliases: ['/zh/tidb/dev/connect-to-tidb'] +summary: 连接到 TiDB 的方式概览。 +aliases: ['/zh/tidb/stable/dev-guide-connect-to-tidb/','/zh/tidb/dev/dev-guide-connect-to-tidb/','/zh/tidb/dev/connect-to-tidb'] --- # 连接到 TiDB -**TiDB** 高度兼容 **MySQL** 协议，全量的客户端连接参数列表，请参阅 [MySQL Client Options](https://dev.mysql.com/doc/refman/8.0/en/mysql-command-options.html)。 +TiDB 高度兼容 MySQL 协议，这使得大多数客户端驱动程序和 ORM 框架可以像连接到 MySQL 一样地连接到 TiDB。 -TiDB 支持 [MySQL 客户端/服务器协议](https://dev.mysql.com/doc/dev/mysql-server/latest/PAGE_PROTOCOL.html)。这使得大多数客户端驱动程序和 ORM 框架可以像连接到 MySQL 一样地连接到 TiDB。 +- 如需手动执行 SQL（用于连接测试、调试或快速验证），可以通过 [MySQL CLI 工具](/develop/dev-guide-mysql-tools.md) 连接到 TiDB。 -## MySQL +- 如果希望通过图形界面工具进行连接，可参考以下常用 GUI 工具的相关文档： -你可以选择使用 MySQL Client 或 MySQL Shell 连接到 TiDB。 + - [MySQL Workbench](/develop/dev-guide-gui-mysql-workbench.md) + - [Navicat](/develop/dev-guide-gui-navicat.md) - +- 如需基于 TiDB 构建应用程序，可以根据所使用的编程语言和框架[选择合适的驱动或 ORM](/develop/dev-guide-choose-driver-or-orm.md)。 -
+- 如需从边缘环境通过 HTTP 连接到 {{{ .starter }}} 或 {{{ .essential }}} 集群，可以使用 [TiDB Cloud Serverless Driver](/develop/serverless-driver.md)。需要注意的是，Serverless Driver 目前处于 beta 阶段，仅适用于 {{{ .starter }}} 或 {{{ .essential }}} 集群。 -你可以使用 MySQL Client 作为 TiDB 的命令行工具连接到 TiDB。下面以基于 YUM 的 Linux 发行版为例，介绍如何安装 MySQL Client。 +## 需要帮助？ -```shell -sudo yum install mysql -``` - -安装完成后，你可以使用如下命令连接到 TiDB： - -```shell -mysql --host --port 4000 -u root -p --comments -``` - -
- -
- -你可以使用 MySQL Shell 作为 TiDB 的命令行工具连接到 TiDB。参考 [MySQL Shell 文档](https://dev.mysql.com/doc/mysql-shell/8.0/en/mysql-shell-install.html)进行安装。安装完成后，你可以使用如下命令连接到 TiDB： - -```shell -mysqlsh --sql mysql://root@:4000 -``` - -
- - - -## JDBC - -你可以使用 [JDBC](https://dev.mysql.com/doc/connector-j/en/) 驱动连接到 TiDB，这需要创建一个 `MysqlDataSource` 或 `MysqlConnectionPoolDataSource` 对象（它们都实现了 `DataSource` 接口），并使用 `setURL` 函数设置连接字符串。 - -例如： - -```java -MysqlDataSource mysqlDataSource = new MysqlDataSource(); -mysqlDataSource.setURL("jdbc:mysql://{host}:{port}/{database}?user={username}&password={password}"); -``` - -有关 JDBC 连接的更多信息，可参考 [JDBC 官方文档](https://dev.mysql.com/doc/connector-j/en/)。 - -**连接参数** - -| 参数名 | 描述 | -| :----------: | :------------------------------------------------------------------------------------------------: | -| `{username}` | 需要连接到 TiDB 集群的 [SQL 用户](/user-account-management.md) | -| `{password}` | 需要连接到 TiDB 集群的 SQL 用户的密码 | -| `{host}` | TiDB 节点运行的 [Host]() | -| `{port}` | TiDB 节点正在监听的端口 | -| `{database}` | (已经存在的)数据库的名称 | - -## Hibernate - -你可以使用 [Hibernate ORM](https://hibernate.org/orm/) 连接到 TiDB，请将 Hibernate 的配置中的 `hibernate.connection.url` 设置为合法的 TiDB 连接字符串。 - -例如，你的配置被写在 `hibernate.cfg.xml` 文件中，那么你的配置文件应该为： - -```xml - - - - - com.mysql.cj.jdbc.Driver - org.hibernate.dialect.TiDBDialect - jdbc:mysql://{host}:{port}/{database}?user={user}&password={password} - - -``` - -随后，使用代码读取配置文件，从而获得 `SessionFactory` 对象： - -```java -SessionFactory sessionFactory = new Configuration().configure("hibernate.cfg.xml").buildSessionFactory(); -``` - -这里有几个需要注意的点： - -1. 因为使用的配置文件 `hibernate.cfg.xml` 为 XML 格式，而 `&` 字符，在 XML 中属于特殊字符，因此，需将 `&` 更改为 `&`。即，连接字符串 `hibernate.connection.url` 由 `jdbc:mysql://{host}:{port}/{database}?user={user}&password={password}` 改为了 `jdbc:mysql://{host}:{port}/{database}?user={user}&password={password}`。 -2. 在你使用 Hibernate 时，建议使用 TiDB 方言，即 `hibernate.dialect` 设置为 `org.hibernate.dialect.TiDBDialect`。 -3. Hibernate 在版本 `6.0.0.Beta2` 及以上可支持 TiDB 方言，因此推荐使用 `6.0.0.Beta2` 及以上版本的 Hibernate。 - -更多有关 Hibernate 连接参数的信息，请参阅 [Hibernate 官方文档](https://hibernate.org/orm/documentation)。 - -**连接参数** - -| 参数名 | 描述 | -| :----------: | :------------------------------------------------------------------------------------------------: | -| `{username}` | 需要连接到 TiDB 集群的 [SQL 用户](/user-account-management.md) | -| `{password}` | 需要连接到 TiDB 集群的 SQL 用户的密码 | -| `{host}` | TiDB 节点运行的 [Host]() | -| `{port}` | TiDB 节点正在监听的端口 | -| `{database}` | (已经存在的)数据库的名称 | +- 在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [提交 TiDB 工单](/support.md) \ No newline at end of file diff --git a/develop/dev-guide-connection-parameters.md b/develop/dev-guide-connection-parameters.md index 5bed4a7c638f..0ca81187e6e1 100644 --- a/develop/dev-guide-connection-parameters.md +++ b/develop/dev-guide-connection-parameters.md @@ -1,13 +1,20 @@ --- -title: 连接池与连接参数 +title: 配置连接池与连接参数 summary: 针对开发者的 TiDB 连接池与连接参数的说明。 -aliases: ['/zh/tidb/dev/connection-parameters'] +aliases: ['/zh/tidb/dev/connection-parameters','/zh/tidb/stable/dev-guide-connection-parameters/','/zh/tidb/dev/dev-guide-connection-parameters/','/zh/tidbcloud/dev-guide-connection-parameters/'] --- -# 连接池与连接参数 +# 配置连接池与连接参数 -> - 连接池参数 - 连接数配置、探活配置两节摘自[开发 Java 应用使用 TiDB 的最佳实践 - 连接池](/best-practices/java-app-best-practices.md#连接池)。 -> - 连接参数摘自[开发 Java 应用使用 TiDB 的最佳实践 - JDBC](/best-practices/java-app-best-practices.md#jdbc)。 +本文介绍在使用 Java 驱动程序或 ORM 框架连接 TiDB 时，如何配置连接池和连接参数。 + +> **Tip:** +> +> 本文中以下章节摘自[开发 Java 应用使用 TiDB 的最佳实践](/develop/java-app-best-practices.md)： +> +> - [连接数配置](#连接数配置) +> - [探活配置](#探活配置) +> - [连接参数](#连接参数) ## 连接池参数 @@ -25,6 +32,38 @@ Java 的连接池实现很多 ([HikariCP](https://github.com/brettwooldridge/Hik 应用在使用连接池时，需要注意连接使用完成后归还连接，推荐应用使用对应的连接池相关监控（如 **metricRegistry**），通过监控能及时定位连接池问题。 +### 配置连接的生命周期 + +TiDB Server 在关闭、因维护而重启，或发生异常（如硬件故障或网络问题）时，现有的客户端连接可能会被重置，导致应用程序出现中断或异常。为避免此类问题，对于长期保持的数据库连接，建议每天至少主动关闭并重新建立一次连接。 + +常见的连接池库通常提供参数，用于控制连接的最长存活时间。 + + +
+ +- **`maxLifetime`**：连接在连接池中的最长存活时间。 + +
+ +
+ +- **`maxAge`**：连接在连接池中的最长存活时间。 + +
+ +
+ +- **`maxConnectionAge`**：连接在连接池中的最长存活时间。 + +
+ +
+ +- **`maxConnLifetimeMillis`**：连接在连接池中的最长存活时间（单位为毫秒）。 + +
+ + ### 探活配置 连接池维护客户端到 TiDB 的长连接的方式如下： @@ -144,7 +183,7 @@ TiDB 同时支持以上两种方式，但更推荐使用第一种将 `FetchSize` ### MySQL JDBC 参数 -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/kb/en/library/about-mariadb-connector-j/#optional-url-parameters)）。因为配置项较多，这里主要关注几个可能影响到性能的参数。 +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 相关参数 @@ -240,13 +279,13 @@ UPDATE `t` SET `a` = 12 WHERE `id` = 3; 通过监控可能会发现，虽然业务只向集群进行 insert 操作，却看到有很多多余的 select 语句。通常这是因为 JDBC 发送了一些查询设置类的 SQL 语句（例如 `select @@session.transaction_read_only`）。这些 SQL 对 TiDB 无用，推荐配置 `useConfigs = maxPerformance` 来避免额外开销。 -`useConfigs = maxPerformance` 会包含一组配置，可查看 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) 或 [5.1 版本](https://github.com/mysql/mysql-connector-j/blob/release/5.1/src/com/mysql/jdbc/configs/maxPerformance.properties) 来确认当前 MySQL Connector/J 中 `maxPerformance` 包含的具体配置。 +`useConfigs = maxPerformance` 会包含一组配置，可查看 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)或 [5.1 版本](https://github.com/mysql/mysql-connector-j/blob/release/5.1/src/com/mysql/jdbc/configs/maxPerformance.properties)来确认当前 MySQL Connector/J 中 `maxPerformance` 包含的具体配置。 配置后查看监控，可以看到多余语句减少。 #### 超时参数 -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 之前，`wait_timeout` 参数的默认值为 `0`，即没有时间限制。 `max_execution_time` 参数的默认值为 `0`，即不限制一条 SQL 语句的执行时间。 +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 之前，`wait_timeout` 参数的默认值为 `0`，即没有时间限制。 `max_execution_time` 参数的默认值为 `0`，即不限制一条 SQL 语句的执行时间，该参数适用于所有 `SELECT` 语句（包括 `SELECT ... FOR UPDATE`）。 但是 [`wait_timeout`](/system-variables.md#wait_timeout) 的默认值比较大，在事务已启动但未提交或回滚的情况下，你可能需要更细粒度的控制和更短的超时，以避免持有锁的时间过长。此时，你可以使用 TiDB 在 v7.6.0 引入的 [`tidb_idle_transaction_timeout`](/system-variables.md#tidb_idle_transaction_timeout-从-v760-版本开始引入) 控制用户会话中事务的空闲超时。 diff --git a/develop/dev-guide-create-database.md b/develop/dev-guide-create-database.md index 71c51d82d096..a2a32fe1a142 100644 --- a/develop/dev-guide-create-database.md +++ b/develop/dev-guide-create-database.md @@ -1,7 +1,7 @@ --- title: 创建数据库 summary: 创建数据库的方法、规范及例子。 -aliases: ['/zh/tidb/dev/create-database'] +aliases: ['/zh/tidb/dev/create-database','/zh/tidb/stable/dev-guide-create-database/','/zh/tidb/dev/dev-guide-create-database/','/zh/tidbcloud/dev-guide-create-database/'] --- # 创建数据库 @@ -16,7 +16,7 @@ aliases: ['/zh/tidb/dev/create-database'] 在阅读本页面之前，你需要准备以下事项： -- [使用 TiDB Cloud Serverless 构建 TiDB 集群](/develop/dev-guide-build-cluster-in-cloud.md)。 +- [使用 {{{ .starter }}} 构建 TiDB 集群](/develop/dev-guide-build-cluster-in-cloud.md)。 - 阅读[数据库模式概览](/develop/dev-guide-schema-design-overview.md)。 ## 什么是数据库 diff --git a/develop/dev-guide-create-secondary-indexes.md b/develop/dev-guide-create-secondary-indexes.md index 729c87527644..47a8fabf7d94 100644 --- a/develop/dev-guide-create-secondary-indexes.md +++ b/develop/dev-guide-create-secondary-indexes.md @@ -1,7 +1,7 @@ --- title: 创建二级索引 summary: 创建二级索引的方法、规范及例子。 -aliases: ['/zh/tidb/dev/create-secondary-indexes'] +aliases: ['/zh/tidb/dev/create-secondary-indexes','/zh/tidb/stable/dev-guide-create-secondary-indexes/','/zh/tidb/dev/dev-guide-create-secondary-indexes/','/zh/tidbcloud/dev-guide-create-secondary-indexes/'] --- # 创建二级索引 @@ -12,14 +12,18 @@ aliases: ['/zh/tidb/dev/create-secondary-indexes'] 在阅读本页面之前，你需要准备以下事项： -- [使用 TiDB Cloud Serverless 构建 TiDB 集群](/develop/dev-guide-build-cluster-in-cloud.md)。 +- [使用 {{{ .starter }}} 构建 TiDB 集群](/develop/dev-guide-build-cluster-in-cloud.md)。 - 阅读[数据库模式概览](/develop/dev-guide-schema-design-overview.md)。 - [创建一个数据库](/develop/dev-guide-create-database.md)。 - [创建表](/develop/dev-guide-create-table.md)。 ## 什么是二级索引 -二级索引是集群中的逻辑对象，你可以简单地认为它就是一种对数据的排序，TiDB 使用这种有序性来加速查询。TiDB 的创建二级索引的操作为在线操作，不会阻塞表中的数据读写。TiDB 会创建表中各行的引用，并按选择的列进行排序。而并非对表本身的数据进行排序。可在[二级索引](/best-practices/tidb-best-practices.md#二级索引)中查看更多信息。二级索引可[跟随表进行创建](#新建表的同时创建二级索引)，也可[在已有的表上进行添加](#在已有表中添加二级索引)。 +二级索引是集群中的逻辑对象，你可以简单地认为它就是一种对数据的排序，TiDB 使用这种有序性来加速查询。TiDB 的创建二级索引的操作为在线操作，不会阻塞表中的数据读写。TiDB 会创建表中各行的引用，并按选择的列进行排序。而并非对表本身的数据进行排序。 + +更多信息，请参阅[二级索引](/best-practices/tidb-best-practices.md#二级索引)。 + +在 TiDB 中，二级索引可[跟随表进行创建](#新建表的同时创建二级索引)，也可[在已有的表上进行添加](#在已有表中添加二级索引)。 ## 在已有表中添加二级索引 @@ -125,12 +129,17 @@ CREATE INDEX `idx_book_published_at` ON `bookshop`.`books` (`bookshop`.`books`.` 可以看到执行计划中没有了 **TableFullScan** 的字样，取而代之的是 **IndexRangeScan**，这代表已经 TiDB 在进行这个查询时准备使用索引。 +上方执行计划中的的 **TableFullScan**、**IndexRangeScan** 等在 TiDB 内被称为[算子](/explain-overview.md#算子简介)。这里对执行计划的解读及算子等不做进一步的展开，若你对此感兴趣，可前往 [TiDB 执行计划概览](/explain-overview.md)文档查看更多关于执行计划与 TiDB 算子的相关知识。 + +执行计划并非每次返回使用的算子都相同，这是由于 TiDB 使用的优化方式为 **基于代价的优化方式 (CBO)**，执行计划不仅与规则相关，还和数据分布相关。 + +关于 TiDB SQL 性能调优的更多信息，请参阅以下文档： + +- TiDB Cloud 文档：[SQL 调优概述](https://docs.pingcap.com/zh/tidbcloud/tidb-cloud-sql-tuning-overview/) +- TiDB 文档：[SQL 性能调优](/sql-tuning-overview.md) + > **注意：** > -> 上方执行计划中的的 **TableFullScan**、**IndexRangeScan** 等在 TiDB 内被称为[算子](/explain-overview.md#算子简介)。这里对执行计划的解读及算子等不做进一步的展开，若你对此感兴趣，可前往 [TiDB 执行计划概览](/explain-overview.md)文档查看更多关于执行计划与 TiDB 算子的相关知识。 -> -> 执行计划并非每次返回使用的算子都相同，这是由于 TiDB 使用的优化方式为 **基于代价的优化方式 (CBO)**，执行计划不仅与规则相关，还和数据分布相关。你可以前往 [SQL 性能调优](/sql-tuning-overview.md)文档查看更多 TiDB SQL 性能的描述。 -> > TiDB 在查询时，还支持显式地使用索引，你可以使用 [Optimizer Hints](/optimizer-hints.md) 或[执行计划管理 (SPM)](/sql-plan-management.md) 来人为的控制索引的使用。但如果你不了解它内部发生了什么，请你**_暂时先不要使用它_**。 可以使用 [SHOW INDEXES](/sql-statements/sql-statement-show-indexes.md) 语句查询表中的索引： diff --git a/develop/dev-guide-create-table.md b/develop/dev-guide-create-table.md index fa0ca0aca991..f6715f4b6363 100644 --- a/develop/dev-guide-create-table.md +++ b/develop/dev-guide-create-table.md @@ -1,7 +1,7 @@ --- title: 创建表 summary: 创建表的方法、规范及例子。 -aliases: ['/zh/tidb/dev/create-table'] +aliases: ['/zh/tidb/dev/create-table','/zh/tidb/stable/dev-guide-create-table/','/zh/tidb/dev/dev-guide-create-table/','/zh/tidbcloud/dev-guide-create-table/'] --- # 创建表 @@ -16,7 +16,7 @@ aliases: ['/zh/tidb/dev/create-table'] 在阅读本页面之前，你需要准备以下事项： -- [使用 TiDB Cloud Serverless 构建 TiDB 集群](/develop/dev-guide-build-cluster-in-cloud.md)。 +- [使用 {{{ .starter }}} 构建 TiDB 集群](/develop/dev-guide-build-cluster-in-cloud.md)。 - 阅读[数据库模式概览](/develop/dev-guide-schema-design-overview.md)。 - [创建一个数据库](/develop/dev-guide-create-database.md)。 @@ -80,7 +80,7 @@ CREATE TABLE `bookshop`.`users` ( 最后，又加入了一个字段名为 `balance` 用以表示用户的余额，类型为 [decimal](/data-type-numeric.md#decimal-类型)，且其精度为 15，比例为 2。简单的说明一下精度和比例代表的含义，精度代表字段数值的总位数，而比例代表小数点后有多少位。例如: `decimal(5,2)`，即精度为 5，比例为 2 时，其取值范围为 `-999.99` 到 `999.99`。`decimal(6,1)`，即精度为 6，比例为 1 时，其取值范围为 `-99999.9` 到 `99999.9`。`decimal` 类型为定点数，可精确保存数字，在需要精确数字的场景（如用户财产相关）中，请确保使用[定点数](/data-type-numeric.md#定点类型)类型。 -TiDB 支持许多其他的列数据类型，包含[整数](/data-type-numeric.md#整数类型)、[浮点数](/data-type-numeric.md#浮点类型)、[定点数](/data-type-numeric.md#定点类型)、[时间](/data-type-date-and-time.md#datetime-类型)、[枚举](/data-type-string.md#enum-类型) 等，可参考支持的列的[数据类型](/basic-features.md#数据类型函数和操作符)，并使用与你准备保存在数据库内的数据匹配的**数据类型**。 +TiDB 支持许多其他的列数据类型，包含[整数](/data-type-numeric.md#整数类型)、[浮点数](/data-type-numeric.md#浮点类型)、[定点数](/data-type-numeric.md#定点类型)、[时间](/data-type-date-and-time.md#datetime-类型)、[枚举](/data-type-string.md#enum-类型)等，可参考支持的列的[数据类型](/basic-features.md#数据类型函数和操作符)，并使用与你准备保存在数据库内的数据匹配的**数据类型**。 稍微提升一下复杂度，例如选择定义一张 `books` 表，这张表将是 `bookshop` 数据的核心。它包含书的唯一标识、名称、书籍类型（如：杂志、动漫、教辅等）、库存、价格、出版时间等字段。 @@ -132,7 +132,7 @@ CREATE TABLE `bookshop`.`users` ( ## 选择聚簇索引 -[聚簇索引](/clustered-indexes.md) (clustered index) 是 TiDB 从 v5.0 开始支持的特性，用于控制含有主键的表数据的存储方式。通过使用聚簇索引，TiDB 可以更好地组织数据表，从而提高某些查询的性能。有些数据库管理系统也将聚簇索引称为“索引组织表” (index-organized tables)。 +[聚簇索引](/clustered-indexes.md) (clustered index) 是 TiDB 从 v5.0 开始支持的特性，用于控制含有主键的表数据的存储方式。通过使用聚簇索引，TiDB 可以更好地组织数据表，从而提高某些查询的性能。有些数据库管理系统将聚簇索引表称为“索引组织表” (index-organized tables)。 目前 TiDB 中 **_含有主键_** 的表分为以下两类： @@ -236,11 +236,9 @@ CREATE TABLE `bookshop`.`users` ( 这种场景下，TiDB 就是一个比较理想的一站式数据库解决方案，TiDB 是一个 **HTAP (Hybrid Transactional and Analytical Processing)** 数据库，同时支持 OLTP 和 OLAP 场景。 -### 同步列存数据 - -当前，TiDB 支持两种数据分析引擎：**TiFlash** 和 **TiSpark**。大数据场景 (100 T) 下，推荐使用 TiFlash MPP 作为 HTAP 的主要方案，TiSpark 作为补充方案。希望了解更多关于 TiDB 的 HTAP 能力，可参考以下文章：[快速上手 HTAP](/quick-start-with-htap.md) 和[深入探索 HTAP](/explore-htap.md)。 +在 TiDB 中，你可以使用行存储引擎 [TiKV](/tikv-overview.md) 进行在线事务处理 (OLTP)，使用列存储引擎 [TiFlash](/tiflash/tiflash-overview.md) 进行在线分析处理（OLAP）。完成相关配置后，TiFlash 将基于 Raft Learner Consensus 算法实时从 TiKV 同步数据，从而确保 TiKV 与 TiFlash 之间的数据强一致。 -此处选用 [TiFlash](/tiflash/tiflash-overview.md) 为 `bookshop` 数据库的数据分析引擎。 +### 同步列存数据 TiFlash 部署完成后并不会自动同步数据，而需要手动指定需要同步的表，开启同步副本仅需一行 SQL，如下所示： @@ -265,7 +263,7 @@ ALTER TABLE `bookshop`.`ratings` SET TIFLASH REPLICA 1; > **注意：** > -> 如果你的集群，不包含 TiFlash 节点，此 SQL 语句将会报错：`1105 - the tiflash replica count: 1 should be less than the total tiflash server count: 0` 你可以[使用 TiDB Cloud Serverless 构建 TiDB 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群) 来创建一个含有 TiFlash 的集群。 +> 如果你的集群，不包含 TiFlash 节点，此 SQL 语句将会报错：`1105 - the tiflash replica count: 1 should be less than the total tiflash server count: 0` 你可以[使用 {{{ .starter }}} 构建 TiDB 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)来创建一个含有 TiFlash 的集群。 随后正常进行查询即可： diff --git a/develop/dev-guide-delete-data.md b/develop/dev-guide-delete-data.md index 2bdfa0b846c4..d4a51a53642a 100644 --- a/develop/dev-guide-delete-data.md +++ b/develop/dev-guide-delete-data.md @@ -1,18 +1,18 @@ --- title: 删除数据 summary: 删除数据、批量删除数据的方法、最佳实践及例子。 -aliases: ['/zh/tidb/dev/delete-data'] +aliases: ['/zh/tidb/dev/delete-data','/zh/tidb/stable/dev-guide-delete-data/','/zh/tidb/dev/dev-guide-delete-data/','/zh/tidbcloud/dev-guide-delete-data/'] --- # 删除数据 -此页面将使用 [DELETE](/sql-statements/sql-statement-delete.md) SQL 语句，对 TiDB 中的数据进行删除。如果需要周期性地删除过期数据，可以考虑使用 TiDB 的 [TTL 功能](/time-to-live.md)。 +此页面将使用 [DELETE](/sql-statements/sql-statement-delete.md) SQL 语句，对 TiDB 中的数据进行删除。如果需要周期性地删除过期数据，可以考虑使用 TiDB 的 [TTL 功能](/develop/dev-guide-time-to-live.md)。 ## 在开始之前 在阅读本页面之前，你需要准备以下事项： -- [使用 TiDB Cloud Serverless 构建 TiDB 集群](/develop/dev-guide-build-cluster-in-cloud.md)。 +- [使用 {{{ .starter }}} 构建 TiDB 集群](/develop/dev-guide-build-cluster-in-cloud.md)。 - 阅读[数据库模式概览](/develop/dev-guide-schema-design-overview.md)，并[创建数据库](/develop/dev-guide-create-database.md)、[创建表](/develop/dev-guide-create-table.md)、[创建二级索引](/develop/dev-guide-create-secondary-indexes.md)。 - 需先[插入数据](/develop/dev-guide-insert-data.md)才可删除。 @@ -162,7 +162,7 @@ with connection: > **注意：** > -> `rated_at` 字段为[日期和时间类型](/data-type-date-and-time.md) 中的 `DATETIME` 类型，你可以认为它在 TiDB 保存时，存储为一个字面量，与时区无关。而 `TIMESTAMP` 类型，将会保存一个时间戳，从而在不同的[时区配置](/configure-time-zone.md)时，展示不同的时间字符串。 +> `rated_at` 字段为[日期和时间类型](/data-type-date-and-time.md)中的 `DATETIME` 类型，你可以认为它在 TiDB 保存时，存储为一个字面量，与时区无关。而 `TIMESTAMP` 类型，将会保存一个时间戳，从而在不同的[时区配置](/configure-time-zone.md)时，展示不同的时间字符串。 > > 另外，和 MySQL 一样，`TIMESTAMP` 数据类型受 [2038 年问题](https://zh.wikipedia.org/wiki/2038%E5%B9%B4%E9%97%AE%E9%A2%98)的影响。如果存储的值大于 2038，建议使用 `DATETIME` 类型。 @@ -174,7 +174,7 @@ with connection: GC 在默认配置中，为 10 分钟触发一次，每次 GC 都会计算出一个名为 **safe_point** 的时间点，这个时间点前的数据，都不会再被使用到，因此，TiDB 可以安全的对数据进行清除。 -GC 的具体实现方案和细节此处不再展开，请参考 [GC 机制简介](/garbage-collection-overview.md) 了解更详细的 GC 说明。 +GC 的具体实现方案和细节此处不再展开，请参考 [GC 机制简介](/garbage-collection-overview.md)了解更详细的 GC 说明。 ### 更新统计信息 diff --git a/develop/dev-guide-get-data-from-single-table.md b/develop/dev-guide-get-data-from-single-table.md index fbf2cfb58e47..76b5a4ebd148 100644 --- a/develop/dev-guide-get-data-from-single-table.md +++ b/develop/dev-guide-get-data-from-single-table.md @@ -1,7 +1,7 @@ --- title: 单表查询 summary: 介绍 TiDB 中的单表查询功能。 -aliases: ['/zh/tidb/dev/get-data-from-single-table'] +aliases: ['/zh/tidb/dev/get-data-from-single-table','/zh/tidb/stable/dev-guide-get-data-from-single-table/','/zh/tidb/dev/dev-guide-get-data-from-single-table/','/zh/tidbcloud/dev-guide-get-data-from-single-table/'] --- @@ -102,9 +102,9 @@ public class AuthorDAO { } ``` -- 在[获得数据库连接](/develop/dev-guide-connect-to-tidb.md#jdbc)之后，你可以通过 `conn.createStatement()` 语句创建一个 `Statement` 实例对象。 -- 然后调用 `stmt.executeQuery("query_sql")` 方法向 TiDB 发起一个数据库查询请求。 -- 数据库返回的查询结果将会存放到 `ResultSet` 当中，通过遍历 `ResultSet` 对象可以将返回结果映射到此前准备的 `Author` 类对象当中。 +在[使用 JDBC 连接到 TiDB](/develop/dev-guide-sample-application-java-jdbc.md)之后，你可以通过 `conn.createStatement()` 语句创建一个 `Statement` 实例对象。然后调用 `stmt.executeQuery("query_sql")` 方法向 TiDB 发起一个数据库查询请求。 + +数据库返回的查询结果将会存放到 `ResultSet` 当中，通过遍历 `ResultSet` 对象可以将返回结果映射到此前准备的 `Author` 类对象当中。 diff --git a/develop/dev-guide-gui-mysql-workbench.md b/develop/dev-guide-gui-mysql-workbench.md index 99784e5d1e89..d5b3eea13c33 100644 --- a/develop/dev-guide-gui-mysql-workbench.md +++ b/develop/dev-guide-gui-mysql-workbench.md @@ -1,6 +1,7 @@ --- title: 使用 MySQL Workbench 连接到 TiDB summary: 了解如何使用 MySQL Workbench 连接到 TiDB。 +aliases: ['/zh/tidb/stable/dev-guide-gui-mysql-workbench/','/zh/tidb/dev/dev-guide-gui-mysql-workbench/','/zh/tidbcloud/dev-guide-gui-mysql-workbench/'] --- # 使用 MySQL Workbench 连接到 TiDB @@ -16,7 +17,7 @@ TiDB 是一个兼容 MySQL 的数据库。[MySQL Workbench](https://www.mysql.co > **注意** > -> 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 +> 本文档适用于 {{{ .starter }}}、{{{ .essential }}}、TiDB Cloud Dedicated 和本地部署的 TiDB。 ## 前置需求 @@ -27,15 +28,15 @@ TiDB 是一个兼容 MySQL 的数据库。[MySQL Workbench](https://www.mysql.co **如果你还没有 TiDB 集群，可以按如下方式创建一个：** -- （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md)，创建一个 TiDB Cloud 集群。 -- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建一个本地集群。 +- （推荐方式）参考[创建 {{{ .starter }}} 集群](/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)，创建一个本地集群。 ## 连接到 TiDB 根据你选择的 TiDB 部署方式连接到 TiDB 集群。 -
+
1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，点击你目标集群的名字，进入集群的 **Overview** 页面。 @@ -64,15 +65,15 @@ TiDB 是一个兼容 MySQL 的数据库。[MySQL Workbench](https://www.mysql.co - **Hostname**：输入从 TiDB Cloud 连接对话框中的得到的 `HOST` 参数。 - **Port**：输入从 TiDB Cloud 连接对话框中的得到的 `PORT` 参数。 - **Username**：输入从 TiDB Cloud 连接对话框中的得到的 `USERNAME` 参数。 - - **Password**：点击 **Store in Keychain ...** 或 **Store in Vault**，输入 TiDB Cloud Serverless 集群的密码，然后点击 **OK** 保存密码。 + - **Password**：点击 **Store in Keychain ...** 或 **Store in Vault**，输入 {{{ .starter }}} 集群的密码，然后点击 **OK** 保存密码。 - ![MySQL Workbench: store the password of TiDB Cloud Serverless in keychain](/media/develop/mysql-workbench-store-password-in-keychain.png) + ![MySQL Workbench: store the password of {{{ .starter }}} in keychain](/media/develop/mysql-workbench-store-password-in-keychain.png) 下图显示了连接参数的示例： - ![MySQL Workbench: configure connection settings for TiDB Cloud Serverless](/media/develop/mysql-workbench-connection-config-serverless-parameters.png) + ![MySQL Workbench: configure connection settings for {{{ .starter }}}](/media/develop/mysql-workbench-connection-config-serverless-parameters.png) -7. 点击 **Test Connection** 以验证与 TiDB Cloud Serverless 集群的连接。 +7. 点击 **Test Connection** 以验证与 {{{ .starter }}} 集群的连接。 8. 如果连接测试成功，你可以看到 **Successfully made the MySQL connection** 信息。点击 **OK** 保存连接配置。 @@ -155,9 +156,9 @@ TiDB 是一个兼容 MySQL 的数据库。[MySQL Workbench](https://www.mysql.co ## 下一步 - 关于 MySQL Workbench 的更多使用方法，可以参考 [MySQL Workbench 官方文档](https://dev.mysql.com/doc/workbench/en/)。 -- 你可以继续阅读[开发者文档](/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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide) 支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 你可以继续阅读[开发者文档](/develop/_index.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://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 ## 需要帮助? -如果在开发的过程中遇到问题，可以在 [AskTUG](https://asktug.com/?utm_source=docs-cn-dev-guide) 上进行提问，或从 PingCAP 官方或 TiDB 社区[获取支持](/support.md)。 +如果在开发的过程中遇到问题，可以在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问，或从 PingCAP 官方或 TiDB 社区[获取支持](/support.md)。 diff --git a/develop/dev-guide-gui-navicat.md b/develop/dev-guide-gui-navicat.md index d8e39fde4bf5..746e2b5befa7 100644 --- a/develop/dev-guide-gui-navicat.md +++ b/develop/dev-guide-gui-navicat.md @@ -1,6 +1,7 @@ --- title: 使用 Navicat 连接到 TiDB summary: 了解如何使用 Navicat 连接到 TiDB。 +aliases: ['/zh/tidb/stable/dev-guide-gui-navicat/','/zh/tidb/dev/dev-guide-gui-navicat/','/zh/tidbcloud/dev-guide-gui-navicat/'] --- # 使用 Navicat 连接到 TiDB @@ -11,7 +12,7 @@ TiDB 是一个兼容 MySQL 的数据库。[Navicat](https://www.navicat.com) 是 > **注意** > -> 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 +> 本文档适用于 {{{ .starter }}}、{{{ .essential }}}、TiDB Cloud Dedicated 和本地部署的 TiDB。 ## 前置需求 @@ -23,15 +24,15 @@ TiDB 是一个兼容 MySQL 的数据库。[Navicat](https://www.navicat.com) 是 **如果你还没有 TiDB 集群，可以按如下方式创建一个：** -- （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md)，创建一个 TiDB Cloud 集群。 -- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建一个本地集群。 +- （推荐方式）参考[创建 {{{ .starter }}} 集群](/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)，创建一个本地集群。 ## 连接到 TiDB 根据你选择的 TiDB 部署方式连接到 TiDB 集群。 -
+
1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，点击你目标集群的名字，进入集群的 **Overview** 页面。 @@ -60,15 +61,15 @@ TiDB 是一个兼容 MySQL 的数据库。[Navicat](https://www.navicat.com) 是 - **Host**：输入从 TiDB Cloud 连接对话框中的得到的 `HOST` 参数。 - **Port**：输入从 TiDB Cloud 连接对话框中的得到的 `PORT` 参数。 - **User Name**：输入从 TiDB Cloud 连接对话框中的得到的 `USERNAME` 参数。 - - **Password**：输入 TiDB Cloud Serverless 集群的密码。 + - **Password**：输入 {{{ .starter }}} 集群的密码。 - ![Navicat: configure connection general panel for TiDB Cloud Serverless](/media/develop/navicat-premium-connection-config-serverless-general.png) + ![Navicat: configure connection general panel for {{{ .starter }}}](/media/develop/navicat-premium-connection-config-serverless-general.png) 7. 点击 **SSL** 选项卡，选择 **Use SSL**，**Use authentication** 以及 **Verify server certificate against CA** 复选框。并在 **CA Certificate** 字段中填入从 TiDB Cloud 连接对话框中获取的 `CA` 文件路径。 - ![Navicat: configure connection SSL panel for TiDB Cloud Serverless](/media/develop/navicat-premium-connection-config-serverless-ssl.png) + ![Navicat: configure connection SSL panel for {{{ .starter }}}](/media/develop/navicat-premium-connection-config-serverless-ssl.png) -8. 点击 **Test Connection** 以验证与 TiDB Cloud Serverless 集群的连接。 +8. 点击 **Test Connection** 以验证与 {{{ .starter }}} 集群的连接。 9. 如果连接测试成功，你可以看到 **Connection Successful** 信息。点击 **OK** 完成连接配置。 @@ -135,9 +136,9 @@ TiDB 是一个兼容 MySQL 的数据库。[Navicat](https://www.navicat.com) 是 ## 下一步 -- 你可以继续阅读[开发者文档](/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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide) 支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 你可以继续阅读[开发者文档](/develop/_index.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://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 ## 需要帮助? -如果在开发的过程中遇到问题，可以在 [AskTUG](https://asktug.com/?utm_source=docs-cn-dev-guide) 上进行提问，或从 PingCAP 官方或 TiDB 社区[获取支持](/support.md)。 +如果在开发的过程中遇到问题，可以在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问，或从 PingCAP 官方或 TiDB 社区[获取支持](/support.md)。 diff --git a/develop/dev-guide-hybrid-oltp-and-olap-queries.md b/develop/dev-guide-hybrid-oltp-and-olap-queries.md index d2ac8e792a80..cd6600e316b5 100644 --- a/develop/dev-guide-hybrid-oltp-and-olap-queries.md +++ b/develop/dev-guide-hybrid-oltp-and-olap-queries.md @@ -1,7 +1,7 @@ --- title: HTAP 查询 summary: 介绍 TiDB 中的 HTAP 查询功能。 -aliases: ['/zh/tidb/dev/hybrid-oltp-and-olap-queries'] +aliases: ['/zh/tidb/dev/hybrid-oltp-and-olap-queries','/zh/tidb/stable/dev-guide-hybrid-oltp-and-olap-queries/','/zh/tidb/dev/dev-guide-hybrid-oltp-and-olap-queries/','/zh/tidbcloud/dev-guide-hybrid-oltp-and-olap-queries/'] --- # HTAP 查询 @@ -14,13 +14,13 @@ HTAP 是 Hybrid Transactional / Analytical Processing 的缩写。传统意义 ## 数据准备 -在开始之前，你可以[通过 `tiup demo` 命令导入](/develop/dev-guide-bookshop-schema-design.md#方法一通过-tiup-demo-命令行)更加大量的示例数据，例如： +在开始之前，你可以[通过 `tiup demo` 命令导入](/develop/dev-guide-bookshop-schema-design.md#本地部署的-tidb通过-tiup-demo-命令行)更加大量的示例数据，例如： ```shell tiup demo bookshop prepare --users=200000 --books=500000 --authors=100000 --ratings=1000000 --orders=1000000 --host 127.0.0.1 --port 4000 --drop-tables ``` -或[使用 TiDB Cloud 的 Import 功能导入](/develop/dev-guide-bookshop-schema-design.md#方法二通过-tidb-cloud-import-功能)预先准备好的示例数据。 +或[使用 TiDB Cloud 的 Import 功能导入](/develop/dev-guide-bookshop-schema-design.md#tidb-cloud通过-import-功能)预先准备好的示例数据。 ## 窗口函数 @@ -247,7 +247,7 @@ SELECT * FROM acc; ## 扩展阅读 -- [HTAP 快速上手指南](/quick-start-with-htap.md) -- [HTAP 深入探索指南](/explore-htap.md) +- TiDB Cloud 文档：[HTAP 快速上手指南](https://docs.pingcap.com/zh/tidbcloud/tidb-cloud-htap-quickstart/) +- TiDB 文档：[HTAP 快速上手指南](/quick-start-with-htap.md) 和 [HTAP 深入探索指南](/explore-htap.md) - [窗口函数](/functions-and-operators/window-functions.md) - [使用 TiFlash](/tiflash/tiflash-overview.md#使用-tiflash) diff --git a/develop/dev-guide-implicit-type-conversion.md b/develop/dev-guide-implicit-type-conversion.md index 2d3983faccad..c413dc7cbc9d 100644 --- a/develop/dev-guide-implicit-type-conversion.md +++ b/develop/dev-guide-implicit-type-conversion.md @@ -1,7 +1,7 @@ --- title: 避免隐式类型转换 summary: 介绍 TiDB 中隐式类型转换可能会带来的后果和避免方法。 -aliases: ['/zh/tidb/dev/implicit-type-conversion'] +aliases: ['/zh/tidb/dev/implicit-type-conversion','/zh/tidb/stable/dev-guide-implicit-type-conversion/','/zh/tidb/dev/dev-guide-implicit-type-conversion/','/zh/tidbcloud/dev-guide-implicit-type-conversion/'] --- # 避免隐式类型转换 diff --git a/develop/dev-guide-index-best-practice.md b/develop/dev-guide-index-best-practice.md index b4f781a35752..282cd7ee1705 100644 --- a/develop/dev-guide-index-best-practice.md +++ b/develop/dev-guide-index-best-practice.md @@ -1,7 +1,7 @@ --- title: 索引的最佳实践 summary: 介绍 TiDB 中索引的最佳实践。 -aliases: ['/zh/tidb/dev/index-best-practice'] +aliases: ['/zh/tidb/dev/index-best-practice','/zh/tidb/stable/dev-guide-index-best-practice/','/zh/tidb/dev/dev-guide-index-best-practice/','/zh/tidbcloud/dev-guide-index-best-practice/'] --- diff --git a/develop/dev-guide-insert-data.md b/develop/dev-guide-insert-data.md index 9a282038fbae..3d776bad6150 100644 --- a/develop/dev-guide-insert-data.md +++ b/develop/dev-guide-insert-data.md @@ -1,7 +1,7 @@ --- title: 插入数据 summary: 插入数据、批量导入数据的方法、最佳实践及例子。 -aliases: ['/zh/tidb/dev/insert-data'] +aliases: ['/zh/tidb/dev/insert-data','/zh/tidb/stable/dev-guide-insert-data/','/zh/tidb/dev/dev-guide-insert-data/','/zh/tidbcloud/dev-guide-insert-data/'] --- @@ -14,7 +14,7 @@ aliases: ['/zh/tidb/dev/insert-data'] 在阅读本页面之前，你需要准备以下事项： -- [使用 TiDB Cloud Serverless 构建 TiDB 集群](/develop/dev-guide-build-cluster-in-cloud.md)。 +- [使用 {{{ .starter }}} 构建 TiDB 集群](/develop/dev-guide-build-cluster-in-cloud.md)。 - 阅读[数据库模式概览](/develop/dev-guide-schema-design-overview.md)，并[创建数据库](/develop/dev-guide-create-database.md)、[创建表](/develop/dev-guide-create-table.md)、[创建二级索引](/develop/dev-guide-create-secondary-indexes.md)。 ## 插入行 @@ -241,12 +241,26 @@ with get_connection(autocommit=True) as connection: ## 批量插入 -如果你需要快速地将大量数据导入 TiDB 集群，最好的方式并不是使用 `INSERT` 语句，这并不是最高效的方法，而且需要你自行处理异常等问题。推荐使用 PingCAP 提供的一系列工具进行数据迁移： +如果你需要快速地将大量数据导入 TiDB 集群，最好的方式并不是使用 `INSERT` 语句，这并不是最高效的方法，而且需要你自行处理异常等问题。推荐使用以下工具进行数据批量插入： + + +
+ +- 数据导出：使用 [Dumpling](/dumpling-overview.md) 将 MySQL 或 TiDB 数据导出到本地或云存储。对于 TiDB Cloud Starter 或 Essential 集群，还可以使用 [TiDB Cloud 控制台](https://tidbcloud.com/) 中的 [Export](https://docs.pingcap.com/zh/tidbcloud/serverless-export) 功能高效地导出数据。 +- 数据导入：使用 [TiDB Cloud 控制台](https://tidbcloud.com/) 中的 [Import](https://docs.pingcap.com/zh/tidbcloud/import-sample-data) 功能。你可以导入 Dumpling 导出的数据、导入本地 CSV 文件，或[从云存储导入 CSV 文件到 TiDB Cloud](https://docs.pingcap.com/zh/tidbcloud/import-csv-files/)。 +- 数据同步：使用 [TiDB Cloud 控制台](https://tidbcloud.com/) 中的 [TiDB Data Migration](https://docs.pingcap.com/zh/tidbcloud/migrate-from-mysql-using-data-migration) 功能。可同步 MySQL 兼容数据库到 TiDB，且支持分库分表数据库的迁移。 +- 数据备份与恢复：使用 [TiDB Cloud 控制台](https://tidbcloud.com/) 中的 [Backup](https://docs.pingcap.com/zh/tidbcloud/backup-and-restore) 功能。与 Dumpling 相比，备份与恢复功能更适用于大数据场景。 + +
+
- 数据导出工具：[Dumpling](/dumpling-overview.md)。可以导出 MySQL 或 TiDB 的数据到本地或 Amazon S3 中。 -- 数据导入工具：[TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md)。可以导入 `Dumpling` 导出的数据、CSV 文件，或者 [Amazon Aurora 生成的 Apache Parquet 文件](/migrate-aurora-to-tidb.md)。同时支持在本地盘或 Amazon S3 云盘读取数据。 -- 数据同步工具：[TiDB Data Migration](/dm/dm-overview.md)。可同步 MySQL、MariaDB、Amazon Aurora 数据库到 TiDB 中。且支持分库分表数据库的迁移。 -- 数据备份恢复工具：[Backup & Restore (BR)](/br/backup-and-restore-overview.md)。相对于 `Dumpling`，BR 更适合**_大数据量_**的场景。 +- 数据导入工具：[TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md)。可以导入 Dumpling 导出的数据、CSV 文件，或者 [Amazon Aurora 生成的 Apache Parquet 文件](/migrate-aurora-to-tidb.md)。同时支持在本地盘或 Amazon S3 云盘读取数据。 +- 数据同步工具：[TiDB Data Migration](/dm/dm-overview.md)。可同步 MySQL、MariaDB、Amazon Aurora 数据库到 TiDB 中，且支持分库分表数据库的迁移。 +- 数据备份恢复工具：[Backup & Restore (BR)](/br/backup-and-restore-overview.md)。相对于 Dumpling，BR 更适合大数据量的场景。 + +
+ ## 避免热点 @@ -256,7 +270,7 @@ with get_connection(autocommit=True) as connection: ## 主键为 `AUTO_RANDOM` 表插入数据 -在插入的表主键为 `AUTO_RANDOM` 时，这时默认情况下，不能指定主键。例如 [bookshop](/develop/dev-guide-bookshop-schema-design.md) 数据库中，可以看到 [users 表](/develop/dev-guide-bookshop-schema-design.md#users-表) 的 `id` 字段含有 `AUTO_RANDOM` 属性。 +在插入的表主键为 `AUTO_RANDOM` 时，这时默认情况下，不能指定主键。例如 [bookshop](/develop/dev-guide-bookshop-schema-design.md) 数据库中，可以看到 [users 表](/develop/dev-guide-bookshop-schema-design.md#users-表)的 `id` 字段含有 `AUTO_RANDOM` 属性。 此时，不可使用类似以下 SQL 进行插入： diff --git a/develop/dev-guide-join-tables.md b/develop/dev-guide-join-tables.md index 8c0556b8abf6..3bf4bfd81708 100644 --- a/develop/dev-guide-join-tables.md +++ b/develop/dev-guide-join-tables.md @@ -1,7 +1,7 @@ --- title: 多表连接查询 summary: 介绍 TiDB 中的多表连接查询功能。 -aliases: ['/zh/tidb/dev/join-tables'] +aliases: ['/zh/tidb/dev/join-tables','/zh/tidb/stable/dev-guide-join-tables/','/zh/tidb/dev/dev-guide-join-tables/','/zh/tidbcloud/dev-guide-join-tables/'] --- # 多表连接查询 diff --git a/develop/dev-guide-mysql-tools.md b/develop/dev-guide-mysql-tools.md new file mode 100644 index 000000000000..9dd48c14695f --- /dev/null +++ b/develop/dev-guide-mysql-tools.md @@ -0,0 +1,58 @@ +--- +title: 通过 MySQL 工具连接到 TiDB +summary: 介绍如何通过 MySQL 工具连接到 TiDB。 +--- + +# 通过 MySQL 工具连接到 TiDB + +**TiDB** 高度兼容 **MySQL** 协议，全量的客户端连接参数列表，请参阅 [MySQL Client Options](https://dev.mysql.com/doc/refman/8.0/en/mysql-command-options.html)。 + +TiDB 支持 [MySQL 客户端/服务器协议](https://dev.mysql.com/doc/dev/mysql-server/latest/PAGE_PROTOCOL.html)。这使得大多数客户端驱动程序和 ORM 框架可以像连接到 MySQL 一样地连接到 TiDB。 + +你可以选择使用 MySQL Client 或 MySQL Shell 连接到 TiDB。 + + + +
+ +你可以使用 MySQL Client 作为 TiDB 的命令行工具连接到 TiDB。下面以基于 YUM 的 Linux 发行版为例，介绍如何安装 MySQL Client。 + +```shell +sudo yum install mysql +``` + +安装完成后，你可以使用如下命令连接到 TiDB： + +```shell +mysql --host --port 4000 -u root -p --comments +``` + +macOS 上的 MySQL v9.0 客户端无法正确加载 `mysql_native_password` 插件，导致连接 TiDB 时报错 `ERROR 2059 (HY000): Authentication plugin 'mysql_native_password' cannot be loaded`。为解决该问题，建议安装并使用 MySQL v8.0 客户端来连接 TiDB 。安装命令如下： + +```shell +brew install mysql-client@8.0 +brew unlink mysql +brew link mysql-client@8.0 +``` + +如果仍然遇到问题，可以尝试指定 MySQL v8.0 客户端的安装路径来使用 MySQL v8.0 客户端连接 TiDB。连接命令如下： + +```shell +/opt/homebrew/opt/mysql-client@8.0/bin/mysql --comments --host ${YOUR_IP_ADDRESS} --port ${YOUR_PORT_NUMBER} -u ${your_user_name} -p +``` + +请使用实际部署的 MySQL v8.0 客户端的安装路径替代上述命令中的 `/opt/homebrew/opt/mysql-client@8.0/bin/mysql`。 + +
+ +
+ +你可以使用 MySQL Shell 作为 TiDB 的命令行工具连接到 TiDB。参考 [MySQL Shell 文档](https://dev.mysql.com/doc/mysql-shell/8.0/en/mysql-shell-install.html)进行安装。安装完成后，你可以使用如下命令连接到 TiDB： + +```shell +mysqlsh --sql mysql://root@:4000 +``` + +
+ + \ No newline at end of file diff --git a/develop/dev-guide-object-naming-guidelines.md b/develop/dev-guide-object-naming-guidelines.md index 5f498e65cdea..1d8b52d300af 100644 --- a/develop/dev-guide-object-naming-guidelines.md +++ b/develop/dev-guide-object-naming-guidelines.md @@ -1,7 +1,7 @@ --- title: 对象命名规范 summary: 介绍 TiDB 中的对象命名规范。 -aliases: ['/zh/tidb/dev/object-naming-guidelines'] +aliases: ['/zh/tidb/dev/object-naming-guidelines','/zh/tidb/stable/dev-guide-object-naming-guidelines/','/zh/tidb/dev/dev-guide-object-naming-guidelines/','/zh/tidbcloud/dev-guide-object-naming-guidelines/'] --- # 对象命名规范 diff --git a/develop/dev-guide-optimistic-and-pessimistic-transaction.md b/develop/dev-guide-optimistic-and-pessimistic-transaction.md index 18b1f7adaebd..83637b17be1a 100644 --- a/develop/dev-guide-optimistic-and-pessimistic-transaction.md +++ b/develop/dev-guide-optimistic-and-pessimistic-transaction.md @@ -1,7 +1,7 @@ --- title: 乐观事务和悲观事务 summary: 介绍 TiDB 中的乐观事务和悲观事务，乐观事务的重试等。 -aliases: ['/zh/tidb/dev/optimistic-and-pessimistic-transaction'] +aliases: ['/zh/tidb/dev/optimistic-and-pessimistic-transaction','/zh/tidb/stable/dev-guide-optimistic-and-pessimistic-transaction/','/zh/tidb/dev/dev-guide-optimistic-and-pessimistic-transaction/','/zh/tidbcloud/dev-guide-optimistic-and-pessimistic-transaction/'] --- # 乐观事务和悲观事务 diff --git a/develop/dev-guide-optimize-sql-best-practices.md b/develop/dev-guide-optimize-sql-best-practices.md index 13d8f90c4502..d25f43257cfb 100644 --- a/develop/dev-guide-optimize-sql-best-practices.md +++ b/develop/dev-guide-optimize-sql-best-practices.md @@ -1,7 +1,7 @@ --- title: 性能调优最佳实践 summary: 介绍使用 TiDB 的性能调优最佳实践。 -aliases: ['/zh/tidb/dev/optimize-sql-best-practices'] +aliases: ['/zh/tidb/dev/optimize-sql-best-practices','/zh/tidb/stable/dev-guide-optimize-sql-best-practices/','/zh/tidb/dev/dev-guide-optimize-sql-best-practices/','/zh/tidbcloud/dev-guide-optimize-sql-best-practices/'] --- # 性能调优最佳实践 @@ -166,8 +166,8 @@ SET @@global.tidb_ddl_reorg_batch_size = 128; ## Java 数据库应用开发最佳实践 -[TiDB 最佳实践系列（五）Java 数据库应用开发指南](https://pingcap.com/zh/blog/best-practice-java)。 +[开发 Java 应用使用 TiDB 的最佳实践](/develop/java-app-best-practices.md).。 ### 推荐阅读 -- [TiDB 最佳实践系列（一）高并发写入常见热点问题及规避方法](https://pingcap.com/zh/blog/tidb-in-high-concurrency-scenarios)。 +- [TiDB 最佳实践系列（一）高并发写入常见热点问题及规避方法](https://tidb.net/blog/09d47cf8)。 diff --git a/develop/dev-guide-optimize-sql-overview.md b/develop/dev-guide-optimize-sql-overview.md index 2a4b986cf9ae..dc19a5c92b4c 100644 --- a/develop/dev-guide-optimize-sql-overview.md +++ b/develop/dev-guide-optimize-sql-overview.md @@ -1,7 +1,7 @@ --- title: 概览 summary: 介绍 TiDB 的 SQL 性能调优概览。 -aliases: ['/zh/tidb/dev/optimize-sql-overview'] +aliases: ['/zh/tidb/dev/optimize-sql-overview','/zh/tidb/stable/dev-guide-optimize-sql-overview/','/zh/tidb/dev/dev-guide-optimize-sql-overview/','/zh/tidbcloud/dev-guide-optimize-sql-overview/'] --- # 概览 @@ -29,4 +29,5 @@ aliases: ['/zh/tidb/dev/optimize-sql-overview'] ## 推荐阅读 -- [SQL 性能调优](/sql-tuning-overview.md)。 +- TiDB Cloud 文档：[SQL 调优概述](https://docs.pingcap.com/zh/tidbcloud/tidb-cloud-sql-tuning-overview/) +- TiDB 文档：[SQL 性能调优](/sql-tuning-overview.md) diff --git a/develop/dev-guide-optimize-sql.md b/develop/dev-guide-optimize-sql.md index e113681098d9..5f5645d94471 100644 --- a/develop/dev-guide-optimize-sql.md +++ b/develop/dev-guide-optimize-sql.md @@ -1,7 +1,7 @@ --- title: SQL 性能调优 summary: 介绍 TiDB 的 SQL 性能调优方案和分析办法。 -aliases: ['/zh/tidb/dev/optimize-sql'] +aliases: ['/zh/tidb/dev/optimize-sql','/zh/tidb/stable/dev-guide-optimize-sql/','/zh/tidb/dev/dev-guide-optimize-sql/','/zh/tidbcloud/dev-guide-optimize-sql/'] --- # SQL 性能调优 @@ -10,13 +10,13 @@ aliases: ['/zh/tidb/dev/optimize-sql'] ## 准备工作 -在开始之前，你可以[通过 `tiup demo` 命令导入](/develop/dev-guide-bookshop-schema-design.md#方法一通过-tiup-demo-命令行)示例数据： +在开始之前，你可以[通过 `tiup demo` 命令导入](/develop/dev-guide-bookshop-schema-design.md#本地部署的-tidb通过-tiup-demo-命令行)示例数据： ```shell tiup demo bookshop prepare --books 1000000 --host 127.0.0.1 --port 4000 ``` -或[使用 TiDB Cloud 的 Import 功能导入](/develop/dev-guide-bookshop-schema-design.md#方法二通过-tidb-cloud-import-功能)预先准备好的示例数据。 +或[使用 TiDB Cloud 的 Import 功能导入](/develop/dev-guide-bookshop-schema-design.md#tidb-cloud通过-import-功能)预先准备好的示例数据。 ## 问题：全表扫描 @@ -108,7 +108,7 @@ EXPLAIN SELECT * FROM books WHERE title = 'Marian Yost'; 从执行计划中的 **IndexLookUp_10** 可以看出，TiDB 将会通过索引 `title_idx` 来查询数据，其 `estRows` 值为 `1.27`，说明优化器估计只会扫描 `1.27` 行数据，远远小于之前全表扫的 `1000000.00` 行数据。 -**IndexLookUp_10** 执行计划的执行流程是先用 **IndexRangeScan_8** 算子通过 `title_idx` 索引获取符合条件的索引数据，然后 **TableRowIDScan_9** 再更据索引数据里面的 Row ID 回表查询相应的行数据。 +**IndexLookUp_10** 执行计划的执行流程是先用 **IndexRangeScan_8** 算子通过 `title_idx` 索引获取符合条件的索引数据，然后 **TableRowIDScan_9** 再根据索引数据里面的 Row ID 回表查询相应的行数据。 更多关于 TiDB 执行计划的内容，可以阅读[TiDB 执行计划概览](/explain-overview.md)。 diff --git a/develop/dev-guide-paginate-results.md b/develop/dev-guide-paginate-results.md index b4c70f87b22f..ccbda6af6c84 100644 --- a/develop/dev-guide-paginate-results.md +++ b/develop/dev-guide-paginate-results.md @@ -1,7 +1,7 @@ --- title: 分页查询 summary: 介绍 TiDB 的分页查询功能。 -aliases: ['/zh/tidb/dev/paginate-results'] +aliases: ['/zh/tidb/dev/paginate-results','/zh/tidb/stable/dev-guide-paginate-results/','/zh/tidb/dev/dev-guide-paginate-results/','/zh/tidbcloud/dev-guide-paginate-results/'] --- # 分页查询 @@ -309,14 +309,30 @@ ORDER BY page_num; 假如想要删除第 1 页上的所有评分记录，可以将上表第 1 页所对应的 `start_key` 和 `end_key` 填入 SQL 语句当中。 ```sql -SELECT * FROM ratings -WHERE - (book_id > 268996 AND book_id < 140982742) - OR ( - book_id = 268996 AND user_id >= 92104804 +SELECT * +FROM ratings +WHERE ( + 268996 = 140982742 + AND book_id = 268996 + AND user_id >= 92104804 + AND user_id <= 374645100 ) OR ( - book_id = 140982742 AND user_id <= 374645100 + 268996 != 140982742 + AND ( + ( + book_id > 268996 + AND book_id < 140982742 + ) + OR ( + book_id = 268996 + AND user_id >= 92104804 + ) + OR ( + book_id = 140982742 + AND user_id <= 374645100 + ) + ) ) ORDER BY book_id, user_id; ``` diff --git a/develop/dev-guide-playground-gitpod.md b/develop/dev-guide-playground-gitpod.md index e6ed35e5bd73..77fb3ea4a97f 100644 --- a/develop/dev-guide-playground-gitpod.md +++ b/develop/dev-guide-playground-gitpod.md @@ -1,6 +1,7 @@ --- title: Gitpod summary: Gitpod 是一个开源 Kubernetes 应用程序，可在浏览器中获得完整的开发环境，并立即编写代码。它能够为云中的每个任务提供全新的自动化开发环境，无需本地配置。Gitpod 提供了完整的、自动化的、预配置的云原生开发环境，让你可以直接在浏览器中开发、运行、测试代码。 +aliases: ['/zh/tidb/stable/dev-guide-playground-gitpod/','/zh/tidb/dev/dev-guide-playground-gitpod/','/zh/tidbcloud/dev-guide-playground-gitpod/'] --- @@ -25,7 +26,7 @@ Gitpod 是一个开源 Kubernetes 应用程序（GitHub 仓库地址 @@ -140,7 +140,7 @@ try (Connection connection = ds.getConnection()) { ### 插入示例 -还是使用 [books 表](/develop/dev-guide-bookshop-schema-design.md#books-表) 为例，需要插入一个 `title` 为 `TiDB Developer Guide`, `type` 为 `Science & Technology`, `stock` 为 `100`, `price` 为 `0.0`, `published_at` 为 `插入的当前时间` 的书籍信息。需要注意的是，`books` 表的主键包含 `AUTO_RANDOM` 属性，无需指定它。如果你对插入数据还不了解，可以在[插入数据](/develop/dev-guide-insert-data.md)一节了解更多数据插入的相关信息。 +还是使用 [books 表](/develop/dev-guide-bookshop-schema-design.md#books-表)为例，需要插入一个 `title` 为 `TiDB Developer Guide`, `type` 为 `Science & Technology`, `stock` 为 `100`, `price` 为 `0.0`, `published_at` 为 `插入的当前时间` 的书籍信息。需要注意的是，`books` 表的主键包含 `AUTO_RANDOM` 属性，无需指定它。如果你对插入数据还不了解，可以在[插入数据](/develop/dev-guide-insert-data.md)一节了解更多数据插入的相关信息。 diff --git a/develop/dev-guide-proxysql-integration.md b/develop/dev-guide-proxysql-integration.md index 93f1b9d63cbe..84cc07b2ad43 100644 --- a/develop/dev-guide-proxysql-integration.md +++ b/develop/dev-guide-proxysql-integration.md @@ -1,6 +1,7 @@ --- title: ProxySQL 集成指南 summary: 了解如何将本地部署的 TiDB 或 TiDB Cloud 集群与 ProxySQL 集成。 +aliases: ['/zh/tidb/stable/dev-guide-proxysql-integration/','/zh/tidb/dev/dev-guide-proxysql-integration/','/zh/tidbcloud/dev-guide-proxysql-integration/'] --- # ProxySQL 集成指南 @@ -10,7 +11,7 @@ summary: 了解如何将本地部署的 TiDB 或 TiDB Cloud 集群与 ProxySQL 关于 TiDB 和 ProxySQL 的更多信息，请参考以下文档： - [TiDB Cloud](https://docs.pingcap.com/tidbcloud) -- [TiDB 开发者指南](/develop/dev-guide-overview.md) +- [TiDB 开发者指南](/develop/_index.md) - [ProxySQL 文档](https://proxysql.com/documentation/) ## 什么是 ProxySQL？ @@ -119,11 +120,11 @@ systemctl start docker ### 选项 1: 集成 TiDB Cloud 与 ProxySQL -在这个集成中，你将使用 [ProxySQL Docker 镜像](https://hub.docker.com/r/proxysql/proxysql)以及 TiDB Cloud Serverless 集群。下面的步骤将在端口 `16033` 上设置 ProxySQL，请确保此端口可用。 +在这个集成中，你将使用 [ProxySQL Docker 镜像](https://hub.docker.com/r/proxysql/proxysql)以及 {{{ .starter }}} 集群。下面的步骤将在端口 `16033` 上设置 ProxySQL，请确保此端口可用。 -#### 步骤 1. 创建一个 TiDB Cloud Serverless 集群 +#### 步骤 1. 创建一个 {{{ .starter }}} 集群 -1. 参考[创建一个 TiDB Cloud Serverless 集群](https://docs.pingcap.com/tidbcloud/tidb-cloud-quickstart#step-1-create-a-tidb-cluster)文档。记住为集群设置的 root 密码。 +1. 参考[创建一个 {{{ .starter }}} 集群](https://docs.pingcap.com/tidbcloud/tidb-cloud-quickstart#step-1-create-a-tidb-cluster)文档。记住为集群设置的 root 密码。 2. 获取集群的 `hostname`、`port` 及 `username` 供后续使用。 1. 在 [Clusters](https://tidbcloud.com/console/clusters) 页面，点击你的集群名称，进入集群概览页面。 @@ -327,12 +328,12 @@ systemctl start docker > > 1. 使用集群的用户名和密码添加一个 ProxySQL 用户。 > 2. 将该用户分配给监控账户。 - > 3. 将你的 TiDB Cloud Serverless 集群添加到主机列表中。 - > 4. 在 ProxySQL 和 TiDB Cloud Serverless 集群之间启用安全连接。 + > 3. 将你的 {{{ .starter }}} 集群添加到主机列表中。 + > 4. 在 ProxySQL 和 {{{ .starter }}} 集群之间启用安全连接。 > > 为了更好地理解此处的配置流程，强烈建议查看 `proxysql-prepare.sql` 文件。关于 ProxySQL 配置的更多信息，参考 [ProxySQL 文档](https://proxysql.com/documentation/proxysql-configuration/)。 - 下面是一个输出示例。输出中显示集群的主机名，这意味着 ProxySQL 和 TiDB Cloud Serverless 集群之间的连接建立成功。 + 下面是一个输出示例。输出中显示集群的主机名，这意味着 ProxySQL 和 {{{ .starter }}} 集群之间的连接建立成功。 ``` *************************** 1. row *************************** @@ -388,7 +389,7 @@ systemctl start docker SELECT VERSION(); ``` - 如果输出了 TiDB 的版本信息，则表示你已经成功通过 ProxySQL 连接到 TiDB Cloud Serverless 集群。如需退出 MySQL 客户端，输入 `quit` 并按下 Enter 键。 + 如果输出了 TiDB 的版本信息，则表示你已经成功通过 ProxySQL 连接到 {{{ .starter }}} 集群。如需退出 MySQL 客户端，输入 `quit` 并按下 Enter 键。 > **注意：** > diff --git a/develop/dev-guide-sample-application-aws-lambda.md b/develop/dev-guide-sample-application-aws-lambda.md index 4916d71c6134..9bd75aae199e 100644 --- a/develop/dev-guide-sample-application-aws-lambda.md +++ b/develop/dev-guide-sample-application-aws-lambda.md @@ -1,6 +1,7 @@ --- title: 在 AWS Lambda 函数中使用 mysql2 连接到 TiDB summary: 本文介绍如何在 AWS Lambda 函数中使用 TiDB 和 mysql2 构建一个 CRUD 应用程序，并给出了简单示例代码片段。 +aliases: ['/zh/tidb/stable/dev-guide-sample-application-aws-lambda/','/zh/tidb/dev/dev-guide-sample-application-aws-lambda/','/zh/tidbcloud/dev-guide-sample-application-aws-lambda/'] --- # 在 AWS Lambda 函数中使用 mysql2 连接到 TiDB @@ -16,7 +17,7 @@ TiDB 是一个兼容 MySQL 的数据库。[AWS Lambda 函数](https://aws.amazon > **Note** > -> 本文档适用于 TiDB Cloud Serverless 和本地部署的 TiDB。 +> 本文档适用于 {{{ .starter }}}、{{{ .essential }}} 和本地部署的 TiDB。 ## 前置需求 @@ -31,8 +32,8 @@ TiDB 是一个兼容 MySQL 的数据库。[AWS Lambda 函数](https://aws.amazon 如果你还没有 TiDB 集群，可以按照以下方式创建： -- （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)，创建你自己的 TiDB Cloud 集群。 -- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 +- （推荐方式）参考[创建 {{{ .starter }}} 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)，创建你自己的 TiDB Cloud 集群。 +- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 如果你还没有 AWS 账户或用户，可以按照 [Lambda 入门](https://docs.aws.amazon.com/zh_cn/lambda/latest/dg/getting-started.html)文档中的步骤来创建它们。 @@ -67,9 +68,9 @@ npm install -
+
-1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 TiDB Cloud Serverless 集群，进入集群的 **Overview** 页面。 +1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 {{{ .starter }}} 集群，进入集群的 **Overview** 页面。 2. 点击右上角的 **Connect** 按钮，将会弹出连接对话框。 @@ -340,7 +341,7 @@ console.log(rsh.affectedRows); - 为了避免 SQL 注入的风险，推荐使用[预处理语句](https://github.com/sidorares/node-mysql2#using-prepared-statements)执行 SQL。 - 在不涉及大量复杂 SQL 语句的场景下，推荐使用 ORM 框架（例如：[Sequelize](https://sequelize.org/)、[TypeORM](https://typeorm.io/) 或 [Prisma](https://www.prisma.io/)）来提升你的开发效率。 - 如需为你的应用程序构建一个 RESTful API，建议[将 AWS Lambda 与 Amazon API Gateway 结合使用](https://docs.aws.amazon.com/zh_cn/lambda/latest/dg/services-apigateway.html)。 -- 关于使用 TiDB Cloud Serverless 和 AWS Lambda 设计高性能应用程序的更多信息，可以参考[这篇博客](https://aws.amazon.com/blogs/apn/designing-high-performance-applications-using-serverless-tidb-cloud-and-aws-lambda/)。 +- 关于使用 {{{ .starter }}} 和 AWS Lambda 设计高性能应用程序的更多信息，可以参考[这篇博客](https://aws.amazon.com/blogs/apn/designing-high-performance-applications-using-serverless-tidb-cloud-and-aws-lambda/)。 ## 下一步 @@ -348,8 +349,10 @@ console.log(rsh.affectedRows); - 关于 mysql2 的更多使用方法，可以参考 [mysql2 的官方文档](https://sidorares.github.io/node-mysql2/zh-CN/docs)。 - 关于 AWS Lambda 的更多使用方法，可以参考 [AWS Lambda 开发者指南](https://docs.aws.amazon.com/zh_cn/lambda/latest/dg/welcome.html)。 - 你可以继续阅读开发者文档的其它章节来获取更多 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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 ## 需要帮助? -如果在开发的过程中遇到问题，可以在 [AskTUG](https://asktug.com/?utm_source=docs-cn-dev-guide) 上进行提问，或从 PingCAP 官方或 TiDB 社区[获取支持](/support.md)。 +- 在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [提交 TiDB 工单](/support.md) diff --git a/develop/dev-guide-sample-application-cs.md b/develop/dev-guide-sample-application-cs.md new file mode 100644 index 000000000000..7018a92f1c61 --- /dev/null +++ b/develop/dev-guide-sample-application-cs.md @@ -0,0 +1,124 @@ +--- +title: 使用 C# 连接 TiDB +summary: 了解如何使用 C# 连接 TiDB。本教程提供了与 TiDB 交互的 C# 代码示例。 +aliases: ['/zh/tidb/stable/dev-guide-sample-application-cs/','/zh/tidb/dev/dev-guide-sample-application-cs/','/zh/tidbcloud/dev-guide-sample-application-cs/'] +--- + +# 使用 C\# 连接 TiDB + +C#（发音为 "C-Sharp"）是 .NET 技术体系中的一种编程语言，由微软开发。其他 .NET 语言还包括 VB.NET 和 F#。在本文档中，你将使用 C# 和 MySQL Connector/NET，通过 MySQL 协议将 C# 应用程序连接到 TiDB。这种连接方式可行，是因为 TiDB [与 MySQL 高度兼容](/mysql-compatibility.md)。 + +虽然 .NET 通常用于 Windows 操作系统，但它同样适用于 macOS 和 Linux 系统。在不同平台上，相关命令和代码基本一致，仅在提示符和文件路径上存在细微差别。 + +## 前提条件 + +- 下载并安装 [.NET 9.0 SDK](https://dotnet.microsoft.com/en-us/download)。 +- 本教程使用 `dotnet` 命令行工具，你也可以使用 Visual Studio Code IDE 编写和运行 C# 代码。 +- 你需要有一个可用的 TiDB 实例。可以使用 [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#starter) 或 [TiDB Cloud Dedicated](https://docs.pingcap.com/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated) 集群，或自托管的 TiDB 集群（如通过 `tiup playground` 启动的集群）。 + +## 第 1 步：创建控制台项目 + +使用 `console` 模板创建一个新项目。以下命令会生成一个名为 `tidb_cs` 的新目录。在运行以下命令前，请先切换到希望创建该目录的位置，或指定完整路径。 + +``` +$ dotnet new console -o tidb_cs +The template "Console App" was created successfully. + +Processing post-creation actions... +Restoring /home/dvaneeden/tidb_cs/tidb_cs.csproj: +Restore succeeded. +``` + +## 第 2 步：添加 MySql.Data 包 + +.NET 的包管理器是 NuGet。MySQL Connector/NET 在 NuGet 上的包名为 [MySql.Data](https://www.nuget.org/packages/MySql.Data)，它为 .NET 应用提供对 MySQL 协议的支持。如果你未指定版本，NuGet 会安装最新稳定版（如 9.3.0）。 + +```shell +$ cd tidb_cs +$ dotnet add package MySql.Data + +Build succeeded in 1.0s +info : X.509 certificate chain validation will use the system certificate bundle at '/etc/pki/ca-trust/extracted/pem/objsign-ca-bundle.pem'。 +info : X.509 certificate chain validation will use the fallback certificate bundle at '/usr/lib64/dotnet/sdk/9.0.106/trustedroots/timestampctl.pem'。 +info : Adding PackageReference for package 'MySql.Data' into project '/home/dvaneeden/tidb_cs/tidb_cs.csproj'。 +info : GET https://api.nuget.org/v3/registration5-gz-semver2/mysql.data/index.json +info : OK https://api.nuget.org/v3/registration5-gz-semver2/mysql.data/index.json 133ms +info : Restoring packages for /home/dvaneeden/tidb_cs/tidb_cs.csproj... +info : GET https://api.nuget.org/v3/vulnerabilities/index.json +info : OK https://api.nuget.org/v3/vulnerabilities/index.json 98ms +info : GET https://api.nuget.org/v3-vulnerabilities/2025.06.18.05.40.02/vulnerability.base.json +info : GET https://api.nuget.org/v3-vulnerabilities/2025.06.18.05.40.02/2025.06.19.11.40.05/vulnerability.update.json +info : OK https://api.nuget.org/v3-vulnerabilities/2025.06.18.05.40.02/vulnerability.base.json 32ms +info : OK https://api.nuget.org/v3-vulnerabilities/2025.06.18.05.40.02/2025.06.19.11.40.05/vulnerability.update.json 64ms +info : Package 'MySql.Data' is compatible with all the specified frameworks in project '/home/dvaneeden/tidb_cs/tidb_cs.csproj'。 +info : PackageReference for package 'MySql.Data' version '9.3.0' added to file '/home/dvaneeden/tidb_cs/tidb_cs.csproj'。 +info : Generating MSBuild file /home/dvaneeden/tidb_cs/obj/tidb_cs.csproj.nuget.g.targets。 +info : Writing assets file to disk. Path: /home/dvaneeden/tidb_cs/obj/project.assets.json +log : Restored /home/dvaneeden/tidb_cs/tidb_cs.csproj (in 551 ms)。 +``` + +## 第 3 步：更新代码 + +将 `Program.cs` 中的 "Hello World" 示例替换为以下代码： + +```cs +using System; +using MySql.Data.MySqlClient; +public class Tutorial1 +{ + public static void Main() + { + // 生产环境请务必使用强密码和唯一密码。 + string connStr = "server=127.0.0.1;user=root;database=test;port=4000;AllowUserVariables=true"; + MySqlConnection conn = new MySqlConnection(connStr); + try + { + Console.WriteLine("Connecting to TiDB...\n"); + conn.Open(); + } + catch (Exception ex) + { + Console.WriteLine(ex.ToString()); + Environment.Exit(1); + } + + Console.WriteLine("Connected to: " + conn.ServerVersion); + + MySqlCommand cmd = new MySqlCommand("SELECT TIDB_VERSION()", conn); + + MySqlDataReader rdr = cmd.ExecuteReader(); + + rdr.Read(); + Console.WriteLine("\nVersion details:\n" + rdr[0]); + rdr.Close(); + + conn.Close(); + Console.WriteLine("Done."); + } +} +``` + +该代码会连接到指定 IP 和端口的 TiDB 实例。如果你使用的是 TiDB Cloud，请将连接字符串中的参数（如主机名、端口、用户名和密码）替换为 [TiDB Cloud 控制台](https://tidbcloud.com/)提供的信息。 + +代码首先会连接数据库，并打印其版本信息，然后执行 [`TIDB_VERSION()`](/functions-and-operators/tidb-functions.md#tidb_version) 查询以获取更详细的版本信息，最后输出结果。 + +## 第 4 步：运行程序 + +``` +$ dotnet run +Connecting to TiDB... + +Connected to: 8.0.11-TiDB-v{{{ .tidb-version }}} + +Version details: +Release Version: v{{{ .tidb-version }}} +Edition: Community +Git Commit Hash: f43a13324440f92209e2a9f04c0bbe9cf763978d +Git Branch: HEAD +UTC Build Time: {{{ .tidb-release-date }}} 03:30:55 +GoVersion: go1.23.8 +Race Enabled: false +Check Table Before Drop: false +Store: tikv +Done. +``` diff --git a/develop/dev-guide-sample-application-golang-gorm.md b/develop/dev-guide-sample-application-golang-gorm.md index 76220ef177ca..d1d7e2149424 100644 --- a/develop/dev-guide-sample-application-golang-gorm.md +++ b/develop/dev-guide-sample-application-golang-gorm.md @@ -1,6 +1,7 @@ --- title: 使用 GORM 连接到 TiDB summary: 了解如何使用 GORM 连接到 TiDB。本文提供了使用 GORM 与 TiDB 交互的 Golang 示例代码片段。 +aliases: ['/zh/tidb/stable/dev-guide-sample-application-golang-gorm/','/zh/tidb/dev/dev-guide-sample-application-golang-gorm/','/zh/tidbcloud/dev-guide-sample-application-golang-gorm/'] --- # 使用 GORM 连接到 TiDB @@ -15,15 +16,15 @@ TiDB 是一个兼容 MySQL 的数据库。[GORM](https://gorm.io/index.html) 是 > **注意** > -> 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 +> 本文档适用于 {{{ .starter }}}、{{{ .essential }}}、TiDB Cloud Dedicated 和本地部署的 TiDB。 ## 前置需求 - 推荐 [Go](https://go.dev/) **1.20** 及以上版本。 - [Git](https://git-scm.com/downloads)。 - TiDB 集群。如果你还没有 TiDB 集群，可以按照以下方式创建： - - （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)，创建你自己的 TiDB Cloud 集群。 - - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 + - （推荐方式）参考[创建 {{{ .starter }}} 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)，创建你自己的 TiDB Cloud 集群。 + - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 ## 运行代码并连接到 TiDB @@ -44,9 +45,9 @@ cd tidb-golang-gorm-quickstart -
+
-1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 TiDB Cloud Serverless 集群，进入集群的 **Overview** 页面。 +1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 {{{ .starter }}} 集群，进入集群的 **Overview** 页面。 2. 点击右上角的 **Connect** 按钮，将会弹出连接对话框。 @@ -86,7 +87,7 @@ cd tidb-golang-gorm-quickstart 注意替换 `{}` 中的占位符为连接对话框中获得的值。 - TiDB Cloud Serverless 要求使用 TLS (SSL) connection，因此 `USE_SSL` 的值应为 `true`。 + {{{ .starter }}} 要求使用 TLS (SSL) connection，因此 `USE_SSL` 的值应为 `true`。 7. 保存 `.env` 文件。 @@ -188,7 +189,7 @@ func createDB() *gorm.DB { } ``` -在使用该函数时，你需要将 `${tidb_host}`、`${tidb_port}`、`${tidb_user}`、`${tidb_password}`、`${tidb_db_name}` 等替换为你的 TiDB 集群的实际值。因为 TiDB Cloud Serverless 要求使用 TLS (SSL) connection，因此在连接到 TiDB Cloud Serverless 时 `${use_ssl}` 的值应为 `true`。 +在使用该函数时，你需要将 `${tidb_host}`、`${tidb_port}`、`${tidb_user}`、`${tidb_password}`、`${tidb_db_name}` 等替换为你的 TiDB 集群的实际值。因为 {{{ .starter }}} 要求使用 TLS (SSL) connection，因此在连接到 {{{ .starter }}} 时 `${use_ssl}` 的值应为 `true`。 ### 插入数据 @@ -226,10 +227,12 @@ db.Delete(&Player{ID: "id"}) ## 下一步 -- 关于 GORM 的更多使用方法，可以参考 [GORM 官方文档](https://gorm.io/zh_CN/docs/index.html) 及 GORM 官方文档中的 [TiDB 章节](https://gorm.io/zh_CN/docs/connecting_to_the_database.html#TiDB)。 +- 关于 GORM 的更多使用方法，可以参考 [GORM 官方文档](https://gorm.io/zh_CN/docs/index.html)及 GORM 官方文档中的 [TiDB 章节](https://gorm.io/zh_CN/docs/connecting_to_the_database.html#TiDB)。 - 你可以继续阅读开发者文档，以获取更多关于 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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 ## 需要帮助? -如果在开发的过程中遇到问题，可以在 [AskTUG](https://asktug.com/?utm_source=docs-cn-dev-guide) 上进行提问，寻求帮助。 +- 在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [提交 TiDB 工单](/support.md) \ No newline at end of file diff --git a/develop/dev-guide-sample-application-golang-sql-driver.md b/develop/dev-guide-sample-application-golang-sql-driver.md index 8920e114f582..966ad438f29a 100644 --- a/develop/dev-guide-sample-application-golang-sql-driver.md +++ b/develop/dev-guide-sample-application-golang-sql-driver.md @@ -1,7 +1,7 @@ --- title: 使用 Go-MySQL-Driver 连接到 TiDB summary: 了解如何使用 Go-MySQL-Driver 连接到 TiDB。本文提供了使用 Go-MySQL-Driver 与 TiDB 交互的 Golang 示例代码片段。 -aliases: ['/zh/tidb/dev/dev-guide-sample-application-golang'] +aliases: ['/zh/tidb/dev/dev-guide-sample-application-golang','/zh/tidb/stable/dev-guide-sample-application-golang-sql-driver/','/zh/tidb/dev/dev-guide-sample-application-golang-sql-driver/','/zh/tidbcloud/dev-guide-sample-application-golang-sql-driver/'] --- # 使用 Go-MySQL-Driver 连接到 TiDB @@ -16,15 +16,15 @@ TiDB 是一个兼容 MySQL 的数据库。[Go-MySQL-Driver](https://github.com/g > **注意** > -> 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 +> 本文档适用于 {{{ .starter }}}、{{{ .essential }}}、TiDB Cloud Dedicated 和本地部署的 TiDB。 ## 前置需求 - 推荐 [Go](https://go.dev/) **1.20** 及以上版本。 - [Git](https://git-scm.com/downloads)。 - TiDB 集群。如果你还没有 TiDB 集群，可以按照以下方式创建： - - （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)，创建你自己的 TiDB Cloud 集群。 - - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 + - （推荐方式）参考[创建 {{{ .starter }}} 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)，创建你自己的 TiDB Cloud 集群。 + - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 ## 运行代码并连接到 TiDB @@ -45,9 +45,9 @@ cd tidb-golang-sql-driver-quickstart -
+
-1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 TiDB Cloud Serverless 集群，进入集群的 **Overview** 页面。 +1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 {{{ .starter }}} 集群，进入集群的 **Overview** 页面。 2. 点击右上角的 **Connect** 按钮，将会弹出连接对话框。 @@ -87,7 +87,7 @@ cd tidb-golang-sql-driver-quickstart 注意替换 `{}` 中的占位符为连接对话框中获得的值。 - TiDB Cloud Serverless 要求使用 TLS (SSL) connection，因此 `USE_SSL` 的值应为 `true`。 + {{{ .starter }}} 要求使用 TLS (SSL) connection，因此 `USE_SSL` 的值应为 `true`。 7. 保存 `.env` 文件。 @@ -187,7 +187,7 @@ func openDB(driverName string, runnable func(db *sql.DB)) { } ``` -在使用该函数时，你需要将 `${tidb_host}`、`${tidb_port}`、`${tidb_user}`、`${tidb_password}`、`${tidb_db_name}` 等替换为你的 TiDB 集群的实际值。因为 TiDB Cloud Serverless 要求使用 TLS (SSL) connection，因此在连接到 TiDB Cloud Serverless 时 `${use_ssl}` 的值应为 `true`。 +在使用该函数时，你需要将 `${tidb_host}`、`${tidb_port}`、`${tidb_user}`、`${tidb_password}`、`${tidb_db_name}` 等替换为你的 TiDB 集群的实际值。因为 {{{ .starter }}} 要求使用 TLS (SSL) connection，因此在连接到 {{{ .starter }}} 时 `${use_ssl}` 的值应为 `true`。 ### 插入数据 @@ -278,8 +278,10 @@ Golang 驱动程序提供对数据库的底层访问，但要求开发者： - 关于 Go-MySQL-Driver 的更多使用方法，可以参考 [Go-MySQL-Driver 官方文档](https://github.com/go-sql-driver/mysql/blob/master/README.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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 ## 需要帮助? -如果在开发的过程中遇到问题，可以在 [AskTUG](https://asktug.com/?utm_source=docs-cn-dev-guide) 上进行提问，寻求帮助。 +- 在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [提交 TiDB 工单](/support.md) \ No newline at end of file diff --git a/develop/dev-guide-sample-application-java-hibernate.md b/develop/dev-guide-sample-application-java-hibernate.md index 2be8e1145baf..d00527d11110 100644 --- a/develop/dev-guide-sample-application-java-hibernate.md +++ b/develop/dev-guide-sample-application-java-hibernate.md @@ -1,11 +1,12 @@ --- title: 使用 Hibernate 连接到 TiDB summary: 了解如何使用 Hibernate 连接到 TiDB。本文提供了使用 Hibernate 与 TiDB 交互的 Java 示例代码片段。 +aliases: ['/zh/tidb/stable/dev-guide-sample-application-java-hibernate/','/zh/tidb/dev/dev-guide-sample-application-java-hibernate/','/zh/tidbcloud/dev-guide-sample-application-java-hibernate/'] --- # 使用 Hibernate 连接到 TiDB -TiDB 是一个兼容 MySQL 的数据库。[Hibernate](https://hibernate.org/orm/) 是当前比较流行的开源 Java 应用持久层框架，且 Hibernate 在版本 `6.0.0.Beta2` 及以上支持了 TiDB 方言，完美适配了 TiDB 的特性。 +TiDB 是一个兼容 MySQL 的数据库。[Hibernate](https://hibernate.org/orm/) 是当前比较流行的开源 Java 应用持久层框架。由于 TiDB 与 MySQL 高度兼容，建议使用 `org.hibernate.dialect.MySQLDialect` 作为 Hibernate 的方言 (Dialect)，以获得更好的长期兼容性。或者，也可以使用 TiDB 特定的方言 (`org.hibernate.community.dialect.TiDBDialect`)，该方言位于 [Hibernate community dialects](https://github.com/hibernate/hibernate-orm/tree/main/hibernate-community-dialects) 项目中，但该项目并非由 PingCAP 维护。如果你在使用 `MySQLDialect` 时遇到兼容性问题，可以在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues)。 本文档将展示如何使用 TiDB 和 Hibernate 来完成以下任务： @@ -15,7 +16,7 @@ TiDB 是一个兼容 MySQL 的数据库。[Hibernate](https://hibernate.org/orm/ > **注意** > -> 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 +> 本文档适用于 {{{ .starter }}}、{{{ .essential }}}、TiDB Cloud Dedicated 和本地部署的 TiDB。 ## 前置需求 @@ -23,8 +24,8 @@ TiDB 是一个兼容 MySQL 的数据库。[Hibernate](https://hibernate.org/orm/ - [Maven](https://maven.apache.org/install.html) **3.8** 及以上版本。 - [Git](https://git-scm.com/downloads)。 - TiDB 集群。如果你还没有 TiDB 集群，可以按照以下方式创建： - - （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)，创建你自己的 TiDB Cloud 集群。 - - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 + - （推荐方式）参考[创建 {{{ .starter }}} 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)，创建你自己的 TiDB Cloud 集群。 + - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 ## 运行代码并连接到 TiDB @@ -45,9 +46,9 @@ cd tidb-java-hibernate-quickstart -
+
-1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 TiDB Cloud Serverless 集群，进入集群的 **Overview** 页面。 +1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 {{{ .starter }}} 集群，进入集群的 **Overview** 页面。 2. 点击右上角的 **Connect** 按钮，将会弹出连接对话框。 @@ -87,7 +88,7 @@ cd tidb-java-hibernate-quickstart 注意替换 `{}` 中的占位符为连接对话框中获得的值。 - TiDB Cloud Serverless 要求使用 TLS (SSL) connection，因此 `USE_SSL` 的值应为 `true`。 + {{{ .starter }}} 要求使用 TLS (SSL) connection，因此 `USE_SSL` 的值应为 `true`。 7. 保存 `env.sh` 文件。 @@ -185,7 +186,7 @@ cd tidb-java-hibernate-quickstart com.mysql.cj.jdbc.Driver - org.hibernate.dialect.TiDBDialect + org.hibernate.dialect.MySQLDialect ${tidb_jdbc_url} ${tidb_user} ${tidb_password} @@ -245,13 +246,51 @@ try (Session session = sessionFactory.openSession()) { 更多信息参考[删除数据](/develop/dev-guide-delete-data.md)。 +## 与 `MySQLDialect` 的兼容性 + +在 TiDB 中使用 `MySQLDialect` 时，请注意以下行为： + +### `SERIALIZABLE` 隔离级别 + +如果应用尝试将事务隔离级别设置为 `SERIALIZABLE`，TiDB 会返回如下错误： + +``` +The isolation level 'SERIALIZABLE' is not supported. Set tidb_skip_isolation_level_check=1 to skip this error +``` + +要避免该错误，请在服务端设置以下 TiDB 系统变量： + +```sql +SET GLOBAL tidb_skip_isolation_level_check=1; +``` + +启用该变量后，TiDB 会接受请求中指定 `SERIALIZABLE` 而不返回错误。TiDB 内部仍然使用 `REPEATABLE-READ`，这是 TiDB 所支持的最强事务隔离级别。更多信息，请参见 [`tidb_skip_isolation_level_check`](/system-variables.md#tidb_skip_isolation_level_check)。 + +> **注意：** +> +> 社区版的 `TiDBDialect` 会自动处理此行为，通过跳过依赖 `SERIALIZABLE` 隔离级别的相关特性来避免问题。 + +### `CHECK` 约束 + +Hibernate 的 [`@Check`](https://docs.hibernate.org/orm/6.5/javadocs/org/hibernate/annotations/Check.html) 注解会生成 DDL `CHECK` 约束。[MySQL 8.0.16 及之后版本](https://dev.mysql.com/doc/refman/8.0/en/create-table-check-constraints.html) 默认会强制执行这些约束。但在 TiDB 中，如果没有显式启用，则不会强制执行。 + +要在 TiDB 中启用 `CHECK` 约束的强制执行，请设置以下系统变量： + +```sql +SET GLOBAL tidb_enable_check_constraint=ON; +``` + +如果未启用该设置，TiDB 会接受 `CHECK` 约束的语法但不会强制执行，这可能导致数据完整性问题。更多信息，请参见 [`CHECK` 约束](/constraints.md#check-约束)。 + ## 下一步 - 关于 Hibernate 的更多使用方法，可以参考 [Hibernate 官方文档](https://hibernate.org/orm/documentation)。 - 你可以继续阅读开发者文档，以获取更多关于 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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 -- 我们还额外提供针对 Java 开发者的课程：[使用 Connector/J - TiDB v6](https://learn.pingcap.com/learner/course/840002/?utm_source=docs-cn-dev-guide) 及[在 TiDB 上开发应用的最佳实践 - TiDB v6](https://learn.pingcap.com/learner/course/780002/?utm_source=docs-cn-dev-guide)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 +- 我们还额外提供针对 Java 开发者的课程：[使用 Connector/J - TiDB v6](https://learn.pingcap.cn/learner/course/840002?utm_source=docs-cn-dev-guide) 及[在 TiDB 上开发应用的最佳实践 - TiDB v6](https://learn.pingcap.cn/learner/course/780002?utm_source=docs-cn-dev-guide)。 ## 需要帮助? -如果在开发的过程中遇到问题，可以在 [AskTUG](https://asktug.com/?utm_source=docs-cn-dev-guide) 上进行提问，寻求帮助。 +- 在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [提交 TiDB 工单](/support.md) diff --git a/develop/dev-guide-sample-application-java-jdbc.md b/develop/dev-guide-sample-application-java-jdbc.md index 6e43b0d65882..4c72de95d118 100644 --- a/develop/dev-guide-sample-application-java-jdbc.md +++ b/develop/dev-guide-sample-application-java-jdbc.md @@ -1,7 +1,7 @@ --- title: 使用 JDBC 连接到 TiDB summary: 了解如何使用 JDBC 连接到 TiDB。本文提供了使用 JDBC 与 TiDB 交互的 Java 示例代码片段。 -aliases: ['/zh/tidb/dev/sample-application-java','/zh/tidb/dev/dev-guide-sample-application-java'] +aliases: ['/zh/tidb/dev/sample-application-java','/zh/tidb/dev/dev-guide-sample-application-java','/zh/tidb/stable/dev-guide-sample-application-java-jdbc/','/zh/tidb/dev/dev-guide-sample-application-java-jdbc/','/zh/tidbcloud/dev-guide-sample-application-java-jdbc/'] --- # 使用 JDBC 连接到 TiDB @@ -16,7 +16,8 @@ TiDB 是一个兼容 MySQL 的数据库。JDBC 是 Java 的数据访问 API。[M > **注意** > -> 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 +> - 本文档适用于 {{{ .starter }}}、{{{ .essential }}}、TiDB Cloud Dedicated 和本地部署的 TiDB。 +> - 从 TiDB v7.4 起，如果 JDBC URL 中未配置 `connectionCollation`，且 `characterEncoding` 未配置或配置为 `UTF-8`，JDBC 连接所使用的排序规则取决于 JDBC 驱动版本。详情请参考 [JDBC 连接所使用的排序规则](/faq/sql-faq.md#jdbc-连接所使用的排序规则)。 ## 前置需求 @@ -24,8 +25,8 @@ TiDB 是一个兼容 MySQL 的数据库。JDBC 是 Java 的数据访问 API。[M - [Maven](https://maven.apache.org/install.html) **3.8** 及以上版本。 - [Git](https://git-scm.com/downloads)。 - TiDB 集群。如果你还没有 TiDB 集群，可以按照以下方式创建： - - （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)，创建你自己的 TiDB Cloud 集群。 - - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 + - （推荐方式）参考[创建 {{{ .starter }}} 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)，创建你自己的 TiDB Cloud 集群。 + - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 ## 运行代码并连接到 TiDB @@ -46,9 +47,9 @@ cd tidb-java-jdbc-quickstart -
+
-1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 TiDB Cloud Serverless 集群，进入集群的 **Overview** 页面。 +1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 {{{ .starter }}} 集群，进入集群的 **Overview** 页面。 2. 点击右上角的 **Connect** 按钮，将会弹出连接对话框。 @@ -88,7 +89,7 @@ cd tidb-java-jdbc-quickstart 注意替换 `{}` 中的占位符为连接对话框中获得的值。 - TiDB Cloud Serverless 要求使用 TLS (SSL) connection，因此 `USE_SSL` 的值应为 `true`。 + {{{ .starter }}} 要求使用 TLS (SSL) connection，因此 `USE_SSL` 的值应为 `true`。 7. 保存 `env.sh` 文件。 @@ -280,13 +281,26 @@ Java 驱动程序提供对数据库的底层访问，但要求开发者： - 减少管理连接和事务的[模板代码](https://en.wikipedia.org/wiki/Boilerplate_code) - 使用数据对象代替大量 SQL 语句来操作数据 +### MySQL 兼容性 + +在 MySQL 中，当写入 `DECIMAL` 类型的数据时，如果小数位数超过字段定义的小数位数，无论超出多少，都会自动截断多余的位数并成功插入。 + +在 TiDB v8.5.3 及之前版本中： + +- 如果小数位数超过字段定义的小数位数但未超过 72 位，同样会自动截断多余的位数并成功插入。 +- 如果小数位数超过 72 位，写入会失败并报错。 + +从 TiDB v8.5.4 开始，TiDB 的行为和 MySQL 保持一致：无论小数位数超过多少，都会自动截断多余的位数并成功插入。 + ## 下一步 - 关于 MySQL Connector/J 的更多使用方法，可以参考 [MySQL Connector/J 官方文档](https://dev.mysql.com/doc/connector-j/en/)。 - 你可以继续阅读开发者文档，以获取更多关于 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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 -- 我们还额外提供针对 Java 开发者的课程：[使用 Connector/J - TiDB v6](https://learn.pingcap.com/learner/course/840002/?utm_source=docs-cn-dev-guide) 及[在 TiDB 上开发应用的最佳实践 - TiDB v6](https://learn.pingcap.com/learner/course/780002/?utm_source=docs-cn-dev-guide)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 +- 我们还额外提供针对 Java 开发者的课程：[使用 Connector/J - TiDB v6](https://learn.pingcap.cn/learner/course/840002?utm_source=docs-cn-dev-guide) 及[在 TiDB 上开发应用的最佳实践 - TiDB v6](https://learn.pingcap.cn/learner/course/780002?utm_source=docs-cn-dev-guide)。 ## 需要帮助? -如果在开发的过程中遇到问题，可以在 [AskTUG](https://asktug.com/?utm_source=docs-cn-dev-guide) 上进行提问，寻求帮助。 +- 在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [提交 TiDB 工单](/support.md) diff --git a/develop/dev-guide-sample-application-java-mybatis.md b/develop/dev-guide-sample-application-java-mybatis.md index 7257bfdcc871..fc155e4339b1 100644 --- a/develop/dev-guide-sample-application-java-mybatis.md +++ b/develop/dev-guide-sample-application-java-mybatis.md @@ -1,6 +1,7 @@ --- title: 使用 MyBatis 连接到 TiDB summary: 了解如何使用 MyBatis 连接到 TiDB。本文提供了使用 MyBatis 与 TiDB 交互的 Java 示例代码片段。 +aliases: ['/zh/tidb/stable/dev-guide-sample-application-java-mybatis/','/zh/tidb/dev/dev-guide-sample-application-java-mybatis/','/zh/tidbcloud/dev-guide-sample-application-java-mybatis/'] --- # 使用 MyBatis 连接到 TiDB @@ -15,7 +16,7 @@ TiDB 是一个兼容 MySQL 的数据库。[MyBatis](https://mybatis.org/mybatis- > **注意** > -> 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 +> 本文档适用于 {{{ .starter }}}、{{{ .essential }}}、TiDB Cloud Dedicated 和本地部署的 TiDB。 ## 前置需求 @@ -23,8 +24,8 @@ TiDB 是一个兼容 MySQL 的数据库。[MyBatis](https://mybatis.org/mybatis- - [Maven](https://maven.apache.org/install.html) **3.8** 及以上版本。 - [Git](https://git-scm.com/downloads)。 - TiDB 集群。如果你还没有 TiDB 集群，可以按照以下方式创建： - - （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)，创建你自己的 TiDB Cloud 集群。 - - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 + - （推荐方式）参考[创建 {{{ .starter }}} 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)，创建你自己的 TiDB Cloud 集群。 + - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 ## 运行代码并连接到 TiDB @@ -45,9 +46,9 @@ cd tidb-java-mybatis-quickstart -
+
-1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 TiDB Cloud Serverless 集群，进入集群的 **Overview** 页面。 +1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 {{{ .starter }}} 集群，进入集群的 **Overview** 页面。 2. 点击右上角的 **Connect** 按钮，将会弹出连接对话框。 @@ -87,7 +88,7 @@ cd tidb-java-mybatis-quickstart 注意替换 `{}` 中的占位符为连接对话框中获得的值。 - TiDB Cloud Serverless 要求使用 TLS (SSL) connection，因此 `USE_SSL` 的值应为 `true`。 + {{{ .starter }}} 要求使用 TLS (SSL) connection，因此 `USE_SSL` 的值应为 `true`。 7. 保存 `env.sh` 文件。 @@ -299,9 +300,11 @@ public SqlSessionFactory getSessionFactory() { - 关于 MyBatis 的更多使用方法，可以参考 [MyBatis 官方文档](http://www.mybatis.org/mybatis-3/)。 - 你可以继续阅读开发者文档，以获取更多关于 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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 -- 我们还额外提供针对 Java 开发者的课程：[使用 Connector/J - TiDB v6](https://learn.pingcap.com/learner/course/840002/?utm_source=docs-cn-dev-guide) 及[在 TiDB 上开发应用的最佳实践 - TiDB v6](https://learn.pingcap.com/learner/course/780002/?utm_source=docs-cn-dev-guide)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 +- 我们还额外提供针对 Java 开发者的课程：[使用 Connector/J - TiDB v6](https://learn.pingcap.cn/learner/course/840002?utm_source=docs-cn-dev-guide) 及[在 TiDB 上开发应用的最佳实践 - TiDB v6](https://learn.pingcap.cn/learner/course/780002?utm_source=docs-cn-dev-guide)。 ## 需要帮助? -如果在开发的过程中遇到问题，可以在 [AskTUG](https://asktug.com/?utm_source=docs-cn-dev-guide) 上进行提问，寻求帮助。 +- 在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [提交 TiDB 工单](/support.md) diff --git a/develop/dev-guide-sample-application-java-spring-boot.md b/develop/dev-guide-sample-application-java-spring-boot.md index 413e200d1d53..8078c14bc642 100644 --- a/develop/dev-guide-sample-application-java-spring-boot.md +++ b/develop/dev-guide-sample-application-java-spring-boot.md @@ -1,7 +1,7 @@ --- title: 使用 Spring Boot 连接到 TiDB summary: 了解如何使用 Spring Boot 连接到 TiDB。本文提供了使用 Spring Boot 与 TiDB 交互的 Java 示例代码片段。 -aliases: ['/zh/tidb/dev/dev-guide-sample-application-spring-boot', '/zh/tidb/dev/sample-application-spring-boot'] +aliases: ['/zh/tidb/dev/dev-guide-sample-application-spring-boot', '/zh/tidb/dev/sample-application-spring-boot','/zh/tidb/stable/dev-guide-sample-application-java-spring-boot/','/zh/tidb/dev/dev-guide-sample-application-java-spring-boot/','/zh/tidbcloud/dev-guide-sample-application-java-spring-boot/'] --- # 使用 Spring Boot 连接到 TiDB @@ -16,7 +16,7 @@ TiDB 是一个兼容 MySQL 的数据库。[Spring](https://spring.io/) 是当前 > **注意** > -> 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 +> 本文档适用于 {{{ .starter }}}、{{{ .essential }}}、TiDB Cloud Dedicated 和本地部署的 TiDB。 ## 前置需求 @@ -24,8 +24,8 @@ TiDB 是一个兼容 MySQL 的数据库。[Spring](https://spring.io/) 是当前 - [Maven](https://maven.apache.org/install.html) **3.8** 及以上版本。 - [Git](https://git-scm.com/downloads)。 - TiDB 集群。如果你还没有 TiDB 集群，可以按照以下方式创建： - - （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)，创建你自己的 TiDB Cloud 集群。 - - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 + - （推荐方式）参考[创建 {{{ .starter }}} 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)，创建你自己的 TiDB Cloud 集群。 + - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 ## 运行代码并连接到 TiDB @@ -46,9 +46,9 @@ cd tidb-java-springboot-jpa-quickstart -
+
-1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 TiDB Cloud Serverless 集群，进入集群的 **Overview** 页面。 +1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 {{{ .starter }}} 集群，进入集群的 **Overview** 页面。 2. 点击右上角的 **Connect** 按钮，将会弹出连接对话框。 @@ -88,7 +88,7 @@ cd tidb-java-springboot-jpa-quickstart 注意替换 `{}` 中的占位符为连接对话框中获得的值。 - TiDB Cloud Serverless 要求使用 TLS (SSL) connection，因此 `USE_SSL` 的值应为 `true`。 + {{{ .starter }}} 要求使用 TLS (SSL) connection，因此 `USE_SSL` 的值应为 `true`。 7. 保存 `env.sh` 文件。 @@ -261,9 +261,11 @@ playerRepository.deleteById(id); - [Spring Data JPA 官方文档](https://spring.io/projects/spring-data-jpa) - [Hibernate 官方文档](https://hibernate.org/orm/documentation) - 你可以继续阅读开发者文档，以获取更多关于 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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 -- 我们还额外提供针对 Java 开发者的课程：[使用 Connector/J - TiDB v6](https://learn.pingcap.com/learner/course/840002/?utm_source=docs-cn-dev-guide) 及[在 TiDB 上开发应用的最佳实践 - TiDB v6](https://learn.pingcap.com/learner/course/780002/?utm_source=docs-cn-dev-guide)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 +- 我们还额外提供针对 Java 开发者的课程：[使用 Connector/J - TiDB v6](https://learn.pingcap.cn/learner/course/840002?utm_source=docs-cn-dev-guide) 及[在 TiDB 上开发应用的最佳实践 - TiDB v6](https://learn.pingcap.cn/learner/course/780002?utm_source=docs-cn-dev-guide)。 ## 需要帮助? -如果在开发的过程中遇到问题，可以在 [AskTUG](https://asktug.com/?utm_source=docs-cn-dev-guide) 上进行提问，寻求帮助。 +- 在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [提交 TiDB 工单](/support.md) diff --git a/develop/dev-guide-sample-application-nextjs.md b/develop/dev-guide-sample-application-nextjs.md index efd888218fd1..7d7beef9d41c 100644 --- a/develop/dev-guide-sample-application-nextjs.md +++ b/develop/dev-guide-sample-application-nextjs.md @@ -1,6 +1,7 @@ --- title: 在 Next.js 中使用 mysql2 连接到 TiDB summary: 本文介绍了如何在 Next.js 中使用 TiDB 和 mysql2 构建一个 CRUD 应用程序，并给出了简单示例代码片段。 +aliases: ['/zh/tidb/stable/dev-guide-sample-application-nextjs/','/zh/tidb/dev/dev-guide-sample-application-nextjs/','/zh/tidbcloud/dev-guide-sample-application-nextjs/'] --- # 在 Next.js 中使用 mysql2 连接到 TiDB @@ -15,7 +16,7 @@ TiDB 是一个兼容 MySQL 的数据库，[mysql2](https://github.com/sidorares/ > **Note** > -> 本文档适用于 TiDB Cloud Serverless 和本地部署的 TiDB。 +> 本文档适用于 {{{ .starter }}}、{{{ .essential }}} 和本地部署的 TiDB。 ## 前置需求 @@ -27,8 +28,8 @@ TiDB 是一个兼容 MySQL 的数据库，[mysql2](https://github.com/sidorares/ 如果你还没有 TiDB 集群，可以按照以下方式创建： -- （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)，创建你自己的 TiDB Cloud 集群。 -- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 +- （推荐方式）参考[创建 {{{ .starter }}} 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)，创建你自己的 TiDB Cloud 集群。 +- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 ## 运行代码并连接到 TiDB @@ -61,9 +62,9 @@ npm install -
+
-1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 TiDB Cloud Serverless 集群，进入集群的 **Overview** 页面。 +1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 {{{ .starter }}} 集群，进入集群的 **Overview** 页面。 2. 点击右上角的 **Connect** 按钮，将会弹出连接对话框。 @@ -265,8 +266,10 @@ console.log(rsh.affectedRows); - 关于使用 ORM 框架和 Next.js 构建复杂应用程序的更多细节，可以参考 [tidb-prisma-vercel-demo](https://github.com/pingcap/tidb-prisma-vercel-demo)。 - 关于 mysql2 的更多使用方法，可以参考 [mysql2 的官方文档](https://sidorares.github.io/node-mysql2/zh-CN/docs)。 - 你可以继续阅读开发者文档的其它章节来获取更多 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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 ## 需要帮助? -如果在开发的过程中遇到问题，可以在 [AskTUG](https://asktug.com/?utm_source=docs-cn-dev-guide) 上进行提问，或从 PingCAP 官方或 TiDB 社区[获取支持](/support.md)。 +- 在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [提交 TiDB 工单](/support.md) \ No newline at end of file diff --git a/develop/dev-guide-sample-application-nodejs-mysql2.md b/develop/dev-guide-sample-application-nodejs-mysql2.md index 77d0b1189e46..ebafbcd04250 100644 --- a/develop/dev-guide-sample-application-nodejs-mysql2.md +++ b/develop/dev-guide-sample-application-nodejs-mysql2.md @@ -1,6 +1,7 @@ --- title: 使用 node-mysql2 连接到 TiDB summary: 本文描述了 TiDB 和 node-mysql2 的连接步骤，并给出了简单示例代码片段。 +aliases: ['/zh/tidb/stable/dev-guide-sample-application-nodejs-mysql2/','/zh/tidb/dev/dev-guide-sample-application-nodejs-mysql2/','/zh/tidbcloud/dev-guide-sample-application-nodejs-mysql2/'] --- # 使用 node-mysql2 连接到 TiDB @@ -15,7 +16,7 @@ TiDB 是一个兼容 MySQL 的数据库。[node-mysql2](https://github.com/sidor > **注意** > -> 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 +> 本文档适用于 {{{ .starter }}}、{{{ .essential }}}、TiDB Cloud Dedicated 和本地部署的 TiDB。 ## 前置需求 @@ -27,8 +28,8 @@ TiDB 是一个兼容 MySQL 的数据库。[node-mysql2](https://github.com/sidor 如果你还没有 TiDB 集群，可以按照以下方式创建： -- （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)，创建你自己的 TiDB Cloud 集群。 -- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 +- （推荐方式）参考[创建 {{{ .starter }}} 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)，创建你自己的 TiDB Cloud 集群。 +- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 ## 运行代码并连接到 TiDB @@ -63,9 +64,9 @@ npm install mysql2 dotenv --save -
+
-1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 TiDB Cloud Serverless 集群，进入集群的 **Overview** 页面。 +1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 {{{ .starter }}} 集群，进入集群的 **Overview** 页面。 2. 点击右上角的 **Connect** 按钮，将会弹出连接对话框。 @@ -101,7 +102,7 @@ npm install mysql2 dotenv --save > **Note** > - > 当你使用 Public Endpoint 连接 TiDB Cloud Serverless 集群时，**必须**启用 TLS 连接，请将 `TIDB_ENABLE_SSL` 修改为 `true`。 + > 当你使用 Public Endpoint 连接 {{{ .starter }}} 集群时，**必须**启用 TLS 连接，请将 `TIDB_ENABLE_SSL` 修改为 `true`。 7. 保存 `.env` 文件。 @@ -182,7 +183,7 @@ npm run start 如果连接成功，你的终端将会输出所连接集群的版本信息： ``` -🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-v8.4.0) +🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-v{{{ .tidb-version }}}) ⏳ Loading sample game data... ✅ Loaded sample game data. @@ -235,7 +236,7 @@ void main(); > **Note** > -> 使用 Public Endpoint 连接 TiDB Cloud Serverless 时，**必须**启用 TLS 连接，请将 `TIDB_ENABLE_SSL` 修改为 `true`。但是你**不需要**通过 `TIDB_CA_PATH` 指定 SSL CA 证书，因为 Node.js 默认使用内置的 [Mozilla CA 证书](https://wiki.mozilla.org/CA/Included_Certificates)，该证书已被 TiDB Cloud Serverless 信任。 +> 使用 Public Endpoint 连接 {{{ .starter }}} 时，**必须**启用 TLS 连接，请将 `TIDB_ENABLE_SSL` 修改为 `true`。但是你**不需要**通过 `TIDB_CA_PATH` 指定 SSL CA 证书，因为 Node.js 默认使用内置的 [Mozilla CA 证书](https://wiki.mozilla.org/CA/Included_Certificates)，该证书已被 {{{ .starter }}} 信任。 ### 插入数据 @@ -288,4 +289,4 @@ console.log(rsh.affectedRows); - 关于 node-mysql2 的更多使用方法，可以参考 [node-mysql2 的 GitHub 仓库](https://github.com/sidorares/node-mysql2)。 - 你可以继续阅读开发者文档的其它章节来获取更多 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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供了专业的 [TiDB 开发者课程](https://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 diff --git a/develop/dev-guide-sample-application-nodejs-mysqljs.md b/develop/dev-guide-sample-application-nodejs-mysqljs.md index ab355f528f00..294e92517229 100644 --- a/develop/dev-guide-sample-application-nodejs-mysqljs.md +++ b/develop/dev-guide-sample-application-nodejs-mysqljs.md @@ -1,6 +1,7 @@ --- title: 使用 mysql.js 连接到 TiDB summary: 本文描述了 TiDB 和 mysql.js 的连接步骤，并给出了简单示例代码片段。 +aliases: ['/zh/tidb/stable/dev-guide-sample-application-nodejs-mysqljs/','/zh/tidb/dev/dev-guide-sample-application-nodejs-mysqljs/','/zh/tidbcloud/dev-guide-sample-application-nodejs-mysqljs/'] --- # 使用 mysql.js 连接到 TiDB @@ -15,7 +16,7 @@ TiDB 是一个兼容 MySQL 的数据库。[mysql.js](https://github.com/mysqljs/ > **注意** > -> 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 +> 本文档适用于 {{{ .starter }}}、{{{ .essential }}}、TiDB Cloud Dedicated 和本地部署的 TiDB。 ## 前置需求 @@ -27,8 +28,8 @@ TiDB 是一个兼容 MySQL 的数据库。[mysql.js](https://github.com/mysqljs/ 如果你还没有 TiDB 集群，可以按照以下方式创建： -- （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)，创建你自己的 TiDB Cloud 集群。 -- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 +- （推荐方式）参考[创建 {{{ .starter }}} 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)，创建你自己的 TiDB Cloud 集群。 +- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 ## 运行代码并连接到 TiDB @@ -63,9 +64,9 @@ npm install mysql dotenv --save -
+
-1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 TiDB Cloud Serverless 集群，进入集群的 **Overview** 页面。 +1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 {{{ .starter }}} 集群，进入集群的 **Overview** 页面。 2. 点击右上角的 **Connect** 按钮，将会弹出连接对话框。 @@ -101,7 +102,7 @@ npm install mysql dotenv --save > **Note** > - > 当你使用 Public Endpoint 连接 TiDB Cloud Serverless 集群时，**必须**启用 TLS 连接，请将 `TIDB_ENABLE_SSL` 修改为 `true`。 + > 当你使用 Public Endpoint 连接 {{{ .starter }}} 集群时，**必须**启用 TLS 连接，请将 `TIDB_ENABLE_SSL` 修改为 `true`。 7. 保存 `.env` 文件。 @@ -182,7 +183,7 @@ npm run start 如果连接成功，你的终端将会输出所连接集群的版本信息： ``` -🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-v8.4.0) +🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-v{{{ .tidb-version }}}) ⏳ Loading sample game data... ✅ Loaded sample game data. @@ -231,7 +232,7 @@ conn.end(); > **Note** > -> 使用 Public Endpoint 连接 TiDB Cloud Serverless 时，**必须**启用 TLS 连接，请将 `TIDB_ENABLE_SSL` 修改为 `true`。但是你**不需要**通过 `TIDB_CA_PATH` 指定 SSL CA 证书，因为 Node.js 默认使用内置的 [Mozilla CA 证书](https://wiki.mozilla.org/CA/Included_Certificates)，该证书已被 TiDB Cloud Serverless 信任。 +> 使用 Public Endpoint 连接 {{{ .starter }}} 时，**必须**启用 TLS 连接，请将 `TIDB_ENABLE_SSL` 修改为 `true`。但是你**不需要**通过 `TIDB_CA_PATH` 指定 SSL CA 证书，因为 Node.js 默认使用内置的 [Mozilla CA 证书](https://wiki.mozilla.org/CA/Included_Certificates)，该证书已被 {{{ .starter }}} 信任。 ### 插入数据 @@ -319,4 +320,4 @@ conn.query('DELETE FROM players WHERE id = ?;', [1], (err, ok) => { - 关于 mysql.js 驱动的更多使用方法，可以参考 [mysql.js 的 GitHub 仓库](https://github.com/mysqljs/mysql)。 - 你可以继续阅读开发者文档的其它章节来获取更多 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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供了专业的 [TiDB 开发者课程](https://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 diff --git a/develop/dev-guide-sample-application-nodejs-prisma.md b/develop/dev-guide-sample-application-nodejs-prisma.md index d6d09b007d8e..b47f7edcab8c 100644 --- a/develop/dev-guide-sample-application-nodejs-prisma.md +++ b/develop/dev-guide-sample-application-nodejs-prisma.md @@ -1,6 +1,7 @@ --- title: 使用 Prisma 连接到 TiDB summary: 本文描述了 TiDB 和 Prisma 的连接步骤，并给出了简单示例代码片段。 +aliases: ['/zh/tidb/stable/dev-guide-sample-application-nodejs-prisma/','/zh/tidb/dev/dev-guide-sample-application-nodejs-prisma/','/zh/tidbcloud/dev-guide-sample-application-nodejs-prisma/'] --- # 使用 Prisma 连接到 TiDB @@ -15,7 +16,7 @@ TiDB 是一个兼容 MySQL 的数据库。[Prisma](https://www.prisma.io/) 是 > **注意** > -> 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 +> 本文档适用于 {{{ .starter }}}、{{{ .essential }}}、TiDB Cloud Dedicated 和本地部署的 TiDB。 ## 前置需求 @@ -27,8 +28,8 @@ TiDB 是一个兼容 MySQL 的数据库。[Prisma](https://www.prisma.io/) 是 如果你还没有 TiDB 集群，可以按照以下方式创建： -- （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)，创建你自己的 TiDB Cloud 集群。 -- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 +- （推荐方式）参考[创建 {{{ .starter }}} 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)，创建你自己的 TiDB Cloud 集群。 +- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 ## 运行代码并连接到 TiDB @@ -63,9 +64,9 @@ npm install prisma typescript ts-node @types/node --save-dev -
+
-1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 TiDB Cloud Serverless 集群，进入集群的 **Overview** 页面。 +1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 {{{ .starter }}} 集群，进入集群的 **Overview** 页面。 2. 点击右上角的 **Connect** 按钮，将会弹出连接对话框。 @@ -96,7 +97,7 @@ npm install prisma typescript ts-node @types/node --save-dev > **Note** > - > 在使用 Public Endpoint 连接 TiDB Cloud Serverless 集群时，**必须**启用 TLS 连接，请将 `sslaccept` 参数设置为 `strict`。 + > 在使用 Public Endpoint 连接 {{{ .starter }}} 集群时，**必须**启用 TLS 连接，请将 `sslaccept` 参数设置为 `strict`。 7. 保存 `.env` 文件。 8. 在 `prisma/schema.prisma` 文件中，将 `provider` 修改为 `mysql`，并将 `url` 修改为 `env("DATABASE_URL")`： @@ -262,7 +263,7 @@ void main(); 如果连接成功，在你的终端上会输出所连接集群的版本信息。 ``` -🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-v8.4.0) +🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-v{{{ .tidb-version }}}) 🆕 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. @@ -361,4 +362,4 @@ await prisma.player.delete({ - 关于 Prisma 的更多使用方法，可以参考 [Prisma 的官方文档](https://www.prisma.io/docs)。 - 你可以继续阅读开发者文档的其它章节来获取更多 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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 diff --git a/develop/dev-guide-sample-application-nodejs-sequelize.md b/develop/dev-guide-sample-application-nodejs-sequelize.md index adf9a732969d..f5be9774eaf1 100644 --- a/develop/dev-guide-sample-application-nodejs-sequelize.md +++ b/develop/dev-guide-sample-application-nodejs-sequelize.md @@ -1,6 +1,7 @@ --- title: 使用 Sequelize 连接到 TiDB summary: 本文描述了 TiDB 和 Sequelize 的连接步骤，并给出了简单示例代码片段。 +aliases: ['/zh/tidb/stable/dev-guide-sample-application-nodejs-sequelize/','/zh/tidb/dev/dev-guide-sample-application-nodejs-sequelize/','/zh/tidbcloud/dev-guide-sample-application-nodejs-sequelize/'] --- # 使用 Sequelize 连接到 TiDB @@ -15,7 +16,7 @@ TiDB 是一个兼容 MySQL 的数据库。[Sequelize](https://sequelize.org/) > **Note** > -> 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 +> 本文档适用于 {{{ .starter }}}、{{{ .essential }}}、TiDB Cloud Dedicated 和本地部署的 TiDB。 ## 前置需求 @@ -27,8 +28,8 @@ TiDB 是一个兼容 MySQL 的数据库。[Sequelize](https://sequelize.org/) 如果你还没有 TiDB 集群，可以按照以下方式创建： -- （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)，创建你自己的 TiDB Cloud 集群。 -- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 +- （推荐方式）参考[创建 {{{ .starter }}} 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)，创建你自己的 TiDB Cloud 集群。 +- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 ## 运行代码并连接到 TiDB @@ -61,9 +62,9 @@ npm install -
+
-1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 TiDB Cloud Serverless 集群，进入集群的 **Overview** 页面。 +1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 {{{ .starter }}} 集群，进入集群的 **Overview** 页面。 2. 点击右上角的 **Connect** 按钮，将会弹出连接对话框。 @@ -307,8 +308,10 @@ logger.info(deletedNewPlayer?.toJSON()); - 关于 Sequelize 的更多使用方法，可以参考 [Sequelize 的官方文档](https://sequelize.org/)。 - 你可以继续阅读开发者文档的其它章节来获取更多 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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 ## 需要帮助? -如果在开发的过程中遇到问题，可以在 [AskTUG](https://asktug.com/?utm_source=docs-cn-dev-guide) 上进行提问，或从 PingCAP 官方或 TiDB 社区[获取支持](/support.md)。 +- 在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [提交 TiDB 工单](/support.md) \ No newline at end of file diff --git a/develop/dev-guide-sample-application-nodejs-typeorm.md b/develop/dev-guide-sample-application-nodejs-typeorm.md index 0711f0231ab9..5a715ab04cd8 100644 --- a/develop/dev-guide-sample-application-nodejs-typeorm.md +++ b/develop/dev-guide-sample-application-nodejs-typeorm.md @@ -1,6 +1,7 @@ --- title: 使用 TypeORM 连接到 TiDB summary: 本文描述了 TiDB 和 TypeORM 的连接步骤，并给出了简单示例代码片段。 +aliases: ['/zh/tidb/stable/dev-guide-sample-application-nodejs-typeorm/','/zh/tidb/dev/dev-guide-sample-application-nodejs-typeorm/','/zh/tidbcloud/dev-guide-sample-application-nodejs-typeorm/'] --- # 使用 TypeORM 连接到 TiDB @@ -15,7 +16,7 @@ TiDB 是一个兼容 MySQL 的数据库。[TypeORM](https://typeorm.io/) 是当 > **注意** > -> 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 +> 本文档适用于 {{{ .starter }}}、{{{ .essential }}}、TiDB Cloud Dedicated 和本地部署的 TiDB。 ## 前置需求 @@ -27,8 +28,8 @@ TiDB 是一个兼容 MySQL 的数据库。[TypeORM](https://typeorm.io/) 是当 如果你还没有 TiDB 集群，可以按照以下方式创建： -- （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)，创建你自己的 TiDB Cloud 集群。 -- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 +- （推荐方式）参考[创建 {{{ .starter }}} 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)，创建你自己的 TiDB Cloud 集群。 +- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 ## 运行代码并连接到 TiDB @@ -76,9 +77,9 @@ npm install @types/node ts-node typescript --save-dev -
+
-1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 TiDB Cloud Serverless 集群，进入集群的 **Overview** 页面。 +1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 {{{ .starter }}} 集群，进入集群的 **Overview** 页面。 2. 点击右上角的 **Connect** 按钮，将会弹出连接对话框。 @@ -114,7 +115,7 @@ npm install @types/node ts-node typescript --save-dev > **Note** > - > 当你使用 Public Endpoint 连接 TiDB Cloud Serverless 集群时，**必须**启用 TLS 连接，请将 `TIDB_ENABLE_SSL` 修改为 `true`。 + > 当你使用 Public Endpoint 连接 {{{ .starter }}} 集群时，**必须**启用 TLS 连接，请将 `TIDB_ENABLE_SSL` 修改为 `true`。 7. 保存 `.env` 文件。 @@ -229,7 +230,7 @@ npm start 如果连接成功，你的终端将会输出所连接集群的版本信息： ``` -🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-v8.4.0) +🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-v{{{ .tidb-version }}}) 🆕 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. @@ -272,9 +273,9 @@ export const AppDataSource = new DataSource({ > **Note** > -> 使用 Public Endpoint 连接 TiDB Cloud Serverless 时，**必须**启用 TLS 连接，请将 `TIDB_ENABLE_SSL` 修改为 `true`。 +> 使用 Public Endpoint 连接 {{{ .starter }}} 时，**必须**启用 TLS 连接，请将 `TIDB_ENABLE_SSL` 修改为 `true`。 > -> 但是你**不需要**通过 `TIDB_CA_PATH` 指定 SSL CA 证书，因为 Node.js 默认使用内置的 [Mozilla CA 证书](https://wiki.mozilla.org/CA/Included_Certificates)，该证书已被 TiDB Cloud Serverless 信任。 +> 但是你**不需要**通过 `TIDB_CA_PATH` 指定 SSL CA 证书，因为 Node.js 默认使用内置的 [Mozilla CA 证书](https://wiki.mozilla.org/CA/Included_Certificates)，该证书已被 {{{ .starter }}} 信任。 ### 插入数据 @@ -363,8 +364,10 @@ export class ActionLog { - 关于 TypeORM 的更多使用方法，可以参考 [TypeORM 的官方文档](https://typeorm.io)。 - 你可以继续阅读开发者文档的其它章节来获取更多 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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 ## 需要帮助? -如果在开发的过程中遇到问题，可以在 [AskTUG](https://asktug.com/?utm_source=docs-cn-dev-guide) 上进行提问，寻求帮助。 +- 在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [提交 TiDB 工单](/support.md) diff --git a/develop/dev-guide-sample-application-python-django.md b/develop/dev-guide-sample-application-python-django.md index 7cd39a05ba8b..33c93394ce82 100644 --- a/develop/dev-guide-sample-application-python-django.md +++ b/develop/dev-guide-sample-application-python-django.md @@ -1,7 +1,7 @@ --- title: 使用 Django 连接到 TiDB summary: 了解如何使用 Django 连接到 TiDB。本文提供了使用 Django 与 TiDB 交互的 Python 示例代码片段。 -aliases: ['/zh/tidb/dev/dev-guide-sample-application-django'] +aliases: ['/zh/tidb/dev/dev-guide-sample-application-django','/zh/tidb/stable/dev-guide-sample-application-python-django/','/zh/tidb/dev/dev-guide-sample-application-python-django/','/zh/tidbcloud/dev-guide-sample-application-python-django/'] --- # 使用 Django 连接到 TiDB @@ -16,15 +16,15 @@ TiDB 是一个兼容 MySQL 的数据库。[Django](https://www.djangoproject.com > **注意** > -> 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 +> 本文档适用于 {{{ .starter }}}、{{{ .essential }}}、TiDB Cloud Dedicated 和本地部署的 TiDB。 ## 前置需求 - 推荐 [Python 3.8](https://www.python.org/downloads/) 及以上版本。 - [Git](https://git-scm.com/downloads)。 - TiDB 集群。如果你还没有 TiDB 集群，可以按照以下方式创建： - - （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)，创建你自己的 TiDB Cloud 集群。 - - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 + - （推荐方式）参考[创建 {{{ .starter }}} 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)，创建你自己的 TiDB Cloud 集群。 + - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 ## 运行代码并连接到 TiDB @@ -63,9 +63,9 @@ pip install -r requirements.txt -
+
-1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 TiDB Cloud Serverless 集群，进入集群的 **Overview** 页面。 +1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 {{{ .starter }}} 集群，进入集群的 **Overview** 页面。 2. 点击右上角的 **Connect** 按钮，将会弹出连接对话框。 @@ -338,8 +338,10 @@ Player.objects.filter(coins=100).delete() - 关于 Django 的更多使用方法，可以参考 [Django 官方文档](https://www.djangoproject.com/)。 - 你可以继续阅读开发者文档，以获取更多关于 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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 ## 需要帮助? -如果在开发的过程中遇到问题，可以在 [AskTUG](https://asktug.com/?utm_source=docs-cn-dev-guide) 上进行提问，寻求帮助。 \ No newline at end of file +- 在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [提交 TiDB 工单](/support.md) \ No newline at end of file diff --git a/develop/dev-guide-sample-application-python-mysql-connector.md b/develop/dev-guide-sample-application-python-mysql-connector.md index 48e8ce3b5567..79012cdce8f2 100644 --- a/develop/dev-guide-sample-application-python-mysql-connector.md +++ b/develop/dev-guide-sample-application-python-mysql-connector.md @@ -1,7 +1,7 @@ --- title: 使用 MySQL Connector/Python 连接到 TiDB summary: 了解如何使用 MySQL Connector/Python 连接到 TiDB。本文提供了使用 MySQL Connector/Python 与 TiDB 交互的 Python 示例代码片段。 -aliases: ['/zh/tidb/dev/dev-guide-sample-application-python'] +aliases: ['/zh/tidb/dev/dev-guide-sample-application-python','/zh/tidb/stable/dev-guide-sample-application-python-mysql-connector/','/zh/tidb/dev/dev-guide-sample-application-python-mysql-connector/','/zh/tidbcloud/dev-guide-sample-application-python-mysql-connector/'] --- # 使用 MySQL Connector/Python 连接到 TiDB @@ -16,15 +16,15 @@ TiDB 是一个兼容 MySQL 的数据库。[MySQL Connector/Python](https://dev.m > **注意** > -> 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 +> 本文档适用于 {{{ .starter }}}、{{{ .essential }}}、TiDB Cloud Dedicated 和本地部署的 TiDB。 ## 前置需求 - 推荐 [Python 3.8](https://www.python.org/downloads/) 及以上版本。 - [Git](https://git-scm.com/downloads)。 - TiDB 集群。如果你还没有 TiDB 集群，可以按照以下方式创建： - - （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)，创建你自己的 TiDB Cloud 集群。 - - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 + - （推荐方式）参考[创建 {{{ .starter }}} 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)，创建你自己的 TiDB Cloud 集群。 + - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 ## 运行代码并连接到 TiDB @@ -53,9 +53,9 @@ pip install -r requirements.txt -
+
-1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 TiDB Cloud Serverless 集群，进入集群的 **Overview** 页面。 +1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 {{{ .starter }}} 集群，进入集群的 **Overview** 页面。 2. 点击右上角的 **Connect** 按钮，将会弹出连接对话框。 @@ -265,8 +265,10 @@ Python 驱动程序提供对数据库的底层访问，但要求开发者： - 关于 mysql-connector-python 的更多使用方法，可以参考 [MySQL Connector/Python 官方文档](https://dev.mysql.com/doc/connector-python/en/)。 - 你可以继续阅读开发者文档，以获取更多关于 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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 ## 需要帮助? -如果在开发的过程中遇到问题，可以在 [AskTUG](https://asktug.com/?utm_source=docs-cn-dev-guide) 上进行提问，寻求帮助。 \ No newline at end of file +- 在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [提交 TiDB 工单](/support.md) \ No newline at end of file diff --git a/develop/dev-guide-sample-application-python-mysqlclient.md b/develop/dev-guide-sample-application-python-mysqlclient.md index 14b1f3fc613e..210d33f7f608 100644 --- a/develop/dev-guide-sample-application-python-mysqlclient.md +++ b/develop/dev-guide-sample-application-python-mysqlclient.md @@ -1,6 +1,7 @@ --- title: 使用 mysqlclient 连接到 TiDB summary: 了解如何使用 mysqlclient 连接到 TiDB。本文提供了使用 mysqlclient 与 TiDB 交互的 Python 示例代码片段。 +aliases: ['/zh/tidb/stable/dev-guide-sample-application-python-mysqlclient/','/zh/tidb/dev/dev-guide-sample-application-python-mysqlclient/','/zh/tidbcloud/dev-guide-sample-application-python-mysqlclient/'] --- # 使用 mysqlclient 连接到 TiDB @@ -15,15 +16,15 @@ TiDB 是一个兼容 MySQL 的数据库。[mysqlclient](https://github.com/PyMyS > **注意** > -> 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 +> 本文档适用于 {{{ .starter }}}、{{{ .essential }}}、TiDB Cloud Dedicated 和本地部署的 TiDB。 ## 前置需求 - 推荐 [Python 3.8](https://www.python.org/downloads/) 及以上版本。 - [Git](https://git-scm.com/downloads)。 - TiDB 集群。如果你还没有 TiDB 集群，可以按照以下方式创建： - - （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)，创建你自己的 TiDB Cloud 集群。 - - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 + - （推荐方式）参考[创建 {{{ .starter }}} 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)，创建你自己的 TiDB Cloud 集群。 + - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 ## 运行代码并连接到 TiDB @@ -54,9 +55,9 @@ pip install -r requirements.txt -
+
-1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 TiDB Cloud Serverless 集群，进入集群的 **Overview** 页面。 +1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 {{{ .starter }}} 集群，进入集群的 **Overview** 页面。 2. 点击右上角的 **Connect** 按钮，将会弹出连接对话框。 @@ -96,7 +97,7 @@ pip install -r requirements.txt 注意替换 `{}` 中的占位符为连接对话框中获得的值。 - TiDB Cloud Serverless 要求使用 TLS (SSL) connection，由于 mysqlclient 的 `ssl_mode` 默认为 `PREFERRED`，所以不需要你手动指定 `CA_PATH`，设置为空即可。但如果你有特殊原因需要手动指定 `CA_PATH`，可以参考 [TiDB Cloud 文档](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-clusters#root-certificate-default-path)获取不同操作系统下证书的路径。 + {{{ .starter }}} 要求使用 TLS (SSL) connection，由于 mysqlclient 的 `ssl_mode` 默认为 `PREFERRED`，所以不需要你手动指定 `CA_PATH`，设置为空即可。但如果你有特殊原因需要手动指定 `CA_PATH`，可以参考 [TiDB Cloud 文档](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-clusters#root-certificate-default-path)获取不同操作系统下证书的路径。 7. 保存 `.env` 文件。 @@ -267,8 +268,10 @@ Python 驱动程序提供对数据库的底层访问，但要求开发者： - 关于 mysqlclient 的更多使用方法，可以参考 [mysqlclient 官方文档](https://mysqlclient.readthedocs.io/)。 - 你可以继续阅读开发者文档，以获取更多关于 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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 ## 需要帮助? -如果在开发的过程中遇到问题，可以在 [AskTUG](https://asktug.com/?utm_source=docs-cn-dev-guide) 上进行提问，寻求帮助。 +- 在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [提交 TiDB 工单](/support.md) diff --git a/develop/dev-guide-sample-application-python-peewee.md b/develop/dev-guide-sample-application-python-peewee.md index 50624c4ae959..d008d7fb4cfe 100644 --- a/develop/dev-guide-sample-application-python-peewee.md +++ b/develop/dev-guide-sample-application-python-peewee.md @@ -1,6 +1,7 @@ --- title: 使用 peewee 连接到 TiDB summary: 了解如何使用 peewee 连接到 TiDB。本文提供了使用 peewee 与 TiDB 交互的 Python 示例代码片段。 +aliases: ['/zh/tidb/stable/dev-guide-sample-application-python-peewee/','/zh/tidb/dev/dev-guide-sample-application-python-peewee/','/zh/tidbcloud/dev-guide-sample-application-python-peewee/'] --- # 使用 peewee 连接到 TiDB @@ -15,15 +16,15 @@ TiDB 是一个兼容 MySQL 的数据库。[peewee](https://github.com/coleifer/p > **注意** > -> 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 +> 本文档适用于 {{{ .starter }}}、{{{ .essential }}}、TiDB Cloud Dedicated 和本地部署的 TiDB。 ## 前置需求 - 推荐 [Python 3.8](https://www.python.org/downloads/) 及以上版本。 - [Git](https://git-scm.com/downloads)。 - TiDB 集群。如果你还没有 TiDB 集群，可以按照以下方式创建： - - （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)，创建你自己的 TiDB Cloud 集群。 - - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 + - （推荐方式）参考[创建 {{{ .starter }}} 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)，创建你自己的 TiDB Cloud 集群。 + - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 ## 运行代码并连接到 TiDB @@ -56,9 +57,9 @@ peewee 是一个支持多种数据库的 ORM 库。它是对数据库的高层 -
+
-1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 TiDB Cloud Serverless 集群，进入集群的 **Overview** 页面。 +1. 在 TiDB Cloud 的 [**Clusters**](https://{{{.console-url}}}/project/clusters) 页面中，选择你的 {{{ .starter }}} 集群，进入集群的 **Overview** 页面。 2. 点击右上角的 **Connect** 按钮，将会弹出连接对话框。 @@ -291,8 +292,10 @@ Player.delete().where(Player.coins == 100).execute() - 关于 peewee 的更多使用方法，可以参考 [peewee 官方文档](https://docs.peewee-orm.com/)。 - 你可以继续阅读开发者文档，以获取更多关于 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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 ## 需要帮助? -如果在开发的过程中遇到问题，可以在 [AskTUG](https://asktug.com/?utm_source=docs-cn-dev-guide) 上进行提问，寻求帮助。 \ No newline at end of file +- 在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [提交 TiDB 工单](/support.md) \ No newline at end of file diff --git a/develop/dev-guide-sample-application-python-pymysql.md b/develop/dev-guide-sample-application-python-pymysql.md index e6f684ff5a22..be9a77d36d0a 100644 --- a/develop/dev-guide-sample-application-python-pymysql.md +++ b/develop/dev-guide-sample-application-python-pymysql.md @@ -1,6 +1,7 @@ --- title: 使用 PyMySQL 连接到 TiDB summary: 了解如何使用 PyMySQL 连接到 TiDB。本文提供了使用 PyMySQL 与 TiDB 交互的 Python 示例代码片段。 +aliases: ['/zh/tidb/stable/dev-guide-sample-application-python-pymysql/','/zh/tidb/dev/dev-guide-sample-application-python-pymysql/','/zh/tidbcloud/dev-guide-sample-application-python-pymysql/'] --- # 使用 PyMySQL 连接到 TiDB @@ -15,15 +16,15 @@ TiDB 是一个兼容 MySQL 的数据库。[PyMySQL](https://github.com/PyMySQL/P > **注意** > -> 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 +> 本文档适用于 {{{ .starter }}}、{{{ .essential }}}、TiDB Cloud Dedicated 和本地部署的 TiDB。 ## 前置需求 - 推荐 [Python 3.8](https://www.python.org/downloads/) 及以上版本。 - [Git](https://git-scm.com/downloads)。 - TiDB 集群。如果你还没有 TiDB 集群，可以按照以下方式创建： - - （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)，创建你自己的 TiDB Cloud 集群。 - - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 + - （推荐方式）参考[创建 {{{ .starter }}} 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)，创建你自己的 TiDB Cloud 集群。 + - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 ## 运行代码并连接到 TiDB @@ -52,9 +53,9 @@ pip install -r requirements.txt -
+
-1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 TiDB Cloud Serverless 集群，进入集群的 **Overview** 页面。 +1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 {{{ .starter }}} 集群，进入集群的 **Overview** 页面。 2. 点击右上角的 **Connect** 按钮，将会弹出连接对话框。 @@ -269,8 +270,10 @@ Python 驱动程序提供对数据库的底层访问，但要求开发者： - 关于 PyMySQL 的更多使用方法，可以参考 [PyMySQL 官方文档](https://pymysql.readthedocs.io)。 - 你可以继续阅读开发者文档，以获取更多关于 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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 ## 需要帮助? -如果在开发的过程中遇到问题，可以在 [AskTUG](https://asktug.com/?utm_source=docs-cn-dev-guide) 上进行提问，寻求帮助。 \ No newline at end of file +- 在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [提交 TiDB 工单](/support.md) \ 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 610c02821b30..d082014f481d 100644 --- a/develop/dev-guide-sample-application-python-sqlalchemy.md +++ b/develop/dev-guide-sample-application-python-sqlalchemy.md @@ -1,6 +1,7 @@ --- title: 使用 SQLAlchemy 连接到 TiDB summary: 了解如何使用 SQLAlchemy 连接到 TiDB。本文提供了使用 SQLAlchemy 与 TiDB 交互的 Python 示例代码片段。 +aliases: ['/zh/tidb/stable/dev-guide-sample-application-python-sqlalchemy/','/zh/tidb/dev/dev-guide-sample-application-python-sqlalchemy/','/zh/tidbcloud/dev-guide-sample-application-python-sqlalchemy/'] --- # 使用 SQLAlchemy 连接到 TiDB @@ -15,15 +16,15 @@ TiDB 是一个兼容 MySQL 的数据库。[SQLAlchemy](https://www.sqlalchemy.or > **注意** > -> 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 +> 本文档适用于 {{{ .starter }}}、{{{ .essential }}}、TiDB Cloud Dedicated 和本地部署的 TiDB。 ## 前置需求 - 推荐 [Python 3.8](https://www.python.org/downloads/) 及以上版本。 - [Git](https://git-scm.com/downloads)。 - TiDB 集群。如果你还没有 TiDB 集群，可以按照以下方式创建： - - （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)，创建你自己的 TiDB Cloud 集群。 - - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 + - （推荐方式）参考[创建 {{{ .starter }}} 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)，创建你自己的 TiDB Cloud 集群。 + - 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 ## 运行代码并连接到 TiDB @@ -58,13 +59,13 @@ SQLAlchemy 是一个支持多种数据库的 ORM 库。它是对数据库的高 -
+
> **注意：** > -> TiDB Cloud Serverless 集群目前存在一个限制：如果 5 分钟内没有活跃连接，集群将会自动关闭，这会导致所有连接中断。因此，当使用 SQLAlchemy 连接到 TiDB Cloud Serverless 集群时，从连接池中获取的连接可能会遇到 `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)。 +> {{{ .starter }}} 集群目前存在一个限制：如果 5 分钟内没有活跃连接，集群将会自动关闭，这会导致所有连接中断。因此，当使用 SQLAlchemy 连接到 {{{ .starter }}} 集群时，从连接池中获取的连接可能会遇到 `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. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 TiDB Cloud Serverless 集群，进入集群的 **Overview** 页面。 +1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 {{{ .starter }}} 集群，进入集群的 **Overview** 页面。 2. 点击右上角的 **Connect** 按钮，将会弹出连接对话框。 @@ -283,8 +284,10 @@ with Session() as session: - 关于 SQLAlchemy 的更多使用方法，可以参考 [SQLAlchemy 官方文档](https://www.sqlalchemy.org/)。 - 你可以继续阅读开发者文档，以获取更多关于 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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 ## 需要帮助? -如果在开发的过程中遇到问题，可以在 [AskTUG](https://asktug.com/?utm_source=docs-cn-dev-guide) 上进行提问，寻求帮助。 +- 在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [提交 TiDB 工单](/support.md) diff --git a/develop/dev-guide-sample-application-ruby-mysql2.md b/develop/dev-guide-sample-application-ruby-mysql2.md index 95660d0c5737..945fb6348e69 100644 --- a/develop/dev-guide-sample-application-ruby-mysql2.md +++ b/develop/dev-guide-sample-application-ruby-mysql2.md @@ -1,6 +1,7 @@ --- title: 使用 mysql2 连接 TiDB summary: 本文描述了 TiDB 和 mysql2 的连接步骤，并给出了使用 mysql2 gem 连接 TiDB 的简单示例代码片段。 +aliases: ['/zh/tidb/stable/dev-guide-sample-application-ruby-mysql2/','/zh/tidb/dev/dev-guide-sample-application-ruby-mysql2/','/zh/tidbcloud/dev-guide-sample-application-ruby-mysql2/'] --- # 使用 mysql2 连接 TiDB @@ -15,7 +16,7 @@ TiDB 是一个兼容 MySQL 的数据库。[mysql2](https://github.com/brianmario > **注意：** > -> 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 以及本地部署的 TiDB。 +> 本文档适用于 {{{ .starter }}}、{{{ .essential }}}、TiDB Cloud Dedicated 以及本地部署的 TiDB。 ## 前置需求 @@ -28,8 +29,8 @@ TiDB 是一个兼容 MySQL 的数据库。[mysql2](https://github.com/brianmario 如果你还没有 TiDB 集群，可以按照以下方式创建： -- （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)，创建你自己的 TiDB Cloud 集群。 -- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 +- （推荐方式）参考[创建 {{{ .starter }}} 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)，创建你自己的 TiDB Cloud 集群。 +- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 ## 运行示例应用程序并连接到 TiDB @@ -68,7 +69,7 @@ bundle add mysql2 dotenv 根据不同的 TiDB 部署方式，使用不同的方法连接到 TiDB 集群。 -
+
1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，点击你的目标集群的名称，进入集群的 **Overview** 页面。 @@ -102,7 +103,7 @@ bundle add mysql2 dotenv > **注意：** > - > 对于 TiDB Cloud Serverless，当使用 Public Endpoint 时，**必须**通过 `DATABASE_ENABLE_SSL` 启用 TLS 连接。 + > 对于 {{{ .starter }}}，当使用 Public Endpoint 时，**必须**通过 `DATABASE_ENABLE_SSL` 启用 TLS 连接。 7. 保存 `.env` 文件。 @@ -182,7 +183,7 @@ ruby app.rb 如果连接成功，你的终端将会输出所连接集群的版本信息： ``` -🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-v8.4.0) +🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-v{{{ .tidb-version }}}) ⏳ Loading sample game data... ✅ Loaded sample game data. @@ -221,7 +222,7 @@ client = Mysql2::Client.new(options) > **注意：** > -> 对于 TiDB Cloud Serverless，当使用 Public Endpoint 时，**必须**通过 `DATABASE_ENABLE_SSL` 启用 TLS 连接，但是你**不需要**通过 `DATABASE_SSL_CA` 指定 SSL CA 证书，因为 mysql2 gem 会按照特定的顺序搜索现有的 CA 证书，直到找到相应的文件。 +> 对于 {{{ .starter }}}，当使用 Public Endpoint 时，**必须**通过 `DATABASE_ENABLE_SSL` 启用 TLS 连接，但是你**不需要**通过 `DATABASE_SSL_CA` 指定 SSL CA 证书，因为 mysql2 gem 会按照特定的顺序搜索现有的 CA 证书，直到找到相应的文件。 ### 插入数据 @@ -298,8 +299,10 @@ end - 从 [mysql2 的文档](https://github.com/brianmario/mysql2#readme)中了解更多关于 mysql2 驱动的使用情况。 - 你可以继续阅读开发者文档的其它章节来获取更多 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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 ## 需要帮助？ -在 [AskTUG](https://asktug.com/) 论坛上提问。 \ No newline at end of file +- 在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [提交 TiDB 工单](/support.md) \ 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 efcf0acd37a9..48877f9a790c 100644 --- a/develop/dev-guide-sample-application-ruby-rails.md +++ b/develop/dev-guide-sample-application-ruby-rails.md @@ -1,6 +1,7 @@ --- title: 使用 Rails 框架和 ActiveRecord ORM 连接 TiDB summary: 本文描述了 TiDB 和 Rails 框架的连接步骤，并给出了使用 Rails 框架和 ActiveRecord ORM 连接 TiDB 的简单示例代码片段。 +aliases: ['/zh/tidb/stable/dev-guide-sample-application-ruby-rails/','/zh/tidb/dev/dev-guide-sample-application-ruby-rails/','/zh/tidbcloud/dev-guide-sample-application-ruby-rails/'] --- # 使用 Rails 框架和 ActiveRecord ORM 连接 TiDB @@ -15,7 +16,7 @@ TiDB 是一个兼容 MySQL 的数据库，[Rails](https://github.com/rails/rails > **注意：** > -> 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 以及本地部署的 TiDB。 +> 本文档适用于 {{{ .starter }}}、{{{ .essential }}}、TiDB Cloud Dedicated 以及本地部署的 TiDB。 ## 前置需求 @@ -28,8 +29,8 @@ TiDB 是一个兼容 MySQL 的数据库，[Rails](https://github.com/rails/rails 如果你还没有 TiDB 集群，可以按照以下方式创建： -- （推荐方式）参考[创建 TiDB Cloud Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)，创建你自己的 TiDB Cloud 集群。 -- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 +- （推荐方式）参考[创建 {{{ .starter }}} 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)，创建你自己的 TiDB Cloud 集群。 +- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#deploy-a-local-test-cluster)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 ## 运行示例应用程序并连接到 TiDB @@ -68,7 +69,7 @@ bundle add mysql2 dotenv 根据不同的 TiDB 部署方式，使用不同的方法连接到 TiDB 集群。 -
+
1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，点击你的目标集群的名称，进入集群的 **Overview** 页面。 @@ -92,7 +93,7 @@ bundle add mysql2 dotenv > **注意** > - > 对于 TiDB Cloud Serverless，当使用 Public Endpoint 时，必须使用 `ssl_mode=verify_identity` 查询参数启用 TLS 连接。 + > 对于 {{{ .starter }}}，当使用 Public Endpoint 时，必须使用 `ssl_mode=verify_identity` 查询参数启用 TLS 连接。 7. 保存 `.env` 文件。 @@ -175,7 +176,7 @@ bundle add mysql2 dotenv 如果连接成功，你的终端将会输出所连接集群的版本信息： ``` -🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-v8.4.0) +🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-v{{{ .tidb-version }}}) ⏳ Loading sample game data... ✅ Loaded sample game data. @@ -215,7 +216,7 @@ production: > **注意** > -> 对于 TiDB Cloud Serverless，当使用 Public Endpoint 时，**必须**通过在 `DATABASE_URL` 中设置 `ssl_mode` 查询参数为 `verify_identity` 来启用 TLS 连接，但是你**不需要**通过 `DATABASE_URL` 指定 SSL CA 证书，因为 mysql2 gem 会按照特定的顺序搜索现有的 CA 证书，直到找到相应的文件。 +> 对于 {{{ .starter }}}，当使用 Public Endpoint 时，**必须**通过在 `DATABASE_URL` 中设置 `ssl_mode` 查询参数为 `verify_identity` 来启用 TLS 连接，但是你**不需要**通过 `DATABASE_URL` 指定 SSL CA 证书，因为 mysql2 gem 会按照特定的顺序搜索现有的 CA 证书，直到找到相应的文件。 ### 插入数据 @@ -272,8 +273,10 @@ player.destroy - 从 [ActiveRecord 文档](https://guides.rubyonrails.org/active_record_basics.html)中了解更多关于 ActiveRecord ORM 的用法。 - 你可以继续阅读开发者文档的其它章节来获取更多 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://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://pingkai.cn/learn)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.cn/learner/certification-center)。 ## 需要帮助？ -在 [AskTUG](https://asktug.com/) 论坛上提问。 \ No newline at end of file +- 在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [提交 TiDB 工单](/support.md) \ No newline at end of file diff --git a/develop/dev-guide-schema-design-overview.md b/develop/dev-guide-schema-design-overview.md index a27a63de4d9e..6d2b5c33f3c1 100644 --- a/develop/dev-guide-schema-design-overview.md +++ b/develop/dev-guide-schema-design-overview.md @@ -1,7 +1,7 @@ --- title: 概述 summary: TiDB 数据库模式设计的概述。 -aliases: ['/zh/tidb/dev/schema-design-overview'] +aliases: ['/zh/tidb/dev/schema-design-overview','/zh/tidb/stable/dev-guide-schema-design-overview/','/zh/tidb/dev/dev-guide-schema-design-overview/','/zh/tidbcloud/dev-guide-schema-design-overview/'] --- # 概述 diff --git a/develop/dev-guide-sql-development-specification.md b/develop/dev-guide-sql-development-specification.md index c787e79c7591..f445d9f5a7c4 100644 --- a/develop/dev-guide-sql-development-specification.md +++ b/develop/dev-guide-sql-development-specification.md @@ -1,7 +1,7 @@ --- title: SQL 开发规范 summary: TiDB 的 SQL 开发规范。 -aliases: ['/zh/tidb/dev/sql-development-specification'] +aliases: ['/zh/tidb/dev/sql-development-specification','/zh/tidb/stable/dev-guide-sql-development-specification/','/zh/tidb/dev/dev-guide-sql-development-specification/','/zh/tidbcloud/dev-guide-sql-development-specification/'] --- # SQL 开发规范 diff --git a/develop/dev-guide-third-party-support.md b/develop/dev-guide-third-party-support.md index 2a908c9142cb..3e51339a5f09 100644 --- a/develop/dev-guide-third-party-support.md +++ b/develop/dev-guide-third-party-support.md @@ -1,7 +1,7 @@ --- title: TiDB 支持的第三方工具 -aliases: ['/zh/tidb/dev/supported-by-pingcap'] summary: TiDB 支持的第三方工具主要包括驱动、ORM 框架和 GUI。支持等级分为 Full 和 Compatible，其中 Full 表示绝大多数功能兼容性已得到支持，Compatible 表示大部分功能可使用但未经完整验证。对于支持的 Driver 或 ORM 框架并不包括应用端事务重试和错误处理。如果在使用工具连接 TiDB 时出现问题，可在 GitHub 上提交包含详细信息的 issue 以获得进展。 +aliases: ['/zh/tidb/stable/dev-guide-third-party-support/','/zh/tidb/dev/dev-guide-third-party-support/','/zh/tidbcloud/dev-guide-third-party-support/'] --- # TiDB 支持的第三方工具 @@ -27,161 +27,29 @@ PingCAP 与开源社区合作，通过三方工具提供以下支持： ## Driver -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
编程语言驱动最新已测试版本支持等级TiDB 适配器教程
GoGo-MySQL-Driverv1.6.0FullN/A使用 Go-MySQL-Driver 连接到 TiDB
JavaJDBC8.0Full - - 使用 JDBC 连接到 TiDB
+| 编程语言 | 驱动 | 最新已测试版本 | 支持等级 | TiDB 适配器 | 教程 | +|----------|--------|-----------------------|---------------|--------------|----------| +| Go | [go-sql-driver/mysql](https://github.com/go-sql-driver/mysql) | v1.6.0 | Full | N/A | [使用 Go-MySQL-Driver 连接到 TiDB](/develop/dev-guide-sample-application-golang-sql-driver.md) | +| Java | [MySQL Connector/J](https://dev.mysql.com/downloads/connector/j/) | 8.0 | Full | [pingcap/mysql-connector-j](/develop/dev-guide-choose-driver-or-orm.md#java-drivers)
[pingcap/tidb-loadbalance](/develop/dev-guide-choose-driver-or-orm.md#java-客户端负载均衡) | [使用 JDBC 连接到 TiDB](/develop/dev-guide-sample-application-java-jdbc.md) | ## ORM - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
编程语言ORM 框架最新已测试版本支持等级TiDB 适配器教程
Gogormv1.23.5FullN/A使用 GORM 连接到 TiDB
beegov2.0.3FullN/AN/A
upper/dbv4.5.2FullN/AN/A
xormv1.3.1FullN/AN/A
JavaHibernate6.1.0.FinalFullN/A使用 Hibernate 连接到 TiDB
MyBatisv3.5.10FullN/A使用 MyBatis 连接到 TiDB
Spring Data JPA2.7.2FullN/A使用 Spring Boot 连接到 TiDB
jOOQv3.16.7 (Open Source)FullN/AN/A
RubyActive Recordv7.0FullN/A使用 Rails 框架和 ActiveRecord ORM 连接到 TiDB
JavaScript / TypeScriptSequelizev6.20.1FullN/AN/A
Prisma4.16.2FullN/A使用 Prisma 连接到 TiDB
TypeORMv0.3.17FullN/A使用 TypeORM 连接到 TiDB
PythonDjangov4.2Fulldjango-tidb使用 Django 连接到 TiDB
SQLAlchemyv1.4.37FullN/A使用 SQLAlchemy 连接到 TiDB
+| 编程语言 | ORM 框架 | 最新已测试版本 | 支持等级 | TiDB 适配器 | 教程 | +|-------------------------|-------------------------------------------|-----------------------|-------------|--------------|----------| +| Go | [gorm](https://github.com/go-gorm/gorm) | v1.23.5 | Full | N/A | [使用 GORM 连接到 TiDB](/develop/dev-guide-sample-application-golang-gorm.md) | +| Go | [beego](https://github.com/beego/beego) | v2.0.3 | Full | N/A | N/A | +| Go | [upper/db](https://github.com/upper/db) | v4.5.2 | Full | N/A | N/A | +| Go | [xorm](https://gitea.com/xorm/xorm) | v1.3.1 | Full | N/A | N/A | +| Java | [Hibernate](https://hibernate.org/orm/) | 6.1.0.Final | Full | N/A | [使用 Hibernate 连接到 TiDB](/develop/dev-guide-sample-application-java-hibernate.md) | +| Java | [MyBatis](https://mybatis.org/mybatis-3/) | v3.5.10 | Full | N/A | [使用 MyBatis 连接到 TiDB](/develop/dev-guide-sample-application-java-mybatis.md) | +| Java | [Spring Data JPA](https://spring.io/projects/spring-data-jpa/) | 2.7.2 | Full | N/A | [使用 Spring Boot 连接到 TiDB](/develop/dev-guide-sample-application-java-spring-boot.md) | +| Java | [jOOQ](https://github.com/jOOQ/jOOQ) | v3.16.7 (Open Source) | Full | N/A | N/A | +| Ruby | [Active Record](https://guides.rubyonrails.org/active_record_basics.html) | v7.0 | Full | N/A | [使用 Rails 框架和 ActiveRecord ORM 连接到 TiDB](/develop/dev-guide-sample-application-ruby-rails.md) | +| JavaScript / TypeScript | [Sequelize](https://sequelize.org/) | v6.20.1 | Full | N/A | [使用 Sequelize 连接到 TiDB](/develop/dev-guide-sample-application-nodejs-sequelize.md) | +| JavaScript / Typescript | [Prisma](https://www.prisma.io/) | 4.16.2 | Full | N/A | [使用 Prisma 连接到 TiDB](/develop/dev-guide-sample-application-nodejs-prisma.md) | +| JavaScript / Typescript | [TypeORM](https://typeorm.io/) | v0.3.17 | Full | N/A | [使用 TypeORM 连接到 TiDB](/develop/dev-guide-sample-application-nodejs-typeorm.md) | +| Python | [Django](https://www.djangoproject.com/) | v4.2 | Full | [django-tidb](https://github.com/pingcap/django-tidb) | [使用 Django 连接到 TiDB](/develop/dev-guide-sample-application-python-django.md) | +| Python | [SQLAlchemy](https://www.sqlalchemy.org/) | v1.4.37 | Full | N/A | [使用 SQLAlchemy 连接到 TiDB](/develop/dev-guide-sample-application-python-sqlalchemy.md) | ## GUI @@ -189,4 +57,5 @@ PingCAP 与开源社区合作，通过三方工具提供以下支持： |-----------------------------------------------------------|-----------------------|---------------|-----| | [JetBrains DataGrip](https://www.jetbrains.com/datagrip/) | 2023.2.1 | Full | N/A | | [DBeaver](https://dbeaver.io/) | 23.0.3 | Full | N/A | -| [Visual Studio Code](https://code.visualstudio.com/) | 1.72.0 | Full | N/A | \ No newline at end of file +| [Visual Studio Code](https://code.visualstudio.com/) | 1.72.0 | Full | N/A | +| [Navicat](https://www.navicat.com) | 17.1.6 | Full | [使用 Navicat 连接到 TiDB](/develop/dev-guide-gui-navicat.md) | \ No newline at end of file diff --git a/develop/dev-guide-third-party-tools-compatibility.md b/develop/dev-guide-third-party-tools-compatibility.md index fa9713bcd716..56abec932fa4 100644 --- a/develop/dev-guide-third-party-tools-compatibility.md +++ b/develop/dev-guide-third-party-tools-compatibility.md @@ -1,6 +1,7 @@ --- title: 已知的第三方工具兼容问题 summary: 介绍在测试中发现的 TiDB 与第三方工具的兼容性问题。 +aliases: ['/zh/tidb/stable/dev-guide-third-party-tools-compatibility/','/zh/tidb/dev/dev-guide-third-party-tools-compatibility/','/zh/tidbcloud/dev-guide-third-party-tools-compatibility/'] --- # 已知的第三方工具兼容问题 @@ -40,7 +41,10 @@ MySQL 维护了一系列 [`Com_` 开头的服务端变量](https://dev.mysql.com **规避方法** -请勿使用这样的变量。在 MySQL 中 `Com_*` 常见的使用场景之一是监控。TiDB 的可观测性较为完善，无需从服务端变量进行查询。如需定制监控工具，可阅读 [TiDB 监控框架概述](/tidb-monitoring-framework.md)来获得更多信息。 +请勿使用这样的变量。在 MySQL 中 `Com_*` 常见的使用场景之一是监控。TiDB 的可观测性较为完善，无需从服务端变量进行查询。如需了解更多关于监控服务的信息，请参阅以下文档： + +- TiDB Cloud 文档：[监控 TiDB 集群](https://docs.pingcap.com/zh/tidbcloud/monitor-tidb-cluster)。 +- TiDB 文档：[TiDB 监控框架概述](/tidb-monitoring-framework.md)。 ### TiDB 错误日志区分 `TIMESTAMP` 与 `DATETIME` 类型 @@ -139,7 +143,7 @@ TiDB 暂不支持 `UpdatableResultSet`，即请勿指定 `ResultSet.CONCUR_UPDAT > **注意：** > -> `maxPerformance` 配置中包含多个参数，其中包括 `useLocalSessionState` 参数。要查看当前 MySQL Connector/J 中 `maxPerformance` 包含的具体参数，可参考 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) 或 [5.1 版本](https://github.com/mysql/mysql-connector-j/blob/release/5.1/src/com/mysql/jdbc/configs/maxPerformance.properties) 的配置文件。在使用 `maxPerformance` 时，请关闭 `useLocalTransactionState`，即 `useConfigs=maxPerformance&useLocalTransactionState=false`。 +> `maxPerformance` 配置中包含多个参数，其中包括 `useLocalSessionState` 参数。要查看当前 MySQL Connector/J 中 `maxPerformance` 包含的具体参数，可参考 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)或 [5.1 版本](https://github.com/mysql/mysql-connector-j/blob/release/5.1/src/com/mysql/jdbc/configs/maxPerformance.properties)的配置文件。在使用 `maxPerformance` 时，请关闭 `useLocalTransactionState`，即 `useConfigs=maxPerformance&useLocalTransactionState=false`。 MySQL Connector/J 已在 8.0.33 版本修复此问题。请使用 8.0.33 或更高版本。基于稳定性和性能考量，并结合到 8.0.x 版本已经停止更新，强烈建议升级 MySQL Connector/J 到[最新的 GA 版本](https://dev.mysql.com/downloads/connector/j/)。 diff --git a/develop/dev-guide-overview.md b/develop/dev-guide-tidb-basics.md similarity index 64% rename from develop/dev-guide-overview.md rename to develop/dev-guide-tidb-basics.md index 257c78013cec..58709f7a3005 100644 --- a/develop/dev-guide-overview.md +++ b/develop/dev-guide-tidb-basics.md @@ -1,30 +1,22 @@ --- -title: 开发者手册概览 -summary: 整体叙述了开发者手册，罗列了开发者手册的大致脉络。 +title: TiDB 基础知识 +summary: 介绍 TiDB 的基础知识，包括事务机制和应用程序与 TiDB 交互的方式。 aliases: ['/zh/tidb/dev/developer-guide-overview'] --- -# 开发者手册概览 - -本文是为应用程序开发者所编写的，如果你对 TiDB 的内部原理感兴趣，或希望参与到 TiDB 的开发中来，那么可前往阅读 [TiDB Kernel Development Guide](https://pingcap.github.io/tidb-dev-guide/) 来获取更多 TiDB 的相关信息。 - -本手册将展示如何使用 TiDB 来快速构建一个应用，并且阐述使用 TiDB 期间可能出现的场景以及可能会遇到的问题。因此，在阅读此页面之前，建议你先行阅读 [TiDB 数据库快速上手指南](/quick-start-with-tidb.md)。 - -此外，你还可以通过视频的形式学习免费的 [TiDB SQL 开发在线课程](https://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)。 - -## TiDB 基础 +# TiDB 基础知识 在你开始使用 TiDB 之前，你需要了解一些关于 TiDB 数据库的一些重要工作机制： - 阅读 [TiDB 事务概览](/transaction-overview.md)来了解 TiDB 的事务运作方式或查看[为应用开发程序员准备的事务说明](/develop/dev-guide-transaction-overview.md)查看应用开发程序员需要了解的事务部分。 -- 学习免费在线课程 [TiDB 架构与特点](https://learn.pingcap.com/learner/course/600003/?utm_source=docs-cn-dev-guide)，了解构建 TiDB 分布式数据库集群的核心组件及其概念。 +- 学习免费在线课程 [TiDB 架构与特点](https://learn.pingcap.cn/learner/course/600003?utm_source=docs-cn-dev-guide)，了解构建 TiDB 分布式数据库集群的核心组件及其概念。 - 了解[应用程序与 TiDB 交互的方式](#应用程序与-tidb-交互的方式)。 ## TiDB 事务机制 TiDB 支持分布式事务，而且提供[乐观事务](/optimistic-transaction.md)与[悲观事务](/pessimistic-transaction.md)两种事务模式。TiDB 当前版本中默认采用 **悲观事务** 模式，这让你在 TiDB 事务时可以像使用传统的单体数据库 (如: MySQL) 事务一样。 -你可以使用 [BEGIN](/sql-statements/sql-statement-begin.md) 开启一个事务，或者使用 `BEGIN PESSIMISTIC` 显式的指定开启一个**悲观事务**，使用 `BEGIN OPTIMISTIC` 显式的指定开启一个**乐观事务**。随后，使用 [COMMIT](/sql-statements/sql-statement-commit.md) 提交事务，或使用 [ROLLBACK](/sql-statements/sql-statement-rollback.md) 回滚事务。 +你可以使用 [`BEGIN`](/sql-statements/sql-statement-begin.md) 开启一个事务，或者使用 `BEGIN PESSIMISTIC` 显式的指定开启一个**悲观事务**，使用 `BEGIN OPTIMISTIC` 显式的指定开启一个**乐观事务**。随后，使用 [`COMMIT`](/sql-statements/sql-statement-commit.md) 提交事务，或使用 [`ROLLBACK`](/sql-statements/sql-statement-rollback.md) 回滚事务。 TiDB 会为你保证 `BEGIN` 开始到 `COMMIT` 或 `ROLLBACK` 结束间的所有语句的原子性，即在这期间的所有语句全部成功，或者全部失败。用以保证你在应用开发时所需的数据一致性。 @@ -47,3 +39,9 @@ TiDB 高度兼容 MySQL 协议，TiDB 支持[大多数 MySQL 的语法及特性] - [事务](/develop/dev-guide-transaction-overview.md) - [优化 SQL 性能](/develop/dev-guide-optimize-sql-overview.md) - [示例程序](/develop/dev-guide-sample-application-java-spring-boot.md) + +## 需要帮助？ + +- 在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [提交 TiDB 工单](/support.md) \ No newline at end of file diff --git a/develop/dev-guide-tidb-crud-sql.md b/develop/dev-guide-tidb-crud-sql.md index 4a2396c8c11c..0a75b68c4437 100644 --- a/develop/dev-guide-tidb-crud-sql.md +++ b/develop/dev-guide-tidb-crud-sql.md @@ -1,7 +1,7 @@ --- title: 使用 TiDB 的增删改查 SQL summary: 简单介绍 TiDB 的增删改查 SQL。 -aliases: ['/zh/tidb/dev/tidb-crud-sql'] +aliases: ['/zh/tidb/dev/tidb-crud-sql','/zh/tidb/stable/dev-guide-tidb-crud-sql/','/zh/tidb/dev/dev-guide-tidb-crud-sql/','/zh/tidbcloud/dev-guide-tidb-crud-sql/'] --- # 使用 TiDB 的增删改查 SQL @@ -10,7 +10,7 @@ aliases: ['/zh/tidb/dev/tidb-crud-sql'] ## 在开始之前 -请确保你已经连接到 TiDB 集群，若未连接，请参考[使用 TiDB Cloud Serverless 构建 TiDB 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-cloud-serverless-集群)来创建一个 TiDB Cloud Serverless 集群。 +请确保你已经连接到 TiDB 集群，若未连接，请参考[使用 {{{ .starter }}} 构建 TiDB 集群](/develop/dev-guide-build-cluster-in-cloud.md#step-1-create-a-tidb-cloud-cluster)来创建一个 {{{ .starter }}} 集群。 ## 基本 SQL 操作 diff --git a/develop/dev-guide-time-to-live.md b/develop/dev-guide-time-to-live.md new file mode 100644 index 000000000000..257cc7d59ad5 --- /dev/null +++ b/develop/dev-guide-time-to-live.md @@ -0,0 +1,69 @@ +--- +title: 使用 TTL (Time to Live) 定期删除过期数据 +summary: 了解如何利用 TiDB 的 TTL 功能自动定期删除过期数据。 +--- + +# 使用 TTL (Time to Live) 定期删除过期数据 + +在应用开发中，一些数据通常只在特定时间内具有价值。例如，验证码通常只需保留几分钟，短链接可能仅在活动期间有效，而访问日志或中间计算结果往往只需保存几个月。 + +TiDB 的 [TTL (Time to Live)](/time-to-live.md) 功能提供了一种行级别的生命周期控制策略，能帮助你**自动、定期**地删除这些过期数据，而无需编写复杂的定时任务脚本。 + +## 适用场景 + +TTL 旨在解决“过期后不再具有业务价值”的数据清理问题，适合以下场景： + +- 定期删除验证码、短网址记录 +- 定期删除不需要的历史订单 +- 自动删除计算的中间结果 + +> **注意：** +> +> TTL 任务在后台周期执行，因此不保证数据在过期后立即被删除。 + +## 快速上手 + +你可以在建表时直接配置 TTL 属性，也可以对现有表进行修改。以下章节列出了使用 TTL 定期删除过期数据的基本示例。完整的示例和 TTL 使用限制，以及 TTL 与其他工具或功能的兼容性请参考 [TTL (Time to Live)](/time-to-live.md)。 + +### 创建带 TTL 的表 + +如需创建一个存储即时消息的表 `app_messages`，并且希望消息在创建 3 个月后自动删除，可以执行以下语句： + +```sql +CREATE TABLE app_messages ( + id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY, + sender_id INT, + msg_content TEXT, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +) TTL = `created_at` + INTERVAL 3 MONTH; +``` + +其中，`TTL = ...` 用于定义过期策略，`created_at` 表示数据的创建时间，`INTERVAL 3 MONTH` 设置了表中行的最长存活时间为 3 个月。 + +### 为现有表增加 TTL + +当你已经有一张表 `app_logs`，如需为该表新增自动清理功能（例如只保留 1 个月的数据），可以执行以下语句： + +```sql +ALTER TABLE app_logs TTL = `created_at` + INTERVAL 1 MONTH; +``` + +### 调整 TTL 时长 + +如需调整表 `app_logs` 的 TTL 时长，可以执行以下语句： + +```sql +ALTER TABLE app_logs TTL = `created_at` + INTERVAL 6 MONTH; +``` + +### 关闭 TTL 功能 + +如需关闭表 `app_logs` 的 TTL 功能，可以执行以下语句： + +```sql +ALTER TABLE app_logs TTL_ENABLE = 'OFF'; +``` + +## 另请参阅 + +- [TTL (Time to Live)](/time-to-live.md) diff --git a/develop/dev-guide-timeouts-in-tidb.md b/develop/dev-guide-timeouts-in-tidb.md index c201e3a50f9c..17b8c3cb6ad7 100644 --- a/develop/dev-guide-timeouts-in-tidb.md +++ b/develop/dev-guide-timeouts-in-tidb.md @@ -1,7 +1,7 @@ --- title: TiDB 中的各种超时 summary: 简单介绍 TiDB 中的各种超时，为排查错误提供依据。 -aliases: ['/zh/tidb/dev/timeouts-in-tidb'] +aliases: ['/zh/tidb/dev/timeouts-in-tidb','/zh/tidb/stable/dev-guide-timeouts-in-tidb/','/zh/tidb/dev/dev-guide-timeouts-in-tidb/','/zh/tidbcloud/dev-guide-timeouts-in-tidb/'] --- # TiDB 中的各种超时 @@ -36,7 +36,7 @@ TiDB 的事务的实现采用了 MVCC（多版本并发控制）机制，当新 > > 在这些场景中，你必须使用 `tikv_gc_life_time` 提前手动调长 GC 时间，以避免因为导出过程中发生 GC 导致导出失败。详见 TiDB 工具 Dumpling 的[手动设置 TiDB GC 时间](/dumpling-overview.md#手动设置-tidb-gc-时间)。 -更多关于 GC 的信息，请参考 [GC 机制简介](https://pingcap.com/docs-cn/stable/reference/garbage-collection/overview/)文档。 +更多关于 GC 的信息，请参考 [GC 机制简介](/garbage-collection-overview.md)文档。 ## 事务超时 @@ -48,16 +48,20 @@ TiDB 的事务的实现采用了 MVCC（多版本并发控制）机制，当新 ## SQL 执行时间超时 -TiDB 还提供了一个系统变量来限制单条 SQL 语句的执行时间，仅对“只读”语句生效：`max_execution_time`，它的默认值为 0，表示无限制。`max_execution_time` 的单位为 ms，但实际精度在 100ms 级别，而非更准确的毫秒级别。 +TiDB 还提供了一个系统变量来限制单条 SQL 语句的执行时间，仅对 `SELECT` 语句（包括 `SELECT ... FOR UPDATE`）生效：`max_execution_time`，它的默认值为 0，表示无限制。`max_execution_time` 的单位为 ms，但实际精度在 100ms 级别，而非更准确的毫秒级别。 ## JDBC 查询超时 -MySQL jdbc 的查询超时设置 `setQueryTimeout()` 对 TiDB 不起作用。这是因为现实客户端感知超时时，向数据库发送一个 KILL 命令。但是由于 tidb-server 是负载均衡的，为防止在错误的 tidb-server 上终止连接，tidb-server 不会执行这个 KILL。这时就要用 `MAX_EXECUTION_TIME` 实现查询超时的效果。 +从 v6.1.0 起，当 [`enable-global-kill`](/tidb-configuration-file.md#enable-global-kill-从-v610-版本开始引入) 配置项为默认值 `true` 时，你可以使用 MySQL JDBC 提供的 `setQueryTimeout()` 方法来控制查询的超时时间。 + +>**注意:** +> +> 当 TiDB 版本低于 v6.1.0 或 [`enable-global-kill`](/tidb-configuration-file.md#enable-global-kill-从-v610-版本开始引入) 为 `false` 时，`setQueryTimeout()` 对 TiDB 不起作用。这是因为查询超时后，客户端会向数据库发送一条 `KILL` 命令。但是由于 TiDB 服务是负载均衡的，为防止 `KILL` 命令在错误的 TiDB 节点上终止连接，TiDB 不会执行该命令。此时，可以通过设置 `max_execution_time` 实现查询超时控制。 TiDB 提供了三个与 MySQL 兼容的超时控制参数： - **wait_timeout**，控制与 Java 应用连接的非交互式空闲超时时间。在 TiDB v5.4 及以上版本中，默认值为 `28800` 秒，即空闲超时为 8 小时。在 v5.4 之前，默认值为 `0`，即没有时间限制。 - **interactive_timeout**，控制与 Java 应用连接的交互式空闲超时时间，默认值为 8 小时。 -- **max_execution_time**，控制连接中 SQL 执行的超时时间，仅对“只读”语句生效，默认值是 0，即允许连接无限忙碌（一个 SQL 语句执行无限的长的时间）。 +- **max_execution_time**，控制连接中 SQL 执行的超时时间，仅对 `SELECT` 语句（包括 `SELECT ... FOR UPDATE`）生效，默认值是 0，即允许连接无限忙碌（一个 SQL 语句执行无限的长的时间）。 但在实际生产环境中，空闲连接和一直无限执行的 SQL 对数据库和应用都有不好的影响。你可以通过在应用的连接字符串中配置这两个 session 级的变量来避免空闲连接和执行时间过长的 SQL 语句。例如，设置 `sessionVariables=wait_timeout=3600（1 小时）`和 `sessionVariables=max_execution_time=300000（5 分钟）`。 diff --git a/develop/dev-guide-transaction-overview.md b/develop/dev-guide-transaction-overview.md index 41e6be8091f5..1d0c2dec0f84 100644 --- a/develop/dev-guide-transaction-overview.md +++ b/develop/dev-guide-transaction-overview.md @@ -1,6 +1,7 @@ --- title: 事务概览 summary: 简单介绍 TiDB 中的事务。 +aliases: ['/zh/tidb/stable/dev-guide-transaction-overview/','/zh/tidb/dev/dev-guide-transaction-overview/','/zh/tidbcloud/dev-guide-transaction-overview/'] --- # 事务概览 @@ -9,7 +10,7 @@ TiDB 支持完整的分布式事务，提供[乐观事务](/optimistic-transacti ## 拓展学习视频 -[TiDB 特有功能与事务控制 - TiDB v6](https://learn.pingcap.com/learner/course/750002/?utm_source=docs-cn-dev-guide)：了解可用于应用程序的 TiDB 独特功能，如 `AUTO_RANDOM` 及 `AUTO_INCREMENT` 特别注意事项、全局临时表、如何使用 TiFlash 启用 HTAP 以及放置策略等。 +[TiDB 特有功能与事务控制 - TiDB v6](https://learn.pingcap.cn/learner/course/750002?utm_source=docs-cn-dev-guide)：了解可用于应用程序的 TiDB 独特功能，如 `AUTO_RANDOM` 及 `AUTO_INCREMENT` 特别注意事项、全局临时表、如何使用 TiFlash 启用 HTAP 以及放置策略等。 ## 通用语句 @@ -155,4 +156,4 @@ mysql> SET TRANSACTION ISOLATION LEVEL SERIALIZABLE; ERROR 8048 (HY000): The isolation level 'SERIALIZABLE' is not supported. Set tidb_skip_isolation_level_check=1 to skip this error ``` -TiDB 实现了快照隔离 (Snapshot Isolation, SI) 级别的一致性。为与 MySQL 保持一致，又称其为“可重复读”。该隔离级别不同于 [ANSI 可重复读隔离级别](/transaction-isolation-levels.md#与-ansi-可重复读隔离级别的区别) 和 [MySQL 可重复读隔离级别](/transaction-isolation-levels.md#与-mysql-可重复读隔离级别的区别)。更多细节请阅读 [TiDB 事务隔离级别](/transaction-isolation-levels.md)。 +TiDB 实现了快照隔离 (Snapshot Isolation, SI) 级别的一致性。为与 MySQL 保持一致，又称其为“可重复读”。该隔离级别不同于 [ANSI 可重复读隔离级别](/transaction-isolation-levels.md#与-ansi-可重复读隔离级别的区别)和 [MySQL 可重复读隔离级别](/transaction-isolation-levels.md#与-mysql-可重复读隔离级别的区别)。更多细节请阅读 [TiDB 事务隔离级别](/transaction-isolation-levels.md)。 diff --git a/develop/dev-guide-transaction-restraints.md b/develop/dev-guide-transaction-restraints.md index 63746f14ab42..38bc47ab1546 100644 --- a/develop/dev-guide-transaction-restraints.md +++ b/develop/dev-guide-transaction-restraints.md @@ -1,7 +1,7 @@ --- title: 事务限制 summary: 介绍 TiDB 中的事务限制。 -aliases: ['/zh/tidb/dev/transaction-restraints'] +aliases: ['/zh/tidb/dev/transaction-restraints','/zh/tidb/stable/dev-guide-transaction-restraints/','/zh/tidb/dev/dev-guide-transaction-restraints/','/zh/tidbcloud/dev-guide-transaction-restraints/'] --- # 事务限制 @@ -724,9 +724,9 @@ mysql> SELECT * FROM T2; 另外注意，无论是大小限制还是行数限制，还要考虑事务执行过程中，TiDB 做编码以及事务额外 Key 的开销。在使用的时候，为了使性能达到最优，建议每 100 ～ 500 行写入一个事务。 -## 自动提交的 SELECT FOR UPDATE 语句不会等锁 +## 自动提交的 `SELECT FOR UPDATE` 语句不会等锁 -自动提交下的 SELECT FOR UPDATE 目前不会加锁。效果如下图所示： +目前，自动提交下的 `SELECT FOR UPDATE` 不会加锁。下图显示了在两个不同会话中的效果： ![TiDB中的情况](/media/develop/autocommit_selectforupdate_nowaitlock.png) diff --git a/develop/dev-guide-transaction-troubleshoot.md b/develop/dev-guide-transaction-troubleshoot.md index ffde9c231f4f..1a2e2f9d5beb 100644 --- a/develop/dev-guide-transaction-troubleshoot.md +++ b/develop/dev-guide-transaction-troubleshoot.md @@ -1,7 +1,7 @@ --- title: 事务错误处理 summary: 介绍 TiDB 中的事务错误处理办法。 -aliases: ['/zh/tidb/dev/transaction-troubleshoot'] +aliases: ['/zh/tidb/dev/transaction-troubleshoot','/zh/tidb/stable/dev-guide-transaction-troubleshoot/','/zh/tidb/dev/dev-guide-transaction-troubleshoot/','/zh/tidbcloud/dev-guide-transaction-troubleshoot/'] --- # 事务错误处理 diff --git a/develop/dev-guide-troubleshoot-overview.md b/develop/dev-guide-troubleshoot-overview.md index 61af376e934e..b38f663c02dc 100644 --- a/develop/dev-guide-troubleshoot-overview.md +++ b/develop/dev-guide-troubleshoot-overview.md @@ -1,7 +1,7 @@ --- title: SQL 或事务问题 summary: 学习诊断在应用开发过程中可能产生的 SQL 或事务问题的方法。 -aliases: ['/zh/tidb/dev/troubleshoot-overview'] +aliases: ['/zh/tidb/dev/troubleshoot-overview','/zh/tidb/stable/dev-guide-troubleshoot-overview/','/zh/tidb/dev/dev-guide-troubleshoot-overview/','/zh/tidbcloud/dev-guide-troubleshoot-overview/'] --- # SQL 或事务问题 @@ -10,11 +10,28 @@ aliases: ['/zh/tidb/dev/troubleshoot-overview'] ## SQL 操作常见问题 -如果你想提高 SQL 的性能，可以阅读 [SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)来避免一些常见的性能问题。然后如果依然存在性能问题，推荐阅读： +如果你想提高 SQL 的性能，可以阅读 [SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)来避免一些常见的性能问题。 + +然后如果依然存在性能问题，推荐阅读： + + + +
+ +- [慢查询](https://docs.pingcap.com/zh/tidbcloud/tune-performance/#慢查询) +- [SQL 语句分析](https://docs.pingcap.com/zh/tidbcloud/tune-performance/#语句分析) +- [Key Visualizer](https://docs.pingcap.com/zh/tidbcloud/tune-performance/#key-visualizer) + +
+ +
- [分析慢查询](/analyze-slow-queries.md) - [使用 Top SQL 定位系统资源消耗过多的查询](/dashboard/top-sql.md) +
+ + 如果你遇到了一些关于 SQL 操作的问题，可以阅读 [SQL 操作常见问题](/faq/sql-faq.md)。 ## 事务错误处理 @@ -25,4 +42,5 @@ aliases: ['/zh/tidb/dev/troubleshoot-overview'] - [不支持的功能特性](/mysql-compatibility.md#不支持的功能特性) - [集群管理 FAQ](/faq/manage-cluster-faq.md) +- [TiDB Cloud 产品 FAQ](https://docs.pingcap.com/zh/tidbcloud/tidb-cloud-faq) - [TiDB 产品 FAQ](/faq/tidb-faq.md) diff --git a/develop/dev-guide-unique-serial-number-generation.md b/develop/dev-guide-unique-serial-number-generation.md index 0227d26b8eab..9d34279e16fb 100644 --- a/develop/dev-guide-unique-serial-number-generation.md +++ b/develop/dev-guide-unique-serial-number-generation.md @@ -1,7 +1,7 @@ --- title: 唯一序列号生成方案 summary: 唯一序列号生成方案，为自行生成唯一 ID 的开发者提供帮助。 -aliases: ['/zh/tidb/dev/unique-serial-number-generation'] +aliases: ['/zh/tidb/dev/unique-serial-number-generation','/zh/tidb/stable/dev-guide-unique-serial-number-generation/','/zh/tidb/dev/dev-guide-unique-serial-number-generation/','/zh/tidbcloud/dev-guide-unique-serial-number-generation/'] --- # 唯一序列号生成方案 diff --git a/develop/dev-guide-unstable-result-set.md b/develop/dev-guide-unstable-result-set.md index 607fac75fe2b..fcaa68a0c6ff 100644 --- a/develop/dev-guide-unstable-result-set.md +++ b/develop/dev-guide-unstable-result-set.md @@ -1,7 +1,7 @@ --- title: 结果集不稳定 summary: 结果集不稳定错误的处理办法。 -aliases: ['/zh/tidb/dev/unstable-result-set'] +aliases: ['/zh/tidb/dev/unstable-result-set','/zh/tidb/stable/dev-guide-unstable-result-set/','/zh/tidb/dev/dev-guide-unstable-result-set/','/zh/tidbcloud/dev-guide-unstable-result-set/'] --- # 结果集不稳定 @@ -120,7 +120,7 @@ mysql> select a.class, a.stuname, b.course, b.courscore from stu_info a join stu ``` -当遇到相同的 order by 值时，排序结果不稳定。为减少随机性，应当尽可能保持 order by 值的唯一性。不能保证唯一的继续加，保证 order by 的字段组合是唯一时，结果才能唯一。 +当 order by 值相同时，结果会不稳定。为了减少随机性，order by 值应该是唯一的。如果不能保证唯一性，则需要添加更多的 order by 字段，直到 order by 字段的组合是唯一的，这样结果才会稳定。 ## 由于 group_concat() 中没有使用 order by 导致结果集不稳定 diff --git a/develop/dev-guide-update-data.md b/develop/dev-guide-update-data.md index 75c34a8b9066..7f09824e4507 100644 --- a/develop/dev-guide-update-data.md +++ b/develop/dev-guide-update-data.md @@ -1,7 +1,7 @@ --- title: 更新数据 summary: 更新数据、批量更新数据的方法、最佳实践及例子。 -aliases: ['/zh/tidb/dev/update-data'] +aliases: ['/zh/tidb/dev/update-data','/zh/tidb/stable/dev-guide-update-data/','/zh/tidb/dev/dev-guide-update-data/','/zh/tidbcloud/dev-guide-update-data/'] --- # 更新数据 @@ -15,7 +15,7 @@ aliases: ['/zh/tidb/dev/update-data'] 在阅读本页面之前，你需要准备以下事项： -- [使用 TiDB Cloud Serverless 构建 TiDB 集群](/develop/dev-guide-build-cluster-in-cloud.md) +- [使用 {{{ .starter }}} 构建 TiDB 集群](/develop/dev-guide-build-cluster-in-cloud.md) - 阅读[数据库模式概览](/develop/dev-guide-schema-design-overview.md)，并[创建数据库](/develop/dev-guide-create-database.md)、[创建表](/develop/dev-guide-create-table.md)、[创建二级索引](/develop/dev-guide-create-secondary-indexes.md) - 若需使用 `UPDATE` 语句更新数据，需先[插入数据](/develop/dev-guide-insert-data.md) diff --git a/develop/dev-guide-use-common-table-expression.md b/develop/dev-guide-use-common-table-expression.md index 4651253c474b..63816c9a3b99 100644 --- a/develop/dev-guide-use-common-table-expression.md +++ b/develop/dev-guide-use-common-table-expression.md @@ -1,7 +1,7 @@ --- title: 公共表表达式 (CTE) summary: 介绍 TiDB 公共表表达式能力，用以简化 SQL。 -aliases: ['/zh/tidb/dev/use-common-table-expression'] +aliases: ['/zh/tidb/dev/use-common-table-expression','/zh/tidb/stable/dev-guide-use-common-table-expression/','/zh/tidb/dev/dev-guide-use-common-table-expression/','/zh/tidbcloud/dev-guide-use-common-table-expression/'] --- # 公共表表达式 (CTE) diff --git a/develop/dev-guide-use-follower-read.md b/develop/dev-guide-use-follower-read.md index c76e9bfbf1ca..a821ea3d3ceb 100644 --- a/develop/dev-guide-use-follower-read.md +++ b/develop/dev-guide-use-follower-read.md @@ -1,7 +1,7 @@ --- title: Follower Read summary: 使用 Follower Read 在特定情况下加速查询。 -aliases: ['/zh/tidb/dev/use-follower-read'] +aliases: ['/zh/tidb/dev/use-follower-read','/zh/tidb/stable/dev-guide-use-follower-read/','/zh/tidb/dev/dev-guide-use-follower-read/','/zh/tidbcloud/dev-guide-use-follower-read/'] --- # Follower Read @@ -18,11 +18,15 @@ aliases: ['/zh/tidb/dev/use-follower-read'] ### 优化读热点 -你可以在 [TiDB Dashboard 流量可视化页面](/dashboard/dashboard-key-visualizer.md)当中通过可视化的方法分析你的应用程序是否存在热点 Region。你可以通过将「指标选择框」选择到 `Read (bytes)` 或 `Read (keys)` 查看是否存在读取热点 Region。 +你可以通过以下可视化的方法分析你的应用程序是否存在热点 Region。 -如果发现确实存在热点问题，你可以通过阅读 [TiDB 热点问题处理](/troubleshoot-hot-spot-issues.md)章节进行逐一排查，以便从应用程序层面上避免热点的产生。 +- TiDB Cloud：打开 [TiDB Cloud 控制台中的 Key Visualizer 页面](https://docs.pingcap.com/zh/tidbcloud/tune-performance/#key-visualizer)，将指标选择框选择到 `Read (bytes)` 或 `Read (keys)` 查看是否存在读取热点 Region。 -如果读取热点的确无法避免或者改动的成本很大，你可以尝试通过 Follower Read 功能将读取请求更好的负载均衡到 follower region。 +- TiDB：打开 [TiDB Dashboard 中的流量可视化页面](/dashboard/dashboard-key-visualizer.md)，将指标选择框选择到 `Read (bytes)` 或 `Read (keys)` 查看是否存在读取热点 Region。 + +如果发现确实存在热点问题，你可以参考 [TiDB 热点问题处理](/troubleshoot-hot-spot-issues.md)文档进行排查，以便从应用程序层面上避免热点的产生。 + +如果读取热点的确无法避免或者改动的成本很大，你可以尝试通过 Follower Read 功能将读取请求更好地负载均衡到 follower region。 ### 优化跨数据中心部署的延迟 @@ -39,7 +43,7 @@ aliases: ['/zh/tidb/dev/use-follower-read'] SET [GLOBAL] tidb_replica_read = 'follower'; ``` -你可以通过 [Follower Read 使用方式](/follower-read.md#使用方式) 了解该变量的更多细节。 +你可以通过 [Follower Read 使用方式](/follower-read.md#使用方式)了解该变量的更多细节。
@@ -136,4 +140,5 @@ public static class AuthorDAO { - [Follower Read](/follower-read.md) - [TiDB 热点问题处理](/troubleshoot-hot-spot-issues.md) +- [TiDB Cloud 控制台中的 Key Visualizer 页面](https://docs.pingcap.com/zh/tidbcloud/tune-performance/#key-visualizer) - [TiDB Dashboard 流量可视化页面](/dashboard/dashboard-key-visualizer.md) diff --git a/develop/dev-guide-use-stale-read.md b/develop/dev-guide-use-stale-read.md index 0c2e29b7dc36..b1812b840117 100644 --- a/develop/dev-guide-use-stale-read.md +++ b/develop/dev-guide-use-stale-read.md @@ -1,7 +1,7 @@ --- title: Stale Read summary: 使用 Stale Read 在特定情况下加速查询。 -aliases: ['/zh/tidb/dev/use-stale-read'] +aliases: ['/zh/tidb/dev/use-stale-read','/zh/tidb/stable/dev-guide-use-stale-read/','/zh/tidb/dev/dev-guide-use-stale-read/','/zh/tidbcloud/dev-guide-use-stale-read/'] --- # Stale Read diff --git a/develop/dev-guide-use-subqueries.md b/develop/dev-guide-use-subqueries.md index 1716a575bd8e..25ffa12a82ce 100644 --- a/develop/dev-guide-use-subqueries.md +++ b/develop/dev-guide-use-subqueries.md @@ -1,7 +1,7 @@ --- title: 子查询 summary: 介绍 TiDB 子查询功能。 -aliases: ['/zh/tidb/dev/use-subqueries'] +aliases: ['/zh/tidb/dev/use-subqueries','/zh/tidb/stable/dev-guide-use-subqueries/','/zh/tidb/dev/dev-guide-use-subqueries/','/zh/tidbcloud/dev-guide-use-subqueries/'] --- # 子查询 @@ -128,4 +128,4 @@ WHERE - [子查询相关的优化](/subquery-optimization.md) - [关联子查询去关联](/correlated-subquery-optimization.md) -- [TiDB 中的子查询优化技术](https://pingcap.com/zh/blog/tidb-optimization-for-subquery) +- [TiDB 中的子查询优化技术](https://tidb.net/blog/b997a44c) diff --git a/develop/dev-guide-use-temporary-tables.md b/develop/dev-guide-use-temporary-tables.md index 123a2a1df871..25c8de1505eb 100644 --- a/develop/dev-guide-use-temporary-tables.md +++ b/develop/dev-guide-use-temporary-tables.md @@ -1,7 +1,7 @@ --- title: 临时表 summary: 介绍 TiDB 临时表创建、删除、限制。 -aliases: ['/zh/tidb/dev/use-temporary-tables'] +aliases: ['/zh/tidb/dev/use-temporary-tables','/zh/tidb/stable/dev-guide-use-temporary-tables/','/zh/tidb/dev/dev-guide-use-temporary-tables/','/zh/tidbcloud/dev-guide-use-temporary-tables/'] --- # 临时表 diff --git a/develop/dev-guide-use-views.md b/develop/dev-guide-use-views.md index fc4711b289bd..90964c60d8d7 100644 --- a/develop/dev-guide-use-views.md +++ b/develop/dev-guide-use-views.md @@ -1,7 +1,7 @@ --- title: 视图 summary: 介绍 TiDB 中的视图功能。 -aliases: ['/zh/tidb/dev/use-views'] +aliases: ['/zh/tidb/dev/use-views','/zh/tidb/stable/dev-guide-use-views/','/zh/tidb/dev/dev-guide-use-views/','/zh/tidbcloud/dev-guide-use-views/'] --- # 视图 @@ -25,7 +25,7 @@ CREATE VIEW view_name AS query; 请注意，创建的视图名称不能与已有的视图或表重名。 -例如，在[多表连接查询](/develop/dev-guide-join-tables.md) 章节当中，通过 `JOIN` 语句连接 `books` 表和 `ratings` 表查询到了带有平均评分的书籍列表。为了方便后续查询，可以将该查询语句定义为一个视图，SQL 语句如下所示： +例如，在[多表连接查询](/develop/dev-guide-join-tables.md)章节当中，通过 `JOIN` 语句连接 `books` 表和 `ratings` 表查询到了带有平均评分的书籍列表。为了方便后续查询，可以将该查询语句定义为一个视图，SQL 语句如下所示： ```sql CREATE VIEW book_with_ratings AS diff --git a/develop/dev-guide-vector-search.md b/develop/dev-guide-vector-search.md new file mode 100644 index 000000000000..ed04258e554e --- /dev/null +++ b/develop/dev-guide-vector-search.md @@ -0,0 +1,61 @@ +--- +title: 向量搜索 +summary: 为应用开发者介绍 TiDB 中的向量搜索功能，包括相关概念、教程、集成方式以及参考文档。 +--- + +# 向量搜索 + +[向量搜索](/ai/concepts/vector-search-overview.md) 支持在文档、图像、音频和视频等多种数据类型上进行语义相似性搜索。熟悉 MySQL 的开发人员可以基于该功能轻松构建人工智能 (AI) 应用。 + +## 快速开始 + +要开始使用 TiDB 向量搜索，请参考以下文档： + +- [使用 SQL 开始向量搜索](/ai/quickstart-via-sql.md) +- [使用 Python 开始向量搜索](/ai/quickstart-via-python.md) + +## 自动嵌入（Auto Embedding） + +自动嵌入功能允许你直接使用纯文本进行向量搜索，而无需自行生成或提供向量。通过该功能，你可以直接插入文本数据，并使用文本查询进行语义搜索，TiDB 会在后台自动将文本转换为向量。 + +目前，TiDB 支持多种嵌入模型，例如 Amazon Titan、Cohere、Jina AI、OpenAI、Gemini、Hugging Face 以及 NVIDIA NIM。你可以根据需求选择合适的模型。更多信息，请参阅[自动嵌入概述](/ai/integrations/vector-search-auto-embedding-overview.md)。 + +## 集成 + +为提高开发效率，你可以将 TiDB 向量搜索与主流 AI 框架（如 LlamaIndex 和 LangChain）、嵌入服务（如 Jina AI）以及 ORM 库（如 SQLAlchemy、Peewee 和 Django ORM）进行集成。你可以根据自己的使用场景选择最合适的集成方式。 + +更多信息，请参阅[向量搜索集成概述](/ai/integrations/vector-search-integration-overview.md)。 + +## 文本搜索 + +与侧重语义相似性的向量搜索不同，全文搜索主要基于精确关键词进行文档检索。 + +在 RAG 场景中，为了提升检索质量，你可以将向量搜索与全文搜索结合使用。 + +| 场景 | 文档 | +|---------------|-------------| +| 使用 SQL 进行基于关键词的搜索 | [使用 SQL 进行全文搜索](/ai/guides/vector-search-full-text-search-sql.md) | +| 在 Python 应用中进行全文搜索 | [使用 Python 进行全文搜索](/ai/guides/vector-search-full-text-search-python.md) | +| 结合向量搜索与全文搜索以获得更优结果 | [混合搜索](/ai/guides/vector-search-hybrid-search.md) | + +## 性能优化 + +为了优化向量搜索查询的性能，你可以遵循一系列最佳实践，例如添加向量索引、监控索引构建进度、降低向量维度、排除向量列以及对索引进行预热。 + +关于这些最佳实践的详细说明，请参阅[提升向量搜索性能](/ai/reference/vector-search-improve-performance.md)。 + +## 限制 + +在实现向量搜索之前，请注意以下限制： + +- 单个向量的最大维度为 16383 +- 向量列不能作为主键、唯一索引或分区键 +- 向量类型与其他数据类型之间不支持直接类型转换（可使用字符串作为中间类型） + +完整限制列表，请参阅[向量搜索限制](/ai/reference/vector-search-limitations.md)。 + +## 参考 + +- [向量数据类型](/ai/reference/vector-search-data-types.md) +- [向量函数与运算符](/ai/reference/vector-search-functions-and-operators.md) +- [向量索引](/ai/reference/vector-search-index.md) \ No newline at end of file diff --git a/develop/dev-guide-wordpress.md b/develop/dev-guide-wordpress.md new file mode 100644 index 000000000000..cfa9437aa049 --- /dev/null +++ b/develop/dev-guide-wordpress.md @@ -0,0 +1,110 @@ +--- +title: 使用 TiDB Cloud Starter 运行 WordPress +summary: 学习如何使用 TiDB Cloud Starter 运行 WordPress。本教程将为你提供分步指导，让你在几分钟内运行 WordPress + TiDB Cloud Starter。 +aliases: ['/zh/tidbcloud/dev-guide-wordpress/'] +--- + +# 使用 TiDB Cloud Starter 运行 WordPress + +TiDB 是一个兼容 MySQL 的数据库，TiDB Cloud Starter 是一款全托管的 TiDB 云服务，[WordPress](https://github.com/WordPress) 是一个免费的开源内容管理系统 (CMS)，可以让用户创建和管理网站。WordPress 使用 PHP 编写，并使用 MySQL 数据库。 + +在本教程中，你可以学习如何免费使用 TiDB Cloud Starter 运行 WordPress。 + +> **注意：** +> +> 除了 TiDB Cloud Starter，本教程同样适用于 TiDB Cloud Essential、TiDB Cloud Dedicated 以及 TiDB 自托管集群。但强烈推荐使用 TiDB Cloud Starter 来运行 WordPress，以获得更高的性价比。 + +## 前提条件 + +要完成本教程，你需要： + +- 一个 TiDB Cloud Starter 集群。如果你还没有集群，请按照[创建 TiDB Cloud Starter 集群](/develop/dev-guide-build-cluster-in-cloud.md)来创建属于你自己的 TiDB Cloud 集群。 + +## 使用 TiDB Cloud Starter 运行 WordPress + +本节将演示如何使用 TiDB Cloud Starter 运行 WordPress。 + +### 第 1 步：克隆 WordPress 示例仓库 + +在终端窗口中运行以下命令，克隆示例代码仓库： + +```shell +git clone https://github.com/Icemap/wordpress-tidb-docker.git +cd wordpress-tidb-docker +``` + +### 第 2 步：安装依赖 + +1. 示例仓库需要 [Docker](https://www.docker.com/) 和 [Docker Compose](https://docs.docker.com/compose/) 来启动 WordPress。如果你已经安装了它们，可以跳过此步骤。强烈建议你在 Linux 环境（如 Ubuntu）下运行 WordPress。运行以下命令安装 Docker 和 Docker Compose： + + ```shell + sudo sh install.sh + ``` + +2. 示例仓库包含了 [TiDB Compatibility Plugin](https://github.com/pingcap/wordpress-tidb-plugin) 作为子模块。运行以下命令以更新子模块： + + ```shell + git submodule update --init --recursive + ``` + +### 第 3 步：配置连接信息 + +配置 WordPress 数据库到 TiDB Cloud Starter 的连接。 + +1. 进入 [**Clusters**](https://tidbcloud.com/project/clusters) 页面，然后点击目标集群的名称，进入其概览页面。 + +2. 点击右上角的 **Connect**。此时会弹出连接对话框。 + +3. 确保连接对话框中的配置与你的操作环境一致。 + + - **Connection Type** 设置为 `Public`。 + - **Connect With** 设置为 `WordPress`。 + - **Operating System** 设置为 `Debian/Ubuntu/Arch`。 + - **Database** 设置为你想要使用的数据库，例如 `test`。 + +4. 点击 **Generate Password** 生成一个随机密码。 + + > **Tip:** + > + > 如果你之前已经创建过密码，可以继续使用原有密码，或者点击 **Reset Password** 生成一个新密码。 + +5. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： + + ```shell + cp .env.example .env + ``` + +6. 将对应的连接字符串复制粘贴到 `.env` 文件中。示例结果如下： + + ```dotenv + TIDB_HOST='{HOST}' # e.g. gateway01.ap-northeast-1.prod.aws.tidbcloud.com + TIDB_PORT='4000' + TIDB_USER='{USERNAME}' # e.g. xxxxxx.root + TIDB_PASSWORD='{PASSWORD}' + TIDB_DB_NAME='test' + ``` + + 请确保将 `{}` 占位符替换为你在连接对话框中获得的连接参数。默认情况下，你的 TiDB Cloud Starter 自带一个 `test` 数据库。如果你已经在 TiDB Cloud Starter 集群中创建了其他数据库，可以将 `test` 替换为你的数据库名。 + +7. 保存 `.env` 文件。 + +### 第 4 步：使用 TiDB Cloud Starter 启动 WordPress + +1. 执行以下命令，将 WordPress 作为 Docker 容器运行： + + ```shell + docker compose up -d + ``` + +2. 通过访问 [localhost](http://localhost/)（如果你在本地机器上启动容器）或 `http://`（如果 WordPress 运行在远程机器上）来设置你的 WordPress 站点。 + +### 第 5 步：确认数据库连接 + +1. 在 TiDB Cloud 控制台关闭集群的连接对话框，并打开 **SQL Editor** 页面。 +2. 在左侧的 **Schemas** 标签下，点击你连接到 WordPress 的数据库。 +3. 确认你现在可以在该数据库的表列表中看到 WordPress 的表（如 `wp_posts` 和 `wp_comments`）。 + +## 需要帮助？ + +- 在 [AskTUG 论坛](https://asktug.com/?utm_source=docs-cn-dev-guide) 上提问 +- [提交 TiDB Cloud 工单](https://tidb.support.pingcap.com/servicedesk/customer/portals) \ No newline at end of file diff --git a/best-practices/java-app-best-practices.md b/develop/java-app-best-practices.md similarity index 80% rename from best-practices/java-app-best-practices.md rename to develop/java-app-best-practices.md index 689d5ca79ae5..987f32653708 100644 --- a/best-practices/java-app-best-practices.md +++ b/develop/java-app-best-practices.md @@ -1,7 +1,7 @@ --- title: 开发 Java 应用使用 TiDB 的最佳实践 -aliases: ['/docs-cn/dev/best-practices/java-app-best-practices/','/docs-cn/dev/reference/best-practices/java-app/','/docs-cn/dev/reference/best-practices/using-tidb-in-java/'] summary: 本文介绍了开发 Java 应用程序使用 TiDB 的常见问题与解决办法。TiDB 是高度兼容 MySQL 协议的数据库，基于 MySQL 开发的 Java 应用的最佳实践也多适用于 TiDB。 +aliases: ['/zh/tidb/stable/java-app-best-practices/','/zh/tidb/dev/java-app-best-practices/','/docs-cn/dev/best-practices/java-app-best-practices/','/docs-cn/dev/reference/best-practices/java-app/','/docs-cn/dev/reference/best-practices/using-tidb-in-java/'] --- # 开发 Java 应用使用 TiDB 的最佳实践 @@ -13,7 +13,7 @@ summary: 本文介绍了开发 Java 应用程序使用 TiDB 的常见问题与 通常 Java 应用中和数据库相关的常用组件有： - 网络协议：客户端通过标准 [MySQL 协议](https://dev.mysql.com/doc/dev/mysql-server/latest/PAGE_PROTOCOL.html)和 TiDB 进行网络交互。 -- JDBC API 及实现：Java 应用通常使用 [JDBC (Java Database Connectivity)](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) 来访问数据库。JDBC 定义了访问数据库 API，而 JDBC 实现完成标准 API 到 MySQL 协议的转换，常见的 JDBC 实现是 [MySQL Connector/J](https://github.com/mysql/mysql-connector-j)，此外有些用户可能使用 [MariaDB Connector/J](https://mariadb.com/kb/en/library/about-mariadb-connector-j/#about-mariadb-connectorj)。 +- JDBC API 及实现：Java 应用通常使用 [JDBC (Java Database Connectivity)](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) 来访问数据库。JDBC 定义了访问数据库 API，而 JDBC 实现完成标准 API 到 MySQL 协议的转换，常见的 JDBC 实现是 [MySQL Connector/J](https://github.com/mysql/mysql-connector-j)，此外有些用户可能使用 [MariaDB Connector/J](https://mariadb.com/docs/connectors/mariadb-connector-j/about-mariadb-connector-j#about-mariadb-connectorj)。 - 数据库连接池：为了避免每次创建连接，通常应用会选择使用数据库连接池来复用连接，JDBC [DataSource](https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html) 定义了连接池 API，开发者可根据实际需求选择使用某种开源连接池实现。 - 数据访问框架：应用通常选择通过数据访问框架 ([MyBatis](https://mybatis.org/mybatis-3/zh_CN/index.html), [Hibernate](https://hibernate.org/)) 的封装来进一步简化和管理数据库访问操作。 - 业务实现：业务逻辑控制着何时发送和发送什么指令到数据库，其中有些业务会使用 [Spring Transaction](https://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/transaction.html) 切面来控制管理事务的开始和提交逻辑。 @@ -72,7 +72,7 @@ TiDB 同时支持以上两种方式，但更推荐使用第一种将 `FetchSize` ### MySQL JDBC 参数 -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/kb/en/library/about-mariadb-connector-j/#optional-url-parameters)）。因为配置项较多，这里主要关注几个可能影响到性能的参数。 +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 相关参数 @@ -104,6 +104,10 @@ JDBC 实现通常通过 JDBC URL 参数的形式来提供实现相关的配置 和上一条类似，在监控中通过 **Query Summary** > **CPS By Instance** 查看请求中 `COM_STMT_EXECUTE` 数目是否远远多于 `COM_STMT_PREPARE` 来确认是否正常。 +#### `readOnlyPropagatesToServer` + +请禁用 `readOnlyPropagatesToServer` 参数。启用该参数时，JDBC 驱动会向服务器发送 `SET SESSION TRANSACTION READ ONLY` 语句。TiDB 不支持该语句。此外，发送该语句也没有必要，因为所有 TiDB 节点都支持读写连接。 + #### Batch 相关参数 在进行 batch 写入处理时推荐配置 `rewriteBatchedStatements = true`，在已经使用 `addBatch` 或 `executeBatch` 后默认 JDBC 还是会一条条 SQL 发送，例如： @@ -120,8 +124,6 @@ pstmt.executeBatch(); 虽然使用了 batch 但发送到 TiDB 语句还是单独的多条 insert： -{{< copyable "sql" >}} - ```sql insert into t(a) values(10); insert into t(a) values(11); @@ -130,16 +132,12 @@ insert into t(a) values(12); 如果设置 `rewriteBatchedStatements = true`，发送到 TiDB 的 SQL 将是： -{{< copyable "sql" >}} - ```sql insert into t(a) values(10),(11),(12); ``` 需要注意的是，insert 语句的改写，只能将多个 values 后的值拼接成一整条 SQL，insert 语句如果有其他差异将无法被改写。例如： -{{< copyable "sql" >}} - ```sql insert into t (a) values (10) on duplicate key update a = 10; insert into t (a) values (11) on duplicate key update a = 11; @@ -148,8 +146,6 @@ insert into t (a) values (12) on duplicate key update a = 12; 上述 insert 语句将无法被改写成一条语句。该例子中，如果将 SQL 改写成如下形式： -{{< copyable "sql" >}} - ```sql insert into t (a) values (10) on duplicate key update a = values(a); insert into t (a) values (11) on duplicate key update a = values(a); @@ -158,16 +154,12 @@ insert into t (a) values (12) on duplicate key update a = values(a); 即可满足改写条件，最终被改写成： -{{< copyable "sql" >}} - ```sql insert into t (a) values (10), (11), (12) on duplicate key update a = values(a); ``` 批量更新时如果有 3 处或 3 处以上更新，则 SQL 语句会改写为 multiple-queries 的形式并发送，这样可以有效减少客户端到服务器的请求开销，但副作用是会产生较大的 SQL 语句，例如这样： -{{< copyable "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; ``` @@ -176,30 +168,72 @@ update t set a = 10 where id = 1; update t set a = 11 where id = 2; update t set #### 集成参数 -通过监控可能会发现，虽然业务只向集群进行 insert 操作，却看到有很多多余的 select 语句。通常这是因为 JDBC 发送了一些查询设置类的 SQL 语句（例如 `select @@session.transaction_read_only`）。这些 SQL 对 TiDB 无用，推荐配置 `useConfigs = maxPerformance` 来避免额外开销。 +通过监控可能会发现，虽然业务只向集群进行 insert 操作，却看到有很多多余的 select 语句。通常这是因为 JDBC 发送了一些查询设置类的 SQL 语句（例如 `select @@session.transaction_read_only`）。这些 SQL 对 TiDB 无用，推荐配置 `useConfigs=maxPerformance` 来避免额外开销。 -`useConfigs = maxPerformance` 会包含一组配置，可查看 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) 或 [5.1 版本](https://github.com/mysql/mysql-connector-j/blob/release/5.1/src/com/mysql/jdbc/configs/maxPerformance.properties) 来确认当前 MySQL Connector/J 中 `maxPerformance` 包含的具体配置。 +`useConfigs=maxPerformance` 会包含一组配置，可查看 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)或 [5.1 版本](https://github.com/mysql/mysql-connector-j/blob/release/5.1/src/com/mysql/jdbc/configs/maxPerformance.properties)来确认当前 MySQL Connector/J 中 `maxPerformance` 包含的具体配置。 配置后查看监控，可以看到多余语句减少。 +> **注意：** +> +> 开启 `useConfigs=maxPerformance` 需要使用 MySQL Connector/J 8.0.33 或更高版本，详情请参考 [MySQL JDBC Bug](/develop/dev-guide-third-party-tools-compatibility.md#mysql-jdbc-bug)。 + #### 超时参数 -TiDB 提供两个与 MySQL 兼容的超时控制参数，`wait_timeout` 和 `max_execution_time`。这两个参数分别控制与 Java 应用连接的空闲超时时间和连接中 SQL 执行的超时时间，即控制 TiDB 与 Java 应用的连接最长闲多久和最长忙多久。这两个参数的默认值都是 `0`，即默认允许连接无限闲置以及无限忙碌（一个 SQL 语句执行无限的长的时间）。 +TiDB 提供以下与 MySQL 兼容的超时控制参数： + +- `wait_timeout`：控制与 Java 应用连接的非交互式空闲超时时间。在 TiDB v5.4 及以上版本中，默认值为 `28800` 秒，即空闲超时为 8 小时。在 v5.4 之前，默认值为 `0`，即没有时间限制。 +- `interactive_timeout`：控制与 Java 应用连接的交互式空闲超时时间，默认值为 8 小时。 +- `max_execution_time`：控制连接中 SQL 执行的超时时间，仅对 `SELECT` 语句（包括 `SELECT ... FOR UPDATE`）生效，默认值是 `0`，即允许连接无限忙碌（一个 SQL 语句执行无限的长的时间）。 但在实际生产环境中，空闲连接和一直无限执行的 SQL 对数据库和应用都有不好的影响。你可以通过在应用的连接字符串中配置这两个参数来避免空闲连接和执行时间过长的 SQL 语句。例如，设置 `sessionVariables=wait_timeout=3600`（1 小时）和 `sessionVariables=max_execution_time=300000`（5 分钟）。 +#### 典型的 JDBC 连接字符串参数 + +对以上的参数值进行组合，JDBC 连接字符串配置如下： + +``` +jdbc:mysql://:/?characterEncoding=UTF-8&useSSL=false&useServerPrepStmts=true&cachePrepStmts=true&prepStmtCacheSqlLimit=10000&prepStmtCacheSize=1000&useConfigs=maxPerformance&rewriteBatchedStatements=true +``` + +> **注意：** +> +> 如果在公共网络发起连接，需要修改配置 `useSSL=true`，并启用 [TiDB 客户端服务端间加密传输](/enable-tls-between-clients-and-servers.md)。 + ## 连接池 TiDB (MySQL) 连接建立是比较昂贵的操作（至少对于 OLTP），除了建立 TCP 连接外还需要进行连接鉴权操作，所以客户端通常会把 TiDB (MySQL) 连接保存到连接池中进行复用。 -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 不会限定使用的连接池，应用可以根据业务特点自行选择连接池实现。 +TiDB 支持以下 Java 的连接池： + +- [HikariCP](https://github.com/brettwooldridge/HikariCP) +- [tomcat-jdbc](https://tomcat.apache.org/tomcat-10.1-doc/jdbc-pool) +- [druid](https://github.com/alibaba/druid) +- [c3p0](https://www.mchange.com/projects/c3p0/) +- [dbcp](https://commons.apache.org/proper/commons-dbcp/) + +在实践中，某些连接池会长期占用特定的活跃会话。这样虽然 TiDB 计算层的多个节点间连接数一致，但活跃连接数不一致，导致实际负载不均衡。在分布式场景中，推荐使用 HikariCP，该连接池能够有效管理连接的生命周期，避免活跃连接长期固定在部分节点上，从而实现更均衡的负载分布。 -### 连接数配置 +### 典型的连接池配置 + +以 HikariCP 为例： + +```yaml +hikari: + maximumPoolSize: 20 + poolName: hikariCP + connectionTimeout: 30000 + maxLifetime: 1200000 + keepaliveTime: 120000 +``` -比较常见的是应用需要根据自身情况配置合适的连接池大小，以 HikariCP 为例： +参数解释如下。更多详情，请参阅 [HikariCP 官方帮助文档](https://github.com/brettwooldridge/HikariCP/blob/dev/README.md)。 -- `maximumPoolSize`：连接池最大连接数，配置过大会导致 TiDB 消耗资源维护无用连接，配置过小则会导致应用获取连接变慢，所以需根据应用自身特点配置合适的值，可参考[这篇文章](https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing)。 -- `minimumIdle`：连接池最小空闲连接数，主要用于在应用空闲时存留一些连接以应对突发请求，同样是需要根据业务情况进行配置。 +- `maximumPoolSize`：连接池的最大连接数，默认值为 `10`。根据经验，在容器化场景下可以使用 Java 应用部署环境的 CPU 核心数的 4 ~ 10 倍。连接数配置过大会导致 TiDB 消耗资源维护无用连接，配置过小则会导致应用获取连接变慢。详情请参考 [About Pool Sizing](https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing)。 +- `minimumIdle`：HikariCP 官方推荐不要配置连接池最小空闲连接数，默认值等于连接池最大连接数。配置为相同值，等同于不使用连接池的伸缩特性，防止业务突增时，建立连接的过程过长，导致应用不能获取连接。 +- `connectionTimeout`：应用从连接池获取连接时的最长等待时间（单位为毫秒），默认值为 `30000` 毫秒（即 30 秒）。如果在指定时间内未能获取到可用连接，系统将抛出 SQLException 异常。 +- `maxLifetime`：连接池中每个连接的最大存活时间（单位为毫秒），即连接的生命周期，默认值为 `1800000` 毫秒（即 30 分钟）。使用中的连接不受影响，仅当连接被关闭后才会根据此设置被移除。过短的设置会引发频繁重建连接的开销。如果有 [`graceful-wait-before-shutdown`](/tidb-configuration-file.md#graceful-wait-before-shutdown-从-v50-版本开始引入) 的使用场景，连接的最大存活时间应小于等待时间。 +- `keepaliveTime`：连接池中连接保活操作间隔（单位为毫秒），防止数据库或网络基础设施因超时断开连接，默认值为 `120000` 毫秒（即 2 分钟）。连接池对空闲连接优先调用 JDBC4 的 `isValid()` 方法进行保活。 应用在使用连接池时，需要注意连接使用完成后归还连接，推荐应用使用对应的连接池相关监控（如 `metricRegistry`），通过监控能及时定位连接池问题。 diff --git a/develop/serverless-driver-drizzle-example.md b/develop/serverless-driver-drizzle-example.md new file mode 100644 index 000000000000..77e4be4c54af --- /dev/null +++ b/develop/serverless-driver-drizzle-example.md @@ -0,0 +1,277 @@ +--- +title: TiDB Cloud serverless driver Drizzle 教程 +summary: 学习如何在 Drizzle 中使用 TiDB Cloud serverless driver。 +aliases: ['/zh/tidbcloud/serverless-driver-drizzle-example/'] +--- + +# TiDB Cloud serverless driver Drizzle 教程 + +[Drizzle ORM](https://orm.drizzle.team/) 是一款轻量级且高性能的 TypeScript ORM，注重开发者体验。从 `drizzle-orm@0.31.2` 开始，Drizzle 支持 [drizzle-orm/tidb-serverless](https://orm.drizzle.team/docs/get-started-mysql#tidb-serverless)，你可以通过 [TiDB Cloud serverless driver](/develop/serverless-driver.md) 以 HTTPS 方式连接 Drizzle。 + +本教程介绍如何在 Node.js 环境和边缘环境中，将 TiDB Cloud serverless driver 与 Drizzle 搭配使用。 + +> **建议：** +> +> 除了 TiDB Cloud Starter 集群，本教程的步骤也适用于 TiDB Cloud Essential 集群。 + +## 在 Node.js 环境中使用 Drizzle 和 TiDB Cloud serverless driver + +本节介绍如何在 Node.js 环境中，将 TiDB Cloud serverless driver 与 Drizzle 搭配使用。 + +### 前置条件 + +完成本教程，你需要准备以下内容： + +- [Node.js](https://nodejs.org/en) >= 18.0.0。 +- [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) 或你喜欢的包管理器。 +- 一个 TiDB Cloud Starter 集群。如果你还没有，可以[创建一个 TiDB Cloud Starter 集群](/develop/dev-guide-build-cluster-in-cloud.md)。 + +### 步骤 1. 创建项目 + +1. 创建一个名为 `drizzle-node-example` 的项目： + + ```shell + mkdir drizzle-node-example + cd drizzle-node-example + ``` + +2. 安装 `drizzle-orm` 和 `@tidbcloud/serverless` 包： + + ```shell + npm install drizzle-orm @tidbcloud/serverless + ``` + +3. 在项目根目录下，找到 `package.json` 文件，并通过添加 `"type": "module"` 指定 ES module： + + ```json + { + "type": "module", + "dependencies": { + "@tidbcloud/serverless": "^0.1.1", + "drizzle-orm": "^0.31.2" + } + } + ``` + +4. 在项目根目录下，添加 `tsconfig.json` 文件以定义 TypeScript 编译选项。以下是示例文件： + + ```json + { + "compilerOptions": { + "module": "ES2022", + "target": "ES2022", + "moduleResolution": "node", + "strict": false, + "declaration": true, + "outDir": "dist", + "removeComments": true, + "allowJs": true, + "esModuleInterop": true, + "resolveJsonModule": true + } + } + ``` + +### 步骤 2. 配置环境 + +1. 在 [TiDB Cloud 控制台](https://tidbcloud.com/)中，进入你项目的 [**Clusters**](https://tidbcloud.com/project/clusters) 页面，点击目标 TiDB Cloud Starter 集群名称，进入集群概览页。 + +2. 在概览页右上角点击 **Connect**，在 **Connect With** 下拉列表中选择 `Serverless Driver`，然后点击 **Generate Password** 生成随机密码。 + + > **建议：** + > + > 如果你之前已经创建过密码，可以继续使用原密码，或者点击 **Reset Password** 生成新密码。 + + 连接字符串格式如下： + + ``` + mysql://[username]:[password]@[host]/[database] + ``` + +3. 在本地环境中设置环境变量 `DATABASE_URL`。例如，在 Linux 或 macOS 下，可以运行以下命令： + + ```shell + export DATABASE_URL='mysql://[username]:[password]@[host]/[database]' + ``` + +### 步骤 3. 使用 Drizzle 查询数据 + +1. 在你的 TiDB Cloud Starter 集群中创建一张表。 + + 你可以使用 [TiDB Cloud 控制台的 SQL Editor](https://docs.pingcap.com/tidbcloud/explore-data-with-chat2query/) 执行 SQL 语句。以下为示例： + + ```sql + CREATE TABLE `test`.`users` ( + `id` BIGINT PRIMARY KEY auto_increment, + `full_name` TEXT, + `phone` VARCHAR(256) + ); + ``` + +2. 在项目根目录下，创建名为 `hello-world.ts` 的文件，并添加以下代码： + + ```ts + import { connect } from '@tidbcloud/serverless'; + import { drizzle } from 'drizzle-orm/tidb-serverless'; + import { mysqlTable, serial, text, varchar } from 'drizzle-orm/mysql-core'; + + // 初始化 + const client = connect({ url: process.env.DATABASE_URL }); + const db = drizzle(client); + + // 定义 schema + export const users = mysqlTable('users', { + id: serial("id").primaryKey(), + fullName: text('full_name'), + phone: varchar('phone', { length: 256 }), + }); + export type User = typeof users.$inferSelect; // 查询时的返回类型 + export type NewUser = typeof users.$inferInsert; // 插入类型 + + // 插入和查询数据 + const user: NewUser = { fullName: 'John Doe', phone: '123-456-7890' }; + await db.insert(users).values(user) + const result: User[] = await db.select().from(users); + console.log(result); + ``` + +### 步骤 4. 运行 TypeScript 代码 + +1. 安装 `ts-node` 用于将 TypeScript 转换为 JavaScript，并安装 `@types/node` 以为 Node.js 提供 TypeScript 类型定义。 + + ```shell + npm install -g ts-node + npm i --save-dev @types/node + ``` + +2. 使用以下命令运行 TypeScript 代码： + + ```shell + ts-node --esm hello-world.ts + ``` + +## 在边缘环境中使用 Drizzle 和 TiDB Cloud serverless driver + +本节以 Vercel Edge Function 为例进行说明。 + +### 前置条件 + +完成本教程，你需要准备以下内容： + +- 一个支持边缘环境的 [Vercel](https://vercel.com/docs) 账号。 +- [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) 或你喜欢的包管理器。 +- 一个 TiDB Cloud Starter 集群。如果你还没有，可以[创建一个 TiDB Cloud Starter 集群](/develop/dev-guide-build-cluster-in-cloud.md)。 + +### 步骤 1. 创建项目 + +1. 安装 Vercel CLI： + + ```shell + npm i -g vercel@latest + ``` + +2. 使用以下命令创建一个名为 `drizzle-example` 的 [Next.js](https://nextjs.org/) 项目： + + ```shell + npx create-next-app@latest drizzle-example --ts --no-eslint --tailwind --no-src-dir --app --import-alias "@/*" + ``` + +3. 进入 `drizzle-example` 目录： + + ```shell + cd drizzle-example + ``` + +4. 安装 `drizzle-orm` 和 `@tidbcloud/serverless` 包： + + ```shell + npm install drizzle-orm @tidbcloud/serverless --force + ``` + +### 步骤 2. 配置环境 + +1. 在 [TiDB Cloud 控制台](https://tidbcloud.com/)中，进入你项目的 [**Clusters**](https://tidbcloud.com/project/clusters) 页面，点击目标 TiDB Cloud Starter 集群名称，进入集群概览页。 + +2. 在概览页右上角点击 **Connect**，在 **Connect With** 下拉列表中选择 `Serverless Driver`，然后点击 **Generate Password** 生成随机密码。 + + > **建议：** + > + > 如果你之前已经创建过密码，可以继续使用原密码，或者点击 **Reset Password** 生成新密码。 + + 连接字符串格式如下： + + ``` + mysql://[username]:[password]@[host]/[database] + ``` + +### 步骤 3. 创建边缘函数 + +1. 在你的 TiDB Cloud Starter 集群中创建一张表。 + + 你可以使用 [TiDB Cloud 控制台的 SQL Editor](https://docs.pingcap.com/tidbcloud/explore-data-with-chat2query/) 执行 SQL 语句。以下为示例： + + ```sql + CREATE TABLE `test`.`users` ( + `id` BIGINT PRIMARY KEY auto_increment, + `full_name` TEXT, + `phone` VARCHAR(256) + ); + ``` + +2. 在项目的 `app` 目录下，创建文件 `/api/edge-function-example/route.ts`，并添加以下代码： + + ```ts + import { NextResponse } from 'next/server'; + import type { NextRequest } from 'next/server'; + import { connect } from '@tidbcloud/serverless'; + import { drizzle } from 'drizzle-orm/tidb-serverless'; + import { mysqlTable, serial, text, varchar } from 'drizzle-orm/mysql-core'; + export const runtime = 'edge'; + + // 初始化 + const client = connect({ url: process.env.DATABASE_URL }); + const db = drizzle(client); + + // 定义 schema + export const users = mysqlTable('users', { + id: serial("id").primaryKey(), + fullName: text('full_name'), + phone: varchar('phone', { length: 256 }), + }); + export type User = typeof users.$inferSelect; // 查询时的返回类型 + export type NewUser = typeof users.$inferInsert; // 插入类型 + + export async function GET(request: NextRequest) { + // 插入和查询数据 + const user: NewUser = { fullName: 'John Doe', phone: '123-456-7890' }; + await db.insert(users).values(user) + const result: User[] = await db.select().from(users); + return NextResponse.json(result); + } + ``` + +3. 本地测试你的代码： + + ```shell + export DATABASE_URL='mysql://[username]:[password]@[host]/[database]' + next dev + ``` + +4. 访问 `http://localhost:3000/api/edge-function-example`，获取路由返回的响应。 + +### 步骤 4. 部署代码到 Vercel + +1. 使用 `DATABASE_URL` 环境变量将代码部署到 Vercel： + + ```shell + vercel -e DATABASE_URL='mysql://[username]:[password]@[host]/[database]' --prod + ``` + + 部署完成后，你会获得项目的 URL。 + +2. 访问 `${Your-URL}/api/edge-function-example` 页面，获取路由返回的响应。 + +## 下一步 + +- 了解更多关于 [Drizzle](https://orm.drizzle.team/docs/overview) 和 [drizzle-orm/tidb-serverless](https://orm.drizzle.team/docs/get-started-mysql#tidb-serverless) 的信息。 +- 学习如何[集成 TiDB Cloud 与 Vercel](https://docs.pingcap.com/zh/tidbcloud/integrate-tidbcloud-with-vercel)。 \ No newline at end of file diff --git a/develop/serverless-driver-kysely-example.md b/develop/serverless-driver-kysely-example.md new file mode 100644 index 000000000000..c174ceb466bf --- /dev/null +++ b/develop/serverless-driver-kysely-example.md @@ -0,0 +1,300 @@ +--- +title: TiDB Cloud serverless driver Kysely 教程 +summary: 学习如何在 Kysely 中使用 TiDB Cloud serverless driver。 +aliases: ['/zh/tidbcloud/serverless-driver-kysely-example/'] +--- + +# TiDB Cloud serverless driver Kysely 教程 + +[Kysely](https://kysely.dev/docs/intro) 是一个类型安全且支持自动补全的 TypeScript SQL 查询构建器。TiDB Cloud 提供了 [@tidbcloud/kysely](https://github.com/tidbcloud/kysely)，使你能够通过 [TiDB Cloud serverless driver](/develop/serverless-driver.md) 在 HTTPS 上使用 Kysely。与传统的 TCP 方式相比，[@tidbcloud/kysely](https://github.com/tidbcloud/kysely) 带来了以下优势： + +- 在 serverless 环境下拥有更好的性能。 +- 能够在边缘环境中使用 Kysely。 + +本教程介绍如何在 Node.js 环境和边缘环境中，将 TiDB Cloud serverless driver 与 Kysely 结合使用。 + +## 在 Node.js 环境中使用 TiDB Cloud Kysely 方言 + +本节介绍如何在 Node.js 环境中，将 TiDB Cloud serverless driver 与 Kysely 结合使用。 + +### 前置条件 + +完成本教程，你需要准备以下内容： + +- [Node.js](https://nodejs.org/en) >= 18.0.0。 +- [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) 或你喜欢的包管理器。 +- 一个 TiDB Cloud Starter 集群。如果你还没有，可以[创建一个 TiDB Cloud Starter 集群](/develop/dev-guide-build-cluster-in-cloud.md)。 + +### 步骤 1. 创建项目 + +1. 创建一个名为 `kysely-node-example` 的项目： + + ``` + mkdir kysely-node-example + cd kysely-node-example + ``` + +2. 安装 `kysely`、`@tidbcloud/kysely` 和 `@tidbcloud/serverless` 包： + + ``` + npm install kysely @tidbcloud/kysely @tidbcloud/serverless + ``` + +3. 在项目根目录下，找到 `package.json` 文件，并通过添加 `"type": "module"` 指定 ES module： + + ```json + { + "type": "module", + "dependencies": { + "@tidbcloud/kysely": "^0.0.4", + "@tidbcloud/serverless": "^0.0.7", + "kysely": "^0.26.3", + } + } + ``` + +4. 在项目根目录下，添加 `tsconfig.json` 文件以定义 TypeScript 编译选项。以下是示例文件： + + ```json + { + "compilerOptions": { + "module": "ES2022", + "target": "ES2022", + "moduleResolution": "node", + "strict": false, + "declaration": true, + "outDir": "dist", + "removeComments": true, + "allowJs": true, + "esModuleInterop": true, + "resolveJsonModule": true + } + } + ``` + +### 步骤 2. 配置环境 + +1. 在 TiDB Cloud Starter 集群的概览页面，点击右上角的 **Connect**，然后在弹出的对话框中获取你的数据库连接字符串。连接字符串格式如下： + + ``` + mysql://[username]:[password]@[host]/[database] + ``` + +2. 在本地环境中设置环境变量 `DATABASE_URL`。例如，在 Linux 或 macOS 下，可以运行以下命令： + + ```bash + export DATABASE_URL='mysql://[username]:[password]@[host]/[database]' + ``` + +### 步骤 3. 使用 Kysely 查询数据 + +1. 在你的 TiDB Cloud Starter 集群中创建一张表并插入一些数据。 + + 你可以使用 [TiDB Cloud 控制台的 SQL Editor](https://docs.pingcap.com/tidbcloud/explore-data-with-chat2query/) 执行 SQL 语句。以下为示例： + + ```sql + CREATE TABLE `test`.`person` ( + `id` int(11) NOT NULL AUTO_INCREMENT, + `name` varchar(255) NULL DEFAULT NULL, + `gender` enum('male','female') NULL DEFAULT NULL, + PRIMARY KEY (`id`) USING BTREE + ); + + insert into test.person values (1,'pingcap','male') + ``` + +2. 在项目根目录下，创建名为 `hello-world.ts` 的文件，并添加以下代码： + + ```ts + import { Kysely,GeneratedAlways,Selectable } from 'kysely' + import { TiDBServerlessDialect } from '@tidbcloud/kysely' + + // 类型定义 + interface Database { + person: PersonTable + } + + interface PersonTable { + id: GeneratedAlways + name: string + gender: "male" | "female" + } + + // 方言配置 + const db = new Kysely({ + dialect: new TiDBServerlessDialect({ + url: process.env.DATABASE_URL + }), + }) + + // 简单查询 + type Person = Selectable + export async function findPeople(criteria: Partial = {}) { + let query = db.selectFrom('person') + + if (criteria.name){ + query = query.where('name', '=', criteria.name) + } + + return await query.selectAll().execute() + } + + console.log(await findPeople()) + ``` + +### 步骤 4. 运行 TypeScript 代码 + +1. 安装 `ts-node` 用于将 TypeScript 转换为 JavaScript，并安装 `@types/node` 以为 Node.js 提供 TypeScript 类型定义。 + + ``` + npm install -g ts-node + npm i --save-dev @types/node + ``` + +2. 使用以下命令运行 TypeScript 代码： + + ``` + ts-node --esm hello-world.ts + ``` + +## 在边缘环境中使用 TiDB Cloud Kysely 方言 + +本节以 Vercel Edge Function 中的 TiDB Cloud Kysely 方言为例进行说明。 + +### 前置条件 + +完成本教程，你需要准备以下内容： + +- 一个提供边缘环境的 [Vercel](https://vercel.com/docs) 账号。 +- [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) 或你喜欢的包管理器。 +- 一个 TiDB Cloud Starter 集群。如果你还没有，可以[创建一个 TiDB Cloud Starter 集群](/develop/dev-guide-build-cluster-in-cloud.md)。 + +### 步骤 1. 创建项目 + +1. 安装 Vercel CLI： + + ``` + npm i -g vercel@latest + ``` + +2. 使用以下终端命令创建一个名为 `kysely-example` 的 [Next.js](https://nextjs.org/) 项目： + + ``` + npx create-next-app@latest kysely-example --ts --no-eslint --tailwind --no-src-dir --app --import-alias "@/*" + cd kysely-example + ``` + +3. 安装 `kysely`、`@tidbcloud/kysely` 和 `@tidbcloud/serverless` 包： + + ``` + npm install kysely @tidbcloud/kysely @tidbcloud/serverless + ``` + +### 步骤 2. 配置环境 + +在 TiDB Cloud Starter 集群的概览页面，点击右上角的 **Connect**，然后在弹出的对话框中获取你的数据库连接字符串。连接字符串格式如下： + +``` +mysql://[username]:[password]@[host]/[database] +``` + +### 步骤 3. 创建边缘函数 + +1. 在你的 TiDB Cloud Starter 集群中创建一张表并插入一些数据。 + + 你可以使用 [TiDB Cloud 控制台的 SQL Editor](https://docs.pingcap.com/tidbcloud/explore-data-with-chat2query/) 执行 SQL 语句。以下为示例： + + ```sql + CREATE TABLE `test`.`person` ( + `id` int(11) NOT NULL AUTO_INCREMENT, + `name` varchar(255) NULL DEFAULT NULL, + `gender` enum('male','female') NULL DEFAULT NULL, + PRIMARY KEY (`id`) USING BTREE + ); + + insert into test.person values (1,'pingcap','male') + ``` + +2. 在项目的 `app` 目录下，创建文件 `/api/edge-function-example/route.ts`，并添加以下代码： + + ```ts + import { NextResponse } from 'next/server'; + import type { NextRequest } from 'next/server'; + import { Kysely,GeneratedAlways,Selectable } from 'kysely' + import { TiDBServerlessDialect } from '@tidbcloud/kysely' + + export const runtime = 'edge'; + + // 类型定义 + interface Database { + person: PersonTable + } + + interface PersonTable { + id: GeneratedAlways + name: string + gender: "male" | "female" | "other" + } + + // 方言配置 + const db = new Kysely({ + dialect: new TiDBServerlessDialect({ + url: process.env.DATABASE_URL + }), + }) + + // 查询 + type Person = Selectable + async function findPeople(criteria: Partial = {}) { + let query = db.selectFrom('person') + + if (criteria.name){ + query = query.where('name', '=', criteria.name) + } + + return await query.selectAll().execute() + } + + export async function GET(request: NextRequest) { + + const searchParams = request.nextUrl.searchParams + const query = searchParams.get('query') + + let response = null; + if (query) { + response = await findPeople({name: query}) + } else { + response = await findPeople() + } + + return NextResponse.json(response); + } + ``` + + 上述代码接收一个查询参数 `query` 并返回查询结果。如果未提供该参数，则返回 `person` 表中的所有记录。 + +3. 本地测试你的代码： + + ``` + export DATABASE_URL='mysql://[username]:[password]@[host]/[database]' + next dev + ``` + +4. 访问 `http://localhost:3000/api/edge-function-example`，即可获取该路由的响应。 + +### 步骤 4. 部署代码到 Vercel + +1. 使用 `DATABASE_URL` 环境变量将代码部署到 Vercel： + + ``` + vercel -e DATABASE_URL='mysql://[username]:[password]@[host]/[database]' --prod + ``` + + 部署完成后，你将获得项目的 URL。 + +2. 访问 `${Your-URL}/api/edge-function-example` 页面，即可获取该路由的响应。 + +## 下一步 + +- 了解更多关于 [Kysely](https://kysely.dev/docs/intro) 和 [@tidbcloud/kysely](https://github.com/tidbcloud/kysely) 的信息 +- 学习如何[将 TiDB Cloud 集成到 Vercel](https://docs.pingcap.com/zh/tidbcloud/integrate-tidbcloud-with-vercel) diff --git a/develop/serverless-driver-node-example.md b/develop/serverless-driver-node-example.md new file mode 100644 index 000000000000..4c0f10a365dd --- /dev/null +++ b/develop/serverless-driver-node-example.md @@ -0,0 +1,96 @@ +--- +title: TiDB Cloud serverless driver Node.js 教程 +summary: 学习如何在本地 Node.js 项目中使用 TiDB Cloud serverless driver。 +aliases: ['/zh/tidbcloud/serverless-driver-node-example/'] +--- + +# TiDB Cloud serverless driver Node.js 教程 + +本教程介绍如何在本地 Node.js 项目中使用 TiDB Cloud serverless driver。 + +> **注意：** +> +> - 除了 TiDB Cloud Starter 集群，本教程的步骤也适用于 TiDB Cloud Essential 集群。 +> - 如果你想了解如何在 Cloudflare Workers、Vercel Edge Functions 和 Netlify Edge Functions 中使用 TiDB Cloud serverless driver，请参考 [Insights into Automotive Sales](https://car-sales-insight.vercel.app/) 和[示例仓库](https://github.com/tidbcloud/car-sales-insight)。 + +## 开始之前 + +要完成本教程中的步骤，你需要准备以下内容： + +- [Node.js](https://nodejs.org/en) >= 18.0.0。 +- [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) 或你喜欢的包管理器。 +- 一个 TiDB Cloud Starter 集群。如果你还没有，可以[创建一个 TiDB Cloud Starter 集群](/develop/dev-guide-build-cluster-in-cloud.md)。 + +## 步骤 1. 创建本地 Node.js 项目 + +1. 创建一个名为 `node-example` 的项目： + + ```shell + mkdir node-example + cd node-example + ``` + +2. 使用 npm 或你喜欢的包管理器安装 TiDB Cloud serverless driver。 + + 以下命令以 npm 安装为例。执行该命令后，会在你的项目目录下创建 `node_modules` 目录和 `package.json` 文件。 + + ``` + npm install @tidbcloud/serverless + ``` + +## 步骤 2. 使用 serverless driver + +serverless driver 同时支持 CommonJS 和 ES modules。以下步骤以 ES module 的用法为例。 + +1. 在你的 TiDB Cloud Starter 集群的概览页面，点击右上角的 **Connect**，然后在弹出的对话框中获取你的数据库连接字符串。连接字符串格式如下： + + ``` + mysql://[username]:[password]@[host]/[database] + ``` + +2. 在 `package.json` 文件中，通过添加 `type: "module"` 来指定 ES module。 + + 例如： + + ```json + { + "type": "module", + "dependencies": { + "@tidbcloud/serverless": "^0.0.7", + } + } + ``` + +3. 在你的项目目录下创建一个名为 `index.js` 的文件，并添加以下代码： + + ```js + import { connect } from '@tidbcloud/serverless' + + const conn = connect({url: 'mysql://[username]:[password]@[host]/[database]'}) // 替换为你的 TiDB Cloud Starter 集群信息 + console.log(await conn.execute("show tables")) + ``` + +4. 使用以下命令运行你的项目： + + ``` + node index.js + ``` + +## 与 Node.js 早期版本的兼容性 + +如果你使用的 Node.js 版本低于 18.0.0，不包含全局 `fetch` 函数，可以通过以下步骤获取 `fetch`： + +1. 安装一个提供 `fetch` 的包，例如 `undici`： + + ``` + npm install undici + ``` + +2. 将 `fetch` 函数传递给 `connect` 函数： + + ```js + import { connect } from '@tidbcloud/serverless' + import { fetch } from 'undici' + + const conn = connect({url: 'mysql://[username]:[password]@[host]/[database]',fetch}) + ``` \ No newline at end of file diff --git a/develop/serverless-driver-prisma-example.md b/develop/serverless-driver-prisma-example.md new file mode 100644 index 000000000000..9c0d75866d61 --- /dev/null +++ b/develop/serverless-driver-prisma-example.md @@ -0,0 +1,284 @@ +--- +title: TiDB Cloud serverless driver Prisma 教程 +summary: 学习如何将 TiDB Cloud serverless driver 与 Prisma ORM 一起使用。 +aliases: ['/zh/tidbcloud/serverless-driver-prisma-example/'] +--- + +# TiDB Cloud serverless driver Prisma 教程 + +[Prisma](https://www.prisma.io/docs) 是一款开源的下一代 ORM（对象关系映射），可以帮助开发者以直观、高效且安全的方式操作数据库。TiDB Cloud 提供了 [@tidbcloud/prisma-adapter](https://github.com/tidbcloud/prisma-adapter)，使你能够通过 [TiDB Cloud serverless driver](/develop/serverless-driver.md) 在 HTTPS 上使用 [Prisma Client](https://www.prisma.io/docs/concepts/components/prisma-client)。与传统的 TCP 方式相比，[@tidbcloud/prisma-adapter](https://github.com/tidbcloud/prisma-adapter) 带来了以下优势： + +- 在 serverless 环境下提升 Prisma Client 的性能 +- 支持在边缘环境下使用 Prisma Client + +本教程介绍如何在 serverless 环境和边缘环境中使用 [@tidbcloud/prisma-adapter](https://github.com/tidbcloud/prisma-adapter)。 + +> **建议：** +> +> 除了 TiDB Cloud Starter 集群，本教程的步骤也适用于 TiDB Cloud Essential 集群。 + +## 安装 + +你需要安装 [@tidbcloud/prisma-adapter](https://github.com/tidbcloud/prisma-adapter) 和 [TiDB Cloud serverless driver](/develop/serverless-driver.md)。你可以使用 [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) 或你喜欢的包管理器进行安装。 + +以 npm 为例，你可以运行以下命令进行安装： + +```shell +npm install @tidbcloud/prisma-adapter +npm install @tidbcloud/serverless +``` + +## 启用 `driverAdapters` + +要使用 Prisma adapter，你需要在 `schema.prisma` 文件中启用 `driverAdapters` 特性。例如： + +```prisma +generator client { + provider = "prisma-client-js" + previewFeatures = ["driverAdapters"] +} + +datasource db { + provider = "mysql" + url = env("DATABASE_URL") +} +``` + +## 初始化 Prisma Client + +在使用 Prisma Client 之前，你需要用 `@tidbcloud/prisma-adapter` 进行初始化。 + +对于 v6.6.0 之前的 `@tidbcloud/prisma-adapter`： + +```js +import { connect } from '@tidbcloud/serverless'; +import { PrismaTiDBCloud } from '@tidbcloud/prisma-adapter'; +import { PrismaClient } from '@prisma/client'; + +// 初始化 Prisma Client +const connection = connect({ url: ${DATABASE_URL} }); +const adapter = new PrismaTiDBCloud(connection); +const prisma = new PrismaClient({ adapter }); +``` + +对于 v6.6.0 或更高版本的 `@tidbcloud/prisma-adapter`： + +```js +import { PrismaTiDBCloud } from '@tidbcloud/prisma-adapter'; +import { PrismaClient } from '@prisma/client'; + +// 初始化 Prisma Client +const adapter = new PrismaTiDBCloud({ url: ${DATABASE_URL} }); +const prisma = new PrismaClient({ adapter }); +``` + +之后，Prisma Client 的查询将通过 TiDB Cloud serverless driver 进行处理。 + +## 在 Node.js 环境中使用 Prisma adapter + +本节提供了在 Node.js 环境下使用 `@tidbcloud/prisma-adapter` 的示例。 + +### 前置条件 + +完成本教程，你需要准备以下内容： + +- [Node.js](https://nodejs.org/en) >= 18.0.0 +- [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) 或你喜欢的包管理器 +- 一个 TiDB Cloud Starter 集群。如果你还没有，可以[创建一个 TiDB Cloud Starter 集群](/develop/dev-guide-build-cluster-in-cloud.md) + +### 步骤 1. 创建项目 + +1. 创建一个名为 `prisma-example` 的项目： + + ``` + mkdir prisma-example + cd prisma-example + ``` + +2. 安装 `@tidbcloud/prisma-adapter` 驱动适配器、`@tidbcloud/serverless` serverless driver 以及 Prisma CLI。 + + 以下命令以 npm 作为包管理器。执行 `npm install @tidbcloud/serverless` 会在你的项目目录下创建 `node_modules` 目录和 `package.json` 文件。 + + ``` + npm install @tidbcloud/prisma-adapter + npm install @tidbcloud/serverless + npm install prisma --save-dev + ``` + +3. 在 `package.json` 文件中，通过添加 `type: "module"` 指定 ES module： + + ```json + { + "type": "module", + "dependencies": { + "@prisma/client": "^6.6.0", + "@tidbcloud/prisma-adapter": "^6.6.0", + "@tidbcloud/serverless": "^0.1.0" + }, + "devDependencies": { + "prisma": "^6.6.0" + } + } + ``` + +### 步骤 2. 配置环境 + +1. 在 TiDB Cloud Starter 集群的概览页面，点击右上角的 **Connect**，然后在弹出的对话框中获取你的数据库连接字符串。连接字符串格式如下： + + ``` + mysql://[username]:[password]@[host]:4000/[database]?sslaccept=strict + ``` + +2. 在项目根目录下创建一个名为 `.env` 的文件，定义名为 `DATABASE_URL` 的环境变量，并将该变量中的 `[]` 占位符替换为连接字符串中的对应参数。 + + ```dotenv + DATABASE_URL='mysql://[username]:[password]@[host]:4000/[database]?sslaccept=strict' + ``` + + > **注意：** + > + > `@tidbcloud/prisma-adapter` 仅支持通过 HTTPS 使用 Prisma Client。对于 [Prisma Migrate](https://www.prisma.io/docs/concepts/components/prisma-migrate) 和 [Prisma Introspection](https://www.prisma.io/docs/concepts/components/introspection)，仍然使用传统的 TCP 连接。如果你只需要使用 Prisma Client，可以将 `DATABASE_URL` 简化为 `mysql://[username]:[password]@[host]/[database]` 格式。 + +3. 安装 `dotenv` 以从 `.env` 文件加载环境变量： + + ``` + npm install dotenv + ``` + +### 步骤 3. 定义 schema + +1. 创建一个名为 `schema.prisma` 的文件。在该文件中，包含 `driverAdapters` 预览特性，并引用 `DATABASE_URL` 环境变量。示例文件如下： + + ``` + // schema.prisma + generator client { + provider = "prisma-client-js" + previewFeatures = ["driverAdapters"] + } + + datasource db { + provider = "mysql" + url = env("DATABASE_URL") + } + ``` + +2. 在 `schema.prisma` 文件中，为你的数据库表定义数据模型。以下示例定义了一个名为 `user` 的数据模型。 + + ``` + // schema.prisma + generator client { + provider = "prisma-client-js" + previewFeatures = ["driverAdapters"] + } + + datasource db { + provider = "mysql" + url = env("DATABASE_URL") + } + + // 根据你的数据库表定义数据模型 + model user { + id Int @id @default(autoincrement()) + email String? @unique(map: "uniq_email") @db.VarChar(255) + name String? @db.VarChar(255) + } + ``` + +3. 使用 Prisma schema 同步你的数据库。你可以手动在 TiDB Cloud Starter 集群中创建数据库表，也可以使用 Prisma CLI 自动创建： + + ``` + npx prisma db push + ``` + + 该命令会通过传统的 TCP 连接在 TiDB Cloud Starter 集群中创建 `user` 表，而不是通过 `@tidbcloud/prisma-adapter` 的 HTTPS 连接。这是因为它使用了与 Prisma Migrate 相同的引擎。关于该命令的更多信息，请参见 [Prototype your schema](https://www.prisma.io/docs/concepts/components/prisma-migrate/db-push)。 + +4. 生成 Prisma Client： + + ``` + npx prisma generate + ``` + + 该命令会根据 Prisma schema 生成 Prisma Client。 + +### 步骤 4. 执行 CRUD 操作 + +1. 创建一个名为 `hello-word.js` 的文件，并添加以下代码以初始化 Prisma Client： + + ```js + import { PrismaTiDBCloud } from '@tidbcloud/prisma-adapter'; + import { PrismaClient } from '@prisma/client'; + import dotenv from 'dotenv'; + + // 设置 + dotenv.config(); + const connectionString = `${process.env.DATABASE_URL}`; + + // 初始化 Prisma Client + const adapter = new PrismaTiDBCloud({ url: connectionString }); + const prisma = new PrismaClient({ adapter }); + ``` + +2. 使用 Prisma Client 执行一些 CRUD 操作。例如： + + ```js + // 插入 + const user = await prisma.user.create({ + data: { + email: 'test@pingcap.com', + name: 'test', + }, + }) + console.log(user) + + // 查询 + console.log(await prisma.user.findMany()) + + // 删除 + await prisma.user.delete({ + where: { + id: user.id, + }, + }) + ``` + +3. 使用 Prisma Client 执行一些事务操作。例如： + + ```js + const createUser1 = prisma.user.create({ + data: { + email: 'test1@pingcap.com', + name: 'test1', + }, + }) + const createUser2 = prisma.user.create({ + data: { + email: 'test1@pingcap.com', + name: 'test1', + }, + }) + const createUser3 = prisma.user.create({ + data: { + email: 'test2@pingcap.com', + name: 'test2', + }, + }) + + try { + await prisma.$transaction([createUser1, createUser2]) // 由于邮箱地址重复，操作失败 + } catch (e) { + console.log(e) + } + + try { + await prisma.$transaction([createUser2, createUser3]) // 由于邮箱地址唯一，操作成功 + } catch (e) { + console.log(e) + } + ``` + +## 在边缘环境中使用 Prisma adapter + +你可以在边缘环境（如 Vercel Edge Functions 和 Cloudflare Workers）中使用 v5.11.0 或更高版本的 `@tidbcloud/prisma-adapter`。 + +- [Vercel Edge Function 示例](https://github.com/tidbcloud/serverless-driver-example/tree/main/prisma/prisma-vercel-example) +- [Cloudflare Workers 示例](https://github.com/tidbcloud/serverless-driver-example/tree/main/prisma/prisma-cloudflare-worker-example) diff --git a/develop/serverless-driver.md b/develop/serverless-driver.md new file mode 100644 index 000000000000..3dc4351c1b24 --- /dev/null +++ b/develop/serverless-driver.md @@ -0,0 +1,350 @@ +--- +title: TiDB Cloud serverless driver (Beta) +summary: 了解如何从 serverless 和边缘环境连接到 TiDB Cloud Starter 或 TiDB Cloud Essential。 +aliases: ['/zh/tidbcloud/serverless-driver/'] +--- + +# TiDB Cloud serverless driver (Beta) + +> **注意：** +> +> serverless driver 目前为 Beta 版本，仅适用于 TiDB Cloud Starter 或 TiDB Cloud Essential 集群。 + +## 为什么要使用 TiDB Cloud serverless driver (Beta) + +传统的基于 TCP 的 MySQL driver 不适用于 serverless 函数，是因为它们假设数据库连接是持久存在的，而这与 serverless 函数的短生命周期特性相矛盾。此外，在 [Vercel Edge Functions](https://vercel.com/docs/functions/edge-functions) 和 [Cloudflare Workers](https://workers.cloudflare.com/) 等边缘环境中，由于可能缺乏完整的 TCP 支持和 Node.js 兼容性，这些 driver 可能根本无法工作。 + +[TiDB Cloud serverless driver (Beta)](https://github.com/tidbcloud/serverless-js) 是一款面向 JavaScript 的驱动，允许你通过 HTTP（serverless 环境普遍支持的通信方式）连接到 TiDB Cloud Starter 或 TiDB Cloud Essential 集群。借助该 driver，你可以从边缘环境连接到 TiDB Cloud Starter 或 TiDB Cloud Essential 集群，减少 TCP 带来的连接开销，同时保持与传统基于 TCP 的 MySQL driver 类似的开发体验。 + +> **注意：** +> +> 如果你更倾向于使用 RESTful API 进行编程而不是 SQL 或 ORM，可以使用 [Data Service (Beta)](https://docs.pingcap.com/zh/tidbcloud/data-service-overview)。 + +## 安装 serverless driver + +你可以通过 npm 安装该 driver： + +```bash +npm install @tidbcloud/serverless +``` + +## 使用 serverless driver + +你可以使用 serverless driver 查询 TiDB Cloud Starter 或 TiDB Cloud Essential 集群中的数据，或执行交互式事务。 + +### 查询 + +要从 TiDB Cloud Starter 或 TiDB Cloud Essential 集群查询数据，你需要先创建连接。然后可以使用该连接执行原生 SQL 查询。例如： + +```ts +import { connect } from '@tidbcloud/serverless' + +const conn = connect({url: 'mysql://[username]:[password]@[host]/[database]'}) +const results = await conn.execute('select * from test where id = ?',[1]) +``` + +### 事务（实验性） + +你也可以使用 serverless driver 执行交互式事务。例如： + +```ts +import { connect } from '@tidbcloud/serverless' + +const conn = connect({url: 'mysql://[username]:[password]@[host]/[database]'}) +const tx = await conn.begin() + +try { + await tx.execute('insert into test values (1)') + await tx.execute('select * from test') + await tx.commit() +} catch (err) { + await tx.rollback() + throw err +} +``` + +## 边缘环境示例 + +以下是在边缘环境中使用 serverless driver 的一些示例。你也可以尝试这个完整的[在线演示](https://github.com/tidbcloud/car-sales-insight)。 + + + +
+ +```ts +import { NextResponse } from 'next/server'; +import type { NextRequest } from 'next/server'; +import { connect } from '@tidbcloud/serverless' +export const runtime = 'edge' + +export async function GET(request: NextRequest) { + const conn = connect({url: process.env.DATABASE_URL}) + const result = await conn.execute('show tables') + return NextResponse.json({result}); +} +``` + +了解更多关于[在 Vercel 中使用 TiDB Cloud serverless driver](https://docs.pingcap.com/zh/tidbcloud/integrate-tidbcloud-with-vercel)。 + +
+ +
+ +```ts +import { connect } from '@tidbcloud/serverless' +export interface Env { + DATABASE_URL: string; +} +export default { + async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise { + const conn = connect({url: env.DATABASE_URL}) + const result = await conn.execute('show tables') + return new Response(JSON.stringify(result)); + }, +}; +``` + +了解更多关于[在 Cloudflare Workers 中使用 TiDB Cloud serverless driver](https://docs.pingcap.com/zh/tidbcloud/integrate-tidbcloud-with-cloudflare)。 + +
+ +
+ +```ts +import { connect } from 'https://esm.sh/@tidbcloud/serverless' + +export default async () => { + const conn = connect({url: Netlify.env.get('DATABASE_URL')}) + const result = await conn.execute('show tables') + return new Response(JSON.stringify(result)); +} +``` + +了解更多关于[在 Netlify 中使用 TiDB Cloud serverless driver](https://docs.pingcap.com/zh/tidbcloud/integrate-tidbcloud-with-netlify#使用-edge-function)。 + +
+ +
+ +```ts +import { connect } from "npm:@tidbcloud/serverless" + +const conn = connect({url: Deno.env.get('DATABASE_URL')}) +const result = await conn.execute('show tables') +``` + +
+ +
+ +```ts +import { connect } from "@tidbcloud/serverless" + +const conn = connect({url: Bun.env.DATABASE_URL}) +const result = await conn.execute('show tables') +``` + +
+ + + +## 配置 serverless driver + +你可以在连接级别和 SQL 级别配置 TiDB Cloud serverless driver。 + +### 连接级别配置 + +在连接级别，你可以进行如下配置： + +| 名称 | 类型 | 默认值 | 描述 | +|--------------|----------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `username` | string | N/A | 集群的用户名。 | +| `password` | string | N/A | 集群的密码。 | +| `host` | string | N/A | 集群的主机名。 | +| `database` | string | `test` | 集群的数据库。 | +| `url` | string | N/A | 数据库的 URL，格式为 `mysql://[username]:[password]@[host]/[database]`，其中 `database` 可省略（如果你打算连接到默认数据库）。 | +| `fetch` | function | global fetch | 自定义 fetch 函数。例如，你可以在 Node.js 中使用 `undici` 的 fetch。 | +| `arrayMode` | bool | `false` | 是否以数组而非对象的形式返回结果。为了获得更好的性能，可以设置为 `true`。 | +| `fullResult` | bool | `false` | 是否返回完整结果对象而不仅仅是行数据。为了获得更详细的结果，可以设置为 `true`。 | +| `decoders` | object | `{}` | 一组键值对，允许你自定义不同列类型的解码过程。在每个键值对中，你可以指定列类型作为 key，并指定相应的函数作为 value。该函数以 TiDB Cloud serverless driver 返回的原始字符串值为参数，并返回解码后的值。 | + +**数据库 URL** + +> **注意：** +> +> 如果你的用户名、密码或数据库名包含特殊字符，在通过 URL 传递时必须对这些字符进行[百分号编码](https://zh.wikipedia.org/wiki/百分号编码)。例如，密码 `password1@//?` 需要在 URL 中编码为 `password1%40%2F%2F%3F`。 + +当配置了 `url` 后，无需单独配置 `host`、`username`、`password` 和 `database`。以下代码是等价的： + +```ts +const config = { + host: '', + username: '', + password: '', + database: '', + arrayMode: true, +} + +const conn = connect(config) +``` + +```ts +const config = { + url: process.env['DATABASE_URL'] || 'mysql://[username]:[password]@[host]/[database]', + arrayMode: true +} + +const conn = connect(config) +``` + +### SQL 级别选项 + +> **注意：** +> +> SQL 级别选项的优先级高于连接级别配置。 + +在 SQL 级别，你可以配置如下选项： + +| 选项 | 类型 | 默认值 | 描述 | +|--------------|--------|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `arrayMode` | bool | `false` | 是否以数组而非对象的形式返回结果。为了获得更好的性能，可以设置为 `true`。 | +| `fullResult` | bool | `false` | 是否返回完整结果对象而不仅仅是行数据。为了获得更详细的结果，可以设置为 `true`。 | +| `isolation` | string | `REPEATABLE READ`| 事务隔离级别，可设置为 `READ COMMITTED` 或 `REPEATABLE READ`。 | +| `decoders` | object | `{}` | 一组键值对，允许你自定义不同列类型的解码过程。在每个键值对中，你可以指定列类型作为 key，并指定相应的函数作为 value。该函数以 TiDB Cloud serverless driver 返回的原始字符串值为参数，并返回解码后的值。如果你在连接级别和 SQL 级别都配置了 `decoders`，则连接级别中具有不同 key 的键值对将合并到 SQL 级别并生效。如果两个级别指定了相同的 key（即列类型），则以 SQL 级别的值为准。 | + +**arrayMode 和 fullResult** + +如果你希望以数组形式返回完整结果对象，可以如下配置 `arrayMode` 和 `fullResult` 选项： + +```ts +const conn = connect({url: process.env['DATABASE_URL'] || 'mysql://[username]:[password]@[host]/[database]'}) +const results = await conn.execute('select * from test',null,{arrayMode:true,fullResult:true}) +``` + +**isolation** + +`isolation` 选项只能在 `begin` 函数中使用。 + +```ts +const conn = connect({url: 'mysql://[username]:[password]@[host]/[database]'}) +const tx = await conn.begin({isolation:"READ COMMITTED"}) +``` + +**decoders** + +如果你想自定义返回列值的格式，可以在 `connect()` 方法中配置 `decoder` 选项，如下所示： + +```ts +import { connect, ColumnType } from '@tidbcloud/serverless'; + +const conn = connect({ + url: 'mysql://[username]:[password]@[host]/[database]', + decoders: { + // 默认情况下，TiDB Cloud serverless driver 会将 BIGINT 类型作为文本值返回。此 decoder 将 BIGINT 转换为 JavaScript 内置的 BigInt 类型。 + [ColumnType.BIGINT]: (rawValue: string) => BigInt(rawValue), + + // 默认情况下，TiDB Cloud serverless driver 会将 DATETIME 类型以 'yyyy-MM-dd HH:mm:ss' 格式的文本值返回。此 decoder 将 DATETIME 文本转换为 JavaScript 原生 Date 对象。 + [ColumnType.DATETIME]: (rawValue: string) => new Date(rawValue), + } +}) + +// 你也可以在 SQL 级别配置 decoder 选项，以覆盖连接级别相同 key 的 decoders。 +conn.execute(`select ...`, [], { + decoders: { + // ... + } +}) +``` + +> **注意：** +> +> TiDB Cloud serverless driver 配置变更： +> +> - v0.0.7：新增 SQL 级别选项 `isolation`。 +> - v0.0.10：新增连接级别配置 `decoders` 和 SQL 级别选项 `decoders`。 + +## 功能特性 + +### 支持的 SQL 语句 + +支持 DDL，支持以下 SQL 语句：`SELECT`、`SHOW`、`EXPLAIN`、`USE`、`INSERT`、`UPDATE`、`DELETE`、`BEGIN`、`COMMIT`、`ROLLBACK` 和 `SET`。 + +### 数据类型映射 + +TiDB 与 JavaScript 之间的数据类型映射如下： + +| TiDB 数据类型 | JavaScript 类型 | +|----------------------|-----------------| +| TINYINT | number | +| UNSIGNED TINYINT | number | +| BOOL | number | +| SMALLINT | number | +| UNSIGNED SMALLINT | number | +| MEDIUMINT | number | +| INT | number | +| UNSIGNED INT | number | +| YEAR | number | +| FLOAT | number | +| DOUBLE | number | +| BIGINT | string | +| UNSIGNED BIGINT | string | +| DECIMAL | string | +| CHAR | string | +| VARCHAR | string | +| BINARY | Uint8Array | +| VARBINARY | Uint8Array | +| TINYTEXT | string | +| TEXT | string | +| MEDIUMTEXT | string | +| LONGTEXT | string | +| TINYBLOB | Uint8Array | +| BLOB | Uint8Array | +| MEDIUMBLOB | Uint8Array | +| LONGBLOB | Uint8Array | +| DATE | string | +| TIME | string | +| DATETIME | string | +| TIMESTAMP | string | +| ENUM | string | +| SET | string | +| BIT | Uint8Array | +| JSON | object | +| NULL | null | +| Others | string | + +> **注意：** +> +> 请确保在 TiDB Cloud 中使用默认的 `utf8mb4` 字符集进行类型转换为 JavaScript 字符串，因为 TiDB Cloud serverless driver 使用 UTF-8 编码将其解码为字符串。 + +> **注意：** +> +> TiDB Cloud serverless driver 数据类型映射变更： +> +> - v0.1.0：`BINARY`、`VARBINARY`、`TINYBLOB`、`BLOB`、`MEDIUMBLOB`、`LONGBLOB` 和 `BIT` 类型现在返回为 `Uint8Array`，而不是 `string`。 + +### ORM 集成 + +TiDB Cloud serverless driver 已集成以下 ORM： + +- [TiDB Cloud serverless driver Kysely dialect](https://github.com/tidbcloud/kysely)。 +- [TiDB Cloud serverless driver Prisma adapter](https://github.com/tidbcloud/prisma-adapter)。 + +## 计费 + +serverless driver 本身免费，但使用该 driver 访问数据会产生 [Request Units (RUs)](https://docs.pingcap.com/zh/tidbcloud/tidb-cloud-glossary/#request-capacity-unit-rcu) 和存储用量。 + +- 对于 TiDB Cloud Starter 集群，按 [TiDB Cloud Starter 计费模式](https://www.pingcap.com/tidb-cloud-starter-pricing-details/)计费。 +- 对于 TiDB Cloud Essential 集群，按 [TiDB Cloud Essential 计费模式](https://www.pingcap.com/tidb-cloud-essential-pricing-details/)计费。 + +## 限制 + +目前，使用 serverless driver 有如下限制： + +- 单次查询最多可获取 10,000 行数据。 +- 每次只能执行一条 SQL 语句，不支持在一个查询中执行多条 SQL 语句。 +- 暂不支持通过[私有端点](https://docs.pingcap.com/zh/tidbcloud/set-up-private-endpoint-connections-serverless)连接。 +- 为保护你的凭证，服务端会通过跨域资源共享 (CORS) 阻止来自未经授权的浏览器来源的请求。因此，你只能在后端服务中使用 serverless driver。 + +## 下一步 + +- 了解如何[在本地 Node.js 项目中使用 TiDB Cloud serverless driver](/develop/serverless-driver-node-example.md)。 \ No newline at end of file diff --git a/dm/deploy-a-dm-cluster-using-binary.md b/dm/deploy-a-dm-cluster-using-binary.md index 370803ab9375..9b29d9acd591 100644 --- a/dm/deploy-a-dm-cluster-using-binary.md +++ b/dm/deploy-a-dm-cluster-using-binary.md @@ -1,6 +1,5 @@ --- title: 使用 DM binary 部署 DM 集群 -aliases: ['/docs-cn/tidb-data-migration/dev/deploy-a-dm-cluster-using-binary/'] summary: 本文介绍了如何使用 DM binary 快速部署 DM 集群。首先需要下载 DM 安装包，然后在五台服务器上部署两个 DM-worker 实例和三个 DM-master 实例。对于 DM-master 的部署，可以使用命令行参数或配置文件两种方式。而对于 DM-worker 的部署，也可以使用命令行参数或配置文件两种方式。部署完成后，需要确保各组件间端口可正常连通。 --- diff --git a/dm/deploy-a-dm-cluster-using-tiup-offline.md b/dm/deploy-a-dm-cluster-using-tiup-offline.md index 282e65278e95..347f6e6ffb1c 100644 --- a/dm/deploy-a-dm-cluster-using-tiup-offline.md +++ b/dm/deploy-a-dm-cluster-using-tiup-offline.md @@ -127,7 +127,7 @@ alertmanager_servers: > > - 配置的层次结构使用 `.` 表示。如：`log.slow-threshold`。更多格式说明，请参考 [TiUP 配置参数模版](https://github.com/pingcap/tiup/blob/master/embed/examples/dm/topology.example.yaml)。 > -> - 更多参数说明，请参考 [master `config.toml.example`](https://github.com/pingcap/tiflow/blob/master/dm/master/dm-master.toml)、[worker `config.toml.example`](https://github.com/pingcap/tiflow/blob/master/dm/worker/dm-worker.toml)。 +> - 更多参数说明，请参考 [master `config.toml.example`](https://github.com/pingcap/tiflow/blob/release-8.5/dm/master/dm-master.toml)、[worker `config.toml.example`](https://github.com/pingcap/tiflow/blob/release-8.5/dm/worker/dm-worker.toml)。 > > - 需要确保以下组件间端口可正常连通： > diff --git a/dm/deploy-a-dm-cluster-using-tiup.md b/dm/deploy-a-dm-cluster-using-tiup.md index 02301aa5fd27..a370eb75363d 100644 --- a/dm/deploy-a-dm-cluster-using-tiup.md +++ b/dm/deploy-a-dm-cluster-using-tiup.md @@ -1,7 +1,6 @@ --- title: 使用 TiUP 部署 DM 集群 summary: 学习如何使用 TiUP DM 组件来部署 TiDB Data Migration 工具。 -aliases: ['/docs-cn/tidb-data-migration/dev/deploy-a-dm-cluster-using-ansible/'] --- # 使用 TiUP 部署 DM 集群 @@ -152,7 +151,7 @@ alertmanager_servers: > > - TiUP 节点可连通所有 DM-worker 节点的 `port`（默认为 `8262`）。 -更多 `master_servers.host.config` 参数说明，请参考 [master parameter](https://github.com/pingcap/tiflow/blob/master/dm/master/dm-master.toml)；更多 `worker_servers.host.config` 参数说明，请参考 [worker parameter](https://github.com/pingcap/tiflow/blob/master/dm/worker/dm-worker.toml)。 +更多 `master_servers.host.config` 参数说明，请参考 [master parameter](https://github.com/pingcap/tiflow/blob/release-8.5/dm/master/dm-master.toml)；更多 `worker_servers.host.config` 参数说明，请参考 [worker parameter](https://github.com/pingcap/tiflow/blob/release-8.5/dm/worker/dm-worker.toml)。 ## 第 3 步：执行部署命令 diff --git a/dm/dm-alert-rules.md b/dm/dm-alert-rules.md index e57a2d80b2b0..aca9e7241644 100644 --- a/dm/dm-alert-rules.md +++ b/dm/dm-alert-rules.md @@ -1,7 +1,6 @@ --- title: DM 告警信息 summary: 介绍 DM 的告警信息。 -aliases: ['/docs-cn/tidb-data-migration/dev/alert-rules/'] --- # DM 告警信息 diff --git a/dm/dm-best-practices.md b/dm/dm-best-practices.md index a3d2fd6603df..e7eeb3c795b8 100644 --- a/dm/dm-best-practices.md +++ b/dm/dm-best-practices.md @@ -5,7 +5,7 @@ summary: 了解使用 TiDB Data Migration (DM) 进行数据迁移的一些最佳 # DM 数据迁移最佳实践 -[TiDB Data Migration (DM)](https://github.com/pingcap/tiflow/tree/master/dm) 是由 PingCAP 开发维护的数据迁移同步工具，主要支持的源数据库类型为各类遵循 MySQL 协议标准的关系型数据库，如 MySQL、Percona MySQL、MariaDB、Amazon RDS for MySQL、Amazon Aurora 等。 +[TiDB Data Migration (DM)](https://github.com/pingcap/tiflow/tree/release-8.5/dm) 是由 PingCAP 开发维护的数据迁移同步工具，主要支持的源数据库类型为各类遵循 MySQL 协议标准的关系型数据库，如 MySQL、Percona MySQL、MariaDB、Amazon RDS for MySQL、Amazon Aurora 等。 DM 的使用场景主要有： @@ -30,7 +30,7 @@ DM 的性能参数如下表所示。 - DM 支持同时管理 1000 个同步节点（Work Node），最大同步任务数量为 600 个。为了保证同步节点的高可用，应预留一部分同步节点作为备用节点。建议预留的节点数量为已开启同步任务的同步节点数量的 20% ~ 50%。 - 单机部署 Work Node 数量。在服务器配置较好情况下，要保证每个 Work Node 至少有 2 核 CPU 加 4G 内存的可用工作资源，并且应为主机预留 10% ~ 20% 的系统资源。 - 单个同步节点（Work Node），理论最大同步 QPS 为 30K QPS/worker（不同 Schema 和 workload 会有所差异），处理上游 Binlog 的能力最高为 20 MB/s/worker。 -- 如果将 DM 作为需要长期使用的数据同步中间件，需要注意 DM 组件的部署架构。请参见 [DM-master 与 DM-woker 部署实践](#dm-master-与-dm-woker-部署实践)。 +- 如果将 DM 作为需要长期使用的数据同步中间件，需要注意 DM 组件的部署架构。请参见 [DM-master 与 DM-worker 部署实践](#dm-master-与-dm-worker-部署实践)。 ## 数据迁移前 @@ -44,7 +44,7 @@ DM 的性能参数如下表所示。 TiDB 的 `AUTO_INCREMENT` 与 MySQL 的 `AUTO_INCREMENT` 整体上看是相互兼容的。但因为 TiDB 作为分布式数据库，一般会有多个计算节点（client 端入口），应用数据写入时会将负载均分开，这就导致在有 `AUTO_INCREMENT` 列的表上，可能出现不连续的自增 ID。详细原理参考 [`AUTO_INCREMENT`](/auto-increment.md#实现原理)。 -如果业务对自增 ID 有强依赖，可以考虑使用 [`AUTO_INCREMENT` 的 MySQL 兼容模式](/auto-increment.md#mysql-兼容模式) 或 [`SEQUENCE` 函数](/sql-statements/sql-statement-create-sequence.md#sequence-函数)。 +如果业务对自增 ID 有强依赖，可以考虑使用[兼容 MySQL 的自增列模式](/auto-increment.md#兼容-mysql-的自增列模式)或 [`SEQUENCE` 函数](/sql-statements/sql-statement-create-sequence.md#sequence-函数)。 #### 是否使用聚簇索引 @@ -64,11 +64,11 @@ TiDB 在建表时可以声明为主键创建聚簇索引或非聚簇索引。下 - 聚簇索引 + AUTO_RANDOM - 此方案是目前分布式数据库既能避免出现写入热点问题，又能保留聚簇索引带来的查询收益的方案。整体改造也相对轻量，可以在业务切换使用 TiDB 作为写库时，修改 Schema 属性来达到目的。如果在后续查询时一定要利用 ID 列进行排序，可以使用 [AUTO_RANDOM](/auto-random.md) ID 列左移 5 位来保证查询数据的顺序性。示例： + 此方案是目前分布式数据库既能避免出现写入热点问题，又能保留聚簇索引带来的查询收益的方案。整体改造也相对轻量，可以在业务切换使用 TiDB 作为写库时，修改 Schema 属性来达到目的。如果在后续查询时一定要利用 ID 列进行排序，可以使用 [AUTO_RANDOM](/auto-random.md) ID 列左移 6 位（符号位 1 位 + 分片位 5 位）来保证查询数据的顺序性。示例： ```sql CREATE TABLE t (a bigint PRIMARY KEY AUTO_RANDOM, b varchar(255)); - Select a, a<<5 ,b from t order by a <<5 desc + Select a, a<<6 ,b from t order by a <<6 asc ``` 下表汇总了不同使用场景的推荐方案和优劣势。 @@ -124,7 +124,7 @@ TiDB 默认使用的字符集为 utf8mb4。建议同步上下游及应用统一 ### 实施侧要点 -#### DM-master 与 DM-woker 部署实践 +#### DM-master 与 DM-worker 部署实践 DM 整体架构分为 DM-master 与 DM-worker。 diff --git a/dm/dm-command-line-flags.md b/dm/dm-command-line-flags.md index f7154a567d30..6bb4e3305270 100644 --- a/dm/dm-command-line-flags.md +++ b/dm/dm-command-line-flags.md @@ -1,7 +1,6 @@ --- title: TiDB Data Migration 命令行参数 summary: 介绍 DM 各组件的主要命令行参数。 -aliases: ['/docs-cn/tidb-data-migration/dev/command-line-flags/'] --- # TiDB Data Migration 命令行参数 diff --git a/dm/dm-compatibility-catalog.md b/dm/dm-compatibility-catalog.md index 014acfb60a05..1ea5b6a1c797 100644 --- a/dm/dm-compatibility-catalog.md +++ b/dm/dm-compatibility-catalog.md @@ -1,46 +1,59 @@ --- title: TiDB Data Migration 兼容性目录 -summary: 了解 DM 各版本与上下游各类型数据库的兼容关系 +summary: 了解 TiDB Data Migration (DM) 各版本与上下游各类型数据库的兼容关系。 --- # TiDB Data Migration 兼容性目录 -DM 数据同步软件支持从不同类型的数据源迁移到 TiDB 集群。针对各种数据源类型，产品支持程度可以分为四个级别： +TiDB Data Migration (DM) 数据迁移工具可以将数据从不同类型的数据源迁移到 TiDB 集群。针对各种数据源类型，DM 定义了以下四种兼容性级别： -- **正式支持**：该场景经过验证，并且通过完整的测试流程。 -- **实验支持**：虽然通过部分验证，但测试尚未覆盖所有预设场景或用户较少，存在少量场景下可能出错的风险。 -- **未测试**：DM 在迭代过程中尽量保证 MySQL 协议的兼容性，但由于资源限制，无法测试所有 MySQL 衍生版本。因此虽然技术原理上兼容，但是并未经完整测试，需要使用前自行验证。 -- **不兼容**：已发现明确不兼容的情况，不建议在生产环境中使用。 +- **正式支持 (GA)**：该场景已经过验证，并且通过了完整的测试流程。 +- **实验支持**：常见的应用场景已验证，但覆盖范围有限，或仅涉及少量用户。可能会偶发问题，因此需要在你的具体场景中验证兼容性。 +- **未测试**：DM 尽量保证兼容 MySQL 协议和 binlog，但并非所有 MySQL 分支或版本都包含在 DM 的测试矩阵中。如果某个分支或版本使用了与 MySQL 兼容的协议和 binlog 格式，理论上应能正常工作，但在使用前必须在你自己的环境中验证兼容性。 +- **不兼容**：DM 存在已知不兼容的情况，不建议在生产环境中使用。 ## 数据源 -|数据源|级别|备注| -|-|-|-| -|MySQL ≤ 5.5|未测试| -|MySQL 5.6|正式支持|| -|MySQL 5.7|正式支持|| -|MySQL 8.0|正式支持|不支持 binlog 事务压缩 [Transaction_payload_event](https://dev.mysql.com/doc/refman/8.0/en/binary-log-transaction-compression.html)| -|MariaDB < 10.1.2|不兼容|时间类型的 binlog 不兼容| -|MariaDB 10.1.2 ~ 10.5.10|实验支持|| -|MariaDB > 10.5.10|不兼容|检查环节存在权限报错| +| 数据源 |级别 | 说明 | +| - | - | - | +| MySQL ≤ 5.5 | 未测试 | +| MySQL 5.6 | 正式支持 | | +| MySQL 5.7 | 正式支持 | | +| MySQL 8.0 | 正式支持 | 不支持 binlog 事务压缩 [Transaction_payload_event](https://dev.mysql.com/doc/refman/8.0/en/binary-log-transaction-compression.html)。 | +| MySQL 8.1 ~ 8.3 | 未测试 | | +| MySQL 8.4 | 不兼容 | 更多信息，请参考 [DM Issue #11020](https://github.com/pingcap/tiflow/issues/11020)。| +| MySQL 9.x | 未测试 | | +| MariaDB < 10.1.2 | 不兼容 | 与时间类型的 binlog 不兼容。 | +| MariaDB 10.1.2 ~ 10.5.10 | 实验支持 | | +| MariaDB > 10.5.10 | 未测试 | 在绕过[前置检查](/dm/dm-precheck.md)后，理论上大多数情况下可以正常工作。参见 [MariaDB 说明](#mariadb-说明)。 | + +### 与外键 CASCADE 操作的不兼容性 + +- DM 会在目标端创建外键约束，但在应用事务时不会强制执行，因为 DM 设置了会话变量 [`foreign_key_checks=OFF`](/system-variables.md#foreign_key_checks)。 +- DM 默认**不**支持 `ON DELETE CASCADE` 和 `ON UPDATE CASCADE` 行为，并且不推荐通过 DM 任务会话变量启用 `foreign_key_checks`。如果你的负载依赖于级联操作，**不要假设**级联效果会被复制。 + +### MariaDB 说明 + +- 对于 MariaDB **10.5.11 及更高版本**，由于权限名称发生变化（例如 `BINLOG MONITOR`、`REPLICATION SLAVE ADMIN`、`REPLICATION MASTER ADMIN`），DM 前置检查会失败。报错信息显示为 `[code=26005] fail to check synchronization configuration`，出现在复制权限、导出权限和导出连接数检查中。 +- 你可以通过在 DM 任务中添加 `ignore-checking-items: ["all"]` 来**绕过前置检查**。详情参见 [DM 前置检查](/dm/dm-precheck.md)。 ## 目标数据库 > **警告：** > -> 不建议使用 DM 5.3.0，因为当使用 GTID 同步且未开启 Relay log 的情况下，低概率会出现数据不同步。 - -|目标数据库|级别|DM 版本| -|-|-|-| -|TiDB 8.x|正式支持|最低 5.3.1| -|TiDB 7.x|正式支持|最低 5.3.1| -|TiDB 6.x|正式支持|最低 5.3.1| -|TiDB 5.4|正式支持|最低 5.3.1| -|TiDB 5.3|正式支持|最低 5.3.1| -|TiDB 5.2|正式支持|最低 2.0.7，建议 5.4 版本| -|TiDB 5.1|正式支持|最低 2.0.4，建议 5.4 版本| -|TiDB 5.0|正式支持|最低 2.0.4，建议 5.4 版本| -|TiDB 4.x|正式支持|最低 2.0.1，建议 2.0.7 版本| -|TiDB 3.x|正式支持|最低 2.0.1，建议 2.0.7 版本| -|MySQL|实验支持|| -|MariaDB|实验支持|| +> 不建议使用 DM v5.3.0。在 DM v5.3.0 中启用 GTID 复制但未启用 relay log 时，尽管概率较低，但可能会导致数据复制失败。 + +| 目标数据库 | 级别 | DM 版本 | +| - | - | - | +| TiDB 8.x | 正式支持 | 最低 5.3.1 | +| TiDB 7.x | 正式支持 | 最低 5.3.1 | +| TiDB 6.x | 正式支持 | 最低 5.3.1 | +| TiDB 5.4 | 正式支持 | 最低 5.3.1 | +| TiDB 5.3 | 正式支持 | 最低 5.3.1 | +| TiDB 5.2 | 正式支持 | 最低 2.0.7，建议 5.4 版本 | +| TiDB 5.1 | 正式支持 | 最低 2.0.4，建议 5.4 版本 | +| TiDB 5.0 | 正式支持 | 最低 2.0.4，建议 5.4 版本 | +| TiDB 4.x | 正式支持 | 最低 2.0.1，建议 2.0.7 版本 | +| TiDB 3.x | 正式支持 | 最低 2.0.1，建议 2.0.7 版本 | +| MySQL | 实验支持 | | +| MariaDB | 实验支持 | | diff --git a/dm/dm-config-overview.md b/dm/dm-config-overview.md index 404de1346cc7..7dd32a2e586d 100644 --- a/dm/dm-config-overview.md +++ b/dm/dm-config-overview.md @@ -1,6 +1,5 @@ --- title: DM 配置简介 -aliases: ['/docs-cn/tidb-data-migration/dev/config-overview/'] summary: 本文简要介绍了 DM（数据迁移）的配置文件和数据迁移任务的配置。配置文件包括 dm-master.toml、dm-worker.toml 和 source.yaml，分别用于配置 DM-master 进程、DM-worker 进程和上游数据库 MySQL/MariaDB。创建数据迁移任务的具体步骤包括使用 dmctl 加载数据源配置、参考数据任务配置向导创建 your_task.yaml 文件，以及使用 dmctl 创建数据迁移任务。关键概念包括 source-id、DM-master ID 和 DM-worker ID，分别用于唯一确定 MySQL 或 MariaDB 实例、DM-master 和 DM-worker。 --- diff --git a/dm/dm-create-task.md b/dm/dm-create-task.md index 305605e5e27b..cf5104ee382d 100644 --- a/dm/dm-create-task.md +++ b/dm/dm-create-task.md @@ -1,7 +1,6 @@ --- title: 创建 TiDB Data Migration 数据迁移任务 summary: 了解 TiDB Data Migration 如何创建数据迁移任务。 -aliases: ['/docs-cn/tidb-data-migration/dev/create-task/'] --- # 创建 TiDB Data Migration 数据迁移任务 diff --git a/dm/dm-customized-secret-key.md b/dm/dm-customized-secret-key.md index 5f9cc6b52a7b..71baadb2bf31 100644 --- a/dm/dm-customized-secret-key.md +++ b/dm/dm-customized-secret-key.md @@ -10,7 +10,7 @@ summary: 介绍如何自定义密钥，用于加密和解密 DM（Data Migration ## 使用方式 1. 创建一个自定义的密钥文件，文件内容必须为长度为 64 个字符的十六进制的 AES-256 密钥。一种生成该秘钥的方式是对随机内容计算 SHA256 校验和，比如 `head -n 256 /dev/urandom | sha256sum`。 -2. 在 DM-master [启动参数](/dm/dm-command-line-flags.md)或[配置文件](/dm/dm-master-configuration-file.md) 中，设置 `secret-key-path` 为你自定义的密钥文件的路径。 +2. 在 DM-master [启动参数](/dm/dm-command-line-flags.md)或[配置文件](/dm/dm-master-configuration-file.md)中，设置 `secret-key-path` 为你自定义的密钥文件的路径。 ## 从低于 v8.0.0 的版本升级 @@ -18,14 +18,14 @@ summary: 介绍如何自定义密钥，用于加密和解密 DM（Data Migration - 如果[数据源配置](/dm/dm-source-configuration-file.md)和[迁移任务配置](/dm/task-configuration-file-full.md)里使用的都是明文密码，则升级不需要做额外处理。 - 如果[数据源配置](/dm/dm-source-configuration-file.md)和[迁移任务配置](/dm/task-configuration-file-full.md)里使用了加密密码，或者后续希望使用加密密码，则需进行以下操作： - 1. 在 [DM-master 配置文件](/dm/dm-master-configuration-file.md) 中，增加 `secret-key-path` 参数，将其设置为你自定义的密钥文件的路径。该文件内容须为长度为 64 个字符的十六进制的 AES-256 密钥。如果升级前使用了[固定的 AES-256 密钥](https://github.com/pingcap/tiflow/blob/1252979421fc83ffa2a1548d981e505f7fc0b909/dm/pkg/encrypt/encrypt.go#L27) 进行加密，可拷贝该秘钥到你的秘钥文件中。请确保所有 DM-master 节点使用相同的密钥配置。 + 1. 在 [DM-master 配置文件](/dm/dm-master-configuration-file.md)中，增加 `secret-key-path` 参数，将其设置为你自定义的密钥文件的路径。该文件内容须为长度为 64 个字符的十六进制的 AES-256 密钥。如果升级前使用了[固定的 AES-256 密钥](https://github.com/pingcap/tiflow/blob/1252979421fc83ffa2a1548d981e505f7fc0b909/dm/pkg/encrypt/encrypt.go#L27)进行加密，可拷贝该秘钥到你的秘钥文件中。请确保所有 DM-master 节点使用相同的密钥配置。 2. 先滚动升级 DM-master，然后滚动升级 DM-worker，具体参考[滚动升级](/dm/maintain-dm-using-tiup.md#滚动升级)。 ## 更新加解密 key 如需更新用于加密和解密的密钥，请按照以下顺序进行： -1. 更新 [DM-master 配置文件](/dm/dm-master-configuration-file.md) 中的 `secret-key-path`。 +1. 更新 [DM-master 配置文件](/dm/dm-master-configuration-file.md)中的 `secret-key-path`。 > **注意：** > diff --git a/dm/dm-daily-check.md b/dm/dm-daily-check.md index 9c6e8e5e5136..27285c7083ad 100644 --- a/dm/dm-daily-check.md +++ b/dm/dm-daily-check.md @@ -1,7 +1,6 @@ --- title: TiDB Data Migration 日常巡检 summary: 了解 DM 工具的日常巡检。 -aliases: ['/docs-cn/tidb-data-migration/dev/daily-check/'] --- # TiDB Data Migration 日常巡检 diff --git a/dm/dm-dml-replication-logic.md b/dm/dm-dml-replication-logic.md index 990590d8f224..e844d3151e18 100644 --- a/dm/dm-dml-replication-logic.md +++ b/dm/dm-dml-replication-logic.md @@ -60,7 +60,7 @@ MySQL binlog 顺序同步模型要求按照 binlog 顺序依次同步 binlog eve DM 通过冲突检测机制，识别出需要顺序执行的 binlog，确保这些 binlog 顺序执行的同时，最大程度地保持其他 binlog 并发执行，以此提高 binlog 同步的性能。 -Causality 采用一种类似并查集的算法，对每一个 DML 进行分类，将相互关联的 DML 分为一组。具体算法可参考[并行执行 DML](https://pingcap.com/zh/blog/tidb-binlog-source-code-reading-8#并行执行DML)。 +Causality 采用一种类似并查集的算法，对每一个 DML 进行分类，将相互关联的 DML 分为一组。具体算法可参考[并行执行 DML](https://tidb.net/blog/bae66851#并行执行%20DML)。 ### Merger diff --git a/dm/dm-error-handling.md b/dm/dm-error-handling.md index 812cd471306c..11245c6fc8b8 100644 --- a/dm/dm-error-handling.md +++ b/dm/dm-error-handling.md @@ -1,7 +1,6 @@ --- title: TiDB Data Migration 故障及处理方法 summary: 了解 DM 的错误系统及常见故障的处理方法。 -aliases: ['/docs-cn/tidb-data-migration/dev/error-handling/','/docs-cn/tidb-data-migration/dev/troubleshoot-dm/','/docs-cn/tidb-data-migration/dev/error-system/'] --- # TiDB Data Migration 故障及处理方法 @@ -68,7 +67,7 @@ aliases: ['/docs-cn/tidb-data-migration/dev/error-handling/','/docs-cn/tidb-data DM 根据错误的严重程度和必要性来选择是否输出错误堆栈。错误堆栈记录了错误发生时完整的堆栈调用信息。如果用户通过错误基本信息和错误 message 描述不能完全诊断出错误发生的原因，可以通过错误堆栈进一步跟进出错时代码的运行路径。 -可在 DM 代码仓库[已发布的错误码](https://github.com/pingcap/tiflow/blob/master/dm/_utils/terror_gen/errors_release.txt) 中查询完整的错误码列表。 +可在 DM 代码仓库[已发布的错误码](https://github.com/pingcap/tiflow/blob/release-8.5/dm/_utils/terror_gen/errors_release.txt)中查询完整的错误码列表。 ## DM 故障诊断 @@ -76,7 +75,7 @@ aliases: ['/docs-cn/tidb-data-migration/dev/error-handling/','/docs-cn/tidb-data 1. 执行 `query-status` 命令查看任务运行状态以及相关错误输出。 -2. 查看与该错误相关的日志文件。日志文件位于 DM-master、DM-worker 部署节点上，通过 [DM 错误系统](#dm-错误系统) 获取错误的关键信息，然后查看[常见故障处理方法](#常见故障处理方法)以寻找相应的解决方案。 +2. 查看与该错误相关的日志文件。日志文件位于 DM-master、DM-worker 部署节点上，通过 [DM 错误系统](#dm-错误系统)获取错误的关键信息，然后查看[常见故障处理方法](#常见故障处理方法)以寻找相应的解决方案。 3. 如果该错误还没有相应的解决方案，并且你无法通过查询日志或监控指标自行解决此问题，请从 PingCAP 官方或 TiDB 社区[获取支持](/support.md)。 @@ -99,7 +98,7 @@ aliases: ['/docs-cn/tidb-data-migration/dev/error-handling/','/docs-cn/tidb-data | `code=10003` | 数据库底层 `invalid connection` 错误，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启、TiKV busy 等）且当前请求已有部分数据发送到了 TiDB。 | DM 提供针对此类错误的自动恢复。如果未能正常恢复，需要用户进一步检查错误信息并根据具体场景进行分析。 | | `code=10005` | 数据库查询类语句出错 | | | `code=10006` | 数据库 `EXECUTE` 类型语句出错，包括 DDL 和 `INSERT`/`UPDATE`/`DELETE` 类型的 DML。更详细的错误信息可通过错误 message 获取。错误 message 中通常包含操作数据库所返回的错误码和错误信息。 | | -| `code=11006` | DM 内置的 parser 解析不兼容的 DDL 时出错 | 可参考 [Data Migration 故障诊断-处理不兼容的 DDL 语句](/dm/dm-faq.md#如何处理不兼容的-ddl-语句) 提供的解决方案 | +| `code=11006` | DM 内置的 parser 解析不兼容的 DDL 时出错 | 可参考 [Data Migration 故障诊断-处理不兼容的 DDL 语句](/dm/dm-faq.md#如何处理不兼容的-ddl-语句)提供的解决方案 | | `code=20010` | 处理任务配置时，解密数据库的密码出错 | 检查任务配置中提供的下游数据库密码是否有[使用 dmctl 正确加密](/dm/dm-manage-source.md#加密数据库密码) | | `code=26002` | 任务检查创建数据库连接失败。更详细的错误信息可通过错误 message 获取。错误 message 中包含操作数据库所返回的错误码和错误信息。 | 检查 DM-master 所在的机器是否有权限访问上游 | | `code=32001` | dump 处理单元异常 | 如果报错 `msg` 包含 `mydumper: argument list too long.`，则需要用户根据 block-allow-list，在 `task.yaml` 的 dump 处理单元的 `extra-args` 参数中手动加上 `--regex` 正则表达式设置要导出的库表。例如，如果要导出所有库中表名字为 `hello` 的表，可加上 `--regex '.*\\.hello$'`，如果要导出所有表，可加上 `--regex '.*'`。 | diff --git a/dm/dm-faq.md b/dm/dm-faq.md index e41c2f95313f..28558be2a5b9 100644 --- a/dm/dm-faq.md +++ b/dm/dm-faq.md @@ -1,6 +1,5 @@ --- title: Data Migration 常见问题 -aliases: ['/docs-cn/tidb-data-migration/dev/faq/'] summary: 数据迁移常见问题包括：DM 是否支持迁移阿里 RDS 和其他云数据库的数据、task 配置中的黑白名单的正则表达式是否支持非获取匹配、处理不兼容的 DDL 语句、重置数据迁移任务、全量导入过程中遇到报错等。 --- @@ -156,7 +155,7 @@ DM 在最后 `rename ghost_table to origin table` 的步骤会把内存的 DDL 用户需要首先确认任务中没有配置 `disable-detect`（v2.0.7 及之前版本），没有其他同步程序或手动插入数据，表中没有配置相关的 DML 过滤器。 -为了便于排查问题，用户收集到下游 TiDB 相关 general log 后可以在 [AskTUG 社区](https://asktug.com/tags/dm) 联系专家进行排查。收集 general log 的方式如下： +为了便于排查问题，用户收集到下游 TiDB 相关 general log 后可以在 [AskTUG 社区](https://asktug.com/tags/dm)联系专家进行排查。收集 general log 的方式如下： ```bash # 开启 general log @@ -198,7 +197,7 @@ if the DDL is not needed, you can use a filter rule with \"*\" schema-pattern to 该情况有两种解决方案： - 如果数据量较小（TB 级以下）或任务有合库合表：清空下游数据库的已导入数据，同时清空导出数据目录，使用 dmctl 删除并 `start-task --remove-meta` 重建任务。后续尽量保证全量导出导入阶段 DM 没有冗余 worker 以及避免在该时段内重启或升级 DM 集群。 -- 如果数据量较大（数 TB 或更多）：清空下游数据库的已导入数据，将 lightning 部署到数据所在的 DM worker 节点，使用 [lightning local backend 模式](/tidb-lightning/deploy-tidb-lightning.md) 导入 DM dump 单元导出的数据。全量导入完成后，修改任务的 `task-mode` 为 `incremental`，修改 `mysql-instance.meta.pos` 为 dump 单元导出数据 `metadata` 中记录的位置，启动一个增量任务。 +- 如果数据量较大（数 TB 或更多）：清空下游数据库的已导入数据，将 lightning 部署到数据所在的 DM worker 节点，使用 [lightning local backend 模式](/tidb-lightning/deploy-tidb-lightning.md)导入 DM dump 单元导出的数据。全量导入完成后，修改任务的 `task-mode` 为 `incremental`，修改 `mysql-instance.meta.pos` 为 dump 单元导出数据 `metadata` 中记录的位置，启动一个增量任务。 ## 使用 DM 同步数据时重启 DM 进程，增量任务出现 `ERROR 1236 (HY000): The slave is connecting using CHANGE MASTER TO MASTER_AUTO_POSITION = 1, but the master has purged binary logs containing GTIDs that the slave requires.` 错误 @@ -218,7 +217,7 @@ if the DDL is not needed, you can use a filter rule with \"*\" schema-pattern to - 方法一：使用 `tiup update --self && tiup update dm` 升级 TiUP 到更新版本，随后先缩容再扩容集群中的 grafana 节点，重建 grafana 服务。 - 方法二： 1. 备份 `deploy/grafana-$port/bin/public` 文件夹。 - 2. 下载 [TiUP DM 离线镜像包](https://download.pingcap.org/tidb-dm-v2.0.1-linux-amd64.tar.gz)，并进行解压，将其中的 grafana-v4.0.3-**.tar.gz 文件解压后，用解压出的 public/ 文件夹替换前面所描述的文件夹，运行 `tiup dm restart $cluster_name -R grafana` 重启 grafana 服务监控。 + 2. 下载 [TiUP DM 离线镜像包](https://download.pingcap.com/tidb-dm-v2.0.1-linux-amd64.tar.gz)，并进行解压，将其中的 grafana-v4.0.3-**.tar.gz 文件解压后，用解压出的 public/ 文件夹替换前面所描述的文件夹，运行 `tiup dm restart $cluster_name -R grafana` 重启 grafana 服务监控。 ## 在 DM v2.0 中，同时开启 relay 与 gtid 同步 MySQL 时，运行 `query-status` 发现 syncer checkpoint 中 GTID 不连续 diff --git a/dm/dm-glossary.md b/dm/dm-glossary.md index 747162bff7b4..4bf2b24d2ff5 100644 --- a/dm/dm-glossary.md +++ b/dm/dm-glossary.md @@ -1,7 +1,6 @@ --- title: TiDB Data Migration 术语表 summary: 学习 TiDB Data Migration 相关术语 -aliases: ['/docs-cn/tidb-data-migration/dev/glossary/'] --- # TiDB Data Migration 术语表 @@ -14,11 +13,11 @@ aliases: ['/docs-cn/tidb-data-migration/dev/glossary/'] ### Binlog -在 TiDB DM 中，Binlog 通常指 MySQL/MariaDB 生成的 binary log 文件，具体请参考 [MySQL Binary Log](https://dev.mysql.com/doc/dev/mysql-server/latest/page_protocol_replication.html) 与 [MariaDB Binary Log](https://mariadb.com/kb/en/library/binary-log/)。 +在 TiDB DM 中，Binlog 通常指 MySQL/MariaDB 生成的 binary log 文件，具体请参考 [MySQL Binary Log](https://dev.mysql.com/doc/dev/mysql-server/latest/page_protocol_replication.html) 与 [MariaDB Binary Log](https://mariadb.com/docs/server/server-management/server-monitoring-logs/binary-log)。 ### Binlog event -MySQL/MariaDB 生成的 Binlog 文件中的数据变更信息，具体请参考 [MySQL Binlog Event](https://dev.mysql.com/doc/dev/mysql-server/latest/page_protocol_replication_binlog_event.html) 与 [MariaDB Binlog Event](https://mariadb.com/kb/en/library/1-binlog-events/)。 +MySQL/MariaDB 生成的 Binlog 文件中的数据变更信息，具体请参考 [MySQL Binlog Event](https://dev.mysql.com/doc/dev/mysql-server/latest/page_protocol_replication_binlog_event.html) 与 [MariaDB Binlog Event](https://mariadb.com/docs/server/reference/clientserver-protocol/replication-protocol/1-binlog-events)。 ### Binlog event filter @@ -26,7 +25,7 @@ MySQL/MariaDB 生成的 Binlog 文件中的数据变更信息，具体请参考 ### Binlog position -特定 Binlog event 在 Binlog 文件中的位置偏移信息，具体请参考 [MySQL `SHOW BINLOG EVENTS`](https://dev.mysql.com/doc/refman/8.0/en/show-binlog-events.html) 与 [MariaDB `SHOW BINLOG EVENTS`](https://mariadb.com/kb/en/library/show-binlog-events/)。 +特定 Binlog event 在 Binlog 文件中的位置偏移信息，具体请参考 [MySQL `SHOW BINLOG EVENTS`](https://dev.mysql.com/doc/refman/8.0/en/show-binlog-events.html) 与 [MariaDB `SHOW BINLOG EVENTS`](https://mariadb.com/docs/server/reference/sql-statements/administrative-sql-statements/show/show-binlog-events)。 ### Binlog replication 处理单元/ sync 处理单元 @@ -34,7 +33,7 @@ DM-worker 内部用于读取上游 Binlog 或本地 Relay log 并迁移到下游 ### Block & allow table list -针对上游数据库实例表的黑白名单过滤功能，具体可参考 [Block & Allow Table Lists](/dm/dm-block-allow-table-lists.md)。该功能与 [MySQL Replication Filtering](https://dev.mysql.com/doc/refman/8.0/en/replication-rules.html) 及 [MariaDB Replication Filters](https://mariadb.com/kb/en/library/replication-filters/) 类似。 +针对上游数据库实例表的黑白名单过滤功能，具体可参考 [Block & Allow Table Lists](/dm/dm-block-allow-table-lists.md)。该功能与 [MySQL Replication Filtering](https://dev.mysql.com/doc/refman/8.0/en/replication-rules.html) 及 [MariaDB Replication Filters](https://mariadb.com/docs/server/ha-and-performance/standard-replication/replication-filters) 类似。 ### Bound @@ -49,7 +48,7 @@ TiDB DM 在全量导入与增量复制过程中的断点信息，用于在重新 - 对于全量导入，Checkpoint 信息对应于每个数据文件已经被成功导入的数据对应的文件内偏移量等信息，其在每个导入数据的事务中迁移更新； - 对于增量复制，Checkpoint 信息对应于已经成功解析并导入到下游的 [Binlog event](#binlog-event) 对应的 [Binlog position](#binlog-position) 等信息，其在 DDL 导入成功后或距上次更新时间超过 30 秒等条件下更新。 -另外，[Relay 处理单元](#relay-处理单元) 对应的 `relay.meta` 内记录的信息也相当于 Checkpoint，其对应于 Relay 处理单元已经成功从上游拉取并写入到 [Relay log](#relay-log) 的 [Binlog event](#binlog-event) 对应的 [Binlog position](#binlog-position) 或 [GTID](#gtid) 信息。 +另外，[Relay 处理单元](#relay-处理单元)对应的 `relay.meta` 内记录的信息也相当于 Checkpoint，其对应于 Relay 处理单元已经成功从上游拉取并写入到 [Relay log](#relay-log) 的 [Binlog event](#binlog-event) 对应的 [Binlog position](#binlog-position) 或 [GTID](#gtid) 信息。 ## D @@ -69,7 +68,7 @@ DM-worker 内部用于从上游导出全量数据的处理单元，每个 Subtas ### GTID -MySQL/MariaDB 的全局事务 ID，当启用该功能后会在 Binlog 文件中记录 GTID 相关信息，多个 GTID 即组成为 GTID Set，具体请参考 [MySQL GTID Format and Storage](https://dev.mysql.com/doc/refman/8.0/en/replication-gtids-concepts.html) 与 [MariaDB Global Transaction ID](https://mariadb.com/kb/en/library/gtid/)。 +MySQL/MariaDB 的全局事务 ID，当启用该功能后会在 Binlog 文件中记录 GTID 相关信息，多个 GTID 即组成为 GTID Set，具体请参考 [MySQL GTID Format and Storage](https://dev.mysql.com/doc/refman/8.0/en/replication-gtids-concepts.html) 与 [MariaDB Global Transaction ID](https://mariadb.com/docs/server/ha-and-performance/standard-replication/gtid)。 ## L @@ -89,7 +88,7 @@ DM-worker 内部用于将全量导出数据导入到下游的处理单元，每 ### Relay log -DM-worker 从上游 MySQL/MariaDB 拉取 Binlog 后存储在本地的文件，当前其格式为标准的 Binlog 格式，可使用版本兼容的 [mysqlbinlog](https://dev.mysql.com/doc/refman/8.0/en/mysqlbinlog.html) 等工具进行解析。其作用与 [MySQL Relay Log](https://dev.mysql.com/doc/refman/8.0/en/replica-logs-relaylog.html) 及 [MariaDB Relay Log](https://mariadb.com/kb/en/library/relay-log/) 相近。 +DM-worker 从上游 MySQL/MariaDB 拉取 Binlog 后存储在本地的文件，当前其格式为标准的 Binlog 格式，可使用版本兼容的 [mysqlbinlog](https://dev.mysql.com/doc/refman/8.0/en/mysqlbinlog.html) 等工具进行解析。其作用与 [MySQL Relay Log](https://dev.mysql.com/doc/refman/8.0/en/replica-logs-relaylog.html) 及 [MariaDB Relay Log](https://mariadb.com/docs/server/server-management/server-monitoring-logs/binary-log/relay-log) 相近。 有关 TiDB DM 内 Relay log 的目录结构、初始迁移规则、数据清理等内容，可参考 [TiDB DM Relay Log](/dm/relay-log.md)。 diff --git a/dm/dm-handle-alerts.md b/dm/dm-handle-alerts.md index 836d7f84a7e7..3ef6d76ee719 100644 --- a/dm/dm-handle-alerts.md +++ b/dm/dm-handle-alerts.md @@ -1,7 +1,6 @@ --- title: TiDB Data Migration 处理告警 summary: 了解 DM 中各主要告警信息的处理方法。 -aliases: ['/docs-cn/tidb-data-migration/dev/handle-alerts/'] --- # TiDB Data Migration 处理告警 diff --git a/dm/dm-handle-performance-issues.md b/dm/dm-handle-performance-issues.md index a413ba79c5d2..34c15382ad13 100644 --- a/dm/dm-handle-performance-issues.md +++ b/dm/dm-handle-performance-issues.md @@ -1,7 +1,6 @@ --- title: TiDB Data Migration 性能问题及处理方法 summary: 了解 DM 可能存在的常见性能问题及其处理方法。 -aliases: ['/docs-cn/tidb-data-migration/dev/handle-performance-issues/'] --- # TiDB Data Migration 性能问题及处理方法 @@ -14,7 +13,7 @@ aliases: ['/docs-cn/tidb-data-migration/dev/handle-performance-issues/'] 在诊断问题前，也可以先了解 DM 的[性能测试报告](https://github.com/pingcap/docs-dm/blob/release-5.3/zh/dm-benchmark-v5.3.0.md)。 -当数据迁移过程存在较大延迟时，若需快速定位瓶颈是在 DM 组件内部还是在 TiDB 集群，可先排查[写入 SQL 到下游](#写入-sql-到下游) 部分的 `DML queue remain length`。 +当数据迁移过程存在较大延迟时，若需快速定位瓶颈是在 DM 组件内部还是在 TiDB 集群，可先排查[写入 SQL 到下游](#写入-sql-到下游)部分的 `DML queue remain length`。 ## relay log 模块的性能问题及处理方法 @@ -60,7 +59,7 @@ Load 模块主要操作为从本地读取 SQL 文件数据并写入到下游， 在 [Binlog replication 的监控部分](/dm/monitor-a-dm-cluster.md#binlog-replication)，可以主要通过 `binlog file gap between master and syncer` 监控项确认是否存在性能问题，如果该指标长时间大于 1，则通常表明存在性能问题；如果该指标基本为 0，则一般表明没有性能问题。 -如果 `binlog file gap between master and syncer` 长时间大于 1，则可以再通过 `binlog file gap between relay and syncer` 判断延迟主要存在于哪个模块，如果该值基本为 0，则延迟可能存在于 relay log 模块，请先参考 [relay log 模块的性能问题及处理方法](#relay-log-模块的性能问题及处理方法) 进行处理；否则继续对 Binlog replication 进行排查。 +如果 `binlog file gap between master and syncer` 长时间大于 1，则可以再通过 `binlog file gap between relay and syncer` 判断延迟主要存在于哪个模块，如果该值基本为 0，则延迟可能存在于 relay log 模块，请先参考 [relay log 模块的性能问题及处理方法](#relay-log-模块的性能问题及处理方法)进行处理；否则继续对 Binlog replication 进行排查。 ### 读取 binlog 数据 diff --git a/dm/dm-hardware-and-software-requirements.md b/dm/dm-hardware-and-software-requirements.md index e7a180a0701d..d5eae456d9d5 100644 --- a/dm/dm-hardware-and-software-requirements.md +++ b/dm/dm-hardware-and-software-requirements.md @@ -1,7 +1,6 @@ --- title: TiDB Data Migration 集群软硬件环境需求 summary: 了解部署 DM 集群的软件和硬件要求。 -aliases: ['/docs-cn/tidb-data-migration/dev/hardware-and-software-requirements/'] --- # TiDB Data Migration 集群软硬件环境需求 diff --git a/dm/dm-manage-source.md b/dm/dm-manage-source.md index 32c3ca05970a..44331059042c 100644 --- a/dm/dm-manage-source.md +++ b/dm/dm-manage-source.md @@ -1,7 +1,6 @@ --- title: 管理 TiDB Data Migration 上游数据源 summary: 了解如何管理上游 MySQL 实例。 -aliases: ['/docs-cn/tidb-data-migration/dev/manage-source/'] --- # 管理 TiDB Data Migration 上游数据源 diff --git a/dm/dm-master-configuration-file.md b/dm/dm-master-configuration-file.md index 6068ef052505..e26aab632289 100644 --- a/dm/dm-master-configuration-file.md +++ b/dm/dm-master-configuration-file.md @@ -1,6 +1,5 @@ --- title: DM-master 配置文件介绍 -aliases: ['/docs-cn/tidb-data-migration/dev/dm-master-configuration-file/'] summary: 本文介绍了 DM-master 的配置文件，包括示例配置和配置项说明。示例配置包括日志配置、DM-master 监听地址、集群配置等。配置项说明包括全局配置，如标识 DM-master、日志级别、日志文件、地址等。另外还包括 SSL 证书路径、证书检查 Common Name 列表和加解密密钥路径等内容。 --- @@ -43,19 +42,60 @@ secret-key-path = "/path/to/secret/key" ### Global 配置 -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `name` | 标识一个 DM-master。| -| `log-level` | 日志级别：debug、info、warn、error、fatal。默认为 info。| -| `log-file` | 日志文件，如果不配置，日志会输出到标准输出中。| -| `master-addr` | DM-master 服务的地址，可以省略 IP 信息，例如：":8261"。| -| `advertise-addr` | DM-master 向外界宣告的地址。| -| `peer-urls` | DM-master 节点的对等 URL。| -| `advertise-peer-urls` | DM-master 向外界宣告的对等 URL。默认为 `peer-urls` 的值。| -| `initial-cluster` | 初始集群中所有 DM-master 的 `advertise-peer-urls` 的值。| -| `join` | 集群里已有的 DM-master 的 `advertise-peer-urls` 的值。如果是新加入的 DM-master 节点，使用 `join` 替代 `initial-cluster`。| -| `ssl-ca` | DM-master 组件用于与其它组件连接的 SSL CA 证书所在的路径 | -| `ssl-cert` | DM-master 组件用于与其它组件连接的 PEM 格式的 X509 证书所在的路径 | -| `ssl-key` | DM-master 组件用于与其它组件连接的 PEM 格式的 X509 密钥所在的路径 | -| `cert-allowed-cn` | 证书检查 Common Name 列表 | -| `secret-key-path` | 用来加解密上下游密码的密钥所在的路径，该文件内容必须是长度为 64 个字符的十六进制的 AES-256 密钥。一种生成该秘钥的方式是对随机内容计算 SHA256 校验和，比如 head -n 256 /dev/urandom \| sha256sum。更多信息，请参考 [DM 自定义加解密 key](/dm/dm-customized-secret-key.md)。| +#### `name` + +- 标识一个 DM-master。 + +#### `log-level` + +- 日志级别。 +- 默认值：`info` +- 可选值：`debug`、`info`、`warn`、`error`、`fatal` + +#### `log-file` + +- 日志文件。如果不配置，日志会输出到标准输出中。 + +#### `master-addr` + +- DM-master 服务的地址，可以省略 IP 信息，例如：`":8261"`。 + +#### `advertise-addr` + +- DM-master 向外界宣告的地址。 + +#### `peer-urls` + +- DM-master 节点的对等 URL。 + +#### `advertise-peer-urls` + +- DM-master 向外界宣告的对等 URL。默认为 [`peer-urls`](#peer-urls) 的值。 + +#### `initial-cluster` + +- 初始集群中所有 DM-master 的 [`advertise-peer-urls`](#advertise-peer-urls) 的值。 + +#### `join` + +- 集群里已有的 DM-master 的 [`advertise-peer-urls`](#advertise-peer-urls) 的值。如果是新加入的 DM-master 节点，使用 `join` 替代 `initial-cluster`。 + +#### `ssl-ca` + +- DM-master 组件用于与其它组件连接的 SSL CA 证书所在的路径。 + +#### `ssl-cert` + +- DM-master 组件用于与其它组件连接的 PEM 格式的 X509 证书所在的路径。 + +#### `ssl-key` + +- DM-master 组件用于与其它组件连接的 PEM 格式的 X509 密钥所在的路径。 + +#### `cert-allowed-cn` + +- 证书检查 Common Name 列表。 + +#### `secret-key-path` + +- 用来加解密上下游密码的密钥所在的路径，该文件内容必须是长度为 64 个字符的十六进制的 AES-256 密钥。一种生成该秘钥的方式是对随机内容计算 SHA256 校验和，比如 `head -n 256 /dev/urandom | sha256sum`。更多信息，请参考 [DM 自定义加解密 key](/dm/dm-customized-secret-key.md)。 diff --git a/dm/dm-open-api.md b/dm/dm-open-api.md index 1eb5fe147178..1d44d47c95b3 100644 --- a/dm/dm-open-api.md +++ b/dm/dm-open-api.md @@ -25,7 +25,7 @@ TiDB Data Migration (DM) 提供 OpenAPI 功能，你可以通过 OpenAPI 方便 > **注意：** > -> - DM 提供符合 OpenAPI 3.0.0 标准的 [Spec 文档](https://github.com/pingcap/tiflow/blob/master/dm/openapi/spec/dm.yaml)，其中包含了所有 API 的请求参数和返回体，你可自行复制到如 [Swagger Editor](https://editor.swagger.io/) 等工具中在线预览文档。 +> - DM 提供符合 OpenAPI 3.0.0 标准的 [Spec 文档](https://github.com/pingcap/tiflow/blob/release-8.5/dm/openapi/spec/dm.yaml)，其中包含了所有 API 的请求参数和返回体，你可自行复制到如 [Swagger Editor](https://editor.swagger.io/) 等工具中在线预览文档。 > > - 部署 DM-master 后，你可访问 `http://{master-addr}/api/v1/docs` 在线预览文档。 > diff --git a/dm/dm-overview.md b/dm/dm-overview.md index 8219229cb344..860a7d00cb4f 100644 --- a/dm/dm-overview.md +++ b/dm/dm-overview.md @@ -1,7 +1,6 @@ --- title: TiDB Data Migration 简介 summary: 了解 TiDB Data Migration -aliases: ['/docs-cn/tidb-data-migration/dev/overview/','/docs-cn/tools/dm/overview/','/zh/tidb/dev/quick-create-migration-task','/zh/tidb/dev/scenarios','/docs-cn/tidb-data-migration/dev/key-features/','/docs-cn/tidb-data-migration/dev/feature-overview/','/zh/tidb/dev/dm-key-features'] --- # TiDB Data Migration 简介 @@ -10,7 +9,7 @@ aliases: ['/docs-cn/tidb-data-migration/dev/overview/','/docs-cn/tools/dm/overvi ![star](https://img.shields.io/github/stars/pingcap/tiflow?style=for-the-badge&logo=github) ![license](https://img.shields.io/github/license/pingcap/tiflow?style=for-the-badge) ![forks](https://img.shields.io/github/forks/pingcap/tiflow?style=for-the-badge) --> -[TiDB Data Migration](https://github.com/pingcap/tiflow/tree/master/dm) (DM) 是一款便捷的数据迁移工具，支持从与 MySQL 协议兼容的数据库（MySQL、MariaDB、Aurora MySQL）到 TiDB 的全量数据迁移和增量数据同步。使用 DM 工具有利于简化数据迁移过程，降低数据迁移运维成本。 +[TiDB Data Migration](https://github.com/pingcap/tiflow/tree/release-8.5/dm) (DM) 是一款便捷的数据迁移工具，支持从与 MySQL 协议兼容的数据库（MySQL、MariaDB、Aurora MySQL）到 TiDB 的全量数据迁移和增量数据同步。使用 DM 工具有利于简化数据迁移过程，降低数据迁移运维成本。 ## 产品特性 @@ -62,40 +61,40 @@ tiup install dm dmctl + 向量类型数据同步 - - DM 不支持迁移或同步 MySQL 9.0 的向量数据类型到 TiDB。 + - DM 不支持迁移或同步 MySQL 的向量数据类型到 TiDB。 ## Contributing -欢迎参与 DM 开源项目并万分感谢您的贡献，可以查看 [CONTRIBUTING.md](https://github.com/pingcap/tiflow/blob/master/dm/CONTRIBUTING.md) 了解更多信息。 +欢迎参与 DM 开源项目并万分感谢您的贡献，可以查看 [CONTRIBUTING.md](https://github.com/pingcap/tiflow/blob/release-8.5/dm/CONTRIBUTING.md) 了解更多信息。 ## 社区技术支持 您可以通过在线文档了解和使用 DM，如果您遇到无法解决的问题，可以选择以下途径之一联系我们。 -- [GitHub](https://github.com/pingcap/tiflow/tree/master/dm) +- [GitHub](https://github.com/pingcap/tiflow/tree/release-8.5/dm) - [AskTUG](https://asktug.com/tags/dm) ## License -DM 遵循 Apache 2.0 协议，在 [LICENSE](https://github.com/pingcap/tiflow/blob/master/LICENSE) 了解更多信息。 +DM 遵循 Apache 2.0 协议，在 [LICENSE](https://github.com/pingcap/tiflow/blob/release-8.5/LICENSE) 了解更多信息。 ## 版本变更说明 在 v5.4 之前，DM 工具的文档独立于 TiDB 文档。要访问这些早期版本的 DM 文档，请点击以下链接： -- [DM v5.3 文档](https://docs.pingcap.com/zh/tidb-data-migration/v5.3) -- [DM v2.0 文档](https://docs.pingcap.com/zh/tidb-data-migration/v2.0/) -- [DM v1.0 文档](https://docs.pingcap.com/zh/tidb-data-migration/v1.0/) +- [DM v5.3 文档](https://docs-archive.pingcap.com/zh/tidb-data-migration/v5.3) +- [DM v2.0 文档](https://docs-archive.pingcap.com/zh/tidb-data-migration/v2.0/) +- [DM v1.0 文档](https://docs-archive.pingcap.com/zh/tidb-data-migration/v1.0/) > **注意：** > -> - DM 的 GitHub 代码仓库已于 2021 年 10 月迁移至 [pingcap/tiflow](https://github.com/pingcap/tiflow/tree/master/dm)。如有任何关于 DM 的问题，请在 `pingcap/tiflow` 仓库提交，以获得后续支持。 +> - DM 的 GitHub 代码仓库已于 2021 年 10 月迁移至 [pingcap/tiflow](https://github.com/pingcap/tiflow/tree/release-8.5/dm)。如有任何关于 DM 的问题，请在 `pingcap/tiflow` 仓库提交，以获得后续支持。 > - 在较早版本中（v1.0 和 v2.0），DM 采用独立于 TiDB 的版本号。从 DM v5.3 起，DM 采用与 TiDB 相同的版本号。DM v2.0 的下一个版本为 DM v5.3。DM v2.0 到 v5.3 无兼容性变更，升级过程与正常升级无差异。 要快速了解 DM 的原理架构、适用场景，建议先观看下面的培训视频。注意本视频只作为学习参考，具体操作步骤和最新功能，请以文档内容为准。 - + - + - + diff --git a/dm/dm-pause-task.md b/dm/dm-pause-task.md index 293f6a7ca2d7..21ca57b9ca09 100644 --- a/dm/dm-pause-task.md +++ b/dm/dm-pause-task.md @@ -1,7 +1,6 @@ --- title: 暂停 TiDB Data Migration 数据迁移任务 summary: 了解 TiDB Data Migration 如何暂停数据迁移任务。 -aliases: ['/docs-cn/tidb-data-migration/dev/pause-task/'] --- # 暂停 TiDB Data Migration 数据迁移任务 diff --git a/dm/dm-performance-test.md b/dm/dm-performance-test.md index a6463904b84f..2ccfbfcff289 100644 --- a/dm/dm-performance-test.md +++ b/dm/dm-performance-test.md @@ -1,7 +1,6 @@ --- title: DM 集群性能测试 summary: 了解如何测试 DM 集群的性能。 -aliases: ['/docs-cn/tidb-data-migration/dev/performance-test/'] --- # DM 集群性能测试 diff --git a/dm/dm-precheck.md b/dm/dm-precheck.md index 35e106cfbf45..89d578b3779d 100644 --- a/dm/dm-precheck.md +++ b/dm/dm-precheck.md @@ -1,7 +1,6 @@ --- title: TiDB Data Migration 任务前置检查 summary: 了解 DM 执行数据迁移任务时将进行的前置检查。 -aliases: ['/docs-cn/tidb-data-migration/dev/precheck/'] --- # TiDB Data Migration 任务前置检查 @@ -81,7 +80,7 @@ tiup dmctl check-task ./task.yaml - 主键 - 唯一索引 - - 乐观协调模式下，检查所有分表结构是否满足[乐观协调兼容](https://github.com/pingcap/tiflow/blob/master/dm/docs/RFCS/20191209_optimistic_ddl.md#modifying-column-types)。 + - 乐观协调模式下，检查所有分表结构是否满足[乐观协调兼容](https://github.com/pingcap/tiflow/blob/release-8.5/dm/docs/RFCS/20191209_optimistic_ddl.md#modifying-column-types)。 - 如果曾经通过 `start-task` 命令成功启动任务，那么将不会对一致性进行检查。 @@ -175,7 +174,7 @@ mydumpers: # dump 处理单元的运行配置参数 global: # 配置名称 threads: 4 # dump 处理单元从上游数据库实例导出数据和执行前置检查时访问上游的线程数量，默认值为 4 chunk-filesize: 64 # dump 处理单元生成的数据文件大小，默认值为 64，单位为 MB - extra-args: "--consistency none" # dump 处理单元的其他参数，不需要在 extra-args 中配置 table-list，DM 会自动生成 + extra-args: "--consistency auto" # dump 处理单元的其他参数，不需要在 extra-args 中配置 table-list，DM 会自动生成 ``` > **注意：** diff --git a/dm/dm-query-status.md b/dm/dm-query-status.md index 39857f9ee0f6..cbf0354eccf1 100644 --- a/dm/dm-query-status.md +++ b/dm/dm-query-status.md @@ -1,7 +1,6 @@ --- title: TiDB Data Migration 查询任务状态 summary: 深入了解 TiDB Data Migration 如何查询数据迁移任务状态 -aliases: ['/docs-cn/tidb-data-migration/dev/query-status/','/docs-cn/tidb-data-migration/dev/query-error/','/tidb-data-migration/dev/query-error/'] --- # TiDB Data Migration 查询任务状态 diff --git a/dm/dm-resume-task.md b/dm/dm-resume-task.md index d7753a426290..55426a5913b6 100644 --- a/dm/dm-resume-task.md +++ b/dm/dm-resume-task.md @@ -1,7 +1,6 @@ --- title: 恢复 TiDB Data Migration 数据迁移任务 summary: 了解 TiDB Data Migration 如何恢复数据迁移任务。 -aliases: ['/docs-cn/tidb-data-migration/dev/resume-task/'] --- # 恢复 TiDB Data Migration 数据迁移任务 diff --git a/dm/dm-source-configuration-file.md b/dm/dm-source-configuration-file.md index 22e7384da819..7614934cdc34 100644 --- a/dm/dm-source-configuration-file.md +++ b/dm/dm-source-configuration-file.md @@ -1,6 +1,5 @@ --- title: TiDB Data Migration 上游数据库配置文件介绍 -aliases: ['/docs-cn/tidb-data-migration/dev/source-configuration-file/'] summary: TiDB Data Migration (DM) 上游数据库配置文件包括示例与配置项说明。示例配置文件包括上游数据库的配置项，如是否开启 GTID、是否开启 relay log、拉取上游 binlog 的起始文件名等。配置项说明包括全局配置、relay log 清理策略配置、任务状态检查配置和 Binlog event filter。配置项包括标识一个 MySQL 实例、是否使用 GTID 方式、是否开启 relay log、存储 relay log 的目录等。从 DM v2.0.2 开始，Binlog event filter 也可以在上游数据库配置文件中进行配置。 --- @@ -19,7 +18,7 @@ source-id: "mysql-replica-01" enable-gtid: false # 是否开启 relay log -enable-relay: false # 该配置项从 DM v2.0.2 版本起弃用，使用 `start-relay` 命令开启 relay log +enable-relay: false relay-binlog-name: "" # 拉取上游 binlog 的起始文件名 relay-binlog-gtid: "" # 拉取上游 binlog 的起始 GTID # relay-dir: "relay-dir" # 存储 relay log 的目录，默认值为 "relay-dir"。从 v6.1 版本起该配置标记为弃用，被 worker 配置中的同名参数取代 @@ -63,49 +62,108 @@ from: ### Global 配置 -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `source-id` | 标识一个 MySQL 实例。| -| `enable-gtid` | 是否使用 GTID 方式从上游拉取 binlog，默认值为 false。一般情况下不需要手动配置，如果上游数据库启用了 GTID 支持，且需要做主从切换，则将该配置项设置为 true。 | -| `enable-relay` | 是否开启 relay log，默认值为 false。自 DM v2.0.2 版本起，该配置项弃用，需使用 `start-relay` 命令[开启 relay log](/dm/relay-log.md#开启关闭-relay-log)。 | -| `relay-binlog-name` | 拉取上游 binlog 的起始文件名，例如 "mysql-bin.000002"，该配置在 `enable-gtid` 为 false 的情况下生效。如果不配置该项，DM-worker 将从正在同步的最早的 binlog 文件开始拉取，一般情况下不需要手动配置。 | -| `relay-binlog-gtid` | 拉取上游 binlog 的起始 GTID，例如 "e9a1fc22-ec08-11e9-b2ac-0242ac110003:1-7849"，该配置在 `enable-gtid` 为 true 的情况下生效。如果不配置该项，DM-worker 将从正在同步的最早 binlog GTID 开始拉取 binlog，一般情况下不需要手动配置。 | -| `relay-dir` | 存储 relay log 的目录，默认值为 "./relay_log"。| -| `host` | 上游数据库的 host。| -| `port` | 上游数据库的端口。| -| `user` | 上游数据库使用的用户名。| -| `password` | 上游数据库的用户密码。注意：推荐使用 dmctl 加密后的密码。| -| `security` | 上游数据库 TLS 相关配置。配置的证书文件路径需能被所有节点访问。若配置为本地路径，则集群所有节点需要将证书文件拷贝一份放在各节点机器相同的路径位置上。| +#### `source-id` + +- 标识一个 MySQL 实例。 + +#### `enable-gtid` + +- 是否使用 GTID 方式从上游拉取 binlog。 +- 一般情况下不需要手动配置，如果上游数据库启用了 GTID 支持，且需要做主从切换，则将该配置项设置为 `true`。 +- 默认值：`false` + +#### `enable-relay` + +- 是否开启 relay log。从 v5.4 开始，该参数生效。此外，你可以使用 `start-relay` 命令[动态开启 relay log](/dm/relay-log.md#开启关闭-relay-log)。 +- 默认值：`false` + +#### `relay-binlog-name` + +- 拉取上游 binlog 的起始文件名，例如 `"mysql-bin.000002"`。 +- 该配置在 [`enable-gtid`](#enable-gtid) 为 `false` 的情况下生效。如果不配置该项，DM-worker 将从正在同步的最早的 binlog 文件开始拉取，一般情况下不需要手动配置。 + +#### `relay-binlog-gtid` + +- 拉取上游 binlog 的起始 GTID，例如 `"e9a1fc22-ec08-11e9-b2ac-0242ac110003:1-7849"`。 +- 该配置在 [`enable-gtid`](#enable-gtid) 为 `true` 的情况下生效。如果不配置该项，DM-worker 将从正在同步的最早 binlog GTID 开始拉取 binlog。一般情况下不需要手动配置。 + +#### `relay-dir` + +- 存储 relay log 的目录。 +- 默认值：`"./relay_log"` + +#### `host` + +- 上游数据库的 host。 + +#### `port` + +- 上游数据库的端口。 + +#### `user` + +- 上游数据库使用的用户名。 + +#### `password` + +- 上游数据库的用户密码。注意：推荐使用 dmctl 加密后的密码。 + +#### `security` + +- 上游数据库 TLS 相关配置。配置的证书文件路径需能被所有节点访问。若配置为本地路径，则集群所有节点需要将证书文件拷贝一份放在各节点机器相同的路径位置上。 ### relay log 清理策略配置（purge 配置项） 一般情况下不需要手动配置，如果 relay log 数据量较大，磁盘空间不足，则可以通过设置该配置项来避免 relay log 写满磁盘。 -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `interval` | 定期检查 relay log 是否过期的间隔时间，默认值：3600，单位：秒。 | -| `expires` | relay log 的过期时间，默认值为 0，单位：小时。未由 relay 处理单元进行写入、或已有数据迁移任务当前或未来不需要读取的 relay log 在超过过期时间后会被 DM 删除。如果不设置则 DM 不会自动清理过期的 relay log。 | -| `remain-space` | 设置最小的可用磁盘空间。当磁盘可用空间小于这个值时，DM-worker 会尝试删除 relay log，默认值：15，单位：GB。 | +#### `interval` + +- 定期检查 relay log 是否过期的间隔时间。 +- 默认值：`3600` +- 单位：秒 + +#### `expires` + +- relay log 的过期时间。 +- 未由 relay 处理单元进行写入、或已有数据迁移任务当前或未来不需要读取的 relay log 在超过过期时间后会被 DM 删除。如果不设置则 DM 不会自动清理过期的 relay log。 +- 默认值：`0` +- 单位：小时 + +#### `remain-space` + +- 设置最小的可用磁盘空间。当磁盘可用空间小于这个值时，DM-worker 会尝试删除 relay log。 +- 默认值：`15` +- 单位：GiB > **注意：** > -> 仅在 `interval` 不为 0 且 `expires` 和 `remain-space` 两个配置项中至少有一个不为 0 的情况下 DM 的自动清理策略才会生效。 +> 仅在 [`interval`](#interval) 不为 `0` 且 [`expires`](#expires) 和 [`remain-space`](#remain-space) 两个配置项中至少有一个不为 `0` 的情况下 DM 的自动清理策略才会生效。 ### 任务状态检查配置（checker 配置项） DM 会定期检查当前任务状态以及错误信息，判断恢复任务能否消除错误，并自动尝试恢复任务进行重试。DM 会使用指数回退策略调整检查间隔。这些行为可以通过如下配置进行调整： -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `check-enable` | 启用自动重试功能。 | -| `backoff-rollback` | 如果指数回退策略的间隔大于该值，且任务处于正常状态，尝试减小间隔。 | -| `backoff-max` | 指数回退策略的间隔的最大值，该值必须大于 1 秒。 | +#### `check-enable` + +- 启用自动重试功能。 + +#### `backoff-rollback` + +- 如果指数回退策略的间隔大于该值，且任务处于正常状态，尝试减小间隔。 + +#### `backoff-max` + +- 指数回退策略的间隔的最大值，该值必须大于 1 秒。 ### Binlog event filter 从 DM v2.0.2 开始，Binlog event filter 也可以在上游数据库配置文件中进行配置。 -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `case-sensitive` | Binlog event filter 标识符是否大小写敏感。默认值：false。| -| `filters` | 配置 Binlog event filter，含义见 [Binlog event filter 参数解释](/dm/dm-binlog-event-filter.md#参数解释)。 | +#### `case-sensitive` + +- Binlog event filter 标识符是否大小写敏感。 +- 默认值：`false` + +#### `filters` + +- 配置 Binlog event filter，含义见 [Binlog event filter 参数解释](/dm/dm-binlog-event-filter.md#参数解释)。 diff --git a/dm/dm-stop-task.md b/dm/dm-stop-task.md index 86fe1533bc72..ce461e145d1e 100644 --- a/dm/dm-stop-task.md +++ b/dm/dm-stop-task.md @@ -1,7 +1,6 @@ --- title: 停止 TiDB Data Migration 数据迁移任务 summary: 了解 TiDB Data Migration 如何停止数据迁移任务。 -aliases: ['/docs-cn/tidb-data-migration/dev/stop-task/'] --- # 停止 TiDB Data Migration 数据迁移任务 diff --git a/dm/dm-tune-configuration.md b/dm/dm-tune-configuration.md index 943e82f84fa1..c18c64516f02 100644 --- a/dm/dm-tune-configuration.md +++ b/dm/dm-tune-configuration.md @@ -1,7 +1,6 @@ --- title: DM 配置优化 summary: 介绍如何通过优化配置来提高数据迁移性能。 -aliases: ['/docs-cn/tidb-data-migration/dev/tune-configuration/'] --- # DM 配置优化 diff --git a/dm/dm-worker-configuration-file.md b/dm/dm-worker-configuration-file.md index 497a061f181c..8f324d968f64 100644 --- a/dm/dm-worker-configuration-file.md +++ b/dm/dm-worker-configuration-file.md @@ -1,6 +1,5 @@ --- title: DM-worker 配置文件介绍 -aliases: ['/docs-cn/tidb-data-migration/dev/dm-worker-configuration-file/'] summary: 本文介绍了 DM-worker 的配置文件，包括配置文件示例和配置项说明。配置文件示例包括了 worker 的名称、日志配置、worker 的地址等内容。配置项说明包括了全局配置中的各个配置项的说明，如 name、log-level、log-file 等。同时还介绍了一些新增的配置项，如 relay-keepalive-ttl 和 relay-dir。SSL 相关的配置项也有详细说明。 --- @@ -38,18 +37,60 @@ cert-allowed-cn = ["dm"] ### Global 配置 -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `name` | 标识一个 DM-worker。 | -| `log-level` | 日志级别：debug、info、warn、error、fatal。默认为 info。 | -| `log-file` | 日志文件，如果不配置日志会输出到标准输出中。 | -| `worker-addr` | DM-worker 服务的地址，可以省略 IP 信息，例如：":8262"。| -| `advertise-addr` | DM-worker 向外界宣告的地址。 | -| `join` | 对应一个或多个 DM-master 配置中的 [`master-addr`](/dm/dm-master-configuration-file.md#global-配置)。 | -| `keepalive-ttl` | 当绑定的上游数据源没有启用 relay log 时，DM-worker 向 DM-master 保持存活的周期，单位为秒。默认是 60 秒。 | -| `relay-keepalive-ttl` | 当绑定的上游数据源启用 relay log 时，DM-worker 向 DM-master 保持存活的周期，单位为秒。默认是 1800 秒。在版本 2.0.2 新增。 | -| `relay-dir` | 当绑定的上游数据源启用 relay log 时，DM-worker 将 relay log 保存在该路径下。该配置优先级比上游数据源配置更高。在版本 5.4.0 新增。 | -| `ssl-ca` | DM-worker 组件用于与其它组件连接的 SSL CA 证书所在的路径 | -| `ssl-cert` | DM-worker 组件用于与其它组件连接的 PEM 格式的 X509 证书所在的路径 | -| `ssl-key` | DM-worker 组件用于与其它组件连接的 PEM 格式的 X509 密钥所在的路径 | -| `cert-allowed-cn` | 证书检查 Common Name 列表 | +#### `name` + +- 标识一个 DM-worker。 + +#### `log-level` + +- 日志级别。 +- 默认值：`info` +- 可选值：`debug`、`info`、`warn`、`error`、`fatal` + +#### `log-file` + +- 日志文件。如果不配置，日志会输出到标准输出中。 + +#### `worker-addr` + +- DM-worker 服务的地址，可以省略 IP 信息，例如：`":8262"`。 + +#### `advertise-addr` + +- DM-worker 向外界宣告的地址。 + +#### `join` + +- 对应一个或多个 DM-master 配置中的 [`master-addr`](/dm/dm-master-configuration-file.md#global-配置)。 + +#### `keepalive-ttl` + +- 当绑定的上游数据源没有启用 relay log 时，DM-worker 向 DM-master 保持存活的周期。 +- 默认值：`60` +- 单位：秒 + +#### `relay-keepalive-ttl` 从 v2.0.2 版本开始引入 + +- 当绑定的上游数据源启用 relay log 时，DM-worker 向 DM-master 保持存活的周期。 +- 默认值：`1800` +- 单位：秒 + +#### `relay-dir` 从 v5.4.0 版本开始引入 + +- 当绑定的上游数据源启用 relay log 时，DM-worker 将 relay log 保存在该路径下。该配置优先级比上游数据源配置更高。 + +#### `ssl-ca` + +- DM-worker 组件用于与其它组件连接的 SSL CA 证书所在的路径。 + +#### `ssl-cert` + +- DM-worker 组件用于与其它组件连接的 PEM 格式的 X509 证书所在的路径。 + +#### `ssl-key` + +- DM-worker 组件用于与其它组件连接的 PEM 格式的 X509 密钥所在的路径。 + +#### `cert-allowed-cn` + +- 证书检查 Common Name 列表。 diff --git a/dm/dm-worker-intro.md b/dm/dm-worker-intro.md index 4e77bcb619f4..fb21d4377faa 100644 --- a/dm/dm-worker-intro.md +++ b/dm/dm-worker-intro.md @@ -1,6 +1,5 @@ --- title: DM-worker 简介 -aliases: ['/docs-cn/tidb-data-migration/dev/dm-worker-intro/'] summary: DM-worker 是 DM (Data Migration) 的一个组件，负责执行数据迁移任务。主要功能包括注册为 MySQL 或 MariaDB 服务器的 slave，读取 binlog event 并持久化保存在本地，支持迁移一个 MySQL 或 MariaDB 实例的数据到多个 TiDB 实例，以及支持迁移多个 MySQL 或 MariaDB 实例的数据到一个 TiDB 实例。处理单元包括 Relay log、dump、load 和 Binlog replication/sync。上游数据库用户需具有 SELECT、RELOAD、REPLICATION SLAVE 和 REPLICATION CLIENT 权限，下游数据库用户需具有 SELECT、INSERT、UPDATE、DELETE、CREATE、DROP 和 INDEX 权限。处理单元所需的最小权限根据具体情况可能会改变。 --- diff --git a/dm/dmctl-introduction.md b/dm/dmctl-introduction.md index b4cf8625ef1f..d318033482df 100644 --- a/dm/dmctl-introduction.md +++ b/dm/dmctl-introduction.md @@ -1,7 +1,6 @@ --- title: 使用 dmctl 运维 TiDB Data Migration 集群 summary: 了解如何使用 dmctl 运维 DM 集群。 -aliases: ['/docs-cn/tidb-data-migration/dev/dmctl-introduction/','/docs-cn/tidb-data-migration/dev/manage-replication-tasks/'] --- # 使用 dmctl 运维 TiDB Data Migration 集群 diff --git a/dm/feature-online-ddl.md b/dm/feature-online-ddl.md index 4b10969d4192..2a7ec7efcd3e 100644 --- a/dm/feature-online-ddl.md +++ b/dm/feature-online-ddl.md @@ -1,6 +1,5 @@ --- title: 迁移使用 GH-ost/PT-osc 的源数据库 -aliases: ['/docs-cn/tidb-data-migration/dev/feature-online-ddl-scheme/','/zh/tidb-data-migration/stable/feature-online-ddl-scheme'] summary: 使用 GH-ost/PT-osc 进行在线 DDL 工具执行 DDL 时，会产生锁表操作，阻塞数据库读写。为降低影响，可选择在线 DDL 工具 gh-ost 和 pt-osc。在 DM 迁移 MySQL 到 TiDB 时，可开启 `online-ddl` 配置，实现 DM 工具与 gh-ost 或 pt-osc 的协同。 DM 与 online DDL 工具协作细节包括 gh-ost 和 pt-osc 的实现过程，以及自定义规则配置。 --- diff --git a/dm/feature-shard-merge-optimistic.md b/dm/feature-shard-merge-optimistic.md index 17b9ca85e7b2..1ecd59cc6bfd 100644 --- a/dm/feature-shard-merge-optimistic.md +++ b/dm/feature-shard-merge-optimistic.md @@ -1,7 +1,6 @@ --- title: 乐观模式下分库分表合并迁移 summary: 介绍 DM 提供的乐观模式下分库分表的合并迁移功能。 -aliases: ['/docs-cn/tidb-data-migration/dev/feature-shard-merge-optimistic/'] --- # 乐观模式下分库分表合并迁移 diff --git a/dm/feature-shard-merge-pessimistic.md b/dm/feature-shard-merge-pessimistic.md index 87381a919821..aacb2ef1cf16 100644 --- a/dm/feature-shard-merge-pessimistic.md +++ b/dm/feature-shard-merge-pessimistic.md @@ -1,7 +1,6 @@ --- title: 悲观模式下分库分表合并迁移 summary: 介绍 DM 提供的悲观模式（默认模式）下分库分表的合并迁移功能。 -aliases: ['/docs-cn/tidb-data-migration/dev/feature-shard-merge-pessimistic/'] --- # 悲观模式下分库分表合并迁移 diff --git a/dm/feature-shard-merge.md b/dm/feature-shard-merge.md index f80752f5c983..f8ea12725836 100644 --- a/dm/feature-shard-merge.md +++ b/dm/feature-shard-merge.md @@ -1,6 +1,5 @@ --- title: 分库分表合并迁移 -aliases: ['/docs-cn/tidb-data-migration/dev/feature-shard-merge/'] summary: DM 提供了分库分表的合并迁移功能，可将上游 MySQL/MariaDB 实例中的表迁移到下游 TiDB 的同一个表中。支持悲观协调和乐观协调两种模式。悲观模式保证数据不出错，但可能会阻塞迁移；乐观模式处理 DDL 时不会阻塞数据迁移，但可能导致数据不一致。 --- diff --git a/dm/handle-failed-ddl-statements.md b/dm/handle-failed-ddl-statements.md index 6b6dac7f90ab..01e3a4f92b60 100644 --- a/dm/handle-failed-ddl-statements.md +++ b/dm/handle-failed-ddl-statements.md @@ -1,7 +1,6 @@ --- title: 使用 TiDB Data Migration 处理出错的 DDL 语句 summary: 了解在使用 TiDB Data Migration 迁移数据时，如何处理出错的 DDL 语句。 -aliases: ['/docs-cn/tidb-data-migration/dev/skip-or-replace-abnormal-sql-statements/'] --- # 使用 TiDB Data Migration 处理出错的 DDL 语句 diff --git a/dm/maintain-dm-using-tiup.md b/dm/maintain-dm-using-tiup.md index 422ce0e8ca1f..80d23707eb29 100644 --- a/dm/maintain-dm-using-tiup.md +++ b/dm/maintain-dm-using-tiup.md @@ -1,7 +1,6 @@ --- title: 使用 TiUP 运维 DM 集群 summary: 学习如何使用 TiUP 运维 DM 集群。 -aliases: ['/docs-cn/tidb-data-migration/dev/cluster-operations/'] --- # 使用 TiUP 运维 DM 集群 @@ -282,7 +281,7 @@ tiup dm patch prod-cluster /tmp/dm--hotfix.tar.gz -N 172.16.4.5:8261 > - `import` 命令用于将数据从 DM 1.0 集群导入到一个新的 DM 2.0 集群。如果你需要将 DM 迁移任务导入一个现有的 DM 2.0 集群，可以参考 [TiDB Data Migration 1.0.x 到 2.0+ 手动升级](/dm/manually-upgrade-dm-1.0-to-2.0.md)。 > - 导入集群某些组件的部署目录与原始集群的部署目录不同，可以执行 `display` 命令来查看相关信息。 > - 导入前，执行 `tiup update --self && tiup update dm`，以确保 DM 组件是最新版本。 -> - 导入后，集群中只存在一个 DM-master 节点。请参考[扩容节点](#扩容节点) 来扩展 DM-master。 +> - 导入后，集群中只存在一个 DM-master 节点。请参考[扩容节点](#扩容节点)来扩展 DM-master。 引入 TiUP 前，DM-Ansible 用于部署 DM 集群。要使 TiUP 接管由 DM-Ansible 部署的 DM 1.0 集群，需要执行 `import` 命令： @@ -394,7 +393,7 @@ tiup dmctl --master-addr master1:8261 operate-source create /tmp/source1.yml 此时可以通过命令行参数 `--native-ssh` 启用系统自带命令行： -- 部署集群：`tiup dm deploy --native-ssh`，其中 `` 为集群名称，`` 为 DM 集群版本（例如 `v8.4.0`），`` 为拓扑文件路径 +- 部署集群：`tiup dm deploy --native-ssh`，其中 `` 为集群名称，`` 为 DM 集群版本（例如 `v{{{ .tidb-version }}}`），`` 为拓扑文件路径 - 启动集群：`tiup dm start --native-ssh` - 升级集群：`tiup dm upgrade ... --native-ssh` diff --git a/dm/manually-handling-sharding-ddl-locks.md b/dm/manually-handling-sharding-ddl-locks.md index 453da69466bc..c9863751a748 100644 --- a/dm/manually-handling-sharding-ddl-locks.md +++ b/dm/manually-handling-sharding-ddl-locks.md @@ -1,6 +1,5 @@ --- title: 手动处理 Sharding DDL Lock -aliases: ['/docs-cn/tidb-data-migration/dev/manually-handling-sharding-ddl-locks/','/docs-cn/tidb-data-migration/dev/feature-manually-handling-sharding-ddl-locks/'] summary: DM 使用 sharding DDL lock 来确保分库分表的 DDL 操作可以正确执行。在异常情况下，需要手动处理异常的 DDL lock。使用 shard-ddl-lock 命令查看 DDL lock 信息，使用 shard-ddl-lock unlock 命令请求 DM-master 解除指定的 DDL lock。支持处理部分 MySQL source 被移除和 unlock 过程中部分 DM-worker 异常停止或网络中断的情况。 --- diff --git a/dm/manually-upgrade-dm-1.0-to-2.0.md b/dm/manually-upgrade-dm-1.0-to-2.0.md index c7056b8a8a90..56b641c52aec 100644 --- a/dm/manually-upgrade-dm-1.0-to-2.0.md +++ b/dm/manually-upgrade-dm-1.0-to-2.0.md @@ -1,7 +1,6 @@ --- title: TiDB Data Migration 1.0.x 到 2.0+ 手动升级 summary: 了解如何从 TiDB Data Migration 1.0.x 手动升级到 2.0+。 -aliases: ['/docs-cn/tidb-data-migration/dev/manually-upgrade-dm-1.0-to-2.0/'] --- # TiDB Data Migration 1.0.x 到 2.0+ 手动升级 diff --git a/dm/migrate-data-using-dm.md b/dm/migrate-data-using-dm.md index bb38bb6bb8e0..da275880f8f9 100644 --- a/dm/migrate-data-using-dm.md +++ b/dm/migrate-data-using-dm.md @@ -1,6 +1,5 @@ --- title: 使用 DM 迁移数据 -aliases: ['/docs-cn/tidb-data-migration/dev/replicate-data-using-dm/'] summary: 本文介绍如何使用 DM 工具迁移数据。首先部署 DM 集群，然后检查集群信息和创建数据源。配置任务后，启动任务并查询任务状态。最后，停止任务并监控任务与查看日志。 --- diff --git a/dm/monitor-a-dm-cluster.md b/dm/monitor-a-dm-cluster.md index 84e2a7159730..0ea7c3243e44 100644 --- a/dm/monitor-a-dm-cluster.md +++ b/dm/monitor-a-dm-cluster.md @@ -1,7 +1,6 @@ --- title: DM 监控指标 summary: 介绍 DM 的监控指标 -aliases: ['/docs-cn/tidb-data-migration/dev/monitor-a-dm-cluster/'] --- # DM 监控指标 diff --git a/dm/quick-start-create-task.md b/dm/quick-start-create-task.md index 6171d1053b39..a7cfc1a62cc6 100644 --- a/dm/quick-start-create-task.md +++ b/dm/quick-start-create-task.md @@ -1,7 +1,6 @@ --- title: 创建 TiDB Data Migration 数据迁移任务 summary: 了解在部署 DM 集群后，如何快速创建数据迁移任务。 -aliases: ['/docs-cn/tidb-data-migration/dev/quick-start-create-task/'] --- # 创建 TiDB Data Migration 数据迁移任务 @@ -69,7 +68,7 @@ docker run --rm --name mysql-3307 -p 3307:3307 -e MYSQL_ALLOW_EMPTY_PASSWORD=tru {{< copyable "shell-regular" >}} ```bash -wget https://download.pingcap.org/tidb-community-server-v8.4.0-linux-amd64.tar.gz +wget https://download.pingcap.com/tidb-community-server-v{{{ .tidb-version }}}-linux-amd64.tar.gz tar -xzvf tidb-latest-linux-amd64.tar.gz mv tidb-latest-linux-amd64/bin/tidb-server ./ ./tidb-server -P 4000 --store mocktikv --log-file "./tidb.log" & diff --git a/dm/quick-start-with-dm.md b/dm/quick-start-with-dm.md index 53664126d264..24894e1854ed 100644 --- a/dm/quick-start-with-dm.md +++ b/dm/quick-start-with-dm.md @@ -1,179 +1,475 @@ --- title: TiDB Data Migration 快速上手指南 -summary: 了解如何快速上手部署试用 TiDB Data Migration 工具。 -aliases: ['/docs-cn/tidb-data-migration/dev/quick-start-with-dm/','/docs-cn/tidb-data-migration/dev/get-started/'] +summary: 了解如何使用 TiUP Playground 快速部署试用 TiDB Data Migration 数据迁移工具。 --- # TiDB Data Migration 快速上手指南 -本文介绍如何快速体验使用数据迁移工具 [TiDB Data Migration (DM)](/dm/dm-overview.md) 从 MySQL 迁移数据到 TiDB。此文档用于快速体验 DM 产品功能特性，并不建议适合在生产环境中使用。 +[TiDB Data Migration (DM)](/dm/dm-overview.md) 是一个强大的数据迁移工具，用于将数据从兼容 MySQL 的数据库迁移到 TiDB。本指南介绍如何使用 [TiUP Playground](/tiup/tiup-playground.md) 在本地快速搭建用于开发或测试的 TiDB DM 环境，并完成一个将数据从源数据库 MySQL 迁移到目标数据库 TiDB 的简单任务。 -## 第 1 步：部署 DM 集群 +> **注意：** +> +> 对于生产环境部署，请参阅[使用 TiUP 部署 DM 集群](/dm/deploy-a-dm-cluster-using-tiup.md)。 -1. 安装 TiUP 工具并通过 TiUP 快速部署 [dmctl](/dm/dmctl-introduction.md)。 +## 第 1 步：搭建测试环境 - {{< copyable "shell-regular" >}} +[TiUP](/tiup/tiup-overview.md) 是一个集群运维工具。使用它的 Playground 可以快速启动一个用于开发和测试的临时本地环境，包含 TiDB 数据库和 TiDB DM。 + +1. 安装 TiUP： ```shell curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh - tiup install dm dmctl ``` -2. 生成 DM 集群最小拓扑文件。 + > **注意：** + > + > 如果你已经安装了 TiUP，请确保其版本为 v1.16.1 或之后版本，以便使用 `--dm-master` 和 `--dm-worker` 参数。如果要检查当前版本，执行以下命令： + > + > ```shell + > tiup --version + > ``` + > + > 如果要将 TiUP 升级到最新版本，执行以下命令： + > + > ```shell + > tiup update --self + > ``` - {{< copyable "shell-regular" >}} +2. 启动包含目标数据库 TiDB 和 DM 组件的 TiUP Playground： + ```shell + tiup playground v{{{ .tidb-version }}} --dm-master 1 --dm-worker 1 --tiflash 0 --without-monitor ``` - tiup dm template + +3. 验证环境，查看输出中 TiDB 和 DM 是否已启动： + + ```text + TiDB Playground Cluster is started, enjoy! + + Connect TiDB: mysql --host 127.0.0.1 --port 4000 -u root + Connect DM: tiup dmctl --master-addr 127.0.0.1:8261 + TiDB Dashboard: http://127.0.0.1:2379/dashboard ``` -3. 复制输出的配置信息，修改 IP 地址后保存为 `topology.yaml` 文件，使用 TiUP 部署 DM 集群。 +4. 保持 `tiup playground` 在当前终端中运行，并在新终端中执行后续步骤。 + + 这个 Playground 环境提供了目标 TiDB 数据库和数据复制引擎（DM-master 和 DM-worker）的运行进程。它将处理的数据流为：MySQL（源数据库）→ DM（数据复制引擎）→ TiDB（目标数据库）。 + +## 第 2 步：准备源数据库（可选） - {{< copyable "shell-regular" >}} +你可以使用一个或多个 MySQL 实例作为源数据库。如果你已经有一个兼容 MySQL 的实例，请跳到[第 3 步](#第-3-步配置-tidb-dm-源)；如果没有，则按照以下步骤创建一个用于测试的 MySQL 实例。 + + + +
+ +你可以使用 Docker 快速部署一个 MySQL 8.0 测试实例。 + +1. 运行 MySQL 8.0 Docker 容器： ```shell - tiup dm deploy dm-test 6.0.0 topology.yaml -p + docker run --name mysql80 \ + -e MYSQL_ROOT_PASSWORD=MyPassw0rd! \ + -p 3306:3306 \ + -d mysql:8.0 ``` -## 第 2 步：准备数据源 +2. 连接到 MySQL： -你可以使用一个或多个 MySQL 实例作为上游数据源。 + ```shell + docker exec -it mysql80 mysql -uroot -pMyPassw0rd! + ``` -1. 为每一个数据源编写如下配置文件： +3. 创建一个 DM 测试专用用户，并授予测试所需的权限： - {{< copyable "shell-regular" >}} + ```sql + CREATE USER 'tidb-dm'@'%' + IDENTIFIED WITH mysql_native_password + BY 'MyPassw0rd!'; - ```yaml - source-id: "mysql-01" + GRANT PROCESS, BACKUP_ADMIN, RELOAD, REPLICATION SLAVE, REPLICATION CLIENT, SELECT ON *.* TO 'tidb-dm'@'%'; + ``` - from: - host: "127.0.0.1" - user: "root" - password: "fCxfQ9XKCezSzuCD0Wf5dUD+LsKegSg=" - port: 3306 +4. 创建示例数据： + + ```sql + CREATE DATABASE hello; + USE hello; + + CREATE TABLE hello_tidb ( + id INT AUTO_INCREMENT PRIMARY KEY, + name VARCHAR(50) + ); + + INSERT INTO hello_tidb (name) VALUES ('Hello World'); + + SELECT * FROM hello_tidb; + ``` + +
+ +
+ +在 macOS 上，你可以使用 [Homebrew](https://brew.sh) 在本地快速安装和启动 MySQL 8.0。 + +1. 更新 Homebrew 并安装 MySQL 8.0： + + ```shell + brew update + brew install mysql@8.0 + ``` + +2. 将 MySQL 命令添加到系统路径中： + + ```shell + brew link mysql@8.0 --force + ``` + +3. 启动 MySQL 服务： + + ```shell + brew services start mysql@8.0 + ``` + +4. 以 `root` 用户连接到 MySQL： + + ```shell + mysql -uroot + ``` + +5. 创建一个 DM 测试专用用户，并授予必要的权限： + + ```sql + CREATE USER 'tidb-dm'@'%' + IDENTIFIED WITH mysql_native_password + BY 'MyPassw0rd!'; + + GRANT PROCESS, BACKUP_ADMIN, RELOAD, REPLICATION SLAVE, REPLICATION CLIENT, SELECT ON *.* TO 'tidb-dm'@'%'; ``` -2. 使用如下命令将数据源增加至 DM 集群。其中，`mysql-01.yaml` 是上一步编写的配置文件。 +6. 创建示例数据： + + ```sql + CREATE DATABASE hello; + USE hello; + + CREATE TABLE hello_tidb ( + id INT AUTO_INCREMENT PRIMARY KEY, + name VARCHAR(50) + ); - {{< copyable "shell-regular" >}} + INSERT INTO hello_tidb (name) VALUES ('Hello World'); - ```bash - tiup dmctl --master-addr=127.0.0.1:8261 operate-source create mysql-01.yaml # --master-addr 填写 master_servers 其中之一。 + SELECT * FROM hello_tidb; ``` -若环境中并不存在可供测试的 MySQL 实例，可以使用以下方式通过 Docker 快速创建一个测试实例。步骤如下： +
-1. 编写 MySQL 配置文件： +
- {{< copyable "shell-regular" >}} +在 CentOS 等企业级 Linux 发行版上，你可以从 MySQL Yum 仓库安装 MySQL 8.0。 + +1. 从 [MySQL Yum 仓库下载页面](https://dev.mysql.com/downloads/repo/yum)下载并安装 MySQL Yum 仓库包。对于非 Linux 9 版本，你需要将以下 URL 中的 `el9`（企业级 Linux 9 版本）替换为相应版本，同时保留 `mysql80` 以用于 MySQL 8.0 版本： ```shell - mkdir -p /tmp/mysqltest && cd /tmp/mysqltest + sudo yum install -y https://dev.mysql.com/get/mysql80-community-release-el9-1.noarch.rpm + ``` + +2. 安装 MySQL： - cat > my.cnf <}} +4. 在 MySQL 日志中找到临时 root 密码： ```shell - docker run --name mysql-01 -v /tmp/mysqltest:/etc/mysql/conf.d -e MYSQL_ROOT_PASSWORD=my-secret-pw -d -p 3306:3306 mysql:5.7 + sudo grep 'temporary password' /var/log/mysqld.log ``` -3. 待 MySQL 启动后，即可连接该实例。 +5. 使用临时密码以 `root` 用户连接到 MySQL： - > **注意：** - > - > 该命令仅适用于体验数据迁移过程，不能用于生产环境和压力测试。 + ```shell + mysql -uroot -p + ``` + +6. 重置 `root` 密码： + + ```sql + ALTER USER 'root'@'localhost' + IDENTIFIED BY 'MyPassw0rd!'; + ``` - {{< copyable "shell-regular" >}} +7. 创建一个 DM 测试专用用户，并授予测试所需的权限： + + ```sql + CREATE USER 'tidb-dm'@'%' + IDENTIFIED WITH mysql_native_password + BY 'MyPassw0rd!'; + + GRANT PROCESS, BACKUP_ADMIN, RELOAD, REPLICATION SLAVE, REPLICATION CLIENT, SELECT ON *.* TO 'tidb-dm'@'%'; + ``` + +8. 创建示例数据： + + ```sql + CREATE DATABASE hello; + USE hello; + + CREATE TABLE hello_tidb ( + id INT AUTO_INCREMENT PRIMARY KEY, + name VARCHAR(50) + ); + + INSERT INTO hello_tidb (name) VALUES ('Hello World'); + + SELECT * FROM hello_tidb; + ``` + +
+ +
+ +在 Ubuntu 上，你可以从官方 Ubuntu 仓库安装 MySQL。 + +1. 更新软件包列表： ```shell - mysql -uroot -p -h 127.0.0.1 -P 3306 + sudo apt-get update ``` -## 第 3 步：准备下游数据库 +2. 安装 MySQL： -可以选择已存在的 TiDB 集群作为数据同步目标。 + ```shell + sudo apt-get install -y mysql-server + ``` -如果没有可以用于测试的 TiDB 集群，则使用以下命令快速构建演示环境。 +3. 检查 `mysql` 服务是否在运行，必要时启动服务： -{{< copyable "shell-regular" >}} + ```shell + sudo systemctl status mysql + sudo systemctl start mysql + ``` -```shell -tiup playground -``` +4. 使用 socket 认证以 `root` 用户连接到 MySQL： -## 第 4 步：准备测试数据 + ```shell + sudo mysql + ``` -在一个或多个数据源中创建测试表和数据。如果你使用已存在的 MySQL 数据库，且数据库中已有可用数据，可跳过这一步。 +5. 创建一个 DM 测试专用用户，并授予测试所需的权限： -{{< copyable "sql" >}} + ```sql + CREATE USER 'tidb-dm'@'%' + IDENTIFIED WITH mysql_native_password + BY 'MyPassw0rd!'; -```sql -drop database if exists `testdm`; -create database `testdm`; -use `testdm`; -create table t1 (id bigint, uid int, name varchar(80), info varchar(100), primary key (`id`), unique key(`uid`)) DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin; -create table t2 (id bigint, uid int, name varchar(80), info varchar(100), primary key (`id`), unique key(`uid`)) DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin; -insert into t1 (id, uid, name) values (1, 10001, 'Gabriel García Márquez'), (2, 10002, 'Cien años de soledad'); -insert into t2 (id, uid, name) values (3, 20001, 'José Arcadio Buendía'), (4, 20002, 'Úrsula Iguarán'), (5, 20003, 'José Arcadio'); -``` + GRANT PROCESS, BACKUP_ADMIN, RELOAD, REPLICATION SLAVE, REPLICATION CLIENT, SELECT ON *.* TO 'tidb-dm'@'%'; + ``` -## 第 5 步：编写数据同步任务 +6. 创建示例数据： -1. 创建任务的配置文件 `testdm-task.yaml`： + ```sql + CREATE DATABASE hello; + USE hello; - {{< copyable "" >}} + CREATE TABLE hello_tidb ( + id INT AUTO_INCREMENT PRIMARY KEY, + name VARCHAR(50) + ); + + INSERT INTO hello_tidb (name) VALUES ('Hello World'); + + SELECT * FROM hello_tidb; + ``` + +
+ + + +## 第 3 步：配置 TiDB DM 源 + +准备好源 MySQL 数据库后，配置 TiDB DM 连接到它。为此，创建一个包含连接详细信息的源配置文件，并使用 `dmctl` 工具应用该配置。 + +1. 创建源配置文件 `mysql-01.yaml`： + + > **注意：** + > + > 这里假设你已经在源数据库中创建了具有数据复制权限的 `tidb-dm` 用户，如[第 2 步](#第-2-步准备源数据库可选)所述。 + + ```yaml + source-id: "mysql-01" + from: + host: "127.0.0.1" + user: "tidb-dm" + password: "MyPassw0rd!" # In production environments, it is recommended to use a password encrypted with dmctl. + port: 3306 + ``` + +2. 创建 DM 数据源： + + ```shell + tiup dmctl --master-addr 127.0.0.1:8261 operate-source create mysql-01.yaml + ``` + +## 第 4 步：创建 TiDB DM 任务 + +配置好源数据库后，在 TiDB DM 中创建一个迁移任务，指定 MySQL 实例作为数据源，并定义目标数据库 TiDB 的详细连接信息。 + +1. 创建 DM 任务配置文件 `tiup-playground-task.yaml`： ```yaml - name: testdm - task-mode: all + # Task + name: tiup-playground-task + task-mode: "all" # Execute all phases - full data migration and incremental sync. + # Source (MySQL) + mysql-instances: + - source-id: "mysql-01" + + ## Target (TiDB) target-database: host: "127.0.0.1" port: 4000 user: "root" - password: "" # 如果密码不为空，则推荐使用经过 dmctl 加密的密文 + password: "" # If the password is not empty, it is recommended to use a password encrypted with dmctl. + ``` - # 填写一个或多个所需同步的数据源信息 - mysql-instances: - - source-id: "mysql-01" - block-allow-list: "ba-rule1" +2. 使用配置文件启动任务： + + ```shell + tiup dmctl --master-addr 127.0.0.1:8261 start-task tiup-playground-task.yaml + ``` + +## 第 5 步：验证数据迁移 + +启动数据迁移任务后，验证数据复制是否符合预期。使用 `dmctl` 工具检查任务状态，并连接到目标数据库 TiDB，确认数据是否已成功从源数据库 MySQL 迁移到了目标数据库 TiDB。 - block-allow-list: - ba-rule1: - do-dbs: ["testdm"] +1. 检查 TiDB DM 任务的状态： + + ```shell + tiup dmctl --master-addr 127.0.0.1:8261 query-status ``` -2. 使用 dmctl 创建任务： +2. 连接到目标数据库 TiDB： + + ```shell + mysql --host 127.0.0.1 --port 4000 -u root --prompt 'tidb> ' + ``` - {{< copyable "shell-regular" >}} +3. 验证迁移的数据。如果在[第 2 步](#第-2-步准备源数据库可选)中创建了示例数据，你将看到从源数据库 MySQL 复制到目标数据库 TiDB 的 `hello_tidb` 表： - ```bash - tiup dmctl --master-addr 127.0.0.1:8261 start-task testdm-task.yaml + ```sql + SELECT * FROM hello.hello_tidb; ``` -这样就成功创建了一个将 `mysql-01` 数据源迁移到 TiDB 的任务。 + 输出如下： + + ```sql + +----+-------------+ + | id | name | + +----+-------------+ + | 1 | Hello World | + +----+-------------+ + 1 row in set (0.00 sec) + ``` + +## 第 6 步：清理环境（可选） + +测试完成后，可以清理环境，包括停止 TiUP Playground、删除 MySQL 实例数据源（如果是专为测试创建的），以及删除不必要的文件。 + +1. 停止 TiUP Playground： + + 在运行 TiUP Playground 的终端中，按 Control+C 终止进程。这将停止所有的 TiDB 和 DM 组件，并删除目标数据库环境。 -## 第 6 步：查看迁移任务状态 +2. 停止并删除数据源 MySQL 实例： + + 如果你在[第 2 步](#第-2-步准备源数据库可选)中为测试创建了 MySQL 实例作为数据源，可按以下步骤停止并删除它： + + + +
+ + 停止并删除 Docker 容器： + + ```shell + docker stop mysql80 + docker rm mysql80 + ``` + +
+ +
+ + 如果你使用 Homebrew 安装的 MySQL 8.0 仅用于测试，则停止服务并卸载： + + ```shell + brew services stop mysql@8.0 + brew uninstall mysql@8.0 + ``` + + > **注意：** + > + > 如果你要删除所有 MySQL 数据文件，则删除 MySQL 数据目录（通常位于 `/opt/homebrew/var/mysql`）。 + +
+ +
+ + 如果你从 MySQL Yum 仓库安装的 MySQL 8.0 仅用于测试，则停止服务并卸载： + + ```shell + sudo systemctl stop mysqld + sudo yum remove -y mysql-community-server + ``` + + > **注意：** + > + > 如果你要删除所有 MySQL 数据文件，则删除 MySQL 数据目录（通常位于 `/var/lib/mysql`）。 + +
+ +
+ + 如果你从官方 Ubuntu 仓库安装的 MySQL 仅用于测试，则停止服务并卸载： + + ```shell + sudo systemctl stop mysql + sudo apt-get remove --purge -y mysql-server + sudo apt-get autoremove -y + ``` + + > **注意：** + > + > 如果你要删除所有 MySQL 数据文件，则删除 MySQL 数据目录（通常位于 `/var/lib/mysql`）。 + +
+ + + +3. 如果不再需要 TiDB DM 配置文件，则删除： + + ```shell + rm mysql-01.yaml tiup-playground-task.yaml + ``` + +4. 如果不再需要 TiUP，则卸载： + + ```shell + rm -rf ~/.tiup + ``` -在创建迁移任务之后，可以用 `dmctl query-status` 来查看任务的状态。 +## 探索更多 -{{< copyable "shell-regular" >}} +现在，你已经成功在测试环境中完成了一个从源数据库 MySQL 迁移数据到目标数据库 TiDB 的任务，接下来可以： -```bash -tiup dmctl --master-addr 127.0.0.1:8261 query-status testdm -``` +- 探索 [TiDB DM 的特性](/dm/dm-overview.md) +- 了解 [TiDB DM 的架构](/dm/dm-arch.md) +- [在生产环境中部署 TiDB DM 集群](/dm/deploy-a-dm-cluster-using-tiup.md) +- 了解 [TiDB DM 数据迁移任务的高级配置](/dm/dm-task-configuration-guide.md) diff --git a/dm/relay-log.md b/dm/relay-log.md index 8f6f67868f8b..8f43046ec08b 100644 --- a/dm/relay-log.md +++ b/dm/relay-log.md @@ -1,7 +1,6 @@ --- title: DM Relay Log summary: 了解目录结构、初始迁移规则和 DM relay log 的数据清理。 -aliases: ['/docs-cn/tidb-data-migration/dev/relay-log/'] --- # DM Relay Log @@ -405,4 +404,4 @@ Relay log 本地存储的目录结构示例如下： ## 探索更多 -- [DM 源码阅读系列文章（六）relay log 的实现丨TiDB 工具](https://pingcap.com/zh/blog/dm-source-code-reading-6) \ No newline at end of file +- [DM 源码阅读系列文章（六）relay log 的实现丨TiDB 工具](https://tidb.net/blog/4570243f) \ No newline at end of file diff --git a/dm/shard-merge-best-practices.md b/dm/shard-merge-best-practices.md index 1240387b8e91..7ee7b1174f96 100644 --- a/dm/shard-merge-best-practices.md +++ b/dm/shard-merge-best-practices.md @@ -1,7 +1,6 @@ --- title: 分表合并数据迁移最佳实践 summary: 使用 DM 对分库分表进行合并迁移时的最佳实践。 -aliases: ['/docs-cn/tidb-data-migration/dev/shard-merge-best-practices/'] --- # 分表合并数据迁移最佳实践 diff --git a/dm/table-selector.md b/dm/table-selector.md index a539ba6f49fc..021dd0011e06 100644 --- a/dm/table-selector.md +++ b/dm/table-selector.md @@ -1,12 +1,11 @@ --- title: DM Table Selector summary: 介绍 DM 的 Table Selector -aliases: ['/docs-cn/tidb-data-migration/dev/table-selector/'] --- # DM Table Selector -Table Selector 提供了一种基于[通配符](https://zh.wikipedia.org/wiki/%E9%80%9A%E9%85%8D%E7%AC%A6) 来匹配指定 `schema/table` 的功能。 +Table Selector 提供了一种基于[通配符](https://zh.wikipedia.org/wiki/%E9%80%9A%E9%85%8D%E7%AC%A6)来匹配指定 `schema/table` 的功能。 ## 通配符 diff --git a/dm/task-configuration-file-full.md b/dm/task-configuration-file-full.md index 0f41413a7a16..b44cefdb783e 100644 --- a/dm/task-configuration-file-full.md +++ b/dm/task-configuration-file-full.md @@ -1,12 +1,11 @@ --- title: DM 任务完整配置文件介绍 -aliases: ['/docs-cn/tidb-data-migration/dev/task-configuration-file-full/','/docs-cn/tidb-data-migration/dev/dm-portal/','/zh/tidb/dev/task-configuration-file'] summary: 本文介绍了 Data Migration (DM) 的任务完整配置文件，包括全局配置和实例配置两部分。全局配置包括任务基本信息配置和功能配置集，功能配置集包括路由规则、过滤规则、block-allow-list、mydumpers、loaders 和 syncers。实例配置定义了具体的数据迁移子任务，包括路由规则、过滤规则、block-allow-list、mydumpers、loaders 和 syncers 的配置名称。 --- # DM 任务完整配置文件介绍 -本文档主要介绍 Data Migration (DM) 的任务完整的配置文件，包含[全局配置](#全局配置) 和[实例配置](#实例配置) 两部分。 +本文档主要介绍 Data Migration (DM) 的任务完整的配置文件，包含[全局配置](#全局配置)和[实例配置](#实例配置)两部分。 ## 关键概念 @@ -111,7 +110,7 @@ mydumpers: # dump 处理单元的运行配置参数 global: # 配置名称 threads: 4 # dump 处理单元从上游数据库实例导出数据和 check-task 访问上游的线程数量，默认值为 4 chunk-filesize: 64 # dump 处理单元生成的数据文件大小，默认值为 64，单位为 MB - extra-args: "--consistency none" # dump 处理单元的其他参数，不需要在 extra-args 中配置 table-list，DM 会自动生成 + extra-args: "--consistency auto" # dump 处理单元的其他参数，不需要在 extra-args 中配置 table-list，DM 会自动生成 loaders: # load 处理单元的运行配置参数 global: # 配置名称 @@ -248,14 +247,29 @@ mysql-instances: 全局配置主要包含下列功能配置集： -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `routes` | 上游和下游表之间的路由 table routing 规则集。如果上游与下游的库名、表名一致，则不需要配置该项。使用场景及示例配置参见 [Table Routing](/dm/dm-table-routing.md) | -| `filters` | 上游数据库实例匹配的表的 binlog event filter 规则集。如果不需要对 binlog 进行过滤，则不需要配置该项。使用场景及示例配置参见 [Binlog Event Filter](/dm/dm-binlog-event-filter.md) | -| `block-allow-list` | 该上游数据库实例匹配的表的 block & allow lists 过滤规则集。建议通过该项指定需要迁移的库和表，否则会迁移所有的库和表。使用场景及示例配置参见 [Block & Allow Lists](/dm/dm-block-allow-table-lists.md) | -| `mydumpers` | dump 处理单元的运行配置参数。如果默认配置可以满足需求，则不需要配置该项，也可以只使用 `mydumper-thread` 对 `thread` 配置项单独进行配置。 | -| `loaders` | load 处理单元的运行配置参数。如果默认配置可以满足需求，则不需要配置该项，也可以只使用 `loader-thread` 对 `pool-size` 配置项单独进行配置。 | -| `syncers` | sync 处理单元的运行配置参数。如果默认配置可以满足需求，则不需要配置该项，也可以只使用 `syncer-thread` 对 `worker-count` 配置项单独进行配置。 | +#### `routes` + +- 上游和下游表之间的路由 table routing 规则集。如果上游与下游的库名、表名一致，则不需要配置该项。使用场景及示例配置参见 [Table Routing](/dm/dm-table-routing.md)。 + +#### `filters` + +- 上游数据库实例匹配的表的 binlog event filter 规则集。如果不需要对 binlog 进行过滤，则不需要配置该项。使用场景及示例配置参见 [Binlog Event Filter](/dm/dm-binlog-event-filter.md)。 + +#### `block-allow-list` + +- 该上游数据库实例匹配的表的 block & allow lists 过滤规则集。建议通过该项指定需要迁移的库和表，否则会迁移所有的库和表。使用场景及示例配置参见 [Block & Allow Lists](/dm/dm-block-allow-table-lists.md)。 + +#### `mydumpers` + +- dump 处理单元的运行配置参数。如果默认配置可以满足需求，则不需要配置该项，也可以只使用 `mydumper-thread` 对 `thread` 配置项单独进行配置。 + +#### `loaders` + +- load 处理单元的运行配置参数。如果默认配置可以满足需求，则不需要配置该项，也可以只使用 `loader-thread` 对 `pool-size` 配置项单独进行配置。 + +#### `syncers` + +- sync 处理单元的运行配置参数。如果默认配置可以满足需求，则不需要配置该项，也可以只使用 `syncer-thread` 对 `worker-count` 配置项单独进行配置。 各个功能配置集的参数及解释参见[完整配置文件示例](#完整配置文件示例)中的注释说明。 diff --git a/dm/usage-scenario-master-slave-switch.md b/dm/usage-scenario-master-slave-switch.md index 147c8bec3811..46b979516a53 100644 --- a/dm/usage-scenario-master-slave-switch.md +++ b/dm/usage-scenario-master-slave-switch.md @@ -1,7 +1,6 @@ --- title: 切换 DM-worker 与上游 MySQL 实例的连接 summary: 了解如何切换 DM-worker 与上游 MySQL 实例的连接。 -aliases: ['/docs-cn/tidb-data-migration/dev/usage-scenario-master-slave-switch/'] --- # 切换 DM-worker 与上游 MySQL 实例的连接 diff --git a/download-ecosystem-tools.md b/download-ecosystem-tools.md index f68f873ffb87..6f08bbe791c7 100644 --- a/download-ecosystem-tools.md +++ b/download-ecosystem-tools.md @@ -1,6 +1,5 @@ --- title: TiDB 工具下载 -aliases: ['/docs-cn/dev/download-ecosystem-tools/','/docs-cn/dev/reference/tools/download/'] summary: 本文介绍如何下载 TiDB 工具包。TiDB 工具包包含常用工具如 Dumpling、TiDB Lightning、BR 等。如果部署环境能访问互联网，可直接通过 TiUP 命令一键部署所需的 TiDB 工具。操作系统需为 Linux，架构为 amd64 或 arm64。下载步骤包括访问 TiDB 社区版页面，找到 TiDB-community-toolkit 软件包并点击立即下载。注意，点击立即下载后默认下载当前 TiDB 的最新发布版本。根据要使用的工具选择安装对应的离线包。 --- @@ -23,12 +22,11 @@ TiDB 工具包中包含了一些常用的 TiDB 工具，例如数据导出工具 ### 下载步骤 -1. 访问 [TiDB 社区版](https://pingcap.com/zh/product-community/)页面。 -2. 找到 **TiDB-community-toolkit 软件包**，点击**立即下载**。 +1. 访问[软件下载中心](https://pingkai.cn/download#tidb-community)页面。 +2. 选择你所需的 TiDB 版本和架构，选择 **TiDB 工具集 TiDB-community-toolkit**，确认隐私政策，然后点击**立即下载**。 > **注意：** > -> - 点击**立即下载**后，默认下载当前 TiDB 的最新发布版本。如需下载其它版本，请在 [TiDB 社区版](https://pingcap.com/zh/product-community/)页面底部查看其它版本下载信息。 > - 如需在 Kubernetes 上部署运维 TiDB，无需下载 TiDB-community-toolkit 软件包，请参考[离线安装 TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/deploy-tidb-operator#离线安装-tidb-operator)。 > - 如需使用 [PD Control](/pd-control.md) 工具 `pd-ctl`，请下载 **TiDB-community-server 软件包**。 diff --git a/dr-secondary-cluster.md b/dr-secondary-cluster.md index 7f7c5a41efec..d25c6aefabb5 100644 --- a/dr-secondary-cluster.md +++ b/dr-secondary-cluster.md @@ -57,7 +57,7 @@ summary: 了解如何使用 TiCDC 构建主备集群进行容灾。 关于服务器配置信息，可以参考如下文档： -- [TiDB 软件和硬件环境建议配置](/hardware-and-software-requirements.md) +- [TiDB 软件和硬件环境需求](/hardware-and-software-requirements.md) - [TiCDC 软件和硬件环境推荐配置](/ticdc/deploy-ticdc.md#软件和硬件环境推荐配置) 部署 TiDB 主集群和备用集群的详细过程，可以参考[部署 TiDB 集群](/production-deployment-using-tiup.md)。 diff --git a/dr-solution-introduction.md b/dr-solution-introduction.md index ecdc783489d4..658464a79ecc 100644 --- a/dr-solution-introduction.md +++ b/dr-solution-introduction.md @@ -93,7 +93,7 @@ BR 作为 TiDB 的备份恢复工具，可以对 TiDB 集群进行基于时间 按照上面的部署，TiDB Cluster1 部署在区域 1 (Region 1)，BR 工具定期将集群的数据备份到区域 2 (Region 2)，并且持续将数据改变日志也备份到区域 2。当区域 1 出现灾难导致 Cluster1 无法恢复时，你可以使用备份的数据和数据改变在区域 2 恢复新的集群 Cluster2 对外提供服务。 -基于备份恢复的容灾方案，目前，RPO 低于 5 分钟，而 RTO 则取决于需要恢复的集群数据大小，对于 v6.5.0 版本的 BR，其恢复速度可以参考[快照恢复的性能与影响](/br/br-snapshot-guide.md#快照恢复的性能与影响)和 [PITR 的性能指标](/br//br-pitr-guide.md#pitr-的性能指标)。通常来说，大部分客户会把跨区域 的备份作为数据安全的最后一道防线，是大多数系统都需要的。对于该方案的详细信息，请参考[基于备份与恢复的容灾方案](/dr-backup-restore.md)。 +基于备份恢复的容灾方案，目前，RPO 低于 5 分钟，而 RTO 则取决于需要恢复的集群数据大小，对于 v6.5.0 版本的 BR，其恢复速度可以参考[快照恢复的性能与影响](/br/br-snapshot-guide.md#快照恢复的性能与影响)和 [PITR 的性能指标](/br/br-pitr-guide.md#pitr-的性能指标)。通常来说，大部分客户会把跨区域的备份作为数据安全的最后一道防线，是大多数系统都需要的。对于该方案的详细信息，请参考[基于备份与恢复的容灾方案](/dr-backup-restore.md)。 另外，从 v6.5.0 开始，BR 支持[基于 AWS 上的 EBS 快照的快速恢复](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/restore-from-aws-s3-by-snapshot)。如果你在 AWS 上运行 TiDB 集群，要求备份过程对集群没有任何影响，并且要求恢复的时间尽量短，可以考虑使用该特性来降低系统的 RTO。 diff --git a/dumpling-overview.md b/dumpling-overview.md index f4ba4a2f4057..0008d77a24a1 100644 --- a/dumpling-overview.md +++ b/dumpling-overview.md @@ -1,16 +1,15 @@ --- title: 使用 Dumpling 导出数据 summary: 使用 Dumpling 从 TiDB 导出数据。 -aliases: ['/docs-cn/dev/dumpling-overview/','/docs-cn/dev/mydumper-overview/','/docs-cn/dev/reference/tools/mydumper/','/zh/tidb/dev/mydumper-overview/'] --- # 使用 Dumpling 导出数据 -使用数据导出工具 [Dumpling](https://github.com/pingcap/tidb/tree/master/dumpling)，你可以把存储在 TiDB 或 MySQL 中的数据导出为 SQL 或 CSV 格式，用于逻辑全量备份。Dumpling 也支持将数据导出到 Amazon S3 中。 +使用数据导出工具 [Dumpling](https://github.com/pingcap/tidb/tree/release-8.5/dumpling)，你可以把存储在 TiDB 或 MySQL 中的数据导出为 SQL 或 CSV 格式，用于逻辑全量备份。Dumpling 也支持将数据导出到 Amazon S3 中。 要快速了解 Dumpling 的基本功能，建议先观看下面的培训视频（时长 28 分钟）。注意本视频只作为功能介绍、学习参考，具体操作步骤和最新功能，请以文档内容为准。 - + 你可以通过下列任意方式获取 Dumpling： @@ -29,7 +28,7 @@ TiDB 还提供了其他工具，你可以根据需要选择使用： > **注意：** > -> PingCAP 之前维护的 Mydumper 工具 fork 自 [mydumper project](https://github.com/maxbube/mydumper)，针对 TiDB 的特性进行了优化。从 v7.5.0 开始，[Mydumper](https://docs.pingcap.com/tidb/v4.0/mydumper-overview) 废弃，其绝大部分功能已经被 [Dumpling](/dumpling-overview.md) 取代，强烈建议切换到 Dumpling。 +> PingCAP 之前维护的 Mydumper 工具 fork 自 [mydumper project](https://github.com/maxbube/mydumper)，针对 TiDB 的特性进行了优化。从 v7.5.0 开始，[Mydumper](https://docs-archive.pingcap.com/tidb/v4.0/mydumper-overview) 废弃，其绝大部分功能已经被 [Dumpling](/dumpling-overview.md) 取代，强烈建议切换到 Dumpling。 Dumpling 具有以下优势： @@ -57,9 +56,10 @@ Dumpling 具有以下优势： - PROCESS：需要该权限用于查询集群信息以获取 PD 地址，从而通过 PD 控制 GC。 - SELECT：导出目标表时需要。 -- RELOAD：使用 consistency flush 时需要。注意，只有 TiDB 支持该权限，当上游为 RDS 或采用托管服务时，可忽略该权限。 -- LOCK TABLES：使用 consistency lock 时需要，需要导出的库表都有该权限。 +- RELOAD：`consistency` 级别为 `flush` 时需要，当上游为 RDS 或采用托管服务时，可忽略该权限。 +- LOCK TABLES：`consistency` 级别为 `lock` 时需要，需要导出的库表都有该权限。 - REPLICATION CLIENT：导出 metadata 记录数据快照点时需要，可选，如果不需要导出 metadata，可忽略该权限。 +- SHOW VIEW：需要该权限收集用于导出的视图元数据。 ### 导出为 SQL 文件 @@ -78,7 +78,11 @@ tiup dumpling -u root -P 4000 -h 127.0.0.1 --filetype sql -t 8 -o /tmp/test -r 2 - `-h`、`-P`、`-u` 分别代表地址、端口、用户。如果需要密码验证，可以使用 `-p $YOUR_SECRET_PASSWORD` 将密码传给 Dumpling。 - `-o`（或 `--output`）用于选择存储导出文件的目录，支持本地文件的绝对路径或[外部存储服务的 URI 格式](#存储服务的-uri-格式说明)。 - `-t` 用于指定导出的线程数。增加线程数会增加 Dumpling 并发度提高导出速度，但也会加大数据库内存消耗，因此不宜设置过大。一般不超过 64。 -- `-r` 用于开启表内并发加速导出。默认值是 `0`，表示不开启。取值大于 0 表示开启，取值是 INT 类型。当数据源为 TiDB 时，设置 `-r` 参数大于 0 表示使用 TiDB region 信息划分区间，同时减少内存使用。具体取值不影响划分算法。对数据源为 MySQL 且表的主键是 INT 的场景，该参数也有表内并发效果。 +- `-r` 选项用于开启表内并发以加速导出，默认关闭（默认值为 `0`）。当设置为大于 `0` 时，不同数据库的行为如下： + + - 对于 TiDB，Dumpling 会根据 Region 信息进行分割，同时减少内存使用，`-r` 的具体数值不会影响分割算法。 + - 对于 MySQL，当主键（或复合主键的首列）为 `INT` 或 `STRING` 类型时，该选项也支持表内并发。 + - `-F` 选项用于指定单个文件的最大大小，单位为 `MiB`，可接受类似 `5GiB` 或 `8KB` 的输入。如果你想使用 TiDB Lightning 将该文件加载到 TiDB 实例中，建议将 `-F` 选项的值保持在 256 MiB 或以下。 > **注意：** @@ -258,7 +262,7 @@ Dumpling 也可以通过 `-B` 或 `-T` 选项导出特定的数据库/数据表 默认情况下，导出的文件会存储到 `./export-` 目录下。常用选项如下： - `-t` 用于指定导出的线程数。增加线程数会增加 Dumpling 并发度提高导出速度，但也会加大数据库内存消耗，因此不宜设置过大。 -- `-r` 选项用于指定单个文件的最大记录数，或者说，数据库中的行数。开启后 Dumpling 会开启表内并发，提高导出大表的速度。当上游为 TiDB 且版本为 v3.0 或更新版本时，设置 `-r` 参数大于 0 表示使用 TiDB region 信息划分表内并发，具体取值不影响划分算法。对上游为 MySQL 且表的主键是 int 的场景，该参数也有表内并发效果。 +- `-r` 选项用于指定单个文件的最大记录数，或者说，数据库中的行数。开启后 Dumpling 会开启表内并发，提高导出大表的速度。当上游为 TiDB 且版本为 v3.0 或更新版本时，设置 `-r` 参数大于 0 表示使用 TiDB region 信息划分表内并发，具体取值不影响划分算法。对上游为 MySQL 且表的主键或复合主键首列是 INT 的场景，该参数也有表内并发效果。 - `--compress ` 选项可以用于压缩导出的数据，支持 `gzip`、`snappy`、`zstd` 压缩算法。压缩可以显著降低导出数据的大小，同时如果存储的写入 I/O 带宽不足，可以使用该选项来加速导出。但该选项也有副作用，由于该选项会对每个文件单独压缩，因此会增加 CPU 消耗。 利用以上选项可以提高 Dumpling 的导出速度。 @@ -271,7 +275,7 @@ Dumpling 也可以通过 `-B` 或 `-T` 选项导出特定的数据库/数据表 Dumpling 通过 `--consistency ` 标志控制导出数据“一致性保证”的方式。在使用 snapshot 来保证一致性的时候，可以使用 `--snapshot` 选项指定要备份的时间戳。还可以使用以下的一致性级别： -- `flush`：使用 [`FLUSH TABLES WITH READ LOCK`](https://dev.mysql.com/doc/refman/8.0/en/flush.html#flush-tables-with-read-lock) 短暂地中断备份库的 DML 和 DDL 操作、保证备份连接的全局一致性和记录 POS 信息。所有的备份连接启动事务后释放该锁。推荐在业务低峰或者 MySQL 备份库上进行全量备份。 +- `flush`：使用 [`FLUSH TABLES WITH READ LOCK`](https://dev.mysql.com/doc/refman/8.0/en/flush.html#flush-tables-with-read-lock) 短暂地中断备份库的 DML 和 DDL 操作、保证备份连接的全局一致性和记录 POS 信息。所有的备份连接启动事务后释放该锁。推荐在业务低峰或者 MySQL 备份库上进行全量备份。注意 TiDB 不支持该值。 - `snapshot`：获取指定时间戳的一致性快照并导出。 - `lock`：为待导出的所有表上读锁。 - `none`：不做任何一致性保证。 @@ -349,7 +353,7 @@ SET GLOBAL tidb_gc_life_time = '10m'; | --case-sensitive | table-filter 是否大小写敏感 | false，大小写不敏感 | | -h 或 --host| 连接的数据库主机的地址 | "127.0.0.1" | | -t 或 --threads | 备份并发线程数| 4 | -| -r 或 --rows | 用于开启表内并发加速导出。默认值是 `0`，表示不开启。取值大于 0 表示开启，取值是 INT 类型。当数据源为 TiDB 时，设置 `-r` 参数大于 0 表示使用 TiDB region 信息划分区间，同时减少内存使用。具体取值不影响划分算法。对数据源为 MySQL 且表的主键是 INT 的场景，该参数也有表内并发效果。 | +| -r 或 --rows | 用于开启表内并发加速导出。默认值是 `0`，表示不开启。取值大于 0 表示开启，取值是 INT 类型。当数据源为 TiDB 时，设置 `-r` 参数大于 0 表示使用 TiDB region 信息划分区间，同时减少内存使用。具体取值不影响划分算法。对数据源为 MySQL 且表的主键或复合主键首列是 INT 的场景，该参数也有表内并发效果。 | | -L 或 --logfile | 日志输出地址，为空时会输出到控制台 | "" | | --loglevel | 日志级别 {debug,info,warn,error,dpanic,panic,fatal} | "info" | | --logfmt | 日志输出格式 {text,json} | "text" | @@ -373,7 +377,7 @@ SET GLOBAL tidb_gc_life_time = '10m'; | --cert | 用于 TLS 连接的 client certificate 文件的地址 | | --key | 用于 TLS 连接的 client private key 文件的地址 | | --csv-delimiter | CSV 文件中字符类型变量的定界符 | '"' | -| --csv-separator | CSV 文件中各值的分隔符，如果数据中可能有逗号，建议源文件导出时分隔符使用非常见组合字符| ','| +| --csv-separator | CSV 文件中各值的分隔符。如果数据中包含逗号，建议导出源文件时，使用非常见组合字符作为分隔符。支持不可见字符作为分隔符，如：`--csv-separator $'\001'` | ','| | --csv-null-value | CSV 文件空值的表示 | "\\N" | | --csv-line-terminator | CSV 文件中表示行尾的换行符。将数据导出为 CSV 文件时，可以通过该选项传入所需的换行符。该选项支持 "\\r\\n" 和 "\\n"，默认值为 "\\r\\n"，和历史版本保持一致。由于 bash 中不同的引号会应用不同的转义规则，如需指定 LF 为换行符，可使用类似 `--csv-line-terminator $'\n'` 的语法。| "\\r\\n" | | --csv-output-dialect | 表示可以将源数据导出成数据库所需的格式存储到 CSV。该选项取值可为 `""`，`"snowflake"`、`"redshift"`、`"bigquery"`。默认值为 `""`，表示会按 UTF-8 进行编码并导出数据。如果设置为 `"snowflake"` 或 `"redshift"`，会把 Binary 数据类型转换成十六进制，但会丢失十六进制数的前缀 `0x`，例如 `0x61` 将被表示成 `61`。如果设置为 `"bigquery"`，会使用 base64 对 Binary 数据类型进行编码。在某些情况下，Binary 字符串会出现乱码。| `""` | @@ -383,3 +387,38 @@ SET GLOBAL tidb_gc_life_time = '10m'; | --tidb-mem-quota-query | 单条 dumpling 命令导出 SQL 语句的内存限制，单位为 byte。对于 v4.0.10 或以上版本，若不设置该参数，默认使用 TiDB 中的 `mem-quota-query` 配置项值作为内存限制值。对于 v4.0.10 以下版本，该参数值默认为 32 GB | 34359738368 | | --params | 为需导出的数据库连接指定 session 变量，可接受的格式: "character_set_client=latin1,character_set_connection=latin1" | | -c 或 --compress | 压缩 Dumpling 导出的 CSV、SQL 数据与表结构文件为指定格式，支持 "gzip"、"snappy" 和 "zstd" 压缩算法 | "" | + +## 输出文件名模板 + +`--output-filename-template` 参数用于定义输出文件的命名规则，不包括文件扩展名。它接受符合 [Go `text/template` 语法](https://golang.org/pkg/text/template/)的字符串。 + +模板中可定义的字段如下： + +* `.DB`：数据库名 +* `.Table`：表名或对象名 +* `.Index`：当一个表被拆分成多个文件时的 0 起始序号，表示正在导出的是哪一部分。例如，`{{printf "%09d" .Index}}` 表示使用 9 位数字格式化 `.Index`，并用前导 0 填充。 + +数据库名和表名可能包含一些在文件系统中不允许使用的特殊字符，如 `/`。为了解决此问题，Dumpling 提供了 `fn` 函数来对这些特殊字符进行百分号编码： + +* U+0000 到 U+001F（控制字符） +* `/`、`\`、`<`、`>`、`:`、`"`、`*`、`?`（无效的 Windows 路径字符） +* `.`（数据库名或表名分隔符） +* `-schema` 中的 `-` + +例如，使用 `--output-filename-template '{{fn .Table}}.{{printf "%09d" .Index}}'`，Dumpling 会将表 `db.tbl:normal` 写入 `tbl%3Anormal.000000000.sql`、`tbl%3Anormal.000000001.sql` 等文件中。 + +除了输出的数据文件名，你还可以通过 `--output-filename-template` 来替换 schema 文件的文件名。下表显示了默认配置。 + +| 名称 | 内容 | +|------|---------| +| data | `{{fn .DB}}.{{fn .Table}}.{{.Index}}` | +| schema | `{{fn .DB}}-schema-create` | +| table | `{{fn .DB}}.{{fn .Table}}-schema` | +| event | `{{fn .DB}}.{{fn .Table}}-schema-post` | +| function | `{{fn .DB}}.{{fn .Table}}-schema-post` | +| procedure | `{{fn .DB}}.{{fn .Table}}-schema-post` | +| sequence | `{{fn .DB}}.{{fn .Table}}-schema-sequence` | +| trigger | `{{fn .DB}}.{{fn .Table}}-schema-triggers` | +| view | `{{fn .DB}}.{{fn .Table}}-schema-view` | + +例如，使用 `--output-filename-template '{{define "table"}}{{fn .Table}}.$schema{{end}}{{define "data"}}{{fn .Table}}.{{printf "%09d" .Index}}{{end}}'`，Dumpling 会将表 `db.tbl:normal` 的 schema 写入名为 `tbl%3Anormal.$schema.sql` 的文件中，将数据写入 `tbl%3Anormal.000000000.sql`、`tbl%3Anormal.000000001.sql` 等文件中。 diff --git a/dynamic-config.md b/dynamic-config.md index e1d942d036bc..5b641fb3e3e0 100644 --- a/dynamic-config.md +++ b/dynamic-config.md @@ -1,7 +1,6 @@ --- title: 在线修改集群配置 summary: 介绍在线修改集群配置的功能。 -aliases: ['/docs-cn/dev/dynamic-config/'] --- # 在线修改集群配置 @@ -87,7 +86,7 @@ Query OK, 0 rows affected (0.01 sec) {{< copyable "sql" >}} ```sql -set config tikv `log-level`='warn'; +set config tikv `log-level`='warn'; -- This command fails because `log-level` is incorrect. Use `log.level` instead. ``` ```sql @@ -131,10 +130,6 @@ show warnings; | raftstore.max-apply-unpersisted-log-limit | 允许 apply 已 commit 但尚未持久化的 Raft 日志的最大数量 | | raftstore.split-region-check-tick-interval | 检查 Region 是否需要分裂的时间间隔 | | raftstore.region-split-check-diff | 允许 Region 数据超过指定大小的最大值 | -| raftstore.region-compact-check-interval | 检查是否需要人工触发 RocksDB compaction 的时间间隔 | -| raftstore.region-compact-check-step | 每轮校验人工 compaction 时，一次性检查的 Region 个数 | -| raftstore.region-compact-min-tombstones | 触发 RocksDB compaction 需要的 tombstone 个数 | -| raftstore.region-compact-tombstones-percent | 触发 RocksDB compaction 需要的 tombstone 所占比例 | | raftstore.pd-heartbeat-tick-interval | 触发 Region 对 PD 心跳的时间间隔 | | raftstore.pd-store-heartbeat-tick-interval | 触发 store 对 PD 心跳的时间间隔 | | raftstore.snap-mgr-gc-tick-interval | 触发回收过期 snapshot 文件的时间间隔 | @@ -179,8 +174,8 @@ show warnings; | quota.foreground-write-bandwidth | 限制前台事务写入的带宽，软限制 | | quota.foreground-read-bandwidth | 限制前台事务读取数据和 Coprocessor 读取数据的带宽，软限制 | | quota.background-cpu-time | 限制处理 TiKV 后台读写请求所使用的 CPU 资源使用量，软限制 | -| quota.background-write-bandwidth | 限制后台事务写入的带宽，软限制，暂未生效 | -| quota.background-read-bandwidth | 限制后台事务读取数据和 Coprocessor 读取数据的带宽，软限制，暂未生效 | +| quota.background-write-bandwidth | 限制后台事务写入的带宽，软限制 | +| quota.background-read-bandwidth | 限制后台事务读取数据和 Coprocessor 读取数据的带宽，软限制 | | quota.enable-auto-tune | 是否支持 quota 动态调整。如果打开该配置项，TiKV 会根据 TiKV 实例的负载情况动态调整对后台请求的限制 quota | | quota.max-delay-duration | 单次读写请求被强制等待的最大时间 | | gc.ratio-threshold | 跳过 Region GC 的阈值（GC 版本个数/key 个数）| @@ -188,6 +183,12 @@ show warnings; | gc.max-write-bytes-per-sec | 一秒可写入 RocksDB 的最大字节数 | | gc.enable-compaction-filter | 是否使用 compaction filter | | gc.compaction-filter-skip-version-check | 是否跳过 compaction filter 的集群版本检查（未 release）| +| gc.auto-compaction.check-interval | TiKV 检查是否需要触发自动 RocksDB compaction 的时间间隔 | +| gc.auto-compaction.tombstone-num-threshold | 触发 TiKV 自动 (RocksDB) compaction 需要的 RocksDB tombstone 个数 | +| gc.auto-compaction.tombstone-percent-threshold | 触发 TiKV 自动 (RocksDB) compaction 需要的 RocksDB tombstone 所占比例 | +| gc.auto-compaction.redundant-rows-threshold | 触发 TiKV 自动 (RocksDB) compaction 需要的冗余的 MVCC 数据行数 | +| gc.auto-compaction.redundant-rows-percent-threshold | 触发 TiKV 自动 (RocksDB) compaction 需要的冗余的 MVCC 数据行数所占比例 | +| gc.auto-compaction.bottommost-level-force | 控制是否强制对 RocksDB 最底层文件进行 compaction | | {db-name}.max-total-wal-size | WAL 总大小限制 | | {db-name}.max-background-jobs | RocksDB 后台线程个数 | | {db-name}.max-background-flushes | RocksDB flush 线程个数 | @@ -227,6 +228,7 @@ show warnings; | storage.flow-control.soft-pending-compaction-bytes-limit | 触发流控机制开始拒绝部分写入请求的 KvDB pending compaction bytes 阈值 | | storage.flow-control.hard-pending-compaction-bytes-limit | 触发流控机制拒绝所有新写入请求的 KvDB pending compaction bytes 阈值 | | storage.scheduler-worker-pool-size | Scheduler 线程池中线程的数量 | +| import.num-threads | 处理恢复或导入 RPC 请求的线程数量（自 v8.1.2 起支持在线修改） | | backup.num-threads | backup 线程的数量（自 v4.0.3 起支持） | | split.qps-threshold | 对 Region 执行 load-base-split 的阈值。如果连续 10s 内，某个 Region 的读请求的 QPS 超过 qps-threshold，则尝试切分该 Region | | split.byte-threshold | 对 Region 执行 load-base-split 的阈值。如果连续 10s 内，某个 Region 的读请求的流量超过 byte-threshold，则尝试切分该 Region | @@ -271,11 +273,12 @@ Query OK, 0 rows affected (0.01 sec) | cluster-version | 集群的版本 | | schedule.max-merge-region-size | 控制 Region Merge 的 size 上限（单位是 MiB） | | schedule.max-merge-region-keys | 控制 Region Merge 的 key 数量上限 | -| schedule.patrol-region-interval | 控制 replicaChecker 检查 Region 健康状态的运行频率 | +| schedule.patrol-region-interval | 控制 checker 检查 Region 健康状态的运行频率 | | schedule.split-merge-interval | 控制对同一个 Region 做 split 和 merge 操作的间隔 | | schedule.max-snapshot-count | 控制单个 store 最多同时接收或发送的 snapshot 数量 | | schedule.max-pending-peer-count | 控制单个 store 的 pending peer 上限 | | schedule.max-store-down-time | PD 认为失联 store 无法恢复的时间 | +| schedule.max-store-preparing-time | 控制 store 上线阶段的最长等待时间 | | schedule.leader-schedule-policy | 用于控制 leader 调度的策略 | | schedule.leader-schedule-limit | 可以控制同时进行 leader 调度的任务个数 | | schedule.region-schedule-limit | 可以控制同时进行 Region 调度的任务个数 | @@ -293,16 +296,42 @@ Query OK, 0 rows affected (0.01 sec) | schedule.enable-location-replacement | 用于开启隔离级别检查 | | schedule.enable-cross-table-merge | 用于开启跨表 Merge | | schedule.enable-one-way-merge | 用于开启单向 Merge（只允许和下一个相邻的 Region Merge） | +| schedule.region-score-formula-version | 用于设置 Region 算分公式的版本 | +| schedule.scheduler-max-waiting-operator | 用于控制每个调度器同时存在的 operator 的个数 | +| schedule.enable-debug-metrics | 用于开启 debug 的 metrics | +| schedule.enable-heartbeat-concurrent-runner | 用于开启 Region 心跳异步并发处理功能 | +| schedule.enable-heartbeat-breakdown-metrics | 用于开启 Region 心跳指标拆分，用于统计 Region 心跳处理各阶段所消耗的时间 | +| schedule.enable-joint-consensus | 用于开启 Joint Consensus 进行副本调度 | +| schedule.hot-regions-write-interval | 设置 PD 存储 Hot Region 信息时间间隔 | +| schedule.hot-regions-reserved-days | 设置 PD 保留的 Hot Region 信息的最长时间 | +| schedule.max-movable-hot-peer-size | 设置热点调度可以调度的最大 Region size | +| schedule.store-limit-version | 设置 [store limit](/configure-store-limit.md) 工作模式 | +| schedule.patrol-region-worker-count | 控制 checker 检查 Region 健康状态时，创建 operator 的并发数 | | replication.max-replicas | 用于设置副本的数量 | | replication.location-labels | 用于设置 TiKV 集群的拓扑信息 | | replication.enable-placement-rules | 开启 Placement Rules | | replication.strictly-match-label | 开启 label 检查 | +| replication.isolation-level | 设置 TiKV 集群的最小强制拓扑隔离级别 | | pd-server.use-region-storage | 开启独立的 Region 存储 | | pd-server.max-gap-reset-ts | 用于设置最大的重置 timestamp 的间隔（BR）| | pd-server.key-type| 用于设置集群 key 的类型 | | pd-server.metric-storage | 用于设置集群 metrics 的存储地址 | | pd-server.dashboard-address | 用于设置 dashboard 的地址 | +| pd-server.flow-round-by-digit | 指定 PD 对 Region 流量信息的末尾数字进行四舍五入的位数 | +| pd-server.min-resolved-ts-persistence-interval | 设置 PD leader 对集群中 Resolved TS 最小值进行持久化的间隔时间 | +| pd-server.server-memory-limit | PD 实例的内存限制比例 | +| pd-server.server-memory-limit-gc-trigger | PD 尝试触发 GC 的阈值比例 | +| pd-server.enable-gogc-tuner | 是否开启 GOGC Tuner | +| pd-server.gc-tuner-threshold | GOGC Tuner 自动调节的最大内存阈值比例 | | replication-mode.replication-mode | 备份的模式 | +| replication-mode.dr-auto-sync.label-key | 用于区分不同的 AZ，需要和 Placement Rules 相匹配 | +| replication-mode.dr-auto-sync.primary | 主 AZ | +| replication-mode.dr-auto-sync.dr | 从 AZ | +| replication-mode.dr-auto-sync.primary-replicas | 主 AZ 上 Voter 副本的数量 | +| replication-mode.dr-auto-sync.dr-replicas | 从 AZ 上 Voter 副本的数量 | +| replication-mode.dr-auto-sync.wait-store-timeout | 当出现网络隔离或者故障时，切换到异步复制模式的等待时间 | +| replication-mode.dr-auto-sync.wait-recover-timeout | 当网络恢复后，切换回 `sync-recover` 状态的等待时间 | +| replication-mode.dr-auto-sync.pause-region-split | 用于控制在 `async_wait` 和 `async` 状态下是否暂停 Region 的 split 操作 | 具体配置项意义可参考 [PD 配置文件描述](/pd-configuration-file.md)。 diff --git a/ecosystem-tool-user-case.md b/ecosystem-tool-user-case.md index 87db4d1dbc03..be7939a4dcfb 100644 --- a/ecosystem-tool-user-case.md +++ b/ecosystem-tool-user-case.md @@ -1,7 +1,6 @@ --- title: TiDB 工具的使用场景 summary: 本文档介绍 TiDB 工具的常见使用场景与工具选择。 -aliases: ['/docs-cn/dev/ecosystem-tool-user-case/'] --- # TiDB 工具的使用场景 diff --git a/ecosystem-tool-user-guide.md b/ecosystem-tool-user-guide.md index c186ea710d3e..060d8074ad69 100644 --- a/ecosystem-tool-user-guide.md +++ b/ecosystem-tool-user-guide.md @@ -1,7 +1,6 @@ --- title: TiDB 工具功能概览 -aliases: ['/docs-cn/dev/ecosystem-tool-user-guide/','/docs-cn/dev/reference/tools/user-guide/','/docs-cn/dev/how-to/migrate/from-mysql/', '/docs-cn/dev/how-to/migrate/incrementally-from-mysql/', '/docs-cn/dev/how-to/migrate/overview/', '/docs-cn/dev/reference/tools/use-guide/'] -summary: TiDB 提供了丰富的工具，包括部署运维工具 TiUP 和 TiDB Operator，数据管理工具如 TiDB Data Migration（DM）、Dumpling、TiDB Lightning、Backup & Restore（BR）、TiCDC、sync-diff-inspector，以及 OLAP 分析工具 TiSpark。这些工具可用于部署、数据迁移、备份恢复、数据校验等多种操作，满足不同需求。 +summary: TiDB 提供了丰富的工具，包括部署运维工具 TiUP 和 TiDB Operator，数据管理工具如 TiDB Data Migration（DM）、Dumpling、TiDB Lightning、Backup & Restore（BR）、TiCDC、sync-diff-inspector。这些工具可用于部署、数据迁移、备份恢复、数据校验等多种操作，满足不同需求。 --- # TiDB 工具功能概览 @@ -50,7 +49,7 @@ TiDB 提供了 TiUP 和 TiDB Operator 部署运维工具，满足你在不同系 - TiDB DM 的输入：MySQL/MariaDB - TiDB DM 的输出：TiDB 集群 - 适用 TiDB 版本：所有版本 -- Kubernetes 支持：使用 [TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/dev/deploy-tidb-dm) 在 Kubernetes 上部署 TiDB DM。 +- Kubernetes 支持：使用 [TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/v1.6/deploy-tidb-dm) 在 Kubernetes 上部署 TiDB DM。 如果数据量在 TB 级别以下，推荐直接使用 TiDB DM 迁移 MySQL/MariaDB 数据到 TiDB（迁移的过程包括全量数据的导出导入和增量数据的复制）。 @@ -93,7 +92,7 @@ TiDB 提供了 TiUP 和 TiDB Operator 部署运维工具，满足你在不同系 - TiDB Lightning 的输入： - Dumpling 输出文件 - 其他格式兼容的 CSV 文件 - - 从 Aurora 或者 Hive 导出的 Parquet 文件 + - 从 Aurora、Hive 或 Snowflake 导出的 Parquet 文件 - 适用 TiDB 版本：v2.1 及以上 - Kubernetes 支持：[使用 TiDB Lightning 快速恢复 Kubernetes 上的 TiDB 集群数据](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/restore-data-using-tidb-lightning) @@ -130,7 +129,3 @@ TiDB 提供了 TiUP 和 TiDB Operator 部署运维工具，满足你在不同系 - sync-diff-inspector 的输入：TiDB、MySQL - sync-diff-inspector 的输出：TiDB、MySQL - 适用 TiDB 版本：所有版本 - -## OLAP 分析工具 - TiSpark - -[TiSpark](/tispark-overview.md) 是 PingCAP 为解决用户复杂 OLAP 需求而推出的产品。它借助 Spark 平台，同时融合 TiKV 分布式集群的优势，和 TiDB 一起为用户一站式解决 HTAP (Hybrid Transactional/Analytical Processing) 的需求。 diff --git a/enable-tls-between-clients-and-servers.md b/enable-tls-between-clients-and-servers.md index 1ec9a6d80e00..8544cecdc026 100644 --- a/enable-tls-between-clients-and-servers.md +++ b/enable-tls-between-clients-and-servers.md @@ -1,6 +1,5 @@ --- title: 为 TiDB 客户端服务端间通信开启加密传输 -aliases: ['/docs-cn/dev/enable-tls-between-clients-and-servers/','/docs-cn/dev/how-to/secure/enable-tls-clients/','/docs-cn/dev/encrypted-connections-with-tls-protocols/','/docs-cn/dev/enable-tls-between-clients/'] summary: TiDB 服务端与客户端间默认采用非加密连接，容易造成信息泄露。建议使用加密连接确保安全性。要开启 TLS 加密传输，需要在服务端配置开启 TLS 支持，并在客户端应用程序中配置使用 TLS 加密连接。可以通过配置系统变量或在创建 / 修改用户时指定要求加密连接。可通过命令检查当前连接是否是加密连接。TLS 版本为 TLSv1.2 和 TLSv1.3，支持的加密算法包括 AES 和 CHACHA20_POLY1305。 --- @@ -21,7 +20,7 @@ TiDB 服务端支持启用基于 TLS（传输层安全）协议的安全连接 另外，与 MySQL 相同，TiDB 也支持在同一 TCP 端口上开启 TLS 连接或非 TLS 连接。对于开启了 TLS 连接支持的 TiDB 服务端，客户端既可以选择通过加密连接安全地连接到该 TiDB 服务端，也可以选择使用普通的非加密连接。如需使用加密连接，你可以通过以下方式进行配置： + 通过配置系统变量 [`require_secure_transport`](/system-variables.md#require_secure_transport-从-v610-版本开始引入) 要求所有用户必须使用加密连接来连接到 TiDB。 -+ 通过在创建用户 (`create user`)，或修改已有用户 (`alter user`) 时指定 `REQUIRE SSL` 要求指定用户必须使用 TLS 连接来连接 TiDB。以创建用户为例： ++ 通过在创建用户 (`CREATE USER`)，或修改已有用户 (`ALTER USER`) 时指定 `REQUIRE SSL` 要求指定用户必须使用 TLS 连接来连接 TiDB。以创建用户为例： ```sql CREATE USER 'u1'@'%' IDENTIFIED BY 'my_random_password' REQUIRE SSL; @@ -47,6 +46,10 @@ TiDB 服务端支持启用基于 TLS（传输层安全）协议的安全连接 - 参数指定的文件都为 PEM 格式。另外目前 TiDB 尚不支持加载有密码保护的私钥，因此必须提供一个没有密码的私钥文件。若提供的证书或私钥无效，则 TiDB 服务端将照常启动，但并不支持客户端 TLS 连接到 TiDB 服务端。 - 若证书参数无误，则 TiDB 在启动时将会输出 `mysql protocol server secure connection is enabled` 到 `"INFO"` 级别日志中。 +## 配置 TiProxy 使用 TLS 连接 + +如需启用 [TiProxy](/tiproxy/tiproxy-overview.md) 的 TLS 连接支持，可以在 TiProxy 配置文件中指定 [`sql-tls`](/tiproxy/tiproxy-configuration.md#sql-tls) 配置项。关于该配置项的详细说明，以及如何为后端连接启用 TLS，请参考 [TiProxy 安全性](/tiproxy/tiproxy-overview.md#安全)。 + ## 配置 MySQL Client 使用 TLS 连接 MySQL 5.7 及以上版本自带的客户端默认尝试使用 TLS 连接，若服务端不支持安全连接则自动退回到使用非安全连接；MySQL 5.7 以下版本自带的客户端默认采用非 TLS 连接。 @@ -77,7 +80,7 @@ MySQL 5.7 及以上版本自带的客户端默认尝试使用 TLS 连接，若 默认情况，服务端对客户端的身份验证是可选的。若客户端在 TLS 握手时未出示自己的身份证书，也能正常建立 TLS 连接。但也可以通过在创建用户 (`CREATE USER`) 或修改已有用户 (`ALTER USER`) 时指定 `REQUIRE x509` 要求客户端需进行身份验证，以创建用户为例： ```sql -CREATE USER 'u1'@'%' REQUIRE X509; +CREATE USER 'u1'@'%' REQUIRE X509; ``` > **注意：** diff --git a/enable-tls-between-components.md b/enable-tls-between-components.md index 4315e517257c..fd6ebad11d5b 100644 --- a/enable-tls-between-components.md +++ b/enable-tls-between-components.md @@ -1,7 +1,6 @@ --- title: 为 TiDB 组件间通信开启加密传输 summary: 了解如何为 TiDB 集群内各组件间开启加密传输。 -aliases: ['/docs-cn/dev/enable-tls-between-components/','/docs-cn/dev/how-to/secure/enable-tls-between-components/'] --- # 为 TiDB 组件间通信开启加密传输 @@ -68,7 +67,7 @@ aliases: ['/docs-cn/dev/enable-tls-between-components/','/docs-cn/dev/how-to/sec - TiFlash（从 v4.0.5 版本开始引入） - 在 `tiflash.toml` 文件中设置，将 `http_port` 项改为 `https_port`: + 在 `tiflash.toml` 文件中设置： ```toml [security] @@ -142,7 +141,7 @@ aliases: ['/docs-cn/dev/enable-tls-between-components/','/docs-cn/dev/how-to/sec > **注意：** > > - 从 v8.4.0 起，PD 的 `cert-allowed-cn` 配置项支持设置多个值。你可以根据需要在 TiDB 的 `cluster-verify-cn` 配置项以及其它组件的 `cert-allowed-cn` 配置项中设置多个 `Common Name`。需要额外注意的是，TiUP 在查询组件状态的时候会使用独立的标识，比如集群名是 `test`，它会使用 `test-client` 作为 `Common Name`。 -> - 对于 v8.3.0 及之前版本，PD 的 `cert-allowed-cn` 配置项只能设置一个值。因此，所有认证对象的 `Common Name` 必须设置成同一个值。相关配置示例可参见 [v8.3.0 文档](https://docs.pingcap.com/zh/tidb/v8.3/enable-tls-between-components)。 +> - 对于 v8.3.0 及之前版本，PD 的 `cert-allowed-cn` 配置项只能设置一个值。因此，所有认证对象的 `Common Name` 必须设置成同一个值。相关配置示例可参见 [v8.3.0 文档](https://docs-archive.pingcap.com/tidb/v8.3/enable-tls-between-components/)。 - TiDB @@ -187,10 +186,47 @@ aliases: ['/docs-cn/dev/enable-tls-between-components/','/docs-cn/dev/how-to/sec cert-allowed-cn = ["tidb", "tikv", "tiflash", "prometheus"] ``` +## 验证 TiDB 组件间的 TLS 配置 + +在为 TiDB 组件间通信配置 TLS 后，可以使用以下命令验证 TLS 是否已成功启用。这些命令会输出每个组件的证书和 TLS 握手详细信息。 + +- TiDB + + ```sh + openssl s_client -connect :10080 -cert /path/to/client.pem -key /path/to/client-key.pem -CAfile ./ca.crt < /dev/null + ``` + +- PD + + ```sh + openssl s_client -connect :2379 -cert /path/to/client.pem -key /path/to/client-key.pem -CAfile ./ca.crt < /dev/null + ``` + +- TiKV + + ```sh + openssl s_client -connect :20160 -cert /path/to/client.pem -key /path/to/client-key.pem -CAfile ./ca.crt < /dev/null + ``` + +- TiFlash (在 v4.0.5 版本引入) + + ```sh + openssl s_client -connect : -cert /path/to/client.pem -key /path/to/client-key.pem -CAfile ./ca.crt < /dev/null + ``` + +- TiProxy + + ```sh + openssl s_client -connect :3080 -cert /path/to/client.pem -key /path/to/client-key.pem -CAfile ./ca.crt < /dev/null + ``` + ## 证书重新加载 - 如果 TiDB 集群部署在本地的数据中心，TiDB、PD、TiKV、TiFlash、TiCDC 和各种 client 在每次新建相互通讯的连接时都会重新读取当前的证书和密钥文件内容，实现证书和密钥的重新加载，无需重启 TiDB 集群。 -- 如果 TiDB 集群部署在自己管理的 Cloud，TLS 证书的签发需要与云服务商的证书管理服务集成，TiDB、PD、TiKV、TiFlash、TiCDC 组件的 TLS 证书支持自动轮换，无需重启 TiDB 集群。 + +- TiProxy 每小时会从磁盘重新加载一次证书。 + +- 如果 TiDB 集群部署在自己管理的 Cloud，TLS 证书的签发需要与云服务商的证书管理服务集成，TiDB、PD、TiKV、TiFlash、TiCDC、TiProxy 组件的 TLS 证书支持自动轮换，无需重启 TiDB 集群。 ## 证书有效期 diff --git a/encryption-at-rest.md b/encryption-at-rest.md index cb8412aa858a..9f8f6d8093be 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -1,7 +1,6 @@ --- title: 静态加密 summary: 了解如何启用静态加密功能保护敏感数据。 -aliases: ['/docs-cn/dev/encryption-at-rest/'] --- # 静态加密 @@ -28,7 +27,7 @@ TiKV 当前不从核心转储 (core dumps) 中排除加密密钥和用户数据 TiKV 使用文件的绝对路径来跟踪已加密的数据文件。一旦 TiKV 节点开启了加密功能，用户就不应更改数据文件的路径配置，例如 `storage.data-dir`，`raftstore.raftdb-path`，`rocksdb.wal-dir` 和 `raftdb.wal-dir`。 -SM4 加密只在 v6.3.0 及之后版本的 TiKV 上支持。v6.3.0 之前的 TiKV 仅支持 AES 加密。SM4 加密会对吞吐造成 50% 到 80% 的回退。 +SM4 加密只在 v6.3.0 及之后版本的 TiKV 上支持。v6.3.0 之前的 TiKV 仅支持 AES 加密。SM4 加密会对性能造成影响：最严重的情况下，会对吞吐造成 50% 到 80% 的回退；[`storage.block-cache`](/tikv-configuration-file.md#storageblock-cache) 足够大会显著降低加密对吞吐的影响，可将吞吐的回退降至 10% 左右。 ### TiFlash diff --git a/error-codes.md b/error-codes.md index b8e14a9ec9a8..8195a4d4d4d9 100644 --- a/error-codes.md +++ b/error-codes.md @@ -1,6 +1,5 @@ --- title: 错误码与故障诊断 -aliases: ['/docs-cn/dev/error-codes/','/docs-cn/dev/reference/error-codes/'] summary: TiDB 错误码包括 MySQL 兼容的错误码和 TiDB 特有的错误码。如果遇到错误码，请参考官方文档或社区获取支持。常见错误码包括内存使用超限、写入冲突、表数据损坏、事务过大、写入冲突等。另外，TiDB 还提供了故障诊断文档供参考。 --- @@ -404,7 +403,7 @@ TiDB 兼容 MySQL 的错误码，在大多数情况下，返回和 MySQL 一样 * Error Number: 8249 - 资源组不存在。在修改或绑定不存在的资源组时返回该错误。请参考[创建资源组](/tidb-resource-control.md#创建资源组)。 + 资源组不存在。在修改或绑定不存在的资源组时返回该错误。请参考[创建资源组](/tidb-resource-control-ru-groups.md#创建资源组)。 * Error Number: 8250 @@ -428,11 +427,11 @@ TiDB 兼容 MySQL 的错误码，在大多数情况下，返回和 MySQL 一样 * Error Number: 8253 - 查询终止，因为满足 Runaway Queries 的条件。请参考 [Runaway Queries](/tidb-resource-control.md#管理资源消耗超出预期的查询-runaway-queries)。 + 查询终止，因为满足 Runaway Queries 的条件。请参考 [Runaway Queries](/tidb-resource-control-runaway-queries.md)。 * Error Number: 8254 - 查询终止，因为被 Runaway Queries 免疫命中。请参考 [Runaway Queries](/tidb-resource-control.md#管理资源消耗超出预期的查询-runaway-queries)。 + 查询终止，因为被 Runaway Queries 免疫命中。请参考 [Runaway Queries](/tidb-resource-control-runaway-queries.md)。 * Error Number: 8260 @@ -448,7 +447,7 @@ TiDB 兼容 MySQL 的错误码，在大多数情况下，返回和 MySQL 一样 * Error Number: 8263 - 该 DDL 无法在特定的 BDR role 下执行。请确定该集群是否处于[双向复制](/ticdc/ticdc-bidirectional-replication.md) 中。如果集群没有在双向复制中，可以通过 `ADMIN UNSET BDR ROLE;` 使 DDL 恢复正常使用。 + 该 DDL 无法在特定的 BDR role 下执行。请确定该集群是否处于[双向复制](/ticdc/ticdc-bidirectional-replication.md)中。如果集群没有在双向复制中，可以通过 `ADMIN UNSET BDR ROLE;` 使 DDL 恢复正常使用。 * Error Number: 9001 diff --git a/explain-overview.md b/explain-overview.md index 04e4f1793cca..0c1c6d806027 100644 --- a/explain-overview.md +++ b/explain-overview.md @@ -1,7 +1,6 @@ --- title: TiDB 执行计划概览 summary: 了解 TiDB 中 EXPLAIN 语句返回的执行计划。 -aliases: ['/docs-cn/dev/query-execution-plan/','/docs-cn/dev/reference/performance/understanding-the-query-execution-plan/','/docs-cn/dev/index-merge/','/docs-cn/dev/reference/performance/index-merge/','/zh/tidb/dev/query-execution-plan/'] --- # TiDB 执行计划概览 diff --git a/explain-walkthrough.md b/explain-walkthrough.md index d2ceeb4bcebb..957cdd2c34b5 100644 --- a/explain-walkthrough.md +++ b/explain-walkthrough.md @@ -67,7 +67,7 @@ EXPLAIN ANALYZE SELECT count(*) FROM trips WHERE start_date BETWEEN '2017-07-01 5 rows in set (1.03 sec) ``` -执行以上示例查询耗时 `1.03` 秒，说明执行性能较为理想。 +执行以上示例查询耗时 `1.03` 秒，说明执行性能不太理想。 以上 `EXPLAIN ANALYZE` 的结果中，`actRows` 表明一些 `estRows` 预估数不准确（预估返回 10000 行数据但实际返回 19117643 行）。`└─TableFullScan_18` 算子的 `operator info` 列 (`stats:pseudo`) 信息也表明该算子的预估数不准确。 diff --git a/explore-htap.md b/explore-htap.md index 1a4955603e21..7db2ea17d926 100644 --- a/explore-htap.md +++ b/explore-htap.md @@ -1,6 +1,6 @@ --- title: HTAP 深入探索指南 -summary: 本文介绍如何深入探索并使用 TiDB 的 HTAP 功能。 +summary: 本文介绍如何深入探索并使用 TiDB 的 HTAP 功能。 --- # HTAP 深入探索指南 @@ -11,10 +11,6 @@ summary: 本文介绍如何深入探索并使用 TiDB 的 HTAP 功能。 > > 如果你对 TiDB HTAP 功能还不太了解，希望快速试用体验，请参阅[快速上手 HTAP](/quick-start-with-htap.md)。 -要快速了解 TiDB 在 HTAP 场景下的体系架构与 HTAP 的适用场景，建议先观看下面的培训视频（时长 15 分钟）。注意本视频只作为学习参考，如需了解详细的 HTAP 相关内容，请参阅下方的文档内容。 - - - ## HTAP 适用场景 TiDB HTAP 可以满足企业海量数据的增产需求、降低运维的风险成本、与现有的大数据栈无缝缝合，从而实现数据资产价值的实时变现。 @@ -33,7 +29,7 @@ TiDB HTAP 可以满足企业海量数据的增产需求、降低运维的风险 当将 TiDB 应用于数据中枢场景时，TiDB 作为数据中枢可以无缝连接数据业务层和数据仓库层，满足不同业务的需求。 -如果想了解更多关于 TiDB HTAP 场景信息，请参阅 [PingCAP 官网中关于 HTAP 的博客](https://pingcap.com/zh/blog/?tag=HTAP)。 +如果想了解更多关于 TiDB HTAP 场景信息，请参阅 [TiDB HTAP 用户案例合集](https://tidb.net/blog/tag/htap)。 当遇到以下技术场景时，建议使用 TiDB HTAP 提升 TiDB 数据库整体表现： @@ -61,21 +57,15 @@ TiDB HTAP 可以满足企业海量数据的增产需求、降低运维的风险 ## HTAP 环境准备 -在深入探索 TiDB HTAP 功能前，请依据你的数据场景部署 TiDB 以及对应的数据分析引擎。大数据场景 (100 T) 下，推荐使用 TiFlash MPP 作为 HTAP 的主要方案，TiSpark 作为补充方案。 - -- TiFlash - - - 如果已经部署 TiDB 集群但尚未部署 TiFlash 节点，请参阅[扩容 TiFlash 节点](/scale-tidb-using-tiup.md#扩容-tiflash-节点)中的步骤在现有 TiDB 集群中添加 TiFlash 节点。 - - 如果尚未部署 TiDB 集群，请使用 [TiUP 部署 TiDB 集群](/production-deployment-using-tiup.md)，并在包含最小拓扑的基础上，同时[增加 TiFlash 拓扑架构](/tiflash-deployment-topology.md)。 - - 在决定如何选择 TiFlash 节点数量时，请考虑以下几种业务场景： - - - 如果业务场景以 OLTP 为主，做轻量级的 Ad hoc OLAP 计算，通常部署 1 个或几个 TiFlash 节点就会产生明显的加速效果。 - - 当 OLTP 数据吞吐量对节点 I/O 无明显压力时，每个 TiFlash 节点将会使用较多资源用于计算，这样 TiFlash 集群可实现近似线性的扩展能力。TiFlash 节点数量应根据期待的性能和响应时间调整。 - - 当 OLTP 数据吞吐量较高时（例如写入或更新超过千万行/小时），由于网络和物理磁盘的写入能力有限，内部 TiKV 与 TiFlash 之间的 I/O 会成为主要瓶颈，也容易产生读写热点。此时 TiFlash 节点数与 OLAP 计算量有较复杂非线性关系，需要根据具体系统状态调整节点数量。 +在深入探索 TiDB HTAP 功能前，请部署 TiDB 以及对应的数据分析引擎 TiFlash。大数据场景 (100 T) 下，推荐使用 TiFlash MPP 作为 HTAP 的方案。 -- TiSpark +- 如果已经部署 TiDB 集群但尚未部署 TiFlash 节点，请参阅[扩容 TiFlash 节点](/scale-tidb-using-tiup.md#扩容-tiflash-节点)中的步骤在现有 TiDB 集群中添加 TiFlash 节点。 +- 如果尚未部署 TiDB 集群，请使用 [TiUP 部署 TiDB 集群](/production-deployment-using-tiup.md)，并在包含最小拓扑的基础上，同时[增加 TiFlash 拓扑架构](/tiflash-deployment-topology.md)。 +- 在决定如何选择 TiFlash 节点数量时，请考虑以下几种业务场景： - - 如果你的业务需要基于 Spark 进行分析，请部署 TiSpark。具体步骤，请参阅 [TiSpark 用户指南](/tispark-overview.md)。 + - 如果业务场景以 OLTP 为主，做轻量级的 Ad hoc OLAP 计算，通常部署 1 个或几个 TiFlash 节点就会产生明显的加速效果。 + - 当 OLTP 数据吞吐量对节点 I/O 无明显压力时，每个 TiFlash 节点将会使用较多资源用于计算，这样 TiFlash 集群可实现近似线性的扩展能力。TiFlash 节点数量应根据期待的性能和响应时间调整。 + - 当 OLTP 数据吞吐量较高时（例如写入或更新超过千万行/小时），由于网络和物理磁盘的写入能力有限，内部 TiKV 与 TiFlash 之间的 I/O 会成为主要瓶颈，也容易产生读写热点。此时 TiFlash 节点数与 OLAP 计算量有较复杂非线性关系，需要根据具体系统状态调整节点数量。 diff --git a/expression-syntax.md b/expression-syntax.md index a6a1743f4d03..0110ba1d4523 100644 --- a/expression-syntax.md +++ b/expression-syntax.md @@ -1,7 +1,6 @@ --- title: 表达式语法 summary: 本文列出 TiDB 的表达式语法。 -aliases: ['/docs-cn/dev/expression-syntax/','/docs-cn/dev/reference/sql/language-structure/expression-syntax/'] --- # 表达式语法 (Expression Syntax) @@ -15,7 +14,7 @@ aliases: ['/docs-cn/dev/expression-syntax/','/docs-cn/dev/reference/sql/language + 函数调用，窗口函数等。可参考[函数和操作符概述](/functions-and-operators/functions-and-operators-overview.md)和[窗口函数](/functions-and-operators/window-functions.md)。 + 其他，包括 paramMarker（即 `?`）、系统变量和用户变量、CASE 表达式等。 -以下规则是表达式的语法，该语法基于 TiDB parser 的 [`parser.y`](https://github.com/pingcap/tidb/blob/master/pkg/parser/parser.y) 文件中所定义的规则。 +以下规则是表达式的语法，该语法基于 TiDB parser 的 [`parser.y`](https://github.com/pingcap/tidb/blob/release-8.5/pkg/parser/parser.y) 文件中所定义的规则。 ```ebnf+diagram Expression ::= diff --git a/faq/backup-and-restore-faq.md b/faq/backup-and-restore-faq.md index d2de7148558e..b9005b158a96 100644 --- a/faq/backup-and-restore-faq.md +++ b/faq/backup-and-restore-faq.md @@ -1,7 +1,6 @@ --- title: 备份与恢复常见问题 summary: 了解备份恢复相关的常见问题以及解决方法。 -aliases: ['/docs-cn/dev/br/backup-and-restore-faq/','/zh/tidb/dev/pitr-troubleshoot/','/zh/tidb/dev/pitr-known-issues/'] --- # 备份与恢复常见问题 @@ -12,7 +11,7 @@ aliases: ['/docs-cn/dev/br/backup-and-restore-faq/','/zh/tidb/dev/pitr-troublesh ## 当误删除或误更新数据后，如何原地快速恢复？ -从 TiDB v6.4.0 引入了完整的 Flashback 功能，可以支持原地快速恢复 GC 时间内的数据到指定时间点。在误操作场景下，推荐使用 Flashback 来恢复数据，具体可以参考 [Flashback 集群](/sql-statements/sql-statement-flashback-cluster.md) 和 [Flashback 数据库](/sql-statements/sql-statement-flashback-database.md)语法。 +从 TiDB v6.4.0 引入了完整的 Flashback 功能，可以支持原地快速恢复 GC 时间内的数据到指定时间点。在误操作场景下，推荐使用 Flashback 来恢复数据，具体可以参考 [Flashback 集群](/sql-statements/sql-statement-flashback-cluster.md)和 [Flashback 数据库](/sql-statements/sql-statement-flashback-database.md)语法。 ## 在 TiDB v5.4.0 及后续版本中，当在有负载的集群进行备份时，备份速度为什么会变得很慢？ @@ -108,6 +107,14 @@ Error: failed to check gc safePoint, checkpoint ts 433177834291200000: GC safepo 此场景的处理办法是：先执行 `br log stop` 命令来删除当前的任务，然后执行 `br log start` 重新创建新的日志备份任务，同时做一个全量备份，便于后续做 PITR 恢复操作。 +### 执行 PITR table filter 时报 `[ddl:8204]invalid ddl job type: none` 错误，该如何处理？ + +```shell +failed to refresh meta for database with schemaID=124, dbName=pitr_test: [ddl:8204]invalid ddl job type: none +``` + +该错误是由于 DDL Owner 所在的 TiDB 节点版本过低，无法识别 Refresh Meta DDL 导致的。请将集群升级至 v8.5.5 或更高版本，再使用 PITR 的 [table filter](/table-filter.md) 功能。 + ## 功能兼容性问题 ### 为什么 BR 恢复的数据无法同步到 TiCDC 的上游集群？ @@ -279,7 +286,7 @@ br restore full -f 'mysql.usertable' -s $external_storage_url --with-sys-table - 统计信息表（`mysql.stat_*`）(但可以恢复统计信息，详细参考[备份统计信息](/br/br-snapshot-manual.md#备份统计信息)) - 系统变量表（`mysql.tidb`、`mysql.global_variables`） -- [其他系统表](https://github.com/pingcap/tidb/blob/master/br/pkg/restore/snap_client/systable_restore.go#L31) +- [其他系统表](https://github.com/pingcap/tidb/blob/release-8.5/br/pkg/restore/snap_client/systable_restore.go#L31) ### 恢复的时候，报错 `cannot file rewrite rule`，该如何处理？ diff --git a/faq/deploy-and-maintain-faq.md b/faq/deploy-and-maintain-faq.md index f3be50ca9846..45d3f8249ac5 100644 --- a/faq/deploy-and-maintain-faq.md +++ b/faq/deploy-and-maintain-faq.md @@ -1,7 +1,6 @@ --- title: TiDB 安装部署常见问题 summary: 介绍 TiDB 集群安装部署的常见问题、原因及解决方法。 -aliases: ['/docs-cn/dev/faq/deploy-and-maintain-faq/'] --- # TiDB 安装部署常见问题 @@ -12,11 +11,11 @@ aliases: ['/docs-cn/dev/faq/deploy-and-maintain-faq/'] ### TiDB 支持哪些操作系统？ -关于 TiDB 支持的操作系统，参见 [TiDB 软件和硬件环境建议配置](/hardware-and-software-requirements.md)。 +关于 TiDB 支持的操作系统，参见[操作系统及平台要求](/hardware-and-software-requirements.md#操作系统及平台要求)。 ### TiDB 对开发、测试、生产环境的服务器硬件配置有什么要求？ -TiDB 支持部署和运行在 Intel x86-64 架构的 64 位通用硬件服务器平台。对于开发、测试、生产环境的服务器硬件配置，参见 [TiDB 软件和硬件环境建议配置 - 服务器建议配置](/hardware-and-software-requirements.md#服务器建议配置)。 +TiDB 支持部署和运行在 Intel x86-64 架构的 64 位通用硬件服务器平台。对于开发、测试、生产环境的服务器硬件配置，参见[服务器配置要求](/hardware-and-software-requirements.md#服务器配置要求)。 ### 两块网卡的目的是？万兆的目的是？ @@ -50,30 +49,6 @@ TiDB 支持部署和运行在 Intel x86-64 架构的 64 位通用硬件服务器 查看访问监控的机器时间跟集群内机器的时间差，如果比较大，更正时间后即可显示正常。 -### supervise/svc/svstat 服务具体起什么作用？ - -- supervise 守护进程 -- svc 启停服务 -- svstat 查看进程状态 - -### inventory.ini 变量参数解读 - -| **变量** | **含义** | -| --- | --- | -| cluster_name | 集群名称，可调整 | -| tidb_version | TiDB 版本 | -| deployment_method | 部署方式，默认为 binary，可选 docker | -| process_supervision | 进程监管方式，默认为 systemd，可选 supervise | -| timezone | 修改部署目标机器时区，默认为 Asia/Shanghai，可调整，与 set_timezone 变量结合使用 | -| set_timezone | 默认为 True，即修改部署目标机器时区，关闭可修改为 False | -| enable_elk | 目前不支持，请忽略 | -| enable_firewalld | 开启防火墙，默认不开启 | -| enable_ntpd | 检测部署目标机器 NTP 服务，默认为 True，请勿关闭 | -| machine_benchmark | 检测部署目标机器磁盘 IOPS，默认为 True，请勿关闭 | -| set_hostname | 根据 IP 修改部署目标机器主机名，默认为 False | -| enable_slow_query_log | TiDB 慢查询日志记录到单独文件({{ deploy_dir }}/log/tidb_slow_query.log)，默认为 False，记录到 tidb 日志 | -| deploy_without_tidb | KV 模式，不部署 TiDB 服务，仅部署 PD、TiKV 及监控服务，请将 inventory.ini 文件中 tidb_servers 主机组 IP 设置为空。 | - ### 如何单独记录 TiDB 中的慢查询日志，如何定位慢查询 SQL？ 1. TiDB 中，对慢查询的定义在 TiDB 的配置文件中。`tidb_slow_log_threshold: 300`，这个参数是配置慢查询记录阈值的，单位是 ms。 @@ -94,24 +69,27 @@ Direct 模式就是把写入请求直接封装成 I/O 指令发到磁盘，这 ### 如何用 fio 命令测试 TiKV 实例的磁盘性能？ -- 随机读测试： +以下示例使用 `ioengine=psync`（即同步 I/O），因此 `iodepth` 通常固定为 `1`，并发主要由 `numjobs` 控制。建议使用 `direct=1` 以绕过文件系统缓存。 - {{< copyable "shell-regular" >}} +- 随机读测试： ```bash - ./fio -ioengine=psync -bs=32k -fdatasync=1 -thread -rw=randread -size=10G -filename=fio_randread_test.txt -name='fio randread test' -iodepth=4 -runtime=60 -numjobs=4 -group_reporting --output-format=json --output=fio_randread_result.json + ./fio -ioengine=psync -bs=32k -direct=1 -thread -rw=randread -time_based -size=10G -filename=fio_randread_test.txt -name='fio randread test' -iodepth=1 -runtime=60 -numjobs=4 -group_reporting --output-format=json --output=fio_randread_result.json ``` - 顺序写和随机读混合测试： - {{< copyable "shell-regular" >}} - ```bash - ./fio -ioengine=psync -bs=32k -fdatasync=1 -thread -rw=randrw -percentage_random=100,0 -size=10G -filename=fio_randread_write_test.txt -name='fio mixed randread and sequential write test' -iodepth=4 -runtime=60 -numjobs=4 -group_reporting --output-format=json --output=fio_randread_write_test.json + ./fio -ioengine=psync -bs=32k -direct=1 -thread -rw=randrw -percentage_random=100,0 -time_based -size=10G -filename=fio_randread_write_test.txt -name='fio mixed randread and sequential write test' -iodepth=1 -runtime=60 -numjobs=4 -group_reporting --output-format=json --output=fio_randread_write_test.json ``` ## TiDB 支持在公有云上部署吗？ -TiDB 支持在 [Google Cloud GKE](https://docs.pingcap.com/zh/tidb-in-kubernetes/v1.1/deploy-on-gcp-gke)、[AWS EKS](https://docs.pingcap.com/zh/tidb-in-kubernetes/v1.1/deploy-on-aws-eks) 和[阿里云 ACK](https://docs.pingcap.com/zh/tidb-in-kubernetes/v1.1/deploy-on-alibaba-cloud) 上部署使用。 +TiDB 支持在以下云上部署： + +- [Google Cloud GKE](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/deploy-on-gcp-gke/) +- [AWS EKS](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/deploy-on-aws-eks/) +- [Azure AKS](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/deploy-on-azure-aks/) +- [阿里云 ACK](https://docs.pingcap.com/zh/tidb-in-kubernetes/v1.5/deploy-on-alibaba-cloud/) 此外，TiDB 云上部署也已在京东云、UCloud 上线。 diff --git a/faq/high-availability-faq.md b/faq/high-availability-faq.md index 7bae9798e0b2..e636e9d03d5b 100644 --- a/faq/high-availability-faq.md +++ b/faq/high-availability-faq.md @@ -1,7 +1,6 @@ --- title: 高可用常见问题 summary: 介绍高可用相关的常见问题。 -aliases: ['/docs-cn/dev/faq/high-availability-faq/'] --- # 高可用常见问题 diff --git a/faq/high-reliability-faq.md b/faq/high-reliability-faq.md index e81f5cfb5e4e..f36d72f37ade 100644 --- a/faq/high-reliability-faq.md +++ b/faq/high-reliability-faq.md @@ -1,7 +1,6 @@ --- title: 高可靠常见问题 summary: 介绍高可靠相关的常见问题。 -aliases: ['/docs-cn/dev/faq/high-reliability-faq/'] --- # 高可靠常见问题 diff --git a/faq/manage-cluster-faq.md b/faq/manage-cluster-faq.md index 394de80f24ee..188e07a4353f 100644 --- a/faq/manage-cluster-faq.md +++ b/faq/manage-cluster-faq.md @@ -41,7 +41,7 @@ mysql -h 127.0.0.1 -uroot -P4000 如需快速了解 TiDB 节点、TiKV 节点、PD 节点的配置文件、数据文件及日志文件的相关介绍与其存放位置，建议观看下面的培训视频（时长 9 分钟）。 - + ### 如何规范停止 TiDB？ @@ -101,7 +101,7 @@ TiDB 目前社区非常活跃，同时，我们还在不断的优化和修改 BU ### Percolator 用了分布式锁，crash 的客户端会保持锁，会造成锁没有 release？ -详细可参考 [Percolator 和 TiDB 事务算法](https://pingcap.com/blog-cn/percolator-and-txn/)。 +详细可参考 [Percolator 和 TiDB 事务算法](https://tidb.net/blog/f537be2c)。 ### TiDB 为什么选用 gRPC 而不选用 Thrift，是因为 Google 在用吗？ @@ -334,23 +334,19 @@ Region 不是前期划分好的，但确实有 Region 分裂机制。当 Region ### TiKV 是否有类似 MySQL 的 `innodb_flush_log_trx_commit` 参数，来保证提交数据不丢失？ -是的。TiKV 单机的存储引擎目前使用两个 RocksDB 实例，其中一个存储 raft-log。TiKV 有个 sync-log 参数，在 true 的情况下，每次提交都会强制刷盘到 raft-log，如果发生 crash 后，通过 raft-log 进行 KV 数据的恢复。 +TiKV 没有类似的参数，但是 TiKV 上的每次提交都会强制落盘到 Raft 日志 (TiKV 使用 [Raft Engine](/glossary.md#raft-engine) 存储 Raft 日志，在提交时会强制刷盘)。如果 TiKV 发生 crash，KV 的数据将会根据 Raft 日志自动恢复。 ### 对 WAL 存储有什么推荐的硬件配置，例如 SSD，RAID 级别，RAID 卡 cache 策略，NUMA 设置，文件系统选择，操作系统的 IO 调度策略等？ WAL 属于顺序写，目前我们并没有单独对他进行配置，建议 SSD。RAID 如果允许的话，最好是 RAID 10，RAID 卡 cache、操作系统 I/O 调度目前没有针对性的最佳实践，Linux 7 以上默认配置即可。NUMA 没有特别建议，NUMA 内存分配策略可以尝试使用 `interleave = all`，文件系统建议 ext4。 -### 在最严格的 `sync-log = true` 数据可用模式下，写入性能如何？ +### 是否可以利用 TiKV 的 Raft + 多副本达到完全的数据可靠？ -一般来说，开启 `sync-log` 会让性能损耗 30% 左右。关闭 `sync-log` 时的性能表现，请参见 [TiDB Sysbench 性能测试报告](/benchmark/v3.0-performance-benchmarking-with-sysbench.md)。 +通过使用 [Raft 一致性算法](https://raft.github.io/)，数据在各 TiKV 节点间复制为多副本，以确保某个节点挂掉时数据的安全性。只有当数据已写入超过 50% 的副本时，应用才返回 ACK（三副本中的两副本）。 -### 是否可以利用 TiKV 的 Raft + 多副本达到完全的数据可靠，单机存储引擎是否需要最严格模式？ +理论上两个节点也可能同时发生故障，因此从 v5.0 版本开始，写入 TiKV 的数据会默认落盘，即每次提交都会强制落盘到 Raft 日志。如果 TiKV 发生 crash，KV 的数据将会根据 Raft 日志自动恢复。 -通过使用 [Raft 一致性算法](https://raft.github.io/)，数据在各 TiKV 节点间复制为多副本，以确保某个节点挂掉时数据的安全性。只有当数据已写入超过 50% 的副本时，应用才返回 ACK（三副本中的两副本）。但理论上两个节点也可能同时发生故障，所以除非是对性能要求高于数据安全的场景，一般都强烈推荐开启 `sync-log`。 - -另外，还有一种 `sync-log` 的替代方案，即在 Raft group 中用五个副本而非三个。这将允许两个副本同时发生故障，而仍然能保证数据安全性。 - -对于单机存储引擎也同样推荐打开 `sync-log` 模式。否则如果节点宕机可能会丢失最后一次写入数据。 +此外，也可以考虑在 Raft group 中使用五个副本而非三个。这将允许两个副本同时发生故障，而仍然能保证数据安全性。 ### 使用 Raft 协议，数据写入会有多次网络的 roundtrip，实际写入延迟如何？ @@ -384,12 +380,17 @@ TiKV 的内存占用主要来自于 RocksDB 的 block-cache，默认为系统总 本小节介绍 TiDB 测试中的常见问题、原因及解决方法。 +### 如何对 TiDB 进行 Sysbench 基准测试？ + +参考[如何用 Sysbench 测试 TiDB](/benchmark/benchmark-tidb-using-sysbench.md)。 + ### TiDB Sysbench 基准测试结果如何？ -很多用户在接触 TiDB 都习惯做一个基准测试或者 TiDB 与 MySQL 的对比测试，官方也做了一个类似测试。我们汇总很多测试结果后，发现虽然测试的数据有一定的偏差，但结论或者方向基本一致，由于 TiDB 与 MySQL 由于架构上的差别非常大，很多方面是很难找到一个基准点，所以官方的建议两点： +很多用户在接触 TiDB 时都习惯做一个基准测试，或者将 TiDB 与 MySQL 进行对比测试。官方也曾进行过类似的测试，发现尽管不同的测试数据之间存在一定的偏差，但整体结论和方向大致一致。由于 TiDB 和 MySQL 在架构上的差异非常大，许多方面都很难找到完全对等的基准点。 + +因此，无需纠结于这类基准测试，可以更多关注 TiDB 在使用场景上的区别。 -- 大家不要用过多精力纠结这类基准测试上，应该更多关注 TiDB 的场景上的区别。 -- 大家可以直接参考 [TiDB Sysbench 性能测试报告](/benchmark/v3.0-performance-benchmarking-with-sysbench.md)。 +如需了解 TiDB v8.5 的性能表现，可以参考 TiDB Cloud Dedicated 集群的[性能测试报告](https://docs.pingcap.com/tidbcloud/v8.5-performance-highlights)（英文版）。 ### TiDB 集群容量 QPS 与节点数之间关系如何，和 MySQL 对比如何？ diff --git a/faq/migration-tidb-faq.md b/faq/migration-tidb-faq.md index 5774d56c1c0e..28b4836c05c2 100644 --- a/faq/migration-tidb-faq.md +++ b/faq/migration-tidb-faq.md @@ -1,7 +1,6 @@ --- title: 迁移常见问题 summary: 介绍 TiDB 迁移中的常见问题。 -aliases: ['/docs-cn/dev/faq/migration-tidb-faq/'] --- # 迁移常见问题 @@ -81,9 +80,9 @@ iperf Done. - 参考 [MySQL 使用 mysqldump 导出某个表的部分数据](https://blog.csdn.net/xin_yu_xin/article/details/7574662)，使用 mysqldump 加 where 条件导出。 - 使用 MySQL client 将 select 的结果输出到一个文件。 -### 如何从 DB2、Oracle 数据库迁移到 TiDB？ +### 如何从 Db2、Oracle 数据库迁移到 TiDB？ -DB2、Oracle 到 TiDB 数据迁移（增量+全量），通常做法有： +Db2、Oracle 到 TiDB 数据迁移（增量+全量），通常做法有： - 使用 Oracle 官方迁移工具，如 OGG、Gateway（透明网关）、CDC (Change Data Capture)。 - 自研数据导出导入程序实现。 @@ -109,7 +108,7 @@ DB2、Oracle 到 TiDB 数据迁移（增量+全量），通常做法有： --batch ``` -- 也可以选择增大 tidb 的单个事物语句数量限制，不过这个会导致内存上涨。 +- 也可以选择增大 TiDB 单个事务允许的语句条数限制，不过这样会占用更多内存。 ### Dumpling 导出时引发上游数据库 OOM 或报错“磁盘空间不足” @@ -166,11 +165,11 @@ DELETE，TRUNCATE 和 DROP 都不会立即释放空间。对于 TRUNCATE 和 DRO ### 删除数据后查询速度为何会变慢？ -删除大量数据后，会有很多无用的 key 存在，影响查询效率。要解决该问题，可以尝试开启 [Region Merge](/best-practices/massive-regions-best-practices.md#方法五开启-region-merge) 功能，具体可参考[最佳实践](https://pingcap.com/blog-cn/tidb-best-practice/)中的删除数据部分。 +删除大量数据后，会有很多无用的 key 存在，影响查询效率。要解决该问题，可以尝试开启 [Region Merge](/best-practices/massive-regions-best-practices.md#方法五开启-region-merge) 功能，具体可参考[最佳实践](https://tidb.net/blog/7f818fc0)中的删除数据部分。 ### 数据删除最高效最快的方式？ -在删除大量数据的时候，建议使用 `Delete from t where xx limit 5000`（xx 建议在满足业务过滤逻辑下，尽量加上强过滤索引列或者直接使用主键选定范围，如 `id >= 5000*n+m and id <= 5000*(n+1)+m` 这样的方案，通过循环来删除，用 `Affected Rows == 0` 作为循环结束条件，这样避免遇到事务大小的限制。如果一次删除的数据量非常大，这种循环的方式会越来越慢，因为每次删除都是从前向后遍历，前面的删除之后，短时间内会残留不少删除标记（后续会被 GC 掉），影响后面的 Delete 语句。如果有可能，建议把 Where 条件细化。可以参考官网[最佳实践](https://pingcap.com/blog-cn/tidb-best-practice/)。 +在删除大量数据的时候，建议使用 `Delete from t where xx limit 5000`（xx 建议在满足业务过滤逻辑下，尽量加上强过滤索引列或者直接使用主键选定范围，如 `id >= 5000*n+m and id <= 5000*(n+1)+m` 这样的方案，通过循环来删除，用 `Affected Rows == 0` 作为循环结束条件，这样避免遇到事务大小的限制。如果一次删除的数据量非常大，这种循环的方式会越来越慢，因为每次删除都是从前向后遍历，前面的删除之后，短时间内会残留不少删除标记（后续会被 GC 掉），影响后面的 Delete 语句。如果有可能，建议把 Where 条件细化。可以参考官网[最佳实践](https://tidb.net/blog/7f818fc0)。 ### TiDB 如何提高数据加载速度？ diff --git a/faq/sql-faq.md b/faq/sql-faq.md index dbbbcd596096..01b082b93791 100644 --- a/faq/sql-faq.md +++ b/faq/sql-faq.md @@ -1,7 +1,6 @@ --- title: SQL 操作常见问题 summary: 介绍 SQL 操作相关的常见问题。 -aliases: ['/docs-cn/dev/faq/sql-faq/'] --- # SQL 操作常见问题 @@ -33,7 +32,9 @@ TiDB 包含一个基于成本的优化器。在大多数情况下，优化器会 ## 如何阻止特定的 SQL 语句执行（或者将某个 SQL 语句加入黑名单）？ -你可以使用 [`MAX_EXECUTION_TIME`](/optimizer-hints.md#max_execution_timen) Hint 来创建 [SQL 绑定](/sql-plan-management.md#执行计划绑定-sql-binding)，将特定语句的执行时间限制为一个较小的值（例如 1ms）。这样，语句就会在超过限制时自动终止。 +对于 v7.5.0 及以上版本，你可以使用 [`QUERY WATCH`](/sql-statements/sql-statement-query-watch.md) 语句将特定的 SQL 查询加入黑名单。具体使用方法参见[管理资源消耗超出预期的查询 (Runaway Queries)](/tidb-resource-control-runaway-queries.md#query-watch-语句说明)。 + +对于 v7.5.0 之前版本，你可以使用 [`MAX_EXECUTION_TIME`](/optimizer-hints.md#max_execution_timen) Hint 来创建 [SQL 绑定](/sql-plan-management.md#执行计划绑定-sql-binding)，将特定语句的执行时间限制为一个较小的值（例如 1ms）。这样，语句就会在超过限制时自动终止。 例如，要阻止执行 `SELECT * FROM t1, t2 WHERE t1.id = t2.id`，可以使用以下 SQL 绑定将语句的执行时间限制为 1ms： @@ -171,7 +172,7 @@ TiDB 支持在会话或全局作用域上修改 [`sql_mode`](/system-variables.m --batch ``` -- 也可以选择增大 TiDB 的单个事物语句数量限制，不过此操作会导致内存增加。详情参见 [SQL 语句的限制](/tidb-limitations.md#sql-statements-的限制)。 +- 也可以选择增大 TiDB 单个事务允许的语句条数限制，不过这样会占用更多内存。详情参见 [SQL 语句的限制](/tidb-limitations.md#sql-statements-的限制)。 ## TiDB 有像 Oracle 那样的 Flashback Query 功能么，DDL 支持么？ @@ -183,7 +184,7 @@ TiDB 支持在会话或全局作用域上修改 [`sql_mode`](/system-variables.m ## 删除数据后查询速度为何会变慢？ -删除大量数据后，会有很多无用的 key 存在，影响查询效率。要解决该问题，可以尝试开启 [Region Merge](/best-practices/massive-regions-best-practices.md#方法五开启-region-merge) 功能，具体可参考[最佳实践](https://pingcap.com/blog-cn/tidb-best-practice/)中的删除数据部分。 +删除大量数据后，会有很多无用的 key 存在，影响查询效率。要解决该问题，可以尝试开启 [Region Merge](/best-practices/massive-regions-best-practices.md#方法五开启-region-merge) 功能，具体可参考[最佳实践](https://tidb.net/blog/7f818fc0)中的删除数据部分。 ## 对数据做删除操作之后，空间回收比较慢，如何处理？ @@ -207,7 +208,7 @@ TiDB 支持改变[全局](/system-variables.md#tidb_force_priority)或单个语 > **注意：** > -> TiDB 从 v6.6.0 版本开始支持[使用资源管控 (Resource Control) 实现资源隔离](/tidb-resource-control.md)功能。该功能可以将不同优先级的语句放在不同的资源组中执行，并为这些资源组分配不同的配额和优先级，可以达到更好的资源管控效果。在开启资源管控功能后，语句的调度主要受资源组的控制，`PRIORITY` 将不再生效。建议在支持资源管控的版本优先使用资源管控功能。 +> TiDB 从 v6.6.0 版本开始支持[使用资源管控 (Resource Control) 实现资源组限制和流控](/tidb-resource-control-ru-groups.md)功能。该功能可以将不同优先级的语句放在不同的资源组中执行，并为这些资源组分配不同的配额和优先级，可以达到更好的资源管控效果。在开启资源管控功能后，语句的调度主要受资源组的控制，`PRIORITY` 将不再生效。建议在支持资源管控的版本优先使用资源管控功能。 以上两种参数可以结合 TiDB 的 DML 语言进行使用，使用方法举例如下： @@ -237,7 +238,7 @@ TiDB 支持改变[全局](/system-variables.md#tidb_force_priority)或单个语 ## DDL 执行 -本节列出了 DDL 语句执行的相关问题。DDL 执行原理的详细说明，参见 [TiDB 中 DDL 执行原理及最佳实践](/ddl-introduction.md)。 +本节列出了 DDL 语句执行的相关问题。DDL 执行原理的详细说明，参见 [TiDB 中 DDL 执行原理及最佳实践](/best-practices/ddl-introduction.md)。 ### 各类 DDL 操作的预估耗时是多长？ @@ -323,6 +324,73 @@ TiDB 在执行 SQL 语句时，会根据隔离级别确定一个对象的 `schem - 如果 Owner 不存在，尝试手动触发 Owner 选举：`curl -X POST http://{TiDBIP}:10080/ddl/owner/resign`。 - 如果 Owner 存在，导出 Goroutine 堆栈并检查可能卡住的地方。 +## JDBC 连接所使用的排序规则 + +本节列出了 JDBC 连接排序规则的相关问题。关于 TiDB 支持的字符集和排序规则，请参考[字符集和排序规则](/character-set-and-collation.md)。 + +### 当 JDBC URL 中未配置 `connectionCollation` 时，JDBC 连接使用什么排序规则？ + +当 JDBC URL 中未配置 `connectionCollation` 时，有以下两种场景： + +**场景一**：JDBC URL 中 `connectionCollation` 和 `characterEncoding` 均未配置 + +- 对于 Connector/J8.0.25 及之前版本，JDBC 驱动程序将尝试使用服务器的默认字符集。因为 TiDB 的默认字符集为 `utf8mb4`，驱动程序将使用 `utf8mb4_bin` 作为连接排序规则。 +- 对于 Connector/J8.0.26 及之后版本，JDBC 驱动程序将使用 `utf8mb4` 字符集，并根据 `SELECT VERSION()` 的返回值自动选择排序规则。 + + - 当返回值小于 `8.0.1` 时，驱动程序使用 `utf8mb4_general_ci` 作为连接排序规则。TiDB 将遵循驱动程序，使用 `utf8mb4_general_ci` 作为排序规则。 + - 当返回值大于等于 `8.0.1` 时，驱动程序使用 `utf8mb4_0900_ai_ci` 作为连接排序规则。v7.4.0 及之后版本的 TiDB 将遵循驱动程序，使用 `utf8mb4_0900_ai_ci` 作为排序规则，而 v7.4.0 之前版本的 TiDB 由于不支持 `utf8mb4_0900_ai_ci` 排序规则，将回退到使用默认的排序规则 `utf8mb4_bin`。 + +**场景二**：JDBC URL 中配置了 `characterEncoding=utf8` 但未配置 `connectionCollation`，JDBC 驱动程序将按照映射规则使用 `utf8mb4` 字符集，并按照场景一中的描述选择排序规则。 + +### 如何解决 TiDB 升级后排序规则变化带来的问题？ + +在 TiDB v7.4 及之前版本中，如果 JDBC URL 中未配置 `connectionCollation`，且 `characterEncoding` 未配置或配置为 `UTF-8`，TiDB [`collation_connection`](/system-variables.md#collation_connection) 变量将默认使用 `utf8mb4_bin` 排序规则。 + +从 TiDB v7.4 开始，如果 JDBC URL 中未配置 `connectionCollation`，且 `characterEncoding` 未配置或配置为 `UTF-8`，[`collation_connection`](/system-variables.md#collation_connection) 变量值取决于 JDBC 驱动版本。详情请参考[JDBC 连接的排序规则](#当-jdbc-url-中未配置-connectioncollation-时jdbc-连接使用什么排序规则)。 + +当从较低版本升级到 v7.4 或更高版本时（例如，从 v6.5 升级到 v7.5），如需保持 JDBC 连接的 `collation_connection` 为 `utf8mb4_bin`，建议在 JDBC URL 中配置 `connectionCollation` 参数。 + +以下为 TiDB v6.5 中常见的 JDBC URL 配置： + +``` +spring.datasource.url=JDBC:mysql://{TiDBIP}:{TiDBPort}/{DBName}?characterEncoding=UTF-8&useSSL=false&useServerPrepStmts=true&cachePrepStmts=true&prepStmtCacheSqlLimit=10000&prepStmtCacheSize=1000&useConfigs=maxPerformance&rewriteBatchedStatements=true&defaultFetchSize=-2147483648&allowMultiQueries=true +``` + +升级到 TiDB v7.4 或更高版本后，建议在 JDBC URL 中配置 `connectionCollation` 参数： + +``` +spring.datasource.url=JDBC:mysql://{TiDBIP}:{TiDBPort}/{DBName}?characterEncoding=UTF-8&connectionCollation=utf8mb4_bin&useSSL=false&useServerPrepStmts=true&cachePrepStmts=true&prepStmtCacheSqlLimit=10000&prepStmtCacheSize=1000&useConfigs=maxPerformance&rewriteBatchedStatements=true&defaultFetchSize=-2147483648&allowMultiQueries=true +``` + +### `utf8mb4_bin` 与 `utf8mb4_0900_ai_ci` 排序规则有何区别？ + +| 排序规则 | 是否区分大小写 | 是否忽略末尾空格 | 是否区分重音 | 比较方式 | +|----------------------|----------------|------------------|--------------|------------------------| +| `utf8mb4_bin` | 区分 | 忽略 | 区分 | 按二进制编码值比较 | +| `utf8mb4_0900_ai_ci` | 不区分 | 不忽略 | 不区分 | 使用 Unicode 排序算法 | + +例如： + +```sql +-- utf8mb4_bin 区分大小写 +SELECT 'apple' = 'Apple' COLLATE utf8mb4_bin; -- 返回 0 (FALSE) + +-- utf8mb4_0900_ai_ci 不区分大小写 +SELECT 'apple' = 'Apple' COLLATE utf8mb4_0900_ai_ci; -- 返回 1 (TRUE) + +-- utf8mb4_bin 忽略末尾空格 +SELECT 'Apple ' = 'Apple' COLLATE utf8mb4_bin; -- 返回 1 (TRUE) + +-- utf8mb4_0900_ai_ci 不忽略末尾空格 +SELECT 'Apple ' = 'Apple' COLLATE utf8mb4_0900_ai_ci; -- 返回 0 (FALSE) + +-- utf8mb4_bin 区分重音 +SELECT 'café' = 'cafe' COLLATE utf8mb4_bin; -- 返回 0 (FALSE) + +-- utf8mb4_0900_ai_ci 不区分重音 +SELECT 'café' = 'cafe' COLLATE utf8mb4_0900_ai_ci; -- 返回 1 (TRUE) +``` + ## SQL 优化 ### TiDB 执行计划解读 @@ -410,4 +478,4 @@ ID 没什么规律，只要是唯一就行。不过在生成执行计划时， ### TiKV 性能参数调优 -详情参考 [TiKV 性能参数调优](/tune-tikv-memory-performance.md)。 +详情参考 [TiKV 性能参数调优](/tune-tikv-memory-performance.md)。 \ No newline at end of file diff --git a/faq/tidb-faq.md b/faq/tidb-faq.md index 9a17d24a265f..869d6d1b2e88 100644 --- a/faq/tidb-faq.md +++ b/faq/tidb-faq.md @@ -1,7 +1,6 @@ --- title: TiDB 产品常见问题 -aliases: ['/docs-cn/dev/faq/tidb-faq/','/docs-cn/dev/faq/tidb/'] -summary: TiDB 是 PingCAP 公司自主设计、研发的开源分布式关系型数据库，支持在线事务处理与在线分析处理，具备水平扩容、高可用、实时 HTAP、云原生的特性。TiDB 不是基于 MySQL 开发的，而是由 PingCAP 团队完全自主开发的产品。TiDB 易用性很高，支持绝大部分 MySQL 8.0 的语法，但不支持触发器、存储过程、自定义函数等。TiDB 支持分布式事务，兼容 MySQL Client/Driver 的编程语言，支持其他存储引擎，如 TiKV、UniStore 和 MockTiKV。获取 TiDB 知识的途径包括官方文档、官方博客、AskTUG 社区论坛和 PingCAP Education。用户名长度限制为 32 个字符，最大列数为 1017，单行大小不超过 6MB。TiDB 不支持 XA，但支持对列存储引擎的高并发 INSERT 或 UPDATE 操作。 +summary: TiDB 是平凯星辰公司自主设计、研发的开源分布式关系型数据库，支持在线事务处理与在线分析处理，具备水平扩容、高可用、实时 HTAP、云原生的特性。TiDB 不是基于 MySQL 开发的，而是由平凯星辰团队完全自主开发的产品。TiDB 易用性很高，支持绝大部分 MySQL 8.0 的语法，但不支持触发器、存储过程、自定义函数等。TiDB 支持分布式事务，兼容 MySQL Client/Driver 的编程语言，支持其他存储引擎，如 TiKV、UniStore 和 MockTiKV。获取 TiDB 知识的途径包括官方文档、官方博客、AskTUG 社区论坛和 PingCAP Education。用户名长度限制为 32 个字符，最大列数为 1017，单行大小不超过 6MB。TiDB 不支持 XA，但支持对列存储引擎的高并发 INSERT 或 UPDATE 操作。 --- # TiDB 产品常见问题 @@ -10,7 +9,7 @@ summary: TiDB 是 PingCAP 公司自主设计、研发的开源分布式关系型 ### 1.1.1 TiDB 是什么？ -[TiDB](https://github.com/pingcap/tidb) 是 [PingCAP](https://pingcap.com/about-cn/) 公司自主设计、研发的开源分布式关系型数据库，是一款同时支持在线事务处理与在线分析处理 (Hybrid Transactional and Analytical Processing, HTAP) 的融合型分布式数据库产品，具备水平扩容或者缩容、金融级高可用、实时 HTAP、云原生的分布式数据库、兼容 MySQL 协议和 MySQL 生态等重要特性。目标是为用户提供一站式 OLTP (Online Transactional Processing)、OLAP (Online Analytical Processing)、HTAP 解决方案。TiDB 适合高可用、强一致要求较高、数据规模较大等各种应用场景。更多详细信息，请参阅 [TiDB 简介](/overview.md)。 +[TiDB](https://github.com/pingcap/tidb) 是[平凯星辰](https://pingkai.cn/about)公司自主设计、研发的开源分布式关系型数据库，是一款同时支持在线事务处理与在线分析处理 (Hybrid Transactional and Analytical Processing, HTAP) 的融合型分布式数据库产品，具备水平扩容或者缩容、金融级高可用、实时 HTAP、云原生的分布式数据库、兼容 MySQL 协议和 MySQL 生态等重要特性。目标是为用户提供一站式 OLTP (Online Transactional Processing)、OLAP (Online Analytical Processing)、HTAP 解决方案。TiDB 适合高可用、强一致要求较高、数据规模较大等各种应用场景。更多详细信息，请参阅 [TiDB 简介](/overview.md)。 ### 1.1.2 TiDB 整体架构 @@ -74,9 +73,9 @@ Usage of ./bin/tidb-server: ### 1.1.10 除了官方文档，有没有其他 TiDB 知识获取途径？ - [官方文档](https://docs.pingcap.com/zh/)：获取 TiDB 相关知识最主要、最及时的途径。 -- [官方博客](https://cn.pingcap.com/blog/)：了解产品技术解读、观点洞察、案例实践。 +- [博客文章](https://tidb.net/blog)：了解产品技术解读、观点洞察、案例实践。 - [AskTUG 社区论坛](https://asktug.com)：与社区用户、技术专家互动交流。 -- [PingCAP Education](https://cn.pingcap.com/education/)：学习线上课程，获得数据库能力认证。 +- [视频课程](https://learn.pingcap.cn/learner/course)：学习线上课程，获得数据库能力认证。 ### 1.1.11 TiDB 用户名长度限制？ @@ -110,12 +109,12 @@ TiFlash 默认保持数据强一致性。Raft Learner 流程会更新数据。 ### 1.2.1 存储 TiKV 详细解读 -[三篇文章了解 TiDB 技术内幕 - 说存储](https://cn.pingcap.com/blog/tidb-internal-1) +[三篇文章了解 TiDB 技术内幕 - 说存储](https://tidb.net/blog/dbe4f467) ### 1.2.2 计算 TiDB 详细解读 -[三篇文章了解 TiDB 技术内幕 - 说计算](https://cn.pingcap.com/blog/tidb-internal-2) +[三篇文章了解 TiDB 技术内幕 - 说计算](https://tidb.net/blog/8427565a) ### 1.2.3 调度 PD 详细解读 -[三篇文章了解 TiDB 技术内幕 - 谈调度](https://cn.pingcap.com/blog/tidb-internal-3) +[三篇文章了解 TiDB 技术内幕 - 谈调度](https://tidb.net/blog/a558961f) diff --git a/faq/upgrade-faq.md b/faq/upgrade-faq.md index bab9edfb403a..addc0726724c 100644 --- a/faq/upgrade-faq.md +++ b/faq/upgrade-faq.md @@ -1,7 +1,6 @@ --- title: 升级与升级后常见问题 summary: TiDB 升级与升级后的常见问题与解决办法。 -aliases: ['/docs-cn/dev/faq/upgrade-faq/','/docs-cn/dev/faq/upgrade/'] --- # 升级与升级后常见问题 @@ -36,6 +35,12 @@ aliases: ['/docs-cn/dev/faq/upgrade-faq/','/docs-cn/dev/faq/upgrade/'] 本小节列出了一些升级后可能会遇到的问题与解决办法。 +### TiDB 升级后 JDBC 连接的排序规则变化问题 + +当从较低版本升级到 v7.4 或更高版本时，如果 JDBC URL 中未配置 `connectionCollation`，且 `characterEncoding` 未配置或配置为 `UTF-8`，升级后 JDBC 连接的默认排序规则可能会从 `utf8mb4_bin` 变更为 `utf8mb4_0900_ai_ci`。如需保持排序规则为 `utf8mb4_bin`，请在 JDBC URL 中配置 `connectionCollation=utf8mb4_bin`。 + +更多信息，请参考 [JDBC 连接所使用的排序规则](/faq/sql-faq.md#jdbc-连接所使用的排序规则)。 + ### 执行 DDL 操作时遇到的字符集 (charset) 问题 TiDB 在 v2.1.0 以及之前版本（包括 v2.0 所有版本）中，默认字符集是 UTF8。从 v2.1.1 开始，默认字符集变更为 UTF8MB4。如果在 v2.1.0 及之前版本中，建表时显式指定了 table 的 charset 为 UTF8，那么升级到 v2.1.1 之后，执行 DDL 操作可能会失败。 diff --git a/follower-read.md b/follower-read.md index d6d1f515a30d..f3b9c0717059 100644 --- a/follower-read.md +++ b/follower-read.md @@ -1,20 +1,30 @@ --- title: Follower Read summary: 了解 Follower Read 的使用与实现。 -aliases: ['/docs-cn/dev/follower-read/','/docs-cn/dev/reference/performance/follower-read/'] --- # Follower Read -当系统中存在读取热点 Region 导致 leader 资源紧张成为整个系统读取瓶颈时，启用 Follower Read 功能可明显降低 leader 的负担，并且通过在多个 follower 之间均衡负载，显著地提升整体系统的吞吐能力。本文主要介绍 Follower Read 的使用方法与实现机制。 +在 TiDB 中，为了保证高可用和数据安全，TiKV 会为每个 Region 保存多个副本，其中一个为 leader，其余为 follower。默认情况下，所有读写请求都由 leader 处理。Follower Read 功能允许在保持强一致性的前提下，从 Region 的 follower 副本读取数据，从而分担 leader 的读取压力，提升集群整体的读吞吐量。 -## 概述 +在执行 Follower Read 时，TiDB 会根据拓扑信息选择合适的副本。具体来说，TiDB 使用 `zone` label 判断一个副本是否为本地副本：当 TiDB 与目标 TiKV 的 `zone` label 相同时，TiDB 认为该副本是本地副本。更多信息参见[通过拓扑 label 进行副本调度](/schedule-replicas-by-topology-labels.md)。 -Follower Read 功能是指在强一致性读的前提下使用 Region 的 follower 副本来承载数据读取的任务，从而提升 TiDB 集群的吞吐能力并降低 leader 负载。Follower Read 包含一系列将 TiKV 读取负载从 Region 的 leader 副本上 offload 到 follower 副本的负载均衡机制。TiKV 的 Follower Read 可以保证数据读取的一致性，可以为用户提供强一致的数据读取能力。 +通过让 follower 参与数据读取，Follower Read 可以实现以下目标： + +- 分散读热点，减轻 leader 负载。 +- 在多可用区或多机房部署中，优先读取本地副本以减少跨区流量。 + +## 适用场景 + +Follower Read 适用于以下场景： + +- 读请求量大、存在明显读热点的业务。 +- 多可用区部署中，希望优先读取本地副本以节省带宽的场景。 +- 在读写分离架构下，希望进一步提升集群整体读性能的场景。 > **注意：** > -> 为了获得强一致读取的能力，在当前的实现中，follower 节点需要向 leader 节点询问当前的执行进度（即 `ReadIndex`），这会产生一次额外的网络请求开销，因此目前 Follower Read 的主要优势是将集群中的读请求与写请求隔离开，并提升整体的读吞吐量。 +> 为确保读取结果的强一致性，Follower Read 在读取前会与 leader 通信以确认当前的提交进度（即执行 Raft `ReadIndex` 操作），该过程会带来一次额外的网络交互。因此，当业务中存在大量读请求或需要读写隔离时，Follower Read 的效果最为显著；但对于低延迟的单次查询，性能提升可能不明显。 ## 使用方式 @@ -30,34 +40,82 @@ set [session | global] tidb_replica_read = '<目标值>'; 默认值：leader -该变量用于设置期待的数据读取方式。 +该变量用于设置期待的数据读取方式。从 v8.5.4 开始，该变量仅对只读 SQL 语句生效。 + +在需要通过读取本地副本以减少跨区流量的场景下，推荐如下配置： + +- `leader`：默认值，提供最佳性能。 +- `closest-adaptive`：在最小性能损失的前提下，尽可能节省跨区流量。 +- `closest-replicas`：可最大限度地节省跨区流量，但可能带来一定的性能损耗。 + +如果当前正在使用其他配置，可参考下表修改为推荐配置： + +| 当前配置 | 推荐配置 | +| ------------- | ------------- | +| `follower` | `closest-replicas` | +| `leader-and-follower` | `closest-replicas` | +| `prefer-leader` | `closest-adaptive` | +| `learner` | `closest-replicas` | + +如果希望使用更精确的读副本选择策略，请参考完整的可选配置列表： - 当设置为默认值 `leader` 或者空字符串时，TiDB 会维持原有行为方式，将所有的读取操作都发送给 leader 副本处理。 -- 当设置为 `follower` 时，TiDB 会选择 Region 的 follower 副本完成所有的数据读取操作。 -- 当设置为 `leader-and-follower` 时，TiDB 可以选择任意副本来执行读取操作，此时读请求会在 leader 和 follower 之间负载均衡。 +- 当设置为 `follower` 时，TiDB 会选择 Region 的 follower 副本完成所有的数据读取操作。当 Region 存在 learner 副本时，TiDB 也会考虑从 learner 副本读取数据，此时 follower 副本和 learner 副本具有相同优先级。若当前 Region 无可用的 follower 副本或 learner 副本，TiDB 会从 leader 副本读取数据。 +- 当设置为 `leader-and-follower` 时，TiDB 可以选择任意副本来执行读取操作，此时读请求会在 leader、follower 和 learner 之间负载均衡。 - 当设置为 `prefer-leader` 时，TiDB 会优先选择 leader 副本执行读取操作。当 leader 副本的处理速度明显变慢时，例如由于磁盘或网络性能抖动，TiDB 将选择其他可用的 follower 副本来执行读取操作。 -- 当设置为 `closest-replicas` 时，TiDB 会优先选择分布在同一可用区的副本执行读取操作，对应的副本可以是 leader 或 follower。如果同一可用区内没有副本分布，则会从 leader 执行读取。 +- 当设置为 `closest-replicas` 时，TiDB 会优先选择分布在同一可用区的副本执行读取操作，对应的副本可以是 leader、follower 或 learner。如果同一可用区内没有副本分布，则会从 leader 执行读取。 - 当设置为 `closest-adaptive` 时： - 当一个读请求的预估返回结果大于或等于变量 [`tidb_adaptive_closest_read_threshold`](/system-variables.md#tidb_adaptive_closest_read_threshold-从-v630-版本开始引入) 的值时，TiDB 会优先选择分布在同一可用区的副本执行读取操作。此时，为了避免读流量在各个可用区分布不均衡，TiDB 会动态检测当前在线的所有 TiDB 和 TiKV 的可用区数量分布，在每个可用区中 `closest-adaptive` 配置实际生效的 TiDB 节点数总是与包含 TiDB 节点最少的可用区中的 TiDB 节点数相同，并将其他多出的 TiDB 节点自动切换为读取 leader 副本。例如，如果 TiDB 分布在 3 个可用区，其中 A 和 B 两个可用区各包含 3 个 TiDB 节点，C 可用区只包含 2 个 TiDB 节点，那么每个可用区中 `closest-adaptive` 实际生效的 TiDB 节点数为 2，A 和 B 可用区中各有 1 个节点自动被切换为读取 leader 副本。 - 当一个读请求的预估返回结果小于变量 [`tidb_adaptive_closest_read_threshold`](/system-variables.md#tidb_adaptive_closest_read_threshold-从-v630-版本开始引入) 的值时，TiDB 会选择 leader 副本执行读取操作。 -- 当设置为 `learner` 时，TiDB 会选择 learner 副本执行读取操作。在读取时，如果当前 Region 没有 learner 副本，TiDB 会报错。 +- 当设置为 `learner` 时，TiDB 会选择 learner 副本执行读取操作。在读取时，如果当前 Region 没有 learner 副本或 learner 副本不可用，TiDB 会从可用 leader 或 follower 副本读取数据。 > **注意：** > -> 当设置为 `closest-replicas` 或 `closest-adaptive` 时，你需要配置集群以确保副本按照指定的设置分布在各个可用区。请参考[通过拓扑 label 进行副本调度](/schedule-replicas-by-topology-labels.md)为 PD 配置 `location-labels` 并为 TiDB 和 TiKV 设置正确的 `labels`。TiDB 依赖 `zone` 标签匹配位于同一可用区的 TiKV，因此请**务必**在 PD 的 `location-labels` 配置中包含 `zone` 并确保每个 TiDB 和 TiKV 节点的 `labels` 配置中包含 `zone`。如果是使用 TiDB Operator 部署的集群，请参考[数据的高可用](https://docs.pingcap.com/zh/tidb-in-kubernetes/v1.4/configure-a-tidb-cluster#%E6%95%B0%E6%8D%AE%E7%9A%84%E9%AB%98%E5%8F%AF%E7%94%A8)进行配置。 +> 当 `tidb_replica_read` 设置为 `closest-replicas` 或 `closest-adaptive` 时，为了确保副本按照指定的设置分布在各个可用区，请参考[通过拓扑 label 进行副本调度](/schedule-replicas-by-topology-labels.md)为 PD 配置 `location-labels` 并为 TiDB 和 TiKV 设置正确的 `labels`。TiDB 依赖 `zone` 标签匹配位于同一可用区的 TiKV，因此请**务必**在 PD 的 `location-labels` 配置中包含 `zone` 并确保每个 TiDB 和 TiKV 节点的 `labels` 配置中包含 `zone`。如果是使用 TiDB Operator 部署的集群，请参考[数据的高可用](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/configure-a-tidb-cluster/#数据的高可用)进行配置。 +> +> 对于 v7.5.0 及之前的 TiDB 版本： +> +> - 当 `tidb_replica_read` 设置为 `follower` 且无可用 follower 副本及 learner 副本时，TiDB 会报错。 +> - 当 `tidb_replica_read` 设置为 `learner` 且无可用 learner 副本时，TiDB 会报错。 + +## 基本监控 + +通过观察 [**TiDB** > **KV Request** > **Read Req Traffic** 面板（从 v8.5.4 开始引入）](/grafana-tidb-dashboard.md#kv-request)，可以帮助判断是否需要使用 Follower Read 以及开启 Follower Read 后查看节省流量的效果。 ## 实现机制 在 Follower Read 功能出现之前，TiDB 采用 strong leader 策略将所有的读写操作全部提交到 Region 的 leader 节点上完成。虽然 TiKV 能够很均匀地将 Region 分散到多个物理节点上，但是对于每一个 Region 来说，只有 leader 副本能够对外提供服务，另外的 follower 除了时刻同步数据准备着 failover 时投票切换成为 leader 外，没有办法对 TiDB 的请求提供任何帮助。 -为了允许在 TiKV 的 follower 节点进行数据读取，同时又不破坏线性一致性和 Snapshot Isolation 的事务隔离，Region 的 follower 节点需要使用 Raft `ReadIndex` 协议确保当前读请求可以读到当前 leader 上已经 commit 的最新数据。在 TiDB 层面，Follower Read 只需根据负载均衡策略将某个 Region 的读取请求发送到 follower 节点。 +Follower Read 包含一系列将 TiKV 读取负载从 Region 的 leader 副本上 offload 到 follower 副本的负载均衡机制。为了允许在 TiKV 的 follower 节点进行数据读取，同时又不破坏线性一致性和 Snapshot Isolation 的事务隔离，Region 的 follower 节点需要使用 Raft `ReadIndex` 协议确保当前读请求可以读到当前 leader 节点上已经 commit 的最新数据。在 TiDB 层面，Follower Read 只需根据负载均衡策略将某个 Region 的读取请求发送到 follower 节点。 ### Follower 强一致读 -TiKV follower 节点处理读取请求时，首先使用 Raft `ReadIndex` 协议与 Region 当前的 leader 进行一次交互，来获取当前 Raft group 最新的 commit index。本地 apply 到所获取的 leader 最新 commit index 后，便可以开始正常的读取请求处理流程。 +TiKV follower 节点处理读取请求时，首先使用 Raft `ReadIndex` 协议与 Region 当前的 leader 节点进行一次交互，来获取当前 Raft group 最新的 commit index（read index）。本地 apply 到所获取的 leader 节点最新 commit index 后，便可以开始正常的读取请求处理流程。 + +![read-index-flow](/media/follower-read/read-index.png) ### Follower 副本选择策略 -由于 TiKV 的 Follower Read 不会破坏 TiDB 的 Snapshot Isolation 事务隔离级别，因此 TiDB 选择 follower 的策略可以采用 round robin 的方式。目前，对于 Coprocessor 请求，Follower Read 负载均衡策略粒度是连接级别的，对于一个 TiDB 的客户端连接在某个具体的 Region 上会固定使用同一个 follower，只有在选中的 follower 发生故障或者因调度策略发生调整的情况下才会进行切换。而对于非 Coprocessor 请求（点查等），Follower Read 负载均衡策略粒度是事务级别的，对于一个 TiDB 的事务在某个具体的 Region 上会固定使用同一个 follower，同样在 follower 发生故障或者因调度策略发生调整的情况下才会进行切换。如果同一事务内既有点查请求又有 Coprocessor 请求，两种请求都将按照上述调度策略分别进行读取，即使 Coprocessor 和点查出现在同一个 Region 上，TiDB 也会当作独立事件来处理。 +Follower Read 不会破坏 TiDB 的 Snapshot Isolation 事务隔离级别。TiDB 在第一次选取副本时会根据 `tidb_replica_read` 的配置进行选择。从第二次重试开始，TiDB 会优先保证读取成功，因此当选中的 follower 节点出现无法访问的故障或其他错误时，会切换到 leader 提供服务。 + +#### `leader` + +- 选择 leader 副本进行读取，不考虑副本位置。 + +#### `closest-replicas` + +- 当和 TiDB 同一个 AZ 的副本是 leader 节点时，不使用 Follower Read。 +- 当和 TiDB 同一个 AZ 的副本不是 leader 节点时，使用 Follower Read。 + +#### `closest-adaptive` + +- 如果预估的返回结果不够大，使用 `leader` 策略，不进行 Follower Read。 +- 如果预估的返回结果足够大，使用 `closest-replicas` 策略。 + +### Follower Read 的性能开销 + +为了保证数据强一致性，Follower Read 不管读取多少数据，都需要执行一次 `ReadIndex` 操作，这将不可避免地消耗更多的 TiKV CPU 资源。因此，在小查询（如点查）场景下，Follower Read 的性能损耗相对更明显。同时，因为对小查询进行本地读取能节省的流量有限，更推荐在大查询或批量读取场景中使用 Follower Read。 + +当 `tidb_replica_read` 设置为 `closest-adaptive` 时，TiDB 在处理小查询时不会使用 Follower Read。因此，在各种工作负载下，相比于 `leader` 策略，TiKV 的额外 CPU 开销通常不超过 10%。 diff --git a/functions-and-operators/aggregate-group-by-functions.md b/functions-and-operators/aggregate-group-by-functions.md index 51376e6426c5..d097a473a7b2 100644 --- a/functions-and-operators/aggregate-group-by-functions.md +++ b/functions-and-operators/aggregate-group-by-functions.md @@ -1,6 +1,5 @@ --- title: GROUP BY 聚合函数 -aliases: ['/docs-cn/dev/functions-and-operators/aggregate-group-by-functions/','/docs-cn/dev/reference/sql/functions-and-operators/aggregate-group-by-functions/'] summary: TiDB支持的聚合函数包括 COUNT、COUNT(DISTINCT)、SUM、AVG、MAX、MIN、GROUP_CONCAT、VARIANCE、VAR_POP、STD、STDDEV、VAR_SAMP、STDDEV_SAMP 和 JSON_OBJECTAGG。除了 GROUP_CONCAT 和 APPROX_PERCENTILE 外，这些聚合函数可以作为窗口函数使用。另外，TiDB 的 GROUP BY 子句支持 WITH ROLLUP 修饰符，还支持 SQL 模式 ONLY_FULL_GROUP_BY。与 MySQL 的区别在于 TiDB 对标准 SQL 有一些扩展，允许在 HAVING 子句中使用别名和非列表达式。 --- @@ -62,7 +61,33 @@ TiDB 支持的 MySQL `GROUP BY` 聚合函数如下所示： 1 row in set (0.00 sec) ``` -上述聚合函数除 `GROUP_CONCAT()` 和 `APPROX_PERCENTILE()` 以外，均可作为[窗口函数](/functions-and-operators/window-functions.md)使用。 ++ `APPROX_COUNT_DISTINCT(expr, [expr...])` + + 该函数的功能与 `COUNT(DISTINCT)` 相似，用于统计不同值的数量，但返回的是一个近似值。它采用 `BJKST` 算法，在处理具有幂律分布特征的大规模数据集时，可以显著降低内存消耗。此外，对于低基数 (low cardinality) 的数据，该函数的结果准确性较高，同时对 CPU 的使用效率也较优。 + + 以下是一个使用该函数的示例： + + ```sql + DROP TABLE IF EXISTS t; + CREATE TABLE t(a INT, b INT, c INT); + INSERT INTO t VALUES(1, 1, 1), (2, 1, 1), (2, 2, 1), (3, 1, 1), (5, 1, 2), (5, 1, 2), (6, 1, 2), (7, 1, 2); + ``` + + ```sql + SELECT APPROX_COUNT_DISTINCT(a, b) FROM t GROUP BY c; + ``` + + ``` + +-----------------------------+ + | approx_count_distinct(a, b) | + +-----------------------------+ + | 3 | + | 4 | + +-----------------------------+ + 2 rows in set (0.00 sec) + ``` + +上述聚合函数除 `GROUP_CONCAT()`、 `APPROX_PERCENTILE()` 和 `APPROX_COUNT_DISTINCT` 以外，均可作为[窗口函数](/functions-and-operators/window-functions.md)使用。 ## GROUP BY 修饰符 diff --git a/functions-and-operators/bit-functions-and-operators.md b/functions-and-operators/bit-functions-and-operators.md index 0b7c7e261adc..72b74e86e903 100644 --- a/functions-and-operators/bit-functions-and-operators.md +++ b/functions-and-operators/bit-functions-and-operators.md @@ -1,6 +1,5 @@ --- title: 位函数和操作符 -aliases: ['/docs-cn/dev/functions-and-operators/bit-functions-and-operators/','/docs-cn/dev/reference/sql/functions-and-operators/bit-functions-and-operators/'] summary: TiDB 支持 MySQL 8.0 中的所有位函数和操作符。 --- @@ -20,7 +19,7 @@ TiDB 支持使用 MySQL 8.0 中提供的所有[位函数和操作符](https://de | [`<<`](#左移) | 左移 | | [`>>`](#右移) | 右移 | -## [`BIT_COUNT()`](https://dev.mysql.com/doc/refman/8.0/en/bit-functions.html#function_bit-count) +## `BIT_COUNT()` `BIT_COUNT(expr)` 函数返回 `expr` 中为 1 的位数。 @@ -71,7 +70,7 @@ SELECT BIT_COUNT(INET_ATON('255.255.255.0')); 1 row in set (0.00 sec) ``` -## [`&`（按位与）](https://dev.mysql.com/doc/refman/8.0/en/bit-functions.html#operator_bitwise-and) +## `&`（按位与） `&` 操作符用于执行按位与 (bitwise AND) 操作。它会比较两个数中的对应位，如果两个对应位都是 1，则结果中的对应位为 1，否则为 0。 @@ -129,7 +128,7 @@ SELECT INET_NTOA(INET_ATON('192.168.1.2') & INET_ATON('255.255.255.0')); 1 row in set (0.00 sec) ``` -## [`~`（按位取反）](https://dev.mysql.com/doc/refman/8.0/en/bit-functions.html#operator_bitwise-invert) +## `~`（按位取反） `~` 操作符用于对给定的值进行按位取反（bitwise NOT）操作。它会对给定值中的每一位进行取反：0 的位变为 1，1 的位变为 0。 @@ -169,7 +168,7 @@ SELECT CONV(~ b'1111111111111111111111111111111111111111111111110000111100001111 1 row in set (0.00 sec) ``` -## [`|`（按位或）](https://dev.mysql.com/doc/refman/8.0/en/bit-functions.html#operator_bitwise-or) +## `|`（按位或） `|` 操作符用于执行按位或 (bitwise OR) 操作。它会比较两个数中的对应位，如果至少有一个对应位为 1，则结果中的对应位为 1。 @@ -197,7 +196,7 @@ SELECT CONV(b'1010' | b'1100',10,2); 1 row in set (0.00 sec) ``` -## [`^`（按位异或）](https://dev.mysql.com/doc/refman/8.0/en/bit-functions.html#operator_bitwise-xor) +## `^`（按位异或） `^` 操作符用于执行按位异或 (bitwise XOR) 操作。它会比较两个数中的对应位，如果对应位不同，则结果中的对应位为 1。 @@ -227,7 +226,7 @@ SELECT CONV(b'1010' ^ b'1100',10,2); 需要注意的是，由于省略了前导零，结果会显示为 `110` 而不是 `0110`。 -## [`<<`（左移）](https://dev.mysql.com/doc/refman/8.0/en/bit-functions.html#operator_left-shift) +## `<<`（左移） `<<` 操作符用于执行左移操作。它会将一个数中的所有位向左移动指定的位数，并用零填充右侧空出的位。 @@ -261,7 +260,7 @@ SELECT n,1<>`（右移）](https://dev.mysql.com/doc/refman/8.0/en/bit-functions.html#operator_right-shift) +## `>>`（右移） `>>` 操作符用于执行右移操作。它会将数中的所有位向右移动指定的位数，并用零填充左侧空出的位。 diff --git a/functions-and-operators/cast-functions-and-operators.md b/functions-and-operators/cast-functions-and-operators.md index 623ac9b475aa..af389717dccc 100644 --- a/functions-and-operators/cast-functions-and-operators.md +++ b/functions-and-operators/cast-functions-and-operators.md @@ -1,6 +1,5 @@ --- title: Cast 函数和操作符 -aliases: ['/docs-cn/dev/functions-and-operators/cast-functions-and-operators/','/docs-cn/dev/reference/sql/functions-and-operators/cast-functions-and-operators/'] summary: Cast 函数和操作符用于将某种数据类型的值转换为另一种数据类型。TiDB 支持使用 MySQL 8.0 中提供的所有 Cast 函数和操作符。 --- @@ -46,6 +45,7 @@ Cast 函数和操作符用于将某种数据类型的值转换为另一种数据 | `SIGNED [INTEGER]` | 有符号整数 | 是 | | `TIME(fsp)` | 时间 | 是 | | `UNSIGNED [INTEGER]` | 无符号整数 | 是 | +| `VECTOR` | 向量 | 否 | | `YEAR` | 年 | 否 | 示例： diff --git a/functions-and-operators/control-flow-functions.md b/functions-and-operators/control-flow-functions.md index 1e859f1bb6fb..e75c232a5201 100644 --- a/functions-and-operators/control-flow-functions.md +++ b/functions-and-operators/control-flow-functions.md @@ -1,6 +1,5 @@ --- title: 控制流程函数 -aliases: ['/docs-cn/dev/functions-and-operators/control-flow-functions/','/docs-cn/dev/reference/sql/functions-and-operators/control-flow-functions/'] summary: TiDB 支持 MySQL 8.0 中的控制流程函数，包括 CASE、IF()、IFNULL() 和 NULLIF()。这些函数可以用于构建 if/else 语句和处理 NULL 值。 --- diff --git a/functions-and-operators/date-and-time-functions.md b/functions-and-operators/date-and-time-functions.md index e56ccb8a9edd..44738f858326 100644 --- a/functions-and-operators/date-and-time-functions.md +++ b/functions-and-operators/date-and-time-functions.md @@ -1,6 +1,5 @@ --- title: 日期和时间函数 -aliases: ['/docs-cn/dev/functions-and-operators/date-and-time-functions/','/docs-cn/dev/reference/sql/functions-and-operators/date-and-time-functions/'] summary: TiDB 支持 MySQL 8.0 中的所有日期和时间函数。 --- diff --git a/functions-and-operators/encryption-and-compression-functions.md b/functions-and-operators/encryption-and-compression-functions.md index 06ac2b27071a..ea7f56579864 100644 --- a/functions-and-operators/encryption-and-compression-functions.md +++ b/functions-and-operators/encryption-and-compression-functions.md @@ -1,6 +1,5 @@ --- title: 加密和压缩函数 -aliases: ['/docs-cn/dev/functions-and-operators/encryption-and-compression-functions/','/docs-cn/dev/reference/sql/functions-and-operators/encryption-and-compression-functions/'] summary: TiDB 支持 MySQL 8.0 中提供的大部分加密和压缩函数。 --- @@ -26,7 +25,7 @@ TiDB 支持使用 MySQL 8.0 中提供的大部分[加密和压缩函数](https:/ | [`UNCOMPRESSED_LENGTH()`](#uncompressed_length) | 返回字符串压缩前的长度 | | [`VALIDATE_PASSWORD_STRENGTH()`](#validate_password_strength) | 计算密码强度 | -### [`AES_DECRYPT()`](https://dev.mysql.com/doc/refman/8.0/en/encryption-functions.html#function_aes-decrypt) +### `AES_DECRYPT()` `AES_DECRYPT(data, key [,iv])` 函数使用相同的 `key` 解密之前由 [`AES_ENCRYPT()`](#aes_encrypt) 函数加密的 `data`。 @@ -47,7 +46,7 @@ SELECT AES_DECRYPT(0x28409970815CD536428876175F1A4923, 'secret'); 1 row in set (0.00 sec) ``` -### [`AES_ENCRYPT()`](https://dev.mysql.com/doc/refman/8.0/en/encryption-functions.html#function_aes-encrypt) +### `AES_ENCRYPT()` `AES_ENCRYPT(data, key [,iv])` 函数使用[高级加密标准 (AES)](https://zh.wikipedia.org/wiki/高级加密标准) 算法和 `key` 加密 `data`。 @@ -68,7 +67,7 @@ SELECT AES_ENCRYPT(0x616263,'secret'); 1 row in set (0.00 sec) ``` -### [`COMPRESS()`](https://dev.mysql.com/doc/refman/8.0/en/encryption-functions.html#function_compress) +### `COMPRESS()` `COMPRESS(expr)` 函数返回输入参数 `expr` 的压缩版本。 @@ -122,7 +121,7 @@ SELECT LENGTH(a),LENGTH(COMPRESS(a)) FROM x; 1 row in set (0.00 sec) ``` -### [`MD5()`](https://dev.mysql.com/doc/refman/8.0/en/encryption-functions.html#function_md5) +### `MD5()` `MD5(expr)` 函数为给定参数 `expr` 计算 128 位 [MD5](https://zh.wikipedia.org/wiki/MD5) 哈希值。 @@ -139,7 +138,7 @@ SELECT MD5('abc'); 1 row in set (0.00 sec) ``` -### [`PASSWORD()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_password) +### `PASSWORD()` > **警告：** > @@ -162,7 +161,7 @@ SELECT PASSWORD('secret'); Warning (Code 1681): PASSWORD is deprecated and will be removed in a future release. ``` -### [`RANDOM_BYTES()`](https://dev.mysql.com/doc/refman/8.0/en/encryption-functions.html#function_random-bytes) +### `RANDOM_BYTES()` `RANDOM_BYTES(n)` 函数返回 `n` 个随机字节。 @@ -179,11 +178,11 @@ SELECT RANDOM_BYTES(3); 1 row in set (0.00 sec) ``` -### [`SHA()`](https://dev.mysql.com/doc/refman/8.0/en/encryption-functions.html#function_sha1) +### `SHA()` `SHA()` 函数是 [`SHA1`](#sha1) 的别名。 -### [`SHA1()`](https://dev.mysql.com/doc/refman/8.0/en/encryption-functions.html#function_sha1) +### `SHA1()` `SHA1(expr)` 函数为给定参数 `expr` 计算 160 位 [SHA-1](https://zh.wikipedia.org/wiki/SHA-1) 哈希值。 @@ -200,7 +199,7 @@ SELECT SHA1('abc'); 1 row in set (0.00 sec) ``` -### [`SHA2()`](https://dev.mysql.com/doc/refman/8.0/en/encryption-functions.html#function_sha2) +### `SHA2()` `SHA2(str, n)` 函数使用 [SHA-2](https://zh.wikipedia.org/wiki/SHA-2) 系列中的算法计算哈希值。参数 `n` 用于选择算法。如果任一参数为 `NULL` 或 `n` 指定的算法未知或不受支持，`SHA2()` 返回 `NULL`。 @@ -248,7 +247,7 @@ SELECT SM3('abc'); 1 row in set (0.00 sec) ``` -### [`UNCOMPRESS()`](https://dev.mysql.com/doc/refman/8.0/en/encryption-functions.html#function_uncompress) +### `UNCOMPRESS()` `UNCOMPRESS(data)` 函数解压缩使用 [`COMPRESS()`](#compress) 函数压缩的数据。 @@ -265,7 +264,7 @@ SELECT UNCOMPRESS(0x03000000789C72747206040000FFFF018D00C7); 1 row in set (0.00 sec) ``` -### [`UNCOMPRESSED_LENGTH()`](https://dev.mysql.com/doc/refman/8.0/en/encryption-functions.html#function_uncompressed-length) +### `UNCOMPRESSED_LENGTH()` `UNCOMPRESSED_LENGTH(data)` 函数返回压缩数据的前 4 个字节，即字符串在使用 [`COMPRESS()`](#compress) 函数压缩之前的长度。 @@ -282,7 +281,7 @@ SELECT UNCOMPRESSED_LENGTH(0x03000000789C72747206040000FFFF018D00C7); 1 row in set (0.00 sec) ``` -### [`VALIDATE_PASSWORD_STRENGTH()`](https://dev.mysql.com/doc/refman/8.0/en/encryption-functions.html#function_validate-password-strength) +### `VALIDATE_PASSWORD_STRENGTH()` `VALIDATE_PASSWORD_STRENGTH(str)` 函数用作 [TiDB 密码管理](/password-management.md)的一部分，它计算密码的强度并返回一个 0 到 100 之间的整数值。 diff --git a/functions-and-operators/expressions-pushed-down.md b/functions-and-operators/expressions-pushed-down.md index be5f51a50ed7..7d74e78b9741 100644 --- a/functions-and-operators/expressions-pushed-down.md +++ b/functions-and-operators/expressions-pushed-down.md @@ -1,7 +1,6 @@ --- title: 下推到 TiKV 的表达式列表 summary: TiDB 中下推到 TiKV 的表达式列表及相关设置。 -aliases: ['/docs-cn/dev/functions-and-operators/expressions-pushed-down/','/docs-cn/dev/reference/sql/functions-and-operators/expressions-pushed-down/'] --- # 下推到 TiKV 的表达式列表 diff --git a/functions-and-operators/functions-and-operators-overview.md b/functions-and-operators/functions-and-operators-overview.md index 88ecad48bc64..a5585229c03e 100644 --- a/functions-and-operators/functions-and-operators-overview.md +++ b/functions-and-operators/functions-and-operators-overview.md @@ -1,6 +1,5 @@ --- title: 函数和操作符概述 -aliases: ['/docs-cn/dev/functions-and-operators/functions-and-operators-overview/','/docs-cn/dev/reference/sql/functions-and-operators/reference/'] summary: TiDB 中的函数和操作符使用方法与 MySQL 基本一致。在 SQL 语句中，表达式可用于诸如 SELECT 语句的 ORDER BY 或 HAVING 子句，SELECT/DELETE/UPDATE 语句的 WHERE 子句，或 SET 语句之类的地方。可使用字面值，列名，NULL，内置函数，操作符等来书写表达式。其中有些表达式下推到 TiKV 上执行，详见下推到 TiKV 的表达式列表。 --- diff --git a/functions-and-operators/information-functions.md b/functions-and-operators/information-functions.md index 17d15bd840e5..1976af6e78e1 100644 --- a/functions-and-operators/information-functions.md +++ b/functions-and-operators/information-functions.md @@ -1,6 +1,5 @@ --- title: 信息函数 -aliases: ['/docs-cn/dev/functions-and-operators/information-functions/','/docs-cn/dev/reference/sql/functions-and-operators/information-functions/'] summary: TiDB 支持 MySQL 8.0 中提供的大部分信息函数。 --- @@ -193,10 +192,12 @@ TABLE t1; > **注意** > -> - 在 TiDB 中，[`AUTO_ID_CACHE`](/auto-increment.md#auto_id_cache) 可能会导致该函数的返回结果与 MySQL 不同。这是因为 TiDB 在每个节点上都会各自缓存 ID，这可能导致分配的 ID 出现无序或间隔。如果你的应用程序依赖于严格的 ID 顺序，可以启用 [MySQL 兼容模式](/auto-increment.md#mysql-兼容模式)。 +> - 在 TiDB 中，[`AUTO_ID_CACHE`](/auto-increment.md#auto_id_cache) 可能会导致该函数的返回结果与 MySQL 不同。这是因为 TiDB 在每个节点上都会各自缓存 ID，这可能导致分配的 ID 出现无序或间隔。如果你的应用程序依赖于严格的 ID 顺序，可以启用[兼容 MySQL 的自增列模式](/auto-increment.md#兼容-mysql-的自增列模式)。 > > - 在以上示例中，ID 是以 2 递增的，而 MySQL 在相同场景中生成的 ID 是以 1 递增的。关于兼容性的更多信息，请参见[自增 ID](/mysql-compatibility.md#自增-id)。 +`LAST_INSERT_ID(expr)` 函数可以接受一个表达式作为参数，并将该值存储以供下一次调用 `LAST_INSERT_ID()` 时使用。你可以使用该函数生成序列，与 MySQL 保持兼容。注意 TiDB 也支持标准的[序列函数](/functions-and-operators/sequence-functions.md)。 + ### ROW_COUNT() `ROW_COUNT()` 函数返回受影响的行数。 diff --git a/functions-and-operators/json-functions.md b/functions-and-operators/json-functions.md index 7e26d5eb2fab..49322e82fe22 100644 --- a/functions-and-operators/json-functions.md +++ b/functions-and-operators/json-functions.md @@ -1,6 +1,5 @@ --- title: JSON 函数 -aliases: ['/docs-cn/dev/functions-and-operators/json-functions/','/docs-cn/dev/reference/sql/functions-and-operators/json-functions/'] summary: TiDB 支持 MySQL 8.0 中提供的大部分 JSON 函数。 --- diff --git a/functions-and-operators/json-functions/json-functions-aggregate.md b/functions-and-operators/json-functions/json-functions-aggregate.md index a419676cc506..d78b623ad1fd 100644 --- a/functions-and-operators/json-functions/json-functions-aggregate.md +++ b/functions-and-operators/json-functions/json-functions-aggregate.md @@ -5,9 +5,11 @@ summary: 了解聚合 JSON 值的 JSON 函数。 # 聚合 JSON 值的 JSON 函数 -本文档介绍 TiDB [聚合函数](/functions-and-operators/aggregate-group-by-functions.md) 中专门用于处理 JSON 的聚合函数。 +本文档介绍 TiDB [聚合函数](/functions-and-operators/aggregate-group-by-functions.md)中专门用于处理 JSON 的聚合函数。 -## [JSON_ARRAYAGG()](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_json-arrayagg) +TiDB 支持使用 MySQL 8.0 中提供的[两个 JSON 聚合函数](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html)。 + +## `JSON_ARRAYAGG()` `JSON_ARRAYAGG(key)` 函数可以根据给定的 `key` 将 `key` 值聚合到一个 JSON 数组中。`key` 通常为表达式或列名。 @@ -28,7 +30,7 @@ SELECT JSON_ARRAYAGG(v) FROM (SELECT 1 'v' UNION SELECT 2); 1 row in set (0.00 sec) ``` -## [JSON_OBJECTAGG()](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_json-objectagg) +## `JSON_OBJECTAGG()` `JSON_OBJECTAGG(key,value)` 函数可以根据给定的 `key` 和 `value` 将 `key` 值和 `value` 值聚合成一个 JSON 对象。`key` 和 `value` 通常为表达式或列名。 diff --git a/functions-and-operators/json-functions/json-functions-create.md b/functions-and-operators/json-functions/json-functions-create.md index fc8d3b3faa2f..60a9b52aead0 100644 --- a/functions-and-operators/json-functions/json-functions-create.md +++ b/functions-and-operators/json-functions/json-functions-create.md @@ -5,9 +5,9 @@ summary: 了解创建 JSON 值的 JSON 函数。 # 创建 JSON 值的 JSON 函数 -本文档介绍用于创建 JSON 值的 JSON 函数。 +TiDB 支持使用 MySQL 8.0 中提供的所有[用于创建 JSON 值的 JSON 函数](https://dev.mysql.com/doc/refman/8.0/en/json-creation-functions.html)。 -## [JSON_ARRAY()](https://dev.mysql.com/doc/refman/8.0/en/json-creation-functions.html#function_json-array) +## `JSON_ARRAY()` `JSON_ARRAY([val[, val] ...])` 函数接受一个值列表（可能为空）作为参数，并返回一个包含这些值的 JSON 数组。 @@ -24,7 +24,7 @@ SELECT JSON_ARRAY(1,2,3,4,5), JSON_ARRAY("foo", "bar"); 1 row in set (0.00 sec) ``` -## [JSON_OBJECT()](https://dev.mysql.com/doc/refman/8.0/en/json-creation-functions.html#function_json-object) +## `JSON_OBJECT()` `JSON_OBJECT([key,val[,key,val]...])` 函数接受一个键值对列表（可能为空）作为参数，并返回一个包含这些键值对的 JSON 对象。 @@ -41,7 +41,7 @@ SELECT JSON_OBJECT("database", "TiDB", "distributed", TRUE); 1 row in set (0.00 sec) ``` -## [JSON_QUOTE()](https://dev.mysql.com/doc/refman/8.0/en/json-creation-functions.html#function_json-quote) +## `JSON_QUOTE()` `JSON_QUOTE(str)` 函数将字符串返回为带引号的 JSON 值。 diff --git a/functions-and-operators/json-functions/json-functions-modify.md b/functions-and-operators/json-functions/json-functions-modify.md index 2f4f170c5759..c45fc0888ada 100644 --- a/functions-and-operators/json-functions/json-functions-modify.md +++ b/functions-and-operators/json-functions/json-functions-modify.md @@ -5,13 +5,13 @@ summary: 了解修改 JSON 值的 JSON 函数。 # 修改 JSON 值的 JSON 函数 -本文档介绍用于修改 JSON 值的 JSON 函数。 +TiDB 支持使用 MySQL 8.0 中提供的所有[用于修改 JSON 值的 JSON 函数](https://dev.mysql.com/doc/refman/8.0/en/json-modification-functions.html)。 -## [JSON_APPEND()](https://dev.mysql.com/doc/refman/8.0/en/json-modification-functions.html#function_json-append) +## `JSON_APPEND()` 该函数为 [`JSON_ARRAY_APPEND()`](#json_array_append) 的别名。 -## [JSON_ARRAY_APPEND()](https://dev.mysql.com/doc/refman/8.0/en/json-modification-functions.html#function_json-array-append) +## `JSON_ARRAY_APPEND()` `JSON_ARRAY_APPEND(json_array, path, value [,path, value] ...)` 函数将 `value` 插入 `path` 中指定的 `json_array` 数组的末尾，并返回结果。 @@ -49,7 +49,7 @@ SELECT JSON_ARRAY_APPEND('{"transport_options": ["Car", "Boat", "Train"]}', '$.t 1 row in set (0.00 sec) ``` -## [JSON_ARRAY_INSERT()](https://dev.mysql.com/doc/refman/8.0/en/json-modification-functions.html#function_json-array-insert) +## `JSON_ARRAY_INSERT()` `JSON_ARRAY_INSERT(json_array, path, value [,path, value] ...)` 函数将 `value` 插入 `path` 中 `json_array` 的指定位置，并返回结果。 @@ -87,7 +87,7 @@ SELECT JSON_ARRAY_INSERT('["Car", "Boat", "Train"]', '$[1]', "Airplane") AS "Tra 1 row in set (0.00 sec) ``` -## [JSON_INSERT()](https://dev.mysql.com/doc/refman/8.0/en/json-modification-functions.html#function_json-insert) +## `JSON_INSERT()` `JSON_INSERT(json_doc,path,value[,path,value] ...)` 函数将一个或多个值插入到 JSON 文档，并返回结果。 @@ -125,7 +125,7 @@ SELECT JSON_INSERT('{"a": 61, "b": 62}', '$.a', 41, '$.c', 63); 1 row in set (0.00 sec) ``` -## [JSON_MERGE_PATCH()](https://dev.mysql.com/doc/refman/8.0/en/json-modification-functions.html#function_json-merge-patch) +## `JSON_MERGE_PATCH()` `JSON_MERGE_PATCH(json_doc, json_doc [,json_doc] ...)` 将两个或多个 JSON 文档合并为一个 JSON 文档，但不保留重复键的值。如果其中某些 `json_doc` 参数包含重复的键，合并后的结果只保留后面指定的那个 `json_doc` 参数中的值。 @@ -150,7 +150,7 @@ SELECT JSON_MERGE_PATCH( 1 row in set (0.00 sec) ``` -## [JSON_MERGE_PRESERVE()](https://dev.mysql.com/doc/refman/8.0/en/json-modification-functions.html#function_json-merge-preserve) +## `JSON_MERGE_PRESERVE()` `JSON_MERGE_PRESERVE(json_doc, json_doc [,json_doc] ...)` 函数通过保留所有键值的方式合并两个或多个 JSON 文档，并返回合并结果。 @@ -171,7 +171,7 @@ SELECT JSON_MERGE_PRESERVE('{"a": 1, "b": 2}','{"a": 100}', '{"c": 300}'); 1 row in set (0.00 sec) ``` -## [JSON_MERGE()](https://dev.mysql.com/doc/refman/8.0/en/json-modification-functions.html#function_json-merge) +## `JSON_MERGE()` > **警告：** > @@ -179,7 +179,7 @@ SELECT JSON_MERGE_PRESERVE('{"a": 1, "b": 2}','{"a": 100}', '{"c": 300}'); 该函数为 [`JSON_MERGE_PRESERVE()`](#json_merge_preserve) 已废弃的别名。 -## [JSON_REMOVE()](https://dev.mysql.com/doc/refman/8.0/en/json-modification-functions.html#function_json-remove) +## `JSON_REMOVE()` `JSON_REMOVE(json_doc,path [,path] ...)` 函数从 JSON 文档中删除指定 `path` 的数据并返回结果。 @@ -215,7 +215,7 @@ SELECT JSON_REMOVE('{"a": 61, "b": 62, "c": 63}','$.b','$.c'); 1 row in set (0.00 sec) ``` -## [JSON_REPLACE()](https://dev.mysql.com/doc/refman/8.0/en/json-modification-functions.html#function_json-replace) +## `JSON_REPLACE()` `JSON_REPLACE(json_doc,path,value[,path,value]...)` 函数替换 JSON 文档中的现有的值并返回结果。如果指定的路径不存在，该路径对应的值不会添加到结果中。 @@ -253,7 +253,7 @@ SELECT JSON_REPLACE('{"a": 41, "b": 62}','$.b',42,'$.c',43); 1 row in set (0.00 sec) ``` -## [JSON_SET()](https://dev.mysql.com/doc/refman/8.0/en/json-modification-functions.html#function_json-set) +## `JSON_SET()` `JSON_SET(json_doc,path,value[,path,value] ...)` 函数在 JSON 文档中插入或更新数据，并返回结果。 @@ -291,7 +291,7 @@ SELECT JSON_SET('{"version": 1.1, "name": "example"}','$.version',1.2,'$.branch' 1 row in set (0.00 sec) ``` -## [JSON_UNQUOTE()](https://dev.mysql.com/doc/refman/8.0/en/json-modification-functions.html#function_json-unquote) +## `JSON_UNQUOTE()` `JSON_UNQUOTE(json)` 函数去掉 JSON 值的引号，并以字符串形式返回结果。该函数与 [`JSON_QUOTE()`](/functions-and-operators/json-functions/json-functions-create.md#json_quote) 函数作用相反。 diff --git a/functions-and-operators/json-functions/json-functions-return.md b/functions-and-operators/json-functions/json-functions-return.md index 9adb89071d6b..ee849d57570e 100644 --- a/functions-and-operators/json-functions/json-functions-return.md +++ b/functions-and-operators/json-functions/json-functions-return.md @@ -5,9 +5,9 @@ summary: 了解返回 JSON 值的 JSON 函数。 # 返回 JSON 值的 JSON 函数 -本文介绍返回 JSON 值的 JSON 函数。 +TiDB 支持使用 MySQL 8.0 中提供的所有[用于返回 JSON 值属性的 JSON 函数](https://dev.mysql.com/doc/refman/8.0/en/json-attribute-functions.html)。 -## [JSON_DEPTH()](https://dev.mysql.com/doc/refman/8.0/en/json-attribute-functions.html#function_json-depth) +## `JSON_DEPTH()` `JSON_DEPTH(json_doc)` 函数返回 JSON 文档的最大深度。 @@ -32,7 +32,7 @@ SELECT JSON_DEPTH('{"weather": {"current": "sunny"}}'); 1 row in set (0.00 sec) ``` -## [JSON_LENGTH()](https://dev.mysql.com/doc/refman/8.0/en/json-attribute-functions.html#function_json-length) +## `JSON_LENGTH()` `JSON_LENGTH(json_doc [,path])` 函数返回 JSON 文档的长度。如果指定了 `path` 参数，则返回路径中的值的长度。 @@ -68,7 +68,7 @@ SELECT JSON_LENGTH('{"weather": {"current": "sunny", "tomorrow": "cloudy"}}','$. 1 row in set (0.01 sec) ``` -## [JSON_TYPE()](https://dev.mysql.com/doc/refman/8.0/en/json-attribute-functions.html#function_json-type) +## `JSON_TYPE()` `JSON_TYPE(json_val)` 函数返回一个字符串，表示 [JSON 值的类型](/data-type-json.md#json-值的类型)。 @@ -132,7 +132,7 @@ SELECT JSON_TYPE('"2025-06-14"'),JSON_TYPE(CAST(CAST('2025-06-14' AS date) AS js 1 row in set (0.00 sec) ``` -## [JSON_VALID()](https://dev.mysql.com/doc/refman/8.0/en/json-attribute-functions.html#function_json-valid) +## `JSON_VALID()` `JSON_VALID(str)` 函数检查输入的参数是否为有效的 JSON 格式。该函数对于在将列转换为 `JSON` 类型之前进行检查非常有用。 diff --git a/functions-and-operators/json-functions/json-functions-search.md b/functions-and-operators/json-functions/json-functions-search.md index ee9d4e626b61..9cbe6f88e93f 100644 --- a/functions-and-operators/json-functions/json-functions-search.md +++ b/functions-and-operators/json-functions/json-functions-search.md @@ -5,9 +5,9 @@ summary: 了解搜索 JSON 值的 JSON 函数。 # 搜索 JSON 值的 JSON 函数 -本文档介绍用于搜索 JSON 值的 JSON 函数。 +TiDB 支持使用 MySQL 8.0 中提供的大部分[用于搜索 JSON 值的 JSON 函数](https://dev.mysql.com/doc/refman/8.0/en/json-search-functions.html)。 -## [JSON_CONTAINS()](https://dev.mysql.com/doc/refman/8.0/en/json-search-functions.html#function_json-contains) +## `JSON_CONTAINS()` 通过返回 `1` 或 `0`，`JSON_CONTAINS(json_doc, candidate [,path])` 函数用于确认指定的 JSON 文档 `candidate` 是否包含在目标 JSON 文档中。 @@ -88,7 +88,7 @@ SELECT JSON_CONTAINS('{"foo": "bar", "aaa": 5}','"bar"', '$.foo'); 1 row in set (0.00 sec) ``` -## [JSON_CONTAINS_PATH()](https://dev.mysql.com/doc/refman/8.0/en/json-search-functions.html#function_json-contains-path) +## `JSON_CONTAINS_PATH()` `JSON_CONTAINS_PATH(json_doc,all_or_one,path [,path, ...])` 函数返回 `0` 或 `1`，表示 JSON 文档是否包含指定路径下的数据。 @@ -139,7 +139,7 @@ SELECT JSON_CONTAINS_PATH('{"foo": "bar", "aaa": 5}','all','$.foo', '$.aaa'); 1 row in set (0.00 sec) ``` -## [JSON_EXTRACT()](https://dev.mysql.com/doc/refman/8.0/en/json-search-functions.html#function_json-extract) +## `JSON_EXTRACT()` `JSON_EXTRACT(json_doc, path[, path] ...)` 函数从 JSON 文档中提取与 `path` 参数匹配的数据。 @@ -156,7 +156,7 @@ SELECT JSON_EXTRACT('{"foo": "bar", "aaa": 5}', '$.foo'); 1 row in set (0.00 sec) ``` -## [->](https://dev.mysql.com/doc/refman/8.0/en/json-search-functions.html#operator_json-column-path) +## `->` `column->path` 函数返回 `column` 中与 `path` 参数匹配的数据。该函数是 [`JSON_EXTRACT()`](#json_extract) 的别名。 @@ -179,7 +179,7 @@ FROM ( 1 row in set (0.00 sec) ``` -## [->>](https://dev.mysql.com/doc/refman/8.0/en/json-search-functions.html#operator_json-inline-path) +## `->>` `column->>path` 函数去掉 `column` 中与 `path` 参数匹配的数据的引号。它是 `JSON_UNQUOTE(JSON_EXTRACT(doc,path_literal))` 的别名。 @@ -204,7 +204,7 @@ FROM ( 1 row in set (0.00 sec) ``` -## [JSON_KEYS()](https://dev.mysql.com/doc/refman/8.0/en/json-search-functions.html#function_json-keys) +## `JSON_KEYS()` `JSON_KEYS(json_doc [,path])` 函数以 JSON 数组的形式返回 JSON 对象的顶层键 (key)。如果指定了 `path` 参数，则返回所选路径的顶层键 (key)。 @@ -240,7 +240,7 @@ SELECT JSON_KEYS('{"name": {"first": "John", "last": "Doe"}, "type": "Person"}', 1 row in set (0.00 sec) ``` -## [JSON_SEARCH()](https://dev.mysql.com/doc/refman/8.0/en/json-search-functions.html#function_json-search) +## `JSON_SEARCH()` `JSON_SEARCH(json_doc,one_or_all,str)` 函数会在 JSON 文档中搜索与字符串匹配的一个或所有的匹配项。 @@ -276,7 +276,7 @@ SELECT JSON_SEARCH('{"a": ["aa", "bb", "cc"], "b": ["cc", "dd"]}','all','cc'); 1 row in set (0.01 sec) ``` -## [MEMBER OF()](https://dev.mysql.com/doc/refman/8.0/en/json-search-functions.html#operator_member-of) +## `MEMBER OF()` `str MEMBER OF (json_array)` 函数测试传入的 `str` 值是否是 `json_array` 的元素，如果是则返回 `1`，否则返回 `0`。如果任一参数为 `NULL`，则返回 `NULL`。 @@ -294,7 +294,7 @@ SELECT '🍍' MEMBER OF ('["🍍","🥥","🥭"]') AS 'Contains pineapple'; ``` -## [JSON_OVERLAPS()](https://dev.mysql.com/doc/refman/8.0/en/json-search-functions.html#function_json-overlaps) +## `JSON_OVERLAPS()` `JSON_OVERLAPS(json_doc, json_doc)` 函数检查两个 JSON 文档是否有重叠部分。如果有重叠，则返回 `1`，如果没有重叠，则返回 `0`。如果任一参数为 `NULL`，则返回 `NULL`。 diff --git a/functions-and-operators/json-functions/json-functions-utility.md b/functions-and-operators/json-functions/json-functions-utility.md index 3c60681b006f..64e68a758155 100644 --- a/functions-and-operators/json-functions/json-functions-utility.md +++ b/functions-and-operators/json-functions/json-functions-utility.md @@ -5,9 +5,9 @@ summary: 了解 JSON 效用函数。 # JSON 效用函数 -本文档介绍 JSON 效用函数。 +TiDB 支持使用 MySQL 8.0 中提供的所有[JSON 效用函数](https://dev.mysql.com/doc/refman/8.0/en/json-utility-functions.html)。 -## [JSON_PRETTY()](https://dev.mysql.com/doc/refman/8.0/en/json-utility-functions.html#function_json-pretty) +## `JSON_PRETTY()` `JSON_PRETTY(json_doc)` 函数用于格式化 JSON 文档。 @@ -29,7 +29,7 @@ JSON_PRETTY('{"person":{"name":{"first":"John","last":"Doe"},"age":23}}'): { 1 row in set (0.00 sec) ``` -## [JSON_STORAGE_FREE()](https://dev.mysql.com/doc/refman/8.0/en/json-utility-functions.html#function_json-storage-free) +## `JSON_STORAGE_FREE()` `JSON_STORAGE_FREE(json_doc)` 函数返回 JSON 值在原地更新操作后释放了多少存储空间，以二进制表示。 @@ -50,7 +50,7 @@ SELECT JSON_STORAGE_FREE('{}'); 1 row in set (0.00 sec) ``` -## [JSON_STORAGE_SIZE()](https://dev.mysql.com/doc/refman/8.0/en/json-utility-functions.html#function_json-storage-size) +## `JSON_STORAGE_SIZE()` `JSON_STORAGE_SIZE(json_doc)` 函数返回存储 JSON 值所需的大致字节数。由于计算该大小时不考虑 TiKV 对数据的压缩，因此该函数的输出与 MySQL 并不完全兼容。 diff --git a/functions-and-operators/json-functions/json-functions-validate.md b/functions-and-operators/json-functions/json-functions-validate.md index cde80373a5d8..5daffc740e9e 100644 --- a/functions-and-operators/json-functions/json-functions-validate.md +++ b/functions-and-operators/json-functions/json-functions-validate.md @@ -5,9 +5,9 @@ summary: 了解验证 JSON 文档的函数。 # 验证 JSON 文档的函数 -本文档介绍用于验证 JSON 文档的函数。 +TiDB 支持使用 MySQL 8.0 中提供的大部分[用于验证 JSON 文档的 JSON 函数](https://dev.mysql.com/doc/refman/8.0/en/json-validation-functions.html)。 -## [JSON_SCHEMA_VALID()](https://dev.mysql.com/doc/refman/8.0/en/json-validation-functions.html#function_json-schema-valid) +## `JSON_SCHEMA_VALID()` `JSON_SCHEMA_VALID(schema, json_doc)` 函数根据 schema 验证 JSON 文档，确保数据的完整性和一致性。该函数可以与 [CHECK](/constraints.md#check-约束) 约束一起使用，以便在修改表时自动进行 schema 验证。该函数遵循 [JSON Schema specification](https://json-schema.org/specification)。 diff --git a/functions-and-operators/miscellaneous-functions.md b/functions-and-operators/miscellaneous-functions.md index 632ea33328a9..17e3a7130b2f 100644 --- a/functions-and-operators/miscellaneous-functions.md +++ b/functions-and-operators/miscellaneous-functions.md @@ -1,6 +1,5 @@ --- title: 其他函数 -aliases: ['/docs-cn/dev/functions-and-operators/miscellaneous-functions/','/docs-cn/dev/reference/sql/functions-and-operators/miscellaneous-functions/'] summary: TiDB 支持使用 MySQL 8.0 中提供的大部分其他函数。 --- diff --git a/functions-and-operators/numeric-functions-and-operators.md b/functions-and-operators/numeric-functions-and-operators.md index 40d844375dc4..2e209ad56030 100644 --- a/functions-and-operators/numeric-functions-and-operators.md +++ b/functions-and-operators/numeric-functions-and-operators.md @@ -1,6 +1,5 @@ --- title: 数值函数与操作符 -aliases: ['/docs-cn/dev/functions-and-operators/numeric-functions-and-operators/','/docs-cn/dev/reference/sql/functions-and-operators/numeric-functions-and-operators/'] summary: TiDB 支持 MySQL 8.0 中的所有数值函数和操作符。 --- diff --git a/functions-and-operators/operators.md b/functions-and-operators/operators.md index 723dc039e7c6..9505b51e72a9 100644 --- a/functions-and-operators/operators.md +++ b/functions-and-operators/operators.md @@ -1,6 +1,5 @@ --- title: 操作符 -aliases: ['/docs-cn/dev/functions-and-operators/operators/','/docs-cn/dev/reference/sql/functions-and-operators/operators/'] summary: 操作符是用于在 MySQL 中执行各种操作的关键元素。它们包括逻辑操作符（如 AND、OR、NOT、XOR）、赋值操作符（如 =、:=）、比较操作符（如 =、<、>、LIKE、BETWEEN）、以及其他操作符（如 +、-、*、/）。操作符具有不同的优先级，可以用于执行各种复杂的操作。需要注意的是，MySQL 不支持 ILIKE 操作符。 --- diff --git a/functions-and-operators/precision-math.md b/functions-and-operators/precision-math.md index e68f95608fff..ab0d8b3c5603 100644 --- a/functions-and-operators/precision-math.md +++ b/functions-and-operators/precision-math.md @@ -1,6 +1,5 @@ --- title: 精度数学 -aliases: ['/docs-cn/dev/functions-and-operators/precision-math/','/docs-cn/dev/reference/sql/functions-and-operators/precision-math/'] summary: TiDB 中的精确数值运算与 MySQL 基本一致。精确数值运算包括整型和 DECIMAL 类型，以及精确值数字字面量。DECIMAL 数据类型是定点数类型，其运算是精确计算。在表达式计算中，TiDB 会尽可能不做任何修改的使用每个输入的数值。数值修约时，`round()` 函数将使用四舍五入的规则。向 DECIMAL 或整数类型列插入数据时，round 的规则将采用 round half away from zero 的方式。 --- @@ -58,7 +57,7 @@ DECIMAL 列不存储前导的字符 `+` 或字符 `-` 或数字 `0`。如果将 DECIMAL 列不允许插入大于列定义的隐含范围的值。例如：DECIMAL(3, 0) 列范围为`-999` 到 `999`。DECIMAL(M, D) 列小数点左边部分最多支持 M-D 位数字。 -有关 DECIMAL 值的内部格式完整说明，请参阅 TiDB 源码文件 [`types/mydecimal.go`](https://github.com/pingcap/tidb/blob/master/pkg/types/mydecimal.go)。 +有关 DECIMAL 值的内部格式完整说明，请参阅 TiDB 源码文件 [`types/mydecimal.go`](https://github.com/pingcap/tidb/blob/release-8.5/pkg/types/mydecimal.go)。 ## 表达式计算 diff --git a/functions-and-operators/string-functions.md b/functions-and-operators/string-functions.md index 50d61156ad92..8099f6875db1 100644 --- a/functions-and-operators/string-functions.md +++ b/functions-and-operators/string-functions.md @@ -1,6 +1,5 @@ --- title: 字符串函数 -aliases: ['/docs-cn/dev/functions-and-operators/string-functions/','/docs-cn/dev/reference/sql/functions-and-operators/string-functions/','/docs-cn/dev/sql/string-functions/'] summary: TiDB 支持 MySQL 8.0 中提供的大部分字符串函数以及 Oracle 21 中提供的部分函数。 --- @@ -12,7 +11,7 @@ TiDB 支持使用 MySQL 8.0 中提供的大部分[字符串函数](https://dev.m ## 支持的函数 -### [`ASCII()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_ascii) +### `ASCII()` `ASCII()` 函数用于获取输入的参数中最左字符的 ASCII 值。该参数可以为字符串或数字。 @@ -40,7 +39,7 @@ SELECT ASCII('A'), ASCII('TiDB'), ASCII(23); +------------+---------------+-----------+ ``` -### [`BIN()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_bin) +### `BIN()` `BIN()` 函数用于将输入的参数转换为其二进制值的字符串表示形式。该参数可以为字符串或数字。 @@ -83,7 +82,7 @@ SELECT BIN(-7); +------------------------------------------------------------------+ ``` -### [`BIT_LENGTH()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_bit-length) +### `BIT_LENGTH()` `BIT_LENGTH()` 函数用于返回输入参数的长度，单位为 bit。 @@ -128,7 +127,7 @@ SELECT CustomerName, BIT_LENGTH(CustomerName) AS BitLengthOfName FROM Customers; > > 上面这个示例假设数据库中存在一个名为 `Customers` 的表，表中有一个名为 `CustomerName` 的列。 -### [`CHAR()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_char) +### `CHAR()` `CHAR()` 函数用于获取指定 ASCII 值的对应字符。该函数执行的操作与 `ASCII()` 相反，`ASCII()` 用于返回指定字符的 ASCII 值。如果提供了多个参数，`CHAR()` 函数将作用于所有参数并将它们的结果拼接在一起返回。 @@ -197,7 +196,7 @@ SELECT CHAR(65,66,67); 1 row in set (0.00 sec) ``` -### [`CHAR_LENGTH()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_char-length) +### `CHAR_LENGTH()` `CHAR_LENGTH()` 函数用于获取输入参数中字符的总数。 @@ -228,11 +227,11 @@ SELECT CustomerName, CHAR_LENGTH(CustomerName) AS LengthOfName FROM Customers; > > 上面这个示例假设数据库中存在一个名为 `Customers` 的表，表中有一个名为 `CustomerName` 的列。 -### [`CHARACTER_LENGTH()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_character-length) +### `CHARACTER_LENGTH()` `CHARACTER_LENGTH()` 函数与 `CHAR_LENGTH()` 函数功能相同，返回结果相同，可以互换使用。 -### [`CONCAT()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_concat) +### `CONCAT()` `CONCAT()` 函数用于将输入的参数连接成一个字符串。 @@ -294,7 +293,7 @@ SELECT 'Ti' 'DB' ' ' 'Server'; +-------------+ ``` -### [`CONCAT_WS()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_concat-ws) +### `CONCAT_WS()` `CONCAT_WS()` 函数是一种带分隔符的 [`CONCAT()`](#concat)，返回由分隔符连接的字符串。 @@ -413,7 +412,7 @@ SELECT CONCAT_WS(',', 'TiDB Server', 'TiKV', 'PD'); +-----------------------------------------+ ``` -### [`ELT()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_elt) +### `ELT()` `ELT()` 函数返回索引号对应的元素。 @@ -432,7 +431,7 @@ SELECT ELT(3, 'This', 'is', 'TiDB'); 在以上示例中，该函数返回第三个元素，即 `'TiDB'`。 -### [`EXPORT_SET()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_export-set) +### `EXPORT_SET()` `EXPORT_SET()` 函数返回一个由指定数量 (`number_of_bits`) 的 `on`/`off` 值组成的字符串，各个值之间可以用 `separator` 分隔（可选）。这些值将基于输入的 `bits` 参数中的相应 bit 是否为 `1` 而确定，其中第一个值对应于 `bits` 中的最右边（即最低）的 bit。 @@ -495,7 +494,7 @@ SELECT EXPORT_SET(b'01010101', 'x', '_', '', 8); 1 row in set (0.00 sec) ``` -### [`FIELD()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_field) +### `FIELD()` 返回参数在后续参数中出现的第一个位置 @@ -511,7 +510,7 @@ SELECT FIELD('needle', 'A', 'needle', 'in', 'a', 'haystack'); 1 row in set (0.00 sec) ``` -### [`FIND_IN_SET()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_find-in-set) +### `FIND_IN_SET()` 返回第一个参数在第二个参数中出现的位置 @@ -529,7 +528,7 @@ SELECT FIND_IN_SET('Go', 'COBOL,BASIC,Rust,Go,Java,Fortran'); 1 row in set (0.00 sec) ``` -### [`FORMAT()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_format) +### `FORMAT()` `FORMAT(X,D[,locale])` 函数用于将数字 `X` 格式化为类似于 `“#,###,###.##”` 的格式，四舍五入保留 `D` 位小数，并将结果作为字符串返回。 @@ -579,7 +578,7 @@ mysql> SELECT FORMAT(1234.56, 1, 'en_US'); +-----------------------------+ ``` -### [`FROM_BASE64()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_from-base64) +### `FROM_BASE64()` `FROM_BASE64(str)` 函数用于对 [Base64](https://datatracker.ietf.org/doc/html/rfc4648) 编码的字符串进行解码，并将解码结果以十六进制字符串的形式返回。 @@ -626,7 +625,7 @@ mysql> SELECT FROM_BASE64('MTIzNDU2'); +--------------------------------------------------+ ``` -### [`HEX()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_hex) +### `HEX()` `HEX()` 函数用于将输入的参数转换为其十六进制值的字符串表示形式。该参数可以为字符串或数字。 @@ -676,7 +675,7 @@ SELECT HEX(NULL); +-----------+ ``` -### [`INSERT()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_insert) +### `INSERT()` `INSERT(str, pos, len, newstr)` 函数用于将字符串 `str` 中的一个子字符串（从位置 `pos` 开始，长度为 `len`）替换为字符串 `newstr`。该函数是多字节安全的。 @@ -731,7 +730,7 @@ SELECT INSERT('PingCAP 数据库', 1, 7, 'TiDB'); +-------------------------------------------+ ``` -### [`INSTR()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_instr) +### `INSTR()` `INSTR(str, substr)` 函数用于获取子字符串 `substr` 在字符串 `str` 中第一次出现的位置。`substr` 和 `str` 均可以为字符串或数字。该函数与 [`LOCATE(substr, str)`](#locate) 函数的两参数版本功能相同，但参数顺序相反。 @@ -790,11 +789,11 @@ SELECT INSTR(0123, "12"); +-------------------+ ``` -### [`LCASE()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_lcase) +### `LCASE()` `LCASE(str)`函数与 [`LOWER(str)`](#lower) 函数功能相同，都是返回输入参数的小写形式。 -### [`LEFT()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_left) +### `LEFT()` `LEFT()` 函数用于返回字符串左侧指定数量的字符。 @@ -869,7 +868,7 @@ SELECT LEFT(NULL, 3); +------------------------------+ ``` -### [`LENGTH()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_length) +### `LENGTH()` `LENGTH()` 函数用于返回字符串的字节长度。`LENGTH()` 将单个多字节字符视为多个字节，而 `CHAR_LENGTH()` 将单个多字节字符视为单个字符。 @@ -909,7 +908,7 @@ SELECT LENGTH(NULL); +--------------+ ``` -### [`LIKE`](https://dev.mysql.com/doc/refman/8.0/en/string-comparison-functions.html#operator_like) +### `LIKE` `LIKE` 用于进行简单字符串匹配。表达式 `expr LIKE pat [ESCAPE 'escape_char']` 返回 `1` (`TRUE`) 或 `0` (`FALSE`)。如果 `expr` 或 `pat` 中任一个为 `NULL`，结果为 `NULL`。 @@ -1046,7 +1045,7 @@ SELECT '🍣🍺Sushi🍣🍺' COLLATE utf8mb4_unicode_ci LIKE '%SUSHI%' AS resu +--------+ ``` -### [`LOCATE()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_locate) +### `LOCATE()` `LOCATE(substr, str[, pos])` 函数用于返回子字符串 `substr` 在字符串 `str` 中第一次出现的位置。`pos` 参数是可选的，用于指定查找的起始位置。 @@ -1225,7 +1224,7 @@ SELECT LOCATE(_binary'B', 'aBcde'); +-----------------------------+ ``` -### [`LOWER()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_lower) +### `LOWER()` `LOWER(str)` 函数用于将输入的参数 `str` 中的所有字符转换为小写。该参数可以为字符串或数字。 @@ -1255,7 +1254,7 @@ SELECT LOWER(-012); +-------------+ ``` -### [`LPAD()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_lpad) +### `LPAD()` `LPAD(str, len, padstr)` 函数返回字符串参数，左侧填充指定字符串 `padstr`，直到字符串长度达到 `len` 个字符。 @@ -1295,7 +1294,7 @@ SELECT LPAD('TiDB',-2,'>'); 1 row in set (0.00 sec) ``` -### [`LTRIM()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_ltrim) +### `LTRIM()` `LTRIM()` 函数用于删除给定的字符串中的前导空格（即字符串开头的连续空格）。 @@ -1337,7 +1336,7 @@ SELECT CONCAT('«',LTRIM(' hello'),'»'); 1 row in set (0.00 sec) ``` -### [`MAKE_SET()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_make-set) +### `MAKE_SET()` `MAKE_SET()` 函数根据输入的 `bits` 参数中相应的 bit 是否为 `1` 返回一组由逗号分隔的字符串。 @@ -1427,7 +1426,7 @@ SELECT MAKE_SET(b'111','foo','bar','baz'); 1 row in set (0.0002 sec) ``` -### [`MID()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_mid) +### `MID()` `MID(str, pos[, len])` 函数返回从指定的 `pos` 位置开始的长度为 `len` 的子字符串。 @@ -1467,7 +1466,7 @@ SELECT MID('abcdef',2); 1 row in set (0.00 sec) ``` -### [`NOT LIKE`](https://dev.mysql.com/doc/refman/8.0/en/string-comparison-functions.html#operator_not-like) +### `NOT LIKE` 否定简单模式匹配。 @@ -1505,11 +1504,11 @@ SELECT 'aaa' LIKE 'b%', 'aaa' NOT LIKE 'b%'; 1 row in set (0.00 sec) ``` -### [`NOT REGEXP`](https://dev.mysql.com/doc/refman/8.0/en/regexp.html#operator_not-regexp) +### `NOT REGEXP` [`REGEXP`](#regexp) 的否定形式 -### [`OCT()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_oct) +### `OCT()` `OCT()` 函数用于返回一个数值的[八进制](https://zh.wikipedia.org/wiki/八进制)表示，形式为字符串。 @@ -1555,11 +1554,11 @@ SELECT n, OCT(n) FROM nr; 20 rows in set (0.00 sec) ``` -### [`OCTET_LENGTH()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_octet-length) +### `OCTET_LENGTH()` 与 [`LENGTH()`](#length) 功能相同 -### [`ORD()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_ord) +### `ORD()` 返回给定的参数中最左侧字符的字符编码。 @@ -1612,11 +1611,11 @@ SELECT ORD('e'), ORD('ë'), HEX('e'), HEX('ë'); 1 row in set (0.00 sec) ``` -### [`POSITION()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_position) +### `POSITION()` 与 [`LOCATE()`](#locate) 功能相同 -### [`QUOTE()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_quote) +### `QUOTE()` `QUOTE()` 函数用于转义字符串，使其可以在 SQL 语句中使用。 @@ -1641,7 +1640,7 @@ SELECT QUOTE(0x002774657374); 1 row in set (0.00 sec) ``` -### [`REGEXP`](https://dev.mysql.com/doc/refman/8.0/en/regexp.html#operator_regexp) +### `REGEXP` 使用正则表达式匹配模式 @@ -1700,7 +1699,7 @@ WHERE 1 row in set (0.01 sec) ``` -### [`REGEXP_INSTR()`](https://dev.mysql.com/doc/refman/8.0/en/regexp.html#function_regexp-instr) +### `REGEXP_INSTR()` 返回满足正则的子字符串的第一个索引位置（与 MySQL 不完全兼容，具体请参考[正则函数与 MySQL 的兼容性](#正则函数与-mysql-的兼容性)） @@ -1811,7 +1810,7 @@ SELECT REGEXP_INSTR('abcabc','A',1,1,0,'i'); 1 row in set (0.00 sec) ``` -除了 `match_type`，[排序规则](/character-set-and-collation.md) 也会影响匹配。在下面的示例中，使用了区分大小写和不区分大小写的排序规则来展示这种影响。 +除了 `match_type`，[排序规则](/character-set-and-collation.md)也会影响匹配。在下面的示例中，使用了区分大小写和不区分大小写的排序规则来展示这种影响。 ```sql SELECT REGEXP_INSTR('abcabc','A' COLLATE utf8mb4_general_ci); @@ -1839,7 +1838,7 @@ SELECT REGEXP_INSTR('abcabc','A' COLLATE utf8mb4_bin); 1 row in set (0.00 sec) ``` -### [`REGEXP_LIKE()`](https://dev.mysql.com/doc/refman/8.0/en/regexp.html#function_regexp-like) +### `REGEXP_LIKE()` 判断字符串是否满足正则表达式（与 MySQL 不完全兼容，具体请参考[正则函数与 MySQL 的兼容性](#正则函数与-mysql-的兼容性)） @@ -1892,7 +1891,7 @@ SELECT REGEXP_LIKE('abc','^A','i'); 1 row in set (0.00 sec) ``` -### [`REGEXP_REPLACE()`](https://dev.mysql.com/doc/refman/8.0/en/regexp.html#function_regexp-replace) +### `REGEXP_REPLACE()` 替换满足正则表达式的子字符串（与 MySQL 不完全兼容，具体请参考[正则函数与 MySQL 的兼容性](#正则函数与-mysql-的兼容性)） @@ -1986,7 +1985,7 @@ SELECT REGEXP_REPLACE('TooDB', 'O{2}','i',1,1,'i'); 1 row in set (0.00 sec) ``` -### [`REGEXP_SUBSTR()`](https://dev.mysql.com/doc/refman/8.0/en/regexp.html#function_regexp-substr) +### `REGEXP_SUBSTR()` 返回满足正则表达式的子字符串（与 MySQL 不完全兼容，具体请参考[正则函数与 MySQL 的兼容性](#正则函数与-mysql-的兼容性)） @@ -2007,7 +2006,7 @@ SELECT REGEXP_SUBSTR('This is TiDB','Ti.{2}'); 1 row in set (0.00 sec) ``` -### [`REPEAT()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_repeat) +### `REPEAT()` `REPEAT()` 函数用于以指定次数重复一个字符串。 @@ -2067,47 +2066,47 @@ SELECT REPEAT('ha',3); 1 row in set (0.00 sec) ``` -### [`REPLACE()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_replace) +### `REPLACE()` 替换所有出现的指定字符串 -### [`REVERSE()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_reverse) +### `REVERSE()` 反转字符串里的所有字符 -### [`RIGHT()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_right) +### `RIGHT()` 返回指定数量的最右侧的字符 -### [`RLIKE`](https://dev.mysql.com/doc/refman/8.0/en/regexp.html#operator_regexp) +### `RLIKE` 与 [`REGEXP`](#regexp) 功能相同 -### [`RPAD()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_rpad) +### `RPAD()` 以指定次数添加字符串 -### [`RTRIM()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_rtrim) +### `RTRIM()` 去掉后缀空格 -### [`SPACE()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_space) +### `SPACE()` 返回指定数量的空格，形式为字符串 -### [`STRCMP()`](https://dev.mysql.com/doc/refman/8.0/en/string-comparison-functions.html#function_strcmp) +### `STRCMP()` 比较两个字符串 -### [`SUBSTR()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_substr) +### `SUBSTR()` 返回指定的子字符串 -### [`SUBSTRING()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_substring) +### `SUBSTRING()` 返回指定的子字符串 -### [`SUBSTRING_INDEX()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_substring-index) +### `SUBSTRING_INDEX()` `SUBSTRING_INDEX()` 函数用于按照指定的分隔符和次数从字符串中提取子字符串。该函数在处理以特定分隔符分隔的数据时特别有用，例如解析 CSV 数据或处理日志文件。 @@ -2156,7 +2155,7 @@ SELECT SUBSTRING_INDEX('www.tidbcloud.com', '.', -1); +------------------------------------------+ ``` -### [`TO_BASE64()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_to-base64) +### `TO_BASE64()` `TO_BASE64()` 函数用于将输入的参数转换为 base-64 编码形式的字符串，并按照当前连接的字符集和排序规则返回结果。base-64 编码的字符串可以使用 [`FROM_BASE64()`](#from_base64) 函数进行解码。 @@ -2201,15 +2200,15 @@ SELECT TO_BASE64(6); +--------------+ ``` -### [`TRANSLATE()`](https://docs.oracle.com/en/database/oracle/oracle-database/21/sqlrf/TRANSLATE.html#GUID-80F85ACB-092C-4CC7-91F6-B3A585E3A690) +### `TRANSLATE()` 将字符串中出现的所有指定字符替换为其它字符。这个函数不会像 Oracle 一样将空字符串视为`NULL` -### [`TRIM()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_trim) +### `TRIM()` 去掉前缀和后缀空格 -### [`UCASE()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_ucase) +### `UCASE()` `UCASE()` 函数将字符串转换为大写字母，此函数等价于 `UPPER()` 函数。 @@ -2233,7 +2232,7 @@ SELECT UCASE('bigdata') AS result_upper, UCASE(null) AS result_null; +--------------+-------------+ ``` -### [`UNHEX()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_unhex) +### `UNHEX()` `UNHEX()` 函数执行 `HEX()` 函数的逆运算，将参数中的每对字符视为十六进制数字，并将其转换为该数字表示的字符，返回值为二进制字符串。 @@ -2258,7 +2257,7 @@ SELECT UNHEX('54694442'); +--------------------------------------+ ``` -### [`UPPER()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_upper) +### `UPPER()` `UPPER()` 函数将字符串转换为大写字母，此函数等价于 `UCASE()` 函数。 @@ -2282,7 +2281,7 @@ SELECT UPPER('bigdata') AS result_upper, UPPER(null) AS result_null; +--------------+-------------+ ``` -### [`WEIGHT_STRING()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_weight-string) +### `WEIGHT_STRING()` `WEIGHT_STRING()` 函数返回字符串的权重（二进制字符），主要用于多字符集场景下的排序和比较操作。如果参数为 `NULL`，则返回 `NULL`。语法示例如下： diff --git a/functions-and-operators/tidb-functions.md b/functions-and-operators/tidb-functions.md index 6b2a5a78648d..1b2098652bf1 100644 --- a/functions-and-operators/tidb-functions.md +++ b/functions-and-operators/tidb-functions.md @@ -9,15 +9,18 @@ summary: 学习使用 TiDB 特有的函数。 | 函数名 | 函数说明 | | :-------------- | :------------------------------------- | -| [`CURRENT_RESOURCE_GROUP()`](#current_resource_group) | 用于查询当前连接绑定的资源组名。参见[使用资源管控 (Resource Control) 实现资源隔离](/tidb-resource-control.md)。 | +| [`CURRENT_RESOURCE_GROUP()`](#current_resource_group) | 用于查询当前连接绑定的资源组名。参见[使用资源管控 (Resource Control) 实现资源组限制和流控](/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) | 返回当前的 [TimeStamp Oracle (TSO)](/tso.md)。 | | [`TIDB_DECODE_BINARY_PLAN()`](#tidb_decode_binary_plan) | 用于解码以二进制格式编码的执行计划。 | | [`TIDB_DECODE_KEY()`](#tidb_decode_key) | 用于将 TiDB 编码的键输入解码为包含 `_tidb_rowid` 和 `table_id` 的 JSON 结构。一些系统表和日志输出中有 TiDB 编码的键。 | | [`TIDB_DECODE_PLAN()`](#tidb_decode_plan) | 用于解码 TiDB 执行计划。 | | [`TIDB_DECODE_SQL_DIGESTS()`](#tidb_decode_sql_digests) | 用于在集群中查询一组 SQL digest 所对应的 SQL 语句的归一化形式（即去除格式和参数后的形式）。 | +| [`TIDB_ENCODE_INDEX_KEY()`](#tidb_encode_index_key) | 对索引键进行编码。 | +| [`TIDB_ENCODE_RECORD_KEY()`](#tidb_encode_record_key) | 对记录键进行编码。 | | [`TIDB_ENCODE_SQL_DIGEST()`](#tidb_encode_sql_digest) | 用于为查询字符串获取 digest。 | | [`TIDB_IS_DDL_OWNER()`](#tidb_is_ddl_owner) | 用于检查你连接的 TiDB 实例是否是 DDL Owner。DDL Owner 是代表集群中所有其他节点执行 DDL 语句的 TiDB 实例。 | +| [`TIDB_MVCC_INFO()`](#tidb_mvcc_info) | 返回关于某个键的多版本并发控制 ([Multi-Version Concurrency Control, MVCC](/glossary.md#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) | 用于查询行数据的 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)。 | @@ -27,7 +30,7 @@ summary: 学习使用 TiDB 特有的函数。 ## CURRENT_RESOURCE_GROUP -`CURRENT_RESOURCE_GROUP()` 函数用于查询当前连接绑定的资源组名称。当开启[资源管控 (Resource Control)](/tidb-resource-control.md) 功能时，执行 SQL 语句对资源的占用会受到所绑定的资源组资源配置的限制。 +`CURRENT_RESOURCE_GROUP()` 函数用于查询当前连接绑定的资源组名称。当开启[资源管控 (Resource Control)](/tidb-resource-control-ru-groups.md) 功能时，执行 SQL 语句对资源的占用会受到所绑定的资源组资源配置的限制。 在会话建立时，TiDB 默认会将连接绑定至登录用户绑定的资源组，如果用户没有绑定任何资源组，则会将连接绑定至 `default` 资源组。在会话建立之后，绑定的资源组默认不会发生变化，即使执行了[修改用户绑定的资源组](/sql-statements/sql-statement-alter-user.md#修改用户绑定的资源组)。如需修改当前会话绑定的资源组，可以使用 [`SET RESOURCE GROUP`](/sql-statements/sql-statement-set-resource-group.md) 语句。 @@ -518,11 +521,11 @@ SELECT TIDB_VERSION()\G ```sql *************************** 1. row *************************** -TIDB_VERSION(): Release Version: v8.4.0 +TIDB_VERSION(): Release Version: v{{{ .tidb-version }}} Edition: Community Git Commit Hash: 821e491a20fbab36604b36b647b5bae26a2c1418 Git Branch: HEAD -UTC Build Time: 2024-07-11 19:16:25 +UTC Build Time: {{{ .tidb-release-date }}} 19:16:25 GoVersion: go1.21.10 Race Enabled: false Check Table Before Drop: false @@ -547,4 +550,166 @@ SELECT VITESS_HASH(123); | 1155070131015363447 | +---------------------+ 1 row in set (0.00 sec) -``` \ No newline at end of file +``` + +## TIDB_ENCODE_INDEX_KEY + +`TIDB_ENCODE_INDEX_KEY()` 函数将指定的索引键编码为一个十六进制字符串。函数语法如下： + +```sql +TIDB_ENCODE_INDEX_KEY(, , , ..., ...) +``` + +参数说明： + +* ``：目标索引所在的数据库的名称。 +* ``：目标索引所在的表的名称。对于分区表，可以指定分区名，例如 `'t(p0)'`。 +* ``：目标索引的名称。 +* `...`：索引列的值。你必须按照索引定义的顺序依次指定。对于复合索引，需指定所有索引列的值。 +* `...`：该行数据对应的 handle 值。根据表的主键类型不同，handle 值的取值规则如下： + + * 如果表没有主键，或主键为 `NONCLUSTERED`，handle 值为隐藏列 `_tidb_rowid` 的值。 + * 如果表的主键为 `CLUSTERED` 且为单列整型，handle 值为主键列的值。 + * 如果表的主键为 `CLUSTERED` 且为复合主键或非整型 (common handle)，handle 值由所有主键列的值按顺序组成。 + +以下示例展示了在不同主键类型下，如何为复合二级索引 `idx(c1, c2)` 调用此函数。 + +```sql +-- 对于没有主键或主键为 NONCLUSTERED 的表，使用 _tidb_rowid +SELECT TIDB_ENCODE_INDEX_KEY( + '', '', '', + , , <_tidb_rowid> +); + +-- 对于主键为 CLUSTERED 的整型主键表（主键列为 id） +SELECT TIDB_ENCODE_INDEX_KEY( + '', '', '', + , , +); + +-- 对于主键为 CLUSTERED 的复合主键表（主键列为 p1, p2） +SELECT TIDB_ENCODE_INDEX_KEY( + '', '', '', + , , , +); +``` + +```sql +CREATE TABLE t(id int PRIMARY KEY, a int, KEY `idx` (a)); +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +```sql +INSERT INTO t VALUES(1,2); +``` + +``` +Query OK, 1 row affected (0.00 sec) +``` + +```sql +SELECT TIDB_ENCODE_INDEX_KEY('test', 't', 'idx', 2, 1); +``` + +``` ++----------------------------------------------------------------------------+ +| TIDB_ENCODE_INDEX_KEY('test', 't', 'idx', 2, 1) | ++----------------------------------------------------------------------------+ +| 7480000000000000b45f698000000000000001038000000000000002038000000000000001 | ++----------------------------------------------------------------------------+ +1 row in set (0.00 sec) +``` + +## TIDB_ENCODE_RECORD_KEY + +`TIDB_ENCODE_RECORD_KEY()` 函数将指定的行记录键编码为一个十六进制字符串。函数语法如下： + +```sql +TIDB_ENCODE_RECORD_KEY(, , ...) +``` + +参数说明： + +* ``：目标表所在的数据库的名称。 +* ``：目标表所在的表的名称。对于分区表，可以在 `` 中指定分区名，例如 `'t(p0)'`。 +* `...`：该行的 handle（行键）值。handle 的具体组成取决于表的主键类型，例如是否为 `CLUSTERED`、是否为 common handle、是否使用隐藏列 `_tidb_rowid`。详情请参考 [`TIDB_ENCODE_INDEX_KEY()`](#tidb_encode_index_key) 中 `...` 的说明。 + +```sql +CREATE TABLE t(id int PRIMARY KEY, a int, KEY `idx` (a)); +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +```sql +INSERT INTO t VALUES(1,2); +``` + +``` +Query OK, 1 row affected (0.00 sec) +``` + +```sql +SELECT TIDB_ENCODE_RECORD_KEY('test', 't', 1); +``` + +``` ++----------------------------------------+ +| TIDB_ENCODE_RECORD_KEY('test', 't', 1) | ++----------------------------------------+ +| 7480000000000000845f728000000000000001 | ++----------------------------------------+ +1 row in set (0.00 sec) +``` + +```sql +SELECT TIDB_DECODE_KEY('7480000000000000845f728000000000000001'); +``` + +``` ++-----------------------------------------------------------+ +| TIDB_DECODE_KEY('7480000000000000845f728000000000000001') | ++-----------------------------------------------------------+ +| {"id":1,"table_id":"132"} | ++-----------------------------------------------------------+ +1 row in set (0.00 sec) +``` + +## TIDB_MVCC_INFO + +返回关于某个键的多版本并发控制 ([Multi-Version Concurrency Control, MVCC](/glossary.md#multi-version-concurrency-control-mvcc)) 信息。你可以使用 [`TIDB_ENCODE_INDEX_KEY`](#tidb_encode_index_key) 函数获取键。 + +```sql +SELECT JSON_PRETTY(TIDB_MVCC_INFO('74800000000000007f5f698000000000000001038000000000000001038000000000000001')) AS info\G +``` + +``` +*************************** 1. row *************************** +info: [ + { + "key": "74800000000000007f5f698000000000000001038000000000000001038000000000000001", + "mvcc": { + "info": { + "values": [ + { + "start_ts": 454654803134119936, + "value": "MA==" + } + ], + "writes": [ + { + "commit_ts": 454654803134119937, + "short_value": "MA==", + "start_ts": 454654803134119936 + } + ] + } + } + } +] +1 row in set (0.00 sec) +``` diff --git a/functions-and-operators/type-conversion-in-expression-evaluation.md b/functions-and-operators/type-conversion-in-expression-evaluation.md index 83380e70f043..7816a7d82d78 100644 --- a/functions-and-operators/type-conversion-in-expression-evaluation.md +++ b/functions-and-operators/type-conversion-in-expression-evaluation.md @@ -1,6 +1,5 @@ --- title: 表达式求值的类型转换 -aliases: ['/docs-cn/dev/functions-and-operators/type-conversion-in-expression-evaluation/','/docs-cn/dev/reference/sql/functions-and-operators/type-conversion/'] summary: TiDB 中的表达式求值类型转换与 MySQL 基本一致。详情请参见 MySQL 表达式求值类型转换文档。 --- diff --git a/functions-and-operators/utility-functions.md b/functions-and-operators/utility-functions.md new file mode 100644 index 000000000000..f69bb2d9050f --- /dev/null +++ b/functions-and-operators/utility-functions.md @@ -0,0 +1,42 @@ +--- +title: 效用函数 +summary: 了解 TiDB 中的效用函数。 +--- + +# 效用函数 + +本文介绍了 TiDB 支持的效用函数，这些函数旨在简化常见数据转换，使结果更易于阅读和理解。 + +## `FORMAT_BYTES()` + +`FORMAT_BYTES()` 函数用于将字节数格式化为易于阅读的形式。 + +```sql +SELECT FORMAT_BYTES(10*1024*1024); +``` + +``` ++----------------------------+ +| FORMAT_BYTES(10*1024*1024) | ++----------------------------+ +| 10.00 MiB | ++----------------------------+ +1 row in set (0.001 sec) +``` + +## `FORMAT_NANO_TIME()` + +`FORMAT_NANO_TIME()` 函数用于将纳秒数格式化为易于阅读的时间形式。 + +```sql +SELECT FORMAT_NANO_TIME(1000000); +``` + +``` ++---------------------------+ +| FORMAT_NANO_TIME(1000000) | ++---------------------------+ +| 1.00 ms | ++---------------------------+ +1 row in set (0.001 sec) +``` diff --git a/functions-and-operators/window-functions.md b/functions-and-operators/window-functions.md index 5d1a7266c06f..2e448e2aedcc 100644 --- a/functions-and-operators/window-functions.md +++ b/functions-and-operators/window-functions.md @@ -1,6 +1,5 @@ --- title: 窗口函数 -aliases: ['/docs-cn/dev/functions-and-operators/window-functions/','/docs-cn/dev/reference/sql/functions-and-operators/window-functions/'] summary: TiDB 中的窗口函数与 MySQL 8.0 基本一致。可以将 `tidb_enable_window_function` 设置为 `0` 来解决升级后无法解析语法的问题。TiDB 支持除 `GROUP_CONCAT()` 和 `APPROX_PERCENTILE()` 以外的所有 `GROUP BY` 聚合函数。其他支持的窗口函数包括 `CUME_DIST()`、`DENSE_RANK()`、`FIRST_VALUE()`、`LAG()`、`LAST_VALUE()`、`LEAD()`、`NTH_VALUE()`、`NTILE()`、`PERCENT_RANK()`、`RANK()` 和 `ROW_NUMBER()`。这些函数可以下推到 TiFlash。 --- @@ -32,7 +31,7 @@ TiDB 支持除 `GROUP_CONCAT()` 和 `APPROX_PERCENTILE()` 以外的所有 [`GROU | [`RANK()`](#rank) | 返回分区中当前行的排名，排名可能不连续 | | [`ROW_NUMBER()`](#row_number) | 返回分区中当前行的编号 | -## [`CUME_DIST()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_cume-dist) +## `CUME_DIST()` `CUME_DIST()` 计算一个值在一组值中的累积分布。请注意，你需要在 `CUME_DIST()` 后使用 `ORDER BY` 子句对该组中的值进行排序。否则，此函数将不会返回预期值。 @@ -66,7 +65,7 @@ FROM 4 rows in set (0.00 sec) ``` -## [`DENSE_RANK()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_dense-rank) +## `DENSE_RANK()` `DENSE_RANK()` 函数返回当前行的排名。它的作用类似于 [`RANK()`](#rank)，但在处理具有相同值和排序条件的行时能够确保排名是连续的。 @@ -102,7 +101,7 @@ FROM ( 6 rows in set (0.00 sec) ``` -## [`FIRST_VALUE()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_first-value) +## `FIRST_VALUE()` `FIRST_VALUE(expr)` 返回窗口中的第一个值。 @@ -141,7 +140,7 @@ ORDER BY 4 rows in set (0.00 sec) ``` -## [`LAG()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_lag) +## `LAG()` 函数 `LAG(expr [, num [, default]])` 返回当前行之前第 `num` 行的 `expr` 值。如果不存在该行，则返回 `default` 值。默认情况下，未指定时，`num` 为 `1`，`default` 为 `NULL`。 @@ -183,7 +182,7 @@ FROM 10 rows in set (0.01 sec) ``` -## [`LAST_VALUE()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_last-value) +## `LAST_VALUE()` `LAST_VALUE()` 函数返回窗口中的最后一个值。 @@ -226,7 +225,7 @@ ORDER BY 10 rows in set (0.00 sec) ``` -## [`LEAD()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_lead) +## `LEAD()` 函数 `LEAD(expr [, num [,default]])` 返回当前行之后第 `num` 行的 `expr` 值。如果不存在该行，则返回 `default` 值。默认情况下，未指定时，`num` 为 `1`，`default` 为 `NULL`。 @@ -269,7 +268,7 @@ FROM 10 rows in set (0.00 sec) ``` -## [`NTH_VALUE()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_nth-value) +## `NTH_VALUE()` 函数 `NTH_VALUE(expr, n)` 返回窗口的第 n 个值。 @@ -317,7 +316,7 @@ ORDER BY 10 rows in set (0.00 sec) ``` -## [`NTILE()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_ntile) +## `NTILE()` `NTILE(n)` 函数将窗口划分为 `n` 个分组，并返回各行的分组编号。 @@ -359,7 +358,7 @@ FROM 10 rows in set (0.00 sec) ``` -## [`PERCENT_RANK()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_percent-rank) +## `PERCENT_RANK()` `PERCENT_RANK()` 函数返回一个介于 0 和 1 之间的数字，表示值小于当前行值的行的百分比。 @@ -396,7 +395,7 @@ FROM ( 6 rows in set (0.00 sec) ``` -## [`RANK()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_rank) +## `RANK()` `RANK()` 函数的作用类似于 [`DENSE_RANK()`](#dense_rank)，但在处理具有相同值和排序条件的行时返回的排名是不连续的。这意味着它提供的是绝对排名。例如，排名 7 意味着有 6 个行的排名更靠前。 @@ -433,7 +432,7 @@ FROM ( 6 rows in set (0.00 sec) ``` -## [`ROW_NUMBER()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_row-number) +## `ROW_NUMBER()` `ROW_NUMBER()` 返回结果集中当前行的行号。 diff --git a/garbage-collection-configuration.md b/garbage-collection-configuration.md index 1355c3a77c09..7bed4cff582b 100644 --- a/garbage-collection-configuration.md +++ b/garbage-collection-configuration.md @@ -1,6 +1,5 @@ --- title: GC 配置 -aliases: ['/docs-cn/dev/garbage-collection-configuration/','/docs-cn/dev/reference/garbage-collection/configuration/'] summary: TiDB 的 GC 配置可以通过系统变量进行设置，包括启用 GC、运行间隔、数据保留时限、并发线程数量等。此外，TiDB 还支持 GC 流控，可以限制每秒数据写入量。从 TiDB 5.0 版本开始，建议使用系统变量进行配置，避免异常行为。在 TiDB 6.1.0 版本引入了新的系统变量 `tidb_gc_max_wait_time`，用于控制活跃事务阻塞 GC safe point 推进的最长时间。另外，GC in Compaction Filter 机制可以通过配置文件或在线配置开启，但可能会影响 TiKV 扫描性能。 --- @@ -92,4 +91,5 @@ show config where type = 'tikv' and name like '%enable-compaction-filter%'; > 在使用 Compaction Filter 机制时，可能会出现 GC 进度延迟的情况，从而影响 TiKV 扫描性能。当你的负载中含有大量 coprocessor 请求，并且在 [**TiKV-Details > Coprocessor Detail**](/grafana-tikv-dashboard.md#coprocessor-detail) 面板中发现 Total Ops Details 的 `next()` 或 `prev()` 调用次数远远超过 `processed_keys` 调用的三倍时，可以采取以下措施： > > - 对于 TiDB v7.1.3 之前版本，建议尝试关闭 Compaction Filter，以加快 GC 速度。 -> - 从 v7.1.3 开始，TiDB 会根据每个 Region 的冗余版本数量 [`region-compact-min-redundant-rows`](/tikv-configuration-file.md#region-compact-min-redundant-rows-从-v710-版本开始引入) 和比例 [`region-compact-redundant-rows-percent`](/tikv-configuration-file.md#region-compact-redundant-rows-percent-从-v710-版本开始引入) 自动触发 compaction，从而提高 Compaction Filter 的 GC 速度。因此，在 v7.1.3 及之后的版本中，如果遇到上述情况，建议调整这两个参数，无需关闭 Compaction Filter。 +> - 在 TiDB v7.1.3 至 v7.5.6，以及 v7.6.0 至 v8.5.3 的版本中，TiDB 会根据每个 Region 的冗余版本数量 [`region-compact-min-redundant-rows`](/tikv-configuration-file.md#region-compact-min-redundant-rows-从-v710-版本开始引入) 和比例 [`region-compact-redundant-rows-percent`](/tikv-configuration-file.md#region-compact-redundant-rows-percent-从-v710-版本开始引入) 自动触发 compaction，从而提高 Compaction Filter 的 GC 速度。如果遇到上述情况，建议调整这两个参数，无需关闭 Compaction Filter。 +> - 从 TiDB v7.5.7 和 v8.5.4 开始，[`region-compact-min-redundant-rows`](/tikv-configuration-file.md#region-compact-min-redundant-rows-从-v710-版本开始引入) 和 [`region-compact-redundant-rows-percent`](/tikv-configuration-file.md#region-compact-redundant-rows-percent-从-v710-版本开始引入) 已废弃，TiDB 会根据 [`gc.auto-compaction.redundant-rows-threshold`](/tikv-configuration-file.md#redundant-rows-threshold-从-v757-和-v854-版本开始引入) 和 [`gc.auto-compaction.redundant-rows-percent-threshold`](/tikv-configuration-file.md#redundant-rows-percent-threshold-从-v757-和-v854-版本开始引入) 自动触发 compaction。如果遇到上述情况，建议调整这两个参数，无需关闭 Compaction Filter。 diff --git a/garbage-collection-overview.md b/garbage-collection-overview.md index bf69491ac660..9e3d832b555d 100644 --- a/garbage-collection-overview.md +++ b/garbage-collection-overview.md @@ -1,6 +1,5 @@ --- title: GC 机制简介 -aliases: ['/docs-cn/dev/garbage-collection-overview/','/docs-cn/dev/reference/garbage-collection/overview/'] summary: TiDB 的事务实现采用了 MVCC 机制，GC 的任务是清理不再需要的旧数据。整体流程包括 GC leader 控制 GC 的运行，定期触发 GC，以及三个步骤：Resolve Locks 清理锁，Delete Ranges 删除区间，Do GC 进行 GC 清理。Resolve Locks 清理锁有两种执行模式：LEGACY 和 PHYSICAL。Delete Ranges 删除区间会快速物理删除待删除的区间及删除操作的时间戳。Do GC 进行 GC 清理会删除所有 key 的过期版本。GC 每 10 分钟触发一次，默认保留最近 10 分钟内的数据。 --- diff --git a/generate-self-signed-certificates.md b/generate-self-signed-certificates.md index 7fd220c1b4e4..70a47aa8af0d 100644 --- a/generate-self-signed-certificates.md +++ b/generate-self-signed-certificates.md @@ -1,6 +1,5 @@ --- title: 生成自签名证书 -aliases: ['/docs-cn/dev/generate-self-signed-certificates/','/docs-cn/dev/how-to/secure/generate-self-signed-certificates/'] summary: 本文介绍了使用 openssl 生成自签名证书的示例。用户可以根据需要生成符合要求的证书和密钥。首先安装 OpenSSL，然后生成 CA 证书和各个组件的证书，最后为客户端签发证书。证书的作用是为各个组件和客户端验证身份。 --- diff --git a/generated-columns.md b/generated-columns.md index daeb76e8551b..abe45759112d 100644 --- a/generated-columns.md +++ b/generated-columns.md @@ -1,6 +1,5 @@ --- title: 生成列 -aliases: ['/docs-cn/dev/generated-columns/','/docs-cn/dev/reference/sql/generated-columns/'] summary: 生成列是由列定义中的表达式计算得到的值。它包括存储生成列和虚拟生成列，存储生成列会将计算得到的值存储起来，而虚拟生成列不会存储其值。生成列可以用于从 JSON 数据类型中解出数据，并为该数据建立索引。在 INSERT 和 UPDATE 语句中，会检查生成列计算得到的值是否满足生成列的定义。生成列的局限性包括不能增加存储生成列，不能转换存储生成列为普通列，不能修改存储生成列的生成列表达式，以及不支持所有的 JSON 函数。 --- @@ -161,3 +160,8 @@ desc select a+1 from t where a+1=3; - 并未支持所有的 [JSON 函数](/functions-and-operators/json-functions.md)； - 不支持使用 [`NULLIF()` 函数](/functions-and-operators/control-flow-functions.md#nullif)，可以使用 [`CASE` 函数](/functions-and-operators/control-flow-functions.md#case)代替； - 目前仅当生成列是虚拟生成列时索引生成列替换规则有效，暂不支持将表达式替换为存储生成列，但仍然可以通过直接使用该生成列本身来使用索引。 +- 生成列定义中不能使用以下函数和表达式，如果使用，TiDB 会返回错误： + + - 非确定性函数和表达式，例如 `RAND`、`UUID` 和 `CURRENT_TIMESTAMP`。 + - 依赖于特定会话状态或全局状态的函数，例如 `CONNECTION_ID` 和 `CURRENT_USER`。 + - 影响系统状态或执行系统交互的函数，例如 `GET_LOCK`、`RELEASE_LOCK` 和 `SLEEP`。 \ No newline at end of file diff --git a/geo-distributed-deployment-topology.md b/geo-distributed-deployment-topology.md index f0c453d18afb..a4f62ea772a8 100644 --- a/geo-distributed-deployment-topology.md +++ b/geo-distributed-deployment-topology.md @@ -1,7 +1,6 @@ --- title: 跨数据中心部署拓扑 summary: 介绍跨数据中心部署 TiDB 集群的拓扑结构。 -aliases: ['/docs-cn/dev/geo-distributed-deployment-topology/'] --- # 跨数据中心部署拓扑 @@ -17,6 +16,10 @@ aliases: ['/docs-cn/dev/geo-distributed-deployment-topology/'] | TiKV | 5 | 16 VCore 32GB 4TB (nvme ssd) * 1 | 10.0.1.11
10.0.1.12
10.0.1.13
10.0.1.14 | 10.0.1.15 | 默认端口
全局目录配置 | | Monitoring & Grafana | 1 | 4 VCore 8GB * 1 500GB (ssd) | 10.0.1.16 || 默认端口
全局目录配置 | +> **注意：** +> +> 该表中拓扑实例的 IP 为示例 IP。在实际部署时，请替换为实际的 IP。 + ### 拓扑模版
diff --git a/get-started-with-tidb-lightning.md b/get-started-with-tidb-lightning.md index a8cfcbb69086..3f74b6ae26bd 100644 --- a/get-started-with-tidb-lightning.md +++ b/get-started-with-tidb-lightning.md @@ -1,6 +1,5 @@ --- title: TiDB Lightning 快速上手 -aliases: ['/docs-cn/dev/get-started-with-tidb-lightning/','/docs-cn/dev/how-to/get-started/tidb-lightning/'] summary: TiDB Lightning 可快速将 MySQL 数据导入到 TiDB 集群中。首先使用 Dumpling 导出数据，然后部署 TiDB 集群。安装最新版本的 TiDB Lightning 并启动，最后检查数据导入情况。详细功能和使用请参考 TiDB Lightning 简介。 --- diff --git a/global-indexes.md b/global-indexes.md new file mode 100644 index 000000000000..0ca43adc515d --- /dev/null +++ b/global-indexes.md @@ -0,0 +1,320 @@ +--- +title: 全局索引 +summary: 介绍 TiDB 全局索引的适用场景、优势、使用方法、工作原理及其限制等。 +--- + +# 全局索引 + +在引入全局索引 (Global Index) 之前，TiDB 会为每个分区创建一个本地索引 (Local Index)，即一个分区对应一个本地索引。这种索引方式存在一个[使用限制](/partitioned-table.md#分区键主键和唯一键)：主键和唯一键必须包含所有的分区键，以确保数据的全局唯一性。此外，当查询的数据跨越多个分区时，TiDB 需要扫描各个分区的数据才能返回结果。 + +为解决这些问题，TiDB 从 [v8.3.0](/releases/release-8.3.0.md) 开始引入全局索引。全局索引能覆盖整个表的数据，使得主键和唯一键在不包含分区键的情况下仍能保持全局唯一性。此外，全局索引可以在一次操作中访问多个分区的索引数据，而无需对每个分区的本地索引逐一查找，显著提升了针对非分区键的查询性能。从 v8.5.4 开始，非唯一索引也可以创建为全局索引。 + +## 优势 + +全局索引可以显著提升查询性能，增强索引设计灵活性，降低数据迁移和应用修改成本。 + +### 提升查询性能 + +全局索引能够有效提高检索非分区列的效率。当查询涉及非分区列时，全局索引可以快速定位相关数据，避免了对所有分区的全表扫描，可以显著降低协处理任务 (Coprocessor Task) 的数量，这对于分区数量庞大的场景尤为有效。 + +经过测试，在分区数量为 100 的情况下，sysbench `select_random_points` 场景的性能提升了 53 倍。 + +### 增强索引设计灵活性 + +全局索引消除了分区表中唯一键必须包含所有分区列的限制。这让你在设计索引时更加灵活，可以根据实际的查询需求和业务逻辑来创建索引，而不再受限于表的分区方案。这种灵活性不仅有助于优化查询性能，还能更好地满足多样化的业务需求。 + +### 降低数据迁移和应用修改成本 + +在数据迁移和应用修改过程中，全局索引可以显著减少额外的调整工作。如果没有全局索引，你可能需要更改分区方案或者重写查询语句，以适应索引的限制。而使用全局索引之后，可以避免这些修改，从而降低开发和维护成本。 + +例如，将 Oracle 数据库中的某张表迁移到 TiDB 时，因为 Oracle 支持全局索引，某些表中可能存在一些不包含分区列的唯一索引。在 TiDB 引入全局索引之前，你需要调整表结构以适应 TiDB 的分区表限制。在 TiDB 支持全局索引后，你只需在迁移时简单地修改索引定义，将其设置为全局索引，即可与 Oracle 保持一致，从而大幅降低迁移成本。 + +## 使用限制 + +- 如果索引定义中未显式指定 `GLOBAL` 关键字，TiDB 将默认创建本地索引 (Local Index)。 +- `GLOBAL` 和 `LOCAL` 关键字仅适用于分区表，对非分区表没有影响。即在非分区表中，全局索引和本地索引之间没有区别。 +- 以下 DDL 操作会触发全局索引的更新：`DROP PARTITION`、`TRUNCATE PARTITION` 和 `REORGANIZE PARTITION`。这些 DDL 需等待全局索引更新完成后才会返回结果，因此耗时会相应增加。尤其是在数据归档场景下，如 `DROP PARTITION` 和 `TRUNCATE PARTITION`，如果没有全局索引，通常可以立即完成；但使用全局索引后，耗时会随着需要更新的索引数量的增加而增加。 +- 包含全局索引的表不支持 `EXCHANGE PARTITION`。 +- 默认情况下，分区表的主键为聚簇索引，且必须包含分区键。如果要求主键不包含分区建，可以在建表时显式指定主键为非聚簇的全局索引，例如：`PRIMARY KEY(col1, col2) NONCLUSTERED GLOBAL`。 +- 如果全局索引建立在表达式列上，或者全局索引同时也是前缀索引（例如 `UNIQUE KEY idx_id_prefix (id(10)) GLOBAL`），则需要手动为该全局索引收集统计信息。 + +## 功能演进 + +- **v7.6.0 之前**：TiDB 仅支持分区表的本地索引。这意味着，分区表上的唯一键必须包含分区表达式中的所有列。如果查询条件中没有使用分区键，则查询需要扫描所有分区，导致查询性能下降。 +- **[v7.6.0](/releases/release-7.6.0.md)**：引入了系统变量 [`tidb_enable_global_index`](/system-variables.md#tidb_enable_global_index-从-v760-版本开始引入)，用于开启全局索引功能。然而，当时该功能仍在开发中，不推荐启用。 +- **[v8.3.0](/releases/release-8.3.0.md)**：全局索引作为实验特性发布。你可以在创建索引时使用 `GLOBAL` 关键字来显式创建全局索引。 +- **[v8.4.0](/releases/release-8.4.0.md)**：全局索引功能正式发布 (GA)。你可以直接使用 `GLOBAL` 关键字创建全局索引，无需再设置系统变量 `tidb_enable_global_index`。从该版本开始，该系统变量被废弃，且变量值固定为 `ON`，即默认启用全局索引。 +- **[v8.5.0](/releases/release-8.5.0.md)**：全局索引支持包含分区表达式中的所有列。 + +## 全局索引和本地索引 + +下图展示了本地索引和全局索引的区别： + +![Global Index vs. Local Index](/media/global-index-vs-local-index.png) + +**全局索引的适用场景**： + +- **数据归档不频繁**：例如，医疗行业的部分业务数据需要保存 30 年，通常按月分区，然后一次性创建 360 个分区，且很少进行 `DROP` 或 `TRUNCATE` 操作。在这种情况下，使用全局索引更为合适，能够提供跨分区的一致性和查询性能。 +- **查询需要跨分区的数据**：当查询需要访问多个分区的数据时，全局索引可以避免跨分区扫描，提高查询效率。 + +**本地索引的适用场景**： + +- **数据归档需求**：如果数据归档操作很频繁，且主要查询集中在单个分区内，本地索引可以提供更好的性能。 +- **需要使用分区交换功能**：在银行等行业，可能会将处理后的数据先写入普通表，确认无误后再交换到分区表，以减少对分区表性能的影响。此时，本地索引更为适用，因为一旦使用了全局索引，分区表将不再支持分区交换功能。 + +## 全局索引和聚簇索引 + +由于聚簇索引和全局索引的原理限制，一个索引不能同时作为聚簇索引和全局索引。然而，这两种索引在不同查询场景中能提供不同的性能优化。在遇到需要同时兼顾两者的需求时，你可以将分区列添加到聚簇索引中，同时创建一个不包含分区列的全局索引。 + +假设有如下表结构： + +```sql +CREATE TABLE `t` ( + `id` int DEFAULT NULL, + `ts` timestamp NULL DEFAULT NULL, + `data` varchar(100) DEFAULT NULL +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin +PARTITION BY RANGE (UNIX_TIMESTAMP(`ts`)) +(PARTITION `p0` VALUES LESS THAN (1735660800) + PARTITION `p1` VALUES LESS THAN (1738339200) + ...) +``` + +在上面的 `t` 表中，`id` 列的值是唯一的。为了优化点查和范围查询的性能，可以选择在建表语句中定义一个聚簇索引 `PRIMARY KEY(id, ts)` 和一个不包含分区列的全局索引 `UNIQUE KEY id(id)`。这样在进行基于 `id` 的点查询时，会采用全局索引 `id`，选择 `PointGet` 的执行计划；而在进行范围查询时，聚簇索引则会被选中，因为聚簇索引相比全局索引少了一次回表操作，从而提升查询效率。 + +修改后的表结构如下所示： + +```sql +CREATE TABLE `t` ( + `id` int NOT NULL, + `ts` timestamp NOT NULL, + `data` varchar(100) DEFAULT NULL, + PRIMARY KEY (`id`, `ts`) /*T![clustered_index] CLUSTERED */, + UNIQUE KEY `id` (`id`) /*T![global_index] GLOBAL */ +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin +PARTITION BY RANGE (UNIX_TIMESTAMP(`ts`)) +(PARTITION `p0` VALUES LESS THAN (1735660800), + PARTITION `p1` VALUES LESS THAN (1738339200) + ...) +``` + +这种方式既能优化基于 `id` 的点查询，又能提升范围查询的性能，同时确保表的分区列在基于时间戳的查询中能得到有效利用。 + +## 使用方法 + +如果你需要创建全局索引，则在索引定义中添加 `GLOBAL` 关键字。 + +> **注意：** +> +> 全局索引会影响分区管理。执行 `DROP`、`TRUNCATE` 和 `REORGANIZE PARTITION` 操作会触发表级别全局索引的更新，这意味着这些 DDL 操作只有在对应表的全局索引更新完成后才会返回结果，耗时可能会增加。 + +```sql +CREATE TABLE t1 ( + col1 INT NOT NULL, + col2 DATE NOT NULL, + col3 INT NOT NULL, + col4 INT NOT NULL, + UNIQUE KEY uidx12(col1, col2) GLOBAL, + UNIQUE KEY uidx3(col3), + KEY idx1(col1) GLOBAL +) +PARTITION BY HASH(col3) +PARTITIONS 4; +``` + +在上述示例中，唯一索引 `uidx12` 和非唯一索引 `idx1` 将成为全局索引，但 `uidx3` 仍是常规的唯一索引。 + +请注意，**聚簇索引**不能成为全局索引，示例如下： + +```sql +CREATE TABLE t2 ( + col1 INT NOT NULL, + col2 DATE NOT NULL, + PRIMARY KEY (col2) CLUSTERED GLOBAL +) PARTITION BY HASH(col1) PARTITIONS 5; +``` + +``` +ERROR 1503 (HY000): A CLUSTERED INDEX must include all columns in the table's partitioning function +``` + +聚簇索引不能同时作为全局索引。原因在于，如果聚簇索引是全局索引，则表将不再分区。聚簇索引的键是分区级别的行数据的键，但全局索引是表级别的，这就产生了冲突。如果需要将主键设置为全局索引，则需要显式设置该主键为非聚簇索引，例如： + +```sql +PRIMARY KEY(col1, col2) NONCLUSTERED GLOBAL +``` + +你可以通过 [`SHOW CREATE TABLE`](/sql-statements/sql-statement-show-create-table.md) 输出中的 `GLOBAL` 索引选项来识别全局索引。 + +```sql +SHOW CREATE TABLE t1\G +``` + +``` + Table: t1 +Create Table: CREATE TABLE `t1` ( + `col1` int NOT NULL, + `col2` date NOT NULL, + `col3` int NOT NULL, + `col4` int NOT NULL, + UNIQUE KEY `uidx12` (`col1`,`col2`) /*T![global_index] GLOBAL */, + UNIQUE KEY `uidx3` (`col3`), + KEY `idx1` (`col1`) /*T![global_index] GLOBAL */ +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin +PARTITION BY HASH (`col3`) PARTITIONS 4 +1 row in set (0.00 sec) +``` + +或查询 [`INFORMATION_SCHEMA.TIDB_INDEXES`](/information-schema/information-schema-tidb-indexes.md) 表并查看输出中的 `IS_GLOBAL` 列来识别全局索引。 + +```sql +SELECT * FROM information_schema.tidb_indexes WHERE table_name='t1'; +``` + +``` ++--------------+------------+------------+----------+--------------+-------------+----------+---------------+------------+----------+------------+-----------+-----------+ +| TABLE_SCHEMA | TABLE_NAME | NON_UNIQUE | KEY_NAME | SEQ_IN_INDEX | COLUMN_NAME | SUB_PART | INDEX_COMMENT | Expression | INDEX_ID | IS_VISIBLE | CLUSTERED | IS_GLOBAL | ++--------------+------------+------------+----------+--------------+-------------+----------+---------------+------------+----------+------------+-----------+-----------+ +| test | t1 | 0 | uidx12 | 1 | col1 | NULL | | NULL | 1 | YES | NO | 1 | +| test | t1 | 0 | uidx12 | 2 | col2 | NULL | | NULL | 1 | YES | NO | 1 | +| test | t1 | 0 | uidx3 | 1 | col3 | NULL | | NULL | 2 | YES | NO | 0 | +| test | t1 | 1 | idx1 | 1 | col1 | NULL | | NULL | 3 | YES | NO | 1 | ++--------------+------------+------------+----------+--------------+-------------+----------+---------------+------------+----------+------------+-----------+-----------+ +3 rows in set (0.00 sec) +``` + +在对普通表进行分区或者对分区表进行重新分区时，可以根据需要将索引更新为全局索引或本地索引。 + +例如，下面的 SQL 语句会基于 `col1` 列对表 `t1` 进行重新分区，并将该表中的全局索引 `uidx12` 和 `idx1` 更新为本地索引，将本地索引 `uidx3` 更新为全局索引。`uidx3` 是基于 `col3` 列的唯一索引，为了保证 `col3` 在所有分区中的唯一性，`uidx3` 必须为全局索引；`uidx12` 和 `idx1` 是基于 `col1` 列的索引，因此可以是全局索引或本地索引。 + +```sql +ALTER TABLE t1 PARTITION BY HASH (col1) PARTITIONS 3 UPDATE INDEXES (uidx12 LOCAL, uidx3 GLOBAL, idx1 LOCAL); +``` + +## 工作原理 + +本节介绍全局索引的工作机制，包括其设计理念与编码方式。 + +### 设计理念 + +在 TiDB 的分区表中，本地索引的键值前缀是分区表的 ID，而全局索引的前缀是表的 ID。这样的改进能够确保全局索引的数据在 TiKV 上连续分布，从而减少查询索引时的 RPC 请求数量。 + +```sql +CREATE TABLE `sbtest` ( + `id` int(11) NOT NULL, + `k` int(11) NOT NULL DEFAULT '0', + `c` char(120) NOT NULL DEFAULT '', + KEY idx(k), + KEY global_idx(k) GLOBAL +) partition by hash(id) partitions 5; +``` + +以上述表结构为例，`idx` 为本地索引（普通索引），`global_idx` 为全局索引。索引 `idx` 的数据会分布在 5 个不同的 Range 中，如 `PartitionID1_i_xxx`、`PartitionID2_i_xxx` 等，而索引 `global_idx` 的数据则会集中在一个 Range (`TableID_i_xxx`) 内。 + +当执行与 `k` 相关的查询时，如 `SELECT * FROM sbtest WHERE k > 1`，通过普通索引 `idx` 会构造 5 个不同的 Range，而通过全局索引 `global_idx` 则只会构造 1 个 Range。每个 Range 在 TiDB 中对应一个或多个 RPC 请求。因此，使用全局索引可以降低数倍的 RPC 请求数，从而提升查询索引的性能。 + +下图直观地展示了在使用 `idx` 和 `global_idx` 两个不同索引执行 `SELECT * FROM sbtest WHERE k > 1` 查询语句时，在 RPC 请求和数据流转过程中的差异： + +![Mechanism of Global Indexes](/media/global-index-mechanism.png) + +### 编码方式 + +在 TiDB 中，索引项被编码为键值对。对于分区表，每个分区在 TiKV 层被视为一个独立的物理表，拥有自己的 `partitionID`。因此，分区表的索引项编码如下： + +``` +唯一键 +Key: +- PartitionID_indexID_ColumnValues + +Value: +- IntHandle + - TailLen_IntHandle + +- CommonHandle + - TailLen_IndexVersion_CommonHandle + +非唯一键 +Key: +- PartitionID_indexID_ColumnValues_Handle + +Value: +- IntHandle + - TailLen_Padding + +- CommonHandle + - TailLen_IndexVersion +``` + +在全局索引中，索引项的编码方式有所不同。为了使全局索引的键布局与当前索引键编码保持兼容，新的索引编码布局如下： + +``` +唯一键 +Key: +- TableID_indexID_ColumnValues + +Value: +- IntHandle + - TailLen_PartitionID_IntHandle + +- CommonHandle + - TailLen_IndexVersion_CommonHandle_PartitionID + +非唯一键 +Key: +- TableID_indexID_ColumnValues_Handle + +Value: +- IntHandle + - TailLen_PartitionID + +- CommonHandle + - TailLen_IndexVersion_PartitionID +``` + +这种编码方式使得全局索引的键以 `TableID` 开头，而 `PartitionID` 被放置在 Value 中。这样设计的优点是与现有的索引键编码方式兼容。然而，这也带来了一些挑战，例如在执行 `DROP PARTITION`、`TRUNCATE PARTITION` 等 DDL 操作时，由于索引项不连续，需要进行额外处理。 + +## 性能测试数据 + +以下测试基于 sysbench 的 `select_random_points` 场景，主要用于对比不同分区策略与索引方式下的查询性能。 + +测试表的表结构如下： + +```sql +CREATE TABLE `sbtest` ( + `id` int(11) NOT NULL, + `k` int(11) NOT NULL DEFAULT '0', + `c` char(120) NOT NULL DEFAULT '', + `pad` char(60) NOT NULL DEFAULT '', + PRIMARY KEY (`id`) /*T![clustered_index] CLUSTERED */, + KEY `k_1` (`k`) + /* Key `k_1` (`k`, `c`) GLOBAL */ +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin +/* Partition by hash(`id`) partitions 100 */ +/* Partition by range(`id`) xxxx */ +``` + +负载 SQL 如下： + +```sql +SELECT id, k, c, pad +FROM sbtest +WHERE k IN (xx, xx, xx) +``` + +Range Partition (100 partitions): + +| Table type | Concurrency 1 | Concurrency 32 | Concurrency 64 | Average RU | +| --------------------------------------------------------------------- | ------------- | -------------- | -------------- | ---------- | +| Clustered non-partitioned table | 225 | 19,999 | 30,293 | 7.92 | +| Clustered table range partitioned by PK | 68 | 480 | 511 | 114.87 | +| Clustered table range partitioned by PK, with Global Index on `k`, `c` | 207 | 17,798 | 27,707 | 11.73 | + +Hash Partition (100 partitions): + +| Table type | Concurrency 1 | Concurrency 32 | Concurrency 64 | Average RU | +| -------------------------------------------------------------------- | ------------- | -------------- | -------------- | ---------- | +| Clustered non-partitioned table | 166 | 20,361 | 28,922 | 7.86 | +| Clustered table hash partitioned by PK | 60 | 244 | 283 | 119.73 | +| Clustered table hash partitioned by PK, with Global Index on `k`, `c` | 156 | 18,233 | 15,581 | 10.77 | + +通过上述测试可以看出，在高并发环境下，全局索引能够显著提升分区表查询性能，提升幅度可达 50 倍。同时，全局索引还能够显著降低资源 (RU) 消耗。随着分区数量的增加，这种性能提升的效果将愈加明显。 diff --git a/glossary.md b/glossary.md index a7cca1ab7e7e..85cd9a796ed8 100644 --- a/glossary.md +++ b/glossary.md @@ -1,7 +1,6 @@ ---- +--- title: 术语表 summary: 了解 TiDB 相关术语。 -aliases: ['/docs-cn/dev/glossary/'] --- # 术语表 @@ -14,7 +13,7 @@ aliases: ['/docs-cn/dev/glossary/'] - [TiCDC 术语表](/ticdc/ticdc-glossary.md) - [TiDB Lightning 术语表](/tidb-lightning/tidb-lightning-glossary.md) -## A +## A ### ACID @@ -25,7 +24,7 @@ ACID 是指数据库管理系统在写入或更新资料的过程中，为保证 * 隔离性 (isolation) 指数据库允许多个并发事务同时对其数据进行读写和修改的能力。隔离性可以防止多个事务并发执行时由于交叉执行而导致数据的不一致，主要用于处理并发场景。关于 TiDB 支持的隔离级别，请参考 [TiDB 事务隔离级别](/transaction-isolation-levels.md#tidb-事务隔离级别)。 * 持久性 (durability) 指事务处理结束后，对数据的修改就是永久的，即便系统故障也不会丢失。在 TiDB 中，事务一旦提交成功，数据全部持久化存储到 TiKV，此时即使 TiDB 服务器宕机也不会出现数据丢失。 -## B +## B ### Backup & Restore (BR) @@ -35,7 +34,7 @@ ACID 是指数据库管理系统在写入或更新资料的过程中，为保证 ### Batch Create Table -批量建表 (Batch Create Table) 是在 TiDB v6.0.0 中引入的新功能，此功能默认开启。当需要恢复的数据中带有大量的表（约 50000 张）时，批量建表功能显著提升数据恢复的速度。详情参见[批量建表](/br/br-batch-create-table.md)。 +批量建表功能 (Batch Create Table) 可以通过批量创建表的方式显著提升多表同时创建的速度。例如，当使用[备份与恢复 (BR)](/br/backup-and-restore-overview.md) 工具恢复数千张表时，该功能有助于缩短整体恢复的整体时长。详情参见[批量建表](/br/br-batch-create-table.md)。 ### Baseline Capturing @@ -45,12 +44,24 @@ ACID 是指数据库管理系统在写入或更新资料的过程中，为保证 一个 [Region](#regionpeerraft-group) 在逻辑上划分为多个小范围，称为 bucket。TiKV 按 bucket 收集查询统计数据，并将 bucket 的情况报告给 PD。详情参见 [Bucket 设计文档](https://github.com/tikv/rfcs/blob/master/text/0082-dynamic-size-region.md#bucket)。 -## C +## C ### Cached Table 缓存表 (Cached Table) 是指 TiDB 把整张表的数据加载到服务器的内存中，直接从内存中获取表数据，避免从 TiKV 获取表数据，从而提升读性能。详情参见[缓存表](/cached-tables.md)。 +### Cluster + +集群由一组协同工作以提供服务的节点组成。与单节点架构相比，TiDB 采用分布式集群架构，实现了更高的可用性和更强的可扩展性。 + +在 TiDB 数据库的分布式架构中： + +- TiDB 节点提供可扩展的 SQL 层以供客户端交互。 +- PD 节点提供弹性的元数据层以支持 TiDB。 +- TiKV 节点使用 Raft 协议，为 TiDB 提供高可用、可扩展和有弹性的存储服务。 + +详情参见 [TiDB 架构](/tidb-architecture.md)。 + ### Coalesce Partition Coalesce Partition 是一种减少 Hash 分区表或 Key 分区表中分区数量的方法。详情参见[管理 Hash 分区和 Key 分区](/partitioned-table.md#管理-hash-分区和-key-分区)。 @@ -61,17 +72,21 @@ Coalesce Partition 是一种减少 Hash 分区表或 Key 分区表中分区数 ### 公共表表达式 (CTE) -公共表表达式 (Common Table Expression, CTE) 用于定义一个临时结果集，能够在 SQL 语句中通过 [`WITH`](/sql-statements/sql-statement-with.md) 子句多次引用。更多信息，请参见[公共表表达式](/develop/dev-guide-use-common-table-expression.md)。 +公共表表达式 (Common Table Expression, CTE) 用于定义一个临时结果集，能够在 SQL 语句中通过 [`WITH`](/sql-statements/sql-statement-with.md) 子句多次引用，提高 SQL 语句的可读性与执行效率。更多信息，请参见[公共表表达式](/develop/dev-guide-use-common-table-expression.md)。 ### Continuous Profiling -持续性能分析 (Continuous Profiling) 是从 TiDB v5.3 起引入的一种从系统调用层面解读资源开销的方法。引入该方法后，TiDB 可提供数据库源码级性能观测，通过火焰图的形式帮助研发、运维人员定位性能问题的根因。详情参见 [TiDB Dashboard 实例性能分析 - 持续分析页面](/dashboard/continuous-profiling.md)。 +持续性能分析 (Continuous Profiling) 是一种从系统调用层面解读资源开销的方法。通过持续性能分析，TiDB 可提供对性能问题的细粒度观测，帮助运维团队使用火焰图定位性能问题的根本原因。详情参见 [TiDB Dashboard 实例性能分析 - 持续分析页面](/dashboard/continuous-profiling.md)。 + +### Coprocessor -## D +Coprocessor 是一种替 TiDB 分担计算工作负载的协处理机制。它位于存储层（TiKV 或 TiFlash），以 Region 为单位协同处理从 TiDB 下推的计算。更多信息，请参见[下推到 TiKV 的表达式列表](/functions-and-operators/expressions-pushed-down.md)。 + +## D ### Data Definition Language (DDL) -数据定义语言 (Data Definition Language, DDL) 是 SQL 标准的一部分，用于创建、修改和删除表及其他对象。更多信息，请参见 [DDL 语句的执行原理及最佳实践](/ddl-introduction.md)。 +数据定义语言 (Data Definition Language, DDL) 是 SQL 标准的一部分，用于创建、修改和删除表及其他对象。更多信息，请参见 [DDL 语句的执行原理及最佳实践](/best-practices/ddl-introduction.md)。 ### Data Migration (DM) @@ -89,6 +104,10 @@ TiDB 会在开发里程碑版本 (Development Milestone Release, DMR) 中引入 容灾 (Disaster Recovery, DR) 是在未来灾难发生时恢复数据和服务的解决方案。TiDB 提供了多种容灾方案，例如备份和复制数据到备用集群。更多信息，请参见 [TiDB 容灾方案概述](/dr-solution-introduction.md)。 +### Dumpling + +Dumpling 是一款数据导出工具，用于将存储在 TiDB、MySQL 或 MariaDB 中的数据导出为 SQL 或 CSV 数据文件，也可用于逻辑全量备份或导出。Dumpling 也支持将数据导出到 Amazon S3 中。详情参见[使用 Dumpling 导出数据](/dumpling-overview.md)。 + ### 分布式执行框架 (DXF) 分布式执行框架 (Distributed eXecution Framework, DXF) 允许 TiDB 在处理特定任务（例如创建索引或导入数据）时对这些任务进行统一调度和分布式执行。该框架旨在高效利用集群资源执行任务，控制资源使用，以减少对核心业务事务的影响。更多信息，请参见 [TiDB 分布式执行框架](/tidb-distributed-execution-framework.md)。 @@ -97,7 +116,15 @@ TiDB 会在开发里程碑版本 (Development Milestone Release, DMR) 中引入 动态裁剪 (Dynamic Pruning) 是 TiDB 访问分区表的两种模式之一。在动态裁剪模式下，TiDB 的每个算子都支持直接访问多个分区，省略 Union 操作，提高执行效率，还避免了 Union 并发管理的问题。 -## G +## E + +### Expression index + +表达式索引 (expression index) 是一种特殊的索引，能将索引建立于表达式上。在创建了表达式索引后，基于表达式的查询便可以使用上索引，极大提升查询的性能。 + +详情参见 [CREATE INDEX - 表达式索引](/sql-statements/sql-statement-create-index.md#表达式索引)。 + +## G ### Garbage Collection (GC) @@ -111,13 +138,17 @@ TiDB 会在开发里程碑版本 (Development Milestone Release, DMR) 中引入 全局事务标识符 (Global Transaction Identifiers, GTIDs) 是在 MySQL 二进制日志中跟踪已复制事务的唯一标识符。[Data Migration (DM)](/dm/dm-overview.md) 在迁移数据时会使用这些标识符确保复制的一致性。 -## H +## H + +### Hotspot + +热点 (Hotspot) 指 TiKV 的读写负载集中于某一个或几个 Region 或节点的现象，此时可能会造成性能瓶颈，使性能无法达到最佳。要解决热点问题，可参考 [TiDB 热点问题处理](/troubleshoot-hot-spot-issues.md)。 ### Hybrid Transactional and Analytical Processing (HTAP) -混合型在线事务与在线分析处理 (Hybrid Transactional and Analytical Processing, HTAP) 功能支持在同一数据库中同时处理 OLTP（联机事务处理）和 OLAP（联机分析处理）工作负载。在 TiDB 中，HTAP 是通过使用 TiKV 进行行存以及使用进行 TiFlash 进行列存来实现的。更多信息，请参见 [Gartner 网站上的 HTAP 定义](https://www.gartner.com/en/information-technology/glossary/htap-enabling-memory-computing-technologies)。 +混合型在线事务与在线分析处理 (Hybrid Transactional and Analytical Processing, HTAP) 功能支持在同一数据库中同时处理 OLTP（联机事务处理）和 OLAP（联机分析处理）工作负载。在 TiDB 中，HTAP 是通过使用 TiKV 进行行存以及使用进行 TiFlash 进行列存来实现的。更多信息，参见 [HTAP 快速上手指南](/quick-start-with-htap.md)和 [HTAP 深入探索指南](/explore-htap.md)。 -## I +## I ### In-Memory Pessimistic Lock @@ -127,7 +158,7 @@ TiDB 会在开发里程碑版本 (Development Milestone Release, DMR) 中引入 索引合并 (Index Merge) 是在 TiDB v4.0 版本中作为实验特性引入的一种查询执行方式的优化，可以大幅提高查询在扫描多列数据时条件过滤的效率。自 v5.4 版本起，Index Merge 成为正式功能，详情参见[用 EXPLAIN 查看索引合并的 SQL 执行计划](/explain-index-merge.md)。 -## K +## K ### Key Management Service (KMS) @@ -137,7 +168,7 @@ TiDB 会在开发里程碑版本 (Development Milestone Release, DMR) 中引入 键值 (Key-Value, KV) 是一种通过唯一键来关联值并存储信息的数据结构，它能够实现快速的数据检索。TiDB 通过 TiKV 将表和索引映射为键值对，从而实现数据库中的高效数据存储和访问。 -## L +## L ### Leader/Follower/Learner @@ -147,17 +178,27 @@ TiDB 会在开发里程碑版本 (Development Milestone Release, DMR) 中引入 轻量级目录访问协议 (Lightweight Directory Access Protocol, LDAP) 是一种标准化的目录信息访问方式，通常用于账户和用户数据的管理。TiDB 对 LDAP 的支持是通过 [LDAP 身份验证插件](/security-compatibility-with-mysql.md#可用的身份验证插件)实现的。 +### Lock View + +锁视图 (Lock View) 特性用于提供关于悲观锁的锁冲突和锁等待的更多信息，方便 DBA 通过锁视图功能来观察事务加锁情况以及排查死锁问题。 + +详情参见系统表文档 [`TIDB_TRX`](/information-schema/information-schema-tidb-trx.md)、[`DATA_LOCK_WAITS`](/information-schema/information-schema-data-lock-waits.md) 和 [`DEADLOCKS`](/information-schema/information-schema-deadlocks.md)。 + ### Long Term Support (LTS) 长期支持 (Long Term Support, LTS) 版本指经过充分测试并在较长时间内维护的软件版本。更多信息，请参见 [TiDB 版本规则](/releases/versioning.md)。 -## M +## M ### Massively Parallel Processing (MPP) 从 v5.0 起，TiDB 通过 TiFlash 节点引入了 Massively Parallel Processing (MPP) 架构。这使得大型表连接类查询可以由不同 TiFlash 节点共同分担完成。当 MPP 模式开启后，TiDB 将会根据代价决定是否应该交由 MPP 框架进行计算。MPP 模式下，表连接将通过对 JOIN Key 进行数据计算时重分布（Exchange 操作）的方式把计算压力分摊到各个 TiFlash 执行节点，从而达到加速计算的目的。更多信息请参见[使用 MPP 模式](/tiflash/use-tiflash-mpp-mode.md)。 -## O +### Multi-version concurrency control (MVCC) + +[MVCC](https://zh.wikipedia.org/wiki/多版本并发控制)（多版本并发控制）是 TiDB 和其他数据库中的一种并发控制机制。它处理事务的内存读取，以实现对 TiDB 的并发访问，从而避免由并发读写冲突引起的阻塞。 + +## O ### Old value @@ -194,11 +235,21 @@ Operator Step 是 Operator 执行过程的一个步骤，一个 Operator 常常 - `PromoteLearner`：将指定 Learner 提升为 Follower - `SplitRegion`：将指定 Region 一分为二 -## P +### Optimistic transaction + +乐观事务是使用乐观并发控制的事务。在并发环境中，外界对数据的操作一般不会造成冲突。开启乐观事务后，TiDB 仅在事务最终提交时才会进行冲突检测。乐观事务模式适合读多写少的并发场景，能提高 TiDB 性能。 + +更多信息，请参见 [TiDB 乐观事务模型](/optimistic-transaction.md)。 + +## P ### Partitioning -[Partitioning](/partitioned-table.md)（分区）指通过 `RANGE`、`LIST`、`HASH` 和 `KEY` 等分区方法在物理上将一张表划分为较小的分区。 +[Partitioning](/partitioned-table.md)（分区）指通过 `RANGE`、`LIST`、`HASH` 和 `KEY` 等分区方法在物理上将一张表划分为较小的分区。这些较小的分区为分区表 (Partitioned Table)。 + +### PD Control (pd-ctl) + +PD Control (pd-ctl) 是一个命令行工具，用于与 TiDB 集群中的 PD (Placement Driver) 组件进行交互。你可以用它获取集群状态信息以及修改集群配置。详情参见 [PD Control 使用说明](/pd-control.md)。 ### Pending/Down @@ -206,7 +257,13 @@ Pending 和 Down 是 Peer 可能出现的两种特殊状态。其中 Pending 表 ### Placement Driver (PD) -PD 是 [TiDB 架构](/tidb-architecture.md) 中的核心组件之一，负责存储元数据，为事务时间戳分配[时间戳服务 (TSO)](/tso.md)，协调 TiKV 上的数据分布，并运行 [TiDB Dashboard](/dashboard/dashboard-overview.md)。更多信息，请参见 [TiDB 调度](/tidb-scheduling.md)。 +PD 是 [TiDB 架构](/tidb-architecture.md)中的核心组件之一，负责存储元数据，为事务时间戳分配[时间戳服务 (TSO)](/tso.md)，协调 TiKV 上的数据分布，并运行 [TiDB Dashboard](/dashboard/dashboard-overview.md)。更多信息，请参见 [TiDB 调度](/tidb-scheduling.md)。 + +### Placement Rules + +Placement Rules 特性用于配置数据在 TiKV 集群中的放置位置。通过该功能，用户可以将表和分区指定部署至不同的地域、机房、机柜、主机。适用场景包括低成本优化数据高可用策略、保证本地的数据副本可用于本地 Stale Read 读取、遵守数据本地要求。 + +详情参见 [Placement Rules in SQL](/placement-rules-in-sql.md)。 ### Point get @@ -220,7 +277,7 @@ PITR 用于将数据恢复到特定时间点（例如，在意外执行了 `DELE 执行 SQL 语句时，优化器在大多数情况下只会用到部分列（例如，`WHERE`、`JOIN`、`ORDER BY`、`GROUP BY` 子句中出现的列）的统计信息，这些用到的列称为 `PREDICATE COLUMNS`。详情参见[收集部分列的统计信息](/statistics.md#收集部分列的统计信息)。 -## Q +## Q ### Queries Per Second (QPS) @@ -230,7 +287,7 @@ PITR 用于将数据恢复到特定时间点（例如，在意外执行了 `DELE 前台限流 (Quota Limiter) 是在 TiDB v6.0.0 版本中作为实验特性引入的功能。当 TiKV 部署的机型资源有限（如 4v CPU，16 G 内存）时，如果 TiKV 前台处理的读写请求量过大，会占用 TiKV 后台处理请求所需的 CPU 资源，最终影响 TiKV 性能的稳定性。此时，开启前台限流相关的 [quota 相关配置项](/tikv-configuration-file.md#quota)可以限制前台各类请求占用的 CPU 资源。 -## R +## R ### Raft Engine @@ -252,13 +309,17 @@ RPC（远程过程调用）是软件组件之间的一种通信方式。在 TiDB ### Request Unit (RU) -RU 是 TiDB 中资源使用的统一抽象单位，用于在[资源管控](/tidb-resource-control.md)功能中衡量资源的使用情况。 +RU 是 TiDB 中资源使用的统一抽象单位，用于在[资源管控](/tidb-resource-control-ru-groups.md)功能中衡量资源的使用情况。 ### Restore 备份操作的逆过程，即利用保存的备份数据还原出原始数据的过程。 -## S +### RocksDB + +[RocksDB](https://rocksdb.org/) 是一款提供键值存储与读写功能的 LSM-tree 架构引擎，由 Facebook 基于 LevelDB 开发。RocksDB 是 TiKV 的核心存储引擎。 + +## S ### Scheduler @@ -269,6 +330,18 @@ Scheduler（调度器）是 PD 中生成调度的组件。PD 中每个调度器 - `hot-region-scheduler`：保持不同节点的读写热点 Region 均衡。 - `evict-leader-{store-id}`：驱逐某个节点的所有 Leader。（常用于滚动升级） +### Security Enhanced Mode + +安全增强模式 (Security Enhanced Mode, SEM) 用于对 TiDB 管理员进行更细粒度的权限划分。受[安全增强式 Linux](https://zh.wikipedia.org/wiki/安全增强式Linux) 等系统设计的启发，SEM 削减了拥有 `SUPER` 权限的用户的能力，转而使用 `RESTRICTED` 细粒度权限作为替代，这些权限必须被显式授予以控制特定的管理操作。 + +详情参见[系统变量文档 - `tidb_enable_enhanced_security`](/system-variables.md#tidb_enable_enhanced_security)。 + +### Stale Read + +Stale Read 是 TiDB 的一种读取机制，用于读取 TiDB 中存储的历史数据版本。通过 Stale Read 功能，你可以从指定时间点或时间范围内读取对应的历史数据，从而缩短存储节点之间数据同步带来的延迟。当使用 Stale Read 时，TiDB 会随机选择一个副本来读取数据，这意味着所有副本都可用于数据读取。 + +详情参见 [Stale Read](/stale-read.md)。 + ### Static Sorted Table / Sorted String Table (SST) SST 是 RocksDB 使用的文件存储格式。RocksDB 是 [TiKV](/storage-engine/rocksdb-overview.md) 的一种存储引擎。 @@ -277,12 +350,40 @@ SST 是 RocksDB 使用的文件存储格式。RocksDB 是 [TiKV](/storage-engine PD 中的 Store 指的是集群中的存储节点，也就是 tikv-server 实例。Store 与 TiKV 实例是严格一一对应的，即使在同一主机甚至同一块磁盘部署多个 TiKV 实例，这些实例也对会对应不同的 Store。 -## T +## T + +### Temporary table + +临时表 (temporary table) 用于存储业务上的中间计算结果，让用户免于频繁地建表和删表等操作。数据用完后，TiDB 会自动清理并回收临时表。这种方式可以帮助你简化应用程序逻辑，减少表管理开销，并提升性能。 + +详情参见[临时表](/temporary-tables.md)。 + +### TiCDC + +[TiCDC](/ticdc/ticdc-overview.md) 是一款数据同步工具，支持将增量数据从 TiDB 复制到各种不同的下游目标系统。目前支持的下游包括 TiDB 实例、MySQL 兼容数据库、存储服务和流处理器（如 Kafka 和 Pulsar）。TiCDC 会拉取上游 TiKV 的数据变更日志，将其解析为有序的行级变更数据，然后输出到下游。更多关于 TiCDC 的概念和术语，参见 [TiCDC 术语表](/ticdc/ticdc-glossary.md)。 + +### TiDB Lightning + +[TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md) 是一款数据导入工具，用于从静态文件导入 TB 级数据到 TiDB 集群，常用于 TiDB 集群的初始化数据导入。 + +更多关于 TiDB Lightning 的概念和术语，参见 [TiDB Lightning 术语表](/tidb-lightning/tidb-lightning-glossary.md)。 + +### TiFlash + +[TiFlash](/tiflash/tiflash-overview.md) 是 TiDB HTAP 形态的关键组件，它是 TiKV 的列存扩展，在提供良好隔离性的同时，也兼顾了强一致性。列存副本通过 Raft Learner 协议异步复制 TiKV 的数据。在读取时，它通过 Raft 校对索引配合 MVCC（多版本并发控制）的方式获得 Snapshot Isolation 的一致性隔离级别。这个架构很好地解决了 HTAP 场景的隔离性以及列存同步的问题，在进行高效分析查询的同时保持实时数据的一致性。 + +### TiKV MVCC 内存引擎 (In-Memory Engine, IME) + +[TiKV MVCC 内存引擎 (IME)](/tikv-in-memory-engine.md) 在内存中缓存最近写入的 MVCC 版本，并实现独立于 TiDB 的 MVCC GC 机制，以加速涉及大量 MVCC 历史版本的查询。 ### Timestamp Oracle (TSO) 因为 TiKV 是一个分布式的储存系统，它需要一个全球性的授时服务 TSO (Timestamp Oracle)，来分配一个单调递增的时间戳。这样的功能在 TiKV 中是由 PD 提供的，在 Google 的 [Spanner](http://static.googleusercontent.com/media/research.google.com/en//archive/spanner-osdi2012.pdf) 中是由多个原子钟和 GPS 来提供的。详见 [TSO 文档](/tso.md)。 +### TiUP + +[TiUP](/tiup/tiup-overview.md) 是一款包管理工具，用于部署、升级和管理 TiDB 集群，以及管理 TiDB 集群中的各种组件，如 TiDB、PD、TiKV 等。通过使用 TiUP，你可以执行一行命令轻松运行 TiDB 中的任何组件，让管理过程更加简单。 + ### Top SQL Top SQL 用于找到一段时间内对某个 TiDB 或 TiKV 节点消耗负载较大的 SQL 查询。详见 [Top SQL 文档](/dashboard/top-sql.md)。 @@ -291,7 +392,7 @@ Top SQL 用于找到一段时间内对某个 TiDB 或 TiKV 节点消耗负载较 每秒事务数 (Transactions Per Second, TPS) 指的是数据库每秒处理的事务数量。它是衡量数据库性能和吞吐量的关键指标。 -## U +## U ### Uniform Resource Identifier (URI) @@ -299,4 +400,10 @@ Top SQL 用于找到一段时间内对某个 TiDB 或 TiKV 节点消耗负载较 ### Universally Unique Identifier (UUID) -通用唯一标识符 (Universally Unique Identifier, UUID) 是一种 128 位（16 字节）的生成 ID，用于在数据库中唯一地标识记录。更多信息，请参见 [UUID](/best-practices/uuid.md)。 \ No newline at end of file +通用唯一标识符 (Universally Unique Identifier, UUID) 是一种 128 位（16 字节）的生成 ID，用于在数据库中唯一地标识记录。更多信息，请参见[将 UUID 用作主键的最佳实践](/best-practices/uuid.md)。 + +## V + +### Vector Search + +[向量搜索 (Vector Search)](/develop/dev-guide-vector-search.md) 是一种优先考虑数据语义以提供相关结果的搜索方法。与传统的全文搜索主要依赖于精确的关键词匹配和词频不同，向量搜索通过将不同类型的数据（如文本、图像或音频）转换为高维向量，并根据这些向量之间的相似度来进行查询。这种搜索方法能够捕捉数据的语义特征和上下文信息，从而更准确地理解用户意图。即使搜索的词语与数据库中的内容不完全匹配，向量搜索仍然可以通过对数据语义的理解，找到与用户意图相符合的结果。 diff --git a/grafana-overview-dashboard.md b/grafana-overview-dashboard.md index 06f900dc9559..16905d65e088 100644 --- a/grafana-overview-dashboard.md +++ b/grafana-overview-dashboard.md @@ -1,6 +1,5 @@ --- title: Overview 面板重要监控指标详解 -aliases: ['/docs-cn/dev/grafana-overview-dashboard/','/docs-cn/dev/reference/key-monitoring-metrics/overview-dashboard/'] summary: TiUP 部署 TiDB 集群时，一键部署监控系统 (Prometheus & Grafana)。Grafana Dashboard 分为 PD、TiDB、TiKV、Node_exporter、Overview、Performance_overview。重要监控指标包括服务在线节点数量、PD 角色、存储容量、Region 数量、TiDB 执行数量、CPU 使用率、内存大小、网络流量等。详细监控说明可参见文章。 --- diff --git a/grafana-pd-dashboard.md b/grafana-pd-dashboard.md index 7f2429cf8b54..6f534726679f 100644 --- a/grafana-pd-dashboard.md +++ b/grafana-pd-dashboard.md @@ -1,6 +1,5 @@ --- title: PD 重要监控指标详解 -aliases: ['/docs-cn/dev/grafana-pd-dashboard/','/docs-cn/dev/reference/key-monitoring-metrics/pd-dashboard/'] summary: PD 重要监控指标详解：使用 TiUP 部署 TiDB 集群时，一键部署监控系统 (Prometheus & Grafana)，监控架构参见 [TiDB 监控框架概述]。Grafana Dashboard 分为 PD、TiDB、TiKV、Node_exporter、Overview、Performance_overview 等。通过观察 PD 面板上的 Metrics，可以了解 PD 当前的状态。监控包括 PD role、Storage capacity、Current storage size、Current storage usage、Normal stores、Number of Regions、Abnormal stores、Region health、Current peer count 等。Cluster、Operator、Statistics - Balance、Statistics - hot write、Statistics - hot read、Scheduler、gRPC、etcd、TiDB、Heartbeat、Region storage 等指标也很重要。 --- diff --git a/grafana-performance-overview-dashboard.md b/grafana-performance-overview-dashboard.md index 9949e45d8035..db08a427f583 100644 --- a/grafana-performance-overview-dashboard.md +++ b/grafana-performance-overview-dashboard.md @@ -1,7 +1,6 @@ --- title: Performance Overview 面板重要监控指标详解 summary: 本文介绍 Performance Overview 面板上监控指标的含义。 -aliases: ['/zh/tidb/v6.0/grafana-performance-overview-dashboard'] --- # Performance Overview 面板重要监控指标详解 diff --git a/grafana-resource-control-dashboard.md b/grafana-resource-control-dashboard.md index 68a9a9744ca7..846bd6e995f6 100644 --- a/grafana-resource-control-dashboard.md +++ b/grafana-resource-control-dashboard.md @@ -9,15 +9,15 @@ summary: 了解资源管控 (Resource Control) 的 Grafana Dashboard 中所展 目前 Grafana Dashboard 整体分为 PD、TiDB、TiKV、Node_exporter、Overview、Performance_overview 等。 -如果你的集群配置了 [Resource Control](/tidb-resource-control.md) ，通过观察 Resource Control 面板上的 Metrics，你可以了解当前集群整体的资源消耗状态。 +如果你的集群配置了 [Resource Control](/tidb-resource-control-ru-groups.md) ，通过观察 Resource Control 面板上的 Metrics，你可以了解当前集群整体的资源消耗状态。 -TiDB 使用[令牌桶算法](https://en.wikipedia.org/wiki/Token_bucket) 做流控，正如资源管控实现机制 ([RFC: Global Resource Control in TiDB](https://github.com/pingcap/tidb/blob/master/docs/design/2022-11-25-global-resource-control.md#distributed-token-buckets)) 中所描述：一个 TiDB 节点可能存在多个 Resource Group（资源组），将在 PD 端的 GAC（Global Admission Control）进行流控。每个 TiDB 节点中的本地令牌桶（Local Token Buckets）将定期（默认 5 秒）与 PD 端的 GAC 进行通信，以重新配置本地令牌。其中的本地令牌桶（Local Token Buckets）具体实现为 Resource Controller Client。 +TiDB 使用[令牌桶算法](https://en.wikipedia.org/wiki/Token_bucket)做流控，正如资源管控实现机制 ([RFC: Global Resource Control in TiDB](https://github.com/pingcap/tidb/blob/release-8.5/docs/design/2022-11-25-global-resource-control.md#distributed-token-buckets)) 中所描述：一个 TiDB 节点可能存在多个 Resource Group（资源组），将在 PD 端的 GAC（Global Admission Control）进行流控。每个 TiDB 节点中的本地令牌桶（Local Token Buckets）将定期（默认 5 秒）与 PD 端的 GAC 进行通信，以重新配置本地令牌。其中的本地令牌桶（Local Token Buckets）具体实现为 Resource Controller Client。 以下为 **Resource Control** 关键监控指标的说明。 ## Request Unit 相关指标 -- RU：以 Resource Group（资源组）为单位进行实时统计的 [Request Unit (RU)](/tidb-resource-control.md#什么是-request-unit-ru) 消耗信息。`total` 为当前所有 Resource Group 消耗的 Request Unit 之和。每个 Resource Group 的 Request Unit 消耗等于其读消耗 (Read Request Unit) 和写消耗 (Write Request Unit) 之和。 +- RU：以 Resource Group（资源组）为单位进行实时统计的 [Request Unit (RU)](/tidb-resource-control-ru-groups.md#什么是-request-unit-ru) 消耗信息。`total` 为当前所有 Resource Group 消耗的 Request Unit 之和。每个 Resource Group 的 Request Unit 消耗等于其读消耗 (Read Request Unit) 和写消耗 (Write Request Unit) 之和。 - RU Per Query：平均每个 SQL 语句消耗的 Request Unit 数量。计算方法是将前述 Request Unit 监控指标除以当前每秒执行的 SQL 语句数量。 - RRU：以 Resource Group 为单位进行实时统计的读请求 Read Request Unit 消耗信息。`total` 为当前所有 Resource Group 消耗的 Read Request Unit 之和。 - RRU Per Query：平均每个 SQL 语句消耗的 Read Request Unit 数量。计算方法是将前述 Read Request Unit 监控指标除以当前每秒执行的 SQL 语句数量。 diff --git a/grafana-tidb-dashboard.md b/grafana-tidb-dashboard.md index 18b394b9abac..5b0fd942a653 100644 --- a/grafana-tidb-dashboard.md +++ b/grafana-tidb-dashboard.md @@ -1,7 +1,6 @@ --- title: TiDB 监控指标 summary: 了解 Grafana Dashboard 中展示的关键指标。 -aliases: ['/docs-cn/dev/grafana-tidb-dashboard/','/docs-cn/dev/reference/key-monitoring-metrics/tidb-dashboard/'] --- # TiDB 重要监控指标详解 @@ -125,6 +124,11 @@ aliases: ['/docs-cn/dev/grafana-tidb-dashboard/','/docs-cn/dev/reference/key-mon - **cross-zone-out**：尝试在远程可用区执行 Stale Read 的请求的响应的传出流量 - **local-in**：尝试在本地可用区执行 Stale Read 的请求的响应的传入流量 - **local-out**：尝试在本地可用区执行 Stale Read 的请求的响应的传出流量 +- Read Req Traffic + - **leader-local**：Leader Read 在本地可用区处理读请求产生的流量 + - **leader-cross-zone**：Leader Read 在远程可用区处理读请求产生的流量 + - **follower-local**：Follower Read 在本地可用区处理读请求产生的流量 + - **follower-cross-zone**：Follower Read 在远程可用区处理读请求产生的流量 ### PD Client diff --git a/grafana-tikv-dashboard.md b/grafana-tikv-dashboard.md index c54df39bb85a..c170a832408a 100644 --- a/grafana-tikv-dashboard.md +++ b/grafana-tikv-dashboard.md @@ -1,6 +1,5 @@ --- title: TiKV 监控指标详解 -aliases: ['/docs-cn/dev/grafana-tikv-dashboard/','/docs-cn/dev/reference/key-monitoring-metrics/tikv-dashboard/'] summary: TiKV 监控指标详解：TiUP 部署 TiDB 集群时，一键部署监控系统 (Prometheus & Grafana)，监控架构详见 TiDB 监控框架概述。Grafana Dashboard 分为 PD、TiDB、TiKV、Node_exporter、Overview、Performance_overview 等。对于日常运维，通过观察 TiKV-Details 面板上的指标，可以了解 TiKV 当前的状态。根据性能地图，可以检查集群的状态是否符合预期。TiKV-Details 默认的监控信息包括 Cluster、Errors、Server、gRPC、Thread CPU、PD、Raft IO、Raft process、Raft message、Raft propose、Raft admin、Local reader、Unified Read Pool、Storage、Flow Control、Scheduler 等。 --- @@ -91,7 +90,7 @@ summary: TiKV 监控指标详解：TiUP 部署 TiDB 集群时，一键部署监 - CDC Worker CPU：CDC Worker 线程的 CPU 使用率 - CDC endpoint CPU：CDC endpoint 的 CPU 使用率 - Raftlog fetch worker CPU：Async raft log fetcher worker 的 CPU 使用率 -- TSO Worker CPU: TSO Worker 线程的 CPU 使用率 +- TSO Worker CPU：TSO Worker 线程的 CPU 使用率 ### PD @@ -409,6 +408,35 @@ summary: TiKV 监控指标详解：TiUP 部署 TiDB 集群时，一键部署监 - Blob GC output file size：Titan GC 输出文件的大小 - Blob GC file count：Titan GC 涉及的 blob 文件数量 +### In Memory Engine + +以下为 [TiKV MVCC 内存引擎](/tikv-in-memory-engine.md) (In-Memory Engine, IME) 的监控指标。 + +- Ops：每秒列族操作次数 +- Read MBps：RocksDB 和内存引擎的总体读流量（字节） +- Coprocessor Handle duration：处理 coprocessor 请求的耗时 +- Region Cache Hit：从 Region 缓存中成功读取数据的次数 +- Region Cache Hit Rate：Region 缓存的命中率 +- Region Cache Miss Reason：从 Region 缓存中读取数据失败的原因 +- Memory Usage：内存引擎的内存使用情况 +- Region Count：不同类型的 Region 的数量 +- GC Filter：垃圾回收 (GC) 过程中过滤相关的信息 +- Region GC Duration：Region 垃圾回收的耗时 +- Region Load Duration：加载 Region 的耗时 +- Region Load Count：每秒加载的 Region 的数量 +- Region Eviction Duration：驱逐 Region 的耗时 +- Region Eviction Count：每秒驱逐的 Region 的数量 +- Write duration：写操作的耗时 +- 99% In-memory engine write duration per server：内存引擎每秒写操作的 99% 耗时 +- Prepare for write duration：准备写操作的耗时 +- 99% In-memory engine prepare for write duration per server：内存引擎每秒准备写操作的 99% 耗时 +- Iterator operations：不同类型的 iterator 操作的数量 +- Seek duration：seek 操作的耗时 +- Oldest Auto GC SafePoint：内存引擎缓存的 Region 中，最早的自动 GC safepoint +- Newest Auto GC SafePoint：内存引擎缓存的 Region 中，最新的自动 GC safepoint +- Auto GC SafePoint Gap：内存引擎缓存的 Region 中，最新的自动 GC safepoint 和最早的自动 GC safepoint 之间的时间差 +- Auto GC SafePoint Gap With TiKV：TiKV 的自动 GC safepoint 和内存引擎缓存的 Region 中最早的自动 GC safepoint 之间的时间差 + ### Pessimistic Locking - Lock Manager Thread CPU：lock manager 的线程 CPU 使用率 diff --git a/hardware-and-software-requirements.md b/hardware-and-software-requirements.md index 6201ed07a5db..272d182ae97e 100644 --- a/hardware-and-software-requirements.md +++ b/hardware-and-software-requirements.md @@ -1,10 +1,9 @@ --- -title: TiDB 软件和硬件环境建议配置 -aliases: ['/docs-cn/dev/hardware-and-software-requirements/','/docs-cn/dev/how-to/deploy/hardware-recommendations/'] +title: TiDB 软件和硬件环境需求 summary: TiDB 是一款开源的一站式实时 HTAP 数据库，支持部署在多种硬件环境和操作系统上。软件和硬件环境建议配置包括操作系统要求、编译和运行依赖库、Docker 镜像依赖、软件配置要求、服务器建议配置、网络要求、磁盘空间要求、客户端 Web 浏览器要求以及 TiFlash 存算分离架构的软硬件要求。 --- -# TiDB 软件和硬件环境建议配置 +# TiDB 软件和硬件环境需求 -TiDB 作为一款开源一栈式实时 HTAP 数据库，可以很好地部署和运行在 Intel 架构服务器环境、ARM 架构的服务器环境及主流虚拟化环境，并支持绝大多数的主流硬件网络。作为一款高性能数据库系统，TiDB 支持主流的 Linux 操作系统环境。 +本文介绍 TiDB 数据库对软件和硬件环境的需求。TiDB 作为一款开源一栈式实时 HTAP 数据库，可以很好地部署和运行在 Intel 架构服务器环境、ARM 架构的服务器环境及主流虚拟化环境，并支持绝大多数的主流硬件网络。作为一款高性能数据库系统，TiDB 支持主流的 Linux 操作系统环境。 ## 操作系统及平台要求 -| 操作系统 | 支持的 CPU 架构 | -| :--- | :--- | -| Red Hat Enterprise Linux 8.4 及以上的 8.x 版本 |
  • x86_64
  • ARM 64
| -| Red Hat Enterprise Linux 7.3 及以上的 7.x 版本 |
  • x86_64
  • ARM 64
| -| Amazon Linux 2 |
  • x86_64
  • ARM 64
| -| Amazon Linux 2023 |
  • x86_64
  • ARM 64
| -| Rocky Linux 9.1 及以上的版本 |
  • x86_64
  • ARM 64
| -| 麒麟欧拉版 V10 SP1/SP2 |
  • x86_64
  • ARM 64
| -| 统信操作系统 (UOS) V20 |
  • x86_64
  • ARM 64
| -| openEuler 22.03 LTS SP1/SP3 |
  • x86_64
  • ARM 64
| -| macOS 12 (Monterey) 及以上的版本 |
  • x86_64
  • ARM 64
| -| Oracle Enterprise Linux 8 及以上的版本 | x86_64 | -| Ubuntu LTS 20.04 及以上的版本 | x86_64 | -| CentOS 8 Stream |
  • x86_64
  • ARM 64
| -| Debian 10 (Buster) 及以上的版本 | x86_64 | -| Fedora 38 及以上的版本 | x86_64 | -| openSUSE Leap 15.5 以上的版本（不包含 Tumbleweed） | x86_64 | -| SUSE Linux Enterprise Server 15 | x86_64 | - -> **注意：** -> -> - TiDB 只支持 Red Hat 兼容内核 (RHCK) 的 Oracle Enterprise Linux，不支持 Oracle Enterprise Linux 提供的 Unbreakable Enterprise Kernel。 -> - 根据 [CentOS Linux EOL](https://www.centos.org/centos-linux-eol/)，CentOS Linux 7 的上游支持于 2024 年 6 月 30 日终止。从 v8.4.0 版本开始，TiDB 已结束对 CentOS 7 的支持，建议使用 Rocky Linux 9.1 及以上的版本。CentOS Linux 8 的上游支持已于 2021 年 12 月 31 日终止，但 CentOS 将继续提供对 CentOS Stream 8 的支持。 -> - TiDB 将不再支持 Ubuntu 16.04。强烈建议升级到 Ubuntu 18.04 或更高版本。 -> - 对于以上表格中所列操作系统的 32 位版本，TiDB 在这些 32 位操作系统以及对应的 CPU 架构上**不保障**可编译、可构建以及可部署，或 TiDB 不主动适配这些 32 位的操作系统。 -> - 以上未提及的操作系统版本**也许可以**运行 TiDB，但尚未得到 TiDB 官方支持。 +在 v8.5 LTS 版本中，针对不同操作系统和 CPU 架构的组合，TiDB 提供不同级别质量标准的支持。 + ++ 在以下操作系统以及对应的 CPU 架构组合上，TiDB 可**满足企业级生产质量的要求**，产品特性经过全面且系统化的验证： + + | 操作系统 | 支持的 CPU 架构 | + |:-----------------------------------------------|:----------------------------------------| + | Red Hat Enterprise Linux 8.4 及以上的 8.x 版本 |
  • x86_64
  • ARM 64
| + | Amazon Linux 2 |
  • x86_64
  • ARM 64
| + | Amazon Linux 2023 |
  • x86_64
  • ARM 64
| + | Rocky Linux 9.1 及以上的版本 |
  • x86_64
  • ARM 64
| + | 银河麒麟 V10 SP1/SP2/SP3（从 v7.5.5 开始支持 SP3） |
  • x86_64
  • ARM 64
| + | 统信操作系统 (UOS) V20 |
  • x86_64
  • ARM 64
| + | openEuler 22.03 LTS SP1/SP3 |
  • x86_64
  • ARM 64
| + + > **警告：** + > + > - 根据 [CentOS Linux EOL](https://www.redhat.com/en/blog/centos-linux-has-reached-its-end-life-eol)，CentOS Linux 7 的上游支持已于 2024 年 6 月 30 日终止。 + > - 升级 TiDB 前，请务必检查你的操作系统版本。TiDB 在 v8.4.0 DMR 和 v8.5.0 版本中移除了对 glibc 2.17 的适配，以及对 CentOS Linux 7 的兼容性测试和支持，建议使用 Rocky Linux 9.1 及以上的版本。如果在使用 CentOS Linux 7 的情况下将 TiDB 升级到 v8.4.0 DMR 或 v8.5.0 版本，将存在导致集群不可用的风险。 + > - 为了更好地服务仍在使用 CentOS Linux 7 的用户，TiDB 从 v8.5.1 版本起重新适配 glibc 2.17，恢复了对 CentOS Linux 7 的兼容性支持和测试。然而，由于 CentOS Linux 7 已到达 EOL，强烈建议用户参考该系统的[官方声明和安全建议](https://www.redhat.com/en/blog/centos-linux-has-reached-its-end-life-eol)，将生产环境迁移到 TiDB 支持的操作系统版本，如 Rocky Linux 9.1 及以上版本。 + > - 根据 [Red Hat Enterprise Linux Life Cycle](https://access.redhat.com/support/policy/updates/errata/#Life_Cycle_Dates)，Red Hat Enterprise Linux 7 的 Maintenance Support 于 2024 年 6 月 30 日终止。从 8.4 DMR 版本开始，TiDB 已结束对 Red Hat Enterprise Linux 7 的支持，建议使用 Rocky Linux 9.1 及以上的版本。如果将运行在 Red Hat Enterprise Linux 7 上的 TiDB 集群升级到 v8.4.0 或之后版本，将存在导致集群不可用的风险。升级 TiDB 前，请务必检查你的操作系统版本。 + ++ 在以下操作系统以及对应的 CPU 架构组合上，你可以编译、构建和部署 TiDB，可使用 OLTP 和 OLAP 以及数据工具的基本功能。但由于这些组合尚未经过全面且系统的测试验证，TiDB **不保证企业级生产质量要求**： + + | 操作系统 | 支持的 CPU 架构 | + | :--- | :--- | + | macOS 12 (Monterey) 及以上的版本 |
  • x86_64
  • ARM 64
| + | Oracle Enterprise Linux 8 及以上的版本 | x86_64 | + | Ubuntu LTS 20.04 及以上的版本 | x86_64 | + | CentOS Stream 8 |
  • x86_64
  • ARM 64
| + | Debian 10 (Buster) 及以上的版本 | x86_64 | + | Fedora 38 及以上的版本 | x86_64 | + | openSUSE Leap 15.5 以上的版本（不包含 Tumbleweed） | x86_64 | + | SUSE Linux Enterprise Server 15 | x86_64 | + + > **注意：** + > + > - TiDB 只支持 Red Hat 兼容内核 (RHCK) 的 Oracle Enterprise Linux，不支持 Oracle Enterprise Linux 提供的 Unbreakable Enterprise Kernel。 + > - TiDB 将不再支持 Ubuntu 16.04。强烈建议升级到 Ubuntu 18.04 或更高版本。 + > - CentOS Stream 8 已于 2024 年 5 月 31 日 [End of Builds](https://blog.centos.org/2023/04/end-dates-are-coming-for-centos-stream-8-and-centos-linux-7/)。 + ++ 对于以上两个表格中所列操作系统的 32 位版本，TiDB 在这些 32 位操作系统以及对应的 CPU 架构上**不保障**可编译、可构建以及可部署，或 TiDB 不主动适配这些 32 位的操作系统。 + ++ 以上未提及的操作系统版本**也许可以**运行 TiDB，但尚未得到 TiDB 官方支持。 ### 编译和运行 TiDB 所依赖的库 @@ -84,19 +100,20 @@ TiDB 作为一款开源一栈式实时 HTAP 数据库，可以很好地部署和 | numa | 2.0.12 及以上 | | tar | 任意 | -## 服务器建议配置 +## 服务器配置要求 TiDB 支持部署和运行在 Intel x86-64 架构的 64 位通用硬件服务器平台或者 ARM 架构的硬件服务器平台。对于开发、测试及生产环境的服务器硬件配置（不包含操作系统 OS 本身的占用）有以下要求和建议： ### 开发及测试环境 -| **组件** | **CPU** | **内存** | **本地存储** | **网络** | **实例数量(最低要求)** | -| --- | --- | --- | --- | --- | --- | -| TiDB | 8 核+ | 16 GB+ | [磁盘空间要求](#磁盘空间要求) | 千兆网卡 | 1（可与 PD 同机器） | -| PD | 4 核+ | 8 GB+ | SAS, 200 GB+ | 千兆网卡 | 1（可与 TiDB 同机器） | -| TiKV | 8 核+ | 32 GB+ | SSD, 200 GB+ | 千兆网卡 | 3 | -| TiFlash | 32 核+ | 64 GB+ | SSD, 200 GB+ | 千兆网卡 | 1 | -| TiCDC | 8 核+ | 16 GB+ | SAS, 200 GB+ | 千兆网卡 | 1 | +| **组件** | **CPU** | **内存** | **本地存储** | **网络** | **实例数量(最低要求)** | +| -------- | ------ | ------ | -------------------- | ------- | --------------------- | +| TiDB | 8 核+ | 16 GB+ | [存储要求](#存储要求) | 千兆网卡 | 1（可与 PD 同机器） | +| PD | 4 核+ | 8 GB+ | SAS, 200 GB+ | 千兆网卡 | 1（可与 TiDB 同机器） | +| TiKV | 8 核+ | 32 GB+ | SSD, 200 GB+ | 千兆网卡 | 3 | +| TiFlash | 32 核+ | 64 GB+ | SSD, 200 GB+ | 千兆网卡 | 1 | +| TiCDC | 8 核+ | 16 GB+ | SAS, 200 GB+ | 千兆网卡 | 1 | +| TiProxy | 4 核+ | 8 GB+ | SAS | 千兆网卡 | 1 | > **注意：** > @@ -111,11 +128,12 @@ TiDB 支持部署和运行在 Intel x86-64 架构的 64 位通用硬件服务器 | **组件** | **CPU** | **内存** | **硬盘类型** | **网络** | **实例数量(最低要求)** | | --- | --- | --- | --- | --- | --- | | TiDB | 16 核+ | 48 GB+ | SSD | 万兆网卡（2 块最佳） | 2 | -| PD | 8 核+ | 16 GB+ | SSD | 万兆网卡（2 块最佳） | 3 | +| PD | 8 核+ | 16 GB+ | SSD | 万兆网卡（2 块最佳） | 3 | | TiKV | 16 核+ | 64 GB+ | SSD | 万兆网卡（2 块最佳） | 3 | | TiFlash | 48 核+ | 128 GB+ | 1 or more SSDs | 万兆网卡（2 块最佳） | 2 | -| TiCDC | 16 核+ | 64 GB+ | SSD | 万兆网卡（2 块最佳） | 2 | -| 监控 | 8 核+ | 16 GB+ | SAS | 千兆网卡 | 1 | +| TiCDC | 16 核+ | 64 GB+ | SSD | 万兆网卡（2 块最佳） | 2 | +| 监控 | 8 核+ | 16 GB+ | SAS | 千兆网卡 | 1 | +| TiProxy | 8 核+ | 16 GB+ | SAS | 万兆网卡（2 块最佳） | 2 | > **注意：** > @@ -167,7 +185,7 @@ TiDB 作为开源一栈式实时 HTAP 数据库，其正常运行需要网络环 | Alertmanager | 9093 | 告警 web 服务端口 | | Alertmanager | 9094 | 告警通信端口 | -## 磁盘空间要求 +## 存储要求 | 组件 | 磁盘空间要求 | 健康水位使用率 | | :-- | :-- | :-- | @@ -178,6 +196,8 @@ TiDB 作为开源一栈式实时 HTAP 数据库，其正常运行需要网络环 | TiUP |
  • 中控机：部署一个版本的 TiDB 集群占用不超过 1 GB 空间，部署多个版本集群所占用的空间会相应增加
  • 部署服务器（实际运行 TiDB 各组件的机器）：TiFlash 占用约 700 MB 空间，其他组件（PD、TiDB、TiKV 等）各占用约 200 MB 空间。同时，部署过程会占用小于 1 MB 临时空间（/tmp）存放临时文件
| 不涉及| | Ngmonitoring |
  • Conprof：3 x 1 GB x 组件数量（表示每个组件每天占用约 1 GB，总共 3 天） + 20 GB 预留空间
  • Top SQL：30 x 50 MB x 组件数量（每个组件每天占用约 50 MB，总共 30 天）
  • Top SQL 和 Conprof 共享预留空间
| 不涉及 | +TiDB 支持 XFS 和 Ext4 文件系统。其他文件系统不推荐用于生产环境。 + ## 客户端 Web 浏览器要求 TiDB 提供了基于 [Grafana](https://grafana.com/) 的技术平台，对数据库集群的各项指标进行可视化展现。采用支持 Javascript 的微软 Edge、Apple Safari、Google Chrome、Mozilla Firefox 的较新版本即可访问监控入口。 diff --git a/hybrid-deployment-topology.md b/hybrid-deployment-topology.md index d64104aaf4bf..43d7546f8789 100644 --- a/hybrid-deployment-topology.md +++ b/hybrid-deployment-topology.md @@ -1,7 +1,6 @@ --- title: 混合部署拓扑 summary: 介绍混合部署 TiDB 集群的拓扑结构。 -aliases: ['/docs-cn/dev/hybrid-deployment-topology/'] --- # 混合部署拓扑 @@ -17,6 +16,10 @@ aliases: ['/docs-cn/dev/hybrid-deployment-topology/'] | TiKV | 6 | 32 VCore 64GB | 10.0.1.7
10.0.1.8
10.0.1.9 | 1. 区分实例级别的 port、status_port；
2. 配置全局参数 readpool、storage 以及 raftstore；
3. 配置实例级别 host 维度的 labels；
4. 配置 numa 绑核操作| | Monitoring & Grafana | 1 | 4 VCore 8GB * 1 500GB (ssd) | 10.0.1.10 | 默认配置 | +> **注意：** +> +> 该表中拓扑实例的 IP 为示例 IP。在实际部署时，请替换为实际的 IP。 + ### 拓扑模版
diff --git a/identify-expensive-queries.md b/identify-expensive-queries.md index a4501930ce57..8bb350426290 100644 --- a/identify-expensive-queries.md +++ b/identify-expensive-queries.md @@ -1,6 +1,5 @@ --- title: 定位消耗系统资源多的查询 -aliases: ['/docs-cn/dev/identify-expensive-queries/','/docs-cn/dev/how-to/maintain/identify-abnormal-queries/identify-expensive-queries/','/docs-cn/how-to/maintain/identify-abnormal-queries/identify-aborted-queries/','/docs-cn/dev/how-to/maintain/identify-abnormal-queries/identify-aborted-queries/'] summary: TiDB 会将执行时间超过 tidb_expensive_query_time_threshold 限制（默认值为 60s），或使用内存超过 tidb_mem_quota_query 限制（默认值为 1 GB）的语句输出到 tidb-server 日志文件中，用于定位消耗系统资源多的查询语句。expensive query 日志和慢查询日志的区别在于，expensive query 日志可以将正在执行的语句的相关信息打印出来。当一条语句在执行过程中达到资源使用阈值时，TiDB 会即时将这条语句的相关信息写入日志。 --- diff --git a/identify-slow-queries.md b/identify-slow-queries.md index c6ba6afb3f35..4eb582daf8eb 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -1,6 +1,5 @@ --- title: 慢查询日志 -aliases: ['/docs-cn/dev/identify-slow-queries/','/docs-cn/dev/how-to/maintain/identify-abnormal-queries/identify-slow-queries/','/docs-cn/sql/slow-query/','/docs-cn/dev/how-to/maintain/identify-slow-queries/'] summary: TiDB 会将执行时间超过 300 毫秒的语句输出到慢查询日志中，用于帮助用户定位慢查询语句。可以通过修改系统变量来启用或禁用慢查询日志。日志示例包括执行时间、用户信息、执行计划等字段。用户可通过查询 SLOW_QUERY 表来查询慢查询日志中的内容。还可以使用 pt-query-digest 工具分析 TiDB 慢日志。ADMIN SHOW SLOW 命令可以显示最近的慢查询记录或最慢的查询记录。 --- @@ -135,8 +134,8 @@ Slow Query 基础信息： * `Cop_wait_p90`：cop-task 的 P90 分位等待时间。 * `Cop_wait_max`：cop-task 的最大等待时间。 * `Cop_wait_addr`：等待时间最长的 cop-task 所在地址。 -* `Rocksdb_delete_skipped_count`：RocksDB 读数据过程中已删除 Key 的扫描数。 -* `Rocksdb_key_skipped_count`：RocksDB 扫数据时遇到的已删除 (tombstone) Key 数量。 +* `Rocksdb_delete_skipped_count`：RocksDB 扫数据时遇到的已删除 (tombstone) Key 数量。 +* `Rocksdb_key_skipped_count`：RocksDB 扫数据时所有遇到的 Key 数量。 * `Rocksdb_block_cache_hit_count`：RocksDB 从 Block Cache 缓存中读数据的次数。 * `Rocksdb_block_read_count`：RocksDB 从文件系统中读数据的次数。 * `Rocksdb_block_read_byte`：RocksDB 从文件系统中读数据的数据量。 @@ -168,6 +167,11 @@ Slow Query 基础信息： * `Request_unit_write`：执行语句消耗的总写 RU。 * `Time_queued_by_rc`：执行语句过程中等待可用资源的总耗时。 +和存储引擎相关的字段： + +- `Storage_from_kv`：从 v8.5.5 开始引入，表示该语句是否从 TiKV 读取数据。 +- `Storage_from_mpp`：从 v8.5.5 开始引入，表示该语句是否从 TiFlash 读取数据。 + ## 相关系统变量 * [tidb_slow_log_threshold](/system-variables.md#tidb_slow_log_threshold)：设置慢日志的阈值，执行时间超过阈值的 SQL 语句将被记录到慢日志中。默认值是 300 ms。 diff --git a/index-advisor.md b/index-advisor.md new file mode 100644 index 000000000000..d27984348ac3 --- /dev/null +++ b/index-advisor.md @@ -0,0 +1,223 @@ +--- +title: 索引推荐 (Index Advisor) +summary: 了解如何使用 TiDB 索引推荐 (Index Advisor) 功能优化查询性能。 +--- + +# 索引推荐 (Index Advisor) + +从 v8.5.0 开始，TiDB 引入索引推荐 (Index Advisor) 功能，通过推荐能够提高查询性能的索引，帮助优化工作负载。你可以使用 `RECOMMEND INDEX` SQL 语句为单个查询或整个工作负载生成索引建议。为了避免实际创建索引时消耗大量资源，TiDB 支持[虚拟索引 (Hypothetical indexes)](#虚拟索引-hypothetical-indexes)，让被评估的索引仅存在于逻辑层面，而不会被实际创建。 + +索引推荐功能通过分析查询语句，从 `WHERE`、`GROUP BY` 和 `ORDER BY` 等子句中识别可索引的列。然后，它会生成索引候选项 (index candidates) 并使用虚拟索引估算其性能收益。TiDB 采用遗传搜索算法从单列索引开始，逐步迭代探索多列索引组合，以选择最优索引集合。在选择的过程中，TiDB 会利用假设分析法 (What-If analysis) 评估这些潜在索引对优化器计划成本的影响。当某些索引能够降低总体查询成本时，索引推荐功能就会推荐这些索引。 + +除了[推荐新索引](#使用-recommend-index-语句推荐索引)，还可以通过部分系统表的信息[删除未使用的索引](#删除未使用的索引)，以确保高效的索引管理。 + +## 使用 `RECOMMEND INDEX` 语句推荐索引 + +TiDB 提供 `RECOMMEND INDEX` SQL 语句用于索引推荐任务。使用 `RUN` 子命令，可以分析历史工作负载并将推荐结果保存到系统表中。使用 `FOR` 选项，可以为特定 SQL 语句生成索引建议，即使该语句未执行过。你还可以使用[其他选项](#recommend-index-选项)进行高级控制。语法如下： + +```sql +RECOMMEND INDEX RUN [ FOR ] [] +``` + +### 为单个查询推荐索引 + +以下示例展示如何为表 `t` 上的查询生成索引推荐，该表包含 5,000 行数据。为简洁起见，以下示例省略了 `INSERT` 语句。 + +```sql +CREATE TABLE t (a INT, b INT, c INT); +RECOMMEND INDEX RUN for "SELECT a, b FROM t WHERE a = 1 AND b = 1"\G +*************************** 1. row *************************** + database: test + table: t + index_name: idx_a_b + index_columns: a,b + est_index_size: 0 + reason: Column [a b] appear in Equal or Range Predicate clause(s) in query: select `a` , `b` from `test` . `t` where `a` = ? and `b` = ? + top_impacted_query: [{"Query":"SELECT `a`,`b` FROM `test`.`t` WHERE `a` = 1 AND `b` = 1","Improvement":0.999994}] +create_index_statement: CREATE INDEX idx_a_b ON t(a,b); +``` + +索引推荐功能分别评估 `a` 和 `b` 上的单列索引，并最终将它们合并为一个组合索引 `(a, b)` 推荐出来，以实现最佳性能。 + +以下 `EXPLAIN` 结果比较了无索引和使用推荐的两列索引的查询执行计划。索引推荐功能会内部评估这两种方案，并选择其中执行计划成本最低的方案。索引推荐功能还会考虑 `a` 和 `b` 上的单列索引，但对于该示例，这些单列索引的性能不如组合的两列索引（为简洁起见，以下示例省略了这些执行计划）。 + +```sql +EXPLAIN FORMAT='VERBOSE' SELECT a, b FROM t WHERE a=1 AND b=1; + ++-------------------------+---------+------------+-----------+---------------+----------------------------------+ +| id | estRows | estCost | task | access object | operator info | ++-------------------------+---------+------------+-----------+---------------+----------------------------------+ +| TableReader_7 | 0.01 | 196066.71 | root | | data:Selection_6 | +| └─Selection_6 | 0.01 | 2941000.00 | cop[tikv] | | eq(test.t.a, 1), eq(test.t.b, 1) | +| └─TableFullScan_5 | 5000.00 | 2442000.00 | cop[tikv] | table:t | keep order:false, stats:pseudo | ++-------------------------+---------+------------+-----------+---------------+----------------------------------+ + +EXPLAIN FORMAT='VERBOSE' SELECT /*+ HYPO_INDEX(t, idx_ab, a, b) */ a, b FROM t WHERE a=1 AND b=1; ++------------------------+---------+---------+-----------+-----------------------------+-------------------------------------------------+ +| id | estRows | estCost | task | access object | operator info | ++------------------------+---------+---------+-----------+-----------------------------+-------------------------------------------------+ +| IndexReader_6 | 0.05 | 1.10 | root | | index:IndexRangeScan_5 | +| └─IndexRangeScan_5 | 0.05 | 10.18 | cop[tikv] | table:t, index:idx_ab(a, b) | range:[1 1,1 1], keep order:false, stats:pseudo | ++------------------------+---------+---------+-----------+-----------------------------+-------------------------------------------------+ +``` + +### 为工作负载推荐索引 + +以下示例展示如何为整个工作负载生成索引推荐。假设表 `t1` 和 `t2` 各包含 5,000 行数据： + +```sql +CREATE TABLE t1 (a INT, b INT, c INT, d INT); +CREATE TABLE t2 (a INT, b INT, c INT, d INT); + +-- 在此工作负载中运行一些查询 +SELECT a, b FROM t1 WHERE a=1 AND b<=5; +SELECT d FROM t1 ORDER BY d LIMIT 10; +SELECT * FROM t1, t2 WHERE t1.a=1 AND t1.d=t2.d; + +RECOMMEND INDEX RUN; ++----------+-------+------------+---------------+------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------+ +| database | table | index_name | index_columns | est_index_size | reason | top_impacted_query | create_index_statement | ++----------+-------+------------+---------------+------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------+ +| test | t1 | idx_a_b | a,b | 19872 | Column [a b] appear in Equal or Range Predicate clause(s) in query: select `a` , `b` from `test` . `t1` where `a` = ? and `b` <= ? | [{"Query":"SELECT `a`,`b` FROM `test`.`t1` WHERE `a` = 1 AND `b` \u003c= 5","Improvement":0.998214},{"Query":"SELECT * FROM (`test`.`t1`) JOIN `test`.`t2` WHERE `t1`.`a` = 1 AND `t1`.`d` = `t2`.`d`","Improvement":0.336837}] | CREATE INDEX idx_a_b ON t1(a,b); | +| test | t1 | idx_d | d | 9936 | Column [d] appear in Equal or Range Predicate clause(s) in query: select `d` from `test` . `t1` order by `d` limit ? | [{"Query":"SELECT `d` FROM `test`.`t1` ORDER BY `d` LIMIT 10","Improvement":0.999433}] | CREATE INDEX idx_d ON t1(d); | +| test | t2 | idx_d | d | 9936 | Column [d] appear in Equal or Range Predicate clause(s) in query: select * from ( `test` . `t1` ) join `test` . `t2` where `t1` . `a` = ? and `t1` . `d` = `t2` . `d` | [{"Query":"SELECT * FROM (`test`.`t1`) JOIN `test`.`t2` WHERE `t1`.`a` = 1 AND `t1`.`d` = `t2`.`d`","Improvement":0.638567}] | CREATE INDEX idx_d ON t2(d); | ++----------+-------+------------+---------------+------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------+ +``` + +在这个示例中，索引推荐功能识别出了适用于整个工作负载的最佳索引，而不仅仅是针对单个查询。工作负载数据来源于 TiDB 系统表 `INFORMATION_SCHEMA.STATEMENTS_SUMMARY`。 + +工作负载中可能包含数万到数十万条查询，为了提高推荐索引的效率，此功能会优先考虑为执行频率最高的查询进行索引推荐，因为这些查询对整体工作负载性能的影响更大。默认情况下，索引推荐功能会选择执行频率最高的前 1,000 条查询，你可以使用 [`max_num_query`](#recommend-index-选项) 参数调整此值。 + +`RECOMMEND INDEX` 语句的结果存储在 `mysql.index_advisor_results` 表中。你可以查询此表以查看推荐的索引。以下示例为执行前两个 `RECOMMEND INDEX` 语句后此系统表的内容： + +```sql +SELECT * FROM mysql.index_advisor_results; ++----+---------------------+---------------------+-------------+------------+------------+---------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+-------+ +| id | created_at | updated_at | schema_name | table_name | index_name | index_columns | index_details | top_impacted_queries | workload_impact | extra | ++----+---------------------+---------------------+-------------+------------+------------+---------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+-------+ +| 1 | 2024-12-10 11:44:45 | 2024-12-10 11:44:45 | test | t1 | idx_a_b | a,b | {"IndexSize": 0, "Reason": "Column [a b] appear in Equal or Range Predicate clause(s) in query: select `a` , `b` from `test` . `t1` where `a` = ? and `b` <= ?"} | [{"Improvement": 0.998214, "Query": "SELECT `a`,`b` FROM `test`.`t1` WHERE `a` = 1 AND `b` <= 5"}, {"Improvement": 0.337273, "Query": "SELECT * FROM (`test`.`t1`) JOIN `test`.`t2` WHERE `t1`.`a` = 1 AND `t1`.`d` = `t2`.`d`"}] | {"WorkloadImprovement": 0.395235} | NULL | +| 2 | 2024-12-10 11:44:45 | 2024-12-10 11:44:45 | test | t1 | idx_d | d | {"IndexSize": 0, "Reason": "Column [d] appear in Equal or Range Predicate clause(s) in query: select `d` from `test` . `t1` order by `d` limit ?"} | [{"Improvement": 0.999715, "Query": "SELECT `d` FROM `test`.`t1` ORDER BY `d` LIMIT 10"}] | {"WorkloadImprovement": 0.225116} | NULL | +| 3 | 2024-12-10 11:44:45 | 2024-12-10 11:44:45 | test | t2 | idx_d | d | {"IndexSize": 0, "Reason": "Column [d] appear in Equal or Range Predicate clause(s) in query: select * from ( `test` . `t1` ) join `test` . `t2` where `t1` . `a` = ? and `t1` . `d` = `t2` . `d`"} | [{"Improvement": 0.639393, "Query": "SELECT * FROM (`test`.`t1`) JOIN `test`.`t2` WHERE `t1`.`a` = 1 AND `t1`.`d` = `t2`.`d`"}] | {"WorkloadImprovement": 0.365871} | NULL | ++----+---------------------+---------------------+-------------+------------+------------+---------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+-------+ +``` + +### `RECOMMEND INDEX` 选项 + +你可以查看 `RECOMMEND INDEX` 语句的选项，并根据你的工作负载需求配置该选项以调整索引推荐的结果，如下所示： + +```sql +RECOMMEND INDEX SET