FastAPI - Tortoise ORM 数据库基础操作

Tortoise ORM 是一个异步的 ORM 框架，使用 Python 的类和对象来操作数据库，不需要编写 SQL 语句。

1. 安装 Tortoise ORM

首先，确保已经安装 Tortoise ORM。如果还没有安装，可以使用 pip 来安装：

pip install tortoise-orm

2. 定义模型

使用 Tortoise ORM, 需要定义模型类来表示数据库中的表。模型类继承自 tortoise.models.Model。

from tortoise import fields, models
from tortoise.contrib.pydantic import pydantic_model_creator

class Tournament(models.Model):
    id = fields.IntField(pk=True)
    name = fields.CharField(max_length=255)
    created_at = fields.DatetimeField(auto_now_add=True)

    class Meta:
        table = 'tournaments'  # 自定义表名

# 创建 Pydantic 模型
Tournament_Pydantic = pydantic_model_creator(Tournament, name="Tournament")

3. 初始化数据库连接

在使用 Tortoise ORM 之前，需要初始化数据库连接。

from tortoise import Tortoise, run_async

async def init_db():
    # 这里使用 SQLite 数据库作为示例
    await Tortoise.init(
        db_url='sqlite://db.sqlite3',
        modules={'models': ['your_app']}  # 你的模型所在的模块
    )
    # 生成数据库表结构
    await Tortoise.generate_schemas()

# 运行初始化函数
run_async(init_db())

4. 数据库操作

定义好模型和数据库连接后，可以进行各种数据库操作。

4.1 创建数据

async def create_tournament():
    tournament = await Tournament.create(name='New Tournament')
    print(f'Created tournament with id: {tournament.id}')

run_async(create_tournament())

4.2 查询数据

async def get_tournaments():
    tournaments = await Tournament.all()
    for tournament in tournaments:
        print(f'Tournament: {tournament.name}')

run_async(get_tournaments())

4.3 更新数据

async def update_tournament(tournament_id: int, new_name: str):
    await Tournament.filter(id=tournament_id).update(name=new_name)
    print(f'Updated tournament with id: {tournament_id}')

run_async(update_tournament(1, 'Updated Tournament'))

4.4 删除数据

async def delete_tournament(tournament_id: int):
    await Tournament.filter(id=tournament_id).delete()
    print(f'Deleted tournament with id: {tournament_id}')

run_async(delete_tournament(1))

5. 使用 Pydantic 模型

Tortoise ORM 提供了 pydantic_model_creator 函数，可以自动生成 Pydantic 模型。

# 创建 Pydantic 模型
Tournament_Pydantic = pydantic_model_creator(Tournament, name="Tournament")

# 使用 Pydantic 模型
tournament_data = Tournament_Pydantic.from_orm(tournament)
print(tournament_data.json())

6. 关闭数据库连接

在应用结束时，确保关闭数据库连接。

from tortoise import Tortoise

# 关闭数据库连接
@app.on_event("shutdown")
async def close_orm():
    await Tortoise.close_connections()

7. fields类相关操作

在 Tortoise ORM 中，fields 是模型中用于定义数据库表字段的类。这些字段类定义了数据库表中每个字段的类型、约束和其他属性。以下是 Tortoise ORM 中一些常用的 fields 类：

1. fields.IntField

用于定义整数字段。

from tortoise import fields

class MyModel(Model):
    id = fields.IntField(pk=True)

2. fields.BigIntField

用于定义大整数字段。

from tortoise import fields

class MyModel(Model):
    id = fields.BigIntField(pk=True)

3. fields.SmallIntField

用于定义小整数字段。

from tortoise import fields

class MyModel(Model):
    id = fields.SmallIntField(pk=True)

4. fields.CharField

用于定义字符字段，通常用于存储短文本。

from tortoise import fields

class MyModel(Model):
    name = fields.CharField(max_length=255)

5. fields.TextField

用于定义文本字段，通常用于存储长文本。

from tortoise import fields

class MyModel(Model):
    description = fields.TextField()

6. fields.BooleanField

用于定义布尔字段。

from tortoise import fields

class MyModel(Model):
    is_active = fields.BooleanField()

7. fields.FloatField

用于定义浮点数字段。

from tortoise import fields

class MyModel(Model):
    price = fields.FloatField()

8. fields.DecimalField

用于定义精确小数字段。

from tortoise import fields

class MyModel(Model):
    balance = fields.DecimalField(max_digits=10, decimal_places=2)

9. fields.DatetimeField

用于定义日期时间字段。

from tortoise import fields

class MyModel(Model):
    created_at = fields.DatetimeField(auto_now_add=True)

10. fields.DateField

用于定义日期字段。

from tortoise import fields

class MyModel(Model):
    birth_date = fields.DateField()

11. fields.TimeField

用于定义时间字段。

from tortoise import fields

class MyModel(Model):
    start_time = fields.TimeField()

12. fields.JSONField

用于定义 JSON 字段，可以存储复杂的数据结构。

from tortoise import fields

class MyModel(Model):
    data = fields.JSONField()

13. fields.BinaryField

用于定义二进制字段，可以存储二进制数据。

from tortoise import fields

class MyModel(Model):
    image = fields.BinaryField()

14. fields.ForeignKeyField

用于定义外键字段，用于建立模型之间的关系。

from tortoise import fields

class MyModel(Model):
    user = fields.ForeignKeyField('models.User')

15. fields.ManyToManyField

用于定义多对多字段，用于建立模型之间的多对多关系。

from tortoise import fields

class MyModel(Model):
    tags = fields.ManyToManyField('models.Tag')

16. fields.OneToOneField

用于定义一对一字段，用于建立模型之间的关系。

from tortoise import fields

class MyModel(Model):
    profile = fields.OneToOneField('models.Profile')

其他字段

Tortoise ORM 还提供了其他一些字段，如 fields.UUIDField、fields.IPAddressField、fields.EmailField 等，用于处理特定类型的数据。

在定义模型字段时，可以设置各种属性，如 null、default、pk、unique、index 等，以控制字段的行为和约束。

8. ORM（对象关系映射）数据迁移

ORM（对象关系映射）数据迁移是管理数据库模式更改的过程。在使用 ORM 时，通常会使用 ORM 提供的迁移工具来处理数据库模式的变更，而不是直接编写 SQL 语句。以下是一些常见的 ORM 迁移命令：

1. 初始化迁移环境

在开始使用迁移之前，需要初始化迁移环境, 涉及到设置数据库连接和配置迁移目录。

# 使用 Tortoise ORM 的迁移工具
tortoise-orm init-db

2. 创建迁移文件

一旦迁移环境设置好，可以创建迁移文件来描述你的数据库模式更改。

# 创建一个新的迁移文件
tortoise-orm makemigrations

这将生成一个新的迁移文件，其中包含了对数据库模式的更改。

3. 应用迁移

创建迁移文件后，可以应用这些迁移来更新数据库模式。

# 应用所有未应用的迁移
tortoise-orm migrate

4. 查看迁移状态

如果查看当前的迁移状态，可以使用以下命令：

# 查看当前的迁移状态
tortoise-orm showmigrations

5. 回滚迁移

如果需要回滚迁移，可以使用命令：

# 回滚最近的一次迁移
tortoise-orm migrate --revision=-1

6. 生成模型

如果需要根据数据库生成模型，可以使用命令：

# 生成模型
tortoise-orm inspectdb

7. 清除迁移历史

如果清除迁移历史，可以使用命令：

# 清除迁移历史
tortoise-orm reset