masamune_model_tidb 3.5.2

Masamune plugin package that includes a model adapter to retrieve data from TiDB.

Masamune Model TiDB

---

[GitHub] | [YouTube] | [Packages] | [X] | [LinkedIn] | [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
    connection_url: mysql://user:[e-mail]:4000/app_db

Katana CLI stores the TiDB connection URL in Cloudflare Workers secrets with wrangler secret put.

TiDB Cloud Starter and Essential clusters require a username prefix. For example, if the TiDB Cloud connection dialog shows 4M9hEa4vE3S7jAF.root, the prefix is 4M9hEa4vE3S7jAF. Use the prefixed username in connection_url:

mysql://4M9hEa4vE3S7jAF.root:<PASSWORD>@gateway01.ap-northeast-1.prod.aws.tidbcloud.com:4000/app_db

The root password in connection_url is used only by the Workers backend and is not returned to the Flutter client.

In direct mode, TiDB databases are not created automatically. Create the database in TiDB Cloud before using it. This includes prefixed databases such as dev_main. Tables and missing columns are created automatically on save.

In Data Service mode, 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:
    mode: data_service
    data_service:
      prefixes:
        - dev

GitHub Sponsors

Sponsors are always welcome. Thank you for your support!

https://github.com/sponsors/mathrunet