【Python百日进阶-Web开发-Peewee】Day263 - Peewee API文档 - 数据库（上）

十一、API 文档

本文档指定了 Peewee 的 API。
http://docs.peewee-orm.com/en/latest/peewee/api.html#database

11.1 数据库

11.1.1 Database 通用

class Database(database[, thread_safe=True[, autorollback=False[, field_types=None[, operations=None[, autoconnect=True[, **kwargs]]]]]])

参数：
database ( str ) – SQLite 的数据库名称或文件名（或None延迟 初始化，在这种情况下，您必须调用Database.init()，指定数据库名称）。
thread_safe ( bool ) – 是否将连接状态存储在线程本地。
autorollback ( bool ) – 自动回滚不在显式事务中失败的查询 。
field_types ( dict ) – 要支持的其他字段类型的映射。
操作( dict ) – 要支持的附加操作的映射。
autoconnect ( bool ) – 如果尝试在关闭的数据库上执行查询，则自动连接到数据库。
kwargs – 创建连接时将传递给数据库驱动程序的任意关键字参数，例如password, host等。
Database负责：

• 执行查询 Executing queries
• 管理连接 Managing connections
• 事务 Transactions
• 内省 Introspection

笔记

None如果在运行时才知道数据库，则可以将数据库实例化为数据库名称。通过这种方式，您可以创建一个数据库实例，然后在已知设置时在其他地方对其进行配置。这称为延迟*初始化。

例子：

# Sqlite database using WAL-mode and 32MB page-cache.
db = SqliteDatabase('app.db', pragmas={
    'journal_mode': 'wal',
    'cache_size': -32 * 1000})

# Postgresql database on remote host.
db = PostgresqlDatabase('my_app', user='postgres', host='10.1.0.3',
                        password='secret')

延迟初始化示例：

db = PostgresqlDatabase(None)

class BaseModel(Model):
    class Meta:
        database = db

# Read database connection info from env, for example:
db_name = os.environ['DATABASE']
db_host = os.environ['PGHOST']

# Initialize database.
db.init(db_name, host=db_host, user='postgres')

param = ‘?’

在 SQL 查询中用作参数占位符的字符串。

quote = ‘"’

用于表示表或列等实体的引号类型。

init（database[, **kwargs])

参数：
database ( str ) – SQLite 的数据库名称或文件名。
kwargs – 创建连接时将传递给数据库驱动程序的任意关键字参数，例如 password,host等。
初始化延迟数据库。有关详细信息，请参阅运行时数据库配置 。

enter()

该Database实例可以用作上下文管理器，在这种情况下，连接将在包装块的持续时间内保持打开状态。

此外，在包装块中执行的任何 SQL 都将在事务中执行。

connection_context()
创建一个上下文管理器，它将在包装块的持续时间内保持打开连接。

例子：

def on_app_startup():
    # When app starts up, create the database tables, being sure
    # the connection is closed upon completion.
    with database.connection_context():
        database.create_tables(APP_MODELS)

connect([reuse_if_open=False])

参数： 重用_if_open( bool ) – 如果连接已打开，则不要引发异常。
回报： 是否打开了新连接。
返回类型： 布尔
提高： OperationalError如果连接已打开 reuse_if_open且未设置为True.
打开与数据库的连接。

close()

回报： 连接是否关闭。如果数据库已经关闭，则返回False.
返回类型： 布尔
关闭与数据库的连接。

is_closed()

回报： True如果数据库关闭，则返回，False如果打开。
返回类型： 布尔

connection()

返回打开的连接。如果连接未打开，则会打开一个连接。该连接将是底层数据库驱动程序用于封装数据库连接的任何内容。

cursor([commit=None])

参数： 犯罪– 供内部使用。
返回cursor当前连接上的对象。如果连接未打开，则会打开一个连接。游标将是底层数据库驱动程序用于封装数据库游标的任何内容。

execute_sql( sql, params=None[, commit=SENTINEL]])

参数：
sql ( str ) – 要执行的 SQL 字符串。
params ( tuple ) – 查询参数。
commit – 用于覆盖默认提交逻辑的布尔标志。
回报：
光标对象。

执行 SQL 查询并在结果上返回游标。

execute(query[, commit=SENTINEL[, **context_options]])

参数：
查询——一个Query实例。
commit – 用于覆盖默认提交逻辑的布尔标志。
context_options – 传递给 SQL 生成器的任意选项。
回报：
光标对象。

通过编译Query实例并执行生成的 SQL 来执行 SQL 查询。

last_insert_id(cursor[, query_type=None])

参数： 光标– 光标对象。
回报： 最后插入的行的主键。

