[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill-cockroachdb-designing-application-transactions":3,"mdc--uhkat1-key":36,"related-org-cockroachdb-designing-application-transactions":3711,"related-repo-cockroachdb-designing-application-transactions":3871},{"slug":4,"name":4,"fn":5,"description":6,"org":7,"tags":11,"stars":22,"repoUrl":23,"updatedAt":24,"license":25,"forks":26,"topics":27,"repo":31,"sourceUrl":34,"mdContent":35},"designing-application-transactions","design performant CockroachDB transaction patterns","Guides application developers in designing correct and performant transaction patterns for CockroachDB, covering transaction lifetime, implicit vs explicit transactions, retry handling with exponential backoff, pushing invariants into SQL, selective pessimistic locking, set-based operations, connection pooling, prepared statements, keyset pagination, follower reads, and separating business logic from database logic. Use when building applications on CockroachDB, designing transaction workflows, handling retries, optimizing application-layer database interactions, or configuring connection pools.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},"cockroachdb","CockroachDB","https:\u002F\u002Fpexgzepcugksgbtrxkhf.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Forg-logos\u002Fcockroachdb.png",[12,16,19],{"name":13,"slug":14,"type":15},"Performance","performance","tag",{"name":17,"slug":18,"type":15},"Database","database",{"name":20,"slug":21,"type":15},"Engineering","engineering",3,"https:\u002F\u002Fgithub.com\u002Fcockroachdb\u002Fclaude-plugin","2026-07-12T07:57:27.903242",null,2,[28,29,8,30],"claude","cockroach-cloud","developer-tools",{"repoUrl":23,"stars":22,"forks":26,"topics":32,"description":33},[28,29,8,30],"CockroachDB development plugin for Claude","https:\u002F\u002Fgithub.com\u002Fcockroachdb\u002Fclaude-plugin\u002Ftree\u002FHEAD\u002Fskills\u002Fcockroachdb-application-development\u002Fdesigning-application-transactions","---\nname: designing-application-transactions\ndescription: Guides application developers in designing correct and performant transaction patterns for CockroachDB, covering transaction lifetime, implicit vs explicit transactions, retry handling with exponential backoff, pushing invariants into SQL, selective pessimistic locking, set-based operations, connection pooling, prepared statements, keyset pagination, follower reads, and separating business logic from database logic. Use when building applications on CockroachDB, designing transaction workflows, handling retries, optimizing application-layer database interactions, or configuring connection pools.\ncompatibility: \"CockroachDB >= 22.1. Works with or without a live database connection. With connection, requires appropriate privileges on target tables.\"\nmetadata:\n author: cockroachdb\n version: \"1.0\"\n---\n\n# Designing Application Transactions\n\nGuides application developers through the design principles and implementation patterns needed to build correct, performant, and resilient applications on CockroachDB. Covers the full spectrum from transaction scoping and retry logic to connection pooling and observability.\n\n**Complement to SQL skills:** For SQL syntax, schema design, and query optimization, see [cockroachdb-sql](..\u002F..\u002Fcockroachdb-query-and-schema-design\u002Fcockroachdb-sql\u002FSKILL.md). For benchmarking transaction formulations under contention, see [benchmarking-transaction-patterns](..\u002Fbenchmarking-transaction-patterns\u002FSKILL.md).\n\n## When to Use This Skill\n\n- Designing transaction boundaries for a CockroachDB application\n- Implementing client-side retry logic with exponential backoff\n- Deciding between implicit and explicit transactions\n- Choosing between optimistic and pessimistic concurrency control\n- Replacing read-modify-write loops with atomic SQL\n- Configuring connection pools (HikariCP, pgbouncer, etc.)\n- Implementing keyset pagination instead of OFFSET\u002FLIMIT\n- Using follower reads for reporting and analytics queries\n- Separating business orchestration from database transactions\n- Using prepared statements for performance and security\n- Selecting explicit column projections instead of SELECT *\n- Testing application behavior under concurrency\n- Monitoring application-level database performance\n\n## Prerequisites\n\n- Familiarity with CockroachDB's SERIALIZABLE isolation level\n- Understanding of ACID transaction semantics\n- Access to application source code for transaction design changes\n- SQL connection to a CockroachDB cluster (for testing and validation)\n\n## Steps\n\n### 1. Keep Transactions Short-Lived\n\nTransactions must include only the minimal set of SQL operations needed for one atomic state change. Do not place remote API calls, service-to-service requests, loops, expensive computation, or artificial waits inside a CockroachDB transaction.\n\nLong-lived transactions increase intent lifetime, contention, and retry probability in CockroachDB's distributed, optimistic-concurrency architecture.\n\n**Anti-pattern:**\n\n```java\n@Transactional\npublic void createOrder(Order order) {\n orderRepository.save(order);\n paymentGateway.charge(order); \u002F\u002F external call inside TX\n}\n```\n\n**Correct approach — split the logic:**\n\n```java\n@Transactional\npublic void createOrderRecord(Order order) {\n orderRepository.save(order);\n}\n\n\u002F\u002F Outside the transaction\npaymentGateway.charge(order);\n```\n\n**Why it matters:**\n- Active intents block concurrent writers, reducing cluster throughput\n- Competing transactions are more likely to encounter `40001` retry errors\n- External work inside a retried transaction may run twice, causing duplicate side effects\n- Long transactions tie up connections and memory, reducing concurrency\n\n### 2. Use Implicit Transactions for Single Statements\n\nCockroachDB automatically wraps each individual SQL statement as a transaction in autocommit mode. For single `INSERT`, `UPDATE`, `DELETE`, or `SELECT` statements, do not wrap in explicit `BEGIN`\u002F`COMMIT`.\n\n**Preferred:**\n\n```sql\nINSERT INTO orders (id, status)\nVALUES (gen_random_uuid(), 'open');\n```\n\n**Avoid:**\n\n```sql\nBEGIN;\nINSERT INTO orders (id, status)\nVALUES (gen_random_uuid(), 'open');\nCOMMIT;\n```\n\n**Benefits:** Simpler code paths, lower latency (fewer round trips), less resource usage, and fewer retry concerns since single-statement transactions are easier for CockroachDB to retry automatically.\n\n### 3. Use Explicit Transactions for Grouped Statements and Handle Retries\n\nWhen multiple SQL operations must succeed or fail together, use explicit transactions with `BEGIN`\u002F`COMMIT`. Because CockroachDB defaults to SERIALIZABLE isolation, transaction retries are a normal part of correct execution under contention.\n\n```sql\nBEGIN;\n UPDATE accounts SET balance = balance - 100 WHERE id = 1;\n UPDATE accounts SET balance = balance + 100 WHERE id = 2;\nCOMMIT;\n```\n\n**Client-side retry loop with exponential backoff:**\n\n```python\nimport random\nimport time\n\ndef execute_with_retry(conn, txn_logic):\n backoff = 0.1\n while True:\n try:\n with conn.transaction() as txn:\n txn_logic(txn)\n return\n except SerializationFailure:\n time.sleep(backoff + random.uniform(0, 0.1))\n backoff = min(backoff * 2, 2.0)\n```\n\n**Advanced retry with the cockroach_restart savepoint protocol:**\n\n```sql\nBEGIN;\nSAVEPOINT cockroach_restart;\n-- transactional work\nRELEASE SAVEPOINT cockroach_restart;\nCOMMIT;\n```\n\n**WARNING: Generic savepoints do NOT work as retry mechanisms.** CockroachDB aborts the entire transaction on a `40001` serialization failure. Using `ROLLBACK TO SAVEPOINT` on a regular savepoint cannot recover -- the transaction remains in an aborted state. Only the special `SAVEPOINT cockroach_restart` protocol (where the client catches the error, rolls back to the savepoint, and re-executes the work) is supported. For most applications, a full-transaction retry loop is simpler and recommended.\n\n**SQLSTATE guidance:**\n\n| Code | Meaning | Action |\n|-----------------|-----------------------------------------|-------------------------------------------------------|\n| `40001` | Serialization \u002F retryable | Retry the entire unit of work with backoff and jitter |\n| `40003` | Ambiguous result \u002F indeterminate commit | Do not blindly replay non-idempotent work |\n| `08xx` \u002F `57xx` | Network or server transient issues | Retry carefully, account for ambiguous commits |\n| `23xxx` | Constraint and application errors | Usually should not be retried |\n\n### 4. Mark Read-Only Transactions Where Applicable\n\nRead-only transactions perform retrieval only and make no writes. Marking them as read-only allows CockroachDB to avoid unnecessary write intents, reduce contention with writers, and enable follower or bounded-staleness reads.\n\n```sql\nBEGIN;\nSET TRANSACTION READ ONLY;\nSELECT * FROM customers WHERE region = 'US-East';\nCOMMIT;\n```\n\n### 5. Push Invariants into SQL — Avoid Read-Modify-Write Loops\n\nDo not fetch state into application code, modify it in memory, and write it back. Prefer atomic SQL, constraints, guarded UPDATEs, UPSERT, INSERT ... ON CONFLICT, and CTE-based mutations.\n\n**Anti-pattern:**\n\n```python\nbalance = db.fetch(\"SELECT balance FROM accounts WHERE id = 123\")\nbalance += 100\ndb.execute(\"UPDATE accounts SET balance = %s WHERE id = 123\", (balance,))\n```\n\n**Preferred atomic SQL:**\n\n```sql\nUPDATE accounts\nSET balance = balance + 100\nWHERE id = 123;\n```\n\n**Guarded write with invariant enforcement:**\n\n```sql\nUPDATE customer_daily_limits\nSET used_total = used_total + $2\nWHERE customer_id = $1\n AND day = current_date\n AND used_total + $2 \u003C= daily_limit;\n```\n\n**Atomic CTE pattern:**\n\n```sql\nWITH limit_row AS (\n SELECT customer_id, day\n FROM customer_daily_limits\n WHERE customer_id = $1 AND day = current_date\n FOR UPDATE\n), spend AS (\n UPDATE customer_daily_limits AS l\n SET remaining_limit = l.remaining_limit - $2,\n used_total = l.used_total + $2\n FROM limit_row\n WHERE l.customer_id = limit_row.customer_id\n AND l.day = limit_row.day\n AND l.remaining_limit >= $2\n RETURNING l.customer_id, l.day\n), ins AS (\n INSERT INTO transfers (customer_id, amount, direction, created_at)\n SELECT $1, $2, 'debit', now()\n FROM spend\n RETURNING id AS transfer_id\n)\nSELECT transfer_id FROM ins;\n```\n\n**Key approaches:**\n- Use atomic updates: `UPDATE ... SET col = col + 1`\n- Use version or timestamp checks in WHERE clauses for optimistic concurrency\n- Enforce business rules with `UNIQUE`, `CHECK`, `NOT NULL`, and `FOREIGN KEY` constraints\n- Use `UPSERT` or `INSERT ... ON CONFLICT` instead of read-before-write existence checks\n- Use CTEs to keep multi-step logic atomic\n\n### 6. Use SELECT ... FOR UPDATE Selectively\n\nCockroachDB defaults to optimistic concurrency, which works well for most workloads. For hot rows or contention-heavy read-before-write paths, `SELECT ... FOR UPDATE` reduces retry churn by making contenders wait instead of race.\n\n```sql\nBEGIN;\nSELECT balance FROM accounts WHERE id = 1 FOR UPDATE;\nUPDATE accounts SET balance = balance - 100 WHERE id = 1;\nCOMMIT;\n```\n\n**Use when:**\n- The same rows are updated frequently by many concurrent transactions\n- Optimistic retries are causing thrashing\n- Consistency before write is required (inventory, financial transfers)\n\n**Counterintuitive contention insight:** Adding more application pods or threads targeting the same hot rows does NOT increase throughput -- it decreases it. With N concurrent writers on the same row, only 1 can commit per round; the other N-1 are aborted with `40001` and must retry. More concurrency on hot data means more wasted work and lower TPS. Solutions: use `SELECT ... FOR UPDATE` to serialize access, use atomic `UPDATE SET balance = balance + amount` to eliminate the read-modify-write cycle, or distribute writes across multiple rows.\n\n**Trade-off:** Overusing pessimistic locks can introduce waiting chains or deadlocks. Reserve for hot paths and contention-heavy workloads.\n\n### 7. Use Set-Based Operations Over Row-by-Row Loops\n\nCockroachDB performs best with set-oriented SQL rather than many small client-driven statements. This reduces round trips, shortens contention windows, and improves throughput.\n\n**Row-by-row anti-pattern:**\n\n```python\nfor row in rows:\n db.execute(\n \"UPDATE accounts SET balance = balance + 10 WHERE id = %s\",\n (row.id,)\n )\n```\n\n**Set-based preferred:**\n\n```sql\nUPDATE accounts\nSET balance = balance + 10\nWHERE region = 'US-East';\n```\n\n**Batch INSERT:**\n\n```sql\nINSERT INTO trades (id, symbol, price)\nVALUES\n (1, 'AAPL', 180),\n (2, 'GOOG', 125),\n (3, 'AMZN', 140);\n```\n\n**Batch UPDATE with UNNEST:**\n\n```sql\nWITH incoming AS (\n SELECT *\n FROM UNNEST(\n ARRAY['u1', 'u2', 'u3']::STRING[],\n ARRAY['active', 'inactive', 'active']::STRING[]\n ) AS t(id, new_status)\n)\nUPDATE users AS u\nSET status = incoming.new_status,\n updated_at = now()\nFROM incoming\nWHERE u.id = incoming.id;\n```\n\n**Maintenance batching with LIMIT:**\n\n```sql\nDELETE FROM sessions\nWHERE expires_at \u003C now()\nORDER BY expires_at\nLIMIT 10000;\n```\n\n`ORDER BY` keeps the batch deterministic so successive runs make forward progress; without it, CockroachDB may pick a different subset each iteration.\n\n**JDBC batching (Java):** Use `addBatch`\u002F`executeBatch` instead of per-row `executeUpdate`. This sends all rows in a single network round trip rather than N individual round trips, eliminating idle time that can account for ~50% of transaction latency in chatty workloads.\n\n**Declarative TTL:**\n\n```sql\n-- created_at must be TIMESTAMPTZ; the expression's result type must also be TIMESTAMPTZ.\n-- Cast if the source column is plain TIMESTAMP.\nALTER TABLE events\nSET (ttl_expiration_expression = '(created_at + INTERVAL ''7 DAY'')::TIMESTAMPTZ');\n```\n\n### 8. Use Follower Reads for Non-Critical Queries\n\nMany analytics, dashboard, and display-oriented queries do not need the absolute latest value. CockroachDB supports follower reads and bounded-staleness reads from follower replicas with lower latency.\n\n**Basic follower read:**\n\n```sql\nSELECT * FROM orders\nAS OF SYSTEM TIME '-5s';\n```\n\n**Bounded staleness:**\n\n```sql\nSELECT * FROM inventory\nAS OF SYSTEM TIME with_max_staleness(INTERVAL '10s');\n```\n\n**Read-write split pattern for heavy reads:** When a workflow reads a large payload (e.g., KYC JSON document) and then updates a status field, split it into three phases: (1) read outside the transaction with `AS OF SYSTEM TIME` for a conflict-free snapshot, (2) process in the application layer, (3) start a short write-only transaction. This avoids holding write intents during the heavy read.\n\n**Use when:** Dashboards, analytics, ETL, display-only reads, or large-payload workflows where the read and write can be separated.\n\n**Avoid when:** The workflow requires the latest transactional state for a subsequent write decision.\n\n### 9. Use Keyset Pagination Instead of OFFSET\u002FLIMIT\n\nAs the OFFSET grows, CockroachDB must scan and discard more rows. Keyset pagination uses the last row's ordered key values to jump directly to the next page.\n\n**OFFSET\u002FLIMIT (inefficient at depth):**\n\n```sql\nSELECT id, order_date, customer_id\nFROM orders\nORDER BY id\nLIMIT 100 OFFSET 5000;\n```\n\n**Keyset pagination (preferred):**\n\n```sql\nSELECT id, order_date, customer_id\nFROM orders\nWHERE id > 5000\nORDER BY id\nLIMIT 100;\n```\n\n**Multi-column keyset:**\n\n```sql\nSELECT id, created_at, customer_id\nFROM orders\nWHERE (created_at, id) > ('2025-01-01 00:00:00', 5000)\nORDER BY created_at, id\nLIMIT 100;\n```\n\n**Trade-off:** Keyset pagination is ideal for next\u002Fprevious navigation but not for arbitrary \"jump to page 73\" UX.\n\n### 10. Use Prepared Statements for Performance and Security\n\nPrepared statements reuse query structure and bind new values, improving performance through plan reuse and protecting against SQL injection.\n\n**Unsafe dynamic string concatenation:**\n\n```python\nquery = f\"SELECT * FROM users WHERE username = '{user_input}'\"\ncursor.execute(query)\n```\n\n**Prepared \u002F parameterized execution:**\n\n```python\ncursor.execute(\"SELECT * FROM users WHERE username = %s;\", (user_input,))\n```\n\n**Plan reuse:**\n\n```sql\nPREPARE get_balance AS\nSELECT balance FROM accounts WHERE id = $1;\n\nEXECUTE get_balance(1001);\nEXECUTE get_balance(2002);\n```\n\n### 11. Use Column Projections Instead of SELECT *\n\nSelect only the columns you need. `SELECT *` increases network payload, memory usage, CPU cost, and prevents narrower index-only scans.\n\n```sql\n-- Avoid\nSELECT * FROM users WHERE id = 101;\n\n-- Preferred\nSELECT name, email FROM users WHERE id = 101;\n```\n\n**Schema evolution impact:** If a later schema change adds `profile_picture BYTEA`, queries using `SELECT *` automatically pull that extra data. Explicit projections avoid this hidden performance regression.\n\n### 12. Design Keys and Indexes to Distribute Load\n\nSequential or monotonically increasing primary keys create write hotspots. Keys and indexes should distribute reads and writes across ranges evenly.\n\n**Hotspot anti-pattern:**\n\n```sql\nCREATE TABLE orders (\n id SERIAL PRIMARY KEY,\n customer_id UUID,\n region STRING\n);\n```\n\n**Randomized key:**\n\n```sql\nCREATE TABLE orders (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n customer_id UUID,\n region STRING\n);\n```\n\n**Hash-sharded index:**\n\n```sql\nCREATE INDEX orders_by_id_hash\nON orders (id)\nUSING HASH SHARDED WITH BUCKET_COUNT = 16;\n```\n\n**Composite key for natural distribution:**\n\n```sql\nCREATE TABLE sales (\n region_id STRING,\n order_id UUID DEFAULT gen_random_uuid(),\n PRIMARY KEY (region_id, order_id)\n);\n```\n\n**Enforce explicit PKs cluster-wide:**\n\n```sql\nSET CLUSTER SETTING sql.defaults.require_explicit_primary_keys.enabled = true;\n```\n\n### 13. Configure Connection Pooling\n\nOpening new database connections is expensive. Pooling reuses live connections to improve performance and prevent overload.\n\n**HikariCP guidance:**\n\n```yaml\nmaximumPoolSize: (vCPUs * 4) \u002F number_of_pool_instances\nminimumIdle: equal to maximumPoolSize\nmaxLifetime: 30 min (add jitter +\u002F- 5 min)\nidleTimeout: 5-10 min typical\nkeepaliveTime: slightly shorter than infrastructure timeout (~5 min)\nconnectionTimeout: 10-30 s typical\nautoCommit: true unless using explicit transactions only\n```\n\n**Example stable configuration:**\n\n```yaml\nmaximum-pool-size: 12\nminimum-idle: 12\nmax-lifetime: 1800000\nidle-timeout: 600000\nkeepalive-time: 300000\nconnection-timeout: 10000\nauto-commit: true\npool-name: ingestionPool\n```\n\n### 14. Separate Business Logic from Database Logic\n\nCockroachDB should manage ACID reads, writes, and schema-level integrity. The application layer should orchestrate workflows, external services, queues, and long-running work.\n\n**Inside the transaction:**\n- Reads, writes, constraints, short guarded state transitions\n\n**Outside the transaction:**\n- HTTP calls, RPC\u002Fservice calls, email, payment providers, queue publishing\n\n**Asynchronous workflow pattern:**\n\n```python\ndef handle_order(order):\n db.execute(\"INSERT INTO orders (id, status) VALUES (%s, %s)\", (order.id, 'PENDING'))\n publish_event('process_order', {'order_id': order.id})\n```\n\n### 15. Respect the 16MB Transaction Payload Limit\n\nCockroachDB has a practical limit of ~16MB per transaction payload. This limit applies to the TOTAL data written in a single transaction, not just individual rows.\n\n**Two ways to hit the limit:**\n- One large row (e.g., a 15MB JSON document)\n- Many moderate rows in one transaction (e.g., 25 INSERTs of 500KB each = 12.5MB)\n\n**Guidelines:**\n- Keep individual rows under 1MB\n- Keep total transaction payload under 4MB\n- Limit transactions to \u003C10 statements\n- Chunk large documents into 64-256KB pieces\n- Store blobs >1MB in object storage (S3\u002FGCS) with a database reference\n- Break multi-statement transactions into smaller batches (commit every 5-10 statements)\n\n**Exceeding the limit causes `split failed while applying backpressure to Put` errors:** large Raft proposals block consensus, range splits stall, and the system applies backpressure.\n\n### 16. Use Session Guardrails\n\nSet session-level guardrails to catch runaway queries and missing WHERE clauses during development and testing:\n\n```sql\nSET transaction_rows_read_err = 10000;\nSET transaction_rows_written_err = 1000;\n```\n\nThese cause transactions that exceed the thresholds to fail with an explicit error rather than silently consuming cluster resources.\n\n### 17. Test and Optimize Under Concurrency\n\nSingle-user correctness is not sufficient. Test with realistic concurrency to surface retries, hotspots, contention, and workload-specific bottlenecks.\n\n**Quick start:**\n\n```bash\ncockroach workload init bank 'postgresql:\u002F\u002Froot@localhost:26257?sslmode=disable'\ncockroach workload run bank --concurrency=64 --duration=10m\n```\n\nSee [monitoring-and-concurrency-testing](references\u002Fmonitoring-and-concurrency-testing.md) for detailed contention queries, validation checklists, and Prometheus metrics.\n\n### 18. Monitor for Performance and Contention\n\nActively monitor query latency, contention, retries, and data distribution using `EXPLAIN ANALYZE`, `crdb_internal.transaction_contention_events`, DB Console SQL Activity, and Key Visualizer.\n\nSee [monitoring-and-concurrency-testing](references\u002Fmonitoring-and-concurrency-testing.md) for live contention queries, Prometheus metrics, and external monitoring integration.\n\n## Decision Guide\n\n| Scenario | Recommended Pattern |\n|---------------------------------------------|--------------------------------------|\n| Single SQL statement | Implicit transaction (autocommit) |\n| Multiple statements, all-or-nothing | Explicit transaction with retry loop |\n| Read current state before write on hot rows | `SELECT ... FOR UPDATE` |\n| Historical, display, or reporting read | `AS OF SYSTEM TIME` \u002F follower reads |\n| Batch of records in memory | `UNNEST` \u002F `VALUES` \u002F batch SQL |\n| Multi-step business rule in one operation | Single-statement CTE |\n\n## Safety Considerations\n\n- Always implement retry logic for `40001` serialization errors\n- Make operations idempotent so retries do not cause duplicate side effects (use `INSERT ... ON CONFLICT DO NOTHING`)\n- Do not use stale snapshot reads as authoritative preconditions for writes\n- Do not run `EXPLAIN ANALYZE` on production queries that modify data\n- Be cautious adding indexes to high-traffic tables during peak hours\n\n## References\n\n- [CockroachDB Transactions Documentation](https:\u002F\u002Fwww.cockroachlabs.com\u002Fdocs\u002Fstable\u002Ftransactions)\n- [Advanced Client-Side Transaction Retries](https:\u002F\u002Fwww.cockroachlabs.com\u002Fdocs\u002Fstable\u002Fadvanced-client-side-transaction-retries)\n- [SQL Performance Best Practices](https:\u002F\u002Fwww.cockroachlabs.com\u002Fdocs\u002Fstable\u002Fperformance-best-practices-overview)\n- [Follower Reads and Bounded Staleness](https:\u002F\u002Fwww.cockroachlabs.com\u002Fdocs\u002Fstable\u002Ffollower-reads)\n- [Optimize Statement Performance](https:\u002F\u002Fwww.cockroachlabs.com\u002Fdocs\u002Fstable\u002Fmake-queries-fast)\n- [Row-Level TTL](https:\u002F\u002Fwww.cockroachlabs.com\u002Fdocs\u002Fstable\u002Frow-level-ttl)\n- [Schema Design and Indexes](https:\u002F\u002Fwww.cockroachlabs.com\u002Fdocs\u002Fstable\u002Fschema-design-indexes)\n- [SQL Injection Prevention](https:\u002F\u002Fwww.cockroachlabs.com\u002Fdocs\u002Fstable\u002Fsql-injection-prevention)\n- [Architecture: Transaction Layer](https:\u002F\u002Fwww.cockroachlabs.com\u002Fdocs\u002Fstable\u002Farchitecture\u002Ftransaction-layer)\n- [JPA Best Practices: Explicit and Implicit Transactions](https:\u002F\u002Fblog.cloudneutral.se\u002Fjpa-best-practices-explicit-and-implicit-transactions)\n- [Deep Dive into Transaction Retry Failures](https:\u002F\u002Fwww.mindfulchase.com\u002Fexplore\u002Ftroubleshooting-tips\u002Fdatabases\u002Fdeep-dive-into-transaction-retry-failures-in-cockroachdb-root-causes-and-fixes.html)\n- [Comparing Multi-Statement vs Single-Statement Transactions](https:\u002F\u002Fandrewdeally.medium.com\u002Fcomparing-multi-statement-vs-single-statement-transactions-for-account-transfers-in-sql-09190b116e64)\n- [Set-Based Operations with CockroachDB](https:\u002F\u002Fandrewdeally.medium.com\u002Fset-based-operations-with-cockroachdb-c9f371992dc7)\n- [Bulk Rewrites with the CockroachDB JDBC Driver](https:\u002F\u002Fblog.cloudneutral.se\u002Fcockroachdb-jdbc-driver-part-iii-bulk-rewrites)\n- [What is a Database Hotspot?](https:\u002F\u002Fwww.cockroachlabs.com\u002Fblog\u002Fthe-hot-content-problem-metadata-storage-for-media-streaming\u002F)\n- [CockroachDB Transaction Demo](https:\u002F\u002Fgithub.com\u002Fcockroachdb\u002Fcockroach-transaction-demo)\n- [CockroachDB Best Practices & Anti-Patterns Demo](https:\u002F\u002Fgithub.com\u002Fviragtripathi\u002Fcockroachdb-best-practices-demo) -- 10 runnable Java demos covering retries, batching, PK hotspots, guardrails, chunking, and multi-region\n- [CockroachDB JDBC Wrapper](https:\u002F\u002Fgithub.com\u002Fviragtripathi\u002Fcockroachdb-jdbc-wrapper) -- automatic retry library for Java\u002FJDBC applications\n",{"data":37,"body":41},{"name":4,"description":6,"compatibility":38,"metadata":39},"CockroachDB >= 22.1. Works with or without a live database connection. With connection, requires appropriate privileges on target tables.",{"author":8,"version":40},"1.0",{"type":42,"children":43},"root",[44,52,58,86,93,163,169,192,198,205,210,215,223,280,288,351,359,390,396,447,455,480,488,525,535,541,559,596,604,722,730,775,808,816,944,950,955,992,998,1003,1010,1041,1049,1080,1088,1135,1143,1326,1334,1414,1420,1433,1470,1478,1496,1528,1538,1544,1549,1557,1604,1612,1642,1650,1697,1705,1807,1815,1854,1865,1898,1906,1945,1951,1956,1964,1987,1995,2018,2036,2045,2055,2061,2066,2074,2113,2121,2165,2173,2218,2227,2233,2238,2246,2269,2277,2291,2299,2345,2351,2364,2410,2435,2441,2446,2454,2501,2509,2552,2560,2591,2599,2645,2653,2667,2673,2678,2686,2818,2826,2970,2976,2981,2989,2997,3005,3013,3021,3052,3058,3063,3071,3084,3092,3125,3143,3149,3154,3177,3182,3188,3193,3201,3279,3292,3298,3318,3328,3334,3455,3461,3511,3517,3705],{"type":45,"tag":46,"props":47,"children":48},"element","h1",{"id":4},[49],{"type":50,"value":51},"text","Designing Application Transactions",{"type":45,"tag":53,"props":54,"children":55},"p",{},[56],{"type":50,"value":57},"Guides application developers through the design principles and implementation patterns needed to build correct, performant, and resilient applications on CockroachDB. Covers the full spectrum from transaction scoping and retry logic to connection pooling and observability.",{"type":45,"tag":53,"props":59,"children":60},{},[61,67,69,76,78,84],{"type":45,"tag":62,"props":63,"children":64},"strong",{},[65],{"type":50,"value":66},"Complement to SQL skills:",{"type":50,"value":68}," For SQL syntax, schema design, and query optimization, see ",{"type":45,"tag":70,"props":71,"children":73},"a",{"href":72},"..\u002F..\u002Fcockroachdb-query-and-schema-design\u002Fcockroachdb-sql\u002FSKILL.md",[74],{"type":50,"value":75},"cockroachdb-sql",{"type":50,"value":77},". For benchmarking transaction formulations under contention, see ",{"type":45,"tag":70,"props":79,"children":81},{"href":80},"..\u002Fbenchmarking-transaction-patterns\u002FSKILL.md",[82],{"type":50,"value":83},"benchmarking-transaction-patterns",{"type":50,"value":85},".",{"type":45,"tag":87,"props":88,"children":90},"h2",{"id":89},"when-to-use-this-skill",[91],{"type":50,"value":92},"When to Use This Skill",{"type":45,"tag":94,"props":95,"children":96},"ul",{},[97,103,108,113,118,123,128,133,138,143,148,153,158],{"type":45,"tag":98,"props":99,"children":100},"li",{},[101],{"type":50,"value":102},"Designing transaction boundaries for a CockroachDB application",{"type":45,"tag":98,"props":104,"children":105},{},[106],{"type":50,"value":107},"Implementing client-side retry logic with exponential backoff",{"type":45,"tag":98,"props":109,"children":110},{},[111],{"type":50,"value":112},"Deciding between implicit and explicit transactions",{"type":45,"tag":98,"props":114,"children":115},{},[116],{"type":50,"value":117},"Choosing between optimistic and pessimistic concurrency control",{"type":45,"tag":98,"props":119,"children":120},{},[121],{"type":50,"value":122},"Replacing read-modify-write loops with atomic SQL",{"type":45,"tag":98,"props":124,"children":125},{},[126],{"type":50,"value":127},"Configuring connection pools (HikariCP, pgbouncer, etc.)",{"type":45,"tag":98,"props":129,"children":130},{},[131],{"type":50,"value":132},"Implementing keyset pagination instead of OFFSET\u002FLIMIT",{"type":45,"tag":98,"props":134,"children":135},{},[136],{"type":50,"value":137},"Using follower reads for reporting and analytics queries",{"type":45,"tag":98,"props":139,"children":140},{},[141],{"type":50,"value":142},"Separating business orchestration from database transactions",{"type":45,"tag":98,"props":144,"children":145},{},[146],{"type":50,"value":147},"Using prepared statements for performance and security",{"type":45,"tag":98,"props":149,"children":150},{},[151],{"type":50,"value":152},"Selecting explicit column projections instead of SELECT *",{"type":45,"tag":98,"props":154,"children":155},{},[156],{"type":50,"value":157},"Testing application behavior under concurrency",{"type":45,"tag":98,"props":159,"children":160},{},[161],{"type":50,"value":162},"Monitoring application-level database performance",{"type":45,"tag":87,"props":164,"children":166},{"id":165},"prerequisites",[167],{"type":50,"value":168},"Prerequisites",{"type":45,"tag":94,"props":170,"children":171},{},[172,177,182,187],{"type":45,"tag":98,"props":173,"children":174},{},[175],{"type":50,"value":176},"Familiarity with CockroachDB's SERIALIZABLE isolation level",{"type":45,"tag":98,"props":178,"children":179},{},[180],{"type":50,"value":181},"Understanding of ACID transaction semantics",{"type":45,"tag":98,"props":183,"children":184},{},[185],{"type":50,"value":186},"Access to application source code for transaction design changes",{"type":45,"tag":98,"props":188,"children":189},{},[190],{"type":50,"value":191},"SQL connection to a CockroachDB cluster (for testing and validation)",{"type":45,"tag":87,"props":193,"children":195},{"id":194},"steps",[196],{"type":50,"value":197},"Steps",{"type":45,"tag":199,"props":200,"children":202},"h3",{"id":201},"_1-keep-transactions-short-lived",[203],{"type":50,"value":204},"1. Keep Transactions Short-Lived",{"type":45,"tag":53,"props":206,"children":207},{},[208],{"type":50,"value":209},"Transactions must include only the minimal set of SQL operations needed for one atomic state change. Do not place remote API calls, service-to-service requests, loops, expensive computation, or artificial waits inside a CockroachDB transaction.",{"type":45,"tag":53,"props":211,"children":212},{},[213],{"type":50,"value":214},"Long-lived transactions increase intent lifetime, contention, and retry probability in CockroachDB's distributed, optimistic-concurrency architecture.",{"type":45,"tag":53,"props":216,"children":217},{},[218],{"type":45,"tag":62,"props":219,"children":220},{},[221],{"type":50,"value":222},"Anti-pattern:",{"type":45,"tag":224,"props":225,"children":230},"pre",{"className":226,"code":227,"language":228,"meta":229,"style":229},"language-java shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","@Transactional\npublic void createOrder(Order order) {\n orderRepository.save(order);\n paymentGateway.charge(order); \u002F\u002F external call inside TX\n}\n","java","",[231],{"type":45,"tag":232,"props":233,"children":234},"code",{"__ignoreMap":229},[235,246,254,262,271],{"type":45,"tag":236,"props":237,"children":240},"span",{"class":238,"line":239},"line",1,[241],{"type":45,"tag":236,"props":242,"children":243},{},[244],{"type":50,"value":245},"@Transactional\n",{"type":45,"tag":236,"props":247,"children":248},{"class":238,"line":26},[249],{"type":45,"tag":236,"props":250,"children":251},{},[252],{"type":50,"value":253},"public void createOrder(Order order) {\n",{"type":45,"tag":236,"props":255,"children":256},{"class":238,"line":22},[257],{"type":45,"tag":236,"props":258,"children":259},{},[260],{"type":50,"value":261}," orderRepository.save(order);\n",{"type":45,"tag":236,"props":263,"children":265},{"class":238,"line":264},4,[266],{"type":45,"tag":236,"props":267,"children":268},{},[269],{"type":50,"value":270}," paymentGateway.charge(order); \u002F\u002F external call inside TX\n",{"type":45,"tag":236,"props":272,"children":274},{"class":238,"line":273},5,[275],{"type":45,"tag":236,"props":276,"children":277},{},[278],{"type":50,"value":279},"}\n",{"type":45,"tag":53,"props":281,"children":282},{},[283],{"type":45,"tag":62,"props":284,"children":285},{},[286],{"type":50,"value":287},"Correct approach — split the logic:",{"type":45,"tag":224,"props":289,"children":291},{"className":226,"code":290,"language":228,"meta":229,"style":229},"@Transactional\npublic void createOrderRecord(Order order) {\n orderRepository.save(order);\n}\n\n\u002F\u002F Outside the transaction\npaymentGateway.charge(order);\n",[292],{"type":45,"tag":232,"props":293,"children":294},{"__ignoreMap":229},[295,302,310,317,324,333,342],{"type":45,"tag":236,"props":296,"children":297},{"class":238,"line":239},[298],{"type":45,"tag":236,"props":299,"children":300},{},[301],{"type":50,"value":245},{"type":45,"tag":236,"props":303,"children":304},{"class":238,"line":26},[305],{"type":45,"tag":236,"props":306,"children":307},{},[308],{"type":50,"value":309},"public void createOrderRecord(Order order) {\n",{"type":45,"tag":236,"props":311,"children":312},{"class":238,"line":22},[313],{"type":45,"tag":236,"props":314,"children":315},{},[316],{"type":50,"value":261},{"type":45,"tag":236,"props":318,"children":319},{"class":238,"line":264},[320],{"type":45,"tag":236,"props":321,"children":322},{},[323],{"type":50,"value":279},{"type":45,"tag":236,"props":325,"children":326},{"class":238,"line":273},[327],{"type":45,"tag":236,"props":328,"children":330},{"emptyLinePlaceholder":329},true,[331],{"type":50,"value":332},"\n",{"type":45,"tag":236,"props":334,"children":336},{"class":238,"line":335},6,[337],{"type":45,"tag":236,"props":338,"children":339},{},[340],{"type":50,"value":341},"\u002F\u002F Outside the transaction\n",{"type":45,"tag":236,"props":343,"children":345},{"class":238,"line":344},7,[346],{"type":45,"tag":236,"props":347,"children":348},{},[349],{"type":50,"value":350},"paymentGateway.charge(order);\n",{"type":45,"tag":53,"props":352,"children":353},{},[354],{"type":45,"tag":62,"props":355,"children":356},{},[357],{"type":50,"value":358},"Why it matters:",{"type":45,"tag":94,"props":360,"children":361},{},[362,367,380,385],{"type":45,"tag":98,"props":363,"children":364},{},[365],{"type":50,"value":366},"Active intents block concurrent writers, reducing cluster throughput",{"type":45,"tag":98,"props":368,"children":369},{},[370,372,378],{"type":50,"value":371},"Competing transactions are more likely to encounter ",{"type":45,"tag":232,"props":373,"children":375},{"className":374},[],[376],{"type":50,"value":377},"40001",{"type":50,"value":379}," retry errors",{"type":45,"tag":98,"props":381,"children":382},{},[383],{"type":50,"value":384},"External work inside a retried transaction may run twice, causing duplicate side effects",{"type":45,"tag":98,"props":386,"children":387},{},[388],{"type":50,"value":389},"Long transactions tie up connections and memory, reducing concurrency",{"type":45,"tag":199,"props":391,"children":393},{"id":392},"_2-use-implicit-transactions-for-single-statements",[394],{"type":50,"value":395},"2. Use Implicit Transactions for Single Statements",{"type":45,"tag":53,"props":397,"children":398},{},[399,401,407,409,415,416,422,424,430,432,438,440,446],{"type":50,"value":400},"CockroachDB automatically wraps each individual SQL statement as a transaction in autocommit mode. For single ",{"type":45,"tag":232,"props":402,"children":404},{"className":403},[],[405],{"type":50,"value":406},"INSERT",{"type":50,"value":408},", ",{"type":45,"tag":232,"props":410,"children":412},{"className":411},[],[413],{"type":50,"value":414},"UPDATE",{"type":50,"value":408},{"type":45,"tag":232,"props":417,"children":419},{"className":418},[],[420],{"type":50,"value":421},"DELETE",{"type":50,"value":423},", or ",{"type":45,"tag":232,"props":425,"children":427},{"className":426},[],[428],{"type":50,"value":429},"SELECT",{"type":50,"value":431}," statements, do not wrap in explicit ",{"type":45,"tag":232,"props":433,"children":435},{"className":434},[],[436],{"type":50,"value":437},"BEGIN",{"type":50,"value":439},"\u002F",{"type":45,"tag":232,"props":441,"children":443},{"className":442},[],[444],{"type":50,"value":445},"COMMIT",{"type":50,"value":85},{"type":45,"tag":53,"props":448,"children":449},{},[450],{"type":45,"tag":62,"props":451,"children":452},{},[453],{"type":50,"value":454},"Preferred:",{"type":45,"tag":224,"props":456,"children":460},{"className":457,"code":458,"language":459,"meta":229,"style":229},"language-sql shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","INSERT INTO orders (id, status)\nVALUES (gen_random_uuid(), 'open');\n","sql",[461],{"type":45,"tag":232,"props":462,"children":463},{"__ignoreMap":229},[464,472],{"type":45,"tag":236,"props":465,"children":466},{"class":238,"line":239},[467],{"type":45,"tag":236,"props":468,"children":469},{},[470],{"type":50,"value":471},"INSERT INTO orders (id, status)\n",{"type":45,"tag":236,"props":473,"children":474},{"class":238,"line":26},[475],{"type":45,"tag":236,"props":476,"children":477},{},[478],{"type":50,"value":479},"VALUES (gen_random_uuid(), 'open');\n",{"type":45,"tag":53,"props":481,"children":482},{},[483],{"type":45,"tag":62,"props":484,"children":485},{},[486],{"type":50,"value":487},"Avoid:",{"type":45,"tag":224,"props":489,"children":491},{"className":457,"code":490,"language":459,"meta":229,"style":229},"BEGIN;\nINSERT INTO orders (id, status)\nVALUES (gen_random_uuid(), 'open');\nCOMMIT;\n",[492],{"type":45,"tag":232,"props":493,"children":494},{"__ignoreMap":229},[495,503,510,517],{"type":45,"tag":236,"props":496,"children":497},{"class":238,"line":239},[498],{"type":45,"tag":236,"props":499,"children":500},{},[501],{"type":50,"value":502},"BEGIN;\n",{"type":45,"tag":236,"props":504,"children":505},{"class":238,"line":26},[506],{"type":45,"tag":236,"props":507,"children":508},{},[509],{"type":50,"value":471},{"type":45,"tag":236,"props":511,"children":512},{"class":238,"line":22},[513],{"type":45,"tag":236,"props":514,"children":515},{},[516],{"type":50,"value":479},{"type":45,"tag":236,"props":518,"children":519},{"class":238,"line":264},[520],{"type":45,"tag":236,"props":521,"children":522},{},[523],{"type":50,"value":524},"COMMIT;\n",{"type":45,"tag":53,"props":526,"children":527},{},[528,533],{"type":45,"tag":62,"props":529,"children":530},{},[531],{"type":50,"value":532},"Benefits:",{"type":50,"value":534}," Simpler code paths, lower latency (fewer round trips), less resource usage, and fewer retry concerns since single-statement transactions are easier for CockroachDB to retry automatically.",{"type":45,"tag":199,"props":536,"children":538},{"id":537},"_3-use-explicit-transactions-for-grouped-statements-and-handle-retries",[539],{"type":50,"value":540},"3. Use Explicit Transactions for Grouped Statements and Handle Retries",{"type":45,"tag":53,"props":542,"children":543},{},[544,546,551,552,557],{"type":50,"value":545},"When multiple SQL operations must succeed or fail together, use explicit transactions with ",{"type":45,"tag":232,"props":547,"children":549},{"className":548},[],[550],{"type":50,"value":437},{"type":50,"value":439},{"type":45,"tag":232,"props":553,"children":555},{"className":554},[],[556],{"type":50,"value":445},{"type":50,"value":558},". Because CockroachDB defaults to SERIALIZABLE isolation, transaction retries are a normal part of correct execution under contention.",{"type":45,"tag":224,"props":560,"children":562},{"className":457,"code":561,"language":459,"meta":229,"style":229},"BEGIN;\n UPDATE accounts SET balance = balance - 100 WHERE id = 1;\n UPDATE accounts SET balance = balance + 100 WHERE id = 2;\nCOMMIT;\n",[563],{"type":45,"tag":232,"props":564,"children":565},{"__ignoreMap":229},[566,573,581,589],{"type":45,"tag":236,"props":567,"children":568},{"class":238,"line":239},[569],{"type":45,"tag":236,"props":570,"children":571},{},[572],{"type":50,"value":502},{"type":45,"tag":236,"props":574,"children":575},{"class":238,"line":26},[576],{"type":45,"tag":236,"props":577,"children":578},{},[579],{"type":50,"value":580}," UPDATE accounts SET balance = balance - 100 WHERE id = 1;\n",{"type":45,"tag":236,"props":582,"children":583},{"class":238,"line":22},[584],{"type":45,"tag":236,"props":585,"children":586},{},[587],{"type":50,"value":588}," UPDATE accounts SET balance = balance + 100 WHERE id = 2;\n",{"type":45,"tag":236,"props":590,"children":591},{"class":238,"line":264},[592],{"type":45,"tag":236,"props":593,"children":594},{},[595],{"type":50,"value":524},{"type":45,"tag":53,"props":597,"children":598},{},[599],{"type":45,"tag":62,"props":600,"children":601},{},[602],{"type":50,"value":603},"Client-side retry loop with exponential backoff:",{"type":45,"tag":224,"props":605,"children":609},{"className":606,"code":607,"language":608,"meta":229,"style":229},"language-python shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","import random\nimport time\n\ndef execute_with_retry(conn, txn_logic):\n backoff = 0.1\n while True:\n try:\n with conn.transaction() as txn:\n txn_logic(txn)\n return\n except SerializationFailure:\n time.sleep(backoff + random.uniform(0, 0.1))\n backoff = min(backoff * 2, 2.0)\n","python",[610],{"type":45,"tag":232,"props":611,"children":612},{"__ignoreMap":229},[613,621,629,636,644,652,660,668,677,686,695,704,713],{"type":45,"tag":236,"props":614,"children":615},{"class":238,"line":239},[616],{"type":45,"tag":236,"props":617,"children":618},{},[619],{"type":50,"value":620},"import random\n",{"type":45,"tag":236,"props":622,"children":623},{"class":238,"line":26},[624],{"type":45,"tag":236,"props":625,"children":626},{},[627],{"type":50,"value":628},"import time\n",{"type":45,"tag":236,"props":630,"children":631},{"class":238,"line":22},[632],{"type":45,"tag":236,"props":633,"children":634},{"emptyLinePlaceholder":329},[635],{"type":50,"value":332},{"type":45,"tag":236,"props":637,"children":638},{"class":238,"line":264},[639],{"type":45,"tag":236,"props":640,"children":641},{},[642],{"type":50,"value":643},"def execute_with_retry(conn, txn_logic):\n",{"type":45,"tag":236,"props":645,"children":646},{"class":238,"line":273},[647],{"type":45,"tag":236,"props":648,"children":649},{},[650],{"type":50,"value":651}," backoff = 0.1\n",{"type":45,"tag":236,"props":653,"children":654},{"class":238,"line":335},[655],{"type":45,"tag":236,"props":656,"children":657},{},[658],{"type":50,"value":659}," while True:\n",{"type":45,"tag":236,"props":661,"children":662},{"class":238,"line":344},[663],{"type":45,"tag":236,"props":664,"children":665},{},[666],{"type":50,"value":667}," try:\n",{"type":45,"tag":236,"props":669,"children":671},{"class":238,"line":670},8,[672],{"type":45,"tag":236,"props":673,"children":674},{},[675],{"type":50,"value":676}," with conn.transaction() as txn:\n",{"type":45,"tag":236,"props":678,"children":680},{"class":238,"line":679},9,[681],{"type":45,"tag":236,"props":682,"children":683},{},[684],{"type":50,"value":685}," txn_logic(txn)\n",{"type":45,"tag":236,"props":687,"children":689},{"class":238,"line":688},10,[690],{"type":45,"tag":236,"props":691,"children":692},{},[693],{"type":50,"value":694}," return\n",{"type":45,"tag":236,"props":696,"children":698},{"class":238,"line":697},11,[699],{"type":45,"tag":236,"props":700,"children":701},{},[702],{"type":50,"value":703}," except SerializationFailure:\n",{"type":45,"tag":236,"props":705,"children":707},{"class":238,"line":706},12,[708],{"type":45,"tag":236,"props":709,"children":710},{},[711],{"type":50,"value":712}," time.sleep(backoff + random.uniform(0, 0.1))\n",{"type":45,"tag":236,"props":714,"children":716},{"class":238,"line":715},13,[717],{"type":45,"tag":236,"props":718,"children":719},{},[720],{"type":50,"value":721}," backoff = min(backoff * 2, 2.0)\n",{"type":45,"tag":53,"props":723,"children":724},{},[725],{"type":45,"tag":62,"props":726,"children":727},{},[728],{"type":50,"value":729},"Advanced retry with the cockroach_restart savepoint protocol:",{"type":45,"tag":224,"props":731,"children":733},{"className":457,"code":732,"language":459,"meta":229,"style":229},"BEGIN;\nSAVEPOINT cockroach_restart;\n-- transactional work\nRELEASE SAVEPOINT cockroach_restart;\nCOMMIT;\n",[734],{"type":45,"tag":232,"props":735,"children":736},{"__ignoreMap":229},[737,744,752,760,768],{"type":45,"tag":236,"props":738,"children":739},{"class":238,"line":239},[740],{"type":45,"tag":236,"props":741,"children":742},{},[743],{"type":50,"value":502},{"type":45,"tag":236,"props":745,"children":746},{"class":238,"line":26},[747],{"type":45,"tag":236,"props":748,"children":749},{},[750],{"type":50,"value":751},"SAVEPOINT cockroach_restart;\n",{"type":45,"tag":236,"props":753,"children":754},{"class":238,"line":22},[755],{"type":45,"tag":236,"props":756,"children":757},{},[758],{"type":50,"value":759},"-- transactional work\n",{"type":45,"tag":236,"props":761,"children":762},{"class":238,"line":264},[763],{"type":45,"tag":236,"props":764,"children":765},{},[766],{"type":50,"value":767},"RELEASE SAVEPOINT cockroach_restart;\n",{"type":45,"tag":236,"props":769,"children":770},{"class":238,"line":273},[771],{"type":45,"tag":236,"props":772,"children":773},{},[774],{"type":50,"value":524},{"type":45,"tag":53,"props":776,"children":777},{},[778,783,785,790,792,798,800,806],{"type":45,"tag":62,"props":779,"children":780},{},[781],{"type":50,"value":782},"WARNING: Generic savepoints do NOT work as retry mechanisms.",{"type":50,"value":784}," CockroachDB aborts the entire transaction on a ",{"type":45,"tag":232,"props":786,"children":788},{"className":787},[],[789],{"type":50,"value":377},{"type":50,"value":791}," serialization failure. Using ",{"type":45,"tag":232,"props":793,"children":795},{"className":794},[],[796],{"type":50,"value":797},"ROLLBACK TO SAVEPOINT",{"type":50,"value":799}," on a regular savepoint cannot recover -- the transaction remains in an aborted state. Only the special ",{"type":45,"tag":232,"props":801,"children":803},{"className":802},[],[804],{"type":50,"value":805},"SAVEPOINT cockroach_restart",{"type":50,"value":807}," protocol (where the client catches the error, rolls back to the savepoint, and re-executes the work) is supported. For most applications, a full-transaction retry loop is simpler and recommended.",{"type":45,"tag":53,"props":809,"children":810},{},[811],{"type":45,"tag":62,"props":812,"children":813},{},[814],{"type":50,"value":815},"SQLSTATE guidance:",{"type":45,"tag":817,"props":818,"children":819},"table",{},[820,844],{"type":45,"tag":821,"props":822,"children":823},"thead",{},[824],{"type":45,"tag":825,"props":826,"children":827},"tr",{},[828,834,839],{"type":45,"tag":829,"props":830,"children":831},"th",{},[832],{"type":50,"value":833},"Code",{"type":45,"tag":829,"props":835,"children":836},{},[837],{"type":50,"value":838},"Meaning",{"type":45,"tag":829,"props":840,"children":841},{},[842],{"type":50,"value":843},"Action",{"type":45,"tag":845,"props":846,"children":847},"tbody",{},[848,870,892,922],{"type":45,"tag":825,"props":849,"children":850},{},[851,860,865],{"type":45,"tag":852,"props":853,"children":854},"td",{},[855],{"type":45,"tag":232,"props":856,"children":858},{"className":857},[],[859],{"type":50,"value":377},{"type":45,"tag":852,"props":861,"children":862},{},[863],{"type":50,"value":864},"Serialization \u002F retryable",{"type":45,"tag":852,"props":866,"children":867},{},[868],{"type":50,"value":869},"Retry the entire unit of work with backoff and jitter",{"type":45,"tag":825,"props":871,"children":872},{},[873,882,887],{"type":45,"tag":852,"props":874,"children":875},{},[876],{"type":45,"tag":232,"props":877,"children":879},{"className":878},[],[880],{"type":50,"value":881},"40003",{"type":45,"tag":852,"props":883,"children":884},{},[885],{"type":50,"value":886},"Ambiguous result \u002F indeterminate commit",{"type":45,"tag":852,"props":888,"children":889},{},[890],{"type":50,"value":891},"Do not blindly replay non-idempotent work",{"type":45,"tag":825,"props":893,"children":894},{},[895,912,917],{"type":45,"tag":852,"props":896,"children":897},{},[898,904,906],{"type":45,"tag":232,"props":899,"children":901},{"className":900},[],[902],{"type":50,"value":903},"08xx",{"type":50,"value":905}," \u002F ",{"type":45,"tag":232,"props":907,"children":909},{"className":908},[],[910],{"type":50,"value":911},"57xx",{"type":45,"tag":852,"props":913,"children":914},{},[915],{"type":50,"value":916},"Network or server transient issues",{"type":45,"tag":852,"props":918,"children":919},{},[920],{"type":50,"value":921},"Retry carefully, account for ambiguous commits",{"type":45,"tag":825,"props":923,"children":924},{},[925,934,939],{"type":45,"tag":852,"props":926,"children":927},{},[928],{"type":45,"tag":232,"props":929,"children":931},{"className":930},[],[932],{"type":50,"value":933},"23xxx",{"type":45,"tag":852,"props":935,"children":936},{},[937],{"type":50,"value":938},"Constraint and application errors",{"type":45,"tag":852,"props":940,"children":941},{},[942],{"type":50,"value":943},"Usually should not be retried",{"type":45,"tag":199,"props":945,"children":947},{"id":946},"_4-mark-read-only-transactions-where-applicable",[948],{"type":50,"value":949},"4. Mark Read-Only Transactions Where Applicable",{"type":45,"tag":53,"props":951,"children":952},{},[953],{"type":50,"value":954},"Read-only transactions perform retrieval only and make no writes. Marking them as read-only allows CockroachDB to avoid unnecessary write intents, reduce contention with writers, and enable follower or bounded-staleness reads.",{"type":45,"tag":224,"props":956,"children":958},{"className":457,"code":957,"language":459,"meta":229,"style":229},"BEGIN;\nSET TRANSACTION READ ONLY;\nSELECT * FROM customers WHERE region = 'US-East';\nCOMMIT;\n",[959],{"type":45,"tag":232,"props":960,"children":961},{"__ignoreMap":229},[962,969,977,985],{"type":45,"tag":236,"props":963,"children":964},{"class":238,"line":239},[965],{"type":45,"tag":236,"props":966,"children":967},{},[968],{"type":50,"value":502},{"type":45,"tag":236,"props":970,"children":971},{"class":238,"line":26},[972],{"type":45,"tag":236,"props":973,"children":974},{},[975],{"type":50,"value":976},"SET TRANSACTION READ ONLY;\n",{"type":45,"tag":236,"props":978,"children":979},{"class":238,"line":22},[980],{"type":45,"tag":236,"props":981,"children":982},{},[983],{"type":50,"value":984},"SELECT * FROM customers WHERE region = 'US-East';\n",{"type":45,"tag":236,"props":986,"children":987},{"class":238,"line":264},[988],{"type":45,"tag":236,"props":989,"children":990},{},[991],{"type":50,"value":524},{"type":45,"tag":199,"props":993,"children":995},{"id":994},"_5-push-invariants-into-sql-avoid-read-modify-write-loops",[996],{"type":50,"value":997},"5. Push Invariants into SQL — Avoid Read-Modify-Write Loops",{"type":45,"tag":53,"props":999,"children":1000},{},[1001],{"type":50,"value":1002},"Do not fetch state into application code, modify it in memory, and write it back. Prefer atomic SQL, constraints, guarded UPDATEs, UPSERT, INSERT ... ON CONFLICT, and CTE-based mutations.",{"type":45,"tag":53,"props":1004,"children":1005},{},[1006],{"type":45,"tag":62,"props":1007,"children":1008},{},[1009],{"type":50,"value":222},{"type":45,"tag":224,"props":1011,"children":1013},{"className":606,"code":1012,"language":608,"meta":229,"style":229},"balance = db.fetch(\"SELECT balance FROM accounts WHERE id = 123\")\nbalance += 100\ndb.execute(\"UPDATE accounts SET balance = %s WHERE id = 123\", (balance,))\n",[1014],{"type":45,"tag":232,"props":1015,"children":1016},{"__ignoreMap":229},[1017,1025,1033],{"type":45,"tag":236,"props":1018,"children":1019},{"class":238,"line":239},[1020],{"type":45,"tag":236,"props":1021,"children":1022},{},[1023],{"type":50,"value":1024},"balance = db.fetch(\"SELECT balance FROM accounts WHERE id = 123\")\n",{"type":45,"tag":236,"props":1026,"children":1027},{"class":238,"line":26},[1028],{"type":45,"tag":236,"props":1029,"children":1030},{},[1031],{"type":50,"value":1032},"balance += 100\n",{"type":45,"tag":236,"props":1034,"children":1035},{"class":238,"line":22},[1036],{"type":45,"tag":236,"props":1037,"children":1038},{},[1039],{"type":50,"value":1040},"db.execute(\"UPDATE accounts SET balance = %s WHERE id = 123\", (balance,))\n",{"type":45,"tag":53,"props":1042,"children":1043},{},[1044],{"type":45,"tag":62,"props":1045,"children":1046},{},[1047],{"type":50,"value":1048},"Preferred atomic SQL:",{"type":45,"tag":224,"props":1050,"children":1052},{"className":457,"code":1051,"language":459,"meta":229,"style":229},"UPDATE accounts\nSET balance = balance + 100\nWHERE id = 123;\n",[1053],{"type":45,"tag":232,"props":1054,"children":1055},{"__ignoreMap":229},[1056,1064,1072],{"type":45,"tag":236,"props":1057,"children":1058},{"class":238,"line":239},[1059],{"type":45,"tag":236,"props":1060,"children":1061},{},[1062],{"type":50,"value":1063},"UPDATE accounts\n",{"type":45,"tag":236,"props":1065,"children":1066},{"class":238,"line":26},[1067],{"type":45,"tag":236,"props":1068,"children":1069},{},[1070],{"type":50,"value":1071},"SET balance = balance + 100\n",{"type":45,"tag":236,"props":1073,"children":1074},{"class":238,"line":22},[1075],{"type":45,"tag":236,"props":1076,"children":1077},{},[1078],{"type":50,"value":1079},"WHERE id = 123;\n",{"type":45,"tag":53,"props":1081,"children":1082},{},[1083],{"type":45,"tag":62,"props":1084,"children":1085},{},[1086],{"type":50,"value":1087},"Guarded write with invariant enforcement:",{"type":45,"tag":224,"props":1089,"children":1091},{"className":457,"code":1090,"language":459,"meta":229,"style":229},"UPDATE customer_daily_limits\nSET used_total = used_total + $2\nWHERE customer_id = $1\n AND day = current_date\n AND used_total + $2 \u003C= daily_limit;\n",[1092],{"type":45,"tag":232,"props":1093,"children":1094},{"__ignoreMap":229},[1095,1103,1111,1119,1127],{"type":45,"tag":236,"props":1096,"children":1097},{"class":238,"line":239},[1098],{"type":45,"tag":236,"props":1099,"children":1100},{},[1101],{"type":50,"value":1102},"UPDATE customer_daily_limits\n",{"type":45,"tag":236,"props":1104,"children":1105},{"class":238,"line":26},[1106],{"type":45,"tag":236,"props":1107,"children":1108},{},[1109],{"type":50,"value":1110},"SET used_total = used_total + $2\n",{"type":45,"tag":236,"props":1112,"children":1113},{"class":238,"line":22},[1114],{"type":45,"tag":236,"props":1115,"children":1116},{},[1117],{"type":50,"value":1118},"WHERE customer_id = $1\n",{"type":45,"tag":236,"props":1120,"children":1121},{"class":238,"line":264},[1122],{"type":45,"tag":236,"props":1123,"children":1124},{},[1125],{"type":50,"value":1126}," AND day = current_date\n",{"type":45,"tag":236,"props":1128,"children":1129},{"class":238,"line":273},[1130],{"type":45,"tag":236,"props":1131,"children":1132},{},[1133],{"type":50,"value":1134}," AND used_total + $2 \u003C= daily_limit;\n",{"type":45,"tag":53,"props":1136,"children":1137},{},[1138],{"type":45,"tag":62,"props":1139,"children":1140},{},[1141],{"type":50,"value":1142},"Atomic CTE pattern:",{"type":45,"tag":224,"props":1144,"children":1146},{"className":457,"code":1145,"language":459,"meta":229,"style":229},"WITH limit_row AS (\n SELECT customer_id, day\n FROM customer_daily_limits\n WHERE customer_id = $1 AND day = current_date\n FOR UPDATE\n), spend AS (\n UPDATE customer_daily_limits AS l\n SET remaining_limit = l.remaining_limit - $2,\n used_total = l.used_total + $2\n FROM limit_row\n WHERE l.customer_id = limit_row.customer_id\n AND l.day = limit_row.day\n AND l.remaining_limit >= $2\n RETURNING l.customer_id, l.day\n), ins AS (\n INSERT INTO transfers (customer_id, amount, direction, created_at)\n SELECT $1, $2, 'debit', now()\n FROM spend\n RETURNING id AS transfer_id\n)\nSELECT transfer_id FROM ins;\n",[1147],{"type":45,"tag":232,"props":1148,"children":1149},{"__ignoreMap":229},[1150,1158,1166,1174,1182,1190,1198,1206,1214,1222,1230,1238,1246,1254,1263,1272,1281,1290,1299,1308,1317],{"type":45,"tag":236,"props":1151,"children":1152},{"class":238,"line":239},[1153],{"type":45,"tag":236,"props":1154,"children":1155},{},[1156],{"type":50,"value":1157},"WITH limit_row AS (\n",{"type":45,"tag":236,"props":1159,"children":1160},{"class":238,"line":26},[1161],{"type":45,"tag":236,"props":1162,"children":1163},{},[1164],{"type":50,"value":1165}," SELECT customer_id, day\n",{"type":45,"tag":236,"props":1167,"children":1168},{"class":238,"line":22},[1169],{"type":45,"tag":236,"props":1170,"children":1171},{},[1172],{"type":50,"value":1173}," FROM customer_daily_limits\n",{"type":45,"tag":236,"props":1175,"children":1176},{"class":238,"line":264},[1177],{"type":45,"tag":236,"props":1178,"children":1179},{},[1180],{"type":50,"value":1181}," WHERE customer_id = $1 AND day = current_date\n",{"type":45,"tag":236,"props":1183,"children":1184},{"class":238,"line":273},[1185],{"type":45,"tag":236,"props":1186,"children":1187},{},[1188],{"type":50,"value":1189}," FOR UPDATE\n",{"type":45,"tag":236,"props":1191,"children":1192},{"class":238,"line":335},[1193],{"type":45,"tag":236,"props":1194,"children":1195},{},[1196],{"type":50,"value":1197},"), spend AS (\n",{"type":45,"tag":236,"props":1199,"children":1200},{"class":238,"line":344},[1201],{"type":45,"tag":236,"props":1202,"children":1203},{},[1204],{"type":50,"value":1205}," UPDATE customer_daily_limits AS l\n",{"type":45,"tag":236,"props":1207,"children":1208},{"class":238,"line":670},[1209],{"type":45,"tag":236,"props":1210,"children":1211},{},[1212],{"type":50,"value":1213}," SET remaining_limit = l.remaining_limit - $2,\n",{"type":45,"tag":236,"props":1215,"children":1216},{"class":238,"line":679},[1217],{"type":45,"tag":236,"props":1218,"children":1219},{},[1220],{"type":50,"value":1221}," used_total = l.used_total + $2\n",{"type":45,"tag":236,"props":1223,"children":1224},{"class":238,"line":688},[1225],{"type":45,"tag":236,"props":1226,"children":1227},{},[1228],{"type":50,"value":1229}," FROM limit_row\n",{"type":45,"tag":236,"props":1231,"children":1232},{"class":238,"line":697},[1233],{"type":45,"tag":236,"props":1234,"children":1235},{},[1236],{"type":50,"value":1237}," WHERE l.customer_id = limit_row.customer_id\n",{"type":45,"tag":236,"props":1239,"children":1240},{"class":238,"line":706},[1241],{"type":45,"tag":236,"props":1242,"children":1243},{},[1244],{"type":50,"value":1245}," AND l.day = limit_row.day\n",{"type":45,"tag":236,"props":1247,"children":1248},{"class":238,"line":715},[1249],{"type":45,"tag":236,"props":1250,"children":1251},{},[1252],{"type":50,"value":1253}," AND l.remaining_limit >= $2\n",{"type":45,"tag":236,"props":1255,"children":1257},{"class":238,"line":1256},14,[1258],{"type":45,"tag":236,"props":1259,"children":1260},{},[1261],{"type":50,"value":1262}," RETURNING l.customer_id, l.day\n",{"type":45,"tag":236,"props":1264,"children":1266},{"class":238,"line":1265},15,[1267],{"type":45,"tag":236,"props":1268,"children":1269},{},[1270],{"type":50,"value":1271},"), ins AS (\n",{"type":45,"tag":236,"props":1273,"children":1275},{"class":238,"line":1274},16,[1276],{"type":45,"tag":236,"props":1277,"children":1278},{},[1279],{"type":50,"value":1280}," INSERT INTO transfers (customer_id, amount, direction, created_at)\n",{"type":45,"tag":236,"props":1282,"children":1284},{"class":238,"line":1283},17,[1285],{"type":45,"tag":236,"props":1286,"children":1287},{},[1288],{"type":50,"value":1289}," SELECT $1, $2, 'debit', now()\n",{"type":45,"tag":236,"props":1291,"children":1293},{"class":238,"line":1292},18,[1294],{"type":45,"tag":236,"props":1295,"children":1296},{},[1297],{"type":50,"value":1298}," FROM spend\n",{"type":45,"tag":236,"props":1300,"children":1302},{"class":238,"line":1301},19,[1303],{"type":45,"tag":236,"props":1304,"children":1305},{},[1306],{"type":50,"value":1307}," RETURNING id AS transfer_id\n",{"type":45,"tag":236,"props":1309,"children":1311},{"class":238,"line":1310},20,[1312],{"type":45,"tag":236,"props":1313,"children":1314},{},[1315],{"type":50,"value":1316},")\n",{"type":45,"tag":236,"props":1318,"children":1320},{"class":238,"line":1319},21,[1321],{"type":45,"tag":236,"props":1322,"children":1323},{},[1324],{"type":50,"value":1325},"SELECT transfer_id FROM ins;\n",{"type":45,"tag":53,"props":1327,"children":1328},{},[1329],{"type":45,"tag":62,"props":1330,"children":1331},{},[1332],{"type":50,"value":1333},"Key approaches:",{"type":45,"tag":94,"props":1335,"children":1336},{},[1337,1348,1353,1388,1409],{"type":45,"tag":98,"props":1338,"children":1339},{},[1340,1342],{"type":50,"value":1341},"Use atomic updates: ",{"type":45,"tag":232,"props":1343,"children":1345},{"className":1344},[],[1346],{"type":50,"value":1347},"UPDATE ... SET col = col + 1",{"type":45,"tag":98,"props":1349,"children":1350},{},[1351],{"type":50,"value":1352},"Use version or timestamp checks in WHERE clauses for optimistic concurrency",{"type":45,"tag":98,"props":1354,"children":1355},{},[1356,1358,1364,1365,1371,1372,1378,1380,1386],{"type":50,"value":1357},"Enforce business rules with ",{"type":45,"tag":232,"props":1359,"children":1361},{"className":1360},[],[1362],{"type":50,"value":1363},"UNIQUE",{"type":50,"value":408},{"type":45,"tag":232,"props":1366,"children":1368},{"className":1367},[],[1369],{"type":50,"value":1370},"CHECK",{"type":50,"value":408},{"type":45,"tag":232,"props":1373,"children":1375},{"className":1374},[],[1376],{"type":50,"value":1377},"NOT NULL",{"type":50,"value":1379},", and ",{"type":45,"tag":232,"props":1381,"children":1383},{"className":1382},[],[1384],{"type":50,"value":1385},"FOREIGN KEY",{"type":50,"value":1387}," constraints",{"type":45,"tag":98,"props":1389,"children":1390},{},[1391,1393,1399,1401,1407],{"type":50,"value":1392},"Use ",{"type":45,"tag":232,"props":1394,"children":1396},{"className":1395},[],[1397],{"type":50,"value":1398},"UPSERT",{"type":50,"value":1400}," or ",{"type":45,"tag":232,"props":1402,"children":1404},{"className":1403},[],[1405],{"type":50,"value":1406},"INSERT ... ON CONFLICT",{"type":50,"value":1408}," instead of read-before-write existence checks",{"type":45,"tag":98,"props":1410,"children":1411},{},[1412],{"type":50,"value":1413},"Use CTEs to keep multi-step logic atomic",{"type":45,"tag":199,"props":1415,"children":1417},{"id":1416},"_6-use-select-for-update-selectively",[1418],{"type":50,"value":1419},"6. Use SELECT ... FOR UPDATE Selectively",{"type":45,"tag":53,"props":1421,"children":1422},{},[1423,1425,1431],{"type":50,"value":1424},"CockroachDB defaults to optimistic concurrency, which works well for most workloads. For hot rows or contention-heavy read-before-write paths, ",{"type":45,"tag":232,"props":1426,"children":1428},{"className":1427},[],[1429],{"type":50,"value":1430},"SELECT ... FOR UPDATE",{"type":50,"value":1432}," reduces retry churn by making contenders wait instead of race.",{"type":45,"tag":224,"props":1434,"children":1436},{"className":457,"code":1435,"language":459,"meta":229,"style":229},"BEGIN;\nSELECT balance FROM accounts WHERE id = 1 FOR UPDATE;\nUPDATE accounts SET balance = balance - 100 WHERE id = 1;\nCOMMIT;\n",[1437],{"type":45,"tag":232,"props":1438,"children":1439},{"__ignoreMap":229},[1440,1447,1455,1463],{"type":45,"tag":236,"props":1441,"children":1442},{"class":238,"line":239},[1443],{"type":45,"tag":236,"props":1444,"children":1445},{},[1446],{"type":50,"value":502},{"type":45,"tag":236,"props":1448,"children":1449},{"class":238,"line":26},[1450],{"type":45,"tag":236,"props":1451,"children":1452},{},[1453],{"type":50,"value":1454},"SELECT balance FROM accounts WHERE id = 1 FOR UPDATE;\n",{"type":45,"tag":236,"props":1456,"children":1457},{"class":238,"line":22},[1458],{"type":45,"tag":236,"props":1459,"children":1460},{},[1461],{"type":50,"value":1462},"UPDATE accounts SET balance = balance - 100 WHERE id = 1;\n",{"type":45,"tag":236,"props":1464,"children":1465},{"class":238,"line":264},[1466],{"type":45,"tag":236,"props":1467,"children":1468},{},[1469],{"type":50,"value":524},{"type":45,"tag":53,"props":1471,"children":1472},{},[1473],{"type":45,"tag":62,"props":1474,"children":1475},{},[1476],{"type":50,"value":1477},"Use when:",{"type":45,"tag":94,"props":1479,"children":1480},{},[1481,1486,1491],{"type":45,"tag":98,"props":1482,"children":1483},{},[1484],{"type":50,"value":1485},"The same rows are updated frequently by many concurrent transactions",{"type":45,"tag":98,"props":1487,"children":1488},{},[1489],{"type":50,"value":1490},"Optimistic retries are causing thrashing",{"type":45,"tag":98,"props":1492,"children":1493},{},[1494],{"type":50,"value":1495},"Consistency before write is required (inventory, financial transfers)",{"type":45,"tag":53,"props":1497,"children":1498},{},[1499,1504,1506,1511,1513,1518,1520,1526],{"type":45,"tag":62,"props":1500,"children":1501},{},[1502],{"type":50,"value":1503},"Counterintuitive contention insight:",{"type":50,"value":1505}," Adding more application pods or threads targeting the same hot rows does NOT increase throughput -- it decreases it. With N concurrent writers on the same row, only 1 can commit per round; the other N-1 are aborted with ",{"type":45,"tag":232,"props":1507,"children":1509},{"className":1508},[],[1510],{"type":50,"value":377},{"type":50,"value":1512}," and must retry. More concurrency on hot data means more wasted work and lower TPS. Solutions: use ",{"type":45,"tag":232,"props":1514,"children":1516},{"className":1515},[],[1517],{"type":50,"value":1430},{"type":50,"value":1519}," to serialize access, use atomic ",{"type":45,"tag":232,"props":1521,"children":1523},{"className":1522},[],[1524],{"type":50,"value":1525},"UPDATE SET balance = balance + amount",{"type":50,"value":1527}," to eliminate the read-modify-write cycle, or distribute writes across multiple rows.",{"type":45,"tag":53,"props":1529,"children":1530},{},[1531,1536],{"type":45,"tag":62,"props":1532,"children":1533},{},[1534],{"type":50,"value":1535},"Trade-off:",{"type":50,"value":1537}," Overusing pessimistic locks can introduce waiting chains or deadlocks. Reserve for hot paths and contention-heavy workloads.",{"type":45,"tag":199,"props":1539,"children":1541},{"id":1540},"_7-use-set-based-operations-over-row-by-row-loops",[1542],{"type":50,"value":1543},"7. Use Set-Based Operations Over Row-by-Row Loops",{"type":45,"tag":53,"props":1545,"children":1546},{},[1547],{"type":50,"value":1548},"CockroachDB performs best with set-oriented SQL rather than many small client-driven statements. This reduces round trips, shortens contention windows, and improves throughput.",{"type":45,"tag":53,"props":1550,"children":1551},{},[1552],{"type":45,"tag":62,"props":1553,"children":1554},{},[1555],{"type":50,"value":1556},"Row-by-row anti-pattern:",{"type":45,"tag":224,"props":1558,"children":1560},{"className":606,"code":1559,"language":608,"meta":229,"style":229},"for row in rows:\n db.execute(\n \"UPDATE accounts SET balance = balance + 10 WHERE id = %s\",\n (row.id,)\n )\n",[1561],{"type":45,"tag":232,"props":1562,"children":1563},{"__ignoreMap":229},[1564,1572,1580,1588,1596],{"type":45,"tag":236,"props":1565,"children":1566},{"class":238,"line":239},[1567],{"type":45,"tag":236,"props":1568,"children":1569},{},[1570],{"type":50,"value":1571},"for row in rows:\n",{"type":45,"tag":236,"props":1573,"children":1574},{"class":238,"line":26},[1575],{"type":45,"tag":236,"props":1576,"children":1577},{},[1578],{"type":50,"value":1579}," db.execute(\n",{"type":45,"tag":236,"props":1581,"children":1582},{"class":238,"line":22},[1583],{"type":45,"tag":236,"props":1584,"children":1585},{},[1586],{"type":50,"value":1587}," \"UPDATE accounts SET balance = balance + 10 WHERE id = %s\",\n",{"type":45,"tag":236,"props":1589,"children":1590},{"class":238,"line":264},[1591],{"type":45,"tag":236,"props":1592,"children":1593},{},[1594],{"type":50,"value":1595}," (row.id,)\n",{"type":45,"tag":236,"props":1597,"children":1598},{"class":238,"line":273},[1599],{"type":45,"tag":236,"props":1600,"children":1601},{},[1602],{"type":50,"value":1603}," )\n",{"type":45,"tag":53,"props":1605,"children":1606},{},[1607],{"type":45,"tag":62,"props":1608,"children":1609},{},[1610],{"type":50,"value":1611},"Set-based preferred:",{"type":45,"tag":224,"props":1613,"children":1615},{"className":457,"code":1614,"language":459,"meta":229,"style":229},"UPDATE accounts\nSET balance = balance + 10\nWHERE region = 'US-East';\n",[1616],{"type":45,"tag":232,"props":1617,"children":1618},{"__ignoreMap":229},[1619,1626,1634],{"type":45,"tag":236,"props":1620,"children":1621},{"class":238,"line":239},[1622],{"type":45,"tag":236,"props":1623,"children":1624},{},[1625],{"type":50,"value":1063},{"type":45,"tag":236,"props":1627,"children":1628},{"class":238,"line":26},[1629],{"type":45,"tag":236,"props":1630,"children":1631},{},[1632],{"type":50,"value":1633},"SET balance = balance + 10\n",{"type":45,"tag":236,"props":1635,"children":1636},{"class":238,"line":22},[1637],{"type":45,"tag":236,"props":1638,"children":1639},{},[1640],{"type":50,"value":1641},"WHERE region = 'US-East';\n",{"type":45,"tag":53,"props":1643,"children":1644},{},[1645],{"type":45,"tag":62,"props":1646,"children":1647},{},[1648],{"type":50,"value":1649},"Batch INSERT:",{"type":45,"tag":224,"props":1651,"children":1653},{"className":457,"code":1652,"language":459,"meta":229,"style":229},"INSERT INTO trades (id, symbol, price)\nVALUES\n (1, 'AAPL', 180),\n (2, 'GOOG', 125),\n (3, 'AMZN', 140);\n",[1654],{"type":45,"tag":232,"props":1655,"children":1656},{"__ignoreMap":229},[1657,1665,1673,1681,1689],{"type":45,"tag":236,"props":1658,"children":1659},{"class":238,"line":239},[1660],{"type":45,"tag":236,"props":1661,"children":1662},{},[1663],{"type":50,"value":1664},"INSERT INTO trades (id, symbol, price)\n",{"type":45,"tag":236,"props":1666,"children":1667},{"class":238,"line":26},[1668],{"type":45,"tag":236,"props":1669,"children":1670},{},[1671],{"type":50,"value":1672},"VALUES\n",{"type":45,"tag":236,"props":1674,"children":1675},{"class":238,"line":22},[1676],{"type":45,"tag":236,"props":1677,"children":1678},{},[1679],{"type":50,"value":1680}," (1, 'AAPL', 180),\n",{"type":45,"tag":236,"props":1682,"children":1683},{"class":238,"line":264},[1684],{"type":45,"tag":236,"props":1685,"children":1686},{},[1687],{"type":50,"value":1688}," (2, 'GOOG', 125),\n",{"type":45,"tag":236,"props":1690,"children":1691},{"class":238,"line":273},[1692],{"type":45,"tag":236,"props":1693,"children":1694},{},[1695],{"type":50,"value":1696}," (3, 'AMZN', 140);\n",{"type":45,"tag":53,"props":1698,"children":1699},{},[1700],{"type":45,"tag":62,"props":1701,"children":1702},{},[1703],{"type":50,"value":1704},"Batch UPDATE with UNNEST:",{"type":45,"tag":224,"props":1706,"children":1708},{"className":457,"code":1707,"language":459,"meta":229,"style":229},"WITH incoming AS (\n SELECT *\n FROM UNNEST(\n ARRAY['u1', 'u2', 'u3']::STRING[],\n ARRAY['active', 'inactive', 'active']::STRING[]\n ) AS t(id, new_status)\n)\nUPDATE users AS u\nSET status = incoming.new_status,\n updated_at = now()\nFROM incoming\nWHERE u.id = incoming.id;\n",[1709],{"type":45,"tag":232,"props":1710,"children":1711},{"__ignoreMap":229},[1712,1720,1728,1736,1744,1752,1760,1767,1775,1783,1791,1799],{"type":45,"tag":236,"props":1713,"children":1714},{"class":238,"line":239},[1715],{"type":45,"tag":236,"props":1716,"children":1717},{},[1718],{"type":50,"value":1719},"WITH incoming AS (\n",{"type":45,"tag":236,"props":1721,"children":1722},{"class":238,"line":26},[1723],{"type":45,"tag":236,"props":1724,"children":1725},{},[1726],{"type":50,"value":1727}," SELECT *\n",{"type":45,"tag":236,"props":1729,"children":1730},{"class":238,"line":22},[1731],{"type":45,"tag":236,"props":1732,"children":1733},{},[1734],{"type":50,"value":1735}," FROM UNNEST(\n",{"type":45,"tag":236,"props":1737,"children":1738},{"class":238,"line":264},[1739],{"type":45,"tag":236,"props":1740,"children":1741},{},[1742],{"type":50,"value":1743}," ARRAY['u1', 'u2', 'u3']::STRING[],\n",{"type":45,"tag":236,"props":1745,"children":1746},{"class":238,"line":273},[1747],{"type":45,"tag":236,"props":1748,"children":1749},{},[1750],{"type":50,"value":1751}," ARRAY['active', 'inactive', 'active']::STRING[]\n",{"type":45,"tag":236,"props":1753,"children":1754},{"class":238,"line":335},[1755],{"type":45,"tag":236,"props":1756,"children":1757},{},[1758],{"type":50,"value":1759}," ) AS t(id, new_status)\n",{"type":45,"tag":236,"props":1761,"children":1762},{"class":238,"line":344},[1763],{"type":45,"tag":236,"props":1764,"children":1765},{},[1766],{"type":50,"value":1316},{"type":45,"tag":236,"props":1768,"children":1769},{"class":238,"line":670},[1770],{"type":45,"tag":236,"props":1771,"children":1772},{},[1773],{"type":50,"value":1774},"UPDATE users AS u\n",{"type":45,"tag":236,"props":1776,"children":1777},{"class":238,"line":679},[1778],{"type":45,"tag":236,"props":1779,"children":1780},{},[1781],{"type":50,"value":1782},"SET status = incoming.new_status,\n",{"type":45,"tag":236,"props":1784,"children":1785},{"class":238,"line":688},[1786],{"type":45,"tag":236,"props":1787,"children":1788},{},[1789],{"type":50,"value":1790}," updated_at = now()\n",{"type":45,"tag":236,"props":1792,"children":1793},{"class":238,"line":697},[1794],{"type":45,"tag":236,"props":1795,"children":1796},{},[1797],{"type":50,"value":1798},"FROM incoming\n",{"type":45,"tag":236,"props":1800,"children":1801},{"class":238,"line":706},[1802],{"type":45,"tag":236,"props":1803,"children":1804},{},[1805],{"type":50,"value":1806},"WHERE u.id = incoming.id;\n",{"type":45,"tag":53,"props":1808,"children":1809},{},[1810],{"type":45,"tag":62,"props":1811,"children":1812},{},[1813],{"type":50,"value":1814},"Maintenance batching with LIMIT:",{"type":45,"tag":224,"props":1816,"children":1818},{"className":457,"code":1817,"language":459,"meta":229,"style":229},"DELETE FROM sessions\nWHERE expires_at \u003C now()\nORDER BY expires_at\nLIMIT 10000;\n",[1819],{"type":45,"tag":232,"props":1820,"children":1821},{"__ignoreMap":229},[1822,1830,1838,1846],{"type":45,"tag":236,"props":1823,"children":1824},{"class":238,"line":239},[1825],{"type":45,"tag":236,"props":1826,"children":1827},{},[1828],{"type":50,"value":1829},"DELETE FROM sessions\n",{"type":45,"tag":236,"props":1831,"children":1832},{"class":238,"line":26},[1833],{"type":45,"tag":236,"props":1834,"children":1835},{},[1836],{"type":50,"value":1837},"WHERE expires_at \u003C now()\n",{"type":45,"tag":236,"props":1839,"children":1840},{"class":238,"line":22},[1841],{"type":45,"tag":236,"props":1842,"children":1843},{},[1844],{"type":50,"value":1845},"ORDER BY expires_at\n",{"type":45,"tag":236,"props":1847,"children":1848},{"class":238,"line":264},[1849],{"type":45,"tag":236,"props":1850,"children":1851},{},[1852],{"type":50,"value":1853},"LIMIT 10000;\n",{"type":45,"tag":53,"props":1855,"children":1856},{},[1857,1863],{"type":45,"tag":232,"props":1858,"children":1860},{"className":1859},[],[1861],{"type":50,"value":1862},"ORDER BY",{"type":50,"value":1864}," keeps the batch deterministic so successive runs make forward progress; without it, CockroachDB may pick a different subset each iteration.",{"type":45,"tag":53,"props":1866,"children":1867},{},[1868,1873,1875,1881,1882,1888,1890,1896],{"type":45,"tag":62,"props":1869,"children":1870},{},[1871],{"type":50,"value":1872},"JDBC batching (Java):",{"type":50,"value":1874}," Use ",{"type":45,"tag":232,"props":1876,"children":1878},{"className":1877},[],[1879],{"type":50,"value":1880},"addBatch",{"type":50,"value":439},{"type":45,"tag":232,"props":1883,"children":1885},{"className":1884},[],[1886],{"type":50,"value":1887},"executeBatch",{"type":50,"value":1889}," instead of per-row ",{"type":45,"tag":232,"props":1891,"children":1893},{"className":1892},[],[1894],{"type":50,"value":1895},"executeUpdate",{"type":50,"value":1897},". This sends all rows in a single network round trip rather than N individual round trips, eliminating idle time that can account for ~50% of transaction latency in chatty workloads.",{"type":45,"tag":53,"props":1899,"children":1900},{},[1901],{"type":45,"tag":62,"props":1902,"children":1903},{},[1904],{"type":50,"value":1905},"Declarative TTL:",{"type":45,"tag":224,"props":1907,"children":1909},{"className":457,"code":1908,"language":459,"meta":229,"style":229},"-- created_at must be TIMESTAMPTZ; the expression's result type must also be TIMESTAMPTZ.\n-- Cast if the source column is plain TIMESTAMP.\nALTER TABLE events\nSET (ttl_expiration_expression = '(created_at + INTERVAL ''7 DAY'')::TIMESTAMPTZ');\n",[1910],{"type":45,"tag":232,"props":1911,"children":1912},{"__ignoreMap":229},[1913,1921,1929,1937],{"type":45,"tag":236,"props":1914,"children":1915},{"class":238,"line":239},[1916],{"type":45,"tag":236,"props":1917,"children":1918},{},[1919],{"type":50,"value":1920},"-- created_at must be TIMESTAMPTZ; the expression's result type must also be TIMESTAMPTZ.\n",{"type":45,"tag":236,"props":1922,"children":1923},{"class":238,"line":26},[1924],{"type":45,"tag":236,"props":1925,"children":1926},{},[1927],{"type":50,"value":1928},"-- Cast if the source column is plain TIMESTAMP.\n",{"type":45,"tag":236,"props":1930,"children":1931},{"class":238,"line":22},[1932],{"type":45,"tag":236,"props":1933,"children":1934},{},[1935],{"type":50,"value":1936},"ALTER TABLE events\n",{"type":45,"tag":236,"props":1938,"children":1939},{"class":238,"line":264},[1940],{"type":45,"tag":236,"props":1941,"children":1942},{},[1943],{"type":50,"value":1944},"SET (ttl_expiration_expression = '(created_at + INTERVAL ''7 DAY'')::TIMESTAMPTZ');\n",{"type":45,"tag":199,"props":1946,"children":1948},{"id":1947},"_8-use-follower-reads-for-non-critical-queries",[1949],{"type":50,"value":1950},"8. Use Follower Reads for Non-Critical Queries",{"type":45,"tag":53,"props":1952,"children":1953},{},[1954],{"type":50,"value":1955},"Many analytics, dashboard, and display-oriented queries do not need the absolute latest value. CockroachDB supports follower reads and bounded-staleness reads from follower replicas with lower latency.",{"type":45,"tag":53,"props":1957,"children":1958},{},[1959],{"type":45,"tag":62,"props":1960,"children":1961},{},[1962],{"type":50,"value":1963},"Basic follower read:",{"type":45,"tag":224,"props":1965,"children":1967},{"className":457,"code":1966,"language":459,"meta":229,"style":229},"SELECT * FROM orders\nAS OF SYSTEM TIME '-5s';\n",[1968],{"type":45,"tag":232,"props":1969,"children":1970},{"__ignoreMap":229},[1971,1979],{"type":45,"tag":236,"props":1972,"children":1973},{"class":238,"line":239},[1974],{"type":45,"tag":236,"props":1975,"children":1976},{},[1977],{"type":50,"value":1978},"SELECT * FROM orders\n",{"type":45,"tag":236,"props":1980,"children":1981},{"class":238,"line":26},[1982],{"type":45,"tag":236,"props":1983,"children":1984},{},[1985],{"type":50,"value":1986},"AS OF SYSTEM TIME '-5s';\n",{"type":45,"tag":53,"props":1988,"children":1989},{},[1990],{"type":45,"tag":62,"props":1991,"children":1992},{},[1993],{"type":50,"value":1994},"Bounded staleness:",{"type":45,"tag":224,"props":1996,"children":1998},{"className":457,"code":1997,"language":459,"meta":229,"style":229},"SELECT * FROM inventory\nAS OF SYSTEM TIME with_max_staleness(INTERVAL '10s');\n",[1999],{"type":45,"tag":232,"props":2000,"children":2001},{"__ignoreMap":229},[2002,2010],{"type":45,"tag":236,"props":2003,"children":2004},{"class":238,"line":239},[2005],{"type":45,"tag":236,"props":2006,"children":2007},{},[2008],{"type":50,"value":2009},"SELECT * FROM inventory\n",{"type":45,"tag":236,"props":2011,"children":2012},{"class":238,"line":26},[2013],{"type":45,"tag":236,"props":2014,"children":2015},{},[2016],{"type":50,"value":2017},"AS OF SYSTEM TIME with_max_staleness(INTERVAL '10s');\n",{"type":45,"tag":53,"props":2019,"children":2020},{},[2021,2026,2028,2034],{"type":45,"tag":62,"props":2022,"children":2023},{},[2024],{"type":50,"value":2025},"Read-write split pattern for heavy reads:",{"type":50,"value":2027}," When a workflow reads a large payload (e.g., KYC JSON document) and then updates a status field, split it into three phases: (1) read outside the transaction with ",{"type":45,"tag":232,"props":2029,"children":2031},{"className":2030},[],[2032],{"type":50,"value":2033},"AS OF SYSTEM TIME",{"type":50,"value":2035}," for a conflict-free snapshot, (2) process in the application layer, (3) start a short write-only transaction. This avoids holding write intents during the heavy read.",{"type":45,"tag":53,"props":2037,"children":2038},{},[2039,2043],{"type":45,"tag":62,"props":2040,"children":2041},{},[2042],{"type":50,"value":1477},{"type":50,"value":2044}," Dashboards, analytics, ETL, display-only reads, or large-payload workflows where the read and write can be separated.",{"type":45,"tag":53,"props":2046,"children":2047},{},[2048,2053],{"type":45,"tag":62,"props":2049,"children":2050},{},[2051],{"type":50,"value":2052},"Avoid when:",{"type":50,"value":2054}," The workflow requires the latest transactional state for a subsequent write decision.",{"type":45,"tag":199,"props":2056,"children":2058},{"id":2057},"_9-use-keyset-pagination-instead-of-offsetlimit",[2059],{"type":50,"value":2060},"9. Use Keyset Pagination Instead of OFFSET\u002FLIMIT",{"type":45,"tag":53,"props":2062,"children":2063},{},[2064],{"type":50,"value":2065},"As the OFFSET grows, CockroachDB must scan and discard more rows. Keyset pagination uses the last row's ordered key values to jump directly to the next page.",{"type":45,"tag":53,"props":2067,"children":2068},{},[2069],{"type":45,"tag":62,"props":2070,"children":2071},{},[2072],{"type":50,"value":2073},"OFFSET\u002FLIMIT (inefficient at depth):",{"type":45,"tag":224,"props":2075,"children":2077},{"className":457,"code":2076,"language":459,"meta":229,"style":229},"SELECT id, order_date, customer_id\nFROM orders\nORDER BY id\nLIMIT 100 OFFSET 5000;\n",[2078],{"type":45,"tag":232,"props":2079,"children":2080},{"__ignoreMap":229},[2081,2089,2097,2105],{"type":45,"tag":236,"props":2082,"children":2083},{"class":238,"line":239},[2084],{"type":45,"tag":236,"props":2085,"children":2086},{},[2087],{"type":50,"value":2088},"SELECT id, order_date, customer_id\n",{"type":45,"tag":236,"props":2090,"children":2091},{"class":238,"line":26},[2092],{"type":45,"tag":236,"props":2093,"children":2094},{},[2095],{"type":50,"value":2096},"FROM orders\n",{"type":45,"tag":236,"props":2098,"children":2099},{"class":238,"line":22},[2100],{"type":45,"tag":236,"props":2101,"children":2102},{},[2103],{"type":50,"value":2104},"ORDER BY id\n",{"type":45,"tag":236,"props":2106,"children":2107},{"class":238,"line":264},[2108],{"type":45,"tag":236,"props":2109,"children":2110},{},[2111],{"type":50,"value":2112},"LIMIT 100 OFFSET 5000;\n",{"type":45,"tag":53,"props":2114,"children":2115},{},[2116],{"type":45,"tag":62,"props":2117,"children":2118},{},[2119],{"type":50,"value":2120},"Keyset pagination (preferred):",{"type":45,"tag":224,"props":2122,"children":2124},{"className":457,"code":2123,"language":459,"meta":229,"style":229},"SELECT id, order_date, customer_id\nFROM orders\nWHERE id > 5000\nORDER BY id\nLIMIT 100;\n",[2125],{"type":45,"tag":232,"props":2126,"children":2127},{"__ignoreMap":229},[2128,2135,2142,2150,2157],{"type":45,"tag":236,"props":2129,"children":2130},{"class":238,"line":239},[2131],{"type":45,"tag":236,"props":2132,"children":2133},{},[2134],{"type":50,"value":2088},{"type":45,"tag":236,"props":2136,"children":2137},{"class":238,"line":26},[2138],{"type":45,"tag":236,"props":2139,"children":2140},{},[2141],{"type":50,"value":2096},{"type":45,"tag":236,"props":2143,"children":2144},{"class":238,"line":22},[2145],{"type":45,"tag":236,"props":2146,"children":2147},{},[2148],{"type":50,"value":2149},"WHERE id > 5000\n",{"type":45,"tag":236,"props":2151,"children":2152},{"class":238,"line":264},[2153],{"type":45,"tag":236,"props":2154,"children":2155},{},[2156],{"type":50,"value":2104},{"type":45,"tag":236,"props":2158,"children":2159},{"class":238,"line":273},[2160],{"type":45,"tag":236,"props":2161,"children":2162},{},[2163],{"type":50,"value":2164},"LIMIT 100;\n",{"type":45,"tag":53,"props":2166,"children":2167},{},[2168],{"type":45,"tag":62,"props":2169,"children":2170},{},[2171],{"type":50,"value":2172},"Multi-column keyset:",{"type":45,"tag":224,"props":2174,"children":2176},{"className":457,"code":2175,"language":459,"meta":229,"style":229},"SELECT id, created_at, customer_id\nFROM orders\nWHERE (created_at, id) > ('2025-01-01 00:00:00', 5000)\nORDER BY created_at, id\nLIMIT 100;\n",[2177],{"type":45,"tag":232,"props":2178,"children":2179},{"__ignoreMap":229},[2180,2188,2195,2203,2211],{"type":45,"tag":236,"props":2181,"children":2182},{"class":238,"line":239},[2183],{"type":45,"tag":236,"props":2184,"children":2185},{},[2186],{"type":50,"value":2187},"SELECT id, created_at, customer_id\n",{"type":45,"tag":236,"props":2189,"children":2190},{"class":238,"line":26},[2191],{"type":45,"tag":236,"props":2192,"children":2193},{},[2194],{"type":50,"value":2096},{"type":45,"tag":236,"props":2196,"children":2197},{"class":238,"line":22},[2198],{"type":45,"tag":236,"props":2199,"children":2200},{},[2201],{"type":50,"value":2202},"WHERE (created_at, id) > ('2025-01-01 00:00:00', 5000)\n",{"type":45,"tag":236,"props":2204,"children":2205},{"class":238,"line":264},[2206],{"type":45,"tag":236,"props":2207,"children":2208},{},[2209],{"type":50,"value":2210},"ORDER BY created_at, id\n",{"type":45,"tag":236,"props":2212,"children":2213},{"class":238,"line":273},[2214],{"type":45,"tag":236,"props":2215,"children":2216},{},[2217],{"type":50,"value":2164},{"type":45,"tag":53,"props":2219,"children":2220},{},[2221,2225],{"type":45,"tag":62,"props":2222,"children":2223},{},[2224],{"type":50,"value":1535},{"type":50,"value":2226}," Keyset pagination is ideal for next\u002Fprevious navigation but not for arbitrary \"jump to page 73\" UX.",{"type":45,"tag":199,"props":2228,"children":2230},{"id":2229},"_10-use-prepared-statements-for-performance-and-security",[2231],{"type":50,"value":2232},"10. Use Prepared Statements for Performance and Security",{"type":45,"tag":53,"props":2234,"children":2235},{},[2236],{"type":50,"value":2237},"Prepared statements reuse query structure and bind new values, improving performance through plan reuse and protecting against SQL injection.",{"type":45,"tag":53,"props":2239,"children":2240},{},[2241],{"type":45,"tag":62,"props":2242,"children":2243},{},[2244],{"type":50,"value":2245},"Unsafe dynamic string concatenation:",{"type":45,"tag":224,"props":2247,"children":2249},{"className":606,"code":2248,"language":608,"meta":229,"style":229},"query = f\"SELECT * FROM users WHERE username = '{user_input}'\"\ncursor.execute(query)\n",[2250],{"type":45,"tag":232,"props":2251,"children":2252},{"__ignoreMap":229},[2253,2261],{"type":45,"tag":236,"props":2254,"children":2255},{"class":238,"line":239},[2256],{"type":45,"tag":236,"props":2257,"children":2258},{},[2259],{"type":50,"value":2260},"query = f\"SELECT * FROM users WHERE username = '{user_input}'\"\n",{"type":45,"tag":236,"props":2262,"children":2263},{"class":238,"line":26},[2264],{"type":45,"tag":236,"props":2265,"children":2266},{},[2267],{"type":50,"value":2268},"cursor.execute(query)\n",{"type":45,"tag":53,"props":2270,"children":2271},{},[2272],{"type":45,"tag":62,"props":2273,"children":2274},{},[2275],{"type":50,"value":2276},"Prepared \u002F parameterized execution:",{"type":45,"tag":224,"props":2278,"children":2280},{"className":606,"code":2279,"language":608,"meta":229,"style":229},"cursor.execute(\"SELECT * FROM users WHERE username = %s;\", (user_input,))\n",[2281],{"type":45,"tag":232,"props":2282,"children":2283},{"__ignoreMap":229},[2284],{"type":45,"tag":236,"props":2285,"children":2286},{"class":238,"line":239},[2287],{"type":45,"tag":236,"props":2288,"children":2289},{},[2290],{"type":50,"value":2279},{"type":45,"tag":53,"props":2292,"children":2293},{},[2294],{"type":45,"tag":62,"props":2295,"children":2296},{},[2297],{"type":50,"value":2298},"Plan reuse:",{"type":45,"tag":224,"props":2300,"children":2302},{"className":457,"code":2301,"language":459,"meta":229,"style":229},"PREPARE get_balance AS\nSELECT balance FROM accounts WHERE id = $1;\n\nEXECUTE get_balance(1001);\nEXECUTE get_balance(2002);\n",[2303],{"type":45,"tag":232,"props":2304,"children":2305},{"__ignoreMap":229},[2306,2314,2322,2329,2337],{"type":45,"tag":236,"props":2307,"children":2308},{"class":238,"line":239},[2309],{"type":45,"tag":236,"props":2310,"children":2311},{},[2312],{"type":50,"value":2313},"PREPARE get_balance AS\n",{"type":45,"tag":236,"props":2315,"children":2316},{"class":238,"line":26},[2317],{"type":45,"tag":236,"props":2318,"children":2319},{},[2320],{"type":50,"value":2321},"SELECT balance FROM accounts WHERE id = $1;\n",{"type":45,"tag":236,"props":2323,"children":2324},{"class":238,"line":22},[2325],{"type":45,"tag":236,"props":2326,"children":2327},{"emptyLinePlaceholder":329},[2328],{"type":50,"value":332},{"type":45,"tag":236,"props":2330,"children":2331},{"class":238,"line":264},[2332],{"type":45,"tag":236,"props":2333,"children":2334},{},[2335],{"type":50,"value":2336},"EXECUTE get_balance(1001);\n",{"type":45,"tag":236,"props":2338,"children":2339},{"class":238,"line":273},[2340],{"type":45,"tag":236,"props":2341,"children":2342},{},[2343],{"type":50,"value":2344},"EXECUTE get_balance(2002);\n",{"type":45,"tag":199,"props":2346,"children":2348},{"id":2347},"_11-use-column-projections-instead-of-select",[2349],{"type":50,"value":2350},"11. Use Column Projections Instead of SELECT *",{"type":45,"tag":53,"props":2352,"children":2353},{},[2354,2356,2362],{"type":50,"value":2355},"Select only the columns you need. ",{"type":45,"tag":232,"props":2357,"children":2359},{"className":2358},[],[2360],{"type":50,"value":2361},"SELECT *",{"type":50,"value":2363}," increases network payload, memory usage, CPU cost, and prevents narrower index-only scans.",{"type":45,"tag":224,"props":2365,"children":2367},{"className":457,"code":2366,"language":459,"meta":229,"style":229},"-- Avoid\nSELECT * FROM users WHERE id = 101;\n\n-- Preferred\nSELECT name, email FROM users WHERE id = 101;\n",[2368],{"type":45,"tag":232,"props":2369,"children":2370},{"__ignoreMap":229},[2371,2379,2387,2394,2402],{"type":45,"tag":236,"props":2372,"children":2373},{"class":238,"line":239},[2374],{"type":45,"tag":236,"props":2375,"children":2376},{},[2377],{"type":50,"value":2378},"-- Avoid\n",{"type":45,"tag":236,"props":2380,"children":2381},{"class":238,"line":26},[2382],{"type":45,"tag":236,"props":2383,"children":2384},{},[2385],{"type":50,"value":2386},"SELECT * FROM users WHERE id = 101;\n",{"type":45,"tag":236,"props":2388,"children":2389},{"class":238,"line":22},[2390],{"type":45,"tag":236,"props":2391,"children":2392},{"emptyLinePlaceholder":329},[2393],{"type":50,"value":332},{"type":45,"tag":236,"props":2395,"children":2396},{"class":238,"line":264},[2397],{"type":45,"tag":236,"props":2398,"children":2399},{},[2400],{"type":50,"value":2401},"-- Preferred\n",{"type":45,"tag":236,"props":2403,"children":2404},{"class":238,"line":273},[2405],{"type":45,"tag":236,"props":2406,"children":2407},{},[2408],{"type":50,"value":2409},"SELECT name, email FROM users WHERE id = 101;\n",{"type":45,"tag":53,"props":2411,"children":2412},{},[2413,2418,2420,2426,2428,2433],{"type":45,"tag":62,"props":2414,"children":2415},{},[2416],{"type":50,"value":2417},"Schema evolution impact:",{"type":50,"value":2419}," If a later schema change adds ",{"type":45,"tag":232,"props":2421,"children":2423},{"className":2422},[],[2424],{"type":50,"value":2425},"profile_picture BYTEA",{"type":50,"value":2427},", queries using ",{"type":45,"tag":232,"props":2429,"children":2431},{"className":2430},[],[2432],{"type":50,"value":2361},{"type":50,"value":2434}," automatically pull that extra data. Explicit projections avoid this hidden performance regression.",{"type":45,"tag":199,"props":2436,"children":2438},{"id":2437},"_12-design-keys-and-indexes-to-distribute-load",[2439],{"type":50,"value":2440},"12. Design Keys and Indexes to Distribute Load",{"type":45,"tag":53,"props":2442,"children":2443},{},[2444],{"type":50,"value":2445},"Sequential or monotonically increasing primary keys create write hotspots. Keys and indexes should distribute reads and writes across ranges evenly.",{"type":45,"tag":53,"props":2447,"children":2448},{},[2449],{"type":45,"tag":62,"props":2450,"children":2451},{},[2452],{"type":50,"value":2453},"Hotspot anti-pattern:",{"type":45,"tag":224,"props":2455,"children":2457},{"className":457,"code":2456,"language":459,"meta":229,"style":229},"CREATE TABLE orders (\n id SERIAL PRIMARY KEY,\n customer_id UUID,\n region STRING\n);\n",[2458],{"type":45,"tag":232,"props":2459,"children":2460},{"__ignoreMap":229},[2461,2469,2477,2485,2493],{"type":45,"tag":236,"props":2462,"children":2463},{"class":238,"line":239},[2464],{"type":45,"tag":236,"props":2465,"children":2466},{},[2467],{"type":50,"value":2468},"CREATE TABLE orders (\n",{"type":45,"tag":236,"props":2470,"children":2471},{"class":238,"line":26},[2472],{"type":45,"tag":236,"props":2473,"children":2474},{},[2475],{"type":50,"value":2476}," id SERIAL PRIMARY KEY,\n",{"type":45,"tag":236,"props":2478,"children":2479},{"class":238,"line":22},[2480],{"type":45,"tag":236,"props":2481,"children":2482},{},[2483],{"type":50,"value":2484}," customer_id UUID,\n",{"type":45,"tag":236,"props":2486,"children":2487},{"class":238,"line":264},[2488],{"type":45,"tag":236,"props":2489,"children":2490},{},[2491],{"type":50,"value":2492}," region STRING\n",{"type":45,"tag":236,"props":2494,"children":2495},{"class":238,"line":273},[2496],{"type":45,"tag":236,"props":2497,"children":2498},{},[2499],{"type":50,"value":2500},");\n",{"type":45,"tag":53,"props":2502,"children":2503},{},[2504],{"type":45,"tag":62,"props":2505,"children":2506},{},[2507],{"type":50,"value":2508},"Randomized key:",{"type":45,"tag":224,"props":2510,"children":2512},{"className":457,"code":2511,"language":459,"meta":229,"style":229},"CREATE TABLE orders (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n customer_id UUID,\n region STRING\n);\n",[2513],{"type":45,"tag":232,"props":2514,"children":2515},{"__ignoreMap":229},[2516,2523,2531,2538,2545],{"type":45,"tag":236,"props":2517,"children":2518},{"class":238,"line":239},[2519],{"type":45,"tag":236,"props":2520,"children":2521},{},[2522],{"type":50,"value":2468},{"type":45,"tag":236,"props":2524,"children":2525},{"class":238,"line":26},[2526],{"type":45,"tag":236,"props":2527,"children":2528},{},[2529],{"type":50,"value":2530}," id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n",{"type":45,"tag":236,"props":2532,"children":2533},{"class":238,"line":22},[2534],{"type":45,"tag":236,"props":2535,"children":2536},{},[2537],{"type":50,"value":2484},{"type":45,"tag":236,"props":2539,"children":2540},{"class":238,"line":264},[2541],{"type":45,"tag":236,"props":2542,"children":2543},{},[2544],{"type":50,"value":2492},{"type":45,"tag":236,"props":2546,"children":2547},{"class":238,"line":273},[2548],{"type":45,"tag":236,"props":2549,"children":2550},{},[2551],{"type":50,"value":2500},{"type":45,"tag":53,"props":2553,"children":2554},{},[2555],{"type":45,"tag":62,"props":2556,"children":2557},{},[2558],{"type":50,"value":2559},"Hash-sharded index:",{"type":45,"tag":224,"props":2561,"children":2563},{"className":457,"code":2562,"language":459,"meta":229,"style":229},"CREATE INDEX orders_by_id_hash\nON orders (id)\nUSING HASH SHARDED WITH BUCKET_COUNT = 16;\n",[2564],{"type":45,"tag":232,"props":2565,"children":2566},{"__ignoreMap":229},[2567,2575,2583],{"type":45,"tag":236,"props":2568,"children":2569},{"class":238,"line":239},[2570],{"type":45,"tag":236,"props":2571,"children":2572},{},[2573],{"type":50,"value":2574},"CREATE INDEX orders_by_id_hash\n",{"type":45,"tag":236,"props":2576,"children":2577},{"class":238,"line":26},[2578],{"type":45,"tag":236,"props":2579,"children":2580},{},[2581],{"type":50,"value":2582},"ON orders (id)\n",{"type":45,"tag":236,"props":2584,"children":2585},{"class":238,"line":22},[2586],{"type":45,"tag":236,"props":2587,"children":2588},{},[2589],{"type":50,"value":2590},"USING HASH SHARDED WITH BUCKET_COUNT = 16;\n",{"type":45,"tag":53,"props":2592,"children":2593},{},[2594],{"type":45,"tag":62,"props":2595,"children":2596},{},[2597],{"type":50,"value":2598},"Composite key for natural distribution:",{"type":45,"tag":224,"props":2600,"children":2602},{"className":457,"code":2601,"language":459,"meta":229,"style":229},"CREATE TABLE sales (\n region_id STRING,\n order_id UUID DEFAULT gen_random_uuid(),\n PRIMARY KEY (region_id, order_id)\n);\n",[2603],{"type":45,"tag":232,"props":2604,"children":2605},{"__ignoreMap":229},[2606,2614,2622,2630,2638],{"type":45,"tag":236,"props":2607,"children":2608},{"class":238,"line":239},[2609],{"type":45,"tag":236,"props":2610,"children":2611},{},[2612],{"type":50,"value":2613},"CREATE TABLE sales (\n",{"type":45,"tag":236,"props":2615,"children":2616},{"class":238,"line":26},[2617],{"type":45,"tag":236,"props":2618,"children":2619},{},[2620],{"type":50,"value":2621}," region_id STRING,\n",{"type":45,"tag":236,"props":2623,"children":2624},{"class":238,"line":22},[2625],{"type":45,"tag":236,"props":2626,"children":2627},{},[2628],{"type":50,"value":2629}," order_id UUID DEFAULT gen_random_uuid(),\n",{"type":45,"tag":236,"props":2631,"children":2632},{"class":238,"line":264},[2633],{"type":45,"tag":236,"props":2634,"children":2635},{},[2636],{"type":50,"value":2637}," PRIMARY KEY (region_id, order_id)\n",{"type":45,"tag":236,"props":2639,"children":2640},{"class":238,"line":273},[2641],{"type":45,"tag":236,"props":2642,"children":2643},{},[2644],{"type":50,"value":2500},{"type":45,"tag":53,"props":2646,"children":2647},{},[2648],{"type":45,"tag":62,"props":2649,"children":2650},{},[2651],{"type":50,"value":2652},"Enforce explicit PKs cluster-wide:",{"type":45,"tag":224,"props":2654,"children":2656},{"className":457,"code":2655,"language":459,"meta":229,"style":229},"SET CLUSTER SETTING sql.defaults.require_explicit_primary_keys.enabled = true;\n",[2657],{"type":45,"tag":232,"props":2658,"children":2659},{"__ignoreMap":229},[2660],{"type":45,"tag":236,"props":2661,"children":2662},{"class":238,"line":239},[2663],{"type":45,"tag":236,"props":2664,"children":2665},{},[2666],{"type":50,"value":2655},{"type":45,"tag":199,"props":2668,"children":2670},{"id":2669},"_13-configure-connection-pooling",[2671],{"type":50,"value":2672},"13. Configure Connection Pooling",{"type":45,"tag":53,"props":2674,"children":2675},{},[2676],{"type":50,"value":2677},"Opening new database connections is expensive. Pooling reuses live connections to improve performance and prevent overload.",{"type":45,"tag":53,"props":2679,"children":2680},{},[2681],{"type":45,"tag":62,"props":2682,"children":2683},{},[2684],{"type":50,"value":2685},"HikariCP guidance:",{"type":45,"tag":224,"props":2687,"children":2691},{"className":2688,"code":2689,"language":2690,"meta":229,"style":229},"language-yaml shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","maximumPoolSize: (vCPUs * 4) \u002F number_of_pool_instances\nminimumIdle: equal to maximumPoolSize\nmaxLifetime: 30 min (add jitter +\u002F- 5 min)\nidleTimeout: 5-10 min typical\nkeepaliveTime: slightly shorter than infrastructure timeout (~5 min)\nconnectionTimeout: 10-30 s typical\nautoCommit: true unless using explicit transactions only\n","yaml",[2692],{"type":45,"tag":232,"props":2693,"children":2694},{"__ignoreMap":229},[2695,2716,2733,2750,2767,2784,2801],{"type":45,"tag":236,"props":2696,"children":2697},{"class":238,"line":239},[2698,2704,2710],{"type":45,"tag":236,"props":2699,"children":2701},{"style":2700},"--shiki-light:#E53935;--shiki-default:#F07178;--shiki-dark:#F07178",[2702],{"type":50,"value":2703},"maximumPoolSize",{"type":45,"tag":236,"props":2705,"children":2707},{"style":2706},"--shiki-light:#39ADB5;--shiki-default:#89DDFF;--shiki-dark:#89DDFF",[2708],{"type":50,"value":2709},":",{"type":45,"tag":236,"props":2711,"children":2713},{"style":2712},"--shiki-light:#91B859;--shiki-default:#C3E88D;--shiki-dark:#C3E88D",[2714],{"type":50,"value":2715}," (vCPUs * 4) \u002F number_of_pool_instances\n",{"type":45,"tag":236,"props":2717,"children":2718},{"class":238,"line":26},[2719,2724,2728],{"type":45,"tag":236,"props":2720,"children":2721},{"style":2700},[2722],{"type":50,"value":2723},"minimumIdle",{"type":45,"tag":236,"props":2725,"children":2726},{"style":2706},[2727],{"type":50,"value":2709},{"type":45,"tag":236,"props":2729,"children":2730},{"style":2712},[2731],{"type":50,"value":2732}," equal to maximumPoolSize\n",{"type":45,"tag":236,"props":2734,"children":2735},{"class":238,"line":22},[2736,2741,2745],{"type":45,"tag":236,"props":2737,"children":2738},{"style":2700},[2739],{"type":50,"value":2740},"maxLifetime",{"type":45,"tag":236,"props":2742,"children":2743},{"style":2706},[2744],{"type":50,"value":2709},{"type":45,"tag":236,"props":2746,"children":2747},{"style":2712},[2748],{"type":50,"value":2749}," 30 min (add jitter +\u002F- 5 min)\n",{"type":45,"tag":236,"props":2751,"children":2752},{"class":238,"line":264},[2753,2758,2762],{"type":45,"tag":236,"props":2754,"children":2755},{"style":2700},[2756],{"type":50,"value":2757},"idleTimeout",{"type":45,"tag":236,"props":2759,"children":2760},{"style":2706},[2761],{"type":50,"value":2709},{"type":45,"tag":236,"props":2763,"children":2764},{"style":2712},[2765],{"type":50,"value":2766}," 5-10 min typical\n",{"type":45,"tag":236,"props":2768,"children":2769},{"class":238,"line":273},[2770,2775,2779],{"type":45,"tag":236,"props":2771,"children":2772},{"style":2700},[2773],{"type":50,"value":2774},"keepaliveTime",{"type":45,"tag":236,"props":2776,"children":2777},{"style":2706},[2778],{"type":50,"value":2709},{"type":45,"tag":236,"props":2780,"children":2781},{"style":2712},[2782],{"type":50,"value":2783}," slightly shorter than infrastructure timeout (~5 min)\n",{"type":45,"tag":236,"props":2785,"children":2786},{"class":238,"line":335},[2787,2792,2796],{"type":45,"tag":236,"props":2788,"children":2789},{"style":2700},[2790],{"type":50,"value":2791},"connectionTimeout",{"type":45,"tag":236,"props":2793,"children":2794},{"style":2706},[2795],{"type":50,"value":2709},{"type":45,"tag":236,"props":2797,"children":2798},{"style":2712},[2799],{"type":50,"value":2800}," 10-30 s typical\n",{"type":45,"tag":236,"props":2802,"children":2803},{"class":238,"line":344},[2804,2809,2813],{"type":45,"tag":236,"props":2805,"children":2806},{"style":2700},[2807],{"type":50,"value":2808},"autoCommit",{"type":45,"tag":236,"props":2810,"children":2811},{"style":2706},[2812],{"type":50,"value":2709},{"type":45,"tag":236,"props":2814,"children":2815},{"style":2712},[2816],{"type":50,"value":2817}," true unless using explicit transactions only\n",{"type":45,"tag":53,"props":2819,"children":2820},{},[2821],{"type":45,"tag":62,"props":2822,"children":2823},{},[2824],{"type":50,"value":2825},"Example stable configuration:",{"type":45,"tag":224,"props":2827,"children":2829},{"className":2688,"code":2828,"language":2690,"meta":229,"style":229},"maximum-pool-size: 12\nminimum-idle: 12\nmax-lifetime: 1800000\nidle-timeout: 600000\nkeepalive-time: 300000\nconnection-timeout: 10000\nauto-commit: true\npool-name: ingestionPool\n",[2830],{"type":45,"tag":232,"props":2831,"children":2832},{"__ignoreMap":229},[2833,2851,2867,2884,2901,2918,2935,2953],{"type":45,"tag":236,"props":2834,"children":2835},{"class":238,"line":239},[2836,2841,2845],{"type":45,"tag":236,"props":2837,"children":2838},{"style":2700},[2839],{"type":50,"value":2840},"maximum-pool-size",{"type":45,"tag":236,"props":2842,"children":2843},{"style":2706},[2844],{"type":50,"value":2709},{"type":45,"tag":236,"props":2846,"children":2848},{"style":2847},"--shiki-light:#F76D47;--shiki-default:#F78C6C;--shiki-dark:#F78C6C",[2849],{"type":50,"value":2850}," 12\n",{"type":45,"tag":236,"props":2852,"children":2853},{"class":238,"line":26},[2854,2859,2863],{"type":45,"tag":236,"props":2855,"children":2856},{"style":2700},[2857],{"type":50,"value":2858},"minimum-idle",{"type":45,"tag":236,"props":2860,"children":2861},{"style":2706},[2862],{"type":50,"value":2709},{"type":45,"tag":236,"props":2864,"children":2865},{"style":2847},[2866],{"type":50,"value":2850},{"type":45,"tag":236,"props":2868,"children":2869},{"class":238,"line":22},[2870,2875,2879],{"type":45,"tag":236,"props":2871,"children":2872},{"style":2700},[2873],{"type":50,"value":2874},"max-lifetime",{"type":45,"tag":236,"props":2876,"children":2877},{"style":2706},[2878],{"type":50,"value":2709},{"type":45,"tag":236,"props":2880,"children":2881},{"style":2847},[2882],{"type":50,"value":2883}," 1800000\n",{"type":45,"tag":236,"props":2885,"children":2886},{"class":238,"line":264},[2887,2892,2896],{"type":45,"tag":236,"props":2888,"children":2889},{"style":2700},[2890],{"type":50,"value":2891},"idle-timeout",{"type":45,"tag":236,"props":2893,"children":2894},{"style":2706},[2895],{"type":50,"value":2709},{"type":45,"tag":236,"props":2897,"children":2898},{"style":2847},[2899],{"type":50,"value":2900}," 600000\n",{"type":45,"tag":236,"props":2902,"children":2903},{"class":238,"line":273},[2904,2909,2913],{"type":45,"tag":236,"props":2905,"children":2906},{"style":2700},[2907],{"type":50,"value":2908},"keepalive-time",{"type":45,"tag":236,"props":2910,"children":2911},{"style":2706},[2912],{"type":50,"value":2709},{"type":45,"tag":236,"props":2914,"children":2915},{"style":2847},[2916],{"type":50,"value":2917}," 300000\n",{"type":45,"tag":236,"props":2919,"children":2920},{"class":238,"line":335},[2921,2926,2930],{"type":45,"tag":236,"props":2922,"children":2923},{"style":2700},[2924],{"type":50,"value":2925},"connection-timeout",{"type":45,"tag":236,"props":2927,"children":2928},{"style":2706},[2929],{"type":50,"value":2709},{"type":45,"tag":236,"props":2931,"children":2932},{"style":2847},[2933],{"type":50,"value":2934}," 10000\n",{"type":45,"tag":236,"props":2936,"children":2937},{"class":238,"line":344},[2938,2943,2947],{"type":45,"tag":236,"props":2939,"children":2940},{"style":2700},[2941],{"type":50,"value":2942},"auto-commit",{"type":45,"tag":236,"props":2944,"children":2945},{"style":2706},[2946],{"type":50,"value":2709},{"type":45,"tag":236,"props":2948,"children":2950},{"style":2949},"--shiki-light:#FF5370;--shiki-default:#FF9CAC;--shiki-dark:#FF9CAC",[2951],{"type":50,"value":2952}," true\n",{"type":45,"tag":236,"props":2954,"children":2955},{"class":238,"line":670},[2956,2961,2965],{"type":45,"tag":236,"props":2957,"children":2958},{"style":2700},[2959],{"type":50,"value":2960},"pool-name",{"type":45,"tag":236,"props":2962,"children":2963},{"style":2706},[2964],{"type":50,"value":2709},{"type":45,"tag":236,"props":2966,"children":2967},{"style":2712},[2968],{"type":50,"value":2969}," ingestionPool\n",{"type":45,"tag":199,"props":2971,"children":2973},{"id":2972},"_14-separate-business-logic-from-database-logic",[2974],{"type":50,"value":2975},"14. Separate Business Logic from Database Logic",{"type":45,"tag":53,"props":2977,"children":2978},{},[2979],{"type":50,"value":2980},"CockroachDB should manage ACID reads, writes, and schema-level integrity. The application layer should orchestrate workflows, external services, queues, and long-running work.",{"type":45,"tag":53,"props":2982,"children":2983},{},[2984],{"type":45,"tag":62,"props":2985,"children":2986},{},[2987],{"type":50,"value":2988},"Inside the transaction:",{"type":45,"tag":94,"props":2990,"children":2991},{},[2992],{"type":45,"tag":98,"props":2993,"children":2994},{},[2995],{"type":50,"value":2996},"Reads, writes, constraints, short guarded state transitions",{"type":45,"tag":53,"props":2998,"children":2999},{},[3000],{"type":45,"tag":62,"props":3001,"children":3002},{},[3003],{"type":50,"value":3004},"Outside the transaction:",{"type":45,"tag":94,"props":3006,"children":3007},{},[3008],{"type":45,"tag":98,"props":3009,"children":3010},{},[3011],{"type":50,"value":3012},"HTTP calls, RPC\u002Fservice calls, email, payment providers, queue publishing",{"type":45,"tag":53,"props":3014,"children":3015},{},[3016],{"type":45,"tag":62,"props":3017,"children":3018},{},[3019],{"type":50,"value":3020},"Asynchronous workflow pattern:",{"type":45,"tag":224,"props":3022,"children":3024},{"className":606,"code":3023,"language":608,"meta":229,"style":229},"def handle_order(order):\n db.execute(\"INSERT INTO orders (id, status) VALUES (%s, %s)\", (order.id, 'PENDING'))\n publish_event('process_order', {'order_id': order.id})\n",[3025],{"type":45,"tag":232,"props":3026,"children":3027},{"__ignoreMap":229},[3028,3036,3044],{"type":45,"tag":236,"props":3029,"children":3030},{"class":238,"line":239},[3031],{"type":45,"tag":236,"props":3032,"children":3033},{},[3034],{"type":50,"value":3035},"def handle_order(order):\n",{"type":45,"tag":236,"props":3037,"children":3038},{"class":238,"line":26},[3039],{"type":45,"tag":236,"props":3040,"children":3041},{},[3042],{"type":50,"value":3043}," db.execute(\"INSERT INTO orders (id, status) VALUES (%s, %s)\", (order.id, 'PENDING'))\n",{"type":45,"tag":236,"props":3045,"children":3046},{"class":238,"line":22},[3047],{"type":45,"tag":236,"props":3048,"children":3049},{},[3050],{"type":50,"value":3051}," publish_event('process_order', {'order_id': order.id})\n",{"type":45,"tag":199,"props":3053,"children":3055},{"id":3054},"_15-respect-the-16mb-transaction-payload-limit",[3056],{"type":50,"value":3057},"15. Respect the 16MB Transaction Payload Limit",{"type":45,"tag":53,"props":3059,"children":3060},{},[3061],{"type":50,"value":3062},"CockroachDB has a practical limit of ~16MB per transaction payload. This limit applies to the TOTAL data written in a single transaction, not just individual rows.",{"type":45,"tag":53,"props":3064,"children":3065},{},[3066],{"type":45,"tag":62,"props":3067,"children":3068},{},[3069],{"type":50,"value":3070},"Two ways to hit the limit:",{"type":45,"tag":94,"props":3072,"children":3073},{},[3074,3079],{"type":45,"tag":98,"props":3075,"children":3076},{},[3077],{"type":50,"value":3078},"One large row (e.g., a 15MB JSON document)",{"type":45,"tag":98,"props":3080,"children":3081},{},[3082],{"type":50,"value":3083},"Many moderate rows in one transaction (e.g., 25 INSERTs of 500KB each = 12.5MB)",{"type":45,"tag":53,"props":3085,"children":3086},{},[3087],{"type":45,"tag":62,"props":3088,"children":3089},{},[3090],{"type":50,"value":3091},"Guidelines:",{"type":45,"tag":94,"props":3093,"children":3094},{},[3095,3100,3105,3110,3115,3120],{"type":45,"tag":98,"props":3096,"children":3097},{},[3098],{"type":50,"value":3099},"Keep individual rows under 1MB",{"type":45,"tag":98,"props":3101,"children":3102},{},[3103],{"type":50,"value":3104},"Keep total transaction payload under 4MB",{"type":45,"tag":98,"props":3106,"children":3107},{},[3108],{"type":50,"value":3109},"Limit transactions to \u003C10 statements",{"type":45,"tag":98,"props":3111,"children":3112},{},[3113],{"type":50,"value":3114},"Chunk large documents into 64-256KB pieces",{"type":45,"tag":98,"props":3116,"children":3117},{},[3118],{"type":50,"value":3119},"Store blobs >1MB in object storage (S3\u002FGCS) with a database reference",{"type":45,"tag":98,"props":3121,"children":3122},{},[3123],{"type":50,"value":3124},"Break multi-statement transactions into smaller batches (commit every 5-10 statements)",{"type":45,"tag":53,"props":3126,"children":3127},{},[3128,3141],{"type":45,"tag":62,"props":3129,"children":3130},{},[3131,3133,3139],{"type":50,"value":3132},"Exceeding the limit causes ",{"type":45,"tag":232,"props":3134,"children":3136},{"className":3135},[],[3137],{"type":50,"value":3138},"split failed while applying backpressure to Put",{"type":50,"value":3140}," errors:",{"type":50,"value":3142}," large Raft proposals block consensus, range splits stall, and the system applies backpressure.",{"type":45,"tag":199,"props":3144,"children":3146},{"id":3145},"_16-use-session-guardrails",[3147],{"type":50,"value":3148},"16. Use Session Guardrails",{"type":45,"tag":53,"props":3150,"children":3151},{},[3152],{"type":50,"value":3153},"Set session-level guardrails to catch runaway queries and missing WHERE clauses during development and testing:",{"type":45,"tag":224,"props":3155,"children":3157},{"className":457,"code":3156,"language":459,"meta":229,"style":229},"SET transaction_rows_read_err = 10000;\nSET transaction_rows_written_err = 1000;\n",[3158],{"type":45,"tag":232,"props":3159,"children":3160},{"__ignoreMap":229},[3161,3169],{"type":45,"tag":236,"props":3162,"children":3163},{"class":238,"line":239},[3164],{"type":45,"tag":236,"props":3165,"children":3166},{},[3167],{"type":50,"value":3168},"SET transaction_rows_read_err = 10000;\n",{"type":45,"tag":236,"props":3170,"children":3171},{"class":238,"line":26},[3172],{"type":45,"tag":236,"props":3173,"children":3174},{},[3175],{"type":50,"value":3176},"SET transaction_rows_written_err = 1000;\n",{"type":45,"tag":53,"props":3178,"children":3179},{},[3180],{"type":50,"value":3181},"These cause transactions that exceed the thresholds to fail with an explicit error rather than silently consuming cluster resources.",{"type":45,"tag":199,"props":3183,"children":3185},{"id":3184},"_17-test-and-optimize-under-concurrency",[3186],{"type":50,"value":3187},"17. Test and Optimize Under Concurrency",{"type":45,"tag":53,"props":3189,"children":3190},{},[3191],{"type":50,"value":3192},"Single-user correctness is not sufficient. Test with realistic concurrency to surface retries, hotspots, contention, and workload-specific bottlenecks.",{"type":45,"tag":53,"props":3194,"children":3195},{},[3196],{"type":45,"tag":62,"props":3197,"children":3198},{},[3199],{"type":50,"value":3200},"Quick start:",{"type":45,"tag":224,"props":3202,"children":3206},{"className":3203,"code":3204,"language":3205,"meta":229,"style":229},"language-bash shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","cockroach workload init bank 'postgresql:\u002F\u002Froot@localhost:26257?sslmode=disable'\ncockroach workload run bank --concurrency=64 --duration=10m\n","bash",[3207],{"type":45,"tag":232,"props":3208,"children":3209},{"__ignoreMap":229},[3210,3249],{"type":45,"tag":236,"props":3211,"children":3212},{"class":238,"line":239},[3213,3219,3224,3229,3234,3239,3244],{"type":45,"tag":236,"props":3214,"children":3216},{"style":3215},"--shiki-light:#E2931D;--shiki-default:#FFCB6B;--shiki-dark:#FFCB6B",[3217],{"type":50,"value":3218},"cockroach",{"type":45,"tag":236,"props":3220,"children":3221},{"style":2712},[3222],{"type":50,"value":3223}," workload",{"type":45,"tag":236,"props":3225,"children":3226},{"style":2712},[3227],{"type":50,"value":3228}," init",{"type":45,"tag":236,"props":3230,"children":3231},{"style":2712},[3232],{"type":50,"value":3233}," bank",{"type":45,"tag":236,"props":3235,"children":3236},{"style":2706},[3237],{"type":50,"value":3238}," '",{"type":45,"tag":236,"props":3240,"children":3241},{"style":2712},[3242],{"type":50,"value":3243},"postgresql:\u002F\u002Froot@localhost:26257?sslmode=disable",{"type":45,"tag":236,"props":3245,"children":3246},{"style":2706},[3247],{"type":50,"value":3248},"'\n",{"type":45,"tag":236,"props":3250,"children":3251},{"class":238,"line":26},[3252,3256,3260,3265,3269,3274],{"type":45,"tag":236,"props":3253,"children":3254},{"style":3215},[3255],{"type":50,"value":3218},{"type":45,"tag":236,"props":3257,"children":3258},{"style":2712},[3259],{"type":50,"value":3223},{"type":45,"tag":236,"props":3261,"children":3262},{"style":2712},[3263],{"type":50,"value":3264}," run",{"type":45,"tag":236,"props":3266,"children":3267},{"style":2712},[3268],{"type":50,"value":3233},{"type":45,"tag":236,"props":3270,"children":3271},{"style":2712},[3272],{"type":50,"value":3273}," --concurrency=64",{"type":45,"tag":236,"props":3275,"children":3276},{"style":2712},[3277],{"type":50,"value":3278}," --duration=10m\n",{"type":45,"tag":53,"props":3280,"children":3281},{},[3282,3284,3290],{"type":50,"value":3283},"See ",{"type":45,"tag":70,"props":3285,"children":3287},{"href":3286},"references\u002Fmonitoring-and-concurrency-testing.md",[3288],{"type":50,"value":3289},"monitoring-and-concurrency-testing",{"type":50,"value":3291}," for detailed contention queries, validation checklists, and Prometheus metrics.",{"type":45,"tag":199,"props":3293,"children":3295},{"id":3294},"_18-monitor-for-performance-and-contention",[3296],{"type":50,"value":3297},"18. Monitor for Performance and Contention",{"type":45,"tag":53,"props":3299,"children":3300},{},[3301,3303,3309,3310,3316],{"type":50,"value":3302},"Actively monitor query latency, contention, retries, and data distribution using ",{"type":45,"tag":232,"props":3304,"children":3306},{"className":3305},[],[3307],{"type":50,"value":3308},"EXPLAIN ANALYZE",{"type":50,"value":408},{"type":45,"tag":232,"props":3311,"children":3313},{"className":3312},[],[3314],{"type":50,"value":3315},"crdb_internal.transaction_contention_events",{"type":50,"value":3317},", DB Console SQL Activity, and Key Visualizer.",{"type":45,"tag":53,"props":3319,"children":3320},{},[3321,3322,3326],{"type":50,"value":3283},{"type":45,"tag":70,"props":3323,"children":3324},{"href":3286},[3325],{"type":50,"value":3289},{"type":50,"value":3327}," for live contention queries, Prometheus metrics, and external monitoring integration.",{"type":45,"tag":87,"props":3329,"children":3331},{"id":3330},"decision-guide",[3332],{"type":50,"value":3333},"Decision Guide",{"type":45,"tag":817,"props":3335,"children":3336},{},[3337,3353],{"type":45,"tag":821,"props":3338,"children":3339},{},[3340],{"type":45,"tag":825,"props":3341,"children":3342},{},[3343,3348],{"type":45,"tag":829,"props":3344,"children":3345},{},[3346],{"type":50,"value":3347},"Scenario",{"type":45,"tag":829,"props":3349,"children":3350},{},[3351],{"type":50,"value":3352},"Recommended Pattern",{"type":45,"tag":845,"props":3354,"children":3355},{},[3356,3369,3382,3398,3416,3442],{"type":45,"tag":825,"props":3357,"children":3358},{},[3359,3364],{"type":45,"tag":852,"props":3360,"children":3361},{},[3362],{"type":50,"value":3363},"Single SQL statement",{"type":45,"tag":852,"props":3365,"children":3366},{},[3367],{"type":50,"value":3368},"Implicit transaction (autocommit)",{"type":45,"tag":825,"props":3370,"children":3371},{},[3372,3377],{"type":45,"tag":852,"props":3373,"children":3374},{},[3375],{"type":50,"value":3376},"Multiple statements, all-or-nothing",{"type":45,"tag":852,"props":3378,"children":3379},{},[3380],{"type":50,"value":3381},"Explicit transaction with retry loop",{"type":45,"tag":825,"props":3383,"children":3384},{},[3385,3390],{"type":45,"tag":852,"props":3386,"children":3387},{},[3388],{"type":50,"value":3389},"Read current state before write on hot rows",{"type":45,"tag":852,"props":3391,"children":3392},{},[3393],{"type":45,"tag":232,"props":3394,"children":3396},{"className":3395},[],[3397],{"type":50,"value":1430},{"type":45,"tag":825,"props":3399,"children":3400},{},[3401,3406],{"type":45,"tag":852,"props":3402,"children":3403},{},[3404],{"type":50,"value":3405},"Historical, display, or reporting read",{"type":45,"tag":852,"props":3407,"children":3408},{},[3409,3414],{"type":45,"tag":232,"props":3410,"children":3412},{"className":3411},[],[3413],{"type":50,"value":2033},{"type":50,"value":3415}," \u002F follower reads",{"type":45,"tag":825,"props":3417,"children":3418},{},[3419,3424],{"type":45,"tag":852,"props":3420,"children":3421},{},[3422],{"type":50,"value":3423},"Batch of records in memory",{"type":45,"tag":852,"props":3425,"children":3426},{},[3427,3433,3434,3440],{"type":45,"tag":232,"props":3428,"children":3430},{"className":3429},[],[3431],{"type":50,"value":3432},"UNNEST",{"type":50,"value":905},{"type":45,"tag":232,"props":3435,"children":3437},{"className":3436},[],[3438],{"type":50,"value":3439},"VALUES",{"type":50,"value":3441}," \u002F batch SQL",{"type":45,"tag":825,"props":3443,"children":3444},{},[3445,3450],{"type":45,"tag":852,"props":3446,"children":3447},{},[3448],{"type":50,"value":3449},"Multi-step business rule in one operation",{"type":45,"tag":852,"props":3451,"children":3452},{},[3453],{"type":50,"value":3454},"Single-statement CTE",{"type":45,"tag":87,"props":3456,"children":3458},{"id":3457},"safety-considerations",[3459],{"type":50,"value":3460},"Safety Considerations",{"type":45,"tag":94,"props":3462,"children":3463},{},[3464,3476,3489,3494,3506],{"type":45,"tag":98,"props":3465,"children":3466},{},[3467,3469,3474],{"type":50,"value":3468},"Always implement retry logic for ",{"type":45,"tag":232,"props":3470,"children":3472},{"className":3471},[],[3473],{"type":50,"value":377},{"type":50,"value":3475}," serialization errors",{"type":45,"tag":98,"props":3477,"children":3478},{},[3479,3481,3487],{"type":50,"value":3480},"Make operations idempotent so retries do not cause duplicate side effects (use ",{"type":45,"tag":232,"props":3482,"children":3484},{"className":3483},[],[3485],{"type":50,"value":3486},"INSERT ... ON CONFLICT DO NOTHING",{"type":50,"value":3488},")",{"type":45,"tag":98,"props":3490,"children":3491},{},[3492],{"type":50,"value":3493},"Do not use stale snapshot reads as authoritative preconditions for writes",{"type":45,"tag":98,"props":3495,"children":3496},{},[3497,3499,3504],{"type":50,"value":3498},"Do not run ",{"type":45,"tag":232,"props":3500,"children":3502},{"className":3501},[],[3503],{"type":50,"value":3308},{"type":50,"value":3505}," on production queries that modify data",{"type":45,"tag":98,"props":3507,"children":3508},{},[3509],{"type":50,"value":3510},"Be cautious adding indexes to high-traffic tables during peak hours",{"type":45,"tag":87,"props":3512,"children":3514},{"id":3513},"references",[3515],{"type":50,"value":3516},"References",{"type":45,"tag":94,"props":3518,"children":3519},{},[3520,3531,3541,3551,3561,3571,3581,3591,3601,3611,3621,3631,3641,3651,3661,3671,3681,3693],{"type":45,"tag":98,"props":3521,"children":3522},{},[3523],{"type":45,"tag":70,"props":3524,"children":3528},{"href":3525,"rel":3526},"https:\u002F\u002Fwww.cockroachlabs.com\u002Fdocs\u002Fstable\u002Ftransactions",[3527],"nofollow",[3529],{"type":50,"value":3530},"CockroachDB Transactions Documentation",{"type":45,"tag":98,"props":3532,"children":3533},{},[3534],{"type":45,"tag":70,"props":3535,"children":3538},{"href":3536,"rel":3537},"https:\u002F\u002Fwww.cockroachlabs.com\u002Fdocs\u002Fstable\u002Fadvanced-client-side-transaction-retries",[3527],[3539],{"type":50,"value":3540},"Advanced Client-Side Transaction Retries",{"type":45,"tag":98,"props":3542,"children":3543},{},[3544],{"type":45,"tag":70,"props":3545,"children":3548},{"href":3546,"rel":3547},"https:\u002F\u002Fwww.cockroachlabs.com\u002Fdocs\u002Fstable\u002Fperformance-best-practices-overview",[3527],[3549],{"type":50,"value":3550},"SQL Performance Best Practices",{"type":45,"tag":98,"props":3552,"children":3553},{},[3554],{"type":45,"tag":70,"props":3555,"children":3558},{"href":3556,"rel":3557},"https:\u002F\u002Fwww.cockroachlabs.com\u002Fdocs\u002Fstable\u002Ffollower-reads",[3527],[3559],{"type":50,"value":3560},"Follower Reads and Bounded Staleness",{"type":45,"tag":98,"props":3562,"children":3563},{},[3564],{"type":45,"tag":70,"props":3565,"children":3568},{"href":3566,"rel":3567},"https:\u002F\u002Fwww.cockroachlabs.com\u002Fdocs\u002Fstable\u002Fmake-queries-fast",[3527],[3569],{"type":50,"value":3570},"Optimize Statement Performance",{"type":45,"tag":98,"props":3572,"children":3573},{},[3574],{"type":45,"tag":70,"props":3575,"children":3578},{"href":3576,"rel":3577},"https:\u002F\u002Fwww.cockroachlabs.com\u002Fdocs\u002Fstable\u002Frow-level-ttl",[3527],[3579],{"type":50,"value":3580},"Row-Level TTL",{"type":45,"tag":98,"props":3582,"children":3583},{},[3584],{"type":45,"tag":70,"props":3585,"children":3588},{"href":3586,"rel":3587},"https:\u002F\u002Fwww.cockroachlabs.com\u002Fdocs\u002Fstable\u002Fschema-design-indexes",[3527],[3589],{"type":50,"value":3590},"Schema Design and Indexes",{"type":45,"tag":98,"props":3592,"children":3593},{},[3594],{"type":45,"tag":70,"props":3595,"children":3598},{"href":3596,"rel":3597},"https:\u002F\u002Fwww.cockroachlabs.com\u002Fdocs\u002Fstable\u002Fsql-injection-prevention",[3527],[3599],{"type":50,"value":3600},"SQL Injection Prevention",{"type":45,"tag":98,"props":3602,"children":3603},{},[3604],{"type":45,"tag":70,"props":3605,"children":3608},{"href":3606,"rel":3607},"https:\u002F\u002Fwww.cockroachlabs.com\u002Fdocs\u002Fstable\u002Farchitecture\u002Ftransaction-layer",[3527],[3609],{"type":50,"value":3610},"Architecture: Transaction Layer",{"type":45,"tag":98,"props":3612,"children":3613},{},[3614],{"type":45,"tag":70,"props":3615,"children":3618},{"href":3616,"rel":3617},"https:\u002F\u002Fblog.cloudneutral.se\u002Fjpa-best-practices-explicit-and-implicit-transactions",[3527],[3619],{"type":50,"value":3620},"JPA Best Practices: Explicit and Implicit Transactions",{"type":45,"tag":98,"props":3622,"children":3623},{},[3624],{"type":45,"tag":70,"props":3625,"children":3628},{"href":3626,"rel":3627},"https:\u002F\u002Fwww.mindfulchase.com\u002Fexplore\u002Ftroubleshooting-tips\u002Fdatabases\u002Fdeep-dive-into-transaction-retry-failures-in-cockroachdb-root-causes-and-fixes.html",[3527],[3629],{"type":50,"value":3630},"Deep Dive into Transaction Retry Failures",{"type":45,"tag":98,"props":3632,"children":3633},{},[3634],{"type":45,"tag":70,"props":3635,"children":3638},{"href":3636,"rel":3637},"https:\u002F\u002Fandrewdeally.medium.com\u002Fcomparing-multi-statement-vs-single-statement-transactions-for-account-transfers-in-sql-09190b116e64",[3527],[3639],{"type":50,"value":3640},"Comparing Multi-Statement vs Single-Statement Transactions",{"type":45,"tag":98,"props":3642,"children":3643},{},[3644],{"type":45,"tag":70,"props":3645,"children":3648},{"href":3646,"rel":3647},"https:\u002F\u002Fandrewdeally.medium.com\u002Fset-based-operations-with-cockroachdb-c9f371992dc7",[3527],[3649],{"type":50,"value":3650},"Set-Based Operations with CockroachDB",{"type":45,"tag":98,"props":3652,"children":3653},{},[3654],{"type":45,"tag":70,"props":3655,"children":3658},{"href":3656,"rel":3657},"https:\u002F\u002Fblog.cloudneutral.se\u002Fcockroachdb-jdbc-driver-part-iii-bulk-rewrites",[3527],[3659],{"type":50,"value":3660},"Bulk Rewrites with the CockroachDB JDBC Driver",{"type":45,"tag":98,"props":3662,"children":3663},{},[3664],{"type":45,"tag":70,"props":3665,"children":3668},{"href":3666,"rel":3667},"https:\u002F\u002Fwww.cockroachlabs.com\u002Fblog\u002Fthe-hot-content-problem-metadata-storage-for-media-streaming\u002F",[3527],[3669],{"type":50,"value":3670},"What is a Database Hotspot?",{"type":45,"tag":98,"props":3672,"children":3673},{},[3674],{"type":45,"tag":70,"props":3675,"children":3678},{"href":3676,"rel":3677},"https:\u002F\u002Fgithub.com\u002Fcockroachdb\u002Fcockroach-transaction-demo",[3527],[3679],{"type":50,"value":3680},"CockroachDB Transaction Demo",{"type":45,"tag":98,"props":3682,"children":3683},{},[3684,3691],{"type":45,"tag":70,"props":3685,"children":3688},{"href":3686,"rel":3687},"https:\u002F\u002Fgithub.com\u002Fviragtripathi\u002Fcockroachdb-best-practices-demo",[3527],[3689],{"type":50,"value":3690},"CockroachDB Best Practices & Anti-Patterns Demo",{"type":50,"value":3692}," -- 10 runnable Java demos covering retries, batching, PK hotspots, guardrails, chunking, and multi-region",{"type":45,"tag":98,"props":3694,"children":3695},{},[3696,3703],{"type":45,"tag":70,"props":3697,"children":3700},{"href":3698,"rel":3699},"https:\u002F\u002Fgithub.com\u002Fviragtripathi\u002Fcockroachdb-jdbc-wrapper",[3527],[3701],{"type":50,"value":3702},"CockroachDB JDBC Wrapper",{"type":50,"value":3704}," -- automatic retry library for Java\u002FJDBC applications",{"type":45,"tag":3706,"props":3707,"children":3708},"style",{},[3709],{"type":50,"value":3710},"html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"items":3712,"total":3870},[3713,3732,3748,3763,3774,3784,3797,3807,3821,3836,3847,3860],{"slug":3714,"name":3714,"fn":3715,"description":3716,"org":3717,"tags":3718,"stars":3729,"repoUrl":3730,"updatedAt":3731},"collecting-cockroachdb-operator-escalation-packet","collect CockroachDB operator escalation packets","Collects a complete CockroachDB Operator escalation packet for TSC\u002FTSE or operator-team handoff, including Helm state, Kubernetes resources, logs, operation-specific evidence, pprof goroutine dumps, metrics, and a customer action timeline. Use when general diagnosis cannot resolve an operator-managed CockroachDB Helm issue or before restarting a stuck operator.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3719,3720,3723,3726],{"name":17,"slug":18,"type":15},{"name":3721,"slug":3722,"type":15},"Incident Response","incident-response",{"name":3724,"slug":3725,"type":15},"Kubernetes","kubernetes",{"name":3727,"slug":3728,"type":15},"Monitoring","monitoring",105,"https:\u002F\u002Fgithub.com\u002Fcockroachdb\u002Fhelm-charts","2026-07-12T07:57:25.288146",{"slug":3733,"name":3733,"fn":3734,"description":3735,"org":3736,"tags":3737,"stars":3729,"repoUrl":3730,"updatedAt":3747},"configuring-cockroachdb-helm-tls","configure TLS for CockroachDB Helm charts","Selects and validates TLS settings for CockroachDB Helm chart deployments, including self-signer, cert-manager, and external certificate modes. Use when a customer needs secure CockroachDB Helm values, certificate secret mapping, cert-manager integration, or TLS install troubleshooting before deploying the chart.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3738,3741,3744],{"name":3739,"slug":3740,"type":15},"Deployment","deployment",{"name":3742,"slug":3743,"type":15},"Encryption","encryption",{"name":3745,"slug":3746,"type":15},"Security","security","2026-07-12T07:56:37.675396",{"slug":3749,"name":3749,"fn":3750,"description":3751,"org":3752,"tags":3753,"stars":3729,"repoUrl":3730,"updatedAt":3762},"debugging-cockroachdb-operator-migrations","debug CockroachDB Operator migration scenarios","Debugs CockroachDB Operator migration scenarios, including Helm StatefulSet to v1beta1 CrdbNode migration and public operator v1alpha1 to v1beta1 migration. Use when migration labels, migration phases, source StatefulSet ownership, converted CRDs, PVC ownership, or post-migration reconciliation are unclear or stuck.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3754,3755,3758,3759],{"name":17,"slug":18,"type":15},{"name":3756,"slug":3757,"type":15},"Debugging","debugging",{"name":3724,"slug":3725,"type":15},{"name":3760,"slug":3761,"type":15},"Migration","migration","2026-07-12T07:56:48.360871",{"slug":3764,"name":3764,"fn":3765,"description":3766,"org":3767,"tags":3768,"stars":3729,"repoUrl":3730,"updatedAt":3773},"diagnosing-cockroachdb-helm-deployments","diagnose CockroachDB Helm chart deployments","Diagnoses failed or unhealthy CockroachDB Helm chart deployments by checking Helm release state, operator health, CrdbCluster and CrdbNode status, pod readiness, RBAC, webhooks, TLS, upgrades, scaling, PVCs, DNS, and multi-region assumptions. Use when Helm install or upgrade fails, pods are not Ready, or the operator is not reconciling.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3769,3770,3771,3772],{"name":17,"slug":18,"type":15},{"name":3756,"slug":3757,"type":15},{"name":3739,"slug":3740,"type":15},{"name":3724,"slug":3725,"type":15},"2026-07-12T07:57:24.018818",{"slug":3775,"name":3775,"fn":3776,"description":3777,"org":3778,"tags":3779,"stars":3729,"repoUrl":3730,"updatedAt":3783},"installing-cockroachdb-with-helm","install CockroachDB using Helm","Guides customer-facing installation of CockroachDB on Kubernetes using the CockroachDB split Helm charts and operator-managed v1beta1 resources. Use when installing CockroachDB with Helm, choosing between published and local split charts, verifying a new install, or helping an agent complete first-time Kubernetes onboarding.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3780,3781,3782],{"name":17,"slug":18,"type":15},{"name":3739,"slug":3740,"type":15},{"name":3724,"slug":3725,"type":15},"2026-07-12T07:56:45.777567",{"slug":3785,"name":3785,"fn":3786,"description":3787,"org":3788,"tags":3789,"stars":3729,"repoUrl":3730,"updatedAt":3796},"validating-cockroachdb-helm-multiregion","validate CockroachDB multi-region Helm deployments","Validates CockroachDB Helm chart values and Kubernetes prerequisites for operator-managed multi-region deployments. Use before adding a region, deploying CockroachDB across multiple Kubernetes clusters, checking region DNS domains, or confirming that all regions share certificate and networking assumptions.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3790,3791,3792,3793],{"name":17,"slug":18,"type":15},{"name":3739,"slug":3740,"type":15},{"name":3724,"slug":3725,"type":15},{"name":3794,"slug":3795,"type":15},"Operations","operations","2026-07-12T07:56:47.082609",{"slug":3798,"name":3798,"fn":3799,"description":3800,"org":3801,"tags":3802,"stars":22,"repoUrl":23,"updatedAt":3806},"analyzing-range-distribution","analyze CockroachDB range distribution and health","Analyzes CockroachDB range distribution across tables and indexes using SHOW RANGES to identify range count, size patterns, leaseholder placement, and replication health. Use when investigating hotspots, uneven data distribution, range fragmentation, or validating zone configuration effects without DB Console access.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3803,3804,3805],{"name":17,"slug":18,"type":15},{"name":3727,"slug":3728,"type":15},{"name":13,"slug":14,"type":15},"2026-07-12T07:57:18.753533",{"slug":3808,"name":3808,"fn":3809,"description":3810,"org":3811,"tags":3812,"stars":22,"repoUrl":23,"updatedAt":3820},"analyzing-schema-change-storage-risk","analyze schema change storage requirements","Estimates storage requirements for CockroachDB online schema change backfills using SHOW RANGES WITH DETAILS, KEYS, INDEXES. Use before CREATE INDEX, ADD COLUMN with INDEX\u002FUNIQUE, ALTER PRIMARY KEY, CREATE MATERIALIZED VIEW, CREATE TABLE AS, REFRESH, or SET LOCALITY on tables with large per-index footprints, to avoid mid-backfill disk exhaustion.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3813,3816,3817,3818],{"name":3814,"slug":3815,"type":15},"Data Modeling","data-modeling",{"name":17,"slug":18,"type":15},{"name":13,"slug":14,"type":15},{"name":3819,"slug":459,"type":15},"SQL","2026-07-12T07:57:22.763788",{"slug":3822,"name":3822,"fn":3823,"description":3824,"org":3825,"tags":3826,"stars":22,"repoUrl":23,"updatedAt":3835},"auditing-cis-benchmark","audit CockroachDB clusters against CIS benchmarks","Audits a self-hosted CockroachDB cluster against the CIS CockroachDB Benchmark v1.0.0 Level 1 controls. Supports two audit depths — quick automated scans and full CIS audit procedures. Produces a structured PASS\u002FFAIL\u002FMANUAL report covering installation, system hardening, logging, user access, data protection, and CockroachDB settings. Use when preparing for CIS compliance assessments, hardening self-hosted deployments, or validating security posture against industry benchmarks.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3827,3830,3833,3834],{"name":3828,"slug":3829,"type":15},"Audit","audit",{"name":3831,"slug":3832,"type":15},"Compliance","compliance",{"name":17,"slug":18,"type":15},{"name":3745,"slug":3746,"type":15},"2026-07-18T05:48:00.862384",{"slug":3837,"name":3837,"fn":3838,"description":3839,"org":3840,"tags":3841,"stars":22,"repoUrl":23,"updatedAt":3846},"auditing-cloud-cluster-security","audit CockroachDB cluster security posture","Audits the security posture of a CockroachDB cluster (Cloud or self-hosted) across network, authentication, authorization, encryption, audit logging, and backup dimensions. Use when assessing cluster security readiness, preparing for compliance reviews, or investigating security configuration gaps.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3842,3843,3844,3845],{"name":3828,"slug":3829,"type":15},{"name":17,"slug":18,"type":15},{"name":3794,"slug":3795,"type":15},{"name":3745,"slug":3746,"type":15},"2026-07-12T07:57:01.506735",{"slug":3848,"name":3848,"fn":3849,"description":3850,"org":3851,"tags":3852,"stars":22,"repoUrl":23,"updatedAt":3859},"auditing-table-statistics","audit optimizer table statistics","Audits optimizer table statistics for staleness, missing coverage, and data quality issues using SHOW STATISTICS. Use when diagnosing poor query performance, unexpected plan changes, or after bulk data changes to identify stale statistics requiring refresh via CREATE STATISTICS.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3853,3854,3857,3858],{"name":3828,"slug":3829,"type":15},{"name":3855,"slug":3856,"type":15},"Data Analysis","data-analysis",{"name":17,"slug":18,"type":15},{"name":13,"slug":14,"type":15},"2026-07-12T07:57:16.190081",{"slug":83,"name":83,"fn":3861,"description":3862,"org":3863,"tags":3864,"stars":22,"repoUrl":23,"updatedAt":3869},"benchmark CockroachDB transaction patterns","Guides benchmarking and comparing explicit multi-statement transactions versus single-statement CTE transactions in CockroachDB, with fair test methodology, contention analysis, and performance interpretation. Use when comparing transaction formulations, benchmarking CockroachDB workloads under contention, investigating retry pressure, or deciding whether to rewrite multi-step application flows into single SQL statements.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3865,3866,3867,3868],{"name":17,"slug":18,"type":15},{"name":20,"slug":21,"type":15},{"name":13,"slug":14,"type":15},{"name":3819,"slug":459,"type":15},"2026-07-12T07:57:26.543278",40,{"items":3872,"total":3923},[3873,3879,3886,3893,3900,3907,3914],{"slug":3798,"name":3798,"fn":3799,"description":3800,"org":3874,"tags":3875,"stars":22,"repoUrl":23,"updatedAt":3806},{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3876,3877,3878],{"name":17,"slug":18,"type":15},{"name":3727,"slug":3728,"type":15},{"name":13,"slug":14,"type":15},{"slug":3808,"name":3808,"fn":3809,"description":3810,"org":3880,"tags":3881,"stars":22,"repoUrl":23,"updatedAt":3820},{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3882,3883,3884,3885],{"name":3814,"slug":3815,"type":15},{"name":17,"slug":18,"type":15},{"name":13,"slug":14,"type":15},{"name":3819,"slug":459,"type":15},{"slug":3822,"name":3822,"fn":3823,"description":3824,"org":3887,"tags":3888,"stars":22,"repoUrl":23,"updatedAt":3835},{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3889,3890,3891,3892],{"name":3828,"slug":3829,"type":15},{"name":3831,"slug":3832,"type":15},{"name":17,"slug":18,"type":15},{"name":3745,"slug":3746,"type":15},{"slug":3837,"name":3837,"fn":3838,"description":3839,"org":3894,"tags":3895,"stars":22,"repoUrl":23,"updatedAt":3846},{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3896,3897,3898,3899],{"name":3828,"slug":3829,"type":15},{"name":17,"slug":18,"type":15},{"name":3794,"slug":3795,"type":15},{"name":3745,"slug":3746,"type":15},{"slug":3848,"name":3848,"fn":3849,"description":3850,"org":3901,"tags":3902,"stars":22,"repoUrl":23,"updatedAt":3859},{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3903,3904,3905,3906],{"name":3828,"slug":3829,"type":15},{"name":3855,"slug":3856,"type":15},{"name":17,"slug":18,"type":15},{"name":13,"slug":14,"type":15},{"slug":83,"name":83,"fn":3861,"description":3862,"org":3908,"tags":3909,"stars":22,"repoUrl":23,"updatedAt":3869},{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3910,3911,3912,3913],{"name":17,"slug":18,"type":15},{"name":20,"slug":21,"type":15},{"name":13,"slug":14,"type":15},{"name":3819,"slug":459,"type":15},{"slug":75,"name":75,"fn":3915,"description":3916,"org":3917,"tags":3918,"stars":22,"repoUrl":23,"updatedAt":3922},"write and optimize CockroachDB SQL","Use when writing, generating, or optimizing SQL for CockroachDB, designing CockroachDB schemas, or when the user asks about CockroachDB-specific SQL patterns, type mappings, and distributed database best practices. Also use when encountering CockroachDB anti-patterns like missing primary keys, sequential ID hotspots, or incorrect type usage.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3919,3920,3921],{"name":17,"slug":18,"type":15},{"name":13,"slug":14,"type":15},{"name":3819,"slug":459,"type":15},"2026-07-25T05:31:22.562808",34]