# What Is SpacetimeDB? Understanding the Database-Server Hybrid Architecture

> Discover SpacetimeDB a revolutionary database server hybrid running WebAssembly for microsecond latency and real-time sync Eliminate network hops and boost app performance

- Repository: [Clockwork Labs/SpacetimeDB](https://github.com/clockworklabs/SpacetimeDB)
- Tags: getting-started
- Published: 2026-03-09

---

**SpacetimeDB is a relational database that doubles as your application server, running WebAssembly modules inside the database process to eliminate network hops and deliver microsecond latency with automatic real-time synchronization.**

Unlike traditional architectures that separate the database from the application server, SpacetimeDB—developed by Clockwork Labs—colocates your business logic and data storage in a single process. You write **modules** in supported languages like Rust, C#, TypeScript, or C++, compile them to WebAssembly, and deploy them directly into the database runtime. This architecture removes the need for external caching layers, load balancers, or complex orchestration while providing ACID guarantees and live client subscriptions.

## The Core Concept: Database and Server as One

Traditional web applications require clients to connect to an API server, which then queries a separate database over the network. SpacetimeDB collapses this stack. Clients connect directly to the database process, invoke **reducers** (server-side functions), and subscribe to **tables**. When a reducer mutates data, SpacetimeDB instantly pushes updates to all subscribed clients without any intermediate network hop.

This colocated design achieves microsecond latency because your business logic runs inside the same process as the storage engine. As implemented in `clockworklabs/SpacetimeDB`, the core engine handles durable commit-log recovery, row-level security, and authentication natively.

### How Modules Work Inside the Database

SpacetimeDB executes your application logic using a WebAssembly runtime. According to the virtual machine documentation in [`crates/vm/README.md`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/vm/README.md), the database hosts a WASM runtime that powers reducer execution. Your module defines both the schema (tables) and the operations (reducers) that modify that schema, all compiled to a portable WASM binary that runs sandboxed inside the database process.

## Defining Data and Logic with Tables and Reducers

SpacetimeDB modules declare **tables** for persistent storage and **reducers** for transactional business logic. These declarations use language-specific macros that generate the necessary bindings for the WASM runtime.

### Declaring Tables with Macros

Tables are defined using the `#[spacetimedb::table]` macro, which registers the schema with the database engine. The implementation in [`crates/bindings-macro/src/table.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/bindings-macro/src/table.rs) handles the parsing of table attributes, primary keys, and access modifiers.

Here is a Rust module defining a `Message` table with an auto-incrementing primary key:

```rust
#[spacetimedb::table(accessor = messages, public)]
pub struct Message {
    #[primary_key]
    #[auto_inc]
    id: u64,
    sender: Identity,
    text: String,
}

```

The `public` attribute controls visibility, while `accessor = messages` generates a helper method for querying the table within reducers.

### Implementing Reducers as Server-Side Functions

Reducers are transaction-bound functions that mutate tables and represent the public API of your module. The `#[spacetimedb::reducer]` macro, implemented in [`crates/bindings-macro/src/reducer.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/bindings-macro/src/reducer.rs), registers these functions and handles the context injection.

Here is the corresponding reducer that inserts a new message:

```rust
#[spacetimedb::reducer]
pub fn send_message(ctx: &ReducerContext, text: String) {
    ctx.db.messages().insert(Message {
        id: 0,
        sender: ctx.sender,
        text,
    });
}

```

When a client calls `send_message`, the database executes the reducer within a transaction, persists the change, and automatically broadcasts the update to all clients subscribed to the `Message` table.

## Real-Time Client Synchronization

SpacetimeDB eliminates the need for manual polling or separate message queues by pushing changes directly to connected clients. The client SDKs handle subscription management and state reconciliation automatically.

### Subscribing to Tables from Client SDKs

Clients connect directly to the database and subscribe to specific tables or queries. When data changes, the server pushes deltas to the client, which updates its local cache. The TypeScript SDK documentation in [`crates/bindings-typescript/README.md`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/bindings-typescript/README.md) describes the hooks available for React applications.

Here is a TypeScript React component that subscribes to the `Message` table:

```typescript
import { useTable } from "@spacetimedb/client";

const [messages] = useTable(tables.message);
// `messages` updates automatically when the server state changes.

```

The `useTable` hook manages the subscription lifecycle, ensuring the client receives immediate updates when any reducer modifies the `Message` table. This architecture removes the complexity of WebSocket management, state reconciliation, and cache invalidation that typically burdens real-time applications.

## Development Workflow and CLI

SpacetimeDB provides a command-line interface to scaffold, test, and deploy modules locally or to the cloud. The CLI implementation is documented in [`crates/cli/README.md`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/cli/README.md).

To start a new project with a pre-configured React TypeScript template:

```bash

# install the CLI

curl -sSf https://install.spacetimedb.com | sh

# start a development instance with a chat template

spacetime dev --template chat-react-ts

```

The `spacetime dev` command compiles your module, starts a local database instance, and hosts the client application, providing a complete development environment without external dependencies.

## Summary

- **SpacetimeDB** is a relational database that embeds the application server, running WebAssembly modules inside the database process to eliminate network latency.
- **Modules** define **tables** (persistent data) and **reducers** (transactional business logic) using language-specific macros like `#[spacetimedb::table]` and `#[spacetimedb::reducer]`.
- Clients connect directly to the database, invoke reducers, and subscribe to tables, receiving automatic real-time updates without polling or separate caching layers.
- The architecture is implemented in Rust, with core components including the WASM runtime (`crates/vm`), macro bindings (`crates/bindings-macro`), and client SDKs (`crates/bindings-typescript`).

## Frequently Asked Questions

### What makes SpacetimeDB different from traditional databases?

Traditional architectures separate the database from the application server, requiring network hops for every query and complex caching layers to reduce latency. SpacetimeDB colocates the server logic inside the database process by running WebAssembly modules directly within the database runtime. This eliminates the network boundary between application logic and data storage, delivering microsecond latency and automatic real-time synchronization without external message queues or caches.

### What languages can I use to write SpacetimeDB modules?

SpacetimeDB supports modules written in **Rust**, **C#**, **TypeScript**, and **C++**. These modules are compiled to WebAssembly and loaded into the database process. The repository provides language-specific macro implementations—such as `#[spacetimedb::table]` and `#[spacetimedb::reducer]` in Rust—to define tables and server-side functions that interface with the core database engine.

### How does SpacetimeDB handle real-time updates?

When a client calls a **reducer** (a server-side function), the database executes the logic within a transaction and commits the changes to the relevant **tables**. SpacetimeDB then automatically pushes these changes to all clients subscribed to those tables via persistent connections. Client SDKs like the TypeScript library provide hooks such as `useTable` that manage subscriptions and update local state automatically, eliminating the need for manual polling or WebSocket management.

### Is SpacetimeDB suitable for production applications?

Yes. SpacetimeDB is built with production requirements in mind, featuring **ACID transactions**, **durable commit-log recovery**, **row-level security**, and built-in **authentication**. The core engine is written in Rust for performance and safety, and the WebAssembly sandboxing ensures module isolation. While the project provides quick-start templates for development (`spacetime dev`), it also supports deployment to cloud infrastructure with the same architectural guarantees.