> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipeshub.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MariaDB Toolset
> Query and explore MariaDB databases from your AI agents
MariaDB Toolset
Schema introspection and SQL execution on MariaDB
Ready
Database
## Overview
The MariaDB toolset lets AI agents read schema information and run SQL queries against a MariaDB database. Use it to answer analytical questions, explore table structures, and fetch data in natural language.
### Key Capabilities
* Ask questions about your data in plain English
* Run complex queries, joins, and aggregations across tables
* Explore the database structure and relationships between tables
* Generate reports and summaries from live data
* Download query results as CSV when they are too large to render in chat
***
## Available Tools
| Tool | Description |
| ------------------- | ---------------------------------------------------------------------- |
| `execute_query` | Run a SQL query against the configured MariaDB database |
| `list_tables` | List all tables in the database |
| `fetch_db_schema` | Fetch schema for the database: tables, columns, keys |
| `get_tables_schema` | Fetch schema (columns, primary keys, foreign keys) for specific tables |
| `get_table_ddl` | Get the `CREATE TABLE` statement for a table |
***
## Configuration Guide
If you already have a MariaDB server, skip this step.
### Option A: Docker (recommended for testing)
Run a local MariaDB container:
```bash theme={null}
docker run --name mariadb-test \
-e MARIADB_ROOT_PASSWORD=rootpass \
-e MARIADB_DATABASE=test_db \
-p 3306:3306 \
-d mariadb:latest
```
This starts MariaDB on `localhost:3306` with:
* Username: `root`
* Password: `rootpass`
* Database: `test_db`
### Option B: Install locally
Install MariaDB from the [official MariaDB downloads page](https://mariadb.org/download/) and follow the installer for your OS. After install, start the server and note your `host`, `port`, `username`, and `password`.
### Verify the connection
```bash theme={null}
mysql -h localhost -P 3306 -u root -p
```
Enter your password when prompted. If you reach the `MariaDB [(none)]>` prompt, the server is ready.
Only an admin creates the MariaDB toolset instance. Once created, every user in the workspace can authenticate with their own database credentials.
### Navigate to Actions
1. Click your profile icon and select **Workspace Settings**
2. In the sidebar, click **Actions**
### Find MariaDB and click Setup
Locate the **MariaDB** card in the list of available toolsets and click **+ Setup**.
### Configure the instance
Fill in the action configuration form:
| Field | Description |
| ----------------- | ------------------------------------------------- |
| **Instance name** | A name for this toolset instance (e.g. `MariaDB`) |
| **Host** | MariaDB server host (e.g. `localhost`) |
| **Port** | MariaDB server port (default `3306`) |
| **Database** | Database name |
Click **Create** to save.
The admin only provides connection details (host, port, database). Username and password are entered by each user when they authenticate.
After the admin creates the toolset, every user must authenticate with their own MariaDB username and password before using it.
### Find the MariaDB card
In **Workspace Settings > Actions**, locate the MariaDB card. It will show **1 inactive instance**, meaning the toolset is set up but not yet authenticated for your user.
### Open the MariaDB toolset
Click the card to open it. You will see the instance marked as **Authentication needed**.
### Enter your credentials
Click **Authenticate** and enter your MariaDB **Username** and **Password**, then click **Save credentials**.
Once saved, the toolset status changes to **Authenticated** and is ready to use in agents.
1. Open the **Agent Builder**
2. In the left sidebar, expand **Tools**
3. Drag the **MariaDB** toolset onto the canvas
4. Connect it to your agent
Ask the agent natural-language questions — it will generate SQL, run it, and return results.
***
## FAQ
* **Admin** creates the toolset instance with connection details (host, port, database).
* **Each user** authenticates separately with their own MariaDB username and password.
This way, every user queries the database with their own permissions.
Yes. Use the public host and port of your MariaDB server. Make sure the server allows connections from the PipesHub deployment and that the user account has the required privileges.
Grant the minimum privileges required for your use case. For read-only analytics, `SELECT` on the relevant database is usually enough:
```sql theme={null}
GRANT SELECT ON test_db.* TO 'username'@'%';
```
Yes. An admin can update the instance configuration from **Workspace Settings > Actions**. Users may need to re-authenticate after a change.
***
## Usage Tips
**How do I list all tables?**
Ask the agent "list all tables in the database".
**How do I explore a table's structure?**
Ask "show me the schema for the `orders` table" or "get the CREATE TABLE for `customers`".
**How do I run a query?**
Describe the question in natural language, for example: "what are the top 10 customers by total order value?" — the agent will generate and run the SQL.
**How do I limit the scope of a query?**
Mention a specific table or time range in your question, e.g. "from the `events` table in the last 30 days".
