From cbd2f29efaef5547bc11b465e38d7d2c8d84c9d1 Mon Sep 17 00:00:00 2001 From: clockwork-labs-bot Date: Mon, 16 Feb 2026 22:33:06 -0500 Subject: [PATCH 1/5] docs: expand Maincloud deployment page Rewrote the Maincloud deployment guide to cover: - Prerequisites: CLI install and login flow to link web account - Publishing: initial publish, hot-swap updates, clearing data - Client connection: host URL (https://maincloud.spacetimedb.com) with code examples for TypeScript, C#, Rust, and C++ - Web dashboard: how to find your database (direct URL and profile), dashboard features (logs, SQL console, SpacetimeAuth) - Database lifecycle: running vs suspended states, automatic suspension/resumption behavior - Deleting a database - Next steps: dashboard, auth, quickstarts, usage monitoring Closes #3108 --- .../00100-deploy/00100-maincloud.md | 110 +++++++++++++++--- 1 file changed, 92 insertions(+), 18 deletions(-) diff --git a/docs/docs/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md b/docs/docs/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md index 004fad8e7ed..4ea79a4082c 100644 --- a/docs/docs/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md +++ b/docs/docs/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md @@ -6,44 +6,55 @@ slug: /how-to/deploy/maincloud import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -Maincloud is a managed cloud service that provides developers an easy way to deploy their SpacetimeDB apps to the cloud. +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. -## Deploy via CLI +For pricing details, see the [pricing page](https://spacetimedb.com/pricing). -1. Install the SpacetimeDB CLI for your platform: [Install SpacetimeDB](https://spacetimedb.com/install) -1. Create your module (see [Getting Started](/)) -1. Publish to Maincloud: +## Prerequisites + +1. Install the SpacetimeDB CLI: [Install SpacetimeDB](https://spacetimedb.com/install) +2. Log in to link your CLI identity with your web account: ```bash -spacetime publish -s maincloud my-cool-module +spacetime login ``` -## Connecting your Identity to the Web Dashboard +This opens a browser window where you sign in with your GitHub account. Once authenticated, your CLI identity is linked to your Maincloud account, and any databases you publish will appear on the web dashboard. + +:::tip +If you previously published a database without logging in first, your CLI identity will not be linked to your web account. Run `spacetime logout` followed by `spacetime login` to re-authenticate. +::: -By logging in your CLI via spacetimedb.com, you can view your published modules on the web dashboard. +## Publishing to Maincloud -If you did not log in with spacetimedb.com when publishing your module, you can log in by running: +After creating your module (see [Getting Started](/)), publish it to Maincloud: ```bash -spacetime logout -spacetime login +spacetime publish my-module --server maincloud ``` -1. Open the SpacetimeDB website and log in using your GitHub login. -1. You should now be able to see your published modules [https://spacetimedb.com/profile](https://spacetimedb.com/profile), or you can navigate to your database directly at [https://spacetimedb.com/my-cool-module](https://spacetimedb.com/my-cool-module). +SpacetimeDB compiles your module, uploads it, runs your `init` reducer (if defined), and outputs the database identity. Save this identity for administrative tasks. ---- +To update an existing module, run the same command. SpacetimeDB hot-swaps the module code without disconnecting clients. See [Automatic Migrations](/databases/automatic-migrations) for details on schema changes during updates. -With SpacetimeDB Maincloud, you benefit from automatic scaling, robust security, and the convenience of not having to manage the hosting environment. +To clear all data and start fresh: +```bash +spacetime publish my-module --server maincloud --delete-data +``` -To connect to your deployed module in your client code, use the host url of `https://maincloud.spacetimedb.com`: +## Connecting Clients to Maincloud + +To connect your client application to a module running on Maincloud, use `https://maincloud.spacetimedb.com` as the host URL and your database name as the module name: ```ts -DbConnection.builder().withUri('https://maincloud.spacetimedb.com'); +DbConnection.builder() + .withUri("https://maincloud.spacetimedb.com") + .withModuleName("my-module") + .build(); ``` @@ -52,15 +63,78 @@ DbConnection.builder().withUri('https://maincloud.spacetimedb.com'); ```csharp DbConnection.Builder() .WithUri("https://maincloud.spacetimedb.com") + .WithModuleName("my-module") + .Build(); ``` + ```rust DbConnection::builder() .with_uri("https://maincloud.spacetimedb.com") + .with_module_name("my-module") + .build() + .expect("Failed to connect"); ``` + + +```cpp +auto conn = DbConnection::builder() + .with_uri("https://maincloud.spacetimedb.com") + .with_module_name("my-module") + .build(); +``` + + + + +## Viewing Your Database on the Web Dashboard + +After publishing, you can manage your database through the web dashboard at [spacetimedb.com](https://spacetimedb.com). + +### Finding your database + +There are two ways to navigate to your database: + +1. **Direct URL**: Go to `https://spacetimedb.com/my-module` (replacing `my-module` with your database name). +2. **Profile page**: Click your profile picture in the top-right corner of [spacetimedb.com](https://spacetimedb.com) and select "My profile". All of your published databases are listed there. You can also navigate directly to `https://spacetimedb.com/@your-username`. + +### Dashboard features + +The database dashboard gives you access to: + +- **Database info**: View your database identity, name, and current status. +- **Logs**: View your module's log output in real time. +- **SQL console**: Run ad-hoc SQL queries against your database. +- **SpacetimeAuth**: Enable and configure the built-in authentication provider (see [SpacetimeAuth](/spacetimeauth)). + +## Database Lifecycle + +Maincloud databases have two states: + +- **Running**: The database is actively serving requests. Any client connection, reducer call, or dashboard visit will keep it in this state. +- **Suspended**: After a period of inactivity (no client connections, no reducer calls), Maincloud automatically suspends the database to save resources. This is not the same as deleting it; all data is preserved. + +A suspended database resumes automatically when it receives a connection or request. The first request after suspension may take a moment while the database wakes up and replays its commit log. Subsequent requests are served at normal speed. + +There is currently no manual way to pause or resume a database from the dashboard or CLI. Suspension and resumption are handled automatically by Maincloud. + +## Deleting a Database + +To permanently delete a database and all its data: + +```bash +spacetime delete my-module --server maincloud +``` + +This action cannot be undone. + +## Next Steps - \ No newline at end of file +- **Explore the dashboard**: Visit [spacetimedb.com](https://spacetimedb.com) to view your database, check logs, and run queries. +- **Set up authentication**: Enable [SpacetimeAuth](/spacetimeauth) or connect a third-party [OIDC provider](/authentication) to authenticate your users. +- **Connect a client**: Follow a [quickstart guide](/quickstart) to build a client that connects to your Maincloud database. +- **Monitor your usage**: Check your energy consumption and plan limits on the [pricing page](https://spacetimedb.com/pricing). From 96ab6c1f3b6e99b316c58843a32d9da9ecdea71e Mon Sep 17 00:00:00 2001 From: clockwork-labs-bot Date: Mon, 16 Feb 2026 22:34:50 -0500 Subject: [PATCH 2/5] docs: add manual pause/resume and usage breakdown to Maincloud page - Database can now be manually paused and resumed from the dashboard - Pausing stops energy usage while preserving data - Added usage breakdown details (bytes scanned/written, index seeks, CPU instructions, bandwidth, table storage) - Added 24-hour stats (CCU, rows per table, transactions) --- .../00100-deploy/00100-maincloud.md | 21 ++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/docs/docs/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md b/docs/docs/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md index 4ea79a4082c..999a03cf4ea 100644 --- a/docs/docs/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md +++ b/docs/docs/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md @@ -106,7 +106,8 @@ There are two ways to navigate to your database: The database dashboard gives you access to: -- **Database info**: View your database identity, name, and current status. +- **Overview**: View your database identity, name, status (Running or Paused), table and reducer counts, and energy usage. The overview also shows stats for the past 24 hours including CCU, rows per table, and transactions. +- **Usage breakdown**: See this month's energy consumption broken down by bytes scanned, bytes written, index seeks, CPU instructions, bandwidth, and table storage. - **Logs**: View your module's log output in real time. - **SQL console**: Run ad-hoc SQL queries against your database. - **SpacetimeAuth**: Enable and configure the built-in authentication provider (see [SpacetimeAuth](/spacetimeauth)). @@ -115,12 +116,22 @@ The database dashboard gives you access to: Maincloud databases have two states: -- **Running**: The database is actively serving requests. Any client connection, reducer call, or dashboard visit will keep it in this state. -- **Suspended**: After a period of inactivity (no client connections, no reducer calls), Maincloud automatically suspends the database to save resources. This is not the same as deleting it; all data is preserved. +- **Running** (green dot on dashboard): The database is actively serving requests. Any client connection, reducer call, or dashboard visit will keep it in this state. +- **Paused** (pause icon on dashboard): The database is suspended. All data is preserved, but the database is not serving requests and does not consume energy. -A suspended database resumes automatically when it receives a connection or request. The first request after suspension may take a moment while the database wakes up and replays its commit log. Subsequent requests are served at normal speed. +### Automatic suspension -There is currently no manual way to pause or resume a database from the dashboard or CLI. Suspension and resumption are handled automatically by Maincloud. +After a period of inactivity (no client connections, no reducer calls), Maincloud automatically pauses the database to save resources. A paused database resumes automatically when it receives a connection or request. The first request after resumption may take a moment while the database wakes up and replays its commit log. Subsequent requests are served at normal speed. + +### Manual pause and resume + +You can manually pause and resume your database from the web dashboard: + +1. Navigate to your database on [spacetimedb.com](https://spacetimedb.com). +2. In the left sidebar, check the **Status** field to see if your database is Running or Paused. +3. Click **Pause Database** to suspend the database, or **Start Database** to resume it. + +Pausing a database stops all energy usage for that database. This is useful if you want to keep your data but are not actively using the database. ## Deleting a Database From de0203069604c92b802a57f18af0605d88d1b2ce Mon Sep 17 00:00:00 2001 From: clockwork-labs-bot Date: Mon, 16 Feb 2026 22:43:09 -0500 Subject: [PATCH 3/5] docs: address review comments on Maincloud page - Fix API: withModuleName -> withDatabaseName (2.0 rename) - Fix direct URL to include @username/database format - Clarify auto-suspension is Free tier only; Pro/Team never auto-suspend with pay-as-you-go enabled - Note startup time is typically less than 1 second - Fix delete command to use my-database --- .../00100-deploy/00100-maincloud.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/docs/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md b/docs/docs/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md index 999a03cf4ea..72397f17f21 100644 --- a/docs/docs/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md +++ b/docs/docs/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md @@ -53,7 +53,7 @@ To connect your client application to a module running on Maincloud, use `https: ```ts DbConnection.builder() .withUri("https://maincloud.spacetimedb.com") - .withModuleName("my-module") + .withDatabaseName("my-module") .build(); ``` @@ -63,7 +63,7 @@ DbConnection.builder() ```csharp DbConnection.Builder() .WithUri("https://maincloud.spacetimedb.com") - .WithModuleName("my-module") + .WithDatabaseName("my-module") .Build(); ``` @@ -73,7 +73,7 @@ DbConnection.Builder() ```rust DbConnection::builder() .with_uri("https://maincloud.spacetimedb.com") - .with_module_name("my-module") + .with_database_name("my-module") .build() .expect("Failed to connect"); ``` @@ -84,7 +84,7 @@ DbConnection::builder() ```cpp auto conn = DbConnection::builder() .with_uri("https://maincloud.spacetimedb.com") - .with_module_name("my-module") + .with_database_name("my-module") .build(); ``` @@ -99,7 +99,7 @@ After publishing, you can manage your database through the web dashboard at [spa There are two ways to navigate to your database: -1. **Direct URL**: Go to `https://spacetimedb.com/my-module` (replacing `my-module` with your database name). +1. **Direct URL**: Go to `https://spacetimedb.com/my-database` or `https://spacetimedb.com/@my-username/my-database` (replacing `my-database` with your database name). 2. **Profile page**: Click your profile picture in the top-right corner of [spacetimedb.com](https://spacetimedb.com) and select "My profile". All of your published databases are listed there. You can also navigate directly to `https://spacetimedb.com/@your-username`. ### Dashboard features @@ -119,9 +119,11 @@ Maincloud databases have two states: - **Running** (green dot on dashboard): The database is actively serving requests. Any client connection, reducer call, or dashboard visit will keep it in this state. - **Paused** (pause icon on dashboard): The database is suspended. All data is preserved, but the database is not serving requests and does not consume energy. -### Automatic suspension +### Automatic suspension (Free tier) -After a period of inactivity (no client connections, no reducer calls), Maincloud automatically pauses the database to save resources. A paused database resumes automatically when it receives a connection or request. The first request after resumption may take a moment while the database wakes up and replays its commit log. Subsequent requests are served at normal speed. +On the Free tier, Maincloud automatically pauses databases after a period of inactivity (no client connections, no reducer calls). A paused database resumes automatically when it receives a connection or request. Startup time is typically less than one second. + +On the Pro and Team tiers, databases are never automatically suspended as long as you have pay-as-you-go enabled or have not exceeded your self-set spending limit. If you want to ensure your database is always available, upgrade to the [Pro or Team tier](https://spacetimedb.com/pricing). ### Manual pause and resume @@ -138,7 +140,7 @@ Pausing a database stops all energy usage for that database. This is useful if y To permanently delete a database and all its data: ```bash -spacetime delete my-module --server maincloud +spacetime delete my-database --server maincloud ``` This action cannot be undone. From d75bb40c438a8ebc7f33b516928ef26ec4a60989 Mon Sep 17 00:00:00 2001 From: clockwork-labs-bot Date: Mon, 16 Feb 2026 22:45:51 -0500 Subject: [PATCH 4/5] docs: replace remaining my-module with my-database --- .../00100-how-to/00100-deploy/00100-maincloud.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/docs/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md b/docs/docs/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md index 72397f17f21..5512884f4dd 100644 --- a/docs/docs/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md +++ b/docs/docs/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md @@ -30,7 +30,7 @@ If you previously published a database without logging in first, your CLI identi After creating your module (see [Getting Started](/)), publish it to Maincloud: ```bash -spacetime publish my-module --server maincloud +spacetime publish my-database --server maincloud ``` SpacetimeDB compiles your module, uploads it, runs your `init` reducer (if defined), and outputs the database identity. Save this identity for administrative tasks. @@ -40,7 +40,7 @@ To update an existing module, run the same command. SpacetimeDB hot-swaps the mo To clear all data and start fresh: ```bash -spacetime publish my-module --server maincloud --delete-data +spacetime publish my-database --server maincloud --delete-data ``` ## Connecting Clients to Maincloud @@ -53,7 +53,7 @@ To connect your client application to a module running on Maincloud, use `https: ```ts DbConnection.builder() .withUri("https://maincloud.spacetimedb.com") - .withDatabaseName("my-module") + .withDatabaseName("my-database") .build(); ``` @@ -63,7 +63,7 @@ DbConnection.builder() ```csharp DbConnection.Builder() .WithUri("https://maincloud.spacetimedb.com") - .WithDatabaseName("my-module") + .WithDatabaseName("my-database") .Build(); ``` @@ -73,7 +73,7 @@ DbConnection.Builder() ```rust DbConnection::builder() .with_uri("https://maincloud.spacetimedb.com") - .with_database_name("my-module") + .with_database_name("my-database") .build() .expect("Failed to connect"); ``` @@ -84,7 +84,7 @@ DbConnection::builder() ```cpp auto conn = DbConnection::builder() .with_uri("https://maincloud.spacetimedb.com") - .with_database_name("my-module") + .with_database_name("my-database") .build(); ``` From b58085e8a797698f6fa4d903052f297dd02a77be Mon Sep 17 00:00:00 2001 From: clockwork-labs-bot Date: Mon, 16 Feb 2026 22:48:42 -0500 Subject: [PATCH 5/5] docs: fix broken links in Maincloud page - /spacetimeauth -> /core-concepts/authentication/spacetimeauth - /authentication -> /core-concepts/authentication - /quickstart -> /quickstarts/react --- .../00100-how-to/00100-deploy/00100-maincloud.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md b/docs/docs/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md index 5512884f4dd..1a43149a207 100644 --- a/docs/docs/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md +++ b/docs/docs/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md @@ -110,7 +110,7 @@ The database dashboard gives you access to: - **Usage breakdown**: See this month's energy consumption broken down by bytes scanned, bytes written, index seeks, CPU instructions, bandwidth, and table storage. - **Logs**: View your module's log output in real time. - **SQL console**: Run ad-hoc SQL queries against your database. -- **SpacetimeAuth**: Enable and configure the built-in authentication provider (see [SpacetimeAuth](/spacetimeauth)). +- **SpacetimeAuth**: Enable and configure the built-in authentication provider (see [SpacetimeAuth](/core-concepts/authentication/spacetimeauth)). ## Database Lifecycle @@ -148,6 +148,6 @@ This action cannot be undone. ## Next Steps - **Explore the dashboard**: Visit [spacetimedb.com](https://spacetimedb.com) to view your database, check logs, and run queries. -- **Set up authentication**: Enable [SpacetimeAuth](/spacetimeauth) or connect a third-party [OIDC provider](/authentication) to authenticate your users. -- **Connect a client**: Follow a [quickstart guide](/quickstart) to build a client that connects to your Maincloud database. +- **Set up authentication**: Enable [SpacetimeAuth](/core-concepts/authentication/spacetimeauth) or connect a third-party [OIDC provider](/core-concepts/authentication) to authenticate your users. +- **Connect a client**: Follow a [quickstart guide](/quickstarts/react) to build a client that connects to your Maincloud database. - **Monitor your usage**: Check your energy consumption and plan limits on the [pricing page](https://spacetimedb.com/pricing).