Using plugins
To use plugins, you must be using Version 2 of
the configuration file. The top-level plugins
array defines the available
plugins.
WASM plugins
WASM plugins are fully sandboxed; they do not have access to the network, filesystem, or environment variables.
In the codegen
section, the out
field dictates what directory will contain
the new files. The plugin
key must reference a plugin defined in the
top-level plugins
map. Any options
are serialized to a string as JSON and
passed on to the plugin itself.
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
options:
lang: en-US
For a complete working example see the following files:
-
A WASM plugin (written in Rust) that outputs a friendly message
-
An example project showing how to use a WASM plugin
Process plugins
Process-based plugins offer minimal security. Only use plugins that you trust. Better yet, only use plugins that you’ve written yourself.
In the codegen
section, the out
field dictates what directory will contain
the new files. The plugin
key must reference a plugin defined in the
top-level plugins
map. Any options
are serialized to a string as JSON and
passed on to the plugin itself.
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:
-
A process-based plugin that serializes the CodeGenRequest to 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,
you can configure access on a per-variable basis. For example, if your plugin
needs the PATH
environment variable, add PATH
to the env
list in the
plugins
collection.
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
A variable named SQLC_VERSION
is always included in the plugin’s
environment, set to the version of the sqlc
executable invoking it.