Create and Configure a Database

This guide explains how to create and configure databases in MaiAgent, including creating tables by uploading files, connecting to external databases, and setting column descriptions

MaiAgent's Database Management feature lets you centrally manage the database connections used by AI assistants on the platform. With Text to SQL, AI assistants can query data in a database directly using natural language.

For an introduction to Text to SQL, see Text to SQL Feature.

MaiAgent supports two types of databases:

• MaiAgent Database: Upload an Excel / CSV / JSON file, and the system automatically creates a table. Suitable for users who do not have their own database

• External Database: Connect to an existing PostgreSQL, MySQL, SQL Server (MSSQL), Oracle, or SynxDB database

Create a Database

1. Open the Database Management Page

From the left navigation bar, open AI Features and click Database. The page has two tabs: MaiAgent Database and External Database.

Click Add Database in the upper right to begin.

Database management page showing the MaiAgent database list

If the button is grayed out and cannot be clicked, your role has not been granted permission to create databases. Contact your organization administrator to set up the permission.

2. Select a Database Type

Select the type of database you want to create. Click its card, then click Next:

• MaiAgent Database: For uploading spreadsheet files; no connection string is required

• PostgreSQL / MySQL / SQL Server / Oracle / SynxDB: Connect to an existing external enterprise database

Step 1: Select a database type

3. Enter Basic Information

MaiAgent Database

Field	Required	Description
Database name	Yes	For example, "2024 sales data"
Description	No	Additional details about the database's purpose or contents

A MaiAgent Database does not require a connection string; the system handles data storage automatically. After creating it, upload a spreadsheet file.

Step 2: MaiAgent Database settings

External Database

Field	Required	Description
Database name	Yes	For example, "Enterprise ERP database"
Description	No	Additional details about the database's purpose or contents
Connection string	Yes	The database connection URL
Specify tables	No	Limit the tables that AI assistants can query; separate table names with commas

The connection string formats are shown below (the format for the selected database type also appears below the field):

PostgreSQL:   postgresql://username:password@host:port/database_name
MySQL:        mysql+pymysql://username:password@host:port/database_name
SQL Server:   mssql+pyodbc://username:password@host:port/database_name?driver=ODBC+Driver+18+for+SQL+Server&TrustServerCertificate=yes&Encrypt=no
Oracle:       oracle+oracledb://username:password@host:port/?service_name=service_name
SynxDB:       postgresql://username:password@host:port/database_name

Make sure the connection string has the correct format and contains all required connection information. Its prefix must match the format above; otherwise, an "Invalid connection string format" message appears and you cannot continue to the next step. Also make sure the database URL is accessible to MaiAgent services.

Step 2: External database (PostgreSQL) settings

After entering the connection string, click Test Connection to check the connection (or skip the test and save directly):

• Connection successful: MaiAgent can access your database

• Connection failed: Check the connection string format, network connectivity, and whether the database allows external connections

If your database has many tables, enter the names of the tables you want to make available (for example, customers, orders, products) in Specify Tables to improve query efficiency and security. Leave this field blank to allow queries across all tables.

4. Configure Role Permissions

The final step is to choose which roles can access the database. Select one option under Quick Select Permission Scope:

• All Roles: Allow members with any role in the organization to use this database

• Exclude Default Roles: Allow only custom roles; exclude default roles

• Select Roles: Choose specific roles manually by moving roles you want to authorize from Available Roles to Selected Roles

Step 3: Quickly select the permission scope

If you do not need to configure role permissions yet, skip this step. You can adjust them later on the Role Permissions tab of the database settings page.

5. Finish Creating the Database

After reviewing the settings, click Create Database (MaiAgent Database) or Save (external database). Once the database is created, its settings page opens for further configuration.

New databases are disabled by default. On the Basic Information tab, turn on Enable Database and save, or toggle Enable in the database list. AI assistants can then use this database for Text to SQL queries.

After creating the database, remember to link it to an AI assistant so the assistant can query it. See Link AI Assistants and Group Permissions.

Upload a File to Create a Table (MaiAgent Database)

After creating a MaiAgent Database, open its settings page and switch to the Table Management tab. Click Upload Table File, select a file or drag one into the upload area, and then click Upload.

Table Management tab, with tables grouped by source file

Supported File Formats

Format	Extension	Description
Excel	.xlsx, .xls	Creates a separate table for each worksheet (Sheet)
CSV	.csv	Comma-separated values file
JSON	.json, .jsonl	JSON data file

After upload, the system parses the file structure and creates tables in the background. Tables are grouped by source file and display their processing status:

Status	Description
Pending	The file has been uploaded and is waiting to be processed
Processing	The system is parsing the file and creating tables
Success	The table has been created and AI assistants can query it
Failed	An error occurred during creation; hover over the error icon to see the reason

File Format Notes

• The first row must contain column names

• Each column must have a consistent data type (for example, all values in a price column should be numbers)

• Avoid merged cells

• Avoid duplicate column names

• Each worksheet (Sheet) in an Excel file must contain only one table

Common reasons a table fails to be created include an invalid or damaged file, special characters in column names, duplicate column names, or inconsistent data types within a column.

Edit Column Descriptions

Column descriptions are a key setting for improving the accuracy of Text to SQL queries. AI assistants use them to understand what the data means and generate more accurate SQL queries.

For example, a table may have a column named status without explaining what it represents. Adding a description such as "Order status; possible values: pending (awaiting processing), completed (finished), cancelled (canceled)" helps the AI assistant interpret the column correctly.

How to Edit

MaiAgent Database: On the Table Management tab, click the Edit icon in the table's Actions column. In the Edit Table Information window, enter a Table Description and a Column Description for each column, then click Save. The window shows your progress (for example, "3 / 10 columns configured").

Edit Table Information: Enter table and column descriptions

External Database: In the Table Structure Description section below the Basic Information tab, click Add Table, enter the Table Name and Column and Purpose Description, then click Save.

Writing Tips

Good column descriptions can significantly improve the accuracy of AI queries:

Column Name	Less Helpful Description	Better Description
amt	Amount	Total order amount (NTD), including tax and shipping
cust_lvl	Level	Customer level: A for VIP customers spending over 1 million per year, B for annual spending of 100,000–1 million, C for others
reg	Region	Customer's geographic region; possible values: north, central, south, east, offshore islands

Manage Existing Databases

Edit a Database

In the database list, click the Edit icon in the Actions column to open the settings page.

Database settings page: Basic Information tab

The settings page contains these tabs:

Tab	Description	Applies To
Basic Information	Edit the name, description, and enabled status; for external databases, also change the connection string, specified tables, and table structure descriptions	All databases
Table Management	Upload files and manage tables and column descriptions	MaiAgent Database only
Linked AI Assistants	Specify which AI assistants can use this database	All databases
Role Permissions	Configure access permissions for roles	All databases

For security, passwords in external database connection strings are masked. To change one, click Change and enter the complete new connection string.

Enable / Disable

In the database list, use the Enable switch to change the status quickly. When disabled, AI assistants temporarily cannot query the database, but its settings and data are retained.

Delete a Database

Deleting a database cannot be undone.

• MaiAgent Database: Also deletes all tables created from uploaded files

• External Database: Removes only the connection settings in MaiAgent; the data in the original database is unaffected