View of /trunk/webwork2/doc/new-DB-notes

    1 --------------------------------------------------------------------------------
    2 Notes on the new database system
    3 --------------------------------------------------------------------------------
    4 
    5 CHANGES IN THE ARCHITECTURE
    6 ---------------------------
    7 
    8 The architecture is now three-tier. For more information, consult the file doc/new-DB-architecture.
    9 
   10 CHANGES IN THE TABLE STRUCTURE
   11 ------------------------------
   12 
   13 PSVNs have been added to the set_user table, eliminating the need for a separate PSVN table.
   14 
   15 set_user and problem_user tables have been added, containing student-specific data. In most cases, the override fields (marked `!' above) will be empty. The dynamic fields (marked `~' above) will be populated as the student works through problems. problem_seed (in problem_user) and psvn(in set_user) are neither  dynamic or override fields -- they are set at assignment time.
   16 
   17 a problem_order field has been added to the set and set_user tables. It contains a definition of how the problems in each set will be ordered.
   18 
   19 RECORD CREATION DEPENDANCIES
   20 ----------------------------
   21 
   22     password -> user
   23   permission -> user
   24          key -> user
   25 	user -> 
   26          set -> 
   27     set_user -> user, set
   28      problem -> set
   29 problem_user -> set_user, problem
   30 
   31 TABLE STRUCTURE IMPLEMENTATION IN HASH-BASED DATABASES
   32 ------------------------------------------------------
   33 
   34 The WW2Hash schema module will implement a new hash-based schema for use with WeBWorK 2.
   35 
   36 Each table will be stored in a separate database file. Each table has either one or two fields that make up a unique identifier for each record. In the case of a one field identifier, the value of that field will be used as the record's key in the hash. In the case of a two-field identifier, the string "FIELD1:FIELD2" will be used. Literal colons will be escaped as `\:', and literal backslashes as `\\'.
   37 
   38 Rather than use a custom encoding scheme for the hash data, as is done in the 1.x implementation, a simple table-based scheme will be used, in which each field is separated by a colon (`:'). Literal colons (and literal backslashes) will be dealt with as above. This sort of scheme is common in the UNIX world. For example, consider the UNIX password file.
   39 
   40 COMPATABILITY WITH 1.X DATABASES
   41 --------------------------------
   42 
   43 By specifying the WW1Hash schema module for the appropriate tables, 1.x databases can be handled.
   44 
   45 Conversion of 1.x databases to 2.x databases can be achieved by using the most popular value for each field in each user-specific record as the global value, and merging PSVNs from the separate PSVN table. Conversion from 2.x databases to 1.x databases is trivial, if somewhat lossy (i.e. problem_order).
   46 
   47 TREATMENT OF THE CURRENT API
   48 ----------------------------
   49 
   50 The current API (implemented by Auth.pm, Classlist.pm, and WW.pm) will be removed. The code base is currently small enough that it will be easy to migrate existing code to the new API.
   51 
   52 NEW API FUNCTIONS
   53 -----------------
   54 
   55 The new API is outlined in the file doc/new-DB-API.