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

SQLAlchemy 1.1文档

反映数据库对象

可以指示Table对象从数据库中已有的相应数据库模式对象加载有关自己的信息。这个过程被称为反射In the most simple case you need only specify the table name, a MetaData object, and the autoload=True flag. 如果MetaData不是永久绑定的,那么还要添加autoload_with参数:

>>> messages = Table('messages', meta, autoload=True, autoload_with=engine)
>>> [c.name for c in messages.columns]
['message_id', 'message_name', 'date']

上面的操作将使用给定的引擎来查询数据库中关于messages表的信息,然后将生成ColumnForeignKey和其他与这个信息相对应的对象就像Python中手工构造的Table对象一样。

当表被反映时,如果给定的表通过外键引用另一个表,则在表示连接的MetaData对象内创建第二个Table对象。下面,假设表shopping_cart_items引用了一个名为shopping_carts的表。反映shopping_cart_items表的作用是使得shopping_carts表也将被加载:

>>> shopping_cart_items = Table('shopping_cart_items', meta, autoload=True, autoload_with=engine)
>>> 'shopping_carts' in meta.tables:
True

The MetaData has an interesting “singleton-like” behavior such that if you requested both tables individually, MetaData will ensure that exactly one Table object is created for each distinct table name. 如果已经存在具有给定名称的Table构造函数实际返回已经存在的Table对象。如下所示,我们可以通过命名来访问已经生成的shopping_carts表:

shopping_carts = Table('shopping_carts', meta)

当然,无论是使用上面的表,使用autoload=True是一个好主意。这是为了表格的属性将被加载,如果他们还没有。自动装载操作只发生在表中,如果它尚未被加载;一旦加载,对Table的新调用将不会重新发出任何反射查询。

覆盖反射列

反映表格时,可以用显式值重写单个列;这对于指定自定义数据类型,数据库中可能没有配置的主键等约束是很方便的。:

>>> mytable = Table('mytable', meta,
... Column('id', Integer, primary_key=True),   # override reflected 'id' to have primary key
... Column('mydata', Unicode(50)),    # override reflected 'mydata' to be Unicode
... autoload=True)

反映意见

反射系统也可以反映意见。基本用法与表格相同:

my_view = Table("some_view", metadata, autoload=True)

Above, my_view is a Table object with Column objects representing the names and types of each column within the view “some_view”.

通常,在反映视图时至少需要一个主键约束,如果不是外键也是如此。视图反射不会推断这些限制。

为此,使用“覆盖”技术,明确指定那些属于主键或具有外键约束的列:

my_view = Table("some_view", metadata,
                Column("view_id", Integer, primary_key=True),
                Column("related_thing", Integer, ForeignKey("othertable.thing_id")),
                autoload=True
)

一次反映所有表

The MetaData object can also get a listing of tables and reflect the full set. 这是通过使用reflect()方法实现的。调用它之后,所有定位的表都出现在MetaData对象的表的字典中:

meta = MetaData()
meta.reflect(bind=someengine)
users_table = meta.tables['users']
addresses_table = meta.tables['addresses']

metadata.reflect() also provides a handy way to clear or delete all the rows in a database:

meta = MetaData()
meta.reflect(bind=someengine)
for table in reversed(meta.sorted_tables):
    someengine.execute(table.delete())

使用Inspector 进行细粒度反射

提供了一个低级别的接口,它提供了从给定数据库加载架构,表,列和约束描述列表的后端无关系统。这就是所谓的“督察”:

from sqlalchemy import create_engine
from sqlalchemy.engine import reflection
engine = create_engine('...')
insp = reflection.Inspector.from_engine(engine)
print(insp.get_table_names())
class sqlalchemy.engine.reflection.Inspector(bind)

执行数据库模式检查。

The Inspector acts as a proxy to the reflection methods of the Dialect, providing a consistent interface as well as caching support for previously fetched metadata.

通常通过inspect()函数创建Inspector对象:

from sqlalchemy import inspect, create_engine
engine = create_engine('...')
insp = inspect(engine)

上面的检查方法相当于使用Inspector.from_engine()方法,即:

engine = create_engine('...')
insp = Inspector.from_engine(engine)

Where above, the Dialect may opt to return an Inspector subclass that provides additional methods specific to the dialect’s target database.

__初始化__ T0> ( T1> 结合 T2> ) T3> ¶ T4>

初始化一个新的Inspector

参数:bind – a Connectable, which is typically an instance of Engine or Connection.

对于Inspector的特定于方言的实例,请参阅Inspector.from_engine()

default_schema_name T0> ¶ T1>

