Insert
Insert rows with the Lua builder.
Recommended style
Use a generated table reference when your resource owns a schema:
local users = kura.db.tables.users
kura.db.insert(users)
:values({
username = 'john',
email = 'john@example.com',
})
:await()The users name above is only an example. Generated refs always come from your own schema.ts.
String table names still work:
kura.db.insert('users')
:values({ username = 'john', email = 'john@example.com' })
:await()String table and column inputs in the builder are compatibility identifiers. They are quoted as identifiers and are not treated as raw SQL fragments.
Payload keys
When you insert through a generated table, use the Lua field names from your schema object:
createdAt: defineColumn('created_at', 'date')
passwordHash: defineColumn('password_hash', 'string')That becomes:
local users = kura.db.tables.users
kura.db.insert(users)
:values({
createdAt = os.time(),
passwordHash = 'hashed',
})
:await()KuraDB resolves those Lua field names to their SQL column names automatically.
Returning
For explicit result shapes, prefer the new helper methods:
local users = kura.db.tables.users
local insertedId = kura.db.insert(users)
:values({
username = 'john',
email = 'john@example.com',
})
:returningValue(users.id)
:await()
local insertedRow = kura.db.insert(users)
:values({
username = 'jane',
email = 'jane@example.com',
})
:returningOne({ users.id, users.username, users.createdAt })
:await()Available helpers:
:returningRows({ ... })returns all returned rows:returningOne({ ... })returns the first returned row ornil:returningValue(column)returns the first returned scalar ornil
Compatibility behavior
returning() is still supported and keeps the older behavior:
local users = kura.db.tables.users
local insertedId = kura.db.insert(users)
:values({
username = 'john',
email = 'john@example.com',
})
:returning({ users.id })
:await()Plain :returning(...):await() on insert() remains compatibility-oriented and returns the first returned scalar, usually the inserted id. Use returningRows, returningOne, or returningValue when you want an explicit result shape.
String column names are still valid here too:
local insertedId = kura.db.insert('users')
:values({ username = 'john' })
:returning({ 'id' })
:await()Bulk insert
For inserting many rows at once, use kura.db.raw.insertMany.await(...):
local ids = kura.db.raw.insertMany.await('users', {
{ license = 'license:1', cash = 500 },
{ license = 'license:2', cash = 750 },
}, {
returning = 'id',
})insertMany is the preferred bulk-insert path today. It generates a multi-row PostgreSQL insert and avoids looping insert() calls one at a time.
Builder bulk insert
The chainable builder does not have a valuesMany() helper yet. If you need bulk inserts today, use raw.insertMany. A builder-native bulk insert helper is still TODO.