Data Modeling With SQLAlchemy and Alembic on Naveen Kannan

PostgreSQL Entity type Version Control with Alembic Utils.

Sun, 08 Feb 2026 00:00:00 +0000

Introduction

PostgreSQL (and other RDBMS) have entity types such as functions, views, materialized views, triggers, and policies. These entity types do a lot of useful work, and a well designed database will use them heavily.

These entity types are not typically considered part of the SQLAlchemy ORM, and by extension, the data model itself. By default, Alembic has no functionality to detect the creation of new entity types when it autogenerates migration files. The default Alembic ORM also has no functionality to define these entity types with classes.

However, these entity types are part of a database’s schema. Creation of/changes to them should be accounted for within the ORM and as part of migration version control, in much the same way as changes in a table are recorded in an ORM as part of migration version control.

In this blog post, we will pick up from the progress in the previous entry in this series and go over how we can use an extension to Alembic called Alembic Utils to add support for autogenerating migrations for some PostgreSQL entity types.

What we’ve already covered

In part 1:

We used SQLAlchemy to create the first iteration of a rudimentary data model, with three tables.
We configured Alembic to connect to a fresh development database and migrated our rudimentary data model.

In part 2:

We created a many-to-many association between orders and products, and a many-to-many association between products and tags.
We generated migration scripts using Alembic.
We committed the migration scripts to version control.

The data model at the end of the previous post.

What we’ll cover

In this blog post, we will cover how you can install Alembic Utils and begin incorporating entity types into the commerce data model.

We will do the following:

Update the virtual environment with Alembic Utils.
Configure Alembic to use the newly installed extension.
Create a function and a view in the ORM.
Register these entities with Alembic Utils.
Autogenerate a migration script with Alembic that we will review, and then apply the revisions.

Installing Alembic Utils

In part 1 of this series, we created a micromamba virtual environment called data_model with SQLAlchemy and Alembic installed.

We will activate this virtual envrionment and then install Alembic Utils.

First, activate the virtual environment.

micromamba activate data_model

Then, install the Alembic Utils extension within the environment. The documentation recommends using pip.

pip install alembic_utils

Export the new environment details using the following command:

micromamba env export > environment.yaml

Note

Updating your environment.yaml file any time your dependencies change is good practice.

It makes your virtual environment reproducible and accessible!

Adding a view to the database

Creating a View in the ORM

To explain what a view is, we can start by asking a straightforward high level question. What are the names of the products associated with a particular order? The stakeholders who have access to data might need to be able to access the products associated with a single specific order, or a group of specific orders.

In our database, there is a table called order_products that maps the associations between orders and products using the primary keys from that table. However, just looking at this table alone won’t give us the contextual information we need. We will need to write an SQL query to join the order_products table with the products table in order to retrieve the name and description of a particular order’s products.

This is a query that can be easily generalizable. A query can be written to join all the products referenced in order_products with the relevant product data from products. This query can then be filtered to return the associations with a single order or group of orders.

This query can be abstracted into a view. Views are named queries that allow for data to be queried from it like a regular table. The view is not physically stored, however. The query in the view is run each time the view itself is referenced in a query.

To return the product data associated with each product_id reference in order_products, we could write a query like this.

select
  op.order_id,
  op.product_id,
  op.product_count,
  p.product_name,
  p.description,
  p.price
from
  order_products op
  join products p on op.product_id = p.product_id

We can add an adjustment to this query to return the total price of each product associated with an order when accounting for the order count.

select
  op.order_id,
  op.product_id,
  op.product_count,
  p.product_name,
  p.description,
  p.price as unit_price,
  op.product_count * p.price as order_price
from
  order_products op
  join products p on op.product_id = p.product_id

We multiply the product count with the unit price to get the total cost of the product within an order. With this query, we can now filter to a specific set of order_id values to return all the products associated with those orders and their total cost!

Creating a view from a query like this, that has the potential to be referenced multiple times, is great database design. We can now add this view to our ORM.

First, we will create a script called db_views.py in the root of the project. This script will be where we store the views that we create for our ORM.

db_views.py:

from alembic_utils.pg_view import PGView

order_line_items = PGView(
    schema="public",
    signature="order_line_items",
    definition="""
select op.order_id ,
	op.product_id,
	op.product_count,
	p.product_name,
	p.description,
	p.price as unit_price,
	op.product_count * p.price as order_price
	from order_products op
join products p
on op.product_id = p.product_id
""",
)

With this code, we first create a PGView class object called order_line_items. This defines a PostgreSQL view also called order_line_items that references the query that we wrote to return the line items (products) associated with orders.

Registering the newly defined entity

We will update alembic/env.py to then register our newly created entity with alembic_utils.

alembic/env.py:

from logging.config import fileConfig

from sqlalchemy import engine_from_config
from sqlalchemy import pool
from alembic_utils.replaceable_entity import register_entities
from alembic import context
from models import Base
from db_views import order_line_items

register_entities([order_line_items])

# this is the Alembic Config object, which provides
# access to the values within the .ini file in use.
config = context.config

# Interpret the config file for Python logging.
# This line sets up loggers basically.
if config.config_file_name is not None:
    fileConfig(config.config_file_name)

# add your model's MetaData object here
# for 'autogenerate' support
# from myapp import mymodel
# target_metadata = mymodel.Base.metadata
target_metadata = Base.metadata

# other values from the config, defined by the needs of env.py,
# can be acquired:
# my_important_option = config.get_main_option("my_important_option")
# ... etc.


def run_migrations_offline() -> None:
    """Run migrations in 'offline' mode.

    This configures the context with just a URL
    and not an Engine, though an Engine is acceptable
    here as well.  By skipping the Engine creation
    we don't even need a DBAPI to be available.

    Calls to context.execute() here emit the given string to the
    script output.

    """
    url = config.get_main_option("sqlalchemy.url")
    context.configure(
        url=url,
        target_metadata=target_metadata,
        literal_binds=True,
        dialect_opts={"paramstyle": "named"},
    )

    with context.begin_transaction():
        context.run_migrations()


def run_migrations_online() -> None:
    """Run migrations in 'online' mode.

    In this scenario we need to create an Engine
    and associate a connection with the context.

    """
    connectable = engine_from_config(
        config.get_section(config.config_ini_section, {}),
        prefix="sqlalchemy.",
        poolclass=pool.NullPool,
    )

    with connectable.connect() as connection:
        context.configure(connection=connection, target_metadata=target_metadata)

        with context.begin_transaction():
            context.run_migrations()


if context.is_offline_mode():
    run_migrations_offline()
else:
    run_migrations_online()

The additions to the code import the newly defined view and register it. This view should now be detected by alembic revision --autogenerate.

Autogenerating a migration

We now autogenerate a revision with the command:

alembic revision --autogenerate -m "Created a view called order_line_items that returns order line items."

This should create a new migration script located at /path_to_your_project/alembic/versions.

/path_to_your_project/alembic/versions/e2ba9d70fc4d_created_a_view_called_order_line_items_.py:

"""Created a view called order_line_items that returns order line items.

Revision ID: e2ba9d70fc4d
Revises: 6e58a26e5c70
Create Date: 2026-02-07 19:26:28.816521

"""
from typing import Sequence, Union

from alembic import op
import sqlalchemy as sa
from alembic_utils.pg_view import PGView
from sqlalchemy import text as sql_text

# revision identifiers, used by Alembic.
revision: str = 'e2ba9d70fc4d'
down_revision: Union[str, None] = '6e58a26e5c70'
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None


def upgrade() -> None:
    # ### commands auto generated by Alembic - please adjust! ###
    public_order_line_items = PGView(
        schema="public",
        signature="order_line_items",
        definition='select op.order_id , \n\top.product_id, \n\top.product_count,\n\tp.product_name, \n\tp.description, \n\tp.price as unit_price, \n\top.product_count * p.price as order_price\n\tfrom order_products op \njoin products p \non op.product_id = p.product_id'
    )
    op.create_entity(public_order_line_items)

    # ### end Alembic commands ###


def downgrade() -> None:
    # ### commands auto generated by Alembic - please adjust! ###
    public_order_line_items = PGView(
        schema="public",
        signature="order_line_items",
        definition='select op.order_id , \n\top.product_id, \n\top.product_count,\n\tp.product_name, \n\tp.description, \n\tp.price as unit_price, \n\top.product_count * p.price as order_price\n\tfrom order_products op \njoin products p \non op.product_id = p.product_id'
    )
    op.drop_entity(public_order_line_items)

    # ### end Alembic commands ###

This migration script now creates a PostgreSQL view with the name order_line_items.

