When managing database schemas, ensuring smooth migrations can be a daunting task, especially when dealing with remote databases. As a software engineer, I’ve found Flyway to be an invaluable tool in automating and managing these migrations. In this blog post, I’ll guide you through the process of using Flyway to run migrations on a remote database, specifically focusing on a macOS setup.
Thank me by sharing on Twitter 🙏
Why Flyway?
Before diving into the how-to, let’s discuss why Flyway is an excellent choice for database migrations:
- Version Control: Flyway uses a version control mechanism for your database, similar to Git for your code.
- Automation: It automates the process of applying and rolling back migrations.
- Flexibility: Flyway supports numerous databases and can be integrated into CI/CD pipelines.
Prerequisites
Before we start, ensure you have the following:
- Flyway installed on your macOS system. You can download it from the official Flyway website.
- A remote database set up and accessible.
- Basic knowledge of SQL and database schemas.
Setting Up Flyway
Installing Flyway
First, download and install Flyway. After downloading, extract the files and add the Flyway executable to your system’s PATH. This allows you to run Flyway commands from any directory in your terminal.
Configuring Flyway
Next, we need to configure Flyway to connect to our remote database and locate our migration scripts. Let’s create a configuration file.
Car Carplay Cable for iPhone 17/17 Pro/Air/16e/16/15 Pro Max/Plus Cable, 2Pack USB A to USB C for CarPlay USBC Cord, iPad, Galaxy, Pixel, Android Accessories Charging Wire Type-C Car Charger Cord 3FT
$7.98 (as of November 20, 2025 01:32 GMT +00:00 - More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)
The Pragmatic Programmer: Your Journey To Mastery, 20th Anniversary Edition (2nd Edition)
$35.59 (as of November 19, 2025 18:29 GMT +00:00 - More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)
Logitech M196 Bluetooth Wireless Mouse, Compact and Portable Mouse for Laptops, Tablets and More, 12-Month Battery, Smooth Tracking, Compatible with PC and Mac, Windows and macOS - Graphite
$9.99 (as of November 20, 2025 01:32 GMT +00:00 - More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)- Create the Configuration File: Navigate to your project directory and create a folder named
infrastructure. Inside this folder, create another folder nameddb. Finally, create a file namedflyway.confwithin thedbfolder. Your directory structure should look like this:
infrastructure/
└── db/
└── flyway.conf- Configure the Database Connection: Open
flyway.confand add the following configurations, replacing the placeholders with your actual database details:
flyway.url=jdbc:<your-database-type>://<your-remote-db-host>:<port>/<database-name>
flyway.user=<your-db-username>
flyway.password=<your-db-password>
flyway.locations=filesystem:infrastructure/db/migrationsHere’s a practical example if you’re using a PostgreSQL database:
flyway.url=jdbc:postgresql://db.example.com:5432/mydatabase
flyway.user=myuser
flyway.password=mypassword
flyway.locations=filesystem:infrastructure/db/migrationsOrganizing Migration Scripts
Creating Migration Scripts
Flyway uses a specific naming convention for migration scripts, typically V1__Description.sql, V2__Description.sql, etc. Create a folder named migrations inside the db directory to store these scripts.
Your updated directory structure should now be:
infrastructure/
└── db/
├── flyway.conf
└── migrations/
├── V1__Initial_migration.sql
└── V2__Add_new_table.sqlWriting Migration Scripts
Inside the migrations folder, create your migration scripts. For example, your V1__Initial_migration.sql might look like this:
CREATE TABLE users (
id SERIAL PRIMARY KEY,
username VARCHAR(50) NOT NULL,
email VARCHAR(100) NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);And V2__Add_new_table.sql might contain:
CREATE TABLE roles (
id SERIAL PRIMARY KEY,
role_name VARCHAR(50) NOT NULL
);Running Migrations
Executing Flyway Commands
With your configuration and migration scripts in place, you can now run Flyway to apply these migrations to your remote database.
Open your terminal, navigate to the Flyway installation directory, and execute the following command:
flyway migrate -configFiles=infrastructure/db/flyway.confThis command tells Flyway to use the specified configuration file and apply the migrations found in the migrations folder to the remote database.
Verifying the Migration
To ensure that the migrations were applied successfully, you can log in to your remote database and check if the tables have been created:
psql -h <your-remote-db-host> -U <your-db-username> -d <your-database-name>Then run:
\dtThis command lists all the tables in the current database, and you should see the users and roles tables.
Conclusion
Using Flyway to manage and automate your database migrations can significantly simplify the process, especially when dealing with remote databases. By following the steps outlined in this guide, you can set up Flyway on your macOS, configure it for your remote database, and organize your migration scripts efficiently. This setup not only saves time but also ensures consistency and reliability in your database schema changes.
