Iron, a simple JDBC Wrapper.

---

Iron

Iron is a simple yet powerful JDBC Wrapper used by ingot.gg backend services to interact with our SQL Databases.

Feel free to read the Contribution Guide to learn how to contribute to Iron or report issues.

Importing

Tags & Releases can be found on our Jitpack.

Gradle

repositories {
  maven("https://jitpack.io")
}

dependencies {
    implementation("gg.ingot:iron:TAG")
}

Maven

<repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
</repository>

<dependency>
    <groupId>gg.ingot</groupId>
    <artifactId>iron</artifactId>
    <version>TAG</version>
</dependency>

Features

• Simple Connection Pooling
• Query Model Mapping
• Built-in JSON Field Deserialization
• Kotlin Coroutines Support

Basic Usage

Connection

@Model // model annotations are required 
data class User(val id: Int, val firstName: String, val lastName: String)

suspend fun main() {
    val connection = Iron("jdbc:sqlite:memory:").connect()

    val user = connection.transaction {
        execute("CREATE TABLE users (id INTEGER PRIMARY KEY, firstName TEXT NOT NULL, lastName TEXT NOT NULL)")
        execute("INSERT INTO users (firstName, lastName) VALUES ('Ingot', 'Team')")
        
        query("SELECT * FROM users LIMIT 1;")
            .single<User>()
    }

    println(user)
}

Pooled Connection

suspend fun main() {
    val connection = Iron(
        "jdbc:postgresql://localhost:5432/postgres",
        /** Increasing maximum connections automatically makes it pooled. */
        IronSettings(
            minimumActiveConnections = 2,
            maximumConnections = 8
        )
    ).connect()

    // Pooled connections are identical to single connections
    // in terms of how you interact with them, but more connections
    // allow for more throughput in your application.
    val sum = connection.query("SELECT 1+1;")
        .columnSingle<Int>() // Gets the only value from the only column, throws if there's more than 1 value or column

    println(sum)
}

Query Model Mapping

@Model
data class PartialUser(val firstName: String, val lastName: String)

suspend fun main() {
    val connection = Iron("jdbc:sqlite:memory:").connect()

    // we can easily map data from our queries to a model.
    val user = connection.query("SELECT firstName, lastName FROM users LIMIT 1;")
        .single<PartialUser>() // Enforces a row check, throws if more or less than 1 is returned
    
    // Or get all the users in the query
    val users = connection.prepare("SELECT firstName, lastName FROM users WHERE age > ?", 18)
        .all<PartialUser>()
    
    println(user)
    println(users.size)
}

JSON Deserialization Support

data class Example(val field: String)
@Model
data class ExampleModel(
    @Column(json = true)
    val example: Example
)

suspend fun main() {
    val connection = Iron(
        "jdbc:sqlite:memory:",
        IronSettings(
            /** Built-in GSON & Kotlinx Serialization support. */
            serialization = SerializationAdapter.Gson(Gson())
        )
    ).connect()

    val model = connection.query("SELECT example FROM table LIMIT 1;")
        .singleNullable<ExampleModel>()
    println(model?.example)
}