支持SQLite数据库。

DBAPI支持¶

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

• pysqlite T0>
• pysqlcipher T0>

日期和时间类型¶

SQLite没有内置的DATE，TIME或DATETIME类型，并且pysqlite不提供用于在Python datetime对象和SQLite支持的格式之间转换值的开箱即用功能。SQLAlchemy自己的DateTime和相关类型在使用SQlite时提供日期格式和分析功能。实现类是DATETIME，DATE和TIME。这些类型将日期和时间表示为ISO格式的字符串，这也很好地支持排序。这些函数不依赖于典型的“libc”内部函数，因此完全支持历史日期。

SQLite自动递增行为¶

SQLite自动增量的背景是：http://sqlite.org/autoinc.html

关键概念：

• SQLite有一个隐含的“自动增量”功能，对于任何使用“INTEGER PRIMARY KEY”专门为+主键创建的非复合主键列进行。
• SQLite也有一个明确的“AUTOINCREMENT”关键字，即not等价于隐式自动增量特性；此关键字不推荐用于一般用途。除非使用特殊的SQLite特定指令，否则SQLAlchemy不会呈现此关键字（请参见下文）。但是，它仍然要求列的类型被命名为“INTEGER”。

Table('sometable', metadata,
        Column('id', Integer, primary_key=True),
        sqlite_autoincrement=True)

table = Table(
    "my_table", metadata,
    Column("id", BigInteger().with_variant(Integer, "sqlite"), primary_key=True)
)

from sqlalchemy import BigInteger
from sqlalchemy.ext.compiler import compiles

class SLBigInteger(BigInteger):
    pass

@compiles(SLBigInteger, 'sqlite')
def bi_c(element, compiler, **kw):
    return "INTEGER"

@compiles(SLBigInteger)
def bi_c(element, compiler, **kw):
    return compiler.visit_BIGINT(element, **kw)


table = Table(
    "my_table", metadata,
    Column("id", SLBigInteger(), primary_key=True)
)

数据库锁定行为/并发¶

SQLite不是专为高级别的写入并发而设计的。作为文件的数据库本身在事务内的写操作期间被完全锁定，这意味着在此期间恰好有一个“连接”（实际上是文件句柄）对数据库有独占访问权限 - 在此期间所有其他“连接”将被阻止时间。

Python DBAPI规范还要求一个始终在事务中的连接模型；没有connection.begin()方法，只有connection.commit()和connection.rollback()立即开始。这似乎意味着SQLite驱动程序理论上在任何时候都只允许在一个特定的数据库文件上使用一个文件句柄；然而，SQlite本身以及pysqlite驱动程序中都有几个因素，这些因素显着地放宽了这一限制。

然而，无论使用什么锁定模式，一旦事务启动并且DML（例如INSERT，UPDATE，DELETE）至少被发射出去，SQLite仍然会始终锁定数据库文件，并且这至少会在该点处阻止其他事务他们也试图发射DML。默认情况下，该块的时间长度非常短，并且在发生错误时超时。

与SQLAlchemy ORM一起使用时，此行为变得更加重要。默认情况下，SQLAlchemy的Session对象在事务中运行，并且使用其自动刷新模型，可以在任何SELECT语句之前发出DML。这可能会导致SQLite数据库的锁定速度超出预期。SQLite的锁定模式和pysqlite驱动程序可以在一定程度上被操纵，但是应该注意的是，使用SQLite实现高度的写入并发是一场失败的战斗。

有关SQLite缺乏设计写入并发性的更多信息，请参阅另一个RDBMS可能更好地工作的情况 - 高并发性接近页面底部。

以下小节介绍了受SQLite的基于文件的体系结构影响的区域，并且通常还需要解决方法才能在使用pysqlite驱动程序时工作。

事务隔离级别¶

SQLite支持以非标准方式沿两个轴进行“事务隔离”。One is that of the PRAGMA read_uncommitted instruction. This setting can essentially switch SQLite between its default mode of SERIALIZABLE isolation, and a “dirty read” isolation mode normally referred to as READ UNCOMMITTED.

SQLAlchemy使用create_engine()的create_engine.isolation_level参数连接到此PRAGMA语句中。与SQLite一起使用时，此参数的有效值分别为"SERIALIZABLE"和“READ UNCOMMITTED”分别为0和1。SQLite默认为SERIALIZABLE，但其行为受到pysqlite驱动程序默认行为的影响。

