3.2.1

Database

Resource Overview

A Database provisions a single relational database instance or serverless database cluster with Amazon Relational Database Service (RDS). Amazon RDS is a database engine that makes it easier to set up, operate, and scale relational databases in the cloud.

Relational Database Types

AWS Aurora Serverless Database Cluster

  • Simple, cost-effective configuration for infrequent, unpredictable workloads
  • Scales compute capacity to match an application's usage without disrupting client connections
  • Reduces the need to manually configure database compute capacity

With this configuration, a cluster type database endpoint is connected to a proxy fleet, which routes the application's workload to a group of active database instances in the cluster. Aurora Serverless maintains a 'warm' pool of resources on the side in order to seamlessly scale the database cluster when a workload requires it.

Before implementing an Aurora Serverless cluster, be sure to consider the following:

  • Available for MySQL 5.6 only
  • Can only be accessed from within a Virtual Network

Single Database Instance

  • AWS manages common database administration tasks like security, backups, and softwares updates
  • Ability to choose on-demand or reserved database instances to fit billing requirements
  • Use of familiar database engines like PostgreSQL, MariaDB, and MySQL
  • Additional security and monitoring through multiple Amazon RDS interfaces

AWS will take care of most of the administration and setup but there are AWS resource settings that you get to determine, like the retention period of your database backups, the instance type to hold your database, and a root user password for the server. What's left for you to define are the database settings specific to your application like the choice of engine, the engine version, and storage size. Database s currently supports PostgreSQL, MariaDB, and MySQL database engines.

Once a Database has been provisioned its DNS name can be found in the View info pane for the resource. Clients can connect to the Database at this address on the server's port.

Service Discovery

Service discovery wires (dashed line) provide compute resources (Function, Edge Function, Docker Task) with the permissions and environment variables required to perform actions using cloud resources within the stack. This resource is on the receiving end of a service discovery wire originating from compute resources.

The following compute resources can use a service discovery wire to access a Database resource:

  • Function
  • Docker Tasks

Database Configurable Properties

Display Name

Human readable name for this resource that is displayed on the Stackery Dashboard and Stackery CLI output.

Logical ID

The unique identifier used to reference this resource in the stack template. Defining a custom Logical ID is recommended, as it allows you to quickly identify a resource and any associated sub-resources when working with your stack in AWS, or anywhere outside of the Stackery Dashboard. As a project grows, it becomes useful in quickly spotting this resource in template.yaml or while viewing a stack in Template View mode.

The Logical ID of all sub-resources associated with this Database will be prefixed with this value.

The identifier you provide must only contain alphanumeric characters (A-Za-z0-9) and be unique within the stack.

Default Logical ID Example: Database2

IMPORTANT : AWS uses the Logical ID of each resource to coordinate and apply updates to the stack when deployed. On any update of a resource's logical ID (or any modification that results in one), CloudFormation will delete the currently deployed resource and create a new one in it's place when the updated stack is deployed.

Type

A Database resource can represent a single RDS database instance, or an Aurora Serverless database cluster.

The Database resource panel will populate different configurable properties based on this value.

Aurora Serverless Cluster Type

Mininum Cluster Capacity (ACUs)

The lowest Aurora capacity units to which the DB cluster can scale down.

Maximum Cluster Capacity (ACUs)

The highest Aurora capacity units to which the DB cluster can scale up.

Aurora Capacity Units (ACUs): Aurora Serverless creates your DB cluster scaling rules based on the minimum and maximum ACU properties above. These scaling rules describe thresholds for CPU utilization, total connections, and available memory.

Auto Pause

Pause the DB cluster's compute capacity (scale down to 0 ACUs) after consecutive minutes of inactivity. If enabled, the default amount of time of inactivity to cause a pause is 300 seconds (5 minutes).

Backup Retention Period

The length of time in days to keep automatic backups. Backups older than this period are automatically deleted. To disable automatic database backups set this property to 0.

Root Password

The initial root user password for the database. It is recommended to reference a value in a Stackery environment configuration to avoid storing this value in your source code repository.

Use Existing RDS Database

When enabled, this feature provides you with a field to specify the Amazon Resource Name (ARN) of an existing RDS Database cluster to reference in your application.

You may reference an environment parameter in order to conditionally reference existing infrastructure based on environment.

Single RDS Instance Type

Engine

You can use following SQL database engines:

  • PostgreSQL
  • MariaDB
  • MySQL

Version

The version number of the database engine that the DB instance uses.

Storage Size

