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.

Database API

Access to the database is made through Python classes. Exactly what functionality you have is dependent on the properties of the database. For example, if you are accessing a read-only view, then you will only have access to a subset of the methods available.

At the root of any database interface is either DbReadBase and/or DbWriteBase. These define the methods to read and write to a database, respectively.

DbBsddb

The DbBsddb interface defines a hierarchical database (non-relational) written in PyBSDDB. There is no such thing as a database schema, and the meaning of the data is defined in the Python classes above. The data is stored as pickled tuples and unserialized into the primary data types (below).

DbDjango

The DbDjango interface defines the Gramps data in terms of models and relations from the Django project. The database backend can be any implementation that supports Django, including such popular SQL implementations as sqlite, MySQL, Postgresql, and Oracle. The data is retrieved from the SQL fields, serialized and then unserialized into the primary data types (below).

Primary objects are treated as tables within the database. Individual components that compose the primary object are stored as individual items in the database.

1. Person:

handle

gramps_id

gender

primary_name

alternate_names

death_ref_index

birth_ref_index

event_ref_list

family_list

parent_family_list

media_list

address_list

attribute_list

urls

lds_ord_list

source_list

note_list

change

tag_list

private

person_ref_list

2. Family:

handle

gramps_id

father_handle

mother_handle

child_ref_list

the_type

event_ref_list

media_list

attribute_list

lds_seal_list

source_list

note_list

change

tag_list

private

3. Event:

handle

gramps_id

the_type

date

description

place

source_list

note_list

media_list

attribute_list

change

private

4. Place:

handle

gramps_id

title

long

lat

main_loc

alt_loc

urls

media_list

source_list

note_list

change

private

5. Source:

handle

gramps_id

title

author

pubinfo

note_list

media_list

abbrev

change

datamap

reporef_list

private

6. Media:

handle

gramps_id

path

mime

desc

attribute_list

source_list

note_list

change

date

tag_list

private

7. Repository

handle

gramps_id

type

note_list

address_list

urls

change

private

8. Note

handle

gramps_id

text

format

type

change

tag_list

private

Secondary Objects

In addition, there are a number of secondary objects. In the DbBsddb implementation, these are stored in the primary objects. Typically, this means that DbBsddb objects are stored in pickled format. In the DbDjango implemetation, the secondary objects are additional tables.

The secondary objects include dates, addresses, and source references among other objects.

1. Name:

privacy

source_list

note_list

date

first_name

surname

suffix

title

name_type

prefix

patronymic

group_as

sort_as

display_as

call

2. Date

3. Address

privacy

source_list

note_list

date

location

4. LDS Ord

source_list

note_list

date

type

place

famc

temple

status

private

5. Source Reference

date

privacy

note_list

confidence

ref

page

Handles

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.

Object lifetime

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.

Database Objects

GRAMPS provides a standard interface for all database objects. The GRAMPS database object provides the interface to the lower level database. Currently, only one database interface is supported:

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
with DbTxn(_("Set Marker"), self.db, batch=True) as transaction
# 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)

UNDO

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:

database.undo()

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:

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:

Finding references

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.

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: