SqlAlchemy 2.0 中文文档（四十九）（5）

SqlAlchemy 2.0 中文文档（四十九）（4）https://developer.aliyun.com/article/1563030

MySQL 数据类型

与所有 SQLAlchemy 方言一样，已知与 MySQL 有效的所有大写类型都可以从顶级方言导入：

from sqlalchemy.dialects.mysql import (
    BIGINT,
    BINARY,
    BIT,
    BLOB,
    BOOLEAN,
    CHAR,
    DATE,
    DATETIME,
    DECIMAL,
    DECIMAL,
    DOUBLE,
    ENUM,
    FLOAT,
    INTEGER,
    LONGBLOB,
    LONGTEXT,
    MEDIUMBLOB,
    MEDIUMINT,
    MEDIUMTEXT,
    NCHAR,
    NUMERIC,
    NVARCHAR,
    REAL,
    SET,
    SMALLINT,
    TEXT,
    TIME,
    TIMESTAMP,
    TINYBLOB,
    TINYINT,
    TINYTEXT,
    VARBINARY,
    VARCHAR,
    YEAR,
)

MySQL 特有的类型，或具有特定于 MySQL 的构造参数的类型如下：

class sqlalchemy.dialects.mysql.BIGINT

MySQL BIGINTEGER 类型。

成员

init()

类签名

class sqlalchemy.dialects.mysql.BIGINT (sqlalchemy.dialects.mysql.types._IntegerType, sqlalchemy.types.BIGINT)

method __init__(display_width=None, **kw)

构造一个 BIGINTEGER。

参数：

• display_width – 可选，此数字的最大显示宽度。
  
• unsigned – 一个布尔值，可选。
  
• zerofill – 可选。如果为 true，则值将以左填充零的字符串形式存储。注意，这不会影响底层数据库 API 返回的值，其仍然是数值。
  

class sqlalchemy.dialects.mysql.BINARY

SQL BINARY 类型。

类签名

class sqlalchemy.dialects.mysql.BINARY (sqlalchemy.types._Binary)

class sqlalchemy.dialects.mysql.BIT

MySQL BIT 类型。

此类型适用于 MySQL 5.0.3 或更高版本的 MyISAM，并且适用于 5.0.5 或更高版本的 MyISAM、MEMORY、InnoDB 和 BDB。对于较旧版本，请使用 MSTinyInteger() 类型。

成员

init()

类签名

class sqlalchemy.dialects.mysql.BIT (sqlalchemy.types.TypeEngine)

method __init__(length=None)

构造一个 BIT。

参数：

length – 可选，位数。

class sqlalchemy.dialects.mysql.BLOB

SQL BLOB 类型。

类签名

class sqlalchemy.dialects.mysql.BLOB (sqlalchemy.types.LargeBinary)

method __init__(length: int | None = None)

继承自 LargeBinary 的 sqlalchemy.types.LargeBinary.__init__ 方法

构造一个 LargeBinary 类型。

参数：

length – 可选，用于 DDL 语句中的列长度，适用于那些接受长度的二进制类型，比如 MySQL BLOB 类型。

class sqlalchemy.dialects.mysql.BOOLEAN

SQL BOOLEAN 类型。

类签名

class sqlalchemy.dialects.mysql.BOOLEAN (sqlalchemy.types.Boolean)

method __init__(create_constraint: bool = False, name: str | None = None, _create_events: bool = True, _adapted_from: SchemaType | None = None)

继承自 Boolean 的 sqlalchemy.types.Boolean.__init__ 方法

构造一个 Boolean。

参数：

• create_constraint –
  默认为 False。如果将布尔值生成为 int/smallint，则还在表上创建一个 CHECK 约束，以确保值为 1 或 0。
  注意
  强烈建议 CHECK 约束具有明确的名称，以支持模式管理问题。这可以通过设置 Boolean.name 参数或设置适当的命名约定来建立；有关背景信息，请参阅 配置约束命名约定。
  从版本 1.4 开始更改：- 此标志现在默认为 False，表示非本地枚举类型不生成 CHECK 约束。
  
• name – 如果生成 CHECK 约束，请指定约束的名称。
  

class sqlalchemy.dialects.mysql.CHAR

MySQL CHAR 类型，用于固定长度的字符数据。

成员

init()

类签名

类 sqlalchemy.dialects.mysql.CHAR (sqlalchemy.dialects.mysql.types._StringType, sqlalchemy.types.CHAR)

method __init__(length=None, **kwargs)

构建一个 CHAR。

参数：

• length – 最大数据长度，以字符为单位。
  
• binary – 可选项，使用国家字符集的默认二进制排序规则。这不影响存储的数据类型，对于二进制数据，请使用 BINARY 类型。
  
• collation – 可选项，请求特定排序规则。必须与国家字符集兼容。
  

class sqlalchemy.dialects.mysql.DATE

SQL DATE 类型。

类签名

类 sqlalchemy.dialects.mysql.DATE (sqlalchemy.types.Date)

class sqlalchemy.dialects.mysql.DATETIME

MySQL DATETIME 类型。

成员

init()

类签名

类 sqlalchemy.dialects.mysql.DATETIME (sqlalchemy.types.DATETIME)

method __init__(timezone=False, fsp=None)

构建一个 MySQL DATETIME 类型。

参数：

• timezone – MySQL 方言不使用。
  
• fsp –
  小数秒精度值。MySQL 5.6.4 支持小数秒的存储；在发出 DATETIME 类型的 DDL 时将使用此参数。
  注意
  DBAPI 驱动程序对小数秒的支持可能有限；当前支持包括 MySQL Connector/Python。
  

class sqlalchemy.dialects.mysql.DECIMAL

MySQL DECIMAL 类型。

成员

init()

类签名

类 sqlalchemy.dialects.mysql.DECIMAL (sqlalchemy.dialects.mysql.types._NumericType, sqlalchemy.types.DECIMAL)

method __init__(precision=None, scale=None, asdecimal=True, **kw)

构建一个 DECIMAL。

参数：

• precision – 此数字中的总位数。如果比例和精度都为 None，则值将存储到服务器允许的限制。
  
• scale – 小数点后的位数。
  
