Skip to content

Latest commit

 

History

History
483 lines (290 loc) · 17.2 KB

API.md

File metadata and controls

483 lines (290 loc) · 17.2 KB
Raw

API Reference

Constructs

DbMigrate

  • Implements: aws-cdk-lib.aws_ec2.IConnectable, aws-cdk-lib.aws_iam.IGrantable

A high level construct for running the migrate based migration scripts against an AWS RDS Instance or Aurora cluster.

NOTE: It wouldn't take a lot to extend this to support the other database targets that 'migrate' supports if required.

Initializers 

import { DbMigrate } from 'db-migrate-cdk'

new DbMigrate(scope: Construct, id: string, props: DbMigrateProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props DbMigrateProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
addDependency No description.
getMigrateCommand Some of the migrate commands allow you to specify a target schema version (i.e 'migrate goto 5'). So we have some special handling here to tack the schema version on to the end of the command where appropriate.
getPort The way you retrieve the connection port depends on whether we are dealing with an RDS instance or an Aurora Cluster.
getSecretId If the user hasn't speficifed their own credentials then default to the credentials associated with the target database.
toString 
public toString(): string

Returns a string representation of this construct.

addDependency 
public addDependency(deps: IDependable): void
depsRequired
  • Type: constructs.IDependable
getMigrateCommand 
public getMigrateCommand(props: DbMigrateProps): string

Some of the migrate commands allow you to specify a target schema version (i.e 'migrate goto 5'). So we have some special handling here to tack the schema version on to the end of the command where appropriate.

propsRequired

the construct props.

getPort 
public getPort(props: DbMigrateProps): string

The way you retrieve the connection port depends on whether we are dealing with an RDS instance or an Aurora Cluster.

Plus the port number won't be resolved until provisioning time (hence the Token.asString code).

propsRequired

the construct props.

getSecretId 
public getSecretId(props: DbMigrateProps): ISecret

If the user hasn't speficifed their own credentials then default to the credentials associated with the target database.

propsRequired

the construct props.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { DbMigrate } from 'db-migrate-cdk'

DbMigrate.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.

Properties

Name Type Description
node constructs.Node The tree node.
connections aws-cdk-lib.aws_ec2.Connections The network connections associated with this resource.
grantPrincipal aws-cdk-lib.aws_iam.IPrincipal The principal to grant permissions to.
response string No description.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

connectionsRequired 
public readonly connections: Connections;
  • Type: aws-cdk-lib.aws_ec2.Connections

The network connections associated with this resource.

grantPrincipalRequired 
public readonly grantPrincipal: IPrincipal;
  • Type: aws-cdk-lib.aws_iam.IPrincipal

The principal to grant permissions to.

responseRequired 
public readonly response: string;
  • Type: string

Structs

DbMigrateProps

Initializer 

import { DbMigrateProps } from 'db-migrate-cdk'

const dbMigrateProps: DbMigrateProps = { ... }

Properties

Name Type Description
migrationsFolder string The local folder containing the sql migration scripts to be used by the 'migrate' cli command.
targetDatabaseInstance aws-cdk-lib.aws_rds.DatabaseCluster | aws-cdk-lib.aws_rds.DatabaseInstance The target RDS instance or Aurora cluster to run the migrations against.
targetDatabaseName string The target database in the target instance/cluster to initially connect to.
vpc aws-cdk-lib.aws_ec2.IVpc The vpc to define the custom resource lambda function in.
dbCredentialsSecret aws-cdk-lib.aws_secretsmanager.ISecret If you want to use an alternate set of db credentials to access the database to the one associated with the instance then pass it here.
eventHandlerLogRetention aws-cdk-lib.aws_logs.RetentionDays No description.
eventHandlerMemorySize number No description.
eventHandlerTimeout aws-cdk-lib.Duration No description.
migrateCommand DbMigrateCommand The migrate command that the 'migrate cli' will run.
providerLogRetention aws-cdk-lib.aws_logs.RetentionDays No description.
providerTotalTimeout aws-cdk-lib.Duration No description.
securityGroups aws-cdk-lib.aws_ec2.ISecurityGroup[] Security groups to attach to the lambda function.
subnetSelection aws-cdk-lib.aws_ec2.SubnetSelection Which subnets from the VPC to place the lambda functions in.
targetSchemaVersion number Some migrate commands accept an optional second argument for the target schema version to move to.
migrationsFolderRequired 
public readonly migrationsFolder: string;
  • Type: string

The local folder containing the sql migration scripts to be used by the 'migrate' cli command.

These scripts will first be uploaded to S3 where they will be access by the lambda function running the migrate cli.

targetDatabaseInstanceRequired 
public readonly targetDatabaseInstance: DatabaseCluster | DatabaseInstance;
  • Type: aws-cdk-lib.aws_rds.DatabaseCluster | aws-cdk-lib.aws_rds.DatabaseInstance

The target RDS instance or Aurora cluster to run the migrations against.

targetDatabaseNameRequired 
public readonly targetDatabaseName: string;
  • Type: string

The target database in the target instance/cluster to initially connect to.

vpcRequired 
public readonly vpc: IVpc;
  • Type: aws-cdk-lib.aws_ec2.IVpc

The vpc to define the custom resource lambda function in.

dbCredentialsSecretOptional 
public readonly dbCredentialsSecret: ISecret;
  • Type: aws-cdk-lib.aws_secretsmanager.ISecret
  • Default: targetDatabase.secret

If you want to use an alternate set of db credentials to access the database to the one associated with the instance then pass it here.

eventHandlerLogRetentionOptional 
public readonly eventHandlerLogRetention: RetentionDays;
  • Type: aws-cdk-lib.aws_logs.RetentionDays
  • Default: Retention.ONE_YEAR
eventHandlerMemorySizeOptional 
public readonly eventHandlerMemorySize: number;
  • Type: number
  • Default: 128
eventHandlerTimeoutOptional 
public readonly eventHandlerTimeout: Duration;
  • Type: aws-cdk-lib.Duration
  • Default: Duration.minutes(14)
migrateCommandOptional 
public readonly migrateCommand: DbMigrateCommand;

The migrate command that the 'migrate cli' will run.

providerLogRetentionOptional 
public readonly providerLogRetention: RetentionDays;
  • Type: aws-cdk-lib.aws_logs.RetentionDays
  • Default: Retention.ONE_YEAR
providerTotalTimeoutOptional 
public readonly providerTotalTimeout: Duration;
  • Type: aws-cdk-lib.Duration
  • Default: Duration.minutes(14)
securityGroupsOptional 
public readonly securityGroups: ISecurityGroup[];
  • Type: aws-cdk-lib.aws_ec2.ISecurityGroup[]
  • Default: a dedicated security group is created for each function.

Security groups to attach to the lambda function.

subnetSelectionOptional 
public readonly subnetSelection: SubnetSelection;
  • Type: aws-cdk-lib.aws_ec2.SubnetSelection
  • Default: the Vpc default strategy if not specified

Which subnets from the VPC to place the lambda functions in.

Note: internet access for Lambdas requires a NAT gateway, so picking Public subnets is not allowed.

targetSchemaVersionOptional 
public readonly targetSchemaVersion: number;
  • Type: number

Some migrate commands accept an optional second argument for the target schema version to move to.

Enums

DbMigrateCommand

Defines the possible commands you can pass to the 'migrate' cli.

Members

Name Description
UP Will instruct migrate to move the schema evolutions forward as far as possible or to the specified version.
DOWN Will instruct migrate to move the schema evolutions back as far as possible or to the specified version.
GOTO Will instruct migrate to move the schema evolutions to the specified version.
DROP Drop everything in the database.
FORCE Set version to specified version but don't run migration.
VERSION Prints the currently applied schema version.
UP

Will instruct migrate to move the schema evolutions forward as far as possible or to the specified version.

DOWN

Will instruct migrate to move the schema evolutions back as far as possible or to the specified version.

GOTO

Will instruct migrate to move the schema evolutions to the specified version.

DROP

Drop everything in the database.

FORCE

Set version to specified version but don't run migration.

VERSION

Prints the currently applied schema version.