imip-agent

Annotated docs/wiki/DatabaseStore

1192:00d37da98920
1128:a0043845de02
1093:3ec032d69fc3
2016-04-19 Paul Boddie file changeset files shortlog Test changes in attendance for declined recurrences. 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 
}}}