Skip to content

Commit

Permalink
Modified README to match ndc-hub version
Browse files Browse the repository at this point in the history
  • Loading branch information
Adalbert Makarovych committed Oct 2, 2024
1 parent 4a7e713 commit f26ee20
Showing 1 changed file with 69 additions and 93 deletions.
162 changes: 69 additions & 93 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,125 +3,100 @@
<a href="https://www.singlestore.com/"><img src="https://github.com/singlestore-labs/singlestore-hasura-connector/blob/main/docs/logo_primary_singlestore_black.png" align="right" width="200"></a>

<!-- TODO: update when connector will be published -->

[![Docs](https://img.shields.io/badge/docs-v3.x-brightgreen.svg?style=flat)](https://hasura.io/docs/3.0/latest/connectors/singesltore/)
[![ndc-hub](https://img.shields.io/badge/ndc--hub-singlestore-blue.svg?style=flat)](https://hasura.io/connectors/singlestore)
[![License](https://img.shields.io/badge/license-Apache--2.0-purple.svg?style=flat)](LICENSE)
[![Status](https://img.shields.io/badge/status-alpha-yellow.svg?style=flat)](./readme.md)

The Hasura SingleStore Connector ("the connector") enables you to connect to a SingleStore database and gives instant access to a GraphQL API on top of your data.
The Hasura SingleStore Connector ("the connector") enables you to connect to a SingleStore database and gives instant
access to a GraphQL API on top of your data.

This connector is built using the [Typescript Data Connector SDK](https://github.com/hasura/ndc-sdk-typescript) and, it implements the [Data Connector Spec](https://github.com/hasura/ndc-spec).
This connector is built using the [Typescript Data Connector SDK](https://github.com/hasura/ndc-sdk-typescript) and, it
implements the [Data Connector Spec](https://github.com/hasura/ndc-spec).

<!-- TODO: update when connector will be published -->

- [See the listing in the Hasura Hub](https://hasura.io/connectors/singlestore)
- [Hasura V3 Documentation](https://hasura.io/docs/3.0)

## Features

The following matrix lists the features supported by the Hasura SingleStore connector:

| Feature | Supported | Notes |
| ------------------------------- | --------- | ----- |
| Native Queries + Logical Models | ❌ | |
| Simple Object Query | ✅ | |
| Filter / Search | ✅ | |
| Simple Aggregation | ✅ | |
| Sort | ✅ | |
| Paginate | ✅ | |
| Table Relationships | ✅ | |
| Views | ✅ | |
| Distinct | ✅ | |
| Remote Relationships | ✅ | |
| Mutations | ❌ | coming soon |
| Feature | Supported | Notes |
| ------------------------------- | --------- | ----------- |
| Native Queries + Logical Models | ❌ | |
| Simple Object Query | ✅ | |
| Filter / Search | ✅ | |
| Simple Aggregation | ✅ | |
| Sort | ✅ | |
| Paginate | ✅ | |
| Table Relationships | ✅ | |
| Views | ✅ | |
| Distinct | ✅ | |
| Remote Relationships | ✅ | |
| Mutations | ❌ | coming soon |

## Prerequisites

Ensure that the following prerequisites are met before using the connector:

1. Install [DDN CLI](https://hasura.io/docs/3.0/cli/installation) and [Docker](https://docs.docker.com/engine/install/).
2. Initialize a [supergraph](https://hasura.io/docs/3.0/getting-started/init-supergraph).
3. Initialize a [subgraph](https://hasura.io/docs/3.0/getting-started/init-subgraph).
4. An active [SingleStore](https://www.singlestore.com/) deployment that serves as the data source for the API.
1. Create a [Hasura Cloud account](https://console.hasura.io)
2. Please ensure you have the [DDN CLI](https://hasura.io/docs/3.0/cli/installation) and
[Docker](https://docs.docker.com/engine/install/) installed
3. [Create a supergraph](https://hasura.io/docs/3.0/getting-started/init-supergraph)
4. [Create a subgraph](https://hasura.io/docs/3.0/getting-started/init-subgraph)
5. An active [SingleStore](https://www.singlestore.com/) deployment that serves as the data source for the API.

The steps below explain how to initialize and configure a connector on your local machine (typically for development
purposes).You can learn how to deploy a connector to Hasura DDN — after it's been configured —
[here](https://hasura.io/docs/3.0/getting-started/deployment/deploy-a-connector).

## Using the SingleStore connector

The following steps explain how to initialize and configure the connector for local development. For information on deploying a connector after it has been configured, refer to [Deploy a Connector](https://hasura.io/docs/3.0/getting-started/deployment/deploy-a-connector).
<!-- TODO: test steps after the connector will be published to hub -->
### Step 1: Authenticate your CLI session

```bash
ddn auth login
```

### Step 2: Configure the connector

After the supergraph and subgraph have been initialized (refer to [Prerequisites](#Prerequisites)), run the initialization command in interactive mode. Specify a name for the connector in the command.
With the [context set](https://hasura.io/docs/3.0/cli/commands/ddn_context_set/) for an existing subgraph, initialize
the connector:

```bash
ddn connector init <connector-name> -i
```sh
ddn connector init -i
```

#### Step 2.1: Select the SingleStore connector

From the list of connectors, select `singlestore`.

#### Step 2.2: Select a port for the connector
The CLI prompts you to specify a port for running the connector. Either select the default port suggested or choose a port that is not currently in use.

#### Step 2.3: Provide the environment variable(s) for the connector

Specify the connection string used to connect to the SingleStore database using the `SINGLESTORE_URL` variable. The connection string must be in the `mysql://[<username>[:<password>]][@<host>:[<port>]]/[<database>][?<key1>=<value1>[&<key2>=<value2>]]` format.

For example:

```env
SINGLESTORE_URL=singlestore://username:password@hostname/database
```
The connector uses [MySQL2](https://sidorares.github.io/node-mysql2/docs) library to establish a connection.
For more information, refer to [Connection options](https://www.npmjs.com/package/mysql#connection-options) and [Pool options](https://www.npmjs.com/package/mysql#pool-options).
When the wizard runs, you'll be prompted to enter the following env vars necessary for your connector to function:

| Name | Default | Description |
| ----------------------------------- | --------- | --------------------------------------------------------------------------------------------------- |
| SINGLESTORE_HOST | localhost | Hostname of the SingleStore database to connect with. |
| SINGLESTORE_PORT | 3306 | Port number of the SingleStore database. |
| SINGLESTORE_USER | | SingleStore user to authenticate as. |
| SINGLESTORE_PASSWORD | | Password of the SingleStore database user. |
| SINGLESTORE_DATABASE | | Name of the SingleStore database to connect with. |
| SINGLESTORE_SSL_CA | | CA certificate. |
| SINGLESTORE_SSL_CERT | | Certificate chain in PEM format. |
| SINGLESTORE_SSL_KEY | | Private key in PEM format. |
| SINGLESTORE_SSL_CIPHERS | | Cipher suite specification. If specified, it replaces the default value. |
| SINGLESTORE_SSL_PASSPHRASE | | Shared passphrase used for a single private key. |
| SINGLESTORE_SSL_REJECT_UNAUTHORIZED | true | If enabled, the server rejects any connection that is not authorized with the list of supplied CAs. |

The connector uses [MySQL2](https://sidorares.github.io/node-mysql2/docs) library to establish a connection. For more
information, refer to [Connection options](https://www.npmjs.com/package/mysql#connection-options) and
[Pool options](https://www.npmjs.com/package/mysql#pool-options).

After the CLI initializes the connector, you'll need to:

- [Introspect](https://hasura.io/docs/3.0/cli/commands/ddn_connector_introspect) the source.
- Add your [models](https://hasura.io/docs/3.0/cli/commands/ddn_model_add),
[commands](https://hasura.io/docs/3.0/cli/commands/ddn_command_add), and
[relationships](https://hasura.io/docs/3.0/cli/commands/ddn_relationship_add).
- Create a [new build](https://hasura.io/docs/3.0/cli/commands/ddn_supergraph_build_local).
- Test it by [running your project along with the connector](https://hasura.io/docs/3.0/cli/commands/ddn_run#examples).

### Note

SingleStore does not support foreign keys. Relationships between tables must be added manually. You can define
relationships by appending relationship information to the `.hml` files generated in the previous step. For information
on defining relationships, refer to [Relationships](https://hasura.io/docs/3.0/supergraph-modeling/relationships/). For
example, to add a relationship from a `message` table to the `user` table, append following text to the `DbMessage.hml`
file:

Alternatively, you can also set following environment variables instead of the `SINGLELSTORE_URL` variable:

| Name | Default | Description |
|-------------------------------------|-------------|-------------|
| SINGLESTORE_HOST | localhost | Hostname of the SingleStore database to connect with. |
| SINGLESTORE_PORT | 3306 | Port number of the SingleStore database. |
| SINGLESTORE_USER | | SingleStore user to authenticate as. |
| SINGLESTORE_PASSWORD | | Password of the SingleStore database user. |
| SINGLESTORE_DATABASE | | Name of the SingleStore database to connect with. |
| SINGLESTORE_SSL_CA | | CA certificate. |
| SINGLESTORE_SSL_CERT | | Certificate chain in PEM format. |
| SINGLESTORE_SSL_KEY | | Private key in PEM format. |
| SINGLESTORE_SSL_CIPHERS | | Cipher suite specification. If specified, it replaces the default value. |
| SINGLESTORE_SSL_PASSPHRASE | | Shared passphrase used for a single private key. |
| SINGLESTORE_SSL_REJECT_UNAUTHORIZED | true | If enabled, the server rejects any connection that is not authorized with the list of supplied CAs. |

If `SINGLELSTORE_URL` is set these variables are ignored.

### Step 3: Introspect your data source

After configuring the connector, use the CLI to introspect the SingleStore database and create a source-specific configuration file for the connector (`configuration.json`).

```bash
ddn connector introspect <connector-name>
```

## Step 4: Add your resources

This command will create `.hml` files for each table and view in your database
and an `.hml` file with information about SingleStore data types.

```bash
ddn connector-link add-resources <connector-name>
```

## Step 5. Add relationships

SingleStore does not support foreign keys. Relationships between tables must be added manually. You can define relationships by appending relationship information to the `.hml` files generated in the previous step.
For information on defining relationships, refer to [Relationships](https://hasura.io/docs/3.0/supergraph-modeling/relationships/).
For example, to add a relationship from a `message` table to the `user` table, append following text to the
`DbMessage.hml` file:
```hml
---
kind: Relationship
Expand All @@ -143,6 +118,7 @@ definition:
- fieldName: id
description: The user details for a message
```

## License

The SingleStore connector is available under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).

0 comments on commit f26ee20

Please sign in to comment.