Amazon Relational Database Service User Guide RDS

Amazon-RDS-userGuide

Amazon-RDS-userGuide

Amazon-RDS-userGuide

Amazon-RDS-userGuide

Amazon-RDS-userGuide

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 1124

DownloadAmazon Relational Database Service - User Guide Amazon-RDS-user
Open PDF In BrowserView PDF
Amazon Relational
Database Service
User Guide
API Version 2014-10-31

Amazon Relational Database Service User Guide

Amazon Relational Database Service: User Guide

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner
that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not
owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by
Amazon.

Amazon Relational Database Service User Guide

Table of Contents
What Is Amazon RDS? ........................................................................................................................ 1
Overview ................................................................................................................................... 1
DB Instances .............................................................................................................................. 1
Regions and Availability Zones ..................................................................................................... 2
Security .................................................................................................................................... 2
Monitoring an Amazon RDS DB Instance ....................................................................................... 3
Amazon RDS Interfaces ............................................................................................................... 3
AWS Management Console .................................................................................................. 3
Command Line Interface ..................................................................................................... 3
Programming with Amazon RDS .......................................................................................... 3
How You Are Charged for Amazon RDS ........................................................................................ 3
What's Next? ............................................................................................................................. 4
Getting Started .................................................................................................................. 4
Database Engine–Specific Topics .......................................................................................... 4
Setting Up ........................................................................................................................................ 5
Sign Up for AWS ........................................................................................................................ 5
Create an IAM User .................................................................................................................... 5
Determine Requirements ............................................................................................................. 7
Provide Access to Your DB Instance in Your VPC by Creating a Security Group .................................... 8
Getting Started ................................................................................................................................ 10
Creating a MariaDB DB Instance and Connecting to a Database ...................................................... 10
Creating a MariaDB Instance .............................................................................................. 10
Connecting to a Database on a DB Instance Running MariaDB ................................................ 15
Deleting a DB Instance ...................................................................................................... 17
Creating a Microsoft SQL Server DB Instance and Connecting to a DB Instance ................................. 18
Creating a Sample SQL Server DB Instance .......................................................................... 18
Connecting to Your Sample DB Instance .............................................................................. 24
Exploring Your Sample DB Instance .................................................................................... 25
Deleting Your Sample DB Instance ...................................................................................... 27
Related Topics ................................................................................................................. 27
Creating a MySQL DB Instance and Connecting to a Database ........................................................ 28
Creating a MySQL DB Instance ........................................................................................... 28
Connecting to a Database on a DB Instance Running MySQL .................................................. 33
Deleting a DB Instance ...................................................................................................... 34
Creating an Oracle DB Instance and Connecting to a Database ....................................................... 36
Creating a Sample Oracle DB Instance ................................................................................ 36
Connecting to Your Sample DB Instance .............................................................................. 39
Deleting Your Sample DB Instance ...................................................................................... 40
Related Topics ................................................................................................................. 40
Creating a PostgreSQL DB Instance and Connecting to a Database .................................................. 40
Creating a PostgreSQL DB Instance .................................................................................... 41
Connecting to a PostgreSQL DB Instance ............................................................................ 44
Deleting a DB Instance ...................................................................................................... 47
Tutorial: Create a Web Server and an Amazon RDS Database ......................................................... 48
Step 1: Create a DB Instance ............................................................................................. 49
Step 2: Create a Web Server .............................................................................................. 54
Tutorials .......................................................................................................................................... 67
Best Practices for Amazon RDS .......................................................................................................... 68
Amazon RDS Basic Operational Guidelines ................................................................................... 68
DB Instance RAM Recommendations ........................................................................................... 69
Amazon RDS Security Best Practices ........................................................................................... 69
Using Enhanced Monitoring to Identify Operating System Issues .................................................... 69
Using Metrics to Identify Performance Issues ............................................................................... 70
Viewing Performance Metrics ............................................................................................. 70
API Version 2014-10-31
iii

Amazon Relational Database Service User Guide

Evaluating Performance Metrics ......................................................................................... 71
Tuning Queries ............................................................................................................... 73
Best Practices for Working with MySQL Storage Engines ............................................................... 73
Best Practices for Working with MariaDB Storage Engines ............................................................. 74
Best Practices for Working with Oracle ....................................................................................... 74
Best Practices for Working with PostgreSQL ................................................................................ 75
Loading Data into a PostgreSQL DB Instance ....................................................................... 75
Working with the fsync and full_page_writes database parameters ......................................... 75
Working with the PostgreSQL Autovacuum Feature .............................................................. 75
Best Practices for Working with SQL Server ................................................................................. 76
Working with DB Parameter Groups ........................................................................................... 77
Amazon RDS Best Practices Presentation Video ............................................................................ 77
DB Instances .................................................................................................................................... 78
DB Instance Class ..................................................................................................................... 80
DB Instance Class Types .................................................................................................... 80
Specifications for All Available DB Instance Classes ............................................................... 80
Changing Your DB Instance Class ....................................................................................... 85
Configuring the Processor for a DB Instance Class ................................................................ 85
DB Instance Status ................................................................................................................... 96
Regions and Availability Zones ................................................................................................... 99
...................................................................................................................................... 99
DB Instance Storage ............................................................................................................... 101
Storage Types ................................................................................................................ 101
General Purpose SSD Storage .......................................................................................... 101
Provisioned IOPS Storage ................................................................................................ 103
Magnetic storage ............................................................................................................ 104
Monitoring storage performance ...................................................................................... 105
Factors That Affect Storage Performance ........................................................................... 105
High Availability (Multi-AZ) ...................................................................................................... 107
Modifying a DB Instance to be a Multi-AZ Deployment ........................................................ 108
Failover Process for Amazon RDS ...................................................................................... 108
Related Topics ................................................................................................................ 109
DB Instance Lifecycle .............................................................................................................. 110
Creating a DB Instance .................................................................................................... 111
Connecting to a DB Instance ............................................................................................ 112
Modifying a DB Instance .................................................................................................. 113
Maintaining a DB Instance ............................................................................................... 115
Upgrading a DB Instance Engine Version ........................................................................... 121
Renaming a DB Instance .................................................................................................. 122
Rebooting a DB Instance ................................................................................................. 125
Stopping a DB Instance ................................................................................................... 127
Starting a DB Instance .................................................................................................... 129
Deleting a DB Instance .................................................................................................... 131
Tagging RDS Resources ........................................................................................................... 134
Overview ....................................................................................................................... 134
AWS Management Console .............................................................................................. 135
CLI ................................................................................................................................ 137
API ............................................................................................................................... 137
Related Topics ................................................................................................................ 138
Working with Read Replicas ..................................................................................................... 139
Overview ....................................................................................................................... 139
Creating a Read Replica ................................................................................................... 141
Promoting a Read Replica ................................................................................................ 142
Creating a Read Replica in a Different AWS Region ............................................................. 144
Monitoring Read Replication ............................................................................................ 150
Working with Option Groups ................................................................................................... 152
Option Groups Overview ................................................................................................. 152
API Version 2014-10-31
iv

Amazon Relational Database Service User Guide

Creating an Option Group ............................................................................................... 153
Making a Copy of an Option Group .................................................................................. 155
Adding an Option to an Option Group .............................................................................. 156
Listing the Options and Option Settings for an Option Group .............................................. 159
Modifying an Option Setting ........................................................................................... 160
Removing an Option from an Option Group ...................................................................... 163
Working with Parameter Groups ............................................................................................... 165
Creating a DB Parameter Group ....................................................................................... 166
Modifying Parameters in a DB Parameter Group ................................................................. 167
Copying a DB Parameter Group ........................................................................................ 169
Listing DB Parameter Groups ........................................................................................... 171
Viewing Parameter Values for a DB Parameter Group .......................................................... 172
Comparing DB Parameter Groups ..................................................................................... 173
DB Parameter Values ...................................................................................................... 173
Working with ARNs ................................................................................................................. 177
Constructing an ARN ....................................................................................................... 177
Getting an Existing ARN .................................................................................................. 179
Working with Storage ............................................................................................................. 183
Increasing DB instance storage capacity ............................................................................ 183
Change storage type ....................................................................................................... 184
Modify Provisioned IOPS ................................................................................................. 186
DB Instance Billing for Amazon RDS ........................................................................................ 188
On-Demand DB Instances ................................................................................................ 189
Reserved DB Instances .................................................................................................... 190
Backing Up and Restoring ............................................................................................................... 201
Working With Backups ............................................................................................................ 202
Backup Storage .............................................................................................................. 202
Backup Window .............................................................................................................. 202
Backup Retention Period ................................................................................................. 203
Disabling Automated Backups .......................................................................................... 203
Enabling Automated Backups ........................................................................................... 205
Retaining Automated Backups .......................................................................................... 206
Automated Backups with Unsupported MySQL Storage Engines ........................................... 208
Automated Backups with Unsupported MariaDB Storage Engines .......................................... 209
.................................................................................................................................... 209
Creating a DB Snapshot .......................................................................................................... 210
Restoring from a DB Snapshot ................................................................................................. 212
Parameter Groups ........................................................................................................... 212
Security Groups .............................................................................................................. 212
Option Groups ............................................................................................................... 212
Microsoft SQL Server ...................................................................................................... 212
Oracle ........................................................................................................................... 213
Restoring from a Snapshot .............................................................................................. 213
Copying a Snapshot ................................................................................................................ 215
Limitations ..................................................................................................................... 215
Snapshot Retention ........................................................................................................ 215
Shared Snapshots ........................................................................................................... 215
Encryption ..................................................................................................................... 215
Copying Snapshots Across AWS Regions ............................................................................ 216
Option Groups ............................................................................................................... 216
Parameter Groups ........................................................................................................... 216
Copying a DB Snapshot ................................................................................................... 217
Sharing a Snapshot ................................................................................................................ 224
Sharing an Encrypted Snapshot ........................................................................................ 225
Sharing a Snapshot ......................................................................................................... 227
Point-in-Time Recovery ........................................................................................................... 231
Tutorial: Restore a DB Instance from a DB Snapshot .................................................................... 233
API Version 2014-10-31
v

Amazon Relational Database Service User Guide

Prerequisites for Restoring a DB Instance from a DB Snapshot ..............................................
Restoring a DB Instance from a DB Snapshot .....................................................................
Modifying a Restored DB Instance ....................................................................................
Related Topics ................................................................................................................
Monitoring .....................................................................................................................................
Overview of Monitoring ..........................................................................................................
Monitoring Tools ............................................................................................................
Monitoring with CloudWatch ............................................................................................
Publishing to CloudWatch Logs ........................................................................................
Enhanced Monitoring ..............................................................................................................
Enhanced Monitoring Availability ......................................................................................
Differences Between CloudWatch and Enhanced Monitoring Metrics ......................................
Setting Up for and Enabling Enhanced Monitoring ..............................................................
Viewing Enhanced Monitoring ..........................................................................................
Viewing Enhanced Monitoring by Using CloudWatch Logs ....................................................
Performance Insights ..............................................................................................................
Enabling Performance Insights .........................................................................................
Access Control for Performance Insights ............................................................................
Using the Performance Insights Dashboard ........................................................................
Additional User Interface Features ....................................................................................
Performance Insights API .................................................................................................
Metrics Published to CloudWatch .....................................................................................
Logging Performance Insights Operations by Using AWS CloudTrail ......................................
Using Amazon RDS Recommendations ......................................................................................
Responding to Recommendations .....................................................................................
Using Amazon RDS Event Notification .......................................................................................
Amazon RDS Event Categories and Event Messages ............................................................
Subscribing to Amazon RDS Event Notification ...................................................................
Listing Your Amazon RDS Event Notification Subscriptions ...................................................
Modifying an Amazon RDS Event Notification Subscription ..................................................
Adding a Source Identifier to an Amazon RDS Event Notification Subscription .........................
Removing a Source Identifier from an Amazon RDS Event Notification Subscription .................
Listing the Amazon RDS Event Notification Categories ........................................................
Deleting an Amazon RDS Event Notification Subscription ....................................................
Viewing Amazon RDS Events ....................................................................................................
AWS Management Console ..............................................................................................
CLI ................................................................................................................................
API ...............................................................................................................................
....................................................................................................................................
Database Log Files ..................................................................................................................
Viewing and Listing Database Log Files .............................................................................
Downloading a Database Log File .....................................................................................
Watching a Database Log File ..........................................................................................
Publishing to CloudWatch Logs ........................................................................................
Reading Log File Contents Using REST ..............................................................................
MariaDB Database Log Files .............................................................................................
Microsoft SQL Server Database Log Files ...........................................................................
MySQL Database Log Files ...............................................................................................
Oracle Database Log Files ...............................................................................................
PostgreSQL Database Log Files ........................................................................................
Logging Amazon RDS API Calls with AWS CloudTrail ...................................................................
Amazon RDS Information in CloudTrail ..............................................................................
Understanding Amazon RDS Log File Entries ......................................................................
Configuring Security .......................................................................................................................
Authentication and Access Control ............................................................................................
Authentication ...............................................................................................................
Access Control ................................................................................................................
API Version 2014-10-31
vi

233
234
235
237
238
239
240
241
247
250
250
250
250
252
254
260
261
265
266
270
271
271
272
274
275
278
279
284
287
289
291
292
293
294
295
295
295
295
296
297
297
297
299
299
299
301
309
310
318
324
326
326
326
330
330
331
331

Amazon Relational Database Service User Guide

Overview of Managing Access ..........................................................................................
Using Identity-Based Policies (IAM Policies) ........................................................................
Amazon RDS API Permissions Reference ............................................................................
Using Conditions ............................................................................................................
IAM Database Authentication for MySQL and PostgreSQL ....................................................
Encrypting Amazon RDS Resources ...........................................................................................
Overview of Encrypting Amazon RDS Resources .................................................................
Enabling Amazon RDS Encryption for a DB Instance ............................................................
Availability of Amazon RDS Encryption .............................................................................
Managing Amazon RDS Encryption Keys ............................................................................
Limitations of Amazon RDS Encrypted DB Instance .............................................................
Using SSL to Encrypt a Connection ...........................................................................................
Intermediate Certificates .................................................................................................
Controlling Access with Amazon RDS Security Groups .................................................................
DB Security Groups .........................................................................................................
VPC Security Groups .......................................................................................................
DB Security Groups vs. VPC Security Groups ......................................................................
Security Group Scenario ..................................................................................................
Creating a VPC Security Group .........................................................................................
Associating with a DB Instance .........................................................................................
Deleting DB VPC Security Groups .....................................................................................
DB Security Groups on EC2-Classic ...........................................................................................
Creating a DB Security Group ...........................................................................................
Listing Available DB Security Groups .................................................................................
Viewing a DB Security Group ...........................................................................................
Associating with a DB Instance .........................................................................................
Authorizing Network Access to a DB Security Group from an IP Range ...................................
Authorizing Network Access to a DB Instance from an Amazon EC2 Instance ...........................
Revoking Network Access to a DB Instance from an IP Range ...............................................
Master User Account Privileges .................................................................................................
Service-Linked Roles ...............................................................................................................
Service-Linked Role Permissions for Amazon RDS ...............................................................
Creating a Service-Linked Role for Amazon RDS .................................................................
Editing a Service-Linked Role for Amazon RDS ...................................................................
Deleting a Service-Linked Role for Amazon RDS .................................................................
Using Amazon RDS with Amazon VPC .......................................................................................
Determining Whether You Are Using the EC2-VPC or EC2-Classic Platform .............................
Scenarios for Accessing a DB Instance in a VPC ..................................................................
Working with a DB Instance in a VPC ................................................................................
Updating the VPC for a DB Instance .................................................................................
Tutorial: Create an Amazon VPC for Use with an Amazon RDS DB Instance .............................
MariaDB on Amazon RDS ................................................................................................................
Common Management Tasks ...................................................................................................
MariaDB Versions ....................................................................................................................
Version and Feature Support ...................................................................................................
MariaDB 10.3 Support .....................................................................................................
MariaDB 10.2 Support .....................................................................................................
MariaDB 10.1 Support .....................................................................................................
MariaDB 10.0 Support .....................................................................................................
Features Not Supported ..........................................................................................................
Supported Storage Engines .....................................................................................................
MariaDB Security ....................................................................................................................
SSL Support ...........................................................................................................................
Cache Warming ......................................................................................................................
Dumping and Loading the Buffer Pool on Demand .............................................................
Database Parameters ..............................................................................................................
Common DBA Tasks ................................................................................................................
API Version 2014-10-31
vii

332
335
339
355
360
377
378
378
379
379
380
380
381
382
382
382
383
383
384
384
384
387
387
389
389
390
391
392
394
395
397
397
398
398
398
400
400
402
408
413
415
420
420
422
422
422
423
423
424
424
425
425
427
428
429
429
429

Amazon Relational Database Service User Guide

Local Time Zone .....................................................................................................................
Creating a DB Instance Running MariaDB ...................................................................................
AWS Management Console ..............................................................................................
CLI ................................................................................................................................
API ...............................................................................................................................
Available Settings ...........................................................................................................
Related Topics ................................................................................................................
Connecting to a DB Instance Running MariaDB ...........................................................................
Connecting from the mysql Utility ....................................................................................
Connecting with SSL .......................................................................................................
Maximum MariaDB Connections .......................................................................................
Related Topics ................................................................................................................
Modifying a DB Instance Running MariaDB ................................................................................
Available Settings ...........................................................................................................
Related Topics ................................................................................................................
Upgrading the MariaDB DB Engine ...........................................................................................
Overview .......................................................................................................................
AWS Management Console ..............................................................................................
CLI ................................................................................................................................
API ...............................................................................................................................
Related Topics ................................................................................................................
Migrating Data from a MySQL DB Snapshot to a MariaDB DB Instance ...........................................
Incompatibilities Between MariaDB and MySQL ..................................................................
AWS Management Console ..............................................................................................
CLI ................................................................................................................................
API ...............................................................................................................................
Related Topics ................................................................................................................
Working with MariaDB Replication ............................................................................................
Working with MariaDB Read Replicas ................................................................................
Configuring GTID-Based Replication ..................................................................................
Importing Data into a MariaDB DB Instance ...............................................................................
Options for MariaDB ...............................................................................................................
MariaDB Audit Plugin Support .........................................................................................
Parameters for MariaDB ..........................................................................................................
MariaDB on Amazon RDS SQL Reference ...................................................................................
mysql.rds_set_external_master_gtid ..................................................................................
mysql.rds_kill_query_id ....................................................................................................
Microsoft SQL Server on Amazon RDS ..............................................................................................
Common Management Tasks ...................................................................................................
Limits ....................................................................................................................................
DB Instance Class Support .......................................................................................................
Security .................................................................................................................................
Compliance Programs .............................................................................................................
HIPAA ...........................................................................................................................
SSL Support ...........................................................................................................................
Version and Feature Support ...................................................................................................
SQL Server 2017 Support ................................................................................................
SQL Server 2016 Support ................................................................................................
SQL Server 2014 Support ................................................................................................
SQL Server 2012 Support on Amazon RDS ........................................................................
SQL Server 2008 R2 Support on Amazon RDS ....................................................................
Engine Version Management ....................................................................................................
CDC Support ..........................................................................................................................
Features Not Supported ..........................................................................................................
Multi-AZ Deployments ............................................................................................................
Using TDE .............................................................................................................................
Local Time Zone .....................................................................................................................
API Version 2014-10-31
viii

429
431
431
434
435
436
439
440
441
441
442
442
443
444
450
451
451
452
452
452
453
454
454
454
456
457
457
458
458
461
464
465
465
468
473
473
475
476
476
478
479
480
480
481
481
481
481
482
482
483
484
485
485
485
486
486
487

Amazon Relational Database Service User Guide

Supported Time Zones ....................................................................................................
Licensing SQL Server on Amazon RDS .......................................................................................
Restoring License-Terminated DB Instances ........................................................................
Using SQL Server Developer Edition on AWS ......................................................................
Related Topics ................................................................................................................
Creating a DB Instance Running SQL Server ...............................................................................
AWS Management Console ..............................................................................................
CLI ................................................................................................................................
API ...............................................................................................................................
Available Settings ...........................................................................................................
Related Topics ................................................................................................................
Connecting to a DB Instance Running SQL Server .......................................................................
Connecting to Your DB Instance with SSMS .......................................................................
Connecting to Your DB Instance with SQL Workbench/J ......................................................
Security Group Considerations ..........................................................................................
Troubleshooting .............................................................................................................
Related Topics ................................................................................................................
Modifying a DB Instance Running SQL Server ............................................................................
Available Settings ...........................................................................................................
Related Topics ................................................................................................................
Upgrading the SQL Server DB Engine .......................................................................................
Overview .......................................................................................................................
Major Version Upgrades ..................................................................................................
Multi-AZ and In-Memory Optimization Considerations .........................................................
Option and Parameter Group Considerations .....................................................................
Testing an Upgrade ........................................................................................................
AWS Management Console ..............................................................................................
CLI ................................................................................................................................
API ...............................................................................................................................
Related Topics ................................................................................................................
Importing and Exporting SQL Server Databases .........................................................................
Setting Up .....................................................................................................................
Using Native Backup and Restore .....................................................................................
Compressing Backup Files ................................................................................................
Migrating to Amazon RDS by Using Native Backup and Restore ............................................
Troubleshooting .............................................................................................................
Related Topics ................................................................................................................
Importing and Exporting SQL Server Data Using Other Methods ...........................................
Multi-AZ for SQL Server ..........................................................................................................
Adding Multi-AZ to a SQL Server DB Instance ....................................................................
Notes and Recommendations ...........................................................................................
Determining the Location of the Secondary .......................................................................
Migrating to Always On ...................................................................................................
Using SSL with a SQL Server DB Instance ..................................................................................
Forcing SSL ....................................................................................................................
Encrypting Specific Connections .......................................................................................
Related Topics ................................................................................................................
Options for SQL Server ...........................................................................................................
Native Backup and Restore ..............................................................................................
Transparent Data Encryption ............................................................................................
Common DBA Tasks for SQL Server ..........................................................................................
Accessing the tempdb Database .......................................................................................
Analyzing Your Database Workload with SQL Server Tuning Advisor ......................................
Collations and Character Sets ..........................................................................................
Determining a Recovery Model .........................................................................................
Dropping a Multi-AZ Database .........................................................................................
Using CDC .....................................................................................................................
API Version 2014-10-31
ix

487
491
491
491
491
492
492
497
498
499
502
503
503
506
508
508
509
510
511
517
518
518
518
519
519
520
520
520
521
522
523
524
526
529
530
530
531
532
541
541
542
544
544
545
545
546
548
549
549
551
554
555
557
559
560
560
560

Amazon Relational Database Service User Guide

Renaming a Multi-AZ Database ........................................................................................
Resetting the db_owner Role Password ............................................................................
Restoring License-Terminated DB Instances ........................................................................
Transitioning a Database from OFFLINE to ONLINE .............................................................
Using SQL Server Agent ..................................................................................................
Working with SQL Server Logs .........................................................................................
Working with Trace and Dump Files ..................................................................................
Related Topics ................................................................................................................
Advanced Administrative Tasks and Concepts for SQL Server .......................................................
Using Windows Authentication with a SQL Server DB Instance .............................................
MySQL on Amazon RDS ..................................................................................................................
Common Management Tasks ...................................................................................................
MySQL Versions .....................................................................................................................
MySQL Features Not Supported By Amazon RDS ........................................................................
Supported Storage Engines .....................................................................................................
MySQL Security ......................................................................................................................
SSL Support ...........................................................................................................................
Using memcached and Other Options with MySQL .....................................................................
InnoDB Cache Warming ...........................................................................................................
Dumping and Loading the Buffer Pool on Demand .............................................................
Local Time Zone .....................................................................................................................
Known Issues and Limitations ..................................................................................................
Creating a DB Instance Running MySQL ....................................................................................
AWS Management Console ..............................................................................................
CLI ................................................................................................................................
API ...............................................................................................................................
Available Settings ...........................................................................................................
Related Topics ................................................................................................................
Connecting to a DB Instance Running MySQL .............................................................................
Connecting from the MySQL Utility ..................................................................................
Connecting with SSL .......................................................................................................
Maximum MySQL connections ..........................................................................................
Related Topics ................................................................................................................
Modifying a DB Instance Running MySQL ..................................................................................
Available Settings ...........................................................................................................
Related Topics ................................................................................................................
Upgrading the MySQL DB Engine .............................................................................................
Overview .......................................................................................................................
Major Version Upgrades ..................................................................................................
Minor Version Upgrades ..................................................................................................
Testing an Upgrade ........................................................................................................
Upgrading a MySQL Database ..........................................................................................
Upgrading a MySQL Database with Reduced Downtime .......................................................
Upgrading a MySQL DB Snapshot .............................................................................................
Upgrading a MySQL DB Snapshot .....................................................................................
CLI ................................................................................................................................
API ...............................................................................................................................
Related Topics ................................................................................................................
Importing Data into a MySQL DB Instance .................................................................................
Overview .......................................................................................................................
Importing Data Considerations .........................................................................................
Restoring a Backup into an Amazon RDS MySQL DB Instance ...............................................
Importing Data from a MySQL or MariaDB DB to an Amazon RDS MySQL or MariaDB DB
Instance .........................................................................................................................
Importing Data to an Amazon RDS MySQL or MariaDB DB Instance with Reduced Downtime .....
Importing Data From Any Source to a MySQL or MariaDB DB Instance ...................................
Working with MySQL Replication ..............................................................................................
API Version 2014-10-31
x

562
563
563
564
564
565
566
567
567
568
576
576
579
580
581
581
582
584
584
585
585
586
587
587
590
591
592
595
596
597
597
598
599
600
601
607
608
608
608
610
610
611
612
614
614
614
615
615
616
616
618
623
630
632
645
650

Amazon Relational Database Service User Guide

Working with MySQL Read Replicas ..................................................................................
Using GTID-Based Replication ..........................................................................................
Replication with a MySQL or MariaDB Instance Running External to Amazon RDS ....................
Exporting Data From a MySQL DB Instance ................................................................................
Prepare an Instance of MySQL External to Amazon RDS ......................................................
Prepare the Replication Source .........................................................................................
Copy the Database .........................................................................................................
Complete the Export .......................................................................................................
Related Topics ................................................................................................................
Options for MySQL .................................................................................................................
MariaDB Audit Plugin ......................................................................................................
MEMCACHED ....................................................................................................................
Common DBA Tasks for MySQL ................................................................................................
Killing a Session or Query ...............................................................................................
Skipping the Current Replication Error ..............................................................................
Working with InnoDB Tablespaces to Improve Crash Recovery Times .....................................
Managing the Global Status History ..................................................................................
Known Issues and Limitations ..................................................................................................
Inconsistent InnoDB Buffer Pool Size ................................................................................
Index Merge Optimization Returns Wrong Results ...............................................................
Log File Size ..................................................................................................................
MySQL Parameter Exceptions for Amazon RDS DB Instances ................................................
MySQL File Size Limits ....................................................................................................
MySQL on Amazon RDS SQL Reference .....................................................................................
Overview .......................................................................................................................
SQL Reference Conventions .............................................................................................
mysql.rds_set_master_auto_position .................................................................................
mysql.rds_set_external_master .........................................................................................
mysql.rds_set_external_master_with_delay .........................................................................
mysql.rds_set_external_master_with_auto_position .............................................................
mysql.rds_reset_external_master ......................................................................................
mysql.rds_import_binlog_ssl_material ...............................................................................
mysql.rds_remove_binlog_ssl_material ..............................................................................
mysql.rds_set_source_delay ..............................................................................................
mysql.rds_start_replication ..............................................................................................
mysql.rds_start_replication_until .......................................................................................
mysql.rds_start_replication_until_gtid ...............................................................................
mysql.rds_stop_replication ...............................................................................................
mysql.rds_skip_transaction_with_gtid ................................................................................
mysql.rds_skip_repl_error ................................................................................................
mysql.rds_next_master_log ..............................................................................................
mysql.rds_innodb_buffer_pool_dump_now .........................................................................
mysql.rds_innodb_buffer_pool_load_now ...........................................................................
mysql.rds_innodb_buffer_pool_load_abort .........................................................................
mysql.rds_set_configuration .............................................................................................
mysql.rds_show_configuration ..........................................................................................
mysql.rds_kill .................................................................................................................
mysql.rds_kill_query ........................................................................................................
mysql.rds_rotate_general_log ...........................................................................................
mysql.rds_rotate_slow_log ...............................................................................................
mysql.rds_enable_gsh_collector ........................................................................................
mysql.rds_set_gsh_collector .............................................................................................
mysql.rds_disable_gsh_collector .......................................................................................
mysql.rds_collect_global_status_history .............................................................................
mysql.rds_enable_gsh_rotation .........................................................................................
mysql.rds_set_gsh_rotation ..............................................................................................
mysql.rds_disable_gsh_rotation ........................................................................................
API Version 2014-10-31
xi

650
656
660
666
666
667
667
669
669
670
671
674
678
678
678
679
680
682
682
682
683
683
683
685
685
686
686
687
689
691
693
694
695
696
697
697
698
699
700
700
701
703
703
703
704
705
706
706
707
707
707
708
708
708
708
709
709

Amazon Relational Database Service User Guide

mysql.rds_rotate_global_status_history .............................................................................
Oracle on Amazon RDS ...................................................................................................................
Common Management Tasks ...................................................................................................
Licensing ...............................................................................................................................
License Included .............................................................................................................
Bring Your Own License (BYOL) ........................................................................................
Licensing Oracle Multi-AZ Deployments .............................................................................
Migrating Between Oracle Editions ...........................................................................................
DB Instance Class Support .......................................................................................................
DB Instance Class Deprecation .........................................................................................
Security .................................................................................................................................
SSL Support ...........................................................................................................................
Oracle 12c .............................................................................................................................
Oracle 12c Version 12.2.0.1 .............................................................................................
Oracle 12c Version 12.1.0.2 .............................................................................................
Oracle 11g .............................................................................................................................
Oracle 11g Supported Features ........................................................................................
Oracle 11g Features Not Supported ..................................................................................
Amazon RDS Parameters for Oracle 11g ............................................................................
Engine Version Management ....................................................................................................
Deprecation of Oracle 11.2.0.2 .........................................................................................
Deprecation of Oracle 11.2.0.3 .........................................................................................
Deprecation of Oracle 12.1.0.1 .........................................................................................
Using Huge Pages ..................................................................................................................
Using utl_http, utl_tcp, and utl_smtp ........................................................................................
Using OEM, APEX, TDE, and Other Options ................................................................................
Using Extended Data Types .....................................................................................................
Enabling Extended Data Types for a New DB Instance .........................................................
Enabling Extended Data Types for an Existing DB Instance ...................................................
Creating a DB Instance Running Oracle .....................................................................................
AWS Management Console ..............................................................................................
CLI ................................................................................................................................
API ...............................................................................................................................
Available Settings ...........................................................................................................
Related Topics ................................................................................................................
Connecting to a DB Instance Running Oracle .............................................................................
Finding the Endpoint ......................................................................................................
SQL Developer ...............................................................................................................
SQL*Plus .......................................................................................................................
Security Group Considerations ..........................................................................................
Dedicated and Shared Server Processes .............................................................................
Troubleshooting .............................................................................................................
Related Topics ................................................................................................................
Modifying a DB Instance Running Oracle ...................................................................................
Available Settings ...........................................................................................................
Modifying Oracle sqlnet.ora Parameters ............................................................................
Upgrading the Oracle DB Engine ..............................................................................................
Overview .......................................................................................................................
Major Version Upgrades ..................................................................................................
Minor Version Upgrades ..................................................................................................
SE2 Upgrade Paths .........................................................................................................
Option and Parameter Group Considerations .....................................................................
Testing an Upgrade ........................................................................................................
AWS Management Console ..............................................................................................
CLI ................................................................................................................................
API ...............................................................................................................................
Related Topics ................................................................................................................
API Version 2014-10-31
xii

709
710
710
712
712
712
713
713
713
715
716
716
717
717
720
726
726
727
727
727
728
728
728
729
731
732
732
732
733
734
734
737
738
738
742
743
743
744
747
747
748
748
749
750
751
760
763
763
763
764
764
765
765
766
766
767
768

Amazon Relational Database Service User Guide

Upgrading an Oracle DB Snapshot ............................................................................................
AWS Management Console ..............................................................................................
CLI ................................................................................................................................
API ...............................................................................................................................
Related Topics ................................................................................................................
Importing Data into Oracle on Amazon RDS ..............................................................................
Oracle SQL Developer .....................................................................................................
Oracle Data Pump ..........................................................................................................
Oracle Export/Import Utilities ..........................................................................................
Oracle SQL*Loader ..........................................................................................................
Oracle Materialized Views ................................................................................................
Oracle Character Sets ..............................................................................................................
Options for Oracle ..................................................................................................................
Application Express (APEX) ..............................................................................................
Enterprise Manager .........................................................................................................
Java Virtual Machine (JVM) ..............................................................................................
Label Security ................................................................................................................
Locator ..........................................................................................................................
Multimedia ....................................................................................................................
Native Network Encryption (NNE) .....................................................................................
Secure Sockets Layer (SSL) ..............................................................................................
Spatial ..........................................................................................................................
SQLT .............................................................................................................................
Statspack .......................................................................................................................
Time Zone .....................................................................................................................
Transparent Data Encryption (TDE) ...................................................................................
UTL_MAIL ......................................................................................................................
XML DB .........................................................................................................................
Common DBA Tasks for Oracle .................................................................................................
System Tasks .................................................................................................................
Database Tasks ...............................................................................................................
Log Tasks ......................................................................................................................
Miscellaneous Tasks ........................................................................................................
Related Topics ................................................................................................................
Tools and Third-Party Software for Oracle .................................................................................
Setting Up .....................................................................................................................
Using AWS CloudHSM Classic to Store Amazon RDS Oracle TDE Keys ....................................
Using Oracle GoldenGate ................................................................................................
Using the Oracle Repository Creation Utility ......................................................................
Installing a Siebel Database on Oracle on Amazon RDS .......................................................
Oracle Database Engine Release Notes ......................................................................................
Oracle Version 12.2.0.1 ...................................................................................................
Oracle Versions 12.1.0.2 and 11.2.0.4 ...............................................................................
Database Engine: 12.2.0.1 ...............................................................................................
Database Engine: 12.1.0.2 ...............................................................................................
Database Engine: 11.2.0.4 ...............................................................................................
PostgreSQL on Amazon RDS ............................................................................................................
Common Management Tasks for PostgreSQL on Amazon RDS ......................................................
Creating a DB Instance Running PostgreSQL ..............................................................................
Create a PostgreSQL DB Instance .....................................................................................
CLI ................................................................................................................................
API ...............................................................................................................................
Related Topics ................................................................................................................
Connecting to a DB Instance Running the PostgreSQL Database Engine .........................................
Using pgAdmin to Connect to a PostgreSQL DB Instance .....................................................
Using psql to Connect to a PostgreSQL DB Instance ............................................................
Troubleshooting Connection Issues ...................................................................................
API Version 2014-10-31
xiii

769
769
769
770
771
772
772
772
776
776
777
779
782
783
790
799
802
805
808
810
812
818
820
825
828
831
833
835
837
840
849
861
868
869
870
870
881
897
908
913
916
916
916
917
919
939
960
960
964
964
968
968
969
970
970
971
972

Amazon Relational Database Service User Guide

Modifying a DB Instance Running PostgreSQL ............................................................................ 973
Available Settings ........................................................................................................... 974
Related Topics ................................................................................................................ 981
Upgrading the PostgreSQL DB Engine ....................................................................................... 982
Overview ....................................................................................................................... 982
Major Version Upgrades .................................................................................................. 982
Minor Version Upgrades .................................................................................................. 985
AWS Management Console .............................................................................................. 985
CLI ................................................................................................................................ 985
API ............................................................................................................................... 986
Related Topics ................................................................................................................ 986
Working with PostgreSQL Read Replicas .................................................................................... 987
Read Replica Configuration with PostgreSQL ...................................................................... 987
Monitoring PostgreSQL Read Replicas ............................................................................... 988
Read Replica Limitations with PostgreSQL ......................................................................... 988
Replication Interruptions with PostgreSQL Read Replicas ..................................................... 988
Troubleshooting a PostgreSQL Read Replica Problem .......................................................... 988
Importing Data into PostgreSQL on Amazon RDS ....................................................................... 991
Importing a PostgreSQL Database from an Amazon EC2 Instance ......................................... 992
Using the \copy Command to Import Data to a Table on a PostgreSQL DB Instance ................. 993
Common DBA Tasks for PostgreSQL ......................................................................................... 995
Creating Roles ................................................................................................................ 995
Managing PostgreSQL Database Access ............................................................................. 996
Working with PostgreSQL Parameters ............................................................................... 996
Working with PostgreSQL Autovacuum ............................................................................ 1004
Audit Logging for a PostgreSQL DB Instance .................................................................... 1012
Working with the pgaudit Extension ............................................................................... 1012
Working with the pg_repack Extension ............................................................................ 1014
Working with PostGIS .................................................................................................... 1015
Using pgBadger for Log Analysis with PostgreSQL ............................................................ 1017
Viewing the Contents of pg_config ................................................................................. 1017
Working with the orafce Extension .................................................................................. 1018
Accessing External Data with the postgres_fdw Extension .................................................. 1019
Using a Custom DNS Server for Outbound Network Access ................................................ 1019
Working with the Database Preview Environment ..................................................................... 1020
Features Not Supported in the Preview Environment ......................................................... 1021
PostgreSQL Extensions Supported in the Preview Environment ........................................... 1021
Creating a New DB Instance in the Preview Environment .................................................... 1023
PostgreSQL Versions and Extensions ....................................................................................... 1023
Supported PostgreSQL Database Versions ........................................................................ 1024
Supported Features and Extensions ................................................................................. 1036
Limits .......................................................................................................................................... 1063
Limits in Amazon RDS ........................................................................................................... 1063
Naming Constraints in Amazon RDS ........................................................................................ 1064
File Size Limits in Amazon RDS .............................................................................................. 1066
MySQL File Size Limits in Amazon RDS ............................................................................ 1066
MariaDB File Size Limits in Amazon RDS ......................................................................... 1067
Troubleshooting ............................................................................................................................ 1069
Cannot Connect to DB Instance .............................................................................................. 1069
Testing the DB Instance Connection ................................................................................ 1069
Troubleshooting Connection Authentication ..................................................................... 1070
Security Issues ...................................................................................................................... 1070
Error Message "Failed to retrieve account attributes, certain console functions may be
impaired." .................................................................................................................... 1070
Resetting the DB Instance Owner Role Password ...................................................................... 1071
DB Instance Outage or Reboot ............................................................................................... 1071
Parameter Changes Not Taking Effect ..................................................................................... 1072
API Version 2014-10-31
xiv

Amazon Relational Database Service User Guide

DB Instance Out of Storage ...................................................................................................
Insufficient DB Instance Capacity ............................................................................................
MySQL Issues .......................................................................................................................
Index Merge Optimization Returns Wrong Results .............................................................
Diagnosing and Resolving Lag Between Read Replicas .......................................................
Diagnosing and Resolving a MySQL or MariaDB Read Replication Failure ..............................
Creating Triggers with Binary Logging Enabled Requires SUPER Privilege .............................
Diagnosing and Resolving Point-In-Time Restore Failures ...................................................
Slave Down or Disabled Error .........................................................................................
Read Replica Create Fails or Replication Breaks With Fatal Error 1236 ..................................
Oracle GoldenGate Issues ......................................................................................................
Retaining Logs for Sufficient Time ..................................................................................
Cannot Connect to SQL Server DB Instance .............................................................................
Cannot Connect to PostgreSQL DB Instance .............................................................................
Cannot set backup retention to 0 ...........................................................................................
Amazon RDS API Reference ............................................................................................................
Using the Query API .............................................................................................................
Query Parameters .........................................................................................................
Query Request Authentication ........................................................................................
Troubleshooting Applications .................................................................................................
Retrieving Errors ...........................................................................................................
Troubleshooting Tips .....................................................................................................
Document History .........................................................................................................................
Earlier Updates .....................................................................................................................

API Version 2014-10-31
xv

1072
1073
1073
1074
1074
1075
1076
1078
1078
1079
1079
1079
1079
1080
1080
1081
1081
1081
1081
1082
1082
1082
1083
1089

Amazon Relational Database Service User Guide
Overview

What Is Amazon Relational Database
Service (Amazon RDS)?
Amazon Relational Database Service (Amazon RDS) is a web service that makes it easier to set up,
operate, and scale a relational database in the cloud. It provides cost-efficient, resizable capacity for an
industry-standard relational database and manages common database administration tasks.

Note

This guide covers non-Aurora Amazon RDS database engines. For information about using
Amazon Aurora, see the Amazon Aurora User Guide.

Overview of Amazon RDS
Why do you want a managed relational database service? Because Amazon RDS takes over many of the
difficult or tedious management tasks of a relational database:
• When you buy a server, you get CPU, memory, storage, and IOPS, all bundled together. With Amazon
RDS, these are split apart so that you can scale them independently. If you need more CPU, less IOPS,
or more storage, you can easily allocate them.
• Amazon RDS manages backups, software patching, automatic failure detection, and recovery.
• To deliver a managed service experience, Amazon RDS doesn't provide shell access to DB instances,
and it restricts access to certain system procedures and tables that require advanced privileges.
• You can have automated backups performed when you need them, or manually create your own
backup snapshot. You can use these backups to restore a database. The Amazon RDS restore process
works reliably and efficiently.
• You can get high availability with a primary instance and a synchronous secondary instance that you
can fail over to when problems occur. You can also use MySQL, MariaDB, or PostgreSQL Read Replicas
to increase read scaling.
• You can use the database products you are already familiar with: MySQL, MariaDB, PostgreSQL, Oracle,
Microsoft SQL Server.
• In addition to the security in your database package, you can help control who can access your RDS
databases by using AWS Identity and Access Management (IAM) to define users and permissions. You
can also help protect your databases by putting them in a virtual private cloud.
If you are new to AWS products and services, begin learning more with the following resources:
• For an overview of all AWS products, see What is Cloud Computing?.
• Amazon Web Services provides a number of database services. For guidance on which service is best
for your environment, see Running Databases on AWS.

DB Instances
The basic building block of Amazon RDS is the DB instance. A DB instance is an isolated database
environment in the cloud. A DB instance can contain multiple user-created databases, and you can
access it by using the same tools and applications that you use with a stand-alone database instance. You
API Version 2014-10-31
1

Amazon Relational Database Service User Guide
Regions and Availability Zones

can create and modify a DB instance by using the AWS Command Line Interface, the Amazon RDS API, or
the AWS Management Console.
Each DB instance runs a DB engine. Amazon RDS currently supports the MySQL, MariaDB, PostgreSQL,
Oracle, and Microsoft SQL Server DB engines. Each DB engine has its own supported features, and
each version of a DB engine may include specific features. Additionally, each DB engine has a set of
parameters in a DB parameter group that control the behavior of the databases that it manages.
The computation and memory capacity of a DB instance is determined by its DB instance class. You can
select the DB instance that best meets your needs. If your needs change over time, you can change DB
instances. For information, see DB Instance Class (p. 80).

Note

For pricing information on DB instance classes, go to the Pricing section of the Amazon RDS
product page.
DB instance storage comes in three types: Magnetic, General Purpose (SSD), and Provisioned IOPS
(PIOPS). They differ in performance characteristics and price, allowing you to tailor your storage
performance and cost to the needs of your database. Each DB instance has minimum and maximum
storage requirements depending on the storage type and the database engine it supports. It’s important
to have sufficient storage so that your databases have room to grow and that features for the DB engine
have room to write content or log entries. For more information, see DB instance storage (p. 101).
You can run a DB instance on a virtual private cloud using the Amazon Virtual Private Cloud
(VPC) service. When you use a virtual private cloud, you have control over your virtual networking
environment: you can select your own IP address range, create subnets, and configure routing and access
control lists. The basic functionality of Amazon RDS is the same whether it is running in a VPC or not;
Amazon RDS manages backups, software patching, automatic failure detection, and recovery. There is
no additional cost to run your DB instance in a VPC. For more information on VPC and RDS, see Amazon
Virtual Private Cloud (VPCs) and Amazon RDS (p. 400).
Amazon RDS uses Network Time Protocol (NTP) to synchronize the time on DB Instances.

Regions and Availability Zones
Amazon cloud computing resources are housed in highly available data center facilities in different areas
of the world (for example, North America, Europe, or Asia). Each data center location is called a region.
Each region contains multiple distinct locations called Availability Zones, or AZs. Each Availability Zone
is engineered to be isolated from failures in other Availability Zones, and to provide inexpensive, lowlatency network connectivity to other Availability Zones in the same region. By launching instances in
separate Availability Zones, you can protect your applications from the failure of a single location. For
more information, see Regions and Availability Zones (p. 99).
You can run your DB instance in several Availability Zones, an option called a Multi-AZ deployment.
When you select this option, Amazon automatically provisions and maintains a secondary standby DB
instance in a different Availability Zone. Your primary DB instance is synchronously replicated across
Availability Zones to the secondary instance to provide data redundancy, failover support, eliminate I/O
freezes, and minimize latency spikes during system backups. For more information, see High Availability
(Multi-AZ) for Amazon RDS (p. 107).

Security
A security group controls the access to a DB instance. It does so by allowing access to IP address ranges
or Amazon EC2 instances that you specify.
API Version 2014-10-31
2

Amazon Relational Database Service User Guide
Monitoring an Amazon RDS DB Instance

Amazon RDS uses DB security groups, VPC security groups, and EC2 security groups. In simple
terms, a DB security group controls access to a DB instance that is not in a VPC, a VPC security group
controls access to a DB instance inside a VPC, and an Amazon EC2 security group controls access to
an EC2 instance and can be used with a DB instance. For more information about security groups, see
Configuring Security in Amazon RDS (p. 330).

Monitoring an Amazon RDS DB Instance
There are several ways that you can track the performance and health of a DB instance. You can use the
free Amazon CloudWatch service to monitor the performance and health of a DB instance; performance
charts are shown in the Amazon RDS console. You can subscribe to Amazon RDS events to be notified
when changes occur with a DB instance, DB Snapshot, DB parameter group, or DB security group. For
more information, see Monitoring Amazon RDS (p. 238).

Amazon RDS Interfaces
There are several ways that you can interact with Amazon RDS.

AWS Management Console
The AWS Management Console is a simple web-based user interface. You can manage your DB instances
from the console with no programming required. To access the Amazon RDS console, sign in to the AWS
Management Console and open the Amazon RDS console at https://console.aws.amazon.com/rds/.

Command Line Interface
You can use the AWS Command Line Interface (AWS CLI) to access the Amazon RDS API interactively. To
install the AWS CLI, see Installing the AWS Command Line Interface. To begin using the AWS CLI for RDS,
see AWS Command Line Interface Reference for Amazon RDS.

Programming with Amazon RDS
If you are a developer, you can access the Amazon RDS programmatically. For more information, see
Amazon RDS Application Programming Interface (API) Reference (p. 1081).
For application development, we recommend that you use one of the AWS Software Development Kits
(SDKs). The AWS SDKs handle low-level details such as authentication, retry logic, and error handling, so
that you can focus on your application logic. AWS SDKs are available for a wide variety of languages. For
more information, see Tools for Amazon Web Services .
AWS also provides libraries, sample code, tutorials, and other resources to help you get started more
easily. For more information, see Sample Code & Libraries.

How You Are Charged for Amazon RDS
When you use Amazon RDS, you can choose to use on-demand DB instances or reserved DB instances.
For more information, see DB Instance Billing for Amazon RDS (p. 188).
For Amazon RDS pricing information, see the Amazon RDS product page.
API Version 2014-10-31
3

Amazon Relational Database Service User Guide
What's Next?

What's Next?
The preceding section introduced you to the basic infrastructure components that RDS offers. What
should you do next?

Getting Started
Create a DB instance using instructions in the Getting Started with Amazon RDS (p. 10) section.

Database Engine–Specific Topics
You can review information specific to a particular DB engine in the following sections:
• MariaDB on Amazon RDS (p. 420)
• Microsoft SQL Server on Amazon RDS (p. 476)
• MySQL on Amazon RDS (p. 576)
• Oracle on Amazon RDS (p. 710)
• PostgreSQL on Amazon RDS (p. 960)

API Version 2014-10-31
4

Amazon Relational Database Service User Guide
Sign Up for AWS

Setting Up for Amazon RDS
Following, you can find how to set up Amazon Relational Database Service (Amazon RDS) for the first
time. If you already have an AWS account, know your Amazon RDS requirements, and prefer to use the
defaults for IAM and VPC security groups, skip ahead to Getting Started (p. 4).
A couple things you should know about Amazon Web Services (AWS):
• When you sign up for AWS, your AWS account automatically has access to all services in AWS,
including Amazon RDS. However, you are charged only for the services that you use.
• With Amazon RDS, you pay only for the RDS instances that are active. The Amazon RDS DB instance
that you create is live (not running in a sandbox). You incur the standard Amazon RDS usage fees for
the instance until you terminate it. For more information about Amazon RDS usage rates, see the
Amazon RDS product page.
Topics
• Sign Up for AWS (p. 5)
• Create an IAM User (p. 5)
• Determine Requirements (p. 7)
• Provide Access to Your DB Instance in Your VPC by Creating a Security Group (p. 8)

Sign Up for AWS
If you have an AWS account already, skip to the next section, Create an IAM User (p. 5).
If you don't have an AWS account, you can use the following procedure to create one. If you are a new
AWS customer, you can get started with Amazon RDS for free; for more information, see AWS Free Usage
Tier.

To create a new AWS account
1.

Open https://aws.amazon.com/, and then choose Create an AWS Account.

Note

2.

If you previously signed in to the AWS Management Console using AWS account root user
credentials, choose Sign in to a different account. If you previously signed in to the console
using IAM credentials, choose Sign-in using root account credentials. Then choose Create
a new AWS account.
Follow the online instructions.
Part of the sign-up procedure involves receiving a phone call and entering a verification code using
the phone keypad.

Create an IAM User
After you create an AWS account and successfully connect to the AWS Management Console, you can
create an AWS Identity and Access Management (IAM) user. Instead of signing in with your AWS root
account, we recommend that you use an IAM administrative user with Amazon RDS.
One way to do this is to create a new IAM user and grant it administrator permissions. Alternatively, you
can add an existing IAM user to an IAM group with Amazon RDS administrative permissions. You can then
access AWS from a special URL using the credentials for the IAM user.
API Version 2014-10-31
5

Amazon Relational Database Service User Guide
Create an IAM User

If you signed up for AWS but haven't created an IAM user for yourself, you can create one using the IAM
console.

To create an IAM user for yourself and add the user to an Administrators group
1.

Use your AWS account email address and password to sign in as the AWS account root user to the
IAM console at https://console.aws.amazon.com/iam/.

Note

2.

We strongly recommend that you adhere to the best practice of using the Administrator
IAM user below and securely lock away the root user credentials. Sign in as the root user
only to perform a few account and service management tasks.
In the navigation pane of the console, choose Users, and then choose Add user.

3.

For User name, type Administrator.

4.

Select the check box next to AWS Management Console access, select Custom password, and then
type the new user's password in the text box. You can optionally select Require password reset to
force the user to create a new password the next time the user signs in.

5.
6.

Choose Next: Permissions.
On the Set permissions page, choose Add user to group.

7.

Choose Create group.

8.

In the Create group dialog box, for Group name type Administrators.

9. For Filter policies, select the check box for AWS managed - job function.
10. In the policy list, select the check box for AdministratorAccess. Then choose Create group.
11. Back in the list of groups, select the check box for your new group. Choose Refresh if necessary to
see the group in the list.
12. Choose Next: Review to see the list of group memberships to be added to the new user. When you
are ready to proceed, choose Create user.
You can use this same process to create more groups and users, and to give your users access to your
AWS account resources. To learn about using policies to restrict users' permissions to specific AWS
resources, go to Access Management and Example Policies.
To sign in as the new IAM user, first sign out of the AWS Management Console. Then use the following
URL, where your_aws_account_id is your AWS account number without the hyphens. For example, if
your AWS account number is 1234-5678-9012, your AWS account ID is 123456789012.
https://your_aws_account_id.signin.aws.amazon.com/console/

Type the IAM user name and password that you just created. When you're signed in, the navigation bar
displays "your_user_name @ your_aws_account_id".
If you don't want the URL for your sign-in page to contain your AWS account ID, you can create an
account alias. From the IAM dashboard, choose Customize and type an alias, such as your company
name. To sign in after you create an account alias, use the following URL.
https://your_account_alias.signin.aws.amazon.com/console/

To verify the sign-in link for IAM users for your account, open the IAM console and check under AWS
Account Alias on the dashboard.
You can also create access keys for your AWS account. These access keys can be used to access AWS
through the AWS Command Line Interface (AWS CLI) or through the Amazon RDS API. For more
information, see Managing Access Keys for Your AWS Account, Installing the AWS Command Line
Interface, and the Amazon RDS API Reference.
API Version 2014-10-31
6

Amazon Relational Database Service User Guide
Determine Requirements

Determine Requirements
The basic building block of Amazon RDS is the DB instance. In a DB instance, you create your databases.
A DB instance provides a network address called an endpoint. Your applications use this endpoint to
connect to your DB instance. When you create a DB instance, you specify details like storage, memory,
database engine and version, network configuration, security, and maintenance periods. You control
network access to a DB instance through a security group.
Before you create a DB instance and a security group, you must know your DB instance and network
needs. Here are some important things to consider:
• Resource requirements – What are the memory and processor requirements for your application or
service? You use these settings to help you determine what DB instance class to use. For specifications
about DB instance classes, see DB Instance Class (p. 80).
• VPC, subnet, and security group – Your DB instance is most likely in a virtual private cloud (VPC). To
connect to your DB instance, you need to set up security group rules. These rules are set up differently
depending on what kind of VPC you use and how you use it: in a default VPC, in a user-defined VPC, or
outside of a VPC.

Note

Some legacy accounts don't use a VPC. If you are accessing a new AWS Region or you are a
new RDS user (after 2013), you are most likely creating a DB instance inside a VPC.
For information on how to determine if your account has a default VPC in a particular AWS Region, see
Determining Whether You Are Using the EC2-VPC or EC2-Classic Platform (p. 400).
The following list describes the rules for each VPC option:
• Default VPC – If your AWS account has a default VPC in the current AWS Region, that VPC is
configured to support DB instances. If you specify the default VPC when you create the DB instance,
do the following:
• Create a VPC security group that authorizes connections from the application or service to the
Amazon RDS DB instance with the database. Use the Amazon EC2 API or the Security Group
option on the VPC console to create VPC security groups. For information, see Step 4: Create a
VPC Security Group (p. 412).
• Specify the default DB subnet group. If this is the first DB instance you have created in this AWS
Region, Amazon RDS creates the default DB subnet group when it creates the DB instance.
• User-defined VPC – If you want to specify a user-defined VPC when you create a DB instance, be
aware of the following:
• Make sure to create a VPC security group that authorizes connections from the application or
service to the Amazon RDS DB instance with the database. Use the Amazon EC2 API or the
Security Group option on the VPC console to create VPC security groups. For information, see
Step 4: Create a VPC Security Group (p. 412).
• The VPC must meet certain requirements in order to host DB instances, such as having at least two
subnets, each in a separate availability zone. For information, see Amazon Virtual Private Cloud
(VPCs) and Amazon RDS (p. 400).
• Make sure to specify a DB subnet group that defines which subnets in that VPC can be used by the
DB instance. For information, see the DB subnet group section in Working with a DB Instance in a
VPC (p. 408).
• No VPC – If your AWS account doesn't have a default VPC and you don't specify a user-defined VPC,
create a DB security group. A DB security group authorizes connections from the devices and Amazon
RDS instances running the applications or utilities to access the databases in the DB instance. For
more information, see Working with DB Security Groups (EC2-Classic Platform) (p. 387).
• High availability: Do you need failover support? On Amazon RDS, a Multi-AZ deployment creates a
primary DB instance and a secondary standby DB instance in another Availability Zone for failover
support. We recommend Multi-AZ deployments for production workloads to maintain high availability.
API Version 2014-10-31
7

Amazon Relational Database Service User Guide
Provide Access to Your DB Instance in
Your VPC by Creating a Security Group

For development and test purposes, you can use a deployment that isn't Multi-AZ. For more
information, see High Availability (Multi-AZ) for Amazon RDS (p. 107).
• IAM policies: Does your AWS account have policies that grant the permissions needed to perform
Amazon RDS operations? If you are connecting to AWS using IAM credentials, your IAM account must
have IAM policies that grant the permissions required to perform Amazon RDS operations. For more
information, see Authentication and Access Control (p. 330).
• Open ports: What TCP/IP port does your database listen on? The firewall at some companies might
block connections to the default port for your database engine. If your company firewall blocks the
default port, choose another port for the new DB instance. When you create a DB instance that listens
on a port you specify, you can change the port by modifying the DB instance.
• AWS Region: What AWS Region do you want your database in? Having your database in close
proximity to your application or web service can reduce network latency.
• DB disk subsystem: What are your storage requirements? Amazon RDS provides three storage types:
• Magnetic (Standard Storage)
• General Purpose (SSD)
• Provisioned IOPS (PIOPS)
Magnetic storage offers cost-effective storage that is ideal for applications with light or burst I/
O requirements. General purpose, SSD-backed storage, also called gp2, can provide faster access
than disk-based storage. Provisioned IOPS storage is designed to meet the needs of I/O-intensive
workloads, particularly database workloads, which are sensitive to storage performance and
consistency in random access I/O throughput. For more information on Amazon RDS storage, see DB
instance storage (p. 101).
When you have the information you need to create the security group and the DB instance, continue to
the next step.

Provide Access to Your DB Instance in Your VPC by
Creating a Security Group
VPC security groups provide access to DB instances in a VPC. They act as a firewall for the associated DB
instance, controlling both inbound and outbound traffic at the instance level. DB instances are created by
default with a firewall and a default security group that protect the DB instance.
Before you can connect to your DB instance, you must add rules to security group that enable you to
connect. Use your network and configuration information to create rules to allow access to your DB
instance.

Note

If your legacy DB instance was created before March 2013 and isn't in a VPC, it might not have
associated security groups. If your DB instance was created after this date, it might be inside a
default VPC.
For example, suppose that you have an application that accesses a database on your DB instance in a
VPC. In this case, you must add a custom TCP rule that specifies the port range and IP addresses that
your application uses to access the database. If you have an application on an Amazon EC2 instance, you
can use the VPC or EC2 security group that you set up for the Amazon EC2 instance.

To create a VPC security group
1.

Sign in to the AWS Management Console and open the Amazon VPC console at https://
console.aws.amazon.com/vpc.
API Version 2014-10-31
8

Amazon Relational Database Service User Guide
Provide Access to Your DB Instance in
Your VPC by Creating a Security Group

2.

3.

In the top right corner of the AWS Management Console, choose the AWS Region where you want
to create your VPC security group and DB instance. In the list of Amazon VPC resources for that AWS
Region, you should see at least one VPC and several subnets. If you don't, you don't have a default
VPC in that AWS Region.
In the navigation pane, choose Security Groups.

4.
5.

Choose Create Security Group.
In the Create Security Group window, type Name tag, Group name, and Description values for your
security group. For VPC, choose the VPC that you want to create your DB instance in. Choose Yes,
Create.

6.

The VPC security group that you created should still be selected. If not, locate it in the list, and
choose it. The details pane at the bottom of the console window displays the details for the security
group, and tabs for working with inbound and outbound rules. Choose the Inbound Rules tab.

7.

On the Inbound Rules tab, choose Edit.

8.
9.

a.

For Type, choose Custom TCP Rule.

b.
c.

For Port Range, type the port value to use for your DB instance.
For Source, choose a security group name or type the IP address range (CIDR value) from where
you access the instance.

Choose Add another rule if you need to add more IP addresses or different port ranges.
(Optional) Use the Outbound Rules tab to add rules for outbound traffic. By default, all outbound
traffic is allowed.

You can use the VPC security group that you just created as the security group for your DB instance when
you create it. If your DB instance isn't going to be in a VPC, see Working with DB Security Groups (EC2Classic Platform) (p. 387) to create a DB security group to use when you create your DB instance.

Note

If you use a default VPC, a default subnet group spanning all of the VPC's subnets is created
for you. When you create a DB instance, you can select the default VPC and use default for DB
Subnet Group.
Once you have completed the setup requirements, you can launch a DB instance using your requirements
and security group. For information on creating a DB instance, see the relevant documentation in the
following table.
Database Engine

Documentation

MariaDB

Creating a MariaDB DB Instance and Connecting to a Database on a MariaDB
DB Instance (p. 10)

Microsoft SQL Server

Creating a Microsoft SQL Server DB Instance and Connecting to a DB
Instance (p. 18)

MySQL

Creating a MySQL DB Instance and Connecting to a Database on a MySQL
DB Instance (p. 28)

Oracle

Creating an Oracle DB Instance and Connecting to a Database on an Oracle
DB Instance (p. 36)

PostgreSQL

Creating a PostgreSQL DB Instance and Connecting to a Database on a
PostgreSQL DB Instance (p. 40)

API Version 2014-10-31
9

Amazon Relational Database Service User Guide
Creating a MariaDB DB Instance
and Connecting to a Database

Getting Started with Amazon RDS
This section shows you how to create and connect to a DB instance using Amazon Relational Database
Service (Amazon RDS). You can create, or launch, a DB instance that uses MySQL, Oracle, PostgreSQL,
Microsoft SQL Server, or MariaDB.

Important

You must complete the tasks in the Setting Up for Amazon RDS (p. 5) section before you can
create or connect to a DB instance.
Creating a DB instance and connecting to a database on a DB instance is slightly different for each of the
DB engines. Choose the DB engine following that you want to use for detailed information on creating
and connecting to the DB instance. After you have created and connected to your DB instance, there are
instructions to help you delete the DB instance.
Topics
• Creating a MariaDB DB Instance and Connecting to a Database on a MariaDB DB Instance (p. 10)
• Creating a Microsoft SQL Server DB Instance and Connecting to a DB Instance (p. 18)
• Creating a MySQL DB Instance and Connecting to a Database on a MySQL DB Instance (p. 28)
• Creating an Oracle DB Instance and Connecting to a Database on an Oracle DB Instance (p. 36)
• Creating a PostgreSQL DB Instance and Connecting to a Database on a PostgreSQL DB
Instance (p. 40)
• Tutorial: Create a Web Server and an Amazon RDS Database (p. 48)

Creating a MariaDB DB Instance and Connecting to
a Database on a MariaDB DB Instance
The easiest way to create a MariaDB DB instance is to use the Amazon RDS console. Once you have
created the DB instance, you can use command line tools such as mysql or standard graphical tools such
as HeidiSQL to connect to a database on the DB instance.

Important

You must complete the tasks in the Setting Up for Amazon RDS (p. 5) section before you can
create or connect to a DB instance.
Topics
• Creating a MariaDB Instance (p. 10)
• Connecting to a Database on a DB Instance Running the MariaDB Database Engine (p. 15)
• Deleting a DB Instance (p. 17)

Creating a MariaDB Instance
The basic building block of Amazon RDS is the DB instance. This environment is where you run your
MariaDB databases.
In this example, you create a DB instance running the MariaDB database engine called mariadbinstance1, with a db.t2.small DB instance class, 20 GiB of storage, and automated backups enabled with a
retention period of one day.
API Version 2014-10-31
10

Amazon Relational Database Service User Guide
Creating a MariaDB Instance

To create a MariaDB DB instance
1.

Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.

2.

In the top right corner of the Amazon RDS console, choose the region in which you want to create
the DB instance.

3.

In the navigation pane, choose Instances.
If the navigation pane is closed, choose the menu icon at the top left to open it.

4.

Choose Create database. The Select engine page opens.

5.

Choose the MariaDB, and then choose Next.

6.

The Choose use case page asks if you plan to use the DB instance you are creating for production.
Because this is an example instance, choose Dev/Test - MariaDB. Then, choose Next.

Note

If you create a production instance, you typically choose Production - MariaDB on this page
to enable the failover option Multi-AZ and the Provisioned IOPS storage option.
API Version 2014-10-31
11

Amazon Relational Database Service User Guide
Creating a MariaDB Instance

7.

On the Specify DB details page, specify your DB instance information. The following table shows
settings for an example DB instance. When the settings are as you want them, choose Next.

For This Parameter

Do This

License model

Choose the default, general-public-license, to use the
GNU General Public License, version 2 for MariaDB.
MariaDB has only one license model.

DB engine version

Choose the version of MariaDB that you want to use.

DB instance class

Choose db.t2.small for a configuration that equates to
2 GiB memory, 1 ECU (1 virtual core with 1 ECU), 64-bit
platform, and moderate I/O capacity.

Multi-AZ deployment

Choose Create replica in a different zone
to have a standby replica of your DB instance created
in another Availability Zone for failover support. We
recommend Multi-AZ for production workloads to
maintain high availability. For development and testing,
you can choose No.
For more information, see High Availability (Multi-AZ) for
Amazon RDS (p. 107).

Storage type

Choose the storage type General Purpose (SSD). For
more information about storage, see DB instance
storage (p. 101).

Allocated storage

Type 20 to allocate 20 GiB of storage for your database.
In some cases, allocating a higher amount of storage
for your DB instance than the size of your database can
improve I/O performance. For more information about
storage allocation, see Amazon RDS Features.

DB instance identifier

Type a name for the DB instance that is unique for your
account in the region you chose. You can add some
intelligence to the name, such as including the region and
DB engine you chose, for example mariadb-instance1.

Master username

Type a name using 1-16 alphanumeric characters to use
as the master user name to log on to your DB instance.
You use this user name to log on to your database on the
DB instance for the first time.

Master password and Confirm
password

Type a password that contains from 8 to 41 printable
ASCII characters (excluding /,", and @) for your master
user password. You use this password with the user name
when you log on to your database. Type the password
again in the Confirm Password box.

API Version 2014-10-31
12

Amazon Relational Database Service User Guide
Creating a MariaDB Instance

API Version 2014-10-31
13

Amazon Relational Database Service User Guide
Creating a MariaDB Instance

8.

On the Configure advanced settings page, provide additional information that RDS needs to launch
the MariaDB DB instance. The table shows settings for an example DB instance. Specify your DB
instance information, then choose Create database.

For This Parameter

Do This

Virtual Private Cloud (VPC)

Choose the name of the Amazon Virtual Private Cloud
(Amazon VPC) to host your MariaDB DB instance. For
more information about using VPC, see Amazon Virtual
Private Cloud (VPCs) and Amazon RDS (p. 400).

Subnet group

Choose Create new DB subnet group.

Public accessibility

Choose Yes.

Availability zone

Determine if you want to specify a particular availability
zone. For more information about Availability Zones, see
Regions and Availability Zones (p. 99).

VPC security groups

Choose Create new VPC security group.

Database name

Type a name for your default database that is 1 to 64
alphanumeric characters. If you don't provide a name,
Amazon RDS doesn't automatically create a database on
the DB instance you are creating.
To create additional databases, connect to the DB
instance and use the SQL command CREATE DATABASE.
For more information about connecting to the DB
instance, see Connecting to a DB Instance Running the
MariaDB Database Engine (p. 440).

Database port

Leave the default value of 3306 unless you have a specific
port you want to access the database through. MariaDB
installations default to port 3306.

DB parameter group

Accept the default value of default.mariadb10.0 unless
you created your own DB parameter group. For more
information about parameter groups, see Working with
DB Parameter Groups (p. 165).

Option group

Accept the default value.

Copy tags to snapshots

Choose this option to have any DB instance tags
copied to a DB snapshot when you create a snapshot.
For more information, see Tagging Amazon RDS
Resources (p. 134).

Encryption

Choose Disable encryption.

Note

You usually choose Enable encryption for
production instances to enable encryption at rest
for this DB instance. For more information, see
Encrypting Amazon RDS Resources (p. 377).
Backup retention period

Set the number of days you want automatic backups of
your database to be retained. For testing purposes, you
can set this value to 1 day.
API Version 2014-10-31
14

Amazon Relational Database Service User Guide
Connecting to a Database on a
DB Instance Running MariaDB

For This Parameter

Do This

Backup window

Unless you have a specific time that you want to have
your database back up, use the default of No Preference.

Enhanced Monitoring

Unless you want to enable gathering metrics in real time
for the operating system that your DB instance runs on,
use the default of Disable enhanced monitoring.

Log exports

Select General log. For more information, see MariaDB
Database Log Files (p. 301).

Auto minor version upgrade

Choose Enable auto minor version upgrade to enable
your DB instance to receive minor DB engine version
upgrades automatically when they become available.

Maintenance window

Choose the 30-minute window in which pending
modifications to your DB instance are applied. If the time
period doesn't matter, choose No preference.

9. Choose Create database.
10. Choose View DB instance details.
On the RDS console, the details for new DB instance appear. The DB instance has a status of creating
until the DB instance is ready to use. When the state changes to available, you can connect to the
DB instance. Depending on the DB instance class and the amount of storage, it can take up to 20
minutes before the new instance is available.

Connecting to a Database on a DB Instance Running
the MariaDB Database Engine
Once Amazon RDS provisions your DB instance, you can use any standard SQL client application to
connect to a database on the DB instance. In this example, you connect to a database on a MariaDB
DB instance using the mysql command-line tool. One GUI-based application you can use to connect is
API Version 2014-10-31
15

Amazon Relational Database Service User Guide
Connecting to a Database on a
DB Instance Running MariaDB

HeidiSQL; for more information, go to the Download HeidiSQL page. For more information on using
MariaDB, go to the MariaDB documentation.
To connect to a database on a DB instance using the mysql command-line tool
1.

2.

Find the endpoint (DNS name) and port number for your DB Instance.
a.

Open the RDS console and then choose Instances to display a list of your DB instances.

b.

Click the MariaDB DB instance name to display its details.

c.

Scroll to the Connect section and copy the endpoint. Also, note the port number. You need both
the endpoint and the port number to connect to the DB instance.

Type the following command at a command prompt on a client computer to connect to a
database on a MariaDB DB instance. Substitute the DNS name (endpoint) for your DB instance
for , the master user name you used for , and provide the master
password you used when prompted for a password.
PROMPT> mysql -h  -P 3306 -u 

-p

After you enter the password for the user, you should see output similar to the following.
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 272
Server version: 5.5.5-10.0.17-MariaDB-log MariaDB Server
Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved.
Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
mysql >

API Version 2014-10-31
16

Amazon Relational Database Service User Guide
Deleting a DB Instance

Deleting a DB Instance
Once you have connected to the sample DB instance that you created, you should delete the DB instance
so you are no longer charged for it.

To delete a DB instance with no final DB snapshot
1.
2.

Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.
In the navigation pane, choose Instances.
If the navigation pane is closed, choose the menu icon at the top left to open it.

3.
4.

Choose the DB instance you want to delete.
For Instance actions, choose Delete.

5.

For Create final snapshot?, choose No, and select the acknowledgment.

6.

Choose Delete.

API Version 2014-10-31
17

Amazon Relational Database Service User Guide
Creating a Microsoft SQL Server DB
Instance and Connecting to a DB Instance

Creating a Microsoft SQL Server DB Instance and
Connecting to a DB Instance
The basic building block of Amazon RDS is the DB instance. Your Amazon RDS DB instance is similar to
your on-premises Microsoft SQL Server. After you create your SQL Server DB instance, you can add one
or more custom databases to it.

Important

You must have an AWS account before you can create a DB instance. If you don't have an AWS
account, open https://aws.amazon.com/, and then choose Create an AWS Account.
In this topic you create a sample SQL Server DB instance. You then connect to the DB instance and run a
simple query. Finally you delete the sample DB instance.

Creating a Sample SQL Server DB Instance
In this procedure you use the AWS Management Console to create a sample DB instance. Since you are
only creating a sample DB instance, each setting is not fully explained. For a full explanation of each
setting, see Creating a DB Instance Running the Microsoft SQL Server Database Engine (p. 492).

To create a DB instance running the Microsoft SQL Server DB engine
1.

Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.

2.

In the top right corner of the Amazon RDS console, choose the region in which you want to create
the DB instance.

3.

In the navigation pane, choose Instances.

4.

Choose Create database.
The Select engine page appears.

API Version 2014-10-31
18

Amazon Relational Database Service User Guide
Creating a Sample SQL Server DB Instance

5.

Choose the SQL Server icon, and then choose Select for the SQL Server Express edition.

API Version 2014-10-31
19

Amazon Relational Database Service User Guide
Creating a Sample SQL Server DB Instance

The Specify DB Details page appears.

6.

On the Specify DB Details page, provide the information for your DB instance as shown in the
following table:

API Version 2014-10-31
20

Amazon Relational Database Service User Guide
Creating a Sample SQL Server DB Instance

7.

For This Parameter

Do This

License Model

Choose license-included to use the general license
agreement for Microsoft SQL Server.

DB Engine Version

Choose the most recent version of SQL Server available in
the list.

DB Instance Class

Choose db.t2.micro. This instance class is appropriate for
testing.

Time Zone

Do not choose a time zone. If you don't choose a time
zone, your DB instance uses the default time zone.

Storage Type

Choose the storage type General Purpose (SSD).

Allocated Storage

Type 20 to allocate 20 GiB of storage for your database.
There is a warning that you should consider allocating
more storage, but since this is a sample DB instance, 20
GiB is sufficient.

DB Instance Identifier

Type sample-instance.

Master Username

Type a name that you will use as the master user name to
log on to your DB Instance with all database privileges.
The master user name is a SQL Server Authentication
login.

Master Password and Confirm
Password

Type a password for your master user password. It must
contain between 8 and 128 printable ASCII characters
(excluding /,", and @).

Choose Next to continue.
The Configure Advanced Settings page appears.

API Version 2014-10-31
21

Amazon Relational Database Service User Guide
Creating a Sample SQL Server DB Instance

API Version 2014-10-31
22

Amazon Relational Database Service User Guide
Creating a Sample SQL Server DB Instance

8.

9.

On the Configure Advanced Settings page, provide the information for your DB instance as shown
in the following table:

For This Parameter

Do This

VPC

Choose Create new VPC.

Subnet Group

Choose Create new DB Subnet Group.

Publicly Accessible

Choose Yes.

Availability Zone

Choose No Preference.

VPC Security Group

Choose Create new Security Group.

Database Port

Leave the default value of 1433 unless you have a specific
port you want to access the database through. SQL Server
installations default to port 1433, but in some cases
a firewall might block this port. If in doubt, ask your
network administrator what port you should use.

DB Parameter Group

Leave the default value.

Option Group

Leave the default value.

Copy Tags To Snapshots

Leave this setting unselected.

Backup Retention Period

Choose 7.

Backup Window

Choose No Preference.

Enable Enhanced Monitoring

Choose No.

Auto Minor Version Upgrade

Choose Yes.

Maintenance Window

Choose No Preference.

Choose Create database.

10. Choose View Your DB Instances.
On the RDS console, the new DB instance appears in the list of DB instances. The DB instance has
a status of creating until the DB instance is ready to use. When the state changes to available, you
can connect to the DB instance. Depending on the DB instance class and the amount of storage, it
can take up to 20 minutes before the new instance is available.

API Version 2014-10-31
23

Amazon Relational Database Service User Guide
Connecting to Your Sample DB Instance

Connecting to Your Sample SQL Server DB Instance
In this procedure you connect to your sample DB instance by using Microsoft SQL Server Management
Studio (SSMS). To download a stand-alone version of this utility, see Download SQL Server Management
Studio (SSMS) in the Microsoft documentation.

To connect to a DB Instance using SSMS
1.

2.

Find the DNS name and port number for your DB Instance.
a.

Open the RDS console and then choose Instances to display a list of your DB instances.

b.

Choose the row for your SQL Server DB instance to display the summary information for the
instance.

c.

Copy the endpoint. The Endpoint field has two parts separated by a colon (:). The part before
the colon is the DNS name for the instance, the part following the colon is the port number.
Copy both parts.

Start SQL Server Management Studio.
The Connect to Server dialog box appears.

API Version 2014-10-31
24

Amazon Relational Database Service User Guide
Exploring Your Sample DB Instance

3.

Provide the information for your sample DB instance.
a.

For Server type, choose Database Engine.

b.

For Server name, type or paste the DNS name and port number of your sample DB Instance,
separated by a comma.

Important

Change the colon between the DNS name and port number to a comma.
For example, your server name should look like the following:
sample-instance.cg034hpkmmjt.us-east-1.rds.amazonaws.com,1433

4.

c.

For Authentication, choose SQL Server Authentication.

d.

For Login, type the master user name you chose earlier for your sample DB instance.

e.

For Password, type the password you chose earlier for your sample DB instance.

Choose Connect.
After a few moments, SSMS connects to your DB instance. If you can't connect to your DB instance,
see Troubleshooting the Connection to Your SQL Server DB Instance (p. 508).

Exploring Your Sample SQL Server DB Instance
In this procedure you continue the previous procedure and explore your sample DB instance by using
Microsoft SQL Server Management Studio (SSMS).

To explore a DB Instance using SSMS
1.

Your SQL Server DB instance comes with SQL Server's standard built-in system databases (master,
model, msdb, and tempdb). To explore the system databases, do the following:
a.

In SSMS, on the View menu, choose Object Explorer.

b.

Expand your DB instance, expand Databases, and then expand System Databases as shown
following.

API Version 2014-10-31
25

Amazon Relational Database Service User Guide
Exploring Your Sample DB Instance

2.

Your SQL Server DB instance also comes with a database named rdsadmin. Amazon RDS uses this
database to store the objects that it uses to manage your database. The rdsadmin database also
includes stored procedures that you can run to perform advanced tasks.

3.

You can now start creating your own databases and running queries against your DB instance and
databases as usual. To run a test query against your sample DB instance, do the following:
a.

In SSMS, on the File menu point to New and then choose Query with Current Connection.

b.

Type the following SQL query:
select @@VERSION

c.

Run the query. SSMS returns the SQL Server version of your Amazon RDS DB instance.

API Version 2014-10-31
26

Amazon Relational Database Service User Guide
Deleting Your Sample DB Instance

Deleting Your Sample DB Instance
Once you are done exploring the sample DB instance that you created, you should delete the DB instance
so that you are no longer charged for it.

To delete a DB instance
1.

Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.

2.

In the Instances list, choose your sample DB instance.

3.

Choose Instance Actions, and then choose Delete.

4.

For Create final Snapshot, choose No.

Note

You should create a final snapshot for any production DB instance that you delete.
5.

Choose Delete.

Related Topics
• Tutorial: Create an Amazon VPC for Use with an Amazon RDS DB Instance (p. 415)
• Creating a DB Instance Running the Microsoft SQL Server Database Engine (p. 492)
• Connecting to a DB Instance Running the Microsoft SQL Server Database Engine (p. 503)
API Version 2014-10-31
27

Amazon Relational Database Service User Guide
Creating a MySQL DB Instance
and Connecting to a Database

• Modifying a DB Instance Running the Microsoft SQL Server Database Engine (p. 510)
• Microsoft SQL Server on Amazon RDS (p. 476)

Creating a MySQL DB Instance and Connecting to a
Database on a MySQL DB Instance
The easiest way to create a DB instance is to use the AWS Management Console. Once you have created
the DB instance, you can use standard MySQL utilities such as MySQL Workbench to connect to a
database on the DB instance.

Important

You must complete the tasks in the Setting Up for Amazon RDS (p. 5) section before you can
create or connect to a DB instance.
Topics
• Creating a MySQL DB Instance (p. 28)
• Connecting to a Database on a DB Instance Running the MySQL Database Engine (p. 33)
• Deleting a DB Instance (p. 34)

Creating a MySQL DB Instance
The basic building block of Amazon RDS is the DB instance. This is the environment in which you run
your MySQL databases.
In this example, you create a DB instance running the MySQL database engine called mysql-instance1,
with a db.m1.small DB instance class, 20 GiB of storage, and automated backups enabled with a
retention period of one day.

To create a MySQL DB instance
1.

Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.

2.

In the top right corner of the Amazon RDS console, choose the region in which you want to create
the DB instance.

3.

In the navigation pane, choose Instances.
If the navigation pane is closed, choose the menu icon at the top left to open it.

4.

Choose Create database. The Select engine page opens.

API Version 2014-10-31
28

Amazon Relational Database Service User Guide
Creating a MySQL DB Instance

5.

Choose MySQL, and then choose Next.

6.

The Choose use case page asks if you are planning to use the DB instance you are creating for
production. Choose Dev/Test and then choose Next.

7.

On the Specify DB Details page, specify your DB instance information. The following table shows
settings for an example DB instance. When the settings are as you want them, choose Next.
For This Parameter

Do This

License model

Choose the default, general-public-license, to use
the general license agreement for MySQL. MySQL has
only one license model.

DB engine version

Choose the default version of MySQL. Amazon RDS
supports multiple versions of MySQL in some regions.

DB instance class

Choose db.m1.small.

Multi-AZ deployment

Choose Yes to have a standby replica of your DB instance
created in another Availability Zone for failover support.
We recommend Multi-AZ for production workloads to
maintain high availability. For development and testing,
you can choose No.
API Version 2014-10-31
29

Amazon Relational Database Service User Guide
Creating a MySQL DB Instance

For This Parameter

Do This
For more information, see High Availability (Multi-AZ) for
Amazon RDS (p. 107).

Storage type

Choose the storage type General Purpose (SSD).
For more information about storage, see DB instance
storage (p. 101).

Allocated storage

Type 20 to allocate 20 GiB of storage for your database.
In some cases, allocating a higher amount of storage
for your DB instance than the size of your database can
improve I/O performance. For more information about
storage allocation, see Amazon RDS Features.

DB instance identifier

Type a name for the DB instance that is unique for your
account in the region you chose. You can add some
intelligence to the name, such as including the region and
DB engine you chose, for example mysql-instance1.

Master username

Type a name using alphanumeric characters to use as the
master user name to log on to your DB instance. This is
the user name you use to log on to your database on the
DB instance for the first time.

Master password and Confirm
password

Type a password that contains from 8 to 41 printable
ASCII characters (excluding /,", and @) for your master
user password. This is the password to use when you use
the user name to log on to your database. Then type the
password again in the Confirm Password box.

API Version 2014-10-31
30

Amazon Relational Database Service User Guide
Creating a MySQL DB Instance

API Version 2014-10-31
31

Amazon Relational Database Service User Guide
Creating a MySQL DB Instance

8.

Choose Next.

9.

On the Configure advanced settings page, provide additional information that RDS needs to launch
the MySQL DB instance. The table shows settings for an example DB instance. Specify your DB
instance information, then choose Create database.

For This Parameter

Do This

Virtual Private Cloud (VPC)

Choose Create new VPC.

Subnet group

Choose Create new DB subnet group.

Public accessibility

Choose Yes.

Availability zone

Choose No Preference.

VPC security groups

Choose Create new VPC security group.

Database name

Type a name for your default database that is 1 to 64
alpha-numeric characters. If you don't provide a name,
Amazon RDS doesn't automatically create a database on
the DB instance you are creating.
To create additional databases, connect to the DB
instance and use the SQL command CREATE DATABASE.
For more information about connecting to the DB
instance, see Connecting to a DB Instance Running the
MySQL Database Engine (p. 596).

Database port

Leave the default value of 3306 unless you have a specific
port you want to access the database through. MySQL
installations default to port 3306.

DB parameter group

Leave the default value unless you created your own DB
parameter group. For more information about parameter
groups, see Working with DB Parameter Groups (p. 165).

Option group

Choose the default value because this option group is
used with the MySQL version you chose on the previous
page.

Copy tags To snapshots

Choose this option to have any DB instance tags
copied to a DB snapshot when you create a snapshot.
For more information, see Tagging Amazon RDS
Resources (p. 134).

IAM DB authentication

Choose No. For more information, see Authentication and
Access Control (p. 330).

Encryption

Choose Enable encryption to enable encryption
at rest for this DB instance. For more information, see
Encrypting Amazon RDS Resources (p. 377).

Backup retention period

Set the number of days you want automatic backups of
your database to be retained. For testing purposes, you
can set this value to 1.

Backup window

Unless you have a specific time that you want to
have your database backup, use the default of No
Preference.
API Version 2014-10-31
32

Amazon Relational Database Service User Guide
Connecting to a Database on a DB Instance Running MySQL

For This Parameter

Do This

Enhanced monitoring

Unless you want to enable gathering metrics in real time
for the operating system that your DB instance runs on,
use the default of Disable enhanced monitoring.

Log exports

Select General log. For more information, see MySQL
Database Log Files (p. 310).

Auto minor version upgrade

Choose Enable auto minor version upgrade.

Maintenance window

Choose No preference.

10. Choose Create database.
11. Choose View DB instance details.
On the RDS console, the details for new DB instance appear. The DB instance has a status of creating
until the DB instance is ready to use. When the state changes to available, you can connect to the
DB instance. Depending on the DB instance class and the amount of storage, it can take up to 20
minutes before the new instance is available.

Connecting to a Database on a DB Instance Running
the MySQL Database Engine
Once Amazon RDS provisions your DB instance, you can use any standard SQL client application to
connect to a database on the DB instance. In this example, you connect to a database on a MySQL DB
instance using MySQL monitor commands. One GUI-based application you can use to connect is MySQL
Workbench; for more information, go to the Download MySQL Workbench page. For more information
on using MySQL, go to the MySQL documentation.
To connect to a database on a DB instance using MySQL monitor
1.

Find the endpoint (DNS name) and port number for your DB Instance.
a.

Open the RDS console and then choose Instances to display a list of your DB instances.
API Version 2014-10-31
33

Amazon Relational Database Service User Guide
Deleting a DB Instance

2.

b.

Click the MySQL DB instance name to display its details.

c.

Scroll to the Connect section and copy the endpoint. Also, note the port number. You need both
the endpoint and the port number to connect to the DB instance.

Type the following command at a command prompt on a client computer to connect to a database
on a MySQL DB instance using the MySQL monitor. Substitute the DNS name for your DB instance
for , the master user name you used for , and and provide the master
password you used when prompted for a password.
PROMPT> mysql -h  -P 3306 -u  -p

After you enter the password for the user, you should see output similar to the following.
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 350
Server version: 5.6.40-log MySQL Community Server (GPL)
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
mysql>

Deleting a DB Instance
Once you have connected to the sample DB instance that you created, you should delete the DB instance
so you are no longer charged for it.
To delete a DB instance with no final DB snapshot
1.

Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.

2.

In the navigation pane, choose Instances.
If the navigation pane is closed, choose the menu icon at the top left to open it.

3.

Choose the DB instance you wish to delete.

4.

Choose Instance actions, and then choose Delete.

5.

For Create final snapshot?, choose No, and select the acknowledgment.

6.

Choose Delete.
API Version 2014-10-31
34

Amazon Relational Database Service User Guide
Deleting a DB Instance

API Version 2014-10-31
35

Amazon Relational Database Service User Guide
Creating an Oracle DB Instance
and Connecting to a Database

Creating an Oracle DB Instance and Connecting to
a Database on an Oracle DB Instance
The basic building block of Amazon RDS is the DB instance. Your Amazon RDS DB instance is similar to
your on-premises Oracle database.

Important

You must have an AWS account before you can create a DB instance. If you don't have an AWS
account, open https://aws.amazon.com/, and then choose Create an AWS Account.
In this topic you create a sample Oracle DB instance. You then connect to the DB instance and run a
simple query. Finally you delete the sample DB instance.

Creating a Sample Oracle DB Instance
In this procedure you use the AWS Management Console to create a sample DB instance. Since you are
only creating a sample DB instance, each setting is not fully explained. For a full explanation of each
setting, see Creating a DB Instance Running the Oracle Database Engine (p. 734).

To create a DB instance running the Oracle database engine
1.

Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.

2.

In the top right corner of the Amazon RDS console, choose the region in which you want to create
the DB instance.

3.

In the navigation pane, choose Instances.

4.

Choose Create database.
The Select engine page appears.

API Version 2014-10-31
36

Amazon Relational Database Service User Guide
Creating a Sample Oracle DB Instance

5.

Choose the Oracle icon, and then choose Select for the Oracle Standard Edition Two edition.

6.

The Choose use case page asks if you are planning to use the DB instance you are creating for
production. Choose Dev/Test and then choose Next.
The Specify DB details page appears.

7.

On the Specify DB details page, provide the information for your DB instance as shown in the
following table:

For This Parameter

Do This

License model

Choose license-included to use the general license
agreement for Oracle.

DB engine version

Choose the most recent version of Oracle available in the
list.

DB instance class

Choose db.t2.small. This instance class is appropriate for
testing.

Multi-AZ deployment

For development and testing, choose No.

Storage type

Choose the storage type General Purpose (SSD).
API Version 2014-10-31
37

Amazon Relational Database Service User Guide
Creating a Sample Oracle DB Instance

8.

For This Parameter

Do This

Allocated storage

Type 20 to allocate 20 GiB of storage for your database.

DB instance identifier

Type oracle-instance1.

Master username

Type a name that you will use as the master user name to
log on to your DB Instance with all database privileges.
The master user name is a SQL Server Authentication
login.

Master password and confirm
Password

Type a password for your master user password. It must
contain between 8 and 128 printable ASCII characters
(excluding /,", and @).

Choose Next to continue.
The Configure Advanced Settings page appears.

9.

On the Configure advanced settings page, provide the information for your DB instance as shown in
the following table:

For This Parameter

Do This

Virtual Private Cloud (VPC)

Choose Create new VPC.

Subnet group

Choose Create new DB subnet group.

Public accessibility

Choose Yes.

Availability zone

Choose No Preference.

VPC security groups

Choose Create new VPC security group.

Database name

Type ORCL.

Database port

Leave the default value of 1521 unless you have a specific
port you want to access the database through. Oracle
installations default to port 1521, but in some cases
a firewall might block this port. If in doubt, ask your
network administrator what port you should use.

DB parameter group

Leave the default value.

Option group

Leave the default value.

Copy tags to snapshots

Leave this setting unselected.

Character set name

Choose the default value of AL32UTF8 for the Unicode
5.0 UTF-8 Universal character set.

Enable encryption

Choose No to enable encryption at rest for this DB
instance.

Backup retention period

Choose 7 days.

Backup window

Choose No preference.

Enhanced monitoring

Choose Disable enhanced monitoring.

Auto minor version upgrade

Choose Enable auto minor version upgrade.
API Version 2014-10-31
38

Amazon Relational Database Service User Guide
Connecting to Your Sample DB Instance

For This Parameter

Do This

Maintenance window

Choose No preference.

10. Choose Create database.
11. Choose View DB instance details.
On the RDS console, the details for new DB instance appear. The DB instance has a status of creating
until the DB instance is ready to use. When the state changes to available, you can connect to the
DB instance. Depending on the DB instance class and the amount of storage, it can take up to 20
minutes before the new instance is available.

Connecting to Your Sample Oracle DB Instance
After Amazon RDS provisions your DB instance, you can use any standard SQL client application to
connect to the instance. In this procedure you connect to your sample DB instance by using the Oracle
sqlplus command line utility. To download a stand-alone version of this utility, see SQL*Plus User's Guide
and Reference.

To connect to a DB Instance using SQL*Plus
1.

2.

Find the endpoint (DNS name) and port number for your DB Instance.
a.

Open the RDS console and then choose Instances to display a list of your DB instances.

b.

Click the Oracle DB instance name to display its details.

c.

Scroll to the Connect section and copy the endpoint. Also, note the port number. You need both
the endpoint and the port number to connect to the DB instance.

Type the following command on one line at a command prompt to connect to your DB instance by
using the sqlplus utility. The value for Host is the endpoint for your DB instance, the value for Port
is the port you assigned the DB instance, and the value for the Oracle SID is the name of the DB
API Version 2014-10-31
39

Amazon Relational Database Service User Guide
Deleting Your Sample DB Instance

instance's database that you specified when you created the DB instance, not the name of the DB
instance.
PROMPT>sqlplus 'mydbusr@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=endpoint)
(PORT=1521))(CONNECT_DATA=(SID=ORCL)))'

You should see output similar to the following.
SQL*Plus: Release 11.1.0.7.0 - Production on Wed May 25 15:13:59 2011
SQL>

Deleting Your Sample DB Instance
Once you are done exploring the sample DB instance that you created, you should delete the DB instance
so that you are no longer charged for it.

To delete a DB instance with no final DB snapshot
1.

Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.

2.
3.
4.

In the navigation pane, choose Instances.
Choose the DB instance you want to delete.
For Instance actions, choose Delete.

5.
6.

For Create final snapshot?, choose No, and select the acknowledgment.
Choose Delete.

Related Topics
• Tutorial: Create an Amazon VPC for Use with an Amazon RDS DB Instance (p. 415)
• Creating a DB Instance Running the Oracle Database Engine (p. 734)
• Connecting to a DB Instance Running the Oracle Database Engine (p. 743)
• Modifying a DB Instance Running the Oracle Database Engine (p. 750)
• Oracle on Amazon RDS (p. 710)

Creating a PostgreSQL DB Instance and
Connecting to a Database on a PostgreSQL DB
Instance
The easiest way to create a DB instance is to use the RDS console. Once you have created the DB
instance, you can use standard SQL client utilities to connect to the DB instance such as the pgAdmin
utility. In this example, you create a DB instance running the PostgreSQL database engine called west2postgres1, with a db.m1.small DB instance class, 10 GiB of storage, and automated backups enabled with
a retention period of one day.

Important

You must complete the tasks in the Setting Up for Amazon RDS (p. 5) section before you can
create or connect to a DB instance.
API Version 2014-10-31
40

Amazon Relational Database Service User Guide
Creating a PostgreSQL DB Instance

Topics
• Creating a PostgreSQL DB Instance (p. 41)
• Connecting to a PostgreSQL DB Instance (p. 44)
• Deleting a DB Instance (p. 47)

Creating a PostgreSQL DB Instance
To create a DB Instance Running the PostgreSQL DB Engine
1.

Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.

2.

In the top right corner of the AWS Management Console, choose the region in which you want to
create the DB instance.

3.

In the navigation pane, choose Instances.
If the navigation pane is closed, choose the menu icon at the top left to open it.

4.

Choose Create database to open the Select engine page.

5.

On the Select engine page, choose the PostgreSQL icon, and then choose Next.

6.

Next, the Use case page asks if you are planning to use the DB instance you are creating for
production. If you are, choose Production. If you choose this option, the failover option Multi-AZ
and the Provisioned IOPS storage options are preselected in the following step. Choose Next when
you are finished.

7.

On the Specify DB Details page, specify your DB instance information. Choose Next when you are
finished.
For This Parameter

Do This

License Model

PostgreSQL has only one license model. Choose
postgresql-license to use the general license
agreement for PostgreSQL.
API Version 2014-10-31
41

Amazon Relational Database Service User Guide
Creating a PostgreSQL DB Instance

For This Parameter

Do This

DB Engine Version

Choose the version of PostgreSQL you want to use.

DB Instance Class

Choose db.t2.small for a configuration that equates
to 2 GiB memory, 1 ECU (1 virtual core with 1 ECU),
64-bit platform, and moderate I/O capacity. For more
information about all the DB instance class options, see
DB Instance Class (p. 80).

Multi-AZ Deployment

Choose Yes to have a standby replica of your DB instance
created in another Availability Zone for failover support.
We recommend Multi-AZ for production workloads to
maintain high availability. For development and testing,
you can choose No.
For more information, see High Availability (Multi-AZ) for
Amazon RDS (p. 107).

8.

Storage Type

Choose the storage type General Purpose (SSD).
For more information about storage, see DB instance
storage (p. 101).

Allocated Storage

Type 20 to allocate 20 GiB of storage for your database.
In some cases, allocating a higher amount of storage
for your DB instance than the size of your database can
improve I/O performance. For more information about
storage allocation, see Amazon RDS Features.

DB Instance Identifier

Type a name for the DB instance that is unique for your
account in the region you chose. You can add some
intelligence to the name, such as including the region and
DB engine you chose, for example postgreSQL-test.

Master Username

Type a name using alphanumeric characters to use as
the master user name to log on to your DB instance.
For information on the default privileges granted to
the master user name, see Amazon RDS for PostgreSQL
Versions and Extensions (p. 1023)

Master Password and Confirm
Password

Type a password that contains from 8 to 128 printable
ASCII characters (excluding /,", and @) for your master
password, then type the password again in the Confirm
Password box.

On the Configure Advanced Settings page, provide additional information that RDS needs to
launch the PostgreSQL DB instance. The table shows settings for an example DB instance. Specify
your DB instance information, then choose Create database.

For This Parameter

Do This

VPC

This setting depends on the platform you are on. If you
are a new customer to AWS, choose the default VPC
shown. If you are creating a DB instance on the previous
E2-Classic platform that does not use a VPC, choose Not
in VPC. For more information about VPC, see Amazon
Virtual Private Cloud (VPCs) and Amazon RDS (p. 400).

API Version 2014-10-31
42

Amazon Relational Database Service User Guide
Creating a PostgreSQL DB Instance

For This Parameter

Do This

Subnet Group

This setting depends on the platform you are on. If you
are a new customer to AWS, choose default, which is
the default DB subnet group that was created for your
account. If you are creating a DB instance on the previous
E2-Classic platform and you want your DB instance in a
specific VPC, choose the DB subnet group you created for
that VPC. For more information about VPC, see Amazon
Virtual Private Cloud (VPCs) and Amazon RDS (p. 400).

Publicly Accessible

Choose Yes to give the DB instance a public IP address,
meaning that it is accessible outside the VPC; otherwise,
choose No, so the DB instance is only accessible from
inside the VPC. For more information about hiding DB
instances from public access, see Hiding a DB Instance in a
VPC from the Internet (p. 410).

Availability Zone

Use the default value of No Preference unless you
want to specify an Availability Zone.

VPC Security Group

If you are a new customer to AWS, choose the default
VPC. If you created a VPC security group, choose the VPC
security group you previously created.

Database Name

Type a name for your database of up to 63 alpha-numeric
characters. If you do not provide a name, the default
"postgres" database is created.
To create additional databases, connect to the DB
instance and use the SQL command CREATE DATABASE.
For more information about connecting to the DB
instance, see Connecting to a DB Instance Running the
PostgreSQL Database Engine (p. 970).

Database Port

Specify a port you want to use to access the database.
PostgreSQL installations default to port 5432.

DB Parameter Group

Use the default value unless you have created your own
parameter group.

Option Group

Use the default value unless you have created your own
option group.

Copy Tags To Snapshots

Choose this option to have any DB instance tags
copied to a DB snapshot when you create a snapshot.
For more information, see Tagging Amazon RDS
Resources (p. 134).

Enable Encryption

Choose Yes to enable encryption at rest for this DB
instance. For more information, see Encrypting Amazon
RDS Resources (p. 377).

Backup Retention Period

Set the number of days you want automatic backups of
your database to be retained. For testing purposes, you
can set this value to 1.

API Version 2014-10-31
43

Amazon Relational Database Service User Guide
Connecting to a PostgreSQL DB Instance

For This Parameter

Do This

Backup Window

Unless you have a specific time that you want to
have your database backup, use the default of No
Preference.

Enable Enhanced Monitoring

Choose Yes to enable real-time OS monitoring. Amazon
RDS provides metrics in real time for the operating
system (OS) that your DB instance runs on. You are only
charged for Enhanced Monitoring that exceeds the free
tier provided by Amazon CloudWatch Logs.

Monitoring Role

Choose Default to use the default IAM role.

Granularity

Choose 60 to monitor the instance every minute.

Auto Minor Version Upgrade

Choose Yes to enable your DB instance to receive minor
DB engine version upgrades automatically when they
become available.

Maintenance Window

Choose the 30-minute window in which pending
modifications to your DB instance are applied. If the time
period doesn't matter, choose No Preference.

9. On the final page, choose Create database.
10. On the Amazon RDS console, the new DB instance appears in the list of DB instances. The DB
instance has a status of creating until the DB instance is created and ready for use. When the state
changes to available, you can connect to the DB instance. Depending on the DB instance class and
store allocated, it could take several minutes for the new instance to be available.

Connecting to a PostgreSQL DB Instance
After Amazon RDS provisions your DB instance, you can use any standard SQL client application to
connect to the instance. It is important to note that the security group you assigned to the DB instance
when you created it must allow access to the DB instance. If you have difficulty connecting to the DB
instance, the problem is most often with the access rules you set up in the security group you assigned to
the DB instance.
This section shows two ways to connect to a PostgreSQL DB instance. The first example uses pgAdmin, a
popular Open Source administration and development tool for PostgreSQL. You can download and use
pgAdmin without having a local instance of PostgreSQL on your client computer. The second example
uses psql, a command line utility that is part of a PostgreSQL installation. To use psql, you must have a
PostgreSQL installed on your client computer or have installed the psql client on your machine.
In this example, you connect to a PostgreSQL DB instance using pgAdmin.
API Version 2014-10-31
44

Amazon Relational Database Service User Guide
Connecting to a PostgreSQL DB Instance

Using pgAdmin to Connect to a PostgreSQL DB Instance
To connect to a PostgreSQL DB instance using pgAdmin
1.

Launch the pgAdmin application on your client computer. You can install pgAdmin from http://
www.pgadmin.org/.

2.

Choose Add Server from the File menu.

3.

In the New Server Registration dialog box, enter the DB instance endpoint (for example,
mypostgresql.c6c8dntfzzhgv0.us-west-2.rds.amazonaws.com) in the Host box. Do not include the
colon or port number as shown on the Amazon RDS console (mypostgresql.c6c8dntfzzhgv0.uswest-2.rds.amazonaws.com:5432).
Enter the port you assigned to the DB instance into the Port box. Enter the user name and user
password you entered when you created the DB instance into the Username and Password boxes,
respectively.

4.

Choose OK.

5.

In the Object browser, expand the Server Groups. Choose the Server (the DB instance) you created,
and then choose the database name.

API Version 2014-10-31
45

Amazon Relational Database Service User Guide
Connecting to a PostgreSQL DB Instance

6.

Choose the plugin icon and choose PSQL Console. The psql command window opens for the default
database you created.

7.

Use the command window to enter SQL or psql commands. Type \q to close the window.

API Version 2014-10-31
46

Amazon Relational Database Service User Guide
Deleting a DB Instance

Using psql to Connect to a PostgreSQL DB Instance
If your client computer has PostgreSQL installed, you can use a local instance of psql to connect to a
PostgreSQL DB instance. To connect to your PostgreSQL DB instance using psql, you need to provide host
information and access credentials.
The following format is used to connect to a PostgreSQL DB instance on Amazon RDS:
psql --host= --port= --username= --password
--dbname=

For example, the following command connects to a database called mypgdb on a PostgreSQL DB
instance called mypostgresql using fictitious credentials:
psql --host=mypostgresql.c6c8mwvfdgv0.us-west-2.rds.amazonaws.com --port=5432 -username=awsuser --password --dbname=mypgdb

Troubleshooting Connection Issues
By far the most common problem that occurs when attempting to connect to a database on a DB
instance is the access rules in the security group assigned to the DB instance. If you used the default DB
security group when you created the DB instance, chances are good that the security group did not have
the rules that allow you to access the instance. For more information about Amazon RDS security groups,
see Controlling Access with Amazon RDS Security Groups (p. 382)
The most common error is could not connect to server: Connection timed out. If you receive this error,
check that the host name is the DB instance endpoint and that the port number is correct. Check that the
security group assigned to the DB instance has the necessary rules to allow access through any firewall
your connection may be going through.

Deleting a DB Instance
Once you have connected to the sample DB instance that you created, you should delete the DB instance
so you are no longer charged for it.

To delete a DB instance with no final DB snapshot
1.

Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.

2.

In the navigation pane, choose Instances.

3.

If the navigation pane is closed, choose the menu icon at the top left to open it.
Choose the DB instance you wish to delete.

4.

Choose Instance actions, and then choose Delete.

5.
6.

For Create final snapshot?, choose No, and select the acknowledgment.
Choose Delete.

API Version 2014-10-31
47

Amazon Relational Database Service User Guide
Tutorial: Create a Web Server
and an Amazon RDS Database

Tutorial: Create a Web Server and an Amazon RDS
Database
This tutorial helps you install an Apache web server with PHP, and create a MySQL database. The web
server runs on an Amazon EC2 instance using Amazon Linux, and the MySQL database is an Amazon RDS
MySQL DB instance. Both the Amazon EC2 instance and the Amazon RDS DB instance run in a VPC based
in Amazon Virtual Private Cloud service (Amazon VPC).

Note

This tutorial works with Amazon Linux and might not work for other versions of Linux such as
Ubuntu.
Before you begin this tutorial, you must have a VPC with both public and private subnets, and
corresponding security groups. If you don't have these, complete the following tasks in Tutorial: Create
an Amazon VPC for Use with an Amazon RDS DB Instance (p. 415):
1. Create a VPC with Private and Public Subnets (p. 415)
2. Create Additional Subnets (p. 416)
3. Create a VPC Security Group for a Public Web Server (p. 417)
4. Create a VPC Security Group for a Private Amazon RDS DB Instance (p. 418)
5. Create a DB Subnet Group (p. 418)
In the tutorial that follows, you specify the VPC, subnets, and security groups when you create the DB
instance. You also specify them when you create the EC2 instance that will host your web server. The
VPC, subnets, and security groups are required for the DB instance and the web server to communicate.
After the VPC is set up, this tutorial shows you how to you create the DB instance and install the web
server. You connect your web server to your RDS DB instance in the VPC using the DB instance endpoint.
In this tutorial, you perform the following procedures:
• Step 1: Create an RDS DB Instance (p. 49)
• Step 2: Create an EC2 Instance and Install a Web Server (p. 54)
The following diagram shows the configuration when the tutorial is complete.

API Version 2014-10-31
48

Amazon Relational Database Service User Guide
Step 1: Create a DB Instance

Step 1: Create an RDS DB Instance
In this step you create an Amazon RDS MySQL DB instance that maintains the data used by a web
application.

Important

Before you begin this step, you must have a VPC with both public and private subnets, and
corresponding security groups. If you don't have these, see Tutorial: Create an Amazon VPC for
Use with an Amazon RDS DB Instance (p. 415). Complete the steps in Create a VPC with Private
and Public Subnets (p. 415), Create Additional Subnets (p. 416), Create a VPC Security Group
for a Public Web Server (p. 417), and Create a VPC Security Group for a Private Amazon RDS
DB Instance (p. 418).

To launch a MySQL DB instance
1.

Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.

2.

In the top-right corner of the AWS Management Console, choose the region in which you want to
create the DB instance. This example uses the US West (Oregon) region.

3.

In the navigation pane, choose Instances.
If the navigation pane is closed, choose the menu icon at the top left to open it.

4.

Choose Create database to open the Select engine page.

5.

On the Select engine page, shown following, choose MySQL, and then choose Next.

API Version 2014-10-31
49

Amazon Relational Database Service User Guide
Step 1: Create a DB Instance

6.

On the Choose use case page, choose Dev/Test – MySQL, and then choose Next.

7.

On the Specify DB details page, shown following, set these values:
• License model: Use the default value.
• DB engine version: Use the default value.
• DB instance class: db.t2.small
• Multi-AZ deployment: No
• Storage type: General Purpose (SSD)
• Allocated storage: 20 GiB
• DB instance identifier: tutorial-db-instance
• Master username: tutorial_user
• Master password: Choose a password.
• Confirm password: Retype the password.

API Version 2014-10-31
50

Amazon Relational Database Service User Guide
Step 1: Create a DB Instance

API Version 2014-10-31
51

Amazon Relational Database Service User Guide
Step 1: Create a DB Instance

8.

Choose Next and set the following values in the Configure advanced settings page:
• Virtual Private Cloud (VPC): Choose an existing VPC with both public and private subnets,
such as the tutorial-vpc (vpc-identifier) created in Create a VPC with Private and Public
Subnets (p. 415)

Note

The VPC must have subnets in different availability zones.
• Subnet group: The DB subnet group for the VPC, such as the tutorial-db-subnet-group
created in Create a DB Subnet Group (p. 418)
• Public accessibility: No
• Availability zone: No Preference
• VPC security groups: Choose an existing VPC security group that is configured for private access,
such as the tutorial-db-securitygroup created in Create a VPC Security Group for a Private
Amazon RDS DB Instance (p. 418)
Remove other security groups, such as the default security group, by clicking the X associated with
it.
• Database name: sample
Leave the default settings for the other options.

API Version 2014-10-31
52

Amazon Relational Database Service User Guide
Step 1: Create a DB Instance

9.

To create your Amazon RDS MySQL DB instance, choose Create database.

10. On the next page, choose View DB instances details to view your RDS MySQL DB instance.
11. Wait for the DB instance status of your new DB instance to show as available. Then scroll to the
Connect section, shown following.

API Version 2014-10-31
53

Amazon Relational Database Service User Guide
Step 2: Create a Web Server

Make note of the endpoint and port for your DB instance. You will use this information to connect
your web server to your RDS DB instance.
To make sure your RDS MySQL DB instance is as secure as possible, verify that sources outside of the VPC
cannot connect to your RDS MySQL DB instance.

Next Step
Step 2: Create an EC2 Instance and Install a Web Server (p. 54)

Step 2: Create an EC2 Instance and Install a Web
Server
In this step you create a web server to connect to the Amazon RDS DB instance that you created in Step
1: Create an RDS DB Instance (p. 49).

Launch an EC2 Instance
First you create an Amazon EC2 instance in the public subnet of your VPC.

To launch an EC2 instance
1.

Sign in to the AWS Management Console and open the Amazon EC2 console at https://
console.aws.amazon.com/ec2/.

2.

Choose EC2 Dashboard, and then choose Launch Instance, as shown following.

API Version 2014-10-31
54

Amazon Relational Database Service User Guide
Step 2: Create a Web Server

3.

Choose the Amazon Linux Amazon Machine Image (AMI), as shown following.

4.

Choose the t2.small instance type, as shown following, and then choose Next: Configure Instance
Details.

API Version 2014-10-31
55

Amazon Relational Database Service User Guide
Step 2: Create a Web Server

5.

On the Configure Instance Details page, shown following, set these values and leave the other
values as their defaults:
• Network: Choose the VPC with both public and private subnets that you chose for the DB
instance, such as the tutorial-vpc (vpc-identifier) created in Create a VPC with Private and
Public Subnets (p. 415).
• Subnet: Choose an existing public subnet, such as subnet-identifier | Tutorial public
| us-west-2a created in Create a VPC Security Group for a Public Web Server (p. 417).
• Auto-assign Public IP: Choose Enable.

API Version 2014-10-31
56

Amazon Relational Database Service User Guide
Step 2: Create a Web Server

6.

Choose Next: Add Storage.

7.

On the Add Storage page, leave the default values and choose Next: Add Tags.

8.

On the Add Tags page, shown following, choose Add Tag, then type Name for Key and type
tutorial-web-server for Value.

9.

Choose Next: Configure Security Group.

10. On the Configure Security Group page, shown following, choose Select an existing security group,
and then choose an existing security group, such as the tutorial-securitygroup created in
Create a VPC Security Group for a Public Web Server (p. 417). The security group must include
inbound rules for SSH and HTTP access.

API Version 2014-10-31
57

Amazon Relational Database Service User Guide
Step 2: Create a Web Server

11. Choose Review and Launch.
12. On the Review Instance Launch page, shown following, verify your settings and then choose
Launch.

API Version 2014-10-31
58

Amazon Relational Database Service User Guide
Step 2: Create a Web Server

13. On the Select an existing key pair or create a new key pair page, shown following, choose Create
a new key pair and set Key pair name to tutorial-key-pair. Choose Download Key Pair,
and then save the key pair file on your local machine. You use this key pair file to connect to your
EC2 instance.

API Version 2014-10-31
59

Amazon Relational Database Service User Guide
Step 2: Create a Web Server

14. To launch your EC2 instance, choose Launch Instances. On the Launch Status page, shown
following, note the identifier for your new EC2 instance, for example: i-0288d65fd4470b6a9.

API Version 2014-10-31
60

Amazon Relational Database Service User Guide
Step 2: Create a Web Server

15. To find your instance, choose View Instances.
16. Wait until Instance Status for your instance reads as running before continuing.

Install an Apache Web Server with PHP
Next you connect to your EC2 instance and install the web server.

To connect to your EC2 instance and install the Apache web server with PHP
1.

To connect to the EC2 instance that you created earlier, follow the steps in Connect to Your Instance.

2.

To get the latest bug fixes and security updates, update the software on your EC2 instance by using
the following command:

Note

The -y option installs the updates without asking for confirmation. To examine updates
before installing, omit this option.
[ec2-user ~]$ sudo yum update -y

3.

After the updates complete, install the Apache web server with the PHP software package using the
yum install command, which installs multiple software packages and related dependencies at the
same time:
API Version 2014-10-31
61

Amazon Relational Database Service User Guide
Step 2: Create a Web Server

[ec2-user ~]$ sudo yum install -y httpd24 php56 php56-mysqlnd

For more information, see Updating Instance Software.
4.

Start the web server with the command shown following:
[ec2-user ~]$ sudo service httpd start

You can test that your web server is properly installed and started by entering the public
DNS name of your EC2 instance in the address bar of a web browser, for example: http://
ec2-42-8-168-21.us-west-1.compute.amazonaws.com. If your web server is running, then
you see the Apache test page. If you don't see the Apache test page, then verify that your inbound
rules for the VPC security group that you created in Tutorial: Create an Amazon VPC for Use with an
Amazon RDS DB Instance (p. 415) include a rule allowing HTTP (port 80) access for the IP address
you use to connect to the web server.

Note

The Apache test page appears only when there is no content in the document root
directory, /var/www/html. After you add content to the document root directory, your
content appears at the public DNS address of your EC2 instance instead of the Apache test
page.
5.

Configure the web server to start with each system boot using the chkconfig command:
[ec2-user ~]$ sudo chkconfig httpd on

To allow ec2-user to manage files in the default root directory for your Apache web server, you need
to modify the ownership and permissions of the /var/www directory. In this tutorial, you add a group
named www to your EC2 instance, and then you give that group ownership of the /var/www directory
and add write permissions for the group. Any members of that group can then add, delete, and modify
files for the web server.

To set file permissions for the Apache web server
1.

Add the www group to your EC2 instance with the following command:
[ec2-user ~]$ sudo groupadd www

2.

Add the ec2-user user to the www group:
[ec2-user ~]$ sudo usermod -a -G www ec2-user

3.

To refresh your permissions and include the new www group, log out:
[ec2-user ~]$ exit

4.

Log back in again and verify that the www group exists with the groups command:
[ec2-user ~]$ groups
ec2-user wheel www

API Version 2014-10-31
62

Amazon Relational Database Service User Guide
Step 2: Create a Web Server

5.

Change the group ownership of the /var/www directory and its contents to the www group:
[ec2-user ~]$ sudo chown -R root:www /var/www

6.

Change the directory permissions of /var/www and its subdirectories to add group write
permissions and set the group ID on subdirectories created in the future:
[ec2-user ~]$ sudo chmod 2775 /var/www
[ec2-user ~]$ find /var/www -type d -exec sudo chmod 2775 {} +

7.

Recursively change the permissions for files in the /var/www directory and its subdirectories to add
group write permissions:
[ec2-user ~]$ find /var/www -type f -exec sudo chmod 0664 {} +

Connect your Apache web server to your RDS DB instance
Next, you add content to your Apache web server that connects to your Amazon RDS DB instance.

To add content to the Apache web server that connects to your RDS DB instance
1.

While still connected to your EC2 instance, change the directory to /var/www and create a new
subdirectory named inc:
[ec2-user ~]$ cd /var/www
[ec2-user ~]$ mkdir inc
[ec2-user ~]$ cd inc

2.

Create a new file in the inc directory named dbinfo.inc, and then edit the file by calling nano (or
the editor of your choice).
[ec2-user ~]$ >dbinfo.inc
[ec2-user ~]$ nano dbinfo.inc

3.

Add the following contents to the dbinfo.inc file, where endpoint is the endpoint of your RDS
MySQL DB instance, without the port, and master password is the master password for your RDS
MySQL DB instance.

Note

Placing the user name and password information in a folder that is not part of the
document root for your web server reduces the possibility of your security information
being exposed.


API Version 2014-10-31
63

Amazon Relational Database Service User Guide
Step 2: Create a Web Server

4.

Save and close the dbinfo.inc file.

5.

Change the directory to /var/www/html:
[ec2-user ~]$ cd /var/www/html

6.

Create a new file in the html directory named SamplePage.php, and then edit the file by calling
nano (or the editor of your choice).
[ec2-user ~]$ >SamplePage.php
[ec2-user ~]$ nano SamplePage.php

7.

Add the following contents to the SamplePage.php file:

Note

Placing the user name and password information in a folder that is not part of the
document root for your web server reduces the possibility of your security information
being exposed.



Sample page

Name Address
API Version 2014-10-31 64 Amazon Relational Database Service User Guide Step 2: Create a Web Server
"; echo "", "", ""; echo ""; } ?>
ID Name Address
",$query_data[0], "",$query_data[1], "",$query_data[2], "
Error adding employee data.

"); /* Check whether the table exists and, if not, create it. */ function VerifyEmployeesTable($connection, $dbName) { if(!TableExists("Employees", $connection, $dbName)) { $query = "CREATE TABLE `Employees` ( `ID` int(11) NOT NULL AUTO_INCREMENT, `Name` varchar(45) DEFAULT NULL, `Address` varchar(90) DEFAULT NULL, PRIMARY KEY (`ID`), UNIQUE KEY `ID_UNIQUE` (`ID`) ) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=latin1"; if(!mysqli_query($connection, $query)) echo("

Error creating table.

"); API Version 2014-10-31 65 Amazon Relational Database Service User Guide Step 2: Create a Web Server } } /* Check for the existence of a table. */ function TableExists($tableName, $connection, $dbName) { $t = mysqli_real_escape_string($connection, $tableName); $d = mysqli_real_escape_string($connection, $dbName); $checktable = mysqli_query($connection, "SELECT TABLE_NAME FROM information_schema.TABLES WHERE TABLE_NAME = '$t' AND TABLE_SCHEMA = '$d'"); if(mysqli_num_rows($checktable) > 0) return true; return false; } ?> 8. Save and close the SamplePage.php file. 9. Verify that your web server successfully connects to your RDS MySQL DB instance by opening a web browser and browsing to http://EC2 instance endpoint/SamplePage.php, for example: http://ec2-55-122-41-31.us-west-2.compute.amazonaws.com/SamplePage.php. You can use SamplePage.php to add data to your RDS MySQL DB instance. The data that you add is then displayed on the page. To make sure your RDS MySQL DB instance is as secure as possible, verify that sources outside of the VPC cannot connect to your RDS MySQL DB instance. API Version 2014-10-31 66 Amazon Relational Database Service User Guide Tutorials The following tutorials show you how to perform common tasks that use Amazon RDS: • Tutorial: Create an Amazon VPC for Use with an Amazon RDS DB Instance (p. 415) • Tutorial: Create a Web Server and an Amazon RDS Database (p. 48) • Tutorial: Restore a DB Instance from a DB Snapshot (p. 233) For videos, see AWS Instructional Videos and Labs. API Version 2014-10-31 67 Amazon Relational Database Service User Guide Amazon RDS Basic Operational Guidelines Best Practices for Amazon RDS Learn best practices for working with Amazon RDS. As new best practices are identified, we will keep this section up to date. Topics • Amazon RDS Basic Operational Guidelines (p. 68) • DB Instance RAM Recommendations (p. 69) • Amazon RDS Security Best Practices (p. 69) • Using Enhanced Monitoring to Identify Operating System Issues (p. 69) • Using Metrics to Identify Performance Issues (p. 70) • Best Practices for Working with MySQL Storage Engines (p. 73) • Best Practices for Working with MariaDB Storage Engines (p. 74) • Best Practices for Working with Oracle (p. 74) • Best Practices for Working with PostgreSQL (p. 75) • Best Practices for Working with SQL Server (p. 76) • Working with DB Parameter Groups (p. 77) • Amazon RDS Best Practices Presentation Video (p. 77) Amazon RDS Basic Operational Guidelines The following are basic operational guidelines that everyone should follow when working with Amazon RDS. Note that the Amazon RDS Service Level Agreement requires that you follow these guidelines: • Monitor your memory, CPU, and storage usage. Amazon CloudWatch can be set up to notify you when usage patterns change or when you approach the capacity of your deployment, so that you can maintain system performance and availability. • Scale up your DB instance when you are approaching storage capacity limits. You should have some buffer in storage and memory to accommodate unforeseen increases in demand from your applications. • Enable automatic backups and set the backup window to occur during the daily low in write IOPS. • If your database workload requires more I/O than you have provisioned, recovery after a failover or database failure will be slow. To increase the I/O capacity of a DB instance, do any or all of the following: • Migrate to a DB instance class with High I/O capacity. • Convert from standard storage to either General Purpose or Provisioned IOPS storage, depending on how much of an increase you need. For information on available storage types, see Amazon RDS Storage Types (p. 101). If you convert to Provisioned IOPS storage, make sure you also use a DB instance class that is optimized for Provisioned IOPS. For information on Provisioned IOPS, see Provisioned IOPS SSD Storage (p. 103). • If you are already using Provisioned IOPS storage, provision additional throughput capacity. • If your client application is caching the Domain Name Service (DNS) data of your DB instances, set a time-to-live (TTL) value of less than 30 seconds. Because the underlying IP address of a DB instance can change after a failover, caching the DNS data for an extended time can lead to connection failures if your application tries to connect to an IP address that no longer is in service. API Version 2014-10-31 68 Amazon Relational Database Service User Guide DB Instance RAM Recommendations • Test failover for your DB instance to understand how long the process takes for your use case and to ensure that the application that accesses your DB instance can automatically connect to the new DB instance after failover. DB Instance RAM Recommendations An Amazon RDS performance best practice is to allocate enough RAM so that your working set resides almost completely in memory. To tell if your working set is almost all in memory, check the ReadIOPS metric (using Amazon CloudWatch) while the DB instance is under load. The value of ReadIOPS should be small and stable. If scaling up the DB instance class—to a class with more RAM—results in a dramatic drop in ReadIOPS, your working set was not almost completely in memory. Continue to scale up until ReadIOPS no longer drops dramatically after a scaling operation, or ReadIOPS is reduced to a very small amount. For information on monitoring a DB instance's metrics, see Viewing DB Instance Metrics (p. 248). Amazon RDS Security Best Practices Use AWS IAM accounts to control access to Amazon RDS API actions, especially actions that create, modify, or delete RDS resources such as DB instances, security groups, option groups, or parameter groups, and actions that perform common administrative actions such as backing up and restoring DB instances, or configuring Provisioned IOPS storage. • Assign an individual IAM account to each person who manages RDS resources. Do not use AWS root credentials to manage Amazon RDS resources; you should create an IAM user for everyone, including yourself. • Grant each user the minimum set of permissions required to perform his or her duties. • Use IAM groups to effectively manage permissions for multiple users. • Rotate your IAM credentials regularly. For more information about IAM, go to AWS Identity and Access Management. For information on IAM best practices, go to IAM Best Practices. Use the AWS Management Console, the AWS CLI, or the Amazon RDS API to change the password for your master user. If you use another tool, such as a SQL client, to change the master user password, it might result in privileges being revoked for the user unintentionally. Using Enhanced Monitoring to Identify Operating System Issues Amazon RDS provides metrics in real time for the operating system (OS) that your DB instance runs on. You can view the metrics for your DB instance using the console, or consume the Enhanced Monitoring JSON output from Amazon CloudWatch Logs in a monitoring system of your choice. For more information about Enhanced Monitoring, see Enhanced Monitoring (p. 250) Enhanced Monitoring is available for the following database engines: • MariaDB • Microsoft SQL Server • MySQL version 5.5 or later API Version 2014-10-31 69 Amazon Relational Database Service User Guide Using Metrics to Identify Performance Issues • Oracle • PostgreSQL Enhanced monitoring is available for all DB instance classes except for db.m1.small. Enhanced Monitoring is available in all regions except for AWS GovCloud (US-West). Using Metrics to Identify Performance Issues To identify performance issues caused by insufficient resources and other common bottlenecks, you can monitor the metrics available for your Amazon RDS DB instance. Viewing Performance Metrics You should monitor performance metrics on a regular basis to see the average, maximum, and minimum values for a variety of time ranges. If you do so, you can identify when performance is degraded. You can also set Amazon CloudWatch alarms for particular metric thresholds so you are alerted if they are reached. In order to troubleshoot performance issues, it’s important to understand the baseline performance of the system. When you set up a new DB instance and get it running with a typical workload, you should capture the average, maximum, and minimum values of all of the performance metrics at a number of different intervals (for example, one hour, 24 hours, one week, two weeks) to get an idea of what is normal. It helps to get comparisons for both peak and off-peak hours of operation. You can then use this information to identify when performance is dropping below standard levels. To view performance metrics 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the left navigation pane, select Instances, and then select a DB instance. 3. Select Show Monitoring. The first eight performance metrics display. The metrics default to showing information for the current day. 4. Use the numbered buttons at top right to page through the additional metrics, or select Show All to see all metrics. 5. Select a performance metric to adjust the time range in order to see data for other than the current day. You can change the Statistic, Time Range, and Period values to adjust the information displayed. For example, to see the peak values for a metric for each day of the last two weeks, set Statistic to Maximum, Time Range to Last 2 Weeks, and Period to Day. Note Changing the Statistic, Time Range, and Period values changes them for all metrics. The updated values persist for the remainder of your session or until you change them again. You can also view performance metrics using the CLI or API. For more information, see Viewing DB Instance Metrics (p. 248). To set a CloudWatch alarm 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the left navigation pane, select Instances, and then select a DB instance. 3. Select Show Monitoring, and then select a performance metric to bring up the expanded view. API Version 2014-10-31 70 Amazon Relational Database Service User Guide Evaluating Performance Metrics 4. Select Create Alarm. 5. On the Create Alarm page, identify what email address should receive the alert by selecting a value in the Send a notification to box. Select create topic to the right of that box to create a new alarm recipient if necessary. 6. In the Whenever list, select the alarm statistic to set. 7. In the of box, select the alarm metric. 8. In the Is box and the unlabeled box to the right of it, set the alarm threshold, as shown following: 9. In the For at least box, enter the number of times that the specified threshold must be reached in order to trigger the alarm. 10. In the consecutive period(s) of box, select the period during which the threshold must have been reached in order to trigger the alarm. 11. In the Name of alarm box, enter a name for the alarm. 12. Select Create Alarm. The performance metrics page appears, and you can see the new alarm in the CloudWatch Alarms status bar. If you don't see the status bar, refresh your page. Evaluating Performance Metrics A DB instance has a number of different categories of metrics, and how to determine acceptable values depends on the metric. CPU • CPU Utilization – Percentage of computer processing capacity used. Memory • Freeable Memory – How much RAM is available on the DB instance, in megabytes. The red line in the Monitoring tab metrics is marked at 75% for CPU, Memory and Storage Metrics. If instance memory consumption frequently crosses that line, then this indicates that you should check your workload or upgrade your instance. • Swap Usage – How much swap space is used by the DB instance, in megabytes. API Version 2014-10-31 71 Amazon Relational Database Service User Guide Evaluating Performance Metrics Disk space • Free Storage Space – How much disk space is not currently being used by the DB instance, in megabytes. Input/output operations • Read IOPS, Write IOPS – The average number of disk read or write operations per second. • Read Latency, Write Latency – The average time for a read or write operation in milliseconds. • Read Throughput, Write Throughput – The average number of megabytes read from or written to disk per second. • Queue Depth – The number of I/O operations that are waiting to be written to or read from disk. Network traffic • Network Receive Throughput, Network Transmit Throughput – The rate of network traffic to and from the DB instance in megabytes per second. Database connections • DB Connections – The number of client sessions that are connected to the DB instance. For more detailed individual descriptions of the performance metrics available, see Amazon RDS Dimensions and Metrics. Generally speaking, acceptable values for performance metrics depend on what your baseline looks like and what your application is doing. Investigate consistent or trending variances from your baseline. Advice about specific types of metrics follows: • High CPU or RAM consumption – High values for CPU or RAM consumption might be appropriate, provided that they are in keeping with your goals for your application (like throughput or concurrency) and are expected. • Disk space consumption – Investigate disk space consumption if space used is consistently at or above 85 percent of the total disk space. See if it is possible to delete data from the instance or archive data to a different system to free up space. • Network traffic – For network traffic, talk with your system administrator to understand what expected throughput is for your domain network and Internet connection. Investigate network traffic if throughput is consistently lower than expected. • Database connections – Consider constraining database connections if you see high numbers of user connections in conjunction with decreases in instance performance and response time. The best number of user connections for your DB instance will vary based on your instance class and the complexity of the operations being performed. You can determine the number of database connections by associating your DB instance with a parameter group where the User Connections parameter is set to other than 0 (unlimited). You can either use an existing parameter group or create a new one. For more information, see Working with DB Parameter Groups (p. 165). • IOPS metrics – The expected values for IOPS metrics depend on disk specification and server configuration, so use your baseline to know what is typical. Investigate if values are consistently different than your baseline. For best IOPS performance, make sure your typical working set will fit into memory to minimize read and write operations. For issues with any performance metrics, one of the first things you can do to improve performance is tune the most used and most expensive queries to see if that lowers the pressure on system resources. For more information, see Tuning Queries (p. 73) API Version 2014-10-31 72 Amazon Relational Database Service User Guide Tuning Queries If your queries are tuned and an issue persists, consider upgrading your Amazon RDS DB Instance Class (p. 80) to one with more of the resource (CPU, RAM, disk space, network bandwidth, I/O capacity) that is related to the issue you are experiencing. Tuning Queries One of the best ways to improve DB instance performance is to tune your most commonly used and most resource-intensive queries to make them less expensive to run. MySQL Query Tuning Go to Optimizing SELECT Statements in the MySQL documentation for more information on writing queries for better performance. You can also go to MySQL Performance Tuning and Optimization Resources for additional query tuning resources. Oracle Query Tuning Go to the Database SQL Tuning Guide in the Oracle documentation for more information on writing and analyzing queries for better performance. SQL Server Query Tuning Go to Analyzing a Query in the SQL Server documentation to improve queries for SQL Server DB instances. You can also use the execution-, index- and I/O-related data management views (DMVs) described in the Dynamic Management Views and Functions documentation to troubleshoot SQL Server query issues. A common aspect of query tuning is creating effective indexes. You can use the Database Engine Tuning Advisor to get potential index improvements for your DB instance. For more information, see Analyzing Your Database Workload on an Amazon RDS DB Instance with SQL Server Tuning Advisor (p. 557). PostgreSQL Query Tuning Go to Using EXPLAIN in the PostgreSQL documentation to learn how to analyze a query plan. You can use this information to modify a query or underlying tables in order to improve query performance. You can also go to Controlling the Planner with Explicit JOIN Clauses to get tips about how to specify joins in your query for the best performance. MariaDB Query Tuning Go to Query Optimizations in the MariaDB documentation for more information on writing queries for better performance. Best Practices for Working with MySQL Storage Engines On a MySQL DB instance, observe the following table creation limits: • You're limited to 10,000 tables if you are either using Provisioned IOPS storage, or using General Purpose storage and the DB instance is 200 GiB or larger in size. • You’re limited to 1000 tables if you are either using standard storage, or using General Purpose storage and the DB instance is less than 200 GiB in size. We recommend these limits because having large numbers of tables significantly increases database recovery time after a failover or database crash. If you need to create more tables than recommended, API Version 2014-10-31 73 Amazon Relational Database Service User Guide Best Practices for Working with MariaDB Storage Engines set the innodb_file_per_table parameter to 0. For more information, see Working with InnoDB Tablespaces to Improve Crash Recovery Times (p. 679) and Working with DB Parameter Groups (p. 165). For MySQL DB instances that use version 5.7 or later, you can exceed these table creation limits due to improvements in InnoDB crash recovery. However, we still recommend that you take caution due to the potential performance impact of creating very large numbers of tables. On a MySQL DB instance, avoid tables in your database growing too large. Provisioned storage limits restrict the maximum size of a MySQL table file to 16 TB. Instead, partition your large tables so that file sizes are well under the 16 TB limit. This approach can also improve performance and recovery time. For more information, see MySQL File Size Limits (p. 683). The Point-In-Time Restore and snapshot restore features of Amazon RDS for MySQL require a crashrecoverable storage engine and are supported for the InnoDB storage engine only. Although MySQL supports multiple storage engines with varying capabilities, not all of them are optimized for crash recovery and data durability. For example, the MyISAM storage engine does not support reliable crash recovery and might prevent a Point-In-Time Restore or snapshot restore from working as intended. This might result in lost or corrupt data when MySQL is restarted after a crash. InnoDB is the recommended and supported storage engine for MySQL DB instances on Amazon RDS. InnoDB instances can also be migrated to Aurora, while MyISAM instances can't be migrated. However, MyISAM performs better than InnoDB if you require intense, full-text search capability. If you still choose to use MyISAM with Amazon RDS, following the steps outlined in Automated Backups with Unsupported MySQL Storage Engines (p. 208) can be helpful in certain scenarios for snapshot restore functionality. If you want to convert existing MyISAM tables to InnoDB tables, you can use the process outlined in the MySQL documentation. MyISAM and InnoDB have different strengths and weaknesses, so you should fully evaluate the impact of making this switch on your applications before doing so. In addition, Federated Storage Engine is currently not supported by Amazon RDS for MySQL. Best Practices for Working with MariaDB Storage Engines The point-in-time restore and snapshot restore features of Amazon RDS for MariaDB require a crashrecoverable storage engine. Although MariaDB supports multiple storage engines with varying capabilities, not all of them are optimized for crash recovery and data durability. For example, although Aria is a crash-safe replacement for MyISAM, it might still prevent a point-in-time restore or snapshot restore from working as intended. This might result in lost or corrupt data when MariaDB is restarted after a crash. InnoDB (for version 10.2 and higher) and XtraDB (for version 10.0 and 10.1) are the recommended and supported storage engines for MariaDB DB instances on Amazon RDS. If you still choose to use Aria with Amazon RDS, following the steps outlined in Automated Backups with Unsupported MariaDB Storage Engines (p. 209) can be helpful in certain scenarios for snapshot restore functionality. Best Practices for Working with Oracle For information about best practices for working with Amazon RDS for Oracle, see Best Practices for Running Oracle Database on Amazon Web Services and the video Running Oracle Databases on Amazon RDS. API Version 2014-10-31 74 Amazon Relational Database Service User Guide Best Practices for Working with PostgreSQL Best Practices for Working with PostgreSQL Two important areas where you can improve performance with PostgreSQL on Amazon RDS are when loading data into a DB instance and when using the PostgreSQL autovacuum feature. The following sections cover some of the practices we recommend for these areas. Loading Data into a PostgreSQL DB Instance When loading data into an Amazon RDS PostgreSQL DB instance, you should modify your DB instance settings and your DB parameter group values to allow for the most efficient importing of data into your DB instance. Modify your DB instance settings to the following: • Disable DB instance backups (set backup_retention to 0) • Disable Multi-AZ Modify your DB parameter group to include the following settings. You should test the parameter settings to find the most efficient settings for your DB instance: • Increase the value of the maintenance_work_mem parameter. For more information about PostgreSQL resource consumption parameters, see the PostgreSQL documentation. • Increase the value of the checkpoint_segments and checkpoint_timeout parameters to reduce the number of writes to the wal log. • Disable the synchronous_commit parameter (do not turn off FSYNC). • Disable the PostgreSQL autovacuum parameter. • Make sure none of the tables you are importing are unlogged. Data stored in unlogged tables can be lost during a failover. For more information see, CREATE TABLE UNLOGGED Use the pg_dump -Fc (compressed) or pg_restore -j (parallel) commands with these settings. Working with the fsync and full_page_writes database parameters In PostgreSQL 9.4.1 on Amazon RDS, the fsync and full_page_writes database parameters are not modifiable. Disabling the fsync and full_page_writes database parameters can lead to data corruption, so we have enabled them for you. We recommend that customers with other 9.3 DB engine versions of PostgreSQL not disable the fsync and full_page_writes parameters. Working with the PostgreSQL Autovacuum Feature The autovacuum feature for PostgreSQL databases is a feature that we strongly recommend you use to maintain the health of your PostgreSQL DB instance. Autovacuum automates the execution of the VACUUM and ANALYZE command; using autovacuum is required by PostgreSQL, not imposed by Amazon RDS, and its use is critical to good performance. The feature is enabled by default for all new Amazon RDS PostgreSQL DB instances, and the related configuration parameters are appropriately set by default. Your database administrator needs to know and understand this maintenance operation. For the PostgreSQL documentation on autovacuum, see http://www.postgresql.org/docs/current/static/ routine-vacuuming.html#AUTOVACUUM. API Version 2014-10-31 75 Amazon Relational Database Service User Guide Best Practices for Working with SQL Server Autovacuum is not a “resource free” operation, but it works in the background and yields to user operations as much as possible. When enabled, autovacuum checks for tables that have had a large number of updated or deleted tuples. It also protects against loss of very old data due to transaction ID wraparound. Autovacuum should not be thought of as a high-overhead operation that can be reduced to gain better performance. On the contrary, tables that have a high velocity of updates and deletes will quickly deteriorate over time if autovacuum is not run. Important Not running autovacuum can result in an eventual required outage to perform a much more intrusive vacuum operation. When an Amazon RDS PostgreSQL DB instance becomes unavailable because of an over conservative use of autovacuum, the PostgreSQL database will shut down to protect itself. At that point, Amazon RDS must perform a single-user-mode full vacuum directly on the DB instance , which can result in a multi-hour outage. Thus, we strongly recommend that you do not turn off autovacuum, which is enabled by default. The autovacuum parameters determine when and how hard autovacuum works. The autovacuum_vacuum_threshold and autovacuum_vacuum_scale_factor parameters determine when autovacuum is run. The autovacuum_max_workers, autovacuum_nap_time, autovacuum_cost_limit, and autovacuum_cost_delay parameters determine how hard autovacuum works. For more information about autovacuum, when it runs, and what parameters are required, see the PostgreSQL documentation. The following query shows the number of "dead" tuples in a table named table1 : PROMPT> select relname, n_dead_tup, last_vacuum, last_autovacuum from pg_catalog.pg_stat_all_tables where n_dead_tup > 0 and relname = ’table1' order by n_dead_tup desc; The results of the query will resemble the following: relname | n_dead_tup | last_vacuum | last_autovacuum ---------+------------+-------------+----------------tasks | 81430522 | | (1 row) Best Practices for Working with SQL Server Best practices for a Multi-AZ deployment with a SQL Server DB instance include the following: • Use Amazon RDS DB events to monitor failovers. For example, you can be notified by text message or email when a DB instance fails over. For more information about Amazon RDS events, see Using Amazon RDS Event Notification (p. 278). • If your application caches DNS values, set time to live (TTL) to less than 30 seconds. Setting TTL as so is a good practice in case there is a failover, where the IP address might change and the cached value might no longer be in service. • We recommend that you do not enable the following modes because they turn off transaction logging, which is required for Multi-AZ: • Simple recover mode • Offline mode • Read-only mode • Test to determine how long it takes for your DB instance to failover. Failover time can vary due to the type of database, the instance class, and the storage type you use. You should also test your application's ability to continue working if a failover occurs. API Version 2014-10-31 76 Amazon Relational Database Service User Guide Working with DB Parameter Groups • To shorten failover time, you should do the following: • Ensure that you have sufficient Provisioned IOPS allocated for your workload. Inadequate I/O can lengthen failover times. Database recovery requires I/O. • Use smaller transactions. Database recovery relies on transactions, so if you can break up large transactions into multiple smaller transactions, your failover time should be shorter. • Take into consideration that during a failover, there will be elevated latencies. As part of the failover process, Amazon RDS automatically replicates your data to a new standby instance. This replication means that new data is being committed to two different DB instances, so there might be some latency until the standby DB instance has caught up to the new primary DB instance. • Deploy your applications in all Availability Zones. If an Availability Zone does go down, your applications in the other Availability Zones will still be available. When working with a Multi-AZ deployment of SQL Server, remember that Amazon RDS creates replicas for all SQL Server databases on your instance. If you don't want specific databases to have secondary replicas, set up a separate DB instance that doesn't use Multi-AZ for those databases. Working with DB Parameter Groups We recommend that you try out DB parameter group changes on a test DB instance before applying parameter group changes to your production DB instances. Improperly setting DB engine parameters in a DB parameter group can have unintended adverse effects, including degraded performance and system instability. Always exercise caution when modifying DB engine parameters and back up your DB instance before modifying a DB parameter group. For information about backing up your DB instance, see Backing Up and Restoring Amazon RDS DB Instances (p. 201). Amazon RDS Best Practices Presentation Video The 2016 AWS Summit conference in Chicago included a presentation on best practices for creating and configuring a secure, highly available database instance using Amazon RDS. A video of the presentation is available here. API Version 2014-10-31 77 Amazon Relational Database Service User Guide Amazon RDS DB Instances A DB instance is an isolated database environment running in the cloud. It is the basic building block of Amazon RDS. A DB instance can contain multiple user-created databases, and can be accessed using the same client tools and applications you might use to access a standalone database instance. DB instances are simple to create and modify with the Amazon AWS command line tools, Amazon RDS API actions, or the AWS Management Console. Note Amazon RDS supports access to databases using any standard SQL client application. Amazon RDS does not allow direct host access. You can have up to 40 Amazon RDS DB instances. Of these 40, up to 10 can be Oracle or SQL Server DB instances under the "License Included" model. All 40 DB instances can be used for MySQL, MariaDB, or PostgreSQL. You can also have 40 DB instances for SQL Server or Oracle under the "BYOL" licensing model. If your application requires more DB instances, you can request additional DB instances using the form at https://console.aws.amazon.com/support/home#/case/create?issueType=service-limitincrease&limitType=service-code-rds-instances. Each DB instance has a DB instance identifier. This customer-supplied name uniquely identifies the DB instance when interacting with the Amazon RDS API and AWS CLI commands. The DB instance identifier must be unique for that customer in an AWS Region. Each DB instance supports a database engine. Amazon RDS currently supports MySQL, MariaDB, PostgreSQL, Oracle, Microsoft SQL Server, and Amazon Aurora database engines. When creating a DB instance, some database engines require that a database name be specified. A DB instance can host multiple databases, or a single Oracle database with multiple schemas. The database name value depends on the database engine: • For the MySQL and MariaDB database engines, the database name is the name of a database hosted in your DB instance. Databases hosted by the same DB instance must have a unique name within that instance. • For the Oracle database engine, database name is used to set the value of ORACLE_SID, which must be supplied when connecting to the Oracle RDS instance. • For the Microsoft SQL Server database engine, database name is not a supported parameter. • For the PostgreSQL database engine, the database name is the name of a database hosted in your DB instance. A database name is not required when creating a DB instance. Databases hosted by the same DB instance must have a unique name within that instance. Amazon RDS creates a master user account for your DB instance as part of the creation process. This master user has permissions to create databases and to perform create, delete, select, update, and insert operations on tables the master user creates. You must set the master user password when you create a DB instance, but you can change it at any time using the Amazon AWS command line tools, Amazon RDS API actions, or the AWS Management Console. You can also change the master user password and manage users using standard SQL commands. Note This guide covers non-Aurora Amazon RDS database engines. For information about using Amazon Aurora, see the Amazon Aurora User Guide. Topics • DB Instance Class (p. 80) • DB Instance Status (p. 96) API Version 2014-10-31 78 Amazon Relational Database Service User Guide • Regions and Availability Zones (p. 99) • DB instance storage (p. 101) • High Availability (Multi-AZ) for Amazon RDS (p. 107) • Amazon RDS DB Instance Lifecycle (p. 110) • Tagging Amazon RDS Resources (p. 134) • Working with Read Replicas of MariaDB, MySQL, and PostgreSQL DB Instances (p. 139) • Working with Option Groups (p. 152) • Working with DB Parameter Groups (p. 165) • Working with Amazon Resource Names (ARNs) in Amazon RDS (p. 177) • Working with Storage (p. 183) • DB Instance Billing for Amazon RDS (p. 188) API Version 2014-10-31 79 Amazon Relational Database Service User Guide DB Instance Class DB Instance Class The DB instance class determines the computation and memory capacity of an Amazon RDS DB instance. The DB instance class you need depends on your processing power and memory requirements. For more information about instance class pricing, see Amazon RDS Pricing. DB Instance Class Types Amazon RDS supports three types of instance classes: Standard, Memory Optimized, and Burstable Performance. For more information about Amazon EC2 instance types, see Instance Type in the Amazon EC2 documentation. The following are the Standard DB instance classes available: • db.m5 – Latest-generation general-purpose instance classes that provide a balance of compute, memory, and network resources, and are a good choice for many applications. The db.m5 instance classes provide more computing capacity than the previous db.m4 instance classes. • db.m4 – Current-generation general-purpose instance classes that provide more computing capacity than the previous db.m3 instance classes. • db.m3 – Previous-generation general-purpose instance classes that provide more computing capacity than the previous db.m1 instance classes. • db.m1 – Previous-generation general-purpose instance classes. The following are the Memory Optimized DB instance classes available: • db.x1e – Latest-generation instance classes optimized for memory-intensive applications. These offer one of the lowest price per GiB of RAM among the DB instance classes and up to 3,904 GiB of DRAMbased instance memory. The db.x1e instance classes are available only in the following regions: US East (N. Virginia), US West (Oregon), EU (Ireland), Asia Pacific (Tokyo), and Asia Pacific (Sydney). • db.x1 – Current-generation instance classes optimized for memory-intensive applications. These offer one of the lowest price per GiB of RAM among the DB instance classes and up to 1,952 GiB of DRAMbased instance memory. • db.r5 – Latest-generation instance classes optimized for memory-intensive applications. These offer a better price per GiB of RAM than the db.r4 instance classes. • db.r4 – Current-generation instance classes optimized for memory-intensive applications. These offer a better price per GiB of RAM than the db.r3 instance classes. • db.r3 – Previous-generation instance classes that provide memory optimization and more computing capacity than the db.m2 instance classes. The db.r3 instances classes are not available in the EU (Paris) region and the South America (São Paulo) region. • db.m2 – Previous-generation memory-optimized instance classes. The following are the Burstable Performance DB instance classes available: • db.t2 – Instance classes that provide a baseline performance level, with the ability to burst to full CPU usage. We recommend only using these instance classes for development and test servers, or other non-production servers. Specifications for All Available DB Instance Classes The following table provides details of the Amazon RDS DB instance classes. The table columns are explained after the table. API Version 2014-10-31 80 Amazon Relational Database Service User Guide Specifications for All Available DB Instance Classes Instance Class 1 2 vCPU ECU 3 9 10 Memory VPC EBS Max. Network MariaDB Microsoft MySQLOraclePostgreSQL 4 5 6 7 (GiB) Only Optimized Bandwidth Performance SQL 8 (Mbps) Server db.m5 – Latest Generation Standard Instance Classes 9 Yes 9 Yes 9 Yes 9 Yes 9 Yes 9 Yes 9 Yes 9 Yes 9 Yes 9 Yes 9 Yes 9 Yes 9 Yes 9 Yes 9 Yes 9 Yes db.m5.24xlarge 96 345 384 Yes Yes 14,000 25 Gbps Yes No Yes Yes db.m5.12xlarge 48 173 192 Yes Yes 7,000 10 Gbps Yes No Yes Yes db.m5.4xlarge 16 61 64 Yes Yes 3,500 Up Yes to 10 Gigabit No Yes Yes db.m5.2xlarge 8 31 32 Yes Yes 3,500 Up Yes to 10 Gigabit No Yes Yes db.m5.xlarge 4 15 16 Yes Yes 3,500 Up Yes to 10 Gigabit No Yes Yes db.m5.large 2 10 8 Yes Yes 3,500 Up Yes to 10 Gigabit No Yes Yes 10 10 10 10 10 10 db.m4 – Current Generation Standard Instance Classes 8 MySQLYes 8.0, 5.7, 5.6 8 Yes Yes 8 Yes Yes 8 Yes Yes 8 Yes Yes 8 Yes Yes 8 Yes Yes 8 Yes Yes 8 Yes Yes db.m4.16xlarge 64 188 256 Yes Yes 10,000 25 Gbps Yes Yes db.m4.10xlarge 40 124.5 160 Yes Yes 4,000 10 Gbps Yes Yes db.m4.4xlarge 16 53.5 64 Yes Yes 2,000 High Yes Yes db.m4.2xlarge 8 25.5 32 Yes Yes 1,000 High Yes Yes db.m4.xlarge 4 13 16 Yes Yes 750 High Yes Yes db.m4.large 2 6.5 8 Yes Yes 450 ModerateYes Yes db.m3 – Previous Generation Standard Instance Classes db.m3.2xlarge 8 26 30 No Yes 1,000 High No Yes db.m3.xlarge 4 13 15 No Yes 500 High No Yes db.m3.large 2 6.5 7.5 No No — ModerateNo Yes db.m3.medium 1 3 3.75 No No — 8 Yes 8 MySQLDeprecated PostgreSQL 5.6, 9.4, 5.5 9.3 ModerateNo Yes High Yes Yes db.m1 – Previous Generation Standard Instance Classes db.m1.xlarge 4 4 15 No Yes 450 API Version 2014-10-31 81 No 9 Amazon Relational Database Service User Guide Specifications for All Available DB Instance Classes 1 2 3 9 10 Instance Class vCPU ECU Memory VPC EBS Max. Network MariaDB Microsoft MySQLOraclePostgreSQL 4 5 6 7 (GiB) Only Optimized Bandwidth Performance SQL 8 (Mbps) Server db.m1.large 2 2 7.5 No Yes 450 ModerateNo Yes db.m1.medium 1 1 3.75 No No — ModerateNo Yes db.m1.small 1 1 1.7 No No — Very Low No 8 MySQLDeprecated PostgreSQL 5.6, 9.4, 5.5 9.3 9 8 MySQLDeprecated PostgreSQL 5.6, 9.4, 5.5 9.3 Yes 8 MySQLDeprecated PostgreSQL 5.6, 9.4, 5.5 9.3 9 9 db.x1e – Latest Generation Memory Optimized Instance Classes 9 No 9 No 9 No 9 No 9 No 9 No 9 No 9 No 9 No 9 No 9 No db.x1e.32xlarge 128 340 3,904 Yes Yes 14,000 25 Gbps No No No Yes db.x1e.16xlarge 64 179 1,952 Yes Yes 7,000 10 Gbps No No No Yes db.x1e.8xlarge 32 91 976 Yes Yes 3,500 Up to 10 Gbps No No No Yes db.x1e.4xlarge 16 47 488 Yes Yes 1,750 Up to 10 Gbps No No No Yes db.x1e.2xlarge 8 23 244 Yes Yes 1,000 Up to 10 Gbps No No No Yes db.x1e.xlarge 4 12 122 Yes Yes 500 Up to 10 Gbps No No No Yes db.x1 – Current Generation Memory Optimized Instance Classes db.x1.32xlarge 128 349 1,952 Yes Yes 14,000 25 Gbps No No No Yes db.x1.16xlarge 64 349 976 Yes Yes 7,000 No No No Yes 10 Gbps db.r5 – Latest Generation Memory Optimized Instance Classes db.r5.24xlarge 96 347 768 Yes Yes 14,000 25 Gbps No No No Yes db.r5.12xlarge 48 173 384 Yes Yes 7,000 10 Gbps No No No Yes db.r5.4xlarge 16 71 128 Yes Yes 3,500 Up to 10 Gbps No No No Yes API Version 2014-10-31 82 Amazon Relational Database Service User Guide Specifications for All Available DB Instance Classes 1 2 3 9 10 Instance Class vCPU ECU Memory VPC EBS Max. Network MariaDB Microsoft MySQLOraclePostgreSQL 4 5 6 7 (GiB) Only Optimized Bandwidth Performance SQL 8 (Mbps) Server db.r5.2xlarge 8 38 64 Yes Yes Up to 3,500 Up to 10 Gbps No No No Yes db.r5.xlarge 4 19 32 Yes Yes Up to 3,500 Up to 10 Gbps No No No Yes db.r5.large 2 10 16 Yes Yes Up to 3,500 Up to 10 Gbps No No No Yes 9 No 9 No 9 No 9 PostgreSQL 9.6, 9.5, 9.4 9 PostgreSQL 9.6, 9.5, 9.4 9 PostgreSQL 9.6, 9.5, 9.4 9 PostgreSQL 9.6, 9.5, 9.4 9 PostgreSQL 9.6, 9.5, 9.4 9 PostgreSQL 9.6, 9.5, 9.4 9 Yes 9 Yes 9 Yes 9 Yes 9 Yes db.r4 – Current Generation Memory Optimized Instance Classes 8 MySQLYes 8.0, 5.7, 5.6 8 MySQLYes 8.0, 5.7, 5.6 8 MySQLYes 8.0, 5.7, 5.6 8 MySQLYes 8.0, 5.7, 5.6 8 MySQLYes 8.0, 5.7, 5.6 8 MySQLYes 8.0, 5.7, 5.6 8 Yes Yes 8 Yes Yes 8 Yes Yes 8 Yes Yes 8 Yes Yes db.r4.16xlarge 64 195 488 Yes Yes 14,000 25 Gbps Yes Yes db.r4.8xlarge 32 99 244 Yes Yes 7,000 10 Gbps Yes Yes db.r4.4xlarge 16 53 122 Yes Yes 3,500 Up to 10 Gbps Yes Yes db.r4.2xlarge 8 27 61 Yes Yes 1,750 Up to 10 Gbps Yes Yes db.r4.xlarge 4 13.5 30.5 Yes Yes 875 Up to 10 Gbps Yes Yes db.r4.large 2 7 Yes Yes 437 Up to 10 Gbps Yes Yes 15.25 db.r3 – Previous Generation Memory Optimized Instance Classes db.r3.8xlarge 32 104 244 No No — 10 Gbps Yes Yes db.r3.4xlarge 16 52 122 No Yes 2,000 High Yes Yes db.r3.2xlarge 8 26 61 No Yes 1,000 High Yes Yes db.r3.xlarge 4 13 30.5 No Yes 500 ModerateYes Yes db.r3.large 2 6.5 15.25 No No — ModerateYes Yes API Version 2014-10-31 83 Amazon Relational Database Service User Guide Specifications for All Available DB Instance Classes Instance Class 1 2 vCPU ECU 3 9 10 Memory VPC EBS Max. Network MariaDB Microsoft MySQLOraclePostgreSQL 4 5 6 7 (GiB) Only Optimized Bandwidth Performance SQL 8 (Mbps) Server db.m2 – Previous Generation Memory Optimized Instance Classes 8 MySQLDeprecated PostgreSQL 5.6, 9.4, 5.5 9.3 8 MySQLDeprecated PostgreSQL 5.6, 9.4, 5.5 9.3 Yes 8 MySQLDeprecated PostgreSQL 5.6, 9.4, 5.5 9.3 db.m2.4xlarge 8 26 68.4 No Yes 1,000 High No Yes db.m2.2xlarge 4 13 34.2 No Yes 500 ModerateNo Yes db.m2.xlarge 2 6.5 17.1 No No — ModerateNo 9 9 9 db.t2 – Current Generation Burstable Performance Instance Classes 9 PostgreSQL 9.6, 9.5, 9.4 9 PostgreSQL 9.6, 9.5, 9.4 9 Yes 9 Yes 9 Yes 9 Yes db.t2.2xlarge 8 8 32 Yes No — ModerateYes No MySQLYes 8.0, 5.7, 5.6 db.t2.xlarge 4 4 16 Yes No — ModerateYes No MySQLYes 8.0, 5.7, 5.6 db.t2.large 2 2 8 Yes No — ModerateYes Yes db.t2.medium 2 2 4 Yes No — ModerateYes Yes db.t2.small 1 1 2 Yes No — Low Yes Yes db.t2.micro 1 1 1 Yes No — Low Yes Yes 8 Yes Yes 8 Yes Yes 8 Yes Yes 8 Yes Yes 1. vCPU – The number of virtual central processing units (CPUs). A virtual CPU is a unit of capacity that you can use to compare DB instance classes. Instead of purchasing or leasing a particular processor to use for several months or years, you are renting capacity by the hour. Our goal is to make a consistent and specific amount of CPU capacity available, within the limits of the actual underlying hardware. 2. ECU – The relative measure of the integer processing power of an Amazon EC2 instance. To make it easy for developers to compare CPU capacity between different instance classes, we have defined an Amazon EC2 Compute Unit. The amount of CPU that is allocated to a particular instance is expressed in terms of these EC2 Compute Units. One ECU currently provides CPU capacity equivalent to a 1.0– 1.2 GHz 2007 Opteron or 2007 Xeon processor. 3. Memory (GiB) – The RAM memory, in gibibytes, allocated to the DB instance. There is often a consistent ratio between memory and vCPU. For example, the db.m1 instance class has the same memory to vCPU ratio as the db.m3 instance class, but for most use cases the db.m3 instance class provides better, more consistent performance, than the db.m1 instance class. 4. VPC Only – The instance class is supported only for DB instances that are in an Amazon Virtual Private Cloud (VPC). If your current DB instance is not in a VPC, and you want to use an instance class that requires a VPC, first move your DB instance into a VPC. For more information, see Moving a DB Instance Not in a VPC into a VPC (p. 414). 5. EBS-Optimized – The DB instance uses an optimized configuration stack and provides additional, dedicated capacity for I/O. This optimization provides the best performance by minimizing contention API Version 2014-10-31 84 Amazon Relational Database Service User Guide Changing Your DB Instance Class between I/O and other traffic from your instance. For more information about Amazon EBS–optimized instances, see Amazon EBS–Optimized Instances in the Amazon EC2 documentation. 6. Max. Bandwidth (Mbps) – The maximum bandwidth in megabits per second. Divide by 8 to get the expected throughput in megabytes per second. Important For general purpose (gp2) storage, the maximum throughput is 1,280 Mbps (160 MB/s). For more information on estimating bandwidth for gp2 storage, see General Purpose SSD Storage (p. 101) 7. Network Performance – The network speed relative to other DB instance classes. 8. Microsoft SQL Server – Instance class support varies according to the version and edition of SQL Server. For instance class support by version and edition, see DB Instance Class Support for Microsoft SQL Server (p. 479). 9. Oracle – Instance class support varies according to the version and edition of Oracle. For instance class support by version and edition, see DB Instance Class Support for Oracle (p. 713). 10.PostgreSQL – PostgreSQL versions 9.6.9 (and above) and 10.4 (and above) are supported. Changing Your DB Instance Class You can change the CPU and memory available to a DB instance by changing its DB instance class. To change the DB instance class, modify your DB instance by following the instructions for your specific database engine. • Modifying a DB Instance Running the MariaDB Database Engine (p. 443) • Modifying a DB Instance Running the Microsoft SQL Server Database Engine (p. 510) • Modifying a DB Instance Running the MySQL Database Engine (p. 600) • Modifying a DB Instance Running the Oracle Database Engine (p. 750) • Modifying a DB Instance Running the PostgreSQL Database Engine (p. 973) MySQL DB instances created after April 23, 2014, can change to the db.r3 instance class by modifying the DB instance just as with any other modification. MySQL DB instances running MySQL versions 5.5 and created before April 23, 2014, must first upgrade to MySQL version 5.6. For more information, see Upgrading the MySQL DB Engine (p. 608). Some instance classes require that your DB instance is in a VPC. If your current DB instance is not in a VPC, and you want to use an instance class that requires a VPC, first move your DB instance into a VPC. For more information, see Moving a DB Instance Not in a VPC into a VPC (p. 414). Configuring the Processor for a DB Instance Class Amazon RDS DB instance classes support Intel Hyper-Threading Technology, which enables multiple threads to run concurrently on a single Intel Xeon CPU core. Each thread is represented as a virtual CPU (vCPU) on the DB instance. A DB instance has a default number of CPU cores, which varies according to DB instance type. For example, a db.m4.xlarge DB instance type has two CPU cores and two threads per core by default—four vCPUs in total. Note Each vCPU is a hyperthread of an Intel Xeon CPU core. In most cases, you can find a DB instance class that has a combination of memory and number of vCPUs to suit your workloads. However, you can also specify the following processor features to optimize your DB instance for specific workloads or business needs: API Version 2014-10-31 85 Amazon Relational Database Service User Guide Configuring the Processor for a DB Instance Class • Number of CPU cores – You can customize the number of CPU cores for the DB instance. You might do this to potentially optimize the licensing costs of your software with a DB instance that has sufficient amounts of RAM for memory-intensive workloads but fewer CPU cores. • Threads per core – You can disable Intel Hyper-Threading Technology by specifying a single thread per CPU core. You might do this for certain workloads, such as high-performance computing (HPC) workloads. You can control the number of CPU cores and threads for each core separately. You can set one or both in a request. After a setting is associated with a DB instance, the setting persists until you change it. The processor settings for a DB instance are associated with snapshots of the DB instance. When a snapshot is restored, its restored DB instance uses the processor feature settings used when the snapshot was taken. If you modify the DB instance class for a DB instance with nondefault processor settings, you must either specify default processor settings or explicitly specify processor settings when you modify the DB instance. This requirement ensures that you are aware of the third-party licensing costs that might be incurred when you modify the DB instance. There is no additional or reduced charge for specifying processor features on an Amazon RDS DB instance. You're charged the same as for DB instances that are launched with default CPU configurations. You can configure the number of CPU cores and threads per core for the DB instance class when you perform the following operations: • Creating a DB instance • Modifying a DB instance • Restoring a DB instance from a snapshot • Restoring a DB instance to a point in time Note When you modify a DB instance to configure the number of CPU cores or threads per core, there is a brief DB instance outage. CPU Cores and Threads Per CPU Core Per DB Instance Class In following table, you can find the DB instance classes that support setting a number of CPU cores and CPU threads per core. You can also find the default value and the valid values for the number of CPU cores and CPU threads per core for each DB instance class. DB Instance Class Default vCPUs Default CPU Cores Default Threads per Core Valid Number of CPU Cores Valid Number of Threads per Core db.m5.large 2 1 2 1 1, 2 db.m5.xlarge 4 2 2 2 1, 2 db.m5.2xlarge 8 4 2 2, 4 1, 2 db.m5.4xlarge 16 8 2 2, 4, 6, 8 1, 2 24 2 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, 24 1, 2 db.m5.12xlarge 48 API Version 2014-10-31 86 Amazon Relational Database Service User Guide Configuring the Processor for a DB Instance Class DB Instance Class Default vCPUs Default CPU Cores Default Threads per Core Valid Number of CPU Cores Valid Number of Threads per Core db.m5.24xlarge 96 48 2 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, 24, 26, 28, 30, 32, 34, 36, 38, 40, 42, 44, 46, 48 1, 2 db.m4.10xlarge 40 20 2 2, 4, 6, 8, 10, 12, 14, 16, 18, 20 1, 2 db.m4.16xlarge 64 32 2 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, 24, 26, 28, 30, 32 1, 2 db.r3.large 2 1 2 1 1, 2 db.r3.xlarge 4 2 2 1, 2 1, 2 db.r3.2xlarge 8 4 2 1, 2, 3, 4 1, 2 db.r3.4xlarge 16 8 2 1, 2, 3, 4, 5, 6, 7, 8 1, 2 db.r3.8xlarge 32 16 2 2, 4, 6, 8, 10, 12, 14, 16 1, 2 db.r5.large 2 1 2 1 1 db.r5.xlarge 4 2 2 2 1, 2 db.r5.2xlarge 8 4 2 2, 4 1, 2 db.r5.4xlarge 16 8 2 2, 4, 6, 8 1, 2 db.r5.12xlarge 48 24 2 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, 24 1, 2 db.r5.24xlarge 96 48 2 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, 24, 26, 28, 30, 32, 34, 36, 38, 40, 42, 44, 46, 48 1, 2 db.r4.large 2 1 2 1 1, 2 db.r4.xlarge 4 2 2 1, 2 1, 2 db.r4.2xlarge 8 4 2 1, 2, 3, 4 1, 2 db.r4.4xlarge 16 8 2 1, 2, 3, 4, 5, 6, 7, 8 1, 2 API Version 2014-10-31 87 Amazon Relational Database Service User Guide Configuring the Processor for a DB Instance Class DB Instance Class Default vCPUs Default CPU Cores Default Threads per Core Valid Number of CPU Cores Valid Number of Threads per Core db.r4.8xlarge 32 16 2 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16 1, 2 db.r4.16xlarge 64 32 2 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, 24, 26, 28, 30, 32 1, 2 db.x1.16xlarge 64 32 2 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, 24, 26, 28, 30, 32 1, 2 db.x1.32xlarge 128 64 2 4, 8, 12, 16, 20, 1, 2 24, 28, 32, 36, 40, 44, 48, 52, 56, 60, 64 db.x1e.xlarge 4 2 2 1, 2 1, 2 db.x1e.2xlarge 8 4 2 1, 2, 3, 4 1, 2 db.x1e.4xlarge 16 8 2 1, 2, 3, 4, 5, 6, 7, 8 1, 2 db.x1e.8xlarge 32 16 2 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16 1, 2 db.x1e.16xlarge 64 32 2 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, 24, 26, 28, 30, 32 1, 2 db.x1e.32xlarge 128 64 2 4, 8, 12, 16, 20, 1, 2 24, 28, 32, 36, 40, 44, 48, 52, 56, 60, 64 Note Currently, you can configure the number of CPU cores and threads per core only for Oracle DB instances. For information about the DB instance classes supported by different Oracle database editions, see DB Instance Class Support for Oracle (p. 713). For Oracle DB instances, configuring the number of CPU cores and threads per core is only supported with the Bring Your Own License (BYOL) licensing option. For more information about Oracle licensing options, see Oracle Licensing (p. 712). API Version 2014-10-31 88 Amazon Relational Database Service User Guide Configuring the Processor for a DB Instance Class Setting the CPU Cores and Threads per CPU Core for a DB Instance Class You can set the CPU cores and the threads per CPU core for a DB instance class using the AWS Management Console, the AWS CLI, or the RDS API. AWS Management Console When you are creating, modifying, or restoring a DB instance, you set the DB instance class in the AWS Management Console. The Instance specifications section shows options for the processor. The following image shows the processor features options. API Version 2014-10-31 89 Amazon Relational Database Service User Guide Configuring the Processor for a DB Instance Class API Version 2014-10-31 90 Amazon Relational Database Service User Guide Configuring the Processor for a DB Instance Class Set the following options to the appropriate values for your DB instance class under Processor features: • Core count – Set the number of CPU cores using this option. The value must be equal to or less than the maximum number of CPU cores for the DB instance class. • Threads per core – Specify 2 to enable multiple threads per core, or specify 1 to disable multiple threads per core. When you modify or restore a DB instance, you can also set the CPU cores and the threads per CPU core to the default settings for the selected DB instance class. When you view the details for a DB instance in the console, you can view the processor information for its DB instance class. The following image shows a DB instance class with one CPU core and multiple threads per core enabled. For Oracle DB instances, the processor information only appears for Bring Your Own License (BYOL) DB instances. CLI You can set the processor features for a DB instance when you run one of the following AWS CLI commands: • create-db-instance API Version 2014-10-31 91 Amazon Relational Database Service User Guide Configuring the Processor for a DB Instance Class • modify-db-instance • restore-db-instance-from-db-snapshot • restore-db-instance-from-s3 • restore-db-instance-to-point-in-time To configure the processor of a DB instance class for a DB instance by using the AWS CLI, include the -processor-features option in the command. Specify the number of CPU cores with the coreCount feature name, and specify whether multiple threads per core are enabled with the threadsPerCore feature name. The option has the following syntax. --processor-features "Name=coreCount,Value=" "Name=threadsPerCore,Value=" Example Setting the Number of CPU Cores for a DB Instance The following example modifies mydbinstance by setting the number of CPU cores to 4. The changes are applied immediately by using --apply-immediately. If you want to apply the changes during the next scheduled maintenance window, omit the --apply-immediately option. For Linux, OS X, or Unix: aws rds modify-db-instance \ --processor-features "Name=coreCount,Value=4" \ --apply-immediately For Windows: aws rds modify-db-instance ^ --processor-features "Name=coreCount,Value=4" ^ --apply-immediately Example Setting the Number of CPU Cores and Disabling Multiple Threads for a DB Instance The following example modifies mydbinstance by setting the number of CPU cores to 4 and disabling multiple threads per core. The changes are applied immediately by using --apply-immediately. If you want to apply the changes during the next scheduled maintenance window, omit the --applyimmediately option. For Linux, OS X, or Unix: aws rds modify-db-instance \ --processor-features "Name=coreCount,Value=4" "Name=threadsPerCore,Value=1" \ --apply-immediately For Windows: aws rds modify-db-instance ^ --processor-features "Name=coreCount,Value=4" "Name=threadsPerCore,Value=1" ^ --apply-immediately API Version 2014-10-31 92 Amazon Relational Database Service User Guide Configuring the Processor for a DB Instance Class Example Viewing the Valid Processor Values for a DB Instance Class You can view the valid processor values for a particular DB instance class by running the describeorderable-db-instance-options command and specifying the instance class for the --db-instanceclass option. For example, the output for the following command shows the processor options for the db.r3.large instance class. aws rds describe-orderable-db-instance-options --engine oracle-ee --db-instance-class db.r3.large Following is sample output for the command in JSON format. { } "SupportsIops": true, "MaxIopsPerGib": 50.0, "LicenseModel": "bring-your-own-license", "DBInstanceClass": "db.r3.large", "SupportsIAMDatabaseAuthentication": false, "MinStorageSize": 100, "AvailabilityZones": [ { "Name": "us-west-2a" }, { "Name": "us-west-2b" }, { "Name": "us-west-2c" } ], "EngineVersion": "12.1.0.2.v2", "MaxStorageSize": 32768, "MinIopsPerGib": 1.0, "MaxIopsPerDbInstance": 40000, "ReadReplicaCapable": false, "AvailableProcessorFeatures": [ { "Name": "coreCount", "DefaultValue": "1", "AllowedValues": "1" }, { "Name": "threadsPerCore", "DefaultValue": "2", "AllowedValues": "1,2" } ], "SupportsEnhancedMonitoring": true, "SupportsPerformanceInsights": false, "MinIopsPerDbInstance": 1000, "StorageType": "io1", "Vpc": false, "SupportsStorageEncryption": true, "Engine": "oracle-ee", "MultiAZCapable": true In addition, you can run the following commands for DB instance class processor information: API Version 2014-10-31 93 Amazon Relational Database Service User Guide Configuring the Processor for a DB Instance Class • describe-db-instances – Shows the processor information for the specified DB instance. • describe-db-snapshots – Shows the processor information for the specified DB snapshot. • describe-valid-db-instance-modifications – Shows the valid modifications to the processor for the specified DB instance. Example Returning to Default Processor Settings for a DB Instance The following example modifies mydbinstance by returning its DB instance class to the default processor values for it. The changes are applied immediately by using --apply-immediately. If you want to apply the changes during the next scheduled maintenance window, omit the --applyimmediately option. For Linux, OS X, or Unix: aws rds modify-db-instance \ --use-default-processor-features \ --apply-immediately For Windows: aws rds modify-db-instance ^ --use-default-processor-features ^ --apply-immediately Example Returning to the Default Number of CPU Cores for a DB Instance The following example modifies mydbinstance by returning its DB instance class to the default number of CPU cores for it. The threads per core setting isn't changed. The changes are applied immediately by using --apply-immediately. If you want to apply the changes during the next scheduled maintenance window, omit the --apply-immediately option. For Linux, OS X, or Unix: aws rds modify-db-instance \ --processor-features "Name=coreCount,Value=DEFAULT" \ --apply-immediately For Windows: aws rds modify-db-instance ^ --processor-features "Name=coreCount,Value=DEFAULT" ^ --apply-immediately Example Returning to the Default Number of Threads Per Core for a DB Instance The following example modifies mydbinstance by returning its DB instance class to the default number of threads per core for it. The number of CPU cores setting isn't changed. The changes are applied immediately by using --apply-immediately. If you want to apply the changes during the next scheduled maintenance window, omit the --apply-immediately option. For Linux, OS X, or Unix: aws rds modify-db-instance \ --processor-features "Name=threadsPerCore,Value=DEFAULT" \ --apply-immediately API Version 2014-10-31 94 Amazon Relational Database Service User Guide Configuring the Processor for a DB Instance Class For Windows: aws rds modify-db-instance ^ --processor-features "Name=threadsPerCore,Value=DEFAULT" ^ --apply-immediately API You can set the processor features for a DB instance when you call one of the following Amazon RDS API actions: • CreateDBInstance • ModifyDBInstance • RestoreDBInstanceFromDBSnapshot • RestoreDBInstanceFromS3 • RestoreDBInstanceToPointInTime To configure the processor features of a DB instance class for a DB instance by using the Amazon RDS API, include the ProcessFeatures parameter in the call. The parameter has the following syntax. ProcessFeatures "Name=coreCount,Value=" "Name=threadsPerCore,Value=" Specify the number of CPU cores with the coreCount feature name, and specify whether multiple threads per core are enabled with the threadsPerCore feature name. You can view the valid processor values for a particular instance class by running the DescribeOrderableDBInstanceOptions action and specifying the instance class for the DBInstanceClass parameter. In addition, you can use the following actions for DB instance class processor information: • DescribeDBInstances – Shows the processor information for the specified DB instance. • DescribeDBSnapshots – Shows the processor information for the specified DB snapshot. • DescribeValidDBInstanceModifications – Shows the valid modifications to the processor for the specified DB instance. API Version 2014-10-31 95 Amazon Relational Database Service User Guide DB Instance Status DB Instance Status The status of a DB instance indicates the health of the DB instance. You can view the status of a DB instance by using the Amazon RDS console, the AWS CLI command describe-db-instances, or the API action DescribeDBInstances. Note Amazon RDS also uses another status called maintenance status, which is shown in the Maintenance column of the Amazon RDS console. This value indicates the status of any maintenance patches that need to be applied to a DB instance. Maintenance status is independent of DB instance status. For more information on maintenance status, see Applying Updates for a DB Instance (p. 116). Find the possible status values for DB instances in the following table, which also shows how you are billed for each status. It shows if you will be billed for the DB instance and storage, billed only for storage, or not billed. For all DB instance statuses, you are always billed for backup usage. DB Instance Status Billed Description available Billed The DB instance is healthy and available. backing-up Billed The DB instance is currently being backed up. backtracking Billed The DB instance is currently being backtracked. This status only applies to Aurora MySQL. configuring-enhancedmonitoring Billed Enhanced Monitoring is being enabled or disabled for this DB instance. configuring-iamdatabase-auth Billed AWS Identity and Access Management (IAM) database authentication is being enabled or disabled for this DB instance. configuring-log-exports Billed Publishing log files to Amazon CloudWatch Logs is being enabled or disabled for this DB instance. converting-to-vpc Billed The DB instance is being converted from a DB instance that is not in an Amazon Virtual Private Cloud (Amazon VPC) to a DB instance that is in an Amazon VPC. creating Not billed The DB instance is being created. The DB instance is inaccessible while it is being created. deleting Not billed The DB instance is being deleted. failed Not billed The DB instance has failed and Amazon RDS can't recover it. Perform a point-in-time restore to the latest restorable time of the DB instance to recover the data. inaccessible-encryptioncredentials Not billed The AWS KMS key used to encrypt or decrypt the DB instance can't be accessed. incompatible-credentials Billed The supplied CloudHSM Classic user name or password is incorrect. Update the CloudHSM Classic credentials for the DB instance. incompatible-network Not billed Amazon RDS is attempting to perform a recovery action on a DB instance but can't do so because the VPC is in a state that prevents the action from being completed. This status can occur API Version 2014-10-31 96 Amazon Relational Database Service User Guide DB Instance Status DB Instance Status Billed Description if, for example, all available IP addresses in a subnet are in use and Amazon RDS can't get an IP address for the DB instance. incompatible-optiongroup Billed Amazon RDS attempted to apply an option group change but can't do so, and Amazon RDS can't roll back to the previous option group state. For more information, check the Recent Events list for the DB instance. This status can occur if, for example, the option group contains an option such as TDE and the DB instance doesn't contain encrypted information. incompatibleparameters Billed Amazon RDS can't start the DB instance because the parameters specified in the DB instance's DB parameter group aren't compatible with the DB instance. Revert the parameter changes or make them compatible with the DB instance to regain access to your DB instance. For more information about the incompatible parameters, check the Recent Events list for the DB instance. incompatible-restore Not billed Amazon RDS can't do a point-in-time restore. Common causes for this status include using temp tables, using MyISAM tables with MySQL, or using Aria tables with MariaDB. maintenance Billed Amazon RDS is applying a maintenance update to the DB instance. This status is used for instance-level maintenance that RDS schedules well in advance. modifying Billed The DB instance is being modified because of a customer request to modify the DB instance. moving-to-vpc Billed The DB instance is being moved to a new Amazon Virtual Private Cloud (Amazon VPC). rebooting Billed The DB instance is being rebooted because of a customer request or an Amazon RDS process that requires the rebooting of the DB instance. renaming Billed The DB instance is being renamed because of a customer request to rename it. resetting-mastercredentials Billed The master credentials for the DB instance are being reset because of a customer request to reset them. restore-error Billed The DB instance encountered an error attempting to restore to a point-in-time or from a snapshot. starting Billed The DB instance is starting. for storage stopped Billed The DB instance is stopped. for storage stopping Billed The DB instance is being stopped. for storage API Version 2014-10-31 97 Amazon Relational Database Service User Guide DB Instance Status DB Instance Status Billed Description storage-full Billed The DB instance has reached its storage capacity allocation. This is a critical status, and we recommend that you fix this issue immediately. To do so, scale up your storage by modifying the DB instance. To avoid this situation, set Amazon CloudWatch alarms to warn you when storage space is getting low. storage-optimization Billed Your DB instance is being modified to change the storage size or type. The DB instance is fully operational. However, while the status of your DB instance is storage-optimization, you can't request any changes to the storage of your DB instance. The storage optimization process is usually short, but can sometimes take up to and even beyond 24 hours. upgrading Billed The database engine version is being upgraded. API Version 2014-10-31 98 Amazon Relational Database Service User Guide Regions and Availability Zones Regions and Availability Zones Amazon cloud computing resources are hosted in multiple locations world-wide. These locations are composed of AWS Regions and Availability Zones. Each AWS Region is a separate geographic area. Each AWS Region has multiple, isolated locations known as Availability Zones. Amazon RDS provides you the ability to place resources, such as instances, and data in multiple locations. Resources aren't replicated across AWS Regions unless you do so specifically. Amazon operates state-of-the-art, highly-available data centers. Although rare, failures can occur that affect the availability of instances that are in the same location. If you host all your instances in a single location that is affected by such a failure, none of your instances would be available. It is important to remember that each AWS Region is completely independent. Any Amazon RDS activity you initiate (for example, creating database instances or listing available database instances) runs only in your current default AWS Region. The default AWS Region can be changed in the console, by setting the EC2_REGION environment variable, or it can be overridden by using the --region parameter with the AWS Command Line Interface. See Configuring the AWS Command Line Interface, specifically, the sections on Environment Variables and Command Line Options for more information. Amazon RDS supports a special AWS Region called AWS GovCloud (US-West) that is designed to allow US government agencies and customers to move more sensitive workloads into the cloud. AWS GovCloud (US-West) addresses the US government's specific regulatory and compliance requirements. For more information about AWS GovCloud (US-West), see What Is AWS GovCloud (US-West)? To create or work with an Amazon RDS DB instance in a specific AWS Region, use the corresponding regional service endpoint. Amazon RDS supports the endpoints listed in the following table. Region Name Region Endpoint Protocol US East (Ohio) us-east-2 rds.us-east-2.amazonaws.com HTTPS US East (N. Virginia) us-east-1 rds.us-east-1.amazonaws.com HTTPS US West (N. California) us-west-1 rds.us-west-1.amazonaws.com HTTPS US West (Oregon) us-west-2 rds.us-west-2.amazonaws.com HTTPS API Version 2014-10-31 99 Amazon Relational Database Service User Guide Regions and Availability Zones Region Name Region Endpoint Protocol Asia Pacific (Mumbai) ap-south-1 rds.ap-south-1.amazonaws.com HTTPS Asia Pacific (OsakaLocal) apnortheast-3 rds.ap-northeast-3.amazonaws.com HTTPS Asia Pacific (Seoul) apnortheast-2 rds.ap-northeast-2.amazonaws.com HTTPS Asia Pacific (Singapore) apsoutheast-1 rds.ap-southeast-1.amazonaws.com HTTPS Asia Pacific (Sydney) apsoutheast-2 rds.ap-southeast-2.amazonaws.com HTTPS Asia Pacific (Tokyo) apnortheast-1 rds.ap-northeast-1.amazonaws.com HTTPS Canada (Central) ca-central-1 rds.ca-central-1.amazonaws.com HTTPS China (Beijing) cn-north-1 rds.cn-north-1.amazonaws.com.cn HTTPS China (Ningxia) cnnorthwest-1 rds.cn-northwest-1.amazonaws.com.cn HTTPS EU (Frankfurt) eu-central-1 rds.eu-central-1.amazonaws.com HTTPS EU (Ireland) eu-west-1 rds.eu-west-1.amazonaws.com HTTPS EU (London) eu-west-2 rds.eu-west-2.amazonaws.com HTTPS EU (Paris) eu-west-3 rds.eu-west-3.amazonaws.com HTTPS South America (São Paulo) sa-east-1 rds.sa-east-1.amazonaws.com HTTPS AWS GovCloud (US-East) us-goveast-1 rds.us-gov-east-1.amazonaws.com HTTPS AWS GovCloud (US) us-govwest-1 rds.us-gov-west-1.amazonaws.com HTTPS If you do not explicitly specify an endpoint, the US West (Oregon) endpoint is the default. API Version 2014-10-31 100 Amazon Relational Database Service User Guide DB Instance Storage DB instance storage DB instances for Amazon RDS for MySQL, MariaDB, PostgreSQL, Oracle, and Microsoft SQL Server use Amazon Elastic Block Store (Amazon EBS) volumes for database and log storage. Depending on the amount of storage requested, Amazon RDS automatically stripes across multiple Amazon EBS volumes to enhance performance. Amazon RDS Storage Types Amazon RDS provides three storage types: General Purpose SSD (also known as gp2), Provisioned IOPS SSD (also known as io1), and magnetic. They differ in performance characteristics and price, which means that you can tailor your storage performance and cost to the needs of your database workload. You can create MySQL, MariaDB, Oracle, and PostgreSQL RDS DB instances with up to 32 TiB of storage. You can create SQL Server RDS DB instances with up to 16 TiB of storage. For this amount of storage, use the Provisioned IOPS SSD and General Purpose SSD storage types. The following list briefly describes the three storage types: • General Purpose SSD – General Purpose SSD , also called gp2, volumes offer cost-effective storage that is ideal for a broad range of workloads. These volumes deliver single-digit millisecond latencies and the ability to burst to 3,000 IOPS for extended periods of time. Baseline performance for these volumes is determined by the volume's size. For more information about General Purpose SSD storage, including the storage size ranges, see General Purpose SSD Storage (p. 101). • Provisioned IOPS – Provisioned IOPS storage is designed to meet the needs of I/O-intensive workloads, particularly database workloads, that require low I/O latency and consistent I/O throughput. For more information about provisioned IOPS storage, including the storage size ranges, see Provisioned IOPS SSD Storage (p. 103). • Magnetic – Amazon RDS also supports magnetic storage for backward compatibility. We recommend that you use General Purpose SSD or Provisioned IOPS for any new storage needs. The maximum amount of storage allowed for DB instances on magnetic storage is less than that of the other storage types. For more information, see Magnetic storage (p. 104). Several factors can affect the performance of Amazon EBS volumes, such as instance configuration, I/O characteristics, and workload demand. For more information about getting the most out of your Provisioned IOPS volumes, see Amazon EBS Volume Performance. General Purpose SSD Storage General Purpose SSD storage offers cost-effective storage that is acceptable for most database workloads. The following are the storage size ranges for General Purpose SSD DB instances: • MySQL, MariaDB, Oracle, and PostgreSQL DB instances: 20 GiB–32 TiB • SQL Server for Enterprise, Standard, Web, and Express editions: 20 GiB–16 TiB Baseline I/O performance for General Purpose SSD storage is 3 IOPS for each GiB, which means that larger volumes have better performance. For example, baseline performance for a 100-GiB volume is 300 IOPS, and 3,000 IOPS for a 1-TiB volume. Volumes of 3.34 TiB and greater have a baseline performance of 10,000 IOPS. API Version 2014-10-31 101 Amazon Relational Database Service User Guide General Purpose SSD Storage Volumes below 1 TiB in size also have ability to burst to 3,000 IOPS for extended periods of time (burst is not relevant for volumes above 1 TiB). Instance I/O credit balance determines burst performance. For more information about instance I/O credits see, I/O Credits and Burst Performance (p. 102). Many workloads never deplete the burst balance, making General Purpose SSD an ideal storage choice for many workloads. However, some workloads can exhaust the 3000 IOPS burst storage credit balance, so you should plan your storage capacity to meet the needs of your workloads. I/O Credits and Burst Performance General Purpose SSD storage performance is governed by volume size, which dictates the base performance level of the volume and how quickly it accumulates I/O credits. Larger volumes have higher base performance levels and accumulate I/O credits faster. I/O credits represent the available bandwidth that your General Purpose SSD storage can use to burst large amounts of I/O when more than the base level of performance is needed. The more I/O credits your storage has for I/O, the more time it can burst beyond its base performance level and the better it performs when your workload requires more performance. When using General Purpose SSD storage, your DB instance receives an initial I/O credit balance of 5.4 million I/O credits. This initial credit balance is enough to sustain a burst performance of 3,000 IOPS for 30 minutes. This balance is designed to provide a fast initial boot cycle for boot volumes and to provide a good bootstrapping experience for other applications. Volumes earn I/O credits at the baseline performance rate of 3 IOPS for each GiB of volume size. For example, a 100-GiB SSD volume has a baseline performance of 300 IOPS. When your storage requires more than the base performance I/O level, it uses I/O credits in the I/O credit balance to burst to the required performance level. Such a burst goes to a maximum of 3,000 IOPS. Storage larger than 1,000 GiB has a base performance that is equal or greater than the maximum burst performance. When your storage uses fewer I/O credits than it earns in a second, unused I/O credits are added to the I/O credit balance. The maximum I/O credit balance for a DB instance using General Purpose SSD storage is equal to the initial I/O credit balance (5.4 million I/O credits). Suppose that your storage uses all of its I/O credit balance. If so, its maximum performance remains at the base performance level until I/O demand drops below the base level and unused I/O credits are added to the I/O credit balance. (The base performance level is the rate at which your storage earns I/ O credits.) The more storage, the greater the base performance is and the faster it replenishes the I/O credit balance. Note Storage conversions between magnetic storage and General Purpose SSD storage can potentially deplete your I/O credit balance, resulting in longer conversion times. For more information about scaling storage, see Working with Storage (p. 183). The following table lists several storage sizes. For each storage size, it lists the associated base performance of the storage, which is also the rate at which it accumulates I/O credits. The table also lists the burst duration at the 3,000 IOPS maximum, when starting with a full I/O credit balance. In addition, the table lists the time in seconds that the storage takes to refill an empty I/O credit balance. Storage size (GiB) Base Performance (IOPS) Maximum Burst Duration at 3,000 IOPS (Seconds) Seconds to Fill Empty I/O Credit Balance 1 100 1,862 54,000 100 300 2,000 18,000 250 750 2,400 7,200 500 1,500 3,600 3,600 API Version 2014-10-31 102 Amazon Relational Database Service User Guide Provisioned IOPS Storage Storage size (GiB) Base Performance (IOPS) Maximum Burst Duration at 3,000 IOPS (Seconds) Seconds to Fill Empty I/O Credit Balance 750 2,250 7,200 2,400 1,000 3,000 Infinite N/A 3,333 10,000 Infinite N/A 10,000 10,000 Infinite N/A The burst duration of your storage depends on the size of the storage, the burst IOPS required, and the I/O credit balance when the burst begins. This relationship is shown in the equation following. Burst duration = (Credit balance) -----------------------------------(Burst IOPS) - 3(Storage size in GiB) You might notice that your storage performance is frequently limited to the base level due to an empty I/O credit balance. If so, consider allocating more General Purpose SSD storage with a higher base performance level. Alternatively, you can switch to Provisioned IOPS storage for workloads that require sustained IOPS performance. For workloads with steady state I/O requirements, provisioning less than 100 GiB of General Purpose SSD storage might result in higher latencies if you exhaust your I/O credit balance. Note In general, most workloads never exceed the I/O credit balance. For a more detailed description of how baseline performance and I/O credit balance affect performance see Understanding Burst vs. Baseline Performance with Amazon RDS and GP2. Provisioned IOPS SSD Storage For production application that requires fast and consistent I/O performance, we recommend Provisioned IOPS (input/output operations per second) storage. Provisioned IOPS storage is a storage type that delivers predictable performance, and consistently low latency. Provisioned IOPS storage is optimized for online transaction processing (OLTP) workloads that have consistent performance requirements. Provisioned IOPS helps performance tuning of these workloads. When you create a DB instance, you specify an IOPS rate and the size of the volume. Amazon RDS provides that IOPS rate for the DB instance until you change it. Note Your database workload might not be able to achieve 100 percent of the IOPS that you have provisioned. The following table shows the range of Provisioned IOPS and storage size range for each database engine. Database Engine Range of Provisioned IOPS Range of Storage MariaDB 1,000–40,000 IOPS 100 GiB–32 TiB SQL Server, Enterprise and Standard editions 1000–32,000 IOPS 20 GiB–16 TiB API Version 2014-10-31 103 Amazon Relational Database Service User Guide Magnetic storage Database Engine Range of Provisioned IOPS Range of Storage SQL Server, Web and Express editions 1000–32,000 IOPS 100 GiB–16 TiB MySQL 1,000–40,000 IOPS 100 GiB–32 TiB Oracle 1,000–40,000 IOPS 100 GiB–32 TiB PostgreSQL 1,000–40,000 IOPS 100 GiB–32 TiB Combining Provisioned IOPS Storage with Multi-AZ deployments, or Read Replicas For production OLTP use cases, we recommend that you use Multi-AZ deployments for enhanced fault tolerance with Provisioned IOPS storage for fast and predictable performance. You can also use Provisioned IOPS SSD storage with Read Replicas for MySQL, MariaDB or PostgreSQL. The type of storage for a Read Replica is independent of that on the master DB instance. For example, you might use General Purpose SSD for Read Replicas with a master DB instance that uses Provisioned IOPS SSD storage to reduce costs. However, your Read Replicas performance in this case might differ from that of a configuration where both the master DB instance and the Read Replicas use Provisioned IOPS SSD storage. Provisioned IOPS Storage Costs With Provisioned IOPS storage, you are charged for the provisioned resources whether or not you use them in a given month. For more information about pricing, see Amazon RDS Pricing. Getting the most out of Amazon RDS Provisioned IOPS SSD storage If your workload is I/O constrained, using Provisioned IOPS SSD storage can increase the number of I/O requests that the system can process concurrently. Increased concurrency allows for decreased latency because I/O requests spend less time in a queue. Decreased latency allows for faster database commits, which improves response time and allows for higher database throughput. Provisioned IOPS SSD storage provides a way to reserve I/O capacity by specifying IOPS. However, as with any other system capacity attribute, its maximum throughput under load is constrained by the resource that is consumed first. That resource might be network bandwidth, CPU, memory, or database internal resources. Magnetic storage Amazon RDS also supports magnetic storage for backward compatibility. We recommend that you use General Purpose SSD or Provisioned IOPS SSD for any new storage needs. The following are some limitations for magnetic storage: • Doesn't allow you to scale storage when using the SQL Server database engine. • Doesn't support elastic volumes. • Limited to a maximum size of 4 TiB. • Limited to a maximum of 1,000 IOPS. API Version 2014-10-31 104 Amazon Relational Database Service User Guide Monitoring storage performance Monitoring storage performance Amazon RDS provides several metrics that you can use to determine how your DB instance is performing. You can view the metrics on the summary page for your instance in Amazon RDS Management Console. You can also use Amazon CloudWatch to monitor these metrics. For more information, see Viewing DB Instance Metrics (p. 248). Enhanced Monitoring provides more detailed I/O metrics; for more information, see Enhanced Monitoring (p. 250). The following metrics are useful for monitoring storage for your DB instance: • IOPS – The number of I/O operations completed each second. This metric is reported as the average IOPS for a given time interval. Amazon RDS reports read and write IOPS separately on 1-minute intervals. Total IOPS is the sum of the read and write IOPS. Typical values for IOPS range from zero to tens of thousands per second. • Latency – The elapsed time between the submission of an I/O request and its completion. This metric is reported as the average latency for a given time interval. Amazon RDS reports read and write latency separately on 1-minute intervals in units of seconds. Typical values for latency are in the millisecond (ms). For example, Amazon RDS reports 2 ms as 0.002 seconds. • Throughput – The number of bytes each second that are transferred to or from disk. This metric is reported as the average throughput for a given time interval. Amazon RDS reports read and write throughput separately on 1-minute intervals using units of megabytes per second (MB/s). Typical values for throughput range from zero to the I/O channel’s maximum bandwidth. • Queue Depth – The number of I/O requests in the queue waiting to be serviced. These are I/O requests that have been submitted by the application but have not been sent to the device because the device is busy servicing other I/O requests. Time spent waiting in the queue is a component of latency and service time (not available as a metric). This metric is reported as the average queue depth for a given time interval. Amazon RDS reports queue depth in 1-minute intervals. Typical values for queue depth range from zero to several hundred. Measured IOPS values are independent of the size of the individual I/O operation. This means that when you measure I/O performance, you should look at the throughput of the instance, not simply the number of I/O operations. Factors That Affect Storage Performance Both system activities and database workload can affect storage performance. System activities The following system-related activities consume I/O capacity and might reduce database instance performance while in progress: • Multi-AZ standby creation • Read replica creation • Changing storage types Database workload In some cases your database or application design results in concurrency issues, locking, or other forms of database contention. In these cases, you might not be able to use all the provisioned bandwidth directly. In addition, you may encounter the following workload-related situations: • The throughput limit of the underlying instance type is reached. • Queue depth is consistently less than 1 because your application is not driving enough I/O operations. API Version 2014-10-31 105 Amazon Relational Database Service User Guide Factors That Affect Storage Performance • You experience query contention in the database even though some I/O capacity is unused. If there isn’t at least one system resource that is at or near a limit, and adding threads doesn’t increase the database transaction rate, the bottleneck is most likely contention in the database. The most common forms are row lock and index page lock contention, but there are many other possibilities. If this is your situation, you should seek the advice of a database performance tuning expert. DB instance class To get the most performance out of your Amazon RDS database instance, choose a current generation instance type with enough bandwidth to support your storage type. For example, you can choose EBSoptimized instances and instances with 10-gigabit network connectivity. For the full list of Amazon EC2 instance types that support EBS optimization, see Instance types that support EBS optimization. We encourage you to use the latest generation of instances to get the best performance. Previous generation DB instances have a lower instance storage limit. Scaling higher than 6 TiB is not supported on the following previous generation instances. • db.m1.small • db.m1.medium • db.m1.large • db.m1.xlarge • db.m2.xlarge • db.m2.2xlarge • db.m2.4xlarge • db.m3.large • db.m3.xlarge • db.m3.2xlarge For more information, see Previous Generation DB Instances. API Version 2014-10-31 106 Amazon Relational Database Service User Guide High Availability (Multi-AZ) High Availability (Multi-AZ) for Amazon RDS Amazon RDS provides high availability and failover support for DB instances using Multi-AZ deployments. Amazon RDS uses several different technologies to provide failover support. MultiAZ deployments for Oracle, PostgreSQL, MySQL, and MariaDB DB instances use Amazon's failover technology. SQL Server DB instances use SQL Server Mirroring. In a Multi-AZ deployment, Amazon RDS automatically provisions and maintains a synchronous standby replica in a different Availability Zone. The primary DB instance is synchronously replicated across Availability Zones to a standby replica to provide data redundancy, eliminate I/O freezes, and minimize latency spikes during system backups. Running a DB instance with high availability can enhance availability during planned system maintenance, and help protect your databases against DB instance failure and Availability Zone disruption. For more information on Availability Zones, see Regions and Availability Zones (p. 99). Note The high-availability feature is not a scaling solution for read-only scenarios; you cannot use a standby replica to serve read traffic. To service read-only traffic, you should use a Read Replica. For more information, see Working with Read Replicas of MariaDB, MySQL, and PostgreSQL DB Instances (p. 139). Using the RDS console, you can create a Multi-AZ deployment by simply specifying Multi-AZ when creating a DB instance. You can also use the console to convert existing DB instances to Multi-AZ deployments by modifying the DB instance and specifying the Multi-AZ option. The RDS console shows the Availability Zone of the standby replica, called the secondary AZ. You can specify a Multi-AZ deployment using the CLI as well. Use the AWS CLI describe-db-instances command, or the Amazon RDS API DescribeDBInstances action to show the Availability Zone of the standby replica (called the secondary AZ). The RDS console shows the Availability Zone of the standby replica (called the secondary AZ), or you can use the AWS CLI describe-db-instances command, or the Amazon RDS API DescribeDBInstances action to find the secondary AZ. DB instances using Multi-AZ deployments may have increased write and commit latency compared to a Single-AZ deployment, due to the synchronous data replication that occurs. You may have a change in latency if your deployment fails over to the standby replica, although AWS is engineered with lowlatency network connectivity between Availability Zones. For production workloads, we recommend that you use Provisioned IOPS and DB instance classes (m1.large and larger) that are optimized for Provisioned IOPS for fast, consistent performance. API Version 2014-10-31 107 Amazon Relational Database Service User Guide Modifying a DB Instance to be a Multi-AZ Deployment Modifying a DB Instance to Be a Multi-AZ Deployment If you have a DB instance in a Single-AZ deployment and you modify it to be a Multi-AZ deployment (for engines other than SQL Server or Amazon Aurora), Amazon RDS takes several steps. First, Amazon RDS takes a snapshot of the primary DB instance from your deployment and then restores the snapshot into another Availability Zone. Amazon RDS then sets up synchronous replication between your primary DB instance and the new instance. This action avoids downtime when you convert from Single-AZ to MultiAZ, but you can experience a significant performance impact when first converting to Multi-AZ. This impact is more noticeable for large and write-intensive DB instances. Once the modification is complete, Amazon RDS triggers an event (RDS-EVENT-0025) that indicates the process is complete. You can monitor Amazon RDS events; for more information about events, see Using Amazon RDS Event Notification (p. 278). Failover Process for Amazon RDS In the event of a planned or unplanned outage of your DB instance, Amazon RDS automatically switches to a standby replica in another Availability Zone if you have enabled Multi-AZ. The time it takes for the failover to complete depends on the database activity and other conditions at the time the primary DB instance became unavailable. Failover times are typically 60-120 seconds. However, large transactions or a lengthy recovery process can increase failover time. When the failover is complete, it can take additional time for the RDS console UI to reflect the new Availability Zone. The failover mechanism automatically changes the DNS record of the DB instance to point to the standby DB instance. As a result, you need to re-establish any existing connections to your DB instance. Due to how the Java DNS caching mechanism works, you may need to reconfigure your JVM environment. For more information on how to manage a Java application that caches DNS values in the case of a failover, see the AWS SDK for Java. Amazon RDS handles failovers automatically so you can resume database operations as quickly as possible without administrative intervention. The primary DB instance switches over automatically to the standby replica if any of the following conditions occur: • An Availability Zone outage • The primary DB instance fails • The DB instance's server type is changed • The operating system of the DB instance is undergoing software patching • A manual failover of the DB instance was initiated using Reboot with failover There are several ways to determine if your Multi-AZ DB instance has failed over: • DB event subscriptions can be setup to notify you via email or SMS that a failover has been initiated. For more information about events, see Using Amazon RDS Event Notification (p. 278) • You can view your DB events by using the Amazon RDS console or API actions. • You can view the current state of your Multi-AZ deployment by using the Amazon RDS console and API actions. For information on how you can respond to failovers, reduce recovery time, and other best practices for Amazon RDS, see Best Practices for Amazon RDS (p. 68). API Version 2014-10-31 108 Amazon Relational Database Service User Guide Related Topics Related Topics • Multi-AZ Deployments for Microsoft SQL Server (p. 541) • Licensing Oracle Multi-AZ Deployments (p. 713) API Version 2014-10-31 109 Amazon Relational Database Service User Guide DB Instance Lifecycle Amazon RDS DB Instance Lifecycle The lifecycle of an Amazon RDS DB instance includes creating, modifying, maintaining and upgrading, performing backups and restores, rebooting, and deleting the instance. This section provides information on and links to more about these processes. Topics • Creating an Amazon RDS DB Instance (p. 111) • Connecting to an Amazon RDS DB Instance (p. 112) • Modifying an Amazon RDS DB Instance and Using the Apply Immediately Parameter (p. 113) • Maintaining a DB Instance (p. 115) • Upgrading a DB Instance Engine Version (p. 121) • Renaming a DB Instance (p. 122) • Rebooting a DB Instance (p. 125) • Stopping an Amazon RDS DB Instance Temporarily (p. 127) • Starting an Amazon RDS DB Instance That Was Previously Stopped (p. 129) • Deleting a DB Instance (p. 131) API Version 2014-10-31 110 Amazon Relational Database Service User Guide Creating a DB Instance Creating an Amazon RDS DB Instance The basic building block of Amazon RDS is the DB instance. To create an Amazon RDS DB instance, follow the instructions for your specific database engine. • Creating a DB Instance Running the MariaDB Database Engine (p. 431) • Creating a DB Instance Running the Microsoft SQL Server Database Engine (p. 492) • Creating a DB Instance Running the MySQL Database Engine (p. 587) • Creating a DB Instance Running the Oracle Database Engine (p. 734) • Creating a DB Instance Running the PostgreSQL Database Engine (p. 964) API Version 2014-10-31 111 Amazon Relational Database Service User Guide Connecting to a DB Instance Connecting to an Amazon RDS DB Instance After you create an Amazon RDS DB instance, you can use any standard SQL client application to connect to the DB instance. To connect to an Amazon RDS DB instance, follow the instructions for your specific database engine. • Connecting to a DB Instance Running the MariaDB Database Engine (p. 440) • Connecting to a DB Instance Running the Microsoft SQL Server Database Engine (p. 503) • Connecting to a DB Instance Running the MySQL Database Engine (p. 596) • Connecting to a DB Instance Running the Oracle Database Engine (p. 743) • Connecting to a DB Instance Running the PostgreSQL Database Engine (p. 970) API Version 2014-10-31 112 Amazon Relational Database Service User Guide Modifying a DB Instance Modifying an Amazon RDS DB Instance and Using the Apply Immediately Parameter Most modifications to a DB instance can be applied immediately or deferred until the next maintenance window. Some modifications, such as parameter group changes, require that you manually reboot your DB instance for the change to take effect. Important Some modifications result in an outage because Amazon RDS must reboot your DB instance for the change to take effect. Review the impact to your database and applications before modifying your DB instance settings. To modify an Amazon RDS DB instance, follow the instructions for your specific database engine. • Modifying a DB Instance Running the MariaDB Database Engine (p. 443) • Modifying a DB Instance Running the Microsoft SQL Server Database Engine (p. 510) • Modifying a DB Instance Running the MySQL Database Engine (p. 600) • Modifying a DB Instance Running the Oracle Database Engine (p. 750) • Modifying a DB Instance Running the PostgreSQL Database Engine (p. 973) The Impact of Apply Immediately When you modify a DB instance, you can apply the changes immediately. To apply changes immediately, you select the Apply Immediately option in the AWS Management Console, you use the --applyimmediately parameter when calling the AWS CLI, or you set the ApplyImmediately parameter to true when using the Amazon RDS API. If you don't choose to apply changes immediately, the changes are put into the pending modifications queue. During the next maintenance window, any pending changes in the queue are applied. If you choose to apply changes immediately, your new changes and any changes in the pending modifications queue are applied. Important If any of the pending modifications require downtime, choosing apply immediately can cause unexpected downtime. Changes to some database settings are applied immediately, even if you choose to defer your changes. To see how the different database settings interact with the apply immediately setting, see the settings for your specific database engine. • Settings for MariaDB DB Instances (p. 444) • Settings for Microsoft SQL Server DB Instances (p. 511) • Settings for MySQL DB Instances (p. 601) • Settings for Oracle DB Instances (p. 751) • Settings for PostgreSQL DB Instances (p. 974) Related Topics • Renaming a DB Instance (p. 122) • Rebooting a DB Instance (p. 125) • Stopping an Amazon RDS DB Instance Temporarily (p. 127) • modify-db-instance API Version 2014-10-31 113 Amazon Relational Database Service User Guide Modifying a DB Instance • ModifyDBInstance API Version 2014-10-31 114 Amazon Relational Database Service User Guide Maintaining a DB Instance Maintaining a DB Instance Periodically, Amazon RDS performs maintenance on Amazon RDS resources. Maintenance most often involves updates to the DB instance's underlying operating system (OS) or database engine version. Updates to the operating system most often occur for security issues and should be done as soon as possible. Maintenance items require that Amazon RDS take your DB instance offline for a short time. Maintenance that require a resource to be offline include scale compute operations, which generally take only a few minutes from start to finish, and required operating system or database patching. Required patching is automatically scheduled only for patches that are related to security and instance reliability. Such patching occurs infrequently (typically once every few months) and seldom requires more than a fraction of your maintenance window. DB instances are not automatically backed up when an OS update is applied, so you should back up your DB instances before you apply an update. You can view whether a maintenance update is available for your DB instance by using the RDS console, the AWS CLI, or the Amazon RDS API. If an update is available, it is indicated by the word Available or Required in the Maintenance column for the DB instance on the Amazon RDS console, as shown following: If an update is available, you can take one of the actions. • Defer the maintenance items. • Apply the maintenance items immediately. • Schedule the maintenance items to start during your next maintenance window. • Take no action. Note Certain OS updates are marked as Required. If you defer a required update, you receive a notice from Amazon RDS indicating when the update will be performed. Other updates are marked as Available, and these you can defer indefinitely. The maintenance window determines when pending operations start, but does not limit the total execution time of these operations. Maintenance operations are not guaranteed to finish before the maintenance window ends, and can continue beyond the specified end time. For more information, see The Amazon RDS Maintenance Window (p. 118). API Version 2014-10-31 115 Amazon Relational Database Service User Guide Maintaining a DB Instance Applying Updates for a DB Instance With Amazon RDS, you can choose when to apply maintenance operations. You can decide when Amazon RDS applies updates by using the RDS console, AWS Command Line Interface (AWS CLI), or RDS API. AWS Management Console To manage an update for a DB instance 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Instances. 3. Select the check box for the DB instance that has a required update. 4. Choose Instance actions, and then choose one of the following: • Upgrade now • Upgrade at next window Note If you choose Upgrade at next window and later want to delay the update, you can select Defer upgrade. CLI To apply a pending update to a DB instance, use the apply-pending-maintenance-action AWS CLI command. Example For Linux, OS X, or Unix: aws rds apply-pending-maintenance-action \ --resource-identifier arn:aws:rds:us-west-2:001234567890:db:mysql-db \ --apply-action system-update \ --opt-in-type immediate For Windows: aws rds apply-pending-maintenance-action ^ --resource-identifier arn:aws:rds:us-west-2:001234567890:db:mysql-db ^ --apply-action system-update ^ --opt-in-type immediate To return a list of resources that have at least one pending update, use the describe-pendingmaintenance-actions AWS CLI command. Example For Linux, OS X, or Unix: aws rds describe-pending-maintenance-actions \ --resource-identifier arn:aws:rds:us-west-2:001234567890:db:mysql-db For Windows: API Version 2014-10-31 116 Amazon Relational Database Service User Guide Maintaining a DB Instance aws rds describe-pending-maintenance-actions ^ --resource-identifier arn:aws:rds:us-west-2:001234567890:db:mysql-db You can also return a list of resources for a DB instance by specifying the --filters parameter of the describe-pending-maintenance-actions AWS CLI command. The format for the --filters command is Name=filter-name,Value=resource-id,.... The following are the accepted values for the Name parameter of a filter: • db-instance-id – Accepts a list of DB instance identifiers or Amazon Resource Names (ARNs). The returned list only includes pending maintenance actions for the DB instances identified by these identifiers or ARNs. • db-cluster-id – Accepts a list of DB cluster identifiers or ARNs for Amazon Aurora. The returned list only includes pending maintenance actions for the DB clusters identified by these identifiers or ARNs. For example, the following example returns the pending maintenance actions for the sampleinstance1 and sample-instance2 DB instances. Example For Linux, OS X, or Unix: aws rds describe-pending-maintenance-actions \ --filters Name=db-instance-id,Values=sample-instance1,sample-instance2 For Windows: aws rds describe-pending-maintenance-actions ^ --filters Name=db-instance-id,Values=sample-instance1,sample-instance2 API To apply an update to a DB instance, call the Amazon RDS API ApplyPendingMaintenanceAction action. To return a list of resources that have at least one pending update, call the Amazon RDS API DescribePendingMaintenanceActions action. Maintenance for Multi-AZ Deployments Running a DB instance as a Multi-AZ deployment can further reduce the impact of a maintenance event, because Amazon RDS will apply operating system updates by following these steps: 1. Perform maintenance on the standby. 2. Promote the standby to primary. 3. Perform maintenance on the old primary, which becomes the new standby. When you modify the database engine for your DB instance in a Multi-AZ deployment, then Amazon RDS upgrades both the primary and secondary DB instances at the same time. In this case, the database engine for the entire Multi-AZ deployment is shut down during the upgrade. For more information on Multi-AZ deployments, see High Availability (Multi-AZ) for Amazon RDS (p. 107). API Version 2014-10-31 117 Amazon Relational Database Service User Guide Maintaining a DB Instance The Amazon RDS Maintenance Window Every DB instance has a weekly maintenance window during which any system changes are applied. You can think of the maintenance window as an opportunity to control when modifications and software patching occur, in the event either are requested or required. If a maintenance event is scheduled for a given week, it is initiated during the 30-minute maintenance window you identify. Most maintenance events also complete during the 30-minute maintenance window, although larger maintenance events may take more than 30 minutes to complete. The 30-minute maintenance window is selected at random from an 8-hour block of time per region. If you don't specify a preferred maintenance window when you create the DB instance, then Amazon RDS assigns a 30-minute maintenance window on a randomly selected day of the week. RDS will consume some of the resources on your DB instance while maintenance is being applied. You might observe a minimal effect on performance. For a DB instance, on rare occasions, a Multi-AZ failover might be required for a maintenance update to complete. Following, you can find the time blocks for each region from which default maintenance windows are assigned. Region Time Block US West (Oregon) Region 06:00–14:00 UTC US West (N. California) Region 06:00–14:00 UTC US East (Ohio) Region 03:00–11:00 UTC US East (N. Virginia) Region 03:00–11:00 UTC Asia Pacific (Mumbai) Region 17:30–01:30 UTC Asia Pacific (Seoul) Region 13:00–21:00 UTC Asia Pacific (Singapore) Region 14:00–22:00 UTC Asia Pacific (Sydney) Region 12:00–20:00 UTC Asia Pacific (Tokyo) Region 13:00–21:00 UTC Canada (Central) Region 03:00–11:00 UTC EU (Frankfurt) Region 23:00–07:00 UTC EU (Ireland) Region 22:00–06:00 UTC EU (London) Region 22:00–06:00 UTC South America (São Paulo) Region 00:00–08:00 UTC AWS GovCloud (US-West) 06:00–14:00 UTC Adjusting the Preferred DB Instance Maintenance Window The maintenance window should fall at the time of lowest usage and thus might need modification from time to time. Your DB instance will only be unavailable during this time if the system changes, such as a API Version 2014-10-31 118 Amazon Relational Database Service User Guide Maintaining a DB Instance scale storage operation or a change in DB instance class, are being applied and require an outage, and only for the minimum amount of time required to make the necessary changes. In the following example, you adjust the preferred maintenance window for a DB instance. For the purpose of this example, we assume that the DB instance named mydbinstance exists and has a preferred maintenance window of "Sun:05:00-Sun:06:00" UTC. AWS Management Console To adjust the preferred maintenance window 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Instances, and then select the DB instance that you want to modify. 3. Choose Instance actions, and then choose Modify. The Modify DB Instance page appears. 4. In the Maintenance section, update the maintenance window. Note The maintenance window and the backup window for the DB instance cannot overlap. If you enter a value for the maintenance window that overlaps the backup window, an error message appears. 5. Choose Continue. On the confirmation page, review your changes. 6. To apply the changes to the maintenance window immediately, select Apply immediately. 7. Choose Modify DB Instance to save your changes. Alternatively, choose Back to edit your changes, or choose Cancel to cancel your changes. CLI To adjust the preferred maintenance window, use the AWS CLI modify-db-instance command with the following parameters: • --db-instance-identifier • --preferred-maintenance-window Example The following code example sets the maintenance window to Tuesdays from 4:00-4:30AM UTC. For Linux, OS X, or Unix: aws rds modify-db-instance \ --db-instance-identifier mydbinstance \ --preferred-maintenance-window Tue:04:00-Tue:04:30 For Windows: aws rds modify-db-instance ^ --db-instance-identifier mydbinstance ^ --preferred-maintenance-window Tue:04:00-Tue:04:30 API Version 2014-10-31 119 Amazon Relational Database Service User Guide Maintaining a DB Instance API To adjust the preferred maintenance window, use the Amazon RDS API ModifyDBInstance action with the following parameters: • DBInstanceIdentifier = mydbinstance • PreferredMaintenanceWindow = Tue:04:00-Tue:04:30 Example The following code example sets the maintenance window to Tuesdays from 4:00-4:30AM UTC. https://rds.us-west-2.amazonaws.com/ ?Action=ModifyDBInstance &DBInstanceIdentifier=mydbinstance &PreferredMaintenanceWindow=Tue:04:00-Tue:04:30 &SignatureMethod=HmacSHA256 &SignatureVersion=4 &Version=2014-09-01 &X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIADQKE4SARGYLE/20140425/us-east-1/rds/aws4_request &X-Amz-Date=20140425T192732Z &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date &X-Amz-Signature=1dc9dd716f4855e9bdf188c70f1cf9f6251b070b68b81103b59ec70c3e7854b3 API Version 2014-10-31 120 Amazon Relational Database Service User Guide Upgrading a DB Instance Engine Version Upgrading a DB Instance Engine Version When Amazon RDS supports a new version of a database engine, you can upgrade your DB instances to the new version. There are two kinds of upgrades: major version upgrades and minor version upgrades. For more information about major and minor version upgrades, see the following documentation for your DB engine: • Upgrading the MariaDB DB Engine (p. 451) • Upgrading the Microsoft SQL Server DB Engine (p. 518) • Upgrading the MySQL DB Engine (p. 608) • Upgrading the Oracle DB Engine (p. 763) • Upgrading the PostgreSQL DB Engine (p. 982) Related Topics • Maintaining a DB Instance (p. 115) • Applying Updates for a DB Instance (p. 116) API Version 2014-10-31 121 Amazon Relational Database Service User Guide Renaming a DB Instance Renaming a DB Instance You can rename a DB instance by using the AWS Management Console, the AWS CLI modify-dbinstance command, or the Amazon RDS API ModifyDBInstance action. Renaming a DB instance can have far-reaching effects; the following is a list of things you should know before you rename a DB instance. • When you rename a DB instance, the endpoint for the DB instance changes, because the URL includes the name you assigned to the DB instance. You should always redirect traffic from the old URL to the new one. • When you rename a DB instance, the old DNS name that was used by the DB instance is immediately deleted, although it could remain cached for a few minutes. The new DNS name for the renamed DB instance becomes effective in about 10 minutes. The renamed DB instance is not available until the new name becomes effective. • You cannot use an existing DB instance name when renaming an instance. • All read replicas associated with a DB instance remain associated with that instance after it is renamed. For example, suppose you have a DB instance that serves your production database and the instance has several associated read replicas. If you rename the DB instance and then replace it in the production environment with a DB snapshot, the DB instance that you renamed will still have the read replicas associated with it. • Metrics and events associated with the name of a DB instance are maintained if you reuse a DB instance name. For example, if you promote a Read Replica and rename it to be the name of the previous master, the events and metrics associated with the master are associated with the renamed instance. • DB instance tags remain with the DB instance, regardless of renaming. • DB snapshots are retained for a renamed DB instance. Renaming to Replace an Existing DB Instance The most common reasons for renaming a DB instance are that you are promoting a Read Replica or you are restoring data from a DB snapshot or PITR. By renaming the database, you can replace the DB instance without having to change any application code that references the DB instance. In these cases, you would do the following: 1. Stop all traffic going to the master DB instance. This can involve redirecting traffic from accessing the databases on the DB instance or some other way you want to use to prevent traffic from accessing your databases on the DB instance. 2. Rename the master DB instance to a name that indicates it is no longer the master as described later in this topic. 3. Create a new master DB instance by restoring from a DB snapshot or by promoting a read replica, and then give the new instance the name of the previous master DB instance. 4. Associate any read replicas with the new master DB instance. If you delete the old master DB instance, you are responsible for deleting any unwanted DB snapshots of the old master instance. For information about promoting a Read Replica, see Promoting a Read Replica to Be a Standalone DB Instance (p. 142). API Version 2014-10-31 122 Amazon Relational Database Service User Guide Renaming a DB Instance AWS Management Console To rename a DB instance 1. 2. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. In the navigation pane, choose Instances. 3. 4. Select the DB instance you want to rename. Choose Instance actions, and then choose Modify. 5. In Settings, enter a new name in the DB instance identifier box. 6. Choose Continue. 7. To apply the changes immediately, select Apply immediately. Selecting this option can cause an outage in some cases. For more information, see The Impact of Apply Immediately (p. 113). 8. On the confirmation page, review your changes. If they are correct, choose Modify DB Instance to save your changes. Alternatively, choose Back to edit your changes, or choose Cancel to cancel your changes. CLI To rename a DB instance, use the AWS CLI command modify-db-instance. Provide the current --dbinstance-identifier value and --new-db-instance-identifier parameter with the new name of the DB instance. Example For Linux, OS X, or Unix: aws rds modify-db-instance \ --db-instance-identifier DBInstanceIdentifier \ --new-db-instance-identifier NewDBInstanceIdentifier For Windows: aws rds modify-db-instance ^ --db-instance-identifier DBInstanceIdentifier ^ --new-db-instance-identifier NewDBInstanceIdentifier API To rename a DB instance, call Amazon RDS API function ModifyDBInstance with the following parameters: • DBInstanceIdentifier = existing name for the instance • NewDBInstanceIdentifier = new name for the instance https://rds.amazonaws.com/ ?Action=ModifyDBInstance &DBInstanceIdentifier=mydbinstance &NewDBInstanceIdentifier=mynewdbinstanceidentifier &Version=2012-01-15 &SignatureVersion=2 &SignatureMethod=HmacSHA256 API Version 2014-10-31 123 Amazon Relational Database Service User Guide Renaming a DB Instance &Timestamp=2012-01-20T22%3A06%3A23.624Z &AWSAccessKeyId= &Signature= Related Topics • Modifying a DB Instance Running the MariaDB Database Engine (p. 443) • Modifying a DB Instance Running the Microsoft SQL Server Database Engine (p. 510) • Modifying a DB Instance Running the MySQL Database Engine (p. 600) • Modifying a DB Instance Running the Oracle Database Engine (p. 750) • Modifying a DB Instance Running the PostgreSQL Database Engine (p. 973) API Version 2014-10-31 124 Amazon Relational Database Service User Guide Rebooting a DB Instance Rebooting a DB Instance You might need to reboot your DB instance, usually for maintenance reasons. For example, if you make certain modifications, or if you change the DB parameter group associated with the DB instance , you must reboot the instance for the changes to take effect. Rebooting a DB instance restarts the database engine service. Rebooting a DB instance results in a momentary outage, during which the DB instance status is set to rebooting. If the Amazon RDS instance is configured for Multi-AZ, the reboot can be conducted with a failover. An Amazon RDS event is created when the reboot is completed. If your DB instance is a Multi-AZ deployment, you can force a failover from one availability zone to another when you reboot. When you force a failover of your DB instance, Amazon RDS automatically switches to a standby replica in another Availability Zone, and updates the DNS record for the DB instance to point to the standby DB instance. As a result, you need to clean up and re-establish any existing connections to your DB instance. Rebooting with failover is beneficial when you want to simulate a failure of a DB instance for testing, or restore operations to the original AZ after a failover occurs. For more information, see High Availability (MultiAZ) for Amazon RDS (p. 107). You can't reboot your DB instance if it is not in the "Available" state. Your database can be unavailable for several reasons, such as an in-progress backup, a previously requested modification, or a maintenancewindow action. The time required to reboot your DB instance depends on the crash recovery process of your specific database engine. To improve the reboot time, we recommend that you reduce database activity as much as possible during the reboot process. Reducing database activity reduces rollback activity for in-transit transactions. AWS Management Console To reboot a DB instance 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Instances, and then select the DB instance that you want to reboot. 3. Choose Instance actions and then choose Reboot. The Reboot DB Instance page appears. 4. (Optional) Select Reboot with failover? to force a failover from one AZ to another. 5. Choose Reboot to reboot your DB instance. Alternatively, choose Cancel. CLI To reboot a DB instance by using the AWS CLI, call the reboot-db-instance command. Example Simple Reboot For Linux, OS X, or Unix: aws rds reboot-db-instance \ --db-instance-identifier mydbinstance For Windows: API Version 2014-10-31 125 Amazon Relational Database Service User Guide Rebooting a DB Instance aws rds reboot-db-instance ^ --db-instance-identifier mydbinstance Example Reboot with Failover To force a failover from one AZ to the other, use the --force-failover parameter. For Linux, OS X, or Unix: aws rds reboot-db-instance \ --db-instance-identifier mydbinstance \ --force-failover For Windows: aws rds reboot-db-instance ^ --db-instance-identifier mydbinstance ^ --force-failover API To reboot a DB instance by using the Amazon RDS API, call the RebootDBInstance action. Example Simple Reboot https://rds.amazonaws.com/ ?Action=RebootDBInstance &DBInstanceIdentifier=mydbinstance &Version=2014-10-31 &X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIADQKE4SARGYLE/20131016/us-west-1/rds/aws4_request &X-Amz-Date=20131016T233051Z &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date &X-Amz-Signature=087a8eb41cb1ab5f99e81575f23e73757ffc6a1e42d7d2b30b9cc0be988cff97 Example Reboot with Failover To force a failover from one AZ to the other, set the ForceFailover parameter to true. https://rds.amazonaws.com/ ?Action=RebootDBInstance &DBInstanceIdentifier=mydbinstance &ForceFailover=true &Version=2014-10-31 &X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIADQKE4SARGYLE/20131016/us-west-1/rds/aws4_request &X-Amz-Date=20131016T233051Z &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date &X-Amz-Signature=087a8eb41cb1ab5f99e81575f23e73757ffc6a1e42d7d2b30b9cc0be988cff97 API Version 2014-10-31 126 Amazon Relational Database Service User Guide Stopping a DB Instance Stopping an Amazon RDS DB Instance Temporarily If you use a DB instance intermittently, for temporary testing, or for a daily development activity, you can stop your Amazon RDS DB instance temporarily to save money. While your DB instance is stopped, you are charged for provisioned storage (including Provisioned IOPS) and backup storage (including manual snapshots and automated backups within your specified retention window), but not for DB instance hours. For more information, see Billing FAQs. You can stop and start DB instances that are running the following engines: • MariaDB • Microsoft SQL Server • MySQL • Oracle • PostgreSQL Stopping and starting a DB instance is supported for all DB instance classes, and in all AWS Regions. You can stop and start a DB instance whether it is configured as single availability zone or multiavailability zone, for database engines that support Multi-AZ deployments. You can't stop an Amazon RDS for SQL Server DB instance in a Multi-AZ configuration. When you stop a DB instance, the DB instance performs a normal shutdown and stops running. The status of the DB instance changes to stopping and then stopped. Any storage volumes remain attached to the DB instance, and their data is kept. Any data stored in the RAM of the DB instance is deleted. You can stop a DB instance for up to seven days. If you do not manually start your DB instance after seven days, your DB instance is automatically started. Benefits Stopping and starting a DB instance is faster than creating a DB snapshot, and then restoring the snapshot. When you stop a DB instance it retains its ID, Domain Name Server (DNS) endpoint, parameter group, security group, and option group. When you start a DB instance, it has the same configuration as when you stopped it. In addition, if you stop a DB instance, Amazon RDS retains the Amazon Simple Storage Service (Amazon S3) transaction logs so you can do a point-in-time restore if necessary. Limitations The following are some limitations to stopping and starting a DB instance: • You can't stop a DB instance that has a Read Replica, or that is a Read Replica. • • • • You can't stop an Amazon RDS for SQL Server DB instance in a Multi-AZ configuration. You can't modify a stopped DB instance. You can't delete an option group that is associated with a stopped DB instance. You can't delete a DB parameter group that is associated with a stopped DB instance. Option and Parameter Group Considerations You can't remove persistent options (including permanent options) from an option group if there are DB instances associated with that option group. This functionality is also true of any DB instance with a state of stopping, stopped, or starting. API Version 2014-10-31 127 Amazon Relational Database Service User Guide Stopping a DB Instance You can change the option group or DB parameter group that is associated with a stopped DB instance, but the change does not occur until the next time you start the DB instance. If you chose to apply changes immediately, the change occurs when you start the DB instance. Otherwise the changes occurs during the next maintenance window after you start the DB instance. VPC Considerations When you stop a DB instance it retains its DNS endpoint. If you stop a DB instance that is not in an Amazon Virtual Private Cloud (Amazon VPC), Amazon RDS releases the IP addresses of the DB instance. If you stop a DB instance that is in a VPC, the DB instance retains its IP addresses. Note You should always connect to a DB instance using the DNS endpoint, not the IP address. AWS Management Console To stop a DB instance 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Instances, and then select the DB instance that you want to stop. 3. Choose Instance actions, and then choose Stop. 4. (Optional) In the Stop DB Instance window, choose Yes for Create Snapshot? and type the snapshot name in the Snapshot name box. Choose Yes if you want to create a snapshot of the DB instance before stopping it. 5. Choose Yes, Stop Now to stop the DB instance, or choose Cancel to cancel the operation. CLI To stop a DB instance by using the AWS CLI, call the stop-db-instance command with the following parameters: • --db-instance-identifier – the name of the DB instance. Example stop-db-instance --db-instance-identifier mydbinstance API To stop a DB instance by using the Amazon RDS API, call the StopDBInstance action with the following parameter: • DBInstanceIdentifier – the name of the DB instance. Related Topics • Starting an Amazon RDS DB Instance That Was Previously Stopped (p. 129) • Deleting a DB Instance (p. 131) • Rebooting a DB Instance (p. 125) API Version 2014-10-31 128 Amazon Relational Database Service User Guide Starting a DB Instance Starting an Amazon RDS DB Instance That Was Previously Stopped You can stop your Amazon RDS DB instance temporarily to save money. After you stop your DB instance, you can restart it to begin using it again. For more details about stopping and starting DB instances, see Stopping an Amazon RDS DB Instance Temporarily (p. 127). When you start a DB instance that you previously stopped, the DB instance retains the ID, Domain Name Server (DNS) endpoint, parameter group, security group, and option group. When you start a stopped instance, you are charged a full instance hour. AWS Management Console To start a DB instance 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Instances, and then select the DB instance that you want to start. 3. Choose Instance actions, and then choose Start. CLI To start a DB instance by using the AWS CLI, call the start-db-instance command with the following parameters: • --db-instance-identifier – the name of the DB instance. Example start-db-instance --db-instance-identifier mydbinstance API To start a DB instance by using the Amazon RDS API, call the StartDBInstance action with the following parameters: • DBInstanceIdentifier – the name of the DB instance. Example https://rds.amazonaws.com/ ?Action=StartDBInstance &DBInstanceIdentifier=mydbinstance &SignatureMethod=HmacSHA256 &SignatureVersion=4 &Version=2014-10-31 &X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIADQKE4SARGYLE/20131016/us-west-1/rds/aws4_request &X-Amz-Date=20131016T233051Z &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date &X-Amz-Signature=087a8eb41cb1ab5f99e81575f23e73757ffc6a1e42d7d2b30b9cc0be988cff97 API Version 2014-10-31 129 Amazon Relational Database Service User Guide Starting a DB Instance Related Topics • Deleting a DB Instance (p. 131) • Rebooting a DB Instance (p. 125) API Version 2014-10-31 130 Amazon Relational Database Service User Guide Deleting a DB Instance Deleting a DB Instance To delete a DB instance, you must do the following: • Provide the name of the instance • Enable or disable the option to take a final DB snapshot of the instance • Enable or disable the option to retain automated backups You can only delete instances that don't have deletion protection enabled. When you create or modify a DB instance, you have the option to enable deletion protection so that users can't delete the DB instance. Deletion protection is disabled by default for you when you use AWS CLI and API commands. Deletion protection is enabled for you when you use the AWS Management Console to create a production DB instance. However, Amazon RDS enforces deletion protection when you use the console, the CLI, or the API to delete a DB instance. To delete a DB instance that has deletion protection enabled, first modify the instance and disable deletion protection. If the DB instance that you want to delete has a Read Replica, you should either promote the Read Replica or delete it. For more information, see Promoting a Read Replica to Be a Standalone DB Instance (p. 142). Creating a Final Snapshot and Retaining Automated Backups When you delete a DB instance, you can choose whether to create a final snapshot of the DB instance. You can also choose to retain automated backups after the DB instance is deleted. To be able to restore the DB instance at a later time, create a final snapshot or retain automated backups. How to choose With Final Snapshot Without Final Snapshot To be able to restore your deleted DB instance at a later time, create a final DB snapshot. To delete a DB instance quickly, you Instead of creating can skip creating a final DB snapshot. a snapshot, you can choose to enable Important Retain automated If you skip the snapshot, to backups when you restore your DB instance you delete a DB instance. need one of the following: These backups are still subject to the • You have to use an earlier manual retention period of the snapshot of the DB instance to DB instance and age out restore the DB instance to that the same way systems snapshot's point in time. snapshots do. • You have to choose to retain automated backups; you can use those to restore it to any point in time within your retention period. Automated All automated backups backups are deleted and can't be recovered, unless you enable Retain automated backups. All automated backups are deleted and can't be recovered, unless you choose to retain automated backups when you delete the DB instance. API Version 2014-10-31 131 Retain Automated Backups Automated backups are retained for a set period of time, regardless of whether you chose to create a final snapshot. They are retained for retention period that was set on the DB instance at the time you deleted it. Amazon Relational Database Service User Guide Deleting a DB Instance Manual snapshots With Final Snapshot Without Final Snapshot Retain Automated Backups Earlier manual snapshots aren't deleted. Earlier manual snapshots aren't deleted. No snapshots are deleted. You can't create a final snapshot of your DB instance if it has the status creating, failed, incompatible-restore, or incompatible-network. For more information about DB instance statuses, see DB Instance Status (p. 96). Deleting a DB Instance by Using the Console, CLI, and API You can delete a DB instance using the AWS Management Console, the AWS CLI, or the RDS API. Console To delete a DB instance 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Instances, and then choose the DB instance that you want to delete. 3. 4. Choose Instance actions, and then choose Delete. For Create final Snapshot?, choose Yes or No. 5. If you chose Yes in the previous step, for Final snapshot name enter the name of your final DB snapshot. 6. 7. To retain automated backups, choose Retain automated backups. Enter delete me in the box. 8. Choose Delete. AWS CLI To delete a DB instance by using the AWS CLI, call the delete-db-instance command with the following options: • --db-instance-identifier • --final-db-snapshot-identifier or --skip-final-snapshot Example With a final snapshot and no retained automated backups For Linux, OS X, or Unix: aws rds delete-db-instance \ --db-instance-identifier mydbinstance \ --final-db-snapshot-identifier mydbinstancefinalsnapshot \ --delete-automated-backups For Windows: aws rds delete-db-instance ^ --db-instance-identifier mydbinstance ^ --final-db-snapshot-identifier mydbinstancefinalsnapshot ^ --delete-automated-backups API Version 2014-10-31 132 Amazon Relational Database Service User Guide Deleting a DB Instance Example With retained automated backups and no final snapshot For Linux, OS X, or Unix: aws rds delete-db-instance \ --db-instance-identifier mydbinstance \ --skip-final-snapshot \ --no-delete-automated-backups For Windows: aws rds delete-db-instance ^ --db-instance-identifier mydbinstance ^ --skip-final-snapshot ^ --no-delete-automated-backups RDS API To delete a DB instance by using the Amazon RDS API, call the DeleteDBInstance action with the following parameters: • DBInstanceIdentifier • FinalDBSnapshotIdentifier or SkipFinalSnapshot Example With a final snapshot and no retained automated backups https://rds.amazonaws.com/ ?Action=DeleteDBInstance &DBInstanceIdentifier=mydbinstance &FinalDBSnapshotIdentifier=mydbinstancefinalsnapshot &DeleteAutomatedBackups=true &SignatureMethod=HmacSHA256 &SignatureVersion=4 &Version=2014-10-31 &X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIADQKE4SARGYLE/20140305/us-west-1/rds/aws4_request &X-Amz-Date=20140305T185838Z &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date &X-Amz-Signature=b441901545441d3c7a48f63b5b1522c5b2b37c137500c93c45e209d4b3a064a3 Example With retained automated backups and no final snapshot https://rds.amazonaws.com/ ?Action=DeleteDBInstance &DBInstanceIdentifier=mydbinstance &SkipFinalSnapshot=true &DeleteAutomatedBackups=false &SignatureMethod=HmacSHA256 &SignatureVersion=4 &Version=2014-10-31 &X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIADQKE4SARGYLE/20140305/us-west-1/rds/aws4_request &X-Amz-Date=20140305T185838Z &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date &X-Amz-Signature=b441901545441d3c7a48f63b5b1522c5b2b37c137500c93c45e209d4b3a064a3 API Version 2014-10-31 133 Amazon Relational Database Service User Guide Tagging RDS Resources Tagging Amazon RDS Resources You can use Amazon RDS tags to add metadata to your Amazon RDS resources. In addition, these tags can be used with IAM policies to manage access to Amazon RDS resources and to control what actions can be applied to the Amazon RDS resources. Finally, these tags can be used to track costs by grouping expenses for similarly tagged resources. All Amazon RDS resources can be tagged • DB instances • DB clusters • Read Replicas • DB snapshots • DB cluster snapshots • Reserved DB instances • Event subscriptions • DB option groups • DB parameter groups • DB cluster parameter groups • DB security groups • DB subnet groups For information on managing access to tagged resources with IAM policies, see Authentication and Access Control (p. 330). Overview of Amazon RDS Resource Tags An Amazon RDS tag is a name-value pair that you define and associate with an Amazon RDS resource. The name is referred to as the key. Supplying a value for the key is optional. You can use tags to assign arbitrary information to an Amazon RDS resource. You can use a tag key, for example, to define a category, and the tag value might be an item in that category. For example, you might define a tag key of “project” and a tag value of “Salix,” indicating that the Amazon RDS resource is assigned to the Salix project. You can also use tags to designate Amazon RDS resources as being used for test or production by using a key such as environment=test or environment=production. We recommend that you use a consistent set of tag keys to make it easier to track metadata associated with Amazon RDS resources. Use tags to organize your AWS bill to reflect your own cost structure. To do this, sign up to get your AWS account bill with tag key values included. Then, to see the cost of combined resources, organize your billing information according to resources with the same tag key values. For example, you can tag several resources with a specific application name, and then organize your billing information to see the total cost of that application across several services. For more information, see Cost Allocation and Tagging in About AWS Billing and Cost Management. Each Amazon RDS resource has a tag set, which contains all the tags that are assigned to that Amazon RDS resource. A tag set can contain as many as 10 tags, or it can be empty. If you add a tag to an Amazon RDS resource that has the same key as an existing tag on resource, the new value overwrites the old value. AWS does not apply any semantic meaning to your tags; tags are interpreted strictly as character strings. Amazon RDS can set tags on a DB instance or other Amazon RDS resources, depending on the settings that you use when you create the resource. For example, Amazon RDS might add a tag indicating that a DB instance is for production or for testing. API Version 2014-10-31 134 Amazon Relational Database Service User Guide AWS Management Console • The tag key is the required name of the tag. The string value can be from 1 to 128 Unicode characters in length and cannot be prefixed with "aws:" or "rds:". The string can contain only the set of Unicode letters, digits, white-space, '_', '.', '/', '=', '+', '-' (Java regex: "^([\\p{L}\\p{Z}\\p{N}_.:/=+\\-]*)$"). • The tag value is an optional string value of the tag. The string value can be from 1 to 256 Unicode characters in length and cannot be prefixed with "aws:". The string can contain only the set of Unicode letters, digits, white-space, '_', '.', '/', '=', '+', '-' (Java regex: "^([\\p{L}\\p{Z}\\p{N}_.:/=+\\-]*)$"). Values do not have to be unique in a tag set and can be null. For example, you can have a key-value pair in a tag set of project/Trinity and cost-center/Trinity. Note You can add a tag to a snapshot, however, your bill will not reflect this grouping. You can use the AWS Management Console, the command line interface, or the Amazon RDS API to add, list, and delete tags on Amazon RDS resources. When using the command line interface or the Amazon RDS API, you must provide the Amazon Resource Name (ARN) for the Amazon RDS resource you want to work with. For more information about constructing an ARN, see Constructing an ARN for Amazon RDS (p. 177). Tags are cached for authorization purposes. Because of this, additions and updates to tags on Amazon RDS resources can take several minutes before they are available. Copying Tags When you create or restore a DB instance, you can specify that the tags from the DB instance are copied to snapshots of the DB instance. Copying tags ensures that the metadata for the DB snapshots matches that of the source DB instance and any access policies for the DB snapshot also match those of the source DB instance. Tags are not copied by default. You can specify that tags are copied to DB snapshots for the following actions: • Creating a DB instance. • Restoring a DB instance. • Creating a Read Replica. • Copying a DB snapshot. Note If you include a value for the --tag-key parameter of the create-db-snapshot AWS CLI command (or supply at least one tag to the CreateDBSnapshot API action) then RDS doesn't copy tags from the source DB instance to the new DB snapshot. This functionality applies even if the source DB instance has the --copy-tags-to-snapshot (CopyTagsToSnapshot) option enabled. If you take this approach, you can create a copy of a DB instance from a DB snapshot and avoid adding tags that don't apply to the new DB instance. Once you have created your DB snapshot using the AWS CLI create-db-snapshot command (or the CreateDBSnapshot Amazon RDS API action) you can then add tags as described later in this topic. AWS Management Console The process to tag an Amazon RDS resource is similar for all resources. The following procedure shows how to tag an Amazon RDS DB instance. API Version 2014-10-31 135 Amazon Relational Database Service User Guide AWS Management Console To add a tag to a DB instance 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Instances. Note To filter the list of DB instances in the Instances pane, type a text string in the Filter instances box. Only DB instances that contain the string appear. 3. Click on the name of the DB instance that you want to tag to show its details. 4. In the details section, scroll down to the Tags section. 5. Choose Add. The Add tags window appears. 6. Type a value for Tag key and Value. 7. To add another tag, you can choose Add another Tag and type a value for its Tag key and Value. Repeat this step as many times as necessary. 8. Choose Add. To delete a tag from a DB instance 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Instances. Note To filter the list of DB instances in the Instances pane, type a text string in the Filter instances box. Only DB instances that contain the string appear. 3. Click on the name of the DB instance to show its details. 4. In the details section, scroll down to the Tags section. 5. Choose the tag you want to delete. API Version 2014-10-31 136 Amazon Relational Database Service User Guide CLI 6. Choose Delete, and then choose Delete in the Delete tags window. CLI You can add, list, or remove tags for a DB instance using the AWS CLI. • To add one or more tags to an Amazon RDS resource, use the AWS CLI command add-tags-toresource. • To list the tags on an Amazon RDS resource, use the AWS CLI command list-tags-for-resource. • To remove one or more tags from an Amazon RDS resource, use the AWS CLI command removetags-from-resource. To learn more about how to construct the required ARN, see Constructing an ARN for Amazon RDS (p. 177). API You can add, list, or remove tags for a DB instance using the Amazon RDS API. • To add a tag to an Amazon RDS resource, use the AddTagsToResource operation. • To list tags that are assigned to an Amazon RDS resource, use the ListTagsForResource. • To remove tags from an Amazon RDS resource, use the RemoveTagsFromResource operation. To learn more about how to construct the required ARN, see Constructing an ARN for Amazon RDS (p. 177). When working with XML using the Amazon RDS API, tags use the following schema: Project Trinity User Jones The following table provides a list of the allowed XML tags and their characteristics. Values for Key and Value are case-dependent. For example, project=Trinity and PROJECT=Trinity are two distinct tags. API Version 2014-10-31 137 Amazon Relational Database Service User Guide Related Topics Tagging Element Description TagSet A tag set is a container for all tags assigned to an Amazon RDS resource. There can be only one tag set per resource. You work with a TagSet only through the Amazon RDS API. Tag A tag is a user-defined key-value pair. There can be from 1 to 50 tags in a tag set. Key A key is the required name of the tag. The string value can be from 1 to 128 Unicode characters in length and cannot be prefixed with "rds:" or "aws:". The string can only contain only the set of Unicode letters, digits, whitespace, '_', '.', '/', '=', '+', '-' (Java regex: "^([\\p{L}\\p{Z}\\p{N}_.:/=+\\-]*)$"). Keys must be unique to a tag set. For example, you cannot have a key-pair in a tag set with the key the same but with different values, such as project/ Trinity and project/Xanadu. Value A value is the optional value of the tag. The string value can be from 1 to 256 Unicode characters in length and cannot be prefixed with "rds:" or "aws:". The string can only contain only the set of Unicode letters, digits, white-space, '_', '.', '/', '=', '+', '-' (Java regex: "^([\\p{L}\\p{Z}\\p{N}_.:/=+\ \-]*)$"). Values do not have to be unique in a tag set and can be null. For example, you can have a key-value pair in a tag set of project/Trinity and cost-center/ Trinity. Related Topics • Authentication and Access Control (p. 330) API Version 2014-10-31 138 Amazon Relational Database Service User Guide Working with Read Replicas Working with Read Replicas of MariaDB, MySQL, and PostgreSQL DB Instances Amazon RDS uses the MariaDB, MySQL, and PostgreSQL DB engines' built-in replication functionality to create a special type of DB instance called a Read Replica from a source DB instance. Updates made to the source DB instance are asynchronously copied to the Read Replica. You can reduce the load on your source DB instance by routing read queries from your applications to the Read Replica. Using Read Replicas, you can elastically scale out beyond the capacity constraints of a single DB instance for readheavy database workloads. Note The information following applies to creating Amazon RDS Read Replicas either in the same AWS Region as the source DB instance, or in a separate AWS Region. The information following doesn't apply to setting up replication with an instance that is running on an Amazon EC2 instance or that is on-premises. When you create a Read Replica, you first specify an existing DB instance as the source. Then Amazon RDS takes a snapshot of the source instance and creates a read-only instance from the snapshot. Amazon RDS then uses the asynchronous replication method for the DB engine to update the Read Replica whenever there is a change to the source DB instance. The Read Replica operates as a DB instance that allows only read-only connections. Applications connect to a Read Replica the same way they do to any DB instance. Amazon RDS replicates all databases in the source DB instance. Amazon RDS sets up a secure communications channel between the source DB instance and a Read Replica if that Read Replica is in a different AWS Region from the DB instance. Amazon RDS establishes any AWS security configurations needed to enable the secure channel, such as adding security group entries. Read Replicas are supported by the MariaDB, MySQL, and PostgreSQL engines. This section provides general information about using Read Replicas with all three of these engines. For information about using Read Replicas with a specific engine, see the following sections: • Working with MySQL Read Replicas (p. 650) • Working with MariaDB Read Replicas (p. 458) • Working with PostgreSQL Read Replicas (p. 987) Overview of Amazon RDS Read Replicas Deploying one or more Read Replicas for a given source DB instance might make sense in a variety of scenarios, including the following: • Scaling beyond the compute or I/O capacity of a single DB instance for read-heavy database workloads. You can direct this excess read traffic to one or more Read Replicas. • Serving read traffic while the source DB instance is unavailable. If your source DB instance can't take I/ O requests (for example, due to I/O suspension for backups or scheduled maintenance), you can direct read traffic to your Read Replicas. For this use case, keep in mind that the data on the Read Replica might be "stale" because the source DB instance is unavailable. • Business reporting or data warehousing scenarios where you might want business reporting queries to run against a Read Replica, rather than your primary, production DB instance. • Implementing disaster recovery. You can use promote a Read Replica to a standalone instances as a disaster recovery solution if the source DB instance fails. API Version 2014-10-31 139 Amazon Relational Database Service User Guide Overview By default, a Read Replica is created with the same storage type as the source DB instance. However, you can create a Read Replica that has a different storage type from the source DB instance based on the options listed in the following table. Source DB Instance Storage Type Source DB Instance Storage Allocation Read Replica Storage Type Options PIOPS 100 GiB – 32 TiB PIOPS, GP2, Standard GP2 100 GiB – 32 TiB PIOPS, GP2, Standard GP2 Less than 100 GiB GP2, Standard Standard 100 GiB – 32 TiB PIOPS, GP2, Standard Standard Less than 100 GiB GP2, Standard Amazon RDS doesn't support circular replication. You can't configure a DB instance to serve as a replication source for an existing DB instance; you can only create a new Read Replica from an existing DB instance. For example, if MyDBInstance replicates to ReadReplica1, you can't configure ReadReplica1 to replicate back to MyDBInstance. From ReadReplica1, you can only create a new Read Replica, such as ReadReplica2. Differences Between PostgreSQL and MySQL or MariaDB Read Replicas Because the PostgreSQL DB engine implements replication differently than the MySQL and MariaDB DB engines, there are several significant differences you should know about, as shown in the following table. Feature or Behavior PostgreSQL MySQL and MariaDB What is the replication method? Physical replication. Logical replication. How are transaction logs purged? PostgreSQL has a parameter, wal_keep_segments, that dictates how many write ahead log (WAL) files are kept to provide data to the Read Replicas. The parameter value specifies the number of logs to keep. Amazon RDS keeps any binary logs that haven't been applied. Can a replica be made writable? No. A PostgreSQL Read Replica is Yes. You can enable the MySQL or a physical copy, and PostgreSQL MariaDB Read Replica to be writable. doesn't allow for a Read Replica to be made writable. Can backups be performed on the replica? Yes, you can create a manual snapshot of a PostgreSQL Read Replica, but you can't enable automatic backups. Yes. You can enable automatic backups on a MySQL or MariaDB Read Replica. Can you use parallel replication? No. PostgreSQL has a single process handling replication. Yes. MySQL version 5.6 and later and all supported MariaDB versions allow for parallel replication threads. API Version 2014-10-31 140 Amazon Relational Database Service User Guide Creating a Read Replica Creating a Read Replica You can create a Read Replica from an existing MySQL, MariaDB, or PostgreSQL DB instance using the AWS Management Console, AWS CLI, or AWS API. You create a Read Replica by specifying the SourceDBInstanceIdentifier, which is the DB instance identifier of the source DB instance from which you wish to replicate. When you create a Read Replica, Amazon RDS takes a DB snapshot of your source DB instance and begins replication. As a result, you experience a brief I/O suspension on your source DB instance while the DB snapshot occurs. The I/O suspension typically lasts about one minute. You can avoid the I/O suspension if the source DB instance is a Multi-AZ deployment, because in that case the snapshot is taken from the secondary DB instance. An active, long-running transaction can slow the process of creating the Read Replica. We recommend that you wait for long-running transactions to complete before creating a Read Replica. If you create multiple Read Replicas in parallel from the same source DB instance, Amazon RDS takes only one snapshot at the start of the first create action. When creating a Read Replica, there are a few things to consider. First, you must enable automatic backups on the source DB instance by setting the backup retention period to a value other than 0. This requirement also applies to a Read Replica that is the source DB instance for another Read Replica. For MySQL DB instances, automatic backups are supported only for Read Replicas running MySQL 5.6 and later, but not for MySQL versions 5.5. To enable automatic backups on an Amazon RDS MySQL version 5.6 and later Read Replica, first create the Read Replica, then modify the Read Replica to enable automatic backups. AWS Management Console To create a Read Replica from a source MySQL, MariaDB, or PostgreSQL DB instance 1. 2. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. In the navigation pane, choose Instances. 3. In the Instances pane, select the MySQL, MariaDB, or PostgreSQL DB instance that you want to use as the source for a Read Replica. 4. 5. For Instance actions, choose Create read replica. Choose the instance specifications you want to use. We recommend that you use the same DB instance class and storage type as the source DB instance for the Read Replica. For Multi-AZ deployment, choose Yes to create a standby of your replica in another Availability Zone for failover support for the replica. Creating your Read Replica as a Multi-AZ DB instance is independent of whether the source database is a Multi-AZ DB instance. 6. Choose the settings you want to use. For DB instance identifier, type a name for the Read Replica. Adjust other settings as needed. 7. 8. Choose the other settings you want to use. Choose Create read replica. CLI To create a Read Replica from a source MySQL, MariaDB, or PostgreSQL DB instance, use the AWS CLI command create-db-instance-read-replica. Example For Linux, OS X, or Unix: aws rds create-db-instance-read-replica \ API Version 2014-10-31 141 Amazon Relational Database Service User Guide Promoting a Read Replica --db-instance-identifier myreadreplica \ --source-db-instance-identifier mydbinstance For Windows: aws rds create-db-instance-read-replica ^ --db-instance-identifier myreadreplica ^ --source-db-instance-identifier mydbinstance API To create a Read Replica from a source MySQL, MariaDB, or PostgreSQL DB instance, call the Amazon RDS API function CreateDBInstanceReadReplica. https://rds.amazonaws.com/ ?Action=CreateDBInstanceReadReplica &DBInstanceIdentifier=myreadreplica &SourceDBInstanceIdentifier=mydbinstance &Version=2012-01-15 &SignatureVersion=2 &SignatureMethod=HmacSHA256 &Timestamp=2012-01-20T22%3A06%3A23.624Z &AWSAccessKeyId= &Signature= Promoting a Read Replica to Be a Standalone DB Instance You can promote a MySQL, MariaDB, or PostgreSQL Read Replica into a standalone DB instance. When you promote a Read Replica, the DB instance is rebooted before it becomes available. There are several reasons you might want to promote a Read Replica to a standalone DB instance: • Performing DDL operations (MySQL and MariaDB only) – DDL operations, such as creating or rebuilding indexes, can take time and impose a significant performance penalty on your DB instance. You can perform these operations on a MySQL or MariaDB Read Replica once the Read Replica is in sync with its source DB instance. Then you can promote the Read Replica and direct your applications to use the promoted instance. • Sharding – Sharding embodies the "share-nothing" architecture and essentially involves breaking a large database into several smaller databases. One common way to split a database is splitting tables that are not joined in the same query onto different hosts. Another method is duplicating a table across multiple hosts and then using a hashing algorithm to determine which host receives a given update. You can create Read Replicas corresponding to each of your shards (smaller databases) and promote them when you decide to convert them into standalone shards. You can then carve out the key space (if you are splitting rows) or distribution of tables for each of the shards depending on your requirements. • Implementing failure recovery – You can use Read Replica promotion as a data recovery scheme if the source DB instance fails. This approach complements synchronous replication, automatic failure detection, and failover. If you are aware of the ramifications and limitations of asynchronous replication and you still want to use Read Replica promotion for data recovery, you can do so. To do this, first create a Read Replica and then monitor the source DB instance for failures. In the event of a failure, do the following: 1. Promote the Read Replica. API Version 2014-10-31 142 Amazon Relational Database Service User Guide Promoting a Read Replica 2. Direct database traffic to the promoted DB instance. 3. Create a replacement Read Replica with the promoted DB instance as its source. When you promote a Read Replica, the new DB instance that is created retains the backup retention period, the backup window, and the parameter group of the former Read Replica source. The promotion process can take several minutes or longer to complete, depending on the size of the Read Replica. Once you promote the Read Replica to a new DB instance, it's just like any other DB instance. For example, you can convert the new DB instance into a Multi-AZ DB instance, create Read Replicas from it, and perform point-in-time restore operations. Because the promoted DB instance is no longer a Read Replica, you can't use it as a replication target. If a source DB instance has several Read Replicas, promoting one of the Read Replicas to a DB instance has no effect on the other replicas. Backup duration is a function of the amount of changes to the database since the previous backup. If you plan to promote a Read Replica to a standalone instance, we recommend that you enable backups and complete at least one backup prior to promotion. In addition, a Read Replica cannot be promoted to a standalone instance when it is in the backing-up status. If you have enabled backups on your Read Replica, configure the automated backup window so that daily backups do not interfere with Read Replica promotion. The following steps show the general process for promoting a Read Replica to a DB instance: 1. Stop any transactions from being written to the Read Replica source DB instance, and then wait for all updates to be made to the Read Replica. Database updates occur on the Read Replica after they have occurred on the source DB instance, and this replication lag can vary significantly. Use the Replica Lag metric to determine when all updates have been made to the Read Replica. 2. For MySQL and MariaDB only: If you need to make changes to the MySQL or MariaDB Read Replica, you must the set the read_only parameter to 0 in the DB parameter group for the Read Replica. You can then perform all needed DDL operations, such as creating indexes, on the Read Replica. Actions taken on the Read Replica don't affect the performance of the source DB instance. 3. Promote the Read Replica by using the Promote Read Replica option on the Amazon RDS console, the AWS CLI command promote-read-replica, or the PromoteReadReplica Amazon RDS API operation. Note The promotion process takes a few minutes to complete. When you promote a Read Replica, replication is stopped and the Read Replica is rebooted. When the reboot is complete, the Read Replica is available as a new DB instance. 4. (Optional) Modify the new DB instance to be a Multi-AZ deployment. For more information, see Modifying an Amazon RDS DB Instance and Using the Apply Immediately Parameter (p. 113) and High Availability (Multi-AZ) for Amazon RDS (p. 107). AWS Management Console To promote a Read Replica to a DB instance 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the Amazon RDS console, choose Instances. The Instance pane appears. Each Read Replica shows replica in the Replication role column. 3. In the Instances pane, select the Read Replica that you want to promote. 4. Choose Instance actions, and then choose Promote read replica. 5. On the Promote Read Replica page, enter the backup retention period and the backup window for the new promoted DB instance. API Version 2014-10-31 143 Amazon Relational Database Service User Guide Creating a Read Replica in a Different AWS Region 6. When the settings are as you want them, choose Continue. 7. On the acknowledgment page, choose Promote Read Replica. CLI To promote a Read Replica to a DB instance, use the AWS CLI promote-read-replica command. Example For Linux, OS X, or Unix: aws rds promote-read-replica \ --db-instance-identifier myreadreplica For Windows: aws rds promote-read-replica ^ --db-instance-identifier myreadreplica API To promote a Read Replica to a DB instance, call PromoteReadReplica. https://rds.amazonaws.com/ ?Action=PromoteReadReplica &DBInstanceIdentifier=myreadreplica &Version=2012-01-15 &SignatureVersion=2 &SignatureMethod=HmacSHA256 &Timestamp=2012-01-20T22%3A06%3A23.624Z &AWSAccessKeyId= &Signature= Creating a Read Replica in a Different AWS Region With Amazon RDS, you can create a MySQL, PostgreSQL, or MariaDB Read Replica in a different AWS Region than the source DB instance. You create a Read Replica to do the following: • Improve your disaster recovery capabilities. • Scale read operations into an AWS Region closer to your users. • Make it easier to migrate from a data center in one AWS Region to a data center in another AWS Region. Creating a MySQL, PostgreSQL, or MariaDB Read Replica in a different AWS Region than the source instance is similar to creating a replica in the same AWS Region. To create a Read Replica across regions, you can use the AWS Management Console, run the create-db-instance-read-replica command, or call the CreateDBInstanceReadReplica API action. To create an encrypted Read Replica in a different AWS Region than the source DB instance, the source DB instance must be encrypted. Following, you can find information on how to create a Read Replica from a source MySQL, MariaDB, or PostgreSQL DB instance in a different AWS Region. API Version 2014-10-31 144 Amazon Relational Database Service User Guide Creating a Read Replica in a Different AWS Region AWS Management Console You can create a Read Replica across regions using the AWS Management Console. To create a Read Replica across regions with the console 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Instances. 3. In the Instances pane, choose the MySQL, MariaDB, or PostgreSQL DB instance that you want to use as the source for a Read Replica, and then choose Create read replica from Instance actions. To create an encrypted Read Replica, the source DB instance must be encrypted. To learn more about encrypting the source DB instance, see Encrypting Amazon RDS Resources (p. 377). Choose the instance specifications you want to use. We recommend that you use the same DB instance class and storage type for the Read Replica. 4. 5. Choose the other settings you want to use: • For DB instance identifier, type a name for the Read Replica. 6. • In the Network & Security section, choose a value for Designation region and Designation DB subnet group. • To create an encrypted Read Replica in another AWS Region, choose Enable Encryption, and then choose the Master key. For the Master key, choose the KMS key identifier of the destination AWS Region. • Choose the other settings you want to use. Choose Create read replica. CLI To create a Read Replica from a source MySQL, MariaDB, or PostgreSQL DB instance in a different AWS Region, you can use the create-db-instance-read-replica command. In this case, you use create-db-instance-read-replica from the AWS Region where you want the Read Replica and specify the Amazon Resource Name (ARN) for the source DB instance. An ARN uniquely identifies a resource created in Amazon Web Services. For example, if your source DB instance is in the US East (N. Virginia) region, the ARN looks similar to the following. arn:aws:rds:us-east-1:123456789012:db:my-mysql-instance For information about ARNs, see Working with Amazon Resource Names (ARNs) in Amazon RDS (p. 177). To create an encrypted Read Replica in a different AWS Region than the source DB instance, you can use the AWS CLI create-db-instance-read-replica command from the destination AWS Region. The following parameters are used to create an encrypted Read Replica in another AWS Region: • --source-region — The AWS Region that the encrypted Read Replica is created in. If sourceregion is not specified, you must specify a pre-signed-url. A pre-signed-url is a URL that contains a Signature Version 4 signed request for the CreateDBInstanceReadReplica action that is called in the source AWS Region where the Read Replica is created from. To learn more about the presigned-url, see CreateDBInstanceReadReplica. • --source-db-instance-identifier — The DB instance identifier for the encrypted Read Replica that is created. This identifier must be in the ARN format for the source AWS Region. The AWS Region specified in source-db-instance-identifier must match the AWS Region specified as the source-region. API Version 2014-10-31 145 Amazon Relational Database Service User Guide Creating a Read Replica in a Different AWS Region • --db-instance-identifier — The identifier for the encrypted Read Replica in the destination AWS Region. • --kms-key-id — The AWS KMS key identifier for the key to use to encrypt the Read Replica in the destination AWS Region. The following code creates a Read Replica in the us-west-2 region. Example For Linux, OS X, or Unix: aws rds create-db-instance-read-replica \ --db-instance-identifier DBInstanceIdentifier \ --region us-west-2 \ --source-db-instance-identifier arn:aws:rds:us-east-1:123456789012:db:my-mysql-instance For Windows: aws rds create-db-instance-read-replica ^ --db-instance-identifier DBInstanceIdentifier ^ --region us-west-2 ^ --source-db-instance-identifier arn:aws:rds:us-east-1:123456789012:db:my-mysql-instance The following code creates a Read Replica in a different AWS Region than the source DB instance. The AWS Region where you call the create-db-instance-read-replica command is the destination AWS Region for the encrypted Read Replica. Example For Linux, OS X, or Unix: aws rds create-db-instance-read-replica \ --db-instance-identifier DBInstanceIdentifier \ --region us-west-2 \ --source-db-instance-identifier arn:aws:rds:us-east-1:123456789012:db:my-mysql-instance \ --source-region us-east-1 \ --kms-key-id my-us-east-1-key For Windows: aws rds create-db-instance-read-replica ^ --db-instance-identifier DBInstanceIdentifier ^ --region us-west-2 ^ --source-db-instance-identifier arn:aws:rds:us-east-1:123456789012:db:my-mysql-instance ^ --source-region us-east-1 ^ --kms-key-id my-us-east-1-key API To create a Read Replica from a source MySQL, MariaDB, or PostgreSQL DB instance in a different AWS Region, you can call the Amazon RDS API function CreateDBInstanceReadReplica. In this case, you call CreateDBInstanceReadReplica from the AWS Region where you want the Read Replica and specify the API Version 2014-10-31 146 Amazon Relational Database Service User Guide Creating a Read Replica in a Different AWS Region Amazon Resource Name (ARN) for the source DB instance. An ARN uniquely identifies a resource created in Amazon Web Services. To create an encrypted Read Replica in a different AWS Region than the source DB instance, you can use the Amazon RDS API CreateDBInstanceReadReplica action from the destination AWS Region. To create an encrypted Read Replica in another AWS Region, you must specify a value for PreSignedURL. PreSignedURL should contain a request for the CreateDBInstanceReadReplica action to call in the source AWS Region where the Read Replica is created in. To learn more about PreSignedUrl, see CreateDBInstanceReadReplica. For example, if your source DB instance is in the US East (N. Virginia) region, the ARN looks similar to the following. arn:aws:rds:us-east-1:123456789012:db:my-mysql-instance For information about ARNs, see Working with Amazon Resource Names (ARNs) in Amazon RDS (p. 177). Example https://us-west-2.rds.amazonaws.com/ ?Action=CreateDBInstanceReadReplica &KmsKeyId=my-us-east-1-key &PreSignedUrl=https%253A%252F%252Frds.us-west-2.amazonaws.com%252F %253FAction%253D CreateDBInstanceReadReplica %2526DestinationRegion%253Dus-east-1 %2526KmsKeyId%253Dmy-us-east-1-key %2526SourceDBInstanceIdentifier%253Darn%25253Aaws%25253Ards%25253Auswest-2%1234567890 12%25253Adb%25253Amy-mysql-instance %2526SignatureMethod%253DHmacSHA256 %2526SignatureVersion%253D4%2526SourceDBInstanceIdentifier%253Darn%25253Aaws %25253Ards%25253Aus-west-2%25253A123456789012%25253Ainstance%25253Amysql-instance1instance-20161115 %2526Version%253D2014-10-31 %2526X-Amz-Algorithm%253DAWS4-HMAC-SHA256 %2526X-Amz-Credential%253DAKIADQKE4SARGYLE%252F20161117%252Fus-west-2%252Frds %252Faws4_request %2526X-Amz-Date%253D20161117T215409Z %2526X-Amz-Expires%253D3600 %2526X-Amz-SignedHeaders%253Dcontent-type%253Bhost%253Buser-agent%253Bx-amzcontent-sha256%253Bx-amz-date %2526X-Amz-Signature %253D255a0f17b4e717d3b67fad163c3ec26573b882c03a65523522cf890a67fca613 &DBInstanceIdentifier=myreadreplica &SourceDBInstanceIdentifier=arn:aws:rds:us-east-1:123456789012:db:my-mysql-instance &Version=2012-01-15 &SignatureVersion=2 &SignatureMethod=HmacSHA256 &Timestamp=2012-01-20T22%3A06%3A23.624Z &AWSAccessKeyId= &Signature= Cross-Region Replication Considerations All of the considerations for performing replication within an AWS Region apply to cross-region replication. The following extra considerations apply when replicating between regions: • You can only replicate between regions when using Amazon RDS DB instances of MariaDB, PostgreSQL (versions 9.4.7 and 9.5.2 and later), or MySQL 5.6 and later. • A source DB instance can have cross-region Read Replicas in multiple regions. API Version 2014-10-31 147 Amazon Relational Database Service User Guide Creating a Read Replica in a Different AWS Region • You can only create a cross-region Amazon RDS Read Replica from a source Amazon RDS DB instance that is not a Read Replica of another Amazon RDS DB instance. • You can't set up a replication channel into or out of the AWS GovCloud (US-West) region. • You can expect to see a higher level of lag time for any Read Replica that is in a different AWS Region than the source instance, due to the longer network channels between regional data centers. • Within an AWS Region, all cross-region Read Replicas created from the same source DB instance must either be in the same Amazon VPC or be outside of a VPC. For cross-region Read Replicas, any of the create Read Replica commands that specify the --db-subnet-group-name parameter must specify a DB subnet group from the same VPC. • You can create a cross-region Read Replica in a VPC from a source DB instance that is in a VPC in another region. You can also create a cross-region Read Replica in a VPC from a source DB instance that is not in a VPC. You can also create a cross-region Read Replica that is not in a VPC from a source DB instance that is in a VPC. • Due to the limit on the number of access control list (ACL) entries for a VPC, we can't guarantee more than five cross-region Read Replica instances. Cross-Region Replication Costs The data transferred for cross-region replication incurs Amazon RDS data transfer charges. These crossregion replication actions generate charges for the data transferred out of the source AWS Region: • When you create a Read Replica, Amazon RDS takes a snapshot of the source instance and transfers the snapshot to the Read Replica region. • For each data modification made in the source databases, Amazon RDS transfers data from the source AWS Region to the Read Replica region. For more information about data transfer pricing, see Amazon RDS Pricing. For MySQL and MariaDB instances, you can reduce your data transfer costs by reducing the number of cross-region Read Replicas that you create. For example, suppose that you have a source DB instance in one AWS Region and want to have three Read Replicas in another AWS Region. In this case, you create only one of the Read Replicas from the source DB instance. You create the other two replicas from the first Read Replica instead of the source DB instance. For example, if you have source-instance-1 in one AWS Region, you can do the following: • Create read-replica-1 in the new AWS Region, specifying source-instance-1 as the source. • Create read-replica-2 from read-replica-1. • Create read-replica-3 from read-replica-1. In this example, you are only charged for the data transferred from source-instance-1 to readreplica-1. You are not charged for the data transferred from read-replica-1 to the other two replicas because they are all in the same AWS Region. If you create all three replicas directly from source-instance-1, you are charged for the data transfers to all three replicas. How Amazon RDS Does Cross-Region Replication Amazon RDS uses the following process to create a cross-region Read Replica. Depending on the regions involved and the amount of data in the databases, this process can take hours to complete. You can use this information to determine how far the process has proceeded when you create a cross-region Read Replica: 1. Amazon RDS begins configuring the source DB instance as a replication source and sets the status to modifying. API Version 2014-10-31 148 Amazon Relational Database Service User Guide Creating a Read Replica in a Different AWS Region 2. Amazon RDS begins setting up the specified Read Replica in the destination AWS Region and sets the status to creating. 3. Amazon RDS creates an automated DB snapshot of the source DB instance in the source AWS Region. The format of the DB snapshot name is rds:-, where is the identifier of the source instance, and is the date and time the copy started. For example, rds:mysourceinstance-2013-11-14-09-24 was created from the instance mysourceinstance at 2013-11-14-09-24. During the creation of an automated DB snapshot, the source DB instance status remains modifying, the Read Replica status remains creating, and the DB snapshot status is creating. The progress column of the DB snapshot page in the console reports how far the DB snapshot creation has progressed. When the DB snapshot is complete, the status of both the DB snapshot and source DB instance are set to available. 4. Amazon RDS begins a cross-region snapshot copy for the initial data transfer. The snapshot copy is listed as an automated snapshot in the destination AWS Region with a status of creating. It has the same name as the source DB snapshot. The progress column of the DB snapshot display indicates how far the copy has progressed. When the copy is complete, the status of the DB snapshot copy is set to available. 5. Amazon RDS then uses the copied DB snapshot for the initial data load on the Read Replica. During this phase, the Read Replica is in the list of DB instances in the destination, with a status of creating. When the load is complete, the Read Replica status is set to available, and the DB snapshot copy is deleted. 6. When the Read Replica reaches the available status, Amazon RDS starts by replicating the changes made to the source instance since the start of the create Read Replica operation. During this phase, the replication lag time for the Read Replica is greater than 0. For MySQL, MariaDB, and PostgreSQL Read Replicas, you can monitor replication lag in Amazon CloudWatch by viewing the Amazon RDS ReplicaLag metric. For MySQL and MariaDB, the ReplicaLag metric reports the value of the Seconds_Behind_Master field of the SHOW SLAVE STATUS command. For PostgreSQL, the ReplicaLag metric reports the value of SELECT extract(epoch from now() - pg_last_xact_replay_timestamp()) AS slave_lag. Common causes for replication lag for MySQL and MariaDB are the following: • A network outage. • Writing to tables with indexes on a Read Replica. If the read_only parameter is not set to 0 on the Read Replica, it can break replication. • Using a non-transactional storage engine such as MyISAM. Replication is only supported for the InnoDB storage engine on MySQL and the XtraDB storage engine on MariaDB. When the ReplicaLag metric reaches 0, the replica has caught up to the source DB instance. If the ReplicaLag metric returns -1, then replication is currently not active. ReplicaLag = -1 is equivalent to Seconds_Behind_Master = NULL. PostgreSQL (versions 9.4.7 and 9.5.2 and later) uses physical replication slots to manage Write Ahead Log (WAL) retention on the source instance. For each cross-region Read Replica instance, Amazon RDS creates a physical replication slot and associates it with the instance. Two Amazon CloudWatch metrics, Oldest Replication Slot Lag and Transaction Logs Disk Usage, show how far behind the most lagging replica is in terms of WAL data received and how much storage is being used for WAL data. The Transaction Logs Disk Usage value can substantially increase when a crossregion Read Replica is lagging significantly. Cross-Region Replication Examples Example Create a Cross-Region Read Replica Outside of Any VPC The following example creates a Read Replica in us-west-2 from a source DB instance in us-east-1. The Read Replica is created outside of a VPC: API Version 2014-10-31 149 Amazon Relational Database Service User Guide Monitoring Read Replication For Linux, OS X, or Unix: aws rds create-db-instance-read-replica \ --db-instance-identifier SimCoProd01Replica01 \ --region us-west-2 --source-db-instance-identifier arn:aws:rds:us-east-1:123456789012:db:SimcoProd01 For Windows: aws rds create-db-instance-read-replica ^ --db-instance-identifier SimCoProd01Replica01 ^ --region us-west-2 --source-db-instance-identifier arn:aws:rds:us-east-1:123456789012:db:SimcoProd01 Example Create Cross-Region Read Replica in a VPC This example creates a Read Replica in us-west-2 from a source DB instance in us-east-1. The Read Replica is created in the VPC associated with the specified DB subnet group: For Linux, OS X, or Unix: aws rds create-db-instance-read-replica \ --db-instance-identifier SimCoProd01Replica01 \ --region us-west-2 --db-subnet-group-name my-us-west-2-subnet --source-db-instance-identifier arn:aws:rds:us-east-1:123456789012:db:SimcoProd01 For Windows: aws rds create-db-instance-read-replica ^ --db-instance-identifier SimCoProd01Replica01 ^ --region us-west-2 --db-subnet-group-name my-us-west-2-subnet --source-db-instance-identifier arn:aws:rds:us-east-1:123456789012:db:SimcoProd01 Monitoring Read Replication You can monitor the status of a Read Replica in several ways. The Amazon RDS console shows the status of a Read Replica in the Availability and durability section of the Read Replica details. To view the details for a Read Replica, click the name of the Read Replica in the list of instances in the Amazon RDS console. API Version 2014-10-31 150 Amazon Relational Database Service User Guide Monitoring Read Replication You can also see the status of a Read Replica using the AWS CLI describe-db-instances command or the Amazon RDS API DescribeDBInstances action. The status of a Read Replica can be one of the following: • replicating—The Read Replica is replicating successfully. • error—An error has occurred with the replication. Check the Replication Error field in the Amazon RDS console or the event log to determine the exact error. For more information about troubleshooting a replication error, see Troubleshooting a MySQL Read Replica Problem (p. 654). • terminated—Replication is terminated. This occurs if replication is stopped for more than thirty consecutive days, either manually or due to a replication error. In this case, Amazon RDS terminates replication between the master DB instance and all Read Replicas in order to prevent increased storage requirements on the master DB instance and long failover times. Broken replication can affect storage because the logs can grow in size and number due to the high volume of errors messages being written to the log. Broken replication can also affect failure recovery due to the time Amazon RDS requires to maintain and process the large number of logs during recovery. • stopped (MySQL or MariaDB only)—Replication has stopped because of a customer initiated request. • replication stop point set (MySQL only)—A customer initiated stop point was set using the mysql.rds_start_replication_until (p. 697) stored procedure and the replication is in progress. • replication stop point reached (MySQL only)—A customer initiated stop point was set using the mysql.rds_start_replication_until (p. 697) stored procedure and replication is stopped because the stop point was reached. API Version 2014-10-31 151 Amazon Relational Database Service User Guide Working with Option Groups Working with Option Groups Some DB engines offer additional features that make it easier to manage data and databases, and to provide additional security for your database. Amazon RDS uses option groups to enable and configure these features. An option group can specify features, called options, that are available for a particular Amazon RDS DB instance. Options can have settings that specify how the option works. When you associate a DB instance with an option group, the specified options and option settings are enabled for that DB instance. Amazon RDS supports options for the following database engines: Database Engine Relevant Documentation MariaDB Options for MariaDB Database Engine (p. 465) Microsoft SQL Server Options for the Microsoft SQL Server Database Engine (p. 549) MySQL Options for MySQL DB Instances (p. 670) Oracle Options for Oracle DB Instances (p. 782) Option Groups Overview Amazon RDS provides an empty default option group for each new DB instance. You cannot modify this default option group, but any new option group that you create derives its settings from the default option group. To apply an option to a DB instance, you must do the following: 1. Create a new option group, or copy or modify an existing option group. 2. Add one or more options to the option group. 3. Associate the option group with the DB instance. Both DB instances and DB snapshots can be associated with an option group. When you restore from a DB snapshot or perform a point-in-time restore for a DB instance, the option group associated with the DB snapshot or DB instance will, by default, be associated with the restored DB instance. You can associate a different option group with a restored DB instance. However, the new option group must contain any persistent or permanent options that were included in the original option group. Persistent and permanent options are described following. Options require additional memory to run on a DB instance, so you might need to launch a larger instance to use them, depending on your current use of your DB instance. For example, Oracle Enterprise Manager Database Control uses about 300 MB of RAM; if you enable this option for a small DB instance, you might encounter performance problems or out-of-memory errors. Persistent and Permanent Options Two types of options, persistent and permanent, require special consideration when you add them to an option group. Persistent options, such as the TDE option for Microsoft SQL Server transparent data encryption (TDE), cannot be removed from an option group while DB instances are associated with the option group. You must disassociate all DB instances from the option group before a persistent option can be removed from the option group. When you restore or perform a point-in-time restore from a DB snapshot, if the option group associated with that DB snapshot contains a persistent option, you can only associate the restored DB instance with that option group. API Version 2014-10-31 152 Amazon Relational Database Service User Guide Creating an Option Group Permanent options, such as the TDE option for Oracle Advanced Security TDE, can never be removed from an option group, and the option group cannot be disassociated from the DB instance. When you restore or perform a point-in-time restore from a DB snapshot, if the option group associated with that DB snapshot contains a permanent option, you can only associate the restored DB instance with an option group with that permanent option. VPC and Platform Considerations When an option group is assigned to a DB instance, it is linked to the platform that the DB instance is on. That platform can either be a VPC supported by the Amazon Virtual Private Cloud (Amazon VPC) service, or EC2-Classic (non-VPC) supported by the Amazon Elastic Compute Cloud (Amazon EC2) service. For details on these two platforms, see Amazon EC2 and Amazon Virtual Private Cloud. If a DB instance is in a VPC, the option group associated with the instance is linked to that VPC. This means that you cannot use the option group assigned to a DB instance if you attempt to restore the instance into a different VPC or onto a different platform. If you restore a DB instance into a different VPC or onto a different platform, you must either assign the default option group to the DB instance, assign an option group that is linked to that VPC or platform, or create a new option group and assign it to the DB instance. Note that with persistent or permanent options, such as Oracle TDE, you must create a new option group that includes the persistent or permanent option when restoring a DB instance into a different VPC. Option settings control the behavior of an option. For example, the Oracle Advanced Security option NATIVE_NETWORK_ENCRYPTION has a setting that you can use to specify the encryption algorithm for network traffic to and from the DB instance. Some options settings are optimized for use with Amazon RDS and cannot be changed. Mutually Exclusive Options Some options are mutually exclusive. You can use one or the other, but not both at the same time. The following options are mutually exclusive: • Oracle Enterprise Manager Database Express (p. 791) and Oracle Management Agent for Enterprise Manager Cloud Control (p. 794). • Oracle Native Network Encryption (p. 810) and Oracle Secure Sockets Layer (p. 812). • Oracle Transparent Data Encryption (p. 831) and Using AWS CloudHSM Classic to Store Amazon RDS Oracle TDE Keys (p. 881). Creating an Option Group You can create a new option group that derives its settings from the default option group, and then add one or more options to the new option group. Alternatively, if you already have an existing option group, you can copy that option group with all of its options to a new option group. For more information, see Making a Copy of an Option Group (p. 155). After you create a new option group, it has no options. To learn how to add options to the option group, see Adding an Option to an Option Group (p. 156). After you have added the options you want, you can then associate the option group with a DB instance so that the options become available on the DB instance. For information about associating an option group with a DB instance, see the documentation for your specific engine listed at Working with Option Groups (p. 152). AWS Management Console One way of creating an option group is by using the AWS Management Console. API Version 2014-10-31 153 Amazon Relational Database Service User Guide Creating an Option Group To create a new option group by using the console 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Option groups. 3. Choose Create group. 4. In the Create option group window, do the following: 5. a. For Name, type a name for the option group that is unique within your AWS account. The name can contain only letters, digits, and hyphens. b. For Description, type a brief description of the option group. The description is used for display purposes. c. For Engine, choose the DB engine that you want. d. For Major engine version, choose the major version of the DB engine that you want. To continue, choose Create. To cancel the operation instead, choose Cancel. CLI To create an option group, use the AWS CLI create-option-group command with the following required parameters. • --option-group-name • --engine-name • --major-engine-version • --option-group-description Example The following example creates an option group named testoptiongroup, which is associated with the Oracle Enterprise Edition DB engine. The description is enclosed in quotation marks. For Linux, OS X, or Unix: aws rds create-option-group \ --option-group-name testoptiongroup \ --engine-name oracle-ee \ --major-engine-version 12.1 \ --option-group-description "Test option group" For Windows: aws rds create-option-group ^ --option-group-name testoptiongroup ^ --engine-name oracle-ee ^ --major-engine-version 12.1 ^ --option-group-description "Test option group" API Version 2014-10-31 154 Amazon Relational Database Service User Guide Making a Copy of an Option Group API To create an option group, call the Amazon RDS API CreateOptionGroup action. Include the following parameters: • OptionGroupName • EngineName • MajorEngineVersion • OptionGroupDescription Making a Copy of an Option Group You can use the AWS CLI or the Amazon RDS API to make a copy of an option group. Copying an option group is a convenient solution when you have already created an option group and you want to include most of the custom parameters and values from that group in a new option group. You can also make a copy of an option group that you use in production and then modify the copy to test other option settings. CLI To copy an option group, use the AWS CLI copy-option-group command. Include the following required parameters: • --source-option-group-identifier • --target-option-group-identifier • --target-option-group-description Example The following example creates an option group named new-local-option-group, which is a local copy of the option group my-remote-option-group. For Linux, OS X, or Unix: aws rds copy-option-group \ --source-option-group-identifier arn:aws:rds:us-west-2:123456789012:og:my-remoteoption-group \ --target-option-group-identifier new-local-option-group \ --target-option-group-description "Option group 2" For Windows: aws rds copy-option-group ^ --source-option-group-identifier arn:aws:rds:us-west-2:123456789012:og:my-remoteoption-group ^ --target-option-group-identifier new-local-option-group ^ --target-option-group-description "Option group 2" API To copy an option group, call the Amazon RDS API CopyOptionGroup action. Include the following required parameters. • SourceOptionGroupIdentifier API Version 2014-10-31 155 Amazon Relational Database Service User Guide Adding an Option to an Option Group • TargetOptionGroupIdentifier • TargetOptionGroupDescription Adding an Option to an Option Group You can add an option to an existing option group. After you have added the options you want, you can then associate the option group with a DB instance so that the options become available on the DB instance. For information about associating an option group with a DB instance, see the documentation for your specific DB engine listed at Working with Option Groups (p. 152). Option group changes must be applied immediately in two cases: • When you add an option that adds or updates a port value, such as the OEM option. • When you add or remove an option group with an option that includes a port value. In these cases, you must select the Apply Immediately option in the console, or include the ApplyImmediately option when using the AWS CLI or set the Apply-Immediately parameter to true when using the Amazon RDS API. Options that don't include port values can be applied immediately, or can be applied during the next maintenance window for the DB instance. AWS Management Console You can use the AWS Management Console to add an option to an option group. To add an option to an option group by using the console 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Option groups. 3. Select the option group that you want to modify, and then choose Add 0ption. 4. In the Add option window, do the following: a. Choose the option that you want to add. You might need to provide additional values, depending on the option that you select. For example, when you choose the OEM option, you must also type a port value and specify a DB security group. b. To enable the option on all associated DB instances as soon as you add it, for Apply Immediately, choose Yes. If you choose No (the default), the option is enabled for each associated DB instance during its next maintenance window. API Version 2014-10-31 156 Amazon Relational Database Service User Guide Adding an Option to an Option Group 5. When the settings are as you want them, choose Add Option. CLI To add an option to an option group, run the AWS CLI add-option-to-option-group command with the option that you want to add. To enable the new option immediately on all associated DB instances, include the --apply-immediately parameter. By default, the option is enabled for each associated DB instance during its next maintenance window. Include the following required parameter: • --option-group-name Example The following example adds the Oracle Enterprise Manager Database Control (OEM) option to an option group named testoptiongroup and immediately enables it. Note that even if you use the default security group, you must specify that security group. For Linux, OS X, or Unix: aws rds add-option-to-option-group \ API Version 2014-10-31 157 Amazon Relational Database Service User Guide Adding an Option to an Option Group --option-group-name testoptiongroup \ --options OptionName=OEM,Port=5500,DBSecurityGroupMemberships=default \ --apply-immediately For Windows: aws rds add-option-to-option-group ^ --option-group-name testoptiongroup ^ --options OptionName=OEM,Port=5500,DBSecurityGroupMemberships=default ^ --apply-immediately Command output is similar to the following: OPTIONGROUP False oracle-ee 12.1 arn:aws:rds:us-east-1:1234567890:og:testoptiongroup Test Option Group testoptiongroup default OPTIONS Oracle 12c EM Express OEM False False 5500 DBSECURITYGROUPMEMBERSHIPS default authorized Example The following example adds the Oracle OEM option to an option group, specifies a custom port, and specifies a pair of Amazon EC2 VPC security groups to use for that port. For Linux, OS X, or Unix: aws rds add-option-to-option-group \ --option-group-name testoptiongroup \ --options OptionName=OEM,Port=5500,VpcSecurityGroupMemberships="sg-test1,sg-test2" \ --apply-immediately For Windows: aws rds add-option-to-option-group ^ --option-group-name testoptiongroup ^ --options OptionName=OEM,Port=5500,VpcSecurityGroupMemberships="sg-test1,sg-test2" ^ --apply-immediately Command output is similar to the following: OPTIONGROUP False oracle-ee 12.1 arn:aws:rds:us-east-1:1234567890:og:testoptiongroup Test Option Group testoptiongroup vpc-test OPTIONS Oracle 12c EM Express OEM False False 5500 VPCSECURITYGROUPMEMBERSHIPS active sg-test1 VPCSECURITYGROUPMEMBERSHIPS active sg-test2 Example The following example adds the Oracle option NATIVE_NETWORK_ENCRYPTION to an option group and specifies the option settings. If no option settings are specified, default values are used. API Version 2014-10-31 158 Amazon Relational Database Service User Guide Listing the Options and Option Settings for an Option Group For Linux, OS X, or Unix: aws rds add-option-to-option-group \ --option-group-name testoptiongroup \ --options '[{"OptionSettings":[{"Name":"SQLNET.ENCRYPTION_SERVER","Value":"REQUIRED"}, {"Name":"SQLNET.ENCRYPTION_TYPES_SERVER","Value":"AES256,AES192,DES"}],"OptionName":"NATIVE_NETWORK_ENC \ --apply-immediately For Windows: aws rds add-option-to-option-group ^ --option-group-name testoptiongroup ^ --options "OptionSettings"=[{"Name"="SQLNET.ENCRYPTION_SERVER","Value"="REQUIRED"}, {"Name"="SQLNET.ENCRYPTION_TYPES_SERVER","Value"="AES256\,AES192\,DES"}],"OptionName"="NATIVE_NETWORK_E ^ --apply-immediately Command output is similar to the following: OPTIONGROUP False oracle-ee 12.1 arn:aws:rds:us-east-1:1234567890:og:testoptiongroup Test Option Group testoptiongroup OPTIONS Oracle Advanced Security - Native Network Encryption NATIVE_NETWORK_ENCRYPTION False False OPTIONSETTINGS RC4_256,AES256,AES192,3DES168,RC4_128,AES128,3DES112,RC4_56,DES,RC4_40,DES40 STATIC STRING RC4_256,AES256,AES192,3DES168,RC4_128,AES128,3DES112,RC4_56,DES,RC4_40,DES40 Specifies list of encryption algorithms in order of intended use True True SQLNET.ENCRYPTION_TYPES_SERVER AES256,AES192,DES OPTIONSETTINGS ACCEPTED,REJECTED,REQUESTED,REQUIRED STATIC STRING REQUESTED Specifies the desired encryption behavior False True SQLNET.ENCRYPTION_SERVER REQUIRED OPTIONSETTINGS SHA1,MD5 STATIC STRING SHA1,MD5 Specifies list of checksumming algorithms in order of intended use True True SQLNET.CRYPTO_CHECKSUM_TYPES_SERVER SHA1,MD5 API To add an option to an option group using the Amazon RDS API, call the ModifyOptionGroup action with the option that you want to add. To enable the new option immediately on all associated DB instances, include the ApplyImmediately parameter and set it to true. By default, the option is enabled for each associated DB instance during its next maintenance window. Include the following required parameter: • OptionGroupName Listing the Options and Option Settings for an Option Group You can list all the options and option settings for an option group. API Version 2014-10-31 159 Amazon Relational Database Service User Guide Modifying an Option Setting AWS Management Console You can use the AWS Management Console to list all of the options and option settings for an option group. To list the options and option settings for an option group 1. 2. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. In the navigation pane, choose Option groups. The Options column in the table shows the options and option settings in the option group. CLI To list the options and option settings for an option group, use the AWS CLI describe-optiongroups command. Specify the name of the option group whose options and settings you want to view. If you don't specify an option group name, all option groups are described. Example The following example lists the options and option settings for all option groups. aws rds describe-option-groups Example The following example lists the options and option settings for an option group named testoptiongroup. aws rds describe-option-groups --option-group-name testoptiongroup API To list the options and option settings for an option group, use the Amazon RDS API DescribeOptionGroups action. Specify the name of the option group whose options and settings you want to view. If you don't specify an option group name, all option groups are described. Modifying an Option Setting After you have added an option that has modifiable option settings, you can modify the settings at any time. If you change options or option settings in an option group, those changes are applied to all DB instances that are associated with that option group. For more information on what settings are available for the various options, see the documentation for your specific engine listed at Working with Option Groups (p. 152). Option group changes must be applied immediately in two cases: • When you add an option that adds or updates a port value, such as the OEM option. • When you add or remove an option group with an option that includes a port value. In these cases, you must select the Apply Immediately option in the console, or include the ApplyImmediately option when using the AWS CLI or set the Apply-Immediately parameter to true when using the Amazon RDS API. Options that don't include port values can be applied immediately, or can be applied during the next maintenance window for the DB instance. API Version 2014-10-31 160 Amazon Relational Database Service User Guide Modifying an Option Setting AWS Management Console You can use the AWS Management Console to modify an option setting. To modify an option setting by using the console 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Option groups. 3. Select the option group whose option that you want to modify, and then choose Modify option. 4. In the Modify option window, from Installed Options, choose the option whose setting you want to modify. Make the changes that you want. 5. To enable the option as soon as you add it, for Apply Immediately, choose Yes. If you choose No (the default), the option is enabled for each associated DB instance during its next maintenance window. 6. When the settings are as you want them, choose Modify Option. CLI To modify an option setting, use the AWS CLI add-option-to-option-group command with the option group and option that you want to modify. By default, the option is enabled for each associated DB instance during its next maintenance window. To apply the change immediately to all associated DB instances, include the --apply-immediately parameter. To modify an option setting, use the -settings argument. Example The following example modifies the port that the Oracle Enterprise Manager Database Control (OEM) uses in an option group named testoptiongroup and immediately applies the change. For Linux, OS X, or Unix: aws rds add-option-to-option-group \ --option-group-name testoptiongroup \ --options OptionName=OEM,Port=5432,DBSecurityGroupMemberships=default \ --apply-immediately For Windows: aws rds add-option-to-option-group ^ --option-group-name testoptiongroup ^ --options OptionName=OEM,Port=5432,DBSecurityGroupMemberships=default ^ --apply-immediately Command output is similar to the following: OPTIONGROUP False oracle-ee 12.1 arn:aws:rds:us-east-1:1234567890:og:testoptiongroup Test Option Group testoptiongroup OPTIONS Oracle 12c EM Express OEM False False 5432 DBSECURITYGROUPMEMBERSHIPS default authorized API Version 2014-10-31 161 Amazon Relational Database Service User Guide Modifying an Option Setting Example The following example modifies the Oracle option NATIVE_NETWORK_ENCRYPTION and changes the option settings. For Linux, OS X, or Unix: aws rds add-option-to-option-group \ --option-group-name testoptiongroup \ --options '[{"OptionSettings":[{"Name":"SQLNET.ENCRYPTION_SERVER","Value":"REQUIRED"}, {"Name":"SQLNET.ENCRYPTION_TYPES_SERVER","Value":"AES256,AES192,DES,RC4_256"}],"OptionName":"NATIVE_NET \ --apply-immediately For Windows: aws rds add-option-to-option-group ^ --option-group-name testoptiongroup ^ --options "OptionSettings"=[{"Name"="SQLNET.ENCRYPTION_SERVER","Value"="REQUIRED"}, {"Name"="SQLNET.ENCRYPTION_TYPES_SERVER","Value"="AES256\,AES192\,DES \,RC4_256"}],"OptionName"="NATIVE_NETWORK_ENCRYPTION" ^ --apply-immediately Command output is similar to the following: OPTIONGROUP False oracle-ee 12.1 arn:aws:rds:us-east-1:1234567890:og:testoptiongroup Test Option Group testoptiongroup OPTIONS Oracle Advanced Security - Native Network Encryption NATIVE_NETWORK_ENCRYPTION False False OPTIONSETTINGS RC4_256,AES256,AES192,3DES168,RC4_128,AES128,3DES112,RC4_56,DES,RC4_40,DES40 STATIC STRING RC4_256,AES256,AES192,3DES168,RC4_128,AES128,3DES112,RC4_56,DES,RC4_40,DES40 Specifies list of encryption algorithms in order of intended use True True SQLNET.ENCRYPTION_TYPES_SERVER AES256,AES192,DES,RC4_256 OPTIONSETTINGS ACCEPTED,REJECTED,REQUESTED,REQUIRED STATIC STRING REQUESTED Specifies the desired encryption behavior False True SQLNET.ENCRYPTION_SERVER REQUIRED OPTIONSETTINGS SHA1,MD5 STATIC STRING SHA1,MD5 Specifies list of checksumming algorithms in order of intended use True True SQLNET.CRYPTO_CHECKSUM_TYPES_SERVER SHA1,MD5 OPTIONSETTINGS ACCEPTED,REJECTED,REQUESTED,REQUIRED STATIC STRING REQUESTED Specifies the desired data integrity behavior False True SQLNET.CRYPTO_CHECKSUM_SERVER REQUESTED API To modify an option setting, use the Amazon RDS API ModifyOptionGroup command with the option group and option that you want to modify. By default, the option is enabled for each associated DB instance during its next maintenance window. To apply the change immediately to all associated DB instances, include the ApplyImmediately parameter and set it to true. API Version 2014-10-31 162 Amazon Relational Database Service User Guide Removing an Option from an Option Group Removing an Option from an Option Group Some options can be removed from an option group, and some cannot. A persistent option cannot be removed from an option group until all DB instances associated with that option group are disassociated. A permanent option can never be removed from an option group. For more information about what options are removable, see the documentation for your specific engine listed at Working with Option Groups (p. 152). If you remove all options from an option group, Amazon RDS doesn't delete the option group. DB instances that are associated with the empty option group continue to be associated with it; they just won’t have any active options. Alternatively, to remove all options from a DB instance, you can associate the DB instance with the default (empty) option group. AWS Management Console You can use the AWS Management Console to remove an option from an option group. To remove an option from an option group by using the console 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Option groups. 3. 4. Select the option group whose option you want to remove, and then choose Delete option. In the Delete option window, do the following: • Select the check box for the option that you want to delete. • For the deletion to take effect as soon as you make it, for Apply immediately, choose Yes. If you choose No (the default), the option is deleted for each associated DB instance during its next maintenance window. 5. When the settings are as you want them, choose Yes, Delete. CLI To remove an option from an option group, use the AWS CLI remove-option-from-optiongroup command with the option that you want to delete. By default, the option is removed from each API Version 2014-10-31 163 Amazon Relational Database Service User Guide Removing an Option from an Option Group associated DB instance during its next maintenance window. To apply the change immediately, include the --apply-immediately parameter. Example The following example removes the Oracle Enterprise Manager Database Control (OEM) option from an option group named testoptiongroup and immediately applies the change. For Linux, OS X, or Unix: aws rds remove-option-from-option-group \ --option-group-name testoptiongroup \ --options OEM \ --apply-immediately For Windows: aws rds remove-option-from-option-group ^ --option-group-name testoptiongroup ^ --options OEM ^ --apply-immediately Command output is similar to the following: OPTIONGROUP testoptiongroup oracle-ee 12.1 Test option group API To remove an option from an option group, use the Amazon RDS API ModifyOptionGroup action. By default, the option is removed from each associated DB instance during its next maintenance window. To apply the change immediately, include the ApplyImmediately parameter and set it to true. Include the following parameters: • OptionGroupName • OptionsToRemove.OptionName API Version 2014-10-31 164 Amazon Relational Database Service User Guide Working with Parameter Groups Working with DB Parameter Groups You manage your DB engine configuration through the use of parameters in a DB parameter group . DB parameter groups act as a container for engine configuration values that are applied to one or more DB instances. A default DB parameter group is created if you create a DB instance without specifying a customercreated DB parameter group. Each default DB parameter group contains database engine defaults and Amazon RDS system defaults based on the engine, compute class, and allocated storage of the instance. You cannot modify the parameter settings of a default DB parameter group; you must create your own DB parameter group to change parameter settings from their default value. Note that not all DB engine parameters can be changed in a customer-created DB parameter group. If you want to use your own DB parameter group, you simply create a new DB parameter group, modify the desired parameters, and modify your DB instance to use the new DB parameter group. All DB instances that are associated with a particular DB parameter group get all parameter updates to that DB parameter group. You can copy an existing DB parameter group with the AWS CLI copy-db-parameter-group command. Copying a parameter group is a convenient solution when you have already created a DB parameter group and you want to include most of the custom parameters and values from that group in a new DB parameter group. Here are some important points you should know about working with parameters in a DB parameter group: • When you change a dynamic parameter and save the DB parameter group, the change is applied immediately regardless of the Apply Immediately setting. When you change a static parameter and save the DB parameter group, the parameter change will take effect after you manually reboot the DB instance. You can reboot a DB instance using the RDS console or explicitly calling the RebootDbInstance API action (without failover, if the DB instance is in a Multi-AZ deployment). The requirement to reboot the associated DB instance after a static parameter change helps mitigate the risk of a parameter misconfiguration affecting an API call, such as calling ModifyDBInstance to change DB instance class or scale storage. • When you change the DB parameter group associated with a DB instance, you must manually reboot the instance before the new DB parameter group is used by the DB instance. • The value for a DB parameter can be specified as an integer or as an integer expression built from formulas, variables, functions, and operators. Functions can include a mathematical log expression. For more information, see DB Parameter Values (p. 173). • Set any parameters that relate to the character set or collation of your database in your parameter group prior to creating the DB instance and before you create a database in your DB instance. This ensures that the default database and new databases in your DB instance use the character set and collation values that you specify. If you change character set or collation parameters for your DB instance, the parameter changes are not applied to existing databases. You can change character set or collation values for an existing database using the ALTER DATABASE command, for example: ALTER DATABASE database_name CHARACTER SET character_set_name COLLATE collation; • Improperly setting parameters in a DB parameter group can have unintended adverse effects, including degraded performance and system instability. Always exercise caution when modifying database parameters and back up your data before modifying a DB parameter group. You should try out parameter group setting changes on a test DB instance before applying those parameter group changes to a production DB instance. API Version 2014-10-31 165 Amazon Relational Database Service User Guide Creating a DB Parameter Group Topics • Creating a DB Parameter Group (p. 166) • Modifying Parameters in a DB Parameter Group (p. 167) • Copying a DB Parameter Group (p. 169) • Listing DB Parameter Groups (p. 171) • Viewing Parameter Values for a DB Parameter Group (p. 172) • Comparing DB Parameter Groups (p. 173) • DB Parameter Values (p. 173) Creating a DB Parameter Group You can create a new DB parameter group using the AWS Management Console, the AWS CLI, or the RDS API. AWS Management Console To create a DB parameter group 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Parameter groups. 3. Choose Create parameter group. The Create parameter group window appears. 4. In the Parameter group family list, select a DB parameter group family. 5. In the Type list, select DB Parameter Group. 6. In the Group name box, type the name of the new DB parameter group. 7. In the Description box, type a description for the new DB parameter group. 8. Choose Create. CLI To create a DB parameter group, use the AWS CLI create-db-parameter-group command. The following example creates a DB parameter group named mydbparametergroup for MySQL version 5.6 with a description of "My new parameter group." Include the following required parameters: • --db-parameter-group-name • --db-parameter-group-family • --description To list all of the available parameter group families, use the following command: aws rds describe-db-engine-versions --query "DBEngineVersions[].DBParameterGroupFamily" Note The output contains duplicates. API Version 2014-10-31 166 Amazon Relational Database Service User Guide Modifying Parameters in a DB Parameter Group Example For Linux, OS X, or Unix: aws rds create-db-parameter-group \ --db-parameter-group-name mydbparametergroup \ --db-parameter-group-family MySQL5.6 \ --description "My new parameter group" For Windows: aws rds create-db-parameter-group ^ --db-parameter-group-name mydbparametergroup ^ --db-parameter-group-family MySQL5.6 ^ --description "My new parameter group" This command produces output similar to the following: DBPARAMETERGROUP mydbparametergroup mysql5.6 My new parameter group API To create a DB parameter group, use the Amazon RDS API CreateDBParameterGroup action. Include the following required parameters: • DBParameterGroupName • DBParameterGroupFamily • Description Modifying Parameters in a DB Parameter Group You can modify parameter values in a customer-created DB parameter group; you cannot change the parameter values in a default DB parameter group. Changes to parameters in a customer-created DB parameter group are applied to all DB instances that are associated with the DB parameter group. If you change a parameter value, when the change is applied is determined by the type of parameter. Changes to dynamic parameters are applied immediately. Changes to static parameters require that the DB instance associated with DB parameter group be rebooted before the change takes effect. To determine the type of a parameter, list the parameters in a parameter group using one of the procedures shown in the section Listing DB Parameter Groups (p. 171). The RDS console shows the status of the DB parameter group associated with a DB instance. For example, if the DB instance is not using the latest changes to its associated DB parameter group, the RDS console shows the DB parameter group with a status of pending-reboot. You would need to manually reboot the DB instance for the latest parameter changes to take effect for that DB instance. API Version 2014-10-31 167 Amazon Relational Database Service User Guide Modifying Parameters in a DB Parameter Group AWS Management Console To modify a DB parameter group 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Parameter groups. 3. In the list, select the parameter group you want to modify. 4. Choose Parameter group actions, and then choose Edit. 5. Change the values of the parameters you want to modify. You can scroll through the parameters using the arrow keys at the top right of the dialog box. Note that you cannot change values in a default parameter group. 6. Choose Save changes. API Version 2014-10-31 168 Amazon Relational Database Service User Guide Copying a DB Parameter Group CLI To modify a DB parameter group, use the AWS CLI modify-db-parameter-group command with the following required parameters: • --db-parameter-group-name • --parameters The following example modifies the max_connections and max_allowed_packet values in the DB parameter group named mydbparametergroup. Note Amazon RDS does not support passing multiple comma-delimited parameter values for a single parameter. Example For Linux, OS X, or Unix: aws rds modify-db-parameter-group \ --db-parameter-group-name mydbparametergroup \ --parameters "ParameterName=max_connections,ParameterValue=250,ApplyMethod=immediate" \ "ParameterName=max_allowed_packet,ParameterValue=1024,ApplyMethod=immediate" For Windows: aws rds modify-db-parameter-group ^ --db-parameter-group-name mydbparametergroup ^ --parameters "ParameterName=max_connections,ParameterValue=250,ApplyMethod=immediate" ^ "ParameterName=max_allowed_packet,ParameterValue=1024,ApplyMethod=immediate" The command produces output like the following: DBPARAMETERGROUP mydbparametergroup API To modify a DB parameter group, use the Amazon RDS API ModifyDBParameterGroup command with the following required parameters: • DBParameterGroupName • Parameters Copying a DB Parameter Group You can copy custom DB parameter groups that you create. Copying a parameter group is a convenient solution when you have already created a DB parameter group and you want to include most of the custom parameters and values from that group in a new DB parameter group. You can copy a DB parameter group by using the AWS CLI copy-db-parameter-group command or the Amazon RDS API CopyDBParameterGroup action. After you copy a DB parameter group, you should wait at least 5 minutes before creating your first DB instance that uses that DB parameter group as the default parameter group. This allows Amazon RDS to API Version 2014-10-31 169 Amazon Relational Database Service User Guide Copying a DB Parameter Group fully complete the copy action before the parameter group is used as the default for a new DB instance. This is especially important for parameters that are critical when creating the default database for a DB instance, such as the character set for the default database defined by the character_set_database parameter. You can use the Parameter Groups option of the Amazon RDS console or the describe-dbparameters command to verify that your DB parameter group has been created. Note You can't copy a default parameter group. However, you can create a new parameter group that is based on a default parameter group. AWS Management Console To copy a DB parameter group 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Parameter groups. 3. In the list, select the custom parameter group you want to copy. 4. 5. Choose Parameter group actions, and then choose Copy. In New DB parameter group identifier, type a name for the new parameter group. 6. In Description, type a description for the new parameter group. 7. Choose Copy. CLI To copy a DB parameter group, use the AWS CLI copy-db-parameter-group command with the following required parameters: • --source-db-parameter-group-identifier • --target-db-parameter-group-identifier • --target-db-parameter-group-description The following example creates a new DB parameter group named mygroup2 that is a copy of the DB parameter group mygroup1. Example For Linux, OS X, or Unix: aws rds copy-db-parameter-group \ --source-db-parameter-group-identifier mygroup1 \ --target-db-parameter-group-identifier mygroup2 \ --target-db-parameter-group-description "DB parameter group 2" For Windows: aws rds copy-db-parameter-group ^ --source-db-parameter-group-identifier mygroup1 ^ --target-db-parameter-group-identifier mygroup2 ^ --target-db-parameter-group-description "DB parameter group 2" API To copy a DB parameter group, use the RDS API CopyDBParameterGroup action with the following required parameters: API Version 2014-10-31 170 Amazon Relational Database Service User Guide Listing DB Parameter Groups • SourceDBParameterGroupIdentifier • TargetDBParameterGroupIdentifier • TargetDBParameterGroupDescription Listing DB Parameter Groups You can list the DB parameter groups you've created for your AWS account. Note Default parameter groups are automatically created from a default parameter template when you create a DB instance for a particular DB engine and version. These default parameter groups contain preferred parameter settings and cannot be modified. When you create a custom parameter group, you can modify parameter settings. AWS Management Console To list all DB parameter groups for an AWS account 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Parameter groups. The DB parameter groups appear in a list. CLI To list all DB parameter groups for an AWS account, use the AWS CLI describe-db-parametergroups command. Example The following example lists all available DB parameter groups for an AWS account. aws rds describe-db-parameter-groups The command returns a response like the following: DBPARAMETERGROUP DBPARAMETERGROUP DBPARAMETERGROUP default.mysql5.5 default.mysql5.6 mydbparametergroup mysql5.5 mysql5.6 mysql5.6 Default parameter group for MySQL5.5 Default parameter group for MySQL5.6 My new parameter group The following example describes the mydbparamgroup1 parameter group. For Linux, OS X, or Unix: aws rds describe-db-parameter-groups \ --db-parameter-group-name mydbparamgroup1 For Windows: aws rds describe-db-parameter-groups ^ --db-parameter-group-name mydbparamgroup1 The command returns a response like the following: API Version 2014-10-31 171 Amazon Relational Database Service User Guide Viewing Parameter Values for a DB Parameter Group DBPARAMETERGROUP mydbparametergroup1 mysql5.5 My new parameter group API To list all DB parameter groups for an AWS account, use the RDS API DescribeDBParameterGroups action. Viewing Parameter Values for a DB Parameter Group You can get a list of all parameters in a DB parameter group and their values. AWS Management Console To view the parameter values for a DB parameter group 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Parameter groups. The DB parameter groups appear in a list. 3. Click the name of the parameter group to see the its list of parameters. CLI To view the parameter values for a DB parameter group, use the AWS CLI describe-db-parameters command with the following required parameter. • --db-parameter-group-name Example The following example lists the parameters and parameter values for a DB parameter group named mydbparametergroup. aws rds describe-db-parameters --db-parameter-group-name mydbparametergroup The command returns a response like the following: DBPARAMETER Parameter Name Type Is Modifiable DBPARAMETER allow-suspicious-udfs false DBPARAMETER auto_increment_increment true DBPARAMETER auto_increment_offset true DBPARAMETER binlog_cache_size true DBPARAMETER socket false Parameter Value Source Data Type Apply engine-default boolean static engine-default integer dynamic engine-default integer dynamic 32768 system integer dynamic /tmp/mysql.sock system string static API To view the parameter values for a DB parameter group, use the Amazon RDS API DescribeDBParameters command with the following required parameter. API Version 2014-10-31 172 Amazon Relational Database Service User Guide Comparing DB Parameter Groups • DBParameterGroupName Comparing DB Parameter Groups You can use the AWS Management Console to view the differences between two parameter groups for the same DB engine and version. To compare two parameter groups 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. 3. In the navigation pane, choose Parameter groups. In the list, select the two parameter groups you want to compare. 4. Choose Parameter group actions, and then choose Compare. DB Parameter Values The value for a DB parameter can be specified as: • An integer constant • A DB parameter formula • A DB parameter function • A character string constant • A log expression (the log function represents log base 2), such as value={log(DBInstanceClassMemory/8187281418)*1000} DB Parameter Formulas A DB parameter formula is an expression that resolves to an integer value or a Boolean value, and is enclosed in braces: {}. Formulas can be specified for either a DB parameter value or as an argument to a DB parameter function. Syntax {FormulaVariable} {FormulaVariable*Integer} {FormulaVariable*Integer/Integer} {FormulaVariable/Integer} DB Parameter Formula Variables Each formula variable returns integer or a Boolean value. The names of the variables are case sensitive. AllocatedStorage Returns the size, in bytes, of the data volume. API Version 2014-10-31 173 Amazon Relational Database Service User Guide DB Parameter Values DBInstanceClassMemory Returns the number of bytes of memory allocated to the DB instance class associated with the current DB instance, less the memory used by the Amazon RDS processes that manage the instance. EndPointPort Returns the number of the port used when connecting to the DB instance. DBInstanceClassHugePagesDefault Returns a Boolean value. Currently, it is only supported for Oracle engines. For more information, see Using Huge Pages with an Oracle DB Instance (p. 729). DB Parameter Formula Operators DB parameter formulas support two operators: division and multiplication. Division Operator: / Divides the dividend by the divisor, returning an integer quotient. Decimals in the quotient are truncated, not rounded. Syntax dividend / divisor The dividend and divisor arguments must be integer expressions. Multiplication Operator: * Multiplies the expressions, returning the product of the expressions. Decimals in the expressions are truncated, not rounded. Syntax expression * expression Both expressions must be integers. DB Parameter Functions The parameter arguments can be specified as either integers or formulas. Each function must have at least one argument. Multiple arguments can be specified as a comma-separated list. The list cannot have any empty members, such as argument1,,argument3. Function names are case insensitive. Note DB Parameter functions are not currently supported in CLI. IF() Returns an argument. Currently, it is only supported for Oracle engines, and the only supported first argument is {DBInstanceClassHugePagesDefault}. For more information, see Using Huge Pages with an Oracle DB Instance (p. 729). Syntax API Version 2014-10-31 174 Amazon Relational Database Service User Guide DB Parameter Values IF(argument1, argument2, argument3) Returns the second argument if the first argument evaluates to true. Returns the third argument otherwise. GREATEST() Returns the largest value from a list of integers or parameter formulas. Syntax GREATEST(argument1, argument2,...argumentn) Returns an integer. LEAST() Returns the smallest value from a list of integers or parameter formulas. Syntax LEAST(argument1, argument2,...argumentn) Returns an integer. SUM() Adds the values of the specified integers or parameter formulas. Syntax SUM(argument1, argument2,...argumentn) Returns an integer. DB Parameter Value Examples These examples show using formulas and functions in the values for DB parameters. Warning Improperly setting parameters in a DB parameter group can have unintended adverse effects, including degraded performance and system instability. Always exercise caution when modifying database parameters and back up your data before modifying your DB parameter group. You should try out parameter group changes on a test DB instances, created using point-in-time-restores, before applying those parameter group changes to your production DB instances. You can specify the GREATEST function in an Oracle processes parameter to set the number of user processes to the larger of either 80 or DBInstanceClassMemory divided by 9868951. GREATEST({DBInstanceClassMemory/9868951},80) You can specify the LEAST() function in a MySQL max_binlog_cache_size parameter value to set the maximum cache size a transaction can use in a MySQL instance to the lesser of 1MB or DBInstanceClass/256: LEAST({DBInstanceClassMemory/256},10485760) API Version 2014-10-31 175 Amazon Relational Database Service User Guide DB Parameter Values API Version 2014-10-31 176 Amazon Relational Database Service User Guide Working with ARNs Working with Amazon Resource Names (ARNs) in Amazon RDS Resources created in Amazon Web Services are each uniquely identified with an Amazon Resource Name (ARN). For certain Amazon RDS operations, you must uniquely identify an Amazon RDS resource by specifying its ARN. For example, when you create an RDS DB instance Read Replica, you must supply the ARN for the source DB instance. Constructing an ARN for Amazon RDS Resources created in Amazon Web Services are each uniquely identified with an Amazon Resource Name (ARN). You can construct an ARN for an Amazon RDS resource using the following syntax. arn:aws:rds:::: Region Name Region Endpoint Protocol US East (Ohio) us-east-2 rds.us-east-2.amazonaws.com HTTPS US East (N. Virginia) us-east-1 rds.us-east-1.amazonaws.com HTTPS US West (N. California) us-west-1 rds.us-west-1.amazonaws.com HTTPS US West (Oregon) us-west-2 rds.us-west-2.amazonaws.com HTTPS Asia Pacific (Mumbai) ap-south-1 rds.ap-south-1.amazonaws.com HTTPS Asia Pacific (OsakaLocal) apnortheast-3 rds.ap-northeast-3.amazonaws.com HTTPS Asia Pacific (Seoul) apnortheast-2 rds.ap-northeast-2.amazonaws.com HTTPS Asia Pacific (Singapore) apsoutheast-1 rds.ap-southeast-1.amazonaws.com HTTPS Asia Pacific (Sydney) apsoutheast-2 rds.ap-southeast-2.amazonaws.com HTTPS Asia Pacific (Tokyo) apnortheast-1 rds.ap-northeast-1.amazonaws.com HTTPS Canada (Central) ca-central-1 rds.ca-central-1.amazonaws.com HTTPS China (Beijing) cn-north-1 rds.cn-north-1.amazonaws.com.cn HTTPS China (Ningxia) cnnorthwest-1 rds.cn-northwest-1.amazonaws.com.cn HTTPS API Version 2014-10-31 177 Amazon Relational Database Service User Guide Constructing an ARN Region Name Region Endpoint Protocol EU (Frankfurt) eu-central-1 rds.eu-central-1.amazonaws.com HTTPS EU (Ireland) eu-west-1 rds.eu-west-1.amazonaws.com HTTPS EU (London) eu-west-2 rds.eu-west-2.amazonaws.com HTTPS EU (Paris) eu-west-3 rds.eu-west-3.amazonaws.com HTTPS South America (São Paulo) sa-east-1 rds.sa-east-1.amazonaws.com HTTPS AWS GovCloud (US-East) us-goveast-1 rds.us-gov-east-1.amazonaws.com HTTPS AWS GovCloud (US) us-govwest-1 rds.us-gov-west-1.amazonaws.com HTTPS The following table shows the format that you should use when constructing an ARN for a particular Amazon RDS resource type. Resource Type ARN Format DB instance arn:aws:rds:::db: For example: arn:aws:rds:us-east-2:123456789012:db:my-mysql-instance-1 DB cluster arn:aws:rds:::cluster: For example: arn:aws:rds:us-east-2:123456789012:cluster:my-auroracluster-1 Event subscription arn:aws:rds:::es: For example: arn:aws:rds:us-east-2:123456789012:es:my-subscription DB option group arn:aws:rds:::og: For example: arn:aws:rds:us-east-2:123456789012:og:my-og DB parameter group arn:aws:rds:::pg: API Version 2014-10-31 178 Amazon Relational Database Service User Guide Getting an Existing ARN Resource Type ARN Format For example: arn:aws:rds:us-east-2:123456789012:pg:my-param-enable-logs DB cluster parameter group arn:aws:rds:::cluster-pg: For example: arn:aws:rds:us-east-2:123456789012:cluster-pg:my-clusterparam-timezone Reserved DB instance arn:aws:rds:::ri: For example: arn:aws:rds:us-east-2:123456789012:ri:my-reservedpostgresql DB security group arn:aws:rds:::secgrp: For example: arn:aws:rds:us-east-2:123456789012:secgrp:my-public DB snapshot arn:aws:rds:::snapshot: For example: arn:aws:rds:us-east-2:123456789012:snapshot:my-mysqlsnap-20130507 DB cluster snapshot arn:aws:rds:::cluster-snapshot: For example: arn:aws:rds:us-east-2:123456789012:cluster-snapshot:myaurora-snap-20160809 DB subnet group arn:aws:rds:::subgrp: For example: arn:aws:rds:us-east-2:123456789012:subgrp:my-subnet-10 Getting an Existing ARN You can get the ARN of an RDS resource by using the AWS Management Console, AWS Command Line Interface (AWS CLI), or RDS API. API Version 2014-10-31 179 Amazon Relational Database Service User Guide Getting an Existing ARN AWS Management Console To get an ARN from the AWS Management Console, navigate to the resource you want an ARN for, and view the details for that resource. For example, you can get the ARN for a DB instance from the DB instance details as shown following. AWS CLI To get an ARN from the AWS CLI for a particular RDS resource, you use the describe command for that resource. The following table shows each AWS CLI command, and the ARN property used with the command to get an ARN. AWS CLI Command ARN Property describe-event-subscriptions EventSubscriptionArn API Version 2014-10-31 180 Amazon Relational Database Service User Guide Getting an Existing ARN AWS CLI Command ARN Property describe-certificates CertificateArn describe-db-parameter-groups DBParameterGroupArn describe-db-cluster-parametergroups DBClusterParameterGroupArn describe-db-instances DBInstanceArn describe-db-security-groups DBSecurityGroupArn describe-db-snapshots DBSnapshotArn describe-events SourceArn describe-reserved-db-instances ReservedDBInstanceArn describe-db-subnet-groups DBSubnetGroupArn describe-option-groups OptionGroupArn describe-db-clusters DBClusterArn describe-db-cluster-snapshots DBClusterSnapshotArn For example, the following AWS CLI command gets the ARN for a DB instance. Example For Linux, OS X, or Unix: aws rds describe-db-instances \ --db-instance-identifier DBInstanceIdentifier \ --region us-west-2 For Windows: aws rds describe-db-instances ^ --db-instance-identifier DBInstanceIdentifier ^ --region us-west-2 API To get an ARN for a particular RDS resource, you can call the following RDS API actions and use the ARN properties shown following. RDS API Action ARN Property DescribeEventSubscriptions EventSubscriptionArn DescribeCertificates CertificateArn DescribeDBParameterGroups DBParameterGroupArn DescribeDBClusterParameterGroups DBClusterParameterGroupArn API Version 2014-10-31 181 Amazon Relational Database Service User Guide Getting an Existing ARN RDS API Action ARN Property DescribeDBInstances DBInstanceArn DescribeDBSecurityGroups DBSecurityGroupArn DescribeDBSnapshots DBSnapshotArn DescribeEvents SourceArn DescribeReservedDBInstances ReservedDBInstanceArn DescribeDBSubnetGroups DBSubnetGroupArn DescribeOptionGroups OptionGroupArn DescribeDBClusters DBClusterArn DescribeDBClusterSnapshots DBClusterSnapshotArn API Version 2014-10-31 182 Amazon Relational Database Service User Guide Working with Storage Working with Storage To specify how you want your data stored in Amazon RDS, you select a storage type and provide a storage size when you create or modify a DB instance. Later, you can increase the amount or change the type of storage by modifying the DB instance. For more information about which storage type to use for your workload, see Amazon RDS Storage Types (p. 101). Topics • Increasing DB instance storage capacity (p. 183) • Changing your storage type (p. 184) • Modifying Provisioned IOPS SSD storage settings (p. 186) Increasing DB instance storage capacity If you need space for additional data, you can scale up the storage of an existing DB instance. To do so, you can use the Amazon RDS Management Console, the Amazon RDS API, or the AWS Command Line Interface (AWS CLI). If you are using General Purpose SSD or Provisioned IOPS SSD storage, you can increase your storage to a maximum of 16 TiB. Scaling storage for Amazon RDS for SQL Server database instance, is supported only for General Purpose SSD or Provisioned IOPS SSD storage types. We recommend that you create a CloudWatch alarm to monitor the amount of free storage for your DB instance so you can respond when necessary. For more information on setting CloudWatch alarms, see Using Amazon RDS Event Notification (p. 278). In most cases, scaling storage doesn't require any outage and does not degrade performance of the server. After you modify the storage size for a DB instance, the status of the DB instance is storageoptimization. The DB instance is fully operational after a storage modification. However, you can't make further storage modifications for either six (6) hours or while the DB instance status is storageoptimization, whichever is longer. If you have a SQL Server DB instance and have not modified the storage configuration since November 2017, you might experience a short outage of a few minutes when you modify your DB instance to increase the allocated storage. After the outage, the DB instance is online but in the storageoptimization state. Performance might be degraded during storage optimization. Note You can't reduce the amount of storage for a DB instance after it has been allocated. AWS Management Console To increase storage for a DB instance 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Instances. 3. Choose the DB instance that you want to modify. 4. For Instance actions, choose Modify. 5. Type a new value for Allocated Storage. It must be greater than the current value. API Version 2014-10-31 183 Amazon Relational Database Service User Guide Change storage type Note When you increase Allocated Storage it must be by at least 10 %. If you try to increase by less than 10 % you see an error. 6. Choose Continue to move to the next screen. 7. To immediately initiate conversion of the DB instance to use the new storage type, choose the Apply immediately check box in the Scheduling of modifications section. If you want the changes to be applied in the next maintenance window, choose that option. 8. When the settings are as you want them, choose Modify DB instance. CLI To increase the storage for a DB instance, use the AWS CLI modify-db-instance command. Set the following parameters: • --allocated-storage – Amount of storage to be allocated for the DB instance, in gibibytes. • --apply-immediately – Use --apply-immediately to initiate conversion immediately, or --noapply-immediately (the default) to apply the conversion during the next maintenance window. An immediate outage occurs when the conversion is applied. For more information about storage, see DB instance storage (p. 101). API To increase storage for a DB instance, use the Amazon RDS API ModifyDBInstance action. Set the following parameters: • AllocatedStorage – Amount of storage to be allocated for the DB instance, in gibibytes. • ApplyImmediately – Set this option to True if you want to initiate conversion immediately. If this option is False (the default), the scaling is applied during the next maintenance window. An immediate outage occurs when the conversion is applied. For more information about storage, see DB instance storage (p. 101). Changing your storage type You can change the type of storage for your DB instance by using the AWS Management Console, the Amazon RDS API, or the AWS Command Line Interface (AWS CLI). When you convert from one storage type to another an outage occurs while the data for that DB instance is migrated to a new volume. The duration of the migration depends on several factors such as API Version 2014-10-31 184 Amazon Relational Database Service User Guide Change storage type database load, storage size, storage type, and amount of IOPS provisioned (if any). The typical migration time is a few minutes. The DB instance is available for use during the migration. However, when you are migrating to or from magnetic storage, the migration time can take up to several days in some cases. During the migration to or from magnetic storage, the DB instance is available for use, but might experience performance degradation. Storage conversions from Provisioned IOPS SSD or magnetic storage to General Purpose SSD storage can potentially deplete the I/O credits allocated for General Purpose SSD storage. This is especially on smaller volumes. After the initial I/O burst credits for the volume are depleted, the remaining data is converted at the base performance rate of 3 IOPS per GiB of allocated General Purpose SSD storage. This approach can result in significantly longer conversion times. AWS Management Console To change the storage type for a DB instance 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Instances. Note To filter the list of DB instances, for Filter instances, type a text string for Amazon RDS to use to filter the results. Only DB instances whose names contain the string appear. 3. Choose the DB instance that you want to modify. 4. For Instance actions, choose Modify. 5. On the Modify DB Instance page, choose the type of storage from the Storage type list. If you are modifying your DB instance to use Provisioned IOPS SSD storage type, then also provide a Provisioned IOPS value. 6. Choose Continue. 7. To apply the changes to the DB instance immediately, choose the Apply immediately check box in the Scheduling of modifications section. Alternatively, you can choose Apply during the next scheduled maintenance window. An immediate outage occurs when the storage type changes. For more information about storage, see DB instance storage (p. 101). API Version 2014-10-31 185 Amazon Relational Database Service User Guide Modify Provisioned IOPS 8. Review the parameters to be changed, and choose Modify DB instance to complete the modification. CLI To change the type of storage for a DB instance, use the AWS CLI modify-db-instance command. Set the following parameters: • --storage-type – Set to io1 for Provisioned IOPS. • --apply-immediately – Use --apply-immediately to initiate conversion immediately. Use -no-apply-immediately (the default) to apply the conversion during the next maintenance window. API To change the type of storage for a DB instance, use the Amazon RDS API ModifyDBInstance action. Set the following parameters: • StorageType – Set to io1 for Provisioned IOPS. • ApplyImmediately – Set this option to True if you want to initiate conversion immediately. If this option is False (the default), the conversion is applied during the next maintenance window. Modifying Provisioned IOPS SSD storage settings You can modify the settings for a DB instance that uses Provisioned IOPS SSD Storage by using the AWS Management Console, the Amazon RDS API, or the AWS CLI. Specify the storage type, allocated storage, and the amount of Provisioned IOPS that you require. You can choose between 1,000 IOPS and 100 GiB of storage up to 40,000 IOPS and 32 TiB (32768 GiB) of storage, depending on your database engine. Although you can reduce the amount of IOPS provisioned for your instance, you can't reduce the amount of General Purpose SSD or magnetic storage allocated. AWS Management Console To change the Provisioned IOPS settings for a DB instance 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Instances. Note To filter the list of DB instances, for Filter instances, type a text string for Amazon RDS to use to filter the results. Only DB instances whose names contain the string appear. 3. Choose the DB instance with Provisioned IOPS that you want to modify. 4. For Instance actions, choose Modify. 5. On the Modify DB Instance page, choose Provisioned IOPS for Storage type and then provide a Provisioned IOPS value. API Version 2014-10-31 186 Amazon Relational Database Service User Guide Modify Provisioned IOPS If the value you specify for either Allocated storage or Provisioned IOPS is outside the limits supported by the other parameter, a warning message is displayed. This messages gives the range of values required for the other parameter. 6. Choose Continue. 7. To apply the changes to the DB instance immediately, choose the Apply immediately check box in the Scheduling of modifications section. Alternatively, you can choose Apply during the next scheduled maintenance window. An immediate outage occurs when the storage type changes. For more information about storage, see DB instance storage (p. 101). 8. Review the parameters to be changed, and choose Modify DB instance to complete the modification. The new value for allocated storage or for Provisioned IOPS appears in the Status column. CLI To change the Provisioned IOPS setting for a DB instance, use the AWS CLI modify-db-instance command. Set the following parameters: • --storage-type – Set to io1 for Provisioned IOPS. • --allocated-storage – Amount of storage to be allocated for the DB instance, in gibibytes. • --iops – The new amount of Provisioned IOPS for the DB instance, expressed in I/O operations per second. • --apply-immediately – Use --apply-immediately to initiate conversion immediately. Use -no-apply-immediately (the default) to apply the conversion during the next maintenance window. API To change the Provisioned IOPS settings for a DB instance, use the Amazon RDS API ModifyDBInstance action. Set the following parameters: • StorageType – Set to io1 for Provisioned IOPS. • AllocatedStorage – Amount of storage to be allocated for the DB instance, in gibibytes. • Iops – The new IOPS rate for the DB instance, expressed in I/O operations per second. • ApplyImmediately – Set this option to True if you want to initiate conversion immediately. If this option is False (the default), the modification is applied during the next maintenance window. API Version 2014-10-31 187 Amazon Relational Database Service User Guide DB Instance Billing for Amazon RDS DB Instance Billing for Amazon RDS Amazon RDS instances are billed based on the following components: • DB instance hours (per hour) – Based on the DB instance class of the DB instance (for example, db.t2.small or db.m4.large). Partial DB instance hours consumed are billed as full hours. For more information, see DB Instance Class (p. 80). • Storage (per GiB per month) – Storage capacity that you have provisioned to your DB instance. If you scale your provisioned storage capacity within the month, your bill is pro-rated. For more information, see DB instance storage (p. 101). • I/O requests (per 1 million requests per month) – Total number of storage I/O requests that you have made in a billing cycle, for Amazon RDS magnetic storage only. • Provisioned IOPS (per IOPS per month) – Provisioned IOPS rate, regardless of IOPS consumed, for Amazon RDS Provisioned IOPS (SSD) Storage only. • Backup storage (per GiB per month) – Backup storage is the storage that is associated with automated database backups and any active database snapshots that you have taken. Increasing your backup retention period or taking additional database snapshots increases the backup storage consumed by your database. For more information, see Backing Up and Restoring Amazon RDS DB Instances (p. 201). • Data transfer (per GB) – Data transfer in and out of your DB instance from or to the internet and other AWS Regions. Amazon RDS provides the following purchasing options to enable you to optimize your costs based on your needs: • On-Demand Instances – Pay by the hour for the DB instance hours that you use. • Reserved Instances – Reserve a DB instance for a one-year or three-year term and receive a significant discount compared to the on-demand DB instance pricing. For Amazon RDS pricing information, see the Amazon RDS product page. Topics • On-Demand DB Instances (p. 189) • Reserved DB Instances (p. 190) API Version 2014-10-31 188 Amazon Relational Database Service User Guide On-Demand DB Instances On-Demand DB Instances Amazon RDS on-demand DB instances are billed based on the class of the DB instance (for example, db.t2.small or db.m4.large). Partial DB instance hours consumed are billed as full hours. For Amazon RDS pricing information, see the Amazon RDS product page. Billing starts for a DB instance as soon as the DB instance is available. DB instance hours are billed for each hour that your DB instance is running in an available state. Billing continues until the DB instance terminates, which occurs when you delete the DB instance or if the DB instance fails. If you no longer want to be charged for your DB instance, you must stop or delete it to avoid being billed for additional DB instance hours. For more information about the DB instance states for which you are billed, see DB Instance Status (p. 96). Stopped DB Instances While your DB instance is stopped, you are charged for provisioned storage, including Provisioned IOPS. You are also charged for backup storage, including storage for manual snapshots and automated backups within your specified retention window. You are not charged for DB instance hours. Multi-AZ DB Instances If you specify that your DB instance should be a Multi-AZ deployment, you are billed according to the Multi-AZ pricing posted on the Amazon RDS pricing page. API Version 2014-10-31 189 Amazon Relational Database Service User Guide Reserved DB Instances Reserved DB Instances Using reserved DB instances, you can reserve a DB instance for a one- or three-year term. Reserved DB instances provide you with a significant discount compared to on-demand DB instance pricing. Reserved DB instances are not physical instances, but rather a billing discount applied to the use of certain ondemand DB instances in your account. Discounts for reserved DB instances are tied to instance type and AWS Region. The general process for working with reserved DB instances is: First get information about available reserved DB instance offerings, then purchase a reserved DB instance offering, and finally get information about your existing reserved DB instances. Overview of Reserved DB Instances When you purchase a reserved DB instance in Amazon RDS, you purchase a commitment to getting a discounted rate, on a specific DB instance type, for the duration of the reserved DB instance. To use an Amazon RDS reserved DB instance, you create a new DB instance just like you do for an on-demand instance. The new DB instance that you create must match the specifications of the reserved DB instance. If the specifications of the new DB instance match an existing reserved DB instance for your account, you are billed at the discounted rate offered for the reserved DB instance. Otherwise, the DB instance is billed at an on-demand rate. For more information about reserved DB instances, including pricing, see Amazon RDS Reserved Instances. Offering Types Reserved DB instances are available in three varieties—No Upfront, Partial Upfront, and All Upfront— that let you optimize your Amazon RDS costs based on your expected usage. No Upfront This option provides access to a reserved DB instance without requiring an upfront payment. Your No Upfront reserved DB instance bills a discounted hourly rate for every hour within the term, regardless of usage, and no upfront payment is required. This option is only available as a one-year reservation. Partial Upfront This option requires a part of the reserved DB instance to be paid upfront. The remaining hours in the term are billed at a discounted hourly rate, regardless of usage. This option is the replacement for the previous Heavy Utilization option. All Upfront Full payment is made at the start of the term, with no other costs incurred for the remainder of the term regardless of the number of hours used. If you are using consolidated billing, all the accounts in the organization are treated as one account. This means that all accounts in the organization can receive the hourly cost benefit of reserved DB instances that are purchased by any other account. For more information about consolidated billing, see Amazon RDS Reserved DB Instances in the AWS Billing and Cost Management User Guide. Size-Flexible Reserved DB Instances When you purchase a reserved DB instance, one thing that you specify is the instance class, for example db.m4.large. For more information about instance classes, see DB Instance Class (p. 80). If you have a DB instance, and you need to scale it to larger capacity, your reserved DB instance is automatically applied to your scaled DB instance. That is, your reserved DB instances are automatically API Version 2014-10-31 190 Amazon Relational Database Service User Guide Reserved DB Instances applied across all DB instance class sizes. Size-flexible reserved DB instances are available for DB instances with the same AWS Region, database engine, and instance family. Reserved DB instance benefits also apply for both Multi-AZ and Single-AZ configurations. Size-flexible reserved DB instances are available for the following database engines: • MariaDB • MySQL • Oracle, Bring Your Own License • PostgreSQL You can compare usage for different reserved DB instance sizes by using normalized units. For example, one unit of usage on two db.m3.large DB instances is equivalent to eight normalized units of usage on one db.m3.small. The following table shows the number of normalized units for each DB instance size. Instance Size Single-AZ Normalized Units Multi-AZ Normalized Units micro 0.5 1 small 1 2 medium 2 4 large 4 8 xlarge 8 16 2xlarge 16 32 4xlarge 32 64 8xlarge 64 128 10xlarge 80 160 16xlarge 128 256 For example, suppose that you purchase a db.t2.medium reserved DB instance, and you have two running db.t2.small DB instances in your account in the same AWS Region. In this case, the billing benefit is applied in full to both instances. API Version 2014-10-31 191 Amazon Relational Database Service User Guide Reserved DB Instances Alternatively, if you have one db.t2.large instance running in your account in the same AWS Region, the billing benefit is applied to 50 percent of the usage of the DB instance. Reserved DB Instance Billing Example The price for a reserved DB instance doesn't include regular costs associated with storage, backups, and I/O. The following example illustrates the total cost per month for a reserved DB instance: • An Amazon RDS MySQL reserved Single-AZ db.r4.large DB instance class in US East (N. Virginia) with the No Upfront option at a cost of $0.12 for the instance, or $90 per month • 400 GiB of General Purpose SSD (gp2) storage at a cost of 0.115 per GiB per month, or $45.60 per month • 600 GiB of backup storage at $0.095, or $19 per month (400 GiB free) Add all of these options ($90 + $45.60 + $19) with the reserved DB instance, and the total cost per month is $154.60. If you chose to use an on-demand DB instance instead of a reserved DB instance, an Amazon RDS MySQL Single-AZ db.r4.large DB instance class in US East (N. Virginia) costs $0.1386 per hour, or $101.18 per month. So, for an on-demand DB instance, add all of these options ($101.18 + $45.60 + $19), and the total cost per month is $165.78. Note The prices in this example are sample prices and might not match actual prices. For Amazon RDS pricing information, see the Amazon RDS product page. Deleting a Reserved DB Instance The terms for a reserved DB instance involve a one-year or three-year commitment. You can't cancel a reserved DB instance. However, you can delete a DB instance that is covered by a reserved DB instance discount. The process for deleting a DB instance that is covered by a reserved DB instance discount is the same as for any other DB instance. Your upfront payment for a reserved DB instance reserves the resources for your use. Because these resources are reserved for you, you are billed for the resources regardless of whether you use them. If you delete a DB instance that is covered by a reserved DB instance discount, you can launch another DB instance with compatible specifications. In this case, you continue to get the discounted rate during the reservation term (one or three years). API Version 2014-10-31 192 Amazon Relational Database Service User Guide Reserved DB Instances Console You can use the AWS Management Console to work with reserved DB instances as shown in the following procedures. To get pricing and information about available reserved DB instance offerings 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Reserved instances. 3. Choose Purchase Reserved DB Instance. 4. For Product description, choose the DB engine and licensing type. 5. For DB instance class, choose the DB instance class. 6. For Multi-AZ deployment, choose whether you want a Multi-AZ deployment. 7. For Term, choose the length of time you want the DB instance reserved. 8. For Offering type, choose the offering type. After you select the offering type, you can see the pricing information. Important Choose Cancel to avoid purchasing the reserved DB instance and incurring any charges. After you have information about the available reserved DB instance offerings, you can use the information to purchase an offering as shown in the following procedure. To purchase a reserved DB instance 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Reserved instances. 3. Choose Purchase Reserved DB Instance. 4. For Product description, choose the DB engine and licensing type. 5. For DB instance class, choose the DB instance class. 6. For Multi-AZ deployment, choose whether you want a Multi-AZ deployment. 7. For Term, choose the length of time you want the DB instance reserved. 8. For Offering type, choose the offering type. After you choose the offering type, you can see the pricing information, as shown following. API Version 2014-10-31 193 Amazon Relational Database Service User Guide Reserved DB Instances API Version 2014-10-31 194 Amazon Relational Database Service User Guide Reserved DB Instances 9. (Optional) You can assign your own identifier to the reserved DB instances that you purchase to help you track them. For Reserved Id, type an identifier for your reserved DB instance. 10. Choose Continue. The Purchase Reserved DB Instance dialog box appears, with a summary of the reserved DB instance attributes that you've selected and the payment due, as shown following. API Version 2014-10-31 195 Amazon Relational Database Service User Guide Reserved DB Instances 11. On the confirmation page, review your reserved DB instance. If the information is correct, choose Purchase to purchase the reserved DB instance. Alternatively, choose Back to edit your reserved DB instance. After you have purchased reserved DB instances, you can get information about your reserved DB instances as shown in the following procedure. To get information about reserved DB instances for your AWS account 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the Navigation pane, choose Reserved instances. The reserved DB instances for your account appear. To see detailed information about a particular reserved DB instance, choose that instance in the list. You can then see detailed information about that instance in the detail pane at the bottom of the console. AWS CLI You can use the AWS CLI to work with reserved DB instances as shown in the following examples. Example Get Available Reserved DB Instance Offerings To get information about available reserved DB instance offerings, call the AWS CLI command describe-reserved-db-instances-offerings. aws rds describe-reserved-db-instances-offerings This call returns output similar to the following: OFFERING OfferingId Class Price Usage Price Description Offering Type OFFERING 438012d3-4052-4cc7-b2e3-8d3372e0e706 db.m1.large USD 0.368 USD mysql Partial Upfront OFFERING 649fd0c8-cf6d-47a0-bfa6-060f8e75e95f db.m1.small USD 0.046 USD mysql Partial Upfront OFFERING 123456cd-ab1c-47a0-bfa6-12345667232f db.m1.small USD 0.00 USD mysql All Upfront Recurring Charges: Amount Currency Frequency Recurring Charges: 0.123 USD Hourly OFFERING 123456cd-ab1c-37a0-bfa6-12345667232d db.m1.large USD 0.00 USD mysql All Upfront Recurring Charges: Amount Currency Frequency Recurring Charges: 1.25 USD Hourly OFFERING 123456cd-ab1c-17d0-bfa6-12345667234e db.m1.xlarge USD 2.42 USD mysql No Upfront Multi-AZ Duration Fixed y 1y 1820.00 n 1y 227.50 n 1y 162.00 y 1y 700.00 n 1y 4242.00 After you have information about the available reserved DB instance offerings, you can use the information to purchase an offering as shown in the following example. Example Purchase a Reserved DB Instance To purchase a reserved DB instance, use the AWS CLI command purchase-reserved-db-instancesoffering with the following parameters: API Version 2014-10-31 196 Amazon Relational Database Service User Guide Reserved DB Instances • --reserved-db-instances-offering-id – the id of the offering that you want to purchase. See the preceding example to get the offering ID. • --reserved-db-instance-id – you can assign your own identifier to the reserved DB instances that you purchase to help you track them. The following example purchases the reserved DB instance offering with ID 649fd0c8-cf6d-47a0bfa6-060f8e75e95f, and assigns the identifier of MyReservation. For Linux, OS X, or Unix: aws rds purchase-reserved-db-instances-offering \ --reserved-db-instances-offering-id 649fd0c8-cf6d-47a0-bfa6-060f8e75e95f \ --reserved-db-instance-id MyReservation For Windows: aws rds purchase-reserved-db-instances-offering ^ --reserved-db-instances-offering-id 649fd0c8-cf6d-47a0-bfa6-060f8e75e95f ^ --reserved-db-instance-id MyReservation The command returns output similar to the following: RESERVATION ReservationId Class Multi-AZ Start Time Duration Fixed Price Usage Price Count State Description Offering Type RESERVATION MyReservation db.m1.small y 2011-12-19T00:30:23.247Z 1y 455.00 USD 0.092 USD 1 payment-pending mysql Partial Upfront After you have purchased reserved DB instances, you can get information about your reserved DB instances as shown in the following example. Example Get Your Reserved DB Instances To get information about reserved DB instances for your AWS account, call the AWS CLI command describe-reserved-db-instances. aws rds describe-reserved-db-instances The command returns output similar to the following: RESERVATION ReservationId Class Multi-AZ Start Time Fixed Price Usage Price Count State Description Offering Type RESERVATION MyReservation db.m1.small y 2011-12-09T23:37:44.720Z 455.00 USD 0.092 USD 1 retired mysql Partial Upfront Duration 1y RDS API You can use the RDS API to work with reserved DB instances as shown in the following examples. Example Get Available Reserved DB Instance Offerings To get information about available reserved DB instance offerings, call the Amazon RDS API function DescribeReservedDBInstancesOfferings. https://rds.us-east-1.amazonaws.com/ ?Action=DescribeReservedDBInstancesOfferings &SignatureMethod=HmacSHA256 &SignatureVersion=4 API Version 2014-10-31 197 Amazon Relational Database Service User Guide Reserved DB Instances &Version=2014-09-01 &X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIADQKE4SARGYLE/20140411/us-east-1/rds/aws4_request &X-Amz-Date=20140411T203327Z &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date &X-Amz-Signature=545f04acffeb4b80d2e778526b1c9da79d0b3097151c24f28e83e851d65422e2 This call returns output similar to the following: 31536000 Partial Upfront USD 1820.0 mysql 0.368 true 438012d3-4052-4cc7-b2e3-8d3372e0e706 db.m1.large 31536000 Partial Upfront USD 227.5 mysql 0.046 false 649fd0c8-cf6d-47a0-bfa6-060f8e75e95f db.m1.small 5e4ec40b-2978-11e1-9e6d-771388d6ed6b After you have information about the available reserved DB instance offerings, you can use the information to purchase an offering as shown in the following example. Example Purchase a Reserved DB Instance To purchase a reserved DB instance, call the Amazon RDS API action PurchaseReservedDBInstancesOffering with the following parameters: • --reserved-db-instances-offering-id – the id of the offering that you want to purchase. See the preceding example to get the offering ID. • --reserved-db-instance-id – you can assign your own identifier to the reserved DB instances that you purchase to help you track them. The following example purchases the reserved DB instance offering with ID 649fd0c8-cf6d-47a0bfa6-060f8e75e95f, and assigns the identifier of MyReservation. API Version 2014-10-31 198 Amazon Relational Database Service User Guide Reserved DB Instances https://rds.us-east-1.amazonaws.com/ ?Action=PurchaseReservedDBInstancesOffering &ReservedDBInstanceId=MyReservation &ReservedDBInstancesOfferingId=438012d3-4052-4cc7-b2e3-8d3372e0e706 &DBInstanceCount=10 &SignatureMethod=HmacSHA256 &SignatureVersion=4 &Version=2014-09-01 &X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIADQKE4SARGYLE/20140415/us-east-1/rds/aws4_request &X-Amz-Date=20140415T232655Z &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date &X-Amz-Signature=c2ac761e8c8f54a8c0727f5a87ad0a766fbb0024510b9aa34ea6d1f7df52fb11 This call returns output similar to the following: Partial Upfront USD mysql 649fd0c8-cf6d-47a0-bfa6-060f8e75e95f true payment-pending MyReservation 10 2011-12-18T23:24:56.577Z 31536000 123.0 0.123 db.m1.small 7f099901-29cf-11e1-bd06-6fe008f046c3 After you have purchased reserved DB instances, you can get information about your reserved DB instances as shown in the following example. Example Get Your Reserved DB Instances To get information about reserved DB instances for your AWS account, call the Amazon RDS API action DescribeReservedDBInstances. https://rds.us-west-2.amazonaws.com/ ?Action=DescribeReservedDBInstances &SignatureMethod=HmacSHA256 &SignatureVersion=4 &Version=2014-09-01 &X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIADQKE4SARGYLE/20140420/us-west-2/rds/aws4_request &X-Amz-Date=20140420T162211Z &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date &X-Amz-Signature=3312d17a4c43bcd209bc22a0778dd23e73f8434254abbd7ac53b89ade3dae88e The API returns output similar to the following: API Version 2014-10-31 199 Amazon Relational Database Service User Guide Reserved DB Instances Partial Upfront USD mysql 649fd0c8-cf6d-47a0-bfa6-060f8e75e95f false payment-failed MyReservation 1 2010-12-15T00:25:14.131Z 31536000 227.5 0.046 db.m1.small Partial Upfront USD mysql 649fd0c8-cf6d-47a0-bfa6-060f8e75e95f false payment-failed MyReservation 1 2010-12-15T01:07:22.275Z 31536000 227.5 0.046 db.m1.small 23400d50-2978-11e1-9e6d-771388d6ed6b API Version 2014-10-31 200 Amazon Relational Database Service User Guide Backing Up and Restoring Amazon RDS DB Instances This section shows how to back up and restore a DB instance. Topics • Working With Backups (p. 202) • Creating a DB Snapshot (p. 210) • Restoring from a DB Snapshot (p. 212) • Copying a Snapshot (p. 215) • Sharing a DB Snapshot (p. 224) • Restoring a DB Instance to a Specified Time (p. 231) • Tutorial: Restore a DB Instance from a DB Snapshot (p. 233) API Version 2014-10-31 201 Amazon Relational Database Service User Guide Working With Backups Working With Backups Amazon RDS creates and saves automated backups of your DB instance. Amazon RDS creates a storage volume snapshot of your DB instance, backing up the entire DB instance and not just individual databases. Amazon RDS creates automated backups of your DB instance during the backup window of your DB instance. Amazon RDS saves the automated backups of your DB instance according to the backup retention period that you specify. If necessary, you can recover your database to any point in time during the backup retention period. Automated backups follow these rules: • Your DB instance must be in the ACTIVE state for automated backups to occur. Automated backups don't occur while your DB instance is in a state other than ACTIVE, for example STORAGE_FULL. • Automated backups and automated snapshots don't occur while a copy is executing in the same region for the same DB instance. You can also back up your DB instance manually, by manually creating a DB snapshot. For more information about creating a DB snapshot, see Creating a DB Snapshot (p. 210). The first snapshot of a DB instance contains the data for the full DB instance. Subsequent snapshots of the same DB instance are incremental, which means that only the data that has changed after your most recent snapshot is saved. You can copy both automatic and manual DB snapshots, and share manual DB snapshots. For more information about copying a DB snapshot, see Copying a Snapshot (p. 215). For more information about sharing a DB snapshot, see Sharing a DB Snapshot (p. 224). Backup Storage Your Amazon RDS backup storage for each region is composed of the automated backups and manual DB snapshots for that region. Your backup storage is equivalent to the sum of the database storage for all instances in that region. Moving a DB snapshot to another region increases the backup storage in the destination region. For more information about backup storage costs, see Amazon RDS Pricing. If you chose to retain automated backups when you delete a DB instance, the automated backups are saved for the full retention period. If you don't choose Retain automated backups when you delete a DB instance, all automated backups are deleted with the DB instance. After they are deleted, the automated backups can't be recovered. If you choose to have Amazon RDS create a final DB snapshot before it deletes your DB instance, you can use that to recover your DB instance. Or you can use a previously created manual snapshot. Manual snapshots are not deleted. Backup Window Automated backups occur daily during the preferred backup window. If the backup requires more time than allotted to the backup window, the backup continues after the window ends, until it finishes. The backup window can't overlap with the weekly maintenance window for the DB instance. During the automatic backup window, storage I/O might be suspended briefly while the backup process initializes (typically under a few seconds). You might experience elevated latencies for a few minutes during backups for Multi-AZ deployments. For MariaDB, MySQL, Oracle, and PostgreSQL, I/O activity is not suspended on your primary during backup for Multi-AZ deployments, because the backup is taken from the standby. For SQL Server, I/O activity is suspended briefly during backup for Multi-AZ deployments. API Version 2014-10-31 202 Amazon Relational Database Service User Guide Backup Retention Period If you don't specify a preferred backup window when you create the DB instance, Amazon RDS assigns a default 30-minute backup window. This window is selected at random from an 8-hour block of time for each AWS Region. The following table lists the time blocks for each region from which the default backups windows are assigned. Region Time Block US West (Oregon) Region 06:00–14:00 UTC US West (N. California) Region 06:00–14:00 UTC US East (Ohio) Region 03:00–11:00 UTC US East (N. Virginia) Region 03:00–11:00 UTC Asia Pacific (Mumbai) Region 16:30–00:30 UTC Asia Pacific (Seoul) Region 13:00–21:00 UTC Asia Pacific (Singapore) Region 14:00–22:00 UTC Asia Pacific (Sydney) Region 12:00–20:00 UTC Asia Pacific (Tokyo) Region 13:00–21:00 UTC Canada (Central) Region 06:29–14:29 UTC EU (Frankfurt) Region 20:00–04:00 UTC EU (Ireland) Region 22:00–06:00 UTC EU (London) Region 06:00–14:00 UTC South America (São Paulo) Region 23:00–07:00 UTC AWS GovCloud (US-West) 03:00–11:00 UTC Backup Retention Period You can set the backup retention period when you create a DB instance. If you don't set the backup retention period, the default backup retention period is one day if you create the DB instance using the Amazon RDS API or the AWS CLI. The default backup retention period is seven days if you create the DB instance using the console. After you create a DB instance, you can modify the backup retention period. You can set the backup retention period to between 0 and 35 days. Setting the backup retention period to 0 disables automated backups. Manual snapshot limits (100 per region) do not apply to automated backups. Important An outage occurs if you change the backup retention period from 0 to a non-zero value or from a non-zero value to 0. Disabling Automated Backups You might want to temporarily disable automated backups in certain situations; for example, while loading large amounts of data. API Version 2014-10-31 203 Amazon Relational Database Service User Guide Disabling Automated Backups Important We highly discourage disabling automated backups because it disables point-in-time recovery. Disabling automatic backups for a DB instance deletes all existing automated backups for the instance. If you disable and then re-enable automated backups, you are only able to restore starting from the time you re-enabled automated backups. In this example, you disable automated backups for a DB instance named mydbinstance by setting the backup retention parameter to 0. Console To disable automated backups immediately 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose DB Instances, and then select the DB instance that you want to modify. 3. Choose Instance Actions, and then choose Modify. The Modify DB Instance window appears. 4. For Backup Retention Period, choose 0. 5. Select Apply Immediately. 6. Choose Continue. 7. On the confirmation page, choose Modify DB Instance to save your changes and disable automated backups. AWS CLI To disable automated backups immediately, use the modify-db-instance command and set the backup retention period to 0 with --apply-immediately. Example The following example immediately disabled automatic backups. For Linux, OS X, or Unix: aws rds modify-db-instance \ --db-instance-identifier mydbinstance \ --backup-retention-period 0 \ --apply-immediately For Windows: aws rds modify-db-instance ^ --db-instance-identifier mydbinstance ^ --backup-retention-period 0 ^ --apply-immediately To know when the modification is in effect, call describe-db-instances for the DB instance until the value for backup retention period is 0 and mydbinstance status is available. aws rds describe-db-instances --db-instance-identifier mydbinstance API Version 2014-10-31 204 Amazon Relational Database Service User Guide Enabling Automated Backups RDS API To disable automated backups immediately, call the ModifyDBInstance action with the following parameters: • DBInstanceIdentifier = mydbinstance • BackupRetentionPeriod = 0 Example https://rds.amazonaws.com/ ?Action=ModifyDBInstance &DBInstanceIdentifier=mydbinstance &BackupRetentionPeriod=0 &SignatureVersion=2 &SignatureMethod=HmacSHA256 &Timestamp=2009-10-14T17%3A48%3A21.746Z &AWSAccessKeyId= &Signature= Enabling Automated Backups If your DB instance doesn't have automated backups enabled, you can enable them at any time. You enable automated backups by setting the backup retention period to a positive non-zero value. When automated backups are enabled, your RDS instance and database is taken offline and a backup is immediately created. In this example, you enable automated backups for a DB instance named mydbinstance by setting the backup retention period to a positive non-zero value (in this case, 3). Console To enable automated backups immediately 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose DB Instances, and then select the DB instance that you want to modify. 3. 4. 5. Choose Instance Actions, and then choose Modify. The Modify DB Instance page appears. For Backup Retention Period, choose a positive non-zero value, for example 3. Select Apply Immediately. 6. 7. Choose Continue. On the confirmation page, choose Modify DB Instance to save your changes and enable automated backups. AWS CLI To enable automated backups immediately, use the AWS CLI modify-db-instance command. In this example, we enable automated backups by setting the backup retention period to three days. Include the following parameters: • --db-instance-identifier API Version 2014-10-31 205 Amazon Relational Database Service User Guide Retaining Automated Backups • --backup-retention-period • --apply-immediately or --no-apply-immediately Example For Linux, OS X, or Unix: aws rds modify-db-instance \ --db-instance-identifier mydbinstance --backup-retention-period 3 \ --apply-immediately \ For Windows: aws rds modify-db-instance ^ --db-instance-identifier mydbinstance --backup-retention-period 3 ^ --apply-immediately ^ RDS API To enable automated backups immediately, use the RDS API ModifyDBInstance operation. In this example, we enable automated backups by setting the backup retention period to three days. Include the following parameters: • DBInstanceIdentifier • BackupRetentionPeriod • ApplyImmediately = true Example https://rds.amazonaws.com/ ?Action=ModifyDBInstance &DBInstanceIdentifier=mydbinstance &BackupRetentionPeriod=3 &ApplyImmediately=true &SignatureVersion=2 &SignatureMethod=HmacSHA256 &Timestamp=2009-10-14T17%3A48%3A21.746Z &AWSAccessKeyId= &Signature= Retaining Automated Backups When you delete a DB instance, you can retain automated backups. Retained automated backups contain system snapshots and transaction logs from a DB instance. They also include your DB instance properties like allocated storage and DB instance class, which are required to restore it to an active instance. You can retain automated backups for RDS instances running MySQL, MariaDB, PostgreSQL, Oracle, and Microsoft SQL Server engines. API Version 2014-10-31 206 Amazon Relational Database Service User Guide Retaining Automated Backups You can restore or remove retained automated backups using the AWS Management Console, RDS API, and AWS CLI. Retention Period The system snapshots and transaction logs in a retained automated backup expire the same way that they expire for the source DB instance. Because there are no new snapshots or logs created for this instance, the retained automated backups eventually expire completely. Effectively, they live as long their last system snapshot would have done, based on the settings for retention period the source instance had when you deleted it. Retained automated backups are removed by the system after their last system snapshot expires. You can remove a retained automated backup in the same way that you can delete a DB instance. You can remove retained automated backups using the console or the RDS API operationDeleteDBInstanceAutomatedBackup. Final snapshots are independent of retained automated backups. We strongly suggest that you take a final snapshot even if you retain automated backups, because the retained automated backups eventually expire. The final snapshot doesn't expire. Restoration To view your retained automated backups, switch to the automated backups page. You can view individual snapshots associated with a retained automated backup on the database snapshots page in the console. Alternatively, you can describe individual snapshots associated with a retained automated backup. From there, you can restore a DB instance directly from one of those snapshots. Restored DB instances are automatically associated with the default parameter and option groups. However, you can apply a custom parameter group and option group by specifying them during a restore. In this example, you restore a DB instance to a point in time using the retained automated backup. First, you describe your retained automated backups, so you can see which of them to restore. To describe your retained automated backups using the RDS API, call the DescribeDBInstanceAutomatedBackups action with one of the following parameters: • DBInstanceIdentifier • DbiResourceId aws rds describe-db-instance-automated-backups --db-instanceidentifier DBInstanceIdentifier OR aws rds describe-db-instance-automated-backups --dbi-resource-idDbiResourceId Next, to restore your retained automated backup to a point in time, using the RDS API, call the RestoreDBInstanceToPointInTime action with the following parameters: • SourceDbiResourceId • TargetDBInstanceIdentifier aws rds restore-db-instance-to-point-in-time --source-dbi-resource-id SourceDbiResourceId --target-db-instance-identifier TargetDBInstanceIdentifier --use-latest-restorable-time API Version 2014-10-31 207 Amazon Relational Database Service User Guide Automated Backups with Unsupported MySQL Storage Engines Retention Costs The cost of a retained automated backup is the cost of total storage of the system snapshots that are associated with it. There is no additional charge for transaction logs or instance metadata. All other pricing rules for backups apply to restorable instances. For example, suppose that your total allocated storage of running instances is 100 GB. Suppose also that you have 50 GB of manual snapshots plus 75 GB of system snapshots associated with a retained automated backup. In this case, you are charged only for the additional 25 GB of backup storage, like this: (50 GB + 75 GB) – 100 GB = 25 GB. Limitations and Recommendations The following limitations apply to retained automated backups: • The maximum number of retained automated backups in one region is 20. It's not included in the DB instances limit. You can have 20 running DB instances and an additional 20 retained automated backups at the same time. • Retained automated backups don't contain information about parameters or option groups. • You can restore a deleted instance to a point in time that is within the retention period at the time of delete. • A retained automated backup can't be modified because it consists of system backups, transaction logs, and the DB instance properties that existed at the time you deleted the source instance. Automated Backups with Unsupported MySQL Storage Engines For the MySQL DB engine, automated backups are only supported for the InnoDB storage engine. Use of these features with other MySQL storage engines, including MyISAM, can lead to unreliable behavior while restoring from backups. Specifically, since storage engines like MyISAM don't support reliable crash recovery, your tables can be corrupted in the event of a crash. For this reason, we encourage you to use the InnoDB storage engine. • To convert existing MyISAM tables to InnoDB tables, you can use the ALTER TABLE command, for example: ALTER TABLE table_name ENGINE=innodb, ALGORITHM=COPY; • If you choose to use MyISAM, you can attempt to manually repair tables that become damaged after a crash by using the REPAIR command. For more information, see REPAIR TABLE Syntax in the MySQL documentation. However, as noted in the MySQL documentation, there is a good chance that you might not be able to recover all your data. • If you want to take a snapshot of your MyISAM tables before restoring, follow these steps: 1. Stop all activity to your MyISAM tables (that is, close all sessions). You can close all sessions by calling the mysql.rds_kill command for each process that is returned from the SHOW FULL PROCESSLIST command. 2. Lock and flush each of your MyISAM tables. For example, the following commands lock and flush two tables named myisam_table1 and myisam_table2: mysql> FLUSH TABLES myisam_table, myisam_table2 WITH READ LOCK; 3. Create a snapshot of your DB instance. When the snapshot has completed, release the locks and resume activity on the MyISAM tables. You can release the locks on your tables using the following command: API Version 2014-10-31 208 Amazon Relational Database Service User Guide Automated Backups with Unsupported MariaDB Storage Engines mysql> UNLOCK TABLES; These steps force MyISAM to flush data stored in memory to disk, which ensures a clean start when you restore from a DB snapshot. For more information on creating a DB snapshot, see Creating a DB Snapshot (p. 210). Automated Backups with Unsupported MariaDB Storage Engines For the MariaDB DB engine, automated backups are only supported with the InnoDB storage engine (version 10.2 and later) and XtraDB storage engine (versions 10.0 and 10.1). Use of these features with other MariaDB storage engines, including Aria, might lead to unreliable behavior while restoring from backups. Even though Aria is a crash-resistant alternative to MyISAM, your tables can still be corrupted in the event of a crash. For this reason, we encourage you to use the XtraDB storage engine. • To convert existing Aria tables to InnoDB tables, you can use the ALTER TABLE command. For example: ALTER TABLE table_name ENGINE=innodb, ALGORITHM=COPY; • To convert existing Aria tables to XtraDB tables, you can use the ALTER TABLE command. For example: ALTER TABLE table_name ENGINE=xtradb, ALGORITHM=COPY; • If you choose to use Aria, you can attempt to manually repair tables that become damaged after a crash by using the REPAIR TABLE command. For more information, see http://mariadb.com/kb/en/ mariadb/repair-table/. • If you want to take a snapshot of your Aria tables before restoring, follow these steps: 1. Stop all activity to your Aria tables (that is, close all sessions). 2. Lock and flush each of your Aria tables. 3. Create a snapshot of your DB instance. When the snapshot has completed, release the locks and resume activity on the Aria tables. These steps force Aria to flush data stored in memory to disk, thereby ensuring a clean start when you restore from a DB snapshot. API Version 2014-10-31 209 Amazon Relational Database Service User Guide Creating a DB Snapshot Creating a DB Snapshot Amazon RDS creates a storage volume snapshot of your DB instance, backing up the entire DB instance and not just individual databases. Creating this DB snapshot on a Single-AZ DB instance results in a brief I/O suspension that can last from a few seconds to a few minutes, depending on the size and class of your DB instance. Multi-AZ DB instances are not affected by this I/O suspension since the backup is taken on the standby. When you create a DB snapshot, you need to identify which DB instance you are going to back up, and then give your DB snapshot a name so you can restore from it later. The amount of time it takes to create a snapshot varies with the size your databases. Since the snapshot includes the entire storage volume, the size of files, such as temporary files, also affects the amount of time it takes to create the snapshot. You can create a DB snapshot using the AWS Management Console, the AWS CLI, or the RDS API. AWS Management Console To create a DB snapshot 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Instances. 3. In the list of DB instances, select the DB instance for which you want to take a snapshot. 4. Choose Instance actions, and then choose Take snapshot. The Take DB Snapshot window appears. 5. Type the name of the snapshot in the Snapshot Name box. 6. Choose Take Snapshot. API Version 2014-10-31 210 Amazon Relational Database Service User Guide Creating a DB Snapshot CLI When you create a DB snapshot using the AWS CLI, you need to identify which DB instance you are going to back up, and then give your DB snapshot a name so you can restore from it later. You can do this by using the AWS CLI create-db-snapshot command with the following parameters: • --db-instance-identifier • --db-snapshot-identifier In this example, you create a DB snapshot called mydbsnapshot for a DB instance called mydbinstance. Example For Linux, OS X, or Unix: aws rds create-db-snapshot / --db-instance-identifier mydbinstance / --db-snapshot-identifier mydbsnapshot For Windows: aws rds create-db-snapshot ^ --db-instance-identifier mydbinstance ^ --db-snapshot-identifier mydbsnapshot API When you create a DB snapshot using the Amazon RDS API, you need to identify which DB instance you are going to back up, and then give your DB snapshot a name so you can restore from it later. You can do this by using the Amazon RDS API CreateDBSnapshot command with the following parameters: • DBInstanceIdentifier • DBSnapshotIdentifier API Version 2014-10-31 211 Amazon Relational Database Service User Guide Restoring from a DB Snapshot Restoring from a DB Snapshot Amazon RDS creates a storage volume snapshot of your DB instance, backing up the entire DB instance and not just individual databases. You can create a DB instance by restoring from this DB snapshot. When you restore the DB instance, you provide the name of the DB snapshot to restore from, and then provide a name for the new DB instance that is created from the restore. You can't restore from a DB snapshot to an existing DB instance; a new DB instance is created when you restore. You can restore a DB instance and use a different storage type than the source DB snapshot. In this case, the restoration process is slower because of the additional work required to migrate the data to the new storage type. If you restore to or from Magnetic (Standard) storage, the migration process is the slowest. That's because Magnetic storage doesn't have the IOPS capability of Provisioned IOPS or General Purpose (SSD) storage. Note You can't restore a DB instance from a DB snapshot that is both shared and encrypted. Instead, you can make a copy of the DB snapshot and restore the DB instance from the copy. Parameter Group Considerations We recommend that you retain the parameter group for any DB snapshots you create, so that you can associate your restored DB instance with the correct parameter group. You can specify the parameter group when you restore the DB instance. Security Group Considerations When you restore a DB instance, the default security group is associated with the restored instance. As soon as the restore is complete and your new DB instance is available, you must associate any custom security groups used by the instance you restored from. You must apply these changes by using the RDS console's Modify command, the ModifyDBInstance Amazon RDS API, or the AWS CLI modify-dbinstance command. Option Group Considerations When you restore a DB instance, the option group associated with the DB snapshot is associated with the restored DB instance after it is created. For example, if the DB snapshot you are restoring from uses Oracle Transparent Data Encryption, the restored DB instance will use the same option group. When you assign an option group to a DB instance, the option group is also linked to the supported platform the DB instance is on, either VPC or EC2-Classic (non-VPC). If a DB instance is in a VPC, the option group associated with the DB instance is linked to that VPC. This means that you can't use the option group assigned to a DB instance if you attempt to restore the instance into a different VPC or onto a different platform. If you restore a DB instance into a different VPC or onto a different platform, you must either assign the default option group to the instance, assign an option group that is linked to that VPC or platform, or create a new option group and assign it to the DB instance. For persistent or permanent options, when restoring a DB instance into a different VPC you must create a new option group that includes the persistent or permanent option. Microsoft SQL Server Considerations When you restore a Microsoft SQL Server DB snapshot to a new instance, you can always restore to the same edition as your snapshot. In some cases, you can also change the edition of the DB instance. The following are the limitations when you change editions: • The DB snapshot must have enough storage allocated for the new edition. API Version 2014-10-31 212 Amazon Relational Database Service User Guide Oracle • Only the following edition changes are supported: • From Standard Edition to Enterprise Edition • From Web Edition to Standard Edition or Enterprise Edition • From Express Edition to Web Edition, Standard Edition or Enterprise Edition If you want to change from one edition to a new edition that is not supported by restoring a snapshot, you can try using the native backup and restore feature. SQL Server verifies whether or not your database is compatible with the new edition based on what SQL Server features you have enabled on the database. For more information, see Importing and Exporting SQL Server Databases (p. 523). Oracle Considerations If you use Oracle GoldenGate, always retain the parameter group with the compatible parameter. When you restore a DB instance from a DB snapshot, you must specify the parameter group that has a matching or greater compatible parameter value. You can upgrade a DB snapshot while it is still a DB snapshot, before you restore it. For more information, see Upgrading an Oracle DB Snapshot (p. 769). Restoring from a Snapshot You can restore a DB instance from a DB snapshot using the AWS Management Console, the AWS CLI, or the RDS API. AWS Management Console To restore a DB instance from a DB snapshot 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Snapshots. 3. Choose the DB snapshot that you want to restore from. 4. From the Actions drop-down, choose Restore Snapshot. 5. On the Restore DB Instance page, in the DB Instance Identifier field, type the name for your restored DB instance. 6. Choose Restore DB Instance. 7. If you want to restore the functionality of the DB instance to that of the DB instance that the snapshot was created from, you must modify the DB instance to use the security group. The next steps assume that your DB instance is in a VPC. If your DB instance is not in a VPC, use the EC2 Management Console to locate the security group you need for the DB instance. a. Sign in to the AWS Management Console and open the Amazon VPC console at https:// console.aws.amazon.com/vpc/. b. In the navigation pane, choose Security Groups. c. Select the security group that you want to use for your DB instances. If necessary, add rules to link the security group to a security group for an EC2 instance. For more information, see A DB Instance in a VPC Accessed by an EC2 Instance in the Same VPC (p. 402). CLI To restore a DB instance from a DB snapshot, use the AWS CLI command restore-db-instance-from-dbsnapshot. API Version 2014-10-31 213 Amazon Relational Database Service User Guide Restoring from a Snapshot In this example, you restore from a previously created DB snapshot named mydbsnapshot. You restore to a new DB instance named mynewdbinstance. Example For Linux, OS X, or Unix: aws rds restore-db-instance-from-db-snapshot \ --db-instance-identifier mynewdbinstance \ --db-snapshot-identifier mydbsnapshot For Windows: aws rds restore-db-instance-from-db-snapshot ^ --db-instance-identifier mynewdbinstance ^ --db-snapshot-identifier mydbsnapshot This command returns output similar to the following: DBINSTANCE mynewdbinstance db.m3.large 5.6.40 general-public-license MySQL 50 sa creating 3 n After the DB instance has been restored, you must add the DB instance to the security group used by the DB instance used to create the DB snapshot if you want the same functionality as that of the previous DB instance. API To restore a DB instance from a DB snapshot, call the Amazon RDS API function RestoreDBInstanceFromDBSnapshot with the following parameters: • DBInstanceIdentifier • DBSnapshotIdentifier API Version 2014-10-31 214 Amazon Relational Database Service User Guide Copying a Snapshot Copying a Snapshot With Amazon RDS, you can copy automated or manual DB snapshots. After you copy a snapshot, the copy is a manual snapshot. You can copy a snapshot within the same AWS Region, you can copy a snapshot across AWS Regions, and you can copy a snapshot across AWS accounts. Copying an automated snapshot to another AWS account is a two-step process: You first create a manual snapshot from the automated snapshot, and then you copy the manual snapshot to the other account. Limitations The following are some limitations when you copy snapshots: • You can't copy a snapshot to or from the following AWS Regions: China (Beijing) or China (Ningxia). • You can copy a snapshot between AWS GovCloud (US-East) and AWS GovCloud (US-West), but you can't copy a snapshot between these AWS GovCloud (US) regions and other AWS Regions. • If you delete a source snapshot before the target snapshot becomes available, the snapshot copy may fail. Verify that the target snapshot has a status of AVAILABLE before you delete a source snapshot. • You can have up to five snapshot copy requests in progress to a single destination region per account. • You can't copy a DB snapshot across regions if it was created from an Oracle DB instance that is using AWS CloudHSM Classic to store TDE keys. • Depending on the regions involved and the amount of data to be copied, a cross-region snapshot copy can take hours to complete. If there is a large number of cross-region snapshot copy requests from a given source AWS Region, Amazon RDS might put new cross-region copy requests from that source AWS Region into a queue until some in-progress copies complete. No progress information is displayed about copy requests while they are in the queue. Progress information is displayed when the copy starts. Snapshot Retention Amazon RDS deletes automated snapshots at the end of their retention period, when you disable automated snapshots for a DB instance, or when you delete a DB instance. If you want to keep an automated snapshot for a longer period, copy it to create a manual snapshot, which is retained until you delete it. Amazon RDS storage costs might apply to manual snapshots if they exceed your default storage space. For more information about backup storage costs, see Amazon RDS Pricing. Copying Shared Snapshots You can copy snapshots shared to you by other AWS accounts. If you are copying an encrypted snapshot that has been shared from another AWS account, you must have access to the KMS encryption key that was used to encrypt the snapshot. You can copy a shared DB snapshot across regions, provided that the snapshot is unencrypted. However, if the shared DB snapshot is encrypted, you can only copy it in the same AWS Region. Handling Encryption You can copy a snapshot that has been encrypted using an AWS KMS encryption key. If you copy an encrypted snapshot, the copy of the snapshot must also be encrypted. If you copy an encrypted API Version 2014-10-31 215 Amazon Relational Database Service User Guide Copying Snapshots Across AWS Regions snapshot within the same AWS Region, you can encrypt the copy with the same KMS encryption key as the original snapshot, or you can specify a different KMS encryption key. If you copy an encrypted snapshot across regions, you can't use the same KMS encryption key for the copy as used for the source snapshot, because KMS keys are region-specific. Instead, you must specify a KMS key valid in the destination AWS Region. You can also encrypt a copy of an unencrypted snapshot. This way, you can quickly add encryption to a previously unencrypted DB instance. That is, you can create a snapshot of your DB instance when you are ready to encrypt it, and then create a copy of that snapshot and specify a KMS encryption key to encrypt that snapshot copy. You can then restore an encrypted DB instance from the encrypted snapshot. Copying Snapshots Across AWS Regions When you copy a snapshot to an AWS Region that is different from the source snapshot's AWS Region, the first copy is a full snapshot copy, even if you copy an incremental snapshot. A full snapshot copy contains all of the data and metadata required to restore the DB instance. After the first snapshot copy, you can copy incremental snapshots of the same DB instance to the same destination region. An incremental snapshot contains only the data that has changed after the most recent snapshot of the same DB instance. Incremental snapshot copying is faster and results in lower storage costs than full snapshot copying. Incremental snapshot copying across AWS Regions is supported for both unencrypted and encrypted snapshots. Depending on the AWS Regions involved and the amount of data to be copied, a cross-region snapshot copy can take hours to complete. In some cases, there might be a large number of cross-region snapshot copy requests from a given source AWS Region. In these cases, Amazon RDS might put new cross-region copy requests from that source AWS Region into a queue until some in-progress copies complete. No progress information is displayed about copy requests while they are in the queue. Progress information is displayed when the copy starts. Note When you copy a source snapshot that is a snapshot copy, the copy isn't incremental because the snapshot copy doesn't include the required metadata for incremental copies. Option Group Considerations Option groups are specific to the AWS Region that they are created in, and you can't use an option group from one AWS Region in another AWS Region. When you copy a snapshot across regions, you can specify a new option group for the snapshot. We recommend that you prepare the new option group before you copy the snapshot. In the destination AWS Region, create an option group with the same settings as the original DB instance . If one already exists in the new AWS Region, you can use that one. If you copy a snapshot and you don't specify a new option group for the snapshot, when you restore it the DB instance gets the default option group. To give the new DB instance the same options as the original, you must do the following: 1. In the destination AWS Region, create an option group with the same settings as the original DB instance . If one already exists in the new AWS Region, you can use that one. 2. After you restore the snapshot in the destination AWS Region, modify the new DB instance and add the new or existing option group from the previous step. Parameter Group Considerations When you copy a snapshot across regions, the copy doesn't include the parameter group used by the original DB instance . When you restore a snapshot to create a new DB instance , that DB instance gets API Version 2014-10-31 216 Amazon Relational Database Service User Guide Copying a DB Snapshot the default parameter group for the AWS Region it is created in. To give the new DB instance the same parameters as the original, you must do the following: 1. In the destination AWS Region, create a DB parameter group with the same settings as the original DB instance . If one already exists in the new AWS Region, you can use that one. 2. After you restore the snapshot in the destination AWS Region, modify the new DB instance and add the new or existing parameter group from the previous step. Copying a DB Snapshot Use the procedures in this topic to copy a DB snapshot. For an overview of copying a snapshot, see Copying a Snapshot (p. 215) For each AWS account, you can copy up to five DB snapshots at a time from one AWS Region to another. If you copy a DB snapshot to another AWS Region, you create a manual DB snapshot that is retained in that AWS Region. Copying a DB snapshot out of the source AWS Region incurs Amazon RDS data transfer charges. For more information about data transfer pricing, see Amazon RDS Pricing. After the DB snapshot copy has been created in the new AWS Region, the DB snapshot copy behaves the same as all other DB snapshots in that AWS Region. You can copy a DB snapshot using the AWS Management Console, the AWS CLI, or the RDS API. AWS Management Console This procedure copies an encrypted or unencrypted DB snapshot, in the same AWS Region or across regions, by using the AWS Management Console. To copy a DB snapshot 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Snapshots. 3. Select the DB snapshot that you want to copy. 4. Choose Actions, and then choose Copy Snapshot. The Make Copy of DB Snapshot page appears. API Version 2014-10-31 217 Amazon Relational Database Service User Guide Copying a DB Snapshot 5. (Optional) To copy the DB snapshot to a different AWS Region, for Destination Region, choose the new AWS Region. Note The destination AWS Region must have the same database engine version available as the source AWS Region. 6. For New DB Snapshot Identifier, type the name of the DB snapshot copy. 7. (Optional) For Target Option Group, choose a new option group. Specify this option if you are copying a snapshot from one AWS Region to another, and your DB instance uses a non-default option group. API Version 2014-10-31 218 Amazon Relational Database Service User Guide Copying a DB Snapshot If your source DB instance uses Transparent Data Encryption for Oracle or Microsoft SQL Server, you must specify this option when copying across regions. For more information, see Option Group Considerations (p. 216). 8. (Optional) Select Copy Tags to copy tags and values from the snapshot to the copy of the snapshot. 9. (Optional) For Enable Encryption, choose one of the following options: • Choose Disable encryption if the DB snapshot isn't encrypted and you don't want to encrypt the copy. • Choose Enable encryption if the DB snapshot isn't encrypted but you want to encrypt the copy. In this case, for Master Key, specify the KMS key identifier to use to encrypt the DB snapshot copy. • Choose Enable encryption if the DB snapshot is encrypted. In this case, you must encrypt the copy, so Yes is already selected. For Master Key, specify the KMS key identifier to use to encrypt the DB snapshot copy. 10. Choose Copy Snapshot. CLI You can copy a DB snapshot by using the AWS CLI command copy-db-snapshot. If you are copying the snapshot to a new AWS Region, run the command in the new AWS Region. The following options are used to copy a DB snapshot. Not all options are required for all scenarios. Use the descriptions and the examples that follow to determine which options to use. • --source-db-snapshot-identifier – The identifier for the source DB snapshot. • If the source snapshot is in the same AWS Region as the copy, specify a valid DB snapshot identifier. For example, rds:mysql-instance1-snapshot-20130805. • If the source snapshot is in a different AWS Region than the copy, specify a valid DB snapshot ARN. For example, arn:aws:rds:us-west-2:123456789012:snapshot:mysql-instance1snapshot-20130805. • If you are copying from a shared manual DB snapshot, this parameter must be the Amazon Resource Name (ARN) of the shared DB snapshot. • If you are copying an encrypted snapshot this parameter must be in the ARN format for the source AWS Region, and must match the SourceDBSnapshotIdentifier in the PreSignedUrl parameter. • --target-db-snapshot-identifier – The identifier for the new copy of the encrypted DB snapshot. • --copy-tags – Include the copy tags option to copy tags and values from the snapshot to the copy of the snapshot. • --option-group-name – The option group to associate with the copy of the snapshot. Specify this option if you are copying a snapshot from one AWS Region to another, and your DB instance uses a non-default option group. If your source DB instance uses Transparent Data Encryption for Oracle or Microsoft SQL Server, you must specify this option when copying across regions. For more information, see Option Group Considerations (p. 216). • --kms-key-id – The AWS KMS key ID for an encrypted DB snapshot. The KMS key ID is the Amazon Resource Name (ARN), KMS key identifier, or the KMS key alias for the KMS encryption key. • If you copy an encrypted DB snapshot from your AWS account, you can specify a value for this parameter to encrypt the copy with a new KMS encryption key. If you don't specify a value for this parameter, then the copy of the DB snapshot is encrypted with the same KMS key as the source DB snapshot. API Version 2014-10-31 219 Amazon Relational Database Service User Guide Copying a DB Snapshot • If you copy an encrypted DB snapshot that is shared from another AWS account, then you must specify a value for this parameter. • If you specify this parameter when you copy an unencrypted snapshot, the copy is encrypted. • If you copy an encrypted snapshot to a different AWS Region, then you must specify a KMS key for the destination AWS Region. KMS encryption keys are specific to the AWS Region that they are created in, and you cannot use encryption keys from one AWS Region in another AWS Region. • --source-region – The ID of the AWS Region of the source DB snapshot. If you copy an encrypted snapshot to a different AWS Region, then you must specify this option. Example From Unencrypted, To Same Region The following code creates a copy of a snapshot, with the new name mydbsnapshotcopy, in the same AWS Region as the source snapshot. When the copy is made, all tags on the original snapshot are copied to the snapshot copy. For Linux, OS X, or Unix: aws rds copy-db-snapshot \ --source-db-snapshot-identifier mysql-instance1-snapshot-20130805 \ --target-db-snapshot-identifier mydbsnapshotcopy \ --copy-tags For Windows: aws rds copy-db-snapshot ^ --source-db-snapshot-identifier mysql-instance1-snapshot-20130805 ^ --target-db-snapshot-identifier mydbsnapshotcopy ^ --copy-tags Example From Unencrypted, Across Regions The following code creates a copy of a snapshot, with the new name mydbsnapshotcopy, in the AWS Region in which the command is run. For Linux, OS X, or Unix: aws rds copy-db-snapshot \ --source-db-snapshot-identifier arn:aws:rds:us-east-1:123456789012:snapshot:mysqlinstance1-snapshot-20130805 \ --target-db-snapshot-identifier mydbsnapshotcopy For Windows: aws rds copy-db-snapshot ^ --source-db-snapshot-identifier arn:aws:rds:us-east-1:123456789012:snapshot:mysqlinstance1-snapshot-20130805 ^ --target-db-snapshot-identifier mydbsnapshotcopy Example From Encrypted, Across Regions The following code example copies an encrypted DB snapshot from the us-west-2 region in the us-east-1 region. Run the command in the us-east-1 region. For Linux, OS X, or Unix: aws rds copy-db-snapshot \ API Version 2014-10-31 220 Amazon Relational Database Service User Guide Copying a DB Snapshot --source-db-snapshot-identifier arn:aws:rds:us-west-2:123456789012:snapshot:mysqlinstance1-snapshot-20161115 \ --target-db-snapshot-identifier mydbsnapshotcopy \ --source-region us-west-2 \ --kms-key-id my-us-east-1-key \ --option-group-name custom-option-group-name For Windows: aws rds copy-db-snapshot ^ --source-db-snapshot-identifier arn:aws:rds:us-west-2:123456789012:snapshot:mysqlinstance1-snapshot-20161115 ^ --target-db-snapshot-identifier mydbsnapshotcopy ^ --source-region us-west-2 ^ --kms-key-id my-us-east-1-key ^ --option-group-name custom-option-group-name API You can copy a DB snapshot by using the Amazon RDS API action CopyDBSnapshot. If you are copying the snapshot to a new AWS Region, perform the action in the new AWS Region. The following parameters are used to copy a DB snapshot. Not all parameters are required for all scenarios. Use the descriptions and the examples that follow to determine which parameters to use. • SourceDBSnapshotIdentifier – The identifier for the source DB snapshot. • If the source snapshot is in the same AWS Region as the copy, specify a valid DB snapshot identifier. For example, rds:mysql-instance1-snapshot-20130805. • If the source snapshot is in a different AWS Region than the copy, specify a valid DB snapshot ARN. For example, arn:aws:rds:us-west-2:123456789012:snapshot:mysql-instance1snapshot-20130805. • If you are copying from a shared manual DB snapshot, this parameter must be the Amazon Resource Name (ARN) of the shared DB snapshot. • If you are copying an encrypted snapshot this parameter must be in the ARN format for the source AWS Region, and must match the SourceDBSnapshotIdentifier in the PreSignedUrl parameter. • TargetDBSnapshotIdentifier – The identifier for the new copy of the encrypted DB snapshot. • CopyTags – Set this parameter to true to copy tags and values from the snapshot to the copy of the snapshot. The default is false. • OptionGroupName – The option group to associate with the copy of the snapshot. Specify this parameter if you are copying a snapshot from one AWS Region to another, and your DB instance uses a non-default option group. If your source DB instance uses Transparent Data Encryption for Oracle or Microsoft SQL Server, you must specify this parameter when copying across regions. For more information, see Option Group Considerations (p. 216). • KmsKeyId – The AWS KMS key ID for an encrypted DB snapshot. The KMS key ID is the Amazon Resource Name (ARN), KMS key identifier, or the KMS key alias for the KMS encryption key. • If you copy an encrypted DB snapshot from your AWS account, you can specify a value for this parameter to encrypt the copy with a new KMS encryption key. If you don't specify a value for this parameter, then the copy of the DB snapshot is encrypted with the same KMS key as the source DB snapshot. • If you copy an encrypted DB snapshot that is shared from another AWS account, then you must specify a value for this parameter. API Version 2014-10-31 221 Amazon Relational Database Service User Guide Copying a DB Snapshot • If you specify this parameter when you copy an unencrypted snapshot, the copy is encrypted. • If you copy an encrypted snapshot to a different AWS Region, then you must specify a KMS key for the destination AWS Region. KMS encryption keys are specific to the AWS Region that they are created in, and you cannot use encryption keys from one AWS Region in another AWS Region. • PreSignedUrl – The URL that contains a Signature Version 4 signed request for the CopyDBSnapshot API action in the source AWS Region that contains the source DB snapshot to copy. You must specify this parameter when you copy an encrypted DB snapshot from another AWS Region by using the Amazon RDS API. You can specify the source region option instead of this parameter when you copy an encrypted DB snapshot from another AWS Region by using the AWS CLI. The presigned URL must be a valid request for the CopyDBSnapshot API action that can be executed in the source AWS Region that contains the encrypted DB snapshot to be copied. The presigned URL request must contain the following parameter values: • DestinationRegion - The AWS Region that the encrypted DB snapshot will be copied to. This AWS Region is the same one where the CopyDBSnapshot action is called that contains this presigned URL. For example, if you copy an encrypted DB snapshot from the us-west-2 region to the us-east-1 region, then you call the CopyDBSnapshot action in the us-east-1 region and provide a presigned URL that contains a call to the CopyDBSnapshot action in the us-west-2 region. For this example, the DestinationRegion in the presigned URL must be set to the us-east-1 region. • KmsKeyId - The KMS key identifier for the key to use to encrypt the copy of the DB snapshot in the destination AWS Region. This is the same identifier for both the CopyDBSnapshot action that is called in the destination AWS Region, and the action contained in the presigned URL. • SourceDBSnapshotIdentifier - The DB snapshot identifier for the encrypted snapshot to be copied. This identifier must be in the Amazon Resource Name (ARN) format for the source AWS Region. For example, if you are copying an encrypted DB snapshot from the us-west-2 region, then your SourceDBSnapshotIdentifier looks like the following example: arn:aws:rds:uswest-2:123456789012:snapshot:mysql-instance1-snapshot-20161115. For more information on Signature Version 4 signed requests, see the following: • Authenticating Requests: Using Query Parameters (AWS Signature Version 4) in the Amazon Simple Storage Service API Reference • Signature Version 4 Signing Process in the AWS General Reference Example From Unencrypted, To Same Region The following code creates a copy of a snapshot, with the new name mydbsnapshotcopy, in the same AWS Region as the source snapshot. When the copy is made, all tags on the original snapshot are copied to the snapshot copy. https://rds.us-west-1.amazonaws.com/ ?Action=CopyDBSnapshot &CopyTags=true &SignatureMethod=HmacSHA256 &SignatureVersion=4 &SourceDBSnapshotIdentifier=mysql-instance1-snapshot-20130805 &TargetDBSnapshotIdentifier=mydbsnapshotcopy &Version=2013-09-09 &X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIADQKE4SARGYLE/20140429/us-west-1/rds/aws4_request &X-Amz-Date=20140429T175351Z &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date &X-Amz-Signature=9164337efa99caf850e874a1cb7ef62f3cea29d0b448b9e0e7c53b288ddffed2 API Version 2014-10-31 222 Amazon Relational Database Service User Guide Copying a DB Snapshot Example From Unencrypted, Across Regions The following code creates a copy of a snapshot, with the new name mydbsnapshotcopy, in the uswest-1 region. https://rds.us-west-1.amazonaws.com/ ?Action=CopyDBSnapshot &SignatureMethod=HmacSHA256 &SignatureVersion=4 &SourceDBSnapshotIdentifier=arn%3Aaws%3Ards%3Aus-east-1%3A123456789012%3Asnapshot%3Amysqlinstance1-snapshot-20130805 &TargetDBSnapshotIdentifier=mydbsnapshotcopy &Version=2013-09-09 &X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIADQKE4SARGYLE/20140429/us-west-1/rds/aws4_request &X-Amz-Date=20140429T175351Z &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date &X-Amz-Signature=9164337efa99caf850e874a1cb7ef62f3cea29d0b448b9e0e7c53b288ddffed2 Example From Encrypted, Across Regions The following code creates a copy of a snapshot, with the new name mydbsnapshotcopy, in the useast-1 region. https://rds.us-east-1.amazonaws.com/ ?Action=CopyDBSnapshot &KmsKeyId=my-us-east-1-key &OptionGroupName=custom-option-group-name &PreSignedUrl=https%253A%252F%252Frds.us-west-2.amazonaws.com%252F %253FAction%253DCopyDBSnapshot %2526DestinationRegion%253Dus-east-1 %2526KmsKeyId%253Dmy-us-east-1-key %2526SourceDBSnapshotIdentifier%253Darn%25253Aaws%25253Ards%25253Auswest-2%25253A123456789012%25253Asnapshot%25253Amysql-instance1-snapshot-20161115 %2526SignatureMethod%253DHmacSHA256 %2526SignatureVersion%253D4 %2526Version%253D2014-10-31 %2526X-Amz-Algorithm%253DAWS4-HMAC-SHA256 %2526X-Amz-Credential%253DAKIADQKE4SARGYLE%252F20161117%252Fus-west-2%252Frds %252Faws4_request %2526X-Amz-Date%253D20161117T215409Z %2526X-Amz-Expires%253D3600 %2526X-Amz-SignedHeaders%253Dcontent-type%253Bhost%253Buser-agent%253Bx-amzcontent-sha256%253Bx-amz-date %2526X-Amz-Signature %253D255a0f17b4e717d3b67fad163c3ec26573b882c03a65523522cf890a67fca613 &SignatureMethod=HmacSHA256 &SignatureVersion=4 &SourceDBSnapshotIdentifier=arn%3Aaws%3Ards%3Aus-west-2%3A123456789012%3Asnapshot %3Amysql-instance1-snapshot-20161115 &TargetDBSnapshotIdentifier=mydbsnapshotcopy &Version=2014-10-31 &X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIADQKE4SARGYLE/20161117/us-east-1/rds/aws4_request &X-Amz-Date=20161117T221704Z &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date &X-Amz-Signature=da4f2da66739d2e722c85fcfd225dc27bba7e2b8dbea8d8612434378e52adccf API Version 2014-10-31 223 Amazon Relational Database Service User Guide Sharing a Snapshot Sharing a DB Snapshot Using Amazon RDS, you can share a manual DB snapshot in the following ways: • Sharing a manual DB snapshot, whether encrypted or unencrypted, enables authorized AWS accounts to copy the snapshot. • Sharing an unencrypted manual DB snapshot enables authorized AWS accounts to directly restore a DB instance from the snapshot instead of taking a copy of it and restoring from that. However, you can't restore a DB instance from a DB snapshot that is both shared and encrypted. Instead, you can make a copy of the DB snapshot and restore the DB instance from the copy. Note To share an automated DB snapshot, create a manual DB snapshot by copying the automated snapshot, and then share that copy. For more information on copying a snapshot, see Copying a Snapshot (p. 215). For more information on restoring a DB instance from a DB snapshot, see Restoring from a DB Snapshot (p. 212). You can share a manual snapshot with up to 20 other AWS accounts. You can also share an unencrypted manual snapshot as public, which makes the snapshot available to all AWS accounts. Take care when sharing a snapshot as public so that none of your private information is included in any of your public snapshots. The following limitations apply when sharing manual snapshots with other AWS accounts: • When you restore a DB instance from a shared snapshot using the AWS Command Line Interface (AWS CLI) or Amazon RDS API, you must specify the Amazon Resource Name (ARN) of the shared snapshot as the snapshot identifier. • You cannot share a DB snapshot that uses an option group with permanent or persistent options. A permanent option cannot be removed from an option group. Option groups with persistent options cannot be removed from a DB instance once the option group has been assigned to the DB instance. The following table lists permanent and persistent options and their related DB engines. Option Name Persistent Permanent DB Engine TDE Yes No Microsoft SQL Server Enterprise Edition TDE Yes Yes Oracle Enterprise Edition TDE_HSM Yes Yes Oracle Enterprise Edition Timezone Yes Yes Oracle Enterprise Edition Oracle Standard Edition Oracle Standard Edition One Oracle Standard Edition Two API Version 2014-10-31 224 Amazon Relational Database Service User Guide Sharing an Encrypted Snapshot Sharing an Encrypted Snapshot You can share DB snapshots that have been encrypted "at rest" using the AES-256 encryption algorithm, as described in Encrypting Amazon RDS Resources (p. 377). To do this, you must take the following steps: 1. Share the AWS Key Management Service (AWS KMS) encryption key that was used to encrypt the snapshot with any accounts that you want to be able to access the snapshot. You can share AWS KMS encryption keys with another AWS account by adding the other account to the KMS key policy. For details on updating a key policy, see Key Policies in the AWS KMS Developer Guide. For an example of creating a key policy, see Allowing Access to an AWS KMS Encryption Key (p. 225) later in this topic. 2. Use the AWS Management Console, AWS CLI, or Amazon RDS API to share the encrypted snapshot with the other accounts. These restrictions apply to sharing encrypted snapshots: • You can't share encrypted snapshots as public. • You can't share Oracle or Microsoft SQL Server snapshots that are encrypted using Transparent Data Encryption (TDE). • You can't share a snapshot that has been encrypted using the default AWS KMS encryption key of the AWS account that shared the snapshot. Allowing Access to an AWS KMS Encryption Key For another AWS account to copy an encrypted DB snapshot shared from your account, the account that you share your snapshot with must have access to the KMS key that encrypted the snapshot. To allow another AWS account access to an AWS KMS key, update the key policy for the KMS key with the ARN of the AWS account that you are sharing to as a Principal in the KMS key policy, and then allow the kms:CreateGrant action. After you have given an AWS account access to your KMS encryption key, to copy your encrypted snapshot, that AWS account must create an AWS Identity and Access Management (IAM) user if it doesn’t already have one. In addition, that AWS account must also attach an IAM policy to that IAM user that allows the IAM user to copy an encrypted DB snapshot using your KMS key. The account must be an IAM user and cannot be a root AWS account identity due to KMS security restrictions. In the following key policy example, user 111122223333 is the owner of the KMS encryption key, and user 444455556666 is the account that the key is being shared with. This updated key policy gives the AWS account access to the KMS key by including the ARN for the root AWS account identity for user 444455556666 as a Principal for the policy, and by allowing the kms:CreateGrant action. { "Id": "key-policy-1", "Version": "2012-10-17", "Statement": [ { "Sid": "Allow use of the key", "Effect": "Allow", "Principal": {"AWS": [ "arn:aws:iam::111122223333:user/KeyUser", "arn:aws:iam::444455556666:root" ]}, "Action": [ "kms:CreateGrant", "kms:Encrypt", API Version 2014-10-31 225 Amazon Relational Database Service User Guide Sharing an Encrypted Snapshot "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource": "*" }, { } ] } "Sid": "Allow attachment of persistent resources", "Effect": "Allow", "Principal": {"AWS": [ "arn:aws:iam::111122223333:user/KeyUser", "arn:aws:iam::444455556666:root" ]}, "Action": [ "kms:CreateGrant", "kms:ListGrants", "kms:RevokeGrant" ], "Resource": "*", "Condition": {"Bool": {"kms:GrantIsForAWSResource": true}} Creating an IAM Policy to Enable Copying of the Encrypted Snapshot Once the external AWS account has access to your KMS key, the owner of that AWS account can create a policy that allows an IAM user created for that account to copy an encrypted snapshot encrypted with that KMS key. The following example shows a policy that can be attached to an IAM user for AWS account 444455556666 that enables the IAM user to copy a shared snapshot from AWS account 111122223333 that has been encrypted with the KMS key c989c1dd-a3f2-4a5d-8d96-e793d082ab26 in the uswest-2 region. { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowUseOfTheKey", "Effect": "Allow", "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey", "kms:CreateGrant", "kms:RetireGrant" ], "Resource": ["arn:aws:kms:us-west-2:111122223333:key/c989c1dd-a3f2-4a5d-8d96e793d082ab26"] }, { "Sid": "AllowAttachmentOfPersistentResources", "Effect": "Allow", "Action": [ "kms:CreateGrant", "kms:ListGrants", "kms:RevokeGrant" ], API Version 2014-10-31 226 Amazon Relational Database Service User Guide Sharing a Snapshot "Resource": ["arn:aws:kms:us-west-2:111122223333:key/c989c1dd-a3f2-4a5d-8d96e793d082ab26"], "Condition": { "Bool": { "kms:GrantIsForAWSResource": true } } } ] } For details on updating a key policy, see Key Policies in the AWS KMS Developer Guide. Sharing a Snapshot You can share a DB snapshot using the AWS Management Console, the AWS CLI, or the RDS API. AWS Management Console Using the Amazon RDS console, you can share a manual DB snapshot with up to 20 AWS accounts. You can also use the console to stop sharing a manual snapshot with one or more accounts. To share a manual DB snapshot by using the Amazon RDS console 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Snapshots. 3. Select the manual snapshot that you want to share. 4. Choose Actions, and then choose Share Snapshot. 5. Choose one of the following options for DB snapshot visibility. • If the source is unencrypted, choose Public to permit all AWS accounts to restore a DB instance from your manual DB snapshot, or choose Private to permit only AWS accounts that you specify to restore a DB instance from your manual DB snapshot. Warning If you set DB snapshot visibility to Public, all AWS accounts can restore a DB instance from your manual DB snapshot and have access to your data. Do not share any manual DB snapshots that contain private information as Public. • If the source is encrypted, DB snapshot visibility is set as Private because encrypted snapshots can't be shared as public. 6. For AWS Account ID, type the AWS account identifier for an account that you want to permit to restore a DB instance from your manual snapshot, and then choose Add. Repeat to include additional AWS account identifiers, up to 20 AWS accounts. If you make an error when adding an AWS account identifier to the list of permitted accounts, you can delete it from the list by choosing Delete at the right of the incorrect AWS account identifier. API Version 2014-10-31 227 Amazon Relational Database Service User Guide Sharing a Snapshot 7. After you have added identifiers for all of the AWS accounts that you want to permit to restore the manual snapshot, choose Save to save your changes. To stop sharing a manual DB snapshot with an AWS account 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Snapshots. 3. Select the manual snapshot that you want to stop sharing. 4. Choose Actions, and then choose Share Snapshot. 5. To remove permission for an AWS account, choose Delete for the AWS account identifier for that account from the list of authorized accounts. API Version 2014-10-31 228 Amazon Relational Database Service User Guide Sharing a Snapshot 6. Choose Save to save your changes. AWS CLI To share a DB snapshot, use the aws rds modify-db-snapshot-attribute command. Use the -values-to-add parameter to add a list of the IDs for the AWS accounts that are authorized to restore the manual snapshot. The following example permits two AWS account identifiers, 123451234512 and 123456789012, to restore the DB snapshot named manual-snapshot1, and removes the all attribute value to mark the snapshot as private. aws rds modify-db-snapshot-attribute \ --db-snapshot-identifier manual-snapshot1 \ --attribute-name restore \ --values-to-add '["111122223333","444455556666"]' To remove an AWS account identifier from the list, use the -- values-to-remove parameter. The following example prevents AWS account ID 444455556666 from restoring the snapshot. aws rds modify-db-snapshot-attribute \ --db-snapshot-identifier manual-snapshot1 \ --attribute-name restore \ --values-to-remove '["444455556666 "]' API Version 2014-10-31 229 Amazon Relational Database Service User Guide Sharing a Snapshot API You can also share a manual DB snapshot with other AWS accounts by using the Amazon RDS API. To do so, call the ModifyDBSnapshotAttribute action. Specify restore for AttributeName, and use the ValuesToAdd parameter to add a list of the IDs for the AWS accounts that are authorized to restore the manual snapshot. To make a manual snapshot public and restorable by all AWS accounts, use the value all. However, take care not to add the all value for any manual snapshots that contain private information that you don't want to be available to all AWS accounts. Also, don't specify all for encrypted snapshots, because making such snapshots public isn't supported. To remove sharing permission for an AWS account, use the ModifyDBSnapshotAttribute action with AttributeName set to restore and the ValuesToRemove parameter. To mark a manual snapshot as private, remove the value all from the values list for the restore attribute. To list all of the AWS accounts permitted to restore a snapshot, use the DescribeDBSnapshotAttributes API action. API Version 2014-10-31 230 Amazon Relational Database Service User Guide Point-in-Time Recovery Restoring a DB Instance to a Specified Time You can restore a DB instance to a specific point in time, creating a new DB instance . When you restore a DB instance to a point in time, the default DB security group is applied to the new DB instance. If you need custom DB security groups applied to your DB instance, you must apply them explicitly using the AWS Management Console, the AWS CLI modify-db-instance command, or the Amazon RDS API ModifyDBInstance action after the DB instance is available. RDS uploads transaction logs for DB instances to Amazon S3 every 5 minutes. To determine the latest restorable time for a DB instance, use the AWS CLI describe-db-instances command and look at the value returned in the LatestRestorableTime field for the DB instance. In the AWS Management Console, this property is visible as the Latest restore time for the DB instance. You can restore to any point in time during your backup retention period. Several of the database engines used by Amazon RDS have special considerations when restoring from a point in time. When you restore an Oracle DB instance to a point in time, you can specify a different Oracle DB engine, license model, and DBName (SID) to be used by the new DB instance. When you restore a SQL Server DB instance to a point in time, each database within that instance is restored to a point in time within 1 second of each other database within the instance. Transactions that span multiple databases within the instance may be restored inconsistently. Also, for a SQL Server DB instance, the OFFLINE, EMERGENCY, and SINGLE_USER modes are not currently supported. Setting any database into one of these modes will cause the latest restorable time to stop moving ahead for the whole instance. Some actions, such as changing the recovery model of a SQL Server database, can break the sequence of logs that are used for point-in-time recovery. In some cases, Amazon RDS can detect this issue and the latest restorable time is prevented from moving forward; in other cases, such as when a SQL Server database uses the BULK_LOGGED recovery model, the break in log sequence is not detected. It may not be possible to restore a SQL Server DB instance to a point in time if there is a break in the log sequence. For these reasons, Amazon RDS does not support changing the recovery model of SQL Server databases. You can restore a DB instance to a point in time using the AWS Management Console, the AWS CLI, or the RDS API. AWS Management Console To restore a DB instance to a specified time 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Instances. 3. Select the DB instance that you want to restore. 4. Choose Instance actions, and then choose Restore to point in time. The Launch DB Instance window appears. 5. Choose Latest restorable time to restore to the latest possible time, or choose Custom to choose a time. If you chose Custom, enter the date and time that you want to restore the instance to. 6. Type the name of the restored DB instance in the DB instance identifier box, and complete the other options. 7. Choose Launch DB Instance. API Version 2014-10-31 231 Amazon Relational Database Service User Guide Point-in-Time Recovery CLI To restore a DB instance to a specified time, use the AWS CLI command restore-db-instance-topoint-in-time to create a new DB instance. Example For Linux, OS X, or Unix: aws rds restore-db-instance-to-point-in-time \ --source-db-instance-identifier mysourcedbinstance \ --target-db-instance-identifier mytargetdbinstance \ --restore-time 2017-10-14T23:45:00.000Z For Windows: aws rds restore-db-instance-to-point-in-time ^ --source-db-instance-identifier mysourcedbinstance ^ --target-db-instance-identifier mytargetdbinstance ^ --restore-time 2017-10-14T23:45:00.000Z API To restore a DB instance to a specified time, call the Amazon RDS API RestoreDBInstanceToPointInTime action with the following parameters: • SourceDBInstanceIdentifier • TargetDBInstanceIdentifier • RestoreTime API Version 2014-10-31 232 Amazon Relational Database Service User Guide Tutorial: Restore a DB Instance from a DB Snapshot Tutorial: Restore a DB Instance from a DB Snapshot A common scenario when working with Amazon RDS is to have a DB instance that you work with occasionally but that you don't need full time. For example, you might have a quarterly customer survey that uses an Amazon Elastic Compute Cloud (Amazon EC2) instance to host a customer survey website and a DB instance that is used to store the survey results. One way to save money on such a scenario is to take a DB snapshot of the DB instance after the survey is completed, delete the DB instance, and then restore the DB instance when you need to conduct the survey again. In the following illustration, you can see a possible scenario where an EC2 instance hosting a customer survey website is in the same Amazon Virtual Private Cloud (Amazon VPC) as a DB instance that retains the customer survey data. Note that each instance has its own security group; the EC2 instance security group allows access from the Internet while the DB instance security group allows access only to and from the EC2 instance. When the survey is done, the EC2 instance can be stopped and the DB instance can be deleted after a final DB snapshot is created. When you need to conduct another survey, you can restart the EC2 instance and restore the DB instance from the DB snapshot. For information about how to set up the needed VPC security groups for this scenario that allows the EC2 instance to connect with the DB instance, see A DB Instance in a VPC Accessed by an EC2 Instance in the Same VPC (p. 402). You must create a DB snapshot before you can restore a DB instance from one. When you restore the DB instance, you provide the name of the DB snapshot to restore from, and then provide a name for the new DB instance that is created from the restore operation. You cannot restore from a DB snapshot to an existing DB instance; a new DB instance is created when you restore. Prerequisites for Restoring a DB Instance from a DB Snapshot Some settings on the restored DB instance are reset when the instance is restored, so you must retain the original resources to be able to restore the DB instance to its previous settings. For example, when you restore a DB instance from a DB snapshot, the default DB parameter and a default security group are associated with the restored instance. That association means that the default security group does not API Version 2014-10-31 233 Amazon Relational Database Service User Guide Restoring a DB Instance from a DB Snapshot allow access to the DB instance, and no custom parameter settings are available in the default parameter group. You need to retain the DB parameter group and security group associated with the DB instance that was used to create the DB snapshot. The following are required before you can restore a DB instance from a DB snapshot: • You must have created a DB snapshot of a DB instance before you can restore a DB instance from that DB snapshot. For more information about creating a DB snapshot, see Creating a DB Snapshot (p. 210). • You must retain the parameter group and security group associated with the DB instance you created the DB snapshot from. • You need to determine the correct option group for the restored DB instance: • The option group associated with the DB snapshot that you restore from is associated with the restored DB instance once it is created. For example, if the DB snapshot you restore from uses Oracle Transparent Data Encryption (TDE), the restored DB instance uses the same option group, which had the TDE option. • You cannot use the option group associated with the original DB instance if you attempt to restore that instance into a different VPC or into a different platform. This restriction occurs because when an option group is assigned to a DB instance, it is also linked to the platform that the DB instance is on, either VPC or EC2-Classic (non-VPC). If a DB instance is in a VPC, the option group associated with the instance is linked to that VPC. • If you restore a DB instance into a different VPC or onto a different platform, you must either assign the default option group to the instance, assign an option group that is linked to that VPC or platform, or create a new option group and assign it to the DB instance. Note that with persistent or permanent options, such as Oracle TDE, you must create a new option group that includes the persistent or permanent option when restoring a DB instance into a different VPC. For more information about working with option groups, see Working with Option Groups (p. 152). Restoring a DB Instance from a DB Snapshot You can use the procedure following to restore from a snapshot in the AWS Management Console. To restore a DB instance from a DB snapshot 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Snapshots. 3. Select the DB snapshot that you want to restore from. 4. Choose Snapshot Actions, and then choose Restore Snapshot. The Restore DB Instance page appears. API Version 2014-10-31 234 Amazon Relational Database Service User Guide Modifying a Restored DB Instance 5. For DB Instance Identifier under Settings, type the name you want to use for the restored DB instance. If you are restoring from a DB instance that you deleted after you made the DB snapshot, you can use the name of that DB instance. 6. Choose Restore DB Instance. Modifying a Restored DB Instance As soon as the restore operation is complete, you should associate the custom security group used by the instance you restored from with any applicable custom DB parameter group that you might have. Only the default DB parameter and security groups are associated with the restored instance. If you want to restore the functionality of the DB instance to that of the DB instance that the snapshot was created from, you must modify the DB instance to use the security group and parameter group used by the previous DB instance. You must apply any changes explicitly using the RDS console's Modify command, the ModifyDBInstance API, or the aws rds modify-db-instance command line tool, once the DB instance is available. We recommend that you retain parameter groups for any DB snapshots you have so that you can associate a restored instance with the correct parameter file. You can modify other settings on the restored DB instance. For example, you can use a different storage type than the source DB snapshot. In this case the restoration process is slower because of the additional work required to migrate the data to the new storage type. In the case of restoring to or from Magnetic (Standard) storage, the migration process is the slowest, because Magnetic storage does not have the IOPS capability of Provisioned IOPS or General Purpose (SSD) storage. The next steps assume that your DB instance is in a VPC. If your DB instance is not in a VPC, use the AWS Management Console to locate the DB security group you need for the DB instance. To modify a restored DB instance to have the settings of the original DB instance 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Instances. 3. Click the name of the DB instance created when you restored from the DB snapshot to display its details. Scroll to the Connect section. The security group assigned to the DB instance might not allow access. If there are no inbound rules, no permissions exist that allow inbound access. 4. Choose Instance actions, and then choose Modify. 5. In the Network & Security section, select the security group that you want to use for your DB instance. If you need to add rules to create a new security group to use with an EC2 instance, see A DB Instance in a VPC Accessed by an EC2 Instance in the Same VPC (p. 402) for more information. API Version 2014-10-31 235 Amazon Relational Database Service User Guide Modifying a Restored DB Instance You can also remove a security group by clicking the X associated with it. 6. Choose Continue, and then choose Apply immediately. 7. Choose Modify DB Instance. After the instance status is available, click the DB instance name to display its details. Scroll to the Details section, and confirm that the new security group has been applied, making the DB instance authorized for access. API Version 2014-10-31 236 Amazon Relational Database Service User Guide Related Topics Related Topics • Restoring from a DB Snapshot (p. 212) API Version 2014-10-31 237 Amazon Relational Database Service User Guide Monitoring Amazon RDS This section shows you how to monitor Amazon RDS. Topics • Overview of Monitoring Amazon RDS (p. 239) • Enhanced Monitoring (p. 250) • Using Amazon RDS Performance Insights (p. 260) • Using Amazon RDS Recommendations (p. 274) • Using Amazon RDS Event Notification (p. 278) • Viewing Amazon RDS Events (p. 295) • Amazon RDS Database Log Files (p. 297) • Logging Amazon RDS API Calls with AWS CloudTrail (p. 326) API Version 2014-10-31 238 Amazon Relational Database Service User Guide Overview of Monitoring Overview of Monitoring Amazon RDS Monitoring is an important part of maintaining the reliability, availability, and performance of Amazon RDS and your AWS solutions. You should collect monitoring data from all of the parts of your AWS solution so that you can more easily debug a multi-point failure if one occurs. Before you start monitoring Amazon RDS, we recommend that you create a monitoring plan that includes answers to the following questions: • What are your monitoring goals? • What resources will you monitor? • How often will you monitor these resources? • What monitoring tools will you use? • Who will perform the monitoring tasks? • Who should be notified when something goes wrong? The next step is to establish a baseline for normal Amazon RDS performance in your environment, by measuring performance at various times and under different load conditions. As you monitor Amazon RDS, you should consider storing historical monitoring data. This stored data will give you a baseline to compare against with current performance data, identify normal performance patterns and performance anomalies, and devise methods to address issues. For example, with Amazon RDS, you can monitor network throughput, I/O for read, write, and/or metadata operations, client connections, and burst credit balances for your DB instances. When performance falls outside your established baseline, you might need change the instance class of your DB instance or the number of DB instances and Read Replicas that are available for clients in order to optimize your database availability for your workload. In general, acceptable values for performance metrics depend on what your baseline looks like and what your application is doing. Investigate consistent or trending variances from your baseline. Advice about specific types of metrics follows: • High CPU or RAM consumption – High values for CPU or RAM consumption might be appropriate, provided that they are in keeping with your goals for your application (like throughput or concurrency) and are expected. • Disk space consumption – Investigate disk space consumption if space used is consistently at or above 85 percent of the total disk space. See if it is possible to delete data from the instance or archive data to a different system to free up space. • Network traffic – For network traffic, talk with your system administrator to understand what expected throughput is for your domain network and Internet connection. Investigate network traffic if throughput is consistently lower than expected. • Database connections – Consider constraining database connections if you see high numbers of user connections in conjunction with decreases in instance performance and response time. The best number of user connections for your DB instance will vary based on your instance class and the complexity of the operations being performed. You can determine the number of database connections by associating your DB instance with a parameter group where the User Connections parameter is set to a value other than 0 (unlimited). You can either use an existing parameter group or create a new one. For more information, see Working with DB Parameter Groups (p. 165). • IOPS metrics – The expected values for IOPS metrics depend on disk specification and server configuration, so use your baseline to know what is typical. Investigate if values are consistently different than your baseline. For best IOPS performance, make sure your typical working set will fit into memory to minimize read and write operations. API Version 2014-10-31 239 Amazon Relational Database Service User Guide Monitoring Tools Monitoring Tools AWS provides various tools that you can use to monitor Amazon RDS. You can configure some of these tools to do the monitoring for you, while some of the tools require manual intervention. We recommend that you automate monitoring tasks as much as possible. Automated Monitoring Tools You can use the following automated monitoring tools to watch Amazon RDS and report when something is wrong: • Amazon RDS Events – Subscribe to Amazon RDS events to be notified when changes occur with a DB instance, DB snapshot, DB parameter group, or DB security group. For more information, see Using Amazon RDS Event Notification (p. 278). • Database log files – View, download, or watch database log files using the Amazon RDS console or Amazon RDS API actions. You can also query some database log files that are loaded into database tables. For more information, see Amazon RDS Database Log Files (p. 297). • Amazon RDS Enhanced Monitoring — Look at metrics in real time for the operating system. For more information, see Enhanced Monitoring (p. 250). In addition, Amazon RDS integrates with Amazon CloudWatch for additional monitoring capabilities: • Amazon CloudWatch Metrics – Amazon RDS automatically sends metrics to CloudWatch every minute for each active database. You are not charged additionally for Amazon RDS metrics in CloudWatch. For more information, see the section called “Viewing DB Instance Metrics” (p. 248). • Amazon CloudWatch Alarms – You can watch a single Amazon RDS metric over a specific time period, and perform one or more actions based on the value of the metric relative to a threshold you set. For more information, see Monitoring with Amazon CloudWatch (p. 241) • Amazon CloudWatch Logs – Most DB engines enable you to monitor, store, and access your database log files in CloudWatch Logs. For more information, see Amazon CloudWatch Logs User Guide Manual Monitoring Tools Another important part of monitoring Amazon RDS involves manually monitoring those items that the CloudWatch alarms don't cover. The Amazon RDS, CloudWatch, AWS Trusted Advisor and other AWS console dashboards provide an at-a-glance view of the state of your AWS environment. We recommend that you also check the log files on your DB instance. • From the Amazon RDS console, you can monitor the following items for your resources: • The number of connections to a DB instance • The amount of read and write operations to a DB instance • The amount of storage that a DB instance is currently utilizing • The amount of memory and CPU being utilized for a DB instance • The amount of network traffic to and from a DB instance • From the AWS Trusted Advisor dashboard, you can review the following cost optimization, security, fault tolerance, and performance improvement checks: • Amazon RDS Idle DB Instances • Amazon RDS Security Group Access Risk • Amazon RDS Backups • Amazon RDS Multi-AZ For more information on these checks, see Trusted Advisor Best Practices (Checks). API Version 2014-10-31 240 Amazon Relational Database Service User Guide Monitoring with CloudWatch • CloudWatch home page shows: • Current alarms and status • Graphs of alarms and resources • Service health status In addition, you can use CloudWatch to do the following: • Create customized dashboards to monitor the services you care about • Graph metric data to troubleshoot issues and discover trends • Search and browse all your AWS resource metrics • Create and edit alarms to be notified of problems Monitoring with Amazon CloudWatch You can monitor DB instances using Amazon CloudWatch, which collects and processes raw data from Amazon RDS into readable, near real-time metrics. These statistics are recorded for a period of two weeks, so that you can access historical information and gain a better perspective on how your web application or service is performing. By default, Amazon RDS metric data is automatically sent to CloudWatch in 1-minute periods. For more information about CloudWatch, see What Are Amazon CloudWatch, Amazon CloudWatch Events, and Amazon CloudWatch Logs? in the Amazon CloudWatch User Guide. Amazon RDS Metrics and Dimensions When you use Amazon RDS resources, Amazon RDS sends metrics and dimensions to Amazon CloudWatch every minute. You can use the following procedures to view the metrics for Amazon RDS. To view metrics using the Amazon CloudWatch console Metrics are grouped first by the service namespace, and then by the various dimension combinations within each namespace. 1. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/. 2. If necessary, change the region. From the navigation bar, select the region where your AWS resources reside. For more information, see Regions and Endpoints. 3. In the navigation pane, choose Metrics. Choose the RDS metric namespace. API Version 2014-10-31 241 Amazon Relational Database Service User Guide Monitoring with CloudWatch 4. Select a metric dimension, for example, By Database Class. 5. To sort the metrics, use the column heading. To graph a metric, select the check box next to the metric. To filter by resource, choose the resource ID and then choose Add to search. To filter by metric, choose the metric name and then choose Add to search. API Version 2014-10-31 242 Amazon Relational Database Service User Guide Monitoring with CloudWatch To view metrics using the AWS CLI • At a command prompt, use the following command: aws cloudwatch list-metrics --namespace AWS/RDS Amazon RDS Metrics The AWS/RDS namespace includes the following metrics. Metric Description AuroraGlobalDBReplicatedWriteIO Units: Bytes AuroraGlobalDBDataTransferBytes Units: Bytes AuroraGlobalDBReplicationLag Units: Milliseconds BinLogDiskUsage The amount of disk space occupied by binary logs on the master. Applies to MySQL read replicas. Units: Bytes BurstBalance The percent of General Purpose SSD (gp2) burst-bucket I/O credits available. Units: Percent CPUUtilization The percentage of CPU utilization. Units: Percent CPUCreditUsage [T2 instances] The number of CPU credits spent by the instance for CPU utilization. One CPU credit equals one vCPU running at 100% utilization for one minute or an equivalent combination of vCPUs, utilization, and time (for example, one vCPU running at 50% utilization for two minutes or two vCPUs running at 25% utilization for two minutes). CPU credit metrics are available at a five-minute frequency only. If you specify a period greater than five minutes, use the Sum statistic instead of the Average statistic. Units: Credits (vCPU-minutes) CPUCreditBalance [T2 instances] The number of earned CPU credits that an instance has accrued since it was launched or started. For T2 Standard, the CPUCreditBalance also includes the number of launch credits that have been accrued. Credits are accrued in the credit balance after they are earned, and removed from the credit balance when they are spent. The credit balance has a maximum limit, determined by the instance size. Once the limit is reached, any new credits that are earned are discarded. For T2 Standard, launch credits do not count towards the limit. The credits in the CPUCreditBalance are available for the instance to spend to burst beyond its baseline CPU utilization. API Version 2014-10-31 243 Amazon Relational Database Service User Guide Monitoring with CloudWatch Metric Description When an instance is running, credits in the CPUCreditBalance do not expire. When the instance stops, the CPUCreditBalance does not persist, and all accrued credits are lost. CPU credit metrics are available at a five-minute frequency only. Units: Credits (vCPU-minutes) DatabaseConnections The number of database connections in use. Units: Count DiskQueueDepth The number of outstanding IOs (read/write requests) waiting to access the disk. Units: Count FreeableMemory The amount of available random access memory. Units: Bytes FreeStorageSpace The amount of available storage space. Units: Bytes MaximumUsedTransactionIDsThe maximum transaction ID that has been used. Applies to PostgreSQL. Units: Count NetworkReceiveThroughput The incoming (Receive) network traffic on the DB instance, including both customer database traffic and Amazon RDS traffic used for monitoring and replication. Units: Bytes/second NetworkTransmitThroughputThe outgoing (Transmit) network traffic on the DB instance, including both customer database traffic and Amazon RDS traffic used for monitoring and replication. Units: Bytes/second OldestReplicationSlotLag The lagging size of the replica lagging the most in terms of WAL data received. Applies to PostgreSQL. Units: Megabytes ReadIOPS The average number of disk read I/O operations per second. Units: Count/Second ReadLatency The average amount of time taken per disk I/O operation. Units: Seconds ReadThroughput The average number of bytes read from disk per second. Units: Bytes/Second API Version 2014-10-31 244 Amazon Relational Database Service User Guide Monitoring with CloudWatch Metric Description ReplicaLag The amount of time a Read Replica DB instance lags behind the source DB instance. Applies to MySQL, MariaDB, and PostgreSQL Read Replicas. Units: Seconds ReplicationSlotDiskUsage The disk space used by replication slot files. Applies to PostgreSQL. Units: Megabytes SwapUsage The amount of swap space used on the DB instance. This metric is not available for SQL Server. Units: Bytes TransactionLogsDiskUsage The disk space used by transaction logs. Applies to PostgreSQL. Units: Megabytes TransactionLogsGenerationThe size of transaction logs generated per second. Applies to PostgreSQL. Units: Megabytes/second WriteIOPS The average number of disk write I/O operations per second. Units: Count/Second WriteLatency The average amount of time taken per disk I/O operation. Units: Seconds WriteThroughput The average number of bytes written to disk per second. Units: Bytes/Second Amazon RDS Dimensions Amazon RDS metrics data can be filtered by using any of the dimensions in the following table: Dimension Description DBInstanceIdentifier This dimension filters the data you request for a specific database instance. DBClusterIdentifier This dimension filters the data you request for a specific Amazon Aurora DB cluster. DBClusterIdentifier, Role This dimension filters the data you request for a specific Aurora DB cluster, aggregating the metric by instance role (WRITER/READER). For example, you can aggregate metrics for all READER instances that belong to a cluster. DatabaseClass This dimension filters the data you request for all instances in a database class. For example, you can aggregate metrics for all instances that belong to the database class db.m1.small API Version 2014-10-31 245 Amazon Relational Database Service User Guide Monitoring with CloudWatch Dimension Description EngineName This dimension filters the data you request for the identified engine name only. For example, you can aggregate metrics for all instances that have the engine name mysql. SourceRegion This dimension filters the data you request for the specified region only. For example, you can aggregate metrics for all instances in the region us-east-1. Creating CloudWatch Alarms to Monitor Amazon RDS You can create a CloudWatch alarm that sends an Amazon SNS message when the alarm changes state. An alarm watches a single metric over a time period you specify, and performs one or more actions based on the value of the metric relative to a given threshold over a number of time periods. The action is a notification sent to an Amazon SNS topic or Auto Scaling policy. Alarms invoke actions for sustained state changes only. CloudWatch alarms will not invoke actions simply because they are in a particular state, the state must have changed and been maintained for a specified number of periods. The following procedures outlines how to create alarms for Amazon RDS. To set alarms using the CloudWatch console 1. Sign in to the AWS Management Console and open the CloudWatch console at https:// console.aws.amazon.com/cloudwatch/. 2. Choose Alarms and then choose Create Alarm. This launches the Create Alarm Wizard. 3. Choose RDS Metrics and scroll through the Amazon RDS metrics to locate the metric you want to place an alarm on. To display just the Amazon RDS metrics in this dialog box, search for the identifier of your resource. Select the metric to create an alarm on and then choose Next. 4. Fill in the Name, Description, Whenever values for the metric. 5. If you want CloudWatch to send you an email when the alarm state is reached, in the Whenever this alarm: field, choose State is ALARM. In the Send notification to: field, choose an existing SNS topic. If you select Create topic, you can set the name and email addresses for a new email subscription list. This list is saved and appears in the field for future alarms. Note If you use Create topic to create a new Amazon SNS topic, the email addresses must be verified before they receive notifications. Emails are only sent when the alarm enters an alarm state. If this alarm state change happens before the email addresses are verified, they do not receive a notification. 6. At this point, the Alarm Preview area gives you a chance to preview the alarm you’re about to create. Choose Create Alarm. To set an alarm using the AWS CLI • Call put-metric-alarm. For more information, see AWS CLI Command Reference. To set an alarm using the CloudWatch API • Call PutMetricAlarm. For more information, see Amazon CloudWatch API Reference API Version 2014-10-31 246 Amazon Relational Database Service User Guide Publishing to CloudWatch Logs Publishing Database Engine Logs to Amazon CloudWatch Logs You can configure your Amazon RDS database engine to publish log data to a log group in Amazon CloudWatch Logs. With CloudWatch Logs, you can perform real-time analysis of the log data, and use CloudWatch to create alarms and view metrics. You can use CloudWatch Logs to store your log records in highly durable storage, which you can manage with the CloudWatch Logs Agent. For example, you can determine when to rotate log records from a host to the log service, so you can access the raw logs when you need to. You can export logs for Amazon RDS MariaDB (all versions) and Amazon RDS MySQL (versions 5.6, 5.7, and 8.0). Note You must have a Service Linked Role before you enable log data publishing. For more information about Service Linked Roles, see the following: Using Service-Linked Roles for Amazon RDS (p. 397). For specific requirements for these engines, see the following: • the section called “Publishing MariaDB Logs to CloudWatch Logs” (p. 302) • the section called “Publishing MySQL Logs to CloudWatch Logs” (p. 311) Configuring CloudWatch Log Integration To publish your database log files to CloudWatch Logs, choose which logs to publish. Make this choice in the Advanced Settings section when you create a new DB instance. You can also modify an existing DB instance to begin publishing. After you have enabled publishing, Amazon RDS continuously streams all of the DB instance log records to a log group. For example, you have a log group /aws/rds/instance/log type for each type of log that you publish. This log group is in the same AWS Region as the database instance that generates the log. After you have published log records, you can use CloudWatch Logs to search and filter the records. For more information about searching and filtering logs, see Searching and Filtering Log Data. API Version 2014-10-31 247 Amazon Relational Database Service User Guide Publishing to CloudWatch Logs Viewing DB Instance Metrics Amazon RDS provides metrics so that you can monitor the health of your DB instances. You can monitor both DB instance metrics and operating system (OS) metrics. This section provides details on how you can view metrics for your DB instance using the RDS console and CloudWatch. For information on monitoring metrics for the operating system of your DB instance in real time using CloudWatch Logs, see Enhanced Monitoring (p. 250). Viewing Metrics by Using the Console To view DB and OS metrics for a DB instance 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Instances. 3. Select the check box to the left of the DB you need information about. For Show Monitoring, choose the option for how you want to view your metrics from these: • CloudWatch – Shows a summary of DB instance metrics available from Amazon CloudWatch. Each metric includes a graph showing the metric monitored over a specific time span. • Enhanced monitoring – Shows a summary of OS metrics available for a DB instance with Enhanced Monitoring enabled. Each metric includes a graph showing the metric monitored over a specific time span. • OS Process list – Shows details for each process running in the selected instance. Tip You can select the time range of the metrics represented by the graphs with the time range drop-down list. You can choose any graph to bring up a more detailed view. You can also apply metricspecific filters to the data. Viewing DB Instance Metrics with the CLI or API Amazon RDS integrates with CloudWatch metrics to provide a variety of DB instance metrics. You can view CloudWatch metrics using the RDS console, AWS CLI, or API. For a complete list of Amazon RDS metrics, go to Amazon RDS Dimensions and Metrics in the Amazon CloudWatch User Guide. API Version 2014-10-31 248 Amazon Relational Database Service User Guide Publishing to CloudWatch Logs Viewing DB Metrics by Using the CloudWatch CLI Note The following CLI example requires the CloudWatch command line tools. For more information on CloudWatch and to download the developer tools, see the Amazon CloudWatch product page. The StartTime and EndTime values supplied in this example are for illustrative purposes. You must substitute appropriate start and end time values for your DB instance. To view usage and performance statistics for a DB instance • Use the CloudWatch command mon-get-stats with the following parameters. PROMPT>mon-get-stats FreeStorageSpace --dimensions="DBInstanceIdentifier=mydbinstance" --statistics= Average --namespace="AWS/RDS" --start-time 2009-10-16T00:00:00 --end-time 2009-10-16T00:02:00 Viewing DB Metrics by Using the CloudWatch API The StartTime and EndTime values supplied in this example are for illustrative purposes. You must substitute appropriate start and end time values for your DB instance. To view usage and performance statistics for a DB instance • Call the CloudWatch API GetMetricStatistics with the following parameters: • Statistics.member.1 = Average • Namespace = AWS/RDS • StartTime = 2009-10-16T00:00:00 • EndTime = 2009-10-16T00:02:00 • Period = 60 • MeasureName = FreeStorageSpace API Version 2014-10-31 249 Amazon Relational Database Service User Guide Enhanced Monitoring Enhanced Monitoring Amazon RDS provides metrics in real time for the operating system (OS) that your DB instance runs on. You can view the metrics for your DB instance using the console, or consume the Enhanced Monitoring JSON output from CloudWatch Logs in a monitoring system of your choice. The cost for using Enhanced Monitoring varies depends on several factors: • You are only charged for Enhanced Monitoring that exceeds the free tier provided by Amazon CloudWatch Logs. For more information about pricing, see Amazon CloudWatch Pricing. • A smaller monitoring interval results in more frequent reporting of OS metrics and increases your monitoring cost. • Usage costs for Enhanced Monitoring are applied for each DB instance that Enhanced Monitoring is enabled for. Monitoring a large number of DB instances is more expensive than monitoring only a few. • DB instances that support a more compute-intensive workload have more OS process activity to report and higher costs for Enhanced Monitoring. Enhanced Monitoring Availability Enhanced Monitoring is available for the following database engines: • MariaDB • Microsoft SQL Server • MySQL version 5.5 or later • Oracle • PostgreSQL Enhanced Monitoring is available for all DB instance classes except for db.m1.small. Differences Between CloudWatch and Enhanced Monitoring Metrics CloudWatch gathers metrics about CPU utilization from the hypervisor for a DB instance, and Enhanced Monitoring gathers its metrics from an agent on the instance. As a result, you might find differences between the measurements, because the hypervisor layer performs a small amount of work. The differences can be greater if your DB instances use smaller instance classes, because then there are likely more virtual machines (VMs) that are managed by the hypervisor layer on a single physical instance. Enhanced Monitoring metrics are useful when you want to see how different processes or threads on a DB instance use the CPU. Setting Up for and Enabling Enhanced Monitoring Before You Begin Enhanced Monitoring requires permission to act on your behalf to send OS metric information to CloudWatch Logs. You grant Enhanced Monitoring the required permissions using an AWS Identity and Access Management (IAM) role. API Version 2014-10-31 250 Amazon Relational Database Service User Guide Setting Up for and Enabling Enhanced Monitoring The first time that you enable Enhanced Monitoring in the console, you can select the Default option for the Monitoring Role property to have RDS create the required IAM role. RDS then automatically creates a role named rds-monitoring-role for you, and uses it for the specified DB instance or Read Replica. You can also create the required role before you enable Enhanced Monitoring, and then specify your new role's name when you enable Enhanced Monitoring. You must create this required role if you enable Enhanced Monitoring using the AWS CLI or the RDS API. To create the appropriate IAM role to permit Amazon RDS to communicate with the Amazon CloudWatch Logs service on your behalf, take the following steps. To create an IAM role for Amazon RDS Enhanced Monitoring 1. Open the IAM Console at https://console.aws.amazon.com. 2. In the navigation pane, choose Roles. 3. Choose Create role. 4. Choose the AWS service tab, and then choose RDS from the list of services. 5. Choose RDS - Enhanced Monitoring, and then choose Next: Permissions. 6. On the Attached permissions policy page, choose AmazonRDSEnhancedMonitoringRole, and then choose Next: Review. 7. For Role Name, type a name for your role, for example emaccess, and then choose Create role. Enabling and Disabling Enhanced Monitoring You can enable Enhanced Monitoring when you create a DB instance or Read Replica, or when you modify a DB instance. If you modify a DB instance to enable Enhanced Monitoring, you do not need to reboot your DB instance for the change to take effect. You can enable Enhanced Monitoring in the RDS console when you do one of the following actions: • Create a Instance – You can enable Enhanced Monitoring in the Configure Advanced Settings page. • Create Read Replica – You can enable Enhanced Monitoring in the Configure Advanced Settings page. • Modify a DB Instance – You can enable Enhanced Monitoring in the Modify DB Instance page. To enable Enhanced Monitoring by using the RDS console, scroll to the Monitoring section and do the following: 1. Choose Enable enhanced monitoring for your DB instance or Read Replica. 2. Set the Monitoring Role property to the IAM role that you created to permit Amazon RDS to communicate with Amazon CloudWatch Logs for you, or choose Default to have RDS create a role for you named rds-monitoring-role. 3. Set the Granularity property to the interval, in seconds, between points when metrics are collected for your DB instance or Read Replica. The Granularity property can be set to one of the following values: 1, 5, 10, 15, 30, or 60. To disable Enhanced Monitoring, choose Disable enhanced monitoring. API Version 2014-10-31 251 Amazon Relational Database Service User Guide Viewing Enhanced Monitoring Enabling Enhanced Monitoring does not require your DB instance to restart. Note The fastest that the RDS console refreshes is every 5 seconds. If you set the granularity to 1 second in the RDS console, you still see updated metrics only every 5 seconds. You can retrieve 1 second metric updates by using CloudWatch Logs. Viewing Enhanced Monitoring You can view OS metrics reported by Enhanced Monitoring in the RDS console by choosing the Enhanced monitoring view from the Monitoring drop-down. The Enhanced Monitoring is shown following. If you want to see details for the processes running on your DB instance, choose OS process list for Monitoring. API Version 2014-10-31 252 Amazon Relational Database Service User Guide Viewing Enhanced Monitoring Process List view is shown following. The Enhanced Monitoring metrics shown in the Process List view are organized as follows: • RDS child processes – Shows a summary of the RDS processes that support the DB instance, for example aurora for Amazon Aurora DB clusters and mysqld for MySQL DB instances. Process threads appear nested beneath the parent process. Process threads show CPU utilization only as other metrics are the same for all threads for the process. The console displays a maximum of 100 processes and threads. The results are a combination of the top CPU consuming and memory consuming processes and threads. If there are more than 50 processes and more than 50 threads, the console displays the top 50 consumers in each category. This display helps you identify which processes are having the greatest impact on performance. • RDS processes – Shows a summary of the resources used by the RDS management agent, diagnostics monitoring processes, and other AWS processes that are required to support RDS DB instances. • OS processes – Shows a summary of the kernel and system processes, which generally have minimal impact on performance. The items listed for each process are: • VIRT – Displays the virtual size of the process. • RES – Displays the actual physical memory being used by the process. • CPU% – Displays the percentage of the CPU bandwidth consumed by the process. • MEM% – Displays the percentage of the total memory consumed by the process. The monitoring data that is shown in the RDS console is retrieved from Amazon CloudWatch Logs. You can also retrieve the metrics for a DB instance as a log stream from CloudWatch Logs. For more information, see Viewing Enhanced Monitoring by Using CloudWatch Logs (p. 254). Enhanced Monitoring metrics are not returned during the following: • A failover of the DB instance. • Changing the instance class of the DB instance (scale compute). Enhanced Monitoring metrics are returned during a reboot of a DB instance because only the database engine is rebooted. Metrics for the operating system are still reported. API Version 2014-10-31 253 Amazon Relational Database Service User Guide Viewing Enhanced Monitoring by Using CloudWatch Logs Viewing Enhanced Monitoring by Using CloudWatch Logs After you have enabled Enhanced Monitoring for your DB instance, you can view the metrics for your DB instance using CloudWatch Logs, with each log stream representing a single DB instance being monitored. The log stream identifier is the resource identifier (DbiResourceId) for the DB instance. To view Enhanced Monitoring log data 1. 2. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/. If necessary, choose the region that your DB instance is in. For more information, go to Regions and Endpoints in the Amazon Web Services General Reference. 3. 4. Choose Logs in the navigation pane. Choose RDSOSMetrics from the list of log groups. 5. Choose the log stream that you want to view from the list of log streams. Available OS Metrics The following tables list the OS metrics available using Amazon CloudWatch Logs. Metrics for MariaDB, MySQL, Oracle, and PostgreSQL DB instances Group Metrics Description General engine The database engine for the DB instance. instanceID The DB instance identifier. instanceResourceID A region-unique, immutable identifier for the DB instance, also used as the log stream identifier. cpuUtilization numVCPUs The number of virtual CPUs for the DB instance. timestamp The time at which the metrics were taken. uptime The amount of time that the DB instance has been active. version The version of the OS metrics' stream JSON format. guest The percentage of CPU in use by guest programs. idle The percentage of CPU that is idle. irq The percentage of CPU in use by software interrupts. nice The percentage of CPU in use by programs running at lowest priority. steal The percentage of CPU in use by other virtual machines. system The percentage of CPU in use by the kernel. total The total percentage of the CPU in use. This value includes the nice value. user The percentage of CPU in use by user programs. API Version 2014-10-31 254 Amazon Relational Database Service User Guide Viewing Enhanced Monitoring by Using CloudWatch Logs Group diskIO fileSys Metrics Description wait The percentage of CPU unused while waiting for I/O access. avgQueueLen The number of requests waiting in the I/O device's queue. avgReqSz The average request size, in kilobytes. await The number of milliseconds required to respond to requests, including queue time and service time. device The identifier of the disk device in use. readIOsPS The number of read operations per second. readKb The total number of kilobytes read. readKbPS The number of kilobytes read per second. rrqmPS The number of merged read requests queued per second. tps The number of I/O transactions per second. util The percentage of CPU time during which requests were issued. writeIOsPS The number of write operations per second. writeKb The total number of kilobytes written. writeKbPS The number of kilobytes written per second. wrqmPS The number of merged write requests queued per second. maxFiles The maximum number of files that can be created for the file system. mountPoint The path to the file system. name The name of the file system. total The total number of disk space available for the file system, in kilobytes. used The amount of disk space used by files in the file system, in kilobytes. usedFilePercent The percentage of available files in use. usedFiles The number of files in the file system. usedPercent The percentage of the file-system disk space in use. loadAverageMinute fifteen The number of processes requesting CPU time over the last 15 minutes. five The number of processes requesting CPU time over the last 5 minutes. one The number of processes requesting CPU time over the last minute. API Version 2014-10-31 255 Amazon Relational Database Service User Guide Viewing Enhanced Monitoring by Using CloudWatch Logs Group Metrics Description memory active The amount of assigned memory, in kilobytes. buffers The amount of memory used for buffering I/O requests prior to writing to the storage device, in kilobytes. cached The amount of memory used for caching file system–based I/O. dirty The amount of memory pages in RAM that have been modified but not written to their related data block in storage, in kilobytes. free The amount of unassigned memory, in kilobytes. hugePagesFree The number of free huge pages. Huge pages are a feature of the Linux kernel. hugePagesRsvd The number of committed huge pages. hugePagesSize The size for each huge pages unit, in kilobytes. hugePagesSurp The number of available surplus huge pages over the total. hugePagesTotal The total number of huge pages for the system. inactive The amount of least-frequently used memory pages, in kilobytes. mapped The total amount of file-system contents that is memory mapped inside a process address space, in kilobytes. pageTables The amount of memory used by page tables, in kilobytes. slab The amount of reusable kernel data structures, in kilobytes. total The total amount of memory, in kilobytes. writeback The amount of dirty pages in RAM that are still being written to the backing storage, in kilobytes. interface The identifier for the network interface being used for the DB instance. rx The number of bytes received per second. tx The number of bytes uploaded per second. cpuUsedPc The percentage of CPU used by the process. id The identifier of the process. memoryUsedPc The amount of memory used by the process, in kilobytes. name The name of the process. parentID The process identifier for the parent process of the process. rss The amount of RAM allocated to the process, in kilobytes. network processList API Version 2014-10-31 256 Amazon Relational Database Service User Guide Viewing Enhanced Monitoring by Using CloudWatch Logs Group swap tasks Metrics Description tgid The thread group identifier, which is a number representing the process ID to which a thread belongs. This identifier is used to group threads from the same process. VIRT The amount of virtual memory allocated to the process, in kilobytes. swap The amount of swap memory available, in kilobytes. swap in The amount of memory, in kilobytes, swapped in from disk. swap out The amount of memory, in kilobytes, swapped out to disk. free The amount of swap memory free, in kilobytes. committed The amount of swap memory, in kilobytes, used as cache memory. blocked The number of tasks that are blocked. running The number of tasks that are running. sleeping The number of tasks that are sleeping. stopped The number of tasks that are stopped. total The total number of tasks. zombie The number of child tasks that are inactive with an active parent task. Metrics for Microsoft SQL Server DB instances Group Metrics Description General engine The database engine for the DB instance. instanceID The DB instance identifier. instanceResourceID A region-unique, immutable identifier for the DB instance, also used as the log stream identifier. cpuUtilization disks numVCPUs The number of virtual CPUs for the DB instance. timestamp The time at which the metrics were taken. uptime The amount of time that the DB instance has been active. version The version of the OS metrics' stream JSON format. idle The percentage of CPU that is idle. kern The percentage of CPU in use by the kernel. user The percentage of CPU in use by user programs. name The identifier for the disk. API Version 2014-10-31 257 Amazon Relational Database Service User Guide Viewing Enhanced Monitoring by Using CloudWatch Logs Group memory network processList Metrics Description totalKb The total space of the disk, in kilobytes. usedKb The amount of space used on the disk, in kilobytes. usedPc The percentage of space used on the disk. availKb The space available on the disk, in kilobytes. availPc The percentage of space available on the disk. rdCountPS The number of read operations per second rdBytesPS The number of bytes read per second. wrCountPS The number of write operations per second. wBytesPS The amount of bytes written per second. commitToKb The amount of pagefile-backed virtual address space in use, that is, the current commit charge. This value is composed of main memory (RAM) and disk (pagefiles). commitLimitKb The maximum possible value for the commitTotKb metric. This value is the sum of the current pagefile size plus the physical memory available for pageable contents–excluding RAM that is assigned to non-pageable areas. commitPeakKb The largest value of the commitTotKb metric since the operating system was last started. kernTotKb The sum of the memory in the paged and non-paged kernel pools, in kilobytes. kernPagedKb The amount of memory in the paged kernel pool, in kilobytes. kernNonpagedKb The amount of memory in the non-paged kernel pool, in kilobytes. pageSize The size of a page, in bytes. physTotKb The amount of physical memory, in kilobytes. physAvailKb The amount of available physical memory, in kilobytes. sqlServerTotKb The amount of memory committed to Microsoft SQL Server, in kilobytes. sysCacheKb The amount of system cache memory, in kilobytes. interface The identifier for the network interface being used for the DB instance. rdBytesPS The number of bytes received per second. wrBytesPS The number of bytes sent per second. cpuUsedPc The percentage of CPU used by the process. memUsedPc The percentage of total memory used by the process. API Version 2014-10-31 258 Amazon Relational Database Service User Guide Viewing Enhanced Monitoring by Using CloudWatch Logs Group Metrics Description name The name of the process. pid The identifier of the process. This value is not present for processes that are owned by Amazon RDS. ppid The process identifier for the parent of this process. This value is only present for child processes. tid The thread identifier. This value is only present for threads. The owning process can be identified by using the pid value. workingSetKb The amount of memory in the private working set plus the amount of memory that is in use by the process and can be shared with other processes, in kilobytes. workingSetPrivKbThe amount of memory that is in use by a process, but can't be shared with other processes, in kilobytes. workingSetShareableKb The amount of memory that is in use by a process and can be shared with other processes, in kilobytes. system virtKb The amount of virtual address space the process is using, in kilobytes. Use of virtual address space does not necessarily imply corresponding use of either disk or main memory pages. handles The number of handles that the system is using. processes The number of processes running on the system. threads The number of threads running on the system. API Version 2014-10-31 259 Amazon Relational Database Service User Guide Performance Insights Using Amazon RDS Performance Insights Amazon RDS Performance Insights monitors your Amazon RDS DB instance load so that you can analyze and troubleshoot your database performance. Amazon RDS Performance Insights is currently available for use with the following DB engines: • Amazon Aurora with MySQL compatibility version 1.17.3 and higher 1.x versions • Amazon RDS MySQL version 5.7.22 and higher 5.7 versions • Amazon RDS MySQL version 5.6.41 and higher 5.6 versions • Amazon Aurora with PostgreSQL compatibility • Amazon RDS PostgreSQL version 10 • Amazon RDS Oracle (all versions) Amazon RDS Performance Insights is not supported for MySQL 5.5 or MySQL 8.0. For information about using Amazon Aurora, see the Amazon Aurora User Guide. Note Performance Insights is not supported on db.t2 DB instance classes. Performance Insights expands on existing Amazon RDS monitoring features to illustrate your database's performance and help you analyze any issues that affect it. With the Performance Insights dashboard, you can visualize the database load and filter the load by waits, SQL statements, hosts, or users. Performance Insights is on by default in the console create wizard for the Amazon Aurora MySQL, Amazon RDS MySQL, Amazon Aurora PostgreSQL, and Amazon RDS PostgreSQL DB engines. If you have more than one database on the DB instance, performance data for all of the databases is aggregated for the DB instance. The central metric for Performance Insights is DB Load, which represents the average number of active sessions for the DB engine. An active session is a connection that has submitted work to the DB engine and is waiting for a response from it. For example, if you submit a SQL query to the DB engine, the database session is active while the DB engine is processing that query. By combining DB Load with wait event data, you can get a complete picture of the state for an active session. Wait events vary by DB engine: • For information about all MySQL wait events, see Wait Event Summary Tables in the MySQL documentation. • For information about all PostgreSQL wait events, see PostgreSQL Wait Events in the PostgreSQL documentation. • For information about all Oracle wait events, see Descriptions of Wait Events in the Oracle documentation. Note For Oracle, background processes sometimes do work without an associated SQL statement. In these cases, Performance Insights reports the type of background process (for example, LGWR, ARC0, PMON, and so on) concatenated with a colon and the wait class associated with that background process. For example, when the archiver is performing I/O, the Performance Insights report for it is similar to ARC1:System I/O. Occasionally, the background process type is missing as well, and Performance Insights only reports the wait class, for example :System I/O. Session information is collected, aggregated, and displayed in the dashboard as the Average Active Sessions chart. The Average Active Sessions chart displays the Max CPU value as a line, so you can see if API Version 2014-10-31 260 Amazon Relational Database Service User Guide Enabling Performance Insights active sessions are exceeding it or not. The Max CPU value is determined by the number of vCPU (virtual CPU) cores for your DB instance. If you find that the load in the Average Active Sessions chart is often above the Max CPU line and the primary wait state is CPU, the system CPU is overloaded. In these cases, you might want to throttle connections to the instance, tune any SQL queries with a high CPU load, or consider a larger instance class. High and consistent instances of any wait state indicate that there might be bottlenecks or resource contention issues that you should resolve, even if the load doesn't cross the Max CPU line. You can find an overview of Performance Insights in the following video. Using Performance Insights to Analyze Performance of Amazon Aurora PostgreSQL Topics • Enabling Performance Insights (p. 261) • Access Control for Performance Insights (p. 265) • Using the Performance Insights Dashboard (p. 266) • Additional User Interface Features (p. 270) • Performance Insights API (p. 271) • Performance Insights Metrics Published to Amazon CloudWatch (p. 271) • Logging Performance Insights Operations by Using AWS CloudTrail (p. 272) Enabling Performance Insights To use Performance Insights, you must enable it on your DB instance. AWS Management Console You can use the console to enable Performance Insights when you create a new DB instance. You can also modify a DB instance to enable Performance Insights. Topics • Enabling Performance Insights with the Console When Creating a DB Instance (p. 261) • Enabling Performance Insights with the Console When Modifying a DB Instance (p. 262) Enabling Performance Insights with the Console When Creating a DB Instance When you create a new DB instance, Performance Insights is enabled when you choose Enable Performance Insights in the Performance Insights section. To create a DB instance, follow the instructions for your DB engine in Creating an Amazon RDS DB Instance (p. 111). The following image shows the Performance Insights section. API Version 2014-10-31 261 Amazon Relational Database Service User Guide Enabling Performance Insights You have the following options when you choose Enable Performance Insights: • Retention – The amount of time to retain Performance Insights data. Choose either 7 days (the default) or 2 years. • Master key – Specify your AWS Key Management Service (AWS KMS) key. Performance Insights encrypts all potentially sensitive data using your AWS KMS key. Data is encrypted in flight and at rest. For more information, see Encrypting Amazon RDS Resources (p. 377). Enabling Performance Insights with the Console When Modifying a DB Instance You can modify a DB instance to enable Performance Insights using the console. To enable Performance Insights for a DB instance using the console 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. Choose Instances. 3. Choose the DB instance that you want to modify, and choose Modify in Instance actions. 4. In the Performance Insights section, choose Enable Performance Insights. You have the following options when you choose Enable Performance Insights: • Retention – The amount of time to retain Performance Insights data. Choose either 7 days (the default) or 2 years. • Master key – Specify your AWS Key Management Service (AWS KMS) key. Performance Insights encrypts all potentially sensitive data using your AWS KMS key. Data is encrypted in flight and at rest. For more information, see Encrypting Amazon RDS Resources (p. 377). 5. Choose Continue. 6. For Scheduling of Modifications, choose one of the following: • Apply during the next scheduled maintenance window – Wait to apply the Performance Insights modification until the next maintenance window. API Version 2014-10-31 262 Amazon Relational Database Service User Guide Enabling Performance Insights 7. • Apply immediately – Apply the Performance Insights modification as soon as possible. Choose Modify instance. CLI When you create a new DB instance using the create-db-instance AWS CLI command, Performance Insights is enabled when you specify --enable-performance-insights. You can also specify the --enable-performance-insights value using the following AWS CLI commands: • create-db-instance-read-replica • modify-db-instance • restore-db-instance-from-s3 The following procedure describes how to enable Performance Insights for a DB instance using the AWS CLI. To enable Performance Insights for a DB instance using the AWS CLI • Call the modify-db-instance AWS CLI command and supply the following values: • --db-instance-identifier – The name of the DB instance. • --enable-performance-insights The following example enables Performance Insights for sample-db-instance. For Linux, OS X, or Unix: aws rds modify-db-instance \ --db-instance-identifier sample-db-instance \ --enable-performance-insights For Windows: aws rds modify-db-instance ^ --db-instance-identifier sample-db-instance ^ --enable-performance-insights When you enable Performance Insights, you can optionally specify the amount of time, in days, to retain Performance Insights data with the --performance-insights-retention-period option. Valid values are 7 (the default) or 731 (2 years). The following example enables Performance Insights for sample-db-instance and specifies that Performance Insights data is retained for two years. For Linux, OS X, or Unix: aws rds modify-db-instance \ --db-instance-identifier sample-db-instance \ API Version 2014-10-31 263 Amazon Relational Database Service User Guide Enabling Performance Insights --enable-performance-insights \ --performance-insights-retention-period 731 For Windows: aws rds modify-db-instance ^ --db-instance-identifier sample-db-instance ^ --enable-performance-insights ^ --performance-insights-retention-period 731 API When you create a new DB instance using the CreateDBInstance action Amazon RDS API action, the Performance Schema is enabled when you set EnablePerformanceInsights to True. You can also specify the EnablePerformanceInsights value using the following API actions: • ModifyDBInstance • CreateDBInstanceReadReplica • RestoreDBInstanceFromS3 When you enable Performance Insights, you can optionally specify the amount of time, in days, to retain Performance Insights data with the PerformanceInsightsRetentionPeriod parameter. Valid values are 7 (the default) or 731 (2 years). Enabling Performance Insights for Amazon RDS MySQL For Amazon RDS MySQL, Performance Insights provides more detailed information when the Performance Schema feature of MySQL is enabled. The Performance Schema is enabled automatically when you create an Amazon RDS MySQL DB instance with Performance Insights enabled. When you create the DB instance with Performance Insights enabled, the following subset of Performance Schema parameters is set to the specified values automatically: • performance_schema=1 • performance-schema-consumer-events-waits-current=ON • performance-schema-instrument='wait/%=ON' • performance-schema-consumer-global-instrumentation=ON • performance-schema-consumer-thread-instrumentation=ON Performance Schema is enabled automatically only if your parameter group doesn't have an explicitly set value for the performance_schema parameter. You can examine the performance_schema parameter, and if the value of source is user, then you set a value. If you want the Performance Schema parameters to be set automatically, then unset the value for the performance_schema parameter. You can view the source of a parameter value by viewing the parameter in the AWS Management Console or by running the AWS CLI describe-db-parameters command. When you change the value of the performance_schema parameter, a DB instance reboot is required. If you're creating a new DB instance with Performance Insights enabled, the performance_schema parameter is set to 1 (enabled) by default. Without the Performance Schema enabled, Performance Insights displays database load broken down by the list state of the MySQL process. With Performance Schema enabled, Performance Insights displays database load broken down by detailed wait events. API Version 2014-10-31 264 Amazon Relational Database Service User Guide Access Control for Performance Insights For more information, see Using the Performance Insights Dashboard (p. 266). Access Control for Performance Insights To access Performance Insights, you must have the appropriate permissions from AWS Identity and Access Management (IAM). There are two options available for granting access: 1. Attach the AmazonRDSFullAccess managed policy to an IAM user or role. 2. Create a custom IAM policy and attach it to an IAM user or role. AmazonRDSFullAccess Managed Policy AmazonRDSFullAccess is an AWS-managed policy that grants access to all of the Amazon RDS API actions. The policy also grants access to related services that are used by the Amazon RDS console—for example, event notifications using Amazon SNS. In addition, AmazonRDSFullAccess contains all the permissions needed for using Performance Insights. If you attach this policy to an IAM user or role, the recipient can use Performance Insights, in addition to all of the other features of the Amazon RDS console. Using a Custom IAM Policy For users who don’t have full access with the AmazonRDSFullAccess policy, you can grant access to Performance Insights by creating or modifying a user-managed IAM policy. When you attach the policy to an IAM user or role, the recipient can use Performance Insights. To create a custom policy 1. Open the IAM console at https://console.aws.amazon.com/iam/. 2. In the navigation pane, choose Policies. 3. Choose Create policy. 4. On the Create Policy page, choose the JSON tab. 5. Copy and paste the following. { } 6. "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "pi:*", "Resource": "arn:aws:pi:*:*:metrics/rds/*" } ] Choose Review policy Note Currently, when you enter this policy, the Visual editor tab displays a warning that the pi resource is not recognized. You can ignore this warning. 7. Provide a name for the policy and optionally a description, and then choose Create policy. You can now attach the policy to an IAM user or role. The following procedure assumes that you already have an IAM user available for this purpose. API Version 2014-10-31 265 Amazon Relational Database Service User Guide Using the Performance Insights Dashboard To attach the policy to an IAM user 1. 2. 3. Open the IAM console at https://console.aws.amazon.com/iam/. In the navigation pane, choose Users. Choose an existing user from the list. Important To use Performance Insights, the user must have access to Amazon RDS in addition to the custom policy. For example, the AmazonRDSReadOnlyAccess predefined policy provides read-only access to Amazon RDS. For more information, see AWS Managed (Predefined) Policies for Amazon RDS (p. 337). 4. On the Summary page, choose Add permissions. 5. Choose Attach existing policies directly. For Search, type the first few characters of your policy name, as shown following. 6. Choose your policy, and then choose Next: Review. 7. Choose Add permissions. Using the Performance Insights Dashboard The Performance Insights dashboard contains database performance information to help you analyze and troubleshoot performance issues. On the main dashboard page, you can view information about the database load. You can also drill into details for a particular wait state, SQL query, host, or user. Topics • Opening the Performance Insights Dashboard (p. 266) • Performance Insights Dashboard Components (p. 268) • Analyzing Database Load Using the Performance Insights Dashboard (p. 269) Opening the Performance Insights Dashboard To see the Performance Insights dashboard, use the following procedure. To view the Performance Insights dashboard in the AWS Management Console 1. Open the Amazon RDS console at https://console.aws.amazon.com/rds/. API Version 2014-10-31 266 Amazon Relational Database Service User Guide Using the Performance Insights Dashboard 2. 3. In the navigation pane, choose Performance Insights. Choose a DB instance. The Performance Insights dashboard is displayed for that DB instance. For DB instances with Performance Insights enabled, you can also reach the dashboard by choosing the Sessions item in the list of DB instances. Under Current activity, the Sessions item shows the database load in average active sessions over the last five minutes. The bar graphically shows the load. When the bar is empty, the DB instance is idle. As the load increases, the bar fills with blue. When the load passes the number of virtual CPUs (vCPUs) on the DB instance class, the bar turns red, indicating a potential bottleneck. The following image shows the dashboard for a DB instance. By default, the Performance Insights dashboard shows data for the last 60 minutes. You can modify it to display data for the last 5 minutes, 60 minutes, 5 hours, 24 hours, or 1 week. You can also show all of the data available. The Performance Insight dashboard automatically refreshes with new data. The refresh rate depends on the amount of data displayed: • 5 minutes refreshes every 5 seconds. • 1 hour and 5 hours both refresh every minute. • 24 hours refreshes every 5 minutes. • 1 week refreshes every hour. API Version 2014-10-31 267 Amazon Relational Database Service User Guide Using the Performance Insights Dashboard Performance Insights Dashboard Components The dashboard is divided into two parts: 1. Average Active Sessions chart – Shows how the database load compares to DB instance capacity as represented by the Max CPU line. 2. Top load items table – Shows the top items contributing to database load. Average Active Sessions Chart The Average Active Sessions chart shows how the database load compares to DB instance capacity as represented by the Max CPU line. By default, load is shown as active sessions grouped by wait states. You can also choose instead to display load as active sessions grouped by SQL queries, hosts, or users. To see details for any item for the selected time period in the legend, hover over that item on the Average Active Sessions chart. API Version 2014-10-31 268 Amazon Relational Database Service User Guide Using the Performance Insights Dashboard Top Load Items Table The Top Load Items table shows the top items contributing to database load. By default, the top SQL queries that are contributing to the database load are shown. Queries are displayed as digests of multiple actual queries that are structurally similar but that possibly have different parameters. You can choose to display top wait states, hosts, or users instead. The percentage of the database load associated with each top load item is illustrated in the DB Load by Waits column. This column reflects the load for that item by whatever grouping is currently selected in the Average Active Sessions chart. Take the case where the Average Active Sessions chart is grouping by hosts and you are looking at SQL queries in the top load items table. In this case, the DB Load by Waits bar reflects the load that query represents on the related host. Here it's colored-coded to map to the representation of that host in the Average Active Sessions chart. For another example, suppose that the Average Active Sessions chart is grouping by wait states and you are looking at SQL queries in the top load items table. In this case, the DB Load by Waits bar is sized, segmented, and color-coded to show how much of a given wait state that query is contributing to. It also shows what wait states are affecting that query. Analyzing Database Load Using the Performance Insights Dashboard If the Average Active Sessions chart shows a bottleneck, you can find out where the load is coming from. To do so, look at the top load items table below the Average Active Sessions chart. Choose a particular item, like a SQL query or a user, to drill down into that item and see details about it. DB load grouped by waits and top SQL queries is the default Performance Insights dashboard view, because this is the combination that typically provides the most insight into performance issues. DB load grouped by waits shows if there are any resource or concurrency bottlenecks in the database. In this case, the SQL tab of the top load items table shows which queries are driving that load. API Version 2014-10-31 269 Amazon Relational Database Service User Guide Additional User Interface Features Your typical workflow for diagnosing performance issues is as follows: 1. Review the Average Active Sessions chart and see if there are any incidents of database load exceeding the Max CPU line. 2. If there is, look at the Average Active Sessions chart and identify which wait state or states are primarily responsible. 3. Identify the digest queries causing the load by seeing which of the queries the SQL tab on the top load items table are contributing most to those wait states. You can identify these by the DB Load by Wait column. 4. Choose one of these digest queries in the SQL tab to expand it and see the child queries that it is composed of. For example, in the dashboard following, IO:XactSync waits are a frequent issue. CPU wait is less, but it still contributes to load. The first four roll-up queries in the SQL tab of the top load items table correlate strongly to the first state. Thus, those are the ones to drill into and examine the child queries of. You do so to determine how they are contributing to the performance issue. The last three roll-up queries are the major contributors to CPU. These are the queries to investigate if CPU load is an issue. Additional User Interface Features You can use other features of the Performance Insights user interface to help analyze performance data. Click-and-Drag Zoom In In the Performance Insights interface, you can choose a small portion of the load chart and zoom in on the detail. To zoom in on a portion of the load chart, choose the start time and drag to the end of the time period you want. When you do this, the selected area is highlighted. When you release the mouse, the load chart zooms in on the selected region, and the Top N table is recalculated. API Version 2014-10-31 270 Amazon Relational Database Service User Guide Performance Insights API Pause and Zoom Out In the upper-right corner of the load chart, you can find the Pause and Zoom out tools. When you choose Pause, the load chart stops autorefreshing. When you choose Pause again, the chart resumes autorefreshing. When you choose Zoom out, the load chart zooms out to the next largest time interval. Performance Insights API The Amazon RDS Performance Insights API provides visibility into the performance of your RDS instance, when Performance Insights is enabled for supported engine types. Amazon CloudWatch Logs provides the authoritative source for vended monitoring metrics for AWS services. Performance Insights offers a domain-specific view of database load measured as average active sessions and provided to API consumers as a two-dimensional time-series dataset. The time dimension of the data provides database load data for each time point in the queried time range. Each time point decomposes overall load in relation to the requested dimensions, such as SQL, Wait-event, User, or Host, measured at that time point. For more information, see the Amazon RDS Performance Insights API Reference. Performance Insights Metrics Published to Amazon CloudWatch Performance Insights automatically publishes metrics to Amazon CloudWatch. Each of these per second metrics represents the average over the last 60 seconds. Metric Description DBLoad The average number of active sessions for the DB engine. DBLoadCPU The number of active sessions where the wait event type is CPU. DBLoadNonCPU The number of active sessions where the wait event type is not CPU. You can examine these metrics using the CloudWatch console, the AWS CLI, or the CloudWatch API. For example, you can get the statistics for the DBLoad metric by running the get-metric-statistics command. aws cloudwatch get-metric-statistics --region us-west-2 --namespace AWS/RDS --metric-name DBLoad --period 60 --statistics Sum --start-time 1532035185 --end-time 1532036185 -dimensions Name=DBInstanceIdentifier,Value=db-loadtest-0 API Version 2014-10-31 271 Amazon Relational Database Service User Guide Logging Performance Insights Operations by Using AWS CloudTrail This example generates output similar to the following. { "Datapoints": [ { "Timestamp": "2018-07-19T21:30:00Z", "Unit": "None", "Sum": 1380.0 }, { "Timestamp": "2018-07-19T21:34:00Z", "Unit": "None", "Sum": 1380.0 }, { "Timestamp": "2018-07-19T21:35:00Z", "Unit": "None", "Sum": 1380.0 }, { "Timestamp": "2018-07-19T21:31:00Z", "Unit": "None", "Sum": 1380.0 }, { "Timestamp": "2018-07-19T21:32:00Z", "Unit": "None", "Sum": 1380.0 }, { "Timestamp": "2018-07-19T21:29:00Z", "Unit": "None", "Sum": 8280.0 }, { "Timestamp": "2018-07-19T21:33:00Z", "Unit": "None", "Sum": 1380.0 } ], "Label": "DBLoad" } For more information about CloudWatch, see What is Amazon CloudWatch? in the Amazon CloudWatch User Guide. Logging Performance Insights Operations by Using AWS CloudTrail Performance Insights is integrated with AWS CloudTrail. CloudTrail captures low-level API requests made by or on behalf of Performance Insights in your AWS account and delivers the log files to an Amazon S3 bucket that you specify. CloudTrail captures calls made from the Performance Insights in the RDS console or from the Performance Insights low-level API. Using the information collected by CloudTrail, you can determine what request was made to Performance Insights. You can also determine the source IP address it was made from, who made it, when it was made, and so on. CloudTrail logging is automatically enabled in your AWS account. To learn more about CloudTrail, see the AWS CloudTrail User Guide. API Version 2014-10-31 272 Amazon Relational Database Service User Guide Logging Performance Insights Operations by Using AWS CloudTrail Any low-level API calls made to Performance Insights actions are tracked in log files. Performance Insights records are written together with other AWS service records in a log file. CloudTrail determines when to create and write to a new file based on a time period and file size. The following API operations are supported: • DescribeDimensionKeys • GetResourceMetrics API Version 2014-10-31 273 Amazon Relational Database Service User Guide Using Amazon RDS Recommendations Using Amazon RDS Recommendations Amazon RDS provides automated recommendations for database resources. These recommendations provide best practice guidance by analyzing DB instance configuration, usage, and performance data. You can find examples of these recommendations in the following table. Type Description Recommendation Additional Information Engine version outdated Your DB instance is not running the latest minor engine version. We recommend that you upgrade to the latest version because it contains the latest security fixes and other improvements. Upgrading a DB Instance Engine Version (p. 121) Pending maintenance available You have pending maintenance available on your DB instance. We recommend that you perform the pending maintenance available on your DB instance. Updates to the operating system most often occur for security issues and should be done as soon as possible. Maintaining a DB Instance (p. 115) Automated backups disabled Your DB instance has automated backups disabled. We recommend that you enable automated backups on your DB instance. Automated backups enable point-in-time recovery of your DB instance. You receive backup storage up to the storage size of your DB instance at no additional charge. Working With Backups (p. 202) Magnetic volumes in use Your DB instance is using magnetic storage. Magnetic storage is not recommended DB instance for most DB instances. We storage (p. 101) recommend switching to General Purpose (SSD) storage or provisioned IOPS storage. EC2-Classic platform in use Your DB instance is using the legacy EC2Classic platform. We recommend moving your DB instance to the EC2-VPC platform for better network access control. Amazon VPC provides a virtual network that is logically isolated from other virtual networks in the AWS Cloud. Determining Whether You Are Using the EC2VPC or EC2-Classic Platform (p. 400) Enhanced Monitoring disabled Your DB instance doesn't have Enhanced Monitoring enabled. We recommend enabling Enhanced Monitoring. Enhanced Monitoring provides real-time operating system metrics for monitoring and troubleshooting. Enhanced Monitoring (p. 250) Encryption disabled Your DB instance doesn't have encryption enabled. We recommend enabling encryption. You can encrypt your existing Amazon RDS DB instances by restoring from an encrypted snapshot. Encrypting Amazon RDS Resources (p. 377) Previous generation Your DB instance is running on a Previous-generation DB instance classes have been replaced by DB DB Instance Class (p. 80) API Version 2014-10-31 274 Amazon Relational Database Service User Guide Responding to Recommendations Type Description Recommendation DB instance class in use previous-generation DB instance class. instance classes with better price, better performance, or both. We recommend running your DB instance on a later generation DB instance class. Additional Information Amazon RDS generates recommendations periodically across all accounts and resources. Topics • Responding to Amazon RDS Recommendations (p. 275) Responding to Amazon RDS Recommendations You can find recommendations in the AWS Management Console. You can perform the recommended action immediately, schedule it for the next maintenance window, or dismiss it. To respond to Amazon RDS recommendations 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Recommendations. The Recommendations page appears. API Version 2014-10-31 275 Amazon Relational Database Service User Guide Responding to Recommendations 3. On the Recommendations page, choose one of the following: • Active – Shows the current recommendations that you can apply, dismiss, or schedule. • Dismissed – Shows the recommendations that have been dismissed. When you choose Dismissed, you can apply these dismissed recommendations. • Applied – Shows the recommendations that are currently applied. • Scheduled – Shows the recommendations that are scheduled but not yet applied. These recommendations will be applied in the next scheduled maintenance window. From any list of recommendations, you can open a section to view the recommendations in that section. API Version 2014-10-31 276 Amazon Relational Database Service User Guide Responding to Recommendations To configure preferences for displaying recommendations in each section, choose the Preferences icon. 4. From the Preferences window that appears, you can set display options. These options include the visible columns and the number of recommendations to display on the page. Manage your active recommendations: a. b. Choose Active and open one or more sections to view the recommendations in them. Choose one or more recommendations and choose Apply now (to apply them immediately), Apply in next maintenance window, or Dismiss. If the Apply now button appears for a recommendation but is unavailable (grayed out), the DB instance is not available. You can apply recommendations immediately only if the DB instance status is available. For example, you can't apply recommendations immediately to the DB instance if its status is modifying. In this case, wait for the DB instance to be available and apply the recommendation. If the Active button doesn't appear for a recommendation, you can't apply the recommendation using the Recommendations page. You can modify the DB instance to apply the recommendation manually. For more information about modifying a DB instance, see Modifying an Amazon RDS DB Instance and Using the Apply Immediately Parameter (p. 113). Note When you choose Apply now, a brief DB instance outage might result. API Version 2014-10-31 277 Amazon Relational Database Service User Guide Using Amazon RDS Event Notification Using Amazon RDS Event Notification Topics • Amazon RDS Event Categories and Event Messages (p. 279) • Subscribing to Amazon RDS Event Notification (p. 284) • Listing Your Amazon RDS Event Notification Subscriptions (p. 287) • Modifying an Amazon RDS Event Notification Subscription (p. 289) • Adding a Source Identifier to an Amazon RDS Event Notification Subscription (p. 291) • Removing a Source Identifier from an Amazon RDS Event Notification Subscription (p. 292) • Listing the Amazon RDS Event Notification Categories (p. 293) • Deleting an Amazon RDS Event Notification Subscription (p. 294) Amazon RDS uses the Amazon Simple Notification Service (Amazon SNS) to provide notification when an Amazon RDS event occurs. These notifications can be in any notification form supported by Amazon SNS for an AWS region, such as an email, a text message, or a call to an HTTP endpoint. Amazon RDS groups these events into categories that you can subscribe to so that you can be notified when an event in that category occurs. You can subscribe to an event category for a DB instance, DB snapshot, DB parameter group, or DB security group. For example, if you subscribe to the Backup category for a given DB instance, you will be notified whenever a backup-related event occurs that affects the DB instance. If you subscribe to a Configuration Change category for a DB security group, you will be notified when the DB security group is changed. You will also receive notification when an event notification subscription changes. Event notifications are sent to the addresses you provide when you create the subscription. You may want to create several different subscriptions, such as one subscription receiving all event notifications and another subscription that includes only critical events for your production DB instances. You can easily turn off notification without deleting a subscription by setting the Enabled radio button to No in the Amazon RDS console or by setting the Enabled parameter to false using the CLI or Amazon RDS API. Note Amazon RDS event notifications using SMS text messages are currently available for topic ARNs and Amazon RDS resources in the US-East (Northern Virginia) Region. For more information on using text messages with SNS, see Sending and Receiving SMS Notifications Using Amazon SNS. Amazon RDS uses the Amazon Resource Name (ARN) of an Amazon SNS topic to identify each subscription. The Amazon RDS console will create the ARN for you when you create the subscription. If you use the CLI or API, you have to create the ARN by using the Amazon SNS console or the Amazon SNS API when you create a subscription. Billing for Amazon RDS event notification is through the Amazon Simple Notification Service (Amazon SNS). Amazon SNS fees apply when using event notification; for more information on Amazon SNS billing, see Amazon Simple Notification Service Pricing. The process for subscribing to Amazon RDS event notification is as follows: 1. Create an Amazon RDS event notification subscription by using the Amazon RDS console, AWS CLI, or API. 2. Amazon RDS sends an approval email or SMS message to the addresses you submitted with your subscription. To confirm your subscription, choose the link in the notification you were sent. 3. When you have confirmed the subscription, the status of your subscription is updated in the Amazon RDS console's My Event Subscriptions section. 4. You will begin to receive event notifications. API Version 2014-10-31 278 Amazon Relational Database Service User Guide Amazon RDS Event Categories and Event Messages The following section lists all categories and events that you can be notified of. It also provides information about subscribing to and working with Amazon RDS event subscriptions. Amazon RDS Event Categories and Event Messages Amazon RDS generates a significant number of events in categories that you can subscribe to using the Amazon RDS Console, AWS CLI, or the API. Each category applies to a source type, which can be a DB instance, DB snapshot, DB security group, or DB parameter group. The following table shows the event category and a list of events when a DB instance is the source type. Categories and Events for the DB Instance Source Type Category Amazon RDS Event ID Description availability RDS-EVENT-0006 The DB instance is restarting due to a previous controlled shutdown, or a recovery. The DB instance will be unavailable until the restart completes. availability RDS-EVENT-0004 The DB instance is undergoing a controlled shutdown. availability RDS-EVENT-0022 An error has occurred while restarting MySQL or MariaDB. backup RDS-EVENT-0001 A backup of the DB instance has started. backup RDS-EVENT-0002 A backup of the DB instance is complete. configuration change RDS-EVENT-0009 The DB instance has been added to a security group. configuration change RDS-EVENT-0024 The DB instance is being converted to a Multi-AZ DB instance. configuration change RDS-EVENT-0030 The DB instance is being converted to a Single-AZ DB instance. configuration change RDS-EVENT-0012 The DB instance class for this DB instance is being changed. configuration change RDS-EVENT-0018 The current storage settings for this DB instance are being changed. configuration change RDS-EVENT-0011 A parameter group for this DB instance has changed. configuration change RDS-EVENT-0092 A parameter group for this DB instance has finished updating. configuration change RDS-EVENT-0028 Automatic backups for this DB instance have been disabled. configuration change RDS-EVENT-0032 Automatic backups for this DB instance have been enabled. configuration change RDS-EVENT-0033 There are [count] users that match the master user name. Users not tied to a specific host have been reset. API Version 2014-10-31 279 Amazon Relational Database Service User Guide Amazon RDS Event Categories and Event Messages Category Amazon RDS Event ID Description configuration change RDS-EVENT-0025 The DB instance has been converted to a Multi-AZ DB instance. configuration change RDS-EVENT-0029 The DB instance has been converted to a Single-AZ DB instance. configuration change RDS-EVENT-0014 The DB instance class for this DB instance has changed. configuration change RDS-EVENT-0017 The storage settings for this DB instance have changed. configuration change RDS-EVENT-0010 The DB instance has been removed from a security group. configuration change RDS-EVENT-0016 The master password for the DB instance has been reset. configuration change RDS-EVENT-0067 An attempt to reset the master password for the DB instance has failed. configuration change RDS-EVENT-0078 The Enhanced Monitoring configuration has been changed. creation RDS-EVENT-0005 A DB instance is being created. deletion RDS-EVENT-0003 The DB instance is being deleted. failover RDS-EVENT-0034 Amazon RDS is not attempting a requested failover because a failover recently occurred on the DB instance. failover RDS-EVENT-0013 A Multi-AZ failover that resulted in the promotion of a standby instance has started. failover RDS-EVENT-0015 A Multi-AZ failover that resulted in the promotion of a standby instance is complete. It may take several minutes for the DNS to transfer to the new primary DB instance. failover RDS-EVENT-0065 The instance has recovered from a partial failover. failover RDS-EVENT-0049 A Multi-AZ failover has completed. failover RDS-EVENT-0050 A Multi-AZ activation has started after a successful instance recovery. failover RDS-EVENT-0051 A Multi-AZ activation is complete. Your database should be accessible now. failure RDS-EVENT-0031 The DB instance has failed due to an incompatible configuration or an underlying storage issue. Begin a point-in-time-restore for the DB instance. failure RDS-EVENT-0036 The DB instance is in an incompatible network. Some of the specified subnet IDs are invalid or do not exist. API Version 2014-10-31 280 Amazon Relational Database Service User Guide Amazon RDS Event Categories and Event Messages Category Amazon RDS Event ID Description failure RDS-EVENT-0035 The DB instance has invalid parameters. For example, MySQL could not start because a memory-related parameter is set too high for this instance class, so the customer action would be to modify the memory parameter and reboot the DB instance. failure RDS-EVENT-0058 Error while creating Statspack user account PERFSTAT. Please drop the account before adding the Statspack option. failure RDS-EVENT-0079 Enhanced Monitoring cannot be enabled without the enhanced monitoring IAM role. For information on creating the enhanced monitoring IAM role, see To create an IAM role for Amazon RDS Enhanced Monitoring (p. 251). failure RDS-EVENT-0080 Enhanced Monitoring was disabled due to an error making the configuration change. It is likely that the enhanced monitoring IAM role is configured incorrectly. For information on creating the enhanced monitoring IAM role, see To create an IAM role for Amazon RDS Enhanced Monitoring (p. 251). failure RDS-EVENT-0081 The IAM role that you use to access your Amazon S3 bucket for SQL Server native backup and restore is configured incorrectly. For more information, see Setting Up for Native Backup and Restore (p. 524). low storage RDS-EVENT-0089 The DB instance has consumed more than 90% of its allocated storage. You can monitor the storage space for a DB instance using the Free Storage Space metric. For more information, see Viewing DB Instance Metrics (p. 248). low storage RDS-EVENT-0007 The allocated storage for the DB instance has been exhausted. To resolve this issue, you should allocate additional storage for the DB instance. For more information, see the RDS FAQ. You can monitor the storage space for a DB instance using the Free Storage Space metric. For more information, see Viewing DB Instance Metrics (p. 248). maintenance RDS-EVENT-0026 Offline maintenance of the DB instance is taking place. The DB instance is currently unavailable. maintenance RDS-EVENT-0027 Offline maintenance of the DB instance is complete. The DB instance is now available. notification RDS-EVENT-0044 Operator-issued notification. For more information, see the event message. notification RDS-EVENT-0047 Patching of the DB instance has completed. notification RDS-EVENT-0048 Patching of the DB instance has been delayed. API Version 2014-10-31 281 Amazon Relational Database Service User Guide Amazon RDS Event Categories and Event Messages Category Amazon RDS Event ID Description notification RDS-EVENT-0054 The MySQL storage engine you are using is not InnoDB, which is the recommended MySQL storage engine for Amazon RDS. For information about MySQL storage engines, see Supported Storage Engines for MySQL on Amazon RDS. notification RDS-EVENT-0055 The number of tables you have for your DB instance exceeds the recommended best practices for Amazon RDS. Please reduce the number of tables on your DB instance. For information about recommended best practices, see Amazon RDS Basic Operational Guidelines (p. 68). notification RDS-EVENT-0056 The number of databases you have for your DB instance exceeds the recommended best practices for Amazon RDS. Please reduce the number of databases on your DB instance. For information about recommended best practices, see Amazon RDS Basic Operational Guidelines (p. 68). notification RDS-EVENT-0064 The TDE key has been rotated. For information about recommended best practices, see Amazon RDS Basic Operational Guidelines (p. 68). notification RDS-EVENT-0084 You attempted to convert a DB instance to MultiAZ, but it contains in-memory file groups that are not supported for Multi-AZ. For more information, see Multi-AZ Deployments for Microsoft SQL Server (p. 541). notification RDS-EVENT-0087 The DB instance has been stopped. notification RDS-EVENT-0088 The DB instance has been started. notification RDS-EVENT-0154 The DB instance is being started due to it exceeding the maximum allowed time being stopped. read replica RDS-EVENT-0045 An error has occurred in the read replication process. For more information, see the event message. For information on troubleshooting Read Replica errors, see Troubleshooting a MySQL Read Replica Problem (p. 654). read replica RDS-EVENT-0046 The Read Replica has resumed replication. This message appears when you first create a Read Replica, or as a monitoring message confirming that replication is functioning properly. If this message follows an RDS-EVENT-0045 notification, then replication has resumed following an error or after replication was stopped. read replica RDS-EVENT-0057 Replication on the Read Replica was terminated. API Version 2014-10-31 282 Amazon Relational Database Service User Guide Amazon RDS Event Categories and Event Messages Category Amazon RDS Event ID Description read replica RDS-EVENT-0062 Replication on the Read Replica was manually stopped. read replica RDS-EVENT-0063 Replication on the Read Replica was reset. recovery RDS-EVENT-0020 Recovery of the DB instance has started. Recovery time will vary with the amount of data to be recovered. recovery RDS-EVENT-0021 Recovery of the DB instance is complete. recovery RDS-EVENT-0023 A manual backup has been requested but Amazon RDS is currently in the process of creating a DB snapshot. Submit the request again after Amazon RDS has completed the DB snapshot. recovery RDS-EVENT-0052 Recovery of the Multi-AZ instance has started. Recovery time will vary with the amount of data to be recovered. recovery RDS-EVENT-0053 Recovery of the Multi-AZ instance is complete. recovery RDS-EVENT-0066 The SQL Server DB instance is re-establishing its mirror. Performance will be degraded until the mirror is reestablished. A database was found with non-FULL recovery model. The recovery model was changed back to FULL and mirroring recovery was started. (: [,…])” restoration RDS-EVENT-0008 The DB instance has been restored from a DB snapshot. restoration RDS-EVENT-0019 The DB instance has been restored from a point-intime backup. security RDS-EVENT-0068 The CloudHSM Classic partition password was decrypted by the system. The following table shows the event category and a list of events when a DB parameter group is the source type. Categories and Events for the DB Parameter Group Source Type Category RDS Event ID Description configuration change RDS-EVENT-0037 The parameter group was modified. The following table shows the event category and a list of events when a DB security group is the source type. Categories and Events for the DB Security Group Source Type API Version 2014-10-31 283 Amazon Relational Database Service User Guide Subscribing to Amazon RDS Event Notification Category RDS Event ID Description configuration change RDS-EVENT-0038 The security group has been modified. failure RDS-EVENT-0039 The Amazon EC2 security group owned by [user] does not exist; authorization for the security group has been revoked. The following table shows the event category and a list of events when a DB snapshot is the source type. Categories and Events for the DB Snapshot Source Type Category RDS Event ID Description creation RDS-EVENT-0040 A manual DB snapshot is being created. deletion RDS-EVENT-0041 A DB snapshot has been deleted. creation RDS-EVENT-0042 A manual DB snapshot has been created. restoration RDS-EVENT-0043 A DB instance is being restored from a DB snapshot. notification RDS-EVENT-0059 Started the copy of the cross region DB snapshot [DB snapshot name] from source region [region name]. notification RDS-EVENT-0060 Finished the copy of the cross region DB snapshot [DB snapshot name] from source region [region name] in [time] minutes. notification RDS-EVENT-0061 The copy of a cross region DB snapshot failed. creation RDS-EVENT-0090 An automated DB snapshot is being created. creation RDS-EVENT-0091 An automated DB snapshot has been created. Subscribing to Amazon RDS Event Notification You can create an Amazon RDS event notification subscription so you can be notified when an event occurs for a given DB instance, DB snapshot, DB security group, or DB parameter group. The simplest way to create a subscription is with the RDS console. If you choose to create event notification subscriptions using the CLI or API, you must create an Amazon Simple Notification Service topic and subscribe to that topic with the Amazon SNS console or Amazon SNS API. You will also need to retain the Amazon Resource Name (ARN) of the topic because it is used when submitting CLI commands or API actions. For information on creating an SNS topic and subscribing to it, see Getting Started with Amazon SNS. You can specify the type of source you want to be notified of and the Amazon RDS source that triggers the event. These are defined by the SourceType (type of source) and the SourceIdentifier (the Amazon RDS source generating the event). If you specify both the SourceType and SourceIdentifier, such as SourceType = db-instance and SourceIdentifier = myDBInstance1, you will receive all the DB_Instance events for the specified source. If you specify a SourceType but do not specify a SourceIdentifier, you will receive notice of the events for that source type for all your Amazon RDS sources. If you do not specify either the SourceType nor the SourceIdentifier, you will be notified of events generated from all Amazon RDS sources belonging to your customer account. Note Event notifications might take up to five minutes to be delivered. API Version 2014-10-31 284 Amazon Relational Database Service User Guide Subscribing to Amazon RDS Event Notification AWS Management Console To subscribe to RDS event notification 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In navigation pane, choose Event Subscriptions. 3. In the Event subscriptions pane, choose Create event subscription. 4. In the Create event subscription dialog box, do the following: a. Type a name for the event notification subscription for Name. b. For Send notifications to, choose an existing Amazon SNS Amazon Resource Name (ARN) for an Amazon SNS topic, or choose create topic to enter the name of a topic and a list of recipients. c. For Source type, choose a source type. d. Choose Yes to enable the subscription. If you want to create the subscription but to not have notifications sent yet, choose No. e. Depending on the source type you selected, choose the event categories and sources that you want to receive event notifications for. f. Choose Create. The Amazon RDS console indicates that the subscription is being created. CLI To subscribe to RDS event notification, use the AWS CLI create-event-subscription command. Include the following required parameters: • --subscription-name • --sns-topic-arn Example For Linux, OS X, or Unix: aws rds create-event-subscription \ --subscription-name myeventsubscription \ --sns-topic-arn arn:aws:sns:us-east-1:802#########:myawsuser-RDS \ --enabled For Windows: aws rds create-event-subscription ^ --subscription-name myeventsubscription ^ --sns-topic-arn arn:aws:sns:us-east-1:802#########:myawsuser-RDS ^ --enabled API Version 2014-10-31 285 Amazon Relational Database Service User Guide Subscribing to Amazon RDS Event Notification API To subscribe to Amazon RDS event notification, call the Amazon RDS API function CreateEventSubscription. Include the following required parameters: • SubscriptionName • SnsTopicArn API Version 2014-10-31 286 Amazon Relational Database Service User Guide Listing Your Amazon RDS Event Notification Subscriptions Listing Your Amazon RDS Event Notification Subscriptions You can list your current Amazon RDS event notification subscriptions. AWS Management Console To list your current Amazon RDS event notification subscriptions 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Event subscriptions. The Event subscriptions pane shows all your event notification subscriptions. CLI To list your current Amazon RDS event notification subscriptions, use the AWS CLI describe-eventsubscriptions command. Example The following example describes all event subscriptions. aws rds describe-event-subscriptions The following example describes the myfirsteventsubscription. aws rds describe-event-subscriptions --subscription-name myfirsteventsubscription API To list your current Amazon RDS event notification subscriptions, call the Amazon RDS API DescribeEventSubscriptions action. Example The following code example lists up to 100 event subscriptions. https://rds.us-east-1.amazonaws.com/ ?Action=DescribeEventSubscriptions API Version 2014-10-31 287 Amazon Relational Database Service User Guide Listing Your Amazon RDS Event Notification Subscriptions &MaxRecords=100 &SignatureMethod=HmacSHA256 &SignatureVersion=4 &Version=2014-09-01 &X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIADQKE4SARGYLE/20140428/us-east-1/rds/aws4_request &X-Amz-Date=20140428T161907Z &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date &X-Amz-Signature=4208679fe967783a1a149c826199080a066085d5a88227a80c6c0cadb3e8c0d4 The following example describes the myfirsteventsubscription. https://rds.us-east-1.amazonaws.com/ ?Action=DescribeEventSubscriptions &SignatureMethod=HmacSHA256 &SignatureVersion=4 &SubscriptionName=myfirsteventsubscription &Version=2014-09-01 &X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIADQKE4SARGYLE/20140428/us-east-1/rds/aws4_request &X-Amz-Date=20140428T161907Z &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date &X-Amz-Signature=4208679fe967783a1a149c826199080a066085d5a88227a80c6c0cadb3e8c0d4 API Version 2014-10-31 288 Amazon Relational Database Service User Guide Modifying an Amazon RDS Event Notification Subscription Modifying an Amazon RDS Event Notification Subscription After you have created a subscription, you can change the subscription name, source identifier, categories, or topic ARN. AWS Management Console To modify an Amazon RDS event notification subscription 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Event subscriptions. 3. In the Event subscriptions pane, choose the subscription that you want to modify and choose Edit. 4. Make your changes to the subscription in either the Target or Source sections. 5. Choose Edit. The Amazon RDS console indicates that the subscription is being modified. CLI To modify an Amazon RDS event notification subscription, use the AWS CLI modify-eventsubscription command. Include the following required parameter: • --subscription-name Example The following code enables myeventsubscription. For Linux, OS X, or Unix: aws rds modify-event-subscription \ --subscription-name myeventsubscription \ --enabled For Windows: aws rds modify-event-subscription ^ --subscription-name myeventsubscription ^ --enabled API To modify an Amazon RDS event, call the Amazon RDS API action ModifyEventSubscription. Include the following required parameter: • SubscriptionName API Version 2014-10-31 289 Amazon Relational Database Service User Guide Modifying an Amazon RDS Event Notification Subscription API Version 2014-10-31 290 Amazon Relational Database Service User Guide Adding a Source Identifier to an Amazon RDS Event Notification Subscription Adding a Source Identifier to an Amazon RDS Event Notification Subscription You can add a source identifier (the Amazon RDS source generating the event) to an existing subscription. AWS Management Console You can easily add or remove source identifiers using the Amazon RDS console by selecting or deselecting them when modifying a subscription. For more information, see Modifying an Amazon RDS Event Notification Subscription (p. 289). CLI To add a source identifier to an Amazon RDS event notification subscription, use the AWS CLI addsource-identifier-to-subscription command. Include the following required parameters: • --subscription-name • --source-identifier Example The following example adds the source identifier mysqldb to the myrdseventsubscription subscription. For Linux, OS X, or Unix: aws rds add-source-identifier-to-subscription \ --subscription-name myrdseventsubscription \ --source-identifier mysqldb For Windows: aws rds add-source-identifier-to-subscription ^ --subscription-name myrdseventsubscription ^ --source-identifier mysqldb API To add a source identifier to an Amazon RDS event notification subscription, call the Amazon RDS API AddSourceIdentifierToSubscription. Include the following required parameters: • SubscriptionName • SourceIdentifier API Version 2014-10-31 291 Amazon Relational Database Service User Guide Removing a Source Identifier from an Amazon RDS Event Notification Subscription Removing a Source Identifier from an Amazon RDS Event Notification Subscription You can remove a source identifier (the Amazon RDS source generating the event) from a subscription if you no longer want to be notified of events for that source. AWS Management Console You can easily add or remove source identifiers using the Amazon RDS console by selecting or deselecting them when modifying a subscription. For more information, see Modifying an Amazon RDS Event Notification Subscription (p. 289). CLI To remove a source identifier from an Amazon RDS event notification subscription, use the AWS CLI remove-source-identifier-from-subscription command. Include the following required parameters: • --subscription-name • --source-identifier Example The following example removes the source identifier mysqldb from the myrdseventsubscription subscription. For Linux, OS X, or Unix: aws rds remove-source-identifier-from-subscription \ --subscription-name myrdseventsubscription \ --source-identifier mysqldb For Windows: aws rds remove-source-identifier-from-subscription ^ --subscription-name myrdseventsubscription ^ --source-identifier mysqldb API To remove a source identifier from an Amazon RDS event notification subscription, use the Amazon RDS API RemoveSourceIdentifierFromSubscription command. Include the following required parameters: • SubscriptionName • SourceIdentifier API Version 2014-10-31 292 Amazon Relational Database Service User Guide Listing the Amazon RDS Event Notification Categories Listing the Amazon RDS Event Notification Categories All events for a resource type are grouped into categories. To view the list of categories available, use the following procedures. AWS Management Console When you create or modify an event notification subscription, the event categories are displayed in the Amazon RDS console. See the topic Modifying an Amazon RDS Event Notification Subscription (p. 289) for more information. CLI To list the Amazon RDS event notification categories, use the AWS CLI describe-event-categories command. This command has no required parameters. Example aws rds describe-event-categories API To list the Amazon RDS event notification categories, use the Amazon RDS API DescribeEventCategories command. This command has no required parameters. API Version 2014-10-31 293 Amazon Relational Database Service User Guide Deleting an Amazon RDS Event Notification Subscription Deleting an Amazon RDS Event Notification Subscription You can delete a subscription when you no longer need it. All subscribers to the topic will no longer receive event notifications specified by the subscription. AWS Management Console To delete an Amazon RDS event notification subscription 1. 2. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. In the navigation pane, choose DB Event Subscriptions. 3. In the My DB Event Subscriptions pane, choose the subscription that you want to delete. 4. Choose Delete. 5. The Amazon RDS console indicates that the subscription is being deleted. CLI To delete an Amazon RDS event notification subscription, use the AWS CLI delete-eventsubscription command. Include the following required parameter: • --subscription-name Example The following example deletes the subscription myrdssubscription. delete-event-subscription --subscription-name myrdssubscription API To delete an Amazon RDS event notification subscription, use the RDS API DeleteEventSubscription command. Include the following required parameter: • SubscriptionName API Version 2014-10-31 294 Amazon Relational Database Service User Guide Viewing Amazon RDS Events Viewing Amazon RDS Events Amazon RDS keeps a record of events that relate to your DB instances, DB snapshots, DB security groups, and DB parameter groups. This information includes the date and time of the event, the source name and source type of the event, and a message associated with the event. You can retrieve events for your RDS resources through the AWS Management Console, which shows events from the past 24 hours. You can also retrieve events for your RDS resources by using the describeevents AWS CLI command, or the DescribeEvents RDS API action. If you use the AWS CLI or the RDS API to view events, you can retrieve events for up to the past 14 days. AWS Management Console To view all Amazon RDS instance events for the past 24 hours 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Events. The available events appear in a list. 3. Use the Filter list to filter the events by type, and use the text box to the right of the Filter list to further filter your results. For example, the following screenshot shows a list of events filtered by the DB instance event type and containing the characters 1318. CLI To view all Amazon RDS instance events for the past 7 days You can view all Amazon RDS instance events for the past 7 days by calling the describe-events AWS CLI command and setting the --duration parameter to 10080. aws rds describe-events --duration 10080 API To view all Amazon RDS instance events for the past 14 days You can view all Amazon RDS instance events for the past 14 days by calling the DescribeEvents RDS API action and setting the Duration parameter to 20160. https://rds.us-west-2.amazonaws.com/ ?Action=DescribeEvents API Version 2014-10-31 295 Amazon Relational Database Service User Guide API &Duration=20160 &MaxRecords=100 &SignatureMethod=HmacSHA256 &SignatureVersion=4 &Version=2014-09-01 &X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIADQKE4SARGYLE/20140421/us-west-2/rds/aws4_request &X-Amz-Date=20140421T194733Z &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date &X-Amz-Signature=8e313cabcdbd9766c56a2886b5b298fd944e0b7cfa248953c82705fdd0374f27 API Version 2014-10-31 296 Amazon Relational Database Service User Guide Database Log Files Amazon RDS Database Log Files You can view, download, and watch database logs using the Amazon RDS console, the AWS Command Line Interface (AWS CLI), or the Amazon RDS API. Viewing, downloading, or watching transaction logs is not supported. For engine-specific information, see the following: • MariaDB Database Log Files (p. 301) • Microsoft SQL Server Database Log Files (p. 309) • MySQL Database Log Files (p. 310) • Oracle Database Log Files (p. 318) • PostgreSQL Database Log Files (p. 324) Viewing and Listing Database Log Files You can view database log files for your DB engine by using the Amazon RDS console. You can list what log files are available for download or monitoring by using the AWS CLI or Amazon RDS API. Note If you can't view the list of log files for an existing Oracle DB instance, reboot the instance to view the list. AWS Management Console To view a database log file 1. 2. Open the Amazon RDS console at https://console.aws.amazon.com/rds/. In the navigation pane, choose Instances. 3. 4. Click the name of the DB instance that has the log file that you want to view. Scroll down to the Logs section. 5. In the Logs section, choose the log you wish to view and then choose View. AWS CLI To list the available database log files for a DB instance, use the AWS CLI describe-db-log-files command. The following example returns a list of log files for a DB instance named my-db-instance. Example aws rds describe-db-log-files --db-instance-identifier my-db-instance API To list the available database log files for a DB instance, use the Amazon RDS API DescribeDBLogFiles action. Downloading a Database Log File You can use the Amazon RDS console, AWS CLI or API to download a database log file. API Version 2014-10-31 297 Amazon Relational Database Service User Guide Downloading a Database Log File AWS Management Console To download a database log file 1. Open the Amazon RDS console at https://console.aws.amazon.com/rds/. 2. In the navigation pane, choose Instances. 3. Click the name of the DB instance that has the log file that you want to view. 4. Scroll down to the Logs section. 5. In the Logs section, choose the button next to the log you want to download, and then choose Download. 6. Open the context (right-click) menu for the link provided, and then choose Save Link As. Type the location where you want the log file to be saved, and then choose Save. AWS CLI To download a database log file, use the AWS CLI command download-db-log-file-portion. By default, this command will download only the latest portion of a log file; however, you can download an entire file by specifying the parameter --starting-token 0. The following example shows how to download the entire contents of a log file called log/ERROR.4 and store it in a local file called errorlog.txt. Example For Linux, OS X, or Unix: aws rds download-db-log-file-portion \ --db-instance-identifier myexampledb \ --starting-token 0 --output text \ --log-file-name log/ERROR.4 > errorlog.txt For Windows: aws rds download-db-log-file-portion ^ --db-instance-identifier myexampledb ^ --starting-token 0 --output text ^ --log-file-name log/ERROR.4 > errorlog.txt RDS API To download a database log file, use the Amazon RDS API DownloadDBLogFilePortion action. API Version 2014-10-31 298 Amazon Relational Database Service User Guide Watching a Database Log File Watching a Database Log File You can monitor the contents of a log file by using the Amazon RDS console. AWS Management Console To watch a database log file 1. 2. 3. Open the Amazon RDS console at https://console.aws.amazon.com/rds/. In the navigation pane, choose Instances. Click the name of the DB instance that has the log file that you want to view. 4. In the Logs pane, choose a log file, and then choose Watch. Publishing Database Logs to Amazon CloudWatch Logs In addition to viewing and downloading DB instance logs, you can publish logs to Amazon CloudWatch Logs. CloudWatch Logs lets you perform real-time analysis of the log data, store the data in highly durable storage,and manage the data with the CloudWatch Logs Agent. AWS retains log data published to CloudWatch Logs for an indefinite time period unless you specify a retention period. For more information, see Change Log Data Retention in CloudWatch Logs. For engine-specific information, see the following: • the section called “Publishing MariaDB Logs to CloudWatch Logs” (p. 302) • the section called “Publishing MySQL Logs to CloudWatch Logs” (p. 311) • the section called “Publishing Oracle Logs to Amazon CloudWatch Logs” (p. 320) Reading Log File Contents Using REST Amazon RDS provides a REST endpoint that allows access to DB instance log files. This is useful if you need to write an application to stream Amazon RDS log file contents. The syntax is: GET /v13/downloadCompleteLogFile/DBInstanceIdentifier/LogFileName HTTP/1.1 Content-type: application/json host: rds.region.amazonaws.com The following parameters are required: • DBInstanceIdentifier—the name of the DB instance that contains the log file you want to download. • LogFileName—the name of the log file to be downloaded. The response contains the contents of the requested log file, as a stream. The following example downloads the log file named log/ERROR.6 for the DB instance named sample-sql in the us-west-2 region. GET /v13/downloadCompleteLogFile/sample-sql/log/ERROR.6 HTTP/1.1 API Version 2014-10-31 299 Amazon Relational Database Service User Guide Reading Log File Contents Using REST host: rds.us-west-2.amazonaws.com X-Amz-Security-Token: AQoDYXdzEIH////////// wEa0AIXLhngC5zp9CyB1R6abwKrXHVR5efnAVN3XvR7IwqKYalFSn6UyJuEFTft9nObglx4QJ+GXV9cpACkETq= X-Amz-Date: 20140903T233749Z X-Amz-Algorithm: AWS4-HMAC-SHA256 X-Amz-Credential: AKIADQKE4SARGYLE/20140903/us-west-2/rds/aws4_request X-Amz-SignedHeaders: host X-Amz-Content-SHA256: e3b0c44298fc1c229afbf4c8996fb92427ae41e4649b934de495991b7852b855 X-Amz-Expires: 86400 X-Amz-Signature: 353a4f14b3f250142d9afc34f9f9948154d46ce7d4ec091d0cdabbcf8b40c558 If you specify a nonexistent DB instance, the response consists of the following error: • DBInstanceNotFound—DBInstanceIdentifier does not refer to an existing DB instance. (HTTP status code: 404) API Version 2014-10-31 300 Amazon Relational Database Service User Guide MariaDB Database Log Files MariaDB Database Log Files You can monitor the MariaDB error log, slow query log, and the general log. The MariaDB error log is generated by default; you can generate the slow query and general logs by setting parameters in your DB parameter group. Amazon RDS rotates all of the MariaDB log files; the intervals for each type are given following. You can monitor the MariaDB logs directly through the Amazon RDS console, Amazon RDS API, Amazon RDS CLI, or AWS SDKs. You can also access MariaDB logs by directing the logs to a database table in the main database and querying that table. You can use the mysqlbinlog utility to download a binary log. For more information about viewing, downloading, and watching file-based database logs, see Amazon RDS Database Log Files (p. 297). Accessing MariaDB Error Logs The MariaDB error log is written to the .err file. You can view this file by using the Amazon RDS console or by retrieving the log using the Amazon RDS API, Amazon RDS CLI, or AWS SDKs. The .err file is flushed every 5 minutes, and its contents are appended to mysql-errorrunning.log. The mysql-error-running.log file is then rotated every hour and the hourly files generated during the last 24 hours are retained. Each log file has the hour it was generated (in UTC) appended to its name. The log files also have a timestamp that helps you determine when the log entries were written. MariaDB writes to the error log only on startup, shutdown, and when it encounters errors. A DB instance can go hours or days without new entries being written to the error log. If you see no recent entries, it's because the server did not encounter an error that resulted in a log entry. Accessing the MariaDB Slow Query and General Logs The MariaDB slow query log and the general log can be written to a file or a database table by setting parameters in your DB parameter group. For information about creating and modifying a DB parameter group, see Working with DB Parameter Groups (p. 165). You must set these parameters before you can view the slow query log or general log in the Amazon RDS console or by using the Amazon RDS API, AWS CLI, or AWS SDKs. You can control MariaDB logging by using the parameters in this list: • slow_query_log: To create the slow query log, set to 1. The default is 0. • general_log: To create the general log, set to 1. The default is 0. • long_query_time: To prevent fast-running queries from being logged in the slow query log, specify a value for the shortest query execution time to be logged, in seconds. The default is 10 seconds; the minimum is 0. If log_output = FILE, you can specify a floating point value that goes to microsecond resolution. If log_output = TABLE, you must specify an integer value with second resolution. Only queries whose execution time exceeds the long_query_time value are logged. For example, setting long_query_time to 0.1 prevents any query that runs for less than 100 milliseconds from being logged. • log_queries_not_using_indexes: To log all queries that do not use an index to the slow query log, set this parameter to 1. The default is 0. Queries that do not use an index are logged even if their execution time is less than the value of the long_query_time parameter. • log_output option: You can specify one of the following options for the log_output parameter: • TABLE (default)– Write general queries to the mysql.general_log table, and slow queries to the mysql.slow_log table. • FILE– Write both general and slow query logs to the file system. Log files are rotated hourly. API Version 2014-10-31 301 Amazon Relational Database Service User Guide MariaDB Database Log Files • NONE– Disable logging. When logging is enabled, Amazon RDS rotates table logs or deletes log files at regular intervals. This measure is a precaution to reduce the possibility of a large log file either blocking database use or affecting performance. FILE and TABLE logging approach rotation and deletion as follows: • When FILE logging is enabled, log files are examined every hour and log files older than 24 hours are deleted. In some cases, the remaining combined log file size after the deletion might exceed the threshold of 2 percent of a DB instance's allocated space. In these cases, the largest log files are deleted until the log file size no longer exceeds the threshold. • When TABLE logging is enabled, in some cases log tables are rotated every 24 hours. This rotation occurs if the space used by the table logs is more than 20 percent of the allocated storage space or the size of all logs combined is greater than 10 GB. If the amount of space used for a DB instance is greater than 90 percent of the DB instance's allocated storage space, then the thresholds for log rotation are reduced. Log tables are then rotated if the space used by the table logs is more than 10 percent of the allocated storage space or the size of all logs combined is greater than 5 GB. When log tables are rotated, the current log table is copied to a backup log table and the entries in the current log table are removed. If the backup log table already exists, then it is deleted before the current log table is copied to the backup. You can query the backup log table if needed. The backup log table for the mysql.general_log table is named mysql.general_log_backup. The backup log table for the mysql.slow_log table is named mysql.slow_log_backup. You can rotate the mysql.general_log table by calling the mysql.rds_rotate_general_log procedure. You can rotate the mysql.slow_log table by calling the mysql.rds_rotate_slow_log procedure. Table logs are rotated during a database version upgrade. Amazon RDS records both TABLE and FILE log rotation in an Amazon RDS event and sends you a notification. To work with the logs from the Amazon RDS console, Amazon RDS API, Amazon RDS CLI, or AWS SDKs, set the log_output parameter to FILE. Like the MariaDB error log, these log files are rotated hourly. The log files that were generated during the previous 24 hours are retained. For more information about the slow query and general logs, go to the following topics in the MariaDB documentation: • Slow Query Log • General Query Log Publishing MariaDB Logs to CloudWatch Logs You can configure your Amazon RDS MariaDB DB instance to publish log data to a log group in Amazon CloudWatch Logs. With CloudWatch Logs, you can perform real-time analysis of the log data, and use CloudWatch to create alarms and view metrics. You can use CloudWatch Logs to store your log records in highly durable storage. Amazon RDS publishes each MariaDB database log as a separate database stream in the log group. For example, if you configure the export function to include the slow query log, slow query data is stored in a slow query log stream in the /aws/rds/instance/my_instance/slowquery log group. The error log is enabled by default. The following table summarizes the requirements for the other MariaDB logs. API Version 2014-10-31 302 Amazon Relational Database Service User Guide MariaDB Database Log Files Log Requirement Audit log The DB instance must use a custom option group with the MARIADB_AUDIT_PLUGIN option. General log The DB instance must use a custom parameter group with the parameter setting general_log = 1 to enable the general log. Slow query log The DB instance must use a custom parameter group with the parameter setting slow_query_log = 1 to enable the slow query log. Log output The DB instance must use a custom parameter group with the parameter setting log_output = FILE to write logs to the file system and publish them to CloudWatch Logs. AWS Management Console To publish MariaDB logs to CloudWatch Logs from the console 1. Open the Amazon RDS console at https://console.aws.amazon.com/rds/. 2. In the navigation pane, choose Instances, and then select the DB instance that you want to modify. 3. For Instance actions, choose Modify. 4. In the Log exports section, choose the logs you want to start publishing to CloudWatch Logs. 5. Choose Continue, and then choose Modify DB Instance on the summary page. AWS CLI You can publish a MariaDB logs with the AWS CLI. You can call the modify-db-instance command with the following parameters: • --db-instance-identifier • --cloudwatch-logs-export-configuration • --apply-immediately You can also publish MariaDB logs by calling the following AWS CLI commands: • create-db-instance • restore-db-instance-from-db-snapshot • restore-db-instance-from-s3 • restore-db-instance-to-point-in-time Run one of these AWS CLI commands with the following options: • --db-instance-identifier • --enable-cloudwatch-logs-exports • --db-instance-class • --engine API Version 2014-10-31 303 Amazon Relational Database Service User Guide MariaDB Database Log Files Other options might be required depending on the AWS CLI command you run. Example The following example modifies an existing MariaDB DB instance to publish log files to CloudWatch Logs. The --cloudwatch-logs-export-configuration value is a JSON object. The key for this object is EnableLogTypes, and its value is an array of strings with any combination of audit, error, general, and slowquery. For Linux, OS X, or Unix: aws rds modify-db-instance \ --db-instance-identifier mydbinstance \ --cloudwatch-logs-export-configuration '{"EnableLogTypes": ["audit","error","general","slowquery"]}' \ --apply-immediately For Windows: aws rds modify-db-instance ^ --db-instance-identifier mydbinstance ^ --cloudwatch-logs-export-configuration '{"EnableLogTypes": ["audit","error","general","slowquery"]}' ^ --apply-immediately Example The following command creates a MariaDB DB instance and publishes log files to CloudWatch Logs. The --enable-cloudwatch-logs-exports value is a JSON array of strings. The strings can be any combination of audit, error, general, and slowquery. For Linux, OS X, or Unix: aws rds create-db-instance \ --db-instance-identifier mydbinstance \ --enable-cloudwatch-logs-exports '["audit","error","general","slowquery"]' \ --db-instance-class db.m4.large \ --engine mariadb For Windows: aws rds create-db-instance ^ --db-instance-identifier mydbinstance ^ --enable-cloudwatch-logs-exports '["audit","error","general","slowquery"]' ^ --db-instance-class db.m4.large ^ --engine mariadb RDS API You can publish MariaDB logs with the RDS API. You can call the ModifyDBInstance action with the following parameters: • DBInstanceIdentifier • CloudwatchLogsExportConfiguration • ApplyImmediately API Version 2014-10-31 304 Amazon Relational Database Service User Guide MariaDB Database Log Files You can also publish MariaDB logs by calling the following RDS API actions: • CreateDBInstance • RestoreDBInstanceFromDBSnapshot • RestoreDBInstanceFromS3 • RestoreDBInstanceToPointInTime Run one of these RDS API actions with the following parameters: • DBInstanceIdentifier • EnableCloudwatchLogsExports • Engine • DBInstanceClass Other parameters might be required depending on the AWS CLI command you run. Log File Size The MariaDB slow query log, error log, and the general log file sizes are constrained to no more than 2 percent of the allocated storage space for a DB instance. To maintain this threshold, logs are automatically rotated every hour and log files older than 24 hours are removed. If the combined log file size exceeds the threshold after removing old log files, then the largest log files are deleted until the log file size no longer exceeds the threshold. Managing Table-Based MariaDB Logs You can direct the general and slow query logs to tables on the DB instance by creating a DB parameter group and setting the log_output server parameter to TABLE. General queries are then logged to the mysql.general_log table, and slow queries are logged to the mysql.slow_log table. You can query the tables to access the log information. Enabling this logging increases the amount of data written to the database, which can degrade performance. Both the general log and the slow query logs are disabled by default. In order to enable logging to tables, you must also set the general_log and slow_query_log server parameters to 1. Log tables keep growing until the respective logging activities are turned off by resetting the appropriate parameter to 0. A large amount of data often accumulates over time, which can use up a considerable percentage of your allocated storage space. Amazon RDS does not allow you to truncate the log tables, but you can move their contents. Rotating a table saves its contents to a backup table and then creates a new empty log table. You can manually rotate the log tables with the following command line procedures, where the command prompt is indicated by PROMPT>: PROMPT> CALL mysql.rds_rotate_slow_log; PROMPT> CALL mysql.rds_rotate_general_log; To completely remove the old data and reclaim the disk space, call the appropriate procedure twice in succession. Binary Logging Format MariaDB on Amazon RDS supports the row-based, statement-based, and mixed binary logging formats. The default binary logging format is mixed. For details on the different MariaDB binary log formats, see Binary Log Formats in the MariaDB documentation. API Version 2014-10-31 305 Amazon Relational Database Service User Guide MariaDB Database Log Files If you plan to use replication, the binary logging format is important because it determines the record of data changes that is recorded in the source and sent to the replication targets. For information about the advantages and disadvantages of different binary logging formats for replication, see Advantages and Disadvantages of Statement-Based and Row-Based Replication in the MySQL documentation. Important Setting the binary logging format to row-based can result in very large binary log files. Large binary log files reduce the amount of storage available for a DB instance and can increase the amount of time to perform a restore operation of a DB instance. Statement-based replication can cause inconsistencies between the source DB instance and a Read Replica. For more information, see Unsafe Statements for Statement-based Replication in the MariaDB documentation. To set the MariaDB binary logging format 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the navigation pane, choose Parameter groups. 3. Choose the parameter group used by the DB instance you want to modify. You can't modify a default parameter group. If the DB instance is using a default parameter group, create a new parameter group and associate it with the DB instance. For more information on DB parameter groups, see Working with DB Parameter Groups (p. 165). 4. From Parameter group actions, choose Edit. 5. Set the binlog_format parameter to the binary logging format of your choice (ROW, STATEMENT, or MIXED). 6. Choose Save changes to save the updates to the DB parameter group. Accessing MariaDB Binary Logs You can use the mysqlbinlog utility to download binary logs in text format from MariaDB DB instances. The binary log is downloaded to your local computer. For more information about using the mysqlbinlog utility, go to Using mysqlbinlog in the MariaDB documentation. To run the mysqlbinlog utility against an Amazon RDS instance, use the following options: • Specify the --read-from-remote-server option. • --host: Specify the DNS name from the endpoint of the instance. • --port: Specify the port used by the instance. • --user: Specify a MariaDB user that has been granted the replication slave permission. • --password: Specify the password for the user, or omit a password value so the utility prompts you for a password. • --result-file: Specify the local file that receives the output. • Specify the names of one or more binary log files. To get a list of the available logs, use the SQL command SHOW BINARY LOGS. For more information about mysqlbinlog options, go to mysqlbinlog Options in the MariaDB documentation. The following is an example: For Linux, OS X, or Unix: API Version 2014-10-31 306 Amazon Relational Database Service User Guide MariaDB Database Log Files mysqlbinlog \ --read-from-remote-server \ --host=mariadbinstance1.1234abcd.region.rds.amazonaws.com \ --port=3306 \ --user ReplUser \ --password \ --result-file=/tmp/binlog.txt For Windows: mysqlbinlog ^ --read-from-remote-server ^ --host=mariadbinstance1.1234abcd.region.rds.amazonaws.com ^ --port=3306 ^ --user ReplUser ^ --password ^ --result-file=/tmp/binlog.txt Amazon RDS normally purges a binary log as soon as possible, but the binary log must still be available on the instance to be accessed by mysqlbinlog. To specify the number of hours for RDS to retain binary logs, use the mysql.rds_set_configuration stored procedure and specify a period with enough time for you to download the logs. After you set the retention period, monitor storage usage for the DB instance to ensure that the retained binary logs do not take up too much storage. The following example sets the retention period to 1 day: call mysql.rds_set_configuration('binlog retention hours', 24); To display the current setting, use the mysql.rds_show_configuration stored procedure: call mysql.rds_show_configuration; Binary Log Annotation In a MariaDB DB instance, you can use the Annotate_rows event to annotate a row event with a copy of the SQL query that caused the row event. This approach provides similar functionality to enabling the binlog_rows_query_log_events parameter on a DB instance on MySQL version 5.6 or later. You can enable binary log annotations globally by creating a custom parameter group and setting the binlog_annotate_row_events parameter to 1. You can also enable annotations at the session level, by calling SET SESSION binlog_annotate_row_events = 1. Use the replicate_annotate_row_events to replicate binary log annotations to the slave instance if binary logging is enabled on it. No special privileges are required to use these settings. The following is an example of a row-based transaction in MariaDB. The use of row-based logging is triggered by setting the transaction isolation level to read-committed. CREATE DATABASE IF NOT EXISTS test; USE test; CREATE TABLE square(x INT PRIMARY KEY, y INT NOT NULL) ENGINE = InnoDB; SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED; BEGIN INSERT INTO square(x, y) VALUES(5, 5 * 5); COMMIT; Without annotations, the binary log entries for the transaction look like the following: API Version 2014-10-31 307 Amazon Relational Database Service User Guide MariaDB Database Log Files BEGIN /*!*/; # at 1163 # at 1209 #150922 7:55:57 server id 1855786460 mapped to number 76 #150922 7:55:57 server id 1855786460 flags: STMT_END_F ### INSERT INTO `test`.`square` ### SET ### @1=5 ### @2=25 # at 1247 #150922 7:56:01 server id 1855786460 COMMIT/*!*/; end_log_pos 1209 Table_map: `test`.`square` end_log_pos 1247 Write_rows: table id 76 end_log_pos 1274 Xid = 62 The following statement enables session-level annotations for this same transaction, and disables them after committing the transaction: CREATE DATABASE IF NOT EXISTS test; USE test; CREATE TABLE square(x INT PRIMARY KEY, y INT NOT NULL) ENGINE = InnoDB; SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED; SET SESSION binlog_annotate_row_events = 1; BEGIN; INSERT INTO square(x, y) VALUES(5, 5 * 5); COMMIT; SET SESSION binlog_annotate_row_events = 0; With annotations, the binary log entries for the transaction look like the following: BEGIN /*!*/; # at 423 # at 483 # at 529 #150922 8:04:24 server id 1855786460 #Q> INSERT INTO square(x, y) VALUES(5, #150922 8:04:24 server id 1855786460 to number 76 #150922 8:04:24 server id 1855786460 STMT_END_F ### INSERT INTO `test`.`square` ### SET ### @1=5 ### @2=25 # at 567 #150922 8:04:26 server id 1855786460 COMMIT/*!*/; end_log_pos 483 5 * 5) end_log_pos 529 Annotate_rows: end_log_pos 567 Write_rows: table id 76 flags: end_log_pos 594 Xid = 88 API Version 2014-10-31 308 Table_map: `test`.`square` mapped Amazon Relational Database Service User Guide Microsoft SQL Server Database Log Files Microsoft SQL Server Database Log Files You can access Microsoft SQL Server error logs, agent logs, trace files, and dump files by using the Amazon RDS console or APIs. For more information about viewing, downloading, and watching filebased database logs, see Amazon RDS Database Log Files (p. 297). Retention Schedule Log files are rotated each day and whenever your DB instance is restarted. The following is the retention schedule for Microsoft SQL Server logs on Amazon RDS. Log Type Retention Schedule Error logs A maximum of 30 error logs are retained. Amazon RDS may delete error logs older than 7 days. Agent logs A maximum of 10 agent logs are retained. Amazon RDS may delete agent logs older than 7 days. Trace files Trace files are retained according to the trace file retention period of your DB instance. The default trace file retention period is 7 days. To modify the trace file retention period for your DB instance, see Setting the Retention Period for Trace and Dump Files (p. 566). Dump files Dump files are retained according to the dump file retention period of your DB instance. The default dump file retention period is 7 days. To modify the dump file retention period for your DB instance, see Setting the Retention Period for Trace and Dump Files (p. 566). Viewing the SQL Server Error Log by Using the rds_read_error_log Procedure You can use the Amazon RDS stored procedure rds_read_error_log to view error logs and agent logs. For more information, see Using the rds_read_error_log Procedure (p. 566). Related Topics • Using SQL Server Agent (p. 564) • Working with Microsoft SQL Server Logs (p. 565) • Working with Trace and Dump Files (p. 566) API Version 2014-10-31 309 Amazon Relational Database Service User Guide MySQL Database Log Files MySQL Database Log Files You can monitor the MySQL error log, slow query log, and the general log. The MySQL error log is generated by default; you can generate the slow query and general logs by setting parameters in your DB parameter group. Amazon RDS rotates all of the MySQL log files; the intervals for each type are given following. You can monitor the MySQL logs directly through the Amazon RDS console, Amazon RDS API, AWS CLI, or AWS SDKs. You can also access MySQL logs by directing the logs to a database table in the main database and querying that table. You can use the mysqlbinlog utility to download a binary log. For more information about viewing, downloading, and watching file-based database logs, see Amazon RDS Database Log Files (p. 297). Accessing MySQL Error Logs The MySQL error log is written to the mysql-error.log file. You can view mysql-error.log by using the Amazon RDS console or by retrieving the log using the Amazon RDS API, Amazon RDS CLI, or AWS SDKs. mysql-error.log is flushed every 5 minutes, and its contents are appended to mysql-errorrunning.log. The mysql-error-running.log file is then rotated every hour and the hourly files generated during the last 24 hours are retained. Note that the retention period is different between Amazon RDS and Aurora. Each log file has the hour it was generated (in UTC) appended to its name. The log files also have a timestamp that helps you determine when the log entries were written. MySQL writes to the error log only on startup, shutdown, and when it encounters errors. A DB instance can go hours or days without new entries being written to the error log. If you see no recent entries, it's because the server did not encounter an error that would result in a log entry. Accessing the MySQL Slow Query and General Logs The MySQL slow query log and the general log can be written to a file or a database table by setting parameters in your DB parameter group. For information about creating and modifying a DB parameter group, see Working with DB Parameter Groups (p. 165). You must set these parameters before you can view the slow query log or general log in the Amazon RDS console or by using the Amazon RDS API, Amazon RDS CLI, or AWS SDKs. You can control MySQL logging by using the parameters in this list: • slow_query_log: To create the slow query log, set to 1. The default is 0. • general_log: To create the general log, set to 1. The default is 0. • long_query_time: To prevent fast-running queries from being logged in the slow query log, specify a value for the shortest query execution time to be logged, in seconds. The default is 10 seconds; the minimum is 0. If log_output = FILE, you can specify a floating point value that goes to microsecond resolution. If log_output = TABLE, you must specify an integer value with second resolution. Only queries whose execution time exceeds the long_query_time value are logged. For example, setting long_query_time to 0.1 prevents any query that runs for less than 100 milliseconds from being logged. • log_queries_not_using_indexes: To log all queries that do not use an index to the slow query log, set to 1. The default is 0. Queries that do not use an index are logged even if their execution time is less than the value of the long_query_time parameter. • log_output option: You can specify one of the following options for the log_output parameter. • TABLE (default)– Write general queries to the mysql.general_log table, and slow queries to the mysql.slow_log table. • FILE– Write both general and slow query logs to the file system. Log files are rotated hourly. API Version 2014-10-31 310 Amazon Relational Database Service User Guide MySQL Database Log Files • NONE– Disable logging. When logging is enabled, Amazon RDS rotates table logs or deletes log files at regular intervals. This measure is a precaution to reduce the possibility of a large log file either blocking database use or affecting performance. FILE and TABLE logging approach rotation and deletion as follows: • When FILE logging is enabled, log files are examined every hour and log files older than 24 hours are deleted. In some cases, the remaining combined log file size after the deletion might exceed the threshold of 2 percent of a DB instance's allocated space. In these cases, the largest log files are deleted until the log file size no longer exceeds the threshold. • When TABLE logging is enabled, in some cases log tables are rotated every 24 hours. This rotation occurs if the space used by the table logs is more than 20 percent of the allocated storage space or the size of all logs combined is greater than 10 GB. If the amount of space used for a DB instance is greater than 90 percent of the DB instance's allocated storage space, then the thresholds for log rotation are reduced. Log tables are then rotated if the space used by the table logs is more than 10 percent of the allocated storage space or the size of all logs combined is greater than 5 GB. You can subscribe to the low_free_storage event to be notified when log tables are rotated to free up space. For more information, see Using Amazon RDS Event Notification (p. 278). When log tables are rotated, the current log table is copied to a backup log table and the entries in the current log table are removed. If the backup log table already exists, then it is deleted before the current log table is copied to the backup. You can query the backup log table if needed. The backup log table for the mysql.general_log table is named mysql.general_log_backup. The backup log table for the mysql.slow_log table is named mysql.slow_log_backup. You can rotate the mysql.general_log table by calling the mysql.rds_rotate_general_log procedure. You can rotate the mysql.slow_log table by calling the mysql.rds_rotate_slow_log procedure. Table logs are rotated during a database version upgrade. To work with the logs from the Amazon RDS console, Amazon RDS API, Amazon RDS CLI, or AWS SDKs, set the log_output parameter to FILE. Like the MySQL error log, these log files are rotated hourly. The log files that were generated during the previous 24 hours are retained. Note that the retention period is different between Amazon RDS and Aurora. For more information about the slow query and general logs, go to the following topics in the MySQL documentation: • The Slow Query Log • The General Query Log Publishing MySQL Logs to CloudWatch Logs You can configure your Amazon RDS MySQL DB instance to publish log data to a log group in Amazon CloudWatch Logs. With CloudWatch Logs, you can perform real-time analysis of the log data, and use CloudWatch to create alarms and view metrics. You can use CloudWatch Logs to store your log records in highly durable storage. Amazon RDS publishes each MySQL database log as a separate database stream in the log group. For example, if you configure the export function to include the slow query log, slow query data is stored in a slow query log stream in the /aws/rds/instance/my_instance/slowquery log group. The error log is enabled by default. The following table summarizes the requirements for the other MySQL logs. API Version 2014-10-31 311 Amazon Relational Database Service User Guide MySQL Database Log Files Log Requirement Audit log The DB instance must use a custom option group with the MARIADB_AUDIT_PLUGIN option. General log The DB instance must use a custom parameter group with the parameter setting general_log = 1 to enable the general log. Slow query log The DB instance must use a custom parameter group with the parameter setting slow_query_log = 1 to enable the slow query log. Log output The DB instance must use a custom parameter group with the parameter setting log_output = FILE to write logs to the file system and publish them to CloudWatch Logs. Note Publishing log files to CloudWatch Logs is only supported for MySQL versions 5.6, 5.7, and 8.0. AWS Management Console To publish MySQL logs to CloudWatch Logs using the console 1. Open the Amazon RDS console at https://console.aws.amazon.com/rds/. 2. In the navigation pane, choose Instances, and then select the DB instance that you want to modify. 3. For Instance actions, choose Modify. 4. In the Log exports section, choose the logs you want to start publishing to CloudWatch Logs. 5. Choose Continue, and then choose Modify DB Instance on the summary page. AWS CLI You can publish MySQL logs with the AWS CLI. You can call the modify-db-instance command with the following parameters: • --db-instance-identifier • --cloudwatch-logs-export-configuration • --apply-immediately You can also publish MySQL logs by calling the following AWS CLI commands: • create-db-instance • restore-db-instance-from-db-snapshot • restore-db-instance-from-s3 • restore-db-instance-to-point-in-time Run one of these AWS CLI commands with the following options: • --db-instance-identifier • --enable-cloudwatch-logs-exports API Version 2014-10-31 312 Amazon Relational Database Service User Guide MySQL Database Log Files • --db-instance-class • --engine Other options might be required depending on the AWS CLI command you run. Example The following example modifies an existing MySQL DB instance to publish log files to CloudWatch Logs. The --cloudwatch-logs-export-configuration value is a JSON object. The key for this object is EnableLogTypes, and its value is an array of strings with any combination of audit, error, general, and slowquery. For Linux, OS X, or Unix: aws rds modify-db-instance \ --db-instance-identifier mydbinstance \ --cloudwatch-logs-export-configuration '{"EnableLogTypes": ["audit","error","general","slowquery"]}' \ --apply-immediately For Windows: aws rds modify-db-instance ^ --db-instance-identifier mydbinstance ^ --cloudwatch-logs-export-configuration '{"EnableLogTypes": ["audit","error","general","slowquery"]}' ^ --apply-immediately Example The following example creates a MySQL DB instance and publishes log files to CloudWatch Logs. The --enable-cloudwatch-logs-exports value is a JSON array of strings. The strings can be any combination of audit, error, general, and slowquery. For Linux, OS X, or Unix: aws rds create-db-instance \ --db-instance-identifier mydbinstance \ --enable-cloudwatch-logs-exports '["audit","error","general","slowquery"]' \ --db-instance-class db.m4.large \ --engine MySQL For Windows: aws rds create-db-instance ^ --db-instance-identifier mydbinstance ^ --enable-cloudwatch-logs-exports '["audit","error","general","slowquery"]' ^ --db-instance-class db.m4.large ^ --engine MySQL RDS API You can publish MySQL logs with the RDS API. You can call the ModifyDBInstance action with the following parameters: API Version 2014-10-31 313 Amazon Relational Database Service User Guide MySQL Database Log Files • DBInstanceIdentifier • CloudwatchLogsExportConfiguration • ApplyImmediately You can also publish MySQL logs by calling the following RDS API actions: • CreateDBInstance • RestoreDBInstanceFromDBSnapshot • RestoreDBInstanceFromS3 • RestoreDBInstanceToPointInTime Run one of these RDS API actions with the following parameters: • DBInstanceIdentifier • EnableCloudwatchLogsExports • Engine • DBInstanceClass Other parameters might be required depending on the AWS CLI command you run. Log File Size The MySQL slow query log, error log, and the general log file sizes are constrained to no more than 2 percent of the allocated storage space for a DB instance. To maintain this threshold, logs are automatically rotated every hour and log files older than 24 hours are removed. If the combined log file size exceeds the threshold after removing old log files, then the largest log files are deleted until the log file size no longer exceeds the threshold. For MySQL, there is a size limit on BLOBs written to the redo log. To account for this limit, ensure that the innodb_log_file_size parameter for your MySQL DB instance is 10 times larger than the largest BLOB data size found in your tables, plus the length of other variable length fields (VARCHAR, VARBINARY, TEXT) in the same tables. For information on how to set parameter values, see Working with DB Parameter Groups (p. 165). For information on the redo log BLOB size limit, go to Changes in MySQL 5.6.20. Managing Table-Based MySQL Logs You can direct the general and slow query logs to tables on the DB instance by creating a DB parameter group and setting the log_output server parameter to TABLE. General queries are then logged to the mysql.general_log table, and slow queries are logged to the mysql.slow_log table. You can query the tables to access the log information. Enabling this logging increases the amount of data written to the database, which can degrade performance. Both the general log and the slow query logs are disabled by default. In order to enable logging to tables, you must also set the general_log and slow_query_log server parameters to 1. Log tables keep growing until the respective logging activities are turned off by resetting the appropriate parameter to 0. A large amount of data often accumulates over time, which can use up a considerable percentage of your allocated storage space. Amazon RDS does not allow you to truncate the log tables, but you can move their contents. Rotating a table saves its contents to a backup table and then creates a new empty log table. You can manually rotate the log tables with the following command line procedures, where the command prompt is indicated by PROMPT>: PROMPT> CALL mysql.rds_rotate_slow_log; API Version 2014-10-31 314 Amazon Relational Database Service User Guide MySQL Database Log Files PROMPT> CALL mysql.rds_rotate_general_log; To completely remove the old data and reclaim the disk space, call the appropriate procedure twice in succession. Binary Logging Format MySQL on Amazon RDS supports the row-based, statement-based, and mixed binary logging formats for MySQL version 5.6 and later. The default binary logging format is mixed. For DB instances running MySQL versions 5.1 and 5.5, only mixed binary logging is supported. For details on the different MySQL binary log formats, see Binary Logging Formats in the MySQL documentation. If you plan to use replication, the binary logging format is important because it determines the record of data changes that is recorded in the source and sent to the replication targets. For information about the advantages and disadvantages of different binary logging formats for replication, see Advantages and Disadvantages of Statement-Based and Row-Based Replication in the MySQL documentation. Important Setting the binary logging format to row-based can result in very large binary log files. Large binary log files reduce the amount of storage available for a DB instance and can increase the amount of time to perform a restore operation of a DB instance. Statement-based replication can cause inconsistencies between the source DB instance and a Read Replica. For more information, see Determination of Safe and Unsafe Statements in Binary Logging in the MySQL documentation. To set the MySQL binary logging format 1. 2. 3. Open the Amazon RDS console at https://console.aws.amazon.com/rds/. In the navigation pane, choose Parameter groups. Choose the parameter group used by the DB instance you want to modify. You can't modify a default parameter group. If the DB instance is using a default parameter group, create a new parameter group and associate it with the DB instance. For more information on DB parameter groups, see Working with DB Parameter Groups (p. 165). 4. 5. 6. From Parameter group actions, choose Edit. Set the binlog_format parameter to the binary logging format of your choice (ROW, STATEMENT, or MIXED). Choose Save changes to save the updates to the DB parameter group. Important Changing the default.mysql5.6, default.mysql5.7, or default.mysql8.0 DB parameter group affects all MySQL version DB instances that use that parameter group. If you want to specify different binary logging formats for different MySQL 5.6, 5.7, or 8.0 DB instances in an AWS Region, you need to create your own DB parameter group. This parameter group identifies the different logging format and assigns that DB parameter group to the intended DB instances. Accessing MySQL Binary Logs You can use the mysqlbinlog utility to download or stream binary logs from Amazon RDS instances running MySQL 5.6 or later. The binary log is downloaded to your local computer, where you can perform actions such as replaying the log using the mysql utility. For more information about using the mysqlbinlog utility, go to Using mysqlbinlog to Back Up Binary Log Files. To run the mysqlbinlog utility against an Amazon RDS instance, use the following options: API Version 2014-10-31 315 Amazon Relational Database Service User Guide MySQL Database Log Files • Specify the --read-from-remote-server option. • --host: Specify the DNS name from the endpoint of the instance. • --port: Specify the port used by the instance. • --user: Specify a MySQL user that has been granted the replication slave permission. • --password: Specify the password for the user, or omit a password value so that the utility prompts you for a password. • To have the file downloaded in binary format, specify the --raw option. • --result-file: Specify the local file to receive the raw output. • Specify the names of one or more binary log files. To get a list of the available logs, use the SQL command SHOW BINARY LOGS. • To stream the binary log files, specify the --stop-never option. For more information about mysqlbinlog options, go to mysqlbinlog - Utility for Processing Binary Log Files. For example, see the following. For Linux, OS X, or Unix: mysqlbinlog \ --read-from-remote-server \ --host=MySQL56Instance1.cg034hpkmmjt.region.rds.amazonaws.com \ --port=3306 \ --user ReplUser \ --password \ --raw \ --result-file=/tmp/ \ binlog.00098 For Windows: mysqlbinlog ^ --read-from-remote-server ^ --host=MySQL56Instance1.cg034hpkmmjt.region.rds.amazonaws.com ^ --port=3306 ^ --user ReplUser ^ --password ^ --raw ^ --result-file=/tmp/ ^ binlog.00098 Amazon RDS normally purges a binary log as soon as possible, but the binary log must still be available on the instance to be accessed by mysqlbinlog. To specify the number of hours for RDS to retain binary logs, use the mysql.rds_set_configuration stored procedure and specify a period with enough time for you to download the logs. After you set the retention period, monitor storage usage for the DB instance to ensure that the retained binary logs don't take up too much storage. Note The mysql.rds_set_configuration stored procedure is only available for MySQL version 5.6 or later. The following example sets the retention period to 1 day. call mysql.rds_set_configuration('binlog retention hours', 24); To display the current setting, use the mysql.rds_show_configuration stored procedure. API Version 2014-10-31 316 Amazon Relational Database Service User Guide MySQL Database Log Files call mysql.rds_show_configuration; API Version 2014-10-31 317 Amazon Relational Database Service User Guide Oracle Database Log Files Oracle Database Log Files You can access Oracle alert logs, audit files, and trace files by using the Amazon RDS console or API. For more information about viewing, downloading, and watching file-based database logs, see Amazon RDS Database Log Files (p. 297). The Oracle audit files provided are the standard Oracle auditing files. Amazon RDS supports the Oracle fine-grained auditing (FGA) feature. However, log access doesn't provide access to FGA events that are stored in the SYS.FGA_LOG$ table and that are accessible through the DBA_FGA_AUDIT_TRAIL view. The DescribeDBLogFiles API action that lists the Oracle log files that are available for a DB instance ignores the MaxRecords parameter and returns up to 1000 records. Retention Schedule The Oracle database engine might rotate logs files if they get very large. To retain audit or trace files, download them. Storing the files locally reduces your Amazon RDS storage costs and makes more space available for your data. The following is the retention schedule for Oracle alert logs, audit files, and trace files on Amazon RDS. Log Type Retention Schedule Alert logs The text alert log is rotated daily with 30-day retention managed by Amazon RDS. The XML alert log is retained for at least seven days. You can access this log by using the ALERTLOG view. Audit files The default retention period for audit files is seven days. Amazon RDS might delete audit files older than seven days. Trace files The default retention period for trace files is seven days. Amazon RDS might delete trace files older than seven days. Listener logs The default retention period for the listener logs is seven days. Amazon RDS might delete listener logs older than seven days. Note Audit files and trace files share the same retention configuration. Switching Online Log files You can use the Amazon RDS procedure rdsadmin.rdsadmin_util.switch_logfile to switch online log files. For more information, see Switching Online Log Files (p. 863). Retrieving Archived Redo Logs You can retain archived redo logs. For more information, see Retaining Archived Redo Logs (p. 866). Working with Oracle Trace Files Following, you can find descriptions of Amazon RDS procedures to create, refresh, access, and delete trace files. Listing Files You can use either of two procedures to allow access to any file in the background_dump_dest path. The first procedure refreshes a view containing a listing of all files currently in background_dump_dest. API Version 2014-10-31 318 Amazon Relational Database Service User Guide Oracle Database Log Files exec rdsadmin.manage_tracefiles.refresh_tracefile_listing; After the view is refreshed, use the following view to access the results. rdsadmin.tracefile_listing An alternative to the previous process is to use FROM table to stream nontable data in a table-like format to list DB directory contents. SELECT * FROM table(rdsadmin.rds_file_util.listdir('BDUMP')); The following query shows the text of a log file. SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','alert_xxx.log')); Generating Trace Files and Tracing a Session Because there are no restrictions on alter session, many standard methods to generate trace files in Oracle remain available to an Amazon RDS DB instance. The following procedures are provided for trace files that require greater access. Oracle Method Amazon RDS Method oradebug hanganalyze 3 exec rdsadmin.manage_tracefiles.hanganalyze; oradebug dump systemstate 266 exec rdsadmin.manage_tracefiles.dump_systemstate; You can use many standard methods to trace individual sessions connected to an Oracle DB instance in Amazon RDS. To enable tracing for a session, you can run subprograms in PL/SQL packages supplied by Oracle, such as the DBMS_SESSION and DBMS_MONITOR packages. For more information, see Enabling Tracing for a Session in the Oracle documentation. Retrieving Trace Files You can retrieve any trace file in background_dump_dest using a standard SQL query on an Amazon RDS–managed external table. To use this method, you must execute the procedure to set the location for this table to the specific trace file. For example, you can use the rdsadmin.tracefile_listing view mentioned preceding to list all of the trace files on the system. You can then set the tracefile_table view to point to the intended trace file using the following procedure. exec rdsadmin.manage_tracefiles.set_tracefile_table_location('CUST01_ora_3260_SYSTEMSTATE.trc'); The following example creates an external table in the current schema with the location set to the file provided. You can retrieve the contents into a local file using a SQL query. # eg: send the contents of the tracefile to a local file: API Version 2014-10-31 319 Amazon Relational Database Service User Guide Oracle Database Log Files sqlplus user/password@TNS alias << EOF > /tmp/tracefile.txt select * from tracefile_table; EOF Purging Trace Files Trace files can accumulate and consume disk space. Amazon RDS purges trace files by default and log files that are older than seven days. You can view and set the trace file retention period using the show_configuration procedure. You should run the command SET SERVEROUTPUT ON so that you can view the configuration results. The following example shows the current trace file retention period, and then sets a new trace file retention period. # Show the current tracefile retention SQL> exec rdsadmin.rdsadmin_util.show_configuration; NAME:tracefile retention VALUE:10080 DESCRIPTION:tracefile expiration specifies the duration in minutes before tracefiles in bdump are automatically deleted. # Set the tracefile retention to 24 hours: SQL> exec rdsadmin.rdsadmin_util.set_configuration('tracefile retention',1440); #show the new tracefile retention SQL> exec rdsadmin.rdsadmin_util.show_configuration; NAME:tracefile retention VALUE:1440 DESCRIPTION:tracefile expiration specifies the duration in minutes before tracefiles in bdump are automatically deleted. In addition to the periodic purge process, you can manually remove files from the background_dump_dest. The following example shows how to purge all files older than five minutes. exec rdsadmin.manage_tracefiles.purge_tracefiles(5); You can also purge all files that match a specific pattern (don't include the file extension, such as .trc). The following example shows how to purge all files that start with SCHPOC1_ora_5935. exec rdsadmin.manage_tracefiles.purge_tracefiles('SCHPOC1_ora_5935'); Publishing Oracle Logs to Amazon CloudWatch Logs You can configure your Amazon RDS Oracle DB instance to publish log data to a log group in Amazon CloudWatch Logs. With CloudWatch Logs, you can analyze the log data, and use CloudWatch to create alarms and view metrics. You can use CloudWatch Logs to store your log records in highly durable storage. Amazon RDS publishes each Oracle database log as a separate database stream in the log group. For example, if you configure the export function to include the audit log, audit data is stored in an audit log stream in the /aws/rds/instance/my_instance/audit log group. AWS Management Console To publish Oracle DB logs to CloudWatch Logs from the console 1. Open the Amazon RDS console at https://console.aws.amazon.com/rds/. API Version 2014-10-31 320 Amazon Relational Database Service User Guide Oracle Database Log Files 2. 3. 4. In the navigation pane, choose Instances, and then choose the DB instance that you want to modify. For Instance actions, choose Modify. In the Log exports section, choose the logs that you want to start publishing to CloudWatch Logs. 5. Choose Continue, and then choose Modify DB Instance on the summary page. AWS CLI To publish Oracle logs, you can use the modify-db-instance command with the following parameters: • --db-instance-identifier • --cloudwatch-logs-export-configuration • --apply-immediately You can also publish Oracle logs using the following commands: • create-db-instance • restore-db-instance-from-db-snapshot • restore-db-instance-from-s3 • restore-db-instance-to-point-in-time Example The following example creates an Oracle DB instance with CloudWatch Logs publishing enabled. The --enable-cloudwatch-logs-exports value is a JSON array of strings. The strings can be any combination of alert, audit, listener, and trace. For Linux, OS X, or Unix: aws rds create-db-instance \ --db-instance-identifier mydbinstance \ --enable-cloudwatch-logs-exports '["trace","audit","alert","listener"]' \ --db-instance-class db.m1.small \ --engine oracle-se1 For Windows: aws rds create-db-instance ^ --db-instance-identifier mydbinstance ^ --enable-cloudwatch-logs-exports '["trace","audit","alert","listener"]' ^ --db-instance-class db.m1.small ^ --engine oracle-se1 Example The following example modifies an existing Oracle DB instance to publish log files to CloudWatch Logs. The --cloudwatch-logs-export-configuration value is a JSON object. The key for this object is EnableLogTypes, and its value is an array of strings with any combination of alert, audit, listener, and trace. For Linux, OS X, or Unix: aws rds modify-db-instance \ API Version 2014-10-31 321 Amazon Relational Database Service User Guide Oracle Database Log Files --db-instance-identifier mydbinstance \ --cloudwatch-logs-export-configuration '{"EnableLogTypes": ["trace","alert","audit","listener"]}' \ --apply-immediately For Windows: aws rds modify-db-instance ^ --db-instance-identifier mydbinstance ^ --cloudwatch-logs-export-configuration '{"EnableLogTypes": ["trace","alert","audit","listener"]}' ^ --apply-immediately Example The following example modifies an existing Oracle DB instance to disable publishing audit and listener log files to CloudWatch Logs. The --cloudwatch-logs-export-configuration value is a JSON object. The key for this object is DisableLogTypes, and its value is an array of strings with any combination of alert, audit, listener, and trace For Linux, OS X, or Unix: aws rds modify-db-instance \ --db-instance-identifier mydbinstance \ --cloudwatch-logs-export-configuration '{"DisableLogTypes":["audit","listener"]}' \ --apply-immediately For Windows: aws rds modify-db-instance ^ --db-instance-identifier mydbinstance ^ --cloudwatch-logs-export-configuration '{"DisableLogTypes":["audit","listener"]}' ^ --apply-immediately RDS API You can publish Oracle DB logs with the RDS API. You can call the ModifyDBInstance action with the following parameters: • DBInstanceIdentifier • CloudwatchLogsExportConfiguration • ApplyImmediately You can also publish Oracle logs by calling the following RDS API actions: • CreateDBInstance • RestoreDBInstanceFromDBSnapshot • RestoreDBInstanceFromS3 • RestoreDBInstanceToPointInTime Run one of these RDS API actions with the following parameters: API Version 2014-10-31 322 Amazon Relational Database Service User Guide Oracle Database Log Files • DBInstanceIdentifier • EnableCloudwatchLogsExports • Engine • DBInstanceClass Other parameters might be required depending on the AWS CLI command you run. Previous Methods for Accessing Alert Logs and Listener Logs You can view the alert log using the Amazon RDS console. You can also use the following SQL statement to access the alert log. select message_text from alertlog; To access the listener log, use the following SQL statement. select message_text from listenerlog; Note Oracle rotates the alert and listener logs when they exceed 10 MB, at which point they are unavailable from Amazon RDS views. API Version 2014-10-31 323 Amazon Relational Database Service User Guide PostgreSQL Database Log Files PostgreSQL Database Log Files RDS PostgreSQL generates query and error logs. We write auto-vacuum info and rds_admin actions to the error log. Postgres also logs connections/disconnections/checkpoints to the error log. For more information, see http://www.postgresql.org/docs/9.4/static/runtime-config-logging.html You can set the retention period for system logs using the rds.log_retention_period parameter in the DB parameter group associated with your DB instance. The unit for this parameter is minutes; for example, a setting of 1440 would retain logs for one day. The default value is 4320 (three days). The maximum value is 10080 (seven days). Note that your instance must have enough allocated storage to contain the retained log files. You can enable query logging for your PostgreSQL DB instance by setting two parameters in the DB parameter group associated with your DB instance: log_statement and log_min_duration_statement. The log_statement parameter controls which SQL statements are logged. We recommend setting this parameter to all to log all statements when debugging issues in your DB instance. The default value is none. Alternatively, you can set this value to ddl to log all data definition language (DDL) statements (CREATE, ALTER, DROP, etc.) or to mod to log all DDL and data modification language (DML) statements (INSERT, UPDATE, DELETE, etc.). The log_min_duration_statement parameter sets the limit in milliseconds of a statement to be logged. All SQL statements that run longer than the parameter setting are logged. This parameter is disabled and set to minus 1 (-1) by default. Enabling this parameter can help you find unoptimized queries. For more information on these settings, see Error Reporting and Logging in the PostgreSQL documentation. If you are new to setting parameters in a DB parameter group and associating that parameter group with a DB instance, see Working with DB Parameter Groups (p. 165) The following steps show how to set up query logging: 1. Set the log_statement parameter to all. The following example shows the information that is written to the postgres.log file: 2013-11-05 16:48:56 UTC::@:[2952]:LOG: 2013-11-05 16:48:56 UTC::@:[2952]:LOG: "1" received SIGHUP, reloading configuration files parameter "log_min_duration_statement" changed to Additional information is written to the postgres.log file when you execute a query. The following example shows the type of information written to the file after a query: 2013-11-05 16:41:07 UTC::@:[2955]:LOG: checkpoint starting: time 2013-11-05 16:41:07 UTC::@:[2955]:LOG: checkpoint complete: wrote 1 buffers (0.3%); 0 transaction log file(s) added, 0 removed, 1 recycled; write=0.000 s, sync=0.003 s, total=0.012 s; sync files=1, longest=0.003 s, average=0.003 s 2013-11-05 16:45:14 UTC:[local]:master@postgres:[8839]:LOG: statement: SELECT d.datname as "Name", pg_catalog.pg_get_userbyid(d.datdba) as "Owner", pg_catalog.pg_encoding_to_char(d.encoding) as "Encoding", d.datcollate as "Collate", d.datctype as "Ctype", pg_catalog.array_to_string(d.datacl, E'\n') AS "Access privileges" FROM pg_catalog.pg_database d ORDER BY 1; 2013-11-05 16:45: 2. Set the log_min_duration_statement parameter. The following example shows the information that is written to the postgres.log file when the parameter is set to 1: API Version 2014-10-31 324 Amazon Relational Database Service User Guide PostgreSQL Database Log Files 2013-11-05 16:48:56 UTC::@:[2952]:LOG: 2013-11-05 16:48:56 UTC::@:[2952]:LOG: "1" received SIGHUP, reloading configuration files parameter "log_min_duration_statement" changed to Additional information is written to the postgres.log file when you execute a query that exceeds the duration parameter setting. The following example shows the type of information written to the file after a query: 2013-11-05 16:51:10 UTC:[local]:master@postgres:[9193]:LOG: statement: SELECT c2.relname, i.indisprimary, i.indisunique, i.indisclustered, i.indisvalid, pg_catalog.pg_get_indexdef(i.indexrelid, 0, true), pg_catalog.pg_get_constraintdef(con.oid, true), contype, condeferrable, condeferred, c2.reltablespace FROM pg_catalog.pg_class c, pg_catalog.pg_class c2, pg_catalog.pg_index i LEFT JOIN pg_catalog.pg_constraint con ON (conrelid = i.indrelid AND conindid = i.indexrelid AND contype IN ('p','u','x')) WHERE c.oid = '1255' AND c.oid = i.indrelid AND i.indexrelid = c2.oid ORDER BY i.indisprimary DESC, i.indisunique DESC, c2.relname; 2013-11-05 16:51:10 UTC:[local]:master@postgres:[9193]:LOG: duration: 3.367 ms 2013-11-05 16:51:10 UTC:[local]:master@postgres:[9193]:LOG: statement: SELECT c.oid::pg_catalog.regclass FROM pg_catalog.pg_class c, pg_catalog.pg_inherits i WHERE c.oid=i.inhparent AND i.inhrelid = '1255' ORDER BY inhseqno; 2013-11-05 16:51:10 UTC:[local]:master@postgres:[9193]:LOG: duration: 1.002 ms 2013-11-05 16:51:10 UTC:[local]:master@postgres:[9193]:LOG: statement: SELECT c.oid::pg_catalog.regclass FROM pg_catalog.pg_class c, pg_catalog.pg_inherits i WHERE c.oid=i.inhrelid AND i.inhparent = '1255' ORDER BY c.oid::pg_catalog.regclass::pg_catalog.text; 2013-11-05 16:51:18 UTC:[local]:master@postgres:[9193]:LOG: statement: select proname from pg_proc; 2013-11-05 16:51:18 UTC:[local]:master@postgres:[9193]:LOG: duration: 3.469 ms API Version 2014-10-31 325 Amazon Relational Database Service User Guide Logging Amazon RDS API Calls with AWS CloudTrail Logging Amazon RDS API Calls with AWS CloudTrail Amazon RDS is integrated with AWS CloudTrail, a service that provides a record of actions taken by a user, role, or an AWS service in Amazon RDS. CloudTrail captures all API calls for Amazon RDS as events, including calls from the Amazon RDS console and from code calls to the Amazon RDS APIs. If you create a trail, you can enable continuous delivery of CloudTrail events to an Amazon S3 bucket, including events for Amazon RDS. If you don't configure a trail, you can still view the most recent events in the CloudTrail console in Event history. Using the information collected by CloudTrail, you can determine the request that was made to Amazon RDS, the IP address from which the request was made, who made the request, when it was made, and additional details. To learn more about CloudTrail, see the AWS CloudTrail User Guide. Amazon RDS Information in CloudTrail CloudTrail is enabled on your AWS account when you create the account. When activity occurs in Amazon RDS, that activity is recorded in a CloudTrail event along with other AWS service events in Event history. You can view, search, and download recent events in your AWS account. For more information, see Viewing Events with CloudTrail Event History. For an ongoing record of events in your AWS account, including events for Amazon RDS, create a trail. A trail enables CloudTrail to deliver log files to an Amazon S3 bucket. By default, when you create a trail in the console, the trail applies to all regions. The trail logs events from all regions in the AWS partition and delivers the log files to the Amazon S3 bucket that you specify. Additionally, you can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs. For more information, see: • Overview for Creating a Trail • CloudTrail Supported Services and Integrations • Configuring Amazon SNS Notifications for CloudTrail • Receiving CloudTrail Log Files from Multiple Regions and Receiving CloudTrail Log Files from Multiple Accounts All Amazon RDS actions are logged by CloudTrail and are documented in the Amazon RDS API Reference. For example, calls to the CreateDBInstance, ModifyDBInstance, and CreateDBParameterGroup actions generate entries in the CloudTrail log files. Every event or log entry contains information about who generated the request. The identity information helps you determine the following: • Whether the request was made with root or IAM user credentials. • Whether the request was made with temporary security credentials for a role or federated user. • Whether the request was made by another AWS service. For more information, see the CloudTrail userIdentity Element. Understanding Amazon RDS Log File Entries A trail is a configuration that enables delivery of events as log files to an Amazon S3 bucket that you specify. CloudTrail log files contain one or more log entries. An event represents a single request from any source and includes information about the requested action, the date and time of the action, request API Version 2014-10-31 326 Amazon Relational Database Service User Guide Understanding Amazon RDS Log File Entries parameters, and so on. CloudTrail log files are not an ordered stack trace of the public API calls, so they do not appear in any specific order. The following example shows a CloudTrail log entry that demonstrates the CreateDBInstance action. { "eventVersion": "1.04", "userIdentity": { "type": "IAMUser", "principalId": "AKIAIOSFODNN7EXAMPLE", "arn": "arn:aws:iam::123456789012:user/johndoe", "accountId": "123456789012", "accessKeyId": "AKIAI44QH8DHBEXAMPLE", "userName": "johndoe" }, "eventTime": "2018-07-30T22:14:06Z", "eventSource": "rds.amazonaws.com", "eventName": "CreateDBInstance", "awsRegion": "us-east-1", "sourceIPAddress": "72.21.198.65", "userAgent": "aws-cli/1.15.42 Python/3.6.1 Darwin/17.7.0 botocore/1.10.42", "requestParameters": { "enableCloudwatchLogsExports": [ "audit", "error", "general", "slowquery" ], "dBInstanceIdentifier": "test-instance", "engine": "mysql", "masterUsername": "myawsuser", "allocatedStorage": 20, "dBInstanceClass": "db.m1.small", "masterUserPassword": "****" }, "responseElements": { "dBInstanceArn": "arn:aws:rds:us-east-1:123456789012:db:test-instance", "storageEncrypted": false, "preferredBackupWindow": "10:27-10:57", "preferredMaintenanceWindow": "sat:05:47-sat:06:17", "backupRetentionPeriod": 1, "allocatedStorage": 20, "storageType": "standard", "engineVersion": "5.6.39", "dbInstancePort": 0, "optionGroupMemberships": [ { "status": "in-sync", "optionGroupName": "default:mysql-5-6" } ], "dBParameterGroups": [ { "dBParameterGroupName": "default.mysql5.6", "parameterApplyStatus": "in-sync" } ], "monitoringInterval": 0, "dBInstanceClass": "db.m1.small", "readReplicaDBInstanceIdentifiers": [], "dBSubnetGroup": { "dBSubnetGroupName": "default", "dBSubnetGroupDescription": "default", "subnets": [ API Version 2014-10-31 327 Amazon Relational Database Service User Guide Understanding Amazon RDS Log File Entries { }, { }, { }, { }, { }, { "subnetAvailabilityZone": {"name": "us-east-1b"}, "subnetIdentifier": "subnet-cbfff283", "subnetStatus": "Active" "subnetAvailabilityZone": {"name": "us-east-1e"}, "subnetIdentifier": "subnet-d7c825e8", "subnetStatus": "Active" "subnetAvailabilityZone": {"name": "us-east-1f"}, "subnetIdentifier": "subnet-6746046b", "subnetStatus": "Active" "subnetAvailabilityZone": {"name": "us-east-1c"}, "subnetIdentifier": "subnet-bac383e0", "subnetStatus": "Active" "subnetAvailabilityZone": {"name": "us-east-1d"}, "subnetIdentifier": "subnet-42599426", "subnetStatus": "Active" "subnetAvailabilityZone": {"name": "us-east-1a"}, "subnetIdentifier": "subnet-da327bf6", "subnetStatus": "Active" } ], "vpcId": "vpc-136a4c6a", "subnetGroupStatus": "Complete" }, "masterUsername": "myawsuser", "multiAZ": false, "autoMinorVersionUpgrade": true, "engine": "mysql", "cACertificateIdentifier": "rds-ca-2015", "dbiResourceId": "db-ETDZIIXHEWY5N7GXVC4SH7H5IA", "dBSecurityGroups": [], "pendingModifiedValues": { "masterUserPassword": "****", "pendingCloudwatchLogsExports": { "logTypesToEnable": [ "audit", "error", "general", "slowquery" ] } }, "dBInstanceStatus": "creating", "publiclyAccessible": true, "domainMemberships": [], "copyTagsToSnapshot": false, "dBInstanceIdentifier": "test-instance", "licenseModel": "general-public-license", "iAMDatabaseAuthenticationEnabled": false, "performanceInsightsEnabled": false, "vpcSecurityGroups": [ { "status": "active", "vpcSecurityGroupId": "sg-f839b688" } ] API Version 2014-10-31 328 Amazon Relational Database Service User Guide Understanding Amazon RDS Log File Entries } }, "requestID": "daf2e3f5-96a3-4df7-a026-863f96db793e", "eventID": "797163d3-5726-441d-80a7-6eeb7464acd4", "eventType": "AwsApiCall", "recipientAccountId": "123456789012" API Version 2014-10-31 329 Amazon Relational Database Service User Guide Authentication and Access Control Configuring Security in Amazon RDS You can manage access to your Amazon RDS resources and your databases on a DB instance. The method you use to manage access depends on what type of task the user needs to perform with Amazon RDS: • Run your DB instance in an Amazon Virtual Private Cloud (VPC) for the greatest possible network access control. For more information about creating a DB instance in a VPC, see Using Amazon RDS with Amazon Virtual Private Cloud (VPC). • Use AWS Identity and Access Management (IAM) policies to assign permissions that determine who is allowed to manage RDS resources. For example, you can use IAM to determine who is allowed to create, describe, modify, and delete DB instances, tag resources, or modify security groups. • Use security groups to control what IP addresses or Amazon EC2 instances can connect to your databases on a DB instance. When you first create a DB instance, its firewall prevents any database access except through rules specified by an associated security group. • Use Secure Socket Layer (SSL) connections with DB instances running the MySQL, MariaDB, PostgreSQL, Oracle, or Microsoft SQL Server database engines. For more information on using SSL with a DB instance, see Using SSL to Encrypt a Connection to a DB Instance (p. 380). • Use RDS encryption to secure your RDS instances and snapshots at rest. RDS encryption uses the industry standard AES-256 encryption algorithm to encrypt your data on the server that hosts your RDS instance. For more information, see Encrypting Amazon RDS Resources (p. 377). • Use network encryption and transparent data encryption with Oracle DB instances; for more information, see Oracle Native Network Encryption (p. 810) and Oracle Transparent Data Encryption (p. 831) • Use the security features of your DB engine to control who can log in to the databases on a DB instance, just as you do if the database was on your local network. Note You only have to configure security for your use cases. You don't have to configure security access for processes that Amazon RDS manages, such as creating backups, replicating data between a master and a Read Replica, or other processes. For more information on managing access to Amazon RDS resources and your databases on a DB instance, see the following topics. Topics • Authentication and Access Control (p. 330) • Encrypting Amazon RDS Resources (p. 377) • Using SSL to Encrypt a Connection to a DB Instance (p. 380) • Controlling Access with Amazon RDS Security Groups (p. 382) • Working with DB Security Groups (EC2-Classic Platform) (p. 387) • Master User Account Privileges (p. 395) • Using Service-Linked Roles for Amazon RDS (p. 397) • Amazon Virtual Private Cloud (VPCs) and Amazon RDS (p. 400) Authentication and Access Control Access to Amazon RDS requires credentials that AWS can use to authenticate your requests. Those credentials must have permissions to access AWS resources, such as an Amazon RDS DB instance. The following sections provide details on how you can use AWS Identity and Access Management (IAM) and Amazon RDS to help secure your resources by controlling who can access them: API Version 2014-10-31 330 Amazon Relational Database Service User Guide Authentication • Authentication (p. 331) • Access Control (p. 331) Authentication You can access AWS as any of the following types of identities: • AWS account root user – When you first create an AWS account, you begin with a single sign-in identity that has complete access to all AWS services and resources in the account. This identity is called the AWS account root user and is accessed by signing in with the email address and password that you used to create the account. We strongly recommend that you do not use the root user for your everyday tasks, even the administrative ones. Instead, adhere to the best practice of using the root user only to create your first IAM user. Then securely lock away the root user credentials and use them to perform only a few account and service management tasks. • IAM user – An IAM user is an identity within your AWS account that has specific custom permissions (for example, permissions to create a DB instance in Amazon RDS). You can use an IAM user name and password to sign in to secure AWS webpages like the AWS Management Console, AWS Discussion Forums, or the AWS Support Center. In addition to a user name and password, you can also generate access keys for each user. You can use these keys when you access AWS services programmatically, either through one of the several SDKs or by using the AWS Command Line Interface (CLI). The SDK and CLI tools use the access keys to cryptographically sign your request. If you don’t use AWS tools, you must sign the request yourself. Amazon RDS supports Signature Version 4, a protocol for authenticating inbound API requests. For more information about authenticating requests, see Signature Version 4 Signing Process in the AWS General Reference. • IAM role – An IAM role is an IAM identity that you can create in your account that has specific permissions. It is similar to an IAM user, but it is not associated with a specific person. An IAM role enables you to obtain temporary access keys that can be used to access AWS services and resources. IAM roles with temporary credentials are useful in the following situations: • Federated user access – Instead of creating an IAM user, you can use existing user identities from AWS Directory Service, your enterprise user directory, or a web identity provider. These are known as federated users. AWS assigns a role to a federated user when access is requested through an identity provider. For more information about federated users, see Federated Users and Roles in the IAM User Guide. • AWS service access – You can use an IAM role in your account to grant an AWS service permissions to access your account’s resources. For example, you can create a role that allows Amazon Redshift to access an Amazon S3 bucket on your behalf and then load data from that bucket into an Amazon Redshift cluster. For more information, see Creating a Role to Delegate Permissions to an AWS Service in the IAM User Guide. • Applications running on Amazon EC2 – You can use an IAM role to manage temporary credentials for applications that are running on an EC2 instance and making AWS API requests. This is preferable to storing access keys within the EC2 instance. To assign an AWS role to an EC2 instance and make it available to all of its applications, you create an instance profile that is attached to the instance. An instance profile contains the role and enables programs that are running on the EC2 instance to get temporary credentials. For more information, see Using an IAM Role to Grant Permissions to Applications Running on Amazon EC2 Instances in the IAM User Guide. Access Control You can have valid credentials to authenticate your requests, but unless you have permissions you cannot create or access Amazon RDS resources. For example, you must have permissions to create an Amazon RDS DB instance, create a DB snapshot, add an event subscription, and so on. API Version 2014-10-31 331 Amazon Relational Database Service User Guide Overview of Managing Access The following sections describe how to manage permissions for Amazon RDS. We recommend that you read the overview first. • Overview of Managing Access Permissions to Your Amazon RDS Resources (p. 332) • Using Identity-Based Policies (IAM Policies) for Amazon RDS (p. 335) Overview of Managing Access Permissions to Your Amazon RDS Resources Every AWS resource is owned by an AWS account, and permissions to create or access the resources are governed by permissions policies. An account administrator can attach permissions policies to IAM identities (that is, users, groups, and roles), and some services (such as AWS Lambda) also support attaching permissions policies to resources. Note An account administrator (or administrator user) is a user with administrator privileges. For more information, see IAM Best Practices in the IAM User Guide. When granting permissions, you decide who is getting the permissions, the resources they get permissions for, and the specific actions that you want to allow on those resources. Topics • Amazon RDS Resources and Operations (p. 332) • Understanding Resource Ownership (p. 333) • Managing Access to Resources (p. 333) • Specifying Policy Elements: Actions, Effects, Resources, and Principals (p. 335) • Specifying Conditions in a Policy (p. 335) Amazon RDS Resources and Operations In Amazon RDS, the primary resource is a DB instance. Amazon RDS supports other resources that can be used with the primary resource such as DB snapshots, parameter groups, and event subscriptions. These are referred to as subresources. These resources and subresources have unique Amazon Resource Names (ARNs) associated with them as shown in the following table. Resource Type ARN Format DB cluster arn:aws:rds:region:account-id:cluster:db-cluster-name DB cluster parameter group arn:aws:rds:region:account-id:cluster-pg:clusterparameter-group-name DB cluster snapshot arn:aws:rds:region:account-id:cluster-snapshot:clustersnapshot-name DB instance arn:aws:rds:region:account-id:db:db-instance-name DB option group arn:aws:rds:region:account-id:og:option-group-name DB parameter group arn:aws:rds:region:account-id:pg:parameter-group-name DB snapshot arn:aws:rds:region:account-id:snapshot:snapshot-name API Version 2014-10-31 332 Amazon Relational Database Service User Guide Overview of Managing Access Resource Type ARN Format DB security group arn:aws:rds:region:account-id:secgrp:security-group-name DB subnet group arn:aws:rds:region:account-id:subgrp:subnet-group-name Event subscription arn:aws:rds:region:account-id:es:subscription-name Read Replica arn:aws:rds:region:account-id:db:db-instance-name Reserved DB instance arn:aws:rds:region:account-id:ri:reserved-db-instance-name Amazon RDS provides a set of operations to work with the Amazon RDS resources. For a list of available operations, see Actions. Understanding Resource Ownership A resource owner is the AWS account that created a resource. That is, the resource owner is the AWS account of the principal entity (the root account, an IAM user, or an IAM role) that authenticates the request that creates the resource. The following examples illustrate how this works: • If you use the root account credentials of your AWS account to create an RDS resource, such as a DB instance, your AWS account is the owner of the RDS resource. • If you create an IAM user in your AWS account and grant permissions to create RDS resources to that user, the user can create RDS resources. However, your AWS account, to which the user belongs, owns the RDS resources. • If you create an IAM role in your AWS account with permissions to create RDS resources, anyone who can assume the role can create RDS resources. Your AWS account, to which the role belongs, owns the RDS resources. Managing Access to Resources A permissions policy describes who has access to what. The following section explains the available options for creating permissions policies. Note This section discusses using IAM in the context of Amazon RDS. It doesn't provide detailed information about the IAM service. For complete IAM documentation, see What Is IAM? in the IAM User Guide. For information about IAM policy syntax and descriptions, see AWS IAM Policy Reference in the IAM User Guide. Policies attached to an IAM identity are referred to as identity-based policies (IAM policies) and policies attached to a resource are referred to as resource-based policies. Amazon RDS supports only identitybased policies (IAM policies). Topics • Identity-Based Policies (IAM Policies) (p. 333) • Resource-Based Policies (p. 334) Identity-Based Policies (IAM Policies) You can attach policies to IAM identities. For example, you can do the following: • Attach a permissions policy to a user or a group in your account – An account administrator can use a permissions policy that is associated with a particular user to grant permissions for that user to create an Amazon RDS resource, such as a DB instance. API Version 2014-10-31 333 Amazon Relational Database Service User Guide Overview of Managing Access • Attach a permissions policy to a role (grant cross-account permissions) – You can attach an identity-based permissions policy to an IAM role to grant cross-account permissions. For example, the administrator in Account A can create a role to grant cross-account permissions to another AWS account (for example, Account B) or an AWS service as follows: 1. Account A administrator creates an IAM role and attaches a permissions policy to the role that grants permissions on resources in Account A. 2. Account A administrator attaches a trust policy to the role identifying Account B as the principal who can assume the role. 3. Account B administrator can then delegate permissions to assume the role to any users in Account B. Doing this allows users in Account B to create or access resources in Account A. The principal in the trust policy can also be an AWS service principal if you want to grant an AWS service permissions to assume the role. For more information about using IAM to delegate permissions, see Access Management in the IAM User Guide. The following is an example policy that allows the user with the ID 123456789012 to create DB instances for your AWS account. The policy requires that the name of the new DB instance begin with test. The new DB instance must also use the MySQL database engine and the db.t2.micro DB instance class. In addition, the new DB instance must use an option group and a DB parameter group that starts with default, and it must use the default subnet group. { } "Version": "2012-10-17", "Statement": [ { "Sid": "AllowCreateDBInstanceOnly", "Effect": "Allow", "Action": [ "rds:CreateDBInstance" ], "Resource": [ "arn:aws:rds:*:123456789012:db:test*", "arn:aws:rds:*:123456789012:og:default*", "arn:aws:rds:*:123456789012:pg:default*", "arn:aws:rds:*:123456789012:subgrp:default" ], "Condition": { "StringEquals": { "rds:DatabaseEngine": "mysql", "rds:DatabaseClass": "db.t2.micro" } } } ] For more information about using identity-based policies with Amazon RDS, see Using Identity-Based Policies (IAM Policies) for Amazon RDS (p. 335). For more information about users, groups, roles, and permissions, see Identities (Users, Groups, and Roles) in the IAM User Guide. Resource-Based Policies Other services, such as Amazon S3, also support resource-based permissions policies. For example, you can attach a policy to an S3 bucket to manage access permissions to that bucket. Amazon RDS doesn't support resource-based policies. API Version 2014-10-31 334 Amazon Relational Database Service User Guide Using Identity-Based Policies (IAM Policies) Specifying Policy Elements: Actions, Effects, Resources, and Principals For each Amazon RDS resource (see Amazon RDS Resources and Operations (p. 332)), the service defines a set of API operations (see Actions). To grant permissions for these API operations, Amazon RDS defines a set of actions that you can specify in a policy. Performing an API operation can require permissions for more than one action. The following are the basic policy elements: • Resource – In a policy, you use an Amazon Resource Name (ARN) to identify the resource to which the policy applies. For more information, see Amazon RDS Resources and Operations (p. 332). • Action – You use action keywords to identify resource operations that you want to allow or deny. For example, the rds:DescribeDBInstances permission allows the user permissions to perform the Amazon RDS DescribeDBInstances operation. • Effect – You specify the effect when the user requests the specific action—this can be either allow or deny. If you don't explicitly grant access to (allow) a resource, access is implicitly denied. You can also explicitly deny access to a resource, which you might do to make sure that a user cannot access it, even if a different policy grants access. • Principal – In identity-based policies (IAM policies), the user that the policy is attached to is the implicit principal. For resource-based policies, you specify the user, account, service, or other entity that you want to receive permissions (applies to resource-based policies only). Amazon RDS doesn't support resource-based policies. To learn more about IAM policy syntax and descriptions, see AWS IAM Policy Reference in the IAM User Guide. For a table showing all of the Amazon RDS API actions and the resources that they apply to, see Amazon RDS API Permissions: Actions, Resources, and Conditions Reference (p. 339). You can test IAM policies with the IAM policy simulator. It automatically provides a list of resources and parameters required for each AWS action, including Amazon RDS actions. The IAM policy simulator determines the permissions required for each of the actions that you specify. For information about the IAM policy simulator, see Testing IAM Policies with the IAM Policy Simulator in the IAM User Guide. Specifying Conditions in a Policy When you grant permissions, you can use the access policy language to specify the conditions when a policy should take effect. For example, you might want a policy to be applied only after a specific date. For more information about specifying conditions in a policy language, see Condition in the IAM User Guide. To express conditions, you use predefined condition keys. There are AWS-wide condition keys and RDSspecific keys that you can use as appropriate. For a complete list of AWS-wide keys, see Available Keys for Conditions in the IAM User Guide. For a complete list of RDS-specific keys, see Using IAM Policy Conditions for Fine-Grained Access Control (p. 355). Using Identity-Based Policies (IAM Policies) for Amazon RDS This topic provides examples of identity-based policies in which an account administrator can attach permissions policies to IAM identities (that is, users, groups, and roles). Important We recommend that you first review the introductory topics that explain the basic concepts and options available for you to manage access to your Amazon RDS resources. For API Version 2014-10-31 335 Amazon Relational Database Service User Guide Using Identity-Based Policies (IAM Policies) more information, see Overview of Managing Access Permissions to Your Amazon RDS Resources (p. 332). The sections in this topic cover the following: • Permissions Required to Use the Amazon RDS Console (p. 337) • AWS Managed (Predefined) Policies for Amazon RDS (p. 337) • Customer Managed Policy Examples (p. 337) The following is an example of an IAM policy: { } "Version": "2012-10-17", "Statement": [ { "Sid": "AllowCreateDBInstanceOnly", "Effect": "Allow", "Action": [ "rds:CreateDBInstance" ], "Resource": [ "arn:aws:rds:*:123456789012:db:test*", "arn:aws:rds:*:123456789012:og:default*", "arn:aws:rds:*:123456789012:pg:default*", "arn:aws:rds:*:123456789012:subgrp:default" ], "Condition": { "StringEquals": { "rds:DatabaseEngine": "mysql", "rds:DatabaseClass": "db.t2.micro" } } } ] The policy includes a single statement that specifies the following permissions for the IAM user: • The policy allows the IAM user to create a DB instance using the CreateDBInstance API action (this also applies to the create-db-instance AWS CLI command and the AWS Management Console). • The Resource element specifies that the user can perform actions on or with resources. You specify resources using an Amazon Resources Name (ARN). This ARN includes the name of the service that the resource belongs to (rds), the AWS Region (* indicates any region in this example), the user account number (123456789012 is the user ID in this example), and the type of resource. For more information about creating ARNs, see Working with Amazon Resource Names (ARNs) in Amazon RDS (p. 177). The Resource element in the example specifies the following policy constraints on resources for the user: • The DB instance identifier for the new DB instance must begin with test (for example, testCustomerData1, test-region2-data). • The option group for the new DB instance must begin with default. • The DB parameter group for the new DB instance must begin with default. • The subnet group for the new DB instance must be the default subnet group. • The Condition element specifies that the DB engine must be MySQL and the DB instance class must be db.t2.micro. The Condition element specifies the conditions when a policy should take effect. You can add additional permissions or restrictions by using the Condition element. For more API Version 2014-10-31 336 Amazon Relational Database Service User Guide Using Identity-Based Policies (IAM Policies) information about specifying conditions, see Using IAM Policy Conditions for Fine-Grained Access Control (p. 355). The policy doesn't specify the Principal element because in an identity-based policy you don't specify the principal who gets the permission. When you attach policy to a user, the user is the implicit principal. When you attach a permission policy to an IAM role, the principal identified in the role's trust policy gets the permissions. For a table showing all of the Amazon RDS API actions and the resources that they apply to, see Amazon RDS API Permissions: Actions, Resources, and Conditions Reference (p. 339). Permissions Required to Use the Amazon RDS Console For a user to work with the Amazon RDS console, that user must have a minimum set of permissions. These permissions allow the user to describe the Amazon RDS resources for their AWS account and to provide other related information, including Amazon EC2 security and network information. If you create an IAM policy that is more restrictive than the minimum required permissions, the console won't function as intended for users with that IAM policy. To ensure that those users can still use the Amazon RDS console, also attach the AmazonRDSReadOnlyAccess managed policy to the user, as described in AWS Managed (Predefined) Policies for Amazon RDS (p. 337). You don't need to allow minimum console permissions for users that are making calls only to the AWS CLI or the Amazon RDS API. AWS Managed (Predefined) Policies for Amazon RDS AWS addresses many common use cases by providing standalone IAM policies that are created and administered by AWS. Managed policies grant necessary permissions for common use cases so you can avoid having to investigate what permissions are needed. For more information, see AWS Managed Policies in the IAM User Guide. The following AWS managed policies, which you can attach to users in your account, are specific to Amazon RDS: • AmazonRDSReadOnlyAccess – Grants read-only access to all Amazon RDS resources for the root AWS account. • AmazonRDSFullAccess – Grants full access to all Amazon RDS resources for the root AWS account. You can also create custom IAM policies that allow users to access the required Amazon RDS API actions and resources. You can attach these custom policies to the IAM users or groups that require those permissions. Customer Managed Policy Examples In this section, you can find example user policies that grant permissions for various Amazon RDS actions. These policies work when you are using RDS API actions, AWS SDKs, or the AWS CLI. When you are using the console, you need to grant additional permissions specific to the console, which is discussed in Permissions Required to Use the Amazon RDS Console (p. 337). Note All examples use the US West (Oregon) Region (us-west-2) and contain fictitious account IDs. Examples • Example 1: Allow a User to Perform Any Describe Action on Any RDS Resource (p. 338) • Example 2: Allow a User to Create a DB Instance That Uses the Specified DB Parameter and Security Groups (p. 338) API Version 2014-10-31 337 Amazon Relational Database Service User Guide Using Identity-Based Policies (IAM Policies) • Example 3: Prevent a User from Deleting a DB Instance (p. 338) Example 1: Allow a User to Perform Any Describe Action on Any RDS Resource The following permissions policy grants permissions to a user to run all of the actions that begin with Describe. These actions show information about an RDS resource, such as a DB instance. The wildcard character (*) in the Resource element indicates that the actions are allowed for all Amazon RDS resources owned by the account. { } "Version":"2012-10-17", "Statement":[ { "Sid":"AllowRDSDescribe", "Effect":"Allow", "Action":"rds:Describe*", "Resource":"*" } ] Example 2: Allow a User to Create a DB Instance That Uses the Specified DB Parameter and Security Groups The following permissions policy grants permissions to allow a user to only create a DB instance that must use the mysql-production DB parameter group and the db-production DB security group. { } "Version":"2012-10-17", "Statement":[ { "Sid":"AllowMySQLProductionCreate", "Effect":"Allow", "Action":"rds:CreateDBInstance", "Resource":[ "arn:aws:rds:us-west-2:123456789012:pg:mysql-production", "arn:aws:rds:us-west-2:123456789012:secgrp:db-production" ] } ] Example 3: Prevent a User from Deleting a DB Instance The following permissions policy grants permissions to prevent a user from deleting a specific DB instance. For example, you might want to deny the ability to delete your production instances to any user that is not an administrator. { } "Version":"2012-10-17", "Statement":[ { "Sid":"DenyDelete1", "Effect":"Deny", "Action":"rds:DeleteDBInstance", "Resource":"arn:aws:rds:us-west-2:123456789012:db:my-mysql-instance" } ] API Version 2014-10-31 338 Amazon Relational Database Service User Guide Amazon RDS API Permissions Reference Amazon RDS API Permissions: Actions, Resources, and Conditions Reference When you set up access control (p. 331) and write permissions policies that you can attach to an IAM identity (identity-based policies), you can use the following as a reference. The following lists each Amazon RDS API operation. Included in the list are the corresponding actions for which you can grant permissions to perform the action, the AWS resource that you can grant the permissions for, and condition keys that you can include for fine-grained access control. You specify the actions in the policy's Action field, the resource value in the policy's Resource field, and conditions in the policy's Condition field. For more information about conditions, see Using IAM Policy Conditions for Fine-Grained Access Control (p. 355). You can use AWS-wide condition keys in your Amazon RDS policies to express conditions. For a complete list of AWS-wide keys, see Available Keys in the IAM User Guide. You can test IAM policies with the IAM policy simulator. It automatically provides a list of resources and parameters required for each AWS action, including Amazon RDS actions. The IAM policy simulator determines the permissions required for each of the actions that you specify. For information about the IAM policy simulator, see Testing IAM Policies with the IAM Policy Simulator in the IAM User Guide. Note To specify an action, use the rds: prefix followed by the API operation name (for example, rds:CreateDBInstance). The following lists RDS API operations and their related actions, resources, and condition keys. Topics • Amazon RDS Actions That Support Resource-Level Permissions (p. 339) • Amazon RDS Actions That Don't Support Resource-Level Permissions (p. 354) Amazon RDS Actions That Support Resource-Level Permissions Resource-level permissions refers to the ability to specify the resources on which users are allowed to perform actions. Amazon RDS has partial support for resource-level permissions. This means that for certain Amazon RDS actions, you can control when users are allowed to use those actions based on conditions that have to be fulfilled, or specific resources that users are allowed to use. For example, you can grant users permission to modify only specific DB instances. The following lists RDS API operations and their related actions, resources, and condition keys. RDS API Operations and Actions Resources Condition Keys AddRoleToDBCluster DB cluster rds:cluster-tag rds:AddRoleToDBCluster arn:aws:rds:region:accountid:cluster:db-cluster-name IAM role — arn:aws:iam::accountid:role/role-name AddSourceIdentifierToSubscription Event subscription API Version 2014-10-31 339 rds:es-tag Amazon Relational Database Service User Guide Amazon RDS API Permissions Reference RDS API Operations and Actions Resources Condition Keys rds:AddSourceIdentifierToSubscription arn:aws:rds:region:accountid:es:subscription-name AddTagsToResource DB instance rds:AddTagsToResourcearn:aws:rds:region:accountid:db:db-instance-name rds:db-tag rds:req-tag DB cluster rds:cluster-tag arn:aws:rds:region:accountid:cluster:db-cluster-name rds:req-tag DB option group rds:og-tag arn:aws:rds:region:accountid:og:option-group-name rds:req-tag DB parameter group rds:pg-tag arn:aws:rds:region:accountid:pg:parameter-group-name rds:req-tag DB cluster parameter group rds:cluster-pg-tag arn:aws:rds:region:accountid:cluster-pg:clusterparameter-group-name rds:req-tag DB security group rds:secgrp-tag arn:aws:rds:region:accountid:secgrp:security-group-name rds:req-tag DB subnet group rds:subgrp-tag arn:aws:rds:region:accountid:subgrp:subnet-group-name rds:req-tag DB snapshot rds:snapshot-tag arn:aws:rds:region:accountid:snapshot:snapshot-name rds:req-tag DB cluster snapshot rds:cluster-snapshot-tag arn:aws:rds:region:accountid:cluster-snapshot:clustersnapshot-name rds:req-tag Event subscription rds:es-tag arn:aws:rds:region:accountid:es:subscription-name rds:req-tag API Version 2014-10-31 340 Amazon Relational Database Service User Guide Amazon RDS API Permissions Reference RDS API Operations and Actions Resources Condition Keys Reserved DB instance rds:ri-tag arn:aws:rds:region:accountid:ri:reserved-db-instance-name rds:req-tag ApplyPendingMaintenanceAction DB instance rds:db-tag rds:ApplyPendingMaintenanceAction arn:aws:rds:region:accountid:db:db-instance-name AuthorizeDBSecurityGroupIngress DB security group rds:secgrp-tag rds:AuthorizeDBSecurityGroupIngress arn:aws:rds:region:accountid:secgrp:security-group-name BacktrackDBCluster DB cluster rds:cluster-tag rds:BacktrackDBCluster arn:aws:rds:region:accountid:cluster:db-cluster-name CopyDBClusterSnapshot DB cluster snapshot rds:cluster-snapshot-tag rds:CopyDBClusterSnapshot arn:aws:rds:region:accountid:cluster-snapshot:clustersnapshot-name CopyDBParameterGroup DB parameter group rds:pg-tag rds:CopyDBParameterGroup arn:aws:rds:region:accountid:pg:parameter-group-name CopyDBSnapshot DB snapshot rds:CopyDBSnapshot arn:aws:rds:region:accountid:snapshot:snapshot-name CopyOptionGroup DB option group rds:snapshot-tag rds:og-tag rds:CopyOptionGroup arn:aws:rds:region:accountid:og:option-group-name CreateDBCluster DB cluster rds:CreateDBCluster arn:aws:rds:region:accountid:cluster:db-cluster-name DB option group rds:DatabaseEngine rds:DatabaseName rds:req-tag rds:og-tag arn:aws:rds:region:accountid:og:option-group-name DB cluster parameter group arn:aws:rds:region:accountid:cluster-pg:clusterparameter-group-name API Version 2014-10-31 341 rds:cluster-pg-tag Amazon Relational Database Service User Guide Amazon RDS API Permissions Reference RDS API Operations and Actions Resources Condition Keys DB subnet group rds:subgrp-tag arn:aws:rds:region:accountid:subgrp:subnet-group-name CreateDBClusterEndpoint DB cluster rds:cluster-tag rds:CreateDBClusterEndpoint arn:aws:rds:region:accountid:cluster:db-cluster-name DB cluster endpoint rds:endpointType arn:aws:rds:region:accountid:cluster-endpoint:db-clusterendpoint-identifier CreateDBClusterParameterGroup DB cluster parameter group rds:req-tag rds:CreateDBClusterParameterGroup arn:aws:rds:region:accountid:cluster-pg:clusterparameter-group-name CreateDBClusterSnapshot DB cluster rds:cluster-tag rds:CreateDBClusterSnapshot arn:aws:rds:region:accountid:cluster:db-cluster-name DB cluster snapshot rds:req-tag arn:aws:rds:region:accountid:cluster-snapshot:clustersnapshot-name CreateDBInstance DB instance rds:CreateDBInstance arn:aws:rds:region:accountid:db:db-instance-name rds:DatabaseClass rds:DatabaseEngine rds:DatabaseName rds:MultiAz rds:Piops rds:StorageSize rds:Vpc rds:req-tag DB option group rds:og-tag arn:aws:rds:region:accountid:og:option-group-name DB parameter group arn:aws:rds:region:accountid:pg:parameter-group-name API Version 2014-10-31 342 rds:pg-tag Amazon Relational Database Service User Guide Amazon RDS API Permissions Reference RDS API Operations and Actions Resources Condition Keys DB security group rds:secgrp-tag arn:aws:rds:region:accountid:secgrp:security-group-name DB subnet group rds:subgrp-tag arn:aws:rds:region:accountid:subgrp:subnet-group-name DB cluster rds:cluster-tag arn:aws:rds:region:accountid:cluster:db-cluster-name CreateDBInstanceReadReplica DB instance rds:DatabaseClass rds:CreateDBInstanceReadReplica arn:aws:rds:region:accountid:db:db-instance-name rds:Piops DB option group rds:req-tag rds:og-tag arn:aws:rds:region:accountid:og:option-group-name DB subnet group rds:subgrp-tag arn:aws:rds:region:accountid:subgrp:subnet-group-name CreateDBParameterGroup DB parameter group rds:req-tag rds:CreateDBParameterGroup arn:aws:rds:region:accountid:pg:parameter-group-name CreateDBSecurityGroup DB security group rds:req-tag rds:CreateDBSecurityGroup arn:aws:rds:region:accountid:secgrp:security-group-name CreateDBSnapshot DB instance rds:db-tag rds:CreateDBSnapshot arn:aws:rds:region:accountid:db:db-instance-name DB snapshot rds:req-tag arn:aws:rds:region:accountid:snapshot:snapshot-name CreateDBSubnetGroup DB subnet group rds:CreateDBSubnetGroup arn:aws:rds:region:accountid:subgrp:subnet-group-name API Version 2014-10-31 343 rds:req-tag Amazon Relational Database Service User Guide Amazon RDS API Permissions Reference RDS API Operations and Actions Resources Condition Keys CreateEventSubscription Event subscription rds:req-tag rds:CreateEventSubscription arn:aws:rds:region:accountid:es:subscription-name CreateOptionGroup DB option group rds:req-tag rds:CreateOptionGrouparn:aws:rds:region:accountid:og:option-group-name DeleteDBCluster DB cluster rds:cluster-tag rds:DeleteDBCluster arn:aws:rds:region:accountid:cluster:db-cluster-name DB cluster snapshot rds:cluster-snapshot-tag arn:aws:rds:region:accountid:cluster-snapshot:clustersnapshot-name DeleteDBClusterEndpoint DB cluster endpoint rds:DeleteDBClusterEndpoint arn:aws:rds:region:accountid:cluster-endpoint:db-clusterendpoint-identifier DeleteDBClusterParameterGroup DB cluster parameter group rds:cluster-pg-tag rds:DeleteDBClusterParameterGroup arn:aws:rds:region:accountid:cluster-pg:clusterparameter-group-name DeleteDBClusterSnapshot DB cluster snapshot rds:cluster-snapshot-tag rds:DeleteDBClusterSnapshot arn:aws:rds:region:accountid:cluster-snapshot:clustersnapshot-name DeleteDBInstance DB instance rds:db-tag rds:DeleteDBInstance arn:aws:rds:region:accountid:db:db-instance-name DeleteDBParameterGroup DB parameter group rds:pg-tag rds:DeleteDBParameterGroup arn:aws:rds:region:accountid:pg:parameter-group-name DeleteDBSecurityGroup DB security group rds:DeleteDBSecurityGroup arn:aws:rds:region:accountid:secgrp:security-group-name API Version 2014-10-31 344 rds:secgrp-tag Amazon Relational Database Service User Guide Amazon RDS API Permissions Reference RDS API Operations and Actions Resources Condition Keys DeleteDBSnapshot DB snapshot rds:snapshot-tag rds:DeleteDBSnapshot arn:aws:rds:region:accountid:snapshot:snapshot-name DeleteDBSubnetGroup DB subnet group rds:subgrp-tag rds:DeleteDBSubnetGroup arn:aws:rds:region:accountid:subgrp:subnet-group-name DeleteEventSubscription Event subscription rds:es-tag rds:DeleteEventSubscription arn:aws:rds:region:accountid:es:subscription-name DeleteOptionGroup DB option group rds:og-tag rds:DeleteOptionGrouparn:aws:rds:region:accountid:og:option-group-name DescribeDBClusterEndpoints DB cluster rds:cluster-tag rds:DescribeDBClusterEndpoints arn:aws:rds:region:accountid:cluster:db-cluster-name DB cluster endpoint arn:aws:rds:region:accountid:cluster-endpoint:db-clusterendpoint-identifier DescribeDBClusterParameterGroups DB cluster parameter group rds:cluster-pg-tag rds:DescribeDBClusterParameterGroups arn:aws:rds:region:accountid:cluster-pg:clusterparameter-group-name DescribeDBClusterParameters DB cluster parameter group rds:cluster-pg-tag rds:DescribeDBClusterParameters arn:aws:rds:region:accountid:cluster-pg:clusterparameter-group-name DescribeDBClusters DB cluster rds:cluster-tag rds:DescribeDBClusters arn:aws:rds:region:accountid:cluster:db-cluster-instancename DescribeDBClusterSnapshotAttributes DB cluster snapshot rds:DescribeDBClusterSnapshotAttributes arn:aws:rds:region:accountid:cluster-snapshot:clustersnapshot-name API Version 2014-10-31 345 rds:cluster-snapshot-tag Amazon Relational Database Service User Guide Amazon RDS API Permissions Reference RDS API Operations and Actions Resources DescribeDBEngineVersions DB parameter group Condition Keys rds:pg-tag rds:DescribeDBEngineVersions arn:aws:rds:region:accountid:pg:parameter-group-name DescribeDBLogFiles DB instance rds:db-tag rds:DescribeDBLogFiles arn:aws:rds:region:accountid:db:db-instance-name DescribeDBParameterGroups DB parameter group rds:pg-tag rds:DescribeDBParameterGroups arn:aws:rds:region:accountid:pg:parameter-group-name DescribeDBParameters DB parameter group rds:pg-tag rds:DescribeDBParameters arn:aws:rds:region:accountid:pg:parameter-group-name DescribeDBSecurityGroups DB security group rds:secgrp-tag rds:DescribeDBSecurityGroups arn:aws:rds:region:accountid:secgrp:security-group-name DescribeDBSnapshotAttributes DB snapshot rds:snapshot-tag rds:DescribeDBSnapshotAttributes arn:aws:rds:region:accountid:snapshot:snapshot-name DescribeDBSnapshots DB instance rds:db-tag rds:DescribeDBSnapshots arn:aws:rds:region:accountid:db:db-instance-name DB snapshot rds:snapshot-tag arn:aws:rds:region:accountid:snapshot:snapshot-name DescribeDBSubnetGroups DB subnet group rds:subgrp-tag rds:DescribeDBSubnetGroups arn:aws:rds:region:accountid:subgrp:subnet-group-name DescribeEventSubscriptionsEvent subscription rds:es-tag rds:DescribeEventSubscriptions arn:aws:rds:region:accountid:es:subscription-name DescribeOptionGroups DB option group rds:DescribeOptionGroups arn:aws:rds:region:accountid:og:option-group-name API Version 2014-10-31 346 rds:og-tag Amazon Relational Database Service User Guide Amazon RDS API Permissions Reference RDS API Operations and Actions Resources Condition Keys DescribePendingMaintenanceActions DB instance rds:DatabaseClass rds:DescribePendingMaintenanceActions arn:aws:rds:region:accountid:db:db-instance-name rds:DatabaseEngine rds:DatabaseName rds:MultiAz rds:Piops rds:StorageSize rds:Vpc rds:db-tag DescribeReservedDBInstances Reserved DB instance rds:DatabaseClass rds:DescribeReservedDBInstances arn:aws:rds:region:accountid:ri:reserved-db-instance-name rds:MultiAz DescribeReservedDBInstancesOfferings DB instance rds:DatabaseClass rds:DescribeReservedDBInstancesOfferings arn:aws:rds:region:accountid:db:db-instance-name rds:MultiAz DownloadDBLogFilePortionDB instance rds:db-tag rds:ri-tag rds:DownloadDBLogFilePortion arn:aws:rds:region:accountid:db:db-instance-name FailoverDBCluster DB cluster rds:cluster-tag rds:FailoverDBClusterarn:aws:rds:region:accountid:cluster:db-cluster-instancename ListTagsForResource DB instance rds:db-tag rds:ListTagsForResource arn:aws:rds:region:accountid:db:db-instance-name DB cluster rds:cluster-tag arn:aws:rds:region:accountid:cluster:db-cluster-name DB option group rds:og-tag arn:aws:rds:region:accountid:og:option-group-name DB parameter group arn:aws:rds:region:accountid:pg:parameter-group-name API Version 2014-10-31 347 rds:pg-tag Amazon Relational Database Service User Guide Amazon RDS API Permissions Reference RDS API Operations and Actions Resources Condition Keys DB security group rds:secgrp-tag arn:aws:rds:region:accountid:secgrp:security-group-name DB cluster parameter group rds:cluster-pg-tag arn:aws:rds:region:accountid:cluster-pg:clusterparameter-group-name DB subnet group rds:subgrp-tag arn:aws:rds:region:accountid:subgrp:subnet-group-name DB snapshot rds:snapshot-tag arn:aws:rds:region:accountid:snapshot:snapshot-name DB cluster snapshot rds:cluster-snapshot-tag arn:aws:rds:region:accountid:cluster-snapshot:clustersnapshot-name Event subscription rds:es-tag arn:aws:rds:region:accountid:es:subscription-name Reserved DB instance rds:ri-tag arn:aws:rds:region:accountid:ri:reserved-db-instance-name ModifyDBCluster DB cluster rds:cluster-tag rds:ModifyDBCluster arn:aws:rds:region:accountid:cluster:db-cluster-name DB option group rds:og-tag arn:aws:rds:region:accountid:og:option-group-name DB cluster parameter group arn:aws:rds:region:accountid:cluster-pg:clusterparameter-group-name API Version 2014-10-31 348 rds:cluster-pg-tag Amazon Relational Database Service User Guide Amazon RDS API Permissions Reference RDS API Operations and Actions Resources ModifyDBClusterEndpoint DB cluster endpoint Condition Keys rds:endpointType rds:ModifyDBClusterEndpoint arn:aws:rds:region:accountid:cluster-endpoint:db-clusterendpoint-identifier ModifyDBClusterParameterGroup DB cluster parameter group rds:cluster-pg-tag rds:ModifyDBClusterParameterGroup arn:aws:rds:region:accountid:cluster-pg:clusterparameter-group-name ModifyDBClusterSnapshotAttribute DB cluster snapshot rds:cluster-snapshot-tag rds:ModifyDBClusterSnapshotAttribute arn:aws:rds:region:accountid:cluster-snapshot:clustersnapshot-name ModifyDBInstance DB instance rds:ModifyDBInstance arn:aws:rds:region:accountid:db:db-instance-name rds:DatabaseClass rds:MultiAz rds:Piops rds:StorageSize rds:Vpc rds:db-tag DB option group rds:og-tag arn:aws:rds:region:accountid:og:option-group-name DB parameter group rds:pg-tag arn:aws:rds:region:accountid:pg:parameter-group-name DB security group rds:secgrp-tag arn:aws:rds:region:accountid:secgrp:security-group-name ModifyDBParameterGroup DB parameter group rds:pg-tag rds:ModifyDBParameterGroup arn:aws:rds:region:accountid:pg:parameter-group-name ModifyDBSnapshotAttribute DB snapshot rds:ModifyDBSnapshotAttribute arn:aws:rds:region:accountid:snapshot:snapshot-name API Version 2014-10-31 349 rds:snapshot-tag Amazon Relational Database Service User Guide Amazon RDS API Permissions Reference RDS API Operations and Actions Resources Condition Keys ModifyDBSubnetGroup DB subnet group rds:subgrp-tag rds:ModifyDBSubnetGroup arn:aws:rds:region:accountid:subgrp:subnet-group-name ModifyEventSubscription Event subscription rds:es-tag rds:ModifyEventSubscription arn:aws:rds:region:accountid:es:subscription-name ModifyOptionGroup DB option group rds:og-tag rds:ModifyOptionGrouparn:aws:rds:region:accountid:og:option-group-name PromoteReadReplica DB instance rds:db-tag rds:PromoteReadReplica arn:aws:rds:region:accountid:db:db-instance-name PromoteReadReplicaDBCluster DB cluster rds:PromoteReadReplicaDBCluster arn:aws:rds:region:accountid:cluster:db-cluster-name RebootDBInstance DB instance rds:db-tag rds:RebootDBInstance arn:aws:rds:region:accountid:db:db-instance-name RemoveSourceIdentifierFromSubscription Event subscription rds:es-tag rds:RemoveSourceIdentifierFromSubscription arn:aws:rds:region:accountid:es:subscription-name RemoveTagsFromResource DB instance rds:db-tag rds:RemoveTagsFromResource arn:aws:rds:region:accountid:db:db-instance-name rds:req-tag DB cluster rds:cluster-tag arn:aws:rds:region:accountid:cluster:db-cluster-name rds:req-tag DB option group rds:og-tag arn:aws:rds:region:accountid:og:option-group-name rds:req-tag DB parameter group rds:pg-tag arn:aws:rds:region:accountid:pg:parameter-group-name rds:req-tag API Version 2014-10-31 350 Amazon Relational Database Service User Guide Amazon RDS API Permissions Reference RDS API Operations and Actions Resources Condition Keys DB cluster parameter group rds:cluster-pg-tag arn:aws:rds:region:accountid:cluster-pg:clusterparameter-group-name rds:req-tag DB security group rds:secgrp-tag arn:aws:rds:region:accountid:secgrp:security-group-name rds:req-tag DB subnet group rds:subgrp-tag arn:aws:rds:region:accountid:subgrp:subnet-group-name rds:req-tag DB snapshot rds:snapshot-tag arn:aws:rds:region:accountid:snapshot:snapshot-name rds:req-tag DB cluster snapshot rds:cluster-snapshot-tag arn:aws:rds:region:accountid:cluster-snapshot:clustersnapshot-name rds:req-tag Event subscription rds:es-tag arn:aws:rds:region:accountid:es:subscription-name rds:req-tag Reserved DB instance rds:ri-tag arn:aws:rds:region:accountid:ri:reserved-db-instance-name rds:req-tag ResetDBClusterParameterGroup DB cluster parameter group rds:cluster-pg-tag rds:ResetDBClusterParameterGroup arn:aws:rds:region:accountid:cluster-pg:clusterparameter-group-name ResetDBParameterGroup DB parameter group rds:pg-tag rds:ResetDBParameterGroup arn:aws:rds:region:accountid:pg:parameter-group-name RestoreDBClusterFromS3 DB cluster rds:DatabaseEngine rds:RestoreDBClusterFromS3 arn:aws:rds:region:accountid:cluster:db-cluster-instancename rds:DatabaseName API Version 2014-10-31 351 rds:req-tag Amazon Relational Database Service User Guide Amazon RDS API Permissions Reference RDS API Operations and Actions Resources Condition Keys DB cluster parameter group rds:cluster-pg-tag arn:aws:rds:region:accountid:cluster-pg:clusterparameter-group-name DB option group rds:og-tag arn:aws:rds:region:accountid:og:option-group-name DB subnet group rds:subgrp-tag arn:aws:rds:region:accountid:subgrp:subnet-group-name RestoreDBClusterFromSnapshot DB cluster rds:DatabaseEngine rds:RestoreDBClusterFromSnapshot arn:aws:rds:region:accountid:cluster:db-cluster-instancename rds:DatabaseName DB option group rds:req-tag rds:og-tag arn:aws:rds:region:accountid:og:option-group-name DB cluster snapshot rds:cluster-snapshot-tag arn:aws:rds:region:accountid:cluster-snapshot:clustersnapshot-name RestoreDBClusterToPointInTime DB cluster rds:req-tag rds:RestoreDBClusterToPointInTime arn:aws:rds:region:accountid:cluster:db-cluster-instancename DB option group rds:og-tag arn:aws:rds:region:accountid:og:option-group-name DB subnet group arn:aws:rds:region:accountid:subgrp:subnet-group-name API Version 2014-10-31 352 rds:subgrp-tag Amazon Relational Database Service User Guide Amazon RDS API Permissions Reference RDS API Operations and Actions Resources Condition Keys RestoreDBInstanceFromDBSnapshot DB instance rds:DatabaseClass rds:RestoreDBInstanceFromDBSnapshot arn:aws:rds:region:accountid:db:db-instance-name rds:DatabaseEngine rds:DatabaseName rds:MultiAz rds:Piops rds:Vpc rds:req-tag DB option group rds:og-tag arn:aws:rds:region:accountid:og:option-group-name DB snapshot rds:snapshot-tag arn:aws:rds:region:accountid:snapshot:snapshot-name DB subnet group rds:subgrp-tag arn:aws:rds:region:accountid:subgrp:subnet-group-name RestoreDBInstanceToPointInTime DB instance rds:DatabaseClass rds:RestoreDBInstanceToPointInTime arn:aws:rds:region:accountid:db:db-instance-name rds:DatabaseEngine rds:DatabaseName rds:MultiAz rds:Piops rds:Vpc rds:req-tag DB option group rds:og-tag arn:aws:rds:region:accountid:og:option-group-name DB snapshot rds:snapshot-tag arn:aws:rds:region:accountid:snapshot:snapshot-name DB subnet group arn:aws:rds:region:accountid:subgrp:subnet-group-name API Version 2014-10-31 353 rds:subgrp-tag Amazon Relational Database Service User Guide Amazon RDS API Permissions Reference RDS API Operations and Actions Resources RevokeDBSecurityGroupIngress DB security group Condition Keys rds:secgrp-tag rds:RevokeDBSecurityGroupIngress arn:aws:rds:region:accountid:secgrp:security-group-name StartDBInstance DB instance rds:StartDBInstance arn:aws:rds:region:accountid:db:db-instance-name rds:DatabaseClass rds:DatabaseEngine rds:DatabaseName rds:MultiAz rds:Piops rds:Vpc rds:db-tag StopDBInstance DB instance rds:DatabaseClass rds:StopDBInstance arn:aws:rds:region:accountid:db:db-instance-name rds:DatabaseEngine rds:DatabaseName rds:MultiAz rds:Piops rds:Vpc rds:db-tag Amazon RDS Actions That Don't Support Resource-Level Permissions You can use all Amazon RDS actions in an IAM policy to either grant or deny users permission to use that action. However, not all Amazon RDS actions support resource-level permissions, which enable you to specify the resources on which an action can be performed. The following Amazon RDS API actions currently don't support resource-level permissions. Therefore, to use these actions in an IAM policy, you must grant users permission to use all resources for the action by using a * wildcard for the Resource element in your statement. • rds:DescribeAccountAttributes • rds:DescribeCertificates • rds:DescribeDBClusterSnapshots • rds:DescribeDBInstances • rds:DescribeEngineDefaultClusterParameters • rds:DescribeEngineDefaultParameters • rds:DescribeEventCategories • rds:DescribeEvents • rds:DescribeOptionGroupOptions API Version 2014-10-31 354 Amazon Relational Database Service User Guide Using Conditions • rds:DescribeOrderableDBInstanceOptions • rds:DownloadCompleteDBLogFile • rds:PurchaseReservedDBInstancesOffering Using IAM Policy Conditions for Fine-Grained Access Control When you grant permissions in Amazon RDS, you can specify conditions that determine how a permissions policy takes effect. Overview In Amazon RDS, you have the option to specify conditions when granting permissions using an IAM policy (see Access Control (p. 331)). For example, you can: • Allow users to create a DB instance only if they specify a particular database engine. • Allow users to modify RDS resources that are tagged with a particular tag name and tag value. There are two ways to specify conditions in an IAM policy for Amazon RDS: • Using Condition Keys (p. 355) • Using Custom Tags (p. 357) Specifying Conditions: Using Condition Keys AWS provides a set of predefined condition keys (AWS-wide condition keys) for all AWS services that support IAM for access control. For example, you can use the aws:userid condition key to require a specific AWS ID when requesting an action. For more information and a list of the AWS-wide condition keys, see Available Keys for Conditions in the IAM User Guide. Note Condition keys are case sensitive. In addition Amazon RDS also provides its own condition keys that you can include in Condition elements in an IAM permissions policy. The following table shows the RDS condition keys that apply to RDS resources. RDS Condition Key Description Value Type rds:DatabaseClass A type of DB instance class. String rds:DatabaseEngine A database engine, such as MySQL. String rds:DatabaseNameThe user-defined name of the database on the DB instance. String rds:MultiAz A value that specifies whether the DB instance runs in multiple Availability Zones. To indicate that the DB instance is using Multi-AZ, specify true. Boolean rds:Piops A value that contains the number of Provisioned IOPS (PIOPS) that the instance supports. To indicate a DB instance that does not have PIOPS enabled, specify 0. Integer API Version 2014-10-31 355 Amazon Relational Database Service User Guide Using Conditions RDS Condition Key Description Value Type rds:StorageSize The storage volume size (in GiB). Integer rds:Vpc A value that specifies whether the DB instance runs in an Amazon Virtual Private Cloud (Amazon VPC). To indicate that the DB instance runs in an Amazon VPC, specify true. Boolean rds:req-tag A value that limits the set of tag keys and values that can be used to tag a resource. String For example, the following Condition element uses a condition key and specifies the MySQL database engine. You could apply this to an IAM policy that allows permission to the rds:CreateDBInstance action to enable users to only create DB instances with the MySQL database engine. For an example of an IAM policy that uses this condition, see Example Policies: Using Condition Keys (p. 356). "Condition":{"StringEquals":{"rds:DatabaseEngine": "mysql" } } For a list of all of the RDS condition key identifiers and the RDS actions and resources that they apply to, see Amazon RDS API Permissions: Actions, Resources, and Conditions Reference (p. 339). Example Policies: Using Condition Keys Following are examples of how you can use condition keys in Amazon RDS IAM permissions policies. Example 1: Grant Permission to Create a DB Instance that Uses a Specific DB Engine and Isn't MultiAZ The following policy uses an RDS condition key and allows a user to create only DB instances that use the MySQL database engine and don't use MultiAZ. The Condition element indicates the requirement that the database engine is MySQL. { } "Version":"2012-10-17", "Statement":[ { "Sid":"AllowMySQLCreate", "Effect":"Allow", "Action":"rds:CreateDBInstance", "Resource":"*", "Condition":{ "StringEquals":{ "rds:DatabaseEngine":"mysql" }, "Bool":{ "rds:MultiAz": false } } } ] Example 2: Explicitly Deny Permission to Create DB Instances for Certain DB Instance Classes and Create DB Instances that Use Provisioned IOPS The following policy explicitly denies permission to create DB instances that use the DB instance classes r3.8xlarge and m4.10xlarge, which are the largest and most expensive instances. This policy also prevents users from creating DB instances that use Provisioned IOPS, which incurs an additional cost. API Version 2014-10-31 356 Amazon Relational Database Service User Guide Using Conditions Explicitly denying permission supersedes any other permissions granted. This ensures that identities to not accidentally get permission that you never want to grant. { "Version":"2012-10-17", "Statement":[ { "Sid":"DenyLargeCreate", "Effect":"Deny", "Action":"rds:CreateDBInstance", "Resource":"*", "Condition":{ "StringEquals":{ "rds:DatabaseClass":[ "db.r3.8xlarge", "db.m4.10xlarge" ] } } }, { "Sid":"DenyPIOPSCreate", "Effect":"Deny", "Action":"rds:CreateDBInstance", "Resource":"*", "Condition":{ "NumericNotEquals":{ "rds:Piops":"0" } } } ] } Example 3: Limit the Set of Tag Keys and Values That Can Be Used to Tag a Resource The following policy uses an RDS condition key and allows the addition of a tag with the key stage to be added to a resource with the values test, qa, and production. { { } "Version" : "2012-10-17", "Statement" : [{ "Effect" : "Allow", "Action" : [ "rds:AddTagsToResource", "rds:RemoveTagsFromResource" ], "Resource" : "*", "Condition" : { "streq" : { "rds:req-tag/stage" : [ "test", "qa", "production" ] } } ] } } Specifying Conditions: Using Custom Tags RDS supports specifying conditions in an IAM policy using custom tags. For example, if you add a tag named environment to your DB instances with values such as beta, staging, production, and so on, you can create a policy that restricts certain users to DB instances based on the environment tag value. API Version 2014-10-31 357 Amazon Relational Database Service User Guide Using Conditions Note Custom tag identifiers are case-sensitive. The following table lists the RDS tag identifiers that you can use in a Condition element. RDS Tag Identifier Applies To db-tag DB instances, including Read Replicas snapshot-tag DB snapshots ri-tag Reserved DB instances secgrp-tag DB security groups og-tag DB option groups pg-tag DB parameter groups subgrp-tag DB subnet groups es-tag Event subscriptions cluster-tag DB clusters cluster-pg-tag DB cluster parameter groups cluster-snapshot-tag DB cluster snapshots The syntax for a custom tag condition is as follows: "Condition":{"StringEquals":{"rds:rds-tag-identifier/tag-name": ["value"]} } For example, the following Condition element applies to DB instances with a tag named environment and a tag value of production. "Condition":{"StringEquals":{"rds:db-tag/environment": ["production"]} } For information about creating tags, see Tagging Amazon RDS Resources (p. 134). Important If you manage access to your RDS resources using tagging, we recommend that you secure access to the tags for your RDS resources. You can manage access to tags by creating policies for the AddTagsToResource and RemoveTagsFromResource actions. For example, the following policy denies users the ability to add or remove tags for all resources. You can then create policies to allow specific users to add or remove tags. { "Version":"2012-10-17", "Statement":[ { "Sid":"DenyTagUpdates", "Effect":"Deny", "Action":[ "rds:AddTagsToResource", "rds:RemoveTagsFromResource" ], "Resource":"*" } ] API Version 2014-10-31 358 Amazon Relational Database Service User Guide Using Conditions } For a list of all of the condition key values, and the RDS actions and resources that they apply to, see Amazon RDS API Permissions: Actions, Resources, and Conditions Reference (p. 339). Example Policies: Using Custom Tags Following are examples of how you can use custom tags in Amazon RDS IAM permissions policies. For more information about adding tags to an Amazon RDS resource, see Working with Amazon Resource Names (ARNs) in Amazon RDS (p. 177). Note All examples use the us-west-2 region and contain fictitious account IDs. Example 1: Grant Permission for Actions on a Resource with a Specific Tag with Two Different Values The following policy allows permission to perform the ModifyDBInstance and CreateDBSnapshot APIs on instances with either the stage tag set to development or test. { } "Version":"2012-10-17", "Statement":[ { "Sid":"AllowDevTestCreate", "Effect":"Allow", "Action":[ "rds:ModifyDBInstance", "rds:CreateDBSnapshot" ], "Resource":"*", "Condition":{ "StringEquals":{ "rds:db-tag/stage":[ "development", "test" ] } } } ] Example 2: Explicitly Deny Permission to Create a DB Instance that Uses Specified DB Parameter Groups The following policy explicitly denies permission to create a DB instance that uses DB parameter groups with specific tag values. You might apply this policy if you require that a specific customer-created DB parameter group always be used when creating DB instances. Note that policies that use Deny are most often used to restrict access that was granted by a broader policy. Explicitly denying permission supersedes any other permissions granted. This ensures that identities to not accidentally get permission that you never want to grant. { "Version":"2012-10-17", "Statement":[ { "Sid":"DenyProductionCreate", "Effect":"Deny", "Action":"rds:CreateDBInstance", API Version 2014-10-31 359 Amazon Relational Database Service User Guide IAM Database Authentication for MySQL and PostgreSQL } ] } "Resource":"*", "Condition":{ "StringEquals":{ "rds:pg-tag/usage":"prod" } } Example 3: Grant Permission for Actions on a DB Instance with an Instance Name that is Prefixed with a User Name The following policy allows permission to call any API (except to AddTagsToResource or RemoveTagsFromResource) on a DB instance that has a DB instance name that is prefixed with the user's name and that has a tag called stage equal to devo or that has no tag called stage. The Resource line in the policy identifies a resource by its Amazon Resource Name (ARN). For more information about using ARNs with Amazon RDS resources, see Working with Amazon Resource Names (ARNs) in Amazon RDS (p. 177). { } "Version":"2012-10-17", "Statement":[ { "Sid":"AllowFullDevAccessNoTags", "Effect":"Allow", "NotAction":[ "rds:AddTagsToResource", "rds:RemoveTagsFromResource" ], "Resource":"arn:aws:rds:*:123456789012:db:${aws:username}*", "Condition":{ "StringEqualsIfExists":{ "rds:db-tag/stage":"devo" } } } ] IAM Database Authentication for MySQL and PostgreSQL You can authenticate to your DB instance using AWS Identity and Access Management (IAM) database authentication. IAM database authentication works with MySQL and PostgreSQL. With this authentication method, you don't need to use a password when you connect to a DB instance. Instead, you use an authentication token. An authentication token is a unique string of characters that Amazon RDS generates on request. Authentication tokens are generated using AWS Signature Version 4. Each token has a lifetime of 15 minutes. You don't need to store user credentials in the database, because authentication is managed externally using IAM. You can also still use standard database authentication. IAM database authentication provides the following benefits: • Network traffic to and from the database is encrypted using Secure Sockets Layer (SSL). • You can use IAM to centrally manage access to your database resources, instead of managing access individually on each DB instance. API Version 2014-10-31 360 Amazon Relational Database Service User Guide IAM Database Authentication for MySQL and PostgreSQL • For applications running on Amazon EC2, you can use profile credentials specific to your EC2 instance to access your database instead of a password, for greater security. Topics • Availability for IAM Database Authentication (p. 361) • MySQL Limitations for IAM Database Authentication (p. 361) • PostgreSQL Limitations for IAM Database Authentication (p. 361) • Enabling and Disabling IAM Database Authentication (p. 362) • Creating and Using an IAM Policy for IAM Database Access (p. 363) • Creating a Database Account Using IAM Authentication (p. 366) • Connecting to Your DB Instance Using IAM Authentication (p. 367) Availability for IAM Database Authentication IAM database authentication is available for the following database engines and instance classes: • MySQL 5.6, minor version 5.6.34 or higher. All instance classes are supported, except for db.m1.small. • MySQL 5.7, minor version 5.7.16 or higher. All instance classes are supported, except for db.m1.small. • PostgreSQL versions 9.5.14, 9.6.9 or higher, and version 10.4 or higher. Note IAM database authentication is not supported for MySQL 5.5 or MySQL 8.0. MySQL Limitations for IAM Database Authentication When using IAM database authentication with MySQL, you are limited to a maximum of 20 new connections per second. If you are using a db.t2.micro instance class, the limit is 10 connections per second. The database engines that work with Amazon RDS don't impose any limits on authentication attempts per second. However, when you use IAM database authentication, your application must generate an authentication token. Your application then uses that token to connect to the DB instance. If you exceed the limit of maximum new connections per second, then the extra overhead of IAM database authentication can cause connection throttling. The extra overhead can cause even existing connections to drop. For information about the maximum total connections for MySQL, see Maximum MySQL connections (p. 598) We recommend the following when using the MySQL engine: • Use IAM database authentication as a mechanism for temporary, personal access to databases. • Use IAM database authentication only for workloads that can be easily retried. • Don't use IAM database authentication if your application requires more than 20 new connections per second. PostgreSQL Limitations for IAM Database Authentication When using IAM database authentication with PostgreSQL, note the following limitations: • The maximum number of connections for your database instance may be limited depending on the instance type and your workload. API Version 2014-10-31 361 Amazon Relational Database Service User Guide IAM Database Authentication for MySQL and PostgreSQL • IAM database authentication is not supported with M5 instance types. Enabling and Disabling IAM Database Authentication By default, IAM database authentication is disabled on DB instances. You can enable IAM database authentication (or disable it again) using the AWS Management Console, AWS CLI, or the API. IAM authentication for PostgreSQL DB instances require that the SSL value be 1. You cannot enable IAM authentication for a PostgreSQL DB instance if the SSL value is 0. You can't change the SSL value to 0 if IAM authentication is enabled for a PostgreSQL DB instance. AWS Management Console To create a new DB instance with IAM authentication by using the console, see either Creating a DB Instance Running the MySQL Database Engine (p. 587) or Creating a DB Instance Running the PostgreSQL Database Engine (p. 964). Each creation workflow has a Configure Advanced Settings page, where you can enable IAM DB authentication. In that page's Database Options section, choose Yes for Enable IAM DB Authentication. To enable or disable IAM authentication for an existing DB instance 1. Open the Amazon RDS console at https://console.aws.amazon.com/rds/. 2. In the navigation pane, choose Instances. 3. Choose the DB instance that you want to modify. 4. Choose Instance actions, and then choose Modify. 5. In the Database options section, for IAM DB authentication, choose Enable IAM DB authentication or Disable, and then choose Continue. 6. To apply the changes immediately, choose Apply immediately. 7. Choose Modify DB instance . To restore a DB instance 1. Open the Amazon RDS console at https://console.aws.amazon.com/rds/. 2. In the navigation pane, choose Snapshots. 3. Choose the snapshot that you want to restore, and then choose Restore Snapshot from Snapshot Actions. 4. In the Settings section, enter an identifier for the DB instance for DB Instance Identifier. 5. In the Database options section, for IAM DB authentication, choose Enable IAM DB authentication or Disable. 6. Choose Restore DB Instance. AWS CLI To create a new DB instance with IAM authentication by using the AWS CLI, use the create-dbinstance command. Specify the --enable-iam-database-authentication option, as shown in the following example. aws rds create-db-instance \ --db-instance-identifier mydbinstance \ --db-instance-class db.m3.medium \ --engine MySQL \ --allocated-storage 20 \ API Version 2014-10-31 362 Amazon Relational Database Service User Guide IAM Database Authentication for MySQL and PostgreSQL --master-username masterawsuser \ --master-user-password masteruserpassword \ --enable-iam-database-authentication To update an existing DB cluster to have or not have IAM authentication, use the AWS CLI command modify-db-instance. Specify either the --enable-iam-database-authentication or --noenable-iam-database-authentication option, as appropriate. By default, Amazon RDS performs the modification during the next maintenance window. If you want to override this and enable IAM DB authentication as soon as possible, use the --apply-immediately parameter. The following example shows how to immediately enable IAM authentication for an existing DB instance. aws rds modify-db-instance \ --db-instance-identifier mydbinstance \ --apply-immediately \ --enable-iam-database-authentication If you are restoring a DB instance, use one of the following AWS CLI commands: • restore-db-instance-to-point-in-time • restore-db-instance-from-db-snapshot The IAM database authentication setting defaults to that of the source snapshot. To change this setting, set the --enable-iam-database-authentication or --no-enable-iam-databaseauthentication option, as appropriate. RDS API To create a new DB instance with IAM authentication by using the API, use the API operation CreateDBInstance. Set the EnableIAMDatabaseAuthentication parameter to true. To update an existing DB instance to have IAM authentication, use the API operation ModifyDBInstance. Set the EnableIAMDatabaseAuthentication parameter to true to enable IAM authentication, or false to disable it. If you are restoring a DB instance, use one of the following API actions: • RestoreDBInstanceToPointInTime • RestoreDBInstanceFromDBSnapshot The IAM database authentication setting defaults to that of the source snapshot. To change this setting, set the EnableIAMDatabaseAuthentication parameter to true to enable IAM authentication, or false to disable it. Creating and Using an IAM Policy for IAM Database Access To allow an IAM user or role to connect to your DB instance, you must create an IAM policy. After that, you attach the policy to an IAM user or role. Note To learn more about IAM policies, see Authentication and Access Control (p. 330). The following example policies allows an IAM user to connect to a DB instance using IAM database authentication. API Version 2014-10-31 363 Amazon Relational Database Service User Guide IAM Database Authentication for MySQL and PostgreSQL { } "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "rds-db:connect" ], "Resource": [ "arn:aws:rds-db:us-east-2:1234567890:dbuser:db-ABCDEFGHIJKL01234/db_user" ] } ] Note Don't confuse the rds-db: prefix with other Amazon RDS action prefixes that begin with rds:. You use the rds-db: prefix and the rds-db:connect action only for IAM database authentication. They aren't valid in any other context. Currently, the IAM console displays an error for policies with the rds-db:connect action. You can ignore this error. The example policy includes a single statement with the following elements: • Effect – Specify Allow to grant access to the DB instance. If you don't explicitly allow access, then access is denied by default. • Action – Specify rds-db:connect to allow connection to the DB instance. • Resource – Specify an Amazon Resource Name (ARN) that describes one database account in one DB instance. The ARN format is as follows. arn:aws:rds-db:region:account-id:dbuser:dbi-resource-id/db-user-name In this format, the following are so: • region is the AWS Region for the Amazon RDS DB instance. In the example policy, the AWS Region is us-east-2. • account-id is the AWS account number for the DB instance. In the example policy, the account number is 1234567890. • dbi-resource-id is the identifier for the DB instance. This identifier is unique to an AWS Region and never changes. In the example policy, the identifier is db-ABCDEFGHIJKL01234. To find a DB instance resource ID in the AWS Management Console for Amazon RDS, choose the DB instance you want, and then choose Instance Actions, See Details. The Resource ID is shown in the Configuration Details section. Alternatively, you can use the AWS CLI command to list the identifiers and resource IDs for all of your DB instances in the current AWS Region, as shown following. aws rds describe-db-instances \ --query "DBInstances[*].[DBInstanceIdentifier,DbiResourceId]" • db-user-name is the name of the database account to associate with IAM authentication. In the example policy, the database account is db_user. You can construct other ARNs to support various access patterns. The following policy allows access to two different database accounts in a DB instance . API Version 2014-10-31 364 Amazon Relational Database Service User Guide IAM Database Authentication for MySQL and PostgreSQL { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "rds-db:connect" ], "Resource": [ "arn:aws:rds-db:us-west-2:123456789012:dbuser:db-12ABC34DEFG5HIJ6KLMNOP78QR/ jane_doe", "arn:aws:rds-db:us-west-2:123456789012:dbuser:db-12ABC34DEFG5HIJ6KLMNOP78QR/ mary_roe" ] } ] } The following policy uses the "*" character to match all DB instances for a particular AWS account and AWS Region. { } "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "rds-db:connect" ], "Resource": [ "arn:aws:rds-db:us-east-2:1234567890:dbuser:*/db_user" ] } ] The following policy matches all of the DB instances for a particular AWS account and AWS Region. However, the policy only grants access to DB instances that have a jane_doe database account. { } "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "rds-db:connect" ], "Resource": [ "arn:aws:rds-db:us-west-2:123456789012:dbuser:*/jane_doe" ] } ] The IAM user or role has access to only those databases that the database user does. For example, suppose that your DB instance has a database named dev, and another database named test. If the API Version 2014-10-31 365 Amazon Relational Database Service User Guide IAM Database Authentication for MySQL and PostgreSQL database user jane_doe has access only to dev, any IAM users or roles that access that DB instance with the jane_doe user also have access only to dev. This access restriction is also true for other database objects, such as tables, views, and so on. Attaching an IAM Policy to an IAM User or Role After you create an IAM policy to allow database authentication, you need to attach the policy to an IAM user or role. For a tutorial on this topic, see Create and Attach Your First Customer Managed Policy in the IAM User Guide. As you work through the tutorial, you can use one of the policy examples shown in this section as a starting point and tailor it to your needs. At the end of the tutorial, you have an IAM user with an attached policy that can make use of the rds-db:connect action. Note You can map multiple IAM users or roles to the same database user account. For example, suppose that your IAM policy specified the following resource ARN. arn:aws:rds-db:us-west-2:123456789012:dbuser:db-12ABC34DEFG5HIJ6KLMNOP78QR/jane_doe If you attach the policy to IAM users Jane, Bob, and Diego, then each of those users can connect to the specified DB instance using the jane_doe database account. Creating a Database Account Using IAM Authentication With IAM database authentication, you don't need to assign database passwords to the user accounts you create. If you remove an IAM user that is mapped to a database account, you should also remove the database account with the DROP USER statement. Using IAM Authentication with PostgreSQL To use IAM authentication with PostgreSQL, connect to the DB instance, create database users, and then grant them the rds_iam role as shown in the following example. CREATE USER db_userx WITH LOGIN; GRANT rds_iam TO db_userx; Using IAM Authentication with MySQL With MySQL, authentication is handled by AWSAuthenticationPlugin—an AWS-provided plugin that works seamlessly with IAM to authenticate your IAM users. Connect to the DB instance and issue the CREATE USER statement, as shown in the following example. CREATE USER jane_doe IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS'; The IDENTIFIED WITH clause allows MySQL to use the AWSAuthenticationPlugin to authenticate the database account (jane_doe). The AS 'RDS' clause refers to the authentication method, and the specified database account must have the same name as the IAM user or role. In this example, both the database account and the IAM user or role must be named jane_doe. Note If you see the following message, it means that the AWS-provided plugin is not available for the current DB instance. API Version 2014-10-31 366 Amazon Relational Database Service User Guide IAM Database Authentication for MySQL and PostgreSQL ERROR 1524 (HY000): Plugin 'AWSAuthenticationPlugin' is not loaded To troubleshoot this error, verify that you are using a supported configuration and that you have enabled IAM database authentication on your DB instance. For more information, see Availability for IAM Database Authentication (p. 361) and Enabling and Disabling IAM Database Authentication (p. 362). After you create an account using AWSAuthenticationPlugin, you manage it in the same way as other database accounts. For example, you can modify account privileges with GRANT and REVOKE statements, or modify various account attributes with the ALTER USER statement. Connecting to Your DB Instance Using IAM Authentication With IAM database authentication, you use an authentication token when you connect to your DB instance. An authentication token is a string of characters that you use instead of a password. After you generate an authentication token, it's valid for 15 minutes before it expires. If you try to connect using an expired token, the connection request is denied. Every authentication token must be accompanied by a valid signature, using AWS signature version 4. (For more information, see Signature Version 4 Signing Process in the AWS General Reference.) The AWS CLI and the AWS SDK for Java can automatically sign each token you create. You can use an authentication token when you connect to Amazon RDS from another AWS service, such as AWS Lambda. By using a token, you can avoid placing a password in your code. Alternatively, you can use the AWS SDK for Java to manually create and manually sign an authentication token. After you have a signed IAM authentication token, you can connect to an Amazon RDS DB instance. Following, you can find out how to do this using either a command line tool or the AWS SDK for Java. For more information, see Use IAM authentication to connect with SQL Workbench/J to Amazon Aurora MySQL or Amazon RDS for MySQL. Topics • Connecting to Your DB Instance from the Command Line: AWS CLI and mysql Client (p. 367) • Connecting to Your DB Instance from the Command Line: AWS CLI and psql Client (p. 369) • Connecting to Your DB Instance Using the AWS SDK for Java (p. 370) Connecting to Your DB Instance from the Command Line: AWS CLI and mysql Client You can connect from the command line to an Amazon RDS DB instance with the AWS CLI and mysql command line tool as described following. Topics • Generating an IAM Authentication Token (p. 367) • Connecting to a DB Instance (p. 368) Generating an IAM Authentication Token The following example shows how to get a signed authentication token using the AWS CLI. aws rds generate-db-auth-token \ --hostname rdsmysql.cdgmuqiadpid.us-west-2.rds.amazonaws.com \ --port 3306 \ --region us-west-2 \ API Version 2014-10-31 367 Amazon Relational Database Service User Guide IAM Database Authentication for MySQL and PostgreSQL --username jane_doe In the example, the parameters are as follows: • --hostname – The host name of the DB instance that you want to access. • --port – The port number used for connecting to your DB instance. • --region – The AWS Region where the DB instance is running. • --username – The database account that you want to access. The first several characters of the token look like the following. rdsmysql.cdgmuqiadpid.us-west-2.rds.amazonaws.com:3306/?Action=connect&DBUser=jane_doe&XAmz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900... Connecting to a DB Instance The general format for connecting is shown following. mysql --host=hostName --port=portNumber --ssl-ca=[full path]rds-combined-ca-bundle.pem -enable-cleartext-plugin --user=userName --password=authToken The parameters are as follows: • --host – The host name of the DB instance that you want to access. • --port – The port number used for connecting to your DB instance. • --ssl-ca – The SSL certificate file that contains the public key. For more information, see Using SSL to Encrypt a Connection to a DB Instance (p. 380). • --enable-cleartext-plugin – A value that specifies that AWSAuthenticationPlugin must be used for this connection. • --user – The database account that you want to access. • --password – A signed IAM authentication token. The authentication token consists of several hundred characters. It can be unwieldy on the command line. One way to work around this is to save the token to an environment variable, and then use that variable when you connect. The following example shows one way to perform this workaround. RDSHOST="rdsmysql.cdgmuqiadpid.us-west-2.rds.amazonaws.com" TOKEN="$(aws rds generate-db-auth-token --hostname $RDSHOST --port 3306 --region us-west-2 --username jane_doe )" mysql --host=$RDSHOST --port=3306 --ssl-ca=/sample_dir/rds-combined-ca-bundle.pem --enablecleartext-plugin --user=jane_doe --password=$TOKEN When you connect using AWSAuthenticationPlugin, the connection is secured using SSL. To verify this, type the following at the mysql> command prompt. show status like 'Ssl%'; The following lines in the output show more details. API Version 2014-10-31 368 Amazon Relational Database Service User Guide IAM Database Authentication for MySQL and PostgreSQL +---------------+-------------+ | Variable_name | Value +---------------+-------------+ | ... | ... | Ssl_cipher | AES256-SHA | ... | Ssl_version | | | ... | TLSv1.1 | ... | ... +-----------------------------+ | Connecting to Your DB Instance from the Command Line: AWS CLI and psql Client You can connect from the command line to an Amazon RDS for PostgreSQL DB instance with the AWS CLI and psql command line tool as described following. Topics • Generating an IAM Authentication Token (p. 369) • Connecting to an Amazon RDS PostgreSQL Instance (p. 369) Generating an IAM Authentication Token The authentication token consists of several hundred characters so it can be unwieldy on the command line. One way to work around this is to save the token to an environment variable, and then use that variable when you connect. The following example shows how to use the AWS CLI to get a signed authentication token using the generated-db-auth-token command, and store it in a PGPASSWORD environment variable. export RDSHOST="rdspostgres.cdgmuqiadpid.us-west-2.rds.amazonaws.com" export PGPASSWORD="$(aws rds generate-db-auth-token --hostname $RDSHOST --port 5432 -region us-west-2 --username jane_doe )" In the example, the parameters to the generate-db-auth-token command are as follows: • --hostname – The host name of the DB instance that you want to access. • --port – The port number used for connecting to your DB instance. • --region – The AWS Region where the DB instance is running. • --username – The database account that you want to access. The first several characters of the generated token look like the following. rdspostgres.cdgmuqiadpid.us-west-2.rds.amazonaws.com:5432/? Action=connect&DBUser=jane_doe&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900... Connecting to an Amazon RDS PostgreSQL Instance The general format for using psql to connect is shown following. API Version 2014-10-31 369 Amazon Relational Database Service User Guide IAM Database Authentication for MySQL and PostgreSQL psql "host=hostName port=portNumber sslmode=verify-full sslrootcert=certificateFile dbname=DBName user=userName" The parameters are as follows: • host – The host name of the DB instance that you want to access. • port – The port number used for connecting to your DB instance. • sslmode – The SSL mode to use. When you use sslmode=verify-full, the SSL connection verifies the DB instance endpoint against the endpoint in the SSL certificate. • sslrootcert – The SSL certificate file that contains the public key. For more information, see Using SSL with a PostgreSQL DB Instance. • dbname – The database that you want to access. • user – The database account that you want to access. The following example shows using the command to connect. The example uses the environment variables that were set when the token was generated in the previous section. psql "host=$RDSHOST port=5432 sslmode=verify-full sslrootcert=/sample_dir/rds-combined-cabundle.pem dbname=DBName user=jane_doe" Connecting to Your DB Instance Using the AWS SDK for Java You can connect from the command line to an Amazon RDS DB instance with the AWS SDK for Java as described following. Topics • Generating an IAM Authentication Token (p. 370) • Manually Constructing an IAM Authentication Token (p. 371) • Connecting to a DB Instance (p. 374) Generating an IAM Authentication Token If you are writing programs using the AWS SDK for Java, you can get a signed authentication token using the RdsIamAuthTokenGenerator class. Using this class requires that you provide AWS credentials. To do this, you create an instance of the DefaultAWSCredentialsProviderChain class. DefaultAWSCredentialsProviderChain uses the first AWS access key and secret key that it finds in the default credential provider chain. For more information about AWS access keys, see Managing Access Keys for IAM Users. After you create an instance of RdsIamAuthTokenGenerator, you can call the getAuthToken method to obtain a signed token. Provide the AWS Region, host name, port number, and user name. The following code example illustrates how to do this. package com.amazonaws.codesamples; import com.amazonaws.auth.DefaultAWSCredentialsProviderChain; import com.amazonaws.services.rds.auth.GetIamAuthTokenRequest; import com.amazonaws.services.rds.auth.RdsIamAuthTokenGenerator; public class GenerateRDSAuthToken { public static void main(String[] args) { API Version 2014-10-31 370 Amazon Relational Database Service User Guide IAM Database Authentication for MySQL and PostgreSQL String String String String region = "us-west-2"; hostname = "rdsmysql.cdgmuqiadpid.us-west-2.rds.amazonaws.com"; port = "3306"; username = "jane_doe"; System.out.println(generateAuthToken(region, hostname, port, username)); } static String generateAuthToken(String region, String hostName, String port, String username) { RdsIamAuthTokenGenerator generator = RdsIamAuthTokenGenerator.builder() .credentials(new DefaultAWSCredentialsProviderChain()) .region(region) .build(); String authToken = generator.getAuthToken( GetIamAuthTokenRequest.builder() .hostname(hostName) .port(Integer.parseInt(port)) .userName(username) .build()); return authToken; } } Manually Constructing an IAM Authentication Token In Java, the easiest way to generate an authentication token is to use RdsIamAuthTokenGenerator. This class creates an authentication token for you, and then signs it using AWS signature version 4. For more information, see Signature Version 4 Signing Process in the AWS General Reference. However, you can also construct and sign an authentication token manually, as shown in the following code example. package com.amazonaws.codesamples; import import import import import com.amazonaws.SdkClientException; com.amazonaws.auth.DefaultAWSCredentialsProviderChain; com.amazonaws.auth.SigningAlgorithm; com.amazonaws.util.BinaryUtils; org.apache.commons.lang3.StringUtils; import import import import import import import import javax.crypto.Mac; javax.crypto.spec.SecretKeySpec; java.nio.charset.Charset; java.security.MessageDigest; java.text.SimpleDateFormat; java.util.Date; java.util.SortedMap; java.util.TreeMap; import static com.amazonaws.auth.internal.SignerConstants.AWS4_TERMINATOR; import static com.amazonaws.util.StringUtils.UTF8; public class CreateRDSAuthTokenManually { public static String httpMethod = "GET"; public static String action = "connect"; public static String canonicalURIParameter = "/"; public static SortedMap canonicalQueryParameters = new TreeMap(); public static String payload = StringUtils.EMPTY; public static String signedHeader = "host"; API Version 2014-10-31 371 Amazon Relational Database Service User Guide IAM Database Authentication for MySQL and PostgreSQL public static String algorithm = "AWS4-HMAC-SHA256"; public static String serviceName = "rds-db"; public static String requestWithoutSignature; public static void main(String[] args) throws Exception { String String String String region = "us-west-2"; instanceName = "rdsmysql.cdgmuqiadpid.us-west-2.rds.amazonaws.com"; port = "3306"; username = "jane_doe"; Date now = new Date(); String date = new SimpleDateFormat("yyyyMMdd").format(now); String dateTimeStamp = new SimpleDateFormat("yyyyMMdd'T'HHmmssZ").format(now); DefaultAWSCredentialsProviderChain creds = new DefaultAWSCredentialsProviderChain(); String awsAccessKey = creds.getCredentials().getAWSAccessKeyId(); String awsSecretKey = creds.getCredentials().getAWSSecretKey(); String expiryMinutes = "900"; System.out.println("Step 1: Create a canonical request:"); String canonicalString = createCanonicalString(username, awsAccessKey, date, dateTimeStamp, region, expiryMinutes, instanceName, port); System.out.println(canonicalString); System.out.println(); System.out.println("Step 2: Create a string to sign:"); String stringToSign = createStringToSign(dateTimeStamp, canonicalString, awsAccessKey, date, region); System.out.println(stringToSign); System.out.println(); System.out.println("Step 3: Calculate the signature:"); String signature = BinaryUtils.toHex(calculateSignature(stringToSign, newSigningKey(awsSecretKey, date, region, serviceName))); System.out.println(signature); System.out.println(); System.out.println("Step 4: Add the signing info to the request"); System.out.println(appendSignature(signature)); System.out.println(); } //Step 1: Create a canonical request date should be in format YYYYMMDD and dateTime should be in format YYYYMMDDTHHMMSSZ public static String createCanonicalString(String user, String accessKey, String date, String dateTime, String region, String expiryPeriod, String hostName, String port) throws Exception { canonicalQueryParameters.put("Action", action); canonicalQueryParameters.put("DBUser", user); canonicalQueryParameters.put("X-Amz-Algorithm", "AWS4-HMAC-SHA256"); canonicalQueryParameters.put("X-Amz-Credential", accessKey + "%2F" + date + "%2F" + region + "%2F" + serviceName + "%2Faws4_request"); canonicalQueryParameters.put("X-Amz-Date", dateTime); canonicalQueryParameters.put("X-Amz-Expires", expiryPeriod); canonicalQueryParameters.put("X-Amz-SignedHeaders", signedHeader); String canonicalQueryString = ""; while(!canonicalQueryParameters.isEmpty()) { String currentQueryParameter = canonicalQueryParameters.firstKey(); String currentQueryParameterValue = canonicalQueryParameters.remove(currentQueryParameter); canonicalQueryString = canonicalQueryString + currentQueryParameter + "=" + currentQueryParameterValue; if (!currentQueryParameter.equals("X-Amz-SignedHeaders")) { canonicalQueryString += "&"; API Version 2014-10-31 372 Amazon Relational Database Service User Guide IAM Database Authentication for MySQL and PostgreSQL } } String canonicalHeaders = "host:" + hostName + ":" + port + '\n'; requestWithoutSignature = hostName + ":" + port + "/?" + canonicalQueryString; String hashedPayload = BinaryUtils.toHex(hash(payload)); return httpMethod + '\n' + canonicalURIParameter + '\n' + canonicalQueryString + '\n' + canonicalHeaders + '\n' + signedHeader + '\n' + hashedPayload; } //Step 2: Create a string to sign using sig v4 public static String createStringToSign(String dateTime, String canonicalRequest, String accessKey, String date, String region) throws Exception { String credentialScope = date + "/" + region + "/" + serviceName + "/aws4_request"; return algorithm + '\n' + dateTime + '\n' + credentialScope + '\n' + BinaryUtils.toHex(hash(canonicalRequest)); } //Step 3: Calculate signature /** * Step 3 of the AWS Signature version 4 calculation. It involves deriving * the signing key and computing the signature. Refer to * http://docs.aws.amazon * .com/general/latest/gr/sigv4-calculate-signature.html */ public static byte[] calculateSignature(String stringToSign, byte[] signingKey) { return sign(stringToSign.getBytes(Charset.forName("UTF-8")), signingKey, SigningAlgorithm.HmacSHA256); } public static byte[] sign(byte[] data, byte[] key, SigningAlgorithm algorithm) throws SdkClientException { try { Mac mac = algorithm.getMac(); mac.init(new SecretKeySpec(key, algorithm.toString())); return mac.doFinal(data); } catch (Exception e) { throw new SdkClientException( "Unable to calculate a request signature: " + e.getMessage(), e); } } { public static byte[] newSigningKey(String secretKey, String dateStamp, String regionName, String serviceName) byte[] byte[] byte[] byte[] } kSecret = ("AWS4" + secretKey).getBytes(Charset.forName("UTF-8")); kDate = sign(dateStamp, kSecret, SigningAlgorithm.HmacSHA256); kRegion = sign(regionName, kDate, SigningAlgorithm.HmacSHA256); kService = sign(serviceName, kRegion, SigningAlgorithm.HmacSHA256); return sign(AWS4_TERMINATOR, kService, SigningAlgorithm.HmacSHA256); public static byte[] sign(String stringData, byte[] key, SigningAlgorithm algorithm) throws SdkClientException { try { byte[] data = stringData.getBytes(UTF8); return sign(data, key, algorithm); } catch (Exception e) { throw new SdkClientException( "Unable to calculate a request signature: " + e.getMessage(), e); API Version 2014-10-31 373 Amazon Relational Database Service User Guide IAM Database Authentication for MySQL and PostgreSQL } } //Step 4: append the signature public static String appendSignature(String signature) { return requestWithoutSignature + "&X-Amz-Signature=" + signature; } } public static byte[] hash(String s) throws Exception { try { MessageDigest md = MessageDigest.getInstance("SHA-256"); md.update(s.getBytes(UTF8)); return md.digest(); } catch (Exception e) { throw new SdkClientException( "Unable to compute hash while signing request: " + e.getMessage(), e); } } Connecting to a DB Instance The following code example shows how to generate an authentication token, and then use it to connect to an instance running MySQL. To run this code example, you need the AWS SDK for Java, found on the AWS site. In addition, you need the following: • MySQL Connector/J. This code example was tested with mysql-connector-java-5.1.33bin.jar. • An intermediate certificate for Amazon RDS that is specific to an AWS Region. (For more information, see Using SSL to Encrypt a Connection to a DB Instance (p. 380).) At runtime, the class loader looks for the certificate in the same directory as this Java code example, so that the class loader can find it. • Modify the values of the following variables as needed: • RDS_INSTANCE_HOSTNAME – The host name of the DB instance that you want to access. • RDS_INSTANCE_PORT – The port number used for connecting to your PostgreSQL DB instance. • REGION_NAME – The AWS Region where the DB instance is running. • DB_USER – The database account that you want to access. • SSL_CERTIFICATE – An SSL certificate for Amazon RDS that is specific to an AWS Region. To download a certificate for your AWS Region, see Intermediate Certificates (p. 381). Place the SSL certificate in the same directory as this Java program file, so that the class loader can find the certificate at runtime. This code example obtains AWS credentials from the default credential provider chain. package com.amazonaws.samples; import import import import import com.amazonaws.services.rds.auth.RdsIamAuthTokenGenerator; com.amazonaws.services.rds.auth.GetIamAuthTokenRequest; com.amazonaws.auth.BasicAWSCredentials; com.amazonaws.auth.DefaultAWSCredentialsProviderChain; com.amazonaws.auth.AWSStaticCredentialsProvider; import import import import import java.io.File; java.io.FileOutputStream; java.io.InputStream; java.security.KeyStore; java.security.cert.CertificateFactory; API Version 2014-10-31 374 Amazon Relational Database Service User Guide IAM Database Authentication for MySQL and PostgreSQL import java.security.cert.X509Certificate; import import import import import java.sql.Connection; java.sql.DriverManager; java.sql.ResultSet; java.sql.Statement; java.util.Properties; import java.net.URL; public class IAMDatabaseAuthenticationTester { //AWS Credentials of the IAM user with policy enabling IAM Database Authenticated access to the db by the db user. private static final DefaultAWSCredentialsProviderChain creds = new DefaultAWSCredentialsProviderChain(); private static final String AWS_ACCESS_KEY = creds.getCredentials().getAWSAccessKeyId(); private static final String AWS_SECRET_KEY = creds.getCredentials().getAWSSecretKey(); //Configuration parameters for the generation of the IAM Database Authentication token private static final String RDS_INSTANCE_HOSTNAME = "rdsmysql.cdgmuqiadpid.uswest-2.rds.amazonaws.com"; private static final int RDS_INSTANCE_PORT = 3306; private static final String REGION_NAME = "us-west-2"; private static final String DB_USER = "jane_doe"; private static final String JDBC_URL = "jdbc:mysql://" + RDS_INSTANCE_HOSTNAME + ":" + RDS_INSTANCE_PORT; private static final String SSL_CERTIFICATE = "rds-ca-2015-us-west-2.pem"; private private private private private static static static static static final final final final final String String String String String KEY_STORE_TYPE = "JKS"; KEY_STORE_PROVIDER = "SUN"; KEY_STORE_FILE_PREFIX = "sys-connect-via-ssl-test-cacerts"; KEY_STORE_FILE_SUFFIX = ".jks"; DEFAULT_KEY_STORE_PASSWORD = "changeit"; public static void main(String[] args) throws Exception { //get the connection Connection connection = getDBConnectionUsingIam(); //verify the connection is successful Statement stmt= connection.createStatement(); ResultSet rs=stmt.executeQuery("SELECT 'Success!' FROM DUAL;"); while (rs.next()) { String id = rs.getString(1); System.out.println(id); //Should print "Success!" } //close the connection stmt.close(); connection.close(); clearSslProperties(); } /** * This method returns a connection to the db instance authenticated using IAM Database Authentication * @return * @throws Exception */ private static Connection getDBConnectionUsingIam() throws Exception { setSslProperties(); return DriverManager.getConnection(JDBC_URL, setMySqlConnectionProperties()); } API Version 2014-10-31 375 Amazon Relational Database Service User Guide IAM Database Authentication for MySQL and PostgreSQL /** * This method sets the mysql connection properties which includes the IAM Database Authentication token * as the password. It also specifies that SSL verification is required. * @return */ private static Properties setMySqlConnectionProperties() { Properties mysqlConnectionProperties = new Properties(); mysqlConnectionProperties.setProperty("verifyServerCertificate","true"); mysqlConnectionProperties.setProperty("useSSL", "true"); mysqlConnectionProperties.setProperty("user",DB_USER); mysqlConnectionProperties.setProperty("password",generateAuthToken()); return mysqlConnectionProperties; } /** * This method generates the IAM Auth Token. * An example IAM Auth Token would look like follows: * btusi123.cmz7kenwo2ye.rds.cn-north-1.amazonaws.com.cn:3306/? Action=connect&DBUser=iamtestuser&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-AmzDate=20171003T010726Z&X-Amz-SignedHeaders=host&X-Amz-Expires=899&X-AmzCredential=AKIAPFXHGVDI5RNFO4AQ%2F20171003%2Fcn-north-1%2Frds-db%2Faws4_request&X-AmzSignature=f9f45ef96c1f770cdad11a53e33ffa4c3730bc03fdee820cfdf1322eed15483b * @return */ private static String generateAuthToken() { BasicAWSCredentials awsCredentials = new BasicAWSCredentials(AWS_ACCESS_KEY, AWS_SECRET_KEY); RdsIamAuthTokenGenerator generator = RdsIamAuthTokenGenerator.builder() .credentials(new AWSStaticCredentialsProvider(awsCredentials)).region(REGION_NAME).build(); return generator.getAuthToken(GetIamAuthTokenRequest.builder() .hostname(RDS_INSTANCE_HOSTNAME).port(RDS_INSTANCE_PORT).userName(DB_USER).build()); } /** * This method sets the SSL properties which specify the key store file, its type and password: * @throws Exception */ private static void setSslProperties() throws Exception { System.setProperty("javax.net.ssl.trustStore", createKeyStoreFile()); System.setProperty("javax.net.ssl.trustStoreType", KEY_STORE_TYPE); System.setProperty("javax.net.ssl.trustStorePassword", DEFAULT_KEY_STORE_PASSWORD); } /** * This method returns the path of the Key Store File needed for the SSL verification during the IAM Database Authentication to * the db instance. * @return * @throws Exception */ private static String createKeyStoreFile() throws Exception { return createKeyStoreFile(createCertificate()).getPath(); } /** * This method generates the SSL certificate * @return * @throws Exception */ private static X509Certificate createCertificate() throws Exception { API Version 2014-10-31 376 Amazon Relational Database Service User Guide Encrypting Amazon RDS Resources } CertificateFactory certFactory = CertificateFactory.getInstance("X.509"); URL url = new File(SSL_CERTIFICATE).toURI().toURL(); if (url == null) { throw new Exception(); } try (InputStream certInputStream = url.openStream()) { return (X509Certificate) certFactory.generateCertificate(certInputStream); } /** * This method creates the Key Store File * @param rootX509Certificate - the SSL certificate to be stored in the KeyStore * @return * @throws Exception */ private static File createKeyStoreFile(X509Certificate rootX509Certificate) throws Exception { File keyStoreFile = File.createTempFile(KEY_STORE_FILE_PREFIX, KEY_STORE_FILE_SUFFIX); try (FileOutputStream fos = new FileOutputStream(keyStoreFile.getPath())) { KeyStore ks = KeyStore.getInstance(KEY_STORE_TYPE, KEY_STORE_PROVIDER); ks.load(null); ks.setCertificateEntry("rootCaCertificate", rootX509Certificate); ks.store(fos, DEFAULT_KEY_STORE_PASSWORD.toCharArray()); } return keyStoreFile; } /** * This method clears the SSL properties. * @throws Exception */ private static void clearSslProperties() throws Exception { System.clearProperty("javax.net.ssl.trustStore"); System.clearProperty("javax.net.ssl.trustStoreType"); System.clearProperty("javax.net.ssl.trustStorePassword"); } } Encrypting Amazon RDS Resources You can encrypt your Amazon RDS DB instances and snapshots at rest by enabling the encryption option for your Amazon RDS DB instances. Data that is encrypted at rest includes the underlying storage for a DB instances, its automated backups, Read Replicas, and snapshots. Amazon RDS encrypted DB instances use the industry standard AES-256 encryption algorithm to encrypt your data on the server that hosts your Amazon RDS DB instances. Once your data is encrypted, Amazon RDS handles authentication of access and decryption of your data transparently with a minimal impact on performance. You don't need to modify your database client applications to use encryption. Topics • Overview of Encrypting Amazon RDS Resources (p. 378) • Enabling Amazon RDS Encryption for a DB Instance (p. 378) • Availability of Amazon RDS Encryption (p. 379) • Managing Amazon RDS Encryption Keys (p. 379) • Limitations of Amazon RDS Encrypted DB Instance (p. 380) API Version 2014-10-31 377 Amazon Relational Database Service User Guide Overview of Encrypting Amazon RDS Resources Overview of Encrypting Amazon RDS Resources Amazon RDS encrypted DB instances provide an additional layer of data protection by securing your data from unauthorized access to the underlying storage. You can use Amazon RDS encryption to increase data protection of your applications deployed in the cloud, and to fulfill compliance requirements for data-at-rest encryption. Amazon RDS also supports encrypting an Oracle or SQL Server DB instance with Transparent Data Encryption (TDE). TDE can be used with encryption at rest, although using TDE and encryption at rest simultaneously might slightly affect the performance of your database. You must manage different keys for each encryption method. For more information on TDE, see Oracle Transparent Data Encryption (p. 831), Using AWS CloudHSM Classic to Store Amazon RDS Oracle TDE Keys (p. 881), or Microsoft SQL Server Transparent Data Encryption Support (p. 551). To manage the keys used for encrypting and decrypting your Amazon RDS resources, you use the AWS Key Management Service (AWS KMS). AWS KMS combines secure, highly available hardware and software to provide a key management system scaled for the cloud. Using AWS KMS, you can create encryption keys and define the policies that control how these keys can be used. AWS KMS supports CloudTrail, so you can audit key usage to verify that keys are being used appropriately. Your AWS KMS keys can be used in combination with Amazon RDS and supported AWS services such as Amazon Simple Storage Service (Amazon S3), Amazon Elastic Block Store (Amazon EBS), and Amazon Redshift. For a list of services that support AWS KMS, go to Supported Services in the AWS Key Management Service Developer Guide. For an Amazon RDS encrypted DB instance, all logs, backups, and snapshots are encrypted. A Read Replica of an Amazon RDS encrypted instance is also encrypted using the same key as the master instance when both are in the same region. If the master and Read Replica are in different regions, you encrypt using the encryption key for that region. For encrypted and unencrypted Amazon RDS DB instances with cross-region Read Replicas, data sent between the source and the Read Replicas is encrypted. Enabling Amazon RDS Encryption for a DB Instance To enable encryption for a new DB instance, choose Enable encryption on the Amazon RDS console. For information on creating a DB instance, see one of the following topics: • Creating a DB Instance Running the MySQL Database Engine (p. 587) • Creating a DB Instance Running the Oracle Database Engine (p. 734) • Creating a DB Instance Running the Microsoft SQL Server Database Engine (p. 492) • Creating a DB Instance Running the PostgreSQL Database Engine (p. 964) • Creating a DB Instance Running the MariaDB Database Engine (p. 431) If you use the create-db-instance AWS CLI command to create an encrypted RDS DB instance, set the --storage-encrypted parameter to true. If you use the CreateDBInstance API action, set the StorageEncrypted parameter to true. When you create an encrypted DB instance, you can also supply the AWS KMS key identifier for your encryption key. If you don't specify an AWS KMS key identifier, then Amazon RDS uses your default encryption key for your new DB instance. AWS KMS creates your default encryption key for Amazon RDS for your AWS account. Your AWS account has a different default encryption key for each AWS Region. Once you have created an encrypted DB instance, you cannot change the encryption key for that instance. Therefore, be sure to determine your encryption key requirements before you create your encrypted DB instance. API Version 2014-10-31 378 Amazon Relational Database Service User Guide Availability of Amazon RDS Encryption If you use the AWS CLI create-db-instance command to create an encrypted RDS DB instance, set the --kms-key-id parameter to the Amazon Resource Name (ARN) for the AWS KMS encryption key for the DB instance. If you use the Amazon RDS API CreateDBInstance action, set the KmsKeyId parameter to the ARN for your AWS KMS key for the DB instance. You can use the ARN of a key from another account to encrypt an RDS DB instance. Or you might create a DB instance with the same AWS account that owns the AWS KMS encryption key used to encrypt that new DB instance. In this case, the AWS KMS key ID that you pass can be the AWS KMS key alias instead of the key's ARN. Important If Amazon RDS loses access to the encryption key for a DB instance—for example, when RDS access to a key is revoked—then the encrypted DB instance goes into a terminal state. In this case, you can only restore the DB instance from a backup. We strongly recommend that you always enable backups for encrypted DB instances to guard against the loss of encrypted data in your databases. Availability of Amazon RDS Encryption Amazon RDS encryption is currently available for all database engines and storage types. Amazon RDS encryption is not currently available in the China (Beijing) region. Amazon RDS encryption is available for most DB instance classes. The following table lists DB instance classes that do not support Amazon RDS encryption: Instance Type Instance Class General Purpose (M1) db.m1.small db.m1.medium db.m1.large db.m1.xlarge Memory Optimized (M2) db.m2.xlarge db.m2.2xlarge db.m2.4xlarge Burst Capable (T2) db.t2.micro Note Encryption at rest is not available for DB instances running SQL Server Express Edition. Managing Amazon RDS Encryption Keys You can manage keys used for Amazon RDS encrypted DB instances using the AWS Key Management Service (AWS KMS) in the IAM console. If you want full control over a key, then you must create a customer-managed key. You can't delete, revoke, or rotate default keys provisioned by AWS KMS. You can't share a snapshot that has been encrypted using the default AWS KMS encryption key of the AWS account that shared the snapshot. You can view audit logs of every action taken with a customer-managed key by using AWS CloudTrail. API Version 2014-10-31 379 Amazon Relational Database Service User Guide Limitations of Amazon RDS Encrypted DB Instance Important If you disable the key for an encrypted DB instance, you cannot read from or write to that DB instance. When Amazon RDS encounters a DB instance encrypted by a key that Amazon RDS doesn't have access to, Amazon RDS puts the DB instance into a terminal state. In this state, the DB instance is no longer available and the current state of the database can't be recovered. To restore the DB instance, you must re-enable access to the encryption key for Amazon RDS, and then restore the DB instance from a backup. Limitations of Amazon RDS Encrypted DB Instance The following limitations exist for Amazon RDS encrypted DB instance: • You can only enable encryption for an Amazon RDS DB instance when you create it, not after the DB instance is created. However, because you can encrypt a copy of an unencrypted DB snapshot, you can effectively add encryption to an unencrypted DB instance. That is, you can create a snapshot of your DB instance, and then create an encrypted copy of that snapshot. You can then restore a DB instance from the encrypted snapshot, and thus you have an encrypted copy of your original DB instance. For more information, see Copying a Snapshot (p. 215). • DB instances that are encrypted can't be modified to disable encryption. • You can't have an encrypted Read Replica of an unencrypted DB instance or an unencrypted Read Replica of an encrypted DB instance. • Encrypted Read Replicas must be encrypted with the same key as the source DB instance. • You can't restore an unencrypted backup or snapshot to an encrypted DB instance. • To copy an encrypted snapshot from one region to another, you must specify the KMS key identifier of the destination region. This is because KMS encryption keys are specific to the region that they are created in. The source snapshot remains encrypted throughout the copy process. AWS Key Management Service uses envelope encryption to protect data during the copy process. For more information about envelope encryption, see Envelope Encryption. Using SSL to Encrypt a Connection to a DB Instance You can use SSL from your application to encrypt a connection to a DB instance running MySQL, MariaDB, SQL Server, Oracle, or PostgreSQL. Each DB engine has its own process for implementing SSL. To learn how to implement SSL for your DB instance, use the link following that corresponds to your DB engine: • Using SSL with a MariaDB DB Instance (p. 427) • Using SSL with a Microsoft SQL Server DB Instance (p. 545) • Using SSL with a MySQL DB Instance (p. 582) • Using SSL with an Oracle DB Instance (p. 716) • Using SSL with a PostgreSQL DB Instance (p. 1061) A root certificate that works for all regions can be downloaded at https://s3.amazonaws.com/rdsdownloads/rds-ca-2015-root.pem. It is the trusted root entity and should work in most cases but might API Version 2014-10-31 380 Amazon Relational Database Service User Guide Intermediate Certificates fail if your application doesn't accept certificate chains. If your application doesn't accept certificate chains, download the AWS Region–specific certificate from the list of intermediate certificates found later in this section. You can download a root certificate for the AWS GovCloud regions at https://s3-usgov-west-1.amazonaws.com/rds-downloads/rds-GovCloud-Root-CA-2017.pem. Note All certificates are only available for download using SSL connections. A certificate bundle that contains both the intermediate and root certificates can be downloaded at https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem. A certificate bundle that contains both the intermediate and root certificates for the AWS GovCloud regions can be downloaded at https://s3-us-gov-west-1.amazonaws.com/rds-downloads/rdscombined-ca-us-gov-bundle.pem. If your application is on the Microsoft Windows platform and requires a PKCS7 file, you can download the PKCS7 certificate bundle that contains both the intermediate and root certificates at https:// s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.p7b. Intermediate Certificates You might need to use an intermediate certificate to connect to your region. For example, you must use an intermediate certificate to connect to the AWS GovCloud (US-West) region using SSL. If you need an intermediate certificate for a particular AWS Region, download the certificate from the following list: Asia Pacific (Mumbai) Asia Pacific (Tokyo) Asia Pacific (Seoul) Asia Pacific (Osaka-Local) Asia Pacific (Singapore) Asia Pacific (Sydney) Canada (Central) China (Beijing) China (Ningxia) EU (Frankfurt) EU (Ireland) EU (London) EU (Paris) South America (São Paulo) US East (N. Virginia) US East (Ohio) US West (N. California) API Version 2014-10-31 381 Amazon Relational Database Service User Guide Controlling Access with Amazon RDS Security Groups US West (Oregon) AWS GovCloud (US-East) (CA-2017) AWS GovCloud (US-West) (CA-2017) AWS GovCloud (US-West) (CA-2012) Controlling Access with Amazon RDS Security Groups Security groups control the access that traffic has in and out of a DB instance. Three types of security groups are used with Amazon RDS: DB security groups, VPC security groups, and Amazon EC2 security groups. In simple terms, these work as follows: • A DB security group controls access to EC2-Classic DB instances that are not in a VPC. • A VPC security group controls access to DB instances and EC2 instances inside a VPC. • An EC2 security group controls access to an EC2 instance. By default, network access is turned off to a DB instance. You can specify rules in a security group that allows access from an IP address range, port, or EC2 security group. Once ingress rules are configured, the same rules apply to all DB instances that are associated with that security group. You can specify up to 20 rules in a security group. DB Security Groups DB security groups are used with DB instances that are not in a VPC and on the EC2-Classic platform. Each DB security group rule enables a specific source to access a DB instance that is associated with that DB security group. The source can be a range of addresses (for example, 203.0.113.0/24), or an EC2 security group. When you specify an EC2 security group as the source, you allow incoming traffic from all EC2 instances that use that EC2 security group. DB security group rules apply to inbound traffic only; outbound traffic is not currently permitted for DB instances. You don't need to specify a destination port number when you create DB security group rules. The port number defined for the DB instance is used as the destination port number for all rules defined for the DB security group. DB security groups can be created using the Amazon RDS API actions or the Amazon RDS page of the AWS Management Console. For more information about working with DB security groups, see Working with DB Security Groups (EC2Classic Platform) (p. 387). VPC Security Groups Each VPC security group rule enables a specific source to access a DB instance in a VPC that is associated with that VPC security group. The source can be a range of addresses (for example, 203.0.113.0/24), or another VPC security group. By specifying a VPC security group as the source, you allow incoming traffic from all instances (typically application servers) that use the source VPC security group. VPC security groups can have rules that govern both inbound and outbound traffic, though the outbound traffic rules typically do not apply to DB instances. Outbound traffic rules only apply if the DB instance acts as a client. For example, outbound traffic rules apply to an Oracle DB instance with outbound database links. You must use the Amazon EC2 API or the Security Group option on the VPC Console to create VPC security groups. API Version 2014-10-31 382 Amazon Relational Database Service User Guide DB Security Groups vs. VPC Security Groups When you create rules for your VPC security group that allow access to the instances in your VPC, you must specify a port for each range of addresses that the rule allows access for. For example, if you want to enable SSH access to instances in the VPC, then you create a rule allowing access to TCP port 22 for the specified range of addresses. You can configure multiple VPC security groups that allow access to different ports for different instances in your VPC. For example, you can create a VPC security group that allows access to TCP port 80 for web servers in your VPC. You can then create another VPC security group that allows access to TCP port 3306 for RDS MySQL DB instances in your VPC. For more information on VPC security groups, see Security Groups in the Amazon Virtual Private Cloud User Guide. DB Security Groups vs. VPC Security Groups The following table shows the key differences between DB security groups and VPC security groups. DB Security Group VPC Security Group Controls access to DB instances outside a VPC. Controls access to DB instances in VPC. Uses Amazon RDS API actions or the Amazon RDS page of the AWS Management Console to create and manage group and rules. Uses Amazon EC2 API actions or the Amazon VPC page of the AWS Management Console to create and manage group and rules. When you add a rule to a group, you don't need to specify port number or protocol. When you add a rule to a group, specify the protocol as TCP. In addition, specify the same port number that you used to create the DB instances (or options) that you plan to add as members to the group. Groups allow access from EC2 security groups in your AWS account or other accounts. Groups allow access from other VPC security groups in your VPC only. Security Group Scenario A common use of an RDS instance in a VPC is to share data with an application server running in an Amazon EC2 instance in the same VPC, which is accessed by a client application outside the VPC. For this scenario, you use the RDS and VPC pages on the AWS Management Console or the RDS and EC2 API actions to create the necessary instances and security groups: 1. Create a VPC security group (for example, sg-appsrv1) and define inbound rules that use the IP addresses of the client application as the source. This security group allows your client application to connect to EC2 instances in a VPC that uses this security group. 2. Create an EC2 instance for the application and add the EC2 instance to the VPC security group (sgappsrv1) that you created in the previous step. The EC2 instance in the VPC shares the VPC security group with the DB instance. 3. Create a second VPC security group (for example, sg-dbsrv1) and create a new rule by specifying the VPC security group that you created in step 1 (sg-appsrv1) as the source. 4. Create a new DB instance and add the DB instance to the VPC security group (sg-dbsrv1) that you created in the previous step. When you create the instance, use the same port number as the one specified for the VPC security group (sg-dbsrv1) rule that you created in step 3. The following diagram shows this scenario. API Version 2014-10-31 383 Amazon Relational Database Service User Guide Creating a VPC Security Group For more information about using a VPC, see Amazon Virtual Private Cloud (VPCs) and Amazon RDS (p. 400). Creating a VPC Security Group You can create a VPC security group for a DB instance by using the VPC console. For information about creating a security group, see Provide Access to Your DB Instance in Your VPC by Creating a Security Group (p. 8) and Security Groups in the Amazon Virtual Private Cloud User Guide. Associating a Security Group with a DB Instance You can associate a security group with a DB instance by using Modify on the RDS console, the ModifyDBInstance Amazon RDS API, or the modify-db-instance AWS CLI command. For information about modifying a DB instance, see Modifying an Amazon RDS DB Instance and Using the Apply Immediately Parameter (p. 113). For security group considerations when you restore a DB instance from a DB snapshot, see Security Group Considerations (p. 212). Deleting DB VPC Security Groups DB VPC security groups are an RDS mechanism to synchronize security information with a VPC security group. However, this synchronization is no longer required, because RDS has been updated to use VPC security group information directly. Note DB VPC security groups are deprecated, and they are different from DB security groups, VPC security groups, and EC2 security groups. We strongly recommend that you delete any DB VPC security groups that you currently use. If you don't delete your DB VPC security groups, you might encounter unintended behaviors with your RDS DB instances, which can be as severe as losing access to a DB instance. The unintended behaviors are a result of an action such as an update to a DB instance, an option group, or similar. Such updates cause RDS to resynchronize the DB VPC security group with the VPC security group. This resynchronization can result in your security information being overwritten with incorrect and outdated security information. This result can have a severe impact on your access to your RDS DB instances. API Version 2014-10-31 384 Amazon Relational Database Service User Guide Deleting DB VPC Security Groups How Can I Determine If I Have a DB VPC Security Group? Because DB VPC security groups have been deprecated, they don't appear in the RDS console. However, you can call the describe-db-security-groups AWS CLI command or the DescribeDBSecurityGroups API action to determine if you have any DB VPC security groups. In this case, you can call the describe-db-security-groups AWS CLI command with JSON specified as the output format. If you do, you can identify DB VPC security groups by the VPC identifier on the second line of the output for the security group as shown in the following example. { } "DBSecurityGroups": [ { "VpcId": "vpc-abcd1234", "DBSecurityGroupDescription": "default:vpc-abcd1234", "IPRanges": [ { "Status": "authorized", "CIDRIP": "xxx.xxx.xxx.xxx/n" }, { "Status": "authorized", "CIDRIP": "xxx.xxx.xxx.xxx/n " } ], "OwnerId": "123456789012", "EC2SecurityGroups": [], "DBSecurityGroupName": "default:vpc-abcd1234" } ] If you run the DescribeDBSecurityGroups API action, then you can identify DB VPC security groups using the response element as shown in the following example. default:vpc-abcd1234 xxx.xxx.xxx.xxx/n authorized xxx.xxx.xxx.xxx/n authorized vpc-abcd1234 123456789012 default:vpc-abcd1234 How Do I Delete a DB VPC Security Group? Because DB VPC security groups don't appear in the RDS console, you must call the delete-db-securitygroup AWS CLI command or the DeleteDBSecurityGroup API action to delete a DB VPC security group. After you delete a DB VPC security group, your DB instances in your VPC continue to be secured by the VPC security group for that VPC. The DB VPC security group that was deleted was merely a copy of the VPC security group information. API Version 2014-10-31 385 Amazon Relational Database Service User Guide Deleting DB VPC Security Groups Review Your AWS CloudFormation Templates Older versions of AWS CloudFormation templates can contain instructions to create a DB VPC security group. Because DB VPC security groups are not yet fully deprecated, they can still be created. Make sure that any AWS CloudFormation templates that you use to provision a DB instance with security settings don't also create a DB VPC security group. Don't use AWS CloudFormation templates that create an RDS DBSecurityGroup with an EC2VpcId as shown in the following example. "DbSecurityByEC2SecurityGroup" : { Type" : "AWS::RDS::DBSecurityGroup", "Properties" : { "GroupDescription" : "Ingress for Amazon EC2 security group", "EC2VpcId" : { "MyVPC" }, "DBSecurityGroupIngress" : [ { "EC2SecurityGroupId" : "sg-b0ff1111", "EC2SecurityGroupOwnerId" : "111122223333" }, { "EC2SecurityGroupId" : "sg-ffd722222", "EC2SecurityGroupOwnerId" : "111122223333" } ] } } Instead, add security information for your RDS DB instances in a VPC using VPC security groups, as shown in the following example. "DBInstance" : { "Type": "AWS::RDS::DBInstance", "Properties": { "DBName" : { "Ref" : "DBName" }, "Engine" : "MySQL", "MultiAZ" : { "Ref": "MultiAZDatabase" }, "MasterUsername" : { "Ref" : "" }, "DBInstanceClass" : { "Ref" : "DBClass" }, "AllocatedStorage" : { "Ref" : "DBAllocatedStorage" }, "MasterUserPassword": { "Ref" : "" }, "VPCSecurityGroups" : [ { "Fn::GetAtt": [ "VPCSecurityGroup", "GroupId" ] } ] } API Version 2014-10-31 386 Amazon Relational Database Service User Guide DB Security Groups on EC2-Classic Working with DB Security Groups (EC2-Classic Platform) By default, network access is turned off to a DB instance. You can specify rules in a security group that allows access from an IP address range, port, or EC2 security group. Once ingress rules are configured, the same rules apply to all DB instances that are associated with that security group. You can specify up to 20 rules in a security group. Amazon RDS supports two different kinds of security groups. The one you use depends on which Amazon RDS platform you are on: • VPC security groups – for the EC2-VPC platform. • DB security groups – for the EC2-Classic platform. You are most likely on the EC2-VPC platform (and must use VPC security groups) if any of the following are true: • If you are a new Amazon RDS customer. • If you have never created a DB instance before. • If you are creating a DB instance in an AWS Region you have not used before. Otherwise, if you are on the EC2-Classic platform, you use DB security groups to manage access to your Amazon RDS DB instances. For more information about the differences between DB security groups and VPC security groups, see Controlling Access with Amazon RDS Security Groups (p. 382). Note To determine which platform you are on, see Determining Whether You Are Using the EC2-VPC or EC2-Classic Platform (p. 400). If you are on the EC2-VPC platform, you must use VPC security groups instead of DB security groups. For more information about using a VPC, see Amazon Virtual Private Cloud (VPCs) and Amazon RDS (p. 400). Topics • Creating a DB Security Group (p. 387) • Listing Available DB Security Groups (p. 389) • Viewing a DB Security Group (p. 389) • Associating a DB Security Group with a DB Instance (p. 390) • Authorizing Network Access to a DB Security Group from an IP Range (p. 391) • Authorizing Network Access to a DB Instance from an Amazon EC2 Instance (p. 392) • Revoking Network Access to a DB Instance from an IP Range (p. 394) Creating a DB Security Group To create a DB security group, you need to provide a name and a description. AWS Management Console To create a DB security group 1. Open the Amazon RDS console at https://console.aws.amazon.com/rds/. API Version 2014-10-31 387 Amazon Relational Database Service User Guide Creating a DB Security Group 2. Choose Security Groups in the navigation pane on the left side of the window. Note If you are on the EC2-VPC platform, the Security Groups option does not appear in the navigation pane. In this case, you must use VPC security groups instead of DB security groups. For more information about using a VPC, see Amazon Virtual Private Cloud (VPCs) and Amazon RDS (p. 400). 3. 4. Choose Create DB Security Group. Type the name and description of the new DB security group in the Name and Description text boxes. The security group name can't contain spaces and can't start with a number. 5. Choose Yes, Create. The DB security group is created. A newly created DB security group doesn't provide access to a DB instance by default. You must specify a range of IP addresses or an Amazon EC2 security group that can have access to the DB instance. To specify IP addresses or an Amazon EC2 security group for a DB security group, see Authorizing Network Access to a DB Security Group from an IP Range (p. 391). CLI To create a DB security group, use the AWS CLI command create-db-security-group. Example For Linux, OS X, or Unix: aws rds create-db-security-group \ --db-security-group-name mydbsecuritygroup \ --db-security-group-description "My new security group" For Windows: aws rds create-db-security-group ^ --db-security-group-name mydbsecuritygroup ^ --db-security-group-description "My new security group" A newly created DB security group doesn't provide access to a DB instance by default. You must specify a range of IP addresses or an Amazon EC2 security group that can have access to the DB instance. To specify IP addresses or an Amazon EC2 security group for a DB security group, see Authorizing Network Access to a DB Security Group from an IP Range (p. 391). API To create a DB security group, call the Amazon RDS function CreateDBSecurityGroup with the following parameters: • DBSecurityGroupName = mydbsecuritygroup • Description = "My new security group" Example https://rds.amazonaws.com/ ?Action=CreateDBSecurityGroup &DBSecurityGroupName=mydbsecuritygroup API Version 2014-10-31 388 Amazon Relational Database Service User Guide Listing Available DB Security Groups &Description=My%20new%20db%20security%20group &Version=2012-01-15 &SignatureVersion=2 &SignatureMethod=HmacSHA256 &Timestamp=2012-01-20T22%3A06%3A23.624Z &AWSAccessKeyId= &Signature= A newly created DB security group doesn't provide access to a DB instance by default. You must specify a range of IP addresses or an Amazon EC2 security group that can have access to the DB instance. To specify IP addresses or an Amazon EC2 security group for a DB security group, see Authorizing Network Access to a DB Security Group from an IP Range (p. 391). Listing Available DB Security Groups You can list which DB security groups have been created for your AWS account. AWS Management Console To list all available DB security groups for an AWS account 1. Open the Amazon RDS console at https://console.aws.amazon.com/rds/. 2. Choose Security Groups in the navigation pane on the left side of the window. The available DB security groups appear in the DB Security Groups list. CLI To list all available DB security groups for an AWS account, Use the AWS CLI command describe-dbsecurity-groups with no parameters. Example aws rds describe-db-security-groups API To list all available DB security groups for an AWS account, call DescribeDBSecurityGroups with no parameters. Example https://rds.amazonaws.com/ ?Action=DescribeDBSecurityGroups &MaxRecords=100 &Version=2009-10-16 &SignatureVersion=2 &SignatureMethod=HmacSHA256 &AWSAccessKeyId= &Signature= Viewing a DB Security Group You can view detailed information about your DB security group to see what IP ranges have been authorized. API Version 2014-10-31 389 Amazon Relational Database Service User Guide Associating with a DB Instance AWS Management Console To view properties of a specific DB security group 1. Open the Amazon RDS console at https://console.aws.amazon.com/rds/. 2. Choose Security Groups in the navigation pane on the left side of the window. 3. Select the details icon for the DB security group you want to view. The detailed information for the DB security group is displayed. CLI To view the properties of a specific DB security group use the AWS CLI describe-db-securitygroups. Specify the DB security group you want to view. Example For Linux, OS X, or Unix: aws rds describe-db-security-groups \ --db-security-group-name mydbsecuritygroup For Windows: aws rds describe-db-security-groups ^ --db-security-group-name mydbsecuritygroup API To view properties of a specific DB security group, call DescribeDBSecurityGroups with the following parameters: • DBSecurityGroupName=mydbsecuritygroup Example https://rds.amazonaws.com/ ?Action=DescribeDBSecurityGroups &DBSecurityGroupName=mydbsecuritygroup &Version=2009-10-16 &SignatureVersion=2 &SignatureMethod=HmacSHA256 &Timestamp=2009-10-16T22%3A23%3A07.107Z &AWSAccessKeyId= &Signature= Associating a DB Security Group with a DB Instance You can associate a DB security group with a DB instance using the RDS console's Modify option, the ModifyDBInstance Amazon RDS API, or the AWS CLI modify-db-instance command. For information about modifying a DB instance, see Modifying an Amazon RDS DB Instance and Using the Apply Immediately Parameter (p. 113). API Version 2014-10-31 390 Amazon Relational Database Service User Guide Authorizing Network Access to a DB Security Group from an IP Range Authorizing Network Access to a DB Security Group from an IP Range By default, network access is turned off to a DB instance. If you want to access a DB instance that is not in a VPC, you must set access rules for a DB security group to allow access from specific EC2 security groups or CIDR IP ranges. You then must associate that DB instance with that DB security group. This process is called ingress. Once ingress is configured for a DB security group, the same ingress rules apply to all DB instances associated with that DB security group. Warning Talk with your network administrator if you are intending to access a DB instance behind a firewall to determine the IP addresses you should use. In following example, you configure a DB security group with an ingress rule for a CIDR IP range. AWS Management Console To configure a DB security group with an ingress rule for a CIDR IP range 1. 2. Open the Amazon RDS console at https://console.aws.amazon.com/rds/. Select Security Groups from the navigation pane on the left side of the console window. 3. Select the details icon for the DB security group you want to authorize. 4. In the details page for your security group, select CIDR/IP from the Connection Type drop-down list, type the CIDR range for the ingress rule you want to add to this DB security group into the CIDR text box, and choose Authorize. Tip 5. The AWS Management Console displays a CIDR IP based on your connection below the CIDR text field. If you are not accessing the DB instance from behind a firewall, you can use this CIDR IP. The status of the ingress rule is authorizing until the new ingress rule has been applied to all DB instances that are associated with the DB security group that you modified. After the ingress rule has been successfully applied, the status changes to authorized. CLI To configure a DB security group with an ingress rule for a CIDR IP range, use the AWS CLI command authorize-db-security-group-ingress. Example For Linux, OS X, or Unix: aws rds authorize-db-security-group-ingress \ --db-security-group-name mydbsecuritygroup \ --cidrip 192.168.1.10/27 For Windows: aws rds authorize-db-security-group-ingress ^ --db-security-group-name mydbsecuritygroup ^ --cidrip 192.168.1.10/27 The command should produce output similar to the following. API Version 2014-10-31 391 Amazon Relational Database Service User Guide Authorizing Network Access to a DB Instance from an Amazon EC2 Instance SECGROUP IP-RANGE mydbsecuritygroup My new DBSecurityGroup 192.168.1.10/27 authorizing API To configure a DB security group with an ingress rule for a CIDR IP range, call the Amazon RDS API AuthorizeDBSecurityGroupIngress with the following parameters: • DBSecurityGroupName = mydbsecuritygroup • CIDRIP = 192.168.1.10/27 Example https://rds.amazonaws.com/ ?Action=AuthorizeDBSecurityGroupIngress &CIDRIP=192.168.1.10%2F27 &DBSecurityGroupName=mydbsecuritygroup &Version=2009-10-16 &Action=AuthorizeDBSecurityGroupIngress &SignatureVersion=2 &SignatureMethod=HmacSHA256 &Timestamp=2009-10-22T17%3A10%3A50.274Z &AWSAccessKeyId= &Signature= Authorizing Network Access to a DB Instance from an Amazon EC2 Instance If you want to access your DB instance from an Amazon EC2 instance, you must first determine if your EC2 instance and DB instance are in a VPC. If you are using a default VPC, you can assign the same EC2 or VPC security group that you used for your EC2 instance when you create or modify the DB instance that the EC2 instance accesses. If your DB instance and EC2 instance are not in a VPC, you must configure the DB instance's security group with an ingress rule that allows traffic from the Amazon EC2 instance. You do this by adding the Amazon EC2 security group for the EC2 instance to the DB security group for the DB instance. In this example, you add an ingress rule to a DB security group for an Amazon EC2 security group. Important • Adding an ingress rule to a DB security group for an Amazon EC2 security group only grants access to your DB instances from Amazon EC2 instances associated with that Amazon EC2 security group. • You can't authorize an Amazon EC2 security group that is in a different AWS Region than your DB instance. You can authorize an IP range, or specify an Amazon EC2 security group in the same AWS Region that refers to IP address in another AWS Region. If you specify an IP range, we recommend that you use the private IP address of your Amazon EC2 instance, which provides a more direct network route from your Amazon EC2 instance to your Amazon RDS DB instance, and doesn't incur network charges for data sent outside of the Amazon network. AWS Management Console To add an EC2 security group to a DB security group 1. Open the Amazon RDS console at https://console.aws.amazon.com/rds/. API Version 2014-10-31 392 Amazon Relational Database Service User Guide Authorizing Network Access to a DB Instance from an Amazon EC2 Instance 2. From the navigation pane, choose Security Groups. 3. Select the details icon for the DB security group you want to grant access. 4. In the details page for your security group, choose EC2 Security Group for Connection Type, and then select the Amazon EC2 security group you want to use. Then choose Authorize. 5. The status of the ingress rule is authorizing until the new ingress rule has been applied to all DB instances that are associated with the DB security group that you modified. After the ingress rule has been successfully applied, the status changes to authorized. CLI To grant access to an Amazon EC2 security group, use the AWS CLI command authorize-dbsecurity-group-ingress. Example For Linux, OS X, or Unix: aws rds authorize-db-security-group-ingress \ --db-security-group-name default \ --ec2-security-group-name myec2group \ --ec2-security-group-owner-id 987654321021 For Windows: aws rds authorize-db-security-group-ingress ^ --db-security-group-name default ^ --ec2-security-group-name myec2group ^ --ec2-security-group-owner-id 987654321021 The command should produce output similar to the following: SECGROUP Name Description SECGROUP default default EC2-SECGROUP myec2group 987654321021 authorizing API To authorize network access to an Amazon EC2 security group, call that Amazon RDS API function, https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/ API_AuthorizeDBSecurityGroupIngress.htmlAuthorizeDBSecurityGroupIngress with the following parameters: • EC2SecurityGroupName = myec2group • EC2SecurityGroupOwnerId = 987654321021 Example https://rds.amazonaws.com/ ?Action=AuthorizeDBSecurityGroupIngress &EC2SecurityGroupOwnerId=987654321021 &EC2SecurityGroupName=myec2group &Version=2009-10-16 API Version 2014-10-31 393 Amazon Relational Database Service User Guide Revoking Network Access to a DB Instance from an IP Range &SignatureVersion=2 &SignatureMethod=HmacSHA256 &Timestamp=2009-10-22T17%3A10%3A50.274Z &AWSAccessKeyId= &Signature= Revoking Network Access to a DB Instance from an IP Range You can easily revoke network access from a CIDR IP range to DB instances belonging to a DB security group by revoking the associated CIDR IP ingress rule. In this example, you revoke an ingress rule for a CIDR IP range on a DB security group. AWS Management Console To revoke an ingress rule for a CIDR IP range on a DB Security Group 1. Open the Amazon RDS console at https://console.aws.amazon.com/rds/. 2. From the navigation pane, choose Security Groups. 3. Select the details icon for the DB security group that has the ingress rule you want to revoke. 4. In the details page for your security group, choose Remove next to the ingress rule you want to revoke. 5. The status of the ingress rule is revoking until the ingress rule has been removed from all DB instances that are associated with the DB security group that you modified. After the ingress rule has been successfully removed, the ingress rule is removed from the DB security group. CLI To revoke an ingress rule for a CIDR IP range on a DB security group, use the AWS CLI command revoke-db-security-group-ingress. Example For Linux, OS X, or Unix: aws rds revoke-db-security-group-ingress \ --db-security-group-name mydbsecuritygroup \ --cidrip 192.168.1.1/27 For Windows: aws rds revoke-db-security-group-ingress ^ --db-security-group-name mydbsecuritygroup ^ --cidrip 192.168.1.1/27 The command should produce output similar to the following. SECGROUP mydbsecuritygroup My new DBSecurityGroup IP-RANGE 192.168.1.1/27 revoking API Version 2014-10-31 394 Amazon Relational Database Service User Guide Master User Account Privileges API To revoke an ingress rule for a CIDR IP range on a DB security group, call the Amazon RDS API action https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/ API_RevokeDBSecurityGroupIngress.htmlRevokeDBSecurityGroupIngress with the following parameters: • DBSecurityGroupName = mydbsecuritygroup • CIDRIP = 192.168.1.10/27 Example https://rds.amazonaws.com/ ?Action=RevokeDBSecurityGroupIngress &DBSecurityGroupName=mydbsecuritygroup &CIDRIP=192.168.1.10%2F27 &Version=2009-10-16 &SignatureVersion=2&SignatureMethod=HmacSHA256 &Timestamp=2009-10-22T22%3A32%3A12.515Z &AWSAccessKeyId= &Signature= Master User Account Privileges When you create a new DB instance, the default master user that you use gets certain privileges for that DB instance. The following table shows the privileges the master user gets for each of the database engines. Note If you accidentally delete the permissions for the master user you can restore them by resetting the password for the account. Database System Privilege Engine Role MySQL and MariaDB — SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, RELOAD, PROCESS, REFERENCES, INDEX, ALTER, SHOW DATABASES, CREATE TEMPORARY TABLES, LOCK TABLES, EXECUTE, REPLICATION CLIENT, CREATE VIEW, SHOW VIEW, CREATE ROUTINE, ALTER ROUTINE, CREATE USER, EVENT, TRIGGER ON *.* WITH GRANT OPTION, REPLICATION SLAVE (only for Amazon RDS MySQL versions 5.6, 5.7 and 8.0, Amazon RDS MariaDB) PostgreSQLCREATE ROLE, CREATE DB, PASSWORD VALID UNTIL INFINITY, CREATE EXTENSION, ALTER EXTENSION, DROP EXTENSION, CREATE TABLESPACE, ALTER < OBJECT> OWNER, CHECKPOINT, PG_CANCEL_BACKEND(), PG_TERMINATE_BACKEND(), SELECT PG_STAT_REPLICATION, EXECUTE PG_STAT_STATEMENTS_RESET(), OWN POSTGRES_FDW_HANDLER(), OWN POSTGRES_FDW_VALIDATOR(), OWN POSTGRES_FDW, EXECUTE PG_BUFFERCACHE_PAGES(), SELECT PG_BUFFERCACHE API Version 2014-10-31 395 RDS_SUPERUSER Amazon Relational Database Service User Guide Master User Account Privileges Database System Privilege Engine Role Oracle ALTER DATABASE LINK, ALTER PUBLIC DATABASE LINK, DROP ANY DIRECTORY, EXEMPT ACCESS POLICY, EXEMPT IDENTITY POLICY, GRANT ANY OBJECT PRIVILEGE, RESTRICTED SESSION, EXEMPT REDACTION POLICY AQ_ADMINISTRATOR_ROLE, AQ_USER_ROLE, CONNECT, CTXAPP, DBA, EXECUTE_CATALOG_ROLE, RECOVERY_CATALOG_OWNER, RESOURCE, SELECT_CATALOG_ROLE Microsoft SQL Server ALTER ANY CONNECTION, ALTER ANY LINKED SERVER, ALTER ANY LOGIN, ALTER SERVER STATE, ALTER TRACE, CONNECT SQL, CREATE ANY DATABASE, VIEW ANY DATABASE, VIEW ANY DEFINITION, VIEW SERVER STATE, ALTER ANY SERVER ROLE, ALTER ANY USER DB_OWNER (Database Level Role) PROCESSADMIN(Server Level Role) SETUPADMIN(Server Level Role) SQLAgentUserRole(Server Level Role) API Version 2014-10-31 396 Amazon Relational Database Service User Guide Service-Linked Roles Using Service-Linked Roles for Amazon RDS Amazon RDS uses AWS Identity and Access Management (IAM) service-linked roles. A service-linked role is a unique type of IAM role that is linked directly to Amazon RDS. Service-linked roles are predefined by Amazon RDS and include all the permissions that the service requires to call other AWS services on your behalf. A service-linked role makes using Amazon RDS easier because you don’t have to manually add the necessary permissions. Amazon RDS defines the permissions of its service-linked roles, and unless defined otherwise, only Amazon RDS can assume its roles. The defined permissions include the trust policy and the permissions policy, and that permissions policy cannot be attached to any other IAM entity. You can delete the roles only after first deleting their related resources. This protects your Amazon RDS resources because you can't inadvertently remove permission to access the resources. For information about other services that support service-linked roles, see AWS Services That Work with IAM and look for the services that have Yes in the Service-Linked Role column. Choose a Yes with a link to view the service-linked role documentation for that service. Service-Linked Role Permissions for Amazon RDS Amazon RDS uses the service-linked role named AWSServiceRoleForRDS – to allow Amazon RDS to call AWS services on behalf of your DB instances. The AWSServiceRoleForRDS service-linked role trusts the following services to assume the role: • rds.amazonaws.com The role permissions policy allows Amazon RDS to complete the following actions on the specified resources: • Actions on ec2: • AssignPrivateIpAddresses • AuthorizeSecurityGroupIngress • CreateNetworkInterface • CreateSecurityGroup • DeleteNetworkInterface • DeleteSecurityGroup • DescribeAvailabilityZones • DescribeInternetGateways • DescribeSecurityGroups • DescribeSubnets • DescribeVpcAttribute • DescribeVpcs • ModifyNetworkInterfaceAttribute • RevokeSecurityGroupIngress • UnassignPrivateIpAddresses • Actions on sns: • ListTopic • Publish API Version 2014-10-31 397 Amazon Relational Database Service User Guide Creating a Service-Linked Role for Amazon RDS • Actions on cloudwatch: • PutMetricData • GetMetricData • CreateLogStream • PullLogEvents • DescribeLogStreams • CreateLogGroup Note You must configure permissions to allow an IAM entity (such as a user, group, or role) to create, edit, or delete a service-linked role. If you encounter the following error message: Unable to create the resource. Verify that you have permission to create service linked role. Otherwise wait and try again later. Make sure you have the following permissions enabled: { "Action": "iam:CreateServiceLinkedRole", "Effect": "Allow", "Resource": "arn:aws:iam::*:role/aws-service-role/rds.amazonaws.com/ AWSServiceRoleForRDS", "Condition": { "StringLike": { "iam:AWSServiceName":"rds.amazonaws.com" } } } For more information, see Service-Linked Role Permissions in the IAM User Guide. Creating a Service-Linked Role for Amazon RDS You don't need to manually create a service-linked role. When you create a DB instance, Amazon RDS creates the service-linked role for you. Important If you were using the Amazon RDS service before December 1, 2017, when it began supporting service-linked roles, then Amazon RDS created the AWSServiceRoleForRDS role in your account. To learn more, see A New Role Appeared in My IAM Account. If you delete this service-linked role, and then need to create it again, you can use the same process to recreate the role in your account. When you create a DB instance, Amazon RDS creates the service-linked role for you again. Editing a Service-Linked Role for Amazon RDS Amazon RDS does not allow you to edit the AWSServiceRoleForRDS service-linked role. After you create a service-linked role, you cannot change the name of the role because various entities might reference the role. However, you can edit the description of the role using IAM. For more information, see Editing a Service-Linked Role in the IAM User Guide. Deleting a Service-Linked Role for Amazon RDS If you no longer need to use a feature or service that requires a service-linked role, we recommend that you delete that role. That way you don’t have an unused entity that is not actively monitored or API Version 2014-10-31 398 Amazon Relational Database Service User Guide Deleting a Service-Linked Role for Amazon RDS maintained. However, you must delete all of your DB instances before you can delete the service-linked role. Cleaning Up a Service-Linked Role Before you can use IAM to delete a service-linked role, you must first confirm that the role has no active sessions and remove any resources used by the role. To check whether the service-linked role has an active session in the IAM console 1. Sign in to the AWS Management Console and open the IAM console at https:// console.aws.amazon.com/iam/. 2. In the navigation pane of the IAM console, choose Roles. Then choose the name (not the check box) of the AWSServiceRoleForRDS role. 3. On the Summary page for the selected role, choose the Access Advisor tab. 4. On the Access Advisor tab, review recent activity for the service-linked role. Note If you are unsure whether Amazon RDS is using the AWSServiceRoleForRDS role, you can try to delete the role. If the service is using the role, then the deletion fails and you can view the regions where the role is being used. If the role is being used, then you must wait for the session to end before you can delete the role. You cannot revoke the session for a service-linked role. If you want to remove the AWSServiceRoleForRDS role, you must first delete all of your DB instances . Deleting All of Your Instances Use one of these procedures to delete each of your instances. To delete an instance (console) 1. 2. Open the Amazon RDS console at https://console.aws.amazon.com/rds/. In the navigation pane, choose Instances. 3. 4. In the Instances list, choose the instance that you want to delete. Choose Instance actions, and then choose Delete. 5. 6. 7. If you are prompted for Create final Snapshot?, choose Yes or No. If you chose Yes in the previous step, for Final snapshot name type the name of your final snapshot. Choose Delete. To delete an instance (CLI) See delete-db-instance in the AWS CLI Command Reference. To delete an instance (API) See DeleteDBInstance in the Amazon RDS API Reference. You can use the IAM console, the IAM CLI, or the IAM API to delete the AWSServiceRoleForRDS servicelinked role. For more information, see Deleting a Service-Linked Role in the IAM User Guide. API Version 2014-10-31 399 Amazon Relational Database Service User Guide Using Amazon RDS with Amazon VPC Amazon Virtual Private Cloud (VPCs) and Amazon RDS There are two Amazon Elastic Compute Cloud (EC2) platforms that host Amazon RDS DB instances, EC2VPC and EC2-Classic. Amazon Virtual Private Cloud (Amazon VPC) lets you launch AWS resources, such as Amazon RDS DB instances, into a virtual private cloud (VPC). When you use an Amazon VPC, you have control over your virtual networking environment: you can select your own IP address range, create subnets, and configure routing and access control lists. The basic functionality of Amazon RDS is the same whether your DB instance is running in an Amazon VPC or not: Amazon RDS manages backups, software patching, automatic failure detection, and recovery. There is no additional cost to run your DB instance in Amazon VPC. Accounts that support only the EC2-VPC platform have a default VPC. All new DB instances are created in the default VPC unless you specify otherwise. If you are a new Amazon RDS customer, if you have never created a DB instance before, or if you are creating a DB instance in a region you have not used before, you are most likely on the EC2-VPC platform and have a default VPC. Some legacy DB instances on the EC2-Classic platform are not in a VPC. The legacy EC2-Classic platform does not have a default VPC, but as is true for either platform, you can create your own VPC and specify that a DB instance be located in that VPC. Topics • Determining Whether You Are Using the EC2-VPC or EC2-Classic Platform (p. 400) • Scenarios for Accessing a DB Instance in a VPC (p. 402) • Working with an Amazon RDS DB Instance in a VPC (p. 408) • Updating the VPC for a DB Instance (p. 413) • Tutorial: Create an Amazon VPC for Use with an Amazon RDS DB Instance (p. 415) This documentation only discusses VPC functionality relevant to Amazon RDS DB instances. For more information about Amazon VPC, see Amazon VPC Getting Started Guide and Amazon VPC User Guide. Determining Whether You Are Using the EC2-VPC or EC2-Classic Platform Your AWS account and the region you select determines which of the two RDS platforms your DB instance is created on: EC2-Classic or EC2-VPC. The type of platform determines if you have a default API Version 2014-10-31 400 Amazon Relational Database Service User Guide Determining Whether You Are Using the EC2-VPC or EC2-Classic Platform VPC, and which type of security group you use to provide access to your DB instance. The legacy EC2Classic platform is the original platform used by Amazon RDS; if you are on this platform and want to use a VPC, you must create the VPC using the Amazon VPC console or Amazon VPC API. Accounts that only support the EC2-VPC platform have a default VPC where all DB instance are created, and you must use either an EC2 or VPC security group to provide access to the DB instance. Note If you are a new Amazon RDS customer, if you have never created a DB instance before, or if you are creating a DB instance in a region you have not used before, in almost all cases you are on the EC2-VPC platform and have a default VPC. You can tell which platform your AWS account in a given region is using by looking at the dashboard on the RDS console or EC2 console. If you are a new Amazon RDS customer, if you have never created a DB instance before, or if you are creating a DB instance in a region you have not used before, you might be redirected to the first-run console page and will not see the home page following. If Supported Platforms indicates VPC, as shown following, your AWS account in the current region uses the EC2-VPC platform, and uses a default VPC. The name of the default VPC is shown below the supported platform. To provide access to a DB instance created on the EC2-VPC platform, you must create a VPC security group. For information about creating a VPC security group, see Tutorial: Create an Amazon VPC for Use with an Amazon RDS DB Instance (p. 415). If Supported Platforms indicates EC2,VPC, as shown following, your AWS account in the current region uses the EC2-Classic platform, and you do not have a default VPC. To provide access to a DB instance created on the EC2-Classic platform, you must create a DB security group. For information about creating a DB security group, see Creating a DB Security Group (p. 387). Note • You can create a VPC on the EC2-Classic platform, but one is not created for you by default as it is on accounts that support the EC2-VPC platform. • If you are interested in moving an existing DB instance into a VPC, you can use the AWS Management Console to do it easily. For more information. see Moving a DB Instance Not in a VPC into a VPC (p. 414). API Version 2014-10-31 401 Amazon Relational Database Service User Guide Scenarios for Accessing a DB Instance in a VPC Scenarios for Accessing a DB Instance in a VPC Amazon RDS supports the following scenarios for accessing a DB instance in a VPC: DB Instance Accessed By In a VPC An EC2 Instance in the Same VPC (p. 402) An EC2 Instance in a Different VPC (p. 403) An EC2 Instance Not in a VPC (p. 404) A Client Application Through the Internet (p. 405) Not in a VPC An EC2 Instance in a VPC (p. 405) An EC2 Instance Not in a VPC (p. 406) A Client Application Through the Internet (p. 407) A DB Instance in a VPC Accessed by an EC2 Instance in the Same VPC A common use of an RDS instance in a VPC is to share data with an application server that is running in an EC2 instance in the same VPC. This is the user scenario created if you use AWS Elastic Beanstalk to create an EC2 instance and a DB instance in the same VPC. The following diagram shows this scenario. The simplest way to manage access between EC2 instances and DB instances in the same VPC is to do the following: • Create a VPC security group that your DB instances will be in. This security group can be used to restrict access to the DB instances. For example, you can create a custom rule for this security group that allows TCP access using the port you assigned to the DB instance when you created it and an IP address you will use to access the DB instance for development or other purposes. API Version 2014-10-31 402 Amazon Relational Database Service User Guide Scenarios for Accessing a DB Instance in a VPC • Create a VPC security group that your EC2 instances (web servers and clients) will be in. This security group can, if needed, allow access to the EC2 instance from the Internet via the VPC's routing table. For example, you can set rules on this security group to allow TCP access to the EC2 instance over port 22. • Create custom rules in the security group for your DB instances that allow connections from the security group you created for your EC2 instances. This would allow any member of the security group to access the DB instances. For a tutorial that shows you how to create a VPC with both public and private subnets for this scenario, see Tutorial: Create an Amazon VPC for Use with an Amazon RDS DB Instance (p. 415). To create a rule in a VPC security group that allows connections from another security group, do the following: 1. Sign in to the AWS Management Console and open the Amazon VPC console at https:// console.aws.amazon.com/vpc. 2. In the navigation pane, choose Security Groups. 3. Select or create a security group for which you want to allow access to members of another security group. In the scenario above, this would be the security group you will use for your DB instances. Choose the Inbound Rules tab, and then choose Edit. 4. Choose Add another rule. 5. From Type, choose All ICMP. In the Source box, start typing the ID of the security group; this provides you with a list of security groups. Select the security group with members that you want to have access to the resources protected by this security group. In the scenario above, this would be the security group you will use for your EC2 instance. 6. Repeat the steps for the TCP protocol by creating a rule with All TCP as the Type and your security group in the Source box. If you intend to use the UDP protocol, create a rule with All UDP as the Type and your security group in the Source box. 7. Create a custom TCP rule that permits access via the port you used when you created your DB instance, such as port 3306 for MySQL. Enter your security group or an IP address you will use in the Source box. 8. Choose Save when you are done. A DB Instance in a VPC Accessed by an EC2 Instance in a Different VPC When your DB instance is in a different VPC from the EC2 instance you are using to access it, you can use VPC peering to access the DB instance. The following diagram shows this scenario. API Version 2014-10-31 403 Amazon Relational Database Service User Guide Scenarios for Accessing a DB Instance in a VPC A VPC peering connection is a networking connection between two VPCs that enables you to route traffic between them using private IP addresses. Instances in either VPC can communicate with each other as if they are within the same network. You can create a VPC peering connection between your own VPCs, with a VPC in another AWS account, or with a VPC in a different AWS Region. To learn more about VPC peering, see the VPC documentation. A DB Instance in a VPC Accessed by an EC2 Instance Not in a VPC You can communicate between an Amazon RDS DB instance that is in a VPC and an EC2 instance that is not in an Amazon VPC by using ClassicLink. When you use Classic Link, an application on the EC2 instance can connect to the DB instance by using the RDS endpoint for the DB instance. ClassicLink is available at no charge. The following diagram shows this scenario. Using ClassicLink, you can connect an EC2 instance to a logically isolated database where you define the IP address range and control the access control lists (ACLs) to manage network traffic. You don't have to use public IP addresses or tunneling to communicate with the DB instance in the VPC. This arrangement provides you with higher throughput and lower latency connectivity for inter-instance communications. To enable ClassicLink between a DB instance in a VPC and an EC2 instance not in a VPC 1. Sign in to the AWS Management Console and open the Amazon VPC console at https:// console.aws.amazon.com/vpc. API Version 2014-10-31 404 Amazon Relational Database Service User Guide Scenarios for Accessing a DB Instance in a VPC 2. In the navigation pane, choose Your VPCs. 3. Choose the VPC used by the DB instance. 4. In Actions, choose Enable ClassicLink. In the confirmation dialog box, choose Yes, Enable. 5. On the EC2 console, select the EC2 instance you want to connect to the DB instance in the VPC. 6. In Actions, choose ClassicLink, and then choose Link to VPC. 7. On the Link to VPC page, choose the security group you want to use, and then choose Link to VPC. Note The ClassicLink features are only visible in the consoles for accounts and regions that support EC2-Classic. For more information, see ClassicLink in the Amazon EC2 User Guide for Linux Instances. A DB Instance in a VPC Accessed by a Client Application Through the Internet To access a DB instance in a VPC from a client application through the internet, you configure a VPC with a single public subnet, and an Internet gateway to enable communication over the Internet. The following diagram shows this scenario. We recommend the following configuration: • A VPC of size /16 (for example CIDR: 10.0.0.0/16). This size provides 65,536 private IP addresses. • A subnet of size /24 (for example CIDR: 10.0.0.0/24). This size provides 256 private IP addresses. • An Amazon RDS DB instance that is associated with the VPC and the subnet. Amazon RDS assigns an IP address within the subnet to your DB instance. • An Internet gateway which connects the VPC to the Internet and to other AWS products. • A security group associated with the DB instance. The security group's inbound rules allow your client application to access to your DB instance. For information about creating a DB instance in a VPC, see Creating a DB Instance in a VPC (p. 410). A DB Instance Not in a VPC Accessed by an EC2 Instance in a VPC In the case where you have an EC2 instance in a VPC and an RDS DB instance not in a VPC, you can connect them over the public Internet. API Version 2014-10-31 405 Amazon Relational Database Service User Guide Scenarios for Accessing a DB Instance in a VPC The following diagram shows this scenario. Note ClassicLink, as described in A DB Instance in a VPC Accessed by an EC2 Instance Not in a VPC (p. 404), is not available for this scenario. To connect your DB instance and your EC2 instance over the public Internet, do the following: • Ensure that the EC2 instance is in a public subnet in the VPC. • Ensure that the RDS DB instance was marked as publicly accessible. • A note about network ACLs here. A network ACL is like a firewall for your entire subnet. Therefore, all instances in that subnet are subject to network ACL rules. By default, network ACLs allow all traffic and you generally don’t need to worry about them, unless you particularly want to add rules as an extra layer of security. A security group, on the other hand, is associated with individual instances, and you do need to worry about security group rules. • Add the necessary ingress rules to the DB security group for the RDS DB instance. An ingress rule specifies a network port and a CIDR/IP range. For example, you can add an ingress rule that allows port 3306 to connect to a MySQL RDS DB instance, and a CIDR/IP range of 203.0.113.25/32. For more information, see Authorizing Network Access to a DB Security Group from an IP Range (p. 391). Note If you are interested in moving an existing DB instance into a VPC, you can use the AWS Management Console to do it easily. For more information. see Moving a DB Instance Not in a VPC into a VPC (p. 414). A DB Instance Not in a VPC Accessed by an EC2 Instance Not in a VPC When neither your DB instance nor an application on an EC2 instance are in a VPC, you can access the DB instance by using its endpoint and port. The following diagram shows this scenario. API Version 2014-10-31 406 Amazon Relational Database Service User Guide Scenarios for Accessing a DB Instance in a VPC You must create a security group for the DB instance that permits access from the port you specified when creating the DB instance. For example, you could use a connection string similar to this connection string used with sqlplus to access an Oracle DB instance: PROMPT>sqlplus 'mydbusr@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=) (PORT=))(CONNECT_DATA=(SID=)))' For more information, see the following documentation. Database Engine Relevant Documentation MariaDB Connecting to a DB Instance Running the MariaDB Database Engine (p. 440) Microsoft SQL Server Connecting to a DB Instance Running the Microsoft SQL Server Database Engine (p. 503) MySQL Connecting to a DB Instance Running the MySQL Database Engine (p. 596) Oracle Connecting to a DB Instance Running the Oracle Database Engine (p. 743) PostgreSQL Connecting to a DB Instance Running the PostgreSQL Database Engine (p. 970) Note If you are interested in moving an existing DB instance into a VPC, you can use the AWS Management Console to do it easily. For more information. see Moving a DB Instance Not in a VPC into a VPC (p. 414). A DB Instance Not in a VPC Accessed by a Client Application Through the Internet New Amazon RDS customers can only create a DB instance in a VPC. However, you might need to connect to an existing Amazon RDS DB instance that is not in a VPC from a client application through the Internet. The following diagram shows this scenario. API Version 2014-10-31 407 Amazon Relational Database Service User Guide Working with a DB Instance in a VPC In this scenario, you must ensure that the DB security group for the RDS DB instance includes the necessary ingress rules for your client application to connect. An ingress rule specifies a network port and a CIDR/IP range. For example, you can add an ingress rule that allows port 3306 to connect to a MySQL RDS DB instance, and a CIDR/IP range of 203.0.113.25/32. For more information, see Authorizing Network Access to a DB Security Group from an IP Range (p. 391). Warning If you intend to access a DB instance behind a firewall, talk with your network administrator to determine the IP addresses you should use. Note If you are interested in moving an existing DB instance into a VPC, you can use the AWS Management Console to do it easily. For more information. see Moving a DB Instance Not in a VPC into a VPC (p. 414). Working with an Amazon RDS DB Instance in a VPC Unless you are working with a legacy DB instance, your DB instance is in a virtual private cloud (VPC). A virtual private cloud is a virtual network that is logically isolated from other virtual networks in the AWS Cloud. Amazon VPC lets you launch AWS resources, such as an Amazon RDS or Amazon EC2 instance, into a VPC. The VPC can either be a default VPC that comes with your account or one that you create. All VPCs are associated with your AWS account. Your default VPC has three subnets you can use to isolate resources inside the VPC. The default VPC also has an Internet Gateway that can be used to provide access to resources inside the VPC from outside the VPC. For a list of scenarios involving Amazon RDS DB instances in a VPC and outside of a VPC, see Scenarios for Accessing a DB Instance in a VPC (p. 402). For a tutorial that shows you how to create a VPC that you can use with a common Amazon RDS scenario, see Tutorial: Create an Amazon VPC for Use with an Amazon RDS DB Instance (p. 415). To learn how to work with an Amazon RDS DB instances inside a VPC, see the following: Topics • Working with a DB Instance in a VPC (p. 408) • Working with DB Subnet Groups (p. 409) • Hiding a DB Instance in a VPC from the Internet (p. 410) • Creating a DB Instance in a VPC (p. 410) Working with a DB Instance in a VPC Here are some tips on working with a DB instance in a VPC: API Version 2014-10-31 408 Amazon Relational Database Service User Guide Working with a DB Instance in a VPC • Your VPC must have at least two subnets. These subnets must be in two different Availability Zones in the region where you want to deploy your DB instance. A subnet is a segment of a VPC's IP address range that you can specify and that lets you group instances based on your security and operational needs. • If you want your DB instance in the VPC to be publicly accessible, you must enable the VPC attributes DNS hostnames and DNS resolution. • Your VPC must have a DB subnet group that you create (for more information, see the next section). You create a DB subnet group by specifying the subnets you created. Amazon RDS uses that DB subnet group and your preferred Availability Zone to select a subnet and an IP address within that subnet to assign to your DB instance. • Your VPC must have a VPC security group that allows access to the DB instance. • The CIDR blocks in each of your subnets must be large enough to accommodate spare IP addresses for Amazon RDS to use during maintenance activities, including failover and compute scaling. • A VPC can have an instance tenancy attribute of either default or dedicated. All default VPCs have the instance tenancy attribute set to default, and a default VPC can support any DB instance class. If you choose to have your DB instance in a dedicated VPC where the instance tenancy attribute is set to dedicated, the DB instance class of your DB instance must be one of the approved Amazon EC2 dedicated instance types. For example, the m3.medium EC2 dedicated instance corresponds to the db.m3.medium DB instance class. For information about instance tenancy in a VPC, go to Using EC2 Dedicated Instances in the Amazon Virtual Private Cloud User Guide. For more information about the instance types that can be in a dedicated instance, see Amazon EC2 Dedicated Instances on the EC2 pricing page. • When an option group is assigned to a DB instance, it is linked to the supported platform the DB instance is on, either VPC or EC2-Classic (non-VPC). Furthermore, if a DB instance is in a VPC, the option group associated with the DB instance is linked to that VPC. This linkage means that you cannot use the option group assigned to a DB instance if you attempt to restore the DB instance into a different VPC or onto a different platform. • If you restore a DB instance into a different VPC or onto a different platform, you must either assign the default option group to the DB instance, assign an option group that is linked to that VPC or platform, or create a new option group and assign it to the DB instance. Note that with persistent or permanent options, such as Oracle TDE, you must create a new option group that includes the persistent or permanent option when restoring a DB instance into a different VPC. Working with DB Subnet Groups Subnets are segments of a VPC's IP address range that you designate to group your resources based on security and operational needs. A DB subnet group is a collection of subnets (typically private) that you create in a VPC and that you then designate for your DB instances. A DB subnet group allows you to specify a particular VPC when creating DB instances using the CLI or API; if you use the console, you can just select the VPC and subnets you want to use. Each DB subnet group should have subnets in at least two Availability Zones in a given region. When creating a DB instance in a VPC, you must select a DB subnet group. Amazon RDS uses that DB subnet group and your preferred Availability Zone to select a subnet and an IP address within that subnet to associate with your DB instance. If the primary DB instance of a Multi-AZ deployment fails, Amazon RDS can promote the corresponding standby and subsequently create a new standby using an IP address of the subnet in one of the other Availability Zones. When Amazon RDS creates a DB instance in a VPC, it assigns a network interface to your DB instance by using an IP address selected from your DB subnet group. However, we strongly recommend that you use the DNS name to connect to your DB instance because the underlying IP address can change during failover. API Version 2014-10-31 409 Amazon Relational Database Service User Guide Working with a DB Instance in a VPC Note For each DB instance that you run in a VPC, you should reserve at least one address in each subnet in the DB subnet group for use by Amazon RDS for recovery actions. Hiding a DB Instance in a VPC from the Internet One common Amazon RDS scenario is to have a VPC in which you have an EC2 instance with a publicfacing web application and a DB instance with a database that is not publicly accessible. For example, you can create a VPC that has a public subnet and a private subnet. Amazon EC2 instances that function as web servers can be deployed in the public subnet, and the Amazon RDS DB instances are deployed in the private subnet. In such a deployment, only the web servers have access to the DB instances. For an illustration of this scenario, see A DB Instance in a VPC Accessed by an EC2 Instance in the Same VPC (p. 402). When you launch a DB instance inside a VPC, you can designate whether the DB instance you create has a DNS that resolves to a public IP address by using the Public accessibility parameter. This parameter lets you designate whether there is public access to the DB instance. Note that access to the DB instance is ultimately controlled by the security group it uses, and that public access is not permitted if the security group assigned to the DB instance does not permit it. You can modify a DB instance to turn on or off public accessibility by modifying the Public accessibility parameter. This parameter is modified just like any other DB instance parameter. For more information, see the modifying section for your DB engine. The following illustration shows the Public accessibility option in the Network & Security section. Creating a DB Instance in a VPC The following procedures help you create a DB instance in a VPC. If your account has a default VPC, you can begin with step 3 because the VPC and DB subnet group have already been created for you. If your AWS account doesn't have a default VPC, or if you want to create an additional VPC, you can create a new VPC. If you don't know if you have a default VPC, see Determining Whether You Are Using the EC2-VPC or EC2-Classic Platform (p. 400). Note If you want your DB instance in the VPC to be publicly accessible, you must update the DNS information for the VPC by enabling the VPC attributes DNS hostnames and DNS resolution. For API Version 2014-10-31 410 Amazon Relational Database Service User Guide Working with a DB Instance in a VPC information about updating the DNS information for a VPC instance, see Updating DNS Support for Your VPC. Follow these steps to create a DB instance in a VPC: • Step 1: Create a VPC (p. 411) • Step 2: Add Subnets to the VPC (p. 411) • Step 3: Create a DB Subnet Group (p. 411) • Step 4: Create a VPC Security Group (p. 412) • Step 5: Create a DB Instance in the VPC (p. 412) Step 1: Create a VPC If your AWS account does not have a default VPC or if you want to create an additional VPC, follow the instructions for creating a new VPC. See Create a VPC with Private and Public Subnets (p. 415) in the Amazon RDS documentation, or see Step 1: Create a VPC in the Amazon VPC documentation. Step 2: Add Subnets to the VPC Once you have created a VPC, you need to create subnets in at least two Availability Zones. You use these subnets when you create a DB subnet group. Note that if you have a default VPC, a subnet is automatically created for you in each Availability Zone in the region. For instructions on how to create subnets in a VPC, see Create a VPC with Private and Public Subnets (p. 415) in the Amazon RDS documentation. Step 3: Create a DB Subnet Group A DB subnet group is a collection of subnets (typically private) that you create for a VPC and that you then designate for your DB instances. A DB subnet group allows you to specify a particular VPC when you create DB instances using the CLI or API. If you use the Amazon RDS console, you can just select the VPC and subnets you want to use. Each DB subnet group must have at least one subnet in at least two Availability Zones in the region. Note For a DB instance to be publicly accessible, the subnets in the DB subnet group must have an Internet gateway. For more information about Internet gateways for subnets, go to Internet Gateways in the Amazon VPC documentation. When you create a DB instance in a VPC, you must select a DB subnet group. Amazon RDS then uses that DB subnet group and your preferred Availability Zone to select a subnet and an IP address within that subnet. Amazon RDS creates and associates an Elastic Network Interface to your DB instance with that IP address. For Multi-AZ deployments, defining a subnet for two or more Availability Zones in a region allows Amazon RDS to create a new standby in another Availability Zone should the need arise. You need to do this even for Single-AZ deployments, just in case you want to convert them to Multi-AZ deployments at some point. In this step, you create a DB subnet group and add the subnets you created for your VPC. AWS Management Console To create a DB subnet group 1. 2. Open the Amazon RDS console at https://console.aws.amazon.com/rds/. In the navigation pane, choose Subnet groups. 3. 4. Choose Create DB Subnet Group. For Name, type the name of your DB subnet group. API Version 2014-10-31 411 Amazon Relational Database Service User Guide Working with a DB Instance in a VPC 5. For Description, type a description for your DB subnet group. 6. For VPC, choose the VPC that you created. 7. In the Add subnets section, click the Add all the subnets related to this VPC link. 8. Choose Create. Your new DB subnet group appears in the DB subnet groups list on the RDS console. You can click the DB subnet group to see details, including all of the subnets associated with the group, in the details pane at the bottom of the window. Step 4: Create a VPC Security Group Before you create your DB instance, you must create a VPC security group to associate with your DB instance. For instructions on how to create a security group for your DB instance, see Create a VPC Security Group for a Private Amazon RDS DB Instance (p. 418) in the Amazon RDS documentation, or see Security Groups for Your VPC in the Amazon VPC documentation. Step 5: Create a DB Instance in the VPC In this step, you create a DB instance and use the VPC name, the DB subnet group, and the VPC security group you created in the previous steps. API Version 2014-10-31 412 Amazon Relational Database Service User Guide Updating the VPC for a DB Instance Note If you want your DB instance in the VPC to be publicly accessible, you must enable the VPC attributes DNS hostnames and DNS resolution. For information on updating the DNS information for a VPC instance, see Updating DNS Support for Your VPC. For details on how to create a DB instance for your DB engine, see the topic following that discusses your DB engine. For each engine, when prompted in the Network & Security section, enter the VPC name, the DB subnet group, and the VPC security group you created in the previous steps. Database Engine Relevant Documentation MariaDB Creating a DB Instance Running the MariaDB Database Engine (p. 431) Microsoft SQL Server Creating a DB Instance Running the Microsoft SQL Server Database Engine (p. 492) MySQL Creating a DB Instance Running the MySQL Database Engine (p. 587) Oracle Creating a DB Instance Running the Oracle Database Engine (p. 734) PostgreSQL Creating a DB Instance Running the PostgreSQL Database Engine (p. 964) Updating the VPC for a DB Instance You can use the AWS Management Console to easily move your DB instance to a different VPC. For details on how to modify a DB instance for your DB engine, see the topic in the table following that discusses your DB engine. In the Network & Security section of the modify page, shown following, for Subnet group, enter the new subnet group. The new subnet group must be a subnet group in a new VPC. Database Engine Relevant Documentation MariaDB Modifying a DB Instance Running the MariaDB Database Engine (p. 443) Microsoft SQL Server Modifying a DB Instance Running the Microsoft SQL Server Database Engine (p. 510) MySQL Modifying a DB Instance Running the MySQL Database Engine (p. 600) Oracle Modifying a DB Instance Running the Oracle Database Engine (p. 750) PostgreSQL Modifying a DB Instance Running the PostgreSQL Database Engine (p. 973) API Version 2014-10-31 413 Amazon Relational Database Service User Guide Updating the VPC for a DB Instance Moving a DB Instance Not in a VPC into a VPC Some legacy DB instances on the EC2-Classic platform are not in a VPC. If your DB instance is not in a VPC, you can use the AWS Management Console to easily move your DB instance into a VPC. Before you can move a DB instance not in a VPC, into a VPC, you must create the VPC. Follow these steps to create a VPC for your DB instance. • Step 1: Create a VPC (p. 411) • Step 2: Add Subnets to the VPC (p. 411) • Step 3: Create a DB Subnet Group (p. 411) • Step 4: Create a VPC Security Group (p. 412) After you create the VPC, follow these steps to move your DB instance into the VPC. • Updating the VPC for a DB Instance (p. 413) The following are some limitations to moving your DB instance into the VPC. • Moving a Multi-AZ DB instance not in a VPC into a VPC is not currently supported. • Moving a DB instance with Read Replicas not in a VPC into a VPC is not currently supported. If you move your DB instance into a VPC, and you are using a custom option group with your DB instance, then you need to change the option group that is associated with your DB instance. Option groups are platform-specific, and moving to a VPC is a change in platform. To use a custom option group in this case, assign the default VPC option group to the DB instance, assign an option group that is used by other DB instances in the VPC you are moving to, or create a new option group and assign it to the DB instance. For more information, see Working with Option Groups (p. 152). API Version 2014-10-31 414 Amazon Relational Database Service User Guide Tutorial: Create an Amazon VPC for Use with an Amazon RDS DB Instance Tutorial: Create an Amazon VPC for Use with an Amazon RDS DB Instance A common scenario includes an Amazon RDS DB instance in an Amazon VPC, that shares data with a web server that is running in the same VPC. In this tutorial you create the VPC for this scenario. The following diagram shows this scenario. For information about other scenarios, see Scenarios for Accessing a DB Instance in a VPC (p. 402). Because your Amazon RDS DB instance only needs to be available to your web server, and not to the public Internet, you create a VPC with both public and private subnets. The web server is hosted in the public subnet, so that it can reach the public Internet. The Amazon RDS DB instance is hosted in a private subnet. The web server is able to connect to the Amazon RDS DB instance because it is hosted within the same VPC, but the Amazon RDS DB instance is not available to the public Internet, providing greater security. Create a VPC with Private and Public Subnets Use the following procedure to create a VPC with both public and private subnets. To create a VPC and subnets 1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/. 2. In the top-right corner of the AWS Management Console, choose the region to create your VPC in. This example uses the US West (Oregon) region. 3. In the upper-left corner, choose VPC Dashboard. To begin creating a VPC, choose Start VPC Wizard. 4. On the Step 1: Select a VPC Configuration page, choose VPC with Public and Private Subnets, and then choose Select. 5. On the Step 2: VPC with Public and Private Subnets page, set these values: • IPv4 CIDR block: 10.0.0.0/16 • IPv6 CIDR block: No IPv6 CIDR Block • VPC name: tutorial-vpc API Version 2014-10-31 415 Amazon Relational Database Service User Guide Tutorial: Create an Amazon VPC for Use with an Amazon RDS DB Instance • Public subnet's IPv4 CIDR: 10.0.0.0/24 • Availability Zone: us-west-2a • Public subnet name: Tutorial public • Private subnet's IPv4 CIDR: 10.0.1.0/24 • Availability Zone: us-west-2a • Private subnet name: Tutorial Private 1 • Instance type: t2.small Important If you do not see the Instance type box in the console, click Use a NAT instance instead. This link is on the right. Note If the t2.small instance type is not listed, you can select a different instance type. • Key pair name: No key pair • Service endpoints: Skip this field. • Enable DNS hostnames: Yes • Hardware tenancy: Default 6. When you're finished, choose Create VPC. Create Additional Subnets You must have either two private subnets or two public subnets available to create an Amazon RDS DB subnet group for an RDS DB instance to use in a VPC. Because the RDS DB instance for this tutorial is private, add a second private subnet to the VPC. To create an additional subnet 1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/. 2. To add the second private subnet to your VPC, choose VPC Dashboard, choose Subnets, and then choose Create Subnet. 3. On the Create Subnet page, set these values: • Name tag: Tutorial private 2 • VPC: Choose the VPC that you created in the previous step, for example: vpc-identifier (10.0.0.0/16) | tutorial-vpc • Availability Zone: us-west-2b Note Choose an Availability Zone that is different from the one that you chose for the first private subnet. • IPv4 CIDR block: 10.0.2.0/24 4. When you're finished, choose Yes, Create. 5. To ensure that the second private subnet that you created uses the same route table as the first private subnet, choose VPC Dashboard, choose Subnets, and then choose the first private subnet that you created for the VPC, Tutorial private 1. 6. Below the list of subnets, choose the Route Table tab, and note the value for Route Table—for example: rtb-98b613fd. 7. In the list of subnets, deselect the first private subnet. 8. In the list of subnets, choose the second private subnet Tutorial private 2, and choose the Route Table tab. API Version 2014-10-31 416 Amazon Relational Database Service User Guide Tutorial: Create an Amazon VPC for Use with an Amazon RDS DB Instance 9. If the current route table is not the same as the route table for the first private subnet, choose Edit. For Change to, choose the route table that you noted earlier—for example: rtb-98b613fd. 10. To save your selection, choose Save. Create a VPC Security Group for a Public Web Server Next you create a security group for public access. To connect to public instances in your VPC, you add inbound rules to your VPC security group that allow traffic to connect from the internet. To create a VPC security group 1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/. 2. Choose VPC Dashboard, choose Security Groups, and then choose Create Security Group. 3. On the Create Security Group page, set these values: • Name tag: tutorial-securitygroup • Group name: tutorial-securitygroup • Description: Tutorial Security Group • VPC: Choose the VPC that you created earlier, for example: vpc-identifier (10.0.0.0/16) | tutorial-vpc 4. To create the security group, choose Yes, Create. To add inbound rules to the security group 1. Determine the IP address that you will use to connect to instances in your VPC. To determine your public IP address, you can use the service at https://checkip.amazonaws.com. An example of an IP address is 203.0.113.25/32. If you are connecting through an Internet service provider (ISP) or from behind your firewall without a static IP address, you need to find out the range of IP addresses used by client computers. Warning If you use 0.0.0.0/0, you enable all IP addresses to access your public instances. This approach is acceptable for a short time in a test environment, but it's unsafe for production environments. In production, you'll authorize only a specific IP address or range of addresses to access your instances. 2. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/. 3. Choose VPC Dashboard, choose Security Groups, and then choose the tutorial-securitygroup security group that you created in the previous procedure. 4. Choose the Inbound Rules tab, and then choose Edit. 5. Set the following values for your new inbound rule to allow Secure Shell (SSH) access to your EC2 instance. If you do this, you can connect to your EC2 instance to install the web server and other utilities, and to upload content for your web server. • Type: SSH (22) • Source: The IP address or range from Step 1, for example: 203.0.113.25/32. 6. Choose Add another rule. 7. Set the following values for your new inbound rule to allow HTTP access to your web server. • Type: HTTP (80) • Source: 0.0.0.0/0. 8. To save your settings, choose Save. API Version 2014-10-31 417 Amazon Relational Database Service User Guide Tutorial: Create an Amazon VPC for Use with an Amazon RDS DB Instance Create a VPC Security Group for a Private Amazon RDS DB Instance To keep your Amazon RDS DB instance private, create a second security group for private access. To connect to private instances in your VPC, you add inbound rules to your VPC security group that allow traffic from your web server only. To create a VPC security group 1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/. 2. Choose VPC Dashboard, choose Security Groups, and then choose Create Security Group. 3. On the Create Security Group page, set these values: • Name tag: tutorial-db-securitygroup • Group name: tutorial-db-securitygroup • Description: Tutorial DB Instance Security Group • VPC: Choose the VPC that you created earlier, for example: vpc-identifier (10.0.0.0/16) | tutorial-vpc 4. To create the security group, choose Yes, Create. To add inbound rules to the security group 1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/. 2. Choose VPC Dashboard, choose Security Groups, and then choose the tutorial-dbsecuritygroup security group that you created in the previous procedure. 3. Choose the Inbound Rules tab, and then choose Edit. 4. Set the following values for your new inbound rule to allow MySQL traffic on port 3306 from your EC2 instance. If you do this, you can connect from your web server to your DB instance to store and retrieve data from your web application to your database. • Type: MySQL/Aurora (3306) • Source: The identifier of the tutorial-securitygroup security group that you created previously in this tutorial, for example: sg-9edd5cfb. 5. To save your settings, choose Save. Create a DB Subnet Group A DB subnet group is a collection of subnets that you create in a VPC and that you then designate for your DB instances. A DB subnet group allows you to specify a particular VPC when creating DB instances. To create a DB subnet group 1. Open the Amazon RDS console at https://console.aws.amazon.com/rds/. 2. In the navigation pane, choose Subnet groups. 3. Choose Create DB Subnet Group. 4. On the Create DB subnet group page, set these values in Subnet group details: • Name: tutorial-db-subnet-group • Description: Tutorial DB Subnet Group • VPC: tutorial-vpc (vpc-identifier) 5. In the Add subnets section, click the Add all the subnets related to this VPC link. API Version 2014-10-31 418 Amazon Relational Database Service User Guide Tutorial: Create an Amazon VPC for Use with an Amazon RDS DB Instance 6. Choose Create. Your new DB subnet group appears in the DB subnet groups list on the RDS console. You can click the DB subnet group to see details, including all of the subnets associated with the group, in the details pane at the bottom of the window. API Version 2014-10-31 419 Amazon Relational Database Service User Guide Common Management Tasks MariaDB on Amazon RDS Amazon RDS supports DB instances running several versions of MariaDB. You can use the following major versions: • MariaDB 10.3 • MariaDB 10.2 • MariaDB 10.1 • MariaDB 10.0 For more information about minor version support, see MariaDB on Amazon RDS Versions (p. 422). You first use the Amazon RDS management tools or interfaces to create an Amazon RDS MariaDB DB instance. You can then use the Amazon RDS tools to perform management actions for the DB instance, such as reconfiguring or resizing the DB instance, authorizing connections to the DB instance, creating and restoring from backups or snapshots, creating Multi-AZ secondaries, creating Read Replicas, and monitoring the performance of the DB instance. You use standard MariaDB utilities and applications to store and access the data in the DB instance. MariaDB is available in all of the AWS Regions. For more information about AWS Regions, see Regions and Availability Zones (p. 99). You can use Amazon RDS for MariaDB databases to build HIPAA-compliant applications. You can store healthcare-related information, including protected health information (PHI), under an executed Business Associate Agreement (BAA) with AWS. For more information, see HIPAA Compliance. AWS Services in Scope have been fully assessed by a third-party auditor and result in a certification, attestation of compliance, or Authority to Operate (ATO). For more information, see AWS Services in Scope by Compliance Program. Before creating your first DB instance, you should complete the steps in the setting up section of this guide. For more information, see Setting Up for Amazon RDS (p. 5). Common Management Tasks for MariaDB on Amazon RDS The following are the common management tasks you perform with an Amazon RDS DB instance running MariaDB, with links to relevant documentation for each task. Task Area Relevant Documentation Instance Classes, Storage, and PIOPS DB Instance Class (p. 80) If you are creating a DB instance for production purposes, you should understand how instance classes, storage types, and Provisioned IOPS work in Amazon RDS. Amazon RDS Storage Types (p. 101) Multi-AZ Deployments High Availability (Multi-AZ) for Amazon RDS (p. 107) Provide high availability with synchronous standby replication in a different Availability Zone, automatic failover, fault tolerance for DB instances using Multi-AZ deployments, and Read Replicas. API Version 2014-10-31 420 Amazon Relational Database Service User Guide Common Management Tasks Task Area Relevant Documentation Amazon Virtual Private Cloud (VPC) Determining Whether You Are Using the EC2-VPC or EC2Classic Platform (p. 400) If your AWS account has a default VPC, then your DB instance is automatically created inside the default VPC. If your account does not have a default VPC, and you want the DB instance in a VPC, you must create the VPC and subnet groups before you create the DB instance. Security Groups By default, DB instances are created with a firewall that prevents access to them. You therefore must create a security group with the correct IP addresses and network configuration to access the DB instance. The security group you create depends on what Amazon EC2 platform your DB instance is on, and whether you access your DB instance from an Amazon EC2 instance. Working with an Amazon RDS DB Instance in a VPC (p. 408) Determining Whether You Are Using the EC2-VPC or EC2Classic Platform (p. 400) Controlling Access with Amazon RDS Security Groups (p. 382) In general, if your DB instance is on the EC2-Classic platform, you will need to create a DB security group; if your DB instance is on the EC2-VPC platform, you will need to create a VPC security group. Parameter Groups If your DB instance is going to require specific database parameters, you should create a parameter group before you create the DB instance. Importing and Exporting Data Establish procedures for importing or exporting data. Replication You can offload read traffic from your primary MariaDB DB instance by creating Read Replicas. Connecting to Your DB Instance Connect to your DB instance using a standard SQL client application. Backup and Restore Working with DB Parameter Groups (p. 165) Importing Data into a MariaDB DB Instance (p. 464) Working with Read Replicas of MariaDB, MySQL, and PostgreSQL DB Instances (p. 139) Connecting to a DB Instance Running the MariaDB Database Engine (p. 440) Working With Backups (p. 202) When you create your DB instance, you can configure it to take automated backups. You can also back up and restore your databases manually by using full backup files (.bak files). Monitoring Monitor your RDS MariaDB DB instance by using Amazon CloudWatch RDS metrics, events, and Enhanced Monitoring. View log files for your RDS MariaDB DB instance. Log Files You can access the log files for your MariaDB DB instance. API Version 2014-10-31 421 Viewing DB Instance Metrics (p. 248) Viewing Amazon RDS Events (p. 295) Amazon RDS Database Log Files (p. 297) MariaDB Database Log Files (p. 301) Amazon Relational Database Service User Guide MariaDB Versions There are also advanced administrative tasks for working with DB instances running MariaDB. For more information, see the following documentation: • Parameters for MariaDB (p. 468) • MariaDB on Amazon RDS SQL Reference (p. 473) MariaDB on Amazon RDS Versions For MariaDB, version numbers are organized as version X.Y.Z. In Amazon RDS terminology, X.Y denotes the major version, and Z is the minor version number. For Amazon RDS implementations, a version change is considered major if the major version number changes, for example going from version 10.0 to 10.1. A version change is considered minor if only the minor version number changes, for example going from version 10.0.17 to 10.0.24. Amazon RDS currently supports the following versions of MariaDB: Major Version Minor Version MariaDB 10.3 • 10.3.8 (supported in all AWS Regions) MariaDB 10.2 • 10.2.15 (supported in all AWS Regions) • 10.2.12 (supported in all AWS Regions) • 10.2.11 (supported in all AWS Regions) MariaDB 10.1 • 10.1.34 (supported in all AWS Regions) • 10.1.31 (supported in all AWS Regions) • 10.1.26 (supported in all AWS Regions) • 10.1.23 (supported in all AWS Regions) • 10.1.19 (supported in all AWS Regions) • 10.1.14 (supported in all AWS Regions except us-east-2) MariaDB 10.0 • 10.0.35 (supported in all AWS Regions) • 10.0.34 (supported in all AWS Regions) • 10.0.32 (supported in all AWS Regions) • 10.0.31 (supported in all AWS Regions) • 10.0.28 (supported in all AWS Regions) • 10.0.24 (supported in all AWS Regions) • 10.0.17 (supported in all AWS Regions except us-east-2, cacentral-1, eu-west-2) For information about the Amazon RDS deprecation policy for MariaDB, see Amazon RDS FAQs. Version and Feature Support on Amazon RDS MariaDB 10.3 Support on Amazon RDS Amazon RDS supports the following versions of MariaDB 10.3: • 10.3.8 (supported in all AWS Regions) API Version 2014-10-31 422 Amazon Relational Database Service User Guide MariaDB 10.2 Support Amazon RDS supports the following new features for your DB instances running MariaDB version 10.3 or later: • Oracle compatibility – PL/SQL compatibility parser, sequences, INTERSECT and EXCEPT to complement UNION, new TYPE OF and ROW TYPE OF declarations, and invisible columns • Temporal data processing – System versioned tables for querying of past and present states of the database • Flexibility – User-defined aggregates, storage-independent column compression, and proxy protocol support to relay the client IP address to the server • Manageability – Instant ADD COLUMN operations and fast-fail data definition language (DDL) operations For a list of all MariaDB 10.3 features and their documentation, see Changes & Improvements in MariaDB 10.3 and Release Notes - MariaDB 10.3 Series on the MariaDB website. For a list of unsupported features, see Features Not Supported (p. 424). MariaDB 10.2 Support on Amazon RDS Amazon RDS supports the following versions of MariaDB 10.2: • 10.2.15 (supported in all AWS Regions) • 10.2.12 (supported in all AWS Regions) • 10.2.11 (supported in all AWS Regions) Amazon RDS supports the following new features for your DB instances running MariaDB version 10.2 or later: • ALTER USER • Common Table Expressions • Compressing Events to Reduce Size of the Binary Log • CREATE USER — new options for limiting resource usage and TLS/SSL • EXECUTE IMMEDIATE • Flashback • InnoDB — now the default storage engine instead of XtraDB • InnoDB — set the buffer pool size dynamically • JSON Functions • Window Functions • WITH For a list of all MariaDB 10.2 features and their documentation, see Changes & Improvements in MariaDB 10.2 and Release Notes - MariaDB 10.2 Series on the MariaDB website. For a list of unsupported features, see Features Not Supported (p. 424). MariaDB 10.1 Support on Amazon RDS Amazon RDS supports the following versions of MariaDB 10.1: • 10.1.34 (supported in all AWS Regions) API Version 2014-10-31 423 Amazon Relational Database Service User Guide MariaDB 10.0 Support • 10.1.31 (supported in all AWS Regions) • 10.1.26 (supported in all AWS Regions) • 10.1.23 (supported in all AWS Regions) • 10.1.19 (supported in all AWS Regions) • 10.1.14 (supported in all AWS Regions except us-east-2) Amazon RDS supports the following new features for your DB instances running MariaDB version 10.1 or later: • Optimistic in-order parallel replication • Page Compression • XtraDB data scrubbing and defragmentation For a list of all MariaDB 10.1 features and their documentation, see Changes & Improvements in MariaDB 10.1 and Release Notes - MariaDB 10.1 Series on the MariaDB website. For a list of unsupported features, see Features Not Supported (p. 424). MariaDB 10.0 Support on Amazon RDS Amazon RDS supports the following versions of MariaDB 10.0: • 10.0.35 (supported in all AWS Regions) • 10.0.34 (supported in all AWS Regions) • 10.0.32 (supported in all AWS Regions) • 10.0.31 (supported in all AWS Regions) • 10.0.28 (supported in all AWS Regions) • 10.0.24 (supported in all AWS Regions) • 10.0.17 (supported in all AWS Regions except us-east-2, ca-central-1, eu-west-2) For a list of all MariaDB 10.0 features and their documentation, see Changes & Improvements in MariaDB 10.0 and Release Notes - MariaDB 10.0 Series on the MariaDB website. For a list of unsupported features, see Features Not Supported (p. 424). Features Not Supported The following MariaDB features are not supported on Amazon RDS: • Authentication plugin – GSSAPI • Authentication plugin – Unix Socket • AWS Key Management encryption plugin • Delayed replication • Encryption at rest for XtraDB and InnoDB • HandlerSocket • JSON table type • MariaDB ColumnStore • MariaDB Galera Cluster API Version 2014-10-31 424 Amazon Relational Database Service User Guide Supported Storage Engines • Multisource replication • MyRocks storage engine • Password validation plugin, simple_password_check, and cracklib_password_check • Replication filters • Spider storage engine • Sphinx storage engine • TokuDB storage engine • Storage engine-specific object attributes, as described in Engine-defined New Table/Field/Index Attributes in the MariaDB documentation • Table and tablespace encryption To deliver a managed service experience, Amazon RDS doesn't provide shell access to DB instances, and it restricts access to certain system procedures and tables that require advanced privileges. Amazon RDS supports access to databases on a DB instance using any standard SQL client application. Amazon RDS doesn't allow direct host access to a DB instance by using Telnet, Secure Shell (SSH), or Windows Remote Desktop Connection. Supported Storage Engines for MariaDB on Amazon RDS While MariaDB supports multiple storage engines with varying capabilities, not all of them are optimized for recovery and data durability. InnoDB (for version 10.2 and higher) and XtraDB (for version 10.0 and 10.1) are the recommended and supported storage engines for MariaDB DB instances on Amazon RDS. Amazon RDS features such as Point-In-Time Restore and snapshot restore require a recoverable storage engine and are supported only for the recommended storage engine for the MariaDB version. Amazon RDS also supports Aria, although using Aria might have a negative impact on recovery in the event of an instance failure. However, if you need to use spatial indexes to handle geographic data on MariaDB 10.1 or 10.0, you should use Aria because spatial indexes are not supported by XtraDB. On MariaDB 10.2 and higher, the InnoDB storage engine supports spatial indexes. Other storage engines are not currently supported by Amazon RDS for MariaDB. MariaDB Security on Amazon RDS Security for Amazon RDS MariaDB DB instances is managed at three levels: • AWS Identity and Access Management controls who can perform Amazon RDS management actions on DB instances. When you connect to AWS using IAM credentials, your IAM account must have IAM policies that grant the permissions required to perform Amazon RDS management operations. For more information, see Authentication and Access Control (p. 330). • When you create a DB instance, you use either a VPC security group or a DB security group to control which devices and Amazon EC2 instances can open connections to the endpoint and port of the DB instance. These connections can be made using Secure Socket Layer (SSL). In addition, firewall rules at your company can control whether devices running at your company can open connections to the DB instance. • Once a connection has been opened to a MariaDB DB instance, authentication of the login and permissions are applied the same way as in a stand-alone instance of MariaDB. Commands such as CREATE USER, RENAME USER, GRANT, REVOKE, and SET PASSWORD work just as they do in standalone databases, as does directly modifying database schema tables. API Version 2014-10-31 425 Amazon Relational Database Service User Guide MariaDB Security When you create an Amazon RDS DB instance, the master user has the following default privileges: • alter • alter routine • create • create routine • create temporary tables • create user • create view • delete • drop • event • execute • grant option • index • insert • lock tables • process • references • reload This privilege is limited on Amazon RDS MariaDB DB instances. It doesn't grant access to the FLUSH LOGS or FLUSH TABLES WITH READ LOCK operations. • replication client • replication slave • select • show databases • show view • trigger • update For more information about these privileges, see User Account Management in the MariaDB documentation. Note Although you can delete the master user on a DB instance, we don't recommend doing so. To recreate the master user, use the ModifyDBInstance API or the modify-db-instance AWS command line tool and specify a new master user password with the appropriate parameter. If the master user does not exist in the instance, the master user is created with the specified password. To provide management services for each DB instance, the rdsadmin user is created when the DB instance is created. Attempting to drop, rename, change the password for, or change privileges for the rdsadmin account results in an error. To allow management of the DB instance, the standard kill and kill_query commands have been restricted. The Amazon RDS commands mysql.rds_kill, mysql.rds_kill_query, and mysql.rds_kill_query_id are provided for use in MariaDB and also MySQL so that you can terminate user sessions or queries on DB instances. API Version 2014-10-31 426 Amazon Relational Database Service User Guide SSL Support Using SSL with a MariaDB DB Instance Amazon RDS supports Secure Sockets Layer (SSL) connections with DB instances running the MariaDB database engine. Amazon RDS creates an SSL certificate and installs the certificate on the DB instance when Amazon RDS provisions the instance. These certificates are signed by a certificate authority. The SSL certificate includes the DB instance endpoint as the Common Name (CN) for the SSL certificate to guard against spoofing attacks. The public key is stored at https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem. MariaDB uses yaSSL for secure connections in the following versions: • MariaDB version 10.1.26 and earlier 10.1 versions • MariaDB version 10.0.32 and earlier 10.0 versions MariaDB uses OpenSSL for secure connections in the following versions: • MariaDB 10.3 versions • MariaDB 10.2 versions • MariaDB version 10.1.31 and later 10.1 versions • MariaDB version 10.0.34 and later 10.0 versions Amazon RDS for MariaDB supports Transport Layer Security (TLS) versions 1.0, 1.1, and 1.2. The following table shows the TLS support for MySQL versions. MariaDB Version TLS 1.0 TLS 1.1 TLS 1.2 MariaDB 10.3 Supported Supported Supported MariaDB 10.2 Supported Supported Supported MariaDB 10.1 Supported Supported for 10.1.31 and later 10.1 versions Supported for 10.1.31 and later 10.1 versions MariaDB 10.0 Supported Supported for 10.0.34 and later 10.0 versions Supported for 10.0.34 and later 10.0 versions To encrypt connections using the default mysql client, launch the mysql client using the --ssl-ca parameter to reference the public key, as shown in the examples following. The following example shows how to launch the client using the --ssl-ca parameter for MariaDB 10.2 and later. mysql -h myinstance.c9akciq32.rds-us-east-1.amazonaws.com --ssl-ca=[full path]rds-combined-ca-bundle.pem --ssl-mode=REQUIRED The following example shows how to launch the client using the --ssl-ca parameter for MariaDB 10.1 and earlier. mysql -h myinstance.c9akciq32.rds-us-east-1.amazonaws.com --ssl-ca=[full path]rds-combined-ca-bundle.pem --ssl-verify-server-cert API Version 2014-10-31 427 Amazon Relational Database Service User Guide Cache Warming You can require SSL connections for specific users accounts. For example, you can use one of the following statements, depending on your MariaDB version, to require SSL connections on the user account encrypted_user. For MariaDB 10.2 and later, use the following statement. ALTER USER 'encrypted_user'@'%' REQUIRE SSL; For MariaDB 10.1 and earlier, use the following statement. GRANT USAGE ON *.* TO 'encrypted_user'@'%' REQUIRE SSL; For more information on SSL connections with MariaDB, see SSL Overview in the MariaDB documentation. Cache Warming InnoDB (version 10.2 and later) and XtraDB (versions 10.0 and 10.1) cache warming can provide performance gains for your MariaDB DB instance by saving the current state of the buffer pool when the DB instance is shut down, and then reloading the buffer pool from the saved information when the DB instance starts up. This approach bypasses the need for the buffer pool to "warm up" from normal database use and instead preloads the buffer pool with the pages for known common queries. For more information on cache warming, see Dumping and restoring the buffer pool in the MariaDB documentation. Cache warming is enabled by default on MariaDB 10.2 and higher DB instances. To enable it, set the innodb_buffer_pool_dump_at_shutdown and innodb_buffer_pool_load_at_startup parameters to 1 in the parameter group for your DB instance. Changing these parameter values in a parameter group affects all MariaDB DB instances that use that parameter group. To enable cache warming for specific MariaDB DB instances, you might need to create a new parameter group for those DB instances. For information on parameter groups, see Working with DB Parameter Groups (p. 165). Cache warming primarily provides a performance benefit for DB instances that use standard storage. If you use PIOPS storage, you don't commonly see a significant performance benefit. Important If your MariaDB DB instance doesn't shut down normally, such as during a failover, then the buffer pool state isn't saved to disk. In this case, MariaDB loads whatever buffer pool file is available when the DB instance is restarted. No harm is done, but the restored buffer pool might not reflect the most recent state of the buffer pool prior to the restart. To ensure that you have a recent state of the buffer pool available to warm the cache on startup, we recommend that you periodically dump the buffer pool "on demand." You can dump or load the buffer pool on demand. You can create an event to dump the buffer pool automatically and at a regular interval. For example, the following statement creates an event named periodic_buffer_pool_dump that dumps the buffer pool every hour. CREATE EVENT periodic_buffer_pool_dump ON SCHEDULE EVERY 1 HOUR DO CALL mysql.rds_innodb_buffer_pool_dump_now(); For more information, see Events in the MariaDB documentation. API Version 2014-10-31 428 Amazon Relational Database Service User Guide Dumping and Loading the Buffer Pool on Demand Dumping and Loading the Buffer Pool on Demand You can save and load the cache on demand using the following stored procedures: • To dump the current state of the buffer pool to disk, call the mysql.rds_innodb_buffer_pool_dump_now (p. 703) stored procedure. • To load the saved state of the buffer pool from disk, call the mysql.rds_innodb_buffer_pool_load_now (p. 703) stored procedure. • To cancel a load operation in progress, call the mysql.rds_innodb_buffer_pool_load_abort (p. 703) stored procedure. Database Parameters for MariaDB By default, a MariaDB DB instance uses a DB parameter group that is specific to a MariaDB database. This parameter group contains some but not all of the parameters contained in the Amazon RDS DB parameter groups for the MySQL database engine. It also contains a number of new, MariaDB-specific parameters. For more information on the parameters available for the Amazon RDS MariaDB DB engine, see Parameters for MariaDB (p. 468). Common DBA Tasks for MariaDB Killing sessions or queries, skipping replication errors, working with InnoDB (version 10.2 and later) and XtraDB (versions 10.0 and 10.1) tablespaces to improve crash recovery times, and managing the global status history are common DBA tasks you might perform in a MariaDB DB instance. You can handle these tasks just as in an Amazon RDS MySQL DB instance, as described in Common DBA Tasks for MySQL DB Instances (p. 678). The crash recovery instructions there refer to the MySQL InnoDB engine, but they are applicable to a MariaDB instance running InnoDB or XtraDB as well. Local Time Zone for MariaDB DB Instances By default, the time zone for an RDS MariaDB DB instance is Universal Time Coordinated (UTC). You can set the time zone for your DB instance to the local time zone for your application instead. To set the local time zone for a DB instance, set the time_zone parameter in the parameter group for your DB instance to one of the supported values listed later in this section. When you set the time_zone parameter for a parameter group, all DB instances and Read Replicas that are using that parameter group change to use the new local time zone. For information on setting parameters in a parameter group, see Working with DB Parameter Groups (p. 165). After you set the local time zone, all new connections to the database reflect the change. If you have any open connections to your database when you change the local time zone, you won't see the local time zone update until after you close the connection and open a new connection. You can set a different local time zone for a DB instance and one or more of its Read Replicas. To do this, use a different parameter group for the DB instance and the replica or replicas and set the time_zone parameter in each parameter group to a different local time zone. If you are replicating across regions, then the replication master DB instance and the Read Replica use different parameter groups (parameter groups are unique to a region). To use the same local time zone for each instance, you must set the time_zone parameter in the instance's and Read Replica's parameter groups. API Version 2014-10-31 429 Amazon Relational Database Service User Guide Local Time Zone When you restore a DB instance from a DB snapshot, the local time zone is set to UTC. You can update the time zone to your local time zone after the restore is complete. If you restore a DB instance to a point in time, then the local time zone for the restored DB instance is the time zone setting from the parameter group of the restored DB instance. You can set your local time zone to one of the following values. Africa/Cairo Asia/Bangkok Australia/Darwin Africa/Casablanca Asia/Beirut Australia/Hobart Africa/Harare Asia/Calcutta Australia/Perth Africa/Monrovia Asia/Damascus Australia/Sydney Africa/Nairobi Asia/Dhaka Brazil/East Africa/Tripoli Asia/Irkutsk Canada/Newfoundland Africa/Windhoek Asia/Jerusalem Canada/Saskatchewan America/Araguaina Asia/Kabul Europe/Amsterdam America/Asuncion Asia/Karachi Europe/Athens America/Bogota Asia/Kathmandu Europe/Dublin America/Caracas Asia/Krasnoyarsk Europe/Helsinki America/Chihuahua Asia/Magadan Europe/Istanbul America/Cuiaba Asia/Muscat Europe/Kaliningrad America/Denver Asia/Novosibirsk Europe/Moscow America/Fortaleza Asia/Riyadh Europe/Paris America/Guatemala Asia/Seoul Europe/Prague America/Halifax Asia/Shanghai Europe/Sarajevo America/Manaus Asia/Singapore Pacific/Auckland America/Matamoros Asia/Taipei Pacific/Fiji America/Monterrey Asia/Tehran Pacific/Guam America/Montevideo Asia/Tokyo Pacific/Honolulu America/Phoenix Asia/Ulaanbaatar Pacific/Samoa America/Santiago Asia/Vladivostok US/Alaska America/Tijuana Asia/Yakutsk US/Central Asia/Amman Asia/Yerevan US/Eastern Asia/Ashgabat Atlantic/Azores US/East-Indiana Asia/Baghdad Australia/Adelaide US/Pacific Asia/Baku Australia/Brisbane UTC API Version 2014-10-31 430 Amazon Relational Database Service User Guide Creating a DB Instance Running MariaDB Creating a DB Instance Running the MariaDB Database Engine The basic building block of Amazon RDS is the DB instance. The DB instance is where you create your MariaDB databases. Important You must complete the tasks in the Setting Up for Amazon RDS (p. 5) section before you can create or connect to a DB instance. For an example that walks you through the process of creating and connecting to a sample DB instance, see Creating a MariaDB DB Instance and Connecting to a Database on a MariaDB DB Instance (p. 10). AWS Management Console To launch a MariaDB DB instance 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. In the top right corner of the AWS Management Console, choose the region in which you want to create the DB instance. 3. In the navigation pane, choose Instances. If the navigation pane is closed, choose the menu icon at the top left to open it. 4. Choose Create database to open the Select engine page. API Version 2014-10-31 431 Amazon Relational Database Service User Guide AWS Management Console 5. Choose MariaDB, and then choose Next. 6. The Choose use case page asks if you are planning to use the DB instance you are creating for production. If you are, choose Production - MariaDB. If you choose Production - MariaDB, the following are preselected in a later step: • Multi-AZ failover option • Provisioned IOPS storage option • Enable deletion protection option We recommend these features for any production environment. 7. Choose Next to continue. The Specify DB details page appears. On the Specify DB details page, specify your DB instance information. For information about each setting, see Settings for MariaDB DB Instances (p. 436). API Version 2014-10-31 432 Amazon Relational Database Service User Guide AWS Management Console API Version 2014-10-31 433 Amazon Relational Database Service User Guide CLI 8. Choose Next to continue. On the Configure advanced settings page, provide additional information that Amazon RDS needs to launch the DB instance. For information about each setting, see Settings for MySQL DB Instances (p. 592). 9. Choose Create database. 10. On the final page, choose View DB instance details. On the RDS console, the details for the new DB instance appear. The DB instance has a status of creating until the DB instance is created and ready for use. When the state changes to available, you can connect to the DB instance. Depending on the DB instance class and storage allocated, it could take several minutes for the new instance to be available. CLI To create a MariaDB DB instance by using the AWS CLI, call the create-db-instance command with the parameters below. For information about each setting, see Settings for MariaDB DB Instances (p. 436). • --db-instance-identifier • --db-instance-class • --db-security-groups • --db-subnet-group • --engine • --master-user-name • --master-user-password • --allocated-storage • --backup-retention-period Note If you require a specific minor version of MariaDB, include the --engine-version parameter. API Version 2014-10-31 434 Amazon Relational Database Service User Guide API Example The following command creates a MariaDB instance named mydbinstance. For Linux, OS X, or Unix: aws rds create-db-instance \ --db-instance-identifier mydbinstance \ --db-instance-class db.m4.xlarge \ --engine mariadb \ --allocated-storage 20 \ --master-username masteruser \ --master-user-password masteruserpassword \ --backup-retention-period 3 For Windows: aws rds create-db-instance ^ --db-instance-identifier mydbinstance ^ --db-instance-class db.m4.xlarge ^ --engine mariadb ^ --allocated-storage 20 ^ --master-username masteruser ^ --master-user-password masteruserpassword ^ --backup-retention-period 3 This command should produce output that begins with information that is similar to the following: DBINSTANCE 20 True 3 rds-ca-2015 False arn:aws:rds:us-east-1:1234567890:db:mydbinstance db.m4.xlarge mydbinstance creating 0 **** mariadb 10.1.26 API To create a MariaDB DB instance by using the Amazon RDS API, call the CreateDBInstance action with the parameters below. For information about each setting, see Settings for MariaDB DB Instances (p. 436). • AllocatedStorage • BackupRetentionPeriod • DBInstanceClass • DBInstanceIdentifier • DBSecurityGroups • DBSubnetGroup • Engine • MasterUsername • MasterUserPassword Note If you require a specific minor version of MariaDB, include the EngineVersion parameter. Example https://rds.us-west-2.amazonaws.com/ ?Action=CreateDBInstance API Version 2014-10-31 435 Amazon Relational Database Service User Guide Available Settings &AllocatedStorage=20 &BackupRetentionPeriod=3 &DBInstanceClass=db.m4.xlarge &DBInstanceIdentifier=mydbinstance &DBName=mydatabase &DBSecurityGroups.member.1=mysecuritygroup &DBSubnetGroup=mydbsubnetgroup &Engine=mariadb &MasterUserPassword=masteruserpassword &MasterUsername=masterawsuser &Version=2014-10-31 &X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIADQKE4SARGYLE/20140213/us-west-2/rds/aws4_request &X-Amz-Date=20140213T162136Z &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date &X-Amz-Signature=8052a76dfb18469393c5f0182cdab0ebc224a9c7c5c949155376c1c250fc7ec3 Settings for MariaDB DB Instances The following table contains details about settings that you choose when you create a Maria DB instance. Setting Setting Description Allocated storage The amount of storage to allocate for your DB instance (in gigabytes). In some cases, allocating a higher amount of storage for your DB instance than the size of your database can improve I/O performance. For more information, see DB instance storage (p. 101). Auto minor version upgrade Enable auto minor version upgrade to enable your DB instance to receive minor DB engine version upgrades automatically when they become available. Availability zone The availability zone for your DB instance. Use the default value of No Preference unless you want to specify an Availability Zone. For more information, see Regions and Availability Zones (p. 99). Backup retention period The number of days that you want automatic backups of your DB instance to be retained. For any non-trivial DB instance, you should set this value to 1 or greater. For more information, see Working With Backups (p. 202). Backup window The time period during which Amazon RDS automatically takes a backup of your DB instance. Unless you have a specific time that you want to have your database backup, use the default of No Preference. For more information, see Working With Backups (p. 202). Copy Tags To Snapshots Select this option to copy any DB instance tags to a DB snapshot when you create a snapshot. For more information, see Tagging Amazon RDS Resources (p. 134). API Version 2014-10-31 436 Amazon Relational Database Service User Guide Available Settings Setting Setting Description Database name The name for the database on your DB instance. The name must contain 1 to 64 alpha-numeric characters. If you do not provide a name, Amazon RDS does not create a database on the DB instance you are creating. To create additional databases on your DB instance, connect to your DB instance and use the SQL command CREATE DATABASE. For more information, see Connecting to a DB Instance Running the MariaDB Database Engine (p. 440). Database port The port that you want to access the DB instance through. MariaDB installations default to port 3306. If you use a DB security group with your DB instance, this must be the same port value you provided when creating the DB security group. The firewalls at some companies block connections to the default MariaDB port. If your company firewall blocks the default port, choose another port for your DB instance. Deletion protection Enable deletion protection to prevent your DB instance from being deleted. If you create a production DB instance with the AWS Management Console, deletion protection is enabled by default. For more information, see Deleting a DB Instance (p. 131). DB engine version The version of MariaDB that you want to use. DB instance class The configuration for your DB instance. If possible, choose an instance class large enough that a typical query working set can be held in memory. When working sets are held in memory the system can avoid writing to disk, and this improves performance. For more information, see DB Instance Class (p. 80). DB instance identifier The name for your DB instance. Your DB instance identifier can contain up to 63 alphanumeric characters, and must be unique for your account in the region you chose. You can add some intelligence to the name, such as including the region you chose, for example mariadb-instance1. DB parameter group A parameter group for your DB instance. You can choose the default parameter group or you can create a custom parameter group. For more information, see Working with DB Parameter Groups (p. 165). Encryption Enable Encryption to enable encryption at rest for this DB instance. For more information, see Encrypting Amazon RDS Resources (p. 377). API Version 2014-10-31 437 Amazon Relational Database Service User Guide Available Settings Setting Setting Description Enhanced monitoring Enable enhanced monitoring to gather metrics in real time for the operating system that your DB instance runs on. For more information, see Enhanced Monitoring (p. 250). License model MariaDB has only one license model, general-publiclicense the general license agreement for MariaDB. Log exports Select the types of MariaDB database log files to generate. For more information, see MariaDB Database Log Files (p. 301). Maintenance window The 30 minute window in which pending modifications to your DB instance are applied. If the time period doesn't matter, choose No Preference. For more information, see The Amazon RDS Maintenance Window (p. 118). Master username The name that you use as the master user name to log on to your DB Instance. For more information, and a list of the default privileges for the master user, see MariaDB Security on Amazon RDS (p. 425). Master password The password for your master user account. The password must contain from 8 to 41 printable ASCII characters (excluding /,", a space, and @). Multi-AZ deployment Create replica in different zone to create a standby mirror of your DB instance in another Availability Zone for failover support. We recommend Multi-AZ for production workloads to maintain high availability. For development and testing, you can choose No. For more information, see High Availability (Multi-AZ) for Amazon RDS (p. 107). Option group An option group for your DB instance. You can choose the default option group or you can create a custom option group. For more information, see Working with Option Groups (p. 152). Public accessibility Yes to give your DB instance a public IP address. This means that it is accessible outside the VPC (the DB instance also needs to be in a public subnet in the VPC). Choose No if you want the DB instance to only be accessible from inside the VPC. For more information, see Hiding a DB Instance in a VPC from the Internet (p. 410). API Version 2014-10-31 438 Amazon Relational Database Service User Guide Related Topics Setting Setting Description Storage type The storage type for your DB instance. For more information, see Amazon RDS Storage Types (p. 101). Subnet group This setting depends on the platform you are on. If you are a new customer to AWS, choose default, which is the default DB subnet group that was created for your account. If you are creating a DB instance on the previous E2-Classic platform and you want your DB instance in a specific VPC, choose the DB subnet group you created for that VPC. Virtual Private Cloud (VPC) This setting depends on the platform you are on. If you are a new customer to AWS, choose the default VPC shown. If you are creating a DB instance on the previous E2-Classic platform that does not use a VPC, choose Not in VPC. For more information, see Amazon Virtual Private Cloud (VPCs) and Amazon RDS (p. 400). VPC security groups If you are a new customer to AWS, choose Create new VPC security group. Otherwise, choose Select existing VPC security groups, and select security groups you previously created. When you choose Create new VPC security group in the RDS console, a new security group is created with an inbound rule that allows access to the DB instance from the IP address detected in your browser. For more information, see Working with DB Security Groups (EC2-Classic Platform) (p. 387). Related Topics • Tutorial: Create an Amazon VPC for Use with an Amazon RDS DB Instance (p. 415) • Connecting to a DB Instance Running the MariaDB Database Engine (p. 440) • Modifying a DB Instance Running the MariaDB Database Engine (p. 443) • Deleting a DB Instance (p. 131) API Version 2014-10-31 439 Amazon Relational Database Service User Guide Connecting to a DB Instance Running MariaDB Connecting to a DB Instance Running the MariaDB Database Engine Once Amazon RDS provisions your DB instance, you can use any standard MariaDB client application or utility to connect to the instance. In the connection string, you specify the DNS address from the DB instance endpoint as the host parameter, and specify the port number from the DB instance endpoint as the port parameter. You can use the AWS Management Console, the AWS CLI describe-db-instances command, or the Amazon RDS API DescribeDBInstances action to list the details of an Amazon RDS DB instance, including its endpoint. To find the endpoint for a MariaDB instance in the AWS Management Console: 1. Open the RDS console and then choose Instances to display a list of your DB instances. 2. Click the MariaDB DB instance name to display its details. 3. Scroll to the Connect section and copy the endpoint. Also, note the port number. You need both the endpoint and the port number to connect to the DB instance. If an endpoint value is mariadb-instance1.123456789012.useast-1.rds.amazonaws.com:3306, then you specify the following values in a MariaDB connection string: • For host or host name, specify mariadb-instance1.123456789012.useast-1.rds.amazonaws.com • For port, specify 3306 You can connect to an Amazon RDS MariaDB DB instance by using tools like the mysql command line utility. For more information on using the mysql utility, go to mysql Command-line Client in the MariaDB documentation. One GUI-based application you can use to connect is HeidiSQL; for more information, go to the Download HeidiSQL page. Two common causes of connection failures to a new DB instance are the following: API Version 2014-10-31 440 Amazon Relational Database Service User Guide Connecting from the mysql Utility • The DB instance was created using a security group that does not authorize connections from the device or Amazon EC2 instance where the MariaDB application or utility is running. If the DB instance was created in an Amazon VPC, it must have a VPC security group that authorizes the connections. If the DB instance was created outside of a VPC, it must have a DB security group that authorizes the connections. • The DB instance was created using the default port of 3306, and your company has firewall rules blocking connections to that port from devices in your company network. To fix this failure, recreate the instance with a different port. You can use SSL encryption on connections to an Amazon RDS MariaDB DB instance. For information, see Using SSL with a MariaDB DB Instance (p. 427). Connecting from the mysql Utility To connect to a DB instance using the mysql utility, type the following command at a command prompt on a client computer to connect to a database on a MariaDB DB instance. Substitute the DNS name (endpoint) for your DB instance for , the master user name you used for , and provide the master password you used when prompted for a password. mysql -h -P 3306 -u After you enter the password for the user, you will see output similar to the following. Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 272 Server version: 5.5.5-10.0.17-MariaDB-log MariaDB Server Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners. Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. mysql > Connecting with SSL Amazon RDS creates an SSL certificate for your DB instance when the instance is created. If you enable SSL certificate verification, then the SSL certificate includes the DB instance endpoint as the Common Name (CN) for the SSL certificate to guard against spoofing attacks. To connect to your DB instance using SSL, follow these steps: To connect to a DB instance with SSL using the mysql utility 1. 2. Download a root certificate that works for all regions from here. Type the following command at a command prompt to connect to a DB instance with SSL using the mysql utility. For the -h parameter, substitute the DNS name for your DB instance. For the --sslca parameter, substitute the SSL certificate file name as appropriate. mysql -h mariadb-instance1.123456789012.us-east-1.rds.amazonaws.com --ssl-ca=rdsca-2015-root.pem 3. Include the --ssl-verify-server-cert parameter so that the SSL connection verifies the DB instance endpoint against the endpoint in the SSL certificate. For example: API Version 2014-10-31 441 Amazon Relational Database Service User Guide Maximum MariaDB Connections mysql -h mariadb-instance1.123456789012.us-east-1.rds.amazonaws.com --ssl-ca=rdsca-2015-root.pem --ssl-verify-server-cert 4. Type the master user password when prompted. You will see output similar to the following. Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 272 Server version: 5.5.5-10.0.17-MariaDB-log MariaDB Server Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners. Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. mysql > Maximum MariaDB Connections The maximum number of connections allowed to an Amazon RDS MariaDB DB instance is based on the amount of memory available for the DB instance class of the DB instance. A DB instance class with more memory available results in a larger number of connections available. For more information on DB instance classes, see DB Instance Class (p. 80). The connection limit for a DB instance is set by default to the maximum for the DB instance class for the DB instance. You can limit the number of concurrent connections to any value up to the maximum number of connections allowed using the max_connections parameter in the parameter group for the DB instance. For more information, see Working with DB Parameter Groups (p. 165). You can retrieve the maximum number of connections allowed for an Amazon RDS MariaDB DB instance by executing the following query on your DB instance: SELECT @@max_connections; You can retrieve the number of active connections to an Amazon RDS MariaDB DB instance by executing the following query on your DB instance: SHOW STATUS WHERE `variable_name` = 'Threads_connected'; Related Topics • • • • Amazon RDS DB Instances (p. 78) Creating a DB Instance Running the MariaDB Database Engine (p. 431) Controlling Access with Amazon RDS Security Groups (p. 382) Deleting a DB Instance (p. 131) API Version 2014-10-31 442 Amazon Relational Database Service User Guide Modifying a DB Instance Running MariaDB Modifying a DB Instance Running the MariaDB Database Engine You can change the settings of a DB instance to accomplish tasks such as adding additional storage or changing the DB instance class. This topic guides you through modifying an Amazon RDS MariaDB DB instance, and describes the settings for MariaDB instances. We recommend that you test any changes on a test instance before modifying a production instance, so that you fully understand the impact of each change. This is especially important when upgrading database versions. After you modify your DB instance settings, you can apply the changes immediately, or apply them during the next maintenance window for the DB instance. Some modifications cause an interruption by restarting the DB instance. AWS Management Console To modify a MariaDB DB instance 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. 3. In the navigation pane, choose Instances, and then select the DB instance that you want to modify. Choose Instance actions, and then choose Modify. The Modify DB instance page appears. 4. Change any of the settings that you want. For information about each setting, see Settings for MariaDB DB Instances (p. 444). 5. To apply the changes immediately, select Apply immediately. Selecting this option can cause an outage in some cases. For more information, see The Impact of Apply Immediately (p. 113). When all the changes are as you want them, choose Continue and check the summary of modifications. To apply the changes immediately, select Apply immediately. Selecting this option can cause an outage in some cases. For more information, see The Impact of Apply Immediately (p. 113). On the confirmation page, review your changes. If they are correct, choose Modify DB Instance to save your changes. 6. 7. 8. Alternatively, choose Back to edit your changes, or choose Cancel to cancel your changes. CLI To modify a MariaDB DB instance by using the AWS CLI, call the modify-db-instance command. Specify the DB instance identifier, and the parameters for the settings that you want to modify. For information about each parameter, see Settings for MariaDB DB Instances (p. 444). Example The following code modifies mydbinstance by setting the backup retention period to 1 week (7 days). The code disables automatic minor version upgrades by using --no-auto-minor-version-upgrade. To allow automatic minor version upgrades, use --auto-minor-version-upgrade. The changes are applied during the next maintenance window by using --no-apply-immediately. Use --applyimmediately to apply the changes immediately. For more information, see The Impact of Apply Immediately (p. 113). For Linux, OS X, or Unix: aws rds modify-db-instance \ API Version 2014-10-31 443 Amazon Relational Database Service User Guide Available Settings --db-instance-identifier mydbinstance \ --backup-retention-period 7 \ --no-auto-minor-version-upgrade \ --no-apply-immediately For Windows: aws rds modify-db-instance ^ --db-instance-identifier mydbinstance ^ --backup-retention-period 7 ^ --no-auto-minor-version-upgrade ^ --no-apply-immediately API To modify a MariaDB instance by using the Amazon RDS API, call the ModifyDBInstance action. Specify the DB instance identifier, and the parameters for the settings that you want to modify. For information about each parameter, see Settings for MariaDB DB Instances (p. 444). Example The following code modifies mydbinstance by setting the backup retention period to 1 week (7 days) and disabling automatic minor version upgrades. These changes are applied during the next maintenance window. https://rds.amazonaws.com/ ?Action=ModifyDBInstance &ApplyImmediately=false &AutoMinorVersionUpgrade=false &BackupRetentionPeriod=7 &DBInstanceIdentifier=mydbinstance &SignatureMethod=HmacSHA256 &SignatureVersion=4 &Version=2014-10-31 &X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIADQKE4SARGYLE/20131016/us-west-1/rds/aws4_request &X-Amz-Date=20131016T233051Z &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date &X-Amz-Signature=087a8eb41cb1ab0fc9ec1575f23e73757ffc6a1e42d7d2b30b9cc0be988cff97 Settings for MariaDB DB Instances The following table contains details about which settings you can modify, which settings you can't modify, when the changes can be applied, and whether the changes cause downtime for the DB instance. Setting Setting Description When the Change Occurs Downtime Notes Allocated storage The storage, in gigabytes, that you want to allocate for your DB instance. If Apply immediately is set to true, the change occurs immediately. You can't modify allocated storage if the DB instance status is storageoptimization or if the allocated storage for the DB instance has been modified in the last six hours. If Apply immediately is set to false, the change occurs during the next maintenance window. No downtime. Performance may be degraded during the change. API Version 2014-10-31 444 Amazon Relational Database Service User Guide Available Settings Setting Setting Description When the Change Occurs Downtime Notes The maximum storage allowed depends on the storage type. For more information, see DB instance storage (p. 101). Auto minor version upgrade Yes if you want your DB instance to receive minor engine version upgrades automatically when they become available. Upgrades are installed only during your scheduled maintenance window. – – Backup retention period The number of days that automatic backups are retained. To disable automatic backups, set the backup retention period to 0. If Apply immediately is set to true, the change occurs immediately. An outage occurs if you change from 0 to a non-zero value, or from a non-zero value to 0. For more information, see Working With Backups (p. 202). Backup window The time range during which automated backups of your databases occur. The backup window is a start time in Universal Coordinated Time (UTC), and a duration in hours. If Apply immediately is set to false and you change the setting from a non-zero value to another non-zero value, the change is applied asynchronously, as soon as possible. Otherwise, the change occurs during the next maintenance window. The change is applied asynchronously, as soon as possible. – For more information, see Working With Backups (p. 202). Certificate authority The certificate that you want to use. – – Copy tags to snapshots If you have any DB instance tags, this option copies them when you create a DB snapshot. The change occurs immediately. This setting ignores the Apply immediately setting. – The change occurs immediately. This setting ignores the Apply immediately setting. The DB instance is rebooted immediately. For more information, see Tagging Amazon RDS Resources (p. 134). Database port The port that you want to use to access the database. The port value must not match any of the port values specified for options in the option group for the DB instance. API Version 2014-10-31 445 Amazon Relational Database Service User Guide Available Settings Setting Setting Description When the Change Occurs Downtime Notes DB engine version The version of the MariaDB database engine that you want to use. Before you upgrade your production DB instances, we recommend that you test the upgrade process on a test instance to verify its duration and to validate your applications. If Apply immediately is set to true, the change occurs immediately. An outage occurs during this change. For more information, see Upgrading the MariaDB DB Engine (p. 451). DB instance class DB instance identifier DB parameter group The DB instance class that you want to use. For more information, see DB Instance Class (p. 80). The DB instance identifier. This value is stored as a lowercase string. For more information about the effects of renaming a DB instance, see Renaming a DB Instance (p. 122). The parameter group that you want associated with the DB instance. For more information, see Working with DB Parameter Groups (p. 165). If Apply immediately is set to false, the change occurs during the next maintenance window. If Apply immediately is set to true, the change occurs immediately. An outage occurs during this change. If Apply immediately is set to false, the change occurs during the next maintenance window. If Apply immediately is set to true, the change occurs immediately. An outage occurs during this change. The DB instance is rebooted. If Apply immediately is set to false, the change occurs during the next maintenance window. The parameter group change occurs immediately. An outage doesn't occur during this change. When you change the parameter group, changes to some parameters are applied to the DB instance immediately without a reboot. Changes to other parameters are applied only after the DB instance is rebooted. For more information, see Rebooting a DB Instance (p. 125). Deletion protection Enable deletion protection to prevent your DB instance from being deleted. For more information, see Deleting a DB Instance (p. 131). – API Version 2014-10-31 446 – Amazon Relational Database Service User Guide Available Settings Setting Setting Description Enhanced Enable enhanced monitoring to monitoring enable gathering metrics in real time for the operating system that your DB instance runs on. When the Change Occurs Downtime Notes – – For more information, see Enhanced Monitoring (p. 250). Log exports Select the types of MariaDB database If Apply immediately is log files to generate. set to true, the change occurs immediately. For more information, see MariaDB Database Log Files (p. 301). If Apply immediately is set to false, the change occurs during the next maintenance window. Maintenance The time range during which window system maintenance occurs. System maintenance includes upgrades, if applicable. The maintenance window is a start time in Universal Coordinated Time (UTC), and a duration in hours. – The change occurs immediately. This setting ignores the Apply immediately setting. If there are one or more pending actions that cause an outage, and the maintenance window is changed to include the current time, then those pending actions are applied immediately, and an outage occurs. If Apply immediately is set to true, the change occurs immediately. – If you set the window to the current time, there must be at least 30 minutes between the current time and end of the window to ensure any pending changes are applied. For more information, see The Amazon RDS Maintenance Window (p. 118). Multi-AZ Yes to deploy your DB instance deployment in multiple Availability Zones; otherwise, No. New master password For more information, see Regions and Availability Zones (p. 99). If Apply immediately is set to false, the change occurs during the next maintenance window. The password for your master user. The password must contain from 8 to 41 alphanumeric characters. The change is applied asynchronously, as soon as possible. This setting ignores the Apply immediately setting. API Version 2014-10-31 447 – Amazon Relational Database Service User Guide Available Settings Setting Setting Description When the Change Occurs Downtime Notes Option group The option group that you want associated with the DB instance. If Apply immediately is set to true, the change occurs immediately. – For more information, see Working with Option Groups (p. 152). Public Yes to give the DB instance a public accessibility IP address, meaning that it is accessible outside the VPC. To be publicly accessible, the DB instance also has to be in a public subnet in the VPC. No to make the DB instance accessible only from inside the VPC. If Apply immediately is set to false, the change occurs during the next maintenance window. The change occurs immediately. This setting ignores the Apply immediately setting. – The change is applied asynchronously, as soon as possible. This setting ignores the Apply immediately setting. – For more information, see Hiding a DB Instance in a VPC from the Internet (p. 410). Security group The security groups you want associated with the DB instance. For more information, see Working with DB Security Groups (EC2-Classic Platform) (p. 387). API Version 2014-10-31 448 Amazon Relational Database Service User Guide Available Settings Setting Setting Description When the Change Occurs Downtime Notes Storage type The storage type that you want to use. If Apply immediately is set to true, the change occurs immediately. The following changes all result in a brief outage while the process starts. After that, you can use your database normally while the change takes place. For more information, see Amazon RDS Storage Types (p. 101). If Apply immediately is set to false, the change occurs during the next maintenance window. • From General Purpose (SSD) to Magnetic. • From General Purpose (SSD) to Provisioned IOPS (SSD), if the DB instance is single-AZ or if you are using a custom parameter group and the DB instance is a read replica. There is no outage for a multi-AZ DB instance or for the source DB instance of a read replica. • From Magnetic to General Purpose (SSD). • From Magnetic to Provisioned IOPS (SSD). • From Provisioned IOPS (SSD) to Magnetic. • From Provisioned IOPS (SSD) to General Purpose (SSD), if the DB instance is single-AZ or if you are using a custom parameter group and the DB instance is a read replica. There is no outage for a multi-AZ API Version 2014-10-31 449 Amazon Relational Database Service User Guide Related Topics Setting Setting Description When the Change Occurs Downtime Notes DB instance or for the source DB instance of a read replica. Subnet Group The subnet group for the DB instance. You can use this setting to move your DB instance to a different VPC. If your DB instance is not in a VPC, you can use this setting to move your DB instance into a VPC. For more information, see Moving a DB Instance Not in a VPC into a VPC (p. 414). If Apply Immediately is set to true, the change occurs immediately. If Apply Immediately is set to false, the change occurs during the next maintenance window. Related Topics • Rebooting a DB Instance (p. 125) • Connecting to a DB Instance Running the MariaDB Database Engine (p. 440) • Upgrading the MariaDB DB Engine (p. 451) • Deleting a DB Instance (p. 131) API Version 2014-10-31 450 An outage occurs during this change. The DB instance is rebooted. Amazon Relational Database Service User Guide Upgrading the MariaDB DB Engine Upgrading the MariaDB DB Engine When Amazon RDS supports a new version of a database engine, you can upgrade your DB instances to the new version. There are two kinds of upgrades: major version upgrades and minor version upgrades. You must modify the DB instance manually to perform a major version upgrade. For more information about MariaDB supported versions and version management, see MariaDB on Amazon RDS Versions (p. 422). Overview of Upgrading Major version upgrades can contain database changes that are not backward-compatible with existing applications. As a result, Amazon RDS doesn't apply major version upgrades automatically; you must manually modify your DB instance. You should thoroughly test any upgrade before applying it to your production instances. Minor version upgrades that contain database changes that are backward-compatible with the previous version might be applied automatically. Amazon RDS doesn't automatically upgrade an Amazon RDS DB instance until after posting an announcement to the forums announcement page, and sending customers an e-mail notification. Automatic upgrades are scheduled so that you can plan around them, because downtime is required to upgrade a DB instance, even for Multi-AZ instances. Amazon RDS takes two DB snapshots during the upgrade process. The first DB snapshot is of the DB instance before any upgrade changes have been made. If the upgrade doesn't work for your databases, you can restore this snapshot to create a DB instance running the old version. The second DB snapshot is taken when the upgrade completes. Note Amazon RDS only takes DB snapshots if you have set the backup retention period for your DB instance to a number greater than 0. To change your backup retention period, see Modifying a DB Instance Running the MariaDB Database Engine (p. 443). After the upgrade is complete, you can't revert to the previous version of the database engine. If you want to return to the previous version, restore the first DB snapshot taken to create a new DB instance. You control when to upgrade your DB instance to a new version supported by Amazon RDS. This level of control helps you maintain compatibility with specific database versions and test new versions with your application before deploying in production. When you are ready, you can perform version upgrades at the times that best fit your schedule. If your DB instance is using read replication, you must upgrade all of the Read Replicas before upgrading the source instance. If your DB instance is in a Multi-AZ deployment, both the primary and standby DB instances are upgraded. The primary and standby DB instances are upgraded at the same time and you will experience an outage until the upgrade is complete. The time for the outage varies based on your database engine, engine version, and the size of your DB instance. If you are using a custom parameter group, and you perform a major version upgrade, you must specify either a default parameter group for the new DB engine version or create your own custom parameter group for the new DB engine version. Associating the new parameter group with the DB instance requires a customer-initiated database reboot after the upgrade completes. The instance's parameter group status will show pending-reboot if the instance needs to be rebooted to apply the parameter group changes. An instance's parameter group status can be viewed in the AWS console or by using a "describe" call such as describe-db-instances. API Version 2014-10-31 451 Amazon Relational Database Service User Guide AWS Management Console AWS Management Console To upgrade the engine version of a DB instance by using the AWS Management Console 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. 2. 3. In the navigation pane, choose Instances, and then select the DB instance that you want to upgrade. Choose Instance actions, and then choose Modify. The Modify DB Instance page appears. 4. 5. 6. For DB engine version, choose the new version. Choose Continue and check the summary of modifications. To apply the changes immediately, select Apply immediately. Selecting this option can cause an outage in some cases. For more information, see The Impact of Apply Immediately (p. 113). 7. On the confirmation page, review your changes. If they are correct, choose Modify DB Instance to save your changes. Alternatively, choose Back to edit your changes, or choose Cancel to cancel your changes. CLI To upgrade the engine version of a DB instance, use the AWS CLI modify-db-instance command. Specify the following parameters: • --db-instance-identifier – the name of the DB instance. • --engine-version – the version number of the database engine to upgrade to. • --no-apply-immediately – apply changes during the next maintenance window. To apply changes immediately, use --apply-immediately. Example For Linux, OS X, or Unix: aws rds modify-db-instance \ --db-instance-identifier \ --engine-version \ --allow-major-version-upgrade \ --apply-immediately For Windows: aws rds modify-db-instance ^ --db-instance-identifier ^ --engine-version ^ --allow-major-version-upgrade ^ --apply-immediately API To upgrade the engine version of a DB instance, use the ModifyDBInstance action. Specify the following parameters: • DBInstanceIdentifier – the name of the DB instance, for example mydbinstance. • EngineVersion – the version number of the database engine to upgrade to. API Version 2014-10-31 452 Amazon Relational Database Service User Guide Related Topics • ApplyImmediately – whether to apply changes immediately or during the next maintenance window. To apply changes immediately, set the value to true. To apply changes during the next maintenance window, set the value to false. Example https://rds.us-east-1.amazonaws.com/ ?Action=ModifyDBInstance &ApplyImmediately=false &DBInstanceIdentifier=mydbinstance &EngineVersion=new_version &SignatureMethod=HmacSHA256 &SignatureVersion=4 &Version=2013-09-09 &X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIADQKE4SARGYLE/20131016/us-east-1/rds/aws4_request &X-Amz-Date=20131016T233051Z &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date &X-Amz-Signature=087a8eb41cb1ab5f99e81575f23e73757ffc6a1e42d7d2b30b9cc0be988cff97 Related Topics • Maintaining a DB Instance (p. 115) • Applying Updates for a DB Instance (p. 116) API Version 2014-10-31 453 Amazon Relational Database Service User Guide Migrating Data from a MySQL DB Snapshot to a MariaDB DB Instance Migrating Data from a MySQL DB Snapshot to a MariaDB DB Instance You can migrate an Amazon RDS MySQL DB snapshot to a new DB instance running MariaDB 10.1 using the AWS Management Console, AWS CLI, or Amazon RDS API. You must create the DB snapshot from an Amazon RDS DB instance running MySQL 5.6. To learn how to create an RDS MySQL DB snapshot, see Creating a DB Snapshot (p. 210). After you migrate from MySQL to MariaDB, the MariaDB DB instance will be associated with the default DB parameter group and option group. After you restore the DB snapshot, you can associate a custom DB parameter group for the new DB instance. However, a MariaDB parameter group has a different set of configurable system variables. For information about the differences between MySQL and MariaDB system variables, see System Variable Differences Between MariaDB 10.0 and MySQL 5.6. To learn about DB parameter groups, see Working with DB Parameter Groups (p. 165). To learn about option groups, see Working with Option Groups (p. 152). Incompatibilities Between MariaDB and MySQL Incompatibilities between MySQL and MariaDB include the following: • You can't migrate a DB snapshot created with MySQL 5.7 or 5.5 to MariaDB 10.1. • You can't migrate a DB snapshot created with MySQL 5.6.40 or higher 5.6 version to MariaDB. • You can't migrate a DB snapshot created with MySQL 5.7.22 or higher 5.7 version to MariaDB. • You can't migrate a DB snapshot created with MySQL 8.0 to MariaDB. • You can't migrate an encrypted snapshot. • If the source MySQL database uses a SHA256 password hash, you need to reset user passwords that are SHA256 hashed before you can connect to the MariaDB database. The following code shows how to reset a password that is SHA256 hashed: SET old_passwords = 0; UPDATE mysql.user SET plugin = 'mysql_native_password', Password = PASSWORD('new_password') WHERE (User, Host) = ('master_user_name', %); FLUSH PRIVILEGES; • If your RDS master user account uses the SHA-256 password hash, the password has to be reset using the rds modify-db-instance AWS CLI command, ModifyDBInstance API action, or the AWS Management Console. For information about modifying a MariaDB DB instance, see Modifying a DB Instance Running the MariaDB Database Engine (p. 443). • MariaDB doesn't support the Memcached plugin; however, the data used by the Memcached plugin is stored as InnoDB tables. After you migrate a MySQL DB snapshot, you can access the data used by the Memcached plugin using SQL. For more information about the innodb_memcache database, see InnoDB memcached Plugin Internals. AWS Management Console To migrate a MySQL DB snapshot to a MariaDB DB instance 1. Sign in to the AWS Management Console and open the Amazon RDS console at https:// console.aws.amazon.com/rds/. API Version 2014-10-31 454 Amazon Relational Database Service User Guide AWS Management Console 2. In the navigation pane, choose Snapshots, and then select the MySQL DB snapshot you want to migrate. 3. Choose Snapshot Actions, and then choose Migrate Snapshot. The Migrate Database page appears. 4. For Migrate to DB Engine, choose mariadb. 5. On the Migrate Database page, provide additional information that RDS needs to launch the MariaDB DB instance. • DB Engine Version: Choose the version of the MariaDB database engine that you want to use. For more information, see Upgrading the MariaDB DB Engine (p. 451). • DB Instance Class: Choose a DB instance class that has the required storage and capacity for your database, for example db.r3.large. For any production application that requires fast and consistent I/O performance, we recommend Provisioned IOPS storage. For more information, see Provisioned IOPS SSD Storage (p. 103). MariaDB 10.1 does not support previous-generation DB instance classes. For more information, see DB Instance Class (p. 80). • Multi-AZ Deployment: Choose Yes to deploy your DB instance in multiple Availability Zones; otherwise, No. For more information, see Regions and Availability Zones (p. 99). • DB Snapshot ID: Type a name for the DB snapshot identifier. The DB snapshot identifier has the following constraints: • It must contain from 1 to 255 alphanumeric characters or hyphens. • The character must be a letter. • It cannot end with a hyphen or contain two consecutive hyphens. If you are restoring from a shared manual DB snapshot, the DB snapshot identifier must be the Amazon Resource Name (ARN) of the shared DB snapshot. • DB Instance Identifier: Type a name for the DB instance that is unique for your account in the AWS Region where the DB instance will reside. This identifier is used in the endpoint addresses for the instances in your DB instance. The DB instance identifier has the following constraints: • It must contain from 1 to 63 alphanumeric characters or hyphens. • Its first character must be a letter. • It cannot end with a hyphen or contain two consecutive hyphens. • It must be unique for all DB instances for your AWS account, within an AWS Region. • Virtual Private Cloud (VPC): If you have an existing VPC, then you can use that VPC with your MariaDB DB instance by selecting your VPC identifier, for example vpc-a464d1c1. For more information about VPC, see Amazon Virtual Private Cloud (VPCs) and Amazon RDS (p. 400) . Otherwise, you can choose to have Amazon RDS create a VPC for you by selecting Create a new VPC. You cannot create MariaDB instances in the EC2 Classic Network. • Subnet group: If you have an existing subnet group, then you can use that subnet group with your MariaDB DB instance by selecting your subnet group identifier, for example gs-subnet-group1. Otherwise, you can choose to have Amazon RDS create a subnet group for you by selecting Create a new subnet group. • Public accessibility: Choose No to specify that instances in your DB instance can only be accessed by resources inside your VPC. Choose Yes to specify that instances in your DB instance can be accessed by resources on the public network. The default is Yes. • Availability zone: Choose the Availability Zone to host the primary instance for your MariaDB DB instance. To have Amazon RDS Availability Zone for you, choose No Preference. APIchoose Versionan2014-10-31 455 Amazon Relational Database Service User Guide CLI • Database Port: Type the default port to be used when connecting to instances in the DB instance. The default is 3306. You might be behind a corporate firewall that doesn't allow access to default ports such as the MySQL default port 3306. In this case, provide a port value that your corporate firewall allows. • Option Group: Choose the option group that you want associated with the DB instance. For more information, see Working with Option Groups (p. 152). • Encryption: Choose Enable Encryption for your new MariaDB DB instance to be encrypted "at rest." If you choose Enable Encryption, you will be required to choose an AWS KMS encryption key as the Master Key value. • Auto Minor Version Upgrade: Choose Yes if you want to enable your MariaDB DB instance to receive minor MySQL DB engine version upgrades automatically when they become available. The Auto Minor Version Upgrade option only applies to upgrades to MySQL minor engine versions for your MariaDB DB instance. It doesn't apply to regular patches applied to maintain system stability. 6. Choose Migrate. CLI To migrate data from a MySQL DB snapshot to a MariaDB DB instance, use the AWS CLI restore-dbinstance-from-db-snapshot command with the following parameters: • --db-instance-identifier – Name of the DB instance to create from the DB snapshot. • --db-snapshot-identifier – The identifier for the DB snapshot to restore from. • --engine – The database engine to use for the new instance. API Version 2014-10-31 456 Amazon Relational Database Service User Guide API Example For Linux, OS X, or Unix: aws rds restore-db-instance-from-db-snapshot \ --db-instance-identifier newmariadbinstance \ --db-snapshot-identifier mysqlsnapshot \ --engine mariadb For Windows: aws rds restore-db-instance-from-db-snapshot \ --db-instance-identifier newmariadbinstance ^ --db-snapshot-identifier mysqlsnapshot ^ --engine mariadb API To migrate data from a MySQL DB snapshot to a MariaDB DB instance, call the Amazon RDS API action RestoreDBInstanceFromDBSnapshot. Example https://rds.us-west-2.amazonaws.com/ ?Action=RestoreDBInstanceFromDBSnapshot &DBInstanceIdentifier= newmariadbinstance &DBSnapshotIdentifier= mysqlsnapshot &Engine= mariadb &SignatureMethod=HmacSHA256 &SignatureVersion=4 &Version=2013-09-09 &X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIADQKE4SARGYLE/20140428/us-west-2/rds/aws4_request &X-Amz-Date=20140428T232655Z &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date &X-Amz-Signature=78ac761e8c8f54a8c0727f4e67ad0a766fbb0024510b9aa34ea6d1f7df52fe92 Related Topics • Creating a DB Snapshot (p. 210) • System Variable Differences Between MariaDB 10.0 and MySQL 5.6 • Working with DB Parameter Groups (p. 165) • Working with Option Groups (p. 152) API Version 2014-10-31 457 Amazon Relational Database Service User Guide Working with MariaDB Replication Working with MariaDB Replication You usually use Read Replicas to configure replication between Amazon RDS DB instances. For general information about Read Replicas, see Working with Read Replicas of MariaDB, MySQL, and PostgreSQL DB Instances (p. 139). For specific information about working with Read Replicas on Amazon RDS MariaDB, see Working with MariaDB Read Replicas (p. 458). You can also configure replication based on binary log coordinates for a MariaDB DB instance. For MariaDB instances, you can also configure replication based on global transaction IDs (GTIDs), which provides better crash safety. For more information, see Configuring GTID-Based Replication into an Amazon RDS MariaDB DB instance (p. 461). The following are other replication options available with Amazon RDS MariaDB: • You can set up replication between an Amazon RDS MariaDB DB instance and a MySQL or MariaDB instance that is external to Amazon RDS. For information about configuring replication with an external source, see Replication with a MySQL or MariaDB Instance Running External to Amazon RDS (p. 660). • You can configure replication to import databases from a MySQL or MariaDB instance that is external to Amazon RDS, or to export databases to such instances. For more information, see Importing Data to an Amazon RDS MySQL or MariaDB DB Instance with Reduced Downtime (p. 632) and Exporting Data from a MySQL DB Instance by Using Replication (p. 666). For any of these replication options, you can use either row-based replication, statement-based, or mixed replication. Row-based replication only replicates the changed rows that result from a SQL statement. Statement-based replication replicates the entire SQL statement. Mixed replication uses statementbased replication when possible, but switches to row-based replication when SQL statements that are unsafe for statement-based replication are executed. In most cases, mixed replication is recommended. The binary log format of the DB instance determines whether replication is row-based, statement-based, or mixed. For information about setting the binary log format, see Binary Logging Format (p. 305). Topics • Working with MariaDB Read Replicas (p. 458) • Configuring GTID-Based Replication into an Amazon RDS MariaDB DB instance (p. 461) Working with MariaDB Read Replicas This section contains specific information about working with Read Replicas on Amazon RDS MariaDB. For general information about Read Replicas and instructions for using them, see Working with Read Replicas of MariaDB, MySQL, and PostgreSQL DB Instances (p. 139). Topics • Read Replica Configuration with MariaDB (p. 459) • Read Replica Updates with MariaDB (p. 459) • Multi-AZ Read Replica Deployments with MariaDB (p. 459) • Monitoring MariaDB Read Replicas (p. 459) • Starting and Stopping Replication with MariaDB Read Replicas (p. 460) • Deleting Read Replicas with MariaDB (p. 460) • Troubleshooting a MariaDB Read Replica Problem (p. 460) API Version 2014-10-31 458 Amazon Relational Database Service User Guide Working with MariaDB Read Replicas Read Replica Configuration with MariaDB Before a MariaDB DB instance can serve as a replication source, you must enable automatic backups on the source DB instance by setting the backup retention period to a value other than 0. This requirement also applies to a Read Replica that is the source DB instance for another Read Replica. You can create up to five Read Replicas from one DB instance. For replication to operate effectively, each Read Replica should have as the same amount of compute and storage resources as the source DB instance. If you scale the source DB instance, you should also scale the Read Replicas. If a Read Replica is running any version of MariaDB, you can specify it as the source DB instance for another Read Replica. For example, you can create ReadReplica1 from MyDBInstance, and then create ReadReplica2 from ReadReplica1. Updates made to MyDBInstance are replicated to ReadReplica1 and then replicated from ReadReplica1 to ReadReplica2. You can't have more than four instances involved in a replication chain. For example, you can create ReadReplica1 from MySourceDBInstance, and then create ReadReplica2 from ReadReplica1, and then create ReadReplica3 from ReadReplica2, but you can't create a ReadReplica4 from ReadReplica3. If you promote a MariaDB Read Replica that is in turn replicating to other Read Replicas, those Read Replicas remain active. Consider an example where MyDBInstance1 replicates to MyDBInstance2, and MyDBInstance2 replicates to MyDBInstance3. If you promote MyDBInstance2, replication from MyDBInstance1 to MyDBInstance2 no longer occurs, but MyDBInstance2 still replicates to MyDBInstance3. To enable automatic backups on a Read Replica for Amazon RDS MariaDB, first create the Read Replica, then modify the Read Replica to enable automatic backups. You can run multiple concurrent Read Replica create or delete actions that reference the same source DB instance, as long as you stay within the limit of five Read Replicas for the source instance. Read Replica Updates with MariaDB Read Replicas are designed to support read queries, but you might need occasional updates. For example, you might need to add an index to speed the specific types of queries accessing the replica. You can enable updates by setting the read_only parameter to 0 in the DB parameter group for the Read Replica. Multi-AZ Read Replica Deployments with MariaDB You can create a Read Replica from either single-AZ or Multi-AZ DB instance deployments. You use MultiAZ deployments to improve the durability and availability of critical data, but you can't use the Multi-AZ secondary to serve read-only queries. Instead, you can create Read Replicas from high-traffic Multi-AZ DB instances to offload read-only queries. If the source instance of a Multi-AZ deployment fails over to the secondary, any associated Read Replicas automatically switch to use the secondary (now primary) as their replication source. For more information, see High Availability (Multi-AZ) for Amazon RDS (p. 107). You can create a Read Replica as a Multi-AZ DB instance. Amazon RDS creates a standby of your replica in another Availability Zone for failover support for the replica. Creating your Read Replica as a Multi-AZ DB instance is independent of whether the source database is a Multi-AZ DB instance. Monitoring MariaDB Read Replicas For MariaDB Read Replicas, you can monitor replication lag in Amazon CloudWatch by viewing the Amazon RDS ReplicaLag metric. The ReplicaLag metric reports the value of the Seconds_Behind_Master field of the SHOW SLAVE STATUS command. Common causes for replication lag for MariaDB are the following: • A network outage. API Version 2014-10-31 459 Amazon Relational Database Service User Guide Working with MariaDB Read Replicas • Writing to tables with indexes on a Read Replica. If the read_only parameter is not set to 0 on the Read Replica, it can break replication. • Using a nontransactional storage engine such as MyISAM. Replication is only supported for the InnoDB storage engine on MariaDB 10.2 and later and the XtraDB storage engine on MariaDB 10.1 and earlier. When the ReplicaLag metric reaches 0, the replica has caught up to the source DB instance. If the ReplicaLag metric returns -1, then replication is currently not active. ReplicaLag = -1 is equivalent to Seconds_Behind_Master = NULL. Starting and Stopping Replication with MariaDB Read Replicas You can stop and restart the replication process on an Amazon RDS DB instance by calling the system stored procedures mysql.rds_stop_replication (p. 699) and mysql.rds_start_replication (p. 697). You can do this when replicating between two Amazon RDS instances for long-running operations such as creating large indexes. You also need to stop and start replication when importing or exporting databases. For more information, see Importing Data to an Amazon RDS MySQL or MariaDB DB Instance with Reduced Downtime (p. 632) and Exporting Data from a MySQL DB Instance by Using Replication (p. 666). If replication is stopped for more than 30 consecutive days, either manually or due to a replication error, Amazon RDS terminates replication between the master DB instance and all Read Replicas. It does so to prevent increased storage requirements on the master DB instance and long failover times. The Read Replica DB instance is still available. However, replication can't be resumed because the binary logs required by the Read Replica are deleted from the master DB instance after replication is terminated. You can create a new Read Replica for the master DB instance to reestablish replication. Deleting Read Replicas with MariaDB You must explicitly delete Read Replicas, using the same mechanisms for deleting a DB instance. If you delete the source DB instance without deleting the replicas, each replica is promoted to a standalone DB instance. Troubleshooting a MariaDB Read Replica Problem The replication technologies for MariaDB are asynchronous. Because they are asynchronous, occasional BinLogDiskUsage increases on the source DB instance and ReplicaLag on the Read Replica are to be expected. For example, a high volume of write operations to the source DB instance can occur in parallel. In contrast, write operations to the Read Replica are serialized using a single I/O thread, which can lead to a lag between the source instance and Read Replica. For more information about read-only replicas in the MariaDB documentation, go to Replication Overview. You can do several things to reduce the lag between updates to a source DB instance and the subsequent updates to the Read Replica, such as the following: • Sizing a Read Replica to have a storage size and DB instance class comparable to the source DB instance. • Ensuring that parameter settings in the DB parameter groups used by the source DB instance and the Read Replica are compatible. For more information and an example, see the discussion of the max_allowed_packet parameter later in this section. Amazon RDS monitors the replication status of your Read Replicas and updates the Replication State field of the Read Replica instance to Error if replication stops for any reason. An example might be if DML queries run on your Read Replica conflict with the updates made on the source DB instance. You can review the details of the associated error thrown by the MariaDB engine by viewing the Replication Error field. Events that indicate the status of the Read Replica are also generated, API Version 2014-10-31 460 Amazon Relational Database Service User Guide Configuring GTID-Based Replication including RDS-EVENT-0045 (p. 282), RDS-EVENT-0046 (p. 282), and RDS-EVENT-0047 (p. 281). For more information about events and subscribing to events, see Using Amazon RDS Event Notification (p. 278). If a MariaDB error message is returned, review the error in the MariaDB error message documentation. One common issue that can cause replication errors is when the value for the max_allowed_packet parameter for a Read Replica is less than the max_allowed_packet parameter for the source DB instance. The max_allowed_packet parameter is a custom parameter that you can set in a DB parameter group that is used to specify the maximum size of DML code that can be executed on the database. In some cases, the max_allowed_packet parameter value in the DB parameter group associated with a source DB instance is smaller than the max_allowed_packet parameter value in the DB parameter group associated with the source's Read Replica. In these cases, the replication process can throw an error (Packet bigger than 'max_allowed_packet' bytes) and stop replication. You can fix the error by having the source and Read Replica use DB parameter groups with the same max_allowed_packet parameter values. Other common situations that can cause replication errors include the following: • Writing to tables on a Read Replica. If you are creating indexes on a Read Replica, you need to have the read_only parameter set to 0 to create the indexes. If you are writing to tables on the Read Replica, it might break replication. • Using a non-transactional storage engine such as MyISAM. Read Replicas require a transactional storage engine. Replication is only supported for the InnoDB storage engine on MariaDB 10.2 and later and the XtraDB storage engine on MariaDB 10.1 and earlier. • Using unsafe nondeterministic queries such as SYSDATE(). For more information, see Determination of Safe and Unsafe Statements in Binary Logging. If you decide that you can safely skip an error, you can follow the steps described in the section Skipping the Current Replication Error (p. 678). Otherwise, you can delete the Read Replica and create an instance using the same DB instance identifier so that the endpoint remains the same as that of your old Read Replica. If a replication error is fixed, the Replication State changes to replicating. For MariaDB DB instances, in some cases Read Replicas can't be switched to the secondary if some binlog events aren't flushed during the failure. In these cases, you must manually delete and recreate the Read Replicas. You can reduce the chance of this happening by setting the following dynamic variable values: sync_binlog=1, innodb_flush_log_at_trx_commit=1, and innodb_support_xa=1. These settings might reduce performance, so test their impact before implementing the changes in a production environment. Configuring GTID-Based Replication into an Amazon RDS MariaDB DB instance You can set up GTID-based replication from an external MariaDB instance of version 10.0.24 or greater into an Amazon RDS MariaDB DB instance. Be sure to follow these guidelines when you set up an external replication master and a replica on Amazon RDS: • Monitor failover events for the Amazon RDS MariaDB DB instance that is your replica. If a failover occurs, then the DB instance that is your replica might be recreated on a new host with a different network address. For information on how to monitor failover events, see Using Amazon RDS Event Notification (p. 278). • Maintain the binlogs on your master instance until you have verified that they have been applied to the replica. This maintenance ensures that you can restore your master instance in the event of a failure. • Turn on automated backups on your MariaDB DB instance on Amazon RDS. Turning on automated backups ensures that you can restore your replica to a particular point in time if you need to reAPI Version 2014-10-31 461 Amazon Relational Database Service User Guide Configuring GTID-Based Replication synchronize your master and replica. For information on backups and Point-In-Time Restore, see Backing Up and Restoring Amazon RDS DB Instances (p. 201). Note The permissions required to start replication on an Amazon RDS MariaDB DB instance are restricted and not available to your Amazon RDS master user. Because of this, you must use the Amazon RDS mysql.rds_set_external_master_gtid (p. 473) and mysql.rds_start_replication (p. 697) commands to set up replication between your live database and your Amazon RDS MariaDB database. To start replication between an external master instance and a MariaDB DB instance on Amazon RDS, use the following procedure. To Start Replication 1. Make the source MariaDB instance read-only: mysql> FLUSH TABLES WITH READ LOCK; mysql> SET GLOBAL read_only = ON; 2. Get the current GTID of the external MariaDB instance. You can do this by using mysql or the query editor of your choice to run SELECT @@gtid_current_pos;. The GTID is formatted as --. A typical GTID looks something like 0-1234510749-1728. For more information about GTIDs and their component parts, see Global Transaction ID in the MariaDB documentation. 3. Copy the database from the external MariaDB instance to the Amazon RDS MariaDB DB instance using mysqldump. For very large databases, you might want to use the procedure in Importing Data to an Amazon RDS MySQL or MariaDB DB Instance with Reduced Downtime (p. 632). Note Make sure there is not a space between the -p option and the entered password. For Linux, OS X, or Unix: mysqldump \ --databases \ --single-transaction \ --compress \ --order-by-primary \ -u \ -p | mysql \ --host=hostname \ --port=3306 \ -u \ -p For Windows: mysqldump ^ --databases ^ --single-transaction ^ --compress ^ --order-by-primary \ -u \ -p | mysql ^ --host=hostname ^ --port=3306 ^ -u ^ API Version 2014-10-31 462 Amazon Relational Database Service User Guide Configuring GTID-Based Replication -p Use the --host, --user (-u), --port and -p options in the mysql command to specify the host name, user name, port, and password to connect to your Amazon RDS MariaDB DB instance. The host name is the DNS name from the Amazon RDS MariaDB DB instance endpoint, for example myinstance.123456789012.us-east-1.rds.amazonaws.com. You can find the endpoint value in the instance details in the Amazon RDS Management Console. 4. Make the source MariaDB instance writeable again: mysql> SET GLOBAL read_only = OFF; mysql> UNLOCK TABLES; 5. In the Amazon RDS Management Console, add the IP address of the server that hosts the external MariaDB database to the VPC security group for the Amazon RDS MariaDB DB instance. For more information on modifying a VPC security group, go to Security Groups for Your VPC in the Amazon Virtual Private Cloud User Guide. You might also need to configure your local network to permit connections from the IP address of your Amazon RDS MariaDB DB instance, so that it can communicate with your external MariaDB instance. To find the IP address of the Amazon RDS MariaDB DB instance, use the host command: host 6. The host name is the DNS name from the Amazon RDS MariaDB DB instance endpoint. Using the client of your choice, connect to the external MariaDB instance and create a MariaDB user to be used for replication. This account is used solely for replication and must be restricted to your domain to improve security. The following is an example: CREATE USER 'repl_user'@'mydomain.com' IDENTIFIED BY ''; 7. For the external MariaDB instance, grant REPLICATION CLIENT and REPLICATION SLAVE privileges to your replication user. For example, to grant the REPLICATION CLIENT and REPLICATION SLAVE privileges on all databases for the 'repl_user' user for your domain, issue the following command: GRANT REPLICATION CLIENT, REPLICATION SLAVE ON *.* TO 'repl_user'@'mydomain.com' IDENTIFIED BY ''; 8. Make the Amazon RDS MariaDB DB instance the replica. Connect to the Amazon RDS MariaDB DB instance as the master user and identify the external MariaDB database as the replication master by using the mysql.rds_set_external_master_gtid (p. 473) command. Use the GTID that you determined in Step 2. The following is an example: CALL mysql.rds_set_external_master_gtid ('mymasterserver.mydomain.com', 3306, 'repl_user', '', '', 0); 9. On the Amazon RDS MariaDB DB instance, issue the mysql.rds_start_replication (p. 697) command to start replication: CALL mysql.rds_start_replication; API Version 2014-10-31 463 Amazon Relational Database Service User Guide Importing Data into a MariaDB DB Instance Importing Data into a MariaDB DB Instance Following, you can find information about methods to import your MariaDB data to an Amazon RDS DB instance running MariaDB. To do an initial data import into a MariaDB DB instance, you can use the procedures documented in Restoring a Backup into an Amazon RDS MySQL DB Instance (p. 623), as follows: • To move data from an Amazon RDS MySQL DB instance, a MariaDB or MySQL instance in Amazon Elastic Compute Cloud (Amazon EC2) in the same VPC as your Amazon RDS MariaDB DB instance, or a small on-premises instance of MariaDB or MySQL, you can use the procedure documented in Importing Data from a MySQL or MariaDB DB to an Amazon RDS MySQL or MariaDB DB Instance (p. 630). • To move data from a large or production on-premises instance of MariaDB or MySQL, you can use the procedure documented in Importing Data to an Amazon RDS MySQL or MariaDB DB Instance with Reduced Downtime (p. 632). • To move data from an instance of MariaDB or MySQL that is in EC2 in a different VPC than your Amazon RDS MariaDB DB instance, or to move data from any data source that can output delimited text files, you can use the procedure documented in Importing Data From Any Source to a MySQL or MariaDB DB Instance (p. 645). You can also use AWS Database Migration Service (AWS DMS) to import data into an Amazon RDS DB instance. AWS DMS can migrate databases without downtime and, for many database engines, continue ongoing replication until you are ready to switch over to the target database. You can migrate to MariaDB from either the same database engine or a different database engine using AWS DMS. If you are migrating from a different database engine, you can use the AWS Schema Conversion Tool to migrate schema objects that are not migrated by AWS DMS. For more information about AWS DMS, see see What is AWS Database Migration Service. You can configure replication into an Amazon RDS MariaDB DB instance using MariaDB global transaction identifiers (GTIDs) when the external instance is MariaDB version 10.0.24 or greater, or using binary log coordinates for MySQL instances or MariaDB instances on earlier versions than 10.0.24. Note that MariaDB GTIDs are implemented differently than MySQL GTIDs, which are not supported by Amazon RDS. To configure replication into a MariaDB DB instance, you can use the following procedures: • To configure replication into a MariaDB DB instance from an external MySQL instance or an external MariaDB instance running a version prior to 10.0.24, you can use the procedure documented in Replication with a MySQL or MariaDB Instance Running External to Amazon RDS (p. 660). • To configure replication into a MariaDB DB instance from an external MariaDB instance running version 10.0.24 or greater, you can use the procedure documented in Configuring GTID-Based Replication into an Amazon RDS MariaDB DB instance (p. 461). Note The mysql system database contains authentication and authorization information required to log into your DB instance and access your data. Dropping, altering, renaming, or truncating tables, data, or other contents of the mysql database in your DB instance can result in errors and might render the DB instance and your data inaccessible. If this occurs, the DB instance can be restored from a snapshot using the AWS CLI restore-db-instance-from-db-snapshot or recovered using restore-db-instance-to-point-in-time commands. API Version 2014-10-31 464 Amazon Relational Database Service User Guide Options for MariaDB Options for MariaDB Database Engine This appendix describes options, or additional features, that are available for Amazon RDS instances running the MariaDB DB engine. To enable these options, you add them to a custom option group, and then associate the option group with your DB instance. For more information about working with option groups, see Working with Option Groups (p. 152). Amazon RDS supports the following options for MariaDB: Option ID Engine Versions MARIADB_AUDIT_PLUGIN MariaDB 10.0.24 and later MariaDB Audit Plugin Support Amazon RDS supports using the MariaDB Audit Plugin on MariaDB database instances. The MariaDB Audit Plugin records database activity such as users logging on to the database, queries run against the database, and more. The record of database activity is stored in a log file. Audit Plugin Option Settings Amazon RDS supports the following settings for the MariaDB Audit Plugin option. Option Setting Valid Values Default Value Description SERVER_AUDIT_FILE_PATH /rdsdbdata/ log/audit/ /rdsdbdata/ log/audit/ The location of the log file. The log file contains the record of the activity specified in SERVER_AUDIT_EVENTS. For more information, see Viewing and Listing Database Log Files (p. 297) and MariaDB Database Log Files (p. 301). SERVER_AUDIT_FILE_ROTATE_SIZE 1–1000000000 1000000 The size in bytes that when reached, causes the file to rotate. For more information, see Log File Size (p. 305). SERVER_AUDIT_FILE_ROTATIONS 0–100 9 The number of log rotations to save. For more information, see Log File Size (p. 305) and Downloading a Database Log File (p. 297). SERVER_AUDIT_EVENTS CONNECT, QUERY, TABLE The types of activity to record in the log. Installing the MariaDB Audit Plugin is itself logged. CONNECT, QUERY • 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. • TABLE: Log tables affected by queries when the queries are run against the database. For MariaDB, CONNECT, QUERY, and TABLE are supported. API Version 2014-10-31 465 Amazon Relational Database Service User Guide MariaDB Audit Plugin Support Option Setting Valid Values Default Value Description For MySQL, CONNECT and QUERY are supported. SERVER_AUDIT_INCL_USERS Multiple commaseparated values None Include only activity from the specified users. By default, activity is recorded for all users. If a user is specified in both SERVER_AUDIT_EXCL_USERS and SERVER_AUDIT_INCL_USERS, then activity is recorded for the user. SERVER_AUDIT_EXCL_USERS Multiple commaseparated values None Exclude activity from the specified users. By default, activity is recorded for all users. If a user is specified in both SERVER_AUDIT_EXCL_USERS and SERVER_AUDIT_INCL_USERS, then activity is recorded for the user. The rdsadmin user queries the database every second to check the health of the database. Depending on your other settings, this activity can possibly cause the size of your log file to grow very large, very quickly. If you don't need to record this activity, add the rdsadmin user to the SERVER_AUDIT_EXCL_USERS list. Note CONNECT activity is always recorded for all users, even if the user is speci