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 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
credentials
DatabaseCredentials
specifies credentials of the master user
Required
engine
(AuroraEngine or AuroraServerlessEngine or RdsEngine)
specifies engine and its properties
accessibility
DatabaseAccessibility
specifies connectivity settings and the level of network protection for database
deletionProtection
boolean
enables database deletion protection

➡️ Basic usage

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

➡️ Credentials

DatabaseCredentials API reference
Parent API reference: RelationalDatabase
Required
masterUserName
string
user name for a database master user
Required
masterUserPassword
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

➡️ Engine

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

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

Rds Engine

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

Storage

DatabaseStorage API reference
Parent API reference: RdsEngineProperties
Required
diskSizeGB
number
the amount of storage (in gigabytes) to be initially allocated for the instance (minimum - 20).
maxDiskSizeGB
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
string
specify instance size
multiAz
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
string
specifies which instance size to use
multiAz
boolean
Specifies whether the database instance is a multiple Availability Zone deployment.

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



In the following example we see following infrastructure:
  • container-workload myApp representing main component of your application which reads and writes to the database continuously (using primary instance),
  • batch-job biJob which is scheduled to run every two hours and runs advanced analytics query to get insights from data in database(using the replica).

resources:
  biJob:
    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
string ENUM
Type of the resource
properties.dbName
string
specifies the name of the database to create
Required
properties.port
number
the port number on which the database instancies accepts connections
Required
properties.instancies
Array of AuroraDatabaseInstance
cluster of instancies that make up the aurora cluster
properties.version
string
specific version of the engine
AuroraEngineProperties API reference
Parent API reference: AuroraEngine
dbName
string
specifies the name of the database to create
Required
port
number
the port number on which the database instancies accepts connections
Required
instancies
Array of AuroraDatabaseInstance
cluster of instancies that make up the aurora cluster
version
string
specific version of the engine

Cluster instancies

AuroraDatabaseInstance API reference
Parent API reference: AuroraEngineProperties
dbInstanceSize
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:
          instancies:
            - dbInstanceSize: db.t3.medium
          port: 5432

Aurora Serverless Engine

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

AuroraServerlessEngineProperties API reference
Parent API reference: AuroraServerlessEngine
dbName
string
specifies the name of the database to create
minCapacity
number
minimum capacity units database can scale down to
maxCapacity
number
the time in seconds after which the idle serverless database is paused.
pauseAfterSeconds
number
the time in seconds after which the idle serverless database is paused.
version
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

Accessibility section of can be used to restrict access to database. By default database is accessible from everywhere on the internet.

DatabaseAccessibility API reference
Parent API reference: RelationalDatabase
Required
restrictAccess
string ENUM
Specifies the database access restriction mode
disablePublicIp
boolean
if set to true, the database address will not be publicly resolvable (only within VPC)
additionalWhitelistedIps
Array of string
list of ip addresses or ip ranges(in CIDR form)

vpc mode

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

In this example we are also whitelisting additional IPs outside of VPC which are able to access 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:
          instancies:
            - dbInstanceSize: db.t3.medium
          port: 5432

scoping-workloads-in-vpc mode

In the scoping-workloads-in-vpc mode only workloads which are in vpc and are scoping the database 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:
          instancies:
            - dbInstanceSize: db.t3.medium
          port: 5432