SQLite的事务锁定所受影响的另一个轴是通过使用的BEGIN语句的性质。如BEGIN TRANSACTION所述，这三个品种是“延期”，“即时”和“排他”。A straight BEGIN statement uses the “deferred” mode, where the the database file is not locked until the first read or write operation, and read access remains open to other transactions until the first write operation. 但同样重要的是要注意，在第一次写操作之前，pysqlite驱动程序会通过干扰此行为，甚至不会发出BEGIN。

SAVEPOINT支持¶

SQLite支持SAVEPOINT，它只在事务开始时才起作用。SQLAlchemy的SAVEPOINT支持可以在核心级别使用Connection.begin_nested()方法，在ORM级别使用Session.begin_nested()。但是，除非采取了解决方法，否则SAVEPOINTs根本无法使用pysqlite。

事务性DDL ¶

SQLite数据库也支持事务性DDL。在这种情况下，pysqlite驱动程序不仅无法启动事务，还会在检测到DDL时结束任何现有的转换，因此再次需要解决方法。

外键支持¶

SQLite在为表发出CREATE语句时支持FOREIGN KEY语法，但默认情况下，这些约束对表的操作没有影响。

SQLite上的约束检查有三个先决条件：

• 至少必须使用SQLite版本3.6.19
• SQLite库必须在没有启用SQLITE_OMIT_FOREIGN_KEY或SQLITE_OMIT_TRIGGER符号的情况下编译。
• 在使用前必须在所有连接上发送PRAGMA foreign_keys = ON

SQLAlchemy允许通过使用事件自动为新连接发布PRAGMA语句：

from sqlalchemy.engine import Engine
from sqlalchemy import event

@event.listens_for(Engine, "connect")
def set_sqlite_pragma(dbapi_connection, connection_record):
    cursor = dbapi_connection.cursor()
    cursor.execute("PRAGMA foreign_keys=ON")
    cursor.close()

类型反射¶

SQLite类型与大多数其他数据库后端的类型不同，因为类型的字符串名称通常不以一对一的方式与“类型”相对应。相反，SQLite根据类型的字符串匹配模式将每列的输入行为链接到五个所谓的“类型亲和性”之一。

SQLAlchemy的反射过程在检查类型时使用简单的查找表来链接返回给提供的SQLAlchemy类型的关键字。这个查询表在SQLite方言中，与所有其他方言一样。但是，当特定类型名称不在查找映射中时，SQLite方言具有不同的“后退”例程；它实现了位于http://www.sqlite.org/datatype3.html 2.1节的SQLite“type affinity”方案。

所提供的typemap将直接关联以下类型的完全字符串名称匹配：

BIGINT, BLOB, BOOLEAN, BOOLEAN, CHAR, DATE, DATETIME, FLOAT, DECIMAL, FLOAT, INTEGER, INTEGER, NUMERIC, REAL, SMALLINT, TEXT, TIME, TIMESTAMP, VARCHAR, NVARCHAR, NCHAR

当类型名称与以上类型之一不匹配时，将使用“类型关联”查找：

• 如果类型名称包含字符串INT，则返回INTEGER
• TEXT is returned if the type name includes the string CHAR, CLOB or TEXT
• NullType is returned if the type name includes the string BLOB
• 如果类型名称包含字符串REAL，FLOA或DOUB，则返回REAL。
• 否则，使用NUMERIC类型。

部分索引¶

部分索引，例如其中一个使用WHERE子句，可以使用参数sqlite_where在DDL系统中指定：

tbl = Table('testtbl', m, Column('data', Integer))
idx = Index('test_idx1', tbl.c.data,
            sqlite_where=and_(tbl.c.data > 5, tbl.c.data < 10))

索引将在创建时呈现为：

CREATE INDEX test_idx1 ON testtbl (data)
WHERE data > 5 AND data < 10

虚线列名称¶

使用明确具有句点的表名或列名是不推荐。虽然这对于关系数据库来说通常是一个坏主意，但由于点是一个语法上重要的特征，SQLite驱动程序直到版本3.10.0 SQLite有一个错误，它要求SQLAlchemy过滤掉这些结果集中的点。

这个错误完全在SQLAlchemy之外，可以这样说明：

import sqlite3

assert sqlite3.sqlite_version_info < (3, 10, 0), "bug is fixed in this version"

conn = sqlite3.connect(":memory:")
cursor = conn.cursor()

cursor.execute("create table x (a integer, b integer)")
cursor.execute("insert into x (a, b) values (1, 1)")
cursor.execute("insert into x (a, b) values (2, 2)")

