docs: Update the managed db and verify documentation (sqlc-dev#3426)

Author: kyleconroy

docs/howto/ci-cd.md

@@ -80,54 +80,20 @@ on: [push]
 jobs:
   vet:
     runs-on: ubuntu-latest
-    services:
-      postgres:
-        image: "postgres:15"
-        env:
-          POSTGRES_DB: postgres
-          POSTGRES_PASSWORD: postgres
-          POSTGRES_USER: postgres
-        ports:
-        - 5432:5432
-        # needed because the postgres container does not provide a healthcheck
-        options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
-    env:
-      PG_PORT: ${{ job.services.postgres.ports['5432'] }}
-
     steps:
     - uses: actions/checkout@v3
     - uses: sqlc-dev/setup-sqlc@v3
       with:
         sqlc-version: '1.26.0'
-      # Connect and migrate your database here. This is an example which runs
-      # commands from a `schema.sql` file.
-    - run: psql -h localhost -U postgres -p $PG_PORT -d postgres -f schema.sql
-      env:
-        PGPASSWORD: postgres
-    - run: sqlc vet
-```
-
-#### Managed databases
-
-```{note}
-Managed databases are powered by [sqlc Cloud](https://dashboard.sqlc.dev). Sign up for [free](https://dashboard.sqlc.dev) today.
-```
-
-If you're using [managed databases](managed-databases.md), the `services` block
-in the previous workflow isn't required.
-
-```yaml
-name: sqlc
-on: [push]
-jobs:
-  vet:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v3
-    - uses: sqlc-dev/setup-sqlc@v3
+    # Start a PostgreSQL server
+    - uses: sqlc-dev/action-setup-postgres@master
       with:
-        sqlc-version: '1.26.0'
+        postgres-version: "16"
+      id: postgres
     - run: sqlc vet
+      env:
+        POSTGRESQL_SERVER_URI: ${{ steps.postgres.outputs.connection-uri }}?sslmode=disable
+
 ```
 
 ### push
@@ -174,8 +140,13 @@ jobs:
     - uses: sqlc-dev/setup-sqlc@v3
       with:
         sqlc-version: '1.26.0'
+    - uses: sqlc-dev/action-setup-postgres@master
+      with:
+        postgres-version: "16"
+      id: postgres
     - run: sqlc verify
       env:
+        POSTGRESQL_SERVER_URI: ${{ steps.postgres.outputs.connection-uri }}?sslmode=disable
         SQLC_AUTH_TOKEN: ${{ secrets.SQLC_AUTH_TOKEN }}
   push:
     runs-on: ubuntu-latest

docs/howto/generate.md

@@ -27,19 +27,16 @@ support planned in the future.
 
 ## Enhanced analysis with managed databases
 
-```{note}
-Managed databases are powered by [sqlc Cloud](https://dashboard.sqlc.dev). Sign up for [free](https://dashboard.sqlc.dev) today.
-```
-
 With [managed databases](managed-databases.md) configured, `generate` will automatically create a hosted ephemeral database with your
 schema and use that database to improve its query analysis. And sqlc will cache its analysis locally
 on a per-query basis to speed up future `generate` runs. This saves you the trouble of running and maintaining a database with
 an up-to-date schema. Here's a minimal working configuration:
 
 ```yaml
 version: "2"
-cloud:
-  project: "<PROJECT_ID>"
+servers:
+- engine: postgresql
+  uri: "postgres://locahost:5432/postgres?sslmode=disable"
 sql:
   - engine: "postgresql"
     queries: "query.sql"

docs/howto/managed-databases.md

@@ -1,37 +1,31 @@
 # Managed databases
 
-```{note}
-Managed databases are powered by [sqlc Cloud](https://dashboard.sqlc.dev). Sign up for [free](https://dashboard.sqlc.dev) today.
-```
-
 *Added in v1.22.0*
 
-`sqlc` can create and maintain short-lived hosted databases for your project.
-These ephemeral databases are immediately useful for powering sqlc's
-database-connected query analyzer, an opt-in feature that improves upon sqlc's
-built-in query analysis engine. PostgreSQL support is available today, with
-MySQL on the way.
+`sqlc` can automatically create read-only databases to power query analysis,
+linting and verification. These databases are immediately useful for powering
+sqlc's database-connected query analyzer, an opt-in feature that improves upon
+sqlc's built-in query analysis engine. PostgreSQL support is available today,
+with MySQL on the way.
 
 Once configured, `sqlc` will also use managed databases when linting queries
 with [`sqlc vet`](vet.md) in cases where your lint rules require a connection
 to a running database.
 
 Managed databases are under active development, and we're interested in
-supporting other use-cases. Outside of sqlc itself, you can use our managed
-databases in your tests to quickly stand up a database per test suite or even per test,
-providing a real, isolated database for a test run. No cleanup required.
+supporting other use-cases.
 
 ## Configuring managed databases
 
 To configure `sqlc` to use managed databases, remove the `uri` key from your
 `database` configuration and replace it with the `managed` key set to `true`.
-Set the `project` key in your `cloud` configuration to the value of your
-project ID, obtained via the [dashboard](https://dashboard.sqlc.dev).
+Access to a running database server is required. Add a connection string to the `servers` mapping.
 
 ```yaml
 version: '2'
-cloud:
-  project: '<PROJECT_ID>'
+servers:
+- engine: postgresql
+  uri: "postgres://locahost:5432/postgres?sslmode=disable"
 sql:
 - schema: schema.sql
   queries: query.sql
@@ -40,13 +34,19 @@ sql:
     managed: true
 ```
 
-### Authentication
+An environment variable can also be used via the `${}` syntax.
 
-`sqlc` expects to find a valid auth token in the value of the `SQLC_AUTH_TOKEN`
-environment variable. You can create an auth token via the [dashboard](https://dashboard.sqlc.dev).
-
-```shell
-export SQLC_AUTH_TOKEN=sqlc_xxxxxxxx
+```yaml
+version: '2'
+servers:
+- engine: postgresql
+  uri: ${DATABASE_URI}
+sql:
+- schema: schema.sql
+  queries: query.sql
+  engine: postgresql
+  database:
+    managed: true
 ```
 
 ## Improving codegen
@@ -61,8 +61,9 @@ on a per-query basis to speed up future codegen runs. Here's a minimal working c
 
 ```yaml
 version: '2'
-cloud:
-  project: '<PROJECT_ID>'
+servers:
+- engine: postgresql
+  uri: "postgres://locahost:5432/postgres?sslmode=disable"
 sql:
 - schema: schema.sql
   queries: query.sql
@@ -86,8 +87,9 @@ to ensure the query is valid. Here's a minimal working configuration:
 
 ```yaml
 version: '2'
-cloud:
-  project: '<PROJECT_ID>'
+servers:
+- engine: postgresql
+  uri: "postgres://locahost:5432/postgres?sslmode=disable"
 sql:
 - schema: schema.sql
   queries: query.sql
@@ -97,35 +99,3 @@ sql:
   rules:
   - sqlc/db-prepare
 ```
-
-## With other tools
-
-With managed databases configured, `sqlc createdb` will create a hosted ephemeral database with your
-schema and write the database's connection URI as a string to standard output (stdout). This allows you to use
-ephemeral databases with other tools that understand database connection strings.
-
-In the simplest case, you can use psql to poke around:
-
-```shell
-psql $(sqlc createdb)
-```
-
-Or if you're tired of waiting for us to resolve https://github.com/sqlc-dev/sqlc/issues/296,
-you can create databases ad hoc to use with pgtyped:
-
-```shell
-DATABASE_URL=$(sqlc createdb) npx pgtyped -c config.json
-```
-
-Here's a minimal working configuration if all you need to use is `sqlc createdb`:
-
-```yaml
-version: '2'
-cloud:
-  project: '<PROJECT_ID>'
-sql:
-- schema: schema.sql
-  engine: postgresql
-  database:
-    managed: true
-```

docs/howto/verify.md

@@ -1,9 +1,5 @@
 # `verify` - Verifying schema changes
 
-```{note}
-`verify` is powered by [sqlc Cloud](https://dashboard.sqlc.dev). Sign up for [free](https://dashboard.sqlc.dev) today.
-```
-
 *Added in v1.24.0*
 
 Schema updates and poorly-written queries often bring down production databases. That’s bad.

docs/tutorials/getting-started-mysql.md

@@ -184,14 +184,14 @@ 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
+## Query verification
 
-[sqlc Cloud](https://dashboard.sqlc.dev) provides additional insights into your
-queries, catching subtle bugs and performance issues. To get started, create a
+[sqlc Cloud](https://dashboard.sqlc.dev) provides additional verification, catching subtle bugs. 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:
@@ -219,7 +219,3 @@ export SQLC_AUTH_TOKEN="<your 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](../howto/managed-databases.md).

docs/tutorials/getting-started-postgresql.md

@@ -203,10 +203,9 @@ 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
+## Query verification
 
-[sqlc Cloud](https://dashboard.sqlc.dev) provides additional insights into your
-queries, catching subtle bugs and performance issues. To get started, create a
+[sqlc Cloud](https://dashboard.sqlc.dev) provides additional verification, catching subtle bugs. 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.
@@ -240,6 +239,10 @@ export SQLC_AUTH_TOKEN="<your sqlc auth token>"
 $ 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](../howto/managed-databases.md).
+In the sidebar, go to the "Queries" section to see your published queries. Run
+`verify` to ensure that previously published queries continue to work against
+updated database schema.
+
+```shell
+$ sqlc verify --against tutorial
+```