phoenixdb Release Nov 14, 2017

Transcription

1 phoenixdb Release Nov 14, 2017

2

3 Contents 1 Installation 3 2 Usage 5 3 Setting up a development environment 7 4 Interactive SQL shell 9 5 Running the test suite 11 6 Known issues 13 7 API Reference API Reference Changelog Changelog Indices and tables 23 Python Module Index 25 i

4 ii

5 phoenixdb is a Python library for accessing the Phoenix SQL database using the remote query server. The library implements the standard DB API 2.0 interface, which should be familiar to most Python programmers. Contents 1

6 2 Contents

7 CHAPTER 1 Installation The easiest way to install the library is using pip: pip install phoenixdb You can also download the source code from GitHub, extract the archive and then install it manually: cd /path/to/python-phoenix-x.y.z/ python setup.py install 3

8 4 Chapter 1. Installation

9 CHAPTER 2 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 = ' 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'] 5

10 6 Chapter 2. Usage

11 CHAPTER 3 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 To create or update the Avatica protobuf classes, change the tag in gen-protobuf.sh and run the script. If you need a Phoenix query server for experimenting, you can get one running quickly using Docker: docker-compose up Or if you need an older version of Phoenix: PHOENIX_VERSION=4.9 docker-compose up 7

12 8 Chapter 3. Setting up a development environment

13 CHAPTER 4 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 db=> CREATE TABLE test (id INTEGER PRIMARY KEY, name VARCHAR); no rows affected (1.363 seconds) db=> UPSERT INTO test (id, name) VALUES (1, 'Lukas'); 1 row affected (0.004 seconds) db=> SELECT * FROM test; ID NAME +======+=======+ 1 Lukas row selected (0.019 seconds) 9

14 10 Chapter 4. Interactive SQL shell

15 CHAPTER 5 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=' nosetests Commits to the master branch are automatically tested against all supported versions of Phoenix. You can see the results here. 11

16 12 Chapter 5. Running the test suite

17 CHAPTER 6 Known issues 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. (CALCITE-767) 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) ARRAY columns are not supported. (CALCITE-1050, PHOENIX-2585) 13

18 14 Chapter 6. Known issues

19 CHAPTER 7 API Reference 7.1 API Reference phoenixdb module phoenixdb.connect(url, max_retries=none, **kwargs) Connects to a Phoenix query server. Parameters url URL to the Phoenix query server, e.g. autocommit Switch the connection to autocommit mode. readonly Switch the connection to readonly mode. max_retries The maximum number of retries in case there is a connection error. cursor_factory If specified, the connection s cursor_factory is set to it. Returns Connection object. phoenixdb.date(year, month, day) Constructs an object holding a date value. phoenixdb.time(hour, minute, second) Constructs an object holding a time value. phoenixdb.timestamp(year, month, day, hour, minute, second) Constructs an object holding a datetime/timestamp value. phoenixdb.datefromticks(ticks) Constructs an object holding a date value from the given UNIX timestamp. phoenixdb.timefromticks(ticks) Constructs an object holding a time value from the given UNIX timestamp. 15

20 phoenixdb.timestampfromticks(ticks) Constructs an object holding a datetime/timestamp value from the given UNIX timestamp. phoenixdb.binary(value) Constructs an object capable of holding a binary (long) string value. class phoenixdb.typehelper static from_class(klass) Retrieves a Rep and functions to cast to/from based on the Java class. Parameters klass The string of the Java class for the column or parameter. Returns tuple (field_name, rep, mutate_to, cast_from) WHERE field_name is the attribute in common_pb2.typedvalue rep is the common_pb2.rep enum mutate_to is the function to cast values into Phoenix values, if any cast_from is the function to cast from the Phoenix value to the Python value, if any Raises NotImplementedError exception phoenixdb.warning Not used by this package, only defined for compatibility with DB API 2.0. exception phoenixdb.error(message, code=none, sqlstate=none, cause=none) Exception that is the base class of all other error exceptions. You can use this to catch all errors with one single except statement. cause code message sqlstate exception phoenixdb.interfaceerror(message, code=none, sqlstate=none, cause=none) Exception raised for errors that are related to the database interface rather than the database itself. exception phoenixdb.databaseerror(message, code=none, sqlstate=none, cause=none) Exception raised for errors that are related to the database. exception phoenixdb.dataerror(message, code=none, sqlstate=none, cause=none) Exception raised for errors that are due to problems with the processed data like division by zero, numeric value out of range, etc. exception phoenixdb.operationalerror(message, code=none, sqlstate=none, cause=none) Raised for errors that are related to the database s operation and not necessarily under the control of the programmer, e.g. an unexpected disconnect occurs, the data source name is not found, a transaction could not be processed, a memory allocation error occurred during processing, etc. exception phoenixdb.integrityerror(message, code=none, sqlstate=none, cause=none) Raised when the relational integrity of the database is affected, e.g. a foreign key check fails. exception phoenixdb.internalerror(message, code=none, sqlstate=none, cause=none) Raised when the database encounters an internal problem. exception phoenixdb.programmingerror(message, code=none, sqlstate=none, cause=none) Raises for programming errors, e.g. table not found, syntax error, etc. exception phoenixdb.notsupportederror(message, code=none, sqlstate=none, cause=none) Raised when using an API that is not supported by the database. 16 Chapter 7. API Reference

