IndexedDB

IndexedDB providers back Gestalt’s persistent state layer, modeled on the W3C Indexed Database API . This contract allows Gestalt to be agnostic of relational, document, or key-value backends.

Using IndexedDB from a plugin

Apps use the IndexedDB client from the language SDK. By default, Gestalt uses the host IndexedDB provider and the app name as the database scope. Configure apps.<name>.indexeddb only when an app needs a different provider or database scope.

For example:


server:
  providers:
    indexeddb: main
 
providers:
  indexeddb:
    main:
      source:
        package: github.com/valon-technologies/gestalt-providers/indexeddb/relationaldb
        version: 0.0.1-alpha.2
      config:
        dsn: ${SYSTEM_DATABASE_URL}
    workplaceHub:
      source:
        package: github.com/valon-technologies/gestalt-providers/indexeddb/relationaldb
        version: 0.0.1-alpha.2
      config:
        dsn: ${APP_DATABASE_URL}
 
apps:
  workplace_hub:
    source: ./plugin/manifest.yaml
    indexeddb:
      provider: workplaceHub
      db: workplace_hub

Then inside the plugin:

Go


import (
    "context"
    "log"
 
    gestalt "github.com/valon-technologies/gestalt/sdk/go"
)
 
ctx := context.Background()
 
db, err := gestalt.IndexedDB()
if err != nil {
    log.Fatal(err)
}
defer db.Close()
 
tasks := db.ObjectStore("tasks")
if err := tasks.Put(ctx, gestalt.Record{
    "id":    "task-1",
    "title": "Ship docs",
}); err != nil {
    log.Fatal(err)
}
 
record, err := tasks.Get(ctx, "task-1")
if err != nil {
    log.Fatal(err)
}
_ = record

Python


from gestalt import IndexedDB
 
db = IndexedDB()
tasks = db.object_store("tasks")
 
tasks.put({"id": "task-1", "title": "Ship docs"})
record = tasks.get("task-1")
 
db.close()

Rust


use std::collections::BTreeMap;
 
use gestalt::IndexedDB;
use serde_json::json;
 
let db = IndexedDB::connect().await?;
let mut tasks = db.object_store("tasks");
 
tasks
    .put(BTreeMap::from([
        ("id".to_string(), json!("task-1")),
        ("title".to_string(), json!("Ship docs")),
    ]))
    .await?;
 
let record = tasks.get("task-1").await?;

TypeScript


import { IndexedDB } from "@valon-technologies/gestalt";
 
const db = new IndexedDB();
const tasks = db.objectStore("tasks");
 
await tasks.put({ id: "task-1", title: "Ship docs" });
const record = await tasks.get("task-1");

Normal app config gives the app one effective IndexedDB binding. If you need a different backing store or a different scoped database name, choose that in YAML instead of encoding transport details in app code.

Advanced reads and writes

The snippets below continue from the basic setup above: db is a connected IndexedDB client, tasks is the tasks object-store handle, and Go examples also use ctx. The examples assume primary keys such as task-100 and a secondary index named by_status.

Range reads

Use a key range when you need a bounded primary-key scan instead of one exact lookup.

Go


recent, err := tasks.GetAll(ctx, &gestalt.KeyRange{
    Lower: "task-100",
    Upper: "task-199",
})
if err != nil {
    log.Fatal(err)
}
 
_ = recent

Python


from gestalt import KeyRange
 
recent = tasks.get_all(KeyRange(lower="task-100", upper="task-199"))

Rust


use gestalt::KeyRange;
use serde_json::json;
 
let recent = tasks
    .get_all(Some(KeyRange {
        lower: Some(json!("task-100")),
        upper: Some(json!("task-199")),
        lower_open: false,
        upper_open: false,
    }))
    .await?;

TypeScript


const recent = await tasks.getAll({
  lower: "task-100",
  upper: "task-199",
});

Cursor pagination

IndexedDB pagination is cursor-based. The SDKs do not expose a page-token list API for object stores; keep the last primary key from one cursor page and use an exclusive lower bound for the next page.

Go


func readTaskPage(
    ctx context.Context,
    tasks *gestalt.ObjectStoreClient,
    after string,
    limit int,
) ([]gestalt.Record, string, error) {
    var keyRange *gestalt.KeyRange
    if after != "" {
        keyRange = &gestalt.KeyRange{
            Lower:     after,
            LowerOpen: true,
        }
    }
 
    cursor, err := tasks.OpenCursor(ctx, keyRange, gestalt.CursorNext)
    if err != nil {
        return nil, "", err
    }
    defer cursor.Close()
 
    page := make([]gestalt.Record, 0, limit)
    var nextAfter string
    for len(page) < limit && cursor.Continue() {
        record, err := cursor.Value()
        if err != nil {
            return nil, "", err
        }
        page = append(page, record)
        nextAfter = cursor.PrimaryKey()
    }
    if err := cursor.Err(); err != nil {
        return nil, "", err
    }
    return page, nextAfter, nil
}
 
page, nextAfter, err := readTaskPage(ctx, tasks, "", 25)
if err != nil {
    log.Fatal(err)
}
 
