Relational (SQL) Databases



Stacktape allows you to deploy a fully managed relational (SQL) database, with support for PostgreSQL, MySQL, MariaDB, Oracle, and SQL Server. The service handles capacity scaling, hardware provisioning, database setup, patching, logging, and backups, so you can focus on your application.

Under the hood, Stacktape uses Amazon RDS. It supports three engine categories with different topologies and scaling behaviors:

  • Basic RDS engines: A single-node database that is the most cost-effective option. It supports optional read replicas for higher performance and a Multi-AZ standby instance for resilience.
  • Aurora engine: A multi-node, highly available cluster with increased durability and fault tolerance. It automatically balances read requests across nodes for better performance.
  • Aurora Serverless engine: Similar to the Aurora engine, but with automatic, usage-based scaling. It can scale down to zero when inactive, saving costs.

Databases are always deployed in a private network within your stack's VPC. You can configure accessibility to control whether the database is accessible from the internet or only from other resources in the VPC.

Basic usage

To connect to a relational database, you typically use a connection string. Stacktape can automatically inject the necessary credentials and connection details into your application's environment when you use the connectTo property.

resources:
  myDatabase:
    type: relational-database
    properties:
      credentials:
        masterUserPassword: $Secret('database.password')
      engine:
        type: postgres
        properties:
          version: '16.2'
          primaryInstance:
            instanceSize: db.t3.micro

  apiServer:
    type: multi-container-workload
    properties:
      resources:
        cpu: 1
        memory: 1024
      containers:
        - name: api-container
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: src/main.ts
      connectTo:
        - myDatabase

A single-node PostgreSQL database.

import express from 'express';
import { Pool } from 'pg';

const pgPool = new Pool({
  connectionString: process.env.STP_MY_DATABASE_CONNECTION_STRING // env variable was automatically injected by Stacktape
});

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');
});

A container workload connecting to the database.

Database credentials

You can configure the credentials for the database's master user. It's recommended to use a secret to manage these credentials securely.

resources:
  myRelationalDatabase:
    type: relational-database
    properties:
      credentials:
        masterUserName: $File('.env').DB_USER_NAME # OPTIONAL
        masterUserPassword: $Secret('dbCredentials.password')
      engine:
        type: postgres
        properties:
          version: '16.2'
          port: 5432
          primaryInstance:
            instanceSize: db.t2.micro
RelationalDatabaseCredentialsAPI referenceParent:RelationalDatabase
masterUserPasswordRequired

Admin password. Avoid special characters: []{}(),;?*=!@.

Type: string

Use $Secret() to store it securely instead of hardcoding:

masterUserPassword: $Secret('database.password')
masterUserNameDefault: db_master_user

Admin username. Avoid special characters: []{}(),;?*=!@.

Type: string

Warning: Changing this after creation replaces the database and deletes all data.

Engine

The database engine determines the database type, performance, availability, and pricing.

Depending on the properties they provide, we group engine types into following groups:

  • RDS Engine group - single node fully managed databases.
    • Supported engines:
      • postgres
      • mysql
      • mariadb
      • oracle-ee
      • oracle-se2
      • sqlserver-ee
      • sqlserver-ex
      • sqlserver-se
      • sqlserver-web
  • Aurora Engine group - multi node highly available cluster with replicated storage.
    • Supported engines:
      • aurora-postgresql
      • aurora-mysql
  • Aurora Serverless V2 Engine - serverless engine with replicated storage. Compute resources scale based on actual demand.
    • Supported engines:
      • aurora-postgresql-serverless-v2
      • aurora-mysql-serverless-v2

Engine version

You must choose a version that is compatible with your chosen engine.

resources:
  myDatabase:
    type: relational-database
    properties:
      credentials:
        masterUserPassword: $Secret('dbPassword')
      engine:
        type: postgres
        properties:
          version: '16.2'
          port: 5432
          primaryInstance:
            instanceSize: db.t3.micro

Available versions

aurora-mysql
  • 8.0.mysql_aurora.3.11.1
  • 8.0.mysql_aurora.3.11.0
  • 8.0.mysql_aurora.3.10.3
  • 8.0.mysql_aurora.3.10.2
  • 8.0.mysql_aurora.3.10.1
  • 8.0.mysql_aurora.3.10.0
  • 8.0.mysql_aurora.3.09.0
  • 8.0.mysql_aurora.3.08.2
  • 8.0.mysql_aurora.3.08.1
  • 8.0.mysql_aurora.3.08.0
  • 8.0.mysql_aurora.3.04.6
  • 8.0.mysql_aurora.3.04.4
  • 8.0.mysql_aurora.3.04.3
  • 8.0.mysql_aurora.3.04.2
  • 8.0.mysql_aurora.3.04.1
  • 8.0.mysql_aurora.3.04.0
  • 5.7.mysql_aurora.2.12.5
  • 5.7.mysql_aurora.2.12.4
  • 5.7.mysql_aurora.2.12.3
  • 5.7.mysql_aurora.2.12.2
  • 5.7.mysql_aurora.2.12.1
  • 5.7.mysql_aurora.2.12.0
  • 5.7.mysql_aurora.2.11.6
  • 5.7.mysql_aurora.2.11.5
  • 5.7.mysql_aurora.2.11.4
  • 5.7.mysql_aurora.2.11.3
  • 5.7.mysql_aurora.2.11.2
  • 5.7.mysql_aurora.2.11.1
aurora-mysql-serverless-v2
  • 8.0.mysql_aurora.3.11.1
  • 8.0.mysql_aurora.3.11.0
  • 8.0.mysql_aurora.3.10.3
  • 8.0.mysql_aurora.3.10.2
  • 8.0.mysql_aurora.3.10.1
  • 8.0.mysql_aurora.3.10.0
  • 8.0.mysql_aurora.3.09.0
  • 8.0.mysql_aurora.3.08.2
  • 8.0.mysql_aurora.3.08.1
  • 8.0.mysql_aurora.3.08.0
