Merge pull request #54 from tecladocode/jose/cou-104-write-database-migrations-section-with

Author: jslvtr

docs/docs/09_flask_migrate/01_why_use_database_migrations/README.md

@@ -0,0 +1,18 @@
+---
+title: Why use database migrations?
+description: Learn about database migrations and what they are useful for.
+---
+
+# Why use database migrations?
+
+As you work on your application, particularly over a long time, it is unavoidable that you will want to add columns to your models, or even add new models entirely.
+
+Making the changes directly to the models without something like Alembic and Flask-Migrate will mean that the existing database tables and the model definitions will be out of sync. When that happens, SQLAlchemy usually complains and your application won't work.
+
+An option is to delete everything and get SQLAlchemy to re-create the tables. Obviously, this is not good if you have data in the database as you would lose all the data.
+
+We can use Alembic to detect the changes to the models, and what steps are necessary to "upgrade" the database so it matches the new models. Then we can use Alembic to actually modify the database following the upgrade steps.
+
+Alembic also tracks each of these migrations over time, so that you can easily go to a past version of the database. This is useful if bugs are introduced or the feature requirements change.
+
+Since Alembic tracks all the migrations over time, we can use it to create the tables from scratch, simply by applying the migrations one at a time until we reach the latest one (which should be equal to the current one).

docs/docs/09_flask_migrate/02_add_flask_migrate_to_app/README.md

@@ -0,0 +1,39 @@
+---
+title: How to add Flask-Migrate to our Flask app
+description: Integrating your Flask app with Flask-Migrate is relatively straightforward. Learn how to do it in this lecture.
+---
+
+# How to add Flask-Migrate to our Flask app
+
+Adding Flask-Migrate to our app is simple, just install it and add a couple lines to `app.py`.
+
+To install:
+
+```
+pip install flask-migrate
+```
+
+This will also install Alembic, since it is a dependency.
+
+Then we need to add 2 lines to `app.py` (highlighted):
+
+```py
+from flask_smorest import Api
+# highlight-start
+from flask_migrate import Migrate
+# highlight-end
+
+import models
+
+app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
+app.config["PROPAGATE_EXCEPTIONS"] = True
+db.init_app(app)
+# highlight-start
+migrate = Migrate(app, db)
+# highlight-end
+api = Api(app)
+
+@app.before_first_request
+def create_tables():
+    db.create_all()
+```

docs/docs/09_flask_migrate/03_initialize_database_flask_db_init/README.md

@@ -0,0 +1,54 @@
+---
+title: Initialize your database with Flask-Migrate
+description: "Learn the first steps when starting with Flask-Migrate: initializing the database."
+---
+
+# Initialize the database with Flask-Migrate
+
+Activate your virtual environment and run this command:
+
+```
+flask db init
+```
+
+This will create a `migrations` folder inside your project folder.
+
+In the `migrations` folder you'll find a few things:
+
+- The `versions` folder is where migration scripts will be placed. These will be used by Alembic to make changes to the database.
+- `alembic.ini` is the Alembic configuration file.
+- `env.py` is a script used by Alembic to generate migration files.
+- `script.py.mako` is the template file for migration files.
+
+## Generate the first migration to set up the database
+
+Now that we're set up, we need to make sure that the database we want to use is currently empty. In our case, since we're using SQLite, just delete `data.db`.
+
+Then, run this command:
+
+```
+flask db migrate
+```
+
+This will create the migration file.
+
+
+:::caution
+It's important to double-check the migration script and make sure it is correct! Compare it with your model definitions and make sure nothing is missing.
+:::
+
+Now let's actually apply the migration:
+
+```
+flask db upgrade
+```
+
+This will create the `data.db` file. If you were using another RDBMS (like PostgreSQL or MySQL), this command would create the tables using the existing model definitions.
+
+:::info How does the database know which version it's on?
+When using Alembic to create the database tables from scratch, it creates an extra table with a single row, that stores the current migration version.
+
+You'll note in each migration script there is information about the previous migration and the next migration.
+
+This is why it's important to **never rename the migration files or change the revision identifiers at the top of those files**.
+:::

docs/docs/09_flask_migrate/04_change_models_generate_alembic_migration/README.md

@@ -0,0 +1,46 @@
+---
+title: Change SQLAlchemy models and generate a migration
+description: Use Flask-Migrate to generate a new database migration after changing your SQLAlchemy models.
+---
+
+# Change SQLAlchemy models and generate a migration
+
+Let's make a change to one of our SQLAlchemy models and then generate another migration script. This is what we will do every time we want to make changes to our models and our database schema.
+
+```python title="models/item.py"
+from db import db
+
+
+class ItemModel(db.Model):
+    __tablename__ = "items"
+
+    id = db.Column(db.Integer, primary_key=True)
+    name = db.Column(db.String(80), unique=True, nullable=False)
+    # highlight-start
+    description = db.Column(db.String)
+    # highlight-end
+    price = db.Column(db.Float(precision=2), unique=False, nullable=False)
+
+    store_id = db.Column(
+        db.Integer, db.ForeignKey("stores.id"), unique=False, nullable=False
+    )
+    store = db.relationship("StoreModel", back_populates="items")
+
+    tags = db.relationship("TagModel", back_populates="items", secondary="items_tags")
+```
+
+Here we're adding a simple column, just a string that doesn't have any constraints.
+
+Now let's go to the terminal and run the command:
+
+```
+flask db migrate
+```
+
+This will now generate _another migration script_ that you have to double-check. Make sure to check the upgrade and downgrade functions.
+
+When you're happy with the contents, apply the migration:
+
+```
+flask db upgrade
+```

