MySQL & MariaDB binding spec

Detailed documentation on the MySQL binding component

Component format

The MySQL binding allows connecting to both MySQL and MariaDB databases. In this document, we refer to “MySQL” to indicate both databases.

To setup a MySQL binding create a component of type bindings.mysql. See this guide on how to create and apply a binding configuration.

The MySQL binding uses Go-MySQL-Driver internally.

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4. name: <NAME>
  5. spec:
  6. type: bindings.mysql
  7. version: v1
  8. metadata:
  9. - name: url # Required, define DB connection in DSN format
  10. value: <CONNECTION_STRING>
  11. - name: pemPath # Optional
  12. value: <PEM PATH>
  13. - name: maxIdleConns
  14. value: <MAX_IDLE_CONNECTIONS>
  15. - name: maxOpenConns
  16. value: <MAX_OPEN_CONNECTIONS>
  17. - name: connMaxLifetime
  18. value: <CONNECTILN_MAX_LIFE_TIME>
  19. - name: connMaxIdleTime
  20. value: <CONNECTION_MAX_IDLE_TIME>

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here. Note that you can not use secret just for username/password. If you use secret, it has to be for the complete connection string.

Spec metadata fields

FieldRequiredBinding supportDetailsExample
urlYOutputRepresent DB connection in Data Source Name (DNS) format. See here SSL details“user:password@tcp(localhost:3306)/dbname”
pemPathYOutputPath to the PEM file. Used with SSL connection“path/to/pem/file”
maxIdleConnsNOutputThe max idle connections. Integer greater than 0“10”
maxOpenConnsNOutputThe max open connections. Integer greater than 0“10”
connMaxLifetimeNOutputThe max connection lifetime. Duration string“12s”
connMaxIdleTimeNOutputThe max connection idel time. Duration string“12s”

SSL connection

If your server requires SSL your connection string must end of &tls=custom for example:

  1. "<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 see the Azure documentation on SSL database connections, for information on how to download the required certificate. The connection to MySQL will require a minimum TLS version of 1.2.

Also note that by default MySQL go driver only supports one SQL statement per query/command. To allow multiple statements in one query you need to add multiStatements=true to a query string, for example:

  1. "<user>:<password>@tcp(<server>:3306)/<database>?multiStatements=true"

While this allows batch queries, it also greatly increases the risk of SQL injections. Only the result of the first query is returned, all other results are silently discarded.

Binding support

This component supports output binding with the following 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

  1. {
  2. "operation": "exec",
  3. "metadata": {
  4. "sql": "INSERT INTO foo (id, c1, ts) VALUES (1, 'demo', '2020-09-24T11:45:05Z07:00')"
  5. }
  6. }

Response

  1. {
  2. "metadata": {
  3. "operation": "exec",
  4. "duration": "294µs",
  5. "start-time": "2020-09-24T11:13:46.405097Z",
  6. "end-time": "2020-09-24T11:13:46.414519Z",
  7. "rows-affected": "1",
  8. "sql": "INSERT INTO foo (id, c1, ts) VALUES (1, 'demo', '2020-09-24T11:45:05Z07:00')"
  9. }
  10. }

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

  1. {
  2. "operation": "query",
  3. "metadata": {
  4. "sql": "SELECT * FROM foo WHERE id < 3"
  5. }
  6. }

Response

  1. {
  2. "metadata": {
  3. "operation": "query",
  4. "duration": "432µs",
  5. "start-time": "2020-09-24T11:13:46.405097Z",
  6. "end-time": "2020-09-24T11:13:46.420566Z",
  7. "sql": "SELECT * FROM foo WHERE id < 3"
  8. },
  9. "data": [
  10. {column_name: value, column_name: value, ...},
  11. {column_name: value, column_name: value, ...},
  12. {column_name: value, column_name: value, ...},
  13. ]
  14. }

Here column_name is the name of the column returned by query, and value is a value of this column. Note that values are returned as string or numbers (language specific data type)

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

  1. {
  2. "operation": "close"
  3. }

Note, the MySQL binding itself doesn’t prevent SQL injection, like with any database application, validate the input before executing query.

Last modified June 19, 2023: Merge pull request #3565 from dapr/aacrawfi/skip-secrets-close (b1763bf)