Add a documented example how to use a template database for tests.

Refs pytest-dev#37.

Author: pelme

docs/database.rst

@@ -268,3 +268,43 @@ You can also manage the access manually via these methods:
 .. py:function:: django_db_blocker.restore_previous_access()
 
   Restore the previous state of the database blocking.
+
+Examples
+########
+
+Using a template database for tests
+"""""""""""""""""""""""""""""""""""
+
+This example shows how a pre-created PostgreSQL source database can be copied
+and used for tests.::
+
+    import pytest
+    from django.db import connections
+
+    import psycopg2
+    from psycopg2.extensions import ISOLATION_LEVEL_AUTOCOMMIT
+
+
+    def run_sql(sql):
+        conn = psycopg2.connect(database='postgres')
+        conn.set_isolation_level(ISOLATION_LEVEL_AUTOCOMMIT)
+        cur = conn.cursor()
+        cur.execute(sql)
+        conn.close()
+
+
+    @pytest.yield_fixture(scope='session')
+    def django_db_setup():
+        from django.conf import settings
+
+        settings.DATABASES['default']['NAME'] = 'the_copied_db'
+
+        run_sql('DROP DATABASE IF EXISTS the_copied_db')
+        run_sql('CREATE DATABASE the_copied_db TEMPLATE the_source_db')
+
+        yield
+
+        for connection in connections.all():
+            connection.close()
+
+        run_sql('DROP DATABASE the_copied_db')