doc/README.development

   1 == Pickle Failures ==
   2
   3 Our schemas are "best guesses" based on what we've seen on the
   4 wire. From time to time they'll be wrong, and thus the (un)pickler
   5 implementation will fail to unpickle some XML document. The easiest
   6 way to test a fix for this is interactively: it's quick, and error
   7 messages are written to the console. Here's an example of such a
   8 session (wrapped for readability):
   9
  10   $ ghci
  11   htsn-import> runX $ xunpickleDocument
  12                       TSN.XML.AutoRacingResults.pickle_message
  13                       parse_opts
  14                       "schemagen/AutoRacingResultsXML/21241892.xml"
  15   [Message {xml_xml_file_id = 21241892... stamp = 2014-06-08 04:05:00 UTC}]
  16
  17 If there's an error, you'll see something like the following:
  18
  19   $ ghci
  20   htsn-import> runX $ xunpickleDocument
  21                       TSN.XML.AutoRacingResults.pickle_message
  22                       parse_opts
  23                       "schemagen/AutoRacingResultsXML/21241892-bad.xml"
  24   fatal error: document unpickling failed
  25   xpElem: got element name "RaceDate", but expected "RaceID"
  26   context:    element "message"
  27   contents:   <Title>IRL - Firestone 600 - Final Results</Title><Track_Location>
  28   Texas Motor Sp...
  29   []
  30
  31
  32 == Creating the Database Schema (Deployment) ==
  33
  34 When deploying for the first time, the target database will most
  35 likely be empty. The schema will be migrated when a new document type
  36 is seen, but this has a downside: it can be months before every
  37 supported document type has been seen once. This can make it difficult
  38 to test the database permissions.
  39
  40 Since all of the test XML documents have old timestamps, one easy
  41 workaround is the following: simply import all of the test XML
  42 documents, and then delete them. This will force the migration of the
  43 schema, after which you can set and test the database permissions.
  44
  45 Something as simple as,
  46
  47   $ find ./test/xml -iname '*.xml' | xargs htsn-import -c foo.sqlite
  48
  49 should do it.