21 7.1.2 phoenixdb.connection module class phoenixdb.connection.connection(client, cursor_factory=none, **kwargs) Database connection. You should not construct this object manually, use connect() instead. exception DataError(message, code=none, sqlstate=none, cause=none) Exception raised for errors that are due to problems with the processed data like division by zero, numeric value out of range, etc. exception DatabaseError(message, code=none, sqlstate=none, cause=none) Exception raised for errors that are related to the database. exception Error(message, code=none, sqlstate=none, cause=none) Exception that is the base class of all other error exceptions. You can use this to catch all errors with one single except statement. cause code message sqlstate exception IntegrityError(message, code=none, sqlstate=none, cause=none) Raised when the relational integrity of the database is affected, e.g. a foreign key check fails. exception InterfaceError(message, code=none, sqlstate=none, cause=none) Exception raised for errors that are related to the database interface rather than the database itself. exception InternalError(message, code=none, sqlstate=none, cause=none) Raised when the database encounters an internal problem. exception NotSupportedError(message, code=none, sqlstate=none, cause=none) Raised when using an API that is not supported by the database. exception OperationalError(message, code=none, sqlstate=none, cause=none) Raised for errors that are related to the database s operation and not necessarily under the control of the programmer, e.g. an unexpected disconnect occurs, the data source name is not found, a transaction could not be processed, a memory allocation error occurred during processing, etc. exception ProgrammingError(message, code=none, sqlstate=none, cause=none) Raises for programming errors, e.g. table not found, syntax error, etc. exception Warning Not used by this package, only defined for compatibility with DB API 2.0. autocommit Read/write attribute for switching the connection s autocommit mode. close() Closes the connection. No further operations are allowed, either on the connection or any of its cursors, once the connection is closed. If the connection is used in a with statement, this method will be automatically called at the end of the with block. closed Read-only attribute specifying if the connection is closed or not API Reference 17

22 commit() Commits pending database changes. Currently, this does nothing, because the RPC does not support transactions. Only defined for DB API 2.0 compatibility. You need to use autocommit mode. cursor(cursor_factory=none) Creates a new cursor. Parameters cursor_factory This argument can be used to create non-standard cursors. The class returned must be a subclass of Cursor (for example DictCursor). A default factory for the connection can also be specified using the cursor_factory attribute. Returns A Cursor object. cursor_factory = None open() Opens the connection. readonly Read/write attribute for switching the connection s readonly mode. set_session(autocommit=none, readonly=none) Sets one or more parameters in the current connection. Parameters autocommit Switch the connection to autocommit mode. With the current version, you need to always enable this, because commit() is not implemented. readonly Switch the connection to read-only mode. transactionisolation phoenixdb.cursor module class phoenixdb.cursor.cursor(connection, id=none) Database cursor for executing queries and iterating over results. You should not construct this object manually, use Connection.cursor() instead. arraysize = 1 close() Closes the cursor. No further operations are allowed once the cursor is closed. If the cursor is used in a with statement, this method will be automatically called at the end of the with block. closed Read-only attribute specifying if the cursor is closed or not. connection Read-only attribute providing access to the Connection object this cursor was created from. description execute(operation, parameters=none) executemany(operation, seq_of_parameters) fetchall() fetchmany(size=none) 18 Chapter 7. API Reference

23 fetchone() itersize = 2000 next() rowcount Read-only attribute specifying the number of rows affected by the last executed DML statement or -1 if the number cannot be determined. Note that this will always be set to -1 for select queries. rownumber Read-only attribute providing the current 0-based index of the cursor in the result set or None if the index cannot be determined. The index can be seen as index of the cursor in a sequence (the result set). The next fetch operation will fetch the row indexed by rownumber in that sequence. setinputsizes(sizes) setoutputsize(size, column=none) class phoenixdb.cursor.columndescription(name, type_code, display_size, internal_size, precision, scale, null_ok) display_size Alias for field number 2 internal_size Alias for field number 3 name Alias for field number 0 null_ok Alias for field number 6 precision Alias for field number 4 scale Alias for field number 5 type_code Alias for field number 1 class phoenixdb.cursor.dictcursor(connection, id=none) A cursor which returns results as a dictionary phoenixdb.avatica module 7.1. API Reference 19

24 20 Chapter 7. API Reference

