v1.1.0

Highlights

Support NDC spec v0.1.2

Support schema for NDC spec v0.1.2 with more representations and reusable scalars:

• BigInt: implements int64 representation which can encode and decode from number string.
• Date: implements date representation which can encode and decode from ISO 8601 date string.

Test Snapshots

The tool supports test snapshots generation for query and mutation requests and responses that are compatible with ndc-test replay command. See generated snapshots at the codegen example.

Usage: hasura-ndc-go test snapshots

Generate test snapshots.

Flags:
  -h, --help                     Show context-sensitive help.
      --log-level="info"         Log level.

      --schema=STRING            NDC schema file path. Use either endpoint or schema path
      --endpoint=STRING          The endpoint of the connector. Use either endpoint or schema path
      --dir=STRING               The directory of test snapshots.
      --depth=10                 The selection depth of nested fields in result types.
      --query=QUERY,...          Specify individual queries to be generated. Separated by commas, or 'all' for all queries
      --mutation=MUTATION,...    Specify individual mutations to be generated. Separated by commas, or 'all' for all mutations
      --strategy="none"          Decide the strategy to do when the snapshot file exists. Accept: none, override.

The command accepts either a connector --endpoint or a JSON --schema file.

Endpoint

hasura-ndc-go test snapshots --endpoint http://localhost:8080 --dir testdata

NDC Schema

hasura-ndc-go test snapshots --schema schema.generated.json --dir testdata

What's Changed

• add convenience scripts by @hgiasac in #59
• Add test snapshots command by @hgiasac in #61
• Support ndc spec v0.1.2 by @hgiasac in #63
• update capabilities v0.1.2 by @hgiasac in #65
• Support test snapshots generation with NDC spec v0.1.2 by @hgiasac in #67
• improve value decoder for Boolean and String by @hgiasac in #69

Full Changelog: v1.0.0...v1.1.0

v0.5.0

Highlights

Support NDC spec v0.1.2

Support schema for NDC spec v0.1.2 with more representations and reusable scalars:

• BigInt: implements int64 representation which can encode and decode from number string.
• Date: implements date representation which can encode and decode from ISO 8601 date string.

Test Snapshots

The tool supports test snapshots generation for query and mutation requests and responses that are compatible with ndc-test replay command. See generated snapshots at the codegen example.

Usage: hasura-ndc-go test snapshots

Generate test snapshots.

Flags:
  -h, --help                     Show context-sensitive help.
      --log-level="info"         Log level.

      --schema=STRING            NDC schema file path. Use either endpoint or schema path
      --endpoint=STRING          The endpoint of the connector. Use either endpoint or schema path
      --dir=STRING               The directory of test snapshots.
      --depth=10                 The selection depth of nested fields in result types.
      --query=QUERY,...          Specify individual queries to be generated. Separated by commas, or 'all' for all queries
      --mutation=MUTATION,...    Specify individual mutations to be generated. Separated by commas, or 'all' for all mutations
      --strategy="none"          Decide the strategy to do when the snapshot file exists. Accept: none, override.

The command accepts either a connector --endpoint or a JSON --schema file.

Endpoint

hasura-ndc-go test snapshots --endpoint http://localhost:8080 --dir testdata

NDC Schema

hasura-ndc-go test snapshots --schema schema.generated.json --dir testdata

What's Changed

• feat: add convenience scripts by @hgiasac in #58
• feat: add test snapshots command by @hgiasac in #60
• feat: update NDC Spec v0.1.2 by @hgiasac in #62
• utils: improve value decoder for Boolean and String by @hgiasac in #68

Full Changelog: v0.4.0...v0.5.0

v1.0.0

Behavior changes

The new major version drops support of Go < v1.21 with the latest OpenTelemetry dependencies and uses the standard slog library for logging.

If you still use Go 1.19 or 1.20, downgrade to v0.4.0 instead.

What's Changed

• upgrade go 1.21 and dependencies by @hgiasac in #14

Full Changelog: v0.4.0...v1.0.0

v0.4.0

Highlights

Support schema for NDC spec v0.1.1 with TypeRepresentation and enum. You can define the enum type with @enum comment tag. The data type must be an alias of string.

// @enum <values separated by commas>
//
// example:
//
// SomeEnum some enum
// @enum foo, bar
type SomeEnum string

The tool will help generate schema, constants, and helper methods for it.

{
  "scalar_types": {
    "SomeEnum": {
      "aggregate_functions": {},
      "comparison_operators": {},
      "representation": {
        "one_of": ["foo", "bar"],
        "type": "enum"
      }
    }
  }
}

Behavior changes

• Change the result of ParseXxx functions to a value instead of a pointer.

What's Changed

• Support NDC Spec v0.1.1 by @hgiasac in #48

Full Changelog: v0.3.0...v0.4.0

v0.3.0

What's Changed

Behavior changes

SDK

