bin/PREUPGRADE_FOR_1_1_X_README

   1 This directory contains utility to convert BDB JE data between different versions of Voldemort.
   2
   3 Need for Conversion
   4 -------------------
   5 Voldemort has been using "sorted duplicates" feature of BDB JE to handle
   6 conflicting writes to the same key. At the very minimum, the conversion gets
   7 rid of BDB sorted duplicates support and handles duplicates in the Voldemort
   8 storage layer itself. The decision was made after months of closely working
   9 with Oracle JE team, to understand the factors affecting performance.
  10
  11 Data Formats
  12 ------------
  13 This section describes the data formats themselves.
  14
  15 1) Base Format (Base)
  16 ---------------------
  17 This is the format used by Voldemort up until 1.1.x, relying on BDB JE for
  18 duplicate handling
  19
  20 Disadvantages:
  21 -- The manner in which BDB JE handles duplicates is not suitable for an
  22    application with small percent of 2-3 duplicates i.e Voldemort.
  23 -- Data bloat issue that prevented us from migrating to any higher 4.x version
  24    to be able to control cache eviction
  25 -- Incompatible with how duplicates are handled in JE5.
  26 -- May incur additional locking costs for the "duplicates" subtree
  27
  28 2) New duplicate format (NewDup)
  29 --------------------------------
  30 This format is supported from release 1.1.x, where Voldemort storage layer
  31 handles duplicates and BDB JE version is bumped up to JE 4.1.17
  32
  33 Advantages:
  34 -- Ability to move data off disk. This is very GC friendly, relying on OS page
  35    cache for the data and using the JVM heap only for index. This is achieved
  36    by setting "bdb.cache.evictln" server parameter to "true"
  37 -- Ability to evict data brought into the cache during scans, minimize impact
  38    on online traffic (Restore, Rebalance, Retention). This is achieved by
  39    setting "bdb.minimize.scan.impact" to "true"
  40 -- Thinner storage layer. eg: BdbStorageEngine.put() does not incur the cost
  41    of an additional delete()
  42 -- General speed up due to elimination of duplicates
  43
  44 This format is the minimum requirement to be able to upgrade to 1.1.x & higher
  45
  46 3) Partition Scan format (PidScan)
  47 ----------------------------------
  48 This is a super set of 'NewDup' format, supported 1.1.x upwards. In addition to
  49 eliminating duplicates and upgrading to JE 4.1.17, it adds a 2 byte prefix
  50 representing the partition id to each key.
  51
  52 Advantages:
  53 -- Speed up Restore and Rebalancing linearly to the number of partitions
  54    actually fetched. (which means much shorter degraded mode performance)
  55
  56 This is an optional format. You can turn it off, by setting
  57 bdb.prefix.keys.with.partitionid=false, if you don't like for some reason
  58
  59 Note : We have not seen the extra 2 bytes cause any overhead to online
  60 performance
  61
  62 IMPORTANT: IT IS REQUIRED TO CONVERT TO EITHER 'NewDup' or 'PidScan' TO RUN
  63 VOLDEMORT WITH BDB, STARTING RELEASE 1.1.x
  64
  65 Running the Conversion Utility
  66 ------------------------------
  67 The tool provides the ability to convert one database from a source environment
  68 to a destination environment. You need to run the tool for each of the databases
  69 or voldemort store you have. You can bring one Voldemort server at a time and
  70 perform the conversion and bring it up on the appropriate release
  71
  72 Note: For users running with "bdb.one.env.per.store=false", it means you will
  73 have to run the tool with the same --src --dest options for each database
  74 contained.
  75
  76 In addition to BDB environment locations, the tool needs the cluster.xml to generate
  77 the partition prefix.
  78
  79 $./voldemort-convert-bdb.sh --src   <Required: Path to source bdb environment>
  80                       --dest  <Required: Path to place converted new environment>
  81                       --store <Required: BDB database (voldemort store) name>
  82                       --cluster-xml <Required: Path to cluster.xml>
  83                       --from-format  <Required: Format to convert FROM, one of the 3
  84                                       strings 'Base','NewDup','PidScan'>
  85                       --to-format    <Required: Format to convert TO, one of the 3
  86                                       strings 'Base','NewDup','PidScan'>
  87                       --je-log-size <Optional: Size in MB for the new JE log files,
  88                                     Default:60>
  89                       --btree-nodemax <Optional: Btree fan out, Default: 512>
  90
  91 We recommend you run the following to move to release 1.1.x & up.
  92
  93 $./voldemort-convert-bdb.sh --src   /path/to/src/env
  94                       --dest  /path/to/dest/env
  95                       --store teststore
  96                       --cluster-xml /path/to/cluster/xml
  97                       --from-format  Base
  98                       --to-format    PidScan
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110