DOCSP-51036: Transactions #40

norareidy · 2025-07-10T20:25:43Z

Pull Request Info

PR Reviewing Guidelines

JIRA - https://jira.mongodb.org/browse/DOCSP-51036

Staging Links

interact-data/transactions

interact-data

interact-data/raw-queries

limitations-upcoming

Self-Review Checklist

Is this free of any warnings or errors in the RST?
Did you run a spell-check?
Did you run a grammar-check?
Are all the links working?
Are the facets and meta keywords accurate?

netlify · 2025-07-10T20:25:49Z

✅ Deploy Preview for docs-django ready!

Name	Link
🔨 Latest commit	`0d93cbb`
🔍 Latest deploy log	https://app.netlify.com/projects/docs-django/deploys/68755ad56f5afa0008e25cdc
😎 Deploy Preview	https://deploy-preview-40--docs-django.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

docs-builder-bot · 2025-07-10T20:26:28Z

🔄 Deploy Preview for docs-django processing

Item	Details
🔨 Latest Commit	d1c6872804d0f00392dcea805b2c3d85cb81a236
😎 Deploy Preview	https://deploy-preview-40--docs-django.netlify.app
🔍 Build Logs	View Logs

mballard-mdb · 2025-07-11T20:38:29Z

source/interact-data/transactions.txt

+**transactions**. Transactions allow you to run a series of operations
+that change data only if the entire transaction is committed.
+If any operation in the transaction does not succeed, {+django-odm+} stops the
+transaction and discards all data changes before they ever become


Suggested change

transaction and discards all data changes before they ever become

transaction and discards all changes to the data before they ever become

Consider this for clarity

mballard-mdb

lgtm with a couple suggestions! great work!

mballard-mdb · 2025-07-11T20:41:03Z

source/interact-data/transactions.txt

+changes are committed MongoDB.
+
+The following example calls the ``create()`` method within a transaction,
+inserting a document into the ``sample_mflix.movies`` collection if the


Suggested change

inserting a document into the ``sample_mflix.movies`` collection if the

which inserts a document into the ``sample_mflix.movies`` collection if the

mballard-mdb · 2025-07-11T20:42:18Z

source/interact-data/transactions.txt

+Run Callbacks After a Transaction
+---------------------------------
+
+If you want to perform certain actions only if a transaction successfully


Suggested change

If you want to perform certain actions only if a transaction successfully

To perform certain actions only if a transaction successfully

mballard-mdb · 2025-07-11T20:42:26Z

source/interact-data/transactions.txt

+---------------------------------
+
+If you want to perform certain actions only if a transaction successfully
+completes, you can use the ``transaction.on_commit()`` method. This method allows you to


Suggested change

completes, you can use the ``transaction.on_commit()`` method. This method allows you to

completes, use the ``transaction.on_commit()`` method. This method allows you to

on_commit() is a function, not a method.

mballard-mdb · 2025-07-11T20:43:50Z

source/interact-data/transactions.txt

+If you want to perform certain actions only if a transaction successfully
+completes, you can use the ``transaction.on_commit()`` method. This method allows you to
+register callbacks that run after a transaction is committed to the 
+database. Pass a function, or any callable object, as an argument to


Suggested change

database. Pass a function, or any callable object, as an argument to

database. To use this method, pass a function, or any callable object, as an argument to

I think this is what this says

I'll keep as is to avoid using too many commas, since I think the "to use..." is implied

timgraham · 2025-07-12T21:33:46Z

source/includes/interact-data/transactions.py

+)
+try:
+    with transaction.atomic():
+        movie.update(title="Jurassic Park I")


models don't have an update() method

timgraham · 2025-07-12T21:34:44Z

source/includes/interact-data/transactions.py

+# start-handle-errors
+movie = Movie.objects.get(
+    title="Jurassic Park",
+    released=timezone.make_aware(datetime(1993, 6, 11))


It's probably enough to retrieve a move by name (omit released=...).

timgraham · 2025-07-12T21:36:01Z

source/includes/interact-data/transactions.py

+            runtime=140,
+            genres=["Horror", "Comedy"]
+        )
+


chop the blank line?

timgraham · 2025-07-12T21:38:24Z

source/limitations-upcoming.txt

@@ -248,8 +250,17 @@ Database and Collection Support
     - ✓

   * - Transactions
-     - *Unsupported*.
-     - ✓
+     - *Partially Supported*. You can use {+framework+}'s transactions API with the


It's not an issue for this PR to tackle, but I think it's a strange choice of words to call it "Partial support" when there are any limitations. To me, "partial support" makes me think "this feature is partially completed and more work will be done later".

Hm I see what you mean, is "Supported with Limitations" more accurate?

Yes, but I think it would be enough to say, "✓ You use... with the following limitations:" rather than place a double emphasis on limitations.

Yeah I like ✓ with limitations noted. Partial support has more of a "we may get further on this soon" which I don't think is the case with transactions support.

timgraham · 2025-07-12T21:40:51Z

source/limitations-upcoming.txt

+       - Migration operations do not run inside a transaction, which differs from {+framework+}'s
+         default migration behavior.


which differs from {+framework+}'s default migration behavior.

This isn't quite accurate. It depends on the database. SQLite & PostgreSQL run operations inside a transaction, but MySQL and Oracle don't. (The relevant feature flag is DatabaseFeatures.can_rollback_ddl.)