aurora-postgresql
  • 17.7
  • 17.6
  • 17.5
  • 17.4
  • 16.11
  • 16.10
  • 16.9-limitless
  • 16.9
  • 16.8-limitless
  • 16.8
  • 16.6-limitless
  • 16.6
  • 16.4-limitless
  • 16.4
  • 15.15
  • 15.14
  • 15.13
  • 15.12
  • 15.10
  • 15.8
  • 14.20
  • 14.19
  • 14.18
  • 14.17
  • 14.15
  • 14.13
  • 14.6
  • 13.23
  • 13.22
  • 13.21
  • 13.20
  • 13.18
  • 13.16
  • 13.9
  • 12.22
  • 12.9
  • 11.21
  • 11.9
aurora-postgresql-serverless-v2
  • 16.11
  • 16.10
  • 15.15
  • 15.14
  • 15.13
  • 15.12
  • 15.10
  • 14.20
  • 14.19
  • 14.18
  • 14.17
  • 14.15
  • 14.13
  • 13.23
  • 13.22
  • 13.21
  • 13.20
  • 13.18
  • 13.16
mariadb
  • 11.8.5
  • 11.8.3
  • 11.4.9
  • 11.4.8
  • 11.4.7
  • 11.4.5
  • 11.4.4
  • 11.4.3
  • 10.11.15
  • 10.11.14
  • 10.11.13
  • 10.11.11
  • 10.11.10
  • 10.11.9
  • 10.6.24
  • 10.6.23
  • 10.6.22
  • 10.6.21
  • 10.6.20
  • 10.6.19
  • 10.5.29
  • 10.5.28
  • 10.5.27
mysql
  • 8.4.8
  • 8.4.7
  • 8.4.6
  • 8.4.5
  • 8.4.4
  • 8.4.3
  • 8.0.45
  • 8.0.44
  • 8.0.43
  • 8.0.42
  • 8.0.41
  • 8.0.40
  • 5.7.44-rds.20251212
  • 5.7.44-rds.20250818
  • 5.7.44-rds.20250508
  • 5.7.44-rds.20250213
  • 5.7.44-rds.20250103
  • 5.7.44-rds.20240808
  • 5.7.44-rds.20240529
  • 5.7.44-rds.20240408
oracle-ee
  • 19.0.0.0.ru-2025-10.spb-1.r1
  • 19.0.0.0.ru-2025-10.rur-2025-10.r1
  • 19.0.0.0.ru-2025-07.spb-1.r1
  • 19.0.0.0.ru-2025-07.rur-2025-07.r1
  • 19.0.0.0.ru-2025-04.spb-1.r1
  • 19.0.0.0.ru-2025-04.rur-2025-04.r1
  • 19.0.0.0.ru-2025-01.rur-2025-01.r2
  • 19.0.0.0.ru-2025-01.spb-1.r1
  • 19.0.0.0.ru-2025-01.rur-2025-01.r1
  • 19.0.0.0.ru-2024-10.rur-2024-10.r1
  • 19.0.0.0.ru-2024-07.rur-2024-07.r1
  • 19.0.0.0.ru-2024-04.rur-2024-04.r1
  • 19.0.0.0.ru-2024-01.rur-2024-01.r1
  • 19.0.0.0.ru-2023-10.rur-2023-10.r1
  • 19.0.0.0.ru-2023-07.rur-2023-07.r1
  • 19.0.0.0.ru-2023-04.rur-2023-04.r1
  • 19.0.0.0.ru-2023-01.rur-2023-01.r2
  • 19.0.0.0.ru-2023-01.rur-2023-01.r1
  • 19.0.0.0.ru-2022-10.rur-2022-10.r1
  • 19.0.0.0.ru-2022-07.rur-2022-07.r1
  • 19.0.0.0.ru-2022-04.rur-2022-04.r1
  • 19.0.0.0.ru-2022-01.rur-2022-01.r1
  • 19.0.0.0.ru-2021-10.rur-2021-10.r1
  • 19.0.0.0.ru-2021-07.rur-2021-07.r1
  • 19.0.0.0.ru-2021-04.rur-2021-04.r1
  • 19.0.0.0.ru-2021-01.rur-2021-01.r2
  • 19.0.0.0.ru-2021-01.rur-2021-01.r1
  • 19.0.0.0.ru-2020-10.rur-2020-10.r1
  • 19.0.0.0.ru-2020-07.rur-2020-07.r1
  • 19.0.0.0.ru-2020-04.rur-2020-04.r1
oracle-se2
  • 19.0.0.0.ru-2025-10.spb-1.r1
  • 19.0.0.0.ru-2025-10.rur-2025-10.r1
  • 19.0.0.0.ru-2025-07.spb-1.r1
  • 19.0.0.0.ru-2025-07.rur-2025-07.r1
  • 19.0.0.0.ru-2025-04.spb-1.r1
  • 19.0.0.0.ru-2025-04.rur-2025-04.r1
  • 19.0.0.0.ru-2025-01.rur-2025-01.r2
  • 19.0.0.0.ru-2025-01.spb-1.r1
  • 19.0.0.0.ru-2025-01.rur-2025-01.r1
  • 19.0.0.0.ru-2024-10.rur-2024-10.r1
  • 19.0.0.0.ru-2024-07.rur-2024-07.r1
  • 19.0.0.0.ru-2024-04.rur-2024-04.r1
  • 19.0.0.0.ru-2024-01.rur-2024-01.r1
  • 19.0.0.0.ru-2023-10.rur-2023-10.r1
  • 19.0.0.0.ru-2023-07.rur-2023-07.r1
  • 19.0.0.0.ru-2023-04.rur-2023-04.r1
  • 19.0.0.0.ru-2023-01.rur-2023-01.r2
  • 19.0.0.0.ru-2023-01.rur-2023-01.r1
  • 19.0.0.0.ru-2022-10.rur-2022-10.r1
  • 19.0.0.0.ru-2022-07.rur-2022-07.r1
  • 19.0.0.0.ru-2022-04.rur-2022-04.r1
  • 19.0.0.0.ru-2022-01.rur-2022-01.r1
  • 19.0.0.0.ru-2021-10.rur-2021-10.r1
  • 19.0.0.0.ru-2021-07.rur-2021-07.r1
  • 19.0.0.0.ru-2021-04.rur-2021-04.r1
  • 19.0.0.0.ru-2021-01.rur-2021-01.r2
  • 19.0.0.0.ru-2021-01.rur-2021-01.r1
  • 19.0.0.0.ru-2020-10.rur-2020-10.r1
  • 19.0.0.0.ru-2020-07.rur-2020-07.r1
  • 19.0.0.0.ru-2020-04.rur-2020-04.r1
