sqlalchemy.sql.schema.Table

Constructor for :class:`_schema.Table`. :param name: The name of this table as represented in the database. The table name, along with the value of the ``schema`` parameter, forms a key which uniquely identifies this :class:`_schema.Table` within the owning :class:`_schema.MetaData` collection. Additional calls to :class:`_schema.Table` with the same name, metadata, and schema name will return the same :class:`_schema.Table` object. Names which contain no upper case characters will be treated as case insensitive names, and will not be quoted unless they are a reserved word or contain special characters. A name with any number of upper case characters is considered to be case sensitive, and will be sent as quoted. To enable unconditional quoting for the table name, specify the flag ``quote=True`` to the constructor, or use the :class:`.quoted_name` construct to specify the name. :param metadata: a :class:`_schema.MetaData` object which will contain this table. The metadata is used as a point of association of this table with other tables which are referenced via foreign key. It also may be used to associate this table with a particular :class:`.Connection` or :class:`.Engine`. :param \*args: Additional positional arguments are used primarily to add the list of :class:`_schema.Column` objects contained within this table. Similar to the style of a CREATE TABLE statement, other :class:`.SchemaItem` constructs may be added here, including :class:`.PrimaryKeyConstraint`, and :class:`_schema.ForeignKeyConstraint`. :param autoload_replace: Defaults to ``True``; when using :paramref:`_schema.Table.autoload_with` in conjunction with :paramref:`_schema.Table.extend_existing`, indicates that :class:`_schema.Column` objects present in the already-existing :class:`_schema.Table` object should be replaced with columns of the same name retrieved from the autoload process. When ``False``, columns already present under existing names will be omitted from the reflection process. Note that this setting does not impact :class:`_schema.Column` objects specified programmatically within the call to :class:`_schema.Table` that also is autoloading; those :class:`_schema.Column` objects will always replace existing columns of the same name when :paramref:`_schema.Table.extend_existing` is ``True``. .. seealso:: :paramref:`_schema.Table.autoload_with` :paramref:`_schema.Table.extend_existing` :param autoload_with: An :class:`_engine.Engine` or :class:`_engine.Connection` object, or a :class:`_reflection.Inspector` object as returned by :func:`_sa.inspect` against one, with which this :class:`_schema.Table` object will be reflected. When set to a non-None value, the autoload process will take place for this table against the given engine or connection. :param extend_existing: When ``True``, indicates that if this :class:`_schema.Table` is already present in the given :class:`_schema.MetaData`, apply further arguments within the constructor to the existing :class:`_schema.Table`. If :paramref:`_schema.Table.extend_existing` or :paramref:`_schema.Table.keep_existing` are not set, and the given name of the new :class:`_schema.Table` refers to a :class:`_schema.Table` that is already present in the target :class:`_schema.MetaData` collection, and this :class:`_schema.Table` specifies additional columns or other constructs or flags that modify the table's state, an error is raised. The purpose of these two mutually-exclusive flags is to specify what action should be taken when a :class:`_schema.Table` is specified that matches an existing :class:`_schema.Table`, yet specifies additional constructs. :paramref:`_schema.Table.extend_existing` will also work in conjunction with :paramref:`_schema.Table.autoload_with` to run a new reflection operation against the database, even if a :class:`_schema.Table` of the same name is already present in the target :class:`_schema.MetaData`; newly reflected :class:`_schema.Column` objects and other options will be added into the state of the :class:`_schema.Table`, potentially overwriting existing columns and options of the same name. As is always the case with :paramref:`_schema.Table.autoload_with`, :class:`_schema.Column` objects can be specified in the same :class:`_schema.Table` constructor, which will take precedence. Below, the existing table ``mytable`` will be augmented with :class:`_schema.Column` objects both reflected from the database, as well as the given :class:`_schema.Column` named "y":: Table("mytable", metadata, Column('y', Integer), extend_existing=True, autoload_with=engine ) .. seealso:: :paramref:`_schema.Table.autoload_with` :paramref:`_schema.Table.autoload_replace` :paramref:`_schema.Table.keep_existing` :param implicit_returning: True by default - indicates that RETURNING can be used, typically by the ORM, in order to fetch server-generated values such as primary key values and server side defaults, on those backends which support RETURNING. In modern SQLAlchemy there is generally no reason to alter this setting, except for some backend specific cases (see :ref:`mssql_triggers` in the SQL Server dialect documentation for one such example). :param include_columns: A list of strings indicating a subset of columns to be loaded via the ``autoload`` operation; table columns who aren't present in this list will not be represented on the resulting ``Table`` object. Defaults to ``None`` which indicates all columns should be reflected. :param resolve_fks: Whether or not to reflect :class:`_schema.Table` objects related to this one via :class:`_schema.ForeignKey` objects, when :paramref:`_schema.Table.autoload_with` is specified. Defaults to True. Set to False to disable reflection of related tables as :class:`_schema.ForeignKey` objects are encountered; may be used either to save on SQL calls or to avoid issues with related tables that can't be accessed. Note that if a related table is already present in the :class:`_schema.MetaData` collection, or becomes present later, a :class:`_schema.ForeignKey` object associated with this :class:`_schema.Table` will resolve to that table normally. .. versionadded:: 1.3 .. seealso:: :paramref:`.MetaData.reflect.resolve_fks` :param info: Optional data dictionary which will be populated into the :attr:`.SchemaItem.info` attribute of this object. :param keep_existing: When ``True``, indicates that if this Table is already present in the given :class:`_schema.MetaData`, ignore further arguments within the constructor to the existing :class:`_schema.Table`, and return the :class:`_schema.Table` object as originally created. This is to allow a function that wishes to define a new :class:`_schema.Table` on first call, but on subsequent calls will return the same :class:`_schema.Table`, without any of the declarations (particularly constraints) being applied a second time. If :paramref:`_schema.Table.extend_existing` or :paramref:`_schema.Table.keep_existing` are not set, and the given name of the new :class:`_schema.Table` refers to a :class:`_schema.Table` that is already present in the target :class:`_schema.MetaData` collection, and this :class:`_schema.Table` specifies additional columns or other constructs or flags that modify the table's state, an error is raised. The purpose of these two mutually-exclusive flags is to specify what action should be taken when a :class:`_schema.Table` is specified that matches an existing :class:`_schema.Table`, yet specifies additional constructs. .. seealso:: :paramref:`_schema.Table.extend_existing` :param listeners: A list of tuples of the form ``(<eventname>, <fn>)`` which will be passed to :func:`.event.listen` upon construction. This alternate hook to :func:`.event.listen` allows the establishment of a listener function specific to this :class:`_schema.Table` before the "autoload" process begins. Historically this has been intended for use with the :meth:`.DDLEvents.column_reflect` event, however note that this event hook may now be associated with the :class:`_schema.MetaData` object directly:: def listen_for_reflect(table, column_info): "handle the column reflection event" # ... t = Table( 'sometable', autoload_with=engine, listeners=[ ('column_reflect', listen_for_reflect) ]) .. seealso:: :meth:`_events.DDLEvents.column_reflect` :param must_exist: When ``True``, indicates that this Table must already be present in the given :class:`_schema.MetaData` collection, else an exception is raised. :param prefixes: A list of strings to insert after CREATE in the CREATE TABLE statement. They will be separated by spaces. :param quote: Force quoting of this table's name on or off, corresponding to ``True`` or ``False``. When left at its default of ``None``, the column identifier will be quoted according to whether the name is case sensitive (identifiers with at least one upper case character are treated as case sensitive), or if it's a reserved word. This flag is only needed to force quoting of a reserved word which is not known by the SQLAlchemy dialect. .. note:: setting this flag to ``False`` will not provide case-insensitive behavior for table reflection; table reflection will always search for a mixed-case name in a case sensitive fashion. Case insensitive names are specified in SQLAlchemy only by stating the name with all lower case characters. :param quote_schema: same as 'quote' but applies to the schema identifier. :param schema: The schema name for this table, which is required if the table resides in a schema other than the default selected schema for the engine's database connection. Defaults to ``None``. If the owning :class:`_schema.MetaData` of this :class:`_schema.Table` specifies its own :paramref:`_schema.MetaData.schema` parameter, then that schema name will be applied to this :class:`_schema.Table` if the schema parameter here is set to ``None``. To set a blank schema name on a :class:`_schema.Table` that would otherwise use the schema set on the owning :class:`_schema.MetaData`, specify the special symbol :attr:`.BLANK_SCHEMA`. .. versionadded:: 1.0.14 Added the :attr:`.BLANK_SCHEMA` symbol to allow a :class:`_schema.Table` to have a blank schema name even when the parent :class:`_schema.MetaData` specifies :paramref:`_schema.MetaData.schema`. The quoting rules for the schema name are the same as those for the ``name`` parameter, in that quoting is applied for reserved words or case-sensitive names; to enable unconditional quoting for the schema name, specify the flag ``quote_schema=True`` to the constructor, or use the :class:`.quoted_name` construct to specify the name. :param comment: Optional string that will render an SQL comment on table creation. .. versionadded:: 1.2 Added the :paramref:`_schema.Table.comment` parameter to :class:`_schema.Table`. :param \**kw: Additional keyword arguments not mentioned above are dialect specific, and passed in the form ``<dialectname>_<argname>``. See the documentation regarding an individual dialect at :ref:`dialect_toplevel` for detail on documented arguments.

