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?
| Database | Usage |
|---|---|
| H2 | Lightweight in-memory database, great for development & testing |
| PostgreSQL | Open-source, powerful RDBMS widely used in production |
| MySQL | Popular and mature RDBMS, supported by many hosting providers |
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:
|
1 2 3 4 |
com.kscodes.micronaut.school |
Using Micronaut CLI
|
1 2 3 4 |
mn create-app com.kscodes.micronaut.school --build=maven --lang=java |
Add Features
You can directly include database support and migration tool using:
|
1 2 3 4 |
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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 |
<dependencies> <!-- Micronaut Runtime --> <dependency> <groupid>io.micronaut</groupid> <artifactid>micronaut-runtime</artifactid> </dependency> <!-- Micronaut Data JDBC --> <dependency> <groupid>io.micronaut.data</groupid> <artifactid>micronaut-data-jdbc</artifactid> </dependency> <!-- Connection Pool --> <dependency> <groupid>io.micronaut.sql</groupid> <artifactid>micronaut-jdbc-hikari</artifactid> </dependency> <!-- Database Drivers --> <dependency> <groupid>com.h2database</groupid> <artifactid>h2</artifactid> <scope>runtime</scope> </dependency> <dependency> <groupid>mysql</groupid> <artifactid>mysql-connector-java</artifactid> <scope>runtime</scope> </dependency> <dependency> <groupid>org.postgresql</groupid> <artifactid>postgresql</artifactid> <scope>runtime</scope> </dependency> <!-- Flyway DB Migration --> <dependency> <groupid>io.micronaut.flyway</groupid> <artifactid>micronaut-flyway</artifactid> </dependency> </dependencies> |
๐ 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)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
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
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
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
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
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:
|
1 2 3 4 5 6 7 8 |
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
| Problem | Solution |
|---|---|
Database Connection Failed | Check database URL, username, and password |
Driver class not found | Ensure correct driver dependency is added |
| Port already in use | Change database or application port |
| H2 not accessible | Use proper H2 JDBC URL format |
๐งช 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.