cursor.execute("select x.a, x.b from x")
assert [c[0] for c in cursor.description] == ['a', 'b']

cursor.execute('''
    select x.a, x.b from x where a=1
    union
    select x.a, x.b from x where a=2
''')
assert [c[0] for c in cursor.description] == ['a', 'b'], \
    [c[0] for c in cursor.description]

第二个断言失败：

Traceback (most recent call last):
  File "test.py", line 19, in <module>
    [c[0] for c in cursor.description]
AssertionError: ['x.a', 'x.b']

在上面的情况中，驱动程序错误地报告了列的名称，包括表的名称，这与UNION不存在时完全不一致。

SQLAlchemy依赖于列名与原始语句匹配的可预测性，因此SQLAlchemy方言别无选择，只能将其过滤掉：

from sqlalchemy import create_engine

eng = create_engine("sqlite://")
conn = eng.connect()

conn.execute("create table x (a integer, b integer)")
conn.execute("insert into x (a, b) values (1, 1)")
conn.execute("insert into x (a, b) values (2, 2)")

result = conn.execute("select x.a, x.b from x")
assert result.keys() == ["a", "b"]

result = conn.execute('''
    select x.a, x.b from x where a=1
    union
    select x.a, x.b from x where a=2
''')
assert result.keys() == ["a", "b"]

注意上面，即使SQLAlchemy过滤掉了这些点，这两个名字仍然是可寻址的：

>>> row = result.first()
>>> row["a"]
1
>>> row["x.a"]
1
>>> row["b"]
1
>>> row["x.b"]
1

Therefore, the workaround applied by SQLAlchemy only impacts ResultProxy.keys() and RowProxy.keys() in the public API. In the very specific case where an application is forced to use column names that contain dots, and the functionality of ResultProxy.keys() and RowProxy.keys() is required to return these dotted names unmodified, the sqlite_raw_colnames execution option may be provided, either on a per-Connection basis:

result = conn.execution_options(sqlite_raw_colnames=True).execute('''
    select x.a, x.b from x where a=1
    union
    select x.a, x.b from x where a=2
''')
assert result.keys() == ["x.a", "x.b"]

或基于每个Engine：

engine = create_engine("sqlite://", execution_options={"sqlite_raw_colnames": True})

在使用per- Engine执行选项时，请注意使用UNION的核心和ORM查询可能无法正常工作。

SQLite数据类型¶

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

from sqlalchemy.dialects.sqlite import \
            BLOB, BOOLEAN, CHAR, DATE, DATETIME, DECIMAL, FLOAT, \
            INTEGER, NUMERIC, SMALLINT, TEXT, TIME, TIMESTAMP, \
            VARCHAR

class sqlalchemy.dialects.sqlite.DATETIME(*args, **kwargs)¶

基础：sqlalchemy.dialects.sqlite.base._DateTimeMixin，sqlalchemy.types.DateTime

使用字符串在SQLite中表示Python日期时间对象。

默认的字符串存储格式是：

"%(year)04d-%(month)02d-%(day)02d %(hour)02d:%(min)02d:%(second)02d.%(microsecond)06d"

例如。：

2011-03-15 12:05:57.10558

存储格式可以使用storage_format和regexp参数进行一定程度的自定义，例如：

import re
from sqlalchemy.dialects.sqlite import DATETIME

dt = DATETIME(
    storage_format="%(year)04d/%(month)02d/%(day)02d %(hour)02d:%(min)02d:%(second)02d",
    regexp=r"(\d+)/(\d+)/(\d+) (\d+)-(\d+)-(\d+)"
)

参数：	storage_format¶ – format string which will be applied to the dict with keys year, month, day, hour, minute, second, and microsecond. regexp¶ – regular expression which will be applied to incoming result rows. 如果正则表达式包含命名组，则所得匹配字典作为关键字参数应用于Python datetime()构造函数。否则，如果使用位置组，则使用位置参数通过* map（int， match_obj.groups（0））调用datetime T0>。

class sqlalchemy.dialects.sqlite。 DATE （ storage_format =无， regexp = None，** kw ） ¶

基础：sqlalchemy.dialects.sqlite.base._DateTimeMixin，sqlalchemy.types.Date

使用字符串在SQLite中表示Python日期对象。

默认的字符串存储格式是：

"%(year)04d-%(month)02d-%(day)02d"

例如。：

2011-03-15

