Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

[1.6.x] Fixed #12579 -- Noted QuerySet.get_or_create() depends on dat…

…abase unique constraints.

Thanks timmolendijk, jdunck, vijay_shanker, and loic84.

Backport of 428de2e from master.
  • Loading branch information...
commit 9687e387d80bba33f82593915bb1351ae73e54f6 1 parent 25b9939
Tim Graham authored July 03, 2013

Showing 1 changed file with 21 additions and 10 deletions. Show diff stats Hide diff stats

  1. 31  docs/ref/models/querysets.txt
31  docs/ref/models/querysets.txt
@@ -1350,7 +1350,7 @@ get_or_create
1350 1350
 
1351 1351
 .. method:: get_or_create(**kwargs)
1352 1352
 
1353  
-A convenience method for looking up an object with the given kwargs (may be
  1353
+A convenience method for looking up an object with the given ``kwargs`` (may be
1354 1354
 empty if your model has defaults for all fields), creating one if necessary.
1355 1355
 
1356 1356
 .. versionchanged:: 1.6
@@ -1361,8 +1361,7 @@ Returns a tuple of ``(object, created)``, where ``object`` is the retrieved or
1361 1361
 created object and ``created`` is a boolean specifying whether a new object was
1362 1362
 created.
1363 1363
 
1364  
-This is meant as a shortcut to boilerplatish code and is mostly useful for
1365  
-data-import scripts. For example::
  1364
+This is meant as a shortcut to boilerplatish code. For example::
1366 1365
 
1367 1366
     try:
1368 1367
         obj = Person.objects.get(first_name='John', last_name='Lennon')
@@ -1410,13 +1409,25 @@ when you're using manually specified primary keys. If an object needs to be
1410 1409
 created and the key already exists in the database, an
1411 1410
 :exc:`~django.db.IntegrityError` will be raised.
1412 1411
 
1413  
-Finally, a word on using ``get_or_create()`` in Django views. As mentioned
1414  
-earlier, ``get_or_create()`` is mostly useful in scripts that need to parse
1415  
-data and create new records if existing ones aren't available. But if you need
1416  
-to use ``get_or_create()`` in a view, please make sure to use it only in
1417  
-``POST`` requests unless you have a good reason not to. ``GET`` requests
1418  
-shouldn't have any effect on data; use ``POST`` whenever a request to a page
1419  
-has a side effect on your data. For more, see `Safe methods`_ in the HTTP spec.
  1412
+This method is atomic assuming correct usage, correct database configuration,
  1413
+and correct behavior of the underlying database. However, if uniqueness is not
  1414
+enforced at the database level for the ``kwargs`` used in a ``get_or_create``
  1415
+call (see :attr:`~django.db.models.Field.unique` or
  1416
+:attr:`~django.db.models.Options.unique_together`), this method is prone to a
  1417
+race-condition which can result in multiple rows with the same parameters being
  1418
+inserted simultaneously.
  1419
+
  1420
+If you are using MySQL, be sure to use the ``READ COMMITTED`` isolation level
  1421
+rather than ``REPEATABLE READ`` (the default), otherwise you may see cases
  1422
+where ``get_or_create`` will raise an :exc:`~django.db.IntegrityError` but the
  1423
+object won't appear in a subsequent :meth:`~django.db.models.query.QuerySet.get`
  1424
+call.
  1425
+
  1426
+Finally, a word on using ``get_or_create()`` in Django views: please make sure
  1427
+to use it only in ``POST`` requests unless you have a good reason not to
  1428
+``GET`` requests shouldn't have any effect on data; use ``POST`` whenever a
  1429
+request to a page as a side effect on your data. For more, see `Safe methods`_
  1430
+in the HTTP spec.
1420 1431
 
1421 1432
 .. _Safe methods: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1
1422 1433
 

0 notes on commit 9687e38

Please sign in to comment.
Something went wrong with that request. Please try again.