Database Query tool

Upcoming release — Zylon 1.58These docs are published ahead of release so you can prepare your API integrations. The release image is not yet available. For installations running 1.57, use the 1.57 documentation.

Use Database Query when you want the assistant to translate natural language into SQL over a configured database connection.

Prerequisites

An API token. See Backoffice Developer Console.
A database connection string you can share with Zylon.

Requirements

Tool spec: { "name": "database_query", "type": "database_query_v1" }
tool_context: one sql_database context with connection_string

Basic request and response

This example validates a request that enables database query. For validation, it sets tool_choice to none so the validator doesn’t try to connect.

curl -X POST "https://{BASE_URL}/api/gpt/v1/messages/validate" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "max_tokens": 128,
    "messages": [
      { "role": "user", "content": "What were total Q1 subscriptions by plan?" }
    ],
    "tools": [
      { "name": "database_query", "type": "database_query_v1" }
    ],
    "tool_choice": { "type": "none" },
    "tool_context": [
      {
        "type": "sql_database",
        "connection_string": "postgresql://{username}:{password}@db.example.com:5432/analytics",
        "schemas": ["public"],
        "ssl": true
      }
    ]
  }'

Example response:

{ "valid": true, "errors": null }

To run the request, send the same body to POST /messages and set tool_choice to { \"type\": \"auto\" }.

Response blocks

Zylon runs this tool on the server. The response contains a server_tool_use block with the call, followed by a server_tool_result block with the result. The call ID starts with srvtoolu_. Don’t send a tool_result back for it.

[
  { "type": "server_tool_use", "id": "srvtoolu_5c6d", "name": "database_query", "input": { "query": "Total Q1 subscriptions by plan" } },
  {
    "type": "server_tool_result",
    "tool_use_id": "srvtoolu_5c6d",
    "content": [{ "type": "text", "text": "Query result: \nplan,subscriptions\nPro,320\nTeam,145" }],
    "is_error": false
  }
]

Error:

{ "type": "server_tool_result", "tool_use_id": "srvtoolu_5c6d", "content": "At least one SQL database artifact is required.", "is_error": true }

is_error is true when the tool fails, and content holds the error message. See Migrating from 1.57 to 1.58 for the full list of server tool blocks.

Tips

Use a read-only database user.
Limit schemas to reduce inspection time.

Next steps

Learn how messages return tool blocks: Messages

First Steps

Build with Zylon

Coding Agents

Database Query tool

Prerequisites

Requirements

Basic request and response

Response blocks

Tips

Next steps

​Prerequisites

​Requirements

​Basic request and response

​Response blocks

​Tips

​Next steps

Prerequisites

Requirements

Basic request and response

Response blocks

Tips

Next steps