@nocobase/plugin-ai 2.2.0-beta.9 → 3.0.0-alpha.1

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

@@ -1,18 +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"
 ---
 
-# External Data Source - MySQL
+# MySQL
 
 ## Introduction
 
-Use an external MySQL database as a data source. Currently supported versions: MySQL >= 5.7
+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.
 
-## Installation
+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.
 
-This is a commercial plugin. For detailed activation instructions, please refer to: [Commercial Plugin Activation Guide](https://www.nocobase.com/en/blog/nocobase-commercial-license-activation-guide)
+| 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.
 
-## Usage Instructions
+:::warning Note
 
-Refer to the [Data Source / External Database](/data-sources/data-source-manager/external-database) section.
+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.

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

@@ -1,157 +1,159 @@
 ---
-title: 'External NocoBase'
-description: 'Connect another NocoBase application as an external data source and learn about configuration, available capabilities, and workflow limitations.'
-keywords: 'External NocoBase,NocoBase data source,data source manager,workflow,NocoBase'
+title: "External NocoBase"
+description: "Connect another NocoBase application as an external data source. Learn the configuration, available capabilities, and workflow limitations."
+keywords: "external NocoBase,NocoBase data source,data source management,workflow,NocoBase"
 ---
 
 # External NocoBase
 
 ## Introduction
 
-The External NocoBase data source connects another NocoBase application to the current application while preserving metadata from the remote application, including collections, field interfaces, titles, and association fields.
+An External NocoBase data source connects another NocoBase application to the current application, retaining metadata configured in the remote application, including collections, Field interfaces, titles, and relation fields.
 
-Compared with an external database data source, an external NocoBase data source usually does not require you to configure field interfaces again or manually create association fields. In addition to viewing, creating, editing, and deleting records, it also supports file upload and preview, import and export, chart queries, and some workflow scenarios.
+Unlike an external database data source, External NocoBase normally does not require you to configure Field interfaces again or manually create relation fields. In addition to viewing, creating, editing, and deleting records, it supports file upload and preview, import and export, chart queries, and some workflow scenarios.
 
-## Add a Data Source
+## Add a data source
 
-After activating the plugin, add an External NocoBase data source in Data Source Manager and fill in the access information of the remote application.
+After activating the plugin, add an External NocoBase data source in **Data source management** and enter the remote application's access information.
 
-| Option | Description |
+| Setting | Description |
 | --- | --- |
-| API URL | The full API URL of the remote NocoBase application, such as `https://example.com/api` |
-| Origin | The public origin of the remote NocoBase application, such as `https://example.com`. It is mainly used to handle preview URLs for local files in the remote application |
+| API address | The complete API address of the remote NocoBase application, for example `https://example.com/api` |
+| Origin | The access origin of the remote NocoBase application, for example `https://example.com`. It is primarily used to handle local-file preview addresses in the remote application |
 | API key | The credential used by the current application to access the remote NocoBase application |
-| Request headers | Additional request headers sent to the remote application, such as space information |
-| Timeout | Request timeout for accessing the remote application |
+| Request headers | Additional request headers passed to the remote application, such as space information |
+| Timeout | The request timeout for accessing the remote application |
 
-After the data source is enabled, the system loads the collections from the remote application.
+After you enable the data source, the system loads collections from the remote application.
 
 ![](https://static-docs.nocobase.com/202606101149185.png)
 
 ## Permissions
 
-An External NocoBase data source is affected by permissions in both the current application and the remote application.
+External NocoBase data sources are affected by permissions in both the current and remote applications.
 
-- In the current application, you can configure access permissions for different collections and fields just like other external data sources.
-- In the remote application, data is read and operated according to the permissions of the configured API key.
+- The current application can configure access permissions for different collections and fields, as with other external data sources
+- The remote application reads and operates the corresponding data according to the permissions of the configured API key
 
-External NocoBase data sources do not return permission metadata used for fine-grained button visibility on the frontend. As a result, some buttons may not be automatically hidden by permissions in the same way as the main data source. Regardless of whether a button is visible, submitted operations still go through server-side permission checks in the current application, and unauthorized operations are rejected.
+An External NocoBase data source does not return permission metadata used by the client to precisely control button visibility. Some buttons might not automatically hide according to permissions as they do for a main data source. Whether or not a button is visible, submitting an operation still passes through the current application's server-side permission check, and unauthorized operations are rejected.
+
+:::warning Note
+
+Prepare a dedicated API key for the External NocoBase data source and grant only the necessary collection and action permissions. If an operation fails although the current application permits it, check the permissions of the remote API key.
 
-:::warning{title=Note}
-Prepare a dedicated API key for the External NocoBase data source and grant only the required collection and operation permissions. If a user has permission in the current application but the operation fails, check the permissions of the remote API key.
 :::
 
-## Use Collections
+## Use collections
 
-After collections are loaded successfully, select this data source in page configuration, block configuration, charts, or workflows to use collections from the remote application.
+After collections are loaded, select this data source in page configuration, block configuration, charts, or workflows to use collections from the remote application.
 
-When the collection structure in the remote application changes, reload the collections in the current application.
+When the remote collection structure changes, reload collections in the current application.
 
-## Features
+## Capabilities
 
-External NocoBase data sources are mainly used to use collections and data from a remote application in the current application. The collection structure, field configuration, and actual data are still maintained by the remote application.
+External NocoBase is mainly used to access collections and data from the remote application in the current application. The collection structure, field configuration, and actual data continue to be maintained by the remote application.
 
-### Collections and Fields
+### Collections and fields
 
-The current application loads metadata from the remote application, including collections, field interfaces, titles, and association fields. Compared with an external database data source, you usually do not need to configure field interfaces again or manually create association fields in the current application.
+The current application loads metadata from the remote application, including collections, Field interfaces, titles, and relation fields. Unlike an external database data source, you normally do not need to configure Field interfaces again or manually create relation fields in the current application.
 
-The current application does not support configuring fields directly for an External NocoBase data source. To add fields, adjust field types, or modify association fields, make the changes in the remote application and then reload the collections in the current application.
+You cannot configure fields of an External NocoBase data source directly in the current application. To add a field, adjust a Field type, or modify a relation field, make the change in the remote application, then return to the current application and reload collections.
 
-### Records and Associated Data
+### Records and relation data
 
-External NocoBase data sources support viewing, creating, editing, and deleting records in page blocks, and also support viewing and maintaining associated data. Operations are initiated by the current application and sent to the remote application through the configured API key.
+An External NocoBase data source supports viewing, creating, editing, and deleting records in page blocks, as well as viewing and maintaining relation data. The current application initiates operations and requests the remote application through the configured API key.
 
-### Files and Attachments
+### Files and attachments
 
-Files are uploaded to the storage used by the remote application. The current application initiates upload, preview, and download requests, but the files themselves are not stored in the current application.
+Files are uploaded to the storage used by the remote application. The current application initiates upload, preview, and download requests, while the file itself is not stored in the current application.
 
-Origin is mainly used to handle preview URLs for files stored locally by the remote application. If the remote application returns a relative path, the current application uses Origin to complete the file access URL. Origin should be the public access address of the remote NocoBase application, for example:
+Origin is primarily used to handle preview addresses for files stored locally by the remote application. When the remote application returns a relative path, the current application uses Origin to complete the file access address. Set Origin to the public access address of the remote NocoBase application, for example:
 
 ```text
 https://example.com
 ```
 
-Do not use the API URL as Origin.
+Do not use the API address as Origin.
 
-### Import and Export
+### Import and export
 
-Import and export operations read from or write to the data source through external files, and are proxied to the remote application for execution. The current application handles user operations, forwards requests, and returns download results. The actual data read and write operations are completed by the remote application.
+Import and export are operations that read and write data sources through external files, and are both proxied to the remote application. The current application receives user actions, forwards requests, and returns download results, while the remote application performs the actual data reads and writes.
 
-- Import records: the current application receives the uploaded import file and proxies it to the remote application for import.
-- Export records: the current application proxies the request to the remote application to export records. In synchronous mode, the record file returned by the remote application is streamed back to the browser for download. In asynchronous mode, a local async task is created, record export is started in the remote application, progress is synchronized to the local task, and the result file is streamed from the remote application when downloaded.
-- Export attachments: the current application proxies the request to the remote application to export attachments. In synchronous mode, the attachment archive returned by the remote application is streamed back to the browser for download. In asynchronous mode, a local async task is created, attachment export is started in the remote application, progress is synchronized to the local task, and the attachment archive is streamed from the remote application when downloaded.
+- **Import records**: The current application receives the uploaded import file and proxies it to the remote application for import
+- **Export records**: The current application proxies a record-export request to the remote application. In synchronous mode, the record file returned by the remote application is streamed to the browser for download. In asynchronous mode, a local asynchronous task is created; it initiates record export in the remote application, synchronizes progress, and streams the record file from the remote application when the result is downloaded
+- **Export attachments**: The current application proxies an attachment-export request to the remote application. In synchronous mode, the attachment archive returned by the remote application is streamed to the browser for download. In asynchronous mode, a local asynchronous task is created; it initiates attachment export in the remote application, synchronizes progress, and streams the attachment archive from the remote application when the result is downloaded
 
-### Template Print
+### Template printing
 
-Template Print can use records from an External NocoBase data source. Print templates and print action configuration are stored in the current application. When printing, the current application reads remote records and associated data, and generates the print file in the current application.
+Template printing can use records from an External NocoBase data source. Print-template and print-action configurations are stored in the current application. When printing, the current application reads remote records and relation data, then generates the print file in the current application.
 
 ### Charts
 
-#### Query Panel
+#### Query panel
 
-External NocoBase data sources can be used in the chart query panel. The current application processes query parameters according to locally configured chart, data source, collection, and field permissions, then requests results from the remote application.
+An External NocoBase data source can be used in a chart query panel. The current application processes query parameters according to locally configured chart, data-source, collection, and field permissions, then requests results from the remote application.
 
-The remote API key must also have access to the corresponding data, otherwise the query fails.
+The remote API key also needs permission to access the corresponding data, otherwise the query fails.
 
-#### SQL Panel
+#### SQL panel
 
-The SQL panel is the SQL query mode in charts and is used only for queries. The current application saves SQL configuration and initiates the call, while the SQL is proxied to the remote application for execution.
+The SQL panel is the SQL query mode of charts and is used only for queries. The current application stores the SQL configuration and initiates the request; SQL is proxied to the remote application for execution.
 
-When using the SQL panel, the local user must have UI configuration permissions in the current application, and the remote API key must also have UI configuration permissions in the remote application. SQL is not broken down by collection and field permissions like the query panel. Grant UI configuration permissions to local users and the corresponding API key with caution.
+When using the SQL panel, local users need UI-configuration permission in the current application, and the remote API key needs UI-configuration permission in the remote application. Unlike the query panel, the SQL panel does not break query parameters down by collection and field permissions. Grant UI-configuration permissions to local users and the API key carefully.
 
 ### Workflows
 
-External NocoBase data sources may involve workflows in both the current application and the remote application. The current application responds to events in local pages, buttons, and API request chains. After the remote application receives proxied requests, it handles them according to its own workflow configuration.
+External NocoBase data can involve two sets of workflows: one in the current application and one in the remote application. The current application handles events in local pages, buttons, and API request chains. After receiving a proxied request, the remote application processes it using its own workflow configuration.
 
-The current application does not listen to create, update, or delete events that occur inside remote collections. Remote collection events are triggered only in the remote application.
+The current application does not listen for internal create, update, or delete events from remote collections. Remote collection events are triggered only in the remote application.
 
 #### Triggers
 
-The following table describes how triggers affected by External NocoBase data sources behave in the current application and the remote application when the corresponding workflow is enabled.
+The following table describes how data-source-related triggers behave in the current and remote applications when the corresponding workflow is enabled.
 
 | Trigger | Current application | Remote application | Description |
 | --- | --- | --- | --- |
-| Pre-action event | Triggered | Triggered only in global mode | Global mode is triggered in the current application, and local mode follows button bindings in the current application. After the remote application receives the proxied request, only global mode is triggered |
-| Post-action event | Triggered | Triggered only in global mode | Global mode is triggered in the current application, and local mode follows button bindings in the current application. After the remote application receives the proxied request, only global mode is triggered |
-| Custom action event | Triggered | Not triggered | A Trigger workflow button bound in the current application triggers the local workflow. Proxied CRUD requests do not trigger remote custom action events |
-| Collection event | Not triggered | Triggered | The actual data changes in the remote application. The current application does not trigger local collection events, while the remote application triggers its own collection events |
-| Date field schedule trigger | Not triggered | Triggered | The current application does not trigger based on fields in remote collections. The remote application triggers according to its own date field configuration |
+| Before request event | Triggered | Global mode only | In the current application, global mode is triggered and local mode is triggered according to bindings on current-application buttons. After the remote application receives a proxied request, only global mode is triggered |
+| After request event | Triggered | Global mode only | In the current application, global mode is triggered and local mode is triggered according to bindings on current-application buttons. After the remote application receives a proxied request, only global mode is triggered |
+| Custom action event | Triggered | Not triggered | A **Trigger workflow** button bound in the current application triggers a local workflow. Proxied CRUD requests do not trigger custom action events in the remote application |
+| Collection event | Not triggered | Triggered | Actual data changes in the remote application, so the current application does not trigger local collection events. The remote application triggers its own collection events |
+| Scheduled date-field trigger | Not triggered | Triggered | The current application does not trigger based on remote collection fields. The remote application triggers according to its own date-field configuration |
 
-Triggers that do not depend on data sources are triggered in the current application and the remote application according to their own configurations.
+Triggers that do not depend on a data source are triggered in the current and remote applications according to their own configurations.
 
-To orchestrate workflows that operate on External NocoBase data in the current application, use pre-action events, post-action events, or custom action events. Existing workflows in the remote application run independently in the remote application.
+To orchestrate workflows that operate on External NocoBase data in the current application, use before-request events, after-request events, or custom action events. Existing workflows in the remote application run independently there.
 
 #### Nodes
 
-The following table lists only data-source-related nodes. General nodes such as condition, calculation, loop, and JSON processing do not depend on the data source type and can be used as usual.
+The following table lists only data-source-related nodes. General nodes such as conditions, calculations, loops, and JSON processing do not depend on the data-source type and can be used in ordinary workflows.
 
 | Node | Available | Description |
 | --- | --- | --- |
-| Query records | Available | Query records in the remote application |
-| Create record | Available | Create records in the remote application |
-| Update record | Available | Update records in the remote application |
-| Delete record | Available | Delete records in the remote application |
-| SQL node | Not available | The workflow SQL node supports only database data sources |
-| Aggregate node | Not available | The aggregate node supports only database data sources |
+| Query records | Yes | Queries records in the remote application |
+| Create record | Yes | Creates records in the remote application |
+| Update record | Yes | Updates records in the remote application |
+| Delete record | Yes | Deletes records in the remote application |
+| SQL node | No | Workflow SQL nodes support database data sources only |
+| Aggregate node | No | Aggregate nodes support database data sources only |
 
 ## FAQ
 
-### Collections Do Not Appear
+### Collections do not appear
 
-Check whether the data source is enabled and whether the API URL and API key are correct. The remote application must also allow the API key to access the corresponding collections.
+Check whether the data source is enabled and whether the API address and API key are correct. The remote application must also allow the API key to access the corresponding collections.
 
-### Files Upload Successfully but Cannot Be Previewed
+### File upload succeeds but preview fails
 
-If the current application or the remote application uses local file storage, check whether Origin is the public access address of the corresponding application. Origin should not be the API URL.
+When the current or remote application uses local file storage, check whether Origin is set to the public access address of the corresponding application. Origin must not be the API address.
 
-### The Current Application Has Permission, but the Operation Fails
+### The current application permits the operation, but it fails
 
-Check the API key permissions in the remote application. External NocoBase data sources are affected by permissions in both the current application and the remote application.
+Check the permissions of the API key in the remote application. An External NocoBase data source is affected by both current-application and remote-application permissions.
 
-### Collections Cannot Be Used After a Remote Service Error
+### Collections cannot be used after a remote service failure
 
-If the remote application returns 502, restarts, or is temporarily unavailable, the current application may temporarily fail to read remote collection metadata. After the remote service recovers, the current application automatically reloads metadata the next time this data source's collections are accessed.
+If the remote application returns a 502 error, restarts, or is temporarily unavailable, the current application might temporarily be unable to read remote collection metadata. After the remote service recovers, the current application automatically reloads metadata the next time a collection from the data source is accessed.
 
-### Why Fields Cannot Be Configured in the Current Application
+### Why can't fields be configured in the current application?
 
-External NocoBase data sources use the collection structure and field configuration from the remote application. Adjust fields in the remote application, then reload the collections in the current application.
+An External NocoBase data source uses the collection structure and field configuration of the remote application. Adjust fields in the remote application, then return to the current application and reload collections.

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

@@ -1,24 +1,53 @@
 ---
 pkg: "@nocobase/plugin-data-source-external-oracle"
+title: "External data source - Oracle"
+description: "Learn how to connect Oracle as an external database in NocoBase, including supported versions, plugin installation, Thin and Thick connection modes, Client directory, permissions, and field mapping."
+keywords: "external data source,Oracle,external database,Thin,Thick,Client directory,field mapping,NocoBase"
 ---
 
-# External Data Source - Oracle
+# Oracle
 
 ## Introduction
 
-This plugin allows you to use an external Oracle database as a data source. It supports Oracle versions >= 11g.
+Oracle can be connected to NocoBase as an external database. NocoBase reads tables, fields, and views from Oracle and makes them available as collections in the external data source.
 
-## Installation
+Unlike a [main data source](../main/index.md), the actual schema of an external Oracle 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.
 
-### Install Oracle Client
+| Setting | Description |
+| --- | --- |
+| Supported version | Oracle >= 11g. |
+| Commercial editions | Available in the Enterprise edition. |
+| Plugin | `@nocobase/plugin-data-source-external-oracle`. |
+| Connection mode | Oracle Database 12.1 and later usually use Thin mode. Versions earlier than 12.1 use Thick mode. |
 
-For Oracle server versions earlier than 12.1, you need to install the Oracle client.
+External Oracle is suitable when you need to:
 
+- Connect an Oracle 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
 
-![Oracle Client Installation](https://static-docs.nocobase.com/20241204164359.png)
+:::warning Note
 
+An external Oracle database is not a NocoBase system database. NocoBase does not manage its backups, restores, migrations, or schema changes.
 
-Example for Linux:
+:::
+
+## 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).
+
+When you use Thick mode, install Oracle Client libraries in the NocoBase runtime environment and specify **Client directory** in the data-source settings.
+
+## Install the Oracle client
+
+Oracle Database 12.1 and later usually use Thin mode, which does not require an additional Oracle Client installation. Install Oracle Client libraries in the NocoBase runtime environment only when connecting to a version earlier than Oracle Database 12.1 or when Thick mode is required.
+
+After selecting **Thick** mode in the data-source settings, make sure the machine running the NocoBase service can load Oracle Client.
+
+![Oracle connection mode](https://static-docs.nocobase.com/20241204164359.png)
+
+On Linux, you can install Oracle Instant Client as follows:
 
 ```bash
 apt-get update
@@ -29,12 +58,101 @@ echo /opt/instantclient_19_25 > /etc/ld.so.conf.d/oracle-instantclient.conf
 ldconfig
 ```
 
-If the client is not installed as described above, you will need to specify the path to the client (for more details, refer to the [node-oracledb documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/initialization.html)).
+When Oracle Client is not installed in a system-default loadable location, enter the client library directory in **Client directory**. For the installation above, the directory is `/opt/instantclient_19_25`.
+
+![Configure Client directory](https://static-docs.nocobase.com/20241204165940.png)
+
+:::tip Tip
+
+Configure `Client directory` only in Thick mode. Thin mode does not use this setting. For more initialization rules, see the [node-oracledb initialization documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/initialization.html).
+
+:::
+
+## Add a data source
+
+In **Data source management**, click **Add new**, select Oracle, and then enter the connection details.
+
+![Add an external Oracle data source](https://static-docs.nocobase.com/20241204164359.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 Oracle` or `Finance database`. |
+| Host / Port | The Oracle host address and port. The default port is usually `1521`. |
+| ServerName | The Oracle service name configured for the database listener. |
+| Username / Password | The account credentials used to connect to Oracle. NocoBase reads tables and views under the Owner of this account; it does not grant access to, or read, objects under other Owners. |
+| Connection mode | The Oracle connection mode. Oracle Database 12.1 and later usually use Thin mode. Versions earlier than 12.1 use Thick mode. |
+| Client directory | The directory containing Oracle Client libraries for Oracle Thick mode. Configure it only when Thick mode is selected. |
+| 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 Owner and prefix 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
+
+In Oracle, the connection scope is primarily determined by the Owner of the connection account, `Table prefix`, and **Collections**. If an instance contains many objects, connect with a dedicated account for the business schema to prevent unrelated objects from being added to NocoBase.
+
+:::
+
+## Select collections
+
+After entering connection details, click **Load Collections** to read available tables and views from Oracle. The results depend on the Owner of the connection account, `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 Oracle 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 Oracle contains many objects, narrow the scope through the Owner of the connection account, `Table prefix`, or **Collections** first.
+
+:::
+
+## Synchronize and configure fields
+
+The external Oracle schema is maintained in the database. NocoBase does not create fields, change field types, or delete actual fields in the external database.
+
+When the Oracle 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 Oracle 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 Oracle tables.
+
+## Field type mapping
+
+NocoBase automatically maps Oracle types to appropriate Field types and Field interfaces. You can adjust the display interface in field settings.
+
+| Oracle type | NocoBase Field type | Available Field interfaces |
+| --- | --- | --- |
+| `NUMBER` | `integer`, `float`, `boolean`, `bigInt`, `unixTimestamp`, `sort` | Integer, Number, Sort, Checkbox, Switch, Select, Radio group. |
+| `BINARY_FLOAT`, `BINARY_DOUBLE`, `FLOAT` | `float` | Number, Percent. |
+| `INTEGER`, `SMALLINT`, `PLSQL_INTEGER` | `integer`, `boolean`, `sort` | Integer, Sort, Checkbox, Switch, Select, Radio group. |
+| `CHAR`, `NCHAR`, `VARCHAR2`, `NVARCHAR2` | `string`, `uuid`, `nanoid`, `datetimeNoTz` | Input, Email, Phone, Password, Color, Icon, Select, Radio group, UUID, Nano ID. |
+| `LONG`, `NCLOB` | `string`, `text` | Input, Textarea, Markdown, Vditor, Rich text. |
+| `CLOB` | `string` | Input, Textarea, Rich text. |
+| `DATE` | `datetimeNoTz` | Date, Time, Created at, Updated at. |
+| `TIMESTAMP` | `datetimeNoTz` | Date, Time, Created at, Updated at. |
+| `TIMESTAMP WITH TIME ZONE`, `TIMESTAMP WITH LOCAL TIME ZONE` | `datetimeTz` | Date, Time, Created at, Updated at. |
+| `ROWID`, `UROWID` | `string`, `text`, `integer` | Input, Textarea, Integer. |
+| `JSON` | `json` | JSON. |
+
+:::warning Note
+
+Binary object types such as `BLOB` and `BFILE` are not automatically used as regular file fields. To manage attachments in pages, it is usually better to use a file collection or attachment field in NocoBase to store file metadata.
+
+:::
+
+## 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.
 
-![Oracle Client Path Configuration](https://static-docs.nocobase.com/20241204165940.png)
+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/20260709210948.png)
+![Configure Record unique key](https://static-docs.nocobase.com/20260709211004.png)
 
-## Usage
+## Related links
 
-For detailed instructions, refer to the [Data Source / External Database](/data-sources/data-source-manager/external-database) section.
+- [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.
+- [node-oracledb initialization documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/initialization.html) - How Oracle Client libraries are loaded.