Skip to content

Commit f75019d

Browse files
datlechindatlechin
committed
docs: add iCloud sync documentation (EN/VI/ZH)
1 parent e97dd57 commit f75019d

5 files changed

Lines changed: 614 additions & 4 deletions

File tree

‎docs/customization/settings.mdx‎

Lines changed: 71 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Settings Overview
3-
description: All settings categories - General, Appearance, Editor, Data Grid, Tabs, Keyboard, AI, History, Plugins, and License
3+
description: All settings categories - General, Appearance, Editor, Data Grid, Tabs, Keyboard, AI, History, Plugins, Sync, and License
44
---
55

66
# Settings Overview
@@ -51,6 +51,9 @@ Open settings via **TablePro** > **Settings** or `Cmd+,`.
5151
<Card title="Plugins" icon="puzzle-piece">
5252
Manage database driver plugins
5353
</Card>
54+
<Card title="Sync" icon="cloud" href="/features/icloud-sync">
55+
iCloud sync for connections, settings, and history across Macs (Pro)
56+
</Card>
5457
<Card title="License" icon="key">
5558
License activation and management
5659
</Card>
@@ -423,6 +426,62 @@ Some settings are available via `defaults write` for advanced users:
423426
| Custom plugin registry | `defaults write com.TablePro com.TablePro.customRegistryURL <url>` | Use a private plugin registry |
424427
| Clear custom registry | `defaults delete com.TablePro com.TablePro.customRegistryURL` | Revert to default registry |
425428

429+
## Sync Settings
430+
431+
Manage iCloud sync from the **Sync** tab in Settings. This is a Pro feature.
432+
433+
### iCloud Sync Toggle
434+
435+
| Setting | Default | Description |
436+
|---------|---------|-------------|
437+
| **iCloud Sync** | Off | Enable or disable iCloud sync across all Macs |
438+
439+
### Status
440+
441+
| Element | Description |
442+
|---------|-------------|
443+
| **iCloud Account** | Shows the current iCloud account status |
444+
| **Last Sync** | Timestamp of the most recent sync |
445+
| **Sync Now** | Manually trigger a sync |
446+
447+
### Sync Categories
448+
449+
| Setting | Default | Description |
450+
|---------|---------|-------------|
451+
| **Connections** | On | Sync connection details (not passwords) |
452+
| **Groups & Tags** | On | Sync connection organization |
453+
| **App Settings** | On | Sync all 8 settings categories |
454+
| **Query History** | On | Sync query history |
455+
456+
### History Limit
457+
458+
| Option | Description |
459+
|--------|-------------|
460+
| **100** | Sync last 100 queries |
461+
| **500** | Sync last 500 queries |
462+
| **1,000** | Sync last 1,000 queries |
463+
| **Unlimited** | Sync all query history |
464+
465+
<Note>
466+
Passwords are never synced. They remain in each Mac's local Keychain.
467+
</Note>
468+
469+
See [iCloud Sync](/features/icloud-sync) for full details on conflict resolution, sync behavior, and troubleshooting.
470+
471+
{/* Screenshot: Sync settings */}
472+
<Frame caption="Sync settings: iCloud sync configuration">
473+
<img
474+
className="block dark:hidden"
475+
src="/images/settings-sync.png"
476+
alt="Sync settings"
477+
/>
478+
<img
479+
className="hidden dark:block"
480+
src="/images/settings-sync-dark.png"
481+
alt="Sync settings"
482+
/>
483+
</Frame>
484+
426485
## License Settings
427486

428487
Manage your license from the **License** tab in Settings.
@@ -537,6 +596,17 @@ See [Appearance](/customization/appearance) for details.
537596
| Shortcut bindings | Keyboard | Customize menu keyboard shortcuts |
538597
| Reset to Defaults | Keyboard | Restore all shortcuts to original values |
539598

599+
### Sync-Related
600+
601+
| Setting | Location | Description |
602+
|---------|----------|-------------|
603+
| iCloud Sync | Sync | Enable/disable iCloud sync (Pro) |
604+
| Sync Connections | Sync | Sync connection details across Macs |
605+
| Sync Groups & Tags | Sync | Sync connection organization |
606+
| Sync App Settings | Sync | Sync preferences across Macs |
607+
| Sync Query History | Sync | Sync query history with configurable limit |
608+
| History Limit | Sync | Max history entries to sync (100/500/1,000/unlimited) |
609+
540610
### Filter-Related
541611

