Chapter 16: Schema Evolution, Migrations, and Advanced Design Patterns

Introduction

Welcome to Chapter 16! So far, we’ve explored the core concepts of SpaceTimeDB, built real-time applications, and even delved into performance and security. But what happens when your application grows, and your initial data model no longer fits your evolving needs? This is where schema evolution and data migrations come into play.

In this chapter, we’ll tackle the crucial, yet often overlooked, aspects of managing change in your SpaceTimeDB projects. We’ll learn how to gracefully adapt your database schema over time without disrupting existing data or live applications. We’ll also explore different strategies for migrating data when your schema changes require transforming existing information. Finally, we’ll dive into advanced design patterns like Event Sourcing and CQRS, showing how SpaceTimeDB’s unique architecture naturally supports them, helping you build even more robust and scalable systems.

This chapter is designed for developers who are ready to build production-grade SpaceTimeDB applications that can adapt and grow. We’ll assume you’re comfortable with defining tables, writing reducers, and interacting with SpaceTimeDB from a client. Let’s get ready to master change!

Core Concepts: Schema Evolution in SpaceTimeDB

Schema evolution refers to the process of adapting your database structure over the lifespan of an application. As features are added or business requirements change, your data model will inevitably need adjustments.

What Makes SpaceTimeDB Schema Evolution Unique?

In traditional relational databases (like PostgreSQL or MySQL), schema is defined using Data Definition Language (DDL) statements (e.g., CREATE TABLE, ALTER TABLE). You often manage these changes with external migration tools (like Flyway or Alembic).

SpaceTimeDB, however, treats your schema as part of your application’s module code. Your tables, their fields, and their types are declared directly within your Rust modules. This tight integration means:

Source of Truth: Your Rust module code is the definitive source of truth for your database schema.
Atomic Deployment: When you deploy a new version of your SpaceTimeDB module, both the application logic (reducers) and the schema definitions are updated together.
Strong Typing: Rust’s strong type system provides compile-time checks, catching many potential schema-related errors before deployment.

The Challenge of Change

Imagine you have a Player table:

// modules/game/src/lib.rs
#[spacetimedb(table)]
pub struct Player {
    #[primarykey]
    pub id: u64,
    pub username: String,
    pub score: u32,
}

Now, your game needs to store a player’s level and a last_login timestamp. How do you add these fields without losing existing player data? What if you later decide to rename username to display_name? These are the challenges of schema evolution.

SpaceTimeDB’s Approach to Module Updates

When you deploy a new version of your SpaceTimeDB module, the system intelligently compares the new schema definition with the existing one.

Adding New Fields: If you add a new field to an existing table, SpaceTimeDB will add that column. For existing rows, the new field will typically be initialized with its default value (e.g., 0 for numbers, empty string for String, None for Option<T>). This is usually a backward-compatible change.
Removing Fields: If you remove a field, SpaceTimeDB will remove the corresponding column. This is a breaking change for any clients or reducers that rely on that field. The data in that column will be lost.
Changing Field Types: Changing a field’s type (e.g., u32 to String) is almost always a breaking change and will likely result in data loss or conversion errors for existing data.
Renaming Fields/Tables: This is essentially a removal of the old and addition of the new. It’s a breaking change.

Key takeaway: While SpaceTimeDB manages the underlying database changes, you are responsible for ensuring that your application logic (reducers, client code) can handle these schema changes, especially regarding existing data.

Backward and Forward Compatibility

Backward Compatibility: A new version of your schema is backward-compatible if old clients or reducers can still interact with it without breaking. Adding nullable fields is often backward-compatible.
Forward Compatibility: An old client/reducer can interact with a newer schema. This is harder to achieve and less common, as older code typically doesn’t know about new fields.

For SpaceTimeDB, the focus is primarily on backward compatibility for your clients and ensuring your reducers gracefully handle schema changes.

Core Concepts: Data Migrations

Sometimes, evolving your schema isn’t enough; you need to transform your existing data to fit the new schema. This is where data migrations come in.

Why Data Migrations?

Consider these scenarios:

Splitting a Field: You have a full_name: String field and decide to split it into first_name: String and last_name: String. Existing full_name data needs to be parsed and moved.
Combining Fields: You have address_line1, address_line2, city, zip_code and decide to consolidate into a single address_json: String.
Data Normalization/Denormalization: Changing how data is structured across tables.
Populating New Fields: As in our Player example, when adding display_name, you might want to pre-populate it for existing players based on their username.

SpaceTimeDB offers a few strategies for data migrations:

1. In-Reducer Migrations (Limited Scope)

For very simple migrations, you can embed logic directly within your reducers to handle older data formats.

How it works: When a reducer reads data, it checks if a field exists or is in an old format. If so, it performs a conversion on the fly and then writes the updated data back.

Pros:

No separate migration script needed.
Data is updated opportunistically as it’s accessed.

Cons:

Can make reducers more complex and harder to read.
Doesn’t “clean up” all old data at once; only updates when a row is touched.
Not suitable for large-scale transformations or changes that affect many rows infrequently.

2. One-Off Module-Based Migrations

This is a common and robust approach in SpaceTimeDB. You create a temporary reducer or a specific module function designed solely to perform the data migration.

How it works:

Define a new reducer (e.g., migrate_player_data).
Inside this reducer, iterate through the relevant table(s).
For each row, apply your data transformation logic.
Update the row using SpaceTimeDB.update().
Crucially, add a mechanism to ensure this reducer runs only once (e.g., a special “migration_status” table, or a check that it has already run).
Deploy your module.
Call the migration reducer from a client.
Once successfully run and verified, you can remove the migration reducer from your module in a subsequent deployment.

Pros:

Keeps migration logic separate from core application reducers.
Ensures all relevant data is transformed consistently.
Leverages SpaceTimeDB’s transactional and real-time update guarantees.

Cons:

Requires careful management to ensure it runs only once.
Can be resource-intensive for very large datasets, potentially impacting live system performance.

3. External Script Migrations (for Complex Scenarios)

For highly complex, large-scale, or highly customized data transformations, you might opt for an external script.

How it works:

Write a script (e.g., in TypeScript/Node.js or Python) that connects to your SpaceTimeDB instance using its client SDK.
The script queries data, performs transformations in memory, and then sends update commands back to SpaceTimeDB.
This script often bypasses reducers directly, using privileged client connections if necessary, or calling specific reducers designed for raw data updates.

Pros:

Full control over the migration process.
Can leverage external libraries and tooling for complex data processing.
Can be run offline or during maintenance windows.

Cons:

Bypasses reducer logic, potentially violating business rules if not carefully managed.
Requires careful transaction management and error handling in the external script.
Potential for race conditions if the system is live and other clients are modifying data.
Less integrated with SpaceTimeDB’s core consistency model. Use with extreme caution and only when necessary.

Hands-on: Implementing a Simple Schema Evolution and Migration

Let’s put these concepts into practice. We’ll simulate a game scenario where we need to add a display_name field to our Player table and populate it for existing players.

Scenario: Adding and Populating `display_name`

Imagine our game has been running for a while. Players have id, username, and score. We now want to introduce a display_name field, which should initially be the same as username for existing players, but can be changed later.

Step 1: Initial Schema (Recap)

First, let’s establish our initial Player table in modules/game/src/lib.rs.

// modules/game/src/lib.rs
// (Make sure you have your standard SpaceTimeDB module boilerplate)

use spacetimedb::{spacetimedb, table, ReducerContext, Identity, timestamp};

#[spacetimedb(table)]
pub struct Player {
    #[primarykey]
    pub id: u64,
    pub username: String,
    pub score: u32,
}

// A simple reducer to create a player for testing
#[spacetimedb(reducer)]
pub fn create_player(ctx: ReducerContext, username: String) {
    let id = Player::iter().count() as u64 + 1; // Simple ID generation
    Player::insert(Player {
        id,
        username,
        score: 0,
    }).expect("Failed to insert player");
    log::info!("Player created: {}", username);
}

// ... other reducers or event definitions as needed ...

Action:

Save the above code in modules/game/src/lib.rs.
Deploy this initial version:
```
spacetime deploy
```

Connect a client (e.g., your frontend or a simple Node.js script) and create a few players:

// Example client-side code (Node.js or browser)
import { SpacetimeDBClient } from "@clockworklabs/spacetimedb-sdk";
import { createPlayer } from "./module_bindings"; // Assuming generated bindings

const client = new SpacetimeDBClient("ws://localhost:3000"); // Adjust if not local
client.connect();

client.onConnect(() => {
    console.log("Connected to SpaceTimeDB!");
    createPlayer("Alice");
    createPlayer("Bob");
    createPlayer("Charlie");
});

// You can also subscribe to the Player table to see data
client.subscribe([{tableName: "Player"}]);
client.on("Player:insert", (player) => console.log("New Player:", player));

