Henson-Database¶
Provides SQLAlchemy support to Henson Applications.
Installation¶
You can install Henson-Database using Pip:
$ python -m pip install henso-databasen
You can also install it from source:
$ python setup.py install
Quickstart¶
from henson import Application
from henson_database import Database
app = Henson(__name__)
database = Database(app)
with db.session() as session:
session.execute('SELECT 1;')
Configuration¶
The following settings are used by Henson-Database. See Engine Configuration for full information on SQLAlchemy database URIs.
DATABASE_URI |
The URI to use to connect to the database. |
Contents:
API¶
Here’s the public API for Henson-Database.
Database¶
-
class
henson_database.Database(app=None)[source]¶ An interface to interact with a relational database.
Parameters: app (Optional[henson.base.Application]) – An application instance that has an attribute named settings that contains a mapping of settings to interact with a database. Changed in version 0.4.0: Alembic migrations are supported.
-
Model¶ Return a base class for creating models.
Returns: The base class to use for creating new models. Return type: sqlalchemy.ext.declarative.declarative_base
-
engine¶ Return the engine.
Returns: The engine. Return type: sqlalchemy.engine.Engine
-
init_app(app)[source]¶ Initialize an application for use with the database.
If database settings are provided by app as a dict rather than individual keys and values, expands them to the format expected by the extension’s internal create_engine call.
Parameters: app (henson.base.Application) – Application instance that has an attribute named settings that contains a mapping of settings needed to interact with the database.
-
metadata¶ Return the metadata associated with
db.Model.Returns: The metadata. Return type: sqlalchemy.MetaData
-
Migrations¶
Henson-Database offers support for Alembic migrations. To enable them, install Henson-Database with the migrations extra:
$ python -m pip install Henson-Database[migrations]
This enables the following commands through the db namespace:
$ henson --app APP_PATH db --help
henson –app APP_PATH db¶
usage: henson --app APP_PATH db [-h]
{branches,current,downgrade,edit,generate,heads,history,init,merge,revision,show,stamp,upgrade}
...
-
-h,--help¶ show this help message and exit
henson –app APP_PATH db branches¶
Show current branch points.
usage: henson --app APP_PATH db branches [-h] [--verbose]
-
-h,--help¶ show this help message and exit
-
--verbose,-v¶ verbose mode
henson –app APP_PATH db current¶
Display the current revision for a database.
usage: henson --app APP_PATH db current [-h] [--verbose]
-
-h,--help¶ show this help message and exit
-
--verbose,-v¶ verbose mode
henson –app APP_PATH db downgrade¶
Revert to a previous version.
usage: henson --app APP_PATH db downgrade [-h] [-s] [-t TAG] [revision]
-
revision¶ revision identifier
-
-h,--help¶ show this help message and exit
-
-s,--sql¶ don’t emit SQL to database - dump to standard output/file instead
-
-t<tag>,--tag<tag>¶ arbitrary ‘tag’ name - can be used by custom env.py scripts
henson –app APP_PATH db edit¶
Edit revision script(s) using $EDITOR.
usage: henson --app APP_PATH db edit [-h] rev
-
rev¶ None
-
-h,--help¶ show this help message and exit
henson –app APP_PATH db generate¶
Generate a revision (alias for ‘revision –autogenerate’).
usage: henson --app APP_PATH db generate [-h] [-m MESSAGE] [--sql]
[--head HEAD] [--splice]
[-b BRANCH_LABEL] [-v VERSION_PATH]
[-r REV_ID] [-d DEPENDS_ON]
-
-h,--help¶ show this help message and exit
-
-m<message>,--message<message>¶ message string to use with ‘revision’
-
--sql¶ don’t emit SQL to database - dump to standard output/file instead
-
--head<head>¶ specify head revision or <branchname>@head to base new revision on
-
--splice¶ allow a non-head revision as the ‘head’ to splice onto
-
-b<branch_label>,--branch-label<branch_label>¶ specify a branch label to apply to the new revision
-
-v<version_path>,--version-path<version_path>¶ specify specific path from config for version file
-
-r<rev_id>,--rev-id<rev_id>¶ specify a hardcoded revision id instead of generating one
-
-d<depends_on>,--depends-on<depends_on>¶ specify one or more revision identifiers which this revision should depend on
henson –app APP_PATH db heads¶
Show current available heads in the script directory.
usage: henson --app APP_PATH db heads [-h] [-r] [--verbose]
-
-h,--help¶ show this help message and exit
-
-r,--resolve-dependencies¶ treat dependency versions as down revisions
-
--verbose,-v¶ verbose mode
henson –app APP_PATH db history¶
List changeset scripts in chronological order.
usage: henson --app APP_PATH db history [-h] [-r REV_RANGE] [--verbose]
-
-h,--help¶ show this help message and exit
-
-r<rev_range>,--rev-range<rev_range>¶ specify a revision range; format is [start]:[end]
-
--verbose,-v¶ verbose mode
henson –app APP_PATH db init¶
Initialize a new scripts directory.
usage: henson --app APP_PATH db init [-h] [directory]
-
directory¶ location of scripts directory
-
-h,--help¶ show this help message and exit
henson –app APP_PATH db merge¶
Merge two revisions together. Creates a new migration file.
usage: henson --app APP_PATH db merge [-h] [-m MESSAGE] [-b BRANCH_LABEL]
[-r REV_ID]
revisions
-
revisions¶ one or more revisions, or ‘heads’ for all heads
-
-h,--help¶ show this help message and exit
-
-m<message>,--message<message>¶ message string to use with ‘revision’
-
-b<branch_label>,--branch-label<branch_label>¶ specify a branch apply to the new revision
-
-r<rev_id>,--rev-id<rev_id>¶ specify a hardcoded revision id instead of generating one
henson –app APP_PATH db revision¶
Create a new revision file.
usage: henson --app APP_PATH db revision [-h] [-m MESSAGE] [-a] [--sql]
[--head HEAD] [--splice]
[-b BRANCH_LABEL] [-v VERSION_PATH]
[-r REV_ID] [-d DEPENDS_ON]
-
-h,--help¶ show this help message and exit
-
-m<message>,--message<message>¶ message string to use with ‘revision’
-
-a,--autogenerate¶ populate revision script with candidate migration operations, based on comparison of database to model
-
--sql¶ don’t emit SQL to database - dump to standard output/file instead
-
--head<head>¶ specify head revision or <branchname>@head to base new revision on
-
--splice¶ allow a non-head revision as the ‘head’ to splice onto
-
-b<branch_label>,--branch-label<branch_label>¶ specify a branch label to apply to the new revision
-
-v<version_path>,--version-path<version_path>¶ specify specific path from config for version file
-
-r<rev_id>,--rev-id<rev_id>¶ specify a hardcoded revision id instead of generating one
-
-d<depends_on>,--depends-on<depends_on>¶ specify one or more revision identifiers which this revision should depend on
henson –app APP_PATH db show¶
Show the revision(s) denoted by the given symbol.
usage: henson --app APP_PATH db show [-h] rev
-
rev¶ None
-
-h,--help¶ show this help message and exit
henson –app APP_PATH db stamp¶
‘stamp’ the revision table with the given revision; don’t run any migrations.
usage: henson --app APP_PATH db stamp [-h] [-s] [-t TAG] revision
-
revision¶ revision identifier
-
-h,--help¶ show this help message and exit
-
-s,--sql¶ don’t emit SQL to database - dump to standard output/file instead
-
-t<tag>,--tag<tag>¶ arbitrary ‘tag’ name - can be used by custom env.py scripts
henson –app APP_PATH db upgrade¶
Upgrade to a later version.
usage: henson --app APP_PATH db upgrade [-h] [-s] [-t TAG] [revision]
-
revision¶ revision identifier
-
-h,--help¶ show this help message and exit
-
-s,--sql¶ don’t emit SQL to database - dump to standard output/file instead
-
-t<tag>,--tag<tag>¶ arbitrary ‘tag’ name - can be used by custom env.py scripts