• unsigned – 一个布尔值，可选。
  
• zerofill – 可选项。如果为真，则值将以左侧填充零的字符串形式存储。请注意，这不会影响底层数据库 API 返回的值，其仍然是数值。
  

class sqlalchemy.dialects.mysql.DOUBLE

MySQL DOUBLE 类型。

类签名

class sqlalchemy.dialects.mysql.DOUBLE (sqlalchemy.dialects.mysql.types._FloatType, sqlalchemy.types.DOUBLE)

method __init__(precision=None, scale=None, asdecimal=True, **kw)

构造一个 DOUBLE。

注意

默认情况下，DOUBLE 类型将从浮点数转换为 Decimal，使用默认的截断为 10 位数。指定 scale=n 或 decimal_return_scale=n 以更改此比例，或者 asdecimal=False 以直接返回 Python 浮点数值。

参数：

• precision – 此数字中的总位数。如果 scale 和 precision 都为 None，则值将存储到服务器允许的限制。
  
• scale – 小数点后的位数。
  
• unsigned – 一个布尔值，可选。
  
• zerofill – 可选项。如果为真，则值将以左侧填充零的字符串形式存储。请注意，这不会影响底层数据库 API 返回的值，其仍然是数值。
  

class sqlalchemy.dialects.mysql.ENUM

MySQL ENUM 类型。

成员

init()

类签名

class sqlalchemy.dialects.mysql.ENUM (sqlalchemy.types.NativeForEmulated, sqlalchemy.types.Enum, sqlalchemy.dialects.mysql.types._StringType)

method __init__(*enums, **kw)

构造一个 ENUM。

例如：

Column('myenum', ENUM("foo", "bar", "baz"))

参数：

• enums –
  此 ENUM 的有效值范围。在枚举中的值不带引号，生成模式时将被转义并用单引号括起。此对象也可以是符合 PEP-435 的枚举类型。
  
• strict –
  此标志无效。
  在版本更改：MySQL ENUM 类型以及基本 Enum 类型现在验证所有 Python 数据值。
  
• charset – 可选项，用于此字符串值的列级字符集。优先于‘ascii’或‘unicode’简写。
  
• collation – 可选项，用于此字符串值的列级排序。优先于‘binary’简写。
  
• ascii – 默认为 False：latin1 字符集的简写，生成模式中的 ASCII。
  
• unicode – 默认为 False：ucs2 字符集的简写，生成模式中的 UNICODE。
  
• binary – 默认为 False：简写，选择与列的字符集匹配的二进制排序类型。在模式中生成 BINARY。这不会影响存储的数据类型，只会影响字符数据的排序。
  

class sqlalchemy.dialects.mysql.FLOAT

MySQL FLOAT 类型。

成员

init()

类签名

类 sqlalchemy.dialects.mysql.FLOAT (sqlalchemy.dialects.mysql.types._FloatType, sqlalchemy.types.FLOAT)

method __init__(precision=None, scale=None, asdecimal=False, **kw)

构造一个浮点数。

参数:

• precision – 此数字中的总位数。如果 scale 和 precision 都为 None，则将值存储到服务器允许的限制。
  
• scale – 小数点后的位数。
  
• unsigned – 一个布尔值，可选。
  
• zerofill – 可选。如果为 true，则值将存储为左填充的带有零的字符串。请注意，这不会影响底层数据库 API 返回的值，其仍然为数值。
  

class sqlalchemy.dialects.mysql.INTEGER

MySQL INTEGER 类型。

成员

init()

类签名

类 sqlalchemy.dialects.mysql.INTEGER (sqlalchemy.dialects.mysql.types._IntegerType, sqlalchemy.types.INTEGER)

method __init__(display_width=None, **kw)

构造一个整数。

参数:

• display_width – 可选，此数字的最大显示宽度。
  
• unsigned – 一个布尔值，可选。
  
• zerofill – 可选。如果为 true，则值将存储为左填充的带有零的字符串。请注意，这不会影响底层数据库 API 返回的值，其仍然为数值。
  

class sqlalchemy.dialects.mysql.JSON

MySQL JSON 类型。

MySQL 从版本 5.7 开始支持 JSON。MariaDB 从版本 10.2 开始支持 JSON（作为 LONGTEXT 的别名）。

当基本的 JSON 数据类型与 MySQL 或 MariaDB 后端一起使用时，JSON 会自动使用。

另请参阅

JSON - 用于通用跨平台 JSON 数据类型的主要文档。

JSON 类型支持 JSON 值的持久性以及通过调整操作以在数据库级别呈现 JSON_EXTRACT 函数所提供的核心索引操作，从而适应基本的 JSON 数据类型。

类签名

类 sqlalchemy.dialects.mysql.JSON （sqlalchemy.types.JSON）

class sqlalchemy.dialects.mysql.LONGBLOB

MySQL LONGBLOB 类型，用于二进制数据最多 2³² 字节。

类签名

类 sqlalchemy.dialects.mysql.LONGBLOB (sqlalchemy.types._Binary)

class sqlalchemy.dialects.mysql.LONGTEXT

MySQL LONGTEXT 类型，用于字符存储编码最多 2³² 字节。

成员

init()

类签名

类 sqlalchemy.dialects.mysql.LONGTEXT (sqlalchemy.dialects.mysql.types._StringType)

method __init__(**kwargs)

构造一个 LONGTEXT。

参数：

• charset – 可选，此字符串值的列级字符集。优先于‘ascii’或‘unicode’简写。
  
• collation – 可选，此字符串值的列级校对。优先于‘binary’简写。
  
• ascii – 默认为 False：latin1字符集的简写，生成模式中的 ASCII。
  
• unicode – 默认为 False：ucs2字符集的简写，生成模式中的 UNICODE。
  
• national – 可选。如果为 true，则使用服务器配置的国家字符集。
  
• binary – 默认为 False：简写，选择与列的字符集匹配的二进制校对类型。在模式中生成 BINARY。这不影响存储的数据类型，只影响字符数据的校对。
  

class sqlalchemy.dialects.mysql.MEDIUMBLOB

MySQL MEDIUMBLOB 类型，用于二进制数据达到 2²⁴ 字节。

类签名

