文章列表
3 分钟阅读

Python Web 项目如何连接数据库：SQLAlchemy、Django ORM、迁移怎么选

Web 开发 进阶 指南 #Python#数据库#SQLAlchemy#Django#Web 框架

更新说明：新增数据库选型和 ORM 使用建议。

系列：Python Web 工程实践

第 2 / 8 篇

  1. Python Web 项目配置管理：环境变量、.env 和生产配置怎么拆
  2. Python Web 项目如何连接数据库：SQLAlchemy、Django ORM、迁移怎么选
  3. Alembic 数据库迁移入门：表结构变更怎么安全上线
  4. Django 数据库迁移实战：makemigrations 和 migrate 背后的坑
  5. FastAPI 项目测试指南：pytest、TestClient、依赖覆盖怎么用
  6. Django 测试入门：Model、View、API 测试怎么写
  7. FastAPI 分层架构：router、service、repository 怎么拆
  8. PostgreSQL 基础：索引、事务、慢查询怎么理解

Web 项目迟早要连接数据库。真正容易纠结的不是“怎么连上”，而是：用 Django ORM，还是 SQLAlchemy？迁移交给谁？复杂查询要不要直接写 SQL？

如果项目还在选框架，可以先看 Python Web 框架有哪些，怎么选。这里只讨论数据库这一层。

Django 项目优先用 Django ORM

Django ORM 和 Django 的表单、Admin、权限、迁移绑定得很紧。只要项目主体是 Django，默认就应该先用 Django ORM。

models.py
from django.db import models




class Article(models.Model):
    title = models.CharField(max_length=120)
    slug = models.SlugField(unique=True)
    published = models.BooleanField(default=False)
    created_at = models.DateTimeField(auto_now_add=True)

它的好处是完整：模型定义、迁移、后台管理、测试数据库都在一套体系里。缺点是离开 Django 后复用价值不高。

FastAPI 项目更常见的是 SQLAlchemy

FastAPI 不自带 ORM。常见组合是 FastAPI + SQLAlchemy + Alembic。

models.py
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column




class Base(DeclarativeBase):
    pass




class Article(Base):
    __tablename__ = "articles"


    id: Mapped[int] = mapped_column(primary_key=True)
    title: Mapped[str] = mapped_column()
    slug: Mapped[str] = mapped_column(unique=True)

SQLAlchemy 的优势是灵活，既能写 ORM，也能写接近 SQL 的表达式。代价是项目结构要自己定，迁移要自己接。

什么时候直接写 SQL

不要把“用了 ORM”理解成“不能写 SQL”。下面几类场景直接写 SQL 反而更清楚：

  • 复杂报表查询
  • 需要窗口函数
  • 大批量更新
  • 需要精确控制执行计划
  • 数据修复脚本
report.py
rows = session.execute(
    text("""
    select user_id, count(*) as total
    from orders
    where created_at >= :start
    group by user_id
    order by total desc
    """),
    {"start": start_time},
)

关键是把 SQL 放在明确的位置，不要散落在每个接口函数里。

迁移工具怎么选

Django 项目用自带迁移。FastAPI / Flask 项目一般用 Alembic。迁移不只是“建表工具”，它记录的是线上结构变化过程。

开发时可以频繁改模型，发布前要认真看迁移文件：

  • 有没有误删字段
  • 有没有给大表加锁的操作
  • 默认值会不会触发全表更新
  • 索引创建是否需要拆开执行

下一篇可以继续看 Alembic 数据库迁移入门：表结构变更怎么安全上线。 如果你对索引、事务和慢查询还不熟，可以先补一遍 PostgreSQL 基础：索引、事务、慢查询怎么理解，再回来看迁移文件会更踏实。

总结

选型时我会先看项目边界，而不是只看工具热度。框架已经选 Django，就不要额外引入 SQLAlchemy 增加复杂度；项目是 FastAPI 或 Flask，就优先选能独立工作的 SQLAlchemy 和 Alembic。

如果是 Django 项目：Django ORM + Django migrations。

如果是 FastAPI 项目：SQLAlchemy + Alembic。

如果项目只有几个简单查询，也可以先用 SQLModel 或轻量封装，但不要把迁移省掉。只要数据需要长期保留，迁移就是项目的一部分。

Django 项目后续可以看 Django 数据库迁移实战：makemigrations 和 migrate 背后的坑，FastAPI 或 SQLAlchemy 项目则更适合继续看 Alembic 迁移。