Overview and basic concepts
Relational databases allow you to deploy a fully managed relational (SQL) database to your stack. You can choose from multiple database types, such as PostgreSQL, MySQL, MariaDB, Oracle Database or SQL Server.
They are easy to set up, operate and scale. They automate capacity scaling, hardware & VM provisioning, database setup, patching, logging, backups and more.
Stacktape supports 3 underlying engine categories, with different topology and scaling behavior:
- Rds engine: default, cheapest, single-node database with optional read replicas for higher performance and Multi AZ standby instances for increased resilience and fault tolerance.
- Aurora engine: mutli-node, highly available database cluster with increased durability and performance.
- Aurora serverless engine: similar to Aurora engine, but with support for automatic usage-based scaling.
Basic usage
- Relational databases require an active connection. To establish a connection, you typically need
host
(database endpoint),port
,database_name
,database_user_name
anddatabase_user_password
. - You can pass these properties as environment variables to your workloads.
Copy
resources:myDatabase:type: relational-databaseproperties:credentials:masterUserName: adminusermasterUserPassword: $Secret('database.password')engine:type: postgresproperties:dbName: mydatabaseport: 5432primaryInstance:instanceSize: db.t2.microapiServer:type: container-workloadproperties:resources:cpu: 1memory: 1024containers:- name: api-containerpackaging:type: stacktape-image-buildpackproperties:entryfilePath: src/main.tsenvironment:- name: DB_USERvalue: adminuser- name: DB_PASSWORDvalue: $Secret('database.password')- name: DB_HOSTvalue: $ResourceParam('myDatabase', 'host')- name: DB_PORTvalue: $ResourceParam('myDatabase', 'port')- name: DB_NAMEvalue: $ResourceParam('myDatabase', 'dbName')
Single-node Postgres database that uses RDS Engine
Copy
import express from 'express';import { Pool } from 'pg';const pgPool = new Pool({user: process.env.DB_USER,host: process.env.DB_HOST,database: process.env.DB_NAME,password: process.env.DB_PASSWORD,port: process.env.DB_PORT});const app = express();app.get('/time', async (req, res) => {const result = await pgPool.query('SELECT NOW()');const time = result.rows[0];res.send(time);});app.listen(3000, () => {console.info('Server running on port 3000');});
Container workload connecting to the database
Database credentials
- Configures credentials for the database master user.
- You should not input these directly. The recommended way is using a
.env
file together with File directive or using secrets.
Copy
resources:myRelationalDatabase:type: relational-databaseproperties:credentials:masterUserName: $File('.env').DB_USER_NAMEmasterUserPassword: $Secret('dbCredentials.password')engine:type: postgresproperties:dbName: my-databaseport: 5432primaryInstance:instanceSize: db.t2.micro
Username of the database master user
Type: string
Password of the database master user
Type: string
Engine
- Database engine determines multiple important properties of your database:
- Database type (PostgreSQL, MySQL, MariaDB, Oracle Database or SQL Server)
- Performance
- High availability and fault tolerance
- Scaling behavior
- Pricing
Rds Engine
- To use the RDS engine, set the
engine.type
property topostgres
,mysql
,mariadb
,oracle-ee
,oracle-se2
,sqlserver-ee
,sqlserver-ex
,sqlserver-se
orsqlserver-web
. - RDS engine is the default, cheapest, single-node, fully managed database engine.
- RdsEngine is not highly available or fault-tolerant by default. However, Stacktape allows you to configure a standby instance in a different AZ (Availability zone) to increase resilience or add read replicas to increase read performance.
No description
Type: string ENUM
Possible values: mariadbmysqloracle-eeoracle-se2postgressqlserver-eesqlserver-exsqlserver-sesqlserver-web
Configures the primary database instance
Type: RdsEnginePrimaryInstance
Configures the name of the default database in the database cluster
Type: string
Meaning of this parameter differs based on the database type:
mysql
: The name of the database to create when the DB instance is created. If this parameter is not specified, a database with name defdb is created.mariadb
: The name of the database to create when the DB instance is created. If this parameter is not specified, a database with name defdb is created.postgres
: The name of the database to create when the DB instance is created. If this parameter is not specified, a database with name defdb is created.oracle-se2
+oracle-ee
: The Oracle System ID (SID) of the created DB instance. If this parameter is not specified, a database with SID defdb is created.sqlserver-ee
+sqlserver-ex
+sqlserver-se
+sqlserver-web
: Not applicable. Must be null.
The port on which the database server will accept client connections.
Type: number
Default values differ based on engine:
mysql
+mariadb
: 3306postgres
: 5432oracle-se2
+oracle-ee
: 1521sqlserver-ee
+sqlserver-ex
+sqlserver-se
+sqlserver-web
: 1433
Configures the storage (disk size) for the database
Type: RdsEngineStorage
- When you run out of free database space, your storage will automatically scale up.
- By default, scales between 20GB and 200GB.
- The scaling process happens when the following conditions are met:
- Free available space` is less than 10 percent of the allocated storage
- The low-storage condition lasts at least five minutes.
- At least six hours have passed since the last storage modification.
- To learn more about storage autoscaling, refer to AWS Docs
List of read replicas (replicas of primary instance)
Type: Array of RdsEngineReadReplica
- Read replicas help to decrease the load on the primary instance by serving a read-only database requests.
- Replication uses database's native asynchronous replication to update the read replicas whenever there is a change to the primary instance.
- Each read replica has its own database endpoint.
Version of the database
Type: string
Configures logging behavior for the database
Type: RelationalDatabaseLogging
- By default, logging is enabled and logs are preserved for
90
days. - Logged data depend on the used
engine
. You can log information about connections, disconnections, executed queries & much more.
Instance size
- Allows you to choose the database instance size. Each instance size offers different combination of CPU, memory, storage, and networking capacity.
- To see a list of available instances, refer to AWS docs
Not every instance size is supported for every database engine, version or region. Refer to AWS Docs for detailed breakdown of supported combinations.
- Instance size can be configured for both primary instance and read replicas.
Copy
resources:myDatabase:type: relational-databaseproperties:credentials:masterUserName: adminmasterUserPassword: $Secret('dbPassword')engine:type: postgresproperties:dbName: app-dbport: 5432primaryInstance:instanceSize: db.t2.micro
MultiAz mode
- When enabled, the data is replicated to a standby instance in a different AZ (Availability Zone).
- If the default (primary) instance fails, the failover to the standby instance in another AZ is performed.
- The failover to the standby instance is synchronous (highly durable).
- The standby instance can not be directly accessed (doesn't have its own database endpoint).
- In contrast to using replicas, standby instance can fully take-over the responsibilities of the primary instance, while replicas can only be used for read operations.
- Reduces the impact of maintenance. The maintenance is performed on the standby instance first, promotes the standby instance to a primary instance, and then performs maintenance on the old primary instance which is now a standby replica.
- Multi AZ (Availability zone) mode can be configured for both primary instances and read replicas.
Copy
resources:myDatabase:type: relational-databaseproperties:credentials:masterUserName: adminmasterUserPassword: $Secret('dbPassword')engine:type: postgresproperties:dbName: mydatabaseport: 5432primaryInstance:instanceSize: db.t2.micromultiAz: true
Database instance size
Type: string
- Allows you to choose the database instance size. Each instance size offers different combination of CPU, memory, storage, and networking capacity.
- To see a list of available instances, refer to AWS docs
Not every instance size is supported for every database engine, version or region. Refer to AWS Docs for detailed breakdown of supported combinations.
Specifies whether the database instance is deployed to multiple Availability Zones
Type: boolean
- When enabled, the data is replicated to a standby instance in a different AZ (Availability Zone).
- If the default (primary) instance fails, the failover to the standby instance in another AZ is performed.
- The failover to the standby instance is synchronous (highly durable).
- The standby instance can not be directly accessed (doesn't have its own database endpoint).
- In contrast to using replicas, standby instance can fully take-over the responsibilities of the primary instance, while replicas can only be used for read operations.
- Reduces the impact of maintenance. The maintenance is performed on the standby instance first, promotes the standby instance to a primary instance, and then performs maintenance on the old primary instance which is now a standby replica.
Read replicas
- Read replicas help to decrease the load on the primary instance by serving a read-only database requests.
- Replication uses database's native asynchronous replication to update the read replicas whenever there is a change to the primary instance.
- Each read replica has its own database endpoint.
Copy
resources:myDatabase:type: relational-databaseproperties:credentials:masterUserName: adminmasterUserPassword: $Secret('dbPassword')engine:type: postgresproperties:dbName: app-dbport: 5432primaryInstance:instanceSize: db.t2.microreadReplicas:- instanceSize: db.t2.micro- instanceSize: db.t2.micro
Database instance size
Type: string
- Allows you to choose the database instance size. Each instance size offers different combination of CPU, memory, storage, and networking capacity.
- To see a list of available instances, refer to AWS docs
Not every instance size is supported for every database engine, version or region. Refer to AWS Docs for detailed breakdown of supported combinations.
Specifies whether the database instance is deployed to multiple Availability Zones
Type: boolean
- When enabled, the data is replicated to a standby instance in a different AZ (Availability Zone).
- If the default (primary) instance fails, the failover to the standby instance in another AZ is performed.
- The failover to the standby instance is synchronous (highly durable).
- The standby instance can not be directly accessed (doesn't have its own database endpoint).
- In contrast to using replicas, standby instance can fully take-over the responsibilities of the primary instance, while replicas can only be used for read operations.
- Reduces the impact of maintenance. The maintenance is performed on the standby instance first, promotes the standby instance to a primary instance, and then performs maintenance on the old primary instance which is now a standby replica.
Storage
- When you run out of free database space, your storage will automatically scale up.
- By default, scales between 20GB and 200GB.
- The scaling process happens when the following conditions are met:
- Free available space` is less than 10 percent of the allocated storage
- The low-storage condition lasts at least five minutes.
- At least six hours have passed since the last storage modification.
- To learn more about storage autoscaling, refer to AWS Docs
Copy
resources:myDatabase:type: relational-databaseproperties:credentials:masterUserName: adminmasterUserPassword: $Secret('dbPassword')engine:type: postgresproperties:dbName: mydatabaseport: 5432primaryInstance:instanceSize: db.t2.microstorage:initialSize: 40maxSize: 400
Initial amount of storage (disk size in GB) your database will have when created
Type: number
- Minimum
20
Maximum amount of storage (disk size in GB) your database can scale up to
Type: number
If you are running out of the free database space, your storage is automatically scaled up.
The scaling process happens when the following conditions are met:
- Free available space` is less than 10 percent of the allocated storage
- The low-storage condition lasts at least five minutes.
- At least six hours have passed since the last storage modification.
To learn more about storage autoscaling, refer to AWS Docs
Aurora Engine
- To use the Aurora engine, set the
engine.type
property toaurora-postgresql
oraurora-mysql
. - Fully-managed, AWS-developed engine with clustering support, high-availability, increased durability & performance.
- Compute instances (nodes) run in a single Availability Zones. Storage is automatically replicated 6-ways accross 3 availability zones.
- Automatically load-balances read operations between nodes.
- Automatic failover - if a primary instance fails, one of the read replicas is elected as a new primary instance.
- To learn more about the AuroraEngine, refer to AWS Docs
Copy
resources:auroraSlsPostgres:type: relational-databaseproperties:credentials:masterUserName: adminmasterUserPassword: $Secret('dbSecret.password')engine:type: aurora-postgresqlproperties:dbName: mydatabaseinstances:- instanceSize: db.t3.mediumport: 5432
No description
Type: string ENUM
Possible values: aurora-mysqlaurora-postgresql
List of database instances that make up the Aurora cluster
Type: Array of AuroraEngineInstance
- First instance in this list is by default a primary instance, which can be used for both reads and writes.
- Rest of the instances can be used for reads only.
- Aurora cluster automatically balances read request between all of the instances.
- In a case of a primary instance failure, Aurora cluster selects another instance to be the primary instance.
Configures the name of the default database in the database cluster
Type: string
By default, a database with name defdb is created.
The port on which the database server will accept connections.
Type: number
Default values differ based on engine:
aurora-mysql
: 3306aurora-postgresql
: 5432
Version of the database
Type: string
Configures logging behavior for the database
Type: RelationalDatabaseLogging
- By default, logging is enabled and logs are preserved for
90
days. - Logged data depend on the used
engine
. You can log information about connections, disconnections, executed queries & much more.
Database instance size
Type: string
- Allows you to choose the database instance size. Each instance size offers different combination of CPU, memory, storage, and networking capacity.
- For a list of available instance types, refer to AWS docs
Aurora Serverless Engine
- To use the Aurora Serverless engine, set the
engine.type
property toaurora-postgresql-serverless
oraurora-mysql-serverless
. - Fully-managed AWS-developed engine with clustering support, high-availability, increased durability & performance.
- Similar to AuroraEngine type, but automatically scales based on usage. Scaling is done using ACUs (Aurora Compute units).
- Each ACU has ~2GB of RAM and 1 virtual CPU.
- Can scale to 0 ACUs (database is paused, and you don't pay anything).
- To learn more about AuroraServerlessEngine, refer to AWS Docs
No description
Type: string ENUM
Possible values: aurora-mysql-serverlessaurora-postgresql-serverless
Configures the name of the default database in the database cluster
Type: string
By default, a database with name defdb is created.
The minimum capacity units the database can scale down to
Type: number
- Serverless databases use ACUs (or Aurora Capacity Units) to measure database capacity. Each ACU has approximately 2 GB of memory with corresponding CPU and networking resources.
- Allowed values:
- For aurora-mysql-serverless:
1
,2
,4
,8
,16
,32
,64
,128
, and256
. - For aurora-postgres-serverless:
2
,4
,8
,16
,32
,64
,128
, and256
.
- For aurora-mysql-serverless:
The maximum capacity units the database can scale up to
Type: number
- Serverless databases use ACUs (or Aurora Capacity Units) to measure database capacity. Each ACU has approximately 2 GB of memory with corresponding CPU and networking resources.
- Allowed values:
- For aurora-mysql-serverless:
1
,2
,4
,8
,16
,32
,64
,128
, and256
. - For aurora-postgres-serverless:
2
,4
,8
,16
,32
,64
,128
, and256
.
- For aurora-mysql-serverless:
Time in seconds after the idle serverless database is paused
Type: number
- Database is considered idle when it has no active connections.
- By default, the database is never paused (it is kept at minimal capacity).
- Allowed values are between
300
(5 minutes) and86400
(24 hours).
Version of the database
Type: string
Configures logging behavior for the database
Type: RelationalDatabaseLogging
- By default, logging is enabled and logs are preserved for
90
days. - Logged data depend on the used
engine
. You can log information about connections, disconnections, executed queries & much more.
Copy
resources:myDatabase:type: relational-databaseproperties:credentials:masterUserName: adminmasterUserPassword: $Secret('dbSecret.password')engine:type: aurora-postgresql-serverlessproperties:dbName: mydatabaseminCapacity: 4maxCapacity: 8pauseAfterSeconds: 600
Backups
- Databases are automatically backed up once a day.
- Maximum retention period is
35
days. - You can disable automated backups by setting the value to 0 (works only for RDS engines).
- You can also take manual backup snapshots (in the console or using the API). The retention is not applied to manual backups.
- By default, backups are retained for 1 day.
- To learn more about RDS engine backups, refer to RDS engine backups AWS Docs.
- To learn more about Aurora engine backups, refer to Aurora engine backups AWS Docs.
Copy
resources:myDatabase:type: relational-databaseproperties:credentials:masterUserName: admin_usermasterUserPassword: my_secret_passwordengine:type: postgresproperties:primaryInstance:instanceSize: db.t3.microautomatedBackupRetentionDays: 5
Logging
- By default, logging is enabled and logs are preserved for
90
days. - Logged data depend on the used
engine
. You can log information about connections, disconnections, executed queries & much more.
Disables the collection of database server logs to CloudWatch
Type: boolean
Amount of days the logs will be retained in the log group
Type: number ENUM
Possible values: 13571430609012015018036540054573118273653
Log types which are captured and exported into log groups
Type: Array of string
For different database engines, different log types can be collected:
postgres
,aurora-postgresql
,aurora-postgresql-serverless
- allowed log types: [postgresql]
- default log types: [postgresql]
- you can further specify which logs should be included in postgresql logs by using
engineSpecificOptions
property
mysql
,aurora-mysql
,aurora-mysql-serverless
,mariadb
- allowed log types: [audit, error, general, slowquery]
- default log types: [audit, error, slowquery]
- you can further specify which logs should be included in audit and slowquery logs by using
engineSpecificOptions
property
oracle-ee
,oracle-se2
- allowed log types: [alert, audit, listener, trace]
- default log types: [alert, listener]
sqlserver-se
,sqlserver-web
- allowed log types: [agent, error]
- default log types: [agent, error]
sqlserver-ex
- allowed log types: [error]
- default log types: [error]
Configures engine-specific log options
Type: (PostgresLoggingOptions or MysqlLoggingOptions)
- Currently, only the following engines support engine specific log options:
postgres
,aurora-postgresql
,aurora-postgresql-serverless
,mysql
,aurora-mysql
,aurora-mysql-serverless
,mariadb
Copy
resources:myDatabase:type: relational-databaseproperties:credentials:masterUserName: admin_usermasterUserPassword: my_secret_passwordengine:type: postgresproperties:primaryInstance:instanceSize: db.t3.micrologging:retentionDays: 30engineSpecificOptions:log_connections: true
Connection pool size
- Depending on the number of clients connecting to your database, you might want to adjust the connection pool size.
- Note that every new connection consume database resources.
- Depending on the database and client connecting to the database, it can also take 10s to 100s of milliseconds to initialize a database connection.
Copy
resources:myDatabase:type: relational-databaseproperties:credentials:masterUserName: adminmasterUserPassword: $Secret('dbPassword')engine:type: postgresproperties:dbName: mydatabaseport: 5432primaryInstance:instanceSize: db.t2.microdatabaseParameters:connectionPoolSize: 50
Closing zombie connections
- Connections initiated by resources that are no longer running (for example stopped containers) can result in so called "zombie" connections.
- Modern, cloud-native architectures usually include horizontally scalable, ephemeral (short-lived) resources. When using these resources, you should have a strategy of dealing with zombie connections.
From container workloads
- For connections initiated from container workloads, you shouldn't forget to close the connection before your container exits. For example, ou can hook to a sigterm signal.
Copy
const connectionPool = createConnectionPool();// remember to close the connection even on errorsprocess.on('uncaughtException', () => {connectionPool.close();process.exit(1);}).on('unhandledRejection', () => {connectionPool.close();process.exit(1);});process.on('SIGTERM', () => {connectionPool.close();process.exit(0);});
Example of closing
From batch jobs
- For connections initiated from batch jobs, you shouldn't forget to close the connection before your batch job finishes its job and your container exits.
Copy
const connectionPool = createConnectionPool();connectionPool.connect();// remember to close the connection even on errorsprocess.on('uncaughtException', () => {connectionPool.close();process.exit(1);}).on('unhandledRejection', () => {connectionPool.close();process.exit(1);});doSomethingWithYourConnection();connectionPool.close();
From lambda functions
- For connections initiated from lambda functions, you have 2 options:
Initialize and close the connection INSIDE the function handler.
- This way you can avoid having a zombie connection.
- This approach is not optimal, because creating a database connection can be slow (can take 10s to 100s of
milliseconds).
Copy
import { Client } from 'pg';const handler = async (event, context) => {const pgClient = new Client({user: process.env.DB_USER,host: process.env.DB_HOST,database: process.env.DB_NAME,password: process.env.DB_PASSWORD,port: process.env.DB_PORT});await pgClient.connect();const result = await pgClient.query('SELECT NOW()');const time = result.rows[0];await pgClient.end();return { result: time };};export default handler;
Initialize connections OUTSIDE the function handler
reuse it in every function invocation.
This WILL result in zombie connections, when the container running your function stops (you can't hook to a lambda container
SIGTERM
signal to close it). In this case, you should do 2 things:- lower your database connection timeout (using a database parameter based on the database used):
- for Postgres, set
idle_in_transaction_session_timeout
to something like30min
,tcp_keepalives_idle
to30min
andtcp_keepalives_interval
to1min
). This means inactive connections will be closed by the database. - for MySQL, @todo
- for Postgres, set
- if a database request fails because of a closed connection, you should re-create it within your application code.
Copy
import { Client } from 'pg';const pgClient = new Client({user: process.env.DB_USER,host: process.env.DB_HOST,database: process.env.DB_NAME,password: process.env.DB_PASSWORD,port: process.env.DB_PORT});(async () => {await pgClient.connect();})();const handler = async (event, context) => {const result = await pgClient.query('SELECT NOW()');const time = result.rows[0];return { result: time };};export default handler;
- lower your database connection timeout (using a database parameter based on the database used):
Accessibility
- You can configure which resources and hosts can access your cluster.
- To access your database, you always need to use your database user credentials.
- On top of that, Stacktape allows your to restrict the accessibility of your database to only certain resources or hosts.
Configures the accessibility mode for this database
Type: string ENUM
Possible values: internetscoping-workloads-in-vpcvpcwhitelisted-ips-only
The following modes are supported:
- internet - Least restrictive mode. The database can be accessed from anywhere on the internet.
- vpc - The database can be accessed only from resources within the same VPC. This
means any function (provided it has
joinDefaultVpc
set to true), batch job or container workload within your stack can access the cluster. Additionally, IP addresses configured inwhitelistedIps
can also access the database (even from the internet). To disable this behavior, and enforce database isolation ONLY to the VPC, you can set theforceDisablePublicIp
property. - scoping-workloads-in-vpc - similar to vpc mode, but even more restrictive. In addition to being in the same VPC, the resources and hosts
accessing your database must also have sufficient IAM permissions (for functions, batch jobs and container workloads, these permissions
can be granted using
allowsAccessTo
oriamRoleStatements
in their configuration). Additionally, IP addresses configured inwhitelistedIps
can also access the database (even from the internet). To disable this behavior, and enforce database isolation, you can set theforceDisablePublicIp
property. - whitelisted-ips-only - The database can only be accessed from an IP addresses and CIDR blocks listed in the
whitelistedIps
list.
The AuroraServerlessEngine
does not support public IPs. Because of that, it only supports vpc
and scoping-workloads-in-vpc
modes.
In this case, interacting with your database from you own computer can be complicated. You can do it in 2 ways:
- Use Aurora Serverless Data Api. Unfortunately, the Data API isn't a full replacement for a normal database connection and can be slow.
- Use a bastion server. Native support for bastion servers in Stacktape will be available soon.
To learn more about VPCs, refer to VPC Docs.
Forcefully disables the public (internet) accessibility of the database endpoint
Type: boolean
- Used to increase the level of database isolation and to ensure NO connections are coming from outer internet.
You can only set this property during the first deployment of the stack (when the database is
created), not during stack update (subsequent deploys). Therefore, if you deploy a database with
a public IP, you CAN NOT disable its public IP in a subsequent deploy. Conversely, if the database
is deployed with disablePublicIp
set to true, the property cannot be changed in a subsequent deploys.
List of IP addresses or IP ranges (in CIDR format)
Type: Array of string
The behavior of this property varies based on accessibilityMode
:
- in the internet mode, this property has no effect as the database is are already accessible from everywhere.
- in the vpc mode and scoping-workloads-in-vpc mode, these IP addresses/ranges can be used to allow access from a specific addresses outside of the VPC (i.e IP address of your office).
- in the whitelisted-ips-only mode, these addresses/ranges are the only addresses that can access the database.
Internet mode
- Default mode.
- Least restrictive. The database can be accessed from anywhere on the internet.
VPC mode
- The database can be accessed only from resources within the default VPC.
- Any function (provided it has
joinDefaultVpc
set to true), batch job or container workload within your stack can access the database. - Additionally, IP addresses configured in
whitelistedIps
can also access the database (even from the internet). To disable this behavior, and enforce database isolation ONLY to the VPC, you can set theforceDisablePublicIp
property.
Copy
resources:myDatabase:type: relational-databaseproperties:credentials:masterUserName: adminmasterUserPassword: $Secret('dbPassword')engine:type: aurora-postgresqlproperties:instances:- instanceSize: db.t3.mediumport: 5432accessibility:accessibilityMode: vpcmyFunction:type: functionproperties:packaging:type: stacktape-lambda-buildpackproperties:entryfilePath: path/to/my/function.tsjoinDefaultVpc: true
Scoping workloads in VPC mode
- Similar to vpc mode, but even more restrictive. In addition to resource being in the VPC, any host or resource
trying to access your database must also have the sufficient IAM (Identity and Access management) permissions. You can
grant these permission to your workloads in 2 ways:
- configuring
allowAccessTo
on your workload (functions, container workloads, batch jobs) - configuring
iamRoleStatements
on your workload (functions, container workloads, batch jobs)
- configuring
- Additionally, IP addresses configured in
whitelistedIps
can also access the database (even from the internet). To disable this behavior, and enforce database isolation, you can set theforceDisablePublicIp
property.
Copy
resources:myDatabase:type: relational-databaseproperties:credentials:masterUserName: adminmasterUserPassword: $Secret('dbPassword')engine:type: aurora-postgresqlproperties:instances:- instanceSize: db.t3.mediumport: 5432accessibility:accessibilityMode: scoping-workloads-in-vpcmyFunction:type: functionproperties:packaging:type: stacktape-lambda-buildpackproperties:entryfilePath: path/to/my/function.tsjoinDefaultVpc: trueaccessControl:allowAccessTo:- myDatabase
Whitelisted IPs only mode
- The database can only be accessed from an IP addresses and CIDR blocks listed in the
whitelistedIps
list.
Copy
resources:myDatabase:type: relational-databaseproperties:credentials:masterUserName: adminmasterUserPassword: $Secret('dbPassword')engine:type: aurora-postgresqlproperties:instances:- instanceSize: db.t3.mediumport: 5432accessibility:accessibilityMode: whitelisted-ips-onlywhitelistedIps:- '147.25.33.12'
Referenceable parameters
The following parameters can be easily referenced using $ResourceParam directive directive.
To learn more about referencing parameters, refer to referencing parameters.
Fully-formed connection string that can be used to access the primary instance. Includes host, port, username, password and dbName.
- Usage:
$ResourceParam('<<resource-name>>', 'connectionString')
Fully-formed connection string in JDBC form that can be used to access the primary instance. Includes host, port, username, password and dbName.
- Usage:
$ResourceParam('<<resource-name>>', 'jdbcConnectionString')
Hostname (address) of the primary instance that can be used for both reads and writes.
- Usage:
$ResourceParam('<<resource-name>>', 'host')
Port of the database.
- Usage:
$ResourceParam('<<resource-name>>', 'port')
Name of the automatically created database (can be configured using the
dbName
property).- Usage:
$ResourceParam('<<resource-name>>', 'dbName')
Hostname (address) used for reads only. (only available for
aurora-postgresql
andaurora-mysql
engines). If you have multiple instances, it is advised to use readerHost for reads to offload the primary (read/write) host. ReaderHost automatically balances requests between available instances. Traffic is auto-balanced among available reader hosts.- Usage:
$ResourceParam('<<resource-name>>', 'readerHost')
Same as connectionString but targets readerHosts (only available for
aurora-postgresql
andaurora-mysql
engines). Traffic is auto-balanced among available reader hosts.- Usage:
$ResourceParam('<<resource-name>>', 'readerConnectionString')
Same as readerConnectionString but in JDBC format (only available for
aurora-postgresql
andaurora-mysql
engines).- Usage:
$ResourceParam('<<resource-name>>', 'readerJdbcConnectionString')
Comma-separated list of read replica hostnames (only available if read replicas are configured). Read replicas can only be used for read operations.
- Usage:
$ResourceParam('<<resource-name>>', 'readReplicaHosts')
Comma-separated list of connection strings (URLs) used to connect to read replicas (only available when read replicas are configured). Read replicas can only be used for read operations.
- Usage:
$ResourceParam('<<resource-name>>', 'readReplicaConnectionStrings')
Same as readReplicaConnectionStrings but in JDBC format (only available when read replicas are configured).
- Usage:
$ResourceParam('<<resource-name>>', 'readReplicaJdbcConnectionStrings')
Pricing
Pricing heavily dependes on the engine used.
RDS engines:
- Database server instance
- Price depends on the instance size and region. Allowed instances depend on the database type. Postgres instancesMySQL instances, Maria db instances, Oracle db, SQL server.
- Storage
- $0.115 - $0.238 per GB-month
- Backups:
- For automated backups with default retention setting (where you never store more than 100% of your total database storage), there is no additional charge.
- Additional backup storage is $0.095 per GB-month.
Aurora engines:
- Database server instance
- Price depends on the instance sizes and region. To see exact prices, refer to AWS pricing page
- Price starts at $0.073 / hour.
- Storage
- $0.10 - $0.19 per GB-month
- I/O Rate
- $0.20 - $0.28 per 1 million read/write operations
- Backups
- For automated backups with default retention setting (where you never store more than 100% of your total database storage), there is no additional charge.
- Additional backup storage is $0.021 - $0.037 per GB-month.
Aurora serverless:
- ACUs (Aurora capacity units)
- Each capacity unit has ~2GB of memory, ~1 Virtual CPU and corresponding network capabilities
- 1 ACU costs $0.06 - $0.10 (depending on region)
- Aurora Serverless databases can scale to 0 ACUs (with no costs)
- Storage, I/O Rate and Backups cost the same amount as Aurora non-serverless.
Data transfer charges (same for all engines).
- IN transfer: free
- OUT to VPC (subnet in the same Availability zone): free
- OUT to VPC (subnet in different Availability zone): $0.01 per GB ($0.02, because you are paying on both sides)
- OUT to Internet: first 1 GB free, then $0.09 -$0.15 per GB
FREE TIER (eligible for first 12 months)
- 750 Hours per month of db.t2.micro database usage (applicable DB engines)
- 20 GB of General Purpose (SSD) database storage \
- 20 GB of storage for database backups and DB Snapshots
API reference
No description
Type: string "relational-database"
Configures credentials for the database master user
Configures the underlying database engine and its properties
Type: (AuroraServerlessEngine or RdsEngine or AuroraEngine)
Database engine determines the properties of your database, such as number of instances, high availability capabilities, redundancy, performance, scaling behavior, pricing etc.
RdsEngine type
- Fully managed single-node database engine
- Configurable read replicas (additional parallelly-running, automatically-replicated instances used for read operations)
- Supported databases::
mysql
,mariadb
,postgres
,oracle
,sqlserver
AuroraEngine type
- Fully-managed AWS-developed engine with clustering support, high-availability, increased durability & performance.
- Compute instances (nodes) run in a single Availability Zone. Storage is automatically replicated 6-ways across 3 availability zones.
- Automatically load-balances read operations between nodes.
- Automatic failover - if a primary instance fails, one of the read replicas is elected as a new primary instance.
- Supported databases:
aurora-postgresql
,aurora-mysql
- To learn more about AuroraEngine, refer to AWS Docs
AuroraServerlessEngine type
- Fully-managed AWS-developed engine with clustering support, high-availability, increased durability & performance.
- Similar to AuroraEngine type, but automatically scales based on usage. Scaling is done using ACUs (Aurora Compute units).
- Each ACU has ~2GB of RAM and 1 virtual CPU.
- Can scale to 0 ACUs (database is paused, and you don't pay anything).
- Supported databases:
aurora-postgresql
,aurora-mysql
- To learn more about AuroraServerlessEngine, refer to AWS Docs
Configures which resources and hosts can access your database
Type: DatabaseAccessibility
Enables database deletion protection
Type: boolean
- By default, the database is not deletion-protected.
- If you wish to delete a database with
deletionProtection
enabled, you first need to explicitly disable the protection.
Configures how long the database backups will be retained (in days)
Type: number
- Databases are automatically backed up once a day.
- Maximum retention period is
35
days. - You can disable automated backups by setting the value to 0 (works only for RDS engines).
- You can also take manual backup snapshots (in the console or using the API). The retention is not applied to manual backups.
- By default, backups are retained for 1 day.
- To learn more about RDS engine backups, refer to RDS engine backups AWS Docs.
- To learn more about Aurora engine backups, refer to Aurora engine backups AWS Docs.
Overrides one or more properties of the specified child resource.
Type: Object
- Child resources are specified using their cloudformation logical id (e.g.
MyBucketBucket
). - To see all configurable child resources for given Stacktape resource, use
stacktape stack-info --detailed
command. - To see the list of properties that can be overridden, refer to AWS Cloudformation docs.
Configures the primary database instance
Type: RdsEnginePrimaryInstance
Configures the name of the default database in the database cluster
Type: string
Meaning of this parameter differs based on the database type:
mysql
: The name of the database to create when the DB instance is created. If this parameter is not specified, a database with name defdb is created.mariadb
: The name of the database to create when the DB instance is created. If this parameter is not specified, a database with name defdb is created.postgres
: The name of the database to create when the DB instance is created. If this parameter is not specified, a database with name defdb is created.oracle-se2
+oracle-ee
: The Oracle System ID (SID) of the created DB instance. If this parameter is not specified, a database with SID defdb is created.sqlserver-ee
+sqlserver-ex
+sqlserver-se
+sqlserver-web
: Not applicable. Must be null.
The port on which the database server will accept client connections.
Type: number
Default values differ based on engine:
mysql
+mariadb
: 3306postgres
: 5432oracle-se2
+oracle-ee
: 1521sqlserver-ee
+sqlserver-ex
+sqlserver-se
+sqlserver-web
: 1433
Configures the storage (disk size) for the database
Type: RdsEngineStorage
- When you run out of free database space, your storage will automatically scale up.
- By default, scales between 20GB and 200GB.
- The scaling process happens when the following conditions are met:
- Free available space` is less than 10 percent of the allocated storage
- The low-storage condition lasts at least five minutes.
- At least six hours have passed since the last storage modification.
- To learn more about storage autoscaling, refer to AWS Docs
List of read replicas (replicas of primary instance)
Type: Array of RdsEngineReadReplica
- Read replicas help to decrease the load on the primary instance by serving a read-only database requests.
- Replication uses database's native asynchronous replication to update the read replicas whenever there is a change to the primary instance.
- Each read replica has its own database endpoint.
Version of the database
Type: string
Configures logging behavior for the database
Type: RelationalDatabaseLogging
- By default, logging is enabled and logs are preserved for
90
days. - Logged data depend on the used
engine
. You can log information about connections, disconnections, executed queries & much more.
List of database instances that make up the Aurora cluster
Type: Array of AuroraEngineInstance
- First instance in this list is by default a primary instance, which can be used for both reads and writes.
- Rest of the instances can be used for reads only.
- Aurora cluster automatically balances read request between all of the instances.
- In a case of a primary instance failure, Aurora cluster selects another instance to be the primary instance.
Configures the name of the default database in the database cluster
Type: string
By default, a database with name defdb is created.
The port on which the database server will accept connections.
Type: number
Default values differ based on engine:
aurora-mysql
: 3306aurora-postgresql
: 5432
Version of the database
Type: string
Configures logging behavior for the database
Type: RelationalDatabaseLogging
- By default, logging is enabled and logs are preserved for
90
days. - Logged data depend on the used
engine
. You can log information about connections, disconnections, executed queries & much more.
Configures the name of the default database in the database cluster
Type: string
By default, a database with name defdb is created.
The minimum capacity units the database can scale down to
Type: number
- Serverless databases use ACUs (or Aurora Capacity Units) to measure database capacity. Each ACU has approximately 2 GB of memory with corresponding CPU and networking resources.
- Allowed values:
- For aurora-mysql-serverless:
1
,2
,4
,8
,16
,32
,64
,128
, and256
. - For aurora-postgres-serverless:
2
,4
,8
,16
,32
,64
,128
, and256
.
- For aurora-mysql-serverless:
The maximum capacity units the database can scale up to
Type: number
- Serverless databases use ACUs (or Aurora Capacity Units) to measure database capacity. Each ACU has approximately 2 GB of memory with corresponding CPU and networking resources.
- Allowed values:
- For aurora-mysql-serverless:
1
,2
,4
,8
,16
,32
,64
,128
, and256
. - For aurora-postgres-serverless:
2
,4
,8
,16
,32
,64
,128
, and256
.
- For aurora-mysql-serverless:
Time in seconds after the idle serverless database is paused
Type: number
- Database is considered idle when it has no active connections.
- By default, the database is never paused (it is kept at minimal capacity).
- Allowed values are between
300
(5 minutes) and86400
(24 hours).
Version of the database
Type: string
Configures logging behavior for the database
Type: RelationalDatabaseLogging
- By default, logging is enabled and logs are preserved for
90
days. - Logged data depend on the used
engine
. You can log information about connections, disconnections, executed queries & much more.
If set to true, database logs all new client connection details
Type: boolean
If set to true, database logs all client disconnections
Type: boolean
If set to true, database logs sessions that are stuck in a locked state
Type: boolean
Helps determine if session locking is causing a performance issue.
Sets time threshold for logging statements. Every statement exceeding specified time will be logged.
Type: number
-1
disables this feature0
all statements are logged (because threshold is set to 0)- any positive number specifies amount of ms (milliseconds). if statement takes more more than this amount of ms, it is logged.
- helpful when optimizing slow queries in your database.
Controls which sql statements are logged by default
Type: string ENUM
Possible values: allddlmodnone
- “none” - No statements are logged.
- “ddl” - Logs all DDL statements (CREATE, ALTER, and so on).
- “mod” - Logs all DDL statements + INSERT, UPDATE, and DELETE statements.
- “all” - Logs all statements.
Types of activity to record in the audit log.
Type: Array of string ENUM
Possible values: CONNECTQUERYQUERY_DCLQUERY_DDLQUERY_DMLQUERY_DML_NO_SELECT
- CONNECT: Log successful and unsuccessful connections to the database, and disconnections from the database.
- QUERY: Log the text of all queries run against the database.
- QUERY_DDL: Similar to the QUERY event, but returns only data definition language (DDL) queries (CREATE, ALTER, and so on).
- QUERY_DML: Similar to the QUERY event, but returns only data manipulation language (DML) queries (INSERT, UPDATE, and so on, and also SELECT).
- QUERY_DML_NO_SELECT: Similar to the QUERY_DML event, but doesn't log SELECT queries.
- QUERY_DCL: Similar to the QUERY event, but returns only data control language (DCL) queries (GRANT, REVOKE, and so on).
Sets time threshold for logging slow statement into slowquery log
Type: number
-1
disables long query logging- To prevent fast-running queries from being logged in the slow query log, specify a value for the shortest query run time to be logged, in seconds.
- helpful when optimizing slow queries in your database.
- log are sent into
slowquery
log type group