@nocobase/plugin-ai 2.3.0-alpha.1 → 3.0.0-alpha.2

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

@@ -0,0 +1,159 @@
+---
+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
+
+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.
+
+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
+
+After activating the plugin, add an External NocoBase data source in **Data source management** and enter the remote application's access information.
+
+| Setting | Description |
+| --- | --- |
+| 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 passed to the remote application, such as space information |
+| Timeout | The request timeout for accessing 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
+
+External NocoBase data sources are affected by permissions in both the current and remote applications.
+
+- 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
+
+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.
+
+:::
+
+## Use collections
+
+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 remote collection structure changes, reload collections in the current application.
+
+## Capabilities
+
+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
+
+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.
+
+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 relation data
+
+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 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 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 address as Origin.
+
+### Import and export
+
+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 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 printing
+
+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
+
+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 also needs permission to access the corresponding data, otherwise the query fails.
+
+#### SQL panel
+
+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, 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 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 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 data-source-related triggers behave in the current and remote applications when the corresponding workflow is enabled.
+
+| Trigger | Current application | Remote application | Description |
+| --- | --- | --- | --- |
+| 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 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 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 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 | 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
+
+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.
+
+### File upload succeeds but preview fails
+
+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 permits the operation, but it fails
+
+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 failure
+
+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 can't fields be configured 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/external/oceanbase.md

@@ -0,0 +1,126 @@
+---
+pkg: "@nocobase/plugin-data-source-oceanbase"
+title: "External data source - OceanBase"
+description: "Learn how to connect OceanBase as an external database in NocoBase, including supported versions, MySQL compatibility mode, connection settings, collection scope, permissions, and field mapping."
+keywords: "external data source,OceanBase,external database,MySQL compatibility mode,field mapping,NocoBase"
+---
+
+# OceanBase
+
+## Introduction
+
+OceanBase can be connected to NocoBase as an external database. NocoBase reads tables, fields, and views from OceanBase 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 OceanBase 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 | OceanBase >= 4.3. |
+| Commercial editions | Available in the Enterprise edition. |
+| Plugin | `@nocobase/plugin-data-source-oceanbase`. |
+| Database mode | Only MySQL compatibility mode is supported. |
+
+External OceanBase is suitable when you need to:
+
+- Connect a business database in an existing OceanBase MySQL tenant
+- 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
+
+OceanBase is supported as an external database only in MySQL compatibility mode. If it uses Oracle 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 OceanBase, and then enter the connection details.
+
+![Add an external OceanBase data source](https://static-docs.nocobase.com/20240507204820.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 `OceanBase business database` or `Reporting database`. |
+| Host / Port | The OceanBase MySQL-compatible connection address and port. Use the port configured for the tenant or proxy. |
+| Database | The name of the OceanBase database to connect to. |
+| Username / Password | The account credentials used to connect to OceanBase. 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 OceanBase 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 OceanBase. 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 OceanBase 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 OceanBase contains many objects, narrow the scope through `Database`, `Table prefix`, or **Collections** first.
+
+:::
+
+## Synchronize and configure fields
+
+The external OceanBase schema is maintained in the database. NocoBase does not create fields, change field types, or delete actual fields in the external database.
+
+When the OceanBase 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 OceanBase 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 OceanBase tables.
+
+## Field type mapping
+
+NocoBase identifies OceanBase types according to MySQL compatibility rules and automatically maps them to appropriate Field types and Field interfaces. You can adjust the display interface in field settings.
+
+| OceanBase 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. |
+| `TEXT` | `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. |
+| `JSON` | `json`, `array` | JSON. |
+
+:::warning Note
+
+Unsupported OceanBase 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/edit_collection.png)
+
+![Configure Record unique key](https://static-docs.nocobase.com/edit_collection_configure.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/oracle.md

@@ -0,0 +1,158 @@
+---
+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"
+---
+
+# Oracle
+
+## Introduction
+
+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.
+
+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.
+
+| 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. |
+
+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
+
+:::warning Note
+
+An external Oracle 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).
+
+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
+apt-get install -y unzip wget libaio1
+wget https://download.oracle.com/otn_software/linux/instantclient/1925000/instantclient-basic-linux.x64-19.25.0.0.0dbru.zip
+unzip instantclient-basic-linux.x64-19.25.0.0.0dbru.zip -d /opt/
+echo /opt/instantclient_19_25 > /etc/ld.so.conf.d/oracle-instantclient.conf
+ldconfig
+```
+
+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.
+
+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)
+
+## 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.
+- [node-oracledb initialization documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/initialization.html) - How Oracle Client libraries are loaded.

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

