Skip to main content
Framefox provides a powerful database abstraction layer built on top of SQLModel, which combines SQLAlchemy and Pydantic for type-safe database operations.

​
SQLModel Integration

Framefox uses SQLModel as its ORM (Object-Relational Mapping) layer. SQLModel provides:
  • Type Safety: Full Python type hints and Pydantic validation
  • Auto-completion: IDE support with intelligent code completion
  • SQLAlchemy Power: Access to SQLAlchemy’s advanced features when needed
  • Data Validation: Automatic validation using Pydantic

​
Database Connection Configuration

Configure your database connection in your application settings: 
from framefox.core.config.settings import Settings

settings = Settings()

# SQLite
settings.database_url = "sqlite:///./database.db"

# MySQL
settings.database_url = {
    "driver": "mysql",
    "username": "user",
    "password": "password",
    "host": "localhost",
    "port": 3306,
    "database": "mydb"
}

# PostgreSQL
settings.database_url = {
    "driver": "postgresql",
    "username": "user",
    "password": "password",
    "host": "localhost",
    "port": 5432,
    "database": "mydb"
}

​
EntityManager

The EntityManager is the core component for database operations in Framefox. It manages database sessions, transactions, and entity lifecycle.

​
Key Features

  • Session Management: Automatic session creation and lifecycle management
  • Transaction Support: Built-in transaction handling with rollback support
  • Identity Map: Caching mechanism to avoid duplicate queries
  • Entity Persistence: Methods to persist, delete, and refresh entities

​
Basic Usage

from framefox.core.orm.entity_manager import EntityManager

# Create an entity manager
entity_manager = EntityManager(connection_name="default")

# Access the session
session = entity_manager.session

# Use transactions
with entity_manager.transaction() as session:
    user = User(name="John Doe", email="[email protected]")
    entity_manager.persist(user)
    # Automatically commits on success, rolls back on error

​
Core Methods

​
persist(entity)

Adds an entity to the session and identity map: 
user = User(name="Alice", email="[email protected]")
entity_manager.persist(user)
entity_manager.commit()
Reference: framefox/core/orm/entity_manager.py:70

​
find(entity_class, primary_key)

Retrieve an entity by its primary key, using the identity map for caching: 
user = entity_manager.find(User, 1)
Reference: framefox/core/orm/entity_manager.py:144

​
delete(entity)

Deletes an entity from the database: 
user = entity_manager.find(User, 1)
entity_manager.delete(user)
entity_manager.commit()
Reference: framefox/core/orm/entity_manager.py:125

​
refresh(entity)

Refresh an entity’s state from the database: 
entity_manager.refresh(user)
Reference: framefox/core/orm/entity_manager.py:131

​
exec_statement(statement)

Execute a SQLModel/SQLAlchemy statement: 
from sqlmodel import select

statement = select(User).where(User.email == "[email protected]")
users = entity_manager.exec_statement(statement)
Reference: framefox/core/orm/entity_manager.py:138

​
Transaction Management

The EntityManager provides robust transaction support: 
# Context manager (recommended)
with entity_manager.transaction() as session:
    user = User(name="Bob")
    entity_manager.persist(user)
    # Auto-commit on success

# Manual control
try:
    user = User(name="Charlie")
    entity_manager.persist(user)
    entity_manager.commit()
except Exception:
    entity_manager.rollback()
    raise
Reference: framefox/core/orm/entity_manager.py:46

​
Table Management

Create or drop all tables defined in your models: 
# Create all tables
entity_manager.create_all_tables()

# Drop all tables (use with caution!)
entity_manager.drop_all_tables()
References:
  • framefox/core/orm/entity_manager.py:172
  • framefox/core/orm/entity_manager.py:182

​
Next Steps

Entities

Learn how to define entity models

Repositories

Work with repositories for data access

Migrations

Manage database schema changes

Query Builder

Build complex queries fluently

Build docs developers (and LLMs) love

Get started for freeTalk to us