imip-agent

Annotated docs/wiki/DatabaseStore

1192:00d37da98920
1122:2003934ef901
1093:3ec032d69fc3
2016-04-19 Paul Boddie file changeset files shortlog Support replies from attendees that refer to specific recurrences before the organiser does so, thus allowing attendees to selectively accept and decline recurrences. Allowed the test handler to refer to recurrences that have not been explicitly separated from their parent objects. Added a docstring for the Object initialiser as a reminder of how to use it. freebusy-collections
paul@1089 1 
= Database Store =
paul@1089 2 
 
 paul@1089      3 
The database data store offers a mechanism for storing calendar objects and free/busy
 
 paul@1089      4 
details in a database system, currently focusing on relational database systems, with
 
 paul@1089      5 
specific support for PostgreSQL.
 
 paul@1089      6 
 
 paul@1089      7 
Benefits of the database store include convenient and standardised interfaces for
 
 paul@1089      8 
querying and inspecting the data, together with various guarantees around the durability
 
 paul@1089      9 
of the stored data. However, more administrative knowledge is usually required to operate
 
 paul@1089     10 
database installations satisfactorily, and activities such as archiving require extra
 
 paul@1089     11 
planning and expertise.
 
 paul@1089     12 
 
 paul@1089     13 
The [[../FileStore|file store]] offers a more convenient method of managing calendar
 
 paul@1089     14 
data, albeit offering arguably less scalability and less convenience when data volumes
 
 paul@1089     15 
become significantly large.
 
 paul@1093     16 
 
 paul@1093     17 
== Configuration Settings ==
 
 paul@1093     18 
 
 paul@1093     19 
The [[../Configuration|configuration]] files (`config.sh` and `config.py`) need to be
 
 paul@1093     20 
updated when choosing a database store.
 
 paul@1093     21 
 
 paul@1093     22 
{{{#!table
 
 paul@1093     23 
'''File''' || '''Setting''' || '''Value''' || '''Description'''
 
 paul@1093     24 
==
 
 paul@1093     25 
`config.sh`
 
 paul@1093     26 
||<rowspan="2"> `STORE_TYPE`
 
 paul@1093     27 
||<rowspan="2"> `postgresql`
 
 paul@1093     28 
||<rowspan="2"> Selects a specific database store type; currently, only `postgresql`
 
 paul@1093     29 
             .. is supported
 
 paul@1093     30 
==
 
 paul@1093     31 
`config.py`
 
 paul@1093     32 
==
 
 paul@1093     33 
<rowspan="2"> `config.py`
 
 paul@1093     34 
|| `STORE_DIR`
 
 paul@1093     35 
|| `dbname=imip_agent`
 
 paul@1093     36 
|| Indicates a connection string for the store database
 
 paul@1093     37 
==
 
 paul@1093     38 
`JOURNAL_DIR`
 
 paul@1093     39 
|| `dbname=imip_agent`
 
 paul@1093     40 
|| Indicates a connection string for the journal database
 
 paul@1093     41 
}}}
 
 paul@1093     42 
 
 paul@1093     43 
== Journal Structure ==
 
 paul@1093     44 
 
 paul@1093     45 
The journal information is retained in a collection of tables. Unlike the structure of
 
 paul@1093     46 
the [[../FileStore|file store]] in the [[../FilesystemUsage|filesystem]], each table
 
 paul@1093     47 
contains details for all quota groups, with each query indicating the group to select
 
 paul@1093     48 
the appropriate information.
 
 paul@1093     49 
 
 paul@1093     50 
{{{#!table
 
 paul@1093     51 
'''Table''' || '''Purpose'''
 
 paul@1093     52 
==
 
 paul@1093     53 
`quota_freebusy`
 
 paul@1093     54 
|| Period descriptions describing reservations for resources sharing a quota (`quota`)
 
 paul@1093     55 
.. made by users or groups (`user_group`), structured similarly to the `freebusy` table
 
 paul@1093     56 
.. in the data store
 
 paul@1093     57 
==
 
 paul@1093     58 
`quota_limits`
 
 paul@1093     59 
|| A mapping from user identities or group identifiers to quota limits
 
 paul@1093     60 
==
 
 paul@1093     61 
`user_freebusy`
 
 paul@1093     62 
|| Period descriptions for reservations made in the context of a quota (`quota`) by a
 
 paul@1093     63 
.. specific user (`store_user`), structured similarly to the `freebusy` table in the
 
 paul@1093     64 
.. data store
 
 paul@1093     65 
==
 
 paul@1093     66 
`user_groups`
 
 paul@1093     67 
|| A mapping from user identities to group identifiers indicating the sharing of a quota
 
 paul@1093     68 
.. across a number of users
 
 paul@1093     69 
}}}
 
 paul@1093     70 
 
 paul@1093     71 
== Store Structure ==
 
 paul@1093     72 
 
 paul@1093     73 
The store information is retained in a collection of tables. Unlike the structure of
 
 paul@1093     74 
the [[../FileStore|file store]] in the [[../FilesystemUsage|filesystem]], each table
 
 paul@1093     75 
contains details for all users, with each query indicating the user to select
 
 paul@1093     76 
the appropriate information.
 
 paul@1093     77 
 
 paul@1093     78 
{{{#!table
 
 paul@1093     79 
'''Table''' || '''Purpose'''
 
 paul@1093     80 
==
 
 paul@1093     81 
`countered_objects`
 
 paul@1093     82 
|| Retains counter-proposals corresponding to events held in the `objects` table
 
 paul@1093     83 
.. received by each user (`store_user`) from another user (`other`)
 
 paul@1093     84 
==
 
 paul@1093     85 
`countered_recurrences`
 
 paul@1093     86 
|| Retains counter-proposals corresponding to events held in the `recurrences` table
 
 paul@1093     87 
.. received by each user (`store_user`) from another user (`other`)
 
 paul@1093     88 
==
 
 paul@1093     89 
`freebusy`
 
 paul@1093     90 
|| Period descriptions indicating start and end datetimes (in UTC), unique identifier
 
 paul@1093     91 
.. (`object_uid`), transparency, recurrence identifier (`object_recurrenceid`),
 
 paul@1093     92 
.. summary and organiser, reflecting the schedule of each user (`store_user`)
 
 paul@1093     93 
==
 
 paul@1093     94 
`freebusy_offers`
 
 paul@1093     95 
|| Period descriptions for scheduling offers made by counter-proposals sent by each
 
 paul@1093     96 
.. user (`store_user`)
 
 paul@1093     97 
==
 
 paul@1093     98 
`freebusy_other`
 
 paul@1093     99 
|| Period descriptions received or deduced for a user (`store_user`) structured
 
 paul@1093    100 
.. similarly to the user's own `freebusy` records
 
 paul@1093    101 
==
 
 paul@1093    102 
`freebusy_providers`
 
 paul@1093    103 
|| Details of [[../EventRecurrences|recurring events]] for which new free/busy records
 
 paul@1093    104 
.. must be [[../CronIntegration|periodically generated]] because these events recur
 
 paul@1093    105 
.. indefinitely, selectable for each user (`store_user`)
 
 paul@1093    106 
==
 
 paul@1093    107 
`freebusy_provider_datetimes`
 
 paul@1093    108 
|| Date/time details associated with the `freebusy_providers` information
 
 paul@1093    109 
==
 
 paul@1093    110 
`objects`
 
 paul@1093    111 
|| Records for each user (`store_data`) containing received event data (`object_text`)
 
 paul@1093    112 
==
 
 paul@1093    113 
`requests`
 
 paul@1093    114 
|| A collections of records, each belonging to a specific user (`store_user`)
 
 paul@1093    115 
.. consisting of a unique identifier (`object_uid`), normalised recurrence identifier
 
 paul@1093    116 
.. (`object_recurrenceid`) if appropriate, and (optionally) a scheduling method,
 
 paul@1093    117 
.. indicating the availability of an incoming scheduling request for handling by a user
 
 paul@1093    118 
==
 
 paul@1093    119 
`recurrences`
 
 paul@1093    120 
|| Records for each user (`store_data`) containing received recurrence event data
 
 paul@1093    121 
.. (`object_text`)
 
 paul@1093    122 
}}}