docs/docs/09_flask_migrate/05_manually_review_modify_migrations/README.md

@@ -0,0 +1,79 @@
+---
+title: Manually review and modify database migrations
+description: Alembic can generate database migrations parting from model changes, but sometimes we need to modify them manually.
+---
+
+# Manually review and modify database migrations
+
+## Default column values
+
+When you add a column that uses a default value, any rows that existed previously will have `null` as the value.
+
+You'll have to go into the database to add the default value to those rows.
+
+You can also do this during the migration, since Alembic migrations can execute any arbitrary SQL queries.
+
+Here's an example for a column being added with a default value:
+
+```py title="migrations/versions/sample_migration.py"
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = "9c386e4052be"
+down_revision = "713af8a4cb34"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column(
+        "invoices",
+        sa.Column("enable_downloads", sa.Boolean(), nullable=True, default=False),
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_column("invoices", "enable_downloads")
+    # ### end Alembic commands ###
+```
+
+You can see that we're adding a column called `enable_downloads` to the `invoices` table. The default value for new rows will be `False`, but what is the value for all the invoices we already have in the database?
+
+The value will be undefined, or `null`.
+
+What we must do is tell Alembic to insert `False` into each of the existing rows. We can do that with SQL:
+
+```py title="migrations/versions/sample_migration.py"
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = "9c386e4052be"
+down_revision = "713af8a4cb34"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column(
+        "invoices",
+        sa.Column("enable_downloads", sa.Boolean(), nullable=True, default=False),
+    )
+    # highlight-start
+    op.execute("UPDATE invoices SET enable_downloads = False")
+    # highlight-end
+    # ### end Alembic commands ###
+
+
+def downgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_column("invoices", "enable_downloads")
+    # ### end Alembic commands ###
+```

docs/docs/09_flask_migrate/_category_.json

@@ -0,0 +1,4 @@
+{
+    "label": "Database migrations with Alembic and Flask-Migrate",
+    "position": 9
+}

project/06-add-db-migrations/.flaskenv

@@ -0,0 +1,2 @@
+FLASK_APP=app
+FLASK_ENV=development

project/06-add-db-migrations/.python-version

@@ -0,0 +1 @@
+3.10.4

project/06-add-db-migrations/Dockerfile

@@ -0,0 +1,7 @@
+FROM python:3.10
+EXPOSE 5000
+WORKDIR /app
+COPY ./requirements.txt requirements.txt
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+COPY . .
+CMD ["flask", "run", "--host", "0.0.0.0"]

project/06-add-db-migrations/app.py

@@ -0,0 +1,38 @@
+from flask import Flask
+from flask_smorest import Api
+from flask_migrate import Migrate
+
+import models
+
+from db import db
+from resources.item import blp as ItemBlueprint
+from resources.store import blp as StoreBlueprint
+from resources.tag import blp as TagBlueprint
+
+
+def create_app(db_url=None):
+    app = Flask(__name__)
+    app.config["API_TITLE"] = "Stores REST API"
+    app.config["API_VERSION"] = "v1"
+    app.config["OPENAPI_VERSION"] = "3.0.3"
+    app.config["OPENAPI_URL_PREFIX"] = "/"
+    app.config["OPENAPI_SWAGGER_UI_PATH"] = "/swagger-ui"
+    app.config[
+        "OPENAPI_SWAGGER_UI_URL"
+    ] = "https://cdn.jsdelivr.net/npm/swagger-ui-dist/"
+    app.config["SQLALCHEMY_DATABASE_URI"] = db_url or "sqlite:///data.db"
+    app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
+    app.config["PROPAGATE_EXCEPTIONS"] = True
+    db.init_app(app)
+    migrate = Migrate(app, db)
+    api = Api(app)
+
+    @app.before_first_request
+    def create_tables():
+        db.create_all()
+
+    api.register_blueprint(ItemBlueprint)
+    api.register_blueprint(StoreBlueprint)
+    api.register_blueprint(TagBlueprint)
+
+    return app

project/06-add-db-migrations/conftest.py

@@ -0,0 +1,19 @@
+import pytest
+from app import create_app
+
+
+@pytest.fixture()
+def app():
+    app = create_app("sqlite://")
+    app.config.update(
+        {
+            "TESTING": True,
+        }
+    )
+
+    yield app
+
+
+@pytest.fixture()
+def client(app):
+    return app.test_client()

project/06-add-db-migrations/db.py

@@ -0,0 +1,3 @@
+from flask_sqlalchemy import SQLAlchemy
+
+db = SQLAlchemy()

project/06-add-db-migrations/migrations/README

@@ -0,0 +1 @@
+Single-database configuration for Flask.

project/06-add-db-migrations/migrations/alembic.ini

@@ -0,0 +1,50 @@
+# A generic, single database configuration.
+
+[alembic]
+# template used to generate migration files
+# file_template = %%(rev)s_%%(slug)s
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+
+# Logging configuration
+[loggers]
+keys = root,sqlalchemy,alembic,flask_migrate
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[logger_flask_migrate]
+level = INFO
+handlers =
+qualname = flask_migrate
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S