update the docs

git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@4581 57a11ea4-9604-0410-9ed3-97b8803252fd

src/engine/sql/README

@@ -130,17 +130,34 @@ password, *NOT* your unix login name and password.
 
 Access Modes
 ------------
-There are three different ways or 'modes' in which to access your 
+There are four different ways or 'modes' in which to access your 
 database.  These are 
 
 mode=single-file
 mode=single-update
+mode=multi-user-poll
 mode=multi-user
 
-The first two are single-user access modes; single-update is the 
-default mode (and the preferred single-user mode).
+The first two are single-user access modes.  These are the
+'safest' modes to use if you don't need multi-user capability.
+The single-update mode is strongly preffered over single-file.
+(single-file can loose your data if your sql connection dies
+at unexpected times).
+
+The multi-user modes are intended for use when multiple users
+need to view and make changes to the data.  The default mode
+is multi-user.  
+
+If you have many users (more than a helf-dozen or so), you may 
+want to run in multi-user-poll mode, instead of the default 
+multi-user.  This will stop the automatic updates of the 
+local instance of gnucash, and thus reduce the amount of
+GUI redraws that happen automatically as other users
+edit data.  It should also reduce network traffic
+slightly, and present a slightly lower load on the 
+sql server.  Different users can mix-n-match the
+two multi-user modes. 
 
-The multi-user mode is mostly implemented and might be usable.
 See the file 'design.txt' for an in-depth explanation of these 
 modes.
 
@@ -269,19 +286,15 @@ To Be Done, Part II
 -------------------
 This list only affects the multi-user and advanced/optional features.
 
-Most of the items on this list are 'critical' in the sense that
-multi-user mode is fundamentally broken unless they are fixed. 
-
--- before going beta: turn down debugging.  
+Most of the items on this list are 'good-to-fix' but are not
+truly critical.  They may result in abberations, but general
+operation is probably OK.
 
 -- if always in multi-mode, then initial checkpoints not set up.
    They're not needed until there are a lot of transactions in the 
    system.  Need to recompute checkpoints on some periodic basis.
 
--- we should use LISTEN/NOTIFY to let others know tht things have 
-   changed.  This is of limited utility, but still...
-   It could be used to update the balances in the main window 
-   dynamically.
+-- NOTIFY is not updating main window balances ...
 
 -- during sync, detect and report conflicting edits to accounts 
    and transactions.  See the notes for pgendSync() for details

src/engine/sql/design.txt

@@ -4,6 +4,22 @@ SQL Tables
 These mostly parallel the data structures in the gnc engine.
 See table-create.sql for more info.
 
+General Theory of Operation
+---------------------------
+The entire backend is built upon the premise that the local
+gnucash process acts only as a 'cache' of (some of) the
+'true' data in a remote SQL database.  The motivation of 
+this design is to allow the local process to quickly access
+and manipulate data (because it is local), without loosing
+the benefits of a remote, shared, persisitant storage 
+server (the sql database).  If the code seems complex,
+that is because it is expending a considerable amount of
+effort in trying to maintain the local cache consistent
+with the remote store.  In the following text (and in the 
+notes in the source code), "the engine" is used as a 
+sysnonym for "the cache", and always refers to the 
+local data running in the local process.
+
 
 Session Table, Session Modes
 ----------------------------
@@ -39,35 +55,89 @@ indicates which mode the database is functioning.
    mode=single-update
    Only one user can have access to the database at a time.  Updates 
    to data are stored in the DB as they are made in the GUI; there
-   is no need to perform a mass-save at the end of a session.
+   is no need to perform a mass-save at the end of a session.  
+
+   When a database is opened in this mode, *all* of the database
+   data is copied from the database into the local engine.  This
+   might result in the gnucash process getting quite large, 
+   especially if the database is large.
 
    This mode is more robust in that there is minimal/no data loss in 
-   the event of a crash.
+   the event of a crash.  If the database needs to be accessed in
+   single-user mode, this is teh preffered mode to use.
 
 -- "Multi-User Polled" -- 
-   mode=multi-user
+   mode=multi-user-poll
    Multiple users are assumed, GnuCash polls the database to detect 
-   changes in the data.  Mostly implemented. 
-
+   changes in the data.   Data storage is incremental, essentially
+   the same as in the single-update mode.  Data fetch is also
+   incremental: only the data that is immediately being viewed/edited
+   is pulled into the local engine.  The idea is that the SQL database
+   may be quite large, but that only some smaller amount of data will
+   be viewed/edited by a user at any given time.  Thus, we save 
+   on network traffic and local memory usage by only pulling in 
+   the data that we need. Note that 'old' data is not purged, so
+   if a gnucash session runs for a long time in this mode, it may
+   pull in significant amounts of the dataset, and thus grow quite 
+   large.
+
+   Multiple users may simultaneously edit the data in this mode.
+   However, in this mode, changes made by remote users do not
+   'automatically' show up as they are made.  To see other users
+   changes, one has to (for example) close a register window, and
+   reopen it.  The local cache of data is synced with the remote
+   database on an as-needed basis:  for example, if the local
+   user tries to edit the same transaction that some remote user
+   has modified, then the local copy of transaction will be updated, 
+   and the user warned that a remote change has occured. 
+
+-- "Multi-User Events" (Default Mode) --
+   mode=multi-user
+   Multiple sers are assumed.  This mode works essentially the
+   same way as the multi-user-poll mode, except that (asynchronous) 
+   events are delivered to the local process when remote users 
+   make changes.  This will cause the local GUI display to automatically
+   update when remote users make changes.  (In the current design,
+   there is a 10 second delay between updates).
 
--- "Multi-User Events" --
-   mode=multi-user-event
-   GnuCash uses the SQL LISTEN/NOTIFY async message delivery routines.
-   Not implemented.  Probably won't be.  These messages do not provide 
-   a sufficient level of detail needed for the kind of notification that 
-   would be useful to gnucash.  Ideally, we would like to have notification 
-   when some other process has modified a particular record.  But there
-   is no way to indicate which record was modified: the local process
-   would have to query all records its interested in, thus providing no
-   better performance than mere polling.
+   This automatic update puts slightly more burden on the local
+   process, on the network, and on the SQL server.  Thus, it won't
+   scale well with lots of users.   We don't know where that limit
+   is; we are guessing its somewhere between 5 and 20 simultaneous 
+   users.  Depends on the power of the DB server, of course.
 
 
 Safety Lockout
 --------------
-There is a safety lockout that prevents a single-user mode database from
-being accessed by another user, and from having a multi-user mode 
-database from being accessed by a single-user-mode client.
+There is a safety lockout that prevents a database that is 
+currently open in single-user mode from being opened by a 
+second user at the same time.  Similarly, a database that
+is currently open in multi-user mode cannot be opened in
+single-user mode.
+
+Note, however, that swithcing modes after all users have
+logged off is perfectly safe:  If all the multi-users
+log off, then the database can be opened in single-user mode
+(and vice-versa).  Logoff happens 'automatically' when 
+a user exits gnucash.
+
+If gnucash dies or is killed, a user might be left logged
+on.  If it dies in multi-user mode, it may seem that many
+users are still logged on; this will prevent the database
+from subsequently being opened in single-user mode.
+
+To force a log-off, you can issue the following command:
+
+echo "UPDATE gncsession SET time_off='NOW' WHERE time_off = 'infinity';" | psql dbname
+
+Just be sure that all users really are logged off when
+you do this.
+
 
+gncSession Table
+----------------
+Shows logon, logoff time, login name and the users 'true name',
+and the FQDN hostname.
 
 Session Design Notes
 --------------------