Table Operations

This chapter describes how to create, delete, empty, and synchronize database tables.

Make sure each KPojo has the table, column, primary key, index, and strategy annotations required by the table operation.

Table operations can be invoked through Kronos.dataSource.table after configuring the default data source, or through a concrete KronosDataSourceWrapper.table. Schema sync and CTAS have dedicated guides: 📚Schema Sync and 📚Create Table As Select.

Build DDL statements and preview SQL

TableOperation exposes build APIs for dry-run review. Use statement builders when you need a syntax object, and task builders when you need the rendered SQL and parameters for the active dialect.

val table = Kronos.dataSource.table

val createStatement = table.buildCreateTableStatement(User())
val dropStatement = table.buildDropTableStatement("user", ifExists = true)
val truncateStatement = table.buildTruncateTableStatement("user", restartIdentity = false)

val dropTask = table.buildDropTableTask("user")
val truncateTask = table.buildTruncateTableTask("user", restartIdentity = false)

val (sql, params, atomicTasks) = truncateTask

println(sql)
println(params)
println(atomicTasks.map { it.operationType })

DELETE FROM "user"
{}
[TRUNCATE, TRUNCATE, TRUNCATE]

CTAS can also be built before execution.

val paidOrders = Order()
    .select { [it.id, it.userId, it.status] }
    .where { it.status == 1 }

val task = table.buildCreateTableAsSelectTask(OrderArchive(), paidOrders)
val (ctasSql, ctasParams) = task

1. exists(tableName) whether the table exists

Check if the table exists by table name.

• Function declaration

  fun exists(tableName: String): Boolean

• Usage Example

  val exists = wrapper.table.exists("user")

• Parameters

  name	description	type	default
  *tableName	Table name	String	-

• Return value

  Boolean - Whether the table exists

2. exists<T>(instance) whether the table exists

• Generic parameters： <T> Entity object type, inherited from KPojo

Check if the table exists by KPojo.

• Function declaration

  inline fun <reified T : KPojo> exists(instance: T = createKPojo<T>()): Boolean

📚How does Kronos create KPojo from KType without reflective construction?

• Usage Example

  val exists = wrapper.table.exists(User())
  // or
  val exists = wrapper.table.exists<User>()

• Parameters

  name	description	type	default
  instance	Entity object. The generic overload uses the generated or registered factory for `T`.	T	createKPojo()

• Return value

  Boolean - Whether the table exists

3. createTable(instance) Create a table

• Generic parameters： <T> Entity object type, inherited from KPojo

Create a table by KPojo.

• Function declaration

  inline fun <reified T : KPojo> createTable(instance: T = createKPojo<T>())

📚How does Kronos create KPojo from KType without reflective construction?

• Usage Example

  wrapper.table.createTable(User())
  // or
  wrapper.table.createTable<User>()

• Parameters

  name	description	type	default
  instance	Entity object. The generic overload uses the generated or registered factory for `T`.	T	createKPojo()

4. createTable(target, query) Create table as select

Create a table from a KSelectable or UnionClause query by passing the target KPojo and the source query to wrapper.table.createTable(target, query).

• Function declaration

  inline fun <reified T : KPojo> createTable(
      instance: T = createKPojo<T>(),
      query: KSelectable<*>
  )
  
  inline fun <reified T : KPojo> createTable(
      instance: T = createKPojo<T>(),
      query: UnionClause<*>
  )

• Usage Example

  val paidOrders = Order()
      .select { [it.id, it.userId, it.status] }
      .where { it.status == 1 }
  
  wrapper.table.createTable(OrderArchive(), paidOrders)

• Generated SQL

  CREATE TABLE IF NOT EXISTS `order_archive` AS
  SELECT `id`, `user_id` AS `userId`, `status`
  FROM `order`
  WHERE `order`.`status` = :status

CTAS uses the query output as the table shape. Use normal createTable(Target()) and then KSelectable.insert<Target>() when the table needs KPojo schema metadata such as indexes, comments, defaults, or primary key definitions.

5. truncateTable(vararg tableName, restartIdentity) Clear the table

Clear one or more tables by table name.

• Function declaration

  fun truncateTable(vararg tableName: String, restartIdentity: Boolean = true)

• Usage Example

  wrapper.table.truncateTable("user")
  wrapper.table.truncateTable("user", "audit_log", restartIdentity = false)

• Parameters

  name	description	type	default
  *tableName	Table name list	vararg String	-
  restartIdentity	Whether to reset the auto-increment value. PostgreSQL and SQLite have explicit reset behavior; other dialects keep their native truncate behavior.	Boolean	true

6. truncateTable(instance, restartIdentity) Clear the table

• Generic parameters： <T> Entity object type, inherited from KPojo

Clear the table by KPojo.

• Function declaration

  inline fun <reified T : KPojo> truncateTable(
      instance: T = createKPojo<T>(),
      restartIdentity: Boolean = true
  )

📚How does Kronos create KPojo from KType without reflective construction?

• Usage Example

  wrapper.table.truncateTable(User())
  // or
  wrapper.table.truncateTable<User>()

• Parameters

  name	description	type	default
  instance	Entity object. The generic overload uses the generated or registered factory for `T`.	T	createKPojo()
  restartIdentity	Whether to reset the auto-increment value. PostgreSQL and SQLite have explicit reset behavior; other dialects keep their native truncate behavior.	Boolean	true

7. dropTable(vararg tableNames) Delete the table

Delete one or more tables by table name.

• Function declaration

  fun dropTable(vararg tableNames: String)

• Usage Example

  wrapper.table.dropTable("user")
  wrapper.table.dropTable("user", "audit_log")

• Parameters

  name	description	type	default
  *tableNames	Table name list	vararg String	-

8. dropTable(instance) Delete the table

• Generic parameters： <T> Entity object type, inherited from KPojo

• Function declaration

  inline fun <reified T : KPojo> dropTable(instance: T = createKPojo<T>())

📚How does Kronos create KPojo from KType without reflective construction?

• Usage Example

  wrapper.table.dropTable(User())
  // or
  wrapper.table.dropTable<User>()

• Parameters

  name	description	type	default
  instance	Entity object. The generic overload uses the generated or registered factory for `T`.	T	createKPojo()

9. syncTable(instance) Synchronize table structure

• Generic parameters： <T> Entity object type, inherited from KPojo

• Function declaration

  inline fun <reified T : KPojo> syncTable(instance: T = createKPojo<T>()): Boolean

📚How does Kronos create KPojo from KType without reflective construction?

• Usage Example

  wrapper.table.syncTable(User())
  // or
  wrapper.table.syncTable<User>()

• Parameters

  name	description	type	default
  instance	Entity object. The generic overload uses the generated or registered factory for `T`.	T	createKPojo()

• Return value

  Boolean - false means Kronos created the target table. true means Kronos synchronized an existing table.

When several table operations use the same object in sequence, keep that object in a local variable and pass it to exists(instance), createTable(instance), dropTable(instance), or syncTable(instance).