MySQL Persistence Setup - 310-Blueprint/fairshare GitHub Wiki

This page records the developer setup for issue #22 and the database migration workflow for issue #37.

Setting up a development machine

Installing MySQL 8.4, installing a Docker runtime, creating the local database and setting the environment variables all differ by operating system. Follow the page for the platform in use, then return here for the migration workflow.

Linux is not documented. The macOS page transfers apart from the Homebrew commands and the zsh configuration files.

What the persistence foundation provides

  • Spring Data JPA for future entity and repository work.
  • MySQL Connector/J as the runtime database driver.
  • Flyway for version-controlled database schema migrations.
  • Credentials supplied only through environment variables.
  • A Testcontainers integration test that applies migrations, inserts a row, reads it back, and disposes of the isolated MySQL database after the test run.

Feature-specific entities, repositories, services, and UI work are outside issue #22.

Credentials

The backend reads SPRING_DATASOURCE_URL, SPRING_DATASOURCE_USERNAME and SPRING_DATASOURCE_PASSWORD. Spring Boot maps these standard environment variables to its datasource configuration, so no matching entry in application.properties is required.

The platform pages show where to set them so that they persist across terminal sessions and are visible to IDE run configurations.

Do not store their real values in Git, application.properties, or a committed environment file. The password is for local development only.

Flyway applies pending migrations before Hibernate starts. The project defaults Hibernate schema handling to validate, so Hibernate checks that mapped entities match the migrated schema without creating or altering tables automatically.

Database schema migrations

Production migration files are stored in backend/src/main/resources/db/migration. Spring Boot applies pending migrations automatically when the backend starts and records them in the flyway_schema_history table. The current V1__create_users_table.sql migration creates the users table.

To add a schema change:

  1. Work from a feature branch for an approved issue.
  2. Find the highest production migration version in backend/src/main/resources/db/migration.
  3. Add a new file using V<VERSION>__<DESCRIPTION>.sql, for example V2__create_groups_table.sql.
  4. Put the required MySQL schema change in the new file. Include the matching JPA mapping change in the same pull request when applicable.
  5. Run the complete backend verification before requesting review.

Use a unique, increasing version. Do not edit or rename a migration after it has been applied to a shared database. Add another migration to correct it. Invalid migration names fail startup because spring.flyway.validate-migration-naming=true.

Test-only migrations are stored in backend/src/test/resources/db/migration. They run after the production migrations during tests and are not packaged with the application.

The MySQL integration test

Testcontainers starts mysql:8.4 automatically. Flyway applies the production migrations and the test-only persistence_probe migration before the test accesses the table. No local database credentials are used by this test.

Docker must be available: verification fails rather than silently skipping the persistence test when Docker is unavailable. GitHub Actions runs the same Maven command on its Docker-enabled Ubuntu runner.

The command to run it is on the platform pages, under verifying the stack.

⚠️ **GitHub.com Fallback** ⚠️