Setting Up a Micronaut App with H2 / PostgreSQL / MySQL

Micronaut makes building modern cloud-native applications extremely simple, but one of the most important parts of any application is data persistence — saving and retrieving data from a database.

In this post, we will learn how to create a Micronaut project and connect a Micronaut App with H2 / PostgreSQL / MySQL

🔧 Why H2, PostgreSQL, and MySQL?

By learning how to configure all 3, you’ll be able to easily switch between development, test, and production environments.

📦 Prerequisites

Before you begin, make sure you have:

• ✅ Java 17 or higher (Java 21 is even better)
• ✅ Micronaut CLI installed — optional but very helpful
• ✅ Maven installed
• ✅ PostgreSQL or MySQL server running (for real database connection)

Check Installing Micronaut CLI and Setting Up Your First Project

🔨 Step 1: Create Your Micronaut Project

We will create a project for our example School Management System using package name:

com.kscodes.micronaut.school

Using Micronaut CLI

mn create-app com.kscodes.micronaut.school --build=maven --lang=java

Add Features

You can directly include database support and migration tool using:

mn create-app com.kscodes.micronaut.school --features=data-jdbc,jdbc-hikari,mysql,postgres,h2,flyway --build=maven

Alternative: Use Micronaut Launch

You can also use Micronaut Launch to generate the project visually.

📄 Step 2: Add Maven Dependencies (Manual Option)

If you are manually modifying your project, ensure your pom.xml contains:

    
    
        io.micronaut
        micronaut-runtime
    

    
    
        io.micronaut.data
        micronaut-data-jdbc
    

    
    
        io.micronaut.sql
        micronaut-jdbc-hikari
    

    
    
        com.h2database
        h2
        runtime
    

    
        mysql
        mysql-connector-java
        runtime
    

    
        org.postgresql
        postgresql
        runtime
    

    
    
        io.micronaut.flyway
        micronaut-flyway
    

🗄 Step 3: Configure Database Connection

Micronaut uses application.yml or environment-specific YAML files to configure datasources.

🔥 Tip: You can easily switch between databases by commenting/uncommenting the datasource you want.

Configuration for H2 (for development & testing)

datasources:
  default:
    url: jdbc:h2:mem:devDb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE
    username: sa
    password:
    driverClassName: org.h2.Driver
    dialect: H2

micronaut:
  application:
    name: school-management

✅ In-memory database — no installation needed.

✅ Fast startup.

✅ Great for writing unit & integration tests.

Configuration for PostgreSQL

datasources:
  default:
    url: jdbc:postgresql://localhost:5432/schooldb
    username: your_postgres_user
    password: your_postgres_password
    driverClassName: org.postgresql.Driver
    dialect: POSTGRES

micronaut:
  application:
    name: school-management

🔧 Make sure your PostgreSQL server is running.

🔧 Replace credentials with your actual database username & password.

Configuration for MySQL

datasources:
  default:
    url: jdbc:mysql://localhost:3306/schooldb
    username: your_mysql_user
    password: your_mysql_password
    driverClassName: com.mysql.cj.jdbc.Driver
    dialect: MYSQL

micronaut:
  application:
    name: school-management

🔧 MySQL 8+ recommended.

🔧 Use MySQL Workbench or CLI to create the database if not already created.

🏗 Recommended Directory Structure

We will follow this package structure:

com.kscodes.micronaut.school
  ├── controllers
  ├── entities
  ├── repositories
  ├── services

• controllers → REST API endpoints
• entities → Database entity classes
• repositories → Database access layer
• services → Business logic

👉 This structure keeps your code clean and maintainable.

⚡ Step 4: Running the Application

You can run the Micronaut app using Maven:

mvnw mn:run

✅ If your configuration is correct, Micronaut will successfully start and connect to the database.

🐞 Common Issues and Troubleshooting

🧪 Why Use H2 for Local Development?

• Faster feedback loop.
• No external dependency.
• Easily resettable database.

You can later switch to PostgreSQL/MySQL for integration or production.

🌐 External References

• Micronaut Data JDBC Guide
• Micronaut SQL Guide