返回当前引擎的数据库用户的方言提供的默认模式名称。

例如。对于SQL Server,这通常是Postgresql和dbopublic

classmethod from_engine(bind)

从给定的引擎或连接构造一个新的特定于方言的Inspector对象。

参数:bind – a Connectable, which is typically an instance of Engine or Connection.

This method differs from direct a direct constructor call of Inspector in that the Dialect is given a chance to provide a dialect-specific Inspector instance, which may provide additional methods.

请参阅Inspector上的示例。

get_check_constraints table_nameschema = None** kw ) T5> ¶ T6>

table_name中返回关于检查约束的信息。

给定一个字符串table_name和一个可选的字符串schema,将检查约束信息返回为带有这些键的字典列表:

名称
检查约束的名称
SQLTEXT
检查约束的SQL表达式
参数:
  • table_name – string name of the table. 对于特殊的引用,请使用quoted_name
  • 架构 - 字符串架构名称;如果省略,则使用数据库连接的默认模式。对于特殊的引用,请使用quoted_name

版本1.1.0新增

get_columns table_nameschema = None** kw ) T5> ¶ T6>

返回有关table_name中列的信息。

给定一个字符串table_name和一个可选的字符串schema,将列信息作为带有这些键的字典列表返回:

名称
该列的名称
类型
TypeEngine
可空
布尔
默认
该列的默认值
ATTRS
包含可选列属性的字典
参数:
  • table_name – string name of the table. 对于特殊的引用,请使用quoted_name
  • 架构 - 字符串架构名称;如果省略,则使用数据库连接的默认模式。对于特殊的引用,请使用quoted_name
get_foreign_keys table_nameschema = None** kw ) T5> ¶ T6>

table_name中返回有关foreign_keys的信息。

给定一个字符串table_name和一个可选字符串schema,将外键信息作为具有这些键的字典列表返回:

constrained_columns
构成外键的列名称的列表
referred_schema
被引用模式的名称
referred_table
被引用表的名称
referred_columns
被引用表中对应于constrained_columns的列名称列表
名称
外键约束的可选名称。
参数:
  • table_name – string name of the table. 对于特殊的引用,请使用quoted_name
  • 架构 - 字符串架构名称;如果省略,则使用数据库连接的默认模式。对于特殊的引用,请使用quoted_name
get_indexes table_nameschema = None** kw ) T5> ¶ T6>

返回关于table_name中索引的信息。

给定一个字符串table_name和一个可选字符串schema,将索引信息返回为带有这些键的字典列表:

名称
索引的名字
COLUMN_NAMES
依次列名称列表
独特
布尔
dialect_options

方言特定索引选项的字典。所有的方言可能不存在。

版本1.0.0中的新功能

参数:
  • table_name – string name of the table. 对于特殊的引用,请使用quoted_name
  • 架构 - 字符串架构名称;如果省略,则使用数据库连接的默认模式。对于特殊的引用,请使用quoted_name
get_pk_constraint table_nameschema =无** kw ) T5> ¶ T6>

返回有关table_name上主键约束的信息。

给定一个字符串table_name和一个可选字符串schema,将主键信息作为字典返回,并带有这些键:

constrained_columns
构成主键的列名称的列表
名称
主键约束的可选名称。
参数:
  • table_name – string name of the table. 对于特殊的引用,请使用quoted_name
  • 架构 - 字符串架构名称;如果省略,则使用数据库连接的默认模式。对于特殊的引用,请使用quoted_name
get_primary_keys table_nameschema =无** kw ) T5> ¶ T6>

返回table_name中的主键信息。

从版本0.7开始弃用:调用弃用的方法get_primary_keys。改用get_pk_constraint。

给定一个字符串table_name和一个可选的字符串schema,返回主键信息作为列名列表。

get_schema_names T0> ( T1> ) T2> ¶ T3>

返回所有模式名称。

get_sorted_table_and_fkc_names T0> ( T1> 架构=无 T2> ) T3> ¶ T4>

返回特定模式中引用的依赖关系排序表和外键约束名称。

这将产生(tablename, [(tname, fkname), > ...])由CREATE顺序中的表名组成,它们与未被检测为属于周期的外键约束名称。The final element will be (None, [(tname, fkname), (tname, fkname), ..]) which will consist of remaining foreign key constraint names that would require a separate CREATE step after-the-fact, based on dependencies between tables.

New in version 1.0.-.

也可以看看

Inspector.get_table_names()

sort_tables_and_constraints() - similar method which works
with an already-given MetaData.
get_table_names(schema=None, order_by=None)

返回特定模式中引用的所有表名称。

预计这些名字只是真实的表格,而不是视图。视图是使用Inspector.get_view_names()方法返回的。

参数:
  • schema – Schema name. 如果schema留在None中,则使用数据库的默认模式,否则搜索指定的模式。如果数据库不支持命名模式,则如果schema没有以None的形式传递,则行为是不确定的。对于特殊的引用,请使用quoted_name
  • order_by -

    可选的,可能是字符串“foreign_key”对外键依赖项进行排序。不会自动解决循环,如果循环存在,将会引发CircularDependencyError

    从版本1.0.0开始弃用: - 参见Inspector.get_sorted_table_and_fkc_names(),这个版本可以自动解析表之间的外键循环。

    Changed in version 0.8: the “foreign_key” sorting sorts tables in order of dependee to dependent; that is, in creation order, rather than in drop order. 这是为了保持与类似功能(如MetaData.sorted_tablesutil.sort_tables()的一致性。

get_table_options table_nameschema = None** kw ) T5> ¶ T6>

返回创建给定名称的表时指定的选项字典。

这当前包括一些适用于MySQL表的选项。

参数:
  • table_name – string name of the table. 对于特殊的引用,请使用quoted_name
  • 架构 - 字符串架构名称;如果省略,则使用数据库连接的默认模式。对于特殊的引用,请使用quoted_name
get_temp_table_names T0> ( T1> ) T2> ¶ T3>

返回当前绑定的临时表名称列表。

大多数方言都不支持这种方法。目前只有SQLite实现它。

版本1.0.0中的新功能

get_temp_view_names T0> ( T1> ) T2> ¶ T3>

返回当前绑定的临时视图名称的列表。

大多数方言都不支持这种方法。目前只有SQLite实现它。

版本1.0.0中的新功能

get_unique_constraints tt> table_nameschema =无** kw ) T5> ¶ T6>

返回关于table_name中的唯一约束的信息。

给定一个字符串table_name和一个可选的字符串schema,返回唯一的约束信息作为这些键的字典列表:

名称
唯一约束的名称
COLUMN_NAMES
依次列名称列表
参数:
  • table_name – string name of the table. 对于特殊的引用,请使用quoted_name
  • 架构 - 字符串架构名称;如果省略,则使用数据库连接的默认模式。对于特殊的引用,请使用quoted_name

0.8.4版本中的新功能

get_view_definition view_nameschema =无 t5 >

返回view_name的定义。

参数:schema – Optional, retrieve names from a non-default schema. 对于特殊的引用,请使用quoted_name
get_view_names T0> ( T1> 架构=无 T2> ) T3> ¶ T4>

返回schema中的所有视图名称。

参数:schema – Optional, retrieve names from a non-default schema. 对于特殊的引用,请使用quoted_name
reflecttable(table, include_columns, exclude_columns=())

给定一个Table对象,根据内省加载它的内部结构。

这是大多数方言用来制作表格反射的基本方法。直接使用就像:

from sqlalchemy import create_engine, MetaData, Table
from sqlalchemy.engine import reflection

engine = create_engine('...')
meta = MetaData()
user_table = Table('user', meta)
insp = Inspector.from_engine(engine)
insp.reflecttable(user_table, None)
参数:
  • table – a Table instance.
  • include_columns – a list of string column names to include in the reflection process. 如果None,所有列都会被反映出来。

反射的限制

请注意,反射过程仅使用关系数据库中表示的信息来重新创建Table元数据。该过程按照定义不能恢复实际上不存储在数据库中的模式的方面。无法从反思中获得的状态包括但不限于:

  • 客户端默认是使用Columndefault关键字定义的Python函数或SQL表达式(注意这与server_default分开,具体是什么可通过反射获得)。
  • 列信息,例如数据可能已被放置在Column.info字典中
  • ColumnTable.quote
  • 特定Sequence与给定Column的关联

关系数据库在很多情况下也以与SQLAlchemy中指定的格式不同的格式报告表格元数据。从反射返回的Table对象不能总是依赖于生成与原始Python定义的Table对象相同的DDL。发生这种情况的领域包括服务器默认值,列相关序列以及有关约束和数据类型的各种特征。服务器端的默认值可以通过cast指令返回(通常Postgresql将包含一个::<type> cast)或者不同于最初指定的引用模式。

另一类限制包括反射仅部分或尚未定义的模式结构。最近对反思的改进允许反映意见,索引和外键选项等内容。在写这篇文章的时候,像CHECK约束,表注释和触发器这样的结构没有被反映出来。