how-to-guide

How to Configure Timeouts for Chat2DB's SQL Execution Service

July 26, 2026 OtterMind/Chat2DB ↗

Set the timeoutMs field (type Long) on the CliSqlQueryRequest object before sending it to the server; the backend converts this value to seconds and applies it via Statement#setQueryTimeout, with no global configuration required.

Chat2DB's SQL execution flow centers on a CLI-style request object that travels from the client through the web layer to the domain execution service. Understanding how the timeoutMs parameter flows through this pipeline allows you to enforce hard limits on query duration per request.

Understanding the Timeout Mechanism

The timeout configuration in Chat2DB is client-driven and request-scoped. When you initiate a SQL execution, you populate an instance of CliSqlQueryRequest with your desired timeout in milliseconds.

The field is defined in the web API model:

Once received, the CliWebConverter maps this value to the domain-level request object (ai.chat2db.community.domain.api.model.request.cli.CliSqlQueryRequest). The core execution service—typically ai.chat2db.community.domain.core.service.SqlExecuteService—retrieves this value, converts it to seconds, and invokes Statement#setQueryTimeout(seconds) on the JDBC Statement before execution begins.

If timeoutMs is omitted or set to null, the backend does not apply any timeout, allowing the query to run indefinitely until the database or network layer terminates it.

Setting Timeouts via the Java Client

When using the Chat2DB Java client or building a custom integration, instantiate CliSqlQueryRequest and call setTimeoutMs() with your desired duration.

import ai.chat2db.community.web.api.model.request.cli.CliSqlQueryRequest;

// Build the request with a 30-second timeout
CliSqlQueryRequest request = new CliSqlQueryRequest();
request.setDataSourceId(1L);
request.setDatabaseName("test_db");
request.setSql("SELECT * FROM users");
request.setTimeoutMs(30_000L);  // 30 seconds in milliseconds

// Send via REST client (implementation details omitted)

The server aborts the query if execution exceeds 30,000 milliseconds.

Setting Timeouts via the REST API

For direct HTTP integrations, include timeoutMs as a JSON property in your POST request to the CLI SQL endpoint.

curl -X POST http://localhost:10825/api/cli/sql/query \
  -H "Content-Type: application/json" \
  -d '{
        "dataSourceId": 1,
        "databaseName": "test_db",
        "sql": "SELECT * FROM orders",
        "timeoutMs": 60000
      }'

This example sets a 60-second timeout for the specific query.

Setting Timeouts in the Web UI

The Chat2DB Web UI ("SQL Console") exposes this parameter through the interface:

  1. Open the SQL Console panel for your connection.
  2. Locate the Advanced Options section.
  3. Enter the desired duration in milliseconds in the Execution timeout field.
  4. Execute your query.

The UI automatically populates timeoutMs on the underlying CliSqlQueryRequest sent to the backend.

Default Behavior and Edge Cases

Null or omitted values: When timeoutMs is not provided, the execution service skips the setQueryTimeout call entirely. The query runs until completion or until the underlying database connection pool or database server enforces its own limits.

Unit conversion: The execution service handles the conversion from milliseconds to seconds internally when applying the timeout to the JDBC Statement. You should always provide the value in milliseconds to maintain consistency with the API contract.

Key Source Files

Understanding the data flow requires examining these specific files in the OtterMind/Chat2DB repository:

Summary

  • Configuring SQL execution timeouts in Chat2DB is a per-request operation controlled by the timeoutMs field on CliSqlQueryRequest.
  • The value is defined in milliseconds and converted to seconds by the backend execution service.
  • If timeoutMs is null or omitted, no timeout is applied, and queries run until natural completion.
  • The timeout is enforced via standard JDBC Statement#setQueryTimeout, ensuring compatibility with all supported databases.
  • No global configuration property is required; each query carries its own timeout directive.

Frequently Asked Questions

What is the default timeout if I don't specify timeoutMs?

If you omit the timeoutMs field or set it to null, Chat2DB does not apply any query timeout. The statement executes until it completes, fails, or is interrupted by the database server's own connection limits.

Does Chat2DB support global timeout configuration?

No. According to the source code analysis, timeout configuration is strictly request-scoped. There is no global property in application-dev.yml or similar configuration files that sets a default ceiling for all queries. You must specify timeoutMs on each CliSqlQueryRequest.

How does the server handle the conversion from milliseconds to seconds?

The execution service (SqlExecuteService or equivalent in the domain module) retrieves the timeoutMs value from the request object and converts it to seconds before calling Statement#setQueryTimeout(int seconds). This ensures compatibility with the JDBC API while allowing clients to specify precise millisecond-level durations.

Can I set different timeouts for different data sources?

Yes. Since timeoutMs is a property of the individual CliSqlQueryRequest rather than the data source configuration, you can specify different values for every query, regardless of which data source ID you specify in the request. This allows fine-grained control over long-running analytical queries versus fast transactional lookups.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →