MySQL Persistence Setup

MySQL Persistence Setup

This page records the developer setup for issue #22.

What the persistence foundation provides

• Spring Data JPA for future entity and repository work.
• MySQL Connector/J as the runtime database driver.
• Credentials supplied only through environment variables.
• A Testcontainers integration test that creates a table, 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.

Required local configuration

Install MySQL 8.4. Then sign in to MySQL as an administrative user (for a standard local installation, run mysql -u root -p) and create the local database and development user:

CREATE DATABASE fairshare;
CREATE USER 'fairshare_dev'@'localhost' IDENTIFIED BY 'your-local-password';
GRANT ALL PRIVILEGES ON fairshare.* TO 'fairshare_dev'@'localhost';
FLUSH PRIVILEGES;

Replace your-local-password with a password used only for local development. Set these variables before starting the backend, using the same password for SPRING_DATASOURCE_PASSWORD:

Environment variable	Purpose	Example
SPRING_DATASOURCE_URL	JDBC connection URL	jdbc:mysql://localhost:3306/fairshare
SPRING_DATASOURCE_USERNAME	Local MySQL username	fairshare_dev
SPRING_DATASOURCE_PASSWORD	Local MySQL password	Use your own local password

Spring Boot maps these standard environment variables to its datasource configuration. Do not store their real values in Git, application.properties, or a committed environment file.

The project defaults Hibernate schema handling to validate. This checks that mapped entities match the existing schema without creating or altering tables automatically.

PowerShell

$env:SPRING_DATASOURCE_URL = "jdbc:mysql://localhost:3306/fairshare"
$env:SPRING_DATASOURCE_USERNAME = "fairshare_dev"
$env:SPRING_DATASOURCE_PASSWORD = "your-local-password"

Set-Location backend
.\mvnw.cmd spring-boot:run

macOS or Linux

export SPRING_DATASOURCE_URL="jdbc:mysql://localhost:3306/fairshare"
export SPRING_DATASOURCE_USERNAME="fairshare_dev"
export SPRING_DATASOURCE_PASSWORD="your-local-password"

cd backend
./mvnw spring-boot:run

Run the MySQL integration test

Start Docker, then run the complete backend verification:

Set-Location backend
.\mvnw.cmd --batch-mode clean verify

Testcontainers starts mysql:8.4 automatically. 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.