Full Feature Recipe
Step-by-step guide for building a feature that spans model, migration, routes and templates in a Flask + SQLAlchemy application. The order matters: each step depends on the one before it. The details of each step live in the plugins this stack depends on; this skill keeps the order, the boundaries and the checks. template.md is the checklist to fill in for each new feature.
Start from a project that follows flask-dev → project-scaffold (factory, extensions.py, a User model, migrations) and read layers-and-boundaries once: it explains the commit, the app context and the loader rules that the steps below rely on.
Step 1: Define the Model and Migrate
Add the model in models.py (typed 2.0 style; OwnedMixin gives it the user_id that scopes every query; models: sqlalchemy-dev → model-patterns, references/flask-login-user.md):
# models.py (continued)
class NewEntity(OwnedMixin, db.Model):
__tablename__ = 'new_entities'
id: Mapped[int] = mapped_column(primary_key=True)
name: Mapped[str] = mapped_column(String(100))
created_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=utcnow)
Then create, read and apply the migration. The schema reaches the database only through a revision; no table-building call belongs in the app factory (flask-dev → app-patterns says which one and why):
flask db migrate -m "Add new_entities table"
grep -n "create_table\|add_column" migrations/versions/*.py # the revision must contain your change
flask db upgrade
flask db check # models and revisions agree
A revision without your table means the model module is not imported by create_app() (see layers-and-boundaries, section 1).
Step 2: Create the Blueprint
Create routes/new_entity.py. Every query starts from owned_by(Model, current_user.id) (sqlalchemy-dev → query-patterns, references/owner-scoped-queries.md):
# routes/new_entity.py
from flask import Blueprint, render_template
from flask_login import current_user, login_required
from extensions import db
from models import NewEntity
from queries import owned_by
new_entity_bp = Blueprint('new_entity', __name__)
@new_entity_bp.route('/new-entities')
@login_required
def list_entities():
entities = db.session.scalars(
owned_by(NewEntity, current_user.id).order_by(NewEntity.name, NewEntity.id)
).all()
return render_template('new_entity.html', entities=entities)
Register it in create_app():
from routes.new_entity import new_entity_bp
app.register_blueprint(new_entity_bp)
Step 3: Add CRUD Routes
Add create, edit and delete routes in the blueprint. The patterns are in flask-dev → app-patterns, references/crud-views.md. The boundary rules for each of them:
@login_required, and a record fetched by an id from the URL is fetched together with its owner (db.one_or_404(owned_by(...).where(...))): another user's id is a404.- A foreign key the form submits (
client_id) is fetched throughowned_bybefore it is used. - Every
POSTform hascsrf_token; delete is aPOST. - The route ends a successful write with one
commit()and a redirect (layers-and-boundaries, sections 3 and 4).
Step 4: Create the Template
Create templates/new_entity.html extending base.html:
{# templates/new_entity.html #}
{% extends "base.html" %}
{% block title %}New entities{% endblock %}
{% block extra_css %}
<link rel="stylesheet" href="{{ url_for('static', filename='css/new_entity.css') }}">
{% endblock %}
{% block content %}
{% for entity in entities %}
<div class="entity-card">{{ entity.name }}</div>
{% else %}
<p>Nothing here yet.</p>
{% endfor %}
{% endblock %}
Add the list view with search and filter, the add form, the edit form and the delete form with confirmation as in crud-views.md. The template only reads what the route loaded: a relationship it touches must be named in the route's options(...) (lazy='raise' on the model turns a forgotten one into an error).
Step 5: Add Styles
Create static/css/new_entity.css; the template above links it in the extra_css block. Follow the design tokens in base.css.
Step 6: Add Navigation
Add a nav link in base.html:
<a href="{{ url_for('new_entity.list_entities') }}"
class="{% if request.blueprint == 'new_entity' %}active{% endif %}">
New Entity
</a>
Step 7: Verify
flask routesshows every endpoint of the blueprint;flask runand click through Create, Read, Update, Delete.pytest(pytest.initurns SQLAlchemy deprecation warnings into errors) with these tests for the feature:- CRUD round trip through the test client.
- A second user gets
404for the first user's id on edit and delete (owner-scoped-queries.md, Test the Isolation). - The list view issues the same number of statements for 2 rows and for 22 (
layers-and-boundaries, section 5). - Every write is committed: assert in a fresh
with app.app_context():after the request (layers-and-boundaries, section 7).
- Validation: required fields, duplicates, unknown ids.
flask db checkis clean.
Checklist
- Model defined with
OwnedMixin(auser_idforeign key) - Migration created, read, applied;
flask db checkclean - Blueprint created and registered
- CRUD routes with
@login_required - All queries start from
owned_by(Model, current_user.id); foreign keys from forms fetched the same way - Template extends
base.html; no query or unloaded relationship in it - Every
POSTform carriescsrf_token; delete is aPOST - Flash messages for success and error
- CSS file created and linked
- Nav link added to
base.html - Tests: CRUD, two-user isolation, statement count, commit