Skip to content

Commit

Permalink
Update turso connector to v0.1.0 (#261)
Browse files Browse the repository at this point in the history 
This PR updates the turso connector metadata to version 0.1.0.

---------

Co-authored-by: GitHub Action <[email protected]>
  • Loading branch information
@TristenHarr @actions-user
TristenHarr and actions-user authored Aug 30, 2024
1 parent 9710600 commit 82d6195
Show file tree
Hide file tree
Showing 4 changed files with 71 additions and 95 deletions.
123 changes: 42 additions & 81 deletions registry/hasura/turso/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# Hasura Turso Connector
<a href="https://turso.tech/"><img src="https://github.com/hasura/ndc-turso/blob/main/docs/logo.svg" align="right" width="200"></a>


[![Docs](https://img.shields.io/badge/docs-v3.x-brightgreen.svg?style=flat)](https://hasura.io/connectors/turso)
[![ndc-hub](https://img.shields.io/badge/ndc--hub-turso-blue.svg?style=flat)](https://hasura.io/connectors/turso)
[![License](https://img.shields.io/badge/license-Apache--2.0-purple.svg?style=flat)](https://github.com/hasura/ndc-turso/blob/main/LICENSE.txt)
Expand All @@ -10,8 +11,8 @@ The Hasura Turso Connector allows for connecting to a LibSQL/SQLite database or

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

* [Connector information in the Hasura Hub](https://hasura.io/connectors/turso)
* [Hasura V3 Documentation](https://hasura.io/docs/3.0/index/)
- [See the listing in the Hasura Hub](https://hasura.io/connectors/turso)
- [Hasura V3 Documentation](https://hasura.io/docs/3.0/index/)

## Features

Expand All @@ -34,8 +35,6 @@ Below, you'll find a matrix of all supported features for the Turso connector:

## Before you get Started

[Prerequisites or recommended steps before using the connector.]

1. The [DDN CLI](https://hasura.io/docs/3.0/cli/installation) and [Docker](https://docs.docker.com/engine/install/) installed
2. A [supergraph](https://hasura.io/docs/3.0/getting-started/init-supergraph)
3. A [subgraph](https://hasura.io/docs/3.0/getting-started/init-subgraph)
Expand All @@ -52,114 +51,76 @@ connector — after it's been configured — [here](https://hasura.io/docs/3.0/g
ddn auth login
```

### Step 2: Initialize the connector
### Step 2: Configure the connector

Once you have an initialized supergraph and subgraph, run the initialization command in interactive mode while providing a name for the connector in the prompt:

```bash
ddn connector init turso --subgraph my_subgraph --hub-connector hasura/turso
ddn connector init turso -i
```

In the snippet above, we've used the subgraph `my_subgraph` as an example; however, you should change this
value to match any subgraph which you've created in your project.
#### Step 2.1: Choose the `hasura/turso` option from the list

### Step 3: Modify the connector's port
#### Step 2.2: Choose a port for the connector

When you initialized your connector, the CLI generated a set of configuration files, including a Docker Compose file for
the connector. Typically, connectors default to port `8080`. Each time you add a connector, we recommend incrementing the published port by one to avoid port collisions.

As an example, if your connector's configuration is in `my_subgraph/connector/turso/docker-compose.turso.yaml`, you can modify the published port to reflect a value that isn't currently being used by any other connectors:

```yaml
ports:
- mode: ingress
target: 8080
published: "8082"
protocol: tcp
```
The CLI will ask for a specific port to run the connector on. Choose a port that is not already in use or use the default suggested port.

### Step 4: Add environment variables
#### Step 2.3: Provide the env var(s) for the connector

Now that our connector has been scaffolded out for us, we need to provide a connection string so that the data source can be introspected and the boilerplate configuration can be taken care of by the CLI.
| Name | Description |
|-|-|
| TURSO_URL | The connection string for the Turso database, or the file path to the SQLite file |
| TURSO_AUTH_TOKEN | The turso auth token |

The CLI has provided an `.env.local` file for our connector in the `my_subgraph/connector/turso` directory. We can add a key-value pair
of `TURSO_URL` along with the connection string itself to this file, and our connector will use this to connect to our database. If you are connecting to a cloud hosted Turso database you can also provide the environment variable for the `TURSO_AUTH_TOKEN` which allows the connector to authenticate.
You'll find the environment variables in the `.env` file and they will be in the format:

`<SUBGRAPH_NAME>_<CONNECTOR_NAME>_<VARIABLE_NAME>`

The file, after adding the `TURSO_URL`, should look like this example if connecting to a Turso hosted database instance:
Here is an example of what your `.env` file might look like:

```env
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://local.hasura.dev:4317
OTEL_SERVICE_NAME=my_subgraph_turso
TURSO_URL=libsql://chinook-tristenharr.turso.io
TURSO_AUTH_TOKEN=eyJhb...
```

To connect to a local SQLite file, you can add the persistent SQLite database file into the `my_subgraph/connector/turso` directory, and since all files in this directory will get mounted to the container at `/etc/connector/` you can then point the `TURSO_URL` to the local file. Assuming that the Turso file was named `chinook.sqlite` the file should look like this example:

```env
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://local.hasura.dev:4317
OTEL_SERVICE_NAME=my_subgraph_turso
TURSO_URL=file:/etc/connector/chinook.sqlite
APP_TURSO_AUTHORIZATION_HEADER="Bearer QTJ7rl19SvKa0rwOZjYILQ=="
APP_TURSO_HASURA_SERVICE_TOKEN_SECRET="QTJ7rl19SvKa0rwOZjYILQ=="
APP_TURSO_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://local.hasura.dev:4317"
APP_TURSO_OTEL_SERVICE_NAME="app_turso"
APP_TURSO_READ_URL="http://local.hasura.dev:4362"
APP_TURSO_TURSO_AUTH_TOKEN="eyJ..."
APP_TURSO_TURSO_URL="libsql://chinook-tristenharr.turso.io"
APP_TURSO_WRITE_URL="http://local.hasura.dev:4362"
```

### Step 5: Introspect your data source
If you are attaching to a local SQLite file, first make sure that the file is located inside the connector directory. For example, if you had a `data.sqlite` file you could place it at `/app/connector/turso/data.sqlite`. Files in the connector directory get mounted to `/etc/connector/`.

With the connector configured, we can now use the CLI to introspect our database and create a source-specific configuration file for our connector.
In this instance, you would set the `TURSO_URL=/etc/connector/data.sqlite` and leave the `TURSO_AUTH_TOKEN` as blank/null. Now your `.env` might look like this:

```bash
ddn connector introspect --connector my_subgraph/connector/turso/connector.yaml
```

### Step 6. Create the Hasura metadata

Hasura DDN uses a concept called "connector linking" to take [NDC-compliant](https://github.com/hasura/ndc-spec)
configuration JSON files for a data connector and transform them into an `hml` (Hasura Metadata Language) file as a
[`DataConnectorLink` metadata object](https://hasura.io/docs/3.0/supergraph-modeling/data-connectors#dataconnectorlink-dataconnectorlink).

Basically, metadata objects in `hml` files define our API.

First we need to create this `hml` file with the `connector-link add` command and then convert our configuration files
into `hml` syntax and add it to this file with the `connector-link update` command.

Let's name the `hml` file the same as our connector, `turso`:

```bash
ddn connector-link add turso --subgraph my_subgraph
APP_TURSO_AUTHORIZATION_HEADER="Bearer QTJ7rl19SvKa0rwOZjYILQ=="
APP_TURSO_HASURA_SERVICE_TOKEN_SECRET="QTJ7rl19SvKa0rwOZjYILQ=="
APP_TURSO_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://local.hasura.dev:4317"
APP_TURSO_OTEL_SERVICE_NAME="app_turso"
APP_TURSO_READ_URL="http://local.hasura.dev:4362"
APP_TURSO_TURSO_URL="/etc/connector/data.sqlite"
APP_TURSO_WRITE_URL="http://local.hasura.dev:4362"
```

The new file is scaffolded out at `my_subgraph/metadata/turso/turso.hml`.

### Step 7. Update the environment variables
Your experience mounting files may vary, and while useful to explore a file locally, it's not recommended to attempt to deploy a connector using a locally mounted file.

The generated file has two environment variables — one for reads and one for writes — that you'll need to add to your subgraph's `.env.my_subgraph` file. Each key is prefixed by the subgraph name, an underscore, and the name of the connector. Ensure the port value matches what is published in your connector's docker compose file.
### Step 3: Introspect the connector

As an example:

```env
MY_SUBGRAPH_TURSO_READ_URL=http://local.hasura.dev:<port>
MY_SUBGRAPH_TURSO_WRITE_URL=http://local.hasura.dev:<port>
```

These values are for the connector itself and utilize `local.hasura.dev` to ensure proper resolution within the docker container.

### Step 8. Start the connector's Docker Compose

Let's start our connector's Docker Compose file by running the following from inside the connector's subgraph:
Introspecting the connector will generate a `config.json` file and a `turso.hml` file.

```bash
docker compose -f docker-compose.turso.yaml up
ddn connector introspect turso
```

### Step 9. Update the new `DataConnectorLink` object
### Step 4: Add your resources

Finally, now that our `DataConnectorLink` has the correct environment variables configured for the connector, we can run the update command to have the CLI look at the configuration JSON and transform it to reflect our database's schema in `hml` format. In a new terminal tab, run:
You can add the models, commands, and relationships to your API by tracking them which generates the HML files.

```bash
ddn connector-link update turso --subgraph my_subgraph
ddn connector-link add-resources turso
```

After this command runs, you can open your `my_subgraph/metadata/turso.hml` file and see your metadata completely
scaffolded out for you 🎉

## Documentation

View the full documentation for the Turso connector [here](https://github.com/hasura/ndc-turso/blob/main/docs/index.md).
Expand Down
20 changes: 6 additions & 14 deletions registry/hasura/turso/metadata.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
"tags": [
"database"
],
"latest_version": "v0.0.15"
"latest_version": "v0.1.0"
},
"author": {
"support_email": "[email protected]",
Expand All @@ -16,19 +16,6 @@
},
"is_verified": false,
"is_hosted_by_hasura": true,
"packages": [
{
"version": "0.0.15",
"uri": "https://github.com/hasura/ndc-turso/releases/download/v0.0.15/connector-definition.tgz",
"checksum": {
"type": "sha256",
"value": "a2c8426c443bf8c94b0f706d8438bd06eeeef30c0d2b40389c0e37be4be920a6"
},
"source": {
"hash": "6bae967daf7b9aa718d62103e077a739c41d5a6d"
}
}
],
"source_code": {
"is_open_source": true,
"repository": "https://github.com/hasura/ndc-turso",
Expand All @@ -37,6 +24,11 @@
"tag": "v0.0.15",
"hash": "6bae967daf7b9aa718d62103e077a739c41d5a6d",
"is_verified": false
},
{
"tag": "v0.1.0",
"hash": "ef4b124ea384a13f3d051e30ce33623fcc6847c5",
"is_verified": false
}
]
}
Expand Down
12 changes: 12 additions & 0 deletions registry/hasura/turso/releases/v0.0.15/connector-packaging.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
{
"version": "0.0.15",
"uri": "https://github.com/hasura/ndc-turso/releases/download/v0.0.15/connector-definition.tgz",
"checksum": {
"type": "sha256",
"value": "a2c8426c443bf8c94b0f706d8438bd06eeeef30c0d2b40389c0e37be4be920a6"
},
"source": {
"hash": "6bae967daf7b9aa718d62103e077a739c41d5a6d"
}
}

11 changes: 11 additions & 0 deletions registry/hasura/turso/releases/v0.1.0/connector-packaging.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{
"version": "0.1.0",
"uri": "https://github.com/hasura/ndc-turso/releases/download/v0.1.0/connector-definition.tgz",
"checksum": {
"type": "sha256",
"value": "b884688c3e328b181af19a23c01cfb5615267469af3c2517dd46b2d21b0e579d"
},
"source": {
"hash": "ef4b124ea384a13f3d051e30ce33623fcc6847c5"
}
}

0 comments on commit 82d6195

Please sign in to comment.