README.rst 5.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131
  1. Phoenix database adapter for Python
  2. ===================================
  3. ``phoenixdb`` is a Python library for accessing the
  4. `Phoenix SQL database <http://phoenix.apache.org/>`_
  5. using the
  6. `remote query server <http://phoenix.apache.org/server.html>`_.
  7. The library implements the
  8. standard `DB API 2.0 <https://www.python.org/dev/peps/pep-0249/>`_ interface,
  9. which should be familiar to most Python programmers.
  10. Installation
  11. ------------
  12. The source code is part of the phoenix-queryserver source distribution.
  13. You can download it from <https://phoenix.apache.org/>, or get the latest development version
  14. from <https://github.com/apache/phoenix-queryserver>
  15. Extract the archive and then install it manually::
  16. cd /path/to/phoenix-queryserver-x.y.z/python/phoenixdb
  17. python setup.py install
  18. Usage
  19. -----
  20. The library implements the standard DB API 2.0 interface, so it can be
  21. used the same way you would use any other SQL database from Python, for example::
  22. import phoenixdb
  23. import phoenixdb.cursor
  24. database_url = 'http://localhost:8765/'
  25. conn = phoenixdb.connect(database_url, autocommit=True)
  26. cursor = conn.cursor()
  27. cursor.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, username VARCHAR)")
  28. cursor.execute("UPSERT INTO users VALUES (?, ?)", (1, 'admin'))
  29. cursor.execute("SELECT * FROM users")
  30. print(cursor.fetchall())
  31. cursor = conn.cursor(cursor_factory=phoenixdb.cursor.DictCursor)
  32. cursor.execute("SELECT * FROM users WHERE id=1")
  33. print(cursor.fetchone()['USERNAME'])
  34. Setting up a development environment
  35. ------------------------------------
  36. If you want to quickly try out the included examples, you can set up a
  37. local `virtualenv <https://virtualenv.pypa.io/en/latest/>`_ with all the
  38. necessary requirements::
  39. virtualenv e
  40. source e/bin/activate
  41. pip install -r requirements.txt
  42. python setup.py develop
  43. You can start a Phoenix QueryServer instance on http://localhost:8765 for testing by running
  44. the following command in the phoenix-queryserver directory::
  45. mvn clean verify -am -pl queryserver-it -Dtest=foo \
  46. -Dit.test=QueryServerBasicsIT\#startLocalPQS \
  47. -Ddo.not.randomize.pqs.port=true -Dstart.unsecure.pqs=true
  48. You can start a secure (https+kerberos) Phoenix QueryServer instance on https://localhost:8765
  49. for testing by running the following command in the phoenix-queryserver directory::
  50. mvn clean verify -am -pl queryserver-it -Dtest=foo \
  51. -Dit.test=SecureQueryServerPhoenixDBIT\#startLocalPQS \
  52. -Ddo.not.randomize.pqs.port=true -Dstart.secure.pqs=true
  53. this will also create a shell script in queryserver-it/target/krb_setup.sh, that you can use to set
  54. up the environment for the tests.
  55. If you want to use the library without installing the phoenixdb library, you can use
  56. the `PYTHONPATH` environment variable to point to the library directly::
  57. cd $PHOENIX_HOME/python
  58. python setup.py build
  59. cd ~/my_project
  60. PYTHONPATH=$PHOENIX_HOME/build/lib python my_app.py
  61. Don't forget to run flake8 on your changes.
  62. Running the test suite
  63. ----------------------
  64. The library comes with a test suite for testing Python DB API 2.0 compliance and
  65. various Phoenix-specific features. In order to run the test suite, you need a
  66. working Phoenix database and set the ``PHOENIXDB_TEST_DB_URL`` environment variable::
  67. export PHOENIXDB_TEST_DB_URL='http://localhost:8765/'
  68. nosetests
  69. If you use a secure PQS server, you can set the connection parameters via the following environment
  70. variables:
  71. - PHOENIXDB_TEST_DB_TRUSTSTORE
  72. - PHOENIXDB_TEST_DB_AUTHENTICATION
  73. - PHOENIXDB_TEST_DB_AVATICA_USER
  74. - PHOENIXDB_TEST_DB_AVATICA_PASSWORD
  75. Similarly, tox can be used to run the test suite against multiple Python versions::
  76. pyenv install 3.5.5
  77. pyenv install 3.6.4
  78. pyenv install 2.7.14
  79. pyenv global 2.7.14 3.5.5 3.6.4
  80. PHOENIXDB_TEST_DB_URL='http://localhost:8765' tox
  81. You can use tox and docker to run the tests on all supported python versions without installing the
  82. environments locally::
  83. docker build -t toxtest .
  84. docker run --rm -v `pwd`:/src toxtest
  85. You can also run the test suite from maven as part of the Java build by setting the
  86. run.full.python.testsuite property. You DO NOT need to set the PHOENIXDB_* enviroment variables,
  87. maven will set them up for you. The output of the test run will be saved in
  88. phoenix-queryserver/queryserver-it/target/python-stdout.log and python-stderr.log::
  89. mvn clean verify -Drun.full.python.testsuite=true
  90. Known issues
  91. ------------
  92. - TIME and DATE columns in Phoenix are stored as full timestamps with a millisecond accuracy,
  93. but the remote protocol only exposes the time (hour/minute/second) or date (year/month/day)
  94. parts of the columns. (`CALCITE-797 <https://issues.apache.org/jira/browse/CALCITE-797>`_, `CALCITE-798 <https://issues.apache.org/jira/browse/CALCITE-798>`_)
  95. - TIMESTAMP columns in Phoenix are stored with a nanosecond accuracy, but the remote protocol truncates them to milliseconds. (`CALCITE-796 <https://issues.apache.org/jira/browse/CALCITE-796>`_)