Permalink
Browse files

Updated examples to new sqlite patterns and added new section to appc…

…ontext docs
  • Loading branch information...
1 parent 3e9f4e2 commit c2e5799879ed22a4657b75df6da66d6074ae7cc7 @mitsuhiko mitsuhiko committed Oct 9, 2012
Showing with 169 additions and 104 deletions.
  1. +44 −0 docs/appcontext.rst
  2. +59 −48 docs/patterns/sqlite3.rst
  3. +22 −19 examples/flaskr/flaskr.py
  4. +44 −37 examples/minitwit/minitwit.py
View
@@ -85,3 +85,47 @@ Extensions are free to store additional information on the topmost level,
assuming they pick a sufficiently unique name.
For more information about that, see :ref:`extension-dev`.
+
+Context Usage
+-------------
+
+The context is typically used to cache resources on there that need to be
+created on a per-request or usage case. For instance database connects
+are destined to go there. When storing things on the application context
+unique names should be chosen as this is a place that is shared between
+Flask applications and extensions.
+
+The most common usage is to split resource management into two parts:
+
+1. an implicit resource caching on the context.
+2. a context teardown based resource deallocation.
+
+Generally there would be a ``get_X()`` function that creates resource
+``X`` if it does not exist yet and otherwise returns the same resource,
+and a ``teardown_X()`` function that is registered as teardown handler.
+
+This is an example that connects to a database::
+
+ import sqlite3
+ from flask import _app_ctx_stack
+
+ def get_db():
+ top = _app_ctx_stack.top
+ if not hasattr(top, 'database'):
+ top.database = connect_to_database()
+ return top.database
+
+ @app.teardown_appcontext
+ def teardown_db(exception):
+ top = _app_ctx_stack.top
+ if hasattr(top, 'database'):
+ top.database.close()
+
+The first time ``get_db()`` is called the connection will be established.
+To make this implicit a :class:`~werkzeug.local.LocalProxy` can be used::
+
+ from werkzeug.local import LocalProxy
+ db = LocalProxy(get_db)
+
+That way a user can directly access ``db`` which internally calls
+``get_db()``.
View
@@ -3,61 +3,61 @@
Using SQLite 3 with Flask
=========================
-In Flask you can implement the opening of database connections at the
-beginning of the request and closing at the end with the
-:meth:`~flask.Flask.before_request` and :meth:`~flask.Flask.teardown_request`
-decorators in combination with the special :class:`~flask.g` object.
+In Flask you can implement the opening of database connections on demand
+and closing it when the context dies (usually at the end of the request)
+easily.
-So here is a simple example of how you can use SQLite 3 with Flask::
+Here is a simple example of how you can use SQLite 3 with Flask::
import sqlite3
- from flask import g
+ from flask import _app_ctx_stack
DATABASE = '/path/to/database.db'
- def connect_db():
- return sqlite3.connect(DATABASE)
+ def get_db():
+ top = _app_ctx_stack.top
+ if not hasattr(top, 'sqlite_db'):
+ top.sqlite_db = sqlite3.connect(DATABASE)
+ return top.sqlite_db
- @app.before_request
- def before_request():
- g.db = connect_db()
+ @app.teardown_appcontext
+ def close_connection(exception):
+ top = _app_ctx_stack.top
+ if hasattr(top, 'sqlite_db'):
+ top.sqlite_db.close()
- @app.teardown_request
- def teardown_request(exception):
- if hasattr(g, 'db'):
- g.db.close()
+All the application needs to do in order to now use the database is having
+an active application context (which is always true if there is an request
+in flight) or to create an application context itself. At that point the
+``get_db`` function can be used to get the current database connection.
+Whenever the context is destroyed the database connection will be
+terminated.
-.. note::
+Example::
- Please keep in mind that the teardown request functions are always
- executed, even if a before-request handler failed or was never
- executed. Because of this we have to make sure here that the database
- is there before we close it.
+ @app.route('/')
+ def index():
+ cur = get_db().cursor()
+ ...
-Connect on Demand
------------------
-The downside of this approach is that this will only work if Flask
-executed the before-request handlers for you. If you are attempting to
-use the database from a script or the interactive Python shell you would
-have to do something like this::
+.. note::
- with app.test_request_context():
- app.preprocess_request()
- # now you can use the g.db object
+ Please keep in mind that the teardown request and appcontext functions
+ are always executed, even if a before-request handler failed or was
+ never executed. Because of this we have to make sure here that the
+ database is there before we close it.
-In order to trigger the execution of the connection code. You won't be
-able to drop the dependency on the request context this way, but you could
-make it so that the application connects when necessary::
+Connect on Demand
+-----------------
- def get_connection():
- db = getattr(g, '_db', None)
- if db is None:
- db = g._db = connect_db()
- return db
+The upside of this approach (connecting on first use) is that this will
+only opening the connection if truly necessary. If you want to use this
+code outside a request context you can use it in a Python shell by opening
+the application context by hand::
-Downside here is that you have to use ``db = get_connection()`` instead of
-just being able to use ``g.db`` directly.
+ with app.app_context():
+ # now you can use get_db()
.. _easy-querying:
@@ -66,16 +66,28 @@ Easy Querying
Now in each request handling function you can access `g.db` to get the
current open database connection. To simplify working with SQLite, a
-helper function can be useful::
+row factory function is useful. It is executed for every result returned
+from the database to convert the result. For instance in order to get
+dictionaries instead of tuples this can be used::
+
+ def make_dicts(cursor, row):
+ return dict((cur.description[idx][0], value)
+ for idx, value in enumerate(row))
+
+ db.row_factory = make_dicts
+Additionally it is a good idea to provide a query function that combines
+getting the cursor, executing and fetching the results::
+
def query_db(query, args=(), one=False):
- cur = g.db.execute(query, args)
- rv = [dict((cur.description[idx][0], value)
- for idx, value in enumerate(row)) for row in cur.fetchall()]
+ cur = get_db().execute(query, args)
+ rv = cur.fetchall()
+ cur.close()
return (rv[0] if rv else None) if one else rv
-This handy little function makes working with the database much more
-pleasant than it is by just using the raw cursor and connection objects.
+This handy little function in combination with a row factory makes working
+with the database much more pleasant than it is by just using the raw
+cursor and connection objects.
Here is how you can use it::
@@ -105,10 +117,9 @@ Relational databases need schemas, so applications often ship a
a function that creates the database based on that schema. This function
can do that for you::
- from contextlib import closing
-
def init_db():
- with closing(connect_db()) as db:
+ with app.app_context():
+ db = get_db()
with app.open_resource('schema.sql') as f:
db.cursor().executescript(f.read())
db.commit()
View
@@ -11,9 +11,8 @@
"""
from __future__ import with_statement
from sqlite3 import dbapi2 as sqlite3
-from contextlib import closing
from flask import Flask, request, session, g, redirect, url_for, abort, \
- render_template, flash
+ render_template, flash, _app_ctx_stack
# configuration
DATABASE = '/tmp/flaskr.db'
@@ -28,35 +27,37 @@
app.config.from_envvar('FLASKR_SETTINGS', silent=True)
-def connect_db():
- """Returns a new connection to the database."""
- return sqlite3.connect(app.config['DATABASE'])
-
-
def init_db():
"""Creates the database tables."""
- with closing(connect_db()) as db:
+ with app.app_context():
+ db = get_db()
with app.open_resource('schema.sql') as f:
db.cursor().executescript(f.read())
db.commit()
-@app.before_request
-def before_request():
- """Make sure we are connected to the database each request."""
- g.db = connect_db()
+def get_db():
+ """Opens a new database connection if there is none yet for the
+ current application context.
+ """
+ top = _app_ctx_stack.top
+ if not hasattr(top, 'sqlite_db'):
+ top.sqlite_db = sqlite3.connect(app.config['DATABASE'])
+ return top.sqlite_db
-@app.teardown_request
-def teardown_request(exception):
+@app.teardown_appcontext
+def close_db_connection(exception):
"""Closes the database again at the end of the request."""
- if hasattr(g, 'db'):
- g.db.close()
+ top = _app_ctx_stack.top
+ if hasattr(top, 'sqlite_db'):
+ top.sqlite_db.close()
@app.route('/')
def show_entries():
- cur = g.db.execute('select title, text from entries order by id desc')
+ db = get_db()
+ cur = db.execute('select title, text from entries order by id desc')
entries = [dict(title=row[0], text=row[1]) for row in cur.fetchall()]
return render_template('show_entries.html', entries=entries)
@@ -65,9 +66,10 @@ def show_entries():
def add_entry():
if not session.get('logged_in'):
abort(401)
- g.db.execute('insert into entries (title, text) values (?, ?)',
+ db = get_db()
+ db.execute('insert into entries (title, text) values (?, ?)',
[request.form['title'], request.form['text']])
- g.db.commit()
+ db.commit()
flash('New entry was successfully posted')
return redirect(url_for('show_entries'))
@@ -95,4 +97,5 @@ def logout():
if __name__ == '__main__':
+ init_db()
app.run()
Oops, something went wrong.

0 comments on commit c2e5799

Please sign in to comment.