postgres
  • 18.1
  • 17.7
  • 17.6
  • 17.5
  • 17.4
  • 17.2
  • 16.11
  • 16.10
  • 16.9
  • 16.8
  • 16.6
  • 15.15
  • 15.14
  • 15.13
  • 15.12
  • 15.10
  • 14.20
  • 14.19
  • 14.18
  • 14.17
  • 14.15
  • 13.23
  • 13.22
  • 13.21
  • 13.20
  • 13.18
  • 12.22-rds.20251114
  • 12.22-rds.20250814
  • 12.22-rds.20250508
  • 12.22-rds.20250220
  • 12.22
  • 11.22-rds.20251114
  • 11.22-rds.20250814
  • 11.22-rds.20250508
  • 11.22-rds.20250220
  • 11.22-rds.20241121
sqlserver-ee
  • 16.00.4225.2.v1
  • 16.00.4215.2.v1
  • 16.00.4210.1.v1
  • 16.00.4205.1.v1
  • 16.00.4195.2.v1
  • 16.00.4185.3.v1
  • 16.00.4175.1.v1
  • 16.00.4165.4.v1
  • 16.00.4150.1.v1
  • 16.00.4140.3.v1
  • 16.00.4135.4.v1
  • 16.00.4131.2.v1
  • 16.00.4125.3.v1
  • 16.00.4120.1.v1
  • 16.00.4115.5.v1
  • 16.00.4105.2.v1
  • 16.00.4095.4.v1
  • 16.00.4085.2.v1
  • 15.00.4455.2.v1
  • 15.00.4445.1.v1
  • 15.00.4440.1.v1
  • 15.00.4435.7.v1
  • 15.00.4430.1.v1
  • 15.00.4420.2.v1
  • 15.00.4415.2.v1
  • 15.00.4410.1.v1
  • 15.00.4395.2.v1
  • 15.00.4390.2.v1
  • 15.00.4385.2.v1
  • 15.00.4382.1.v1
  • 15.00.4375.4.v1
  • 15.00.4365.2.v1
  • 15.00.4355.3.v1
  • 15.00.4345.5.v1
  • 15.00.4335.1.v1
  • 15.00.4322.2.v1
  • 15.00.4316.3.v1
  • 15.00.4312.2.v1
  • 15.00.4236.7.v1
  • 15.00.4198.2.v1
  • 15.00.4153.1.v1
  • 15.00.4073.23.v1
  • 15.00.4043.16.v1
  • 14.00.3515.1.v1
  • 14.00.3505.1.v1
  • 14.00.3500.1.v1
  • 14.00.3495.9.v1
  • 14.00.3485.1.v1
  • 14.00.3480.1.v1
  • 14.00.3475.1.v1
  • 14.00.3471.2.v1
  • 14.00.3465.1.v1
  • 14.00.3460.9.v1
  • 14.00.3451.2.v1
  • 14.00.3421.10.v1
  • 14.00.3401.7.v1
  • 14.00.3381.3.v1
  • 14.00.3356.20.v1
  • 14.00.3294.2.v1
  • 14.00.3281.6.v1
sqlserver-ex
  • 16.00.4225.2.v1
  • 16.00.4215.2.v1
  • 16.00.4210.1.v1
  • 16.00.4205.1.v1
  • 16.00.4195.2.v1
  • 16.00.4185.3.v1
  • 16.00.4175.1.v1
  • 16.00.4165.4.v1
  • 16.00.4150.1.v1
  • 16.00.4140.3.v1
  • 16.00.4135.4.v1
  • 16.00.4131.2.v1
  • 16.00.4125.3.v1
  • 16.00.4120.1.v1
  • 16.00.4115.5.v1
  • 16.00.4105.2.v1
  • 16.00.4095.4.v1
  • 16.00.4085.2.v1
  • 15.00.4455.2.v1
  • 15.00.4445.1.v1
  • 15.00.4440.1.v1
  • 15.00.4435.7.v1
  • 15.00.4430.1.v1
  • 15.00.4420.2.v1
  • 15.00.4415.2.v1
  • 15.00.4410.1.v1
  • 15.00.4395.2.v1
  • 15.00.4390.2.v1
  • 15.00.4385.2.v1
  • 15.00.4382.1.v1
  • 15.00.4375.4.v1
  • 15.00.4365.2.v1
  • 15.00.4355.3.v1
  • 15.00.4345.5.v1
  • 15.00.4335.1.v1
  • 15.00.4322.2.v1
  • 15.00.4316.3.v1
  • 15.00.4312.2.v1
  • 15.00.4236.7.v1
  • 15.00.4198.2.v1
  • 15.00.4153.1.v1
  • 15.00.4073.23.v1
  • 15.00.4043.16.v1
  • 14.00.3515.1.v1
  • 14.00.3505.1.v1
  • 14.00.3500.1.v1
  • 14.00.3495.9.v1
  • 14.00.3485.1.v1
  • 14.00.3480.1.v1
  • 14.00.3475.1.v1
  • 14.00.3471.2.v1
  • 14.00.3465.1.v1
  • 14.00.3460.9.v1
  • 14.00.3451.2.v1
  • 14.00.3421.10.v1
  • 14.00.3401.7.v1
  • 14.00.3381.3.v1
  • 14.00.3356.20.v1
  • 14.00.3294.2.v1
  • 14.00.3281.6.v1
