Add transactions API docs #2459
Conversation
WalkthroughAdded a "Transactions" navigation item to the databases docs layout (isNewUntil('31 Oct 2025')). Added a new Transactions guide page describing createTransaction, staging operations (including createOperations batch), committing and rolling back transactions, conflict handling, scope/limitations, and multi-language examples. Inserted "Use transactions" sections into atomic numeric operations, bulk operations, and rows docs to document transactionId support with multi-language code samples. All changes are documentation-only; no exported/public APIs or function signatures were modified. Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
src/routes/docs/products/databases/atomic-numeric-operations/+page.markdoc (1)
575-600: Consider adding a link to the Transactions guide for consistency.The "Use transactions" section correctly documents
transactionIdsupport with clear examples. However, unlike the similar sections in the rows and bulk-operations docs, this section doesn't include a link to the Transactions guide. Consider adding a reference like "Learn more in the Transactions guide." for consistency and to help users understand the complete workflow.Apply this diff to add the link:
# Use transactions {% #use-transactions %} Atomic numeric operations accept `transactionId`. When provided, increments/decrements are staged and applied on commit. +Learn more in the [Transactions guide](/docs/products/databases/transactions). {% multicode %}
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
src/routes/changelog/(entries)/2025-09-29.markdoc(1 hunks)src/routes/docs/products/databases/+layout.svelte(1 hunks)src/routes/docs/products/databases/atomic-numeric-operations/+page.markdoc(1 hunks)src/routes/docs/products/databases/bulk-operations/+page.markdoc(1 hunks)src/routes/docs/products/databases/rows/+page.markdoc(1 hunks)src/routes/docs/products/databases/transactions/+page.markdoc(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: build
- GitHub Check: tests
🔇 Additional comments (4)
src/routes/docs/products/databases/rows/+page.markdoc (1)
724-758: LGTM! Clear documentation of transaction support.The "Use transactions" section is well-placed and provides clear examples showing how to stage row operations within a transaction. The examples cover create, update, and delete operations, and the link to the full Transactions guide helps users understand the complete workflow.
src/routes/docs/products/databases/bulk-operations/+page.markdoc (1)
267-287: LGTM! Consistent transaction documentation.The "Use transactions" section correctly documents that bulk operations support
transactionIdand provides appropriate server-side SDK examples (Node.js and Python). This aligns well with the pattern established in other operation docs.src/routes/docs/products/databases/+layout.svelte (1)
80-84: LGTM! Navigation entry properly configured.The Transactions navigation item is appropriately placed in the Journeys section and marked as new with a reasonable expiration date.
src/routes/changelog/(entries)/2025-09-29.markdoc (1)
1-19: LGTM! Clear and comprehensive changelog entry.The changelog entry effectively communicates the new Transactions feature, covering the key workflow (create, stage, commit/rollback), ordering guarantees, conflict detection, and the relevant API methods. The link to the Transactions guide helps users learn more.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
src/routes/docs/products/databases/rows/+page.markdoc (1)
779-779: Consider using consistent variable names for discarded results.The use of
_2for the second discarded result is unconventional. In Swift and Kotlin, when discarding multiple results, either use_for all (with repeatedlet _ = ...orval _ = ...statements) or use descriptive names.Apply this pattern for Swift:
// Update row inside a transaction -let _2 = try await tablesDB.updateRow( +let _ = try await tablesDB.updateRow(Apply this pattern for Kotlin:
// Update row inside a transaction -val _2 = tablesDB.updateRow( +val _ = tablesDB.updateRow(Also applies to: 798-798, 931-931, 940-940
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
src/routes/docs/products/databases/bulk-operations/+page.markdoc(1 hunks)src/routes/docs/products/databases/rows/+page.markdoc(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- src/routes/docs/products/databases/bulk-operations/+page.markdoc
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: tests
- GitHub Check: build
🔇 Additional comments (3)
src/routes/docs/products/databases/rows/+page.markdoc (3)
725-727: LGTM!The section header and introduction clearly explain the transactionId support for row operations and appropriately link to the comprehensive Transactions guide.
729-865: LGTM! Comprehensive client SDK examples.The client SDK examples effectively demonstrate transactionId usage across multiple languages with consistent patterns matching the rest of the documentation.
866-964: LGTM! Comprehensive server SDK examples.The server SDK examples effectively demonstrate transactionId usage with deleteRow operations, providing good variety alongside the client SDK create/update examples. All examples follow language-specific conventions appropriately.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
src/routes/docs/products/databases/atomic-numeric-operations/+page.markdoc (2)
575-577: Enhance the transaction explanation and add cross-reference.The explanation is too brief for users unfamiliar with the transaction feature. Consider:
- Adding a link to the main transactions documentation
- Explaining the full workflow (create → stage with transactionId → commit/rollback)
- Noting what happens on rollback (staged changes are discarded)
- Clarifying when to use transactions vs. standalone atomic operations
Example enhancement:
# Use transactions {% #use-transactions %} -Atomic numeric operations accept `transactionId`. When provided, increments/decrements are staged and applied on commit. +Atomic numeric operations accept an optional `transactionId` parameter. When provided, the increment or decrement is staged within the transaction and only applied when you commit the transaction. If the transaction is rolled back, the staged change is discarded. This allows you to coordinate atomic operations with other database changes. + +Learn more about [database transactions](/docs/products/databases/transactions).
579-756: Add context for the complete transaction workflow.The code examples show how to pass
transactionIdtoincrementRowColumn, but they don't demonstrate where the transaction ID comes from or how to commit/rollback. Users may be confused about the full workflow.Consider one of these approaches:
- Add a brief note above the examples directing users to the Transactions guide for the complete workflow (create → stage operations → commit/rollback)
- Show a minimal complete example with createTransaction, incrementRowColumn with transactionId, and updateTransaction
Example addition before the multicode block:
First, create a transaction and obtain its ID. Then pass the ID to your atomic operations. See the [Transactions guide](/docs/products/databases/transactions) for the complete workflow.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
src/routes/docs/products/databases/atomic-numeric-operations/+page.markdoc(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: build
- GitHub Check: tests
|
@coderabbitai full review |
✅ Actions performedFull review triggered. |
src/routes/docs/products/databases/atomic-numeric-operations/+page.markdoc
Outdated
Show resolved
Hide resolved
src/routes/docs/products/databases/atomic-numeric-operations/+page.markdoc
Outdated
Show resolved
Hide resolved
src/routes/docs/products/databases/atomic-numeric-operations/+page.markdoc
Outdated
Show resolved
Hide resolved
src/routes/docs/products/databases/bulk-operations/+page.markdoc
Outdated
Show resolved
Hide resolved
src/routes/docs/products/databases/bulk-operations/+page.markdoc
Outdated
Show resolved
Hide resolved
| ### Bulk update {% #bulk-update %} | ||
| Pass queries and the data to apply. | ||
| ```json | ||
| { "queries": ["equal(\"status\", [\"draft\"])"], "data": { "status": "published" } } |
There was a problem hiding this comment.
Queries should be JSON format {"method": "equal", "attribute": "status", "values": ["draft"]}
- Remove unnecessary let/val assignments in Swift/Kotlin examples - Fix Node.js to use object params for transactionId - Change nested data field to top-level columns in bulk operations - Update Java examples to use Map.of() instead of HashMap - Standardize example methods across all languages - Fix queries to use JSON object format - Remove table name - transactionLogs - Add multi-line params for commit/rollback examples
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
src/routes/docs/products/databases/transactions/+page.markdoc(1 hunks)
🧰 Additional context used
🧠 Learnings (2)
📚 Learning: 2025-09-05T19:35:53.943Z
Learnt from: ebenezerdon
PR: appwrite/website#2372
File: src/routes/docs/tutorials/react/step-6/+page.markdoc:70-75
Timestamp: 2025-09-05T19:35:53.943Z
Learning: In React tutorial files, the correct Appwrite database instance to import is `tablesDB` from "../appwrite", not `databases`. The import statement should be `import { tablesDB } from "../appwrite"` to match the usage throughout the React tutorial code.
Applied to files:
src/routes/docs/products/databases/transactions/+page.markdoc
📚 Learning: 2025-09-05T19:35:59.449Z
Learnt from: ebenezerdon
PR: appwrite/website#2372
File: src/routes/docs/tutorials/react-native/step-6/+page.markdoc:67-73
Timestamp: 2025-09-05T19:35:59.449Z
Learning: In React Native tutorials, the lib/appwrite.js file exports `tablesDB` (not `databases`), so imports should use `import { tablesDB } from "../lib/appwrite"` to match the export pattern established in step-3.
Applied to files:
src/routes/docs/products/databases/transactions/+page.markdoc
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: build
- GitHub Check: tests
|
|
||
| ## Stage single operations {% #stage-single-operations %} | ||
|
|
||
| Create, update, upsert, delete, and atomic numeric operations accept `transactionId`. |
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
src/routes/docs/products/databases/transactions/+page.markdoc (1)
438-474: Standardize operation examples to match other languages.The Node.js example uses
updateRow+deleteRowwhile the Python example usesupsertRow+decrementRowColumn. These should usecreateRow+incrementRowColumnto match the other 12 languages for consistency, as previously requested.Apply this pattern for Node.js (lines 438-455):
-// Update inside a transaction -await tablesDB.updateRow({ +// Create inside a transaction +await tablesDB.createRow({ databaseId: '<DATABASE_ID>', tableId: '<TABLE_ID>', rowId: '<ROW_ID>', - data: { plan: 'pro' }, + data: { name: 'Walter' }, transactionId: tx.$id }); -// Delete inside a transaction -await tablesDB.deleteRow({ +// Increment inside a transaction +await tablesDB.incrementRowColumn({ databaseId: '<DATABASE_ID>', tableId: '<TABLE_ID>', rowId: '<ROW_ID>', + column: 'credits', + value: 1, transactionId: tx.$id });Apply this pattern for Python (lines 456-474):
-# Upsert inside a transaction -tablesDB.upsert_row( +# Create inside a transaction +tablesDB.create_row( database_id = '<DATABASE_ID>', table_id = '<TABLE_ID>', row_id = '<ROW_ID>', data = { 'name': 'Walter' }, transaction_id = tx['$id'] ) -# Decrement inside a transaction -tablesDB.decrement_row_column( +# Increment inside a transaction +tablesDB.increment_row_column( database_id = '<DATABASE_ID>', table_id = '<TABLE_ID>', row_id = '<ROW_ID>', column = 'credits', value = 1, transaction_id = tx['$id'] )
🧹 Nitpick comments (3)
src/routes/docs/products/databases/transactions/+page.markdoc (3)
21-29: Consider moving the Limits section after the workflow explanation.The limits are presented before readers understand what operations they're limiting. Moving this section after "How transactions work" or "Stage operations" would improve the documentation flow.
602-612: Clarify the pipe notation in the JSON schema.The schema uses
"tableId|collectionId"and"rowId|documentId"which might be unclear. Add a brief note explaining these represent alternative field names (choose one).Consider adding a note before the schema:
+{% info title="Schema notation" %} +Field names with pipes (e.g., `tableId|collectionId`) indicate alternatives—use one or the other depending on your API version. +{% /info %} + ```json [ {
614-614: Simplify the section heading.The heading "Provide data for each action (createOperations)" has an awkward suffix. Simplify to improve readability.
-### Provide data for each action (createOperations) {% #provide-data-for-each-action %} +### Data format for each action {% #provide-data-for-each-action %}
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
src/routes/docs/products/databases/transactions/+page.markdoc(1 hunks)
🧰 Additional context used
🧠 Learnings (2)
📚 Learning: 2025-09-05T19:35:53.943Z
Learnt from: ebenezerdon
PR: appwrite/website#2372
File: src/routes/docs/tutorials/react/step-6/+page.markdoc:70-75
Timestamp: 2025-09-05T19:35:53.943Z
Learning: In React tutorial files, the correct Appwrite database instance to import is `tablesDB` from "../appwrite", not `databases`. The import statement should be `import { tablesDB } from "../appwrite"` to match the usage throughout the React tutorial code.
Applied to files:
src/routes/docs/products/databases/transactions/+page.markdoc
📚 Learning: 2025-09-05T19:35:59.449Z
Learnt from: ebenezerdon
PR: appwrite/website#2372
File: src/routes/docs/tutorials/react-native/step-6/+page.markdoc:67-73
Timestamp: 2025-09-05T19:35:59.449Z
Learning: In React Native tutorials, the lib/appwrite.js file exports `tablesDB` (not `databases`), so imports should use `import { tablesDB } from "../lib/appwrite"` to match the export pattern established in step-3.
Applied to files:
src/routes/docs/products/databases/transactions/+page.markdoc
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: tests
- GitHub Check: build
🔇 Additional comments (5)
src/routes/docs/products/databases/transactions/+page.markdoc (5)
1-19: LGTM! Clear introduction and scope.The introduction effectively explains the transaction concept and workflow. The scope limitation regarding schema operations is appropriately highlighted.
31-289: LGTM! Consistent multi-language examples.The transaction creation examples are consistent across all languages and follow each language's conventions correctly.
646-956: LGTM! Consistent createOperations examples across all languages.All language examples consistently demonstrate staging two operations (create + increment), following the standardization requested in previous reviews.
958-1137: LGTM! Complete commit and rollback examples.The transaction finalization examples consistently show both commit and rollback workflows across all supported languages.
1139-1149: LGTM! Clear conflict handling guidance.The conflict explanation and best practices provide clear guidance for transaction management. The recommendation to keep transactions short-lived and use
createOperationsfor batch staging is sound advice.
3 participants
What does this PR do?
Adds transaction api docs
Summary by CodeRabbit