Skip to main content

Work with records

A record is one object stored in a table. Its fields follow the table schema, and its primary key identifies it across reads, updates, relationships, and deletes. The examples use the tasks table from the quickstart.

These workflows use managed flat-table storage. Review storage compatibility before applying them to a whole-table JSONB table.

New single-key tables use a generated UUID field named id. SDK and REST clients may supply their own UUID when stable client-side identity helps with retry reconciliation. Existing integer-key tables retain their declared identifier. In the snippets, taskId and task_id refer to the primary key of an existing task.

Create a record​

Send the fields declared by the table schema. Omit id to let TaruviBase generate it, then keep the ID from the create response.

await database
  .from('tasks')
  .create({
    title: 'Prepare release notes',
    done: false,
  })
  .execute();

REST and the JavaScript builder return HTTP 201 with the created records in data. Python's direct create() method returns that record list directly.

List records​

Use a stable sort and an explicit page size whenever a collection may grow.

await database
  .from('tasks')
  .sort('title', 'asc')
  .sort('id', 'asc')
  .page(1)
  .pageSize(20)
  .execute();

Collection responses include data for the current page and total for all matching records.

Read one record​

Use the record's primary-key value.

await database
  .from('tasks')
  .get(taskId)
  .execute();

REST and the JavaScript builder return one object in data without total. Python's direct get() method returns the record object. In Refine 5, useOne exposes that record directly as result; request state is under query.

Update a record​

Keep the primary key in the record selector and send only the fields that should change.

await database
  .from('tasks')
  .get(taskId)
  .update({done: true})
  .execute();

REST and the JavaScript builder return the updated record in data. Python's direct update() method returns the updated record object.

Create or update by primary key​

Use upsert when a source record already owns a stable primary key. TaruviBase creates a row when that primary key is missing from the table and updates it when the key already exists.

await database
  .from('tasks')
  .upsert({
    id: taskId,
    title: 'Prepare release notes',
    done: false,
  })
  .execute();

Use the table's primary key for this workflow. For another unique field such as an email address or external reference, read the matching record first and then choose an explicit create or update.

Delete a record​

Record deletion is permanent. Keep the selected ID visible while confirming the operation.

Confirm the target
  • Affected resource and cascade: The target is the selected record in the named site, app, and table. Review configured foreign-key delete behavior for dependent records before continuing.
  • Reversibility: Record deletion is permanent.
  • Authorization: The caller must have the table policy's delete action for the intended app and record scope.
  • Backup or export: Retain the record fields needed to recreate it when the workflow requires recovery.
  • Confirmation: Read the record immediately before deletion, then confirm the site, app, table, and exact record ID. Console shows these values in Confirm Delete Record; programmatic callers need an equivalent check.
  • Success response and postcondition: Successful REST deletion returns HTTP 204 with no body. Read the ID again and verify that it is absent.
  • Recovery: This guide documents no undelete operation. Recreate the record only from retained data and re-verify its constraints and authorization.
await database
  .from('tasks')
  .delete(taskId)
  .execute();

Successful single-record deletion returns HTTP 204 with no body.

Delete a selected set​

Use an explicit list of primary keys when one action should remove multiple records. First query the intended records, keep the IDs visible for review, then use the bulk delete workflow.

For deletion by filter, resolve the filter to IDs first. The application can show that bounded set for review and confirmation before submitting the explicit IDs.

Continue​