ClickHouse · chernser · Jun 16, 2026 · Jun 16, 2026 · Jun 16, 2026 · Jun 16, 2026
@@ -0,0 +1,78 @@
+---
+name: triage-issues
+description: |
+  Analyzes a single GitHub issue at a time. Reads the description, defines labels and priority, researches additional information, and provides a short but detailed report. Use when the user asks to triage an issue, analyze a bug report, or categorize a GitHub issue.
+disable-model-invocation: true
+---
+
+# Issue Triage Workflow
+
+## Stage 1: Preview
+
+1. Sizes the description into categories: Tiny, Small, Medium, Large. See [Description Sizes in references.md](references.md) for size definitions.
+2. Analyzes based on description size:
+   - **Tiny**: Tries to detect what module is affected. Uses specific terms and method names. JDBC, for example, has very recognizable sets of methods. Remembers or outputs additional information.
+   - **Small or Medium**: Finds what module or functionality is affected and records this information. Small or Medium descriptions just need more technical details.
+   - **Large**: Refines and compacts the issue for further investigation. Large descriptions should have enough data to pinpoint the problem but are often in a form hardly readable by humans, so creates a minimal version.
+3. Checks that there is minimal data available about the problem. See [Minimal Issue Details in references.md](references.md).
+
+## Stage 2: Research
+
+Before exploring the tree, use [source-map.md](source-map.md) to locate the
+affected module and `area:*` labels (module/package boundaries, label → source
+location, entry-point classes, and stacktrace → module heuristics). Only grep
+the source once the map has narrowed the scope.
+
+Every issue type has its own research approach.
+
+### Question
+
+1. Looks up documentation first if there is related information. See [Module Documentation in references.md](references.md).
+2. If the question is about how configuration works - explores source code. See [Module Sources in references.md](references.md).
+3. If the question is about usage then generates a set of questions to get details about the use-case.
+4. Else, notes that this question needs human attention.
+
+### Potential Bug
+
+1. Finds out scope: determines the module, what configuration parameters are involved, and what classes implement the area.
+   1. If there is a stacktrace, adds the call chain of methods for review.
+   2. If there is a specific code example given, looks at what functions are called in what order.
+2. Understands the runtime environment more. Generates questions to discover more.
+   1. If JDBC, then there could be some framework involved. Finds out what the conditions should be.
+   2. If client, then the application environment is important.
+3. When the user provides a data example or use case description, creates a test scenario or code. Keeps code minimal.
+
+### What to ask User
+
+- Asks user about specific version of client or JDBC driver. Asks about specific version of server.
+- Asks about network setup if relevant. For example, issue related network may be affected by proxy in the middle.
+- Asks about reproducibility of the problem if it is network related and looks like have unstable nature.
+
+## Stage 3: Summary
+
+When finishing the analysis, outputs the findings using this exact template:
+~~~
+## Triage Report
+**Effort to Fix**: [Tiny/Small/Medium/Large]
+**Type**: [Question/Bug]
+**Affected Module**: [Module Name]
+### Summary
+[1-2 sentences summarizing the core issue]
+### Recommended Labels & Priority
+- Labels: [label1, label2]
+### Missing Information / Questions for User
+1. [Question 1]
+2. [Question 2]
+### Tests to Add
+
+**Test 1: Scenario**
+```
+// code
+```
+
+
+**Test 2: Scenario**
+```
+// code
+```
+~~~
@@ -0,0 +1,82 @@
+# Description Sizes
+
+**Tiny**
+Problem is described in a few general words and mainly in issue title. For
+example, "getRow() throws exception", "client hangs", "Array serialization broken", etc.
+
+**Small**
+Problem is described with minimal details but there is reference to a project
+or functionality. There can be a single stacktrace.
+
+**Medium**
+Problem is described with enough details and tells what is broken and how
+it should work. There can be additional comments from author.
+
+**Large**
+Problem is described with main details and examples. There is some explanation
+of the usecase. Sometimes there is a link to external demo project.
+
+
+# Minimal Issue Details
+
+- Issue type: potential bug, feature request, chore
+- Affected component: language client or JDBC driver
+- Affected area: core functionality (data codecs, configuration validation, formats), special functionality (subset of core functionality or very specific feature) or general failure.
+
+
+# Module Documentation
+
+External documentation (for human reference only — do NOT fetch these during
+automated triage; rely on the checked-out source under "Module Sources"):
+
+- java client documentation: https://clickhouse.com/docs/integrations/language-clients/java/client
+- JDBC documentation: https://clickhouse.com/docs/integrations/language-clients/java/jdbc
+- JDBC working with date/time values: https://clickhouse.com/docs/integrations/language-clients/java/jdbc_date_time_guide
+
+
+# Module Sources
+
+Local module directories in this checked-out repository (explore these with
+Read/Glob/Grep — do not follow external links):
+
+- client v2: `client-v2/`
+- JDBC v2: `jdbc-v2/`
+- client v1: `clickhouse-http-client/` (also `clickhouse-client/`, `clickhouse-data/`)
+- JDBC v1: `clickhouse-jdbc/`
+
+For a structural map (module/package boundaries, `area:*` label → source
+location, entry-point classes, and stacktrace → module heuristics) use
+[source-map.md](source-map.md). Consult it to locate the affected module/area
+before grepping the tree.
+
+
+# Labels
+
+# Main
+
+* **client-v1**: Use when issue is in old client version. Projects like `clickhouse-client`, `clickhouse-data`, etc.
+* **client-api-v2**: Use when issue is in the new client - `client-v2` project.
+* **jdbc-v1**: Use when issue is in the old JDBC driver - `clickhouse-jdbc` project.
+* **jdbc-v2**: Use when issue is in the new JDBC driver - `jdbc-v2` project.
+* **question**: Use when issue is asking question rather then describing a bug.
+* **investigating**: Use when more investigation is needed and it is not possible to pin point the problem.
+
+# Area
+
+* **`area:client-insert`**: Use when handling data insertion specifically in the ClickHouse client.
+* **`area:client-pojo-serde`**: Use for issues involving the Serialization and Deserialization (SerDe) of Plain Old Java Objects (POJOs).
+* **`area:client-read`**: Use when handling data reading specifically in the ClickHouse client.
+* **`area:data-type`**: Use for issues related to processing or handling different ClickHouse data types.
+* **`area:dependencies`**: Use for pull requests or issues that update, add, or remove a dependency file.
+* **`area:docs`**: Use when documentation is missing, incorrect, or needs updating.
+* **`area:error-handling`**: Use for tracking issues or improvements related to error and exception handling.
+* **`area:format`**: Use for issues handling specific data formats (e.g., JSON, CSV, RowBinary).
+* **`area:general`**: Use for general issues that do not neatly fit into any other specific `area:` category.
+* **`area:integration`**: Use for integration issues with third-party frameworks, tools, or systems.
+* **`area:jdbc-insert`**: Use for handling data insertion issues specifically related to the JDBC driver.
+* **`area:jdbc-metadata`**: Use for issues handling JDBC metadata, such as retrieving the type of a column or database properties.
+* **`area:jdbc-read`**: Use for reading data issues specifically related to the JDBC driver.
+* **`area:network`**: Use for tracking network configuration, connectivity, and I/O-related issues.
+* **`area:old-stmt-parsing`**: Use for issues concerning the parsing logic of older SQL statements.
+* **`area:packaging`**: Use for issues related to project packaging, builds, or distribution artifacts.
+* **`area:sql-parser`**: Use for issues, bugs, or feature requests regarding the custom SQL parser.
@@ -0,0 +1,116 @@
+# Source Map
+
+A structural map of the repository for fast, offline triage. Use it to pick the
+**module label** and **`area:*` labels** and to jump straight to the relevant
+source instead of grepping the whole tree.
+
+Keep this map structural (modules, packages, entry points, label → location).
+Do not add line numbers or exhaustive class lists — they go stale. When a
+mapping below is wrong because the code moved, fix the boundary here.
+
+## Modules at a glance
+
+| Module label | Directory | Root package | What it is |
+| --- | --- | --- | --- |
+| `client-api-v2` | `client-v2/` | `com.clickhouse.client.api` | Current HTTP client (the "v2" client). |
+| `client-v1` | `clickhouse-client/`, `clickhouse-http-client/` | `com.clickhouse.client` (no `.api`) | Legacy v1 client stack. |
+| `client-v1` (data) | `clickhouse-data/` | `com.clickhouse.data` | Shared data types, codecs, formats, streams. Used by v1 and indirectly elsewhere. |
+| `jdbc-v2` | `jdbc-v2/` | `com.clickhouse.jdbc` | Current JDBC driver (built on client-v2). |
+| `jdbc-v1` | `clickhouse-jdbc/` | `com.clickhouse.jdbc` | Legacy JDBC driver (built on client-v1). |
+| (r2dbc) | `clickhouse-r2dbc/` | `com.clickhouse.r2dbc` | R2DBC integration. No dedicated label — use `area:integration`. |
+
+
+## Disambiguating v1 vs v2 (important)
+
+Package prefixes overlap between versions, so use class-name cues:
+
+- **Client v2 vs v1**: v2 lives under `com.clickhouse.client.api.*` and its entry
+  point is `Client` (`client-v2/.../api/Client.java`). v1 lives under
+  `com.clickhouse.client.*` / `com.clickhouse.client.http.*` with no `.api`
+  segment (e.g. `ClickHouseClient`, `ClickHouseHttpClient`).
+- **JDBC v2 vs v1**: both use `com.clickhouse.jdbc`. v2 uses `*Impl` classes
+  (`ConnectionImpl`, `StatementImpl`, `PreparedStatementImpl`, `ResultSetImpl`,
+  `DatabaseMetaDataImpl`, `Driver`, `DataSourceImpl`) under `jdbc-v2/`.
+  v1 uses `ClickHouse*` classes (`ClickHouseConnection`, `ClickHouseStatement`,
+  `ClickHouseDriver`, `ClickHouseDataSource`) under `clickhouse-jdbc/`.
+- If the issue does not say which version, note it as a question for the user,
+  but make a best guess from the class names / JDBC URL / Maven coordinates in
+  the report.
+
+
+## `area:*` label → source location
+
+Use these to attach `area:` labels and to find the implementing code.
+
+- **`area:client-insert`** — `client-v2/.../api/insert/` (`InsertResponse`,
+  `InsertSettings`) and `Client.insert*`. v1: `clickhouse-client`/`http-client`.
+- **`area:client-read`** — `client-v2/.../api/query/` (`QueryResponse`,
+  `QuerySettings`, `GenericRecord`, `Records`) and `Client.query*`.
+- **`area:client-pojo-serde`** — `client-v2/.../api/serde/` (`POJOSerDe`,
+  `POJOFieldSerializer`, `POJOFieldDeserializer`) and
+  `client-v2/.../api/metadata/` matching strategies (`ColumnToMethodMatchingStrategy`).
+- **`area:data-type`** — `clickhouse-data/.../data/` core (`ClickHouseDataType`,
+  `ClickHouseColumn`, `ClickHouseValue(s)`, `value/`) and client-v2
+  `api/data_formats/` readers/writers. jdbc-v2 type wrappers in
+  `jdbc-v2/.../jdbc/types/` (`Array`, `Struct`).
+- **`area:format`** — `clickhouse-data/.../data/format/` (RowBinary, TSV, JSON
+  processors) and `client-v2/.../api/data_formats/` (`RowBinary*FormatReader/Writer`,
+  `NativeFormatReader`). Compression: `clickhouse-data/.../data/compress/`.
+- **`area:network`** — `client-v2/.../api/transport/` (`Endpoint`, `HttpEndpoint`),
+  `api/http/`, connection/config (`ClientConfigProperties`,
+  `ConnectionInitiationException`, `ConnectionReuseStrategy`). v1:
+  `clickhouse-http-client/.../client/http/`.
+- **`area:error-handling`** — exception types across modules: client-v2
+  `ClientException`, `ServerException`, `ClickHouseException`, `ClientFaultCause`,
+  `DataTransferException`; jdbc `SqlExceptionUtils` (v1); data `ClickHouseChecker`.
+- **`area:jdbc-insert`** — `jdbc-v2/.../jdbc/` `PreparedStatementImpl`,
+  `WriterStatementImpl`. v1: `clickhouse-jdbc/.../jdbc/ClickHousePreparedStatement`.
+- **`area:jdbc-read`** — `jdbc-v2/.../jdbc/` `ResultSetImpl`, `StatementImpl`.
+  v1: `ClickHouseResultSet`, `ClickHouseStatement`.
+- **`area:jdbc-metadata`** — `jdbc-v2/.../jdbc/metadata/` (`DatabaseMetaDataImpl`,
+  `ResultSetMetaDataImpl`, `ParameterMetaDataImpl`). v1:
+  `ClickHouseDatabaseMetaData`, `ClickHouseResultSetMetaData`, `JdbcTypeMapping`.
+- **`area:sql-parser`** — new parser in `jdbc-v2/.../jdbc/internal/parser/`
+  (incl. `javacc/`).
+- **`area:old-stmt-parsing`** — legacy parser in
+  `clickhouse-jdbc/.../jdbc/parser/` (`ClickHouseSqlParser`, `ClickHouseSqlUtils`,
+  `ClickHouseSqlStatement`).
+- **`area:integration`** — `clickhouse-r2dbc/`, or third-party framework glue
+  (Spring, Hibernate, etc.) referenced in the issue.
+- **`area:packaging`** — `packages/clickhouse-jdbc-all/`, Maven `pom.xml` build/
+  shading/distribution concerns.
+- **`area:dependencies`** — dependency version bumps in `pom.xml` files.
+- **`area:docs`** — documentation gaps (no code area implied).
+- **`area:general`** — use only when nothing above fits.
+
+
+## Entry points (start reading here)
+
+- **client-v2**: `client-v2/.../api/Client.java` (builder + query/insert API),
+  `ClientConfigProperties` (config keys).
+- **jdbc-v2**: `jdbc-v2/.../jdbc/Driver.java`, `ConnectionImpl`, `StatementImpl`,
+  `DriverProperties`.
+- **client-v1**: `clickhouse-client/.../client/` and
+  `clickhouse-http-client/.../client/http/`.
+- **jdbc-v1**: `clickhouse-jdbc/.../jdbc/ClickHouseConnection.java`,
+  `ClickHouseDriver`.
+- **data**: `clickhouse-data/.../data/ClickHouseDataProcessor`,
+  `ClickHouseColumn`, `format/`.
+
+
+## Stacktrace → module heuristics
+
+Map the top app-owned frames (ignore JDK/third-party frames) by package:
+
+- `com.clickhouse.client.api.*` → **client-api-v2** (then pick area by sub-package:
+  `insert`/`query`/`serde`/`data_formats`/`transport`).
+- `com.clickhouse.client.*` (no `.api`) / `com.clickhouse.client.http.*` →
+  **client-v1**.
+- `com.clickhouse.jdbc.*Impl` or `com.clickhouse.jdbc.internal.parser.*` →
+  **jdbc-v2**.
+- `com.clickhouse.jdbc.ClickHouse*` or `com.clickhouse.jdbc.parser.*` →
+  **jdbc-v1**.
+- `com.clickhouse.data.*` → **clickhouse-data** (shared); attach `area:data-type`
+  / `area:format` / compression by sub-package. Identify the *caller* module to
+  set the module label.
+- `com.clickhouse.r2dbc.*` → r2dbc (`area:integration`).