simple-jdbc

Wrapper to simplify working with JDBC.

This project is at an early development stage and the API will change without backwards compatibility.

• Changelog
• API JavaDoc
• Test report
• Coverage report

Usage

This project requires Java 17 or later.

Add Dependency

Add dependency to your Gradle project:

dependencies {
    implementation 'org.itsallcode:simple-jdbc:0.9.0'
}

Add dependency to your Maven project:

<dependency>
  <groupId>org.itsallcode</groupId>
  <artifactId>simple-jdbc</artifactId>
  <version>0.9.0</version>
</dependency>

Features

See features and API documentation in the API documentation.

Examples

See complete example code in ExampleTest.

Imports

import org.itsallcode.jdbc.ConnectionFactory;
import org.itsallcode.jdbc.SimpleConnection;
import org.itsallcode.jdbc.Transaction;
import org.itsallcode.jdbc.resultset.batch.BatchInsert;
import org.itsallcode.jdbc.resultset.SimpleResultSet;
import org.itsallcode.jdbc.resultset.generic.Row;

Create SimpleConnection

final ConnectionFactory connectionFactory = ConnectionFactory.create(Context.builder().build());
try (SimpleConnection connection = connectionFactory.create("jdbc:h2:mem:", "user", "password")) {
    // Use connection...
}

Batch Insert Using Rows

// Define a model record or class
record Name(int id, String name) {
    static void setPreparedStatement(final Name row, final PreparedStatement stmt) throws SQLException {
        stmt.setInt(1, row.id);
        stmt.setString(2, row.name);
    }
}

connection.batchInsert(Name.class)
        .into("NAMES", List.of("ID", "NAME"))
        .rows(Stream.of(new Name(1, "a"), new Name(2, "b"), new Name(3, "c")))
        .mapping(Name::setPreparedStatement)
        .start();

Direct Batch Insert

This allows using batch inserts without creating objects for each row to avoid memory allocations.

try (BatchInsert batch = transaction.batchInsert().into("NAMES", List.of("ID", "NAME")).build()) {
    for (int i = 0; i < 5; i++) {
        final int id = i + 1;
        batch.add(ps -> {
            ps.setInt(1, id);
            ps.setString(2, "name" + id);
        });
    }
}

Transactions

Transaction implements DbOperations which provides most of the methods as SimpleConnection. Transactions will be automatically rolled back during close unless you commit before.

try (Transaction transaction = connection.startTransaction()) {
    // Use transaction
    // ...
    // Commit successful transaction
    transaction.commit();
}

Query Using Generic Row Type

try (SimpleResultSet<Row> rs = connection.query("select * from names order by id")) {
    final List<Row> result = rs.stream().toList();
    assertEquals(3, result.size());
    assertEquals(1, result.get(0).get(0).value());
}

Query Using Row Mapper and Prepared Statement

try (SimpleResultSet<Name> result = connection.query("select id, name from names where id = ?",
        ps -> ps.setInt(1, 2),
        (rs, idx) -> new Name(rs.getInt("id"), rs.getString("name")))) {
    final List<Name> names = result.stream().toList();
    assertEquals(1, names.size());
    assertEquals(new Name(2, "b"), names.get(0));
}

Development

Check if dependencies are up-to-date

./gradlew dependencyUpdates

Building

Install to local maven repository:

./gradlew publishToMavenLocal

Test Coverage

To calculate and view test coverage:

./gradlew check jacocoTestReport
open build/reports/jacoco/test/html/index.html

View Generated Javadoc

./gradlew javadoc
open build/docs/javadoc/index.html

Publish to Maven Central

Preparations

1. Checkout the main branch, create a new branch.
2. Update version number in build.gradle and README.md.
3. Add changes in new version to CHANGELOG.md.
4. Commit and push changes.
5. Create a new pull request, have it reviewed and merged to main.

Perform the Release

1. Start the release workflow

• Run command gh workflow run release.yml --repo itsallcode/simple-jdbc --ref main
• or go to GitHub Actions and start the release.yml workflow on branch main.

2. Update title and description of the newly created GitHub release.
3. After some time the release will be available at Maven Central.