add example, update readme and docs for data api usage

Author: mmichaelb

README.md

@@ -1,27 +1,41 @@
 # Terraform Provider for AWS Redshift
 
-This provider allows to manage with Terraform [AWS Redshift](https://aws.amazon.com/redshift/) objects like users, groups, schemas, etc..
+This provider allows to manage with Terraform [AWS Redshift](https://aws.amazon.com/redshift/) objects like users, groups, schemas, etc...
 
 It's published on the [Terraform registry](https://registry.terraform.io/providers/dbsystel/redshift/latest/docs).
 
 ## Requirements
 
-  - [Terraform](https://www.terraform.io/downloads.html) >= 1.0
-  - [Go](https://golang.org/doc/install) 1.24 (to build the provider plugin)
+- [Terraform](https://www.terraform.io/downloads.html) >= 1.0
+- [Go](https://golang.org/doc/install) 1.24 (to build the provider plugin)
 
 ## Limitations
 
+### Untested features
+
 Due to limited testing capacities, the following features are not tested/stable yet:
 
 * External Schemas
-  * Hive Database
-  * RDS Postgres Database
-  * RDS MySQL Database
-  * Redshift Database
+    * Hive Database
+    * RDS Postgres Database
+    * RDS MySQL Database
+    * Redshift Database
 * Temporary Credentials Cluster Identifier
 * Temporary Credentials Assume Role
 * Datashares
 
+### Using the AWS Redshift Data API
+
+This provider *does* support connecting to the Redshift instance using the AWS Redshift Data API. However, this is not
+the default behavior, requires some additional configuration and comes along with some caveats:
+
+* Transactions are not run as real DB-level transactions, but rather as a sequence of individual statements.
+* Due to the unsupported state of transactions, interfering DB interactions might lead to unexpected results.
+* In order to
+  prevent [errors due to conflicts with concurrent transactions](https://stackoverflow.com/questions/37344942/redshift-could-not-complete-because-of-conflict-with-concurrent-transaction),
+  all statements depend on one lock across resources. This may lead to longer execution times, especially when multiple
+  resources are created or updated at the same time.
+
 ## Building The Provider
 
 ```sh
@@ -34,14 +48,15 @@ Enter the provider directory and build the provider
 $ cd terraform-provider-redshift
 $ make build
 ```
+
 ## Development
 
 If you're new to provider development, a good place to start is the [Extending
 Terraform](https://www.terraform.io/docs/extend/index.html) docs.
 
 ### Running Tests
 
-Acceptance tests require a running real AWS Redshift cluster. 
+Acceptance tests require a running real AWS Redshift cluster.
 
 ```sh
 REDSHIFT_HOST=<cluster ip or DNS>
@@ -52,6 +67,7 @@ make testacc
 ```
 
 If your cluster is only accessible from within the VPC, you can connect via a socks proxy:
+
 ```sh
 ALL_PROXY=socks5[h]://[<socks-user>:<socks-password>@]<socks-host>[:<socks-port>]
 NO_PROXY=127.0.0.1,192.168.0.0/24,*.example.com,localhost
@@ -71,8 +87,9 @@ Use `go generate` to update generated docs.
 
 ## Releasing
 
-Builds and releases are automated with GitHub Actions and [GoReleaser](https://github.com/goreleaser/goreleaser/). 
-The changelog is managed with [github-changelog-generator](https://github.com/github-changelog-generator/github-changelog-generator).
+Builds and releases are automated with GitHub Actions and [GoReleaser](https://github.com/goreleaser/goreleaser/).
+The changelog is managed
+with [github-changelog-generator](https://github.com/github-changelog-generator/github-changelog-generator).
 
 Currently there are a few manual steps to this:
 

docs/index.md

@@ -54,6 +54,7 @@ provider "redshift" {
 
 ### Optional
 
+- `data_api` (Block List, Max: 1) Configuration for using the Redshift Data API. This can only be used for serverless Redshift clusters. (see [below for nested schema](#nestedblock--data_api))
 - `database` (String) The name of the database to connect to. The default is `redshift`.
 - `host` (String) Name of Redshift server address to connect to.
 - `max_connections` (Number) Maximum number of connections to establish to the database. Zero means unlimited.
@@ -63,6 +64,15 @@ provider "redshift" {
 - `temporary_credentials` (Block List, Max: 1) Configuration for obtaining a temporary password using redshift:GetClusterCredentials (see [below for nested schema](#nestedblock--temporary_credentials))
 - `username` (String) Redshift user name to connect as.
 
+<a id="nestedblock--data_api"></a>
+### Nested Schema for `data_api`
+
+Required:
+
+- `region` (String) The AWS region where the Redshift Serverless workgroup is located. If not specified, the region will be determined from the AWS SDK configuration.
+- `workgroup_name` (String) The name of the Redshift Serverless workgroup to connect to.
+
+
 <a id="nestedblock--temporary_credentials"></a>
 ### Nested Schema for `temporary_credentials`
 

examples/provider/provider_data_api.tf

@@ -0,0 +1,7 @@
+provider "redshift" {
+  database = "exampledb"
+  data_api {
+    workgroup_name = "example-workgroup"
+    region         = "us-west-2"
+  }
+}