> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.privategpt.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.privategpt.dev/_mcp/server.

# Database Tools

> Install and configure built-in database query tools.

This page covers installation and server-side configuration for built-in database tools.

Use this together with:

* [Tools](/api-guide/tools) for request examples and runtime usage

---

## Supported database tools

Built-in database tools include:

* `database_query_v1`
* `/v1/tools/database-query`

---

## How to install

### Python extras

Choose the smallest extra that matches your database:

| Database             | Extra                            | Installs                     |
| -------------------- | -------------------------------- | ---------------------------- |
| PostgreSQL           | `private-gpt[database-postgres]` | `psycopg2-binary`, `asyncpg` |
| MySQL                | `private-gpt[database-mysql]`    | `pymysql`                    |
| SQL Server           | `private-gpt[database-mssql]`    | `pyodbc`                     |
| DB2                  | `private-gpt[database-db2]`      | `ibm-db`, `ibm-db-sa`        |
| All database drivers | `private-gpt[database]`          | all of the above             |
| Database tool bundle | `private-gpt[tool-database]`     | `private-gpt[database]`      |

If you only want the database tool itself, `tool-database` is the simplest entry point. If you want a narrower install, use the driver-specific extra directly.

> **Warning**
>
> DB2 support is only available on non-`aarch64` platforms in the current package metadata. On arm64 / Apple Silicon, the `database-db2` extra cannot be installed and DB2 is not supported.

Examples:

```bash
uv sync --extra database-postgres
uv sync --extra database-mysql
uv sync --extra database-mssql
uv sync --extra database-db2
uv sync --extra tool-database
```

`database_query_v1` will also work when you install broader bundles that include database support, such as `private-gpt[database]`, `private-gpt[tool-database]`, `private-gpt[tools]`, or `private-gpt[core]`.

---

### OS libraries required

The Python drivers above need database client libraries from the operating system.

| Database        | What the driver needs             | Notes                                                                                                                     |
| --------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| PostgreSQL      | No extra OS package in most cases | `psycopg2-binary` and `asyncpg` bundle their own client libraries on common platforms.                                    |
| MySQL / MariaDB | MySQL/MariaDB client libraries    | On Debian/Ubuntu the Dockerfile installs `libmariadb3`. On other distros install your MySQL/MariaDB client package.       |
| SQL Server      | Microsoft ODBC driver             | The Docker image installs `msodbcsql18` from Microsoft’s APT repo. Use the matching ODBC driver for your OS.              |
| DB2             | IBM DB2 client libraries          | `ibm-db` uses IBM’s DB2 client; availability varies by platform and architecture. Not available on arm64 / Apple Silicon. |

---

## Install by environment

#### Docker

When you use the published Docker image (`zylonai/private-gpt:latest` and variants), there is nothing extra to install for database tools: the image already contains the Python drivers and required OS libraries for all supported databases.

Only if you are **building your own image from source** do you need to think about extras:

```bash
docker build \
  --build-arg EXTRAS="core tool-database" \
  -t private-gpt-db .
```

This mirrors the official image behavior by:

* Installing the Python extras from the table above (`tool-database` → all `database-*` extras).
* Triggering the Dockerfile logic that installs OS-level libraries (`libmariadb3` for MySQL/MariaDB and `msodbcsql18` for SQL Server).

After that, run the image as usual:

```bash
docker run -p 8080:8080 private-gpt-db
```

You can still pass additional extras via `EXTRAS` if you also need ingestion, media, or other tools.

#### macOS

For local macOS installs, first install PrivateGPT with database support (via `uv` or the package):

```bash
# Example with uv source install
uv sync --frozen --extra core --extra tool-database
```

Then ensure database client libraries are available:

* **PostgreSQL**: Install Postgres (includes client libs), for example:

  ```bash
  brew install postgresql
  ```

* **MySQL / MariaDB** (matches the example setup script):

  ```bash
  brew install mysql pkg-config
  ```

* **SQL Server**: Install the Microsoft ODBC driver for SQL Server, for example:

  ```bash
  brew install unixodbc freetds
  brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
  brew update
  HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18 mssql-tools18
  ```

* **DB2**: (non-arm64 only) Install IBM’s DB2 client for macOS and configure the environment according to IBM’s documentation; `ibm-db` will detect it. DB2 is not available on Apple Silicon.

#### Linux (Debian/Ubuntu)

On Linux, install PrivateGPT with database support (for example with uv):

```bash
uv sync --frozen --extra core --extra tool-database
```

Then install the OS packages for your distribution.

For Debian/Ubuntu-like systems:

* **PostgreSQL**:

  ```bash
  sudo apt update
  sudo apt install postgresql-client
  ```

* **MySQL / MariaDB** (matches the Dockerfile’s `libmariadb3`):

  ```bash
  sudo apt update
  sudo apt install libmariadb3
  ```

* **SQL Server** (same approach as the Dockerfile):

  ```bash
  curl -sSL -O https://packages.microsoft.com/config/debian/12/packages-microsoft-prod.deb
  sudo dpkg -i packages-microsoft-prod.deb
  rm packages-microsoft-prod.deb
  sudo apt update
  sudo ACCEPT_EULA=Y apt install msodbcsql18
  ```

* **DB2** (non-arm64 only):

  Install IBM’s DB2 client packages for your distribution and architecture, then configure as documented by IBM. The `database-db2` extra is only published for non-`aarch64` platforms and is not available on arm64.

After installing both the Python extras and the OS libraries, restart the server and `database_query_v1` will be able to connect to your configured databases.

---

## Settings reference

Database query does not have a global `enabled` flag in `settings.yaml`. Instead, the server uses runtime limits from `database_query`, and each request provides the target database through a `sql_database` artifact.

```yaml
database_query:
  timeout_seconds: 1000
  batch_size: 1000
  max_mb_result: 150
```

---

### Settings

| Setting                          | Description                                               |
| -------------------------------- | --------------------------------------------------------- |
| `database_query.timeout_seconds` | Maximum time allowed for a database query.                |
| `database_query.batch_size`      | Number of rows processed per batch.                       |
| `database_query.max_mb_result`   | Maximum response size in MB before truncation or failure. |

---

### Runtime requirement

The database connection is not configured globally in `settings.yaml`. Pass it in the request as a `sql_database` artifact.

See [Tools](/api-guide/tools) for Messages API and standalone tool endpoint examples.