Flask-SQLAlchemySession

Documentation
Release 1.0

Dimitris Theodorou

May 31, 2015

 Contents

1 Basic usage 3

2 Implementation 5

3 Full Example 7

4 Comparison with Flask-SQLAlchemy 9

5 API 11
5.1 Flask-SQLAlchemy-Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Python Module Index 13

i
ii
 Flask-SQLAlchemySession Documentation, Release 1.0

Flask-SQLALchemy-Session is a tiny library providing an SQLAlchemy scoped session that creates unique sessions
per Flask request, following the guidelines documented at Using Custom Created Scopes.

• Basic usage
• Implementation
• Full Example
• Comparison with Flask-SQLAlchemy
• API
– Flask-SQLAlchemy-Session

Contents 1
Flask-SQLAlchemySession Documentation, Release 1.0

2 Contents
 CHAPTER 1

Basic usage

Initialize a flask_scoped_session as you would a scoped_session, with the addition of a Flask app. Then
use the resulting session to query models:
from flask import Flask, abort, jsonify
from flask_sqlalchemy_session import flask_scoped_session

app = Flask(__name__)
session = flask_scoped_session(session_factory, app)

@app.route("/users/<int:user_id>")
def user(user_id):
user = session.query(User).get(user_id)
if user is None:
abort(404)
return flask.jsonify(**user.to_dict())

The current_session is also provided as a convenient accessor to the session of the current request, in the same
spirit of request and current_app.

3
Flask-SQLAlchemySession Documentation, Release 1.0

4 Chapter 1. Basic usage

 CHAPTER 2

Implementation

The flask_scoped_session is a simple wrapper over the original scoped_session that sets the scope to the
Flask application context, using the right scopefunc parameter. The application context is rougly equivalent to a
Flask request (more here). The session is destroyed on application context teardown.

5
Flask-SQLAlchemySession Documentation, Release 1.0

6 Chapter 2. Implementation
 CHAPTER 3

Full Example

This is a complete example with SQL Alchemy model and engine initialization, followed by Flask app creation and
querying of models within a Flask request.
Declare your models:
from sqlalchemy import Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

class User(Base):
id = Column(Integer, primary_key=True)
name = Column(String)

def to_dict(self):
return {"id": self.id,
"name": self.name}

Initialize the database engine and session:

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

engine = create_engine("sqlite://")
session_factory = sessionmaker(bind=engine)

Instantiate a Flask application and query a model within a request:

from flask import Flask, abort, jsonify
from flask_sqlalchemy_session import flask_scoped_session

app = Flask(__name__)
session = flask_scoped_session(session_factory, app)

@app.route("/users/<int:user_id>")
def user(user_id):
user = session.query(User).get(user_id)
if user is None:
abort(404)
return flask.jsonify(**user.to_dict())

Or use the equivalent current_session:

7
Flask-SQLAlchemySession Documentation, Release 1.0

from flask_sqlalchemy_session import current_session

@app.route("/users/<int:user_id>")
def user(user_id):
user = current_session.query(User).get(user_id)
if user is None:
abort(404)
return flask.jsonify(**user.to_dict())

8 Chapter 3. Full Example

 CHAPTER 4

Comparison with Flask-SQLAlchemy

The Flask-SQLAlchemy project also provides a request-scoped session, along with much more. It comes an API that
acts as a facade over various SQL Alchemy APIs (engines, models, metadata). This API buries the engine/session
initialization behind the Flask app initialization, detracts from the original by removing decisions, and tightly couples
the data layer with the Flask app. On the good side, it is an API easier to start with than SQL Alchemy itself.
Flask-SQLAlchemySession is not intrusive to the original SQL Alchemy APIs in any way, and does not force you to
couple your data layer with your web application. It’s sole purpose is to enable request-scoped sessions on top of your
SQL Alchemy constructs.

9
Flask-SQLAlchemySession Documentation, Release 1.0

10 Chapter 4. Comparison with Flask-SQLAlchemy

 CHAPTER 5

API

5.1 Flask-SQLAlchemy-Session

Provides an SQLAlchemy scoped session that creates unique sessions per Flask request
flask_sqlalchemy_session.current_session
Provides the current SQL Alchemy session within a request.
class flask_sqlalchemy_session.flask_scoped_session(session_factory, app=None)
A scoped_session whose scope is set to the Flask application context.
__init__(session_factory, app=None)
Parameters
• session_factory – A callable that returns a Session
• app – a Flask application
init_app(app)
Setup scoped sesssion creation and teardown for the passed app.
Parameters app – a Flask application

11
Flask-SQLAlchemySession Documentation, Release 1.0

12 Chapter 5. API
 Python Module Index

f
flask_sqlalchemy_session, 11

13
Flask-SQLAlchemySession Documentation, Release 1.0

14 Python Module Index

 Index

Symbols
__init__() (flask_sqlalchemy_session.flask_scoped_session
method), 11

C
current_session (in module flask_sqlalchemy_session),
11

F
flask_scoped_session (class in
flask_sqlalchemy_session), 11
flask_sqlalchemy_session (module), 11

I
init_app() (flask_sqlalchemy_session.flask_scoped_session
method), 11

15