sqlserver-se
  • 16.00.4225.2.v1
  • 16.00.4215.2.v1
  • 16.00.4210.1.v1
  • 16.00.4205.1.v1
  • 16.00.4195.2.v1
  • 16.00.4185.3.v1
  • 16.00.4175.1.v1
  • 16.00.4165.4.v1
  • 16.00.4150.1.v1
  • 16.00.4140.3.v1
  • 16.00.4135.4.v1
  • 16.00.4131.2.v1
  • 16.00.4125.3.v1
  • 16.00.4120.1.v1
  • 16.00.4115.5.v1
  • 16.00.4105.2.v1
  • 16.00.4095.4.v1
  • 16.00.4085.2.v1
  • 15.00.4455.2.v1
  • 15.00.4445.1.v1
  • 15.00.4440.1.v1
  • 15.00.4435.7.v1
  • 15.00.4430.1.v1
  • 15.00.4420.2.v1
  • 15.00.4415.2.v1
  • 15.00.4410.1.v1
  • 15.00.4395.2.v1
  • 15.00.4390.2.v1
  • 15.00.4385.2.v1
  • 15.00.4382.1.v1
  • 15.00.4375.4.v1
  • 15.00.4365.2.v1
  • 15.00.4355.3.v1
  • 15.00.4345.5.v1
  • 15.00.4335.1.v1
  • 15.00.4322.2.v1
  • 15.00.4316.3.v1
  • 15.00.4312.2.v1
  • 15.00.4236.7.v1
  • 15.00.4198.2.v1
  • 15.00.4153.1.v1
  • 15.00.4073.23.v1
  • 15.00.4043.16.v1
  • 14.00.3515.1.v1
  • 14.00.3505.1.v1
  • 14.00.3500.1.v1
  • 14.00.3495.9.v1
  • 14.00.3485.1.v1
  • 14.00.3480.1.v1
  • 14.00.3475.1.v1
  • 14.00.3471.2.v1
  • 14.00.3465.1.v1
  • 14.00.3460.9.v1
  • 14.00.3451.2.v1
  • 14.00.3421.10.v1
  • 14.00.3401.7.v1
  • 14.00.3381.3.v1
  • 14.00.3356.20.v1
  • 14.00.3294.2.v1
  • 14.00.3281.6.v1
sqlserver-web
  • 16.00.4225.2.v1
  • 16.00.4215.2.v1
  • 16.00.4210.1.v1
  • 16.00.4205.1.v1
  • 16.00.4195.2.v1
  • 16.00.4185.3.v1
  • 16.00.4175.1.v1
  • 16.00.4165.4.v1
  • 16.00.4150.1.v1
  • 16.00.4140.3.v1
  • 16.00.4135.4.v1
  • 16.00.4131.2.v1
  • 16.00.4125.3.v1
  • 16.00.4120.1.v1
  • 16.00.4115.5.v1
  • 16.00.4105.2.v1
  • 16.00.4095.4.v1
  • 16.00.4085.2.v1
  • 15.00.4455.2.v1
  • 15.00.4445.1.v1
  • 15.00.4440.1.v1
  • 15.00.4435.7.v1
  • 15.00.4430.1.v1
  • 15.00.4420.2.v1
  • 15.00.4415.2.v1
  • 15.00.4410.1.v1
  • 15.00.4395.2.v1
  • 15.00.4390.2.v1
  • 15.00.4385.2.v1
  • 15.00.4382.1.v1
  • 15.00.4375.4.v1
  • 15.00.4365.2.v1
  • 15.00.4355.3.v1
  • 15.00.4345.5.v1
  • 15.00.4335.1.v1
  • 15.00.4322.2.v1
  • 15.00.4316.3.v1
  • 15.00.4312.2.v1
  • 15.00.4236.7.v1
  • 15.00.4198.2.v1
  • 15.00.4153.1.v1
  • 15.00.4073.23.v1
  • 15.00.4043.16.v1
  • 14.00.3515.1.v1
  • 14.00.3505.1.v1
  • 14.00.3500.1.v1
  • 14.00.3495.9.v1
  • 14.00.3485.1.v1
  • 14.00.3480.1.v1
  • 14.00.3475.1.v1
  • 14.00.3471.2.v1
  • 14.00.3465.1.v1
  • 14.00.3460.9.v1
  • 14.00.3451.2.v1
  • 14.00.3421.10.v1
  • 14.00.3401.7.v1
  • 14.00.3381.3.v1
  • 14.00.3356.20.v1
  • 14.00.3294.2.v1
  • 14.00.3281.6.v1

RDS engine

The RDS engine is the default, single-node, and most cost-effective option. While it's not highly available by default, you can configure a standby instance in a different Availability Zone or add read replicas to improve performance and resilience.

RdsEngineAPI referenceParent:RelationalDatabase
typeRequired
No description

Type: string ENUM

Possible values: mariadbmysqloracle-eeoracle-se2postgressqlserver-eesqlserver-exsqlserver-sesqlserver-web

properties.primaryInstanceRequired

The primary (writer) instance. Handles all write operations.

Type: RdsEnginePrimaryInstance

properties.versionRequired

Engine version (e.g., 16.6 for PostgreSQL, 8.0.36 for MySQL).

Type: string

properties.dbName

Name of the database created on initialization. For Oracle, this is the SID. Not applicable to SQL Server.

Type: string

properties.port

Port the database listens on. Defaults: PostgreSQL 5432, MySQL/MariaDB 3306, Oracle 1521, SQL Server 1433.

Type: number

properties.storage

Storage configuration. Auto-scales up when free space is low.

Type: RdsEngineStorage

properties.readReplicas

Read replicas to offload read traffic from the primary instance.

Type: Array of RdsEngineReadReplica

Each replica gets its own endpoint. Data is replicated asynchronously from the primary.

properties.disableAutoMinorVersionUpgrade

Skip automatic minor version upgrades (e.g., 16.4 → 16.5).

Type: boolean

Instance size

You can configure the instance size for both the primary instance and its read replicas.

