Changes

Jump to: navigation, search

Using database API

4,500 bytes added, 21:15, 16 July 2021
m
grammar
{{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 [httphttps://www.gramps-project.org/docs/ API Reference Documentation for current version 3of Gramps] and as well as a simple [[Media:API.svg|UML (svg) diagram for 4.21.0 of GRAMPSx]] and [[Gramps Data Model]] is overview are available.
GRAMPS Gramps is written in the [http://www.python.org 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 [httphttps://docs.python.org/tut2/tutorial/ Python 2.x tutorial] or [https://tutdocs.python.html org/3/tutorial/ Python 3.x 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. The full database hierarchy is: * '''DbBsddb''' - read and write implementation to BSDDB databases ([http://sourceforge.net/p/gramps/source/ci/master/tree/gramps/gen/db/write.py gen/db/write.py])** '''DbWriteBase''' - virtual and implementation-independent methods for reading data ([http://sourceforge.net/p/gramps/source/ci/master/tree/gramps/gen/db//base.py gen/db/base.py])** '''DbBsddbRead''' - read-only (accessors, getters) implementation to BSDDB databases ([http://sourceforge.net/p/gramps/source/ci/master/tree/gramps/gen/db/read.py gen/db/read.py])*** '''DbReadBase''' - virtual and implementation-independent methods for reading data ([http://sourceforge.net/p/gramps/source/ci/master/tree/gramps/gen/db/base.py gen/db/base.py])*** '''Callback''' - callback and signal functions ([http://sourceforge.net/p/gramps/source/ci/master/tree/gramps/gen/utils/callback.py gen/utils/callback.py])** '''UpdateCallback''' - callback functionality ([http://sourceforge.net/p/gramps/source/ci/master/tree/gramps/gen/updatecallback.py gen/updatecallback.py])** '''DbTxn''' - class for managing Gramps transactions and the undo database ([http://sourceforge.net/p/gramps/source/ci/master/tree/gramps/gen/db/txn.py gen/db/txn.py])* '''DbGeneric''' - general read and write implementations** '''DbWriteBase''' - virtual and implementation-independent methods for reading data ([http://sourceforge.net/p/gramps/source/ci/master/tree/gramps/gen/db/base.py gen/db/base.py])** '''DbReadBase''' - virtual and implementation-independent methods for reading data ([http://sourceforge.net/p/gramps/source/ci/master/tree/gramps/gen/db//base.py gen/db/base.py]) === DbBsddb === The DbBsddb interface defines a hierarchical database (non-relational) written in [http://www.jcea.es/programacion/pybsddb.htm 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 [[Using_database_API#Primary_Objects|primary data types (below)]]. === DB-API === The DB-API interface uses a generic interface backed with the general Python SQL implementation, called [https://www.python.org/dev/peps/pep-0249/ 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. === Using the Database === 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==
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.repo Repository] - Contains the information related to a repository.* [http://www.gramps-project.org/docs/gen/gen_lib.html#module-gramps.gen.lib.src Source] - Contains the information related to a source of 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.
Primary objects are treated as tables within the database. Individual components that compose the primary object are stored as individual items in the database.
===Database Structure===
====1. Person:====
# handle
# gramps_id
# urls
# lds_ord_list
# source_listcitation_list
# note_list
# change
# markertag_list
# private
# person_ref_list
====2. Family:====
# handle
# gramps_id
# attribute_list
# lds_seal_list
# source_listcitation_list# note_list# change# tag_list# private ===3. Event:===# handle# gramps_id# type# date# description# place# citation_list# note_list# media_list# attribute_list# change# tag_list# private ===4. Place:===# handle# gramps_id# title# long (longitude)# lat (latitude)# placeref_list# name# alt_names# place_type# code# alt_loc (deprecated)# media_list# citation_list
# note_list
# change
# markertag_list
# private
====35. Source:====
# handle
# gramps_id
# title
# author
# pubinfo(publication information)
# note_list
# media_list
# abbrev(abbreviation)
# change
# datamapattribute_list
# reporef_list
# markertag_list
# private
====46. PlaceCitation:====
# handle
# gramps_id
# titledate# longpage# latconfidence# main_locsource_handle# alt_loc# urlsnote_list
# media_list
# source_list# note_listattribute_list
# change
# markertag_list
# private
====57. Media:====
# handle
# gramps_id
# path
# mime
# desc(description)# checksum
# attribute_list
# source_listcitation_list
# note_list
# change
# date
# markertag_list
# private
====68. Event:=Repository===
# handle
# gramps_id
# the_typetype# date# description# place# source_listname
# note_list
# media_listaddress_list# attribute_listurls# change# tag_list# private ===9. Note===# handle# gramps_id# text# format# type
# change
# markertag_list
# private
==Secondary Objects ==7 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 [https://docs.python.org/3.4/library/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. ===1. Name:====
# privacy
# source_list
# call
===2. Date===8 ===3. Address====
# privacy
# source_list
# location
====94. LDS Ord====
# source_list
# note_list
# private
====10. 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.
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 Gramps ID value should be used for this purpose. The GRAMPS 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 Gramps ID without affecting the database.
Once created, the handle should never be modified.
person1.set_nickname('Fred')
</pre>
In this case, even though person1 and person2 represent the same person, but they 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 Database Objects==Secondary objects are objects that are contained within primary Gramps provides a standard interface for all database objects. These objects include dates, addresses, and source references among other objects. Secondary objects are treated as a single unit within The Gramps database object provides the interface to the lower level database. TypicallyCurrently, this means that the objects are stored in [httponly one database interface is supported://www.python.org/doc/current/lib/module-pickle.html pickled] format.
==Database Objects==
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 [httphttps://www.gramps-project.org/devdocdocs/apigen/2gen_db.2/private/GrampsDbhtml#module-gramps._GrampsDbBasegen.Transaction-classdb.html 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.
# begin transaction
transaction with DbTxn(_("Set Marker"), self.db, batch= database.transaction_begin(True)as transaction
# Create new family, add it to the database. The add_family
database.commit_person(mother, transaction)
database.commit_family(father, transaction)
 
# finish the transaction
database.transaction_commit(transaction, "Add family")
</pre>
===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)
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 <tt>[https://gramps-project.org/docs/gen/gen_db.html#module-gramps.gen.db.base GrampsDbBase]</tt> class in the <tt>GrampsDbBase[https://github.com/gramps-project/gramps/blob/master/gramps/gen/db/base.py gramps/gen/db/base.py]</tt> module.
[[Category:Developers/Tutorials]]
[[Category:Developers/General]]
[[Category:Reports|A]]
[[Category:Plugins|A]]
[[Category:Tools|A]]
[[Category:Gramplets|A]]
[[Category:Views|A]]

Navigation menu