rows_affected(cursor)

参数： 光标– 光标对象。
回报： 查询修改的行数。

in_transaction()

回报： 交易当前是否打开。
返回类型： 布尔

atomic()

创建一个上下文管理器，它在事务中的包装块中运行任何查询（如果块是嵌套的，则为保存点）。

调用atomic()可以嵌套。

atomic()也可以用作装饰器。

示例代码：

with db.atomic() as txn:
    perform_operation()

    with db.atomic() as nested_txn:
        perform_another_operation()

事务和保存点可以在包装块内显式提交或回滚。如果发生这种情况，则在提交/回滚之后开始一个新的事务或保存点。

例子：

with db.atomic() as txn:
    User.create(username='mickey')
    txn.commit()  # Changes are saved and a new transaction begins.

    User.create(username='huey')
    txn.rollback()  # "huey" will not be saved.

    User.create(username='zaizee')

# Print the usernames of all users.
print([u.username for u in User.select()])

# Prints ["mickey", "zaizee"]

manual_commit()

创建一个上下文管理器，它在包装块的持续时间内禁用所有事务管理。

例子：

with db.manual_commit():
    db.begin()  # Begin transaction explicitly.
    try:
        user.delete_instance(recursive=True)
    except:
        db.rollback()  # Rollback -- an error occurred.
        raise
    else:
        try:
            db.commit()  # Attempt to commit changes.
        except:
            db.rollback()  # Error committing, rollback.
            raise

上面的代码等价于以下代码：

with db.atomic():
    user.delete_instance(recursive=True)

session_start()

开始一个新事务（不使用上下文管理器或装饰器）。如果您打算在事务中执行一系列操作，则此方法很有用，但不适合使用装饰器或上下文管理器。

笔记
强烈建议您Database.atomic() 尽可能使用该方法来管理事务/保存点。该
atomic方法正确地管理嵌套，使用适当的构造（例如，transaction-vs-savepoint），并且总是在自己之后进行清理。
session_start()仅当操作序列不容易使用上下文管理器或装饰器进行包装时，才应使用该方法。

警告
您必须始终调用其中一个session_commit() 或session_rollback()调用该 session_start方法之后。

session_commit()

提交在以 开头的事务期间所做的任何更改 session_start()。

session_rollback()

回滚在以 开头的事务期间所做的任何更改 session_start()。

transaction()

创建一个上下文管理器，在事务中运行包装块中的所有查询。

警告
调用transaction不能嵌套。只有最顶层的调用才会生效。回滚或提交嵌套事务上下文管理器具有未定义的行为。

savepoint()

创建一个上下文管理器，在保存点中运行包装块中的所有查询。保存点可以任意嵌套。

警告
调用savepoint必须发生在事务内部。

begin()

使用手动提交模式时开始事务。

笔记
此方法只能与 manual_commit()上下文管理器一起使用。

commit()

手动提交当前活动的事务。

笔记
此方法只能与 manual_commit()上下文管理器一起使用。

rollback()

手动回滚当前活动的事务。

笔记
此方法只能与 manual_commit()上下文管理器一起使用。

batch_commit(it, n)

参数：
it ( iterable ) – 将产生其项目的可迭代对象。
n ( int ) – 每n项提交一次。
回报：
与所提供的等效的可迭代对象，此外，将在事务中产生n项的组。

此方法的目的是简化批处理大型操作，例如插入、更新等。您传入一个可迭代对象和每批项目的数量，这些项目将由一个等效的迭代器返回，该迭代器将每个批次包装在一笔交易。

例子：

# Some list or iterable containing data to insert.
row_data = [{'username': 'u1'}, {'username': 'u2'}, ...]

# Insert all data, committing every 100 rows. If, for example,
# there are 789 items in the list, then there will be a total of
# 8 transactions (7x100 and 1x89).
for row in db.batch_commit(row_data, 100):
    User.create(**row)

另一种可能更有效的替代方法是将数据批处理为多值INSERT语句（例如，使用 Model.insert_many()）：

with db.atomic():
    for idx in range(0, len(row_data), 100):
        # Insert 100 rows at a time.
        rows = row_data[idx:idx + 100]
        User.insert_many(rows).execute()

table_exists(table[, schema=None])

参数：
表( str ) – 表名。
架构( str ) – 架构名称（可选）。
回报：
bool指示表是否存在。

get_tables([schema=None])

参数： 图式( str ) – 架构名称（可选）。
回报： 数据库中的表名列表。

get_indexes(table[, schema=None])

参数：
表( str ) – 表名。
架构( str ) – 架构名称（可选）。
返回IndexMetadata元组列表。

