一、核心基础

1. 引擎与连接

create_engine()

本质：数据库工厂与调度中心。它是应用程序与数据库之间的接口，负责管理连接池、方言生成和事务处理。
语法：create_engine(url, **kwargs)
关键参数：
url：数据库连接字符串。
echo：布尔值，若为 True 则打印所有生成的 SQL 语句（用于调试）。
pool_size：连接池中保持打开的连接数量。
max_overflow：连接池允许超出 pool_size 的最大连接数。
返回值：Engine 对象。

# 格式：方言+驱动://用户:密码@地址:端口/库名?参数
url = "mysql+pymysql://root:123456@localhost:3306/mydb?charset=utf8mb4"
engine = create_engine(url)

连接字符串与 Dialects

本质：定义数据库类型、驱动、认证信息及目标地址的标准化 URL 格式。Dialect（方言）负责将 SQLAlchemy 的通用指令转换为特定数据库的 SQL。
语法：dialect+driver://username:password@host:port/database?charset=utf8mb4
关键参数：
dialect：数据库名称（如 mysql, postgresql, sqlite）。
driver：DBAPI 驱动名称（如 pymysql, psycopg2），若不填则使用默认驱动。
username：数据库登录用户名。
password：数据库登录密码（若含 @ 等特殊字符需进行 URL 编码）。
host：数据库服务器地址（IP 或域名）。
port：数据库服务端口（如 MySQL 默认 3306）。
database：要连接的具体数据库名称。
?charset=utf8mb4：连接参数，指定字符集以防止中文乱码。
返回值：无（作为 create_engine 的参数）。

# 格式：方言+驱动://用户:密码@地址:端口/库名?参数
url = "mysql+pymysql://root:123456@localhost:3306/mydb?charset=utf8mb4"
engine = create_engine(url)

连接池配置

本质：管理数据库连接的复用机制。避免频繁创建和销毁连接的开销，提高系统性能。SQLAlchemy 默认使用 QueuePool。
语法：通过 create_engine 的参数配置。
关键参数：
pool_size：池中保持的活跃连接数（默认 5）。
max_overflow：允许临时创建的额外连接数（默认 10）。
pool_timeout：获取连接的超时时间（秒）。
pool_recycle：连接回收时间（秒），防止数据库自动断开空闲连接。
pool_pre_ping：每次获取连接前先发送 ping 测试，确保连接可用。
返回值：无。

engine = create_engine(
    "mysql+pymysql://user:pass@host/db?charset=utf8mb4",
    pool_size=10,
    max_overflow=20,
    pool_pre_ping=True
)

2. 类型系统

通用类型与特定类型

自定义类型

二、ORM 映射

1. 声明式映射

declarative_base()

2.x 风格：Mapped 与 mapped_column

2. 模式配置

tablename

关系：relationship() 与 ForeignKey

事件监听

三、会话管理

1. 会话工厂

sessionmaker()

Session 对象

2. 事务控制

commit(), rollback()

异步会话

四、数据定义

1. 表结构操作

创建表

反射表结构

五、数据操作

1. 插入

session.add()

批量插入

2. 更新

对象更新

批量更新

3. 删除

session.delete()

批量删除

六、查询系统

1. 构造器

select()

insert(), update(), delete()

2. 执行与结果

execute()

scalars()

3. 高级查询

过滤、排序、分页

关联加载

七、迁移

1. Alembic

初始化与配置

版本控制