数据库¶

Tortoise 目前支持以下数据库

• SQLite（使用 aiosqlite）

• PostgreSQL >= 9.4（使用 asyncpg 或 psycopg）

• MySQL/MariaDB（使用 asyncmy）

• Microsoft SQL Server（使用 asyncodbc）

要使用，请确保安装了相应的 asyncio 驱动程序。

DB_URL¶

Tortoise 支持以 URL 形式指定数据库配置。

格式为

DB_TYPE://USERNAME:PASSWORD@HOST:PORT/DB_NAME?PARAM1=value&PARAM2=value

如果密码包含特殊字符，则需要进行 URL 编码

>>> import urllib.parse
>>> urllib.parse.quote_plus("kx%jj5/g")
'kx%25jj5%2Fg'

支持的 DB_TYPE

sqlite:

通常采用 sqlite://DB_FILE 的形式。因此，如果 DB_FILE 为 “/data/db.sqlite3”，则字符串将为 sqlite:///data/db.sqlite（注意三个 /）

postgres

使用 asyncpg：通常采用 postgres://postgres:pass@db.host:5432/somedb 的形式

或具体使用 asyncpg/psycopg

• psycopg： psycopg://postgres:pass@db.host:5432/somedb

• asyncpg： asyncpg://postgres:pass@db.host:5432/somedb

mysql:

通常采用 mysql://myuser:mypass@db.host:3306/somedb 的形式

mssql:

通常采用 mssql://myuser:mypass@db.host:1433/somedb?driver=the odbc driver 的形式

功能¶

由于每个数据库都有一组不同的功能，因此我们在每个客户端上注册了 Capabilities。这主要是为了解决比 SQL 更大的差异或常见问题。

class tortoise.backends.base.client.Capabilities(dialect, *, daemon=True, requires_limit=False, inline_comment=False, supports_transactions=True, support_for_update=True, support_index_hint=False, support_update_limit_order_by=True)[source]¶

DB 客户端功能指示支持的功能集，也用于记录针对缺陷的常见解决方法。

默认值使用以下标准设置

• 缺陷：假设其正常工作。

• 功能：假设其不具备。

参数:¶

dialect¶

DB 客户端驱动程序的方言名称。

daemon=True¶

DB 是我们连接到的外部守护进程吗？

requires_limit=False¶

表示此 DB 需要 LIMIT 语句才能使 OFFSET 语句正常工作。

inline_comment=False¶

表示注释应与 DDL 语句呈行内显示，而不是作为单独的语句显示。

supports_transactions=True¶

表示此数据库支持事务。

support_for_update=True¶

表示此数据库支持 SELECT … FOR UPDATE SQL 语句。

support_index_hint=False¶

支持强制索引或使用索引。

support_update_limit_order_by=True¶

支持带有 limit 和 order by 的更新/删除。

SQLite¶

SQLite 是一个嵌入式数据库，可以在文件或内存中运行。适合本地开发或测试代码逻辑的数据库，但建议不要用于生产环境。

数据库 URL 通常采用 sqlite://DB_FILE 的形式。因此，如果 DB_FILE 为 “/data/db.sqlite3”，则字符串将为 sqlite:///data/db.sqlite（注意三个 /）

必需的参数¶

路径:

SQLite3 文件的路径。 :memory: 是一个特殊路径，表示内存数据库。

可选参数：¶

SQLite 可选参数基本上是 此处记录的任何 PRAGMA 语句。

journal_mode（默认为 WAL）

指定 SQLite 日志模式。

journal_size_limit（默认为 16384）

日志大小。

foreign_keys（默认为 ON）

设置为 OFF 以不强制引用完整性。

PostgreSQL¶

数据库 URL 通常采用 postgres://postgres:pass@db.host:5432/somedb 的形式，或者如果通过 Unix 域套接字连接，则采用 postgres:///somedb 的形式。

必需的参数¶

用户:

用于连接的用户名。

密码:

用户名对应的密码。

主机:

数据库可用的网络主机。

端口:

数据库可用的网络端口。（默认为 5432）

数据库:

要使用的数据库。

可选参数：¶

PostgreSQL 可选参数是传递给驱动程序的参数，有关更多详情，请参阅 此处。

minsize（默认为 1）

最小连接池大小

maxsize（默认为 5）

最大连接池大小

max_queries（默认为 50000）

在关闭并替换连接之前查询的最大数量。

max_inactive_connection_lifetime（默认为 300.0）

在假定连接已失效并强制重新连接之前，非活动连接的持续时间。

schema（默认情况下使用用户的默认架构）

默认情况下要使用的特定架构。

ssl（默认为 ``False``）

自签名证书的 True 或自定义 SSL 上下文。有关更多信息，请参阅 MSSQL/Oracle。

如果缺少 user、password、host、port 中的任何一个参数，我们允许 asyncpg/psycopg 从默认源（标准 PostgreSQL 环境变量或默认值）中检索它。

MySQL/MariaDB¶

数据库 URL 通常采用 mysql://myuser:mypass@db.host:3306/somedb 的形式

必需的参数¶

用户:

用于连接的用户名。

密码:

用户名对应的密码。

主机:

数据库可用的网络主机。

端口:

数据库可用的网络端口。（默认为 3306）

数据库:

要使用的数据库。

可选参数：¶

MySQL 可选参数是传递给驱动程序的参数，有关更多详情，请参阅 此处。

minsize（默认为 1）

最小连接池大小

maxsize（默认为 5）

最大连接池大小

connect_timeout（默认为 None）

在抛出错误之前等待连接的持续时间。

echo（默认为 False）

