Project: SPIRE (Provisioning / Key Management)
File: plugin_server_datastore_sql.md

The `sql` plugin implements SQL based data storage for the SPIRE server using SQLite, PostgreSQL or MySQL databases. | Configuration | Description | |-|| | database_type | database type | | connection_string | connection string | | roconnectionstring | | | rootcapath | Path to Root CA bundle (MySQL only) | | clientcertpath | Path to client certificate (MySQL only) | | clientkeypath | Path to private key for client certificate (MySQL only) | | maxopenconns | The maximum number of open db connections (default: 100) | | maxidleconns | The maximum number of idle connections in the pool (default: 2) | | connmaxlifetime | The maximum amount of time a connection may be reused (default: unlimited) | | disable_migration | True to disable auto-migration functionality. Use of this flag allows finer control over when datastore migrations occur and coordination of the migration of a datastore shared with a SPIRE Server cluster. Only available for databases from SPIRE Code version 0.9.0 or later. | For more information on the `maxopenconns`, `maxidleconns`, and `connmaxlifetime`, refer to the documentation for the Go package. Save database in file: ```hcl connectionstring="DATABASEFILE.db" ``` Save database in memory: ```hcl connection_string="file:memdb?mode=memory&cache=shared" ``` If you are compiling SPIRE from source, please see for additional information. ```hcl DataStore "sql" { plugin_data { database_type = "sqlite3" connection_string = "./.data/datastore.sqlite3" } } ``` The `connection_string` for the PostgreSQL database connection consists of the number of configuration options separated by spaces. For example: ```hcl connection_string="dbname=postgres user=postgres password=password host=localhost sslmode=disable" ``` Consult the for more `connection_string` options. dbname - The name of the database to connect to user - The user to sign in as password - The user's password host - The host to connect to. Values that start with / are for unix domain sockets. (default is localhost) port - The port to bind to. (default is 5432) sslmode - Whether or not to use SSL (default is require, this is not the default for libpq) fallbackapplicationname - An application_name to fall back to if one isn't provided. connect_timeout - Maximum wait for connection, in seconds. Zero or not specified means wait indefinitely. sslcert - Cert file location. The file must contain PEM encoded data. sslkey - Key file location. The file must contain PEM encoded data. sslrootcert - The location of the root certificate file. The file must contain PEM encoded data. disable - No SSL require - Always SSL (skip verification) verify-ca - Always SSL (verify that the certificate presented by the server was signed by a trusted CA) verify-full - Always SSL (verify that the certification presented by the server was signed by a trusted CA and the server host name matches the one in the certificate) ```hcl DataStore "sql" { plugin_data { database_type = "postgres" connectionstring = "dbname=spiredevelopment user=spire host=127.0.0.1 sslmode=disable" } } ``` The `connection_string` for the MySQL database connection consists of the number of configuration options (optional parts marked by square brackets): ```text username]/dbname[?param1=value1&...&paramN=valueN] ``` For example: ```hcl connection_string="username:password@tcp(localhost:3306)/dbname?parseTime=true" ``` Consult the for more `connection_string`

dbname - The name of the database to connect to username - The user to sign in as password - The user's password address - The host to connect to. Values that start with / are for unix domain sockets. (default is localhost) If you need to use custom Root CA, just specify `rootcapath` in the plugin config. Similarly, if you need to use client certificates, specify `clientkeypath` and `clientcertpath`. Other options can be configured via params in the `connection_string` options. ```hcl DataStore "sql" { plugin_data { database_type = "mysql" connectionstring = "spire:@tcp(127.0.0.1)/spiredevelopment?parseTime=true" } } ``` Identity and Access Management (IAM) authentication allows for secure authentication to databases hosted on cloud services. Unlike traditional methods, it uses an authentication token instead of a password. When using IAM authentication, it is required to exclude the password from the connection string. The `database_type` configuration allows specifying the type of database with IAM authentication support. The configuration always follows this structure: ```hcl database_type "dbtype-with-iam-support" { setting_1 = "value-1" setting_2 = "value-2" ... } ``` Note: Replace `dbtype-with-iam-support` with the specific database type that supports IAM authentication. Supported IAM authentication database types include: For PostgreSQL databases on AWS RDS using IAM authentication. The `region` setting is mandatory, specifying the AWS service region. This is the complete list of configuration options under the `databasetype` setting when `awspostgres` is set: | Configuration | Description | Required | Default | |-|||--| | accesskeyid | AWS access key id. | Required only if AWSACCESSKEYID environment variable is not set. | Value of AWSACCESSKEYID environment variable. | | secretaccesskey | AWS secret access key. | Required only if AWSSECRETACCESSKEY environment variable is not set. | Value of AWSSECRETACCESSKEY environment variable. | | region | AWS region of the database. | Yes. | | Settings of the database type also apply here. ```hcl DataStore "sql" { plugin_data { databasetype "awspostgres" { region = "us-east-2" } connectionstring = "dbname=spire user=testuser host=spire-test.example.us-east-2.rds.amazonaws.com port=5432 sslmode=require" } } ``` For MySQL databases on AWS RDS using IAM authentication. The `region` setting is required. This is the complete list of configuration options under the `databasetype` setting when `awsmysql` is set: | Configuration | Description | Required | Default | |-|||--| | accesskeyid | AWS access key id. | Required only if AWSACCESSKEYID environment variable is not set. | Value of AWSACCESSKEYID environment variable. | | secretaccesskey | AWS secret access key. | Required only if AWSSECRETACCESSKEY environment variable is not set. | Value of AWSSECRETACCESSKEY environment variable. | | region | AWS region of the database. | Yes. | | Settings of the database type also apply here. ```hcl DataStore "sql" { plugin_data { databasetype "awsmysql" { region = "us-east-2" } connectionstring="testuser:@tcp(spire-test.example.us-east-2.rds.amazonaws.com:3306)/spire?parseTime=true&allowCleartextPasswords=1&tls=true" } } ``` Read Only connection will be used when the optional `roconnectionstring` is set. The formatted string takes the same form as connection_string. This option is not applicable for SQLite3. SQLite support requires the use of CGO. This is not a concern for users downloading SPIRE or using the official SPIRE container images. However, if you are building SPIRE from the source code, please note that compiling SPIRE without CGO (e.g. `CGO_ENABLED=0`) will disable SQLite support.