vault backup: 2026-05-30 16:02:33

note/python/python tool/SQLAlchemy-Tutorial.md

@@ -0,0 +1,176 @@
+# SQLAlchemy 2.0 Tutorial (Recipe Scraper Edition)
+
+This guide covers SQLAlchemy 2.0, the industry-standard SQL toolkit and Object-Relational Mapper (ORM) for Python. We'll use the **Recipe Web Scraper** project models as our primary examples.
+
+---
+
+## 1. What is SQLAlchemy?
+
+SQLAlchemy has two main components:
+1.  **Core**: A SQL abstraction layer (SQL Expression Language, Schema definitions, Engine).
+2.  **ORM**: A layer on top of Core that maps Python classes to database tables.
+
+In this project, we primarily use the **ORM** to treat recipes and ingredients as Python objects.
+
+---
+
+## 2. Defining Models (The Modern Way)
+
+SQLAlchemy 2.0 introduced a type-hint-centric way to define models using `Mapped` and `mapped_column`.
+
+### The Base Class
+All models inherit from a common `Base` class created from `DeclarativeBase`.
+
+```python
+from sqlalchemy.orm import DeclarativeBase
+
+class Base(DeclarativeBase):
+    pass
+```
+
+### Example: The Recipe Model
+```python
+from sqlalchemy import String, Integer, DateTime
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from datetime import datetime
+
+class Recipe(Base):
+    __tablename__ = "recipes"  # Name of the table in the DB
+    
+    # Primary Key
+    id: Mapped[int] = mapped_column(primary_key=True)
+    
+    # Simple Columns (SQLAlchemy infers types from Mapped[T])
+    url: Mapped[str] = mapped_column(String, unique=True, index=True)
+    title: Mapped[str]
+    total_time: Mapped[int | None] # Optional column (nullable=True)
+    
+    # Column with a default value
+    scraped_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+
+    # Relationships (Defined in section 4)
+    ingredients: Mapped[list["Ingredient"]] = relationship(back_populates="recipe")
+```
+
+---
+
+## 3. Engine and Session
+
+### The Engine
+The **Engine** is the starting point for any SQLAlchemy application. It manages a pool of connections to the database.
+
+```python
+from sqlalchemy import create_engine
+
+# SQLite: The '///' means relative path to the current directory
+engine = create_engine("sqlite:///recipes.db", echo=True) 
+# echo=True logs all SQL commands to the terminal (great for debugging)
+```
+
+### Creating Tables
+You can tell SQLAlchemy to create all tables defined in your models:
+```python
+Base.metadata.create_all(engine)
+```
+
+### The Session
+The **Session** handles the conversation with the database. Use `sessionmaker` to create a factory for sessions.
+
+```python
+from sqlalchemy.orm import sessionmaker
+
+SessionLocal = sessionmaker(bind=engine)
+
+# Use as a context manager to ensure the connection is closed
+with SessionLocal() as session:
+    # do work here
+    pass
+```
+
+---
+
+## 4. Relationships (1-to-Many)
+
+In our project, one `Recipe` has many `Ingredients`.
+
+### Foreign Key
+The "child" table (`Ingredient`) must have a column pointing to the "parent" table (`Recipe`).
+
+```python
+from sqlalchemy import ForeignKey
+
+class Ingredient(Base):
+    __tablename__ = "ingredients"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    
+    # Links to 'recipes.id'
+    recipe_id: Mapped[int] = mapped_column(ForeignKey("recipes.id"))
+    
+    text: Mapped[str]
+    
+    # Back-reference to the parent Recipe object
+    recipe: Mapped["Recipe"] = relationship(back_populates="ingredients")
+```
+
+### Cascades
+`cascade="all, delete-orphan"` ensures that if you delete a Recipe, all its Ingredients are also deleted automatically.
+
+---
+
+## 5. CRUD Operations
+
+### Create (Insert)
+```python
+with SessionLocal() as session:
+    new_recipe = Recipe(title="Pasta Carbonara", url="https://example.com/pasta")
+    session.add(new_recipe)
+    session.commit() # Save to DB
+```
+
+### Read (Select)
+```python
+from sqlalchemy import select
+
+with SessionLocal() as session:
+    # 1. Get by ID
+    recipe = session.get(Recipe, 1)
+    
+    # 2. Filter by column
+    stmt = select(Recipe).where(Recipe.title == "Pasta Carbonara")
+    result = session.execute(stmt).scalars().first()
+    
+    # 3. Get all
+    all_recipes = session.query(Recipe).all() # Older syntax, still common
+```
+
+### Update
+```python
+with SessionLocal() as session:
+    recipe = session.get(Recipe, 1)
+    recipe.title = "Authentic Pasta Carbonara"
+    session.commit()
+```
+
+### Delete
+```python
+with SessionLocal() as session:
+    recipe = session.get(Recipe, 1)
+    session.delete(recipe)
+    session.commit()
+```
+
+---
+
+## 6. Common Pitfalls
+
+1.  **Lazy Loading**: By default, SQLAlchemy doesn't load relationships until you access them. This can cause "N+1" performance issues. Use `joinedload` to fetch everything in one query.
+2.  **Session Lifecycle**: Always use a context manager (`with session:`) or close your sessions manually.
+3.  **Commit vs Flush**: `session.flush()` sends changes to the DB but doesn't permanentize them. `session.commit()` makes them permanent.
+
+---
+
+## 7. Next Steps: Migrations with Alembic
+
+As your models change (e.g., you add a `rating` column), you shouldn't just delete the DB and start over. **Alembic** is the tool used to handle database migrations.
+
+Install it with: `pip install alembic`