From 9caebbb275d447866f46eae3b7ed876a5b1bb767 Mon Sep 17 00:00:00 2001 From: Matt Linville Date: Tue, 20 Aug 2024 12:11:13 -0700 Subject: [PATCH 01/11] Move connection string info to shared include --- .../_includes/cockroachcloud/connection-string-standard.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 src/current/_includes/cockroachcloud/connection-string-standard.md diff --git a/src/current/_includes/cockroachcloud/connection-string-standard.md b/src/current/_includes/cockroachcloud/connection-string-standard.md new file mode 100644 index 00000000000..1d4310f1f66 --- /dev/null +++ b/src/current/_includes/cockroachcloud/connection-string-standard.md @@ -0,0 +1,3 @@ +After the cluster is created, the **Connection info** window appears. Click the **Connection string** tab and copy the connection string to a secure location. You will use this connection string to connect to CockroachDB later in the tutorial. + +The connection string is pre-populated with your SQL username and password, the cluster name, and other details. Save the password in a secure place such a password manager. You can find the connection string at any time from the CockroachDB Cloud Console. You can reset your SQL password for this cluster from the cluster's **SQL Users** page. From 8965473fc4b38fb941dd5cdc114df59a0c0890ed Mon Sep 17 00:00:00 2001 From: Matt Linville Date: Tue, 20 Aug 2024 12:14:30 -0700 Subject: [PATCH 02/11] Cache some shared static includes --- .../v24.2/build-a-java-app-with-cockroachdb-hibernate.md | 2 +- src/current/v24.2/build-a-java-app-with-cockroachdb-jooq.md | 2 +- src/current/v24.2/build-a-java-app-with-cockroachdb.md | 2 +- .../v24.2/build-a-nodejs-app-with-cockroachdb-knexjs.md | 2 +- .../v24.2/build-a-nodejs-app-with-cockroachdb-prisma.md | 2 +- src/current/v24.2/build-a-nodejs-app-with-cockroachdb.md | 2 +- .../v24.2/build-a-python-app-with-cockroachdb-asyncpg.md | 2 +- .../v24.2/build-a-python-app-with-cockroachdb-django.md | 2 +- .../v24.2/build-a-python-app-with-cockroachdb-psycopg3.md | 2 +- .../v24.2/build-a-python-app-with-cockroachdb-sqlalchemy.md | 4 ++-- src/current/v24.2/build-a-python-app-with-cockroachdb.md | 2 +- .../v24.2/build-a-ruby-app-with-cockroachdb-activerecord.md | 2 +- src/current/v24.2/build-a-ruby-app-with-cockroachdb.md | 2 +- src/current/v24.2/build-a-spring-app-with-cockroachdb-jdbc.md | 2 +- src/current/v24.2/build-a-spring-app-with-cockroachdb-jpa.md | 2 +- src/current/v24.2/build-a-typescript-app-with-cockroachdb.md | 2 +- 16 files changed, 17 insertions(+), 17 deletions(-) diff --git a/src/current/v24.2/build-a-java-app-with-cockroachdb-hibernate.md b/src/current/v24.2/build-a-java-app-with-cockroachdb-hibernate.md index deaf6ead590..c19bdcaed7b 100644 --- a/src/current/v24.2/build-a-java-app-with-cockroachdb-hibernate.md +++ b/src/current/v24.2/build-a-java-app-with-cockroachdb-hibernate.md @@ -152,4 +152,4 @@ Note that interleaved execution (partial execution of multiple statements within Read more about using the [Hibernate ORM](http://hibernate.org/orm/), or check out a more realistic implementation of Hibernate with CockroachDB in our [`examples-orms`](https://github.com/cockroachdb/examples-orms) repository. -{% include {{page.version.version}}/app/see-also-links.md %} +{% include_cached {{page.version.version}}/app/see-also-links.md %} diff --git a/src/current/v24.2/build-a-java-app-with-cockroachdb-jooq.md b/src/current/v24.2/build-a-java-app-with-cockroachdb-jooq.md index 7701e284e1c..9cc7c07ccf1 100644 --- a/src/current/v24.2/build-a-java-app-with-cockroachdb-jooq.md +++ b/src/current/v24.2/build-a-java-app-with-cockroachdb-jooq.md @@ -269,4 +269,4 @@ SELECT id, balance FROM accounts; Read more about using [jOOQ](https://www.jooq.org/), or check out a more realistic implementation of jOOQ with CockroachDB in our [`examples-orms`](https://github.com/cockroachdb/examples-orms) repository. -{% include {{page.version.version}}/app/see-also-links.md %} +{% include_cached {{page.version.version}}/app/see-also-links.md %} diff --git a/src/current/v24.2/build-a-java-app-with-cockroachdb.md b/src/current/v24.2/build-a-java-app-with-cockroachdb.md index 38d4b02bb14..eae610ab364 100644 --- a/src/current/v24.2/build-a-java-app-with-cockroachdb.md +++ b/src/current/v24.2/build-a-java-app-with-cockroachdb.md @@ -328,4 +328,4 @@ For guidance on connection pooling, with an example using JDBC and [HikariCP](ht Read more about using the [Java JDBC driver](https://jdbc.postgresql.org/). -{% include {{page.version.version}}/app/see-also-links.md %} +{% include_cached {{page.version.version}}/app/see-also-links.md %} diff --git a/src/current/v24.2/build-a-nodejs-app-with-cockroachdb-knexjs.md b/src/current/v24.2/build-a-nodejs-app-with-cockroachdb-knexjs.md index 04e67363a9e..e6f4ee477fb 100644 --- a/src/current/v24.2/build-a-nodejs-app-with-cockroachdb-knexjs.md +++ b/src/current/v24.2/build-a-nodejs-app-with-cockroachdb-knexjs.md @@ -85,4 +85,4 @@ $ git clone https://github.com/cockroachlabs/example-app-node-knex ## What's next? -{% include {{page.version.version}}/app/see-also-links.md %} +{% include_cached {{page.version.version}}/app/see-also-links.md %} diff --git a/src/current/v24.2/build-a-nodejs-app-with-cockroachdb-prisma.md b/src/current/v24.2/build-a-nodejs-app-with-cockroachdb-prisma.md index 560acba96bb..afda47789ec 100644 --- a/src/current/v24.2/build-a-nodejs-app-with-cockroachdb-prisma.md +++ b/src/current/v24.2/build-a-nodejs-app-with-cockroachdb-prisma.md @@ -220,4 +220,4 @@ All Customer rows deleted. { count: 10 } Read more about using [Prisma Client](https://www.prisma.io/docs/). -{% include {{page.version.version}}/app/see-also-links.md %} +{% include_cached {{page.version.version}}/app/see-also-links.md %} diff --git a/src/current/v24.2/build-a-nodejs-app-with-cockroachdb.md b/src/current/v24.2/build-a-nodejs-app-with-cockroachdb.md index e0f3e3f88a2..39df626e5bd 100644 --- a/src/current/v24.2/build-a-nodejs-app-with-cockroachdb.md +++ b/src/current/v24.2/build-a-nodejs-app-with-cockroachdb.md @@ -105,4 +105,4 @@ All of the database operations are wrapped in a helper function named `retryTxn` Read more about using the [node-postgres driver](https://www.npmjs.com/package/pg). -{% include {{page.version.version}}/app/see-also-links.md %} +{% include_cached {{page.version.version}}/app/see-also-links.md %} diff --git a/src/current/v24.2/build-a-python-app-with-cockroachdb-asyncpg.md b/src/current/v24.2/build-a-python-app-with-cockroachdb-asyncpg.md index af6a614d63f..8043ef1b9a5 100644 --- a/src/current/v24.2/build-a-python-app-with-cockroachdb-asyncpg.md +++ b/src/current/v24.2/build-a-python-app-with-cockroachdb-asyncpg.md @@ -107,4 +107,4 @@ For other ways to install Psycopg, see the [official documentation](https://www. Read more about using the [asyncpg](https://magicstack.github.io/asyncpg/current/usage.html). -{% include {{page.version.version}}/app/see-also-links.md %} +{% include_cached {{page.version.version}}/app/see-also-links.md %} diff --git a/src/current/v24.2/build-a-python-app-with-cockroachdb-django.md b/src/current/v24.2/build-a-python-app-with-cockroachdb-django.md index 88320dbb3fa..85644de65ed 100644 --- a/src/current/v24.2/build-a-python-app-with-cockroachdb-django.md +++ b/src/current/v24.2/build-a-python-app-with-cockroachdb-django.md @@ -239,4 +239,4 @@ This initializes the tables defined in `models.py`, in addition to some other ta Read more about writing a [Django app](https://docs.djangoproject.com/en/3.1/intro/tutorial01/). -{% include {{page.version.version}}/app/see-also-links.md %} +{% include_cached {{page.version.version}}/app/see-also-links.md %} diff --git a/src/current/v24.2/build-a-python-app-with-cockroachdb-psycopg3.md b/src/current/v24.2/build-a-python-app-with-cockroachdb-psycopg3.md index 07c1092d3c9..d59db6d73ef 100644 --- a/src/current/v24.2/build-a-python-app-with-cockroachdb-psycopg3.md +++ b/src/current/v24.2/build-a-python-app-with-cockroachdb-psycopg3.md @@ -103,4 +103,4 @@ For other ways to install Psycopg, see the [official documentation](https://www. Read more about using the [Python psycopg3 driver](https://www.psycopg.org/docs/). -{% include {{page.version.version}}/app/see-also-links.md %} +{% include_cached {{page.version.version}}/app/see-also-links.md %} diff --git a/src/current/v24.2/build-a-python-app-with-cockroachdb-sqlalchemy.md b/src/current/v24.2/build-a-python-app-with-cockroachdb-sqlalchemy.md index b50f73477af..73e5dfa528b 100644 --- a/src/current/v24.2/build-a-python-app-with-cockroachdb-sqlalchemy.md +++ b/src/current/v24.2/build-a-python-app-with-cockroachdb-sqlalchemy.md @@ -105,7 +105,7 @@ This tutorial uses [`virtualenv`](https://virtualenv.pypa.io) for dependency man `main.py` uses the connection string saved to the `DATABASE_URL` environment variable to connect to your cluster and execute the code. {{site.data.alerts.callout_info}} -The example application uses the general connection string, which begins with `postgresql://` but modifies it so it uses the `cockroachdb://` prefix. It does this so SQLAlchemy will use the CockroachDB SQLAlchemy adapter. +The example application uses the general connection string, which begins with `postgresql://` but modifies it so it uses the `cockroachdb://` prefix. It does this so SQLAlchemy will use the CockroachDB SQLAlchemy adapter. {% include_cached copy-clipboard.html %} ~~~ python @@ -224,7 +224,7 @@ SQLAlchemy relies on the existence of [foreign keys]({% link {{ page.version.ver - The [SQLAlchemy](https://docs.sqlalchemy.org/) docs - [Transactions]({% link {{ page.version.version }}/transactions.md %}) -{% include {{page.version.version}}/app/see-also-links.md %} +{% include_cached {{page.version.version}}/app/see-also-links.md %} {% comment %} Reference Links {% endcomment %} diff --git a/src/current/v24.2/build-a-python-app-with-cockroachdb.md b/src/current/v24.2/build-a-python-app-with-cockroachdb.md index b27d70c7798..6d75ab3394d 100644 --- a/src/current/v24.2/build-a-python-app-with-cockroachdb.md +++ b/src/current/v24.2/build-a-python-app-with-cockroachdb.md @@ -100,4 +100,4 @@ For other ways to install psycopg2, see the [official documentation](http://init Read more about using the [Python psycopg2 driver](https://www.psycopg.org/docs/). -{% include {{page.version.version}}/app/see-also-links.md %} +{% include_cached {{page.version.version}}/app/see-also-links.md %} diff --git a/src/current/v24.2/build-a-ruby-app-with-cockroachdb-activerecord.md b/src/current/v24.2/build-a-ruby-app-with-cockroachdb-activerecord.md index 5182c6bf39c..4a7b6bd8b49 100644 --- a/src/current/v24.2/build-a-ruby-app-with-cockroachdb-activerecord.md +++ b/src/current/v24.2/build-a-ruby-app-with-cockroachdb-activerecord.md @@ -103,4 +103,4 @@ git clone https://github.com/cockroachlabs/example-app-ruby-activerecord Read more about using [Active Record](http://guides.rubyonrails.org/active_record_basics.html), or check out a more realistic implementation of Active Record with CockroachDB in a Rails app in our [`examples-orms`](https://github.com/cockroachdb/examples-orms) repository. -{% include {{page.version.version}}/app/see-also-links.md %} +{% include_cached {{page.version.version}}/app/see-also-links.md %} diff --git a/src/current/v24.2/build-a-ruby-app-with-cockroachdb.md b/src/current/v24.2/build-a-ruby-app-with-cockroachdb.md index dcab62e0b16..cf924102f54 100644 --- a/src/current/v24.2/build-a-ruby-app-with-cockroachdb.md +++ b/src/current/v24.2/build-a-ruby-app-with-cockroachdb.md @@ -107,4 +107,4 @@ The code connects as the user you created and executes some basic SQL statements Read more about using the [Ruby pg driver](https://rubygems.org/gems/pg). -{% include {{page.version.version}}/app/see-also-links.md %} +{% include_cached {{page.version.version}}/app/see-also-links.md %} diff --git a/src/current/v24.2/build-a-spring-app-with-cockroachdb-jdbc.md b/src/current/v24.2/build-a-spring-app-with-cockroachdb-jdbc.md index 1080c5dbaeb..ccae12a8c4a 100644 --- a/src/current/v24.2/build-a-spring-app-with-cockroachdb-jdbc.md +++ b/src/current/v24.2/build-a-spring-app-with-cockroachdb-jdbc.md @@ -35,7 +35,7 @@ Choose whether to run a local cluster or a free CockroachDB {{ site.data.product ### Create a free trial cluster -{% include cockroachcloud/quickstart/create-free-trial-standard-cluster.md %} +{% include_cached cockroachcloud/quickstart/create-free-trial-standard-cluster.md %} ### Set up your cluster connection diff --git a/src/current/v24.2/build-a-spring-app-with-cockroachdb-jpa.md b/src/current/v24.2/build-a-spring-app-with-cockroachdb-jpa.md index 27b676716b5..3d1c1951792 100644 --- a/src/current/v24.2/build-a-spring-app-with-cockroachdb-jpa.md +++ b/src/current/v24.2/build-a-spring-app-with-cockroachdb-jpa.md @@ -31,7 +31,7 @@ Choose whether to run a local cluster or a free CockroachDB {{ site.data.product ### Create a free trial cluster -{% include cockroachcloud/quickstart/create-free-trial-standard-cluster.md %} +{% include_cached cockroachcloud/quickstart/create-free-trial-standard-cluster.md %} ### Set up your cluster connection diff --git a/src/current/v24.2/build-a-typescript-app-with-cockroachdb.md b/src/current/v24.2/build-a-typescript-app-with-cockroachdb.md index afa91694763..fe9eceff74f 100644 --- a/src/current/v24.2/build-a-typescript-app-with-cockroachdb.md +++ b/src/current/v24.2/build-a-typescript-app-with-cockroachdb.md @@ -131,4 +131,4 @@ Printing balances from account 4e26653a-3821-48c8-a481-47eb73b3e4cc. Read more about using the [TypeORM](https://typeorm.io/#/). -{% include {{page.version.version}}/app/see-also-links.md %} +{% include_cached {{page.version.version}}/app/see-also-links.md %} From 0d1d19f310314607709a465e762c501e00d0fbc8 Mon Sep 17 00:00:00 2001 From: Matt Linville Date: Tue, 20 Aug 2024 12:16:11 -0700 Subject: [PATCH 03/11] Edit some common includes --- .../_includes/cockroachcloud/download-the-cert-free.md | 8 ++++---- .../quickstart/create-free-trial-standard-cluster.md | 9 ++++----- src/current/cockroachcloud/quickstart.md | 2 +- 3 files changed, 9 insertions(+), 10 deletions(-) diff --git a/src/current/_includes/cockroachcloud/download-the-cert-free.md b/src/current/_includes/cockroachcloud/download-the-cert-free.md index 29626da8930..658183c9a44 100644 --- a/src/current/_includes/cockroachcloud/download-the-cert-free.md +++ b/src/current/_includes/cockroachcloud/download-the-cert-free.md @@ -2,7 +2,7 @@ {% include_cached copy-clipboard.html %} ~~~ shell - curl --create-dirs -o ~/.postgresql/root.crt -O https://cockroachlabs.cloud/clusters//cert + curl --create-dirs -o ~/.postgresql/root.crt -O https://cockroachlabs.cloud/clusters/{cluster-id}/cert ~~~ Your `cert` file will be downloaded to `~/.postgresql/root.crt`. @@ -13,7 +13,7 @@ {% include_cached copy-clipboard.html %} ~~~ shell - curl --create-dirs -o ~/.postgresql/root.crt -O https://cockroachlabs.cloud/clusters//cert + curl --create-dirs -o ~/.postgresql/root.crt -O https://cockroachlabs.cloud/clusters/{cluster-id}/cert ~~~ Your `cert` file will be downloaded to `~/.postgresql/root.crt`. @@ -23,8 +23,8 @@
{% include_cached copy-clipboard.html %} - ~~~ shell - mkdir -p $env:appdata\.postgresql\; Invoke-WebRequest -Uri https://cockroachlabs.cloud/clusters//cert -OutFile $env:appdata\.postgresql\root.crt + ~~~ powershell + mkdir -p $env:appdata\.postgresql\; Invoke-WebRequest -Uri https://cockroachlabs.cloud/clusters/{cluster-id}/cert -OutFile $env:appdata\.postgresql\root.crt ~~~ Your `cert` file will be downloaded to `%APPDATA%/.postgresql/root.crt`. diff --git a/src/current/_includes/cockroachcloud/quickstart/create-free-trial-standard-cluster.md b/src/current/_includes/cockroachcloud/quickstart/create-free-trial-standard-cluster.md index b3ffc85f1a2..00e04c0fb3f 100644 --- a/src/current/_includes/cockroachcloud/quickstart/create-free-trial-standard-cluster.md +++ b/src/current/_includes/cockroachcloud/quickstart/create-free-trial-standard-cluster.md @@ -2,11 +2,10 @@ After the free trial details are finalized, add a link to free trial page to check for free trial eligibility. {% endcomment %} -1. If you haven't already, sign up for a CockroachDB {{ site.data.products.cloud }} account. -1. [Log in](https://cockroachlabs.cloud/) to your CockroachDB {{ site.data.products.cloud }} account. +1. Create a [CockroachDB {{ site.data.products.cloud }}](https://cockroachlabs.cloud/signup?referralId={{page.referral_id}}) account and log in. 1. On the **Clusters** page, click **Create cluster**. 1. On the **Select a plan** page, select **Standard**. -1. On the **Cloud & Regions** page, select a cloud provider (GCP or AWS) in the **Cloud provider** section. +1. On the **Cloud & Regions** page, select a cloud provider (GCP or AWS) in the **Cloud provider** section. 1. In the **Regions** section, select a region for the cluster. Refer to [CockroachDB {{ site.data.products.cloud }} Regions]({% link cockroachcloud/regions.md %}) for the regions where CockroachDB {{ site.data.products.standard }} clusters can be deployed. To create a multi-region cluster, click **Add region** and select additional regions. 1. Click **Next: Capacity**. 1. On the **Capacity** page, keep the **Provisioned capacity** at the default value of 1000 RUs/second. @@ -14,7 +13,7 @@ After the free trial details are finalized, add a link to free trial page to che Click **Next: Finalize**. 1. On the **Finalize** page, name your cluster. If applicable, the 30-day trial code is pre-applied to your cluster. - + 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 + Your cluster will be created in a few seconds and the **Create SQL user** dialog will display. diff --git a/src/current/cockroachcloud/quickstart.md b/src/current/cockroachcloud/quickstart.md index fdad6aa548d..be48f57edab 100644 --- a/src/current/cockroachcloud/quickstart.md +++ b/src/current/cockroachcloud/quickstart.md @@ -11,7 +11,7 @@ This page shows you how to deploy a CockroachDB cluster on CockroachDB {{ site.d ## Create a free trial cluster -{% include cockroachcloud/quickstart/create-free-trial-standard-cluster.md %} +{% include_cached cockroachcloud/quickstart/create-free-trial-standard-cluster.md %} ## Create a SQL user From 6961cae6f84642723e44c3adb0b98c1c0307c218 Mon Sep 17 00:00:00 2001 From: Matt Linville Date: Tue, 20 Aug 2024 12:12:22 -0700 Subject: [PATCH 04/11] Update Lambda and serverless pages for Cloud 2.0 --- src/current/v24.2/deploy-lambda-function.md | 156 +++++++----------- .../serverless-function-best-practices.md | 28 ++-- 2 files changed, 74 insertions(+), 110 deletions(-) diff --git a/src/current/v24.2/deploy-lambda-function.md b/src/current/v24.2/deploy-lambda-function.md index a5c083a0d4f..a4f507021ed 100644 --- a/src/current/v24.2/deploy-lambda-function.md +++ b/src/current/v24.2/deploy-lambda-function.md @@ -13,48 +13,37 @@ This tutorial shows you how to create an [AWS Lambda](https://aws.amazon.com/lam Before starting the tutorial, do the following: -1. Create a [CockroachDB {{ site.data.products.cloud }}](https://cockroachlabs.cloud/signup?referralId={{page.referral_id}}) account. - -1. Create an [AWS](https://aws.amazon.com/) account. - -1. Create an [AWS user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html) with administrator permissions. - -1. Install the [AWS CLI](https://aws.amazon.com/cli/). +1. Create an [AWS](https://aws.amazon.com/) account and log in, then: + 1. Create an [AWS user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html) with administrator permissions. + 1. Install the [AWS CLI](https://aws.amazon.com/cli/) and log in locally. ## Step 1. Create a CockroachDB {{ site.data.products.standard }} cluster -{% include cockroachcloud/quickstart/create-free-trial-standard-cluster.md %} - - +{% include_cached cockroachcloud/quickstart/create-free-trial-standard-cluster.md %} -After the cluster is created, the **Connection info** window appears. Click the **Connection string** tab and copy the connection string to a secure location. You will use this connection string to connect to CockroachDB later in the tutorial. +{% include_cached cockroachcloud/connection-string-standard.md %} -{{site.data.alerts.callout_info}} -The connection string is pre-populated with your username, cluster name, and other details, including your password. Your password, in particular, will be provided only once. Save it in a secure place (we recommend a password manager) to connect to your cluster in the future. If you forget your password, you can reset it by going to the **SQL Users** page for the cluster, found at `https://cockroachlabs.cloud/cluster//users`. -{{site.data.alerts.end}} +## Step 2. Get the code -## Step 2. Get the sample code - -Open a terminal window and clone the [sample code's GitHub repo](https://github.com/cockroachlabs/examples-aws-lambda): +In a terminal, clone the [sample code's GitHub repo](https://github.com/cockroachlabs/examples-aws-lambda): {% include_cached copy-clipboard.html %} ~~~ shell -$ git clone https://github.com/cockroachlabs/examples-aws-lambda +git clone https://github.com/cockroachlabs/examples-aws-lambda ~~~ -This repo includes samples for Node.js and Python [Lambda runtimes](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html). +This repo includes samples for Node.js and Python [Lambda runtimes](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html). Select either node.js or Python to continue.
- +
-The Node.js function code is available under the `examples-aws-lambda/node` directory: +The Node.js function code is located in the `examples-aws-lambda/node` directory and has the following structure: ~~~ shell -. ├── README.md ├── deployment-package.zip ## Lambda deployment package ├── index.js ## Lambda function source code @@ -62,16 +51,15 @@ The Node.js function code is available under the `examples-aws-lambda/node` dire └── package.json ## Dependencies ~~~ -This function uses the [node-postgres](https://node-postgres.com/) modules to connect to CockroachDB. +The Lambda function uses the [node-postgres](https://node-postgres.com/) modules to connect to your cluster.
-The Python function's code is available under the `examples-aws-lambda/python` directory: +The Python function code is located in the `examples-aws-lambda/python` directory and has the following structure: ~~~ shell -. ├── README.md ├── deployment-package.zip ## Lambda deployment package ├── init_db.py ## Lambda function source code @@ -80,81 +68,54 @@ The Python function's code is available under the `examples-aws-lambda/python` d └── root.crt ## CA cert ~~~ -This function uses the [Psycopg2](https://www.psycopg.org/) PostgreSQL adapter to connect to CockroachDB. +The Lambda function uses the [Psycopg2](https://www.psycopg.org/) PostgreSQL adapter to connect to your cluster.
## Step 3. (Optional) Create the deployment package -{{site.data.alerts.callout_info}} -This step is optional, as you do not need to create a new deployment package to deploy the sample function. The `examples-aws-lambda` repo includes deployment packages that are ready to deploy. -{{site.data.alerts.end}} +Creating a deployment package to deploy the sample function is optional. The `examples-aws-lambda` repo includes deployment packages that are ready to deploy.
-1. Navigate to the Node.js function directory: +1. In the `node` directory, install the code dependencies: {% include_cached copy-clipboard.html %} ~~~ shell - cd node + cd node; npm install ~~~ -1. Install the code dependencies: +1. Compress the project files to a ZIP file in the parent directory for deployment: {% include_cached copy-clipboard.html %} ~~~ shell - npm install - ~~~ - -1. Compress the project files to a ZIP file for deployment: - - {% include_cached copy-clipboard.html %} - ~~~ shell - zip -r deployment-package.zip . + zip -r ../my-deployment-package.zip . ~~~
-1. Navigate to the Python function directory: - - {% include_cached copy-clipboard.html %} - ~~~ shell - cd python - ~~~ - -1. Download and install the `psycopg2-binary` Python library to a new directory: +1. In the `python` directory, download and install the `psycopg2-binary` Python library: {% include_cached copy-clipboard.html %} ~~~ shell - $ python3 -m pip install --only-binary :all: --platform manylinux1_x86_64 --target ./my-package -r requirements.txt + cd python; python3 -m pip install \ + --only-binary :all: \ + --platform manylinux1_x86_64 \ + --target ./my-package \ + -r requirements.txt ~~~ - {{site.data.alerts.callout_info}} + {{site.data.alerts.callout_info}} To run on Amazon Linux distributions, `pscyopg2` dependencies must be compiled for Linux. {{site.data.alerts.end}} -1. Compress the project files to a ZIP file for deployment: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cd my-package - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ zip -r ../my-deployment-package.zip . - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cd .. - ~~~ +1. Compress the project files to a ZIP file in the parent directory for deployment: {% include_cached copy-clipboard.html %} ~~~ shell - $ zip -g my-deployment-package.zip init_db.py root.crt + zip -r ../my-deployment-package.zip my-deployment-package ./init_db.py ./root.crt ~~~
@@ -165,25 +126,27 @@ This step is optional, as you do not need to create a new deployment package to {% include_cached copy-clipboard.html %} ~~~ shell - $ aws configure + aws configure ~~~ - Follow the prompts to authenticate as a user with administrator privileges. We do not recommend using the root user. + Follow the prompts to authenticate as a user with administrator privileges. We do not recommend using the `root` user. -1. Create an execution role for the Lambda function and attach the `AWSLambdaBasicExecutionRole` policy to the role: +1. Create an execution role for the Lambda function and attach the `AWSLambdaBasicExecutionRole` policy to the role. The Lambda function needs this role to run. {% include_cached copy-clipboard.html %} ~~~ shell - $ aws iam create-role --role-name lambda-ex --assume-role-policy-document '{"Version": "2012-10-17","Statement": [{ "Effect": "Allow", "Principal": {"Service": "lambda.amazonaws.com"}, "Action": "sts:AssumeRole"}]}' + aws iam create-role \ + --role-name lambda-ex \ + --assume-role-policy-document '{"Version": "2012-10-17","Statement": [{ "Effect": "Allow", "Principal": {"Service": "lambda.amazonaws.com"}, "Action": "sts:AssumeRole"}]}' ~~~ {% include_cached copy-clipboard.html %} ~~~ shell - $ aws iam attach-role-policy --role-name lambda-ex --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole + aws iam attach-role-policy \ + --role-name lambda-ex \ + --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole ~~~ - The Lambda function needs this role to run. - ## Step 5. Deploy the function to AWS Lambda 1. In the deployment package directory, use the AWS CLI to create a Lambda function: @@ -192,14 +155,14 @@ This step is optional, as you do not need to create a new deployment package to {% include_cached copy-clipboard.html %} ~~~ shell - $ aws lambda create-function \ - --function-name init-crdb \ - --region \ - --zip-file fileb://deployment-package.zip \ - --handler index.handler \ - --runtime nodejs14.x \ - --role arn:aws:iam:::role/lambda-ex \ - --environment "Variables={DATABASE_URL=}" + aws lambda create-function \ + --function-name init-crdb \ + --region \ + --zip-file fileb://deployment-package.zip \ + --handler index.handler \ + --runtime nodejs14.x \ + --role arn:aws:iam:::role/lambda-ex \ + --environment "Variables={DATABASE_URL=}" ~~~
@@ -208,14 +171,14 @@ This step is optional, as you do not need to create a new deployment package to {% include_cached copy-clipboard.html %} ~~~ shell - $ aws lambda create-function \ - --function-name init-crdb \ - --region \ - --zip-file fileb://deployment-package.zip \ - --handler init_db.lambda_handler \ - --runtime python3.9 \ - --role arn:aws:iam:::role/lambda-ex \ - --environment "Variables={DATABASE_URL=,PGSSLROOTCERT=./root.crt}" + aws lambda create-function \ + --function-name init-crdb \ + --region \ + --zip-file fileb://deployment-package.zip \ + --handler init_db.lambda_handler \ + --runtime python3.9 \ + --role arn:aws:iam:::role/lambda-ex \ + --environment "Variables={DATABASE_URL=,PGSSLROOTCERT=./root.crt}" ~~~ @@ -228,7 +191,7 @@ This step is optional, as you do not need to create a new deployment package to
{{site.data.alerts.callout_info}} - To connect to a CockroachDB {{ site.data.products.standard }} cluster with Psycopg2, you must provide the client with a valid CA certificate. By default, Pscyopg2 searches for the certificate at ~/.postgresql/root.crt, or in the environment variable `PGSSLROOTCERT`. + To connect to a CockroachDB {{ site.data.products.standard }} cluster with Psycopg2, you must provide the client with a valid CA certificate. By default, Pscyopg2 searches for the certificate at `~/.postgresql/root.crt` and in the location point to by the environment variable `PGSSLROOTCERT`. {{site.data.alerts.end}}
@@ -237,8 +200,11 @@ This step is optional, as you do not need to create a new deployment package to {% include_cached copy-clipboard.html %} ~~~ shell - $ aws lambda invoke --function-name init-crdb out --log-type Tail \ - --query 'LogResult' --output text | base64 -d + aws lambda invoke \ + --function-name init-crdb out \ + --log-type Tail \ + --query 'LogResult' \ + --output text | base64 -d ~~~ ~~~ @@ -258,6 +224,6 @@ This step is optional, as you do not need to create a new deployment package to ## See also - [Build a Simple Django App with CockroachDB]({% link {{ page.version.version }}/build-a-python-app-with-cockroachdb-django.md %}) -- [Deploy a Global, Serverless Application]({% link {{ page.version.version }}/movr-flask-deployment.md %}) +- [Deploy a Global Serverless Application]({% link {{ page.version.version }}/movr-flask-deployment.md %}) -{% include {{page.version.version}}/app/see-also-links.md %} +{% include_cached {{page.version.version}}/app/see-also-links.md %} diff --git a/src/current/v24.2/serverless-function-best-practices.md b/src/current/v24.2/serverless-function-best-practices.md index a61d85ebab7..612c8335970 100644 --- a/src/current/v24.2/serverless-function-best-practices.md +++ b/src/current/v24.2/serverless-function-best-practices.md @@ -1,30 +1,28 @@ --- title: Serverless Function Best Practices -summary: Best practices for optimizing the performance of serverless functions (e.g., AWS Lambda functions or Google Cloud Functions) that connect to CockroachDB. +summary: Best practices for optimizing the performance of serverless functions that connect to CockroachDB, such AWS Lambda functions or Google Cloud Functions. toc: true referral_id: docs_serverless_functions docs_area: get_started --- -This page provides best practices for optimizing the performance of serverless functions (e.g., [AWS Lambda functions](https://aws.amazon.com/lambda) and [Google Cloud Functions](https://cloud.google.com/functions)) that connect to CockroachDB. +This page provides best practices for optimizing the performance of serverless functions that connect to CockroachDB, such as [AWS Lambda functions](https://aws.amazon.com/lambda) and [Google Cloud Functions](https://cloud.google.com/functions). -## Use connection pools +## Use connection pools that persist across function invocations -Use connection pools to manage the lifecycle of database connections established by serverless functions. Connection pools health-check connections and re-establish broken connections in the event of a communication error. +Use [connection pools]({% link {{ page.version.version }}/connection-pooling.md %}) to manage the lifecycle of database connections established by serverless functions. Connection pools check connection health and re-establish broken connections in the event of a communication error. When creating connection pools in serverless functions: - Set the maximum connection pool size to 1, unless your function is multi-threaded and establishes multiple concurrent requests to your database within a single function instance. - - Do not set a minimum idle connection count. The connection pool should be free to open connections as needed. - - If supported by your pooling library, set the maximum lifetime on the connection pool to 30 minutes. -## Persist connection pools across function invocations +If you plan to invoke a serverless function frequently, configure the function to persist connection pools across function invocations. This helps to limit the number of new connection attempts to the cluster. One way to do this is to initialize the connection pool variable outside the scope of the serverless function definition. -If you plan to invoke a serverless function at a high frequency, you should configure the function to persist connection pools across function invocations, to limit the number of new connection attempts to the database. This is typically done by initializing the connection pool variable outside the scope of the serverless function definition. +For example if an AWS Lambda function uses [`INSERT`]({% link {{ page.version.version }}/insert.md %}) to add data to a table and runs every few seconds, initialize the connection pool variable outside of the [handler function](https://docs.aws.amazon.com/lambda/latest/dg/foundation-progmodel.html) definition, then define the connection pool in the handler only if the pool does not already exist. -For example, suppose you are writing an AWS Lambda function that [`INSERT`]({% link {{ page.version.version }}/insert.md %})s data into a table on a CockroachDB cluster, and you plan to run this query every few seconds. To persist a connection pool across invocations, initialize the connection pool variable outside of the [handler function](https://docs.aws.amazon.com/lambda/latest/dg/foundation-progmodel.html) definition and then define the connection pool in the handler only if the pool does not already exist. +Select either node.js or Python to continue.
@@ -33,7 +31,7 @@ For example, suppose you are writing an AWS Lambda function that [`INSERT`]({% l
-A node.JS function that implements this pattern could look similar to the following: +The following node.js code implements this pattern: {% include_cached copy-clipboard.html %} ~~~ js @@ -69,7 +67,7 @@ exports.handler = async (context) => {
-A Python function that implements this pattern could look similar to the following: +The following Python code implements this pattern: {% include_cached copy-clipboard.html %} ~~~ python @@ -99,15 +97,15 @@ def lambda_handler(context): ## Use CockroachDB {{ site.data.products.standard }} -As a database-as-a-service, CockroachDB {{ site.data.products.standard }} abstracts away the complexity of deploying, scaling, and load-balancing your database. Additionally, idle database connections to CockroachDB use very little memory (~20-30 KiB) when compared to PostgreSQL (~2-10 MiB). +As a database-as-a-service, CockroachDB {{ site.data.products.standard }} abstracts away the complexity of deploying, scaling, and load-balancing your database. To create a free CockroachDB {{ site.data.products.standard }} cluster: -{% include cockroachcloud/quickstart/create-free-trial-standard-cluster.md %} +{% include_cached cockroachcloud/quickstart/create-free-trial-standard-cluster.md %} -## Deploy serverless functions in the same region as your database +## Deploy serverless functions in the same region as your cluster -To minimize network latency, you should deploy your serverless functions in the same region as your database deployment. If your serverless function provider does not offer deployments in the same region as your database deployment, choose the region closest to the region where your database is deployed. +To minimize network latency, you should deploy your serverless functions in the same region as your cluster. If your serverless function provider does not offer deployments in the same region as your database deployment, choose the region nearest to the region where your database is deployed. ## See also From bcfd87eed086b8e9329b78bd2eec963cba851c87 Mon Sep 17 00:00:00 2001 From: Matt Linville Date: Tue, 20 Aug 2024 12:13:06 -0700 Subject: [PATCH 05/11] Update GCR tutorial for Cloud 2.0 --- src/current/v24.2/deploy-app-gcr.md | 103 ++++++++++++++-------------- 1 file changed, 50 insertions(+), 53 deletions(-) diff --git a/src/current/v24.2/deploy-app-gcr.md b/src/current/v24.2/deploy-app-gcr.md index eeca4c16f8b..d7610d5aa3c 100644 --- a/src/current/v24.2/deploy-app-gcr.md +++ b/src/current/v24.2/deploy-app-gcr.md @@ -13,14 +13,13 @@ This tutorial shows you how to use Google Cloud Run to deploy a containerized Dj Before starting the tutorial, do the following: -1. Create a [CockroachDB {{ site.data.products.cloud }}](https://cockroachlabs.cloud/signup?referralId={{page.referral_id}}) account. -1. Create a [Google Cloud](https://cloud.google.com/) account. +1. Create a [Google Cloud](https://cloud.google.com/) account and log in. 1. Install the [Google Cloud SDK](https://cloud.google.com/sdk). 1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop). ## Step 1. Create a CockroachDB {{ site.data.products.standard }} cluster -{% include cockroachcloud/quickstart/create-free-trial-standard-cluster.md %} +{% include_cached cockroachcloud/quickstart/create-free-trial-standard-cluster.md %} ## Step 2. Set up your cluster connection @@ -28,16 +27,16 @@ Before starting the tutorial, do the following: ## Step 3. Create a database -1. If you haven't already, [download the CockroachDB binary]({% link {{ page.version.version }}/install-cockroachdb.md %}). +1. If you haven't already, [download the CockroachDB SQL Shell binary]({% link {{ page.version.version }}/install-cockroachdb.md %}). 1. Start the [built-in SQL shell]({% link {{ page.version.version }}/cockroach-sql.md %}) using the connection string you got from the CockroachDB {{ site.data.products.cloud }} Console earlier: {% include_cached copy-clipboard.html %} ~~~ shell - $ cockroach sql \ - --url='postgres://:@:26257/defaultdb?sslmode=verify-full&sslrootcert=/cc-ca.crt' + cockroach sql \ + --url='postgres://:@:26257/defaultdb?sslmode=verify-full&sslrootcert={certs_dir}/cc-ca.crt' ~~~ - In the connection string copied from the CockroachDB {{ site.data.products.cloud }} Console, your username, password and cluster name are pre-populated. Replace the `` placeholder with the path to the `certs` directory that you created earlier. + In the connection string copied from the CockroachDB {{ site.data.products.cloud }} Console, your username, password and cluster name are pre-populated. Replace the `{certs_dir}` placeholder with the path to the `certs` directory that you created earlier. 1. In the SQL shell, create the `bank` database that your application will use: @@ -55,14 +54,14 @@ Before starting the tutorial, do the following: ## Step 4. Get the application code -1. Clone the code's GitHub repo: +1. Clone the example code's GitHub repo: {% include_cached copy-clipboard.html %} ~~~ shell - $ git clone https://github.com/cockroachlabs/example-app-python-django/ + git clone https://github.com/cockroachlabs/example-app-python-django/ ~~~ -1. Create a new folder named `certs` at the top level of the `example-app-python-django` project, and then copy the root certificate that you downloaded for your cluster to the new folder. +1. Create a new directory named `certs` at the top level of the `example-app-python-django` project, and then copy the root certificate that you downloaded for your cluster to the new directory. The project directory structure should look like this: @@ -93,26 +92,26 @@ Before starting the tutorial, do the following: {% include_cached copy-clipboard.html %} ~~~ shell - $ virtualenv env + virtualenv env ~~~ {% include_cached copy-clipboard.html %} ~~~ shell - $ source env/bin/activate + source env/bin/activate ~~~ 1. Install the required modules to the virtual environment: {% include_cached copy-clipboard.html %} ~~~ shell - $ pip install -r requirements.txt + pip install -r requirements.txt ~~~ 1. Set the `DATABASE_URL` environment variable to the connection string provided in the **Connection info** window of the CockroachDB {{ site.data.products.cloud }} Console, but with the root certificate located in the local `certs` directory: {% include_cached copy-clipboard.html %} ~~~ shell - $ export DATABASE_URL="postgresql://$USER:$PASSWORD@random-cluster-name-4300.6wr.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert=root.crt" + export DATABASE_URL="postgresql://$USER:$PASSWORD@random-cluster-name-4300.6wr.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert=root.crt" ~~~ This Django app uses the `dj_database_url` module to configure the database connection from a connection URL. The module uses the value assigned to the `DATABASE_URL` environment variable for the connection. @@ -125,7 +124,7 @@ Before starting the tutorial, do the following: {% include_cached copy-clipboard.html %} ~~~ shell - $ python3 cockroach_example/manage.py migrate + python3 cockroach_example/manage.py migrate ~~~ This migration initializes the `bank` database with the tables defined in `models.py`, in addition to some other tables for the admin functionality included with Django's starter application. @@ -134,7 +133,7 @@ Before starting the tutorial, do the following: {% include_cached copy-clipboard.html %} ~~~ shell - $ python3 cockroach_example/manage.py runserver 0.0.0.0:8000 + python3 cockroach_example/manage.py runserver 0.0.0.0:8000 ~~~ The output should look like this: @@ -151,9 +150,9 @@ Before starting the tutorial, do the following: {% include_cached copy-clipboard.html %} ~~~ shell - $ curl --header "Content-Type: application/json" \ - --request POST \ - --data '{"name":"Carl"}' http://0.0.0.0:8000/customer/ + curl --header "Content-Type: application/json" \ + --request POST \ + --data '{"name":"Carl"}' http://0.0.0.0:8000/customer/ ~~~ This request inserts a new row into the `cockroach_example_customers` table. @@ -162,7 +161,7 @@ Before starting the tutorial, do the following: {% include_cached copy-clipboard.html %} ~~~ shell - $ curl http://0.0.0.0:8000/customer/ + curl http://0.0.0.0:8000/customer/ ~~~ ~~~ @@ -195,7 +194,7 @@ Before starting the tutorial, do the following: {% include_cached copy-clipboard.html %} ~~~ shell - $ gcloud auth login + gcloud auth login ~~~ Follow the prompts to authenticate. @@ -204,25 +203,25 @@ Before starting the tutorial, do the following: {% include_cached copy-clipboard.html %} ~~~ shell - $ gcloud projects create + gcloud projects create {gcp_project_id} ~~~ {{site.data.alerts.callout_info}} - You can specify a location for the project within your Google Cloud resources with the `--organization` or `--folder` flags. + You can specify a location for the project within your Google Cloud resources by using the `--organization` or `--folder` flags. {{site.data.alerts.end}} 1. Configure the CLI to use your Google Cloud account and the new project ID by default: {% include_cached copy-clipboard.html %} ~~~ shell - $ gcloud init + gcloud init ~~~ 1. Set the `PROJECT_ID` environment variable: {% include_cached copy-clipboard.html %} ~~~ shell - $ export PROJECT_ID= + export PROJECT_ID={gcp_project_id} ~~~ For the rest of the tutorial, we use `PROJECT_ID` to refer to the project ID. @@ -233,7 +232,7 @@ Before starting the tutorial, do the following: {% include_cached copy-clipboard.html %} ~~~ shell - $ docker build -t gcr.io/$PROJECT_ID/crdb-sample:v1 . + docker build -t gcr.io/$PROJECT_ID/crdb-sample:v1 . ~~~ If there are no errors, the container built successfully. @@ -242,21 +241,21 @@ Before starting the tutorial, do the following: {% include_cached copy-clipboard.html %} ~~~ shell - $ gcloud auth configure-docker + gcloud auth configure-docker ~~~ 1. Enable the Container Registry API for the project: {% include_cached copy-clipboard.html %} ~~~ shell - $ gcloud services enable containerregistry.googleapis.com + gcloud services enable containerregistry.googleapis.com ~~~ 1. Push the Docker image to the project's registry. {% include_cached copy-clipboard.html %} ~~~ shell - $ docker push gcr.io/$PROJECT_ID/crdb-sample:v1 + docker push gcr.io/$PROJECT_ID/crdb-sample:v1 ~~~ ## Step 8. Create a secret for the database connection URI @@ -265,26 +264,26 @@ Before starting the tutorial, do the following: {% include_cached copy-clipboard.html %} ~~~ shell - $ gcloud iam service-accounts create cockroach-labs + gcloud iam service-accounts create cockroach-labs ~~~ 1. Enable the Secret Manager API for the project: {% include_cached copy-clipboard.html %} ~~~ shell - $ gcloud services enable secretmanager.googleapis.com + gcloud services enable secretmanager.googleapis.com ~~~ 1. Create a secret for the connection string stored locally in the `DATABASE_URL` environment variable, and bind the new service account to the secret. {% include_cached copy-clipboard.html %} ~~~ shell - $ echo $DATABASE_URL | gcloud secrets create cockroach-connection-uri --data-file=- --replication-policy=automatic + echo $DATABASE_URL | gcloud secrets create cockroach-connection-uri --data-file=- --replication-policy=automatic ~~~ {% include_cached copy-clipboard.html %} ~~~ shell - $ gcloud secrets add-iam-policy-binding cockroach-connection-uri \ + gcloud secrets add-iam-policy-binding cockroach-connection-uri \ --member=serviceAccount:cockroach-labs@${PROJECT_ID}.iam.gserviceaccount.com \ --role=roles/secretmanager.secretAccessor ~~~ @@ -295,17 +294,19 @@ Before starting the tutorial, do the following: {% include_cached copy-clipboard.html %} ~~~ shell - $ gcloud services enable run.googleapis.com + gcloud services enable run.googleapis.com ~~~ 1. Create a [Cloud Run](https://console.cloud.google.com/run/) service for the application: {% include_cached copy-clipboard.html %} ~~~ shell - $ gcloud alpha run deploy crl-app --region us-central1 --allow-unauthenticated \ - --service-account=cockroach-labs@${PROJECT_ID}.iam.gserviceaccount.com \ - --set-secrets="DATABASE_URL=cockroach-connection-uri:latest" \ - --image=gcr.io/${PROJECT_ID}/crdb-sample:v1 + gcloud alpha run deploy crl-app \ + --region us-central1 \ + --allow-unauthenticated \ + --service-account "cockroach-labs@${PROJECT_ID}.iam.gserviceaccount.com" \ + --set-secrets "DATABASE_URL=cockroach-connection-uri:latest" \ + --image gcr.io/${PROJECT_ID}/crdb-sample:v1 ~~~ Note the following: @@ -316,26 +317,22 @@ Before starting the tutorial, do the following: If prompted, select `Cloud Run (fully managed)`. -After the revision is deployed, you should be able to send requests to the application from a browser, or using a REST client (e.g., `curl`). For example: +1. After the revision is deployed, verify that you can send requests to the application from a browser or a REST client: -{% include_cached copy-clipboard.html %} -~~~ shell -$ curl https:///customer/ -~~~ - -~~~ -[{"id": "bb7d6c4d-efb3-45f8-b790-9911aae7d8b2", "name": "Carl"}] -~~~ + {% include_cached copy-clipboard.html %} + ~~~ shell + curl https:///customer/ + ~~~ -{{site.data.alerts.callout_danger}} -By default, the sample application allows all hosts/domain names to serve the application. + ~~~ + [{"id": "bb7d6c4d-efb3-45f8-b790-9911aae7d8b2", "name": "Carl"}] + ~~~ -After testing, we recommend that you update the [`ALLOWED_HOSTS` property in `settings.py`](https://docs.djangoproject.com/en/3.2/ref/settings/#allowed-hosts) to allow only a local testing URL and the Cloud Run service URL to serve the application. -{{site.data.alerts.end}} +1. By default, the sample application allows all hosts/domain names to serve the application. After testing, we recommend that you update the [`ALLOWED_HOSTS` property in `settings.py`](https://docs.djangoproject.com/en/3.2/ref/settings/#allowed-hosts) to allow only a local testing URL and the Cloud Run service URL to serve the application. ## See also - [Build a Simple Django App with CockroachDB]({% link {{ page.version.version }}/build-a-python-app-with-cockroachdb-django.md %}) -- [Deploy a Global, Serverless Application]({% link {{ page.version.version }}/movr-flask-deployment.md %}) +- [Deploy a Global Serverless Application]({% link {{ page.version.version }}/movr-flask-deployment.md %}) -{% include {{page.version.version}}/app/see-also-links.md %} +{% include_cached {{page.version.version}}/app/see-also-links.md %} From f894642de6a80158dcef451da3ab0cef5106e1ba Mon Sep 17 00:00:00 2001 From: Matt Linville Date: Tue, 20 Aug 2024 12:13:35 -0700 Subject: [PATCH 06/11] Update Netlify tutorial for Cloud 2.0 --- src/current/v24.2/deploy-app-netlify.md | 125 +++++++++--------------- 1 file changed, 47 insertions(+), 78 deletions(-) diff --git a/src/current/v24.2/deploy-app-netlify.md b/src/current/v24.2/deploy-app-netlify.md index 407d94bff12..04861487ed1 100644 --- a/src/current/v24.2/deploy-app-netlify.md +++ b/src/current/v24.2/deploy-app-netlify.md @@ -9,73 +9,60 @@ docs_area: get_started This tutorial shows you how to deploy a [Netlify](https://www.netlify.com/) web application that communicates with a CockroachDB {{ site.data.products.standard }} cluster. -The sample app used in this tutorial simulates [a gaming leaderboard](https://www.cockroachlabs.com/blog/react-typescript-cockroachdb-sample-app/). The [Netlify functions](https://www.netlify.com/products/functions/) used for the app are written in TypeScript. The functions use [Prisma](https://www.prisma.io/) to connect to CockroachDB. The app's frontend, also written in TypeScript, uses React, bootstrapped with [Create React App](https://github.com/facebook/create-react-app). +The sample app used in this tutorial simulates a [gaming leaderboard](https://www.cockroachlabs.com/blog/react-typescript-cockroachdb-sample-app/) using [Netlify functions](https://www.netlify.com/products/functions/) written in TypeScript. The functions use [Prisma](https://www.prisma.io/) to connect to CockroachDB. The app's frontend, also written in TypeScript, uses React, bootstrapped with [Create React App](https://github.com/facebook/create-react-app). -The source code for the completed app is available on GitHub at [https://github.com/cockroachdb/cockroachdb-typescript](https://github.com/cockroachdb/cockroachdb-typescript). +You can view or download the [source code](https://github.com/cockroachdb/cockroachdb-typescript) for the example. ## Before you begin -Before starting the tutorial, do the following: +Before starting the tutorial: -1. Create a [CockroachDB {{ site.data.products.cloud }}](https://cockroachlabs.cloud/signup?referralId={{page.referral_id}}) account. - -1. Create a Starter [Netlify](https://app.netlify.com/signup) account. You can do this with your GitHub login credentials. +1. Create a Starter [Netlify](https://app.netlify.com/signup) account. +1. Install the `netlify` CLI locally and log in. Refer to [Get started with Netlify CLI](https://docs.netlify.com/cli/get-started/). ## Step 1. Create a CockroachDB {{ site.data.products.standard }} cluster -{% include cockroachcloud/quickstart/create-free-trial-standard-cluster.md %} - - +{% include_cached cockroachcloud/quickstart/create-free-trial-standard-cluster.md %} -After the cluster is created, the **Connection info** window appears. Click the **Connection string** tab and copy the connection string to a secure location. You will use this connection string to connect to CockroachDB later in the tutorial. - -{{site.data.alerts.callout_info}} -The connection string is pre-populated with your username, cluster name, and other details, including your password. Your password, in particular, will be provided only once. Save it in a secure place (we recommend a password manager) to connect to your cluster in the future. If you forget your password, you can reset it by going to the **SQL Users** page for the cluster, found at `https://cockroachlabs.cloud/cluster//users`. -{{site.data.alerts.end}} +{% include_cached cockroachcloud/connection-string-standard.md %} ## Step 2. Get the code -1. Clone the code's GitHub repo: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ git clone git@github.com:cockroachdb/cockroachdb-typescript.git - ~~~ - - The project has the following directory structure: - - ~~~ - ├── LICENSE.md - ├── README.md - ├── netlify - │   └── functions - │   ├── addScore.ts - │   ├── getPlayers.ts - │   └── getScores.ts - ├── package-lock.json - ├── package.json - ├── prisma - │   ├── schema.prisma - │   └── seed.ts - ├── public - ├── src - └── tsconfig.json - ~~~ - - In this tutorial, we focus on the files in the `netlify` and `prisma` directories. - -1. At the top of the repo directory, fork the repo: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ gh repo fork --remote - ~~~ - - To deploy your code to Netlify, you need to have your own repo or your own fork of the existing repo. +1. Open the code repository's [GitHub repository](https://github.com/cockroachdb/cockroachdb-typescript). +1. Fork it by clicking **Fork** at the top. Netlify requires you to own a Netlify app's repository. + - Set **Owner** to your GitHub identity or an organization. + - Disable **Copy the master branch only**. + - Click **Fork**. + + You now have an exact copy of the code repository in the GitHub location you chose. +1. Copy the fork's address, which you will use to clone it locally. Click **Code**, then in the **Local** tab, click **SSH** if you have added SSH keys to GitHub, or **HTTPS** if not. Click the copy symbol to copy the address. +1. Clone your fork locally. Replace `{ADDRESS}` with the full address of your fork, which will end with `cockroachdb-typescript.git`. + +The project has the following directory structure: + +~~~ +├── LICENSE.md +├── README.md +├── netlify +│   └── functions +│   ├── addScore.ts +│   ├── getPlayers.ts +│   └── getScores.ts +├── package-lock.json +├── package.json +├── prisma +│   ├── schema.prisma +│   └── seed.ts +├── public +├── src +└── tsconfig.json +~~~ + +This tutorial modifies the files in the `netlify` and `prisma` directories. ## Step 3. Initialize the database -1. In the `.env` file in your project, set the `DATABASE_URL` environment variable to [the connection string](#connection-string) you obtained earlier from the CockroachDB {{ site.data.products.cloud }} Console: +1. Open the project's `.env` file in a text editor set the `DATABASE_URL` environment variable to [the connection string](#connection-string) you obtained earlier from the CockroachDB {{ site.data.products.cloud }} Console: {% include_cached copy-clipboard.html %} ~~~ text @@ -95,11 +82,9 @@ The connection string is pre-populated with your username, cluster name, and oth {% include_cached copy-clipboard.html %} ~~~ shell - $ npx prisma migrate dev --name init + npx prisma migrate dev --name init ~~~ - You should see the following output: - ~~~ Your database is now in sync with your schema. ✔ Generated Prisma Client (3.11.0 | library) to ./node_modules/@prisma/client in 87ms @@ -118,31 +103,15 @@ The connection string is pre-populated with your username, cluster name, and oth ## Step 4. Deploy the application -You can deploy web applications directly from GitHub to Netlify. In this tutorial, we use the [Netlify CLI](https://docs.netlify.com/cli/get-started/) to deploy the app. +You can deploy web applications directly from GitHub to Netlify. This tutorial uses the [Netlify CLI](https://docs.netlify.com/cli/get-started/) to deploy the app. -1. Install the `netlify` CLI: +1. Using the Netlify CLI, start the app server locally to preview your site: {% include_cached copy-clipboard.html %} ~~~ shell - $ npm install netlify-cli -g + netlify dev ~~~ -1. Sign into your Netlify account: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ netlify login - ~~~ - -1. Run the app server locally to preview your site: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ netlify dev - ~~~ - - If the local deployment succeeds, you should see the following message in your terminal: - ~~~ ┌─────────────────────────────────────────────────┐ │ │ @@ -162,10 +131,10 @@ You can deploy web applications directly from GitHub to Netlify. In this tutoria {% include_cached copy-clipboard.html %} ~~~ shell - $ netlify deploy + netlify deploy ~~~ - Choose to create a new site, and then select the default options for each of the subsequent prompts. You will be required to authorize Netlify with GitHub. + Choose to create a new site, and then select the default options for each of the subsequent prompts. You will be required to log in to Netlify using GitHub. After the app is deployed, you should see the following message: @@ -177,7 +146,7 @@ You can deploy web applications directly from GitHub to Netlify. In this tutoria {% include_cached copy-clipboard.html %} ~~~ shell - $ netlify open + netlify open ~~~ From the **Site overview** page, you can manage your site. The **Site overview** page also provides you with a public URL for your site. @@ -187,4 +156,4 @@ You can deploy web applications directly from GitHub to Netlify. In this tutoria - [How to build a Complete Webapp with React, TypeScript & CockroachDB](https://www.cockroachlabs.com/blog/react-typescript-cockroachdb-sample-app/#deploy-the-application-to-netlify) - [Build a Simple CRUD Node.js App with CockroachDB and Prisma Client]({% link {{ page.version.version }}/build-a-nodejs-app-with-cockroachdb-prisma.md %}) -{% include {{page.version.version}}/app/see-also-links.md %} +{% include_cached {{page.version.version}}/app/see-also-links.md %} From 291f68771f61887322f5c95cd65dbfbc051ba48d Mon Sep 17 00:00:00 2001 From: Matt Linville Date: Tue, 20 Aug 2024 12:14:06 -0700 Subject: [PATCH 07/11] Update Vercel tutorial for Cloud 2.0 --- src/current/v24.2/deploy-app-vercel.md | 94 ++++++++------------------ 1 file changed, 29 insertions(+), 65 deletions(-) diff --git a/src/current/v24.2/deploy-app-vercel.md b/src/current/v24.2/deploy-app-vercel.md index 38dfe10fe5e..ec839972341 100644 --- a/src/current/v24.2/deploy-app-vercel.md +++ b/src/current/v24.2/deploy-app-vercel.md @@ -16,23 +16,32 @@ This tutorial shows you how to use [Vercel](https://vercel.com/) to deploy a web ## Before you begin -Before starting the tutorial, do the following: +Before starting the tutorial, create a [Vercel](https://vercel.com/signup) account and sign in. -1. Create a [CockroachDB {{ site.data.products.cloud }}](https://cockroachlabs.cloud/signup?referralId={{page.referral_id}}) account. +## Step 1. Create a CockroachDB {{ site.data.products.standard }} cluster -1. Create a [Vercel](https://vercel.com/signup) account. +{% include_cached cockroachcloud/quickstart/create-free-trial-standard-cluster.md %} -
+{% include_cached cockroachcloud/connection-string-standard.md %} + +# Step 2. Get the code -## Step 1. Get the code +1. Open the code repository's [GitHub repository](https://github.com/cockroachdb/prisma-examples). +1. Fork it by clicking **Fork** at the top. Netlify requires you to own a Netlify app's repository. + - Set **Owner** to your GitHub identity or an organization. + - Disable **Copy the master branch only**. + - Click **Fork**. -1. Create a [GitHub](https://github.com/) account if you haven't already. -1. In GitHub, [create your own fork](https://docs.github.com/get-started/quickstart/fork-a-repo#forking-a-repository) of CockroachDB's [`prisma-examples` repo](https://github.com/cockroachdb/prisma-examples). + You now have an exact copy of the code repository in the GitHub location you chose. +1. Copy the fork's address, which you will use to clone it locally. Click **Code**, then in the **Local** tab, click **SSH** if you have added SSH keys to GitHub, or **HTTPS** if not. Click the copy symbol to copy the address. +1. Clone your fork locally. Replace `{ADDRESS}` with the full address of your fork, which will end with `prisma-examples.git`. + +
-## Step 2. Create a Vercel project +## Step 3. Create a Vercel project 1. From the [Vercel dashboard](https://vercel.com/dashboard), click **Add new...** > **Project**. -1. Select the `prisma-examples` repository you forked in [Step 1](#step-1-get-the-code) to import. +1. Select the `prisma-examples` repository you forked in [Step 2](#step-2-get-the-code) to import. 1. From the **Framework preset** dropdown, select **Next.js**. 1. In the **Root directory** field, click **Edit**. 1. Select the **typescript** > **rest-nextjs-api-routes** directory. @@ -43,22 +52,19 @@ Before starting the tutorial, do the following: Your deployment will fail until you integrate CockroachDB in the next step, so you can leave this screen without waiting for it to finish. -## Step 3. Integrate CockroachDB +## Step 4. Integrate your project with CockroachDB 1. Navigate to the [CockroachDB page](https://vercel.com/integrations/cockroachdb) of Vercel's integration marketplace. 1. Click **Add Integration**. 1. Select your Vercel account and click **Continue**. 1. Select the project you just created and click **Continue**. 1. Accept the permissions and click **Add Integration**. +1. When prompted, log into CockroachDB Cloud and select the organization and cluster to integrate with. +1. Click **Create** to finish the integration. - A window will pop up prompting you to log in to CockroachDB {{ site.data.products.cloud }} if you haven't already. - -1. In the CockroachDB {{ site.data.products.cloud }} pop-up window, select the organization in which you want to create a new CockroachDB {{ site.data.products.standard }} cluster. -1. Click **Create**. + After a few seconds, the window will close automatically and your Vercel project will have the `DATABASE_URL` environment variable configured with the cluster's connection string. - After a few seconds, your cluster will be created and the pop-up window will close automatically. Once this is done, your Vercel project will have the `DATABASE_URL` environment variable automatically populated with the connection string for your new cluster. - -## Step 3. Deploy the application +## Step 5. Deploy the application 1. Navigate to the **Overview** page for your Vercel project. 1. Select the **Deployments** tab. @@ -69,48 +75,6 @@ Before starting the tutorial, do the following:
- -## Step 1. Create a CockroachDB {{ site.data.products.standard }} cluster - -{% include cockroachcloud/quickstart/create-free-trial-standard-cluster.md %} - - - -After the cluster is created, the **Connection info** window appears. Click the **Connection string** tab and copy the connection string to a secure location. You will use this connection string to connect to CockroachDB later in the tutorial. - -{{site.data.alerts.callout_info}} -The connection string is pre-populated with your username, cluster name, and other details, including your password. Your password, in particular, will be provided only once. Save it in a secure place (we recommend a password manager) to connect to your cluster in the future. If you forget your password, you can reset it by going to the **SQL Users** page for the cluster, found at `https://cockroachlabs.cloud/cluster//users`. -{{site.data.alerts.end}} - -## Step 2. Get the code - -1. Clone the `cockroachdb` fork of the `prisma-examples` repo: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ git clone git@github.com:cockroachdb/prisma-examples.git - ~~~ - -1. Navigate to the `rest-nextjs-api-routes` directory: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cd typescript/rest-nextjs-api-routes - ~~~ - -1. Install the application dependencies: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ npm install - ~~~ - -1. Install the `vercel` and `prisma` CLI tools: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ npm install --global vercel prisma - ~~~ ## Step 3. Initialize the database @@ -118,7 +82,7 @@ The connection string is pre-populated with your username, cluster name, and oth {% include_cached copy-clipboard.html %} ~~~ shell - $ echo "DATABASE_URL=" >> .env + echo "DATABASE_URL=" >> .env ~~~ Prisma loads the variables defined in `.env` to the project environment. By default, Prisma uses the `DATABASE_URL` environment variable as the connection string to the database. @@ -127,7 +91,7 @@ The connection string is pre-populated with your username, cluster name, and oth {% include_cached copy-clipboard.html %} ~~~ shell - $ prisma migrate dev --name init + prisma migrate dev --name init ~~~ You should see the following output: @@ -146,7 +110,7 @@ The connection string is pre-populated with your username, cluster name, and oth {% include_cached copy-clipboard.html %} ~~~ shell - $ npm run dev + npm run dev ~~~ You should see the following output: @@ -159,7 +123,7 @@ The connection string is pre-populated with your username, cluster name, and oth {% include_cached copy-clipboard.html %} ~~~ shell - $ vercel deploy --confirm + vercel deploy --confirm ~~~ You will be asked to sign into your Vercel account. When you authenticate your credentials, you should see the following message: @@ -179,7 +143,7 @@ The connection string is pre-populated with your username, cluster name, and oth ~~~ Follow the links provided to view and manage your deployed application. - +
## See also @@ -188,4 +152,4 @@ The connection string is pre-populated with your username, cluster name, and oth - [How to build a Complete Webapp with React, TypeScript & CockroachDB](https://www.cockroachlabs.com/blog/react-typescript-cockroachdb-sample-app/#deploy-the-application-to-netlify) - [Build a Simple CRUD Node.js App with CockroachDB and Prisma Client]({% link {{ page.version.version }}/build-a-nodejs-app-with-cockroachdb-prisma.md %}) -{% include {{page.version.version}}/app/see-also-links.md %} \ No newline at end of file +{% include_cached {{page.version.version}}/app/see-also-links.md %} From 4c80e8e11428ee6562fbc90b749915f242487539 Mon Sep 17 00:00:00 2001 From: Matt Linville Date: Tue, 20 Aug 2024 17:02:34 -0700 Subject: [PATCH 08/11] [DOC-9717] Update Movr Flask deployment tutorial for Cloud 2.0 --- src/current/v24.2/movr-flask-application.md | 55 +++--- src/current/v24.2/movr-flask-database.md | 17 +- src/current/v24.2/movr-flask-deployment.md | 175 ++++++++------------ src/current/v24.2/movr-flask-setup.md | 58 +++---- src/current/v24.2/movr-flask-use-case.md | 12 +- 5 files changed, 140 insertions(+), 177 deletions(-) diff --git a/src/current/v24.2/movr-flask-application.md b/src/current/v24.2/movr-flask-application.md index 1cc432ceae8..640c2f51977 100644 --- a/src/current/v24.2/movr-flask-application.md +++ b/src/current/v24.2/movr-flask-application.md @@ -7,15 +7,13 @@ docs_area: develop This page guides you through developing a globally-available web application. It is the fourth section of the [Develop and Deploy a Global Application]({% link {{ page.version.version }}/movr.md %}#develop-and-deploy-a-global-application) tutorial. -{% comment %} {% include {{ page.version.version }}/misc/movr-live-demo.md %} {% endcomment %} - {{site.data.alerts.callout_info}} -This tutorial assumes you are running under [`SERIALIZABLE`]({% link {{ page.version.version }}/demo-serializable.md %}) isolation. Client-side retry handling is **not** necessary under [`READ COMMITTED`]({% link {{ page.version.version }}/read-committed.md %}) isolation. +This tutorial uses [`SERIALIZABLE`]({% link {{ page.version.version }}/demo-serializable.md %}) isolation. Client-side retry handling is **not** necessary under [`READ COMMITTED`]({% link {{ page.version.version }}/read-committed.md %}) isolation. {{site.data.alerts.end}} ## Before you begin -Before you begin this section, complete the previous section of the tutorial, [Set Up a Virtual Environment for Developing Global Applications]({% link {{ page.version.version }}/movr-flask-setup.md %}). +Before you begin this section, complete the previous sections of the tutorial, ending with [Set Up a Virtual Environment for Developing Global Applications]({% link {{ page.version.version }}/movr-flask-setup.md %}). ## Project structure @@ -23,22 +21,22 @@ The application needs to handle requests from clients, namely web browsers. To t - A multi-region database schema that defines the tables and indexes for user, vehicle, and ride data. The database schema is covered on a separate page, [Create a Multi-Region Database Schema]({% link {{ page.version.version }}/movr-flask-database.md %}). -- A multi-node, geo-distributed CockroachDB cluster, with each node's locality corresponding to cloud provider regions. +- A multi-node geographically-distributed CockroachDB cluster where each node's locality corresponds to a cloud provider region. Database deployment is covered on two separate pages: - - For instructions on setting up a demo cluster, see [Set Up a Virtual Environment for Developing Multi-Region Applications]({% link {{ page.version.version }}/movr-flask-setup.md %}). - - For instructions on setting up a multi-region cluster, see [Deploy a Global Application]({% link {{ page.version.version }}/movr-flask-deployment.md %}). -- Python class definitions that map to the tables in our database. - For details, see [Mappings](#mappings) below. + - To set up a demo cluster, refer to [Set Up a Virtual Environment for Developing Multi-Region Applications]({% link {{ page.version.version }}/movr-flask-setup.md %}). + - To set up up a multi-region cluster, refer to [Deploy a Global Application]({% link {{ page.version.version }}/movr-flask-deployment.md %}). +- Python class definitions that map to the tables in the database. + Refer to [Mappings](#mappings). - Functions that wrap database transactions. - For details, see [Transactions](#transactions) below. + Refer to [Transactions](#transactions). - A backend API that defines the application's connection to the database. - For details, see [Database connection](#database-connection) below. + Refer to [Database connection](#database-connection). - A [Flask](https://palletsprojects.com/p/flask/) server that handles requests from clients. - For details, see [Web application](#web-application) below. + Refer to [Web application](#web-application). - HTML files that the Flask server can render into web pages. - For details, see [User interface](#user-interface) below. + Refer to [User interface](#user-interface). -In the sections that follow, we go over each of the files and folders in the project, with a focus on the backend and database components. Here is the application's project directory structure: +In the sections that follow, we go over each of the files and folders in the project, with a focus on the backend and database components. The project's code is structured as follows: ~~~ shell movr @@ -78,10 +76,9 @@ movr └── gunicorn.py ## Contains gunicorn configuration settings ~~~ - ## SQLAlchemy with CockroachDB -Object Relational Mappers (ORMs) map classes to tables, class instances to rows, and class methods to transactions on the rows of a table. The `sqlalchemy` package includes some base classes and methods that you can use to connect to your database's server from a Python application, and then map tables in that database to Python classes. +Object Relational Mappers (ORMs) map classes to tables, class instances to rows, and class methods to transactions on the rows of a table. The `sqlalchemy` package includes some base classes and methods that you can use to connect to your database's cluster from a Python application, and then map tables in that database to Python classes. In our example, we use SQLAlchemy's [Declarative](https://docs.sqlalchemy.org/orm/extensions/declarative/) extension, which is built on the `mapper()` and `Table` data structures. We also use the [`sqlalchemy-cockroachdb`](https://github.com/cockroachdb/sqlalchemy-cockroachdb) Python package, which defines the CockroachDB SQLAlchemy [dialect](https://docs.sqlalchemy.org/dialects/). The package includes some functions that help you handle [transactions]({% link {{ page.version.version }}/transactions.md %}) in a running CockroachDB cluster. @@ -130,7 +127,7 @@ Recall that the `vehicles` table contains more columns and data types than the ` #### The `Ride` class -Lastly, there's the `Ride` class: +Take a look at the `Ride` class: ~~~ python {% remote_include https://raw.githubusercontent.com/cockroachlabs/movr-flask/v2-doc-includes/movr/models.py ||# START Ride ||# END Ride %} @@ -152,16 +149,15 @@ The [`sqlalchemy-cockroachdb`](https://github.com/cockroachdb/sqlalchemy-cockroa - When passed a [`sqlalchemy.orm.session.sessionmaker`](https://docs.sqlalchemy.org/orm/session_api.html#session-and-sessionmaker) object, it ensures that a new session is created exclusively for use by the callback, which protects you from accidentally reusing objects via any sessions created outside the transaction. Note that a `sessionmaker` objects is different from a `session` object, which is not an allowable `transactor` for `run_transaction()`. - By abstracting transaction retry logic away from your application, it keeps your application code portable across different databases. + Because all callback functions are passed to `run_transaction()`, the `Session` method calls within those callback functions are written a little differently than the typical SQLAlchemy application. Most importantly, those functions must not change the session and/or transaction state. This is in line with the recommendations of the [SQLAlchemy FAQs](https://docs.sqlalchemy.org/orm/session_basics.html#session-frequently-asked-questions), which state (with emphasis added by the original author) that - Because all callback functions are passed to `run_transaction()`, the `Session` method calls within those callback functions are written a little differently than the typical SQLAlchemy application. Most importantly, those functions must not change the session and/or transaction state. This is in line with the recommendations of the [SQLAlchemy FAQs](https://docs.sqlalchemy.org/orm/session_basics.html#session-frequently-asked-questions), which state (with emphasis added by the original author) that + As a general rule, the application should manage the lifecycle of the session *externally* to functions that deal with specific data. This is a fundamental separation of concerns which keeps data-specific operations agnostic of the context in which they access and manipulate that data. -As a general rule, the application should manage the lifecycle of the session *externally* to functions that deal with specific data. This is a fundamental separation of concerns which keeps data-specific operations agnostic of the context in which they access and manipulate that data. + and - and + Keep the lifecycle of the session (and usually the transaction) **separate and external**. -Keep the lifecycle of the session (and usually the transaction) **separate and external**. - - In keeping with the above recommendations from the official docs, we strongly recommend avoiding any explicit mutations of the transaction state inside the callback passed to `run_transaction()`. Specifically, we do not make calls to the following functions from inside `run_transaction()`: + In keeping with the above recommendations from the official docs, we strongly recommend avoiding any explicit mutations of the transaction state inside the callback passed to `run_transaction()`. Specifically, we do not make calls to the following functions from inside `run_transaction()`: - [`sqlalchemy.orm.Session.commit()`](https://docs.sqlalchemy.org/orm/session_api.html?highlight=commit#sqlalchemy.orm.session.Session.commit) (or other variants of `commit()`) @@ -173,13 +169,17 @@ The [`sqlalchemy-cockroachdb`](https://github.com/cockroachdb/sqlalchemy-cockroa - `Session.flush()` - This will not work as expected with CockroachDB because [CockroachDB does not support nested transactions]({% link {{ page.version.version }}/savepoint.md %}), which are necessary for `Session.flush()` to work properly. If the call to `Session.flush()` encounters an error and aborts, it will try to rollback. This will not be allowed by the currently-executing CockroachDB transaction created by `run_transaction()`, and will result in an error message like the following: `sqlalchemy.orm.exc.DetachedInstanceError: Instance is not bound to a Session; attribute refresh operation cannot proceed (Background on this error at: http://sqlalche.me/e/bhk3)`. + This will not work as expected with CockroachDB because [CockroachDB does not support nested transactions]({% link {{ page.version.version }}/savepoint.md %}), which are necessary for `Session.flush()` to work properly. If the call to `Session.flush()` encounters an error and aborts, it will try to roll back. This will not be allowed by the currently-executing CockroachDB transaction created by `run_transaction()`, and will result in an error message like the following: + + ~~~ + sqlalchemy.orm.exc.DetachedInstanceError: Instance is not bound to a Session; attribute refresh operation cannot proceed (Background on this error at: http://sqlalche.me/e/bhk3). + ~~~ - In the example application, all calls to `run_transaction()` are found within the methods of the `MovR` class (defined in [`movr/movr.py`](https://github.com/cockroachlabs/movr-flask/blob/master/movr/movr.py)), which represents the connection to the running database. Requests to the web application frontend (defined in [`server.py`](https://github.com/cockroachlabs/movr-flask/blob/master/server.py)), are routed to the `MovR` class methods. + In the example application, all calls to `run_transaction()` are located within the methods of the `MovR` class, which is defined in [`movr/movr.py`](https://github.com/cockroachlabs/movr-flask/blob/master/movr/movr.py). This class represents the connection to the running database. Requests to the web application frontend, which are defined in [`server.py`](https://github.com/cockroachlabs/movr-flask/blob/master/server.py), are routed to the `MovR` class methods. #### Transaction callback functions - To separate concerns, we define all callback functions passed to `run_transaction()` calls in a separate file, [`movr/transactions.py`](https://github.com/cockroachlabs/movr-flask/blob/master/movr/transactions.py). These callback functions wrap `Session` method calls, like [`session.query()`](https://docs.sqlalchemy.org/orm/session_api.html#sqlalchemy.orm.session.Session.query) and [`session.add()`](https://docs.sqlalchemy.org/orm/session_api.html#sqlalchemy.orm.session.Session.add), to perform database operations within a transaction. +To separate concerns, we define all callback functions passed to `run_transaction()` calls in a separate file, [`movr/transactions.py`](https://github.com/cockroachlabs/movr-flask/blob/master/movr/transactions.py). These callback functions wrap `Session` method calls, like [`session.query()`](https://docs.sqlalchemy.org/orm/session_api.html#sqlalchemy.orm.session.Session.query) and [`session.add()`](https://docs.sqlalchemy.org/orm/session_api.html#sqlalchemy.orm.session.Session.add), to perform database operations within a transaction. {{site.data.alerts.callout_success}} We recommend that you use a `sessionmaker` object, bound to an existing `Engine`, as the `transactor` that you pass to `run_transaction()`. This protects you from accidentally reusing objects via any sessions created outside the transaction. Every time `run_transaction()` is called, it uses the `sessionmaker` object to create a new [`Session`](https://docs.sqlalchemy.org/orm/session.html) object for the callback. If the `sessionmaker` is bound to an existing `Engine`, the same database connection can be reused. @@ -383,11 +383,10 @@ We've also added some Bootstrap syntax and Google Maps, for UX purposes. As you ## Next Steps -After you finish developing and debugging your application, you can start [deploying the application]({% link {{ page.version.version }}/movr-flask-deployment.md %}). +After you finish developing and debugging your application, you can learn about [deploying the application]({% link {{ page.version.version }}/movr-flask-deployment.md %}). ## See also -{% comment %} [MovR (live demo)](https://movr.cloud){% endcomment %} - [SQLAlchemy documentation](https://docs.sqlalchemy.org/) - [Transactions]({% link {{ page.version.version }}/transactions.md %}) - [Flask documentation](https://flask.palletsprojects.com/) diff --git a/src/current/v24.2/movr-flask-database.md b/src/current/v24.2/movr-flask-database.md index c77c24a0ab4..4bb882c2135 100644 --- a/src/current/v24.2/movr-flask-database.md +++ b/src/current/v24.2/movr-flask-database.md @@ -9,7 +9,7 @@ This page guides you through creating a database schema for an example global ap ## Before you begin -Before you begin this section, complete the previous section of the tutorial, [MovR: A Global Application Use-Case]({% link {{ page.version.version }}/movr-flask-use-case.md %}). +Before you begin this section, complete the previous sections of the tutorial, ending with [MovR: A Global Application Use-Case]({% link {{ page.version.version }}/movr-flask-use-case.md %}). We also recommend reviewing [CockroachDB's multi-region capabilities]({% link {{ page.version.version }}/multiregion-overview.md %}), if you have not done so already. @@ -26,8 +26,7 @@ These tables store information about the users and vehicles registered with MovR Initialization statements for `movr` are defined in [`dbinit.sql`](https://github.com/cockroachlabs/movr-flask/blob/master/dbinit.sql), a SQL file that you use later in this tutorial to load the database to a running cluster. {{site.data.alerts.callout_info}} -The database schema used in this application is a slightly simplified version of the [`movr` database schema]({% link {{ page.version.version }}/movr.md %}) that is built into the `cockroach` binary. The schemas are similar, but they are not the same. -{{site.data.alerts.end}} +The database schema used in this application is a slightly simplified version of the [`movr` database schema]({% link {{ page.version.version }}/movr.md %}) that is built into the `cockroach` binary. The schemas are similar, but they are not identical. ## Multi-region in CockroachDB @@ -39,7 +38,7 @@ To keep track of geographic information about nodes in a cluster, CockroachDB us When you [add a node to a cluster]({% link {{ page.version.version }}/cockroach-start.md %}), you can assign the node a specific [locality]({% link {{ page.version.version }}/cockroach-start.md %}#locality). Localities represent a geographic region or zone, and are meant to correspond directly to the cloud provider region or zone in which the node is deployed. -Each unique regional locality is stored in CockroachDB as a [cluster region]({% link {{ page.version.version }}/multiregion-overview.md %}#cluster-regions). After a [cluster is deployed]({% link {{ page.version.version }}/movr-flask-deployment.md %}), you can assign regions to new and existing databases in the cluster. +Each unique regional locality is stored in CockroachDB as a [cluster region]({% link {{ page.version.version }}/multiregion-overview.md %}#cluster-regions). After a cluster is deployed, you can assign regions to new and existing databases in the cluster. For an example of a deployment, refer to [Deploy a Global Serverless Application]({% link {{ page.version.version }}/movr-flask-deployment.md %}), the final step of this tutorial series. {{site.data.alerts.callout_info}} Only cluster regions specified at node startup can be used as [database regions]({% link {{ page.version.version }}/multiregion-overview.md %}#database-regions). You can view regions available to databases in the cluster with [`SHOW REGIONS FROM CLUSTER`]({% link {{ page.version.version }}/show-regions.md %}). @@ -52,7 +51,7 @@ Here is the [`CREATE DATABASE`]({% link {{ page.version.version }}/create-databa > {% remote_include https://raw.githubusercontent.com/cockroachlabs/movr-flask/v2-doc-includes/dbinit.sql ||-- START database ||-- END database %} ~~~ -Note that `movr` has the following [database regions]({% link {{ page.version.version }}/multiregion-overview.md %}#database-regions), which correspond to regions in Google Cloud: +In this example, `movr` has the following [database regions]({% link {{ page.version.version }}/multiregion-overview.md %}#database-regions), which correspond to regions in Google Cloud: - `gcp-us-east1` (primary) - `gcp-europe-west1` @@ -64,9 +63,9 @@ Note that `movr` has the following [database regions]({% link {{ page.version.ve After you have added regions to a database, you can control where the data in each table in the database is stored, using [table localities]({% link {{ page.version.version }}/multiregion-overview.md %}#table-locality). -By default, CockroachDB uses the table locality setting [`REGIONAL BY TABLE IN PRIMARY REGION`]({% link {{ page.version.version }}/table-localities.md %}#regional-tables) for all new tables added to a multi-region database. The `REGIONAL BY TABLE` table locality optimizes read and write access to the data in a table from a single region (in this case, the primary region `gcp-us-east1`). +By default, CockroachDB uses the table locality setting [`REGIONAL BY TABLE IN PRIMARY REGION`]({% link {{ page.version.version }}/table-localities.md %}#regional-tables) for all new tables added to a multi-region database. The `REGIONAL BY TABLE` locality optimizes read and write access to the data in a table from a single region (in this case, the primary region `gcp-us-east1`). -The `movr` database contains tables with rows of data that need to be accessed by users in more than one region. As a result, none of the tables benefit from using a `REGIONAL BY TABLE` locality. Instead, all three tables in the `movr` database schema should use a [`REGIONAL BY ROW` locality]({% link {{ page.version.version }}/table-localities.md %}#regional-by-row-tables). For `REGIONAL BY ROW` tables, CockroachDB automatically assigns each row to a region based on the locality of the node from which the row is inserted. It then optimizes subsequent read and write queries executed from nodes located in the region assigned to the rows being queried. +The `movr` database contains tables with rows of data that need to be accessed by users in more than one region. As a result, none of the tables benefit from using a `REGIONAL BY TABLE` locality. Instead, all three tables in the `movr` database schema should use a [`REGIONAL BY ROW` locality]({% link {{ page.version.version }}/table-localities.md %}#regional-by-row-tables). With `REGIONAL BY ROW` locality, CockroachDB initially assigns each row of the table to a region based on the locality of the node that inserted the row. Subsequent reads and writes are optimized based on the localities of the nodes querying those rows. {{site.data.alerts.callout_info}} As shown in the `CREATE TABLE` statements below, the `REGIONAL BY ROW` clauses do not identify a column to track the region for each row. To assign rows to regions, CockroachDB creates and manages a hidden [`crdb_region` column]({% link {{ page.version.version }}/alter-table.md %}#crdb_region), of [`ENUM`]({% link {{ page.version.version }}/enum.md %}) type `crdb_internal_region`. The values of `crdb_region` are populated using the regional locality of the node from which the query creating the row originates. @@ -88,7 +87,7 @@ Here is the `CREATE TABLE` statement for the `users` table: > {% remote_include https://raw.githubusercontent.com/cockroachlabs/movr-flask/v2-doc-includes/dbinit.sql ||-- START vehicles ||-- END vehicles %} ~~~ -Note that the `vehicles` table has a [foreign key constraint]({% link {{ page.version.version }}/foreign-key.md %}) on the `users` table, for the `city` and `owner_id` columns. This guarantees that a vehicle is registered to a particular user (i.e., an "owner") in the city where that user is registered. +The `vehicles` table has a [foreign key constraint]({% link {{ page.version.version }}/foreign-key.md %}) on the `users` table, for the `city` and `owner_id` columns. This guarantees that a vehicle is registered to a particular user (i.e., an "owner") in the city where that user is registered. ## The `rides` table @@ -97,7 +96,7 @@ Note that the `vehicles` table has a [foreign key constraint]({% link {{ page.ve > {% remote_include https://raw.githubusercontent.com/cockroachlabs/movr-flask/v2-doc-includes/dbinit.sql ||-- START rides ||-- END rides %} ~~~ -Note that, like the `vehicles` table, the `rides` table has foreign key constraints. These constraints are on the `users` and the `vehicles` tables. +Like the `vehicles` table, the `rides` table has foreign key constraints. These constraints are on the `users` and the `vehicles` tables. ## Next steps diff --git a/src/current/v24.2/movr-flask-deployment.md b/src/current/v24.2/movr-flask-deployment.md index 4479be9ab68..1a8d3b2e47f 100644 --- a/src/current/v24.2/movr-flask-deployment.md +++ b/src/current/v24.2/movr-flask-deployment.md @@ -1,86 +1,74 @@ --- -title: Deploy a Global, Serverless Application -summary: This page includes instructions for deploying a multi-region web application using CockroachDB Cloud and Google Cloud services. +title: Deploy a Global Serverless Application +summary: This page includes instructions for deploying a multi-region web application using CockroachDB Standard and Google Cloud Platform. toc: true docs_area: --- This page guides you through deploying an application and database in multiple regions. It is the fifth and final section of the [Develop and Deploy a Global Application]({% link {{ page.version.version }}/movr.md %}#develop-and-deploy-a-global-application) tutorial. -{% comment %} {% include {{ page.version.version }}/misc/movr-live-demo.md %} {% endcomment %} - ## Before you begin -Before you begin this section, complete the previous section of the tutorial, [Develop a Multi-Region Web Application]({% link {{ page.version.version }}/movr-flask-application.md %}). After you finish developing and debugging your multi-region application in a local development environment, you are ready to deploy the application and database in multiple regions. +Before you begin this section, complete the previous sections of the tutorial, ending with [Develop a Multi-Region Web Application]({% link {{ page.version.version }}/movr-flask-application.md %}). After you finish developing and debugging your multi-region application in a local development environment, you are ready to deploy the application and database in multiple regions. -In addition to the requirements listed in [Setting Up a Virtual Environment for Developing Multi-Region Applications]({% link {{ page.version.version }}/movr-flask-setup.md %}), make sure that you have the following: +In addition to the requirements listed in [Setting Up a Virtual Environment for Developing Multi-Region Applications]({% link {{ page.version.version }}/movr-flask-setup.md %}): -- [A Google Cloud account](https://cloud.google.com/) -- [The Google Cloud SDK installed on your local machine](https://cloud.google.com/sdk/install) -- [Docker installed on your local machine](https://docs.docker.com/v17.12/docker-for-mac/install/) +- Log in to [Google Cloud](https://cloud.google.com/). +- Install the [Google Cloud SDK](https://cloud.google.com/sdk/install). +- Install a container runtime, such as [Docker Desktop](https://www.docker.com/products/docker-desktop/), and ensure that it is running in the background. ## Multi-region database deployment -In production, you want to start a secure CockroachDB cluster, with nodes on machines located in different areas of the world. To deploy CockroachDB in multiple regions, we recommend using [CockroachDB {{ site.data.products.standard }}]({% link cockroachcloud/quickstart.md %}). - -{{site.data.alerts.callout_info}} -You can also deploy CockroachDB manually. For instructions, see the [Manual Deployment]({% link {{ page.version.version }}/manual-deployment.md %}) page of the Cockroach Labs documentation site. -{{site.data.alerts.end}} +In production, you want to start a secure CockroachDB cluster, with nodes on machines located in different areas of the world. To deploy CockroachDB in multiple regions, we recommend using [CockroachDB {{ site.data.products.standard }}]({% link cockroachcloud/quickstart.md %}). To use CockroachDB {{ site.data.products.core }} instead, refer to [Install CockroachDB](/docs/{{ page.version.version }}/install-cockroachdb.html). ### Create a multi-region CockroachDB {{ site.data.products.standard }} cluster -1. Sign up for a CockroachDB {{ site.data.products.cloud }} account. - -1. [Log in](https://cockroachlabs.cloud/) to your CockroachDB {{ site.data.products.cloud }} account. - -1. On the **Overview** page, select **Create Cluster**. - -1. On the **Create new cluster** page: - - For **Plan**, select CockroachDB {{ site.data.products.standard }}. You won't be charged for the first 30 days of service. - - For **Cloud Provider**, select Google Cloud. - - For **Regions & nodes**, add "us-east1", "us-west1", and "europe-west1", with 3 nodes in each region. - - Leave the **Hardware** and **Cluster name** as their default values. - - For **Additional settings**, turn on VPC peering, with the default IP range. +1. Create a [CockroachDB {{ site.data.products.cloud }}](https://cockroachlabs.cloud/signup?referralId={{page.referral_id}}) account and log in. +1. On the **Clusters** page, click **Create cluster**. +1. On the **Select a plan** page, select **Standard**. +1. On the **Cloud & Regions** page, set **Cloud provider** to **GCP**. +1. In the **Regions** section, add `us-east1`, `us-west1`, and `europe-west1`. Keep the default of 3 nodes per region. + Click **Next: Capacity**. +1. Keep the **Provisioned capacity** at the default value of 1000 RUs/second. + Click **Next: Finalize**. +1. On the **Finalize** page, optionally name your cluster. If applicable, the 30-day trial code is pre-applied to your cluster. -1. Select **Next**, and on the **Summary** page, enter your credit card details. + Click **Create cluster**. - {{site.data.alerts.callout_info}} - You will not be charged until after your free trial expires in 30 days. - {{site.data.alerts.end}} - -1. Select **Create cluster**. + Your cluster will be created in a few seconds and the **Create SQL user** dialog will display. - Once your cluster is created, you will be redirected to the **Cluster Overview** page. +1. Enter a username for the SQL user. Click **Generate & Save Password**. Save the username and password to a secure location such as a password manager. Click **Next**, then **Close**. -1. On the **Cluster Overview** page, select **SQL Users** from the side panel. + The **Cluster Overview** page appears. -1. Select **Add user**, give the user a name and a password, and then add the user. You can use any user name except "root". +1. On the **Cluster Overview** page, select **Networking**, then select the **IP Allowlist** tab. -1. Select **Networking** from the side panel, and select **Add network**. - -1. From the **Network** dropdown, select **Current Network** to auto-populate your local machine's IP address. To allow the network to access the cluster's DB Console and to use the CockroachDB client to access the databases, select the **DB Console to monitor the cluster** and **CockroachDB Client to access the databases** checkboxes. +1. Click **Add Network**. From the **Network** dropdown, select **Current Network** to auto-populate your local machine's IP address. This allows your local machine to access the cluster's DB Console and to use the CockroachDB client to access the databases. {{site.data.alerts.callout_info}} - After setting up your application's GCP project and GCP VPC network, you will need to return to the **Networking** page to configure VPC peering. + After setting up your application's GCP project and GCP VPC network, you will need to return to the **Networking** page to configure GCP Private Service Connect for private connectivity. {{site.data.alerts.end}} ### Initialize the `movr` database 1. Open a new terminal window on your local machine, and navigate to the `movr-flask` project directory. -1. In the CockroachDB {{ site.data.products.cloud }} Console, select **Connect** at the top-right corner of the page. +1. In your web browser, log in to the CockroachDB {{ site.data.products.cloud }} Console, then select **Connect** at the top-right corner of the page. 1. Select the **SQL User** that you created and the **Region** closest to you, and then select **Next**. -1. From the **Connection info** page, copy the `curl` command to download the cluster's root certificate, and execute the command in your terminal window. This root certificate is the same for all regions in a cluster. +1. From the **Connection info** dialog, click **Download CA Certificate**, then follow the instructions. This is required only once per client. This root certificate is the same for all regions in a cluster. -1. From the **Connection info** page, copy the `cockroach sql` command. In the terminal window, execute the command with an `-f dbinit.sql` option at the end of the command. For example: +1. Under **Select option/language**, select **CockroachDB Client**. Copy the command. +1. In a new terminal window, navigate to the `movr-flask` project directory, then paste the command you just copied. Add the ` -f dbinit.sql` option at the end of the command. For example: ~~~ shell - $ cockroach sql --url 'postgresql://user:password@cluster.gcp-us-east1.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert='$HOME'/Library/CockroachCloud/certs/root.crt' -f dbinit.sql + cockroach sql \ + --url 'postgresql://user:password@cluster.gcp-us-east1.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert='$HOME'/Library/CockroachCloud/certs/root.crt' \ + -f dbinit.sql ~~~ - This command will initialize the `movr` database on your CockroachDB {{ site.data.products.standard }} cluster. + This command will initialize the `movr` database on the cluster in CockroachDB {{ site.data.products.cloud }}. ## Global application deployment @@ -108,10 +96,10 @@ We do not recommend deploying insecure web applications on public networks. 1. **Optional:** Enable the [Google Maps Embed API](https://console.cloud.google.com/apis/library), create an API key, restrict the API key to all URLS on your domain name (e.g., `https://site.com/*`), and retrieve the API key. {{site.data.alerts.callout_info}} - The example HTML templates include maps. Not providing an API key to the application will prevent the maps from loading, but will not break the rest of the application. + The example HTML templates include maps. Not providing an API key to the application will prevent the maps from loading, but will not prevent the rest of the application from functioning. {{site.data.alerts.end}} -1. Configure/authorize the `gcloud` command-line tool to use your project and region. +1. Initialize and log in using the `gcloud` command-line tool. {{site.data.alerts.callout_info}} `gcloud` is included with the [Google Cloud SDK](https://cloud.google.com/sdk) installation. @@ -119,106 +107,86 @@ We do not recommend deploying insecure web applications on public networks. {% include_cached copy-clipboard.html %} ~~~ shell - $ gcloud init + gcloud init ~~~ {% include_cached copy-clipboard.html %} ~~~ shell - $ gcloud auth login + gcloud auth login ~~~ {% include_cached copy-clipboard.html %} ~~~ shell - $ gcloud auth application-default login + gcloud auth application-default login ~~~ -### Set up VPC peering +### Set up GCP Private Service Connect -1. Open the CockroachDB {{ site.data.products.cloud }} Console for your cluster, select the **Networking**, and then select **VPC peering**. +GCP Private Service Connect allows your cluster to connect to your Google Cloud project using private cloud infrastructure rather than the public internet. To set up PSC: -1. Set up a new VPC peering connection, with your Google Cloud project's ID, the `default` VPC network created for your Google Cloud project, and a new VPC connection name (e.g., `movr-app-vpc`). +1. Once for each cluster region, follow the instructions to [Establish private connectivity]({% link cockroachcloud/connect-to-your-cluster.md %}#establish-private-connectivity). -1. Copy the `gcloud` command provided by the console, and execute the command in a new terminal window. +1. To obtain the private connection string your application will use to connect privately to your cluster, click **Connect** at the top-right corner of the page, then: + - Select the **SQL User** that you created. + - For each cluster region: + - Select the region. + - For **Connection type**, select **Private connection**, then select the private connection you just created. + - Under **Select option/language**, select **General connection string**. Copy the connection string. - {{site.data.alerts.callout_info}} - The connection strings used to connect to CockroachDB {{ site.data.products.cloud }} from an application in a VPC network differ slightly from connection strings to allow-listed IP addresses. - {{site.data.alerts.end}} - -1. Obtain the VPC connection string for each region: - - 1. Open CockroachDB {{ site.data.products.cloud }} Console, and select **Connect** at the top right of the page. - 1. Select **VPC Peering** for **Network Security**, your SQL username for the **SQL User**, one of the cluster regions for **Region**, `movr` for the **Database**. - 1. Select **Next**. On the following page, select the **Connection string** tab, and then copy the connection string provided. - - Take note of each region's connection string. You will need to provide connection information to the Google Cloud Run service in each region. - -1. Open the Google Cloud console for your project. Under the **VPC network** services, select the **Serverless VPC access** service. - -1. For each Cloud Run service, create a new VPC connector: - - For **Name**, use a name specific to the region. - - For **Region**, use the region of the Cloud Run service. - - For **Network**, use `default`. - - For **Subnet**, specify a custom IP range. This range must be an unused `/28` CIDR IP range (`10.8.0.0`, `10.8.1.0`, `10.8.2.0`, etc.). +You now have a private connection string for each of the cluster's regions. You will use these connection strings to [deploy the application](#deploy-the-application). ### Containerize the application -1. Create a new folder named `certs` at the top level of the `movr-flask` project, and then copy the root certificate that you downloaded for your cluster to the new folder. The `Dockerfile` for the application contains instructions to mount this folder and certificate onto the container. +1. Create a new directory named `certs` at the top level of the `movr-flask` project, and then copy the root certificate that you downloaded for your cluster to the new directory. The `Dockerfile` for the application contains instructions to mount this directory onto the container so that it can read the CA certificate. -1. Build and run the Docker image locally. +1. Build the container image locally. {% include_cached copy-clipboard.html %} ~~~ shell - $ docker build -t gcr.io//movr-app:v1 . + docker build -t gcr.io//movr-app:v1 . ~~~ - If there are no errors, the container built successfully. + If there are errors, verify that your container runtime is running in the background and try again. -1. Push the Docker image to the Google Cloud project's container registry. +1. Push the container image to the Google Cloud project's container registry. {% include_cached copy-clipboard.html %} ~~~ shell - $ docker push gcr.io//movr-app:v1 + docker push gcr.io//movr-app:v1 ~~~ -### Deploy the application +The image can now be pulled by container runtimes with access to your Google Cloud project. -1. Create a [Google Cloud Run](https://console.cloud.google.com/run/) service for the application, in one of the regions in which the database is deployed (e.g., `gcp-us-east1`): - - Select the container image URL for the image that you just pushed to the container registry. - - Under **Advanced settings**->**Variables & Secrets**, do the following: - - Set an environment variable named `DB_URI` to the VPC connection string for a node on the CockroachDB {{ site.data.products.standard }} cluster, in the region in which this first Cloud Run service is located. +### Deploy the application - Verify that the `DB_URI` value: - 1. Specifies `cockroachdb` as the database protocol. - 1. Includes both the username and password. - 1. Includes the path to the container-mounted root certificate (e.g., `certs/root.crt`). +1. Create a [Google Cloud Run](https://console.cloud.google.com/run/) service for the application, in one of the regions in which the database is deployed: + - Select the container image that you just pushed your project's registry. + - Under **Advanced settings**->**Variables & Secrets**: + - Create a new environment variable named `DB_URI`. Set its value to the private connection string for this region that you copied when you [set up GCP Private Service Connect](#set-up-gcp-private-service-connect) with the following modifications: + 1. Change `postgresql://` to `cockroachdb://`. + 1. Add `&sslrootcert=certs/root.crt` directly after `sslmode=verify-full`. For example: `cockroachdb://user:password@internal-cluster.gcp-us-east1.cockroachlabs.cloud:26257/movr?sslmode=verify-full&sslrootcert=certs/root.crt` - - Set an environment variable named `REGION` to the CockroachDB {{ site.data.products.cloud }} region (e.g., `gcp-us-east1`). - - **Optional:** Create a secret for your Google Maps API key and use it to set the environment variable `API_KEY`. You may need to enable the Secret Manager API to do this. - -1. Repeat the Google Cloud Run set-up steps for all regions. - - {{site.data.alerts.callout_info}} - Each region has the same root certificate, but different connection strings. - {{site.data.alerts.end}} + - Create a new environment variable named `REGION` to the region associated with the connection string. + - **Optional:** Enable the Secret Manager API, then create a secret for your Google Maps API key and set the the environment variable `API_KEY` to its value. -1. Create an [external HTTPS load balancer](https://console.cloud.google.com/net-services/loadbalancing) to route requests to the right service: +1. Create an [external HTTPS load balancer](https://console.cloud.google.com/net-services/loadbalancing) to route requests to the service in each region: - For the backend configuration, create separate network endpoint groups (NEGs) for the Google Cloud Run services in each region. - - For the frontend configuration, make sure that you use the HTTPS protocol. You can create a [managed IP address](https://console.cloud.google.com/networking/addresses) and a [managed SSL cert](https://console.cloud.google.com/net-services/loadbalancing/advanced/sslCertificates) for the load balancer directly from the load balancer console. For the SSL cert, you will need to specify a domain name. + - For the frontend configuration, use the HTTPS protocol. You can create a [managed IP address](https://console.cloud.google.com/networking/addresses) and a [managed SSL cert](https://console.cloud.google.com/net-services/loadbalancing/advanced/sslCertificates) for the load balancer directly from the load balancer console. For the SSL cert, you will need to specify a domain name. For detailed instructions on setting up a load balancer for a multi-region Google Cloud Run backend, see the [GCP Load Balancer docs](https://cloud.google.com/load-balancing/docs/https/setting-up-https-serverless#ip-address). 1. In the **Cloud DNS** console (found under **Network Services**), create a new zone. You can name the zone whatever you want. Enter the same domain name for which you created a certificate earlier. -1. Select your zone, and copy the nameserver addresses (under "**Data**") for the recordset labeled "**NS**". +1. Select your zone, and copy the nameserver addresses **Data** for the recordset labeled **NS**. -1. Outside of the GCP console, through your domain name provider, add the nameserver addresses to the authoritative nameserver list for your domain name. +1. In your domain's DNS provider, add the nameserver addresses to the authoritative nameserver list for your domain. {{site.data.alerts.callout_info}} It can take up to 48 hours for changes to the authoritative nameserver list to take effect. {{site.data.alerts.end}} -1. Navigate to the domain name and test out your application. +1. Navigate to the domain name to access and test your application. ## Next steps @@ -228,12 +196,9 @@ This tutorial demonstrates how to develop and deploy an example multi-region app ### Upgrade your deployment -Some time after you have deployed your application, you will likely need to push changes that you've made locally. When pushing changes, be aware that you defined the database separate from the application. If you change a data type, for example, in your application, you will also need to modify the database schema to be compatible with your application's requests. For information about making online changes to database schemas, see [Online Schema Changes]({% link {{ page.version.version }}/online-schema-changes.md %}). +When pushing changes to update your deployment, remember that you defined the database separate from the application. If you change a data type, for example, in your application, you will also need to modify the database schema to be compatible with your application's requests. For information about making online changes to database schemas, refer to [Online Schema Changes]({% link {{ page.version.version }}/online-schema-changes.md %}). ## See also -{% comment %} [MovR (live demo)](https://movr.cloud){% endcomment %} -- [CockroachDB {{ site.data.products.cloud }} documentation]({% link cockroachcloud/quickstart.md %}) +- [CockroachDB {{ site.data.products.cloud }} quickstart]({% link cockroachcloud/quickstart.md %}) - [Google Cloud Platform documentation](https://cloud.google.com/docs/) -- [Docker documentation](https://docs.docker.com/) -- [Kubernetes documentation](https://kubernetes.io/docs/home/) diff --git a/src/current/v24.2/movr-flask-setup.md b/src/current/v24.2/movr-flask-setup.md index 5c0b55e2153..74d15e1153b 100644 --- a/src/current/v24.2/movr-flask-setup.md +++ b/src/current/v24.2/movr-flask-setup.md @@ -9,14 +9,12 @@ This page guides you through setting up a virtual environment for developing and ## Before you begin -1. Complete the previous section of the tutorial, [Create a Multi-Region Database Schema]({% link {{ page.version.version }}/movr-flask-database.md %}). +1. Complete the previous sections of the tutorial, ending with [Create a Multi-Region Database Schema]({% link {{ page.version.version }}/movr-flask-database.md %}). -1. Make sure that you have the following installed on your local machine: - - [CockroachDB]({% link {{ page.version.version }}/install-cockroachdb-mac.md %}) - - [Python 3](https://www.python.org/downloads/) - - [Pipenv](https://pipenv.pypa.io) - -1. Clone the [`movr-flask`](https://github.com/cockroachlabs/movr-flask) repository. We'll reference the source code in this repository throughout the tutorial. +1. On your local machine: + - [Install CockroachDB](/docs/{{ page.version.version }}/install-cockroachdb.html). + - [Install Python 3](https://www.python.org/downloads/) and [Pipenv](https://pipenv.pypa.io) if necessary. + - Clone the [`movr-flask`](https://github.com/cockroachlabs/movr-flask) repository. We'll reference the source code in this repository throughout the tutorial. ## Set up a demo multi-region CockroachDB cluster @@ -26,25 +24,27 @@ For debugging and development purposes, you can use the [`cockroach demo`]({% li {% include_cached copy-clipboard.html %} ~~~ shell - $ cockroach demo \ - --nodes=9 \ - --demo-locality=region=gcp-us-east1:region=gcp-us-east1:region=gcp-us-east1:\ - region=gcp-us-west1:region=gcp-us-west1:region=gcp-us-west1:\ - region=gcp-europe-west1:region=gcp-europe-west1:region=gcp-europe-west1 \ - --empty + cockroach demo \ + --nodes=9 \ + --demo-locality=region=gcp-us-east1:region=gcp-us-east1:region=gcp-us-east1:\ + region=gcp-us-west1:region=gcp-us-west1:region=gcp-us-west1:\ + region=gcp-europe-west1:\ + region=gcp-europe-west1:region=gcp-europe-west1 \ + --empty ~~~ Keep this terminal window open. Closing it will shut down the demo cluster. -1. Open another terminal window. In the new window, run the following command to load `dbinit.sql` to the demo database. This file contains the `movr` database schema that we covered in [Create a Multi-Region Database Schema]({% link {{ page.version.version }}/movr-flask-database.md %}). +1. In a new terminal, load the `dbinit.sql` script to the demo database. This file contains the `movr` database schema that we covered in [Create a Multi-Region Database Schema]({% link {{ page.version.version }}/movr-flask-database.md %}). {% include_cached copy-clipboard.html %} ~~~ shell - $ cockroach sql --url='postgres://demo:@127.0.0.1:26257?sslmode=require' -f dbinit.sql + cockroach sql \ + --url='postgres://demo:@127.0.0.1:26257?sslmode=require' \ + -f dbinit.sql ~~~ - -1. In the demo cluster terminal, verify that the database schema loaded properly: +1. Verify that the database schema loaded: {% include_cached copy-clipboard.html %} ~~~ sql @@ -61,35 +61,34 @@ For debugging and development purposes, you can use the [`cockroach demo`]({% li ~~~ {{site.data.alerts.callout_info}} -In production, you want to start a secure CockroachDB cluster, with nodes on machines located in different areas of the world. For instructions on deploying a multi-region CockroachDB cluster for this application, using CockroachDB {{ site.data.products.standard }}, see [Deploy a Global, Serverless Application]({% link {{ page.version.version }}/movr-flask-deployment.md %}). +A production deployment should ideally have nodes on machines located in different areas of the world. You will deploy a multi-region CockroachDB cluster for this application using CockroachDB {{ site.data.products.standard }} in the final section of this tutorial series, [Deploy a Global, Serverless Application]({% link {{ page.version.version }}/movr-flask-deployment.md %}). {{site.data.alerts.end}} - ## Set up a virtual development environment For debugging, use [`pipenv`](https://docs.pipenv.org/), a tool that manages dependencies with `pip` and creates virtual environments with `virtualenv`. -1. Run the following command to initialize the project's virtual environment: +1. Initialize the project's virtual environment: {% include_cached copy-clipboard.html %} ~~~ shell - $ pipenv --three + pipenv ~~~ `pipenv` creates a `Pipfile` in the current directory, with the requirements needed for the app. -1. Run the following command to install the packages listed in the `Pipfile`: +1. Install the packages listed in the `Pipfile`: {% include_cached copy-clipboard.html %} ~~~ shell - $ pipenv install + pipenv install ~~~ 1. Activate the virtual environment: {% include_cached copy-clipboard.html %} ~~~ shell - $ pipenv shell + pipenv shell ~~~ From this shell, you can run any Python 3 application with the required dependencies that you listed in the `Pipfile`, and the environment variables that you listed in the `.env` file. You can exit the shell subprocess at any time with a simple `exit` command. @@ -98,21 +97,22 @@ For debugging, use [`pipenv`](https://docs.pipenv.org/), a tool that manages dep {% include_cached copy-clipboard.html %} ~~~ shell - $ python server.py + python server.py ~~~ -1. Navigate to the URL provided to test out the application. By default, this should be http://127.0.0.1:5000/. + To run Python commands within the virtual environment, you do not need to add `3` to the end of the command. For example, running `python3 server.py` instead of the above command results in an error. + +1. Navigate to the application's test URL, which defaults to [http://127.0.0.1:5000/](http://127.0.0.1:5000/). {{site.data.alerts.callout_info}} -In production, you want to [containerize](https://www.docker.com/resources/what-container) your application and deploy it with a deployment orchestration tool, like [Kubernetes](https://kubernetes.io/), or with a serverless deployment service, like [Google Cloud Run](https://cloud.google.com/run). We cover deploying the application with Google Cloud Run in [Deploy a Global Application]({% link {{ page.version.version }}/movr-flask-deployment.md %}). +In production, it is often recommended to [containerize](https://www.docker.com/resources/what-container) your application and deploy it with a deployment orchestration tool like [Kubernetes](https://kubernetes.io/) or with a serverless deployment service like [Google Cloud Run](https://cloud.google.com/run). You will learn to deploy the application with Google Cloud Run in the final section of this tutorial series, [Deploy a Global Application]({% link {{ page.version.version }}/movr-flask-deployment.md %}). {{site.data.alerts.end}} ## Next steps -Now that you've set up a development environment, you can start [developing and debugging the application]({% link {{ page.version.version }}/movr-flask-application.md %}). +Now that you've set up a development environment, you can learn about [developing and debugging the application]({% link {{ page.version.version }}/movr-flask-application.md %}). ## See also - [`movr-flask` on GitHub](https://github.com/cockroachlabs/movr-flask) - [`cockroach demo`]({% link {{ page.version.version }}/cockroach-demo.md %}) -- [Pipenv](https://pipenv.pypa.io) diff --git a/src/current/v24.2/movr-flask-use-case.md b/src/current/v24.2/movr-flask-use-case.md index 026cc845c8a..3ad5a2c80a0 100644 --- a/src/current/v24.2/movr-flask-use-case.md +++ b/src/current/v24.2/movr-flask-use-case.md @@ -13,17 +13,17 @@ MovR is a fictional company that offers users a platform for sharing vehicles, l ## Resiliency and distributed deployments -For an application to be resilient to system failures, the application and database need to be deployed on multiple machines (i.e., part of a distributed deployment). In distributed CockroachDB deployments, all data is replicated and distributed across the instances of the database that make up the deployment. For more information about data replication and distribution in CockroachDB, see [The Raft Protocol in CockroachDB](https://www.youtube.com/watch?v=k5BR9m8o9ec&feature=youtu.be). +For an application to be resilient to system failures, the application and database need to be deployed on multiple machines (i.e., part of a distributed deployment). In distributed CockroachDB deployments, all data is replicated and distributed across the instances of the database that make up the deployment. For more information about data replication and distribution in CockroachDB, refer to [The Raft Protocol in CockroachDB](https://www.youtube.com/watch?v=k5BR9m8o9ec&feature=youtu.be). The replication and distribution of data across multiple machines in a *single region* makes the deployment resilient to individual node failures within the region. Replication and distribution across *multiple regions* makes the deployment resilient to entire regional failures. To achieve the highest level of resiliency, we use a multi-region deployment for MovR database and application. {{site.data.alerts.callout_info}} -In the [example deployment]({% link {{ page.version.version }}/movr-flask-deployment.md %}), the application and the database deployments are separate and not co-located on the same machine. +In the [example deployment]({% link {{ page.version.version }}/movr-flask-deployment.md %}), the application and the database deployments are deployed on separate machines. {{site.data.alerts.end}} ## Latency in global applications -If the MovR application and database are deployed in a single region, latency can become a serious problem when users are located in cities outside the deployment region. Deploying the application and database in multiple regions is not guaranteed to improve latency if client requests are sent to any regional deployment, without consideration for the client's location. +If the MovR application and database are deployed in a single region, latency can become a serious problem when users or client applications are located outside the deployment region. Deploying the application and database in multiple regions can improve latency if client requests are expected to originate from multiple deployment region. Limiting latency improves the user experience, and it can also help you avoid problems with data integrity, like [transaction contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention). @@ -48,16 +48,16 @@ To limit the latency between the application and the database: To limit the latency between client and application server requests, you need to deploy your application such that requests are routed to the application deployment closest to the client. This requires a global load balancer that can redirect traffic to application deployments based on client location. -We cover setting up an external load balancer in [Deploy a Global, Serverless Application]({% link {{ page.version.version }}/movr-flask-deployment.md %}). +You will set up an external load balancer in [Deploy a Global Serverless Application]({% link {{ page.version.version }}/movr-flask-deployment.md %}). ## Next steps -You should now be ready to start [creating a multi-region database schema]({% link {{ page.version.version }}/movr-flask-database.md %}). +Next, learn more about [creating a multi-region database schema]({% link {{ page.version.version }}/movr-flask-database.md %}). ## See also - [`movr-flask` on GitHub](https://github.com/cockroachlabs/movr-flask) -- [CockroachDB terminology]({% link {{ page.version.version }}/architecture/glossary.md %}#cockroachdb-architecture-terms) +- [CockroachDB Terminology]({% link {{ page.version.version }}/architecture/glossary.md %}#cockroachdb-architecture-terms) - [Replication Controls]({% link {{ page.version.version }}/configure-replication-zones.md %}) - [Define Table Partitions]({% link {{ page.version.version }}/partitioning.md %}) - [Topology Patterns]({% link {{ page.version.version }}/topology-patterns.md %}) From cae9ccd01062398ad2d9dac2d042c9aacaa42ee6 Mon Sep 17 00:00:00 2001 From: Matt Linville Date: Wed, 28 Aug 2024 15:30:02 -0700 Subject: [PATCH 09/11] [DOC-9718] Update Spring JPA and JDBC app tutorials for Cloud 2.0 --- .../cockroachcloud/sql-connection-string-free.md | 10 +++++----- .../v24.2/build-a-spring-app-with-cockroachdb-jdbc.md | 10 +++++----- .../v24.2/build-a-spring-app-with-cockroachdb-jpa.md | 10 +++++----- src/current/v24.2/deploy-app-vercel.md | 2 +- 4 files changed, 16 insertions(+), 16 deletions(-) diff --git a/src/current/_includes/cockroachcloud/sql-connection-string-free.md b/src/current/_includes/cockroachcloud/sql-connection-string-free.md index 3b2a0cacc8b..1fcfa37e62a 100644 --- a/src/current/_includes/cockroachcloud/sql-connection-string-free.md +++ b/src/current/_includes/cockroachcloud/sql-connection-string-free.md @@ -2,7 +2,7 @@ {% include_cached copy-clipboard.html %} ~~~ shell - cockroach sql --url 'postgresql://:@:26257/defaultdb?sslmode=verify-full&sslrootcert='$HOME'/.postgresql/root.crt' + cockroach sql --url 'postgresql://:@:26257/defaultdb?sslmode=verify-full&sslrootcert='$HOME'/.postgresql/root.crt' ~~~
@@ -11,7 +11,7 @@ {% include_cached copy-clipboard.html %} ~~~ shell - cockroach sql --url 'postgresql://:@:26257/defaultdb?sslmode=verify-full&sslrootcert='$HOME'/.postgresql/root.crt' + cockroach sql --url 'postgresql://:@:26257/defaultdb?sslmode=verify-full&sslrootcert='$HOME'/.postgresql/root.crt' ~~~
@@ -20,7 +20,7 @@ {% include_cached copy-clipboard.html %} ~~~ shell - cockroach sql --url "postgresql://:@:26257/defaultdb?sslmode=verify-full&sslrootcert=$env:appdata/.postgresql/root.crt" + cockroach sql --url "postgresql://:@:26257/defaultdb?sslmode=verify-full&sslrootcert=$env:appdata/.postgresql/root.crt" ~~~
@@ -28,7 +28,7 @@ Where: - `` is the SQL user. By default, this is your CockroachDB {{ site.data.products.cloud }} account username. - `` is the password for the SQL user. The password will be shown only once in the **Connection info** dialog after creating the cluster. - - `` is the hostname of the CockroachDB {{ site.data.products.serverless }} cluster. + - `` is the hostname of your CockroachDB {{ site.data.products.cloud }} cluster. - `` is a unique string used to identify your cluster when downloading the CA certificate. For example, `12a3bcde-4fa5-6789-1234-56bc7890d123`. - You can find these settings in the **Connection parameters** tab of the **Connection info** dialog. \ No newline at end of file + You can find these settings in the **Connection parameters** tab of the **Connection info** dialog. diff --git a/src/current/v24.2/build-a-spring-app-with-cockroachdb-jdbc.md b/src/current/v24.2/build-a-spring-app-with-cockroachdb-jdbc.md index ccae12a8c4a..f387bdecd4b 100644 --- a/src/current/v24.2/build-a-spring-app-with-cockroachdb-jdbc.md +++ b/src/current/v24.2/build-a-spring-app-with-cockroachdb-jdbc.md @@ -17,7 +17,7 @@ This tutorial assumes you are running under [`SERIALIZABLE`]({% link {{ page.ver ## Step 1. Start CockroachDB -Choose whether to run a local cluster or a free CockroachDB {{ site.data.products.cloud }} cluster. +Choose whether to run a local cluster or a free CockroachDB {{ site.data.products.standard }} cluster.
@@ -39,7 +39,7 @@ Choose whether to run a local cluster or a free CockroachDB {{ site.data.product ### Set up your cluster connection -{% include cockroachcloud/quickstart/set-up-your-cluster-connection.md %} +{% include_cached cockroachcloud/quickstart/set-up-your-cluster-connection.md %} @@ -92,13 +92,13 @@ The [`--also-generate-pkcs8-key` flag]({% link {{ page.version.version }}/cockro
-1. If you haven't already, [download the CockroachDB binary]({% link {{ page.version.version }}/install-cockroachdb.md %}). +1. If you haven't already, [download the CockroachDB SQL Shell binary]({% link {{ page.version.version }}/install-cockroachdb.md %}). 1. Start the [built-in SQL shell]({% link {{ page.version.version }}/cockroach-sql.md %}) using the connection string you got from the CockroachDB {{ site.data.products.cloud }} Console [earlier](#set-up-your-cluster-connection): {% include_cached copy-clipboard.html %} ~~~ shell $ cockroach sql \ - --url 'postgresql://@-..:26257/?sslmode=verify-full&sslrootcert='$HOME'/Library/CockroachCloud/certs/-ca.crt' + --url 'postgresql://@-..:26257/?sslmode=verify-full&sslrootcert='$HOME'/Library/CockroachCloud/certs/-ca.crt' ~~~ 1. Enter your SQL user password. @@ -211,7 +211,7 @@ Where: ~~~ yml ... datasource: - url: jdbc:postgresql://{globalhost}:{port}/{cluster_name}.roach_data?sslmode=verify-full&sslrootcert={path to the CA certificate}/cc-ca.crt + url: jdbc:postgresql://{globalhost}:{port}/{cluster_host}.roach_data?sslmode=verify-full&sslrootcert={path to the CA certificate}/cc-ca.crt username: {username} password: {password} driver-class-name: org.postgresql.Driver diff --git a/src/current/v24.2/build-a-spring-app-with-cockroachdb-jpa.md b/src/current/v24.2/build-a-spring-app-with-cockroachdb-jpa.md index 3d1c1951792..d9e1c60c6dd 100644 --- a/src/current/v24.2/build-a-spring-app-with-cockroachdb-jpa.md +++ b/src/current/v24.2/build-a-spring-app-with-cockroachdb-jpa.md @@ -13,7 +13,7 @@ This tutorial shows you how to build a [Spring Boot](https://spring.io/projects/ ## Step 1. Start CockroachDB -Choose whether to run a local cluster or a free CockroachDB {{ site.data.products.cloud }} cluster. +Choose whether to run a local cluster or a free CockroachDB {{ site.data.products.standard }} cluster.
@@ -35,7 +35,7 @@ Choose whether to run a local cluster or a free CockroachDB {{ site.data.product ### Set up your cluster connection -{% include cockroachcloud/quickstart/set-up-your-cluster-connection.md %} +{% include_cached cockroachcloud/quickstart/set-up-your-cluster-connection.md %}
@@ -88,13 +88,13 @@ The [`--also-generate-pkcs8-key` flag]({% link {{ page.version.version }}/cockro
-1. If you haven't already, [download the CockroachDB binary]({% link {{ page.version.version }}/install-cockroachdb.md %}). +1. If you haven't already, [download the CockroachDB SQL Shell binary]({% link {{ page.version.version }}/install-cockroachdb.md %}). 1. Start the [built-in SQL shell]({% link {{ page.version.version }}/cockroach-sql.md %}) using the connection string you got from the CockroachDB {{ site.data.products.cloud }} Console [earlier](#set-up-your-cluster-connection): {% include_cached copy-clipboard.html %} ~~~ shell $ cockroach sql \ - --url='postgres://{username}:{password}@{global host}:26257/{cluster_name}.defaultdb?sslmode=verify-full&sslrootcert={certs_dir}/cc-ca.crt' + --url='postgres://{username}:{password}@{global host}:26257/{cluster_host}.defaultdb?sslmode=verify-full&sslrootcert={certs_dir}/cc-ca.crt' ~~~ In the connection string copied from the CockroachDB {{ site.data.products.cloud }} Console, your username, password and cluster name are pre-populated. Replace the `{certs_dir}` placeholder with the path to the `certs` directory that you created [earlier](#set-up-your-cluster-connection). @@ -217,7 +217,7 @@ Where: ~~~ yml ... datasource: - url: jdbc:postgresql://{globalhost}:{port}/{cluster_name}.roach_data?sslmode=verify-full&sslrootcert={path to the CA certificate}/cc-ca.crt + url: jdbc:postgresql://{globalhost}:{port}/{cluster_host}.roach_data?sslmode=verify-full&sslrootcert={path to the CA certificate}/cc-ca.crt username: {username} password: {password} driver-class-name: org.postgresql.Driver diff --git a/src/current/v24.2/deploy-app-vercel.md b/src/current/v24.2/deploy-app-vercel.md index ec839972341..25a2703f12b 100644 --- a/src/current/v24.2/deploy-app-vercel.md +++ b/src/current/v24.2/deploy-app-vercel.md @@ -24,7 +24,7 @@ Before starting the tutorial, create a [Vercel](https://vercel.com/signup) accou {% include_cached cockroachcloud/connection-string-standard.md %} -# Step 2. Get the code +## Step 2. Get the code 1. Open the code repository's [GitHub repository](https://github.com/cockroachdb/prisma-examples). 1. Fork it by clicking **Fork** at the top. Netlify requires you to own a Netlify app's repository. From ea29cdfa2ae17fc7a78dbcf60f994375d26538c3 Mon Sep 17 00:00:00 2001 From: Matt Linville Date: Thu, 12 Sep 2024 11:24:40 -0700 Subject: [PATCH 10/11] [DOC-10647] Update Python Todo app --- ...ith-flask-kubernetes-and-cockroachcloud.md | 105 ++++++------------ src/current/cockroachcloud/tools-page.md | 2 +- .../v24.2/cloud-storage-authentication.md | 2 +- 3 files changed, 39 insertions(+), 70 deletions(-) diff --git a/src/current/cockroachcloud/deploy-a-python-to-do-app-with-flask-kubernetes-and-cockroachcloud.md b/src/current/cockroachcloud/deploy-a-python-to-do-app-with-flask-kubernetes-and-cockroachcloud.md index 7b4b0a439ab..30317d88593 100644 --- a/src/current/cockroachcloud/deploy-a-python-to-do-app-with-flask-kubernetes-and-cockroachcloud.md +++ b/src/current/cockroachcloud/deploy-a-python-to-do-app-with-flask-kubernetes-and-cockroachcloud.md @@ -6,13 +6,15 @@ toc_not_nested: true docs_area: --- -This tutorial shows you how to run a sample To-Do app in [Kubernetes](https://kubernetes.io/) with CockroachDB {{ site.data.products.standard }} as the datastore. The app is written in Python with Flask as the web framework and SQLAlchemy for working with SQL data, and the code is [open-source and forkable](https://github.com/cockroachdb/examples-python/tree/master/flask-sqlalchemy). +This tutorial shows you how to run a sample To-Do app in [Kubernetes](https://kubernetes.io/) with CockroachDB {{ site.data.products.standard }} as the datastore. The app is written in Python and uses the Flask web framework and SQLAlchemy for working with SQL data. You can view and download the code from [GitHub](https://github.com/cockroachdb/examples-python/tree/master/flask-sqlalchemy). ## Before you begin -1. If you haven't already, sign up for a CockroachDB {{ site.data.products.cloud }} account. +1. Create a [CockroachDB {{ site.data.products.cloud }}](https://cockroachlabs.cloud/signup?referralId={{page.referral_id}}) account and log in. -1. Install the following tools, if you do not already have them: +1. [Create a CockroachDB {{ site.data.products.standard }} cluster]({% link cockroachcloud/create-your-cluster.md %}) for the sample To-Do app. + +1. On your local system, be sure the following tools are installed: Tool | Purpose -----|-------- @@ -20,36 +22,27 @@ This tutorial shows you how to run a sample To-Do app in [Kubernetes](https://ku [Docker](https://docs.docker.com/v17.12/docker-for-mac/install/) | You'll dockerize your application for running in Kubernetes. [minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/) | This is the tool you'll use to run Kubernetes locally, for your OS. This includes installing a hypervisor and `kubectl`, the command-line tool used to manage Kubernetes from your local workstation. -1. If you haven't already, [create a CockroachDB {{ site.data.products.standard }} cluster]({% link cockroachcloud/create-your-cluster.md %}). - ## Prepare your cluster -- [Step 1. Authorize your local workstation's network](#step-1-authorize-your-local-workstations-network) -- [Step 2. Create a SQL user](#step-2-create-a-sql-user) -- [Step 3. Connect to the cluster](#step-3-connect-to-the-cluster) -- [Step 4. Create the CockroachDB {{ site.data.products.standard }} database](#step-4-create-the-database) -- [Step 5. Generate the application connection string](#step-5-generate-the-application-connection-string) +Follow the steps in this section to prepare your cluster for the example To-DO app. ### Step 1. Authorize your local workstation's network -Before you connect to your CockroachDB {{ site.data.products.standard }} cluster, you need to authorize your network by adding the public IP address of the workstation to the allowlist. Otherwise, connections from this workstation will be rejected. - -Once you are [logged in](https://cockroachlabs.cloud/), you can use the Console to authorize your network: +Before you can connect to your CockroachDB {{ site.data.products.standard }} cluster, you need to authorize your network by adding the public IP address of the workstation to the [allowlist]({% link cockroachcloud/network-authorization.md %}#ip-allowlisting). Otherwise, connections from this workstation will be rejected. -1. In the left navigation bar, click **Networking**. -1. Click the **Add Network** button in the right corner. The **Add Network** dialog displays. +1. In the left navigation bar of the CockroachDB {{ site.data.products.cloud }} Console, click **Networking**. +1. Click **Add Network**. The **Add Network** dialog displays. 1. (Optional) Enter a descriptive name for the network. -1. From the **Network** dropdown, select **Current Network**. Your local machine's IP address will be auto-populated in the box. -1. Select both networks: **DB Console to monitor the cluster** and **CockroachDB Client to access the databases**. - - The **DB Console** refers to the cluster's DB Console, where you can observe your cluster's health and performance. For more information, see [DB Console Overview]({% link {{site.current_cloud_version}}/ui-overview.md %}). - +1. From the **Network** selector, choose **Current Network**. Your local machine's IP address will be auto-populated in the box. +1. Select both **DB Console to monitor the cluster** and **CockroachDB Client to access the databases**. The first option allows connections from this IP to the cluster's [DB Console]({% link {{site.current_cloud_version}}/ui-overview.md %}), where you can observe your cluster's health and performance. The second option allows SQL clients to connect from this IP. 1. Click **Apply**. ### Step 2. Create a SQL user {% include cockroachcloud/cockroachcloud-ask-admin.md %} +To connect from a SQL client, your cluster must have at least one SQL user. To create a SQL user: + 1. In the left navigation bar, click **SQL Users**. 1. Click **Add User**. The **Add User** dialog displays. 1. Enter a username and click **Generate & Save Password**. @@ -58,9 +51,9 @@ Once you are [logged in](https://cockroachlabs.cloud/), you can use the Console Currently, all new SQL users are created with admin privileges. For more information and to change the default settings, see [Managing SQL users on a cluster]({% link cockroachcloud/managing-access.md %}#manage-sql-users-on-a-cluster). -### Step 3. Connect to the cluster +### Step 3. Find the cluster's connection details -In this step, you connect both your application and your local system to the cluster. +In this step, you find the connection details that allow both your application and your local system to connect to the cluster. 1. In the top right corner of the CockroachDB {{ site.data.products.cloud }} Console, click the **Connect** button. @@ -71,15 +64,13 @@ In this step, you connect both your application and your local system to the clu The **Connect** page of the **Connection info** dialog displays. -1. Select the **Command Line** tab. +1. Select the **Command Line** tab to find the details you can use to connect from your local workstation's terminal. 1. If CockroachDB is not installed locally, copy the command to download and install it. In your terminal, run the command. -1. Select the **Connection string** tab. +1. Copy the `cockroach sql` command. In the command, add a `:` character after the username and before the `@` character, then paste the password for the SQL user you created earlier. To connect to your cluster from the command line, you can run this command. +1. Select the **Connection string** tab to find the details you can use to connect from your application. 1. If the CA certificate for the cluster is not downloaded locally, copy the command to download it. In your terminal, run the command. -1. Copy the connection string, which begins with `postgresql://`. This will be used to connect your application to CockroachDB {{ site.data.products.standard }}. +1. Copy the connection string, which begins with `postgresql://`. You will add this string to the example To-Do app so that it can connect to your cluster. In the string, add a `:` character after the username and before the `@` character, then paste the password for the SQL user you created earlier. 1. Click **Close**. -1. Use the connection string to connect to the cluster using `cockroach sql`: - - {% include cockroachcloud/sql-connection-string.md %} ### Step 4. Create the database @@ -92,23 +83,25 @@ On your local workstation's terminal:

-1. Use the `cockroach sql` from [Step 3. Connect to the cluster](#step-3-connect-to-the-cluster) to connect to the cluster using the binary you just configured. +1. Use the **Command Line** `cockroach sql` command to connect to the cluster from a terminal: -1. Create a database `todos`: + {% include cockroachcloud/sql-connection-string.md %} + +1. After connecting to the cluster, create a database named `todos`: {% include_cached copy-clipboard.html %} ~~~ sql > CREATE DATABASE todos; ~~~ -1. Use database `todos`: +1. Select the `todos` database: {% include_cached copy-clipboard.html %} ~~~ sql > USE todos; ~~~ -1. Create a table `todos`: +1. Create a table `todos` with the following schema: {% include_cached copy-clipboard.html %} ~~~ sql @@ -123,19 +116,6 @@ On your local workstation's terminal: ); ~~~ -### Step 5. Generate the application connection string - - 1. In the top right corner of the Console, click the **Connect** button. - - The **Connect** dialog displays. - - 1. From the **User** dropdown, select the SQL user you created in [Step 2](#step-2-create-a-sql-user). - 1. Select a **Region** to connect to. - 1. From the **Database** dropdown, select `todos`. - 1. On the **Connection String** tab, click **Copy connection string**. - - Copy the application connection string to an accessible location. You will update the password and certificate path in the next step. - ## Build the app - [Step 1. Configure the sample Python app](#step-1-configure-the-sample-python-app) @@ -159,11 +139,11 @@ In a new terminal: $ cd examples-python/flask-sqlalchemy ~~~ -1. In the `hello.cfg` file, replace the value for the `SQLALCHEMY_DATABASE_URI` with the application connection string you generated in [Step 5. Generate the application connection string](#step-5-generate-the-application-connection-string) and save the file. +1. In the `hello.cfg` file, replace the value for the `SQLALCHEMY_DATABASE_URI` with the application connection string you generated in [Step 3. Find the cluster's connection details](#step-3-find-the-clusters-connection-details). Replace `defaultdb` with `todos` to connect to the `todos` database. Save the file. {% include_cached copy-clipboard.html %} ~~~ - SQLALCHEMY_DATABASE_URI = 'cockroachdb://@:26257/todos?sslmode=verify-full&sslrootcert=$Home/Library/CockroachCloud/certs/-ca.crt' + SQLALCHEMY_DATABASE_URI = 'cockroachdb://{username}:{password}@{host}:26257/todos?sslmode=verify-full&sslrootcert=$Home/Library/CockroachCloud/certs/{cluster-name}-ca.crt' ~~~ {{site.data.alerts.callout_info}} @@ -174,7 +154,7 @@ In a new terminal: ### Step 2. Test the application locally -1. Install SQLAlchemy, as well as a CockroachDB Python package that accounts for some differences between CockroachDB and PostgreSQL: +1. Install the following Python packages to satisfy the example app's dependencies. The `sqlalchemy-cockroachdb` package accounts for some differences between CockroachDB and PostgreSQL: {% include_cached copy-clipboard.html %} ~~~ shell @@ -200,15 +180,7 @@ In a new terminal: ## Deploy the app -{{site.data.alerts.callout_info}} -These steps focus on deploying your app locally. For production Kubernetes deployments, use a service like GKE. -{{site.data.alerts.end}} - -- [Step 1. Start a local Kubernetes cluster](#step-1-start-a-local-kubernetes-cluster) -- [Step 2. Create a Kubernetes secret](#step-2-create-a-kubernetes-secret) -- [Step 3. Change certificate directory path in configuration file](#step-3-change-certificate-directory-path-in-configuration-file) -- [Step 4. Dockerize the application](#step-4-dockerize-the-application) -- [Step 5. Deploy the application](#step-5-deploy-the-application) +These steps show how to deploy your app locally using Kubernetes. ### Step 1. Start a local Kubernetes cluster @@ -227,7 +199,8 @@ Create a Kubernetes secret to store the CA certificate you downloaded earlier: {% include_cached copy-clipboard.html %} ~~~ shell -$ kubectl create secret generic -secret --from-file $Home/Library/CockroachCloud/certs/-ca.crt +$ kubectl create secret generic -secret \ + --from-file $Home/Library/CockroachCloud/certs/-ca.crt ~~~ Verify the Kubernetes secret was created: @@ -252,13 +225,9 @@ In the `hello.cfg` file in the `flask-alchemy` folder, replace the certificate d SQLALCHEMY_DATABASE_URI = 'cockroachdb://@:26257/todos?sslmode=verify-full&sslrootcert=$Home/Library/CockroachCloud/certs/-ca.crt' ~~~ -{{site.data.alerts.callout_info}} -You must use the `cockroachdb://` prefix in the URL passed to [`sqlalchemy.create_engine`](https://docs.sqlalchemy.org/core/engines.html#sqlalchemy.create_engine) to make sure the [`cockroachdb`](https://github.com/cockroachdb/sqlalchemy-cockroachdb) dialect is used. Using the `postgres://` URL prefix to connect to your CockroachDB cluster will not work. -{{site.data.alerts.end}} - -### Step 4. Dockerize the application +### Step 4. Create a container with the application -1. In the `flask-sqlalchemy` folder, create a file named `Dockerfile` and copy the following code into the file: +1. In the `flask-sqlalchemy` folder, create a file named `Dockerfile` with the following contents: {% include_cached copy-clipboard.html %} ~~~ @@ -307,7 +276,7 @@ You must use the `cockroachdb://` prefix in the URL passed to [`sqlalchemy.creat ### Step 5. Deploy the application -1. In the `flask-alchemy` folder, create a file named `app-deployment.yaml` and copy the following code into the file. Replace the `` placeholder with the SQL user's username that you created [while preparing the cluster](#step-2-create-a-sql-user): +1. In the `flask-alchemy` folder, create a file named `app-deployment.yaml` and copy the following code into the file. Replace the `{username}` placeholder with the SQL user's username that you created [while preparing the cluster](#step-2-create-a-sql-user): {% include_cached copy-clipboard.html %} ~~~ @@ -342,7 +311,7 @@ You must use the `cockroachdb://` prefix in the URL passed to [`sqlalchemy.creat volumes: - name: ca-certs secret: - secretName: -secret + secretName: {username}-secret --- apiVersion: v1 kind: Service @@ -372,7 +341,7 @@ You must use the `cockroachdb://` prefix in the URL passed to [`sqlalchemy.creat service/appdeploy created ~~~ -1. Verify that the deployment and server were created: +1. Verify that the deployment is ready and the load balancer service is pending: {% include_cached copy-clipboard.html %} ~~~ shell @@ -440,7 +409,7 @@ You must use the `cockroachdb://` prefix in the URL passed to [`sqlalchemy.creat 1. On the Console, navigate to the cluster's **Tools** page and click **Open DB Console**. - You can also access the DB Console by navigating to `https://crdb.io:8080/#/metrics/overview/cluster`. Replace the `` placeholder with the name of your cluster. + You can also access the DB Console by navigating to `https://{cluster-name}crdb.io:8080/#/metrics/overview/cluster`. Replace `` with the name of your cluster. 1. Enter the SQL user's username and password you created while [preparing the cluster](#step-2-create-a-sql-user). diff --git a/src/current/cockroachcloud/tools-page.md b/src/current/cockroachcloud/tools-page.md index b359e95d712..dd876ad832b 100644 --- a/src/current/cockroachcloud/tools-page.md +++ b/src/current/cockroachcloud/tools-page.md @@ -13,7 +13,7 @@ The **Tools** page is accessible on CockroachDB {{ site.data.products.standard } To view the **Tools** page, select a cluster from the [**Clusters** page]({% link cockroachcloud/cluster-management.md %}#view-clusters-page), and click **Tools** in the **Monitoring** section of the left side navigation. -## Monitor CockroachDB {{ site.data.products.cloud }} with Datadog +## Monitor CockroachDB Cloud with Datadog The [CockroachDB {{ site.data.products.cloud }} integration for Datadog](https://docs.datadoghq.com/integrations/cockroachdb_dedicated/) enables data collection and alerting on a [subset of CockroachDB metrics](#available-metrics) available at the [Prometheus endpoint]({% link {{site.current_cloud_version}}/monitoring-and-alerting.md %}#prometheus-endpoint), using the Datadog platform. diff --git a/src/current/v24.2/cloud-storage-authentication.md b/src/current/v24.2/cloud-storage-authentication.md index 59ab2ef6f34..e178f5162e8 100644 --- a/src/current/v24.2/cloud-storage-authentication.md +++ b/src/current/v24.2/cloud-storage-authentication.md @@ -58,7 +58,7 @@ To use `implicit` authentication on a CockroachDB {{ site.data.products.cloud }} ### Use implicit authentication with your own IAM role -For self-hosted deployments, follow these instructions. For CockroachDB {{ site.data.products.advanced }} deployments, you can either follow these instructions or you can [use implicit authentication together with the service account that CockroachDB {{ site.data.products.cloud }} automatically creates](/docs/v23.2/cloud-storage-authentication.html?filters=aws#use-implicit-authentication-advanced). +For self-hosted deployments, follow these instructions. For CockroachDB {{ site.data.products.advanced }} deployments, you can either follow these instructions or you can [use implicit authentication together with the service account that CockroachDB {{ site.data.products.cloud }} automatically creates](#use-implicit-authentication-advanced). To limit the control access to your Amazon S3 buckets, you can create IAM roles for users to assume. IAM roles do not have an association to a particular user. The role contains permissions that define the operations a user (or [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal)) can complete. An IAM user can then assume a role to undertake a CockroachDB backup, restore, import, etc. As a result, the IAM user only has access to the assigned role, rather than having unlimited access to an S3 bucket. From 48c83164e0e5934bc6987b57c341b4564d5e9729 Mon Sep 17 00:00:00 2001 From: Matt Linville Date: Thu, 12 Sep 2024 11:43:47 -0700 Subject: [PATCH 11/11] Propagate v23.1 link fixes to v22.1 pages to fix links --- .../_includes/v22.1/connect/connection-url.md | 19 + .../_includes/v22.1/connect/core-note.md | 7 + .../v22.1/connect/jdbc-connection-url.md | 19 + src/current/_includes/v22.1/core-note.md | 7 + .../_includes/v22.1/faq/what-is-crdb.md | 7 + .../_includes/v22.1/jdbc-connection-url.md | 19 + src/current/v22.1/connect-to-the-database.md | 384 ++++++++++++------ .../v22.1/frequently-asked-questions.md | 76 ++-- 8 files changed, 367 insertions(+), 171 deletions(-) create mode 100644 src/current/_includes/v22.1/connect/connection-url.md create mode 100644 src/current/_includes/v22.1/connect/core-note.md create mode 100644 src/current/_includes/v22.1/connect/jdbc-connection-url.md create mode 100644 src/current/_includes/v22.1/core-note.md create mode 100644 src/current/_includes/v22.1/faq/what-is-crdb.md create mode 100644 src/current/_includes/v22.1/jdbc-connection-url.md diff --git a/src/current/_includes/v22.1/connect/connection-url.md b/src/current/_includes/v22.1/connect/connection-url.md new file mode 100644 index 00000000000..ae994bb3047 --- /dev/null +++ b/src/current/_includes/v22.1/connect/connection-url.md @@ -0,0 +1,19 @@ +
+Set a `DATABASE_URL` environment variable to your connection string. + +{% include_cached copy-clipboard.html %} +~~~ shell +export DATABASE_URL="{connection string}" +~~~ + +
+ +
+Set a `DATABASE_URL` environment variable to your connection string. + +{% include_cached copy-clipboard.html %} +~~~ shell +$env:DATABASE_URL = "{connection string}" +~~~ + +
\ No newline at end of file diff --git a/src/current/_includes/v22.1/connect/core-note.md b/src/current/_includes/v22.1/connect/core-note.md new file mode 100644 index 00000000000..7b701cafb80 --- /dev/null +++ b/src/current/_includes/v22.1/connect/core-note.md @@ -0,0 +1,7 @@ +{{site.data.alerts.callout_info}} +The connection information shown on this page uses [client certificate and key authentication]({% link {{ page.version.version }}/authentication.md %}#client-authentication) to connect to a secure, CockroachDB {{ site.data.products.core }} cluster. + +To connect to a CockroachDB {{ site.data.products.core }} cluster with client certificate and key authentication, you must first [generate server and client certificates]({% link {{ page.version.version }}/authentication.md %}#using-digital-certificates-with-cockroachdb). + +For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)]({% link {{ page.version.version }}/secure-a-cluster.md %}). +{{site.data.alerts.end}} diff --git a/src/current/_includes/v22.1/connect/jdbc-connection-url.md b/src/current/_includes/v22.1/connect/jdbc-connection-url.md new file mode 100644 index 00000000000..c055a390b4e --- /dev/null +++ b/src/current/_includes/v22.1/connect/jdbc-connection-url.md @@ -0,0 +1,19 @@ +Set a `JDBC_DATABASE_URL` environment variable to your JDBC connection string. + +
+ +{% include_cached copy-clipboard.html %} +~~~ shell +export JDBC_DATABASE_URL="{connection string}" +~~~ + +
+ +
+ +{% include_cached copy-clipboard.html %} +~~~ shell +$env:JDBC_DATABASE_URL = "{connection string}" +~~~ + +
diff --git a/src/current/_includes/v22.1/core-note.md b/src/current/_includes/v22.1/core-note.md new file mode 100644 index 00000000000..7b701cafb80 --- /dev/null +++ b/src/current/_includes/v22.1/core-note.md @@ -0,0 +1,7 @@ +{{site.data.alerts.callout_info}} +The connection information shown on this page uses [client certificate and key authentication]({% link {{ page.version.version }}/authentication.md %}#client-authentication) to connect to a secure, CockroachDB {{ site.data.products.core }} cluster. + +To connect to a CockroachDB {{ site.data.products.core }} cluster with client certificate and key authentication, you must first [generate server and client certificates]({% link {{ page.version.version }}/authentication.md %}#using-digital-certificates-with-cockroachdb). + +For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)]({% link {{ page.version.version }}/secure-a-cluster.md %}). +{{site.data.alerts.end}} diff --git a/src/current/_includes/v22.1/faq/what-is-crdb.md b/src/current/_includes/v22.1/faq/what-is-crdb.md new file mode 100644 index 00000000000..28857ed61fa --- /dev/null +++ b/src/current/_includes/v22.1/faq/what-is-crdb.md @@ -0,0 +1,7 @@ +CockroachDB is a [distributed SQL](https://www.cockroachlabs.com/blog/what-is-distributed-sql/) database built on a transactional and strongly-consistent key-value store. It **scales** horizontally; **survives** disk, machine, rack, and even datacenter failures with minimal latency disruption and no manual intervention; supports **strongly-consistent** ACID transactions; and provides a familiar **SQL** API for structuring, manipulating, and querying data. + +CockroachDB is inspired by Google's [Spanner](http://research.google.com/archive/spanner.html) and [F1](http://research.google.com/pubs/pub38125.html) technologies, and the [source code](https://github.com/cockroachdb/cockroach) is freely available. + +{{site.data.alerts.callout_success}} +For a deeper dive into CockroachDB's capabilities and how it fits into the database landscape, take the free [**Intro to Distributed SQL and CockroachDB**](https://university.cockroachlabs.com/courses/course-v1:crl+intro-to-distributed-sql-and-cockroachdb+self-paced/about) course on Cockroach University. +{{site.data.alerts.end}} \ No newline at end of file diff --git a/src/current/_includes/v22.1/jdbc-connection-url.md b/src/current/_includes/v22.1/jdbc-connection-url.md new file mode 100644 index 00000000000..c055a390b4e --- /dev/null +++ b/src/current/_includes/v22.1/jdbc-connection-url.md @@ -0,0 +1,19 @@ +Set a `JDBC_DATABASE_URL` environment variable to your JDBC connection string. + +
+ +{% include_cached copy-clipboard.html %} +~~~ shell +export JDBC_DATABASE_URL="{connection string}" +~~~ + +
+ +
+ +{% include_cached copy-clipboard.html %} +~~~ shell +$env:JDBC_DATABASE_URL = "{connection string}" +~~~ + +
diff --git a/src/current/v22.1/connect-to-the-database.md b/src/current/v22.1/connect-to-the-database.md index 29d085f32ad..7f16cbfd273 100644 --- a/src/current/v22.1/connect-to-the-database.md +++ b/src/current/v22.1/connect-to-the-database.md @@ -5,30 +5,40 @@ toc: true docs_area: develop --- -This page documents the required connection configuration for [fully-supported third-party tools](third-party-database-tools.html). +This page documents the required connection configuration for [fully-supported third-party tools]({% link {{ page.version.version }}/third-party-database-tools.md %}). -For a list of all supported cluster connection parameters, see the [`cockroach` Connection Parameters](connection-parameters.html). +For a list of all supported cluster connection parameters, see the [`cockroach` Connection Parameters]({% link {{ page.version.version }}/connection-parameters.md %}). -For a list of community-supported third-party tools, see [Third-Party Tools Supported by the Community](community-tooling.html). CockroachDB supports both native drivers and the PostgreSQL wire protocol. Most client drivers and ORM frameworks connect to CockroachDB like they connect to PostgreSQL. +For a list of community-supported third-party tools, see [Third-Party Tools Supported by the Community]({% link {{ page.version.version }}/community-tooling.md %}). CockroachDB supports both native drivers and the PostgreSQL wire protocol. Most client drivers and ORM frameworks connect to CockroachDB like they connect to PostgreSQL. -
+## Step 1. Select your deployment -{{site.data.alerts.callout_info}} -The connection information shown on this page uses [client certificate and key authentication](authentication.html#client-authentication) to connect to a secure, CockroachDB {{ site.data.products.core }} cluster. +
+ + + +
-To connect to a CockroachDB {{ site.data.products.core }} cluster with client certificate and key authentication, you must first [generate server and client certificates](authentication.html#using-digital-certificates-with-cockroachdb). +
+To connect to a CockroachDB {{ site.data.products.cloud }} cluster, you need a general connection string or connection parameters, which include the username, host, database, and port. To find these, open the **Connect** dialog for your cluster in the [CockroachDB {{ site.data.products.cloud }} Console](https://cockroachlabs.cloud) and select either **General connection string** or **Parameters only** as the option. +
-For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](secure-a-cluster.html). -{{site.data.alerts.end}} +
+To connect to a CockroachDB {{ site.data.products.core }} cluster, you need the [general connection string]({% link {{ page.version.version }}/connection-parameters.md %}#connect-using-a-url) or [connection parameters]({% link {{ page.version.version }}/connection-parameters.md %}#connect-using-discrete-parameters) for your cluster. +The connection strings and parameters for your cluster are output when you [start the cluster]({% link {{ page.version.version }}/cockroach-start.md %}#standard-output).
+## Step 2. Select your OS +
- - - + + +
+## Step 3. Select your language +
@@ -37,14 +47,100 @@ For instructions on starting a secure cluster, see [Start a Local Cluster (Secur
-
+## Step 4. Select your driver or ORM +
+
+ +
+
+ + + + +
+
+ +
+
+ + + +
+
+ +
+
+ + +
+
+ +
+
+ + +
+
+ +## Step 5. Connect to the cluster + +
+
+ +{% include {{ page.version.version }}/connect/connection-url.md %} + +
+
+ +
+
+ +{% include {{ page.version.version }}/connect/connection-url.md %} + +
+
+ +
+
+ +{% include {{ page.version.version }}/connect/connection-url.md %} + +
+
+ +
+
+ +{% include {{ page.version.version }}/connect/connection-url.md %} + +
+
+ +
+ +
+The **Connect to cluster** dialog shows information about how to connect to your cluster. + +1. Select **Java** from the **Select option** dropdown. +1. Copy the `JDBC_DATABASE_URL` environment variable command provided and save it in a secure location. +
+ +
+Copy the JDBC connection string from the `sql (JDBC)` field in the output from when you started the cluster. +
+ +{% include {{ page.version.version }}/connect/jdbc-connection-url.md %} + +
+ +
@@ -65,7 +161,7 @@ Where `DATABASE_URL` is an environment variable set to a valid CockroachDB conne node-postgres accepts the following format for CockroachDB connection strings: -
+
{% include_cached copy-clipboard.html %} ~~~ @@ -74,7 +170,7 @@ postgresql://:@:/?sslmode=verify-full
-
+
{% include_cached copy-clipboard.html %} ~~~ @@ -90,6 +186,8 @@ postgresql://:@:/?sslmode=verify-full& postgresql://@:/?sslmode=verify-full&sslrootcert=&sslcert=&sslkey= ~~~ +{% include {{ page.version.version }}/connect/core-note.md %} +
For more information about connecting with node-postgres, see the [official node-postgres documentation](https://node-postgres.com/features/connecting). @@ -114,7 +212,7 @@ Where `DATABASE_URL` is an environment variable set to a valid CockroachDB conne Sequelize accepts the following format for CockroachDB connection strings: -
+
{% include_cached copy-clipboard.html %} ~~~ @@ -123,7 +221,7 @@ postgresql://:@:/?sslmode=verify-full
-
+
{% include_cached copy-clipboard.html %} ~~~ @@ -139,6 +237,8 @@ postgresql://:@:/?sslmode=verify-full& postgresql://@:/?sslmode=verify-full&sslrootcert=&sslcert=&sslkey= ~~~ +{% include {{ page.version.version }}/connect/core-note.md %} +
{{site.data.alerts.callout_info}} @@ -159,9 +259,9 @@ For example, suppose that you are defining the `DataSource` for your application
-
+
-CockroachDB {{ site.data.products.serverless }} requires you to specify the `type`, `url`, and `ssl` properties: +CockroachDB {{ site.data.products.basic }} and {{ site.data.products.standard }} requires you to specify the `type`, `url`, and `ssl` properties: {% include_cached copy-clipboard.html %} ~~~ ts @@ -186,9 +286,9 @@ postgresql://:@:/
-
+
-CockroachDB {{ site.data.products.dedicated }} requires you to specify the `type`, `url`, and `ssl` properties: +CockroachDB {{ site.data.products.advanced }} requires you to specify the `type`, `url`, and `ssl` properties: {% include_cached copy-clipboard.html %} ~~~ ts @@ -207,7 +307,7 @@ export const AppDataSource = new DataSource({ Where: - `DATABASE_URL` is an environment variable set to a valid CockroachDB connection string. -- `CA_CERT` is an environment variable set to the root certificate [downloaded from the CockroachDB Cloud Console](../cockroachcloud/authentication.html#node-identity-verification). +- `CA_CERT` is an environment variable set to the root certificate [downloaded from the CockroachDB Cloud Console]({% link cockroachcloud/authentication.md %}#node-identity-verification). TypeORM accepts the following format for CockroachDB connection strings: @@ -241,9 +341,11 @@ export const AppDataSource = new DataSource({ Where: - `DATABASE_URL` is an environment variable set to a valid CockroachDB connection string. -- `CA_CERT` is an environment variable set to the root certificate.
You can generate this certificate with [`cockroach cert create-ca`](cockroach-cert.html#subcommands), or you can use a [custom CA cert](create-security-certificates-custom-ca.html). -- `CLIENT_KEY` is an environment variable set to the [client key](cockroach-cert.html#client-key-and-certificates) for the user connecting to the cluster.
You can generate this key with [`cockroach cert create-client`](cockroach-cert.html#subcommands). -- `CLIENT_CERT` is an environment variable set to the [client certificate](cockroach-cert.html#client-key-and-certificates) for the user connecting to the cluster.
You can generate this certificate with [`cockroach cert create-client`](cockroach-cert.html#subcommands). +- `CA_CERT` is an environment variable set to the root certificate.
You can generate this certificate with [`cockroach cert create-ca`]({% link {{ page.version.version }}/cockroach-cert.md %}#subcommands), or you can use a [custom CA cert]({% link {{ page.version.version }}/create-security-certificates-custom-ca.md %}). +- `CLIENT_KEY` is an environment variable set to the [client key]({% link {{ page.version.version }}/cockroach-cert.md %}#client-key-and-certificates) for the user connecting to the cluster.
You can generate this key with [`cockroach cert create-client`]({% link {{ page.version.version }}/cockroach-cert.md %}#subcommands). +- `CLIENT_CERT` is an environment variable set to the [client certificate]({% link {{ page.version.version }}/cockroach-cert.md %}#client-key-and-certificates) for the user connecting to the cluster.
You can generate this certificate with [`cockroach cert create-client`]({% link {{ page.version.version }}/cockroach-cert.md %}#subcommands). + +{% include {{ page.version.version }}/connect/core-note.md %} TypeORM accepts the following format for CockroachDB connection strings: @@ -294,7 +396,7 @@ Where `DATABASE_URL` is an environment variable set to a valid CockroachDB conne Prisma accepts the following format for CockroachDB connection strings: -
+
{% include_cached copy-clipboard.html %} ~~~ @@ -303,10 +405,10 @@ postgresql://:@:/?sslmode=verify-full
-
+
{% include_cached copy-clipboard.html %} -~~~ +~~~ postgresql://:@:/?sslmode=verify-full&sslrootcert= ~~~ @@ -315,10 +417,12 @@ postgresql://:@:/?sslmode=verify-full&
{% include_cached copy-clipboard.html %} -~~~ +~~~ postgresql://@:/?sslmode=verify-full&sslrootcert=&sslcert=&sslkey= ~~~ +{% include {{ page.version.version }}/connect/core-note.md %} +
For more information about connecting with Prisma, see the [official Prisma documentation](https://www.prisma.io/cockroachdb). @@ -327,11 +431,11 @@ For more information about connecting with Prisma, see the [official Prisma docu ## Connection parameters -
+
Parameter | Description ----------|------------ -`` | The [SQL user](security-reference/authorization.html#sql-users) connecting to the cluster. +`` | The [SQL user]({% link {{ page.version.version }}/security-reference/authorization.md %}#sql-users) connecting to the cluster. `` | The password for the SQL user connecting to the cluster. `` | The host on which the CockroachDB node is running. `` | The port at which the CockroachDB node is listening. @@ -339,16 +443,16 @@ Parameter | Description
-
+
Parameter | Description ----------|------------ -`` | The [SQL user](security-reference/authorization.html#sql-users) connecting to the cluster. +`` | The [SQL user]({% link {{ page.version.version }}/security-reference/authorization.md %}#sql-users) connecting to the cluster. `` | The password for the SQL user connecting to the cluster. `` | The host on which the CockroachDB node is running. `` | The port at which the CockroachDB node is listening. `` | The name of the (existing) database. -`` | The path to the root certificate that you [downloaded from the CockroachDB Cloud Console](../cockroachcloud/authentication.html#node-identity-verification). +`` | The path to the root certificate that you [downloaded from the CockroachDB Cloud Console]({% link cockroachcloud/authentication.md %}#node-identity-verification).
@@ -356,32 +460,26 @@ Parameter | Description Parameter | Description ----------|------------ -`` | The [SQL user](security-reference/authorization.html#sql-users) connecting to the cluster. +`` | The [SQL user]({% link {{ page.version.version }}/security-reference/authorization.md %}#sql-users) connecting to the cluster. `` | The host on which the CockroachDB node is running. `` | The port at which the CockroachDB node is listening. `` | The name of the (existing) database. -`` | The path to the root certificate.
You can generate this certificate with [`cockroach cert create-ca`](cockroach-cert.html#subcommands), or you can use a [custom CA cert](create-security-certificates-custom-ca.html). -`` | The path to the [client certificate](cockroach-cert.html#client-key-and-certificates) for the user connecting to the cluster.
You can generate this certificate with [`cockroach cert create-client`](cockroach-cert.html#subcommands). -`` | The path to the [client key](cockroach-cert.html#client-key-and-certificates) for the user connecting to the cluster.
You can generate this key with [`cockroach cert create-client`](cockroach-cert.html#subcommands). +`` | The path to the root certificate.
You can generate this certificate with [`cockroach cert create-ca`]({% link {{ page.version.version }}/cockroach-cert.md %}#subcommands), or you can use a [custom CA cert]({% link {{ page.version.version }}/create-security-certificates-custom-ca.md %}). +`` | The path to the [client certificate]({% link {{ page.version.version }}/cockroach-cert.md %}#client-key-and-certificates) for the user connecting to the cluster.
You can generate this certificate with [`cockroach cert create-client`]({% link {{ page.version.version }}/cockroach-cert.md %}#subcommands). +`` | The path to the [client key]({% link {{ page.version.version }}/cockroach-cert.md %}#client-key-and-certificates) for the user connecting to the cluster.
You can generate this key with [`cockroach cert create-client`]({% link {{ page.version.version }}/cockroach-cert.md %}#subcommands). -
+{% include {{ page.version.version }}/connect/core-note.md %}
-
- -
- - - -
+
-
+
{{site.data.alerts.callout_info}} -To connect to a CockroachDB {{ site.data.products.serverless }} cluster from a Python application, you must have a valid CA certificate located at ~/.postgresql/root.crt.
For instructions on downloading a CA certificate from the CockroachDB {{ site.data.products.cloud }} Console, see Connect to a CockroachDB {{ site.data.products.serverless }} Cluster. +To connect to a CockroachDB {{ site.data.products.basic }} or {{ site.data.products.standard }} cluster from a Python application, you must have a valid CA certificate located at ~/.postgresql/root.crt.
For instructions on downloading a CA certificate from the CockroachDB {{ site.data.products.cloud }} Console, see [Connect to a CockroachDB {{ site.data.products.basic }} Cluster]({% link cockroachcloud/connect-to-a-basic-cluster.md %}) or [Connect to a CockroachDB {{ site.data.products.standard }} Cluster]({% link cockroachcloud/connect-to-your-cluster.md %}. {{site.data.alerts.end}}
@@ -404,7 +502,7 @@ Where `DATABASE_URL` is an environment variable set to a valid CockroachDB conne Psycopg2 accepts the following format for CockroachDB connection strings: -
+
{% include_cached copy-clipboard.html %} ~~~ @@ -413,7 +511,7 @@ postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full
-
+
{% include_cached copy-clipboard.html %} ~~~ @@ -429,6 +527,8 @@ postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full& postgresql://{username}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key} ~~~ +{% include {{ page.version.version }}/connect/core-note.md %} +
For more information about connecting with Psycopg, see the [official Psycopg documentation](https://www.psycopg.org/docs). @@ -454,7 +554,7 @@ Where `DATABASE_URL` is an environment variable set to a valid CockroachDB conne Psycopg accepts the following format for CockroachDB connection strings: -
+
{% include_cached copy-clipboard.html %} ~~~ @@ -463,7 +563,7 @@ postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full
-
+
{% include_cached copy-clipboard.html %} ~~~ @@ -479,6 +579,8 @@ postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full& postgresql://{username}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key} ~~~ +{% include {{ page.version.version }}/connect/core-note.md %} +
For more information about connecting with Psycopg, see the [official Psycopg documentation](https://www.psycopg.org/psycopg3/docs/basic/index.html). @@ -487,7 +589,7 @@ For more information about connecting with Psycopg, see the [official Psycopg do
-To connect to CockroachDB with [SQLAlchemy](http://docs.sqlalchemy.org/en/latest/), [create an `Engine` object](https://docs.sqlalchemy.org/en/14/core/engines.html) by passing the connection string to the `create_engine` function. +To connect to CockroachDB with [SQLAlchemy](http://docs.sqlalchemy.org/), [create an `Engine` object](https://docs.sqlalchemy.org/core/engines.html) by passing the connection string to the `create_engine` function. For example: @@ -504,7 +606,7 @@ Where `DATABASE_URL` is an environment variable set to a valid CockroachDB conne SQLAlchemy accepts the following format for CockroachDB connection strings: -
+
{% include_cached copy-clipboard.html %} ~~~ @@ -513,7 +615,7 @@ cockroachdb://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full
-
+
{% include_cached copy-clipboard.html %} ~~~ @@ -529,13 +631,26 @@ cockroachdb://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full cockroachdb://{username}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key} ~~~ +{% include {{ page.version.version }}/connect/core-note.md %} +
{{site.data.alerts.callout_info}} To connect to CockroachDB with SQLAlchemy, you must install the [CockroachDB SQLAlchemy adapter](https://github.com/cockroachdb/sqlalchemy-cockroachdb). {{site.data.alerts.end}} -For more information about connecting with SQLAlchemy, see the [official SQLAlchemy documentation](https://docs.sqlalchemy.org/en/14/core/engines_connections.html). +For more information about connecting with SQLAlchemy, see the [official SQLAlchemy documentation](https://docs.sqlalchemy.org/core/engines_connections.html). + +{{site.data.alerts.callout_info}} +In order for SQLAlchemy to use the CockroachDB adapter, the connection string must begin with `cockroachdb://`. You can use the following code to modify the general connection string, which begins with `postgresql://`, to the format that works with SQLAlchemy and the CockroachDB adapter: + +{% include_cached copy-clipboard.html %} +~~~ python +engine = create_engine(os.environ['DATABASE_URL'].replace("postgresql://", "cockroachdb://")) +engine.connect() +~~~ + +{{site.data.alerts.end}}
@@ -549,7 +664,7 @@ Django accepts the following format for CockroachDB connection information:
-
+
{% include_cached copy-clipboard.html %} ~~~ @@ -576,7 +691,7 @@ DATABASES = {
-
+
{% include_cached copy-clipboard.html %} ~~~ @@ -631,6 +746,8 @@ DATABASES = { ... ~~~ +{% include {{ page.version.version }}/connect/core-note.md %} +
{{site.data.alerts.callout_info}} @@ -643,11 +760,11 @@ For more information about connecting with Django, see the [official Django docu ## Connection parameters -
+
Parameter | Description ----------|------------ -`{username}` | The [SQL user](security-reference/authorization.html#sql-users) connecting to the cluster. +`{username}` | The [SQL user]({% link {{ page.version.version }}/security-reference/authorization.md %}#sql-users) connecting to the cluster. `{password}` | The password for the SQL user connecting to the cluster. `{host}` | The host on which the CockroachDB node is running. `{port}` | The port at which the CockroachDB node is listening. @@ -655,16 +772,16 @@ Parameter | Description
-
+
Parameter | Description ----------|------------ -`{username}` | The [SQL user](security-reference/authorization.html#sql-users) connecting to the cluster. +`{username}` | The [SQL user]({% link {{ page.version.version }}/security-reference/authorization.md %}#sql-users) connecting to the cluster. `{password}` | The password for the SQL user connecting to the cluster. `{host}` | The host on which the CockroachDB node is running. `{port}` | The port at which the CockroachDB node is listening. `{database}` | The name of the (existing) database. -`{root-cert}` | The path to the root certificate that you [downloaded from the CockroachDB Cloud Console](../cockroachcloud/authentication.html#node-identity-verification). +`{root-cert}` | The path to the root certificate that you [downloaded from the CockroachDB Cloud Console]({% link cockroachcloud/authentication.md %}#node-identity-verification).
@@ -672,13 +789,15 @@ Parameter | Description Parameter | Description ----------|------------ -`{username}` | The [SQL user](security-reference/authorization.html#sql-users) connecting to the cluster. +`{username}` | The [SQL user]({% link {{ page.version.version }}/security-reference/authorization.md %}#sql-users) connecting to the cluster. `{host}` | The host on which the CockroachDB node is running. `{port}` | The port at which the CockroachDB node is listening. `{database}` | The name of the (existing) database. -`{root-cert}` | The path to the root certificate.
You can generate this certificate with [`cockroach cert create-ca`](cockroach-cert.html#subcommands), or you can use a [custom CA cert](create-security-certificates-custom-ca.html). -`{client-cert}` | The path to the [client certificate](cockroach-cert.html#client-key-and-certificates) for the user connecting to the cluster.
You can generate this certificate with [`cockroach cert create-client`](cockroach-cert.html#subcommands). -`{client-key}` | The path to the [client key](cockroach-cert.html#client-key-and-certificates) for the user connecting to the cluster.
You can generate this key with [`cockroach cert create-client`](cockroach-cert.html#subcommands). +`{root-cert}` | The path to the root certificate.
You can generate this certificate with [`cockroach cert create-ca`]({% link {{ page.version.version }}/cockroach-cert.md %}#subcommands), or you can use a [custom CA cert]({% link {{ page.version.version }}/create-security-certificates-custom-ca.md %}). +`{client-cert}` | The path to the [client certificate]({% link {{ page.version.version }}/cockroach-cert.md %}#client-key-and-certificates) for the user connecting to the cluster.
You can generate this certificate with [`cockroach cert create-client`]({% link {{ page.version.version }}/cockroach-cert.md %}#subcommands). +`{client-key}` | The path to the [client key]({% link {{ page.version.version }}/cockroach-cert.md %}#client-key-and-certificates) for the user connecting to the cluster.
You can generate this key with [`cockroach cert create-client`]({% link {{ page.version.version }}/cockroach-cert.md %}#subcommands). + +{% include {{ page.version.version }}/connect/core-note.md %}
@@ -686,12 +805,6 @@ Parameter | Description
-
- - - -
-
To connect to CockroachDB with [pgx](https://github.com/jackc/pgx), use the `pgx.Connect` function. @@ -720,7 +833,7 @@ func main() { pgx accepts the following format for CockroachDB connection strings: -
+
{% include_cached copy-clipboard.html %} ~~~ @@ -729,7 +842,7 @@ postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full
-
+
{% include_cached copy-clipboard.html %} ~~~ @@ -745,6 +858,8 @@ postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full& postgresql://{username}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key} ~~~ +{% include {{ page.version.version }}/connect/core-note.md %} +
For more information about connecting with pgx, see the [official pgx documentation](https://pkg.go.dev/github.com/jackc/pgx). @@ -779,7 +894,7 @@ func main() { pq accepts the following format for CockroachDB connection strings: -
+
{% include_cached copy-clipboard.html %} ~~~ @@ -788,7 +903,7 @@ postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full
-
+
{% include_cached copy-clipboard.html %} ~~~ @@ -804,6 +919,8 @@ postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full& postgresql://{username}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key} ~~~ +{% include {{ page.version.version }}/connect/core-note.md %} +
For more information about connecting with pq, see the [official pq documentation](https://pkg.go.dev/github.com/lib/pq). @@ -838,7 +955,7 @@ func main() { GORM accepts the following format for CockroachDB connection strings: -
+
{% include_cached copy-clipboard.html %} ~~~ @@ -847,7 +964,7 @@ postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full
-
+
{% include_cached copy-clipboard.html %} ~~~ @@ -863,6 +980,8 @@ postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full& postgresql://{username}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key} ~~~ +{% include {{ page.version.version }}/connect/core-note.md %} +
For more information about connecting with GORM, see the [official GORM documentation](https://gorm.io/docs). @@ -871,11 +990,11 @@ For more information about connecting with GORM, see the [official GORM document ## Connection parameters -
+
Parameter | Description ----------|------------ -`{username}` | The [SQL user](security-reference/authorization.html#sql-users) connecting to the cluster. +`{username}` | The [SQL user]({% link {{ page.version.version }}/security-reference/authorization.md %}#sql-users) connecting to the cluster. `{password}` | The password for the SQL user connecting to the cluster. `{host}` | The host on which the CockroachDB node is running. `{port}` | The port at which the CockroachDB node is listening. @@ -883,16 +1002,16 @@ Parameter | Description
-
+
Parameter | Description ----------|------------ -`{username}` | The [SQL user](security-reference/authorization.html#sql-users) connecting to the cluster. +`{username}` | The [SQL user]({% link {{ page.version.version }}/security-reference/authorization.md %}#sql-users) connecting to the cluster. `{password}` | The password for the SQL user connecting to the cluster. `{host}` | The host on which the CockroachDB node is running. `{port}` | The port at which the CockroachDB node is listening. `{database}` | The name of the (existing) database. -`{root-cert}` | The path to the root certificate that you [downloaded from the CockroachDB Cloud Console](../cockroachcloud/authentication.html#node-identity-verification). +`{root-cert}` | The path to the root certificate that you [downloaded from the CockroachDB Cloud Console]({% link cockroachcloud/authentication.md %}#node-identity-verification).
@@ -900,25 +1019,21 @@ Parameter | Description Parameter | Description ----------|------------ -`{username}` | The [SQL user](security-reference/authorization.html#sql-users) connecting to the cluster. +`{username}` | The [SQL user]({% link {{ page.version.version }}/security-reference/authorization.md %}#sql-users) connecting to the cluster. `{host}` | The host on which the CockroachDB node is running. `{port}` | The port at which the CockroachDB node is listening. `{database}` | The name of the (existing) database. -`{root-cert}` | The path to the root certificate.
You can generate this certificate with [`cockroach cert create-ca`](cockroach-cert.html#subcommands), or you can use a [custom CA cert](create-security-certificates-custom-ca.html). -`{client-cert}` | The path to the [client certificate](cockroach-cert.html#client-key-and-certificates) for the user connecting to the cluster.
You can generate this certificate with [`cockroach cert create-client`](cockroach-cert.html#subcommands). -`{client-key}` | The path to the [client key](cockroach-cert.html#client-key-and-certificates) for the user connecting to the cluster.
You can generate this key with [`cockroach cert create-client`](cockroach-cert.html#subcommands). +`{root-cert}` | The path to the root certificate.
You can generate this certificate with [`cockroach cert create-ca`]({% link {{ page.version.version }}/cockroach-cert.md %}#subcommands), or you can use a [custom CA cert]({% link {{ page.version.version }}/create-security-certificates-custom-ca.md %}). +`{client-cert}` | The path to the [client certificate]({% link {{ page.version.version }}/cockroach-cert.md %}#client-key-and-certificates) for the user connecting to the cluster.
You can generate this certificate with [`cockroach cert create-client`]({% link {{ page.version.version }}/cockroach-cert.md %}#subcommands). +`{client-key}` | The path to the [client key]({% link {{ page.version.version }}/cockroach-cert.md %}#client-key-and-certificates) for the user connecting to the cluster.
You can generate this key with [`cockroach cert create-client`]({% link {{ page.version.version }}/cockroach-cert.md %}#subcommands). -
+{% include {{ page.version.version }}/connect/core-note.md %}
-
- -
- -
+
@@ -936,7 +1051,7 @@ Where `JDBC_DATABASE_URL` is an environment variable set to a valid JDBC-compati JDBC accepts the following format for CockroachDB connection strings: -
+
{% include_cached copy-clipboard.html %} ~~~ @@ -945,7 +1060,7 @@ jdbc:postgresql://{host}:{port}/{database}?password={password}&sslmode=verify-fu
-
+
{% include_cached copy-clipboard.html %} ~~~ @@ -961,6 +1076,8 @@ jdbc:postgresql://{host}:{port}/{database}?user={username}&password={password}&s jdbc:postgresql://{host}:{port}/{database}?user={username}&sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key} ~~~ +{% include {{ page.version.version }}/connect/core-note.md %} +
For more information about connecting with JDBC, see the [official JDBC documentation](https://jdbc.postgresql.org/documentation/). @@ -991,7 +1108,7 @@ Where `DATABASE_URL` is an environment variable set to a valid CockroachDB conne Hibernate accepts the following format for CockroachDB connection strings: -
+
{% include_cached copy-clipboard.html %} ~~~ @@ -1000,7 +1117,7 @@ jdbc:postgresql://{host}:{port}/{database}?password={password}&sslmode=verify-fu
-
+
{% include_cached copy-clipboard.html %} ~~~ @@ -1016,10 +1133,12 @@ jdbc:postgresql://{host}:{port}/{database}?user={username}&password={password}&s jdbc:postgresql://{host}:{port}/{database}?user={username}&sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key} ~~~ +{% include {{ page.version.version }}/connect/core-note.md %} +
{{site.data.alerts.callout_info}} -To connect to CockroachDB with Hibernate, you must specify the [CockroachDB Hibernate dialect](install-client-drivers.html?filters=java#hibernate) in your `hibernate.cfg.xml` configuration file. +To connect to CockroachDB with Hibernate, you must specify the [CockroachDB Hibernate dialect]({% link {{ page.version.version }}/install-client-drivers.md %}?filters=java#hibernate) in your `hibernate.cfg.xml` configuration file. {{site.data.alerts.end}} For more information about connecting with Hibernate, see the [official Hibernate documentation](https://hibernate.org/orm/documentation). @@ -1028,11 +1147,11 @@ For more information about connecting with Hibernate, see the [official Hibernat ## Connection parameters -
+
Parameter | Description ----------|------------ -`{username}` | The [SQL user](security-reference/authorization.html#sql-users) connecting to the cluster. +`{username}` | The [SQL user]({% link {{ page.version.version }}/security-reference/authorization.md %}#sql-users) connecting to the cluster. `{password}` | The password for the SQL user connecting to the cluster. `{host}` | The host on which the CockroachDB node is running. `{port}` | The port at which the CockroachDB node is listening. @@ -1040,16 +1159,16 @@ Parameter | Description
-
+
Parameter | Description ----------|------------ -`{username}` | The [SQL user](security-reference/authorization.html#sql-users) connecting to the cluster. +`{username}` | The [SQL user]({% link {{ page.version.version }}/security-reference/authorization.md %}#sql-users) connecting to the cluster. `{password}` | The password for the SQL user connecting to the cluster. `{host}` | The host on which the CockroachDB node is running. `{port}` | The port at which the CockroachDB node is listening. `{database}` | The name of the (existing) database. -`{root-cert}` | The [URL-encoded](https://en.wikipedia.org/wiki/Percent-encoding) path to the root certificate that you [downloaded from the CockroachDB Cloud Console](../cockroachcloud/authentication.html#node-identity-verification). +`{root-cert}` | The [URL-encoded](https://wikipedia.org/wiki/Percent-encoding) path to the root certificate that you [downloaded from the CockroachDB Cloud Console]({% link cockroachcloud/authentication.md %}#node-identity-verification).
@@ -1057,13 +1176,15 @@ Parameter | Description Parameter | Description ----------|------------ -`{username}` | The [SQL user](security-reference/authorization.html#sql-users) connecting to the cluster. +`{username}` | The [SQL user]({% link {{ page.version.version }}/security-reference/authorization.md %}#sql-users) connecting to the cluster. `{host}` | The host on which the CockroachDB node is running. `{port}` | The port at which the CockroachDB node is listening. `{database}` | The name of the (existing) database. -`{root-cert}` | The [URL-encoded](https://en.wikipedia.org/wiki/Percent-encoding) path to the root certificate.
You can generate this certificate with [`cockroach cert create-ca`](cockroach-cert.html#subcommands), or you can use a [custom CA cert](create-security-certificates-custom-ca.html). -`{client-cert}` | The [URL-encoded](https://en.wikipedia.org/wiki/Percent-encoding) path to the [client certificate](cockroach-cert.html#client-key-and-certificates) for the user connecting to the cluster.
You can generate this certificate with [`cockroach cert create-client`](cockroach-cert.html#subcommands). -`{client-key}` | The [URL-encoded](https://en.wikipedia.org/wiki/Percent-encoding) path to the [PKCS#8](https://tools.ietf.org/html/rfc5208)-formatted [client key](cockroach-cert.html#client-key-and-certificates) for the user connecting to the cluster.
You can generate this key with [`cockroach cert create-client --also-generate-pkcs8-key`](cockroach-cert.html#subcommands). +`{root-cert}` | The [URL-encoded](https://wikipedia.org/wiki/Percent-encoding) path to the root certificate.
You can generate this certificate with [`cockroach cert create-ca`]({% link {{ page.version.version }}/cockroach-cert.md %}#subcommands), or you can use a [custom CA cert]({% link {{ page.version.version }}/create-security-certificates-custom-ca.md %}). +`{client-cert}` | The [URL-encoded](https://wikipedia.org/wiki/Percent-encoding) path to the [client certificate]({% link {{ page.version.version }}/cockroach-cert.md %}#client-key-and-certificates) for the user connecting to the cluster.
You can generate this certificate with [`cockroach cert create-client`]({% link {{ page.version.version }}/cockroach-cert.md %}#subcommands). +`{client-key}` | The [URL-encoded](https://wikipedia.org/wiki/Percent-encoding) path to the [PKCS#8](https://tools.ietf.org/html/rfc5208)-formatted [client key]({% link {{ page.version.version }}/cockroach-cert.md %}#client-key-and-certificates) for the user connecting to the cluster.
You can generate this key with [`cockroach cert create-client --also-generate-pkcs8-key`]({% link {{ page.version.version }}/cockroach-cert.md %}#subcommands). + +{% include {{ page.version.version }}/connect/core-note.md %}
@@ -1071,13 +1192,8 @@ Parameter | Description
-
- - -
- {{site.data.alerts.callout_info}} -To connect to a CockroachDB {{ site.data.products.serverless }} cluster from a Ruby application, you must have a valid CA certificate located at ~/.postgresql/root.crt.
For instructions on downloading a CA certificate from the CockroachDB {{ site.data.products.cloud }} Console, see Connect to a CockroachDB {{ site.data.products.serverless }} Cluster. +To connect to a CockroachDB {{ site.data.products.basic }} or {{ site.data.products.standard }} cluster from a Ruby application, you must have a valid CA certificate located at `~/.postgresql/root.crt`.For instructions on downloading a CA certificate from the CockroachDB {{ site.data.products.cloud }} Console, see [Connect to a CockroachDB {{ site.data.products.basic }} Cluster]({% link cockroachcloud/connect-to-a-basic-cluster.md %}) or [Connect to a CockroachDB {{ site.data.products.standard }} Cluster]({% link cockroachcloud/connect-to-your-cluster.md %}). {{site.data.alerts.end}}
@@ -1099,7 +1215,7 @@ Where `DATABASE_URL` is an environment variable set to a valid CockroachDB conne pg accepts the following format for CockroachDB connection strings: -
+
{% include_cached copy-clipboard.html %} ~~~ @@ -1108,7 +1224,7 @@ postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full
-
+
{% include_cached copy-clipboard.html %} ~~~ @@ -1124,6 +1240,8 @@ postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full& postgresql://{username}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key} ~~~ +{% include {{ page.version.version }}/connect/core-note.md %} +
For more information about connecting with pg, see the [official pg documentation](https://www.rubydoc.info/gems/pg). @@ -1150,7 +1268,7 @@ Active Record accepts the following format for CockroachDB connection strings:
-
+
{% include_cached copy-clipboard.html %} ~~~ @@ -1159,7 +1277,7 @@ cockroachdb://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full
-
+
{% include_cached copy-clipboard.html %} ~~~ @@ -1175,6 +1293,8 @@ cockroachdb://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full cockroachdb://{username}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key} ~~~ +{% include {{ page.version.version }}/connect/core-note.md %} +
{{site.data.alerts.callout_info}} @@ -1187,11 +1307,11 @@ For more information about connecting with Active Record, see the [official Acti ## Connection parameters -
+
Parameter | Description ----------|------------ -`{username}` | The [SQL user](security-reference/authorization.html#sql-users) connecting to the cluster. +`{username}` | The [SQL user]({% link {{ page.version.version }}/security-reference/authorization.md %}#sql-users) connecting to the cluster. `{password}` | The password for the SQL user connecting to the cluster. `{host}` | The host on which the CockroachDB node is running. `{port}` | The port at which the CockroachDB node is listening. @@ -1199,16 +1319,16 @@ Parameter | Description
-
+
Parameter | Description ----------|------------ -`{username}` | The [SQL user](security-reference/authorization.html#sql-users) connecting to the cluster. +`{username}` | The [SQL user]({% link {{ page.version.version }}/security-reference/authorization.md %}#sql-users) connecting to the cluster. `{password}` | The password for the SQL user connecting to the cluster. `{host}` | The host on which the CockroachDB node is running. `{port}` | The port at which the CockroachDB node is listening. `{database}` | The name of the (existing) database. -`{root-cert}` | The path to the root certificate that you [downloaded from the CockroachDB Cloud Console](../cockroachcloud/authentication.html#node-identity-verification). +`{root-cert}` | The path to the root certificate that you [downloaded from the CockroachDB Cloud Console]({% link cockroachcloud/authentication.md %}#node-identity-verification).
@@ -1216,13 +1336,15 @@ Parameter | Description Parameter | Description ----------|------------ -`{username}` | The [SQL user](security-reference/authorization.html#sql-users) connecting to the cluster. +`{username}` | The [SQL user]({% link {{ page.version.version }}/security-reference/authorization.md %}#sql-users) connecting to the cluster. `{host}` | The host on which the CockroachDB node is running. `{port}` | The port at which the CockroachDB node is listening. `{database}` | The name of the (existing) database. -`{root-cert}` | The path to the root certificate.
You can generate this certificate with [`cockroach cert create-ca`](cockroach-cert.html#subcommands), or you can use a [custom CA cert](create-security-certificates-custom-ca.html). -`{client-cert}` | The path to the [client certificate](cockroach-cert.html#client-key-and-certificates) for the user connecting to the cluster.
You can generate this certificate with [`cockroach cert create-client`](cockroach-cert.html#subcommands). -`{client-key}` | The path to the [client key](cockroach-cert.html#client-key-and-certificates) for the user connecting to the cluster.
You can generate this key with [`cockroach cert create-client`](cockroach-cert.html#subcommands). +`{root-cert}` | The path to the root certificate.
You can generate this certificate with [`cockroach cert create-ca`]({% link {{ page.version.version }}/cockroach-cert.md %}#subcommands), or you can use a [custom CA cert]({% link {{ page.version.version }}/create-security-certificates-custom-ca.md %}). +`{client-cert}` | The path to the [client certificate]({% link {{ page.version.version }}/cockroach-cert.md %}#client-key-and-certificates) for the user connecting to the cluster.
You can generate this certificate with [`cockroach cert create-client`]({% link {{ page.version.version }}/cockroach-cert.md %}#subcommands). +`{client-key}` | The path to the [client key]({% link {{ page.version.version }}/cockroach-cert.md %}#client-key-and-certificates) for the user connecting to the cluster.
You can generate this key with [`cockroach cert create-client`]({% link {{ page.version.version }}/cockroach-cert.md %}#subcommands). + +{% include {{ page.version.version }}/connect/core-note.md %}
@@ -1230,7 +1352,7 @@ Parameter | Description ## See also -- [Install a Driver or ORM Framework](install-client-drivers.html) -- [Connection Pooling](connection-pooling.html) -- [`cockroach` Connection Parameters](connection-parameters.html) -- [Example Apps](example-apps.html) +- [Install a Driver or ORM Framework]({% link {{ page.version.version }}/install-client-drivers.md %}) +- [Connection Pooling]({% link {{ page.version.version }}/connection-pooling.md %}) +- [`cockroach` Connection Parameters]({% link {{ page.version.version }}/connection-parameters.md %}) +- [Example Apps]({% link {{ page.version.version }}/example-apps.md %}) diff --git a/src/current/v22.1/frequently-asked-questions.md b/src/current/v22.1/frequently-asked-questions.md index 0267503e50f..fe8a055f3b4 100644 --- a/src/current/v22.1/frequently-asked-questions.md +++ b/src/current/v22.1/frequently-asked-questions.md @@ -10,13 +10,7 @@ docs_area: get_started ### What is CockroachDB? -CockroachDB is a [distributed SQL](https://www.cockroachlabs.com/blog/what-is-distributed-sql/) database built on a transactional and strongly-consistent key-value store. It **scales** horizontally; **survives** disk, machine, rack, and even datacenter failures with minimal latency disruption and no manual intervention; supports **strongly-consistent** ACID transactions; and provides a familiar **SQL** API for structuring, manipulating, and querying data. - -CockroachDB is inspired by Google's [Spanner](http://research.google.com/archive/spanner.html) and [F1](http://research.google.com/pubs/pub38125.html) technologies, and the [source code](https://github.com/cockroachdb/cockroach) is freely available. - -{{site.data.alerts.callout_success}} -For a deeper dive into CockroachDB's capabilities and how it fits into the database landscape, take the free [**Intro to Distributed SQL and CockroachDB**](https://university.cockroachlabs.com/courses/course-v1:crl+intro-to-distributed-sql-and-cockroachdb+self-paced/about) course on Cockroach University. -{{site.data.alerts.end}} +{% include {{ page.version.version }}/faq/what-is-crdb.md %} ### When is CockroachDB a good choice? @@ -30,23 +24,22 @@ CockroachDB is well suited for applications that require reliable, available, an -CockroachDB returns single-row reads in 2ms or less and single-row writes in 4ms or less, and supports a variety of [SQL and operational tuning practices](performance-best-practices-overview.html) for optimizing query performance. However, CockroachDB is not yet suitable for heavy analytics / OLAP. +CockroachDB returns single-row reads in 2ms or less and single-row writes in 4ms or less, and supports a variety of [SQL and operational tuning practices]({% link {{ page.version.version }}/performance-best-practices-overview.md %}) for optimizing query performance. However, CockroachDB is not yet suitable for heavy analytics / OLAP. ### How easy is it to get started with CockroachDB? -You can get started with CockroachDB with just a few clicks. Sign up for a CockroachDB {{ site.data.products.cloud }} account to create a free CockroachDB {{ site.data.products.serverless }} cluster. For more details, see [Quickstart](../cockroachcloud/quickstart.html). +You can get started with CockroachDB with just a few clicks. Sign up for a CockroachDB {{ site.data.products.cloud }} account to create a CockroachDB {{ site.data.products.standard }} cluster. For more details, see [Quickstart]({% link cockroachcloud/quickstart.md %}). -Alternatively, you can download a binary or run our official Kubernetes configurations or Docker image. For more details, see [Install CockroachDB](install-cockroachdb.html). +Alternatively, you can download a binary or run our official Kubernetes configurations or Docker image. For more details, see [Install CockroachDB]({% link {{ page.version.version }}/install-cockroachdb.md %}). ### How do I know which CockroachDB deployment option is right for my project? -There are three way to use and deploy CockroachDB: +There are four ways to use and deploy CockroachDB: -- **CockroachDB {{ site.data.products.serverless }}**: A multi-tenant CockroachDB deployment, managed by Cockroach Labs, in a single region and cloud (AWS or GCP). CockroachDB {{ site.data.products.serverless }} lets you create and start clusters instantly. This deployment option is good for starter projects and evaluations. -- **CockroachDB {{ site.data.products.dedicated }}**: A single tenant CockroachDB deployment, managed by Cockroach Labs, in a single, multi-region cloud (AWS or GCP). This deployment option is good for mission-critical databases and projects that require [Enterprise features](enterprise-licensing.html). -- **CockroachDB {{ site.data.products.core }}**: A self-managed CockroachDB deployment, backed by Cockroach Labs Support, for multiple clouds and regions. This deployment option is good if you require complete control over the database environment and require [Enterprise features](enterprise-licensing.html). - -For more details, see [Choose a Deployment Option](choose-a-deployment-option.html). +- **CockroachDB {{ site.data.products.basic }}**: A multi-tenant CockroachDB deployment, managed by Cockroach Labs. CockroachDB {{ site.data.products.basic }} provides highly available database clusters that scale instantly and automatically for small production and dev/test workloads. +- **CockroachDB {{ site.data.products.standard }}**: A multi-tenant CockroachDB deployment, managed by Cockroach Labs. CockroachDB {{ site.data.products.standard }} allows you to consolidate a variety of production workloads while optimizing cost. +- **CockroachDB {{ site.data.products.advanced }}**: A single tenant CockroachDB deployment, managed by Cockroach Labs. CockroachDB {{ site.data.products.advanced }} provides dedicated hardware to support stringent regulatory requirements and enhanced compliance, targeting production workloads with advanced Enterprise requirements. +- **CockroachDB {{ site.data.products.core }}**: A self-managed CockroachDB deployment, backed by Cockroach Labs Support, for multiple clouds and regions. This deployment option is good if you require complete control over the database environment and require [Enterprise features]({% link {{ page.version.version }}/enterprise-licensing.md %}). ## About the database @@ -54,11 +47,14 @@ For more details, see [Choose a Deployment Option](choose-a-deployment-option.ht CockroachDB scales horizontally with minimal operator overhead. -At the key-value level, CockroachDB starts off with a single, empty range. As you put data in, this single range eventually reaches a threshold size (512 MiB by default). When that happens, the data splits into two ranges, each covering a contiguous segment of the entire key-value space. This process continues indefinitely; as new data flows in, existing ranges continue to split into new ranges, aiming to keep a relatively small and consistent range size. +At the key-value level, CockroachDB starts off with a single, empty range. As you put data in, this single range eventually reaches [a threshold size]({% link {{ page.version.version }}/configure-replication-zones.md %}#range-max-bytes). When that happens, the data [splits into two ranges]({% link {{ page.version.version }}/architecture/distribution-layer.md %}#range-splits), each covering a contiguous segment of the entire key-value space. This process continues indefinitely; as new data flows in, existing ranges continue to split into new ranges, aiming to keep a relatively small and consistent range size. + +When your cluster spans multiple nodes (physical machines, virtual machines, or containers), newly split ranges are automatically rebalanced to nodes with more capacity. CockroachDB communicates opportunities for rebalancing using a peer-to-peer [gossip protocol](https://wikipedia.org/wiki/Gossip_protocol) by which nodes exchange network addresses, store capacity, and other information. -When your cluster spans multiple nodes (physical machines, virtual machines, or containers), newly split ranges are automatically rebalanced to nodes with more capacity. CockroachDB communicates opportunities for rebalancing using a peer-to-peer [gossip protocol](https://en.wikipedia.org/wiki/Gossip_protocol) by which nodes exchange network addresses, store capacity, and other information. +For more information about scaling a CockroachDB cluster, see the following docs: -For more information about scaling a CockroachDB cluster, refer to [`cockroach start` - Add a node to a cluster](cockroach-start.html#add-a-node-to-a-cluster) +- [Manage Your Advanced Cluster - Scale your cluster]({% link cockroachcloud/advanced-cluster-management.md %}#scale-your-cluster) +- [`cockroach start` - Add a node to a cluster]({% link {{ page.version.version }}/cockroach-start.md %}#add-a-node-to-a-cluster) ### How does CockroachDB survive failures? @@ -66,13 +62,13 @@ CockroachDB is designed to survive software and hardware failures, from server r **Replication** -CockroachDB replicates your data for availability and guarantees consistency between replicas using the [Raft consensus algorithm](https://raft.github.io/), a popular alternative to Paxos. You can [define the location of replicas](configure-replication-zones.html) in various ways, depending on the types of failures you want to secure against and your network topology. You can locate replicas on: +CockroachDB replicates your data for availability and guarantees consistency between replicas using the [Raft consensus algorithm](https://raft.github.io/), a popular alternative to Paxos. You can [define the location of replicas]({% link {{ page.version.version }}/configure-replication-zones.md %}) in various ways, depending on the types of failures you want to secure against and your network topology. You can locate replicas on: - Different servers within a rack to tolerate server failures - Different servers on different racks within a datacenter to tolerate rack power/network failures - Different servers in different datacenters to tolerate large scale network or power outages -In a CockroachDB cluster spread across multiple geographic regions, the round-trip latency between regions will have a direct effect on your database's performance. In such cases, it is important to think about the latency requirements of each table and then use the appropriate [data topologies](topology-patterns.html) to locate data for optimal performance and resiliency. For a step-by-step demonstration, see [Low Latency Multi-Region Deployment](demo-low-latency-multi-region-deployment.html). +In a CockroachDB cluster spread across multiple geographic regions, the round-trip latency between regions will have a direct effect on your database's performance. In such cases, it is important to think about the latency requirements of each table and then use the appropriate [data topologies]({% link {{ page.version.version }}/topology-patterns.md %}) to locate data for optimal performance and resiliency. For a step-by-step demonstration, see [Low Latency Multi-Region Deployment]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). **Automated Repair** @@ -80,36 +76,36 @@ For short-term failures, such as a server restart, CockroachDB uses Raft to cont ### How is CockroachDB strongly-consistent? -CockroachDB guarantees [serializable SQL transactions](demo-serializable.html), the highest isolation level defined by the SQL standard. It does so by combining the Raft consensus algorithm for writes and a custom time-based synchronization algorithms for reads. +CockroachDB guarantees [serializable SQL transactions]({% link {{ page.version.version }}/demo-serializable.md %}), the highest isolation level defined by the SQL standard. It does so by combining the Raft consensus algorithm for writes and a custom time-based synchronization algorithms for reads. -- Stored data is versioned with MVCC, so [reads simply limit their scope to the data visible at the time the read transaction started](architecture/transaction-layer.html#time-and-hybrid-logical-clocks). +- Stored data is versioned with MVCC, so [reads simply limit their scope to the data visible at the time the read transaction started]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#time-and-hybrid-logical-clocks). -- Writes are serviced using the [Raft consensus algorithm](https://raft.github.io/), a popular alternative to Paxos. A consensus algorithm guarantees that any majority of replicas together always agree on whether an update was committed successfully. Updates (writes) must reach a majority of replicas (2 out of 3 by default) before they are considered committed. +- Writes are serviced using the [Raft consensus algorithm](https://raft.github.io/), a popular alternative to Paxos. A consensus algorithm guarantees that any majority of replicas together always agree on whether an update was committed successfully. Updates (writes) must reach a majority of replicas (2 out of 3 by default) before they are considered committed. - To ensure that a write transaction does not interfere with read transactions that start after it, CockroachDB also uses a [timestamp cache](architecture/transaction-layer.html#timestamp-cache) which remembers when data was last read by ongoing transactions. + To ensure that a write transaction does not interfere with read transactions that start after it, CockroachDB also uses a [timestamp cache]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#timestamp-cache) which remembers when data was last read by ongoing transactions. This ensures that clients always observe serializable consistency with regards to other concurrent transactions. ### How is CockroachDB both highly available and strongly consistent? -The [CAP theorem](https://en.wikipedia.org/wiki/CAP_theorem) states that it is impossible for a distributed system to simultaneously provide more than two out of the following three guarantees: +The [CAP theorem](https://wikipedia.org/wiki/CAP_theorem) states that it is impossible for a distributed system to simultaneously provide more than two out of the following three guarantees: - Consistency - Availability - Partition Tolerance CockroachDB is a CP (consistent and partition tolerant) system. This means -that, in the presence of partitions, the system will become unavailable rather than do anything which might cause inconsistent results. For example, writes require acknowledgements from a majority of replicas, and reads require a lease, which can only be transferred to a different node when writes are possible. +that, in the presence of partitions, the system will become unavailable rather than do anything which might cause inconsistent results. For example, writes require acknowledgments from a majority of replicas, and reads require a lease, which can only be transferred to a different node when writes are possible. Separately, CockroachDB is also Highly Available, although "available" here means something different than the way it is used in the CAP theorem. In the CAP theorem, availability is a binary property, but for High Availability, we talk about availability as a spectrum (using terms like "five nines" for a system that is available 99.999% of the time). -Being both CP and HA means that whenever a majority of replicas can talk to each other, they should be able to make progress. For example, if you deploy CockroachDB to three datacenters and the network link to one of them fails, the other two datacenters should be able to operate normally with only a few seconds' disruption. We do this by attempting to detect partitions and failures quickly and efficiently, transferring leadership to nodes that are able to communicate with the majority, and routing internal traffic away from nodes that are partitioned away. +Being both CP and HA means that whenever a majority of replicas can talk to each other, they should be able to make progress. For example, if you deploy CockroachDB to three datacenters and the network link to one of them fails, the other two datacenters should be able to operate normally with only a few seconds' disruption. We do this by attempting to detect partitions and failures quickly and efficiently, [transferring leadership to nodes that are able to communicate with the majority]({% link {{ page.version.version }}/architecture/replication-layer.md %}#how-leases-are-transferred-from-a-dead-node), and routing internal traffic away from nodes that are partitioned away. ### Why is CockroachDB SQL? -At the lowest level, CockroachDB is a distributed, strongly-consistent, transactional key-value store, but the external API is Standard SQL with extensions. This provides developers familiar relational concepts such as schemas, tables, columns, and indexes and the ability to structure, manipulate, and query data using well-established and time-proven tools and processes. Also, since CockroachDB supports the PostgreSQL wire protocol, it’s simple to get your application talking to Cockroach; just find your [PostgreSQL language-specific driver](install-client-drivers.html) and start building. +At the lowest level, CockroachDB is a distributed, strongly-consistent, transactional key-value store, but the external API is Standard SQL with extensions. This provides developers familiar relational concepts such as schemas, tables, columns, and indexes and the ability to structure, manipulate, and query data using well-established and time-proven tools and processes. Also, since CockroachDB supports the PostgreSQL wire protocol, it’s simple to get your application talking to Cockroach; just find your [PostgreSQL language-specific driver]({% link {{ page.version.version }}/install-client-drivers.md %}) and start building. -For more details, learn our [basic CockroachDB SQL statements](learn-cockroachdb-sql.html), explore the [full SQL grammar](sql-grammar.html), and try it out via our [built-in SQL client](cockroach-sql.html). Also, to understand how CockroachDB maps SQL table data to key-value storage and how CockroachDB chooses the best index for running a query, see [SQL in CockroachDB](https://www.cockroachlabs.com/blog/sql-in-cockroachdb-mapping-table-data-to-key-value-storage/) and [Index Selection in CockroachDB](https://www.cockroachlabs.com/blog/index-selection-cockroachdb-2/). +For more details, learn our [basic CockroachDB SQL statements]({% link {{ page.version.version }}/learn-cockroachdb-sql.md %}), explore the [full SQL grammar]({% link {{ page.version.version }}/sql-grammar.md %}), and try it out via our [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}). Also, to understand how CockroachDB maps SQL table data to key-value storage and how CockroachDB chooses the best index for running a query, see [SQL in CockroachDB](https://www.cockroachlabs.com/blog/sql-in-cockroachdb-mapping-table-data-to-key-value-storage/) and [Index Selection in CockroachDB](https://www.cockroachlabs.com/blog/index-selection-cockroachdb-2/). ### Does CockroachDB support distributed transactions? @@ -117,18 +113,18 @@ Yes. CockroachDB distributes transactions across your cluster, whether it’s a ### Do transactions in CockroachDB guarantee ACID semantics? -Yes. Every [transaction](transactions.html) in CockroachDB guarantees [ACID semantics](https://en.wikipedia.org/wiki/ACID) spanning arbitrary tables and rows, even when data is distributed. +Yes. Every [transaction]({% link {{ page.version.version }}/transactions.md %}) in CockroachDB guarantees [ACID semantics](https://en.wikipedia.org/wiki/ACID) spanning arbitrary tables and rows, even when data is distributed. - **Atomicity:** Transactions in CockroachDB are “all or nothing.” If any part of a transaction fails, the entire transaction is aborted, and the database is left unchanged. If a transaction succeeds, all mutations are applied together with virtual simultaneity. For a detailed discussion of atomicity in CockroachDB transactions, see [How CockroachDB Distributes Atomic Transactions](https://www.cockroachlabs.com/blog/how-cockroachdb-distributes-atomic-transactions/). - **Consistency:** SQL operations never see any intermediate states and move the database from one valid state to another, keeping indexes up to date. Operations always see the results of previously completed statements on overlapping data and maintain specified constraints such as unique columns. For a detailed look at how we've tested CockroachDB for correctness and consistency, see [CockroachDB Beta Passes Jepsen Testing](https://www.cockroachlabs.com/blog/cockroachdb-beta-passes-jepsen-testing/). -- **Isolation:** Transactions in CockroachDB implement the strongest ANSI isolation level: serializable (`SERIALIZABLE`). This means that transactions will never result in anomalies. For more information about transaction isolation in CockroachDB, see [Transactions: Isolation Levels](transactions.html#isolation-levels). +- **Isolation:** Transactions in CockroachDB implement the strongest ANSI isolation level: serializable (`SERIALIZABLE`). This means that transactions will never result in anomalies. For more information about transaction isolation in CockroachDB, see [Transactions: Isolation Levels]({% link {{ page.version.version }}/transactions.md %}#isolation-levels). - **Durability:** In CockroachDB, every acknowledged write has been persisted consistently on a majority of replicas (by default, at least 2) via the [Raft consensus algorithm](https://raft.github.io/). Power or disk failures that affect only a minority of replicas (typically 1) do not prevent the cluster from operating and do not lose any data. ### Since CockroachDB is inspired by Spanner, does it require atomic clocks to synchronize time? No. CockroachDB was designed to work without atomic clocks or GPS clocks. It’s a database intended to be run on arbitrary collections of nodes, from physical servers in a corp development cluster to public cloud infrastructure using the flavor-of-the-month virtualization layer. It’d be a showstopper to require an external dependency on specialized hardware for clock synchronization. However, CockroachDB does require moderate levels of clock synchronization for correctness. If clocks drift past a maximum threshold, nodes will be taken offline. It's therefore highly recommended to run [NTP](http://www.ntp.org/) or other clock synchronization software on each node. -For more details on how CockroachDB handles unsynchronized clocks, see [Clock Synchronization](recommended-production-settings.html#clock-synchronization). And for a broader discussion of clocks, and the differences between clocks in Spanner and CockroachDB, see [Living Without Atomic Clocks](https://www.cockroachlabs.com/blog/living-without-atomic-clocks/). +For more details on how CockroachDB handles unsynchronized clocks, see [Clock Synchronization]({% link {{ page.version.version }}/recommended-production-settings.md %}#clock-synchronization). And for a broader discussion of clocks, and the differences between clocks in Spanner and CockroachDB, see [Living Without Atomic Clocks](https://www.cockroachlabs.com/blog/living-without-atomic-clocks/). ### What languages can I use to work with CockroachDB? @@ -143,7 +139,7 @@ CockroachDB supports the PostgreSQL wire protocol, so you can use any available - C#(.NET) - Rust -See [Install Client Drivers](install-client-drivers.html) for more details. +See [Install Client Drivers]({% link {{ page.version.version }}/install-client-drivers.md %}) for more details. ### Why does CockroachDB use the PostgreSQL wire protocol instead of the MySQL protocol? @@ -153,9 +149,9 @@ Note, however, that the protocol used doesn't significantly impact how easy it i ### Can a PostgreSQL or MySQL application be migrated to CockroachDB? -Yes. Most users should be able to follow the instructions in [Migrate from PostgreSQL](migrate-from-postgres.html) or [Migrate from MySQL](migrate-from-mysql.html). Due to differences in available features and syntax, some features supported by these databases may require manual effort to port to CockroachDB. Check those pages for details. +Yes. Most users should be able to follow the instructions in [Migrate from PostgreSQL]({% link {{ page.version.version }}/migrate-from-postgres.md %}) or [Migrate from MySQL]({% link {{ page.version.version }}/migrate-from-mysql.md %}). Due to differences in available features and syntax, some features supported by these databases may require manual effort to port to CockroachDB. Check those pages for details. -We also fully support [importing your data via CSV](migrate-from-csv.html). +We also fully support [importing your data via CSV]({% link {{ page.version.version }}/migrate-from-csv.md %}). ### What is CockroachDB’s security model? @@ -163,7 +159,7 @@ You can run a secure or insecure CockroachDB cluster. When secure, client/node a Also, CockroachDB supports common SQL privileges on databases and tables. The `root` user has privileges for all databases, while unique users can be granted privileges for specific statements at the database and table-levels. -For more details, see our [Security Overview](security-reference/security-overview.html). +For more details, see our [Security Overview]({% link {{ page.version.version }}/security-reference/security-overview.md %}). ## How CockroachDB compares @@ -171,17 +167,17 @@ For more details, see our [Security Overview](security-reference/security-overvi While all of these databases support SQL syntax, CockroachDB is the only one that scales easily (without the manual complexity of sharding), rebalances and repairs itself automatically, and distributes transactions seamlessly across your cluster. -For more insight, see [CockroachDB in Comparison](cockroachdb-in-comparison.html). +For more insight, see [CockroachDB in Comparison]({% link {{ page.version.version }}/cockroachdb-in-comparison.md %}). ### How does CockroachDB compare to Cassandra, HBase, MongoDB, or Riak? While all of these are distributed databases, only CockroachDB supports distributed transactions and provides strong consistency. Also, these other databases provide custom APIs, whereas CockroachDB offers standard SQL with extensions. -For more insight, see [CockroachDB in Comparison](cockroachdb-in-comparison.html). +For more insight, see [CockroachDB in Comparison]({% link {{ page.version.version }}/cockroachdb-in-comparison.md %}). ## Have questions that weren’t answered? -Try searching the rest of our docs for answers or using our other [support resources](support-resources.html), including: +Try searching the rest of our docs for answers or using our other [support resources]({% link {{ page.version.version }}/support-resources.md %}), including: - [CockroachDB Community Forum](https://forum.cockroachlabs.com) - [CockroachDB Community Slack](https://cockroachdb.slack.com)