• English

      • MySQL

      Data source: External MySQLStandard Edition+

      Introduction

      MySQL can be connected to NocoBase as an external database. NocoBase reads MySQL tables, fields, and views and uses them as collections in the external data source.

      Unlike the main database, 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.

      SettingDescription
      Supported versionMySQL >= 5.7.
      Commercial editionsStandard, Professional, and Enterprise.
      Plugin@nocobase/plugin-data-source-external-mysql.
      Connection protocolMySQL 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.

      Note

      External MySQL is not the NocoBase system database. NocoBase does not manage its backup, restore, migrations, or schema changes.

      Plugin installation

      This is a commercial plugin. See the commercial plugin activation guide for activation.

      Add a data source

      In Data source management, click Add new, select MySQL, and enter the connection information.

      Add MySQL

      SettingDescription
      Data source nameInternal identifier used by blocks, permissions, workflows, and APIs. It cannot be changed after creation.
      Data source display nameName shown in the interface, such as ERP MySQL or Orders database.
      Host / PortMySQL server address and port. The usual default port is 3306.
      DatabaseThe MySQL database to connect.
      Username / PasswordCredentials used to connect. NocoBase reads only objects that this account can access; it does not grant access to other users' private objects.
      Table prefixLimits reading to matching tables and views, and removes the prefix from the NocoBase collection name.
      Collections / Add all collectionsWith Add all collections enabled, imports all tables and views in scope; otherwise imports only selected objects.
      Enabled the data sourceDisables access through blocks, permissions, workflows, and APIs while keeping the configuration.
      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

      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 typeNocoBase Field typeAvailable Field interfaces
      TINYINT, SMALLINT, MEDIUMINTinteger, boolean, sortInteger, Sort, Checkbox, Switch, Select, Radio group.
      INT, INTEGERinteger, unixTimestamp, sortInteger, Sort, Unix timestamp, Select, Radio group.
      BIGINTbigInt, snowflakeId, unixTimestamp, sortInteger, Sort, Unix timestamp, Created at, Updated at.
      FLOAT, DOUBLEfloatNumber, Percent.
      DECIMALdecimalNumber, Percent, Currency.
      CHAR, VARCHARstring, uuid, nanoid, encryptionInput, Email, Phone, Password, Color, Icon, Select, Radio group, UUID, Nano ID.
      TINYTEXT, TEXT, MEDIUMTEXT, LONGTEXTtextTextarea, Markdown, Vditor, Rich text, URL.
      DATEdateOnlyDate.
      TIMEtimeTime.
      DATETIMEdatetimeNoTz, datetimeTz, dateDate, Time, Created at, Updated at.
      TIMESTAMPdatetimeTz, dateDate, Time, Created at, Updated at.
      YEARstring, integerInput, Integer, Date.
      JSONjson, arrayJSON.
      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 Configure Record unique key