Databases and Storage
Use organization databases and workflow state safely inside B3OS automations.
B3OS includes organization-scoped database capabilities so workflows can query and update durable data without requiring every team to operate a separate backend service.
Storage Layers
| Layer | Use |
|---|---|
| Workflow definition storage | Drafts, live versions, metadata, visibility, and validation state |
| Run and execution storage | Trigger input, node input/output, status, timing, sanitized errors, and activity |
| Organization database | Team-managed tables queried by workflow nodes |
| Connector storage | Encrypted provider credential data and masked client-visible metadata |
| Knowledge storage | Searchable organization knowledge used by Caddie workflow tooling |
Database Query Action
The db-query built-in action lets a workflow read or modify organization database state. Use it for lightweight operational data such as allowlists, account mappings, customer settings, campaign configuration, alert routing, or workflow memory that needs a table shape.
json{ "query": "select wallet_address, tier from customers where customer_id = $1", "params": ["{{$trigger.body.customerId}}"]}
Avoid broad writes and destructive operations. B3OS restricts dangerous statement classes, but workflow authors should still keep database access narrow and auditable.
Common Patterns
| Pattern | Example |
|---|---|
| Lookup before action | Fetch a routing rule before sending Slack or Telegram messages |
| Idempotency | Store processed external event IDs before sending payments or notifications |
| Policy | Check allowlists, thresholds, and per-customer settings before wallet actions |
| Enrichment | Join trigger input with known account or protocol metadata |
| Audit support | Write a compact operational record after a successful workflow |
Data Retention and Visibility
Workflow run data is visible to authorized organization users and APIs. Sensitive values are masked before display where B3OS recognizes connector secrets, tokens, keys, and configured sensitive fields.
Store provider IDs, customer IDs, token symbols, addresses, and routing metadata. Keep credentials in connectors and signing authority in wallets.
Query Design Checklist
- Parameterize values instead of concatenating strings.
- Keep read queries narrow with explicit filters.
- Use unique event IDs for idempotency.
- Avoid storing secret material in org tables.
- Validate query output before passing it into strict action schemas.
- Emit clear logs when a query returns no rows or too many rows.