Built-in Tools

Database Tools

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

Use this together with:

  • 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:

DatabaseExtraInstalls
PostgreSQLprivate-gpt[database-postgres]psycopg2-binary, asyncpg
MySQLprivate-gpt[database-mysql]pymysql
SQL Serverprivate-gpt[database-mssql]pyodbc
DB2private-gpt[database-db2]ibm-db, ibm-db-sa
All database driversprivate-gpt[database]all of the above
Database tool bundleprivate-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.

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:

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

DatabaseWhat the driver needsNotes
PostgreSQLNo extra OS package in most casespsycopg2-binary and asyncpg bundle their own client libraries on common platforms.
MySQL / MariaDBMySQL/MariaDB client librariesOn Debian/Ubuntu the Dockerfile installs libmariadb3. On other distros install your MySQL/MariaDB client package.
SQL ServerMicrosoft ODBC driverThe Docker image installs msodbcsql18 from Microsoft’s APT repo. Use the matching ODBC driver for your OS.
DB2IBM DB2 client librariesibm-db uses IBM’s DB2 client; availability varies by platform and architecture. Not available on arm64 / Apple Silicon.

Install by environment

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:

$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:

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

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.

1database_query:
2  timeout_seconds: 1000
3  batch_size: 1000
4  max_mb_result: 150

Settings

SettingDescription
database_query.timeout_secondsMaximum time allowed for a database query.
database_query.batch_sizeNumber of rows processed per batch.
database_query.max_mb_resultMaximum 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 for Messages API and standalone tool endpoint examples.