Automatic vs. Explicit Persistence
- ๐ Automatic (Snapshots)
- ๐พ Explicit (Persistence)
Built-in session persistence
- Works automatically without any code
- Preserves state when users leave and return
- Lost when code changes (new session created)
- Perfect for temporary game sessions
Any code change creates a new session, losing all previous data.
Session Identity System
Understanding how Multisynq identifies sessions is crucial for persistence:๐ sessionId
Code-dependent session identifier
- Combination of
appId
,name
, and code hash - Changes with any code modification
- Used for snapshots and live sessions
๐ persistentId
Code-independent persistent identifier
- Combination of
appId
andname
only - Survives code changes
- Used for persistence lookup
How Persistence Works
1
First Session Join
When joining a session with a never-seen-before sessionId:
- Multisynq looks up persistent data by
persistentId
- If found, passes it to your modelโs
init()
method - Your model restores state from persistent data
2
Saving Persistent Data
Your application decides when to save using
persistSession()
:3
Code Update
When you update your code:
- New sessionId is generated (code changed)
- Same persistentId is used (appId + name unchanged)
- Persistent data is loaded into new code version
Basic Implementation
- Simple Pattern
- Advanced Pattern
Most applications can use this straightforward approach:
This pattern works well for simple applications with straightforward data structures.
Data Serialization Requirements
Critical:
persistSession()
uses stable JSON stringification. Non-JSON types require special handling.- โ JSON-Safe Types
- โ ๏ธ Requires Conversion
These work automatically:
When to Use Persistence
โ
Good Use Cases
โ Good Use Cases
Applications that benefit from persistence:
- Collaborative editors: Documents must survive code updates
- Creative tools: User creations are valuable
- Configuration apps: Settings should persist
- Score tracking: High scores across game updates
- Chat applications: Message history preservation
โ Not Needed
โ Not Needed
Applications that donโt need persistence:
- Simple games: No long-term state to preserve
- Temporary demonstrations: Short-lived sessions
- Real-time only: No data worth preserving
- Prototype applications: Data structure still changing
If you donโt need to preserve data across code changes, snapshots are sufficient.
When to Save Data
Unlike automatic snapshots, you control when to save persistent data. Balance data safety with performance.
- ๐ฅ Major Changes
- โฐ Timer-Based
Save after significant data modifications:
Error Handling and Recovery
Critical: Implement error handling to prevent data corruption during development.
- Safe Loading Pattern
- Development Workflow
Protect against corrupted persistent data:
Version Management
๐ Data Format Evolution
๐ Data Format Evolution
Handle changing data formats over time:
๐ง Migration Strategies
๐ง Migration Strategies
Handle breaking changes safely:
Debugging Tools
- Debug Options
- Manual Inspection
Enable detailed logging:Console output:
Security and Encryption
End-to-End Encryption: Persistent data inherits Multisynqโs security model.
๐ Secure by Default
Your data is protected:
- All persistent data is encrypted
- Only clients with session password can decrypt
- Server cannot read your data
- Suitable for sensitive information
โ ๏ธ Password Management
Important considerations:
- Lost password = lost data (unrecoverable)
- Consider password storage strategy
- Balance security vs. convenience
Best Practices Summary
๐ Planning
Think ahead about persistence:
- Plan persistence from the start
- Canโt add persistence to existing sessions
- Consider what data needs to survive updates
- Design for data format evolution
โก Performance
Optimize save frequency:
- Save after major changes only
- Use timers for burst activity
- Keep persistent data minimal
- Clean up unnecessary data
๐ก๏ธ Safety
Handle errors gracefully:
- Validate persistent data structure
- Handle version mismatches
- Donโt save during loading
- Test with corrupted data
๐ Testing
Test thoroughly:
- Test fresh sessions
- Test loading from persistence
- Test data migrations
- Use separate deployments for testing
Real-World Examples
๐ Document Editor
๐ Document Editor
๐จ Creative Canvas
๐จ Creative Canvas
Next Steps
Writing a Multisynq Model
Learn to build models with persistence in mind
Data API
Explore advanced data management patterns
Snapshots
Understand how snapshots and persistence work together
Sim Time & Future
Master time-based behaviors in persistent applications
Persistence is essential for applications where user data has long-term value. Plan for it early, implement it safely, and test thoroughly to ensure your users never lose their important work.