Note

The PGView object here is called public_order_line_items as the autogenerate function uses the schema name as a prefix to the object name. In this case, the schema used is public.

Applying the migration

We now apply the migration with the command:

alembic upgrade head

Connecting to the database shows us that the view has been migrated to the database.

The newly migrated view.

Expanding the data model’s scope

We would like to now expand the data model to track when the attributes of a particular product have been edited. To do this, we will do the following:

Add a last_edited timestamp column to the products table.
Create a function that will update the last_edited column of a table.
Create a trigger that will call the aforementioned function whenever a row of products is edited.

Adding a timestamp column to the `products` table

Amend the data model in models.py to have a last_edited timestamp column.

from sqlalchemy import (
    Column,
    Integer,
    String,
    Float,
    ForeignKey,
    Identity,
    Text,
    DateTime,
    Table,
)
from sqlalchemy.orm import declarative_base, relationship
from sqlalchemy.sql import func

Base = declarative_base()


class Customer(Base):
    __tablename__ = "customers"

    customer_id = Column(Integer, Identity(always=True), primary_key=True)
    first_name = Column(String, nullable=False)
    last_name = Column(String, nullable=False)
    email_address = Column(String, nullable=False)

    orders = relationship(
        "Order",
        back_populates="customer",
        cascade="all, delete-orphan",
    )


class OrderProduct(Base):
    __tablename__ = "order_products"
    order_id = Column(
        Integer,
        ForeignKey("orders.order_id", ondelete="CASCADE"),
        primary_key=True,
    )

    product_id = Column(
        Integer,
        ForeignKey("products.product_id", ondelete="CASCADE"),
        primary_key=True,
    )

    product_count = Column(Integer, server_default="1", nullable=False)
    order = relationship("Order", back_populates="products")
    product = relationship("Product", back_populates="orders")


class Order(Base):
    __tablename__ = "orders"

    order_id = Column(Integer, Identity(always=True), primary_key=True)
    customer_id = Column(
        Integer, ForeignKey("customers.customer_id", ondelete="CASCADE"), nullable=False
    )
    order_date = Column(
        DateTime(timezone=True),
        server_default=func.now(),
        nullable=False,
    )
    customer = relationship(
        "Customer",
        back_populates="orders",
    )
    products = relationship(
        "OrderProduct",
        back_populates="order",
        cascade="all, delete-orphan",
    )


product_tags = Table(
    "product_tags",
    Base.metadata,
    Column(
        "product_id",
        ForeignKey("products.product_id", ondelete="CASCADE"),
        primary_key=True,
    ),
    Column("tag_id", ForeignKey("tags.tag_id", ondelete="CASCADE"), primary_key=True),
)


class Product(Base):
    __tablename__ = "products"

    product_id = Column(Integer, Identity(always=True), primary_key=True)
    product_name = Column(String, nullable=False)
    description = Column(Text)
    price = Column(Float, nullable=False)
    last_edited = Column(
        DateTime(timezone=True), server_default=func.now(), onupdate=func.now()
    )
    orders = relationship(
        "OrderProduct",
        back_populates="product",
        cascade="all, delete-orphan",
    )
    tags = relationship("Tag", secondary=product_tags, back_populates="products")


class Tag(Base):
    __tablename__ = "tags"

    tag_id = Column(Integer, Identity(always=True), primary_key=True)
    name = Column(String, nullable=False, unique=True)
    products = relationship("Product", secondary=product_tags, back_populates="tags")

Note

The onupdate=func.now() parameter for last_edited will update the column when changes are issued through the ORM.

To guarantee database level correctness, we will need to create a trigger as well to guarantee data accuracy even when changes come from outside of any applications that use the ORM.

Generate a revision with alembic --autogenerate.

"""Added a column to products to track timestamps for row-level edits.

Revision ID: eebe110ef9d2
Revises: e2ba9d70fc4d
Create Date: 2026-02-08 16:29:55.536261

"""
from typing import Sequence, Union

from alembic import op
import sqlalchemy as sa


# revision identifiers, used by Alembic.
revision: str = 'eebe110ef9d2'
down_revision: Union[str, None] = 'e2ba9d70fc4d'
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None


def upgrade() -> None:
    # ### commands auto generated by Alembic - please adjust! ###
    op.add_column('products', sa.Column('last_edited', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=True))
    # ### end Alembic commands ###


def downgrade() -> None:
    # ### commands auto generated by Alembic - please adjust! ###
    op.drop_column('products', 'last_edited')
    # ### end Alembic commands ###

We will then apply this migration with the alembic upgrade head command.

Creating a function to update the `last_edited` column of `products`

Create a script called db_functions.py in the project root.

db_functions.py:

from alembic_utils.pg_function import PGFunction

## Creating a function that updates the `last_edited` column of a table
timestamp_update_on_edit = PGFunction(
    schema="public",
    signature="timestamp_update_on_edit()",
    definition="""
RETURNS TRIGGER AS $$ BEGIN NEW.last_edited = now();
RETURN NEW;
END;
$$ language PLPGSQL
""",
)

With this code, we create a PGFunction class object that defines a PostgreSQL function called timestamp_update_on_edit(). When this function is called, the last_edited column is updated to have the time and date of the point in time when it was called.

Creating a trigger to call the timestamp function on row edits

Create a script called db_triggers.py in the project root.

db_triggers.py:

from alembic_utils.pg_trigger import PGTrigger

## Creating a trigger to apply `timestamp_update_on_edit()` to `products` on a row being updated
timestamp_update_apply_products_trigger = PGTrigger(
    schema="public",
    signature="timestamp_update_apply_products_trigger",
    on_entity="public.products",
    is_constraint=False,
    definition="""
BEFORE
UPDATE
  on products FOR EACH ROW EXECUTE FUNCTION timestamp_update_on_edit()
""",
)

This code defines a PGTrigger class object with the signature timestamp_update_apply_products_trigger. When a row is updated on products, this trigger is activated and calls the timestamp_update_on_edit() function, which will update the last_edited column.

Note

In the ORM, as part of the definition of the Product object, the onupdate=func.now() parameter updates the last_edited column when changes are issued through the ORM.

When we create a trigger to perform the timestamp update for products in the database upon a row being edited, this guarantees correctness on a database level even when the changes come outside of the application.

Registering the newly defined entities

We will update alembic/env.py to then register our newly created entities with alembic_utils.

alembic/env.py:

from logging.config import fileConfig

from sqlalchemy import engine_from_config
from sqlalchemy import pool
from alembic_utils.replaceable_entity import register_entities
from alembic import context
from models import Base
from db_views import order_line_items
from db_functions import timestamp_update_on_edit
from db_triggers import timestamp_update_apply_products_trigger

register_entities(
    [
        order_line_items,
        timestamp_update_on_edit,
        timestamp_update_apply_products_trigger,
    ]
)

# this is the Alembic Config object, which provides
# access to the values within the .ini file in use.
config = context.config

# Interpret the config file for Python logging.
# This line sets up loggers basically.
if config.config_file_name is not None:
    fileConfig(config.config_file_name)

# add your model's MetaData object here
# for 'autogenerate' support
# from myapp import mymodel
# target_metadata = mymodel.Base.metadata
target_metadata = Base.metadata

# other values from the config, defined by the needs of env.py,
# can be acquired:
# my_important_option = config.get_main_option("my_important_option")
# ... etc.


def run_migrations_offline() -> None:
    """Run migrations in 'offline' mode.

    This configures the context with just a URL
    and not an Engine, though an Engine is acceptable
    here as well.  By skipping the Engine creation
    we don't even need a DBAPI to be available.

    Calls to context.execute() here emit the given string to the
    script output.

    """
    url = config.get_main_option("sqlalchemy.url")
    context.configure(
        url=url,
        target_metadata=target_metadata,
        literal_binds=True,
        dialect_opts={"paramstyle": "named"},
    )

    with context.begin_transaction():
        context.run_migrations()


def run_migrations_online() -> None:
    """Run migrations in 'online' mode.

    In this scenario we need to create an Engine
    and associate a connection with the context.

    """
    connectable = engine_from_config(
        config.get_section(config.config_ini_section, {}),
        prefix="sqlalchemy.",
        poolclass=pool.NullPool,
    )

    with connectable.connect() as connection:
        context.configure(connection=connection, target_metadata=target_metadata)

        with context.begin_transaction():
            context.run_migrations()


if context.is_offline_mode():
    run_migrations_offline()
else:
    run_migrations_online()

With this update, our newly created function and trigger have been registered. They should now be detected when using autogenerate.