• The SDK no longer detects HTTP protocol via http(s) scheme in the URL. By default, the OTEL exporter uses GRPC protocol. You can change to HTTP protocol by using port 4318 or set OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf.
• Now you can choose only one metrics exporter by OTEL_METRICS_EXPORTER=<none|otlp|prometheus> variable. By default metrics exporter is disabled (none).
• If OTEL_METRICS_EXPORTER != prometheus, the /metrics route returns HTTP 404. You can change the Prometheus service to another port with OTEL_EXPORTER_PROMETHEUS_PORT variable.
• Bad request HTTP status is changed to HTTP 422. Engine v3 only exposes errors with this status (source).

Generator

• Boost generation performance to 100x with go/packages.
• Require the function or type name in the head of the comment if using comment tags.

// CreateAuthor this procedure will be parsed (OK)
// @procedure
func CreateAuthor(ctx context.Context, state *types.State, arguments *CreateAuthorArguments) (*CreateAuthorResult, error)

// This function won't be parsed because there is no `Foo` in the head (FAIL)
// @function
func Foo(ctx context.Context, state *types.State) (bool, error)

Changelog

• add unsafe constructors for schema and capabilities responses by @hgiasac in #38
• add more OTEL configuration options by @hgiasac in #40
• improve OpenTelemetry trace spans and events by @hgiasac in #42
• improve generator performance by @hgiasac in #44

Full Changelog: v0.2.0...v0.3.0

v0.2.0

What's Changed

Breaking Changes

• Change capabilities and schema responses in Connector interface to CapabilitiesResponseMarshaler and SchemaResponseMarshaler. It's helpful to custom the response, for example, return static bytes directly with RawSchemaResponse and RawCapabilitiesResponse.
• Add Context parameter to ParseConfiguration and TryInitState
• Add State parameter to GetSchema

ParseConfiguration(ctx context.Context, configurationDir string) (*Configuration, error)

TryInitState(ctx context.Context, configuration *Configuration, metrics *TelemetryState) (*State, error)

GetCapabilities(configuration *Configuration) schema.CapabilitiesResponseMarshaler

GetSchema(ctx context.Context, configuration *Configuration, state *State) (schema.SchemaResponseMarshaler, error)

Highlights

Customize the CLI

The SDK uses Kong, a lightweight command-line parser to implement the CLI interface.

The default CLI already implements the serve command, so you don't need to do anything. If you want to add more custom commands, the SDK abstracts an interface for the CLI that requires embedding the base ServeCLI command and can execute other commands.

type ConnectorCLI interface {
	GetServeCLI() *ServeCLI
	Execute(ctx context.Context, command string) error
}

And use the StartCustom function to start the CLI.

See the custom CLI example in the reference connector.

Changelog

• restructure schema package and add more unmarshal utils by @hgiasac in #27
• add state argument to GetSchema method by @hgiasac in #29
• Extend CLI interface and add context to ParseConfiguration and TryInitState methods by @hgiasac in #31
• fix invalid capabilities version by @hgiasac in #33
• introduce capabilities schema marshalers by @hgiasac in #35

Full Changelog: v0.1.3...v0.2.0

v0.1.3

What's Changed

• fix: function query selection evaluation and improve OTEL propagator extraction by @hgiasac in #24

Full Changelog: v0.1.2...v0.1.3

v0.1.2

What's Changed

• Fix redundant mapstructure import by @hgiasac in #21
• fix telemetry shutdown with one error by @hgiasac in #23

Full Changelog: v0.1.1...v0.1.2

v0.1.1

What's Changed

• Rename the binary name to hasura-ndc-go to follow the NDC CLI plugin specification. The codegen tool may be developed as a plugin in the future.
• The init command is also changed to new to avoid conflicting with the CLI command spec.
• The time.Duration type doesn't support JSON decoding from string, e.g. 1s, 1m. So the codegen tool shouldn't support that type. Users need to define a scalar wrapper to support it themselves.
• Create a new Decoder type that wraps mapstructure.Encoder to support nested values mapping. Improve mapping from any types without falling back to JSON encoding/decoding.
• uuid.UUID decoder is optionally generated if any argument or return type property contains this type.

Changelog

• fix missing fmt package in template by @hgiasac in #15
• Change init command to new by @hgiasac in #16
• codegen: drop time.Duration support and update UUID scalar codegen by @hgiasac in #18

Full Changelog: v0.1.0...v0.1.1

v0.1.0

Key Features

The SDK fully supports NDC Specification v0.1.0 and Connector Deployment spec with following features:

• Connector HTTP server
• Authentication
• Observability with OpenTelemetry and Prometheus

The NDC code generator provides tools to develop data connectors quickly. You can use it to set up new projects and generate queries, and mutations from Go functions. See the example project here.

The SDK supports Go 1.19+ in v0.x versions. The next major version (v1.x) will support Go 1.21+ only.

New Contributors

• @hgiasac made their first contribution in #1
• @OjasWadhwani made their first contribution in #2

Full Changelog: https://github.com/hasura/ndc-sdk-go/commits/v0.1.0