Skip to content

Commit 0afb44b

Browse files
datlechindatlechin
committed
docs: add Chinese translation for Cassandra/ScyllaDB documentation
1 parent 3e53cb7 commit 0afb44b

4 files changed

Lines changed: 386 additions & 5 deletions

File tree

‎docs/docs.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -233,6 +233,8 @@
233233
"zh/databases/redshift",
234234
"zh/databases/oracle",
235235
"zh/databases/clickhouse",
236+
"zh/databases/cassandra",
237+
"zh/databases/duckdb",
236238
"zh/databases/mssql",
237239
"zh/databases/oracle",
238240
"zh/databases/ssh-tunneling"

‎docs/zh/databases/cassandra.mdx‎

Lines changed: 356 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,356 @@
1+
---
2+
title: Cassandra / ScyllaDB
3+
description: 连接 Cassandra 和 ScyllaDB 集群，浏览 keyspace，执行 CQL 查询
4+
---
5+
6+
# Cassandra / ScyllaDB 连接
7+
8+
TablePro 通过 CQL 原生协议支持 Apache Cassandra 3.11+ 和 ScyllaDB 4.0+。浏览 keyspace、查看表结构、查看物化视图，并在编辑器中执行 CQL 查询。
9+
10+
## 快速设置
11+
12+
<Steps>
13+
<Step title="打开连接表单">
14+
在欢迎界面点击 **New Connection**，或选择 **File** > **New Connection**
15+
</Step>
16+
<Step title="选择 Cassandra 或 ScyllaDB">
17+
从数据库类型选择器中选择 **Cassandra** 或 **ScyllaDB**
18+
</Step>
19+
<Step title="输入连接信息">
20+
填写 host、port、username、password 和 keyspace
21+
</Step>
22+
<Step title="测试并连接">
23+
点击 **Test Connection**，然后点击 **Create**
24+
</Step>
25+
</Steps>
26+
27+
## 连接设置
28+
29+
### 必填字段
30+
31+
| 字段 | 描述 | 默认值 |
32+
|-------|-------------|---------|
33+
| **Name** | 连接标识名称 | - |
34+
| **Host** | Contact point 主机名或 IP | `localhost` |
35+
| **Port** | CQL 原生传输端口 | `9042` |
36+
37+
### 可选字段
38+
39+
| 字段 | 描述 |
40+
|-------|-------------|
41+
| **Username** | 认证用户名 |
42+
| **Password** | 认证密码 |
43+
| **Keyspace** | 连接后使用的默认 keyspace |
44+
45+
<Tip>
46+
本地 Cassandra 安装通常未启用认证。本地开发时可以留空 username 和 password。
47+
</Tip>
48+
49+
## 连接 URL 格式
50+
51+
使用 Cassandra 或 ScyllaDB URL 导入连接。
52+
53+
参阅 [连接 URL 参考](/zh/databases/connection-urls#cassandra--scylladb) 了解完整的 URL 格式。
54+
55+
## 配置示例
56+
57+
### 本地开发服务器
58+
59+
```text
60+
Name: Local Cassandra
61+
Host: localhost
62+
Port: 9042
63+
Username: （留空）
64+
Password: （留空）
65+
Keyspace: my_keyspace
66+
```
67+
68+
### Docker Cassandra 容器
69+
70+
```text
71+
Name: Docker Cassandra
72+
Host: localhost
73+
Port: 9042（或你映射的端口）
74+
Username: cassandra
75+
Password: cassandra
76+
Keyspace: （留空）
77+
```
78+
79+
### DataStax Astra DB（云）
80+
81+
```text
82+
Name: Astra DB
83+
Host: <your-cluster-id>-<region>.apps.astra.datastax.com
84+
Port: 29042
85+
Username: （来自 token 的 Client ID）
86+
Password: （来自 token 的 Client Secret）
87+
Keyspace: my_keyspace
88+
```
89+
90+
<Note>
91+
Astra DB 需要 Secure Connect Bundle 进行 TLS 连接。从 Astra 控制面板下载 bundle 并在 SSL/TLS 部分配置。
92+
</Note>
93+
94+
### 远程服务器
95+
96+
```text
97+
Name: Production Cassandra
98+
Host: cassandra.example.com
99+
Port: 9042
100+
Username: app_user
101+
Password: （安全密码）
102+
Keyspace: production
103+
```
104+
105+
<Warning>
106+
对于生产环境的 Cassandra 集群，建议使用 [SSH tunneling](/zh/databases/ssh-tunneling) 进行安全连接。
107+
</Warning>
108+
109+
## SSL/TLS 连接
110+
111+
在连接表单的 **SSL/TLS** 部分配置 SSL。
112+
113+
| SSL 模式 | 描述 |
114+
|----------|-------------|
115+
| **Disabled** | 不使用 SSL 加密 |
116+
| **Required** | 要求 SSL 加密 |
117+
| **Verify CA** | 要求 SSL 并验证服务器证书是否由 CA 签发 |
118+
119+
对于 **Verify CA** 模式，需要提供 CA 证书文件路径。也可以提供可选的客户端证书和密钥文件以实现 mutual TLS。
120+
121+
<Note>
122+
如果不想配置 SSL 证书，[SSH tunneling](/zh/databases/ssh-tunneling) 可以通过 SSH tunnel 加密所有流量。
123+
</Note>
124+
125+
## SSH Tunnel 支持
126+
127+
通过 SSH tunnel 连接 Cassandra 以安全访问远程集群。设置方法请参阅 [SSH Tunneling](/zh/databases/ssh-tunneling)。
128+
129+
## 功能
130+
131+
### Keyspace 浏览
132+
133+
连接后，侧栏会列出所有 keyspace。展开 keyspace 可以查看其表、物化视图、用户自定义类型（UDT）和二级索引。
134+
135+
1. 点击侧栏中的连接名称
136+
2. 展开 keyspace 查看其对象
137+
3. 点击表查看数据
138+
139+
### 表结构
140+
141+
查看任意表的完整 schema：
142+
143+
- **列**：名称、CQL 类型、聚簇排序
144+
- **分区键**：决定数据分布的列
145+
- **聚簇列**：决定分区内行排序的列
146+
- **二级索引**：索引名称、目标列、索引类
147+
- **表选项**：压缩策略、压缩方式、TTL 默认值、gc_grace_seconds
148+
149+
### 物化视图
150+
151+
在侧栏中可以与表一起浏览物化视图。查看视图定义、基表和列映射。
152+
153+
### 数据网格
154+
155+
带分页的表数据浏览。单元格值以 CQL 类型感知的格式显示：
156+
157+
- **text/varchar** 值显示为纯文本
158+
- **int/bigint/varint** 显示为数字
159+
- **uuid/timeuuid** 显示为格式化的 UUID
160+
- **timestamp** 值以可配置的日期格式显示
161+
- **map/set/list/tuple** 显示为格式化的集合
162+
- **blob** 值显示为十六进制
163+
164+
### CQL 编辑器
165+
166+
在编辑器标签页中直接执行 CQL 语句：
167+
168+
```sql
169+
-- 使用分区键限制查询
170+
SELECT * FROM users WHERE user_id = 123e4567-e89b-12d3-a456-426614174000;
171+
172+
-- 插入数据
173+
INSERT INTO users (user_id, name, email, created_at)
174+
VALUES (uuid(), 'Alice', 'alice@example.com', toTimestamp(now()));
175+
176+
-- 带 TTL 的更新
177+
UPDATE users USING TTL 86400
178+
SET email = 'new@example.com'
179+
WHERE user_id = 123e4567-e89b-12d3-a456-426614174000;
180+
181+
-- 删除
182+
DELETE FROM users WHERE user_id = 123e4567-e89b-12d3-a456-426614174000;
183+
184+
-- 创建表
185+
CREATE TABLE IF NOT EXISTS events (
186+
event_id timeuuid,
187+
user_id uuid,
188+
event_type text,
189+
payload text,
190+
PRIMARY KEY ((user_id), event_id)
191+
) WITH CLUSTERING ORDER BY (event_id DESC);
192+
193+
-- 创建索引
194+
CREATE INDEX ON users (email);
195+
196+
-- 描述表
197+
DESCRIBE TABLE users;
198+
```
199+
200+
## CQL 特殊说明
201+
202+
Cassandra Query Language (CQL) 看起来像 SQL，但有重要区别：
203+
204+
### 不支持 JOIN
205+
CQL 不支持 JOIN 操作。请围绕查询模式设计数据模型，按需在多个表中反规范化数据。
206+
207+
### 不支持子查询
208+
209+
CQL 不支持子查询。将复杂查询拆分为多条顺序执行的语句。
210+
211+
### 分区键限制
212+
213+
每个 SELECT 查询的 WHERE 子句中必须包含完整的分区键，除非使用 `ALLOW FILTERING`（这会扫描整个集群，在生产环境中应避免使用）。
214+
215+
```sql
216+
-- 正确：包含分区键
217+
SELECT * FROM orders WHERE customer_id = 42;
218+
219+
-- 错误：缺少分区键，需要 ALLOW FILTERING
220+
SELECT * FROM orders WHERE total > 100 ALLOW FILTERING;
221+
```
222+
223+
### ALLOW FILTERING
224+
225+
`ALLOW FILTERING` 子句会强制执行全集群扫描。它适用于开发和小型数据集，但在生产集群上会导致超时和性能问题。当查询包含 `ALLOW FILTERING` 时，TablePro 会显示警告。
226+
227+
### 轻量级事务
228+
229+
Cassandra 支持使用 `IF` 子句的条件写入（轻量级事务 / compare-and-set）：
230+
231+
```sql
232+
INSERT INTO users (user_id, email) VALUES (uuid(), 'alice@example.com') IF NOT EXISTS;
233+
UPDATE users SET email = 'new@example.com' WHERE user_id = ? IF email = 'old@example.com';
234+
```
235+
236+
### TTL 和 Writetime
237+
238+
设置每行或每列的 TTL（生存时间），单位为秒：
239+
240+
```sql
241+
INSERT INTO cache (key, value) VALUES ('k1', 'v1') USING TTL 3600;
242+
SELECT TTL(value), WRITETIME(value) FROM cache WHERE key = 'k1';
243+
```
244+
245+
## 故障排除
246+
247+
### 连接被拒绝
248+
249+
**症状**："Connection refused" 或超时
250+
251+
**原因及解决方案**：
252+
253+
1. **Cassandra 未运行**
254+
```bash
255+
# 检查 Cassandra 是否运行
256+
nodetool status
257+
258+
# 启动 Cassandra（macOS Homebrew）
259+
brew services start cassandra
260+
261+
# 启动 Cassandra（Docker）
262+
docker run -d -p 9042:9042 cassandra:latest
263+
```
264+
265+
2. **端口错误**
266+
- 检查 `cassandra.yaml` 中的 `native_transport_port`
267+
- 默认 CQL 端口是 `9042`，不是 `9160`（Thrift，已废弃）
268+
269+
3. **Cassandra 未监听预期地址**
270+
- 检查 `cassandra.yaml` 中的 `rpc_address` 和 `listen_address`
271+
- 对于远程连接，将 `rpc_address` 设为 `0.0.0.0`
272+
273+
### 认证失败
274+
275+
**症状**："Provided username and/or password are incorrect"
276+
277+
**解决方案**：
278+
279+
1. 验证凭据是否匹配 Cassandra 中配置的角色
280+
2. 检查认证是否已启用：
281+
```yaml
282+
# cassandra.yaml
283+
authenticator: PasswordAuthenticator
284+
```
285+
3. 默认超级用户为 `cassandra` / `cassandra`（生产环境中请更改）
286+
287+
### 连接超时
288+
289+
**症状**：连接挂起或超时
290+
291+
**解决方案**：
292+
293+
1. 验证 host 和 port 是否正确
294+
2. 检查网络连通性和防火墙规则（端口 9042）
295+
3. 对于云托管的 Cassandra，确保你的 IP 已加入白名单
296+
4. 在 Advanced 标签页中增加连接超时时间
297+
298+
### 读取超时
299+
300+
**症状**："Read timed out"
301+
302+
**解决方案**：
303+
304+
1. 在 WHERE 子句中添加完整的分区键
305+
2. 移除 `ALLOW FILTERING` 并重新设计查询
306+
3. 使用 `nodetool status` 检查集群健康状况
307+
4. 使用 `LIMIT` 限制结果集大小
308+
309+
## 已知限制
310+
311+
- **多数据中心**：尚不支持连接到特定数据中心。TablePro 连接到 contact point 解析到的节点。
312+
- **User-Defined Functions (UDFs)**：UDF 和 UDA 不会显示在侧栏中，但可以在 CQL 查询中使用。
313+
- **BATCH 语句**：在 CQL 编辑器中支持，但不会由变更跟踪系统生成。
314+
- **Counter 表**：counter 列在数据网格中为只读。使用 CQL 编辑器更新 counter。
315+
- **大分区**：包含数百万行的分区会自动分页以防止内存问题。
316+
317+
## 性能建议
318+
319+
### 查询性能
320+
321+
对于大数据集的 Cassandra 集群：
322+
323+
1. 始终在 WHERE 子句中包含分区键
324+
2. 在生产环境中避免使用 `ALLOW FILTERING`
325+
3. 使用 `LIMIT` 限制结果集大小
326+
4. 使用 `TOKEN()` 进行跨分区的范围扫描
327+
328+
### 监控
329+
330+
检查集群健康状况和性能：
331+
332+
```sql
333+
-- 检查集群状态（通过 nodetool，非 CQL）
334+
-- nodetool status
335+
-- nodetool info
336+
337+
-- 检查表统计信息
338+
SELECT * FROM system.size_estimates WHERE keyspace_name = 'my_keyspace';
339+
```
340+
341+
## 后续步骤
342+
343+
<CardGroup cols={2}>
344+
<Card title="SSH Tunneling" icon="lock" href="/zh/databases/ssh-tunneling">
345+
安全连接远程 Cassandra 集群
346+
</Card>
347+
<Card title="SQL 编辑器" icon="code" href="/zh/features/sql-editor">
348+
掌握查询编辑器功能
349+
</Card>
350+
<Card title="导入/导出" icon="file-import" href="/zh/features/import-export">
351+
导入和导出 Cassandra 数据
352+
</Card>
353+
<Card title="数据网格" icon="table" href="/zh/features/data-grid">
354+
在数据网格中浏览和编辑数据
355+
</Card>
356+
</CardGroup>

‎docs/zh/databases/connection-urls.mdx‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ TablePro 解析标准的数据库连接 URL，用于导入连接、从浏览器
2525
| `sqlserver://` | Microsoft SQL Server（别名） |
2626
| `oracle://` | Oracle Database |
2727
| `jdbc:oracle:thin:@//` | Oracle Database（JDBC thin） |
28+
| `cassandra://` | Cassandra |
29+
| `scylladb://` | ScyllaDB |
2830

2931
在任意 scheme 后追加 `+ssh`（SQLite 除外）即可使用 SSH tunnel：
3032

@@ -164,6 +166,16 @@ redis://:password@host:6379/2 # 数据库索引 2
164166
rediss://:password@host:6380 # TLS，默认索引 0
165167
```
166168

169+
### Cassandra / ScyllaDB
170+
171+
路径部分设置默认 keyspace。`cassandra://` 和 `scylladb://` 使用相同的格式。
172+
173+
```text
174+
cassandra://user:pass@host:9042/my_keyspace
175+
scylladb://user:pass@host:9042/my_keyspace
176+
cassandra://host:9042 # 无认证，无默认 keyspace
177+
```
178+
167179
### SSH Tunnel
168180

169181
| 参数 | 描述 |

0 commit comments

Comments
 (0)