@aws-amplify/graphql-api-construct 1.4.1 → 1.4.3

package/src/model-datasource-strategy.ts

@@ -0,0 +1,149 @@
+// #########################################################################################################################################
+// These are the public-facing types used by customers to define their L3 CDK construct. Many of these have corresponding definitions in the
+// transformer-interfaces package to define internal behavior.
+//
+// If you change types in this file (the customer-facing interface), be sure to make corresponding changes to
+// amplify-graphql-transformer-interfaces/src/model-datasource (the internal implementation)
+// #########################################################################################################################################
+
+/**
+ * All known ModelDataSourceStrategies. Concrete strategies vary widely in their requirements and implementations.
+ * @experimental
+ */
+export type ModelDataSourceStrategy =
+  | DefaultDynamoDbModelDataSourceStrategy
+  | AmplifyDynamoDbModelDataSourceStrategy
+  | SQLLambdaModelDataSourceStrategy;
+
+// TODO: Make this the source of truth for database type definitions used throughout the construct & transformer
+export type ModelDataSourceStrategyDbType = 'DYNAMODB';
+
+/**
+ * Use default CloudFormation type 'AWS::DynamoDB::Table' to provision table.
+ * @experimental
+ */
+export interface DefaultDynamoDbModelDataSourceStrategy {
+  readonly dbType: 'DYNAMODB';
+  readonly provisionStrategy: 'DEFAULT';
+}
+
+/**
+ * Use custom resource type 'Custom::AmplifyDynamoDBTable' to provision table.
+ * @experimental
+ */
+export interface AmplifyDynamoDbModelDataSourceStrategy {
+  readonly dbType: 'DYNAMODB';
+  readonly provisionStrategy: 'AMPLIFY_TABLE';
+}
+
+/**
+ * A strategy that creates a Lambda to connect to a pre-existing SQL table to resolve model data.
+ *
+ * @experimental
+ */
+export interface SQLLambdaModelDataSourceStrategy {
+  /**
+   * The name of the strategy. This will be used to name the AppSync DataSource itself, plus any associated resources like resolver Lambdas.
+   * This name must be unique across all schema definitions in a GraphQL API.
+   */
+  readonly name: string;
+
+  /**
+   * The type of the SQL database used to process model operations for this definition.
+   */
+  readonly dbType: 'MYSQL' | 'POSTGRES';
+
+  /**
+   * The parameters the Lambda data source will use to connect to the database.
+   */
+  readonly dbConnectionConfig: SqlModelDataSourceDbConnectionConfig;
+
+  /**
+   * The configuration of the VPC into which to install the Lambda.
+   */
+  readonly vpcConfiguration?: VpcConfig;
+
+  /**
+   * Custom SQL statements. The key is the value of the `references` attribute of the `@sql` directive in the `schema`; the value is the SQL
+   * to be executed.
+   */
+  readonly customSqlStatements?: Record<string, string>;
+
+  /**
+   * The configuration for the provisioned concurrency of the Lambda.
+   */
+  readonly sqlLambdaProvisionedConcurrencyConfig?: ProvisionedConcurrencyConfig;
+}
+
+/**
+ * Configuration of the VPC in which to install a Lambda to resolve queries against a SQL-based data source. The SQL Lambda will be deployed
+ * into the specified VPC, subnets, and security groups. The specified subnets and security groups must be in the same VPC. The VPC must
+ * have at least one subnet. The construct will also create VPC service endpoints in the specified subnets, as well as inbound security
+ * rules, to allow traffic on port 443 within each security group. This allows the Lambda to read database connection information from
+ * Secure Systems Manager.
+ * @experimental
+ */
+export interface VpcConfig {
+  /** The VPC to install the Lambda data source in. */
+  readonly vpcId: string;
+
+  /** The security groups to install the Lambda data source in. */
+  readonly securityGroupIds: string[];
+
+  /** The subnets to install the Lambda data source in, one per availability zone. */
+  readonly subnetAvailabilityZoneConfig: SubnetAvailabilityZone[];
+}
+
+/**
+ * The configuration for the provisioned concurrency of the Lambda.
+ * @experimental
+ */
+export interface ProvisionedConcurrencyConfig {
+  /** The amount of provisioned concurrency to allocate. **/
+  readonly provisionedConcurrentExecutions: number;
+}
+
+/**
+ * Subnet configuration for VPC endpoints used by a Lambda resolver for a SQL-based data source. Although it is possible to create multiple
+ * subnets in a single availability zone, VPC service endpoints may only be deployed to a single subnet in a given availability zone. This
+ * structure ensures that the Lambda function and VPC service endpoints are mutually consistent.
+ * @experimental
+ */
+export interface SubnetAvailabilityZone {
+  /** The subnet ID to install the Lambda data source in. */
+  readonly subnetId: string;
+
+  /** The availability zone of the subnet. */
+  readonly availabilityZone: string;
+}
+
+/**
+ * The Secure Systems Manager parameter paths the Lambda data source will use to connect to the database.
+ *
+ * These parameters are retrieved from Secure Systems Manager in the same region as the Lambda.
+ * @experimental
+ */
+export interface SqlModelDataSourceDbConnectionConfig {
+  /** The Secure Systems Manager parameter containing the hostname of the database. For RDS-based SQL data sources, this can be the hostname
+   * of a database proxy, cluster, or instance.
+   */
+  readonly hostnameSsmPath: string;
+
+  /** The Secure Systems Manager parameter containing the port number of the database proxy, cluster, or instance. */
+  readonly portSsmPath: string;
+
+  /** The Secure Systems Manager parameter containing the username to use when connecting to the database. */
+  readonly usernameSsmPath: string;
+
+  /** The Secure Systems Manager parameter containing the password to use when connecting to the database. */
+  readonly passwordSsmPath: string;
+
+  /** The Secure Systems Manager parameter containing the database name. */
+  readonly databaseNameSsmPath: string;
+}
+
+export interface CustomSqlDataSourceStrategy {
+  readonly typeName: 'Query' | 'Mutation';
+  readonly fieldName: string;
+  readonly strategy: SQLLambdaModelDataSourceStrategy;
+}

