For AI agents: the complete documentation index is at llms.txt. Remove the trailing slash from a page URL and append .md to read its Markdown version. For the docs home, use index.md.

Tables

Tables are database objects that contain all the data in a database.

In tables, data is logically organized in a row-and-column format similar to a spreadsheet. Each row represents a unique record, and each column represents a field in the record.

Creating a Table

Tables are SQLAlchemy models. Define one base class for the app and make each table a subclass of it.

import reflex as rx
from sqlalchemy.orm import DeclarativeBase, Mapped, MappedAsDataclass, mapped_column


class Base(MappedAsDataclass, DeclarativeBase):
    """Base class for the app's tables."""


class User(Base):
    __tablename__ = "user"

    id: Mapped[int] = mapped_column(init=False, primary_key=True)
    username: Mapped[str]
    email: Mapped[str]

Each Mapped[...] annotation becomes a column whose SQL type is derived from the Python type. MappedAsDataclass makes the model a dataclass, so User(username="test", email="[email protected]") constructs a row and Reflex can store User instances in state and render their fields in components. Until a base is registered with rx.ModelRegistry.register(Base), the reflex db migration commands find the tables of every DeclarativeBase subclass defined at module level or in a class body of a module that the app imports; see Database Overview for when to register bases.

Dataclass fields without a default must come before fields with one, so declare required columns first and optional columns, with default=None or default_factory, after them. A default_factory belongs to the dataclass alone, so the column has no default that a migration could give the rows a table already holds: reflex db makemigrations refuses to add such a column unless it is nullable or also has a server_default, or use a literal default= instead.

Primary Key

Every table needs a primary key. Declare it with primary_key=True; init=False excludes it from the constructor so the database assigns it on insert.

class User(Base):
    __tablename__ = "user"

    id: Mapped[int] = mapped_column(init=False, primary_key=True)
    ...

Advanced Column Types

Nullable and Optional Columns

A column annotated with | None is nullable. Give it default=None so it can be left out when constructing the row.

from datetime import datetime


class Post(Base):
    __tablename__ = "post"

    id: Mapped[int] = mapped_column(init=False, primary_key=True)
    title: Mapped[str]
    body: Mapped[str]
    published_at: Mapped[datetime | None] = mapped_column(default=None)

Explicit column types

SQLAlchemy maps basic Python types to column types, but for more advanced use cases, pass the column type to mapped_column directly. For example, we can add a last updated timestamp to the post example as a DateTime with timezone that the database fills in.

import datetime

import sqlalchemy


class Post(Base):
    __tablename__ = "post"

    id: Mapped[int] = mapped_column(init=False, primary_key=True)
    ...
    update_ts: Mapped[datetime.datetime] = mapped_column(
        sqlalchemy.DateTime(timezone=True),
        init=False,
        server_default=sqlalchemy.func.now(),
    )

Reflex serializes datetime values to ISO strings for the frontend. To change how a model is sent to the frontend, register a serializer for it. This one strips the microseconds from update_ts, which is None until the row has been inserted:

import reflex as rx
import sqlalchemy


@rx.serializer
def serialize_post(post: Post) -> dict:
    data = {
        attr.key: getattr(post, attr.key)
        for attr in sqlalchemy.inspect(post).mapper.column_attrs
    }
    if post.update_ts is not None:
        data["update_ts"] = post.update_ts.replace(microsecond=0).isoformat()
    return data

The serializer reads only the column attributes. dataclasses.asdict(post) would also follow the model's relationships, which raises DetachedInstanceError for one the query did not load and RecursionError for a loaded one that links back, such as post.user.posts.

Existing rx.Model apps

rx.Model is deprecated as of Reflex 0.9.2 and is scheduled for removal in 1.0.0. See Migrating existing apps for the equivalent SQLAlchemy declarations. The note below applies to apps that still use rx.Model or SQLModel directly.

Datetimes and SQLModel upgrades

From SQLModel 0.0.45, a plain datetime field uses UTCDateTime: database writes require timezone-aware values, and reads return UTC-aware values, including on SQLite. Migrations generated with these versions reference sqlmodel.sql.sqltypes.UTCDateTime() and require SQLModel 0.0.45 or later when they run. Keep the SQLModel version used to generate migrations in your deployment dependencies; for example, sqlmodel>=0.0.45 if a migration uses UTCDateTime.

Reflex does not cap the SQLModel version, so a fresh install, or an upgrade that refreshes every dependency such as uv pip install -U, can move an app from SQLModel 0.0.44 to 0.0.45 or later. pip install -U and uv pip install without -U leave an installed SQLModel in place. After the move, naive datetime values are rejected when written, and values read back are timezone-aware, so comparing them with datetime.now() raises TypeError: can't compare offset-naive and offset-aware datetimes. To keep naive datetimes, declare the column explicitly as shown below, or pin sqlmodel<0.0.45 while no migration references UTCDateTime.

For existing apps that store naive datetimes, declare the SQLAlchemy type explicitly to preserve that behavior across SQLModel versions:

from datetime import datetime

from sqlalchemy import DateTime
from sqlmodel import Field


class Post(rx.Model, table=True):
    created_at: datetime = Field(
        default_factory=datetime.now,
        sa_type=DateTime(timezone=False),
    )

On SQLModel 0.0.45 or later, Pydantic's NaiveDatetime annotation also selects naive storage. For UTC storage, use aware producers such as datetime.now(timezone.utc), and update comparisons, query parameters, and database defaults to use aware values. Changing the Python field type does not convert existing database values: determine the timezone of stored data and apply a database-specific migration before adopting UTC storage. Follow SQLModel's datetime upgrade guide for the PostgreSQL, SQLite, and MySQL migration details.