Database storage models
TaruviBase Database has two storage models. Choose the model before building the application because their record and query contracts are not interchangeable.
Use managed tables for application data
The task guides, SDK examples, Refine reads, and REST examples use this table metadata:
provider_type: flat_table
schema_format: frictionless
is_materialized: true
In this model, TaruviBase maps declared fields to PostgreSQL columns. Use it when the application needs the complete set of workflows described in these guides, including relationships, aggregations, and configured search indexes.
An object field inside a flat table is still part of this model. It stores
one structured value in a JSONB column; see JSON object
fields.
Understand whole-table JSONB storage
A table with provider_type: jsonb uses a separate physical record model:
Primary key + data JSONB object + created_at + updated_at
The declared schema remains table metadata rather than a set of independently
materialized business columns. TaruviBase flattens the stored data object when
the provider returns a record.
Whole-table JSONB integrations use provider-specific record operations. Verify basic record access, bounded inserts, top-level filtering, sorting, pagination, and nested object values in an isolated app before deploying the integration.
Check feature compatibility
| Capability | Recommended path |
|---|---|
| Create, read, update, and delete one record | Verify through the provider-specific REST integration |
| Insert a bounded record batch | Verify through the provider-specific REST integration |
| Top-level filters, sorting, and pagination | Use top-level field names and explicit page controls |
| Store and return nested objects as record values | Treat each nested object as one returned value |
| Change the declared schema | Metadata-only compatibility path |
| Upsert | Use the flat-table provider |
| Vector or hybrid search | Use the flat-table provider |
| Relationship traversal filters | Use flat-table foreign keys and explicit related-table reads |
| Nested JSON path filters | Promote queryable values to top-level fields |
| Population, aggregation, field projection, bulk update, and bulk delete | Use the flat-table provider |
| JavaScript SDK, Python SDK, Refine, and TaruviBase Console workflows | Use the flat-table provider for the manual's cross-interface examples |
Top-level fields can participate in the provider's filter path. Keep nested objects as complete values and promote queryable properties to top-level fields.
Model many-to-many connections with the flat-table junction pattern in Relationships.
Keep application workflows portable
Use the flat-table compatibility path for the examples in these guides. If an existing app already uses whole-table JSONB storage, record its exact provider metadata and validate every required operation in an isolated app before depending on it.
The SDK, REST, Refine, relationship, aggregation, and search examples in these guides are for flat tables. Test each one on a JSONB table before you rely on it.
Continue with Tables and schemas, Fields and constraints, or Manage tables.