Skip to main content

SQLAlchemy Pydantic Type

License Build Codecov PyPI Version Python Version

SQLAlchemy Pydantic Type is a Python package that bridges SQLAlchemy and Pydantic by providing a custom SQLAlchemy type for automatic serialization and deserialization of Pydantic models as database column values.

The main goal of this project is to make it easy to store and retrieve complex data structures (such as JSON fields) as Pydantic models in your SQLAlchemy 2.0 ORM models, with automatic conversion between Python objects and database representations.

See the examples directory for real-world usage.

Example

Using BasePydanticType with Pydantic models

Use BasePydanticType when your data is defined as a Pydantic BaseModel:

from typing import Any

from pydantic import BaseModel
from sqlalchemy import String
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column

from sqlalchemy_pydantic_type import BasePydanticType


class Base(DeclarativeBase):
    pass


class PydanticString(BasePydanticType):
    """
    Custom type that serializes Pydantic models to JSON strings and
    deserializes JSON strings back into Pydantic models.
    """
    impl = String
    cache_ok = True

    def _default_model_serializer(self, model: BaseModel) -> Any:
        return model.model_dump_json()

    def _default_model_deserializer(self, value: Any | None) -> BaseModel:
        return self._pydantic_model_type.model_validate_json(value)


class UserMeta(BaseModel):
    roles: list[str]
    is_active: bool


class User(Base):
    __tablename__ = "users"

    id: Mapped[int] = mapped_column(primary_key=True)
    meta: Mapped[UserMeta] = mapped_column(PydanticString(UserMeta))

In this example, the meta column will automatically handle conversion between UserMeta Pydantic objects and JSON strings in the database.

Using BaseTypeAdapterType with dataclasses and other types

Use BaseTypeAdapterType when your data is defined as a dataclass, TypedDict, or any other type supported by Pydantic's TypeAdapter:

from dataclasses import dataclass
from typing import Any

from pydantic import TypeAdapter
from sqlalchemy import JSON, String
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column

from sqlalchemy_pydantic_type import BaseTypeAdapterType


class Base(DeclarativeBase):
    pass


@dataclass
class Address:
    street: str
    city: str


@dataclass
class UserProfile:
    name: str
    age: int
    address: Address


# Create a TypeAdapter for the dataclass
user_profile_adapter = TypeAdapter(UserProfile)


# Option 1: Specify the exact type
class UserProfileJSON(BaseTypeAdapterType[UserProfile]):
    impl = JSON
    cache_ok = True


# Option 2: Reusable version - use `Any` to work with any TypeAdapter
class TypeAdapterJSON(BaseTypeAdapterType[Any]):
    impl = JSON
    cache_ok = True


class User(Base):
    __tablename__ = "users"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str]
    profile: Mapped[UserProfile] = mapped_column(UserProfileJSON(user_profile_adapter))

In this example, the profile column stores a Python dataclass as JSON in the database, with automatic serialization and deserialization.

Alembic Support

To enable proper migration script generation when using SQLAlchemy Pydantic Type with Alembic, follow these steps:

  1. Install the package with Alembic support:

    pip install sqlalchemy_pydantic_type[alembic]
    
  2. In your Alembic environment (env.py), import the render_item function:

    from sqlalchemy_pydantic_type.alembic import render_item
    
  3. Add the render_item argument to all context.configure() calls:

    context.configure(
        url=url,
        target_metadata=target_metadata,
        literal_binds=True,
        render_item=render_item,  # Add this line
        dialect_opts={"paramstyle": "named"},
    )
    

This ensures that Alembic correctly generates migration scripts for columns using Pydantic types.

For a complete working example, check out the kitchen-sink example in the examples directory.

Development

For details on setting up the development environment and contributing, see CONTRIBUTING.md.

Credits

This package was created with The Hatchlor project template.

Metadata

Release files for sqlalchemy-pydantic-type 0.0.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sqlalchemy-pydantic-type 0.0.3
File Size Uploaded Provenance Actions
sqlalchemy_pydantic_type-0.0.3.tar.gz 7.6 kB With provenance Details for sqlalchemy_pydantic_type-0.0.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sqlalchemy-pydantic-type 0.0.3
File Interpreter ABI Platform Actions
sqlalchemy_pydantic_type-0.0.3-py3-none-any.whl Python 3 none any Details for sqlalchemy_pydantic_type-0.0.3-py3-none-any.whl

Total release size: 15.1 kB

Release files / sqlalchemy_pydantic_type-0.0.3.tar.gz

Download URL sqlalchemy_pydantic_type-0.0.3.tar.gz
Size 7.6 kB
Tags Source
SHA-256 checksum
How to use checksums
80b346427db3f5608c3455d43c40e3122f3ebb42c39118ad2a4f4475d334eecf
BLAKE2b-256 checksum
How to use checksums
9053bbaae8ed0441a1a256487502c7c7376bc3a40e52369d3fbf1cacbc3a16ae
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 3, 2026.

Transparency log

Release files / sqlalchemy_pydantic_type-0.0.3-py3-none-any.whl

Download URL sqlalchemy_pydantic_type-0.0.3-py3-none-any.whl
Size 7.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ebed8a98caba4525a1209f6df19755a86b7bc23703857db46afae3f69404b32b
BLAKE2b-256 checksum
How to use checksums
56b4994e615590292691719be42119cc61f7a5770d0f04a37d56c5bc5f74fa3b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 3, 2026.

Transparency log

Security for sqlalchemy-pydantic-type 0.0.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for sqlalchemy_pydantic_type-0.0.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 3, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page