Run this client code and ensure Alice, Bob, and Charlie are created. You can verify with spacetime client or spacetime db dump.

Step 2: Evolving the Schema

Now, let’s add the display_name field to our Player table. We’ll make it an Option<String> initially to handle cases where it might not be immediately set, but for our migration, we’ll populate it.

Modify modules/game/src/lib.rs:

// modules/game/src/lib.rs
// ... (existing use statements) ...

#[spacetimedb(table)]
pub struct Player {
    #[primarykey]
    pub id: u664, // Corrected u64 typo from previous thought process
    pub username: String,
    pub score: u32,
    pub display_name: Option<String>, // <--- NEW FIELD!
}

// ... (existing create_player reducer) ...

Explanation: We’ve added pub display_name: Option<String>,. When you deploy this change, SpaceTimeDB will add a new display_name column to the Player table. For all existing rows (Alice, Bob, Charlie), this new field will be None. New players created after this deployment would also have display_name as None by default unless explicitly set in create_player or another reducer.

Action:

Update modules/game/src/lib.rs with the display_name field.
Deploy the updated module:
```
spacetime deploy
```
You should see a message indicating schema changes were applied.
Verify the schema change (e.g., spacetime db dump Player or connect with spacetime client and inspect the schema). You’ll see display_name as null for existing players.

Step 3: Creating a Migration Reducer

Now, let’s write a one-off migration reducer to populate display_name for existing players. We’ll also add a simple MigrationStatus table to ensure this migration runs only once.

Add the following to modules/game/src/lib.rs:

// modules/game/src/lib.rs
// ... (existing Player table and create_player reducer) ...

#[spacetimedb(table)]
pub struct MigrationStatus {
    #[primarykey]
    pub migration_name: String,
    pub completed_at: u64, // Timestamp
}

#[spacetimedb(reducer)]
pub fn migrate_player_display_names(_ctx: ReducerContext) {
    let migration_name = "populate_player_display_names".to_string();

    // Check if migration has already been completed
    if MigrationStatus::filter_by_migration_name(&migration_name).is_some() {
        log::info!("Migration '{}' already completed. Skipping.", migration_name);
        return;
    }

    log::info!("Starting migration: '{}'", migration_name);

    // Iterate through all players and update their display_name
    for mut player in Player::iter() {
        if player.display_name.is_none() {
            // Only update if display_name is not already set
            player.display_name = Some(player.username.clone());
            Player::update(player.id, player).expect("Failed to update player during migration");
            log::info!("Updated player {} (id: {}) with display_name: {}", player.username, player.id, player.display_name.as_ref().unwrap());
        }
    }

    // Mark migration as completed
    MigrationStatus::insert(MigrationStatus {
        migration_name,
        completed_at: timestamp(),
    }).expect("Failed to insert migration status");

    log::info!("Migration completed successfully!");
}

Explanation:

MigrationStatus Table: This new table is a simple way to track which migrations have run. It has a migration_name (primary key) and completed_at timestamp.
migrate_player_display_names Reducer:
- It defines a migration_name constant.
- It first checks MigrationStatus::filter_by_migration_name to see if this migration has already been recorded as completed. If so, it exits early, preventing re-execution (this is crucial for idempotency).
- It then iterates through Player::iter(), which gives us mutable references to each Player row.
- Inside the loop, it checks if player.display_name is None. If it is, we populate it with the player.username.
- Player::update(player.id, player) commits the changes to the database.
- After iterating through all players, it inserts a record into MigrationStatus to mark the migration as done.

Step 4: Deploying and Executing the Migration

Now, deploy the module with the new MigrationStatus table and the migration reducer. Then, call the reducer from your client.

Action:

Add the MigrationStatus table and migrate_player_display_names reducer to modules/game/src/lib.rs.
Deploy the module:
```
spacetime deploy
```

From your client-side code, call the migration reducer. Ensure you have the migratePlayerDisplayNames binding generated.

// Example client-side code (Node.js or browser)
import { SpacetimeDBClient } from "@clockworklabs/spacetimedb-sdk";
import { createPlayer, migratePlayerDisplayNames } from "./module_bindings"; // Assuming generated bindings

const client = new SpacetimeDBClient("ws://localhost:3000");
client.connect();

client.onConnect(() => {
    console.log("Connected to SpaceTimeDB!");

    // Call the migration reducer
    migratePlayerDisplayNames();

    // Optionally, create a new player to see how display_name behaves
    // createPlayer("David");
});

