more docs

Author: kyleconroy

docs/guides/plugins.md

@@ -15,32 +15,20 @@ top-level `plugins` map. The `options` are serialized to a string and passed on
 to the plugin itself.
 
 
-```json
-{
-  "version": "2",
-  "plugins": [
-    {
-      "name": "greeter",
-      "wasm": {
-        "url": "https://github.com/sqlc-dev/sqlc-gen-greeter/releases/download/v0.1.0/sqlc-gen-greeter.wasm",
-        "sha256": "afc486dac2068d741d7a4110146559d12a013fd0286f42a2fc7dcd802424ad07"
-      }
-    }
-  ],
-  "sql": [
-    {
-      "schema": "schema.sql",
-      "queries": "query.sql",
-      "engine": "postgresql",
-      "codegen": [
-        {
-          "out": "gen",
-          "plugin": "greeter"
-        }
-      ]
-    }
-  ]
-}
+```yaml
+version: '2'
+plugins:
+- name: greeter
+  wasm:
+    url: https://github.com/sqlc-dev/sqlc-gen-greeter/releases/download/v0.1.0/sqlc-gen-greeter.wasm
+    sha256: afc486dac2068d741d7a4110146559d12a013fd0286f42a2fc7dcd802424ad07
+sql:
+- schema: schema.sql
+  queries: query.sql
+  engine: postgresql
+  codegen:
+  - out: gen
+    plugin: greeter
 ```
 
 For a complete working example see the following files:
@@ -59,39 +47,51 @@ the new files. The `plugin` key must reference a plugin defined in the
 top-level `plugins` map. The `options` are serialized to a string and passed on
 to the plugin itself.
 
-```json
-{
-  "version": "2",
-  "plugins": [
-    {
-      "name": "jsonb",
-      "process": {
-        "cmd": "sqlc-gen-json"
-      }
-    }
-  ],
-   "sql": [
-    {
-      "schema": "schema.sql",
-      "queries": "query.sql",
-      "engine": "postgresql",
-      "codegen": [
-        {
-          "out": "gen",
-          "plugin": "jsonb",
-          "options": {
-            "indent": "  ",
-            "filename": "codegen.json"
-          }
-        }
-      ]
-    }
-  ]
-}
+```yaml
+version: '2'
+plugins:
+- name: jsonb
+  process:
+    cmd: sqlc-gen-json
+sql:
+- schema: schema.sql
+  queries: query.sql
+  engine: postgresql
+  codegen:
+  - out: gen
+    plugin: jsonb
+    options:
+      indent: "  "
+      filename: codegen.json
 ```
 
 For a complete working example see the following files:
 - [sqlc-gen-json](https://github.com/sqlc-dev/sqlc/tree/main/cmd/sqlc-gen-json)
   - A process-based plugin that serializes the CodeGenRequest to JSON
 - [process_plugin_sqlc_gen_json](https://github.com/sqlc-dev/sqlc/tree/main/internal/endtoend/testdata/process_plugin_sqlc_gen_json)
   - An example project showing how to use a process-based plugin
+
+## Environment variables
+
+By default, plugins do not inherit access to environment variables. Instead,
+access can be configured on a per-variable basis. For example, if your plugin
+needs the `PATH` environment variable, add the `PATH` to the `env` option in the
+`plugins` collection.
+
+```yaml
+version: '2'
+sql:
+- schema: schema.sql
+  queries: query.sql
+  engine: postgresql
+  codegen:
+  - out: gen
+    plugin: test
+plugins:
+- name: test
+  env:
+  - PATH
+  wasm:
+    url: https://github.com/sqlc-dev/sqlc-gen-test/releases/download/v0.1.0/sqlc-gen-test.wasm
+    sha256: 138220eae508d4b65a5a8cea555edd155eb2290daf576b7a8b96949acfeb3790
+```

docs/reference/config.md

@@ -316,6 +316,8 @@ Each mapping in the `plugins` collection has the following keys:
 
 - `name`:
   - The name of this plugin. Required
+- `env`
+  - A list of environment variables to pass to the plugin. By default, no environment variables are passed.
 - `process`: A mapping with a single `cmd` key
   - `cmd`:
     - The executable to call when using this plugin
@@ -333,6 +335,8 @@ plugins:
     url: "https://github.com/sqlc-dev/sqlc-gen-python/releases/download/v0.16.0-alpha/sqlc-gen-python.wasm"
     sha256: "428476c7408fd4c032da4ec74e8a7344f4fa75e0f98a5a3302f238283b9b95f2"
 - name: "js"
+  env:
+  - PATH
   process: 
     cmd: "sqlc-gen-json"
 ```