streams

Creates, updates, deletes, gets or lists a streams resource.

Overview

Name	streams
Type	Resource
Id	aws.dsql.streams

Fields

The following fields are returned by SELECT queries:

get_stream

Name	Datatype	Description
arn	string	The ARN of the retrieved stream. (pattern: <code>arn:aws(-[^:]+)?:dsql:[a-z0-9-]{1,20}:[0-9]{12}:cluster/[a-z0-9]{26}/stream/[a-z0-9]{26}</code>)
cluster_identifier	string	The ID of the cluster. (pattern: <code>[a-z0-9]{26}</code>)
creation_time	string (date-time)	The time when the stream was created.
format_	string	Stream record format. JSON Stream records are formatted as JSON. (JSON)
ordering	string	Stream ordering mode. UNORDERED Changes are streamed without ordering guarantees. (UNORDERED)
status	string	The current status of the retrieved stream. (CREATING, ACTIVE, DELETING, DELETED, FAILED, IMPAIRED)
status_reason	object	Stream status reason with error code and timestamp (if applicable).
stream_identifier	string	The ID of the stream. (pattern: <code>[a-z0-9]{26}</code>)
tags	object	A map of tags associated with the stream.
target_definition	object	Target definition for stream destination.

list_streams

Name	Datatype	Description
arn	string	The ARN of the stream. (pattern: <code>arn:aws(-[^:]+)?:dsql:[a-z0-9-]{1,20}:[0-9]{12}:cluster/[a-z0-9]{26}/stream/[a-z0-9]{26}</code>)
cluster_identifier	string	The ID of the cluster. (pattern: <code>[a-z0-9]{26}</code>)
creation_time	string (date-time)	The timestamp when the stream was created.
status	string	The current status of the stream. (CREATING, ACTIVE, DELETING, DELETED, FAILED, IMPAIRED)
stream_identifier	string	The ID of the stream. (pattern: <code>[a-z0-9]{26}</code>)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_stream	select	cluster_identifier, stream_identifier, region		Retrieves information about a stream.
list_streams	select	cluster_identifier, region	max-results, next-token	Retrieves information about a list of streams for a cluster.
create_stream	insert	cluster_identifier, region, targetDefinition, ordering, format		Creates a new change data capture (CDC) stream for a cluster. The stream captures database changes and delivers them to the specified target destination. Required permissions dsql:CreateStream Permission to create a new stream. Resources: arn:aws:dsql:region:account-id:cluster/cluster-id iam:PassRole Permission to pass the IAM role specified in the target definition to the service. Resources: ARN of the IAM role specified in targetDefinition.kinesis.roleArn kms:Decrypt Required when the cluster uses a customer managed KMS key (CMK). Permission to decrypt data using the cluster's CMK. Resources: ARN of the KMS key used by the cluster
delete_stream	delete	cluster_identifier, stream_identifier, region	client-token	Deletes a stream from a cluster.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
cluster_identifier	string	The ID of the cluster containing the stream to delete.
region	string	AWS region (default: us-east-1)
stream_identifier	string	The ID of the stream to delete.
client-token	string	A unique, case-sensitive identifier that you provide to ensure the idempotency of the request. Idempotency ensures that an API request completes only once. With an idempotent request, if the original request completes successfully, the subsequent retries with the same client token return the result from the original successful request and they have no additional effect. If you don't specify a client token, the Amazon Web Services SDK automatically generates one.
max-results	integer	An optional parameter that specifies the maximum number of results to return. You can use nextToken to display the next page of results. Default: 10.
next-token	string	If your initial ListStreams operation returns a nextToken, you can include the returned nextToken in following ListStreams operations, which returns results in the next page.

SELECT examples

get_stream

Retrieves information about a stream.

SELECT
arn,
cluster_identifier,
creation_time,
format_,
ordering,
status,
status_reason,
stream_identifier,
tags,
target_definition
FROM aws.dsql.streams
WHERE cluster_identifier = '{{ cluster_identifier }}' -- required
AND stream_identifier = '{{ stream_identifier }}' -- required
AND region = '{{ region }}' -- required
;

list_streams

Retrieves information about a list of streams for a cluster.

SELECT
arn,
cluster_identifier,
creation_time,
status,
stream_identifier
FROM aws.dsql.streams
WHERE cluster_identifier = '{{ cluster_identifier }}' -- required
AND region = '{{ region }}' -- required
AND `max-results` = '{{ max-results }}'
AND `next-token` = '{{ next-token }}'
;

INSERT examples

create_stream

Creates a new change data capture (CDC) stream for a cluster. The stream captures database changes and delivers them to the specified target destination. Required permissions dsql:CreateStream Permission to create a new stream. Resources: arn:aws:dsql:region:account-id:cluster/cluster-id iam:PassRole Permission to pass the IAM role specified in the target definition to the service. Resources: ARN of the IAM role specified in targetDefinition.kinesis.roleArn kms:Decrypt Required when the cluster uses a customer managed KMS key (CMK). Permission to decrypt data using the cluster's CMK. Resources: ARN of the KMS key used by the cluster

INSERT INTO aws.dsql.streams (
targetDefinition,
ordering,
format,
tags,
clientToken,
cluster_identifier,
region
)
SELECT 
'{{ targetDefinition }}' /* required */,
'{{ ordering }}' /* required */,
'{{ format }}' /* required */,
'{{ tags }}',
'{{ clientToken }}',
'{{ cluster_identifier }}',
'{{ region }}'
RETURNING
arn,
cluster_identifier,
creation_time,
format_,
ordering,
status,
stream_identifier
;

Manifest

# Description fields are for documentation purposes
- name: streams
props:
  - name: cluster_identifier
    value: "{{ cluster_identifier }}"
    description: Required parameter for the streams resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the streams resource.
  - name: targetDefinition
    description: |
      Target definition for stream destination.
    value:
      kinesis:
        streamArn: "{{ streamArn }}"
        roleArn: "{{ roleArn }}"
  - name: ordering
    value: "{{ ordering }}"
    description: |
      Stream ordering mode. UNORDERED Changes are streamed without ordering guarantees.
    valid_values: ['UNORDERED']
  - name: format
    value: "{{ format }}"
    description: |
      Stream record format. JSON Stream records are formatted as JSON.
    valid_values: ['JSON']
  - name: tags
    value: "{{ tags }}"
    description: |
      Map of tags.
  - name: clientToken
    value: "{{ clientToken }}"
    description: |
      Idempotency token so a request is only processed once.

DELETE examples

delete_stream

Deletes a stream from a cluster.

DELETE FROM aws.dsql.streams
WHERE cluster_identifier = '{{ cluster_identifier }}' --required
AND stream_identifier = '{{ stream_identifier }}' --required
AND region = '{{ region }}' --required
AND `client-token` = '{{ client-token }}'
;