25 CHAPTER 8 Changelog 8.1 Changelog Version 0.7 Added DictCursor for easier access to columns by their names. Support for Phoenix versions from 4.8 to Version 0.6 Fixed result fetching when using a query with parameters. Support for Phoenix Version 0.5 Added support for Python 3. Switched from the JSON serialization to Protocol Buffers, improved compatibility with Phoenix 4.8. Phoenix 4.6 and older are no longer supported Version 0.4 Fixes for the final version of Phoenix Version 0.3 Compatible with Phoenix

26 8.1.6 Version 0.2 Added (configurable) retry on connection errors. Added Vagrantfile for easier testing. Compatible with Phoenix Version 0.1 Initial release. Compatible with Phoenix Chapter 8. Changelog

27 CHAPTER 9 Indices and tables genindex modindex search 23

28 24 Chapter 9. Indices and tables

29 Python Module Index p phoenixdb, 15 phoenixdb.avatica, 19 phoenixdb.connection, 17 phoenixdb.cursor, 18 25

30 26 Python Module Index

31 Index A arraysize (phoenixdb.cursor.cursor attribute), 18 autocommit (phoenixdb.connection.connection attribute), 17 B Binary() (in module phoenixdb), 16 C cause (phoenixdb.connection.connection.error attribute), 17 cause (phoenixdb.error attribute), 16 close() (phoenixdb.connection.connection method), 17 close() (phoenixdb.cursor.cursor method), 18 closed (phoenixdb.connection.connection attribute), 17 closed (phoenixdb.cursor.cursor attribute), 18 code (phoenixdb.connection.connection.error attribute), 17 code (phoenixdb.error attribute), 16 ColumnDescription (class in phoenixdb.cursor), 19 commit() (phoenixdb.connection.connection method), 17 connect() (in module phoenixdb), 15 Connection (class in phoenixdb.connection), 17 connection (phoenixdb.cursor.cursor attribute), 18 Connection.DatabaseError, 17 Connection.DataError, 17 Connection.Error, 17 Connection.IntegrityError, 17 Connection.InterfaceError, 17 Connection.InternalError, 17 Connection.NotSupportedError, 17 Connection.OperationalError, 17 Connection.ProgrammingError, 17 Connection.Warning, 17 Cursor (class in phoenixdb.cursor), 18 cursor() (phoenixdb.connection.connection method), 18 cursor_factory (phoenixdb.connection.connection attribute), 18 D DatabaseError, 16 DataError, 16 Date() (in module phoenixdb), 15 DateFromTicks() (in module phoenixdb), 15 description (phoenixdb.cursor.cursor attribute), 18 DictCursor (class in phoenixdb.cursor), 19 display_size (phoenixdb.cursor.columndescription attribute), 19 E Error, 16 execute() (phoenixdb.cursor.cursor method), 18 executemany() (phoenixdb.cursor.cursor method), 18 F fetchall() (phoenixdb.cursor.cursor method), 18 fetchmany() (phoenixdb.cursor.cursor method), 18 fetchone() (phoenixdb.cursor.cursor method), 19 from_class() (phoenixdb.typehelper static method), 16 I IntegrityError, 16 InterfaceError, 16 internal_size (phoenixdb.cursor.columndescription attribute), 19 InternalError, 16 itersize (phoenixdb.cursor.cursor attribute), 19 M message (phoenixdb.connection.connection.error attribute), 17 message (phoenixdb.error attribute), 16 N name (phoenixdb.cursor.columndescription attribute), 19 next() (phoenixdb.cursor.cursor method), 19 NotSupportedError, 16 27

32 null_ok (phoenixdb.cursor.columndescription attribute), 19 O open() (phoenixdb.connection.connection method), 18 OperationalError, 16 P phoenixdb (module), 15 phoenixdb.avatica (module), 19 phoenixdb.connection (module), 17 phoenixdb.cursor (module), 18 precision (phoenixdb.cursor.columndescription attribute), 19 ProgrammingError, 16 R readonly (phoenixdb.connection.connection attribute), 18 rowcount (phoenixdb.cursor.cursor attribute), 19 rownumber (phoenixdb.cursor.cursor attribute), 19 S scale (phoenixdb.cursor.columndescription attribute), 19 set_session() (phoenixdb.connection.connection method), 18 setinputsizes() (phoenixdb.cursor.cursor method), 19 setoutputsize() (phoenixdb.cursor.cursor method), 19 sqlstate (phoenixdb.connection.connection.error attribute), 17 sqlstate (phoenixdb.error attribute), 16 T Time() (in module phoenixdb), 15 TimeFromTicks() (in module phoenixdb), 15 Timestamp() (in module phoenixdb), 15 TimestampFromTicks() (in module phoenixdb), 15 transactionisolation (phoenixdb.connection.connection attribute), 18 type_code (phoenixdb.cursor.columndescription attribute), 19 TypeHelper (class in phoenixdb), 16 W Warning, Index