Hasura DuckDB Connector
The Hasura DuckDB Connector allows for connecting to a DuckDB database or a MotherDuck hosted DuckDB database to give you an instant GraphQL API on top of your DuckDB data.
This connector is built using the Typescript Data Connector SDK and implements the Data Connector Spec.
Features
Below, you'll find a matrix of all supported features for the DuckDB connector:
Feature | Supported | Notes |
---|---|---|
Native Queries + Logical Models | ❌ | |
Simple Object Query | ✅ | |
Filter / Search | ✅ | |
Simple Aggregation | ❌ | |
Sort | ✅ | |
Paginate | ✅ | |
Table Relationships | ✅ | |
Views | ❌ | |
Distinct | ❌ | |
Remote Relationships | ✅ | |
Custom Fields | ❌ | |
Mutations | ❌ |
Before you get Started
- The DDN CLI and Docker installed
- A supergraph
- A subgraph
- Have a MotherDuck hosted DuckDB database, or a persitent DuckDB database file — for supplying data to your API.
The steps below explain how to Initialize and configure a connector for local development. You can learn how to deploy a connector — after it's been configured — here.
Using the DuckDB connector
Step 1: Authenticate your CLI session
ddn auth login
Step 2: Configure the connector
Once you have an initialized supergraph and subgraph, run the initialization command in interactive mode while providing a name for the connector in the prompt:
ddn connector init duckdb -i
Step 2.1: Choose the hasura/duckdb
option from the list
Step 2.2: Choose a port for the connector
The CLI will ask for a specific port to run the connector on. Choose a port that is not already in use or use the default suggested port.
Step 2.3: Provide the env var(s) for the connector
Name | Description |
---|---|
DUCKDB_URL | The connection string for the DuckDB database, or the file path to the DuckDB database file |
You'll find the environment variables in the .env
file and they will be in the format:
<SUBGRAPH_NAME>_<CONNECTOR_NAME>_<VARIABLE_NAME>
Here is an example of what your .env
file might look like:
APP_DUCKDB_AUTHORIZATION_HEADER="Bearer SPHZWfL7P3Jdc9mDMF9ZNA==" APP_DUCKDB_DUCKDB_URL="md:?motherduck_token=ey..." APP_DUCKDB_HASURA_SERVICE_TOKEN_SECRET="SPHZWfL7P3Jdc9mDMF9ZNA==" APP_DUCKDB_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://local.hasura.dev:4317" APP_DUCKDB_OTEL_SERVICE_NAME="app_duckdb" APP_DUCKDB_READ_URL="http://local.hasura.dev:7525" APP_DUCKDB_WRITE_URL="http://local.hasura.dev:7525"
If you are attaching to a local DuckDB file, first make sure that the file is located inside the connector directory. For example, if you had a data.duckdb
file you could place it at /app/connector/duckdb/data.duckdb
. Files in the connector directory get mounted to /etc/connector/
.
In this instance, you would set the DUCKDB_URL=/etc/connector/data.duckdb
. Now your .env
might look like this:
APP_DUCKDB_AUTHORIZATION_HEADER="Bearer SPHZWfL7P3Jdc9mDMF9ZNA==" APP_DUCKDB_DUCKDB_URL="/etc/connector/data.duckdb" APP_DUCKDB_HASURA_SERVICE_TOKEN_SECRET="SPHZWfL7P3Jdc9mDMF9ZNA==" APP_DUCKDB_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://local.hasura.dev:4317" APP_DUCKDB_OTEL_SERVICE_NAME="app_duckdb" APP_DUCKDB_READ_URL="http://local.hasura.dev:7525" APP_DUCKDB_WRITE_URL="http://local.hasura.dev:7525"
Your experience mounting files may vary, and while useful to explore a file locally, it's not recommended to attempt to deploy a connector using a locally mounted file.
Step 3: Introspect the connector
Introspecting the connector will generate a config.json
file and a duckdb.hml
file.
ddn connector introspect duckdb
Step 4: Add your resources
You can add the models, commands, and relationships to your API by tracking them which generates the HML files.
ddn connector-link add-resources duckdb
Documentation
View the full documentation for the DuckDB connector here.
Contributing
Check out our contributing guide for more details.
License
The DuckDB connector is available under the Apache License 2.0.