Tentdata

Tent Database Module (tent.data)

The tent.data module provides an Object Relational Mapper (ORM) facility that is used to read and write native python objects in a traditional relational database engine (i.e. SQLite, MySQL, PostgreSQL). At the moment only SQLite is supported, support for other engines will be added soon. The module is mainly powered by SQLAlchemy and theoretically any backend DBMS that they support should work with our system too.

Using existing data models

Loading data modules

Before we open any connections, data models that you want to work with should be loaded into the system. Currently the number of data models that tent supports is minimal (if you think you can help add more, see 'Creating Data Models' below), Load models by importing one or many of the following packages:

• tent.data.user - Loads tables for managing pytentd users (representations of people who host their data on this server) and their profiles.

Establishing a Connection

First, import tent.data.dbm. This is the main entrypoint to the database system in tent. It contains methods for connecting to the database systems, creating tables and establishing ORM sessions.

Next, you'll need to open a connection to your database. This is achieved through tent.data.dbm.connect(). This method expects an argument containing database configuration that can be used to build a connection URI.

For SQLite, you should feed in a python dict containing the path to the database and the driver name ('sqlite'). e.g.

{
  'driver' : 'sqlite',
  'path'   : '/home/user/tent.db'
}

Or for an in-memory temporary database (used in some database unit tests)

{
  'driver' : 'sqlite',
  'path'   : '/home/user/tent.db'
}

The returned object from this call is an SQLAlchemy Engine object which can be used by pytentd to automatically create all database tables, establish ORM sessions and directly query the database.

Installing database tables

If you are working with a new database file (or have just opened a new SQLite :memory: database), you'll need to set up the new data tables. Provided you have loaded all the data models you wish to work with(as described above), tent will automatically detect table schemas for your models and install all relevant tables into the database with a call to tent.data.dbm.install_tables( engine ). Simply pass in your engine object from the previous step at this point.

Establishing a data session

SQLAlchemy's ORM capability requires that a session object is created and used to get python data objects in and out of the database. Generation of a session object is wrapped by tent and can be triggered by a call to tent.data.dbm.open_session( engine ). Pass in the engine object from the previous steps. The session object is returned upon a successful connection.

Using a session

Session objects can be queried and python data objects can be added and removed from sessions. For more information on how sessions can be used, read Session over at SQLAlchemy and have a look at the below code example.

Storing a user in the database

from tent.data import dbm
from tent.data.user import User

config = { 'driver' : 'sqlite', 'path' : ':memory:'}
engine = dbm.connect(config)
dbm.install_tables(engine)
session = dbm.open_session(engine)

u = User("Joe Public")
session.add(u)
session.commit()
session.close()

Creating new data models

If you need to create a new data model for pytentd, you can set up one or many classes as if you were working with vanilla SQLAlchemy ORM with a couple of exceptions.

You should inherit from tent's declarative base rather than setting up your own. This allows pytentd to automatically detect and generate tables for your new model on import. You can do this by importing tent.data.dbm.Base and inheriting from it in your model.

from tent.data.dbm import Base

...
class User(Base):
    __tablename__ = "tables"
... 

You can use pytentd's tent.data.dbm.TableMixin for your data models to make table definitions more convenient. The main advantage of this is that pytentd will try to guess your object's table name for you and the TableMixin may also provide more automatic helpfulness in future.

Further Reading

For more information, read the SQLAlchemy manual and take a look at our pydoc (not yet available).