Determines CPU, memory, and network capacity. Quick guide:

  • db.t4g.micro (~$12/mo): Dev/testing, 2 vCPU, 1 GB RAM
  • db.t4g.medium (~$50/mo): Small production, 2 vCPU, 4 GB RAM
  • db.r6g.large (~$180/mo): Production, 2 vCPU, 16 GB RAM

t family instances are burstable (fine for low/variable load). Use r family for steady workloads.

resources:
  myDatabase:
    type: relational-database
    properties:
      credentials:
        masterUserPassword: $Secret('dbPassword')
      engine:
        type: postgres
        properties:
          version: '16.2'
          port: 5432
          primaryInstance:
            instanceSize: db.t3.micro

Multi-AZ mode

You can enable Multi-AZ mode for both primary instances and read replicas.

If the primary goes down, traffic fails over to the standby automatically. Also reduces downtime during maintenance. Doubles the instance cost.

resources:
  myDatabase:
    type: relational-database
    properties:
      credentials:
        masterUserPassword: $Secret('dbPassword')
      engine:
        type: postgres
        properties:
          version: '16.2'
          port: 5432
          primaryInstance:
            instanceSize: db.t2.micro
            multiAz: true
RdsEnginePrimaryInstanceAPI referenceParent:RdsEngineProperties
instanceSizeRequired

Instance size (e.g., db.t4g.micro, db.r6g.large).

Type: string

Determines CPU, memory, and network capacity. Quick guide:

  • db.t4g.micro (~$12/mo): Dev/testing, 2 vCPU, 1 GB RAM
  • db.t4g.medium (~$50/mo): Small production, 2 vCPU, 4 GB RAM
  • db.r6g.large (~$180/mo): Production, 2 vCPU, 16 GB RAM

t family instances are burstable (fine for low/variable load). Use r family for steady workloads.

multiAz

Create a standby replica in another availability zone for automatic failover.

Type: boolean

If the primary goes down, traffic fails over to the standby automatically. Also reduces downtime during maintenance. Doubles the instance cost.

Read replicas

Each replica gets its own endpoint. Data is replicated asynchronously from the primary.

resources:
  myDatabase:
    type: relational-database
    properties:
      credentials:
        masterUserPassword: $Secret('dbPassword')
      engine:
        type: postgres
        properties:
          version: '16.2'
          port: 5432
          primaryInstance:
            instanceSize: db.t3.micro
          readReplicas:
            - instanceSize: db.t3.micro
            - instanceSize: db.t3.micro
RdsEngineReadReplicaAPI referenceParent:RdsEngineProperties
instanceSizeRequired

Instance size (e.g., db.t4g.micro, db.r6g.large).

Type: string

Determines CPU, memory, and network capacity. Quick guide:

  • db.t4g.micro (~$12/mo): Dev/testing, 2 vCPU, 1 GB RAM
  • db.t4g.medium (~$50/mo): Small production, 2 vCPU, 4 GB RAM
  • db.r6g.large (~$180/mo): Production, 2 vCPU, 16 GB RAM

t family instances are burstable (fine for low/variable load). Use r family for steady workloads.

multiAz

Create a standby replica in another availability zone for automatic failover.

Type: boolean

If the primary goes down, traffic fails over to the standby automatically. Also reduces downtime during maintenance. Doubles the instance cost.

Storage

Storage configuration. Auto-scales up when free space is low.

resources:
  myDatabase:
    type: relational-database
    properties:
      credentials:
        masterUserPassword: $Secret('dbPassword')
      engine:
        type: postgres
        properties:
          version: '16.2'
          port: 5432
          primaryInstance:
            instanceSize: db.t3.micro
          storage:
            initialSize: 40
            maxSize: 400
RdsEngineStorageAPI referenceParent:RdsEngineProperties
initialSizeDefault: 20

Initial storage in GB. Auto-scales up when free space is low.

Type: number

maxSizeDefault: 200

Max storage in GB. The database won't auto-scale beyond this.

Type: number


Aurora engine

The Aurora engine is a fully managed, AWS-developed database engine that offers clustering, high availability, and increased performance. It replicates storage six ways across three Availability Zones and automatically load-balances read operations between nodes. If a primary instance fails, a read replica is automatically promoted to take its place.

resources:
  auroraSlsPostgres:
    type: relational-database
    properties:
      credentials:
        masterUserPassword: $Secret('dbSecret.password')
      engine:
        type: aurora-postgresql
        properties:
          version: '16.2'
          instances:
            - instanceSize: db.t3.medium
          port: 5432
AuroraEngineAPI referenceParent:RelationalDatabase
typeRequired
No description

Type: string ENUM

Possible values: aurora-mysqlaurora-postgresql

properties.instancesRequired

Cluster instances. First = primary (writer), rest = read replicas.

Type: Array of AuroraEngineInstance

Reads are load-balanced across all instances. If the primary fails, a replica is automatically promoted (usually within 30 seconds).

properties.versionRequired

Engine version (e.g., 16.6 for PostgreSQL, 8.0.36 for MySQL).

Type: string

properties.dbNameDefault: defdb

Name of the initial database.

Type: string

properties.port

Port. Defaults: aurora-mysql 3306, aurora-postgresql 5432.

Type: number

properties.disableAutoMinorVersionUpgrade

Skip automatic minor version upgrades (e.g., 16.4 → 16.5).

Type: boolean

AuroraEngineInstanceAPI referenceParent:AuroraEngineProperties
instanceSizeRequired

Instance size (e.g., db.t4g.medium, db.r6g.large).

Type: string

t family = burstable (dev/low-traffic). r family = memory-optimized (production).


Aurora Serverless V2 engine

The Aurora Serverless V2 engine is similar to the standard Aurora engine but adds automatic, usage-based scaling. It's more responsive and less disruptive when scaling than the V1 engine. The database can scale down to zero, so you don't pay for compute capacity when it's not in use.

Scaling is measured in Aurora Capacity Units (ACUs), where each ACU provides approximately 2GB of RAM and one virtual CPU.

AuroraServerlessV2EngineAPI referenceParent:RelationalDatabase
typeRequired
No description

Type: string ENUM

