Usage¶
Some facts about this library:
- setup from a CRUD (Create Read Update Delete) perspective
- lightly setup as a pyramid extension / add-on
- minimally uses the component architecture (zope.interface)
Scripting Usage¶
Occasionally, a script or application will need to utilize the database in
a one off way. The cnxdb.scripting.prepare()
function has been created
to prepare an environment for work with the database. It pulls from the same
configuration as the application would. The resulting dictionary contains
the discovered settings, a dict of database engines
(sqlalchemy.engine.Engine instances) and a closer function.
The settings information comes from the documented means of configuration. See Configuration for details.
The engines are created using the settings. The dictionary is keyed
by the purpose of the needed connection.
For example, the use of engines['super']
will give you
a superuser connection.
The closer function is used to safely close the process without leaving hanging connections and/or communications.
This design of this feature is modeled after pyramid.scripting.prepare.
Script Example¶
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | from cnxdb.scripting import prepare
def print_latest_publication():
env = prepare()
print("working with the following settings: {}".format(env['settings']))
conn = env['engines']['common'].raw_connection()
with conn:
with conn.cursor() as cursor:
cursor.execute("select uuid from latest_modules "
"order by revised desc")
print(cursor.fetchone()[0])
env['closer']()
if __name__ == '__main__':
print_latest_publication()
|
This script prints the UUID of the latest publication. It utilizes all three
of the env
values: settings
, engines
and closer
.
For other examples, have a look at cnxdb.cli.subcommands
.
Pyramid Application Usage¶
This package can be integrated with a Pyramid Web Framework based application. For exmaple, the following includes this package using the imperative configuration style:
1 2 3 4 5 6 7 8 | from pyramid.config import Configurator
def app():
config = Configurator()
# ...
config.include('cnxdb.contrib.pyramid')
# ...
return config.make_wsgi_app()
|
This will give you access to the get_db_engine
and db_tables
method and attribute on the request object.
The get_db_engine
method returns a SQLAlchemy Engine object.
It can optionally be given a connection name
(common
, super
, readonly
).
If the connection name is ommited, it will default to the use of common
.
The db_tables
attribute returns an object contains references
SQLAlchemy Table objects that have been created from the database
through SQLAlchemy’s inspection process.