Close
logoStacktape docs

Relational Databases

Overview

Relational-database resources allow you to deploy managed SQL database with multiple familiar database engines to choose from, including Amazon Aurora, PostgreSQL, MySQL, MariaDB, Oracle Database, and SQL Server. Stacktape makes it easy to set up, operate, and scale a relational database in the cloud. Thanks to the underlying AWS RDS platform, it provides cost-efficient and resizable capacity while automating time-consuming administration tasks such as hardware provisioning, database setup, patching, and backups.

Usage

RelationalDatabase  API reference
Required
type
Type: string "relational-database"
Type of the resource
Required
properties.credentials
Type: DatabaseCredentials
specifies credentials of the master user
Required
properties.engine
Type: (AuroraEngine or AuroraServerlessEngine or RdsEngine)

specifies engine and its properties

properties.accessibility
Type: DatabaseAccessibility
specifies connectivity settings and the level of network protection for database
properties.deletionProtection
Type: boolean
enables database deletion protection
Default: 1
properties.automatedBackupRetention
Type: number

specifies how many days are automated backups retained

overrides
Type: Object

Overrides properties of the specified sub-resource.

resources:
  myPgSql:
    Type: 'relational-database'
    Properties:
      credentials:
        masterUserName: commander
        masterUserPassword: mySecretPassword
      engine:
        type: postgres
        properties:
          port: 5432
          storage:
            diskSizeGB: 20
          instance:
            dbInstanceSize: db.t3.micro

Setting access credentials

DatabaseCredentials  API reference
Parent API reference: RelationalDatabase
Required
masterUserName
Type: string
user name for a database master user
Required
masterUserPassword
Type: string
password name for a database master user

resources:
  myPgSql:
    Type: 'relational-database'
    Properties:
      credentials:
        masterUserName: commander
        masterUserPassword: mySecretPassword
      engine:
        type: postgres
        properties:
          dbName: app-db
          port: 5432
          storage:
            diskSizeGB: 20
          instance:
            dbInstanceSize: db.t3.micro
          replicas:
            - dbInstanceSize: db.t3.micro

Choosing engine

We group engines into 3 groups: RdsEngines, AuroraEngines, AuroraServerlessEngines.

Each respective engine group has different configuration properties and utilizies different topology concepts.

  • RdsEngines

    • Supported engines: Commercial engines such as:

      • mysql
      • mariadb
      • postgres
      • oracle
      • sqlserver

    • Topology:

      • 1 primary instance.
      • Optionally, read replicas (for applications with heavy database use) can be added.

  • AuroraEngines

    • Supported engines: AWS-developed engines compatible with standard postgres and mysql connectors:

      • aurora-postgresql
      • aurora-mysql

      In some cases these engines offer better scalability, perfomance and failover properties compared to using standard mysql or postgres engines.

    • Topology

      • 1 primary instance.
      • Optionally, read replicas (for applications with heavy database use) can be added.
      • Automatic load balancing - aurora automatically takes care of load balancing database reads between instances of you database
      • Automatic failover - if primary instance fails one of the read replicas is elected a new primary instance.
      • Storage replication - storage is automatically replicated accross multiple availability zones.

  • AuroraServerlessEngines

    • Supported engines: AWS-developed engines compatible with standard postgres and mysql connectors:

      • aurora-postgresql
      • aurora-mysql

      In some cases these engines offer better scalability, perfomance and failover properties compared to using standard mysql or postgres engines.

    • Topology

      • Serverless - The database is fully serverless. You only set minimum and maximum of ACU (Aurora Capacity Units) your serverless database can use and aurora takes care of the rest.
      • Autoscaling - The database is automatically scaled based on the connections and cpu usage (can be useful in environemnts when you need the computation power only during peak hours)
      • Database pause - You can completely pause the database (scale to 0 and pay nothing) in cases when database is idle for specified amount of time(can be usefull for development environments).
      • Storage replication - storage is automatically replicated accross multiple availability zones.

Rds Engine

RdsEngine  API reference
Parent API reference: RelationalDatabase
Required
type
Type: string ENUM
Type of the resource
properties.dbName
Type: string
meaning and behaviour of this property differs based on engine type being used
Required
properties.port
Type: number
the port number on which the database instances accepts connections
Required
properties.storage
Type: DatabaseStorage
storage settings for the database
Required
properties.instance
Type: DatabaseInstance
properties of the primary instance
properties.replicas
Type: Array of DatabaseReplica
list of read replicas (replicas of primary instance)
properties.version
Type: string
specific version of the engine

resources:
  myPgSql:
    Type: 'relational-database'
    Properties:
      credentials:
        masterUserName: commander
        masterUserPassword: mySecretPassword
      engine:
        type: postgres
        properties:
          port: 5432
          storage:
            diskSizeGB: 20
          instance:
            dbInstanceSize: db.t3.micro

Storage

DatabaseStorage  API reference
Parent API reference: RdsEngineProperties
Required
diskSizeGB
Type: number
the amount of storage (in gigabytes) to be initially allocated for the instance (minimum - 20).
maxDiskSizeGB
Type: number
enables and sets the upper limit to which Amazon can automatically scale the storage.

resources:
  myPgSql:
    Type: 'relational-database'
    Properties:
      credentials:
        masterUserName: commander
        masterUserPassword: mySecretPassword
      engine:
        type: postgres
        properties:
          dbName: app-db
          port: 5432
          storage:
            diskSizeGB: 20
          instance:
            dbInstanceSize: db.t3.micro
          replicas:
            - dbInstanceSize: db.t3.micro

Primary instance

DatabaseInstance  API reference
Parent API reference: RdsEngineProperties
Required
dbInstanceSize
Type: string
specify instance size
multiAz
Type: boolean
specifies whether the database instance is a multiple Availability Zone deployment

resources:
  myPgSql:
    Type: 'relational-database'
    Properties:
      credentials:
        masterUserName: commander
        masterUserPassword: mySecretPassword
      engine:
        type: postgres
        properties:
          dbName: app-db
          port: 5432
          storage:
            diskSizeGB: 20
          instance:
            dbInstanceSize: db.t3.micro
          replicas:
            - dbInstanceSize: db.t3.micro

Replicas

DatabaseReplica  API reference
Parent API reference: RdsEngineProperties
Required
dbInstanceSize
Type: string

specifies which instance size to use

multiAz
Type: boolean
Specifies whether the database instance is a multiple Availability Zone deployment.

A typical example of utilizing read replicas is using them for running BI/reporting queries. This way the primary database's performance (used for reads and writes made by our main application) is not affected.


The following example shows:

  • container-workload myApp representing main component of your application which reads and writes to the database continuously (uses primary database instance),
  • batch-job myAnalyticsJob which is scheduled to run every two hours and runs and processes advanced analytics queries to get insights from data in the database (using replica instance).

resources:
  myAnalyticsJob:
    Type: 'batch-job'
    Properties:
      container:
        imageConfig:
          dockerfilePath: 'bi-job/Dockerfile'
          command: ['python', 'bijob-script.py']
        environment:
          # we are injecting replica database address into environment variables
          - name: DB_URL
            value: "$GetParam('myPgSql', 'DbReplica.0::Endpoint.Address')"
      resources:
        cpu: 4
        memory: 7800
      events:
        - type: 'schedule'
          properties:
            scheduleRate: 'rate(2 hours)' # every two hours


  myApp:
    Type: container-workload
    Properties:
      container:
        imageConfig:
          filePath: '_example-configs/containers/my-app.ts'
        environment:
          # we are injecting primary dbInstance database address into environment variables
          # primary instance can be used for both read and write connections
          - name: DB_URL
            value: "$GetParam('myPgSql', 'DbInstance::Endpoint.Address')"
        events:
          - type: 'http-api-gateway'
            properties:
              httpApiGatewayName: 'myApiGw'
              containerPort: 80
              path: '*'
              method: '*'
      resources:
        cpu: 0.5
        memory: 512


  myPgSql:
    Type: 'relational-database'
    Properties:
      credentials:
        masterUserName: commander
        masterUserPassword: mySecretPassword
      engine:
        type: postgres
        properties:
          dbName: appdb
          port: 5432
          storage:
            diskSizeGB: 20
          instance:
            dbInstanceSize: db.t3.micro
          replicas:
            - dbInstanceSize: db.t3.micro

Aurora Engine

AuroraEngine  API reference
Parent API reference: RelationalDatabase
Required
type
Type: string ENUM
Type of the resource
properties.dbName
Type: string
specifies the name of the database to create
Required
properties.port
Type: number
the port number on which the database instances accepts connections
Required
properties.instances
Type: Array of AuroraDatabaseInstance

cluster of instances that make up the aurora cluster

properties.version
Type: string
specific version of the engine

resources:
  auroraSlsPostgres:
    Type: 'relational-database'
    Properties:
      credentials:
        masterUserName: congor
        masterUserPassword: $GetSecret('dbSecret.password')
      engine:
        type: aurora-postgresql
        properties:
          instances:
            - dbInstanceSize: db.t3.medium
          port: 5432

Cluster instances

AuroraDatabaseInstance  API reference
Parent API reference: AuroraEngineProperties
dbInstanceSize
Type: string
specifies which instance size to use

