===================================
Python connector for SQream DB Blue
===================================
* **Version:** 1.0.46
* **Supported SQream DB versions:** >= Blue cloud
The Python connector for SQream DB is a Python DB API 2.0-compliant interface for developing Python applications with SQream DB.
The SQream Python connector provides an interface for creating and running Python applications that can connect to a SQream DB database. It provides a lighter-weight alternative to working through native C++ or Java bindings, including JDBC and ODBC drivers.
pysqream conforms to Python DB-API specifications `PEP-249 <https://www.python.org/dev/peps/pep-0249/>`_
``pysqream_blue`` is native and pure Python, with minimal requirements. It can be installed with ``pip3`` on any operating system, including Linux, Windows, and macOS.
.. For more information and a full API reference, see `SQream documentation's pysqream blue guide <https://sqream-docs.readthedocs.io/en/latest/guides/client_drivers/python/index.html>`_ .
Requirements
-------------
* Python 3.9+
Installing the Python connector
--------------------------------
Prerequisites
----------------
1. Python
^^^^^^^^^^^^
The connector requires Python 3.9 or newer. To verify your version of Python:
.. code-block:: console
$ python --version
Python 3.9
2. PIP
^^^^^^^^^^^^
The Python connector is installed via ``pip3``, the Python package manager and installer.
We recommend upgrading to the latest version of ``pip3`` before installing. To verify that you are on the latest version, run the following command:
.. code-block:: console
$ python -m pip3 install --upgrade pip
Collecting pip
Downloading https://files.pythonhosted.org/packages/00/b6/9cfa56b4081ad13874b0c6f96af8ce16cfbc1cb06bedf8e9164ce5551ec1/pip-19.3.1-py2.py3-none-any.whl (1.4MB)
|████████████████████████████████| 1.4MB 1.6MB/s
Installing collected packages: pip
Found existing installation: pip 19.1.1
Uninstalling pip-19.1.1:
Successfully uninstalled pip-19.1.1
Successfully installed pip-19.3.1
.. note::
* On macOS, you may want to use virtualenv to install Python and the connector, to ensure compatibility with the built-in Python environment
* If you encounter an error including ``SSLError`` or ``WARNING: pip is configured with locations that require TLS/SSL, however the ssl module in Python is not available.`` - please be sure to reinstall Python with SSL enabled, or use virtualenv or Anaconda.
Install via pip
-----------------
The Python connector is available via `PyPi <https://pypi.org/project/pysqream/>`_.
Install the connector with ``pip3``:
.. code-block:: console
$ pip3 install pysqream-blue
``pip3`` will automatically installs all necessary libraries and modules.
Validate the installation
-----------------------------
Create a file called ``test.py`` (make sure to replace the parameters in the connection with the respective parameters for your SQream DB installation):
.. code-block:: python
#!/usr/bin/env python
import pysqream_blue
"""
Connection parameters include:
* IP/Hostname
* Port
* database name
* username
* password
* Connect through load balancer, or direct to worker (Default: false - direct to worker)
* use SSL connection (default: false)
* Optional service queue (default: 'sqream')
"""
# Create a connection object
con = pysqream_blue.connect(host='127.0.0.1', port='80',
database='master', username='sqream', password='sqream')
# Create a new cursor
cur = con.cursor()
# Prepare and execute a query
cur.execute('select 1')
result = cur.fetchall() # `fetchall` gets the entire data set
print(f"Result: {result}")
# This should print the SQream DB version. For example ``Version: v2020.1``.
# close statement
cur.close()
# Finally, close the connection
con.close()
Logging
-------
To enable logging, pass a path to a log file in the connection string as follows:
.. code-block:: python
pysqream_blue.set_log_path('PATH LOG FILE')
con = pysqream_blue.connect('127.0.0.1', '80', use_logs=True, log_level='INFO')
For example save to `'/tmp/sqream_dbapi.log'`:
.. code-block:: python
pysqream_blue.set_log_path('/tmp/sqream_dbapi.log')
con = pysqream_blue.connect('127.0.0.1', '80', use_logs=True, log_level='INFO')
The log level default is 'INFO', the logs level are ['INFO', 'DEBUG', 'CRITICAL', 'WARNING', 'ERROR']
TODO (when server support):
-----------------------------------------
* use ssl connection.
* send the token recived in authentication in every following request as call credentials (compile, execute, etc).
* parametered queries / network insert.
the existing code related to those points is a preparation and not reliable.
Differences from V1 pysqream (from user view):
-----------------------------------------------
* The parameters to connect function are different (some were removed and some were added).
* SSL connection not supported.
* `executemany()` (- network insert) not supported.
Design decisions:
-----------------------------------------
* The grpc chunnel and stubs are opened and closed by `__init__` and `__del__` methods (which call `_connect_to_server()` and `_disconnect_server()` where the implementation itself is).
The authentication with sqream and receipt a token made by `connect_database()` method (while `close()` close it).
User can call `close()` and then `connect_database()` for swiching between databases on the same server.
It may make sense to decide to close the chunnel as well in `close()` method (which is a part of DB API).
* The same chunnel and stubs used for all cursors of a connection but every cursor open his own token.
it may make sense to decide to use different stubs or chunnel for every cursor or to use the same token for all.
* Fetch methods return list of list and not list of tuple
License-File: LICENSE
Raw data
{
"_id": null,
"home_page": "https://github.com/SQream/pysqream-blue",
"name": "pysqream-blue",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "database db-api sqream sqreamdbV2",
"author": "SQream",
"author_email": "info@sqream.com",
"download_url": "https://files.pythonhosted.org/packages/99/a2/c96cba8759f83f77b4e37935e7a1c331d198e706f9f95033dc1e5d05e60f/pysqream-blue-1.0.46.tar.gz",
"platform": null,
"description": "===================================\nPython connector for SQream DB Blue\n===================================\n\n* **Version:** 1.0.46\n\n* **Supported SQream DB versions:** >= Blue cloud\n\nThe Python connector for SQream DB is a Python DB API 2.0-compliant interface for developing Python applications with SQream DB.\n\nThe SQream Python connector provides an interface for creating and running Python applications that can connect to a SQream DB database. It provides a lighter-weight alternative to working through native C++ or Java bindings, including JDBC and ODBC drivers.\n\npysqream conforms to Python DB-API specifications `PEP-249 <https://www.python.org/dev/peps/pep-0249/>`_\n\n``pysqream_blue`` is native and pure Python, with minimal requirements. It can be installed with ``pip3`` on any operating system, including Linux, Windows, and macOS.\n\n.. For more information and a full API reference, see `SQream documentation's pysqream blue guide <https://sqream-docs.readthedocs.io/en/latest/guides/client_drivers/python/index.html>`_ .\n\nRequirements\n-------------\n\n* Python 3.9+\n\nInstalling the Python connector\n--------------------------------\n\nPrerequisites\n----------------\n\n1. Python\n^^^^^^^^^^^^\n\nThe connector requires Python 3.9 or newer. To verify your version of Python:\n\n.. code-block:: console\n\n $ python --version\n Python 3.9\n\n2. PIP\n^^^^^^^^^^^^\nThe Python connector is installed via ``pip3``, the Python package manager and installer.\n\nWe recommend upgrading to the latest version of ``pip3`` before installing. To verify that you are on the latest version, run the following command:\n\n.. code-block:: console\n\n $ python -m pip3 install --upgrade pip\n Collecting pip\n Downloading https://files.pythonhosted.org/packages/00/b6/9cfa56b4081ad13874b0c6f96af8ce16cfbc1cb06bedf8e9164ce5551ec1/pip-19.3.1-py2.py3-none-any.whl (1.4MB)\n |\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| 1.4MB 1.6MB/s\n Installing collected packages: pip\n Found existing installation: pip 19.1.1\n Uninstalling pip-19.1.1:\n Successfully uninstalled pip-19.1.1\n Successfully installed pip-19.3.1\n\n.. note::\n * On macOS, you may want to use virtualenv to install Python and the connector, to ensure compatibility with the built-in Python environment\n * If you encounter an error including ``SSLError`` or ``WARNING: pip is configured with locations that require TLS/SSL, however the ssl module in Python is not available.`` - please be sure to reinstall Python with SSL enabled, or use virtualenv or Anaconda.\n\n\nInstall via pip\n-----------------\n\nThe Python connector is available via `PyPi <https://pypi.org/project/pysqream/>`_.\n\nInstall the connector with ``pip3``:\n\n.. code-block:: console\n\n $ pip3 install pysqream-blue\n\n``pip3`` will automatically installs all necessary libraries and modules.\n\nValidate the installation\n-----------------------------\n\nCreate a file called ``test.py`` (make sure to replace the parameters in the connection with the respective parameters for your SQream DB installation):\n\n.. code-block:: python\n\n #!/usr/bin/env python\n\n import pysqream_blue\n\n \"\"\"\n Connection parameters include:\n * IP/Hostname\n * Port\n * database name\n * username\n * password\n * Connect through load balancer, or direct to worker (Default: false - direct to worker)\n * use SSL connection (default: false)\n * Optional service queue (default: 'sqream')\n \"\"\"\n\n # Create a connection object\n\n con = pysqream_blue.connect(host='127.0.0.1', port='80',\n database='master', username='sqream', password='sqream')\n\n # Create a new cursor\n cur = con.cursor()\n\n # Prepare and execute a query\n cur.execute('select 1')\n\n result = cur.fetchall() # `fetchall` gets the entire data set\n\n print(f\"Result: {result}\")\n\n # This should print the SQream DB version. For example ``Version: v2020.1``.\n\n # close statement\n cur.close()\n\n # Finally, close the connection\n con.close()\n\n\nLogging\n-------\n\nTo enable logging, pass a path to a log file in the connection string as follows:\n\n.. code-block:: python\n\n pysqream_blue.set_log_path('PATH LOG FILE')\n con = pysqream_blue.connect('127.0.0.1', '80', use_logs=True, log_level='INFO')\n\nFor example save to `'/tmp/sqream_dbapi.log'`:\n\n.. code-block:: python\n\n pysqream_blue.set_log_path('/tmp/sqream_dbapi.log')\n con = pysqream_blue.connect('127.0.0.1', '80', use_logs=True, log_level='INFO')\n\nThe log level default is 'INFO', the logs level are ['INFO', 'DEBUG', 'CRITICAL', 'WARNING', 'ERROR']\n\nTODO (when server support):\n-----------------------------------------\n\n* use ssl connection.\n* send the token recived in authentication in every following request as call credentials (compile, execute, etc).\n* parametered queries / network insert.\n the existing code related to those points is a preparation and not reliable.\n\nDifferences from V1 pysqream (from user view):\n-----------------------------------------------\n* The parameters to connect function are different (some were removed and some were added).\n* SSL connection not supported.\n* `executemany()` (- network insert) not supported.\n\n\nDesign decisions:\n-----------------------------------------\n* The grpc chunnel and stubs are opened and closed by `__init__` and `__del__` methods (which call `_connect_to_server()` and `_disconnect_server()` where the implementation itself is).\n The authentication with sqream and receipt a token made by `connect_database()` method (while `close()` close it).\n User can call `close()` and then `connect_database()` for swiching between databases on the same server.\n It may make sense to decide to close the chunnel as well in `close()` method (which is a part of DB API).\n\n* The same chunnel and stubs used for all cursors of a connection but every cursor open his own token.\n it may make sense to decide to use different stubs or chunnel for every cursor or to use the same token for all.\n\n* Fetch methods return list of list and not list of tuple\n\nLicense-File: LICENSE\n",
"bugtrack_url": null,
"license": null,
"summary": "DB-API connector for SQream DB",
"version": "1.0.46",
"project_urls": {
"Homepage": "https://github.com/SQream/pysqream-blue"
},
"split_keywords": [
"database",
"db-api",
"sqream",
"sqreamdbv2"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0be41993dd30010d98f6a3b029ed451b7eff03205879ad6125388cf458fba193",
"md5": "cd56544e350f82019f90741a8d3d845d",
"sha256": "ec7ae883bb47b31b659eeabc2f1b8736ebacf7df887e8dcf5455898e3beb0f48"
},
"downloads": -1,
"filename": "pysqream_blue-1.0.46-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cd56544e350f82019f90741a8d3d845d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 29648,
"upload_time": "2024-04-14T14:46:37",
"upload_time_iso_8601": "2024-04-14T14:46:37.303807Z",
"url": "https://files.pythonhosted.org/packages/0b/e4/1993dd30010d98f6a3b029ed451b7eff03205879ad6125388cf458fba193/pysqream_blue-1.0.46-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "99a2c96cba8759f83f77b4e37935e7a1c331d198e706f9f95033dc1e5d05e60f",
"md5": "c59e97f300dd928551eb9c73b6594b5a",
"sha256": "8761c1e7de8c3ce8d087d4ffd18d5f8e7456dff359fabaeae092b4517e71f48a"
},
"downloads": -1,
"filename": "pysqream-blue-1.0.46.tar.gz",
"has_sig": false,
"md5_digest": "c59e97f300dd928551eb9c73b6594b5a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 25441,
"upload_time": "2024-04-14T14:46:39",
"upload_time_iso_8601": "2024-04-14T14:46:39.013778Z",
"url": "https://files.pythonhosted.org/packages/99/a2/c96cba8759f83f77b4e37935e7a1c331d198e706f9f95033dc1e5d05e60f/pysqream-blue-1.0.46.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-14 14:46:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SQream",
"github_project": "pysqream-blue",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "pysqream-blue"
}
JSON
