# SpacetimeDB > SpacetimeDB is a database that lets you write your entire application as a database module. Server logic runs inside the database as WebAssembly. Clients subscribe to queries and get real-time updates over WebSocket. No separate server needed. ## docs Installation - [Getting Started](/docs/): Installation ### bsatn The Spacetime Algebraic Type Notation binary (BSATN) format defines - [BSATN Data Format](/docs/bsatn): The Spacetime Algebraic Type Notation binary (BSATN) format defines ### cli-reference This document contains the help content for the spacetime command-line program. - [Command-Line Help for spacetime](/docs/cli-reference): This document contains the help content for the spacetime command-line program. - [spacetime.json Configuration File](/docs/cli-reference/spacetime-json): The spacetime.json file defines project-level configuration for the SpacetimeDB CLI. It eliminates repetitive CLI flags and enables multi-target workflows such as publishing multiple databases or generating bindings for multiple languages from a single project. - [Standalone Configuration](/docs/cli-reference/standalone-config): A local database instance (as started by spacetime start) can be configured in /config.toml, where {data-dir} is the database's data directory. This directory is printed when you run spacetime start: ### clients The SpacetimeDB Client SDKs provide a comprehensive interface for building applications that connect to SpacetimeDB databases. Client applications can query data, invoke server-side functions, and receive real-time updates as the database state changes. - [Clients](/docs/clients): The SpacetimeDB Client SDKs provide a comprehensive interface for building applications that connect to SpacetimeDB databases. Client applications can query data, invoke server-side functions, and receive real-time updates as the database state changes. - [SDK API Overview](/docs/clients/api): The SpacetimeDB client SDKs provide a comprehensive API for interacting with your database. After generating client bindings and establishing a connection, you can query data, invoke server functions, and observe real-time changes. - [C# Reference](/docs/clients/c-sharp): The SpacetimeDB client for C# contains all the tools you need to build native clients for SpacetimeDB modules using C#. - [Generating Client Bindings](/docs/clients/codegen): Before you can interact with a SpacetimeDB database from a client application, you must generate client bindings for your module. These bindings create type-safe interfaces that allow your client to query tables, invoke reducers, call procedures, and subscribe to tables, and/or views. - [Connecting to SpacetimeDB](/docs/clients/connection): After generating client bindings for your module, you can establish a connection to your SpacetimeDB database from your client application. The DbConnection type provides a persistent WebSocket connection that enables real-time communication with the server. - [Rust Reference](/docs/clients/rust): The SpacetimeDB client SDK for Rust contains all the tools you need to build native clients for SpacetimeDB modules using Rust. - [Subscriptions](/docs/clients/subscriptions): Subscriptions replicate database rows to your client in real-time. When you subscribe to a query, SpacetimeDB sends you the matching rows immediately and then pushes updates whenever those rows change. - [Subscription Semantics](/docs/clients/subscriptions/semantics): This document describes the subscription semantics maintained by the SpacetimeDB host over WebSocket connections. These semantics outline message ordering guarantees, subscription handling, transaction updates, and client cache consistency. - [TypeScript Reference](/docs/clients/typescript): The SpacetimeDB client SDK for TypeScript contains all the tools you need to build clients for SpacetimeDB modules using Typescript, either in the browser or with NodeJS. - [Unreal Reference](/docs/clients/unreal): The SpacetimeDB client for Unreal Engine contains all the tools you need to build native clients for SpacetimeDB modules using C++ and Blueprint. ### core-concepts This section covers the fundamental concepts you need to understand to build applications with SpacetimeDB. - [Core Concepts](/docs/core-concepts): This section covers the fundamental concepts you need to understand to build applications with SpacetimeDB. - [Authentication](/docs/core-concepts/authentication): SpacetimeDB modules are exposed to the open internet and anyone can connect to - [Auth0](/docs/core-concepts/authentication/Auth0): This guide will walk you through integrating Auth0 authentication with your SpacetimeDB application. - [Better Auth](/docs/core-concepts/authentication/BetterAuth): Better Auth is a TypeScript authentication - [Clerk](/docs/core-concepts/authentication/Clerk): This guide will walk you through integrating Clerk authentication with your SpacetimeDB React application. You will configure a Clerk application, obtain a JWT from Clerk, and pass it to your SpacetimeDB connection as the authentication token. - [Overview](/docs/core-concepts/authentication/spacetimeauth/): SpacetimeAuth is currently in beta, some features may not be available yet or - [Configuring your project](/docs/core-concepts/authentication/spacetimeauth/configuring-a-project): SpacetimeAuth is currently in beta, some features may not be available yet or may change in the future. You might encounter bugs or issues while using the service. Please report any problems you encounter to help us improve SpacetimeAuth. - [Creating a project](/docs/core-concepts/authentication/spacetimeauth/creating-a-project): SpacetimeAuth is currently in beta, some features may not be available yet or may change in the future. You might encounter bugs or issues while using the service. Please report any problems you encounter to help us improve SpacetimeAuth. - [React Integration](/docs/core-concepts/authentication/spacetimeauth/react-integration): SpacetimeAuth is currently in beta, some features may not be available yet or may change in the future. You might encounter bugs or issues while using the service. Please report any problems you encounter to help us improve SpacetimeAuth. - [Steam Session Ticket Authentication](/docs/core-concepts/authentication/spacetimeauth/steam): SpacetimeAuth supports authentication using Steam's Session Ticket system. This allows - [Testing](/docs/core-concepts/authentication/spacetimeauth/testing): SpacetimeAuth is currently in beta, some features may not be available yet or may change in the future. You might encounter bugs or issues while using the service. Please report any problems you encounter to help us improve SpacetimeAuth. - [Using Auth Claims](/docs/core-concepts/authentication/usage): SpacetimeDB allows you to easily access authentication (auth) claims embedded in ### databases A module is a collection of functions and schema definitions, which can be written in TypeScript, C#, Rust, or C++. Modules define the structure of your database and the server-side logic that processes and handles client requests. - [The Database Module](/docs/databases): A module is a collection of functions and schema definitions, which can be written in TypeScript, C#, Rust, or C++. Modules define the structure of your database and the server-side logic that processes and handles client requests. - [Automatic Migrations](/docs/databases/automatic-migrations): When you republish a module to an existing database using spacetime publish , SpacetimeDB attempts to automatically migrate your database schema to match the new module definition. This allows you to update your module code and redeploy without losing existing data, as long as the changes are compatible. - [spacetime publish](/docs/databases/building-publishing): This guide covers how to build and publish your SpacetimeDB module. - [Cheat Sheet](/docs/databases/cheat-sheet): Quick reference for SpacetimeDB module syntax across Rust, C#, TypeScript, and C++. - [spacetime dev](/docs/databases/developing): This guide covers how to create a new SpacetimeDB database module project. - [Incremental Migrations](/docs/databases/incremental-migrations): SpacetimeDB does not provide built-in support for general schema-modifying migrations. It does, however, allow adding new tables, and changing reducers' definitions in arbitrary ways. It's possible to run general migrations using an external tool, but this is tedious, necessitates downtime, and imposes the requirement that you update all your clients at the same time as publishing your new module version. - [Transactions and Atomicity](/docs/databases/transactions-atomicity): SpacetimeDB provides strong transactional guarantees for all database operations. Every reducer runs inside a database transaction, ensuring your data remains consistent and reliable even under concurrent load. ### functions | Property / Characteristic | Reducers | Procedures | Views | - [Functions](/docs/functions): | Property / Characteristic | Reducers | Procedures | Views | - [HTTP Handlers](/docs/functions/http-handlers): HTTP handlers allow a SpacetimeDB database to expose an HTTP API. - [Procedures](/docs/functions/procedures): A procedure is a function exported by a database, similar to a reducer. - [Overview](/docs/functions/reducers): Reducers are functions that modify database state in response to client requests or system events. They are the only way to mutate tables in SpacetimeDB - all database changes must go through reducers. - [Error Handling](/docs/functions/reducers/error-handling): Error Handling - [Lifecycle Reducers](/docs/functions/reducers/lifecycle): Special reducers handle system events during the database lifecycle. - [Reducer Context](/docs/functions/reducers/reducer-context): Every reducer receives a special context parameter as its first argument. This context provides read-write access to the database, information about the caller, and additional utilities like random number generation. - [Views](/docs/functions/views): Views are read-only functions that compute and return results from your tables. Unlike reducers, views do not modify database state - they only query and return data. Views are useful for computing derived data, aggregations, or joining multiple tables before sending results to clients. ### how-to - [Maincloud](/docs/how-to/deploy/maincloud): Maincloud is SpacetimeDB's fully managed serverless platform. It handles infrastructure, scaling, replication, and backups so you can focus on building your application. Maincloud scales to zero when your database is idle, so you only pay for what you use. - [Railway](/docs/how-to/deploy/railway): Railway is a hosted platform for deploying infrastructure and application services. If you want to run SpacetimeDB without managing your own VM, the official Railway template is a quick way to get started. - [Self-hosting](/docs/how-to/deploy/self-hosting): This tutorial will guide you through setting up SpacetimeDB on an Ubuntu 24.04 server, securing it with HTTPS using Nginx and Let's Encrypt, and configuring a systemd service to keep it running. - [Logging](/docs/how-to/logging): SpacetimeDB provides logging capabilities for debugging and monitoring your modules. Log messages are private to the database owner and are not visible to clients. - [PostgreSQL Wire Protocol (PGWire)](/docs/how-to/pg-wire): SpacetimeDB supports the PostgreSQL wire protocol (PGWire), - [Reject Client Connections](/docs/how-to/reject-client-connections): SpacetimeDB provides a way to disconnect a client during a client connection attempt. - [Row Level Security](/docs/how-to/rls): Row Level Security is an experimental, unstable feature. The API may change or be removed in future releases. - [Azure Self-Hosted VMs + Key Rotation & Key Vault](/docs/how-to/self-hosted-key-rotation): This guide explains how JWT signing key rotation works in self-hosted SpacetimeDB and how to avoid breaking spacetime publish during rotation. ### http - [Authorization](/docs/http/authorization): Generating identities and tokens - [/v1/database](/docs/http/database): The HTTP endpoints in /v1/database allow clients to interact with Spacetime databases in a variety of ways, including retrieving information, creating and deleting databases, invoking reducers and evaluating SQL queries. These APIs are intended primarily for management, debugging and interactive developer use, and have not been optimized for performance to the same extent as the WebSocket API used by the SpacetimeDB client SDKs. - [/v1/identity](/docs/http/identity): The HTTP endpoints in /v1/identity allow clients to generate and manage Spacetime public identities and private tokens. ### intro - [FAQ](/docs/intro/faq): General - [Key Architecture](/docs/intro/key-architecture): Host - [Language Support](/docs/intro/language-support): Server Database Modules - [What is SpacetimeDB?](/docs/intro/what-is-spacetimedb): SpacetimeDB is a database that is also a server. - [The Zen of SpacetimeDB](/docs/intro/zen): SpacetimeDB is built on 5 core principles. As you embrace these simple principles, you will find your troubles simply melt away. These principles guide both how we develop SpacetimeDB and how you should think about building applications with it. ### quickstarts - [Angular Quickstart](/docs/quickstarts/angular): Get a SpacetimeDB Angular app running in under 5 minutes. - [Astro Quickstart](/docs/quickstarts/astro): Get a SpacetimeDB Astro app running in under 5 minutes. - [Browser Quickstart](/docs/quickstarts/browser): Get a SpacetimeDB app running in the browser with inline JavaScript. - [Bun Quickstart](/docs/quickstarts/bun): Get a SpacetimeDB Bun app running in under 5 minutes. - [C++ Quickstart](/docs/quickstarts/c-plus-plus): Get a SpacetimeDB C++ app running in under 5 minutes. - [C# Quickstart](/docs/quickstarts/c-sharp): Get a SpacetimeDB C# app running in under 5 minutes. - [Deno Quickstart](/docs/quickstarts/deno): Get a SpacetimeDB Deno app running in under 5 minutes. - [Next.js Quickstart](/docs/quickstarts/nextjs): Get a SpacetimeDB Next.js app running in under 5 minutes. - [Node.js Quickstart](/docs/quickstarts/nodejs): Get a SpacetimeDB Node.js app running in under 5 minutes. - [Nuxt Quickstart](/docs/quickstarts/nuxt): Get a SpacetimeDB Nuxt app running in under 5 minutes. - [React Quickstart](/docs/quickstarts/react): Get a SpacetimeDB React app running in under 5 minutes. - [Remix Quickstart](/docs/quickstarts/remix): Get a SpacetimeDB Remix app running in under 5 minutes. - [Rust Quickstart](/docs/quickstarts/rust): Get a SpacetimeDB Rust app running in under 5 minutes. - [SolidJS Quickstart](/docs/quickstarts/solid): Get a SpacetimeDB SolidJS app running in under 5 minutes. - [Svelte Quickstart](/docs/quickstarts/svelte): Get a SpacetimeDB Svelte app running in under 5 minutes. - [TanStack Start Quickstart](/docs/quickstarts/tanstack): Get a SpacetimeDB app with TanStack Start running in under 5 minutes. - [TypeScript Quickstart](/docs/quickstarts/typescript): Get a SpacetimeDB TypeScript app running in under 5 minutes. - [Vue Quickstart](/docs/quickstarts/vue): Get a SpacetimeDB Vue app running in under 5 minutes. ### reference - [Commitlog](/docs/reference/internals/commitlog): The commitlog is the write-ahead log (WAL) used by SpacetimeDB to persist all committed transactions. As an in-memory database, SpacetimeDB relies entirely on this log for durability. Every committed transaction is written to the commitlog before it is considered durable, and the full state of any database can be reconstructed by replaying the log from the beginning. - [SQL Reference](/docs/reference/sql): SpacetimeDB supports two subsets of SQL: ### resources Guides, references, and tools to help you build with SpacetimeDB. - [Developer Resources](/docs/resources): Guides, references, and tools to help you build with SpacetimeDB. ### sats-json The Spacetime Algebraic Type System JSON format defines how Spacetime AlgebraicTypes and AlgebraicValues are encoded as JSON. Algebraic types and values are JSON-encoded for transport via the HTTP Databases API and the WebSocket text protocol. Note that SATS-JSON is not self-describing, and so a SATS value represented in JSON requires knowing the value's schema to meaningfully understand it - for example, it's not possible to tell whether a JSON object with a single field is a ProductValue with one element or a SumValue. - [SATS-JSON Data Format](/docs/sats-json): The Spacetime Algebraic Type System JSON format defines how Spacetime AlgebraicTypes and AlgebraicValues are encoded as JSON. Algebraic types and values are JSON-encoded for transport via the HTTP Databases API and the WebSocket text protocol. Note that SATS-JSON is not self-describing, and so a SATS value represented in JSON requires knowing the value's schema to meaningfully understand it - for example, it's not possible to tell whether a JSON object with a single field is a ProductValue with one element or a SumValue. ### tables Tables are the way to store data in SpacetimeDB. All data in SpacetimeDB is stored in memory for extremely low latency and high throughput access. SpacetimeDB also automatically persists all data to disk. - [Tables](/docs/tables): Tables are the way to store data in SpacetimeDB. All data in SpacetimeDB is stored in memory for extremely low latency and high throughput access. SpacetimeDB also automatically persists all data to disk. - [Table Access Permissions](/docs/tables/access-permissions): SpacetimeDB controls data access through table visibility and context-based permissions. Tables can be public or private, and different execution contexts (reducers, views, clients) have different levels of access. - [Auto-Increment](/docs/tables/auto-increment): Auto-increment columns automatically generate unique integer values for new rows. When you insert a row with a zero value in an auto-increment column, SpacetimeDB assigns the next value from an internal sequence. - [Column Types](/docs/tables/column-types): Columns define the structure of your tables. SpacetimeDB supports primitive types, composite types for complex data, and special types for database-specific functionality. - [Constraints](/docs/tables/constraints): Constraints enforce data integrity rules on your tables. SpacetimeDB supports primary key and unique constraints. - [Default Values](/docs/tables/default-values): Default values allow you to add new columns to existing tables during automatic migrations. When you republish a module with a new column that has a default value, existing rows are automatically populated with that default. - [Event Tables](/docs/tables/event-tables): In many applications, particularly games and real-time systems, modules need to notify clients about things that happened without storing that information permanently. A combat system might need to tell clients "entity X took 50 damage" so they can display a floating damage number, but there is no reason to keep that record in the database after the moment has passed. - [File Storage](/docs/tables/file-storage): SpacetimeDB can store binary data directly in table columns, making it suitable for files, images, and other blobs that need to participate in transactions and subscriptions. - [Indexes](/docs/tables/indexes): Indexes accelerate queries by maintaining sorted data structures alongside your tables. Without an index, finding rows that match a condition requires scanning every row. With an index, the database locates matching rows directly. - [Performance Best Practices](/docs/tables/performance): Follow these guidelines to optimize table performance in your SpacetimeDB modules. - [Schedule Tables](/docs/tables/schedule-tables): Tables can trigger reducers or procedures at specific times by including a special scheduling column. This allows you to schedule future actions like sending reminders, expiring items, or running periodic maintenance tasks. ### troubleshooting This is a list of common problems when using SpacetimeDB and how to fix them. - [Troubleshooting](/docs/troubleshooting): This is a list of common problems when using SpacetimeDB and how to fix them. ### tutorials - [Chat App Tutorial](/docs/tutorials/chat-app): In this tutorial, we'll implement a simple chat server as a SpacetimeDB module. You can write your module in TypeScript, C#, or Rust - use the tabs throughout this guide to see code examples in your preferred language. - [Godot Tutorial](/docs/tutorials/godot): Need help with the tutorial or CLI commands? Join our Discord server! - [1 - Setup](/docs/tutorials/godot/part-1): Unity Tutorial Hero Image - [2 - Connecting to SpacetimeDB](/docs/tutorials/godot/part-2): Need help with the tutorial? Join our Discord server! - [3 - Gameplay](/docs/tutorials/Godot/part-3): Need help with the tutorial? Join our Discord server! - [4 - Moving and Colliding](/docs/tutorials/Godot/part-4): Need help with the tutorial? Join our Discord server! - [Unity Tutorial](/docs/tutorials/unity): Need help with the tutorial or CLI commands? Join our Discord server! - [1 - Setup](/docs/tutorials/unity/part-1): Unity Tutorial Hero Image - [2 - Connecting to SpacetimeDB](/docs/tutorials/unity/part-2): Need help with the tutorial? Join our Discord server! - [3 - Gameplay](/docs/tutorials/unity/part-3): Need help with the tutorial? Join our Discord server! - [4 - Moving and Colliding](/docs/tutorials/unity/part-4): Need help with the tutorial? Join our Discord server! - [Unreal Tutorial](/docs/tutorials/unreal): Need help with the tutorial or CLI commands? Join our Discord server! - [1 - Setup](/docs/tutorials/unreal/part-1): Need help with the tutorial? Join our Discord server! - [2 - Connecting to SpacetimeDB](/docs/tutorials/unreal/part-2): Need help with the tutorial? Join our Discord server! - [3 - Gameplay](/docs/tutorials/unreal/part-3): Need help with the tutorial? Join our Discord server! - [4 - Moving and Colliding](/docs/tutorials/unreal/part-4): Need help with the tutorial? Join our Discord server! ### upgrade This guide covers the breaking changes between SpacetimeDB 1.0 and 2.0 and how to update your code. - [Migrating from SpacetimeDB 1.0 to 2.0](/docs/upgrade): This guide covers the breaking changes between SpacetimeDB 1.0 and 2.0 and how to update your code. ### webassembly-abi This document specifies the low level details of module-host interactions ("Module ABI"). **Most users** looking to interact with the host will want to use derived and higher level functionality like bindings], #[spacetimedb(table)], and #[derive(SpacetimeType)] rather than this low level ABI. For more on those, read the [Rust module quick start guide and the Rust module reference. - [Module ABI Reference](/docs/webassembly-abi): This document specifies the low level details of module-host interactions ("Module ABI"). **Most users** looking to interact with the host will want to use derived and higher level functionality like bindings], #[spacetimedb(table)], and #[derive(SpacetimeType)] rather than this low level ABI. For more on those, read the [Rust module quick start guide and the Rust module reference. --- # Full Documentation Content # BSATN Data Format The Spacetime Algebraic Type Notation binary (BSATN) format defines how Spacetime `AlgebraicValue`s and friends are encoded as byte strings. Algebraic values and product values are BSATN-encoded for e.g., module-host communication and for storing row data in the database. ## Notes on notation[​](#notes-on-notation "Direct link to Notes on notation") In this reference, we give a formal definition of the format. To do this, we use inductive definitions, and define the following notation: * `bsatn(x)` denotes a function converting some value `x` to a list of bytes. * `a: B` means that `a` is of type `B`. * `Foo(x)` denotes extracting `x` out of some variant or type `Foo`. * `a ++ b` denotes concatenating two byte lists `a` and `b`. * `bsatn(A) = bsatn(B) | ... | bsatn(Z)` where `B` to `Z` are variants of `A` means that `bsatn(A)` is defined as e.g., `bsatn(B)`, `bsatn(C)`, .., `bsatn(Z)` depending on what variant of `A` it was. * `[]` denotes the empty list of bytes. ## Values[​](#values "Direct link to Values") ### At a glance[​](#at-a-glance "Direct link to At a glance") | Type | Description | | ----------------------------------- | ---------------------------------------------------- | | [`AlgebraicValue`](#algebraicvalue) | A value of any type. | | [`SumValue`](#sumvalue) | A value of a sum type, i.e. an enum or tagged union. | | [`ProductValue`](#productvalue) | A value of a product type, i.e. a struct or tuple. | ### `AlgebraicValue`[​](#algebraicvalue "Direct link to algebraicvalue") The BSATN encoding of an `AlgebraicValue` defers to the encoding of each variant: ``` bsatn(AlgebraicValue) = bsatn(SumValue) | bsatn(ProductValue) | bsatn(ArrayValue) | bsatn(String) | bsatn(Bool) | bsatn(U8) | bsatn(U16) | bsatn(U32) | bsatn(U64) | bsatn(U128) | bsatn(U256) | bsatn(I8) | bsatn(I16) | bsatn(I32) | bsatn(I64) | bsatn(I128) | bsatn(I256) | bsatn(F32) | bsatn(F64) ``` Algebraic values include sums, products, arrays, strings, and primitives types. The primitive types include booleans, unsigned and signed integers up to 256-bits, and floats, both single and double precision. ### `SumValue`[​](#sumvalue "Direct link to sumvalue") An instance of a sum type, i.e. an enum or tagged union. `SumValue`s are binary-encoded as `bsatn(tag) ++ bsatn(variant_data)` where `tag: u8` is an index into the `SumType.variants` array of the value's `SumType`, and where `variant_data` is the data of the variant. For variants holding no data, i.e., of some zero sized type, `bsatn(variant_data) = []`. ### `ProductValue`[​](#productvalue "Direct link to productvalue") An instance of a product type, i.e. a struct or tuple. `ProductValue`s are binary encoded as: ``` bsatn(elems) = bsatn(elem_0) ++ .. ++ bsatn(elem_n) ``` Field names are not encoded. ### `ArrayValue`[​](#arrayvalue "Direct link to arrayvalue") The encoding of an `ArrayValue` is: ``` bsatn(ArrayValue(a)) = bsatn(len(a) as u32) ++ bsatn(normalize(a)_0) ++ .. ++ bsatn(normalize(a)_n) ``` where `normalize(a)` for `a: ArrayValue` converts `a` to a list of `AlgebraicValue`s. ### Strings[​](#strings "Direct link to Strings") For strings, the encoding is defined as: ``` bsatn(String(s)) = bsatn(len(s) as u32) ++ bsatn(utf8_to_bytes(s)) ``` That is, the BSATN encoding is the concatenation of * the bsatn of the string's length as a `u32` integer byte * the utf8 representation of the string as a byte array ### Primitives[​](#primitives "Direct link to Primitives") For the primitive variants of `AlgebraicValue`, the BSATN encodings are:s ``` bsatn(Bool(false)) = [0] bsatn(Bool(true)) = [1] bsatn(U8(x)) = [x] bsatn(U16(x: u16)) = to_little_endian_bytes(x) bsatn(U32(x: u32)) = to_little_endian_bytes(x) bsatn(U64(x: u64)) = to_little_endian_bytes(x) bsatn(U128(x: u128)) = to_little_endian_bytes(x) bsatn(U256(x: u256)) = to_little_endian_bytes(x) bsatn(I8(x: i8)) = to_little_endian_bytes(x) bsatn(I16(x: i16)) = to_little_endian_bytes(x) bsatn(I32(x: i32)) = to_little_endian_bytes(x) bsatn(I64(x: i64)) = to_little_endian_bytes(x) bsatn(I128(x: i128)) = to_little_endian_bytes(x) bsatn(I256(x: i256)) = to_little_endian_bytes(x) bsatn(F32(x: f32)) = bsatn(f32_to_raw_bits(x)) // lossless conversion bsatn(F64(x: f64)) = bsatn(f64_to_raw_bits(x)) // lossless conversion bsatn(String(s)) = bsatn(len(s) as u32) ++ bsatn(bytes(s)) ``` Where * `f32_to_raw_bits(x)` extracts the raw bits of `x: f32` to `u32` * `f64_to_raw_bits(x)` extracts the raw bits of `x: f64` to `u64` ## Types[​](#types "Direct link to Types") All SATS types are BSATN-encoded by converting them to an `AlgebraicValue`, then BSATN-encoding that meta-value. See [the SATN JSON Format](/docs/sats-json) for more details of the conversion to meta values. Note that these meta values are converted to BSATN and *not JSON*. --- # Command-Line Help for `spacetime` This document contains the help content for the `spacetime` command-line program. **Command Overview:** * [`spacetime`↴](#spacetime) * [`spacetime publish`↴](#spacetime-publish) * [`spacetime delete`↴](#spacetime-delete) * [`spacetime logs`↴](#spacetime-logs) * [`spacetime call`↴](#spacetime-call) * [`spacetime describe`↴](#spacetime-describe) * [`spacetime dev`↴](#spacetime-dev) * [`spacetime sql`↴](#spacetime-sql) * [`spacetime rename`↴](#spacetime-rename) * [`spacetime generate`↴](#spacetime-generate) * [`spacetime list`↴](#spacetime-list) * [`spacetime login`↴](#spacetime-login) * [`spacetime login show`↴](#spacetime-login-show) * [`spacetime logout`↴](#spacetime-logout) * [`spacetime init`↴](#spacetime-init) * [`spacetime build`↴](#spacetime-build) * [`spacetime server`↴](#spacetime-server) * [`spacetime server list`↴](#spacetime-server-list) * [`spacetime server set-default`↴](#spacetime-server-set-default) * [`spacetime server add`↴](#spacetime-server-add) * [`spacetime server remove`↴](#spacetime-server-remove) * [`spacetime server fingerprint`↴](#spacetime-server-fingerprint) * [`spacetime server ping`↴](#spacetime-server-ping) * [`spacetime server edit`↴](#spacetime-server-edit) * [`spacetime server clear`↴](#spacetime-server-clear) * [`spacetime subscribe`↴](#spacetime-subscribe) * [`spacetime start`↴](#spacetime-start) * [`spacetime version`↴](#spacetime-version) ## `spacetime`[​](#spacetime "Direct link to spacetime") **Usage:** `spacetime [OPTIONS] ` ###### **Subcommands:**[​](#subcommands "Direct link to subcommands") * `publish` — Create and update a SpacetimeDB database * `delete` — Deletes a SpacetimeDB database * `logs` — Prints logs from a SpacetimeDB database * `call` — Invokes a function (reducer or procedure) in a database. WARNING: This command is UNSTABLE and subject to breaking changes. * `describe` — Describe the structure of a database or entities within it. WARNING: This command is UNSTABLE and subject to breaking changes. * `dev` — Start development mode with auto-regenerate client module bindings, auto-rebuild, and auto-publish on file changes. * `sql` — Runs a SQL query on the database. WARNING: This command is UNSTABLE and subject to breaking changes. * `rename` — Rename a database * `generate` — Generate client files for a spacetime module. * `list` — Lists the databases attached to an identity. WARNING: This command is UNSTABLE and subject to breaking changes. * `login` — Manage your login to the SpacetimeDB CLI * `logout` — * `init` — Initializes a new spacetime project. * `build` — Builds a spacetime module. * `server` — Manage the connection to the SpacetimeDB server. WARNING: This command is UNSTABLE and subject to breaking changes. * `subscribe` — Subscribe to SQL queries on the database. WARNING: This command is UNSTABLE and subject to breaking changes. * `start` — Start a local SpacetimeDB instance * `version` — Manage installed spacetime versions ###### **Options:**[​](#options "Direct link to options") * `--root-dir ` — The root directory to store all spacetime files in. * `--config-path ` — The path to the cli.toml config file ## `spacetime publish`[​](#spacetime-publish "Direct link to spacetime-publish") Create and update a SpacetimeDB database **Usage:** `spacetime publish [OPTIONS] [name|identity]` Run `spacetime help publish` for more detailed information. ###### **Arguments:**[​](#arguments "Direct link to arguments") * `` — A valid domain or identity for this database. Database names must match the regex `/^[a-z0-9]+(-[a-z0-9]+)*$/`, i.e. only lowercase ASCII letters and numbers, separated by dashes. ###### **Options:**[​](#options-1 "Direct link to options-1") * `-c`, `--delete-data ` — When publishing to an existing database identity, first DESTROY all data associated with the module. With 'on-conflict': only when breaking schema changes occur. Possible values: `always`, `on-conflict`, `never` * `--build-options ` — Options to pass to the build command, for example --build-options='--lint-dir=' Default value: \`\` * `-p`, `--module-path ` — The system path (absolute or relative) to the module project. Defaults to spacetimedb/ subdirectory, then current directory. * `-b`, `--bin-path ` — The system path (absolute or relative) to the compiled wasm binary we should publish, instead of building the project. * `-j`, `--js-path ` — UNSTABLE: The system path (absolute or relative) to the javascript file we should publish, instead of building the project. * `--break-clients` — Allow breaking changes when publishing to an existing database identity. Equivalent to --yes=break-clients: skips the "this will BREAK existing clients" prompt, but will NOT force publish if it would cause deletion of any data in the database. See --yes and --delete-data for details. * `--anonymous` — Perform this action with an anonymous identity * `--parent ` — A valid domain or identity of an existing database that should be the parent of this database. If a parent is given, the new database inherits the team permissions from the parent. A parent can only be set when a database is created, not when it is updated. * `--organization ` — The name or identity of an existing organization this database should be created under. If an organization is given, the organization member's permissions apply to the new database. An organization can only be set when a database is created, not when it is updated. * `-s`, `--server ` — The nickname, domain name or URL of the server to host the database. * `-y`, `--yes ` — Skip confirmation prompts. With no value, defaults to 'all' (equivalent to --yes=all). To skip specific prompts, pass one or more of: all, remote, migrate, break-clients, skip-login, delete-data. Multiple values can be comma-separated (--yes=migrate,break-clients) or given via repeated flags (--yes=migrate --yes=break-clients). The value must be attached with '=' (so `--yes my-db` treats `my-db` as the database name). Possible values: * `all`: Equivalent to passing every other option. This is the default when `--yes` is given without a value * `remote`: Skip the "publish to a non-local server?" confirmation * `migrate`: Skip migration confirmations (e.g. major version upgrade) * `break-clients`: Skip the "this will BREAK existing clients" confirmation * `skip-login`: Don't prompt the user to log in; act non-interactively for auth * `delete-data`: Skip the destructive "this will DESTROY ... ALL corresponding data" confirmation * `--no-config` — Ignore spacetime.json configuration * `--env ` — Environment name for config file layering (e.g., dev, staging) * `--native-aot` — Use NativeAOT-LLVM compilation for C# modules (experimental, Windows only) ## `spacetime delete`[​](#spacetime-delete "Direct link to spacetime-delete") Deletes a SpacetimeDB database **Usage:** `spacetime delete [OPTIONS] [database]` Run `spacetime help delete` for more detailed information. ###### **Arguments:**[​](#arguments-1 "Direct link to arguments-1") * `` — The name or identity of the database to delete ###### **Options:**[​](#options-2 "Direct link to options-2") * `-s`, `--server ` — The nickname, host name or URL of the server hosting the database * `-y`, `--yes` — Run non-interactively wherever possible. This will answer "yes" to almost all prompts, but will sometimes answer "no" to preserve non-interactivity (e.g. when prompting whether to log in with spacetimedb.com). * `--no-config` — Ignore spacetime.json configuration ## `spacetime logs`[​](#spacetime-logs "Direct link to spacetime-logs") Prints logs from a SpacetimeDB database **Usage:** `spacetime logs [OPTIONS] [database]` Run `spacetime help logs` for more detailed information. ###### **Arguments:**[​](#arguments-2 "Direct link to arguments-2") * `` — The name or identity of the database to print logs from ###### **Options:**[​](#options-3 "Direct link to options-3") * `-s`, `--server ` — The nickname, host name or URL of the server hosting the database * `-n`, `--num-lines ` — The number of lines to print from the start of the log of this database. If no num lines is provided, all lines will be returned. * `-f`, `--follow` — A flag that causes logs to not stop when end of the log file is reached, but rather to wait for additional data to be appended to the input. * `--format ` — Output format for the logs Default value: `text` Possible values: `text`, `json` * `-l`, `--level ` — Filter logs by severity level. Only messages at the specified level or higher will be shown. Levels from least to most severe: trace, debug, info, warn, error, panic. Possible values: `trace`, `debug`, `info`, `warn`, `error`, `panic` * `--level-exact` — When combined with --level, show only logs at exactly the specified level instead of that level and above. * `-y`, `--yes` — Run non-interactively wherever possible. This will answer "yes" to almost all prompts, but will sometimes answer "no" to preserve non-interactivity (e.g. when prompting whether to log in with spacetimedb.com). * `--no-config` — Ignore spacetime.json configuration ## `spacetime call`[​](#spacetime-call "Direct link to spacetime-call") Invokes a function (reducer or procedure) in a database. WARNING: This command is UNSTABLE and subject to breaking changes. **Usage:** `spacetime call [OPTIONS] [call_parts]...` Run `spacetime help call` for more detailed information. ###### **Arguments:**[​](#arguments-3 "Direct link to arguments-3") * `` — Call arguments: \[DATABASE] \ \[ARGUMENTS...] ###### **Options:**[​](#options-4 "Direct link to options-4") * `-s`, `--server ` — The nickname, host name or URL of the server hosting the database * `--anonymous` — Perform this action with an anonymous identity * `-y`, `--yes` — Run non-interactively wherever possible. This will answer "yes" to almost all prompts, but will sometimes answer "no" to preserve non-interactivity (e.g. when prompting whether to log in with spacetimedb.com). * `--no-config` — Ignore spacetime.json configuration ## `spacetime describe`[​](#spacetime-describe "Direct link to spacetime-describe") Describe the structure of a database or entities within it. WARNING: This command is UNSTABLE and subject to breaking changes. **Usage:** `spacetime describe [OPTIONS] --json [describe_parts]...` Run `spacetime help describe` for more detailed information. ###### **Arguments:**[​](#arguments-4 "Direct link to arguments-4") * `` — Describe arguments: \[DATABASE] \[ENTITY\_TYPE ENTITY\_NAME] ###### **Options:**[​](#options-5 "Direct link to options-5") * `--json` — Output the schema in JSON format. Currently required; in the future, omitting this will give human-readable output. * `--anonymous` — Perform this action with an anonymous identity * `-s`, `--server ` — The nickname, host name or URL of the server hosting the database * `-y`, `--yes` — Run non-interactively wherever possible. This will answer "yes" to almost all prompts, but will sometimes answer "no" to preserve non-interactivity (e.g. when prompting whether to log in with spacetimedb.com). * `--no-config` — Ignore spacetime.json configuration ## `spacetime dev`[​](#spacetime-dev "Direct link to spacetime-dev") Start development mode with auto-regenerate client module bindings, auto-rebuild, and auto-publish on file changes. **Usage:** `spacetime dev [OPTIONS] [database]` ###### **Arguments:**[​](#arguments-5 "Direct link to arguments-5") * `` — The database name/identity to publish to (optional, will prompt if not provided) ###### **Options:**[​](#options-6 "Direct link to options-6") * `--project-path ` — The path to the project directory Default value: `.` * `--module-bindings-path ` — The path to the module bindings directory relative to the project directory, defaults to `/src/module_bindings` Default value: `src/module_bindings` * `--module-path ` — Path to the SpacetimeDB server module, relative to current directory. Defaults to `/spacetimedb`. * `--client-lang ` — The programming language for the generated client module bindings (e.g., typescript, csharp, rust, unrealcpp). If not specified, it will be detected from the project. Possible values: `csharp`, `typescript`, `rust`, `unrealcpp` * `-s`, `--server ` — The nickname, host name or URL of the server to publish to * `-y`, `--yes` — Run non-interactively wherever possible. This will answer "yes" to almost all prompts, but will sometimes answer "no" to preserve non-interactivity (e.g. when prompting whether to log in with spacetimedb.com). * `-c`, `--delete-data ` — When publishing to an existing database identity, first DESTROY all data associated with the module. With 'on-conflict': only when breaking schema changes occur. Possible values: `always`, `on-conflict`, `never` * `-t`, `--template