542612
| Setting | Location | Description |

‎docs/docs.json‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,8 @@
6363
"features/ai-chat",
6464
"features/keyboard-shortcuts",
6565
"features/deep-links",
66-
"features/safe-mode"
66+
"features/safe-mode",
67+
"features/icloud-sync"
6768
]
6869
},
6970
{
@@ -157,7 +158,8 @@
157158
"vi/features/ai-chat",
158159
"vi/features/keyboard-shortcuts",
159160
"vi/features/deep-links",
160-
"vi/features/safe-mode"
161+
"vi/features/safe-mode",
162+
"vi/features/icloud-sync"
161163
]
162164
},
163165
{
@@ -256,7 +258,8 @@
256258
"zh/features/ai-chat",
257259
"zh/features/keyboard-shortcuts",
258260
"zh/features/deep-links",
259-
"zh/features/safe-mode"
261+
"zh/features/safe-mode",
262+
"zh/features/icloud-sync"
260263
]
261264
},
262265
{

‎docs/features/icloud-sync.mdx‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
---
2+
title: iCloud Sync
3+
description: Sync connections, settings, and query history across Macs via iCloud (Pro feature)
4+
---
5+
6+
# iCloud Sync
7+
8+
TablePro syncs your connections, groups, settings, and query history across all your Macs via CloudKit. iCloud Sync is a Pro feature that requires an active license.
9+
10+
## What Syncs (and What Doesn't)
11+
12+
| Data | Synced | Notes |
13+
|------|--------|-------|
14+
| **Connections** | Yes | Host, port, username, database type, SSH/SSL config |
15+
| **Passwords** | No | Stay in each Mac's local Keychain |
16+
| **Groups & Tags** | Yes | Full connection organization |
17+
| **App Settings** | Yes | All 8 categories (General, Appearance, Editor, Data Grid, History, Tabs, Keyboard, AI) |
18+
| **Query History** | Yes | Configurable limit: 100, 500, 1,000, or unlimited |
19+
20+
<Warning>
21+
Passwords are never synced. They remain in your macOS Keychain on each machine. After syncing a connection to a new Mac, you need to enter the password once on that machine.
22+
</Warning>
23+
24+
## Enabling iCloud Sync
25+
26+
1. Open **Settings** (`Cmd+,`) and select the **Sync** tab
27+
2. Toggle **iCloud Sync** on
28+
3. Choose which categories to sync using the per-category toggles
29+
4. Click **Sync Now** or wait for the next automatic sync
30+
31+
Sync is off by default. You must opt in explicitly.
32+
33+
{/* Screenshot: Sync settings tab */}
34+
<Frame caption="iCloud Sync settings">
35+
<img
36+
className="block dark:hidden"
37+
src="/images/settings-sync.png"
38+
alt="iCloud Sync settings"
39+
/>
40+
<img
41+
className="hidden dark:block"
42+
src="/images/settings-sync-dark.png"
43+
alt="iCloud Sync settings"
44+
/>
45+
</Frame>
46+
47+
## Sync Categories
48+
49+
Each data type has its own toggle. Sync connections but not history, or settings but not connections.
50+
51+
| Category | What it includes |
52+
|----------|-----------------|
53+
| **Connections** | All connection details except passwords |
54+
| **Groups & Tags** | Connection groups and color tags |
55+
| **App Settings** | Preferences from all 8 settings categories |
56+
| **Query History** | Past queries up to the configured limit |
57+
58+
### History Limit
59+
60+
Control how many history entries sync across devices:
61+
62+
| Option | Description |
63+
|--------|-------------|
64+
| **100** | Last 100 queries |
65+
| **500** | Last 500 queries |
66+
| **1,000** | Last 1,000 queries |
67+
| **Unlimited** | All query history |
68+
69+
<Tip>
70+
Start with 500. Unlimited history sync can slow down initial sync on large histories.
71+
</Tip>
72+
73+
## Automatic Sync
74+
75+
TablePro auto-syncs in three situations:
76+
77+
- **App launch** -- pulls the latest data from iCloud
78+
- **App foreground** -- syncs when you switch back to TablePro
79+
- **Local edits** -- pushes changes 2 seconds after you modify synced data (debounced to avoid excess writes)
80+
81+
Use the **Sync Now** button in Settings > Sync to trigger a manual sync at any time.
82+
83+
## Conflict Resolution
84+
85+
When the same record is modified on two Macs before syncing, TablePro prompts you to choose:
86+
87+
| Option | Description |
88+
|--------|-------------|
89+
| **Keep This Mac's Version** | Discard the remote change, keep local |
90+
| **Keep Other Version** | Discard the local change, use the remote version |
91+
92+
Conflicts are resolved per-record, not per-category. Editing a connection on Mac A and a different connection on Mac B causes no conflict.
93+
94+
{/* Screenshot: Conflict resolution dialog */}
95+
<Frame caption="Sync conflict resolution">
96+
<img
97+
className="block dark:hidden"
98+
src="/images/sync-conflict.png"
99+
alt="Sync conflict resolution"
100+
/>
101+
<img
102+
className="hidden dark:block"
103+
src="/images/sync-conflict-dark.png"
104+
alt="Sync conflict resolution"
105+
/>
106+
</Frame>
107+
108+
## Sync Status Indicator
109+
110+
The welcome window footer shows the current sync status:
111+
112+
| Status | Meaning |
113+
|--------|---------|
114+
| **Synced** | All data is up to date |
115+
| **Syncing** | Sync in progress |
116+
| **Error** | Sync failed (hover for details) |
117+
| **Off** | iCloud Sync is disabled |
118+
119+
{/* Screenshot: Sync status in welcome window footer */}
120+
<Frame caption="Sync status indicator in welcome window">
121+
<img
122+
className="block dark:hidden"
123+
src="/images/sync-status.png"
124+
alt="Sync status indicator"
125+
/>
126+
<img
127+
className="hidden dark:block"
128+
src="/images/sync-status-dark.png"
129+
alt="Sync status indicator"
130+
/>
131+
</Frame>
132+
133+
## Pro License Requirement
134+
135+
iCloud Sync requires an active Pro license. Without one, the Sync settings tab shows a "Pro required" overlay.
136+
137+
When a license expires:
138+
139+
- Sync stops immediately
140+
- All previously synced data stays on each Mac as local data
141+
- Re-activating a license resumes sync from where it left off
142+
143+
## Troubleshooting
144+
145+
### No records syncing
146+
147+
1. Confirm iCloud is signed in: **System Settings** > **Apple Account** > **iCloud**
148+
2. Check that iCloud Drive is enabled
149+
3. Verify the specific category toggle is on in Settings > Sync
150+
4. Click **Sync Now** to force a sync attempt
151+
152+
### Stale data on one Mac
153+
154+
Click **Sync Now** on the Mac with outdated data. If the problem persists, toggle iCloud Sync off and on again. This forces a full re-sync.
155+
156+
### "iCloud account unavailable" error
157+
158+
TablePro requires an active iCloud account. Sign in via **System Settings** > **Apple Account**. Corporate Managed Apple IDs work as long as iCloud Drive is not restricted by MDM policy.
159+
160+
### Sync stopped after license expired
161+
162+
This is expected. Sync requires an active Pro license. Renew or re-activate your license to resume syncing.
163+
164+
## Related Pages
165+
166+
<CardGroup cols={2}>
167+
<Card title="Settings" icon="gear" href="/customization/settings">
168+
All settings categories
169+
</Card>
170+
<Card title="License" icon="key" href="/customization/settings#license-settings">
171+
License activation and management
172+
</Card>
173+
<Card title="Query History" icon="clock-rotate-left" href="/features/query-history">
174+
Browse previous queries
175+
</Card>
176+
<Card title="Safe Mode" icon="shield" href="/features/safe-mode">
177+
Per-connection query execution controls
178+
</Card>
179+
</CardGroup>

0 commit comments

Comments
 (0)