_ = page
_ = nextAfter

Python


from gestalt import CURSOR_NEXT, KeyRange
 
def read_task_page(tasks, after: str | None = None, limit: int = 25):
    key_range = (
        KeyRange(lower=after, lower_open=True)
        if after
        else None
    )
    page = []
    next_after = None
 
    with tasks.open_cursor(key_range, direction=CURSOR_NEXT) as cursor:
        while len(page) < limit and cursor.continue_():
            page.append(cursor.value)
            next_after = cursor.primary_key
 
    return page, next_after
 
page, next_after = read_task_page(tasks, limit=25)

Rust


use gestalt::{CursorDirection, KeyRange};
use serde_json::json;
 
let after = None::<String>;
let cursor_range = after.map(|id| KeyRange {
    lower: Some(json!(id)),
    upper: None,
    lower_open: true,
    upper_open: false,
});
let mut cursor = tasks
    .open_cursor(cursor_range, CursorDirection::Next)
    .await?;
 
let mut page = Vec::new();
let mut next_after = None::<String>;
while page.len() < 25 && cursor.continue_next().await? {
    page.push(cursor.value()?);
    next_after = Some(cursor.primary_key().to_string());
}
cursor.close().await?;

TypeScript


import {
  CursorDirection,
  type KeyRange,
  type Record,
} from "@valon-technologies/gestalt";
 
async function readTaskPage(after?: string, limit = 25) {
  const range: KeyRange | undefined = after
    ? { lower: after, lowerOpen: true }
    : undefined;
  const cursor = await tasks.openCursor({
    range,
    direction: CursorDirection.Next,
  });
  const page: Record[] = [];
  let nextAfter: string | undefined;
 
  if (!cursor) return { page, nextAfter };
 
  try {
    while (page.length < limit) {
      const hasNext = await cursor.continue();
      if (!hasNext) break;
      if (cursor.value) page.push(cursor.value);
      nextAfter = cursor.primaryKey;
    }
  } finally {
    cursor.close();
  }
 
  return { page, nextAfter };
}
 
const { page, nextAfter } = await readTaskPage(undefined, 25);

Secondary index queries

Use an index when you need to find or count rows by a field other than the primary key. In TypeScript, the first index-query argument is the optional key range; pass undefined before index values when no range is needed.

Go


byStatus := tasks.Index("by_status")
 
activeCount, err := byStatus.Count(ctx, nil, "active")
if err != nil {
    log.Fatal(err)
}
 
activeKeys, err := byStatus.GetAllKeys(ctx, nil, "active")
if err != nil {
    log.Fatal(err)
}
 
_, _ = activeCount, activeKeys

Python


by_status = tasks.index("by_status")
 
active_count = by_status.count("active")
active_keys = by_status.get_all_keys("active")

Rust


use serde_json::json;
 
let mut by_status = tasks.index("by_status");
 
let active_count = by_status.count(&[json!("active")], None).await?;
let active_keys = by_status.get_all_keys(&[json!("active")], None).await?;

TypeScript


const byStatus = tasks.index("by_status");
 
const activeCount = await byStatus.count(undefined, "active");
const activeKeys = await byStatus.getAllKeys(undefined, "active");

Transactions

Use an explicit transaction when a group of reads and writes should commit or roll back together.

Go


import "time"
 
tx, err := db.Transaction(
    ctx,
    []string{"tasks"},
    gestalt.TransactionReadwrite,
    gestalt.TransactionOptions{
        DurabilityHint: gestalt.TransactionDurabilityStrict,
    },
)
if err != nil {
    log.Fatal(err)
}
 
txTasks := tx.ObjectStore("tasks")
now := time.Now().UTC().Format(time.RFC3339)
for _, record := range []gestalt.Record{
    {"id": "task-123", "status": "active", "priority": 2, "updatedAt": now},
    {"id": "task-124", "status": "queued", "priority": 1, "updatedAt": now},
} {
    if err := txTasks.Put(ctx, record); err != nil {
        _ = tx.Abort(ctx)
        log.Fatal(err)
    }
}
if err := tx.Commit(ctx); err != nil {
    log.Fatal(err)
}

Python


import datetime as dt
 
now = dt.datetime.now(dt.timezone.utc).isoformat()
with db.transaction(["tasks"], "readwrite", durability_hint="strict") as tx:
    tx_tasks = tx.object_store("tasks")
    tx_tasks.put(
        {
            "id": "task-123",
            "status": "active",
            "priority": 2,
            "updatedAt": now,
        }
    )
    tx_tasks.put(
        {
            "id": "task-124",
            "status": "queued",
            "priority": 1,
            "updatedAt": now,
        }
    )

Rust


use std::collections::BTreeMap;
 
use gestalt::{
    TransactionDurabilityHint, TransactionMode, TransactionOptions,
};
use serde_json::json;
 
let mut tx = db
    .transaction(
        &["tasks"],
        TransactionMode::Readwrite,
        TransactionOptions {
            durability_hint: TransactionDurabilityHint::Strict,
        },
    )
    .await?;
 
