跳转至

模型定义

定义模型

模型类

你可以和 Pydantic 一样轻松地定义一个数据库模型，只需继承 cherry.Model 类即可。

以下是一个最简单的模型。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from datetime import date

import cherry


class User(cherry.Model):
    id: int = cherry.Field(primary_key=True)
    name: str
    age: int = 18
    birthday: date

模型字段

可以用 cherry.Field 对模型的字段进行详细设置，就像 pydantic.Field 一样。

1
2
3
4
5
class User(cherry.Model):
    id: int = cherry.Field(primary_key=True)
    name: str = cherry.Field(unique=True)
    age: int = cherry.Field(default=18, index=True)
    birthday: date = cherry.Field(default_factory=date.today)

cherry.Field 支持 pydantic.Field 的所有配置，并增添了以下配置：

  • primary_key - 主键
  • autoincrement - 数据库自增
  • index - 索引
  • unique - 唯一约束
  • nullable - 是否允许为空

同时它们还有一些简便写法，通过 Annotated 来实现：

1
2
3
4
5
class User(cherry.Model):
    id: int = cherry.Field(primary_key=True)
    name: str = cherry.Field(unique=True)
    age: int = cherry.Field(default=18, index=True)
    birthday: date = cherry.Field(default_factory=date.today)

1
2
3
4
5
class User(cherry.Model):
    id: cherry.PrimaryKey[int]
    name: cherry.Unique[str]
    age: cherry.Index[int] = 18
    birthday: date = cherry.Field(default_factory=date.today)

对于数据库自增整型主键，你可以采用以下写法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
from datetime import date
from typing import Optional

import cherry


class User(cherry.Model):
    id: Optional[int] = cherry.Field(default=None, primary_key=True, autoincrement=True)
    name: cherry.Unique[str]
    age: cherry.Index[int] = 18
    birthday: date = cherry.Field(default_factory=date.today)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from datetime import date

import cherry


class User(cherry.Model):
    id: cherry.AutoIntPK = None
    name: cherry.Unique[str]
    age: cherry.Index[int] = 18
    birthday: date = cherry.Field(default_factory=date.today)

数据库绑定

在定义好 Model 之后，你尚未能够使用它。你需要创建一个 cherry.Database 对象，它负责与数据库进行连接交互，你需要传入一个数据库连接字符串，并且必须添加一个支持异步的后端，例如:

  • sqlite+aiosqlite:///test.db
  • mysql+asyncmy://root:123456@localhost:3306/test
  • postgresql+asyncpg://root:123456@localhost:5432/test
1
2
3
import cherry

db = cherry.Database("sqlite+aiosqlite:///test.db")

然后通过模型的 cherry_config字段 ，将数据库对象绑定到模型上：

1
2
3
4
5
6
class User(cherry.Model):
    id: int = cherry.Field(primary_key=True)
    name: str
    age: int = 18

    cherry_config = cherry.CherryConfig(tablename="user_table", database=db)

在 cherry_config 中，你还可以定义以下配置：

  • database - cherry.Database 对象，默认无。
  • tablename - 模型在数据库中的表名。默认使用模型的类名作为表名，例如本处的 User。
  • abstract - 是否为抽象模型。抽象模型即只用于继承，不作为数据库中的表，默认为 False。
  • constraints - 更多 sqlalchemy 的表约束，类型为 List[sqlalchemy.ColumnCollectionConstraint]。
  • indexes - 组合索引，类型为 List[cherry.CompositeIndex]。
  • use_jsonb_in_postgres - 在 postgresql 数据库中 Mapping 等类型使用 jsonb，默认为 True。
  • use_array_in_postgres - 在 postgresql 数据库中 Iterable 等类型使用 array，默认为 True。

模型初始化

在绑定数据库对象后，你还需要在你的入口文件中调用 Database.init 方法，对模型以及数据库进行初始化才能使用。

1
2
3
4
5
6
7
8
async def main():
    await db.init()


if __name__ == "__main__":
    import asyncio

    asyncio.run(main())