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

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.

Database URL format

User name and password go into this URL; there is no separate field for them. X-Database-URL always has the form scheme://user:password@host:port/database, for example:

postgresql://mgpt_reader:PASSWORD@db.example.com:5432/my_db
mssql://mgpt_reader:PASSWORD@db.example.com:1433/my_db

• Scheme: postgres:// or postgresql://, mysql:// or mssql:// (sqlserver:// also works for Microsoft SQL Server). MeinGPT uses it to detect the client unless you set X-Database-Client.
• Port: For Microsoft SQL Server the default is 1433 if you omit the port.
• Special characters: If the user name, password or database name contain special characters, they must be URL-encoded (percent-encoded), for example @ → %40, : → %3A, / → %2F, # → %23, ? → %3F and % → %25. MeinGPT decodes them before connecting.
• Only these parts count for Microsoft SQL Server: host, port, user, password and database from the URL. Additional URL parameters (such as ?encrypt=false) are ignored.

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.

Sharing it with colleagues

The configuration – connection string and headers – belongs to your user account in the respective workspace, not to the assistant.

• Within the assistant you created: Even if you share the assistant via the share icon with colleagues, they do not automatically inherit your database connection. They'll see a "Connect" button on the assistant and need to enter the same connection string themselves, once.
• In their own assistant, or directly in chat: You yourself can reuse your one configured connection as often as you like – in any further assistant, and directly in chat via the connector picker, without re-entering it. This does not extend to colleagues: each person needs their own connector entry. Where the database supports it, set up a separate database user per person with the same restricted rights (see "Restricting access properly" below); that way you can revoke one colleague's access on its own. If that isn't possible, everyone shares one login - changing the password then revokes access for everyone at once.

Unlike OAuth connectors such as SharePoint or Google Workspace (see the connection model), which are authorized once and then usable everywhere, there is currently no way to set up one database connection for the whole organization.

Connecting several databases

The database tool holds exactly one database connection per person and workspace. That one connection applies in all your assistants and in chat; you cannot add a second entry pointing at a different database. There are two routes for several databases:

• One MCP server per database: Run an MCP server that offers SQL access for each database and add each as its own connector (see Custom MCP server). Each entry has its own credentials and can be enabled separately. The server must be reachable from the internet over HTTPS; behind a firewall you need to allow the MeinGPT IP addresses (see IP allowlisting). The workspace setting for allowed connector actions applies only to MeinGPT's built-in connectors, not to your own MCP servers. Limit write access in the MCP server itself or with a database user that can only read.
• Share the database through an Outpost: If the database sits in your own network, you can share it as a service through an Outpost. Each shared database appears as its own connector "via Outpost" (see Services: database, MCP server, HTTP API). This requires the services preview to be enabled for your workspace.

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) 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 on MSSQL cannot be turned off, but it is not enforced. MeinGPT requests an encrypted connection to Microsoft SQL Server (encrypt: true) and accepts any server certificate, including self-signed ones. If the server reports that it does not support encryption, the connection can be established unencrypted. A certificate problem is therefore not a cause of a failed test.
• TLS is not on by default for PostgreSQL. MeinGPT does not enable TLS on its own. Append ?sslmode=require to X-Database-URL to encrypt the connection. The server certificate is then fully verified (chain and hostname), so the server needs a certificate from a publicly trusted certificate authority. ?sslmode=no-verify encrypts without verifying the server's identity.
• 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.

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

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

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?"

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."

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
• Connect databases
• Trust Center