From 781cc07e48e7aafbc9ada6b58c5a5b1d4e23f5f3 Mon Sep 17 00:00:00 2001 From: Samir Talwar Date: Mon, 4 Mar 2024 17:03:40 +0100 Subject: [PATCH] Update the README to accommodate recent changes. --- README.md | 57 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 36 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 8ed21ae0..65633252 100644 --- a/README.md +++ b/README.md @@ -2,34 +2,48 @@ This repository provides: -1. A registry of connectors and -2. Resources to help build connectors to connect new & custom data sources to Hasura. +1. a registry of connectors and +2. resources to help build connectors to connect new and custom data sources to + Hasura. -This allows Hasura users to instantly get a powerful Hasura GraphQL API (pagination, filtering, sorting, relationships) with granular RLS style authorization out of the box on any data-source (DBs, APIs). +This allows Hasura users to instantly get a powerful Hasura GraphQL API +(pagination, filtering, sorting, relationships) with granular RLS style +authorization out of the box on any data-source (DBs, APIs). -> [!WARNING] -> NDC hub (the set of connectors and the SDK to build new connectors) is currently in alpha, and subject to breaking changes. It is shared here to provide an early preview of what can be expected for connector development & deployment in the future, and feedback is welcome! If you have any comments, please create an issue. +> [!WARNING] NDC Hub (the set of connectors and the SDK to build new +> connectors) is currently in beta, and subject to large changes. It is +> shared here to provide an early preview of what can be expected for connector +> development & deployment in the future, and feedback is welcome! If you have +> any comments, please create an issue. ## Registry -There are 4 connectors you can start trying out today, and we'll gradually add more to this list: +There are some connectors you can start trying out today, and we'll gradually add more to this list: 1. [hasura/ndc-clickhouse](https://github.com/hasura/ndc-clickhouse) +1. [hasura/ndc-postgres](https://github.com/hasura/ndc-postgres) 2. [hasura/ndc-qdrant](https://github.com/hasura/ndc-qdrant) -3. [hasura/ndc-sendgrid](https://github.com/hasura/ndc-sendgrid/) +3. [hasura/ndc-sendgrid](https://github.com/hasura/ndc-sendgrid) 4. [hasura/ndc-typescript-deno](https://github.com/hasura/ndc-typescript-deno) ## SDK & Guides ### Connector Developer Guide -The best way to get started developing Hasura native data connectors is to [read the specification](http://hasura.github.io/ndc-spec/) and familiarise yourself with the [reference implementation](https://github.com/hasura/ndc-spec/tree/main/ndc-reference). +The best way to get started developing Hasura native data connectors is to +[read the specification](http://hasura.github.io/ndc-spec/) and familiarise +yourself with the [reference +implementation](https://github.com/hasura/ndc-spec/tree/main/ndc-reference). ### Rust SDK -This repository provides a Rust crate to aid development of [Hasura Native Data Connectors](https://hasura.github.io/ndc-spec/). Developers can implement a trait, and derive an executable which can be used to run a connector which is compatible with the specification. +This repository provides a Rust crate to aid development of [Hasura Native Data +Connectors](https://hasura.github.io/ndc-spec/). Developers can implement a +trait, and derive an executable which can be used to run a connector which is +compatible with the specification. -In addition, this library adopts certain conventions which are not covered by the current specification: +In addition, this library adopts certain conventions which are not covered by +the current specification: - Connector configuration - State management @@ -45,35 +59,36 @@ cargo build #### Run the example connector ```sh -cargo run --bin ndc_hub_example -- \ - --configuration <(echo 'null') +mkdir empty +cargo run --bin ndc_hub_example -- --configuration ./empty ``` Inspect the resulting (empty) schema: ```sh -curl http://localhost:8100/schema +curl http://localhost:8080/schema ``` -(the default port 8100 can be changed using `--port`) +(The default port, 8080, can be changed using `--port`.) ## Tracing -The serve command emits OTLP trace information. This can be used to see details of requests across services. +The serve command emits OTLP trace information. This can be used to see details +of requests across services. To enable tracing you must: -- Use the NDC-Hub option `--otlp-endpoint` e.g. `http://localhost:4317` -- Or, set the NDC-Hub ENV Variable `OTLP_ENDPOINT` -- Or, set the `tracing` ENV Variable `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` +- use the SDK option `--otlp-endpoint` e.g. `http://localhost:4317`, +- set the SDK environment variable `OTLP_ENDPOINT`, or +- set the `tracing` environment variable `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`. For additional service information you can: - Set `OTEL_SERVICE_NAME` e.g. `ndc_hub_example` -- Set `OTEL_RESOURCE_ATTRIBUTES` e.g. `key=value, k = v , a= x, a=z` +- Set `OTEL_RESOURCE_ATTRIBUTES` e.g. `key=value, k = v, a= x, a=z` -To view trace information during local development you can run a Jager server via Docker: +To view trace information during local development you can run a Jaeger server via Docker: ``` -docker run --name jaeger -e COLLECTOR_OTLP_ENABLED=true -p 16686:16686 -p 4317:4317 -p 4318:4318 jaegertracing/all-in-one:1.45 +docker run --name jaeger -e COLLECTOR_OTLP_ENABLED=true -p 16686:16686 -p 4317:4317 -p 4318:4318 jaegertracing/all-in-one ```