The schema module provides the building blocks for database metadata.
Each element within this module describes a database entity which can be created and dropped, or is otherwise part of such an entity. Examples include tables, columns, sequences, and indexes.
All entities are subclasses of SchemaItem, and as defined in this module they are intended to be agnostic of any vendor-specific constructs.
A collection of entities are grouped into a unit called MetaData. MetaData serves as a logical grouping of schema elements, and can also be associated with an actual database connection such that operations involving the contained elements can contact the database as needed.
Two of the elements here also build upon their "syntactic" counterparts, which are defined in module sqlalchemy.sql.expression, specifically Table and Column. Since these objects are part of the SQL expression language, they are usable as components in SQL expressions.
Represent a column in a database table.
This is a subclass of expression.ColumnClause and represents an actual existing table in the database, in a similar fashion as TableClause/Table.
Construct a new Column object.
Arguments are:
Keyword arguments include:
A plain default value on a column.
This could correspond to a constant, a callable function, or a SQL clause.
Represent a table-level Constraint such as a composite primary key, foreign key, or unique constraint.
Implements a hybrid of dict/setlike behavior with regards to the list of underying columns.
Defines a column-level ForeignKey constraint between two columns.
ForeignKey is specified as an argument to a Column object.
One or more ForeignKey objects are used within a ForeignKeyConstraint object which represents the table-level constraint definition.
Construct a new ForeignKey object.
return the column in the given table referenced by this ForeignKey, or None if this ForeignKey does not reference the given table.
Table-level foreign key constraint, represents a collection of ForeignKey objects.
Construct a new ForeignKeyConstraint.
Represent an index of columns from a database table.
Construct an index object.
Arguments are:
Keyword arguments include:
A collection of Tables and their associated schema constructs.
Holds a collection of Tables and an optional binding to an Engine or Connection. If bound, the Table objects in the collection and their columns may participate in implicit SQL execution.
The bind property may be assigned to dynamically. A common pattern is to start unbound and then bind later when an engine is available:
metadata = MetaData() # define tables Table('mytable', metadata, ...) # connect to an engine later, perhaps after loading a URL from a # configuration file metadata.bind = an_engine
MetaData is a thread-safe object after tables have been explicitly defined or loaded via reflection.
Create a new MetaData object.
An Engine or Connection to which this MetaData is bound.
This property may be assigned an Engine or Connection, or assigned a string or URL to automatically create a basic Engine for this bind with create_engine().
Deprecated. Bind this MetaData to an Engine.
Use metadata.bind = <engine> or metadata.bind = <url>.
- bind
- A string, URL, Engine or Connection instance. If a string or URL, will be passed to create_engine() along with \**kwargs to produce the engine which to connect to. Otherwise connects directly to the given Engine.
Create all tables stored in this metadata.
This will conditionally create tables depending on if they do not yet exist in the database.
Drop all tables stored in this metadata.
This will conditionally drop tables depending on if they currently exist in the database.
Load all available table definitions from the database.
Automatically creates Table entries in this MetaData for any table available in the database but not yet present in the MetaData. May be called multiple times to pick up tables recently added to the database, however no special action is taken if a table in this MetaData no longer exists in the database.
Optional. Load only a sub-set of available named tables. May be specified as a sequence of names or a callable.
If a sequence of names is provided, only those tables will be reflected. An error is raised if a table is requested but not available. Named tables already present in this MetaData are ignored.
If a callable is provided, it will be used as a boolean predicate to filter the list of potential table names. The callable is called with a table name and this MetaData instance as positional arguments and should return a true value for any table to reflect.
A default that takes effect on the database side.
Represents a named sequence.
Construct a new Sequence.
Represent a relational database table.
Construct a Table.
Table objects can be constructed directly. Arguments are:
The name of this table, exactly as it appears, or will appear, in the database.
This property, along with the schema, indicates the singleton identity of this table.
Further tables constructed with the same name/schema combination will return the same Table instance.
kwargs include:
Issue a CREATE statement for this table.
See also metadata.create_all().
Issue a DROP statement for this table.
See also metadata.drop_all().
Return a copy of this Table associated with a different MetaData.
A MetaData variant that presents a different bind in every thread.
Makes the bind property of the MetaData a thread-local value, allowing this collection of tables to be bound to different Engine implementations or connections in each thread.
The ThreadLocalMetaData starts off bound to None in each thread. Binds must be made explicitly by assigning to the bind property or using connect(). You can also re-bind dynamically multiple times per thread, just like a regular MetaData.
Use this type of MetaData when your tables are present in more than one database and you need to address them simultanesouly.
The bound Engine or Connection for this thread.
This property may be assigned an Engine or Connection, or assigned a string or URL to automatically create a basic Engine for this bind with create_engine().
Deprecated. Bind to an Engine in the caller's thread.
Use metadata.bind=<engine> or metadata.bind=<url>.
- bind
- A string, URL, Engine or Connection instance. If a string or URL, will be passed to create_engine() along with \**kwargs to produce the engine which to connect to. Otherwise connects directly to the given Engine.