@nocobase/plugin-ai 2.2.0-alpha.1 → 2.2.0-alpha.11

package/dist/ai/docs/nocobase/data-sources/external/index.md

@@ -0,0 +1,140 @@
+---
+title: "External databases"
+description: "Connect existing MySQL, PostgreSQL, MariaDB, KingbaseES, OceanBase, MSSQL, Oracle, ClickHouse, and Doris databases to NocoBase, then map their fields and relations."
+keywords: "external database,MySQL,PostgreSQL,MariaDB,KingbaseES,OceanBase,MSSQL,Oracle,ClickHouse,Doris,field mapping,NocoBase"
+---
+
+# External databases
+
+## Introduction
+
+An **external database** connects an existing business database to NocoBase. NocoBase reads tables, fields, and views so they can be used in page blocks, permissions, workflows, and APIs.
+
+Unlike the [main database](../main/index.md), the original system and database tools maintain the external schema. NocoBase reads the structure and views; it does not change real tables in the external database.
+
+| Database | Supported version | Community | Standard | Professional | Enterprise |
+| --- | --- | --- | --- | --- | --- |
+| MySQL | >= 5.7 | No | Yes | Yes | Yes |
+| PostgreSQL | >= 9.5 | No | Yes | Yes | Yes |
+| MariaDB | >= 10.3 | No | Yes | Yes | Yes |
+| MSSQL | 2014-2019 | No | Yes | Yes | Yes |
+| KingbaseES | >= V9 | No | No | Yes | Yes |
+| OceanBase | >= 4.3 | No | No | No | Yes |
+| Oracle | >= 11g | No | No | No | Yes |
+| ClickHouse | See the corresponding plugin documentation. | No | No | No | Yes |
+| Doris | See the corresponding plugin documentation. | No | No | No | Yes |
+
+:::tip Tip
+
+KingbaseES supports only PostgreSQL compatibility mode. OceanBase, ClickHouse, and Doris support only MySQL compatibility mode.
+
+:::
+
+Typical use cases include:
+
+- Connect an existing ERP, MES, WMS, or CRM database and build management pages, permissions, workflows, and reports without changing its schema.
+- Add lightweight approval, data-correction, exception-handling, or operations-dashboard capabilities without replacing the original system.
+- Query, analyze, or display existing data for reporting or BI.
+- Migrate a historical system gradually: keep the old database connected first, then put new business data in the main database over time.
+- Leave the database structure to DBAs, migration scripts, or the original system while NocoBase provides pages and data usage.
+
+:::warning Note
+
+An external database is not the NocoBase system database. NocoBase does not manage its backup, restore, migrations, or schema changes.
+
+:::
+
+## Plugin installation
+
+Each external database is supplied by a data-source plugin. Install and enable the plugin before its database type appears in **Data source management** > **Add new**.
+
+| Database | Plugin | Installation |
+| --- | --- | --- |
+| MySQL | `@nocobase/plugin-data-source-external-mysql` | Requires a commercial license; install and enable it. |
+| PostgreSQL | `@nocobase/plugin-data-source-external-postgres` | Requires a commercial license; install and enable it. |
+| MariaDB | `@nocobase/plugin-data-source-external-mariadb` | Requires a commercial license; install and enable it. |
+| KingbaseES | `@nocobase/plugin-data-source-kingbase` | Requires a commercial license; install and enable it. |
+| OceanBase | `@nocobase/plugin-data-source-oceanbase` | Requires a commercial license; install and enable it. |
+| MSSQL | `@nocobase/plugin-data-source-external-mssql` | Requires a commercial license; install and enable it. |
+| Oracle | `@nocobase/plugin-data-source-external-oracle` | Requires a commercial license; install and enable it. |
+| ClickHouse | `@nocobase/plugin-data-source-external-clickhouse` | Requires a commercial license; install and enable it. |
+| Doris | `@nocobase/plugin-data-source-external-doris` | Requires a commercial license; install and enable it. |
+
+![Add a database](https://static-docs.nocobase.com/add_new_database.png)
+
+If a database type is missing from **Add new**, check that its plugin is installed and enabled, the commercial license includes it, and the current user can manage data sources.
+
+## Usage
+
+### Add an external database
+
+After the plugin is activated, choose the database type from **Add new** and provide its connection information.
+
+![Add an external database](https://static-docs.nocobase.com/20240507204316.png)
+
+![Configure an external database](https://static-docs.nocobase.com/20240507204820.png)
+
+### Synchronize collections
+
+After an external database is connected, NocoBase reads its collections. It cannot create collections or change the external schema. Make schema changes through database tools, then use the refresh action to synchronize metadata.
+
+![Synchronize external collections](https://static-docs.nocobase.com/20240507204725.png)
+
+### Configure fields
+
+NocoBase reads and displays existing fields. You can configure their title, **Field type**, and **Field interface**, or use **Edit** for additional configuration.
+
+![Configure external fields](https://static-docs.nocobase.com/20240507210537.png)
+
+Because an external database schema cannot be changed from NocoBase, the only field type you can add is a relation field. A relation field is not a real database column; it connects collections in NocoBase.
+
+![Add an external relation field](https://static-docs.nocobase.com/20240507220140.png)
+
+See [Collection fields](../data-modeling/collection-fields/index.md) for details.
+
+### Field type mapping
+
+NocoBase maps external database types to a corresponding **Field type** and **Field interface**. Field type defines the kind, format, and structure of stored data; Field interface defines the control used to display and enter the value.
+
+| PostgreSQL | MySQL / MariaDB | NocoBase Field type | NocoBase Field interface |
+| --- | --- | --- | --- |
+| BOOLEAN | BOOLEAN, TINYINT(1) | `boolean` | `checkbox`, `switch` |
+| SMALLINT, INTEGER, SERIAL, SMALLSERIAL | TINYINT, SMALLINT, MEDIUMINT, INTEGER | `integer`, `boolean`, `sort` | `integer`, `sort`, `checkbox`, `switch`, `select`, `radioGroup` |
+| BIGINT, BIGSERIAL | BIGINT | `bigInt`, `sort` | `integer`, `sort`, `checkbox`, `switch`, `select`, `radioGroup`, `unixTimestamp`, `createdAt`, `updatedAt` |
+| REAL | FLOAT | `float` | `number`, `percent` |
+| DOUBLE PRECISION | DOUBLE PRECISION | `double` | `number`, `percent` |
+| DECIMAL, NUMERIC | DECIMAL | `decimal` | `number`, `percent`, `currency` |
+| VARCHAR, CHAR | VARCHAR, CHAR | `string`, `password`, `uuid`, `nanoid` | `input`, `email`, `phone`, `password`, `color`, `icon`, `select`, `radioGroup`, `uuid`, `nanoid` |
+| TEXT | TEXT, TINYTEXT, MEDIUMTEXT, LONGTEXT | `text`, `json` | `textarea`, `markdown`, `vditor`, `richText`, `url`, `json` |
+| UUID | - | `uuid` | `uuid` |
+| JSON, JSONB | JSON | `json` | `json` |
+| TIMESTAMP | DATETIME, TIMESTAMP | `date` | `date`, `time`, `createdAt`, `updatedAt` |
+| DATE | DATE | `dateOnly` | `datetime` |
+| TIME | TIME | `time` | `time` |
+| - | YEAR | - | `datetime` |
+| CIRCLE | - | `circle` | `json`, `circle` |
+| POINT, GEOMETRY(POINT) | POINT | `point` | `json`, `point` |
+| PATH, GEOMETRY(LINESTRING) | LINESTRING | `lineString` | `json`, `lineString` |
+| POLYGON, GEOMETRY(POLYGON) | POLYGON | `polygon` | `json`, `polygon` |
+| GEOMETRY | GEOMETRY | - | - |
+| BLOB | BLOB | `blob` | - |
+| ARRAY | - | `array` | `multipleSelect`, `checkboxGroup` |
+| BIT | BIT | - | - |
+| SET | SET | `set` | `multipleSelect`, `checkboxGroup` |
+| RANGE | - | - | - |
+
+### Unsupported field types
+
+Unsupported field types are shown separately. They require development support before they can be used.
+
+![Unsupported field types](https://static-docs.nocobase.com/20240507221854.png)
+
+### Record unique key
+
+A collection shown in a block needs a **Record unique key** to locate a record, usually a primary key or unique field.
+
+For a view, table without a primary key, or composite-primary-key table, set the Record unique key manually in the collection configuration. Without a usable unique key, blocks might not be created correctly or might not be able to view and edit records.
+
+![Edit a collection](https://static-docs.nocobase.com/edit_collection.png)
+
+![Configure a collection](https://static-docs.nocobase.com/edit_collection_configure.png)

package/dist/ai/docs/nocobase/data-sources/external/kingbase.md

@@ -0,0 +1,129 @@
+---
+pkg: "@nocobase/plugin-data-source-kingbase"
+title: "External data source - KingbaseES"
+description: "Learn how to connect KingbaseES as an external database in NocoBase, including supported versions, PostgreSQL compatibility mode, connection settings, schemas, permissions, and field mapping."
+keywords: "external data source,KingbaseES,external database,PostgreSQL compatibility mode,field mapping,NocoBase"
+---
+
+# KingbaseES
+
+## Introduction
+
+KingbaseES can be connected to NocoBase as an external database. NocoBase reads tables, fields, and views from KingbaseES and makes them available as collections in the external data source.
+
+Unlike a [main data source](../main/index.md), the actual schema of an external KingbaseES database continues to be maintained by the original business system, database client, or migration scripts. NocoBase reads the schema, stores field metadata, and lets you configure blocks, permissions, workflows, and APIs.
+
+| Setting | Description |
+| --- | --- |
+| Supported version | KingbaseES >= V9. |
+| Commercial editions | Available in Professional and Enterprise editions. |
+| Plugin | `@nocobase/plugin-data-source-kingbase`. |
+| Database mode | Only PostgreSQL compatibility mode is supported. |
+
+External KingbaseES is suitable when you need to:
+
+- Connect an existing KingbaseES business database in a government, enterprise, intranet, or localized environment
+- Build management pages in NocoBase without migrating historical data
+- Apply permissions, workflow processing, data corrections, or reporting to existing tables
+- Keep the database schema maintained by DBAs, migration scripts, or the original system
+
+:::warning Note
+
+KingbaseES is supported as an external database only in PostgreSQL compatibility mode. If the database does not use PostgreSQL compatibility mode, NocoBase cannot read its schema and field types through the current plugin.
+
+:::
+
+## Plugin installation
+
+This is a commercial plugin. For activation instructions, see the [Commercial plugin activation guide](https://www.nocobase.com/en/blog/nocobase-commercial-license-activation-guide).
+
+## Add a data source
+
+In **Data source management**, click **Add new**, select KingbaseES, and then enter the connection details.
+
+![Add an external KingbaseES data source](https://static-docs.nocobase.com/20260709210325.png)
+
+Common connection settings are as follows:
+
+| Setting | Description |
+| --- | --- |
+| Data source name | The internal identifier used by blocks, permissions, workflows, and APIs. It cannot be changed after the data source is created. |
+| Data source display name | The name displayed in the interface. Use a name that business users can recognize, such as `Government KingbaseES` or `Reporting database`. |
+| Host / Port | The KingbaseES host address and port. Use the port configured for the database. |
+| Database | The name of the KingbaseES database to connect to. |
+| Username / Password | The account credentials used to connect to KingbaseES. NocoBase can read only objects that this account is allowed to access; it does not grant access to, or read, objects private to other accounts. |
+| Schema | The schema to read. If the database contains multiple schemas, specify only the schema required by the current business application. |
+| Table prefix | A table-name prefix. When configured, NocoBase reads only tables and views that match the prefix, and removes the prefix from the generated NocoBase collection names. |
+| Collections / Add all collections | Controls the connection scope. With **Add all collections** enabled, NocoBase connects all tables and views in the current scope. When disabled, it connects only the objects selected in **Collections**. |
+| Enabled the data source | Whether to enable the data source. When disabled, its configuration is retained, but blocks, permissions, workflows, and APIs can no longer read its data. |
+
+:::tip Tip
+
+When KingbaseES contains many objects, narrow the scope through `Schema`, `Table prefix`, and **Collections** first. Connecting only the tables and views used by the current application keeps permissions, page building, and synchronization easier to maintain.
+
+:::
+
+## Select collections
+
+After entering connection details, click **Load Collections** to read available tables and views from KingbaseES. The results depend on the connection account, `Schema`, `Table prefix`, and **Collections** settings.
+
+By default, **Add all collections** is enabled, which connects all tables and views in the current scope. To connect only selected objects, disable **Add all collections** and select the required tables or views from the list.
+
+![Select external KingbaseES collections](https://static-docs.nocobase.com/20260709210603.png)
+
+:::warning Note
+
+An external data source can connect up to 500 tables or views at a time. When KingbaseES contains many objects, narrow the scope through `Schema`, `Table prefix`, or **Collections** first.
+
+:::
+
+## Synchronize and configure fields
+
+The external KingbaseES schema is maintained in the database. NocoBase does not create fields, change field types, or delete actual fields in the external database.
+
+When the KingbaseES schema changes, run **Sync from database** from the data source to read collection and field metadata again. Synchronization updates the collections, fields, primary keys, unique keys, and field-type mapping metadata stored in NocoBase. It does not delete actual KingbaseES tables or data.
+
+After fields are synchronized, you can configure their titles, Field type, and Field interface in NocoBase. NocoBase relationship fields are also stored as relationship metadata in NocoBase and do not automatically add actual foreign-key columns to KingbaseES tables.
+
+## Field type mapping
+
+NocoBase identifies KingbaseES types according to PostgreSQL compatibility rules and automatically maps them to appropriate Field types and Field interfaces. You can adjust the display interface in field settings.
+
+| KingbaseES type | NocoBase Field type | Available Field interfaces |
+| --- | --- | --- |
+| `BOOLEAN` | `boolean` | Checkbox, Switch. |
+| `SMALLINT`, `INTEGER` | `integer`, `sort` | Integer, Sort, Select, Radio group. |
+| `BIGINT` | `bigInt`, `snowflakeId`, `unixTimestamp`, `sort` | Integer, Sort, Unix timestamp, Created at, Updated at. |
+| `REAL`, `DOUBLE PRECISION` | `float` | Number, Percent. |
+| `DECIMAL`, `NUMERIC` | `decimal` | Number, Percent, Currency. |
+| `VARCHAR`, `CHAR` | `string`, `uuid`, `nanoid`, `encryption`, `datetimeNoTz` | Input, Email, Phone, Password, Color, Icon, Select, Radio group, UUID, Nano ID. |
+| `TEXT` | `text` | Textarea, Markdown, Vditor, Rich text, URL. |
+| `UUID` | `uuid` | UUID. |
+| `JSON`, `JSONB` | `json`, `array` | JSON. |
+| `TIMESTAMP WITHOUT TIME ZONE` | `datetimeNoTz` | Date, Time, Created at, Updated at. |
+| `TIMESTAMP WITH TIME ZONE` | `datetimeTz`, `date` | Date, Time, Created at, Updated at. |
+| `DATE` | `dateOnly` | Date. |
+| `TIME WITHOUT TIME ZONE` | `time` | Time. |
+| `POINT`, `PATH`, `POLYGON`, `CIRCLE` | `json` | JSON. |
+| `ARRAY` | `array` | Multiple select, Checkbox group, JSON. |
+
+:::warning Note
+
+Unsupported KingbaseES types are displayed separately in field settings. They require development support before they can be used as regular NocoBase fields.
+
+:::
+
+## Primary key and Record unique key
+
+Collections used for block display and editing should have a primary key or unique field. NocoBase uses the primary key as the Record unique key when available.
+
+For views, tables without a primary key, or composite-primary-key tables, configure **Record unique key** manually in the collection settings. Without a usable identifier, blocks might not view, edit, or delete records correctly.
+
+![Primary key and Record unique key](https://static-docs.nocobase.com/20260709210636.png)
+![Configure Record unique key](https://static-docs.nocobase.com/20260709210651.png)
+
+## Related links
+
+- [External databases](./index.md) - General external-database configuration and management.
+- [Data source management](../data-source-manager/index.md) - Data-source entry points and management.
+- [Collection fields](../data-modeling/collection-fields/index.md) - Field types and field mapping.

package/dist/ai/docs/nocobase/data-sources/external/mariadb.md

@@ -0,0 +1,126 @@
+---
+pkg: "@nocobase/plugin-data-source-external-mariadb"
+title: "External data source - MariaDB"
+description: "Learn how to connect MariaDB as an external database in NocoBase, including supported versions, plugin installation, connection settings, collection scope, permissions, and field mapping."
+keywords: "external data source,MariaDB,external database,field mapping,NocoBase"
+---
+
+# MariaDB
+
+## Introduction
+
+MariaDB can be connected to NocoBase as an external database. NocoBase reads tables, fields, and views from MariaDB and makes them available as collections in the external data source.
+
+Unlike a [main data source](../main/index.md), the actual schema of an external MariaDB database continues to be maintained by the original business system, database client, or migration scripts. NocoBase reads the schema, stores field metadata, and lets you configure blocks, permissions, workflows, and APIs.
+
+| Setting | Description |
+| --- | --- |
+| Supported version | MariaDB >= 10.3. |
+| Commercial editions | Available in Standard, Professional, and Enterprise editions. |
+| Plugin | `@nocobase/plugin-data-source-external-mariadb`. |
+| Compatible protocol | Connects through the MySQL protocol. Field mapping generally follows MySQL compatibility rules. |
+
+External MariaDB is suitable when you need to:
+
+- Connect a MariaDB database used by an existing ERP, MES, WMS, CRM, or other business system
+- Build management pages in NocoBase without migrating historical data
+- Apply permissions, workflow processing, data corrections, or reporting to existing tables
+- Keep the database schema maintained by DBAs, migration scripts, or the original system
+
+:::warning Note
+
+An external MariaDB database is not a NocoBase system database. NocoBase does not manage its backups, restores, migrations, or schema changes.
+
+:::
+
+## Plugin installation
+
+This is a commercial plugin. For activation instructions, see the [Commercial plugin activation guide](https://www.nocobase.com/en/blog/nocobase-commercial-license-activation-guide).
+
+## Add a data source
+
+In **Data source management**, click **Add new**, select MariaDB, and then enter the connection details.
+
+![Add an external MariaDB data source](https://static-docs.nocobase.com/20260709204413.png)
+
+Common connection settings are as follows:
+
+| Setting | Description |
+| --- | --- |
+| Data source name | The internal identifier used by blocks, permissions, workflows, and APIs. It cannot be changed after the data source is created. |
+| Data source display name | The name displayed in the interface. Use a name that business users can recognize, such as `ERP MariaDB` or `Order database`. |
+| Host / Port | The MariaDB host address and port. The default port is usually `3306`. |
+| Database | The name of the MariaDB database to connect to. |
+| Username / Password | The account credentials used to connect to MariaDB. NocoBase can read only objects that this account is allowed to access; it does not grant access to, or read, objects private to other accounts. |
+| Table prefix | A table-name prefix. When configured, NocoBase reads only tables and views that match the prefix, and removes the prefix from the generated NocoBase collection names. |
+| Collections / Add all collections | Controls the connection scope. With **Add all collections** enabled, NocoBase connects all tables and views in the current scope. When disabled, it connects only the objects selected in **Collections**. |
+| Enabled the data source | Whether to enable the data source. When disabled, its configuration is retained, but blocks, permissions, workflows, and APIs can no longer read its data. |
+
+:::tip Tip
+
+When MariaDB contains many objects, narrow the scope through `Database`, `Table prefix`, and **Collections** first. Connecting only the tables and views used by the current application keeps permissions, page building, and synchronization easier to maintain.
+
+:::
+
+## Select collections
+
+After entering connection details, click **Load Collections** to read available tables and views from MariaDB. The results depend on the connection account, `Database`, `Table prefix`, and **Collections** settings.
+
+By default, **Add all collections** is enabled, which connects all tables and views in the current scope. To connect only selected objects, disable **Add all collections** and select the required tables or views from the list.
+
+![Select external MariaDB collections](https://static-docs.nocobase.com/20260709204452.png)
+
+:::warning Note
+
+An external data source can connect up to 500 tables or views at a time. When MariaDB contains many objects, narrow the scope through `Database`, `Table prefix`, or **Collections** first.
+
+:::
+
+## Synchronize and configure fields
+
+The external MariaDB schema is maintained in MariaDB. NocoBase does not create fields, change field types, or delete actual fields in the external database.
+
+When the MariaDB schema changes, run **Sync from database** from the data source to read collection and field metadata again. Synchronization updates the collections, fields, primary keys, unique keys, and field-type mapping metadata stored in NocoBase. It does not delete actual MariaDB tables or data.
+
+After fields are synchronized, you can configure their titles, Field type, and Field interface in NocoBase. NocoBase relationship fields are also stored as relationship metadata in NocoBase and do not automatically add actual foreign-key columns to MariaDB tables.
+
+## Field type mapping
+
+NocoBase automatically maps MariaDB types to appropriate Field types and Field interfaces. Common MariaDB mappings are largely the same as MySQL mappings, and you can adjust the display interface in field settings.
+
+| MariaDB type | NocoBase Field type | Available Field interfaces |
+| --- | --- | --- |
+| `TINYINT`, `SMALLINT`, `MEDIUMINT` | `integer`, `boolean`, `sort` | Integer, Sort, Checkbox, Switch, Select, Radio group. |
+| `INT`, `INTEGER` | `integer`, `unixTimestamp`, `sort` | Integer, Sort, Unix timestamp, Select, Radio group. |
+| `BIGINT` | `bigInt`, `snowflakeId`, `unixTimestamp`, `sort` | Integer, Sort, Unix timestamp, Created at, Updated at. |
+| `FLOAT`, `DOUBLE` | `float` | Number, Percent. |
+| `DECIMAL` | `decimal` | Number, Percent, Currency. |
+| `CHAR`, `VARCHAR` | `string`, `uuid`, `nanoid`, `encryption` | Input, Email, Phone, Password, Color, Icon, Select, Radio group, UUID, Nano ID. |
+| `TINYTEXT`, `TEXT`, `MEDIUMTEXT`, `LONGTEXT` | `text` | Textarea, Markdown, Vditor, Rich text, URL. |
+| `DATE` | `dateOnly` | Date. |
+| `TIME` | `time` | Time. |
+| `DATETIME` | `datetimeNoTz`, `datetimeTz`, `date` | Date, Time, Created at, Updated at. |
+| `TIMESTAMP` | `datetimeTz`, `date` | Date, Time, Created at, Updated at. |
+| `YEAR` | `string`, `integer` | Input, Integer, Date. |
+| `JSON` | `json`, `array` | JSON. |
+
+:::warning Note
+
+Unsupported MariaDB types are displayed separately in field settings. They require development support before they can be used as regular NocoBase fields.
+
+:::
+
+## Primary key and Record unique key
+
+Collections used for block display and editing should have a primary key or unique field. NocoBase uses the primary key as the Record unique key when available.
+
+For views, tables without a primary key, or composite-primary-key tables, configure **Record unique key** manually in the collection settings. Without a usable identifier, blocks might not view, edit, or delete records correctly.
+
+![Primary key and Record unique key](https://static-docs.nocobase.com/20260709205835.png)
+![Configure Record unique key](https://static-docs.nocobase.com/20260709205854.png)
+
+## Related links
+
+- [External databases](./index.md) - General external-database configuration and management.
+- [Data source management](../data-source-manager/index.md) - Data-source entry points and management.
+- [Collection fields](../data-modeling/collection-fields/index.md) - Field types and field mapping.

package/dist/ai/docs/nocobase/data-sources/external/mssql.md

@@ -0,0 +1,129 @@
+---
+pkg: "@nocobase/plugin-data-source-external-mssql"
+title: "External data source - MSSQL"
+description: "Learn how to connect MSSQL/SQL Server as an external database in NocoBase, including supported versions, plugin installation, connection settings, encrypted connections, permissions, and field mapping."
+keywords: "external data source,MSSQL,SQL Server,external database,field mapping,NocoBase"
+---
+
+# MSSQL
+
+## Introduction
+
+MSSQL (SQL Server) can be connected to NocoBase as an external database. NocoBase reads tables, fields, and views from SQL Server and makes them available as collections in the external data source.
+
+Unlike a [main data source](../main/index.md), the actual schema of an external MSSQL database continues to be maintained by the original business system, database client, or migration scripts. NocoBase reads the schema, stores field metadata, and lets you configure blocks, permissions, workflows, and APIs.
+
+| Setting | Description |
+| --- | --- |
+| Supported version | SQL Server 2014-2019. |
+| Commercial editions | Available in Standard, Professional, and Enterprise editions. |
+| Plugin | `@nocobase/plugin-data-source-external-mssql`. |
+| Connection features | Supports **Encrypt connection** and **Trust server certificate**. |
+
+External MSSQL is suitable when you need to:
+
+- Connect an SQL Server database used by an existing ERP, MES, WMS, CRM, or other business system
+- Build management pages in NocoBase without migrating historical data
+- Apply permissions, workflow processing, data corrections, or reporting to existing tables
+- Keep the database schema maintained by DBAs, migration scripts, or the original system
+
+:::warning Note
+
+An external MSSQL database is not a NocoBase system database. NocoBase does not manage its backups, restores, migrations, or schema changes.
+
+:::
+
+## Plugin installation
+
+This is a commercial plugin. For activation instructions, see the [Commercial plugin activation guide](https://www.nocobase.com/en/blog/nocobase-commercial-license-activation-guide).
+
+## Add a data source
+
+In **Data source management**, click **Add new**, select MSSQL, and then enter the connection details.
+
+![Add an external MSSQL data source](https://static-docs.nocobase.com/20260709210022.png)
+
+Common connection settings are as follows:
+
+| Setting | Description |
+| --- | --- |
+| Data source name | The internal identifier used by blocks, permissions, workflows, and APIs. It cannot be changed after the data source is created. |
+| Data source display name | The name displayed in the interface. Use a name that business users can recognize, such as `ERP SQL Server` or `Finance database`. |
+| Host / Port | The SQL Server host address and port. The default port is usually `1433`. |
+| Database | The name of the SQL Server database to connect to. |
+| Username / Password | The account credentials used to connect to SQL Server. NocoBase can read only objects that this account is allowed to access; it does not grant access to, or read, objects private to other accounts. |
+| Table prefix | A table-name prefix. When configured, NocoBase reads only tables and views that match the prefix, and removes the prefix from the generated NocoBase collection names. |
+| Encrypt connection | Whether to enable an encrypted connection. Enable it when the database enforces encryption or the network connection requires encryption. |
+| Trust server certificate | Whether to trust the server certificate. You might need to enable it for test environments or self-signed certificates; use a trusted certificate in production. |
+| Collections / Add all collections | Controls the connection scope. With **Add all collections** enabled, NocoBase connects all tables and views in the current scope. When disabled, it connects only the objects selected in **Collections**. |
+| Enabled the data source | Whether to enable the data source. When disabled, its configuration is retained, but blocks, permissions, workflows, and APIs can no longer read its data. |
+
+:::tip Tip
+
+When SQL Server contains many objects, narrow the scope through `Database`, `Table prefix`, and **Collections** first. Connecting only the tables and views used by the current application keeps permissions, page building, and synchronization easier to maintain.
+
+:::
+
+## Select collections
+
+After entering connection details, click **Load Collections** to read available tables and views from SQL Server. The results depend on the connection account, `Database`, `Table prefix`, and **Collections** settings.
+
+By default, **Add all collections** is enabled, which connects all tables and views in the current scope. To connect only selected objects, disable **Add all collections** and select the required tables or views from the list.
+
+![Select external SQL Server collections](https://static-docs.nocobase.com/add_new_database_configure_load_collection.png)
+
+:::warning Note
+
+An external data source can connect up to 500 tables or views at a time. When SQL Server contains many objects, narrow the scope through `Database`, `Table prefix`, or **Collections** first.
+
+:::
+
+## Synchronize and configure fields
+
+The external MSSQL schema is maintained in SQL Server. NocoBase does not create fields, change field types, or delete actual fields in the external database.
+
+When the SQL Server schema changes, run **Sync from database** from the data source to read collection and field metadata again. Synchronization updates the collections, fields, primary keys, unique keys, and field-type mapping metadata stored in NocoBase. It does not delete actual SQL Server tables or data.
+
+After fields are synchronized, you can configure their titles, Field type, and Field interface in NocoBase. NocoBase relationship fields are also stored as relationship metadata in NocoBase and do not automatically add actual foreign-key columns to SQL Server tables.
+
+## Field type mapping
+
+NocoBase automatically maps SQL Server types to appropriate Field types and Field interfaces. You can adjust the display interface in field settings.
+
+| SQL Server type | NocoBase Field type | Available Field interfaces |
+| --- | --- | --- |
+| `BIT` | `bit` | Checkbox, Switch. |
+| `TINYINT`, `SMALLINT` | `integer`, `boolean`, `sort` | Integer, Sort, Checkbox, Switch, Select, Radio group. |
+| `INT` | `integer`, `unixTimestamp`, `sort` | Integer, Sort, Unix timestamp, Select, Radio group. |
+| `BIGINT` | `bigInt`, `unixTimestamp`, `sort` | Integer, Sort, Unix timestamp, Created at, Updated at. |
+| `DECIMAL`, `MONEY`, `SMALLMONEY` | `decimal` | Number, Percent, Currency. |
+| `NUMERIC`, `FLOAT`, `REAL` | `float` | Number, Percent. |
+| `CHAR`, `VARCHAR`, `NCHAR`, `NVARCHAR` | `string`, `uuid`, `nanoid` | Input, Email, Phone, Password, Color, Icon, Select, Radio group, UUID, Nano ID. |
+| `TEXT`, `NTEXT` | `text` | Textarea, Markdown, Vditor, Rich text, URL. |
+| `DATE` | `dateOnly` | Date. |
+| `TIME` | `time` | Time. |
+| `DATETIME`, `DATETIME2` | `datetimeNoTz` | Date, Time, Created at, Updated at. |
+| `DATETIMEOFFSET` | `datetimeTz` | Date, Time, Created at, Updated at. |
+| `UNIQUEIDENTIFIER` | `uuid`, `string` | UUID, Input. |
+| `JSON` | `json`, `array` | JSON. |
+
+:::warning Note
+
+Unsupported SQL Server types are displayed separately in field settings. They require development support before they can be used as regular NocoBase fields.
+
+:::
+
+## Primary key and Record unique key
+
+Collections used for block display and editing should have a primary key or unique field. NocoBase uses the primary key as the Record unique key when available.
+
+For views, tables without a primary key, or composite-primary-key tables, configure **Record unique key** manually in the collection settings. Without a usable identifier, blocks might not view, edit, or delete records correctly.
+
+![Primary key and Record unique key](https://static-docs.nocobase.com/20260709210154.png)
+![Configure Record unique key](https://static-docs.nocobase.com/20260709210214.png)
+
+## Related links
+
+- [External databases](./index.md) - General external-database configuration and management.
+- [Data source management](../data-source-manager/index.md) - Data-source entry points and management.
+- [Collection fields](../data-modeling/collection-fields/index.md) - Field types and field mapping.

package/dist/ai/docs/nocobase/data-sources/external/mysql.md

@@ -0,0 +1,115 @@
+---
+pkg: "@nocobase/plugin-data-source-external-mysql"
+title: "External data source - MySQL"
+description: "Connect MySQL as an external NocoBase database, including version support, plugin installation, connection configuration, table scope, permissions, and field mapping."
+keywords: "external data source,MySQL,external database,field mapping,NocoBase"
+---
+
+# MySQL
+
+## Introduction
+
+MySQL can be connected to NocoBase as an external database. NocoBase reads MySQL tables, fields, and views and uses them as collections in the external data source.
+
+Unlike the [main database](../main/index.md), the original business system, database client, or migration scripts maintain the real MySQL schema. NocoBase reads structure, stores field metadata, and configures blocks, permissions, workflows, and APIs.
+
+| Setting | Description |
+| --- | --- |
+| Supported version | MySQL >= 5.7. |
+| Commercial editions | Standard, Professional, and Enterprise. |
+| Plugin | `@nocobase/plugin-data-source-external-mysql`. |
+| Connection protocol | MySQL protocol. |
+
+Use external MySQL to connect existing ERP, MES, WMS, or CRM databases, build management pages without migrating historical data, apply permissions and workflows to existing tables, and leave schema maintenance to DBAs or the original system.
+
+:::warning Note
+
+External MySQL is not the NocoBase system database. NocoBase does not manage its backup, restore, migrations, or schema changes.
+
+:::
+
+## Plugin installation
+
+This is a commercial plugin. See the [commercial plugin activation guide](https://www.nocobase.com/en/blog/nocobase-commercial-license-activation-guide) for activation.
+
+## Add a data source
+
+In **Data source management**, click **Add new**, select MySQL, and enter the connection information.
+
+![Add MySQL](https://static-docs.nocobase.com/20240507204820.png)
+
+| Setting | Description |
+| --- | --- |
+| Data source name | Internal identifier used by blocks, permissions, workflows, and APIs. It cannot be changed after creation. |
+| Data source display name | Name shown in the interface, such as ERP MySQL or Orders database. |
+| Host / Port | MySQL server address and port. The usual default port is `3306`. |
+| Database | The MySQL database to connect. |
+| Username / Password | Credentials used to connect. NocoBase reads only objects that this account can access; it does not grant access to other users' private objects. |
+| Table prefix | Limits reading to matching tables and views, and removes the prefix from the NocoBase collection name. |
+| Collections / Add all collections | With **Add all collections** enabled, imports all tables and views in scope; otherwise imports only selected objects. |
+| Enabled the data source | Disables access through blocks, permissions, workflows, and APIs while keeping the configuration. |
+
+:::tip Tip
+
+For a database with many objects, narrow the scope with `Database`, `Table prefix`, and **Collections**. Import only objects the application needs so that permissions, page building, and synchronization remain manageable.
+
+:::
+
+## Select collections
+
+Click **Load Collections** to read available MySQL tables and views. Results depend on the connection account, `Database`, `Table prefix`, and **Collections** settings.
+
+**Add all collections** is enabled by default. Disable it and select individual objects when only part of the database is needed.
+
+![Select MySQL collections](https://static-docs.nocobase.com/add_new_database_configure_load_collection.png)
+
+:::warning Note
+
+One external data source can import at most 500 tables or views. Narrow the scope with `Database`, `Table prefix`, or **Collections** when MySQL has many objects.
+
+:::
+
+## Synchronize and configure fields
+
+MySQL maintains the external table structure. NocoBase does not create columns, change column types, or delete real fields in external MySQL.
+
+When the MySQL schema changes, use **Sync from database** to reread collection and field metadata. Synchronization updates NocoBase collections, fields, primary keys, unique keys, and type mappings; it does not delete real MySQL tables or data.
+
+After synchronization, configure field titles, Field types, and Field interfaces in NocoBase. NocoBase relation fields are metadata only and do not automatically add real foreign-key columns to MySQL.
+
+## Field type mapping
+
+| MySQL type | NocoBase Field type | Available Field interfaces |
+| --- | --- | --- |
+| `TINYINT`, `SMALLINT`, `MEDIUMINT` | `integer`, `boolean`, `sort` | Integer, Sort, Checkbox, Switch, Select, Radio group. |
+| `INT`, `INTEGER` | `integer`, `unixTimestamp`, `sort` | Integer, Sort, Unix timestamp, Select, Radio group. |
+| `BIGINT` | `bigInt`, `snowflakeId`, `unixTimestamp`, `sort` | Integer, Sort, Unix timestamp, Created at, Updated at. |
+| `FLOAT`, `DOUBLE` | `float` | Number, Percent. |
+| `DECIMAL` | `decimal` | Number, Percent, Currency. |
+| `CHAR`, `VARCHAR` | `string`, `uuid`, `nanoid`, `encryption` | Input, Email, Phone, Password, Color, Icon, Select, Radio group, UUID, Nano ID. |
+| `TINYTEXT`, `TEXT`, `MEDIUMTEXT`, `LONGTEXT` | `text` | Textarea, Markdown, Vditor, Rich text, URL. |
+| `DATE` | `dateOnly` | Date. |
+| `TIME` | `time` | Time. |
+| `DATETIME` | `datetimeNoTz`, `datetimeTz`, `date` | Date, Time, Created at, Updated at. |
+| `TIMESTAMP` | `datetimeTz`, `date` | Date, Time, Created at, Updated at. |
+| `YEAR` | `string`, `integer` | Input, Integer, Date. |
+| `JSON` | `json`, `array` | JSON. |
+
+:::warning Note
+
+Unsupported MySQL types are shown separately in field configuration. They require development support before they can be used as normal NocoBase fields.
+
+:::
+
+## Primary key and Record unique key
+
+Collections used for block display and editing should have a primary key or unique field. NocoBase uses the primary key as the Record unique key when available.
+
+For views, tables without a primary key, or composite-primary-key tables, configure **Record unique key** manually. Without a usable identifier, blocks might not view, edit, or delete records correctly.
+
+![Primary key and Record unique key](https://static-docs.nocobase.com/20260709205547.png)
+![Configure Record unique key](https://static-docs.nocobase.com/20260709205609.png)
+
+- [External databases](./index.md) - General external-database configuration and management.
+- [Data source management](../data-source-manager/index.md) - Data-source entry points and management.
+- [Collection fields](../data-modeling/collection-fields/index.md) - Field types and mapping.