Better docs, fixes coleifer#489.

docs/peewee/database.rst

@@ -21,12 +21,19 @@ This document describes how to perform typical database-related tasks with peewe
 Creating a database connection and tables
 -----------------------------------------
 
-While it is not necessary to explicitly connect to the database before using it, managing connections explicitly is a good practice. This way if the connection fails, the exception can be caught during the *connect* step, rather than some arbitrary time later when a query is executed.
+While it is not necessary to explicitly connect to the database before using it, **managing connections explicitly is a good practice**. This way if the connection fails, the exception can be caught during the *connect* step, rather than some arbitrary time later when a query is executed. Furthermore, if you're using a :ref:`connection pool <pool>`, it is actually necessary to call :py:meth:`~Database.connect` and :py:meth:`~Database.close` to ensure connections are recycled correctly.
+
+For web-apps you will typically open a connection when a request is started and close it when the response is delivered:
 
 .. code-block:: python
 
-    >>> database = SqliteDatabase('my_app.db')
-    >>> database.connect()
+    database = SqliteDatabase('my_app.db')
+
+    def before_request_handler():
+        database.connect()
+
+    def after_request_handler():
+        database.close()
 
 To use this database with your models, set the ``database`` attribute on an inner :ref:`Meta <model-options>` class:
 

docs/peewee/example.rst

@@ -172,7 +172,9 @@ This is a peewee idiom:
     # execute queries
     database = SqliteDatabase(DATABASE, threadlocals=True)
 
-Because SQLite likes to have a separate connection per-thread, we will tell flask that during the request/response cycle we need to create a connection to the database. Flask provides some handy decorators to make this a snap:
+When developing a web application, it's common to open a connection when a request starts, and close it when the response is returned. **You should always manage your connections explicitly**. For instance, if you are using a :ref:`connection pool <pool>`, connections will only be recycled correctly if you call :py:meth:`~Database.connect` and :py:meth:`~Database.close`.
+
+We will tell flask that during the request/response cycle we need to create a connection to the database. Flask provides some handy decorators to make this a snap:
 
 .. code-block:: python
 

docs/peewee/quickstart.rst

@@ -61,7 +61,13 @@ Things get interesting when we set up relationships between models using `foreig
         class Meta:
             database = db # this model uses the people database
 
-Now that we have our models, let's create the tables in the database that will store our data. This will create the tables with the appropriate columns, indexes, sequences, and foreign key constraints:
+Now that we have our models, let's connect to the database. Although it's not necessary to open the connection explicitly, it is good practice since it will reveal any errors with your database connection immediately, as opposed to some arbitrary time later when the first query is executed. It is also good to close the connection when you are done -- for instance, a web app might open a connection when it receives a request, and close the connection when it sends the response.
+
+.. code-block:: pycon
+
+    >>> db.connect()
+
+We'll begin by creating the tables in the database that will store our data. This will create the tables with the appropriate columns, indexes, sequences, and foreign key constraints:
 
 .. code-block:: pycon
 
@@ -308,6 +314,12 @@ One last query. This will use a SQL function to find all people whose names star
     ...
     Grandma L.
 
+We're done with our database, let's close the connection:
+
+.. code-block:: pycon
+
+    >>> db.close()
+
 This is just the basics! You can make your queries as complex as you like.
 
 All the other SQL clauses are available as well, such as:

examples/analytics/app.py

@@ -126,6 +126,18 @@ def script():
 def not_found(e):
     return Response('<h3>Not found.</h3>')
 
+# Request handlers -- these two hooks are provided by flask and we will use them
+# to create and tear down a database connection on each request.
+@app.before_request
+def before_request():
+    g.db = database
+    g.db.connect()
+
+@app.after_request
+def after_request(response):
+    g.db.close()
+    return response
+
 
 if __name__ == '__main__':
     create_model_tables([Account, PageView], fail_silently=True)

examples/twitter/app.py

@@ -150,9 +150,8 @@ def get_object_or_404(model, *expressions):
 def is_following(from_user, to_user):
     return from_user.is_following(to_user)
 
-# request handlers -- these two hooks are provided by flask and we will use them
-# to create and tear down a database connection on each request.  peewee will do
-# this for us, but its generally a good idea to be explicit.
+# Request handlers -- these two hooks are provided by flask and we will use them
+# to create and tear down a database connection on each request.
 @app.before_request
 def before_request():
     g.db = database