类 sqlalchemy.dialects.mysql.MEDIUMBLOB (sqlalchemy.types._Binary)

class sqlalchemy.dialects.mysql.MEDIUMINT

MySQL MEDIUMINTEGER 类型。

成员

init()

类签名

类 sqlalchemy.dialects.mysql.MEDIUMINT (sqlalchemy.dialects.mysql.types._IntegerType)

method __init__(display_width=None, **kw)

构造一个 MEDIUMINTEGER

参数：

• display_width – 可选，此数字的最大显示宽度。
  
• unsigned – 一个布尔值，可选。
  
• zerofill – 可选。如果为 true，则值将以左边填充零的字符串形式存储。请注意，这不影响底层数据库 API 返回的值，其仍然是数值。
  

class sqlalchemy.dialects.mysql.MEDIUMTEXT

MySQL MEDIUMTEXT 类型，用于存储编码达到 2²⁴ 字节的字符。

成员

init()

类签名

类 sqlalchemy.dialects.mysql.MEDIUMTEXT (sqlalchemy.dialects.mysql.types._StringType)

method __init__(**kwargs)

构造一个 MEDIUMTEXT。

参数：

• charset – 可选，此字符串值的列级字符集。优先于‘ascii’或‘unicode’简写。
  
• collation – 可选，此字符串值的列级校对。优先于‘binary’简写。
  
• ascii – 默认为 False：latin1字符集的简写，生成模式中的 ASCII。
  
• unicode – 默认为 False：ucs2字符集的简写，生成模式中的 UNICODE。
  
• national – 可选。如果为 true，则使用服务器配置的国家字符集。
  
• binary – 默认为 False：简写，选择与列的字符集匹配的二进制校对类型。在模式中生成 BINARY。这不影响存储的数据类型，只影响字符数据的校对。
  

class sqlalchemy.dialects.mysql.NCHAR

MySQL NCHAR 类型。

用于服务器配置的国家字符集中的固定长度字符数据。

成员

init()

类签名

类sqlalchemy.dialects.mysql.NCHAR（sqlalchemy.dialects.mysql.types._StringType，sqlalchemy.types.NCHAR）

method __init__(length=None, **kwargs)

构造一个 NCHAR。

参数：

• length – 最大数据长度，以字符为单位。
  
• binary – 可选，使用国家字符集的默认二进制排序规则。这不会影响存储的数据类型，对于二进制数据，请使用 BINARY 类型。
  
• collation – 可选，请求特定��排序规则。必须与国家字符集兼容。
  

class sqlalchemy.dialects.mysql.NUMERIC

MySQL NUMERIC 类型。

成员

init()

类签名

类sqlalchemy.dialects.mysql.NUMERIC（sqlalchemy.dialects.mysql.types._NumericType，sqlalchemy.types.NUMERIC）

method __init__(precision=None, scale=None, asdecimal=True, **kw)

构造一个 NUMERIC。

参数：

• precision – 此数字中的总位数。如果比例和精度都为 None，则值将存储到服务器允许的限制。
  
• scale – 小数点后的位数。
  
• unsigned – 一个布尔值，可选。
  
• zerofill – 可选。如果为 true，则值将以左侧填充零的字符串形式存储。请注意，这不会影响底层数据库 API 返回的值，其仍然是数值型的。
  

class sqlalchemy.dialects.mysql.NVARCHAR

MySQL NVARCHAR 类型。

用于服务器配置的国家字符集中的可变长度字符数据。

成员

init()

类签名

类sqlalchemy.dialects.mysql.NVARCHAR（sqlalchemy.dialects.mysql.types._StringType，sqlalchemy.types.NVARCHAR）

method __init__(length=None, **kwargs)

构造一个 NVARCHAR。

参数：

• length – 最大数据长度，以字符为单位。
  
• binary – 可选，使用国家字符集的默认二进制排序规则。这不会影响存储的数据类型，对于二进制数据，请使用 BINARY 类型。
  
• collation – 可选，请求特定的排序规则。必须与国家字符集兼容。
  

class sqlalchemy.dialects.mysql.REAL

MySQL REAL 类型。

成员

init()

类签名

类sqlalchemy.dialects.mysql.REAL（sqlalchemy.dialects.mysql.types._FloatType，sqlalchemy.types.REAL）

method __init__(precision=None, scale=None, asdecimal=True, **kw)

构造一个 REAL。

注意

默认情况下，REAL 类型将从浮点数转换为 Decimal，使用默认为 10 位的截断。要更改此标度，请指定 scale=n 或 decimal_return_scale=n，或者指定 asdecimal=False 以直接将值返回为 Python 浮点数。

参数：

• precision – 此数字中的总位数。如果 scale 和 precision 都为 None，则值将存储到服务器允许的限制。
  
• scale – 小数点后的位数。
  
• unsigned – 一个布尔值，可选。
  
• zerofill – 可选。如果为真，则值将作为用零左填充的字符串存储。请注意，这不影响底层数据库 API 返回的值，这些值仍然是数字。
  

class sqlalchemy.dialects.mysql.SET

MySQL SET 类型。

成员

init()

类签名

类 sqlalchemy.dialects.mysql.SET (sqlalchemy.dialects.mysql.types._StringType)

method __init__(*values, **kw)

构造一个 SET。

例如：

Column('myset', SET("foo", "bar", "baz"))

在此 set 将用于为表生成 DDL 或者如果 SET.retrieve_as_bitwise 标志设置为 True，则必须提供潜在值的列表。

参数：

• values – 此 SET 的有效值范围。这些值不加引号，生成模式时会被转义并用单引号括起来。
  
• convert_unicode – 与 String.convert_unicode 相同的标志。
  
• collation – 与 String.collation 相同。
  
• charset – 与 VARCHAR.charset 相同。
  
• ascii – 与 VARCHAR.ascii 相同。
  
• unicode – 与 VARCHAR.unicode 相同。
  
• binary – 与 VARCHAR.binary 相同。
  
