Update release with 1.0 changes (#202)

* Changed subscript to SubscribeToAllTables (#155) Missed updating the HandleConnect from `Subscribe("SELECT * FROM *"` to `SubscribeToAllTables()` in the updated code block on page 3. * Updated the TypeScript quickstart guide to use the new 1.0 API (#141) * Updated the quickstart guide to use the new 1.0 API * Completed quickstart rewrite * Update docs/sdks/typescript/quickstart.md Co-authored-by: Phoebe Goldman <[email protected]> * Update docs/sdks/typescript/quickstart.md Co-authored-by: Phoebe Goldman <[email protected]> * Update docs/sdks/typescript/quickstart.md Co-authored-by: Phoebe Goldman <[email protected]> * Update docs/sdks/typescript/quickstart.md Co-authored-by: Phoebe Goldman <[email protected]> * Update docs/sdks/typescript/quickstart.md Co-authored-by: Phoebe Goldman <[email protected]> * Clarification * Update docs/sdks/typescript/quickstart.md Co-authored-by: Phoebe Goldman <[email protected]> * Update docs/sdks/typescript/quickstart.md Co-authored-by: Phoebe Goldman <[email protected]> * Wrong type of quotes * Update docs/sdks/typescript/quickstart.md Co-authored-by: Phoebe Goldman <[email protected]> * Update docs/sdks/typescript/quickstart.md Co-authored-by: Phoebe Goldman <[email protected]> * Apply suggestions from code review Co-authored-by: Phoebe Goldman <[email protected]> Co-authored-by: rekhoff <[email protected]> * Address review comments --------- Co-authored-by: Phoebe Goldman <[email protected]> Co-authored-by: rekhoff <[email protected]> * Update Rust client SDK docs for SpacetimeDB#2118 (#130) * docs(70): The 1.0 SQL spec Closes #70. * Small TS SDK Quickstart Fixes (#157) Updated quickstart url * Style guide: add formatting advice for GUI elements and menu paths (#129) * Style guide: add formatting advice for menu items * Generalize guidance to all GUI elements, not just menu paths * Remove WebSocket api docs and all references to them (#165) Closes #164. --------- Co-authored-by: Phoebe Goldman <[email protected]> * CLI docs (#168) * [bfops/cli-docs]: CLI docs * [bfops/cli-docs]: fix? * [bfops/cli-docs]: manual backticks * [bfops/cli-docs]: manual bold * [bfops/cli-docs]: manual bold * [bfops/cli-docs]: add README for maintaining CLI reference docs * [bfops/cli-docs]: maybe fix code? * [bfops/cli-docs]: tweak <code> * [bfops/cli-docs]: tweak code * [bfops/cli-docs]: update --------- Co-authored-by: Zeke Foppa <[email protected]> * Add link to the `cli` (#171) * Rename satn.md -> sats-json.md (#158) * Fix auto_inc attribute name (#175) * Document LIMIT and COUNT (#178) Closes #177. * Add best practices for Spacetime SQL (#180) Closes #179. * API for mutable subscriptions (#166) Closes #78. Includes rust and csharp examples. * Remove references to SpacetimeDB 0.6 Closes #118. * Remove reference to set energy-balance in http api Closes #119. * Remove references to testnet Closes #183. * Remove 0.12 migration guide * Update to C# Quickstart-Chat Server Module and Client SDK tutorial documents (#170) * Initial code pass on updating server to 1.0.0 * Updated to work with current 1.0.0-rc4, master branches of SpacetimeDB and the CSharpSDK * Minor edit for clarity * No longer optional, ReducerContext is always the first argument Co-authored-by: Phoebe Goldman <[email protected]> * Improved description of OnInsert and OnDelete callbacks Co-authored-by: Phoebe Goldman <[email protected]> * Fixed capitalization. Co-authored-by: Phoebe Goldman <[email protected]> * Fixed capitalization. Co-authored-by: Phoebe Goldman <[email protected]> * SDK language corrected and clarified. Co-authored-by: Phoebe Goldman <[email protected]> * Added that the example is for the C# client and does not include server examples. Co-authored-by: Phoebe Goldman <[email protected]> * Added comma for clarity Co-authored-by: Phoebe Goldman <[email protected]> * Added comma for clarity Co-authored-by: Phoebe Goldman <[email protected]> * Applied requested changes to improve clarity * Revised the SDK Client Quickstart to be more-in-line with the Rust Client Quickstart flow * Added comments to code * Replaced <module-name> with quickstart-chat --------- Co-authored-by: Phoebe Goldman <[email protected]> * Move Rust Module SDK reference to docs.rs (#114) Move rust reference to rustdoc * Document reducer semantics wrt. transactionality (#185) document reducer semantics wrt. transactionality * Document behaviour of SEQUENCES (#174) * Document behaviour of SEQUENCES * Update docs/appendix.md Co-authored-by: Tyler Cloutier <[email protected]> * Apply suggestions from code review Co-authored-by: Phoebe Goldman <[email protected]> --------- Co-authored-by: Tyler Cloutier <[email protected]> Co-authored-by: Phoebe Goldman <[email protected]> * Update Rust client SDK quickstart for 1.0 API (#162) * Begin revising rust client quickstart: update the code * Revise Rust client SDK quickstart A whole bunch of stuff has changed since this document was last updated. Notably, I've chosen to re-order a bunch of sections, since the previous structure of the document doesn't make much sense after the 0.12 API rework. * Fix credentials import issue There are still warnings here but it builds now * Fix warnings after pasting all this code into a fresh project --------- Co-authored-by: John Detter <[email protected]> * Add docs for standalone config.toml (#190) * Add docs for standalone config.toml * Update docs/cli-reference/standalone-config.md Co-authored-by: Phoebe Goldman <[email protected]> * pre formatting --------- Co-authored-by: Phoebe Goldman <[email protected]> * Update docs for http api (#188) * Update docs for http api * Apply suggestions from code review Co-authored-by: Phoebe Goldman <[email protected]> * Remove energy page --------- Co-authored-by: Phoebe Goldman <[email protected]> * Update Rust SDK ref, and also a few small fixes (#172) * *Must* accept `ReducerContext`, not *may* * Small fixes to Rust docs for database Identity and rename Address * Update Rust SDK reference for various 1.0 API changes * Fix broken links * TOC and TODOs * Rename `Address` to `ConnectionId` in index, fix some links * Minor fixes I found while working through converting this to typescript * Link to SQL ref * Additional fixups found while rewriting TS ref * Remove references to BitCraftMini We no longer use this as an example. Also, I'm pretty sure we stopped using that name ages ago. * No UB from mixing `subscribe` and `subscribe_to_all_tables` Co-authored-by: joshua-spacetime <[email protected]> * Update TypeScript SDK reference (#181) * Begin updating TypeScript SDK ref to match the new rust one * Link to SQL ref from `subscribe` method * Fill in the rest of the TypeScript SDK ref * Fix copy-paste error: `subscribeToAllTables` should be camelCase Co-authored-by: joshua-spacetime <[email protected]> * Copy change from Rust SDK docs: no UB in `subscribeToAllTables` Co-authored-by: joshua-spacetime <[email protected]> * Fix casing of `withModuleName` Co-authored-by: Tyler Cloutier <[email protected]> * Address Tyler's review --------- Co-authored-by: joshua-spacetime <[email protected]> Co-authored-by: Tyler Cloutier <[email protected]> --------- Co-authored-by: joshua-spacetime <[email protected]> Co-authored-by: Tyler Cloutier <[email protected]> * How-to: Incremental Migrations (#127) * How-to: Incremental Migrations This commit adds a how-to guide for defining "incremental migrations," a strategy for updating the schema of a database while maintaining compatibility with outdated clients and without requiring a manual migration. The code is not on GitHub yet, as I'd like review on my choice of example before pushing the repository. As such, the links to the code at the bottom of the new document are broken. * Updates following review * Updates to blackhol.io tutorials (#194) Updates to blackholio tutorials Page 3 - Fix duplicate code in Rust "disconnect reducer" instructions. Page 4 - Update use of `CallerIdentity` to `Sender` in C# instructions. * Updated with corrected table names to lower case, for compatibility w… (#195) Updated with corrected table names to lower case, for compatibility with other quickstart-chat languages. Updated with additional changes in clockworklabs/com.clockworklabs.spacetimedbsdk#258 * Small doc fixes potpourri (#198) * Remove hedging about table access from module quickstarts We'll announce RLS when we announce it. For now, what we have is what we have. * Remove hedging about supported module languages This kind of thing belongs in a roadmap, not anywhere else in our docs. * Fix :fingers_crossed: formatting of link to scheduled reducers * Fix link * List module langs in alphabetical order Which also happens to be decreasing order of support and battle-tested-ness * Re-order various and pages in sidebar - Internals get their own section, and move down. - Appendix gets its own section, instead of joining "Subscriptions." - SQL and Subscriptions move up. * Remove outdated guidance about tokens We don't have "SpacetimeDB tokens" anymore, we just have regular OIDC JWTs. We don't need to offer any special guidance about JWT hygiene. * Fixes the typescript quickstart for the new subscription API (#161) * Updated quickstart url * DBConnection -> DbConnection for TypeScript SDK * Updated for the subscription update * Multiplayer bug fix in tutorial (#169) * Multiplayer bug fix in tutorial * Update part-4.md Small fix * removed reference to test input This test input is not used during the tutorial and causes unused variable warnings * Update part-4.md * Add instructions for deploying to maincloud (#167) * [bfops/deploying]: add instructions for deploying mainnet * [bfops/deploying]: nav.ts * [bfops/deploying]: nav.ts * [bfops/deploying]: fix link? * Update docs/deploying/maincloud.md Co-authored-by: John Detter <[email protected]> * Update docs/deploying/maincloud.md Co-authored-by: John Detter <[email protected]> * [bfops/deploying]: review * Update docs/deploying/maincloud.md Co-authored-by: Tyler Cloutier <[email protected]> * Apply suggestions from code review Co-authored-by: Tyler Cloutier <[email protected]> * Add `/profile` as a known link --------- Co-authored-by: Zeke Foppa <[email protected]> Co-authored-by: joshua-spacetime <[email protected]> Co-authored-by: John Detter <[email protected]> Co-authored-by: Tyler Cloutier <[email protected]> Co-authored-by: Phoebe Goldman <[email protected]> * C# Module Library docs (#193) * Most of the way to C# Module SDK docs * Copy in more docs * Mostly done * Remove dead docs * Apply suggestions from code review Thanks Mazdak, also going to apply some of these to the Rust modules. Co-authored-by: Mazdak Farrokhzad <[email protected]> Co-authored-by: joshua-spacetime <[email protected]> * Address review comments --------- Co-authored-by: Mazdak Farrokhzad <[email protected]> Co-authored-by: joshua-spacetime <[email protected]> * C# sdk reference (#191) Closes #192. * Describe how a JWT's sub/iss are translated into an Identity (#204) * Rekhoff/blackholio fixes (#205) * Updates to blackholio tutorials Page 3 - Fix duplicate code in Rust "disconnect reducer" instructions. Page 4 - Update use of `CallerIdentity` to `Sender` in C# instructions. * Fixes from running through Blackholio tutorial in Rust and C# on 1.0.0 * Minor formatting updates * Minor formatting update * Another minor format change * Whitespace fix. Co-authored-by: John Detter <[email protected]> * Whitespace fix. Co-authored-by: John Detter <[email protected]> * Whitespace fix. Co-authored-by: John Detter <[email protected]> --------- Co-authored-by: John Detter <[email protected]> --------- Co-authored-by: rekhoff <[email protected]> Co-authored-by: Tyler Cloutier <[email protected]> Co-authored-by: joshua-spacetime <[email protected]> Co-authored-by: Zeke Foppa <[email protected]> Co-authored-by: Zeke Foppa <[email protected]> Co-authored-by: Mario Montoya <[email protected]> Co-authored-by: Noa <[email protected]> Co-authored-by: james gilles <[email protected]> Co-authored-by: Mazdak Farrokhzad <[email protected]> Co-authored-by: John Detter <[email protected]>
clockworklabs · Mar 4, 2025 · 80a7094 · 80a7094
1 parent 4a97611
commit 80a7094
Show file tree

Hide file tree

Showing 36 changed files with 6,449 additions and 4,297 deletions.
diff --git a/README.md b/README.md
@@ -32,6 +32,16 @@ git push -u origin a-branch-name-that-describes-my-change
 
 > NOTE! If you make a change to `nav.ts` you will have to run `npm run build` to generate a new `docs/nav.js` file.
 
+#### CLI Reference Section
+1. Make sure that https://github.com/clockworklabs/SpacetimeDB/pull/2276 is included in your `spacetimedb-cli` binary
+1. Run `cargo run --features markdown-docs -p spacetimedb-cli > cli-reference.md`
+
+We currently don't properly render markdown backticks and bolding that are inside of headers, so do these two manual replacements to make them look okay (these have only been tested on Linux):
+```bash
+sed -i'' -E 's!^(##) `(.*)`$!\1 \2!' docs/cli-reference.md
+sed -i'' -E 's!^(######) \*\*(.*)\*\*$!\1 <b>\2</b>!' docs/cli-reference.md
+```
+
 ### Checking Links
 
 We have a CI job which validates internal links. You can run it locally with `npm run check-links`. This will print any internal links (i.e. links to other docs pages) whose targets do not exist, including fragment links (i.e. `#`-ey links to anchors).

diff --git a/STYLE.md b/STYLE.md
@@ -73,6 +73,14 @@ Don't make promises, even weak ones, about what we plan to do in the future, wit
 
 If your document needs to describe a feature that isn't implemented yet, either rewrite to not depend on that feature, or just say that it's a "current limitation" without elaborating further. Include a workaround if there is one.
 
+### Menu items and paths
+
+When describing GUI elements and menu items, like the **Unity Registry** tab, use bolded text to draw attention to any phrases that will appear in the actual UI. Readers will see this bolded text in the documentation and look for it on their screen. Where applicable, include a short description of the type or category of element, like "tab" above, or the **File** menu. This category should not be bolded, since it is not a word the reader can expect to find on their screen.
+
+When describing a chain of accesses through menus and submenus, use the **->** thin arrow (that's `->`, a hyphen followed by a greater-than sign) as a separator, like **File -> Quit** or **Window -> Package Manager**. List the top-level menu first, and proceed left-to-right until you reach the option you want the user to interact with. Include all nested submenus, like **Foo -> Bar -> Baz -> Quux**. Bold the whole sequence, including the arrows. 
+
+It's generally not necessary or desirable to tell users where to look for the top-level menu. You may be tempted to write something like, "Open the **File** menu in the upper left, and navigate **File -> Export as -> Export as PDF**." Do not include "in the upper left" unless you are absolutely confident that the menu will be located there on any combination of OS, version, desktop environment, window manager, theming configuration &c. Even within a single system, UI designers are known to move graphical elements around during updates, making statements like "upper left" obsolete and stale. We can generally trust our readers to be familiar with their own systems and the software they use, and none of our documents involve introducing readers to new GUI software. (E.g. the Unity tutorial is targeted at introducing SpacetimeDB to people who already know Unity.) "Open the **File** menu and navigate **File -> Export as -> Export as PDF**" is sufficient.
+
 ## Key vocabulary
 
 There are a small number of key terms that we need to use consistently throughout the documentation.
@@ -367,7 +375,7 @@ Start the conclusion with a sentence or paragraph that reminds the reader what t
 
 If this tutorial is part of a series, link to the next entry:
 
-> You can use any of SpacetimDB's supported client languages to do this. Take a look at the quickstart guide for your client language of choice: [Rust](/docs/sdks/rust/quickstart), [C#](/docs/sdks/c-sharp/quickstart), or [TypeScript](/docs/sdks/typescript/quickstart). If you are planning to use SpacetimeDB with the Unity game engine, you can skip right to the [Unity Comprehensive Tutorial](/docs/unity/part-1) or check out our example game, [BitcraftMini](/docs/unity/part-3).
+> You can use any of SpacetimDB's supported client languages to do this. Take a look at the quickstart guide for your client language of choice: [Rust](/docs/sdks/rust/quickstart), [C#](/docs/sdks/c-sharp/quickstart), or [TypeScript](/docs/sdks/typescript/quickstart). If you are planning to use SpacetimeDB with the Unity game engine, you can skip right to the [Unity Comprehensive Tutorial](/docs/unity/part-1).
 
 If this tutorial is about a specific component, link to its reference page:
 
@@ -391,7 +399,7 @@ If this tutorial is the end of a series, or ends with a reasonably complete app,
 If the tutorial involved writing code, add a link to the complete code. This should be somewhere on GitHub, either as its own repo, or as an example project within an existing repo. Ensure the linked folder has a README.md file which includes:
 
 - The name of the tutorial project.
-- How to run or interact with the tutorial project, whatever that means (e.g. publish to testnet and then `spacetime call`).
+- How to run or interact with the tutorial project, whatever that means (e.g. publish to maincloud and then `spacetime call`).
 - Links to external dependencies (e.g. for client projects, the module which it runs against).
 - A back-link to the tutorial that builds this project.
 

diff --git a/docs/appendix.md b/docs/appendix.md
@@ -0,0 +1,61 @@
+# Appendix
+
+## SEQUENCE
+
+For each table containing an `#[auto_inc]` column, SpacetimeDB creates a sequence number generator behind the scenes, which functions similarly to `postgres`'s `SEQUENCE`.
+
+### How It Works
+
+* Sequences in SpacetimeDB use Rust’s `i128` integer type.
+* The field type marked with `#[auto_inc]`   is cast to `i128` and increments by `1` for each new row.
+* Sequences are pre-allocated in chunks of `4096` to speed up number generation, and then are only persisted to disk when the pre-allocated chunk is exhausted.
+
+> **⚠ Warning:** Sequence number generation is not transactional.
+
+* Numbers are incremented even if a transaction is later rolled back.
+* Unused numbers are not reclaimed, meaning sequences may have *gaps*.
+* If the server restarts or a transaction rolls back, the sequence continues from the next pre-allocated chunk + `1`:
+
+**Example:**
+
+```rust
+#[spacetimedb::table(name = users, public)]
+struct Users {
+    #[auto_inc]
+    user_id: u64,
+    name: String,
+}
+
+#[spacetimedb::reducer]
+pub fn insert_user(ctx: &ReducerContext, count: u8) {
+    for i in 0..count {
+        let name = format!("User {}", i);
+        ctx.db.users().insert(Users { user_id: 0, name });
+    }
+    // Query the table to see the effect of the `[auto_inc]` attribute:
+    for user in ctx.db.users().iter() {
+        log::info!("User: {:?}", user);
+    }
+}
+```
+
+Then:
+
+```bash
+❯ cargo run --bin spacetimedb-cli call sample insert_user 3
+
+❯ spacetimedb-cli logs sample
+...
+.. User: Users { user_id: 1, name: "User 0" }
+.. User: Users { user_id: 2, name: "User 1" }
+.. User: Users { user_id: 3, name: "User 2" }
+
+# Database restart, then
+
+❯ cargo run --bin spacetimedb-cli call sample insert_user 1
+
+❯ spacetimedb-cli logs sample
+...
+.. User: Users { user_id: 3, name: "User 2" }
+.. User: Users { user_id: 4098, name: "User 0" }
+```
diff --git a/docs/bsatn.md b/docs/bsatn.md
@@ -104,6 +104,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/satn)
+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_.