Undocumented

Undocumented

Undocumented

Add a 'dependency' for this Table. This is another Table object which must be created first before this one can, or dropped after this one. Usually, dependencies between tables are determined via ForeignKey objects. However, for other situations that create dependencies outside of foreign keys (rules, inheriting), this method can manually establish such a link.

Append a :class:`_schema.Column` to this :class:`_schema.Table`. The "key" of the newly added :class:`_schema.Column`, i.e. the value of its ``.key`` attribute, will then be available in the ``.c`` collection of this :class:`_schema.Table`, and the column definition will be included in any CREATE TABLE, SELECT, UPDATE, etc. statements generated from this :class:`_schema.Table` construct. Note that this does **not** change the definition of the table as it exists within any underlying database, assuming that table has already been created in the database. Relational databases support the addition of columns to existing tables using the SQL ALTER command, which would need to be emitted for an already-existing table that doesn't contain the newly added column. :param replace_existing: When ``True``, allows replacing existing columns. When ``False``, the default, an warning will be raised if a column with the same ``.key`` already exists. A future version of sqlalchemy will instead rise a warning. .. versionadded:: 1.4.0

Append a :class:`_schema.Constraint` to this :class:`_schema.Table`. This has the effect of the constraint being included in any future CREATE TABLE statement, assuming specific DDL creation events have not been associated with the given :class:`_schema.Constraint` object. Note that this does **not** produce the constraint within the relational database automatically, for a table that already exists in the database. To add a constraint to an existing relational database table, the SQL ALTER command must be used. SQLAlchemy also provides the :class:`.AddConstraint` construct which can produce this SQL when invoked as an executable clause.

