Release: 2.1.0b1 | Release Date: January 21, 2026

# SQLAlchemy 2.1 Documentation

# Schema Definition Language

This section references SQLAlchemy schema metadata, a comprehensive system of describing and inspecting database schemas.

The core of SQLAlchemy’s query and object mapping operations are supported by database metadata, which is comprised of Python objects that describe tables and other schema-level objects. These objects are at the core of three major types of operations - issuing CREATE and DROP statements (known as DDL), constructing SQL queries, and expressing information about structures that already exist within the database.

Database metadata can be expressed by explicitly naming the various components and their properties, using constructs such as `Table`, `Column`, `ForeignKey` and `Sequence`, all of which are imported from the `sqlalchemy.schema` package. It can also be generated by SQLAlchemy using a process called reflection, which means you start with a single object such as `Table`, assign it a name, and then instruct SQLAlchemy to load all the additional information related to that name from a particular engine source.

A key feature of SQLAlchemy’s database metadata constructs is that they are designed to be used in a declarative style which closely resembles that of real DDL. They are therefore most intuitive to those who have some background in creating real schema generation scripts.

- Describing Databases with MetaData
  - Accessing Tables and Columns
  - Creating and Dropping Database Tables
  - Altering Database Objects through Migrations
  - Specifying the Schema Name
    - Specifying a Default Schema Name with MetaData
    - Applying Dynamic Schema Naming Conventions
    - Setting a Default Schema for New Connections
    - Schemas and Reflection
  - Alternate CREATE TABLE forms: CREATE VIEW, CREATE TABLE AS
    - Using `CreateView`
    - Using `CreateTableAs` or `Select.into()`
  - Backend-Specific Options for `Table`
  - Column, Table, MetaData API
    - `Column`
    - `CreateTableAs`
    - `CreateView`
    - `MetaData`
    - `SchemaConst`
    - `SchemaItem`
    - `Table`
    - `TypedColumns`
    - `Named`
    - `HasRowPos`
- Reflecting Database Objects
  - Overriding Reflected Columns
  - Reflecting Views
  - Reflecting All Tables at Once
  - Reflecting Tables from Other Schemas
    - Interaction of Schema-qualified Reflection with the Default Schema
  - Fine Grained Reflection with Inspector
    - `Inspector`
    - `ReflectedColumn`
    - `ReflectedComputed`
    - `ReflectedCheckConstraint`
    - `ReflectedForeignKeyConstraint`
    - `ReflectedIdentity`
    - `ReflectedIndex`
    - `ReflectedPrimaryKeyConstraint`
    - `ReflectedUniqueConstraint`
    - `ReflectedTableComment`
  - Reflecting with Database-Agnostic Types
  - Limitations of Reflection
- Column INSERT/UPDATE Defaults
  - Scalar Defaults
  - Python-Executed Functions
    - Context-Sensitive Default Functions
  - Client-Invoked SQL Expressions
  - Server-invoked DDL-Explicit Default Expressions
  - Marking Implicitly Generated Values, timestamps, and Triggered Columns
  - Defining Sequences
    - Associating a Sequence on a SERIAL column
    - Executing a Sequence Standalone
    - Associating a Sequence with the MetaData
    - Associating a Sequence as the Server Side Default
  - Computed Columns (GENERATED ALWAYS AS)
  - Identity Columns (GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY)
  - Default Objects API
    - `Computed`
    - `ColumnDefault`
    - `DefaultClause`
    - `DefaultGenerator`
    - `FetchedValue`
    - `Sequence`
    - `Identity`
- Defining Constraints and Indexes
  - Defining Foreign Keys
    - Creating/Dropping Foreign Key Constraints via ALTER
    - ON UPDATE and ON DELETE
  - UNIQUE Constraint
  - CHECK Constraint
  - PRIMARY KEY Constraint
  - Setting up Constraints when using the Declarative ORM Extension
  - Configuring Constraint Naming Conventions
    - Configuring a Naming Convention for a MetaData Collection
    - The Default Naming Convention
    - Truncation of Long Names
    - Creating Custom Tokens for Naming Conventions
    - Naming CHECK Constraints
    - Configuring Naming for Boolean, Enum, and other schema types
    - Using Naming Conventions with ORM Declarative Mixins
  - Constraints API
    - `Constraint`
    - `ColumnCollectionMixin`
    - `ColumnCollectionConstraint`
    - `CheckConstraint`
    - `ForeignKey`
    - `ForeignKeyConstraint`
    - `HasConditionalDDL`
    - `PrimaryKeyConstraint`
    - `UniqueConstraint`
    - `conv()`
  - Indexes
    - Functional Indexes
  - Index API
    - `Index`
- Customizing DDL
  - Custom DDL
  - Controlling DDL Sequences
  - Using the built-in DDLElement Classes
  - Controlling DDL Generation of Constraints and Indexes
  - DDL Expression Constructs API
    - `sort_tables()`
    - `sort_tables_and_constraints()`
    - `BaseDDLElement`
    - `ExecutableDDLElement`
    - `DDL`
    - `CheckFirst`
    - `_CreateDropBase`
    - `CreateTable`
    - `DropTable`
    - `DropView`
    - `CreateColumn`
    - `insert_sentinel()`
    - `CreateSequence`
    - `DropSequence`
    - `CreateIndex`
    - `DropIndex`
    - `AddConstraint`
    - `DropConstraint`
    - `CreateSchema`
    - `DropSchema`