Possible values: aurora-mysql-serverless-v2aurora-postgresql-serverless-v2

properties.versionRequired

Engine version (e.g., 16.6 for PostgreSQL, 8.0.36 for MySQL).

Type: string

properties.dbNameDefault: defdb

Name of the initial database.

Type: string

properties.minCapacityDefault: 0.5

Minimum ACUs (0.5-128 in 0.5 increments). ~1 ACU ≈ 2 GB RAM.

Type: number

Set low (0.5) for dev/staging to minimize cost. The database scales up instantly under load.

properties.maxCapacityDefault: 10

Maximum ACUs (0.5-128 in 0.5 increments). Caps your scaling and cost.

Type: number

properties.serverlessReadersCount

Number of reader instances in the Aurora Serverless v2 cluster.

Type: number

Aurora Serverless v2 always has one writer instance. This value adds additional readers (0 means writer only, 2 means writer + 2 readers).

properties.disableAutoMinorVersionUpgrade

Skip automatic minor version upgrades (e.g., 16.4 → 16.5).

Type: boolean

resources:
  myDatabase:
    type: relational-database
    properties:
      credentials:
        masterUserPassword: $Secret('dbSecret.password')
      engine:
        type: aurora-postgresql-serverless-v2
        properties:
          version: '16.4'
          maxCapacity: 8

Backups

Days to keep automated daily backups (0-35). Set to 0 to disable (RDS only).

resources:
  myDatabase:
    type: relational-database
    properties:
      credentials:
        masterUserPassword: my_secret_password
      engine:
        type: postgres
        properties:
          version: '16.2'
          primaryInstance:
            instanceSize: db.t3.micro
      automatedBackupRetentionDays: 5

Logging

Logs are sent to CloudWatch and retained for 90 days by default. Available log types vary by engine.

RelationalDatabaseLoggingAPI referenceParent:RelationalDatabase
disabled

Disable CloudWatch logging entirely.

Type: boolean

retentionDaysDefault: 90

How many days to keep logs.

Type: number ENUM

Possible values: 13571430609012015018036540054573118273653

logTypes

Which log types to export. Depends on engine:

  • PostgreSQL: postgresql
  • MySQL/MariaDB: audit, error, general, slowquery
  • Oracle: alert, audit, listener, trace
  • SQL Server: agent, error

Type: Array of string

engineSpecificOptions

Fine-grained logging settings (PostgreSQL: slow queries, statements; MySQL: audit events).

Type: PostgresLoggingOptions or MysqlLoggingOptions

logForwarding

Forward logs to an external service (Datadog, Highlight.io, or any HTTP endpoint).

Type: HttpEndpointLogForwarding or HighlightLogForwarding or DatadogLogForwarding

Uses Kinesis Data Firehose (~$0.03/GB). Failed deliveries go to a backup S3 bucket.

resources:
  myDatabase:
    type: relational-database
    properties:
      credentials:
        masterUserPassword: my_secret_password
      engine:
        type: postgres
        properties:
          version: '16.2'
          primaryInstance:
            instanceSize: db.t3.micro
      logging:
        retentionDays: 30
        engineSpecificOptions:
          log_connections: true

Forwarding logs

You can forward logs to third-party services. See Forwarding Logs for more information.

Closing zombie connections

Connections from resources that are no longer running (like stopped containers) can become "zombie" connections. In modern, ephemeral architectures, it's important to have a strategy for handling them.

From container workloads

When connecting from a container, you should close the connection before the container exits. You can do this by listening for the SIGTERM signal.

const connectionPool = createConnectionPool();

// remember to close the connection even on errors
process
  .on('uncaughtException', () => {
    connectionPool.close();
    process.exit(1);
  })
  .on('unhandledRejection', () => {
    connectionPool.close();
    process.exit(1);
  });

process.on('SIGTERM', () => {
  connectionPool.close();
  process.exit(0);
});

From batch jobs

Similarly, for batch jobs, you should close the connection before the job finishes.

const connectionPool = createConnectionPool();

connectionPool.connect();

// remember to close the connection even on errors
process
  .on('uncaughtException', () => {
    connectionPool.close();
    process.exit(1);
  })
  .on('unhandledRejection', () => {
    connectionPool.close();
    process.exit(1);
  });

doSomethingWithYourConnection();

connectionPool.close();

From Lambda functions

For Lambda functions, you have two options:

1. Initialize and close the connection inside the handler.

This prevents zombie connections but can be slow, as creating a new connection for each invocation can add significant latency.

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;

2. Initialize the connection outside the handler.

This reuses the connection across invocations, which is more performant. However, it can lead to zombie connections because you can't hook into the Lambda container's shutdown process. To mitigate this, you should:

  • Lower your database's connection timeout settings.
  • Add logic to your application to re-establish the connection if it's been closed by the database.
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;

Accessibility

You can control which resources can access your database. In addition to requiring user credentials, you can restrict access based on the network.

DatabaseAccessibilityAPI referenceParent:RelationalDatabase
accessibilityModeDefault: internetRequired

Controls who can connect to your database.

Type: string ENUM

Possible values: internetscoping-workloads-in-vpcvpcwhitelisted-ips-only

  • internet (default): Anyone with the credentials can connect. Simplest setup, great for development. The database is still protected by username/password.
  • vpc: Only your app's resources (and anything in the same VPC) can connect. You can also whitelist specific IPs (e.g., your office) using whitelistedIps.
  • scoping-workloads-in-vpc: Most restrictive. Only resources that explicitly list this database in their connectTo can reach it. Best for production.
  • whitelisted-ips-only: Only the IP addresses you list in whitelistedIps can connect.

Aurora Serverless engines only support vpc or scoping-workloads-in-vpc.

forceDisablePublicIp

Remove the database's public IP entirely (VPC-only access).

Type: boolean

For Aurora, this can only be set at creation time and cannot be changed later.

whitelistedIps

IP addresses or CIDR ranges allowed to connect (e.g., 203.0.113.50/32).

