API: Issue Opening Databases in Gramps 5


Several years ago I wrote a lengthy script to access Gramps data and generate custom reports. This script runs external to Gramps, importing Gramps modules from /usr/lib/.

After upgrading to Gramps version 5, my script is no longer able to open databases. The Gramps API documentation is very thorough when it comes to reading data from objects in the db, but it offers few clues on how to open the database itself. Sadly, I had to rely on some “cargo cult” code I found on Stack Exchange:

btspierre’s method worked great in previous versions, but unfortunately it doe does not work in version 5 and returns the following error:

ImportError: cannot import name ‘DbBsddb’ from ‘gramps.gen.db’ (/usr/lib/python3/dist-packages/gramps/gen/db/init.py)

From perusing the Gramps source code, It seems that DbState and DbBsddb are structured differently in the new version. Can someone offer some advice on how to externally open a Gramps Database in version 5?

Best Regards,


The 1st question is if you upgraded to a 5.1.x version & imported the old file?

There was a major change in version 5.0.x to support multiple DB backends.

And with version 5.1.x, it defaults to the to SQLite backend instead of the BSDDB.

You might (might!) be able to reset the database backend to BSDDB, create a new Tree, re-import to create a BSDDB file. Your custom-built external tool might be able to access again.

(Although if you have the skill to built a report manually, maybe you might want to use the Report API to do the same report from within Gramps.)


Thank you Brian.

Per your suggestion I updated to 5.1.2. but I have had no luck accessing either SQLite or BSDDB databases in either 5.1.2 or 5.0.1.

The problem seems to be that the boilerplate code I am using to open a database is not usable in any version 5.x.x regardless of db type. Is there any documentation or examples available of how to open a database in version 5? Or is there a well-documented way to launch my script from within Gramps on a db that is already open?

The report I generate is a CSV file which gets processed downstream, so unfortunately it isn’t well suited for the Report API.

Best Regards,


You could use the experimental mongoDB backend… there everything is stored as json(bson) object, and can access the data with normal mongodb queries…

Just a suggestion if you need external access today…

And if you want to, you could set up a neo4j connector and create neo4j graphs… the sky and beyong is the limit…

As a workaround, you could also download the previous version before the overhaul of the DB api

Gramps 4.2.8: for Mac, Windows, Debian. Or build from source

The development docs can be found here.

There is already a CSV export option in Gramps. Assuming it cannot be configured to output a useable file for your purposes, it is still a broad template for all the access & file writing features in 5.1 compatible plug-in code.

It is in the plugins export subfolder of the Gramps installation folder for your OS. (On my Win10 box, it is in c:\Program Files\GrampsAIO64-5.1.2\plugins\export ). The export.gpr.py registers the multitude of Export related Python ( .py ) modules in the plug-in API.

Modifying the original is NOT recommended. It could be overwritten during an update and your modifications would be lost.

Instead, manually add your modified copy (with a unique name, fname & id) to a new subfolder of the plugins folder stored under your User Directory.

Examine the files in other subfolders of that plug-in folder (like the ExportRaw/ExportRaw.gpr.py ) to see the slight differences from the 'built-in" Gramps Plugin Registration ( .gpr.py ) file when registering 3rd Party add-ons.

You now need to use the make_database utility function.

from gramps.gen.db.utils import make_database
db = make_database('bsddb')

For existing databases the database type is stored in a text file.


Gramps allows addons of many types to be created. And many have been. They all access the database to perform some function or other. I suggest you look at the code in https://github.com/gramps-project/addons-source at an addon that generates some sort of report. If you wan to use Gramps internal report generating code, it will have examples, even if you are satisfied with writing out what you want directly to your own file, it will have what is needed to access the db. If you make up your own .gpr.py file (based on examples) along with the report code, it can reside in your own local addons directory.
Note the branch dropdown, you need to look at code for the main version of Gramps you are targeting. Usually the changes are not too different between versions, but there are usually some.


Thank you all! Nick-Hall’s reply put me on the right track, and I have brought my script back from the dead. The code I ended up using to replace the StackExchange example is:

from gramps.gen.dbstate import DbState
dbstate = DbState()
from gramps.gen.db.utils import make_database
db = make_database('sqlite')

Ultimately I will eventually re-factor my code to work as an add-on or similar.

Also, I am very impressed community here, and I’d kinda like to dip my toe into contributing as a developer.


This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.