Understanding Orthogonal Persistence

On most platforms, your application and your data live in two separate places: code runs on a server, and data sits in a database you connect to, query, and maintain. OpenCloud doesn't work that way. With orthogonal persistence, your data lives directly inside your code — and the platform keeps it there automatically. There's no database to set up, connect to, or manage.

This is one of the biggest mental shifts for new users, so this article explains what it means, why it exists, and how to work with it safely.

The short version

Your variables are your storage. When you set a value in your backend, it persists — across calls, restarts, and upgrades — without a database, files, or save logic.

If you declare a counter and increment it, that number is simply still there the next time anyone calls your Engine. You didn't write it to a database, because there isn't one.

The traditional model vs. orthogonal persistence

Traditional stack:

1. Code runs in memory (temporary — lost on restart).
2. To keep anything, you serialize it and write it to a separate database.
3. To read it back, you connect, query, and deserialize.
4. You maintain that database: schemas, migrations, backups, scaling, connection limits.

Orthogonal persistence:

1. Code runs and holds state in variables.
2. The platform persists that state automatically.
3. To read it back, you... just use the variable.
4. There's no separate database to maintain.

The word orthogonal means persistence is independent of your code's logic — you don't think about saving and loading as a separate concern. It just happens.

What this looks like in practice

In Motoko, state is just a variable on your actor:

actor {  // This value persists automatically — no database call anywhere.  stable var visits : Nat = 0;  public func recordVisit() : async Nat {    visits += 1;    return visits;   // still here on the next call, and the next deploy  };}

There's no connect(), no INSERT, no SELECT. The data is the variable. (See Write Your First Backend in Motoko for the full example.)

Why OpenCloud works this way

• Less to build and operate. No database to provision, secure, scale, or back up — removing a whole category of ops work.
• Fewer moving parts to fail. No connection pools, no separate datastore to go down, no sync issues between app and DB.
• It fits sovereign, autonomous Engines. Because data lives inside the Engine, the Engine is genuinely self-contained — which is what makes it portable across node providers without dragging an external database along.

The one thing you must understand: stable and upgrades

Persistence is automatic while your Engine runs. The subtle part is code upgrades — when you deploy new code, existing data has to carry over into the new version.

In Motoko, you mark data you want to survive upgrades as stable:

stable var orders : [Order] = [];   // survives upgradesvar cache : [Item] = [];            // transient — may be discarded on upgrade

• stable data is preserved across upgrades.
• Non-stable (transient) data can be re-initialized on upgrade — good for caches, bad for anything you need to keep.

Lossy migrations

If an upgrade would destroy or corrupt persisted data — for example, removing a stable variable or changing its type in an incompatible way — OpenCloud detects this lossy migration and warns you before it runs, so you don't silently lose production data. If something still goes wrong, you can roll the Engine back.

Rule of thumb: mark anything you need to keep as stable, evolve your data types carefully, and always read migration warnings before confirming an upgrade.

Common questions

"Where's my database? How do I back up?"
There isn't one to manage — your state lives in your Engine. 

"Does my data persist if the Engine restarts or a node fails?"
Yes. State is persisted and the network runs your Engine replicated across nodes, so individual node failures don't lose your data.

"Is there a storage limit?"
Storage consumes cycles on an ongoing basis, so your practical limit is your funded balance.

Next steps

• Write Your First Backend in Motoko — See persistence in working code.
• Restore or Roll Back an Engine After a Bad Upgrade — Your safety net for migrations.
• What Are Cycles? — Why stored data has an ongoing cost.