Autogenerating and applying a revision to migrate the newly added entities

Create a revision script with:

alembic revision --autogenerate -m "Created a function to update the last_edited timestamp column, and created a trigger to call this function for the products table."

This should generate a revision file with the following content:

"""Created a function to update the last_edited timestamp column, and created a trigger to call this function for the products table.

Revision ID: 172f9e67a364
Revises: eebe110ef9d2
Create Date: 2026-02-08 16:41:47.178179

"""
from typing import Sequence, Union

from alembic import op
import sqlalchemy as sa
from alembic_utils.pg_function import PGFunction
from sqlalchemy import text as sql_text
from alembic_utils.pg_trigger import PGTrigger
from sqlalchemy import text as sql_text

# revision identifiers, used by Alembic.
revision: str = '172f9e67a364'
down_revision: Union[str, None] = 'eebe110ef9d2'
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None


def upgrade() -> None:
    # ### commands auto generated by Alembic - please adjust! ###
    public_timestamp_update_on_edit = PGFunction(
        schema="public",
        signature="timestamp_update_on_edit()",
        definition='RETURNS TRIGGER AS $$ BEGIN NEW.last_edited = now();\nRETURN NEW;\nEND;\n$$ language PLPGSQL'
    )
    op.create_entity(public_timestamp_update_on_edit)

    public_products_timestamp_update_apply_products_trigger = PGTrigger(
        schema="public",
        signature="timestamp_update_apply_products_trigger",
        on_entity="public.products",
        is_constraint=False,
        definition='BEFORE \nUPDATE \n  on products FOR EACH ROW EXECUTE FUNCTION timestamp_update_on_edit()'
    )
    op.create_entity(public_products_timestamp_update_apply_products_trigger)

    # ### end Alembic commands ###


def downgrade() -> None:
    # ### commands auto generated by Alembic - please adjust! ###
    public_products_timestamp_update_apply_products_trigger = PGTrigger(
        schema="public",
        signature="timestamp_update_apply_products_trigger",
        on_entity="public.products",
        is_constraint=False,
        definition='BEFORE \nUPDATE \n  on products FOR EACH ROW EXECUTE FUNCTION timestamp_update_on_edit()'
    )
    op.drop_entity(public_products_timestamp_update_apply_products_trigger)

    public_timestamp_update_on_edit = PGFunction(
        schema="public",
        signature="timestamp_update_on_edit()",
        definition='RETURNS TRIGGER AS $$ BEGIN NEW.last_edited = now();\nRETURN NEW;\nEND;\n$$ language PLPGSQL'
    )
    op.drop_entity(public_timestamp_update_on_edit)

    # ### end Alembic commands ###

The migration script should create the function and the trigger that we defined in the ORM within the database. After reviewing it, we apply the migration with the command alembic upgrade head.

Once these changes have been migrated, run the following SQL code in the database to get the triggers associated with the products table.

SELECT
    tgname AS trigger_name
FROM
    pg_trigger
WHERE
    tgrelid = 'public.products'::regclass
ORDER BY
    trigger_name;

This should give you the output:

RI_ConstraintTrigger_a_16447
RI_ConstraintTrigger_a_16448
RI_ConstraintTrigger_a_16471
RI_ConstraintTrigger_a_16472
timestamp_update_apply_products_trigger

Indicating the trigger has been successfully migrated. Run the following code to get the functions associated with the public schema:

SELECT
    routine_name
FROM
    information_schema.routines
WHERE
    routine_type = 'FUNCTION'
AND
    routine_schema = 'public';

This should give you the output:

routine_name
timestamp_update_on_edit

showing that our new function has been migrated to the database as well!

We’ve successfully added a view, a function and a trigger to our database via migrations applied from our SQLAlchemy ORM.

Browsing through alembic/versions should give us an idea of the growth of our data model and how it evolves to match the change in scope of our e-commerce workflow.

alembic/versions/
├── 172f9e67a364_created_a_function_to_update_the_last_.py
├── 6e58a26e5c70_created_a_table_for_tags_and_created_a_.py
├── 960969e75871_created_orderproduct_as_an_association_.py
├── a0cf7f5d705d_initial_commit_created_customers_orders_.py
├── e2ba9d70fc4d_created_a_view_called_order_line_items_.py
└── eebe110ef9d2_added_a_column_to_products_to_track_.py

Next Steps

In subsequent blog posts, we will cover:

Applying our migrations to a production environment
Using the ORM as a module when coding a FastAPI server

References

The repo for Alembic Utils.
The documentation for Alembic Utils.

Data Model Version Control with Alembic.

Mon, 26 Jan 2026 00:00:00 +0000

Introduction

As the scope of a data model (and by extension, its downstream APIs) changes, it will need to be updated and expanded to account for this new scope.

When changes are made to a data model, especially to a model that is split across development and production environments, schema drift becomes a constant problem that looms in the background.

Typical coding workflows are managed by version control as an industry standard. Database schemas, however, are typically not submitted to a version control system. As different team members collaborate on a data model split across different environments, the possibility of schema drift gradually grows in an environment where the data model is not tracked in a central repository.

This is where Alembic shines! It is the de-facto migration tool for SQLAlchemy, and is the ideal tool to version control a data model’s development.

In this blog post, we will pick up from the progress in the previous entry in this series and continue to develop our data model. We will build more tables and relationships into our data model, and commit all of these changes to version control using Alembic.

What we’ve already covered

In our previous blog post:

We used SQLAlchemy to create the first iteration of a rudimentary data model, with three tables.
We configured Alembic to connect to a fresh development database and migrated our rudimentary data model.

Please refer to the first post in this series for a detailed explanation of SQLAlchemy and Alembic, and how it is relevant in our workflows here.

What we’ll cover in this post

Creating a many-to-many association between orders and products.
Creating a many-to-many association between products and tags.
Committing all of our changes to version control with Alembic.

Getting started

At this point, we have a rudimentary data model with three tables, and only two relationships.

There’s orders,customers and products, with a one-to-many relationship between customers and orders, and a many-to-one relationship between orders and customers.

Our initial data model.

The classes for these tables in our ORM were defined as follows:

class Customer(Base):
    __tablename__ = "customers"

    customer_id = Column(
        Integer, Identity(always=True), primary_key=True
    )
    first_name = Column(String, nullable=False)
    last_name = Column(String, nullable=False)
    email_address = Column(String, nullable=False)

    orders = relationship(
        "Order",
        back_populates="customer",
        cascade="all, delete-orphan",
    )

class Order(Base):
    __tablename__ = "orders"

    order_id = Column(
        Integer, Identity(always=True), primary_key=True
    )
    customer_id = Column(
        Integer,
        ForeignKey("customers.customer_id", ondelete="CASCADE"),
        nullable=False
    )
    order_date = Column(
        DateTime(timezone=True),
        server_default=func.now(),
        nullable=False,
    )

    customer = relationship(
        "Customer",
        back_populates="orders"
    )

class Product(Base):
    __tablename__ = "products"

    product_id = Column(
        Integer, Identity(always=True), primary_key=True
    )
    product_name = Column(
        String, nullable=False
    )
    description = Column(Text)
    price = Column(Float, nullable=False)

Note

We generated an initial migration, but right now, this migration environment lives locally. We need to push this to a GitHub repository!

The data model at the end of the first blog post has been pushed to GitHub and can be found here.

This repository will evolve along with the blog! Every change we make moving forward will be committed to version control.

There are a lot of changes we need to make to make this data model usable. To start with:

A connection needs to be built between orders and products. A single order can have multiple products, and a single product can be associated with multiple orders.
Products need to be associated with tags to enable better categorization within the product catalog. Each product can be associated with multiple tags, and a single tag can be associated with multiple products.

Tip

This change in relationship between orders and products is a many-to-many relationship!

When we expand our data model to include tags, the relationship between tags and products will also be a many-to-many relationship.

Let’s begin implementing this change in scope within the data model. With each step, we will also commit our work to version control using Alembic.

Many-to-many relationship between `orders` and `products`

We want to build a many-to-many relationship between orders and products. We also want to expand this relationship to track the count of each product in an order.

To accomplish that, we will create an association table.

Tip

Association tables are also referred to as join tables, junction tables or cross-reference tables.

An association table maps two (or more) tables together by using their primary keys as foreign keys. Each foreign key forms a many-to-one relationship between the association table and the individual data table. An association table creates a two-way link between the tables that represent each entity.

The best way to demonstrate this is by example! Let’s begin by creating an association table to group together the products associated with each order.

To generate an association table, the following changes need to be made to models.py. Additions have been highlighted.

models.py:

