From d5a151e5606c1cf4acf317fd74d8813f4be50400 Mon Sep 17 00:00:00 2001 From: kirl Date: Thu, 12 Nov 2026 21:32:29 +0000 Subject: [PATCH 1/3] chore(bigquery-jdbc): add testing skills --- .../skills/bigquery-jdbc-testing/SKILL.md | 127 ++++++++++++++++++ .../.claude/skills/bigquery-jdbc-testing | 1 + .../.gemini/skills/bigquery-jdbc-testing | 1 + java-bigquery-jdbc/.gitignore | 4 - 4 files changed, 129 insertions(+), 4 deletions(-) create mode 100644 java-bigquery-jdbc/.agents/skills/bigquery-jdbc-testing/SKILL.md create mode 120000 java-bigquery-jdbc/.claude/skills/bigquery-jdbc-testing create mode 120000 java-bigquery-jdbc/.gemini/skills/bigquery-jdbc-testing diff --git a/java-bigquery-jdbc/.agents/skills/bigquery-jdbc-testing/SKILL.md b/java-bigquery-jdbc/.agents/skills/bigquery-jdbc-testing/SKILL.md new file mode 100644 index 000000000000..12f1fee4873a --- /dev/null +++ b/java-bigquery-jdbc/.agents/skills/bigquery-jdbc-testing/SKILL.md @@ -0,0 +1,127 @@ +--- +name: bigquery-jdbc-testing +description: Conventions for writing and refactoring unit and integration tests in the BigQuery JDBC driver (java-bigquery-jdbc). Use this skill when adding, reviewing, or cleaning up tests under java-bigquery-jdbc/src/test, including tests for connection/credential setup, Storage Read/Write API clients, TPC/universe-domain behavior, and ITBase-derived integration tests. +--- + +# BigQuery JDBC Driver: Writing Tests + +Applies to `java-bigquery-jdbc/src/test/java/com/google/cloud/bigquery/jdbc/**`. + +- **Unit tests** live in `com.google.cloud.bigquery.jdbc` and extend + `BigQueryJdbcBaseTest` (directly or through `BigQueryJdbcLoggingBaseTest`). +- **Integration tests** live in `com.google.cloud.bigquery.jdbc.it`, are named + `IT*`, and extend `ITBase`. + +Aim for tests that are short and read top to bottom: setup comes from shared +fixtures, the test body holds only what is specific to the case, and repeated +assertions live in one helper. + +## 1. Reuse existing fixtures. Don't hand-roll them + +Before writing setup code, check `BigQueryJdbcBaseTest`, +`BigQueryJdbcLoggingBaseTest`, `utils/TestUtilities`, and `utils/URIBuilder`. + +| Need | Use | Avoid | +| --- | --- | --- | +| A private key / PEM string | `fake_pkcs8_key` | `KeyPairGenerator`, Base64 encoding, building `-----BEGIN PRIVATE KEY-----` by hand | +| A service-account connection URL | `getUriOAuthServiceAccount()` | Building `jdbc:bigquery://...;OAuthType=0;...` by string concatenation | +| Other auth types | `getUriOAuthUserAccount()`, `getUriOAuthToken()`, `getUriOAuthApplicationDefault()`, `getUriOAuthExternal()` | Copy-pasting URL fragments | +| Extra URL properties | `.append("Key", value)` on the `URIBuilder`, then `.toString()` | Manual `";"` handling | + +Example: + +```java +String url = + getUriOAuthServiceAccount() + .append("ProjectId", "project") + .append("universeDomain", TPC_UNIVERSE) + .toString(); +``` + +If a fixture you need doesn't exist and more than one test would use it, add it +to the base class instead of keeping a private copy in one test file. + +## 2. Pull repeated assertions into a helper + +When a test asserts the same thing for two or more objects (for example the +Storage **Read** and **Write** clients, or the Arrow and JSON result sets), move +the assertions into one `private static` helper that takes the varying parts +(credentials, endpoint URI, expected scopes, expected universe) as parameters. +Each test then makes one call per object. + +```java +assertStorageCredentialsScoped( + readClient.getSettings().getCredentialsProvider().getCredentials(), + TPC_UNIVERSE, TPC_READ_URI, BigQueryReadSettings.getDefaultServiceScopes()); +assertStorageCredentialsScoped( + writeClient.getSettings().getCredentialsProvider().getCredentials(), + TPC_UNIVERSE, TPC_WRITE_URI, BigQueryWriteSettings.getDefaultServiceScopes()); +``` + +Put repeated literals (universe domains, endpoint URIs, scope lists) in +`private static final` constants at the top of the test class. + +## 3. Cover every branch of the code under test + +For each conditional in the production change, write at least one test that +takes each side. In particular: + +- **Credential type.** If the code special-cases `ServiceAccountCredentials` or + `GoogleCredentials`, also test a credential that is *not* a service account, + such as `getUriOAuthToken()` / `GoogleCredentials.create(AccessToken)`. Check + that it passes through unchanged (`assertSame` where possible). +- **Universe domain.** If the code behaves differently for TPC + (`universeDomain=apis-tpczero.goog`), also test the **default** universe (no + `universeDomain` property, so `googleapis.com`). +- **Already configured input.** For example, credentials that already have + explicit scopes must keep them. + +When you are asked to *refactor* tests, keep coverage the same: every assertion +the old tests made must still be made, possibly through a helper. Don't drop +cases or weaken assertions (for example, changing `assertEquals` to +`assertNotNull`). + +## 4. Integration tests: shared pieces belong in `ITBase` + +- If more than one `IT*` class uses the same query template or check, define it + once in `ITBase` as a `public static final` constant or a `protected`/`public + static` helper. Don't redefine it per class or inline the literal. Current + shared pieces: + - `GENERATE_ARRAY_QUERY` = `"SELECT * FROM UNNEST(GENERATE_ARRAY(1, %s));"`, + used with `String.format(GENERATE_ARRAY_QUERY, n)`. + - `assertArrowResultSet(ResultSet)`, which checks that the High-Throughput + (Storage Read) API path was taken. + - `resultSetRowCount(ResultSet)` and `validateStatement(...)`. +- Don't shadow `ITBase` members with a same-named `private static final` field + that means something else (for example a class-local `BASE_QUERY` that is a + different query). +- Use try-with-resources for `Connection`, `Statement`, and `ResultSet`, or close + them explicitly. IT suites share quotas. +- `@Tag("disable_tpc")` excludes a test from TPC runs. Remove it only when the + feature is known to work against TPC, and in that case add an assertion that + proves the intended path was used (for example `assertArrowResultSet`). + +## 5. Style and verification + +- Follow the repo `AGENTS.md`: least visibility (`private static` helpers), + short names over fully qualified names, no `@Deprecated`/`@ObsoleteApi` + calls, and no unrelated formatting changes. +- Remove imports that the refactor makes unused (for example `KeyPairGenerator`, + `PrivateKey`, `Base64`). +- Run the formatter from `java-bigquery-jdbc/`: + ```bash + make lint # mvn com.spotify.fmt:fmt-maven-plugin:format + ``` + If the formatter fails with `NoSuchMethodError`, your JDK is too new for + google-java-format. Run it under an older JDK, for example + `JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 make lint`. +- Run the affected unit tests: + ```bash + make unittest test=BigQueryConnectionTest + make unittest test='BigQueryConnectionTest#testReadAndWrite*' + ``` +- Integration tests need real credentials (`GOOGLE_APPLICATION_CREDENTIALS`). + If they can't run locally, at least compile them: + ```bash + mvn -q -Denforcer.skip=true -Dclirr.skip=true test-compile + ``` diff --git a/java-bigquery-jdbc/.claude/skills/bigquery-jdbc-testing b/java-bigquery-jdbc/.claude/skills/bigquery-jdbc-testing new file mode 120000 index 000000000000..dffed6f65a1d --- /dev/null +++ b/java-bigquery-jdbc/.claude/skills/bigquery-jdbc-testing @@ -0,0 +1 @@ +../../.agents/skills/bigquery-jdbc-testing \ No newline at end of file diff --git a/java-bigquery-jdbc/.gemini/skills/bigquery-jdbc-testing b/java-bigquery-jdbc/.gemini/skills/bigquery-jdbc-testing new file mode 120000 index 000000000000..dffed6f65a1d --- /dev/null +++ b/java-bigquery-jdbc/.gemini/skills/bigquery-jdbc-testing @@ -0,0 +1 @@ +../../.agents/skills/bigquery-jdbc-testing \ No newline at end of file diff --git a/java-bigquery-jdbc/.gitignore b/java-bigquery-jdbc/.gitignore index b919e39bbe0f..eb60678e7791 100644 --- a/java-bigquery-jdbc/.gitignore +++ b/java-bigquery-jdbc/.gitignore @@ -3,7 +3,6 @@ target-it/** **/*logs*/** **/ITBigQueryJDBCLocalTest.java **/BigQueryStatementE2EBenchmark.java -.agents/ tools/**/*.class tools/**/drivers/** @@ -11,6 +10,3 @@ tools/**/logs/** tools/**/*.jfr tools/**/odbc/ tools/**/native_odbc_perf - -# Gemini/Jetski agent custom skills -.agents/ \ No newline at end of file From 03b49fef16521870168c869a8c89b061222f54f2 Mon Sep 17 00:00:00 2001 From: kirl Date: Thu, 12 Nov 2026 22:48:08 +0000 Subject: [PATCH 2/3] chore(bigquery-jdbc): add prepare-pr skill; share skills via .agents/skills --- .../.agents/skills/prepare-pr/SKILL.md | 189 ++++++++++++++++++ java-bigquery-jdbc/.claude/skills | 1 + .../.claude/skills/bigquery-jdbc-testing | 1 - .../.gemini/skills/bigquery-jdbc-testing | 1 - java-bigquery-jdbc/.gitignore | 4 + 5 files changed, 194 insertions(+), 2 deletions(-) create mode 100644 java-bigquery-jdbc/.agents/skills/prepare-pr/SKILL.md create mode 120000 java-bigquery-jdbc/.claude/skills delete mode 120000 java-bigquery-jdbc/.claude/skills/bigquery-jdbc-testing delete mode 120000 java-bigquery-jdbc/.gemini/skills/bigquery-jdbc-testing diff --git a/java-bigquery-jdbc/.agents/skills/prepare-pr/SKILL.md b/java-bigquery-jdbc/.agents/skills/prepare-pr/SKILL.md new file mode 100644 index 000000000000..a9339996ce3f --- /dev/null +++ b/java-bigquery-jdbc/.agents/skills/prepare-pr/SKILL.md @@ -0,0 +1,189 @@ +--- +name: prepare-pr +description: Prepare a pull request for the BigQuery JDBC driver (java-bigquery-jdbc) and get it independently reviewed. Before a PR is created, pushed, or marked ready for review, a reviewer agent on a different model checks the code and the PR description. The author fixes or argues against each finding, and a fresh reviewer re-checks. The loop repeats until both the author and the reviewer are satisfied. Use this skill whenever you are about to open, update, or finish a PR. +--- + +# Preparing a PR with external review + +When you (the **author agent**) finish a change, you aren't done when your own +tests pass. Get an independent review from an agent running a **different +model** first, and repeat until you and the reviewer agree the PR is ready. + +```mermaid +flowchart TD + A["1. Finish change, run local checks"] --> B["2. Write PR description, build context bundle"] + B --> C["3. Start a FRESH reviewer on a different model"] + C --> D{"Reviewer verdict"} + D -->|"APPROVE, nothing blocking open"| G{"Author satisfied?"} + D -->|"CHANGES_REQUESTED"| E["4. Author answers every finding: FIXED or PUSHBACK with a reason"] + E --> F["5. Re-run local checks, update description and ledger"] + F --> C + G -->|"yes"| H["6. Done: push or open the PR, report to user"] + G -->|"no, author has open concerns"| E +``` + +## 1. Finish the change and run local checks + +Before you ask anyone to review, the change must build and pass its tests: + +- Format: `make lint` from `java-bigquery-jdbc/`. +- Unit tests for the classes you touched: `make unittest test=`. +- Integration tests compile at least: `mvn -q -Denforcer.skip=true -Dclirr.skip=true test-compile`. +- Follow the repo `AGENTS.md` and, for test changes, the `bigquery-jdbc-testing` skill. + +## 2. Write the PR description and build the context bundle + +Write the PR description now, not after the review. The reviewer checks it too. +It has: + +- **Title** in Conventional Commits form: `fix(bigquery-jdbc): ...`. +- **What** changed and **why** (the bug, the issue link, or the requirement). +- **How it was tested**: the commands you ran, new tests, and anything you + couldn't run (for example integration tests that need credentials). +- **Risks / follow-ups**, if any. + +Build a **context bundle** for the reviewer: + +1. The PR description, word for word. +2. The full diff against the base branch: `git diff origin/main...HEAD` plus any + uncommitted changes (`git diff HEAD`). +3. The list of changed files (`git diff --name-only origin/main...HEAD`) and the + repo path, so the reviewer can open surrounding code itself. +4. From round 2 on, the **review ledger** (see step 4). + +Keep the bundle and ledger in a scratch location **outside the repository** (for +example the agent's scratch or artifact directory, or `/tmp`). Never commit them. + +## 3. Start a fresh reviewer on a different model + +The reviewer must run on a **different model from yours**, so its blind spots +differ from yours. Start a **new** reviewer every round. Don't continue an old +reviewer conversation, because it is already anchored on its earlier opinions. +The ledger gives the new reviewer the history it needs. + +How to start a reviewer, depending on your harness: + +| Harness | How to start a different-model reviewer | +| --- | --- | +| Jetski / Antigravity | `invoke_subagent` with a `Model` other than your own (for example `pro` if you aren't on it), read-only research type. | +| Claude Code | Gemini CLI from the shell: `gemini -p "$(cat )"`. If it isn't installed, use a Task subagent pinned to a different Claude model. | +| Gemini CLI | Claude Code from the shell: `claude -p "$(cat )"`. If it isn't installed, use a subagent on a different Gemini model. | + +If you can't get a different model at all, stop and tell the user. Don't quietly +use your own model to review your own work. + +### Reviewer prompt template + +```text +You are an independent senior reviewer for a pull request to the google-cloud-java +monorepo, module java-bigquery-jdbc (the BigQuery JDBC driver). You did not write +this code. Be rigorous and specific, and don't rubber-stamp it. + +Repository: (you may read any file for context) +Base branch: origin/main + +== PR DESCRIPTION == + + +== CHANGED FILES == + + +== DIFF == + + +== REVIEW LEDGER FROM EARLIER ROUNDS (empty in round 1) == + + +Review for: correctness and edge cases, concurrency and resource leaks +(connections, statements, result sets, threads), JDBC spec compliance, backward +compatibility and public API surface (see AGENTS.md and the api-lifecycle skill), +security (credentials, logging of secrets), test coverage of every new branch, +test quality (see the bigquery-jdbc-testing skill), and whether the PR +description is accurate and complete. + +For each earlier finding marked PUSHBACK in the ledger, say whether you ACCEPT +the author's reason (the finding is then closed) or MAINTAIN it, with a new +argument. Don't repeat a finding that is marked FIXED unless the fix is wrong or +incomplete. + +Reply in exactly this format: + +VERDICT: APPROVE | CHANGES_REQUESTED +FINDINGS: +- id: R- + severity: blocking | major | minor | nit + location: : | PR description + issue: + suggestion: +PUSHBACK_RESPONSES: +- id: + decision: ACCEPT | MAINTAIN + reason: + +APPROVE only if no blocking or major findings are open. +``` + +## 4. Answer every finding: fix it or push back + +Answer **every** finding in the ledger with exactly one of: + +- **FIXED**: say what you changed and where. +- **PUSHBACK**: you disagree. You **must** give a concrete reason backed by + evidence: a code reference, the JDBC spec, an existing convention in the repo, + a test result, or scope ("out of scope for this PR; tracked in "). + "I prefer it this way" is not a reason. + +Rules: + +- Take the findings seriously. Push back only when you are confident the + reviewer is wrong or the request is out of scope. Don't push back to save + effort. +- `nit` findings may be answered `WONTFIX` with a short reason. +- If a reviewer maintains a pushback for a second round, either fix it or + escalate it to the user (see step 6). Don't argue a third round. +- You may also add your **own** open concerns to the ledger, things you are + still unsure about. The loop doesn't end while any of them are open. + +### Ledger format + +Keep one ledger file for the whole loop and append to it every round: + +```markdown +## Round , reviewer model: , verdict: + +| id | severity | finding | author response | status | +| --- | --- | --- | --- | --- | +| R1-1 | blocking | ResultSet leaked on error path in Foo.java:120 | FIXED: try-with-resources in Foo.java:118-131 | closed | +| R1-2 | major | Missing test for default universe | FIXED: added testXForDefaultUniverse | closed | +| R1-3 | minor | Rename helper to assertY | PUSHBACK: name matches existing assertX convention in BarTest | open, awaiting reviewer | + +Author open concerns: +``` + +## 5. Re-run checks and loop + +After you address the findings: + +1. Re-run the local checks from step 1. Every round, not just the first. +2. Update the PR description if the change or the testing changed. +3. Rebuild the context bundle (new diff, updated ledger). +4. Go back to step 3 with a **new** reviewer. + +## 6. When to stop + +The loop **ends successfully** only when all of these are true: + +- The latest reviewer's verdict is `APPROVE`. +- No `blocking` or `major` finding is open, and every pushback is either + ACCEPTED or resolved by a fix. +- You (the author) have no open concerns. +- The local checks pass on the final code. + +**Safety limit:** if you haven't reached agreement after **5 rounds**, or a +pushback is maintained twice, stop. Report the unresolved items to the user +with both sides' arguments and let them decide. Don't loop forever, and don't +declare agreement that didn't happen. + +When the loop ends, report to the user: the number of rounds, the reviewer +model(s) used, what changed because of review, any accepted pushbacks, and the +final PR description. Push or open the PR only if the user asked you to. diff --git a/java-bigquery-jdbc/.claude/skills b/java-bigquery-jdbc/.claude/skills new file mode 120000 index 000000000000..2b7a412b8fa0 --- /dev/null +++ b/java-bigquery-jdbc/.claude/skills @@ -0,0 +1 @@ +../.agents/skills \ No newline at end of file diff --git a/java-bigquery-jdbc/.claude/skills/bigquery-jdbc-testing b/java-bigquery-jdbc/.claude/skills/bigquery-jdbc-testing deleted file mode 120000 index dffed6f65a1d..000000000000 --- a/java-bigquery-jdbc/.claude/skills/bigquery-jdbc-testing +++ /dev/null @@ -1 +0,0 @@ -../../.agents/skills/bigquery-jdbc-testing \ No newline at end of file diff --git a/java-bigquery-jdbc/.gemini/skills/bigquery-jdbc-testing b/java-bigquery-jdbc/.gemini/skills/bigquery-jdbc-testing deleted file mode 120000 index dffed6f65a1d..000000000000 --- a/java-bigquery-jdbc/.gemini/skills/bigquery-jdbc-testing +++ /dev/null @@ -1 +0,0 @@ -../../.agents/skills/bigquery-jdbc-testing \ No newline at end of file diff --git a/java-bigquery-jdbc/.gitignore b/java-bigquery-jdbc/.gitignore index eb60678e7791..fda14508dd4d 100644 --- a/java-bigquery-jdbc/.gitignore +++ b/java-bigquery-jdbc/.gitignore @@ -4,6 +4,10 @@ target-it/** **/ITBigQueryJDBCLocalTest.java **/BigQueryStatementE2EBenchmark.java +# Agent files: ignore local/generated content, but track shared skills. +.agents/* +!.agents/skills/ + tools/**/*.class tools/**/drivers/** tools/**/logs/** From cd5c1aa7c1266d16710a36331f8d672fa498293c Mon Sep 17 00:00:00 2001 From: Keshav Dandeva Date: Mon, 16 Nov 2026 15:55:35 +0000 Subject: [PATCH 3/3] chore(bigquery-jdbc): harden shared agent skills and add module AGENTS.md - Rename prepare-pr to bigquery-jdbc-prepare-pr and remove its contradictions: the flowchart no longer says to push, WONTFIX is a defined response, pushback escalation is stated once, and findings attached to an APPROVE have a rule. - bigquery-jdbc-prepare-pr: add a single-round path for non-Java changes, a sync-with-main step, the full unit suite before round 1 and on the final code, untracked-file handling, and reviewer prompts on stdin. - bigquery-jdbc-testing: state base classes as a rule for new tests only, use the real BigQueryConnectionTest example, and point to ITBase instead of listing its members. - Add java-bigquery-jdbc/AGENTS.md with module guardrails and a skill index. - .gitignore: ignore .claude/ except the shared skills symlink. - DEVELOPMENT.md: replace nonexistent BigQueryJdbcTypeMappings and BigQueryCoercion with BigQueryTypeRegistry and TypeDescriptor, and describe make lint as formatter-only. --- .../skills/bigquery-jdbc-prepare-pr/SKILL.md | 251 ++++++++++++++++++ .../skills/bigquery-jdbc-testing/SKILL.md | 61 +++-- .../.agents/skills/prepare-pr/SKILL.md | 189 ------------- java-bigquery-jdbc/.gitignore | 5 +- java-bigquery-jdbc/AGENTS.md | 48 ++++ java-bigquery-jdbc/DEVELOPMENT.md | 19 +- 6 files changed, 354 insertions(+), 219 deletions(-) create mode 100644 java-bigquery-jdbc/.agents/skills/bigquery-jdbc-prepare-pr/SKILL.md delete mode 100644 java-bigquery-jdbc/.agents/skills/prepare-pr/SKILL.md create mode 100644 java-bigquery-jdbc/AGENTS.md diff --git a/java-bigquery-jdbc/.agents/skills/bigquery-jdbc-prepare-pr/SKILL.md b/java-bigquery-jdbc/.agents/skills/bigquery-jdbc-prepare-pr/SKILL.md new file mode 100644 index 000000000000..df59dd294571 --- /dev/null +++ b/java-bigquery-jdbc/.agents/skills/bigquery-jdbc-prepare-pr/SKILL.md @@ -0,0 +1,251 @@ +--- +name: bigquery-jdbc-prepare-pr +description: Prepare a pull request for the BigQuery JDBC driver (java-bigquery-jdbc) and get it independently reviewed. Before a PR is created, pushed, or marked ready for review, a fresh reviewer agent on a different model checks the diff and the PR description. The author fixes or argues against each finding, and the loop repeats until both the author and the reviewer are satisfied. Docs, config and other non-Java changes get a single review round. Use this skill whenever you are about to open, update, or finish a PR that touches java-bigquery-jdbc. +--- + +# Preparing a PR with external review + +When you (the **author agent**) finish a change, you aren't done when your own +tests pass. Get an independent review from an agent running a **different +model** first, and repeat until you and the reviewer agree the PR is ready. + +This skill never pushes or opens a PR by itself. Do that only if the user asked. + +```mermaid +flowchart TD + A["1. Sync with main, finish change, run local checks"] --> B["2. Write PR description, build context bundle"] + B --> C["3. Start a FRESH reviewer on a different model"] + C --> D{"Reviewer verdict"} + D -->|"CHANGES_REQUESTED"| E["4. Answer every finding: FIXED, PUSHBACK or WONTFIX"] + D -->|"APPROVE"| G{"Author concerns open, or an answer that changes behaviour?"} + G -->|"yes"| E + G -->|"no"| H["6. Stop and report to the user. Push or open the PR only if asked"] + E --> F["5. Re-run local checks, update description and ledger"] + F -->|"full loop"| C + F -->|"single-round change, nothing blocking"| H +``` + +## How much review the change needs + +| The change | Review | +| --- | --- | +| Edits any `.java` file under `src/`, beyond comments or formatting | **Full loop**: steps 1 to 6. | +| Anything else: docs, Markdown, skills, build or CI config, dependency bumps, comment-only or formatting-only edits | **Single round**: steps 1 to 4 once, then re-run the checks, update the description, and report as in step 6. Go one more round only if the reviewer raised a `blocking` finding, to confirm the fix. | + +If you aren't sure which row applies, use the full loop. In a single-round +change, run only the local checks the change can affect. + +## 1. Sync with main, finish the change, run local checks + +Before you ask anyone to review, the branch must be current and the change must +build and pass its tests: + +- Sync: `git fetch origin main`, then bring `origin/main` into the branch. If + the branch is already pushed, merge instead of rebasing unless the user asks + for a rebase, so nobody has to force-push. (`origin` here means the remote for + `googleapis/google-cloud-java`.) +- Format: `make lint` from `java-bigquery-jdbc/`. It rewrites files in place. +- Unit tests: the full suite, `make unittest`, before the first round and again + on the final code. Between rounds the classes you touched are enough: + `make unittest test=`. +- Integration tests compile at least: `mvn -q -Denforcer.skip=true -Dclirr.skip=true test-compile`. +- Follow the repo and module `AGENTS.md` and, for test changes, the + `bigquery-jdbc-testing` skill. + +## 2. Write the PR description and build the context bundle + +Write the PR description now, not after the review. The reviewer checks it too. +It has: + +- **Title** in Conventional Commits form: `fix(bigquery-jdbc): ...`. +- **What** changed and **why** (the bug, the issue link, or the requirement). +- **How it was tested**: the commands you ran, new tests, and anything you + couldn't run (for example integration tests that need credentials). +- **Risks / follow-ups**, if any. + +**Untracked files are in no diff.** Before you build the bundle, run +`git status --short`. For every `??` file that belongs to the change, run +`git add -N ` (or commit it) so the reviewer sees it. + +Build a **context bundle** for the reviewer: + +1. The PR description, word for word. +2. The full diff from the merge base to your working tree: + `git diff "$(git merge-base origin/main HEAD)"`. One diff covers committed, + staged and unstaged changes. +3. The list of changed files (the same command with `--name-only`) and the repo + path, so the reviewer can open surrounding code itself. +4. From round 2 on, the **review ledger** (see step 4). + +Keep the bundle and ledger in a scratch location **outside the repository** (for +example the agent's scratch or artifact directory, or `/tmp`). Never commit them. + +## 3. Start a fresh reviewer on a different model + +The reviewer must run on a **different model from yours**, so its blind spots +differ from yours. Prefer a model at least as capable as your own. If every +different model you can reach is weaker than yours, use the strongest of them +and say so in the final report, so the user knows how much weight the approval +carries. + +Start a **new** reviewer every round. Don't continue an old reviewer +conversation, because it is already anchored on its earlier opinions. The ledger +gives the new reviewer the history it needs. + +Save the filled-in prompt as a file in the scratch location (`$PROMPT_FILE` +below). How to start a reviewer, depending on your harness: + +| Harness | How to start a different-model reviewer | +| --- | --- | +| Jetski / Antigravity | `invoke_subagent` with a `Model` other than your own, on a read-only type such as `research`. Give it the path of the prompt file, or the prompt itself if it is short. | +| Claude Code | Gemini CLI from the shell: `gemini -p "Review as instructed on stdin." < "$PROMPT_FILE"`. If it isn't installed, use a Task subagent pinned to a different Claude model. | +| Gemini CLI | Claude Code from the shell: `claude -p "Review as instructed on stdin." < "$PROMPT_FILE"`. If it isn't installed, use a subagent on a different Gemini model. | + +- Pass the prompt on stdin as shown, not as a command-line argument. Linux + limits a single argument to 128 KiB, and a large diff plus this template + exceeds that. +- The two shell commands send the diff to another company's service. Don't use + them for a security fix that isn't public yet, or where the user or team has + restricted external services. Use the same-vendor fallback in that row + instead. +- If you can't get a different model at all, stop and tell the user. Don't + quietly use your own model to review your own work. If you can't tell which + model you are running on, say that in the final report. + +### Reviewer prompt template + +```text +You are an independent senior reviewer for a pull request to the google-cloud-java +monorepo, module java-bigquery-jdbc (the BigQuery JDBC driver). You did not write +this code. Be rigorous and specific, and don't rubber-stamp it. + +Repository: (you may read any file for context) +Base branch: origin/main +Round: + +== PR DESCRIPTION == + + +== CHANGED FILES == + + +== DIFF == + + +== REVIEW LEDGER FROM EARLIER ROUNDS (empty in round 1) == + + +Review for: correctness and edge cases, concurrency and resource leaks +(connections, statements, result sets, threads), JDBC spec compliance, backward +compatibility and public API surface (see AGENTS.md and the api-lifecycle skill), +security (credentials, logging of secrets), test coverage of every new branch, +test quality (see the bigquery-jdbc-testing skill), and whether the PR +description is accurate and complete. For documentation, skill and config +changes, check every factual claim (class names, commands, paths) against the +repository. + +From round 2 on: +- For each finding marked FIXED, check the fix in the code. Don't repeat the + finding unless the fix is wrong or incomplete. +- For each finding marked PUSHBACK, say whether you ACCEPT the author's reason + (the finding is then closed) or MAINTAIN it, with a new argument. +- Findings marked WONTFIX are closed nits. Don't repeat them. +- Concentrate on what the ledger says changed since the previous round. Raise a + new finding on code that has not changed since then only if it is blocking or + major. + +Reply in exactly this format: + +VERDICT: APPROVE | CHANGES_REQUESTED +FINDINGS: +- id: R- + severity: blocking | major | minor | nit + location: : | PR description + issue: + suggestion: +PUSHBACK_RESPONSES: +- id: + decision: ACCEPT | MAINTAIN + reason: + +APPROVE only if no blocking or major findings are open. +``` + +## 4. Answer every finding + +Answer **every** finding in the ledger with exactly one of: + +- **FIXED**: say what you changed and where (file and lines). The next reviewer + uses this to find the change. +- **PUSHBACK**: you disagree. You **must** give a concrete reason backed by + evidence: a code reference, the JDBC spec, an existing convention in the repo, + a test result, or scope ("out of scope for this PR; tracked in "). + "I prefer it this way" is not a reason. +- **WONTFIX**: for `nit` findings only, with a short reason. It closes the + finding. + +Rules: + +- Take the findings seriously. Push back only when you are confident the + reviewer is wrong or the request is out of scope. Don't push back to save + effort. +- If the reviewer maintains a pushback, you may answer it once more. If it is + maintained a second time, fix it, or stop and escalate to the user (see + step 6). Don't argue a third round. +- You may also add your **own** open concerns to the ledger, things you are + still unsure about. The loop doesn't end while any of them are open. +- An `APPROVE` can still carry `minor` or `nit` findings. Answer them like any + others. If an answer changes behaviour (anything beyond renames, comments, + formatting, or the PR description), that code has not been reviewed: go + another round. Otherwise re-run the checks and finish. + +### Ledger format + +Keep one ledger file for the whole loop and append to it every round: + +```markdown +## Round , reviewer model: , verdict: + +| id | severity | finding | author response | status | +| --- | --- | --- | --- | --- | +| R1-1 | blocking | ResultSet leaked on error path in Foo.java:120 | FIXED: try-with-resources in Foo.java:118-131 | closed | +| R1-2 | major | Missing test for default universe | FIXED: added testXForDefaultUniverse in FooTest.java:210-240 | closed | +| R1-3 | minor | Rename helper to assertY | PUSHBACK: name matches existing assertX convention in BarTest | open, awaiting reviewer | +| R1-4 | nit | Blank line before return | WONTFIX: formatter output | closed | + +Author open concerns: +``` + +## 5. Re-run checks and loop + +After you address the findings: + +1. Re-run the local checks from step 1. Every round, not just the first. +2. Update the PR description if the change or the testing changed. +3. Rebuild the context bundle (new diff, updated ledger). +4. Go back to step 3 with a **new** reviewer. + +A single-round change stops after item 2, unless the reviewer raised a +`blocking` finding. + +## 6. When to stop + +The full loop **ends successfully** only when all of these are true: + +- The latest reviewer's verdict is `APPROVE`. +- No `blocking` or `major` finding is open, and every pushback is either + ACCEPTED or resolved by a fix. +- You (the author) have no open concerns. +- Nothing that changes behaviour was edited after the last review. +- The local checks, including the full unit suite, pass on the final code. + +**Safety limit:** stop after **5 rounds** without agreement, or when a pushback +has been maintained twice and you are not going to fix it. Report the +unresolved items to the user with both sides' arguments and let them decide. +Don't loop forever, and don't declare agreement that didn't happen. + +When you stop, report to the user: the number of rounds, the reviewer model(s) +used and whether any was weaker than yours, what changed because of review, any +accepted pushbacks, anything you changed after the last review, any finding +left unfixed, and the final PR description. Push or open the PR only if the +user asked you to. diff --git a/java-bigquery-jdbc/.agents/skills/bigquery-jdbc-testing/SKILL.md b/java-bigquery-jdbc/.agents/skills/bigquery-jdbc-testing/SKILL.md index 12f1fee4873a..fb89b3c46cf7 100644 --- a/java-bigquery-jdbc/.agents/skills/bigquery-jdbc-testing/SKILL.md +++ b/java-bigquery-jdbc/.agents/skills/bigquery-jdbc-testing/SKILL.md @@ -7,10 +7,15 @@ description: Conventions for writing and refactoring unit and integration tests Applies to `java-bigquery-jdbc/src/test/java/com/google/cloud/bigquery/jdbc/**`. -- **Unit tests** live in `com.google.cloud.bigquery.jdbc` and extend - `BigQueryJdbcBaseTest` (directly or through `BigQueryJdbcLoggingBaseTest`). -- **Integration tests** live in `com.google.cloud.bigquery.jdbc.it`, are named - `IT*`, and extend `ITBase`. +- **Unit tests** live in `com.google.cloud.bigquery.jdbc`. A new test class that + needs the shared fixtures extends `BigQueryJdbcBaseTest`, or + `BigQueryJdbcLoggingBaseTest` when it asserts on log output. +- **Integration tests** live in `com.google.cloud.bigquery.jdbc.it` and are + named `IT*`. A new one extends `ITBase` when it uses the shared connection, + datasets, or helpers. + +Many existing test classes extend neither base class. Leave their parent alone: +don't re-parent a class unless that is the task you were given. Aim for tests that are short and read top to bottom: setup comes from shared fixtures, the test body holds only what is specific to the case, and repeated @@ -34,7 +39,7 @@ Example: String url = getUriOAuthServiceAccount() .append("ProjectId", "project") - .append("universeDomain", TPC_UNIVERSE) + .append("universeDomain", "apis-tpczero.goog") .toString(); ``` @@ -49,13 +54,21 @@ the assertions into one `private static` helper that takes the varying parts (credentials, endpoint URI, expected scopes, expected universe) as parameters. Each test then makes one call per object. +This is how `BigQueryConnectionTest` does it. `TPC_UNIVERSE`, `storageUri` and +`assertStorageCredentialsScoped` are private members of that class, not shared +fixtures: + ```java assertStorageCredentialsScoped( readClient.getSettings().getCredentialsProvider().getCredentials(), - TPC_UNIVERSE, TPC_READ_URI, BigQueryReadSettings.getDefaultServiceScopes()); + TPC_UNIVERSE, + storageUri(TPC_UNIVERSE, "BigQueryRead"), + BigQueryReadSettings.getDefaultServiceScopes()); assertStorageCredentialsScoped( writeClient.getSettings().getCredentialsProvider().getCredentials(), - TPC_UNIVERSE, TPC_WRITE_URI, BigQueryWriteSettings.getDefaultServiceScopes()); + TPC_UNIVERSE, + storageUri(TPC_UNIVERSE, "BigQueryWrite"), + BigQueryWriteSettings.getDefaultServiceScopes()); ``` Put repeated literals (universe domains, endpoint URIs, scope lists) in @@ -83,18 +96,19 @@ cases or weaken assertions (for example, changing `assertEquals` to ## 4. Integration tests: shared pieces belong in `ITBase` +- Read `ITBase` before you add a query template or a check. It is the source of + truth for what is shared. It already has, for example, + `GENERATE_ARRAY_QUERY` (used as `String.format(GENERATE_ARRAY_QUERY, n)`), + `assertArrowResultSet(ResultSet)` (proves the High-Throughput, Storage Read + API path was taken), `resultSetRowCount(ResultSet)` and + `validateStatement(...)`. - If more than one `IT*` class uses the same query template or check, define it - once in `ITBase` as a `public static final` constant or a `protected`/`public - static` helper. Don't redefine it per class or inline the literal. Current - shared pieces: - - `GENERATE_ARRAY_QUERY` = `"SELECT * FROM UNNEST(GENERATE_ARRAY(1, %s));"`, - used with `String.format(GENERATE_ARRAY_QUERY, n)`. - - `assertArrowResultSet(ResultSet)`, which checks that the High-Throughput - (Storage Read) API path was taken. - - `resultSetRowCount(ResultSet)` and `validateStatement(...)`. -- Don't shadow `ITBase` members with a same-named `private static final` field - that means something else (for example a class-local `BASE_QUERY` that is a - different query). + once in `ITBase`. Don't redefine it per class or inline the literal. Use the + least visibility that works: `protected static` is enough unless something + outside the `ITBase` hierarchy needs it. +- Don't give a class-local constant or helper the same name as an `ITBase` + member. A same-named field that means something else hides the shared one and + misleads the reader. - Use try-with-resources for `Connection`, `Statement`, and `ResultSet`, or close them explicitly. IT suites share quotas. - `@Tag("disable_tpc")` excludes a test from TPC runs. Remove it only when the @@ -103,9 +117,10 @@ cases or weaken assertions (for example, changing `assertEquals` to ## 5. Style and verification -- Follow the repo `AGENTS.md`: least visibility (`private static` helpers), - short names over fully qualified names, no `@Deprecated`/`@ObsoleteApi` - calls, and no unrelated formatting changes. +- Follow the repo and module `AGENTS.md`: least visibility (`private static` + helpers), short names over fully qualified names, no + `@Deprecated`/`@ObsoleteApi` calls, no Mockito mocks of final JDK types, and + no unrelated formatting changes. - Remove imports that the refactor makes unused (for example `KeyPairGenerator`, `PrivateKey`, `Base64`). - Run the formatter from `java-bigquery-jdbc/`: @@ -113,8 +128,8 @@ cases or weaken assertions (for example, changing `assertEquals` to make lint # mvn com.spotify.fmt:fmt-maven-plugin:format ``` If the formatter fails with `NoSuchMethodError`, your JDK is too new for - google-java-format. Run it under an older JDK, for example - `JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 make lint`. + google-java-format. Run it under JDK 17, which is what the CI lint job uses: + `JAVA_HOME= make lint`. - Run the affected unit tests: ```bash make unittest test=BigQueryConnectionTest diff --git a/java-bigquery-jdbc/.agents/skills/prepare-pr/SKILL.md b/java-bigquery-jdbc/.agents/skills/prepare-pr/SKILL.md deleted file mode 100644 index a9339996ce3f..000000000000 --- a/java-bigquery-jdbc/.agents/skills/prepare-pr/SKILL.md +++ /dev/null @@ -1,189 +0,0 @@ ---- -name: prepare-pr -description: Prepare a pull request for the BigQuery JDBC driver (java-bigquery-jdbc) and get it independently reviewed. Before a PR is created, pushed, or marked ready for review, a reviewer agent on a different model checks the code and the PR description. The author fixes or argues against each finding, and a fresh reviewer re-checks. The loop repeats until both the author and the reviewer are satisfied. Use this skill whenever you are about to open, update, or finish a PR. ---- - -# Preparing a PR with external review - -When you (the **author agent**) finish a change, you aren't done when your own -tests pass. Get an independent review from an agent running a **different -model** first, and repeat until you and the reviewer agree the PR is ready. - -```mermaid -flowchart TD - A["1. Finish change, run local checks"] --> B["2. Write PR description, build context bundle"] - B --> C["3. Start a FRESH reviewer on a different model"] - C --> D{"Reviewer verdict"} - D -->|"APPROVE, nothing blocking open"| G{"Author satisfied?"} - D -->|"CHANGES_REQUESTED"| E["4. Author answers every finding: FIXED or PUSHBACK with a reason"] - E --> F["5. Re-run local checks, update description and ledger"] - F --> C - G -->|"yes"| H["6. Done: push or open the PR, report to user"] - G -->|"no, author has open concerns"| E -``` - -## 1. Finish the change and run local checks - -Before you ask anyone to review, the change must build and pass its tests: - -- Format: `make lint` from `java-bigquery-jdbc/`. -- Unit tests for the classes you touched: `make unittest test=`. -- Integration tests compile at least: `mvn -q -Denforcer.skip=true -Dclirr.skip=true test-compile`. -- Follow the repo `AGENTS.md` and, for test changes, the `bigquery-jdbc-testing` skill. - -## 2. Write the PR description and build the context bundle - -Write the PR description now, not after the review. The reviewer checks it too. -It has: - -- **Title** in Conventional Commits form: `fix(bigquery-jdbc): ...`. -- **What** changed and **why** (the bug, the issue link, or the requirement). -- **How it was tested**: the commands you ran, new tests, and anything you - couldn't run (for example integration tests that need credentials). -- **Risks / follow-ups**, if any. - -Build a **context bundle** for the reviewer: - -1. The PR description, word for word. -2. The full diff against the base branch: `git diff origin/main...HEAD` plus any - uncommitted changes (`git diff HEAD`). -3. The list of changed files (`git diff --name-only origin/main...HEAD`) and the - repo path, so the reviewer can open surrounding code itself. -4. From round 2 on, the **review ledger** (see step 4). - -Keep the bundle and ledger in a scratch location **outside the repository** (for -example the agent's scratch or artifact directory, or `/tmp`). Never commit them. - -## 3. Start a fresh reviewer on a different model - -The reviewer must run on a **different model from yours**, so its blind spots -differ from yours. Start a **new** reviewer every round. Don't continue an old -reviewer conversation, because it is already anchored on its earlier opinions. -The ledger gives the new reviewer the history it needs. - -How to start a reviewer, depending on your harness: - -| Harness | How to start a different-model reviewer | -| --- | --- | -| Jetski / Antigravity | `invoke_subagent` with a `Model` other than your own (for example `pro` if you aren't on it), read-only research type. | -| Claude Code | Gemini CLI from the shell: `gemini -p "$(cat )"`. If it isn't installed, use a Task subagent pinned to a different Claude model. | -| Gemini CLI | Claude Code from the shell: `claude -p "$(cat )"`. If it isn't installed, use a subagent on a different Gemini model. | - -If you can't get a different model at all, stop and tell the user. Don't quietly -use your own model to review your own work. - -### Reviewer prompt template - -```text -You are an independent senior reviewer for a pull request to the google-cloud-java -monorepo, module java-bigquery-jdbc (the BigQuery JDBC driver). You did not write -this code. Be rigorous and specific, and don't rubber-stamp it. - -Repository: (you may read any file for context) -Base branch: origin/main - -== PR DESCRIPTION == - - -== CHANGED FILES == - - -== DIFF == - - -== REVIEW LEDGER FROM EARLIER ROUNDS (empty in round 1) == - - -Review for: correctness and edge cases, concurrency and resource leaks -(connections, statements, result sets, threads), JDBC spec compliance, backward -compatibility and public API surface (see AGENTS.md and the api-lifecycle skill), -security (credentials, logging of secrets), test coverage of every new branch, -test quality (see the bigquery-jdbc-testing skill), and whether the PR -description is accurate and complete. - -For each earlier finding marked PUSHBACK in the ledger, say whether you ACCEPT -the author's reason (the finding is then closed) or MAINTAIN it, with a new -argument. Don't repeat a finding that is marked FIXED unless the fix is wrong or -incomplete. - -Reply in exactly this format: - -VERDICT: APPROVE | CHANGES_REQUESTED -FINDINGS: -- id: R- - severity: blocking | major | minor | nit - location: : | PR description - issue: - suggestion: -PUSHBACK_RESPONSES: -- id: - decision: ACCEPT | MAINTAIN - reason: - -APPROVE only if no blocking or major findings are open. -``` - -## 4. Answer every finding: fix it or push back - -Answer **every** finding in the ledger with exactly one of: - -- **FIXED**: say what you changed and where. -- **PUSHBACK**: you disagree. You **must** give a concrete reason backed by - evidence: a code reference, the JDBC spec, an existing convention in the repo, - a test result, or scope ("out of scope for this PR; tracked in "). - "I prefer it this way" is not a reason. - -Rules: - -- Take the findings seriously. Push back only when you are confident the - reviewer is wrong or the request is out of scope. Don't push back to save - effort. -- `nit` findings may be answered `WONTFIX` with a short reason. -- If a reviewer maintains a pushback for a second round, either fix it or - escalate it to the user (see step 6). Don't argue a third round. -- You may also add your **own** open concerns to the ledger, things you are - still unsure about. The loop doesn't end while any of them are open. - -### Ledger format - -Keep one ledger file for the whole loop and append to it every round: - -```markdown -## Round , reviewer model: , verdict: - -| id | severity | finding | author response | status | -| --- | --- | --- | --- | --- | -| R1-1 | blocking | ResultSet leaked on error path in Foo.java:120 | FIXED: try-with-resources in Foo.java:118-131 | closed | -| R1-2 | major | Missing test for default universe | FIXED: added testXForDefaultUniverse | closed | -| R1-3 | minor | Rename helper to assertY | PUSHBACK: name matches existing assertX convention in BarTest | open, awaiting reviewer | - -Author open concerns: -``` - -## 5. Re-run checks and loop - -After you address the findings: - -1. Re-run the local checks from step 1. Every round, not just the first. -2. Update the PR description if the change or the testing changed. -3. Rebuild the context bundle (new diff, updated ledger). -4. Go back to step 3 with a **new** reviewer. - -## 6. When to stop - -The loop **ends successfully** only when all of these are true: - -- The latest reviewer's verdict is `APPROVE`. -- No `blocking` or `major` finding is open, and every pushback is either - ACCEPTED or resolved by a fix. -- You (the author) have no open concerns. -- The local checks pass on the final code. - -**Safety limit:** if you haven't reached agreement after **5 rounds**, or a -pushback is maintained twice, stop. Report the unresolved items to the user -with both sides' arguments and let them decide. Don't loop forever, and don't -declare agreement that didn't happen. - -When the loop ends, report to the user: the number of rounds, the reviewer -model(s) used, what changed because of review, any accepted pushbacks, and the -final PR description. Push or open the PR only if the user asked you to. diff --git a/java-bigquery-jdbc/.gitignore b/java-bigquery-jdbc/.gitignore index fda14508dd4d..b1029c8bff20 100644 --- a/java-bigquery-jdbc/.gitignore +++ b/java-bigquery-jdbc/.gitignore @@ -4,9 +4,12 @@ target-it/** **/ITBigQueryJDBCLocalTest.java **/BigQueryStatementE2EBenchmark.java -# Agent files: ignore local/generated content, but track shared skills. +# Agent files: only shared skills are tracked; everything else is local. +# .claude/skills is a symlink to .agents/skills, for Claude Code. .agents/* !.agents/skills/ +.claude/* +!.claude/skills tools/**/*.class tools/**/drivers/** diff --git a/java-bigquery-jdbc/AGENTS.md b/java-bigquery-jdbc/AGENTS.md new file mode 100644 index 000000000000..e292bc2b593c --- /dev/null +++ b/java-bigquery-jdbc/AGENTS.md @@ -0,0 +1,48 @@ +# Agents Guide for java-bigquery-jdbc + +Applies to everything under `java-bigquery-jdbc/`, on top of the repo-wide +[AGENTS.md](../AGENTS.md). + +Read [DEVELOPMENT.md](DEVELOPMENT.md) before you change code. It has the +architecture, the build and test commands, the logging conventions and the +pre-PR checklist. The guardrails below are the short form of its section 2; +DEVELOPMENT.md is the full text. + +## Guardrails + +1. **Visibility**: default to `private` or package-private. Make something + `public` only when a JDBC interface requires it. +2. **Imports**: explicit imports only. No wildcard imports and no inline fully + qualified names. +3. **Logging**: use `BigQueryJdbcCustomLogger`, not `java.util.logging.Logger`. +4. **Exceptions**: throw types from `com.google.cloud.bigquery.exception`. +5. **Tests**: don't mock final JDK types (`BigDecimal`, `LocalDate`, `Instant`, + `UUID`) with Mockito. Construct real instances. + +## Commands + +Run these from `java-bigquery-jdbc/`: + +- `make lint` formats the code in place. +- `make unittest` runs all unit tests. `make unittest test=` runs one + class. +- `make integration-test test=` runs one integration test class. It + needs `GOOGLE_APPLICATION_CREDENTIALS`. + +## Skills + +| Skill | Use it when | +| --- | --- | +| `bigquery-jdbc-testing` | Adding, reviewing or refactoring tests under `src/test`. | +| `bigquery-jdbc-prepare-pr` | About to open, update or finish a PR that touches this module. | + +Shared skills live in `.agents/skills//SKILL.md`. To add one, create that +directory with a `SKILL.md` whose front matter has a `name` (the directory name, +prefixed `bigquery-jdbc-`) and a `description` (what the skill does and when to +use it), then add a row to the table above. + +- `.claude/skills` is a symlink to `.agents/skills`, so Claude Code finds the + same skills. On a Windows checkout without symlink support it is a plain text + file and Claude Code will not see them. +- Only the skills are tracked. `.gitignore` ignores everything else under + `.agents/` and `.claude/`, so personal rules and local settings stay local. diff --git a/java-bigquery-jdbc/DEVELOPMENT.md b/java-bigquery-jdbc/DEVELOPMENT.md index aa4dae950473..825da028d7b2 100644 --- a/java-bigquery-jdbc/DEVELOPMENT.md +++ b/java-bigquery-jdbc/DEVELOPMENT.md @@ -16,6 +16,7 @@ This guide details the architectural design, core abstractions, coding principle - [Instantiating Loggers](#instantiating-loggers) - [Developer Logging Rules & Conventions](#developer-logging-rules--conventions) 5. [Pre-PR Checklist](#5-pre-pr-checklist) +6. [Agent Rules & Skills](#6-agent-rules--skills) --- @@ -32,7 +33,7 @@ graph TD Conn -->|Dynamic Context Proxy| Proxy[BigQueryJdbcContextProxy] Proxy -->|MDC Tracing| Mdc[BigQueryJdbcMdc] Proxy -->|Delegates Exec| DirectConn[Client Session] - Conn -->|Type Mapping & Coercion| Coercion[BigQueryJdbcTypeMappings & BigQueryCoercion] + Conn -->|Type Mapping & Coercion| Coercion[BigQueryTypeRegistry & TypeDescriptor] Conn -->|REST / Storage API| BQSDK[google-cloud-bigquery] ``` @@ -42,7 +43,7 @@ graph TD - **`BigQueryConnection`**: Represents an active BigQuery session, holding dataset defaults, connection configuration maps, and transaction/session state (`EnableSession=true`, `session_id`). - **`BigQueryJdbcUrlUtility`**: Parses and validates connection string parameters using a bounded LRU parse cache (`PARSE_CACHE`) to avoid heavy allocations during frequent connection creation. - **`BigQueryJdbcContextProxy`**: A dynamic proxy layer (`java.lang.reflect.Proxy`) wrapping JDBC statements, connections, and metadata. Intercepts calls to propagate ThreadLocal MDC parameters (`connectionId`) across execution threads and enforce state validation (`checkClosed()`). -- **`BigQueryJdbcTypeMappings` & `BigQueryCoercion`**: Centralized mapping logic handling standard JDBC-to-BigQuery SQL type mappings (`StandardSQLTypeName`) and object coercions (`Date`, `Timestamp`, `BigDecimal`, etc.). +- **`BigQueryTypeRegistry` & `TypeDescriptor`**: Centralized, bidirectional mapping between JDBC SQL types, Java classes and BigQuery types (`StandardSQLTypeName`), including the coercion of raw values (`Date`, `Timestamp`, `BigDecimal`, etc.) into the expected Java type. - **`BigQueryArrowResultSet`**: Custom result set implementation accelerating large query result retrieval via the BigQuery Storage Read API gRPC stream. --- @@ -73,7 +74,7 @@ make install # Clean project target directory make clean -# Format code and check linter compliance +# Format code in place (google-java-format) make lint ``` @@ -128,11 +129,11 @@ The driver uses a custom logging subsystem built on top of `java.util.logging`: ```java private final BigQueryJdbcCustomLogger LOG = new BigQueryJdbcCustomLogger(this.toString()); ``` -- **For Static / Utility Components** (`BigQueryJdbcUrlUtility`, `BigQueryJdbcTypeMappings`): +- **For Static / Utility Components** (for example `BigQueryJdbcUrlUtility`): Use the class name: ```java private static final BigQueryJdbcCustomLogger LOG = - new BigQueryJdbcCustomLogger(BigQueryJdbcTypeMappings.class.getName()); + new BigQueryJdbcCustomLogger(BigQueryJdbcUrlUtility.class.getName()); ``` ### Developer Logging Rules & Conventions @@ -176,4 +177,10 @@ Before submitting a Pull Request: - [ ] All method changes and feature additions are covered by corresponding JUnit 5 tests. - [ ] Unit tests pass cleanly without Mockito `UnnecessaryStubbingException` warnings. - [ ] All `Statement`, `ResultSet`, or `DatabaseMetaData` objects returned by public entry points are properly wrapped via `BigQueryJdbcContextProxy.wrap()`. -- [ ] Code formatting and linting pass via `make lint`. +- [ ] Code is formatted with `make lint`. + +--- + +## 6. Agent Rules & Skills + +AI coding agents that follow the `AGENTS.md` convention load [AGENTS.md](AGENTS.md) for this module. It carries the short form of the guardrails in section 2 and lists the shared agent skills in `.agents/skills/` (currently `bigquery-jdbc-testing` and `bigquery-jdbc-prepare-pr`), when each one applies, and how to add a new one.