Using database API
This document describes the basics of the underlying GRAMPS database. This is not intended to be a reference manual, but an introductory programmer's guide to using the GRAMPS database access routines. If you are a looking for documentation on how to use the GRAMPS system as a user instead of as a program developer, it can be found on the GRAMPS documentation web page. Separate API Reference Documentation is available (Note that you should click in the right-hand-corner of this website, on the show private link to really see how the API works!).
GRAMPS is written in the Python language. A basic familiarity with Python is required before the database objects can be effectively used. If you are new to Python, you may wish to check out the Python tutorial.
Primary objects are the fundamental objects in the GRAMPS database. These objects are:
- Person - Contains the information specific to an individual person.
- Family - Contains the information specific to relationships between people. This typically contains one or two parents and zero or more children.
- Source - Contains the information related to a source of information.
- Place - Contains the information related to a specific place.
- Media Object - Contains the information related to a media object. This includes images, documents, or any other type of related files.
- Event - Contains the information related to an event. The event is treated as a primary object in the database, it currently does not appear as a primary object to the end user.
Primary objects are treated as tables within the database. Individual components that compose the primary object are stored as individual items in the database.
Each primary object has a unique handle associated with it. The handle serves as both a unique identifier and as the key into the database. This handle is generated using the current timestamp along with two 32-bit random numbers. The resulting value is converted to a text string to provide a hashable handle.
The handle can always be retrieved from a primary object using the get_handle function.
handle = person.get_handle()
All relationships between primary objects are in terms of the handle, instead of a reference to an object. This allows objects that are not currently being used to be stored on disk instead of in memory. This adds an additional step of fetching from the database to find related data. For example, to get the Person object marked as the father of a Family, the following must be done:
# find father from a family father_handle = family.get_father_handle() father = database.get_person_from_handle(father_handle)
For this reason, it is always necessary to have reference to the database that contains the objects with which you are working.
The handle should not be visible to the end user, and should not be included in reports or displayed on screen. Instead, the GRAMPS ID value should be used for this purpose. The GRAMPS ID is a user defined value for each object, but is not used internally to the database. This allows the user to change the GRAMPS ID without affecting the database.
Once created, the handle should never be modified.
Care must be taken when working with primary objects. Each instance that is retrieved from the database is unique, and not connected to other instances. The example below exhibits the issue:
# get two person objects using the same handle person1 = database.get_handle(handle) person2 = database.get_handle(handle) person1.set_nickname('Fred')
In this case, even though person1 and person2 represent the same person, but are distinct objects. Changing the nickname of person1 does not affect person2. The person2 object will retain the original nickname.
Changes to the object do not become permanent until the object has been committed to the database. If multiple instances exist in memory at the same time, care must be taken to make sure that data is not lost.
Secondary objects are objects that are contained within primary objects. These objects include dates, addresses, and source references among other objects.
Secondary objects are treated as a single unit within the database. Typically, this means that the objects are stored in pickled format.
GRAMPS provides a standard interface for all database objects. The GRAMPS database object provides the interface to the lower level database. Currently, three database objects are supported:
- GrampsBSDDB - the default database, providing access to a Berkeley DB database.
- GrampsXMLDB - provides in-memory editing of the GRAMPS XML database format.
- GrampsGEDDB - provides in-memory editing of a GEDCOM file.
All the database classes are inherited from a common base, so they provide identical interfaces.
Transactions and Commits
In order to support an UNDO feature, the database has the concept of Transactions. Transactions are a group of related database commit operations that need treated as a single unit. If all related commits are not undone as a single unit, the database can be left in a corrupted state. The UNDO operation will undo all the commits in the transaction.
Transactions may be as small as a simple edit of a person or as complex as a GEDCOM import. The developer must decide what the appropriate level of abstraction is for an operation. The developer must also guarantee that the transaction encompasses the entire transaction, so that an undo operation does not leave the database in an inconsistent state.
An example of a transaction is shown below.
# Create a new family and add the spouses # Assume that the father and mother already exist # begin transaction transaction = database.transaction_begin() # Create new family, add it to the database. The add_family # function will assign the handle family = Family() database.add_family(family,transaction) # Add the family to the father and mother father.add_family_handle(family.get_handle()) mother.add_family_handle(family.get_handle()) # Add parents to the family family.set_father_handle(father.get_handle()) family.set_mother_handle(mother.get_handle()) # Commit the changes to the father, mother, and family database.commit_person(father, transaction) database.commit_person(mother, transaction) database.commit_family(father, transaction) # finish the transaction database.transaction_commit(transaction, "Add family")
Each commit operation associated with a transaction stores the previous value of the object in the database log file. The transaction keeps track to the start and stop commits in this list. Undoing the last transaction is as simple as:
This operation pops the last transaction off the stack, and restores the previous values that were stored in the transaction log file.
Iterating through the database
Frequently, it is useful to iterate through all the elements of a database. GRAMPS provides two ways of accomplishing this. The first method involves getting a list of all the handles and looping over the list. This method is the easiest to implement. An example is below:
for handle in database.get_person_handles(): person = database.get_person_from_handle(handle)
A more efficient method exists, but is more complicated to use. The database can provide a cursor that will iterate through the database without having to load all handles into memory. The cursor returns a handle, data pair. The data represents the serialized data directly from the database. It is the users responsibility to unserialize the data. An example is below:
cursor = database.get_person_cursor() pair = cursor.first() while pair: (handle,data) = pair person = Person() person.unserialize(data) pair = cursor.next() cursor.close()
Primary objects can reference each other in two ways.
A primary object may reference another directly, for instance a Person object may link to a Source object that has information about where some information about the person came from. Finding all of the primary (or forward links) can be done like this:
# get references directly from the primary object references = person.get_referenced_handles() # get all references from the primary object and # all secondary objects that are linked to it. references = person.get_referenced_handles_recursively()
The second type of reference is an implicit backlink, this is the reverse of the forward-link above. To find all the backlinks for a primary object you have to ask the database to search all the primary objects to see which ones have a reference to the primary object you are looking for. You can do this by using the find_backlink_handles() method. e.g.
for reference in db.find_backlink_handles(person.get_handle()): reference_class_name, reference_handle = reference if reference_class_name == 'Person': person = db.get_person_from_handle(reference_handle)
Getting notification of changes to the database
If you have widgets that are displaying the content of the database tables you need to be aware that the database can change. Records may be added, removed or updated by other parts of GRAMPS and your widget must show these changes. The GRAMPS database provides a signalling mechanism that can be used to notify your widget of changes to the database. The documentation for the ((GrampsDBCallback)) class provides a description of the signalling mechanism. For most code that uses the GRAMPS database all that is required is for callback functions to be connected to the correct signals. For example:
database.connect('person-add',self.update_view) database.connect('person-update',self.update_view) database.connect('person-rebuild',self.update_view)
A full list of the signals that are emitted from the database can be found at the top of the GrampsDbBase class in the GrampsDbBase.py module.