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

package/dist/ai/docs/nocobase/data-sources/file-manager/field-attachment.md

@@ -1,19 +1,113 @@
 ---
-pkg: "@nocobase/plugin-file-manager"
+title: "Attachment"
+description: "The Attachment field uploads files and relates file records to the current business record."
+keywords: "Attachment,attachment,field,Field interface,NocoBase"
 ---
 
-# Attachment Field
+# Attachment
 
 ## Introduction
 
-The attachment field is a specialized relational field that connects directly to the file collection.
+In NocoBase, **Attachment** uploads files and relates file records to the current business record.
 
-## Field Configuration
+It normally relates to a File collection. The file binary is stored by a file-storage engine, while metadata such as file name, size, URL, and MIME type is stored in the File collection. Use Attachment URL for external file links.
 
+## Use cases
 
-![20240512180916](https://static-docs.nocobase.com/20240512180916.png)
+Attachment fields are suitable for these business scenarios:
 
+- Contract attachments
+- Invoice files
+- Product images
+- Files uploaded for business records
 
-## Example
+## Create and configure
 
-(Example to be added)
+On the collection's **Configure fields** page, click **Add field** and select **Attachment** to create this field.
+
+![Configure a Attachment field](https://static-docs.nocobase.com/20251031000729.png)
+
+| Setting | Description |
+| --- | --- |
+| Field interface | The field interface. Attachment uses `attachment`, which determines how the field is entered and displayed in pages. |
+| Field display name | The name displayed for the field, such as `Contract attachments`, `Invoice files`, or `Product images`. Use a name that business users can recognize. |
+| Field name | The field identifier used internally by APIs, relation fields, permissions, and workflows. It usually cannot be changed after creation. It supports only letters, numbers, and underscores, and must begin with a letter. |
+| Field type | The data-layer type. Attachment uses `association` by default. |
+| Default value | The default value. When a new record has no value, NocoBase can fill this value automatically. |
+| Validation rules | Validation rules. Required validation is supported; file count, size, and type are controlled by upload-component or file-storage settings. |
+| Description | A field description. Record the field meaning, entry requirements, data source, or maintainer. |
+
+:::warning Note
+
+Field names are referenced by page blocks, permissions, workflows, and APIs after creation. Confirm the name before creating the field to avoid later configuration changes.
+
+:::
+
+## Field behavior
+
+The default behavior of a Attachment field is as follows:
+
+| Behavior | Description |
+| --- | --- |
+| Default Field interface | `attachment`. |
+| Default Field type | `association`. |
+| Available Field types | A relation field associated with file records. |
+| Page component | Uses an upload component in edit mode. |
+| Filtering | Attachment filtering depends on the relation field and block capabilities. |
+| Sorting | It is usually not used for sorting. |
+| Validation | Required validation is supported; file count, size, and type are controlled by upload-component or file-storage settings. |
+
+## Edit configuration
+
+After creation, click **Edit** beside the field to edit its configuration. Edit fields to adjust how they are displayed and used in NocoBase, such as the display name, description, default value, validation rules, or field-specific settings.
+
+When a field comes from a synchronized main-database table, editing usually maps the database field to a NocoBase Field type and Field interface.
+
+| Setting | Can be edited | Description |
+| --- | --- | --- |
+| Field display name | Yes | Changes the name displayed in the interface without changing the field identifier. |
+| Field name | No | The field identifier normally cannot be changed in the edit form after creation. |
+| Field interface | Conditional | Main-database fields and synchronized fields can be adjusted during field mapping. Changes affect page input, display, and validation. |
+| Field type | Conditional | Main-database fields and synchronized fields can be adjusted during field mapping. Confirm that existing values can be used by the new type first. |
+| Default value | Yes | Adjusts the default value for new records. |
+| Validation rules | Yes | Adjusts field validation rules. |
+| Description | Yes | Adds the field meaning, entry requirements, data source, or maintainer. |
+
+:::warning Note
+
+Changing a Field type or Field interface is more than changing a display name. It affects field storage, input components, validation rules, filters, and workflow-variable usage. When the field contains substantial existing data, confirm that its data format is compatible first.
+
+:::
+
+## Delete field
+
+Click **Delete** beside a Attachment field to delete it. You can also select multiple fields and delete them in the main data source.
+
+Deleting a Attachment field created in the main database usually also deletes the actual database column and its values. For a synchronized or external-data-source field, the impact depends on the corresponding data source and field origin.
+
+:::danger Warning
+
+Deleting a field can affect page blocks, forms, filters, permissions, workflows, APIs, imports and exports, and existing data. Confirm that the field is no longer referenced by business configuration before deleting it.
+
+:::
+
+## Use in pages
+
+Attachment fields are suitable for file upload, preview, and download in business records.
+
+![Use a Attachment field in a page](https://static-docs.nocobase.com/20260709231642.png)
+
+
+| Scenario | Use |
+| --- | --- |
+| Form block | Upload attachments for a business record. |
+| Details block | Display, preview, or download attachments. |
+| Table block | Display attachment values in lists. |
+| Workflows and APIs | Use related file metadata in business logic. |
+
+## Related links
+
+- [Fields](../data-modeling/collection-fields/index.md) - Learn about field categories and mapping.
+- [General collection](../data-source-main/general-collection.md) - Create and manage fields in a collection.
+- [File collection](../file-manager/file-collection.md) - Manage file metadata.
+- [Attachment URL](../field-attachment-url/index.md) - Store external file addresses.

package/dist/ai/docs/nocobase/data-sources/file-manager/file-collection.md

@@ -1,40 +1,127 @@
 ---
-pkg: "@nocobase/plugin-file-manager"
+title: "File collection"
+description: "A File collection stores file titles, names, sizes, MIME types, paths, URLs, preview addresses, storage locations, and extended metadata for use with attachment fields."
+keywords: "File collection,File Collection,attachments,metadata,NocoBase"
 ---
 
-# File Collection
+# File collection
+
+<PluginInfo name="file-manager"></PluginInfo>
 
 ## Introduction
 
-Files are records in a specially structured collection known as a file collection. It is used to store file metadata and can be managed through the File Manager.
+File collections are suitable for file metadata, such as file names, extensions, sizes, MIME types, paths, URLs, preview addresses, storage locations, and custom metadata. The file binary is stored by the file-storage engine; the File collection stores the file metadata.
+
+You can create File collections only from the main data source. External databases, REST API data sources, and External NocoBase data sources do not support creating File collections.
+
+## Use cases
+
+File collections are suitable for these business scenarios:
+
+- Contract attachments, invoice files, and reimbursement receipts
+- Product images, employee certificates, and project documents
+- Files uploaded, previewed, and downloaded from business records
+- Attachment libraries that need independent management of file metadata
+
+## Usage flow
+
+File collections are usually not used directly as main business collections. A common flow is:
+
+1. Create a File collection to store metadata such as file title, file name, size, type, URL, and storage location.
+2. Create a relation field in the business collection and relate it to the File collection. For example, relate a `Contract attachments` File collection to the `Contracts` collection.
+3. Add the relation field to a Form block for the business collection so that users can upload files while creating or editing a business record.
+4. After upload, NocoBase writes file metadata to the File collection and relates the file record to the current business record through the relation field.
+5. Display the attachment field in a Details block, Table block, or List block for the business collection so that users can view, preview, or download files.
+
+## Create and configure
+
+In the main data source, click **Create collection** and select **File collection** to create a File collection.
+
+![Create a File collection](https://static-docs.nocobase.com/20240324090414.png)
+
+File collection settings are mostly the same as those for a general collection. A File collection includes file-metadata fields for storing uploaded file titles, paths, URLs, storage locations, and extended information.
+
+| Setting | Description |
+| --- | --- |
+| Collection display name | The name displayed for the collection, such as `Contract attachments`, `Invoice files`, or `Product images`. |
+| Collection name | The collection identifier used internally by APIs, relation fields, permissions, and workflows. |
+| Categories | Collection categories affect only organization in Data source management; they do not change the collection structure. |
+| Description | A description of the collection. State which files it stores, who uploads them, and which business collections use them. |
+| Preset fields | Preset fields. Keep system fields and File collection built-in fields when creating a File collection. |
+
+### Built-in fields
+
+After a File collection is created, it usually includes the following built-in fields. File binaries are stored in file storage, while the File collection stores this metadata.
+
+| Field | Field name | Description |
+| --- | --- | --- |
+| ID | `id` | The default primary key that uniquely identifies a file record. |
+| Title | `title` | The file title, normally used for display in the interface. |
+| File name | `filename` | The file name. |
+| Extension name | `extname` | The file extension. |
+| Size | `size` | The file size. |
+| MIME type | `mimetype` | The file MIME type. |
+| Path | `path` | The path of the file in storage. |
+| URL | `url` | The file access address. |
+| Preview | `preview` | The file preview address. |
+| Storage | `storage` / `storageId` | The storage to which the file belongs. `storage` is a relation field and `storageId` is its corresponding foreign key. |
+| Meta | `meta` | Extended file metadata. |
+| Created at | `createdAt` | Automatically records when the file record was created. |
+| Created by | `createdBy` | Automatically records the user who uploaded or created the file record. |
+| Updated at | `updatedAt` | Automatically records when the file record was last updated. |
+| Updated by | `updatedBy` | Automatically records the user who last updated the file record. |
+| Space | `space` | Available after enabling the [Multi-space plugin](../../multi-app/multi-space/index.md). It isolates data by space and does not appear when Multi-space is not enabled. |
+
+![File collection built-in fields](https://static-docs.nocobase.com/20240324090527.png)
+
+### Primary key field
+
+Like a general collection, a File collection needs a primary key. Attachment fields and relation fields use the primary key to relate file metadata records.
 
-## User Manual
+If a File collection has no primary key, set **Record unique key** when editing the collection. Otherwise, attachment records might not be related, previewed, or edited correctly.
 
-Creating a File Collection
+## Create a relation
 
+Create a relation field in the business collection and relate it to the File collection.
 
-![20240324090414](https://static-docs.nocobase.com/20240324090414.png)
+![Create a relation to a File collection](https://static-docs.nocobase.com/20240324091529.png)
 
+## Use in pages
 
-Preset Fields in a File Collection
+File collection data is usually created automatically when files are uploaded through attachment interfaces. Use it in Form blocks, Details blocks, or relation blocks.
 
+![Configure an attachment field](https://static-docs.nocobase.com/20260710160424.png)
 
-![20240324090527](https://static-docs.nocobase.com/20240324090527.png)
+![Use a File collection in a page](https://static-docs.nocobase.com/20240324091321.png)
 
+| Configuration location | Use |
+| --- | --- |
+| [Form block](../../interface-builder/blocks/data-blocks/form.md) | Upload attachments in a business-collection record. |
+| [Details block](../../interface-builder/blocks/data-blocks/details.md) | Display, preview, or download attachments. |
+| [Table block](../../interface-builder/blocks/data-blocks/table.md) | Display attachment fields in a list. |
+| [Relation block](../../interface-builder/blocks/data-blocks/table.md) | Manage file records related to the current business record directly. |
 
-Using in Blocks
+## Edit configuration
 
+In the collection list, click **Edit** next to a File collection to change its display name, category, description, simple pagination mode, **Record unique key**, and other settings.
 
-![20240324090848](https://static-docs.nocobase.com/20240324090848.png)
+File metadata fields are normally written automatically during upload. Do not repurpose fields such as `url`, `path`, or `storageId` for other business meanings. To extend file-related business information, add fields such as `File type`, `Project phase`, or `Archived`.
 
+## Delete a collection
 
-Association Field
+In the collection list, click **Delete** next to a File collection to delete it.
 
+Deleting a File collection deletes file-metadata records and related collection metadata. Before deleting it, confirm whether attachment fields and relation fields in business collections, page blocks, permissions, workflows, or APIs still depend on it.
 
-![20240324091529](https://static-docs.nocobase.com/20240324091529.png)
+:::danger Warning
 
+A File collection stores file metadata. Deleting File collection records might invalidate attachment references in business records. Whether file binaries are also deleted depends on the file storage and business configuration. Confirm that files are no longer used by the business before proceeding.
 
-Association Blocks
+:::
 
+## Related links
 
-![20240324091321](https://static-docs.nocobase.com/20240324091321.png)
+- [General collection](../data-source-main/general-collection.md) - General configuration and block usage.
+- [Collection fields](../data-modeling/collection-fields/index.md) - Configure attachment fields and relation fields.
+- [File manager](../../plugins/@nocobase/plugin-file-manager/index.md) - Configure file storage.
+- [Multi-space](../../multi-app/multi-space/index.md) - Learn about the Space field and data isolation by space.

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

@@ -1,53 +1,69 @@
+---
+title: "Data sources overview"
+description: "NocoBase data sources and data modeling: main databases, external databases, REST APIs, external NocoBase, collections, and fields."
+keywords: "data source,data modeling,main database,external database,REST API,external NocoBase,collection,NocoBase"
+---
+
 # Overview
 
-Data modeling is a key step in designing databases, involving a deep analysis and abstraction process of various types of data and their interrelationships in the real world. In this process, we try to reveal the intrinsic connections between data and formalize them into data models, laying the foundation for the database structure of the information system. NocoBase is a platform driven by data models, with the following features:
+Data modeling is a key part of database design. It analyzes and abstracts real-world data and the relationships between it, then describes those relationships as a data model for an information system. NocoBase is data-model driven and provides the following capabilities.
+
+## Connect data from different sources
+
+NocoBase data sources can be common databases, API or SDK platforms, and files.
 
-## Supports Access to Data from Various Sources
+![Data source types](https://static-docs.nocobase.com/20240512085558.png)
 
-NocoBase supports data sources from various origins, including common databases, API/SDK platforms, and files.
+NocoBase provides the [Data Source Manager](./data-source-manager/index.md) to manage data sources and their collections. The manager provides the interface for managing all data sources; it does not connect to a source by itself. Use it together with the applicable data-source plugin.
 
-![20240512085558](https://static-docs.nocobase.com/20240512085558.png)
+Supported data sources include:
 
-NocoBase provides a [data source manager](/data-sources/data-source-manager) for managing various data sources and their collections. The data source manager plugin only provides a management interface for all data sources and does not provide the ability to directly access data sources. It needs to be used in conjunction with various data source plugins. The currently supported data sources include:
+- [Main data source](./data-source-main/index.md): The NocoBase main database. It supports PostgreSQL, MySQL, MariaDB, KingbaseES, and OceanBase.
+- [External PostgreSQL](./data-source-external-postgres/index.md): Connect an existing PostgreSQL database.
+- [External MySQL](./data-source-external-mysql/index.md): Connect an existing MySQL database.
+- [External MariaDB](./data-source-external-mariadb/index.md): Connect an existing MariaDB database.
+- [External MSSQL](./data-source-external-mssql/index.md): Connect an existing SQL Server database.
+- [External KingbaseES](./data-source-kingbase/index.md): Connect an existing KingbaseES database.
+- [External OceanBase](./external/oceanbase.md): Connect an existing OceanBase database.
+- [External Oracle](./data-source-external-oracle/index.md): Connect an existing Oracle database.
+- [External ClickHouse](./external/clickhouse.md): Connect an existing ClickHouse database.
+- [External Doris](./external/doris.md): Connect an existing Doris database.
+- [REST API data source](./data-source-rest-api/index.md): Map a third-party system's REST API to a data source.
+- [External NocoBase data source](./data-source-external-nocobase/index.md): Connect collections from another NocoBase application.
 
-- [Main Database](/data-sources/data-source-main): NocoBase's main database, supporting relational databases such as MySQL, PostgreSQL, and MariaDB.
-- [KingbaseES](/data-sources/data-source-kingbase): Use KingbaseES database as a data source, which can be used as both a main database and an external database.
-- [External MySQL](/data-sources/data-source-external-mysql): Use an external MySQL database as a data source.
-- [External MariaDB](/data-sources/data-source-external-mariadb): Use an external MariaDB database as a data source.
-- [External PostgreSQL](/data-sources/data-source-external-postgres): Use an external PostgreSQL database as a data source.
-- [External MSSQL](/data-sources/data-source-external-mssql): Use an external MSSQL (SQL Server) database as a data source.
-- [External Oracle](/data-sources/data-source-external-oracle): Use an external Oracle database as a data source.
+![Data source management](https://static-docs.nocobase.com/20240512083651.png)
 
-![20240512083651](https://static-docs.nocobase.com/20240512083651.png)
+## Data-modeling tools
 
-## Provides a Variety of Data Modeling Tools
+**A simple collection management interface** lets you create different data models (collections) or connect existing ones.
 
-**Simple collection management interface**: Used to create various models (collections) or connect to existing ones.
+![Collection management](https://static-docs.nocobase.com/20240512090751.png)
 
-![20240512090751](https://static-docs.nocobase.com/20240512090751.png)
+**An ER-diagram-like visual interface** helps extract entities and their relationships from user and business requirements. It gives you a direct way to describe the data model and understand the main data entities in a system and how they are connected.
 
-**ER-style visual interface**: Used to extract entities and their relationships from user and business requirements. It provides an intuitive and easy-to-understand way to describe data models. Through ER diagrams, you can more clearly understand the main data entities in the system and their relationships.
+![Visual data modeling](https://static-docs.nocobase.com/20240410075906.png)
 
-![20240512091042](https://static-docs.nocobase.com/20240410075906.png)
+## Create different collection types
 
-## Supports Various Types of Collections
+| Collection | Description |
+| --- | --- |
+| [General collection](./data-source-main/general-collection.md) | Includes commonly used system fields. |
+| [Calendar collection](./calendar/calendar-collection.md) | Creates event collections for calendars. |
+| [Comment collection](./collection-comment/index.md) | Stores comments or feedback on data. |
+| [Tree collection](./collection-tree/index.md) | Stores hierarchical data. Currently it supports the adjacency-list design. |
+| [File collection](./file-manager/file-collection.md) | Manages file storage. |
+| [Connect a database view](./collection-view/index.md) | Connects an existing database view. |
+| [SQL collection](./collection-sql/index.md) | Presents an SQL query result in a structured form; it is not a real database table. |
+| [Connect external data](./collection-fdw/index.md) | Connects remote data tables through database FDW technology. |
 
-- [General collection](/data-sources/data-source-main/general-collection): Built-in common system fields;
-- [Calendar collection](/data-sources/calendar/calendar-collection): Used to create calendar-related event collections;
-- Comment collection: Used for storing comments or feedback on data;
-- [Tree collection](/data-sources/collection-tree): Tree-structured collection, currently only supports the adjacency list model;
-- [File collection](/data-sources/file-manager/file-collection): Used for file storage management;
-- [SQL collection](/data-sources/collection-sql): Not an actual database collection, but visualizes SQL queries in a structured manner;
-- [Connect to database view](/data-sources/collection-view): Connects to existing database views;
-- Expression collection: Used for dynamic expression scenarios in workflows;
-- [Connect to foreign data](/data-sources/collection-fdw): Allows the database system to directly access and query data in external data sources based on FDW technology.
+![Collection types](https://static-docs.nocobase.com/20240512102212.png)
 
-![20240512102212](https://static-docs.nocobase.com/20240512102212.png)
+For more information, see [Collections](./data-modeling/collection.md).
 
-For more content, see the "[Collection / Overview](/data-sources/data-modeling/collection)" section.
+## Rich field types
 
-## Provides a Rich Variety of Field Types
+NocoBase provides a range of field types for different business data and interface requirements.
 
-![20240512110352](https://static-docs.nocobase.com/20240512110352.png)
+![Field types](https://static-docs.nocobase.com/20240512110352.png)
 
-For more content, see the "[Collection Fields / Overview](/data-sources/data-modeling/collection-fields)" section.
+For more information, see [Collection fields](./data-modeling/collection-fields/index.md).

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

@@ -0,0 +1,130 @@
+---
+title: "Main database"
+description: "The NocoBase main database stores system and business data. It supports MySQL, PostgreSQL, MariaDB, KingbaseES, and OceanBase, table synchronization, and collection creation."
+keywords: "main database,MySQL,PostgreSQL,MariaDB,KingbaseES,OceanBase,table synchronization,NocoBase"
+---
+
+# Main database
+
+## Introduction
+
+The database configured when [deploying NocoBase](/ai/install-nocobase-app) stores NocoBase system tables and can also store application business tables.
+
+| Database | Supported version | Community | Standard | Professional | Enterprise |
+| --- | --- | --- | --- | --- | --- |
+| MySQL | >= 8.0.17 | Yes | Yes | Yes | Yes |
+| PostgreSQL | >= 10 | Yes | Yes | Yes | Yes |
+| MariaDB | >= 10.9 | Yes | Yes | Yes | Yes |
+| KingbaseES | >= V9 | No | No | Yes | Yes |
+| OceanBase | >= 4.3 | No | No | No | Yes |
+
+:::tip Tip
+
+KingbaseES supports only PostgreSQL compatibility mode. OceanBase supports only MySQL compatibility mode.
+
+:::
+
+## Plugin installation
+
+| Database | Plugin | Installation |
+| --- | --- | --- |
+| MySQL | None | Built in; no separate installation is required. |
+| PostgreSQL | None | Built in; no separate installation is required. |
+| MariaDB | None | Built in; no separate installation is required. |
+| KingbaseES | `@nocobase/plugin-data-source-kingbase` | Requires a commercial license and is enabled after installation. |
+| OceanBase | `@nocobase/plugin-data-source-oceanbase` | Requires a commercial license and is enabled after installation. |
+
+## Access the main data source
+
+1. Open the **Data sources** menu.
+2. Select **Main** in the data-source list and click **Configure** to manage the main database.
+
+![Configure the main data source](https://static-docs.nocobase.com/configure_main_datasource.png)
+
+## Main data-source management
+
+The main database manages collections and fields. You can:
+
+- **Filter**: search collections managed by the NocoBase main database.
+- **Create collection**: add a business collection.
+- **Edit**: change business collection metadata.
+- **Delete**: delete a business collection.
+- **Sync from database**: synchronize the structure of an existing database table.
+- **Configure fields**: create, change, and delete collection fields.
+- **+**: create, edit, and delete collection categories from the collection tabs.
+
+![Main data source management](https://static-docs.nocobase.com/main_datasource_management.png)
+
+### Synchronize existing tables from the database
+
+![Synchronize existing tables](https://static-docs.nocobase.com/nocobase_doc-2025-10-29-19-46-34.png)
+
+Synchronizing existing database tables lets you manage them in NocoBase without recreating them.
+
+- **Protect existing investment**: use existing business tables directly.
+- **Flexible integration**: bring in tables created by SQL scripts or database-management tools.
+- **Gradual migration**: migrate an existing system to NocoBase step by step rather than refactoring everything at once.
+
+With **Load from database**, you can:
+
+1. Browse all tables in the database.
+2. Select the tables to synchronize.
+3. Identify table structures and field types automatically.
+4. Import them into NocoBase for management.
+
+### Supported collection types
+
+![Collection types](https://static-docs.nocobase.com/nocobase_doc-2025-10-29-19-47-14.png)
+
+NocoBase supports creating and managing these collection types:
+
+- **General collection**: includes commonly used system fields.
+- **Inheritance collection**: derives child collections from a parent collection. Child collections inherit the parent structure and can define their own fields.
+- **Tree collection**: a hierarchical collection that currently supports the adjacency-list design.
+- **Calendar collection**: stores calendar-related event records.
+- **File collection**: manages file storage.
+- **SQL collection**: presents an SQL query result in a structured form; it is not a real database table.
+- **Database view collection**: connects an existing database view.
+
+### Collection categories
+
+![Collection categories](https://static-docs.nocobase.com/20240322231520.png)
+
+### Rich field types
+
+![Field types](https://static-docs.nocobase.com/nocobase_doc-2025-10-29-19-48-51.png)
+
+#### Flexible field type conversion
+
+NocoBase supports flexible Field interface conversion when the underlying database type is compatible.
+
+For example, a database string field can be presented as:
+
+- **Basic types**: Single line text, Multiline text, Phone, Email, URL, Password, Color, or Icon.
+- **Choice types**: Select or Radio group.
+- **Media types**: Markdown, Markdown (Vditor), Rich text, or Attachment URL.
+- **Date and time types**: Date time with timezone or Date time without timezone.
+- **Advanced types**: Sequence, Collection selector, or Encryption.
+
+This conversion does not change the underlying database storage type. It lets you adjust presentation and interaction as business requirements change while preserving existing data.
+
+### Field-level synchronization
+
+NocoBase can synchronize fields individually as well as synchronize an entire collection.
+
+![Field-level synchronization](https://static-docs.nocobase.com/nocobase_doc-2025-10-29-19-49-56.png)
+
+#### Field synchronization behavior
+
+1. Synchronize newly added fields after the database schema changes.
+2. Select only the fields you need rather than synchronizing every field.
+3. Identify database field types and map them to NocoBase Field types automatically.
+4. Preserve existing data during synchronization.
+
+#### Use cases
+
+- **Database schema evolution**: synchronize fields added for new business requirements.
+- **Team collaboration**: synchronize fields added by another team member or DBA.
+- **Hybrid management**: combine fields managed in NocoBase with fields managed by traditional database tools.
+
+See [Collection fields](../data-modeling/collection-fields/index.md) for details.

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

@@ -0,0 +1,147 @@
+---
+pkg: "@nocobase/plugin-data-source-kingbase"
+title: "Main data source - KingbaseES"
+description: "Learn KingbaseES version support, installation, environment variables, Docker deployment, usage, and field mapping for the NocoBase main database."
+keywords: "main data source,KingbaseES,main database,PostgreSQL compatibility mode,field mapping,NocoBase"
+---
+
+# KingbaseES
+
+## Introduction
+
+KingbaseES can be used as the NocoBase main database. It stores NocoBase system-table data and business data in the main data source. Configure it when deploying NocoBase; it cannot be deleted after the application is running.
+
+To connect an existing KingbaseES database as an external database, see [External KingbaseES](../external/kingbase.md).
+
+| Setting | Description |
+| --- | --- |
+| Supported version | >= V9. |
+| Commercial editions | Professional and Enterprise. |
+| Database type | PostgreSQL compatibility mode. |
+
+:::warning Note
+
+Only KingbaseES databases running in PostgreSQL compatibility mode are supported.
+
+:::
+
+## Installation
+
+### Use as the main database
+
+Follow [Install a NocoBase application](/ai/install-nocobase-app). The main difference is the database environment variables.
+
+#### Environment variables
+
+Add or update these database variables in `.env`:
+
+```bash
+# Adjust DB parameters for your environment.
+DB_DIALECT=kingbase
+DB_HOST=localhost
+DB_PORT=54321
+DB_DATABASE=kingbase
+DB_USER=nocobase
+DB_PASSWORD=nocobase
+```
+
+#### Docker installation
+
+```yml
+networks:
+  nocobase:
+    driver: bridge
+
+services:
+  app:
+    image: registry.cn-shanghai.aliyuncs.com/nocobase/nocobase:latest
+    restart: always
+    networks: [nocobase]
+    depends_on: [kingbase]
+    environment:
+      - APP_KEY=your-secret-key
+      - DB_DIALECT=kingbase
+      - DB_HOST=kingbase
+      - DB_PORT=54321
+      - DB_DATABASE=kingbase
+      - DB_USER=nocobase
+      - DB_PASSWORD=nocobase
+      - TZ=UTC
+    volumes:
+      - ./storage:/app/nocobase/storage
+    ports:
+      - "11000:80"
+
+  kingbase:
+    image: registry.cn-shanghai.aliyuncs.com/nocobase/kingbase:v009r001c001b0030_single_x86
+    platform: linux/amd64
+    restart: always
+    privileged: true
+    networks: [nocobase]
+    volumes:
+      - ./storage/db/kingbase:/home/kingbase/userdata
+    environment:
+      ENABLE_CI: no
+      DB_USER: nocobase
+      DB_PASSWORD: nocobase
+      DB_MODE: pg
+      NEED_START: yes
+    command: ["/usr/sbin/init"]
+```
+
+`APP_KEY` is used for user tokens and similar application secrets. Changing it invalidates existing tokens; use a random value and store it safely. The `kingbase` service is intended only for local evaluation. `DB_MODE` must be `pg`.
+
+#### Install with create-nocobase-app
+
+```bash
+yarn create nocobase-app my-nocobase-app -d kingbase \
+  -e DB_HOST=localhost \
+  -e DB_PORT=54321 \
+  -e DB_DATABASE=kingbase \
+  -e DB_USER=nocobase \
+  -e DB_PASSWORD=nocobase \
+  -e TZ=Asia/Shanghai
+```
+
+### Use as an external database
+
+For configuration entry points, connection parameters, and synchronization rules when using KingbaseES as an external database, see [External KingbaseES](../external/kingbase.md).
+
+## Usage
+
+KingbaseES main data sources use PostgreSQL compatibility mode. For everyday management, see [PostgreSQL main data source](./postgresql.md).
+
+1. Select or enter KingbaseES connection settings when deploying NocoBase.
+2. After NocoBase starts, open **Data source management**, select **Main**, and manage collections and fields.
+3. Use **Sync from database** to connect tables that already exist in the main database.
+4. Use [Collections](../data-modeling/collection.md) and [Collection fields](../data-modeling/collection-fields/index.md) to choose Field types and Field interfaces.
+
+## Field type mapping
+
+When you create a field in NocoBase, NocoBase creates the corresponding KingbaseES field. When you synchronize an existing table, NocoBase applies PostgreSQL-compatible mapping to select a Field type and Field interface.
+
+| 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 shown separately in field configuration. They require development support before they can be used as normal NocoBase fields.
+
+:::
+
+For common configuration, see [Main database](./index.md).