IndexedDB

IndexedDB providers back Gestalt’s persistent state layer. The host uses them for users, sessions, plugin tokens, API tokens, OAuth registrations, and other system records. Gestalt adopts the IndexedDB model so a single provider contract can map cleanly to relational, document, or key-value backends.

How IndexedDB providers work

The active datastore is selected by server.providers.indexeddb, which points to one of the named entries under providers.indexeddb. Gestalt talks to that provider through the IndexedDB service contract while keeping plugin state isolated with plugin-scoped datastore instances. Plugins may override that host selection with plugins.<name>.indexeddb.provider; otherwise they inherit the selected/default host IndexedDB. plugins.<name>.indexeddb.db defaults to the plugin key and controls the plugin-visible database name used for backend scoping. With the first-party RelationalDB provider, Postgres, MySQL, and SQL Server receive that value as schema, while SQLite falls back to <db>_ table prefixes because it has no schema support. Other IndexedDB providers fall back to <db>_ transport-level store prefixes. Plugins may also set plugins.<name>.indexeddb.objectStores to allowlist logical stores such as tasks.

Using IndexedDB from a plugin

Executable plugins do not choose raw database DSNs or relational schemas at runtime. They receive one IndexedDB SDK socket from the host, and the host decides what that socket points to from config.

In plugin code, use the IndexedDB client from the language SDK. The plugins.<name>.indexeddb.provider field selects which named providers.indexeddb entry backs that client, and plugins.<name>.indexeddb.db selects the plugin-visible database name used for backend scoping. On schema-capable backends such as RelationalDB, that becomes the backend schema name. If the plugin omits plugins.<name>.indexeddb, it inherits the host-selected IndexedDB provider and uses the plugin key as the default db name.

For example:

server:
  providers:
    indexeddb: main
 
providers:
  indexeddb:
    main:
      source: https://artifacts.example.com/indexeddb/relationaldb/v0.0.1-alpha.1/provider-release.yaml
      config:
        dsn: ${SYSTEM_DATABASE_URL}
    workplaceHub:
      source: https://artifacts.example.com/indexeddb/relationaldb/v0.0.1-alpha.1/provider-release.yaml
      config:
        dsn: ${APP_DATABASE_URL}
 
plugins:
  workplace_hub:
    source: ./plugin/manifest.yaml
    indexeddb:
      provider: workplaceHub
      db: workplace_hub

Then inside the plugin:

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

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

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?;

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 plugin config gives the plugin 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 plugin code.

First-party IndexedDB providers

First-party storage backends live under valon-technologies/gestalt-providers/indexeddb.

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, reference a published release metadata URL:

server:
  providers:
    indexeddb: main
 
providers:
  indexeddb:
    main:
      source: https://artifacts.example.com/indexeddb/relationaldb/v0.0.1-alpha.1/provider-release.yaml
      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: https://artifacts.example.com/indexeddb/dynamodb/v0.0.1-alpha.1/provider-release.yaml
      config:
        table: gestalt
        region: us-east-1
        # endpoint: http://localhost:8000

providers:
  indexeddb:
    main:
      source: https://artifacts.example.com/indexeddb/mongodb/v0.0.1-alpha.1/provider-release.yaml
      config:
        uri: ${MONGODB_URI}
        database: gestalt

Operational notes

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

Building your own datastore provider

The full IndexedDB interface, SDK authoring details, and custom provider release flow now live under Custom Providers > IndexedDB.

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. If you want to implement the contract yourself, read Custom IndexedDB Providers.