sql/4_1_0-to-4_2_0_upgrade.sql

   1 --
   2 --  Comment Meta Language for sql upgrades:
   3 --
   4 --  Each section within an upgrade sql file is enveloped with an #If*/#EndIf block.  At first glance, these appear to be standard mysql
   5 --  comments meant to be cryptic hints to -other developers about the sql goodness contained therein.  However, were you to rely on such basic premises,
   6 --  you would find yourself grossly decieved.  Indeed, without the knowledge that these comments are, in fact a sneakily embedded meta langauge derived
   7 --  for a purpose none-other than to aid in the protection of the database during upgrades,  you would no doubt be subject to much ridicule and public
   8 --  beratement at the hands of the very developers who envisioned such a crafty use of comments. -jwallace
   9 --
  10 --  While these lines are as enigmatic as they are functional, there is a method to the madness.  Let's take a moment to briefly go over proper comment meta language use.
  11 --
  12 --  The #If* sections have the behavior of functions and come complete with arguments supplied command-line style
  13 --
  14 --  Your Comment meta language lines cannot contain any other comment styles such as the nefarious double dashes "--" lest your lines be skipped and
  15 --  the blocks automatcially executed with out regard to the existing database state.
  16 --
  17 --  Comment Meta Language Constructs:
  18 --
  19 --  #IfNotTable
  20 --    argument: table_name
  21 --    behavior: if the table_name does not exist,  the block will be executed
  22
  23 --  #IfTable
  24 --    argument: table_name
  25 --    behavior: if the table_name does exist, the block will be executed
  26
  27 --  #IfMissingColumn
  28 --    arguments: table_name colname
  29 --    behavior:  if the colname in the table_name table does not exist,  the block will be executed
  30
  31 --  #IfNotColumnType
  32 --    arguments: table_name colname value
  33 --    behavior:  If the table table_name does not have a column colname with a data type equal to value, then the block will be executed
  34
  35 --  #IfNotRow
  36 --    arguments: table_name colname value
  37 --    behavior:  If the table table_name does not have a row where colname = value, the block will be executed.
  38
  39 --  #IfNotRow2D
  40 --    arguments: table_name colname value colname2 value2
  41 --    behavior:  If the table table_name does not have a row where colname = value AND colname2 = value2, the block will be executed.
  42
  43 --  #IfNotRow3D
  44 --    arguments: table_name colname value colname2 value2 colname3 value3
  45 --    behavior:  If the table table_name does not have a row where colname = value AND colname2 = value2 AND colname3 = value3, the block will be executed.
  46
  47 --  #IfNotRow4D
  48 --    arguments: table_name colname value colname2 value2 colname3 value3 colname4 value4
  49 --    behavior:  If the table table_name does not have a row where colname = value AND colname2 = value2 AND colname3 = value3 AND colname4 = value4, the block will be executed.
  50
  51 --  #IfNotRow2Dx2
  52 --    desc:      This is a very specialized function to allow adding items to the list_options table to avoid both redundant option_id and title in each element.
  53 --    arguments: table_name colname value colname2 value2 colname3 value3
  54 --    behavior:  The block will be executed if both statements below are true:
  55 --               1) The table table_name does not have a row where colname = value AND colname2 = value2.
  56 --               2) The table table_name does not have a row where colname = value AND colname3 = value3.
  57
  58 --  #EndIf
  59 --    all blocks are terminated with and #EndIf statement.
  60