from sqlalchemy import (
    Column,
    Integer,
    String,
    Float,
    ForeignKey,
    Identity,
    Text,
    DateTime,
)
from sqlalchemy.orm import declarative_base, relationship
from sqlalchemy.sql import func

Base = declarative_base()


class Customer(Base):
    __tablename__ = "customers"

    customer_id = Column(Integer, Identity(always=True), primary_key=True)
    first_name = Column(String, nullable=False)
    last_name = Column(String, nullable=False)
    email_address = Column(String, nullable=False)

    orders = relationship(
        "Order",
        back_populates="customer",
        cascade="all, delete-orphan",
    )


class OrderProduct(Base):
    __tablename__ = "order_products"
    order_id = Column(
        Integer,
        ForeignKey("orders.order_id", ondelete="CASCADE"),
        primary_key=True,
    )

    product_id = Column(
        Integer,
        ForeignKey("products.product_id", ondelete="CASCADE"),
        primary_key=True,
    )

    product_count = Column(Integer, server_default="1", nullable=False)
    order = relationship("Order", back_populates="products")
    product = relationship("Product", back_populates="orders")


class Order(Base):
    __tablename__ = "orders"

    order_id = Column(Integer, Identity(always=True), primary_key=True)
    customer_id = Column(
        Integer, ForeignKey("customers.customer_id", ondelete="CASCADE"), nullable=False
    )
    order_date = Column(
        DateTime(timezone=True),
        server_default=func.now(),
        nullable=False,
    )
    customer = relationship(
        "Customer",
        back_populates="orders",
    )
    products = relationship(
        "OrderProduct",
        back_populates="order",
        cascade="all, delete-orphan",
    )


class Product(Base):
    __tablename__ = "products"

    product_id = Column(Integer, Identity(always=True), primary_key=True)
    product_name = Column(String, nullable=False)
    description = Column(Text)
    price = Column(Float, nullable=False)
    orders = relationship(
        "OrderProduct",
        back_populates="product",
        cascade="all, delete-orphan",
    )

Creating the association table

We create a class to define the association table, since the association table contains an additional column beyond just the associations with Order and Product. This table is OrderProduct.

Theorder_id and product_id columns in this table are designated as foreign keys.

We then create associations between OrderProduct and the entity tables using the relationship parameter. OrderProducts has relationships built to both Order and Product.

Explaining the relationship between `Order` and `Product`

There is no direct relationship between Order and Product. This relationship is mediated by the OrderProduct class, which is an association table that decomposes the relationship between Order and Product.

A single instance of an Order can belong to multiple rows of OrderProduct.

A single instance of a Product can belong to multiple rows of OrderProduct.

However, every instance of OrderProduct can only have:

A single Order
A single Product.

In essence, the many-to-many relationship between Order and Product is abstracted into being indirect via OrderProduct. Each row in OrderProduct represents a single product within a single order, along with additional metadata about that association, such as the product count for that order.

The following code snippets establish this indirect relationship between Order and Product.

OrderProduct:

    order = relationship("Order", back_populates="products")
    product = relationship("Product", back_populates="orders")

Order:

products = relationship(
        "OrderProduct",
        back_populates="order",
        cascade="all, delete-orphan",
    )

Product:

orders = relationship(
        "OrderProduct",
        back_populates="product",
        cascade="all, delete-orphan",
    )

For the OrderProduct Class, this code:

Creates a relationship called order, that points towards the Order class. This now establishes a many-to-one relationship between OrderProduct and Order. Each instance of OrderProduct references exactly one Order.
Creates a relationship called product, that points towards the Product class. This now establishes a many-to-one relationship between OrderProduct and Product. Each instance of OrderProduct references exactly one Product.

For the Order Class, this code:

Creates a relationship called products, that points towards the OrderProduct class. This now establishes a one-to-many relationship between Order and OrderProducts. A single Order can be referenced by multiple instances of OrderProduct.

Tip

Even though this relationship points to OrderProduct, it is named products. This is intentional, and it refers to the conceptual representation of this relationship, not the literal schema itself.

Conceptually: An order has multiple products.
Relationally: An Order can be referenced by multiple OrderProduct rows.

This relationship is named products to reflect the conceptual link between orders and products, and not the direct relational link between Orders and OrderProducts.

Remember that there is no direct connection between Order and Product in the data model!

For the Product Class, this code:

Creates a relationship called orders, that points towards the OrderProduct class. This now establishes a one-to-many relationship between Product and OrderProducts. A single Product can be referenced by multiple instances of OrderProduct.
Similar to the products relationship defined in Order, this is a conceptual representation, which is why it is called orders.

By wiring these connections, we abstract away the many-to-many relationship between Orders and Products.

Tip

The back_populates parameter establishes a bidirectional link between the two ORM relationships. It ensures that objects on both sides of each relationship synchronize in-Python state changes.

Auto-generating migrations

We now have a end state of our data model defined in the ORM. To generate a migration, we need to allow Alembic to compare the current state of the database against the ORM, and have it automatically generate a migration script that we must review before applying.

We configured and set up Alembic in the previous blog post, so this time, we just need to run the following command:

alembic revision --autogenerate -m "Created OrderProduct as an association table to track Order-Product association."

This should autogenerate a migration script, located at /path_to_your_project/alembic/versions/960969e75871_created_orderproduct_as_an_association_.py. The versions directory will have the following content:

alembic/versions/
└── a0cf7f5d705d_initial_commit_created_customers_orders_.py
└── 960969e75871_created_orderproduct_as_an_association_.py

The versions directory now contains two migration scripts! One is the migration script for our initial commit in the previous blog post, and one is the newly generated script for creating the OrderProducts table.

Note

In the previous blog post, the initial commit migration script had the ID de5f32c11361, and not a0cf7f5d705d.

The reason for this change is that I created a new revision script for the initial migration, and the revision ID is randomly generated!

Other aspects of the migration script are otherwise exactly the same, and the scripts are otherwise functionally identical.

The newly generated migration should have the following content:

"""Created OrderProduct as an association table to track Order-Product association.

Revision ID: 960969e75871
Revises: a0cf7f5d705d
Create Date: 2026-01-26 17:30:18.314422

"""
from typing import Sequence, Union

from alembic import op
import sqlalchemy as sa


# revision identifiers, used by Alembic.
revision: str = '960969e75871'
down_revision: Union[str, None] = 'a0cf7f5d705d'
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None


def upgrade() -> None:
    # ### commands auto generated by Alembic - please adjust! ###
    op.create_table('order_products',
    sa.Column('order_id', sa.Integer(), nullable=False),
    sa.Column('product_id', sa.Integer(), nullable=False),
    sa.Column('product_count', sa.Integer(), server_default='1', nullable=False),
    sa.ForeignKeyConstraint(['order_id'], ['orders.order_id'], ondelete='CASCADE'),
    sa.ForeignKeyConstraint(['product_id'], ['products.product_id'], ondelete='CASCADE'),
    sa.PrimaryKeyConstraint('order_id', 'product_id')
    )
    # ### end Alembic commands ###


def downgrade() -> None:
    # ### commands auto generated by Alembic - please adjust! ###
    op.drop_table('order_products')
    # ### end Alembic commands ###

Reviewing the auto-generated migration

Remember that Alembic’s documentation states,

It is always necessary to manually review and correct the candidate migrations that autogenerate produces.

Reviewing our migration script, it looks like:

Alembic has created a table called order_products.
order_id and product_id are both foreign keys. They are the primary keys from the tables orders and products respectively.
order_id and product_id are also primary keys for the order_products table.
order_products has a column called product_count, with a default value of 1.

Tip

order_id and product_id are both selected as primary keys to ensure that duplicate rows won’t be persisted within the order_products regardless of issues on the application side.

This migration script looks good! We can go ahead and apply it to the database.

Why does the migration script look so sparse compared to the complex ORM relationships?

Order:

products = relationship(
        "OrderProduct",
        back_populates="order",
        cascade="all, delete-orphan",
    )

This code defines the behavior within the ORM, and will become relevant when you interact with the database via SQLAlchemy. It defines the behaviour of these classes within Python and also documents the relationship on a conceptual level. It doesn’t create anything within the database.

On the database level, it is really straightforward to build this relationship, which is why the migration script seems so sparse in comparison. Within the migration script, on the database level, we’re just creating order_products as a table with foreign keys pointing to the parent entity tables. The relational aspect of the data model is much lower level than the conceptual data model, which is what we define in the ORM.

The ORM helps us build a conceptual data model with rich, complex relationships as seen in our code. Alembic reads the ORM and generates migrations to create a lower-level relational data model from the ORM.

