From ccd49c436993ef0b9537498637e8d0076b13fc47 Mon Sep 17 00:00:00 2001 From: Gemma Shay Date: Tue, 3 Oct 2023 15:27:28 -0400 Subject: [PATCH 1/3] draft --- .../quickstart/create-a-free-cluster.md | 4 + .../v21.2/setup/create-first-sql-user.md | 2 +- .../v22.2/setup/create-first-sql-user.md | 2 +- .../v23.1/setup/create-a-free-cluster.md | 4 + .../v23.1/setup/create-first-sql-user.md | 2 +- .../v23.2/setup/create-a-free-cluster.md | 4 + .../v23.2/setup/create-first-sql-user.md | 2 +- .../create-a-serverless-cluster.md | 2 +- src/current/cockroachcloud/quickstart.md | 167 +----------------- 9 files changed, 23 insertions(+), 166 deletions(-) diff --git a/src/current/_includes/cockroachcloud/quickstart/create-a-free-cluster.md b/src/current/_includes/cockroachcloud/quickstart/create-a-free-cluster.md index 28fbf2e780b..a40bf5d0d4b 100644 --- a/src/current/_includes/cockroachcloud/quickstart/create-a-free-cluster.md +++ b/src/current/_includes/cockroachcloud/quickstart/create-a-free-cluster.md @@ -4,6 +4,10 @@ 1. [Log in](https://cockroachlabs.cloud/) to your CockroachDB {{ site.data.products.cloud }} account. 1. On the **Clusters** page, click **Create Cluster**. 1. On the **Create your cluster** page, select **Serverless**. +1. *(Optional)* Set a **Resource limit**. + + Each non-contract CockroachDB {{ site.data.products.cloud }} organization is given 50 million [Request Units](#request-units) and 10 GiB of storage for free each month. If this is your first cluster, you can select **Start for free**. + 1. Click **Create cluster**. Your cluster will be created in a few seconds and the **Create SQL user** dialog will display. \ No newline at end of file diff --git a/src/current/_includes/v21.2/setup/create-first-sql-user.md b/src/current/_includes/v21.2/setup/create-first-sql-user.md index a1e46b5694b..b9d21128c99 100644 --- a/src/current/_includes/v21.2/setup/create-first-sql-user.md +++ b/src/current/_includes/v21.2/setup/create-first-sql-user.md @@ -5,4 +5,4 @@ The **Create SQL user** dialog allows you to create a new SQL user and password. 1. Copy the generated password and save it in a secure location. 1. Click **Next**. - Currently, all new users are created with full privileges. For more information and to change the default settings, see [[Manage SQL users on a cluster](../cockroachcloud/managing-access.html#manage-sql-users-on-a-cluster). \ No newline at end of file + Currently, all new users are created with full privileges. For more information and to change the default settings, see [Manage SQL users on a cluster](../cockroachcloud/managing-access.html#manage-sql-users-on-a-cluster). \ No newline at end of file diff --git a/src/current/_includes/v22.2/setup/create-first-sql-user.md b/src/current/_includes/v22.2/setup/create-first-sql-user.md index 9b573c79fc3..6ee617d8fba 100644 --- a/src/current/_includes/v22.2/setup/create-first-sql-user.md +++ b/src/current/_includes/v22.2/setup/create-first-sql-user.md @@ -5,4 +5,4 @@ The **Create SQL user** dialog allows you to create a new SQL user and password. 1. Copy the generated password and save it in a secure location. 1. Click **Next**. - Currently, all new SQL users are created with admin privileges. For more information and to change the default settings, see [[Manage SQL users on a cluster](../cockroachcloud/managing-access.html#manage-sql-users-on-a-cluster). \ No newline at end of file + Currently, all new SQL users are created with admin privileges. For more information and to change the default settings, see [Manage SQL users on a cluster](../cockroachcloud/managing-access.html#manage-sql-users-on-a-cluster). \ No newline at end of file diff --git a/src/current/_includes/v23.1/setup/create-a-free-cluster.md b/src/current/_includes/v23.1/setup/create-a-free-cluster.md index 28fbf2e780b..a40bf5d0d4b 100644 --- a/src/current/_includes/v23.1/setup/create-a-free-cluster.md +++ b/src/current/_includes/v23.1/setup/create-a-free-cluster.md @@ -4,6 +4,10 @@ 1. [Log in](https://cockroachlabs.cloud/) to your CockroachDB {{ site.data.products.cloud }} account. 1. On the **Clusters** page, click **Create Cluster**. 1. On the **Create your cluster** page, select **Serverless**. +1. *(Optional)* Set a **Resource limit**. + + Each non-contract CockroachDB {{ site.data.products.cloud }} organization is given 50 million [Request Units](#request-units) and 10 GiB of storage for free each month. If this is your first cluster, you can select **Start for free**. + 1. Click **Create cluster**. Your cluster will be created in a few seconds and the **Create SQL user** dialog will display. \ No newline at end of file diff --git a/src/current/_includes/v23.1/setup/create-first-sql-user.md b/src/current/_includes/v23.1/setup/create-first-sql-user.md index 556a2d8ad60..20abe14e696 100644 --- a/src/current/_includes/v23.1/setup/create-first-sql-user.md +++ b/src/current/_includes/v23.1/setup/create-first-sql-user.md @@ -5,4 +5,4 @@ The **Create SQL user** dialog allows you to create a new SQL user and password. 1. Copy the generated password and save it in a secure location. 1. Click **Next**. - Currently, all new SQL users are created with admin privileges. For more information and to change the default settings, see [[Manage SQL users on a cluster](https://www.cockroachlabs.com/docs/cockroachcloud/managing-access#manage-sql-users-on-a-cluster). \ No newline at end of file + Currently, all new SQL users are created with admin privileges. For more information and to change the default settings, see [Manage SQL users on a cluster](https://www.cockroachlabs.com/docs/cockroachcloud/managing-access#manage-sql-users-on-a-cluster). \ No newline at end of file diff --git a/src/current/_includes/v23.2/setup/create-a-free-cluster.md b/src/current/_includes/v23.2/setup/create-a-free-cluster.md index 28fbf2e780b..a40bf5d0d4b 100644 --- a/src/current/_includes/v23.2/setup/create-a-free-cluster.md +++ b/src/current/_includes/v23.2/setup/create-a-free-cluster.md @@ -4,6 +4,10 @@ 1. [Log in](https://cockroachlabs.cloud/) to your CockroachDB {{ site.data.products.cloud }} account. 1. On the **Clusters** page, click **Create Cluster**. 1. On the **Create your cluster** page, select **Serverless**. +1. *(Optional)* Set a **Resource limit**. + + Each non-contract CockroachDB {{ site.data.products.cloud }} organization is given 50 million [Request Units](#request-units) and 10 GiB of storage for free each month. If this is your first cluster, you can select **Start for free**. + 1. Click **Create cluster**. Your cluster will be created in a few seconds and the **Create SQL user** dialog will display. \ No newline at end of file diff --git a/src/current/_includes/v23.2/setup/create-first-sql-user.md b/src/current/_includes/v23.2/setup/create-first-sql-user.md index 556a2d8ad60..20abe14e696 100644 --- a/src/current/_includes/v23.2/setup/create-first-sql-user.md +++ b/src/current/_includes/v23.2/setup/create-first-sql-user.md @@ -5,4 +5,4 @@ The **Create SQL user** dialog allows you to create a new SQL user and password. 1. Copy the generated password and save it in a secure location. 1. Click **Next**. - Currently, all new SQL users are created with admin privileges. For more information and to change the default settings, see [[Manage SQL users on a cluster](https://www.cockroachlabs.com/docs/cockroachcloud/managing-access#manage-sql-users-on-a-cluster). \ No newline at end of file + Currently, all new SQL users are created with admin privileges. For more information and to change the default settings, see [Manage SQL users on a cluster](https://www.cockroachlabs.com/docs/cockroachcloud/managing-access#manage-sql-users-on-a-cluster). \ No newline at end of file diff --git a/src/current/cockroachcloud/create-a-serverless-cluster.md b/src/current/cockroachcloud/create-a-serverless-cluster.md index 64d470662e0..24a06f5bf5a 100644 --- a/src/current/cockroachcloud/create-a-serverless-cluster.md +++ b/src/current/cockroachcloud/create-a-serverless-cluster.md @@ -51,7 +51,7 @@ Private connectivity is not available for {{ site.data.products.serverless }} cl Your cluster's [resource limits](https://www.cockroachlabs.com/docs/{{site.current_cloud_version}}/architecture/glossary#resource-limits) are the maximum amount of storage and RUs you can use in a month. If you reach your storage limit, your cluster will be throttled and you may only be able to delete data. If you reach your RU limit, your cluster will be disabled until the end of the billing cycle unless you raise the limit. -All CockroachDB {{ site.data.products.cloud }} organizations get 50M RUs and 10 GiB of storage for free each month. Free resources can be spent across all CockroachDB {{ site.data.products.serverless }} clusters in an organization. You can set higher resource limits to maintain a high level of performance with larger workloads. You will only be charged for what you use. +Each non-contract CockroachDB {{ site.data.products.cloud }} organization is given 50 million [Request Units](#request-units) and 10 GiB of storage for free each month. Free resources can be spent across all CockroachDB {{ site.data.products.serverless }} clusters in an organization. You can set higher resource limits to maintain a high level of performance with larger workloads. You will only be charged for what you use. {% include cockroachcloud/serverless-usage.md %} For more information, see [Planning your cluster]({% link cockroachcloud/plan-your-cluster.md %}). diff --git a/src/current/cockroachcloud/quickstart.md b/src/current/cockroachcloud/quickstart.md index 0f8331ca9af..3a4df6529b8 100644 --- a/src/current/cockroachcloud/quickstart.md +++ b/src/current/cockroachcloud/quickstart.md @@ -7,7 +7,7 @@ referral_id: docs_quickstart_free docs_area: get_started --- -This page shows you how to use the [CockroachDB {{ site.data.products.cloud }} Console](https://cockroachlabs.cloud) to create a CockroachDB {{ site.data.products.serverless }} cluster and then insert and read some sample data from a Java or Node.js sample application. +This page shows you how to use the [CockroachDB {{ site.data.products.cloud }} Console](https://cockroachlabs.cloud) to create a CockroachDB {{ site.data.products.serverless }} cluster, connect to it using a sample workload, and run your first query. ## Create a CockroachDB {{ site.data.products.serverless }} cluster @@ -19,97 +19,16 @@ This page shows you how to use the [CockroachDB {{ site.data.products.cloud }} C ## Connect to the cluster -Select a language to connect a sample application to your cluster. To connect to your cluster directly from the command line, refer to [Connect to a {{ site.data.products.serverless }} Cluster](connect-to-a-serverless-cluster.html?fiters=command-line#connect-to-your-cluster). +You can connect to your cluster directly from the {{ site.data.products.cloud }} Console's SQL Shell or using the command line. To connect a sample application to your cluster instead, refer to [Example Applications Overview]({% link /{{ site.current_cloud_version }}/example-apps.md %}).
- - + +
-
+
-Once you create a SQL user, the **Connect to cluster** dialog will show information about how to connect to your cluster. - -1. Select **Java** from the **Select option/language** dropdown. -1. Copy the `JDBC_DATABASE_URL` environment variable command provided and save it in a secure location. - - This Quickstart uses default certificates, so you can skip the Download CA Cert instructions. - - {{site.data.alerts.callout_info}} - The connection string is pre-populated with your username, password, cluster name, and other details. Your password, in particular, will be provided *only* once. Save it in a secure place (Cockroach Labs recommends a password manager) to connect to your cluster in the future. If you forget your password, a Cluster Administrator can reset it. Refer to: [Managing SQL users on a cluster]({% link cockroachcloud/managing-access.md %}#manage-sql-users-on-a-cluster) - {{site.data.alerts.end}} - -## Configure the connection environment variable - -
- - - -
- -
-In a terminal set the `JDBC_DATABASE_URL` environment variable to the JDBC connection string: - -{% include_cached copy-clipboard.html %} -~~~ shell -export JDBC_DATABASE_URL="" -~~~ - -The code sample uses the connection string stored in the environment variable `JDBC_DATABASE_URL` to connect to your cluster.
- -
-In a terminal set the `JDBC_DATABASE_URL` environment variable to the JDBC connection string: - -{% include_cached copy-clipboard.html %} -~~~ shell -$env:JDBC_DATABASE_URL = "" -~~~ - -The code sample uses the connection string stored in the environment variable `JDBC_DATABASE_URL` to connect to your cluster. -
- -## Run the Java sample code - -1. Clone the `quickstart-code-samples` repo: - - {% include_cached copy-clipboard.html %} - ~~~ shell - git clone https://github.com/cockroachdb/quickstart-code-samples - ~~~ - -1. Navigate to the `java` directory of the repo: - - {% include_cached copy-clipboard.html %} - ~~~ shell - cd quickstart-code-samples/java - ~~~ - - The code sample in this directory does the following: - 1. Connects to CockroachDB {{ site.data.products.cloud }} with the [JDBC driver](https://jdbc.postgresql.org) using the JDBC connection string set in the `JDBC_DATABASE_URL` environment variable. - 1. Creates a table. - 1. Inserts some data into the table. - 1. Reads the inserted data. - 1. Prints the data to the terminal. - -1. Run the application using `gradlew`: - - {% include_cached copy-clipboard.html %} - ~~~ shell - ./gradlew run - ~~~ - - The output should look like this: - - ~~~ - > Task :app:run - Hello world! - - BUILD SUCCESSFUL in 3s - 2 actionable tasks: 2 executed - ~~~ - -
-
+
Once you create a SQL user, the **Connect to cluster** dialog will show information about how to connect to your cluster. @@ -122,80 +41,6 @@ Once you create a SQL user, the **Connect to cluster** dialog will show informat The connection string is pre-populated with your username, password, cluster name, and other details. Your password, in particular, will be provided *only* once. Save it in a secure place (Cockroach Labs recommends a password manager) to connect to your cluster in the future. If you forget your password, a Cluster Administrator can reset it. Refer to: [Managing SQL users on a cluster]({% link cockroachcloud/managing-access.md %}#manage-sql-users-on-a-cluster) {{site.data.alerts.end}} -## Configure the connection environment variable - -
- - - -
- -
-In a terminal set the `DATABASE_URL` environment variable to the connection string: - -{% include_cached copy-clipboard.html %} -~~~ shell -export DATABASE_URL="" -~~~ - -The code sample uses the connection string stored in the environment variable `DATABASE_URL` to connect to your cluster. -
- -
-In a terminal set the `DATABASE_URL` environment variable to the connection string: - -{% include_cached copy-clipboard.html %} -~~~ shell -$env:DATABASE_URL = "" -~~~ - -The code sample uses the connection string stored in the environment variable `DATABASE_URL` to connect to your cluster. -
- -## Run the Node.js sample code - -1. Clone the `quickstart-code-samples` repo: - - {% include_cached copy-clipboard.html %} - ~~~ shell - git clone https://github.com/cockroachdb/quickstart-code-samples - ~~~ - -1. Navigate to the `node` directory of the repo: - - {% include_cached copy-clipboard.html %} - ~~~ shell - cd quickstart-code-samples/node - ~~~ - - The code sample in this directory does the following: - 1. Connects to CockroachDB {{ site.data.products.cloud }} with the [node-postgres driver](https://node-postgres.com) using the connection string set in the `DATABASE_URL` environment variable. - 1. Creates a table. - 1. Inserts some data into the table. - 1. Reads the inserted data. - 1. Prints the data to the terminal. - - -1. Install the app requirements: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ npm install - ~~~ - -1. Run the app: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ node app.js - ~~~ - - The output will look like this: - - ~~~ - Hello world! - ~~~ -
## Learn more From 4d15e0c9506c72273a9b3a985540fe7e1d883976 Mon Sep 17 00:00:00 2001 From: Gemma Shay Date: Tue, 3 Oct 2023 15:35:56 -0400 Subject: [PATCH 2/3] link --- src/current/cockroachcloud/quickstart.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/current/cockroachcloud/quickstart.md b/src/current/cockroachcloud/quickstart.md index 3a4df6529b8..5f68324f743 100644 --- a/src/current/cockroachcloud/quickstart.md +++ b/src/current/cockroachcloud/quickstart.md @@ -19,13 +19,14 @@ This page shows you how to use the [CockroachDB {{ site.data.products.cloud }} C ## Connect to the cluster -You can connect to your cluster directly from the {{ site.data.products.cloud }} Console's SQL Shell or using the command line. To connect a sample application to your cluster instead, refer to [Example Applications Overview]({% link /{{ site.current_cloud_version }}/example-apps.md %}). +You can connect to your cluster directly from the {{ site.data.products.cloud }} Console's SQL Shell or using the command line. To connect a sample application to your cluster instead, refer to [Example Applications Overview](https://www.cockroachlabs.com/docs/{{site.current_cloud_version}}/example-apps.md)
-
+ +
@@ -50,7 +51,7 @@ Now that you have a free CockroachDB {{ site.data.products.serverless }} cluster - Build a simple CRUD application in [Go](https://www.cockroachlabs.com/docs/{{site.current_cloud_version}}/build-a-go-app-with-cockroachdb), [Java](https://www.cockroachlabs.com/docs/{{site.current_cloud_version}}/build-a-java-app-with-cockroachdb), [Node.js](https://www.cockroachlabs.com/docs/{{site.current_cloud_version}}/build-a-nodejs-app-with-cockroachdb), or [Python](https://www.cockroachlabs.com/docs/{{site.current_cloud_version}}/build-a-python-app-with-cockroachdb). - [Learn CockroachDB SQL]({% link cockroachcloud/learn-cockroachdb-sql.md %}). - [Create and manage SQL users]({% link cockroachcloud/managing-access.md %}). -- Explore our [example apps](https://www.cockroachlabs.com/docs/{{site.current_cloud_version}}/example-apps) for examples on how to build applications using your preferred driver or ORM and run it on CockroachDB. +- Explore our [example apps](https://www.cockroachlabs.com/docs/{{site.current_cloud_version}}/example-apps.md) for examples on how to build applications using your preferred driver or ORM and run it on CockroachDB. - [Migrate your existing data](https://www.cockroachlabs.com/docs/{{site.current_cloud_version}}/migration-overview). This page highlights just one way you can get started with CockroachDB. For information on other options that are available when creating a CockroachDB cluster, see the following: From dd945041afbea4b8d9062a290be4788a4e83b9ae Mon Sep 17 00:00:00 2001 From: Gemma Shay Date: Tue, 3 Oct 2023 15:59:33 -0400 Subject: [PATCH 3/3] draft commands --- src/current/cockroachcloud/quickstart.md | 75 ++++++++++++++++++++++-- 1 file changed, 69 insertions(+), 6 deletions(-) diff --git a/src/current/cockroachcloud/quickstart.md b/src/current/cockroachcloud/quickstart.md index 5f68324f743..3e60403479b 100644 --- a/src/current/cockroachcloud/quickstart.md +++ b/src/current/cockroachcloud/quickstart.md @@ -28,22 +28,85 @@ You can connect to your cluster directly from the {{ site.data.products.cloud }}
+{{site.data.alerts.callout_info}} +The SQL Shell is available only to team members with the [Cluster Administrator role]({% link cockroachcloud/managing-access.md %}). +{{site.data.alerts.end}} + +1. Close the **Connect to cluster** dialog that displays once you create a SQL user. +1. From the cluster's **Overview** page, navigate to the **SQL Shell**. +
Once you create a SQL user, the **Connect to cluster** dialog will show information about how to connect to your cluster. -1. Select **General connection string** from the **Select option** dropdown. -1. Open the **General connection string** section, then copy the connection string provided and save it in a secure location. +1. Select **CockroachDB Client** from the **Select option** dropdown. +1. In a terminal, run the command provided in the **Download the latest CockroachDB Client** section of the dialog to install CockroachDB. +1. Expand the **Connect to the database** section, then copy the `cockroach sql` command provided and save it in a secure location. + + {% include_cached copy-clipboard.html %} + ~~~ + cockroach sql --url "postgresql://{user}@{host}:{port}/defaultdb?sslmode=verify-full" + ~~~ + +1. In your terminal, enter the copied `cockroach sql` command and connection string to start the [built-in SQL client](https://www.cockroachlabs.com/docs/{{site.current_cloud_version}}/cockroach-sql.html). + +1. Enter the SQL user's password and hit enter. - This Quickstart uses default certificates, so you can skip the Download CA Cert instructions. + {% include cockroachcloud/postgresql-special-characters.md %} - {{site.data.alerts.callout_info}} - The connection string is pre-populated with your username, password, cluster name, and other details. Your password, in particular, will be provided *only* once. Save it in a secure place (Cockroach Labs recommends a password manager) to connect to your cluster in the future. If you forget your password, a Cluster Administrator can reset it. Refer to: [Managing SQL users on a cluster]({% link cockroachcloud/managing-access.md %}#manage-sql-users-on-a-cluster) - {{site.data.alerts.end}} + A welcome message displays: + + ~~~ + # + # Welcome to the CockroachDB SQL shell. + # All statements must be terminated by a semicolon. + # To exit, type: \q. + # + ~~~
+## Run SQL statements + +1. You can now run [CockroachDB SQL statements]({% link cockroachcloud/learn-cockroachdb-sql.md %}): + + {% include_cached copy-clipboard.html %} + ~~~ sql + > CREATE DATABASE bank; + ~~~ + + {% include_cached copy-clipboard.html %} + ~~~ sql + > CREATE TABLE bank.accounts (id INT PRIMARY KEY, balance DECIMAL); + ~~~ + + {% include_cached copy-clipboard.html %} + ~~~ sql + > INSERT INTO bank.accounts VALUES (1, 1000.50); + ~~~ + + {% include_cached copy-clipboard.html %} + ~~~ sql + > SELECT * FROM bank.accounts; + ~~~ + + ~~~ + id | balance + -----+---------- + 1 | 1000.50 + (1 row) + ~~~ + +
+1. To exit the SQL shell: + + {% include_cached copy-clipboard.html %} + ~~~ sql + > \q + ~~~ +
+ ## Learn more Now that you have a free CockroachDB {{ site.data.products.serverless }} cluster running, try out the following: