OnDB uses an append-only storage model. Data is never overwritten or physically removed — every change is recorded as a new entry. Optional immutability via a Data Availability layer is available for use cases requiring on-chain verification.Documentation Index
Fetch the complete documentation index at: https://docs.ondb.ai/llms.txt
Use this file to discover all available pages before exploring further.
How It Works
| Operation | Behavior |
|---|---|
| Create | Appends a new record with a unique ID and timestamp |
| Read | Returns the latest version of a record by default (based on timestamp) |
| Update | Appends a NEW record with the same ID but a newer timestamp. The original record remains unchanged. |
| Delete | Appends a record with deleted: true (soft delete). Previous versions are preserved. |
Traditional DB vs OnDB
| Aspect | Traditional DB | OnDB |
|---|---|---|
| Update | Modifies existing row in place | Appends new version, old version preserved |
| Delete | Removes row from storage | Soft delete, data is preserved |
| History | Lost unless manually tracked | Automatic, all versions preserved |
| Audit trail | Requires additional implementation | Built-in, cryptographically verified |
| Storage | Fixed per record | Grows with each version |
Benefits
- Complete audit trail — All historical versions are preserved and can be queried
- Tamper-proof history — Past states cannot be altered or deleted
- Cryptographic verifiability — When on-chain mode is enabled, every change is recorded with a block height and transaction hash
- Conflict-free — No race conditions on writes since each version is a distinct record
Implications
- Storage grows with each update (each version is a new record)
- Historical versions can be queried by timestamp if needed
- Data is never physically removed from the blockchain
- “Deletes” are logical — they mark records as deleted but prior versions persist
Data Retention
While the underlying storage is immutable, OnDB supports configurable retention policies per collection to manage storage costs.| Setting | Description | Cost |
|---|---|---|
| Permanent | Data stored indefinitely, no automatic cleanup | Standard storage fees |
| 30 days or less | Free tier — no additional retention costs | Free |
| 31+ days | Extended retention with monthly cost per KB | Variable |
The first 30 days of retention are free for all collections. Costs only apply for retention periods beyond 30 days.
Configuring Retention
From the Dashboard:- Navigate to your application
- Select the Retention tab
- Expand a collection to view/edit its settings
- Enter the retention period in days (leave empty for permanent)
- Click Save to apply changes
Recommended Retention by Data Type
| Data Type | Recommended Retention |
|---|---|
| Session data | 7-14 days |
| User activity logs | 30-90 days |
| Analytics events | 30-180 days |
| Transaction records | Permanent |
| User profiles | Permanent |
| Audit logs | Permanent or compliance-required period |
Next Steps
CRUD Operations
See how append-only storage affects CRUD operations
Data Storage
Store data with payment handling