Skip to main content

🧱 SQLMorph: Migrations & Schema Visualization for SQLModel and SQLAlchemy

SQLMorph — Zero-config migrations, schema inspection, and ER diagram generation for SQLModel and SQLAlchemy.
No boilerplate. No manual scripts. Just magic. ⚡

PyPI version License


✨ Why SQLMorph?

Feature Alembic SQLMorph
Auto-detects model changes ❌ ✅
Zero configuration ❌ ✅
Schema health check ❌ ✅
ER diagram generator ❌ ✅
Live migration watch ❌ ✅
Works with SQLAlchemy + SQLModel ✅ ✅
Interactive shell ❌ ✅
JSON + Mermaid export ❌ ✅

🚀 Features

SQLMorph is more than just a migration tool — it’s a complete database companion for your ORM projects.

  • 🚀 Zero-Config Migrations: Automatically detects schema changes and generates migration scripts.
  • 🩺 Schema Health Checks: Detects drift between your models and the database.
  • 📝 Safe Planning: Preview SQL changes before migrating.
  • 🔍 Advanced Inspection: View models and relationships as tables or JSON.
  • 🎨 Auto Diagrams: Generate Mermaid.js ERDs directly from your models.
  • 🌱 Data Seeding: Load seed data via JSON or YAML.
  • 👀 Live Watch Mode: Automatically detect model changes.
  • 🔧 Reverse Engineering: Generate ORM classes from existing DBs.
  • 🗄️ Interactive Shell: Native database shell integration.
  • 🧠 SQLAlchemy + SQLModel: Full compatibility with both ORMs.

📦 Installation

pip install -e .
# For shell command support on Debian/Ubuntu
sudo apt update && sudo apt install sqlite3

⚡ Quick Start

Define your models

# models.py
from typing import Optional
from sqlmorph import SQLModel, Field

class User(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    name: str

Create your first migration

sqlmorph makemigration "create_user_table" --models models.py
sqlmorph migrate

Make changes and apply them

# models.py
class User(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    name: str
    email: str  # <-- new field
sqlmorph plan
sqlmorph makemigration "add_email_to_user"
sqlmorph migrate

🧠 Works with SQLAlchemy Too

from sqlalchemy import Column, Integer, String, ForeignKey
from sqlalchemy.orm import declarative_base, relationship

Base = declarative_base()

class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    name = Column(String)
    posts = relationship("Post", back_populates="user")

class Post(Base):
    __tablename__ = "posts"
    id = Column(Integer, primary_key=True)
    title = Column(String)
    user_id = Column(Integer, ForeignKey("users.id"))
    user = relationship("User", back_populates="posts")

Both ORM types work seamlessly.


🧰 Command Reference

Command Description
makemigration <name> Generate migration script for detected schema changes
migrate Apply pending migrations
rollback Undo the last migration
plan Preview upcoming SQL operations
doctor Detect drift between DB and models
inspect Show model tables and relationships
diagram Generate Mermaid.js ER diagrams
snapshot Save current schema state
explain <query> Analyze query performance
seed --file <path> Load seed data from JSON/YAML
watch Monitor models for changes
diffdb --url <db_url> Reverse engineer SQLModel from DB
shell Open database shell
help Show command reference

🧪 CI/CD Example

- name: Validate Schema
  run: |
    pip install sqlmorph
    sqlmorph doctor

🧩 How It Works

SQLMorph introspects your ORM metadata (SQLModel.metadata or Base.metadata), snapshots its structure, and generates safe migration plans.
All migrations are explicit, auditable, and reversible.


🛠️ Roadmap

  • Plugin system for lifecycle hooks
  • Cloud schema diff dashboard
  • FastAPI integration helpers
  • Visual web UI for migration planning

🧑‍💻 Contributing

Pull requests are welcome! Please run tests before submitting:

pytest

📜 License

MIT License © 2025 SQLMorph Contributors

Metadata

Release files for sqlmorph 1.0.0

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

Source distribution (sdist)

Source distribution for sqlmorph 1.0.0
File Size Uploaded Provenance Actions
sqlmorph-1.0.0.tar.gz 19.6 kB Without provenance Details for sqlmorph-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sqlmorph 1.0.0
File Interpreter ABI Platform Actions
sqlmorph-1.0.0-py3-none-any.whl Python 3 none any Details for sqlmorph-1.0.0-py3-none-any.whl

Total release size: 44.7 kB

Release files / sqlmorph-1.0.0.tar.gz

Download URL sqlmorph-1.0.0.tar.gz
Size 19.6 kB
Tags Source
SHA-256 checksum
How to use checksums
26cc7132c4a3b9ee0b148b923fb1073f0fc52a96676d45af05bc91d7b2934d45
BLAKE2b-256 checksum
How to use checksums
c64873408a94299b967c70fc06866e9e32780358b414d6b9b69d75a001c2eed6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.2.1 CPython/3.12.3 Linux/5.10.16.3-microsoft-standard-WSL2

Release files / sqlmorph-1.0.0-py3-none-any.whl

Download URL sqlmorph-1.0.0-py3-none-any.whl
Size 25.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2dfb6edeb53b9b5139294028acc7246cee99c6865a40c2b8311453f5f40a9225
BLAKE2b-256 checksum
How to use checksums
d7c4468b751a9cd388f1f70fd708e35267fd696b6718e1c64e26f274a8eb9c9c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.2.1 CPython/3.12.3 Linux/5.10.16.3-microsoft-standard-WSL2

Security for sqlmorph 1.0.0

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

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