client.subscribe([{ tableName: "Player" }, { tableName: "MigrationStatus" }]);
client.on("Player:insert", (player) => console.log("New Player:", player));
client.on("Player:update", (oldPlayer, newPlayer) => console.log("Player Updated:", newPlayer));
client.on("MigrationStatus:insert", (status) => console.log("Migration Status:", status));

Run the client. You should see log messages indicating the migration starting, players being updated, and the migration completing.
Verify the data:
- Use spacetime db dump Player to confirm display_name is now set for Alice, Bob, and Charlie.
- Use spacetime db dump MigrationStatus to confirm the populate_player_display_names migration is recorded.

Step 5: Cleaning Up (Optional but Recommended)

Once the migration has successfully run and you’ve verified the data, you can (and often should) remove the migrate_player_display_names reducer and potentially the MigrationStatus table from your module. This keeps your production module lean and prevents accidental re-execution.

Action:

Comment out or delete the MigrationStatus table and migrate_player_display_names reducer from modules/game/src/lib.rs.
Deploy the module again:
```
spacetime deploy
```
SpaceTimeDB will detect that MigrationStatus and the reducer are no longer defined and will remove them. The data in Player will remain as migrated.

This hands-on exercise demonstrates a practical way to evolve your schema and migrate data using SpaceTimeDB’s module-based approach.

Advanced Design Patterns for SpaceTimeDB

SpaceTimeDB’s unique architecture – combining a database, real-time synchronization, and deterministic server-side logic – makes it an excellent fit for several advanced architectural patterns.

1. Event Sourcing with SpaceTimeDB

What is Event Sourcing? Instead of storing the current state of an application, Event Sourcing stores every change to the state as a sequence of immutable events. The current state is then derived by replaying these events.

How SpaceTimeDB Supports It: SpaceTimeDB’s reducer model is inherently event-driven. Each reducer call is essentially an “event” that modifies the global state. You can extend this by:

Event Tables: Create dedicated tables to store historical events. For example, a ChatEvent table might store MessageSent, UserJoined, UserLeft events.
State Derivation: Your main application tables (e.g., ChatRoomState) can then be populated or updated by reducers that process these events.

Benefits:

Auditability: A complete, immutable history of every change.
Time Travel: Replay events to reconstruct state at any point in time.
Debugging: Easier to trace how a particular state was reached.
Consistency: Events are processed deterministically by reducers.

Example: Simple Chat Application

Let’s imagine a ChatRoom with messages.

flowchart TD Client_A[Client A] --> Reducer_SendMessage[Reducer: sendMessage] Reducer_SendMessage --> Event_Table[Table: ChatEvent ] Event_Table --> Reducer_ProcessEvent[Reducer: processChatEvent ] Reducer_ProcessEvent --> State_Table[Table: ChatRoomState ] State_Table --> Client_B[Client B ] Event_Table --> Client_C[Client C ]

Mermaid Diagram: Event Sourcing Flow with SpaceTimeDB

In this pattern:

A client calls a reducer (e.g., send_message).
This reducer first records a new MessageSent event into a ChatEvent table.
Then, another internal reducer (or the same one) processes this ChatEvent to update the ChatRoomState table, which holds the current, derived list of messages.
Clients subscribe to ChatRoomState to see the live chat, and potentially ChatEvent for an audit log.

2. Command-Query Responsibility Segregation (CQRS)

What is CQRS? CQRS separates the concerns of modifying data (“Commands”) from reading data (“Queries”). This means you might have different models or even different databases optimized for writes versus reads.

How SpaceTimeDB Supports It: SpaceTimeDB naturally aligns with CQRS:

Commands (Writes): Your reducers are the “command handlers.” They take input (commands), apply business logic, and modify the database state. This is your write model.
Queries (Reads): Client subscriptions to tables are your “query model.” Clients subscribe to the data they need, and SpaceTimeDB streams real-time updates. This is your read model.

Benefits:

Scalability: Read and write paths can be optimized and scaled independently.
Flexibility: Read models can be denormalized for optimal querying without affecting the write model’s integrity.
Performance: Queries can be highly optimized for specific client needs.

Example: User Profile Management

You might have a User table for core user data (write model, updated by reducers) and a UserProfileView table (a derived, denormalized table updated by other reducers) that combines User data with GameStats for quick display on a profile page (read model).

3. Distributed Counters and Aggregates

