Documented all features

Author: Photonios

README.rst

@@ -68,81 +68,10 @@ Installation
             }
         }
 
-Usage
------
-
-* ``psqlextra.models.PostgresModel``
-    Inheriting your models from this gives you access to the ``PostgresManager``, which exposes:
-
-    * ``upsert``:
-
-        * Native, single query, concurrency safe upsert:
-
-            .. code-block:: python
-
-                from psqlextra.models import PostgresModel
-
-                class MyModel(PostgresModel):
-                    title = models.CharField(unique=True)
-
-                pk1 = MyModel.objects.upsert(title='beer')
-                pk2 = MyModel.objects.upsert(title='beer')
-
-                assert pk1 == pk2
-
-    * ``upsert_and_get``:
-
-        * Native, single query, concurrency safe upsert + select:
-
-            .. code-block:: python
-
-                from psqlextra.models import PostgresModel
-
-                class MyModel(PostgresModel):
-                    title = models.CharField(unique=True)
-
-                pk1 = MyModel.objects.upsert(title='beer')
-                obj2 = MyModel.objects.upsert_and_get(title='beer')
-
-                assert pk1 == obj2.pk
-
-    Upserts use PostgreSQL's ``ON CONFLICT`` clause. This instruct PostgreSQL to overwrite
-    an existing row when it encounters a conflict (duplicate key). This happens in a single
-    query. PostgreSQL guarentees concurrency safety for ``ON CONFLICT``.
-
-* ``psqlextra.fields.HStoreField``
-    Inherits from Django's ``HStoreField`` but adds support for constraints:
-
-    * ``uniqueness``:
-
-        * Enforce uniqueness for one or more key:
-
-            .. code-block:: python
-
-                from psqlextra.fields import HStoreField
-
-                class MyModel(models.Model):
-                    title = HStoreField(uniqueness=['en', 'ro'])
-
-        * Enforce uniqueness for one ore more keys **together** (similar to Django's ``unique_together``):
-
-            .. code-block:: python
-
-                from psqlextra.fields import HStoreField
-
-                class MyModel(models.Model):
-                    title = HStoreField(uniqueness=[('en', 'ro')])
-
-    * ``required``:
-
-        * Require one or more keys to be set:
-
-            .. code-block:: python
-
-                from psqlextra.fields import HStoreField
+Documentation
+-------------
 
-                class MyModel(models.Model):
-                    title = HStoreField(required=['h1', 'h2'])
+Browse the documentation at: [http://django-postgres-extra.readthedocs.io/](http://django-postgres-extra.readthedocs.io/).
 
 
 FAQ - Frequently asked questions

docs/features.md

@@ -1,10 +1,7 @@
-# Overview
-
 # HStoreField
 `psqlextra.fields.HStoreField` is based on Django's [HStoreField](https://docs.djangoproject.com/en/1.10/ref/contrib/postgres/fields/#hstorefield) and therefor supports everything Django does natively, plus more.
 
-## Constraints
-### uniqueness
+## uniqueness
 The `uniqueness` constraint can be added on one or more `hstore` keys, similar to how a `UNIQUE` constraint can be added to a column. Setting this option causes unique indexes to be created on the specified keys.
 
 You can specify a `list` of strings to specify the keys that must be marked as unique:
@@ -26,7 +23,7 @@ Uniqueness can also be enforced "together", similar to Django's [unique_together
 
 In the example above, `key1` and `key2` must unique **together**, and `key3` must unique on its own. By default, none of the keys are marked as "unique".
 
-### required
+## required
 The `required` option can be added to ensure that the specified `hstore` keys are set for every row. This is similar to a `NOT NULL` constraint on a column. You can specify a list of `hstore` keys that are required:
 
     from psqlextra.fields import HStoreField
@@ -39,3 +36,41 @@ The `required` option can be added to ensure that the specified `hstore` keys ar
     MyModel.objects.create(myfield={'key2': 'value1'})
 
 Both calls to `create` would fail in the example above since they do not provide a non-null value for `key1`. By default, none of the keys are required.
+
+# Upsert
+An "upsert" is an operation where a piece of data is inserted/created if it doesn't exist yet and updated (overwritten) when it already exists. Django has long provided this functionality through [`update_or_create`](https://docs.djangoproject.com/en/1.10/ref/models/querysets/#update-or-create). It does this by first checking whether the record exists and creating it not.
+
+The major problem with this approach is possibility of race conditions. In between the `SELECT` and `INSERT`, another process could perform the `INSERT`. The last `INSERT` would most likely fail because it would be duplicating a `UNIQUE` constaint.
+
+In order to combat this, PostgreSQL added native upserts. Also known as [`ON CONFLICT DO ...`](https://www.postgresql.org/docs/9.5/static/sql-insert.html#SQL-ON-CONFLICT). This allows a user to specify what to do when a conflict occurs.
+
+
+## upsert
+The `upsert` method attempts to insert a row with the specified data or updates (and overwrites) the duplicate row, and then returns the primary key of the row that was created/updated:
+
+from django.db import models
+    from psqlextra.models import PostgresModel
+
+    class MyModel(PostgresModel):
+        myfield = models.CharField(max_length=255, unique=True)
+
+    id1 = MyModel.objects.upsert(myfield='beer')
+    id2 = MyModel.objects.upsert(myfield='beer')
+
+    assert id1 == id2
+
+Note that a single call to `upsert` results in a single `INSERT INTO` statement. It is therefor much faster and much safer than anything Django currently has to offer.
+
+## upsert_and_get
+`upsert_and_get` does the same thing as `upsert`, but returns a model instance rather than the primary key of the row that was created/updated. This also happens in a single query using `RETURNING` clause on the `INSERT INTO` statement:
+
+    from django.db import models
+    from psqlextra.models import PostgresModel
+
+    class MyModel(PostgresModel):
+        myfield = models.CharField(max_length=255, unique=True)
+
+    obj1 = MyModel.objects.upsert_and_get(myfield='beer')
+    obj2 = MyModel.objects.upsert_and_get(myfield='beer')
+
+    assert obj1.id == obj2.id

docs/index.md

@@ -5,15 +5,15 @@ django-postgres-extra aims to make all of PostgreSQL's awesome features availabl
 With seamless we mean that any features we add will work truly seamlessly. You should not have to manually modify your migrations to work with fields and objects provided by this package.
 
 ## PostgreSQL features
-We are currently aiming on having the following features available:
+Explore the [Features](/features/) page for detailed instructions and information on how to use all features.
 
-* [hstore](https://www.postgresql.org/docs/9.1/static/hstore.html)
-    * UNIQUE constaints
-    * NOT-NULL constaints
+* [hstore](/features/#hstorefield)
+    * [`uniqueness`](/features/#uniqueness)
+    * [`required`](/features/#required)
 
-* [ltree](https://www.postgresql.org/docs/9.1/static/ltree.html)
-
-* [native upsert](https://www.postgresql.org/docs/9.5/static/sql-insert.html#SQL-ON-CONFLICT)
+* [upsert](/features/#upsert)
+    * [`upsert`](http://localhost:8000/features/#upsert_1)
+    * [`upsert_and_get`](http://localhost:8000/features/#upsert_and_get)
 
 ## Installation
 
@@ -44,5 +44,6 @@ In order to use this package, your project must be using:
 
 * Python 3.5, or newer
 * PostgreSQL 9.6 or newer
+* Django 1.10 or newer
 
 Python 3.5 is required because type hints are used. A feature only available in Python 3.5 and newer. PostgreSQL 9.6 is required to take advantage of the latest features such as `ltree`.