TinyBase logoTinyBase β

DpcTabularSave

The DpcTabularSave type describes the configuration for saving Tables in a database-oriented Persister that is operating in tabular mode.

{[tableId: Id]: {
  tableName: string;
  rowIdColumnName?: string;
  deleteEmptyColumns?: boolean;
  deleteEmptyTable?: boolean;
} | string}

It is an object where each key is an Id of a Store Table, and the value is a child configuration object for how that Table should be saved out to the database. The properties of the child configuration object are:

TypeDescription
tableNamestringThe name of the database table out to which the Store Table should be saved.
rowIdColumnName?stringThe optional name of the column in the database table that will be used to save the Row Ids from the Store Table, defaulting to '_id'.
deleteEmptyColumns?booleanWhether columns in the database table will be removed if they are empty in the Store Table, defaulting to false.
deleteEmptyTable?booleanWhether tables in the database will be removed if the Store Table is empty, defaulting to false.

As a shortcut, if you do not need to specify a custom rowIdColumnName, or enable the deleteEmptyColumns or deleteEmptyTable settings, you can simply provide the name of the database table instead of the whole object.

deleteEmptyColumns and deleteEmptyTable only have a guaranteed effect when an explicit call is made to the Persister's save method. Columns and tables will not necessarily be removed when the Persister is incrementally 'autoSaving', due to performance reasons. If you want to be sure that your database table matches a TinyBase Table without any extraneous columns, simply call the save method at an idle moment.

The 'Dpc' prefix indicates that this type is used within the DatabasePersisterConfig type.

Example

When applied to a database Persister, this DatabasePersisterConfig will save the data of two Store Tables (called 'pets' and 'species') into two database tables (called 'petsInDb' and 'speciesInDb'). One has a column for the Row Id called 'id' and will delete columns and the whole table if empty, the other defaults to '_id' and will not delete columns or the whole table if empty.

import type {DatabasePersisterConfig} from 'tinybase';

export const databasePersisterConfig: DatabasePersisterConfig = {
  mode: 'tabular',
  tables: {
    save: {
      pets: {
        tableName: 'petsInDb',
        deleteEmptyColumns: true,
        deleteEmptyTable: true,
      },
      species: 'speciesInDb',
    },
  },
};

Imagine a Store with Tables that look like this:

{
  "pets": {
    "fido": {"species": "dog", "color": "brown"},
    "felix": {"species": "cat", "color": "black"},
  },
  "species": {
    "dog": {"price": 5},
    "cat": {"price": 4},
  },
}

With the configuration above, this will save out to a database with tables that look like this:

> SELECT * FROM petsInDb;
+-------+---------+-------+
| id    | species | color |
+-------+---------+-------+
| fido  | dog     | brown |
| felix | cat     | black |
+-------+---------+-------+

> SELECT * FROM speciesInDb;
+------+-------+
| _id  | price |
+------+-------+
| dog  | 5     |
| cat  | 4     |
+------+-------+

The example above represents what happens with a SQLite Persister. In PostgreSQL databases, all Cell and Value columns are expected to be typed as text, and the strings, booleans, and numbers would be JSON-encoded if you queried them.

Since

v4.0.0