> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/database/create-database.md).

# Create & Configure a Database

MaiAgent's **Database Management** feature lets you centrally manage the database connections used by your AI Assistants on the platform. Combined with the Text to SQL feature, AI Assistants can query database data directly using natural language.

{% hint style="info" %}
For a conceptual introduction to Text to SQL, see: [Text to SQL Feature](/maiagent-user-guide/maiagent-user-guide-en/database/text2sql.md)
{% endhint %}

MaiAgent supports two database types:

* **MaiAgent Database**: Upload Excel / CSV / JSON files and the system automatically creates data tables. Ideal for users without their own database
* **External Database**: Connect to an existing PostgreSQL, MySQL, MSSQL, or Oracle database

## Create a Database

### 1. Go to the Database Management Page

Navigate to the "<mark style="color:blue;">AI Features</mark>" section from the left sidebar and click "<mark style="color:blue;">Database</mark>." The page has two tabs: **MaiAgent Database** and **External Database**.

Click the "<mark style="color:blue;">Add Database</mark>" button in the upper right corner to begin.

{% hint style="info" %}
If the button is grayed out and unclickable, your role has not been granted permission to create databases. Contact your organization administrator to set up permissions.
{% endhint %}

### 2. Select the Database Type

Choose the type of database you want to create by clicking the corresponding card:

* **MaiAgent**: Suitable for uploading spreadsheet files; no connection string required
* **PostgreSQL / MySQL / MSSQL / Oracle**: Connect to an existing external enterprise database

### 3. Fill In Basic Information

#### MaiAgent Database

| Field         | Required | Description                                              |
| ------------- | -------- | -------------------------------------------------------- |
| Database Name | Yes      | e.g., "2024 Annual Sales Data"                           |
| Description   | No       | Additional notes about the database's purpose or content |

{% hint style="info" %}
MaiAgent databases do not require a connection string — the system handles data storage automatically. After creation, upload your spreadsheet files.
{% endhint %}

#### External Database

| Field             | Required | Description                                                           |
| ----------------- | -------- | --------------------------------------------------------------------- |
| Database Name     | Yes      | e.g., "Enterprise ERP Database"                                       |
| Description       | No       | Additional notes about the database's purpose or content              |
| Connection String | Yes      | The database connection URL                                           |
| Specified Tables  | No       | Restrict which tables the AI Assistant can query, separated by commas |

Connection string formats are as follows:

```
PostgreSQL:   postgresql://username:password@host:port/database_name
MySQL:        mysql://username:password@host:port/database_name
MSSQL:        mssql+pymssql://username:password@host:port/database_name
Oracle:       oracle+cx_oracle://username:password@host:port/database_name
```

{% hint style="danger" %}
Make sure the connection string format is correct and includes all required connection information. The database URL must be accessible by the MaiAgent service.
{% endhint %}

After entering the connection string, click the "<mark style="color:blue;">Test Connection</mark>" button to verify the connection:

* **Connection successful**: MaiAgent can access your database normally
* **Connection failed**: Check the connection string format, network connectivity, and whether the database allows external connections

If your database contains a large number of tables, enter the table names you want to expose in the "<mark style="color:blue;">Specified Tables</mark>" field (e.g., `customers, orders, products`) to improve query efficiency and security.

### 4. Set Group Permissions

The final step is to set which groups can access this database. Use the transfer widget to move the groups that need authorization from the left panel to the right panel.

{% hint style="info" %}
If you don't need to set group permissions right now, you can skip this step and adjust it later from the database settings page.
{% endhint %}

### 5. Complete Creation

After confirming all settings, click the "<mark style="color:blue;">Create</mark>" button. Upon successful creation, you will be taken to the database settings page for further configuration.

{% hint style="info" %}
After creation, don't forget to **associate the database with an AI Assistant** so the AI Assistant can use this database for queries. See: [Associate AI Assistants and Group Permissions](/maiagent-user-guide/maiagent-user-guide-en/database/link-chatbots-groups.md)
{% endhint %}

## Upload Files to Create Data Tables (MaiAgent Database)

