# How to Configure Timeouts for Chat2DB's SQL Execution Service

> Configure Chat2DB SQL execution timeouts easily by setting the timeoutMs field in CliSqlQueryRequest. Learn how to prevent long-running queries without global config.

- Repository: [OtterMind/Chat2DB](https://github.com/OtterMind/Chat2DB)
- Tags: how-to-guide
- Published: 2026-07-26

---

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

- **Field**: `timeoutMs` (type `Long`)
- **Unit**: Milliseconds
- **Location**: [`chat2db-community-web/src/main/java/ai/chat2db/community/web/api/model/request/cli/CliSqlQueryRequest.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-web/src/main/java/ai/chat2db/community/web/api/model/request/cli/CliSqlQueryRequest.java)

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.

```java
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.

```bash
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:

- **[`CliSqlQueryRequest.java`](https://github.com/OtterMind/Chat2DB/blob/main/CliSqlQueryRequest.java)**: [`chat2db-community-web/src/main/java/ai/chat2db/community/web/api/model/request/cli/CliSqlQueryRequest.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-web/src/main/java/ai/chat2db/community/web/api/model/request/cli/CliSqlQueryRequest.java) — Defines the `timeoutMs` field available to clients.

- **[`CliWebConverter.java`](https://github.com/OtterMind/Chat2DB/blob/main/CliWebConverter.java)**: [`chat2db-community-web/src/main/java/ai/chat2db/community/web/api/converter/cli/CliWebConverter.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-web/src/main/java/ai/chat2db/community/web/api/converter/cli/CliWebConverter.java) — Transfers `timeoutMs` from the web request to the domain request object.

- **Domain request model**: `ai.chat2db.community.domain.api.model.request.cli.CliSqlQueryRequest` — The internal representation used by the execution service.

- **Execution service**: `ai.chat2db.community.domain.core.service.SqlExecuteService` (or equivalent in the domain module) — Reads the timeout and applies it to the JDBC statement.

## 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`](https://github.com/OtterMind/Chat2DB/blob/main/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.