🧱 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. ⚡
✨ 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.