KQLite/com.kqlite.table/KQLiteTable

KQLiteTable

abstract class KQLiteTable @JvmOverloads constructor(name: String, temp: Boolean = false, ifNotExists: Boolean = true, strict: Boolean = false, withoutRowId: Boolean = false)

Represents a database table definition in KQLite.

This abstract class serves as the foundation for creating type-safe table schemas. To define a table, create a singleton object that inherits from KQLiteTable. Inside the object, use the provided DSL functions (e.g., longColumn, stringColumn) to declare the columns and their constraints.

The core responsibilities of this class are:

Column Definition: Define columns using predefined functions like integerColumn, textColumn, etc.
Constraint Definition: Specify table-level constraints using the constraints property.
Index Definition: Create indexes on columns using the indexes property.

Example Usage:

object Products : KQLiteTable("products") {
    val productId = longColumn("ProductId").primaryKey()
    val name = textColumn("Name").notNull()
    val price = doubleColumn("Price").notNull()
    val discount = doubleColumn("Discount").notNull().default(0.0)
    val inTime = dateTimeColumn("InTime").default(CURRENT_TIMESTAMP)
    val propertiesJson = jsonObjectColumn("Properties")

    override val constraints: (ConstraintBuilder.() -> Unit)? = {
        // Ensure the price is always positive
        check { price GT 0.0 }

        // Ensure the discount is not greater than the price
        constraint("chk_discount").check { discount LTE price }
    }

    override val indexes: (IndexBuilder.() -> Unit)? = {
        createIndex("price_index").on(price)
    }
}

The class provides builders for defining table-level constraints and indexes, as well as a rich set of column types and modifiers to model a SQLite table accurately.

Author

MOHAMMAD AZIM ANSARI

Parameters

name

The name of the table in the database. It will be escaped for special characters.

temp

If true, creates a TEMP table. Default is false.

ifNotExists

If true, the CREATE TABLE statement will include IF NOT EXISTS. Default is true.

strict

If true, enables STRICT mode for the table, enforcing more rigid data type validation.

See also

ConstraintBuilder

Inheritors

Constructors

constructor(name: String, temp: Boolean = false, ifNotExists: Boolean = true, strict: Boolean = false, withoutRowId: Boolean = false)

Properties

protected open val constraints: ConstraintBuilder.() -> Unit? = null

Defines table-level constraints using a DSL.

protected open val indexes: IndexBuilder.() -> Unit? = null

Defines indexes on the table to improve query performance.

val rowId: KQLiteColumn<Long>

Represents the SQLite rowid column.

val tableName: String

The escaped and safe name of the table, ready to be used in SQL queries.

Functions

infix fun KQLiteTable.AS(alias: String): AliasTable

Creates an alias for a table using SQL AS.

protected fun <T> KQLiteColumn<T>.autoIncrement(): KQLiteColumn<T>

Marks this INTEGER PRIMARY KEY column of type Long to AUTOINCREMENT.

protected fun blobColumn(name: String): KQLiteColumn<ByteArray?>

Defines a nullable BLOB column in the table, intended to store a ByteArray.

protected fun booleanColumn(name: String): KQLiteColumn<Boolean?>

Defines a nullable BOOLEAN column in the table, intended to store a Boolean.

byteArrayColumn

protected fun byteArrayColumn(name: String): KQLiteColumn<ByteArray?>

Defines a nullable BLOB column in the table, intended to store a ByteArray.

protected fun byteColumn(name: String): KQLiteColumn<Byte?>

Defines a nullable TINYINT column in the table, intended to store a Byte.

protected fun charColumn(name: String): KQLiteColumn<Char?>

Defines a nullable CHAR(1) column in the table, intended to store a single Char.

protected fun <T> KQLiteColumn<T>.check(clause: Clause.(KQLiteColumn<T>) -> Unit): KQLiteColumn<T>

Adds a CHECK constraint to this column.

protected fun <T> KQLiteColumn<T>.collate(collation: Collate): KQLiteColumn<T>

Adds a COLLATE clause to this column, specifying the text comparison behavior.

protected fun dateColumn(name: String): KQLiteColumn<KQLiteDate?>

Defines a nullable DATE column to store a date.

protected fun dateTimeColumn(name: String): KQLiteColumn<KQLiteDateTime?>

Defines a nullable DATETIME column to store a dateTime.

protected fun <T> KQLiteColumn<T>.default(value: T): KQLiteColumn<T>

Sets a DEFAULT value for this column.

protected fun <T> KQLiteColumn<T>.default(value: KQLiteColumn<out T>): KQLiteColumn<T>

Sets a DEFAULT value for this column using com.kqlite.column.Literal.

protected fun doubleColumn(name: String): KQLiteColumn<Double?>

Defines a nullable REAL column in the table, intended to store a Double.

protected fun <E : Enum<E>> enumColumn(name: String, entries: EnumEntries<E>): KQLiteColumn<E?>

Defines a nullable ENUM column to store an enum value by its name.

protected fun floatColumn(name: String): KQLiteColumn<Float?>

Defines a nullable FLOAT column in the table, intended to store a Float.

generatedAlwaysAs

protected fun <T> KQLiteColumn<T>.generatedAlwaysAs(column: KQLiteColumn<*>, type: Generated? = null): KQLiteColumn<T>

Defines this column as a GENERATED ALWAYS AS whose value is computed from other columns.

fun getColumns(): List<KQLiteColumn<*>>

Retrieves a list of all columns defined in this table.

protected fun intColumn(name: String): KQLiteColumn<Int?>

Defines a nullable INT column in the table, intended to store an Int.

protected fun integerColumn(name: String): KQLiteColumn<Long?>

Defines a nullable INTEGER column in the table.

jsonArrayColumn

protected fun jsonArrayColumn(name: String): KQLiteColumn<KQLiteJsonArray?>

Defines a nullable JSON ARRAY column to store a JSON array.

protected fun jsonColumn(name: String): KQLiteColumn<KQLiteJson?>

Defines a nullable JSON column to store any valid JSON data.

jsonObjectColumn

protected fun jsonObjectColumn(name: String): KQLiteColumn<KQLiteJsonObject?>

Defines a nullable JSON OBJECT column to store a JSON object.

julianDayColumn

protected fun julianDayColumn(name: String): KQLiteColumn<KQLiteJulianDay?>

Defines a nullable DOUBLE column to store a Julian Day Number.

protected fun longColumn(name: String): KQLiteColumn<Long?>

Defines a nullable INTEGER column in the table, intended to store a Long.

protected fun <T> KQLiteColumn<T>.onConflict(action: Action): KQLiteColumn<T>

Specifies the ON CONFLICT resolution algorithm for a UNIQUE, PRIMARY KEY, or NOT NULL constraint.

protected fun <T> KQLiteColumn<T>.primaryKey(sort: Sort? = null): KQLiteColumn<T>

Designates this column as the PRIMARY KEY for the table.

protected fun realColumn(name: String): KQLiteColumn<Double?>

Defines a nullable REAL column in the table, intended to store a Double.

protected fun <T> KQLiteColumn<T>.references(column: KQLiteColumn<out T>, onDelete: ForeignKeyAction? = null, onUpdate: ForeignKeyAction? = null): KQLiteColumn<T>

Adds a FOREIGN KEY constraint to this column, referencing another column.

protected fun shortColumn(name: String): KQLiteColumn<Short?>

Defines a nullable SMALLINT column in the table, intended to store a Short.

protected fun stringColumn(name: String): KQLiteColumn<String?>

Defines a nullable TEXT column in the table, intended to store a String.

protected fun textColumn(name: String): KQLiteColumn<String?>

Defines a nullable TEXT column in the table, intended to store a String.

protected fun timeColumn(name: String): KQLiteColumn<KQLiteTime?>

Defines a nullable TIME column to store a time.

open override fun toString(): String

Returns a string representation of the table object.

protected fun uByteColumn(name: String): KQLiteColumn<UByte?>

Defines a nullable TINYINT UNSIGNED column in the table, intended to store an unsigned 8-bit integer (UByte).

protected fun uIntColumn(name: String): KQLiteColumn<UInt?>

Defines a nullable INT UNSIGNED column in the table, intended to store an unsigned 32-bit integer (UInt).

protected fun uLongColumn(name: String): KQLiteColumn<ULong?>

Defines a nullable INTEGER column in the table, intended to store an unsigned 64-bit integer (ULong).

protected fun <T> KQLiteColumn<T>.unique(): KQLiteColumn<T>

Adds a UNIQUE constraint to this column.

unixEpochColumn

protected fun unixEpochColumn(name: String): KQLiteColumn<KQLiteUnixEpoch?>

Defines a nullable BIGINT column to store a Unix Epoch timestamp.

protected fun uShortColumn(name: String): KQLiteColumn<UShort?>

Defines a nullable SMALLINT UNSIGNED column in the table, intended to store an unsigned 16-bit integer (UShort).