Type: Array of string

  • In vpc/scoping-workloads-in-vpc: adds external IPs on top of VPC access (e.g., your office).
  • In whitelisted-ips-only: only these IPs can connect.
  • No effect in internet mode.

Internet mode

This is the default and least restrictive mode. The database can be accessed from anywhere on the internet.

VPC mode

The database can only be accessed from resources within the default VPC, such as functions, batch jobs, and container workloads. You can also whitelist specific IP addresses to allow access from the internet.

resources:
  myDatabase:
    type: relational-database
    properties:
      credentials:
        masterUserPassword: $Secret('dbPassword')
      engine:
        type: aurora-postgresql
        properties:
          version: '16.2'
          instances:
            - instanceSize: db.t3.medium
          port: 5432
      accessibility:
        accessibilityMode: vpc

  myFunction:
    type: function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: path/to/my/function.ts
      joinDefaultVpc: true

Scoping workloads in VPC mode

This mode is similar to VPC mode but more restrictive. In addition to being in the same VPC, a resource must explicitly list the database in its connectTo property to gain access.

resources:
  myDatabase:
    type: relational-database
    properties:
      credentials:
        masterUserPassword: $Secret('dbPassword')
      engine:
        type: aurora-postgresql
        properties:
          version: '16.2'
          instances:
            - instanceSize: db.t3.medium
          port: 5432
      accessibility:
        accessibilityMode: scoping-workloads-in-vpc
  myFunction:
    type: function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: path/to/my/function.ts
      joinDefaultVpc: true
      connectTo:
        - myDatabase

Whitelisted IPs only mode

The database can only be accessed from the IP addresses and CIDR blocks in the whitelistedIps list.

resources:
  myDatabase:
    type: relational-database
    properties:
      credentials:
        masterUserPassword: $Secret('dbPassword')
      engine:
        type: aurora-postgresql
        properties:
          version: '16.2'
          instances:
            - instanceSize: db.t3.medium
          port: 5432
      accessibility:
        accessibilityMode: whitelisted-ips-only
        whitelistedIps:
          - '147.25.33.12'

Maintenance window

The database may be briefly unavailable during this window. Use multi-AZ or Aurora to minimize downtime.

resources:
  myDatabase:
    type: relational-database
    properties:
      credentials:
        masterUserPassword: my_secret_password
      engine:
        type: postgres
        properties:
          version: '16.2'
          primaryInstance:
            instanceSize: db.t3.micro
      preferredMaintenanceWindow: Sun:04:00-Sun:05:00

Referenceable parameters

The following parameters can be easily referenced using $ResourceParam directive directive.

To learn more about referencing parameters, refer to referencing parameters.

connectionString
  • Fully-formed connection string that can be used to access the primary instance. For aurora databases, this is connectionString to cluster endpoint, which can be used for both reads and writes. Includes host, port, username, password and dbName.

  • Usage: $ResourceParam('<<resource-name>>', 'connectionString')
jdbcConnectionString
  • 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')
host
  • Hostname (address) of the primary instance that can be used for both reads and writes. For aurora databases, this is hostname of a cluster endpoint, which can be used for both reads and writes.

  • Usage: $ResourceParam('<<resource-name>>', 'host')
port
  • Port of the database.

  • Usage: $ResourceParam('<<resource-name>>', 'port')
dbName
  • Name of the automatically created database (can be configured using the dbName property).

  • Usage: $ResourceParam('<<resource-name>>', 'dbName')
readerHost
  • Hostname (address) used for reads only. (only available for aurora-postgresql and aurora-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. Connections are auto-balanced among available reader hosts.

  • Usage: $ResourceParam('<<resource-name>>', 'readerHost')
readerConnectionString
  • Same as connectionString but targets readerHosts (only available for aurora-postgresql and aurora-mysql engines). Connections are auto-balanced among available reader hosts.

  • Usage: $ResourceParam('<<resource-name>>', 'readerConnectionString')
readerJdbcConnectionString
  • Same as readerConnectionString but in JDBC format (only available for aurora-postgresql and aurora-mysql engines).

  • Usage: $ResourceParam('<<resource-name>>', 'readerJdbcConnectionString')
readReplicaHosts
  • 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')
readReplicaConnectionStrings
  • 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')
readReplicaJdbcConnectionStrings
  • Same as readReplicaConnectionStrings but in JDBC format (only available when read replicas are configured).

  • Usage: $ResourceParam('<<resource-name>>', 'readReplicaJdbcConnectionStrings')

Pricing

Pricing depends heavily on the engine you choose.

RDS engines:

  • Instances: Prices vary by instance size and region. See the AWS pricing pages for PostgreSQL, MySQL, MariaDB, Oracle, and SQL Server.
  • Storage: $0.115 - $0.238 per GB per month.
  • Backups: Free for automated backups that don't exceed your total database storage. Additional backup storage is $0.095 per GB per month.

Aurora engines:

  • Instances: Prices start at $0.073 per hour. See the Aurora pricing page for details.
  • Storage: $0.10 - $0.19 per GB per month.
  • I/O Rate: $0.20 - $0.28 per million read/write operations.
  • Backups: Free for automated backups that don't exceed your total database storage. Additional backup storage is $0.021 - $0.037 per GB per month.

Aurora Serverless:

  • ACUs (Aurora Capacity Units): Each ACU costs $0.06 - $0.10 per hour.
  • Storage, I/O, and Backups: Same as the standard Aurora engine.

Data transfer charges (all engines):

  • Inbound: Free.
  • Outbound (same AZ): Free.
  • Outbound (different AZ): $0.01 per GB.
  • Outbound (internet): First 1GB is free, then $0.09 - $0.15 per GB.

Free Tier (first 12 months):

  • 750 hours of db.t2.micro usage per month.
  • 20GB of SSD storage.
  • 20GB of backup storage.

API reference

RelationalDatabaseAPI reference
typeRequired
No description

Type: string "relational-database"

properties.credentialsRequired

Master user credentials (username and password).

Type: RelationalDatabaseCredentials

Included in the auto-generated connection string. Store the password in a Stacktape secret to avoid exposing it in your config file.

properties.engineRequired

Database engine: what type of database and how it runs.

Type: AuroraEngine or AuroraServerlessEngine or AuroraServerlessV2Engine or RdsEngine

  • RDS (postgres, mysql, mariadb, etc.): Single-node, fixed-size. Simple and predictable pricing.
  • Aurora (aurora-postgresql, aurora-mysql): High-performance clustered DB with auto-failover. Up to 5x faster than standard MySQL / 3x faster than standard PostgreSQL.
  • Aurora Serverless v2 (aurora-postgresql-serverless-v2): Auto-scales from 0.5 to 128 ACUs. Recommended for most new projects — pay only for what you use.
properties.accessibility

Who can connect to this database (network-level access control).

Type: DatabaseAccessibility

Default is internet — anyone with credentials can connect (fine for development). For production, use scoping-workloads-in-vpc to restrict access to only resources that list this database in their connectTo.

properties.deletionProtection

Prevent accidental deletion of the database. Must be disabled before deleting.

Type: boolean

properties.automatedBackupRetentionDaysDefault: 1

Days to keep automated daily backups (0-35). Set to 0 to disable (RDS only).

Type: number

properties.preferredMaintenanceWindow

When maintenance (patching, upgrades) happens. Format: Sun:02:00-Sun:04:00 (UTC).

Type: string

The database may be briefly unavailable during this window. Use multi-AZ or Aurora to minimize downtime.

properties.alarms

Alarms for this database (merged with global alarms from the Stacktape Console).

Type: Array of RelationalDatabaseAlarm

properties.disabledGlobalAlarms

Global alarm names to exclude from this database.

Type: Array of string

properties.logging

Database logging (connections, slow queries, errors).

Type: RelationalDatabaseLogging

Logs are sent to CloudWatch and retained for 90 days by default. Available log types vary by engine.

properties.dev

Dev mode: runs locally in Docker by default. Set remote: true to use the deployed database.

Type: DevModeConfig

overrides

Escape hatch to modify the underlying CloudFormation resources Stacktape creates.

Type: Object

Use dot-notation paths to override specific properties on any child resource. Find resource logical IDs with stacktape stack-info --detailed.

overrides:
  MyDbInstance:
    Properties.StorageEncrypted: true
RdsEnginePropertiesAPI referenceParent:RdsEngine
primaryInstanceRequired

The primary (writer) instance. Handles all write operations.

Type: RdsEnginePrimaryInstance

versionRequired

Engine version (e.g., 16.6 for PostgreSQL, 8.0.36 for MySQL).

Type: string

dbName

Name of the database created on initialization. For Oracle, this is the SID. Not applicable to SQL Server.

Type: string

port

Port the database listens on. Defaults: PostgreSQL 5432, MySQL/MariaDB 3306, Oracle 1521, SQL Server 1433.

Type: number

storage

Storage configuration. Auto-scales up when free space is low.

Type: RdsEngineStorage

readReplicas

Read replicas to offload read traffic from the primary instance.

Type: Array of RdsEngineReadReplica

Each replica gets its own endpoint. Data is replicated asynchronously from the primary.

disableAutoMinorVersionUpgrade

Skip automatic minor version upgrades (e.g., 16.4 → 16.5).

Type: boolean

AuroraEnginePropertiesAPI referenceParent:AuroraEngine
instancesRequired

Cluster instances. First = primary (writer), rest = read replicas.

Type: Array of AuroraEngineInstance

Reads are load-balanced across all instances. If the primary fails, a replica is automatically promoted (usually within 30 seconds).

versionRequired

Engine version (e.g., 16.6 for PostgreSQL, 8.0.36 for MySQL).

Type: string

dbNameDefault: defdb

Name of the initial database.

Type: string

port

Port. Defaults: aurora-mysql 3306, aurora-postgresql 5432.

Type: number

disableAutoMinorVersionUpgrade

Skip automatic minor version upgrades (e.g., 16.4 → 16.5).

Type: boolean

AuroraServerlessEnginePropertiesAPI referenceParent:AuroraServerlessEngine
version

Engine version. Usually managed by AWS automatically for serverless v1.

Type: string

dbNameDefault: defdb

Name of the initial database.

Type: string

minCapacityDefault: 2

Minimum ACUs to scale down to (~1 ACU ≈ 2 GB RAM).

Type: number

MySQL: 1-256 (powers of 2). PostgreSQL: 2-256 (powers of 2).

maxCapacityDefault: 4

Maximum ACUs to scale up to.

Type: number

MySQL: 1-256 (powers of 2). PostgreSQL: 2-256 (powers of 2).

pauseAfterSeconds

Pause the database after this many seconds of inactivity (no connections).

Type: number

When paused, you only pay for storage. Range: 300 (5 min) - 86400 (24 hr). Omit to never pause.

disableAutoMinorVersionUpgrade

Skip automatic minor version upgrades (e.g., 16.4 → 16.5).

Type: boolean

PostgresLoggingOptionsAPI referenceParent:RelationalDatabaseLogging
log_connections

Log new client connections.

Type: boolean

log_disconnections

Log client disconnections.

Type: boolean

log_lock_waits

Log sessions waiting for locks (helps find lock contention issues).

Type: boolean

log_min_duration_statementDefault: 10000

Log queries slower than this (ms). -1 = disabled, 0 = log all. Great for finding slow queries.

Type: number

log_statementDefault: ddl

Which SQL statements to log: none, ddl (CREATE/ALTER), mod (ddl + INSERT/UPDATE/DELETE), all.

Type: string ENUM

Possible values: allddlmodnone

MysqlLoggingOptionsAPI referenceParent:RelationalDatabaseLogging
server_audit_eventsDefault: QUERY_DDL

What to record in the audit log: connections, all queries, DDL only, DML only, etc.

Type: Array of string ENUM

Possible values: CONNECTQUERYQUERY_DCLQUERY_DDLQUERY_DMLQUERY_DML_NO_SELECT

long_query_timeDefault: 10

Queries slower than this (seconds) are logged as "slow queries". -1 to disable.

Type: number