---
title: "Database tool"
description: "Let assistants run SQL queries against your database"
canonical_url: "https://meingpt.com/en/docs/integrations/connectors/mcp-database"
language: en
---

# Database tool

The database tool gives your assistants direct SQL access to a database — for analysis, reporting and questions answered from real data rather than from a knowledge base.

## Overview

The tool ships three methods:

- **`query_database_readonly`** — read queries (`SELECT`, `SHOW`, `DESCRIBE`, `EXPLAIN`, `WITH`) in an enforced read-only session. This is the normal case for analysis.
- **`execute_sql`** — full SQL execution including `INSERT`, `UPDATE`, `DELETE` and DDL. Works **only** when `X-Allow-Write` is set to `true` (default: `false`).
- **`get_database_schema`** — inspect tables and columns before writing a query.

## Supported databases

| Client | Value for `X-Database-Client` |
| --- | --- |
| PostgreSQL | `postgres` |
| MySQL | `mysql` |
| Microsoft SQL Server | `mssql` |

Other systems — SQLite, for instance — are not connected.

## Setup

The database tool is a built-in tool. In the assistant editor you activate it in the **Tools** section and enter its configuration there.

| Key | Required | Meaning |
| --- | --- | --- |
| `X-Database-URL` | yes | Connection string for the target database. Stored as a secret. |
| `X-Database-Client` | no | Set the client explicitly (`postgres`, `mysql`, `mssql`) where it cannot be derived from the URL. |
| `X-Max-Rows` | no | Hard cap on returned rows (default: 5000). |
| `X-Allow-Write` | no | Allow write operations through `execute_sql`. Default: `false`. |

Without `X-Database-URL` every call fails with "Missing database URL". The connection test in the editor lets you check the configuration before the assistant goes live.

## Troubleshooting connection failures

The connection test opens a direct TCP connection to the target database — no proxy or intermediate layer. The most common causes of "connection failed" when the credentials are correct:

- **Only the IP address is allowlisted, not port-forwarded.** A firewall rule for the meinGPT IPs (see [IP allowlisting](/en/docs/integrations/connections-cloud-on-prem/ip-allowlisting)) is not enough on its own — the target port also has to be reachable from outside via NAT/port-forwarding. Test this with a connection attempt from outside your own network, against the exact host and port.
- **MSSQL with a named server instance instead of a fixed port number.** A named SQL Server instance (`SERVER\INSTANCE`) resolves its actual port dynamically via the SQL Server Browser service on UDP 1434. If UDP 1434 isn't reachable, or the Browser service is disabled, resolution fails — use the instance's fixed TCP port directly in the connection URL instead.
- **The database user lacks remote-login rights.** The user in `X-Database-URL` needs explicit permission to connect from outside `localhost` (for MSSQL, that typically means a server login, not just a database-level permission).
- **TLS is always on for MSSQL and cannot be turned off.** The connection to Microsoft SQL Server is always encrypted (`encrypt: true`) with a trusted server certificate — there is no configuration field to disable this. A server that only offers unencrypted TDS, or a self-signed certificate with incompatible parameters, can cause the negotiation to fail.
- **Reverse proxies in front of the database.** An HTTP(S) reverse proxy cannot pass through a raw database wire protocol (PostgreSQL, MySQL, or TDS). Only a plain TCP forward may sit between meinGPT and the database — never a layer-7 proxy.

## What the tool enforces — and what it does not

The tool enforces exactly two things:

- **The read-only split:** `query_database_readonly` rejects anything that does not start with `SELECT`, `SHOW`, `DESCRIBE`, `EXPLAIN`, `PRAGMA` or `WITH`, and sets the session read-only.
- **Limits against runaways:** a 30-second statement timeout and the row cap from `X-Max-Rows`.

Everything else you have to enforce **in the database**. There is no
configuration for permitted schemas, tables or columns — enabling
`X-Allow-Write` allows the assistant every statement the database user is
allowed to run.

## Restricting access properly

Permissions sit with the database user you connect as. Three building blocks cover most cases:

**1. A dedicated user that may only read**

```sql
CREATE USER mgpt_reader WITH PASSWORD 'a-strong-password';
GRANT CONNECT ON DATABASE my_db TO mgpt_reader;
GRANT USAGE ON SCHEMA public TO mgpt_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mgpt_reader;
```

**2. Views instead of raw tables where columns are sensitive**

```sql
CREATE VIEW customer_view AS
SELECT id, name, email, country
FROM customers;
-- excluded: tax_id, bank_details, …
```

**3. Row level security where rows must stay separated per tenant**

That way the restriction holds regardless of which query the assistant writes.

## Examples

**"What were our ten highest-revenue products last quarter?"**

```sql
SELECT p.product_name,
       SUM(s.quantity * s.unit_price) AS revenue,
       COUNT(DISTINCT s.order_id) AS order_count
FROM sales s
JOIN products p ON s.product_id = p.id
WHERE s.order_date >= '2026-01-01'
  AND s.order_date < '2026-04-01'
GROUP BY p.product_name
ORDER BY revenue DESC
LIMIT 10;
```

**"Check the orders table for data quality issues."**

```sql
SELECT COUNT(*) AS total_rows,
       COUNT(*) FILTER (WHERE customer_id IS NULL) AS null_customers,
       COUNT(*) FILTER (WHERE order_date IS NULL) AS null_dates,
       COUNT(*) FILTER (WHERE total_amount < 0) AS negative_amounts
FROM orders;
```

The assistant writes the query, runs it and explains the result. Where structures are unknown it looks at the schema first with `get_database_schema`.

## Recommendations for running it

- **Read-only by default.** Turn `X-Allow-Write` on only where an assistant really has to write — and then with a database user that holds only the rights needed for it.
- **Indexes for the common patterns.** Otherwise the 30-second timeout hits the interesting queries first.
- **Pre-computed views** for recurring analysis, instead of aggregating over raw data every time.
- **Set `X-Max-Rows` deliberately** where tables are large: the default of 5000 rows is a ceiling, not a guideline.

## Read on

- [Tools and connectors overview](/en/docs/integrations/connectors)
- [Connect databases](/en/docs/integrations/databases-overview)
- [Trust Center](/trust-center)