Getting started with the Midgard content repository

1. Installing Midgard
2. Defining a schema
3. Initiating the repository connection
4. Interacting with data
5. Querying data

I'm doing a talk today in the Bossa Conference about using Midgard as a content repository for mobile applications. As part of my presentation I wrote some simple example code for using the Midgard APIs in Python, and thought they would be good to share to those not attending the event as well.

The idea of a content repository is that instead of coming up with new, isolated file formats or database setups for your application you can just work with objects and signals, and let Midgard handle the rest. This is something that lots of people are doing with CouchDB as well, but we feel Midgard, with its light footprint and native APIs for languages like Python, C, Vala and PHP fits better in the mobile applications context.

Installing Midgard

Midgard packages are available for many different Linux distributions through the OpenSuse Build Service. To find the right repository for your setup, go to the OBS project page. For example, on my Ubuntu Karmic netbook the URL to add to apt sources.list is deb http://download.opensuse.org/repositories/home:/midgardproject:/mjolnir/xUbuntu_9.10/ ./. Then I just:

sudo apt-get update
sudo apt-get install python-midgard2

Midgard is also available in Maemo extras and for OS X on MacPorts.

Defining a schema

The first thing when developing a Midgard application is to define your storage objects. This is done using the MgdSchema XML format. In this case we're doing a simple "attendee" object that amends Midgard's built-in person record with information related to the conference:

<?xml version="1.0" encoding="UTF-8"?>
<Schema xmlns="http://www.midgard-project.org/repligard/1.4">
    <type name="openbossa_attendee" table="openbossa_attendee">
        <property name="id" type="unsigned integer" primaryfield="id">
            <description>Local non-replication-safe database identifier</description>
        </property>
        <property name="person" type="unsigned integer" link="midgard_person:id">
            <description>Person attending the event</description>
        </property>
        <property name="registration" type="datetime">
            <description>Registration date of the attendee</description>
        </property>
        <property name="likesbeer" type="boolean">
            <description>Whether the attendee likes beer</description>
        </property>
    </type>
</Schema>

Then we just save this XML file into /usr/share/midgard2/schema/ so that Midgard will find it.

Initiating the repository connection

Once the MgdSchema is in place it is time to import antigravity and start hacking in Python. The code works pretty much in the same way in other languages Midgard is available for, but Python is used here for the sake of simplicity. First we load the Midgard extension:

import _midgard as midgard

Then we setup the repository connection. With these settings we will store our content into an SQLite database located in ~/.midgard2/data/midgardexample.db:

configuration = midgard.config()
configuration.dbtype = 'SQLite'
configuration.database = 'midgardexample'

# Open a Midgard repository connection with our config
connection = midgard.connection()
connection.open_config(configuration)

As this is the first time we're interacting with the repository we need to tell Midgard to prepare the storage for itself and also for our new openbossa_attendee class:

midgard.storage.create_base_storage()
midgard.storage.create_class_storage('midgard_person')
midgard.storage.create_class_storage('midgard_parameter')
midgard.storage.create_class_storage('openbossa_attendee')

Interacting with data

First we create a person object with our attendee:

person = midgard.mgdschema.midgard_person()
person.firstname = 'Leif'
person.lastname = 'Eriksson'
person.create()

Then we create our attendee object and link that with the person we just created:

attendee = midgard.mgdschema.openbossa_attendee()
attendee.person = person.id
attendee.likesbeer = True
attendee.create()

Querying data

Later we'll want to find out about all Leifs attending the event. We do this by using the Midgard query builder:

qb = midgard.query_builder('openbossa_attendee')
qb.add_constraint('person.firstname', '=', 'Leif')
attendees = qb.execute()

The query builder returns us a list of matching attendee objects. We can go through them and also fetch the associated persons:

for attendee in attendees:
    person = midgard.mgdschema.midgard_person()
    person.get_by_id(attendee.person)
    if attendee.likesbeer:
        print "%s, %s is attending the event" % (person.lastname, person.firstname)

Then we can update the persons with their email addresses:

    person.email = 'leif@vinland.no'
    person.update()

For basic data handling, that's it! When you need more, you can extend objects with file attachments or parameters. You can also create joined records using Midgard views. Midgard provides D-Bus signals, transactions, centralized metadata, synchronization and many other things.