diff --git a/README.md b/README.md index 4b2a2e5..3acb622 100644 --- a/README.md +++ b/README.md @@ -3,16 +3,20 @@ + [![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). + - [See the listing in the Hasura Hub](https://hasura.io/connectors/singlestore) - [Hasura V3 Documentation](https://hasura.io/docs/3.0) @@ -20,108 +24,79 @@ This connector is built using the [Typescript Data Connector SDK](https://github 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). - -### 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 -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://[[:]][@:[]]/[][?=[&=]]` 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 -``` - -## 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 -``` - -## 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 @@ -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).