Upgrading from Phoenix 2.2.x

By default, Phoenix 2.2.x tables are not automatically upgraded to Apache Phoenix 3.0/4.0 tables. Since pre-Apache 2.2.x code lines have a different package structure (com.salesforce.phoenix) than the 3.0/4.0 code line (org.apache.phoenix), the two installations may actually coexist. An existing Phoenix table may either remain as a 2.2.x table or be upgraded to 3.0/4.0 table, but not both. In addition, a client JVM may either use the 3.0/4.0 driver or the 2.2.x driver, but not both. Upgrade, however, is a one way street: once a table is upgrade to 3.0/4.0, it stays that way.

Note that upgrading a table will not affect its data - only the metadata of the table will change. In order to upgrade tables from 2.2.x to 3.0/4.0, the following must be done BEFORE the first connection to a cluster which has 3.0/4.0 installed on it.

• Add a new phoenix.client.autoUpgradeWhiteList config parameter to your client-side hbase-sites.xml. Make sure the directory containing the hbase-sites.xml is on the classpath of your client so that HBase finds it. The value you use for the parameter depends on which tables you want to upgrade:

  • To upgrade all tables use a value of *. This will cause all Phoenix 2.2.x tables to be automatically converted to the new 3.0.0 structure when the first connection occurs. For example:

    <pre><code>&lt;configuration&gt;
      &lt;property&gt;
        &lt;name&gt;phoenix.client.autoUpgradeWhiteList&lt;/name&gt;
        &lt;value&gt;*&lt;/value&gt;
      &lt;/property&gt;
    &lt;/configuration&gt;</code></pre>
    

  • To upgrade only some tables use a comma separated list of full table names. In that case, only those tables and their secondary indexes will be upgraded on first connection to a cluster. Note that table names are case sensitive. For example, the following would upgrade my_schema.my_table and MY_OTHER_TABLE:

    <pre><code>&lt;configuration&gt;
      &lt;property&gt;
        &lt;name&gt;phoenix.client.autoUpgradeWhiteList&lt;/name&gt;
        &lt;value&gt;my_schema.my_table,MY_OTHER_TABLE&lt;/value&gt;
      &lt;/property&gt;
    &lt;/configuration&gt;</code></pre>
    

• After the first connection has been made to a cluster with Phoenix 3.0/4.0 installed, no further upgrade will take place. However, you may force it to take place again by removing the UpgradeTo30 attribute from the SYSTEM.CATALOG HBase table metadata. Then, on the next connection to the cluster, upgrade will again occur as describe above.