From d10180259cc869a887a967a05c9a6983f9cc0aec Mon Sep 17 00:00:00 2001 From: Ana Hobden Date: Tue, 7 Jan 2020 16:45:18 -0800 Subject: [PATCH 1/7] Add multi-version support Signed-off-by: Ana Hobden --- config.yaml | 3 + content/docs/3.0/concepts/architecture.md | 2 +- content/docs/3.0/concepts/features.md | 2 +- content/docs/3.0/concepts/overview.md | 6 +- content/docs/3.0/reference/clients/c.md | 2 +- content/docs/3.0/reference/clients/go.md | 2 +- .../3.0/reference/clients/introduction.md | 2 +- content/docs/3.0/reference/clients/java.md | 2 +- content/docs/3.0/reference/clients/rust.md | 2 +- content/docs/3.0/reference/contribute.md | 5 +- content/docs/3.0/reference/faq.md | 5 +- content/docs/3.0/reference/introduction.md | 5 +- content/docs/3.0/reference/query-layers.md | 2 +- .../docs/3.0/reference/tools/introduction.md | 2 +- content/docs/3.0/reference/tools/pd-ctl.md | 2 +- .../docs/3.0/reference/tools/pd-recover.md | 2 +- content/docs/3.0/reference/tools/pd-server.md | 2 +- content/docs/3.0/reference/tools/tikv-ctl.md | 2 +- .../docs/3.0/reference/tools/tikv-server.md | 2 +- content/docs/3.0/tasks/backup/introduction.md | 2 +- .../docs/3.0/tasks/configure/introduction.md | 2 +- content/docs/3.0/tasks/configure/limit.md | 2 +- content/docs/3.0/tasks/configure/namespace.md | 2 +- .../docs/3.0/tasks/configure/region-merge.md | 2 +- content/docs/3.0/tasks/configure/rocksdb.md | 2 +- content/docs/3.0/tasks/configure/security.md | 2 +- content/docs/3.0/tasks/configure/titan.md | 2 +- content/docs/3.0/tasks/configure/topology.md | 2 +- content/docs/3.0/tasks/deploy/ansible.md | 2 +- content/docs/3.0/tasks/deploy/binary.md | 2 +- .../docs/3.0/tasks/deploy/docker-compose.md | 2 +- content/docs/3.0/tasks/deploy/docker.md | 2 +- content/docs/3.0/tasks/deploy/introduction.md | 2 +- content/docs/3.0/tasks/introduction.md | 5 +- .../docs/3.0/tasks/monitor/introduction.md | 2 +- content/docs/3.0/tasks/monitor/key-metrics.md | 2 +- .../docs/3.0/tasks/monitor/tikv-cluster.md | 2 +- content/docs/3.0/tasks/scale/ansible.md | 2 +- content/docs/3.0/tasks/scale/introduction.md | 2 +- content/docs/3.0/tasks/try.md | 2 +- .../docs/3.1-beta/concepts/architecture.md | 84 ++ content/docs/3.1-beta/concepts/features.md | 9 + content/docs/3.1-beta/concepts/overview.md | 44 + content/docs/3.1-beta/reference/clients/c.md | 14 + content/docs/3.1-beta/reference/clients/go.md | 361 +++++++ .../reference/clients/introduction.md | 15 + .../docs/3.1-beta/reference/clients/java.md | 14 + .../docs/3.1-beta/reference/clients/rust.md | 199 ++++ content/docs/3.1-beta/reference/contribute.md | 82 ++ content/docs/3.1-beta/reference/faq.md | 169 ++++ .../docs/3.1-beta/reference/introduction.md | 13 + .../docs/3.1-beta/reference/query-layers.md | 16 + .../3.1-beta/reference/tools/introduction.md | 18 + .../docs/3.1-beta/reference/tools/pd-ctl.md | 932 ++++++++++++++++++ .../3.1-beta/reference/tools/pd-recover.md | 49 + .../3.1-beta/reference/tools/pd-server.md | 10 + .../docs/3.1-beta/reference/tools/tikv-ctl.md | 296 ++++++ .../3.1-beta/reference/tools/tikv-server.md | 10 + .../3.1-beta/tasks/backup/introduction.md | 8 + .../3.1-beta/tasks/configure/introduction.md | 23 + .../docs/3.1-beta/tasks/configure/limit.md | 100 ++ .../3.1-beta/tasks/configure/namespace.md | 126 +++ .../3.1-beta/tasks/configure/region-merge.md | 40 + .../docs/3.1-beta/tasks/configure/rocksdb.md | 37 + .../docs/3.1-beta/tasks/configure/security.md | 186 ++++ .../docs/3.1-beta/tasks/configure/titan.md | 55 ++ .../docs/3.1-beta/tasks/configure/topology.md | 97 ++ content/docs/3.1-beta/tasks/deploy/ansible.md | 548 ++++++++++ content/docs/3.1-beta/tasks/deploy/binary.md | 161 +++ .../3.1-beta/tasks/deploy/docker-compose.md | 22 + content/docs/3.1-beta/tasks/deploy/docker.md | 162 +++ .../3.1-beta/tasks/deploy/introduction.md | 103 ++ content/docs/3.1-beta/tasks/introduction.md | 48 + .../3.1-beta/tasks/monitor/introduction.md | 28 + .../3.1-beta/tasks/monitor/key-metrics.md | 58 ++ .../3.1-beta/tasks/monitor/tikv-cluster.md | 239 +++++ content/docs/3.1-beta/tasks/scale/ansible.md | 374 +++++++ .../docs/3.1-beta/tasks/scale/introduction.md | 125 +++ content/docs/3.1-beta/tasks/try.md | 344 +++++++ .../consensus-algorithm/byzantine-failure.md | 30 - .../consistency-availability-partitioning.md | 21 - .../consensus-algorithm/introduction.md | 16 - .../deep-dive/consensus-algorithm/paxos.md | 28 - .../deep-dive/consensus-algorithm/raft.md | 23 - .../deep-dive/distributed-sql/dist-sql.md | 104 -- .../deep-dive/distributed-sql/introduction.md | 47 - .../distributed-algorithms.md | 63 -- .../distributed-transaction/introduction.md | 19 - .../isolation-level.md | 69 -- .../distributed-transaction/locking.md | 25 - .../optimized-percolator.md | 84 -- .../distributed-transaction/percolator.md | 160 --- .../timestamp-oracle.md | 21 - content/docs/deep-dive/introduction.md | 49 - .../key-value-engine/b-tree-vs-lsm.md | 148 --- .../key-value-engine/introduction.md | 35 - .../deep-dive/key-value-engine/rocksdb.md | 163 --- .../resource-scheduling/introduction.md | 16 - .../resource-scheduling/kubernetes.md | 36 - .../deep-dive/resource-scheduling/mesos.md | 69 -- .../resource-scheduling/simulator.md | 95 -- content/docs/deep-dive/rpc/grpc.md | 50 - content/docs/deep-dive/rpc/http2.md | 98 -- content/docs/deep-dive/rpc/introduction.md | 69 -- content/docs/deep-dive/rpc/protobuf.md | 74 -- .../deep-dive/scalability/data-sharding.md | 29 - .../scalability/horizontal-or-vertical.md | 21 - .../deep-dive/scalability/introduction.md | 11 - .../docs/deep-dive/scalability/multi-raft.md | 26 - .../deep-dive/testing/failure_injection.md | 8 - .../docs/deep-dive/testing/introduction.md | 72 -- layouts/docs/list.html | 14 +- layouts/docs/single.html | 10 +- layouts/partials/entry-tree.html | 92 +- layouts/partials/navbar.html | 23 +- 115 files changed, 5332 insertions(+), 1902 deletions(-) create mode 100644 content/docs/3.1-beta/concepts/architecture.md create mode 100644 content/docs/3.1-beta/concepts/features.md create mode 100644 content/docs/3.1-beta/concepts/overview.md create mode 100644 content/docs/3.1-beta/reference/clients/c.md create mode 100644 content/docs/3.1-beta/reference/clients/go.md create mode 100644 content/docs/3.1-beta/reference/clients/introduction.md create mode 100644 content/docs/3.1-beta/reference/clients/java.md create mode 100644 content/docs/3.1-beta/reference/clients/rust.md create mode 100644 content/docs/3.1-beta/reference/contribute.md create mode 100644 content/docs/3.1-beta/reference/faq.md create mode 100644 content/docs/3.1-beta/reference/introduction.md create mode 100644 content/docs/3.1-beta/reference/query-layers.md create mode 100644 content/docs/3.1-beta/reference/tools/introduction.md create mode 100644 content/docs/3.1-beta/reference/tools/pd-ctl.md create mode 100644 content/docs/3.1-beta/reference/tools/pd-recover.md create mode 100644 content/docs/3.1-beta/reference/tools/pd-server.md create mode 100644 content/docs/3.1-beta/reference/tools/tikv-ctl.md create mode 100644 content/docs/3.1-beta/reference/tools/tikv-server.md create mode 100644 content/docs/3.1-beta/tasks/backup/introduction.md create mode 100644 content/docs/3.1-beta/tasks/configure/introduction.md create mode 100644 content/docs/3.1-beta/tasks/configure/limit.md create mode 100644 content/docs/3.1-beta/tasks/configure/namespace.md create mode 100644 content/docs/3.1-beta/tasks/configure/region-merge.md create mode 100644 content/docs/3.1-beta/tasks/configure/rocksdb.md create mode 100644 content/docs/3.1-beta/tasks/configure/security.md create mode 100644 content/docs/3.1-beta/tasks/configure/titan.md create mode 100644 content/docs/3.1-beta/tasks/configure/topology.md create mode 100644 content/docs/3.1-beta/tasks/deploy/ansible.md create mode 100644 content/docs/3.1-beta/tasks/deploy/binary.md create mode 100644 content/docs/3.1-beta/tasks/deploy/docker-compose.md create mode 100644 content/docs/3.1-beta/tasks/deploy/docker.md create mode 100644 content/docs/3.1-beta/tasks/deploy/introduction.md create mode 100644 content/docs/3.1-beta/tasks/introduction.md create mode 100644 content/docs/3.1-beta/tasks/monitor/introduction.md create mode 100644 content/docs/3.1-beta/tasks/monitor/key-metrics.md create mode 100644 content/docs/3.1-beta/tasks/monitor/tikv-cluster.md create mode 100644 content/docs/3.1-beta/tasks/scale/ansible.md create mode 100644 content/docs/3.1-beta/tasks/scale/introduction.md create mode 100644 content/docs/3.1-beta/tasks/try.md delete mode 100644 content/docs/deep-dive/consensus-algorithm/byzantine-failure.md delete mode 100644 content/docs/deep-dive/consensus-algorithm/consistency-availability-partitioning.md delete mode 100644 content/docs/deep-dive/consensus-algorithm/introduction.md delete mode 100644 content/docs/deep-dive/consensus-algorithm/paxos.md delete mode 100644 content/docs/deep-dive/consensus-algorithm/raft.md delete mode 100644 content/docs/deep-dive/distributed-sql/dist-sql.md delete mode 100644 content/docs/deep-dive/distributed-sql/introduction.md delete mode 100644 content/docs/deep-dive/distributed-transaction/distributed-algorithms.md delete mode 100644 content/docs/deep-dive/distributed-transaction/introduction.md delete mode 100644 content/docs/deep-dive/distributed-transaction/isolation-level.md delete mode 100644 content/docs/deep-dive/distributed-transaction/locking.md delete mode 100644 content/docs/deep-dive/distributed-transaction/optimized-percolator.md delete mode 100644 content/docs/deep-dive/distributed-transaction/percolator.md delete mode 100644 content/docs/deep-dive/distributed-transaction/timestamp-oracle.md delete mode 100644 content/docs/deep-dive/introduction.md delete mode 100644 content/docs/deep-dive/key-value-engine/b-tree-vs-lsm.md delete mode 100644 content/docs/deep-dive/key-value-engine/introduction.md delete mode 100644 content/docs/deep-dive/key-value-engine/rocksdb.md delete mode 100644 content/docs/deep-dive/resource-scheduling/introduction.md delete mode 100644 content/docs/deep-dive/resource-scheduling/kubernetes.md delete mode 100644 content/docs/deep-dive/resource-scheduling/mesos.md delete mode 100644 content/docs/deep-dive/resource-scheduling/simulator.md delete mode 100644 content/docs/deep-dive/rpc/grpc.md delete mode 100644 content/docs/deep-dive/rpc/http2.md delete mode 100644 content/docs/deep-dive/rpc/introduction.md delete mode 100644 content/docs/deep-dive/rpc/protobuf.md delete mode 100644 content/docs/deep-dive/scalability/data-sharding.md delete mode 100644 content/docs/deep-dive/scalability/horizontal-or-vertical.md delete mode 100644 content/docs/deep-dive/scalability/introduction.md delete mode 100644 content/docs/deep-dive/scalability/multi-raft.md delete mode 100644 content/docs/deep-dive/testing/failure_injection.md delete mode 100644 content/docs/deep-dive/testing/introduction.md diff --git a/config.yaml b/config.yaml index eacf02dd..4cfa186a 100644 --- a/config.yaml +++ b/config.yaml @@ -25,6 +25,9 @@ params: googleAnalyticsId: "UA-130734531-1" versions: latest: "3.0" + all: + - "3.1-beta" + - "3.0" description: brief: "A distributed transactional key-value database" long: "Based on the design of [Google Spanner](https://ai.google/research/pubs/pub39966) and [HBase](https://hbase.apache.org), but simpler to manage and without dependencies on any distributed filesystem" diff --git a/content/docs/3.0/concepts/architecture.md b/content/docs/3.0/concepts/architecture.md index e7016363..8d228e29 100644 --- a/content/docs/3.0/concepts/architecture.md +++ b/content/docs/3.0/concepts/architecture.md @@ -2,7 +2,7 @@ title: Architecture description: How TiKV works and how it was built menu: - docs: + "3.0": parent: Concepts --- diff --git a/content/docs/3.0/concepts/features.md b/content/docs/3.0/concepts/features.md index e5c0b4ff..7c907fa0 100644 --- a/content/docs/3.0/concepts/features.md +++ b/content/docs/3.0/concepts/features.md @@ -2,7 +2,7 @@ title: Features description: The features of TiKV menu: - docs: + "3.0": parent: Concepts --- diff --git a/content/docs/3.0/concepts/overview.md b/content/docs/3.0/concepts/overview.md index 1daa52e1..a2b23e52 100644 --- a/content/docs/3.0/concepts/overview.md +++ b/content/docs/3.0/concepts/overview.md @@ -2,11 +2,7 @@ title: Concepts description: Some basic facts about TiKV menu: - nav: - name: Concepts - parent: Docs - weight: 1 - docs: + "3.0": weight: 1 --- diff --git a/content/docs/3.0/reference/clients/c.md b/content/docs/3.0/reference/clients/c.md index 2ff865d3..da086c63 100644 --- a/content/docs/3.0/reference/clients/c.md +++ b/content/docs/3.0/reference/clients/c.md @@ -2,7 +2,7 @@ title: C Client description: Interact with TiKV using C. menu: - docs: + "3.0": parent: Clients weight: 4 --- diff --git a/content/docs/3.0/reference/clients/go.md b/content/docs/3.0/reference/clients/go.md index 40ddc197..97219e19 100644 --- a/content/docs/3.0/reference/clients/go.md +++ b/content/docs/3.0/reference/clients/go.md @@ -2,7 +2,7 @@ title: Go Client description: Interact with TiKV using Go. menu: - docs: + "3.0": parent: Clients weight: 1 --- diff --git a/content/docs/3.0/reference/clients/introduction.md b/content/docs/3.0/reference/clients/introduction.md index c4b3e3d0..3a808e03 100644 --- a/content/docs/3.0/reference/clients/introduction.md +++ b/content/docs/3.0/reference/clients/introduction.md @@ -2,7 +2,7 @@ title: Clients description: Interact with TiKV using the raw key-value API or the transactional key-value API menu: - docs: + "3.0": parent: Reference weight: 2 --- diff --git a/content/docs/3.0/reference/clients/java.md b/content/docs/3.0/reference/clients/java.md index 46f40f3b..f79a7750 100644 --- a/content/docs/3.0/reference/clients/java.md +++ b/content/docs/3.0/reference/clients/java.md @@ -2,7 +2,7 @@ title: Java Client description: Interact with TiKV using Java. menu: - docs: + "3.0": parent: Clients weight: 3 --- diff --git a/content/docs/3.0/reference/clients/rust.md b/content/docs/3.0/reference/clients/rust.md index 7459fc0d..871fc664 100644 --- a/content/docs/3.0/reference/clients/rust.md +++ b/content/docs/3.0/reference/clients/rust.md @@ -2,7 +2,7 @@ title: Rust Client description: Interact with TiKV using Rust. menu: - docs: + "3.0": parent: Clients weight: 2 --- diff --git a/content/docs/3.0/reference/contribute.md b/content/docs/3.0/reference/contribute.md index 50e5a90c..36d555f9 100644 --- a/content/docs/3.0/reference/contribute.md +++ b/content/docs/3.0/reference/contribute.md @@ -2,10 +2,7 @@ title: Contribute description: How to be a part of TiKV menu: - nav: - parent: Docs - weight: 6 - docs: + "3.0": parent: Reference weight: 6 aliases: diff --git a/content/docs/3.0/reference/faq.md b/content/docs/3.0/reference/faq.md index 6493b5de..28e4e75d 100644 --- a/content/docs/3.0/reference/faq.md +++ b/content/docs/3.0/reference/faq.md @@ -2,10 +2,7 @@ title: FAQ description: FAQs about TiKV menu: - nav: - parent: Docs - weight: 5 - docs: + "3.0": parent: Reference weight: 4 aliases: diff --git a/content/docs/3.0/reference/introduction.md b/content/docs/3.0/reference/introduction.md index 18a141c9..78ce8272 100644 --- a/content/docs/3.0/reference/introduction.md +++ b/content/docs/3.0/reference/introduction.md @@ -2,12 +2,9 @@ title: Reference description: Details about TiKV menu: - docs: + "3.0": name: Reference weight: 3 - nav: - parent: Docs - weight: 3 --- This section includes instructions on using TiKV clients and tools. \ No newline at end of file diff --git a/content/docs/3.0/reference/query-layers.md b/content/docs/3.0/reference/query-layers.md index 600a542b..b64cf229 100644 --- a/content/docs/3.0/reference/query-layers.md +++ b/content/docs/3.0/reference/query-layers.md @@ -2,7 +2,7 @@ title: Query Layers description: Extend TiKV using stateless query layers menu: - docs: + "3.0": parent: Reference weight: 3 --- diff --git a/content/docs/3.0/reference/tools/introduction.md b/content/docs/3.0/reference/tools/introduction.md index 0d8eab7c..9badead1 100755 --- a/content/docs/3.0/reference/tools/introduction.md +++ b/content/docs/3.0/reference/tools/introduction.md @@ -2,7 +2,7 @@ title: Tools description: Tools which can be used to administrate TiKV menu: - docs: + "3.0": parent: Reference weight: 3 --- diff --git a/content/docs/3.0/reference/tools/pd-ctl.md b/content/docs/3.0/reference/tools/pd-ctl.md index 738e6d9b..340e40a6 100755 --- a/content/docs/3.0/reference/tools/pd-ctl.md +++ b/content/docs/3.0/reference/tools/pd-ctl.md @@ -2,7 +2,7 @@ title: pd-ctl description: Learn about interacting with pd-ctl menu: - docs: + "3.0": parent: Tools weight: 4 --- diff --git a/content/docs/3.0/reference/tools/pd-recover.md b/content/docs/3.0/reference/tools/pd-recover.md index 3c888280..35f3d7fe 100755 --- a/content/docs/3.0/reference/tools/pd-recover.md +++ b/content/docs/3.0/reference/tools/pd-recover.md @@ -2,7 +2,7 @@ title: pd-recover description: Learn about interacting with pd-recover menu: - docs: + "3.0": parent: Tools weight: 5 --- diff --git a/content/docs/3.0/reference/tools/pd-server.md b/content/docs/3.0/reference/tools/pd-server.md index 2a011153..3bb1f27f 100755 --- a/content/docs/3.0/reference/tools/pd-server.md +++ b/content/docs/3.0/reference/tools/pd-server.md @@ -2,7 +2,7 @@ title: pd-server description: Learn about interacting with pd-server menu: - docs: + "3.0": parent: Tools weight: 3 --- diff --git a/content/docs/3.0/reference/tools/tikv-ctl.md b/content/docs/3.0/reference/tools/tikv-ctl.md index af904f0b..be90c490 100755 --- a/content/docs/3.0/reference/tools/tikv-ctl.md +++ b/content/docs/3.0/reference/tools/tikv-ctl.md @@ -2,7 +2,7 @@ title: tikv-ctl description: Learn about interacting with tikv-ctl menu: - docs: + "3.0": parent: Tools weight: 2 --- diff --git a/content/docs/3.0/reference/tools/tikv-server.md b/content/docs/3.0/reference/tools/tikv-server.md index f181dd59..9a74383f 100755 --- a/content/docs/3.0/reference/tools/tikv-server.md +++ b/content/docs/3.0/reference/tools/tikv-server.md @@ -2,7 +2,7 @@ title: tikv-server description: Learn about interacting with tikv-server menu: - docs: + "3.0": parent: Tools weight: 1 --- diff --git a/content/docs/3.0/tasks/backup/introduction.md b/content/docs/3.0/tasks/backup/introduction.md index 8c44a26a..071e38ea 100644 --- a/content/docs/3.0/tasks/backup/introduction.md +++ b/content/docs/3.0/tasks/backup/introduction.md @@ -3,6 +3,6 @@ title: Backup description: Backup TiKV draft: true menu: - docs: + "3.0": parent: Tasks --- \ No newline at end of file diff --git a/content/docs/3.0/tasks/configure/introduction.md b/content/docs/3.0/tasks/configure/introduction.md index 72ebd6b4..eb01bc3b 100644 --- a/content/docs/3.0/tasks/configure/introduction.md +++ b/content/docs/3.0/tasks/configure/introduction.md @@ -2,7 +2,7 @@ title: Configure description: Configure a wide range of TiKV facets, including RocksDB, gRPC, the Placement Driver, and more menu: - docs: + "3.0": parent: Tasks weight: 3 --- diff --git a/content/docs/3.0/tasks/configure/limit.md b/content/docs/3.0/tasks/configure/limit.md index e4d30a98..cd796f82 100644 --- a/content/docs/3.0/tasks/configure/limit.md +++ b/content/docs/3.0/tasks/configure/limit.md @@ -2,7 +2,7 @@ title: Limit Config description: Learn how to configure scheduling rate limit on stores menu: - docs: + "3.0": parent: Configure weight: 4 --- diff --git a/content/docs/3.0/tasks/configure/namespace.md b/content/docs/3.0/tasks/configure/namespace.md index 0b7efb23..95092d7a 100644 --- a/content/docs/3.0/tasks/configure/namespace.md +++ b/content/docs/3.0/tasks/configure/namespace.md @@ -2,7 +2,7 @@ title: Namespace Config description: Learn how to configure namespace in TiKV. menu: - docs: + "3.0": parent: Configure weight: 3 --- diff --git a/content/docs/3.0/tasks/configure/region-merge.md b/content/docs/3.0/tasks/configure/region-merge.md index 321296b7..f1f5f176 100644 --- a/content/docs/3.0/tasks/configure/region-merge.md +++ b/content/docs/3.0/tasks/configure/region-merge.md @@ -2,7 +2,7 @@ title: Region Merge Config description: Learn how to configure Region Merge in TiKV. menu: - docs: + "3.0": parent: Configure weight: 5 --- diff --git a/content/docs/3.0/tasks/configure/rocksdb.md b/content/docs/3.0/tasks/configure/rocksdb.md index fd72b8e0..20b14823 100644 --- a/content/docs/3.0/tasks/configure/rocksdb.md +++ b/content/docs/3.0/tasks/configure/rocksdb.md @@ -2,7 +2,7 @@ title: RocksDB Config description: Learn how to configure namespace in TiKV. menu: - docs: + "3.0": parent: Configure weight: 6 --- diff --git a/content/docs/3.0/tasks/configure/security.md b/content/docs/3.0/tasks/configure/security.md index ef37a461..679819e1 100644 --- a/content/docs/3.0/tasks/configure/security.md +++ b/content/docs/3.0/tasks/configure/security.md @@ -2,7 +2,7 @@ title: Security Config description: Keeping your TiKV deployment secure menu: - docs: + "3.0": parent: Configure weight: 1 --- diff --git a/content/docs/3.0/tasks/configure/titan.md b/content/docs/3.0/tasks/configure/titan.md index a4753390..f0743ef0 100644 --- a/content/docs/3.0/tasks/configure/titan.md +++ b/content/docs/3.0/tasks/configure/titan.md @@ -2,7 +2,7 @@ title: Titan Config description: Learn how to enable Titan in TiKV. menu: - docs: + "3.0": parent: Configure weight: 7 --- diff --git a/content/docs/3.0/tasks/configure/topology.md b/content/docs/3.0/tasks/configure/topology.md index d41f0d78..8f280324 100644 --- a/content/docs/3.0/tasks/configure/topology.md +++ b/content/docs/3.0/tasks/configure/topology.md @@ -2,7 +2,7 @@ title: Topology Config description: Learn how to configure labels. menu: - docs: + "3.0": parent: Configure weight: 2 --- diff --git a/content/docs/3.0/tasks/deploy/ansible.md b/content/docs/3.0/tasks/deploy/ansible.md index fc4746d1..94c518f5 100644 --- a/content/docs/3.0/tasks/deploy/ansible.md +++ b/content/docs/3.0/tasks/deploy/ansible.md @@ -2,7 +2,7 @@ title: Ansible Deployment description: Use TiDB-Ansible to deploy a TiKV cluster on multiple nodes. menu: - docs: + "3.0": parent: Deploy weight: 2 --- diff --git a/content/docs/3.0/tasks/deploy/binary.md b/content/docs/3.0/tasks/deploy/binary.md index 3f34febc..c1e5507c 100644 --- a/content/docs/3.0/tasks/deploy/binary.md +++ b/content/docs/3.0/tasks/deploy/binary.md @@ -2,7 +2,7 @@ title: Binary Deployment description: Use binary files to deploy a TiKV cluster on a single machine or on multiple nodes for testing. menu: - docs: + "3.0": parent: Deploy weight: 4 --- diff --git a/content/docs/3.0/tasks/deploy/docker-compose.md b/content/docs/3.0/tasks/deploy/docker-compose.md index 0caedeab..f66bf0b0 100644 --- a/content/docs/3.0/tasks/deploy/docker-compose.md +++ b/content/docs/3.0/tasks/deploy/docker-compose.md @@ -2,7 +2,7 @@ title: Docker Compose/Swarm description: Use Docker Compose or Swarm to quickly deploy a TiKV testing cluster. menu: - docs: + "3.0": parent: Deploy weight: 5 --- diff --git a/content/docs/3.0/tasks/deploy/docker.md b/content/docs/3.0/tasks/deploy/docker.md index ae6bbc72..699d94de 100644 --- a/content/docs/3.0/tasks/deploy/docker.md +++ b/content/docs/3.0/tasks/deploy/docker.md @@ -2,7 +2,7 @@ title: Docker Deployment description: Use Docker to deploy a TiKV cluster on multiple nodes. menu: - docs: + "3.0": parent: Deploy weight: 3 --- diff --git a/content/docs/3.0/tasks/deploy/introduction.md b/content/docs/3.0/tasks/deploy/introduction.md index 88cf2439..6f83dbea 100644 --- a/content/docs/3.0/tasks/deploy/introduction.md +++ b/content/docs/3.0/tasks/deploy/introduction.md @@ -2,7 +2,7 @@ title: Deploy description: Prerequisites for deploying TiKV menu: - docs: + "3.0": parent: Tasks weight: 2 name: Deploy diff --git a/content/docs/3.0/tasks/introduction.md b/content/docs/3.0/tasks/introduction.md index 5bfeac56..a0ab54be 100644 --- a/content/docs/3.0/tasks/introduction.md +++ b/content/docs/3.0/tasks/introduction.md @@ -2,10 +2,7 @@ title: Tasks description: How to accomplish common tasks with TiKV menu: - nav: - parent: Docs - weight: 2 - docs: + "3.0": weight: 2 --- diff --git a/content/docs/3.0/tasks/monitor/introduction.md b/content/docs/3.0/tasks/monitor/introduction.md index 346618f4..605fcd85 100644 --- a/content/docs/3.0/tasks/monitor/introduction.md +++ b/content/docs/3.0/tasks/monitor/introduction.md @@ -2,7 +2,7 @@ title: Monitor description: Monitor TiKV menu: - docs: + "3.0": parent: Tasks weight: 4 --- diff --git a/content/docs/3.0/tasks/monitor/key-metrics.md b/content/docs/3.0/tasks/monitor/key-metrics.md index a606cd6b..2375b8fb 100644 --- a/content/docs/3.0/tasks/monitor/key-metrics.md +++ b/content/docs/3.0/tasks/monitor/key-metrics.md @@ -2,7 +2,7 @@ title: Key Metrics description: Learn some key metrics displayed on the Grafana Overview dashboard. menu: - docs: + "3.0": parent: Monitor weight: 2 --- diff --git a/content/docs/3.0/tasks/monitor/tikv-cluster.md b/content/docs/3.0/tasks/monitor/tikv-cluster.md index bf259daf..81299615 100644 --- a/content/docs/3.0/tasks/monitor/tikv-cluster.md +++ b/content/docs/3.0/tasks/monitor/tikv-cluster.md @@ -2,7 +2,7 @@ title: Monitoring a Cluster description: Learn how to monitor the state of a TiKV cluster. menu: - docs: + "3.0": parent: Monitor weight: 1 --- diff --git a/content/docs/3.0/tasks/scale/ansible.md b/content/docs/3.0/tasks/scale/ansible.md index 7afaba9f..7676ac77 100644 --- a/content/docs/3.0/tasks/scale/ansible.md +++ b/content/docs/3.0/tasks/scale/ansible.md @@ -2,7 +2,7 @@ title: Ansible Scaling description: Use TiDB-Ansible to scale out or scale in a TiKV cluster. menu: - docs: + "3.0": parent: Scale --- diff --git a/content/docs/3.0/tasks/scale/introduction.md b/content/docs/3.0/tasks/scale/introduction.md index 77cdefb7..03de5cbb 100644 --- a/content/docs/3.0/tasks/scale/introduction.md +++ b/content/docs/3.0/tasks/scale/introduction.md @@ -2,7 +2,7 @@ title: Scale description: Scale TiKV menu: - docs: + "3.0": parent: Tasks weight: 5 --- diff --git a/content/docs/3.0/tasks/try.md b/content/docs/3.0/tasks/try.md index 96cf296d..42acf90d 100644 --- a/content/docs/3.0/tasks/try.md +++ b/content/docs/3.0/tasks/try.md @@ -2,7 +2,7 @@ title: Try description: Try locally with Docker menu: - docs: + "3.0": parent: Tasks weight: 1 --- diff --git a/content/docs/3.1-beta/concepts/architecture.md b/content/docs/3.1-beta/concepts/architecture.md new file mode 100644 index 00000000..7672a97b --- /dev/null +++ b/content/docs/3.1-beta/concepts/architecture.md @@ -0,0 +1,84 @@ +--- +title: Architecture +description: How TiKV works and how it was built +menu: + "3.1-beta": + parent: Concepts +--- + +This page discusses the core concepts and architecture behind TiKV, including: + +* The [APIs](#apis) that applications can use to interact with TiKV +* The basic [system architecture](#system) underlying TiKV +* The anatomy of each [instance](#instance) in a TiKV installation +* The role of core system components, including the [Placement Driver](#placement-driver), [Store](#store), [Region](#region), and [Node](#node) +* TiKV's [transaction model](#transactions) +* The role of the [Raft consensus algorithm](#raft) in TiKV +* The [origins](#origins) of TiKV + +## APIs + +TiKV provides two APIs that you can use to interact with it: + +API | Description | Atomicity | Use when... +:---|:------------|:----------|:----------- +Raw | A lower-level key-value API for interacting directly with individual key-value pairs. | Single key | Your application doesn't require distributed transactions or multi-version concurrency control (**MVCC**) +Transactional | A higher-level key-value API that provides ACID semantics | Multiple keys | Your application requires distributed transactions and/or MVCC + +## System architecture {#system} + +The overall architecture of TiKV is illustrated in **Figure 1** below: + +{{< figure + src="/img/basic-architecture.png" + caption="The architecture of TiKV" + alt="TiKV architecture diagram" + width="70" + number="1" >}} + +## TiKV instance {#instance} + +The architecture of each TiKV instance is illustrated in **Figure 2** below: + +{{< figure + src="/img/tikv-instance.png" + caption="TiKV instance architecture" + alt="TiKV instance architecture diagram" + width="60" + number="2" >}} + + +## Placement driver (PD) {#placement-driver} + +The TiKV placement driver is the cluster manager of TiKV, which periodically checks replication constraints to balance load and data automatically across nodes and regions in a process called **auto-sharding**. + +## Store + +There is a [RocksDB](https://rocksdb.org) database within each Store and it stores data into the local disk. + +## Region + +Region is the basic unit of key-value data movement. Each Region is replicated to multiple Nodes. These multiple replicas form a Raft group. + +## Node + +A TiKV **Node** is just a physical node in the cluster, which could be a virtual machine, a container, etc. Within each Node, there are one or more **Store**s. The data in each Store is split across multiple regions. Data is distributed across Regions using the Raft algorithm. + +When a Node starts, the metadata for the Node, Store, and Region is recorded into the Placement Driver. The status of each Region and Store is regularly reported to the PD. + +## Transaction model {#transactions} + +TiKV's transaction model is similar to that of Google's [Percolator](https://ai.google/research/pubs/pub36726), a system built for processing updates to large data sets. Percolator uses an incremental update model in place of a batch-based model. + +TiKV's transaction model provides: + +* **Snapshot isolation** with lock, with semantics analogous to `SELECT ... FOR UPDATE` in SQL +* Externally consistent reads and writes in distributed transactions + +## Raft + +Data is distributed across TiKV instances via the [Raft consensus algorithm](https://raft.github.io/), which is based on the so-called [Raft paper](https://raft.github.io/raft.pdf) ("In Search of an Understandable Consensus Algorithm") from [Diego Ongaro](https://ongardie.net/diego/) and [John Ousterhout](https://web.stanford.edu/~ouster/cgi-bin/home.php). + +## The origins of TiKV {#origins} + +TiKV was originally created by [PingCAP](https://pingcap.com) to complement [TiDB](https://github.com/pingcap/tidb), a distributed [HTAP](https://en.wikipedia.org/wiki/Hybrid_transactional/analytical_processing_(HTAP)) database compatible with the [MySQL protocol](https://dev.mysql.com/doc/dev/mysql-server/latest/PAGE_PROTOCOL.html). diff --git a/content/docs/3.1-beta/concepts/features.md b/content/docs/3.1-beta/concepts/features.md new file mode 100644 index 00000000..955b67c0 --- /dev/null +++ b/content/docs/3.1-beta/concepts/features.md @@ -0,0 +1,9 @@ +--- +title: Features +description: The features of TiKV +menu: + "3.1-beta": + parent: Concepts +--- + +{{< features >}} \ No newline at end of file diff --git a/content/docs/3.1-beta/concepts/overview.md b/content/docs/3.1-beta/concepts/overview.md new file mode 100644 index 00000000..74077746 --- /dev/null +++ b/content/docs/3.1-beta/concepts/overview.md @@ -0,0 +1,44 @@ +--- +title: Concepts +description: Some basic facts about TiKV +menu: + nav: + name: Concepts + parent: Docs + weight: 1 + "3.1-beta": + weight: 1 +--- + +**TiKV** is a distributed transactional key-value database originally created by [PingCAP](https://pingcap.com/en) to complement [TiDB](https://github.com/pingcap/tidb). + +As an incubating project of the [Cloud Native Computing Foundation](https://www.cncf.io/), TiKV is intended to fill the role of a unifying distributed storage layer. TiKV excels at working with **data in the large** by supporting petabyte scale deployments spanning trillions of rows. + +It compliments other CNCF projects technologies like [etcd](https://etcd.io/) which is useful for low-volume metadata storage, and can be extended using [stateless query layers](../../reference/query-layers) which speak other protocols, like [TiDB](https://github.com/pingcap/tidb) speaking MySQL. + +{{< info >}} +The **Ti** in TiKV stands for **titanium**. Titanium has the highest strength-to-density ratio of any metallic element and is named after the Titans of Greek mythology. +{{< /info >}} + +## Notable Features + +{{< features featured >}} + +You can browse a complete list on the [features](../features) page. + +## Architecture + +{{< figure + src="/img/basic-architecture.png" + caption="The architecture of TiKV" + alt="TiKV architecture diagram" + width="70" + number="1" >}} + +You can read more in the [Concepts and architecture](../architecture/) documentation. + +## Codebase, Inspiration, and Culture + +TiKV is implemented in the [Rust](https://rust-lang.org) programming language. It uses technologies like [Facebook's RocksDB](https://rocksdb.org/) and [Raft](https://raft.github.io/). + +The project was originally inspired by [Google Spanner](https://ai.google/research/pubs/pub39966) and [HBase](https://hbase.apache.org). \ No newline at end of file diff --git a/content/docs/3.1-beta/reference/clients/c.md b/content/docs/3.1-beta/reference/clients/c.md new file mode 100644 index 00000000..f82f0d59 --- /dev/null +++ b/content/docs/3.1-beta/reference/clients/c.md @@ -0,0 +1,14 @@ +--- +title: C Client +description: Interact with TiKV using C. +menu: + "3.1-beta": + parent: Clients + weight: 4 +--- + +This document, like our C API, is still a work in progress. In the meantime, you can track development at [tikv/client-c](https://github.com/tikv/client-c/) repository. Most development happens on the `dev` branch. + +{{< warning >}} +You should not use the C client for production use until it is released. +{{< /warning >}} \ No newline at end of file diff --git a/content/docs/3.1-beta/reference/clients/go.md b/content/docs/3.1-beta/reference/clients/go.md new file mode 100644 index 00000000..ce5ae9fa --- /dev/null +++ b/content/docs/3.1-beta/reference/clients/go.md @@ -0,0 +1,361 @@ +--- +title: Go Client +description: Interact with TiKV using Go. +menu: + "3.1-beta": + parent: Clients + weight: 1 +--- + +To apply to different scenarios, TiKV provides two types of APIs for developers: the Raw Key-Value API and the Transactional Key-Value API. This document uses two examples to guide you through how to use the two APIs in TiKV. The usage examples are based on multiple nodes for testing. You can also quickly try the two types of APIs on a single machine. + +{{< warning >}} +It is **not recommended or supported** to use both the raw and transactional APIs on the same keyspace. +{{< /warning >}} + +## Try the Raw Key-Value API + +To use the Raw Key-Value API in applications developed in the Go language, take the following steps: + +1. Install the necessary packages. + + ```bash + export GO111MODULE=on + go mod init rawkv-demo + go get github.com/pingcap/tidb@master + ``` + +2. Import the dependency packages. + + ```go + import ( + "fmt" + "github.com/pingcap/tidb/config" + "github.com/pingcap/tidb/store/tikv" + ) + ``` + +3. Create a Raw Key-Value client. + + ```go + cli, err := tikv.NewRawKVClient([]string{"192.168.199.113:2379"}, config.Security{}) + ``` + + Description of two parameters in the above command: + + - `string`: a list of PD servers’ addresses + - `config.Security`: used to establish TLS connections, usually left empty when you do not need TLS + +4. Call the Raw Key-Value client methods to access the data on TiKV. The Raw Key-Value API contains the following methods, and you can also find them at [GoDoc](https://godoc.org/github.com/pingcap/tidb/store/tikv#RawKVClient). + + ```go + type RawKVClient struct + func (c *RawKVClient) Close() error + func (c *RawKVClient) ClusterID() uint64 + func (c *RawKVClient) Delete(key []byte) error + func (c *RawKVClient) Get(key []byte) ([]byte, error) + func (c *RawKVClient) Put(key, value []byte) error + func (c *RawKVClient) Scan(startKey, endKey []byte, limit int) (keys [][]byte, values [][]byte, err error) + ``` + +### Usage example of the Raw Key-Value API + +```go +package main + +import ( + "fmt" + + "github.com/pingcap/tidb/config" + "github.com/pingcap/tidb/store/tikv" +) + +func main() { + cli, err := tikv.NewRawKVClient([]string{"192.168.199.113:2379"}, config.Security{}) + if err != nil { + panic(err) + } + defer cli.Close() + + fmt.Printf("cluster ID: %d\n", cli.ClusterID()) + + key := []byte("Company") + val := []byte("PingCAP") + + // put key into tikv + err = cli.Put(key, val) + if err != nil { + panic(err) + } + fmt.Printf("Successfully put %s:%s to tikv\n", key, val) + + // get key from tikv + val, err = cli.Get(key) + if err != nil { + panic(err) + } + fmt.Printf("found val: %s for key: %s\n", val, key) + + // delete key from tikv + err = cli.Delete(key) + if err != nil { + panic(err) + } + fmt.Printf("key: %s deleted\n", key) + + // get key again from tikv + val, err = cli.Get(key) + if err != nil { + panic(err) + } + fmt.Printf("found val: %s for key: %s\n", val, key) +} +``` + +The result is like: + +```bash +INFO[0000] [pd] create pd client with endpoints [192.168.199.113:2379] +INFO[0000] [pd] leader switches to: http://127.0.0.1:2379, previous: +INFO[0000] [pd] init cluster id 6554145799874853483 +cluster ID: 6554145799874853483 +Successfully put Company:PingCAP to tikv +found val: PingCAP for key: Company +key: Company deleted +found val: for key: Company +``` + +RawKVClient is a client of the TiKV server and only supports the GET/PUT/DELETE/SCAN commands. The RawKVClient can be safely and concurrently accessed by multiple goroutines, as long as it is not closed. Therefore, for one process, one client is enough generally. + +### Possible Error + +- If you see this error: + + ```bash + build rawkv-demo: cannot load github.com/pingcap/pd/pd-client: cannot find module providing package github.com/pingcap/pd/pd-client + ``` + + You can run `GO111MODULE=on go get -u github.com/pingcap/tidb@master` to fix it. + +- If you got this error when you run `go get -u github.com/pingcap/tidb@master`: + + ``` + go: github.com/golang/lint@v0.0.0-20190409202823-959b441ac422: parsing go.mod: unexpected module path "golang.org/x/lint" + ``` + + You can run `go mod edit -replace github.com/golang/lint=golang.org/x/lint@latest` to fix it. [Refer Link](https://github.com/golang/lint/issues/446#issuecomment-483638233) + +## Try the Transactional Key-Value API + +The Transactional Key-Value API is more complicated than the Raw Key-Value API. Some transaction related concepts are listed as follows. For more details, see the [KV package](https://github.com/pingcap/tidb/tree/master/kv). + +- Storage + + Like the RawKVClient, a Storage is an abstract TiKV cluster. + +- Snapshot + + A Snapshot is the state of a Storage at a particular point of time, which provides some readonly methods. The multiple times read from a same Snapshot is guaranteed consistent. + +- Transaction + + Like the transactions in SQL, a Transaction symbolizes a series of read and write operations performed within the Storage. Internally, a Transaction consists of a Snapshot for reads, and a MemBuffer for all writes. The default isolation level of a Transaction is Snapshot Isolation. + +To use the Transactional Key-Value API in applications developed by golang, take the following steps: + +1. Install the necessary packages. + + ```bash + export GO111MODULE=on + go mod init txnkv-demo + go get github.com/pingcap/tidb@master + ``` + +2. Import the dependency packages. + + ```go + import ( + "flag" + "fmt" + "os" + + "github.com/juju/errors" + "github.com/pingcap/tidb/kv" + "github.com/pingcap/tidb/store/tikv" + "github.com/pingcap/tidb/terror" + + goctx "golang.org/x/net/context" + ) + ``` + +3. Create Storage using a URL scheme. + + ```go + driver := tikv.Driver{} + storage, err := driver.Open("tikv://192.168.199.113:2379") + ``` + +4. (Optional) Modify the Storage using a Transaction. + + The lifecycle of a Transaction is: _begin → {get, set, delete, scan} → {commit, rollback}_. + +5. Call the Transactional Key-Value API's methods to access the data on TiKV. The Transactional Key-Value API contains the following methods: + + ```go + Begin() -> Txn + Txn.Get(key []byte) -> (value []byte) + Txn.Set(key []byte, value []byte) + Txn.Iter(begin, end []byte) -> Iterator + Txn.Delete(key []byte) + Txn.Commit() + ``` + +### Usage example of the Transactional Key-Value API + +```go +package main + +import ( + "flag" + "fmt" + "os" + + "github.com/juju/errors" + "github.com/pingcap/tidb/kv" + "github.com/pingcap/tidb/store/tikv" + "github.com/pingcap/tidb/terror" + + goctx "golang.org/x/net/context" +) + +type KV struct { + K, V []byte +} + +func (kv KV) String() string { + return fmt.Sprintf("%s => %s (%v)", kv.K, kv.V, kv.V) +} + +var ( + store kv.Storage + pdAddr = flag.String("pd", "192.168.199.113:2379", "pd address:192.168.199.113:2379") +) + +// Init initializes information. +func initStore() { + driver := tikv.Driver{} + var err error + store, err = driver.Open(fmt.Sprintf("tikv://%s", *pdAddr)) + terror.MustNil(err) +} + +// key1 val1 key2 val2 ... +func puts(args ...[]byte) error { + tx, err := store.Begin() + if err != nil { + return errors.Trace(err) + } + + for i := 0; i < len(args); i += 2 { + key, val := args[i], args[i+1] + err := tx.Set(key, val) + if err != nil { + return errors.Trace(err) + } + } + err = tx.Commit(goctx.Background()) + if err != nil { + return errors.Trace(err) + } + + return nil +} + +func get(k []byte) (KV, error) { + tx, err := store.Begin() + if err != nil { + return KV{}, errors.Trace(err) + } + v, err := tx.Get(k) + if err != nil { + return KV{}, errors.Trace(err) + } + return KV{K: k, V: v}, nil +} + +func dels(keys ...[]byte) error { + tx, err := store.Begin() + if err != nil { + return errors.Trace(err) + } + for _, key := range keys { + err := tx.Delete(key) + if err != nil { + return errors.Trace(err) + } + } + err = tx.Commit(goctx.Background()) + if err != nil { + return errors.Trace(err) + } + return nil +} + +func scan(keyPrefix []byte, limit int) ([]KV, error) { + tx, err := store.Begin() + if err != nil { + return nil, errors.Trace(err) + } + it, err := tx.Iter(kv.Key(keyPrefix), nil) + if err != nil { + return nil, errors.Trace(err) + } + defer it.Close() + var ret []KV + for it.Valid() && limit > 0 { + ret = append(ret, KV{K: it.Key()[:], V: it.Value()[:]}) + limit-- + it.Next() + } + return ret, nil +} + +func main() { + pdAddr := os.Getenv("PD_ADDR") + if pdAddr != "" { + os.Args = append(os.Args, "-pd", pdAddr) + } + flag.Parse() + initStore() + + // set + err := puts([]byte("key1"), []byte("value1"), []byte("key2"), []byte("value2")) + terror.MustNil(err) + + // get + kv, err := get([]byte("key1")) + terror.MustNil(err) + fmt.Println(kv) + + // scan + ret, err := scan([]byte("key"), 10) + for _, kv := range ret { + fmt.Println(kv) + } + + // delete + err = dels([]byte("key1"), []byte("key2")) + terror.MustNil(err) +} +``` + +The result is like: + +```bash +INFO[0000] [pd] create pd client with endpoints [192.168.199.113:2379] +INFO[0000] [pd] leader switches to: http://192.168.199.113:2379, previous: +INFO[0000] [pd] init cluster id 6563858376412119197 +key1 => value1 ([118 97 108 117 101 49]) +key1 => value1 ([118 97 108 117 101 49]) +key2 => value2 ([118 97 108 117 101 50]) +``` diff --git a/content/docs/3.1-beta/reference/clients/introduction.md b/content/docs/3.1-beta/reference/clients/introduction.md new file mode 100644 index 00000000..b579c27c --- /dev/null +++ b/content/docs/3.1-beta/reference/clients/introduction.md @@ -0,0 +1,15 @@ +--- +title: Clients +description: Interact with TiKV using the raw key-value API or the transactional key-value API +menu: + "3.1-beta": + parent: Reference + weight: 2 +--- + +TiKV has clients for a number of languages: + +* [Go](../go) (Stable) +* [Java](../java) (Unstable) +* [Rust](../rust) (Unstable) +* [C](../c) (early development) \ No newline at end of file diff --git a/content/docs/3.1-beta/reference/clients/java.md b/content/docs/3.1-beta/reference/clients/java.md new file mode 100644 index 00000000..f1a17dc6 --- /dev/null +++ b/content/docs/3.1-beta/reference/clients/java.md @@ -0,0 +1,14 @@ +--- +title: Java Client +description: Interact with TiKV using Java. +menu: + "3.1-beta": + parent: Clients + weight: 3 +--- + +This document, like our Java API, is still a work in progress. In the meantime, you can track development at [tikv/client-java](https://github.com/tikv/client-java/) repository. + +{{< warning >}} +You should not use the Java client for production use until it is released. +{{< /warning >}} \ No newline at end of file diff --git a/content/docs/3.1-beta/reference/clients/rust.md b/content/docs/3.1-beta/reference/clients/rust.md new file mode 100644 index 00000000..72cfc122 --- /dev/null +++ b/content/docs/3.1-beta/reference/clients/rust.md @@ -0,0 +1,199 @@ +--- +title: Rust Client +description: Interact with TiKV using Rust. +menu: + "3.1-beta": + parent: Clients + weight: 2 +--- + +TiKV offers two APIs that you can interact with: + +API | Description | Atomicity | Use when... +:---|:------------|:----------|:----------- +[Raw](#raw) | A lower-level key-value API for interacting directly with individual key-value pairs. | Single key | Your application doesn't require distributed transactions or multi-version concurrency control (MVCC) +[Transactional](#transactional) | A higher-level key-value API that provides ACID semantics | Multiple keys | Your application requires distributed transactions and/or MVCC + +{{< warning >}} +It is **not recommended or supported** to use both the raw and transactional APIs on the same keyspace. +{{< /warning >}} + +There are several clients that connect to TiKV: + +* [Rust](https://github.com/tikv/client-rust) +* [Java](https://github.com/tikv/client-java) +* [Go](https://github.com/tikv/client-go) + +Below we use the Rust client for some examples, but you should find all clients work similarly. + +## Basic Types {#types} + +Both clients use a few basic types for most of their API: + +* `Key`, a wrapper around a `Vec` symbolizing the 'key' in a key-value pair. +* `Value`, a wrapper around a `Vec` symbolizing the 'value' in a key-value pair. +* `KvPair`, a tuple of `(Key, Value)` representing a key-value pair. +* `KeyRange`, a trait representing a range of `Key`s from one value to either another value, or the end of the entire dataset. + +The `Key` and `Value` types implement `Deref>` so they can generally be used just like their contained values. Where possible API calls accept `impl Into` instead of the type `T` when it comes to `Key`, `Value`, and `KvPair`. + +If you're using your own key or value types, we reccomend implementing `Into` and/or `Into` for them where appropriate. You can also `impl KeyRange` if you have any range types. + +## Add the dependency {#dependency} + +This guide assumes you are using Rust 1.31 or above. You will also need an already deployed TiKV and PD cluster, since TiKV is not an embedded database. + +To start, open the `Cargo.toml` of your project, and add the `tikv-client` and `futures` as dependencies. + + + +```toml +[dependencies] +tikv-client = { git = "https://github.com/tikv/client-rust" } +futures = "0.1" +``` + +## Connect a client {#connnect} + +In your `src/main.rs`, import the raw API as well as the functionality of the `Future` trait. + +**Note:** In this example we used `raw`, but you can also use `transaction`. The process is the same. + +```rust +use tikv_client::{Config, raw::Client} +use futures::Future; +``` + +Build an instance of `Config`, then use it to build an instance of a `Client`. + +```rust +let config = Config::new(vec![ // Always use more than one PD endpoint! + "192.168.0.100:2379", + "192.168.0.101:2379", + "192.168.0.102:2379", +]).with_security( // Configure TLS if used. + "root.ca", + "internal.cert", + "internal.key", +); + +let unconnected_client = Client::new(config); +let client = unconnected_client.wait()?; // Block and resolve the future. +``` + +The value returned by `Client::new` is a `Future`. Futures need to be resolved in order to obtain the output. During the resolution of the future the client must create a connection with the cluster. + +{{< info >}} +If your application is syncronous you can call `.wait()` to block the current task until the future is resolved. If your application is asyncronous you might have better ways (eg. a Tokio reactor) of dealing with this. +{{< /info >}} + +With a connected client, you'll be able to send requests to TiKV. This client supports both singlular or batch operations. + +## Raw key-value API {#raw} + +Using a connected `raw::Client`, you can perform actions such as `put`, `get`, and `delete`: + +```rust +let client = Client::new(config).wait(); +// Data stored in TiKV does not need to be UTF-8. +let key = "TiKV".to_bytes(); +let value = "Astronaut".to_bytes(); + +// This creates a future that must be resolved. +let req = client.put( + key, // Vec impl Into + value // Vec impl Into +); +req.wait()?; + +let req = client.get(key); +let result = req.wait()?; + +// `Value` derefs to `Vec`. +assert_eq!(result, Some(value)); + +let req = client.delete(key); +req.wait()?; + +let req = client.get(key).wait()?; +assert_eq!(result, None); +``` + +You can also perform `scan`s, giving you all the values for keys in a given range: + +```rust +// For stability and reliability, it's good to chose a reasonable limit. +const REASONABLE_LIMIT = 1000; +// If you are using UTF-8,`Key` and `Value` arguments can be provided as +// `String` or `&'static str` as well. +const (START, END) = ("C", "F"); + +// Scanning can also work on an open end (Eg `START..`) +let req = client.scan(START..END, REASONABLE_LIMIT); +let result: Vec = req.wait()?; +``` + +These functions also have batch variants which accept sets and return `Vec<_>`s of data. These offer considerably reduced network overhead and can result in dramatic performance increases under certain workloads. + +For documented, tested examples of all functionalities, check the documentation of `raw::Client` in the generated Rust documentation. + +## Transactional key-value API {#transactional} + +> The transactional API of the Rust client is incomplete. You can track the progress with [issue #15](https://github.com/tikv/client-rust/issues/15). For a complete implementation, you can try the [Go client](https://github.com/pingcap/tidb/store/tikv). + +Using a connected `transaction::Client` you can then begin a transaction: + +```rust +let client = Client::new(config).wait(); +let txn = client.begin(); +``` + +Then it's possible to send commands like `get`, `set`, `delete`, or `scan`. Batch variants also exist. + +```rust +// `Key` and `Value` wrap around `Vec` values. +// This means data need not be UTF-8. +let key = "TiKV".to_bytes(); +let value = "Astronaut".to_bytes(); + +// This creates a future that must be resolved. +let req = txn.set(key, value); +req.wait()?; + +let req = txn.get(key); +let result = req.wait()?; + +// `Value` and `Key` deref to `Vec`. +// This means you should find them easy to work with. +assert_eq!(result, Some(value)); + +let req = txn.delete(key); +req.wait()?; + +let req = txn.get(key).wait()?; +assert_eq!(result, None); + +// For more detail on scanning, see the raw section above or the documentation. +let req = client.scan("A".."B", 1000); +let result: Vec = req.wait()?; +``` + +Commit these changes when you're ready, or roll back if you prefer to abort the operation: + +```rust +if all_is_good { + txn.commit()?; +} else { + txn.rollback()? +} +``` + +## Beyond the Basics + +At this point you're familiar with the basic functionality of TiKV. To begin integrating with TiKV you should explore the documentation of your favorite client from those we listed above. + +For the Rust client, you can find the full documentation for the client (and all your dependencies) by running: + +```bash +cargo doc --package tikv-client --open +``` diff --git a/content/docs/3.1-beta/reference/contribute.md b/content/docs/3.1-beta/reference/contribute.md new file mode 100644 index 00000000..171729bb --- /dev/null +++ b/content/docs/3.1-beta/reference/contribute.md @@ -0,0 +1,82 @@ +--- +title: Contribute +description: How to be a part of TiKV +menu: + nav: + parent: Docs + weight: 6 + "3.1-beta": + parent: Reference + weight: 6 +aliases: + - /docs/3.0/contribute/contribute-to-tikv/ +--- + +As an open source project, TiKV cannot grow without support and participating of contributors from the community. If you would like to contribute to the TiKV code, our documentation, or even the website, we would appreciate your help. And we are glad to provide any support along the way. + +## How to be a TiKV Contributor + +If a PR (Pull Request) submitted to the TIKV related projects by you is approved and merged, then you become a TiKV Contributor. + +## Pick an area to contribute + +You can choose the one of the following areas to contribute: + +- [TiKV core](https://github.com/tikv/tikv) + + This is where we host the core code base of the TiKV project, which is developed in Rust. See [Contribute to TiKV](https://github.com/tikv/tikv/blob/master/CONTRIBUTING.md) for details on how to make contributions to the TiKV core code base. + +- [TiKV documentation](https://github.com/tikv/website/tree/master/content/docs) + + We host our documentation within the [TiKV website] repository. The documentation is generated via the Hugo framework. See [Contribute to Docs](../docs) for detailed steps of contribution. + +- Libraries + + The TiKV team actively develops and maintains a bunch of dependencies used in TiKV, which you may be also interested in: + + - [rust-prometheus](https://github.com/pingcap/rust-prometheus): The Prometheus client for Rust, our metrics collecting and reporting library + - [rust-rocksdb](https://github.com/pingcap/rust-rocksdb): Our RocksDB binding and wrapper for Rust + - [raft-rs](https://github.com/pingcap/raft-rs): The Raft distributed consensus algorithm implemented in Rust + - [grpc-rs](https://github.com/pingcap/grpc-rs): The gRPC library for Rust built on the gRPC C Core library and Rust Futures + - [fail-rs](https://github.com/pingcap/fail-rs): Fail points for Rust + + For details on how to contribute to the above dependent libraries of TiKV, refer to the **README** file in the corresponding repository. + + +- [TiKV Clients](https://github.com/tikv) + + This is where we host TiKV clients in different languages, which are: + + - [Go client](https://github.com/tikv/client-go) + - [Rust client](https://github.com/tikv/client-rust) + - [Java client](https://github.com/tikv/client-java) + - [C client](https://github.com/tikv/client-c) + + As the Go client came out the earliest, it has evolved into a stable shape. Clients like Rust and Java are not stable enough, while client C is still in early development phase, which is a good timing to get yourself involved with the development of TiKV clients. See [Contribute to TiKV](https://github.com/tikv/tikv/blob/master/CONTRIBUTING.md) for details on how to make contributions to the TiKV clients. + +- [RFCs](https://github.com/tikv/rfcs) + + This is where the design process of a new feature starts. If you wish to contribute something major or substantial to TiKV, we would love to see that and will ask you to submit a Request for Change (RFC) to generate a consensus among the TiKV community. See the [README](https://github.com/tikv/rfcs/blob/master/README.md) file and existing RFCs for references on how to draft and submit an RFC. + +- Meetups/Events + + As an open source project, we are passionate about meetups and events, where the community gather and share. Besides the official events hosted by TiKV, we would love to see you be the organizer or the participant of an event/meetup. Showing up, giving a talk, or joining in the discussions would all be a form of contribution in our eyes, and we appreciate that. Let us know if you have any ideas. + +## Find an issue to work on + +For beginners, we have prepared many suitable tasks for you. You can check out, for example, our [Help Wanted issues](https://github.com/tikv/tikv/issues?q=is%3Aissue+is%3Aopen+label%3A%22S%3A+HelpWanted%22) in the TiKV repository. + +See below for some commonly used labels across major repositories listed in [Pick an area to contribute](#pick-an-area-to-contribute): + +- **`bug`** Something is wrong; can be small or big in scope +- **`good first issue`** - An ideal first issue to work on for beginners, with mentoring available +- **`help wanted`** - Help wanted. Contributions are very welcome! +- **`discussion`** - Status: Under discussion or need discussion +- **`enhancement`** New feature or request +- **`question`** Further information is requested, or the question is to be answered. + +## Ask a question + +{{< info >}} +If you need any help or mentoring getting started, understanding the codebase, or making a PR (or anything else really), please ask on [Slack](https://join.slack.com/t/tikv-wg/shared_invite/enQtNTUyODE4ODU2MzI0LTgzZDQ3NzZlNDkzMGIyYjU1MTA0NzIwMjFjODFiZjA0YjFmYmQyOTZiNzNkNzg1N2U1MDdlZTIxNTU5NWNhNjk), or [WeChat](https://github.com/tikv/tikv#wechat). +{{< /info >}} \ No newline at end of file diff --git a/content/docs/3.1-beta/reference/faq.md b/content/docs/3.1-beta/reference/faq.md new file mode 100644 index 00000000..19744dd7 --- /dev/null +++ b/content/docs/3.1-beta/reference/faq.md @@ -0,0 +1,169 @@ +--- +title: FAQ +description: FAQs about TiKV +menu: + nav: + parent: Docs + weight: 5 + "3.1-beta": + parent: Reference + weight: 4 +aliases: + - /docs/3.0/faq/faq/ +--- + +## What is TiKV? + +TiKV is a distributed Key-Value database that features in geo-replication, horizontal scalability, consistent distributed transactions and coprocessor support. + +## How do TiDB and TiKV work together? What is the relationship between the two? + +TiDB works as the SQL layer and TiKV works as the Key-Value layer. TiDB provides TiKV the SQL enablement and turns TiKV into a NewSQL database. TiDB and TiKV work together to be as scalable as a NoSQL database while maintains the ACID transactions of a relational database. + +## Why do you have separate layers? + +Inspired by Google F1 and Spanner, TiDB and TiKV adopt a highly-layered architecture. This architecture supports pluggable storage drivers and engines, which powers you to customize your database solutions based on your own business requirements. Meanwhile, this architecture makes it easy to debug, update, tune, and maintain. You won’t have to go through the whole system just to find and fix a bug in one module. + +## How do I run TiKV? + +For further information, see [Quick Start](../../tasks/try) for deploying a TiKV testing cluster, or [Deploy TiKV](../../tasks/deploy/introduction) for deploying TiKV in production. + +## When to use TiKV? + +TiKV is at your service if your applications require: + +* Horizontal scalability (including writes) +* Strong consistency +* Support for distributed ACID transactions + +## When is TiKV inappropriate? + +TiKV is not yet ready to deal with very low latency reads and writes. + +## How does TiKV scale? + +Grow TiKV as your business grows. You can increase the capacity simply by adding more machines. You can run TiKV across physical, virtual, container, and cloud environments. + +PD ([Placement Driver](https://github.com/pingcap/pd)) periodically checks replication constraints and balances the load, and it handles data movement automatically. When PD notices that the load is too high, it will rebalance data. + +## How is TiKV highly available? + +TiKV is self-healing. With its strong consistency guarantee, whether it’s data machine failures or even downtime of an entire data center, your data can be recovered automatically. + +## How is TiKV strongly-consistent? + +Strong consistency means all replicas return the same value when queried for the attribute of an object. TiKV uses the [Raft consensus algorithm](https://raft.github.io/) to ensure consistency among multiple replicas. TiKV allows a collection of machines to work as a coherent group that can survive the failures of some of its members. + +## Does TiKV support distributed transactions? + +Yes. The transaction model in TiKV is inspired by Google’s Percolator, a paper published in 2006. It’s mainly a two-phase commit protocol with some practical optimizations. This model relies on a timestamp allocator to assign a monotonically increasing timestamp for each transaction, so that conflicts can be detected. + +## Does TiKV have ACID semantics? + +Yes. ACID semantics are guaranteed in TiKV: + +* Atomicity: Each transaction in TiKV is "all or nothing": if one part of the transaction fails, then the entire transaction fails, and the database state is left unchanged. TiKV guarantees atomicity in each and every situation, including power failures, errors, and crashes. +* Consistency: TiKV ensures that any transaction brings the database from one valid state to another. Any data written to the TiKV database must be valid according to all defined rules. +* Isolation: TiKV provides snapshot isolation (SI), snapshot isolation with lock, and externally consistent reads and writes in distributed transactions. +* Durability: TiKV allows a collection of machines to work as a coherent group that can survive the failures of some of its members. So in TiKV, once a transaction has been committed, it will remain so, even in the event of power loss, crashes, or errors. + +## How are transactions in TiKV lock-free? + +TiKV has an optimistic transaction model, which means the client will buffer all the writes within a transaction, and when the client calls commit function, the writes will be packed and sent to the servers. If there is no conflict, the writes which are the key-value pairs with specific version are written into the database, and can be read by other transactions. + +## Can I use TiKV as a key-value store? + +Yes. That's what TiKV is. + +## How does TiKV compare to NoSQL databases like Cassandra, HBase, or MongoDB? + +TiKV is as scalable as NoSQL databases like to advertise, while including features like externally consistent distributed transactions and good support for stateless query layers such as TiSpark (Spark), Titan (Redis), or TiDB (MySQL) + +## What is the recommended number of replicas in the TiKV cluster? Is it better to keep the minimum number for high availability? + +3 replicas for each Region is sufficient for a testing environment. However, you should never operate a TiKV cluster with under 3 nodes in a production scenario. Depending on infrastructure, workload, and resiliency needs, you may wish to increase this number. + +## If a node is down, will the service be affected? How long? + +TiKV uses Raft to synchronize data among multiple replicas (by default 3 replicas for each Region). If one replica goes wrong, the other replicas can guarantee data safety. Based on the Raft protocol, if a single leader fails as the node goes down, a follower in another node is soon elected as the Region leader after a maximum of 2 * lease time (lease time is 10 seconds). + +## Is the Range of the Key data table divided before data access? + +No. It differs from the table splitting rules of MySQL. In TiKV, the table Range is dynamically split based on the size of Region. + +## How does Region split? + +Region is not divided in advance, but it follows a Region split mechanism. When the Region size exceeds the value of the `region-split-size` or `region-split-keys` parameters, split is triggered. After the split, the information is reported to PD. + +## What are the features of TiKV block cache? + +TiKV implements the Column Family (CF) feature of RocksDB. By default, the KV data is eventually stored in the 3 CFs (default, write and lock) within RocksDB. + +- The default CF stores real data and the corresponding parameter is in `[rocksdb.defaultcf]`. The write CF stores the data version information (MVCC) and index-related data, and the corresponding parameter is in `[rocksdb.writecf]`. The lock CF stores the lock information and the system uses the default parameter. +- The Raft RocksDB instance stores Raft logs. The default CF mainly stores Raft logs and the corresponding parameter is in `[raftdb.defaultcf]`. +- All CFs have a shared block-cache to cache data blocks and improve RocksDB read speed. The size of block-cache is controlled by the `block-cache-size` parameter. A larger value of the parameter means more hot data can be cached and is more favorable to read operation. At the same time, it consumes more system memory. +- Each CF has an individual write-buffer and the size is controlled by the `write-buffer-size` parameter. + +## What are the TiKV scenarios that take up high I/O, memory, CPU, and exceed the parameter configuration? + +Writing or reading a large volume of data in TiKV takes up high I/O, memory and CPU. Executing very complex queries costs a lot of memory and CPU resources, such as the scenario that generates large intermediate result sets. + +## Does TiKV have the `innodb_flush_log_trx_commit` parameter like MySQL, to guarantee the security of data? + +Yes. Currently, the standalone storage engine uses two RocksDB instances. One instance is used to store the raft-log. When the `sync-log` parameter in TiKV is set to true, each commit is mandatorily flushed to the raft-log. If a crash occurs, you can restore the KV data using the raft-log. + +## What is the recommended server configuration for WAL storage, such as SSD, RAID level, cache strategy of RAID card, NUMA configuration, file system, I/O scheduling strategy of the operating system? + +WAL belongs to ordered writing, and currently, we don't have separate configuration for it. Recommended configuration is as follows: + +- SSD +- RAID 10 preferred +- Cache strategy of RAID card and I/O scheduling strategy of the operating system: currently no specific best practices; you can use the default configuration in Linux 7 or later +- NUMA: no specific suggestion; for memory allocation strategy, you can use `interleave = all` +- File system: ext4 + +## Can Raft + multiple replicas in the TiKV architecture achieve absolute data safety? Is it necessary to apply the most strict mode (`sync-log = true`) to a standalone storage? + +Data is redundantly replicated between TiKV nodes using the [Raft consensus algorithm](https://raft.github.io/) to ensure recoverability should a node failure occur. Only when the data has been written into more than 50% of the replicas will the application return ACK (two out of three nodes). However, theoretically, two nodes might crash. Therefore, except for scenarios with less strict requirement on data security but extreme requirement on performance, it is strongly recommended that you enable the sync-log mode. + +As an alternative to using `sync-log`, you may also consider having five replicas instead of three in your Raft group. This would allow for the failure of two replicas, while still providing data safety. + +For a standalone TiKV node, it is still recommended to enable the sync-log mode. Otherwise, the last write might be lost in case of a node failure. + +## Why does TiKV frequently switch Region leader? + +- Leaders can not reach out to followers. E.g., network problem or node failure. +- Leader balance from PD. E.g., PD wants to transfer leaders from a hotspot node to others. + +## The `cluster ID mismatch` message is displayed when starting TiKV. + +This is because the cluster ID stored in local TiKV is different from the cluster ID specified by PD. When a new PD cluster is deployed, PD generates random cluster IDs. TiKV gets the cluster ID from PD and stores the cluster ID locally when it is initialized. The next time when TiKV is started, it checks the local cluster ID with the cluster ID in PD. If the cluster IDs don't match, the `cluster ID mismatch` message is displayed and TiKV exits. + +If you previously deploy a PD cluster, but then you remove the PD data and deploy a new PD cluster, this error occurs because TiKV uses the old data to connect to the new PD cluster. + +## The `duplicated store address` message is displayed when starting TiKV. + +This is because the address in the startup parameter has been registered in the PD cluster by other TiKVs. This error occurs when there is no data folder under the directory that TiKV `--store` specifies, but you use the previous parameter to restart the TiKV. + +To solve this problem, use the [`store delete`](https://github.com/pingcap/pd/tree/55db505e8f35e8ab4e00efd202beb27a8ecc40fb/tools/pd-ctl#store-delete--label--weight-store_id----jqquery-string) function to delete the previous store and then restart TiKV. + +## TiKV master and slave use the same compression algorithm, why the results are different? + +Currently, some files of TiKV master have a higher compression rate, which depends on the underlying data distribution and RocksDB implementation. It is normal that the data size fluctuates occasionally. The underlying storage engine adjusts data as needed. + +## What are causes for "TiKV channel full"? + +- The Raftstore thread is too slow or blocked by I/O. You can view the CPU usage status of Raftstore. +- TiKV is too busy (CPU, disk I/O, etc.) and cannot manage to handle it. + +## How is the write performance in the most strict data available mode (`sync-log = true`)? + +Generally, enabling `sync-log` reduces about 30% of the performance. For write performance when `sync-log` is set to `false`, see [Performance test result for TiDB using Sysbench](https://github.com/pingcap/docs/blob/master/v3.0/benchmark/sysbench-v4.md). + +## Why does `IO error: No space left on device While appending to file` occur? + +This is because the disk space is not enough. You need to add nodes or enlarge the disk space. + +## Why does the OOM (Out of Memory) error occur frequently in TiKV? + +The memory usage of TiKV mainly comes from the block-cache of RocksDB, which is 40% of the system memory size by default. When the OOM error occurs frequently in TiKV, you should check whether the value of `block-cache-size` is set too high. In addition, when multiple TiKV instances are deployed on a single machine, you need to explicitly configure the parameter to prevent multiple instances from using too much system memory that results in the OOM error. diff --git a/content/docs/3.1-beta/reference/introduction.md b/content/docs/3.1-beta/reference/introduction.md new file mode 100644 index 00000000..de2a7d19 --- /dev/null +++ b/content/docs/3.1-beta/reference/introduction.md @@ -0,0 +1,13 @@ +--- +title: Reference +description: Details about TiKV +menu: + "3.1-beta": + name: Reference + weight: 3 + nav: + parent: Docs + weight: 3 +--- + +This section includes instructions on using TiKV clients and tools. \ No newline at end of file diff --git a/content/docs/3.1-beta/reference/query-layers.md b/content/docs/3.1-beta/reference/query-layers.md new file mode 100644 index 00000000..22bb2cdd --- /dev/null +++ b/content/docs/3.1-beta/reference/query-layers.md @@ -0,0 +1,16 @@ +--- +title: Query Layers +description: Extend TiKV using stateless query layers +menu: + "3.1-beta": + parent: Reference + weight: 3 +--- + +There are several projects which harness TiKV to power their storage: + +* [TiDB](https://github.com/pingcap/tidb) (MySQL) +* [TiPrometheus](https://github.com/bragfoo/TiPrometheus) (Prometheus) +* [Titan](https://github.com/distributedio/titan) (Redis) +* [Tidis](https://github.com/yongman/tidis) (Redis) +* [Titea](https://github.com/gengmei-tech/titea) (Redis) \ No newline at end of file diff --git a/content/docs/3.1-beta/reference/tools/introduction.md b/content/docs/3.1-beta/reference/tools/introduction.md new file mode 100644 index 00000000..ed22639f --- /dev/null +++ b/content/docs/3.1-beta/reference/tools/introduction.md @@ -0,0 +1,18 @@ +--- +title: Tools +description: Tools which can be used to administrate TiKV +menu: + "3.1-beta": + parent: Reference + weight: 3 +--- + +There are a number of components and tools involved in maintaining a TiKV deployment. + +You can browse documentation on: + +* [`tikv-server`](../tikv-server): The TiKV service stores data and serves client requests. +* [`tikv-ctl`](../tikv-ctl): The control plane tool for managing TiKV, both online or offline. +* [`pd-server`](../pd-server): The PD service manages cluster metadata and transaction timestamps. +* [`pd-ctl`](../pd-ctl): The control plane tool for managing PD. +* [`pd-recover`](../pd-recover): A disaster recovery tool for PD. \ No newline at end of file diff --git a/content/docs/3.1-beta/reference/tools/pd-ctl.md b/content/docs/3.1-beta/reference/tools/pd-ctl.md new file mode 100644 index 00000000..285b4ac1 --- /dev/null +++ b/content/docs/3.1-beta/reference/tools/pd-ctl.md @@ -0,0 +1,932 @@ +--- +title: pd-ctl +description: Learn about interacting with pd-ctl +menu: + "3.1-beta": + parent: Tools + weight: 4 +--- + +As a command line tool of PD, PD Control obtains the state information of the cluster and tunes the cluster. + +## Source code compiling + +1. [Go](https://golang.org/) Version 1.11 or later +2. In the root directory of the [PD project](https://github.com/pingcap/pd), use the `make` command to compile and generate `bin/pd-ctl` + +> **Note:** Generally, you do not need to compile source code because the PD Control tool already exists in the released Binary or Docker. For developer users, the `make` command can be used to compile source code. + +## Usage + +Single-command mode: + +```bash +./pd-ctl store -u http://127.0.0.1:2379 +``` + +Interactive mode: + +```bash +./pd-ctl -u http://127.0.0.1:2379 +``` + +Use environment variables: + +```bash +export PD_ADDR=http://127.0.0.1:2379 +./pd-ctl +``` + +Use TLS to encrypt: + +```bash +./pd-ctl -u https://127.0.0.1:2379 --cacert="path/to/ca" --cert="path/to/cert" --key="path/to/key" +``` + +## Command line flags + +### \-\-pd,-u + ++ PD address ++ Default address: http://127.0.0.1:2379 ++ Environment variable: PD_ADDR + +### \-\-detach,-d + ++ Use single command line mode (not entering readline) ++ Default: true + +### --cacert + ++ Specify the path to the certificate file of the trusted CA in PEM format ++ Default: "" + +### --cert + ++ Specify the path to the certificate of SSL in PEM format ++ Default: "" + +### --key + ++ Specify the path to the certificate key file of SSL in PEM format, which is the private key of the certificate specified by `--cert` ++ Default: "" + +### --version,-V + ++ Print the version information and exit ++ Default: false + +## Command + +### `cluster` + +Use this command to view the basic information of the cluster. + +Usage: + +```bash +>> cluster // To show the cluster information +{ + "id": 6493707687106161130, + "max_peer_count": 3 +} +``` + +### `config [show | set