> 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/agent-builder/database.md).

# Database

## What Is This? <a href="#what-is-this" id="what-is-this"></a>

Database enables Agents to query structured data using natural language. When a user asks "How many laptops did we sell last month?", the Agent automatically converts the question into a SQL query, retrieves the answer from the database, and responds in plain language.

The technical name for this feature is **Text to SQL**.

## When Do You Need It? <a href="#when-do-you-need-it" id="when-do-you-need-it"></a>

When your use case involves:

* **Data queries**: Order status, inventory quantities, sales figures
* **Statistical analysis**: "How much did this quarter's revenue grow compared to last quarter?"
* **Real-time status**: "How many pending tickets are there right now?"

The answers to these questions are stored in structured tables, not in documents, so you need a Database rather than a Knowledge Base.

## What Databases Are Supported? <a href="#supported-databases" id="supported-databases"></a>

| Type                           | Description                                                                                           |
| ------------------------------ | ----------------------------------------------------------------------------------------------------- |
| **MaiAgent Built-in Database** | A database provided by the platform where you can directly upload CSV files or manually create tables |
| **External Database**          | Connect to your PostgreSQL, MySQL, SQL Server, or Oracle                                              |

## Is It Secure? <a href="#is-it-secure" id="is-it-secure"></a>

The Agent only executes **read-only queries** (SELECT) and will not modify or delete your data. You can also restrict which tables and fields the Agent can access.

> **Advanced Note**: The accuracy of Text to SQL depends on how clearly the table structure is defined. It is recommended to add Chinese descriptions to tables and fields to help the Agent understand what each field represents.

## What Do I Need to Do? <a href="#what-do-i-need-to-do" id="what-do-i-need-to-do"></a>

1. **Create a database connection** — Select the database type and configure connection details
2. **Set accessible tables** — Choose which tables the Agent can query
3. **Add field descriptions** — Add descriptions to fields to improve query accuracy
4. **Test queries** — Test whether the Agent can query correctly using natural language
5. **Attach to Agent** — Link to the Agent as a tool

## Further Reading <a href="#further-reading" id="further-reading"></a>

* [Text to SQL Feature](https://github.com/Playma-Co-Ltd/maiagent-user-guide-gitbook/tree/main/en/tools/text2sql.md)
* [Using MaiAgent Knowledge Base for Text to SQL](https://github.com/Playma-Co-Ltd/maiagent-user-guide-gitbook/tree/main/en/tools/text-to-sql-maiagent.md)
* [Using Supabase for Text to SQL](https://github.com/Playma-Co-Ltd/maiagent-user-guide-gitbook/tree/main/en/tools/text-to-sql-supabase.md)


---

# 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/agent-builder/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.