The base model you keep rewriting, done once.

Installation

pip install flask-modelkit

Requirements:

Everything is importable from the top-level package:

from flask_modelkit import (
    BaseModelMixin,     # UUID + timestamps + CRUD + to_dict
    UUIDMixin, IntIdMixin, TimestampMixin,
    SoftDeleteMixin, CRUDMixin, SerializerMixin,
    hidden_column,      # never sent to the client by to_dict()
    protected_column,   # never set from client input
    secret_column,      # both: for password hashes, API keys, tokens
    utcnow,             # the UTC clock the timestamps use
    PaginationReturn,   # TypedDict returned by paginate()
    InvalidBodyError, MissingFieldsError, DuplicateValueError,  # create_or_abort() errors
    db, BaseModel,      # optional bundled SQLAlchemy() and abstract base
)

Quick start

A complete, runnable app: one model, create/read/update/list endpoints.

1. Define a model

   Put the mixin before db.Model. You only declare your own columns; id, created_at and updated_at come from the mixin.

   models.pyCopy

   from flask_sqlalchemy import SQLAlchemy
   from flask_modelkit import BaseModelMixin, protected_column, secret_column
   
   db = SQLAlchemy()
   
   
   class User(BaseModelMixin, db.Model):
       name = db.Column(db.String(50), nullable=False)
       email = db.Column(db.String(100), unique=True, nullable=False)
       is_admin = protected_column(db.Boolean, default=False)   # clients can't set it
       password_hash = secret_column(db.String(200))            # never sent, never set

2. Wire up the app and create the tables

   app.pyCopy

   from flask import Flask, jsonify, request
   from werkzeug.security import generate_password_hash
   
   from models import User, db
   
   app = Flask(__name__)
   app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///app.db"
   db.init_app(app)
   
   with app.app_context():
       db.create_all()          # or use Flask-Migrate, see Migrations

3. Add endpoints

   app.py (continued)Copy

   @app.post("/users")
   def create_user():
       data = request.get_json(silent=True) or {}
       pw = data.get("password")
       # 400 naming missing fields · 409 if the email is taken · unknown keys dropped
       user = User.create_or_abort(
           data,
           required=["password"],
           password_hash=generate_password_hash(pw) if pw else None,
       )
       return jsonify(user.to_dict(json_safe=True)), 201
   
   
   @app.get("/users/<id>")
   def get_user(id):
       return jsonify(User.get_or_404(id).to_dict(json_safe=True))
   
   
   @app.patch("/users/<id>")
   def update_user(id):
       user = User.get_or_404(id)
       user.update(request.get_json(silent=True) or {})   # id, timestamps, is_admin, password_hash ignored
       return jsonify(user.to_dict(json_safe=True))
   
   
   @app.get("/users")
   def list_users():
       page = User.paginate(page=request.args.get("page", 1, type=int), per_page=20)
       page["items"] = [u.to_dict(json_safe=True) for u in page["items"]]
       return jsonify(page)

4. Call it

   curl -X POST localhost:5000/users \
     -H "Content-Type: application/json" \
     -d '{"name": "Ada", "email": "ada@example.com", "password": "s3cret"}'

   201 CreatedCopy

   {
     "id": "3f1c9a7e-5b2d-4c8e-9f10-2a6b7d4e1c33",
     "created_at": "2026-11-07T10:15:00.123456",
     "updated_at": "2026-11-07T10:15:00.123456",
     "name": "Ada",
     "email": "ada@example.com",
     "is_admin": false
   }

   No password_hash in the output: it is a secret_column, so it is never sent. Sending "is_admin": true or your own "password_hash" is ignored, because both are protected. See Hidden vs protected.

   Bad requests get a clear JSON error, without any code of yours:

   400 Bad Request · body {"name": "Ada"}Copy

   {"error": "missing_fields", "message": "Missing required field(s): email, password", "fields": ["email", "password"]}

   409 Conflict · same email againCopy

   {"error": "duplicate", "message": "A User with this email already exists.", "fields": ["email"]}

The ordering rule

There is one rule to remember: mixins go before db.Model in the class bases.

class Post(BaseModelMixin, db.Model):   # ✓ correct
class Post(db.Model, BaseModelMixin):   # ✗ wrong

Python runs base-class constructors in method-resolution order, and SQLAlchemy's constructor does not call the next one in line. With the mixins first, UUIDMixin and TimestampMixin run their __init__, fill in id and the timestamps, then hand off to SQLAlchemy. That is why an id exists before you save:

post = Post(title="Hello")
post.id          # '3f2b…'  usable right away, e.g. to build a URL
post.created_at  # datetime(2026, 11, 7, 10, 15, 0, 123456)

The order among the mixins does not matter.

Use with AI agents

AI coding assistants know Flask-SQLAlchemy well, but they don't know this package's rules. Without them, an agent will write User.create(**request.json), put db.Model first, or store a password hash in a hidden_column. flask-modelkit ships an AGENT.md that spells those rules out. Add it to your project once, and your agent follows it.

Add it to your agent

Run one of these in your project's root folder:

# Save the rules, then import them from CLAUDE.md
mkdir -p .claude
curl -fsSL https://anoziechibuike.github.io/FlaskModelKit/AGENT.md -o .claude/flask-modelkit.md
echo "@.claude/flask-modelkit.md" >> CLAUDE.md

# A project rule that attaches automatically to Python files
mkdir -p .cursor/rules
{ printf -- '---\ndescription: How to use flask-modelkit models, fields and endpoints\nglobs: **/*.py\nalwaysApply: false\n---\n\n'
  curl -fsSL https://anoziechibuike.github.io/FlaskModelKit/AGENT.md; } > .cursor/rules/flask-modelkit.mdc

# Path-specific instructions, applied to Python files (VS Code, JetBrains, github.com)
mkdir -p .github/instructions
{ printf -- '---\napplyTo: "**/*.py"\n---\n\n'
  curl -fsSL https://anoziechibuike.github.io/FlaskModelKit/AGENT.md; } > .github/instructions/flask-modelkit.instructions.md

# AGENTS.md is read by Codex, Jules, Amp, Zed and other agents
curl -fsSL https://anoziechibuike.github.io/FlaskModelKit/AGENT.md >> AGENTS.md

# Gemini CLI reads GEMINI.md instead
curl -fsSL https://anoziechibuike.github.io/FlaskModelKit/AGENT.md >> GEMINI.md

Before writing any code, read https://anoziechibuike.github.io/FlaskModelKit/AGENT.md
and follow it for everything that uses flask-modelkit in this conversation.

Commit the file it creates so everyone on your team, and every CI agent, gets the same rules.

What it teaches the agent

• Mixins before db.Model, and which mixins to combine for which model.
• Request data goes through create_or_abort() and update(), never create(**request.json).
• Hidden vs protected: secret_column for secrets, protected_column for permissions, ownership and computed values.
• Protected, required fields are passed as keyword arguments, such as author=current_user.
• UTC timestamps, soft-delete behaviour, JSON with to_dict(json_safe=True), and SQL counts instead of len(Model.all()).

Overview & builder

Every feature is a separate mixin. Choose a primary key and the features you want, and the builder shows the class line, the columns your table gets, and the methods available on the model.

BaseModelMixin

The batteries-included combination, and the right default for most models. It is exactly:

class BaseModelMixin(UUIDMixin, TimestampMixin, CRUDMixin, SerializerMixin):
    """UUID key + timestamps + CRUD/query helpers + to_dict()."""

class Article(BaseModelMixin, db.Model):
    title = db.Column(db.String(200), nullable=False)
    body = db.Column(db.Text)

article = Article.create(title="Hello")
article.id, article.created_at      # set automatically
article.update({"body": "…"})       # safe update + commit
article.to_dict(json_safe=True)     # ready for jsonify()

Add soft delete by putting SoftDeleteMixin in front: class Article(SoftDeleteMixin, BaseModelMixin, db.Model).

UUIDMixin

A UUID4 string primary key. It is generated in Python when the object is constructed, so you can use it before the first flush: in a URL, a log line, or as a foreign key for a child created in the same transaction.

class Invite(UUIDMixin, CRUDMixin, db.Model):
    email = db.Column(db.String(120))

invite = Invite(email="ada@example.com")
link = f"https://app.example.com/invites/{invite.id}"   # before saving
invite.save()

legacy = Invite(id="b1946ac9-2a7c-4d3e-9b1f-0c1d2e3f4a5b", email="x@y.z")  # explicit id

IntIdMixin

An auto-increment integer primary key, assigned by the database on insert. Good for lookup tables, internal join tables, or when you are adding the package to an existing integer-keyed schema.

class Tag(IntIdMixin, CRUDMixin, SerializerMixin, db.Model):
    name = db.Column(db.String(30), unique=True)

tag = Tag(name="python")
tag.id          # None
tag.save()
tag.id          # 1

Use one primary-key mixin per model: UUIDMixin or IntIdMixin, never both.

TimestampMixin

Adds created_at and updated_at, both in UTC. Both are set to the same instant when the object is constructed.

class Note(UUIDMixin, TimestampMixin, CRUDMixin, db.Model):
    text = db.Column(db.Text)

note = Note.create(text="draft")
note.created_at == note.updated_at   # True

note.text = "final"
db.session.commit()                  # plain commit still bumps updated_at
note.updated_at > note.created_at    # True

from datetime import timedelta
from flask_modelkit import utcnow

recent = db.session.scalars(
    Note.select().where(Note.created_at >= utcnow() - timedelta(days=7))
).all()

SoftDeleteMixin

Marks rows as deleted instead of removing them. Deleted rows are hidden from every ORM query automatically. Full behaviour is in the soft delete guide.

class Post(SoftDeleteMixin, BaseModelMixin, db.Model):
    title = db.Column(db.String(200))

post.soft_delete()
post.is_deleted                    # True
Post.get(post.id)                  # None, hidden
Post.get(post.id, include_deleted=True).restore()

CRUDMixin

Write methods on instances and query helpers on the class. All of them use the session of the db your model inherits from and must run inside an application context (a request, a CLI command, or with app.app_context():).

What update() and create_or_abort() may change is controlled by protected fields: mark columns with protected_column() or list names in __protected_fields__. Each method is covered in the guides and the API reference.

SerializerMixin

Adds to_dict(): columns plus related objects, with depth control, cycle safety, hidden fields and optional JSON-safe conversion.

user.to_dict()
# {"id": "…", "created_at": datetime(…), "updated_at": datetime(…),
#  "name": "Ada", "posts": [{…}, {…}]}

user.to_dict(json_safe=True)       # datetimes → ISO strings, etc.
user.to_dict(depth=0)              # columns only
user.to_dict(exclude=["email"])    # leave fields out of this response

See Serialisation for every option, Hidden fields for keeping columns out of responses, and Hidden vs protected for secrets.

Bundled db & BaseModel

If your app does not have a SQLAlchemy() instance yet, use the package's. BaseModel is an abstract class equivalent to BaseModelMixin, db.Model, bound to that db.

from flask_modelkit import BaseModel, db

class User(BaseModel):
    name = db.Column(db.String(50))

db.init_app(app)

Recipes

class User(BaseModelMixin, db.Model):
    email = db.Column(db.String(100), unique=True, nullable=False)

class User(BaseModelMixin, db.Model):
    email = db.Column(db.String(100), unique=True, nullable=False)
    is_admin = protected_column(db.Boolean, default=False, nullable=False)
    password_hash = secret_column(db.String(255), nullable=False)

class Post(SoftDeleteMixin, BaseModelMixin, db.Model):
    title = db.Column(db.String(200))

class Country(IntIdMixin, CRUDMixin, SerializerMixin, db.Model):
    code = db.Column(db.String(2), unique=True)

class AuditLog(UUIDMixin, TimestampMixin, db.Model):
    action = db.Column(db.String(50))

db.session.add(AuditLog(action="login"))
db.session.commit()

class Model(SoftDeleteMixin, BaseModelMixin, db.Model):
    __abstract__ = True

class Invoice(Model):
    amount = db.Column(db.Numeric(10, 2))

Creating & updating

user = User.create(name="Ada", email="ada@example.com")   # construct + save

user.name = "Ada L."
user.save()                                               # add + commit

user.update({"name": "Ada Lovelace"})                     # safe set + save
user.delete()                                             # removes the row

user.update({
    "name": "Ada",             # set
    "id": "hacked",            # ignored: protected
    "created_at": "1970-01-01",# ignored: protected
    "role": "admin",           # ignored: not a column
})

Create from request data

create_or_abort() is create() for untrusted input. It validates the input, drops unsafe keys, and raises a JSON HTTP error with the exact field names when something is wrong. Most endpoints become one line:

@app.post("/posts")
def create_post():
    post = Post.create_or_abort(request.get_json(silent=True), author=current_user)
    return jsonify(post.to_dict(json_safe=True)), 201

What happens, in order

1. Check the body is an object

   A list or string raises InvalidBodyError (400).

2. Drop unsafe keys

   Keys that aren't mapped attributes, or are protected, are removed. With fields=, anything not listed is removed too.

3. Check the endpoint itself

   If a required column can never be filled, because it is protected or left out of fields= and you didn't pass it as a keyword argument, a TypeError explains which field and how to fix it. This is a bug in the endpoint, not the request, so it is raised on every call, even for an empty body, and you find it the first time you try the route.

4. Check required fields

   Every NOT NULL column without a default is required, plus any names in required=. Passing a relationship (author=user) counts for its foreign-key column (author_id). None, "" and whitespace-only strings count as missing. All missing fields are reported together with MissingFieldsError (400).

5. Create and commit

   If a unique value is already taken, the session is rolled back and DuplicateValueError (409) names the field. Single-column, composite and soft-deleted conflicts are all detected. Other integrity errors are re-raised so real bugs aren't hidden behind a 409.

Derived values like password hashes

The client sends password, but the column is password_hash. Mark the input as required and pass the hash as a trusted value:

data = request.get_json(silent=True) or {}
pw = data.get("password")
user = User.create_or_abort(
    data,
    required=["password"],
    password_hash=generate_password_hash(pw) if pw else None,
)

Error responses

Errors render as JSON without any setup:

{"error": "missing_fields", "message": "Missing required field(s): name, email", "fields": ["name", "email"]}

They subclass Werkzeug's BadRequest and Conflict, so an error handler you already have still receives them, with the field names on e.fields:

from flask_modelkit import MissingFieldsError

@app.errorhandler(MissingFieldsError)
def missing(e):
    return {"ok": False, "missing": e.fields}, 400

Protected fields

A protected field can never be set from client input. When you pass a request body to update() or create_or_abort(), protected keys are dropped silently and everything else is applied:

user.update({"name": "Ada L.", "is_admin": True, "id": "hacked"})
user.name       # "Ada L."   set
user.is_admin   # False      ignored: protected
user.id         # unchanged  ignored: protected by default

Without protection, any client could send PATCH /me {"is_admin": true} and make itself an admin. This is called mass assignment, and it is the reason protection exists.

from flask_modelkit import BaseModelMixin, protected_column

class Post(BaseModelMixin, db.Model):
    title = db.Column(db.String(200), nullable=False)

    # 1. Shorthand: same arguments as db.Column, ForeignKey included
    author_id = protected_column(db.String(126), db.ForeignKey("user.id"), nullable=False)

    # 2. The info flag: works on db.Column, mapped_column and db.relationship
    status = db.Column(db.String(20), default="draft", info={"protected": True})
    author = db.relationship("User", info={"protected": True})

class Invoice(TenantMixin, BaseModelMixin, db.Model):    # TenantMixin adds tenant_id
    __protected_fields__ = BaseModelMixin.__protected_fields__ | {"tenant_id"}

{"id", "created_at"} | {"email"}    # {"id", "created_at", "email"}

__protected_fields__ = BaseModelMixin.__protected_fields__ | {"email"}   # ✓ id, timestamps, email
__protected_fields__ = frozenset({"email"})                             # ✗ only email: id is writable again!

Post.protected_fields()
# frozenset({"id", "created_at", "updated_at", "deleted_at", "author_id", "status", "author"})

user.is_admin = True                          # plain assignment
user.save()
User.create(name="Ada", is_admin=True)        # create() is for trusted values
Post.create_or_abort(data, author=current_user)   # keyword arguments are trusted

class Post(BaseModelMixin, db.Model):
    author_id = protected_column(db.String(126), db.ForeignKey("user.id"), nullable=False)
    author = db.relationship("User", back_populates="posts", info={"protected": True})

@app.post("/posts")
def create_post():
    # Whatever author_id the client sends is dropped; the owner comes from the session.
    post = Post.create_or_abort(request.get_json(silent=True), author=current_user)
    return jsonify(post.to_dict(json_safe=True)), 201

class Order(BaseModelMixin, db.Model):
    total = protected_column(db.Numeric(10, 2), default=Decimal("0"), nullable=False)

order.update(request.json)                     # "total": "0.01" is ignored
order.total = sum(l.unit_price * l.quantity for l in order.lines)
order.save()

comments = db.relationship("Comment", back_populates="post", info={"protected": True})

class User(BaseModelMixin, db.Model):
    email = db.Column(db.String(120), unique=True, nullable=False)   # not protected

User.create_or_abort(data, ...)        # signup: email accepted, 400 if missing, 409 if taken

PROFILE_FIELDS = {"name", "bio"}

@app.patch("/me")
def edit_profile():
    data = request.get_json(silent=True) or {}
    current_user.update({k: v for k, v in data.items() if k in PROFILE_FIELDS})
    return jsonify(current_user.to_dict(json_safe=True))

TypeError: User.create_or_abort(): required field(s) email can never be filled: 'email' is
protected, so request data can't set it. Pass them as keyword arguments, e.g.
User.create_or_abort(data, email=...), or, if clients should send them, stop protecting
them / add them to fields=.

This is the most common protection mistake: protecting email, then expecting it from the signup body. If clients should send it, don't protect it; see "Set once, read-only afterwards".

Transactions

create, create_or_abort, save, update, delete, soft_delete and restore all commit by default. Pass commit=False to stage several changes and commit them together:

order = Order.create(user=user, commit=False)
for item in cart:
    OrderLine.create(order=order, product=item, commit=False)
db.session.commit()          # all or nothing

create_or_abort(..., commit=False) still flushes, so a duplicate value is reported straight away instead of at your final commit. The rollback that comes with a 409 discards every uncommitted change in the session, not only the new row.

If a commit from create, save or update fails (a unique constraint, a foreign key), the session is left in a failed state. Roll it back before using it again:

from sqlalchemy.exc import IntegrityError

try:
    user.update({"email": new_email})
except IntegrityError:
    db.session.rollback()
    abort(409)

create_or_abort() does this rollback for you.

Reading & filtering

Filters are exact-match column=value pairs, combined with AND:

User.filter_all(country="NG", is_active=True)
User.filter_one(email="ada@example.com")
User.exists(email="ada@example.com")          # no rows loaded
User.filter_and_count_all(country="NG")      # no rows loaded

User.get(None), User.get("")                  # None, no query

Counts and existence checks run in the database, so they never load rows into Python.

Pagination

User.paginate(page=2, per_page=20)
# {"items": [<User>, ...], "total": 135, "pages": 7, "page": 2, "per_page": 20}

• Ordered by created_at, then primary key, so a row never appears on two pages. Models without timestamps are ordered by primary key.
• An out-of-range page returns an empty items list, not an error.
• The return value is a plain dict, typed as PaginationReturn, so you can replace items before returning it:

@app.get("/users")
def list_users():
    page = User.paginate(page=request.args.get("page", 1, type=int), per_page=20)
    page["items"] = [u.to_dict(json_safe=True) for u in page["items"]]
    return jsonify(page)

paginate() does not take filters. To paginate a filtered query, build it with select() and use Flask-SQLAlchemy's db.paginate, as shown next.

Custom queries

For ranges, joins, OR, LIKE and custom ordering, start from Model.select() and use SQLAlchemy directly. Soft-deleted rows are still hidden.

from sqlalchemy import or_

stmt = (
    User.select()
    .where(User.created_at >= since)
    .where(or_(User.name.ilike("%ada%"), User.email.ilike("%ada%")))
    .order_by(User.name)
)
users = db.session.scalars(stmt).all()
page = db.paginate(stmt, page=1, per_page=20)    # Flask-SQLAlchemy pagination object

Model.select(include_deleted=True) returns the same statement with soft-deleted rows included.

Serialisation

json_safe=True converts column values like this:

return jsonify(user.to_dict(json_safe=True))

Hidden fields

A hidden field is never sent to the client by to_dict(): not at any depth, and not when the object appears inside another object's relationships. The value is still stored and readable on the object; it is only left out of the output.

from flask_modelkit import BaseModelMixin, hidden_column

class Integration(BaseModelMixin, db.Model):
    name = db.Column(db.String(50))
    webhook_secret = hidden_column(db.String(64))                        # shorthand
    last_error = db.Column(db.Text, info={"hidden": True})               # same thing
    deliveries = db.relationship("Delivery", info={"hidden": True})      # relationships too

hook.webhook_secret                 # "whsec_…"  still readable in your code
"webhook_secret" in hook.to_dict()  # False

class User(SoftDeleteMixin, BaseModelMixin, db.Model):
    __hidden_fields__ = frozenset({"deleted_at"})   # always null for live rows: no need to send it

Hidden vs protected

These are two separate controls on what crosses your API boundary. Hidden stops a field going out to the client. Protected stops a field coming in from the client. A field can be either, both or neither.

Fields that need both use secret_column(...), which sets both flags.

password_hash = hidden_column(db.String(255))     # ✗ hidden, but NOT protected

user.update(request.json)    # body: {"password_hash": "<the attacker's own hash>"}

password_hash = secret_column(db.String(255), nullable=False)   # ✓ never sent, never set

# Set it from your own code, from the password the client sent:
User.create_or_abort(data, required=["password"],
                     password_hash=generate_password_hash(data["password"]) if data.get("password") else None)

Depth & relationships

Two-way relationships (back_populates or backref) are safe at any depth. An object already serialised higher up the tree is skipped, so there is no infinite loop:

author.to_dict(depth=None)
# {"name": "A", "books": [{"title": "B", "chapters": [{"title": "C"}]}]}
#                          ^ no "author" key inside the book

author.to_dict(depth=0)   # columns only
author.to_dict()          # + books, but each book is columns only
author.to_dict(depth=2)   # + books + each book's chapters

from sqlalchemy.orm import selectinload

stmt = Author.select().options(selectinload(Author.books))
authors = db.session.scalars(stmt).all()
data = [a.to_dict() for a in authors]   # no extra queries for books

On models with SoftDeleteMixin, soft-deleted related objects are left out automatically.

Soft delete

Soft-deleted rows can be restored, audited, or kept to satisfy foreign keys. Most implementations only filter their own helper methods, so a single raw query leaks deleted data. This mixin hooks into the SQLAlchemy session instead, so deleted rows are left out of every ORM query on the model.

Post.all()                               # hidden
Post.get(id), Post.filter_one(...)       # hidden
Post.count_all(), Post.exists(...)       # hidden
Post.query.filter_by(...).all()          # hidden
db.session.scalars(db.select(Post))      # hidden
db.session.get(Post, id)                 # hidden
author.posts                             # hidden in relationship loads too

Post.get(id, include_deleted=True)

stmt = Post.select(include_deleted=True)                       # same as:
stmt = db.select(Post).execution_options(include_deleted=True)

trash = db.session.scalars(
    Post.select(include_deleted=True).where(Post.deleted_at.is_not(None))
).all()

post = Post.get(id, include_deleted=True)
post.restore()

post.delete()      # the row is gone

# PostgreSQL: unique among live rows only
class User(SoftDeleteMixin, BaseModelMixin, db.Model):
    email = db.Column(db.String(120), nullable=False)
    __table_args__ = (
        db.Index("uq_user_email_live", "email", unique=True,
                 postgresql_where=db.text("deleted_at IS NULL")),
    )

Migrations

The mixins are ordinary SQLAlchemy columns, so Flask-Migrate (Alembic) picks them up like any other column.

1. Install and register

   # pip install Flask-Migrate
   from flask_migrate import Migrate
   migrate = Migrate(app, db)

2. Create the migrations folder (once)

   flask db init

3. Generate and apply

   flask db migrate -m "add posts"
   flask db upgrade

op.add_column("post", sa.Column("deleted_at", sa.DateTime(), nullable=True))
op.create_index("ix_post_deleted_at", "post", ["deleted_at"])

def upgrade():
    with op.batch_alter_table("post") as batch:   # batch mode also works on SQLite
        batch.add_column(sa.Column("created_at", sa.DateTime(), nullable=False,
                                   server_default=sa.func.current_timestamp()))
        batch.add_column(sa.Column("updated_at", sa.DateTime(), nullable=False,
                                   server_default=sa.func.current_timestamp()))
    with op.batch_alter_table("post") as batch:
        batch.alter_column("created_at", server_default=None)
        batch.alter_column("updated_at", server_default=None)

-- PostgreSQL
SELECT created_at AT TIME ZONE 'UTC' AT TIME ZONE 'Africa/Lagos' FROM post;

Blog API

A small but complete blog backend: users, posts and comments, with password hashing, protected ownership fields, a trash can, restore, filtered pagination and nested JSON. It uses almost every feature in the package.

from flask_migrate import Migrate
from flask_sqlalchemy import SQLAlchemy

db = SQLAlchemy()
migrate = Migrate()

import enum

from flask_modelkit import BaseModelMixin, SoftDeleteMixin, protected_column, secret_column

from extensions import db


class Model(SoftDeleteMixin, BaseModelMixin, db.Model):
    """Every table: UUID id, timestamps, soft delete, CRUD, to_dict()."""
    __abstract__ = True


class User(Model):
    name = db.Column(db.String(80), nullable=False)
    # Not protected: signup must accept it. Profile edits use an allowlist instead.
    email = db.Column(db.String(120), unique=True, nullable=False)
    is_admin = protected_column(db.Boolean, default=False, nullable=False)
    password_hash = secret_column(db.String(255), nullable=False)

    posts = db.relationship("Post", back_populates="author", info={"protected": True})


class PostStatus(enum.Enum):
    DRAFT = "draft"
    PUBLISHED = "published"


class Post(Model):
    # Clients may edit title/body/status, never ownership or children.
    title = db.Column(db.String(200), nullable=False)
    body = db.Column(db.Text, default="")
    status = db.Column(db.Enum(PostStatus), default=PostStatus.DRAFT, nullable=False)
    author_id = protected_column(db.String(126), db.ForeignKey("user.id"), nullable=False)

    author = db.relationship("User", back_populates="posts", info={"protected": True})
    comments = db.relationship("Comment", back_populates="post", info={"protected": True})


class Comment(Model):
    body = db.Column(db.String(1000), nullable=False)
    post_id = protected_column(db.String(126), db.ForeignKey("post.id"), nullable=False)

    post = db.relationship("Post", back_populates="comments", info={"protected": True})

from flask import Flask

from extensions import db, migrate


def create_app():
    app = Flask(__name__)
    app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///blog.db"

    db.init_app(app)
    migrate.init_app(app, db)

    from routes import bp
    app.register_blueprint(bp)
    return app

from flask import Blueprint, abort, jsonify, request
from werkzeug.security import generate_password_hash

from extensions import db
from models import Comment, Post, PostStatus, User

bp = Blueprint("api", __name__)


def body():
    return request.get_json(silent=True) or {}


# ---- users ---------------------------------------------------------------

@bp.post("/users")
def register():
    data = body()
    pw = data.get("password")
    # 400 lists missing name/email/password · 409 if email is taken
    # is_admin and password_hash are protected: a client can't sign up as
    # admin or choose its own hash. The hash is passed as a trusted value.
    user = User.create_or_abort(
        data,
        required=["password"],
        password_hash=generate_password_hash(pw) if pw else None,
    )
    return jsonify(user.to_dict(depth=0, json_safe=True)), 201


PROFILE_FIELDS = {"name"}   # email is set at signup, then changed only by verification


@bp.patch("/users/<id>")
def edit_profile(id):
    user = User.get_or_404(id)
    user.update({k: v for k, v in body().items() if k in PROFILE_FIELDS})
    return jsonify(user.to_dict(depth=0, json_safe=True))


# ---- posts ---------------------------------------------------------------

@bp.post("/users/<user_id>/posts")
def create_post(user_id):
    author = User.get_or_404(user_id)
    # title required; author_id comes from the trusted `author=` value
    post = Post.create_or_abort(body(), fields=["title", "body"], author=author)
    return jsonify(post.to_dict(json_safe=True)), 201


@bp.get("/posts")
def list_published():
    # paginate() has no filters, so build the query and use db.paginate
    stmt = (Post.select()
            .where(Post.status == PostStatus.PUBLISHED)
            .order_by(Post.created_at.desc()))
    page = db.paginate(stmt, page=request.args.get("page", 1, type=int),
                       per_page=10, error_out=False)
    return jsonify({
        "items": [p.to_dict(depth=0, json_safe=True) for p in page.items],
        "total": page.total, "page": page.page, "pages": page.pages,
    })


@bp.get("/posts/<id>")
def read_post(id):
    # depth=1 → author (without password_hash) and live comments
    return jsonify(Post.get_or_404(id).to_dict(json_safe=True))


@bp.patch("/posts/<id>")
def edit_post(id):
    post = Post.get_or_404(id)
    data = body()
    if "status" in data:
        data["status"] = PostStatus(data["status"])   # "published" → enum
    post.update(data)        # author_id, id, timestamps can't change
    return jsonify(post.to_dict(depth=0, json_safe=True))


@bp.delete("/posts/<id>")
def trash_post(id):
    Post.get_or_404(id).soft_delete()
    return "", 204


@bp.get("/trash")
def trash():
    stmt = Post.select(include_deleted=True).where(Post.deleted_at.is_not(None))
    return jsonify([p.to_dict(depth=0, json_safe=True)
                    for p in db.session.scalars(stmt)])


@bp.post("/posts/<id>/restore")
def restore_post(id):
    post = Post.get(id, include_deleted=True) or abort(404)
    post.restore()
    return jsonify(post.to_dict(depth=0, json_safe=True))


# ---- comments ------------------------------------------------------------

@bp.post("/posts/<id>/comments")
def add_comment(id):
    post = Post.get_or_404(id)      # trashed posts 404 automatically
    comment = Comment.create_or_abort(body(), post=post)   # 400 if body is blank
    return jsonify(comment.to_dict(depth=0, json_safe=True)), 201

pip install flask-modelkit Flask-Migrate
export FLASK_APP="app:create_app"
flask db init && flask db migrate -m "initial" && flask db upgrade
flask run

{
  "id": "9c0e…", "created_at": "2026-11-07T09:02:11.401233",
  "updated_at": "2026-11-07T09:40:52.118904", "deleted_at": null,
  "title": "Shipping v2", "body": "…", "status": "published",
  "author_id": "3f1c…",
  "author": {
    "id": "3f1c…", "name": "Ada", "email": "ada@example.com", "is_admin": false,
    "created_at": "…", "updated_at": "…", "deleted_at": null
  },
  "comments": [
    {"id": "a71d…", "body": "Congrats!", "post_id": "9c0e…", "…": "…"}
  ]
}

Shop checkout

An order and its lines must be saved together or not at all. Stage every write with commit=False, then commit once. UUIDs exist before the flush, so you can return the order id or build a payment reference immediately.

from decimal import Decimal

from flask import abort, jsonify, request
from flask_modelkit import BaseModelMixin, protected_column

from extensions import db


class Product(BaseModelMixin, db.Model):
    name = db.Column(db.String(100), nullable=False)
    price = db.Column(db.Numeric(10, 2), nullable=False)
    stock = db.Column(db.Integer, default=0, nullable=False)


class Order(BaseModelMixin, db.Model):
    # Computed and owned by the server: clients can never set these.
    user_id = protected_column(db.String(126), nullable=False)
    total = protected_column(db.Numeric(10, 2), default=Decimal("0"), nullable=False)
    reference = db.Column(db.String(40), unique=True)
    lines = db.relationship("OrderLine", back_populates="order")


class OrderLine(BaseModelMixin, db.Model):
    order_id = db.Column(db.String(126), db.ForeignKey("order.id"), nullable=False)
    product_id = db.Column(db.String(126), db.ForeignKey("product.id"), nullable=False)
    quantity = db.Column(db.Integer, nullable=False)
    unit_price = db.Column(db.Numeric(10, 2), nullable=False)
    order = db.relationship("Order", back_populates="lines")


# `app` and `current_user` come from your project (e.g. Flask-Login)
@app.post("/checkout")
def checkout():
    cart = request.get_json()["items"]        # [{"product_id": "…", "quantity": 2}]
    order = Order(user_id=current_user.id)
    order.reference = f"ORD-{order.id[:8].upper()}"   # id exists before saving
    total = Decimal("0")

    for item in cart:
        product = Product.get(item["product_id"])
        if product is None or product.stock < item["quantity"]:
            db.session.rollback()
            abort(409, description="item unavailable")
        product.stock -= item["quantity"]
        OrderLine.create(order=order, product_id=product.id, quantity=item["quantity"],
                         unit_price=product.price, commit=False)
        total += product.price * item["quantity"]

    order.total = total
    order.save()                       # one commit: order, lines and stock together
    return jsonify(order.to_dict(json_safe=True)), 201
    # "total": "59.98"  (Decimal → string, no float rounding)

Lookup tables

Small reference tables don't need UUIDs or timestamps. Combine IntIdMixin with just the helpers you use, and seed them from a CLI command.

import click
from flask_modelkit import CRUDMixin, IntIdMixin, SerializerMixin

from extensions import db


class Country(IntIdMixin, CRUDMixin, SerializerMixin, db.Model):
    code = db.Column(db.String(2), unique=True, nullable=False)
    name = db.Column(db.String(80), nullable=False)


SEED = [("NG", "Nigeria"), ("GH", "Ghana"), ("KE", "Kenya")]


@app.cli.command("seed-countries")
def seed_countries():
    for code, name in SEED:
        if not Country.exists(code=code):
            Country.create(code=code, name=name, commit=False)
    db.session.commit()
    click.echo(f"{Country.count_all()} countries")


@app.get("/countries")
def countries():
    return jsonify([c.to_dict() for c in Country.all()])
    # [{"id": 1, "code": "NG", "name": "Nigeria"}, …]

API reference

Every public name in flask_modelkit. T means "your model class".

Column reference

All defaults are Python-side; no server_default is set, which keeps Alembic diffs clean. Every column in this table is protected: input passed to update() or create_or_abort() can't set it.

Community & stats

flask-modelkit is free and open source. If it saves you from writing another base model, star it on GitHub. Stars are how other Flask developers find it.

Live numbers

Stars, forks and issues come from the GitHub API. Downloads come from PyPI via pypistats (weekly, monthly) and pepy (all time), and include CI and mirror traffic, so read them as a trend rather than a user count. The numbers refresh at most once an hour.

Star history

Show that you use it

Add a badge to your project's README:

[![built with flask-modelkit](https://img.shields.io/badge/built%20with-flask--modelkit-A84E08)](https://anoziechibuike.github.io/FlaskModelKit/)

Gotchas & FAQ