How to Debug SpacetimeDB: Inspect Tables, Run SQL, Call Reducers, and Read Logs

When a SpacetimeDB-powered app behaves unexpectedly, the fastest route to an answer is often to inspect the database state behind it. Did the expected row get inserted? Does the table have the columns your client expects? Did the reducer run, and what did the server log? A repeatable debugging workflow helps you answer these questions without guessing.

This guide walks through that workflow using the SpacetimeDB CLI, the Maincloud dashboard, and graphical clients such as Spacetime Studio. The CLI and dashboard are useful tools in their own right. Studio brings table browsing, schema inspection, SQL, reducer calls, logs, and saved connections together in a desktop workspace.

A practical SpacetimeDB debugging workflow

Start by reproducing the issue and writing down what you expected to happen. Then inspect the database in a few focused steps:

1. Confirm you are connected to the intended server and database.
2. Check the schema and find the table that should have changed.
3. Inspect relevant rows or run a read query to see the current state.
4. Call the reducer with a known input when you need to isolate server-side behavior.
5. Review the logs around that action and compare the resulting data with your expectation.

This sequence separates common causes: connecting to the wrong environment, using an outdated table or column name, sending unexpected reducer arguments, or having a reducer produce different state than you assumed.

Check the schema and table data

Begin with the schema. Confirm that the table and columns exist with the names and types your module and client expect. Table names used in SQL are the names defined by your module; they are not automatically pluralized or converted to another naming style. A small naming mismatch can make a valid query appear broken.

Next, browse the table rows. Look for a missing record, an unexpected default, a stale value, or a relationship key that does not match the row you are tracing. For a game, that might mean checking whether a player row was created, whether a session points to the right player, or whether a position update reached the table.

SpacetimeDB tables can be private or public. Private tables are available to reducers and the database owner, while public tables are readable by clients through subscriptions. If a table is not visible from a client, check its visibility and the permissions of the identity you are using; do not make sensitive data public just to make debugging easier. See the official table visibility documentation.

Use SQL to narrow down a problem

A graphical table browser is handy for scanning rows. SQL is useful when you want to ask a precise question, filter a large table, or inspect a few related values. For example, if your module has a player table with an identity column, you might look up one player like this:

SELECT * FROM player WHERE identity = 'your-player-identity';

Replace the table and column names with the exact names in your module. Start with a narrow, read-only query, then widen it if needed. If the result is empty, verify the connection, identifier, table name, and any visibility restrictions before assuming the reducer failed.

The SpacetimeDB HTTP API supports SQL queries and reducer invocation for interactive management and debugging. You can work through the CLI or API directly, or use a GUI with a SQL editor to issue a query and inspect its results. See the official database HTTP API reference.

Call reducers deliberately

If you suspect a reducer, test it with a specific set of arguments and inspect what changes afterward. A manual reducer call can help isolate server logic from your client UI, input handling, or network timing. Record the database and arguments used so you can reproduce the same check.

Remember that reducers can mutate state. Use a local development database when experimenting. On a shared environment, understand the reducer's effects first and avoid sending test inputs that create, delete, or overwrite data you care about. A GUI makes reducer calls accessible, but it does not make a mutating operation harmless.

Use logs to follow execution

Logs provide context for what happened around a request. Check them at the same time you reproduce the problem, then correlate the relevant entries with the reducer call and the rows you inspected. This can help distinguish a request that never reached the server from one that ran but produced an unexpected result.

Logs are most useful alongside the schema and data rather than on their own. Read a log entry, form a hypothesis, and confirm it by checking the affected rows or repeating the action with a controlled input.

Choose the right SpacetimeDB debugging tool

The SpacetimeDB CLI is a good fit for terminal-first workflows, scripts, and deployment tasks. It is part of the official toolchain and is often the quickest choice when you already know the command you need.

The Maincloud dashboard is convenient when you host on Maincloud and want to inspect or manage a database from the hosting provider's web interface. Hosting-specific tools belong there; for local or self-hosted servers, use a client that can connect to those environments.

Spacetime Studio is a free, open-source desktop GUI for local, Maincloud, and self-hosted SpacetimeDB. It is useful when debugging involves several kinds of inspection: browse the schema and rows, run SQL, call reducers, follow logs, and switch between saved connections without piecing together separate windows or commands.

These tools can complement each other. You might use the CLI to publish a module, Studio to inspect its data and test a reducer, and the Maincloud dashboard to review hosting information. Choose the tool that makes the current question easiest to answer.

Debug with Spacetime Studio

In Studio, save a connection to the server and database you want to inspect, then use the database tools in one place:

• Schema and tables: see the structure of your module and browse table rows with pagination.
• SQL: run a focused query and inspect the returned data.
• Reducers: call a reducer with chosen arguments when you need to test server behavior directly.
• Logs: follow database logs while reproducing an issue.
• Connections: switch among local, staging, Maincloud, or self-hosted databases saved in the app.

Studio also supports inline row editing and CSV or JSON export for workflows that need them. Credentials are stored in the operating system keychain, and read-only mode blocks writes in Studio's backend for connections where you only want to inspect. As with any database client, use server authentication and permissions to control who can connect.

Because Studio is a native desktop client, you can keep it beside your editor and game or web app while you reproduce a bug. There is no need to move your database to use it: connect to a local server, Maincloud, or a reachable self-hosted instance. Studio does not deploy your module or replace your hosting provider.

Download Spacetime Studio for Windows, macOS, or Linux, or browse the MIT-licensed source on GitHub.

Debug safely across environments

It is easy to inspect the wrong database when a project has local, staging, and production instances. Give saved connections clear names, confirm the server and database before running a query, and use read-only access for production investigation whenever possible.

Prefer read queries while diagnosing. Before calling a reducer or editing a row, understand whether it changes persistent state and whether the environment contains data you need to preserve. Keep credentials private, grant only the access a developer needs, and remember that a client-side read-only setting complements rather than replaces server-side authorization.

Frequently asked questions

How do I inspect SpacetimeDB table data?

Use a compatible GUI to browse tables, or run SQL through the CLI or database HTTP API. You need to connect to the correct server and have permission to read the data.

Can I debug a local SpacetimeDB database with Spacetime Studio?

Yes. Start your local SpacetimeDB server, then connect Studio to its URL and choose the database you want to inspect. Local standalone servers commonly listen on port 3000.

Can I call reducers from a GUI?

Yes. Spacetime Studio includes reducer calls. Since reducers may change database state, test carefully and prefer a local or development database while experimenting.

Does Spacetime Studio replace the SpacetimeDB CLI?

No. Studio focuses on database inspection and interactive operations. Keep using the CLI for terminal workflows such as publishing and other command-line tasks.

Why can I not see a table or row?

Check that you connected to the intended database, that the table and row exist, and that your identity has permission to access them. Private tables are not generally visible to regular clients.