docs(advanced/sa_column): add clean outputs; show encrypted ciphertext with sa_column; tidy examples and messages

Author: ravishan16

docs/advanced/sa-column.md

@@ -61,6 +61,24 @@ After running, you should see "Database and tables created." and a `database_enc
 If you change the encryption key between runs, delete `database_encrypted.db` first so existing ciphertext doesn’t fail to decrypt with the new key.
 ///
 
+### Output
+
+```
+Adding Hero 1: Ted Lasso
+Adding Hero 2: Roy Kent
+Adding Hero 3: Keeley Jones
+Inserted 3 heroes.
+
+Selecting by name: Ted Lasso
+Hero 1: id=1 name='Ted Lasso' secret_name='Coach' age=None
+Hero 1 secret_name (decrypted in Python): Coach
+Hero 1 secret_name (stored in DB, encrypted): omSF3WBuflYmqx2+Dz6PgQ==
+
+Selecting by name: Roy Kent
+Hero 2: id=2 name='Roy Kent' secret_name='Roy' age=None
+Hero 2 secret_name (decrypted in Python): Roy
+```
+
 ## Use case: enforcing uniqueness
 
 - Single‑column unique: You can express this using `Field(unique=True)` in SQLModel or directly on the SQLAlchemy `Column(...)` when using `sa_column` for full control (e.g., to set a specific SQL type or name).
@@ -91,6 +109,24 @@ python app.py
 
 After running, you should see the selected rows printed, with a database created at `database_unique.db`. Attempting to insert a duplicate `email` (single‑column unique) or a duplicate pair of `(name, secret_name)` (composite unique) would raise an integrity error.
 
+### Output
+
+```
+Adding Hero 1: Ted Lasso ([email protected])
+Adding Hero 2: Roy Kent ([email protected])
+Adding Hero 3: Keeley Jones ([email protected])
+Inserted 3 heroes.
+
+Attempting to insert a duplicate (name, secret_name) ...
+Composite unique constraint enforced: UNIQUE constraint failed: hero.name, hero.secret_name
+
+Selecting by email (unique column):
+Hero 1: name='Ted Lasso' id=1 age=None secret_name='Coach' email='[email protected]'
+
+Selecting by composite key (name, secret_name):
+Hero 2: name='Roy Kent' id=2 age=None secret_name='Roy' email='[email protected]'
+```
+
 ## Important considerations
 
 - **Prefer** built‑in `Field()` parameters (like `unique=True`, `index=True`, `default=...`) when they are sufficient.

docs_src/advanced/sa_column/tutorial001.py

@@ -30,10 +30,13 @@ class Hero(SQLModel, table=True):
 
 sqlite_file_name = "database_encrypted.db"
 sqlite_url = f"sqlite:///{sqlite_file_name}"
-engine = create_engine(sqlite_url, echo=True)
+engine = create_engine(sqlite_url)
 
 
 def create_db_and_tables() -> None:
+    # Reset DB for demo so decryption key changes don't break runs
+    if os.path.exists(sqlite_file_name):
+        os.remove(sqlite_file_name)
     SQLModel.metadata.create_all(engine)
 
 
@@ -43,19 +46,32 @@ def create_heroes() -> None:
     hero_3 = Hero(name="Keeley Jones", secret_name="Keeley", age=29)
 
     with Session(engine) as session:
+        print("Adding Hero 1: Ted Lasso")
+        print("Adding Hero 2: Roy Kent")
+        print("Adding Hero 3: Keeley Jones")
         session.add(hero_1)
         session.add(hero_2)
         session.add(hero_3)
         session.commit()
+        print("Inserted 3 heroes.\n")
 
 
 def select_heroes() -> None:
     with Session(engine) as session:
+        print("Selecting by name: Ted Lasso")
         statement = select(Hero).where(Hero.name == "Ted Lasso")
         hero_1 = session.exec(statement).one()
         print("Hero 1:", hero_1)
         print("Hero 1 secret_name (decrypted in Python):", hero_1.secret_name)
-
+        # Read the raw encrypted value directly from the DB (bypassing type decryption)
+        with engine.connect() as conn:
+            raw_encrypted = conn.exec_driver_sql(
+                "SELECT secret_name FROM hero WHERE name = ?",
+                ("Ted Lasso",),
+            ).scalar_one()
+            print("Hero 1 secret_name (stored in DB, encrypted):", raw_encrypted)
+
+        print("\nSelecting by name: Roy Kent")
         statement = select(Hero).where(Hero.name == "Roy Kent")
         hero_2 = session.exec(statement).one()
         print("Hero 2:", hero_2)

docs_src/advanced/sa_column/tutorial002.py

@@ -1,52 +1,69 @@
+import os
 from typing import Optional
 
 from sqlalchemy import Column, String, UniqueConstraint
+from sqlalchemy.exc import IntegrityError
 from sqlmodel import Field, Session, SQLModel, create_engine, select
 
 
 class Hero(SQLModel, table=True):
     id: Optional[int] = Field(default=None, primary_key=True)
-    # Single-column unique using sa_column for full control (e.g., explicit SQL type and nullability)
+    # Single-column unique via sa_column
     email: str = Field(sa_column=Column(String(255), unique=True, nullable=False))
     name: str
     secret_name: str
     age: Optional[int] = None
 
-    # Composite (multi-column) unique constraint using the idiomatic SQLAlchemy approach
+    # Composite unique constraint
     __table_args__ = (
         UniqueConstraint("name", "secret_name", name="uq_hero_name_secret"),
     )
 
 
 sqlite_file_name = "database_unique.db"
 sqlite_url = f"sqlite:///{sqlite_file_name}"
-engine = create_engine(sqlite_url, echo=True)
+engine = create_engine(sqlite_url)
 
 
 def create_db_and_tables() -> None:
+    # Reset DB for demo
+    if os.path.exists(sqlite_file_name):
+        os.remove(sqlite_file_name)
     SQLModel.metadata.create_all(engine)
 
 
 def create_heroes() -> None:
-    hero_1 = Hero(email="[email protected]", name="Ted Lasso", secret_name="Coach")
-    hero_2 = Hero(email="[email protected]", name="Roy Kent", secret_name="Roy")
-    hero_3 = Hero(
-        email="[email protected]", name="Keeley Jones", secret_name="Keeley"
-    )
-
     with Session(engine) as session:
-        session.add(hero_1)
-        session.add(hero_2)
-        session.add(hero_3)
+        hero_1 = Hero(email="[email protected]", name="Ted Lasso", secret_name="Coach")
+        hero_2 = Hero(email="[email protected]", name="Roy Kent", secret_name="Roy")
+        hero_3 = Hero(email="[email protected]", name="Keeley Jones", secret_name="Keeley")
+
+        print("Adding Hero 1: Ted Lasso ([email protected])")
+        print("Adding Hero 2: Roy Kent ([email protected])")
+        print("Adding Hero 3: Keeley Jones ([email protected])")
+        session.add_all([hero_1, hero_2, hero_3])
         session.commit()
+        print("Inserted 3 heroes.\n")
+
+        # Duplicate (name, secret_name) should fail (different email)
+        hero_4 = Hero(email="[email protected]", name="Roy Kent", secret_name="Roy")
+        try:
+            print("Attempting to insert a duplicate (name, secret_name) ...")
+            session.add(hero_4)
+            session.commit()
+        except IntegrityError as e:
+            session.rollback()
+            print("Composite unique constraint enforced:", str(e.orig))
 
 
 def select_heroes() -> None:
     with Session(engine) as session:
+        print("\nSelecting by email (unique column):")
         statement = select(Hero).where(Hero.email == "[email protected]")
         hero_1 = session.exec(statement).one()
         print("Hero 1:", hero_1)
 
+        print("\nSelecting by composite key (name, secret_name):")
         statement = select(Hero).where(
             (Hero.name == "Roy Kent") & (Hero.secret_name == "Roy")
         )