Legacy Quickstart¶
Warning
This guide shows you how to initialize the extension and define models when using the SQLAlchemy 1.x style of ORM model classes. We encourage you to upgrade to SQLAlchemy 2.x to take advantage of the new typed model classes.
Initialize the Extension¶
First create the db object using the SQLAlchemy constructor.
When using the SQLAlchemy 1.x API, you do not need to pass any arguments to the SQLAlchemy constructor.
A declarative base class will be created behind the scenes for you.
from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from sqlalchemy.orm import DeclarativeBase
db = SQLAlchemy()
Using custom MetaData and naming conventions¶
You can optionally construct the SQLAlchemy object with a custom
MetaData object. This allows you to specify a custom
constraint naming convention. This makes constraint names consistent and predictable,
useful when using migrations, as described by Alembic.
from sqlalchemy import MetaData
from flask_sqlalchemy import SQLAlchemy
db = SQLAlchemy(metadata=MetaData(naming_convention={
"ix": 'ix_%(column_0_label)s',
"uq": "uq_%(table_name)s_%(column_0_name)s",
"ck": "ck_%(table_name)s_%(constraint_name)s",
"fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
"pk": "pk_%(table_name)s"
}))
Define Models¶
Subclass db.Model to define a model class. This is a SQLAlchemy declarative base
class, it will take Column attributes and create a table.
class User(db.Model):
id = db.Column(db.Integer, primary_key=True)
username = db.Column(db.String, unique=True, nullable=False)
email = db.Column(db.String)
For convenience, the extension object provides access to names in the sqlalchemy and
sqlalchemy.orm modules. So you can use db.Column instead of importing and using
sqlalchemy.Column, although the two are equivalent.
Unlike plain SQLAlchemy, Flask-SQLAlchemy’s model will automatically generate a table name
if __tablename__ is not set and a primary key column is defined.
The table name "user" will automatically be assigned to the model’s table.
Create the Tables¶
Defining a model does not create it in the database. Use create_all()
to create the models and tables after defining them. If you define models in submodules,
you must import them so that SQLAlchemy knows about them before calling create_all.
with app.app_context():
db.create_all()
Querying the Data¶
You can query the data the same way regardless of SQLAlchemy version. See Modifying and Querying Data for more information about queries.