# DatabaseProxy

RDS Database Proxy.

Extends: Construct › Resource › DatabaseProxy
Implements: IResource, IConnectable, IDatabaseProxy, ISecretAttachmentTarget, IEnvironmentAware, IDBProxyRef, IConstruct, IDependable

- CloudFormation: [`AWS::RDS::DBProxy`](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-rds-dbproxy.html)
- L1 type: [`CfnDBProxy`](/cdk/api/v2/docs/aws-cdk-lib.aws_rds.CfnDBProxy.html)
- Source: [`aws-rds/lib/proxy.ts`](https://github.com/aws/aws-cdk/blob/v2.273.0/packages/aws-cdk-lib/aws-rds/lib/proxy.ts#L447)
- Type last changed: v2.235.0 · 15 Jan 2026

## Example

```ts
declare const vpc: ec2.Vpc;
const cluster = new rds.DatabaseCluster(this, 'Database', {
  engine: rds.DatabaseClusterEngine.auroraMysql({
    version: rds.AuroraMysqlEngineVersion.VER_3_03_0,
  }),
  writer: rds.ClusterInstance.provisioned('writer'),
  vpc,
});

const proxy = new rds.DatabaseProxy(this, 'Proxy', {
  proxyTarget: rds.ProxyTarget.fromCluster(cluster),
  secrets: [cluster.secret!],
  vpc,
  clientPasswordAuthType: rds.ClientPasswordAuthType.MYSQL_NATIVE_PASSWORD,
});
```

## Initializer

```ts
new DatabaseProxy(scope: Construct, id: string, props: DatabaseProxyProps)
```

## Construct Props

- `borrowTimeout`: [Duration](/cdk/api/v2/docs/aws-cdk-lib.Duration.html) = cdk.Duration.seconds(120) — The duration for a proxy to wait for a connection to become available in the connection pool.

  Only applies when the proxy has opened its maximum number of connections and all connections are busy with client
  sessions.

  Value must be between 1 second and 1 hour, or `Duration.seconds(0)` to represent unlimited.

- `clientPasswordAuthType`: [ClientPasswordAuthType](/cdk/api/v2/docs/aws-cdk-lib.aws_rds.ClientPasswordAuthType.html) = CloudFormation defaults will apply given the specified database engine. — Specifies the details of authentication used by a proxy to log in as a specific database user.

  **Default:** CloudFormation defaults will apply given the specified database engine.

- `dbProxyName`: string = Generated by CloudFormation (recommended) — The identifier for the proxy.

  This name must be unique for all proxies owned by your AWS account in the specified AWS Region.
  An identifier must begin with a letter and must contain only ASCII letters, digits, and hyphens;
  it can't end with a hyphen or contain two consecutive hyphens.

  **Default:** Generated by CloudFormation (recommended)

- `debugLogging`: boolean = false — Whether the proxy includes detailed information about SQL statements in its logs.

  This information helps you to debug issues involving SQL behavior or the performance and scalability of the proxy connections.
  The debug information includes the text of SQL statements that you submit through the proxy.
  Thus, only enable this setting when needed for debugging, and only when you have security measures in place to safeguard any sensitive
  information that appears in the logs.

- `defaultAuthScheme`: [DefaultAuthScheme](/cdk/api/v2/docs/aws-cdk-lib.aws_rds.DefaultAuthScheme.html) = DefaultAuthScheme.NONE — The default authentication scheme that the proxy uses for client connections to the proxy and connections from the proxy to the underlying database.

  When set to `DefaultAuthScheme.IAM_AUTH`, the proxy uses end-to-end IAM authentication to connect to the database.

- `iamAuth`: boolean = false — Whether to require or disallow AWS Identity and Access Management (IAM) authentication for connections to the proxy.

- `idleClientTimeout`: [Duration](/cdk/api/v2/docs/aws-cdk-lib.Duration.html) = cdk.Duration.minutes(30) — The number of seconds that a connection to the proxy can be inactive before the proxy disconnects it.

  You can set this value higher or lower than the connection timeout limit for the associated database.

- `initQuery`: string = no initialization query — One or more SQL statements for the proxy to run when opening each new database connection.

  Typically used with SET statements to make sure that each connection has identical settings such as time zone
  and character set.
  For multiple statements, use semicolons as the separator.
  You can also include multiple variables in a single SET statement, such as SET x=1, y=2.

  not currently supported for PostgreSQL.

- `maxConnectionsPercent`: number = 100 — The maximum size of the connection pool for each target in a target group.

  For Aurora MySQL, it is expressed as a percentage of the max_connections setting for the RDS DB instance or Aurora DB
  cluster used by the target group.

  1-100

- `maxIdleConnectionsPercent`: number = 50 — Controls how actively the proxy closes idle database connections in the connection pool.

  A high value enables the proxy to leave a high percentage of idle connections open.
  A low value causes the proxy to close idle client connections and return the underlying database connections
  to the connection pool.
  For Aurora MySQL, it is expressed as a percentage of the max_connections setting for the RDS DB instance
  or Aurora DB cluster used by the target group.

  between 0 and MaxConnectionsPercent

- `proxyTarget`: [ProxyTarget](/cdk/api/v2/docs/aws-cdk-lib.aws_rds.ProxyTarget.html) (required) — DB proxy target: Instance or Cluster.

- `requireTLS`: boolean = true — A Boolean parameter that specifies whether Transport Layer Security (TLS) encryption is required for connections to the proxy.

  By enabling this setting, you can enforce encrypted TLS connections to the proxy.

- `role`: [IRole](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IRole.html) = A role will automatically be created — IAM role that the proxy uses to access secrets in AWS Secrets Manager.

  **Default:** A role will automatically be created

- `secrets`: [ISecret](/cdk/api/v2/docs/aws-cdk-lib.aws_secretsmanager.ISecret.html)[] = None — The secret that the proxy uses to authenticate to the RDS DB instance or Aurora DB cluster.

  These secrets are stored within Amazon Secrets Manager.
  One or more secrets are required when defaultAuthScheme is `DefaultAuthScheme.NONE`.

- `securityGroups`: [ISecurityGroup](/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.ISecurityGroup.html)[] = No security groups — One or more VPC security groups to associate with the new proxy.

- `sessionPinningFilters`: [SessionPinningFilter](/cdk/api/v2/docs/aws-cdk-lib.aws_rds.SessionPinningFilter.html)[] = no session pinning filters — Each item in the list represents a class of SQL operations that normally cause all later statements in a session using a proxy to be pinned to the same underlying database connection.

  Including an item in the list exempts that class of SQL operations from the pinning behavior.

- `vpc`: [IVpc](/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.IVpc.html) (required) — The VPC to associate with the new proxy.

- `vpcSubnets`: [SubnetSelection](/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.SubnetSelection.html) = the VPC default strategy if not specified. — The subnets used by the proxy.

  **Default:** the VPC default strategy if not specified.

## Properties

- `connections`: [Connections](/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.Connections.html) (required) — Access to network connections.

- `dbProxyArn`: string (required) — DB Proxy ARN.

- `dbProxyName`: string (required) — DB Proxy Name.

- `dbProxyRef`: [DBProxyReference](/cdk/api/v2/docs/aws-cdk-lib.interfaces.aws_rds.DBProxyReference.html) (required) — A reference to this database proxy.

- `endpoint`: string (required) — Endpoint.

- `env`: [ResourceEnvironment](/cdk/api/v2/docs/aws-cdk-lib.interfaces.ResourceEnvironment.html) (required) — The environment this resource belongs to.

  For resources that are created and managed in a Stack (those created by
  creating new class instances like `new Role()`, `new Bucket()`, etc.), this
  is always the same as the environment of the stack they belong to.

  For referenced resources (those obtained from referencing methods like
  `Role.fromRoleArn()`, `Bucket.fromBucketName()`, etc.), they might be
  different than the stack they were imported into.

- `node`: [Node](/cdk/api/v2/docs/constructs.Node.html) (required) — The tree node.

- `PROPERTY_INJECTION_ID`: string (required) (static) — Uniquely identifies this class.

- `stack`: [Stack](/cdk/api/v2/docs/aws-cdk-lib.Stack.html) (required) — The stack in which this resource is defined.

## Methods

- `addEndpoint(id: string, options?: DatabaseProxyEndpointOptions): IDatabaseProxyEndpoint` — Add an Endpoint to this DB Proxy.

- `applyCrossStackReferenceStrength(strength: ReferenceStrength): void` — Override the cross-stack reference strength for this resource.

  When set, any cross-stack reference to this resource will use the specified
  mechanism instead of the global default determined by the
  `@aws-cdk/core:defaultCrossStackReferences` context key. This is useful for
  selectively weakening specific references to avoid the "deadly embrace" problem
  without changing the app-wide default.

  **Parameters**

  - `strength` — - The reference strength to use for this resource.

- `applyRemovalPolicy(policy: RemovalPolicy): void` — Apply the given removal policy to this resource.

  The Removal Policy controls what happens to this resource when it stops
  being managed by CloudFormation, either because you've removed it from the
  CDK application or because you've made a change that requires the resource
  to be replaced.

  The resource can be deleted (`RemovalPolicy.DESTROY`), or left in your AWS
  account for data recovery and cleanup later (`RemovalPolicy.RETAIN`).

- `asSecretAttachmentTarget(): SecretAttachmentTargetProps` — Renders the secret attachment target specifications.

- `fromDatabaseProxyAttributes(scope: Construct, id: string, attrs: DatabaseProxyAttributes): IDatabaseProxy` (static) — Import an existing database proxy.

- `grantConnect(grantee: IGrantable, dbUser?: string): Grant` — [disable-awslint:no-grants].

- `isConstruct(x: any): boolean` (static) — Checks if `x` is a construct.

  Use this method instead of `instanceof` to properly detect `Construct`
  instances, even when the construct library is symlinked.

  Explanation: in JavaScript, multiple copies of the `constructs` library on
  disk are seen as independent, completely different libraries. As a
  consequence, the class `Construct` in each copy of the `constructs` library
  is seen as a different class, and an instance of one class will not test as
  `instanceof` the other class. `npm install` will not create installations
  like this, but users may manually symlink construct libraries together or
  use a monorepo tool: in those cases, multiple copies of the `constructs`
  library can be accidentally installed, and `instanceof` will behave
  unpredictably. It is safest to avoid using `instanceof`, and using
  this type-testing method instead.

  **Parameters**

  - `x` — Any object.

  **Returns:** true if `x` is an object created from a class which extends `Construct`.

- `isOwnedResource(construct: IConstruct): boolean` (static) — Returns true if the construct was created by CDK, and false otherwise.

- `isResource(construct: IConstruct): boolean` (static) — Check whether the given construct is a Resource.

- `toString(): string` — Returns a string representation of this construct.

- `with(...mixins: IMixin[]): IConstruct` — Applies one or more mixins to this construct.

  Mixins are applied in order. The list of constructs is captured at the
  start of the call, so constructs added by a mixin will not be visited.
  Use multiple `with()` calls if subsequent mixins should apply to added
  constructs.