From 8b8fe6ae968bdf19528516cb292f90fc3080ebbf Mon Sep 17 00:00:00 2001 From: Kyle Conroy Date: Fri, 5 Jan 2024 09:41:21 -0800 Subject: [PATCH] docs: Move the sqlc Dashboard section lower in getting started --- docs/tutorials/getting-started-mysql.md | 42 +++++++++++++ docs/tutorials/getting-started-postgresql.md | 63 +++++++++++++------- 2 files changed, 85 insertions(+), 20 deletions(-) diff --git a/docs/tutorials/getting-started-mysql.md b/docs/tutorials/getting-started-mysql.md index 7cf52972fc..882cd75fa7 100644 --- a/docs/tutorials/getting-started-mysql.md +++ b/docs/tutorials/getting-started-mysql.md @@ -8,6 +8,8 @@ We'll generate Go code here, but other naturally need the Go toolchain if you want to build and run a program with the code sqlc generates, but sqlc itself has no dependencies. +At the end, you'll push your SQL queries to [sqlc Cloud](https://dashboard.sqlc.dev/) for further insights and analysis. + ## Setting up Create a new directory called `sqlc-tutorial` and open it up. @@ -181,3 +183,43 @@ database must have the `authors` table as defined in `schema.sql`. You should now have a working program using sqlc's generated Go source code, and hopefully can see how you'd use sqlc in your own real-world applications. + +## Query analysis and managed databases + +[sqlc Cloud](https://dashboard.sqlc.dev) provides additional insights into your +queries, catching subtle bugs and performance issues. To get started, create a +[dashboard account](https://dashboard.sqlc.dev). Once you've signed in, create a +project and generate an auth token. Add your project's ID to the `cloud` block +to your sqlc.yaml. + +```yaml +version: "2" +cloud: + # Replace with your project ID from the sqlc Cloud dashboard + project: "" +sql: + - engine: "mysql" + queries: "query.sql" + schema: "schema.sql" + gen: + go: + package: "tutorial" + out: "tutorial" +``` + +Replace `` with your project ID from the sqlc Cloud dashboard. It +will look something like `01HA8SZH31HKYE9RR3N3N3TSJM`. + +And finally, set the `SQLC_AUTH_TOKEN` environment variable: + +```shell +export SQLC_AUTH_TOKEN="" +``` + +```shell +$ sqlc push --tag tutorial +``` + +In the sidebar, go to the "Insights" section to run checks against your queries. +If you need access to a pre-configured MySQL database, check out [managed +databases](../howtwo/managed-databases.md). diff --git a/docs/tutorials/getting-started-postgresql.md b/docs/tutorials/getting-started-postgresql.md index 2f67298969..db2a46d472 100644 --- a/docs/tutorials/getting-started-postgresql.md +++ b/docs/tutorials/getting-started-postgresql.md @@ -8,12 +8,8 @@ We'll generate Go code here, but other naturally need the Go toolchain if you want to build and run a program with the code sqlc generates, but sqlc itself has no dependencies. -We'll also rely on sqlc's [managed databases](../howto/managed-databases.md), -which require a sqlc Cloud project and auth token. You can get those from -the [sqlc Cloud dashboard](https://dashboard.sqlc.dev/). Managed databases are -an optional feature that improves sqlc's query analysis in many cases, but you -can turn it off simply by removing the `cloud` and `database` sections of your -configuration. +At the end, you'll push your SQL queries to [sqlc +Cloud](https://dashboard.sqlc.dev/) for further insights and analysis. ## Setting up @@ -31,15 +27,10 @@ following contents: ```yaml version: "2" -cloud: - # Replace with your project ID from the sqlc Cloud dashboard - project: "" sql: - engine: "postgresql" queries: "query.sql" schema: "schema.sql" - database: - managed: true gen: go: package: "tutorial" @@ -47,15 +38,6 @@ sql: sql_package: "pgx/v5" ``` -Replace `` with your project ID from the sqlc Cloud dashboard. It -will look something like `01HA8SZH31HKYE9RR3N3N3TSJM`. - -And finally, set the `SQLC_AUTH_TOKEN` environment variable: - -```shell -export SQLC_AUTH_TOKEN="" -``` - ## Schema and queries sqlc needs to know your database schema and queries in order to generate code. @@ -220,3 +202,44 @@ database must have the `authors` table as defined in `schema.sql`. You should now have a working program using sqlc's generated Go source code, and hopefully can see how you'd use sqlc in your own real-world applications. + +## Query analysis and managed databases + +[sqlc Cloud](https://dashboard.sqlc.dev) provides additional insights into your +queries, catching subtle bugs and performance issues. To get started, create a +[dashboard account](https://dashboard.sqlc.dev). Once you've signed in, create a +project and generate an auth token. Add your project's ID to the `cloud` block +to your sqlc.yaml. + +```yaml +version: "2" +cloud: + # Replace with your project ID from the sqlc Cloud dashboard + project: "" +sql: + - engine: "postgresql" + queries: "query.sql" + schema: "schema.sql" + gen: + go: + package: "tutorial" + out: "tutorial" + sql_package: "pgx/v5" +``` + +Replace `` with your project ID from the sqlc Cloud dashboard. It +will look something like `01HA8SZH31HKYE9RR3N3N3TSJM`. + +And finally, set the `SQLC_AUTH_TOKEN` environment variable: + +```shell +export SQLC_AUTH_TOKEN="" +``` + +```shell +$ sqlc push --tag tutorial +``` + +In the sidebar, go to the "Insights" section to run checks against your queries. +If you need access to a pre-configured PostgreSQL database, check out [managed +databases](../howtwo/managed-databases.md).