Applying the migration

We can then apply the migration script with the command:

alembic upgrade head

This should give us the following output:

INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
INFO  [alembic.runtime.migration] Running upgrade a0cf7f5d705d -> 960969e75871, Created OrderProduct as an association table to track Order-Product association.

Connecting to the database shows the following ERD:

Our newly iterated data model!

We’ve successfully created the association table, and we have built an indirect many-to-many association between Orders and Products! When we examine the contents of the alembic_version table, it now contains a single row with the value 960969e75871, which is the revision it has applied. It applied this one specifically because we had alembic upgrade to the head version, which is the latest version.

Committing to GitHub

At this point, we’ve made changes to models.py and we have a new migration script called 960969e75871_created_orderproduct_as_an_association_.py. Both these changes need to be pushed GitHub. I recommend committing and pushing these changes as a single commit with the same commit message that we used for auto-generating a migration script.

Remember to always commit migration scripts together with model changes.

Further iterating

Let’s expand this data model more. A great addition to this data model would be the ability to create and assign tags to products for greater searchability.

To start with, these tags will be really simple. A tag will be a text-based descriptor that can be applied to any product. For example, a laptop as a product might have a tag called ‘computer’ assigned to it.

To reflect this, we will create a table containing tags, and build a many-to-many relationship between products and tags. Each product can have multiple tags, and each tag can be assigned to multiple products. For this, like before, we will build an association table.

We will do the following:

Create a class for Tags in the ORM
Create an association table called product_tags to associate products and tags
Update the relationships for Products to reflect the new relationship to the Tags class.

Tip

In the interest of brevity, this section won’t be as thoroughly explanatory as the section for creating OrderProducts. This process is very similar to what we’ve covered thus far!

Creating a `Tags` class

models.py (Changes to code have been highlighted):

from sqlalchemy import (
    Column,
    Integer,
    String,
    Float,
    ForeignKey,
    Identity,
    Text,
    DateTime,
    Table,
)
from sqlalchemy.orm import declarative_base, relationship
from sqlalchemy.sql import func

Base = declarative_base()


class Customer(Base):
    __tablename__ = "customers"

    customer_id = Column(Integer, Identity(always=True), primary_key=True)
    first_name = Column(String, nullable=False)
    last_name = Column(String, nullable=False)
    email_address = Column(String, nullable=False)

    orders = relationship(
        "Order",
        back_populates="customer",
        cascade="all, delete-orphan",
    )


class OrderProduct(Base):
    __tablename__ = "order_products"
    order_id = Column(
        Integer,
        ForeignKey("orders.order_id", ondelete="CASCADE"),
        primary_key=True,
    )

    product_id = Column(
        Integer,
        ForeignKey("products.product_id", ondelete="CASCADE"),
        primary_key=True,
    )

    product_count = Column(Integer, server_default="1", nullable=False)
    order = relationship("Order", back_populates="products")
    product = relationship("Product", back_populates="orders")


class Order(Base):
    __tablename__ = "orders"

    order_id = Column(Integer, Identity(always=True), primary_key=True)
    customer_id = Column(
        Integer, ForeignKey("customers.customer_id", ondelete="CASCADE"), nullable=False
    )
    order_date = Column(
        DateTime(timezone=True),
        server_default=func.now(),
        nullable=False,
    )
    customer = relationship(
        "Customer",
        back_populates="orders",
    )
    products = relationship(
        "OrderProduct",
        back_populates="order",
        cascade="all, delete-orphan",
    )


product_tags = Table(
    "product_tags",
    Base.metadata,
    Column(
        "product_id",
        ForeignKey("products.product_id", ondelete="CASCADE"),
        primary_key=True,
    ),
    Column("tag_id", ForeignKey("tags.tag_id", ondelete="CASCADE"), primary_key=True),
)


class Product(Base):
    __tablename__ = "products"

    product_id = Column(Integer, Identity(always=True), primary_key=True)
    product_name = Column(String, nullable=False)
    description = Column(Text)
    price = Column(Float, nullable=False)
    orders = relationship(
        "OrderProduct",
        back_populates="product",
        cascade="all, delete-orphan",
    )
    tags = relationship("Tag", secondary=product_tags, back_populates="products")


class Tag(Base):
    __tablename__ = "tags"

    tag_id = Column(Integer, Identity(always=True), primary_key=True)
    name = Column(String, nullable=False, unique=True)
    products = relationship("Product", secondary=product_tags, back_populates="tags")

Note

The product_tags implementation here is different from the OrderProducts class.

This is because product_tags is a straightforward, simple association table, which is what the documentation for SQLAlchemy says to use when your association table has no metadata.

This secondary table pattern is only usable when all you have in the table are foreign keys. product_tags has no attributes apart from its foreign keys, so we use the association table with the secondary table pattern.

The reason OrderProducts was mapped as a class was because we have additional metadata beyond just the foreign keys in that table.

OrderProducts goes from just a simple association table to a full entity in it’s own right when you add even a single extra column beyond the foreign keys. The recommended approach for adding metadata to an association table is to map the association table directly to a full class.

Generating a migration

We create an auto-generated migration script with the following command:

alembic revision --autogenerate -m "Created a table for tags, and created a table called product_tags as an association table between products and tags."

Reviewing the migration script

The contents of the migration script are:

"""Created a table for tags, and created a table called product_tags as an association table between products and tags.

Revision ID: 6e58a26e5c70
Revises: 960969e75871
Create Date: 2026-01-26 18:32:43.007353

"""
from typing import Sequence, Union

from alembic import op
import sqlalchemy as sa


# revision identifiers, used by Alembic.
revision: str = '6e58a26e5c70'
down_revision: Union[str, None] = '960969e75871'
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None


def upgrade() -> None:
    # ### commands auto generated by Alembic - please adjust! ###
    op.create_table('tags',
    sa.Column('tag_id', sa.Integer(), sa.Identity(always=True), nullable=False),
    sa.Column('name', sa.String(), nullable=False),
    sa.PrimaryKeyConstraint('tag_id'),
    sa.UniqueConstraint('name')
    )
    op.create_table('product_tags',
    sa.Column('product_id', sa.Integer(), nullable=False),
    sa.Column('tag_id', sa.Integer(), nullable=False),
    sa.ForeignKeyConstraint(['product_id'], ['products.product_id'], ondelete='CASCADE'),
    sa.ForeignKeyConstraint(['tag_id'], ['tags.tag_id'], ondelete='CASCADE'),
    sa.PrimaryKeyConstraint('product_id', 'tag_id')
    )
    # ### end Alembic commands ###


def downgrade() -> None:
    # ### commands auto generated by Alembic - please adjust! ###
    op.drop_table('product_tags')
    op.drop_table('tags')
    # ### end Alembic commands ###

This migration script (with the revision ID 6e58a26e5c70) looks good!

You should now have three scripts inside alembic/versions.

alembic/versions/
├── 6e58a26e5c70_created_a_table_for_tags_and_created_a_.py
├── 960969e75871_created_orderproduct_as_an_association_.py
└── a0cf7f5d705d_initial_commit_created_customers_orders_.py

Applying the migration script

Apply the migration script by running:

alembic upgrade head

Connecting to the database shows the following ERD:

Tags are now associated with Products!

We’ve successfully built a connection between Products and Tags via an association table!

Browsing through alembic/versions should give us an idea of the growth of our data model and how it evolves to match the change in scope of our e-commerce workflow. With these three migration scripts, we’ve gone from a rudimentary data model to a more complex one, while being able to track how the data model has evolved from its conception.

Next Steps

In subsequent blog posts, we will cover:

Using an Async engine for asynchronous database connections
Using the alembic_utils library to incorporate views, functions and triggers into the version control system.
Configuring Alembic to connect to a production environment, and seamlessly bring the production environment’s schema up-to-date with our final revision.

References

SQLAlchemy’s documentation on many-to-many relationships.
Alembic’s documentation on auto-generating migrations.

Relational Data Model design with SQLAlchemy.

Tue, 13 Jan 2026 00:00:00 +0000

Introduction

Data Modeling

Data modeling is the process of creating a representation of data that defines the way it is structured and used in complex systems. When it comes to relational databases, designing a normalized data model is essential for efficient database operation, and to make your data consistent and clean.

With a fully normalized data model, data in your relational database becomes:

Understandable

A good data model can decompose the complexity of real-world systems and the data they generate into a relational model that is easy to read and comprehend, and standardizes the relationship of one data domain with every other data domain.

Scalable

A well defined and normalized data model becomes scalable, and allows for sustainable development of data-driven solutions for users of your database as the scope of your data grows.

