Add more documentation on custom database back-end

Author: Photonios

docs/db-engine.md

@@ -0,0 +1,25 @@
+`psqlextra.backend` is an extension of the standard PostgreSQL back-end that comes with Django. This is required in order to implement automatic migrations for all the extra features that `psqlextra` offers.
+
+## Common pitfalls
+### Superuser required
+The `psqlextra.backend` attempts to enable the HStore extension through the following statement:
+
+```sql
+CREATE EXTENSION IF NOT EXISTS hstore'
+```
+
+This requires the user connecting to the database to be a super-user. If you're using a non-superuser to connect to your database, make sure to manually enable the extension on your database, otherwise migrations will fail with an exception:
+
+```
+django.db.utils.ProgrammingError: permission denied to create extension "hstore"
+HINT:  Must be superuser to create this extension.
+```
+
+### Using a custom database back-end
+Are you already using a custom database back-end that is not the standard PostgreSQL back-end? For example, the `postgis` back-end? You can control the base back-end for `psqlextra` by setting this setting:
+
+```python
+POSTGRES_EXTRA_DB_BACKEND_BASE = 'django.contrib.gis.db.backends.postgis'
+```
+
+`psqlextra` will use the specified back-end as the base. By default, this is the standard PostgreSQL back-end that comes with Django.

docs/index.md

@@ -20,6 +20,8 @@ Explore the documentation to learn about all features:
 * [Indexes](/indexes)
     * [ConditionalUniqueIndex](/indexes/#conditional-unique-index)
 
+* [Database engine](/db-engine)
+
 ## Installation
 
 1. Install the package from PyPi:
@@ -46,6 +48,8 @@ Explore the documentation to learn about all features:
 
 4. Make sure all models that inherit from `psqlextra.models.PostgresModel` or use the `psqlextra.manager.PostgresManager`. Without this, most features **do not work**.
 
+5. Read the documentation about the custom database engine to avoid common pitfalls: [Database engine](/db-engine) .
+
 ## Requirements
 In order to use this package, your project must be using:
 

mkdocs.yml

@@ -5,3 +5,4 @@ pages:
 - HStore: hstore.md
 - Signals: signals.md
 - Indexes: indexes.md
+- Database engine: db-engine.md