Skip to main content

The Database Module

A module is a collection of functions and schema definitions, which can be written in TypeScript, C# or Rust. Modules define the structure of your database and the server-side logic that processes and handles client requests.

A database is a running instance of a module. While a module is the code you write (schema and reducers), a database is the actual deployed entity running on a SpacetimeDB host with stored data and active connections.

Module vs Database​

Understanding this distinction is important:

  • A module is the code you write; it defines your schema (tables) and business logic (reducers, procedures, and views). Modules are compiled and deployed to SpacetimeDB. Rust and C# modules compile to WebAssembly, while TypeScript modules run on V8.
  • A database is a running instance of a module; it has the module's schema and logic, plus actual stored data.

You can deploy the same module to multiple databases (e.g. separate environments for testing, staging, production), each with its own independent data. When you update your module code and re-publish, SpacetimeDB will update the database's schema/logic — the existing data remains (though for complicated schema changes you may need to handle migrations carefully).

What's in a Module?​

A module contains:

  • Tables - Define your data structure and storage.
  • Reducers - Server-side functions that modify your data transactionally.
  • Procedures - Functions that can perform external operations like HTTP requests and return results.
  • Views - Read-only computed queries over your data.

The logic is contained within these three categories of server-side functions: reducers (transactional state changes), procedures (functions with external capabilities), and views (read-only queries).

Supported Languages​

SpacetimeDB modules can be written in multiple languages:

Rust is fully supported for server modules. Rust is a great choice for performance-critical applications.

Database Names​

When you publish a module, you give the database a name. Database names must match the regex /^[a-z0-9]+(-[a-z0-9]+)*$/, i.e. only lowercase ASCII letters and numbers, separated by dashes.

Examples of valid names:

  • my-game-server
  • chat-app-production
  • test123

Each database also receives a unique identity (a hex string) when created. Clients can connect using either the name or identity.

Managing Databases​

Modules and databases are administered using the spacetime CLI tool.

Creating and Updating Databases​

Create or update a database by publishing your module:

spacetime publish <DATABASE_NAME>

See Building and Publishing for details on the publishing workflow.

When you republish to an existing database, SpacetimeDB attempts to automatically migrate the schema. For details on what changes are supported and migration strategies:

For all available publish options, see the spacetime publish CLI reference.

Deleting a Database​

To permanently delete a database and all its data:

spacetime delete <DATABASE_NAME>

You'll be prompted to confirm the deletion. Use --yes to skip the confirmation in scripts.

warning

Deleting a database is permanent and cannot be undone. All data will be lost.

For more options, see the spacetime delete CLI reference.

Querying with SQL​

You can run SQL queries directly against your database:

spacetime sql <DATABASE_NAME> "SELECT * FROM user"

Owner Privileges​

Important: When you run SQL queries as the database owner, you bypass table visibility restrictions. This means you can query private tables that normal clients cannot access.

To test queries as an unprivileged client would see them, use the --anonymous flag:

spacetime sql --anonymous <DATABASE_NAME> "SELECT * FROM user"

This executes the query as an anonymous client, respecting table visibility rules.

For more SQL options, see the spacetime sql CLI reference.

Viewing Logs​

View logs from your database:

spacetime logs <DATABASE_NAME>

Following Logs in Real-Time​

To stream logs as they're generated (similar to tail -f):

spacetime logs --follow <DATABASE_NAME>

This keeps the connection open and displays new log entries as they occur. Press Ctrl+C to stop following.

Limiting Log Output​

To view only the last N lines:

spacetime logs --num-lines 100 <DATABASE_NAME>

For more logging options, see the spacetime logs CLI reference.

Listing Your Databases​

To see all databases associated with your identity:

spacetime list

This shows database names, identities, and host servers.

Managing Databases via the Website​

You can also manage your databases through the SpacetimeDB web interface at spacetimedb.com:

  • View metrics - Monitor database performance, connection counts, and resource usage
  • Browse tables - Inspect table schemas and data
  • View logs - Access historical logs with filtering and search
  • Manage access - Control database permissions and team access
  • Monitor queries - See subscription queries and reducer calls
tip

The website provides a graphical interface for many CLI operations, making it easier to visualize and manage your databases.

Projects and Teams​

SpacetimeDB supports organizing databases into projects and managing team access. This allows you to:

  • Group related databases together
  • Share access with team members
  • Manage permissions at the project level

Learning Path​

Getting Started​

If you're new to SpacetimeDB, follow this recommended learning path:

  1. Create Your First Database Module - Set up a new module project with spacetime init or spacetime dev
  2. Build and Publish - Learn how to compile and deploy your module
  3. Define Tables - Structure your data with tables, columns, and indexes
  4. Write Reducers - Create transactional functions that modify your database
  5. Connect a Client - Build a client application that connects to your database

Core Concepts​

Once you have the basics down, explore these essential topics:

Advanced Features​

Ready to level up? Dive into these advanced capabilities:

Deployment​

When you're ready to go live:

Next Steps​