Building block 9 · Going further
Data & storage
Your extension doesn't need a storage system of its own. Charlie gives it three places to keep the person's data: a folder on this computer, the person's remote storage, and the person's own database. The data stays theirs, wherever it lives.
What you'd use it for
- Save small records on this computer with nothing to set up.
- Keep documents in the person's A.N.D.Why hub so they follow them to another machine.
- Store real tables, like a ledger, in the person's PostgreSQL database.
- Provide one of those places yourself, so other extensions can use it.
The three places
| In a handler | Where the data lives |
|---|---|
ctx.persistence | A folder on this computer, ~/ClaudeShared/charlie/data/. Always on. Nothing to declare. |
ctx.remotePersistence | Whichever extension holds the remotePersistence role. Today that is hub-persistence, which stores in the person's hub. |
ctx.rdbmsPg | A PostgreSQL database, through whichever extension holds the rdbmsPg role. Today that is hub-database. |
Both document stores work the same way: one JSON document per key, grouped under a collection name. They offer get, set, update, patchText, append, list and delete.
In your manifest
Using storage needs nothing in the manifest. Providing it does. This is from hub-database, which provides the database:
{
"name": "hub-database",
"role": "rdbmsPg",
"rdbms": { "module": "./handlers/rdbms.js" },
"connections": [
{ "name": "hub", "authType": "oauth2-discovery",
"transport": "rest-client" }
]
}And this is how its own query tool reaches the database, the same way any other extension would:
r = await ctx.rdbmsPg.query(sql, params, { maxRows })The hub-persistence extension (Finder) provides remote storage with "role": "remotePersistence" and "persistence": { "module": "./handlers/persistence.js" }.
What each part means
| Field | What it does |
|---|---|
persistence.module | For a remotePersistence provider. The file exports get, set, update, patchText, append, list and delete, each taking (ctx, collection, key, ...). |
rdbms.module | For a database provider. The file exports query, describe, import and info. Required with the rdbmsPg role. |
Things to know
- Storage isn't divided by extension. Every extension, and the model, reaches the same collections. Pick a specific collection name, and list it before creating a new one.
- Remote storage can land locally. If no extension holds the role, or the hub can't be reached, the call is saved to a local offline folder instead. Each result carries
ranLocally, so you can tell the person. - The database never falls back. With no working provider, every
ctx.rdbmsPgcall throws an error whosecodeis'unavailable'. Splitting someone's records across two databases would be worse. - Every extension sees every table. Start your table names with your own prefix, like
acct_, by convention. - Large numbers arrive as text. PostgreSQL
bigintandnumericvalues come back as strings, so money never loses precision. - The sqlite extension is separate. It keeps its own file,
~/ClaudeShared/charlie/sqlite/charlie.db, and doesn't hold a role. Other extensions can't reach it throughctx. - Never store passwords or keys here. Those belong in
ctx.secrets, which is encrypted and stays on this computer. See Settings. - Uninstalling keeps the data. Removing an extension never deletes the documents it stored.
See it in
- Finder (persistence)
Every field in detail: persistence and rdbms in the reference.