跳到主要内容

02 安装与连接数据库

本章目标：理解 SQLAlchemy 的两个核心对象 engine 和 Session，学会连接 SQLite / MySQL / PostgreSQL。

1. 安装​

pip install sqlalchemy

确认版本是 2.0+：

python -c "import sqlalchemy; print(sqlalchemy.__version__)"
# 应输出 2.0.x 或更高

SQLite 支持是 Python 内置的，不需要装任何额外东西。

2. 数据库连接字符串（URL）​

SQLAlchemy 用一个 URL 描述「连哪个数据库」，格式：

数据库类型+驱动://用户名:密码@主机:端口/数据库名

常用示例：

# SQLite：连接（不存在则自动创建）当前目录下的 app.db 文件
"sqlite:///./app.db"

# SQLite：内存数据库，程序退出即消失（适合测试）
"sqlite://"

# MySQL（需要先 pip install pymysql）
"mysql+pymysql://root:password@localhost:3306/mydb"

# PostgreSQL（需要先 pip install psycopg2-binary）
"postgresql+psycopg2://postgres:password@localhost:5432/mydb"

SQLite 的三条斜杠：sqlite:/// 后面跟相对路径，sqlite:////absolute/path 四条杠是绝对路径（Linux/Mac）。Windows 绝对路径写 sqlite:///D:/data/app.db。

3. engine：数据库连接的总管​

from sqlalchemy import create_engine

engine = create_engine(
    "sqlite:///./app.db",
    echo=True,   # 打印所有实际执行的 SQL，学习期强烈建议打开！
)

关于 engine 你需要知道：

  • 全局只创建一个。它内部维护一个连接池，负责管理与数据库的所有物理连接
  • 创建 engine 时并不会真的连接数据库，第一次执行操作时才连
  • echo=True 是学习 SQLAlchemy 的利器：每次操作都能看到 ORM 到底生成了什么 SQL。上线时关掉

SQLite 专属参数​

以后配合 FastAPI 使用 SQLite 时需要多传一个参数：

engine = create_engine(
    "sqlite:///./app.db",
    connect_args={"check_same_thread": False},  # 仅 SQLite 需要
)

原因：SQLite 默认限制连接只能在创建它的线程使用，而 FastAPI 会在不同线程处理请求。这个参数解除限制（配合 Session 的正确用法是安全的）。MySQL/PostgreSQL 不需要这个参数。

4. Session：一次数据库对话​

engine 管连接，而实际的增删改查通过 Session 进行。可以把 Session 理解为「一次数据库会话/工作单元」：你把要做的操作告诉它，最后统一提交。

标准配置（这几行以后每个项目都会写，背下来）：

from sqlalchemy.orm import sessionmaker

# sessionmaker 创建一个「Session 工厂」，绑定到 engine
SessionLocal = sessionmaker(bind=engine, autoflush=False)

# 需要时创建一个 Session 用
db = SessionLocal()
try:
    # ... 在这里做增删改查 ...
    db.commit()      # 提交事务，修改真正写入数据库
except Exception:
    db.rollback()    # 出错则回滚，所有修改作废
    raise
finally:
    db.close()       # 用完必须关闭，把连接还给连接池

也可以用 with 语法自动关闭：

with SessionLocal() as db:
    ...
    db.commit()

三个必须理解的概念​

① 事务（Transaction）：Session 里做的修改（add/delete/更新）都先记在"账上"，只有 db.commit() 之后才真正写入数据库。commit 前程序崩了？什么都没写入，数据不会只改一半——这就是事务的原子性。

② rollback：出错时撤销本次会话的所有未提交修改。

③ close：归还连接。不关闭会耗尽连接池，这也是为什么第四部分要用 FastAPI 的 yield 依赖来自动管理。

Session 使用原则（重要）​

  • engine 全局一个；Session 用完就扔——每个请求/每个任务单元创建一个新 Session，绝不搞全局共享的 Session
  • 记住口诀：「一个请求，一个 Session，一个事务」

5. 验证连接​

写个脚本 test_conn.py 测试一下（这里临时用 text() 执行原生 SQL，仅用于验证连接，后面都用 ORM）：

from sqlalchemy import create_engine, text

engine = create_engine("sqlite:///./app.db", echo=True)

with engine.connect() as conn:
    result = conn.execute(text("SELECT 'Hello SQLAlchemy!'"))
    print(result.scalar())   # → Hello SQLAlchemy!

运行 python test_conn.py，同时观察 echo 打印的 SQL 日志。看到输出说明连接成功，目录下也多了一个 app.db 文件。

6. MySQL 用户的额外说明（可跳过）​

如果你想直接用 MySQL 练习：

  1. 安装 MySQL Server 并启动（或用 Docker：docker run -d -p 3306:3306 -e MYSQL_ROOT_PASSWORD=password mysql:8）
  2. 创建数据库：CREATE DATABASE mydb CHARACTER SET utf8mb4;
  3. 安装驱动：pip install pymysql
  4. 连接字符串：mysql+pymysql://root:password@localhost:3306/mydb

其余所有代码与 SQLite 完全一致。建议新手先用 SQLite 学完教程，再切 MySQL——只需改这一行。

本章小结​

  • 连接字符串描述连哪个库；SQLite 零配置最适合学习
  • create_engine() 全局一个，echo=True 学习期必开
  • sessionmaker 造 Session 工厂；每个工作单元一个新 Session
  • 修改必须 commit() 才生效；出错 rollback()；用完 close()

下一章：03-定义数据模型 —— 用 Python 类建表。