The amount of storage allocated to your database up to 16TB. Amazon RDS utilizes Amazon Elastic Block Store (EBS) volumes for database instance storage.

Backup Retention Period

The length of time in days to keep automatic daily storage snapshots. Snapshots older than this period are automatically deleted. To disable automatic database backups set this property to 0.

Instance Type

The AWS Instance Class Type of the DB instance.

Root Password

The initial root user password for the server. It is recommended to reference a value in a Stackery environment configuration to avoid storing this value in your source code repository.

Failover Instance

Automatically creates a standby replica of your database in a different availability zone. Your application with automatically failover to the standby database in the event of an instance failure. Read more about the benefits of enabling this feature and the failover process in the AWS docs.

Use Existing RDS Database

When enabled, this feature provides you with a field to specify the Amazon Resource Name (ARN) of an existing RDS Database instance to reference in your application.

You may reference an environment parameter in order to conditionally reference existing infrastructure based on environment.

IAM Permissions

When connected by a service discovery wire (dashed wire), a Function or Docker Task will add the following IAM statement/policy to its role and gain permission to access this resource.

No Permissions Added

Access to your database is managed through the database engine's native authentication and authorization system. No additional IAM permissions are required.

Environment Variables

When connected by a service discovery wire (dashed wire), a Function or Docker Task will automatically populate and reference the following environment variables in order to interact with this resource.

DB_ID

The Physical ID of the Database resource.

Example: Database2

DB_ADDRESS

The Database resource endpoint.

Cluster Example: mycluster.cluster-123456789012.us-east-1.rds.amazonaws.com

Instance Example: stackery-9834723-4830492838-df8fs87.cd78f9d8s.us-east-1.rds.amazonaws.com

DB_PORT

The port to access the Database resource.

Example: 3306

DB_ARN

The Amazon Resource Name of the RDS Database resource.

Example: arn:aws:rds:us-east-1:0123456789:cluster:stackery-9834723-4830492838-df8fs87

AWS SDK Code Example

Language-specific examples of AWS SDK calls using the environment variables discussed above.

Connect to Aurora MySQL & Create a Database table

screenshot

// Load AWS SDK and create a new mysql object
const AWS = require("aws-sdk");
const mysql = require('mysql');

const pool = mysql.createPool({
  host: process.env.DB_ADDRESS,
  user: 'root',
  password: 'password'
});

console.log('connection result', pool);

exports.handler = async (message, context) => {
  // send the response right away when the callback executes, instead of waiting for the Node.js event loop to be empty
  context.callbackWaitsForEmptyEventLoop = false;

  // retrieve connection, query, and release
  pool.getConnection(function (err, connection) {
    if (err) console.log('connection error: ', err);
    const sql = 'CREATE TABLE employees ( EmpID  int NOT NULL, Name varchar(255) NOT NULL, PRIMARY KEY (EmpID))';
    connection.query(sql, function (error, results, fields) {
      connection.release();

      if (error) return error;
      else return results;
    });
  });
}
import boto3
import pymysql
import os
import logging
import sys

rds_host = os.environ['DB_ADDRESS']
name = 'root'
password = 'password'
db_name = os.environ['DB_ID']
port = os.environ['DB_PORT']

logger = logging.getLogger()
logger.setLevel(logging.INFO)

try:
  conn = pymysql.connect(rds_host, user=name, passwd=password, db=db_name, connect_timeout=10000)
  print(conn)
except:
  logger.error("ERROR: Unexpected error: Could not connect to MySQL instance.")
  sys.exit()

logger.info("SUCCESS: Connection to RDS MySQL instance succeeded")
def handler(message, context):
  with conn.cursor() as cur:
    cur.execute("create table Employee3 ( EmpID  int NOT NULL, Name varchar(255) NOT NULL, PRIMARY KEY (EmpID))")
    conn.commit()
    for row in cur:
      print(row)
  conn.commit()

  return "Added %d items from RDS MySQL table" %(item_count)

Metrics & Logs

Double clicking a resource while viewing your stack's current deployment gives you access to your pre-configured resource properties, and the following metrics and logs.

  • CPU Utilization
  • Available Memory
  • Swap Usage
  • Available Storage
  • IO Operations
  • IO Latency
  • IO Throughput
  • IO Queue Length
  • Network Throughput
  • Database Connections

Related AWS Documentation

AWS Documentation:

AWS SDK Documentation: Node.js | Python | Java | .NET

← CDN (Content Delivery Network)Docker Task →