Issue a ``CREATE`` statement for this :class:`_schema.Table`, using the given :class:`.Connection` or :class:`.Engine` for connectivity. .. seealso:: :meth:`_schema.MetaData.create_all`.

Issue a ``DROP`` statement for this :class:`_schema.Table`, using the given :class:`.Connection` or :class:`.Engine` for connectivity. .. seealso:: :meth:`_schema.MetaData.drop_all`.

Return a copy of this :class:`_schema.Table` associated with a different :class:`_schema.MetaData`. E.g.:: m1 = MetaData() user = Table('user', m1, Column('id', Integer, primary_key=True)) m2 = MetaData() user_copy = user.to_metadata(m2) .. versionchanged:: 1.4 The :meth:`_schema.Table.to_metadata` function was renamed from :meth:`_schema.Table.tometadata`. :param metadata: Target :class:`_schema.MetaData` object, into which the new :class:`_schema.Table` object will be created. :param schema: optional string name indicating the target schema. Defaults to the special symbol :attr:`.RETAIN_SCHEMA` which indicates that no change to the schema name should be made in the new :class:`_schema.Table`. If set to a string name, the new :class:`_schema.Table` will have this new name as the ``.schema``. If set to ``None``, the schema will be set to that of the schema set on the target :class:`_schema.MetaData`, which is typically ``None`` as well, unless set explicitly:: m2 = MetaData(schema='newschema') # user_copy_one will have "newschema" as the schema name user_copy_one = user.to_metadata(m2, schema=None) m3 = MetaData() # schema defaults to None # user_copy_two will have None as the schema name user_copy_two = user.to_metadata(m3, schema=None) :param referred_schema_fn: optional callable which can be supplied in order to provide for the schema name that should be assigned to the referenced table of a :class:`_schema.ForeignKeyConstraint`. The callable accepts this parent :class:`_schema.Table`, the target schema that we are changing to, the :class:`_schema.ForeignKeyConstraint` object, and the existing "target schema" of that constraint. The function should return the string schema name that should be applied. To reset the schema to "none", return the symbol :data:`.BLANK_SCHEMA`. To effect no change, return ``None`` or :data:`.RETAIN_SCHEMA`. .. versionchanged:: 1.4.33 The ``referred_schema_fn`` function may return the :data:`.BLANK_SCHEMA` or :data:`.RETAIN_SCHEMA` symbols. E.g.:: def referred_schema_fn(table, to_schema, constraint, referred_schema): if referred_schema == 'base_tables': return referred_schema else: return to_schema new_table = table.to_metadata(m2, schema="alt_schema", referred_schema_fn=referred_schema_fn) .. versionadded:: 0.9.2 :param name: optional string name indicating the target table name. If not specified or None, the table name is retained. This allows a :class:`_schema.Table` to be copied to the same :class:`_schema.MetaData` target with a new name. .. versionadded:: 1.0.0

Return a copy of this :class:`_schema.Table` associated with a different :class:`_schema.MetaData`. See :meth:`_schema.Table.to_metadata` for a full description.