Challenge: How do you efficiently manage shared counters (e.g., “total active users,” “likes on a post”) or aggregates (e.g., “sum of all player scores”) in a real-time, distributed system?

SpaceTimeDB Solution: Reducers are perfect for this. Because reducers execute deterministically and atomically, they can safely increment/decrement counters or update aggregates without race conditions.

#[spacetimedb(table)]
pub struct GlobalStats {
    #[primarykey]
    pub key: String, // e.g., "total_users", "total_posts"
    pub value: u64,
}

#[spacetimedb(reducer)]
pub fn increment_user_count(_ctx: ReducerContext) {
    let key = "total_users".to_string();
    let mut stat = GlobalStats::filter_by_key(&key)
        .unwrap_or_else(|| GlobalStats { key: key.clone(), value: 0 });
    stat.value += 1;
    GlobalStats::update_or_insert(stat);
}

This reducer ensures that total_users is incremented safely and atomically, even with many concurrent calls.

4. State Machines

What is a State Machine? A state machine models the behavior of an entity by representing its possible states and the transitions between them. For example, an order might go from Pending -> Processing -> Shipped -> Delivered.

How SpaceTimeDB Supports It: SpaceTimeDB tables can store the current state of an entity, and reducers can enforce the valid transitions.

// Example: Order Status
pub enum OrderStatus {
    Pending,
    Processing,
    Shipped,
    Delivered,
    Cancelled,
}

#[spacetimedb(table)]
pub struct Order {
    #[primarykey]
    pub id: u64,
    pub customer_id: u64,
    pub status: OrderStatus,
    // ... other order details
}

#[spacetimedb(reducer)]
pub fn ship_order(_ctx: ReducerContext, order_id: u64) {
    let mut order = Order::filter_by_id(&order_id)
        .expect("Order not found.");

    match order.status {
        OrderStatus::Processing => {
            order.status = OrderStatus::Shipped;
            Order::update(order_id, order).expect("Failed to update order status.");
            log::info!("Order {} shipped.", order_id);
        }
        _ => {
            log::warn!("Cannot ship order {} from status: {:?}", order_id, order.status);
            // You might want to return an error or revert transaction in a real system
        }
    }
}

This reducer ensures that an order can only be Shipped if its current status is Processing, enforcing the state machine’s rules.

Mini-Challenge: Implement an Event-Sourced Like Feature

Let’s enhance our simple game (or a new project if you prefer) to incorporate an event-sourced pattern for player actions.

Challenge:

Create a new table called PlayerActionEvent. This table should record events like PlayerMoved or ItemPickedUp. It should store:
- An id (primary key, u64).
- player_id (u64).
- event_type (String, e.g., “Moved”, “PickedUp”).
- details (String, a JSON string or simple description, e.g., “Moved to (10, 5)”, “Picked up ‘Health Potion’”).
- timestamp (u64).
Modify an existing reducer (or create a new one) that handles a player action (e.g., move_player or pick_up_item). In addition to updating the player’s position or inventory, this reducer should also insert a new row into the PlayerActionEvent table.
Create a new derived table, PlayerRecentActions, which stores the last 3 actions for each player. This table should be updated by another reducer that listens to PlayerActionEvent inserts. (Hint: This will involve deleting old actions if a player has more than 3.)
From your client, call the action reducer a few times for a player and then subscribe to PlayerRecentActions to observe the derived state.

Hint:

For PlayerActionEvent, details could be an Option<String> if some events have no details.
For PlayerRecentActions, you might need a composite primary key or a unique index on (player_id, action_timestamp) to manage ordering, or simply filter and sort within your reducer.
Remember timestamp() for recording event times.

What to observe/learn:

How to combine direct state updates with event logging.
The concept of creating “event streams” in SpaceTimeDB.
How to derive and maintain a separate, optimized read model (like PlayerRecentActions) from an event stream using reducers.
The power of SpaceTimeDB’s deterministic execution for building consistent derived views.

Common Pitfalls & Troubleshooting

1. Breaking Schema Changes Without Planning

Pitfall: Deploying a schema change (e.g., removing a field, changing a type) without considering its impact on existing data or client applications.
Troubleshooting:
- Always test schema changes in a development environment first.
- For breaking changes, plan a multi-step deployment:
 1. Add new fields (make them optional or default initially).
 2. Migrate data to the new fields.
 3. Update clients/reducers to use new fields.
 4. (Optional) Remove old fields.
