Set up a database migration

If your project includes a database, you need to set up an initial migrations for it.

To do so, Upsun recommends using Flask-Migrate. If you’ve generated your Flask app using Cookiecutter, your app uses Flask-Migrate by default to handle database migrations.

Otherwise, to install Flask-Migrate, run the following command:

pip install Flask-Migrate

After you’ve installed Flask-Migrate, you need to set up a temporary local environment and allow it to access your database, so you can run the migrate command successfully.

Follow these steps:

1. To set up a local environment where your project can run, run the following command:

   Terminal

   python3 -m venv env && source venv/bin/activate

2. To upgrade pip and install your requirements, run the following commands:

   Terminal

   pip install –upgrade pip
   pip install -r requirements.txt

3. Your database was automatically created and deployed when you first pushed your changes to Upsun. To allow your virtual environment to communicate with your database, run the following command:

   Terminal

   platform tunnel:open -y

   An SSH tunnel to all the services for your app is open.

4. To successfully establish communication between your local environment and your services, you need to set more environment variables.
   To do so, add the following line to your .upsun/config.yaml file:

   .upsun/config.yaml

   export PLATFORM_RELATIONSHIPS="$(platform tunnel:info --encode)"

   The Upsun $PLATFORM_RELATIONSHIPS variable allows you to retrieve information about services and their credentials, while platform tunnel generates that same data locally.

5. To set other required variables, add the following lines:

   .upsun/config.yaml

   export PLATFORM_ENVIRONMENT_TYPE=production
   export PORT=8888
   export PLATFORM_PROJECT_ENTROPY=$(openssl rand -base64 32)

6. To complete the setup of all the required environmental variables in your current shell, run the following command:

   Terminal

   source ./.environment

7. To instruct Flask-migrate to initiate the migration directory, prepare for the migrate command, and generate your migrations, run the following commands:

   Terminal

   flask db init 
   flask db migrate

8. To commit your migrations, run the following commands:

   Terminal

   git add migrations/*
   git commit -m "Adds migrations"

9. If you want future migration changes to be automatically applied, instruct Upsun to run the Flask-migrate upgrade command whenever your app is deployed.
   To do so, customize your deploy hook again. Locate the section dedicated to it:

   .upsun/config.yaml

   # The deploy hook is run after the app container has been started, but before it has started accepting requests.
   # More information: https://docs.upsun.com/create-apps/hooks/hooks-comparison.html#deploy-hook
   deploy: |
       set -eux
       npm run build    

   Add flask db upgrade:

   .upsun/config.yaml

   deploy: |
       set -eux
       npm run build
       flask db upgrade            

10. To commit and push your changes, run the following commands:

    Terminal

    git add .platform.app.yaml
    git commit -m "Adds flask db upgrade to deploy hook"
    platform environment:push -y

    Your Flask app is now fully deployed on Upsun.