mirror of
https://github.com/imartinez/privateGPT.git
synced 2026-07-17 01:48:03 +00:00
204 lines
6.7 KiB
Plaintext
204 lines
6.7 KiB
Plaintext
---
|
||
title: "Database Tools"
|
||
description: "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.
|
||
</Warning>
|
||
|
||
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
|
||
|
||
<Tabs>
|
||
<Tab title="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.
|
||
</Tab>
|
||
<Tab title="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.
|
||
</Tab>
|
||
<Tab title="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.
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
---
|
||
|
||
## 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.
|