Phoenix database adapter for Python
Project description
phoenixdb is a Python library for accessing Apache Phoenix using the remote query server. This library implements the standard DB API 2.0 interface and a subset of SQLAlchemy, either of which should be familiar to most Python programmers.
Installation
The source code is part of the phoenix-queryserver source distribution. You can download it from <https://phoenix.apache.org/>, or get the latest development version from <https://github.com/apache/phoenix-queryserver>
Extract the archive and then install it manually:
cd /path/to/phoenix-queryserver-x.y.z/python/phoenixdb 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 import phoenixdb.cursor 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()) cursor = conn.cursor(cursor_factory=phoenixdb.cursor.DictCursor) cursor.execute("SELECT * FROM users WHERE id=1") print(cursor.fetchone()['USERNAME'])
Setting up a development environment
If you want to quickly try out the included examples, you can set up a local virtualenv with all the necessary requirements:
virtualenv e source e/bin/activate pip install -r requirements.txt python setup.py develop
You can start a Phoenix QueryServer instance on http://localhost:8765 for testing by running the following command in the pohoenix-queryserver-parent directory:
mvn clean verify -am -pl phoenix-queryserver-it -Dtest=foo \ -Dit.test=QueryServerBasicsIT\#startLocalPQS \ -Ddo.not.randomize.pqs.port=true -Dstart.unsecure.pqs=true
You can start a secure (https+kerberos) Phoenix QueryServer instance on https://localhost:8765 for testing by running the following command in the phoenix-queryserver-parent directory:
mvn clean verify -am -pl phoenix-queryserver-it -Dtest=foo \ -Dit.test=SecureQueryServerPhoenixDBIT\#startLocalPQS \ -Ddo.not.randomize.pqs.port=true -Dstart.secure.pqs=true
this will also create a shell script in phoenix-queryserver-it/target/krb_setup.sh, that you can use to set up the environment for the tests.
If you want to use the library without installing the phoenixdb library, you can use the PYTHONPATH environment variable to point to the library directly:
cd phoenix-queryserver-parent/python-phoenixdb python setup.py build cd ~/my_project PYTHONPATH=$PHOENIX_HOME/build/lib python my_app.py
Don’t forget to run flake8 on your changes.
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/' nosetests
If you use a secure PQS server, you can set the connection parameters via the following environment variables:
PHOENIXDB_TEST_DB_TRUSTSTORE
PHOENIXDB_TEST_DB_AUTHENTICATION
PHOENIXDB_TEST_DB_AVATICA_USER
PHOENIXDB_TEST_DB_AVATICA_PASSWORD
Similarly, tox can be used to run the test suite against multiple Python versions:
pyenv install 3.5.5 pyenv install 3.6.4 pyenv install 2.7.14 pyenv global 2.7.14 3.5.5 3.6.4 PHOENIXDB_TEST_DB_URL='http://localhost:8765' tox
You can use tox and docker to run the tests on supported python versions up to 3.8 without installing the environments locally:
docker build -t toxtest . docker run --rm -v `pwd`:/src toxtest
You can also run the test suite from maven as part of the Java build by setting the run.full.python.testsuite property. You DO NOT need to set the PHOENIXDB_* enviroment variables, maven will set them up for you. The output of the test run will be saved in phoenix-queryserver/phoenix-queryserver-it/target/python-stdout.log and python-stderr.log:
mvn clean verify -Drun.full.python.testsuite=true
Known issues
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. (CALCITE-797, CALCITE-798)
TIMESTAMP columns in Phoenix are stored with a nanosecond accuracy, but the remote protocol truncates them to milliseconds. (CALCITE-796)
SQLAlchemy feature support
SQLAlchemy has a wide breadth of API, ranging from basic SQL commands to object-relational mapping support.
Today, python-phoenixdb only supports the following subset of the complete SQLAlchemy API:
All other API should be considered not implemented.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for phoenixdb-1.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6feaf79754f63d473d65688c53845603b3343f6029929a7e5a4fb090609097a2 |
|
MD5 | e0f6b88dc204bec8364a14a5a7739ddc |
|
BLAKE2b-256 | f1df9f7c8f10611851879ae9f927181fab1be942e5f6c05106f2af67ce6fa45d |
Hashes for phoenixdb-1.1.0-py2-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 91bde5267aaa1428fa14ac2a1851314405f1bb73102033f31b3f098d24a13ba8 |
|
MD5 | f472ad8d614ee6cb7324617e43494adc |
|
BLAKE2b-256 | 769c8921f39d8d4ca32c9d1f859ee188764eb3d2c25e4ffb95d419d847c10786 |