Developer Guide

This guide contains information helpful when you want to engage in development of this project. sqlalchemy-exasol provides an Exasol dialect for sqlalchemy. For further information on the creation of a dialect, see SQLAlchemy’s README.dialects.rst.

Note

This project uses the features of the Exasol-Python-Toolbox. These features include: common Git hooks, CI/CD templates, common task sessions via nox, a standardized release preparation & triggering, etc.

Prerequisites

Tools

Locale

Make sure the locale is set up appropriately.

Example: Set up an English locale

sed -i -e 's/# en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/' /etc/locale.gen && locale-gen
export LANG=en_US.UTF-8

Set up Your Workspace

  1. Get the Source Code
    git clone https://github.com/exasol/sqlalchemy-exasol.git
  2. Set up the Tooling & Virtual Environment
    poetry env use python3.10
poetry install
  3. Install the Git Hooks

    A .pre-commit-config.yaml is included in the source code. Follow the instructions provided on the Exasol-Python-Toolbox’s page for Git hooks.

Task Runner (Nox)

Most repeating and complex tasks within this project are automated using the session runner nox. To get an overview about the available sessions just run:

poetry run -- nox -l

To run a specific task, execute the following command:

poetry run -- nox -s <task-name>

You can modify or add a new task by editing the noxfile.py file. For details, please see the User Guide of the Exasol-Python-Toolbox.

Running tests

Note

If you manually run some integration tests or want to try a database-related operation out:

# to start a test database
poetry run -- nox -s db:start -- --db-version <db_version>
# to stop a test database
poetry run -- nox -s db:stop

Unit Tests

The unit tests are located in the directory test/unit.

poetry run -- nox -s test:unit

Integration Tests

The integration tests are located in the directory test/integration.

Attention

A Docker container with a test database needs to be started for the integration tests. If a test group is not working or unclear, you may want to look into the CI/CD workflows files.

The integration tests are split into three groups to reduce the likelihood of test side effects:

  1. The SQLAlchemy Conformance Test Suite

    The SQLAlchemy conformance test suite is provided and maintained by the sqlalchemy project and intended to support third party dialect developers. For further details, see also README.dialects.rst. In general, if Exasol does not support a feature for a test, it is preferred to use a pytest.mark.xfail marker (rather than to skip the test or modify the sqlalchemy_exasol.requirements.py). An xfail provides continuous feedback that an expected error is being raised, and is preferred as both SQLAlchemy and Exasol Databases are being updated, and it is possible that a future version may include this feature or require minor modifications for this to work.

    poetry run -- nox -s test:sqla -- --connector websocket

  2. Our Custom Exasol Test Suite

    The Exasol test suite consists of tests written and maintained by Exasol. These have a slight reliance upon the generic test classes provided by the SQLAlchemy Conformance Test Suite. This can sometimes prove problematic when the SQLAlchemy version is increased, as all of these tests may initially fail until the issue has been resolved.

    poetry run -- nox -s test:exasol -- --connector websocket

  3. Regression Test Suite

    This is an extension to the custom Exasol test suite that ensures that previously reported bugs are not experienced by customers as there are upgrades to the SQLAlchemy API and Exasol databases.

    poetry run -- nox -s test:regression -- --connector websocket

Attention

The Exasol database does do implicit schema/context changes (open & close schema) in certain scenarios. Keep this in mind when setting up (writing) tests.

  1. CREATE SCHEMA implicitly changes the CURRENT_SCHEMA context

    When you create a new schema, you implicitly open this new schema.

  2. DROP SCHEMA sometimes switches the context to <null>

    If the CURRENT_SCHEMA is dropped, an implicit context switch to <null> is done

For further details, have a look at the Exasol-Documentation.

Note

Creating/Using a new un-pooled connection can be used for protecting against this side effect.

Preparing & Triggering a Release

The Exasol-Python-Toolbox provides nox sessions to semi-automate the release process:

# prepare a release
poetry run -- nox -s release:prepare -- --type {major,minor,patch}

# trigger a release
poetry run -- nox -s release:trigger

For further information, please refer to the Exasol-Python-Toolbox’s page Creating a Release.