sqlmodel-ext

Appearance

字段类型 ​

sqlmodel-ext 提供了一系列预定义的字段类型，同时满足 Pydantic 数据验证和 SQLAlchemy 列类型映射。

字符串约束 ​

写 name: Str64 等于同时告诉 Pydantic 验证 max_length=64，以及告诉 SQLAlchemy 创建 VARCHAR(64) 列。

类型最大长度典型用途
Str2424短编码
Str3232Token、哈希
Str3636UUID 字符串格式
Str4848短标签
Str6464名称、标题
Str100100简短描述
Str128128路径、标识符
Str255 / Str256255 / 256标准 VARCHAR
Str512512长标识符、长路径
Text1K ~ Text100K1,000 ~ 100,000各种长度的文本（含 Text5K）
python
from sqlmodel_ext import SQLModelBase, Str64, Str255, Text1K

class Article(SQLModelBase):
    title: Str64          # VARCHAR(64)
    summary: Str255       # VARCHAR(255)
    body: Text1K          # VARCHAR(1000)

数值约束 ​

类型范围典型用途
Port1 ~ 65535网络端口
Percentage0 ~ 100百分比
PositiveInt>= 1计数、数量
NonNegativeInt>= 0索引、计数器
PositiveFloat> 0.0价格、重量
PositiveBigInt>= 1（BigInteger）大整数 ID、时间戳
NonNegativeBigInt>= 0（BigInteger）大整数计数器
python
from sqlmodel_ext import Port, Percentage

class ServerConfig(SQLModelBase):
    port: Port                    # 自动验证 1~65535
    cpu_threshold: Percentage     # 自动验证 0~100

URL 类型 ​

四种 URL 类型，都继承 str，在数据库中存储为普通 VARCHAR：

类型允许的协议SSRF 防护
Url任意（http, ftp, ws, ...）无
HttpUrl仅 http / https无
WebSocketUrl仅 ws / wss无
SafeHttpUrl仅 http / https有
python
from sqlmodel_ext import HttpUrl, SafeHttpUrl

class Webhook(SQLModelBase):
    url: HttpUrl             # 验证 HTTP 格式
    callback: SafeHttpUrl    # 验证 HTTP 格式 + 阻止内网地址

SafeHttpUrl 与 SSRF 防护 ​

SafeHttpUrl 在验证 URL 格式之外，还会阻止指向内网的地址，防止 SSRF 攻击：

SSRF 防护

  • 禁止 localhost、127.0.0.1、::1 等回环地址
  • 禁止 10.x.x.x、192.168.x.x、172.16-31.x.x 等私有 IP
  • 禁止链路本地地址和保留地址

适用于用户提交的回调 URL、Webhook 地址等场景。

IPAddress 类型 ​

验证 IPv4/IPv6 格式，额外提供 is_private() 方法：

python
from sqlmodel_ext import IPAddress

class Device(SQLModelBase):
    ip: IPAddress

device = Device(ip="192.168.1.1")
device.ip.is_private()  # True

路径类型 ​

python
from sqlmodel_ext.field_types import FilePathType, DirectoryPathType

class Storage(SQLModelBase):
    file: FilePathType           # 要求包含文件扩展名
    directory: DirectoryPathType # 要求不包含扩展名

PostgreSQL 专属类型 ​

仅限 PostgreSQL

Array[T] 使用 PostgreSQL 原生 ARRAY 列类型，不适用于 SQLite 等其他数据库。

python
from sqlmodel_ext.field_types.dialects.postgresql import Array

class Tag(SQLModelBase, UUIDTableBaseMixin, table=True):
    labels: Array[str]     # 映射 PostgreSQL TEXT[]
    scores: Array[float]   # 映射 PostgreSQL FLOAT[]

Array[T] 在 Pydantic 中表现为 list[T]，在 PostgreSQL 中映射为 ARRAY 列类型。