• retrieve_as_bitwise –
  如果为 True，set 类型的数据将使用整数值进行持久化和选择，其中一个 set 被强制转换为位掩码进行持久化。MySQL 允许此模式，它的优点是能够明确地存储值，如空字符串 ''。在 SELECT 语句中，数据类型将显示为表达式 col + 0，以便值被强制转换为整数值在结果集中返回。如果希望持久化一个可以存储空字符串 '' 作为值的 set，则需要此标志。
  警告
  在使用 SET.retrieve_as_bitwise 时，重要的是确保集合值的列表与 MySQL 数据库中存在的完全相同的顺序。
  

class sqlalchemy.dialects.mysql.SMALLINT

MySQL SMALLINTEGER 类型。

成员

init()

类签名

类 sqlalchemy.dialects.mysql.SMALLINT (sqlalchemy.dialects.mysql.types._IntegerType, sqlalchemy.types.SMALLINT)

method __init__(display_width=None, **kw)

构造一个 SMALLINTEGER。

参数：

• display_width – 可选，此数字的最大显示宽度。
  
• unsigned – 一个布尔值，可选。
  
• zerofill – 可选。如果为真，则值将作为用零填充的字符串存储。请注意，这不影响底层数据库 API 返回的值，它们仍然是数字。
  

class sqlalchemy.dialects.mysql.TEXT

MySQL TEXT 类型，用于存储编码为最多 2¹⁶ 字节的字符。

类签名

类 sqlalchemy.dialects.mysql.TEXT (sqlalchemy.dialects.mysql.types._StringType, sqlalchemy.types.TEXT)

method __init__(length=None, **kw)

构造一个 TEXT。

参数：

• length – 可选，如果提供了，服务器可以通过用足够存储 length 字节字符的最小 TEXT 类型替换来优化存储。
  
• charset – 可选，此字符串值的列级字符集。优先于 ‘ascii’ 或 ‘unicode’ 简写。
  
• collation – 可选，此字符串值的列级排序。优先于 ‘binary’ 简写。
  
• ascii – 默认为 False：latin1 字符集的简写，生成模式中的 ASCII。
  
• unicode – 默认为 False：ucs2 字符集的简写，生成模式中的 UNICODE。
  
• national – 可选。如果为真，则使用服务器配置的国家字符集。
  
• binary – 默认为 False：简写，选择与列的字符集匹配的二进制排序类型。在模式中生成 BINARY。这不影响存储的数据类型，只影响字符数据的排序。
  

class sqlalchemy.dialects.mysql.TIME

MySQL TIME 类型。

成员

init()

类签名

类 sqlalchemy.dialects.mysql.TIME (sqlalchemy.types.TIME)

method __init__(timezone=False, fsp=None)

构造一个 MySQL TIME 类型。

参数：

• timezone – MySQL 方言不使用。
  
• fsp –
  分数秒精度值。MySQL 5.6 支持存储分数秒；在发出 TIME 类型的 DDL 时将使用此参数。
  注意
  DBAPI 驱动程序对于分数秒的支持可能有限；当前支持包括 MySQL Connector/Python。
  

class sqlalchemy.dialects.mysql.TIMESTAMP

MySQL TIMESTAMP 类型。

成员

init()

类签名

类 sqlalchemy.dialects.mysql.TIMESTAMP (sqlalchemy.types.TIMESTAMP)

method __init__(timezone=False, fsp=None)

构造一个 MySQL TIMESTAMP 类型。

参数：

• timezone – MySQL 方言不使用。
  
• fsp –
  分数秒精度值。MySQL 5.6.4 支持分数秒的存储；在为 TIMESTAMP 类型发出 DDL 时将使用此参数。
  注意
  DBAPI 驱动程序对分数秒的支持可能有限；当前支持包括 MySQL Connector/Python。
  

class sqlalchemy.dialects.mysql.TINYBLOB

MySQL TINYBLOB 类型，用于存储最多 2⁸ 字节的二进制数据。

类签名

类 sqlalchemy.dialects.mysql.TINYBLOB (sqlalchemy.types._Binary)

class sqlalchemy.dialects.mysql.TINYINT

MySQL TINYINT 类型。

成员

init()

类签名

类 sqlalchemy.dialects.mysql.TINYINT (sqlalchemy.dialects.mysql.types._IntegerType)

method __init__(display_width=None, **kw)

构造一个 TINYINT。

参数：

• display_width – 可选，此数字的最大显示宽度。
  
• unsigned – 一个布尔值，可选。
  
• zerofill – 可选。如果为 true，则值将存储为左填充零的字符串。注意，这不会影响底层数据库 API 返回的值，这些值仍然是数字。
  

class sqlalchemy.dialects.mysql.TINYTEXT

MySQL TINYTEXT 类型，用于存储编码为 2⁸ 字节的字符。

成员

init()

类签名

类 sqlalchemy.dialects.mysql.TINYTEXT (sqlalchemy.dialects.mysql.types._StringType)

method __init__(**kwargs)

构造一个 TINYTEXT。

参数：

• charset – 可选，此字符串值的列级字符集。优先于 ‘ascii’ 或 ‘unicode’ 简写。
  
• collation – 可选，此字符串值的列级排序。优先于 ‘binary’ 简写。
  
• ascii – 默认为 False：latin1 字符集的简写，在模式中生成 ASCII。
  
• unicode – 默认为 False：ucs2 字符集的简写，在模式中生成 UNICODE。
  
• national – 可选。如果为 true，则使用服务器配置的国家字符集。
  
• binary – 默认为 False：简写，选择与列的字符集匹配的二进制排序类型。在模式中生成 BINARY。这不影响存储的数据类型，只影响字符数据的排序。
  

class sqlalchemy.dialects.mysql.VARBINARY

SQL VARBINARY 类型。

类签名

类 sqlalchemy.dialects.mysql.VARBINARY (sqlalchemy.types._Binary)

class sqlalchemy.dialects.mysql.VARCHAR

MySQL VARCHAR 类型，用于可变长度字符数据。

成员

init()

类签名

类sqlalchemy.dialects.mysql.VARCHAR (sqlalchemy.dialects.mysql.types._StringType, sqlalchemy.types.VARCHAR)

method __init__(length=None, **kwargs)

构造一个 VARCHAR。

参数：

• charset – 可选，此字符串值的列级字符集。优先于‘ascii’或‘unicode’的简写形式。
  
• collation – 可选，此字符串值的列级排序规则。优先于‘binary’的简写形式。
  
• ascii – 默认为 False：latin1字符集的简写形式，在模式中生成 ASCII。
  
• unicode – 默认为 False：ucs2字符集的简写形式，在模式中生成 UNICODE。
  
• national – 可选。如果为 true，则使用服务器配置的国家字符集。
  
• binary – 默认为 False：简写形式，选择与列的字符集匹配的二进制排序类型。在模式中生成 BINARY。这不影响存储的数据类型，只影响字符数据的排序规则。
  

class sqlalchemy.dialects.mysql.YEAR

MySQL YEAR 类型，用于存储 1901-2155 年的单字节。

类签名

类sqlalchemy.dialects.mysql.YEAR (sqlalchemy.types.TypeEngine)

MySQL DML 构造

function sqlalchemy.dialects.mysql.insert(table: _DMLTableArgument) → Insert

构造一个 MySQL/MariaDB 特定变体的Insert构造。

sqlalchemy.dialects.mysql.insert()函数创建一个sqlalchemy.dialects.mysql.Insert。这个类基于方言不可知的Insert构造，可以使用 SQLAlchemy Core 中的insert()函数构造。

Insert构造包括额外的方法Insert.on_duplicate_key_update()。

class sqlalchemy.dialects.mysql.Insert

INSERT 的 MySQL 特定实现。

添加用于 MySQL 特定语法的方法，如 ON DUPLICATE KEY UPDATE。

Insert对象是使用sqlalchemy.dialects.mysql.insert()函数创建的。

版本 1.2 中的新功能。

成员

inherit_cache, inserted, on_duplicate_key_update()

类签名

类sqlalchemy.dialects.mysql.Insert (sqlalchemy.sql.expression.Insert)

attribute inherit_cache: bool | None = False

指示此HasCacheKey实例是否应使用其直接超类使用的缓存键生成方案。

该属性默认为None，表示构造尚未考虑其是否适合参与缓存；这在功能上等同于将值设置为False，只是还会发出警告。

如果与该对象对应的 SQL 不基于此类的本地属性而是其超类，则可以在特定类上将此标志设置为True。

另请参阅

为自定义构造启用缓存支持 - 为第三方或用户定义的 SQL 构造设置HasCacheKey.inherit_cache属性的一般指南。

attribute inserted

为 ON DUPLICATE KEY UPDATE 语句提供“inserted”命名空间

MySQL 的 ON DUPLICATE KEY UPDATE 子句允许引用将要插入的行，通过一个名为VALUES()的特殊函数。此属性提供了此行中的所有列可引用，以便它们在 ON DUPLICATE KEY UPDATE 子句中的VALUES()函数内呈现。该属性命名为.inserted，以避免与现有的Insert.values()方法发生冲突。

提示

Insert.inserted 属性是 ColumnCollection 的实例，提供了与 访问表和列 中描述的 Table.c 集合相同的接口。使用此集合，可以像属性一样访问普通名称（例如 stmt.inserted.some_column），但应该使用索引访问特殊名称和字典方法名称，例如 stmt.inserted["column name"] 或 stmt.inserted["values"]。有关更多示例，请参阅 ColumnCollection 的文档字符串。

另请参阅

INSERT…ON DUPLICATE KEY UPDATE（插入或更新） - 使用 Insert.inserted 的示例

method on_duplicate_key_update(*args: Mapping[Any, Any] | List[Tuple[str, Any]] | ColumnCollection[Any, Any], **kw: Any) → Self

指定 ON DUPLICATE KEY UPDATE 子句。

参数：

**kw – 与 UPDATE 值关联的列键。值可以是任何 SQL 表达式或支持的字面 Python 值。

警告

此字典不会考虑 Python 指定的默认 UPDATE 值或生成函数，例如那些使用 Column.onupdate 指定的值。除非在此处手动指定值，否则这些值将不会被用于 ON DUPLICATE KEY UPDATE 风格的 UPDATE。

参数：

*args –

作为传递键/值参数的替代方法，可以将字典或 2 元组的列表作为单个位置参数传递。

传递单个字典相当于关键字参数形式：

insert().on_duplicate_key_update({"name": "some name"})

传递 2 元组的列表表示 UPDATE 子句中的参数分配应按发送顺序排序，类似于整体描述的 Update 构造中的 参数排序更新：

insert().on_duplicate_key_update(
    [("name", "some name"), ("value", "some value")])

自 1.3 版更改：参数可以指定为字典或 2 元组的列表；后一种形式提供了参数的排序。

自 1.2 版新功能。

另请参阅

INSERT…ON DUPLICATE KEY UPDATE（插入或更新）

mysqlclient（MySQL-Python 的分支）

通过 mysqlclient（MySQL-Python 的维护分支）驱动程序支持 MySQL / MariaDB 数据库。

DBAPI

mysqlclient（MySQL-Python 的维护分支）的文档和下载信息（如果适用）可在此处找到：pypi.org/project/mysqlclient/

连接中

连接字符串：

mysql+mysqldb://<user>:<password>@<host>[:<port>]/<dbname>

驱动程序状态

mysqlclient DBAPI 是MySQL-Python DBAPI 的维护分支，后者已不再维护。mysqlclient支持 Python 2 和 Python 3，并且非常稳定。

Unicode

请参阅 Unicode 以获取有关 Unicode 处理的当前建议。### SSL Connections

mysqlclient 和 PyMySQL DBAPI 接受一个额外的字典，键为“ssl”，可以使用create_engine.connect_args字典指定：

engine = create_engine(
    "mysql+mysqldb://scott:tiger@192.168.0.134/test",
    connect_args={
        "ssl": {
            "ca": "/home/gord/client-ssl/ca.pem",
            "cert": "/home/gord/client-ssl/client-cert.pem",
            "key": "/home/gord/client-ssl/client-key.pem"
        }
    }
)

为方便起见，以下键也可以内联在 URL 中指定，它们将自动解释为“ssl”字典中： “ssl_ca”，“ssl_cert”，“ssl_key”，“ssl_capath”，“ssl_cipher”，“ssl_check_hostname”。示例如下：

connection_uri = (
    "mysql+mysqldb://scott:tiger@192.168.0.134/test"
    "?ssl_ca=/home/gord/client-ssl/ca.pem"
    "&ssl_cert=/home/gord/client-ssl/client-cert.pem"
    "&ssl_key=/home/gord/client-ssl/client-key.pem"
)

另请参阅

SSL Connections 在 PyMySQL 方言中

使用 MySQLdb 与 Google Cloud SQL

Google Cloud SQL 现在建议使用 MySQLdb 方言。使用以下 URL 进行连接：

mysql+mysqldb://root@/<dbname>?unix_socket=/cloudsql/<projectid>:<instancename>

服务器端游标

mysqldb 方言支持服务器端游标。请参阅 Server Side Cursors。

DBAPI

mysqlclient（MySQL-Python 的维护分支）的文档和下载信息（如果适用）可在以下链接找到：pypi.org/project/mysqlclient/

连接中

连接字符串：

mysql+mysqldb://<user>:<password>@<host>[:<port>]/<dbname>

驱动程序状态

mysqlclient DBAPI 是MySQL-Python DBAPI 的维护分支，后者已不再维护。mysqlclient支持 Python 2 和 Python 3，并且非常稳定。

Unicode

请参阅 Unicode 以获取有关 Unicode 处理的当前建议。

SSL Connections

mysqlclient 和 PyMySQL DBAPI 接受一个额外的字典，键为“ssl”，可以使用create_engine.connect_args字典指定：

engine = create_engine(
    "mysql+mysqldb://scott:tiger@192.168.0.134/test",
    connect_args={
        "ssl": {
            "ca": "/home/gord/client-ssl/ca.pem",
            "cert": "/home/gord/client-ssl/client-cert.pem",
            "key": "/home/gord/client-ssl/client-key.pem"
        }
    }
)

为方便起见，以下键也可以内联在 URL 中指定，它们将自动解释为“ssl”字典中： “ssl_ca”，“ssl_cert”，“ssl_key”，“ssl_capath”，“ssl_cipher”，“ssl_check_hostname”。示例如下：

connection_uri = (
    "mysql+mysqldb://scott:tiger@192.168.0.134/test"
    "?ssl_ca=/home/gord/client-ssl/ca.pem"
    "&ssl_cert=/home/gord/client-ssl/client-cert.pem"
    "&ssl_key=/home/gord/client-ssl/client-key.pem"
)

另请参阅

SSL Connections 在 PyMySQL 方言中

使用 MySQLdb 与 Google Cloud SQL

Google Cloud SQL 现在建议使用 MySQLdb 方言。使用以下 URL 进行连接：

mysql+mysqldb://root@/<dbname>?unix_socket=/cloudsql/<projectid>:<instancename>

服务器端游标

mysqldb 方言支持服务器端游标。请参阅 Server Side Cursors。

PyMySQL

通过 PyMySQL 驱动程序支持 MySQL / MariaDB 数据库。

DBAPI

PyMySQL 的文档和下载信息（如果适用）可在以下链接找到：pymysql.readthedocs.io/

连接中

连接字符串：

mysql+pymysql://<username>:<password>@<host>/<dbname>[?<options>]

Unicode

请参阅 Unicode 以获取有关 Unicode 处理的当前建议。

SSL 连接

PyMySQL DBAPI 接受与 MySQLdb 相同���SSL 参数，详见 SSL 连接。请参阅该部分以获取其他示例。

如果服务器使用自动生成的自签名证书或与主机名不匹配（从客户端看），还可能需要在 PyMySQL 中指定ssl_check_hostname=false：

connection_uri = (
    "mysql+pymysql://scott:tiger@192.168.0.134/test"
    "?ssl_ca=/home/gord/client-ssl/ca.pem"
    "&ssl_cert=/home/gord/client-ssl/client-cert.pem"
    "&ssl_key=/home/gord/client-ssl/client-key.pem"
    "&ssl_check_hostname=false"
)

MySQL-Python 兼容性

pymysql DBAPI 是 MySQL-python（MySQLdb）驱动程序的纯 Python 移植版本，目标是 100%兼容。对于 MySQL-python 的大多数行为注意事项也适用于 pymysql 驱动程序。

DBAPI

PyMySQL 的文档和下载信息（如果适用）可在此处找到：pymysql.readthedocs.io/

连接

连接字符串:

mysql+pymysql://<username>:<password>@<host>/<dbname>[?<options>]

Unicode

有关当前有关 Unicode 处理的建议，请参阅 Unicode。

SSL 连接

PyMySQL DBAPI 接受与 MySQLdb 相同的 SSL 参数，详见 SSL 连接。请参阅该部分以获取其他示例。

如果服务器使用自动生成的自签名证书或与主机名不匹配（从客户端看），还可能需要在 PyMySQL 中指定ssl_check_hostname=false：

connection_uri = (
    "mysql+pymysql://scott:tiger@192.168.0.134/test"
    "?ssl_ca=/home/gord/client-ssl/ca.pem"
    "&ssl_cert=/home/gord/client-ssl/client-cert.pem"
    "&ssl_key=/home/gord/client-ssl/client-key.pem"
    "&ssl_check_hostname=false"
)

MySQL-Python 兼容性

pymysql DBAPI 是 MySQL-python（MySQLdb）驱动程序的纯 Python 移植版本，目标是 100%兼容。对于 MySQL-python 的大多数行为注意事项也适用于 pymysql 驱动程序。

MariaDB-连接器

通过 MariaDB Connector/Python 驱动程序支持 MySQL / MariaDB 数据库。

DBAPI

MariaDB Connector/Python 的文档和下载信息（如果适用）可在此处找到：pypi.org/project/mariadb/

连接

连接字符串:

mariadb+mariadbconnector://<user>:<password>@<host>[:<port>]/<dbname>

驱动程序状态

MariaDB Connector/Python 使 Python 程序能够使用符合 Python DB API  2.0（PEP-249）的 API 访问 MariaDB 和 MySQL 数据库。它是用 C 编写的，并使用 MariaDB  Connector/C 客户端库进行客户端服务器通信。

