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.