=================
sqlalchemy-hsqldb
=================
SQLAlchemy dialect for HyperSQL 2.0 (HSQLDB)
Description
-----------
The objective of this project is to enable
`SQLAlchemy <https://www.sqlalchemy.org/>`_ support for
`HyperSQL <https://hsqldb.org/>`_ 2.0 databases (a.k.a. HSQLDB).
As an initial release this version has limitations and still contains much
debug code. However the great news is "It works on my Windows based system",
currently passing about 38 percent of the dialect test suite.
Testing on other environments will follow in due course.
This project depends on a modified version of the
`JayDeBeApi <https://github.com/baztian/jaydebeapi>`_ module to provide
JDBC connectivity and a DB-API 2.0 interface. The module should install itself
automatically. If not, my project can be found here on GitHub:
`jaydebeapi-hsqldb <https://github.com/Pebble94464/jaydebeapi-hsqldb.git>`_
License
-------
sqlalchemy-hsqldb is distributed under the
`MIT license <https://opensource.org/licenses/MIT>`_.
Prerequisites
-------------
You'll need a copy of the Java Runtime Environment (JRE) installed, or Java
Development Kit (JDK). See: `www.java.com <https://www.java.com/>`_
You'll also need an HyperSQL 2.0 database running as a service, which can be
accessed by specifying a URL (not a file URL). See:
`hsqldb.org <https://hsqldb.org/>`_
Older versions of HyperSQL are not currently supported, including those used by
OpenOffice.org and LibreOffce. This may change in the future. However both
applications can be configured relatively easily to connect to a HyperSQL 2.0
database.
Please ensure the architecture of any software components installed match,
including Java and Python environments, HyperSQL, and applications used.
Mixing 32 and 64-bit software is not advised.
Installation
------------
Packages for installing sqlalchemy-hsqldb will soon be available from
`pypi.org <https://pypi.org/>`_
To install sqlalchemy-hsqldb from pypi.org, open a command prompt and type:
.. code-block:: sh
pip install sqlalchemy-hsqldb
Alternatively the dialect and its driver can be downloaded from the
repositories on GitHub:
* Dialect: `sqlalchemy-hsqldb repository <https://github.com/Pebble94464/sqlalchemy-hsqldb.git>`_
* Driver: `jaydebeapi-hsqldb repository <https://github.com/Pebble94464/jaydebeapi-hsqldb.git>`_
The driver module probably needs installing before the dialect. Use the
'pip install <path>' syntax to install, where <path> points to where your local
copy is installed.
.. code-block:: sh
pip install ./jaydebeapi-hsqldb
pip install ./sqlalchemy-hsqldb
Post-install Configuration
--------------------------
Your system needs to know where the Java Runtime Environment is installed.
If not detected automatically you may need to add 'JAVA_HOME' or 'JRE_HOME'
to your environment variables.
.. code-block:: sh
set "JAVA_HOME=C:\Program Files\Java\jre-1.8\bin"
The jaydebeapi-hsqldb module also needs to know where HyperSQL's JAR file is
located. At the moment this can be specified using another environment
variable named 'CLASSPATH', (but this method of specifing the location will
likely change in a future release). For example, on Windows...
.. code-block:: sh
set "CLASSPATH=/some_folder/hsqldb-osgi-jdk8.jar"
Getting Started
---------------
After the dialect and prerequisites have been installed and configured we can
begin writing Python code. The example below is provided as a minimal example,
designed to get you connected to the database as quickly as possible, but you
will need to update some parameters to match your configuration.
.. code-block:: python
from sqlalchemy import create_engine
import os
# Set 'JAVA_HOME' or 'JRE_HOME' environment variables to the path of your
# Java installation (this step might not be required)...
os.environ['JAVA_HOME'] = "C:\\Program Files\\Java\\jre-1.8\\bin"
# Tell jaydebeapi-hsqldb where your HyperSQL jar file is installed...
os.environ['CLASSPATH'] = "/PROGS/HSQLDB/hsqldb-osgi-jdk8.jar"
if __name__ == '__main__':
# Call SQLAlchemy's create_engine function with your connection string.
# The basic format is:
# <dialect+driver>://<user>:<password>@<hostname>:<port>/<db name>
engine = create_engine("hsqldb+jaydebeapi://SA:@localhost/db1", echo=True)
try:
conn = engine.connect()
version = engine.dialect._get_server_version_info(conn)
assert isinstance(version,str) and len(version) > 0, 'Version string is missing.'
print(f'\nSuccessfully connected!\nHSQLDB version: {version}\n')
conn.close()
except Exception as e:
print(f'\n{repr(e)}\n{str(e)}\n')
If all goes well you should see a success message displayed, otherwise an error
message will provide some hint as to why it's not working.
Known issues
------------
This initial release contains some debug code that will cause execution to
halt. Due to be removed in the next release.
Troubleshooting
---------------
This project was coded and tested on a 64-bit Windows system. It should work on
other platforms too, but you may find the code examples and docs need adapting.
If you're struggling to get sqlalchemy-hsqldb working here are a few things you can try:
* Avoid mixing 32-bit and 64-bit software components
* If the Java Runtime Environment (JRE) is not automatically detected you may need to add 'JAVA_HOME' or 'JRE_HOME' to your environment variables.
* If using HyperSQL in conjunction with other software such as OpenOffice.org or LibreOffce, verify they're working first.
* If you suspect a permissions issue, try installing and running with an administrator account.
* If you suspect a firewall issue, temporarily disable the firewall to see if this is the case.
* If you suspect some other configuration issue, ensure all paths specified are correct. Use back slashes or forward slashes as appropriate for your OS. Do they need escaping?
* Submit a question via StackOverflow!
It's quite possible others have already encountered the same issue and SO can
often provide a quick response. Tag your question with an appropriate tag, such
as 'sqlalchemy-hsqldb', which I can then monitor.
If you think you've found a bug please feel welcome to submit a report via GitHub:
* `sqlalchemy-hsqldb issues <https://github.com/Pebble94464/sqlalchemy-hsqldb/issues>`_
* `jaydebeapi-hsqldb issues <https://github.com/Pebble94464/jaydebeapi-hsqldb/issues>`_
Changelog
---------
0.1.0 initial release
Raw data
{
"_id": null,
"home_page": "https://github.com/Pebble94464/sqlalchemy-hsqldb",
"name": "sqlalchemy-hsqldb",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "SQLAlchemy dialect hsqld hsqldb hypersql",
"author": "Pebble94464",
"author_email": "sqlalchemy-hsqldb@pebble.plus.com",
"download_url": "https://files.pythonhosted.org/packages/6d/84/2021b91d8564d2c60199ab8644a9da77da1cbba16221c9bcbf655fe084b5/sqlalchemy_hsqldb-0.1.0.tar.gz",
"platform": null,
"description": "=================\r\nsqlalchemy-hsqldb\r\n=================\r\nSQLAlchemy dialect for HyperSQL 2.0 (HSQLDB)\r\n\r\nDescription\r\n-----------\r\nThe objective of this project is to enable \r\n`SQLAlchemy <https://www.sqlalchemy.org/>`_ support for\r\n`HyperSQL <https://hsqldb.org/>`_ 2.0 databases (a.k.a. HSQLDB).\r\n\r\nAs an initial release this version has limitations and still contains much\r\ndebug code. However the great news is \"It works on my Windows based system\",\r\ncurrently passing about 38 percent of the dialect test suite.\r\nTesting on other environments will follow in due course.\r\n\r\nThis project depends on a modified version of the\r\n`JayDeBeApi <https://github.com/baztian/jaydebeapi>`_ module to provide\r\nJDBC connectivity and a DB-API 2.0 interface. The module should install itself\r\nautomatically. If not, my project can be found here on GitHub:\r\n`jaydebeapi-hsqldb <https://github.com/Pebble94464/jaydebeapi-hsqldb.git>`_\r\n\r\nLicense\r\n-------\r\nsqlalchemy-hsqldb is distributed under the\r\n`MIT license <https://opensource.org/licenses/MIT>`_.\r\n\r\nPrerequisites\r\n-------------\r\nYou'll need a copy of the Java Runtime Environment (JRE) installed, or Java\r\nDevelopment Kit (JDK). See: `www.java.com <https://www.java.com/>`_\r\n\r\nYou'll also need an HyperSQL 2.0 database running as a service, which can be\r\naccessed by specifying a URL (not a file URL). See:\r\n`hsqldb.org <https://hsqldb.org/>`_\r\n\r\nOlder versions of HyperSQL are not currently supported, including those used by\r\nOpenOffice.org and LibreOffce. This may change in the future. However both\r\napplications can be configured relatively easily to connect to a HyperSQL 2.0\r\ndatabase.\r\n\r\nPlease ensure the architecture of any software components installed match,\r\nincluding Java and Python environments, HyperSQL, and applications used.\r\nMixing 32 and 64-bit software is not advised.\r\n\r\nInstallation\r\n------------\r\n\r\nPackages for installing sqlalchemy-hsqldb will soon be available from\r\n`pypi.org <https://pypi.org/>`_\r\nTo install sqlalchemy-hsqldb from pypi.org, open a command prompt and type:\r\n\r\n.. code-block:: sh\r\n\r\n\tpip install sqlalchemy-hsqldb\r\n\r\nAlternatively the dialect and its driver can be downloaded from the\r\nrepositories on GitHub:\r\n\r\n* Dialect: `sqlalchemy-hsqldb repository <https://github.com/Pebble94464/sqlalchemy-hsqldb.git>`_\r\n* Driver: `jaydebeapi-hsqldb repository <https://github.com/Pebble94464/jaydebeapi-hsqldb.git>`_\r\n\r\nThe driver module probably needs installing before the dialect. Use the\r\n'pip install <path>' syntax to install, where <path> points to where your local\r\ncopy is installed.\r\n\r\n.. code-block:: sh\r\n\r\n\tpip install ./jaydebeapi-hsqldb\r\n\tpip install ./sqlalchemy-hsqldb\r\n\r\nPost-install Configuration\r\n--------------------------\r\nYour system needs to know where the Java Runtime Environment is installed.\r\nIf not detected automatically you may need to add 'JAVA_HOME' or 'JRE_HOME'\r\nto your environment variables.\r\n\r\n.. code-block:: sh\r\n\r\n\tset \"JAVA_HOME=C:\\Program Files\\Java\\jre-1.8\\bin\"\r\n\r\nThe jaydebeapi-hsqldb module also needs to know where HyperSQL's JAR file is\r\nlocated. At the moment this can be specified using another environment\r\nvariable named 'CLASSPATH', (but this method of specifing the location will\r\nlikely change in a future release). For example, on Windows...\r\n.. code-block:: sh\r\n\r\n\tset \"CLASSPATH=/some_folder/hsqldb-osgi-jdk8.jar\"\r\n\r\nGetting Started\r\n---------------\r\nAfter the dialect and prerequisites have been installed and configured we can\r\nbegin writing Python code. The example below is provided as a minimal example,\r\ndesigned to get you connected to the database as quickly as possible, but you\r\nwill need to update some parameters to match your configuration.\r\n\r\n.. code-block:: python\r\n\r\n\tfrom sqlalchemy import create_engine\r\n\r\n\timport os\r\n\r\n\t# Set 'JAVA_HOME' or 'JRE_HOME' environment variables to the path of your\r\n\t# Java installation (this step might not be required)...\r\n\tos.environ['JAVA_HOME'] = \"C:\\\\Program Files\\\\Java\\\\jre-1.8\\\\bin\"\r\n\r\n\t# Tell jaydebeapi-hsqldb where your HyperSQL jar file is installed...\r\n\tos.environ['CLASSPATH'] = \"/PROGS/HSQLDB/hsqldb-osgi-jdk8.jar\"\r\n\r\n\tif __name__ == '__main__':\r\n\r\n\t\t# Call SQLAlchemy's create_engine function with your connection string.\r\n\t\t# The basic format is:\r\n\t\t# <dialect+driver>://<user>:<password>@<hostname>:<port>/<db name>\r\n\t\tengine = create_engine(\"hsqldb+jaydebeapi://SA:@localhost/db1\", echo=True)\r\n\r\n\t\ttry:\r\n\t\t\tconn = engine.connect()\r\n\t\t\tversion = engine.dialect._get_server_version_info(conn)\r\n\t\t\tassert isinstance(version,str) and len(version) > 0, 'Version string is missing.'\r\n\t\t\tprint(f'\\nSuccessfully connected!\\nHSQLDB version: {version}\\n')\r\n\t\t\tconn.close()\r\n\t\texcept Exception as e:\r\n\t\t\tprint(f'\\n{repr(e)}\\n{str(e)}\\n')\r\n\r\nIf all goes well you should see a success message displayed, otherwise an error\r\nmessage will provide some hint as to why it's not working.\r\n\r\nKnown issues\r\n------------\r\n\r\nThis initial release contains some debug code that will cause execution to\r\nhalt. Due to be removed in the next release.\r\n\r\nTroubleshooting\r\n---------------\r\n\r\nThis project was coded and tested on a 64-bit Windows system. It should work on \r\nother platforms too, but you may find the code examples and docs need adapting.\r\n\r\nIf you're struggling to get sqlalchemy-hsqldb working here are a few things you can try:\r\n\r\n* Avoid mixing 32-bit and 64-bit software components\r\n* If the Java Runtime Environment (JRE) is not automatically detected you may need to add 'JAVA_HOME' or 'JRE_HOME' to your environment variables.\r\n* If using HyperSQL in conjunction with other software such as OpenOffice.org or LibreOffce, verify they're working first.\r\n* If you suspect a permissions issue, try installing and running with an administrator account.\r\n* If you suspect a firewall issue, temporarily disable the firewall to see if this is the case.\r\n* If you suspect some other configuration issue, ensure all paths specified are correct. Use back slashes or forward slashes as appropriate for your OS. Do they need escaping?\r\n\r\n* Submit a question via StackOverflow!\r\n\tIt's quite possible others have already encountered the same issue and SO can\r\n\toften provide a quick response. Tag your question with an appropriate tag, such\r\n\tas 'sqlalchemy-hsqldb', which I can then monitor.\r\n\r\nIf you think you've found a bug please feel welcome to submit a report via GitHub:\r\n\r\n* `sqlalchemy-hsqldb issues <https://github.com/Pebble94464/sqlalchemy-hsqldb/issues>`_\r\n* `jaydebeapi-hsqldb issues <https://github.com/Pebble94464/jaydebeapi-hsqldb/issues>`_\r\n\r\nChangelog\r\n---------\r\n\t0.1.0\tinitial release\r\n\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "SQLAlchemy dialect for HyperSQL 2.0 (HSQLDB)",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/Pebble94464/sqlalchemy-hsqldb/wiki",
"Homepage": "https://github.com/Pebble94464/sqlalchemy-hsqldb",
"Source": "https://github.com/Pebble94464/sqlalchemy-hsqldb",
"Tracker": "https://github.com/Pebble94464/sqlalchemy-hsqldb/issues"
},
"split_keywords": [
"sqlalchemy",
"dialect",
"hsqld",
"hsqldb",
"hypersql"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "80e529143500c9616155ef557ca62913d1764e19b2a96ce903acb3d61050e1ae",
"md5": "e2ea91da36c9a2fb1f6684f63f24a72a",
"sha256": "b103a726a2a7c0a1d4bf4731335503421381dc9ebed3378fc3c7e205fcea4bd5"
},
"downloads": -1,
"filename": "sqlalchemy_hsqldb-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e2ea91da36c9a2fb1f6684f63f24a72a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 39804,
"upload_time": "2024-12-07T10:23:06",
"upload_time_iso_8601": "2024-12-07T10:23:06.336349Z",
"url": "https://files.pythonhosted.org/packages/80/e5/29143500c9616155ef557ca62913d1764e19b2a96ce903acb3d61050e1ae/sqlalchemy_hsqldb-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6d842021b91d8564d2c60199ab8644a9da77da1cbba16221c9bcbf655fe084b5",
"md5": "92269f572e710a2ddc53206765d6a234",
"sha256": "8fa8735d5b14f1b3fe86380db095d88cd6990d52f678eebeff70cbd9abcb2839"
},
"downloads": -1,
"filename": "sqlalchemy_hsqldb-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "92269f572e710a2ddc53206765d6a234",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 46828,
"upload_time": "2024-12-07T10:23:08",
"upload_time_iso_8601": "2024-12-07T10:23:08.403052Z",
"url": "https://files.pythonhosted.org/packages/6d/84/2021b91d8564d2c60199ab8644a9da77da1cbba16221c9bcbf655fe084b5/sqlalchemy_hsqldb-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-07 10:23:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Pebble94464",
"github_project": "sqlalchemy-hsqldb",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "sqlalchemy-hsqldb"
}
JSON