存储格式可以使用storage_format和regexp参数进行一定程度的自定义，例如：

import re
from sqlalchemy.dialects.sqlite import DATE

d = DATE(
        storage_format="%(month)02d/%(day)02d/%(year)04d",
        regexp=re.compile("(?P<month>\d+)/(?P<day>\d+)/(?P<year>\d+)")
    )

参数：	storage_format¶ – format string which will be applied to the dict with keys year, month, and day. regexp¶ – regular expression which will be applied to incoming result rows. 如果正则表达式包含命名组，则所得到的匹配字典作为关键字参数应用于Python date()构造函数。否则，如果使用位置组，则使用位置参数通过* map（int， match_obj.groups（0））调用date T0>。

class sqlalchemy.dialects.sqlite.TIME(*args, **kwargs)¶

基础：sqlalchemy.dialects.sqlite.base._DateTimeMixin，sqlalchemy.types.Time

使用字符串在SQLite中表示一个Python时间对象。

默认的字符串存储格式是：

"%(hour)02d:%(minute)02d:%(second)02d.%(microsecond)06d"

例如。：

12:05:57.10558

存储格式可以使用storage_format和regexp参数进行一定程度的自定义，例如：

import re
from sqlalchemy.dialects.sqlite import TIME

t = TIME(
    storage_format="%(hour)02d-%(minute)02d-%(second)02d-%(microsecond)06d",
    regexp=re.compile("(\d+)-(\d+)-(\d+)-(?:-(\d+))?")
)

参数：	T0> storage_format T1> ¶ T2> - 将被施加到字典连键时，分，秒和微秒格式字符串。 regexp¶ – regular expression which will be applied to incoming result rows. 如果正则表达式包含命名组，则所得匹配字典作为关键字参数应用于Python time()构造函数。否则，如果使用位置组，time()构造函数将通过位置参数通过* map（int， match_obj.groups（0）） T0>。

Pysqlite ¶ T0>

通过pysqlite驱动程序支持SQLite数据库。

请注意，pysqlite与Python发行版中包含的sqlite3模块是相同的驱动程序。

sqlite+pysqlite:///file_path

from sqlite3 import dbapi2 as sqlite
e = create_engine('sqlite+pysqlite:///file.db', module=sqlite)

driver://user:pass@host/database

# relative path
e = create_engine('sqlite:///path/to/database.db')

# absolute path
e = create_engine('sqlite:////path/to/database.db')

# absolute path on Windows
e = create_engine('sqlite:///C:\\path\\to\\database.db')

# in-memory database
e = create_engine('sqlite://')

engine = create_engine('sqlite://',
    connect_args={'detect_types':
        sqlite3.PARSE_DECLTYPES|sqlite3.PARSE_COLNAMES},
    native_datetime=True
)

from sqlalchemy.pool import StaticPool
engine = create_engine('sqlite://',
                    connect_args={'check_same_thread':False},
                    poolclass=StaticPool)

# maintain the same connection per thread
from sqlalchemy.pool import SingletonThreadPool
engine = create_engine('sqlite:///mydb.db',
                    poolclass=SingletonThreadPool)


# maintain the same connection across all threads
from sqlalchemy.pool import StaticPool
engine = create_engine('sqlite:///mydb.db',
                    poolclass=StaticPool)

from sqlalchemy import create_engine, event

engine = create_engine("sqlite:///myfile.db")

@event.listens_for(engine, "connect")
def do_connect(dbapi_connection, connection_record):
    # disable pysqlite's emitting of the BEGIN statement entirely.
    # also stops it from emitting COMMIT before any DDL.
    dbapi_connection.isolation_level = None

@event.listens_for(engine, "begin")
def do_begin(conn):
    # emit our own BEGIN
    conn.execute("BEGIN")

@event.listens_for(engine, "begin")
def do_begin(conn):
    conn.execute("BEGIN EXCLUSIVE")

Pysqlcipher ¶ T0>

通过pysqlcipher驱动程序支持SQLite数据库。

pysqlcipher是使用SQLCipher后端的标准pysqlite驱动程序的一个分支。

sqlite+pysqlcipher://:passphrase/file_path[?kdf_iter=<iter>]

e = create_engine('sqlite+pysqlcipher://:testing@/foo.db')

e = create_engine('sqlite+pysqlcipher://:testing@//path/to/foo.db')

e = create_engine('sqlite+pysqlcipher://:testing@/foo.db?cipher=aes-256-cfb&kdf_iter=64000')