update docs about the :batch feature

Author: uwemaurer

website/public/benchmark-postgres-insert.html

@@ -1,38 +1,49 @@
 <div class="benchmark-report">
   <style>
+    .benchmark-report, .benchmark-report * {
+      color-scheme: light only;
+    }
     .benchmark-report {
       font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
-      color: #111827;
+      color: #111827 !important;
+      background: #ffffff !important;
       line-height: 1.6;
+      padding: 2rem;
+      border-radius: 8px;
     }
     .benchmark-report .container {
       max-width: 1100px;
       margin: 0;
       background: transparent;
       padding: 0;
     }
-    h1 { font-size: 2rem; margin-bottom: 0.5rem; color: #111827; }
-    .subtitle { color: #6b7280; margin-bottom: 2rem; }
-    .chart-section { margin-top: 2rem; padding-top: 1.5rem; border-top: 2px solid #e5e7eb; }
-    .chart-section h2 { font-size: 1.25rem; margin-bottom: 0.75rem; }
-    .chart-container { max-width: 900px; margin: 0 auto 2rem; }
-    .batch-section { margin-top: 2rem; padding-top: 1.5rem; border-top: 2px solid #e5e7eb; }
-    .batch-section h2 { font-size: 1.25rem; margin-bottom: 0.75rem; }
-    .results-table { width: 100%; border-collapse: collapse; margin-bottom: 1rem; }
-    .results-table th, .results-table td {
+    .benchmark-report h1 { font-size: 2rem; margin-bottom: 0.5rem; color: #111827 !important; }
+    .benchmark-report h2 { color: #111827 !important; }
+    .benchmark-report h3 { color: #374151 !important; }
+    .benchmark-report p { color: #111827 !important; }
+    .benchmark-report .subtitle { color: #6b7280 !important; margin-bottom: 2rem; }
+    .benchmark-report .chart-section { margin-top: 2rem; padding-top: 1.5rem; border-top: 2px solid #e5e7eb; }
+    .benchmark-report .chart-section h2 { font-size: 1.25rem; margin-bottom: 0.75rem; }
+    .benchmark-report .chart-container { max-width: 900px; margin: 0 auto 2rem; }
+    .benchmark-report .batch-section { margin-top: 2rem; padding-top: 1.5rem; border-top: 2px solid #e5e7eb; }
+    .benchmark-report .batch-section h2 { font-size: 1.25rem; margin-bottom: 0.75rem; }
+    .benchmark-report .results-table { width: 100%; border-collapse: collapse; margin-bottom: 1rem; }
+    .benchmark-report .results-table th, .benchmark-report .results-table td {
       padding: 0.5rem 0.75rem; text-align: left;
       border-bottom: 1px solid #e5e7eb; font-size: 0.875rem;
+      color: #111827 !important;
     }
-    .results-table th { background: #f9fafb; font-weight: 600; color: #374151; }
-    .results-table td.number { text-align: right; font-variant-numeric: tabular-nums; }
-    .winner { font-weight: 600; color: #10b981; }
-    .system-info { margin-top: 2rem; padding-top: 2rem; border-top: 2px solid #e5e7eb; }
-    .system-info h3 { font-size: 1.125rem; margin-bottom: 0.75rem; color: #374151; }
-    .system-table { width: 100%; border-collapse: collapse; }
-    .system-table td {
+    .benchmark-report .results-table th { background: #f9fafb; font-weight: 600; color: #374151 !important; }
+    .benchmark-report .results-table td.number { text-align: right; font-variant-numeric: tabular-nums; }
+    .benchmark-report .winner td { font-weight: 600; color: #10b981 !important; }
+    .benchmark-report .system-info { margin-top: 2rem; padding-top: 2rem; border-top: 2px solid #e5e7eb; }
+    .benchmark-report .system-info h3 { font-size: 1.125rem; margin-bottom: 0.75rem; color: #374151 !important; }
+    .benchmark-report .system-table { width: 100%; border-collapse: collapse; }
+    .benchmark-report .system-table td {
       padding: 0.375rem 0.5rem; border-bottom: 1px solid #e5e7eb; font-size: 0.875rem;
+      color: #111827 !important;
     }
-    .system-table td:first-child { font-weight: 600; color: #6b7280; width: 160px; }
+    .benchmark-report .system-table td:first-child { font-weight: 600; color: #6b7280 !important; width: 160px; }
   </style>
   <script src="https://cdn.jsdelivr.net/npm/chart.js@4"></script>
   <div class="container">

website/src/components/BenchmarkReport.astro

@@ -45,15 +45,11 @@ const styles = styleMatch ? styleMatch[1] : "";
 <style>
   .benchmark-report-wrapper {
     margin: 2rem 0;
-    border: 1px solid #e5e7eb;
-    border-radius: 8px;
     overflow: hidden;
-    background: white;
   }
-  
+
   .benchmark-report-wrapper :global(.container) {
     margin: 0;
-    padding: 2rem;
     box-shadow: none;
   }
 </style>

website/src/content/docs/generators/java-jdbc.mdx

@@ -187,6 +187,47 @@ The generator creates a single Java file with:
 
 All types are nullable (using wrapper classes).
 
+## Batch EXEC (`:batch`)
+
+Add the `:batch` modifier to any `EXEC` to also generate a JDBC batch method. The single-row method is kept alongside it, so callers can pick per use case. Works with any JDBC database (SQLite, DuckDB, PostgreSQL, ...).
+
+```sql
+-- EXEC insert_user :batch
+@set id = 'u1'
+@set name = 'Alice'
+@set email = 'alice@example.com'
+INSERT INTO users (id, name, email) VALUES (${id}, ${name}, ${email});
+```
+
+Multi-parameter EXECs generate a params record so call sites stay readable:
+
+```java
+public record InsertUserParams(String id, String name, String email) {}
+
+public int insertUser(String id, String name, String email) throws SQLException { ... }
+
+public int[] insertUserBatch(Iterable<InsertUserParams> params) throws SQLException { ... }
+```
+
+Single-parameter EXECs skip the record:
+
+```sql
+-- EXEC delete_user :batch
+@set id = 'u1'
+DELETE FROM users WHERE id = ${id};
+```
+
+```java
+public int[] deleteUserBatch(Iterable<String> params) throws SQLException { ... }
+```
+
+Parameters are bound with typed JDBC setters (`setInt`, `setString`, `setLong`, ...) based on the inferred Java type, falling back to `setObject` for types without a typed setter (`LocalDate`, `OffsetDateTime`, `BigDecimal`, `UUID`, list/array types). Typed setters skip the driver's per-row type inspection, which is noticeable on large batches.
+
+**When to use:**
+- `:batch` works for INSERT, UPDATE, and DELETE on any JDBC database.
+- For PostgreSQL INSERTs, add `?reWriteBatchedInserts=true` to your JDBC URL for ~2.5× throughput — the driver automatically rewrites batches into multi-VALUES statements.
+- For the fastest PostgreSQL INSERTs, use [`TABLE ... :appender`](#bulk-inserts-postgresql) (COPY BINARY) instead — typically 5–20× faster than `:batch`. See the [PostgreSQL insert benchmark](/blog/java-postgres-insert-benchmark/) for the numbers.
+
 ## PostgreSQL
 
 SQG supports PostgreSQL via the `java/postgres` generator. PostgreSQL-specific features include:

website/src/content/docs/guides/sql-syntax.mdx

@@ -152,6 +152,8 @@ UPDATE users SET active = false WHERE id = ${id};
 - Database-specific result type (e.g., `RunResult` for SQLite)
 - Typically includes `changes` count and `lastInsertRowid`
 
+Add `:batch` to additionally generate a JDBC batch method — see the [`:batch`](#batch) modifier below.
+
 ### TABLE (Bulk Inserts)
 
 Generate high-performance bulk insert code for DuckDB and PostgreSQL tables. Provides significantly faster inserts than individual INSERT statements.
@@ -245,6 +247,52 @@ SELECT id FROM users;
 getUserIds(): (number | null)[]
 ```
 
+### :batch
+
+Applies to `EXEC` statements only. Generates an additional `<name>Batch(...)` method that uses JDBC's `addBatch()` / `executeBatch()` to send many rows in one round trip. The regular single-row method is still generated alongside it.
+
+**Java only** — ignored by the TypeScript and Python generators.
+
+```sql
+-- EXEC insert_user :batch
+@set id = 'u1'
+@set name = 'Alice'
+@set email = 'alice@example.com'
+INSERT INTO users (id, name, email) VALUES (${id}, ${name}, ${email});
+```
+
+For queries with multiple parameters, SQG generates a params record to keep call sites readable:
+
+```java
+// Generated
+public record InsertUserParams(String id, String name, String email) {}
+
+public int[] insertUserBatch(Iterable<InsertUserParams> params) throws SQLException { ... }
+```
+
+```java
+queries.insertUserBatch(List.of(
+    new MyApp.InsertUserParams("u1", "Alice", "alice@example.com"),
+    new MyApp.InsertUserParams("u2", "Bob",   "bob@example.com")
+));
+```
+
+Single-parameter EXECs skip the record wrapper:
+
+```sql
+-- EXEC delete_user :batch
+@set id = 'u1'
+DELETE FROM users WHERE id = ${id};
+```
+
+```java
+queries.deleteUserBatch(List.of("u1", "u2", "u3"));
+```
+
+**When to use which:**
+- `:batch` — general-purpose; works for INSERT, UPDATE, and DELETE on any JDBC database. For PostgreSQL, add `?reWriteBatchedInserts=true` to the JDBC URL for ~2.5× throughput on batched INSERTs (see the [insert benchmark](/blog/java-postgres-insert-benchmark/)).
+- `TABLE ... :appender` — INSERT-only, DuckDB and PostgreSQL only, typically 5–20× faster than `:batch` because it bypasses SQL parsing entirely (COPY BINARY / DuckDB appender API).
+
 ### Combining Modifiers
 
 Modifiers can be combined: