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.
