git commit: Add upgrade info to README

[ja...@apache.org]

Repository: incubator-phoenix
Updated Branches:
  refs/heads/3.0 f5140d824 -> 9564d4ddb


Add upgrade info to README


Project: http://git-wip-us.apache.org/repos/asf/incubator-phoenix/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-phoenix/commit/9564d4dd
Tree: http://git-wip-us.apache.org/repos/asf/incubator-phoenix/tree/9564d4dd
Diff: http://git-wip-us.apache.org/repos/asf/incubator-phoenix/diff/9564d4dd

Branch: refs/heads/3.0
Commit: 9564d4ddb0cbb46ed0faa76b11534027b9677ac8
Parents: f5140d8
Author: James Taylor <ja...@apache.org>
Authored: Fri Mar 28 09:28:59 2014 -0700
Committer: James Taylor <ja...@apache.org>
Committed: Fri Mar 28 09:28:59 2014 -0700

----------------------------------------------------------------------
 README | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-phoenix/blob/9564d4dd/README
----------------------------------------------------------------------
diff --git a/README b/README
index afee3bd..7f1873e 100644
--- a/README
+++ b/README
@@ -18,3 +18,57 @@ The Phoenix mailing lists and archives are listed here [5]
 3. http://phoenix.incubator.apache.org/issues.html
 4. http://www.apache.org/licenses/
 5. http://phoenix.incubator.apache.org/mailing_list.html
+
+Upgrading from Phoenix 2.2.x to Apache Phoenix 3.0/4.0
+------------------------------------------------------
+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><configuration>
+          <property>
+            <name>phoenix.client.autoUpgradeWhiteList</name>
+            <value>*</value>
+          </property>
+        </configuration></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><configuration>
+          <property>
+            <name>phoenix.client.autoUpgradeWhiteList</name>
+            <value>my_schema.my_table,MY_OTHER_TABLE</value>
+          </property>
+        </configuration></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.
+