Persistence

Preparation

Create a database, and a user with permissions to work with the database.

Create a class that represents the data you want to store.

import basium_model

class Contacts(basium_model.Model):
    name = basium_model.VarcharCol()
    age = basium_model.IntegerCol()

Initalize Basium and register the classes that should be persisted, and start basium. When started, the database is opened. If checkTables=True the columns and types are verified against the model Class and adjusted if needed.

db = basium_init.Basium(
    driver='mysql', checkTables=True, 
    conn={'host':'localhost',
          'port':'8051', 
          'user':'basium_user', 
          'pass':'secret', 
          'name': 'basium_db'}
    )
db.addClass(Contacts)
if not basium.start():
   sys.exit(1)

Now Basium is ready to be used.

Store objects

Create instances of the object .

contact1 = Contact()
contact1.name = 'Anders Lowinger'
contact1.age = 21

contact2 = Contact()
contact2.name = 'Albert Einstein'
contact2.age = 133

Store the object in the database

res1 = db.store(contact1)
res2 = db.store(contact2)

store returns the objects unique id

Easy, isn't it?

Retrieve objects

There are two ways to retrieve a contact, by ID and doing a Query.

By ID

Each Class that is registred in Basium automatically gets a column called '_id' added, this column is the primary column, type integer and auto-assigned. When creating an instance of the Contact class the id is initialized to -1 (not persisted).

After the db.store() the id gets a positive value. If you know the ID it is very simple to retrieve the object.

contact = Contact(1)
contact = db.load(contact)

contact[0] now contains the contact1 stored above (assuming the database table contacts was empty)

Load always returns an array

The above can be shortened

contact = db.load(Contact(1))

By query

To support more complex retrieval of objects, the Query can be used. Remember to prepend the coluumn that should be filtered on with q. Example:

If you want to match on "customer.age", you specify "customer.q.age". The attribute customer.age just returns the current age, while the customer.q.age is the IntegerCol() used when defining the Customer class and the Query object needs the instance, so it can find out what table to query etc.

query = db.query()
query.filter(contact.q.age, '>', 100)
contacts = db.load(query)
for contact in contacts:
   print contact.name, contact.age

This retrieves and prints out all contacts in the table that is older than 100 years

Query objects can contain multiple filters, the resulting query is the individual filters ANDed together.

query = db.query()
query.filter(contact.q.age, '>', 18)
query.filter(contact.q.age, '<', 24)
contacts = db.load(query)
for contact in contacts:
   print contact.name, contact.age

This retrieves and prints out all contacts in the table that is 100 years or older, where their age is over 18 and less than 24 years.

The filter object returns itself, so it can be chained. The above query can be shortened.

query = db.query().filter(contact.q.age, '>', 18).filter(contact.q.age, '<', 24)

If you want to retrieve all objects, just pass an instance of the Class

contacts = db.load(Customer())
for contact in contacts:
   print contact.name, contact.age

This retrieves and prints all contacts.

Error handling

The db.load() and db.store() function returns an exception if there is any errors.

try:
  contact = db.load(Contact())
except db.Error as err:
  print("Error in load(), %s" % err)

The err above is an Exception class that contains an integer errno and a string errmsg. The err.str method returns a text representation of the error that can be printed