Skip to main content

Creating a simple client database

The best way to quickly learn how to use clientdb would be to write some code with it.

We'll create a simple 'Todos' client database with todo and list entities.

We'll cover:

  • defining entities (aka tables) of our client database
  • creating a database given our defined entities
  • inserting into and reading from the database
  • defining relationships between entities
  • defining default values for entities

Define our first entity

The first thing we need to do is to define what type of data will your entity hold. You can think of entities like database tables.

Let's start with our Todo entity.

import { defineEntity } from "@clientdb/core";

interface Todo {
id: string;
title: string;
doneAt: Date;

const todoEntity = defineEntity<Todo>({
name: "todo",
fields: ["id", "title", "doneAt"],

This is the minimal definition of an entity. There are way more powerful features we'll go through later.

We created a new entity definition todoEntity using TypeScript interface to make it type-safe.

We also provided minimal required configuration which includes name of the entity (aka. table name) and fields array which is a list of allowed fields of this entity.


You can also set idField when defining a new entity. If you don't define it, it will be automatically set to id.

Creating a data store

Now as we have our first entity, we can already create a local database with it.

import { createClientDb } from "@clientdb/core";

const db = createClientDb([todoEntity]);

To create a new client db, we need to pass an array of entities that will be available in it.

db we created will be an entry point for all the operations of our data like reading, inserting, querying, etc.

Inserting data

Now we can add the first todo to our database.

const todo = db.add(todoEntity, {
id: "todo-0",
title: "Buy milk",
doneAt: null,

Call to db.add returns our newly created todo. We can instantly read from it:

todo.title; // "Buy milk"

Get all items from db

We can now get all todos from our database

db.entity(todoEntity).count; // count of all todos - 1

const allTodos = db.entity(todoEntity).all;
const [firstTodo] = allTodos;
firstTodo.title; // "Buy milk"

Querying the database

We can also query our database with criteria of what we are looking for:

const todoQuery = db.entity(todoEntity).query({
title: "Buy milk",

todoQuery.count; // 1
todoQuery.first.title; // "Buy milk"
todoQuery.all; // [todoWeCreated]

Query object can be way more advanced than shown in this example. Check out API reference to more informations


Your data is observable

Before we continue to other parts (eg. updating data), it'd be good to know that all of our data is observable with mobx.

This means that we can subscribe to any piece of data from the database and always have up to date results.

import { autorun } from "mobx";

autorun(() => {

db.add(todoEntity, {
id: "todo-1",
title: "Buy milk",
doneAt: null,

db.add(todoEntity, {
id: "todo-2",
title: "Buy books",
doneAt: null,

// prints:
// 0
// 1
// 2

Updating entity data

Every entity can be updated by calling entity.update() method.

const todo = db.entity(todoEntity).findById("todo-1");

todo.doneAt; // null

const now = new Date();

doneAt: now,

todo.doneAt; // now

Deleting entities

Each entity can be removed with entity.remove() call

const todo = db.entity(todoEntity).findById("todo-1");


db.entity(todoEntity).findById("todo-1"); // null

Calling .update() on removed entity will throw an error.

You can check if the entity is removed, by calling entity.isRemoved()

Great! We now have our database with todo entity. Let's move forward by creating our list entity and connecting it with todo entity.