使用 sqlacodegen 反向生成 SQLAlchemy 模型代码

介绍

sqlacodegen 是一款能够读取现有数据库结构并生成相应的 SQLAlchemy 模型代码的工具。目前支持 SQLAlchemy 2.x，能识别关系类型（包括多对多、一对一），能自动检测表继承等。

安装

sqlacodegen 的安装命令如下：

pip install sqlacodegen

截至目前， sqlacodegen 的版本是 3.0.0。

示例

使用 sqlacodegen 命令，最基本的是要传给它一个数据库 URL。

示例：

sqlacodegen postgresql:///some_local_db
sqlacodegen --generator tables mysql+pymysql://user:password@localhost/dbname
sqlacodegen --generator dataclasses sqlite:///database.db

下面使用一个简单的 user 表来演示 sqlacodegen 命令的使用。user 表的数据库是 MySQL，有三个字段，分别是 id、username 和 password。其中 id 是主键字段，username 和 password 是用户名和密码，且都不能为 null，同时 username 具有唯一索引。

user 表结构如下所示：

名	类型	长度	不是 null	键	注释
id	int		☑	🔑	主键
username	varchar	20	☑		用户名
password	varchar	32	☑		密码

使用 sqlacodegen 命令前，需要安装 pymysql 这个 MySQL 数据库驱动包，命令如下：

pip install pymysql

目前 pymysql 的版本是 1.1.1。

接下来就可以使用 sqlacodegen 命令反向生成 ORM 模型类了，命令如下：

sqlacodegen mysql+pymysql://user:password@localhost/test --outfile user.py

生成的 user.py 文件的代码如下：

from sqlalchemy import Index, Integer
from sqlalchemy.dialects.mysql import VARCHAR
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_columnclass Base(DeclarativeBase):passclass User(Base):__tablename__ = 'user'__table_args__ = (Index('username', 'username', unique=True),)id: Mapped[int] = mapped_column(Integer, primary_key=True, comment='主键')username: Mapped[str] = mapped_column(VARCHAR(20), comment='用户名')password: Mapped[str] = mapped_column(VARCHAR(32), comment='密码')

通用选项

使用 sqlacodegen --help 命令可以查看 sqlacodegen 命令的通用选项，其输出如下所示：

usage: sqlacodegen [-h] [--options OPTIONS] [--version] [--schemas SCHEMAS] [--generator {dataclasses,declarative,sqlmodels,tables}][--tables TABLES] [--noviews] [--outfile OUTFILE][url]Generates SQLAlchemy model code from an existing database.positional arguments:url                   SQLAlchemy url to the databaseoptions:-h, --help            show this help message and exit--options OPTIONS     options (comma-delimited) passed to the generator class--version             print the version number and exit--schemas SCHEMAS     load tables from the given schemas (comma-delimited)--generator {dataclasses,declarative,sqlmodels,tables}generator class to use--tables TABLES       tables to process (comma-delimited, default: all)--noviews             ignore views (always true for sqlmodels generator)--outfile OUTFILE     file to write output to (default: stdout)

相应的中文翻译如下所示：

用法: sqlacodegen [-h] [--options OPTIONS] [--version] [--schemas SCHEMAS] [--generator {dataclasses,declarative,sqlmodels,tables}][--tables TABLES] [--noviews] [--outfile OUTFILE][url]从现有数据库生成 SQLAlchemy 模型代码。位置参数:url                   数据库URL选项:-h, --help            显示帮助信息--options OPTIONS     传递给生成器类的选项（逗号分隔）--version             输出版本号--schemas SCHEMAS     从指定模式加载表（逗号分隔）--generator {dataclasses,declarative,sqlmodels,tables}使用的生成器--tables TABLES       要处理的表（逗号分隔，默认：全部）--noviews             忽略视图（sqlmodels 生成器始终忽略视图）--outfile OUTFILE     输出到文件（默认：标准输出）

生成器(generator)

生成器(generator)介绍

生成器是 sqlacodegen 的核心选项，用于指定代码生成逻辑的类型。不同的生成器会输出不同风格的 SQLAlchemy 模型代码，适用于不同的开发场景。通过 --generator 参数选择生成器。

sqlacodegen 内置的生成器包括:

• tables (仅生成 Table 对象)
• declarative (默认，生成继承自 declarative_base() 的类)
• dataclasses (生成基于数据类的模型，仅限 v1.4+)
• sqlmodels (生成 SQLModel 模型类)

生成器专属选项

通过 --options 指定(多个值用逗号分隔):

• tables

  • noconstraints: 忽略约束（外键、唯一约束等）

  • nocomments: 忽略注释

  • noindexes: 忽略索引

• declarative

  • 继承 tables 所有选项

  • use_inflect: 自动将复数表名转换为单数类名（如 users → User）。

  • nojoined: 禁用表继承检测

  • nobidi: 仅生成单向关系（不生成反向关系属性）。

• dataclasses

  • 继承 declarative 所有选项

• sqlmodels

  • 继承 declarative 所有选项