> ## 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.

# Immutability

> Append-only storage model with full audit trails

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.

## 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              |

<Note>
  The first 30 days of retention are free for all collections. Costs only apply for retention periods beyond 30 days.
</Note>

### Configuring Retention

From the [Dashboard](https://app.ondb.ai):

1. Navigate to your application
2. Select the **Retention** tab
3. Expand a collection to view/edit its settings
4. Enter the retention period in days (leave empty for permanent)
5. 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 |

<Warning>
  Once data is cleaned up by the retention policy, it cannot be recovered. Ensure you have appropriate backups for critical data before setting retention limits.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="CRUD Operations" icon="database" href="/crud/overview">
    See how append-only storage affects CRUD operations
  </Card>

  <Card title="Data Storage" icon="hard-drive" href="/concepts/data-storage">
    Store data with payment handling
  </Card>
</CardGroup>