- Use Option<T> for new fields to ensure backward compatibility during transitions.

2. Non-Idempotent Migrations

Pitfall: A migration reducer that, if run multiple times, would cause incorrect data (e.g., incrementing a value multiple times when it should only be incremented once).
Troubleshooting:
- Always design migrations to be idempotent. This means running them once or a hundred times yields the same correct result.
- Our MigrationStatus table pattern is a good example of ensuring idempotency by checking if a migration has already run.
- For updates, check the current state before applying a change (e.g., if player.display_name.is_none() { ... }).

3. Over-Complicating In-Reducer Migrations

Pitfall: Embedding too much complex data transformation logic directly into core application reducers.
Troubleshooting:
- Keep core reducers focused on their primary business logic.
- If a migration is complex or affects many rows, use the “one-off module-based migration” strategy to isolate the logic.
- Long-running reducers can impact performance; separate them if they need to iterate over large datasets.

4. Race Conditions with External Migrations

Pitfall: Running an external script that directly modifies SpaceTimeDB data while other clients are actively writing, leading to inconsistent states.
Troubleshooting:
- Avoid external script migrations unless absolutely necessary. Prefer module-based reducers.
- If you must use an external script, run it during a maintenance window when no other writes are occurring.
- Consider implementing locking mechanisms (e.g., a “migration_in_progress” flag in a SpaceTimeDB table) that reducers can check before processing updates, though this adds complexity.

Summary

Phew! You’ve just mastered some of the most advanced concepts in SpaceTimeDB development. Let’s recap the key takeaways from this chapter:

Schema Evolution: SpaceTimeDB’s schema is defined in your Rust modules, providing a unified source of truth. Changes are applied atomically on deployment.
Managing Change: Understand the implications of adding, removing, or changing field types. Prioritize backward compatibility for your clients and reducers.
Data Migrations:
- In-Reducer: For simple, opportunistic data fixes.
- One-Off Module-Based: The recommended approach for structured migrations, using a temporary reducer to transform data and a MigrationStatus table for idempotency.
- External Script: For highly complex scenarios, but use with extreme caution due to potential consistency issues.
Advanced Design Patterns:
- Event Sourcing: Naturally supported by SpaceTimeDB’s reducer model, allowing you to store immutable event streams and derive application state.
- CQRS: SpaceTimeDB inherently separates command (reducer) and query (subscription) responsibilities, enabling optimized read/write paths.
- Distributed Counters: Reducers provide a safe and atomic way to manage shared counters and aggregates.
- State Machines: Model entity lifecycles by storing state in tables and enforcing transitions within deterministic reducers.
Best Practices: Always test schema changes, ensure migrations are idempotent, and choose the right migration strategy for the complexity of the task.

You now have the tools and knowledge to not only build powerful real-time applications with SpaceTimeDB but also to maintain and evolve them gracefully over time. This is a critical skill for any long-lived project.

In the next chapter, we’ll shift our focus to deployment strategies, ensuring your finely crafted SpaceTimeDB application can run reliably in production environments.

References

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.

Chapter 16: Schema Evolution, Migrations, and Advanced Design Patterns

Table of Contents

Introduction

Core Concepts: Schema Evolution in SpaceTimeDB

What Makes SpaceTimeDB Schema Evolution Unique?

The Challenge of Change

SpaceTimeDB’s Approach to Module Updates

Backward and Forward Compatibility

Core Concepts: Data Migrations

1. In-Reducer Migrations (Limited Scope)

2. One-Off Module-Based Migrations

3. External Script Migrations (for Complex Scenarios)

Hands-on: Implementing a Simple Schema Evolution and Migration

Scenario: Adding and Populating display_name

Step 1: Initial Schema (Recap)

Step 2: Evolving the Schema

Step 3: Creating a Migration Reducer

Step 4: Deploying and Executing the Migration

Step 5: Cleaning Up (Optional but Recommended)

Advanced Design Patterns for SpaceTimeDB

1. Event Sourcing with SpaceTimeDB

2. Command-Query Responsibility Segregation (CQRS)

3. Distributed Counters and Aggregates

4. State Machines

Mini-Challenge: Implement an Event-Sourced Like Feature

Common Pitfalls & Troubleshooting

1. Breaking Schema Changes Without Planning

2. Non-Idempotent Migrations

3. Over-Complicating In-Reducer Migrations

4. Race Conditions with External Migrations

Summary

References

Scenario: Adding and Populating `display_name`