Documentation/712 add smaller feature details (#713)

* Add information about indexes
* Add non-ORM examples
* Add new examples into docs and add autoincrement to feature
* Add details on foreign keys

Author: ArBridgeman

doc/changes/unreleased.md

@@ -16,3 +16,4 @@
 * #698: Updated Configuration pages
 * #703: Added ORM examples
 * #706: Added more single and multiple entry ORM examples
+* #712: Added to features information on: autoincremented columns, foreign keys, & automatic indexes

doc/user_guide/examples/index.rst

@@ -9,6 +9,7 @@ Examples
 
    connection_configuration
    testing_connection
+   non_orm/index.rst
    orm/index.rst
 
 SQLAlchemy-Exasol contains the following examples which are regularly verified in the CI to be correct.

doc/user_guide/examples/non_orm/create_tables.rst

@@ -0,0 +1,8 @@
+.. _example_non_orm_create_table:
+
+Creating Tables
+===============
+
+.. literalinclude:: ../../../../examples/features/non_orm/_0_create_tables.py
+       :language: python3
+       :caption: examples/features/non_orm/_0_create_tables.py

doc/user_guide/examples/non_orm/index.rst

@@ -0,0 +1,10 @@
+.. _examples_non_orm:
+
+Basic Operations
+================
+
+.. toctree::
+   :maxdepth: 2
+
+   create_tables
+   single_entry

doc/user_guide/examples/non_orm/single_entry.rst

@@ -0,0 +1,8 @@
+.. _example_non_orm_single_entry:
+
+Working with a Single Entry
+===========================
+
+.. literalinclude:: ../../../../examples/features/non_orm/_1_working_with_single_entry.py
+       :language: python3
+       :caption: examples/features/non_orm/_1_working_with_single_entry.py

doc/user_guide/features/index.rst

@@ -3,6 +3,81 @@
 Features
 ========
 
+Autoincremented Columns
+-----------------------
+
+In SQLAlchemy-Exasol, the autoincrement feature leverages Exasol's native
+`IDENTITY <https://docs.exasol.com/db/latest/sql_references/data_types/identitycolumns.htm>`__
+columns to automatically generate unique, sequential primary key values. To enable this
+behavior when defining a table, set ``primary_key=True`` as shown in the following examples:
+
+* :ref:`Create Table <example_non_orm_create_table>`
+* :ref:`Create Table with ORM <example_orm_create_table>`
+
+Once configured, Exasol generates a new ID on the server side whenever a new row is
+inserted.
+
+Automatic Indexes
+-----------------
+
+Exasol is a self-tuning database designed to eliminate the manual effort of performance
+optimization. Instead of requiring users to design and maintain indexes, the database
+engine intelligently generates and updates them on the fly during query execution to ensure
+optimal join and filter performance.
+
+For SQLALchemy-Exasol users, this means:
+
+* **Simplified Development**: You are free from the burden of manual index
+  management; the database handles it all for you.
+* **Automatic Performance**: Efficient indexes are created precisely when needed and
+  are automatically maintained or discarded based on usage.
+* **Optimized Storage**: Indexes are only persisted upon a successful transaction
+  commit, keeping your database clean and efficient.
+
+Because Exasol provides this built-in auto-tuning, manual index creation is not only
+unnecessary but intentionally unsupported to prevent interference with the engine's
+optimization algorithms. For more in-depth information, explore the Exasol documentation
+on `indexes <https://docs.exasol.com/db/latest/performance/indexes.htm>`__.
+
+Foreign Keys
+------------
+
+By default, Exasol does not enforce foreign keys or primary keys. Instead, they are
+primarily used as metadata to help the query optimizer create faster execution plans:
+
+* **Default State**: By default, constraints are created in a ``DISABLE`` state. This
+  means you can insert data that violates referential integrity without the database
+  stopping you.
+* **Enforcement Setting**: To prevent invalid data from being inserted, you can
+  explicitly set the constraint to ``ENABLE``.
+* **Performance Impact**: Exasol leaves them disabled by default because strict
+   enforcement adds overhead during high-speed data loading (DML operations).
+
+To see the status of your foreign key columns, check table
+`EXA_ALL_CONSTRAINTS <https://docs.exasol.com/db/latest/sql_references/system_tables/metadata/exa_all_constraints.htm>`__.
+
+To check what your system settings are, use this SQL statement:
+
+.. code-block:: sql
+
+    SELECT * FROM EXA_PARAMETERS
+    WHERE PARAMETER_NAME = 'CONSTRAINT_STATE_DEFAULT';
+
+
+To check a foreign key constraint without switching the constraint to ``ENABLE``, see
+`Verification of the Foreign Key Property <https://docs.exasol.com/db/latest/sql/foreignkey.htm>`__.
+
+To switch a constraint to ``ENABLE``, choose which SQL statement suits your purposes best:
+
+.. code-block:: sql
+
+    -- For a specific constraint
+    ALTER TABLE <table_name> MODIFY CONSTRAINT <constraint_name> ENABLE;
+
+    -- For global enforcement, which will degrade performance
+    ALTER SYSTEM SET DEFAULT_CONSTRAINT_STATE = 'ENABLE';
+
+
 .. _orm:
 
 Object-Relational Mapping
@@ -17,7 +92,7 @@ that ensures data consistency.
 
 .. note::
 
-    * To get started, check out our :ref:`examples_orm`.
+    * To get started, check out our :ref:`ORM Examples <examples_orm>`.
     * For more examples & details, see SQLAlchemy's
       `ORM Quick Start <https://docs.sqlalchemy.org/en/20/orm/quickstart.html>`__
       and `ORM Index <https://docs.sqlalchemy.org/en/20/orm/index.html>`__.

examples/features/non_orm/_0_create_tables.py

@@ -0,0 +1,44 @@
+from sqlalchemy import (
+    Column,
+    ForeignKey,
+    Integer,
+    MetaData,
+    String,
+    Table,
+)
+
+from examples.config import (
+    DEFAULT_SCHEMA_NAME,
+    ENGINE,
+    SQL_ALCHEMY,
+)
+
+# 1. Ensure that the schema exists
+SQL_ALCHEMY.create_schema(engine=ENGINE, schema=DEFAULT_SCHEMA_NAME)
+
+# 2. Use the schema to define the metadata_obj, which is used in the `Base` class
+metadata_obj = MetaData(schema=DEFAULT_SCHEMA_NAME)
+
+
+metadata = MetaData()
+
+# 3. Define tables
+user_table = Table(
+    "user",
+    metadata,
+    Column("id", Integer, primary_key=True),
+    Column("first_name", String(30), nullable=False),
+    Column("last_name", String(30), nullable=False),
+)
+
+email_address_table = Table(
+    "email_address",
+    metadata,
+    Column("id", Integer, primary_key=True),
+    Column("email_address", String(100), nullable=False),
+    Column("user_id", Integer, ForeignKey("user.id")),
+)
+
+# 4. Create all tables
+with ENGINE.begin() as conn:
+    metadata.create_all(conn)

examples/features/non_orm/_1_working_with_single_entry.py

@@ -0,0 +1,85 @@
+from sqlalchemy import (
+    delete,
+    insert,
+    join,
+    select,
+    update,
+)
+
+from examples.config import ENGINE
+from examples.features.non_orm._0_create_tables import (
+    email_address_table,
+    user_table,
+)
+
+# 1. Clean tables and Insert
+with ENGINE.begin() as conn:
+    # a. clean tables
+    conn.execute(delete(email_address_table))
+    conn.execute(delete(user_table))
+
+    # b. Insert user
+    conn.execute(insert(user_table).values(first_name="Jax", last_name="Doe"))
+
+    # c. Use a SELECT statement to get the user ID
+    select_stmt = select(user_table.c.id).where(
+        user_table.c.first_name == "Jax", user_table.c.last_name == "Doe"
+    )
+    user_id = conn.execute(select_stmt).scalar()
+
+    # d. Insert email_address
+    conn.execute(
+        insert(email_address_table).values(
+            user_id=user_id, email_address="jax.doe@example.com"
+        )
+    )
+
+
+# 2. Select with a join
+def select_all_entries():
+    with ENGINE.connect() as conn:
+        j = join(
+            user_table,
+            email_address_table,
+            user_table.c.id == email_address_table.c.user_id,
+            isouter=True,
+        )
+        stmt = select(user_table, email_address_table.c.email_address).select_from(j)
+
+        for row in conn.execute(stmt):
+            print(f"{row.id} {row.first_name} {row.last_name} [{row.email_address}]")
+
+
+select_all_entries()
+
+# 3. Update (Atomic execution)
+with ENGINE.begin() as conn:
+    # a. Update User
+    conn.execute(
+        update(user_table)
+        .where(user_table.c.first_name == "Jax")
+        .values(first_name="Paris")
+    )
+    # b. Update Email (using a subquery or join-like syntax depending on logic)
+    conn.execute(
+        update(email_address_table)
+        .where(email_address_table.c.email_address == "jax.doe@example.com")
+        .values(email_address="paris.doe@example.com")
+    )
+
+# 4. Delete
+with ENGINE.begin() as conn:
+    # a. Get the IDs of the users you want to delete
+    user_ids_stmt = select(user_table.c.id).where(user_table.c.first_name == "Paris")
+    user_ids = conn.execute(user_ids_stmt).scalars().all()
+
+    if user_ids:
+        # b. Delete related emails first
+        conn.execute(
+            delete(email_address_table).where(
+                email_address_table.c.user_id.in_(user_ids)
+            )
+        )
+
+        # c. Now delete the user
+        conn.execute(delete(user_table).where(user_table.c.id.in_(user_ids)))