diff --git a/docs/deploying/maincloud.md b/docs/deploying/maincloud.md index ea14ebbd..f73aa2e4 100644 --- a/docs/deploying/maincloud.md +++ b/docs/deploying/maincloud.md @@ -12,6 +12,8 @@ Maincloud is a managed cloud service that provides developers an easy way to dep spacetime publish -s maincloud my-cool-module ``` +`maincloud` is the nickname for the hostname `maincloud.spacetimedb.com`, which is pre-configured in the SpacetimeDB CLI. See [`spacetime server`↴](/docs/cli-reference#spacetime-server) for more information. Use `wss://maincloud.spacetimedb.com` as URI to connect to maincloud from clients. + ## Connecting your Identity to the Web Dashboard By logging in your CLI via spacetimedb.com, you can view your published modules on the web dashboard. diff --git a/docs/how-to/incremental-migrations.md b/docs/how-to/incremental-migrations.md index 3f9106b1..4a91d3de 100644 --- a/docs/how-to/incremental-migrations.md +++ b/docs/how-to/incremental-migrations.md @@ -120,7 +120,7 @@ $ spacetime sql incr-migration-demo 'SELECT * FROM character' | "Gefjon" | 2 | (Fighter = ()) ``` -See [the SATS JSON reference](/docs/sats-json) for more on the encoding of arguments to `spacetime call`. +See [the SATS JSON reference](/docs/internals/sats-json) for more on the encoding of arguments to `spacetime call`. Now we want to add a new feature: each player should be able to align themselves with the forces of good or evil, so we can get some healthy competition going between our players. We'll start each character off with `Alliance::Neutral`, and then offer them a reducer `choose_alliance` to set it to either `Alliance::Good` or `Alliance::Evil`. Our first attempt will be to add a new column to the type `Character`: diff --git a/docs/http/index.md b/docs/http/authorization.md similarity index 100% rename from docs/http/index.md rename to docs/http/authorization.md diff --git a/docs/http/database.md b/docs/http/database.md index 0ac41070..89232e04 100644 --- a/docs/http/database.md +++ b/docs/http/database.md @@ -30,7 +30,7 @@ Accessible through the CLI as `spacetime publish`. | Name | Value | | --------------- | --------------------------------------------------------------------- | -| `Authorization` | A Spacetime token [as Bearer auth](/docs/http#authorization-headers). | +| `Authorization` | A Spacetime token [as Bearer auth](/docs/http/authorization#authorization-headers). | #### Data @@ -63,7 +63,7 @@ Accessible through the CLI as `spacetime publish`. | Name | Value | | --------------- | --------------------------------------------------------------------- | -| `Authorization` | A Spacetime token [as Bearer auth](/docs/http#authorization-headers). | +| `Authorization` | A Spacetime token [as Bearer auth](/docs/http/authorization#authorization-headers). | #### Data @@ -123,7 +123,7 @@ Accessible through the CLI as `spacetime delete `. | Name | Value | | --------------- | --------------------------------------------------------------------- | -| `Authorization` | A Spacetime token [as Bearer auth](/docs/http#authorization-headers). | +| `Authorization` | A Spacetime token [as Bearer auth](/docs/http/authorization#authorization-headers). | ## `GET /v1/database/:name_or_identity/names` @@ -147,7 +147,7 @@ Add a new name for this database. | Name | Value | | --------------- | --------------------------------------------------------------------- | -| `Authorization` | A Spacetime token [as Bearer auth](/docs/http#authorization-headers). | +| `Authorization` | A Spacetime token [as Bearer auth](/docs/http/authorization#authorization-headers). | #### Data @@ -180,7 +180,7 @@ Set the list of names for this database. | Name | Value | | --------------- | --------------------------------------------------------------------- | -| `Authorization` | A Spacetime token [as Bearer auth](/docs/http#authorization-headers). | +| `Authorization` | A Spacetime token [as Bearer auth](/docs/http/authorization#authorization-headers). | #### Data @@ -224,16 +224,16 @@ For more information about WebSocket headers, see [RFC 6455](https://datatracker | `Sec-WebSocket-Version` | `13` | | `Sec-WebSocket-Key` | A 16-byte value, generated randomly by the client, encoded as Base64. | -The SpacetimeDB binary WebSocket protocol, `v1.bsatn.spacetimedb`, encodes messages as well as reducer and row data using [BSATN](/docs/bsatn). +The SpacetimeDB binary WebSocket protocol, `v1.bsatn.spacetimedb`, encodes messages as well as reducer and row data using [BSATN](/docs/internals/bsatn). Its messages are defined [here](https://github.com/clockworklabs/SpacetimeDB/blob/master/crates/client-api-messages/src/websocket.rs). -The SpacetimeDB text WebSocket protocol, `v1.json.spacetimedb`, encodes messages according to the [SATS-JSON format](/docs/sats-json). +The SpacetimeDB text WebSocket protocol, `v1.json.spacetimedb`, encodes messages according to the [SATS-JSON format](/docs/internals/sats-json). #### Optional Headers | Name | Value | | --------------- | --------------------------------------------------------------------- | -| `Authorization` | A Spacetime token [as Bearer auth](/docs/http#authorization-headers). | +| `Authorization` | A Spacetime token [as Bearer auth](/docs/http/authorization#authorization-headers). | ## `POST /v1/database/:name_or_identity/call/:reducer` @@ -249,7 +249,7 @@ Invoke a reducer in a database. | Name | Value | | --------------- | --------------------------------------------------------------------- | -| `Authorization` | A Spacetime token [as Bearer auth](/docs/http#authorization-headers). | +| `Authorization` | A Spacetime token [as Bearer auth](/docs/http/authorization#authorization-headers). | #### Data @@ -409,7 +409,7 @@ Accessible through the CLI as `spacetime logs `. | Name | Value | | --------------- | --------------------------------------------------------------------- | -| `Authorization` | A Spacetime token [as Bearer auth](/docs/http#authorization-headers). | +| `Authorization` | A Spacetime token [as Bearer auth](/docs/http/authorization#authorization-headers). | #### Returns @@ -425,7 +425,7 @@ Accessible through the CLI as `spacetime sql `. | Name | Value | | --------------- | --------------------------------------------------------------------- | -| `Authorization` | A Spacetime token [as Bearer auth](/docs/http#authorization-headers). | +| `Authorization` | A Spacetime token [as Bearer auth](/docs/http/authorization#authorization-headers). | #### Data @@ -442,6 +442,6 @@ Returns a JSON array of statement results, each of which takes the form: } ``` -The `schema` will be a [JSON-encoded `ProductType`](/docs/sats-json) describing the type of the returned rows. +The `schema` will be a [JSON-encoded `ProductType`](/docs/internals/sats-json) describing the type of the returned rows. -The `rows` will be an array of [JSON-encoded `ProductValue`s](/docs/sats-json), each of which conforms to the `schema`. +The `rows` will be an array of [JSON-encoded `ProductValue`s](/docs/internals/sats-json), each of which conforms to the `schema`. diff --git a/docs/http/identity.md b/docs/http/identity.md index f3b68b28..222ac1e9 100644 --- a/docs/http/identity.md +++ b/docs/http/identity.md @@ -35,7 +35,7 @@ Generate a short-lived access token which can be used in untrusted contexts, e.g | Name | Value | | --------------- | --------------------------------------------------------------- | -| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http). | +| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http/authorization). | #### Returns @@ -77,7 +77,7 @@ Associate an email with a Spacetime identity. | Name | Value | | --------------- | --------------------------------------------------------------- | -| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http). | +| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http/authorization). | ## `GET /v1/identity/:identity/databases` @@ -115,7 +115,7 @@ Verify the validity of an identity/token pair. | Name | Value | | --------------- | --------------------------------------------------------------- | -| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http). | +| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http/authorization). | #### Returns diff --git a/docs/index.md b/docs/index.md index 6e4a0b65..16e2455c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -75,7 +75,7 @@ A database exports [tables](#table), which store data, and [reducers](#reducer), A database's schema and business logic is specified by a piece of software called a **module**. Modules can be written in C# or Rust. -(Technically, a SpacetimeDB module is a [WebAssembly module](https://developer.mozilla.org/en-US/docs/WebAssembly) that imports a specific low-level [WebAssembly ABI](/docs/webassembly-abi) and exports a small number of special functions. However, the SpacetimeDB [server-side libraries](#module-libraries) hide these low-level details. As a developer, writing a module is mostly like writing any other C# or Rust application, except for the fact that a [special CLI tool](/install) is used to deploy the application.) +(Technically, a SpacetimeDB module is a [WebAssembly module](https://developer.mozilla.org/en-US/docs/WebAssembly) that imports a specific low-level [WebAssembly ABI](/docs/internals/webassembly-abi) and exports a small number of special functions. However, the SpacetimeDB [server-side libraries](#module-libraries) hide these low-level details. As a developer, writing a module is mostly like writing any other C# or Rust application, except for the fact that a [special CLI tool](/install) is used to deploy the application.) ### Table A SpacetimeDB **table** is a SQL database table. Tables are declared in a module's native language. For instance, in C#, a table is declared like so: diff --git a/docs/bsatn.md b/docs/internals/bsatn.md similarity index 98% rename from docs/bsatn.md rename to docs/internals/bsatn.md index 2e464b51..46c5f470 100644 --- a/docs/bsatn.md +++ b/docs/internals/bsatn.md @@ -128,6 +128,6 @@ Where 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) +See [the SATN JSON Format](/docs/internals/sats-json) for more details of the conversion to meta values. Note that these meta values are converted to BSATN and _not JSON_. diff --git a/docs/sats-json.md b/docs/internals/sats-json.md similarity index 100% rename from docs/sats-json.md rename to docs/internals/sats-json.md diff --git a/docs/webassembly-abi/index.md b/docs/internals/webassembly-abi.md similarity index 100% rename from docs/webassembly-abi/index.md rename to docs/internals/webassembly-abi.md diff --git a/docs/modules/c-sharp/index.md b/docs/modules/c-sharp/index.md index fc2acc95..5f72c244 100644 --- a/docs/modules/c-sharp/index.md +++ b/docs/modules/c-sharp/index.md @@ -201,7 +201,7 @@ You can also generate code for clients of your module using the `spacetime gener # How it works -Under the hood, SpacetimeDB modules are WebAssembly modules that import a [specific WebAssembly ABI](https://spacetimedb.com/docs/webassembly-abi) and export a small number of special functions. This is automatically configured when you add the `SpacetimeDB.Runtime` package as a dependency of your application. +Under the hood, SpacetimeDB modules are WebAssembly modules that import a [specific WebAssembly ABI](https://spacetimedb.com/docs/internals/webassembly-abi) and export a small number of special functions. This is automatically configured when you add the `SpacetimeDB.Runtime` package as a dependency of your application. The SpacetimeDB host is an application that hosts SpacetimeDB databases. [Its source code is available](https://github.com/clockworklabs/SpacetimeDB) under [the Business Source License with an Additional Use Grant](https://github.com/clockworklabs/SpacetimeDB/blob/master/LICENSE.txt). You can run your own host, or you can upload your module to the public SpacetimeDB network. The network will create a database for you and install your module in it to serve client requests. diff --git a/docs/modules/c-sharp/quickstart.md b/docs/modules/c-sharp/quickstart.md index 86bcf16f..a41dccae 100644 --- a/docs/modules/c-sharp/quickstart.md +++ b/docs/modules/c-sharp/quickstart.md @@ -298,7 +298,7 @@ info: Hello, World! SpacetimeDB supports a subset of the SQL syntax so that you can easily query the data of your database. We can run a query using the `sql` command. ```bash -spacetime sql quickstart-chat "SELECT * FROM Message" +spacetime sql quickstart-chat "SELECT * FROM message" ``` ```bash diff --git a/docs/modules/index.md b/docs/modules/index.md index 78d60d9c..08d72a92 100644 --- a/docs/modules/index.md +++ b/docs/modules/index.md @@ -15,7 +15,7 @@ Rust is the only fully supported language for server modules. Rust is a great op ### C# -We have C# support available in experimental status. C# can be a good choice for developers who are already using Unity or .net for their client applications. +We have C# support available. C# can be a good choice for developers who are already using Unity or .net for their client applications. - [C# Module Reference](/docs/modules/c-sharp) - [C# Module Quickstart Guide](/docs/modules/c-sharp/quickstart) diff --git a/docs/modules/rust/quickstart.md b/docs/modules/rust/quickstart.md index 0670bb89..b9158b69 100644 --- a/docs/modules/rust/quickstart.md +++ b/docs/modules/rust/quickstart.md @@ -224,11 +224,15 @@ pub fn identity_disconnected(ctx: &ReducerContext) { } ``` +## Start the Server + +If you haven't already started the SpacetimeDB server, run the `spacetime start` command in a _separate_ terminal and leave it running while you continue following along. + ## Publish the module And that's all of our module code! We'll run `spacetime publish` to compile our module and publish it on SpacetimeDB. `spacetime publish` takes an optional name which will map to the database's unique `Identity`. Clients can connect either by name or by `Identity`, but names are much more user-friendly. If you'd like, come up with a unique name that contains only URL-safe characters (letters, numbers, hyphens and underscores), and fill it in where we've written `quickstart-chat`. -From the `quickstart-chat` directory, run: +From the `quickstart-chat` directory, run in another tab: ```bash spacetime publish --project-path server quickstart-chat @@ -239,7 +243,7 @@ spacetime publish --project-path server quickstart-chat You can use the CLI (command line interface) to run reducers. The arguments to the reducer are passed in JSON format. ```bash -spacetime call quickstart-chat send_message 'Hello, World!' +spacetime call quickstart-chat send_message "Hello, World!" ``` Once we've called our `send_message` reducer, we can check to make sure it ran by running the `logs` command. diff --git a/docs/nav.js b/docs/nav.js index e7d0b944..9f32bb1b 100644 --- a/docs/nav.js +++ b/docs/nav.js @@ -18,6 +18,8 @@ const nav = { page('2 - Connecting to SpacetimeDB', 'unity/part-2', 'unity/part-2.md'), page('3 - Gameplay', 'unity/part-3', 'unity/part-3.md'), page('4 - Moving and Colliding', 'unity/part-4', 'unity/part-4.md'), + section('SQL'), + page('SQL Reference', 'sql', 'sql/index.md'), section('CLI Reference'), page('CLI Reference', 'cli-reference', 'cli-reference.md'), page('SpacetimeDB Standalone Configuration', 'cli-reference/standalone-config', 'cli-reference/standalone-config.md'), @@ -35,20 +37,18 @@ const nav = { page('Rust Reference', 'sdks/rust', 'sdks/rust/index.md'), page('TypeScript Quickstart', 'sdks/typescript/quickstart', 'sdks/typescript/quickstart.md'), page('TypeScript Reference', 'sdks/typescript', 'sdks/typescript/index.md'), - section('SQL'), - page('SQL Reference', 'sql', 'sql/index.md'), section('Subscriptions'), page('Subscription Reference', 'subscriptions', 'subscriptions/index.md'), section('How To'), page('Incremental Migrations', 'how-to/incremental-migrations', 'how-to/incremental-migrations.md'), section('HTTP API'), - page('HTTP', 'http', 'http/index.md'), + page('Authorization', 'http/authorization', 'http/authorization.md'), page('`/identity`', 'http/identity', 'http/identity.md'), page('`/database`', 'http/database', 'http/database.md'), section('Internals'), - page('Module ABI Reference', 'webassembly-abi', 'webassembly-abi/index.md'), - page('SATS-JSON Data Format', 'sats-json', 'sats-json.md'), - page('BSATN Data Format', 'bsatn', 'bsatn.md'), + page('Module ABI Reference', 'webassembly-abi', 'internals/webassembly-abi.md'), + page('SATS-JSON Data Format', 'sats-json', 'internals/sats-json.md'), + page('BSATN Data Format', 'bsatn', 'internals/bsatn.md'), section('Appendix'), page('Appendix', 'appendix', 'appendix.md'), ], diff --git a/docs/sdks/c-sharp/index.md b/docs/sdks/c-sharp/index.md index 16fd2068..323c9dd6 100644 --- a/docs/sdks/c-sharp/index.md +++ b/docs/sdks/c-sharp/index.md @@ -68,6 +68,8 @@ class DbConnection Construct a `DbConnection` by calling `DbConnection.Builder()`, chaining configuration methods, and finally calling `.Build()`. At a minimum, you must specify `WithUri` to provide the URI of the SpacetimeDB instance, and `WithModuleName` to specify the module's name or identity. +Please be aware that you must [advance the connection](#advance-the-connection-and-process-messages) to process messages. If you don't do that, no callbacks will ever be invoked! + | Name | Description | |---------------------------------------------------------|--------------------------------------------------------------------------------------------| | [WithUri method](#method-withuri) | Set the URI of the SpacetimeDB instance hosting the remote database. | @@ -159,7 +161,9 @@ After configuring the connection and registering callbacks, attempt to open the ## Advance the connection and process messages -In the interest of supporting a wide variety of client applications with different execution strategies, the SpacetimeDB SDK allows you to choose when the `DbConnection` spends compute time and processes messages. If you do not arrange for the connection to advance by calling one of these methods, the `DbConnection` will never advance, and no callbacks will ever be invoked. +In the interest of supporting a wide variety of client applications with different execution strategies, the SpacetimeDB SDK allows you to choose when the `DbConnection` spends compute time and processes messages. + +> NOTE: If you do not arrange for the connection to advance by calling one of these methods, the `DbConnection` will never advance, and no callbacks will ever be invoked. | Name | Description | |---------------------------------------------|-------------------------------------------------------| diff --git a/docs/sdks/rust/index.md b/docs/sdks/rust/index.md index a6dd23bb..cb4f0025 100644 --- a/docs/sdks/rust/index.md +++ b/docs/sdks/rust/index.md @@ -67,6 +67,8 @@ impl DbConnection { Construct a `DbConnection` by calling `DbConnection::builder()` and chaining configuration methods, then calling `.build()`. You must at least specify `with_uri`, to supply the URI of the SpacetimeDB to which you published your module, and `with_module_name`, to supply the human-readable SpacetimeDB domain name or the raw `Identity` which identifies the module. +Please be aware that you must [advance the connection](#advance-the-connection-and-process-messages) to process messages. If you don't do that, no callbacks will ever be invoked! + | Name | Description | |-----------------------------------------------------------|--------------------------------------------------------------------------------------| | [`with_uri` method](#method-with_uri) | Set the URI of the SpacetimeDB instance which hosts the remote database. | @@ -160,7 +162,9 @@ After configuring the connection and registering callbacks, attempt to open the ### Advance the connection and process messages -In the interest of supporting a wide variety of client applications with different execution strategies, the SpacetimeDB SDK allows you to choose when the `DbConnection` spends compute time and processes messages. If you do not arrange for the connection to advance by calling one of these methods, the `DbConnection` will never advance, and no callbacks will ever be invoked. +In the interest of supporting a wide variety of client applications with different execution strategies, the SpacetimeDB SDK allows you to choose when the `DbConnection` spends compute time and processes messages. + +> NOTE: If you do not arrange for the connection to advance by calling one of these methods, the `DbConnection` will never advance, and no callbacks will ever be invoked. | Name | Description | |-----------------------------------------------|-------------------------------------------------------| diff --git a/docs/sql/index.md b/docs/sql/index.md index 807af409..aa4ddcd2 100644 --- a/docs/sql/index.md +++ b/docs/sql/index.md @@ -469,6 +469,9 @@ Both types of identifiers are case sensitive. Use quoted identifiers to avoid conflict with reserved SQL keywords, or if your table or column contains non-alphanumeric characters. +Because SpacetimeDB uses a postgres compatible parser, identifiers which are +reserved in postgres are automatically reserved in Spacetime SQL. See [SQL Key Words in the PostgreSQL documentation](https://www.postgresql.org/docs/current/sql-keywords-appendix.html). + ### Example ```sql @@ -487,6 +490,8 @@ consider the following best practices to ensure optimal performance: - **Add Primary Key and/or Unique Constraints:** Constrain columns whose values are guaranteed to be distinct as either unique or primary keys. The query planner can further optimize joins if it knows the join values to be unique. + - **Differences between primary keys and unique constraints:**
+ In SpacetimeDB, the only difference between unique and primary_key is that the [client SDKs](/docs/sdks) assign special semantics to primary_key columns. Specifically, the on_update callback fires for a row when a single transaction deletes an old row with a certain primary key, and then inserts a new row with that same primary key. Tables without a primary key column will never observe an on_update event. (Also, a table can only have at most one primary key column, but may have as many unique columns as it wants.) Otherwise, the two constraints are equivalent. - **Index Filtered Columns:** Index columns frequently used in a `WHERE` clause. diff --git a/nav.ts b/nav.ts index fb968928..46be8b22 100644 --- a/nav.ts +++ b/nav.ts @@ -44,6 +44,9 @@ const nav: Nav = { page('3 - Gameplay', 'unity/part-3', 'unity/part-3.md'), page('4 - Moving and Colliding', 'unity/part-4', 'unity/part-4.md'), + section('SQL'), + page('SQL Reference', 'sql', 'sql/index.md'), + section('CLI Reference'), page('CLI Reference', 'cli-reference', 'cli-reference.md'), page( @@ -84,9 +87,6 @@ const nav: Nav = { ), page('TypeScript Reference', 'sdks/typescript', 'sdks/typescript/index.md'), - section('SQL'), - page('SQL Reference', 'sql', 'sql/index.md'), - section('Subscriptions'), page('Subscription Reference', 'subscriptions', 'subscriptions/index.md'), @@ -94,14 +94,14 @@ const nav: Nav = { page('Incremental Migrations', 'how-to/incremental-migrations', 'how-to/incremental-migrations.md'), section('HTTP API'), - page('HTTP', 'http', 'http/index.md'), + page('Authorization', 'http/authorization', 'http/authorization.md'), page('`/identity`', 'http/identity', 'http/identity.md'), page('`/database`', 'http/database', 'http/database.md'), section('Internals'), - page('Module ABI Reference', 'webassembly-abi', 'webassembly-abi/index.md'), - page('SATS-JSON Data Format', 'sats-json', 'sats-json.md'), - page('BSATN Data Format', 'bsatn', 'bsatn.md'), + page('Module ABI Reference', 'webassembly-abi', 'internals/webassembly-abi.md'), + page('SATS-JSON Data Format', 'sats-json', 'internals/sats-json.md'), + page('BSATN Data Format', 'bsatn', 'internals/bsatn.md'), section('Appendix'), page('Appendix', 'appendix', 'appendix.md'),