Explanation of the basics, 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.
Separate API Reference Documentation for version 5.0.x of Gramps and as well as a simple UML (svg) diagram for 4.1.x and Gramps Data Model overview are available.
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 2.x tutorial or Python 3.x tutorial.
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.
The full database hierarchy is:
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).
The DB-API interface uses a generic interface backed with the general Python SQL implementation, called DB-API. The Gramps' generic interface (gramps.gen.db.generic.DbGeneric) has all of the logic for interacting with the database, except for the specific DB access code. Gramps' DB-API (gramps.plugins.db.dbapi.dbapi) implements the details so as to talk to conforming SQL databases. Other database engines could also implement the DbGeneric details, such as a nosql option.
By default, Gramps DB-API uses sqlite. However, you can also configure DB-API to use mysql, postgresql, and perhaps others.
To be compatible with BSDDB, DB-API stores Gramps data in an identical manner (pickled tuples). However, to allow for fast access, DB-API also stores "flat" data (such as strings and integers) in secondary SQL fields. These are indexed so that data can be selected without having to traverse, unpickle, initialize objects, and compare properties.
For most cases, Gramps will have already opened a database for you. This is often embedded in a DbState object. Thus, you might interface the database like:
>>> dbstate.db.get_person_from_gramps_id("I0001")
However, to do any database activity, you need to understand the primary objects.
Primary objects are the fundamental objects in the Gramps database. These objects are: