版本:1.1.0b2 |发布日期:2016年7月1日

SQLAlchemy 1.1文档

Microsoft SQL Server

支持Microsoft SQL Server数据库。

DBAPI支持

以下dialect / DBAPI选项可用。有关连接信息,请参阅各个DBAPI部分。

自动递增行为

SQL Server使用IDENTITY结构提供所谓的“自动递增”行为,该结构可放置在整数主键上。SQLAlchemy在Column.autoincrement中描述的默认“autoincrement”行为中考虑IDENTITY;这意味着默认情况下,Table中的第一个整数主键列将被视为标识列,并将生成DDL:

from sqlalchemy import Table, MetaData, Column, Integer

m = MetaData()
t = Table('t', m,
        Column('id', Integer, primary_key=True),
        Column('x', Integer))
m.create_all(engine)

上面的例子将生成DDL为:

CREATE TABLE t (
    id INTEGER NOT NULL IDENTITY(1,1),
    x INTEGER NULL,
    PRIMARY KEY (id)
)

对于不需要此默认的IDENTITY生成的情况,请在所有整数主键列上指定autoincrement=False

m = MetaData()
t = Table('t', m,
        Column('id', Integer, primary_key=True, autoincrement=False),
        Column('x', Integer))
m.create_all(engine)

注意

SQL Server禁止引用此类列的显式值的INSERT语句,但SQLAlchemy将检测到这一点,并在语句执行时相应地修改IDENTITY_INSERT标志。由于这不是一个高性能的过程,因此应该小心地为实际上不需要IDENTITY行为的列设置autoincrement标志。

控制“开始”和“递增”

使用schema.Sequence对象支持对IDENTITY值参数的特定控制。虽然此对象通常表示支持后端的显式“序列”,但在SQL Server上,它重新用于指定有关标识列的行为,包括对“开始”和“增量”值的支持:

from sqlalchemy import Table, Integer, Sequence, Column

Table('test', metadata,
       Column('id', Integer,
              Sequence('blah', start=100, increment=10),
              primary_key=True),
       Column('name', String(20))
     ).create(some_engine)

会产生:

CREATE TABLE test (
  id INTEGER NOT NULL IDENTITY(100,10) PRIMARY KEY,
  name VARCHAR(20) NULL,
  )

请注意,序列的startincrement值是可选的,将默认为1,1。

INSERT行为

在INSERT时间处理IDENTITY列涉及两个关键技术。The most common is being able to fetch the “last inserted value” for a given IDENTITY column, a process which SQLAlchemy performs implicitly in many cases, most importantly within the ORM.

获取这个值的过程有几个变种:

  • 在绝大多数情况下,RETURNING与SQL Server上的INSERT语句一起使用,以获取新生成的主键值:

    INSERT INTO t (x) OUTPUT inserted.id VALUES (?)
  • 当RETURNING不可用或已通过implicit_returning=False禁用时,使用scope_identity()函数或@@identity变量;行为因后端而异:

    • 当使用PyODBC时,短语 select scope_identity()将被附加到INSERT语句的末尾;第二个结果集将被提取以便接收该值。给定一个表格为:

      t = Table('t', m, Column('id', Integer, primary_key=True),
              Column('x', Integer),
              implicit_returning=False)

      INSERT将如下所示:

      INSERT INTO t (x) VALUES (?); select scope_identity()
    • Other dialects such as pymssql will call upon SELECT scope_identity() AS lastrowid subsequent to an INSERT statement. If the flag use_scope_identity=False is passed to create_engine(), the statement SELECT @@identity AS lastrowid is used instead.

包含IDENTITY列的表将禁止显式引用标识列的INSERT语句。The SQLAlchemy dialect will detect when an INSERT construct, created using a core insert() construct (not a plain string SQL), refers to the identity column, and in this case will emit SET IDENTITY_INSERT ON prior to the insert statement proceeding, and SET IDENTITY_INSERT OFF subsequent to the execution. 鉴于这个例子:

m = MetaData()
t = Table('t', m, Column('id', Integer, primary_key=True),
                Column('x', Integer))
m.create_all(engine)

engine.execute(t.insert(), {'id': 1, 'x':1}, {'id':2, 'x':2})

上面的列将使用IDENTITY创建,但是我们发出的INSERT语句是指定明确的值。在echo输出中,我们可以看到SQLAlchemy如何处理这个问题:

CREATE TABLE t (
    id INTEGER NOT NULL IDENTITY(1,1),
    x INTEGER NULL,
    PRIMARY KEY (id)
)

COMMIT
SET IDENTITY_INSERT t ON
INSERT INTO t (id, x) VALUES (?, ?)
((1, 1), (2, 2))
SET IDENTITY_INSERT t OFF
COMMIT

这是一个适用于测试和批量插入场景的辅助用例。

整理支持

字符排序规则由字符串参数“排序规则”指定的基本字符串类型支持:

from sqlalchemy import VARCHAR
Column('login', VARCHAR(32, collation='Latin1_General_CI_AS'))

当这样的列与Table关联时,此列的CREATE TABLE语句将产生:

login VARCHAR(32) COLLATE Latin1_General_CI_AS NULL

0.8版本中的新功能字符归类现在是基本字符串类型的一部分。

支持限制/偏移

MSSQL不支持LIMIT或OFFSET关键字。LIMIT直接通过TOP Transact SQL关键字支持:

select.limit

会产生:

SELECT TOP n

如果使用SQL Server 2005或更高版本,则可以通过ROW_NUMBER OVER结构使用支持OFFSET的LIMIT。对于2005以下的版本,使用OFFSET的LIMIT将失败。

事务隔离级别

All SQL Server dialects support setting of transaction isolation level both via a dialect-specific parameter create_engine.isolation_level accepted by create_engine(), as well as the Connection.execution_options.isolation_level argument as passed to Connection.execution_options(). This feature works by issuing the command SET TRANSACTION ISOLATION LEVEL <level> for each new connection.

使用create_engine()设置隔离级别:

engine = create_engine(
    "mssql+pyodbc://scott:tiger@ms_2008",
    isolation_level="REPEATABLE READ"
)

要设置使用每个连接执行选项:

connection = engine.connect()
connection = connection.execution_options(
    isolation_level="READ COMMITTED"
)

isolation_level的有效值包括:

  • READ COMMITTED
  • READ UNCOMMITTED
  • REPEATABLE READ
  • SERIALIZABLE
  • SNAPSHOT - specific to SQL Server

版本1.1中的新增功能:支持Microsoft SQL Server上的隔离级别设置。

为空¶ T0>

MSSQL支持三个列的可空性级别。默认的可空性允许空值,并且在CREATE TABLE结构中是显式的:

name VARCHAR(20) NULL

如果指定了nullable=None,则不作任何说明。换句话说,使用数据库的配置默认值。这将呈现:

name VARCHAR(20)

If nullable is True or False then the column will be NULL or NOT NULL respectively.

日期/时间处理

DATE和TIME是支持的。绑定参数按照大多数MSSQL驱动程序的要求转换为datetime.datetime()对象,并根据需要从字符串处理结果。DATE和TIME类型不适用于MSSQL 2005和以前 - 如果检测到2008以下的服务器版本,这些类型的DDL将作为DATETIME发布。

大文本/二进制类型不赞成

Per SQL Server 2012/2014 Documentation, the NTEXT, TEXT and IMAGE datatypes are to be removed from SQL Server in a future release. SQLAlchemy normally relates these types to the UnicodeText, Text and LargeBinary datatypes.

为了适应这种变化,一个新的标志deprecate_large_types被添加到方言中,如果没有用户设置,它将根据正在使用的服务器版本的检测自动设置。这个标志的行为如下:

  • 当这个标志是True时,UnicodeTextTextLargeBinary数据类型在渲染DDL时,分别是NVARCHAR(max)VARCHAR(max)VARBINARY(max)类型。这是添加此标志的新行为。

  • 当这个标志是False时,UnicodeTextTextLargeBinary数据类型在渲染DDL时,类型NTEXTTEXTIMAGE这是这些类型的长期行为。

  • 在数据库连接建立之前,标志以None值开始。如果方言用于在没有设置标志的情况下呈现DDL,则它被解释为与False相同。

  • 在第一次连接时,方言检测SQL Server版本2012或更高版本是否正在使用;如果标志仍然在None,则根据是否检测到2012或更高,将其设置为TrueFalse

  • 创建方言时,标志可以设置为TrueFalse,通常通过create_engine()

    eng = create_engine("mssql+pymssql://user:pass@host/db",
                    deprecate_large_types=True)
  • 在所有SQLAlchemy版本中,通过使用UPPERCASE类型对象来完全控制是否呈现“旧”或“新”类型:NVARCHARVARCHARtypes.VARBINARYTEXTmssql.NTEXTmssql.IMAGE将始终保持固定,并始终输出该类型。

版本1.0.0中的新功能

传统架构模式

非常旧版本的MSSQL方言引入了这样的行为:在SELECT语句中使用时,限定模式的表将被自动别名;给一张表:

account_table = Table(
    'account', metadata,
    Column('id', Integer, primary_key=True),
    Column('info', String(100)),
    schema="customer_schema"
)

这种传统的渲染模式会假定“customer_schema.account”不会被SQL语句的所有部分所接受,如下所示:

>>> eng = create_engine("mssql+pymssql://mydsn", legacy_schema_aliasing=True)
>>> print(account_table.select().compile(eng))
SELECT account_1.id, account_1.info
FROM customer_schema.account AS account_1

这种行为模式现在是默认关闭的,因为它似乎没有任何用处。但是在传统应用程序依赖于它的情况下,如上所述,可以使用create_engine()legacy_schema_aliasing参数。

Changed in version 1.1: the legacy_schema_aliasing flag introduced in version 1.0.5 to allow disabling of legacy mode for schemas now defaults to False.

聚簇索引支持

MSSQL方言通过mssql_clustered选项支持聚簇索引(和主键)。此选项可用于IndexUniqueConstraintPrimaryKeyConstraint

要生成聚簇索引:

Index("my_index", table.c.x, mssql_clustered=True)

它将索引呈现为CREATE CLUSTERED INDEX my_index ON table (x)

要生成一个集群主键使用:

Table('my_table', metadata,
      Column('x', ...),
      Column('y', ...),
      PrimaryKeyConstraint("x", "y", mssql_clustered=True))

例如,这将呈现该表格:

CREATE TABLE my_table (x INTEGER NOT NULL, y INTEGER NOT NULL,
                       PRIMARY KEY CLUSTERED (x, y))

同样,我们可以使用以下方法生成一个聚集的唯一约束

Table('my_table', metadata,
      Column('x', ...),
      Column('y', ...),
      PrimaryKeyConstraint("x"),
      UniqueConstraint("y", mssql_clustered=True),
      )

要显式请求非集群主键(例如,当需要单独的集群索引时),请使用:

Table('my_table', metadata,
      Column('x', ...),
      Column('y', ...),
      PrimaryKeyConstraint("x", "y", mssql_clustered=False))

例如,这将呈现该表格:

CREATE TABLE my_table (x INTEGER NOT NULL, y INTEGER NOT NULL,
                       PRIMARY KEY NONCLUSTERED (x, y))

在版本1.1中更改: mssql_clustered选项现在默认为None,而不是False。mssql_clustered=False现在显式呈现NONCLUSTERED子句,而None则完全忽略CLUSTERED子句,从而允许SQL Server默认设置生效。

MSSQL特定的索引选项

除集群之外,MSSQL方言还支持Index的其他特殊选项。

INCLUDE ¶ T0>

mssql_include选项为给定的字符串名称呈现INCLUDE(colname):

Index("my_index", table.c.x, mssql_include=['y'])

会将索引呈现为CREATE INDEX my_index ON (x) INCLUDE (y)

0.8版本中的新功能

索引排序

索引排序可通过函数表达式获得,例如:

Index("my_index", table.c.x.desc())

would render the index as CREATE INDEX my_index ON table (x DESC)

0.8版本中的新功能

也可以看看

Functional Indexes

兼容级别

MSSQL支持在数据库级别设置兼容级别的概念。例如,这允许在SQL2005数据库服务器上运行时运行与SQL2000兼容的数据库。server_version_info will always return the database server version information (in this case SQL2005) and not the compatibility level information. 因此,如果在向后兼容模式下运行,SQAlchemy可能会尝试使用无法由数据库服务器分析的T-SQL语句。

触发器¶ T0>

默认情况下,SQLAlchemy使用OUTPUT INSERTED通过IDENTITY列或其他服务器端默认值获取新生成的主键值。MS-SQL不允许在具有触发器的表上使用OUTPUT INSERTED。要禁止在每个表的基础上使用OUTPUT INSERTED,为每个具有触发器的Table指定implicit_returning=False

Table('mytable', metadata,
    Column('id', Integer, primary_key=True),
    # ...,
    implicit_returning=False
)

声明形式:

class MyClass(Base):
    # ...
    __table_args__ = {'implicit_returning':False}

此选项也可以在create_engine()上使用implicit_returning=False参数在引擎范围内指定。

Rowcount支持/ ORM版本控制

SQL Server驱动程序具有非常有限的能力来返回从UPDATE或DELETE语句更新的行数。特别是,pymssql驱动程序不支持,而pyodbc驱动程序只能在某些条件下返回此值。

特别是,当使用OUTPUT INSERTED时,更新的rowcount不可用。这会在使用服务器端版本控制方案时影响SQLAlchemy ORM的版本控制功能。当使用pyodbc时,对于任何使用version_id列和服务器端版本生成器的ORM映射类,需要将“implicit_returning”标志设置为false:

class MyTable(Base):
    __tablename__ = 'mytable'
    id = Column(Integer, primary_key=True)
    stuff = Column(String(10))
    timestamp = Column(TIMESTAMP(), default=text('DEFAULT'))
    __mapper_args__ = {
        'version_id_col': timestamp,
        'version_id_generator': False,
    }
    __table_args__ = {
        'implicit_returning': False
    }

Without the implicit_returning flag above, the UPDATE statement will use OUTPUT inserted.timestamp and the rowcount will be returned as -1, causing the versioning logic to fail.

启用快照隔离

不一定特定于SQLAlchemy,SQL Server具有一个默认的事务隔离模式,可以锁定整个表,甚至会导致轻度并发的应用程序长期持有的锁和频繁的死锁。对于现代级别的并发支持,建议为整个数据库启用快照隔离。这是通过在SQL提示符下执行的以下ALTER DATABASE命令完成的:

ALTER DATABASE MyDatabase SET ALLOW_SNAPSHOT_ISOLATION ON

ALTER DATABASE MyDatabase SET READ_COMMITTED_SNAPSHOT ON

有关SQL Server快照隔离的背景,请访问http://msdn.microsoft.com/en-us/library/ms175095.aspx

已知问题

  • 每个表不支持多个IDENTITY
  • 索引的反射不适用于比SQL Server 2005更早的版本

SQL Server数据类型

与所有的SQLAlchemy方言一样,所有已知可用于SQL Server的UPPERCASE类型都可以从顶级方言导入,无论它们来源于sqlalchemy.types还是来自当地方言:

from sqlalchemy.dialects.mssql import \
    BIGINT, BINARY, BIT, CHAR, DATE, DATETIME, DATETIME2, \
    DATETIMEOFFSET, DECIMAL, FLOAT, IMAGE, INTEGER, MONEY, \
    NCHAR, NTEXT, NUMERIC, NVARCHAR, REAL, SMALLDATETIME, \
    SMALLINT, SMALLMONEY, SQL_VARIANT, TEXT, TIME, \
    TIMESTAMP, TINYINT, UNIQUEIDENTIFIER, VARBINARY, VARCHAR

特定于SQL Server的类型或SQL Server特定的构造参数如下所示:

class sqlalchemy.dialects.mssql。 BIT

基础:sqlalchemy.types.TypeEngine

__初始化__ T0> ¶ T1>
inherited from the __init__ attribute of object

x .__ init __(...)初始化x;请参阅帮助(键入(x))进行签名

class sqlalchemy.dialects.mssql.CHAR(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False)

基础:sqlalchemy.types.String

SQL CHAR类型。

__init__(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False)
inherited from the __init__() method of String

创建一个字符串保存类型。

参数:
  • length – optional, a length for the column for use in DDL and CAST expressions. 如果没有CREATE TABLE将被发布,可以安全地省略。某些数据库可能需要用于DDL的length,并且在CREATE TABLE DDL时会引发异常如果包含没有长度的VARCHAR,则发布。值是否被解释为字节或字符是数据库特定的。
  • 整理 -

    可选,用于DDL和CAST表达式的列级别排序规则。呈现使用SQLite,MySQL和Postgresql支持的COLLATE关键字。例如。:

    >>> from sqlalchemy import cast, select, String
    >>> print select([cast('some string', String(collation='utf8'))])
    SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1

    0.8版新增:增加了对所有字符串类型的COLLATE支持。

  • convert_unicode -

    设置为True时,String类型将假定输入将作为Python unicode对象传递,结果以Python unicode对象。If the DBAPI in use does not support Python unicode (which is fewer and fewer these days), SQLAlchemy will encode/decode the value, using the value of the encoding parameter passed to create_engine() as the encoding.

    当使用本地支持Python unicode对象的DBAPI时,通常不需要设置此标志。For columns that are explicitly intended to store non-ASCII data, the Unicode or UnicodeText types should be used regardless, which feature the same behavior of convert_unicode but also indicate an underlying column type that directly supports unicode, such as NVARCHAR.

    For the extremely rare case that Python unicode is to be encoded/decoded by SQLAlchemy on a backend that does natively support Python unicode, the value force can be passed here which will cause SQLAlchemy’s encode/decode services to be used unconditionally.

  • unicode_error - 可选,用于处理Unicode转换错误的方法。行为就像标准库的string.decode()函数的errors关键字参数。此标志要求将convert_unicode设置为force - 否则,SQLAlchemy不能保证处理unicode转换的任务。请注意,此标志为已经返回unicode对象的后端(大多数DBAPI所做的)的行取回操作增加了显着的性能开销。这个标志只能作为从不同的或损坏的编码列读取字符串的最后手段。
class sqlalchemy.dialects.mssql。 DATETIME2 precision = None **千瓦 T5> ) T6> ¶ T7>

基础:sqlalchemy.dialects.mssql.base._DateTimeBasesqlalchemy.types.DateTime

class sqlalchemy.dialects.mssql。 DATETIMEOFFSET precision = None ** kwargs T5> ) T6> ¶ T7>

基础:sqlalchemy.types.TypeEngine

class sqlalchemy.dialects.mssql.IMAGE(length=None)

基础:sqlalchemy.types.LargeBinary

__初始化__ T0> ( T1> 长度=无 T2> ) T3> ¶ T4>
inherited from the __init__() method of LargeBinary

构建一个LargeBinary类型。

参数:length – optional, a length for the column for use in DDL statements, for those binary types that accept a length, such as the MySQL BLOB type.
class sqlalchemy.dialects.mssql。 MONEY

基础:sqlalchemy.types.TypeEngine

__初始化__ T0> ¶ T1>
inherited from the __init__ attribute of object

x .__ init __(...)初始化x;请参阅帮助(键入(x))进行签名

class sqlalchemy.dialects.mssql。 NCHAR length =无 ** kwargs T5> ) T6> ¶ T7>

基础:sqlalchemy.types.Unicode

SQL NCHAR类型。

__init__(length=None, **kwargs)
inherited from the __init__() method of Unicode

创建一个Unicode对象。

参数与String相同,除了convert_unicode默认为True

类 T0> sqlalchemy.dialects.mssql。 T1> NTEXT T2> ( T3> 长度=无 T4>, ** kwargs T5> ) T6> ¶ T7>

基础:sqlalchemy.types.UnicodeText

MSSQL NTEXT类型,可变长度的unicode文本最多2 ^ 30个字符。

__init__(length=None, **kwargs)
inherited from the __init__() method of UnicodeText

创建一个Unicode转换文本类型。

参数与Text的参数相同,但convert_unicode默认为True

class sqlalchemy.dialects.mssql。 NVARCHAR length = None ** kwargs T5> ) T6> ¶ T7>

基础:sqlalchemy.types.Unicode

SQL NVARCHAR类型。

__init__(length=None, **kwargs)
inherited from the __init__() method of Unicode

创建一个Unicode对象。

参数与String相同,除了convert_unicode默认为True

class sqlalchemy.dialects.mssql。REAL ** kw ) T5> ¶ T6>

基础:sqlalchemy.types.REAL

class sqlalchemy.dialects.mssql。 SMALLDATETIME timezone = False ) T5> ¶ T6>

基础:sqlalchemy.dialects.mssql.base._DateTimeBasesqlalchemy.types.DateTime

__初始化__ T0> ( T1> 时区=假 T2> ) T3> ¶ T4>

构建一个新的DateTime

参数: timezone - 布尔值。如果为True,并由后端支持,则会产生“TIMESTAMP WITH TIMEZONE”。对于不支持时区感知时间戳的后端,不起作用。
class sqlalchemy.dialects.mssql。 SMALLMONEY

基础:sqlalchemy.types.TypeEngine

__初始化__ T0> ¶ T1>
inherited from the __init__ attribute of object

x .__ init __(...)初始化x;请参阅帮助(键入(x))进行签名

class sqlalchemy.dialects.mssql。 SQL_VARIANT

基础:sqlalchemy.types.TypeEngine

__初始化__ T0> ¶ T1>
inherited from the __init__ attribute of object

x .__ init __(...)初始化x;请参阅帮助(键入(x))进行签名

class sqlalchemy.dialects.mssql.TEXT(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False)

基础:sqlalchemy.types.Text

SQL TEXT类型。

__init__(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False)
inherited from the __init__() method of String

创建一个字符串保存类型。

参数:
  • length – optional, a length for the column for use in DDL and CAST expressions. 如果没有CREATE TABLE将被发布,可以安全地省略。某些数据库可能需要用于DDL的length,并且在CREATE TABLE DDL时会引发异常如果包含没有长度的VARCHAR,则发布。值是否被解释为字节或字符是数据库特定的。
  • 整理 -

    可选,用于DDL和CAST表达式的列级别排序规则。呈现使用SQLite,MySQL和Postgresql支持的COLLATE关键字。例如。:

    >>> from sqlalchemy import cast, select, String
    >>> print select([cast('some string', String(collation='utf8'))])
    SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1

    0.8版新增:增加了对所有字符串类型的COLLATE支持。

  • convert_unicode -

    设置为True时,String类型将假定输入将作为Python unicode对象传递,结果以Python unicode对象。If the DBAPI in use does not support Python unicode (which is fewer and fewer these days), SQLAlchemy will encode/decode the value, using the value of the encoding parameter passed to create_engine() as the encoding.

    当使用本地支持Python unicode对象的DBAPI时,通常不需要设置此标志。For columns that are explicitly intended to store non-ASCII data, the Unicode or UnicodeText types should be used regardless, which feature the same behavior of convert_unicode but also indicate an underlying column type that directly supports unicode, such as NVARCHAR.

    For the extremely rare case that Python unicode is to be encoded/decoded by SQLAlchemy on a backend that does natively support Python unicode, the value force can be passed here which will cause SQLAlchemy’s encode/decode services to be used unconditionally.

  • unicode_error - 可选,用于处理Unicode转换错误的方法。行为就像标准库的string.decode()函数的errors关键字参数。此标志要求将convert_unicode设置为force - 否则,SQLAlchemy不能保证处理unicode转换的任务。请注意,此标志为已经返回unicode对象的后端(大多数DBAPI所做的)的行取回操作增加了显着的性能开销。这个标志只能作为从不同的或损坏的编码列读取字符串的最后手段。
class sqlalchemy.dialects.mssql。 TIME precision = None ** kwargs T5> ) T6> ¶ T7>

基础:sqlalchemy.types.TIME

class sqlalchemy.dialects.mssql。 TINYINT

基础:sqlalchemy.types.Integer

__初始化__ T0> ¶ T1>
inherited from the __init__ attribute of object

x .__ init __(...)初始化x;请参阅帮助(键入(x))进行签名

class sqlalchemy.dialects.mssql。 UNIQUEIDENTIFIER

基础:sqlalchemy.types.TypeEngine

__初始化__ T0> ¶ T1>
inherited from the __init__ attribute of object

x .__ init __(...)初始化x;请参阅帮助(键入(x))进行签名

class sqlalchemy.dialects.mssql.VARCHAR(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False)

基础:sqlalchemy.types.String

SQL VARCHAR类型。

__init__(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False)
inherited from the __init__() method of String

创建一个字符串保存类型。

参数:
  • length – optional, a length for the column for use in DDL and CAST expressions. 如果没有CREATE TABLE将被发布,可以安全地省略。某些数据库可能需要用于DDL的length,并且在CREATE TABLE DDL时会引发异常如果包含没有长度的VARCHAR,则发布。值是否被解释为字节或字符是数据库特定的。
  • 整理 -

    可选,用于DDL和CAST表达式的列级别排序规则。呈现使用SQLite,MySQL和Postgresql支持的COLLATE关键字。例如。:

    >>> from sqlalchemy import cast, select, String
    >>> print select([cast('some string', String(collation='utf8'))])
    SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1

    0.8版新增:增加了对所有字符串类型的COLLATE支持。

  • convert_unicode -

    设置为True时,String类型将假定输入将作为Python unicode对象传递,结果以Python unicode对象。If the DBAPI in use does not support Python unicode (which is fewer and fewer these days), SQLAlchemy will encode/decode the value, using the value of the encoding parameter passed to create_engine() as the encoding.

    当使用本地支持Python unicode对象的DBAPI时,通常不需要设置此标志。For columns that are explicitly intended to store non-ASCII data, the Unicode or UnicodeText types should be used regardless, which feature the same behavior of convert_unicode but also indicate an underlying column type that directly supports unicode, such as NVARCHAR.

    For the extremely rare case that Python unicode is to be encoded/decoded by SQLAlchemy on a backend that does natively support Python unicode, the value force can be passed here which will cause SQLAlchemy’s encode/decode services to be used unconditionally.

  • unicode_error - 可选,用于处理Unicode转换错误的方法。行为就像标准库的string.decode()函数的errors关键字参数。此标志要求将convert_unicode设置为force - 否则,SQLAlchemy不能保证处理unicode转换的任务。请注意,此标志为已经返回unicode对象的后端(大多数DBAPI所做的)的行取回操作增加了显着的性能开销。这个标志只能作为从不同的或损坏的编码列读取字符串的最后手段。

PyODBC ¶ T0>

通过PyODBC驱动程序支持Microsoft SQL Server数据库。

DBAPI ¶ T0>

PyODBC的文档和下载信息(如果适用)可在以下网址获得:http://pypi.python.org/pypi/pyodbc/

连接¶ T0>

连接字符串:

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

连接到PyODBC

这里的URL将被转换成PyODBC连接字符串,详见ConnectionStrings

DSN连接

A DSN-based connection is preferred overall when using ODBC. 基本的基于DSN的连接如下所示:

engine = create_engine("mssql+pyodbc://scott:tiger@some_dsn")

上面哪个,将下面的连接字符串传给PyODBC:

dsn=mydsn;UID=user;PWD=pass

如果省略用户名和密码,则DSN表单还会将Trusted_Connection=yes指令添加到ODBC字符串中。

主机名连接

Hostname-based connections are not preferred, however are supported. ODBC驱动程序名称必须显式指定:

engine = create_engine("mssql+pyodbc://scott:tiger@myhost:port/databasename?driver=SQL+Server+Native+Client+10.0")

版本1.0.0更改:现在,基于主机名的PyODBC连接需要明确指定的SQL Server驱动程序名称。SQLAlchemy不能在这里选择一个最佳的默认值,因为它根据平台和安装的驱动程序而变化。

Other keywords interpreted by the Pyodbc dialect to be passed to pyodbc.connect() in both the DSN and hostname cases include: odbc_autotranslate, ansi, unicode_results, autocommit.

通过精确的Pyodbc字符串

PyODBC连接字符串也可以按照ConnectionStrings的指定,使用参数odbc_connect发送到驱动程序中。但是,使用urllib.quote_plus时,定界符必须是URL转义的:

import urllib
params = urllib.quote_plus("DRIVER={SQL Server Native Client 10.0};SERVER=dagger;DATABASE=test;UID=user;PWD=password")

engine = create_engine("mssql+pyodbc:///?odbc_connect=%s" % params)

Unicode绑定

unicode在FreeTDS和/或EasySoft的unix后台上的PyODBC现状很差;不同的操作系统平台和版本的UnixODBC与IODBC与FreeTDS / EasySoft相比,PyODBC本身会显着改变字符串的接收方式。PyODBC方言尝试使用它所知道的所有信息来确定Python unicode文字是否可以直接传递给PyODBC驱动程序;虽然SQLAlchemy可以首先将这些字符串编码为字节串,但是有些用户报告说PyODBC对某些编码的字节串错误处理,并且需要一个Python unicode对象,而作者已经观察到python unicode被PyODBC完全误解的普遍情况,特别是在处理在表反射中使用的信息模式表,并且该值必须首先被编码为一个字节串。

正因为如此,可以使用supports_unicode_binds参数控制create_engine()是否将绑定参数的unicode文字发送到PyODBC。在默认的None时,PyODBC方言将使用最好的猜测来判断驱动程序是否处理Unicode字面值。False时,unicode文字将首先被编码,而True unicode文字将被直接传递。当unix + PyODBC的unicode情况稳定时,这是一个临时的标志,希望不需要。

New in version 0.7.7: supports_unicode_binds parameter to create_engine().

行数支持

Pyodbc只支持rowcount。使用ORM版本控制时,请参阅Rowcount Support / ORM Versioning中的注意事项以了解重要注意事项。

mxODBC ¶ T0>

通过mxODBC驱动程序支持Microsoft SQL Server数据库。

DBAPI ¶ T0>

有关mxODBC的文档和下载信息(如果适用),请访问:http://www.egenix.com/

连接¶ T0>

连接字符串:

mssql+mxodbc://<username>:<password>@<dsnname>

执行模式

mxODBC采用两种类型的语句执行方式,使用cursor.execute()cursor.executedirect()方法(第二种是DBAPI规范的扩展)。前者使用特定于SQL Server Native Client ODBC驱动程序的特定API调用(已知SQLDescribeParam),而后者则不使用。

当使用SQLDescribeParam时,mxODBC显然只会重复使用一个预准备语句。准备语句重用的好处是性能。缺点是SQLDescribeParam有一组有限的绑定参数被理解的场景,包括它们不能放在函数调用的参数列表中,在FROM之外的任何地方,或者甚至在FROM子句内的子查询中 - 使得在SELECT语句中绑定参数是不可能的,除了最简单的语句之外。

出于这个原因,mxODBC方言默认只使用INSERT,UPDATE和DELETE语句的“本机”模式,对所有其他语句使用转义字符串模式。

This behavior can be controlled via execution_options() using the native_odbc_execute flag with a value of True or False, where a value of True will unconditionally use native bind parameters and a value of False will unconditionally use string-escaped parameters.

pymssql ¶ T0>

通过pymssql驱动程序支持Microsoft SQL Server数据库。

DBAPI ¶ T0>

pymssql的文档和下载信息(如果适用)可在以下网址获得:http://pymssql.org/

连接¶ T0>

连接字符串:

mssql+pymssql://<username>:<password>@<freetds_name>/?charset=utf8

pymssql是一个Python模块,它提供了围绕FreeTDS的Python DBAPI接口。兼容版本适用于Linux,MacOSX和Windows平台。

zxjdbc ¶ T0>

通过zxJDBC为Jython驱动程序支持Microsoft SQL Server数据库。

注意

当前版本的SQLAlchemy不支持Jython。zxjdbc方言应该被认为是实验性的。

DBAPI ¶ T0>

这个数据库的驱动程序可以在http://jtds.sourceforge.net/上找到

连接¶ T0>

连接字符串:

mssql+zxjdbc://user:pass@host:port/dbname[?key=value&key=value...]

AdoDBAPI ¶ T0>

通过adodbapi驱动程序支持Microsoft SQL Server数据库。

DBAPI ¶ T0>

adodbapi的文档和下载信息(如果适用)可在以下网址找到:http://adodbapi.sourceforge.net/

连接¶ T0>

连接字符串:

mssql+adodbapi://<username>:<password>@<dsnname>

注意

adodbapi方言目前还没有实现SQLAlchemy版本0.6及以上版本。