mirror of https://github.com/dapr/docs.git
Merge branch 'v1.0-rc3' into release-rc3
This commit is contained in:
Aaron Crawfis
GitHub
commit
2e48c0b484
|
|
@ -1,5 +1,6 @@
|
|||
# Visual Studio 2015/2017/2019 cache/options directory
|
||||
.vs/
|
||||
.idea/
|
||||
node_modules/
|
||||
daprdocs/public
|
||||
daprdocs/resources/_gen
|
||||
|
|
|
|||
|
|
@ -19,6 +19,7 @@ Every binding has its own unique set of properties. Click the name link to see t
|
|||
| [Kafka]({{< ref kafka.md >}}) | ✅ | ✅ | Experimental |
|
||||
| [Kubernetes Events]({{< ref "kubernetes-binding.md" >}}) | ✅ | | Experimental |
|
||||
| [MQTT]({{< ref mqtt.md >}}) | ✅ | ✅ | Experimental |
|
||||
| [MySQL]({{< ref mysql.md >}}) | | ✅ | Experimental |
|
||||
| [PostgreSql]({{< ref postgres.md >}}) | | ✅ | Experimental |
|
||||
| [Postmark]({{< ref postmark.md >}}) | | ✅ | Experimental |
|
||||
| [RabbitMQ]({{< ref rabbitmq.md >}}) | ✅ | ✅ | Experimental |
|
||||
|
|
|
|||
|
|
@ -0,0 +1,147 @@
|
|||
---
|
||||
type: docs
|
||||
title: "MySQL binding spec"
|
||||
linkTitle: "MySQL"
|
||||
description: "Detailed documentation on the MySQL binding component"
|
||||
---
|
||||
|
||||
## Setup Dapr component
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: <NAME>
|
||||
namespace: <NAMESPACE>
|
||||
spec:
|
||||
type: bindings.mysql
|
||||
version: v1
|
||||
metadata:
|
||||
- name: url # Required, define DB connection in DSN format
|
||||
value: <CONNECTION_STRING>
|
||||
- name: pemPath # Optional
|
||||
value: <PEM PATH>
|
||||
- name: maxIdleConns
|
||||
value: <MAX_IDLE_CONNECTIONS>
|
||||
- name: maxOpenConns
|
||||
value: <MAX_OPEN_CONNECTIONS>
|
||||
- name: connMaxLifetime
|
||||
value: <CONNECTILN_MAX_LIFE_TIME>
|
||||
- name: connMaxIdleTime
|
||||
value: <CONNECTION_MAX_IDLE_TIME>
|
||||
```
|
||||
|
||||
The MySQL binding uses [Go-MySQL-Driver](https://github.com/go-sql-driver/mysql) internally so the `url` parameter should follow the `DSN` format shown below:
|
||||
|
||||
- `url`: Required, represent DB connection in Data Source Name (DNS) format.
|
||||
|
||||
**Example DSN**
|
||||
|
||||
```yaml
|
||||
- name: url
|
||||
value: user:password@tcp(localhost:3306)/dbname
|
||||
```
|
||||
|
||||
If your server requires SSL your connection string must end of `&tls=custom` for example, `"<user>:<password>@tcp(<server>:3306)/<database>?allowNativePasswords=true&tls=custom"`. You must replace the `<PEM PATH>` with a full path to the PEM file. If you are using [MySQL on Azure](http://bit.ly/AzureMySQLSSL) see the Azure [documentation on SSL database connections](http://bit.ly/MySQLSSL), for information on how to download the required certificate. The connection to MySQL will require a minimum TLS version of 1.2.
|
||||
|
||||
- `pemPath`: path to the PEM file
|
||||
|
||||
also support connection pool configuration variables:
|
||||
|
||||
- `maxIdleConns`: integer greater than 0
|
||||
- `maxOpenConns`: integer greater than 0
|
||||
- `connMaxLifetime`: duration string
|
||||
- `connMaxIdleTime`: duration string
|
||||
|
||||
{{% alert title="Warning" color="warning" %}} The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described [here]({{< ref component-secrets.md >}}). {{% /alert %}}
|
||||
|
||||
## Output Binding Supported Operations
|
||||
|
||||
- `exec`
|
||||
- `query`
|
||||
- `close`
|
||||
|
||||
### exec
|
||||
|
||||
The `exec` operation can be used for DDL operations (like table creation), as well as `INSERT`, `UPDATE`, `DELETE` operations which return only metadata (e.g. number of affected rows).
|
||||
|
||||
**Request**
|
||||
|
||||
```json
|
||||
{
|
||||
"operation": "exec",
|
||||
"metadata": {
|
||||
"sql": "INSERT INTO foo (id, c1, ts) VALUES (1, 'demo', '2020-09-24T11:45:05Z07:00')"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"operation": "exec",
|
||||
"duration": "294µs",
|
||||
"start-time": "2020-09-24T11:13:46.405097Z",
|
||||
"end-time": "2020-09-24T11:13:46.414519Z",
|
||||
"rows-affected": "1",
|
||||
"sql": "INSERT INTO foo (id, c1, ts) VALUES (1, 'demo', '2020-09-24T11:45:05Z07:00')"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### query
|
||||
|
||||
The `query` operation is used for `SELECT` statements, which returns the metadata along with data in a form of an array of row values.
|
||||
|
||||
**Request**
|
||||
|
||||
```json
|
||||
{
|
||||
"operation": "query",
|
||||
"metadata": {
|
||||
"sql": "SELECT * FROM foo WHERE id < 3"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"operation": "query",
|
||||
"duration": "432µs",
|
||||
"start-time": "2020-09-24T11:13:46.405097Z",
|
||||
"end-time": "2020-09-24T11:13:46.420566Z",
|
||||
"sql": "SELECT * FROM foo WHERE id < 3"
|
||||
},
|
||||
"data": "[
|
||||
[0,\"test-0\",\"2020-09-24T04:13:46Z\"],
|
||||
[1,\"test-1\",\"2020-09-24T04:13:46Z\"],
|
||||
[2,\"test-2\",\"2020-09-24T04:13:46Z\"]
|
||||
]"
|
||||
}
|
||||
```
|
||||
|
||||
### close
|
||||
|
||||
Finally, the `close` operation can be used to explicitly close the DB connection and return it to the pool. This operation doesn't have any response.
|
||||
|
||||
**Request**
|
||||
|
||||
```json
|
||||
{
|
||||
"operation": "close"
|
||||
}
|
||||
```
|
||||
|
||||
> Note, the MySQL binding itself doesn't prevent SQL injection, like with any database application, validate the input before executing query.
|
||||
|
||||
## Related links
|
||||
|
||||
- [Bindings building block]({{< ref bindings >}})
|
||||
- [How-To: Trigger application with input binding]({{< ref howto-triggers.md >}})
|
||||
- [How-To: Use bindings to interface with external resources]({{< ref howto-bindings.md >}})
|
||||
- [Bindings API reference]({{< ref bindings_api.md >}})
|
||||
|
|
@ -20,6 +20,7 @@ The following stores are supported, at various levels, by the Dapr state managem
|
|||
| [Hazelcast]({{< ref setup-hazelcast.md >}}) | ✅ | ❌ |
|
||||
| [Memcached]({{< ref setup-memcached.md >}}) | ✅ | ❌ |
|
||||
| [MongoDB]({{< ref setup-mongodb.md >}}) | ✅ | ✅ |
|
||||
| [MySQL]({{< ref setup-mysql.md >}}) | ✅ | ✅ |
|
||||
| [PostgreSQL]({{< ref setup-postgresql.md >}}) | ✅ | ✅ |
|
||||
| [Redis]({{< ref setup-redis.md >}}) | ✅ | ✅ |
|
||||
| [Zookeeper]({{< ref setup-zookeeper.md >}}) | ✅ | ❌ |
|
||||
|
|
@ -28,4 +29,3 @@ The following stores are supported, at various levels, by the Dapr state managem
|
|||
| [Azure Table Storage]({{< ref setup-azure-tablestorage.md >}}) | ✅ | ❌ |
|
||||
| [Azure Blob Storage]({{< ref setup-azure-blobstorage.md >}}) | ✅ | ❌ |
|
||||
| [Google Cloud Firestore]({{< ref setup-firestore.md >}}) | ✅ | ❌ |
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,145 @@
|
|||
---
|
||||
type: docs
|
||||
title: "MySQL"
|
||||
linkTitle: "MySQL"
|
||||
description: Detailed information on the MySQL state store component
|
||||
---
|
||||
|
||||
## Create a MySQL Store
|
||||
|
||||
Dapr can use any MySQL instance - containerized, running on your local dev machine, or a managed cloud service. If you already have a MySQL store, move on to the [Create a Dapr component](#create-a-dapr-component) section.
|
||||
|
||||
{{< tabs "Self-Hosted" "Kubernetes" "Azure" "AWS" "GCP" >}}
|
||||
|
||||
{{% codetab %}}
|
||||
<!-- Self-Hosted -->
|
||||
|
||||
Run an instance of MySQL. You can run a local instance of MySQL in Docker CE with the following command:
|
||||
|
||||
This example does not describe a production configuration because it sets the password in plain text and the user name is left as the MySQL default of "root".
|
||||
|
||||
```bash
|
||||
docker run --name dapr_mysql -p 3306:3306 -e MYSQL_ROOT_PASSWORD=my-secret-pw -d mysql:latest
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
<!-- Kubernetes -->
|
||||
|
||||
We can use [Helm](https://helm.sh/) to quickly create a MySQL instance in our Kubernetes cluster. This approach requires [Installing Helm](https://github.com/helm/helm#install).
|
||||
|
||||
1. Install MySQL into your cluster.
|
||||
|
||||
```bash
|
||||
helm repo add bitnami https://charts.bitnami.com/bitnami
|
||||
helm install dapr_mysql bitnami/mysql
|
||||
```
|
||||
|
||||
1. Run `kubectl get pods` to see the MySQL containers now running in your cluster.
|
||||
|
||||
1. Next, we'll get our password, which is slightly different depending on the OS we're using:
|
||||
- **Windows**: Run `[System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($(kubectl get secret --namespace default dapr-mysql -o jsonpath="{.data.mysql-root-password}")))` and copy the outputted password.
|
||||
|
||||
- **Linux/MacOS**: Run `kubectl get secret --namespace default dapr-mysql -o jsonpath="{.data.mysql-root-password}" | base64 --decode` and copy the outputted password.
|
||||
|
||||
1. With the password you can construct your connection string.
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
<!-- Azure -->
|
||||
|
||||
[Azure MySQL](http://bit.ly/AzureMySQL)
|
||||
|
||||
If you are using [MySQL on Azure](http://bit.ly/AzureMySQLSSL) see the Azure [documentation on SSL database connections](http://bit.ly/MySQLSSL), for information on how to download the required certificate.
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
<!-- AWS -->
|
||||
|
||||
[AWS MySQL](https://aws.amazon.com/rds/mysql/)
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
<!-- GCP -->
|
||||
|
||||
[GCP MySQL](https://cloud.google.com/sql/docs/mysql/features)
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
## Create a Dapr component
|
||||
|
||||
### Non SSL connection
|
||||
|
||||
Create a file called `mysqlstate.yaml`, paste the following and replace the `<CONNECTION STRING>` value with your connection string. The connection string is a standard MySQL connection string. For example, `"<user>:<password>@tcp(<server>:3306)/?allowNativePasswords=true"`. Do not add the schema to the connection string. The component connects to the server first to check for the existence of the desired schema. If the schemaName is not provided the default value of **dapr_state_store** will be used. If the schema does not exist it will be created.
|
||||
|
||||
The tableName is also optional and if not provided will default to **state**. If the table does ont exist it will be created.
|
||||
|
||||
If you want to also configure MySQL to store actors, add the `actorStateStore` configuration element shown below.
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: statestore
|
||||
spec:
|
||||
type: state.mysql
|
||||
version: v1
|
||||
metadata:
|
||||
- name: connectionString
|
||||
value: "<CONNECTION STRING>"
|
||||
- name: schemaName
|
||||
value: "<SCHEMA NAME>"
|
||||
- name: tableName
|
||||
value: "<TABLE NAME>"
|
||||
- name: actorStateStore
|
||||
value: "true"
|
||||
```
|
||||
|
||||
### Enforced SSL connection
|
||||
|
||||
If your server requires SSL your connection string must end with `&tls=custom` for example, `"<user>:<password>@tcp(<server>:3306)/?allowNativePasswords=true&tls=custom"`. You must replace the `<PEM PATH>` with a full path to the PEM file. The connection to MySQL will require a minimum TLS version of 1.2.
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: statestore
|
||||
spec:
|
||||
type: state.mysql
|
||||
version: v1
|
||||
metadata:
|
||||
- name: connectionString
|
||||
value: "<CONNECTION STRING>"
|
||||
- name: schemaName
|
||||
value: "<SCHEMA NAME>"
|
||||
- name: tableName
|
||||
value: "<TABLE NAME>"
|
||||
- name: pemPath
|
||||
value: "<PEM PATH>"
|
||||
- name: actorStateStore
|
||||
value: "true"
|
||||
```
|
||||
|
||||
{{% alert title="Warning" color="warning" %}}
|
||||
The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described [here]({{< ref component-secrets.md >}}).
|
||||
{{% /alert %}}
|
||||
|
||||
## Apply the configuration
|
||||
|
||||
### In Kubernetes
|
||||
|
||||
To apply the MySQL state store to Kubernetes, use the `kubectl` CLI:
|
||||
|
||||
```yaml
|
||||
kubectl apply -f mysqlstate.yaml
|
||||
```
|
||||
|
||||
### Running locally
|
||||
|
||||
To run locally, create a `components` dir containing the YAML file and provide the path to the `dapr run` command with the flag `--components-path`.
|
||||
Loading…
Reference in New Issue