Docs

README.rst

@@ -1,46 +1,23 @@
-python-phoenixdb
-================
+Phoenixdb - Phoenix database adapter for Python
+===============================================
 
-*phoenixdb* is a Python library for accessing the
-`Phoenix SQL database <http://phoenix.apache.org/>`_ using the standard
-`DB API 2.0 interface <https://www.python.org/dev/peps/pep-0249/>`_. It implements the
-`Avatica RPC protocol <http://calcite.incubator.apache.org/docs/avatica.html>`_, which is
-used by the `Phoenix query server <http://phoenix.apache.org/server.html>`_, but unfortunately
-the protocol is still in development and might change at any time.
-The library works with Phoenix 4.4, but will most likely need to be changed to support the
-next release. Also note, that this is more of a proof-of-concept implementation, it has not
-been thoroughly tested. Use with care.
+`phoenixdb` is a Python library for accessing the
+`Phoenix SQL database <http://phoenix.apache.org/>`_
+using the
+`remote query server <http://phoenix.apache.org/server.html>`_ introduced
+in Phoenix 4.4.  The library implements the  
+standard `DB API 2.0 <https://www.python.org/dev/peps/pep-0249/>`_ interface,
+which should be familiar to most Python programmers.
 
 Example usage::
 
     import phoenixdb
 
-    with phoenixdb.connect('http://localhost:8765/', autocommit=True) as conn:
-        c = conn.cursor()
-        c.execute("SELECT * FROM test")
-        print c.fetchall()
+    database_url = 'http://localhost:8765/'
+    conn = phoenixdb.connect(database_url, autocommit=True)
 
-You can also use the database from a Python-based command-line shell::
-
-    virtualenv e
-    . e/bin/activate
-    pip install -r requirements.txt
-    python setup.py develop
-    ./examples/shell.py http://localhost:8765/
-
-Running the DB API 2.0 compliance test suite and other unit tests::
-
-    export PHOENIXDB_TEST_DB_URL=http://localhost:8765/
-    nosetests
-
-If you need a Phoenix server for experimenting, you can get one running quickly using Vagrant, Ansible and VirtualBox::
-
-    git clone https://bitbucket.org/lalinsky/ansible-hadoop.git
-    cd ansible-hadoop
-    vagrant up
-
-Known problems:
-
-* "Transaction" support, i.e. non-autocommit mode. Needs support in the Avatica RPC server first. (`CALCITE-767 <https://issues.apache.org/jira/browse/CALCITE-767>`_)
-* Proper exception handling, currently it tries to parse the HTML error page it receives from the server. (`CALCITE-645 <https://issues.apache.org/jira/browse/CALCITE-767>`_)
-* Can't use TIME/DATE columns. The server returns incomplete data and expects different format on input and output. (`discussion <http://mail-archives.apache.org/mod_mbox/phoenix-user/201506.mbox/%3CCAGUtLj8HDeq7chOSTz%3DVznB-v79%3DCmJ5%3Dt1N9Bbe4wE_m1%3D3zg%40mail.gmail.com%3E>`_)
+    cursor = conn.cursor()
+    cursor.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, username VARCHAR)")
+    cursor.execute("UPSERT INTO users VALUES (?, ?)", (1, 'admin'))
+    cursor.execute("SELECT * FROM users")
+    print cursor.fetchall()

doc/index.rst

@@ -2,16 +2,93 @@ Welcome to phoenixdb's documentation!
 =====================================
 
 `phoenixdb` is a Python library for accessing the
