tree: 4bea5032cb23e193346b21cce557a8d22aa18670 [path history] [tgz]
  1. .gitignore
  2. .gitlab-ci.yml
  3. README.md
  4. phoenixdb/
  5. requests-kerberos/
python/README.md

Apache Phoenix Python Driver “PhoenixDB”

This directory contains the Python driver for Apache Phoenix called “Python PhoenixDB” or just “PhoenixDB”.

This driver implements the Python DB 2.0 API for database drivers as described by PEP-249. This driver is implemented using the Phoenix Query Server (PQS) and the Apache Calcite Avatica project.

This driver should be compatible with Python 2.7 and Python 3.3+ and support both unauthenticated access and authenticated access via SPNEGO to PQS.

Usage

The use of a virtual Python environment is strongly recommended, e.g. virtualenv or conda. You can install one of these using the Python package manager pip. For developers who need to support multiple versions of Python, Python version managers, such as pyenv, can drastically improve your quality of life.

When connecting to an unsecured PQS instance, install the phoenixdb module into your local environment and write your application.

$ virtualenv e
$ source e/bin/activate
$ pip install file:///path/to/phoenix-x.y.z/phoenix/python/phoenixdb
$ cat <<EOF
import phoenixdb
import phoenixdb.cursor

if __name__ == '__main__':
  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())
EOF > test-client.py
$ python test-client.py

When using a PQS instance secured via SPNEGO with Kerberos-based authentication, you must also install the custom release of requests-kerberos provided with PhoenixDB.

$ virtualenv e
$ source e/bin/activate
$ pip install file:///path/to/phoenix-x.y.z/phoenix/python/phoenixdb
$ pip install file:///path/to/phoenix-x.y.z/phoenix/python/requests-kerberos
$ cat <<EOF
import phoenixdb
import phoenixdb.cursor

if __name__ == '__main__':
  database_url = 'http://localhost:8765/'
  conn = phoenixdb.connect(database_url, autocommit=True, auth="SPNEGO")
  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())
EOF > test-client.py
$ python test-client.py

Please see the README included with PhoenixDB for more information on using the Python driver.

Kerberos support in testing

An integration test, SecureQueryServerPhoenixDBIT, is included with Phoenix that sets up a secured Phoenix installation with PQS, then uses the driver to interact with that installation. We have observed that, with a correct krb5.conf for the Kerberos installation (MIT or Heimdal), this driver and the patched requests-kerberos library can communicate with the secured PQS instance.

This test will guess at the flavor of Kerberos that you have installed on your local system. There is an option exposed which will force a specific flavor to be assumed: PHOENIXDB_KDC_IMPL. Valid options are MIT and HEIMDAL. You specify this as a Java system property from Maven, e.g. mvn verify -Dtest=foo -Did.test=SecureQueryServerPhoenixDBIT -DPHOENIXDB_KDC_IMPL=MIT forces an MIT Kerberos style krb5.conf to be used for the test.