@@ -0,0 +1,122 @@
+---
+pkg: "@nocobase/plugin-data-source-external-postgres"
+title: "External data source - PostgreSQL"
+description: "Connect PostgreSQL as an external NocoBase database, including version support, plugin installation, connection configuration, Schema, SSL, permissions, and field mapping."
+keywords: "external data source,PostgreSQL,external database,Schema,SSL,field mapping,NocoBase"
+---
+
+# PostgreSQL
+
+## Introduction
+
+PostgreSQL can be connected to NocoBase as an external database. NocoBase reads PostgreSQL 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 continue to maintain the real PostgreSQL schema. NocoBase reads structure, stores field metadata, and configures blocks, permissions, workflows, and APIs.
+
+| Setting | Description |
+| --- | --- |
+| Supported version | PostgreSQL >= 9.5. |
+| Commercial editions | Standard, Professional, and Enterprise. |
+| Plugin | `@nocobase/plugin-data-source-external-postgres`. |
+
+Use external PostgreSQL to connect existing ERP, MES, WMS, or CRM databases; build management pages without migrating historical data; apply permissions, workflows, corrections, or reports to existing tables; and leave schema maintenance to DBAs, migration scripts, or the original system.
+
+:::warning Note
+
+External PostgreSQL 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 PostgreSQL, and enter the connection information.
+
+![Add PostgreSQL](https://static-docs.nocobase.com/20260709204045.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 PostgreSQL or Reporting database. |
+| Host / Port | PostgreSQL server address and port. The usual default port is `5432`. |
+| Database | The PostgreSQL database to connect. |
+| Username / Password | Connection credentials. NocoBase reads only objects that this account is allowed to access; it does not grant access to other users' private objects. |
+| Schema | The PostgreSQL schema to read, such as `public`. When several schemas exist, set only the schema required by the current business use. |
+| Table prefix | Limits reading to matching tables and views, and removes the prefix from the NocoBase collection name. |
+| Collections / Add all collections | Controls the imported scope. With **Add all collections** enabled, NocoBase imports all tables and views in scope; otherwise it imports only selected objects. |
+| Enabled the data source | Disables or enables access through blocks, permissions, workflows, and APIs while keeping the configuration. |
+| SSL options | PostgreSQL SSL settings, including SSL mode, unauthorized-certificate handling, and CA, client-certificate, and client-key paths. |
+
+:::tip Tip
+
+For a database with many objects, narrow the scope with `Schema`, `Table prefix`, and **Collections**. Import only tables and views that the application needs so that permission configuration, page building, and later synchronization remain manageable.
+
+:::
+
+## Select collections
+
+After connection settings are entered, click **Load Collections** to read available PostgreSQL tables and views. Results depend on the connection account, `Schema`, `Table prefix`, and **Collections** settings.
+
+**Add all collections** is enabled by default and imports every table and view in the current scope. Disable it and select individual tables or views when only part of the database is needed.
+
+![Select PostgreSQL collections](https://static-docs.nocobase.com/20260709204309.png)
+
+:::warning Note
+
+One external data source can import at most 500 tables or views. Narrow the scope with `Schema`, `Table prefix`, or **Collections** when PostgreSQL has many objects.
+
+:::
+
+## Synchronize and configure fields
+
+PostgreSQL maintains the external table structure. NocoBase does not create columns, change column types, or delete real fields in external PostgreSQL.
+
+When the PostgreSQL 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 PostgreSQL tables or data.
+
+After synchronization, configure field titles, Field types, and Field interfaces in NocoBase. NocoBase relation fields are relation metadata only and do not automatically add real foreign-key columns to PostgreSQL.
+
+## Field type mapping
+
+NocoBase automatically maps PostgreSQL types to suitable Field types and Field interfaces. You can adjust the display interface in field configuration.
+
+| PostgreSQL type | NocoBase Field type | Available Field interfaces |
+| --- | --- | --- |
+| `BOOLEAN` | `boolean` | Checkbox, Switch. |
+| `SMALLINT`, `INTEGER`, `SERIAL`, `SMALLSERIAL` | `integer`, `boolean`, `sort` | Integer, Sort, Checkbox, Switch, Select, Radio group. |
+| `BIGINT`, `BIGSERIAL` | `bigInt`, `sort` | Integer, Sort, Checkbox, Switch, Select, Radio group, Unix timestamp, Created at, Updated at. |
+| `REAL` | `float` | Number, Percent. |
+| `DOUBLE PRECISION` | `double` | Number, Percent. |
+| `DECIMAL`, `NUMERIC` | `decimal` | Number, Percent, Currency. |
+| `VARCHAR`, `CHAR` | `string`, `password`, `uuid`, `nanoid` | Input, Email, Phone, Password, Color, Icon, Select, Radio group, UUID, Nano ID. |
+| `TEXT` | `text`, `json` | Textarea, Markdown, Vditor, Rich text, URL, JSON. |
+| `UUID` | `uuid` | UUID. |
+| `JSON`, `JSONB` | `json` | JSON. |
+| `TIMESTAMP` | `date` | Date, Time, Created at, Updated at. |
+| `DATE` | `dateOnly` | Date. |
+| `TIME` | `time` | Time. |
+| `POINT`, `LINESTRING`, `POLYGON`, `CIRCLE` | `point`, `lineString`, `polygon`, `circle` | Point, Line string, Polygon, Circle, JSON. |
+| `ARRAY` | `array` | Multiple select, Checkbox group. |
+
+:::warning Note
+
+Unsupported PostgreSQL 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/20260709204742.png)
+![Configure Record unique key](https://static-docs.nocobase.com/20260709204827.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 mapping.