Phoenix database adapter for Python
===================================
``phoenixdb`` is a Python library for accessing
`Apache Phoenix <http://phoenix.apache.org/>`_
using the
`remote query server <http://phoenix.apache.org/server.html>`_.
This library implements the
standard `DB API 2.0 <https://www.python.org/dev/peps/pep-0249/>`_ interface and a
subset of `SQLAlchemy <https://www.sqlalchemy.org/>`_, either of which should be familiar
to most Python programmers.
Installation from PyPI
----------------------
The easiest way to install the latest official release of phoenixdb is from PyPI::
pip install phoenixdb
Installation from Source
------------------------
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
pip install -r requirements.txt
python setup.py install
Note that old versions of pip and setuptools have various bugs and incompatibilities that
may result in installation errors, especially on old python versions.
If you encounter problems while building, update your pip and setuptools, and try again::
pip install --upgrade pip
pip install --upgrade setuptools
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 <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
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 -Pshade-javax-servlet -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 -Pshade-javax-servlet -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.
Note: Depending on the Phoenix version used for building, you may or may not need the
`-Pshade-javax-servlet` option. See BUILDING.md in the repository root for more information.
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/'
tox
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 without
installing the environments locally::
docker build -t toxtest .
docker run --rm --add-host=host.docker.internal:host-gateway -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
------------
- When using phoenixdb 1.2.0 or later with Python 2, phoenixdb will not work unless the Python
protobuf library uses the 'cpp' implementation.
See https://issues.apache.org/jira/browse/PHOENIX-6863 on how to work around the issue.
- 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 <https://issues.apache.org/jira/browse/CALCITE-797>`_, `CALCITE-798 <https://issues.apache.org/jira/browse/CALCITE-798>`_)
- 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>`_)
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:
- `Textual SQL <https://docs.sqlalchemy.org/en/13/core/tutorial.html#using-textual-sql>`_
All other API should be considered not implemented.
Raw data
{
"_id": null,
"home_page": "http://phoenix.apache.org/python.html",
"name": "phoenixdb",
"maintainer": null,
"docs_url": "https://pythonhosted.org/phoenixdb/",
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Apache Software Foundation",
"author_email": "dev@phoenix.apache.org",
"download_url": "https://files.pythonhosted.org/packages/ea/00/2b44dcb27e82c1331e57540adfb25bf05214191a02d8801f260e24764740/phoenixdb-1.2.2.tar.gz",
"platform": null,
"description": "Phoenix database adapter for Python\n===================================\n\n``phoenixdb`` is a Python library for accessing \n`Apache Phoenix <http://phoenix.apache.org/>`_\nusing the\n`remote query server <http://phoenix.apache.org/server.html>`_.\nThis library implements the\nstandard `DB API 2.0 <https://www.python.org/dev/peps/pep-0249/>`_ interface and a\nsubset of `SQLAlchemy <https://www.sqlalchemy.org/>`_, either of which should be familiar\nto most Python programmers.\n\nInstallation from PyPI\n----------------------\n\nThe easiest way to install the latest official release of phoenixdb is from PyPI::\n\n pip install phoenixdb\n\nInstallation from Source\n------------------------\n\nThe source code is part of the phoenix-queryserver source distribution.\nYou can download it from <https://phoenix.apache.org/>, or get the latest development version\nfrom <https://github.com/apache/phoenix-queryserver>\n\nExtract the archive and then install it manually::\n\n cd /path/to/phoenix-queryserver-x.y.z/python-phoenixdb\n pip install -r requirements.txt\n python setup.py install\n\nNote that old versions of pip and setuptools have various bugs and incompatibilities that\nmay result in installation errors, especially on old python versions.\nIf you encounter problems while building, update your pip and setuptools, and try again::\n\n pip install --upgrade pip\n pip install --upgrade setuptools\n\n\nUsage\n-----\n\nThe library implements the standard DB API 2.0 interface, so it can be\nused the same way you would use any other SQL database from Python, for example::\n\n import phoenixdb\n import phoenixdb.cursor\n\n database_url = 'http://localhost:8765/'\n conn = phoenixdb.connect(database_url, autocommit=True)\n\n cursor = conn.cursor()\n cursor.execute(\"CREATE TABLE users (id INTEGER PRIMARY KEY, username VARCHAR)\")\n cursor.execute(\"UPSERT INTO users VALUES (?, ?)\", (1, 'admin'))\n cursor.execute(\"SELECT * FROM users\")\n print(cursor.fetchall())\n\n cursor = conn.cursor(cursor_factory=phoenixdb.cursor.DictCursor)\n cursor.execute(\"SELECT * FROM users WHERE id=1\")\n print(cursor.fetchone()['USERNAME'])\n\n\nSetting up a development environment\n------------------------------------\n\nIf you want to quickly try out the included examples, you can set up a\nlocal `virtualenv <https://virtualenv.pypa.io/en/latest/>`_ with all the\nnecessary requirements::\n\n virtualenv e\n source e/bin/activate\n pip install -r requirements.txt\n python setup.py develop\n\nYou can start a Phoenix QueryServer instance on http://localhost:8765 for testing by running\nthe following command in the pohoenix-queryserver-parent directory::\n\n mvn clean verify -Pshade-javax-servlet -am -pl phoenix-queryserver-it -Dtest=foo \\\n -Dit.test=QueryServerBasicsIT#startLocalPQS \\\n -Ddo.not.randomize.pqs.port=true -Dstart.unsecure.pqs=true\n\nYou can start a secure (https+kerberos) Phoenix QueryServer instance on https://localhost:8765\nfor testing by running the following command in the phoenix-queryserver-parent directory::\n\n mvn clean verify -Pshade-javax-servlet -am -pl phoenix-queryserver-it -Dtest=foo \\\n -Dit.test=SecureQueryServerPhoenixDBIT#startLocalPQS \\\n -Ddo.not.randomize.pqs.port=true -Dstart.secure.pqs=true\n\nthis will also create a shell script in phoenix-queryserver-it/target/krb_setup.sh, that you can\nuse to set up the environment for the tests.\n\nNote: Depending on the Phoenix version used for building, you may or may not need the\n`-Pshade-javax-servlet` option. See BUILDING.md in the repository root for more information.\n\nIf you want to use the library without installing the phoenixdb library, you can use\nthe `PYTHONPATH` environment variable to point to the library directly::\n\n cd phoenix-queryserver-parent/python-phoenixdb\n python setup.py build\n cd ~/my_project\n PYTHONPATH=$PHOENIX_HOME/build/lib python my_app.py\n\nDon't forget to run flake8 on your changes.\n\nRunning the test suite\n----------------------\n\nThe library comes with a test suite for testing Python DB API 2.0 compliance and\nvarious Phoenix-specific features. In order to run the test suite, you need a\nworking Phoenix database and set the ``PHOENIXDB_TEST_DB_URL`` environment variable::\n\n export PHOENIXDB_TEST_DB_URL='http://localhost:8765/'\n tox\n\nIf you use a secure PQS server, you can set the connection parameters via the following environment\nvariables:\n\n- PHOENIXDB_TEST_DB_TRUSTSTORE\n- PHOENIXDB_TEST_DB_AUTHENTICATION\n- PHOENIXDB_TEST_DB_AVATICA_USER\n- PHOENIXDB_TEST_DB_AVATICA_PASSWORD\n\nSimilarly, tox can be used to run the test suite against multiple Python versions::\n\n pyenv install 3.5.5\n pyenv install 3.6.4\n pyenv install 2.7.14\n pyenv global 2.7.14 3.5.5 3.6.4\n PHOENIXDB_TEST_DB_URL='http://localhost:8765' tox\n\nYou can use tox and docker to run the tests on supported python versions without\ninstalling the environments locally::\n\n docker build -t toxtest .\n docker run --rm --add-host=host.docker.internal:host-gateway -v `pwd`:/src toxtest\n\nYou can also run the test suite from maven as part of the Java build by setting the \nrun.full.python.testsuite property. You DO NOT need to set the PHOENIXDB_* enviroment variables,\nmaven will set them up for you. The output of the test run will be saved in\nphoenix-queryserver/phoenix-queryserver-it/target/python-stdout.log and python-stderr.log::\n\n mvn clean verify -Drun.full.python.testsuite=true\n\nKnown issues\n------------\n\n- When using phoenixdb 1.2.0 or later with Python 2, phoenixdb will not work unless the Python\n protobuf library uses the 'cpp' implementation.\n See https://issues.apache.org/jira/browse/PHOENIX-6863 on how to work around the issue.\n- TIME and DATE columns in Phoenix are stored as full timestamps with a millisecond accuracy,\n but the remote protocol only exposes the time (hour/minute/second) or date (year/month/day)\n parts of the columns. (`CALCITE-797 <https://issues.apache.org/jira/browse/CALCITE-797>`_, `CALCITE-798 <https://issues.apache.org/jira/browse/CALCITE-798>`_)\n- 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>`_)\n\n\nSQLAlchemy feature support\n--------------------------\n\nSQLAlchemy has a wide breadth of API, ranging from basic SQL commands to object-relational mapping support.\n\nToday, python-phoenixdb only supports the following subset of the complete SQLAlchemy API:\n\n- `Textual SQL <https://docs.sqlalchemy.org/en/13/core/tutorial.html#using-textual-sql>`_\n\nAll other API should be considered not implemented.\n\n\n",
"bugtrack_url": null,
"license": "Apache 2",
"summary": "Phoenix database adapter for Python",
"version": "1.2.2",
"project_urls": {
"Homepage": "http://phoenix.apache.org/python.html"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bc46e54a5119852e6e63fd0485b77bd6144cacb63c0c7119b2f7965168f3fe7d",
"md5": "9a3a6e13a7ef0c7be5016434f0173b87",
"sha256": "947d4049b728de9645e704b529e044ff454d502b77d9770bdcacd7b72757b403"
},
"downloads": -1,
"filename": "phoenixdb-1.2.2-py2-none-any.whl",
"has_sig": false,
"md5_digest": "9a3a6e13a7ef0c7be5016434f0173b87",
"packagetype": "bdist_wheel",
"python_version": "py2",
"requires_python": null,
"size": 64467,
"upload_time": "2024-06-07T13:05:02",
"upload_time_iso_8601": "2024-06-07T13:05:02.862010Z",
"url": "https://files.pythonhosted.org/packages/bc/46/e54a5119852e6e63fd0485b77bd6144cacb63c0c7119b2f7965168f3fe7d/phoenixdb-1.2.2-py2-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f0ddab0b46b6a2702d9c58936a958ca047ed02f56cc755774b9dd63c5356992c",
"md5": "577d9b2fa366b7210fb4db8f4767966a",
"sha256": "f0251e6e5f90ef6a13a67aee158fdbe43ed13ff3c9147e1967de24555023d5d7"
},
"downloads": -1,
"filename": "phoenixdb-1.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "577d9b2fa366b7210fb4db8f4767966a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 64482,
"upload_time": "2024-06-07T13:05:06",
"upload_time_iso_8601": "2024-06-07T13:05:06.586175Z",
"url": "https://files.pythonhosted.org/packages/f0/dd/ab0b46b6a2702d9c58936a958ca047ed02f56cc755774b9dd63c5356992c/phoenixdb-1.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ea002b44dcb27e82c1331e57540adfb25bf05214191a02d8801f260e24764740",
"md5": "d0326725e6c250dfb5a19f56851f4ccd",
"sha256": "bd177f5d7cd6ad482cc5127fe41062cf37553d2ce51f12c4b6687028966761fd"
},
"downloads": -1,
"filename": "phoenixdb-1.2.2.tar.gz",
"has_sig": false,
"md5_digest": "d0326725e6c250dfb5a19f56851f4ccd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 51343,
"upload_time": "2024-06-07T13:05:07",
"upload_time_iso_8601": "2024-06-07T13:05:07.710451Z",
"url": "https://files.pythonhosted.org/packages/ea/00/2b44dcb27e82c1331e57540adfb25bf05214191a02d8801f260e24764740/phoenixdb-1.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-07 13:05:07",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "phoenixdb"
}
JSON