{
    let mut tx_tasks = tx.object_store("tasks");
    tx_tasks.put(
        BTreeMap::from([
            ("id".to_string(), json!("task-123")),
            ("status".to_string(), json!("active")),
            ("priority".to_string(), json!(2)),
            ("updatedAt".to_string(), json!("2026-05-12T12:00:00Z")),
        ])
    )
    .await?;
    tx_tasks.put(
        BTreeMap::from([
            ("id".to_string(), json!("task-124")),
            ("status".to_string(), json!("queued")),
            ("priority".to_string(), json!(1)),
            ("updatedAt".to_string(), json!("2026-05-12T12:00:00Z")),
        ])
    )
    .await?;
}
tx.commit().await?;

TypeScript


const tx = await db.transaction(["tasks"], "readwrite", {
  durabilityHint: "strict",
});
try {
  const txTasks = tx.objectStore("tasks");
  const updatedAt = new Date().toISOString();
  await txTasks.put({
    id: "task-123",
    status: "active",
    priority: 2,
    updatedAt,
  });
  await txTasks.put({
    id: "task-124",
    status: "queued",
    priority: 1,
    updatedAt,
  });
  await tx.commit();
} catch (error) {
  await tx.abort("failed to save task batch");
  throw error;
}

Configuring storage

For local development, SQLite keeps setup simple:


server:
  providers:
    indexeddb: main
 
providers:
  indexeddb:
    main:
      source: ./relationaldb/manifest.yaml
      config:
        dsn: sqlite://gestalt.db

For production, use the first-party package source:


server:
  providers:
    indexeddb: main
 
providers:
  indexeddb:
    main:
      source:
        package: github.com/valon-technologies/gestalt-providers/indexeddb/relationaldb
        version: 0.0.1-alpha.2
      config:
        dsn: ${DATABASE_URL}

The first-party RelationalDB provider accepts postgres://, mysql://, sqlite://, and sqlserver:// DSN prefixes.

Other first-party IndexedDB providers use their own config blocks:


providers:
  indexeddb:
    main:
      source:
        package: github.com/valon-technologies/gestalt-providers/indexeddb/dynamodb
        version: 0.0.1-alpha.1
      config:
        table: gestalt
        region: us-east-1
        # endpoint: http://localhost:8000


providers:
  indexeddb:
    main:
      source:
        package: github.com/valon-technologies/gestalt-providers/indexeddb/mongodb
        version: 0.0.1-alpha.1
      config:
        uri: ${MONGODB_URI}
        database: gestalt

Operational notes

Gestalt needs exactly one active datastore selected by server.providers.indexeddb. Published datastore packages can be locked and prepared with gestaltd lock and gestaltd sync --locked just like other provider types. Apps still go through the host’s request and auth model, so they do not talk to the datastore provider directly.

Building your own IndexedDB provider

Manifest

An IndexedDB provider manifest declares kind: indexeddb:


kind: indexeddb
source: github.com/valon-technologies/gestalt-providers/indexeddb/relationaldb
version: 0.0.1-alpha.2
displayName: RelationalDB
description: IndexedDB provider supporting PostgreSQL, MySQL, SQLite, and SQL Server.
spec:
  configSchemaPath: ./datastore_config.json

Provider interface

You implement the IndexedDB contract, which covers object store lifecycle, primary key CRUD, bulk operations, and index queries. Go providers implement gestalt.IndexedDBProvider.


package relationaldb
 
import (
  "context"
  "database/sql"
 
  gestalt "github.com/valon-technologies/gestalt/sdk/go"
)
 
type RelationalDB struct {
  db *sql.DB
}
 
func New() *RelationalDB { return &RelationalDB{} }
 
func (r *RelationalDB) HealthCheck(ctx context.Context) error {
  return r.db.PingContext(ctx)
}
 
func (r *RelationalDB) CreateObjectStore(ctx context.Context, name string, schema gestalt.ObjectStoreSchema) error {
  return nil
}
 
func (r *RelationalDB) DeleteObjectStore(ctx context.Context, name string) error {
  return nil
}
 
// Get retrieves a single record by primary key.
func (r *RelationalDB) Get(ctx context.Context, req gestalt.IndexedDBObjectStoreRequest) (gestalt.Record, error) {
  return gestalt.Record{}, nil
}
 
// Add inserts a new record. Fails if the key already exists.
func (r *RelationalDB) Add(ctx context.Context, req gestalt.IndexedDBRecordRequest) error {
  return nil
}
 
// Put inserts or replaces the record at the given key.
func (r *RelationalDB) Put(ctx context.Context, req gestalt.IndexedDBRecordRequest) error {
  return nil
}
 
// Delete removes a record by primary key.
func (r *RelationalDB) Delete(ctx context.Context, req gestalt.IndexedDBObjectStoreRequest) error {
  return nil
}
 
// See the W3C IndexedDB specification for the remaining methods:
// https://www.w3.org/TR/IndexedDB/#object-store-interface

What to read next

For the broader server and provider config model, continue to Configuration. For the catalog of first-party packages, see Built-in Providers.