-`Phoenix SQL database <http://phoenix.apache.org/>`_ using the standard
-`DB API 2.0 interface <https://www.python.org/dev/peps/pep-0249/>`_. It implements the
-`Avatica RPC protocol <http://calcite.incubator.apache.org/docs/avatica.html>`_, which is
-used by the `Phoenix query server <http://phoenix.apache.org/server.html>`_, but unfortunately
-the protocol is still in development and might change at any time.
-The library works with Phoenix 4.4, but will most likely need to be changed to support the
-next release. Also note, that this is more of a proof-of-concept implementation, it has not
-been thoroughly tested. Use with care.
-
-Contents:
+`Phoenix SQL database <http://phoenix.apache.org/>`_
+using the
+`remote query server <http://phoenix.apache.org/server.html>`_ introduced
+in Phoenix 4.4.  The library implements the  
+standard `DB API 2.0 <https://www.python.org/dev/peps/pep-0249/>`_ interface,
+which should be familiar to most Python programmers.
+
+Installation
+------------
+
+The easiest way to install the library is using `pip <https://pip.pypa.io/en/stable/>`_::
+
+    pip install python-phoenixdb
+
+You can also download the source code from `Bitbucket <https://bitbucket.org/lalinsky/python-phoenixdb/downloads>`_,
+extract the archive and then install it manually::
+
+    cd /path/to/python-phoenix-x.y.z/
+    python setup.py install
+
+Usage
+-----
+
+The library implements the standard DB API 2.0 interface, so it can be
+used the same way you would use any other SQL database from Python, for example::
+
+    import phoenixdb
+
+    database_url = 'http://localhost:8765/'
+    conn = phoenixdb.connect(database_url, autocommit=True)
+
+    cursor = conn.cursor()
+    cursor.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, username VARCHAR)")
+    cursor.execute("UPSERT INTO users VALUES (?, ?)", (1, 'admin'))
+    cursor.execute("SELECT * FROM users")
+    print cursor.fetchall()
+
+Setting up a development environment
+------------------------------------
+
+If you want to quickly try out the included examples, you can set up a
+local `virtualenv <https://virtualenv.pypa.io/en/latest/>`_ with all the
+necessary requirements::
+
+    virtualenv e
+    source e/bin/activate
+    pip install -r requirements.txt
+    python setup.py develop
+
+If you need a Phoenix server for experimenting, you can get one running
+quickly using Vagrant, Ansible and VirtualBox::
+
+    git clone https://bitbucket.org/lalinsky/ansible-hadoop.git
+    cd ansible-hadoop
+    vagrant up
+
+Running the test suite
+----------------------
+
+The library comes with a test suite for testing Python DB API 2.0 compliance and
+various Phoenix-specific features. In order to run the test suite, you need a
+working Phoenix database and set the ``PHOENIXDB_TEST_DB_URL`` environment variable::
+
+    export PHOENIXDB_TEST_DB_URL='http://localhost:8765/?v=1.4.0'
+    nosetests
+
+Interactive SQL shell
+---------------------
+
+There is a Python-based interactive shell include in the examples folder, which can be
+used to connect to Phoenix and execute queries::
+
+    ./examples/shell.py http://localhost:8765/
+
+Known issues
+------------
+
+- In general, the library has not been battle-tested yet. You might encounter almost any problem. Use with care.
+- You can only use the library in autocommit mode. The native Java Phoenix library also implements batched upserts, which can be committed at once, but this is not exposed over the remote server.
+- In some cases, generic exceptions are raises, instead of more specific SQL errors. This is because the Avatica server from Calcite currently does not pass errors in a structured format.
+- BINARY, TIME, DATE and TIMESTAMP data types do not work with Phoenix 4.4, which ships with Calcite 1.2. You can use them if you make a custom build of Phoenix with a more recent version of Calcite.
+- Requests with more than 16k data will fail on Phoenix 4.4.
+- TIME and DATE columns in Phoenix are stored as full timestamps with a millisecond accuracy, but the remote protocol only exposes the time (hour/minute/second) or date (year/month/day) parts of the columns.
+- TIMESTAMP columns in Phoenix are stored with a nanosecond accuracy, but the remote protocol truncates them to milliseconds.
+
+API Reference
+-------------
 
 .. toctree::
    :maxdepth: 2