package/src/sql-model-datasource-strategy.ts

@@ -1,6 +1,6 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { SQLLambdaModelDataSourceStrategy, SqlModelDataSourceDbConnectionConfig } from './types';
+import { SQLLambdaModelDataSourceStrategy, SqlModelDataSourceDbConnectionConfig } from './model-datasource-strategy';
 
 /**
  * Type predicate that returns true if the object is a SQLLambdaModelDataSourceStrategy.

package/src/types.ts

@@ -18,6 +18,7 @@ import { IUserPool } from 'aws-cdk-lib/aws-cognito';
 import { IFunction, CfnFunction } from 'aws-cdk-lib/aws-lambda';
 import { IBucket } from 'aws-cdk-lib/aws-s3';
 import { AmplifyDynamoDbTableWrapper } from './amplify-dynamodb-table-wrapper';
+import { CustomSqlDataSourceStrategy, ModelDataSourceStrategy } from './model-datasource-strategy';
 
 /**
  * Configuration for IAM Authorization on the Graphql Api.
@@ -425,8 +426,9 @@ export interface TranslationBehavior {
 
   /**
    * This behavior will only come into effect when both "allowDestructiveGraphqlSchemaUpdates" and this value are set to true
-   * When enabled, any GSI update operation will replace the table instead of iterative deployment, which will WIPE ALL EXISTING DATA but cost much less time for deployment
-   * This will only affect DynamoDB tables with provision strategy "AMPLIFY_TABLE".
+   *
+   * When enabled, any GSI update operation will replace the table instead of iterative deployment, which will WIPE ALL EXISTING DATA but
+   * cost much less time for deployment This will only affect DynamoDB tables with provision strategy "AMPLIFY_TABLE".
    * @default false
    * @experimental
    */
@@ -526,8 +528,9 @@ export interface PartialTranslationBehavior {
 
   /**
    * This behavior will only come into effect when both "allowDestructiveGraphqlSchemaUpdates" and this value are set to true
-   * When enabled, any global secondary index update operation will replace the table instead of iterative deployment, which will WIPE ALL EXISTING DATA but cost much less time for deployment
-   * This will only affect DynamoDB tables with provision strategy "AMPLIFY_TABLE".
+   *
+   * When enabled, any global secondary index update operation will replace the table instead of iterative deployment, which will WIPE ALL
+   * EXISTING DATA but cost much less time for deployment This will only affect DynamoDB tables with provision strategy "AMPLIFY_TABLE".
    * @default false
    * @experimental
    */
@@ -567,6 +570,16 @@ export interface IAmplifyGraphqlDefinition {
    * @returns datasource strategy mapping
    */
   readonly dataSourceStrategies: Record<string, ModelDataSourceStrategy>;
+
+  /**
+   * An array of custom Query or Mutation SQL commands to the data sources that resolves them.
+   *
+   * **NOTE** Explicitly specifying the 'customSqlDataSourceStrategies' configuration option is in preview and is not recommended to use
+   * with production systems. For production, use the static factory methods `fromString` or `fromFiles`.
+   * @experimental
+   * @returns a list of mappings from custom SQL commands to data sources
+   */
+  readonly customSqlDataSourceStrategies?: CustomSqlDataSourceStrategy[];
 }
 
 /**
@@ -820,150 +833,3 @@ export interface AddFunctionProps {
    */
   readonly code?: Code;
 }
