Tables and schemas

A TaruviBase table stores one kind of application data: projects, tasks, customers, or any other records an app owns. Its stored schema describes the fields, keys, constraints, and relationships expected by that table.

App-scoped tables

Every table belongs to one app. Its logical name is unique inside that app, so two apps can each have a table named tasks.

A Database request identifies a table with three values:

Site hostname + app slug + logical table name

For a REST record request:

/api/apps/{app_slug}/datatables/tasks/data/

Use the logical name in SDK and REST requests. TaruviBase derives a physical_table_name for PostgreSQL storage and returns it as table metadata; application code does not need to construct or depend on that value.

Choose the storage model

The record and query guides use managed relational tables with this metadata:

provider_type: flat_table
schema_format: frictionless
is_materialized: true

Whole-table JSONB storage follows a different record and query contract. Review Database storage compatibility before using a table with different metadata.

Stored schema descriptors

TaruviBase managed tables use a Frictionless-style descriptor. A compact schema for a task list looks like this:

{
  "fields": [
    {
      "name": "id",
      "type": "string",
      "format": "uuid",
      "constraints": {
        "required": true
      }
    },
    {
      "name": "title",
      "type": "string",
      "constraints": {
        "required": true,
        "maxLength": 200
      }
    },
    {
      "name": "done",
      "type": "boolean"
    }
  ],
  "primaryKey": ["id"],
  "foreignKeys": []
}

Each field has:

• a name used in records, filters, sorting, and field selection;
• a type that maps the value to PostgreSQL;
• an optional format, such as uuid; and
• optional constraints, such as required, unique, or maxLength.

Use lowercase snake_case names such as project_id and created_at. Start each name with a letter or underscore and use only letters, numbers, and underscores.

The schema reference lists the supported field declarations and constraints.

Primary keys

The primaryKey array identifies the field used to address one record. New single-key tables use a UUID field named id, and TaruviBase generates its value when a create omits it. See the primary-key declaration in the schema reference for the exact descriptor.

Existing integer-key tables retain their key type. SDK and REST clients may supply a UUID when stable client-side identity is useful for retries or external synchronization. The public record path addresses one key value per record; see Primary keys before adopting a composite descriptor.

The schema includes the managed id field together with the application fields.

Foreign keys

In a managed table, a foreign key connects a local field to a key in another table in the same app. For example, tasks.project_id can reference projects.id. The foreign-key reference contains the declaration and supported delete actions.

reference.resource is the referenced table's logical name. The local and referenced fields must use compatible types. If x-actions.onDelete is omitted, TaruviBase uses NO ACTION.

Create the referenced table before adding the foreign key, then use Relationships to filter root records through the connection.

Stored schema and physical storage

TaruviBase stores the schema with the table and tracks whether the PostgreSQL table behind it has been created, in is_materialized:

• true — the table is ready for record operations;
• false — the schema exists and provisioning must complete before record operations begin.

The Console shows a table as synced once it is ready. Treat its Definition as the source of truth for your application, and test a read and a write after every schema change.

Design a schema before storing data

Plan the schema before storing application data:

1. Choose stable field names and value types.
2. Use the generated UUID id for a new single-key table.
3. Mark only genuinely required fields as required.
4. Add constraints that match application validation.
5. Create referenced tables before declaring foreign keys.
6. Test the schema with representative data in a development app.

Continue with Manage tables before connecting application code.