Skip to content

Commit 70a6fde

Browse files
Albert-mahAlbert-mah
authored
feat: update handbook with new data source comparison details (#401)
1 parent 07e90cc commit 70a6fde

File tree

5 files changed

+680
-13
lines changed

5 files changed

+680
-13
lines changed

‎docs/config/handbook.ts‎

Lines changed: 20 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -34,18 +34,18 @@ export default [
3434
link: '/handbook/data-source-manager',
3535
},
3636
{
37-
title: 'Main database',
38-
'title.fr-FR': 'Base de données principale',
39-
'title.zh-CN': '主数据库',
40-
'title.ja-JP': 'メインデータベース',
37+
title: 'Main data source',
38+
'title.fr-FR': 'Source de données principale',
39+
'title.zh-CN': '主数据源',
40+
'title.ja-JP': 'メインデータソース',
4141
// subTitle: '@nocobase/plugin-collection-manager',
4242
link: '/handbook/data-source-main',
4343
},
4444
{
45-
title: 'External database',
46-
'title.fr-FR': 'Base de données externe',
47-
'title.zh-CN': '外部数据库',
48-
'title.ja-JP': '外部データベース',
45+
title: 'External data sources (Databases)',
46+
'title.fr-FR': 'Sources de données externes (Bases de données)',
47+
'title.zh-CN': '外部数据源（数据库）',
48+
'title.ja-JP': '外部データソース（データベース）',
4949
children: [
5050
{
5151
title: 'Overview',
@@ -56,46 +56,53 @@ export default [
5656
},
5757
{
5858
title: 'External MySQL',
59-
'title.fr-FR': 'Source de données MySQL',
59+
'title.fr-FR': 'MySQL externe',
6060
'title.zh-CN': '外部 MySQL',
6161
'title.ja-JP': '外部 MySQL',
6262
// subTitle: '@nocobase/plugin-data-source-external-mysql',
6363
link: '/handbook/data-source-external-mysql',
6464
},
6565
{
6666
title: 'External MariaDB',
67-
'title.fr-FR': 'Source de données MariaDB',
67+
'title.fr-FR': 'MariaDB externe',
6868
'title.zh-CN': '外部 MariaDB',
6969
'title.ja-JP': '外部 MariaDB',
7070
// subTitle: '@nocobase/plugin-data-source-external-mariadb',
7171
link: '/handbook/data-source-external-mariadb',
7272
},
7373
{
7474
title: 'External PostgreSQL',
75-
'title.fr-FR': 'Source de données PostgreSQL',
75+
'title.fr-FR': 'PostgreSQL externe',
7676
'title.zh-CN': '外部 PostgreSQL',
7777
'title.ja-JP': '外部 PostgreSQL',
7878
// subTitle: '@nocobase/plugin-data-source-external-postgres',
7979
link: '/handbook/data-source-external-postgres',
8080
},
8181
{
8282
title: 'External MSSQL',
83-
'title.fr-FR': 'Source de données MSSQL',
83+
'title.fr-FR': 'MSSQL externe',
8484
'title.zh-CN': '外部 MSSQL',
8585
'title.ja-JP': '外部 MSSQL',
8686
// subTitle: '@nocobase/plugin-data-source-external-mysql',
8787
link: '/handbook/data-source-external-mssql',
8888
},
8989
{
9090
title: 'External Oracle',
91-
'title.fr-FR': 'Source de données Oracle',
91+
'title.fr-FR': 'Oracle externe',
9292
'title.zh-CN': '外部 Oracle',
9393
'title.ja-JP': '外部 Oracle',
9494
// subTitle: '@nocobase/plugin-data-source-external-mysql',
9595
link: '/handbook/data-source-external-oracle',
9696
},
9797
],
9898
},
99+
{
100+
title: 'Master vs External Data Sources',
101+
'title.fr-FR': 'Sources de données: principale vs externe',
102+
'title.zh-CN': '主、外部数据源对比',
103+
'title.ja-JP': 'メイン・外部データソース比較',
104+
link: '/handbook/data-modeling/master-vs-external-data-sources',
105+
},
99106
{
100107
title: 'REST API data source',
101108
'title.fr-FR': 'Source de données API REST',

‎docs/en-US/handbook/data-modeling/master-vs-external-data-sources.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# Master vs External Data Sources
2+
3+
The differences between master data sources and external data sources in NocoBase are primarily reflected in four aspects: data source type support, collection type support, field type support, and backup and migration capabilities.
4+
5+
## 1. Data Source Type Support
6+
7+
For more details, see: [Data Source Manager](https://docs.nocobase.com/handbook/data-source-manager)
8+
9+
### Data Source Types
10+
11+
| Data Source Type | Master Data Source Support | External Data Source Support |
12+
|------------------|---------------------------|------------------------------|
13+
| PostgreSQL | ✅ | ✅ |
14+
| MySQL | ✅ | ✅ |
15+
| MariaDB | ✅ | ✅ |
16+
| KingbaseES | ✅ | ✅ |
17+
| MSSQL | ❌ | ✅ |
18+
| Oracle | ❌ | ✅ |
19+
20+
### Collection Management
21+
22+
| Collection Management | Master Data Source Support | External Data Source Support |
23+
|----------------------|-----------------------------|------------------------------|
24+
| Basic Management | ✅ | ✅ |
25+
| Visual Management | ✅ | ❌ |
26+
27+
## 2. Collection Type Support
28+
29+
For more details, see: [Collections](https://docs.nocobase.com/handbook/data-modeling/collection)
30+
31+
| Collection Type | Master Data Source | External Data Source | Description |
32+
|----------------|-------------------|---------------------|-------------|
33+
| General | ✅ | ✅ | Basic collection |
34+
| View | ✅ | ✅ | Data source view |
35+
| Inheritance | ✅ | ❌ | Supports data model inheritance, master data source only |
36+
| File | ✅ | ❌ | Supports file uploads, master data source only |
37+
| Comment | ✅ | ❌ | Built-in comment system, master data source only |
38+
| Calendar | ✅ | ❌ | Collection for calendar views |
39+
| Expression | ✅ | ❌ | Supports formula calculations |
40+
| Tree | ✅ | ❌ | For tree structure data modeling |
41+
| SQL | ✅ | ❌ | Collection defined through SQL |
42+
| External Connection | ✅ | ❌ | Connection collection for external data sources, limited functionality |
43+
44+
## 3. Field Type Support
45+
46+
For more details, see: [Collection Fields](https://docs.nocobase.com/handbook/data-modeling/collection-fields)
47+
48+
### Basic Types
49+
50+
| Field Type | Master Data Source | External Data Source |
51+
|-----------|----------------|-------------------|
52+
| Single text | ✅ | ✅ |
53+
| Long text | ✅ | ✅ |
54+
| Phone | ✅ | ✅ |
55+
| Email | ✅ | ✅ |
56+
| URL | ✅ | ✅ |
57+
| Integer | ✅ | ✅ |
58+
| Number | ✅ | ✅ |
59+
| Percent | ✅ | ✅ |
60+
| Password | ✅ | ✅ |
61+
| Color | ✅ | ✅ |
62+
| Icon | ✅ | ✅ |
63+
64+
### Choice Types
65+
66+
| Field Type | Master Data Source | External Data Source |
67+
|-----------|----------------|-------------------|
68+
| Checkbox | ✅ | ✅ |
69+
| Single select | ✅ | ✅ |
70+
| Multiple select | ✅ | ✅ |
71+
| Radio group | ✅ | ✅ |
72+
| Checkbox group | ✅ | ✅ |
73+
| China region | ✅ | ❌ |
74+
75+
### Media Types
76+
77+
| Field Type | Master Data Source | External Data Source |
78+
|-----------|----------------|-------------------|
79+
| Media | ✅ | ✅ |
80+
| Markdown | ✅ | ✅ |
81+
| Markdown(Vditor) | ✅ | ❌ |
82+
| Rich text | ✅ | ✅ |
83+
| Attachment(Association) | ✅ | ❌ |
84+
| Attachment(URL) | ✅ | ✅ |
85+
86+
### Date & Time Types
87+
88+
| Field Type | Master Data Source | External Data Source |
89+
|-----------|----------------|-------------------|
90+
| Datetime(with time zone) | ✅ | ✅ |
91+
| Datetime(without time zone) | ✅ | ✅ |
92+
| Unix timestamp | ✅ | ✅ |
93+
| Date(without time) | ✅ | ✅ |
94+
| Time | ✅ | ✅ |
95+
96+
### Geometric Types
97+
98+
| Field Type | Master Data Source | External Data Source |
99+
|-----------|----------------|-------------------|
100+
| Point | ✅ | ✅ |
101+
| Line | ✅ | ✅ |
102+
| Circle | ✅ | ✅ |
103+
| Polygon | ✅ | ✅ |
104+
105+
### Advanced Types
106+
107+
| Field Type | Master Data Source | External Data Source |
108+
|-----------|----------------|-------------------|
109+
| UUID | ✅ | ✅ |
110+
| Nano ID | ✅ | ✅ |
111+
| Sort | ✅ | ✅ |
112+
| Formula | ✅ | ✅ |
113+
| Sequence | ✅ | ✅ |
114+
| JSON | ✅ | ✅ |
115+
| Collection select | ✅ | ❌ |
116+
| Encryption | ✅ | ✅ |
117+
118+
### System Info Fields
119+
120+
| Field Type | Master Data Source | External Data Source |
121+
|-----------|----------------|-------------------|
122+
| Created at | ✅ | ✅ |
123+
| Last updated at | ✅ | ✅ |
124+
| Created by | ✅ | ❌ |
125+
| Last updated by | ✅ | ❌ |
126+
| Table OID | ✅ | ❌ |
127+
128+
### Association Types
129+
130+
| Field Type | Master Data Source | External Data Source |
131+
|-----------|----------------|-------------------|
132+
| One-to-one | ✅ | ✅ |
133+
| One-to-many | ✅ | ✅ |
134+
| Many-to-one | ✅ | ✅ |
135+
| Many-to-many | ✅ | ✅ |
136+
| Many-to-many (array) | ✅ | ❌ |
137+
138+
:::info
139+
Attachment fields depend on file collections, which are only supported by master data sources. Therefore, external data sources do not currently support attachment fields.
140+
:::
141+
142+
## 4. Backup and Migration Support Comparison
143+
144+
| Feature | Master Data Source | External Data Source |
145+
|---------|-------------------|---------------------|
146+
| Backup & Restore | ✅ | ❌ (User managed) |
147+
| Migration Management | ✅ | ❌ (User managed) |
148+
149+
:::info
150+
NocoBase provides backup, restore, and structure migration capabilities for master data sources. For external data sources, these operations need to be completed independently by users according to their own data source environments. NocoBase does not provide built-in support.
151+
:::
152+
153+
## Summary Comparison
154+
155+
| Comparison Item | Master Data Source | External Data Source |
156+
|----------------|-------------------|---------------------|
157+
| Data Source Types | PostgreSQL, MySQL, MariaDB, KingbaseES | PostgreSQL, MySQL, MariaDB, MSSQL, Oracle, KingbaseES |
158+
| Collection Type Support | All collection types | Only general and view collections |
159+
| Field Type Support | All field types | All field types except attachment fields |
160+
| Backup & Migration | Built-in support | User managed |
161+
162+
## Recommendations
163+
164+
- **If you need to use NocoBase's advanced features** (such as comments, inheritance, file uploads, etc.), please use the **master data source**.
165+
- **If you only need to read or connect to existing external data source data**, you can use **external data sources**.

0 commit comments

Comments
 (0)