Add autocommit (#717)

* Add autocommit to features

Author: ArBridgeman

doc/changes/unreleased.md

@@ -18,3 +18,4 @@
 * #706: Added more single and multiple entry ORM examples
 * #712: Added to features information on: autoincremented columns, foreign keys, & automatic indexes
 * #714: Added to features information on: caching + more non-ORM examples
+* #716: Added to features information on: autocommit

doc/user_guide/examples/index.rst

@@ -11,6 +11,7 @@ Examples
    testing_connection
    non_orm/index.rst
    orm/index.rst
+   specific_focuses/index.rst
 
 SQLAlchemy-Exasol contains the following examples which are regularly verified in the CI to be correct.
 For a broader introduction and an overview, please see:
@@ -49,7 +50,7 @@ Some basic preparation steps are required to see the examples in action:
     - `exasol/docker-db <https://hub.docker.com/r/exasol/docker-db/tags>`__, which can be easily accessed by using ``poetry run -- nox -s db:start``
     - the free `Exasol Community Edition <https://www.exasol.com/free-signup-community-edition/>`__
 
-#. Open the ``/examples/`` directory and edit the file configuration file, as described in :ref:`example_configuration`.
+#. Open the ``/examples/`` directory and edit the configuration file, as described in :ref:`example_configuration`.
 #. To verify that your connection configuration is correct, run the code, as described in :ref:`example_connection`.
 #. Now, you may run whatever examples you would like:
 

doc/user_guide/examples/specific_focuses/autocommit.rst

@@ -0,0 +1,135 @@
+.. _autocommit:
+
+Autocommit
+==========
+
+These examples are meant to highlight best practices and allow users to explore the
+difference between having ``AUTOCOMMIT`` enabled versus disabled.
+
+Throughout our examples, we use ``engine.begin()``. Code inside of a with-block using
+``engine.begin()`` will behave the same whether ``AUTOCOMMIT``
+is enabled (``y``) or disabled (``n``). This is because ``engine.begin()`` automatically
+issues a ``COMMIT`` when the block successfully finished or a ``ROLLBACK`` if it fails.
+For any basic database modifications, the recommended best practice is to use
+``engine.begin()``. This is to ensure that the objects are in the desired state before
+performing further manipulation steps. While it is possible to use ``engine.connect()``
+instead, when ``AUTOCOMMIT`` is disabled, you must manually, inside of the with-block,
+call ``commit()``. For a more nuanced discussion, see :ref:`begin_or_connect`.
+
+To explore what changes when ``AUTOCOMMIT`` is set to ``n``, you can:
+
+1. Modify your configuration file, as described on :ref:`example_configuration`, to set
+   ``"AUTOCOMMIT":"n"``.
+2. Modify the code in the examples to use ``engine.connect()`` instead of
+   ``engine.begin()``.
+3. Try to execute the examples and see what happens. You should get failures, as
+   ``engine.connect()`` without ``AUTOCOMMIT`` requires you to manually call
+   ``conn.commit()`` as needed.
+4. Add ``conn.commit()`` to the examples and try to execute them. They should now pass.
+
+.. note::
+
+    The examples on this page are presented in sections, but they are all part
+    of the same module ``examples/features/specific_focuses/_1_autocommit.py``.
+    They are broken up here to provide further information and context. Please
+    ensure that you read and execute the parts in order.
+
+
+.. _ddl:
+
+Data Definition Language (DDL)
+------------------------------
+
+.. literalinclude:: ../../../../examples/features/specific_focuses/_1_autocommit.py
+       :language: python3
+       :caption: examples/features/specific_focuses/autocommit.py
+       :end-before: # 2. Data Query Language (DQL)
+
+
+It is recommended to use ``engine.begin()`` for DDL statements.
+
+.. note::
+
+    Note that ``IDENTITY``
+    (`an Exasol Database keyword <https://docs.exasol.com/db/latest/sql_references/data_types/identitycolumns.htm?Highlight=identity>`__)
+    **must** be included for the ID to autoincrement. This is not required for the
+    examples given in :ref:`examples_non_orm` or :ref:`examples_orm`, where SQLAlchemy
+    generates the required SQL statement for the Exasol database instance.
+
+Data Query Language (DQL)
+-------------------------
+
+.. literalinclude:: ../../../../examples/features/specific_focuses/_1_autocommit.py
+       :language: python3
+       :caption: examples/features/specific_focuses/autocommit.py
+       :start-at: # 2. Data Query Language (DQL)
+       :end-before: # 3. Data Manipulation Language (DML)
+
+Typically, ``SELECT`` is considered the only member of DQL. In such use cases, no data
+manipulations are occurring, so no manual commits need to be made. As such,
+this code works and should stay the same regardless of whether ``AUTOCOMMIT`` is
+enabled or disabled.
+
+Data Manipulation Language (DML)
+--------------------------------
+
+.. literalinclude:: ../../../../examples/features/specific_focuses/_1_autocommit.py
+       :language: python3
+       :caption: examples/features/specific_focuses/autocommit.py
+       :start-at: # 3. Data Manipulation Language (DML)
+
+Like the :ref:`ddl` example, it is preferred here to use ``begin()`` in the with-block.
+This behaves the same whether ``AUTOCOMMIT`` is enabled or disabled. For a
+more nuanced discussion, see :ref:`begin_or_connect`.
+
+.. _begin_or_connect:
+
+
+Connection Management in SQLAlchemy
+-----------------------------------
+
+.. _begin-method:
+
+The ``begin()`` Method
+^^^^^^^^^^^^^^^^^^^^^^
+
+The ``begin()`` method provides a **transactional boundary**. It is the safest choice
+for an operation that modifies the database.
+
+.. list-table:: When to use ``begin()``
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Scenario
+     - Description
+   * - DDL
+     - Use for ``CREATE``, ``ALTER``, or ``DROP`` commands to ensure schema changes are committed.
+   * - DML
+     - Ideal for ``INSERT``, ``UPDATE``, and ``DELETE`` where you want an "all-or-nothing" result.
+   * - Auto-Rollback
+     - If your code fails mid-block, SQLAlchemy automatically reverts any partial changes.
+
+.. _connect-method:
+
+The ``connect()`` Method
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``connect()`` method provides a **raw connection**. It offers granular control but
+places the responsibility of transaction management on the user.
+
+When ``AUTOCOMMIT`` is enabled, using ``connect()`` ensures that each statement is
+finalised by the database as soon as it is executed. If ``AUTOCOMMIT`` is disabled,
+then you must manually use ``commit``.
+
+.. list-table:: When to use ``connect()``
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Scenario
+     - Description
+   * - DQL
+     - Best for ``SELECT`` statements where no data is being changed.
+   * - DML
+     - Use if you need to commit specific parts of a long-running script at different times.
+   * - Performance Tuning
+     - Avoids the overhead of starting a transaction block when only reading data.

doc/user_guide/examples/specific_focuses/index.rst

@@ -0,0 +1,7 @@
+Specific Focuses
+================
+
+.. toctree::
+   :maxdepth: 2
+
+   autocommit

doc/user_guide/features/index.rst

@@ -3,6 +3,24 @@
 Features
 ========
 
+Autocommit
+----------
+
+By default, SQLAlchemy-Exasol has ``AUTOCOMMIT`` turned on, as mentioned in
+:ref:`dialect_specific_params`. This parameter is only relevant when using
+``engine.connect()``. When using ``engine.begin()``, the transaction, if the inner steps
+are successful, is always automatically committed at the end of the with-block.
+
+Committing or using autocommit ensures that any changes made during a transaction — such
+as inserts or updates — are permanently saved to the database. For more information on these
+patterns, please see :ref:`begin_or_connect` and these other resources:
+
+
+
+* Our :ref:`Autocommit Examples <autocommit>`
+* SQLAlchemy's `Working with Engines and Connections <https://docs.sqlalchemy.org/en/20/core/connections.html>`__
+* SQLAlchemy's `Transaction & Connection Management <https://docs.sqlalchemy.org/en/20/orm/session_transaction.html>`__
+
 Autoincremented Columns
 -----------------------
 

examples/features/specific_focuses/_1_autocommit.py

@@ -0,0 +1,60 @@
+from sqlalchemy import text
+
+from examples.config import (
+    DEFAULT_SCHEMA_NAME,
+    ENGINE,
+    SQL_ALCHEMY,
+)
+
+# 0. Ensure that the schema exists
+SQL_ALCHEMY.create_schema(engine=ENGINE, schema=DEFAULT_SCHEMA_NAME)
+
+# 1. Data Definition Language (DDL)
+TABLE_NAME = "HEX_LOOKUP"
+
+create_hex_table = f"""
+    CREATE OR REPLACE TABLE {DEFAULT_SCHEMA_NAME}.{TABLE_NAME} (
+        id INTEGER IDENTITY PRIMARY KEY,
+        hex_code CHAR(6) NOT NULL
+    );
+"""
+
+with ENGINE.begin() as conn:
+    conn.execute(text(create_hex_table))
+
+# 2. Data Query Language (DQL)
+query = f"""
+SELECT *
+FROM SYS.EXA_ALL_TABLES
+WHERE TABLE_SCHEMA = '{DEFAULT_SCHEMA_NAME}'
+AND TABLE_NAME = '{TABLE_NAME}'
+"""
+
+with ENGINE.connect() as conn:
+    results = conn.execute(text(query)).fetchall()
+    # conn.commit() is never needed for DQL
+
+print(f"Table search result: {results}")
+
+# 3. Data Manipulation Language (DML)
+hex_data = [{"hex_code": "FF5733"}, {"hex_code": "33FF57"}, {"hex_code": "3357FF"}]
+
+insert_statement = (
+    f"INSERT INTO {DEFAULT_SCHEMA_NAME}.{TABLE_NAME} " f"(hex_code) VALUES (:hex_code)"
+)
+with ENGINE.begin() as conn:
+    conn.execute(text(insert_statement), hex_data)
+    # if `ENGINE.connect()` were used instead of `ENGINE.begin()` and
+    # "AUTOCOMMIT" were disabled, you MUST include a `conn.commit()`
+    # for the change to be persisted; otherwise, no results will be
+    # found in #4,
+
+# 4. DQL
+select_statement = f"SELECT * FROM {DEFAULT_SCHEMA_NAME}.{TABLE_NAME}"
+
+with ENGINE.connect() as conn:
+    result = conn.execute(text(select_statement)).fetchall()
+
+    print(f"Number of entries: {len(result)}")
+    for row in result:
+        print(row)