Connectors
Grain ships nine built-in connectors. Each is a separate module the daemon loads on demand, so a connector you never use costs nothing at startup and a driver that fails to load takes down only its own connector.
What each connector needs
| Connector | Required fields | Notes |
|---|---|---|
| PostgreSQL | host, port, user, database |
Optional SSL toggle. Port defaults to 5432 |
| MySQL | host, port, user, database |
Also covers MariaDB. Port defaults to 3306 |
| SQL Server | host, user, database |
Covers Azure SQL |
| SQLite | databasePath |
A path to a file on disk |
| DuckDB | databasePath |
Point it at a .duckdb file, or use in-memory for CSV and Parquet |
| Trino | host, port, user |
Catalog and schema are chosen per query |
| Snowflake | account, username |
account is the Snowflake account identifier, not a URL |
| BigQuery | projectId |
Authenticates through Google Application Default Credentials |
| Elasticsearch | host, port |
Queries the Elasticsearch SQL API |
Add a profile from the Grain panel in the activity bar. The form is generated from the connector’s own schema, so it always matches what that connector actually accepts.
Credentials are never in a config file
When you save a profile, Grain picks the first credential store available, in this order:
- An operating-system credential helper
- The OS keychain
- VS Code’s Secret Storage
- A local file protected by filesystem permissions — only when none of the above exists
Connection profiles live in ~/.grain/. Passwords do not.
For headless use where there is no editor to hold secrets, a connector’s own environment variable is the better option — PGPASSWORD for PostgreSQL, Application Default Credentials for BigQuery — rather than a password in GRAIN_CONNECTIONS.
Optional drivers
Six connectors depend on a driver that is not bundled with the extension, because bundling every database client would make the download many times larger for people who use one database.
| Connector | Driver |
|---|---|
| PostgreSQL | pg |
| MySQL | mysql2 |
| SQL Server | mssql |
| SQLite | sql.js |
| Snowflake | snowflake-sdk |
| BigQuery | @google-cloud/bigquery |
If a driver is missing, Grain does not fail with a stack trace. It recognises the specific failure, names the connector, and offers to install the driver for you. Only the six packages in that table can be installed this way — the list is an allowlist, not a free-form install.
DuckDB, Trino, and Elasticsearch need nothing extra. DuckDB’s runtime can be provisioned and managed by Grain itself.
Writing your own
The connector interface is a published package, @pattrnlabs/connector-api. A connector is a descriptor — an id, a display name, a JSON Schema for its configuration, and a factory — plus an implementation of the query interface. @pattrnlabs/connector-testkit carries the behavioural conformance checks every built-in connector passes, so a custom connector can be held to the same bar.