Let's Build a Connector!

This repository contains a series of tutorials which walk through the process of creating a data connector in small steps. We will build a connector to sqlite which you can run locally on your machine, either by cloning this repo, or by following along with each tutorial.

It is recommended that you first review the Hasura NDC Specification and accompanying reference implementation, at least to gain a basic familiarity with the concepts, but these materials are intended to be complementary.

The dependencies required to follow along here are minimal - you will need Node and npm so that you can run the TypeScript compiler. If you'd like to follow along using the same test-driven approach, then you will also need a working ndc-test executable on your PATH. ndc-test can be installed using the Rust toolchain from the ndc-spec repository.

Tutorials

1. Setup
2. Predicates
3. Sorting
4. Aggregates
5. Relationships
6. Custom Operators
7. Observability

Other Resources

• NDC Specification
  • Reference Implementation with Tutorial
• SDKs
  • NDC Rust SDK
  • NDC Typescript SDK
• Examples of Native Connectors
  • Clickhouse (Rust)
  • QDrant (Typescript)
  • Deno (Typescript)

Getting Started

npm i
npm run build

Run the connector:

node dist/index.js serve --configuration .

To start from scratch and create the initial project:

npm init
npm i typescript
npx tsc --init
npm i @hasura/ndc-sdk-typescript sqlite sqlite3

Running the connector using Docker

The provided Dockerfile can be used to build and run the connector inside a Docker container:

docker build -t ndc-learn .
docker run -p 8080:8080 -it ndc-learn

Local development using v3-engine

The docker-compose.yaml file provides an environment with the open source Hasura v3-engine, this connector, Jaeger for tracing, and Prometheus for metrics:

docker compose up
open http://localhost:3000 # Graphiql
open http://localhost:4002 # Jaeger
open http://localhost:9090 # Prometheus

When using Graphiql, remember to provide the appropriate headers. Specifically, x-hasura-role can be set to admin for testing.