-
-/**
- * All known ModelDataSourceStrategies. Concrete strategies vary widely in their requirements and implementations.
- * @experimental
- */
-export type ModelDataSourceStrategy =
-  | DefaultDynamoDbModelDataSourceStrategy
-  | AmplifyDynamoDbModelDataSourceStrategy
-  | SQLLambdaModelDataSourceStrategy;
-
-// TODO: Make this the source of truth for database type definitions used throughout the construct & transformer
-export type ModelDataSourceStrategyDbType = 'DYNAMODB';
-
-/**
- * Use default CloudFormation type 'AWS::DynamoDB::Table' to provision table.
- * @experimental
- */
-export interface DefaultDynamoDbModelDataSourceStrategy {
-  readonly dbType: 'DYNAMODB';
-  readonly provisionStrategy: 'DEFAULT';
-}
-
-/**
- * Use custom resource type 'Custom::AmplifyDynamoDBTable' to provision table.
- * @experimental
- */
-export interface AmplifyDynamoDbModelDataSourceStrategy {
-  readonly dbType: 'DYNAMODB';
-  readonly provisionStrategy: 'AMPLIFY_TABLE';
-}
-
-/**
- * A strategy that creates a Lambda to connect to a pre-existing SQL table to resolve model data.
- *
- * @experimental
- */
-export interface SQLLambdaModelDataSourceStrategy {
-  /**
-   * The name of the strategy. This will be used to name the AppSync DataSource itself, plus any associated resources like resolver Lambdas.
-   * This name must be unique across all schema definitions in a GraphQL API.
-   */
-  readonly name: string;
-
-  /**
-   * The type of the SQL database used to process model operations for this definition.
-   */
-  readonly dbType: 'MYSQL' | 'POSTGRES';
-
-  /**
-   * The parameters the Lambda data source will use to connect to the database.
-   */
-  readonly dbConnectionConfig: SqlModelDataSourceDbConnectionConfig;
-
-  /**
-   * The configuration of the VPC into which to install the Lambda.
-   */
-  readonly vpcConfiguration?: VpcConfig;
-
-  /**
-   * Custom SQL statements. The key is the value of the `references` attribute of the `@sql` directive in the `schema`; the value is the SQL
-   * to be executed.
-   */
-  readonly customSqlStatements?: Record<string, string>;
-
-  /**
-   * An optional override for the default SQL Lambda Layer
-   */
-  readonly sqlLambdaLayerMapping?: SQLLambdaLayerMapping;
-
-  /**
-   * The configuration for the provisioned concurrency of the Lambda.
-   */
-  readonly sqlLambdaProvisionedConcurrencyConfig?: ProvisionedConcurrencyConfig;
-}
-
-/**
- * Configuration of the VPC in which to install a Lambda to resolve queries against a SQL-based data source. The SQL Lambda will be deployed
- * into the specified VPC, subnets, and security groups. The specified subnets and security groups must be in the same VPC. The VPC must
- * have at least one subnet. The construct will also create VPC service endpoints in the specified subnets, as well as inbound security
- * rules, to allow traffic on port 443 within each security group. This allows the Lambda to read database connection information from
- * Secure Systems Manager.
- * @experimental
- */
-export interface VpcConfig {
-  /** The VPC to install the Lambda data source in. */
-  readonly vpcId: string;
-
-  /** The security groups to install the Lambda data source in. */
-  readonly securityGroupIds: string[];
-
-  /** The subnets to install the Lambda data source in, one per availability zone. */
-  readonly subnetAvailabilityZoneConfig: SubnetAvailabilityZone[];
-}
-
-/**
- * The configuration for the provisioned concurrency of the Lambda.
- * @experimental
- */
-export interface ProvisionedConcurrencyConfig {
-  /** The amount of provisioned concurrency to allocate. **/
-  readonly provisionedConcurrentExecutions: number;
-}
-
-/**
- * Subnet configuration for VPC endpoints used by a Lambda resolver for a SQL-based data source. Although it is possible to create multiple
- * subnets in a single availability zone, VPC service endpoints may only be deployed to a single subnet in a given availability zone. This
- * structure ensures that the Lambda function and VPC service endpoints are mutually consistent.
- * @experimental
- */
-export interface SubnetAvailabilityZone {
-  /** The subnet ID to install the Lambda data source in. */
-  readonly subnetId: string;
-
-  /** The availability zone of the subnet. */
-  readonly availabilityZone: string;
-}
-
-/**
- * Maps a given AWS region to the SQL Lambda layer version ARN for that region. `key` is the region; the `value` is the Lambda Layer version
- * ARN
- */
-export type SQLLambdaLayerMapping = Record<string, string>;
-
-/**
- * The Secure Systems Manager parameter paths the Lambda data source will use to connect to the database.
- *
- * These parameters are retrieved from Secure Systems Manager in the same region as the Lambda.
- * @experimental
- */
-export interface SqlModelDataSourceDbConnectionConfig {
-  /** The Secure Systems Manager parameter containing the hostname of the database. For RDS-based SQL data sources, this can be the hostname
-   * of a database proxy, cluster, or instance.
-   */
-  readonly hostnameSsmPath: string;
-
-  /** The Secure Systems Manager parameter containing the port number of the database proxy, cluster, or instance. */
-  readonly portSsmPath: string;
-
-  /** The Secure Systems Manager parameter containing the username to use when connecting to the database. */
-  readonly usernameSsmPath: string;
-
-  /** The Secure Systems Manager parameter containing the password to use when connecting to the database. */
-  readonly passwordSsmPath: string;
-
-  /** The Secure Systems Manager parameter containing the database name. */
-  readonly databaseNameSsmPath: string;
-}