请注意，mariadb://连接 URI 的默认驱动程序仍然是mysqldb。要使用此驱动程序，需要mariadb+mariadbconnector://。

DBAPI

MariaDB Connector/Python 的文档和下载信息（如果适用）可在此处找到：pypi.org/project/mariadb/

连接

连接字符串:

mariadb+mariadbconnector://<user>:<password>@<host>[:<port>]/<dbname>

驱动程序状态

MariaDB Connector/Python 使 Python 程序能够使用符合 Python DB API  2.0（PEP-249）的 API 访问 MariaDB 和 MySQL 数据库。它是用 C 编写的，并使用 MariaDB  Connector/C 客户端库进行客户端服务器通信。

请注意，mariadb://连接 URI 的默认驱动程序仍然是mysqldb。要使用此驱动程序，需要mariadb+mariadbconnector://。

MySQL-连接器

通过 MySQL Connector/Python 驱动程序支持 MySQL/MariaDB 数据库。

DBAPI

MySQL Connector/Python 的文档和下载信息（如果适用）可在此处获取：pypi.org/project/mysql-connector-python/

连接

连接字符串：

mysql+mysqlconnector://<user>:<password>@<host>[:<port>]/<dbname>

注意

自发布以来，MySQL Connector/Python DBAPI 存在许多问题，其中一些可能仍未解决，而 mysqlconnector 方言未作为 SQLAlchemy 持续集成的一部分进行测试。推荐的 MySQL 方言是 mysqlclient 和 PyMySQL。

DBAPI

MySQL Connector/Python 的文档和下载信息（如果适用）可在此处获取：pypi.org/project/mysql-connector-python/

连接

连接字符串：

mysql+mysqlconnector://<user>:<password>@<host>[:<port>]/<dbname>

asyncmy

通过 asyncmy 驱动程序支持 MySQL/MariaDB 数据库。

DBAPI

异步 MySQL 的文档和下载信息（如果适用）可在此处获取：github.com/long2ice/asyncmy

连接

连接字符串：

mysql+asyncmy://user:password@host:port/dbname[?key=value&key=value...]

使用特殊的 asyncio 中介层，asyncmy 方言可作为 SQLAlchemy asyncio 扩展包的后端使用。

此方言通常只应与create_async_engine()引擎创建函数一起使用：

from sqlalchemy.ext.asyncio import create_async_engine
engine = create_async_engine("mysql+asyncmy://user:pass@hostname/dbname?charset=utf8mb4")

DBAPI

异步 MySQL 的文档和下载信息（如果适用）可在此处获取：github.com/long2ice/asyncmy

连接

连接字符串：

mysql+asyncmy://user:password@host:port/dbname[?key=value&key=value...]

aiomysql

通过 aiomysql 驱动程序支持 MySQL/MariaDB 数据库。

DBAPI

aiomysql 的文档和下载信息（如果适用）可在此处获取：github.com/aio-libs/aiomysql

连接

连接字符串：

mysql+aiomysql://user:password@host:port/dbname[?key=value&key=value...]

aiomysql 方言是 SQLAlchemy 的第二个 Python asyncio 方言。

使用特殊的 asyncio 中介层，aiomysql 方言可作为 SQLAlchemy asyncio 扩展包的后端使用。

此方言通常只应与create_async_engine()引擎创建函数一起使用：

from sqlalchemy.ext.asyncio import create_async_engine
engine = create_async_engine("mysql+aiomysql://user:pass@hostname/dbname?charset=utf8mb4")

DBAPI

aiomysql 的文档和下载信息（如果适用）可在此处获取：github.com/aio-libs/aiomysql

连接

连接字符串：

mysql+aiomysql://user:password@host:port/dbname[?key=value&key=value...]

cymysql

通过 CyMySQL 驱动程序支持 MySQL/MariaDB 数据库。

DBAPI

CyMySQL 的文档和下载信息（如果适用）可在此处获取：github.com/nakagami/CyMySQL

连接

连接字符串：

mysql+cymysql://<username>:<password>@<host>/<dbname>[?<options>]

注意

CyMySQL 方言不在 SQLAlchemy 的持续集成测试范围内，可能存在未解决的问题。推荐使用的 MySQL 方言是 mysqlclient 和 PyMySQL。

DBAPI

CyMySQL 的文档和下载信息（如果适用）可在此处找到：github.com/nakagami/CyMySQL

连接

连接字符串：

mysql+cymysql://<username>:<password>@<host>/<dbname>[?<options>]

pyodbc

通过 PyODBC 驱动程序支持 MySQL / MariaDB 数据库。

DBAPI

PyODBC 的文档和下载信息（如果适用）可在此处找到：pypi.org/project/pyodbc/

连接

连接字符串：

mysql+pyodbc://<username>:<password>@<dsnname>

注意

PyODBC 对于 MySQL 方言不在 SQLAlchemy 的持续集成测试范围内。推荐使用的 MySQL 方言是 mysqlclient 和 PyMySQL。但是，如果您想使用 mysql+pyodbc 方言并且需要对utf8mb4字符（包括表情符号等辅助字符）进行完全支持，请确保使用当前版本的 MySQL Connector/ODBC 并在 DSN 或连接字符串中指定“ANSI”（而不是“Unicode”）版本的驱动程序。

通过精确的 pyodbc 连接字符串进行传递：

import urllib
connection_string = (
    'DRIVER=MySQL ODBC 8.0 ANSI Driver;'
    'SERVER=localhost;'
    'PORT=3307;'
    'DATABASE=mydb;'
    'UID=root;'
    'PWD=(whatever);'
    'charset=utf8mb4;'
)
params = urllib.parse.quote_plus(connection_string)
connection_uri = "mysql+pyodbc:///?odbc_connect=%s" % params

DBAPI

PyODBC 的文档和下载信息（如果适用）可在此处找到：pypi.org/project/pyodbc/

连接

连接字符串：

mysql+pyodbc://<username>:<password>@<dsnname>

thon 的文档和下载信息（如果适用）可在此处找到：pypi.org/project/mariadb/

连接

连接字符串:

mariadb+mariadbconnector://<user>:<password>@<host>[:<port>]/<dbname>

驱动程序状态

