stormify/onl.ycode.stormify/DbField

DbField

annotation class DbField(val name: String = "", val primaryKey: Boolean = false, val primarySequence: String = "", val autoIncrement: Boolean = false, val creatable: Boolean = true, val updatable: Boolean = true, val enumAsString: Boolean = false)

Controls how a Kotlin property maps to a database column with advanced configuration options.

This annotation is optional. Most properties work fine without it, using automatic mapping based on naming conventions. Use @DbField only when you need:

Custom column names
Primary key configuration
Sequence-based ID generation
Fine-grained control over INSERT/UPDATE operations

Basic Usage Examples

data class User(
    // Automatic mapping - no annotation needed
    var name: String,        // Maps to column: name
    var emailAddress: String // Maps to column: email_address (snake_case)
)

data class User(
    // Custom column name
    @DbField(name = "user_id")
    var id: Int,

    // Primary key with auto-increment
    @DbField(primaryKey = true)
    var id: Int,

    // Primary key with sequence (Oracle/PostgreSQL)
    @DbField(primaryKey = true, primarySequence = "user_id_seq")
    var id: Int,

    // Read-only field (generated by database)
    @DbField(creatable = false, updatable = false)
    var createdAt: Long,

    // Create-only field (set once, never updated)
    @DbField(updatable = false)
    var createdBy: String,

    // Update-only field (skip on insert)
    @DbField(creatable = false)
    var lastModified: Long
)

Primary Key Configuration

// Simple auto-increment primary key
data class User(
    @DbField(primaryKey = true)
    var id: Int = 0,
    var name: String
)

// Sequence-based primary key (Oracle/PostgreSQL)
data class User(
    @DbField(primaryKey = true, primarySequence = "user_id_seq")
    var id: Int = 0,
    var name: String
)

// Composite primary key
data class OrderDetail(
    @DbField(primaryKey = true)
    var orderId: Int,
    @DbField(primaryKey = true)
    var productId: Int,
    var quantity: Int
)

Field Lifecycle Control

data class AuditedEntity(
    var id: Int,
    var name: String,

    // Set by database on INSERT, never updated
    @DbField(creatable = false, updatable = false)
    var createdAt: Timestamp,

    // Set once on INSERT, cannot be changed
    @DbField(updatable = false)
    var createdBy: String,

    // Updated on UPDATE, not set on INSERT
    @DbField(creatable = false)
    var modifiedAt: Timestamp?,

    // Updated on UPDATE, not set on INSERT
    @DbField(creatable = false)
    var modifiedBy: String?
)

Custom Column Mapping

data class User(
    // Legacy database column name
    @DbField(name = "usr_id")
    var id: Int,

    // Abbreviated column name
    @DbField(name = "email")
    var emailAddress: String,

    // Column with different naming convention
    @DbField(name = "FirstName")
    var firstName: String
)

Comparison with JPA Annotations

Stormify also supports JPA annotations:

// Stormify annotations
@DbField(primaryKey = true)
var id: Int

// JPA equivalent (also supported)
@Id
var id: Int

// Stormify custom column
@DbField(name = "email")
var emailAddress: String

// JPA equivalent (also supported)
@Column(name = "email")
var emailAddress: String

Excluding Fields

To exclude a field from database operations, mark it as transient. All three forms are recognized:

JPA: @javax.persistence.Transient
Kotlin: @kotlin.jvm.Transient
Java: the transient keyword

data class User(
    var id: Int,
    var name: String,

    // Excluded from all database operations
    @Transient
    var tempData: String = ""
)

Important Notes

Annotation is optional - only use when automatic mapping isn't sufficient
Primary key fields should have default values (e.g., var id: Int = 0)
creatable = false, updatable = false means field is completely managed by database
For composite keys, mark all key fields with primaryKey = true
Sequences are database-specific (Oracle, PostgreSQL support, MySQL doesn't)