Masamune Model TiDB

---

[GitHub](https://github.com/mathrunet) | [YouTube](https://www.youtube.com/c/mathrunetchannel) | [Packages](https://pub.dev/publishers/mathru.net/packages) | [X](https://x.com/mathru) | [LinkedIn](https://www.linkedin.com/in/mathrunet/) | [mathru.net](https://mathru.net)

---

Plug-in packages that add functionality to the Masamune Framework.

For more information about Masamune Framework, please click here.

https://pub.dev/packages/masamune

Usage

Use TidbModelAdapter with @mathrunet/masamune_cloudflare_tidb Workers.

final adapter = TidbModelAdapter();

Model paths use the same layout as Turso.

database/<database>/<table>/<document_id>

The adapter sends all reads and writes to the Workers CRUD endpoint. It does not open direct MySQL/TiDB TCP connections from Flutter clients.

Persistent local cache

Use CachedTidbModelAdapter when loaded data should remain available from a device-local cache after the app restarts.

final adapter = CachedTidbModelAdapter();

Documents are loaded from the local cache first. Call reload() on the Masamune model when fresh remote data is required. Saves, deletes, batches, and transactions keep TiDB, the runtime cache, and the persistent cache in sync.

Use cacheFilter to exclude documents from the persistent cache. Collection cache loading is opt-in through collectionLoaders, which can return cached rows only or return a modified query to merge additional TiDB rows.

late final CachedTidbModelAdapter adapter;
adapter = CachedTidbModelAdapter(
  cacheFilter: (_, value) => value["private"] != true,
  collectionLoaders: [
    (query, _) async {
      final cache = await adapter.loadCachedCollection(query);
      if (cache == null) {
        return null;
      }
      return CachedTidbModelCollectionLoaderResponse(value: cache);
    },
  ],
);

Pass a custom cachedLocalDatabase for testing or custom persistence behavior. The default shared database stores native data in the application documents area and Web data through the storage used by DatabaseExporter. Database prefixes also isolate persistent cache entries.

Separate development and production databases

Pass prefix to select a prefixed physical database while keeping model paths unchanged.

final developmentAdapter = TidbModelAdapter(
  prefix: "dev___", // Normalized to "dev_".
);

For database/main/users, this adapter connects to dev_main.users. A null, empty, or underscore-only prefix connects to the existing main.users. Trailing underscores are removed before exactly one underscore is appended. Rules continue to use the logical path main/users, and local caches are separated by prefix.

Katana CLI

Enable TiDB in katana.yaml and run katana apply.

cloudflare:
  tidb:
    enable: true
    project_id: "123"
    cluster_id: "456"

TiDB uses Data Service only. Store the Organization Management API public and private keys under cloudflare.tidb.management_api in katana_secrets.yaml. Katana-generated Data App, Data API key, region, and cutover state are stored in the Git-ignored cloudflare/tidb.yaml.

Define shared prefixes once in katana.yaml. Every @tidbDataService model uses the same list, and katana apply creates the generated physical databases through additive schema SQL.

cloudflare:
  tidb:
    prefixes:
      - dev

GitHub Sponsors

Sponsors are always welcome. Thank you for your support!

https://github.com/sponsors/mathrunet