https://github.com/hasura/ndc-duckdb
https://github.com/hasura/ndc-duckdb
Last synced: 7 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/hasura/ndc-duckdb
- Owner: hasura
- License: apache-2.0
- Created: 2023-11-23T01:03:32.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-08-22T17:11:11.000Z (about 1 year ago)
- Last Synced: 2024-08-22T19:30:30.886Z (about 1 year ago)
- Language: TypeScript
- Size: 347 KB
- Stars: 6
- Watchers: 7
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/contributing.md
- License: LICENSE.txt
- Code of conduct: docs/code-of-conduct.md
- Security: docs/security.md
- Support: docs/support.md
Awesome Lists containing this project
- awesome-duckdb - Hasura DuckDB Connector - Allows connecting to a DuckDB database or a MotherDuck-hosted DuckDB database through a GraphQL API. (Integrations / Web Clients (WebAssembly))
README
# Hasura DuckDB Connector
[](https://hasura.io/connectors/duckdb)
[](https://hasura.io/connectors/duckdb)
[](https://github.com/hasura/ndc-duckdb/blob/main/LICENSE.txt)
[](https://github.com/hasura/ndc-duckdb/blob/main/README.md)
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](https://github.com/hasura/ndc-sdk-typescript) and implements the [Data Connector Spec](https://github.com/hasura/ndc-spec).
- [See the listing in the Hasura Hub](https://hasura.io/connectors/duckdb)
- [Hasura V3 Documentation](https://hasura.io/docs/3.0/index/)
## 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
1. The [DDN CLI](https://hasura.io/docs/3.0/cli/installation) and [Docker](https://docs.docker.com/engine/install/) installed
2. A [supergraph](https://hasura.io/docs/3.0/getting-started/init-supergraph)
3. A [subgraph](https://hasura.io/docs/3.0/getting-started/init-subgraph)
4. Have a [MotherDuck](https://motherduck.com/) 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](https://hasura.io/docs/3.0/getting-started/deployment/deploy-a-connector).
## Using the DuckDB connector
### Step 1: Authenticate your CLI session
```bash
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:
```bash
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:
`__`
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.
```bash
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.
```bash
ddn connector-link add-resources duckdb
```
## Documentation
View the full documentation for the DuckDB connector [here](https://github.com/hasura/ndc-duckdb/blob/main/docs/index.md).
## Contributing
Check out our [contributing guide](https://github.com/hasura/ndc-duckdb/blob/main/docs/contributing.md) for more details.
## License
The DuckDB connector is available under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).