设置为 True` 以回显 SQL 查询（仅调试）

no_delay（默认为 None）

设置为 True 以将 TCP NO_DELAY 设置为在套接字上禁用 Nagle 算法。

charset（默认为 utf8mb4）

设置正在使用的字符集

ssl（默认为 False）

自签名证书的 True 或自定义 SSL 上下文。有关更多信息，请参阅 MSSQL/Oracle。

MSSQL/Oracle¶

数据库 URL 通常采用 mssql or oracle://myuser:mypass@db.host:1433/somedb?driver=the odbc driver 的形式

必需参数¶

用户:

用于连接的用户名。

密码:

用户名对应的密码。

主机:

数据库可用的网络主机。

端口:

数据库可用的网络端口。（默认为 1433）

数据库:

要使用的数据库。

driver:

要使用的 ODBC 驱动程序。odbcinst.ini 文件中 ODBC 驱动程序的实际名称（可以使用 odbcinst -j 命令找到其位置）。它要求在你的系统中安装 unixodbc。

可选参数：¶

MSSQL/Oracle 可选参数是传递给驱动程序的参数，有关更多详细信息，请参阅 此处。

minsize（默认为 1）

最小连接池大小

maxsize（默认为 10）

最大连接池大小

pool_recycle（默认为 -1）

池回收超时（秒）。

echo（默认为 False）

设置为 True 以回显 SQL 查询（仅调试）

Oracle 中的编码：¶

如果你在 Varchar 字段中获得 ??? 值，而不是实际文本（俄语/中文/等），那么将客户端环境中的 NLS_LANG 变量设置为支持 UTF8。例如，“American_America.UTF8”。

传递自定义 SSL 证书¶

要传递自定义 SSL 证书，必须使用详细的 init 结构，因为 URL 解析器无法处理复杂对象。

# Here we create a custom SSL context
import ssl
ctx = ssl.create_default_context()
# And in this example we disable validation...
# Please don't do this. Look at the official Python ``ssl`` module documentation
ctx.check_hostname = False
ctx.verify_mode = ssl.CERT_NONE

# Here we do a verbose init
await Tortoise.init(
    config={
        "connections": {
            "default": {
                "engine": "tortoise.backends.asyncpg",
                "credentials": {
                    "database": None,
                    "host": "127.0.0.1",
                    "password": "moo",
                    "port": 54321,
                    "user": "postgres",
                    "ssl": ctx  # Here we pass in the SSL context
                }
            }
        },
        "apps": {
            "models": {
                "models": ["some.models"],
                "default_connection": "default",
            }
        },
    }
)

基本数据库客户端¶

在此处提供基本数据库客户端接口，但仅应作为高级案例直接使用。

class tortoise.backends.base.client.BaseDBAsyncClient(connection_name, fetch_inserted=True, **kwargs)[source]¶

包含数据库连接的基本类。

参数作为关键字参数传递，并且主要特定于驱动程序。

query_class Type[pypika.Query]¶

PyPika 查询方言（低级方言）

executor_class Type[BaseExecutor]¶

执行器方言类（高级方言）

schema_generator Type[BaseSchemaGenerator]¶

DDL 模式生成器

capabilities Capabilities¶

包含连接功能

acquire_connection()[源代码]¶

从池中获取连接。如果已处于事务中，将返回当前上下文连接。

返回类型:¶

Union[ConnectionWrapper, PoolConnectionWrapper]

async close()[源代码]¶

关闭数据库连接。

返回类型:¶

无

async create_connection(with_db)[源代码]¶

建立数据库连接。

参数:¶

with_db¶

如果为 True，则选择要使用的数据库，否则使用默认数据库。此用例用于创建/删除数据库。

返回类型:¶

无

async db_create()[source]¶

在服务器中创建数据库。通常仅由测试运行器调用。

需要使用参数 with_db=False 调用 create_connection()` 以使用默认连接而不是配置的连接，否则会收到指示数据库不存在的错误。

返回类型:¶

无

async db_delete()[source]¶

从服务器中删除数据库。通常仅由测试运行器调用。

需要使用参数 with_db=False 调用 create_connection()` 以使用默认连接而不是配置的连接，否则会收到指示数据库正在使用的错误。

返回类型:¶

无

async execute_insert(query, values)[source]¶

执行原始 SQL 插入语句，并提供参数。

参数:¶

query¶

针对目标数据库方言预参数化的 SQL 字符串。

values¶

一系列位置 DB 参数。

返回类型:¶

任意

返回:¶

如果是由 DB 生成的，则为主键。（目前仅限于整数自增主键）

async execute_many(query, values)[source]¶

执行 RAW 批量插入语句，如 execute_insert，但不返回数据。

参数:¶

query¶

针对目标数据库方言预参数化的 SQL 字符串。

values¶

一系列位置 DB 参数。

返回类型:¶

无

async execute_query(query, values=None)[source]¶

执行 RAW SQL 查询语句，并返回结果集。

参数:¶

query¶

针对目标数据库方言预参数化的 SQL 字符串。

values=None¶

一系列位置 DB 参数。

返回类型:¶

元组[int, 序列[字典]]

返回:¶

元组：(受影响的行数，结果集)

async execute_query_dict(query, values=None)[source]¶

执行原始 SQL 查询语句，并将结果集作为字典列表返回。

参数:¶

query¶

针对目标数据库方言预参数化的 SQL 字符串。

values=None¶

一系列位置 DB 参数。

返回类型:¶

列表[字典]

async execute_script(query)[source]¶

执行包含多条语句的原始 SQL 脚本，不返回任何内容。

参数:¶

query¶

将逐字传递的 SQL 字符串。此处支持分号。

返回类型:¶

无