fix

Author: asmyasnikov

docs/guides/engine-plugins.md

@@ -66,6 +66,20 @@ sql:
 
 Each engine must define either `process` (with `cmd`) or `wasm` (with `url` and `sha256`). See [Configuration reference](../reference/config.md) for the full `engines` schema.
 
+### How sqlc finds the process plugin
+
+For an engine with `process.cmd`, sqlc resolves and runs the plugin as follows:
+
+1. **Command parsing** — `process.cmd` is split on whitespace. The first token is the executable; any further tokens are passed as arguments, and sqlc appends the RPC method name (`parse`) when invoking the plugin.
+
+2. **Executable lookup** — The first token is resolved the same way as in the shell:
+   - If it contains a path separator (e.g. `/usr/bin/sqlc-engine-mydb` or `./bin/sqlc-engine-mydb`), it is treated as a path. Absolute paths are used as-is; relative paths are taken relative to the **current working directory of the process running sqlc**.
+   - If it has no path separator, the executable is looked up in the **PATH** of the process running sqlc. The plugin binary must be on PATH (e.g. after `go install` or adding its directory to PATH) or `process.cmd` must be an absolute path.
+
+3. **Working directory** — The plugin process is started with its working directory set to the **directory containing the sqlc config file**. That directory is used for resolving relative paths inside the plugin, not for resolving `process.cmd` itself.
+
+If the executable cannot be found or `process.cmd` is empty, sqlc reports an error and refers to this documentation.
+
 ## Implementing an engine plugin (Go)
 
 ### 1. Dependencies and entrypoint

internal/cmd/plugin_engine.go

@@ -45,12 +45,12 @@ func (r *engineProcessRunner) invoke(ctx context.Context, method string, req, re
 
 	cmdParts := strings.Fields(r.Cmd)
 	if len(cmdParts) == 0 {
-		return fmt.Errorf("engine plugin not found: %s\n\nMake sure the plugin is installed and available in PATH.\nInstall with: go install <plugin-module>@latest", r.Cmd)
+		return fmt.Errorf("engine plugin not found: %s\n\nSee the engine plugins documentation: https://docs.sqlc.dev/en/latest/guides/engine-plugins.html", r.Cmd)
 	}
 
 	path, err := exec.LookPath(cmdParts[0])
 	if err != nil {
-		return fmt.Errorf("engine plugin not found: %s\n\nMake sure the plugin is installed and available in PATH.\nInstall with: go install <plugin-module>@latest", r.Cmd)
+		return fmt.Errorf("engine plugin not found: %s\n\nSee the engine plugins documentation: https://docs.sqlc.dev/en/latest/guides/engine-plugins.html", r.Cmd)
 	}
 
 	args := append(cmdParts[1:], method)
@@ -97,8 +97,7 @@ func runPluginQuerySet(ctx context.Context, rp ResultProcessor, name, dir string
 	enginePlugin, found := config.FindEnginePlugin(&combo.Global, string(combo.Package.Engine))
 	if !found || enginePlugin.Process == nil {
 		e := string(combo.Package.Engine)
-		return fmt.Errorf("unknown engine: %s\n\nTo use a custom database engine, add it to the 'engines' section of sqlc.yaml:\n\n  engines:\n    - name: %s\n      process:\n        cmd: sqlc-engine-%s\n\nThen install the plugin: go install github.com/example/sqlc-engine-%s@latest",
-			e, e, e, e)
+		return fmt.Errorf("unknown engine: %s\n\nAdd the engine to the 'engines' section of sqlc.yaml. See the engine plugins documentation: https://docs.sqlc.dev/en/latest/guides/engine-plugins.html", e)
 	}
 
 	var parseFn func(schemaSQL, querySQL string) (*pb.ParseResponse, error)

internal/endtoend/testdata/bad_config/engine/stderr.txt

@@ -1 +1,3 @@
-error creating compiler: unknown engine: bad_engine
+error creating compiler: unknown engine: bad_engine
+
+Add the engine to the 'engines' section of sqlc.yaml. See the engine plugins documentation: https://docs.sqlc.dev/en/latest/guides/engine-plugins.html