Document the parse and analyze commands

Add how-to pages for the new parse and analyze commands, list them in the
CLI reference, and register them in the Commands toctree.

Author: claude

docs/howto/analyze.md

@@ -0,0 +1,97 @@
+# `analyze` - Analyzing query result types
+
+`sqlc analyze` analyzes a query against a schema and prints the inferred result
+columns and parameters as a single JSON document.
+
+Unlike [`generate`](generate.md), this command does not require a configuration
+file and does not connect to a database. It uses sqlc's native static analysis
+to infer types directly from the provided schema.
+
+## Usage
+
+```sh
+sqlc analyze --dialect <dialect> --schema <schema-file> [query-file]
+```
+
+The query is read from the given file, or from standard input when no file is
+provided. The schema is always read from the `--schema` file.
+
+## Flags
+
+- `--dialect`, `-d` - The SQL dialect to use. One of `postgresql`, `mysql`, or
+  `sqlite`. Required.
+- `--schema`, `-s` - Path to the schema (DDL) file. Required.
+- `--ast` - Include each statement's AST in the output. Defaults to `false`.
+
+## Examples
+
+Given a schema in `schema.sql`:
+
+```sql
+CREATE TABLE authors (
+  id   BIGSERIAL PRIMARY KEY,
+  name text      NOT NULL,
+  bio  text
+);
+```
+
+and a query in `query.sql`:
+
+```sql
+-- name: GetAuthor :one
+SELECT * FROM authors WHERE id = $1;
+```
+
+Running:
+
+```sh
+sqlc analyze --dialect postgresql --schema schema.sql query.sql
+```
+
+reports the result columns and parameters:
+
+```json
+[
+  {
+    "name": "GetAuthor",
+    "cmd": ":one",
+    "columns": [
+      {
+        "name": "id",
+        "data_type": "bigserial",
+        "not_null": true,
+        "is_array": false,
+        "table": "authors"
+      },
+      {
+        "name": "name",
+        "data_type": "text",
+        "not_null": true,
+        "is_array": false,
+        "table": "authors"
+      },
+      {
+        "name": "bio",
+        "data_type": "text",
+        "not_null": false,
+        "is_array": false,
+        "table": "authors"
+      }
+    ],
+    "params": [
+      {
+        "number": 1,
+        "column": {
+          "name": "id",
+          "data_type": "bigserial",
+          "not_null": true,
+          "is_array": false,
+          "table": "authors"
+        }
+      }
+    ]
+  }
+]
+```
+
+Pass `--ast` to also include each statement's parsed AST under an `ast` key.

docs/howto/parse.md

@@ -0,0 +1,58 @@
+# `parse` - Parsing SQL into an AST
+
+`sqlc parse` parses SQL from a file or standard input and prints the abstract
+syntax tree (AST) as a single JSON document. It does not require a configuration
+file or a database connection.
+
+Each statement is reported with its sqlc query name and command (when the
+statement carries a [`-- name:`](../reference/query-annotations.md) annotation)
+alongside its AST.
+
+## Usage
+
+```sh
+sqlc parse --dialect <dialect> [file]
+```
+
+The SQL is read from the given file, or from standard input when no file is
+provided.
+
+## Flags
+
+- `--dialect`, `-d` - The SQL dialect to use. One of `postgresql`, `mysql`,
+  `sqlite`, or `clickhouse`. Required.
+
+## Examples
+
+Parse a query file:
+
+```sh
+sqlc parse --dialect postgresql query.sql
+```
+
+Parse SQL piped via standard input:
+
+```sh
+echo "SELECT 1;" | sqlc parse --dialect mysql
+```
+
+The output is a JSON array with one object per statement:
+
+```json
+[
+  {
+    "name": "GetAuthor",
+    "cmd": ":one",
+    "ast": {
+      "Stmt": {
+        "...": "..."
+      },
+      "StmtLocation": 0,
+      "StmtLen": 42
+    }
+  }
+]
+```
+
+Statements without a `-- name:` annotation (for example schema DDL) omit the
+`name` and `cmd` fields.

docs/index.rst

@@ -41,7 +41,9 @@ code ever again.
    :caption: Commands
    :hidden:
 
+   howto/analyze.md
    howto/generate.md
+   howto/parse.md
    howto/push.md
    howto/verify.md
    howto/vet.md

docs/reference/cli.md

@@ -5,13 +5,15 @@ Usage:
   sqlc [command]
 
 Available Commands:
+  analyze     Analyze a query against a schema and output the result columns and parameters
   compile     Statically check SQL for syntax and type errors
   completion  Generate the autocompletion script for the specified shell
   createdb    Create an ephemeral database
   diff        Compare the generated files to the existing files
   generate    Generate source code from SQL
   help        Help about any command
   init        Create an empty sqlc.yaml settings file
+  parse       Parse SQL and output the AST as JSON
   push        Push the schema, queries, and configuration for this project
   verify      Verify schema, queries, and configuration for this project
   version     Print the sqlc version number