|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +Guidance for Claude Code when working with the QuestDB Java client |
| 4 | +(`java-questdb-client`). |
| 5 | + |
| 6 | +## Project Overview |
| 7 | + |
| 8 | +The standalone client repo for QuestDB ingestion (legacy ILP and QWP). It is |
| 9 | +a Git submodule of the `questdb` repository and ships as the |
| 10 | +`io.questdb:questdb-client` Maven artifact. The module targets Java 11, so |
| 11 | +only legacy Java features are available here — no enhanced switch, no |
| 12 | +multiline strings, no pattern variables in `instanceof`. |
| 13 | + |
| 14 | +## Git & PR Conventions |
| 15 | + |
| 16 | +- **PRs are squash-merged. Commit history on a PR branch is throwaway** — |
| 17 | + only the squashed commit message that lands on the default branch is |
| 18 | + preserved. Do not spend effort tidying the branch's history: no soft |
| 19 | + resets to "commit all at once", no rewording prior commits, no force |
| 20 | + pushes to clean up. Adding a fix-up commit on top is always fine. The |
| 21 | + squash flow folds the lot at merge time anyway. |
| 22 | +- This repo is a submodule of `questdb`. Commit here first, then bump the |
| 23 | + submodule pointer in the parent repo in a separate commit — never push |
| 24 | + a parent-repo submodule pointer that refers to an unpushed client SHA. |
| 25 | + |
| 26 | +## Investigating failures |
| 27 | + |
| 28 | +- **Never dismiss a failure as "pre-existing", "flaky", "unrelated", or "a |
| 29 | + known issue" without actually proving it.** That label is a hypothesis, |
| 30 | + not a conclusion. Treat any red test, red CI job, or surprising log line |
| 31 | + as a live bug to investigate until the evidence — git log, reproduction |
| 32 | + on master, a real timing constraint, an upstream report — forces a |
| 33 | + different conclusion. Only after that proof can the issue be set aside, |
| 34 | + and the proof itself should be reported back so it can be verified. |
| 35 | + |
| 36 | +## Build |
| 37 | + |
| 38 | +Standard Maven build. Targets Java 11: |
| 39 | + |
| 40 | +```bash |
| 41 | +mvn clean install -DskipTests # build + install to local Maven cache |
| 42 | +mvn -pl core test # run client unit tests |
| 43 | +``` |
| 44 | + |
| 45 | +The parent `questdb` repo's `local-client` profile pulls this module as a |
| 46 | +sub-module so server changes can build against unpublished client code; if |
| 47 | +you change client code, install it (or pass `-P local-client` in the parent) |
| 48 | +before running parent-repo tests. |
0 commit comments