例子：

print(db.get_indexes('entry'))
[IndexMetadata(
     name='entry_public_list',
     sql='CREATE INDEX "entry_public_list" ...',
     columns=['timestamp'],
     unique=False,
     table='entry'),
 IndexMetadata(
     name='entry_slug',
     sql='CREATE UNIQUE INDEX "entry_slug" ON "entry" ("slug")',
     columns=['slug'],
     unique=True,
     table='entry')]

get_columns(table[, schema=None])

参数：
表( str ) – 表名。
架构( str ) – 架构名称（可选）。
返回ColumnMetadata元组列表。

例子：

print(db.get_columns('entry'))
[ColumnMetadata(
     name='id',
     data_type='INTEGER',
     null=False,
     primary_key=True,
     table='entry'),
 ColumnMetadata(
     name='title',
     data_type='TEXT',
     null=False,
     primary_key=False,
     table='entry'),
 ...]

get_primary_keys(table[, schema=None])

参数：
表( str ) – 表名。
架构( str ) – 架构名称（可选）。
返回包含主键的列名列表。

例子：

print(db.get_primary_keys('entry'))
['id']

get_foreign_keys(table[, schema=None])

参数：
表( str ) – 表名。
架构( str ) – 架构名称（可选）。
返回表上ForeignKeyMetadata存在的键的元组列表。

例子：

print(db.get_foreign_keys('entrytag'))
[ForeignKeyMetadata(
     column='entry_id',
     dest_table='entry',
     dest_column='id',
     table='entrytag'),
 ...]

get_views([schema=None])

参数： 图式( str ) – 架构名称（可选）。
返回ViewMetadata数据库中存在的 VIEW 的元组列表。

例子：

print(db.get_views())
[ViewMetadata(
     name='entries_public',
     sql='CREATE VIEW entries_public AS SELECT ... '),
 ...]

sequence_exists(seq)

参数： 序列( str ) – 序列的名称。
回报： 序列是否存在。
返回类型： 布尔

create_tables(models[, **options])

参数：
模型( list ) --Model类列表。
options – 调用时指定的选项 Model.create_table()。
为给定的模型列表创建表、索引和关联的元数据。

解决依赖关系，以便以适当的顺序创建表。

drop_tables(models[, **options])

参数：
模型( list ) --Model类列表。
kwargs – 调用时指定的选项 Model.drop_table()。
删除给定模型列表的表、索引和相关元数据。

解决依赖关系，以便以适当的顺序删除表。

bind(models[, bind_refs=True[, bind_backrefs=True]])

参数：
models ( list ) – 一个或多个Model要绑定的类。
bind_refs ( bool ) – 绑定相关模型。
bind_backrefs ( bool ) – 绑定反向引用相关模型。
将给定的模型列表和指定的关系绑定到数据库。

bind_ctx(models[, bind_refs=True[, bind_backrefs=True]])

参数：
models ( list ) – 要绑定到数据库的模型列表。
bind_refs ( bool ) – 绑定使用外键引用的模型。
bind_backrefs ( bool ) – 使用外键绑定引用给定模型的模型。
创建一个上下文管理器，在包装块的持续时间内将给定模型与当前数据库绑定（关联）。

例子：

MODELS = (User, Account, Note)

# Bind the given models to the db for the duration of wrapped block.
def use_test_database(fn):
    @wraps(fn)
    def inner(self):
        with test_db.bind_ctx(MODELS):
            test_db.create_tables(MODELS)
            try:
                fn(self)
            finally:
                test_db.drop_tables(MODELS)
    return inner


class TestSomething(TestCase):
    @use_test_database
    def test_something(self):
        # ... models are bound to test database ...
        pass

extract_date(date_part, date_field)

参数：
date_part ( str ) – 要提取的日期部分，例如“年份”。
date_field ( Node ) – 包含日期/时间的 SQL 节点，例如DateTimeField.
回报：
表示将返回提供的日期部分的函数调用的 SQL 节点。

提供用于提取日期时间的一部分的兼容接口。

truncate_date(date_part, date_field)

参数：
date_part ( str ) – 要截断的日期部分，例如“day”。
date_field ( Node ) – 包含日期/时间的 SQL 节点，例如DateTimeField.
回报：
表示将返回截断日期部分的函数调用的 SQL 节点。

提供一个兼容的接口，用于将日期时间截断为给定的分辨率。

random()
回报： 表示返回随机值的函数调用的 SQL 节点。
用于调用数据库提供的适当随机数生成函数的兼容接口。对于 Postgres 和 Sqlite，这相当于fn.random(), 对于 MySQL fn.rand()。