After creating a MaiAgent database, go to the settings page, switch to the "<mark style="color:blue;">Table Management</mark>" tab, and click the "<mark style="color:blue;">Upload Table File</mark>" button.

### Supported File Formats

| Format | Extensions        | Description                                          |
| ------ | ----------------- | ---------------------------------------------------- |
| Excel  | `.xlsx`, `.xls`   | Each worksheet (Sheet) creates a separate data table |
| CSV    | `.csv`            | Comma-separated values file                          |
| JSON   | `.json`, `.jsonl` | JSON format data file                                |

After uploading, the system automatically parses the file structure and creates data tables in the background. Each data table displays a processing status:

| Status     | Description                                                                    |
| ---------- | ------------------------------------------------------------------------------ |
| Pending    | File has been uploaded, waiting for system processing                          |
| Processing | System is parsing the file and creating the data table                         |
| Completed  | Data table created successfully; the AI Assistant can query it                 |
| Failed     | An error occurred during creation; hover over the error icon to see the reason |

### File Format Guidelines

* [x] The first row must contain **column names**
* [x] **Data types** within each column should be consistent (e.g., the price column should contain only numbers)
* [x] Avoid **merged cells**
* [x] Avoid **duplicate column names**
* [x] Each worksheet (Sheet) in an Excel file should contain only **one table**
* [x] It is recommended to annotate data formats after column names, e.g., `price(int)`, `date(datetime)`

{% hint style="warning" %}
If a data table fails to create, common causes include: incorrect or corrupted file format, special characters in column names, duplicate column names, or inconsistent data types within the same column.
{% endhint %}

## Edit Column Descriptions

Column descriptions are a **critical setting** for improving Text to SQL query accuracy. The AI Assistant references column descriptions to understand the meaning of the data, enabling it to generate more precise SQL queries.

For example, if your data table has a column called `status`, the AI Assistant may not know what it represents. But if you add a description like "Order status, possible values: pending, completed, cancelled," the AI Assistant can correctly understand the column's meaning.

### How to Edit

**MaiAgent Database**: In the "<mark style="color:blue;">Table Management</mark>" tab, click "<mark style="color:blue;">Edit</mark>" on a data table to edit the table description and column descriptions. The dialog shows completion progress (e.g., "3/10 columns have descriptions").

**External Database**: Under the "<mark style="color:blue;">Basic Information</mark>" tab, in the data table list below, click to expand a table and enter descriptions directly in the column description field.

### Writing Tips

{% hint style="info" %}
Good column descriptions can significantly improve AI query accuracy:
{% endhint %}

| Column Name | Poor Description | Better Description                                                                                             |
| ----------- | ---------------- | -------------------------------------------------------------------------------------------------------------- |
| `amt`       | Amount           | Total order amount (NTD), including tax and shipping                                                           |
| `cust_lvl`  | Level            | Customer level. A = VIP customers with annual spending over 1 million, B = annual spending 100K-1M, C = others |
| `reg`       | Region           | Customer geographic region. Possible values: North, Central, South, East, Offshore Islands                     |

## Manage Existing Databases

### Edit a Database

In the database list, click "<mark style="color:blue;">Edit</mark>" in the action menu to enter the settings page.

The settings page contains the following tabs:

| Tab                      | Description                                               | Applicable Type |
| ------------------------ | --------------------------------------------------------- | --------------- |
| Basic Information        | Edit name, description, enabled status, connection string | All             |
| Table Management         | Upload files, manage data tables and column descriptions  | MaiAgent only   |
| Associated AI Assistants | Specify which AI Assistants can use this database         | All             |
| Role Permissions         | Set group access permissions                              | All             |

### Enable / Disable

In the database list, use the "Enable" toggle to quickly switch the status. When disabled, AI Assistants temporarily cannot query this database, but settings and data are preserved.

### Delete a Database

{% hint style="danger" %}
Deleting a database is an irreversible operation.

* **MaiAgent Database**: After deletion, all data tables created by uploading files will also be removed
* **External Database**: Only the connection configuration in MaiAgent is removed; the original database and its data are not affected
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/database/create-database.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.