Modular

A database with a well designed and thoroughly documented data model becomes easy to use by downstream teams such as API designers and front-end developers, minimizing the communication needed for these teams to function independently. Good design will naturally flow downstream of a properly normalized database.

Efficient data model design can help your database be a bedrock for your fellow team members to rely on.

SQLAlchemy

SQLAlchemy is a Python SQL toolkit and ORM (Object Relational Mapper) that allows Python developers to work with relational databases using the Python language. SQLAlchemy is indispensable if you’re a Python developer looking to create a relational data model for your database. The two most significant components of SQLAlchemy are it’s Object Relational Mapper (ORM) and SQLAlchemy Core.

SQLAlchemy Core

SQLALchemy Core is the foundation of SQLAlchemy, and is independent of the ORM. It provides the connectivity to the database, and by allowing for the construction of SQL expressions that can then be executed against a target database, enabling interaction with a database to in the form of queries.

SQLAlchemy ORM

The SQLAlchemy ORM (Object Relational Mapper) uses Core as a foundation. The ORM will be the bulk of what we discuss in this blog post. The ORM builds on Core to help create user-defined Python classes that can be mapped into database tables. The ORM is what allows SQLAlchemy to define a data model for a relational database.

The major components of SQLAlchemy.Taken from the SQLAlchemy documentation.

Alembic

Alembic is a database migration tool written by the author of SQLAlchemy. It helps create a version-controlled system of database migrations that can be used to upgrade a target database to any version of your data model. It uses SQLAlchemy as the underlying engine. By executing migrations in a sequential order, databases can be upgraded and downgraded across versions, even when you are building from scratch.

Alembic is a great way to test your migrations and schema design in a development environment before transferring these migrations to a production environment. An empty database environment can be converted into a database with a production ready schema with just a single command using Alembic.

What we’ll cover

In this blog post, we will cover how you can begin using SQLAlchemy and Alembic to start developing the first iteration of your data model.

We will do the following:

Create a virtual environment with SQLAlchemy and Alembic installed
Initialize Alembic
Design a simple, rudimentary data model with three tables
Configure Alembic to connect to your database
Utilize Alembic to generate a migration script
Migrate your initial data model to the database for the first time

In future posts, we will cover how you can use Alembic to generate database migrations and help grow your database within a version-controlled system, and how this data model can then be plugged into a FastAPI server as a module to help design a modern API service.

Prerequisites

The code in this blog post was written with Python 3.13.1, Alembic 1.14.0 and SQLAlchemy 2.0.36.

You will need the following prerequisites:

A PostgreSQL server initialized and running, with a database that has been initialized but is otherwise empty. We will refer to this server as development from here.
An installation of mamba,micromamba or conda as a package manager to create a new environment. I like to use micromamba. You can find instructions on how to install micromamba here.

We will create a new virtual environment using Python 3.13.1 as the pinned version. Create an environment named data_model as follows:

micromamba create -n data_model python=3.13.1 sqlalchemy=2.0.36 alembic=1.14.0 psycopg2=2.9.9 -y

This will create a micromamba environment with the pinned versions of Python and SQLAlchemy that can then be used to follow this tutorial. This environment can be activated with the command micromamba activate data_model.

Note

Using a virtual environment is a good way to keep your base environment uncluttered and free of broken dependencies. It is good practice to begin any Python project with a virtual environment, even for development workflows. Other options for virtual environment creation include uv and Poetry.

Lets now get into actually creating some data models!

Getting Started

Setting up the Alembic environment

Before we can start working with our PostgreSQL database, we will first set up the migration environment using Alembic. The reason we set this up first is because we will use Alembic’s config files to connect to our database first before we can begin creating our data model. Alembic uses SQLAlchemy core’s Engine object as a dependency when connecting to a database.

In the root of your project directory, run:

alembic init alembic

This will generate a directory of scripts. The root of your project directory will look like this:

.
├── alembic
│   ├── README
│   ├── env.py
│   ├── script.py.mako
│   └── versions
└── alembic.ini

The directory now includes these files of importance:

`alembic.ini`

This is Alembic’s main configuration file. When Alembic is run, it looks in the directory for this file. This file is where you will add the SQLAlchemy URL to connect to your database. You can also define multiple environments to run migrations in.

For now we will go with the boilerplate file generated by the alembic init file. Here is what the default file should look like:

# A generic, single database configuration.

[alembic]
# path to migration scripts
# Use forward slashes (/) also on windows to provide an os agnostic path
script_location = alembic

# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
# Uncomment the line below if you want the files to be prepended with date and time
# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
# for all available tokens
# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s

# sys.path path, will be prepended to sys.path if present.
# defaults to the current working directory.
prepend_sys_path = .

# timezone to use when rendering the date within the migration file
# as well as the filename.
# If specified, requires the python>=3.9 or backports.zoneinfo library.
# Any required deps can installed by adding `alembic[tz]` to the pip requirements
# string value is passed to ZoneInfo()
# leave blank for localtime
# timezone =

# max length of characters to apply to the "slug" field
# truncate_slug_length = 40

# set to 'true' to run the environment during
# the 'revision' command, regardless of autogenerate
# revision_environment = false

# set to 'true' to allow .pyc and .pyo files without
# a source .py file to be detected as revisions in the
# versions/ directory
# sourceless = false

# version location specification; This defaults
# to alembic/versions.  When using multiple version
# directories, initial revisions must be specified with --version-path.
# The path separator used here should be the separator specified by "version_path_separator" below.
# version_locations = %(here)s/bar:%(here)s/bat:alembic/versions

# version path separator; As mentioned above, this is the character used to split
# version_locations. The default within new alembic.ini files is "os", which uses os.pathsep.
# If this key is omitted entirely, it falls back to the legacy behavior of splitting on spaces and/or commas.
# Valid values for version_path_separator are:
#
# version_path_separator = :
# version_path_separator = ;
# version_path_separator = space
# version_path_separator = newline
version_path_separator = os  # Use os.pathsep. Default configuration used for new projects.

# set to 'true' to search source files recursively
# in each "version_locations" directory
# new in Alembic version 1.10
# recursive_version_locations = false

# the output encoding used when revision files
# are written from script.py.mako
# output_encoding = utf-8

sqlalchemy.url = driver://user:pass@localhost/dbname


[post_write_hooks]
# post_write_hooks defines scripts or Python functions that are run
# on newly generated revision scripts.  See the documentation for further
# detail and examples

# format using "black" - use the console_scripts runner, against the "black" entrypoint
# hooks = black
# black.type = console_scripts
# black.entrypoint = black
# black.options = -l 79 REVISION_SCRIPT_FILENAME

# lint with attempts to fix using "ruff" - use the exec runner, execute a binary
# hooks = ruff
# ruff.type = exec
# ruff.executable = %(here)s/.venv/bin/ruff
# ruff.options = --fix REVISION_SCRIPT_FILENAME

# Logging configuration
[loggers]
keys = root,sqlalchemy,alembic

[handlers]
keys = console

[formatters]
keys = generic

[logger_root]
level = WARNING
handlers = console
qualname =

[logger_sqlalchemy]
level = WARNING
handlers =
qualname = sqlalchemy.engine

[logger_alembic]
level = INFO
handlers =
qualname = alembic

[handler_console]
class = StreamHandler
args = (sys.stderr,)
level = NOTSET
formatter = generic

[formatter_generic]
format = %(levelname)-5.5s [%(name)s] %(message)s
datefmt = %H:%M:%S

To begin with, we will substitute the sqlalchemy.url parameter for the alembic section with the connection string used for our database. As an example, the following is a dummy connection string.

sqlalchemy.url = postgresql://nk_dev:placeholder_password@localhost/development

In the above code snippet:

The database driver is postgresql
The database username is nk_dev
The password of the user is placeholder_password
The database host is localhost
The name of the database is development

Warning

The above is an example to begin testing with. This isn’t the ideal way to store your PostgreSQL server connection details. Ideally you manage them with a key vault or via injection of environment variables at the time of virtual environment activation. Remember to never include the alembic.ini file within version control. Always have your config file (alembic.ini) added to .gitignore.

Here are the contents of the .gitignore: file:

alembic.ini

A more in-depth explanation of the alembic.ini file can be found in the official documentation here.

The `alembic` directory

This directory is the home of the migration environment. The relevant contents of this directory include:

env.py

This is a Python script that can be run when the migration tool is invoked. You can do some cool stuff with this script, like registering entities like views, functions and triggers, and also generating filters to ignore tables that you don’t want to migrate with Alembic.

versions/

This directory holds the individual version scripts. This directory will have the scripts in it run sequentially when upgrading to or downgrading to a particular version of your database. As you begin generating migrations and applying them, this folder will grow. Each migration will become it’s own script, containing both an upgrade and a downgrade parameter for that particular version.

Now that all of this is finally sorted, we can get to creating basic data models!

Creating a file for our data models

Create a file in the project directory called models.py. This file will be where we store our user-defined Python classes that will then be mapped into database tables in the database using Alembic to run the actual migrations. Let’s start with a simple scenario where we have commerce data for customers, products and orders. Each customer can submit multiple orders, and each order can have several products in it.

As a basic assumption, this initial data model isn’t bad, but there is plenty of room for improvement and refinement in the future. Let’s start with defining these three tables as Python classes first.

We will build a one-to-many relationship between customers and orders, since every customer can have many orders, and each order belongs to just one customer. We will build a table to define our products as well.

Note

In future posts, we will expand on this rudimentary data model, building in connections between products and orders. We will also incorporate additional features into our data model, such as views, functions and triggers.

This is what your models.py file will look like:

from sqlalchemy import (
    Column,
    Integer,
    String,
    Float,
    ForeignKey,
    Identity,
    Text,
    DateTime,
)
from sqlalchemy.orm import declarative_base, relationship
from sqlalchemy.sql import func

Base = declarative_base()

class Customer(Base):
    __tablename__ = "customers"

    customer_id = Column(
        Integer, Identity(always=True), primary_key=True
    )
    first_name = Column(String, nullable=False)
    last_name = Column(String, nullable=False)
    email_address = Column(String, nullable=False)

    orders = relationship(
        "Order",
        back_populates="customer",
        cascade="all, delete-orphan",
    )

class Order(Base):
    __tablename__ = "orders"

    order_id = Column(
        Integer, Identity(always=True), primary_key=True
    )
    customer_id = Column(
        Integer,
        ForeignKey("customers.customer_id", ondelete="CASCADE"),
        nullable=False
    )
    order_date = Column(
        DateTime(timezone=True),
        server_default=func.now(),
        nullable=False,
    )

    customer = relationship(
        "Customer",
        back_populates="orders"
    )

class Product(Base):
    __tablename__ = "products"

    product_id = Column(
        Integer, Identity(always=True), primary_key=True
    )
    product_name = Column(
        String, nullable=False
    )
    description = Column(Text)
    price = Column(Float, nullable=False)

With these classes in models.py, We have created the following objects: Customer, Order and Product.

`Customer`:

This object describes the attributes of the customers. The customer_id column is the primary key of the table, and we initialize it as a serialized integer. We have added some additional parameters to the column (which also apply to the primary keys of every other table).

always=True means the identity is always generated (even if a value is provided)

first_name,last_name and email_address are string columns that cannot be null, and need to be present in the data. This code snippet:

    orders = relationship(
        "Order",
        back_populates="customer",
        cascade="all, delete-orphan",
    )

establishes a one-to-many relationship between customers and orders.

The cascade behavior ("all", "delete-orphan") means that when a instance of customer is deleted, all the associated orders (Orders that used the ID of the deleted customer as a foreign key) will also be deleted, and these changes will cascade downwards to any future child table of the orders table.

`Order`:

This object describes the attributes of each individual order. order_id is the primary key of this table. We designate the customer_id column as a foreign key from the customers table with this code snippet:

  customer_id = Column(
        Integer,
        ForeignKey("customers.customer_id", ondelete="CASCADE"),
        nullable=False
    )

The foreign key enforces referential integrity, while nullable=False ensures that each order must be associated with a customer. Orders that are associated with non-existent customers, or have no customer at all, will not be possible.

We also establish a many-to-one relationship between orders and customers using the following code snippet:

  customer = relationship(
        "Customer",
        back_populates="orders"
    )

`Product`:

This object describes the attributes of each individual product. product_id is the primary key of this table, and this table does not have any relationships with any other tables yet. This data model is currently incomplete, but it is a great starting point at which to begin the development and migration of our data model.

With this file complete, our rudimentary data model has been initialized. Without migrating these changes over to the database, however, these will only live as Python classes, and not as database objects.

Doing our first database migration.

The vast majority of database migration workflows with Alembic are done by auto-generating migration scripts. To begin auto-generating migration scripts, we will first need to connect Alembic to the database, and then point alembic towards the target metadata we would like to migrate the data model to.

Alembic can be configured to connect to the database (pointed to be the sqlalchemy.url parameter in the alembic.ini file). For Alembic to compare the state of the database against our target metadata, we will edit alembic/env.py so that Alembic can access the table metadata object that contains the target. Configuring Alembic therefore has two components:

Connecting Alembic to the database, so that it can compare the state of the database against the target metadata.
Importing the target metadata, so that Alembic knows what to compare the state of the database against.

Once alembic/env.py is configured, Alembic can then auto generate the “obvious” migrations based on a comparison. In this case, we want it to compare the empty database against our models, and then auto-generate migrations that we can then review and modify before applying.

We have already defined the database connection string in our configuration file. We will begin working with the env.py to access the table metadata object that contains the target.

Editing `env.py` to import our models

The following is the default content of alembic/env.py. The sections that we will edit have been highlighted.

from logging.config import fileConfig

from sqlalchemy import engine_from_config
from sqlalchemy import pool

from alembic import context

# this is the Alembic Config object, which provides
# access to the values within the .ini file in use.
config = context.config

# Interpret the config file for Python logging.
# This line sets up loggers basically.
if config.config_file_name is not None:
    fileConfig(config.config_file_name)

# add your model's MetaData object here
# for 'autogenerate' support
# from myapp import mymodel
# target_metadata = mymodel.Base.metadata
target_metadata = None

# other values from the config, defined by the needs of env.py,
# can be acquired:
# my_important_option = config.get_main_option("my_important_option")
# ... etc.


def run_migrations_offline() -> None:
    """Run migrations in 'offline' mode.

    This configures the context with just a URL
    and not an Engine, though an Engine is acceptable
    here as well.  By skipping the Engine creation
    we don't even need a DBAPI to be available.

    Calls to context.execute() here emit the given string to the
    script output.

    """
    url = config.get_main_option("sqlalchemy.url")
    context.configure(
        url=url,
        target_metadata=target_metadata,
        literal_binds=True,
        dialect_opts={"paramstyle": "named"},
    )

    with context.begin_transaction():
        context.run_migrations()


def run_migrations_online() -> None:
    """Run migrations in 'online' mode.

    In this scenario we need to create an Engine
    and associate a connection with the context.

    """
    connectable = engine_from_config(
        config.get_section(config.config_ini_section, {}),
        prefix="sqlalchemy.",
        poolclass=pool.NullPool,
    )

    with connectable.connect() as connection:
        context.configure(
            connection=connection, target_metadata=target_metadata
        )

        with context.begin_transaction():
            context.run_migrations()


if context.is_offline_mode():
    run_migrations_offline()
else:
    run_migrations_online()

First, we will import the models.py script. Edit the highlighted snippet to add an import statement.

from models import Base

Then we will replace the target_metadata value with the metadata of our data model. We will change the second highlighted section to:

target_metadata = Base.metadata

Our env.py file should now look like the following, with our changes being highlighted.

from logging.config import fileConfig

from sqlalchemy import engine_from_config
from sqlalchemy import pool

from alembic import context
from models import Base

# this is the Alembic Config object, which provides
# access to the values within the .ini file in use.
config = context.config

# Interpret the config file for Python logging.
# This line sets up loggers basically.
if config.config_file_name is not None:
    fileConfig(config.config_file_name)

# add your model's MetaData object here
# for 'autogenerate' support
# from myapp import mymodel
# target_metadata = mymodel.Base.metadata
target_metadata = Base.metadata

# other values from the config, defined by the needs of env.py,
# can be acquired:
# my_important_option = config.get_main_option("my_important_option")
# ... etc.


def run_migrations_offline() -> None:
    """Run migrations in 'offline' mode.

    This configures the context with just a URL
    and not an Engine, though an Engine is acceptable
    here as well.  By skipping the Engine creation
    we don't even need a DBAPI to be available.

    Calls to context.execute() here emit the given string to the
    script output.

    """
    url = config.get_main_option("sqlalchemy.url")
    context.configure(
        url=url,
        target_metadata=target_metadata,
        literal_binds=True,
        dialect_opts={"paramstyle": "named"},
    )

    with context.begin_transaction():
        context.run_migrations()


def run_migrations_online() -> None:
    """Run migrations in 'online' mode.

    In this scenario we need to create an Engine
    and associate a connection with the context.

    """
    connectable = engine_from_config(
        config.get_section(config.config_ini_section, {}),
        prefix="sqlalchemy.",
        poolclass=pool.NullPool,
    )

    with connectable.connect() as connection:
        context.configure(
            connection=connection, target_metadata=target_metadata
        )

        with context.begin_transaction():
            context.run_migrations()


if context.is_offline_mode():
    run_migrations_offline()
else:
    run_migrations_online()

Auto-generating a migration script with Alembic

Now that env.py and alembic.ini have been configured, and we have created our first data model, we can auto-generate our first migration script! We will run the command:

alembic revision --autogenerate -m "Initial commit, created customers, orders and products"

This code does the following:

Runs Alembic and creates a new revision.
Tells Alembic to auto-generate the migration script.
Creates a message string to use with the revision. In this case, this string is “Initial commit, created customers, orders and products”. This is analogous to a commit message when using git for version control.

You should get output like this:

INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
INFO  [alembic.autogenerate.compare] Detected added table 'customers'
INFO  [alembic.autogenerate.compare] Detected added table 'products'
INFO  [alembic.autogenerate.compare] Detected added table 'orders'
  Generating /path_to_your_project/alembic/versions/de5f32c11361_initial_commit_created_customers_orders_.py ...  done

This output means that Alembic has successfully generated a migration script, and the script is located at /path_to_your_project/alembic/versions/de5f32c11361_initial_commit_created_customers_orders_.py. The versions directory will have the following content:

alembic/versions/
└── de5f32c11361_initial_commit_created_customers_orders_.py

The contents of this auto-generated script are:

"""Initial commit, created customers, orders and products

Revision ID: de5f32c11361
Revises:
Create Date: 2026-01-15 16:10:01.002285

"""
from typing import Sequence, Union

from alembic import op
import sqlalchemy as sa


# revision identifiers, used by Alembic.
revision: str = 'de5f32c11361'
down_revision: Union[str, None] = None
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None


def upgrade() -> None:
    # ### commands auto generated by Alembic - please adjust! ###
    op.create_table('customers',
    sa.Column('customer_id', sa.Integer(), sa.Identity(always=True), nullable=False),
    sa.Column('first_name', sa.String(), nullable=False),
    sa.Column('last_name', sa.String(), nullable=False),
    sa.Column('email_address', sa.String(), nullable=False),
    sa.PrimaryKeyConstraint('customer_id')
    )
    op.create_table('products',
    sa.Column('product_id', sa.Integer(), sa.Identity(always=True), nullable=False),
    sa.Column('product_name', sa.String(), nullable=False),
    sa.Column('description', sa.Text(), nullable=True),
    sa.Column('price', sa.Float(), nullable=False),
    sa.PrimaryKeyConstraint('product_id')
    )
    op.create_table('orders',
    sa.Column('order_id', sa.Integer(), sa.Identity(always=True), nullable=False),
    sa.Column('customer_id', sa.Integer(), nullable=False),
    sa.Column('order_date', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
    sa.ForeignKeyConstraint(['customer_id'], ['customers.customer_id'], ondelete='CASCADE'),
    sa.PrimaryKeyConstraint('order_id')
    )
    # ### end Alembic commands ###


def downgrade() -> None:
    # ### commands auto generated by Alembic - please adjust! ###
    op.drop_table('orders')
    op.drop_table('products')
    op.drop_table('customers')
    # ### end Alembic commands ###

We can see that a migration script has been generated, with an upgrade and a downgrade parameter. Alembic has compared our target metadata against the database, and has generated a migration script complete with the operations needed to upgrade our database to the state defined by our ORM.

Note

It is important to note that Alembic does not detect every change reliably. There are certain changes that it can always detect, but it is always necessary to manually check the migration file to correct the auto-generated migrations.

From Alembic’s documentation on Autogenerate,

It is critical to note that autogenerate is not intended to be perfect. It is always necessary to manually review and correct the candidate migrations that autogenerate produces.

Alembic’s documentation has a section covering what can and cannot be detected with autogeneration.

Given that our operations here are rudimentary, in this case, the changes needed to apply our data model to the database have been correctly detected and applied, but it is always a good idea to read through the migration script anyway.

Examining the auto-generated migration script

Going through the upgrade function generated by Alembic, we can see that the following migrations have been generated:

The customers, orders and products tables have been created, with their primary keys being customer_id,order_id and product_id respectively.
The attributes defined by our models.py file have been correctly added to these newly created tables.
From this code snippet:

sa.ForeignKeyConstraint(['customer_id'], ['customers.customer_id'], ondelete='CASCADE'), We can see that the customer_id field in the orders table has been made a foreign key, connecting to the customer_id column in the customers table.

The migration script looks good, and does not need further refinement. Let’s now actually apply our first migration!

Applying the Alembic-generated migration script

We will now apply the migration script with the following command:

alembic upgrade head

This command tells Alembic to upgrade the database to the latest revision (the “head”). Depending on the state of the database, it will work through the scripts located in the versions directory to bring the database’s metadata in line with the most recent migration script.

The output of the command is as follows:

INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
INFO  [alembic.runtime.migration] Running upgrade  -> de5f32c11361, Initial commit, created customers, orders and products

Since our database is empty and there is only a single migration script, only that script has been run. The last line confirms that migration de5f32c11361 has been successfully applied.

Examining the database to verify our migration

Connect to your database with the database management tool of your choice. I use DBeaver.

The Entity Relationship Diagram for the public schema of your database should look like this.

Our newly created data model!

We’ve successfully applied our first database migration! We’ve created the customers, orders and products tables, and have built a foreign key relationship between customers and orders.

The alembic_version table has been newly created by Alembic. Alembic uses this table to identify the path to upgrade the database from its current state to the version requested by the alembic upgrade command. In our case, we requested the version head.

Alembic works through the migration scripts in the versions directory, starting from the version found in the database’s alembic_version, up to the script that defined the version requested by us, invoking the upgrade() method in each file to get to the target revision. You can check this by examining the data in the alembic_version table. It should have a single entry, corresponding to the revision of the script we just applied.

Next Steps

This is a great first step towards building a comprehensive data model, but there is a long way to go before we can consider migrating our data model from a development environment to a production environment! In subsequent blog posts, we will cover the following:

Updating our data model with more tables and relationships to create a proper e-commerce database schema.
Using an Async engine for asynchronous database connections
Using the alembic_utils library to incorporate views, functions and triggers into the version control system.
Configuring Alembic to connect to a production environment, and seamlessly bring the production environment’s schema up-to-date with our final revision.

References

SQLAlchemy documentation, most notably the SQLAlchemy Unified Tutorial Section.
Alembic’s documentation, and importantly, the section covering Autogeneration.

Data Modeling With SQLAlchemy and Alembic on Naveen Kannan

PostgreSQL Entity type Version Control with Alembic Utils.

Introduction

What we’ve already covered

What we’ll cover

Installing Alembic Utils

Adding a view to the database

Creating a View in the ORM

Registering the newly defined entity

Autogenerating a migration

Applying the migration

Expanding the data model’s scope

Adding a timestamp column to the products table

Creating a function to update the last_edited column of products

Creating a trigger to call the timestamp function on row edits

Registering the newly defined entities

Autogenerating and applying a revision to migrate the newly added entities

Next Steps

References

Data Model Version Control with Alembic.

Introduction

What we’ve already covered

What we’ll cover in this post

Getting started

Many-to-many relationship between orders and products

Creating the association table

Explaining the relationship between Order and Product

Auto-generating migrations

Reviewing the auto-generated migration

Applying the migration

Committing to GitHub

Further iterating

Creating a Tags class

Generating a migration

Reviewing the migration script

Applying the migration script

Next Steps

References

Relational Data Model design with SQLAlchemy.

Introduction

Data Modeling

SQLAlchemy

Alembic

What we’ll cover

Prerequisites

Getting Started

Setting up the Alembic environment

alembic.ini

The alembic directory

Creating a file for our data models

Customer:

Order:

Product:

Doing our first database migration.

Editing env.py to import our models

Auto-generating a migration script with Alembic

Examining the auto-generated migration script

Applying the Alembic-generated migration script

Examining the database to verify our migration

Next Steps

References

Adding a timestamp column to the `products` table

Creating a function to update the `last_edited` column of `products`

Many-to-many relationship between `orders` and `products`

Explaining the relationship between `Order` and `Product`

Creating a `Tags` class

`alembic.ini`

The `alembic` directory

`Customer`:

`Order`:

`Product`:

Editing `env.py` to import our models