docs: add Chinese (zh) translation#275
Conversation
|
All contributors have signed the CLA ✍️ ✅ |
📝 WalkthroughWalkthroughAdded a full Chinese (zh) locale to the docs site: navigation entry and 60+ new MDX pages covering API, databases, features, customization, development, installation, quickstart, and changelog. No code or public API changes; purely localized documentation content and navigation updates. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
|
I have read the CLA Document and I hereby sign the CLA. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 11
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
🟡 Minor comments (31)
docs/zh/features/data-grid.mdx-338-338 (1)
338-338:⚠️ Potential issue | 🟡 MinorKeep the cross-links inside
/zh/.These links still point to the default-locale docs, so readers get bounced out of the Chinese doc tree from this page.
🔗 Proposed fix
-详情参见[变更追踪](/features/change-tracking)。 +详情参见[变更追踪](/zh/features/change-tracking)。 -在提交到数据库前查看所有修改。详情参见[变更追踪](/features/change-tracking)。 +在提交到数据库前查看所有修改。详情参见[变更追踪](/zh/features/change-tracking)。 -安全模式设为只读的连接以及复杂查询结果不可编辑。在这些情况下，单元格检查器中的编辑功能被禁用。详情参见[安全模式](/features/safe-mode)。 +安全模式设为只读的连接以及复杂查询结果不可编辑。在这些情况下，单元格检查器中的编辑功能被禁用。详情参见[安全模式](/zh/features/safe-mode)。 -详情参见[导入与导出](/features/import-export)。 +详情参见[导入与导出](/zh/features/import-export)。 - <Card title="SQL 编辑器" icon="code" href="/features/sql-editor"> + <Card title="SQL 编辑器" icon="code" href="/zh/features/sql-editor"> - <Card title="导入与导出" icon="file-import" href="/features/import-export"> + <Card title="导入与导出" icon="file-import" href="/zh/features/import-export"> - <Card title="表结构" icon="table-columns" href="/features/table-structure"> + <Card title="表结构" icon="table-columns" href="/zh/features/table-structure"> - <Card title="设置" icon="gear" href="/customization/settings"> + <Card title="设置" icon="gear" href="/zh/customization/settings">Also applies to: 370-370, 417-417, 692-692, 715-725
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/features/data-grid.mdx` at line 338, The Chinese page uses cross-links that point to the default-locale paths (e.g., "/features/change-tracking") and should instead use the Chinese equivalents under "/zh/"; update all occurrences in docs/zh/features/data-grid.mdx (including the instances at the noted lines) to use the "/zh/..." versions (for example change "/features/change-tracking" to "/zh/features/change-tracking") so internal navigation stays within the Chinese doc tree.docs/zh/databases/clickhouse.mdx-71-78 (1)
71-78:⚠️ Potential issue | 🟡 MinorLabel the connection preset blocks.
These fenced blocks are unlabeled. Adding
textkeeps the presets consistent with the rest of the docs and restores code-block styling.🛠️ Proposed fix
-``` +```text Name: Local ClickHouse Host: localhost Port: 8123 Username: default Password: （留空） Database: defaultApply the same change to the other preset blocks in this file. </details> As per coding guidelines, Include language identifiers in fenced code blocks. Also applies to: 96-103, 107-114, 122-129 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/zh/databases/clickhouse.mdxaround lines 71 - 78, The fenced preset
connection blocks in docs/zh/databases/clickhouse.mdx (e.g., the blocks starting
with "Name: Local ClickHouse ... Database: default" and the other similar
presets at the ranges mentioned) are missing language identifiers; update each
triple-backtick fence to use "text" (i.e., changetotext) for the blocks
shown (the blocks containing the lines "Name: Local ClickHouse ...", and the
other preset blocks at the indicated ranges 96-103, 107-114, 122-129) so they
render consistently and get proper code-block styling.</details> </blockquote></details> <details> <summary>docs/zh/databases/mssql.mdx-55-62 (1)</summary><blockquote> `55-62`: _⚠️ Potential issue_ | _🟡 Minor_ **Add language identifiers to the connection presets.** These four fenced blocks are unlabeled. Using `text` is enough here and keeps the page consistent with the rest of the docs. <details> <summary>🛠️ Proposed fix</summary> ```diff -``` +```text Name: Local SQL Server Host: localhost Port: 1433 Username: sa Password: （你的密码） Database: master ``` ``` Apply the same change to the other preset blocks in this file. </details> As per coding guidelines, Include language identifiers in fenced code blocks. Also applies to: 79-86, 94-101, 105-112 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/zh/databases/mssql.mdxaround lines 55 - 62, Add the language
identifier "text" to the unlabeled fenced code blocks that show the SQL Server
connection presets (the blocks containing "Name: Local SQL Server / Host:
localhost / Port: 1433 / Username: sa / Password: （你的密码） / Database: master" and
the three similar presets later in the file) so they becometext fences; update each of the four preset blocks referenced in the comment (the ones around the shown content and the blocks at the other listed locations) to usetext
at the opening fence to match the docs' code block style.</details> </blockquote></details> <details> <summary>docs/zh/databases/clickhouse.mdx-45-51 (1)</summary><blockquote> `45-51`: _⚠️ Potential issue_ | _🟡 Minor_ **Fix the optional-fields table shape.** The header only defines two columns, but `Username` and `Database` include a third default-value cell. That will render inconsistently and hide the intended defaults. <details> <summary>🛠️ Proposed fix</summary> ```diff ### 可选字段 -| 字段 | 描述 | -|-------|-------------| -| **Username** | ClickHouse 用户名 | `default` | -| **Password** | 用户密码（本地安装默认为空） | -| **Database** | 要连接的数据库 | `default` | +| 字段 | 描述 | 默认值 | +|-------|-------------|---------| +| **Username** | ClickHouse 用户名 | `default` | +| **Password** | 用户密码（本地安装默认为空） | - | +| **Database** | 要连接的数据库 | `default` | ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/zh/databases/clickhouse.mdx` around lines 45 - 51, The table under the "### 可选字段" section has only two header columns but three cells in the Username and Database rows; update the table to have three columns by adding a third header (e.g., "默认") and the corresponding separator (|---|---|---|), then ensure each row (the rows containing "Username", "Password", and "Database") has three cells so defaults render correctly; look for the table directly under the "### 可选字段" heading and adjust those rows accordingly. ``` </details> </blockquote></details> <details> <summary>docs/zh/features/filtering.mdx-445-457 (1)</summary><blockquote> `445-457`: _⚠️ Potential issue_ | _🟡 Minor_ **Point the related cards at the Chinese pages.** These `href`s still target the default locale instead of the translated pages. <details> <summary>🔗 Proposed fix</summary> ```diff - <Card title="数据网格" icon="table" href="/features/data-grid"> + <Card title="数据网格" icon="table" href="/zh/features/data-grid"> - <Card title="SQL 编辑器" icon="code" href="/features/sql-editor"> + <Card title="SQL 编辑器" icon="code" href="/zh/features/sql-editor"> - <Card title="导入与导出" icon="file-import" href="/features/import-export"> + <Card title="导入与导出" icon="file-import" href="/zh/features/import-export"> - <Card title="设置" icon="gear" href="/customization/settings"> + <Card title="设置" icon="gear" href="/zh/customization/settings"> ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/zh/features/filtering.mdx` around lines 445 - 457, The Card components inside CardGroup are linking to default-locale pages via the href props; update each Card's href to point to the Chinese translations (e.g., change "/features/data-grid", "/features/sql-editor", "/features/import-export", "/customization/settings" to their Chinese route equivalents under the zh locale) by editing the href values on the Card components so they point to the translated pages; ensure you update the Card instances for "数据网格", "SQL 编辑器", "导入与导出", and "设置" accordingly. ``` </details> </blockquote></details> <details> <summary>docs/zh/features/import-export.mdx-286-292 (1)</summary><blockquote> `286-292`: _⚠️ Potential issue_ | _🟡 Minor_ **Don't present `pg_dump` as SQL.** `SHOW CREATE TABLE` is a SQL statement, but `pg_dump -s -t users database_name` is a shell command. Keeping both inside a `sql` fence implies the PostgreSQL example runs in TablePro's SQL editor. <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/zh/features/import-export.mdxaround lines 286 - 292, The PostgreSQL
examplepg_dump -s -t users database_nameis shown inside a SQL code fence
alongside the SQL statementSHOW CREATE TABLE users;, which implies it runs in
the SQL editor; update the markdown to separate them by using an appropriate
shell/bash code fence (or add an inline note) soSHOW CREATE TABLE users;
remains in asql block and `pg_dump -s -t users database_name` is moved into abash (or ```sh) block or clearly marked as a shell command.</details> </blockquote></details> <details> <summary>docs/zh/features/safe-mode.mdx-84-90 (1)</summary><blockquote> `84-90`: _⚠️ Potential issue_ | _🟡 Minor_ **Keep the related links inside the Chinese docs tree.** These two cards currently route to the default-language pages. <details> <summary>🔗 Proposed fix</summary> ```diff - <Card title="变更追踪" icon="arrows-rotate" href="/features/change-tracking"> + <Card title="变更追踪" icon="arrows-rotate" href="/zh/features/change-tracking"> 编辑如何被追踪和提交 </Card> - <Card title="表操作" icon="table" href="/features/table-operations"> + <Card title="表操作" icon="table" href="/zh/features/table-operations"> 清空、删除和其他表级操作 </Card> ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/zh/features/safe-mode.mdx` around lines 84 - 90, The two Card components (Card title="变更追踪" and Card title="表操作" inside CardGroup) point to default-language routes; update their href props to the Chinese docs tree (e.g. change "/features/change-tracking" to "/zh/features/change-tracking" and "/features/table-operations" to "/zh/features/table-operations" or to the correct localized paths) so the links remain inside the Chinese docs tree. ``` </details> </blockquote></details> <details> <summary>docs/zh/databases/duckdb.mdx-94-100 (1)</summary><blockquote> `94-100`: _⚠️ Potential issue_ | _🟡 Minor_ **Fix the related-page route.** `/zh/features/query-editor` does not match the zh feature routes used elsewhere in this PR, so this card likely lands on a missing page. The rest of the docs point to `/zh/features/sql-editor`. <details> <summary>🔗 Proposed fix</summary> ```diff - <Card title="查询编辑器" icon="code" href="/zh/features/query-editor"> + <Card title="查询编辑器" icon="code" href="/zh/features/sql-editor"> 编写和执行 SQL 查询 </Card> ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/zh/databases/duckdb.mdx` around lines 94 - 100, The Card in the CardGroup uses an incorrect href for the query editor; update the Card with title "查询编辑器" (the Card component instance referencing href="/zh/features/query-editor") to use the correct route href="/zh/features/sql-editor" so it matches the rest of the zh feature routes. ``` </details> </blockquote></details> <details> <summary>docs/zh/features/ai-chat.mdx-342-354 (1)</summary><blockquote> `342-354`: _⚠️ Potential issue_ | _🟡 Minor_ **Use localized targets in the related-pages cards.** These four links currently jump from the Chinese page into the default docs tree. <details> <summary>🔗 Proposed fix</summary> ```diff - <Card title="SQL 编辑器" icon="code" href="/features/sql-editor"> + <Card title="SQL 编辑器" icon="code" href="/zh/features/sql-editor"> 编写和执行 SQL 查询 </Card> - <Card title="设置" icon="gear" href="/customization/settings"> + <Card title="设置" icon="gear" href="/zh/customization/settings"> 配置所有 TablePro 设置 </Card> - <Card title="键盘快捷键" icon="keyboard" href="/features/keyboard-shortcuts"> + <Card title="键盘快捷键" icon="keyboard" href="/zh/features/keyboard-shortcuts"> 所有键盘快捷键 </Card> - <Card title="查询历史" icon="clock-rotate-left" href="/features/query-history"> + <Card title="查询历史" icon="clock-rotate-left" href="/zh/features/query-history"> 浏览历史查询 </Card> ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/zh/features/ai-chat.mdx` around lines 342 - 354, The related-page Card components (CardGroup / Card) use non-localized hrefs that navigate from the Chinese page into the default docs tree; update each Card's href to point to the localized Chinese routes (e.g., change "/features/sql-editor", "/customization/settings", "/features/keyboard-shortcuts", "/features/query-history" to their Chinese equivalents or to a locale-aware helper) so Card components render localized targets and keep users on the Chinese docs tree. ``` </details> </blockquote></details> <details> <summary>docs/zh/features/import-export.mdx-524-536 (1)</summary><blockquote> `524-536`: _⚠️ Potential issue_ | _🟡 Minor_ **Prefix the related links with `/zh/`.** These cards currently send readers back to the default docs tree instead of the Chinese translation. <details> <summary>🔗 Proposed fix</summary> ```diff - <Card title="数据网格" icon="table" href="/features/data-grid"> + <Card title="数据网格" icon="table" href="/zh/features/data-grid"> 导出前查看数据 </Card> - <Card title="SQL 编辑器" icon="code" href="/features/sql-editor"> + <Card title="SQL 编辑器" icon="code" href="/zh/features/sql-editor"> 用查询筛选数据 </Card> - <Card title="表结构" icon="table-columns" href="/features/table-structure"> + <Card title="表结构" icon="table-columns" href="/zh/features/table-structure"> 导出 schema DDL </Card> - <Card title="查询历史" icon="clock-rotate-left" href="/features/query-history"> + <Card title="查询历史" icon="clock-rotate-left" href="/zh/features/query-history"> 重新运行导入查询 </Card> ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/zh/features/import-export.mdx` around lines 524 - 536, The card links under CardGroup are pointing to the default docs tree; update each Card's href prop (the four Card components with titles "数据网格", "SQL 编辑器", "表结构", "查询历史") to prefix the path with "/zh/" (e.g. change "/features/data-grid" to "/zh/features/data-grid", "/features/sql-editor" to "/zh/features/sql-editor", "/features/table-structure" to "/zh/features/table-structure", and "/features/query-history" to "/zh/features/query-history") so the cards route into the Chinese docs tree. ``` </details> </blockquote></details> <details> <summary>docs/zh/customization/editor-settings.mdx-2-4 (1)</summary><blockquote> `2-4`: _⚠️ Potential issue_ | _🟡 Minor_ **Remove `Vim 模式` from the description or cover it below.** The page never documents Vim mode, so the metadata currently advertises content that readers cannot find. <details> <summary>✏️ One minimal fix</summary> ```diff -description: SQL 编辑器字体、大小、行号、自动换行、缩进和 Vim 模式配置 +description: SQL 编辑器字体、大小、行号、自动换行和缩进配置 ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/zh/customization/editor-settings.mdx` around lines 2 - 4, The frontmatter description currently mentions "Vim 模式" but the page does not document it; either remove "和 Vim 模式" from the description line (the `description: SQL 编辑器字体、大小、行号、自动换行、缩进和 Vim 模式配置` frontmatter) or add a dedicated "Vim 模式" section in this document (editor-settings.mdx) that explains how to enable/configure Vim mode (commands, keybindings, toggles), and then keep the description as-is; update the frontmatter or add the section accordingly so the metadata matches the page content. ``` </details> </blockquote></details> <details> <summary>docs/zh/customization/settings.mdx-437-441 (1)</summary><blockquote> `437-441`: _⚠️ Potential issue_ | _🟡 Minor_ **Label the storage-path block as `text`.** This is the only unlabeled fence on the page, so it stands out from the rest of the docs. As per coding guidelines, "Include language identifiers in fenced code blocks". <details> <summary>📝 Suggested fix</summary> ```diff -``` +```text ~/Library/Preferences/com.TablePro.plist ``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/zh/customization/settings.mdxaround lines 437 - 441, The code fence
containing the storage path string (the block with
~/Library/Preferences/com.TablePro.plist) is unlabeled; update that fenced block
to include the language identifier "text" (i.e., change the opening ``` toguideline "Include language identifiers in fenced code blocks."docs/zh/databases/ssh-tunneling.mdx-151-158 (1)
151-158:⚠️ Potential issue | 🟡 MinorAdd language identifiers to the remaining SSH examples.
Several fenced blocks on this page are still unlabeled. Please tag them—
textis fine for the host/port and URL samples—so Mintlify renders them consistently. As per coding guidelines, "Include language identifiers in fenced code blocks".📝 Example fix
-``` +```text # ~/.ssh/config Host production-jump HostName jump.example.com User deploy Port 22 IdentityFile ~/.ssh/production_keyApply the same change to the other plain fenced examples on this page.
Also applies to: 196-202, 208-214, 220-227, 293-299, 361-363, 369-371
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/databases/ssh-tunneling.mdx` around lines 151 - 158, Several fenced code blocks in docs/zh/databases/ssh-tunneling.mdx are missing language identifiers; update each unlabeled fenced block (for example the SSH config block starting with "# ~/.ssh/config" and the other plain blocks around the indicated snippets) to include a language tag such as text (i.e., change ``` to ```text). Ensure you update all remaining unlabeled blocks mentioned in the comment (near the blocks at the other examples) so Mintlify renders them consistently.docs/zh/installation.mdx-72-78 (1)
72-78:⚠️ Potential issue | 🟡 MinorRemove the dangling
()after Apple 菜单.It reads like a missing icon or link placeholder in the install steps.
✏️ Suggested fix
-1. 点击菜单栏中的 **Apple 菜单** () +1. 点击菜单栏中的 **Apple 菜单**🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/installation.mdx` around lines 72 - 78, In the "查看你的 Mac 架构" section remove the dangling empty parentheses after "Apple 菜单" so the step reads "点击菜单栏中的 **Apple 菜单**" (no `()`); locate the text block under the "查看你的 Mac 架构" header that contains "Apple 菜单 ()" and delete the `()` placeholder to eliminate the orphaned icon/link placeholder.docs/zh/databases/mongodb.mdx-81-88 (1)
81-88:⚠️ Potential issue | 🟡 MinorAdd language identifiers to the connection examples.
These four configuration samples are still plain triple-backtick fences, so Mintlify will render them inconsistently.
textis enough for these key/value blocks. As per coding guidelines, "Include language identifiers in fenced code blocks".📝 Example fix
-``` +```text Name: Local MongoDB Host: localhost Port: 27017 Username: （留空） Password: （留空） Database: myappApply the same fence change to the other three samples in this section.
Also applies to: 92-99, 103-110, 118-125
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/databases/mongodb.mdx` around lines 81 - 88, Update the four plain triple-backtick fenced configuration examples (the block starting with "Name: Local MongoDB" and the other three blocks around lines shown) to include a language identifier "text" after the opening ``` so they become ```text fences; apply the same change to the blocks at the other ranges referenced (the samples beginning at the lines containing the same key/value format) to ensure consistent Mintlify rendering.docs/zh/development/architecture.mdx-192-203 (1)
192-203:⚠️ Potential issue | 🟡 MinorRewrite the DatabaseManager and SSHTunnelManager snippets to match the actual source code.
The code blocks contain multiple inaccuracies beyond missing method bodies:
DatabaseManageruses@Observablewith@MainActor final class, not@MainActor class ObservableObject- Property names don't match:
activeSessions(notsessions),currentSessionId(notactiveSessionId)- Property types don't match:
activeSessionsis[UUID: ConnectionSession], not[DatabaseSession]- The
executeQuerymethod does not exist in the actual source- All methods require bodies (invalid Swift syntax in concrete types)
Replace these snippets with accurate implementations or simplified protocol-style examples that readers can safely reference.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/development/architecture.mdx` around lines 192 - 203, Replace the inaccurate Swift snippets with versions that match the real code: change DatabaseManager to the actual declaration pattern (use `@Observable` and make it a final class) and update property names/types to activeSessions: [UUID: ConnectionSession] and currentSessionId: UUID?; remove the nonexistent executeQuery method and instead include the real public methods with bodies or a simplified protocol-style signature that compiles (e.g., connectToSession(_:), disconnectSession(_:), etc.) using the real types (ConnectionSession, DatabaseConnection) used in the source; do the same for SSHTunnelManager so its class name, property names, types and method signatures/bodies reflect the actual implementation rather than the incorrect examples in the snippet.docs/zh/features/autocomplete.mdx-45-50 (1)
45-50:⚠️ Potential issue | 🟡 MinorThe “手动触发” section doesn't describe a manual action.
“开始输入并稍等片刻” is still the automatic path. Either document the real manual trigger here or merge this subsection into “自动触发”.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/features/autocomplete.mdx` around lines 45 - 50, The “手动触发” section currently describes an automatic flow; either replace its contents with the actual manual trigger steps (e.g., state the explicit user action such as a keyboard shortcut, toolbar/menu command, or context-menu item and give exact steps and expected UI result) and keep the heading “手动触发”, or remove/merge this subsection into the existing “自动触发” section; update the text under the “手动触发” heading to clearly name the trigger (e.g., “按 Ctrl+Space” or “点击编辑器右上角的补全按钮”), example usage, and expected behavior so it is genuinely a manual-trigger doc rather than a wait-for-auto description.docs/zh/features/keyboard-shortcuts.mdx-394-443 (1)
394-443:⚠️ Potential issue | 🟡 MinorAdd a language identifier to the quick-reference fence.
This block is unlabeled, so Mintlify loses consistent rendering/highlighting.
textis probably the right fit here.As per coding guidelines "Include language identifiers in fenced code blocks".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/features/keyboard-shortcuts.mdx` around lines 394 - 443, The fenced quick-reference block in keyboard-shortcuts.mdx is missing a language identifier; update the opening fence from ``` to ```text so Mintlify renders/highlights it consistently (edit the block that starts with the keyboard shortcuts table under the SQL 编辑器 / 数据网格 sections).docs/zh/api/deactivate.mdx-1-4 (1)
1-4:⚠️ Potential issue | 🟡 MinorAdd a localized
descriptionto the frontmatter.This page only sets
titleandopenapi, so its metadata is incomplete relative to the rest of the docs set.As per coding guidelines "Add frontmatter (title, description) to every documentation page".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/api/deactivate.mdx` around lines 1 - 4, The frontmatter for docs/zh/api/deactivate.mdx is missing a localized description field; add a "description" key to the existing frontmatter (alongside title and openapi) with a brief Chinese summary of the page's purpose (e.g., what the POST /v1/license/deactivate endpoint does) so the metadata matches project guidelines requiring title and description on every doc page.docs/zh/api/validate.mdx-1-4 (1)
1-4:⚠️ Potential issue | 🟡 MinorAdd a localized
descriptionto the frontmatter.This page only sets
titleandopenapi, so its metadata is incomplete relative to the rest of the docs set.As per coding guidelines "Add frontmatter (title, description) to every documentation page".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/api/validate.mdx` around lines 1 - 4, The frontmatter in docs/zh/api/validate.mdx is missing a localized description field; update the frontmatter block (which currently contains only title and openapi) to include a zh-CN description key (e.g., description: "..." in Chinese) so the page follows the guideline to include both title and description; ensure the new description is added alongside the existing title and openapi entries in the frontmatter.docs/zh/features/query-history.mdx-90-92 (1)
90-92:⚠️ Potential issue | 🟡 MinorAdd language identifiers to these fenced examples.
Both blocks are unlabeled.
textwould fit the search-input example and the filesystem path.As per coding guidelines "Include language identifiers in fenced code blocks".
Also applies to: 176-178
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/features/query-history.mdx` around lines 90 - 92, The fenced code blocks are missing language identifiers; update the example block containing the text `SELECT users -- 查找包含 "SELECT" 和 "users" 的所有查询` to use a language tag (e.g., ```text) and likewise add an appropriate language identifier to the other unlabeled fenced block referenced around lines 176-178 (e.g., `text` for search input or `text`/`bash` for a filesystem path) so both fenced examples include proper language identifiers.docs/zh/features/table-structure.mdx-143-149 (1)
143-149:⚠️ Potential issue | 🟡 MinorAdd "(MySQL)" qualifier to the SPATIAL index row.
The
SPATIALindex type is MySQL/MariaDB-specific (using R-tree structures). PostGIS uses different access methods—GiST, SP-GiST, or BRIN—but these are not namedSPATIAL INDEX. Modify the row to read| **SPATIAL** | 地理空间数据（MySQL）|to match the existingFULLTEXTscoping pattern, or remove it if TablePro doesn't expose MySQL-specific index types in its interface.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/features/table-structure.mdx` around lines 143 - 149, Update the SPATIAL index row in the markdown table so it is scoped to MySQL like the FULLTEXT row; specifically change the row for the symbol "**SPATIAL**" to read "地理空间数据（MySQL）" (i.e., `| **SPATIAL** | 地理空间数据（MySQL） |`) so the table consistently indicates that SPATIAL is MySQL-specific.docs/zh/features/table-operations.mdx-96-98 (1)
96-98:⚠️ Potential issue | 🟡 MinorQualify the
TRUNCATEnote per database engine.The note states TRUNCATE "resets the auto-increment counter" as a universal behavior, but this is only true for MySQL and MariaDB. PostgreSQL's default
TRUNCATEdoes not reset sequences—it requiresTRUNCATE ... RESTART IDENTITYto do so. SQLite does not supportTRUNCATEat all. Since the file documents all three engines in tabs above this note, the statement should be scoped to the engines where it applies.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/features/table-operations.mdx` around lines 96 - 98, Update the Note about TRUNCATE to scope its behavior by engine: state that TRUNCATE is faster than DELETE FROM table and resets the auto-increment counter for MySQL and MariaDB only; add that PostgreSQL’s TRUNCATE does NOT reset sequences unless you use TRUNCATE ... RESTART IDENTITY; and note that SQLite does not support TRUNCATE. Mention the engines by name (MySQL, MariaDB, PostgreSQL, SQLite) so readers of the tabs see the correct behavior for each.docs/zh/api/overview.mdx-30-31 (1)
30-31:⚠️ Potential issue | 🟡 MinorFix the SHA-256 and signature terminology.
Line 31 says the
machine_idhash is “64 位十六进制字符”, but a SHA-256 digest is 64 hex characters / 256 bits. Lines 50-59 also describe RSA-SHA256 as an encryption step, which is inaccurate here and makes the verification flow harder to follow.Suggested wording
@@ -| `machine_id` | `string` | 设备标识符的 SHA-256 哈希值（64 位十六进制字符） | +| `machine_id` | `string` | 设备标识符的 SHA-256 哈希值（64 个十六进制字符） | @@ -`signature` 字段是 `data` 对象的 RSA-SHA256 加密签名。可在客户端使用公钥验证以确保响应完整性。 +`signature` 字段是 `data` 对象的 RSA-SHA256 数字签名。客户端可使用公钥验证其完整性和来源。 @@ -所有成功的激活和验证响应都经过加密签名： +所有成功的激活和验证响应都经过数字签名：Also applies to: 50-59
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/api/overview.mdx` around lines 30 - 31, Update the documentation to correct the SHA-256 and signature terminology: change the `machine_id` description to state it is the SHA-256 digest formatted as "64 hex characters (256 bits)" rather than "64 位十六进制字符" alone, and replace any wording that describes "RSA-SHA256" as an encryption step (in the section around lines 50-59) with clear language that it is an RSA signature algorithm using SHA-256 for hashing—describe the flow as "data is hashed with SHA-256, then signed with RSA (RSA-SHA256), and verification involves checking the RSA signature against the SHA-256 digest" so readers understand signing vs encryption.docs/zh/api/activate.mdx-1-4 (1)
1-4:⚠️ Potential issue | 🟡 MinorAdd a
descriptionto the frontmatter.This page currently defines
titleandopenapi, but notdescription. That breaks the repo-wide metadata convention for docs pages.As per coding guidelines, "Add frontmatter (title, description) to every documentation page."Suggested fix
--- title: 激活许可证 +description: 激活许可证并将其绑定到当前设备 openapi: POST /v1/license/activate ---🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/api/activate.mdx` around lines 1 - 4, The frontmatter for this doc (the YAML block containing title: 激活许可证 and openapi: POST /v1/license/activate) is missing a description field; add a description entry to the top YAML/frontmatter (e.g., description: "短句概述此页面用途") so the file includes both title and description per repo conventions and preserves the existing openapi value.docs/zh/databases/redshift.mdx-48-55 (1)
48-55:⚠️ Potential issue | 🟡 MinorAdd language identifiers to the setup examples.
The cluster and serverless setup snippets are plain fenced blocks right now. Please mark them as
textso they render consistently with the typedsqlexample below.As per coding guidelines, "Include language identifiers in fenced code blocks."
Also applies to: 59-66
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/databases/redshift.mdx` around lines 48 - 55, The two setup examples for the cluster and serverless Redshift snippets use plain fenced code blocks; update each fence (the blocks containing "Name: Production Warehouse" and the subsequent serverless block) to include the language identifier `text` by changing the opening triple backticks to ```text so they render consistently with the `sql` example and follow the fenced-code guideline.docs/zh/databases/redis.mdx-60-66 (1)
60-66:⚠️ Potential issue | 🟡 MinorTag the setup snippets with a language.
These four config examples are still plain fenced blocks. Please mark them as
textso they render consistently with the typedredisandbashexamples later in the page.As per coding guidelines, "Include language identifiers in fenced code blocks."
Also applies to: 70-76, 80-86, 94-100
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/databases/redis.mdx` around lines 60 - 66, Add the language identifier "text" to the fenced code blocks containing the Redis config examples (e.g., the block starting with "Name: Local Redis\nHost: localhost\nPort: 6379\nPassword: （留空）\nDatabase: 0") and the other similar blocks referenced (lines shown as 70-76, 80-86, 94-100) so each triple-backtick fence becomes ```text to match the later `redis` and `bash` examples and satisfy the code block language guideline.docs/zh/databases/connection-urls.mdx-31-35 (1)
31-35:⚠️ Potential issue | 🟡 MinorAdd language identifiers to the fenced URL examples.
Most of the format/example fences here are plain triple-backtick blocks, so Mintlify will render them without syntax highlighting. Please tag these as
textto keep them consistent with the typedbashblock later in the page.As per coding guidelines, "Include language identifiers in fenced code blocks."
Also applies to: 39-41, 45-51, 61-63, 67-71, 92-95, 109-111, 128-131, 142-144, 154-156, 162-165, 175-177, 202-204
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/databases/connection-urls.mdx` around lines 31 - 35, The fenced code blocks that show raw connection URL examples (e.g., the blocks containing "postgresql+ssh://", "mysql+ssh://", "mariadb+ssh://", and the other similar URL/example blocks throughout the file) should use a language identifier so they render consistently; update each triple-backtick fence from ``` to ```text for every plain URL/example block (including the other blocks noted in the review) so Mintlify applies the correct syntax highlighting and adheres to the guideline.docs/docs.json-223-236 (1)
223-236:⚠️ Potential issue | 🟡 MinorRemove the duplicate Oracle page from the Chinese nav.
Line 232 and Line 235 both point to
zh/databases/oracle, so the Chinese sidebar will render Oracle twice.Suggested fix
"zh/databases/redshift", "zh/databases/oracle", "zh/databases/clickhouse", "zh/databases/mssql", - "zh/databases/oracle", "zh/databases/ssh-tunneling"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/docs.json` around lines 223 - 236, The "pages" array contains a duplicate entry 'zh/databases/oracle' which causes the Chinese sidebar to render Oracle twice; edit the "pages" array in docs.json and remove the redundant 'zh/databases/oracle' entry so it only appears once (keep a single occurrence), ensuring the array order remains correct and no other entries are altered.docs/zh/features/deep-links.mdx-10-21 (1)
10-21:⚠️ Potential issue | 🟡 MinorClarify whether the scheme table is exhaustive.
This section says users can open “任意数据库连接”, but the table only lists a subset of schemes. Other zh docs in this PR document additional schemes like
mariadb://,redshift://,oracle://, andclickhouse://, so this page currently reads as if those are unsupported. Either add the missing entries or explicitly label this table as a partial list.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/features/deep-links.mdx` around lines 10 - 21, The "支持的 Scheme" table currently implies completeness but omits schemes like mariadb://, redshift://, oracle://, and clickhouse://; update the table under the "支持的 Scheme" heading by either adding rows for those missing schemes (mariadb://, redshift://, oracle://, clickhouse://, etc.) matching the existing table format or add a clear note (e.g., "部分示例，非完整列表") immediately above or below the table to indicate it is a partial list so readers know other schemes are supported.docs/zh/databases/overview.mdx-128-132 (1)
128-132:⚠️ Potential issue | 🟡 MinorInclude
ClickHousein theTypefield description.This table documents the connection form, but Line 131 omits
ClickHouseeven though the same page lists it as a supported engine and links to the dedicated ClickHouse guide later. That makes the field reference internally inconsistent.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/databases/overview.mdx` around lines 128 - 132, The Type field's description (the table row labeled "**Type**") is missing ClickHouse; update that table entry to include "ClickHouse" in the list of supported database types (MySQL、MariaDB、PostgreSQL、SQLite、MongoDB、Redis、Redshift、SQL Server、Oracle) so it reads something like "数据库类型：MySQL、MariaDB、PostgreSQL、SQLite、MongoDB、Redis、Redshift、SQL Server、Oracle、ClickHouse", keeping the same punctuation and language style as the surrounding text.
🧹 Nitpick comments (7)
docs/zh/databases/sqlite.mdx (1)
75-87: Add an info string to this fenced block.This snippet is currently untyped, so Mintlify cannot render it consistently with the rest of the page.
bashortextwould both work here.As per coding guidelines, "Include language identifiers in fenced code blocks".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/databases/sqlite.mdx` around lines 75 - 87, The fenced code block in docs/zh/databases/sqlite.mdx lacks a language identifier; update the triple-backtick fence to include a language (e.g., ```bash or ```text) so Mintlify can render it consistently—locate the block that lists Ruby on Rails, Django, iOS simulator, and Core Data paths and add the chosen language tag to the opening ``` line.docs/zh/customization/editor-settings.mdx (1)
266-274: Type the preset configuration blocks.All five presets are untyped fenced blocks. Mark them as
textso they render consistently with the rest of the docs.As per coding guidelines, "Include language identifiers in fenced code blocks".
Also applies to: 278-286, 290-298, 302-310, 314-322
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/customization/editor-settings.mdx` around lines 266 - 274, The fenced preset configuration blocks are missing language identifiers; update each of the five fenced code blocks (the blocks that currently start with triple backticks before "Font Family: System Mono" etc.) to use a language identifier of text (i.e., change ``` to ```text) so they render consistently and comply with the "Include language identifiers in fenced code blocks" guideline; apply the same change to the other similar preset blocks referenced in the comment.docs/zh/development/building.mdx (1)
76-79: Add language identifiers to the plain fenced blocks.These output and error snippets are currently untyped.
textis enough here and keeps the MDX rendering consistent.As per coding guidelines, "Include language identifiers in fenced code blocks".
Also applies to: 150-153, 217-219, 227-229, 232-235, 238-240
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/development/building.mdx` around lines 76 - 79, Add the missing language identifier "text" to the fenced code blocks that show build outputs (e.g., the block containing "build/Release/TablePro-arm64.app # Apple Silicon" and "build/Release/TablePro-x86_64.app # Intel") and similarly for the other untyped blocks noted (lines referenced in the comment: 150-153, 217-219, 227-229, 232-235, 238-240); update each triple-backtick fence from ``` to ```text so the MDX renderer treats them as plain text consistently.docs/zh/databases/oracle.mdx (1)
63-70: Add info strings to the connection snippets.These are plain-text configuration examples, but they currently omit a language identifier.
textwould keep the rendering consistent without implying executable syntax.As per coding guidelines, "Include language identifiers in fenced code blocks".
Also applies to: 86-93, 101-108, 112-119
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/databases/oracle.mdx` around lines 63 - 70, Add a language identifier ("text") to the fenced code blocks that show the Oracle connection examples (e.g., the block starting with "Name: Local Oracle XE" and the other similar blocks at the same examples) so they render as plain text rather than unspecified code; update each triple-backtick fence from ``` to ```text for the snippets that contain the Host/Port/Username/Password/Service Name examples.docs/zh/databases/mysql.mdx (1)
71-78: Tag the connection examples astext.All four setup snippets are plain fenced blocks. Adding a language identifier keeps rendering consistent with the rest of the docs.
Suggested fix
-``` +```text Name: Local MySQL Host: localhost Port: 3306 Username: root Password: （你的密码） Database: （留空）</details> Apply the same change to the other config examples in this section. As per coding guidelines, "Include language identifiers in fenced code blocks." Also applies to: 82-89, 93-100, 104-111 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/zh/databases/mysql.mdxaround lines 71 - 78, Add the language
identifier "text" to the fenced code blocks that contain the MySQL connection
examples (the blocks showing "Name: Local MySQL", "Host: localhost",
"Port: 3306", "Username: root", "Password: （你的密码）", "Database: （留空）") and
the other similar config snippets in this section so they become ```text ...the rest of the docs.docs/zh/databases/postgresql.mdx (1)
66-73: Add language identifiers to the untyped fenced blocks.The connection examples and
pg_hba.confsample are plain fences right now. Mark them astextso they render consistently and are easier to scan.Apply the same change to the other untyped blocks in this file. As per coding guidelines, "Include language identifiers in fenced code blocks."Suggested fix
-``` +```text Name: Local PostgreSQL Host: localhost Port: 5432 Username: postgres Password: （你的密码） Database: postgres-
+textTYPE DATABASE USER ADDRESS METHOD
local all all trust
host all all 127.0.0.1/32 md5
host all all ::1/128 md5Also applies to: 77-84, 88-95, 103-110, 116-123, 127-134, 274-279
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/zh/databases/postgresql.mdx` around lines 66 - 73, Update all untyped fenced code blocks in the PostgreSQL doc to include the language identifier "text": replace the opening fences ``` with ```text for the example block that starts "Name: Local PostgreSQL" and for the pg_hba.conf block that starts "# TYPE DATABASE USER ADDRESS METHOD", and make the same change for the other untyped blocks referenced (around the blocks at the ranges containing those samples: 77-84, 88-95, 103-110, 116-123, 127-134, 274-279) so every plain fence becomes ```text.docs/zh/features/deep-links.mdx (1)
25-27: Add language identifiers to the URL template blocks.These fenced blocks are untyped, so they lose consistent Mintlify rendering and syntax highlighting.
textfits these URL patterns well.Suggested fix
-``` +```text scheme://[username[:password]@]host[:port][/database][?param=value]-
+text
tablepro://connect/{name}-``` +```text tablepro://connect/{name}/table/{table} tablepro://connect/{name}/database/{db}/table/{table}-
+text
tablepro://connect/{name}/query?sql={encoded_sql}-``` +```text tablepro://import?name={n}&host={h}&port={p}&type={t}&username={u}&database={db}</details> As per coding guidelines, "Include language identifiers in fenced code blocks." Also applies to: 88-90, 100-103, 114-116, 126-128 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/zh/features/deep-links.mdxaround lines 25 - 27, The fenced code blocks
containing URL templates (e.g., the blocks with
"scheme://[username[:password]@]host[:port][/database][?param=value]",
"tablepro://connect/{name}", "tablepro://connect/{name}/table/{table}",
"tablepro://connect/{name}/query?sql={encoded_sql}", and the import URL
"tablepro://import?name={n}&host={h}&port={p}&type={t}&username={u}&database={db}")
should include a language identifier to enable consistent Mintlify rendering;
update each triple-backtick fence to start with ```text (for all occurrences
mentioned, including the other blocks at the noted locations) so the URL
templates aretext-highlighted.</details> </blockquote></details> </blockquote></details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: defaults **Review profile**: CHILL **Plan**: Pro **Run ID**: `a6a22b0e-4c1d-4d13-81c5-8bc15a7f7a2a` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 73667122aec8f78ef109d4e241ceed2216175941 and e64d83861f2a90d4d1d6b595977f76d1addbecb9. </details> <details> <summary>📒 Files selected for processing (44)</summary> * `docs/docs.json` * `docs/zh/api/activate.mdx` * `docs/zh/api/deactivate.mdx` * `docs/zh/api/overview.mdx` * `docs/zh/api/validate.mdx` * `docs/zh/changelog.mdx` * `docs/zh/customization/appearance.mdx` * `docs/zh/customization/editor-settings.mdx` * `docs/zh/customization/settings.mdx` * `docs/zh/databases/clickhouse.mdx` * `docs/zh/databases/connection-urls.mdx` * `docs/zh/databases/duckdb.mdx` * `docs/zh/databases/mongodb.mdx` * `docs/zh/databases/mssql.mdx` * `docs/zh/databases/mysql.mdx` * `docs/zh/databases/oracle.mdx` * `docs/zh/databases/overview.mdx` * `docs/zh/databases/postgresql.mdx` * `docs/zh/databases/redis.mdx` * `docs/zh/databases/redshift.mdx` * `docs/zh/databases/sqlite.mdx` * `docs/zh/databases/ssh-tunneling.mdx` * `docs/zh/development/architecture.mdx` * `docs/zh/development/building.mdx` * `docs/zh/development/code-style.mdx` * `docs/zh/development/plugin-registry.mdx` * `docs/zh/development/setup.mdx` * `docs/zh/features/ai-chat.mdx` * `docs/zh/features/autocomplete.mdx` * `docs/zh/features/change-tracking.mdx` * `docs/zh/features/data-grid.mdx` * `docs/zh/features/deep-links.mdx` * `docs/zh/features/filtering.mdx` * `docs/zh/features/import-export.mdx` * `docs/zh/features/keyboard-shortcuts.mdx` * `docs/zh/features/query-history.mdx` * `docs/zh/features/safe-mode.mdx` * `docs/zh/features/sql-editor.mdx` * `docs/zh/features/table-operations.mdx` * `docs/zh/features/table-structure.mdx` * `docs/zh/features/tabs.mdx` * `docs/zh/index.mdx` * `docs/zh/installation.mdx` * `docs/zh/quickstart.mdx` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
| ### Oracle Cloud（Autonomous Database） | ||
|
|
||
| ``` | ||
| Name: Oracle Cloud ADB | ||
| Host: adb.region.oraclecloud.com | ||
| Port: 1522 | ||
| Username: ADMIN | ||
| Password: （你的密码） | ||
| Service Name: mydb_tp | ||
| ``` | ||
|
|
||
| <Note> | ||
| Oracle Autonomous Database 默认使用 1522 端口并要求 TLS。从 Oracle Cloud Console 下载 wallet 用于 mTLS 连接。 | ||
| </Note> |
There was a problem hiding this comment.
Clarify the Autonomous Database guidance.
This section reads like a supported setup, but later the page says wallet-based authentication is not supported. As written, readers are sent into an ADB flow that TablePro cannot complete. Either mark Autonomous Database unsupported here, or document only the supported non-wallet path.
Also applies to: 214-215, 283-285
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/zh/databases/oracle.mdx` around lines 110 - 123, The "Oracle
Cloud（Autonomous Database）" section currently instructs readers to use the
wallet/TLS flow but the product does not support wallet-based authentication;
update the text under the "Oracle Cloud（Autonomous Database）" heading (and the
similar guidance currently echoed later in the doc) to either (A) explicitly
mark Autonomous Database/wallet-based (mTLS) connections as unsupported by
TablePro, or (B) replace the wallet instructions with the supported connection
path only (e.g., simple TCP/port 1522 with username/password or service name)
and remove or reword the Note that instructs downloading the wallet; ensure the
change references the "Oracle Cloud（Autonomous Database）" heading and the Note
block so reviewers can find and adjust all occurrences.
| ## CI/CD | ||
|
|
||
| ### GitHub Actions | ||
|
|
||
| CI 工作流示例： | ||
|
|
||
| ```yaml | ||
| name: Build | ||
|
|
||
| on: | ||
| push: | ||
| branches: [main] | ||
| pull_request: | ||
| branches: [main] | ||
|
|
||
| jobs: | ||
| build: | ||
| runs-on: macos-latest | ||
| steps: | ||
| - uses: actions/checkout@v4 | ||
|
|
||
| - name: Select Xcode | ||
| run: sudo xcode-select -s /Applications/Xcode_15.0.app | ||
|
|
||
| - name: Build | ||
| run: | | ||
| xcodebuild -project TablePro.xcodeproj \ | ||
| -scheme TablePro \ | ||
| -configuration Debug \ | ||
| build \ | ||
| -skipPackagePluginValidation | ||
|
|
||
| - name: Test | ||
| run: | | ||
| xcodebuild -project TablePro.xcodeproj \ | ||
| -scheme TablePro \ | ||
| test \ | ||
| -skipPackagePluginValidation | ||
| ``` | ||
|
|
||
| ### 发布工作流 | ||
|
|
||
| ```yaml | ||
| release: | ||
| runs-on: macos-latest | ||
| steps: | ||
| - uses: actions/checkout@v4 | ||
|
|
||
| - name: Build Release (arm64) | ||
| run: scripts/build-release.sh arm64 | ||
|
|
||
| - name: Build Release (x86_64) | ||
| run: scripts/build-release.sh x86_64 | ||
|
|
||
| - name: Create DMGs | ||
| run: | | ||
| scripts/create-dmg.sh arm64 | ||
| scripts/create-dmg.sh x86_64 | ||
|
|
||
| - name: Upload Artifacts | ||
| uses: actions/upload-artifact@v3 | ||
| with: | ||
| name: release-dmgs | ||
| path: build/Release/*.dmg | ||
| ``` |
There was a problem hiding this comment.
Align this CI/CD section with the repo’s actual release pipeline.
If this page is meant to document TablePro’s real workflow, the examples are materially out of sync: they show push/PR builds and a simple DMG upload job, but omit the tag trigger, lint stage, split arch builds, packaged ZIP/DMG release flow, Sparkle signing, and CHANGELOG-based release notes. Either document the real pipeline here or explicitly label these as simplified examples.
Based on learnings, ".github/workflows/build.yml: GitHub Actions CI/CD triggered by v* tags runs: lint → build arm64 → build x86_64 → release (DMG/ZIP + Sparkle signatures). Release notes auto-extracted from CHANGELOG.md".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/zh/development/building.mdx` around lines 264 - 328, The CI/CD examples
in the "Build" and "release" workflow blocks are out of sync with the repo;
update this section to either mark these snippets explicitly as simplified
examples or replace them with the real pipeline steps from
.github/workflows/build.yml: add the tag trigger (v*), include the lint stage,
show the split-arch build flow (arm64/x86_64 using scripts/build-release.sh),
packaging artifacts (DMG/ZIP via scripts/create-dmg.sh), Sparkle signing step,
artifact upload (actions/upload-artifact@v3) and automatic release-notes
extraction from CHANGELOG.md so the docs reflect the actual release flow and
unique scripts referenced.
|
|
||
| # 查询标签页 | ||
|
|
||
| 每个标签页都是一个独立的工作区，拥有自己的 SQL 内容、查询结果、分页、排序和筛选状态。你可以同时打开任意多个标签页。它们在应用重启后依然保留。 |
There was a problem hiding this comment.
The persistence wording overpromises what survives a restart.
Line 8 reads like SQL, results, pagination, sorting, and filtering all come back after relaunch, but the persistence table below says results, pending changes, selection, sorting, and filtering are not saved. Please narrow the claim and call out the large-query persistence limit so users do not expect a full workspace restore.
Based on learnings "Persist tab state as JSON via TabPersistenceService and TabStateStorage; truncate queries >500KB to prevent JSON freeze; skip writes >500KB".
Also applies to: 233-267
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/zh/features/tabs.mdx` at line 8, The sentence overstates what is
restored on restart; update the wording to state that only tab metadata/state is
persisted via TabPersistenceService and TabStateStorage (not full query results
or live workspace state), and explicitly call out the large-query persistence
behavior: queries larger than 500KB are truncated to avoid JSON freeze and
writes >500KB are skipped. Apply this change to the sentence currently
describing persistence and the similar section referenced around lines 233-267,
and mention the 500KB limit and truncation/skipping behavior so users don’t
expect full workspace/result restoration.
|
Hi @shiqkuangsan could you fix those reviews? |
Don't worry, I'll handle it. |
There was a problem hiding this comment.
Actionable comments posted: 8
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/zh/features/autocomplete.mdx`:
- Around line 45-50: The "手动触发" section currently doesn't describe any explicit
manual action; update the section titled "手动触发" to either (A) list the actual
manual entry points (e.g., the keyboard shortcut, command palette command, or UI
button that triggers autocomplete) and show a brief step like "按下 <快捷键> 或在命令面板执行
<命令>" and/or mention platform differences, or (B) if you don't have a manual
trigger to document, rename the heading to something like "自动触发" and adjust the
text to match; edit the "手动触发" heading and its content accordingly so readers
know the exact manual trigger or the heading no longer implies one.
In `@docs/zh/features/change-tracking.mdx`:
- Around line 66-72: Update the "要插入新行：" instruction that currently reads
"点击工具栏中的 **+** 按钮或使用键盘快捷键" to either spell out the exact shortcut keys (e.g.,
the actual key combination) or remove the phrase "或使用键盘快捷键" so the step is
actionable; apply the same change to the other duplicate insert-row block that
also mentions a keyboard shortcut elsewhere in the document.
- Around line 272-274: In the Step component with title "点击提交" update the inline
label 'Commit' to use bold formatting to match other UI labels—change the text
"点击 Commit 按钮或按 `Cmd+S`" to "点击 **Commit** 按钮或按 `Cmd+S`" so the Commit button
label is rendered in bold; leave the `Cmd+S` code span unchanged.
In `@docs/zh/features/data-grid.mdx`:
- Around line 162-167: Replace the awkward phrasing "弹出窗口自动检测关联表中最合适的显示列" with
the clearer wording "弹出窗口自动检测关联表中最适合作为显示文本的列" in the data-grid feature text so
the meaning about which column is chosen for display is unambiguous.
In `@docs/zh/features/filtering.mdx`:
- Around line 180-184: Replace the untyped, placeholder fenced example with a
typed fence and realistic IN-list values: change the fence to include a language
identifier (e.g., use "text" or "sql") and replace "value1, value2, value3" with
concrete values such as "active, pending, archived" so the example matches the
rest of the page and follows the fenced code block guideline.
In `@docs/zh/features/keyboard-shortcuts.mdx`:
- Around line 394-443: The fenced code block in the keyboard-shortcuts page
lacks a language identifier; update the triple-backtick fence around the
shortcut matrix in docs/zh/features/keyboard-shortcuts.mdx (the large shortcuts
block containing sections like "=== SQL 编辑器 ===", "=== 数据网格 ===", etc.) to
include a language tag such as text or plaintext (e.g., ```text) so the MDX
follows the repo convention for fenced code blocks.
In `@docs/zh/features/sql-editor.mdx`:
- Around line 81-96: Update the multi-statement execution doc to clarify that
"all changes roll back" only applies to transactional statements and that DDL
(e.g., DROP TABLE, CREATE TABLE) may cause implicit commits or behave
differently depending on the database (MySQL/Postgres), so rollback is not
guaranteed for DDL; mention that the last SELECT result is shown and each
statement is recorded as before, and make the same wording change in
docs/features/sql-editor.mdx (mirror the Chinese edits in
docs/zh/features/sql-editor.mdx) to note DB- and statement-type-dependent
behavior.
In `@docs/zh/features/table-structure.mdx`:
- Around line 141-149: Update the table row describing spatial indexes: replace
the incorrect MySQL-specific "SPATIAL" wording with PostGIS-appropriate
terminology by changing the row for spatial indexes to mention GiST (常用) and
SP-GiST (适用于点密集型场景) and optionally note that MySQL's SPATIAL is different; edit
the table entry in the "索引类型" section where the row currently reads
`**SPATIAL**` / `地理空间数据（PostGIS）` to instead reference `GiST / SP-GiST` and a
short description like "地理空间索引（PostGIS，常用GiST；点密集型可用SP-GiST）".
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 75edcb83-928f-4b7f-ba19-d4295fc0806e
📒 Files selected for processing (13)
docs/zh/features/ai-chat.mdxdocs/zh/features/autocomplete.mdxdocs/zh/features/change-tracking.mdxdocs/zh/features/data-grid.mdxdocs/zh/features/filtering.mdxdocs/zh/features/import-export.mdxdocs/zh/features/keyboard-shortcuts.mdxdocs/zh/features/query-history.mdxdocs/zh/features/safe-mode.mdxdocs/zh/features/sql-editor.mdxdocs/zh/features/table-operations.mdxdocs/zh/features/table-structure.mdxdocs/zh/features/tabs.mdx
✅ Files skipped from review due to trivial changes (1)
- docs/zh/features/safe-mode.mdx
🚧 Files skipped from review as they are similar to previous changes (4)
- docs/zh/features/table-operations.mdx
- docs/zh/features/query-history.mdx
- docs/zh/features/tabs.mdx
- docs/zh/features/import-export.mdx
| ### 手动触发 | ||
|
|
||
| 手动呼出自动补全弹窗： | ||
|
|
||
| - 开始输入并稍等片刻 | ||
| - 弹窗会显示相关建议 |
There was a problem hiding this comment.
手动触发 这一节现在没有写出“手动”操作。
这几行只是在描述输入后等待建议出现，读者仍然不知道如何显式触发补全。请补上真正的手动入口（快捷键、命令或按钮），或者把小节标题改成不暗示“手动触发”的表述。
🧰 Tools
🪛 LanguageTool
[uncategorized] ~47-~47: 您的意思是“"不"全”？
Context: ...字后（SELECT、FROM、JOIN 等） ### 手动触发 手动呼出自动补全弹窗： - 开始输入并稍等片刻 - 弹窗会显示相关建议 ### 关闭 -...
(BU)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/zh/features/autocomplete.mdx` around lines 45 - 50, The "手动触发" section
currently doesn't describe any explicit manual action; update the section titled
"手动触发" to either (A) list the actual manual entry points (e.g., the keyboard
shortcut, command palette command, or UI button that triggers autocomplete) and
show a brief step like "按下 <快捷键> 或在命令面板执行 <命令>" and/or mention platform
differences, or (B) if you don't have a manual trigger to document, rename the
heading to something like "自动触发" and adjust the text to match; edit the "手动触发"
heading and its content accordingly so readers know the exact manual trigger or
the heading no longer implies one.
| 要插入新行： | ||
|
|
||
| 1. 点击工具栏中的 **+** 按钮或使用键盘快捷键 | ||
| 2. 数据网格底部出现一行新行，标有插入指示器 | ||
| 3. 为每列填入值 | ||
| 4. 有默认值的列会预填 `DEFAULT` | ||
|
|
There was a problem hiding this comment.
Name the insert-row shortcut or remove the mention.
Line 68 says readers can use a keyboard shortcut, but this page never tells them what it is, and the shortcut table below does not list one. Either spell out the keys here or drop the shortcut claim so the instructions stay actionable.
Also applies to: 439-446
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/zh/features/change-tracking.mdx` around lines 66 - 72, Update the
"要插入新行：" instruction that currently reads "点击工具栏中的 **+** 按钮或使用键盘快捷键" to either
spell out the exact shortcut keys (e.g., the actual key combination) or remove
the phrase "或使用键盘快捷键" so the step is actionable; apply the same change to the
other duplicate insert-row block that also mentions a keyboard shortcut
elsewhere in the document.
| <Step title="点击提交"> | ||
| 点击 Commit 按钮或按 `Cmd+S` | ||
| </Step> |
There was a problem hiding this comment.
Format Commit like the other UI labels on this page.
This button name is plain text here, while the surrounding UI labels are bolded. Please make Commit bold for consistency.
As per coding guidelines, "Use bold formatting when referencing UI elements (e.g., Click Settings)".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/zh/features/change-tracking.mdx` around lines 272 - 274, In the Step
component with title "点击提交" update the inline label 'Commit' to use bold
formatting to match other UI labels—change the text "点击 Commit 按钮或按 `Cmd+S`" to
"点击 **Commit** 按钮或按 `Cmd+S`" so the Commit button label is rendered in bold;
leave the `Cmd+S` code span unchanged.
| 编辑外键列时，会弹出一个可搜索的下拉列表，显示来自关联表的有效值： | ||
|
|
||
| - 下拉列表同时显示外键值和描述文本列（例如 `1 — John Doe`） | ||
| - 在搜索框中输入以筛选值 | ||
| - 单击高亮选中；双击或按 `Enter` 确认 | ||
| - 弹出窗口自动检测关联表中最合适的显示列 |
There was a problem hiding this comment.
Clarify the display-column wording.
Line 167 reads a bit awkwardly in Chinese and slightly blurs the meaning. 自动检测关联表中最适合作为显示文本的列 is clearer than 最合适的显示列.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~167-~167: 动词的修饰一般为‘形容词（副词）+地+动词’。您的意思是否是：合适"地"显示
Context: ...单击高亮选中；双击或按 Enter 确认 - 弹出窗口自动检测关联表中最合适的显示列 外键查找最多获取关联表中的 1,000 条值。对于更多记录...
(wb4)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/zh/features/data-grid.mdx` around lines 162 - 167, Replace the awkward
phrasing "弹出窗口自动检测关联表中最合适的显示列" with the clearer wording
"弹出窗口自动检测关联表中最适合作为显示文本的列" in the data-grid feature text so the meaning about
which column is chosen for display is unambiguous.
| 输入逗号分隔的值以匹配列表： | ||
|
|
||
| ``` | ||
| value1, value2, value3 | ||
| ``` |
There was a problem hiding this comment.
Use a typed code fence and a concrete IN-list example.
This is the only fenced example on the page without a language identifier, and value1, value2, value3 reads like placeholder text. Switching to a text or sql fence with realistic values will keep it consistent with the rest of the page.
Suggested edit
-```
-value1, value2, value3
-```
+```text
+active, pending, archived
+```As per coding guidelines, "Include language identifiers in fenced code blocks" and "Show realistic parameter values in code examples, not placeholders like foo or bar."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/zh/features/filtering.mdx` around lines 180 - 184, Replace the untyped,
placeholder fenced example with a typed fence and realistic IN-list values:
change the fence to include a language identifier (e.g., use "text" or "sql")
and replace "value1, value2, value3" with concrete values such as "active,
pending, archived" so the example matches the rest of the page and follows the
fenced code block guideline.
| ``` | ||
| === SQL 编辑器 === | ||
| Cmd+Enter 执行查询 | ||
| Opt+Cmd+E 解释查询 | ||
| Opt+Cmd+F 格式化 SQL | ||
| Cmd+F 查找 | ||
| Cmd+Z 撤销 | ||
| Cmd+Shift+Z 重做 | ||
|
|
||
| === 数据网格 === | ||
| 方向键 导航单元格 | ||
| Enter 编辑单元格 | ||
| Tab 下一个单元格 | ||
| Cmd+C 复制 | ||
| Delete 删除行 | ||
|
|
||
| === 数据变更 === | ||
| Cmd+S 提交更改 | ||
| Cmd+Z 撤销 | ||
| Cmd+Shift+Z 重做 | ||
| Cmd+Shift+P 预览 SQL | ||
|
|
||
| === 标签页 === | ||
| Cmd+T 新建查询标签页 | ||
| Cmd+W 关闭标签页 | ||
| Cmd+1-9 切换到标签页 N | ||
| Cmd+Shift+[ 上一个标签页 | ||
| Cmd+Shift+] 下一个标签页 | ||
|
|
||
| === Vim 模式（启用时） === | ||
| Escape Normal 模式 | ||
| i/a/o 进入 Insert 模式 | ||
| v/V Visual / Visual Line | ||
| h/j/k/l 左/下/上/右 | ||
| w/b/e 单词移动 | ||
| ^/_ 行首非空字符 | ||
| dd/yy/cc 删除/复制/更改行 | ||
| :w 执行查询 | ||
| :q 关闭标签页 | ||
|
|
||
| === 应用程序 === | ||
| Cmd+N 新建连接 | ||
| Cmd+Y 查询历史 | ||
| Cmd+Shift+L 切换 AI 聊天 | ||
| Cmd+L AI 解释 | ||
| Cmd+Opt+L AI 优化 | ||
| Cmd+, 设置 | ||
| Cmd+W 关闭窗口 | ||
| Cmd+Q 退出 | ||
| ``` |
There was a problem hiding this comment.
给速查表代码块补一个语言标识。
这个 fenced block 目前没有语言标识，和仓库的 MDX 约定不一致。这里用 text 或 plaintext 就够了。
🛠️ Suggested fix
-```
+```text
=== SQL 编辑器 ===
Cmd+Enter 执行查询
Opt+Cmd+E 解释查询
Opt+Cmd+F 格式化 SQL
@@
Cmd+, 设置
Cmd+W 关闭窗口
Cmd+Q 退出</details>
As per coding guidelines, "Include language identifiers in fenced code blocks".
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against the current code and only fix it if needed.
In @docs/zh/features/keyboard-shortcuts.mdx around lines 394 - 443, The fenced
code block in the keyboard-shortcuts page lacks a language identifier; update
the triple-backtick fence around the shortcut matrix in
docs/zh/features/keyboard-shortcuts.mdx (the large shortcuts block containing
sections like "=== SQL 编辑器 ===", "=== 数据网格 ===", etc.) to include a language tag
such as text or plaintext (e.g., ```text) so the MDX follows the repo convention
for fenced code blocks.
</details>
<!-- fingerprinting:phantom:poseidon:grasshopper -->
<!-- This is an auto-generated comment by CodeRabbit -->
| 如果选中内容包含**多条语句**（以分号分隔），它们会在一个事务中依次执行： | ||
|
|
||
| - 语句按顺序逐条执行 | ||
| - 如果任一语句失败，执行停止并回滚所有变更 | ||
| - 错误信息会标明是哪条语句失败（例如 "Statement 3/5 failed: ..."） | ||
| - 最后一个 `SELECT` 的结果显示在数据网格中 | ||
| - 每条语句都会单独记录到查询历史 | ||
|
|
||
| 适合运行 SQL 转储文件、数据迁移或一批相关语句： | ||
|
|
||
| ```sql | ||
| DROP TABLE IF EXISTS users; | ||
| CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(100)); | ||
| INSERT INTO users VALUES (1, 'Alice'), (2, 'Bob'); | ||
| SELECT * FROM users; | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
cat -n docs/zh/features/sql-editor.mdx | sed -n '75,105p'Repository: datlechin/TablePro
Length of output: 943
🏁 Script executed:
# Check if English version exists and what it says about this feature
find docs -name "sql-editor.mdx" -type fRepository: datlechin/TablePro
Length of output: 154
🏁 Script executed:
# Look for any existing caveats about transaction behavior in other language versions
rg -n "transaction|事务|DDL|implicit" docs/features/sql-editor.mdx docs/*/features/sql-editor.mdx -A 2 -B 2 | head -80Repository: datlechin/TablePro
Length of output: 1921
🏁 Script executed:
# Check the English version for comparison
cat -n docs/features/sql-editor.mdx | sed -n '75,105p'Repository: datlechin/TablePro
Length of output: 1401
🏁 Script executed:
# Check what databases TablePro supports to understand scope
rg -i "mysql|postgres|sqlite|database.*support" docs/features/sql-editor.mdx docs/README.mdx | head -20Repository: datlechin/TablePro
Length of output: 956
🏁 Script executed:
# Look for any explicit transaction handling or database-specific notes
rg -n "BEGIN|COMMIT|ROLLBACK|transaction" docs/features/sql-editor.mdx -A 3 -B 1Repository: datlechin/TablePro
Length of output: 552
🏁 Script executed:
# Check if there's implementation code that shows what behavior is actually guaranteed
find . -name "*.ts" -o -name "*.tsx" -o -name "*.js" | head -20Repository: datlechin/TablePro
Length of output: 44
🏁 Script executed:
# Search for implementation that shows how transactions are actually handled
find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" \) | grep -E "(query|execute|transaction)" | head -20Repository: datlechin/TablePro
Length of output: 44
🏁 Script executed:
# Check git history or any comments about transaction handling
rg -n "implicit.*commit|DDL|transaction|rollback" --type ts --type tsx --type js | head -30Repository: datlechin/TablePro
Length of output: 89
🌐 Web query:
MySQL DDL implicit commit behavior in transactions
💡 Result:
In MySQL, most DDL implicitly ends the current transaction: when you execute a DDL statement while a transaction is open, MySQL behaves as if it ran COMMIT before the DDL, and most of these statements also perform an implicit commit after they run—so the DDL effectively runs in its own special transaction. Typical examples include CREATE TABLE, ALTER TABLE, DROP TABLE, TRUNCATE TABLE, RENAME TABLE, and many other object-definition statements. [1]
Key nuances called out by the MySQL manual:
CREATE TABLE/DROP TABLEwithTEMPORARY: no implicit commit occurs, but the operation still cannot be rolled back (so it can still violate transactional atomicity). [1]CREATE TABLE ... SELECT(non-temporary): causes an implicit commit before and after the statement. [1]- Starting a new transaction (
START TRANSACTION/BEGIN) implicitly commits any current one (transactions can’t be nested). [1]
Practical implication: you cannot make a multi-statement unit of work that includes DDL and then reliably ROLLBACK everything; once the DDL executes, any prior uncommitted DML in that session is committed. [1]
Source
[1] MySQL 8.4 Reference Manual – “Statements That Cause an Implicit Commit”
Clarify transaction behavior for DDL statements in multi-statement execution.
The documentation currently states that failed statements cause "all changes roll back," but the example includes DDL statements (DROP TABLE, CREATE TABLE). On MySQL and PostgreSQL, DDL statements trigger implicit commits and cannot be rolled back as part of the surrounding transaction. This overstates the safety guarantee, especially problematic since the use case—SQL dumps and migrations—often contains DDL.
Update the text to clarify that rollback applies only to transactional statements, or explicitly note that behavior depends on the database and statement type.
🛠️ Suggested wording
-如果选中内容包含**多条语句**（以分号分隔），它们会在一个事务中依次执行：
+如果选中内容包含**多条语句**（以分号分隔），TablePro 会按顺序执行它们。对于支持事务的语句，失败时会回滚当前事务；具体行为取决于数据库和语句类型：
- 语句按顺序逐条执行
-- 如果任一语句失败，执行停止并回滚所有变更
+- 如果任一语句失败，执行停止；对支持事务的语句会回滚当前事务
- 错误信息会标明是哪条语句失败（例如 "Statement 3/5 failed: ..."）
- 最后一个 `SELECT` 的结果显示在数据网格中
- 每条语句都会单独记录到查询历史
-适合运行 SQL 转储文件、数据迁移或一批相关语句：
+适合运行一批相关语句。执行包含 DDL 的批次前，请先确认目标数据库的事务行为：Note: Update the English version (docs/features/sql-editor.mdx) with equivalent changes for consistency.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~84-~84: 数词与名词之间一般应存在量词，可能缺少量词。
Context: ...以分号分隔），它们会在一个事务中依次执行： - 语句按顺序逐条执行 - 如果任一语句失败，执行停止并回滚所有变更 - 错误信息会标明是哪条语句失败（例如 "Stat...
(wa5)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/zh/features/sql-editor.mdx` around lines 81 - 96, Update the
multi-statement execution doc to clarify that "all changes roll back" only
applies to transactional statements and that DDL (e.g., DROP TABLE, CREATE
TABLE) may cause implicit commits or behave differently depending on the
database (MySQL/Postgres), so rollback is not guaranteed for DDL; mention that
the last SELECT result is shown and each statement is recorded as before, and
make the same wording change in docs/features/sql-editor.mdx (mirror the Chinese
edits in docs/zh/features/sql-editor.mdx) to note DB- and
statement-type-dependent behavior.
| ### 索引类型 | ||
|
|
||
| | 类型 | 用途 | | ||
| |------|------| | ||
| | **PRIMARY** | 主键约束 | | ||
| | **UNIQUE** | 唯一约束/索引 | | ||
| | **INDEX** | 用于性能优化的常规索引 | | ||
| | **FULLTEXT** | 全文搜索（MySQL） | | ||
| | **SPATIAL** | 地理空间数据（PostGIS） | |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
PostgreSQL spatial index types GiST SP-GiST
💡 Result:
PostgreSQL spatial index types: GiST vs SP-GiST (PostGIS)
GiST (Generalized Search Tree)
- The default / most common spatial index for PostGIS: PostGIS implements an R-tree–like spatial index on top of GiST (typically indexing geometry/geography bounding boxes) and the planner uses it for common spatial predicates (e.g., “intersects”, “within”, etc.). [1]
- Create it like:
(If you omit
CREATE INDEX ON mytable USING GIST (geom);
USING GIST, you won’t get a spatial index.) [1] - PostgreSQL core also ships GiST support for built-in 2D geometric types, and GiST is a framework for building tree indexes beyond just spatial. [2][3]
SP-GiST (Space-Partitioned GiST)
- A different access method designed for space-partitioning trees (e.g., quad-trees, k-d trees, tries), which can work well when data partitions cleanly and/or is non-uniform. [4][5]
- PostGIS supports SP-GiST as another spatial indexing option (along with GiST and BRIN) and documents how to build SP-GiST indexes on geometry columns. [6]
- Create it like:
CREATE INDEX ON mytable USING SPGIST (geom); ``` [6]
Practical guidance (rule of thumb)
- Use GiST first for PostGIS spatial workloads (it’s the standard, broadly applicable choice). [1][6]
- Consider SP-GiST especially for point-heavy data and cases where a partitioning structure (quad/k-d–style) matches your query patterns and distribution; test with
EXPLAIN (ANALYZE, BUFFERS)because results depend on data and queries. [4][6]
Sources: PostGIS spatial index FAQ [1], PostgreSQL docs on index types and GiST [2][3], PostgreSQL docs on SP-GiST [5], Purdue SP-GiST overview (data structures) [4], PostGIS manual (GiST/SP-GiST/BRIN and SP-GiST usage) [6].
🌐 Web query:
PostGIS index types spatial indexing GIST
💡 Result:
PostGIS spatial index types (focus: GiST)
- GiST (Generalized Search Tree) — the default and most common PostGIS spatial index. PostGIS implements an R-tree–like index structure on top of GiST, and the index stores bounding boxes (not full geometries), using them to quickly narrow candidates before exact geometry checks. [1]
- SP-GiST — an alternative that can help certain spatial workloads (often point-heavy / partitionable data) and is explicitly supported as a spatial indexing option in PostGIS. [2]
- BRIN — a lightweight index that stores summaries per block-range (very small/fast to build). For PostGIS it currently provides “inclusion” support for a limited set of bounding-box-style operators (e.g.,
&&in 2D,&&&in 3D), and benefits a lot when data is physically clustered/sorted spatially. [3]
Typical GiST syntax (geometry/geography)
-- Geometry (2D GiST is the common default)
CREATE INDEX ON my_table USING GIST (geom);
-- Force n-D operator class (e.g., for 3D)
CREATE INDEX ON my_table USING GIST (geom gist_geometry_ops_nd);
-- Geography
CREATE INDEX ON my_table USING GIST (geog);Query note (how the index gets used)
Most common PostGIS predicates (e.g., ST_Intersects, ST_DWithin, etc.) are “index-aware” and will automatically apply an indexable bounding-box filter where possible; you typically don’t need to add && manually. [4]
Sources
[1] (postgis.net)
[2] (postgis.net)
[3] (postgis.net)
[4] (postgis.net)
Citations:
- 1: https://postgis.net/stuff/postgis-3.5.3-en.pdf?utm_source=openai
- 2: https://postgis.net/docs/manual-3.5/postgis-en.html?utm_source=openai
- 3: https://postgis.net/docs/manual-3.5/using_postgis_dbmanagement.html?utm_source=openai
- 4: https://postgis.net/workshops/uk/postgis-intro/indexing.html?utm_source=openai
🌐 Web query:
MySQL SPATIAL index type
💡 Result:
In MySQL, a SPATIAL index is an R-tree index (MySQL uses R-trees with quadratic splitting) for spatial (geometry) columns, supported for InnoDB and MyISAM tables. [1], [2]
The index type terminology for PostGIS is incorrect.
The row | **SPATIAL** | 地理空间数据（PostGIS） | incorrectly uses MySQL terminology (SPATIAL is an R-tree index type specific to MySQL) and misleads readers into thinking PostGIS uses a SPATIAL index keyword. PostgreSQL and PostGIS use GiST (the default and most common choice) or SP-GiST (an alternative for certain spatial workloads like point-heavy data). Update this row to use the correct PostGIS terminology.
🛠️ Suggested wording
-| **SPATIAL** | 地理空间数据（PostGIS） |
+| **GiST / SP-GiST** | PostgreSQL / PostGIS 中常见的空间索引 |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/zh/features/table-structure.mdx` around lines 141 - 149, Update the
table row describing spatial indexes: replace the incorrect MySQL-specific
"SPATIAL" wording with PostGIS-appropriate terminology by changing the row for
spatial indexes to mention GiST (常用) and SP-GiST (适用于点密集型场景) and optionally note
that MySQL's SPATIAL is different; edit the table entry in the "索引类型" section
where the row currently reads `**SPATIAL**` / `地理空间数据（PostGIS）` to instead
reference `GiST / SP-GiST` and a short description like
"地理空间索引（PostGIS，常用GiST；点密集型可用SP-GiST）".
2 participants
Summary
docs/zh/)docs.json.mdxfiles covering all sections: Getting Started, Database Connections, Features, Customization, API Reference, and DevelopmentDetails
Translation follows the same structure as the existing Vietnamese (
vi) translation:zh/zh/databases/zh/features/zh/customization/zh/api/zh/development/Translation guidelines followed:
title/descriptiontranslated to Chinese/zh/prefixSummary by CodeRabbit