915
edits
Changes
→Primary Objects
{{man warn|If you are a looking for documentation on how to use the GRAMPS Gramps system as a user instead of as a program developer, it can be found on the [[Portal:Using_GRAMPSUsing_Gramps|GRAMPS Gramps documentation web page]].}}
Explanation of the basics, underlying GRAMPS Gramps database. This is not intended to be a reference manual, but an introductory programmer's guide to using the GRAMPS Gramps database access routines.
Separate [http://www.gramps-project.org/docs/ API Reference Documentation for version 34.30.0 x of GRAMPSGramps] and simple [[Media:API.svg|UML (svg) for 3.4.x]] are available.
== Database API ==
The full database hierarchy is:
* '''DbBsddb''' - read and write implementation to BSDDB databases ([http://grampssvn.svncode.sourceforgesf.net/viewvcp/gramps/code/trunk/srcgramps/gen/db/write.py?view=markup gen/db/write.py])** '''DbWriteBase''' - virtual and implementation-independent methods for reading data ([http://grampssvn.svncode.sourceforgesf.net/viewvcp/gramps/code/trunk/srcgramps/gen/db/base.py?view=markup gen/db/base.py])** '''DbBsddbRead''' - read-only (accessors, getters) implementation to BSDDB databases ([http://grampssvn.svncode.sourceforgesf.net/viewvcp/gramps/code/trunk/srcgramps/gen/db/read.py?view=markup gen/db/read.py])*** '''DbReadBase''' - virtual and implementation-independent methods for reading data ([http://grampssvn.svncode.sourceforgesf.net/viewvcp/gramps/code/trunk/srcgramps/gen/db/base.py?view=markup gen/db/base.py])*** '''Callback''' - callback and signal functions ([http://grampssvn.svncode.sourceforgesf.net/viewvcp/gramps/code/trunk/srcgramps/gen/utils/callback.py?view=markup gen/utils/callback.py])** '''UpdateCallback''' - callback functionality ([http://grampssvn.svncode.sourceforgesf.net/viewvcp/gramps/code/trunk/srcgramps/gen/db/readupdatecallback.py?view=markup gen/updatecallback.py])** '''DbTxn''' - class for managing Gramps transactions and the undo database ([http://grampssvn.svncode.sourceforgesf.net/viewvcp/gramps/code/trunk/srcgramps/gen/db/txn.py??view=markup gen/bddb/txn.py])* '''DbDjango''' - read and write implementation to Django-based databases ([http://grampssvn.svncode.sourceforgesf.net/viewvcp/gramps/code/trunk/srcgramps/webwebapp/dbdjango.py?view=markup webwebapp/dbdjango.py])** '''DbWriteBase''' - virtual and implementation-independent methods for reading data ([http://grampssvn.svncode.sourceforgesf.net/viewvcp/gramps/code/trunk/srcgramps/gen/db/base.py?view=markup gen/db/base.py])** '''DbReadBase''' - virtual and implementation-independent methods for reading data ([http://grampssvn.svncode.sourceforgesf.net/viewvcp/gramps/code/trunk/srcgramps/gen/db/base.py?view=markup gen/db/base.py])
=== DbBsddb ===
The DbDjango interface defines the Gramps data in terms of ''models'' and ''relations'' from the [http://www.djangoproject.com/ 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).
For more details on the Gramps Django project, see [[GEPS 013: GRAMPS Gramps Webapp]].
=== Using the Database ===
==Primary Objects==
Primary objects are the fundamental objects in the GRAMPS Gramps database. These objects are:* [http://www.gramps-project.org/docs/gen/gen_lib.html#module-gramps.gen.lib.person Person] - Contains the information specific to an individual person.* [http://www.gramps-project.org/docs/gen/gen_lib.html#module-gramps.gen.lib.family Family] - Contains the information specific to relationships between people. This typically contains one or two parents and zero or more children.* [http://www.gramps-project.org/docs/gen/gen_lib.html#module-gramps.gen.lib.event 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.* [http://www.gramps-project.org/docs/gen/gen_lib.html#module-gramps.gen.lib.place Place] - Contains the information related to a specific place.* [http://www.gramps-project.org/docs/gen/gen_lib.html#module-gramps.gen.lib.src Sourcerepo Repository] - Contains the information related to a source of informationrepository.* Citation [http://www.gramps-project.org/docs/gen/gen_lib.html#module-gramps.gen.lib.src Source] - Contains the information related to a citation into a sourceof information.* [http://www.gramps-project.org/docs/gen/gen_lib.html#module-gramps.gen.lib.mediaobj Media Objectcitation Citation] - Contains the information related to a media object. This includes images, documents, or any other type of related filescitation into a source.* [http://www.gramps-project.org/docs/gen/gen_lib.html#module-gramps.gen.lib.repo Repositorymediaobj Media Object] - Contains the information related to a repositorymedia object. This includes images, documents, or any other type of related files.* [http://www.gramps-project.org/docs/gen/gen_lib.html#module-gramps.gen.lib.note Note] - Contains the information related to a note.
# urls
# lds_ord_list
# source_listcitation_list
# note_list
# change
# attribute_list
# lds_seal_list
# source_listcitation_list
# note_list
# change
# handle
# gramps_id
# the_typetype
# date
# description
# place
# source_listcitation_list
# note_list
# media_list
# attribute_list
# change
# tag_list
# private
# gramps_id
# title
# long(longitude)# lat(latitude)# main_locplaceref_list# alt_locname# alt_names# place_type# code# urlsalt_loc (deprecated)
# media_list
# source_listcitation_list
# note_list
# change
# tag_list
# private
# title
# author
# pubinfo(publication information)
# note_list
# media_list
# abbrev(abbreviation)
# change
# datamapattribute_list
# reporef_list
# tag_list
# private
# handle
# gramps_id
===7. Media:===
# path
# mime
# desc(description)# checksum
# attribute_list
# source_listcitation_list
# note_list
# change
# gramps_id
# type
# name
# note_list
# address_list
# urls
# 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 [httphttps://wwwdocs.python.org/doc/current3.4/liblibrary/module-pickle.html pickled] format. In the DbDjango implemetation, the secondary objects are additional tables.
The secondary objects include dates, addresses, and source references among other objects.
==Database Objects==
* GrampsBSDDB - the default database, providing access to a Berkeley DB database.
===Transactions and Commits===
In order to support an UNDO feature, the database has the concept of [httphttps://gramps-project.org/docs/gen/gen_db.html#bsddbmodule-gramps.gen.db.txn 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.
===Iterating through the database===
Frequently, it is useful to iterate through all the elements of a database. GRAMPS 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 [httphttps://www.gramps-project.org/devdocdocs/apigen/2gen_db.2/private/GrampsDbhtml#module-gramps._GrampsDbBasegen.GrampsCursor-classdb.html cursor 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()
===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 Gramps and your widget must show these changes. The GRAMPS 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 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)