Removed this part

timgraham · 2025-07-12T21:43:18Z

source/interact-data/transactions.txt

+
+To handle exceptions that occur during a transaction, add error handling
+logic around your atomic code block. If you include error handing logic inside
+the atomic block, {+framework+} might ignore these errors, resulting in unexpected


I think the meaning of "{+framework+} might ignore these errors," is probably unclear.

I added some more detail here

timgraham · 2025-07-12T21:46:37Z

source/interact-data/transactions.txt

+the atomic block, {+framework+} might ignore these errors, resulting in unexpected
+behavior.
+
+If a transaction does not succeed, your application does not revert any changes made


"your application" -> Django

timgraham · 2025-07-12T21:48:32Z

source/interact-data/transactions.txt

+---------------------------------
+
+If you want to perform certain actions only if a transaction successfully
+completes, you can use the ``transaction.on_commit()`` method. This method allows you to


on_commit() is a function, not a method.

timgraham · 2025-07-12T21:50:54Z

source/includes/interact-data/transactions.py

+    with transaction.atomic():
+        movie.update(title="Jurassic Park I")
+except DatabaseError:
+    movie.update(title="Jurassic Park")


You might copy from Django's example and use the value of movie.title in a line that follows (like if obj.active: in Django's example) to make it clear why it could be important to revert the value.

timgraham · 2025-07-14T18:09:12Z

source/interact-data/transactions.txt

+   {+django-odm+}'s support for the {+framework+} transaction API
+   has several limitations. To view a list of limitations, see
+   :ref:`Database and Collection Support <django-feature-compat-db-coll>`
+   in the Django and MongoDB Feature Compatibility guide.


Suggested change

in the Django and MongoDB Feature Compatibility guide.

in the {+framework+} and MongoDB Feature Compatibility guide.

timgraham · 2025-07-14T18:09:32Z

source/interact-data/transactions.txt

+{+framework+} uses errors to determine whether to commit or roll
+back a transaction, this can cause unexpected behavior.
+
+If a transaction does not succeed, Django does not revert any changes made


Suggested change

If a transaction does not succeed, Django does not revert any changes made

If a transaction does not succeed, {+framework+} does not revert any changes made

timgraham · 2025-07-14T18:18:39Z

source/limitations-upcoming.txt

@@ -248,8 +250,17 @@ Database and Collection Support
     - ✓

   * - Transactions
-     - *Unsupported*.
-     - ✓
+     - *Partially Supported*. You can use {+framework+}'s transactions API with the


Yes, but I think it would be enough to say, "✓ You use... with the following limitations:" rather than place a double emphasis on limitations.

aclark4life

LGTM!

norareidy added 2 commits July 10, 2025 10:55

DOCSP-51036: Transactions

073c271

work in progress

07a82ac

norareidy added 8 commits July 11, 2025 10:57

edits

f1560c9

atlas search idx note

005217f

edits

9652563

add limitation

48f877e

edit

fab0362

add example

7b36ded

wording

4d0fdb3

fix

90d24a8

mballard-mdb reviewed Jul 11, 2025

View reviewed changes

mballard-mdb approved these changes Jul 11, 2025

View reviewed changes

timgraham reviewed Jul 12, 2025

View reviewed changes

feedback

72b93db

norareidy requested a review from aclark4life July 14, 2025 15:37

edit

d1c6872

timgraham approved these changes Jul 14, 2025

View reviewed changes

aclark4life approved these changes Jul 14, 2025

View reviewed changes

feedback 2

0d93cbb

norareidy merged commit 5fcd185 into mongodb:master Jul 14, 2025
5 checks passed

norareidy deleted the DOCSP-51036-transactions branch July 14, 2025 19:37

	transaction and discards all data changes before they ever become
	transaction and discards all changes to the data before they ever become

	inserting a document into the ``sample_mflix.movies`` collection if the
	which inserts a document into the ``sample_mflix.movies`` collection if the

	If you want to perform certain actions only if a transaction successfully
	To perform certain actions only if a transaction successfully

	completes, you can use the ``transaction.on_commit()`` method. This method allows you to
	completes, use the ``transaction.on_commit()`` method. This method allows you to

	database. Pass a function, or any callable object, as an argument to
	database. To use this method, pass a function, or any callable object, as an argument to

		- Migration operations do not run inside a transaction, which differs from {+framework+}'s
		default migration behavior.

	in the Django and MongoDB Feature Compatibility guide.
	in the {+framework+} and MongoDB Feature Compatibility guide.

	If a transaction does not succeed, Django does not revert any changes made
	If a transaction does not succeed, {+framework+} does not revert any changes made

DOCSP-51036: Transactions #40

DOCSP-51036: Transactions #40

Uh oh!

Conversation

norareidy commented Jul 10, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Info

Staging Links

Self-Review Checklist

Uh oh!

netlify bot commented Jul 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for docs-django ready!

Uh oh!

docs-builder-bot commented Jul 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔄 Deploy Preview for docs-django processing

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mballard-mdb left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aclark4life left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

norareidy commented Jul 10, 2025 •

edited by github-actions bot

Loading

netlify bot commented Jul 10, 2025 •

edited

Loading

docs-builder-bot commented Jul 10, 2025 •

edited

Loading