resources:
  auroraSlsPostgres:
    Type: 'relational-database'
    Properties:
      credentials:
        masterUserName: congor
        masterUserPassword: $GetSecret('dbSecret.password')
      accessibility:
        restrictAccess: 'vpc'
        additionalWhitelistedIps:
          - '192.168.1.1'
      engine:
        type: aurora-postgresql
        properties:
          instances:
            - dbInstanceSize: db.t3.medium
          port: 5432

Aurora Serverless Engine

AuroraServerlessEngine  API reference
Parent API reference: RelationalDatabase
Required
type
Type: string ENUM
Type of the resource
properties.dbName
Type: string
specifies the name of the database to create
properties.minCapacity
Type: number
minimum capacity units database can scale down to
properties.maxCapacity
Type: number
the time in seconds after which the idle serverless database is paused.
properties.pauseAfterSeconds
Type: number
the time in seconds after which the idle serverless database is paused.
properties.version
Type: string
specific version of the engine

resources:
  auroraSlsPostgres:
    Type: 'relational-database'
    Properties:
      credentials:
        masterUserName: congor
        masterUserPassword: mySecretPass
      accessibility:
        restrictAccess: 'vpc'
      engine:
        type: aurora-postgresql-serverless
        properties:
          dbName: 'erko'
          minCapacity: 8
          pauseAfterSeconds: 500

Accessibility

The accessibility section can be used to restrict access to the database. By default, a database is accessible from everywhere on the internet.

DatabaseAccessibility  API reference
Parent API reference: RelationalDatabase
Required
restrictAccess
Type: string ENUM

Specifies the database access restriction mode

disablePublicIp
Type: boolean

if set to true, the database address will not be publicly resolvable (only within VPC)

additionalWhitelistedIps
Type: Array of string

list of ip addresses or ip ranges(in CIDR form)

VPC mode

In the vpc mode, only the workloads which are in the VPC are able to access the database.

The following example shows:

  • database with accessibility restricted to VPC
  • database additionally whitelists additional IPs outside of VPC, which are able to access the database as well.

resources:
  auroraSlsPostgres:
    Type: 'relational-database'
    Properties:
      credentials:
        masterUserName: congor
        masterUserPassword: mySecretPass
      accessibility:
        restrictAccess: 'vpc'
        additionalWhitelistedIps:
          - '147.25.33.12'
      engine:
        type: aurora-postgresql
        properties:
          instances:
            - dbInstanceSize: db.t3.medium
          port: 5432

Scoping workloads in VPC mode

In the scoping-workloads-in-vpc mode, only the workloads which are in the VPC and are scoping the database in the allowAccessTo section are able to access the database.

resources:
  # functionOne does NOT have access to database eventhough it is joined in vpc
  functionOne:
    Type: function
    Properties:
      packageConfig:
        filePath: 'path/to/my-lambda.ts'
      joinDefaultVpc: true


  # functionTwo does have access to database, because it is scoping the database in allowAccessTo list
  functionTwo:
    Type: function
    Properties:
      packageConfig:
        filePath: 'path/to/my-lambda-2.ts'
      joinDefaultVpc: true
      accessControl:
        allowAccessTo:
          - 'myPgSql'


  myPgSql:
    Type: 'relation-database'
    Properties:
      accessibility:
        restrictAccess: 'scoping-workloads-in-vpc'
      credentials:
        masterUserName: commander
        masterUserPassword: mySecretPassword
      engine:
        type: postgres
        properties:
          dbName: appdatabase
          port: 5432
          storage:
            diskSizeGB: 20
          instance:
            dbInstanceSize: db.t3.micro

Whitelisted IPs only mode

In the whitelisted-ips-only mode, only specified IPs can access the database.

resources:
  auroraSlsPostgres:
    Type: 'relational-database'
    Properties:
      credentials:
        masterUserName: congor
        masterUserPassword: mySecretPass
      accessibility:
        restrictAccess: 'whitelisted-ips-only'
        additionalWhitelistedIps:
          - '147.25.33.12'
      engine:
        type: aurora-postgresql
        properties:
          instances:
            - dbInstanceSize: db.t3.medium
          port: 5432

Backups

  • AWS automatically backups the database daily.
  • By default automated backups are retained for one day.
  • Maximum retention period is 35 days.
  • You can disable automated backup by setting value to 0 (works only for Rds engines).
  • You can also take manual backup snapshots (in console or using API). The retention is not applied on manual backup snapshots.
  • All information on backups for Rds engines and backups for Aurora engines can be found on respective links.

resources:
  myPgSql:
    Type: 'relational-database'
    Properties:
      credentials:
        masterUserName: commander
        masterUserPassword: mySecretPassword
      engine:
        type: postgres
        properties:
          port: 5432
          storage:
            diskSizeGB: 20
          instance:
            dbInstanceSize: db.t3.micro
      automatedBackupRetention: 5