MariaDB Connector/Python 使 Python 程序能够使用符合 Python DB API  2.0（PEP-249）的 API 访问 MariaDB 和 MySQL 数据库。它是用 C 编写的，并使用 MariaDB  Connector/C 客户端库进行客户端服务器通信。

请注意，mariadb://连接 URI 的默认驱动程序仍然是mysqldb。要使用此驱动程序，需要mariadb+mariadbconnector://。

DBAPI

MariaDB Connector/Python 的文档和下载信息（如果适用）可在此处找到：pypi.org/project/mariadb/

连接

连接字符串:

mariadb+mariadbconnector://<user>:<password>@<host>[:<port>]/<dbname>

驱动程序状态

MariaDB Connector/Python 使 Python 程序能够使用符合 Python DB API  2.0（PEP-249）的 API 访问 MariaDB 和 MySQL 数据库。它是用 C 编写的，并使用 MariaDB  Connector/C 客户端库进行客户端服务器通信。

请注意，mariadb://连接 URI 的默认驱动程序仍然是mysqldb。要使用此驱动程序，需要mariadb+mariadbconnector://。

MySQL-连接器

通过 MySQL Connector/Python 驱动程序支持 MySQL/MariaDB 数据库。

DBAPI

MySQL Connector/Python 的文档和下载信息（如果适用）可在此处获取：pypi.org/project/mysql-connector-python/

连接

连接字符串：

mysql+mysqlconnector://<user>:<password>@<host>[:<port>]/<dbname>

注意

自发布以来，MySQL Connector/Python DBAPI 存在许多问题，其中一些可能仍未解决，而 mysqlconnector 方言未作为 SQLAlchemy 持续集成的一部分进行测试。推荐的 MySQL 方言是 mysqlclient 和 PyMySQL。

DBAPI

MySQL Connector/Python 的文档和下载信息（如果适用）可在此处获取：pypi.org/project/mysql-connector-python/

连接

连接字符串：

mysql+mysqlconnector://<user>:<password>@<host>[:<port>]/<dbname>

asyncmy

通过 asyncmy 驱动程序支持 MySQL/MariaDB 数据库。

DBAPI

异步 MySQL 的文档和下载信息（如果适用）可在此处获取：github.com/long2ice/asyncmy

连接

连接字符串：

mysql+asyncmy://user:password@host:port/dbname[?key=value&key=value...]

使用特殊的 asyncio 中介层，asyncmy 方言可作为 SQLAlchemy asyncio 扩展包的后端使用。

此方言通常只应与create_async_engine()引擎创建函数一起使用：

from sqlalchemy.ext.asyncio import create_async_engine
engine = create_async_engine("mysql+asyncmy://user:pass@hostname/dbname?charset=utf8mb4")

DBAPI

异步 MySQL 的文档和下载信息（如果适用）可在此处获取：github.com/long2ice/asyncmy

连接

连接字符串：

mysql+asyncmy://user:password@host:port/dbname[?key=value&key=value...]

aiomysql

通过 aiomysql 驱动程序支持 MySQL/MariaDB 数据库。

DBAPI

aiomysql 的文档和下载信息（如果适用）可在此处获取：github.com/aio-libs/aiomysql

连接

连接字符串：

mysql+aiomysql://user:password@host:port/dbname[?key=value&key=value...]

aiomysql 方言是 SQLAlchemy 的第二个 Python asyncio 方言。

使用特殊的 asyncio 中介层，aiomysql 方言可作为 SQLAlchemy asyncio 扩展包的后端使用。

此方言通常只应与create_async_engine()引擎创建函数一起使用：

from sqlalchemy.ext.asyncio import create_async_engine
engine = create_async_engine("mysql+aiomysql://user:pass@hostname/dbname?charset=utf8mb4")

DBAPI

aiomysql 的文档和下载信息（如果适用）可在此处获取：github.com/aio-libs/aiomysql

连接

连接字符串：

mysql+aiomysql://user:password@host:port/dbname[?key=value&key=value...]

cymysql

通过 CyMySQL 驱动程序支持 MySQL/MariaDB 数据库。

DBAPI

CyMySQL 的文档和下载信息（如果适用）可在此处获取：github.com/nakagami/CyMySQL

连接

连接字符串：

mysql+cymysql://<username>:<password>@<host>/<dbname>[?<options>]

注意

CyMySQL 方言不在 SQLAlchemy 的持续集成测试范围内，可能存在未解决的问题。推荐使用的 MySQL 方言是 mysqlclient 和 PyMySQL。

DBAPI

CyMySQL 的文档和下载信息（如果适用）可在此处找到：github.com/nakagami/CyMySQL

连接

连接字符串：

mysql+cymysql://<username>:<password>@<host>/<dbname>[?<options>]

pyodbc

通过 PyODBC 驱动程序支持 MySQL / MariaDB 数据库。

DBAPI

PyODBC 的文档和下载信息（如果适用）可在此处找到：pypi.org/project/pyodbc/

连接

连接字符串：

mysql+pyodbc://<username>:<password>@<dsnname>

注意

PyODBC 对于 MySQL 方言不在 SQLAlchemy 的持续集成测试范围内。推荐使用的 MySQL 方言是 mysqlclient 和 PyMySQL。但是，如果您想使用 mysql+pyodbc 方言并且需要对utf8mb4字符（包括表情符号等辅助字符）进行完全支持，请确保使用当前版本的 MySQL Connector/ODBC 并在 DSN 或连接字符串中指定“ANSI”（而不是“Unicode”）版本的驱动程序。

通过精确的 pyodbc 连接字符串进行传递：

import urllib
connection_string = (
    'DRIVER=MySQL ODBC 8.0 ANSI Driver;'
    'SERVER=localhost;'
    'PORT=3307;'
    'DATABASE=mydb;'
    'UID=root;'
    'PWD=(whatever);'
    'charset=utf8mb4;'
)
params = urllib.parse.quote_plus(connection_string)
connection_uri = "mysql+pyodbc:///?odbc_connect=%s" % params

DBAPI

PyODBC 的文档和下载信息（如果适用）可在此处找到：pypi.org/project/pyodbc/

连接

连接字符串：

mysql+pyodbc://<username>:<password>@<dsnname>