Amazon Relational

Database Service
User Guide

Amazon Relational Database Service: User Guide

Copyright © Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
 Amazon Relational Database Service User Guide

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
AWS Regions and Availability Zones ............................................................................................. 2
Security .................................................................................................................................... 2
Monitoring an Amazon RDS DB instance ....................................................................................... 3
How to work with Amazon RDS ................................................................................................... 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? .............................................................................................................................. 3
Getting started .................................................................................................................. 4
Database engine–Specific topics ........................................................................................... 4
DB instances .............................................................................................................................. 5
DB instance classes .................................................................................................................... 7
DB instance class types ....................................................................................................... 7
Supported DB engines ........................................................................................................ 8
Determining DB instance class support in AWS Regions ......................................................... 17
Changing your DB instance class ........................................................................................ 20
Configuring the processor ................................................................................................. 20
Hardware specifications ..................................................................................................... 33
DB instance storage .................................................................................................................. 40
Storage types .................................................................................................................. 40
General Purpose SSD storage ............................................................................................. 40
Provisioned IOPS storage .................................................................................................. 42
Magnetic storage .............................................................................................................. 44
Monitoring storage performance ........................................................................................ 44
Factors that affect storage performance .............................................................................. 45
Regions, Availability Zones, and Local Zones ................................................................................ 49
AWS Regions ................................................................................................................... 49
Availability Zones ............................................................................................................. 52
Local Zones ..................................................................................................................... 52
High availability (Multi-AZ) ........................................................................................................ 53
Modifying a DB instance to be a Multi-AZ deployment .......................................................... 54
Failover process for Amazon RDS ....................................................................................... 54
DB instance billing for Amazon RDS ........................................................................................... 57
On-Demand DB instances .................................................................................................. 58
Reserved DB instances ...................................................................................................... 59
Setting up ....................................................................................................................................... 67
Sign up for AWS ...................................................................................................................... 67
Create an IAM user ................................................................................................................... 67
Determine requirements ............................................................................................................ 69
Provide access to your DB instance in your VPC by creating a security group ..................................... 70
Getting started ................................................................................................................................ 73
Creating a MariaDB DB instance and connecting to a database ....................................................... 73
Creating a MariaDB DB instance ......................................................................................... 73
Connecting to a database on a DB instance running MariaDB ................................................. 77
Deleting a DB instance ...................................................................................................... 79
Creating a SQL Server DB instance and connecting to it ................................................................ 80
Creating a sample SQL Server DB instance .......................................................................... 80
Connecting to your sample DB instance .............................................................................. 83
Exploring your sample DB instance ..................................................................................... 84
Deleting your sample DB instance ...................................................................................... 85

iii
 Amazon Relational Database Service User Guide

Creating a MySQL DB instance and connecting to a database ......................................................... 86

Creating a MySQL DB instance ........................................................................................... 86
Connecting to a database on a DB instance running MySQL ................................................... 90
Deleting a DB instance ...................................................................................................... 92
Creating an Oracle DB instance and connecting to a database ........................................................ 93
Creating a sample Oracle DB instance ................................................................................. 93
Connecting to your sample DB instance .............................................................................. 97
Deleting your sample DB instance ...................................................................................... 99
Creating a PostgreSQL DB instance and connecting to a database .................................................. 99
Creating a PostgreSQL DB instance .................................................................................... 99
Connecting to a PostgreSQL DB instance ........................................................................... 103
Deleting a DB instance .................................................................................................... 107
Tutorial: Create a web server and an Amazon RDS DB instance ..................................................... 108
Create a DB instance ....................................................................................................... 109
Create a web server ........................................................................................................ 119
Tutorials ........................................................................................................................................ 132
Tutorials in this guide ............................................................................................................. 132
Tutorials in other AWS guides .................................................................................................. 132
Best practices for Amazon RDS ........................................................................................................ 134
Amazon RDS basic operational guidelines .................................................................................. 134
DB instance RAM recommendations .......................................................................................... 135
Using Enhanced Monitoring to identify operating system issues .................................................... 135
Using metrics to identify performance issues ............................................................................. 135
Viewing performance metrics ........................................................................................... 135
Evaluating performance metrics ....................................................................................... 138
Tuning queries .............................................................................................................. 139
Best practices for working with MySQL storage engines ............................................................... 140
Table size ...................................................................................................................... 140
Number of tables ........................................................................................................... 140
Storage engine ............................................................................................................... 141
Best practices for working with MariaDB storage engines ............................................................. 141
Table size ...................................................................................................................... 141
Number of tables ........................................................................................................... 142
Storage engine ............................................................................................................... 142
Best practices for working with Oracle ...................................................................................... 143
Best practices for working with PostgreSQL ............................................................................... 143
Loading data into a PostgreSQL DB instance ...................................................................... 143
Working with the PostgreSQL autovacuum feature ............................................................. 143
Best practices for working with SQL Server ................................................................................ 144
Amazon RDS for SQL Server best practices video ................................................................ 145
Working with DB parameter groups .......................................................................................... 145
Amazon RDS new features and best practices presentation video .................................................. 145
Configuring a DB instance ............................................................................................................... 146
Creating a DB instance ............................................................................................................ 147
Available settings ........................................................................................................... 151
Original console example ................................................................................................ 163
Connecting to a DB instance .................................................................................................... 168
Finding the connection information .................................................................................. 168
Database authentication options ...................................................................................... 171
Encrypted connections .................................................................................................... 172
Scenarios for accessing a DB instance ................................................................................ 172
Connecting to a DB instance running a specific DB engine ................................................... 172
Managing connections with RDS Proxy .............................................................................. 173
Managing connections with RDS Proxy .............................................................................. 173
Working with option groups .................................................................................................... 218
Option groups overview .................................................................................................. 218
Creating an option group ................................................................................................ 220

iv
 Amazon Relational Database Service User Guide

Copying an option group ................................................................................................. 221

Adding an option to an option group ................................................................................ 222
Listing the options and option settings for an option group ................................................. 226
Modifying an option setting ............................................................................................ 227
Removing an option from an option group ........................................................................ 230
Deleting an option group ................................................................................................ 231
Working with parameter groups ............................................................................................... 234
Creating a DB parameter group ........................................................................................ 235
Associating a DB parameter group with a DB instance ......................................................... 237
Modifying parameters in a DB parameter group ................................................................. 238
Resetting parameters in a DB parameter group .................................................................. 240
Copying a DB parameter group ........................................................................................ 242
Listing DB parameter groups ............................................................................................ 244
Viewing parameter values for a DB parameter group .......................................................... 245
Comparing DB parameter groups ...................................................................................... 246
Specifying DB parameters ................................................................................................ 246
Managing a DB instance .................................................................................................................. 251
Stopping a DB instance ........................................................................................................... 252
Benefits ......................................................................................................................... 252
Limitations ..................................................................................................................... 253
Option and parameter group considerations ...................................................................... 253
Public IP address ............................................................................................................ 253
Stopping a DB instance ................................................................................................... 253
Starting a DB instance ............................................................................................................ 255
Modifying a DB instance .......................................................................................................... 256
Apply Immediately setting ............................................................................................... 257
Available settings ........................................................................................................... 257
Maintaining a DB instance ....................................................................................................... 270
Applying updates ........................................................................................................... 272
Maintenance for Multi-AZ deployments ............................................................................. 273
The maintenance window ................................................................................................ 274
Adjusting the maintenance window for a DB instance .......................................................... 275
Upgrading the engine version .................................................................................................. 277
Manually upgrading the engine version ............................................................................. 277
Automatically upgrading the minor engine version ............................................................. 279
Renaming a DB instance .......................................................................................................... 280
Renaming to replace an existing DB instance ..................................................................... 280
Rebooting a DB instance ......................................................................................................... 282
Working with read replicas ...................................................................................................... 284
Overview ....................................................................................................................... 286
Creating a read replica .................................................................................................... 289
Promoting a read replica ................................................................................................. 291
Monitoring read replication .............................................................................................. 294
Creating a read replica in a different AWS Region ............................................................... 296
Tagging RDS resources ............................................................................................................ 305
Overview ....................................................................................................................... 305
Using tags for access control with IAM .............................................................................. 306
Using tags to produce detailed billing reports .................................................................... 306
Adding, listing, and removing tags .................................................................................... 306
Using the AWS Tag Editor ............................................................................................... 309
Copying tags to DB instance snapshots ............................................................................. 309
Tutorial: Use tags to specify which DB instances to stop ...................................................... 310
Enabling backups ........................................................................................................... 312
Working with ARNs ................................................................................................................. 315
Constructing an ARN ....................................................................................................... 315
Getting an existing ARN .................................................................................................. 318
Working with storage .............................................................................................................. 322

v
 Amazon Relational Database Service User Guide

Increasing DB instance storage capacity ............................................................................ 322

Managing capacity automatically with storage autoscaling ................................................... 323
Modifying Provisioned IOPS ............................................................................................. 328
Deleting a DB instance ............................................................................................................ 330
Deletion protection ......................................................................................................... 330
Final snapshots and retained backups ............................................................................... 330
Deleting a DB instance .................................................................................................... 331
Backing up and restoring a DB instance ............................................................................................ 333
Working with backups ............................................................................................................. 334
Backup storage .............................................................................................................. 334
Backup window .............................................................................................................. 334
Backup retention period .................................................................................................. 336
Enabling automated backups ........................................................................................... 336
Retaining automated backups .......................................................................................... 337
Deleting retained automated backups ............................................................................... 339
Disabling automated backups .......................................................................................... 340
Using AWS Backup ......................................................................................................... 341
Unsupported MySQL storage engines ................................................................................ 342
Unsupported MariaDB storage engines .............................................................................. 342
Replicating automated backups to another Region ..................................................................... 344
Enabling cross-Region automated backups ........................................................................ 344
Finding information about replicated backups .................................................................... 345
Point-in-time recovery from a replicated backup ................................................................ 348
Stopping backup replication ............................................................................................ 349
Deleting replicated backups ............................................................................................. 350
.................................................................................................................................... 351
Creating a DB snapshot ........................................................................................................... 352
Restoring from a DB snapshot ................................................................................................. 355
Parameter groups ........................................................................................................... 355
Security groups .............................................................................................................. 355
Option groups ................................................................................................................ 355
Microsoft SQL Server ...................................................................................................... 356
Oracle ........................................................................................................................... 356
Restoring from a snapshot ............................................................................................... 356
Copying a snapshot ................................................................................................................ 358
Limitations ..................................................................................................................... 358
Snapshot retention ......................................................................................................... 358
Copying shared snapshots ............................................................................................... 358
Handling encryption ....................................................................................................... 359
Incremental snapshot copying .......................................................................................... 359
Cross-Region copying ...................................................................................................... 359
Option groups ................................................................................................................ 362
Parameter groups ........................................................................................................... 363
Copying a DB snapshot ................................................................................................... 363
Sharing a snapshot ................................................................................................................. 371
Sharing an encrypted snapshot ........................................................................................ 372
Sharing a snapshot ......................................................................................................... 374
Exporting snapshot data to Amazon S3 ..................................................................................... 379
Limitations ..................................................................................................................... 380
Overview of exporting snapshot data ................................................................................ 380
Setting up access to an S3 bucket .................................................................................... 380
Exporting a snapshot to an S3 bucket ............................................................................... 383
Monitoring snapshot exports ........................................................................................... 385
Canceling a snapshot export ............................................................................................ 386
Troubleshooting PostgreSQL permissions errors ................................................................. 387
File naming convention ................................................................................................... 388
Data conversion ............................................................................................................ 388

vi
 Amazon Relational Database Service User Guide

Point-in-time recovery ............................................................................................................. 395

Deleting a snapshot ................................................................................................................ 398
Deleting a DB snapshot ................................................................................................... 398
Tutorial: Restore a DB instance from a DB snapshot .................................................................... 400
Prerequisites for restoring a DB instance from a DB snapshot ............................................... 400
Restoring a DB instance from a DB snapshot ...................................................................... 401
Modifying a restored DB instance ..................................................................................... 402
Monitoring a DB instance ................................................................................................................ 405
Overview of monitoring .......................................................................................................... 406
Monitoring plan ............................................................................................................. 406
Performance baseline ...................................................................................................... 406
Performance guidelines ................................................................................................... 406
Monitoring tools ............................................................................................................. 407
DB instance status .................................................................................................................. 410
Using Amazon RDS recommendations ....................................................................................... 413
Responding to recommendations ...................................................................................... 415
Using Performance Insights ..................................................................................................... 418
Overview ....................................................................................................................... 418
Enabling and Disabling Performance Insights ..................................................................... 421
Accessing Performance Insights ........................................................................................ 425
Monitoring with the Performance Insights dashboard .......................................................... 427
Customizing the Performance Insights dashboard ............................................................... 450
Retrieving data with the Performance Insights API .............................................................. 460
Metrics published to CloudWatch ..................................................................................... 473
Logging Performance Insights calls by using AWS CloudTrail ................................................ 474
Using Enhanced Monitoring ..................................................................................................... 477
Enhanced Monitoring availability ...................................................................................... 477
Differences between CloudWatch and Enhanced Monitoring metrics ...................................... 477
Setting up and enabling Enhanced Monitoring ................................................................... 477
Viewing Enhanced Monitoring .......................................................................................... 480
Viewing Enhanced Monitoring by using CloudWatch Logs .................................................... 484
Using Amazon RDS event notification ....................................................................................... 493
Amazon RDS event categories and event messages ............................................................. 494
Subscribing to Amazon RDS event notification ................................................................... 500
Listing Amazon RDS event notification subscriptions ........................................................... 502
Modifying an Amazon RDS event notification subscription ................................................... 503
Adding a source identifier to an Amazon RDS event notification subscription .......................... 505
Removing a source identifier from an Amazon RDS event notification subscription ................... 506
Listing the Amazon RDS event notification categories ......................................................... 507
Deleting an Amazon RDS event notification subscription ..................................................... 508
Viewing Amazon RDS events .................................................................................................... 509
.................................................................................................................................... 509
Accessing database logs .......................................................................................................... 510
Viewing and listing database log files ............................................................................... 510
Downloading a database log file ...................................................................................... 510
Watching a database log file ............................................................................................ 512
Publishing to CloudWatch Logs ........................................................................................ 512
Reading log file contents using REST ................................................................................ 512
MariaDB database log files .............................................................................................. 514
Microsoft SQL Server database log files ............................................................................ 522
MySQL database log files ................................................................................................ 525
Oracle database log files ................................................................................................. 533
PostgreSQL database log files .......................................................................................... 540
Monitoring with CloudWatch .................................................................................................... 546
Metrics and dimensions ................................................................................................... 547
Publishing to CloudWatch Logs ................................................................................................ 554
Configuring CloudWatch log integration ............................................................................ 554

vii
 Amazon Relational Database Service User Guide

Viewing DB instance metrics ............................................................................................ 555

Getting CloudWatch and EventBridge events for RDS .................................................................. 558
Overview of events for Amazon RDS ................................................................................. 558
Creating rules to send Amazon RDS events to CloudWatch Events ......................................... 560
Tutorial: Log Amazon RDS instance states .......................................................................... 561
Working with AWS CloudTrail and Amazon RDS ......................................................................... 564
CloudTrail integration with Amazon RDS ........................................................................... 564
Amazon RDS log file entries ............................................................................................ 564
Working with RDS on AWS Outposts ................................................................................................. 568
Prerequisites .......................................................................................................................... 568
Support for Amazon RDS features ............................................................................................ 569
Supported DB instance classes ................................................................................................. 571
Customer-owned IP addresses .................................................................................................. 572
Creating DB instances ............................................................................................................. 574
MariaDB on Amazon RDS ................................................................................................................ 581
Common management tasks .................................................................................................... 581
MariaDB versions .................................................................................................................... 583
Deprecation of MariaDB versions 10.0 and 10.1 .................................................................. 584
MariaDB feature support ......................................................................................................... 585
MariaDB 10.5 support ..................................................................................................... 585
MariaDB 10.4 support ..................................................................................................... 586
MariaDB 10.3 support ..................................................................................................... 586
MariaDB 10.2 support ..................................................................................................... 586
MariaDB 10.1 support ..................................................................................................... 587
MariaDB 10.0 support ..................................................................................................... 587
Features not supported ........................................................................................................... 587
Supported storage engines ...................................................................................................... 588
File size limits ........................................................................................................................ 588
MariaDB security .................................................................................................................... 589
SSL support ........................................................................................................................... 591
Cache warming ...................................................................................................................... 592
Dumping and loading the buffer pool on demand .............................................................. 593
Database parameters .............................................................................................................. 593
Common DBA tasks ................................................................................................................ 593
Local time zone ...................................................................................................................... 594
Connecting to a DB instance running MariaDB ........................................................................... 595
Finding the connection information .................................................................................. 596
Connecting from the mysql utility .................................................................................... 598
Connecting with SSL ....................................................................................................... 599
Troubleshooting ............................................................................................................. 599
Updating applications for new SSL/TLS certificates ..................................................................... 601
Determining whether a client requires certificate verification in order to connect ..................... 601
Updating your application trust store ................................................................................ 602
Example Java code for establishing SSL connections ........................................................... 604
Upgrading the MariaDB DB engine ........................................................................................... 605
Overview ....................................................................................................................... 605
Major version upgrades ................................................................................................... 606
Upgrading a MariaDB DB instance .................................................................................... 607
Automatic minor version upgrades ................................................................................... 607
Migrating data from a MySQL DB snapshot to a MariaDB DB instance ............................................ 610
Incompatibilities between MariaDB and MySQL .................................................................. 610
Performing the migration ................................................................................................ 610
Working with MariaDB replication ............................................................................................. 612
Working with MariaDB read replicas .................................................................................. 612
Configuring GTID-based replication ................................................................................... 620
Importing data into a MariaDB DB instance ............................................................................... 623
Options for MariaDB ............................................................................................................... 623

viii
 Amazon Relational Database Service User Guide

MariaDB Audit Plugin support .......................................................................................... 624

Parameters for MariaDB .......................................................................................................... 627
MariaDB on Amazon RDS SQL reference .................................................................................... 632
mysql.rds_replica_status .................................................................................................. 632
mysql.rds_set_external_master_gtid .................................................................................. 633
mysql.rds_kill_query_id .................................................................................................... 635
Microsoft SQL Server on Amazon RDS .............................................................................................. 637
Common management tasks .................................................................................................... 637
Limits .................................................................................................................................... 639
DB instance class support ........................................................................................................ 641
Security ................................................................................................................................. 642
Compliance programs ............................................................................................................. 643
HIPAA ........................................................................................................................... 643
SSL support ........................................................................................................................... 644
Version support ...................................................................................................................... 644
Version management .............................................................................................................. 646
Database engine patches and versions .............................................................................. 646
Deprecation schedule ...................................................................................................... 646
Feature support ...................................................................................................................... 647
SQL Server 2019 features ................................................................................................ 647
SQL Server 2017 features ................................................................................................ 647
SQL Server 2016 features ................................................................................................ 648
SQL Server 2014 features ................................................................................................ 648
SQL Server 2012 features ................................................................................................ 648
SQL Server 2008 R2 deprecated on Amazon RDS ............................................................... 649
CDC support .......................................................................................................................... 649
Features not supported and features with limited support ........................................................... 650
Multi-AZ deployments ............................................................................................................. 650
Using TDE ............................................................................................................................. 651
Functions and stored procedures .............................................................................................. 651
Local time zone ...................................................................................................................... 653
Supported time zones ..................................................................................................... 654
Licensing SQL Server on Amazon RDS ....................................................................................... 662
Restoring license-terminated DB instances ......................................................................... 662
SQL Server Developer Edition .......................................................................................... 662
Connecting to a DB instance running SQL Server ........................................................................ 663
Connecting to your DB instance with SSMS ........................................................................ 663
Connecting to your DB instance with SQL Workbench/J ...................................................... 665
Security group considerations .......................................................................................... 667
Troubleshooting ............................................................................................................. 668
Updating applications for new SSL/TLS certificates ..................................................................... 669
Determining whether any applications are connecting to your Microsoft SQL Server DB
instance using SSL .......................................................................................................... 669
Determining whether a client requires certificate verification in order to connect ..................... 670
Updating your application trust store ................................................................................ 671
Upgrading the SQL Server DB engine ....................................................................................... 673
Overview ....................................................................................................................... 673
Major version upgrades ................................................................................................... 674
Multi-AZ and in-memory optimization considerations .......................................................... 675
Option and parameter group considerations ...................................................................... 675
Testing an upgrade ......................................................................................................... 676
Upgrading a SQL server DB instance ................................................................................. 676
Upgrading deprecated DB instances before support ends ..................................................... 677
Importing and exporting SQL server databases .......................................................................... 678
Limitations and recommendations .................................................................................... 678
Setting up ..................................................................................................................... 679
Using native backup and restore ...................................................................................... 682

ix
 Amazon Relational Database Service User Guide

Compressing backup files ................................................................................................ 692

Troubleshooting ............................................................................................................. 692
.................................................................................................................................... 693
Importing and exporting SQL Server data using other methods ............................................ 694
Working with SQL Server read replicas ...................................................................................... 703
Configuring read replicas for SQL Server ........................................................................... 703
Read replica limitations with SQL Server ........................................................................... 703
Troubleshooting a SQL Server read replica problem ............................................................ 704
Multi-AZ for SQL Server .......................................................................................................... 705
Adding Multi-AZ to a SQL Server DB instance .................................................................... 706
Notes and recommendations ............................................................................................ 706
Determining the location of the secondary ........................................................................ 708
Migrating to always on AGs ............................................................................................. 709
Additional features for SQL Server ........................................................................................... 710
Using SSL with a SQL Server DB instance .......................................................................... 711
Configuring security protocols and ciphers ......................................................................... 714
Using Windows Authentication with a SQL Server DB instance .............................................. 718
Amazon S3 integration .................................................................................................... 728
Using Database Mail ....................................................................................................... 741
Instance store support for tempdb ................................................................................... 751
Options for SQL Server ........................................................................................................... 753
Listing the available options for SQL Server versions and editions ......................................... 754
Native backup and restore ............................................................................................... 755
Transparent Data Encryption ............................................................................................ 758
SQL Server Audit ............................................................................................................ 761
SQL Server Analysis Services ............................................................................................ 766
SQL Server Integration Services ....................................................................................... 777
SQL Server Reporting Services ......................................................................................... 791
Microsoft Distributed Transaction Coordinator .................................................................... 801
Common DBA tasks for SQL Server .......................................................................................... 813
Accessing the tempdb database ....................................................................................... 814
Analyzing your database workload with SQL Server Tuning Advisor ....................................... 816
Collations and character sets ........................................................................................... 818
Determining a recovery model ......................................................................................... 821
Determining the last failover time .................................................................................... 821
Disabling fast inserts ...................................................................................................... 822
Dropping a SQL Server database ...................................................................................... 822
Renaming a Multi-AZ database ......................................................................................... 822
Resetting the db_owner role password ............................................................................. 823
Restoring license-terminated DB instances ......................................................................... 823
Transitioning a database from OFFLINE to ONLINE ............................................................. 824
Using CDC ..................................................................................................................... 824
Using SQL Server Agent .................................................................................................. 826
Working with SQL Server logs .......................................................................................... 827
Working with trace and dump files ................................................................................... 828
MySQL on Amazon RDS .................................................................................................................. 830
Common management tasks .................................................................................................... 830
MySQL versions ...................................................................................................................... 832
Deprecation of MySQL version 5.6 .................................................................................... 834
Deprecation of MySQL version 5.5 .................................................................................... 835
MySQL features not supported by Amazon RDS ......................................................................... 835
Supported storage engines ...................................................................................................... 836
MySQL security ...................................................................................................................... 837
Password Validation Plugin ...................................................................................................... 838
SSL support ........................................................................................................................... 839
Using memcached and other options with MySQL ...................................................................... 840
InnoDB cache warming ............................................................................................................ 840

x
 Amazon Relational Database Service User Guide

Dumping and loading the buffer pool on demand .............................................................. 841

Local time zone ...................................................................................................................... 841
Known issues and limitations ................................................................................................... 843
Deprecated MySQL versions ..................................................................................................... 843
Connecting to a DB instance running MySQL ............................................................................. 844
Finding the connection information .................................................................................. 844
Connecting from the MySQL client ................................................................................... 847
Connecting with SSL ....................................................................................................... 848
Connecting from MySQL Workbench ................................................................................. 848
Troubleshooting ............................................................................................................. 850
Updating applications for new SSL/TLS certificates ..................................................................... 852
Determining whether any applications are connecting to your MySQL DB instance using SSL ..... 853
Determining whether a client requires certificate verification to connect ................................ 853
Updating your application trust store ................................................................................ 854
Example Java code for establishing SSL connections ........................................................... 855
Upgrading the MySQL DB engine ............................................................................................. 857
Overview ....................................................................................................................... 857
Major version upgrades ................................................................................................... 858
Testing an upgrade ......................................................................................................... 862
Upgrading a MySQL DB instance ...................................................................................... 862
Automatic minor version upgrades ................................................................................... 862
Upgrading with reduced downtime ................................................................................... 864
Upgrading a MySQL DB snapshot ............................................................................................. 867
Importing data into a MySQL DB instance ................................................................................. 869
Overview ....................................................................................................................... 869
Importing data considerations .......................................................................................... 870
Restoring a backup into an Amazon RDS MySQL DB instance ............................................... 875
Importing data from a MySQL or MariaDB DB to a MySQL or MariaDB DB instance ................... 883
Importing data to an Amazon RDS MySQL or MariaDB DB instance with reduced downtime ....... 885
Importing data from any source to a MySQL or MariaDB DB instance ..................................... 898
Working with MySQL replication .............................................................................................. 903
Working with MySQL read replicas .................................................................................... 903
Using GTID-based replication ........................................................................................... 914
Replication with a MySQL or MariaDB instance running external to Amazon RDS ..................... 918
Exporting data from a MySQL DB instance ................................................................................ 925
Prepare an external MySQL database ................................................................................ 925
Prepare the source MySQL DB instance ............................................................................. 926
Copy the database .......................................................................................................... 927
Complete the export ....................................................................................................... 928
Options for MySQL ................................................................................................................. 929
MariaDB Audit Plugin ...................................................................................................... 930
memcached ................................................................................................................... 933
Common DBA tasks for MySQL ................................................................................................ 937
Ending a session or query ................................................................................................ 937
Skipping the current replication error ................................................................................ 937
Working with InnoDB tablespaces to improve crash recovery times ....................................... 938
Managing the global status history ................................................................................... 940
Using Kerberos authentication for MySQL .................................................................................. 942
Setting up Kerberos authentication for MySQL DB instances ................................................ 943
Managing a DB instance in a domain ................................................................................ 949
Connecting to MySQL with Kerberos authentication ............................................................ 950
Restoring a MySQL DB instance and adding it to a domain .................................................. 951
Kerberos authentication MySQL limitations ........................................................................ 951
Known issues and limitations ................................................................................................... 952
Inconsistent InnoDB buffer pool size ................................................................................. 952
Index merge optimization returns wrong results ................................................................. 952
Log file size ................................................................................................................... 953

xi
 Amazon Relational Database Service User Guide

MySQL parameter exceptions for Amazon RDS DB instances ................................................ 953

MySQL file size limits in Amazon RDS ............................................................................... 954
MySQL Keyring Plugin not supported ................................................................................ 955
MySQL on Amazon RDS SQL reference ...................................................................................... 956
Overview ....................................................................................................................... 956
SQL reference conventions .............................................................................................. 957
mysql.rds_set_master_auto_position ................................................................................. 957
mysql.rds_set_external_master ......................................................................................... 958
mysql.rds_set_external_master_with_delay ......................................................................... 960
mysql.rds_set_external_master_with_auto_position ............................................................. 963
mysql.rds_reset_external_master ...................................................................................... 965
mysql.rds_import_binlog_ssl_material ............................................................................... 966
mysql.rds_remove_binlog_ssl_material .............................................................................. 967
mysql.rds_set_source_delay .............................................................................................. 968
mysql.rds_start_replication .............................................................................................. 968
mysql.rds_start_replication_until ....................................................................................... 969
mysql.rds_start_replication_until_gtid ............................................................................... 970
mysql.rds_stop_replication ............................................................................................... 971
mysql.rds_skip_transaction_with_gtid ................................................................................ 972
mysql.rds_skip_repl_error ................................................................................................ 972
mysql.rds_next_master_log .............................................................................................. 973
mysql.rds_innodb_buffer_pool_dump_now ......................................................................... 975
mysql.rds_innodb_buffer_pool_load_now ........................................................................... 975
mysql.rds_innodb_buffer_pool_load_abort ......................................................................... 976
mysql.rds_set_configuration ............................................................................................. 976
mysql.rds_show_configuration .......................................................................................... 978
mysql.rds_kill ................................................................................................................. 978
mysql.rds_kill_query ........................................................................................................ 979
mysql.rds_rotate_general_log ........................................................................................... 979
mysql.rds_rotate_slow_log ............................................................................................... 980
mysql.rds_enable_gsh_collector ........................................................................................ 980
mysql.rds_set_gsh_collector ............................................................................................. 980
mysql.rds_disable_gsh_collector ....................................................................................... 980
mysql.rds_collect_global_status_history ............................................................................. 981
mysql.rds_enable_gsh_rotation ......................................................................................... 981
mysql.rds_set_gsh_rotation .............................................................................................. 981
mysql.rds_disable_gsh_rotation ........................................................................................ 981
mysql.rds_rotate_global_status_history ............................................................................. 982
Oracle on Amazon RDS ................................................................................................................... 983
Oracle versions ....................................................................................................................... 983
Oracle 19c ..................................................................................................................... 983
Oracle 18c ..................................................................................................................... 984
Oracle 12c ..................................................................................................................... 985
Oracle licensing ...................................................................................................................... 994
License Included ............................................................................................................. 994
Bring Your Own License (BYOL) ........................................................................................ 994
Licensing Oracle Multi-AZ deployments ............................................................................. 996
Oracle instance classes ............................................................................................................ 996
Deprecated DB instance classes ........................................................................................ 997
Oracle features ....................................................................................................................... 998
Supported features for RDS for Oracle .............................................................................. 998
Unsupported features for RDS for Oracle ......................................................................... 1000
Oracle parameters ................................................................................................................ 1000
Oracle character sets ............................................................................................................. 1000
DB character set ........................................................................................................... 1000
National character set ................................................................................................... 1003
Oracle limitations ................................................................................................................. 1003

xii
 Amazon Relational Database Service User Guide

File size limits .............................................................................................................. 1003

Public synonyms ........................................................................................................... 1004
Schemas for unsupported features .................................................................................. 1004
Limitations for Oracle DBA privileges .............................................................................. 1004
Connecting to an Oracle instance ........................................................................................... 1005
Finding the endpoint ..................................................................................................... 1005
SQL developer .............................................................................................................. 1007
SQL*Plus ...................................................................................................................... 1009
Security group considerations ......................................................................................... 1010
Dedicated and shared server processes ............................................................................ 1010
Troubleshooting ............................................................................................................ 1010
Modifying Oracle sqlnet.ora parameters .......................................................................... 1011
Securing Oracle connections .................................................................................................. 1014
Encrypting with SSL ...................................................................................................... 1014
Using new SSL/TLS certificates ...................................................................................... 1015
Configuring Kerberos authentication ............................................................................... 1018
Configuring outbound network access ............................................................................. 1029
Administering your Oracle DB ................................................................................................ 1032
System tasks ................................................................................................................ 1040
Database tasks ............................................................................................................. 1053
Log tasks ..................................................................................................................... 1066
RMAN tasks ................................................................................................................. 1073
Oracle Scheduler tasks .................................................................................................. 1089
Diagnostic tasks ............................................................................................................ 1093
Other tasks .................................................................................................................. 1099
Importing data into Oracle .................................................................................................... 1110
Importing using Oracle SQL Developer ............................................................................ 1110
Importing using Oracle Data Pump ................................................................................. 1110
Oracle Export/Import utilities ......................................................................................... 1119
Oracle SQL*Loader ........................................................................................................ 1119
Oracle materialized views .............................................................................................. 1120
Working with Oracle replicas .................................................................................................. 1122
Overview of Oracle replicas ........................................................................................... 1122
Replica requirements for Oracle ...................................................................................... 1122
Preparing to create an Oracle replica .............................................................................. 1124
Creating an Oracle replica in mounted mode .................................................................... 1125
Modifying the Oracle replica mode ................................................................................. 1126
Troubleshooting Oracle replicas ...................................................................................... 1127
Options for Oracle ................................................................................................................ 1129
Amazon S3 integration .................................................................................................. 1130
Application Express (APEX) ............................................................................................. 1143
Enterprise Manager ....................................................................................................... 1152
Java virtual machine (JVM) ............................................................................................ 1167
Label security ............................................................................................................... 1170
Locator ........................................................................................................................ 1173
Multimedia ................................................................................................................... 1176
Native network encryption (NNE) .................................................................................... 1179
OLAP .......................................................................................................................... 1183
Secure Sockets Layer (SSL) ............................................................................................. 1185
Spatial ......................................................................................................................... 1193
SQLT ........................................................................................................................... 1196
Statspack ..................................................................................................................... 1201
Time zone .................................................................................................................... 1204
Transparent Data Encryption (TDE) ................................................................................. 1207
UTL_MAIL .................................................................................................................... 1209
XML DB ....................................................................................................................... 1211
Upgrading the Oracle DB engine ............................................................................................ 1212

xiii
 Amazon Relational Database Service User Guide

Overview of Oracle upgrades ......................................................................................... 1212

Major version upgrades ................................................................................................. 1214
Minor version upgrades ................................................................................................. 1215
SE2 upgrade paths ........................................................................................................ 1215
Upgrade considerations ................................................................................................. 1216
Automatic upgrade of 18c ............................................................................................. 1217
Testing an upgrade ....................................................................................................... 1218
Upgrading an Oracle DB instance ................................................................................... 1219
Upgrading an Oracle DB snapshot .......................................................................................... 1220
Console ....................................................................................................................... 1220
AWS CLI ...................................................................................................................... 1221
RDS API ....................................................................................................................... 1221
Tools and third-party software for Oracle ................................................................................ 1222
Setting up ................................................................................................................... 1222
Using Oracle GoldenGate ............................................................................................... 1228
Using the Oracle Repository Creation Utility .................................................................... 1240
Installing a Siebel database on Oracle on Amazon RDS ...................................................... 1245
Oracle database engine release notes ...................................................................................... 1248
Oracle versions 19.0.0, 18.0.0, and 12.2.0.1 ..................................................................... 1248
Oracle versions 12.1.0.2 and 11.2.0.4 .............................................................................. 1248
Database engine: 19.0.0.0 .............................................................................................. 1250
Database engine: 18.0.0.0 .............................................................................................. 1296
Database engine: 12.2.0.1 .............................................................................................. 1323
Database engine: 12.1.0.2 .............................................................................................. 1362
Database engine: 11.2.0.4 .............................................................................................. 1413
PostgreSQL on Amazon RDS .......................................................................................................... 1456
Common management tasks for PostgreSQL on Amazon RDS .................................................... 1456
Connecting to a DB instance running the PostgreSQL database engine ........................................ 1460
Using pgAdmin to connect to a PostgreSQL DB instance .................................................... 1460
Using psql to connect to a PostgreSQL DB instance .......................................................... 1462
Troubleshooting connections to your PostgreSQL instance ................................................. 1463
Updating applications for new SSL/TLS certificates ................................................................... 1465
Determining whether applications are connecting to PostgreSQL DB instances using SSL ........ 1465
Determining whether a client requires certificate verification in order to connect ................... 1466
Updating your application trust store .............................................................................. 1466
Using SSL/TLS connections for different types of applications ............................................ 1467
Upgrading the PostgreSQL DB engine ..................................................................................... 1469
Overview of upgrading .................................................................................................. 1469
PostgreSQL version numbers .......................................................................................... 1470
Choosing a major version upgrade .................................................................................. 1470
How to perform a major version upgrade ........................................................................ 1472
Automatic minor version upgrades .................................................................................. 1475
Upgrading PostgreSQL extensions .................................................................................. 1476
Upgrading a PostgreSQL DB snapshot engine version ................................................................ 1478
Working with PostgreSQL read replicas ................................................................................... 1480
Read replica configuration with PostgreSQL ..................................................................... 1480
Monitoring PostgreSQL read replicas ............................................................................... 1481
Read replica limitations with PostgreSQL ......................................................................... 1481
Replication interruptions with PostgreSQL read replicas ..................................................... 1481
Troubleshooting a PostgreSQL read replica problem .......................................................... 1482
Importing data into PostgreSQL on Amazon RDS ...................................................................... 1484
Importing a PostgreSQL database from an Amazon EC2 instance ........................................ 1485
Using the \copy command to import data to a table on a PostgreSQL DB instance ................. 1487
Importing S3 data into RDS for PostgreSQL ..................................................................... 1488
Transporting PostgreSQL databases between DB instances ................................................. 1499
Exporting PostgreSQL data into Amazon S3 files ...................................................................... 1504
Overview of exporting to S3 .......................................................................................... 1504

xiv
 Amazon Relational Database Service User Guide

Verify that your PostgreSQL version supports exports ....................................................... 1505

Specifying the Amazon S3 file path to export to ............................................................... 1505
Setting up access to an Amazon S3 bucket ...................................................................... 1506
Exporting query data using the aws_s3.query_export_to_s3 function ................................... 1508
Function reference ........................................................................................................ 1510
Common DBA tasks for PostgreSQL ........................................................................................ 1514
Creating roles ............................................................................................................... 1514
Managing PostgreSQL database access ............................................................................ 1515
Working with PostgreSQL parameters ............................................................................. 1515
Audit logging for a PostgreSQL DB instance ..................................................................... 1524
Working with the pgaudit extension ................................................................................ 1524
Working with the pg_repack extension ............................................................................ 1526
Using pgBadger for log analysis with PostgreSQL ............................................................. 1526
Viewing the contents of pg_config .................................................................................. 1526
Working with the orafce extension .................................................................................. 1527
Accessing external data with the postgres_fdw extension ................................................... 1528
Restricting password management .................................................................................. 1529
Working with PostgreSQL autovacuum ............................................................................ 1529
Working with PostGIS .................................................................................................... 1538
Using a custom DNS server for outbound network access ................................................... 1540
Scheduling maintenance with the pg_cron extension ......................................................... 1542
Managing partitions with the pg_partman extension ......................................................... 1549
Using Kerberos authentication ................................................................................................ 1553
Availability ................................................................................................................... 1553
Overview of Kerberos authentication ............................................................................... 1554
Setting up ................................................................................................................... 1555
Managing a DB instance in a Domain .............................................................................. 1563
Connecting with Kerberos authentication ......................................................................... 1564
Working with the database preview environment ...................................................................... 1565
Features not supported in the preview environment .......................................................... 1566
PostgreSQL extensions supported in the preview environment ........................................... 1566
Creating a new DB instance in the preview environment .................................................... 1568
PostgreSQL versions and extensions ........................................................................................ 1568
Supported PostgreSQL database versions ........................................................................ 1569
Supported features and extensions ................................................................................. 1587
Security ....................................................................................................................................... 1617
Database authentication ........................................................................................................ 1618
Password authentication ................................................................................................ 1618
IAM database authentication .......................................................................................... 1619
Kerberos authentication ................................................................................................. 1619
Data protection .................................................................................................................... 1619
Data encryption ............................................................................................................ 1620
Internetwork traffic privacy ............................................................................................ 1633
Identity and access management ............................................................................................ 1634
Audience ...................................................................................................................... 1634
Authenticating with identities ......................................................................................... 1634
Managing access using policies ....................................................................................... 1636
How Amazon RDS works with IAM .................................................................................. 1638
Identity-based policy examples ....................................................................................... 1640
IAM database authentication for MySQL and PostgreSQL ................................................... 1650
Troubleshooting ............................................................................................................ 1676
Logging and monitoring ........................................................................................................ 1678
Compliance validation ........................................................................................................... 1680
Resilience ............................................................................................................................. 1681
Backup and restore ....................................................................................................... 1681
Replication ................................................................................................................... 1681
Failover ....................................................................................................................... 1681

xv
 Amazon Relational Database Service User Guide

Infrastructure security ........................................................................................................... 1682

Security groups ............................................................................................................ 1682
Public accessibility ........................................................................................................ 1682
VPC endpoints (AWS PrivateLink) ............................................................................................ 1683
Considerations .............................................................................................................. 1683
Availability ................................................................................................................... 1683
Creating an interface VPC endpoint ................................................................................ 1684
Creating a VPC endpoint policy ...................................................................................... 1684
Security best practices ........................................................................................................... 1685
Controlling access with security groups ................................................................................... 1686
VPC security groups ...................................................................................................... 1686
DB security groups ........................................................................................................ 1686
DB security groups vs. VPC security groups ...................................................................... 1687
Security group scenario ................................................................................................. 1687
Creating a VPC security group ........................................................................................ 1688
Associating with a DB instance ....................................................................................... 1688
Deleting DB VPC security groups .................................................................................... 1688
DB security groups on EC2-Classic .................................................................................. 1691
Master user account privileges ................................................................................................ 1699
Service-linked roles ............................................................................................................... 1701
Service-linked role permissions for Amazon RDS ............................................................... 1701
Creating a service-linked role for Amazon RDS ................................................................. 1703
Editing a service-linked role for Amazon RDS ................................................................... 1703
Deleting a service-linked role for Amazon RDS ................................................................. 1703
Using Amazon RDS with Amazon VPC ..................................................................................... 1705
Determining whether you are using the EC2-VPC or EC2-Classic platform ............................. 1705
Scenarios for accessing a DB instance in a VPC ................................................................. 1707
Working with a DB instance in a VPC .............................................................................. 1714
Updating the VPC for a DB instance ................................................................................ 1721
Tutorial: Create an Amazon VPC for use with a DB instance ................................................ 1724
Quotas and constraints .................................................................................................................. 1729
Quotas in Amazon RDS ......................................................................................................... 1729
Naming constraints in Amazon RDS ........................................................................................ 1730
Maximum number of database connections ............................................................................. 1731
File size limits in Amazon RDS ................................................................................................ 1732
Troubleshooting ............................................................................................................................ 1733
Can't connect to DB instance ................................................................................................. 1733
Testing the DB instance connection ................................................................................. 1734
Troubleshooting connection authentication ...................................................................... 1735
Security issues ...................................................................................................................... 1735
Error message "failed to retrieve account attributes, certain console functions may be
impaired." .................................................................................................................... 1735
Resetting the DB instance owner password .............................................................................. 1735
DB instance outage or reboot ................................................................................................. 1736
Parameter changes not taking effect ....................................................................................... 1736
DB instance out of storage .................................................................................................... 1737
Insufficient DB instance capacity ............................................................................................. 1738
MySQL and MariaDB issues .................................................................................................... 1738
Maximum MySQL and MariaDB connections ..................................................................... 1739
Diagnosing and resolving incompatible parameters status for a memory limit ....................... 1739
Diagnosing and resolving lag between read replicas .......................................................... 1740
Diagnosing and resolving a MySQL or MariaDB read replication failure ................................. 1741
Creating triggers with binary logging enabled requires SUPER privilege ............................... 1742
Diagnosing and resolving point-in-time restore failures ..................................................... 1744
Replication stopped error .............................................................................................. 1744
Read replica create fails or replication breaks with fatal error 1236 ..................................... 1745
Can't set backup retention period to 0 .................................................................................... 1745

xvi
 Amazon Relational Database Service User Guide

Amazon RDS API reference ............................................................................................................ 1746

Using the Query API ............................................................................................................. 1746
Query parameters ......................................................................................................... 1746
Query request authentication ......................................................................................... 1746
Troubleshooting applications .................................................................................................. 1747
Retrieving errors ........................................................................................................... 1747
Troubleshooting tips ..................................................................................................... 1747
Document history ......................................................................................................................... 1748
Earlier updates ..................................................................................................................... 1784
AWS glossary ............................................................................................................................... 1804

xvii
 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 AWS Cloud. It provides cost-efficient, resizable capacity
for an industry-standard relational database and manages common database administration tasks.
Note
This guide covers Amazon RDS database engines other than Amazon Aurora. For information
about using Amazon Aurora, see the Amazon Aurora User Guide.
This guide covers using Amazon RDS in the AWS Cloud. For information about using Amazon
RDS in on-premises VMware environments, see the Amazon RDS on VMware User Guide.

Overview of Amazon RDS

Why do you want a managed relational database service? Because Amazon RDS takes over many of the
difficult and 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. It
also 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 use the database products you are already familiar with: MySQL, MariaDB, PostgreSQL, Oracle,
Microsoft SQL Server.
• 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 MariaDB, Microsoft SQL Server, MySQL, Oracle,
and PostgreSQL read replicas to increase read scaling.
• 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 AWS Cloud. Your DB instance can contain multiple user-created databases. You
can access your DB instance by using the same tools and applications that you use with a standalone

1
 Amazon Relational Database Service User Guide
AWS Regions and Availability Zones

database instance. You 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 classes (p. 7).
Note
For pricing information on DB instance classes, see 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. Also, sufficient storage makes sure
that features for the DB engine have room to write content or log entries. For more information, see
Amazon RDS DB instance storage (p. 40).

You can run a DB instance on a virtual private cloud (VPC) using the Amazon Virtual Private Cloud
(Amazon VPC) service. When you use a VPC, you have control over your virtual networking environment.
You can choose 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's running in a VPC or not. Amazon RDS
manages backups, software patching, automatic failure detection, and recovery. There's no additional
cost to run your DB instance in a VPC. For more information on using Amazon VPC with RDS, see Amazon
Virtual Private Cloud VPCs and Amazon RDS (p. 1705).

Amazon RDS uses Network Time Protocol (NTP) to synchronize the time on DB Instances.

AWS 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 an AWS
Region.

Each AWS Region contains multiple distinct locations called Availability Zones, or AZs. Each Availability
Zone is engineered to be isolated from failures in other Availability Zones. Each is engineered to provide
inexpensive, low-latency network connectivity to other Availability Zones in the same AWS 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, Availability Zones, and Local Zones (p. 49).

You can run your DB instance in several Availability Zones, an option called a Multi-AZ deployment.
When you choose 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. This approach helps provide data redundancy and
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. 53).

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.

2
 Amazon Relational Database Service User Guide
Monitoring an Amazon RDS DB instance

For more information about security groups, see Security in Amazon RDS (p. 1617).

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 Amazon CloudWatch service to monitor the performance and health of a DB instance. CloudWatch
performance charts are shown in the Amazon RDS console. You can also subscribe to Amazon RDS events
to be notified about changes to a DB instance, DB snapshot, DB parameter group, or DB security group.
For more information, see Monitoring an Amazon RDS DB instance (p. 405).

How to work with Amazon RDS

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. 1746).

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. 57).

For Amazon RDS pricing information, see the Amazon RDS product page.

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

3
 Amazon Relational Database Service User Guide
Getting started

Getting started
Create a DB instance using instructions in Getting started with Amazon RDS (p. 73).

Database engine–Specific topics

You can review information specific to a particular DB engine in the following sections:

• MariaDB on Amazon RDS (p. 581)

• Microsoft SQL Server on Amazon RDS (p. 637)
• MySQL on Amazon RDS (p. 830)
• Oracle on Amazon RDS (p. 983)
• PostgreSQL on Amazon RDS (p. 1456)

4
 Amazon Relational Database Service User Guide
DB instances

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 operations,
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, with the following limitations:

• 10 for each SQL Server edition (Enterprise, Standard, Web, and Express) under the "license-included"
model
• 10 for Oracle under the "license-included" model
• 40 for MySQL, MariaDB, or PostgreSQL
• 40 for Oracle under the "bring-your-own-license" (BYOL) licensing model

Note
If your application requires more DB instances, you can request additional DB instances by using
this form.

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.

The identifier is used as part of the DNS hostname allocated to your instance by RDS. For example, if you
specify db1 as the DB instance identifier, then RDS will automatically allocate a DNS endpoint for your
instance, such as db1.123456789012.us-east-1.rds.amazonaws.com, where 123456789012 is the
fixed identifier for a specific region for your account.

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

5
 Amazon Relational Database Service User Guide
DB instances

API operations, 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.

6
 Amazon Relational Database Service User Guide
DB instance classes

DB instance classes
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.

Topics
• DB instance class types (p. 7)
• Supported DB engines for DB instance classes (p. 8)
• Determining DB instance class support in AWS Regions (p. 17)
• Changing your DB instance class (p. 20)
• Configuring the processor for a DB instance class (p. 20)
• Hardware specifications for DB instance classes (p. 33)

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.m6g – General-purpose instance classes powered by AWS Graviton2 processors. These deliver
balanced compute, memory, and networking for a broad range a general purpose workloads.

You can modify a DB instance to use one of the DB instance classes powered by AWS Graviton2
processors by completing the same steps as any other DB instance modification.
• db.m5d – Newest generation instance classes that are optimized for low latency, very high random I/O
performance, and high sequential read throughput.
• 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. They are powered
by the AWS Nitro System, a combination of dedicated hardware and lightweight hypervisor.
• db.m4 – General-purpose instance classes that provide more computing capacity than the previous
db.m3 instance classes.
• db.m3 – General-purpose instance classes that provide more computing capacity than the previous
db.m1 instance classes.
• db.m1 – Earlier generation general-purpose instance classes.

The following are the Memory Optimized DB instance classes available:

• db.z1d – Instance classes optimized for memory-intensive applications. These offer both high compute
capacity and a high memory footprint. High frequency z1d instances deliver a sustained all core
frequency of up to 4.0 GHz.
• db.x1e – Instance classes optimized for memory-intensive applications. These offer one of the lowest
price per gibibyte (GiB) of RAM among the DB instance classes and up to 3,904 GiB of DRAM-based
instance memory.
• db.x1 – 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 DRAM-based instance
memory.

7
 Amazon Relational Database Service User Guide
Supported DB engines

• db.r6g – Instance classes powered by AWS Graviton2 processors. These are ideal for running memory-
intensive workloads in open-source databases such as MySQL and PostgreSQL.

You can modify a DB instance to use one of the DB instance classes powered by AWS Graviton2
processors by completing the same steps as any other DB instance modification.
• db.r5b – Instance classes that are memory-optimized for throughput-intensive applications. Powered
by the AWS Nitro System, db.r5b instances deliver up to 60 Gbps bandwidth and 260,000 IOPS of EBS
performance, which is the fastest block storage performance on EC2.
• db.r5d – Instance classes that are optimized for low latency, very high random I/O performance, and
high sequential read throughput.
• db.r5 – Latest generation instance classes optimized for memory-intensive applications. These offer
improved networking and Amazon Elastic Block Store (Amazon EBS) performance. They are powered
by the AWS Nitro System, a combination of dedicated hardware and lightweight hypervisor.
• db.r4 – Instance classes optimized for memory-intensive applications. These offer improved
networking and Amazon EBS performance.
• db.r3 – Instance classes that provide memory optimization.
• db.m2 – Earlier generation memory-optimized instance classes.

The following are the Burstable Performance DB instance classes available:

• db.t3 – Next generation instance classes that provide a baseline performance level, with the ability
to burst to full CPU usage. These instance classes provide more computing capacity than the previous
db.t2 instance classes. They are powered by the AWS Nitro System, a combination of dedicated
hardware and lightweight hypervisor.
• db.t2 – Instance classes that provide a baseline performance level, with the ability to burst to full CPU
usage.

Note
The DB instance classes that use the AWS Nitro System (db.m5, db.r5, db.t3) are throttled on
combined read plus write workload.

For DB instance class hardware specifications, see Hardware specifications for DB instance classes
(p. 33).

Supported DB engines for DB instance classes

The following are DB engine considerations for DB instance classes:

MariaDB

The Graviton2 instance classes db.m6g and db.r6g are supported for all MariaDB 10.5 versions and
MariaDB version 10.4.13 and higher 10.4 versions.
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. 641).
MySQL

The Graviton2 instance classes db.m6g and db.r6g are supported for RDS for MySQL versions 8.0.17
and higher.
Oracle

Instance class support varies according to the version and edition of Oracle. For instance class
support by version and edition, see RDS for Oracle instance classes (p. 996).

8
 Amazon Relational Database Service User Guide
Supported DB engines

PostgreSQL

PostgreSQL versions 13 and higher support the db.m6g, db.m5, db.r6g, db.r5, db.t3 instance classes.
Previous generations of classes are supported only by PostgreSQL versions lower than 13 and
include db.m4, db.m3, db.r4, db.r3, and db.t2.

In the following table, you can find details about supported Amazon RDS DB instance classes for each
Amazon RDS DB engine.

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL Server

db.m6g – Standard instance classes powered by AWS Graviton2 processors

db.m6g.16xlarge All MariaDB No MySQL 8.0.17 No PostgreSQL

10.5 versions & higher 13,12.3 &
and MariaDB higher
version
10.4.13 &
higher 10.4
versions

db.m6g.12xlarge All MariaDB No MySQL 8.0.17 No PostgreSQL

10.5 versions & higher 13,12.3 &
and MariaDB higher
version
10.4.13 &
higher 10.4
versions

db.m6g.8xlarge All MariaDB No MySQL 8.0.17 No PostgreSQL

10.5 versions & higher 13,12.3 &
and MariaDB higher
version
10.4.13 &
higher 10.4
versions

db.m6g.4xlarge All MariaDB No MySQL 8.0.17 No PostgreSQL

10.5 versions & higher 13,12.3 &
and MariaDB higher
version
10.4.13 &
higher 10.4
versions

db.m6g.2xlarge All MariaDB No MySQL 8.0.17 No PostgreSQL

10.5 versions & higher 13,12.3 &
and MariaDB higher
version
10.4.13 &
higher 10.4
versions

db.m6g.xlarge All MariaDB No MySQL 8.0.17 No PostgreSQL

10.5 versions & higher 13,12.3 &
and MariaDB higher
version

9
 Amazon Relational Database Service User Guide
Supported DB engines

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL Server
10.4.13 &
higher 10.4
versions

db.m6g.large All MariaDB No MySQL 8.0.17 No PostgreSQL

10.5 versions & higher 13,12.3 &
and MariaDB higher
version
10.4.13 &
higher 10.4
versions

db.m5d – Newest generation standard instance classes

db.m5d.24xlarge No Yes No No No

db.m5d.16xlarge No Yes No No No

db.m5d.12xlarge No Yes No No No

db.m5d.8xlarge No Yes No No No

db.m5d.4xlarge No Yes No No No

db.m5d.2xlarge No Yes No No No

db.m5d.xlarge No Yes No No No

db.m5d.large No Yes No No No

db.m5 – Latest generation standard instance classes

db.m5.24xlarge Yes Yes Yes Yes PostgreSQL

13, 12, 11,
10.4 & higher,
9.6.9 & higher

db.m5.16xlarge Yes Yes Yes Yes PostgreSQL

13, 12, 11,
10.4 & higher,
9.6.9 & higher

db.m5.12xlarge Yes Yes Yes Yes PostgreSQL

13, 12, 11,
10.4 & higher,
9.6.9 & higher

db.m5.8xlarge Yes Yes Yes Yes PostgreSQL

13, 12, 11,
10.4 & higher,
9.6.9 & higher

db.m5.4xlarge Yes Yes Yes Yes PostgreSQL

13, 12, 11,
10.4 & higher,
9.6.9 & higher

10
 Amazon Relational Database Service User Guide
Supported DB engines

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL Server

db.m5.2xlarge Yes Yes Yes Yes PostgreSQL

13, 12, 11,
10.4 & higher,
9.6.9 & higher

db.m5.xlarge Yes Yes Yes Yes PostgreSQL

13, 12, 11,
10.4 & higher,
9.6.9 & higher

db.m5.large Yes Yes Yes Yes PostgreSQL

13, 12, 11,
10.4 & higher,
9.6.9 & higher

db.m4 – Standard instance classes

db.m4.16xlarge Yes Yes MySQL 8.0, Yes Lower than

5.7, 5.6 PostgreSQL
13

db.m4.10xlarge Yes Yes Yes Yes Lower than

PostgreSQL
13

db.m4.4xlarge Yes Yes Yes Yes Lower than

PostgreSQL
13

db.m4.2xlarge Yes Yes Yes Yes Lower than

PostgreSQL
13

db.m4.xlarge Yes Yes Yes Yes Lower than

PostgreSQL
13

db.m4.large Yes Yes Yes Yes Lower than

PostgreSQL
13

db.m3 – Standard instance classes

db.m3.2xlarge No Yes Yes Deprecated Lower than

PostgreSQL
13

db.m3.xlarge No Yes Yes Deprecated Lower than

PostgreSQL
13

db.m3.large No Yes Yes Deprecated Lower than

PostgreSQL
13

11
 Amazon Relational Database Service User Guide
Supported DB engines

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL Server

db.m3.medium No Yes Yes Deprecated Lower than

PostgreSQL
13

db.m1 – Standard instance classes

db.m1.xlarge No Yes Deprecated Deprecated Deprecated

db.m1.large No Yes Deprecated Deprecated Deprecated

db.m1.medium No Yes Deprecated Deprecated Deprecated

db.m1.small No Yes Deprecated Deprecated Deprecated

db.z1d – Memory-optimized instance classes

db.z1d.12xlarge No Yes No Yes No

db.z1d.6xlarge No Yes No Yes No

db.z1d.3xlarge No Yes No Yes No

db.z1d.2xlarge No Yes No Yes No

db.z1d.xlarge No Yes No Yes No

db.z1d.large No Yes No Yes No

db.x1e – Memory-optimized instance classes

db.x1e.32xlarge No Yes No Yes No

db.x1e.16xlarge No Yes No Yes No

db.x1e.8xlarge No Yes No Yes No

db.x1e.4xlarge No Yes No Yes No

db.x1e.2xlarge No Yes No Yes No

db.x1e.xlarge No Yes No Yes No

db.x1 – Memory-optimized instance classes

db.x1.32xlarge No Yes No Yes No

db.x1.16xlarge No Yes No Yes No

db.r6g – Memory-optimized instance classes powered by AWS Graviton2 processors

db.r6g.16xlarge All MariaDB No MySQL 8.0.17 No PostgreSQL

10.5 versions & higher 13, 12.3 &
and MariaDB higher
version
10.4.13 &
higher 10.4
versions

12
 Amazon Relational Database Service User Guide
Supported DB engines

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL Server

db.r6g.12xlarge All MariaDB No MySQL 8.0.17 No PostgreSQL

10.5 versions & higher 13, 12.3 &
and MariaDB higher
version
10.4.13 &
higher 10.4
versions

db.r6g.8xlarge All MariaDB No MySQL 8.0.17 No PostgreSQL

10.5 versions & higher 12.3 & higher
and MariaDB
version
10.4.13 &
higher 10.4
versions

db.r6g.4xlarge All MariaDB No MySQL 8.0.17 No PostgreSQL

10.5 versions & higher 13, 12.3 &
and MariaDB higher
version
10.4.13 &
higher 10.4
versions

db.r6g.2xlarge All MariaDB No MySQL 8.0.17 No PostgreSQL

10.5 versions & higher 13, 12.3 &
and MariaDB higher
version
10.4.13 &
higher 10.4
versions

db.r6g.xlarge All MariaDB No MySQL 8.0.17 No PostgreSQL

10.5 versions & higher 13, 12.3 &
and MariaDB higher
version
10.4.13 &
higher 10.4
versions

db.r6g.large All MariaDB No MySQL 8.0.17 No PostgreSQL

10.5 versions & higher 13, 12.3 &
and MariaDB higher
version
10.4.13 &
higher 10.4
versions

db.r5d – Newest Generation Memory Optimized Instance Classes

db.r5d.24xlarge No Yes No No No

db.r5d.16xlarge No Yes No No No

db.r5d.12xlarge No Yes No No No

13
 Amazon Relational Database Service User Guide
Supported DB engines

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL Server

db.r5d.8xlarge No Yes No No No

db.r5d.4xlarge No Yes No No No

db.r5d.2xlarge No Yes No No No

db.r5d.xlarge No Yes No No No

db.r5d.large No Yes No No No

db.r5b – Memory-optimized instance classes

db.r5b.24xlarge No Yes No Yes No

db.r5b.16xlarge No Yes No Yes No

db.r5b.12xlarge No Yes No Yes No

db.r5b.8xlarge No Yes No Yes No

db.r5b.4xlarge No Yes No Yes No

db.r5b.2xlarge No Yes No Yes No

db.r5b.xlarge No Yes No Yes No

db.r5b.large No Yes No Yes No

db.r5 – Latest generation memory-optimized instance classes

db.r5.24xlarge Yes Yes Yes Yes PostgreSQL

13, 12, 11,
10.4 & higher,
9.6.9 & higher

db.r5.16xlarge Yes Yes Yes Yes PostgreSQL

13, 12, 11,
10.4 & higher,
9.6.9 & higher

db.r5.12xlarge Yes Yes Yes Yes PostgreSQL

13, 12, 11,
10.4 & higher,
9.6.9 & higher

db.r5.8xlarge Yes Yes Yes Yes PostgreSQL

13, 12, 11,
10.4 & higher,
9.6.9 & higher

db.r5.4xlarge Yes Yes Yes Yes PostgreSQL

13, 12, 11,
10.4 & higher,
9.6.9 & higher

14
 Amazon Relational Database Service User Guide
Supported DB engines

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL Server

db.r5.2xlarge Yes Yes Yes Yes PostgreSQL

13, 12, 11,
10.4 & higher,
9.6.9 & higher

db.r5.xlarge Yes Yes Yes Yes PostgreSQL

13, 12, 11,
10.4 & higher,
9.6.9 & higher

db.r5.large Yes Yes Yes Yes PostgreSQL

13, 12, 11,
10.4 & higher,
9.6.9 & higher

db.r4 – Memory-optimized instance classes

db.r4.16xlarge Yes Yes MySQL 8.0, Yes Lower than

5.7, 5.6 PostgreSQL
13

db.r4.8xlarge Yes Yes MySQL 8.0, Yes Lower than

5.7, 5.6 PostgreSQL
13

db.r4.4xlarge Yes Yes MySQL 8.0, Yes Lower than

5.7, 5.6 PostgreSQL
13

db.r4.2xlarge Yes Yes MySQL 8.0, Yes Lower than

5.7, 5.6 PostgreSQL
13

db.r4.xlarge Yes Yes MySQL 8.0, Yes Lower than

5.7, 5.6 PostgreSQL
13

db.r4.large Yes Yes MySQL 8.0, Yes Lower than

5.7, 5.6 PostgreSQL
13

db.r3 – Memory-optimized instance classes

db.r3.8xlarge** Yes Yes Yes Deprecated Lower than

PostgreSQL
13

db.r3.4xlarge Yes Yes Yes Deprecated Lower than

PostgreSQL
13

db.r3.2xlarge Yes Yes Yes Deprecated Lower than

PostgreSQL
13

15
 Amazon Relational Database Service User Guide
Supported DB engines

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL Server

db.r3.xlarge Yes Yes Yes Deprecated Lower than

PostgreSQL
13

db.r3.large Yes Yes Yes Deprecated Lower than

PostgreSQL
13

db.m2 – Memory-optimized instance classes

db.m2.4xlarge No Yes Deprecated Deprecated Deprecated

db.m2.2xlarge No Yes Deprecated Deprecated Deprecated

db.m2.xlarge No Yes Deprecated Deprecated Deprecated

db.t3 – Next generation burstable performance instance classes

db.t3.2xlarge Yes Yes Yes Yes PostgreSQL

13, 12, 11, 10,
9.6.9 & higher

db.t3.xlarge Yes Yes Yes Yes PostgreSQL

13, 12, 11, 10,
9.6.9 & higher

db.t3.large Yes Yes Yes Yes PostgreSQL

13, 12, 11, 10,
9.6.9 & higher

db.t3.medium Yes Yes Yes Yes PostgreSQL

13, 12, 11, 10,
9.6.9 & higher

db.t3.small Yes Yes Yes Yes PostgreSQL

13, 12, 11, 10,
9.6.9 & higher

db.t3.micro Yes No Yes Yes PostgreSQL

13, 12, 11, 10,
9.6.9 & higher

db.t2 – Burstable performance instance classes

db.t2.2xlarge Yes No MySQL 8.0, Deprecated Lower than

5.7, 5.6 PostgreSQL
13

db.t2.xlarge Yes No MySQL 8.0, Deprecated Lower than

5.7, 5.6 PostgreSQL
13

db.t2.large Yes Yes Yes Deprecated Lower than

PostgreSQL
13

16
 Amazon Relational Database Service User Guide
Determining DB instance class support in AWS Regions

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL Server

db.t2.medium Yes Yes Yes Deprecated Lower than

PostgreSQL
13

db.t2.small Yes Yes Yes Deprecated Lower than

PostgreSQL
13

db.t2.micro Yes Yes Yes Deprecated Lower than

PostgreSQL
13

Determining DB instance class support in AWS

Regions
To determine the DB instance classes supported by each DB engine in a specific AWS Region, you can use
the AWS Management Console, the Amazon RDS Pricing page, or the describe-orderable-db-instance-
options command for the AWS Command Line Interface (AWS CLI).
Note
When you perform operations with the AWS CLI, such as creating or modifying a DB instance,
it automatically shows the supported DB instance classes for a specific DB engine, DB engine
version, and AWS Region.

Contents
• Using the Amazon RDS pricing page to determine DB instance class support in AWS
Regions (p. 17)
• Using the AWS CLI to determine DB instance class support in AWS Regions (p. 18)
• Listing the DB instance classes that are supported by a specific DB engine version in an AWS
Region (p. 18)
• Listing the DB engine versions that support a specific DB instance class in an AWS
Region (p. 19)

Using the Amazon RDS pricing page to determine DB instance

class support in AWS Regions
You can use the Amazon RDS Pricing page to determine the DB instance classes supported by each DB
engine in a specific AWS Region.

To use the pricing page to determine the DB instance classes supported by each engine in a
Region

1. Go to Amazon RDS Pricing.

2. Choose a DB engine.
3. On the pricing page for the DB engine, choose On-Demand DB Instances or Reserved DB Instances.
4. To see the DB instance classes available in an AWS Region, choose the AWS Region in Region.

Other choices might be available for some DB engines, such as Single-AZ Deployment or Multi-AZ
Deployment.

17
 Amazon Relational Database Service User Guide
Determining DB instance class support in AWS Regions

Using the AWS CLI to determine DB instance class support in

AWS Regions
You can use the AWS CLI to determine which DB instance classes are supported for specific DB engines
and DB engine versions in an AWS Region. The following table shows the valid DB engine values.

Engine names Engine values in CLI More information about versions

commands

MariaDB mariadb MariaDB on Amazon RDS versions (p. 583)

Microsoft SQL Server sqlserver-ee Microsoft SQL Server versions on Amazon

RDS (p. 644)
sqlserver-se

sqlserver-ex

sqlserver-web

MySQL mysql MySQL on Amazon RDS versions (p. 832)

Oracle oracle-ee Oracle database engine release notes (p. 1248)

oracle-se2

oracle-se

PostgreSQL postgres Amazon RDS for PostgreSQL versions and

extensions (p. 1568)

For information about AWS Region names, see AWS Regions (p. 49).

The following examples demonstrate how to determine DB instance class support in an AWS Region
using the describe-orderable-db-instance-options AWS CLI command.
Note
To limit the output, these examples show results only for the General Purpose SSD (gp2) storage
type. If necessary, you can change the storage type to Provisioned IOPS (io1) or magnetic
(standard) in the commands.

Topics
• Listing the DB instance classes that are supported by a specific DB engine version in an AWS
Region (p. 18)
• Listing the DB engine versions that support a specific DB instance class in an AWS Region (p. 19)

Listing the DB instance classes that are supported by a specific DB engine

version in an AWS Region
To list the DB instance classes that are supported by a specific DB engine version in an AWS Region, run
the following command.

For Linux, macOS, or Unix:

aws rds describe-orderable-db-instance-options --engine engine --engine-version version \

--query "*[].{DBInstanceClass:DBInstanceClass,StorageType:StorageType}|[?
StorageType=='gp2']|[].{DBInstanceClass:DBInstanceClass}" \

18
 Amazon Relational Database Service User Guide
Determining DB instance class support in AWS Regions

--output text \
--region region

For Windows:

aws rds describe-orderable-db-instance-options --engine engine --engine-version version ^

--query "*[].{DBInstanceClass:DBInstanceClass,StorageType:StorageType}|[?
StorageType=='gp2']|[].{DBInstanceClass:DBInstanceClass}" ^
--output text ^
--region region

For example, the following command lists the supported DB instance classes for version 12.4 of the RDS
for PostgreSQL DB engine in US East (N. Virginia).

For Linux, macOS, or Unix:

aws rds describe-orderable-db-instance-options --engine postgres --engine-version 12.4 \

--query "*[].{DBInstanceClass:DBInstanceClass,StorageType:StorageType}|[?
StorageType=='gp2']|[].{DBInstanceClass:DBInstanceClass}" \
--output text \
--region us-east-1

For Windows:

aws rds describe-orderable-db-instance-options --engine postgres --engine-version 12.4 ^

--query "*[].{DBInstanceClass:DBInstanceClass,StorageType:StorageType}|[?
StorageType=='gp2']|[].{DBInstanceClass:DBInstanceClass}" ^
--output text ^
--region us-east-1

Listing the DB engine versions that support a specific DB instance class in an

AWS Region
To list the DB engine versions that support a specific DB instance class in an AWS Region, run the
following command.

For Linux, macOS, or Unix:

aws rds describe-orderable-db-instance-options --engine engine --db-instance-

class DB_instance_class \
--query "*[].{EngineVersion:EngineVersion,StorageType:StorageType}|[?
StorageType=='gp2']|[].{EngineVersion:EngineVersion}" \
--output text \
--region region

For Windows:

aws rds describe-orderable-db-instance-options --engine engine --db-instance-

class DB_instance_class ^
--query "*[].{EngineVersion:EngineVersion,StorageType:StorageType}|[?
StorageType=='gp2']|[].{EngineVersion:EngineVersion}" ^
--output text ^
--region region

For example, the following command lists the DB engine versions of the RDS for PostgreSQL DB engine
that support the db.r5.large DB instance class in US East (N. Virginia).

For Linux, macOS, or Unix:

19
 Amazon Relational Database Service User Guide
Changing your DB instance class

aws rds describe-orderable-db-instance-options --engine postgres --db-instance-class

db.r5.large \
--query "*[].{EngineVersion:EngineVersion,StorageType:StorageType}|[?
StorageType=='gp2']|[].{EngineVersion:EngineVersion}" \
--output text \
--region us-east-1

For Windows:

aws rds describe-orderable-db-instance-options --engine postgres --db-instance-class

db.r5.large ^
--query "*[].{EngineVersion:EngineVersion,StorageType:StorageType}|[?
StorageType=='gp2']|[].{EngineVersion:EngineVersion}" ^
--output text ^
--region us-east-1

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 in Modifying an
Amazon RDS DB instance (p. 256).

Some instance classes require that your DB instance is in a VPC. If your current DB instance isn't in a VPC,
and you want to use an instance class that requires one, first move your DB instance into a VPC. For more
information, see Moving a DB instance not in a VPC into a VPC (p. 1722).

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.

Topics
• Overview of configuring the processor (p. 20)
• CPU cores and threads per CPU core per DB instance class (p. 21)
• Setting the CPU cores and threads per CPU core for a DB instance class (p. 25)

Overview of configuring the processor

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:

• 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.

20
 Amazon Relational Database Service User Guide
Configuring the processor

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, either specify
default processor settings or explicitly specify processor settings at modification. 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.

CPU cores and threads per CPU core per DB instance class
In the 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 Default vCPUs Default CPU Default Valid number Valid number
class cores threads per of CPU cores of threads per
core 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

db.m5.8xlarge 32 16 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16

db.m5.12xlarge 48 24 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24

db.m5.16xlarge 64 32 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24, 26,
28, 30, 32

db.m5.24xlarge 96 48 2 4, 6, 8, 10, 12, 1, 2

14, 16, 18, 20,
22, 24, 26, 28,
30, 32, 34, 36,
38, 40, 42, 44,
46, 48

db.m5d.large 2 1 2 1 1, 2

db.m5d.xlarge 4 2 2 2 1, 2

db.m5d.2xlarge 8 4 2 2, 4 1, 2

db.m5d.4xlarge 16 8 2 2, 4, 6, 8 1, 2

21
 Amazon Relational Database Service User Guide
Configuring the processor

DB instance Default vCPUs Default CPU Default Valid number Valid number
class cores threads per of CPU cores of threads per
core core

db.m5d.8xlarge 32 16 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16

db.m5d.12xlarge 48 24 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24

db.m5d.16xlarge 64 32 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24, 26,
28, 30, 32

db.m5d.24xlarge 96 48 2 4, 6, 8, 10, 12, 1, 2

14, 16, 18, 20,
22, 24, 26, 28,
30, 32, 34, 36,
38, 40, 42, 44,
46, 48

db.m4.10xlarge 40 20 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20

db.m4.16xlarge 64 32 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24, 26,
28, 30, 32

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, 1, 2
7, 8

db.r3.8xlarge 32 16 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16

db.r5.large 2 1 2 1 1, 2

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.8xlarge 32 16 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16

db.r5.12xlarge 48 24 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24

22
 Amazon Relational Database Service User Guide
Configuring the processor

DB instance Default vCPUs Default CPU Default Valid number Valid number
class cores threads per of CPU cores of threads per
core core

db.r5.16xlarge 64 32 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24, 26,
28, 30, 32

db.r5.24xlarge 96 48 2 4, 6, 8, 10, 12, 1, 2

14, 16, 18, 20,
22, 24, 26, 28,
30, 32, 34, 36,
38, 40, 42, 44,
46, 48

db.r5b.large 2 1 2 1 1, 2

db.r5b.xlarge 4 2 2 2 1, 2

db.r5b.2xlarge 8 4 2 2, 4 1, 2

db.r5b.4xlarge 16 8 2 2, 4, 6, 8 1, 2

db.r5b.8xlarge 32 16 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16

db.r5b.12xlarge 48 24 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24

db.r5b.16xlarge 64 32 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24, 26,
28, 30, 32

db.r5b.24xlarge 96 48 2 4, 6, 8, 10, 12, 1, 2

14, 16, 18, 20,
22, 24, 26, 28,
30, 32, 34, 36,
38, 40, 42, 44,
46, 48

db.r5d.large 2 1 2 1 1, 2

db.r5d.xlarge 4 2 2 2 1, 2

db.r5d.2xlarge 8 4 2 2, 4 1, 2

db.r5d.4xlarge 16 8 2 2, 4, 6, 8 1, 2

db.r5d.8xlarge 32 16 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16

db.r5d.12xlarge 48 24 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24

23
 Amazon Relational Database Service User Guide
Configuring the processor

DB instance Default vCPUs Default CPU Default Valid number Valid number
class cores threads per of CPU cores of threads per
core core

db.r5d.16xlarge 64 32 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24, 26,
28, 30, 32

db.r5d.24xlarge 96 48 2 4, 6, 8, 10, 12, 1, 2

14, 16, 18, 20,
22, 24, 26, 28,
30, 32, 34, 36,
38, 40, 42, 44,
46, 48

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, 1, 2
7, 8

db.r4.8xlarge 32 16 2 1, 2, 3, 4, 5, 6, 1, 2
7, 8, 9, 10, 11,
12, 13, 14, 15,
16

db.r4.16xlarge 64 32 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24, 26,
28, 30, 32

db.x1.16xlarge 64 32 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24, 26,
28, 30, 32

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, 1, 2
7, 8

db.x1e.8xlarge 32 16 2 1, 2, 3, 4, 5, 6, 1, 2
7, 8, 9, 10, 11,
12, 13, 14, 15,
16

24
 Amazon Relational Database Service User Guide
Configuring the processor

DB instance Default vCPUs Default CPU Default Valid number Valid number
class cores threads per of CPU cores of threads per
core core

db.x1e.16xlarge 64 32 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24, 26,
28, 30, 32

db.x1e.32xlarge 128 64 2 4, 8, 12, 16, 20, 1, 2

24, 28, 32, 36,
40, 44, 48, 52,
56, 60, 64

db.z1d.large 2 1 2 1 1, 2

db.z1d.xlarge 4 2 2 2 1, 2

db.z1d.2xlarge 8 4 2 2, 4 1, 2

db.z1d.3xlarge 12 6 2 2, 4, 6 1, 2

db.z1d.6xlarge 24 12 2 2, 4, 6, 8, 10, 1, 2
12

db.z1d.12xlarge 48 24 2 4, 6, 8, 10, 12, 1, 2

14, 16, 18, 20,
22, 24

Currently, you can configure the number of CPU cores and threads per core only when the following
conditions are met:

• You are configuring an Oracle DB instance. For information about the DB instance classes supported by
different Oracle database editions, see RDS for Oracle instance classes (p. 996)
• Your instance is using the Bring Your Own License (BYOL) licensing option. For more information about
Oracle licensing options, see Oracle licensing options (p. 994).

Note
You can use AWS CloudTrail to monitor and audit changes to the process configuration of
Amazon RDS for Oracle DB instances. For more information about using CloudTrail, see Working
with AWS CloudTrail and Amazon RDS (p. 564).

Setting the CPU cores and threads per CPU core for a DB
instance class
You can configure the number of CPU cores and threads per core for the DB instance class when you
perform the following operations:

• Creating an Amazon RDS DB instance (p. 147)

• Modifying an Amazon RDS DB instance (p. 256)
• Restoring from a DB snapshot (p. 355)
• Restoring a DB instance to a specified time (p. 395)

25
 Amazon Relational Database Service User Guide
Configuring the processor

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.

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.

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.

26
Amazon Relational Database Service User Guide
Configuring the processor

27
 Amazon Relational Database Service User Guide
Configuring the processor

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 defaults for the 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 on the Configuration tab. 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.

AWS CLI

You can set the processor features for a DB instance when you run one of the following AWS CLI
commands:

• create-db-instance

28
 Amazon Relational Database Service User Guide
Configuring the processor

• 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=<value>" "Name=threadsPerCore,Value=<value>"

The following are examples that configure the processor:

Examples
• Setting the number of CPU cores for a DB instance (p. 29)
• Setting the number of CPU cores and disabling multiple threads for a DB instance (p. 29)
• Viewing the valid processor values for a DB instance class (p. 30)
• Returning to default processor settings for a DB instance (p. 31)
• Returning to the default number of CPU cores for a DB instance (p. 31)
• Returning to the default number of threads per core for a DB instance (p. 32)

Setting the number of CPU cores for a DB instance

Example
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, macOS, 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

Setting the number of CPU cores and disabling multiple threads for a DB instance

Example
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 --apply-
immediately option.

29
 Amazon Relational Database Service User Guide
Configuring the processor

For Linux, macOS, 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

Viewing the valid processor values for a DB instance class

Example
You can view the valid processor values for a particular DB instance class by running the describe-
orderable-db-instance-options command and specifying the instance class for the --db-instance-
class 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"
}
],

30
 Amazon Relational Database Service User Guide
Configuring the processor

"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:

• 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.

In the output of the preceding commands, the values for the processor features are not null only if the
following conditions are met:

• You are using an Oracle DB instance.

• Your Oracle DB instance supports changing processor values.
• The current CPU core and thread settings are set to nondefault values.

If the preceding conditions aren't met, you can get the instance type using describe-db-instances. You
can get the processor information for this instance type by running the EC2 operation describe-instance-
types.

Returning to default processor settings for a DB instance

Example
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 --apply-
immediately option.

For Linux, macOS, 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

Returning to the default number of CPU cores for a DB instance

Example
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.

31
 Amazon Relational Database Service User Guide
Configuring the processor

For Linux, macOS, 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

Returning to the default number of threads per core for a DB instance

Example
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, macOS, or Unix:

aws rds modify-db-instance \

--processor-features "Name=threadsPerCore,Value=DEFAULT" \
--apply-immediately

For Windows:

aws rds modify-db-instance ^

--processor-features "Name=threadsPerCore,Value=DEFAULT" ^
--apply-immediately

RDS API
You can set the processor features for a DB instance when you call one of the following Amazon RDS API
operations:

• 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=<value>" "Name=threadsPerCore,Value=<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 operation and specifying the instance class for the
DBInstanceClass parameter. You can also use the following operations:

32
 Amazon Relational Database Service User Guide
Hardware specifications

• 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.

In the output of the preceding operations, the values for the processor features are not null only if the
following conditions are met:

• You are using an Oracle DB instance.

• Your Oracle DB instance supports changing processor values.
• The current CPU core and thread settings are set to nondefault values.

If the preceding conditions aren't met, you can get the instance type using DescribeDBInstances.
You can get the processor information for this instance type by running the EC2 operation
DescribeInstanceTypes.

Hardware specifications for DB instance classes

The following terminology is used to describe hardware specifications for DB instance classes:

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.
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.
Memory (GiB)

The RAM, in gibibytes, allocated to the DB instance. There is often a consistent ratio between
memory and vCPU. As an example, take the db.r4 instance class, which has a memory to vCPU ratio
similar to the db.r5 instance class. However, for most use cases the db.r5 instance class provides
better, more consistent performance than the db.r4 instance class.
VPC Only

The instance class is supported only for DB instances that are in a VPC based on the Amazon VPC
service. In some cases, you might want to use an instance class that requires a VPC but your current
DB instance isn't in a VPC. In these cases, start by moving your DB instance into a VPC. For more
information, see Moving a DB instance not in a VPC into a VPC (p. 1722).
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 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 User Guide for Linux Instances.
Max. Bandwidth (Mbps)

The maximum bandwidth in megabits per second. Divide by 8 to get the expected throughput in
megabytes per second.

33
 Amazon Relational Database Service User Guide
Hardware specifications

Important
General Purpose SSD (gp2) volumes for Amazon RDS DB instances have a throughput limit
of 250 MiB/s in most cases. However, the throughput limit can vary depending on volume
size. For more information, see Amazon EBS volume types in the Amazon EC2 User Guide
for Linux Instances. For information on estimating bandwidth for gp2 storage, see General
Purpose SSD storage (p. 40).
Network Performance

The network speed relative to other DB instance classes.

In the following table, you can find hardware details about the Amazon RDS DB instance classes.

For information about Amazon RDS DB engine support for each DB instance class, see Supported DB
engines for DB instance classes (p. 8).

Instance class vCPU ECU Memory VPC only EBS Max. Network
(GiB) optimized bandwidth performance
(mbps)

db.m6g – Standard instance classes powered by AWS Graviton2 processors

db.m6g.16xlarge 64 – 256 Yes Yes 19,000 25 Gbps

db.m6g.12xlarge 48 – 192 Yes Yes 13,500 20 Gbps

db.m6g.8xlarge 32 – 128 Yes Yes 9,500 12 Gbps

db.m6g.4xlarge 16 – 64 Yes Yes 6,800 Up to 10

Gbps

db.m6g.2xlarge* 8 – 32 Yes Yes Up to 4,750 Up to 10

Gbps

db.m6g.xlarge* 4 – 16 Yes Yes Up to 4,750 Up to 10

Gbps

db.m6g.large* 2 – 8 Yes Yes Up to 4,750 Up to 10

Gbps

db.m5d – Latest generation standard instance classes

db.m5d.24xlarge 96 345 384 Yes Yes 19,000 25 Gbps

db.m5d.16xlarge 64 262 256 Yes Yes 13,600 20 Gbps

db.m5d.12xlarge 48 173 192 Yes Yes 9,500 10 Gbps

db.m5d.8xlarge 32 131 128 Yes Yes 6,800 10 Gbps

db.m5d.4xlarge 16 61 64 Yes Yes 4,750 Up to 10

Gbps

db.m5d.2xlarge* 8 31 32 Yes Yes Up to 4,750 Up to 10

Gbps

db.m5d.xlarge* 4 15 16 Yes Yes Up to 4,750 Up to 10

Gbps

db.m5d.large* 2 10 8 Yes Yes Up to 4,750 Up to 10

Gbps

34
 Amazon Relational Database Service User Guide
Hardware specifications

Instance class vCPU ECU Memory VPC only EBS Max. Network
(GiB) optimized bandwidth performance
(mbps)

db.m5 – Latest generation standard instance classes

db.m5.24xlarge 96 345 384 Yes Yes 19,000 25 Gbps

db.m5.16xlarge 64 262 256 Yes Yes 13,600 20 Gbps

db.m5.12xlarge 48 173 192 Yes Yes 9,500 10 Gbps

db.m5.8xlarge 32 131 128 Yes Yes 6,800 10 Gbps

db.m5.4xlarge 16 61 64 Yes Yes 4,750 Up to 10

Gbps

db.m5.2xlarge* 8 31 32 Yes Yes Up to 4,750 Up to 10

Gbps

db.m5.xlarge* 4 15 16 Yes Yes Up to 4,750 Up to 10

Gbps

db.m5.large* 2 10 8 Yes Yes Up to 4,750 Up to 10

Gbps

db.m4 – Standard instance classes

db.m4.16xlarge 64 188 256 Yes Yes 10,000 25 Gbps

db.m4.10xlarge 40 124.5 160 Yes Yes 4,000 10 Gbps

db.m4.4xlarge 16 53.5 64 Yes Yes 2,000 High

db.m4.2xlarge 8 25.5 32 Yes Yes 1,000 High

db.m4.xlarge 4 13 16 Yes Yes 750 High

db.m4.large 2 6.5 8 Yes Yes 450 Moderate

db.m3 – Standard instance classes

db.m3.2xlarge 8 26 30 No Yes 1,000 High

db.m3.xlarge 4 13 15 No Yes 500 High

db.m3.large 2 6.5 7.5 No No — Moderate

db.m3.medium 1 3 3.75 No No — Moderate

db.m1 – Standard instance classes

db.m1.xlarge 4 4 15 No Yes 450 High

db.m1.large 2 2 7.5 No Yes 450 Moderate

db.m1.medium 1 1 3.75 No No — Moderate

db.m1.small 1 1 1.7 No No — Very Low

db.z1d – Memory-optimized instance classes

db.z1d.12xlarge 48 271 384 Yes Yes 14,000 25 Gbps

35
 Amazon Relational Database Service User Guide
Hardware specifications

Instance class vCPU ECU Memory VPC only EBS Max. Network
(GiB) optimized bandwidth performance
(mbps)

db.z1d.6xlarge 24 134 192 Yes Yes 7,000 10 Gbps

db.z1d.3xlarge 12 75 96 Yes Yes 3,500 Up to 10

Gbps

db.z1d.2xlarge 8 53 64 Yes Yes 2,333 Up to 10

Gbps

db.z1d.xlarge* 4 28 32 Yes Yes Up to 2,333 Up to 10

Gbps

db.z1d.large* 2 15 16 Yes Yes Up to 2,333 Up to 10

Gbps

db.x1e – Memory-optimized instance classes

db.x1e.32xlarge 128 340 3,904 Yes Yes 14,000 25 Gbps

db.x1e.16xlarge 64 179 1,952 Yes Yes 7,000 10 Gbps

db.x1e.8xlarge 32 91 976 Yes Yes 3,500 Up to 10

Gbps

db.x1e.4xlarge 16 47 488 Yes Yes 1,750 Up to 10

Gbps

db.x1e.2xlarge 8 23 244 Yes Yes 1,000 Up to 10

Gbps

db.x1e.xlarge 4 12 122 Yes Yes 500 Up to 10

Gbps

db.x1 – Memory-optimized instance classes

db.x1.32xlarge 128 349 1,952 Yes Yes 14,000 25 Gbps

db.x1.16xlarge 64 174.5 976 Yes Yes 7,000 10 Gbps

db.r6g – Memory-optimized instance classes powered by AWS Graviton2 processors

db.r6g.16xlarge 64 – 512 Yes Yes 19,000 25 Gbps

db.r6g.12xlarge 48 – 384 Yes Yes 13,500 20 Gbps

db.r6g.8xlarge 32 – 256 Yes Yes 9,000 12 Gbps

db.r6g.4xlarge 16 – 128 Yes Yes 4,750 Up to 10

Gbps

db.r6g.2xlarge* 8 – 64 Yes Yes Up to 4,750 Up to 10

Gbps

db.r6g.xlarge* 4 – 32 Yes Yes Up to 4,750 Up to 10

Gbps

db.r6g.large* 2 – 16 Yes Yes Up to 4,750 Up to 10

Gbps

36
 Amazon Relational Database Service User Guide
Hardware specifications

Instance class vCPU ECU Memory VPC only EBS Max. Network
(GiB) optimized bandwidth performance
(mbps)

db.r5d – Latest generation memory optimized instance classes

db.r5d.24xlarge 96 347 768 Yes Yes 19,000 25 Gbps

db.r5d.16xlarge 64 264 512 Yes Yes 13,600 20 Gbps

db.r5d.12xlarge 48 173 384 Yes Yes 9,500 10 Gbps

db.r5d.8xlarge 32 132 256 Yes Yes 6,800 10 Gbps

db.r5d.4xlarge 16 71 128 Yes Yes 4,750 Up to 10

Gbps

db.r5d.2xlarge* 8 38 64 Yes Yes Up to 4,750 Up to 10

Gbps

db.r5d.xlarge* 4 19 32 Yes Yes Up to 4,750 Up to 10

Gbps

db.r5d.large* 2 10 16 Yes Yes Up to 4,750 Up to 10

Gbps

db.r5b – Memory-optimized instance classes

db.r5b.24xlarge 96 347 768 Yes Yes 60,000 25 Gbps

db.r5b.16xlarge 64 264 512 Yes Yes 40,000 20 Gbps

db.r5b.12xlarge 48 173 384 Yes Yes 30,000 10 Gbps

db.r5b.8xlarge 32 132 256 Yes Yes 20,000 10 Gbps

db.r5b.4xlarge 16 71 128 Yes Yes 10,000 Up to 10

Gbps

db.r5b.2xlarge* 8 38 64 Yes Yes Up to 10,000 Up to 10

Gbps

db.r5b.xlarge* 4 19 32 Yes Yes Up to 10,000 Up to 10

Gbps

db.r5b.large* 2 10 16 Yes Yes Up to 10,000 Up to 10

Gbps

db.r5 – Latest generation memory-optimized instance classes

db.r5.24xlarge 96 347 768 Yes Yes 19,000 25 Gbps

db.r5.16xlarge 64 264 512 Yes Yes 13,600 20 Gbps

db.r5.12xlarge 48 173 384 Yes Yes 9,500 10 Gbps

db.r5.8xlarge 32 132 256 Yes Yes 6,800 10 Gbps

db.r5.4xlarge 16 71 128 Yes Yes 4,750 Up to 10

Gbps

37
 Amazon Relational Database Service User Guide
Hardware specifications

Instance class vCPU ECU Memory VPC only EBS Max. Network
(GiB) optimized bandwidth performance
(mbps)

db.r5.2xlarge* 8 38 64 Yes Yes Up to 4,750 Up to 10

Gbps

db.r5.xlarge* 4 19 32 Yes Yes Up to 4,750 Up to 10

Gbps

db.r5.large* 2 10 16 Yes Yes Up to 4,750 Up to 10

Gbps

db.r4 – Memory-optimized instance classes

db.r4.16xlarge 64 195 488 Yes Yes 14,000 25 Gbps

db.r4.8xlarge 32 99 244 Yes Yes 7,000 10 Gbps

db.r4.4xlarge 16 53 122 Yes Yes 3,500 Up to 10

Gbps

db.r4.2xlarge 8 27 61 Yes Yes 1,700 Up to 10

Gbps

db.r4.xlarge 4 13.5 30.5 Yes Yes 850 Up to 10

Gbps

db.r4.large 2 7 15.25 Yes Yes 425 Up to 10

Gbps

db.r3 – Memory-optimized instance classes (deprecated)

db.r3.8xlarge 32 104 244 No No — 10 Gbps

db.r3.4xlarge 16 52 122 No Yes 2,000 High

db.r3.2xlarge 8 26 61 No Yes 1,000 High

db.r3.xlarge 4 13 30.5 No Yes 500 Moderate

db.r3.large 2 6.5 15.25 No No — Moderate

db.m2 – Memory-optimized instance classes

db.m2.4xlarge 8 26 68.4 No Yes 1,000 High

db.m2.2xlarge 4 13 34.2 No Yes 500 Moderate

db.m2.xlarge 2 6.5 17.1 No No — Moderate

db.t3 – Next generation burstable performance instance classes

db.t3.2xlarge* 8 Variable 32 Yes Yes Up to 2,048 Up to 5 Gbps

db.t3.xlarge* 4 Variable 16 Yes Yes Up to 2,048 Up to 5 Gbps

db.t3.large* 2 Variable 8 Yes Yes Up to 2,048 Up to 5 Gbps

db.t3.medium* 2 Variable 4 Yes Yes Up to 1,536 Up to 5 Gbps

db.t3.small* 2 Variable 2 Yes Yes Up to 1,536 Up to 5 Gbps

38
 Amazon Relational Database Service User Guide
Hardware specifications

Instance class vCPU ECU Memory VPC only EBS Max. Network
(GiB) optimized bandwidth performance
(mbps)

db.t3.micro* 2 Variable 1 Yes Yes Up to 1,536 Up to 5 Gbps

db.t2 – Burstable performance instance classes

db.t2.2xlarge 8 Variable 32 Yes No — Moderate

db.t2.xlarge 4 Variable 16 Yes No — Moderate

db.t2.large 2 Variable 8 Yes No — Moderate

db.t2.medium 2 Variable 4 Yes No — Moderate

db.t2.small 1 Variable 2 Yes No — Low

db.t2.micro 1 Variable 1 Yes No — Low

* These DB instance classes can support maximum performance for 30 minutes at least once every
24 hours. For more information on baseline performance of these instance types, see Amazon EBS-
optimized instances in the Amazon EC2 User Guide for Linux Instances.

** These DB instance classes can support maximum performance for 30 minutes at least once every
24 hours. For more information on baseline performance of these instance types, see Amazon EBS-
optimized instances in the Amazon EC2 User Guide for Linux Instances.

*** The r3.8xlarge instance doesn't have dedicated EBS bandwidth and therefore doesn't offer EBS
optimization. On this instance, network traffic and Amazon EBS traffic share the same 10-gigabit
network interface.

39
 Amazon Relational Database Service User Guide
DB instance storage

Amazon RDS 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 (also known as standard). 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 64 tebibytes (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 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. 40).
• 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. 42).
• 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. 44).

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:

• MariaDB, MySQL, Oracle, and PostgreSQL database instances: 20 GiB–64 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, with a minimum of
100 IOPS. This relationship means that larger volumes have better performance. For example, baseline
performance for a 100-GiB volume is 300 IOPS. Baseline performance for a 1-TiB volume is 3,000 IOPS.
And baseline performance for a 5.34-TiB volume is 16,000 IOPS.

40
 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. 41).

Many workloads never deplete the burst balance, making General Purpose SSD an ideal storage choice
for many workloads. However, some workloads can exhaust the 3,000 IOPS burst storage credit balance,
so you should plan your storage capacity to meet the needs of your workloads.
Note
DB instances that use General Purpose SSD storage can experience much longer latency after
read replica creation, Multi-AZ conversion, and DB snapshot restoration than instances that
use Provisioned IOPS storage. If you need a DB instance with minimum latency after these
operations, we recommend using Provisioned IOPS storage.

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 for Amazon RDS DB
instances (p. 322).

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.
Note
The IOPS figure reaches its maximum value at a volume storage size of 5,334 GiB.

41
 Amazon Relational Database Service User Guide
Provisioned IOPS storage

Storage size (GiB) Base performance Maximum burst Seconds to fill empty
(IOPS) duration at 3,000 IOPS I/O credit balance
(seconds)

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

750 2,250 7,200 2,400

1,000 3,000 Infinite N/A

5,334 16,000 N/A 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.

(Credit balance)
Burst duration =  --------------------------------------
(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 a 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.
Note
Your database workload might not be able to achieve 100 percent of the IOPS that you have
provisioned. For more information, see Factors that affect storage performance (p. 45).

When you create a DB instance, you specify the IOPS rate and the size of the volume. The ratio of
IOPS to allocated storage (in GiB) must be at least 0.5. Amazon RDS provides that IOPS rate for the DB
instance until you change it.

The following table shows the range of Provisioned IOPS and storage size range for each database
engine.

42
 Amazon Relational Database Service User Guide
Provisioned IOPS storage

Database engine Range of Provisioned Range of storage

IOPS

MariaDB 1,000–80,000 IOPS 100 GiB–64 TiB

SQL Server Enterprise, Standard, 1,000–64,000 IOPS 20 GiB–16 TiB

and Web Editions

SQL Server Express Edition 1,000–64,000 IOPS 100 GiB–16 TiB

MySQL 1,000–80,000 IOPS 100 GiB–64 TiB

Oracle 1,000–256,000 IOPS 100 GiB–64 TiB

PostgreSQL 1,000–80,000 IOPS 100 GiB–64 TiB

Note
For SQL Server, the maximum IOPS of 64,000 is guaranteed only on Nitro-based instances that
are on the m5, m5d, r5, r5b, r5d, and z1d instance types. Other instance families guarantee
performance up to 32,000 IOPS.
For Oracle, the maximum IOPS of 256,000 is guaranteed only on Nitro-based instances that are
on the r5b instance type. Other instance families guarantee performance up to 80,000 IOPS.
For PostgreSQL, the maximum IOPS on the db.m5.8xlarge, db.m5.16xlarge, db.r5.8xlarge, and
db.r5.16xlarge instance classes is 40,000.
Important
Depending on the instance class you're using, you might see lower IOPS performance than the
maximum that RDS allows you to provision. For specific information on IOPS performance for
DB instance classes, see Amazon EBS-optimized instances. We recommend that you determine
the maximum IOPS for the instance class before setting a Provisioned IOPS value for your DB
instance.

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 primary DB instance. For example,
you might use General Purpose SSD for read replicas with a primary DB instance that uses Provisioned
IOPS SSD storage to reduce costs. However, your read replica's performance in this case might differ
from that of a configuration where both the primary 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 best performance from 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

43
 Amazon Relational Database Service User Guide
Magnetic storage

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 storage autoscaling.
• Doesn't support elastic volumes.
• Limited to a maximum size of 3 TiB.
• Limited to a maximum of 1,000 IOPS.

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. 555). Enhanced Monitoring provides more detailed I/O metrics; for more
information, see Using Enhanced Monitoring (p. 477).

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.

44
 Amazon Relational Database Service User Guide
Factors that affect storage performance

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.
• 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 EBS-
optimized instances and instances with 10-gigabit network connectivity.
Important
Depending on the instance class you're using, you might see lower IOPS performance than the
maximum that RDS allows you to provision. For specific information on IOPS performance for
DB instance classes, see Amazon EBS-optimized instances. We recommend that you determine
the maximum IOPS for the instance class before setting a Provisioned IOPS value for your DB
instance.

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. The following table shows the maximum
storage that each DB instance class can scale to for each database engine. All values are in tebibytes
(TiB).

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL
Server

db.m5 – Latest Generation Standard Instance Classes

db.m5.24xlarge 64 16 64 64 64

db.m5.16xlarge 64 16 64 64 64

db.m5.12xlarge 64 16 64 64 64

45
 Amazon Relational Database Service User Guide
Factors that affect storage performance

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL
Server

db.m5.8xlarge 64 16 64 64 64

db.m5.4xlarge 64 16 64 64 64

db.m5.2xlarge 64 16 64 64 64

db.m5.xlarge 64 16 64 64 64

db.m5.large 64 16 64 64 64

db.m4 – Current Generation Standard Instance Classes

db.m4.16xlarge 64 16 64 64 64

db.m4.10xlarge 64 16 64 64 64

db.m4.4xlarge 64 16 64 64 64

db.m4.2xlarge 64 16 64 64 64

db.m4.xlarge 64 16 64 64 64

db.m4.large 64 16 64 64 64

db.m3 – Previous Generation Standard Instance Classes

db.m3.2xlarge 6 16 6 6 6

db.m3.xlarge 6 16 6 6 6

db.m3.large 6 16 6 6 6

db.m3.medium 32 16 32 32 32

db.r5 – Latest Generation Memory Optimized Instance Classes

db.r5.24xlarge 64 16 64 64 64

db.r5.16xlarge 64 16 64 64 64

db.r5.12xlarge 64 16 64 64 64

db.r5.8xlarge 64 16 64 64 64

db.r5.4xlarge 64 16 64 64 64

db.r5.2xlarge 64 16 64 64 64

db.r5.xlarge 64 16 64 64 64

db.r5.large 64 16 64 64 64

db.r4 – Current Generation Memory Optimized Instance Classes

db.r4.16xlarge 64 16 64 64 64

db.r4.8xlarge 64 16 64 64 64

db.r4.4xlarge 64 16 64 64 64

46
 Amazon Relational Database Service User Guide
Factors that affect storage performance

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL
Server

db.r4.2xlarge 64 16 64 64 64

db.r4.xlarge 64 16 64 64 64

db.r4.large 64 16 64 64 64

db.r3 – Previous Generation Memory Optimized Instance Classes

db.r3.8xlarge 64 16 64 64 64

db.r3.4xlarge 64 16 64 64 64

db.r3.2xlarge 64 16 64 64 64

db.r3.xlarge 64 16 64 64 64

db.r3.large 64 16 64 64 64

db.t3 – Latest Generation Burstable Performance Instance Classes

db.t3.2xlarge 16 16 16 64 64

db.t3.xlarge 16 16 16 64 64

db.t3.large 16 16 16 64 64

db.t3.medium 16 16 16 32 32

db.t3.small 16 16 16 32 16

db.t3.micro 16 16 16 32 16

db.t2 – Current Generation Burstable Performance Instance Classes

db.t2.2xlarge 64 16 64 64 64

db.t2.xlarge 64 16 64 64 64

db.t2.large 64 16 64 64 64

db.t2.medium 32 16 32 32 32

db.t2.small 16 16 16 16 16

db.t2.micro 16 16 16 16 16

db.x1e – Latest Generation Memory Optimized Instance Classes

db.x1e.32xlarge   16   64  

db.x1e.16xlarge   16   64  

db.x1e.8xlarge   16   64  

db.x1e.4xlarge   16   64  

db.x1e.2xlarge   16   64  

db.x1e.xlarge   16   64  

47
 Amazon Relational Database Service User Guide
Factors that affect storage performance

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL
Server

db.x1 – Current Generation Memory Optimized Instance Classes

db.x1.32xlarge   16   64  

db.x1.16xlarge   16   64  

For Oracle, scaling up to 80,000 IOPS is only supported on the following instance classes.

• db.m5.24xlarge
• db.r5.24xlarge
• db.x1.32xlarge
• db.x1e.32xlarge

For more details on all instance classes supported, see Previous generation DB instances.

48
 Amazon Relational Database Service User Guide
Regions, Availability Zones, and Local Zones

Regions, Availability Zones, and Local Zones

Amazon cloud computing resources are hosted in multiple locations world-wide. These locations
are composed of AWS Regions, Availability Zones, and Local Zones. Each AWS Region is a separate
geographic area. Each AWS Region has multiple, isolated locations known as Availability Zones.
Note
For information about finding the Availability Zones for an AWS Region, see Describing your
Regions, Availability Zones, and Local Zones in the Amazon EC2 documentation.

By using Local Zones, you can place resources, such as compute and storage, in multiple locations closer
to your users. Amazon RDS enables you to place resources, such as DB 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 is 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 AWS_DEFAULT_REGION environment variable, or it can be overridden by using the --region
parameter with the AWS Command Line Interface (AWS CLI). For more information, see Configuring the
AWS Command Line Interface, specifically the sections about environment variables and command line
options.

Amazon RDS supports special AWS Regions called AWS GovCloud (US) that are designed to allow
US government agencies and customers to move more sensitive workloads into the cloud. The AWS
GovCloud (US) Regions address the US government's specific regulatory and compliance requirements.
For more information, see What is AWS GovCloud (US)?

To create or work with an Amazon RDS DB instance in a specific AWS Region, use the corresponding
regional service endpoint.

AWS Regions
Each AWS Region is designed to be isolated from the other AWS Regions. This design achieves the
greatest possible fault tolerance and stability.

49
 Amazon Relational Database Service User Guide
AWS Regions

When you view your resources, you see only the resources that are tied to the AWS Region that you
specified. This is because AWS Regions are isolated from each other, and we don't automatically replicate
resources across AWS Regions.

Region availability
The following table shows the AWS Regions where Amazon RDS is currently available and the endpoint
for each Region.

Region Region Endpoint Protocol

Name

US East us-east-2 rds.us-east-2.amazonaws.com HTTPS

(Ohio)
rds-fips.us-east-2.amazonaws.com HTTPS

US East (N. us-east-1 rds.us-east-1.amazonaws.com HTTPS

Virginia)
rds-fips.us-east-1.amazonaws.com HTTPS

US us-west-1 rds.us-west-1.amazonaws.com HTTPS

West (N.
California) rds-fips.us-west-1.amazonaws.com HTTPS

US West us-west-2 rds.us-west-2.amazonaws.com HTTPS

(Oregon)
rds-fips.us-west-2.amazonaws.com HTTPS

Africa af-south-1 rds.af-south-1.amazonaws.com HTTPS

(Cape
Town)

Asia ap-east-1 rds.ap-east-1.amazonaws.com HTTPS

Pacific
(Hong
Kong)

Asia ap- rds.ap-south-1.amazonaws.com HTTPS

Pacific south-1
(Mumbai)

Asia ap- rds.ap-northeast-3.amazonaws.com HTTPS

Pacific northeast-3
(Osaka)

Asia ap- rds.ap-northeast-2.amazonaws.com HTTPS

Pacific northeast-2
(Seoul)

Asia ap- rds.ap-southeast-1.amazonaws.com HTTPS

Pacific southeast-1
(Singapore)

Asia ap- rds.ap-southeast-2.amazonaws.com HTTPS

Pacific southeast-2
(Sydney)

50
 Amazon Relational Database Service User Guide
AWS Regions

Region Region Endpoint Protocol

Name

Asia ap- rds.ap-northeast-1.amazonaws.com HTTPS

Pacific northeast-1
(Tokyo)

Canada ca- rds.ca-central-1.amazonaws.com HTTPS

(Central) central-1
rds-fips.ca-central-1.amazonaws.com HTTPS

China cn-north-1 rds.cn-north-1.amazonaws.com.cn HTTPS

(Beijing)

China cn- rds.cn-northwest-1.amazonaws.com.cn HTTPS

(Ningxia) northwest-1

Europe eu- rds.eu-central-1.amazonaws.com HTTPS

(Frankfurt) central-1

Europe eu-west-1 rds.eu-west-1.amazonaws.com HTTPS

(Ireland)

Europe eu-west-2 rds.eu-west-2.amazonaws.com HTTPS

(London)

Europe eu- rds.eu-south-1.amazonaws.com HTTPS

(Milan) south-1

Europe eu-west-3 rds.eu-west-3.amazonaws.com HTTPS

(Paris)

Europe eu-north-1 rds.eu-north-1.amazonaws.com HTTPS

(Stockholm)

Middle me- rds.me-south-1.amazonaws.com HTTPS

East south-1
(Bahrain)

South sa-east-1 rds.sa-east-1.amazonaws.com HTTPS

America
(São
Paulo)

AWS us-gov- rds.us-gov-east-1.amazonaws.com HTTPS

GovCloud east-1
(US-East)

AWS us-gov- rds.us-gov-west-1.amazonaws.com HTTPS

GovCloud west-1
(US-West)

If you do not explicitly specify an endpoint, the US West (Oregon) endpoint is the default.

When you work with a DB instance using the AWS CLI or API operations, make sure that you specify its
regional endpoint.

51
 Amazon Relational Database Service User Guide
Availability Zones

Availability Zones
When you create a DB instance, you can choose an Availability Zone or have Amazon RDS choose one for
you randomly. An Availability Zone is represented by an AWS Region code followed by a letter identifier
(for example, us-east-1a).

You can't choose the Availability Zones for the primary and secondary DB instances in a Multi-AZ DB
deployment. Amazon RDS chooses them for you randomly. For more information about Multi-AZ
deployments, see High availability (Multi-AZ) for Amazon RDS (p. 53).
Note
Random selection of Availability Zones by RDS doesn't guarantee an even distribution of DB
instances among Availability Zones within a single account or DB subnet group. You can request
a specific AZ when you create or modify a Single-AZ instance, and you can use more-specific DB
subnet groups for Multi-AZ instances. For more information, see Creating an Amazon RDS DB
instance (p. 147) and Modifying an Amazon RDS DB instance (p. 256).

Local Zones
A Local Zone is an extension of an AWS Region that is geographically close to your users. You can extend
any VPC from the parent AWS Region into Local Zones by creating a new subnet and assigning it to the
AWS Local Zone. When you create a subnet in a Local Zone, your VPC is extended to that Local Zone. The
subnet in the Local Zone operates the same as other subnets in your VPC.

When you create a DB instance, you can choose a subnet in a Local Zone. Local Zones have their own
connections to the internet and support AWS Direct Connect. Thus, resources created in a Local Zone can
serve local users with very low-latency communications. For more information, see AWS Local Zones.

A Local Zone is represented by an AWS Region code followed by an identifier that indicates the location,
for example us-west-2-lax-1a.
Note
A Local Zone can't be included in a Multi-AZ deployment.

To use a Local Zone

1. Enable the Local Zone in the Amazon EC2 console.

For more information, see Enabling Local Zones in the Amazon EC2 User Guide for Linux Instances.
2. Create a subnet in the Local Zone.

For more information, see Creating a subnet in your VPC in the Amazon VPC User Guide.
3. Create a DB subnet group in the Local Zone.

When you create a DB subnet group, choose the Availability Zone group for the Local Zone.

For more information, see Creating a DB instance in a VPC (p. 1717).

4. Create a DB instance that uses the DB subnet group in the Local Zone.

For more information, see Creating an Amazon RDS DB instance (p. 147).

Important
Currently, Local Zones are only available in the US West (Oregon) Region. In this AWS Region,
the Los Angeles AWS Local Zone is available.

52
 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. Multi-
AZ deployments for MariaDB, MySQL, Oracle, and PostgreSQL DB instances use Amazon's failover
technology. SQL Server DB instances use SQL Server Database Mirroring (DBM) or Always On Availability
Groups (AGs). For information on SQL Server version support for Multi-AZ, see Multi-AZ deployments for
Microsoft SQL Server (p. 705).

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,
Availability Zones, and Local Zones (p. 49).
Note
The high-availability feature isn't a scaling solution for read-only scenarios; you can't use a
standby replica to serve read traffic. To serve read-only traffic, you use a read replica instead. For
more information, see Working with read replicas (p. 284).

Using the RDS console, you can create a Multi-AZ deployment by simply specifying Multi-AZ
when creating a DB instance. You can use the console to convert existing DB instances to Multi-AZ
deployments by modifying the DB instance and specifying the Multi-AZ option. You can also specify a
Multi-AZ deployment with the AWS CLI or Amazon RDS API. Use the create-db-instance or modify-db-
instance CLI command, or the CreateDBInstance or ModifyDBInstance API operation.

The RDS console shows the Availability Zone of the standby replica (called the secondary AZ). You can
also use the describe-db-instances CLI command or the DescribeDBInstances API operation to find the
secondary AZ.

DB instances using Multi-AZ deployments can have increased write and commit latency compared to a
Single-AZ deployment, due to the synchronous data replication that occurs. You might have a change
in latency if your deployment fails over to the standby replica, although AWS is engineered with low-
latency network connectivity between Availability Zones. For production workloads, we recommend

53
 Amazon Relational Database Service User Guide
Modifying a DB instance to be a Multi-AZ deployment

that you use Provisioned IOPS and DB instance classes that are optimized for Provisioned IOPS for fast,
consistent performance. For more information about DB instance classes, see DB instance classes (p. 7).

Modifying a DB instance to be a Multi-AZ deployment

If you have a DB instance in a Single-AZ deployment and modify it to a Multi-AZ deployment (for engines
other than 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.

For information about modifying a DB instance, see Modifying an Amazon RDS DB instance (p. 256).
Important
This action avoids downtime when you convert from Single-AZ to Multi-AZ, but you can
experience a performance impact during and after converting to Multi-AZ. This impact can be
significant for large write-intensive DB instances.
To enable Multi-AZ for a DB instance, RDS takes a snapshot of the primary DB instance's EBS
volume and restores it on the newly created standby replica, and then synchronizes both
volumes. New volumes created from existing EBS snapshots load lazily in the background.
This capability permits large volumes to be restored from a snapshot quickly, but there is
the possibility of added latency during and after the modification is complete. For more
information, see Restoring an Amazon EBS volume from a snapshot in the Amazon EC2
documentation.

After 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. 493).

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 to reflect the new Availability Zone.
Note
You can force a failover manually when you reboot a DB instance. For more information, see
Rebooting a DB instance (p. 282).

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 conditions described in the following table occurs. You can view these
failover reasons in the event log.

Failover reason Description

The operating system underlying the RDS A failover was triggered during the maintenance
database instance is being patched in an offline window for an OS patch or a security update.
operation.
For more information, see Maintaining a DB
instance (p. 270).

The primary host of the RDS Multi-AZ instance is The Multi-AZ deployment detected an impaired
unhealthy. primary DB instance and failed over.

54
 Amazon Relational Database Service User Guide
Failover process for Amazon RDS

Failover reason Description

The primary host of the RDS Multi-AZ instance is RDS monitoring detected a network reachability
unreachable due to loss of network connectivity. failure to the primary DB instance and triggered a
failover.

The RDS instance was modified by customer. An RDS DB instance modification triggered a
failover.

For more information, see Modifying an Amazon

RDS DB instance (p. 256).

The RDS Multi-AZ primary instance is busy and The primary DB instance is unresponsive. We
unresponsive. recommend that you do the following:

• Examine the event and CloudWatch logs for

excessive CPU, memory, or swap space usage.
For more information, see Using Amazon
RDS event notification (p. 493) and Getting
CloudWatch Events and Amazon EventBridge
events for Amazon RDS (p. 558).
• Evaluate your workload to determine whether
you're using the appropriate DB instance
class. For more information, see DB instance
classes (p. 7).
• Use Enhanced Monitoring for real-
time operating system metrics. For
more information, see Using Enhanced
Monitoring (p. 477).
• Use Performance Insights to help analyze
any issues that affect your DB instance's
performance. For more information, see
Using Performance Insights on Amazon
RDS (p. 418).

For more information on these recommendations,

see Overview of monitoring Amazon
RDS (p. 406) and Best practices for Amazon
RDS (p. 134).

The storage volume underlying the primary The Multi-AZ deployment detected a storage issue
host of the RDS Multi-AZ instance experienced a on the primary DB instance and failed over.
failure.

The user requested a failover of the DB instance. You rebooted the DB instance and chose Reboot
with failover.

For more information, see Rebooting a DB

instance (p. 282).

There are several ways to determine if your Multi-AZ DB instance has failed over:

• DB event subscriptions can be set up to notify you by email or SMS that a failover has been initiated.
For more information about events, see Using Amazon RDS event notification (p. 493).
• You can view your DB events by using the Amazon RDS console or API operations.

55
 Amazon Relational Database Service User Guide
Failover process for Amazon RDS

• You can view the current state of your Multi-AZ deployment by using the Amazon RDS console and API
operations.

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. 134).

Setting the JVM TTL for DNS name lookups

The failover mechanism automatically changes the Domain Name System (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. In a Java virtual machine (JVM) environment, due to how the Java DNS
caching mechanism works, you might need to reconfigure JVM settings.

The JVM caches DNS name lookups. When the JVM resolves a hostname to an IP address, it caches the IP
address for a specified period of time, known as the time-to-live (TTL).

Because AWS resources use DNS name entries that occasionally change, we recommend that you
configure your JVM with a TTL value of no more than 60 seconds. Doing this makes sure that when a
resource's IP address changes, your application can receive and use the resource's new IP address by
requerying the DNS.

On some Java configurations, the JVM default TTL is set so that it never refreshes DNS entries until
the JVM is restarted. Thus, if the IP address for an AWS resource changes while your application is still
running, it can't use that resource until you manually restart the JVM and the cached IP information
is refreshed. In this case, it's crucial to set the JVM's TTL so that it periodically refreshes its cached IP
information.
Note
The default TTL can vary according to the version of your JVM and whether a security manager
is installed. Many JVMs provide a default TTL less than 60 seconds. If you're using such a JVM
and not using a security manager, you can ignore the rest of this topic. For more information on
security managers in Oracle, see The security manager in the Oracle documentation.

To modify the JVM's TTL, set the networkaddress.cache.ttl property value. Use one of the
following methods, depending on your needs:

• To set the property value globally for all applications that use the JVM, set
networkaddress.cache.ttl in the $JAVA_HOME/jre/lib/security/java.security file.

networkaddress.cache.ttl=60

• To set the property locally for your application only, set networkaddress.cache.ttl in your
application's initialization code before any network connections are established.

java.security.Security.setProperty("networkaddress.cache.ttl" , "60");

56
 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). Pricing is listed on a per-hour basis, but bills are calculated down to the
second and show times in decimal form. RDS usage is billed in one second increments, with a minimum
of 10 minutes. For more information, see DB instance classes (p. 7).
• 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 Amazon RDS DB instance storage (p. 40).
• 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. Provisioned storage for EBS volumes are billed in
one second increments, with a minimum of 10 minutes.
• 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. Per second billing doesn't apply to backup storage (metered in GB-month).

For more information, see Backing up and restoring an Amazon RDS DB instance (p. 333).
• 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. Pricing is listed on a
per-hour basis, but bills are calculated down to the second and show times in decimal form. RDS usage
is now billed in one second increments, with a minimum of 10 minutes.
• Reserved Instances – Reserve a DB instance for a one-year or three-year term and get a significant
discount compared to the on-demand DB instance pricing. With Reserved Instance usage, you can
launch, delete, start, or stop multiple instances within an hour and get the Reserved Instance benefit
for all of the instances.

For Amazon RDS pricing information, see the Amazon RDS product page.

Topics
• On-Demand DB instances for Amazon RDS (p. 58)
• Reserved DB instances for Amazon RDS (p. 59)

57
 Amazon Relational Database Service User Guide
On-Demand DB instances

On-Demand DB instances for Amazon RDS

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). 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. Pricing is listed on a per-hour
basis, but bills are calculated down to the second and show times in decimal form. Amazon RDS usage
is billed in one-second increments, with a minimum of 10 minutes. In the case of billable configuration
change, such as scaling compute or storage capacity, you're charged a 10-minute minimum. 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. 410).

Stopped DB instances
While your DB instance is stopped, you're 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 aren't charged for DB instance hours.

Multi-AZ DB instances
If you specify that your DB instance should be a Multi-AZ deployment, you're billed according to the
Multi-AZ pricing posted on the Amazon RDS pricing page.

58
 Amazon Relational Database Service User Guide
Reserved DB instances

Reserved DB instances for Amazon RDS

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 on-
demand 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 classes (p. 7).

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

59
 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 and database engine. Size-flexible reserved DB instances can only
scale in their instance class type. For example, a reserved DB instance for a db.m4.large can apply to a
db.m4.xlarge, but not to a db.m5.large, because db.m4 and db.m5 are different instance class types.

Reserved DB instance benefits also apply for both Multi-AZ and Single-AZ configurations. Flexibility
means that you can move freely between configurations within the same DB instance class type. For
example, you can move from a Single-AZ deployment running on one large DB instance (four normalized
units) to a Multi-AZ deployment running on two small DB instances (2*2 = 4 normalized units).

Size-flexible reserved DB instances are available for the following Amazon RDS database engines:

• MariaDB
• MySQL
• Oracle, Bring Your Own License
• PostgreSQL

For details about using size-flexible reserved instances with Aurora, see Reserved DB instances for
Aurora.

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

6xlarge 48 96

8xlarge 64 128

10xlarge 80 160

12xlarge 96 192

16xlarge 128 256

24xlarge 192 384

32xlarge 256 512

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.

60
 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 RDS for 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 RDS for 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.

61
 Amazon Relational Database Service User Guide
Reserved DB instances

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).

Working with reserved DB instances

You can use the AWS Management Console, the AWS CLI, and the RDS API to work with 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.

62
 Amazon Relational Database Service User Guide
Reserved DB 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.

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 Instances dialog box appears, with a summary of the reserved DB
instance attributes that you've selected and the payment due.

63
 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
Order 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.

64
 Amazon Relational Database Service User Guide
Reserved DB instances

Example of getting 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 Multi-AZ Duration Fixed

Price Usage Price Description Offering Type
OFFERING 438012d3-4052-4cc7-b2e3-8d3372e0e706 db.m1.large y 1y 1820.00
USD 0.368 USD mysql Partial Upfront
OFFERING 649fd0c8-cf6d-47a0-bfa6-060f8e75e95f db.m1.small n 1y 227.50
USD 0.046 USD mysql Partial Upfront
OFFERING 123456cd-ab1c-47a0-bfa6-12345667232f db.m1.small n 1y 162.00
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 y 1y 700.00
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 n 1y 4242.00
USD 2.42 USD mysql No Upfront

After you have information about the available reserved DB instance offerings, you can use the
information to purchase an offering.

To purchase a reserved DB instance, use the AWS CLI command purchase-reserved-db-instances-

offering 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 track them.

Example of purchasing a reserved DB instance

The following example purchases the reserved DB instance offering with ID 649fd0c8-cf6d-47a0-
bfa6-060f8e75e95f, and assigns the identifier of MyReservation.

For Linux, macOS, 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:

65
 Amazon Relational Database Service User Guide
Reserved DB instances

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.

To get information about reserved DB instances for your AWS account, call the AWS CLI command
describe-reserved-db-instances, as shown in the following example.

Example of getting your reserved DB instances

aws rds describe-reserved-db-instances

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-09T23:37:44.720Z 1y
455.00 USD 0.092 USD 1 retired mysql Partial Upfront

RDS API

You can use the RDS API to work with reserved DB instances:

• To get information about available reserved DB instance offerings, call the Amazon RDS API operation
DescribeReservedDBInstancesOfferings.
• After you have information about the available reserved DB instance offerings, you can use the
information to purchase an offering. Call the PurchaseReservedDBInstancesOffering RDS API
operation with the following parameters:
• --reserved-db-instances-offering-id – The ID of the offering that you want to purchase.
• --reserved-db-instance-id – You can assign your own identifier to the reserved DB instances
that you purchase to help track them.
• After you have purchased reserved DB instances, you can get information about your reserved DB
instances. Call the DescribeReservedDBInstances RDS API operation.

66
 Amazon Relational Database Service User Guide
Sign up for AWS

Setting up for Amazon RDS

Complete the tasks in this section 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. 67)
• Create an IAM user (p. 67)
• Determine requirements (p. 69)
• Provide access to your DB instance in your VPC by creating a security group (p. 70)

Sign up for AWS

If you have an AWS account already, skip to the next section, Create an IAM user (p. 67).

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://portal.aws.amazon.com/billing/signup.
2. Follow the online instructions.

Part of the sign-up procedure involves receiving a phone call and entering a verification code on 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.

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

67
 Amazon Relational Database Service User Guide
Create an IAM user

To create an administrator user for yourself and add the user to an administrators group
(console)

1. Sign in to the IAM console as the account owner by choosing Root user and entering your AWS
account email address. On the next page, enter your password.
Note
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.
2. In the navigation pane, choose Users and then choose Add user.
3. For User name, enter Administrator.
4. Select the check box next to AWS Management Console access. Then select Custom password, and
then enter your new password in the text box.
5. (Optional) By default, AWS requires the new user to create a new password when first signing in. You
can clear the check box next to User must create a new password at next sign-in to allow the new
user to reset their password after they sign in.
6. Choose Next: Permissions.
7. Under Set permissions, choose Add user to group.
8. Choose Create group.
9. In the Create group dialog box, for Group name enter Administrators.
10. Choose Filter policies, and then select AWS managed -job function to filter the table contents.
11. In the policy list, select the check box for AdministratorAccess. Then choose Create group.
Note
You must activate IAM user and role access to Billing before you can use the
AdministratorAccess permissions to access the AWS Billing and Cost Management
console. To do this, follow the instructions in step 1 of the tutorial about delegating access
to the billing console.
12. 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.
13. Choose Next: Tags.
14. (Optional) Add metadata to the user by attaching tags as key-value pairs. For more information
about using tags in IAM, see Tagging IAM entities in the IAM User Guide.
15. 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 that restrict user permissions to specific AWS resources,
see 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.

68
 Amazon Relational Database Service User Guide
Determine requirements

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 Programmatic access, Installing the AWS CLI, and the Amazon RDS API reference.

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 classes (p. 7).
• 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. 1705).

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. 1721).
• 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. 1721).
• 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. 1705).

69
 Amazon Relational Database Service User Guide
Provide access to your DB instance in
your VPC by creating a security group

• 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. 1715).
• 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. 1691).
• 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.
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. 53).
• 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 Identity and access management in Amazon RDS (p. 1634).
• 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
Amazon RDS DB instance storage (p. 40).

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.

70
 Amazon Relational Database Service User Guide
Provide access to your DB instance in
your VPC by creating a security group

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 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.
2. 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.
3. In the navigation pane, choose Security Groups.
4. Choose Create Security Group.
5. 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.

a. For Type, choose Custom TCP Rule.

b. For Port Range, type the port value to use for your DB instance.
c. For Source, choose a security group name or type the IP address range (CIDR value) from where
you access the instance. If you choose My IP, this allows access to the DB instance from the IP
address detected in your browser.
8. Choose Add another rule if you need to add more IP addresses or different port ranges.
9. (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 (EC2-
Classic platform) (p. 1691) 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. 73)

Microsoft SQL Server Creating a Microsoft SQL Server DB instance and connecting to it (p. 80)

MySQL Creating a MySQL DB instance and connecting to a database on a MySQL DB

instance (p. 86)

71
 Amazon Relational Database Service User Guide
Provide access to your DB instance in
your VPC by creating a security group

Database engine Documentation

Oracle Creating an Oracle DB instance and connecting to a database on an Oracle

DB instance (p. 93)

PostgreSQL Creating a PostgreSQL DB instance and connecting to a database on a

PostgreSQL DB instance (p. 99)

Note
If you can't connect to a DB instance after you create it, see the troubleshooting information in
Can't connect to Amazon RDS DB instance (p. 1733).

72
 Amazon Relational Database Service User Guide
Creating a MariaDB DB instance
and connecting to a database

Getting started with Amazon RDS

In the following examples, you can find how to create and connect to a DB instance using Amazon
Relational Database Service (Amazon RDS). You can create a DB instance that uses MariaDB, MySQL,
Microsoft SQL Server, Oracle, or PostgreSQL.
Important
Before you can create or connect to a DB instance, you must complete the tasks in Setting up for
Amazon RDS (p. 67).

Creating a DB instance and connecting to a database on a DB instance is slightly different for each of the
DB engines. Choose one of the following DB engines 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. 73)
• Creating a Microsoft SQL Server DB instance and connecting to it (p. 80)
• Creating a MySQL DB instance and connecting to a database on a MySQL DB instance (p. 86)
• Creating an Oracle DB instance and connecting to a database on an Oracle DB instance (p. 93)
• Creating a PostgreSQL DB instance and connecting to a database on a PostgreSQL DB
instance (p. 99)
• Tutorial: Create a web server and an Amazon RDS DB instance (p. 108)

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. After you create 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
Before you can create or connect to a DB instance, you must complete the tasks in Setting up for
Amazon RDS (p. 67).

Topics
• Creating a MariaDB DB instance (p. 73)
• Connecting to a database on a DB instance running the MariaDB database engine (p. 77)
• Deleting a DB instance (p. 79)

Creating a MariaDB DB instance

The basic building block of Amazon RDS is the DB instance. This environment is where you run your
MariaDB databases.

73
 Amazon Relational Database Service User Guide
Creating a MariaDB DB instance

Console
You can create a DB instance running MariaDB with the AWS Management Console with Easy Create
enabled or not enabled. With Easy Create enabled, you specify only the DB engine type, DB instance size,
and DB instance identifier. Easy Create uses the default setting for other configuration options. With
Easy Create not enabled, you specify more configuration options when you create a database, including
ones for availability, security, backups, and maintenance.

In this example, you use Easy Create to create a DB instance running the MariaDB database engine with a
db.t2.micro DB instance class.
Note
For information about creating DB instances with Easy Create not enabled, see Creating an
Amazon RDS DB instance (p. 147).

To create a MariaDB DB instance with Easy Create enabled

1. Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.
2. In the upper-right corner of the Amazon RDS console, choose the AWS Region in which you want to
create the DB instance.
3. In the navigation pane, choose Databases.
4. Choose Create database and make sure that Easy Create is chosen.

5. In Configuration, choose MariaDB.

6. For DB instance size, choose Free tier.
7. For DB instance identifier, enter a name for the DB instance, or leave the default name.
8. For Master username, enter a name for the master user, or leave the default name.

The Create database page should look similar to the following image.

74
Amazon Relational Database Service User Guide
Creating a MariaDB DB instance

75
 Amazon Relational Database Service User Guide
Creating a MariaDB DB instance

9. To use an automatically generated master password for the DB instance, make sure that the Auto
generate a password check box is chosen.

To enter your master password, clear the Auto generate a password check box, and then enter the
same password in Master password and Confirm password.
10. (Optional) Open View default settings for Easy create.

You can examine the default settings used when Easy Create is enabled. If you want to change one
or more settings during database creation, choose Standard Create to set them. The Editable after
database creation column shows which options you can change after database creation. To change
a setting with No in that column, use Standard Create. For settings with Yes in that column, you can
either use Standard Create or modify the DB instance after it's created to change the setting.
11. Choose Create database.

If you chose to use an automatically generated password, the View credential details button
appears on the Databases page.

To view the master user name and password for the DB instance, choose View credential details.

To connect to the DB instance as the master user, use the user name and password that appear.
Important
You can't view the master user password again. If you don't record it, you might have to
change it. If you need to change the master user password after the DB instance is available,
you can modify the DB instance to do so. For more information about modifying a DB
instance, see Modifying an Amazon RDS DB instance (p. 256).
12. For Databases, choose the name of the new Maria DB instance.

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.

76
 Amazon Relational Database Service User Guide
Connecting to a database on a
DB instance running MariaDB

Connecting to a database on a DB instance running

the MariaDB database engine
After 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 Maria DB
instance using the mysql command-line tool. One GUI-based application you can use to connect is
HeidiSQL. For more information, see the Download HeidiSQL page. For more information on using
MariaDB, see the MariaDB documentation.

To connect to a database on a DB instance using the mysql command-line tool

1. Find the endpoint (DNS name) and port number for your DB instance.

a. Open the RDS console and then choose Databases to display a list of your DB instances.
b. Choose the Maria DB instance name to display its details.
c. On the Connectivity & security tab, copy the endpoint. Also note the port number. You need
both the endpoint and the port number to connect to the DB instance.

77
 Amazon Relational Database Service User Guide
Connecting to a database on a
DB instance running MariaDB

2. Enter the following command at a command prompt on a client computer to connect to a database
on a Maria DB instance. Substitute the DNS name (endpoint) for your DB instance for <endpoint>,
the master user name you used for <mymasteruser>, and provide the master password you used
when prompted for a password.

PROMPT> mysql -h <endpoint> -P 3306 -u <mymasteruser> -p

78
 Amazon Relational Database Service User Guide
Deleting a DB instance

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 >

For more information about connecting to a MariaDB DB instance, see Connecting to a DB instance
running the MariaDB database engine (p. 595). For information on connection issues, see Can't connect
to Amazon RDS DB instance (p. 1733).

Deleting a DB instance
After 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 Databases.
3. Choose the DB instance you want to delete.
4. For Actions, choose Delete.
5. For Create final snapshot?, choose No, and select the acknowledgment.
6. Choose Delete.

79
 Amazon Relational Database Service User Guide
Creating a SQL Server DB instance and connecting to it

Creating a Microsoft SQL Server DB instance and

connecting to it
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

You can create a DB instance running Microsoft SQL Server with the AWS Management Console with
Easy create enabled or not enabled. With Easy create enabled, you specify only the DB engine type, DB
instance size, and DB instance identifier. Easy create uses the default settings for other configuration
options. With Easy create not enabled (Standard create), you specify more configuration options when
you create a database, including ones for availability, security, backups, and maintenance.

For this example, you use Easy create to create a DB instance running SQL Server Express Edition with a
db.t2.micro DB instance class.
Note
For information about creating DB instances with Standard create, see Creating an Amazon RDS
DB instance (p. 147).

To create a Microsoft SQL Server DB instance with Easy create

1. Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.
2. In the upper-right corner of the Amazon RDS console, choose the AWS Region in which you want to
create the DB instance.
3. In the navigation pane, choose Databases.
4. Choose Create database.
5. Choose Easy create.

6. From Engine type, choose Microsoft SQL Server.

7. For DB instance size, choose Free tier.

80
 Amazon Relational Database Service User Guide
Creating a sample SQL Server DB instance

8. For DB instance identifier, enter a name for the DB instance, or leave the default name.
9. For Master username, enter a name for the master user, or leave the default name.
10. To use an automatically generated master password for the DB instance, choose the Auto generate
a password check box.

To enter your master password, clear the Auto generate a password check box, and then enter the
same password in Master password and Confirm password.

The Create database page should look similar to the following image.

11. (Optional) Expand View default settings for Easy create.

81
 Amazon Relational Database Service User Guide
Creating a sample SQL Server DB instance

You can examine the default settings used when Easy create is enabled. If you want to change one
or more settings during database creation, choose Standard create to set them. The Editable after
database is created column shows which options you can change after database creation. To change
a setting with No in that column, use Standard create. For settings with Yes in that column, you can
either use Standard create or modify the DB instance after it's created to change the setting.
12. Choose Create database.

If you chose to use an automatically generated password, the View credential details button
appears on the Databases page.

To view the master user name and password for the DB instance, choose View credential details.

To connect to the DB instance as the master user, use the user name and password that appear.
Important
You can't view the master user password again. If you don't record it, you might have to
change it. If you need to change the master user password after the DB instance is available,
you can modify the DB instance to do so. For more information about modifying a DB
instance, see Modifying an Amazon RDS DB instance (p. 256).
13. For Databases, choose the name of the new Microsoft SQL Server DB instance.

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.

82
 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).

Before you begin, your database should have a status of Available. If it has a status of Creating or
Backing-up, wait until it's Available. The status updates without requiring you to refresh the page.
This process can take up to 20 minutes.

Also, make sure you have SSMS installed. If you can also connect to SQL Server on RDS by using a
different tools, such as an add-in for your development environment or some other database tool.
However, this tutorial only covers using SSMS. To download a stand-alone version of this SSMS, see
Download SQL Server Management Studio (SSMS) in the Microsoft documentation.

To connect to a DB instance using SSMS

1. Find the DNS name and port number for your DB instance.

a. Open the RDS console, and then choose Databases to display a list of your DB instances.
b. Hover your mouse cursor over the name sample-instance, which is blue. When you do this, the
mouse cursor changes into a selection icon (for example, a pointing hand). Also, the DB instance
name, becomes underlined.

Click on the DB instance name to choose it. The screen changes to display the information for
the DB instance you choose.
c. On the Connectivity tab, which opens by default, copy the endpoint. The Endpoint looks
something like this: sample-instance.abc2defghije.us-west-2.rds.amazonaws.com.
Also, take note of the port number. The default port for SQL Server is 1433. If yours is different,
write it down.
2. Start SQL Server Management Studio.

The Connect to Server dialog box appears.

3. Provide the information for your sample DB instance.

a. For Server type, choose Database Engine.

b. For Server name, enter the DNS name, followed by a comma and the port number (the default
port is 1433). For example, your server name should look like the following.

sample-instance.abc2defghije.us-west-2.rds.amazonaws.com,1433

c. For Authentication, choose SQL Server Authentication.

d. For Login, enter the user name that you chose to use for your sample DB instance. This is also
known as the master user name.
e. For Password, enter the password that you chose earlier for your sample DB instance. This is
also known as the master user password.
4. Choose Connect.

After a few moments, SSMS connects to your DB instance.

83
 Amazon Relational Database Service User Guide
Exploring your sample DB instance

If you can't connect to your DB instance, see Troubleshooting connections to your SQL Server DB
instance (p. 668).

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.

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. Enter the following SQL query.

select @@VERSION

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

84
 Amazon Relational Database Service User Guide
Deleting your sample DB instance

Deleting your sample DB instance

After 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 navigation pane, choose Databases.
3. Choose the button next to sample-instance, or whatever you named your sample DB instance.
4. From Actions, choose Delete.
5. If you see a message that says This database has deletion protection option enabled, follow these
steps:

a. Choose Modify.
b. On the Deletion protection card (near the bottom of the page), clear the box next to Enable
deletion protection. Then choose Continue.
c. On the Scheduling of modifications card, choose Apply immediately. Then choose Modify DB
instance.
d. Try again to delete the instance by choosing Delete from the Actions menu.
6. Clear the box for Create final snapshot. Because this isn't a production database, you don't need to
save a copy of it.
7. Verify that you selected the correct database to delete. The name "sample-instance" displays in the
title of the screen: Delete sample-instance instance?

If you don't recognize the name of your sample instance in the title, choose Cancel and start over.
8. To confirm that you want to permanently delete the database that is displayed in the title of this
screen, do the following:

• Check the box to confirm: I acknowledge that upon instance deletion, automated backups,
including system snapshots and point-in-time recovery, will no longer be available.
• Type "delete me" into the box To confirm deletion, type delete me into the field.
• Choose Delete. This action can't be undone.

85
 Amazon Relational Database Service User Guide
Creating a MySQL DB instance
and connecting to a database

The database shows a status of Deleting until deletion is complete.

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. After 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
Before you can create or connect to a DB instance, you must complete the tasks in Setting up for
Amazon RDS (p. 67).

Topics
• Creating a MySQL DB instance (p. 86)
• Connecting to a database on a DB instance running the MySQL database engine (p. 90)
• Deleting a DB instance (p. 92)

Creating a MySQL DB instance

The basic building block of Amazon RDS is the DB instance. This environment is where you run your
MySQL databases.

Console
You can create a DB instance running MySQL with the AWS Management Console with Easy Create
enabled or disabled. With Easy Create enabled, you specify only the DB engine type, DB instance size,
and DB instance identifier. Easy Create uses the default setting for other configuration options. With
Easy Create not enabled, you specify more configuration options when you create a database, including
ones for availability, security, backups, and maintenance.

In this example, you use Easy Create to create a DB instance running the MySQL database engine with a
db.t2.micro DB instance class.
Note
For information about creating DB instances with Easy Create not enabled, see Creating an
Amazon RDS DB instance (p. 147).

To create a MySQL DB instance with Easy Create enabled

1. Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.
2. In the upper-right corner of the Amazon RDS console, choose the AWS Region in which you want to
create the DB instance.
3. In the navigation pane, choose Databases.
4. Choose Create database and make sure that Easy Create is chosen.

86
 Amazon Relational Database Service User Guide
Creating a MySQL DB instance

5. In Configuration, choose MySQL.

6. For DB instance size, choose Free tier.
7. For DB instance identifier, enter a name for the DB instance, or leave the default name.
8. For Master username, enter a name for the master user, or leave the default name.

The Create database page should look similar to the following image.

87
Amazon Relational Database Service User Guide
Creating a MySQL DB instance

88
 Amazon Relational Database Service User Guide
Creating a MySQL DB instance

9. To use an automatically generated master password for the DB instance, enable Auto generate a
password.

To enter your master password, disable Auto generate a password, and then enter the same
password in Master password and Confirm password.
10. (Optional) Open View default settings for Easy create.

You can examine the default settings used when Easy Create is enabled. If you want to change one
or more settings during database creation, choose Standard Create to set them. The Editable after
database creation column shows which options you can change after database creation. To change
a setting with No in that column, use Standard Create. For settings with Yes in that column, you can
either use Standard Create or modify the DB instance after it is created to change the setting.
11. Choose Create database.

If you chose to use an automatically generated password, the View credential details button
appears on the Databases page.

To view the master username and password for the DB instance, choose View credential details.

You can use the username and password that appears to connect to the DB instance as the master
user.
Important
You won't be able to view master user password again. If you don't record it, you might
have to change it. If you need to change the master user password after the DB instance is
available, you can modify the DB instance to do so. For more information about modifying a
DB instance, see Modifying an Amazon RDS DB instance (p. 256).
12. In the Databases list, choose the name of the new MySQL DB instance.

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

89
 Amazon Relational Database Service User Guide
Connecting to a database on a DB instance running MySQL

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
After 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. For information about installing MySQL (including
the MySQL client), see Installing and upgrading MySQL.

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 Databases to display a list of your DB instances.
b. Choose the MySQL DB instance name to display its details.
c. On the Connectivity & security tab, copy the endpoint. Also, note the port number. You need
both the endpoint and the port number to connect to the DB instance.

90
 Amazon Relational Database Service User Guide
Connecting to a database on a DB instance running MySQL

2. Download a SQL client that you can use to connect to the DB instance.

You can connect to a MySQL DB instance by using tools like the MySQL command line utility. For
more information on using the MySQL client, go to mysql - the MySQL command-line client in the
MySQL documentation. One GUI-based application you can use to connect is MySQL Workbench. For
more information, go to the Download MySQL Workbench page.

91
 Amazon Relational Database Service User Guide
Deleting a DB instance

3. Connect to the a database on a MySQL DB instance. For example, enter the following command at
a command prompt on a client computer to connect to a database on a MySQL DB instance using
the MySQL client. Substitute the DNS name for your DB instance for <endpoint>, the master user
name you used for <mymasteruser>, and provide the master password you used when prompted
for a password.

PROMPT> mysql -h <endpoint> -P 3306 -u <mymasteruser> -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>

If you can't connect to your MySQL DB instance, two common causes of connection failures to a new DB
instance are:

• The DB instance was created using a security group that does not authorize connections from
the device or Amazon EC2 instance where the MySQL application or utility is running. If the DB
instance was created in a 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. For more information, see Amazon Virtual Private Cloud VPCs and Amazon
RDS (p. 1705).
• 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.

For more information about connecting to a MySQL DB instance, see Connecting to a DB instance
running the MySQL database engine (p. 844). For information on connection issues, see Can't connect
to Amazon RDS DB instance (p. 1733).

Deleting a DB instance
After 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 Databases.
3. Choose the DB instance that you want to delete.
4. For Actions, choose Delete.
5. For Create final snapshot?, choose No, and select the acknowledgment.
6. Choose Delete.

92
 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

The DB instance is where you run your Oracle databases.

Console
You can create a DB instance running Oracle with the AWS Management Console with Easy create
enabled or not enabled. With Easy create enabled, you specify only the DB engine type, DB instance size,
and DB instance identifier. Easy create uses the default setting for other configuration options. With
Easy create not enabled, you specify more configuration options when you create a database, including
ones for availability, security, backups, and maintenance.

For this example, you use Easy create to create a DB instance running the Oracle database engine with a
db.m4.large DB instance class.
Note
For information about creating DB instances with Easy create not enabled, see Creating an
Amazon RDS DB instance (p. 147).

To create an Oracle DB instance with Easy create enabled

1. Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.
2. In the upper-right corner of the Amazon RDS console, choose the AWS Region in which you want to
create the DB instance.
3. In the navigation pane, choose Databases.
4. Choose Create database and ensure that Easy create is chosen.

93
 Amazon Relational Database Service User Guide
Creating a sample Oracle DB instance

5. In Configuration, choose Oracle.

6. For DB instance size, choose Free tier. If Free tier isn't available, choose Dev/Test.
7. For DB instance identifier, enter a name for the DB instance, or leave the default name.
8. For Master username, enter a name for the master user, or leave the default name.

The Create database page should look similar to the following image.

94
Amazon Relational Database Service User Guide
Creating a sample Oracle DB instance

95
 Amazon Relational Database Service User Guide
Creating a sample Oracle DB instance

9. To use an automatically generated master password for the DB instance, make sure that the Auto
generate a password check box is chosen.

To enter your master password, clear the Auto generate a password check box, and then enter the
same password in Master password and Confirm password.
10. (Optional) Open View default settings for Easy create.

You can examine the default settings that are used when Easy create is enabled. If you want to
change one or more settings during database creation, choose Standard create to set them. The
Editable after database creation column shows which options you can change after database
creation. To change a setting with No in that column, use Standard create. For settings with Yes
in that column, you can either use Standard create or modify the DB instance after it's created to
change the setting.
11. Choose Create database.

If you used an automatically generated password, the View credential details button appears on the
Databases page.

To view the master user name and password for the DB instance, choose View credential details.

To connect to the DB instance as the master user, use the user name and password that appear.
Important
You can't view the master user password again. If you don't record it, you might have to
change it. If you need to change the master user password after the DB instance is available,
you can modify the DB instance to do so. For more information about modifying a DB
instance, see Modifying an Amazon RDS DB instance (p. 256).
12. For Databases, choose the name of the new Oracle DB instance.

96
 Amazon Relational Database Service User Guide
Connecting to your sample DB instance

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 DB 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. Find the endpoint (DNS name) and port number for your DB Instance.

a. Open the RDS console and then choose Databases to display a list of your DB instances.
b. Choose the Oracle DB instance name to display its details.
c. On the Connectivity & security tab, copy the following pieces of information:

• Endpoint
• Port

You need both the endpoint and the port number to connect to the DB instance.

97
 Amazon Relational Database Service User Guide
Connecting to your sample DB instance

d. On the Configuration tab, copy the following pieces of information:

• DB name (not the DB instance ID)

• Master username

You need both the DB name and the master username to connect to the DB instance.
2. Enter the following command on one line at a command prompt to connect to your DB instance by
using the sqlplus utility. Use the following values:

• For dbuser, enter the name of the master user that you copied in the preceding steps.
• For HOST=endpoint, enter the endpoint that you copied in the preceding steps.
• For PORT=portnum, enter the port number that you copied in the preceding steps.
• For SID=DB_NAME, enter the Oracle database name (not the instance name) that you copied in the
preceding steps.

sqlplus 'dbuser@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=endpoint)(PORT=portnum))
(CONNECT_DATA=(SID=DB_NAME)))'

You should see output similar to the following.

98
 Amazon Relational Database Service User Guide
Deleting your sample DB instance

SQL*Plus: Release 11.1.0.7.0 - Production on Wed May 25 15:13:59 2011

SQL>

For more information about connecting to an Oracle DB instance, see Connecting to your Oracle
DB instance (p. 1005). For information on connection issues, see Can't connect to Amazon RDS DB
instance (p. 1733).

Deleting your sample DB instance

After 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. In the navigation pane, choose Databases.
3. Choose the DB instance that you want to delete.
4. For Actions, choose Delete.
5. For Create final snapshot?, choose No, and choose the acknowledgment.
6. Choose Delete.

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. After 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
database-1, with a db.t2.micro DB instance class and 20 gibibytes (GiB) of storage.
Important
Before you can create or connect to a DB instance, you must complete the tasks in Setting up for
Amazon RDS (p. 67).

Contents
• Creating a PostgreSQL DB instance (p. 99)
• Connecting to a PostgreSQL DB instance (p. 103)
• Using pgAdmin to connect to a PostgreSQL DB instance (p. 103)
• Using psql to connect to a PostgreSQL DB instance (p. 107)
• Deleting a DB instance (p. 107)

Creating a PostgreSQL DB instance

The basic building block of Amazon RDS is the DB instance. This environment is where you run your
PostgreSQL databases.

99
 Amazon Relational Database Service User Guide
Creating a PostgreSQL DB instance

You can create a DB instance running PostgreSQL with the AWS Management Console with Easy Create
enabled or disabled. With Easy Create enabled, you specify only the DB engine type, DB instance size,
and DB instance identifier. Easy Create uses the default setting for other configuration options. With
Easy Create not enabled, you specify more configuration options when you create a database, including
ones for availability, security, backups, and maintenance.

In this example, you use Easy Create to create a DB instance running the PostgreSQL database engine
with a db.t2.micro DB instance class.
Note
For information about creating DB instances with Easy Create not enabled, see Creating an
Amazon RDS DB instance (p. 147).

To create a PostgreSQL DB instance with Easy Create enabled

1. Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.
2. In the upper-right corner of the Amazon RDS console, choose the AWS Region in which you want to
create the DB instance.
3. In the navigation pane, choose Databases.
4. Choose Create database and make sure that Easy Create is chosen.

5. In Configuration, choose PostgreSQL.

6. For DB instance size, choose Free tier.
7. For DB instance identifier, enter a name for the DB instance, or leave the default name.
8. For Master username, enter a name for the master user, or leave the default name.

The Create database page should look similar to the following image.

100
Amazon Relational Database Service User Guide
Creating a PostgreSQL DB instance

101
 Amazon Relational Database Service User Guide
Creating a PostgreSQL DB instance

9. To use an automatically generated master password for the DB instance, make sure that the Auto
generate a password check box is chosen.

To enter your master password, clear the Auto generate a password check box, and then enter the
same password in Master password and Confirm password.
10. (Optional) Open View default settings for Easy create.

You can examine the default settings used when Easy Create is enabled. If you want to change one
or more settings during database creation, choose Standard Create to set them. The Editable after
database creation column shows which options you can change after database creation. To change
a setting with No in that column, use Standard Create. For settings with Yes in that column, you can
either use Standard Create or modify the DB instance after it's created to change the setting.
11. Choose Create database.

If you chose to use an automatically generated password, the View credential details button
appears on the Databases page.

To view the master user name and password for the DB instance, choose View credential details.

To connect to the DB instance as the master user, use the user name and password that appear.
Important
You can't view the master user password again. If you don't record it, you might have to
change it. If you need to change the master user password after the DB instance is available,
you can modify the DB instance to do so. For more information about modifying a DB
instance, see Modifying an Amazon RDS DB instance (p. 256).
12. For Databases, choose the name of the new PostgreSQL DB instance.

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.

102
 Amazon Relational Database Service User Guide
Connecting to a PostgreSQL DB instance

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. The security group that 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.

For more information about connecting to a PostgreSQL DB instance, see Connecting to a DB instance
running the PostgreSQL database engine (p. 1460). If you can't connect to your DB instance, see
Troubleshooting connections to your PostgreSQL instance (p. 1463).

Topics
• Using pgAdmin to connect to a PostgreSQL DB instance (p. 103)
• Using psql to connect to a PostgreSQL DB instance (p. 107)

Using pgAdmin to connect to a PostgreSQL DB instance

To connect to a PostgreSQL DB instance using pgAdmin

1. Find the endpoint (DNS name) and port number for your DB instance.

a. Open the RDS console and then choose Databases to display a list of your DB instances.
b. Choose the PostgreSQL DB instance name to display its details.
c. On the Connectivity & security tab, copy the endpoint. Also, note the port number. You need
both the endpoint and the port number to connect to the DB instance.

103
 Amazon Relational Database Service User Guide
Connecting to a PostgreSQL DB instance

2. Install pgAdmin from https://www.pgadmin.org/. You can download and use pgAdmin without
having a local instance of PostgreSQL on your client computer.
3. Launch the pgAdmin application on your client computer.
4. Choose Add Server from the File menu.
5. In the New Server Registration dialog box, enter the DB instance endpoint (for example,
database-1.c6c8dntfzzhgv0.us-west-1.rds.amazonaws.com) in the Host
box. Don't include the colon or port number as shown on the Amazon RDS console
(database-1.c6c8dntfzzhgv0.us-west-1.rds.amazonaws.com:5432).

Enter the port you assigned to the DB instance for Port. Enter the user name and user password that
you entered when you created the DB instance for Username and Password.

104
 Amazon Relational Database Service User Guide
Connecting to a PostgreSQL DB instance

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

105
 Amazon Relational Database Service User Guide
Connecting to a PostgreSQL DB instance

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

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

106
 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, provide host
information and access credentials.

The following format is used to connect to a PostgreSQL DB instance on Amazon RDS.

psql --host=DB_instance_endpoint --port=port --username=master_user_name --password --

dbname=database_name

For example, the following command connects to a database called mypgdb on a PostgreSQL DB
instance called mypostgresql using fictitious credentials.

psql --host=database-1.c6c8dntfzzhgv0.us-west-1.rds.amazonaws.com --port=5432 --

username=awsuser --password --dbname=postgres

Deleting a DB instance
After 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 Databases.
3. Choose the DB instance that you want to delete.
4. For Actions, choose Delete.
5. For Create final snapshot?, choose No, and select the acknowledgment.
6. Choose Delete.

107
 Amazon Relational Database Service User Guide
Tutorial: Create a web server
and an Amazon RDS DB instance

Tutorial: Create a web server and an Amazon RDS

DB instance
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 MySQL DB
instance. Both the Amazon EC2 instance and the DB instance run in a virtual private cloud (VPC) based
on the Amazon VPC service.
Important
There's no charge for creating an AWS account. However, by completing this tutorial, you might
incur costs for the AWS resources you use. You can delete these resources after you complete
the tutorial if they are no longer needed.
Note
This tutorial works with Amazon Linux and might not work for other versions of Linux such as
Ubuntu.

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 to 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 create the DB instance and install the web server. You
connect your web server to your DB instance in the VPC using the DB instance endpoint endpoint.

1. Complete the tasks in Tutorial: Create an Amazon VPC for use with a DB instance (p. 1724).

Before you begin this tutorial, make sure that you have a VPC with both public and private subnets,
and corresponding security groups. If you don't have these, complete the following tasks in the
tutorial:

a. Create a VPC with private and public subnets (p. 1724)

b. Create additional subnets (p. 1726)
c. Create a VPC security group for a public web server (p. 1726)
d. Create a VPC security group for a private DB instance (p. 1727)
e. Create a DB subnet group (p. 1728)
2. Create a DB instance (p. 109)
3. Create an EC2 instance and install a web server (p. 119)

The following diagram shows the configuration when the tutorial is complete.

108
 Amazon Relational Database Service User Guide
Create a DB instance

Create a DB instance
In this step, you create an Amazon RDS for MySQL DB instance that maintains the data used by a web
application.
Important
Before you begin this step, make sure that you 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 a DB instance (p. 1724). Complete the steps in Create a VPC with private and public
subnets (p. 1724), Create additional subnets (p. 1726), Create a VPC security group for a public
web server (p. 1726), and Create a VPC security group for a private DB instance (p. 1727).
Note
A new console interface is available for database creation. Choose either the New Console or
the Original Console instructions based on the console that you are using. The New Console
instructions are open by default.

New console
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 upper-right corner of the AWS Management Console, choose the AWS Region where you want
to create the DB instance. This example uses the US West (Oregon) Region.
3. In the navigation pane, choose Databases.
4. Choose Create database.
5. On the Create database page, shown following, make sure that the Standard Create option is
chosen, and then choose MySQL.

109
 Amazon Relational Database Service User Guide
Create a DB instance

6. In the Templates section, choose Free tier.

7. In the Settings section, set these values:

• DB instance identifier – tutorial-db-instance

• Master username – tutorial_user
• Auto generate a password – Disable the option
• Master password – Choose a password.
• Confirm password – Retype the password.

110
 Amazon Relational Database Service User Guide
Create a DB instance

8. In the DB instance size section, set these values:

• Burstable classes (includes t classes)

• db.t2.micro

111
 Amazon Relational Database Service User Guide
Create a DB instance

9. In the Storage and Availability & durability sections, use the default values.
10. In the Connectivity section, open Additional connectivity configuration and set these values:

• 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. 1724)
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. 1728)
• Public access – No
• Existing 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 DB instance (p. 1727).

Remove other security groups, such as the default security group, by choosing the X associated
with each.
• Database port – 3306

112
 Amazon Relational Database Service User Guide
Create a DB instance

11. Open the Additional configuration section, and enter sample for Initial database name. Keep the
default settings for the other options.
12. Choose Create database to create your MySQL DB instance.

Your new DB instance appears in the Databases list with the status Creating.
13. Wait for the Status of your new DB instance to show as Available. Then choose the DB instance
name to show its details.
14. In the Connectivity & security section, view the Endpoint and Port of the DB instance.

113
 Amazon Relational Database Service User Guide
Create a DB instance

Note the endpoint and port for your DB instance. You use this information to connect your web
server to your DB instance.

To make sure that your DB instance is as secure as possible, verify that sources outside of the VPC
can't connect to your DB instance.
15. Complete Create an EC2 instance and install a web server (p. 119).

Original console

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 AWS Management Console, choose the AWS Region where you want to
create the DB instance. This example uses the US West (Oregon) Region.

114
 Amazon Relational Database Service User Guide
Create a DB instance

3. In the navigation pane, choose Databases.

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.

6. On the Choose use case page, choose Free tier – 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.micro
• 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.

115
Amazon Relational Database Service User Guide
Create a DB instance

116
 Amazon Relational Database Service User Guide
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. 1724)
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. 1728)
• 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
DB instance (p. 1727).

Remove other security groups, such as the default security group, by choosing the X associated
with each.
• Database name: sample

Keep the default settings for the other options.

117
 Amazon Relational Database Service User Guide
Create a DB instance

9. Choose Create database to create your MySQL DB instance.

10. On the next page, choose View DB instances details to view your 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.

118
 Amazon Relational Database Service User Guide
Create a web server

Note the endpoint and port for your DB instance. You use this information to connect your web
server to your DB instance.

To make sure that your DB instance is as secure as possible, verify that sources outside of the VPC
can't connect to your DB instance.
12. Complete Create an EC2 instance and install a web server (p. 119).

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
Create a DB instance (p. 109).

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.

119
 Amazon Relational Database Service User Guide
Create a web server

3. Choose the Amazon Linux 2 AMI.

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

120
 Amazon Relational Database Service User Guide
Create a web server

5. On the Configure Instance Details page, shown following, set these values and keep 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 vpc-identifier | tutorial-vpc created in Create a VPC with private
and public subnets (p. 1724).
• 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. 1726).
• Auto-assign Public IP: Choose Enable.

121
 Amazon Relational Database Service User Guide
Create a web server

6. Choose Next: Add Storage.

7. On the Add Storage page, keep the default values and choose Next: Add Tags.
8. On the Add Tags page, shown following, choose Add Tag, then enter Name for Key and enter
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.
Then choose an existing security group, such as the tutorial-securitygroup created in Create
a VPC security group for a public web server (p. 1726). Make sure that the security group that you
choose includes inbound rules for Secure Shell (SSH) and HTTP access.

122
 Amazon Relational Database Service User Guide
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.

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.

123
 Amazon Relational Database Service User Guide
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.

124
 Amazon Relational Database Service User Guide
Create a web server

15. Choose View Instances to find your instance.

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.
Note
This tutorial is designed to work with a MySQL version 5.6 DB instance. If you are using a MySQL
8.0 DB instance instead, you must set the following parameters to the values specified in a
customer-created DB parameter group:

• character_set_server – utf8
• collation_server – utf8_general_ci

The default settings for these parameters cause the database connection to fail. Other
parameter settings might also correct the problem. For more information about setting
parameters, see Working with DB parameter groups (p. 234).
After you reset the parameters, modify your DB instance to use the DB parameter group,
and reboot the DB instance. For more information, see Modifying an Amazon RDS DB
instance (p. 256) and Rebooting a DB instance (p. 282).

125
 Amazon Relational Database Service User Guide
Create a web server

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

1. Connect to the EC2 instance that you created earlier by following the steps in Connect to your Linux
instance.
2. Get the latest bug fixes and security updates by updating the software on your EC2 instance. To do
this, use the following command.
Note
The -y option installs the updates without asking for confirmation. To examine updates
before installing, omit this option.

sudo yum update -y

3. After the updates complete, install the PHP software using the amazon-linux-extras install
command. This command installs multiple software packages and related dependencies at the same
time.

sudo amazon-linux-extras install -y lamp-mariadb10.2-php7.2 php7.2

If you receive an error stating sudo: amazon-linux-extras: command not found, then your
instance was not launched with an Amazon Linux 2 AMI (perhaps you are using the Amazon Linux
AMI instead). You can view your version of Amazon Linux using the following command.

cat /etc/system-release

For more information, see Updating instance software.

4. Install the Apache web server.

sudo yum install -y httpd

5. Start the web server with the command shown following.

sudo systemctl start httpd

You can test that your web server is properly installed and started. To do this, enter the public
Domain Name System (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, check your inbound rules for the VPC security group that you
created in Tutorial: Create an Amazon VPC for use with a DB instance (p. 1724). Make sure that your
inbound rules 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.
6. Configure the web server to start with each system boot using the chkconfig command.

sudo systemctl enable httpd

126
 Amazon Relational Database Service User Guide
Create a web server

To allow ec2-user to manage files in the default root directory for your Apache web server, modify the
ownership and permissions of the /var/www directory. There are many ways to accomplish this task.
In this tutorial, you add ec2-user to the apache group, to give the apache group ownership of the /
var/www directory and assign write permissions to the group.

To set file permissions for the Apache web server

1. Add the ec2-user user to the apache group.

sudo usermod -a -G apache ec2-user

2. Log out to refresh your permissions and include the new apache group.

exit

3. Log back in again and verify that the apache group exists with the groups command.

groups

Your output looks similar to the following:

ec2-user adm wheel apache systemd-journal

4. Change the group ownership of the /var/www directory and its contents to the apache group.

sudo chown -R ec2-user:apache /var/www

5. 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.

sudo chmod 2775 /var/www

find /var/www -type d -exec sudo chmod 2775 {} \;

6. Recursively change the permissions for files in the /var/www directory and its subdirectories to add
group write permissions.

find /var/www -type f -exec sudo chmod 0664 {} \;

Now, ec2-user (and any future members of the apache group) can add, delete, and edit files in the
Apache document root, enabling you to add content, such as a static website or a PHP application.
Note
A web server running the HTTP protocol provides no transport security for the data that it
sends or receives. When you connect to an HTTP server using a web browser, the URLs that
you visit, the content of web pages that you receive, and the contents (including passwords) of
any HTML forms that you submit are all visible to eavesdroppers anywhere along the network
pathway. The best practice for securing your web server is to install support for HTTPS (HTTP
Secure), which protects your data with SSL/TLS encryption. For more information, see Tutorial:
Configure SSL/TLS with the Amazon Linux AMI in the Amazon EC2 User Guide.

Connect your Apache web server to your DB instance

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

127
 Amazon Relational Database Service User Guide
Create a web server

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

1. While still connected to your EC2 instance, change the directory to /var/www and create a new
subdirectory named inc.

cd /var/www
mkdir inc
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).

>dbinfo.inc
nano dbinfo.inc

3. Add the following contents to the dbinfo.inc file. Here, db_instance_endpoint is your DB
instance endpoint, without the port, and master password is the master password for your DB
instance.
Note
We recommend placing the user name and password information in a folder that isn't part
of the document root for your web server. Doing this reduces the possibility of your security
information being exposed.

<?php

define('DB_SERVER', 'db_instance_endpoint');
define('DB_USERNAME', 'tutorial_user');
define('DB_PASSWORD', 'master password');
define('DB_DATABASE', 'sample');

?>

4. Save and close the dbinfo.inc file.

5. Change the directory to /var/www/html.

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).

>SamplePage.php
nano SamplePage.php

7. Add the following contents to the SamplePage.php file:

Note
We recommend placing the user name and password information in a folder that isn't part
of the document root for your web server. Doing this reduces the possibility of your security
information being exposed.

<?php include "../inc/dbinfo.inc"; ?>

<html>
<body>
<h1>Sample page</h1>
<?php

128
 Amazon Relational Database Service User Guide
Create a web server

/* Connect to MySQL and select the database. */

$connection = mysqli_connect(DB_SERVER, DB_USERNAME, DB_PASSWORD);

if (mysqli_connect_errno()) echo "Failed to connect to MySQL: " .

mysqli_connect_error();

$database = mysqli_select_db($connection, DB_DATABASE);

/* Ensure that the EMPLOYEES table exists. */

VerifyEmployeesTable($connection, DB_DATABASE);

/* If input fields are populated, add a row to the EMPLOYEES table. */

$employee_name = htmlentities($_POST['NAME']);
$employee_address = htmlentities($_POST['ADDRESS']);

if (strlen($employee_name) || strlen($employee_address)) {
AddEmployee($connection, $employee_name, $employee_address);
}
?>

<!-- Input form -->

<form action="<?PHP echo $_SERVER['SCRIPT_NAME'] ?>" method="POST">
<table border="0">
<tr>
<td>NAME</td>
<td>ADDRESS</td>
</tr>
<tr>
<td>
<input type="text" name="NAME" maxlength="45" size="30" />
</td>
<td>
<input type="text" name="ADDRESS" maxlength="90" size="60" />
</td>
<td>
<input type="submit" value="Add Data" />
</td>
</tr>
</table>
</form>

<!-- Display table data. -->

<table border="1" cellpadding="2" cellspacing="2">
<tr>
<td>ID</td>
<td>NAME</td>
<td>ADDRESS</td>
</tr>

<?php

$result = mysqli_query($connection, "SELECT * FROM EMPLOYEES");

while($query_data = mysqli_fetch_row($result)) {
echo "<tr>";
echo "<td>",$query_data[0], "</td>",
"<td>",$query_data[1], "</td>",
"<td>",$query_data[2], "</td>";
echo "</tr>";
}
?>

</table>

<!-- Clean up. -->

<?php

129
 Amazon Relational Database Service User Guide
Create a web server

mysqli_free_result($result);
mysqli_close($connection);

?>

</body>
</html>

<?php

/* Add an employee to the table. */

function AddEmployee($connection, $name, $address) {
$n = mysqli_real_escape_string($connection, $name);
$a = mysqli_real_escape_string($connection, $address);

$query = "INSERT INTO EMPLOYEES (NAME, ADDRESS) VALUES ('$n', '$a');";

if(!mysqli_query($connection, $query)) echo("<p>Error adding employee data.</p>");

}

/* 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) UNSIGNED AUTO_INCREMENT PRIMARY KEY,
NAME VARCHAR(45),
ADDRESS VARCHAR(90)
)";

if(!mysqli_query($connection, $query)) echo("<p>Error creating table.</p>");

}
}

/* 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 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 DB instance. The data that you add is then displayed
on the page. To verify that the data was inserted into the table, you can install MySQL on the Amazon
EC2 instance, connect to the DB instance, and query the table.

To make sure that your DB instance is as secure as possible, verify that sources outside of the VPC can't
connect to your DB instance.

130
 Amazon Relational Database Service User Guide
Create a web server

After you have finished testing your web server and your database, you should delete your DB instance
and your Amazon EC2 instance.

• To delete a DB instance, follow the instructions in Deleting a DB instance (p. 330). You don't need to
create a final snapshot.
• To terminate an Amazon EC2 instance, follow the instruction in Terminate your instance in the Amazon
EC2 User Guide.

131
 Amazon Relational Database Service User Guide
Tutorials in this guide

Amazon RDS Tutorials

The AWS documentation includes several tutorials that guide you through common Amazon RDS use
cases. Many of these tutorials show you how to use Amazon RDS with other AWS services.
Note
You can find more tutorials at the AWS Database Blog. For information about training, see AWS
Training and Certification.

Tutorials in this guide

The following tutorials in this guide show you how to perform common tasks with Amazon RDS:

• Tutorial: Create an Amazon VPC for use with a DB instance (p. 1724)

Learn how to include a DB instance in an Amazon virtual private cloud (VPC) that shares data with a
web server that is running on an Amazon EC2 instance in the same VPC.
• Tutorial: Create a web server and an Amazon RDS DB instance (p. 108)

Learn how to 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 a MySQL DB
instance. Both the Amazon EC2 instance and the DB instance run in an Amazon VPC.
• Tutorial: Restore a DB instance from a DB snapshot (p. 400)

Learn how to restore a DB instance from a DB snapshot.

• Tutorial: Use tags to specify which DB instances to stop (p. 310)

Learn how to use tags to specify which DB instances to stop.

• Tutorial: log the state of an Amazon RDS instance using EventBridge (p. 561)

Learn how to log a DB instance stage change using Amazon EventBridge and AWS Lambda.

Tutorials in other AWS guides

The following tutorials in other AWS guides show you how to perform common tasks with Amazon RDS:

• Tutorial: Rotating a Secret for an AWS Database in the AWS Secrets Manager User Guide

Learn how to create a secret for an AWS database and configure the secret to rotate on a schedule.
You trigger one rotation manually, and then confirm that the new version of the secret continues to
provide access.
• Tutorial: Configuring a Lambda function to access Amazon RDS in an Amazon VPC in the AWS Lambda
Developer Guide

Learn how to create a Lambda function to access a database, create a table, add a few records, and
retrieve the records from the table. You also learn how to invoke the Lambda function and verify the
query results.
• Tutorials and samples in the AWS Elastic Beanstalk Developer Guide

Learn how to deploy applications that use Amazon RDS databases with AWS Elastic Beanstalk.

132
 Amazon Relational Database Service User Guide
Tutorials in other AWS guides

• Using Data from an Amazon RDS Database to Create an Amazon ML Datasource in the Amazon
Machine Learning Developer Guide

Learn how to create an Amazon Machine Learning (Amazon ML) datasource object from data stored in
a MySQL DB instance.
• Manually Enabling Access to an Amazon RDS Instance in a VPC in the Amazon QuickSight User Guide

Learn how to enable Amazon QuickSight access to an Amazon RDS DB instance in a VPC.

133
 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. 134)
• DB instance RAM recommendations (p. 135)
• Using Enhanced Monitoring to identify operating system issues (p. 135)
• Using metrics to identify performance issues (p. 135)
• Best practices for working with MySQL storage engines (p. 140)
• Best practices for working with MariaDB storage engines (p. 141)
• Best practices for working with Oracle (p. 143)
• Best practices for working with PostgreSQL (p. 143)
• Best practices for working with SQL Server (p. 144)
• Working with DB parameter groups (p. 145)
• Amazon RDS new features and best practices presentation video (p. 145)

Note
For common recommendations for Amazon RDS, see Using Amazon RDS
recommendations (p. 413).

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.
That's when a backup is least disruptive to your database usage.
• 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 different DB instance class with high I/O capacity.
• Convert from magnetic 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. 40).

134
 Amazon Relational Database Service User Guide
DB instance RAM recommendations

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. 42).
• 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.
• Test failover for your DB instance to understand how long the process takes for your particular use
case and to ensure that the application that accesses your DB instance can automatically connect to
the new DB instance after failover occurs.

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. The working set is the data and indexes that are frequently in use on your
instance. The more you use the DB instance, the more the working set will grow.

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. 555).

Using Enhanced Monitoring to identify operating

system issues
When Enhanced Monitoring is enabled, 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 Using
Enhanced Monitoring (p. 477).

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.

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

135
 Amazon Relational Database Service User Guide
Viewing performance metrics

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 navigation pane, choose Databases, and then choose a DB instance.
3. Choose 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 choose adjust the
settings to see more metrics.
5. Choose 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. 555).

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 navigation pane, choose Databases, and then choose a DB instance.
3. Choose Logs & events.
4. In the CloudWatch alarms section, choose Create alarm.

136
 Amazon Relational Database Service User Guide
Viewing performance metrics

5. For Send notifications, choose Yes, and for Send notifications to, choose New email or SMS topic.
6. For Topic name, enter a name for the notification, and for With these recipients, enter a comma-
separated list of email addresses and phone numbers.
7. For Metric, choose the alarm statistic and metric to set.
8. For Threshold, specify whether the metric must be greater than, less than, or equal to the threshold,
and specify the threshold value.
9. For Evaluation period, choose the evaluation period for the alarm, and for consecutive period(s) of,
choose the period during which the threshold must have been reached in order to trigger the alarm.
10. For Name of alarm, enter a name for the alarm.
11. Choose Create Alarm.

137
 Amazon Relational Database Service User Guide
Evaluating performance metrics

The alarm appears in the CloudWatch alarms section.

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.

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 Monitoring Amazon
RDS metrics with Amazon CloudWatch (p. 546).

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.

138
 Amazon Relational Database Service User Guide
Tuning queries

• 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. 234).
• 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. 139)

If your queries are tuned and an issue persists, consider upgrading your Amazon RDS DB instance
classes (p. 7) 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. 816).

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

139
 Amazon Relational Database Service User Guide
Best practices for working with MySQL storage engines

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
Both table sizes and number of tables in a MySQL database can affect performance.

Table size
Typically, operating system constraints on file sizes determine the effective maximum table size for
MySQL databases. So, the limits usually aren't determined by internal MySQL constraints.

On a MySQL DB instance, avoid tables in your database growing too large. Although the general storage
limit is 64 TiB, provisioned storage limits restrict the maximum size of a MySQL table file to 16 TiB.
Partition your large tables so that file sizes are well under the 16 TiB limit. This approach can also
improve performance and recovery time. For more information, see MySQL file size limits in Amazon
RDS (p. 954).

Very large tables (greater than 100 GB in size) can negatively affect performance for both reads
and writes (including DML statements and especially DDL statements). Indexes on larges tables
can significantly improve select performance, but they can also degrade the performance of DML
statements. DDL statements, such as ALTER TABLE, can be significantly slower for the large tables
because those operations might completely rebuild a table in some cases. These DDL statements might
lock the tables for the duration of the operation.

The amount of memory required by MySQL for reads and writes depends on the tables involved in the
operations. It is a best practice to have at least enough RAM to the hold the indexes of actively used
tables. To find the ten largest tables and indexes in a database, use the following query:

SELECT CONCAT(table_schema, '.', table_name),

CONCAT(ROUND(table_rows / 1000000, 2), 'M') rows,
CONCAT(ROUND(data_length / ( 1024 * 1024 * 1024 ), 2), 'G') DATA,
CONCAT(ROUND(index_length / ( 1024 * 1024 * 1024 ), 2), 'G') idx,
CONCAT(ROUND(( data_length + index_length ) / ( 1024 * 1024 * 1024 ), 2), 'G')
total_size,
ROUND(index_length / data_length, 2)
idxfrac
FROM information_schema.TABLES
ORDER BY data_length + index_length DESC
LIMIT 10;

Number of tables
While the underlying file system might have a limit on the number of files that represent tables, MySQL
has no limit on the number of tables. However, the total number of tables in the MySQL InnoDB storage
engine can contribute to the performance degradation, regardless of the size of those tables. To limit
the operating system impact, you can split the tables across multiple databases in the same MySQL DB
instance. Doing so might limit the number of files in a directory but won't solve the overall problem.

140
 Amazon Relational Database Service User Guide
Storage engine

When there is performance degradation because of a large number of tables (more than 10 thousand), it
is caused by MySQL working with storage files, including opening and closing them. To address this issue,
you can increase the size of the table_open_cache and table_definition_cache parameters.
However, increasing the values of those parameters might significantly increase the amount of memory
MySQL uses, and might even use all of the available memory. For more information, see How MySQL
Opens and Closes Tables in the MySQL documentation.

In addition, too many tables can significantly affect MySQL startup time. Both a clean shutdown and
restart and a crash recovery can be affected, especially in versions prior to MySQL 8.0.

We recommend having fewer than ten thousand tables total across all of the databases in a DB instance.
For a use case with a large number of tables in a MySQL database, see One Million Tables in MySQL 8.0.

Storage engine
The point-in-time restore and snapshot restore features of Amazon RDS for MySQL require a crash-
recoverable 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. 342) 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
Both table sizes and number of tables in a MariaDB database can affect performance.

Table size
Typically, operating system constraints on file sizes determine the effective maximum table size for
MariaDB databases. So, the limits usually aren't determined by internal MariaDB constraints.

On a MariaDB DB instance, avoid tables in your database growing too large. Although the general
storage limit is 64 TiB, provisioned storage limits restrict the maximum size of a MariaDB table file to 16
TiB. Partition your large tables so that file sizes are well under the 16 TiB limit. This approach can also
improve performance and recovery time.

Very large tables (greater than 100 GB in size) can negatively affect performance for both reads
and writes (including DML statements and especially DDL statements). Indexes on larges tables
can significantly improve select performance, but they can also degrade the performance of DML

141
 Amazon Relational Database Service User Guide
Number of tables

statements. DDL statements, such as ALTER TABLE, can be significantly slower for the large tables
because those operations might completely rebuild a table in some cases. These DDL statements might
lock the tables for the duration of the operation.

The amount of memory required by MariaDB for reads and writes depends on the tables involved in
the operations. It is a best practice to have at least enough RAM to the hold the indexes of actively used
tables. To find the ten largest tables and indexes in a database, use the following query:

SELECT CONCAT(table_schema, '.', table_name),

CONCAT(ROUND(table_rows / 1000000, 2), 'M') rows,
CONCAT(ROUND(data_length / ( 1024 * 1024 * 1024 ), 2), 'G') DATA,
CONCAT(ROUND(index_length / ( 1024 * 1024 * 1024 ), 2), 'G') idx,
CONCAT(ROUND(( data_length + index_length ) / ( 1024 * 1024 * 1024 ), 2), 'G')
total_size,
ROUND(index_length / data_length, 2)
idxfrac
FROM information_schema.TABLES
ORDER BY data_length + index_length DESC
LIMIT 10;

Number of tables
While the underlying file system might have a limit on the number of files that represent tables, MariaDB
has no limit on the number of tables. However, the total number of tables in the MariaDB InnoDB
storage engine can contribute to the performance degradation, regardless of the size of those tables.
To limit the operating system impact, you can split the tables across multiple databases in the same
MariaDB DB instance. Doing so might limit the number of files in a directory but won't solve the overall
problem.

When there is performance degradation because of a large number of tables (more than 10 thousand),
it is caused by MariaDB working with storage files, including opening and closing them. To address
this issue, you can increase the size of the table_open_cache and table_definition_cache
parameters. However, increasing the values of those parameters might significantly increase the amount
of memory MariaDB uses, and might even use all of the available memory. For more information, see
Optimizing table_open_cache in the MariaDB documentation.

In addition, too many tables can significantly affect MariaDB startup time. Both a clean shutdown and
restart and a crash recovery can be affected. We recommend having fewer than ten thousand tables total
across all of the databases in a DB instance.

Storage engine
The point-in-time restore and snapshot restore features of Amazon RDS for MariaDB require a crash-
recoverable 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. 342) 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
MariaDB 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.

142
 Amazon Relational Database Service User Guide
Best practices for working with Oracle

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.

A 2020 AWS virtual workshop included a presentation on running production Oracle databases on
Amazon RDS. A video of the presentation is available here.

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.

After the load operation completes, return your DB instance and DB parameters to their normal settings.

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 Routine vacuuming.

143
 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. For more information, see Preventing transaction ID wraparound failures.

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

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. 493).
• 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.

144
 Amazon Relational Database Service User Guide
Amazon RDS for SQL Server best practices video

• 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.

Amazon RDS for SQL Server best practices video

The 2019 AWS re:Invent conference included a presentation on new features and best practices for
working with SQL Server on Amazon RDS. A video of the presentation is available here.

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 an Amazon RDS DB
instance (p. 333).

Amazon RDS new features and best practices

presentation video
The 2019 AWS re:Invent conference included a presentation on new Amazon RDS features and best
practices for monitoring, analyzing, and tuning database performance using RDS. A video of the
presentation is available here.

145
 Amazon Relational Database Service User Guide

Configuring an Amazon RDS DB

instance
This section shows how to set up your Amazon RDS DB instance. Before creating a DB instance, decide
on the DB instance class that will run the DB instance. Also, decide where the DB instance will run by
choosing an AWS Region. Next, create the DB instance.

You can configure a DB instance with an option group and a DB parameter group.

• An option group specifies features, called options, that are available for a particular Amazon RDS DB
instance.
• A DB parameter group acts as a container for engine configuration values that are applied to one or
more DB instances.

The options and parameters that are available depend on the DB engine and DB engine version. You can
specify an option group and a DB parameter group when you create a DB instance, or you can modify a
DB instance to specify them.

Topics
• Creating an Amazon RDS DB instance (p. 147)
• Connecting to an Amazon RDS DB instance (p. 168)
• Working with option groups (p. 218)
• Working with DB parameter groups (p. 234)

146
 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, where you create your databases. You choose
the engine-specific characteristics of the DB instance when you create it. You also choose the storage
capacity, CPU, memory, and so on, of the AWS instance on which the database server runs.
Important
Before you can create or connect to a DB instance, you must complete the tasks in Setting up for
Amazon RDS (p. 67).

Console
You can create a DB instance by using the AWS Management Console with Easy Create enabled or
not enabled. With Easy Create enabled, you specify only the DB engine type, DB instance size, and DB
instance identifier. Easy Create uses the default setting for other configuration options. With Easy Create
not enabled, you specify more configuration options when you create a database, including ones for
availability, security, backups, and maintenance.
Note
In the following procedure, Standard Create is enabled, and Easy Create isn't enabled. This
procedure uses Microsoft SQL Server as an example.
For examples that use Easy Create to walk you through creating and connecting to sample DB
instances for each engine, see Getting started with Amazon RDS (p. 73). For an example that
uses the original console to create a DB instance, see Original console example (p. 163).

To create 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 upper-right corner of the Amazon RDS console, choose the AWS Region in which you want to
create the DB instance.
3. In the navigation pane, choose Databases.
4. Choose Create database.
5. In Choose a database creation method, select Standard Create.
6. In Engine options, choose the engine type: MariaDB, Microsoft SQL Server, MySQL, Oracle, or
PostgreSQL. Microsoft SQL Server is shown here.

147
 Amazon Relational Database Service User Guide
Creating a DB instance

7. For Edition, if you're using Oracle or SQL Server choose the DB engine edition that you want to use.

MySQL has only one option for the edition, and MariaDB and PostgreSQL have none.
8. For Version, choose the engine version.
9. In Templates, choose the template that matches your use case. If you choose Production, the
following are preselected in a later step:

• Multi-AZ failover option

• Provisioned IOPS storage option
• Enable deletion protection option

148
 Amazon Relational Database Service User Guide
Creating a DB instance

We recommend these features for any production environment.

Note
Template choices vary by edition.
10. To enter your master password, do the following:

a. In the Settings section, open Credential Settings.

b. Clear the Auto generate a password check box.
c. (Optional) Change the Master username value and enter the same password in Master
password and Confirm password.

By default, the new DB instance uses an automatically generated password for the master user.
11. For the remaining sections, specify your DB instance settings. For information about each setting,
see Settings for DB instances (p. 151).
12. Choose Create database.

If you chose to use an automatically generated password, the View credential details button
appears on the Databases page.

To view the master user name and password for the DB instance, choose View credential details.

To connect to the DB instance as the master user, use the user name and password that appear.
Important
You can't view the master user password again. If you don't record it, you might have to
change it. If you need to change the master user password after the DB instance is available,
modify the DB instance to do so. For more information about modifying a DB instance, see
Modifying an Amazon RDS DB instance (p. 256).
13. For Databases, choose the name of the new DB instance.

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 can
take several minutes for the new instance to be available.

149
 Amazon Relational Database Service User Guide
Creating a DB instance

AWS CLI
To create a DB instance by using the AWS CLI, call the create-db-instance command with the following
parameters. This example uses Microsoft SQL Server.

For information about each setting, see Settings for DB instances (p. 151).

• --db-instance-identifier
• --db-instance-class
• --vpc-security-group-ids
• --db-subnet-group
• --engine
• --master-username
• --master-user-password
• --allocated-storage
• --backup-retention-period

Example
For Linux, macOS, or Unix:

aws rds create-db-instance \

--engine sqlserver-se \
--db-instance-identifier mymsftsqlserver \
--allocated-storage 250 \
--db-instance-class db.t3.large \
--vpc-security-group-ids mysecuritygroup \
--db-subnet-group mydbsubnetgroup \
--master-username masterawsuser \
--master-user-password masteruserpassword \
--backup-retention-period 3

For Windows:

aws rds create-db-instance ^

--engine sqlserver-se ^
--db-instance-identifier mydbinstance ^
--allocated-storage 250 ^
--db-instance-class db.t3.large ^
--vpc-security-group-ids mysecuritygroup ^
--db-subnet-group mydbsubnetgroup ^
--master-username masterawsuser ^
--master-user-password masteruserpassword ^
--backup-retention-period 3

This command produces output similar to the following.

DBINSTANCE mydbinstance db.t3.large sqlserver-se 250 sa creating 3 **** n

10.50.2789
SECGROUP default active
PARAMGRP default.sqlserver-se-14 in-sync

RDS API
To create a DB instance by using the Amazon RDS API, call the CreateDBInstance operation with the
following parameters.

150
 Amazon Relational Database Service User Guide
Available settings

For information about each setting, see Settings for DB instances (p. 151).

• AllocatedStorage
• BackupRetentionPeriod
• DBInstanceClass
• DBInstanceIdentifier
• VpcSecurityGroupIds
• DBSubnetGroup
• Engine
• MasterUsername
• MasterUserPassword

Settings for DB instances

In the following table, you can find details about settings that you choose when you create a DB
instance. The table also shows the DB engines for which each setting is supported.

You can create a DB instance using the console, the create-db-instance CLI command, or the
CreateDBInstance RDS API operation.

Console setting Setting description CLI option and RDS API parameter Supported
DB engines

Allocated The amount of storage to allocate CLI option: All

storage for your DB instance (in gigabytes).
In some cases, allocating a higher --allocated-storage
amount of storage for your
DB instance than the size of API parameter:
your database can improve I/O
AllocatedStorage
performance.

For more information, see Amazon

RDS DB instance storage (p. 40).

Auto minor Enable auto minor version upgrade CLI option: All except
version upgrade to enable your DB instance to SQL Server
receive preferred minor DB engine --auto-minor-version-upgrade
version upgrades automatically
when they become available. --no-auto-minor-version-
Amazon RDS performs automatic upgrade
minor version upgrades in the
API parameter:
maintenance window.
AutoMinorVersionUpgrade

Availability zone The Availability Zone for your DB CLI option: All
instance. Use the default value of
No Preference unless you want to --availability-zone
specify an Availability Zone.
API parameter:
For more information, see Regions,
Availability Zones, and Local Zones AvailabilityZone
(p. 49).

151
 Amazon Relational Database Service User Guide
Available settings

Console setting Setting description CLI option and RDS API parameter Supported
DB engines

Backup Choose Enable replication to Not available when creating a DB Oracle

replication another AWS Region to create instance. For information on enabling
backups in an additional Region for cross-Region backups using the AWS CLI
disaster recovery. or RDS API, see Enabling cross-Region
automated backups (p. 344).
Then choose the Destination
Region for the additional backups.

Backup The number of days that you want CLI option: All
retention period automatic backups of your DB
instance to be retained. For any --backup-retention-period
nontrivial DB instance, set this value
to 1 or greater. API parameter:

For more information, see Working BackupRetentionPeriod

with backups (p. 334).

Backup window The time period during which CLI option: All
Amazon RDS automatically takes
a backup of your DB instance. --preferred-backup-window
Unless you have a specific time that
you want to have your database API parameter:
backed up, use the default of No
PreferredBackupWindow
Preference.

For more information, see Working

with backups (p. 334).

Character set The character set for your DB CLI option: Oracle
instance. The default value of
AL32UTF8 for the DB character --character-set-name
set is for the Unicode 5.0 UTF-8
Universal character set. You can't API parameter:
change the DB character set after
CharacterSetName
you create the DB instance.

The DB character set is different

from the national character set,
which is called the NCHAR character
set. Unlike the DB character set,
the NCHAR character set specifies
the encoding for NCHAR data types
(NCHAR, NVARCHAR2, and NCLOB)
columns without affecting database
metadata.

For more information, see RDS for

Oracle character sets (p. 1000).

Collation A server-level collation for your DB CLI option: SQL Server

instance.
--character-set-name
For more information, see Server-
level collation for Microsoft SQL API parameter:
Server (p. 818).
CharacterSetName

152
 Amazon Relational Database Service User Guide
Available settings

Console setting Setting description CLI option and RDS API parameter Supported
DB engines

Copy tags to This option copies any DB instance CLI option: All
snapshots tags to a DB snapshot when you
create a snapshot. --copy-tags-to-snapshot

For more information, see Tagging --no-copy-tags-to-snapshot

Amazon RDS resources (p. 305).
RDS API parameter:

CopyTagsToSnapshot

Database port The port that you want to access CLI option: All
the DB instance through. The
default port is shown. If you use --port
a DB security group with your DB
instance, this port value must be the RDS API parameter:
same one that you provided when
Port
creating the DB security group.
Note
The firewalls at some
companies block
connections to the default
MariaDB, MySQL, and
PostgreSQL ports. If your
company firewall blocks the
default port, enter another
port for your DB instance.

153
 Amazon Relational Database Service User Guide
Available settings

Console setting Setting description CLI option and RDS API parameter Supported
DB engines

Database The database authentication option IAM: MySQL

authentication that you want to use.
CLI option: Oracle
Choose Password authentication
to authenticate database users with --enable-iam-database- PostgreSQL
database passwords only. authentication

Choose Password and IAM DB --no-enable-iam-database-

authentication to authenticate authentication
database users with database
passwords and user credentials RDS API parameter:
through IAM users and roles. For
EnableIAMDatabaseAuthentication
more information, see IAM database
authentication for MySQL and Kerberos:
PostgreSQL (p. 1650). This option
is only supported for MySQL and CLI option:
PostgreSQL.
--domain
Choose Password and Kerberos
authentication to authenticate --domain-iam-role-name
database users with database
passwords and Kerberos RDS API parameter:
authentication through an AWS
Managed Microsoft AD created with Domain
AWS Directory Service. Next, choose
DomainIAMRoleName
the directory or choose Create a
new Directory.

For more information, see one of the

following:

• Using Kerberos authentication for

MySQL (p. 942)
• Configuring Kerberos
authentication for Amazon RDS
for Oracle (p. 1018)
• Using Kerberos authentication
with Amazon RDS for
PostgreSQL (p. 1553)

DB engine The version of database engine that CLI option: All

version you want to use.
--engine-version

RDS API parameter:

EngineVersion

154
 Amazon Relational Database Service User Guide
Available settings

Console setting Setting description CLI option and RDS API parameter Supported
DB engines

DB instance The configuration for your DB CLI option: All

class instance. For example, a db.t3.small
instance class has 2 GiB memory, 2 --db-instance-class
vCPUs, 1 virtual core, a variable ECU,
and a moderate I/O capacity. RDS API parameter:

If possible, choose an instance class DBInstanceClass

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, which improves
performance.

For more information, see DB

instance classes (p. 7).

DB instance The name for your DB instance. CLI option: All

identifier Name your DB instances in the
same way that you name your on- --db-instance-identifier
premises servers. Your DB instance
identifier can contain up to 63 RDS API parameter:
alphanumeric characters, and must
DBInstanceIdentifier
be unique for your account in the
AWS Region you chose. You can add
some intelligence to the name, such
as including the AWS Region and
DB engine you chose, for example
sqlsrvr-instance1.

DB parameter A parameter group for your DB CLI option: All

group instance. You can choose the default
parameter group or you can create a --db-parameter-group-name
custom parameter group.
RDS API parameter:
For more information, see
Working with DB parameter DBParameterGroupName
groups (p. 234).

Deletion Enable deletion protection to CLI option: All

protection prevent your DB instance from
being deleted. If you create a --deletion-protection
production DB instance with the
AWS Management Console, deletion --no-deletion-protection
protection is enabled by default.
RDS API parameter:
For more information, see Deleting a
DeletionProtection
DB instance (p. 330).

155
 Amazon Relational Database Service User Guide
Available settings

Console setting Setting description CLI option and RDS API parameter Supported
DB engines

Encryption Enable Encryption to enable CLI option: All

encryption at rest for this DB
instance. --storage-encrypted

For more information, see --no-storage-encrypted

Encrypting Amazon RDS
resources (p. 1620). RDS API parameter:

StorageEncrypted

Enhanced Enable enhanced monitoring to CLI options: All

Monitoring enable gathering metrics in real
time for the operating system that --monitoring-interval
your DB instance runs on.
--monitoring-role-arn
For more information, see Using
Enhanced Monitoring (p. 477). RDS API parameters:

MonitoringInterval

MonitoringRoleArn

156
 Amazon Relational Database Service User Guide
Available settings

Console setting Setting description CLI option and RDS API parameter Supported
DB engines

Initial database The name for the database on your CLI option: All except
name DB instance. If you don't provide a SQL Server
name, Amazon RDS doesn't create a --db-name
database on the DB instance (except
for Oracle and PostgreSQL). The RDS API parameter:
name can't be a word reserved by
DBName
the database engine, and has other
constraints depending on the DB
engine.

MariaDB and MySQL:

• It must contain 1–64

alphanumeric characters.

Oracle:

• It must contain 1–8 alphanumeric

characters.
• It can't be NULL. The default value
is ORCL.
• It must begin with a letter.

PostgreSQL:

• It must contain 1–63

alphanumeric characters.
• It must begin with a letter or
an underscore. Subsequent
characters can be letters,
underscores, or digits (0-9).
• The initial database name is
postgres.

License The license model: CLI option: SQL Server

• Choose license-included for --license-model Oracle

Microsoft SQL Server.
RDS API parameter:
• Choose license-included or bring-
your-own-license for Oracle. LicenseModel

Maintenance The 30-minute window in which CLI option: All

window pending modifications to your DB
instance are applied. If the time --preferred-maintenance-window
period doesn't matter, choose No
Preference. RDS API parameter:

For more information, see The PreferredMaintenanceWindow

Amazon RDS maintenance
window (p. 274).

157
 Amazon Relational Database Service User Guide
Available settings

Console setting Setting description CLI option and RDS API parameter Supported
DB engines

Master The password for your master user CLI option: All
password account. The password has the
following number of printable ASCII --master-user-password
characters (excluding /, ", a space,
and @) depending on the DB engine: RDS API parameter:

• Oracle: 8–30 MasterUserPassword

• MariaDB and MySQL: 8–41
• SQL Server and PostgreSQL: 8–
128

Master The name that you use as the CLI option: All
username master user name to log on to
your DB instance with all database --master-username
privileges.
RDS API parameter:
• It can contain 1–16 alphanumeric
characters and underscores. MasterUsername
• Its first character must be a letter.
• It can't be a word reserved by the
database engine.

For more information on privileges

granted to the master user, see the
following topics:

• MariaDB security on Amazon

RDS (p. 589)
• Microsoft SQL Server
security (p. 642)
• MySQL security on Amazon
RDS (p. 837)
• Securing Oracle DB instance
connections (p. 1014)
• Amazon RDS for PostgreSQL
versions and extensions (p. 1568)

Microsoft SQL Enable Microsoft SQL Server CLI options: SQL Server
Server Windows Windows authentication, then
Authentication Browse Directory to choose the --domain
directory where you want to
allow authorized domain users --domain-iam-role-name
to authenticate with this SQL
RDS API parameters:
Server instance using Windows
Authentication. Domain

DomainIAMRoleName

158
 Amazon Relational Database Service User Guide
Available settings

Console setting Setting description CLI option and RDS API parameter Supported
DB engines

Multi-AZ Create a standby instance to CLI option: All

deployment create a passive secondary replica
of your DB instance in another --multi-az
Availability Zone for failover
support. We recommend Multi- --no-multi-az
AZ for production workloads to
RDS API parameter:
maintain high availability.
MultiAZ
For development and testing, you
can choose Do not create a standby
instance.

For more information, see High

availability (Multi-AZ) for Amazon
RDS (p. 53).

National The national character set for your CLI option: Oracle
character set DB instance, commonly called the
(NCHAR) NCHAR character set. You can set --nchar-character-set-name
the national character set to either
AL16UTF16 (default) or UTF-8. You API parameter:
can't change the national character
NcharCharacterSetName
set after you create the DB instance.

The national character set is

different from the DB character set.
Unlike the DB character set, the
national character set specifies the
encoding only for NCHAR data types
(NCHAR, NVARCHAR2, and NCLOB)
columns without affecting database
metadata.

For more information, see RDS for

Oracle character sets (p. 1000).

Option group An option group for your DB CLI option: All

instance. You can choose the default
option group or you can create a --option-group-name
custom option group.
RDS API parameter:
For more information, see Working
with option groups (p. 218). OptionGroupName

159
 Amazon Relational Database Service User Guide
Available settings

Console setting Setting description CLI option and RDS API parameter Supported
DB engines

Performance Enable Performance Insights CLI options: All

Insights to monitor your DB instance
load so that you can analyze --enable-performance-insights
and troubleshoot your database
performance. --no-enable-performance-
insights
Choose a retention period to
determine how much rolling data --performance-insights-
history to keep. The default of seven retention-period
days is in the free tier. Long-term
--performance-insights-kms-
retention (two years) is priced per
key-id
vCPU per month.
RDS API parameters:
Choose a master key to use to
protect the key used to encrypt EnablePerformanceInsights
this database volume. Choose from
the master keys in your account, PerformanceInsightsRetentionPeriod
or enter the key from a different
account. PerformanceInsightsKMSKeyId

For more information, see Using

Performance Insights on Amazon
RDS (p. 418).

160
 Amazon Relational Database Service User Guide
Available settings

Console setting Setting description CLI option and RDS API parameter Supported
DB engines

Public access Publicly accessible to give the CLI option: All

DB instance a public IP address,
meaning that it's accessible outside --publicly-accessible
the VPC. To be publicly accessible,
the DB instance also has to be in a --no-publicly-accessible
public subnet in the VPC.
RDS API parameter:
Not publicly accessible to make the
PubliclyAccessible
DB instance accessible only from
inside the VPC.

For more information, see Hiding

a DB instance in a VPC from the
internet (p. 1716).

To connect to a DB instance from

outside of its Amazon VPC, the
DB instance must be publicly
accessible, access must be granted
using the inbound rules of the DB
instance's security group, and other
requirements must be met. For more
information, see Can't connect to
Amazon RDS DB instance (p. 1733).

If your DB instance is isn't publicly

accessible, you can also use an AWS
Site-to-Site VPN connection or an
AWS Direct Connect connection to
access it from a private network. For
more information, see Internetwork
traffic privacy (p. 1633).

Storage Enable storage autoscaling CLI option: All

autoscaling to enable Amazon RDS to
automatically increase storage when --max-allocated-storage
needed to avoid having your DB
instance run out of storage space. RDS API parameter:

Use Maximum storage threshold to MaxAllocatedStorage

set the upper limit for Amazon RDS
to automatically increase storage
for your DB instance. The default is
1,000 GiB.

For more information, see Managing

capacity automatically with Amazon
RDS storage autoscaling (p. 323).

161
 Amazon Relational Database Service User Guide
Available settings

Console setting Setting description CLI option and RDS API parameter Supported
DB engines

Storage type The storage type for your DB CLI option: All
instance.
--storage-type
For more information, see Amazon
RDS storage types (p. 40). RDS API parameter:

StorageType

Subnet group This setting depends on the CLI option: All

platform that you are on. If you are
a new customer to AWS, choose --db-subnet-group-name
default, which is the default DB
subnet group that was created for RDS API parameter:
your account.
DBSubnetGroupName
If you are creating a DB instance on
the earlier E2-Classic platform, you
might want your DB instance in a
specific VPC. In this case, choose the
DB subnet group that you created
for that VPC.

Time zone The time zone for your DB instance. CLI option: SQL Server
If you don't choose a time zone,
your DB instance uses the default --timezone
time zone. You can't change the
time zone after the DB instance is RDS API parameter:
created.
Timezone
For more information, see Local
time zone for Microsoft SQL Server
DB instances (p. 653).

Virtual Private This setting depends on the For the CLI and API, you specify the VPC All
Cloud (VPC) platform that you are on. If you are security group IDs.
a new customer to AWS, choose
the default VPC shown. If you are
creating a DB instance on the earlier
E2-Classic platform that doesn't use
a VPC, choose Not in VPC.

For more information, see Amazon

Virtual Private Cloud VPCs and
Amazon RDS (p. 1705).

162
 Amazon Relational Database Service User Guide
Original console example

Console setting Setting description CLI option and RDS API parameter Supported
DB engines

VPC security If you are a new customer to AWS, CLI option: All
group Create new to create a new VPC
security group. Otherwise, Choose --vpc-security-group-ids
existing, then choose from security
groups that you previously created. RDS API parameter:

When you choose Create new in the VpcSecurityGroupIds

RDS console, a new security group
is created. This new security group
has 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. 1691).

Original console example

You can create a DB instance with the original AWS Management Console. This example uses Microsoft
SQL Server.

To launch a SQL Server 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 upper-right corner of the Amazon RDS console, choose the AWS Region in which you want to
create the DB instance.
3. In the navigation pane, choose Databases.

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. Choose the Microsoft SQL Server icon.

163
 Amazon Relational Database Service User Guide
Original console example

6. Choose the SQL Server DB engine edition that you want to use. The SQL Server editions that are
available vary by AWS Region.
7. For some editions, the Use Case step asks if you are planning to use the DB instance you are creating
for production. If you are, choose Production. If you choose Production, the following are all
preselected in a later step:

• Multi-AZ failover option

164
 Amazon Relational Database Service User Guide
Original console example

• Provisioned IOPS storage option

• Enable deletion protection option

We recommend these features for any production environment.

8. 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 DB instances (p. 151).

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

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 DB
instances (p. 151).

165
 Amazon Relational Database Service User Guide
Original console example

10. Choose Launch DB Instance.

11. On the final page of the wizard, choose Close.

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.

166
Amazon Relational Database Service User Guide
Original console example

167
 Amazon Relational Database Service User Guide
Connecting to a DB instance

Connecting to an Amazon RDS DB instance

Before you can connect to a DB instance, you must create the DB instance. For information, see Creating
an Amazon RDS DB instance (p. 147). After Amazon RDS provisions your DB instance, you can use any
standard client application or utility for your DB engine to connect to the DB 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.

Topics
• Finding the connection information for an Amazon RDS DB instance (p. 168)
• Database authentication options (p. 171)
• Encrypted connections (p. 172)
• Scenarios for accessing a DB instance in a VPC (p. 172)
• Connecting to a DB instance that is running a specific DB engine (p. 172)
• Managing connections with RDS Proxy (p. 173)
• Managing connections with Amazon RDS Proxy (p. 173)

Finding the connection information for an Amazon

RDS DB instance
The connection information for a DB instance includes its endpoint, port, and a valid database user,
such as the master user. For example, for a MySQL DB instance, suppose that the endpoint value is
mydb.123456789012.us-east-1.rds.amazonaws.com. In this case, the port value is 3306, and the
database user is admin. Given this information, you specify the following values in a connection string:

• For host or host name or DNS name, specify mydb.123456789012.us-

east-1.rds.amazonaws.com.
• For port, specify 3306.
• For user, specify admin.

The endpoint is unique for each DB instance, and the values of the port and user can vary. The following
list shows the most common port for each DB engine:

• MariaDB – 3306
• Microsoft SQL Server – 1433
• MySQL – 3306
• Oracle – 1521
• PostgreSQL – 5432

To connect to a DB instance, use any client for a DB engine. For example, you might use the mysql utility
to connect to a MariaDB or MySQL DB instance. You might use Microsoft SQL Server Management Studio
to connect to a SQL Server DB instance. You might use Oracle SQL Developer to connect to an Oracle DB
instance, or the psql command line utility to connect to a PostgreSQL DB instance.

To find the connection information for a DB instance, you can use the AWS Management Console, the
AWS Command Line Interface (AWS CLI) describe-db-instances command, or the Amazon RDS API
DescribeDBInstances operation to list its details.

168
 Amazon Relational Database Service User Guide
Finding the connection information

Console

To find the connection information for a DB instance in 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. In the navigation pane, choose Databases to display a list of your DB instances.
3. Choose the name of the DB instance to display its details.
4. On the Connectivity & security tab, copy the endpoint. Also, note the port number. You need both
the endpoint and the port number to connect to the DB instance.

169
 Amazon Relational Database Service User Guide
Finding the connection information

5. If you need to find the master user name, choose the Configuration tab and view the Master
username value.

AWS CLI
To find the connection information for a DB instance by using the AWS CLI, call the describe-db-
instances command. In the call, query for the DB instance ID, endpoint, port, and master user name.

170
 Amazon Relational Database Service User Guide
Database authentication options

For Linux, macOS, or Unix:

aws rds describe-db-instances \

--query "*[].[DBInstanceIdentifier,Endpoint.Address,Endpoint.Port,MasterUsername]"

For Windows:

aws rds describe-db-instances ^

--query "*[].[DBInstanceIdentifier,Endpoint.Address,Endpoint.Port,MasterUsername]"

Your output should be similar to the following.

[
[
"mydb",
"mydb.123456789012.us-east-1.rds.amazonaws.com",
3306,
"admin"
],
[
"myoracledb",
"myoracledb.123456789012.us-east-1.rds.amazonaws.com",
1521,
"dbadmin"
],
[
"mypostgresqldb",
"mypostgresqldb.123456789012.us-east-1.rds.amazonaws.com",
5432,
"postgresadmin"
]
]

RDS API
To find the connection information for a DB instance by using the Amazon RDS API, call the
DescribeDBInstances operation. In the output, find the values for the endpoint address, endpoint port,
and master user name.

Database authentication options

Amazon RDS supports the following ways to authenticate database users:

• Password authentication – Your DB instance performs all administration of user accounts. You create
users and specify passwords with SQL statements. The SQL statements you can use depend on your
DB engine.
• AWS Identity and Access Management (IAM) database authentication – You don't need to use a
password when you connect to a DB instance. Instead, you use an authentication token.
• Kerberos authentication – You use external authentication of database users using Kerberos and
Microsoft Active Directory. Kerberos is a network authentication protocol that uses tickets and
symmetric-key cryptography to eliminate the need to transmit passwords over the network. Kerberos
has been built into Active Directory and is designed to authenticate users to network resources, such as
databases.

IAM database authentication and Kerberos authentication are available only for specific DB engines and
versions.

For more information, see Database authentication with Amazon RDS (p. 1618).

171
 Amazon Relational Database Service User Guide
Encrypted connections

Encrypted connections
You can use Secure Socket Layer (SSL) or Transport Layer Security (TLS) from your application to encrypt
a connection to a DB instance. Each DB engine has its own process for implementing SSL/TLS. For more
information, see Using SSL/TLS to encrypt a connection to a DB instance (p. 1624).

Scenarios for accessing a DB instance in a VPC

Using Amazon Virtual Private Cloud (Amazon VPC), you can launch AWS resources, such as Amazon
RDS DB instances, into a virtual private cloud (VPC). When you use Amazon VPC, you have control over
your virtual networking environment. You can choose your own IP address range, create subnets, and
configure routing and access control lists.

A VPC security group controls access to DB instances inside a VPC. 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.

Before attempting to connect to your DB instance, configure your VPC for your use case. The following
are common scenarios for accessing a DB instance in a VPC:

• A DB instance in a VPC accessed by an Amazon EC2 instance in the same VPC – A common use of a
DB instance in a VPC is to share data with an application server that is running in an EC2 instance in
the same VPC. The EC2 instance might run a web server with an application that interacts with the DB
instance.
• 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 that you're using to access it, you can use VPC peering to access
the DB instance.
• 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.

To connect to a DB instance from outside of its VPC, the DB instance must be publicly accessible.
Also, access must be granted using the inbound rules of the DB instance's security group, and
other requirements must be met. For more information, see Can't connect to Amazon RDS DB
instance (p. 1733).
• A DB instance in a VPC accessed by a private network – If your DB instance isn't publicly accessible,
you can use an AWS Site-to-Site VPN connection or an AWS Direct Connect connection to access it
from a private network.
• A DB instance in a VPC accessed by an EC2 instance not in a VPC – You can communicate between a
DB instance that is in a VPC and an EC2 instance that is not in a VPC by using ClassicLink.

For more information, see Scenarios for accessing a DB instance in a VPC (p. 1707).

Connecting to a DB instance that is running a specific

DB engine
For information about connecting to a DB instance that is running a specific DB engine, follow the
instructions for your DB engine:

• Connecting to a DB instance running the MariaDB database engine (p. 595)

• Connecting to a DB instance running the Microsoft SQL Server database engine (p. 663)
• Connecting to a DB instance running the MySQL database engine (p. 844)

172
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

• Connecting to your Oracle DB instance (p. 1005)

• Connecting to a DB instance running the PostgreSQL database engine (p. 1460)

Managing connections with RDS Proxy

You can also use Amazon RDS Proxy to manage connections to MySQL and PostgreSQL DB instances.
RDS Proxy allows applications to pool and share database connections to improve scalability.

• Managing connections with Amazon RDS Proxy (p. 173)

Managing connections with Amazon RDS Proxy

By using Amazon RDS Proxy, you can allow your applications to pool and share database connections
to improve their ability to scale. RDS Proxy makes applications more resilient to database failures by
automatically connecting to a standby DB instance while preserving application connections. RDS Proxy
also enables you to enforce AWS Identity and Access Management (IAM) authentication for databases,
and securely store credentials in AWS Secrets Manager.
Note
RDS Proxy is fully compatible with MySQL and PostgreSQL. You can enable RDS Proxy for most
applications with no code changes.

Using RDS Proxy, you can handle unpredictable surges in database traffic that otherwise might cause
issues due to oversubscribing connections or creating new connections at a fast rate. RDS Proxy
establishes a database connection pool and reuses connections in this pool without the memory and
CPU overhead of opening a new database connection each time. To protect the database against
oversubscription, you can control the number of database connections that are created.

RDS Proxy queues or throttles application connections that can't be served immediately from the pool
of connections. Although latencies might increase, your application can continue to scale without
abruptly failing or overwhelming the database. If connection requests exceed the limits you specify, RDS
Proxy rejects application connections (that is, it sheds load). At the same time, it maintains predictable
performance for the load that can be served with the available capacity.

You can reduce the overhead to process credentials and establish a secure connection for each new
connection. RDS Proxy can handle some of that work on behalf of the database.

Topics
• RDS Proxy concepts and terminology (p. 173)
• Planning for and setting up RDS Proxy (p. 177)
• Connecting to a database through RDS Proxy (p. 188)
• Managing an RDS Proxy (p. 190)
• Monitoring RDS Proxy using Amazon CloudWatch (p. 198)
• Endpoints for Amazon RDS Proxy (p. 203)
• Command-line examples for RDS Proxy (p. 209)
• Troubleshooting for RDS Proxy (p. 211)
• Using RDS Proxy with AWS CloudFormation (p. 217)

RDS Proxy concepts and terminology

You can simplify connection management for your Amazon RDS DB instances and Amazon Aurora DB
clusters by using RDS Proxy.

173
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

RDS Proxy handles the network traffic between the client application and the database. It does so in an
active way first by understanding the database protocol. It then adjusts its behavior based on the SQL
operations from your application and the result sets from the database.

RDS Proxy reduces the memory and CPU overhead for connection management on your database.
The database needs less memory and CPU resources when applications open many simultaneous
connections. It also doesn't require logic in your applications to close and reopen connections that stay
idle for a long time. Similarly, it requires less application logic to reestablish connections in case of a
database problem.

The infrastructure for RDS Proxy is highly available and deployed over multiple Availability Zones (AZs).
The computation, memory, and storage for RDS Proxy are independent of your RDS DB instances and
Aurora DB clusters. This separation helps lower overhead on your database servers, so that they can
devote their resources to serving database workloads. The RDS Proxy compute resources are serverless,
automatically scaling based on your database workload.

Topics
• Overview of RDS Proxy concepts (p. 174)
• Connection pooling (p. 175)
• RDS Proxy security (p. 175)
• Failover (p. 176)
• Transactions (p. 177)

Overview of RDS Proxy concepts

RDS Proxy handles the infrastructure to perform connection pooling and the other features described
following. You see the proxies represented in the RDS console on the Proxies page.

Each proxy handles connections to a single RDS DB instance or Aurora DB cluster. The proxy
automatically determines the current writer instance for RDS Multi-AZ DB instances and Aurora
provisioned clusters. For Aurora multi-master clusters, the proxy connects to one of the writer instances
and uses the other writer instances as hot standby targets.

The connections that a proxy keeps open and available for your database application to use form the
connection pool.

By default, RDS Proxy can reuse a connection after each transaction in your session. This transaction-
level reuse is called multiplexing. When RDS Proxy temporarily removes a connection from the
connection pool to reuse it, that operation is called borrowing the connection. When it's safe to do so,
RDS Proxy returns that connection to the connection pool.

In some cases, RDS Proxy can't be sure that it's safe to reuse a database connection outside of the current
session. In these cases, it keeps the session on the same connection until the session ends. This fallback
behavior is called pinning.

A proxy has a default endpoint. You connect to this endpoint when you work with an RDS DB instance
or Aurora DB cluster, instead of connecting to the read/write endpoint that connects directly to the
instance or cluster. The special-purpose endpoints for an Aurora cluster remain available for you to use.
For Aurora DB clusters, you can also create additional read/write and read-only endpoints. For more
information, see Overview of proxy endpoints (p. 203).

For example, you can still connect to the cluster endpoint for read/write connections without connection
pooling. You can still connect to the reader endpoint for load-balanced read-only connections. You
can still connect to the instance endpoints for diagnosis and troubleshooting of specific DB instances
within an Aurora cluster. If you are using other AWS services such as AWS Lambda to connect to RDS
databases, you change their connection settings to use the proxy endpoint. For example, you specify the
proxy endpoint to allow Lambda functions to access your database while taking advantage of RDS Proxy
functionality.

174
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

Each proxy contains a target group. This target group embodies the RDS DB instance or Aurora DB cluster
that the proxy can connect to. For an Aurora cluster, by default the target group is associated with all
the DB instances in that cluster. That way, the proxy can connect to whichever Aurora DB instance is
promoted to be the writer instance in the cluster. The RDS DB instance associated with a proxy, or the
Aurora DB cluster and its instances, are called the targets of that proxy. For convenience, when you create
a proxy through the console, RDS Proxy also creates the corresponding target group and registers the
associated targets automatically.

An engine family is a related set of database engines that use the same DB protocol. You choose the
engine family for each proxy that you create.

Connection pooling
Each proxy performs connection pooling for the writer instance of its associated RDS or Aurora database.
Connection pooling is an optimization that reduces the overhead associated with opening and closing
connections and with keeping many connections open simultaneously. This overhead includes memory
needed to handle each new connection. It also involves CPU overhead to close each connection and
open a new one, such as Transport Layer Security/Secure Sockets Layer (TLS/SSL) handshaking,
authentication, negotiating capabilities, and so on. Connection pooling simplifies your application logic.
You don't need to write application code to minimize the number of simultaneous open connections.

Each proxy also performs connection multiplexing, also known as connection reuse. With multiplexing,
RDS Proxy perform all the operations for a transaction using one underlying database connection, then
can use a different connection for the next transaction. You can open many simultaneous connections
to the proxy, and the proxy keeps a smaller number of connections open to the DB instance or cluster.
Doing so further minimizes the memory overhead for connections on the database server. This technique
also reduces the chance of "too many connections" errors.

RDS Proxy security

RDS Proxy uses the existing RDS security mechanisms such as TLS/SSL and AWS Identity and Access
Management (IAM). For general information about those security features, see Security in Amazon
RDS (p. 1617). If you aren't familiar with how RDS and Aurora work with authentication, authorization,
and other areas of security, make sure to familiarize yourself with how RDS and Aurora work with those
areas first.

RDS Proxy can act as an additional layer of security between client applications and the underlying
database. For example, you can connect to the proxy using TLS 1.2, even if the underlying DB instance
supports only TLS 1.0 or 1.1. You can connect to the proxy using an IAM role, even if the proxy connects
to the database using the native user and password authentication method. By using this technique, you
can enforce strong authentication requirements for database applications without a costly migration
effort for the DB instances themselves.

You store the database credentials used by RDS Proxy in AWS Secrets Manager. Each database user
for the RDS DB instance or Aurora DB cluster accessed by a proxy must have a corresponding secret
in Secrets Manager. You can also set up IAM authentication for users of RDS Proxy. By doing so,
you can enforce IAM authentication for database access even if the databases use native password
authentication. We recommend using these security features instead of embedding database credentials
in your application code.

Using TLS/SSL with RDS Proxy

You can connect to RDS Proxy using the TLS/SSL protocol.
Note
RDS Proxy uses certificates from the AWS Certificate Manager (ACM). If you use RDS Proxy, when
you rotate your TLS/SSL certificate you don't need to update applications that use RDS Proxy
connections.

To enforce TLS for all connections between the proxy and your database, you can specify a setting
Require Transport Layer Security when you create or modify a proxy.

175
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

RDS Proxy can also ensure that your session uses TLS/SSL between your client and the RDS Proxy
endpoint. To have RDS Proxy do so, specify the requirement on the client side. SSL session variables are
not set for SSL connections to a database using RDS Proxy.

• For RDS for MySQL and Aurora MySQL, specify the requirement on the client side with the --ssl-
mode parameter when you run the mysql command.
• For Amazon RDS PostgreSQL and Aurora PostgreSQL, specify sslmode=require as part of the
conninfo string when you run the psql command.

RDS Proxy supports TLS protocol version 1.0, 1.1, and 1.2. You can connect to the proxy using a higher
version of TLS than you use in the underlying database.

By default, client programs establish an encrypted connection with RDS Proxy, with further control
available through the --ssl-mode option. From the client side, RDS Proxy supports all SSL modes.

For the client, the SSL modes are the following:

PREFERRED

SSL is the first choice, but it isn't required.

DISABLED

No SSL is allowed.
REQUIRED

Enforce SSL.
VERIFY_CA

Enforce SSL and verify the certificate authority (CA).

VERIFY_IDENTITY

Enforce SSL and verify the CA and CA hostname.

Note
You can use the SSL mode VERIFY_IDENTITY when connecting to the default proxy
endpoint. You can't use that SSL mode when you connect to proxy endpoints that you
create.

When using a client with --ssl-mode VERIFY_CA or VERIFY_IDENTITY, specify the --ssl-ca option
pointing to a CA in .pem format. For a .pem file that you can use, download the Amazon root CA 1 trust
store from Amazon Trust Services.

RDS Proxy uses wildcard certificates, which apply to a both a domain and its subdomains. If you use the
mysql client to connect with SSL mode VERIFY_IDENTITY, currently you must use the MySQL 8.0-
compatible mysql command.

Failover
Failover is a high-availability feature that replaces a database instance with another one when the
original instance becomes unavailable. A failover might happen because of a problem with a database
instance. It might also be part of normal maintenance procedures, such as during a database upgrade.
Failover applies to RDS DB instances in a Multi-AZ configuration, and Aurora DB clusters with one or
more reader instances in addition to the writer instance.

Connecting through a proxy makes your application more resilient to database failovers. When the
original DB instance becomes unavailable, RDS Proxy connects to the standby database without dropping
idle application connections. Doing so helps to speed up and simplify the failover process. The result is
faster failover that's less disruptive to your application than a typical reboot or database problem.

176
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

Without RDS Proxy, a failover involves a brief outage. During the outage, you can't perform write
operations on that database. Any existing database connections are disrupted and your application must
reopen them. The database becomes available for new connections and write operations when a read-
only DB instance is promoted to take the place of the one that's unavailable.

During DB failovers, RDS Proxy continues to accept connections at the same IP address and automatically
directs connections to the new primary DB instance. Clients connecting through RDS Proxy are not
susceptible to the following:

• Domain Name System (DNS) propagation delays on failover.

• Local DNS caching.
• Connection timeouts.
• Uncertainty about which DB instance is the current writer.
• Waiting for a query response from a former writer that became unavailable without closing
connections.

For applications that maintain their own connection pool, going through RDS Proxy means that most
connections stay alive during failovers or other disruptions. Only connections that are in the middle of a
transaction or SQL statement are canceled. RDS Proxy immediately accepts new connections. When the
database writer is unavailable, RDS Proxy queues up incoming requests.

For applications that don't maintain their own connection pools, RDS Proxy offers faster connection
rates and more open connections. It offloads the expensive overhead of frequent reconnects from the
database. It does so by reusing database connections maintained in the RDS Proxy connection pool. This
approach is particularly important for TLS connections, where setup costs are significant.

Transactions
All the statements within a single transaction always use the same underlying database connection.
The connection becomes available for use by a different session when the transaction ends. Using the
transaction as the unit of granularity has the following consequences:

• Connection reuse can happen after each individual statement when the RDS for MySQL or Aurora
MySQL autocommit setting is enabled.
• Conversely, when the autocommit setting is disabled, the first statement you issue in a session
begins a new transaction. Thus, if you enter a sequence of SELECT, INSERT, UPDATE, and other data
manipulation language (DML) statements, connection reuse doesn't happen until you issue a COMMIT,
ROLLBACK, or otherwise end the transaction.
• Entering a data definition language (DDL) statement causes the transaction to end after that
statement completes.

RDS Proxy detects when a transaction ends through the network protocol used by the database client
application. Transaction detection doesn't rely on keywords such as COMMIT or ROLLBACK appearing in
the text of the SQL statement.

In some cases, RDS Proxy might detect a database request that makes it impractical to move your session
to a different connection. In these cases, it turns off multiplexing for that connection the remainder
of your session. The same rule applies if RDS Proxy can't be certain that multiplexing is practical for
the session. This operation is called pinning. For ways to detect and minimize pinning, see Avoiding
pinning (p. 196).

Planning for and setting up RDS Proxy

In the following sections, you can find how to set up RDS Proxy. You can also find how to set the related
security options that control who can access each proxy and how each proxy connects to DB instances.

177
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

Topics
• Limits for RDS Proxy (p. 178)
• Identifying DB instances, clusters, and applications to use with RDS Proxy (p. 179)
• Setting up network prerequisites (p. 180)
• Setting up database credentials in AWS Secrets Manager (p. 181)
• Setting up AWS Identity and Access Management (IAM) policies (p. 182)
• Creating an RDS Proxy (p. 184)
• Viewing an RDS Proxy (p. 187)

Limits for RDS Proxy

The following limitations apply to RDS Proxy:

• RDS Proxy is available only in certain AWS Regions only. For more information, see Amazon RDS Proxy.

You can have up to 20 proxies for each AWS account ID. If your application requires more proxies, you
can request additional proxies by opening a ticket with the AWS Support organization.
• Each proxy can have up to 200 associated Secrets Manager secrets. Thus, each proxy can connect to
with up to 200 different user accounts at any given time.
• You can create, view, modify, and delete up to 20 endpoints for each proxy. These endpoints are in
addition to the default endpoint that's automatically created for each proxy.
• In an Aurora cluster, all of the connections using the default proxy endpoint are handled by the Aurora
writer instance. To perform load balancing for read-intensive workloads, you can create a read-only
endpoint for a proxy. That endpoint passes connections to the reader endpoint of the cluster. That
way, your proxy connections can take advantage of Aurora read scalability. For more information, see
Overview of proxy endpoints (p. 203).

For RDS DB instances in replication configurations, you can associate a proxy only with the writer DB
instance, not a read replica.
• You can't use RDS Proxy with Aurora Serverless clusters.
• You can't use RDS Proxy with Aurora clusters that are part of an Aurora global database.
• Your RDS Proxy must be in the same VPC as the database. The proxy can't be publicly accessible,
although the database can be.
Note
For Aurora DB clusters, you can enable cross-VPC access by creating an additional endpoint
for a proxy and specifying a different VPC, subnets, and security groups with that endpoint.
For more information, see Accessing Aurora and RDS databases across VPCs (p. 204).
• You can't use RDS Proxy with a VPC that has dedicated tenancy.
• If you use RDS Proxy with an RDS DB instance or Aurora DB cluster that has IAM authentication
enabled, make sure that all users who connect through a proxy authenticate through user names and
passwords. See Setting up AWS Identity and Access Management (IAM) policies (p. 182) for details
about IAM support in RDS Proxy.
• You can't use RDS Proxy with custom DNS.
• RDS Proxy is available for the MySQL and PostgreSQL engine families.
• Each proxy can be associated with a single target DB instance or cluster. However, you can associate
multiple proxies with the same DB instance or cluster.

The following RDS Proxy prerequisites and limitations apply to MySQL:

• For RDS for MySQL, RDS Proxy supports MySQL 5.6 and 5.7. For Aurora MySQL, RDS Proxy supports
version 1 (compatible with MySQL 5.6) and version 2 (compatible with MySQL 5.7).

178
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

• Currently, all proxies listen on port 3306 for MySQL. The proxies still connect to your database using
the port that you specified in the database settings.
• You can't use RDS Proxy with RDS for MySQL 8.0.
• You can't use RDS Proxy with self-managed MySQL databases in EC2 instances.
• Proxies don't support MySQL compressed mode. For example, they don't support the compression
used by the --compress or -C options of the mysql command.
• Some SQL statements and functions can change the connection state without causing pinning. For the
most current pinning behavior, see Avoiding pinning (p. 196).

The following RDS Proxy prerequisites and limitations apply to PostgreSQL:

• For RDS PostgreSQL, RDS Proxy supports version 10.10 and higher minor versions, and version 11.5
and higher minor versions. For Aurora PostgreSQL, RDS Proxy supports version 10.11 and higher minor
versions, and 11.6 and higher minor versions.
• Currently, all proxies listen on port 5432 for PostgreSQL.
• Query cancellation isn't supported for PostgreSQL.
• The results of the PostgreSQL function lastval aren't always accurate. As a work-around, use the
INSERT statement with the RETURNING clause.

Identifying DB instances, clusters, and applications to use with RDS Proxy

You can determine which of your DB instances, clusters, and applications might benefit the most from
using RDS Proxy. To do so, consider these factors:

• RDS Proxy is highly available and deployed over multiple Availability Zones (AZs). To ensure overall
high availability for your database, deploy your Amazon RDS DB instance or Aurora cluster in a Multi-
AZ configuration.
• Any DB instance or cluster that encounters "too many connections" errors is a good candidate for
associating with a proxy. The proxy enables applications to open many client connections, while the
proxy manages a smaller number of long-lived connections to the DB instance or cluster.
• For DB instances or clusters that use smaller AWS instance classes, such as T2 or T3, using a proxy
can help avoid out-of-memory conditions. It can also help reduce the CPU overhead for establishing
connections. These conditions can occur when dealing with large numbers of connections.
• You can monitor certain Amazon CloudWatch metrics to determine whether a DB instance or cluster
is approaching certain types of limit. These limits are for the number of connections and the memory
associated with connection management. You can also monitor certain CloudWatch metrics to
determine whether a DB instance or cluster is handling many short-lived connections. Opening and
closing such connections can impose performance overhead on your database. For information about
the metrics to monitor, see Monitoring RDS Proxy using Amazon CloudWatch (p. 198).
• AWS Lambda functions can also be good candidates for using a proxy. These functions make frequent
short database connections that benefit from connection pooling offered by RDS Proxy. You can take
advantage of any IAM authentication you already have for Lambda functions, instead of managing
database credentials in your Lambda application code.
• Applications that use languages and frameworks such as PHP and Ruby on Rails are typically good
candidates for using a proxy. Such applications typically open and close large numbers of database
connections, and don't have built-in connection pooling mechanisms.
• Applications that keep a large number of connections open for long periods are typically good
candidates for using a proxy. Applications in industries such as software as a service (SaaS) or
ecommerce often minimize the latency for database requests by leaving connections open. With RDS
Proxy, an application can keep more connections open than it can when connecting directly to the DB
instance or cluster.

179
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

• You might not have adopted IAM authentication and Secrets Manager due to the complexity of
setting up such authentication for all DB instances and clusters. If so, you can leave the existing
authentication methods in place and delegate the authentication to a proxy. The proxy can enforce
the authentication policies for client connections for particular applications. You can take advantage
of any IAM authentication you already have for Lambda functions, instead of managing database
credentials in your Lambda application code.

Setting up network prerequisites

Using RDS Proxy requires you to have a set of networking resources in place. These include a virtual
private cloud (VPC), two or more subnets, an Amazon EC2 instance within the same VPC, and an internet
gateway. If you've successfully connected to any RDS DB instances or Aurora DB clusters, you already
have the required network resources.

The following Linux example shows AWS CLI commands that examine the VPCs and subnets owned by
your AWS account. In particular, you pass subnet IDs as parameters when you create a proxy using the
CLI.

aws ec2 describe-vpcs

aws ec2 describe-internet-gateways
aws ec2 describe-subnets --query '*[].[VpcId,SubnetId]' --output text | sort

The following Linux example shows AWS CLI commands to determine the subnet IDs corresponding
to a specific Aurora DB cluster or RDS DB instance. For an Aurora cluster, first you find the ID for one
of the associated DB instances. You can extract the subnet IDs used by that DB instance by examining
the nested fields within the DBSubnetGroup and Subnets attributes in the describe output for the DB
instance. You specify some or all of those subnet IDs when setting up a proxy for that database server.

$ # Optional first step, only needed if you're starting from an Aurora cluster. Find the ID
of any DB instance in the cluster.
$ aws rds describe-db-clusters --db-cluster-id my_cluster_id --query '*[].
[DBClusterMembers]|[0]|[0][*].DBInstanceIdentifier' --output text
my_instance_id
instance_id_2
instance_id_3
...

$ # From the DB instance, trace through the DBSubnetGroup and Subnets to find the subnet
IDs.
$ aws rds describe-db-instances --db-instance-id my_instance_id --query '*[].
[DBSubnetGroup]|[0]|[0]|[Subnets]|[0]|[*].SubnetIdentifier' --output text
subnet_id_1
subnet_id_2
subnet_id_3
...

As an alternative, you can first find the VPC ID for the DB instance. Then you can examine the VPC to find
its subnets. The following Linux example shows how.

$ # From the DB instance, find the VPC.

$ aws rds describe-db-instances --db-instance-id my_instance_id --query '*[].[VpcId]' --
output text
my_vpc_id

$ aws ec2 describe-subnets --filters Name=vpc-id,Values=my_vpc_id --query '*[].[SubnetId]'

--output text
subnet_id_1
subnet_id_2
subnet_id_3

180
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

subnet_id_4
subnet_id_5
subnet_id_6

Setting up database credentials in AWS Secrets Manager

For each proxy that you create, you first use the Secrets Manager service to store sets of user name and
password credentials. You create a separate Secrets Manager secret for each database user account that
the proxy connects to on the RDS DB instance or Aurora DB cluster.

In Secrets Manager, you create these secrets with values for the username and password fields. Doing
so allows the proxy to connect to the corresponding database users on whichever RDS DB instances or
Aurora DB clusters that you associate with the proxy. To do this, you can use the setting Credentials for
other database, Credentials for RDS database, or Other type of secrets. Fill in the appropriate values
for the User name and Password fields, and placeholder values for any other required fields. The proxy
ignores other fields such as Host and Port if they're present in the secret. Those details are automatically
supplied by the proxy.

You can also choose Other type of secrets. In this case, you create the secret with keys named username
and password.

Because the secrets used by your proxy aren't tied to a specific database server, you can reuse a secret
across multiple proxies if you use the same credentials across multiple database servers. For example,
you might use the same credentials across a group of development and test servers.

To connect through the proxy as a specific user, make sure that the password associated with a secret
matches the database password for that user. If there's a mismatch, you can update the associated secret
in Secrets Manager. In this case, you can still connect to other accounts where the secret credentials and
the database passwords do match.

When you create a proxy through the AWS CLI or RDS API, you specify the Amazon Resource Names
(ARNs) of the corresponding secrets for all the DB user accounts that the proxy can access. In the AWS
Management Console, you choose the secrets by their descriptive names.

For instructions about creating secrets in Secrets Manager, see the Creating a secret page in the Secrets
Manager documentation. Use one of the following techniques:

• Use Secrets Manager in the console.

• To use the CLI to create a Secrets Manager secret for use with RDS Proxy, use a command such as the
following.

aws secretsmanager create-secret

--name "secret_name"
--description "secret_description"
--region region_name
--secret-string '{"username":"db_user","password":"db_user_password"}'

For example, the following commands create Secrets Manager secrets for two database users, one
named admin and the other named app-user.

aws secretsmanager create-secret \

--name admin_secret_name --description "db admin user" \
--secret-string '{"username":"admin","password":"choose_your_own_password"}'

aws secretsmanager create-secret \

--name proxy_secret_name --description "application user" \
--secret-string '{"username":"app-user","password":"choose_your_own_password"}'

To see the secrets owned by your AWS account, use a command such as the following.

181
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

aws secretsmanager list-secrets

When you create a proxy using the CLI, you pass the Amazon resource names (ARNs) of one or more
secrets to the --auth parameter. The following Linux example shows how to prepare a report with only
the name and ARN of each secret owned by your AWS account. This example uses the --output table
parameter that is available in AWS CLI version 2. If you are using AWS CLI version 1, use --output text
instead.

aws secretsmanager list-secrets --query '*[].[Name,ARN]' --output table

To verify that you stored the correct credentials and in the right format in a secret, use a command such
as the following. Substitute the short name or the ARN of the secret for your_secret_name.

aws secretsmanager get-secret-value --secret-id your_secret_name

The output should include a line displaying a JSON-encoded value like the following.

"SecretString": "{\"username\":\"your_username\",\"password\":\"your_password\"}",

Setting up AWS Identity and Access Management (IAM) policies

After you create the secrets in Secrets Manager, you create an IAM policy that can access those secrets.
For general information about using IAM with RDS and Aurora, see Identity and access management in
Amazon RDS (p. 1634).
Tip
The following procedure applies if you use the IAM console. If you use the AWS Management
Console for RDS, RDS can create the IAM policy for you automatically. In that case, you can skip
the following procedure.

To create an IAM policy that accesses your Secrets Manager secrets for use with your proxy

1. Sign in to the IAM console. Follow the Create role process, as described in Creating IAM roles.
Include the Add Role to Database step.
2. For the new role, perform the Add inline policy step. Use the same general procedures as in Editing
IAM policies. Paste the following JSON into the JSON text box. Substitute your own account ID.
Substitute your AWS Region for us-east-2. Substitute the Amazon Resource Names (ARNs) for
the secrets that you created. For the kms:Decrypt action, substitute the ARN of the default AWS
KMS customer master key (CMK) or your own AWS KMS CMK, depending on which one you used to
encrypt the Secrets Manager secrets.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": "secretsmanager:GetSecretValue",
"Resource": [
"arn:aws:secretsmanager:us-east-2:account_id:secret:secret_name_1",
"arn:aws:secretsmanager:us-east-2:account_id:secret:secret_name_2"
]
},
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": "kms:Decrypt",
"Resource": "arn:aws:kms:us-east-2:account_id:key/key_id",

182
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

"Condition": {
"StringEquals": {
"kms:ViaService": "secretsmanager.us-east-2.amazonaws.com"
}
}
}
]
}

3. Edit the trust policy for this IAM role. Paste the following JSON into the JSON text box.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "rds.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}

The following commands perform the same operation through the AWS CLI.

PREFIX=choose_an_identifier

aws iam create-role --role-name choose_role_name \

--assume-role-policy-document '{"Version":"2012-10-17","Statement":
[{"Effect":"Allow","Principal":{"Service":
["rds.amazonaws.com"]},"Action":"sts:AssumeRole"}]}'

aws iam put-role-policy --role-name same_role_name_as_previous \

--policy-name $PREFIX-secret-reader-policy --policy-document """
same_json_as_in_previous_example
"""

aws kms create-key --description "$PREFIX-test-key" --policy """

{
"Id":"$PREFIX-kms-policy",
"Version":"2012-10-17",
"Statement":
[
{
"Sid":"Enable IAM User Permissions",
"Effect":"Allow",
"Principal":{"AWS":"arn:aws:iam::account_id:root"},
"Action":"kms:*","Resource":"*"
},
{
"Sid":"Allow access for Key Administrators",
"Effect":"Allow",
"Principal":
{
"AWS":
["$USER_ARN","arn:aws:iam::account_id:role/Admin"]
},
"Action":
[
"kms:Create*",
"kms:Describe*",

183
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

"kms:Enable*",
"kms:List*",
"kms:Put*",
"kms:Update*",
"kms:Revoke*",
"kms:Disable*",
"kms:Get*",
"kms:Delete*",
"kms:TagResource",
"kms:UntagResource",
"kms:ScheduleKeyDeletion",
"kms:CancelKeyDeletion"
],
"Resource":"*"
},
{
"Sid":"Allow use of the key",
"Effect":"Allow",
"Principal":{"AWS":"$ROLE_ARN"},
"Action":["kms:Decrypt","kms:DescribeKey"],
"Resource":"*"
}
]
}
"""

Creating an RDS Proxy

To manage connections for a specified set of DB instances, you can create a proxy. You can associate a
proxy with an RDS for MySQL DB instance, PostgreSQL DB instance, or an Aurora DB cluster.

AWS Management Console

To create a proxy

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 Proxies.
3. Choose Create proxy.
4. Choose all the settings for your proxy.

For Proxy configuration, provide information for the following:

• Proxy identifier. Specify a name of your choosing, unique within your AWS account ID and current
AWS Region.
• Engine compatibility. Choose either MySQL or POSTGRESQL.
• Require Transport Layer Security. Choose this setting if you want the proxy to enforce TLS/SSL
for all client connections. When you use an encrypted or unencrypted connection to a proxy, the
proxy uses the same encryption setting when it makes a connection to the underlying database.
• Idle client connection timeout. Choose a time period that a client connection can be idle before
the proxy can close it. The default is 1,800 seconds (30 minutes). A client connection is considered
idle when the application doesn't submit a new request within the specified time after the
previous request completed. The underlying database connection stays open and is returned to
the connection pool. Thus, it's available to be reused for new client connections.

Consider lowering the idle client connection timeout if you want the proxy to proactively remove
stale connections. If your workload is spiking, consider raising the idle client connection timeout to
save the cost of establishing connections.

184
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

For Target group configuration, provide information for the following:

• Database. Choose one RDS DB instance or Aurora DB cluster to access through this proxy. The list
only includes DB instances and clusters with compatible database engines, engine versions, and
other settings. If the list is empty, create a new DB instance or cluster that's compatible with RDS
Proxy. To do so, follow the procedure in Creating an Amazon RDS DB instance (p. 147) . Then try
creating the proxy again.
• Connection pool maximum connections. Specify a value from 1 through 100. This setting
represents the percentage of the max_connections value that RDS Proxy can use for its
connections. If you only intend to use one proxy with this DB instance or cluster, you can set this
value to 100. For details about how RDS Proxy uses this setting, see Controlling connection limits
and timeouts (p. 195).
• Session pinning filters. (Optional) This is an advanced setting, for troubleshooting performance
issues with particular applications. Currently, the only choice is EXCLUDE_VARIABLE_SETS.
Choose a filter only if both of following are true: Your application isn't reusing connections
due to certain kinds of SQL statements, and you can verify that reusing connections with those
SQL statements doesn't affect application correctness. For more information, see Avoiding
pinning (p. 196).
• Connection borrow timeout. In some cases, you might expect the proxy to sometimes use all
available database connections. In such cases, you can specify how long the proxy waits for
a database connection to become available before returning a timeout error. You can specify
a period up to a maximum of five minutes. This setting only applies when the proxy has the
maximum number of connections open and all connections are already in use.

For Connectivity, provide information for the following:

• Secrets Manager ARNs. Choose at least one Secrets Manager secret that contains DB user
credentials for the RDS DB instance or Aurora DB cluster that you intend to access with this proxy.
• IAM role. Choose an IAM role that has permission to access the Secrets Manager secrets that you
chose earlier. You can also choose for the AWS Management Console to create a new IAM role for
you and use that.
• IAM Authentication. Choose whether to require or disallow IAM authentication for connections to
your proxy. The choice of IAM authentication or native database authentication applies to all DB
users that access this proxy.
• Subnets. This field is prepopulated with all the subnets associated with your VPC. You can remove
any subnets that you don't need for this proxy. You must leave at least two subnets.

Provide additional connectivity configuration:

• VPC security group. Choose an existing VPC security group. You can also choose for the AWS
Management Console to create a new security group for you and use that.
Note
This security group must allow access to the database the proxy connects to. The same
security group is used for ingress from your applications to the proxy, and for egress from
the proxy to the database. For example, suppose that you use the same security group for
your database and your proxy. In this case, make sure that you specify that resources in
that security group can communicate with other resources in the same security group.

(Optional) Provide advanced configuration:

• Enable enhanced logging. You can enable this setting to troubleshoot proxy compatibility or
performance issues.

185
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

When this setting is enabled, RDS Proxy includes detailed information about SQL statements in its
logs. This information helps you to debug issues involving SQL behavior or the performance and
scalability of the proxy connections. The debug information includes the text of SQL statements
that you submit through the proxy. Thus, only enable this setting when needed for debugging,
and only when you have security measures in place to safeguard any sensitive information that
appears in the logs.

To minimize overhead associated with your proxy, RDS Proxy automatically turns this setting off
24 hours after you enable it. Enable it temporarily to troubleshoot a specific issue.
5. Choose Create Proxy.

AWS CLI

To create a proxy, use the AWS CLI command create-db-proxy. The --engine-family value is case-
sensitive.

Example

For Linux, macOS, or Unix:

aws rds create-db-proxy \

--db-proxy-name proxy_name \
--engine-family { MYSQL | POSTGRESQL } \
--auth ProxyAuthenticationConfig_JSON_string \
--role-arn iam_role \
--vpc-subnet-ids space_separated_list \
[--vpc-security-group-ids space_separated_list] \
[--require-tls | --no-require-tls] \
[--idle-client-timeout value] \
[--debug-logging | --no-debug-logging] \
[--tags comma_separated_list]

For Windows:

aws rds create-db-proxy ^

--db-proxy-name proxy_name ^
--engine-family { MYSQL | POSTGRESQL } ^
--auth ProxyAuthenticationConfig_JSON_string ^
--role-arn iam_role ^
--vpc-subnet-ids space_separated_list ^
[--vpc-security-group-ids space_separated_list] ^
[--require-tls | --no-require-tls] ^
[--idle-client-timeout value] ^
[--debug-logging | --no-debug-logging] ^
[--tags comma_separated_list]

Tip
If you don't already know the subnet IDs to use for the --vpc-subnet-ids parameter, see
Setting up network prerequisites (p. 180) for examples of how to find the subnet IDs that you
can use.

To create the required information and associations for the proxy, you also use the register-db-proxy-
targets command. Specify the target group name default. RDS Proxy automatically creates a target
group with this name when you create each proxy.

aws rds register-db-proxy-targets

--db-proxy-name value

186
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

[--target-group-name target_group_name]
[--db-instance-identifiers space_separated_list] # rds db instances, or
[--db-cluster-identifiers cluster_id] # rds db cluster (all instances), or
[--db-cluster-endpoint endpoint_name] # rds db cluster endpoint (all
instances)

RDS API

To create an RDS proxy, call the Amazon RDS API operation CreateDBProxy. You pass a parameter with
the AuthConfig data structure.

RDS Proxy automatically creates a target group named default when you create each proxy. You
associate an RDS DB instance or Aurora DB cluster with the target group by calling the function
RegisterDBProxyTargets.

Viewing an RDS Proxy

After you create one or more RDS proxies, you can view them all to examine their configuration details
and choose which ones to modify, delete, and so on.

Any database applications that use the proxy require the proxy endpoint to use in the connection string.

AWS Management Console

To view your proxy

1. Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.
2. In the upper-right corner of the AWS Management Console, choose the AWS Region in which you
created the RDS Proxy.
3. In the navigation pane, choose Proxies.
4. Choose the name of an RDS proxy to display its details.
5. On the details page, the Target groups section shows how the proxy is associated with a specific
RDS DB instance or Aurora DB cluster. You can follow the link to the default target group page to
see more details about the association between the proxy and the database. This page is where you
see settings that you specified when creating the proxy, such as maximum connection percentage,
connection borrow timeout, engine compatibility, and session pinning filters.

CLI

To view your proxy using the CLI, use the describe-db-proxies command. By default, it displays all proxies
owned by your AWS account. To see details for a single proxy, specify its name with the --db-proxy-
name parameter.

aws rds describe-db-proxies [--db-proxy-name proxy_name]

To view the other information associated with the proxy, use the following commands.

aws rds describe-db-proxy-target-groups --db-proxy-name proxy_name

aws rds describe-db-proxy-targets --db-proxy-name proxy_name

Use the following sequence of commands to see more detail about the things that are associated with
the proxy:

1. To get a list of proxies, run describe-db-proxies.

187
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

2. To show connection parameters such as the maximum percentage of connections that the proxy can
use, run describe-db-proxy-target-groups --db-proxy-name and use the name of the proxy as the
parameter value.
3. To see the details of the RDS DB instance or Aurora DB cluster associated with the returned target
group, run describe-db-proxy-targets.

RDS API

To view your proxies using the RDS API, use the DescribeDBProxies operation. It returns values of the
DBProxy data type.

To see details of the connection settings for the proxy, use the proxy identifiers from this return value
with the DescribeDBProxyTargetGroups operation. It returns values of the DBProxyTargetGroup data
type.

To see the RDS instance or Aurora DB cluster associated with the proxy, use the DescribeDBProxyTargets
operation. It returns values of the DBProxyTarget data type.

Connecting to a database through RDS Proxy

You connect to an RDS DB instance or Aurora DB cluster through a proxy in generally the same way as
you connect directly to the database. The main difference is that you specify the proxy endpoint instead
of the instance or cluster endpoint. For an Aurora DB cluster, by default all proxy connections have
read/write capability and use the writer instance. If you normally use the reader endpoint for read-only
connections, you can create an additional read-only endpoint for the proxy and use that endpoint the
same way. For more information, see Overview of proxy endpoints (p. 203).

Topics
• Connecting to a proxy using native authentication (p. 188)
• Connecting to a proxy using IAM authentication (p. 189)
• Considerations for connecting to a proxy with PostgreSQL (p. 189)

Connecting to a proxy using native authentication

Use the following basic steps to connect to a proxy using native authentication:

1. Find the proxy endpoint. In the AWS Management Console, you can find the endpoint on the details
page for the corresponding proxy. With the AWS CLI, you can use the describe-db-proxies command.
The following example shows how.

# Add --output text to get output as a simple tab-separated list.

$ aws rds describe-db-proxies --query '*[*].{DBProxyName:DBProxyName,Endpoint:Endpoint}'
[
[
{
"Endpoint": "the-proxy.proxy-demo.us-east-1.rds.amazonaws.com",
"DBProxyName": "the-proxy"
},
{
"Endpoint": "the-proxy-other-secret.proxy-demo.us-east-1.rds.amazonaws.com",
"DBProxyName": "the-proxy-other-secret"
},
{
"Endpoint": "the-proxy-rds-secret.proxy-demo.us-east-1.rds.amazonaws.com",
"DBProxyName": "the-proxy-rds-secret"
},
{

188
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

"Endpoint": "the-proxy-t3.proxy-demo.us-east-1.rds.amazonaws.com",
"DBProxyName": "the-proxy-t3"
}
]
]

2. Specify that endpoint as the host parameter in the connection string for your client application. For
example, specify the proxy endpoint as the value for the mysql -h option or psql -h option.
3. Supply the same database user name and password as you usually do.

Connecting to a proxy using IAM authentication

When you use IAM authentication with RDS Proxy, set up your database users to authenticate with
regular user names and passwords. The IAM authentication applies to RDS Proxy retrieving the user
name and password credentials from Secrets Manager. The connection from RDS Proxy to the underlying
database doesn't go through IAM.

To connect to RDS Proxy using IAM authentication, follow the same general procedure as for connecting
to an RDS DB instance or Aurora cluster using IAM authentication. For general information about using
IAM with RDS and Aurora, see Security in Amazon RDS (p. 1617).

The major differences in IAM usage for RDS Proxy include the following:

• You don't configure each individual database user with an authorization plugin. The database users
still have regular user names and passwords within the database. You set up Secrets Manager secrets
containing these user names and passwords, and authorize RDS Proxy to retrieve the credentials from
Secrets Manager.
Important
The IAM authentication applies to the connection between your client program and the proxy.
The proxy then authenticates to the database using the user name and password credentials
retrieved from Secrets Manager. When you use IAM for the connection to a proxy, make sure
that the underlying RDS DB instance or Aurora DB cluster doesn't have IAM enabled.
• Instead of the instance, cluster, or reader endpoint, you specify the proxy endpoint. For details about
the proxy endpoint, see Connecting to your DB instance using IAM authentication (p. 1658).
• In the direct DB IAM auth case, you selectively pick database users and configure them to be identified
with a special auth plugin. You can then connect to those users using IAM auth.

In the proxy use case, you need to provide the proxy with Secrets that contain some user's username
and password (native auth). You then connect to the proxy using IAM auth (by generating an auth
token with the proxy endpoint, not the database endpoint) and using a username which matches one
of the usernames for the secrets you previously provided.
• Make sure that you use Transport Layer Security (TLS) / Secure Sockets Layer (SSL) when connecting to
a proxy using IAM authentication.

You can grant a specific user access to the proxy by modifying the IAM policy. An example follows.

"Resource": "arn:aws:rds-db:us-east-2:1234567890:dbuser:prx-ABCDEFGHIJKL01234/db_user"

Considerations for connecting to a proxy with PostgreSQL

For PostgreSQL, when a client starts a connection to a PostgreSQL database, it sends a startup message
that includes pairs of parameter name and value strings. For details, see the StartupMessage in
PostgreSQL message formats in the PostgreSQL documentation.

When connecting through an RDS proxy, the startup message can include the following currently
recognized parameters:

189
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

• user
• database
• replication

The startup message can also include the following additional runtime parameters:

• application_name
• client_encoding
• DateStyle
• TimeZone
• extra_float_digits

For more information about PostgreSQL messaging, see the Frontend/Backend protocol in the
PostgreSQL documentation.

For PostgreSQL, if you use JDBC we recommend the following to avoid pinning:

• Set the JDBC connection parameter assumeMinServerVersion to at least 9.0 to avoid pinning.
Doing this prevents the JDBC driver from performing an extra round trip during connection startup
when it runs SET extra_float_digits = 3.
• Set the JDBC connection parameter ApplicationName to any/your-application-name to
avoid pinning. Doing this prevents the JDBC driver from performing an extra round trip during
connection startup when it runs SET application_name = "PostgreSQL JDBC Driver".
Note the JDBC parameter is ApplicationName but the PostgreSQL StartupMessage parameter is
application_name.
• Set the JDBC connection parameter preferQueryMode to extendedForPrepared to avoid pinning.
The extendedForPrepared ensures that the extended mode is used only for prepared statements.

The default for the preferQueryMode parameter is extended, which uses the extended mode for
all queries. The extended mode uses a series of Prepare, Bind, Execute, and Sync requests and
corresponding responses. This type of series causes connection pinning in an RDS proxy.

For more information, see Avoiding pinning (p. 196). For more information about connecting using
JDBC, see Connecting to the database in the PostgreSQL documentation.

Managing an RDS Proxy

Following, you can find an explanation of how to manage RDS proxy operation and configuration. These
procedures help your application make the most efficient use of database connections and achieve
maximum connection reuse. The more that you can take advantage of connection reuse, the more CPU
and memory overhead that you can save. This in turn reduces latency for your application and enables
the database to devote more of its resources to processing application requests.

Topics
• Modifying an RDS Proxy (p. 191)
• Adding a new database user (p. 195)
• Changing the password for a database user (p. 195)
• Controlling connection limits and timeouts (p. 195)
• Managing and monitoring connection pooling (p. 195)
• Avoiding pinning (p. 196)
• Deleting an RDS Proxy (p. 198)

190
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

Modifying an RDS Proxy

You can change certain settings associated with a proxy after you create the proxy. You do so by
modifying the proxy itself, its associated target group, or both. Each proxy has an associated target
group.

AWS Management Console

To modify the settings for a proxy

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 Proxies.
3. In the list of proxies, choose the proxy whose settings you want to modify or go to its details page.
4. For Actions, choose Modify.
5. Enter or choose the properties to modify. You can do the following:

• Rename the proxy by entering a new identifier.

• Turn the requirement for Transport layer Security (TLS) on or off.
• Enter a time period for the idle connection timeout.
• Add or remove Secrets Manager secrets. These secrets correspond to database user names and
passwords.
• Change the IAM role used to retrieve the secrets from Secrets Manager.
• Require or disallow IAM authentication for connections to the proxy.
• Add or remove VPC subnets for the proxy to use.
• Add or remove VPC security groups for the proxy to use.
• Enable or disable enhanced logging.
6. Choose Modify.

If you didn't find the settings listed that you want to change, use the following procedure to update the
target group for the proxy. The target group associated with a proxy controls the settings related to the
physical database connections. Each proxy has one associated target group named default, which is
created automatically along with the proxy.

You can only modify the target group from the proxy details page, not from the list on the Proxies page.

To modify the settings for a proxy target group

1. On the Proxies page, go to the details page for a proxy.

2. For Target groups, choose the default link. Currently, all proxies have a single target group named
default.
3. On the details page for the default target group, choose Modify.
4. Choose new settings for the properties that you can modify:

• Choose a different RDS DB instance or Aurora cluster.

• Adjust what percentage of the maximum available connections the proxy can use.
• Choose a session pinning filter. Doing this can help reduce performance issues due to insufficient
transaction-level reuse for connections. Using this setting requires understanding of application
behavior and the circumstances under which RDS Proxy pins a session to a database connection.
• Adjust the connection borrow timeout interval. This setting applies when the maximum number of
connections is already being used for the proxy. The setting determines how long the proxy waits
for a connection to become available before returning a timeout error.

191
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

You can't change certain properties, such as the target group identifier and the database engine.
5. Choose Modify target group.

AWS CLI

To modify a proxy using the AWS CLI, use the commands modify-db-proxy, modify-db-proxy-target-
group, deregister-db-proxy-targets, and register-db-proxy-targets.

With the modify-db-proxy command, you can change properties such as the following:

• The set of Secrets Manager secrets used by the proxy.

• Whether TLS is required.
• The idle client timeout.
• Whether to log additional information from SQL statements for debugging.
• The IAM role used to retrieve Secrets Manager secrets.
• The security groups used by the proxy.

The following example shows how to rename an existing proxy.

aws rds modify-db-proxy --db-proxy-name the-proxy --new-db-proxy-name the_new_name

To modify connection-related settings or rename the target group, use the modify-db-proxy-
target-group command. Currently, all proxies have a single target group named default. When
working with this target group, you specify the name of the proxy and default for the name of the
target group.

The following example shows how to first check the MaxIdleConnectionsPercent setting for a proxy
and then change it, using the target group.

aws rds describe-db-proxy-target-groups --db-proxy-name the-proxy

{
"TargetGroups": [
{
"Status": "available",
"UpdatedDate": "2019-11-30T16:49:30.342Z",
"ConnectionPoolConfig": {
"MaxIdleConnectionsPercent": 50,
"ConnectionBorrowTimeout": 120,
"MaxConnectionsPercent": 100,
"SessionPinningFilters": []
},
"TargetGroupName": "default",
"CreatedDate": "2019-11-30T16:49:27.940Z",
"DBProxyName": "the-proxy",
"IsDefault": true
}
]
}

aws rds modify-db-proxy-target-group --db-proxy-name the-proxy --target-group-name default

--connection-pool-config '
{ "MaxIdleConnectionsPercent": 75 }'

192
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

"DBProxyTargetGroup": {
"Status": "available",
"UpdatedDate": "2019-12-02T04:09:50.420Z",
"ConnectionPoolConfig": {
"MaxIdleConnectionsPercent": 75,
"ConnectionBorrowTimeout": 120,
"MaxConnectionsPercent": 100,
"SessionPinningFilters": []
},
"TargetGroupName": "default",
"CreatedDate": "2019-11-30T16:49:27.940Z",
"DBProxyName": "the-proxy",
"IsDefault": true
}
}

With the deregister-db-proxy-targets and register-db-proxy-targets commands, you

change which RDS DB instance or Aurora DB cluster the proxy is associated with through its target group.
Currently, each proxy can connect to one RDS DB instance or Aurora DB cluster. The target group tracks
the connection details for all the RDS DB instances in a Multi-AZ configuration, or all the DB instances in
an Aurora cluster.

The following example starts with a proxy that is associated with an Aurora MySQL cluster named
cluster-56-2020-02-25-1399. The example shows how to change the proxy so that it can connect
to a different cluster named provisioned-cluster.

When you work with an RDS DB instance, you specify the --db-instance-identifier option. When
you work with an Aurora DB cluster, you specify the --db-cluster-identifier option instead.

The following example modifies an Aurora MySQL proxy. An Aurora PostgreSQL proxy has port 5432.

aws rds describe-db-proxy-targets --db-proxy-name the-proxy

{
"Targets": [
{
"Endpoint": "instance-9814.demo.us-east-1.rds.amazonaws.com",
"Type": "RDS_INSTANCE",
"Port": 3306,
"RdsResourceId": "instance-9814"
},
{
"Endpoint": "instance-8898.demo.us-east-1.rds.amazonaws.com",
"Type": "RDS_INSTANCE",
"Port": 3306,
"RdsResourceId": "instance-8898"
},
{
"Endpoint": "instance-1018.demo.us-east-1.rds.amazonaws.com",
"Type": "RDS_INSTANCE",
"Port": 3306,
"RdsResourceId": "instance-1018"
},
{
"Type": "TRACKED_CLUSTER",
"Port": 0,
"RdsResourceId": "cluster-56-2020-02-25-1399"
},
{
"Endpoint": "instance-4330.demo.us-east-1.rds.amazonaws.com",
"Type": "RDS_INSTANCE",
"Port": 3306,
"RdsResourceId": "instance-4330"

193
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

}
]
}

aws rds deregister-db-proxy-targets --db-proxy-name the-proxy --db-cluster-identifier

cluster-56-2020-02-25-1399

aws rds describe-db-proxy-targets --db-proxy-name the-proxy

{
"Targets": []
}

aws rds register-db-proxy-targets --db-proxy-name the-proxy --db-cluster-identifier

provisioned-cluster

{
"DBProxyTargets": [
{
"Type": "TRACKED_CLUSTER",
"Port": 0,
"RdsResourceId": "provisioned-cluster"
},
{
"Endpoint": "gkldje.demo.us-east-1.rds.amazonaws.com",
"Type": "RDS_INSTANCE",
"Port": 3306,
"RdsResourceId": "gkldje"
},
{
"Endpoint": "provisioned-1.demo.us-east-1.rds.amazonaws.com",
"Type": "RDS_INSTANCE",
"Port": 3306,
"RdsResourceId": "provisioned-1"
}
]
}

RDS API

To modify a proxy using the RDS API, you use the operations ModifyDBProxy,
ModifyDBProxyTargetGroup, DeregisterDBProxyTargets, and RegisterDBProxyTargets operations.

With ModifyDBProxy, you can change properties such as the following:

• The set of Secrets Manager secrets used by the proxy.

• Whether TLS is required.
• The idle client timeout.
• Whether to log additional information from SQL statements for debugging.
• The IAM role used to retrieve Secrets Manager secrets.
• The security groups used by the proxy.

With ModifyDBProxyTargetGroup, you can modify connection-related settings or rename the target
group. Currently, all proxies have a single target group named default. When working with this target
group, you specify the name of the proxy and default for the name of the target group.

With DeregisterDBProxyTargets and RegisterDBProxyTargets, you change which RDS DB

instance or Aurora DB cluster the proxy is associated with through its target group. Currently, each proxy
can connect to one RDS DB instance or Aurora DB cluster. The target group tracks the connection details
for all the RDS DB instances in a Multi-AZ configuration, or all the DB instances in an Aurora cluster.

194
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

Adding a new database user

In some cases, you might add a new database user to an RDS DB instance or Aurora cluster that's
associated with a proxy. If so, add or repurpose a Secrets Manager secret to store the credentials for that
user. To do this, choose one of the following options:

• Create a new Secrets Manager secret, using the procedure described in Setting up database credentials
in AWS Secrets Manager (p. 181).
• Update the IAM role to give RDS Proxy access to the new Secrets Manager secret. To do so, update the
resources section of the IAM role policy.
• If the new user takes the place of an existing one, update the credentials stored in the proxy's Secrets
Manager secret for the existing user.

Changing the password for a database user

In some cases, you might change the password for a database user in an RDS DB instance or Aurora
cluster that's associated with a proxy. If so, update the corresponding Secrets Manager secret with the
new password.

Controlling connection limits and timeouts

RDS Proxy uses the max_connections setting for your RDS DB instance or Aurora DB cluster. This
setting represents the overall upper limit on the connections that the proxy can open at any one time. In
Aurora clusters and RDS Multi-AZ configurations, the max_connections value that the proxy uses is the
one for the Aurora primary instance or the RDS writer instance.

To set this value for your RDS DB instance or Aurora DB cluster, follow the procedures in Working with
DB parameter groups (p. 234). These procedures demonstrate how to associate a parameter group with
your database and edit the max_connections value in the parameter group.

The proxy setting for maximum connections represents a percentage of the max_connections value
for the database that's associated with the proxy. If you have multiple applications all using the same
database, you can effectively divide their connection quotas by using a proxy for each application with
a specific percentage of max_connections. If you do so, ensure that the percentages add up to 100 or
less for all proxies associated with the same database.

RDS Proxy periodically disconnects idle connections and returns them to the connection pool. You can
adjust this timeout interval. Doing so helps your applications to deal with stale resources, especially if
the application mistakenly leaves a connection open while holding important database resources.

Managing and monitoring connection pooling

As described in Connection pooling (p. 175), connection pooling is a crucial RDS Proxy feature.
Following, you can learn how to make the most efficient use of connection pooling and transaction-level
connection reuse (multiplexing).

Because the connection pool is managed by RDS Proxy, you can monitor it and adjust connection limits
and timeout intervals without changing your application code.

For each proxy, you can specify an upper limit on the number of connections used by the connection
pool. You specify the limit as a percentage. This percentage applies to the maximum connections
configured in the database. The exact number varies depending on the DB instance size and
configuration settings.

For example, suppose that you configured RDS Proxy to use 75 percent of the maximum connections
for the database. For MySQL, the maximum value is defined by the max_connections configuration
parameter. In this case, the other 25 percent of maximum connections remain available to assign to
other proxies or for connections that don't go through a proxy. In some cases, the proxy might keep

195
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

less than 75 percent of the maximum connections open at a particular time. Those cases might include
situations where the database doesn't have many simultaneous connections, or some connections stay
idle for long periods.

The overall number of connections available for the connection pool changes as you update the
max_connections configuration setting that applies to an RDS DB instance or an Aurora cluster.

The proxy doesn't reserve all of these connections in advance. Thus, you can specify a relatively large
percentage, and those connections are only opened when the proxy becomes busy enough to need them.

You can choose how long to wait for a connection to become available for use by your application. This
setting is represented by the Connection borrow timeout option when you create a proxy. This setting
specifies how long to wait for a connection to become available in the connection pool before returning
a timeout error. It applies when the number of connections is at the maximum, and so no connections
are available in the connection pool. It also applies if no writer instance is available because a failover
operation is in process. Using this setting, you can set the best wait period for your application without
having to change the query timeout in your application code.

Avoiding pinning
Multiplexing is more efficient when database requests don't rely on state information from previous
requests. In that case, RDS Proxy can reuse a connection at the conclusion of each transaction. Examples
of such state information include most variables and configuration parameters that you can change
through SET or SELECT statements. SQL transactions on a client connection can multiplex between
underlying database connections by default.

Your connections to the proxy can enter a state known as pinning. When a connection is pinned, each
later transaction uses the same underlying database connection until the session ends. Other client
connections also can't reuse that database connection until the session ends. The session ends when the
client connection is dropped.

RDS Proxy automatically pins a client connection to a specific DB connection when it detects a session
state change that isn't appropriate for other sessions. Pinning reduces the effectiveness of connection
reuse. If all or almost all of your connections experience pinning, consider modifying your application
code or workload to reduce the conditions that cause the pinning.

For example, if your application changes a session variable or configuration parameter, later statements
can rely on the new variable or parameter to be in effect. Thus, when RDS Proxy processes requests to
change session variables or configuration settings, it pins that session to the DB connection. That way,
the session state remains in effect for all later transactions in the same session.

This rule doesn't apply to all parameters you can set. RDS Proxy tracks changes to the character set,
collation, time zone, autocommit, current database, SQL mode, and session_track_schema settings.
Thus RDS Proxy doesn't pin the session when you modify these. In this case, RDS Proxy only reuses the
connection for other sessions that have the same values for those settings.

Performance tuning for RDS Proxy involves trying to maximize transaction-level connection reuse
(multiplexing) by minimizing pinning. You can do so by doing the following:

• Avoid unnecessary database requests that might cause pinning.

• Set variables and configuration settings consistently across all connections. That way, later sessions are
more likely to reuse connections that have those particular settings.

However, for PostgreSQL setting a variable leads to session pinning.

• Apply a session pinning filter to the proxy. You can exempt certain kinds of operations from pinning
the session if you know that doing so doesn't affect the correct operation of your application.
• See how frequently pinning occurs by monitoring the CloudWatch metric
DatabaseConnectionsCurrentlySessionPinned. For information about this and other
CloudWatch metrics, see Monitoring RDS Proxy using Amazon CloudWatch (p. 198).

196
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

• If you use SET statements to perform identical initialization for each client connection, you can do so
while preserving transaction-level multiplexing. In this case, you move the statements that set up the
initial session state into the initialization query used by a proxy. This property is a string containing
one or more SQL statements, separated by semicolons.

For example, you can define an initialization query for a proxy that sets certain configuration
parameters. Then, RDS Proxy applies those settings whenever it sets up a new connection for that
proxy. You can remove the corresponding SET statements from your application code, so that they
don't interfere with transaction-level multiplexing.
Important
For proxies associated with MySQL databases, don't set the configuration parameter
sql_auto_is_null to true or a nonzero value in the initialization query. Doing so might
cause incorrect application behavior.

The proxy pins the session to the current connection in the following situations where multiplexing
might cause unexpected behavior:

• Any statement with a text size greater than 16 KB causes the proxy to pin the session.
• Prepared statements cause the proxy to pin the session. This rule applies whether the prepared
statement uses SQL text or the binary protocol.
• Explicit MySQL statements LOCK TABLE, LOCK TABLES, or FLUSH TABLES WITH READ LOCK cause
the proxy to pin the session.
• Setting a user variable or a system variable (with some exceptions) causes the proxy to pin the session.
If this situation reduces your connection reuse too much, you can choose for SET operations not
to cause pinning. For information about how to do so by setting the SessionPinningFilters
property, see Creating an RDS Proxy (p. 184).
• Creating a temporary table causes the proxy to pin the session. That way, the contents of the
temporary table are preserved throughout the session regardless of transaction boundaries.
• Calling the MySQL functions ROW_COUNT, FOUND_ROWS, and LAST_INSERT_ID sometimes causes
pinning.

The exact circumstances where these functions cause pinning might differ between Aurora MySQL
versions that are compatible with MySQL 5.6 and MySQL 5.7.

Calling MySQL stored procedures and stored functions doesn't cause pinning. RDS Proxy doesn't
detect any session state changes resulting from such calls. Therefore, make sure that your application
doesn't change session state inside stored routines and rely on that session state to persist across
transactions. For example, if a stored procedure creates a temporary table that is intended to persist
across transactions, that application currently isn't compatible with RDS Proxy.

For PostgreSQL, the following interactions cause pinning:

• Using SET commands

• Using the extended query protocol such as by using JDBC default settings
• Creating temporary sequences, tables, or views
• Declaring cursors
• Discarding the session state
• Listening on a notification channel
• Loading a library module such as auto_explain
• Manipulating sequences using functions such as nextval and setval
• Interacting with locks using functions such as pg_advisory_lock and pg_try_advisory_lock
• Using prepared statements, setting parameters, or resetting a parameter to its default

197
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

If you have expert knowledge about your application behavior, you can skip the pinning behavior for
certain application statements. To do so, choose the Session pinning filters option when creating the
proxy. Currently, you can opt out of session pinning for setting session variables and configuration
settings.

For metrics about how often pinning occurs for a proxy, see Monitoring RDS Proxy using Amazon
CloudWatch (p. 198).

Deleting an RDS Proxy

You can delete a proxy if you no longer need it. You might delete a proxy because the application that
was using it is no longer relevant. Or you might delete a proxy if you take the DB instance or cluster
associated with it out of service.

AWS Management Console

To delete a proxy

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 Proxies.
3. Choose the proxy to delete from the list.
4. Choose Delete Proxy.

AWS CLI

To delete a DB proxy, use the AWS CLI command delete-db-proxy. To remove related associations, also
use the deregister-db-proxy-targets command.

aws rds delete-db-proxy --name proxy_name

aws rds deregister-db-proxy-targets

--db-proxy-name proxy_name
[--target-group-name target_group_name]
[--target-ids comma_separated_list] # or
[--db-instance-identifiers instance_id] # or
[--db-cluster-identifiers cluster_id]

RDS API

To delete a DB proxy, call the Amazon RDS API function DeleteDBProxy. To delete related items and
associations, you also call the functions DeleteDBProxyTargetGroup and DeregisterDBProxyTargets.

Monitoring RDS Proxy using Amazon CloudWatch

You can monitor RDS Proxy by using Amazon CloudWatch. CloudWatch collects and processes raw data
from the proxies into readable, near-real-time metrics. To find these metrics in the CloudWatch console,
choose Metrics, then choose RDS, and choose Per-Proxy Metrics. For more information, see Using
Amazon CloudWatch metrics in the Amazon CloudWatch User Guide.
Note
RDS publishes these metrics for each underlying Amazon EC2 instance associated with a proxy.
A single proxy might be served by more than one EC2 instance. Use CloudWatch statistics to
aggregate the values for a proxy across all the associated instances.

198
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

Some of these metrics might not be visible until after the first successful connection by a proxy.

In the RDS Proxy logs, each entry is prefixed with the name of the associated proxy endpoint. This name
can be the name you specified for a user-defined endpoint, or the special name default for read/write
requests using the default endpoint of a proxy.

All RDS Proxy metrics are in the group proxy.

Each proxy endpoint has its own CloudWatch metrics. You can monitor the usage of each proxy
endpoint independently. For more information about proxy endpoints, see Endpoints for Amazon RDS
Proxy (p. 203).

You can aggregate the values for each metric using one of the following dimension sets. For example,
by using the ProxyName dimension set, you can analyze all the traffic for a particular proxy. By using
the other dimension sets, you can split the metrics in different ways. You can split the metrics based on
the different endpoints or target databases of each proxy, or the read/write and read-only traffic to each
database.

• Dimension set 1: ProxyName

• Dimension set 2: ProxyName, EndpointName
• Dimension set 3: ProxyName, TargetGroup, Target
• Dimension set 4: ProxyName, TargetGroup, TargetRole

Metric Description Valid period CloudWatch dimension

set

The percentage of time

AvailabilityPercentage 1 minute Dimension set
for which the target 4 (p. 199)
group was available
in the role indicated
by the dimension. This
metric is reported
every minute. The most
useful statistic for this
metric is Average.

ClientConnections The current number 1 minute Dimension set

of client connections. 1 (p. 199), Dimension
This metric is reported set 2 (p. 199)
every minute. The most
useful statistic for this
metric is Sum.

The number of client

ClientConnectionsClosed 1 minute and above Dimension set
connections closed. The 1 (p. 199), Dimension
most useful statistic for set 2 (p. 199)
this metric is Sum.

The current number

ClientConnectionsNoTLS 1 minute and above Dimension set
of client connections 1 (p. 199), Dimension
without Transport set 2 (p. 199)
Layer Security (TLS).
This metric is reported
every minute. The most
useful statistic for this
metric is Sum.

199
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

Metric Description Valid period CloudWatch dimension

set

The number of client

ClientConnectionsReceived 1 minute and above Dimension set
connection requests 1 (p. 199), Dimension
received. The most set 2 (p. 199)
useful statistic for this
metric is Sum.

The number of
ClientConnectionsSetupFailedAuth 1 minute and above Dimension set
client connection 1 (p. 199), Dimension
attempts that failed set 2 (p. 199)
due to misconfigured
authentication or
TLS. The most useful
statistic for this metric
is Sum.

The number of
ClientConnectionsSetupSucceeded 1 minute and above Dimension set
client connections 1 (p. 199), Dimension
successfully established set 2 (p. 199)
with any authentication
mechanism with or
without TLS. The most
useful statistic for this
metric is Sum.

ClientConnectionsTLSThe current number 1 minute and above Dimension set

of client connections 1 (p. 199), Dimension
with TLS. This metric set 2 (p. 199)
is reported every
minute. The most
useful statistic for this
metric is Sum.

The number of requests

DatabaseConnectionRequests 1 minute and above Dimension set
to create a database 1 (p. 199), Dimension
connection. The most set 3 (p. 199),
useful statistic for this Dimension set
metric is Sum. 4 (p. 199)

The number of requests

DatabaseConnectionRequestsWithTLS 1 minute and above Dimension set
to create a database 1 (p. 199), Dimension
connection with TLS. set 3 (p. 199),
The most useful Dimension set
statistic for this metric 4 (p. 199)
is Sum.

DatabaseConnections The current number of 1 minute Dimension set

database connections. 1 (p. 199), Dimension
This metric is reported set 3 (p. 199),
every minute. The most Dimension set
useful statistic for this 4 (p. 199)
metric is Sum.

200
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

Metric Description Valid period CloudWatch dimension

set

The time in
DatabaseConnectionsBorrowLatency 1 minute and above Dimension set
microseconds that it 1 (p. 199), Dimension
takes for the proxy set 2 (p. 199)
being monitored
to get a database
connection. The most
useful statistic for this
metric is Average.

The current number of

DatabaseConnectionsCurrentlyBorrowed 1 minute Dimension set
database connections 1 (p. 199), Dimension
in the borrow state. set 3 (p. 199),
This metric is reported Dimension set
every minute. The most 4 (p. 199)
useful statistic for this
metric is Sum.

The current number of

DatabaseConnectionsCurrentlyInTransaction 1 minute Dimension set
database connections 1 (p. 199), Dimension
in a transaction. This set 3 (p. 199),
metric is reported Dimension set
every minute. The most 4 (p. 199)
useful statistic for this
metric is Sum.

The current number of

DatabaseConnectionsCurrentlySessionPinned 1 minute Dimension set
database connections 1 (p. 199), Dimension
currently pinned set 3 (p. 199),
because of operations Dimension set
in client requests that 4 (p. 199)
change session state.
This metric is reported
every minute. The most
useful statistic for this
metric is Sum.

The number of
DatabaseConnectionsSetupFailed 1 minute and above Dimension set
database connection 1 (p. 199), Dimension
requests that failed. set 3 (p. 199),
The most useful Dimension set
statistic for this metric 4 (p. 199)
is Sum.

The number of
DatabaseConnectionsSetupSucceeded 1 minute and above Dimension set
database connections 1 (p. 199), Dimension
successfully established set 3 (p. 199),
with or without TLS. Dimension set
The most useful 4 (p. 199)
statistic for this metric
is Sum.

201
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

Metric Description Valid period CloudWatch dimension

set

The current number of

DatabaseConnectionsWithTLS 1 minute Dimension set
database connections 1 (p. 199), Dimension
with TLS. This metric set 3 (p. 199),
is reported every Dimension set
minute. The most 4 (p. 199)
useful statistic for this
metric is Sum.

The maximum
MaxDatabaseConnectionsAllowed 1 minute Dimension set
number of database 1 (p. 199), Dimension
connections allowed. set 3 (p. 199),
This metric is reported Dimension set
every minute. The most 4 (p. 199)
useful statistic for this
metric is Sum.

The time in
QueryDatabaseResponseLatency 1 minute and above Dimension set
microseconds that 1 (p. 199), Dimension
the database took set 2 (p. 199),
to respond to the Dimension set
query. The most useful 3 (p. 199), Dimension
statistic for this metric set 4 (p. 199)
is Average.

QueryRequests The number of queries 1 minute and above Dimension set

received. A query 1 (p. 199), Dimension
including multiple set 2 (p. 199)
statements is counted
as one query. The most
useful statistic for this
metric is Sum.

QueryRequestsNoTLS The number of queries 1 minute and above Dimension set

received from non-TLS 1 (p. 199), Dimension
connections. A query set 2 (p. 199)
including multiple
statements is counted
as one query. The most
useful statistic for this
metric is Sum.

QueryRequestsTLS The number of queries 1 minute and above Dimension set

received from TLS 1 (p. 199), Dimension
connections. A query set 2 (p. 199)
including multiple
statements is counted
as one query. The most
useful statistic for this
metric is Sum.

202
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

Metric Description Valid period CloudWatch dimension

set

QueryResponseLatencyThe time in 1 minute and above Dimension set

microseconds between 1 (p. 199), Dimension
getting a query set 2 (p. 199)
request and the proxy
responding to it. The
most useful statistic for
this metric is Average.

Endpoints for Amazon RDS Proxy

Following, you can learn about endpoints for RDS Proxy and how to use them. By using endpoints, you
can take advantage of the following capabilities:

• You can use multiple endpoints with a proxy to monitor and troubleshoot connections from different
applications independently.
• You can use reader endpoints with Aurora DB clusters to improve read scalability and high availability
for your query-intensive applications.
• You can use a cross-VPC endpoint to allow access to databases in one VPC from resources such as
Amazon EC2 instances in a different VPC.

Topics
• Overview of proxy endpoints (p. 203)
• Reader endpoints (p. 204)
• Accessing Aurora and RDS databases across VPCs (p. 204)
• Creating a proxy endpoint (p. 205)
• Viewing proxy endpoints (p. 207)
• Modifying a proxy endpoint (p. 207)
• Deleting a proxy endpoint (p. 208)
• Limits for proxy endpoints (p. 209)

Overview of proxy endpoints

Working with RDS Proxy endpoints involves the same kinds of procedures as with Aurora DB cluster
and reader endpoints and RDS instance endpoints. If you aren't familiar with RDS endpoints, find more
information in Connecting to a DB instance running the MySQL database engine and Connecting to a DB
instance running the PostgreSQL database engine.

By default, the endpoint that you connect to when you use RDS Proxy with an Aurora cluster has read/
write capability. As a consequence, this endpoint sends all requests to the writer instance of the cluster,
and all of those connections count against the max_connections value for the writer instance. If
your proxy is associated with an Aurora DB cluster, you can create additional read/write or read-only
endpoints for that proxy.

You can use a read-only endpoint with your proxy for read-only queries, the same way that you use the
reader endpoint for an Aurora provisioned cluster. Doing so helps you to take advantage of the read
scalability of an Aurora cluster with one or more reader DB instances. You can run more simultaneous
queries and make more simultaneous connections by using a read-only endpoint and adding more reader
DB instances to your Aurora cluster as needed.

203
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

For a proxy endpoint that you create, you can also associate the endpoint with a different virtual private
cloud (VPC) than the proxy itself uses. By doing so, you can connect to the proxy from a different VPC,
for example a VPC used by a different application within your organization. Both VPCs must be owned by
the same AWS account.

For information about limits associated with proxy endpoints, see Limits for proxy endpoints (p. 209).

In the RDS Proxy logs, each entry is prefixed with the name of the associated proxy endpoint. This name
can be the name you specified for a user-defined endpoint, or the special name default for read/write
requests using the default endpoint of a proxy.

Each proxy endpoint has its own set of CloudWatch metrics. You can monitor the metrics for all
endpoints of a proxy. You can also monitor metrics for a specific endpoint, or for all the read/write
or read-only endpoints of a proxy. For more information, see Monitoring RDS Proxy using Amazon
CloudWatch (p. 198).

A proxy endpoint uses the same authentication mechanism as its associated proxy. RDS Proxy
automatically sets up permissions and authorizations for the user-defined endpoint, consistent with the
properties of the associated proxy.

Reader endpoints
With RDS Proxy, you can create and use reader endpoints. However, these endpoints only work for
proxies associated with Aurora DB clusters. You might see references to reader endpoints in the AWS
Management Console. If you use the RDS CLI or API, you might see the TargetRole attribute with a
value of READ_ONLY. You can take advantage of these features by changing the target of a proxy from
an RDS DB instance to an Aurora DB cluster. To learn about reader endpoints, see Managing connections
with Amazon RDS Proxy in the Aurora User Guide.

Accessing Aurora and RDS databases across VPCs

By default, the components of your RDS and Aurora technology stack are all in the same Amazon VPC.
For example, suppose that an application running on an Amazon EC2 instance connects to an Amazon
RDS DB instance or an Aurora DB cluster. In this case, the application server and database must both be
within the same VPC.

With RDS Proxy, you can set up access to an Aurora cluster or RDS instance in one VPC from resources
such as EC2 instances in another VPC. For example, your organization might have multiple applications
that access the same database resources. Each application might be in its own VPC. To use cross-VPC
capability with RDS Proxy, all the VPCs must be owned by the same AWS account.

To enable cross-VPC access, you create a new endpoint for the proxy. If you aren't familiar with creating
proxy endpoints, see Endpoints for Amazon RDS Proxy (p. 203) for details. The proxy itself resides
in the same VPC as the Aurora DB cluster or RDS instance. However, the cross-VPC endpoint resides
in the other VPC, along with the other resources such as the EC2 instances. The cross-VPC endpoint is
associated with subnets and security groups from the same VPC as the EC2 and other resources. These
associations let you connect to the endpoint from the applications that otherwise can't access the
database due to the VPC restrictions.

The following steps explain how to create and access a cross-VPC endpoint through RDS Proxy:

1. Create two VPCs, or choose two VPCs that you already use for Aurora and RDS work. Each VPC should
have its own associated network resources such as an Internet gateway, route tables, subnets, and
security groups. If you only have one VPC, you can consult Getting started with Amazon RDS (p. )
for the steps to set up another VPC to use RDS successfully. You can also examine your existing VPC in
the Amazon EC2 console to see what kinds of resources to connect together.
2. Create a DB proxy associated with the Aurora DB cluster or RDS instance that you want to connect to.
Follow the procedure in Creating an RDS Proxy (p. 184).

204
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

3. On the Details page for your proxy in the RDS console, under the Proxy endpoints section, choose
Create endpoint. Follow the procedure in Creating a proxy endpoint (p. 205).
4. Choose whether to make the cross-VPC endpoint read/write or read-only.
5. Instead of accepting the default of the same VPC as the Aurora DB cluster or RDS instance, choose a
different VPC. This VPC must be in the same AWS Region as the VPC where the proxy resides.
6. Now instead of accepting the defaults for subnets and security groups from the same VPC as the
Aurora DB cluster or RDS instance, make new selections. Make these based on the subnets and
security groups from the VPC that you chose.
7. You don't need to change any of the settings for the SageMaker secrets. The same credentials work for
all endpoints for your proxy, regardless of which VPC each endpoint is in.
8. Wait for the new endpoint to reach the Available state.
9. Make a note of the full endpoint name. This is the value ending in
Region_name.rds.amazonaws.com that you supply as part of the connection string for your
database application.
10.Access the new endpoint from a resource in the same VPC as the endpoint. A simple way to test this
process is to create a new EC2 instance in this VPC. Then you can log into the EC2 instance and run the
mysql or psql commands to connect by using the endpoint value in your connection string.

Creating a proxy endpoint

Console

To create a proxy endpoint

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 Proxies.
3. Click the name of the proxy that you want to create a new endpoint for.

The details page for that proxy appears.

4. In the Proxy endpoints section, choose Create proxy endpoint.

The Create proxy endpoint window appears.

5. For Proxy endpoint name, enter a descriptive name of your choice.
6. For Target role, choose whether to make the endpoint read/write or read-only.

Connections that use a read/write endpoint can perform any kind of operation: data definition
language (DDL) statements, data manipulation language (DML) statements, and queries. These
endpoints always connect to the primary instance of the Aurora cluster. You can use read/write
endpoints for general database operations when you only use a single endpoint in your application.
You can also use read/write endpoints for administrative operations, online transaction processing
(OLTP) applications, and extract-transform-load (ETL) jobs.

Connections that use a read-only endpoint can only perform queries. When there are multiple
reader instances in the Aurora cluster, RDS Proxy can use a different reader instance for each
connection to the endpoint. That way, a query-intensive application can take advantage of Aurora's
clustering capability. You can add more query capacity to the cluster by adding more reader DB
instances. These read-only connections don't impose any overhead on the primary instance of the
cluster. That way, your reporting and analysis queries don't slow down the write operations of your
OLTP applications.
7. For Virtual Private Cloud (VPC), choose the default if you plan to access the endpoint from the
same EC2 instances or other resources where you normally access the proxy or its associated
database. If you want to set up cross-VPC access for this proxy, choose a VPC other than the default.

205
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

For more information about cross-VPC access, see Accessing Aurora and RDS databases across
VPCs (p. 204).
8. For Subnets, RDS Proxy fills in the same subnets as the associated proxy by default. If you want to
restrict access to the endpoint so that only a portion of the address range of the VPC can connect to
it, remove one or more subnets from the set of choices.
9. For VPC security group, you can choose an existing security group or create a new one. RDS Proxy
fills in the same security group or groups as the associated proxy by default. If the inbound and
outbound rules for the proxy are appropriate for this endpoint, you can leave the default choice.

If you choose to create a new security group, specify a name for the security group on this page.
Then edit the security group settings from the EC2 console afterward.
10. Choose Create proxy endpoint.

AWS CLI

To create a proxy endpoint, use the AWS CLI create-db-proxy-endpoint command.

Include the following required parameters:

• --db-proxy-name value
• --db-proxy-endpoint-name value
• --vpc-subnet-ids list_of_ids. Separate the subnet IDs with spaces. You don't specify the ID of
the VPC itself.

You can also include the following optional parameters:

• --target-role { READ_WRITE | READ_ONLY }. This parameter defaults to READ_WRITE. The

READ_ONLY value only has an effect on Aurora provisioned clusters that contain one or more reader
DB instances. When the proxy is associated with an RDS instance or with an Aurora cluster that only
contains a writer DB instance, you can't specify READ_ONLY.
• --vpc-security-group-ids value. Separate the security group IDs with spaces. If you omit this
parameter, RDS Proxy uses the default security group for the VPC. RDS Proxy determines the VPC
based on the subnet IDs that you specify for the --vpc-subnet-ids parameter.

Example

The following example creates a proxy endpoint named my-endpoint.

For Linux, macOS, or Unix:

aws rds create-db-proxy-endpoint \

--db-proxy-name my-proxy \
--db-proxy-endpoint-name my-endpoint \
--vpc-subnet-ids subnet_id subnet_id subnet_id ... \
--target-role READ_ONLY \
--vpc-security-group-ids security_group_id ]

For Windows:

aws rds create-db-proxy-endpoint ^

--db-proxy-name my-proxy ^
--db-proxy-endpoint-name my-endpoint ^
--vpc-subnet-ids subnet_id_1 subnet_id_2 subnet_id_3 ... ^
--target-role READ_ONLY ^
--vpc-security-group-ids security_group_id

206
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

RDS API

To create a proxy endpoint, use the RDS API CreateProxyEndpoint action.

Viewing proxy endpoints

Console

To view the details for a proxy endpoint

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 Proxies.
3. In the list, choose the proxy whose endpoint you want to view. Click the proxy name to view its
details page.
4. In the Proxy endpoints section, choose the endpoint that you want to view. Click its name to view
the details page.
5. Examine the parameters whose values you're interested in. You can check properties such as the
following:

• Whether the endpoint is read/write or read-only.

• The endpoint address that you use in a database connection string.
• The VPC, subnets, and security groups associated with the endpoint.

AWS CLI

To view one or more DB proxy endpoints, use the AWS CLI describe-db-proxy-endpoints command.

You can include the following optional parameters:

• --db-proxy-endpoint-name
• --db-proxy-name

The following example describes the my-endpoint proxy endpoint.

Example

For Linux, macOS, or Unix:

aws rds describe-db-proxy-endpoints \

--db-proxy-endpoint-name my-endpoint

For Windows:

aws rds describe-db-proxy-endpoints ^

--db-proxy-endpoint-name my-endpoint

RDS API

To describe one or more proxy endpoints, use the RDS API DescribeDBProxyEndpoints operation.

Modifying a proxy endpoint

207
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

Console

To modify one or more proxy endpoints

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 Proxies.
3. In the list, choose the proxy whose endpoint you want to modify. Click the proxy name to view its
details page.
4. In the Proxy endpoints section, choose the endpoint that you want to modify. You can select it in
the list, or click its name to view the details page.
5. On the proxy details page, under the Proxy endpoints section, choose Edit. Or on the proxy
endpoint details page, for Actions, choose Edit.
6. Change the values of the parameters that you want to modify.
7. Choose Save changes.

AWS CLI
To modify a DB proxy endpoint, use the AWS CLI modify-db-proxy-endpoint command with the
following required parameters:

• --db-proxy-endpoint-name

Specify changes to the endpoint properties by using one or more of the following parameters:

• --new-db-proxy-endpoint-name
• --vpc-security-group-ids. Separate the security group IDs with spaces.

The following example renames the my-endpoint proxy endpoint to new-endpoint-name.

Example
For Linux, macOS, or Unix:

aws rds modify-db-proxy-endpoint \

--db-proxy-endpoint-name my-endpoint \
--new-db-proxy-endpoint-name new-endpoint-name

For Windows:

aws rds modify-db-proxy-endpoint ^

--db-proxy-endpoint-name my-endpoint ^
--new-db-proxy-endpoint-name new-endpoint-name

RDS API
To modify a proxy endpoint, use the RDS API ModifyDBProxyEndpoint operation.

Deleting a proxy endpoint

You can delete an endpoint for your proxy using the console as described following.
Note
You can't delete the default endpoint that RDS Proxy automatically creates for each proxy.
When you delete a proxy, RDS Proxy automatically deletes all the associated endpoints.

208
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

Console

To delete a proxy endpoint using the AWS Management Console

1. In the navigation pane, choose Proxies.

2. In the list, choose the proxy whose endpoint you want to endpoint. Click the proxy name to view its
details page.
3. In the Proxy endpoints section, choose the endpoint that you want to delete. You can select one or
more endpoints in the list, or click the name of a single endpoint to view the details page.
4. On the proxy details page, under the Proxy endpoints section, choose Delete. Or on the proxy
endpoint details page, for Actions, choose Delete.

AWS CLI
To delete a proxy endpoint, run the delete-db-proxy-endpoint command with the following required
parameters:

• --db-proxy-endpoint-name

The following command deletes the proxy endpoint named my-endpoint.

For Linux, macOS, or Unix:

aws rds delete-db-proxy-endpoint \

--db-proxy-endpoint-name my-endpoint

For Windows:

aws rds delete-db-proxy-endpoint ^

--db-proxy-endpoint-name my-endpoint

RDS API
To delete a proxy endpoint with the RDS API, run the DeleteDBProxyEndpoint operation. Specify the
name of the proxy endpoint for the DBProxyEndpointName parameter.

Limits for proxy endpoints

Each proxy has a default endpoint that you can modify but not create or delete.

The maximum number of user-defined endpoints for a proxy is 20. Thus, a proxy can have up to 21
endpoints: the default endpoint, plus 20 that you create.

When you associate additional endpoints with a proxy, RDS Proxy automatically determines which DB
instances in your cluster to use for each endpoint. You can't choose specific instances the way that you
can with Aurora custom endpoints.

To use cross-VPC capability with RDS Proxy, all the VPCs must be owned by the same AWS account.

Reader endpoints aren't available for Aurora multi-writer clusters.

You can connect to proxy endpoints that you create using the SSL modes REQUIRED and VERIFY_CA.
You can't connect to an endpoint that you create using the SSL mode VERIFY_IDENTITY.

Command-line examples for RDS Proxy

To see how combinations of connection commands and SQL statements interact with RDS Proxy, look at
the following examples.

209
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

Examples

• Preserving Connections to a MySQL Database Across a Failover

• Adjusting the max_connections Setting for an Aurora DB Cluster

Example Preserving connections to a MySQL database across a failover

This MySQL example demonstrates how open connections continue working during a failover, for
example when you reboot a database or it becomes unavailable due to a problem. This example
uses a proxy named the-proxy and an Aurora DB cluster with DB instances instance-8898 and
instance-9814. When you run the failover-db-cluster command from the Linux command line,
the writer instance that the proxy is connected to changes to a different DB instance. You can see that
the DB instance associated with the proxy changes while the connection remains open.

$ mysql -h the-proxy.proxy-demo.us-east-1.rds.amazonaws.com -u admin_user -p

Enter password:
...

mysql> select @@aurora_server_id;

+--------------------+
| @@aurora_server_id |
+--------------------+
| instance-9814 |
+--------------------+
1 row in set (0.01 sec)

mysql>
[1]+ Stopped mysql -h the-proxy.proxy-demo.us-east-1.rds.amazonaws.com -
u admin_user -p
$ # Initially, instance-9814 is the writer.
$ aws rds failover-db-cluster --db-cluster-id cluster-56-2019-11-14-1399
JSON output
$ # After a short time, the console shows that the failover operation is complete.
$ # Now instance-8898 is the writer.
$ fg
mysql -h the-proxy.proxy-demo.us.us-east-1.rds.amazonaws.com -u admin_user -p

mysql> select @@aurora_server_id;

+--------------------+
| @@aurora_server_id |
+--------------------+
| instance-8898 |
+--------------------+
1 row in set (0.01 sec)

mysql>
[1]+ Stopped mysql -h the-proxy.proxy-demo.us-east-1.rds.amazonaws.com -
u admin_user -p
$ aws rds failover-db-cluster --db-cluster-id cluster-56-2019-11-14-1399
JSON output
$ # After a short time, the console shows that the failover operation is complete.
$ # Now instance-9814 is the writer again.
$ fg
mysql -h the-proxy.proxy-demo.us-east-1.rds.amazonaws.com -u admin_user -p

mysql> select @@aurora_server_id;

+--------------------+
| @@aurora_server_id |
+--------------------+
| instance-9814 |
+--------------------+
1 row in set (0.01 sec)
+---------------+---------------+

210
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

| Variable_name | Value |
+---------------+---------------+
| hostname | ip-10-1-3-178 |
+---------------+---------------+
1 row in set (0.02 sec)

Example Adjusting the max_connections setting for an Aurora DB cluster

This example demonstrates how you can adjust the max_connections setting for an Aurora
MySQL DB cluster. To do so, you create your own DB cluster parameter group based on the default
parameter settings for clusters that are compatible with MySQL 5.6 or 5.7. You specify a value for the
max_connections setting, overriding the formula that sets the default value. You associate the DB
cluster parameter group with your DB cluster.

export REGION=us-east-1
export CLUSTER_PARAM_GROUP=rds-proxy-mysql-56-max-connections-demo
export CLUSTER_NAME=rds-proxy-mysql-56

aws rds create-db-parameter-group --region $REGION \

--db-parameter-group-family aurora5.6 \
--db-parameter-group-name $CLUSTER_PARAM_GROUP \
--description "Aurora MySQL 5.6 cluster parameter group for RDS Proxy demo."

aws rds modify-db-cluster --region $REGION \

--db-cluster-identifier $CLUSTER_NAME \
--db-cluster-parameter-group-name $CLUSTER_PARAM_GROUP

echo "New cluster param group is assigned to cluster:"

aws rds describe-db-clusters --region $REGION \
--db-cluster-identifier $CLUSTER_NAME \
--query '*[*].{DBClusterParameterGroup:DBClusterParameterGroup}'

echo "Current value for max_connections:"

aws rds describe-db-cluster-parameters --region $REGION \
--db-cluster-parameter-group-name $CLUSTER_PARAM_GROUP \
--query '*[*].{ParameterName:ParameterName,ParameterValue:ParameterValue}' \
--output text | grep "^max_connections"

echo -n "Enter number for max_connections setting: "

read answer

aws rds modify-db-cluster-parameter-group --region $REGION --db-cluster-parameter-group-

name $CLUSTER_PARAM_GROUP \
--parameters "ParameterName=max_connections,ParameterValue=$
$answer,ApplyMethod=immediate"

echo "Updated value for max_connections:"

aws rds describe-db-cluster-parameters --region $REGION \
--db-cluster-parameter-group-name $CLUSTER_PARAM_GROUP \
--query '*[*].{ParameterName:ParameterName,ParameterValue:ParameterValue}' \
--output text | grep "^max_connections"

Troubleshooting for RDS Proxy

Following, you can find troubleshooting ideas for some common RDS Proxy issues and information on
CloudWatch logs for RDS Proxy.

In the RDS Proxy logs, each entry is prefixed with the name of the associated proxy endpoint. This name
can be the name you specified for a user-defined endpoint, or the special name default for read/
write requests using the default endpoint of a proxy. For more information about proxy endpoints, see
Endpoints for Amazon RDS Proxy (p. 203).

211
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

Topics
• Common issues and solutions (p. 212)
• Working with CloudWatch logs for RDS Proxy (p. 216)
• Verifying connectivity for a proxy (p. 216)

Common issues and solutions

For possible causes and solutions to some common problems that you might encounter using RDS Proxy,
see the following.

You might encounter the following issues while creating a new proxy or connecting to a proxy.

Error Causes or workarounds

403: The security Select an existing IAM role instead of choosing to create a new one.
token included in
the request is
invalid

You might encounter the following issues while connecting to a MySQL proxy.

Error Causes or workarounds

ERROR 1040 The rate of connection requests from the client to the proxy has exceeded
(HY000): the limit.
Connections rate
limit exceeded
(limit_value)

ERROR 1040 The number of simultaneous requests with IAM authentication from the
(HY000): IAM client to the proxy has exceeded the limit.
authentication
rate limit
exceeded

ERROR 1040 The number of simultaneous connection requests from the client to the
(HY000): Number proxy exceeded the limit.
simultaneous
connections
exceeded
(limit_value)

ERROR 1045 Some possible reasons include the following:

(28000): Access
denied for user • The Secrets Manager secret used by the proxy doesn't match the user
'DB_USER'@'%' (using name and password of an existing database user. Either update the
password: YES) credentials in the Secrets Manager secret, or make sure the database user
exists and has the same password as in the secret.

ERROR 1105 An unknown error occurred.

(HY000): Unknown
error

ERROR 1231 The value set for the character_set_client parameter is not valid. For
(42000): Variable example, the value ucs2 is not valid because it can crash the MySQL server.

212
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

Error Causes or workarounds

''character_set_client''
can't be set to
the value of value

ERROR 3159 You enabled the setting Require Transport Layer Security in the proxy
(HY000): This RDS but your connection included the parameter ssl-mode=DISABLED in the
Proxy requires TLS MySQL client. Do either of the following:
connections.
• Disable the setting Require Transport Layer Security for the proxy.
• Connect to the database using the minimum setting of ssl-
mode=REQUIRED in the MySQL client.

ERROR 2026 The TLS handshake to the proxy failed. Some possible reasons include the
(HY000): SSL following:
connection error:
Internal Server • SSL is required but the server doesn't support it.
Error • An internal server error occurred.
• A bad handshake occurred.

ERROR 9501 The proxy timed-out waiting to acquire a database connection. Some
(HY000): Timed- possible reasons include the following:
out waiting to
acquire database • The proxy is unable to establish a database connection because the
connection maximum connections have been reached
• The proxy is unable to establish a database connection because the
database is unavailable.

You might encounter the following issues while connecting to a PostgreSQL proxy.

Error Cause Solution

IAM authentication is The user tried to connect The user needs to connect to the
allowed only with SSL to the database using IAM database using the minimum
connections. authentication with the setting setting of sslmode=require in
sslmode=disable in the the PostgreSQL client. For more
PostgreSQL client. information, see the PostgreSQL
SSL support documentation.

This RDS Proxy requires The user enabled the option To fix this error, do one of the
TLS connections. Require Transport Layer following:
Security but tried to connect
with sslmode=disable in the • Disable the proxy's Require
PostgreSQL client. Transport Layer Security
option.
• Connect to the database
using the minimum setting
of sslmode=allow in the
PostgreSQL client.

IAM authentication This error might be due to the To fix this error, do the
failed for user following reasons: following:
user_name. Check the IAM
token for this user and • The client supplied the 1. Confirm that the provided
try again. incorrect IAM user name. IAM user exists.

213
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

Error Cause Solution

• The client supplied an 2. Confirm that the IAM
incorrect IAM authorization authorization token belongs
token for the user. to the provided IAM user.
• The client is using an IAM 3. Confirm that the IAM policy
policy that does not have the has adequate permissions for
necessary permissions. RDS.
• The client supplied an expired 4. Check the validity of the IAM
IAM authorization token for authorization token used.
the user.

This RDS proxy has no There is no Secrets Manager Add a Secrets Manager secret for
credentials for the role secret for this role. this role.
role_name. Check the
credentials for this
role and try again.

RDS supports only IAM or The database client being used If you're not using IAM
MD5 authentication. to connect to the proxy is using authentication, use the MD5
an authentication mechanism password authentication only.
not currently supported by the
proxy, such as SCRAM-SHA-256.

A user name is missing The database client being used Make sure to define a user name
from the connection to connect to the proxy isn't when setting up a connection to
startup packet. Provide sending a user name when the proxy using the PostgreSQL
a user name for this trying to establish a connection. client of your choice.
connection.

Feature not supported: The PostgreSQL client used Use a newer PostgreSQL client
RDS Proxy supports to connect to the proxy uses a that supports the 3.0 messaging
only version 3.0 of the protocol older than 3.0. protocol. If you're using the
PostgreSQL messaging PostgreSQL psql CLI, use a
protocol. version greater than or equal to
7.4.

Feature not supported: The PostgreSQL client used to Turn off the streaming
RDS Proxy currently connect to the proxy is trying replication mode in the
doesn't support to use the streaming replication PostgreSQL client being used to
streaming replication mode, which isn't currently connect.
mode. supported by RDS Proxy.

Feature not supported: Through the startup message, Turn off the option being
RDS Proxy currently the PostgreSQL client used shown as not supported from
doesn't support the to connect to the proxy is the message above in the
option option_name. requesting an option that isn't PostgreSQL client being used to
currently supported by RDS connect.
Proxy.

The IAM authentication The number of simultaneous Reduce the rate in which
failed because of too requests with IAM connections using IAM
many competing requests. authentication from the client to authentication from a
the proxy has exceeded the limit. PostgreSQL client are
established.

214
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

Error Cause Solution

The maximum number The number of simultaneous Reduce the number of active
of client connections connection requests from the connections from PostgreSQL
to the proxy exceeded client to the proxy exceeded the clients to this RDS proxy.
number_value. limit.

Rate of connection The rate of connection requests Reduce the rate in which
to proxy exceeded from the client to the proxy has connections from a PostgreSQL
number_value. exceeded the limit. client are established.

The password that was The password for this role Check the secret for this role in
provided for the role doesn't match the Secrets Secrets Manager to see if the
role_name is wrong. Manager secret. password is the same as what's
being used in your PostgreSQL
client.

The IAM authentication There is a problem with Generate a new authentication

failed for the role the IAM token used for IAM token and use it in a new
role_name. Check the IAM authentication. connection.
token for this role and
try again.

IAM is allowed only with A client tried to connect using Enable SSL in the PostgreSQL
SSL connections. IAM authentication, but SSL client.
wasn't enabled.

Unknown error. An unknown error occurred. Reach out to AWS Support for us
to investigate the issue.

Timed-out waiting The proxy timed-out waiting to Possible solutions are:

to acquire database acquire a database connection.
connection. Some possible reasons include • Check the target of the RDS
the following: DB instance or Aurora DB
cluster status to see if it's
• The proxy can't establish a unavailable.
database connection because • Check if there are long-
the maximum connections running transactions and/or
have been reached. queries being executed. They
• The proxy can't establish a can use database connections
database connection because from the connection pool for a
the database is unavailable. long time.

Request returned an The database connection The solution depends on the

error: database_error. established from the proxy specific database error. One
returned an error. example is: Request returned
an error: database
"your-database-name"
does not exist. This means
the specified database name,
or the user name used as a
database name (in case a
database name hasn't been
specified), doesn't exist in the
database server.

215
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

Working with CloudWatch logs for RDS Proxy

You can find logs of RDS Proxy activity under CloudWatch in the AWS Management Console. Each proxy
has an entry in the Log groups page.
Important
These logs are intended for human consumption for troubleshooting purposes and not for
programmatic access. The format and content of the logs is subject to change.
In particular, older logs don't contain any prefixes indicating the endpoint for each request. In
newer logs, each entry is prefixed with the name of the associated proxy endpoint. This name
can be the name that you specified for a user-defined endpoint, or the special name default
for requests using the default endpoint of a proxy.

Verifying connectivity for a proxy

You can use the following commands to verify that all components of the connection mechanism can
communicate with the other components.

Examine the proxy itself using the describe-db-proxies command. Also examine the associated target
group using the describe-db-proxy-target-groups Check that the details of the targets match the RDS
DB instance or Aurora DB cluster that you intend to associate with the proxy. Use commands such as the
following.

aws rds describe-db-proxies --db-proxy-name $DB_PROXY_NAME

aws rds describe-db-proxy-target-groups --db-proxy-name $DB_PROXY_NAME

To confirm that the proxy can connect to the underlying database, examine the targets specified in the
target groups using the describe-db-proxy-targets command. Use a command such as the following.

aws rds describe-db-proxy-targets --db-proxy-name $DB_PROXY_NAME

The output of the describe-db-proxy-targets command includes a TargetHealth field. You can
examine the fields State, Reason, and Description inside TargetHealth to check if the proxy can
communicate with the underlying DB instance.

• A State value of AVAILABLE indicates that the proxy can connect to the DB instance.
• A State value of UNAVAILABLE indicates a temporary or permanent connection problem. In
this case, examine the Reason and Description fields. For example, if Reason has a value of
PENDING_PROXY_CAPACITY, try connecting again after the proxy finishes its scaling operation. If
Reason has a value of UNREACHABLE, CONNECTION_FAILED, or AUTH_FAILURE, use the explanation
from the Description field to help you diagnose the issue.
• The State field might have a value of REGISTERING for a brief time before changing to AVAILABLE
or UNAVAILABLE.

If the following Netcat command (nc) is successful, you can access the proxy endpoint from the EC2
instance or other system where you're logged in. This command reports failure if you're not in the same
VPC as the proxy and the associated database. You might be able to log directly in to the database
without being in the same VPC. However, you can't log into the proxy unless you're in the same VPC.

nc -zx MySQL_proxy_endpoint 3306

nc -zx PostgreSQL_proxy_endpoint 5432

You can use the following commands to make sure that your EC2 instance has the required properties. In
particular, the VPC for the EC2 instance must be the same as the VPC for the RDS DB instance or Aurora
DB cluster that the proxy connects to.

216
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

aws ec2 describe-instances --instance-ids your_ec2_instance_id

Examine the Secrets Manager secrets used for the proxy.

aws secretsmanager list-secrets

aws secretsmanager get-secret-value --secret-id your_secret_id

Make sure that the SecretString field displayed by get-secret-value is encoded as a JSON
string that includes username and password fields. The following example shows the format of the
SecretString field.

{
"ARN": "some_arn",
"Name": "some_name",
"VersionId": "some_version_id",
"SecretString": '{"username":"some_username","password":"some_password"}',
"VersionStages": [ "some_stage" ],
"CreatedDate": some_timestamp
}

Using RDS Proxy with AWS CloudFormation

You can use RDS Proxy with AWS CloudFormation. Doing so helps you to create groups of related
resources, including a proxy that can connect to a newly created Amazon RDS DB instance or Aurora
DB cluster. RDS Proxy support in AWS CloudFormation involves two new registry types: DBProxy and
DBProxyTargetGroup.

The following listing shows a sample AWS CloudFormation template for RDS Proxy.

Resources:
DBProxy:
Type: AWS::RDS::DBProxy
Properties:
DBProxyName: CanaryProxy
EngineFamily: MYSQL
RoleArn:
Fn::ImportValue: SecretReaderRoleArn
Auth:
- {AuthScheme: SECRETS, SecretArn: !ImportValue ProxySecret, IAMAuth: DISABLED}
VpcSubnetIds:
Fn::Split: [",", "Fn::ImportValue": SubnetIds]

ProxyTargetGroup:
Type: AWS::RDS::DBProxyTargetGroup
Properties:
DbProxyName: CanaryProxy
TargetGroupName: default
InstanceIdentifiers:
- Fn::ImportValue: DBInstanceName
DependsOn: DBProxy

For more information about the Amazon RDS and Aurora resources that you can create using AWS
CloudFormation, see RDS resource type reference.

217
 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. 623)

Microsoft SQL Server Options for the Microsoft SQL Server database engine (p. 753)

MySQL Options for MySQL DB instances (p. 929)

Oracle Adding options to Oracle DB instances (p. 1129)

PostgreSQL PostgreSQL does not use options and option groups. PostgreSQL
uses extensions and modules to provide additional features.
For more information, see Supported PostgreSQL features and
extensions (p. 1587).

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.

To associate an option group with a DB instance, modify the DB instance. For more information, see
Modifying an Amazon RDS DB instance (p. 256).

Both DB instances and DB snapshots can be associated with an option group. In some cases, you might
restore from a DB snapshot or perform a point-in-time restore for a DB instance. In these cases, the
option group associated with the DB snapshot or DB instance is, by default, 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. Thus, 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.

218
 Amazon Relational Database Service User Guide
Option groups overview

Persistent options can't be removed from an option group while DB instances are associated with the
option group. An example of a persistent option is the TDE option for Microsoft SQL Server transparent
data encryption (TDE). You must disassociate all DB instances from the option group before a persistent
option can be removed from the option group. In some cases, you might restore or perform a point-in-
time restore from a DB snapshot. In these cases, 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.

Permanent options, such as the TDE option for Oracle Advanced Security TDE, can never be removed
from an option group. You can change the option group of a DB instance that is using the permanent
option. However, the option group associated with the DB instance must include the same permanent
option. In some cases, you might restore or perform a point-in-time restore from a DB snapshot. In these
cases, 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.

For Oracle DB instances, you can copy shared DB snapshots that have the options Timezone or OLS
(or both). To do so, specify a target option group that includes these options when you copy the DB
snapshot. The OLS option is permanent and persistent only for Oracle DB instances running Oracle
version 12.2 or higher. For more information about these options, see Oracle time zone (p. 1204) and
Oracle Label Security (p. 1170).

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 VPC service, or EC2-Classic (non-VPC)
supported by the 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 can't use the option group assigned to a DB instance if you try to restore the instance
to a different VPC or a different platform. If you restore a DB instance to a different VPC or a different
platform, you can do one of the following:

• Assign the default option group to the DB instance.

• Assign an option group that is linked to that VPC or platform.
• Create a new option group and assign it to the DB instance.

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. 1153) and Oracle Management Agent for Enterprise
Manager Cloud Control (p. 1157).
• Oracle native network encryption (p. 1179) and Oracle Secure Sockets Layer (p. 1185).

219
 Amazon Relational Database Service User Guide
Creating an option group

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
Copying an option group (p. 221).

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. 222). 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. 218).

Console
One way of creating an option group is by using the AWS Management Console.

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:

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.
5. To continue, choose Create. To cancel the operation instead, choose Cancel.

AWS 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, macOS, or Unix:

aws rds create-option-group \

220
 Amazon Relational Database Service User Guide
Copying an 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"

RDS API
To create an option group, call the Amazon RDS API CreateOptionGroup operation. Include the
following parameters:

• OptionGroupName
• EngineName
• MajorEngineVersion
• OptionGroupDescription

Copying an option group

You can use the AWS CLI or the Amazon RDS API copy an option group. Copying an option group
is convenient when you have an existing option group and you want to include most of its custom
parameters and values 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.
Note
Currently, you can't copy an option group to a different AWS Region.

AWS CLI
To copy an option group, use the AWS CLI copy-option-group command. Include the following required
options:

• --source-option-group-identifier
• --target-option-group-identifier
• --target-option-group-description

Example

The following example creates an option group named new-option-group, which is a local copy of the
option group my-option-group.

For Linux, macOS, or Unix:

aws rds copy-option-group \

--source-option-group-identifier my-option-group \

221
 Amazon Relational Database Service User Guide
Adding an option to an option group

--target-option-group-identifier new-option-group \
--target-option-group-description "My new option group"

For Windows:

aws rds copy-option-group ^

--source-option-group-identifier my-option-group ^
--target-option-group-identifier new-option-group ^
--target-option-group-description "My new option group"

RDS API
To copy an option group, call the Amazon RDS API CopyOptionGroup operation. Include the following
required parameters.

• SourceOptionGroupIdentifier
• 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. 218).

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, choose the Apply Immediately option in the console. Or you can include the --apply-
immediately option when using the AWS CLI or set the ApplyImmediately 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.
Note
If you specify a security group as a value for an option in an option group, you manage the
security group by modifying the option group. You can't change or remove this security group
by modifying a DB instance. Also, the security group doesn't appear in the DB instance details
in the AWS Management Console or in the output for the AWS CLI command describe-db-
instances.

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. Choose the option group that you want to modify, and then choose Add option.

222
 Amazon Relational Database Service User Guide
Adding an option to an option group

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 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.

223
 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.

AWS 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. Even if you use the default security group,
you must specify that security group.

For Linux, macOS, or Unix:

aws rds add-option-to-option-group \

224
 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. It also specifies a custom port
and a pair of Amazon EC2 VPC security groups to use for that port.

For Linux, macOS, 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.

225
 Amazon Relational Database Service User Guide
Listing the options and option settings for an option group

For Linux, macOS, 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

RDS API
To add an option to an option group using the Amazon RDS API, call the ModifyOptionGroup operation
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.

226
 Amazon Relational Database Service User Guide
Modifying an option setting

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. 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 the name of the option group to display its details. The options and option settings in the
option group are listed.

AWS CLI
To list the options and option settings for an option group, use the AWS CLI describe-option-
groups 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

RDS API
To list the options and option settings for an option group, use the Amazon RDS API
DescribeOptionGroups operation. 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. 218).

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, choose the Apply Immediately option in the console. Or you can include the --apply-
immediately option when using the AWS CLI or set the ApplyImmediately parameter to true when

227
 Amazon Relational Database Service User Guide
Modifying an option setting

using the 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.
Note
If you specify a security group as a value for an option in an option group, you manage the
security group by modifying the option group. You can't change or remove this security group
by modifying a DB instance. Also, the security group doesn't appear in the DB instance details
in the AWS Management Console or in the output for the AWS CLI command describe-db-
instances.

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.

AWS 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, macOS, 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

228
 Amazon Relational Database Service User Guide
Modifying an option setting

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

Example

The following example modifies the Oracle option NATIVE_NETWORK_ENCRYPTION and changes the
option settings.

For Linux, macOS, 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

229
 Amazon Relational Database Service User Guide
Removing an option from an option group

RDS 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.

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. 218).

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.

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. Select the option group whose option you want to remove, and then choose Delete option.
4. 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.

230
 Amazon Relational Database Service User Guide
Deleting an option group

5. When the settings are as you want them, choose Yes, Delete.

AWS CLI
To remove an option from an option group, use the AWS CLI remove-option-from-option-
group command with the option that you want to delete. By default, the option is removed from each
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, macOS, 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

RDS 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

Deleting an option group

You can delete an option group that is not associated with any Amazon RDS resource. An option group
can be associated with a DB instance, a manual DB snapshot, or an automated DB snapshot.

If you try to delete an option group that is associated with an Amazon RDS resource, an error similar to
the following is returned.

231
 Amazon Relational Database Service User Guide
Deleting an option group

An error occurred (InvalidOptionGroupStateFault) when calling the DeleteOptionGroup

operation: The option group 'optionGroupName' cannot be deleted because it is in use.

To find the Amazon RDS resources associated with an option 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 Option groups.
3. Choose the name of the option group to show its details.
4. Check the Associated Instances and Snapshots section for the associated Amazon RDS resources.

If a DB instance is associated with the option group, modify the DB instance to use a different option
group. For more information, see Modifying an Amazon RDS DB instance (p. 256).

If a manual DB snapshot is associated with the option group, modify the DB snapshot to use a different
option group using the AWS CLI modify-db-snapshot command.
Note
You can't modify the option group of an automated DB snapshot.

Console
One way of deleting an option group is by using the AWS Management Console.

To delete 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. Choose the option group.
4. Choose Delete group.
5. On the confirmation page, choose Delete to finish deleting the option group, or choose Cancel to
cancel the deletion.

AWS CLI
To delete an option group, use the AWS CLI delete-option-group command with the following
required parameter.

• --option-group-name

Example

The following example deletes an option group named testoptiongroup.

For Linux, macOS, or Unix:

aws rds delete-option-group \

--option-group-name testoptiongroup

232
 Amazon Relational Database Service User Guide
Deleting an option group

For Windows:

aws rds delete-option-group ^

--option-group-name testoptiongroup

RDS API
To delete an option group, call the Amazon RDS API DeleteOptionGroup operation. Include the
following parameter:

• OptionGroupName

233
 Amazon Relational Database Service User Guide
Working with parameter groups

Working with DB parameter groups

You manage your DB engine configuration by associating your DB instances with parameter groups.
Amazon RDS defines parameter groups with default settings that apply to newly created DB instances.
Important
You can define your own parameter groups with customized settings. Then you can modify your
DB instances to use your own parameter groups.
For information about modifying a DB instance, see Modifying an Amazon RDS DB
instance (p. 256).

A DB parameter group acts as a container for engine configuration values that are applied to one or more
DB instances.

If you create a DB instance without specifying a DB parameter group, the DB instance uses a default 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 can't
modify the parameter settings of a default parameter group. Instead, you create your own parameter
group where you choose your own parameter settings. Not all DB engine parameters can be changed in a
parameter group that you create.

If you want to use your own parameter group, you create a new parameter group and modify the
parameters that you want to. You then modify your DB instance to use the new parameter group. If
you update parameters within a DB parameter group, the changes apply to all DB instances that are
associated with that parameter group.

You can copy an existing DB parameter group with the AWS CLI copy-db-parameter-group command.
Copying a parameter group can be convenient when you want to include most of an existing DB
parameter group's custom parameters and values in a new DB parameter group.

Here are some important points 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 takes effect after you manually reboot the DB
instance. You can reboot a DB instance using the RDS console, by calling the reboot-db-instance
CLI command, or by calling the RebootDbInstance API operation. 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.

If a DB instance isn't using the latest changes to its associated DB parameter group, the AWS
Management Console shows the DB parameter group with a status of pending-reboot. The pending-
reboot parameter groups status doesn't result in an automatic reboot during the next maintenance
window. To apply the latest parameter changes to that DB instance, manually reboot the DB instance.
• When you change the DB parameter group associated with a DB instance, you must manually reboot
the instance before the DB instance can use the new DB parameter group. For more information about
changing the DB parameter group, see Modifying an Amazon RDS DB instance (p. 256).
• You can specify the value for a DB parameter 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 Specifying DB parameters (p. 246).
• Set any parameters that relate to the character set or collation of your database in your parameter
group before 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.

234
 Amazon Relational Database Service User Guide
Creating a DB parameter group

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. Try out
parameter group setting changes on a test DB instance before applying those parameter group
changes to a production DB instance.
• To determine the supported parameters for your DB engine, you can view the parameters in the DB
parameter group used by the DB instance. For more information, see Viewing parameter values for a
DB parameter group (p. 245).

Topics
• Creating a DB parameter group (p. 235)
• Associating a DB parameter group with a DB instance (p. 237)
• Modifying parameters in a DB parameter group (p. 238)
• Resetting parameters in a DB parameter group to their default values (p. 240)
• Copying a DB parameter group (p. 242)
• Listing DB parameter groups (p. 244)
• Viewing parameter values for a DB parameter group (p. 245)
• Comparing DB parameter groups (p. 246)
• Specifying DB parameters (p. 246)

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.

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, enter the name of the new DB parameter group.
7. In the Description box, enter a description for the new DB parameter group.
8. Choose Create.

235
 Amazon Relational Database Service User Guide
Creating a DB parameter group

AWS 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.

Example

For Linux, macOS, 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

RDS API
To create a DB parameter group, use the RDS API CreateDBParameterGroup operation.

Include the following required parameters:

• DBParameterGroupName
• DBParameterGroupFamily
• Description

236
 Amazon Relational Database Service User Guide
Associating a DB parameter group with a DB instance

Associating a DB parameter group with a DB instance

You can create your own DB parameter groups with customized settings. You can associate a DB
parameter group with a DB instance using the AWS Management Console, the AWS CLI, or the RDS API.
You can do so when you create or modify a DB instance.

For information about creating a DB parameter group, see Creating a DB parameter group (p. 235).
For information about creating a DB instance, see Creating an Amazon RDS DB instance (p. 147). For
information about modifying a DB instance, see Modifying an Amazon RDS DB instance (p. 256).
Note
When you change the DB parameter group associated with a DB instance, you must manually
reboot the instance before the DB instance can use the new DB parameter group.

Console

To associate a DB parameter group with 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 Databases, and then choose the DB instance that you want to
modify.
3. Choose Modify. The Modify DB Instance page appears.
4. Change the DB parameter group setting.
5. Choose Continue and check the summary of modifications.
6. (Optional) Choose Apply immediately to apply the changes immediately. Choosing this option
can cause an outage in some cases. For more information, see Using the Apply Immediately
setting (p. 257).
7. On the confirmation page, review your changes. If they are correct, choose Modify DB instance to
save your changes.

Or choose Back to edit your changes or Cancel to cancel your changes.

AWS CLI
To associate a DB parameter group with a DB instance, use the AWS CLI modify-db-instance
command with the following options:

• --db-instance-identifier
• --db-parameter-group-name

The following example associates the mydbpg DB parameter group with the database-1 DB
instance. The changes are applied immediately by using --apply-immediately. Use --no-apply-
immediately to apply the changes during the next maintenance window. For more information, see
Using the Apply Immediately setting (p. 257).

Example

For Linux, macOS, or Unix:

aws rds modify-db-instance \

--db-instance-identifier database-1 \

237
 Amazon Relational Database Service User Guide
Modifying parameters in a DB parameter group

--db-parameter-group-name mydbpg \
--apply-immediately

For Windows:

aws rds modify-db-instance ^

--db-instance-identifier database-1 ^
--db-parameter-group-name mydbpg ^
--apply-immediately

RDS API
To associate a DB parameter group with a DB instance, use the RDS API ModifyDBInstance operation
with the following parameters:

• DBInstanceName
• DBParameterGroupName

Modifying parameters in a DB parameter group

You can modify parameter values in a customer-created DB parameter group; you can't 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.

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. The RDS console shows the status
of the DB parameter group associated with a DB instance on the Configuration tab. For example, if the
DB instance isn't using the latest changes to its associated DB parameter group, the RDS console shows
the DB parameter group with a status of pending-reboot. To apply the latest parameter changes to that
DB instance, manually reboot the DB instance.

238
 Amazon Relational Database Service User Guide
Modifying parameters in a DB parameter group

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, choose the parameter group that you want to modify.
4. For Parameter group actions, choose Edit.
5. Change the values of the parameters that you want to modify. You can scroll through the
parameters using the arrow keys at the top right of the dialog box.

You can't change values in a default parameter group.

6. Choose Save changes.

AWS CLI
To modify a DB parameter group, use the AWS CLI modify-db-parameter-group command with the
following required options:

• --db-parameter-group-name

239
 Amazon Relational Database Service User Guide
Resetting parameters in a DB parameter group

• --parameters

The following example modifies the max_connections and max_allowed_packet values in the DB
parameter group named mydbparametergroup.

Example

For Linux, macOS, 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

RDS API
To modify a DB parameter group, use the RDS API ModifyDBParameterGroup operation with the
following required parameters:

• DBParameterGroupName
• Parameters

Resetting parameters in a DB parameter group to

their default values
You can reset parameter values in a customer-created DB parameter group to their default values.
Changes to parameters in a customer-created DB parameter group are applied to all DB instances that
are associated with the DB parameter group.

When you use the console, you can reset specific parameters to their default values, but you can't easily
reset all of the parameters in the DB parameter group at once. When you use the AWS CLI or RDS API,
you can reset specific parameters to their default values, and you can reset all of the parameters in the
DB parameter group at once.

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. The RDS console shows the status
of the DB parameter group associated with a DB instance on the Configuration tab. For example, if the
DB instance isn't using the latest changes to its associated DB parameter group, the RDS console shows
the DB parameter group with a status of pending-reboot. To apply the latest parameter changes to that
DB instance, manually reboot the DB instance.

240
 Amazon Relational Database Service User Guide
Resetting parameters in a DB parameter group

Note
In a default DB parameter group, parameters are always set to their default values.

Console
To reset parameters in a DB parameter group to their default values

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, choose the parameter group.
4. For Parameter group actions, choose Edit.
5. Choose the parameters that you want to reset to their default values. You can scroll through the
parameters using the arrow keys at the top right of the dialog box.

You can't reset values in a default parameter group.

6. Choose Reset and then confirm by choosing Reset parameters.

AWS CLI
To reset some or all of the parameters in a DB parameter group, use the AWS CLI reset-db-
parameter-group command with the following required option: --db-parameter-group-name.

241
 Amazon Relational Database Service User Guide
Copying a DB parameter group

To reset all of the parameters in the DB parameter group, specify the --reset-all-parameters
option. To reset specific parameters, specify the --parameters option.

The following example resets all of the parameters in the DB parameter group named
mydbparametergroup to their default values.

Example

For Linux, macOS, or Unix:

aws rds reset-db-parameter-group \

--db-parameter-group-name mydbparametergroup \
--reset-all-parameters

For Windows:

aws rds reset-db-parameter-group ^

--db-parameter-group-name mydbparametergroup ^
--reset-all-parameters

The following example resets the max_connections and max_allowed_packet options to their
default values in the DB parameter group named mydbparametergroup.

Example

For Linux, macOS, or Unix:

aws rds reset-db-parameter-group \

--db-parameter-group-name mydbparametergroup \
--parameters "ParameterName=max_connections,ApplyMethod=immediate" \
"ParameterName=max_allowed_packet,ApplyMethod=immediate"

For Windows:

aws rds reset-db-parameter-group ^

--db-parameter-group-name mydbparametergroup ^
--parameters "ParameterName=max_connections,ApplyMethod=immediate" ^
"ParameterName=max_allowed_packet,ApplyMethod=immediate"

The command produces output like the following:

DBParameterGroupName mydbparametergroup

RDS API
To reset parameters in a DB parameter group to their default values, use the RDS
API ResetDBParameterGroup command with the following required parameter:
DBParameterGroupName.

To reset all of the parameters in the DB parameter group, set the ResetAllParameters parameter to
true. To reset specific parameters, specify the Parameters parameter.

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

242
 Amazon Relational Database Service User Guide
Copying a DB parameter group

custom parameters and values from that group in a new DB parameter group. You can copy a DB
parameter group by using the AWS Management Console, the AWS CLI copy-db-parameter-group
command, or the RDS API CopyDBParameterGroup operation.

After you copy a DB parameter group, wait at least 5 minutes before creating your first DB instance that
uses that DB parameter group as the default parameter group. Doing this allows Amazon RDS to fully
complete the copy action before the parameter group is used. This is especially important for parameters
that are critical when creating the default database for a DB instance. An example is the character set
for the default database defined by the character_set_database parameter. Use the Parameter
Groups option of the Amazon RDS console or the describe-db-parameters command to verify that your
DB parameter group is 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.
Currently, you can't copy a parameter group to a different AWS Region.

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, choose the custom parameter group that you want to copy.
4. For Parameter group actions, choose Copy.
5. In New DB parameter group identifier, enter a name for the new parameter group.
6. In Description, enter a description for the new parameter group.
7. Choose Copy.

AWS CLI
To copy a DB parameter group, use the AWS CLI copy-db-parameter-group command with the
following required options:

• --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, macOS, 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 ^

243
 Amazon Relational Database Service User Guide
Listing DB parameter groups

--target-db-parameter-group-identifier mygroup2 ^
--target-db-parameter-group-description "DB parameter group 2"

RDS API
To copy a DB parameter group, use the RDS API CopyDBParameterGroup operation with the following
required parameters:

• 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 can't be modified. When you create a custom
parameter group, you can modify parameter settings.

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.

AWS CLI
To list all DB parameter groups for an AWS account, use the AWS CLI describe-db-parameter-
groups 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 default.mysql5.5 mysql5.5 Default parameter group for MySQL5.5

DBPARAMETERGROUP default.mysql5.6 mysql5.6 Default parameter group for MySQL5.6
DBPARAMETERGROUP mydbparametergroup mysql5.6 My new parameter group

The following example describes the mydbparamgroup1 parameter group.

For Linux, macOS, or Unix:

aws rds describe-db-parameter-groups \

244
 Amazon Relational Database Service User Guide
Viewing parameter values for a DB parameter group

--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:

DBPARAMETERGROUP mydbparametergroup1 mysql5.5 My new parameter group

RDS API
To list all DB parameter groups for an AWS account, use the RDS API DescribeDBParameterGroups
operation.

Viewing parameter values for a DB parameter group

You can get a list of all parameters in a DB parameter group and their values.

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. Choose the name of the parameter group to see its list of parameters.

AWS 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 Parameter Value Source Data Type Apply

Type Is Modifiable
DBPARAMETER allow-suspicious-udfs engine-default boolean static
false
DBPARAMETER auto_increment_increment engine-default integer dynamic
true
DBPARAMETER auto_increment_offset engine-default integer dynamic
true

245
 Amazon Relational Database Service User Guide
Comparing DB parameter groups

DBPARAMETER binlog_cache_size 32768 system integer dynamic

true
DBPARAMETER socket /tmp/mysql.sock system string static
false

RDS API
To view the parameter values for a DB parameter group, use the RDS API DescribeDBParameters
command with the following required parameter.

• 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. In the navigation pane, choose Parameter groups.
3. In the list, choose the two parameter groups that you want to compare.
4. For Parameter group actions, choose Compare.
Note
If the items you selected aren't equivalent, you can't choose Compare. For example, you
can't compare a MySQL 5.6 and a MySQL 5.7 parameter group. You can't compare a DB
parameter group and an Aurora DB cluster parameter group.

Specifying DB parameters
DB parameter types include the following:

• integer
• Boolean
• string
• long
• double
• timestamp
• object of other defined data types
• array of values of type integer, Boolean, string, long, double, timestamp, or object

You can also specify integer and Boolean DB parameters using expressions, formulas, and functions.

For the Oracle engine, you can use the DBInstanceClassHugePagesDefault formula variable to
specify a Boolean DB parameter. See DB parameter formula variables (p. 247).

For the PostgreSQL engine, you can use an expression to specify a Boolean DB parameter. See Boolean
DB parameter expressions (p. 249).

Contents

246
 Amazon Relational Database Service User Guide
Specifying DB parameters

• DB parameter formulas (p. 247)

• DB parameter formula variables (p. 247)
• DB parameter formula operators (p. 247)
• DB parameter functions (p. 248)
• Boolean DB parameter expressions (p. 249)
• DB parameter log expressions (p. 250)
• DB parameter value examples (p. 250)

DB parameter formulas
A DB parameter formula is an expression that resolves to an integer value or a Boolean value. You
enclose the expression in braces: {}. You can use a formula 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 an integer or a Boolean value. The names of the variables are case-
sensitive.

AllocatedStorage

Returns an integer representing the size, in bytes, of the data volume.

DBInstanceClassHugePagesDefault

Returns a Boolean value. Currently, it's only supported for Oracle engines.

For more information, see Enabling HugePages for an Oracle DB instance (p. 1105).
DBInstanceClassMemory

Returns an integer of the number of bytes of memory allocated to the DB instance class associated
with the current DB instance, less the memory used by RDS processes that manage the instance.
DBInstanceVCPU

Returns an integer representing the number of virtual central processing units (vCPUs) used by
Amazon RDS to manage the instance. Currently, it's only supported for the PostgreSQL engine.
EndPointPort

Returns an integer representing the port used when connecting to the DB instance.

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.

247
 Amazon Relational Database Service User Guide
Specifying DB parameters

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
You specify the arguments of DB parameter functions as either integers or formulas. Each function must
have at least one argument. Specify multiple arguments as a comma-separated list. The list can't have
any empty members, such as argument1,,argument3. Function names are case-insensitive.

IF

Returns an argument.

Currently, it's only supported for Oracle engines, and the only supported first argument is
{DBInstanceClassHugePagesDefault}. For more information, see Enabling HugePages for an
Oracle DB instance (p. 1105).

Syntax

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.

248
 Amazon Relational Database Service User Guide
Specifying DB parameters

SUM

Adds the values of the specified integers or parameter formulas.

Syntax

SUM(argument1, argument2,...argumentn)

Returns an integer.

Boolean DB parameter expressions

A Boolean DB parameter expression resolves to a Boolean value of 1 or 0. The expression is enclosed in
quotation marks.
Note
Boolean DB parameter expressions are only supported for the PostgreSQL engine.

Syntax

"expression operator expression"

Both expressions must resolve to integers. An expression can be the following:

• integer constant
• DB parameter formula
• DB parameter function
• DB parameter variable

Boolean DB parameter expressions support the following inequality operators:

The greater than operator: >

Syntax

"expression > expression"

The less than operator: <

Syntax

"expression < expression"

The greater than or equal to operators: >=, =>

Syntax

"expression >= expression"

"expression => expression"

The less than or equal to operators: <=, =<

Syntax

"expression <= expression"

249
 Amazon Relational Database Service User Guide
Specifying DB parameters

"expression =< expression"

Example using a Boolean DB parameter expression

The following Boolean DB parameter expression example compares the result of a parameter formula
with an integer to modify the Boolean DB parameter wal_compression for a PostgreSQL DB instance.
The parameter expression compares the number of vCPUs with the value 2. If the number of vCPUs is
greater than 2, then the wal_compression DB parameter is set to true.

aws rds modify-db-parameter-group --db-parameter-group-name group-name \

--parameters "ParameterName=wal_compression,ParameterValue=\"{DBInstanceVCPU} > 2\" "

DB parameter log expressions

You can set an integer DB parameter value to a log expression. You enclose the expression in braces: {}.
For example:

{log(DBInstanceClassMemory/8187281418)*1000}

The log function represents log base 2. This example also uses the DBInstanceClassMemory formula
variable. See DB parameter formula variables (p. 247).
Note
Currently, you can't specify the MySQL innodb_log_file_size parameter with any value
other than an integer.

DB parameter value examples

These examples show using formulas, functions, and expressions for the values of DB parameters.
Note
DB Parameter functions are currently supported only in the console and aren't supported in the
AWS CLI.
Warning
Improperly setting parameters in a DB parameter group can have unintended adverse effects.
These might include degraded performance and system instability. Use caution when modifying
database parameters and back up your data before modifying your DB parameter group. Try out
parameter group changes on a test DB instance, created using point-in-time-restores, before
applying those parameter group changes to your production DB instances.

Example using the DB parameter function GREATEST

You can specify the GREATEST function in an Oracle processes parameter. Use it to set the number of
user processes to the larger of either 80 or DBInstanceClassMemory divided by 9,868,951.

GREATEST({DBInstanceClassMemory/9868951},80)

Example using the DB parameter function LEAST

You can specify the LEAST function in a MySQL max_binlog_cache_size parameter value. Use
it to set the maximum cache size a transaction can use in a MySQL instance to the lesser of 1 MB or
DBInstanceClass/256.

LEAST({DBInstanceClassMemory/256},10485760)

250
 Amazon Relational Database Service User Guide

Managing an Amazon RDS DB

instance
Following, you can find instructions for managing and maintaining your Amazon RDS DB instance.

Topics
• Stopping an Amazon RDS DB instance temporarily (p. 252)
• Starting an Amazon RDS DB instance that was previously stopped (p. 255)
• Modifying an Amazon RDS DB instance (p. 256)
• Maintaining a DB instance (p. 270)
• Upgrading a DB instance engine version (p. 277)
• Renaming a DB instance (p. 280)
• Rebooting a DB instance (p. 282)
• Working with read replicas (p. 284)
• Tagging Amazon RDS resources (p. 305)
• Working with Amazon Resource Names (ARNs) in Amazon RDS (p. 315)
• Working with storage for Amazon RDS DB instances (p. 322)
• Deleting a DB instance (p. 330)

251
 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.
Note
In some cases, a large amount of time is required to stop a DB instance. If you want to stop your
DB instance and restart it immediately, you can reboot the DB instance. For information about
rebooting a DB instance, see Rebooting a DB instance (p. 282).

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 for a single Availability Zone or for Multi-
AZ, 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.
Note
For a Multi-AZ deployment, a large amount of time might be required to stop a DB instance.
If you have at least one backup after a previous failover, then you can speed up the stop DB
instance operation by performing a reboot with failover operation before stopping the DB
instance.

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.

Stopping a DB instance removes pending actions, except for pending actions for the DB instance's option
group or DB parameter group.

Automated backups aren't created while a DB instance is stopped. Backups can be retained longer than
the backup retention period if a DB instance has been stopped. RDS doesn't include time spent in the
stopped state when the backup retention window is calculated.
Important
You can stop a DB instance for up to seven days. If you don't manually start your DB instance
after seven days, your DB instance is automatically started so that it doesn't fall behind any
required maintenance updates.

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

252
 Amazon Relational Database Service User Guide
Limitations

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.

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.

Public IP address
When you stop a DB instance, it retains its DNS endpoint. If you stop a DB instance that has a public IP
address, Amazon RDS releases its public IP address. When the DB instance is restarted, it has a different
public IP address.
Note
You should always connect to a DB instance using the DNS endpoint, not the IP address.

Stopping a DB instance temporarily

You can stop a DB using the AWS Management Console, the AWS CLI, or the RDS API.

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 Databases, and then choose the DB instance that you want to stop.
3. For Actions, choose Stop.
4. (Optional) In the Stop DB Instance window, choose Yes for Create Snapshot? and enter the
snapshot name for Snapshot name. 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.

AWS CLI
To stop a DB instance by using the AWS CLI, call the stop-db-instance command with the following
option:

253
 Amazon Relational Database Service User Guide
Stopping a DB instance

• --db-instance-identifier – the name of the DB instance.

Example

aws rds stop-db-instance --db-instance-identifier mydbinstance

RDS API
To stop a DB instance by using the Amazon RDS API, call the StopDBInstance operation with the
following parameter:

• DBInstanceIdentifier – the name of the DB instance.

254
 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. 252).

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.

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 Databases, and then choose the DB instance that you want to start.
3. For Actions, choose Start.

AWS CLI
To start a DB instance by using the AWS CLI, call the start-db-instance command with the following
option:

• --db-instance-identifier – The name of the DB instance.

Example

aws rds start-db-instance --db-instance-identifier mydbinstance

RDS API
To start a DB instance by using the Amazon RDS API, call the StartDBInstance operation with the
following parameter:

• DBInstanceIdentifier – The name of the DB instance.

255
 Amazon Relational Database Service User Guide
Modifying a DB instance

Modifying an Amazon RDS DB instance

You can change the settings of a DB instance to accomplish tasks such as adding additional storage or
changing the DB instance class. In this topic, you can find out how to modify an Amazon RDS DB instance
and learn about the settings for DB 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. Testing is especially important when upgrading
database versions.

Most modifications to a DB instance you can either apply immediately or defer 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.

Console
To modify 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 Databases, and then choose the DB instance that you want to
modify.
3. 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 DB
instances (p. 257).
5. When all the changes are as you want them, choose Continue and check the summary of
modifications.
6. (Optional) Choose Apply immediately to apply the changes immediately. Choosing this option
can cause an outage in some cases. For more information, see Using the Apply Immediately
setting (p. 257).
7. On the confirmation page, review your changes. If they are correct, choose Modify DB Instance to
save your changes.

Or choose Back to edit your changes or Cancel to cancel your changes.

AWS CLI
To modify a DB instance by using the AWS CLI, call the modify-db-instance command. Specify the DB
instance identifier and the values for the options that you want to modify. For information about each
option, see Settings for DB instances (p. 257).

Example

The following code modifies mydbinstance by setting the backup retention period to 1 week (7
days). The code enables deletion protection by using --deletion-protection. To disable deletion
protection, use --no-deletion-protection. The changes are applied during the next maintenance
window by using --no-apply-immediately. Use --apply-immediately to apply the changes
immediately. For more information, see Using the Apply Immediately setting (p. 257).

256
 Amazon Relational Database Service User Guide
Apply Immediately setting

For Linux, macOS, or Unix:

aws rds modify-db-instance \

--db-instance-identifier mydbinstance \
--backup-retention-period 7 \
--deletion-protection \
--no-apply-immediately

For Windows:

aws rds modify-db-instance ^

--db-instance-identifier mydbinstance ^
--backup-retention-period 7 ^
--deletion-protection ^
--no-apply-immediately

RDS API
To modify a DB instance by using the Amazon RDS API, call the ModifyDBInstance operation. Specify
the DB instance identifier, and the parameters for the settings that you want to modify. For information
about each parameter, see Settings for DB instances (p. 257).

Using the Apply Immediately setting

When you modify a DB instance, you can apply the changes immediately. To apply changes immediately,
you choose the Apply Immediately option in the AWS Management Console. Or you use the --apply-
immediately parameter when calling the AWS CLI or 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 the apply immediately option
can cause unexpected downtime.
When you choose to apply a change immediately, any pending modifications are also applied
immediately, instead of during the next maintenance window.
If you don't want a pending change to be applied in the next maintenance window, you
can modify the DB instance to revert the change. You can do this by using the AWS CLI and
specifying the --apply-immediately option.

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 Settings for
DB instances (p. 257).

Settings for DB instances

In the following table, you can find details about which settings you can and can't modify, when changes
can be applied, and whether the changes cause downtime for your DB instance.

You can modify a DB instance using the console, the modify-db-instance CLI command, or the
ModifyDBInstance RDS API operation.

257
 Amazon Relational Database Service User Guide
Available settings

Console setting and description CLI option and RDS When the change Downtime notes Supported
API parameter occurs DB
engines

Allocated storage CLI option: If you choose to An outage doesn't All DB

apply the change occur during this engines
The storage, in gibibytes, that --allocated- immediately, it change. Performance
you want to allocate for your DB storage occurs immediately. might be degraded
instance. You can only increase during the change.
the allocated storage. You can't RDS API parameter:
If you don't choose
reduce the allocated storage. to apply the change
AllocatedStorage immediately, it
You can't modify the storage of occurs during the
some older DB instances, or DB next maintenance
instances restored from older window.
DB snapshots. The Allocated
storage setting is disabled in the
console if your DB instance isn't
eligible. You can check whether
you can allocate more storage
by using the CLI command
describe-valid-db-instance-
modifications. This command
returns the valid storage options
for your DB instance.

You can't modify allocated

storage if the DB instance status
is storage-optimization or if
the allocated storage for the DB
instance has been modified in
the last six hours.

The maximum storage allowed

depends on your DB engine
and the storage type. For more
information, see Amazon RDS
DB instance storage (p. 40).

Auto minor version upgrade CLI option: The change occurs An outage doesn't Only
immediately. This occur during this MariaDB,
Yes to enable your DB instance --auto-minor- setting ignores the change. MySQL,
to receive preferred minor version- apply immediately Oracle,
DB engine version upgrades upgrade|--no- setting. and
automatically when they auto-minor- PostgreSQL
become available. Amazon version-upgrade
RDS performs automatic
minor version upgrades in RDS API parameter:
the maintenance window.
Otherwise, No. AutoMinorVersionUpgrade

For more information, see

Automatically upgrading the
minor engine version (p. 279).

Backup retention period CLI option: If you choose to An outage occurs if All DB
apply the change you change from 0 engines
to a nonzero value,

258
 Amazon Relational Database Service User Guide
Available settings

Console setting and description CLI option and RDS When the change Downtime notes Supported
API parameter occurs DB
engines
The number of days that --backup- immediately, it or from a nonzero
automatic backups are retained. retention-period occurs immediately. value to 0.
To disable automatic backups,
set the backup retention period RDS API parameter:If you don't choose This applies to both
to 0. to apply the change Single-AZ and Multi-
BackupRetentionPeriod
immediately, AZ DB instances.
For more information, see and you change
Working with backups (p. 334). the setting
from a nonzero
Note
value to another
If you use AWS Backup
nonzero value, the
to manage your
change is applied
backups, this option
asynchronously, as
doesn't appear. For
soon as possible.
information about AWS
Otherwise, the
Backup, see the AWS
change occurs
Backup Developer Guide.
during the next
maintenance
window.

Backup window CLI option: The change An outage doesn't All DB

is applied occur during this engines
The time range during which --preferred- asynchronously, as change.
automated backups of your backup-window soon as possible.
databases occur. The backup
window is a start time in RDS API parameter:
Universal Coordinated Time
(UTC), and a duration in hours. PreferredBackupWindow

For more information, see

Working with backups (p. 334).
Note
If you use AWS Backup
to manage your
backups, this option
doesn't appear. For
information about AWS
Backup, see the AWS
Backup Developer Guide.

Certificate authority CLI option: If you choose to An outage occurs All DB

apply the change during this change. engines
The certificate that you want to --ca- immediately, it
use for SSL/TLS connections. certificate- occurs immediately.
identifier
For more information, see Using If you don't choose
SSL/TLS to encrypt a connection RDS API parameter:to apply the change
to a DB instance (p. 1624). immediately, it
CACertificateIdentifier
occurs during the
next maintenance
window.

259
 Amazon Relational Database Service User Guide
Available settings

Console setting and description CLI option and RDS When the change Downtime notes Supported
API parameter occurs DB
engines

Copy tags to snapshots CLI option: The change occurs An outage doesn't All DB
immediately. This occur during this engines
If you have any DB instance tags, --copy-tags-to- setting ignores the change.
enable this option to copy them snapshot or --no- apply immediately
when you create a DB snapshot. copy-tags-to- setting.
snapshot
For more information,
see Tagging Amazon RDS RDS API parameter:
resources (p. 305).
CopyTagsToSnapshot

Database port CLI option: The change occurs The DB instance All DB
immediately. This is rebooted engines
The port that you want to use to --db-port-number setting ignores the immediately.
access the DB instance. apply immediately
RDS API parameter: setting.
The port value must not match
any of the port values specified DBPortNumber
for options in the option group
that is associated with the DB
instance.

For more information, see

Connecting to an Amazon RDS
DB instance (p. 168).

DB engine version CLI option: If you choose to An outage occurs All DB

apply the change during this change. engines
The version of the DB engine --engine-version immediately, it
that you want to use. Before you occurs immediately.
upgrade your production DB RDS API parameter:
instance, we recommend that If you don't choose
you test the upgrade process on EngineVersion to apply the change
a test DB instance to verify its immediately, it
duration and to validate your occurs during the
applications. next maintenance
window.
For more information, see
Upgrading a DB instance engine
version (p. 277).

DB instance class CLI option: If you choose to An outage occurs All DB

apply the change during this change. engines
The DB instance class that you --db-instance- immediately, it
want to use. class occurs immediately.

For more information, see DB RDS API parameter: If you don't choose
instance classes (p. 7). to apply the change
DBInstanceClass immediately, it
occurs during the
next maintenance
window.

260
 Amazon Relational Database Service User Guide
Available settings

Console setting and description CLI option and RDS When the change Downtime notes Supported
API parameter occurs DB
engines

DB instance identifier CLI option: If you choose to An outage occurs All DB

apply the change during this change. engines
The new DB instance identifier. --new-db- immediately, it
This value is stored as a instance- occurs immediately.
lowercase string. identifier
If you don't choose
For more information about RDS API parameter:to apply the change
the effects of renaming a DB immediately, it
instance, see Renaming a DB NewDBInstanceIdentifier
occurs during the
instance (p. 280). next maintenance
window.

DB parameter group CLI option: The parameter An outage doesn't All DB

group change occurs occur during this engines
The DB parameter group that --db-parameter- immediately. change. However,
you want associated with the DB group-name you must manually
instance. reboot the DB
RDS API parameter: instance before the
For more information, see new DB parameter
Working with DB parameter DBParameterGroupName
group is used by the
groups (p. 234). DB instance.

For more
information, see
Working with
DB parameter
groups (p. 234) and
Rebooting a DB
instance (p. 282).

Deletion protection CLI option: The change occurs An outage doesn't All DB
immediately. This occur during this engines
Enable deletion protection to --deletion- setting ignores the change.
prevent your DB instance from protection|-- apply immediately
being deleted. no-deletion- setting.
protection
For more information,
see Deleting a DB RDS API parameter:
instance (p. 330).
DeletionProtection

Enhanced Monitoring CLI option: The change occurs An outage doesn't All DB
immediately. This occur during this engines
Enable Enhanced Monitoring to --monitoring- setting ignores the change.
enable gathering metrics in real interval and -- apply immediately
time for the operating system monitoring-role- setting.
that your DB instance runs on. arn

For more information, see Using RDS API parameter:

Enhanced Monitoring (p. 477).
MonitoringInterval
and
MonitoringRoleArn

261
 Amazon Relational Database Service User Guide
Available settings

Console setting and description CLI option and RDS When the change Downtime notes Supported
API parameter occurs DB
engines

IAM DB authentication CLI option: If you choose to An outage doesn't Only

apply the change occur during this MySQL
Enable IAM DB authentication --enable- immediately, it change. and
to authenticate database users iam-database- occurs immediately. PostgreSQL
through IAM users and roles. authentication|--
no-enable- If you don't choose
For more information, iam-database- to apply the change
see IAM database authentication immediately, it
authentication for MySQL and occurs during the
PostgreSQL (p. 1650). RDS API parameter: next maintenance
window.
EnableIAMDatabaseAuthentication

Kerberos authentication CLI option: If you choose to A brief outage occurs Only
apply the change during this change. Microsoft
Choose the Active Directory to --domain and -- immediately, it SQL
move the DB instance to. The domain-iam-role- occurs immediately. Server,
directory must exist prior to name MySQL,
this operation. If a directory is If you don't choose Oracle,
already selected, you can specify RDS API parameter: to apply the change and
None to remove the DB instance immediately, it PostgreSQL
from its current directory. Domain and occurs during the
DomainIAMRoleName next maintenance
For more information, window.
see Kerberos
authentication (p. 1619).

License model CLI option: If you choose to An outage occurs Only

apply the change during this change. Microsoft
Choose bring-your-own-license --license-model immediately, it SQL
to use your license for Oracle. occurs immediately. Server
RDS API parameter: and
Choose license-included to use If you don't choose Oracle
the general license agreement LicenseModel to apply the change
for Microsoft SQL Server or immediately, it
Oracle. occurs during the
next maintenance
For more information, window.
see Licensing Microsoft
SQL Server on Amazon
RDS (p. 662) and Oracle
licensing options (p. 994).

Log exports CLI option: The change occurs An outage doesn't All DB
immediately. This occur during this engines
The types of database log --cloudwatch- setting ignores the change.
files to publish to Amazon logs-export- apply immediately
CloudWatch Logs. configuration setting.
For more information, see RDS API parameter:
Publishing database logs
to Amazon CloudWatch CloudwatchLogsExportConfiguration
Logs (p. 512).

262
 Amazon Relational Database Service User Guide
Available settings

Console setting and description CLI option and RDS When the change Downtime notes Supported
API parameter occurs DB
engines

Maintenance window CLI option: The change occurs If there are one All DB
immediately. This or more pending engines
The time range during which --preferred- setting ignores the actions that cause
system maintenance occurs. maintenance- apply immediately an outage, and
System maintenance includes window setting. the maintenance
upgrades, if applicable. The window is changed
maintenance window is a start RDS API parameter: to include the
time in Universal Coordinated current time, those
Time (UTC), and a duration in PreferredMaintenanceWindow
pending actions are
hours. applied immediately
and an outage
If you set the window to the occurs.
current time, there must be at
least 30 minutes between the
current time and the end of
the window to ensure that any
pending changes are applied.

For more information, see The

Amazon RDS maintenance
window (p. 274).

Multi-AZ deployment CLI option: If you choose to An outage doesn't All DB

apply the change occur during this engines
Yes to deploy your DB instance --multi-az|--no- immediately, it change.
in multiple Availability Zones. multi-az occurs immediately.
Otherwise, No.
RDS API parameter: If you don't choose
For more information, see to apply the change
High availability (Multi-AZ) for MultiAZ immediately, it
Amazon RDS (p. 53). occurs during the
next maintenance
window.

New master password CLI option: The change An outage doesn't All DB
is applied occur during this engines
The password for your master --master-user- asynchronously, as change.
user. The password must contain password soon as possible.
8–41 alphanumeric characters. This setting
RDS API parameter: ignores the apply
immediately setting.
MasterUserPassword

Option group CLI option: If you choose to An outage doesn't All DB

apply the change occur during this engines
The option group that you want --option-group- immediately, it change.
associated with the DB instance. name occurs immediately.

For more information, RDS API parameter: If you don't choose

see Working with option to apply the change
groups (p. 218). OptionGroupName immediately, it
occurs during the
next maintenance
window.

263
 Amazon Relational Database Service User Guide
Available settings

Console setting and description CLI option and RDS When the change Downtime notes Supported
API parameter occurs DB
engines

Performance Insights CLI option: The change occurs An outage doesn't All DB
immediately. This occur during this engines
Enable Performance Insights --enable- setting ignores the change.
to monitor your DB instance performance- apply immediately
load so that you can analyze insights|-- setting.
and troubleshoot your database no-enable-
performance. performance-
insights
Performance Insights isn't
available for some DB engine RDS API parameter:
versions and DB instance classes.
The Performance Insights EnablePerformanceInsights
section doesn't appear in the
console if it isn't available for
your DB instance.

For more information, see

Using Performance Insights on
Amazon RDS (p. 418).

Performance Insights Master CLI option: The change occurs An outage doesn't All DB
key immediately. This occur during this engines
--performance- setting ignores the change.
The AWS KMS key identifier for insights-kms- apply immediately
the customer master key (CMK) key-id setting.
for encryption of Performance
Insights data. The key identifier RDS API parameter:
is the Amazon Resource Name
(ARN), AWS KMS key identifier, PerformanceInsightsKMSKeyId
or the key alias for the CMK.

For more information, see

Enabling and disabling
Performance Insights (p. 421).

Performance Insights Retention CLI option: The change occurs An outage doesn't All DB
period immediately. This occur during this engines
--performance- setting ignores the change.
The amount of time, in days, insights- apply immediately
to retain Performance Insights retention-period setting.
data. Valid values are 7 or 731 (2
years). RDS API parameter:

For more information, see PerformanceInsightsRetentionPeriod

Enabling and disabling
Performance Insights (p. 421).

264
 Amazon Relational Database Service User Guide
Available settings

Console setting and description CLI option and RDS When the change Downtime notes Supported
API parameter occurs DB
engines

Processor features CLI option: If you choose to An outage occurs Only

apply the change during this change. Oracle
The number of CPU cores and --processor- immediately, it
the number of threads per core features and -- occurs immediately.
for the DB instance class of the use-default-
DB instance. processor- If you don't choose
features | -- to apply the change
For more information, see no-use-default- immediately, it
Configuring the processor for a processor- occurs during the
DB instance class (p. 20). features next maintenance
window.
RDS API parameter:

ProcessorFeatures
and
UseDefaultProcessorFeatures

Provisioned IOPS CLI option: If you choose to An outage doesn't All DB

apply the change occur during this engines
The new Provisioned IOPS --iops immediately, it change.
(I/O operations per second) occurs immediately.
value for the DB instance. RDS API parameter:
The setting is available only If you don't choose
if Provisioned IOPS (SSD) is Iops to apply the change
chosen for Storage type. immediately, it
occurs during the
For more information, next maintenance
see Provisioned IOPS SSD window.
storage (p. 42).

265
 Amazon Relational Database Service User Guide
Available settings

Console setting and description CLI option and RDS When the change Downtime notes Supported
API parameter occurs DB
engines

Public access CLI option: The change occurs An outage doesn't All DB
immediately. This occur during this engines
Publicly accessible to give the --publicly- setting ignores the change.
DB instance a public IP address, accessible|-- apply immediately
meaning that it's accessible no-publicly- setting.
outside the VPC. To be publicly accessible
accessible, the DB instance also
has to be in a public subnet in RDS API parameter:
the VPC.
PubliclyAccessible
Not publicly accessible to make
the DB instance accessible only
from inside the VPC.

For more information, see

Hiding a DB instance in a VPC
from the internet (p. 1716).

To connect to a DB instance
from outside of its Amazon
VPC, the DB instance must be
publicly accessible, access must
be granted using the inbound
rules of the DB instance's
security group, and other
requirements must be met. For
more information, see Can't
connect to Amazon RDS DB
instance (p. 1733).

If your DB instance is isn't

publicly accessible, you can
also use an AWS Site-to-Site
VPN connection or an AWS
Direct Connect connection
to access it from a private
network. For more information,
see Internetwork traffic
privacy (p. 1633).

Security group CLI option: The change An outage doesn't All DB

is applied occur during this engines
The VPC security group that you --vpc-security- asynchronously, as change.
want associated with the DB group-ids soon as possible.
instance. This setting
RDS API parameter: ignores the apply
For more information, see immediately setting.
Controlling access with security VpcSecurityGroupIds
groups (p. 1686).

266
 Amazon Relational Database Service User Guide
Available settings

Console setting and description CLI option and RDS When the change Downtime notes Supported
API parameter occurs DB
engines

Storage autoscaling CLI option: The change occurs An outage doesn't All DB
immediately. This occur during this engines
Enable storage autoscaling --max-allocated- setting ignores the change.
to enable Amazon RDS to storage apply immediately
automatically increase storage setting.
when needed to avoid having RDS API parameter:
your DB instance run out of
storage space. MaxAllocatedStorage

Use Maximum storage

threshold to set the upper
limit for Amazon RDS to
automatically increase storage
for your DB instance. The default
is 1,000 GiB.

For more information,

see Managing capacity
automatically with Amazon RDS
storage autoscaling (p. 323).

267
 Amazon Relational Database Service User Guide
Available settings

Console setting and description CLI option and RDS When the change Downtime notes Supported
API parameter occurs DB
engines

Storage type CLI option: If you choose to The following All DB

apply the change changes all result in engines
The storage type that you want --storage-type immediately, it a brief outage while
to use. occurs immediately. the process starts.
RDS API parameter: After that, you can
After Amazon RDS begins to If you don't choose use your database
modify your DB instance to StorageType to apply the change normally while the
change the storage size or immediately, it change takes place.
type, you can't submit another occurs during the
request to change the storage next maintenance • From General
size or type for six hours. window. Purpose (SSD) to
Magnetic.
For more information,
• From General
see Amazon RDS storage
types (p. 40). Purpose (SSD) to
Provisioned IOPS
(SSD). The outage
only happens if
the DB instance is
Single-AZ and you
are using a custom
parameter group.
There is no outage
for a Multi-AZ DB
instance.
• 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). The outage
only happens if
the DB instance is
Single-AZ and you
are using a custom
parameter group.
There is no outage
for a Multi-AZ DB
instance.

268
 Amazon Relational Database Service User Guide
Available settings

Console setting and description CLI option and RDS When the change Downtime notes Supported
API parameter occurs DB
engines

Subnet group CLI option: If you choose to An outage occurs All DB

apply the change during this change. engines
The subnet group for the --db-subnet- immediately, it
DB instance. You can use group-name occurs immediately.
this setting to move your DB
instance to a different VPC. If RDS API parameter:If you don't choose
your DB instance isn't in a VPC, to apply the change
you can use this setting to move DBSubnetGroupName immediately, it
your DB instance into a VPC. occurs during the
next maintenance
For more information, see window.
Amazon Virtual Private
Cloud VPCs and Amazon
RDS (p. 1705).

269
 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 hardware, 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.

Some maintenance items require that Amazon RDS take your DB instance offline for a short time.
Maintenance items that require a resource to be offline include 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.

Deferred DB instance modifications that you have chosen not to apply immediately are also applied
during the maintenance window. For example, you might choose to change the DB instance class
or parameter group during the maintenance window. Such modifications that you specify using
the pending reboot setting don't show up in the Pending maintenance list. For information about
modifying a DB instance, see Modifying an Amazon RDS DB instance (p. 256).

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 in the Maintenance column
for the DB instance on the Amazon RDS console, as shown following.

If no maintenance update is available for a DB instance, the column value is none for it.

If a maintenance update is available for a DB instance, the following column values are possible:

• required – The maintenance action will be applied to the resource and can't be deferred indefinitely.
• available – The maintenance action is available, but it will not be applied to the resource
automatically. You can apply it manually.
• next window – The maintenance action will be applied to the resource during the next maintenance
window.
• In progress – The maintenance action is in the process of being applied to the resource.

If an update is available, you can take one of the actions:

• If the maintenance value is next window, defer the maintenance items by choosing Defer upgrade
from Actions. You can't defer a maintenance action if it has already started.
• Apply the maintenance items immediately.

270
 Amazon Relational Database Service User Guide
Maintaining a DB instance

• 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 get a notice
from Amazon RDS indicating when the update will be performed. Other updates are marked as
available, and these you can defer indefinitely.

To take an action, choose the DB instance to show its details, then choose Maintenance & backups. The
pending maintenance items appear.

The maintenance window determines when pending operations start, but doesn't limit the total run
time of these operations. Maintenance operations aren't 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. 274).

271
 Amazon Relational Database Service User Guide
Applying updates

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.

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 Databases.
3. Choose the DB instance that has a required update.
4. For Actions, 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
choose Defer upgrade. You can't defer a maintenance action if it has already started.
To cancel a maintenance action, modify the DB instance and disable Auto minor version
upgrade.

AWS CLI
To apply a pending update to a DB instance, use the apply-pending-maintenance-action AWS CLI
command.

Example

For Linux, macOS, 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

Note
To defer a maintenance action, specify undo-opt-in for --opt-in-type. You can't specify
undo-opt-in for --opt-in-type if the maintenance action has already started.
To cancel a maintenance action, run the modify-db-instance AWS CLI command and specify --
no-auto-minor-version-upgrade.

To return a list of resources that have at least one pending update, use the describe-pending-
maintenance-actions AWS CLI command.

272
 Amazon Relational Database Service User Guide
Maintenance for Multi-AZ deployments

Example
For Linux, macOS, or Unix:

aws rds describe-pending-maintenance-actions \

--resource-identifier arn:aws:rds:us-west-2:001234567890:db:mysql-db

For Windows:

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 sample-
instance1 and sample-instance2 DB instances.

Example
For Linux, macOS, 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

RDS API
To apply an update to a DB instance, call the Amazon RDS API ApplyPendingMaintenanceAction
operation.

To return a list of resources that have at least one pending update, call the Amazon RDS API
DescribePendingMaintenanceActions operation.

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 applies 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.

273
 Amazon Relational Database Service User Guide
The maintenance window

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. 53).

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 Name Region Time Block

US East (Ohio) us-east-2 03:00–11:00 UTC

US East (N. Virginia) us-east-1 03:00–11:00 UTC

US West (N. California) us-west-1 06:00–14:00 UTC

US West (Oregon) us-west-2 06:00–14:00 UTC

Africa (Cape Town) af-south-1 03:00–11:00 UTC

Asia Pacific (Hong ap-east-1 06:00–14:00 UTC

Kong)

Asia Pacific (Mumbai) ap-south-1 06:00–14:00 UTC

Asia Pacific (Osaka) ap-northeast-3 22:00–23:59 UTC

Asia Pacific (Seoul) ap-northeast-2 13:00–21:00 UTC

Asia Pacific (Singapore) ap-southeast-1 14:00–22:00 UTC

Asia Pacific (Sydney) ap-southeast-2 12:00–20:00 UTC

Asia Pacific (Tokyo) ap-northeast-1 13:00–21:00 UTC

Canada (Central) ca-central-1 03:00–11:00 UTC

China (Beijing) cn-north-1 06:00–14:00 UTC

China (Ningxia) cn-northwest-1 06:00–14:00 UTC

Europe (Frankfurt) eu-central-1 21:00–05:00 UTC

274
 Amazon Relational Database Service User Guide
Adjusting the maintenance window for a DB instance

Region Name Region Time Block

Europe (Ireland) eu-west-1 22:00–06:00 UTC

Europe (London) eu-west-2 22:00–06:00 UTC

Europe (Paris) eu-west-3 23:59–07:29 UTC

Europe (Milan) eu-south-1 02:00–10:00 UTC

Europe (Stockholm) eu-north-1 23:00–07:00 UTC

Middle East (Bahrain) me-south-1 06:00–14:00 UTC

South America (São sa-east-1 00:00–08:00 UTC

Paulo)

AWS GovCloud (US- us-gov-east-1 17:00–01:00 UTC

East)

AWS GovCloud (US- us-gov-west-1 06:00–14:00 UTC

West)

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
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.

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 Databases, and then select the DB instance that you want to modify.
3. 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.

275
 Amazon Relational Database Service User Guide
Adjusting the maintenance window for a DB instance

Alternatively, choose Back to edit your changes, or choose Cancel to cancel your changes.

AWS 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, macOS, 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

RDS API
To adjust the preferred maintenance window, use the Amazon RDS API ModifyDBInstance operation
with the following parameters:

• DBInstanceIdentifier
• PreferredMaintenanceWindow

276
 Amazon Relational Database Service User Guide
Upgrading the engine version

Upgrading a DB instance engine version

Amazon RDS provides newer versions of each supported database engine so you can keep your
DB instance up-to-date. Newer versions can include bug fixes, security enhancements, and other
improvements for the database engine. When Amazon RDS supports a new version of a database engine,
you can choose how and when to upgrade your database DB instances.

There are two kinds of upgrades: major version upgrades and minor version upgrades. In general, a
major engine version upgrade can introduce changes that are not compatible with existing applications.
In contrast, a minor version upgrade includes only changes that are backward-compatible with existing
applications.

The version numbering sequence is specific to each database engine. For example, RDS for MySQL 5.7
and 8.0 are major engine versions and upgrading from any 5.7 version to any 8.0 version is a major
version upgrade. RDS for MySQL version 5.7.22 and 5.7.23 are minor versions and upgrading from 5.7.22
to 5.7.23 is a minor version upgrade.
Important
You can't modify a DB instance when it is being upgraded. During an upgrade, the DB instance
status is upgrading.

For more information about major and minor version upgrades for a specific DB engine, see the
following documentation for your DB engine:

• Upgrading the MariaDB DB engine (p. 605)

• Upgrading the Microsoft SQL Server DB engine (p. 673)
• Upgrading the MySQL DB engine (p. 857)
• Upgrading the Oracle DB engine (p. 1212)
• Upgrading the PostgreSQL DB engine for Amazon RDS (p. 1469)

For major version upgrades, you must manually modify the DB engine version through the AWS
Management Console, AWS CLI, or RDS API. For minor version upgrades, you can manually modify the
engine version, or you can choose to enable auto minor version upgrades.

Topics
• Manually upgrading the engine version (p. 277)
• Automatically upgrading the minor engine version (p. 279)

Manually upgrading the engine version

To manually upgrade the engine version of a DB instance, you can use the AWS Management Console,
the AWS CLI, or the RDS API.

Console
To upgrade the engine version of a DB instance 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 Databases, and then choose the DB instance that you want to
upgrade.
3. Choose Modify. The Modify DB Instance page appears.

277
 Amazon Relational Database Service User Guide
Manually upgrading the engine version

4. For DB engine version, choose the new version.

5. Choose Continue and check the summary of modifications.
6. To apply the changes immediately, choose Apply immediately. Choosing this option can cause an
outage in some cases. For more information, see Using the Apply Immediately setting (p. 257).
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.

AWS CLI
To upgrade the engine version of a DB instance, use the 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.

For information about valid engine versions, use the AWS CLI describe-db-engine-versions command.
• --allow-major-version-upgrade – to upgrade the major version.
• --no-apply-immediately – to apply changes during the next maintenance window. To apply
changes immediately, use --apply-immediately.

Example

For Linux, macOS, or Unix:

aws rds modify-db-instance \

--db-instance-identifier mydbinstance \
--engine-version new_version \
--allow-major-version-upgrade \
--no-apply-immediately

For Windows:

aws rds modify-db-instance ^

--db-instance-identifier mydbinstance ^
--engine-version new_version ^
--allow-major-version-upgrade ^
--no-apply-immediately

RDS 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. For information about
valid engine versions, use the DescribeDBEngineVersions operation.
• AllowMajorVersionUpgrade – whether to allow a major version upgrade. To do so, set the value to
true.
• 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.

278
 Amazon Relational Database Service User Guide
Automatically upgrading the minor engine version

Automatically upgrading the minor engine version

A minor engine version is an update to a DB engine version within a major engine version. For example, a
major engine version might be 9.6 with the minor engine versions 9.6.11 and 9.6.12 within it.

If you want Amazon RDS to upgrade the DB engine version of a database automatically, you can enable
auto minor version upgrades for the database.

When Amazon RDS designates a minor engine version as the preferred minor engine version, each
database that meets both of the following conditions is upgraded to the minor engine version
automatically:

• The database is running a minor version of the DB engine that is lower than the preferred minor
engine version.
• The database has auto minor version upgrade enabled.

You can control whether auto minor version upgrade is enabled for a DB instance when you perform the
following tasks:

• Creating a DB instance (p. 147)

• Modifying a DB instance (p. 256)
• Creating a read replica (p. 289)
• Restoring a DB instance from a snapshot (p. 355)
• Restoring a DB instance to a specific time (p. 395)
• Importing a DB instance from Amazon S3 (p. 875) (for a MySQL backup on Amazon S3)

When you perform these tasks, you can control whether auto minor version upgrade is enabled for the
DB instance in the following ways:

• Using the console, set the Auto minor version upgrade option.
• Using the AWS CLI, set the --auto-minor-version-upgrade|--no-auto-minor-version-
upgrade option.
• Using the RDS API, set the AutoMinorVersionUpgrade parameter.

To determine whether a maintenance update, such as a DB engine version upgrade, is available for
your DB instance, you can use the console, AWS CLI, or RDS API. You can also upgrade the DB engine
version manually and adjust the maintenance window. For more information, see Maintaining a DB
instance (p. 270).
Important
If you plan to migrate an RDS for PostgreSQL DB instance to an Aurora PostgreSQL DB cluster
in the near future, we strongly recommend that you disable auto minor version upgrades
for the DB instance early in the migration planning phase. Migration to Aurora PostgreSQL
might be delayed if the RDS for PostgreSQL version isn't yet supported by Aurora PostgreSQL.
For information about Aurora PostgreSQL versions, see Engine versions for Amazon Aurora
PostgreSQL.

279
 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-db-
instance command, or the Amazon RDS API ModifyDBInstance action. Renaming a DB instance can
have far-reaching effects. The following is a list of considerations 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 primary DB instance, the events and metrics associated with the primary DB instance 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.

Note
A DB instance is an isolated database environment running in the cloud. A DB instance can host
multiple databases, or a single Oracle database with multiple schemas. For information about
changing a database name, see the documentation for your DB engine.

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 point-in-time recovery (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 primary 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 primary DB instance to a name that indicates it is no longer the primary DB instance as
described later in this topic.
3. Create a new primary 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 primary DB instance.
4. Associate any read replicas with the new primary DB instance.

If you delete the old primary DB instance, you are responsible for deleting any unwanted DB snapshots
of the old primary DB instance.

For information about promoting a read replica, see Promoting a read replica to be a standalone DB
instance (p. 291).

280
 Amazon Relational Database Service User Guide
Renaming to replace an existing DB instance

Console
To rename 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 Databases.
3. Choose the DB instance that you want to rename.
4. Choose Modify.
5. In Settings, enter a new name for DB instance identifier.
6. Choose Continue.
7. To apply the changes immediately, choose Apply immediately. Choosing this option can cause an
outage in some cases. For more information, see Modifying an Amazon RDS DB instance (p. 256).
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.

AWS CLI
To rename a DB instance, use the AWS CLI command modify-db-instance. Provide the current --db-
instance-identifier value and --new-db-instance-identifier parameter with the new name
of the DB instance.

Example

For Linux, macOS, 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

RDS API
To rename a DB instance, call Amazon RDS API operation ModifyDBInstance with the following
parameters:

• DBInstanceIdentifier — existing name for the instance

• NewDBInstanceIdentifier — new name for the instance

281
 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.
Note
If a DB instance isn't using the latest changes to its associated DB parameter group, the AWS
Management Console shows the DB parameter group with a status of pending-reboot. The
pending-reboot parameter groups status doesn't result in an automatic reboot during the next
maintenance window. To apply the latest parameter changes to that DB instance, manually
reboot the DB instance. For more information about parameter groups, see Working with DB
parameter groups (p. 234).

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, you can perform the reboot 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 (AZ) 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
(Multi-AZ) for Amazon RDS (p. 53).
Note
When you force a failover from one Availability Zone to another when you reboot, the
Availability Zone change might not be reflected in the AWS Management Console, and in calls to
the AWS CLI and RDS API, for several minutes.

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 maintenance-
window action.

The time required to reboot your DB instance depends on the crash recovery process, database activity
at the time of reboot, and the behavior of your specific DB 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.

For a DB instance with read replicas, you can reboot the source DB instance and its read replicas
independently. After a reboot completes, replication resumes automatically.

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 Databases, and then choose the DB instance that you want to reboot.
3. For Actions, choose Reboot.

The Reboot DB Instance page appears.

4. (Optional) Choose Reboot with failover? to force a failover from one AZ to another.
5. Choose Reboot to reboot your DB instance.

282
 Amazon Relational Database Service User Guide
Rebooting a DB instance

Alternatively, choose Cancel.

AWS CLI
To reboot a DB instance by using the AWS CLI, call the reboot-db-instance command.

Example Simple reboot

For Linux, macOS, or Unix:

aws rds reboot-db-instance \

--db-instance-identifier mydbinstance

For Windows:

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, macOS, 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

RDS API
To reboot a DB instance by using the Amazon RDS API, call the RebootDBInstance operation.

283
 Amazon Relational Database Service User Guide
Working with read replicas

Working with read replicas

Amazon RDS uses the MariaDB, Microsoft SQL Server, MySQL, Oracle, 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. The source DB instance becomes the primary DB instance. Updates made to the primary
DB instance are asynchronously copied to the read replica. You can reduce the load on your primary 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 read-heavy 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 primary DB instance. The read replica operates as a DB instance that allows only

284
 Amazon Relational Database Service User Guide
Working with read replicas

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.
Note
The Oracle DB engine supports replica databases in mounted mode. A mounted replica doesn't
accept user connections and so can't serve a read-only workload. The primary use for mounted
replicas is cross-Region disaster recovery. For more information, see Working with Oracle
replicas for Amazon RDS (p. 1122).

In some cases, a read replica resides in a different AWS Region from its primary DB instance. In these
cases, Amazon RDS sets up a secure communications channel between the primary DB instance and
the read replica. Amazon RDS establishes any AWS security configurations needed to enable the secure
channel, such as adding security group entries. For more information about cross-Region read replicas,
see Creating a read replica in a different AWS Region (p. 296).

You can configure a read replica for a DB instance that also has a standby replica configured for high
availability. Replication with the standby replica is synchronous, and the standby replica can't serve read
traffic.

For more information about high availability and standby replicas, see High availability (Multi-AZ) for
Amazon RDS (p. 53).

285
 Amazon Relational Database Service User Guide
Overview

Read replicas are supported by the MariaDB, Microsoft SQL Server, MySQL, Oracle, and PostgreSQL DB
engines. In this section, you can find general information about using read replicas with all of these
engines. For information about using read replicas with a specific engine, see the following sections:

• Working with MariaDB read replicas (p. 612)

• Working with read replicas for Microsoft SQL Server in Amazon RDS (p. 703)
• Working with MySQL read replicas (p. 903)
• Working with Oracle replicas for Amazon RDS (p. 1122)
• Working with PostgreSQL read replicas in Amazon RDS (p. 1480)

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. In some cases, your source DB instance
might not be able to take I/O requests, for example due to I/O suspension for backups or scheduled
maintenance. In these cases, 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 production DB instance.
• Implementing disaster recovery. You can promote a read replica to a standalone instance as a disaster
recovery solution if the primary DB instance fails.

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 Source DB instance storage Read replica storage type
type allocation options

PIOPS 100 GiB–32 TiB PIOPS, GP2, Standard

GP2 100 GiB–32 TiB PIOPS, GP2, Standard

GP2 <100 GiB GP2, Standard

Standard 100 GiB–6 TiB PIOPS, GP2, Standard

Standard <100 GiB GP2, Standard

Note
When you increase the allocated storage of a read replica, it must be by at least 10 percent. If
you try to increase the value by less than 10 percent, you get an error.

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. For MariaDB and MySQL you can create a read
replica from an existing read replica. For example, from ReadReplica1, you can create a new read

286
 Amazon Relational Database Service User Guide
Overview

replica, such as ReadReplica2. For Oracle, PostgreSQL, and SQL Server, you can't create a read replica
from an existing read replica.

If you no longer need read replicas, you can explicitly delete them using the same mechanisms for
deleting a DB instance. If you delete a source DB instance without deleting its read replicas in the same
AWS Region, each read replica is promoted to a standalone DB instance. For information about deleting
a DB instance, see Deleting a DB instance (p. 330). For information about read replica promotion,
see Promoting a read replica to be a standalone DB instance (p. 291). If you have cross-Region read
replicas, see Cross-Region replication considerations (p. 301) for considerations related to deleting the
source for a cross-Region read replica.

Differences between read replicas for different DB engines

Because Amazon RDS DB engines implement replication differently, there are several significant
differences you should know about, as shown in the following table.

Feature or MySQL and MariaDB Oracle PostgreSQL SQL Server

behavior

What is the Logical replication. Physical replication. Physical replication. Physical

replication replication.
method?

How are RDS for MySQL and If a primary DB PostgreSQL has The Virtual
transaction RDS for MariaDB keep instance has no the parameter Log File
logs purged? any binary logs that cross-Region read wal_keep_segments (VLF) of the
haven't been applied. replicas, Amazon that dictates how transaction
RDS for Oracle keeps many write ahead log file on
a minimum of two log (WAL) files are the primary
hours of transaction kept to provide data replica can
logs on the source to the read replicas. be truncated
DB instance. Logs The parameter value after it is
are purged from the specifies the number no longer
source DB instance of logs to keep. required for
after two hours or the secondary
after the archive replicas.
log retention hours
setting has passed, The VLF
whichever is longer. can only
Logs are purged be marked
from the read replica as inactive
after the archive when the
log retention hours log records
setting has passed have been
only if they have been hardened in
successfully applied the replicas.
to the database. Regardless
of how fast
In some cases, a the disk
primary DB instance subsystems
might have one or are in the
more cross-Region primary
read replicas. If replica, the
so, Amazon RDS transaction
for Oracle keeps log will keep
the transaction the VLFs until
logs on the source the slowest

287
 Amazon Relational Database Service User Guide
Overview

Feature or MySQL and MariaDB Oracle PostgreSQL SQL Server

behavior
DB instance until replica has
they have been hardened it.
transmitted and
applied to all cross-
Region read replicas.

For information about

setting archive log
retention hours, see
Retaining archived
redo logs (p. 1071).

Can a replica Yes. You can enable No. An Oracle read No. A PostgreSQL No. A SQL
be made the MySQL or replica is a physical read replica is a Server read
writable? MariaDB read replica copy, and Oracle physical copy, and replica is
to be writable. doesn't allow for PostgreSQL doesn't a physical
writes in a read allow for a read copy and also
replica. You can replica to be made doesn't allow
promote the read writable. for writes.
replica to make You can
it writable. The promote the
promoted read replica read replica
has the replicated to make it
data to the point writable. The
when the request was promoted
made to promote it. read replica
has the
replicated
data up to
the point
when the
request was
made to
promote it.

Can backups Yes. You can enable No. You can't create Yes, you can create No. You
be performed automatic backups on manual snapshots a manual snapshot can't create
on the a MySQL or MariaDB of Amazon RDS for of a PostgreSQL read manual
replica? read replica. Oracle read replicas replica, but you can't snapshots
or enable automatic enable automatic of Amazon
backups for them. backups. RDS for
SQL Server
read replicas
or enable
automatic
backups for
them.

288
 Amazon Relational Database Service User Guide
Creating a read replica

Feature or MySQL and MariaDB Oracle PostgreSQL SQL Server

behavior

Can you Yes. MySQL version Yes. Redo log data is No. PostgreSQL Yes. Redo log
use parallel 5.6 and later and all always transmitted has a single process data is always
replication? supported MariaDB in parallel from the handling replication. transmitted
versions allow for primary database to in parallel
parallel replication all of its read replicas. from the
threads. primary
database to
all of its read
replicas.

Can you No. Yes. The primary No. No.

maintain a use for mounted
replica in a replicas is cross-
mounted Region disaster
rather than recovery. An Active
a read-only Data Guard license
state? isn't required for
mounted replicas. For
more information, see
Working with Oracle
replicas for Amazon
RDS (p. 1122).

Creating a read replica

You can create a read replica from an existing DB instance using the AWS Management Console, AWS CLI,
or RDS API. You create a read replica by specifying SourceDBInstanceIdentifier, which is the DB
instance identifier of the source DB instance that you want to replicate from.

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.
Note
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 RDS for MySQL version 5.6 and
later read replica, first create the read replica, then modify the read replica to enable automatic backups.
Note
Within an AWS Region, we strongly recommend that you create all read replicas in the same
virtual private cloud (VPC) based on Amazon VPC as the source DB instance. If you create a read
replica in a different VPC from the source DB instance, classless inter-domain routing (CIDR)

289
 Amazon Relational Database Service User Guide
Creating a read replica

ranges can overlap between the replica and the RDS system. CIDR overlap makes the replica
unstable, which can negatively impact applications connecting to it. If you receive an error when
creating the read replica, choose a different destination DB subnet group. For more information,
see Working with a DB instance in a VPC (p. 1714).
You can't create a read replica in a different AWS account from the source DB instance.

Console
To create a read replica from a source 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 Databases.
3. Choose the DB instance that you want to use as the source for a read replica.
4. For Actions, choose Create read replica.
5. For DB instance identifier, enter a name for the read replica.
6. Choose your instance specifications. We recommend that you use the same DB instance class and
storage type as the source DB instance for the read replica.
7. For Multi-AZ deployment, choose Yes to create a standby of your replica in another Availability
Zone for failover support for the replica.
Note
Creating your read replica as a Multi-AZ DB instance is independent of whether the source
database is a Multi-AZ DB instance.
8. To create an encrypted read replica:

a. Choose Enable encryption.

b. For Master key, choose the AWS Key Management Service (AWS KMS) key identifier of the
customer master key (CMK).

Note
The source DB instance must be encrypted. To learn more about encrypting the source DB
instance, see Encrypting Amazon RDS resources (p. 1620).
9. Choose other options, such as storage autoscaling.
10. Choose Create read replica.

AWS CLI
To create a read replica from a source DB instance, use the AWS CLI command create-db-instance-
read-replica. This example also enables storage autoscaling.

Example

For Linux, macOS, or Unix:

aws rds create-db-instance-read-replica \

--db-instance-identifier myreadreplica \
--source-db-instance-identifier mydbinstance \
--max-allocated-storage 1000

For Windows:

aws rds create-db-instance-read-replica ^

290
 Amazon Relational Database Service User Guide
Promoting a read replica

--db-instance-identifier myreadreplica ^
--source-db-instance-identifier mydbinstance ^
--max-allocated-storage 1000

RDS API
To create a read replica from a source MySQL, MariaDB, Oracle, PostgreSQL, or SQL Server DB instance,
call the Amazon RDS API CreateDBInstanceReadReplica operation with the following required
parameters:

• DBInstanceIdentifier
• SourceDBInstanceIdentifier

Promoting a read replica to be a standalone DB

instance
You can promote a read replica into a standalone DB instance. When you promote a read replica, the DB
instance is rebooted before it becomes available.

291
 Amazon Relational Database Service User Guide
Promoting a read replica

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 primary 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

292
 Amazon Relational Database Service User Guide
Promoting a read replica

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 primary 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. To do this, first create a read replica and then
monitor the primary DB instance for failures. In the event of a failure, do the following:
1. Promote the 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 option group and the
parameter group of the former read replica. The promotion process can take several minutes or longer
to complete, depending on the size of the read replica. After you promote the read replica to a new DB
instance, it's just like any other DB instance. For example, you can create read replicas from the new DB
instance 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 number 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, you can't promote a read replica to
a standalone instance when it has the backing-up status. If you have enabled backups on your read
replica, configure the automated backup window so that daily backups don't 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 primary 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 primary 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 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 primary DB instance.
3. Promote the read replica by using the Promote 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 (p. 256) and High availability (Multi-AZ) for Amazon
RDS (p. 53).

293
 Amazon Relational Database Service User Guide
Monitoring read replication

Console

To promote a read replica to a standalone 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 Databases.

The Databases pane appears. Each read replica shows Replica in the Role column.
3. Choose the read replica that you want to promote.
4. For Actions, choose Promote.
5. On the Promote Read Replica page, enter the backup retention period and the backup window for
the newly promoted DB instance.
6. When the settings are as you want them, choose Continue.
7. On the acknowledgment page, choose Promote Read Replica.

AWS CLI
To promote a read replica to a standalone DB instance, use the AWS CLI promote-read-replica
command.

Example

For Linux, macOS, or Unix:

aws rds promote-read-replica \

--db-instance-identifier myreadreplica

For Windows:

aws rds promote-read-replica ^

--db-instance-identifier myreadreplica

RDS API
To promote a read replica to a standalone DB instance, call the Amazon RDS API PromoteReadReplica
operation with the required parameter DBInstanceIdentifier.

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, choose the name of the read replica in the list of instances in the Amazon RDS console.

294
 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 operation.

The status of a read replica can be one of the following:

• replicating – The read replica is replicating successfully.

• replication degraded (SQL Server only) – Replicas are receiving data from the primary instance, but
one or more databases might be not getting updates. This can occur, for example, when a replica is in
the process of setting up newly created databases.

The status doesn't transition from replication degraded to error, unless an error occurs during
the degraded state.
• 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. 912).
• terminated (MariaDB, MySQL, or PostgreSQL only) – Replication is terminated. This occurs if
replication is stopped for more than 30 consecutive days, either manually or due to a replication error.
In this case, Amazon RDS terminates replication between the primary DB instance and all read replicas.
Amazon RDS does this to prevent increased storage requirements on the source 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 (MariaDB or MySQL 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. 969) 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. 969) stored procedure and replication is stopped because the
stop point was reached.

Monitoring replication lag

You can monitor replication lag in Amazon CloudWatch by viewing the Amazon RDS ReplicaLag
metric.

295
 Amazon Relational Database Service User Guide
Creating a read replica in a different AWS Region

For MySQL and MariaDB, the ReplicaLag metric reports the value of the Seconds_Behind_Master
field of the SHOW SLAVE STATUS command. 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 nontransactional 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 primary DB instance. If the
ReplicaLag metric returns -1, then replication is currently not active. ReplicaLag = -1 is equivalent
to Seconds_Behind_Master = NULL.

For Oracle, the ReplicaLag metric is the sum of the Apply Lag value and the difference between the
current time and the apply lag's DATUM_TIME value. The DATUM_TIME value is the last time the read
replica received data from its source DB instance. For more information, see V$DATAGUARD_STATS in
the Oracle documentation.

For SQL Server, the ReplicaLag metric is the maximum lag of databases that have fallen behind, in
seconds. For example, if you have two databases that lag 5 seconds and 10 seconds, respectively, then
ReplicaLag is 10 seconds. The ReplicaLag metric returns the value of the following query.

select ag.name name, MAX(hdrs.secondary_lag_seconds) max_lag from

sys.dm_hadr_database_replica_state

For more information, see secondary_lag_seconds in the Microsoft documentation.

ReplicaLag returns -1 if RDS can't determine the lag, such as during replica setup, or when the read
replica is in the error state.
Note
New databases aren't included in the lag calculation until they are accessible on the read replica.

For PostgreSQL, the ReplicaLag metric returns the value of the following query.

SELECT extract(epoch from now() - pg_last_xact_replay_timestamp()) AS slave_lag

PostgreSQL versions 9.5.2 and later use 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 cross-Region read replica is
lagging significantly.

For more information about monitoring a DB instance with CloudWatch, see Monitoring Amazon RDS
metrics with Amazon CloudWatch (p. 546).

Creating a read replica in a different AWS Region

With Amazon RDS, you can create a MariaDB, MySQL, Oracle, or PostgreSQL read replica in a different
AWS Region from the source DB instance. Creating a cross-Region read replica isn't supported for SQL
Server on Amazon RDS.

296
 Amazon Relational Database Service User Guide
Creating a read replica in a different AWS Region

You create a read replica in a different AWS Region 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 read replica in a different AWS Region from the source instance is similar to creating a replica
in the same AWS Region. You can use the AWS Management Console, run the create-db-instance-
read-replica command, or call the CreateDBInstanceReadReplica API operation.
Note
To create an encrypted read replica in a different AWS Region from the source DB instance, the
source DB instance must be encrypted.

Creating a cross-Region read replica

The following procedures show how to create a read replica from a source MariaDB, MySQL, Oracle, or
PostgreSQL DB instance in a different AWS Region.

Console

You can create a read replica across AWS Regions using the AWS Management Console.

To create a read replica across AWS 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 Databases.
3. Choose the MariaDB, MySQL, Oracle, or PostgreSQL DB instance that you want to use as the source
for a read replica.
4. For Actions, choose Create read replica.

297
 Amazon Relational Database Service User Guide
Creating a read replica in a different AWS Region

5. For DB instance identifier, enter a name for the read replica.

6. Choose the Destination Region.
7. 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.
8. To create an encrypted read replica in another AWS Region:

a. Choose Enable encryption.

b. For Master key, choose the AWS Key Management Service (AWS KMS) key identifier of the
customer master key (CMK) of the destination AWS Region.

Note
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. 1620).
9. Choose other options, such as storage autoscaling.
10. Choose Create read replica.

AWS CLI

To create a read replica from a source MySQL, MariaDB, Oracle, 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
(destination Region) 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 this
example:

arn:aws:rds:us-east-1:123456789012:db:mydbinstance

For information about ARNs, see Working with Amazon Resource Names (ARNs) in Amazon
RDS (p. 315).

To create a read replica in a different AWS Region from 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 required for creating a read replica in another AWS Region:

• --region – The destination AWS Region where the read replica is created.
• --source-db-instance-identifier – The DB instance identifier for the source DB instance.
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 in --region.
• --db-instance-identifier – The identifier for the read replica in the destination AWS Region.

Example of a cross-Region read replica

The following code creates a read replica in the US West (Oregon) Region from a source DB instance in
the US East (N. Virginia) Region.

For Linux, macOS, or Unix:

aws rds create-db-instance-read-replica \

--db-instance-identifier myreadreplica \
--region us-west-2 \

298
 Amazon Relational Database Service User Guide
Creating a read replica in a different AWS Region

--source-db-instance-identifier arn:aws:rds:us-east-1:123456789012:db:mydbinstance

For Windows:

aws rds create-db-instance-read-replica ^

--db-instance-identifier myreadreplica ^
--region us-west-2 ^
--source-db-instance-identifier arn:aws:rds:us-east-1:123456789012:db:mydbinstance

The following parameters are also required for creating an encrypted read replica in another AWS
Region:

• --source-region – The AWS Region of the source DB instance.

If --source-region isn't specified, you must specify a --pre-signed-url value. A presigned URL
is a URL that contains a Signature Version 4 signed request for the CreateDBInstanceReadReplica
operation that is called in the source AWS Region. For more information about presigned URLs, see
CreateDBInstanceReadReplica.
• --kms-key-id – The AWS KMS key identifier for the customer master key (CMK) to use to encrypt the
read replica in the destination AWS Region.

Example of an encrypted cross-Region read replica

The following code creates an encrypted read replica in the US West (Oregon) Region from a source DB
instance in the US East (N. Virginia) Region.

For Linux, macOS, or Unix:

aws rds create-db-instance-read-replica \

--db-instance-identifier myreadreplica \
--region us-west-2 \
--source-db-instance-identifier arn:aws:rds:us-east-1:123456789012:db:mydbinstance \
--source-region us-east-1 \
--kms-key-id my-us-west-2-key

For Windows:

aws rds create-db-instance-read-replica ^

--db-instance-identifier myreadreplica ^
--region us-west-2 ^
--source-db-instance-identifier arn:aws:rds:us-east-1:123456789012:db:mydbinstance ^
--source-region us-east-1 ^
--kms-key-id my-us-west-2-key

RDS API

To create a read replica from a source MySQL, MariaDB, Oracle, 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 (destination
Region) and specify the 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 from the source DB instance, you can use
the Amazon RDS API CreateDBInstanceReadReplica operation from the destination AWS Region. To
create an encrypted read replica in another AWS Region, you must specify a value for PreSignedURL.

299
 Amazon Relational Database Service User Guide
Creating a read replica in a different AWS Region

PreSignedURL should contain a request for the CreateDBInstanceReadReplica operation 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:mydbinstance

For information about ARNs, see Working with Amazon Resource Names (ARNs) in Amazon
RDS (p. 315).

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%253DCreateDBInstanceReadReplica
%2526DestinationRegion%253Dus-east-1
%2526KmsKeyId%253Dmy-us-east-1-key
%2526SourceDBInstanceIdentifier%253Darn%25253Aaws%25253Ards%25253Aus-
west-2%123456789012%25253Adb%25253Amydbinstance
%2526SignatureMethod%253DHmacSHA256
%2526SignatureVersion%253D4%2526SourceDBInstanceIdentifier%253Darn%25253Aaws
%25253Ards%25253Aus-west-2%25253A123456789012%25253Ainstance%25253Amydbinstance
%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-amz-
content-sha256%253Bx-amz-date
%2526X-Amz-Signature
%253D255a0f17b4e717d3b67fad163c3ec26573b882c03a65523522cf890a67fca613
&DBInstanceIdentifier=myreadreplica
&SourceDBInstanceIdentifier=arn:aws:rds:us-east-1:123456789012:db:mydbinstance
&Version=2012-01-15
&SignatureVersion=2
&SignatureMethod=HmacSHA256
&Timestamp=2012-01-20T22%3A06%3A23.624Z
&AWSAccessKeyId=<AWS Access Key ID>
&Signature=<Signature>

How Amazon RDS does cross-Region replication

Amazon RDS uses the following process to create a cross-Region read replica. Depending on the AWS
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.
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:<InstanceID>-<timestamp>, where <InstanceID>
is the identifier of the source instance, and <timestamp> is the date and time the copy started.

300
 Amazon Relational Database Service User Guide
Creating a read replica in a different AWS Region

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 information about replication lag time, see Monitoring read replication (p. 294).

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 AWS Regions:

• You can only replicate between AWS Regions when using the following Amazon RDS DB instances:
• MariaDB (all versions).
• MySQL version 5.6 and later.
• Oracle Enterprise Edition (EE) engine version 12.1.0.2.v10 and higher 12.1 versions, and all versions
of 12.2, 18c, and 19c.

An Active Data Guard license is required. For information about limitations for Oracle cross-Region
read replicas, see Replica requirements for Oracle (p. 1122).
• PostgreSQL (all versions).
• A source DB instance can have cross-Region read replicas in multiple AWS Regions.
• 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 replicate between the AWS GovCloud (US-East) and AWS GovCloud (US-West) Regions, but
not into or out of AWS GovCloud (US).
• 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. This lag time comes from the longer network channels between regional
data centers.
• 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 AWS Region
• In a VPC from a source DB instance that isn't in a VPC
• That isn't 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.
• The read replica uses the default DB parameter group for the specified DB engine.
• The read replica uses the default security group.

301
 Amazon Relational Database Service User Guide
Creating a read replica in a different AWS Region

• For MariaDB, MySQL, and Oracle DB instances, when the source for a cross-Region read replica is
deleted, the read replica is promoted.
• For PostgreSQL DB instances, when the source for a cross-Region read replica is deleted, the
replication status of the read replica is set to terminated. The read replica isn't promoted.

Requesting a cross-Region read replica

To communicate with the source Region to request the creation of a cross-Region read replica, the
requester (IAM role or IAM user) must have access to the source DB instance and the source Region.

Certain conditions in the requester's IAM policy can cause the request to fail. The following examples
assume that the source DB instance is in US East (Ohio) and the read replica is created in US East (N.
Virginia). These examples show conditions in the requester's IAM policy that cause the request to fail:

• The requester's policy has a condition for aws:RequestedRegion.

...
"Effect": "Allow",
"Action": "rds:CreateDBInstanceReadReplica",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:RequestedRegion": "us-east-1"
}
}

The request fails because the policy doesn't allow access to the source Region. For a successful request,
specify both the source and destination Regions.

...
"Effect": "Allow",
"Action": "rds:CreateDBInstanceReadReplica",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:RequestedRegion": [
"us-east-1",
"us-east-2"
]
}
}

• The requester's policy doesn't allow access to the source DB instance.

...
"Effect": "Allow",
"Action": "rds:CreateDBInstanceReadReplica",
"Resource": "arn:aws:rds:us-east-1:123456789012:db:myreadreplica"
...

For a successful request, specify both the source instance and the replica.

...
"Effect": "Allow",
"Action": "rds:CreateDBInstanceReadReplica",
"Resource": [
"arn:aws:rds:us-east-1:123456789012:db:myreadreplica",
"arn:aws:rds:us-east-2:123456789012:db:mydbinstance"
]

302
 Amazon Relational Database Service User Guide
Creating a read replica in a different AWS Region

...

• The requester's policy denies aws:ViaAWSService.

...
"Effect": "Allow",
"Action": "rds:CreateDBInstanceReadReplica",
"Resource": "*",
"Condition": {
"Bool": {"aws:ViaAWSService": "false"}
}

Communication with the source Region is made by RDS on the requester's behalf. For a successful
request, don't deny calls made by AWS services.
• The requester's policy has a condition for aws:SourceVpc or aws:SourceVpce.

These requests might fail because when RDS makes the call to the remote Region, it isn't from the
specified VPC or VPC endpoint.

If you need to use one of the previous conditions that would cause a request to fail, you can include a
second statement with aws:CalledVia in your policy to make the request succeed. For example, you
can use aws:CalledVia with aws:SourceVpce as shown here:

...
"Effect": "Allow",
"Action": "rds:CreateDBInstanceReadReplica",
"Resource": "*",
"Condition": {
"Condition" : {
"ForAnyValue:StringEquals" : {
"aws:SourceVpce": "vpce-1a2b3c4d"
}
}
},
{
"Effect": "Allow",
"Action": [
"rds:CreateDBInstanceReadReplica"
],
"Resource": "*",
"Condition": {
"ForAnyValue:StringEquals": {
"aws:CalledVia": [
"rds.amazonaws.com"
]
}
}
}

For more information, see Policies and permissions in IAM in the IAM User Guide.

Authorizing the read replica

After a cross-Region DB read replica creation request returns success, RDS starts the replica creation in
the background. An authorization for RDS to access the source DB instance is created. This authorization
links the source DB instance to the read replica, and allows RDS to copy only to the specified read replica.

The authorization is verified by RDS using the rds:CrossRegionCommunication permission in the

service-linked IAM role. If the replica is authorized, RDS communicates with the source Region and
completes the replica creation.

303
 Amazon Relational Database Service User Guide
Creating a read replica in a different AWS Region

RDS doesn't have access to DB instances that weren't authorized previously by a

CreateDBInstanceReadReplica request. The authorization is revoked when read replica creation
completes.

RDS uses the service-linked role to verify the authorization in the source Region. If you delete the
service-linked role during the replication creation process, the creation fails.

For more information, see Using service-linked roles in the IAM User Guide.

Using AWS Security Token Service credentials

Session tokens from the global AWS Security Token Service (AWS STS) endpoint are valid only in AWS
Regions that are enabled by default (commercial Regions). If you use credentials from the assumeRole
API operation in AWS STS, use the regional endpoint if the source Region is an opt-in Region. Otherwise,
the request fails. This happens because your credentials must be valid in both Regions, which is true for
opt-in Regions only when the regional AWS STS endpoint is used.

To use the global endpoint, make sure that it's enabled for both Regions in the operations. Set the global
endpoint to Valid in all AWS Regions in the AWS STS account settings.

The same rule applies to credentials in the presigned URL parameter.

For more information, see Managing AWS STS in an AWS Region in the IAM User Guide.

Cross-Region replication costs

The data transferred for cross-Region replication incurs Amazon RDS data transfer charges. These cross-
Region 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 AWS Region.
• For each data modification made in the source databases, Amazon RDS transfers data from the source
AWS Region to the read replica AWS 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 read-
replica-1. You aren't 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.

304
 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. You can use the tags
to add your own notations about database instances, snapshots, Aurora clusters, and so on. Doing
so can help you to document your Amazon RDS resources. You can also use the tags with automated
maintenance procedures.

In particular, you can use these tags with IAM policies to manage access to Amazon RDS resources and to
control what actions can be applied to the Amazon RDS resources. You can also use these tags to track
costs by grouping expenses for similarly tagged resources.

You can tag the following Amazon RDS resources:

• 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

Topics
• Overview of Amazon RDS resource tags (p. 305)
• Using tags for access control with IAM (p. 306)
• Using tags to produce detailed billing reports (p. 306)
• Adding, listing, and removing tags (p. 306)
• Using the AWS Tag Editor (p. 309)
• Copying tags to DB instance snapshots (p. 309)
• Tutorial: Use tags to specify which DB instances to stop (p. 310)
• Using tags to enable backups in AWS Backup (p. 312)

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.

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 50 tags, or it can be empty. If you add a tag to an Amazon

305
 Amazon Relational Database Service User Guide
Using tags for access control with IAM

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.

• 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.

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. 315).

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.

Using tags for access control with IAM

You can use tags with IAM policies to manage access to Amazon RDS resources and to control what
actions can be applied to the Amazon RDS resources.

For information on managing access to tagged resources with IAM policies, see Identity and access
management in Amazon RDS (p. 1634).

Using tags to produce detailed billing reports

You can also use tags to track costs by grouping expenses for similarly tagged 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.
Note
You can add a tag to a snapshot, however, your bill will not reflect this grouping.

Adding, listing, and removing tags

The following procedures show how to perform typical tagging operations on resources related to DB
instances.

306
 Amazon Relational Database Service User Guide
Adding, listing, and removing tags

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.

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 Databases.
Note
To filter the list of DB instances in the Databases pane, enter a text string for Filter
databases. Only DB instances that contain the string appear.
3. Choose 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. Enter a value for Tag key and Value.

7. To add another tag, you can choose Add another Tag and enter 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 Databases.
Note
To filter the list of DB instances in the Databases pane, enter a text string in the Filter
databases box. Only DB instances that contain the string appear.
3. Choose the name of the DB instance to show its details.
4. In the details section, scroll down to the Tags section.

307
 Amazon Relational Database Service User Guide
Adding, listing, and removing tags

5. Choose the tag you want to delete.

6. Choose Delete, and then choose Delete in the Delete tags window.

AWS 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-to-
resource.
• 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 remove-
tags-from-resource.

To learn more about how to construct the required ARN, see Constructing an ARN for Amazon
RDS (p. 315).

RDS 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. 315).

When working with XML using the Amazon RDS API, tags use the following schema:

<Tagging>
<TagSet>
<Tag>
<Key>Project</Key>
<Value>Trinity</Value>
</Tag>
<Tag>
<Key>User</Key>
<Value>Jones</Value>
</Tag>
</TagSet>
</Tagging>

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.

308
 Amazon Relational Database Service User Guide
Using the AWS Tag Editor

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, white-
space, '_', '.', '/', '=', '+', '-' (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.

Using the AWS Tag Editor

You can browse and edit the tags on your RDS resources in the AWS Management Console by using the
AWS Tag editor. For more information, see Tag Editor in the AWS Resource Groups User Guide.

Copying tags to DB instance snapshots

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 operation) 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

309
 Amazon Relational Database Service User Guide
Tutorial: Use tags to specify which DB instances to stop

snapshot using the AWS CLI create-db-snapshot command (or the CreateDBSnapshot
Amazon RDS API operation) you can then add tags as described later in this topic.

Tutorial: Use tags to specify which DB instances to

stop
Suppose that you're creating a number of DB instances in a development or test environment. You
need to keep all of these DB instances for several days. Some of the DB instances run tests overnight.
Other DB instances can be stopped overnight and started again the next day. The following example
shows how to assign a tag to those DB instances that are suitable to stop overnight. Then the example
shows how a script can detect which DB instances have that tag and then stop those DB instances. In this
example, the value portion of the key-value pair doesn't matter. The presence of the stoppable tag
signifies that the DB instance has this user-defined property.

To specify which DB instances to stop

1. Determine the ARN of a DB instance that you want to designate as stoppable.

The commands and APIs for tagging work with ARNs. That way, they can work seamlessly across
AWS Regions, AWS accounts, and different types of resources that might have identical short
names. You can specify the ARN instead of the DB instance ID in CLI commands that operate on
DB instances. Substitute the name of your own DB instances for dev-test-db-instance. In
subsequent commands that use ARN parameters, substitute the ARN of your own DB instance. The
ARN includes your own AWS account ID and the name of the AWS Region where your DB instance is
located.

$ aws rds describe-db-instances --db-instance-id dev-test-db-instance \

--query "*[].{DBInstance:DBInstanceArn}" --output text
arn:aws:rds:us-east-1:123456789102:db:dev-test-db-instance

2. Add the tag stoppable to this DB instance.

The name for this tag is chosen by you. Using a tag like this is an alternative to devising a naming
convention that encodes all the relevant information in the name of the DB instance (or other types
of resources). Because this example treats the tag as an attribute that is either present or absent, it
omits the Value= part of the --tags parameter.

$ aws rds add-tags-to-resource \

--resource-name arn:aws:rds:us-east-1:123456789102:db:dev-test-db-instance \
--tags Key=stoppable

3. Confirm that the tag is present in the DB instance.

These commands retrieve the tag information for the DB instance in JSON format and in plain tab-
separated text.

$ aws rds list-tags-for-resource \

--resource-name arn:aws:rds:us-east-1:123456789102:db:dev-test-db-instance
{
"TagList": [
{
"Key": "stoppable",
"Value": ""

}
]
}
aws rds list-tags-for-resource \

310
 Amazon Relational Database Service User Guide
Tutorial: Use tags to specify which DB instances to stop

--resource-name arn:aws:rds:us-east-1:123456789102:db:dev-test-db-instance --output

text
TAGLIST stoppable

4. To stop all the DB instances that are designated as stoppable, prepare a list of all your DB
instances. Loop through the list and check if each DB instance is tagged with the relevant attribute.

This Linux example uses shell scripting to save the list of DB instance ARNs to a temporary file and
then perform CLI commands for each DB instance.

$ aws rds describe-db-instances --query "*[].[DBInstanceArn]" --output text >/tmp/

db_instance_arns.lst
$ for arn in $(cat /tmp/db_instance_arns.lst)
do
match="$(aws rds list-tags-for-resource --resource-name $arn --output text | grep
stoppable)"
if [[ ! -z "$match" ]]
then
echo "DB instance $arn is tagged as stoppable. Stopping it now."
# Note that you need to get the DB instance identifier from the ARN.
dbid=$(echo $arn | sed -e 's/.*://')
aws rds stop-db-instance --db-instance-identifier $dbid
fi
done

DB instance arn:arn:aws:rds:us-east-1:123456789102:db:dev-test-db-instance is tagged as

stoppable. Stopping it now.
{
"DBInstance": {
"DBInstanceIdentifier": "dev-test-db-instance",
"DBInstanceClass": "db.t3.medium",
...

You can run a script like this at the end of each day to make sure that nonessential DB instances are
stopped. You might also schedule a job using a utility such as cron to perform such a check each night,
in case some DB instances were left running by mistake. In that case, you might fine-tune the command
that prepares the list of DB instances to check. The following command produces a list of your DB
instances, but only the ones in available state. The script can ignore DB instances that are already
stopped, because they will have different status values such as stopped or stopping.

$ aws rds describe-db-instances \

--query '*[].{DBInstanceArn:DBInstanceArn,DBInstanceStatus:DBInstanceStatus}|[?
DBInstanceStatus == `available`]|[].{DBInstanceArn:DBInstanceArn}' \
--output text
arn:aws:rds:us-east-1:123456789102:db:db-instance-2447
arn:aws:rds:us-east-1:123456789102:db:db-instance-3395
arn:aws:rds:us-east-1:123456789102:db:dev-test-db-instance
arn:aws:rds:us-east-1:123456789102:db:pg2-db-instance

Tip
Once you're familiar with the general procedure of assigning tags and finding DB instances that
have those tags, you can use the same technique to reduce costs in other ways. For example, in
this scenario with DB instances used for development and testing, you might designate some DB
instances to be deleted at the end of each day, or to have their DB instances changed to a small
DB instance classes during times of expected low usage.

311
 Amazon Relational Database Service User Guide
Enabling backups

Using tags to enable backups in AWS Backup

AWS Backup is a fully managed backup service that makes it easy to centralize and automate the backup
of data across AWS services in the cloud and on premises. You can manage backups of your Amazon RDS
DB instances in AWS Backup.

To enable backups in AWS Backup, you use resource tagging to associate your DB instance with a backup
plan.

This example assumes that you have already created a backup plan in AWS Backup. You use exactly the
same tag for your DB instance that is in your backup plan, as shown in the following figure.

For more information about AWS Backup, see the AWS Backup Developer Guide.

You can assign a tag to a DB instance using the AWS Management Console, the AWS CLI, or the RDS API.
The following examples are for the console and CLI.

Console

To assign 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 Databases.
3. Choose the link for the DB instance to which you want to assign a tag.
4. On the database details page, choose the Tags tab.
5. Under Tags, choose Add tags.
6. Under Add tags:

a. For Tag key, enter BackupPlan.

b. For Value, enter Test.
c. Choose Add.

The result is shown under Tags.

312
 Amazon Relational Database Service User Guide
Enabling backups

CLI
To assign a tag to a DB instance

• Use the following CLI command:

For Linux, macOS, or Unix:

aws rds add-tags-to-resource \

--resource-name arn:aws:rds:us-east-1:123456789012:db:new-orcl-db \
--tags Key=BackupPlan,Value=Test

For Windows:

aws rds add-tags-to-resource ^

--resource-name arn:aws:rds:us-east-1:123456789012:db:new-orcl-db ^
--tags Key=BackupPlan,Value=Test

The add-tags-to-resource CLI command returns no output.

To confirm that the DB instance is tagged

• Use the following CLI command:

For Linux, macOS, or Unix:

aws rds list-tags-for-resource \

--resource-name arn:aws:rds:us-east-1:123456789012:db:new-orcl-db

For Windows:

aws rds list-tags-for-resource ^

--resource-name arn:aws:rds:us-east-1:123456789012:db:new-orcl-db

The list-tags-for-resource CLI command returns the following output:

313
 Amazon Relational Database Service User Guide
Enabling backups

{
"TagList": [
{
"Key": "BackupPlan",
"Value": "Test"
}
]
}

314
 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>:<account number>:<resourcetype>:<name>

Region Region Endpoint Protocol

Name

US East us-east-2 rds.us-east-2.amazonaws.com HTTPS

(Ohio)
rds-fips.us-east-2.amazonaws.com HTTPS

US East (N. us-east-1 rds.us-east-1.amazonaws.com HTTPS

Virginia)
rds-fips.us-east-1.amazonaws.com HTTPS

US us-west-1 rds.us-west-1.amazonaws.com HTTPS

West (N.
California) rds-fips.us-west-1.amazonaws.com HTTPS

US West us-west-2 rds.us-west-2.amazonaws.com HTTPS

(Oregon)
rds-fips.us-west-2.amazonaws.com HTTPS

Africa af-south-1 rds.af-south-1.amazonaws.com HTTPS

(Cape
Town)

Asia ap-east-1 rds.ap-east-1.amazonaws.com HTTPS

Pacific
(Hong
Kong)

Asia ap- rds.ap-south-1.amazonaws.com HTTPS

Pacific south-1
(Mumbai)

Asia ap- rds.ap-northeast-3.amazonaws.com HTTPS

Pacific northeast-3
(Osaka)

Asia ap- rds.ap-northeast-2.amazonaws.com HTTPS

Pacific northeast-2
(Seoul)

315
 Amazon Relational Database Service User Guide
Constructing an ARN

Region Region Endpoint Protocol

Name

Asia ap- rds.ap-southeast-1.amazonaws.com HTTPS

Pacific southeast-1
(Singapore)

Asia ap- rds.ap-southeast-2.amazonaws.com HTTPS

Pacific southeast-2
(Sydney)

Asia ap- rds.ap-northeast-1.amazonaws.com HTTPS

Pacific northeast-1
(Tokyo)

Canada ca- rds.ca-central-1.amazonaws.com HTTPS

(Central) central-1
rds-fips.ca-central-1.amazonaws.com HTTPS

China cn-north-1 rds.cn-north-1.amazonaws.com.cn HTTPS

(Beijing)

China cn- rds.cn-northwest-1.amazonaws.com.cn HTTPS

(Ningxia) northwest-1

Europe eu- rds.eu-central-1.amazonaws.com HTTPS

(Frankfurt) central-1

Europe eu-west-1 rds.eu-west-1.amazonaws.com HTTPS

(Ireland)

Europe eu-west-2 rds.eu-west-2.amazonaws.com HTTPS

(London)

Europe eu- rds.eu-south-1.amazonaws.com HTTPS

(Milan) south-1

Europe eu-west-3 rds.eu-west-3.amazonaws.com HTTPS

(Paris)

Europe eu-north-1 rds.eu-north-1.amazonaws.com HTTPS

(Stockholm)

Middle me- rds.me-south-1.amazonaws.com HTTPS

East south-1
(Bahrain)

South sa-east-1 rds.sa-east-1.amazonaws.com HTTPS

America
(São
Paulo)

AWS us-gov- rds.us-gov-east-1.amazonaws.com HTTPS

GovCloud east-1
(US-East)

AWS us-gov- rds.us-gov-west-1.amazonaws.com HTTPS

GovCloud west-1
(US-West)

316
 Amazon Relational Database Service User Guide
Constructing an ARN

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:<region>:<account>:db:<name>

For example:

arn:aws:rds:us-east-2:123456789012:db:my-mysql-instance-1

Event subscription arn:aws:rds:<region>:<account>:es:<name>

For example:

arn:aws:rds:us-east-2:123456789012:es:my-subscription

DB option group arn:aws:rds:<region>:<account>:og:<name>

For example:

arn:aws:rds:us-east-2:123456789012:og:my-og

DB parameter group arn:aws:rds:<region>:<account>:pg:<name>

For example:

arn:aws:rds:us-east-2:123456789012:pg:my-param-enable-logs

Reserved DB instance arn:aws:rds:<region>:<account>:ri:<name>

For example:

arn:aws:rds:us-east-2:123456789012:ri:my-reserved-
postgresql

DB security group arn:aws:rds:<region>:<account>:secgrp:<name>

For example:

arn:aws:rds:us-east-2:123456789012:secgrp:my-public

Automated DB snapshot arn:aws:rds:<region>:<account>:snapshot:rds:<name>

For example:

arn:aws:rds:us-east-2:123456789012:snapshot:rds:my-mysql-
db-2019-07-22-07-23

Manual DB snapshot arn:aws:rds:<region>:<account>:snapshot:<name>

For example:

317
 Amazon Relational Database Service User Guide
Getting an existing ARN

Resource type ARN format

arn:aws:rds:us-east-2:123456789012:snapshot:my-mysql-db-
snap

DB subnet group arn:aws:rds:<region>:<account>:subgrp:<name>

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.

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
Configuration tab of the DB instance details, as shown following.

318
 Amazon Relational Database Service User Guide
Getting an existing ARN

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

describe-certificates CertificateArn

319
 Amazon Relational Database Service User Guide
Getting an existing ARN

AWS CLI command ARN property

describe-db-parameter-groups DBParameterGroupArn

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

For example, the following AWS CLI command gets the ARN for a DB instance.

Example

For Linux, macOS, or Unix:

aws rds describe-db-instances \

--db-instance-identifier DBInstanceIdentifier \
--region us-west-2 \
--query "*[].{DBInstanceIdentifier:DBInstanceIdentifier,DBInstanceArn:DBInstanceArn}"

For Windows:

aws rds describe-db-instances ^

--db-instance-identifier DBInstanceIdentifier ^
--region us-west-2 ^
--query "*[].{DBInstanceIdentifier:DBInstanceIdentifier,DBInstanceArn:DBInstanceArn}"

The output of that command is like the following:

[
{
"DBInstanceArn": "arn:aws:rds:us-west-2:account_id:db:instance_id",
"DBInstanceIdentifier": "instance_id"
}
]

RDS API
To get an ARN for a particular RDS resource, you can call the following RDS API operations and use the
ARN properties shown following.

RDS API operation ARN property

DescribeEventSubscriptions EventSubscriptionArn

DescribeCertificates CertificateArn

320
 Amazon Relational Database Service User Guide
Getting an existing ARN

RDS API operation ARN property

DescribeDBParameterGroups DBParameterGroupArn

DescribeDBInstances DBInstanceArn

DescribeDBSecurityGroups DBSecurityGroupArn

DescribeDBSnapshots DBSnapshotArn

DescribeEvents SourceArn

DescribeReservedDBInstances ReservedDBInstanceArn

DescribeDBSubnetGroups DBSubnetGroupArn

DescribeOptionGroups OptionGroupArn

321
 Amazon Relational Database Service User Guide
Working with storage

Working with storage for Amazon RDS DB

instances
To specify how you want your data stored in Amazon RDS, choose 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. 40).

Topics
• Increasing DB instance storage capacity (p. 322)
• Managing capacity automatically with Amazon RDS storage autoscaling (p. 323)
• Modifying SSD storage settings for Provisioned IOPS (p. 328)

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). For information about storage limits, see Amazon RDS DB instance storage (p. 40).
Note
Scaling storage for Amazon RDS for Microsoft SQL Server DB instances is supported only for
General Purpose SSD or Provisioned IOPS SSD storage types.

To monitor the amount of free storage for your DB instance so you can respond when necessary, we
recommend that you create an Amazon CloudWatch alarm. For more information on setting CloudWatch
alarms, see Using CloudWatch alarms.

In most cases, scaling storage doesn't require any outage and doesn't degrade performance of the
server. After you modify the storage size for a DB instance, the status of the DB instance is storage-
optimization. The DB instance is fully operational after a storage modification.
Note
You can't make further storage modifications until six (6) hours after storage optimization has
completed on the instance.

However, a special case is if you have a SQL Server DB instance and haven't modified the storage
configuration since November 2017. In this case, 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 storage-optimization state. Performance might be degraded during storage
optimization.
Note
You can't reduce the amount of storage for a DB instance after storage has been allocated.
When you increase the allocated storage, it must be by at least 10 percent. If you try to increase
the value by less than 10 percent, you get an error.

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 Databases.

322
 Amazon Relational Database Service User Guide
Managing capacity automatically with storage autoscaling

3. Choose the DB instance that you want to modify.

4. Choose Modify.
5. Enter a new value for Allocated storage. It must be greater than the current value.

6. Choose Continue to move to the next screen.

7. Choose Apply immediately in the Scheduling of modifications section to apply the storage
changes to the DB instance immediately. Or choose Apply during the next scheduled maintenance
window to apply the changes during the next maintenance window.
8. When the settings are as you want them, choose Modify DB instance.

AWS CLI
To increase the storage for a DB instance, use the AWS CLI command modify-db-instance. Set the
following parameters:

• --allocated-storage – Amount of storage to be allocated for the DB instance, in gibibytes.

• --apply-immediately – Use --apply-immediately to change to the new storage type
immediately. Or use --no-apply-immediately (the default) to apply storage changes during the
next maintenance window. An immediate outage occurs when the changes are applied.

For more information about storage, see Amazon RDS DB instance storage (p. 40).

Amazon RDS API

To increase storage for a DB instance, use the Amazon RDS API operation ModifyDBInstance. Set the
following parameters:

• AllocatedStorage – Amount of storage to be allocated for the DB instance, in gibibytes.

• ApplyImmediately – Set this option to True to apply scaling changes immediately. Set this option
to False (the default) to apply scaling changes during the next maintenance window. An immediate
outage occurs when the changes are applied.

For more information about storage, see Amazon RDS DB instance storage (p. 40).

Managing capacity automatically with Amazon RDS

storage autoscaling
If your workload is unpredictable, you can enable storage autoscaling for an Amazon RDS DB instance. To
do so, you can use the Amazon RDS console, the Amazon RDS API, or the AWS CLI.

323
 Amazon Relational Database Service User Guide
Managing capacity automatically with storage autoscaling

For example, you might use this feature for a new mobile gaming application that users are adopting
rapidly. In this case, a rapidly increasing workload might exceed the available database storage. To avoid
having to manually scale up database storage, you can use Amazon RDS storage autoscaling.

With storage autoscaling enabled, when Amazon RDS detects that you are running out of free database
space it automatically scales up your storage. Amazon RDS starts a storage modification for an
autoscaling-enabled DB instance when these factors apply:

• Free available space is less than 10 percent of the allocated storage.

• The low-storage condition lasts at least five minutes.
• At least six hours have passed since the last storage modification.

The additional storage is in increments of whichever of the following is greater:

• 5 GiB
• 10 percent of currently allocated storage
• Storage growth prediction for 7 hours based on the FreeStorageSpace metrics change in the past
hour. For more information on metrics, see Monitoring with Amazon CloudWatch.

The maximum storage threshold is the limit that you set for autoscaling the DB instance. You can't set
the maximum storage threshold for autoscaling-enabled instances to a value greater than the maximum
allocated storage.

For example, SQL Server Standard Edition on db.m5.xlarge has a default allocated storage for the
instance of 20 GiB (the minimum) and a maximum allocated storage of 16,384 GiB. The default
maximum storage threshold for autoscaling is 1,000 GiB. If you use this default, the instance doesn't
autoscale above 1,000 GiB. This is true even though the maximum allocated storage for the instance is
16,384 GiB.
Note
We recommend that you carefully choose the maximum storage threshold based on usage
patterns and customer needs. If there are any aberrations in the usage patterns, the maximum
storage threshold can prevent scaling storage to an unexpectedly high value when autoscaling
predicts a very high threshold. After a DB instance has been autoscaled, its allocated storage
can't be reduced.

The following limitations apply to storage autoscaling:

• Autoscaling doesn't occur if the maximum storage threshold would be exceeded by the storage
increment.
• Autoscaling can't completely prevent storage-full situations for large data loads, because further
storage modifications can't be made until six hours after storage optimization has completed on the
instance. If you perform a large data load, and autoscaling doesn't provide enough space, the database
might remain in the storage-full state for several hours. This can harm the database.
• If you start a storage scaling operation at the same time that Amazon RDS starts an autoscaling
operation, your storage modification takes precedence. The autoscaling operation is canceled.
• Autoscaling can't be used with magnetic storage.
• Autoscaling can't be used with the following previous-generation instance classes that have less than 6
TiB of orderable storage: db.m3.large, db.m3.xlarge, and db.m3.2xlarge.
• Autoscaling operations aren't logged by AWS CloudTrail. For more information on CloudTrail, see
Working with AWS CloudTrail and Amazon RDS (p. 564).

Although automatic scaling helps you to increase storage on your Amazon RDS DB instance dynamically,
you should still configure the initial storage for your DB instance to an appropriate size for your typical
workload.

324
 Amazon Relational Database Service User Guide
Managing capacity automatically with storage autoscaling

Enabling storage autoscaling for a new DB instance

When you create a new Amazon RDS DB instance, you can choose whether to enable storage autoscaling.
You can also set an upper limit on the storage that Amazon RDS can allocate for the DB instance.
Note
When you clone an Amazon RDS DB instance that has storage autoscaling enabled, that setting
isn't automatically inherited by the cloned instance. The new DB instance has the same amount
of allocated storage as the original instance. You can turn storage autoscaling on again for the
new instance if the cloned instance continues to increase its storage requirements.

Console

To enable storage autoscaling for a new 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 upper-right corner of the Amazon RDS console, choose the AWS Region where you want to
create the DB instance.
3. In the navigation pane, choose Databases.
4. Choose Create database. On the Select engine page, choose your database engine and specify your
DB instance information as described in Getting started with Amazon RDS (p. 73).
5. In the Storage autoscaling section, set the Maximum storage threshold value for the DB instance.
6. Specify the rest of your DB instance information as described in Getting started with Amazon
RDS (p. 73).

AWS CLI

To enable storage autoscaling for a new DB instance, use the AWS CLI command create-db-
instance. Set the following parameter:

• --max-allocated-storage – Turns on storage autoscaling and sets the upper limit on storage size,
in gibibytes.

To verify that Amazon RDS storage autoscaling is available for your DB instance, use the AWS CLI
describe-valid-db-instance-modifications command. To check based on the instance class
before creating an instance, use the describe-orderable-db-instance-options command. Check
the following field in the return value:

• SupportsStorageAutoscaling – Indicates whether the DB instance or instance class supports

storage autoscaling.

For more information about storage, see Amazon RDS DB instance storage (p. 40).

Amazon RDS API

To enable storage autoscaling for a new DB instance, use the Amazon RDS API operation
CreateDBInstance. Set the following parameter:

• MaxAllocatedStorage – Turns on Amazon RDS storage autoscaling and sets the upper limit on
storage size, in gibibytes.

To verify that Amazon RDS storage autoscaling is available for your DB instance, use the Amazon
RDS API DescribeValidDbInstanceModifications operation for an existing instance, or the

325
 Amazon Relational Database Service User Guide
Managing capacity automatically with storage autoscaling

DescribeOrderableDBInstanceOptions operation before creating an instance. Check the following

field in the return value:

• SupportsStorageAutoscaling – Indicates whether the DB instance supports storage autoscaling.

For more information about storage, see Amazon RDS DB instance storage (p. 40).

Changing the storage autoscaling settings for a DB instance

You can turn storage autoscaling on for an existing Amazon RDS DB instance. You can also change the
upper limit on the storage that Amazon RDS can allocate for the DB instance.

Console

To change the storage autoscaling 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 Databases.
3. Choose the DB instance that you want to modify, and choose Modify. The Modify DB instance page
appears.
4. Change the storage limit in the Autoscaling section. For more information, see Modifying an
Amazon RDS DB instance (p. 256).
5. When all the changes are as you want them, choose Continue and check your modifications.
6. On the confirmation page, review your changes. If they're correct, choose Modify DB Instance to
save your changes. If they aren't correct, choose Back to edit your changes or Cancel to cancel your
changes.

Changing the storage autoscaling limit occurs immediately. This setting ignores the Apply
immediately setting.

AWS CLI
To change the storage autoscaling settings for a DB instance, use the AWS CLI command modify-db-
instance. Set the following parameter:

• --max-allocated-storage – Sets the upper limit on storage size, in gibibytes. If the value is
greater than the --allocated-storage parameter, storage autoscaling is turned on. If the value is
the same as the --allocated-storage parameter, storage autoscaling is turned off.

To verify that Amazon RDS storage autoscaling is available for your DB instance, use the AWS CLI
describe-valid-db-instance-modifications command. To check based on the instance class
before creating an instance, use the describe-orderable-db-instance-options command. Check
the following field in the return value:

• SupportsStorageAutoscaling – Indicates whether the DB instance supports storage autoscaling.

For more information about storage, see Amazon RDS DB instance storage (p. 40).

Amazon RDS API

To change the storage autoscaling settings for a DB instance, use the Amazon RDS API operation
ModifyDBInstance. Set the following parameter:

• MaxAllocatedStorage – Sets the upper limit on storage size, in gibibytes.

326
 Amazon Relational Database Service User Guide
Managing capacity automatically with storage autoscaling

To verify that Amazon RDS storage autoscaling is available for your DB instance, use the Amazon
RDS API DescribeValidDbInstanceModifications operation for an existing instance, or the
DescribeOrderableDBInstanceOptions operation before creating an instance. Check the following
field in the return value:

• SupportsStorageAutoscaling – Indicates whether the DB instance supports storage autoscaling.

For more information about storage, see Amazon RDS DB instance storage (p. 40).

Turning off storage autoscaling for a DB instance

If you no longer need Amazon RDS to automatically increase the storage for an Amazon RDS DB
instance, you can turn off storage autoscaling. After you do, you can still manually increase the amount
of storage for your DB instance.

Console

To turn off storage autoscaling 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 Databases.
3. Choose the DB instance that you want to modify and choose Modify. The Modify DB instance page
appears.
4. Clear the Enable storage autoscaling check box in the Storage autoscaling section. For more
information, see Modifying an Amazon RDS DB instance (p. 256).
5. When all the changes are as you want them, choose Continue and check the modifications.
6. On the confirmation page, review your changes. If they're correct, choose Modify DB Instance to
save your changes. If they aren't correct, choose Back to edit your changes or Cancel to cancel your
changes.

Changing the storage autoscaling limit occurs immediately. This setting ignores the Apply immediately
setting.

AWS CLI

To turn off storage autoscaling for a DB instance, use the AWS CLI command modify-db-instance and
the following parameter:

• --max-allocated-storage – Specify a value equal to the --allocated-storage setting to

prevent further Amazon RDS storage autoscaling for the specified DB instance.

For more information about storage, see Amazon RDS DB instance storage (p. 40).

Amazon RDS API

To turn off storage autoscaling for a DB instance, use the Amazon RDS API operation
ModifyDBInstance. Set the following parameter:

• MaxAllocatedStorage – Specify a value equal to the AllocatedStorage setting to prevent

further Amazon RDS storage autoscaling for the specified DB instance.

For more information about storage, see Amazon RDS DB instance storage (p. 40).

327
 Amazon Relational Database Service User Guide
Modifying Provisioned IOPS

Modifying SSD storage settings for Provisioned IOPS

You can modify the settings for a DB instance that uses Provisioned IOPS SSD storage by using the
Amazon RDS console, AWS CLI, or Amazon RDS API. Specify the storage type, allocated storage, and the
amount of Provisioned IOPS that you require. You can choose from a range between 1,000 IOPS and
100 GiB of storage up to 80,000 IOPS and 64 TiB (64,000 GiB) of storage. The range depends on your
database engine and instance type.

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.

In most cases, scaling storage doesn't require any outage and doesn't degrade performance of the
server. After you modify the storage IOPS for a DB instance, the status of the DB instance is storage-
optimization. The DB instance is fully operational after a storage modification.
Note
You can't make further storage modifications until six (6) hours after storage optimization has
completed on the instance.

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 Databases.
Note
To filter the list of DB instances, for Filter databases enter 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. Choose Modify.
5. On the Modify DB Instance page, choose Provisioned IOPS for Storage type and then provide a
Provisioned IOPS value.

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 message gives the range of
values required for the other parameter.
6. Choose Continue.
7. To apply the changes to the DB instance immediately, choose Apply immediately in the Scheduling
of modifications section. Or choose Apply during the next scheduled maintenance window to
apply the changes during the next maintenance window.

An immediate outage occurs when the storage type changes. For more information about storage,
see Amazon RDS DB instance storage (p. 40).

328
 Amazon Relational Database Service User Guide
Modifying Provisioned IOPS

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.

AWS CLI
To change the Provisioned IOPS setting for a DB instance, use the AWS CLI command modify-db-
instance. 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 apply changes immediately. Use --no-
apply-immediately (the default) to apply changes during the next maintenance window.

Amazon RDS API

To change the Provisioned IOPS settings for a DB instance, use the Amazon RDS API operation
ModifyDBInstance. 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 to apply changes immediately. Set this option to False
(the default) to apply changes during the next maintenance window.

329
 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

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. 291).
Note
When the status for a DB instance is deleting, its CA certificate value doesn't appear in the
RDS console or in output for AWS CLI commands or RDS API operations. For more information
about CA certificates, see Using SSL/TLS to encrypt a connection to a DB instance (p. 1624).

Deletion protection
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. Enabling or disabling deletion protection doesn't cause an
outage.

Creating a final snapshot and retaining automated

backups
When you delete a DB instance, you can choose to do one or both of the following:

• Create a final DB snapshot.

• To be able to restore your deleted DB instance later, create a final DB snapshot. The final snapshot is
retained, along with any manual snapshots that were taken.
• To delete a DB instance quickly, you can skip creating a final DB snapshot.
Note
You can't create a final DB snapshot of your DB instance if it has the status creating,
failed, incompatible-restore, or incompatible-network. For more information, see
DB instance status (p. 410).
• Retain automated backups.
• Your automated backups are retained for the retention period that is set on the DB instance at the
time when you delete it. This set retention period occurs whether or not you choose to create a final
DB snapshot.
• If you don't choose to retain automated backups, your automated backups in the same AWS Region
as the DB instance are deleted. They can't be recovered after you delete the DB instance.
Note
Automated backups that are replicated to another AWS Region are retained even if you
choose not to retain automated backups. For more information, see Replicating automated
backups to another AWS Region (p. 344).
• You typically don't need to retain automated backups if you create a final DB snapshot.

330
 Amazon Relational Database Service User Guide
Deleting a DB instance

• To delete a retained automated backup, follow the instructions in Deleting retained automated
backups (p. 339).

Important
If you skip the final DB snapshot, to restore your DB instance do one of the following:

• Use an earlier manual snapshot of the DB instance to restore the DB instance to that DB
snapshot's point in time.
• Retain automated backups. You can use them to restore your DB instance during your
retention period, but not after your retention period has ended.

Note
Regardless of your choice, manual DB snapshots aren't deleted. For more information on
snapshots, see Creating a DB snapshot (p. 352).

Deleting a DB instance
You can delete a DB instance using the AWS Management Console, the AWS CLI, or the RDS API.

The time required to delete a DB instance can vary depending on the backup retention period (that is,
how many backups to delete), how much data is deleted, and whether a final snapshot is taken.
Note
You can't delete a DB instance when deletion protection is enabled for it. For more information,
see Deletion protection (p. 330).
You can disable deletion protection by modifying the DB instance. For more information, see
Modifying an Amazon RDS DB instance (p. 256).

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 Databases, and then choose the DB instance that you want to delete.
3. For Actions, choose Delete.
4. To create a final DB snapshot for the DB instance, choose Create final snapshot?.
5. If you chose to create a final snapshot, enter the Final snapshot name.
6. To retain automated backups, choose Retain automated backups.
7. 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, macOS, or Unix:

331
 Amazon Relational Database Service User Guide
Deleting a DB instance

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

Example With retained automated backups and no final snapshot

For Linux, macOS, 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 operation with the
following parameters:

• DBInstanceIdentifier
• FinalDBSnapshotIdentifier or SkipFinalSnapshot

332
 Amazon Relational Database Service User Guide

Backing up and restoring an Amazon

RDS DB instance
This section shows how to back up and restore a DB instance.

Topics
• Working with backups (p. 334)
• Replicating automated backups to another AWS Region (p. 344)
• Creating a DB snapshot (p. 352)
• Restoring from a DB snapshot (p. 355)
• Copying a snapshot (p. 358)
• Sharing a DB snapshot (p. 371)
• Exporting DB snapshot data to Amazon S3 (p. 379)
• Restoring a DB instance to a specified time (p. 395)
• Deleting a snapshot (p. 398)
• Tutorial: Restore a DB instance from a DB snapshot (p. 400)

333
 Amazon Relational Database Service User Guide
Working with backups

Working with backups

Amazon RDS creates and saves automated backups of your DB instance during the backup window of
your DB instance. RDS creates a storage volume snapshot of your DB instance, backing up the entire
DB instance and not just individual databases. 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 AVAILABLE state for automated backups to occur. Automated
backups don't occur while your DB instance is in a state other than AVAILABLE, for example
STORAGE_FULL.
• Automated backups and automated snapshots don't occur while a copy is running in the same AWS
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. 352).

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. 358). For more information
about sharing a DB snapshot, see Sharing a DB snapshot (p. 371).

Backup storage
Your Amazon RDS backup storage for each AWS Region is composed of the automated backups and
manual DB snapshots for that Region. Total backup storage space equals the sum of the storage for all
backups in that Region. Moving a DB snapshot to another Region increases the backup storage in the
destination Region. Backups are stored in Amazon S3.

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. You can have up to 100 manual snapshots
per Region.

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

334
 Amazon Relational Database Service User Guide
Backup window

taken from the standby. For SQL Server, I/O activity is suspended briefly during backup for Multi-AZ
deployments.

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 AWS Region from which the default
backup windows are assigned.

Region Name Region Time Block

US East (Ohio) us-east-2 03:00–11:00 UTC

US East (N. Virginia) us-east-1 03:00–11:00 UTC

US West (N. California) us-west-1 06:00–14:00 UTC

US West (Oregon) us-west-2 06:00–14:00 UTC

Africa (Cape Town) af-south-1 03:00–11:00 UTC

Asia Pacific (Hong ap-east-1 06:00–14:00 UTC

Kong)

Asia Pacific (Mumbai) ap-south-1 16:30–00:30 UTC

Asia Pacific (Osaka) ap-northeast-3 00:00–08:00 UTC

Asia Pacific (Seoul) ap-northeast-2 13:00–21:00 UTC

Asia Pacific (Singapore) ap-southeast-1 14:00–22:00 UTC

Asia Pacific (Sydney) ap-southeast-2 12:00–20:00 UTC

Asia Pacific (Tokyo) ap-northeast-1 13:00–21:00 UTC

Canada (Central) ca-central-1 03:00–11:00 UTC

China (Beijing) cn-north-1 06:00–14:00 UTC

China (Ningxia) cn-northwest-1 06:00–14:00 UTC

Europe (Frankfurt) eu-central-1 20:00–04:00 UTC

Europe (Ireland) eu-west-1 22:00–06:00 UTC

Europe (London) eu-west-2 22:00–06:00 UTC

Europe (Paris) eu-west-3 07:29–14:29 UTC

Europe (Milan) eu-south-1 02:00–10:00 UTC

Europe (Stockholm) eu-north-1 23:00–07:00 UTC

Middle East (Bahrain) me-south-1 06:00–14:00 UTC

South America (São sa-east-1 23:00–07:00 UTC

Paulo)

AWS GovCloud (US- us-gov-east-1 17:00–01:00 UTC

East)

335
 Amazon Relational Database Service User Guide
Backup retention period

Region Name Region Time Block

AWS GovCloud (US- us-gov-west-1 06:00–14:00 UTC

West)

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.

Automated backups aren't created while a DB instance is stopped. Backups can be retained longer than
the backup retention period if a DB instance has been stopped. RDS doesn't include time spent in the
stopped state when the backup retention window is calculated.
Important
An outage occurs if you change the backup retention period from 0 to a nonzero value or from a
nonzero value to 0. This applies to both Single-AZ and Multi-AZ DB instances.

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 nonzero value. When
automated backups are enabled, your RDS instance and database is taken offline and a backup is
immediately created.
Note
If you manage your backups in AWS Backup, you can't enable automated backups. For more
information, see Using AWS Backup to manage automated backups (p. 341).

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 Databases, and then choose the DB instance that you want to
modify.
3. Choose Modify. The Modify DB instance page appears.
4. For Backup retention period, choose a positive nonzero value, for example 3 days.
5. Choose Continue.
6. Choose Apply immediately.
7. On the confirmation page, choose Modify DB instance to save your changes and enable automated
backups.

AWS CLI
To enable automated backups, use the AWS CLI modify-db-instance command.

336
 Amazon Relational Database Service User Guide
Retaining automated backups

Include the following parameters:

• --db-instance-identifier
• --backup-retention-period
• --apply-immediately or --no-apply-immediately

In the following example, we enable automated backups by setting the backup retention period to three
days. The changes are applied immediately.

Example

For Linux, macOS, 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, use the RDS API ModifyDBInstance operation with the following
required parameters:

• DBInstanceIdentifier
• BackupRetentionPeriod

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 the MySQL, MariaDB, PostgreSQL, Oracle,
and Microsoft SQL Server engines.

You can restore or remove retained automated backups using the AWS Management Console, RDS API,
and AWS CLI.

Topics
• Retention period (p. 338)
• Viewing retained backups (p. 338)
• Restoration (p. 338)
• Retention costs (p. 338)
• Limitations and recommendations (p. 339)

337
 Amazon Relational Database Service User Guide
Retaining automated backups

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 operation
DeleteDBInstanceAutomatedBackup.

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.

Viewing retained backups

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.

To describe your retained automated backups using the AWS CLI, use one of the following commands:

aws rds describe-db-instance-automated-backups --db-instance-

identifier DBInstanceIdentifier

or

aws rds describe-db-instance-automated-backups --dbi-resource-id DbiResourceId

To describe your retained automated backups using the RDS API, call the
DescribeDBInstanceAutomatedBackups action with one of the following parameters:

• DBInstanceIdentifier
• DbiResourceId

Restoration
For information on restoring DB instances from automated backups, see Restoring a DB instance to a
specified time (p. 395).

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.

338
 Amazon Relational Database Service User Guide
Deleting retained automated backups

Limitations and recommendations

The following limitations apply to retained automated backups:

• The maximum number of retained automated backups in one AWS Region is 40. It's not included in
the DB instances limit. You can have 40 running DB instances and an additional 40 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.
• You can't modify a retained automated backup. That's because it consists of system backups,
transaction logs, and the DB instance properties that existed at the time that you deleted the source
instance.

Deleting retained automated backups

You can delete retained automated backups when they are no longer needed.

Console
To delete a retained automated backup

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 Automated backups.
3. On the Retained tab, choose the retained automated backup that you want to delete.
4. For Actions, choose Delete.
5. On the confirmation page, enter delete me and choose Delete.

AWS CLI
You can delete a retained automated backup by using the AWS CLI command delete-db-instance-
automated-backup with the following option:

• --dbi-resource-id – The resource identifier for the source DB instance.

You can find the resource identifier for the source DB instance of a retained automated backup by
running the AWS CLI command describe-db-instance-automated-backups.

Example

The following example deletes the retained automated backup with source DB instance resource
identifier db-123ABCEXAMPLE.

For Linux, macOS, or Unix:

aws rds delete-db-instance-automated-backup \

--dbi-resource-id db-123ABCEXAMPLE

For Windows:

aws rds delete-db-instance-automated-backup ^

339
 Amazon Relational Database Service User Guide
Disabling automated backups

--dbi-resource-id db-123ABCEXAMPLE

RDS API
You can delete a retained automated backup by using the Amazon RDS API operation
DeleteDBInstanceAutomatedBackup with the following parameter:

• DbiResourceId – The resource identifier for the source DB instance.

You can find the resource identifier for the source DB instance of a retained automated backup using
the Amazon RDS API operation DescribeDBInstanceAutomatedBackups.

Disabling automated backups

You might want to temporarily disable automated backups in certain situations, for example while
loading large amounts of data.
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 can restore starting only
from the time you re-enabled automated backups.

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 Databases, and then choose the DB instance that you want to
modify.
3. Choose Modify. The Modify DB instance page appears.
4. For Backup retention period, choose 0 days.
5. Choose Continue.
6. Choose Apply immediately.
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, macOS, or Unix:

aws rds modify-db-instance \

--db-instance-identifier mydbinstance \
--backup-retention-period 0 \
--apply-immediately

340
 Amazon Relational Database Service User Guide
Using AWS Backup

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

RDS API
To disable automated backups immediately, call the ModifyDBInstance operation 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=<AWS Access Key ID>
&Signature=<Signature>

Using AWS Backup to manage automated backups

AWS Backup is a fully managed backup service that makes it easy to centralize and automate the backup
of data across AWS services in the cloud and on premises. You can manage backups of your Amazon RDS
DB instances in AWS Backup.

To enable backups in AWS Backup, you use resource tagging to associate your DB instance with a backup
plan. For more information, see Using tags to enable backups in AWS Backup (p. 312).
Note
Backups managed by AWS Backup are considered manual DB snapshots, but don't count toward
the DB snapshot quota for RDS. Backups that were created with AWS Backup have names
ending in awsbackup:AWS-Backup-job-number.

For more information about AWS Backup, see the AWS Backup Developer Guide.

To view backups managed by AWS Backup

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 Backup service tab.

Your AWS Backup backups are listed under Backup service snapshots.

341
 Amazon Relational Database Service User Guide
Unsupported MySQL storage engines

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 statement 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:

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. 352).

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/.

342
 Amazon Relational Database Service User Guide
Unsupported MariaDB storage engines

• 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.

343
 Amazon Relational Database Service User Guide
Replicating automated backups to another Region

Replicating automated backups to another AWS

Region
For added disaster recovery capability, you can configure your Amazon RDS database instance to
replicate snapshots and transaction logs to a destination AWS Region of your choice. When backup
replication is configured for a DB instance, RDS initiates a cross-Region copy of all snapshots and
transaction logs as soon as they are ready on the DB instance.

DB snapshot copy charges apply to the data transfer. After the DB snapshot is copied, standard charges
apply to storage in the destination Region. For more details, see RDS Pricing.

Backup replication is available for RDS DB instances running the following database engines:

• Oracle version 12.1.0.2.v10 and higher

• PostgreSQL version 9.6 and higher

Backup replication isn't supported for encrypted DB instances.

Enabling cross-Region automated backups

You can enable backup replication on new or existing DB instances using the Amazon RDS console. You
can also use the start-db-instance-automated-backups-replication AWS CLI command or the
StartDBInstanceAutomatedBackupsReplication RDS API operation.
Note
To be able to replicate automated backups, make sure to enable them. For more information,
see Enabling automated backups (p. 336).

You can use the describe-source-regions CLI command to list the source AWS Regions that can
replicate automated backups to a particular destination Region. For more information, see Finding
information about replicated backups (p. 345).

Console
You can enable backup replication for a new or existing DB instance:

• For a new DB instance, enable it when you launch the instance. For more information, see Settings for
DB instances (p. 151).
• For an existing DB instance, use the following procedure.

To enable backup replication for an existing 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 Automated backups.
3. On the Current Region tab, choose the DB instance for which you want to enable backup
replication.
4. For Actions, choose Manage cross-Region replication.
5. Under Backup replication, choose Enable replication to another AWS Region.
6. Choose the Destination Region.
7. Choose the Replicated backup retention period.
8. Choose Save.

344
 Amazon Relational Database Service User Guide
Finding information about replicated backups

In the source Region, replicated backups are listed on the Current Region tab of the Automated backups
page. In the destination Region, replicated backups are listed on the Replicated backups tab of the
Automated backups page.

AWS CLI
Enable backup replication by using the start-db-instance-automated-backups-replication
AWS CLI command.

The following CLI example replicates automated backups from a DB instance in the US West (Oregon)
Region to the US East (N. Virginia) Region.

To enable backup replication

• Run one of the following commands.

For Linux, macOS, or Unix:

aws rds start-db-instance-automated-backups-replication \

--region us-east-1 \
--source-db-instance-arn "arn:aws:rds:us-west-2:123456789012:db:mydatabase" \
--backup-retention-period 7

For Windows:

aws rds start-db-instance-automated-backups-replication ^

--region us-east-1 ^
--source-db-instance-arn "arn:aws:rds:us-west-2:123456789012:db:mydatabase" ^
--backup-retention-period 7

RDS API
Enable backup replication by using the StartDBInstanceAutomatedBackupsReplication RDS API
operation with the following parameters:

• Region
• SourceDBInstanceArn
• BackupRetentionPeriod

Finding information about replicated backups

You can use the following CLI commands to find information about replicated backups:

• describe-source-regions
• describe-db-instances
• describe-db-instance-automated-backups

The following describe-source-regions example lists the source AWS Regions from which
automated backups can be replicated to the US West (Oregon) destination Region.

To show information about source Regions

• Run the following command.

345
 Amazon Relational Database Service User Guide
Finding information about replicated backups

aws rds describe-source-regions --region us-west-2

The output shows that backups can be replicated from Asia Pacific (Tokyo), but not from Asia Pacific
(Seoul), into US West (Oregon).

{
"SourceRegions": [
{
"RegionName": "ap-northeast-1",
"Endpoint": "https://rds.ap-northeast-1.amazonaws.com",
"Status": "available",
"SupportsDBInstanceAutomatedBackupsReplication": true
},
{
"RegionName": "ap-northeast-2",
"Endpoint": "https://rds.ap-northeast-2.amazonaws.com",
"Status": "available",
"SupportsDBInstanceAutomatedBackupsReplication": false
}
...
]
}

The following describe-db-instances example shows the automated backups for a DB instance.

To show the replicated backups for a DB instance

• Run one of the following commands.

For Linux, macOS, or Unix:

aws rds describe-db-instances \

--db-instance-identifier mydatabase

For Windows:

aws rds describe-db-instances ^

--db-instance-identifier mydatabase

The output includes the replicated backups.

{
"DBInstances": [
{
"StorageEncrypted": false,
"Endpoint": {
"HostedZoneId": "Z1PVIF0B656C1W",
"Port": 1521,
...

"BackupRetentionPeriod": 7,
"DBInstanceAutomatedBackupsReplications": [{"DBInstanceAutomatedBackupsArn":
"arn:aws:rds:us-east-1:123456789012:auto-backup:ab-L2IJCEXJP7XQ7HOJ4SIEXAMPLE"}]
}
]
}

346
 Amazon Relational Database Service User Guide
Finding information about replicated backups

The following describe-db-instance-automated-backups example shows the automated backups

for a DB instance.

To show automated backups for a DB instance

• Run one of the following commands.

For Linux, macOS, or Unix:

aws rds describe-db-instance-automated-backups \

--db-instance-identifier mydatabase

For Windows:

aws rds describe-db-instance-automated-backups ^

--db-instance-identifier mydatabase

The output shows the source DB instance and automated backups in US West (Oregon), with backups
replicated to US East (N. Virginia).

{
"DBInstanceAutomatedBackups": [
{
"DBInstanceArn": "arn:aws:rds:us-west-2:868710585169:db:mydatabase",
"DbiResourceId": "db-L2IJCEXJP7XQ7HOJ4SIEXAMPLE",
"DBInstanceAutomatedBackupsArn": "arn:aws:rds:us-west-2:123456789012:auto-
backup:ab-L2IJCEXJP7XQ7HOJ4SIEXAMPLE",
"BackupRetentionPeriod": 7,
"DBInstanceAutomatedBackupsReplications": [{"DBInstanceAutomatedBackupsArn":
"arn:aws:rds:us-east-1:123456789012:auto-backup:ab-L2IJCEXJP7XQ7HOJ4SIEXAMPLE"}]
"Region": "us-west-2",
"DBInstanceIdentifier": "mydatabase",
"RestoreWindow": {
"EarliestTime": "2020-10-26T01:09:07Z",
"LatestTime": "2020-10-31T19:09:53Z",
}
...
}
]
}

The following describe-db-instance-automated-backups example uses the --db-instance-

automated-backups-arn option to show the replicated backups in the destination Region.

To show replicated backups

• Run one of the following commands.

For Linux, macOS, or Unix:

aws rds describe-db-instance-automated-backups \

--db-instance-automated-backups-arn "arn:aws:rds:us-east-1:123456789012:auto-backup:ab-
L2IJCEXJP7XQ7HOJ4SIEXAMPLE"

For Windows:

aws rds describe-db-instance-automated-backups ^

347
 Amazon Relational Database Service User Guide
Point-in-time recovery from a replicated backup

--db-instance-automated-backups-arn "arn:aws:rds:us-east-1:123456789012:auto-backup:ab-
L2IJCEXJP7XQ7HOJ4SIEXAMPLE"

The output shows the source DB instance in US West (Oregon), with replicated backups in US East (N.
Virginia).

{
"DBInstanceAutomatedBackups": [
{
"DBInstanceArn": "arn:aws:rds:us-west-2:868710585169:db:mydatabase",
"DbiResourceId": "db-L2IJCEXJP7XQ7HOJ4SIEXAMPLE",
"DBInstanceAutomatedBackupsArn": "arn:aws:rds:us-east-1:123456789012:auto-
backup:ab-L2IJCEXJP7XQ7HOJ4SIEXAMPLE",
"Region": "us-west-2",
"DBInstanceIdentifier": "mydatabase",
"RestoreWindow": {
"EarliestTime": "2020-10-26T01:09:07Z",
"LatestTime": "2020-10-31T19:01:23Z"
},
"AllocatedStorage": 50,
"BackupRetentionPeriod": 7,
"Status": "replicating",
"Port": 1521,
...
}
]
}

Restoring to a specified time from a replicated

backup
You can restore a DB instance to a specific point in time from a replicated backup using the Amazon RDS
console. You can also use the restore-db-instance-to-point-in-time AWS CLI command or the
RestoreDbInstanceToPointInTime RDS API operation.

For general information on point-in-time recovery (PITR), see Restoring a DB instance to a specified
time (p. 395).

Console
To restore a DB instance to a specified time from a replicated backup

1. Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.
2. Choose the destination Region (where backups are replicated to) from the Region selector.
3. In the navigation pane, choose Automated backups.
4. On the Replicated backups tab, choose the DB instance that you want to restore.
5. For Actions, choose Restore to point in time.
6. 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.
Note
Times are shown in your local time zone, which is indicated by an offset from Coordinated
Universal Time (UTC). For example, UTC-5 is Eastern Standard Time/Central Daylight Time.

348
 Amazon Relational Database Service User Guide
Stopping backup replication

7. For DB instance identifier, enter the name of the target restored DB instance.
8. (Optional) Choose other options as needed, such as enabling autoscaling.
9. Choose Restore to point in time.

AWS CLI
Use the restore-db-instance-to-point-in-time AWS CLI command to create a new DB instance.

To restore a DB instance to a specified time from a replicated backup

• Run one of the following commands.

For Linux, macOS, or Unix:

aws rds restore-db-instance-to-point-in-time \

--source-db-instance-automated-backups-arn "arn:aws:rds:us-
east-1:123456789012:auto-backup:ab-L2IJCEXJP7XQ7HOJ4SIEXAMPLE" \
--target-db-instance-identifier mytargetdbinstance \
--restore-time 2020-10-14T23:45:00.000Z

For Windows:

aws rds restore-db-instance-to-point-in-time ^

--source-db-instance-automated-backups-arn "arn:aws:rds:us-
east-1:123456789012:auto-backup:ab-L2IJCEXJP7XQ7HOJ4SIEXAMPLE" ^
--target-db-instance-identifier mytargetdbinstance ^
--restore-time 2020-10-14T23:45:00.000Z

RDS API
To restore a DB instance to a specified time, call the RestoreDBInstanceToPointInTime Amazon
RDS API operation with the following parameters:

• SourceDBInstanceAutomatedBackupsArn
• TargetDBInstanceIdentifier
• RestoreTime

Stopping automated backup replication

You can stop backup replication for DB instances using the Amazon RDS console. You can also
use the stop-db-instance-automated-backups-replication AWS CLI command or the
StopDbInstanceAutomatedBackupsReplication RDS API operation.

Replicated backups are retained, subject to the backup retention period set when they were created.

Console
Stop backup replication from the Automated backups page in the source Region.

To stop backup replication to an AWS Region

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

349
 Amazon Relational Database Service User Guide
Deleting replicated backups

2. Choose the source Region from the Region selector.

3. In the navigation pane, choose Automated backups.
4. On the Current Region tab, choose the DB instance for which you want to stop backup replication.
5. For Actions, choose Manage cross-Region replication.
6. Under Backup replication, clear the Enable replication to another AWS Region check box.
7. Choose Save.

Replicated backups are listed on the Retained tab of the Automated backups page in the destination
Region.

AWS CLI
Stop backup replication by using the stop-db-instance-automated-backups-replication AWS
CLI command.

The following CLI example stops automated backups of a DB instance from replicating in the US West
(Oregon) Region.

To stop backup replication

• Run one of the following commands.

For Linux, macOS, or Unix:

aws rds stop-db-instance-automated-backups-replication \

--region us-east-1 \
--source-db-instance-arn "arn:aws:rds:us-west-2:123456789012:db:mydatabase"

For Windows:

aws rds stop-db-instance-automated-backups-replication ^

--region us-east-1 ^
--source-db-instance-arn "arn:aws:rds:us-west-2:123456789012:db:mydatabase"

RDS API
Stop backup replication by using the StopDbInstanceAutomatedBackupsReplication RDS API
operation with the following parameters:

• Region
• SourceDBInstanceArn

Deleting replicated backups

You can delete replicated backups for DB instances using the Amazon RDS console. You
can also use the delete-db-instance-automated-backups AWS CLI command or the
DeleteDbInstanceAutomatedBackups RDS API operation.

Console
Delete replicated backups in the destination Region from the Automated backups page.

350
 Amazon Relational Database Service User Guide
Deleting replicated backups

To delete replicated backups

1. Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.
2. Choose the destination Region from the Region selector.
3. In the navigation pane, choose Automated backups.
4. On the Replicated backups tab, choose the DB instance for which you want to delete the replicated
backups.
5. For Actions, choose Delete.
6. On the confirmation page, enter delete me and choose Delete.

AWS CLI
Delete replicated backups by using the delete-db-instance-automated-backup AWS CLI
command.

You can use the describe-db-instances CLI command to find the Amazon Resource Names
(ARNs) of the replicated backups. For more information, see Finding information about replicated
backups (p. 345).

To delete replicated backups

• Run one of the following commands.

For Linux, macOS, or Unix:

aws rds delete-db-instance-automated-backup \

--db-instance-automated-backups-arn "arn:aws:rds:us-east-1:123456789012:auto-backup:ab-
L2IJCEXJP7XQ7HOJ4SIEXAMPLE"

For Windows:

aws rds delete-db-instance-automated-backup ^

--db-instance-automated-backups-arn "arn:aws:rds:us-east-1:123456789012:auto-backup:ab-
L2IJCEXJP7XQ7HOJ4SIEXAMPLE"

RDS API
Delete replicated backups by using the DeleteDbInstanceAutomatedBackup RDS API operation with
the DbInstanceAutomatedBackupsArn parameter.

351
 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. 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.

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.
Note
For PostgreSQL DB instances, data in unlogged tables might not be restored from snapshots.
For more information, see Best practices for working with PostgreSQL (p. 143).

Unlike automated backups, manual snapshots aren't subject to the backup retention period. Snapshots
don't expire.

For very long-term backups of MariaDB, MySQL, and PostgreSQL data, we recommend exporting
snapshot data to Amazon S3. If the major version of your DB engine is no longer supported, you can't
restore to that version from a snapshot. For more information, see Exporting DB snapshot data to
Amazon S3 (p. 379).

You can create a DB snapshot using the AWS Management Console, the AWS CLI, or the RDS API.

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 Databases.
3. In the list of DB instances, choose the DB instance for which you want to take a snapshot.
4. For Actions, choose Take snapshot.

The Take DB Snapshot window appears.

5. Type the name of the snapshot in the Snapshot Name box.

352
 Amazon Relational Database Service User Guide
Creating a DB snapshot

6. Choose Take Snapshot.

AWS 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, macOS, 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

RDS 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:

353
 Amazon Relational Database Service User Guide
Creating a DB snapshot

• DBInstanceIdentifier
• DBSnapshotIdentifier

354
 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 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. For more
information, see Copying a snapshot (p. 358).

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 by
default.
Note

• If you're using the Amazon RDS console, you can specify a custom security group to associate
with the instance or create a new VPC security group.
• If you're using the AWS CLI, you can specify a custom security group to associate with the
instance by including the --vpc-security-group-ids option in the restore-db-
instance-from-db-snapshot command.
• If you're using the Amazon RDS API, you can include the
VpcSecurityGroupIds.VpcSecurityGroupId.N parameter in the
RestoreDBInstanceFromDBSnapshot action.

As soon as the restore is complete and your new DB instance is available, you can associate any
custom security groups used by the snapshot you restored from. You must apply these changes by
modifying the DB instance with the RDS console, the AWS CLI modify-db-instance command, or the
ModifyDBInstance Amazon RDS API operation. For more information, see Modifying an Amazon RDS
DB instance (p. 256).

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

355
 Amazon Relational Database Service User Guide
Microsoft SQL Server

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.
• 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. 678).

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. 1220).

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.

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. For Actions, choose Restore snapshot.
5. On the Restore snapshot page, for DB instance identifier, enter the name for your restored DB
instance.
6. Choose Restore DB instance.

356
 Amazon Relational Database Service User Guide
Restoring from a snapshot

AWS CLI
To restore a DB instance from a DB snapshot, use the AWS CLI command restore-db-instance-from-db-
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, macOS, 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 MySQL 50 sa creating 3 n

5.6.40 general-public-license

RDS API
To restore a DB instance from a DB snapshot, call the Amazon RDS API function
RestoreDBInstanceFromDBSnapshot with the following parameters:

• DBInstanceIdentifier
• DBSnapshotIdentifier

357
 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 shared snapshots.

Limitations
The following are some limitations when you copy snapshots:

• You can't copy a snapshot to or from the China (Beijing) or China (Ningxia) Regions.
• You can copy a snapshot between AWS GovCloud (US-East) and AWS GovCloud (US-West). However,
you can't copy a snapshot between these AWS GovCloud (US) Regions and commercial AWS Regions.
• If you delete a source snapshot before the target snapshot becomes available, the snapshot copy
might 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.
• 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 Region. In such cases, Amazon RDS might put
new cross-Region copy requests from that source 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 in several situations:

• At the end of their retention period.

• When you disable automated snapshots for a DB instance.
• 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. In some cases, you might copy an
encrypted snapshot that has been shared from another AWS account. In these cases, you must have
access to the AWS KMS customer master key (CMK) that was used to encrypt the snapshot.

You can copy a shared DB snapshot across AWS Regions if the snapshot is unencrypted. However, if the
shared DB snapshot is encrypted, you can only copy it in the same Region.
Note
Copying shared incremental snapshots in the same AWS Region is supported when they're
unencrypted, or encrypted using the same AWS KMS key as the initial full snapshot. If you use a

358
 Amazon Relational Database Service User Guide
Handling encryption

different KMS key to encrypt subsequent snapshots when copying them, those shared snapshots
are full snapshots.

Handling encryption
You can copy a snapshot that has been encrypted using an AWS KMS customer master key (CMK). If you
copy an encrypted snapshot, the copy of the snapshot must also be encrypted. If you copy an encrypted
snapshot within the same AWS Region, you can encrypt the copy with the same AWS KMS CMK as the
original snapshot. Or you can specify a different CMK. If you copy an encrypted snapshot across Regions,
you can't use the same AWS KMS CMK for the copy as used for the source snapshot. This is because AWS
KMS CMKs are Region-specific. Instead, you must specify an AWS KMS CMK valid in the destination AWS
Region.

The source snapshot remains encrypted throughout the copy process. For more information, see
Limitations of Amazon RDS encrypted DB instances (p. 1622).

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. You then create
a copy of that snapshot and specify an AWS KMS CMK to encrypt that snapshot copy. You can then
restore an encrypted DB instance from the encrypted snapshot.

Incremental snapshot copying

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.
Note
When you copy a source snapshot that is a snapshot copy itself, the new copy isn't incremental.
This is because the source snapshot copy doesn't include the required metadata for incremental
copies.

Whether a snapshot copy is incremental is determined by the most recently completed snapshot copy.
If the most recent snapshot copy was deleted, the next copy is a full copy, not an incremental copy. If
a copy is still pending when you start another copy, the second copy doesn't start until the first copy
finishes.

When you copy a snapshot across AWS accounts, the copy is an incremental copy if the following
conditions are met:

• The snapshot was previously copied to the destination account.

• The most recent snapshot copy still exists in the destination account.
• All copies of the snapshot in the destination account are either unencrypted, or were encrypted using
the same CMK.

For shared snapshots, copying incremental snapshots across AWS accounts is only supported when
they're unencrypted.

For information on copying incremental snapshots across AWS Regions, see Full and incremental
copies (p. 362).

Cross-Region snapshot copying

You can copy DB snapshots across AWS Regions. However, there are certain constraints and
considerations for cross-Region snapshot copying.

359
 Amazon Relational Database Service User Guide
Cross-Region copying

Requesting a cross-Region DB snapshot copy

To communicate with the source Region to request a cross-Region DB snapshot copy, the requester (IAM
role or IAM user) must have access to the source DB snapshot and the source Region.

Certain conditions in the requester's IAM policy can cause the request to fail. The following examples
assume that you're copying the DB snapshot from US East (Ohio) to US East (N. Virginia). These examples
show conditions in the requester's IAM policy that cause the request to fail:

• The requester's policy has a condition for aws:RequestedRegion.

...
"Effect": "Allow",
"Action": "rds:CopyDBSnapshot",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:RequestedRegion": "us-east-1"
}
}

The request fails because the policy doesn't allow access to the source Region. For a successful request,
specify both the source and destination Regions.

...
"Effect": "Allow",
"Action": "rds:CopyDBSnapshot",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:RequestedRegion": [
"us-east-1",
"us-east-2"
]
}
}

• The requester's policy doesn't allow access to the source DB snapshot.

...
"Effect": "Allow",
"Action": "rds:CopyDBSnapshot",
"Resource": "arn:aws:rds:us-east-1:123456789012:snapshot:target-snapshot"
...

For a successful request, specify both the source and target snapshots.

...
"Effect": "Allow",
"Action": "rds:CopyDBSnapshot",
"Resource": [
"arn:aws:rds:us-east-1:123456789012:snapshot:target-snapshot",
"arn:aws:rds:us-east-2:123456789012:snapshot:source-snapshot"
]
...

• The requester's policy denies aws:ViaAWSService.

...
"Effect": "Allow",

360
 Amazon Relational Database Service User Guide
Cross-Region copying

"Action": "rds:CopyDBSnapshot",
"Resource": "*",
"Condition": {
"Bool": {"aws:ViaAWSService": "false"}
}

Communication with the source Region is made by RDS on the requester's behalf. For a successful
request, don't deny calls made by AWS services.
• The requester's policy has a condition for aws:SourceVpc or aws:SourceVpce.

These requests might fail because when RDS makes the call to the remote Region, it isn't from the
specified VPC or VPC endpoint.

If you need to use one of the previous conditions that would cause a request to fail, you can include a
second statement with aws:CalledVia in your policy to make the request succeed. For example, you
can use aws:CalledVia with aws:SourceVpce as shown here:

...
"Effect": "Allow",
"Action": "rds:CopyDBSnapshot",
"Resource": "*",
"Condition": {
"Condition" : {
"ForAnyValue:StringEquals" : {
"aws:SourceVpce": "vpce-1a2b3c4d"
}
}
},
{
"Effect": "Allow",
"Action": [
"rds:CopyDBSnapshot"
],
"Resource": "*",
"Condition": {
"ForAnyValue:StringEquals": {
"aws:CalledVia": [
"rds.amazonaws.com"
]
}
}
}

For more information, see Policies and permissions in IAM in the IAM User Guide.

Authorizing the snapshot copy

After a cross-Region DB snapshot copy request returns success, RDS starts the copy in the background.
An authorization for RDS to access the source snapshot is created. This authorization links the source DB
snapshot to the target DB snapshot, and allows RDS to copy only to the specified target snapshot.

The authorization is verified by RDS using the rds:CrossRegionCommunication permission in

the service-linked IAM role. If the copy is authorized, RDS communicates with the source Region and
completes the copy.

RDS doesn't have access to DB snapshots that weren't authorized previously by a CopyDBSnapshot
request. The authorization is revoked when copying completes.

RDS uses the service-linked role to verify the authorization in the source Region. If you delete the
service-linked role during the copy process, the copy fails.

361
 Amazon Relational Database Service User Guide
Option groups

For more information, see Using service-linked roles in the IAM User Guide.

Using AWS Security Token Service credentials

Session tokens from the global AWS Security Token Service (AWS STS) endpoint are valid only in AWS
Regions that are enabled by default (commercial Regions). If you use credentials from the assumeRole
API operation in AWS STS, use the regional endpoint if the source Region is an opt-in Region. Otherwise,
the request fails. This happens because your credentials must be valid in both Regions, which is true for
opt-in Regions only when the regional AWS STS endpoint is used.

To use the global endpoint, make sure that it's enabled for both Regions in the operations. Set the global
endpoint to Valid in all AWS Regions in the AWS STS account settings.

The same rule applies to credentials in the presigned URL parameter.

For more information, see Managing AWS STS in an AWS Region in the IAM User Guide.

Latency and multiple copy requests

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 such 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
copying starts.

Full and incremental copies

When you copy a snapshot to a different AWS Region from the source snapshot, 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 within the same AWS
account. For more information on incremental snapshots, see Incremental snapshot copying (p. 359).

Incremental snapshot copying across AWS Regions is supported for both unencrypted and encrypted
snapshots.

When you copy a snapshot across AWS Regions, the copy is an incremental copy if the following
conditions are met:

• The snapshot was previously copied to the destination Region.

• The most recent snapshot copy still exists in the destination Region.
• All copies of the snapshot in the destination Region are either unencrypted, or were encrypted using
the same CMK.

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.

362
 Amazon Relational Database Service User Guide
Parameter groups

In some cases, you might copy a snapshot and not specify a new option group for the snapshot. In these
cases, when you restore the snapshot the DB instance gets the default option group. To give the new DB
instance the same options as the original, 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
the default parameter group for the AWS Region it is created in. To give the new DB instance the same
parameters as the original, 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. 358)

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.

Console
The following 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. For Actions, choose Copy snapshot.

The Copy snapshot page appears.

363
 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.

364
 Amazon Relational Database Service User Guide
Copying a DB snapshot

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 nondefault 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. 362).
8. (Optional) Select Copy Tags to copy tags and values from the snapshot to the copy of the snapshot.
9. (Optional) For Encryption, do the following:

a. Choose Enable Encryption if the DB snapshot isn't encrypted but you want to encrypt the copy.
Note
If the DB snapshot is encrypted, you must encrypt the copy, so the check box is already
selected.
b. For Master key, specify the AWS KMS key identifier to use to encrypt the DB snapshot copy.
10. Choose Copy snapshot.

AWS 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-instance1-
snapshot-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. 362).

365
 Amazon Relational Database Service User Guide
Copying a DB snapshot

• --kms-key-id – The AWS KMS key identifier for an encrypted DB snapshot. The AWS KMS key
identifier is the Amazon Resource Name (ARN), key identifier, or key alias for the AWS KMS CMK.
• 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 AWS KMS CMK. If you don't specify a value for this
parameter, then the copy of the DB snapshot is encrypted with the same AWS KMS CMK 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.
• 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 an AWS KMS
CMK for the destination AWS Region. AWS KMS CMKs 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 the 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, macOS, 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, macOS, or Unix:

aws rds copy-db-snapshot \

--source-db-snapshot-identifier arn:aws:rds:us-east-1:123456789012:snapshot:mysql-
instance1-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:mysql-
instance1-snapshot-20130805 ^
--target-db-snapshot-identifier mydbsnapshotcopy

366
 Amazon Relational Database Service User Guide
Copying a DB snapshot

Example from encrypted, across Regions

The following code example copies an encrypted DB snapshot from the US West (Oregon) Region in the
US East (N. Virginia) Region. Run the command in the destination (us-east-1) Region.

For Linux, macOS, or Unix:

aws rds copy-db-snapshot \

--source-db-snapshot-identifier arn:aws:rds:us-west-2:123456789012:snapshot:mysql-
instance1-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:mysql-
instance1-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

RDS API
You can copy a DB snapshot by using the Amazon RDS API operation 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-instance1-
snapshot-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. 362).
• KmsKeyId – The AWS KMS key identifier for an encrypted DB snapshot. The AWS KMS key identifier is
the Amazon Resource Name (ARN), key identifier, or key alias for the AWS KMS CMK.

367
 Amazon Relational Database Service User Guide
Copying a DB snapshot

• 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 AWS KMS CMK. If you don't specify a value for this
parameter, then the copy of the DB snapshot is encrypted with the same AWS KMS CMK 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.
• 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 an AWS KMS
CMK for the destination AWS Region. AWS KMS CMKs 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 operation in the source AWS Region that contains the source DB snapshot to
copy.

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 operation that can be run in
the source AWS Region containing 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 operation is called that contains this
presigned URL.

For example, suppose that you copy an encrypted DB snapshot from the us-west-2 Region to the us-
east-1 Region. You then call the CopyDBSnapshot operation in the us-east-1 Region and provide a
presigned URL that contains a call to the CopyDBSnapshot operation 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 AWS 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 operation
that is called in the destination AWS Region, and the operation 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:us-
west-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 the 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

368
 Amazon Relational Database Service User Guide
Copying a DB snapshot

&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 unencrypted, across Regions

The following code creates a copy of a snapshot, with the new name mydbsnapshotcopy, in the US
West (N. California) Region.

https://rds.us-west-1.amazonaws.com/
?Action=CopyDBSnapshot
&SignatureMethod=HmacSHA256
&SignatureVersion=4
&SourceDBSnapshotIdentifier=arn%3Aaws%3Ards%3Aus-east-1%3A123456789012%3Asnapshot%3Amysql-
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

Example from encrypted, across Regions

The following code creates a copy of a snapshot, with the new name mydbsnapshotcopy, in the US East
(N. Virginia) 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%25253Aus-
west-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-amz-
content-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

369
 Amazon Relational Database Service User Guide
Copying a DB snapshot

&X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date
&X-Amz-Signature=da4f2da66739d2e722c85fcfd225dc27bba7e2b8dbea8d8612434378e52adccf

370
 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. This process also applies to AWS Backup–generated
resources.

For more information on copying a snapshot, see Copying a snapshot (p. 358). For more information on
restoring a DB instance from a DB snapshot, see Restoring from a DB snapshot (p. 355).

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.

You can use the following AWS CLI command (Unix only) to find the public snapshots for your AWS
account in a particular AWS Region:

aws rds describe-db-snapshots --snapshot-type public --include-public | grep account_number

The output returned is similar to the following example if you have public snapshots:

"DBSnapshotArn": "arn:aws:rds:us-east-1:123456789012:snapshot:mysnapshot1",
"DBSnapshotArn": "arn:aws:rds:us-east-1:123456789012:snapshot:mysnapshot2",

Note
You might see duplicate entries for DBSnapshotIdentifier or
SourceDBSnapshotIdentifier.

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,
except for Oracle DB instances that have the Timezone or OLS option (or both).

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

371
 Amazon Relational Database Service User Guide
Sharing an encrypted snapshot

Option name Persistent Permanent DB engine

TDE Yes Yes Oracle Enterprise Edition

Timezone Yes Yes Oracle Enterprise Edition

Oracle Standard Edition

Oracle Standard Edition One

Oracle Standard Edition Two

For Oracle DB instances, you can copy shared DB snapshots that have the Timezone or OLS option
(or both). To do so, specify a target option group that includes these options when you copy the DB
snapshot. The OLS option is permanent and persistent only for Oracle DB instances running Oracle
version 12.2 or higher. For more information about these options, see Oracle time zone (p. 1204) and
Oracle Label Security (p. 1170).

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. 1620). To do this, you must take the following
steps:

1. Share the AWS Key Management Service (AWS KMS) customer master key (CMK) 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 CMKs with another AWS account by adding the other account to the AWS
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 customer master key
(CMK) (p. 372) 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 CMK of the AWS
account that shared the snapshot.

Allowing access to an AWS KMS customer master key (CMK)

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 AWS KMS customer master key (CMK) that
encrypted the snapshot. To allow another AWS account access to an AWS KMS CMK, update the key
policy for the AWS KMS CMK with the ARN of the AWS account that you are sharing to as a Principal
in the AWS KMS key policy, and then allow the kms:CreateGrant action.

After you have given an AWS account access to your AWS KMS CMK, 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 AWS KMS CMK. The account must be an IAM user
and cannot be a root AWS account identity due to AWS KMS security restrictions.

372
 Amazon Relational Database Service User Guide
Sharing an encrypted snapshot

In the following key policy example, user 111122223333 is the owner of the AWS KMS CMK, and user
444455556666 is the account that the key is being shared with. This updated key policy gives the AWS
account access to the AWS KMS CMK 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",
"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 AWS KMS customer master key (CMK), 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 AWS KMS CMK.

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 AWS KMS CMK c989c1dd-a3f2-4a5d-8d96-e793d082ab26 in the
us-west-2 region.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowUseOfTheKey",
"Effect": "Allow",

373
 Amazon Relational Database Service User Guide
Sharing a snapshot

"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-8d96-
e793d082ab26"]
},
{
"Sid": "AllowAttachmentOfPersistentResources",
"Effect": "Allow",
"Action": [
"kms:CreateGrant",
"kms:ListGrants",
"kms:RevokeGrant"
],
"Resource": ["arn:aws:kms:us-west-2:111122223333:key/c989c1dd-a3f2-4a5d-8d96-
e793d082ab26"],
"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.

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. For Actions, 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.

374
 Amazon Relational Database Service User Guide
Sharing a snapshot

• 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.

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.

375
 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.

Example of sharing a snapshot with a single account

The following example enables AWS account identifier 123456789012 to restore the DB snapshot
named db7-snapshot.

For Linux, macOS, or Unix:

aws rds modify-db-snapshot-attribute \

--db-snapshot-identifier db7-snapshot \
--attribute-name restore \
--values-to-add 123456789012

For Windows:

aws rds modify-db-snapshot-attribute ^

--db-snapshot-identifier db7-snapshot ^
--attribute-name restore ^
--values-to-add 123456789012

376
 Amazon Relational Database Service User Guide
Sharing a snapshot

Example of sharing a snapshot with multiple accounts

The following example enables two AWS account identifiers, 111122223333 and 444455556666, to
restore the DB snapshot named manual-snapshot1.

For Linux, macOS, or Unix:

aws rds modify-db-snapshot-attribute \

--db-snapshot-identifier manual-snapshot1 \
--attribute-name restore \
--values-to-add {"111122223333","444455556666"}

For Windows:

aws rds modify-db-snapshot-attribute ^

--db-snapshot-identifier manual-snapshot1 ^
--attribute-name restore ^
--values-to-add "[\"111122223333\",\"444455556666\"]"

Note
When using the Windows command prompt, you must escape double quotes (") in JSON code by
prefixing them with a backslash (\).

To remove an AWS account identifier from the list, use the --values-to-remove parameter.

Example of stopping snapshot sharing

The following example prevents AWS account ID 444455556666 from restoring the snapshot.

For Linux, macOS, or Unix:

aws rds modify-db-snapshot-attribute \

--db-snapshot-identifier manual-snapshot1 \
--attribute-name restore \
--values-to-remove 444455556666

For Windows:

aws rds modify-db-snapshot-attribute ^

--db-snapshot-identifier manual-snapshot1 ^
--attribute-name restore ^
--values-to-remove 444455556666

To list the AWS accounts enabled to restore a snapshot, use the describe-db-snapshot-attributes
AWS CLI command.

RDS 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 operation. 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.

377
 Amazon Relational Database Service User Guide
Sharing a snapshot

To remove sharing permission for an AWS account, use the ModifyDBSnapshotAttribute operation
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 operation.

378
 Amazon Relational Database Service User Guide
Exporting snapshot data to Amazon S3

Exporting DB snapshot data to Amazon S3

You can export DB snapshot data to an Amazon S3 bucket. After the data is exported, you can analyze
the exported data directly through tools like Amazon Athena or Amazon Redshift Spectrum. The export
process runs in the background and doesn't affect the performance of your active DB instance.

When you export a DB snapshot, Amazon RDS extracts data from the snapshot and stores it in an
Amazon S3 bucket in your account. The data is stored in an Apache Parquet format that is compressed
and consistent.

You can export all types of DB snapshots—including manual snapshots, automated system snapshots,
and snapshots created by the AWS Backup service. By default, all data in the snapshot is exported.
However, you can choose to export specific sets of databases, schemas, or tables.

Amazon RDS supports exporting snapshots in all AWS Regions except the following:

• AWS GovCloud (US-East)

• AWS GovCloud (US-West)

The following table shows the engine versions that are supported for exporting snapshot data to
Amazon S3.

MariaDB MySQL PostgreSQL

10.3 8.0.13 and higher 11.2 and higher

10.2.12 and higher 5.7.24 and higher 10.7 and higher

10.1.26 and higher 5.6.40 and higher 9.6.6–9.6.9, 9.6.12 and higher

10.0.32 and higher

For complete lists of engine versions supported by Amazon RDS, see the following:

• MariaDB on Amazon RDS versions (p. 583)

• MySQL on Amazon RDS versions (p. 832)
• Supported PostgreSQL database versions (p. 1569)

Topics
• Limitations (p. 380)
• Overview of exporting snapshot data (p. 380)
• Setting up access to an Amazon S3 bucket (p. 380)
• Exporting a snapshot to an Amazon S3 bucket (p. 383)
• Monitoring snapshot exports (p. 385)
• Canceling a snapshot export task (p. 386)
• Troubleshooting PostgreSQL permissions errors (p. 387)
• File naming convention (p. 388)
• Data conversion when exporting to an Amazon S3 bucket (p. 388)

379
 Amazon Relational Database Service User Guide
Limitations

Limitations
Exporting DB snapshot data to S3 has the following limitations:

• Exporting snapshots from DB instances that use magnetic storage isn't supported.
• If a database, schema, or table has characters in its name other than the following, partial export isn't
supported. However, you can export the entire DB snapshot.
• Latin letters (A–Z)
• Digits (0–9)
• Dollar symbol ($)
• Underscore (_)
• Some characters aren't supported in database table column names. Tables with the following
characters in column names are skipped during export:

, ; { } ( ) \n \t =

• If the data contains a huge value close to or greater than 500 MB, the export fails.

Overview of exporting snapshot data

You use the following process to export DB snapshot data to an Amazon S3 bucket. For more details, see
the following sections.

1. Identify the snapshot to export.

Use an existing automated or manual snapshot, or create a manual snapshot of a DB instance.

2. Set up access to the Amazon S3 bucket.

A bucket is a container for Amazon S3 objects or files. To provide the information to access a bucket,
take the following steps:

a. Identify the S3 bucket where the snapshot is to be exported to. The S3 bucket must be in the
same AWS Region as the snapshot. For more information, see Identifying the Amazon S3 bucket
for export (p. 381).
b. Create an AWS Key Management Service (AWS KMS) customer master key (CMK) for the
server-side encryption. The AWS KMS CMK is used by the snapshot export task to set up AWS
KMS server-side encryption when writing the export data to S3. For more information, see
Encrypting Amazon RDS resources (p. 1620).
c. Create an AWS Identity and Access Management (IAM) role that grants the snapshot export task
access to the S3 bucket. For more information, see Providing access to an Amazon S3 bucket
using an IAM role (p. 381).
3. Export the snapshot to Amazon S3 using the console or the start-export-task CLI command.
For more information, see Exporting a snapshot to an Amazon S3 bucket (p. 383).
4. To access your exported data in the Amazon S3 bucket, see Uploading, downloading, and managing
objects in the Amazon Simple Storage Service Console User Guide.

Setting up access to an Amazon S3 bucket

To export DB snapshot data to an Amazon S3 file, you first give the snapshot permission to access the
Amazon S3 bucket. You then create an IAM role to allow the Amazon RDS service to write to the Amazon
S3 bucket.

380
 Amazon Relational Database Service User Guide
Setting up access to an S3 bucket

Topics
• Identifying the Amazon S3 bucket for export (p. 381)
• Providing access to an Amazon S3 bucket using an IAM role (p. 381)

Identifying the Amazon S3 bucket for export

Identify the Amazon S3 bucket to export the DB snapshot to. Use an existing S3 bucket or create a new
S3 bucket.
Note
The S3 bucket to export to must be in the same AWS Region as the snapshot.

For more information about working with Amazon S3 buckets, see the following in the Amazon Simple
Storage Service Console User Guide:

• How do I view the properties for an S3 bucket?

• How do I enable default encryption for an Amazon S3 bucket?
• How do I create an S3 bucket?

Providing access to an Amazon S3 bucket using an IAM role

Before you export DB snapshot data to Amazon S3, give the snapshot export tasks write-access
permission to the Amazon S3 bucket.

To do this, create an IAM policy that provides access to the bucket. Then create an IAM role and attach
the policy to the role. You later assign the IAM role to your snapshot export task.
Important
If you plan to use the AWS Management Console to export your snapshot, you can choose to
create the IAM policy and the role automatically when you export the snapshot. For instructions,
see Exporting a snapshot to an Amazon S3 bucket (p. 383).

To give DB snapshot tasks access to Amazon S3

1. Create an IAM policy. This policy provides the bucket and object permissions that allow your
snapshot export task to access Amazon S3.

Include in the policy the following required actions to allow the transfer of files from Amazon RDS
to an S3 bucket:

• s3:PutObject*
• s3:GetObject*
• s3:ListBucket
• s3:DeleteObject*
• s3:GetBucketLocation

Include in the policy the following resources to identify the S3 bucket and objects in the bucket. The
following list of resources shows the Amazon Resource Name (ARN) format for accessing Amazon S3.

• arn:aws:s3:::your-s3-bucket
• arn:aws:s3:::your-s3-bucket/*

381
 Amazon Relational Database Service User Guide
Setting up access to an S3 bucket

For more information on creating an IAM policy for Amazon RDS, see Creating and using an IAM
policy for IAM database access (p. 1654). See also Tutorial: Create and attach your first customer
managed policy in the IAM User Guide.

The following AWS CLI command creates an IAM policy named ExportPolicy with these options. It
grants access to a bucket named your-s3-bucket.
Note
After you create the policy, note the ARN of the policy. You need the ARN for a subsequent
step when you attach the policy to an IAM role.

aws iam create-policy --policy-name ExportPolicy --policy-document '{

"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListBucket",
"s3:GetBucketLocation"
],
"Resource": [
"arn:aws:s3:::*"
]
},
{
"Effect": "Allow",
"Action": [
"s3:PutObject*",
"s3:GetObject*",
"s3:CopyObject*",
"s3:DeleteObject*"
],
"Resource": [
"arn:aws:s3:::your-s3-bucket",
"arn:aws:s3:::your-s3-bucket/*"
]
}
]
}'

2. Create an IAM role. You do this so that Amazon RDS can assume this IAM role on your behalf to
access your Amazon S3 buckets. For more information, see Creating a role to delegate permissions
to an IAM user in the IAM User Guide.

The following example shows using the AWS CLI command to create a role named rds-s3-
export-role.

aws iam create-role --role-name rds-s3-export-role --assume-role-policy-document '{

"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "export.rds.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}'

3. Attach the IAM policy that you created to the IAM role that you created.

382
 Amazon Relational Database Service User Guide
Exporting a snapshot to an S3 bucket

The following AWS CLI command attaches the policy created earlier to the role named rds-s3-
export-role. Replace your-policy-arn with the policy ARN that you noted in an earlier step.

aws iam attach-role-policy --policy-arn your-policy-arn --role-name rds-s3-export-

role

Exporting a snapshot to an Amazon S3 bucket

You can have up to five concurrent DB snapshot export tasks in progress per account.
Note
Exporting RDS snapshots can take a while depending on your database type and size. The
export task first restores and scales the entire database before extracting the data to Amazon
S3. The task's progress during this phase displays as Starting. When the task switches to
exporting data to S3, progress displays as In progress.
The time it takes for the export to complete depends on the data stored in the database.
For example, tables with well distributed numeric primary key or index columns will export
the fastest. Tables that don't contain a column suitable for partitioning and tables with only
one index on a string-based column will take longer because the export uses a slower single
threaded process.

You can export a DB snapshot to Amazon S3 using the AWS Management Console, the AWS CLI, or the
RDS API.

If you use a Lambda function to export a snapshot, add the kms:DescribeKey action to the Lambda
function policy. For more information, see AWS Lambda permissions.

Console
The Export to Amazon S3 console option appears only for snapshots that can be exported to Amazon
S3. A snapshot might not be available for export because of the following reasons:

• The DB engine isn't supported for S3 export.

• The DB instance version isn't supported for S3 export.
• S3 export isn't supported in the AWS Region where the snapshot was created.

To export 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. From the tabs, choose the type of snapshot that you want to export.
4. In the list of snapshots, choose the snapshot that you want to export.
5. For Actions, choose Export to Amazon S3.

The Export to Amazon S3 window appears.

6. For Export identifier, enter a name to identify the export task. This value is also used for the name
of the file created in the S3 bucket.
7. Choose the amount of data to be exported:

• Choose All to export all data in the snapshot.

• Choose Partial to export specific parts of the snapshot. To identify which parts of the snapshot to
export, enter one or more tables for Identifiers.

383
 Amazon Relational Database Service User Guide
Exporting a snapshot to an S3 bucket

8. For S3 bucket, choose the bucket to export to.

To assign the exported data to a folder path in the S3 bucket, enter the optional path for S3 prefix.
9. For IAM role, either choose a role that grants you write access to your chosen S3 bucket, or create a
new role.

• If you created a role by following the steps in Providing access to an Amazon S3 bucket using an
IAM role (p. 381), choose that role.
• If you didn't create a role that grants you write access to your chosen S3 bucket, choose Create a
new role to create the role automatically. Next, enter a name for the role in IAM role name.
10. For Master key, enter the ARN for the key to use for encrypting the exported data.
11. Choose Export to Amazon S3.

AWS CLI
To export a DB snapshot to Amazon S3 using the AWS CLI, use the start-export-task command with the
following required options:

• --export-task-identifier
• --source-arn
• --s3-bucket-name
• --iam-role-arn
• --kms-key-id

In the following examples, the snapshot export task is named my_snapshot_export, which exports a
snapshot to an S3 bucket named my_export_bucket.

Example
For Linux, macOS, or Unix:

aws rds start-export-task \

--export-task-identifier my_snapshot_export \
--source-arn arn:aws:rds:AWS_Region:123456789012:snapshot:snapshot_name \
--s3-bucket-name my_export_bucket \
--iam-role-arn iam_role \
--kms-key-id master_key

For Windows:

aws rds start-export-task ^

--export-task-identifier my_snapshot_export ^
--source-arn arn:aws:rds:AWS_Region:123456789012:snapshot:snapshot_name ^
--s3-bucket-name my_export_bucket ^
--iam-role-arn iam_role ^
--kms-key-id master_key

Sample output follows.

{
"Status": "STARTING",
"IamRoleArn": "iam_role",
"ExportTime": "2019-08-12T01:23:53.109Z",
"S3Bucket": "my_export_bucket",
"PercentProgress": 0,
"KmsKeyId": "master_key",

384
 Amazon Relational Database Service User Guide
Monitoring snapshot exports

"ExportTaskIdentifier": "my_snapshot_export",
"TotalExtractedDataInGB": 0,
"TaskStartTime": "2019-11-13T19:46:00.173Z",
"SourceArn": "arn:aws:rds:AWS_Region:123456789012:snapshot:snapshot_name"
}

To provide a folder path in the S3 bucket for the snapshot export, include the --s3-prefix option in
the start-export-task command.

RDS API
To export a DB snapshot to Amazon S3 using the Amazon RDS API, use the StartExportTask operation
with the following required parameters:

• ExportTaskIdentifier
• SourceArn
• S3BucketName
• IamRoleArn
• KmsKeyId

Monitoring snapshot exports

You can monitor DB snapshot exports using the AWS Management Console, the AWS CLI, or the RDS API.

Console
To monitor DB snapshot exports

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. To view the list of snapshot exports, choose the Exports in Amazon S3 tab.
4. To view information about a specific snapshot export, choose the export task.

AWS CLI
To monitor DB snapshot exports using the AWS CLI, use the describe-export-tasks command.

The following example shows how to display current information about all of your snapshot exports.

Example

aws rds describe-export-tasks

{
"ExportTasks": [
{
"Status": "CANCELED",
"TaskEndTime": "2019-11-01T17:36:46.961Z",
"S3Prefix": "something",
"ExportTime": "2019-10-24T20:23:48.364Z",
"S3Bucket": "examplebucket",
"PercentProgress": 0,
"KmsKeyId": "arn:aws:kms:AWS_Region:123456789012:key/K7MDENG/
bPxRfiCYEXAMPLEKEY",
"ExportTaskIdentifier": "anewtest",

385
 Amazon Relational Database Service User Guide
Canceling a snapshot export

"IamRoleArn": "arn:aws:iam::123456789012:role/export-to-s3",
"TotalExtractedDataInGB": 0,
"TaskStartTime": "2019-10-25T19:10:58.885Z",
"SourceArn": "arn:aws:rds:AWS_Region:123456789012:snapshot:parameter-groups-
test"
},
{
"Status": "COMPLETE",
"TaskEndTime": "2019-10-31T21:37:28.312Z",
"WarningMessage": "{\"skippedTables\":[],\"skippedObjectives\":[],\"general\":
[{\"reason\":\"FAILED_TO_EXTRACT_TABLES_LIST_FOR_DATABASE\"}]}",
"S3Prefix": "",
"ExportTime": "2019-10-31T06:44:53.452Z",
"S3Bucket": "examplebucket1",
"PercentProgress": 100,
"KmsKeyId": "arn:aws:kms:AWS_Region:123456789012:key/2Zp9Utk/
h3yCo8nvbEXAMPLEKEY",
"ExportTaskIdentifier": "thursday-events-test",
"IamRoleArn": "arn:aws:iam::123456789012:role/export-to-s3",
"TotalExtractedDataInGB": 263,
"TaskStartTime": "2019-10-31T20:58:06.998Z",
"SourceArn":
"arn:aws:rds:AWS_Region:123456789012:snapshot:rds:example-1-2019-10-31-06-44"
},
{
"Status": "FAILED",
"TaskEndTime": "2019-10-31T02:12:36.409Z",
"FailureCause": "The S3 bucket edgcuc-export isn't located in the current AWS
Region. Please, review your S3 bucket name and retry the export.",
"S3Prefix": "",
"ExportTime": "2019-10-30T06:45:04.526Z",
"S3Bucket": "examplebucket2",
"PercentProgress": 0,
"KmsKeyId": "arn:aws:kms:AWS_Region:123456789012:key/2Zp9Utk/
h3yCo8nvbEXAMPLEKEY",
"ExportTaskIdentifier": "wednesday-afternoon-test",
"IamRoleArn": "arn:aws:iam::123456789012:role/export-to-s3",
"TotalExtractedDataInGB": 0,
"TaskStartTime": "2019-10-30T22:43:40.034Z",
"SourceArn":
"arn:aws:rds:AWS_Region:123456789012:snapshot:rds:example-1-2019-10-30-06-45"
}
]
}

To display information about a specific snapshot export, include the --export-task-identifier

option with the describe-export-tasks command. To filter the output, include the --Filters
option. For more options, see the describe-export-tasks command.

RDS API
To display information about DB snapshot exports using the Amazon RDS API, use the
DescribeExportTasks operation.

To track completion of the export workflow or to trigger another workflow, you can subscribe to Amazon
Simple Notification Service topics. For more information on Amazon SNS, see Using Amazon RDS event
notification (p. 493).

Canceling a snapshot export task

You can cancel a DB snapshot export task using the AWS Management Console, the AWS CLI, or the RDS
API.

386
 Amazon Relational Database Service User Guide
Troubleshooting PostgreSQL permissions errors

Note
Canceling a snapshot export task doesn't remove any data that was exported to Amazon S3. For
information about how to delete the data using the console, see How do I delete objects from
an S3 bucket? To delete the data using the CLI, use the delete-object command.

Console
To cancel a snapshot export task

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 Exports in Amazon S3 tab.
4. Choose the snapshot export task that you want to cancel.
5. Choose Cancel.
6. Choose Cancel export task on the confirmation page.

AWS CLI
To cancel a snapshot export task using the AWS CLI, use the cancel-export-task command. The command
requires the --export-task-identifier option.

Example

aws rds cancel-export-task --export-task-identifier my_export

{
"Status": "CANCELING",
"S3Prefix": "",
"ExportTime": "2019-08-12T01:23:53.109Z",
"S3Bucket": "examplebucket",
"PercentProgress": 0,
"KmsKeyId": "arn:aws:kms:AWS_Region:123456789012:key/K7MDENG/bPxRfiCYEXAMPLEKEY",
"ExportTaskIdentifier": "my_export",
"IamRoleArn": "arn:aws:iam::123456789012:role/export-to-s3",
"TotalExtractedDataInGB": 0,
"TaskStartTime": "2019-11-13T19:46:00.173Z",
"SourceArn": "arn:aws:rds:AWS_Region:123456789012:snapshot:export-example-1"
}

RDS API
To cancel a snapshot export task using the Amazon RDS API, use the CancelExportTask operation with
the ExportTaskIdentifier parameter.

Troubleshooting PostgreSQL permissions errors

When exporting PostgreSQL databases to Amazon S3, you might see a PERMISSIONS_DO_NOT_EXIST
error stating that certain tables were skipped. This is usually caused by the superuser, which you specify
when creating the DB instance, not having permissions to access those tables.

To fix this error, run the following command:

GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA schema_name TO superuser_name

For more information on superuser privileges, see Master user account privileges (p. 1699).

387
 Amazon Relational Database Service User Guide
File naming convention

File naming convention

Exported data for specific tables is stored in the format base_prefix/files, where the base prefix is
the following:

export_identifier/database_name/schema_name.table_name/

For example:

export-1234567890123-459/rdststdb/rdststdb.DataInsert_7ADB5D19965123A2/

There are two conventions for how files are named:

• part-partition_index-random_uuid.format-based_extension
• partition_index/part-00000-random_uuid.format-based_extension

For example:

part-00000-c5a881bb-58ff-4ee6-1111-b41ecff340a3-c000.gz.parquet
part-00001-d7a881cc-88cc-5ab7-2222-c41ecab340a4-c000.gz.parquet
part-00002-f5a991ab-59aa-7fa6-3333-d41eccd340a7-c000.gz.parquet

1/part-00000-c5a881bb-58ff-4ee6-1111-b41ecff340a3-c000.gz.parquet
2/part-00000-d7a881cc-88cc-5ab7-2222-c41ecab340a4-c000.gz.parquet
3/part-00000-f5a991ab-59aa-7fa6-3333-d41eccd340a7-c000.gz.parquet

The file naming convention is subject to change. Therefore, when reading target tables we recommend
that you read everything inside the base prefix for the table.

Data conversion when exporting to an Amazon S3

bucket
When you export a DB snapshot to an Amazon S3 bucket, Amazon RDS converts data to, exports data
in, and stores data in the Parquet format. For more information about Parquet, see the Apache Parquet
website.
Parquet stores all data as one of the following primitive types:

• BOOLEAN
• INT32
• INT64
• INT96
• FLOAT
• DOUBLE
• BYTE_ARRAY – A variable-length byte array, also known as binary
• FIXED_LEN_BYTE_ARRAY – A fixed-length byte array used when the values have a constant size

The Parquet data types are few to reduce the complexity of reading and writing the format. Parquet
provides logical types for extending primitive types. A logical type is implemented as an annotation with
the data in a LogicalType metadata field. The logical type annotation explains how to interpret the
primitive type.

388
 Amazon Relational Database Service User Guide
Data conversion

When the STRING logical type annotates a BYTE_ARRAY type, it indicates that the byte array should be
interpreted as a UTF-8 encoded character string. After an export task completes, Amazon RDS notifies
you if any string conversion occurred. The underlying data exported is always the same as the data from
the source. However, due to the encoding difference in UTF-8, some characters might appear different
from the source when read in tools such as Athena.

For more information, see Parquet logical type definitions in the Parquet documentation.

Topics
• MySQL and MariaDB data type mapping to Parquet (p. 389)
• PostgreSQL data type mapping to Parquet (p. 391)

MySQL and MariaDB data type mapping to Parquet

The following table shows the mapping from MySQL and MariaDB data types to Parquet data types
when data is converted and exported to Amazon S3.

Source data type Parquet primitive type Logical type Conversion notes
annotation

Numeric data types

BIGINT INT64  

BIGINT UNSIGNED FIXED_LEN_BYTE_ARRAY(9)

DECIMAL(20,0) Parquet supports only
signed types, so the
mapping requires an
additional byte (8
plus 1) to store the
BIGINT_UNSIGNED
type.

BIT BYTE_ARRAY  

DECIMAL INT32 DECIMAL(p,s) If the source value is

31
less than 2 , it's stored
as INT32.
31
INT64 DECIMAL(p,s) If the source value is 2
or greater, but less than
63
2 , it's stored as INT64.
63
FIXED_LEN_BYTE_ARRAY(N)
DECIMAL(p,s) If the source value is 2
or greater, it's stored as
FIXED_LEN_BYTE_ARRAY(N).

BYTE_ARRAY STRING Parquet doesn't support

Decimal precision
greater than 38.
The Decimal value is
converted to a string in
a BYTE_ARRAY type and
encoded as UTF8.

DOUBLE DOUBLE  

FLOAT DOUBLE  

389
 Amazon Relational Database Service User Guide
Data conversion

Source data type Parquet primitive type Logical type Conversion notes
annotation

INT INT32  

INT UNSIGNED INT64  

MEDIUMINT INT32  

MEDIUMINT UNSIGNED INT64  

NUMERIC INT32 DECIMAL(p,s) If the source value is

31
less than 2 , it's stored
as INT32.
31
INT64 DECIMAL(p,s) If the source value is 2
or greater, but less than
63
2 , it's stored as INT64.
63
FIXED_LEN_ARRAY(N) DECIMAL(p,s) If the source value is 2
or greater, it's stored as
FIXED_LEN_BYTE_ARRAY(N).

BYTE_ARRAY STRING Parquet doesn't support

Numeric precision
greater than 38. This
Numeric value is
converted to a string in
a BYTE_ARRAY type and
encoded as UTF8.

SMALLINT INT32  

SMALLINT UNSIGNED INT32  

TINYINT INT32  

TINYINT UNSIGNED INT32  

String data types

BINARY BYTE_ARRAY  

BLOB BYTE_ARRAY  

CHAR BYTE_ARRAY  

ENUM BYTE_ARRAY STRING

LINESTRING BYTE_ARRAY  

LONGBLOB BYTE_ARRAY  

LONGTEXT BYTE_ARRAY STRING

MEDIUMBLOB BYTE_ARRAY  

MEDIUMTEXT BYTE_ARRAY STRING

MULTILINESTRING BYTE_ARRAY  

SET BYTE_ARRAY STRING

390
 Amazon Relational Database Service User Guide
Data conversion

Source data type Parquet primitive type Logical type Conversion notes
annotation

TEXT BYTE_ARRAY STRING

TINYBLOB BYTE_ARRAY  

TINYTEXT BYTE_ARRAY STRING

VARBINARY BYTE_ARRAY  

VARCHAR BYTE_ARRAY STRING

Date and time data types

DATE BYTE_ARRAY STRING A date is converted to a

string in a BYTE_ARRAY
type and encoded as
UTF8.

DATETIME INT64 TIMESTAMP_MICROS

TIME BYTE_ARRAY STRING A TIME type is

converted to a string
in a BYTE_ARRAY and
encoded as UTF8.

TIMESTAMP INT64 TIMESTAMP_MICROS

YEAR INT32  

Geometric data types

GEOMETRY BYTE_ARRAY  

GEOMETRYCOLLECTION BYTE_ARRAY  

MULTIPOINT BYTE_ARRAY  

MULTIPOLYGON BYTE_ARRAY  

POINT BYTE_ARRAY  

POLYGON BYTE_ARRAY  

JSON data type

JSON BYTE_ARRAY STRING

PostgreSQL data type mapping to Parquet

The following table shows the mapping from PostgreSQL data types to Parquet data types when data is
converted and exported to Amazon S3.

PostgreSQL data type Parquet primitive type Logical type Mapping notes
annotation

Numeric data types

391
 Amazon Relational Database Service User Guide
Data conversion

PostgreSQL data type Parquet primitive type Logical type Mapping notes
annotation

BIGINT INT64  

BIGSERIAL INT64  

DECIMAL BYTE_ARRAY STRING A DECIMAL type is

converted to a string in
a BYTE_ARRAY type and
encoded as UTF8.

This conversion is to
avoid complications due
to data precision and
data values that are not
a number (NaN).

DOUBLE PRECISION DOUBLE  

INTEGER INT32  

MONEY BYTE_ARRAY STRING

REAL FLOAT  

SERIAL INT32  

SMALLINT INT32 INT_16

SMALLSERIAL INT32 INT_16

String and related data types

ARRAY BYTE_ARRAY STRING An array is converted to

a string and encoded as
BINARY (UTF8).

This conversion is to
avoid complications due
to data precision, data
values that are not a
number (NaN), and time
data values.

BIT BYTE_ARRAY STRING

BIT VARYING BYTE_ARRAY STRING

BYTEA BINARY  

CHAR BYTE_ARRAY STRING

CHAR(N) BYTE_ARRAY STRING

ENUM BYTE_ARRAY STRING

NAME BYTE_ARRAY STRING

TEXT BYTE_ARRAY STRING

392
 Amazon Relational Database Service User Guide
Data conversion

PostgreSQL data type Parquet primitive type Logical type Mapping notes
annotation

TEXT SEARCH BYTE_ARRAY STRING

VARCHAR(N) BYTE_ARRAY STRING

XML BYTE_ARRAY STRING

Date and time data types

DATE BYTE_ARRAY STRING

INTERVAL BYTE_ARRAY STRING

TIME BYTE_ARRAY STRING  

TIME WITH TIME ZONE BYTE_ARRAY STRING  

TIMESTAMP BYTE_ARRAY STRING  

TIMESTAMP WITH TIME BYTE_ARRAY STRING  

ZONE

Geometric data types

BOX BYTE_ARRAY STRING

CIRCLE BYTE_ARRAY STRING

LINE BYTE_ARRAY STRING

LINESEGMENT BYTE_ARRAY STRING

PATH BYTE_ARRAY STRING

POINT BYTE_ARRAY STRING

POLYGON BYTE_ARRAY STRING

JSON data types

JSON BYTE_ARRAY STRING

JSONB BYTE_ARRAY STRING

Other data types

BOOLEAN BOOLEAN  

CIDR BYTE_ARRAY STRING Network data type

COMPOSITE BYTE_ARRAY STRING

DOMAIN BYTE_ARRAY STRING

INET BYTE_ARRAY STRING Network data type

MACADDR BYTE_ARRAY STRING

OBJECT IDENTIFIER N/A    

PG_LSN BYTE_ARRAY STRING

393
 Amazon Relational Database Service User Guide
Data conversion

PostgreSQL data type Parquet primitive type Logical type Mapping notes
annotation

RANGE BYTE_ARRAY STRING

UUID BYTE_ARRAY STRING

394
 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 operation after the DB instance is available.

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.

RDS uploads transaction logs for DB instances to Amazon S3 every 5 minutes. To see 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. To see the latest restorable
time for each DB instance in the Amazon RDS console, choose Automated backups.

You can restore to any point in time within your backup retention period. To see the earliest restorable
time for each DB instance, choose Automated backups in the Amazon RDS console.

Note
We recommend that you restore to the same or similar DB instance size—and IOPS if using
Provisioned IOPS storage—as the source DB instance. You might get an error if, for example, you
choose a DB instance size with an incompatible IOPS value.

Some 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 might be restored inconsistently.
• For a SQL Server DB instance, the OFFLINE, EMERGENCY, and SINGLE_USER modes aren't supported.
Setting any database into one of these modes causes 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 isn't detected. It

395
 Amazon Relational Database Service User Guide
Point-in-time recovery

might 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 doesn't support changing the recovery model of SQL
Server databases.

Note
You can also use AWS Backup to manage backups of Amazon RDS DB instances. If your
DB instance is associated with a backup plan in AWS Backup, that backup plan is used for
point-in-time recovery. Backups that were created with AWS Backup have names ending in
awsbackup:AWS-Backup-job-number. For information about AWS Backup, see the AWS
Backup Developer Guide.

You can restore a DB instance to a point in time using the AWS Management Console, the AWS CLI, or
the RDS API.

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 Automated backups.
3. Choose the DB instance that you want to restore.
4. For Actions, choose Restore to point in time.

The Restore to point in time 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 to which you want to restore the instance.
Note
Times are shown in your local time zone, which is indicated by an offset from Coordinated
Universal Time (UTC). For example, UTC-5 is Eastern Standard Time/Central Daylight Time.
6. For DB instance identifier, enter the name of the target restored DB instance.
7. Choose other options as needed, such as DB instance class, storage, and whether you want to use
storage autoscaling.
8. Choose Restore to point in time.

AWS CLI
To restore a DB instance to a specified time, use the AWS CLI command restore-db-instance-to-
point-in-time to create a new DB instance. This example also enables storage autoscaling.

Example

For Linux, macOS, 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 \
--max-allocated-storage 1000

For Windows:

396
 Amazon Relational Database Service User Guide
Point-in-time recovery

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 ^
--max-allocated-storage 1000

RDS API
To restore a DB instance to a specified time, call the Amazon RDS API
RestoreDBInstanceToPointInTime operation with the following parameters:

• SourceDBInstanceIdentifier
• TargetDBInstanceIdentifier
• RestoreTime

397
 Amazon Relational Database Service User Guide
Deleting a snapshot

Deleting a snapshot
You can delete DB snapshots managed by Amazon RDS when you no longer need them.
Note
To delete backups managed by AWS Backup, use the AWS Backup console. For information
about AWS Backup, see the AWS Backup Developer Guide.

Deleting a DB snapshot
You can delete a manual, shared, or public DB snapshot using the AWS Management Console, the AWS
CLI, or the RDS API.

To delete a shared or public snapshot, you must sign in to the AWS account that owns the snapshot.

If you have automated DB snapshots that you want to delete without deleting the DB instance, change
the backup retention period for the DB instance to 0. The automated snapshots are deleted when
the change is applied. You can apply the change immediately if you don't want to wait until the next
maintenance period. After the change is complete, you can then re-enable automatic backups by setting
the backup retention period to a number greater than 0. For information about modifying a DB instance,
see Modifying an Amazon RDS DB instance (p. 256).

If you deleted a DB instance, you can delete its automated DB snapshots by removing the automated
backups for the DB instance. For information about automated backups, see Working with
backups (p. 334).

Console
To delete 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.

The Manual snapshots list appears.

3. Choose the DB snapshot that you want to delete.
4. For Actions, choose Delete Snapshot.
5. Choose Delete on the confirmation page.

AWS CLI
You can delete a DB snapshot by using the AWS CLI command delete-db-snapshot.

The following options are used to delete a DB snapshot.

• --db-snapshot-identifier – The identifier for the DB snapshot.

Example

The following code deletes the mydbsnapshot DB snapshot.

For Linux, macOS, or Unix:

aws rds delete-db-snapshot \

--db-snapshot-identifier mydbsnapshot

398
 Amazon Relational Database Service User Guide
Deleting a DB snapshot

For Windows:

aws rds delete-db-snapshot ^

--db-snapshot-identifier mydbsnapshot

RDS API
You can delete a DB snapshot by using the Amazon RDS API operation DeleteDBSnapshot.

The following parameters are used to delete a DB snapshot.

• DBSnapshotIdentifier – The identifier for the DB snapshot.

399
 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. 1707).

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
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.

400
 Amazon Relational Database Service User Guide
Restoring a DB instance from a 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. 352).
• 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. 218).

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. Choose the DB snapshot that you want to restore from.
4. For Actions, choose Restore snapshot.

The Restore snapshot page appears.

5. For DB Instance identifier under Settings, enter the unique name that you want to use for the
restored DB instance.

If you're 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 additional settings as needed.
7. Choose Restore DB Instance.

401
 Amazon Relational Database Service User Guide
Modifying a restored 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 Databases.
3. Choose the name of the DB instance created when you restored from the DB snapshot to display
its details. Choose the Connectivity tab. 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.

402
 Amazon Relational Database Service User Guide
Modifying a restored DB instance

4. Choose Modify.
5. In the Network & Security section, choose 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. 1707) for more information.

You can also remove a security group by choosing the X associated with it.

6. Choose Continue, and then choose Apply immediately.

7. Choose Modify DB Instance.

403
 Amazon Relational Database Service User Guide
Modifying a restored DB instance

After the instance status is available, choose the DB instance name to display its details. Choose
the Connectivity tab, and confirm that the new security group has been applied, making the DB
instance authorized for access.

404
 Amazon Relational Database Service User Guide

Monitoring an Amazon RDS DB

instance
This section shows you how to monitor Amazon RDS.

Topics
• Overview of monitoring Amazon RDS (p. 406)
• DB instance status (p. 410)
• Using Amazon RDS recommendations (p. 413)
• Using Performance Insights on Amazon RDS (p. 418)
• Using Enhanced Monitoring (p. 477)
• Using Amazon RDS event notification (p. 493)
• Viewing Amazon RDS events (p. 509)
• Accessing Amazon RDS database log files (p. 510)
• Monitoring Amazon RDS metrics with Amazon CloudWatch (p. 546)
• Publishing database engine logs to Amazon CloudWatch Logs (p. 554)
• Getting CloudWatch Events and Amazon EventBridge events for Amazon RDS (p. 558)
• Working with AWS CloudTrail and Amazon RDS (p. 564)

405
 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. To more easily debug multi-point failures, we recommend that you collect
monitoring data from all parts of your AWS solution.

Monitoring plan
Before you start monitoring Amazon RDS, create a monitoring plan. This plan should answer the
following questions:

• What are your monitoring goals?

• Which resources will you monitor?
• How often will you monitor these resources?
• Which monitoring tools will you use?
• Who will perform the monitoring tasks?
• Whom should be notified when something goes wrong?

Performance baseline
To achieve your monitoring goals, you need to establish a baseline. To do this, measure performance
under different load conditions at various times in your Amazon RDS environment. You can monitor
metrics such as the following:

• Network throughput
• Client connections
• I/O for read, write, or metadata operations
• Burst credit balances for your DB instances

We recommend that you store historical performance data for Amazon RDS. Using the stored data, you
can compare current performance against past trends. You can also distinguish normal performance
patterns from anomalies, and devise techniques to address issues.

Performance guidelines
In general, acceptable values for performance metrics depend on what your application is doing relative
to your baseline. Investigate consistent or trending variances from your baseline. The following metrics
are often the source of performance issues:

• High CPU or RAM consumption – High values for CPU or RAM consumption might be appropriate,
if they're 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 – If you see high numbers of user connections and also decreases in instance
performance and response time, consider constraining database connections. The best number of

406
 Amazon Relational Database Service User Guide
Monitoring tools

user connections for your DB instance varies based on your instance class and the complexity of the
operations being performed. To determine the number of database connections, associate 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. 234).
• 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 that your typical working set fits
into memory to minimize read and write operations.

When performance falls outside your established baseline, you might need to make changes to optimize
your database availability for your workload. For example, you might need to change the instance class
of your DB instance. Or you might need to change the number of DB instances and read replicas that are
available for clients.

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, and other tools require manual intervention.

Automated monitoring tools

We recommend that you automate monitoring tasks as much as possible.

Amazon RDS reporting tools

You can use the following automated tools to watch Amazon RDS and report when something is wrong:

• Amazon RDS instance status — View details about the current status of your instance by using the
Amazon RDS console, the AWS CLI command, or the RDS API.
• Amazon RDS recommendations — Respond to automated recommendations for database resources,
such as DB instances, read replicas, and DB parameter groups. For more information, see Using
Amazon RDS recommendations (p. 413).
• Amazon RDS Performance Insights — Assess the load on your database, and determine when and
where to take action. For more information, see Using Performance Insights on Amazon RDS (p. 418).
• Amazon RDS Enhanced Monitoring — Look at metrics in real time for the operating system. For more
information, see Using Enhanced Monitoring (p. 477).
• 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. 493).
• Amazon RDS database logs – View, download, or watch database log files using the Amazon RDS
console or Amazon RDS API operations. You can also query some database log files that are loaded
into database tables. For more information, see Accessing Amazon RDS database log files (p. 510).

Integrated monitoring tools

Amazon RDS integrates with Amazon CloudWatch, Amazon EventBridge, and AWS CloudTrail for
additional monitoring capabilities.

• Amazon CloudWatch – This service monitors your AWS resources and the applications you run on AWS
in real time. You can use the following Amazon CloudWatch features with Amazon RDS:
• Amazon CloudWatch metrics – Amazon RDS automatically sends metrics to CloudWatch every
minute for each active database. You don't get additional charges for Amazon RDS metrics

407
 Amazon Relational Database Service User Guide
Monitoring tools

in CloudWatch. For more information, see Monitoring Amazon RDS metrics with Amazon
CloudWatch (p. 546).
• Amazon CloudWatch alarms – You can watch a single Amazon RDS metric over a specific time
period. You can then perform one or more actions based on the value of the metric relative to a
threshold that you set. For more information, see Monitoring Amazon RDS metrics with Amazon
CloudWatch (p. 546).
• 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.
• Amazon EventBridge – is a serverless event bus service that makes it easy to connect your applications
with data from a variety of sources. EventBridge delivers a stream of real-time data from your own
applications, Software-as-a-Service (SaaS) applications, and AWS services and routes that data to
targets such as Lambda. This enables you to monitor events that happen in services, and build event-
driven architectures. For more information, see Getting CloudWatch Events and Amazon EventBridge
events for Amazon RDS (p. 558).
• AWS CloudTrail – You can view 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. These captures include calls from
the Amazon RDS console and from code calls to the Amazon RDS API operations. 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. For more information, see Working with AWS CloudTrail and
Amazon RDS (p. 564).

Manual monitoring tools

You need to manually monitor 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 using
• The amount of memory and CPU being used for a DB instance
• The amount of network traffic to and from a DB instance
• From the 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).
• 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 that you care about.
• Graph metric data to troubleshoot issues and discover trends.
• Search and browse all your AWS resource metrics.

408
 Amazon Relational Database Service User Guide
Monitoring tools

• Create and edit alarms to be notified of problems.

409
 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
operation 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. 272).

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-enhanced- Billed Enhanced Monitoring is being enabled or disabled for this DB

monitoring instance.

configuring-iam- Billed AWS Identity and Access Management (IAM) database

database-auth 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 The DB instance is being created. The DB instance is inaccessible

billed while it is being created.

deleting Not The DB instance is being deleted.

billed

failed Not The DB instance has failed and Amazon RDS can't recover it.
billed Perform a point-in-time restore to the latest restorable time of the
DB instance to recover the data.

inaccessible- Not The AWS KMS customer master key (CMK) used to encrypt or
encryption-credentials billed decrypt the DB instance can't be accessed.

incompatible-network Not Amazon RDS is attempting to perform a recovery action on a

billed 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
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.

410
 Amazon Relational Database Service User Guide
DB instance status

DB instance status Billed Description

incompatible-option- Billed Amazon RDS attempted to apply an option group change but
group 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.

incompatible- Billed Amazon RDS can't start the DB instance because the parameters
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 Amazon RDS can't do a point-in-time restore. Common causes for
billed this status include using temp tables, using MyISAM tables with
MySQL, or using Aria tables with MariaDB.

insufficient-capacity   Amazon RDS can’t create your instance because sufficient capacity
isn’t currently available. To create your DB instance in the same AZ
with the same instance type, delete your DB instance, wait a few
hours, and try to create again. Alternatively, create a new instance
using a different instance class or AZ.

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.

resetting-master- Billed The master credentials for the DB instance are being reset because
credentials of a customer request to reset them.

renaming Billed The DB instance is being renamed because of a customer request

to rename it.

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

411
 Amazon Relational Database Service User Guide
DB instance status

DB instance status Billed Description

stopping Billed The DB instance is being stopped.

for
storage

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.

412
 Amazon Relational Database Service User Guide
Using Amazon RDS recommendations

Using Amazon RDS recommendations

Amazon RDS provides automated recommendations for database resources, such as DB instances, read
replicas, and DB parameter groups. 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 Your DB instance is We recommend that you upgrade to Upgrading a DB

version not running the latest the latest version because it contains instance engine
outdated minor engine version. the latest security fixes and other version (p. 277)
improvements.

Pending You have pending We recommend that you perform Maintaining a DB

maintenance maintenance the pending maintenance available instance (p. 270)
available available on your DB on your DB instance. Updates to the
instance. operating system most often occur
for security issues and should be done
as soon as possible.

Automated Your DB instance has We recommend that you enable Working with
backups automated backups automated backups on your DB backups (p. 334)
disabled disabled. 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.

Magnetic Your DB instance Magnetic storage is not recommended Amazon RDS

volumes in is using magnetic for most DB instances. We DB instance
use storage. recommend switching to General storage (p. 40)
Purpose (SSD) storage or provisioned
IOPS storage.

EC2-Classic Your DB instance is We recommend moving your DB Determining

platform in using the legacy EC2- instance to the EC2-VPC platform whether you are
use Classic platform. for better network access control. using the EC2-
Amazon VPC provides a virtual VPC or EC2-Classic
network that is logically isolated from platform (p. 1705)
other virtual networks in the AWS
Cloud.

Enhanced Your DB instance We recommend enabling Enhanced Using Enhanced

Monitoring doesn't have Monitoring. Enhanced Monitoring Monitoring (p. 477)
disabled Enhanced Monitoring provides real-time operating
enabled. system metrics for monitoring and
troubleshooting.

Encryption Your DB instance We recommend enabling encryption. Encrypting

disabled doesn't have You can encrypt your existing Amazon Amazon RDS
encryption enabled. RDS DB instances by restoring from resources (p. 1620)
an encrypted snapshot.

Previous Your DB instance Previous-generation DB instance DB instance

generation is running on a classes have been replaced by DB classes (p. 7)

413
 Amazon Relational Database Service User Guide
Using Amazon RDS recommendations

Type Description Recommendation Additional

information
DB instance previous-generation instance classes with better price,
class in use DB instance class. better performance, or both. We
recommend running your DB instance
on a later generation DB instance
class.

Huge pages The For increased database scalability, Enabling HugePages

not used for use_large_pages we recommend setting for an Oracle DB
an Oracle DB parameter is not set use_large_pages to ONLY in the instance (p. 1105)
instance to ONLY in the DB DB parameter group used by your DB
parameter group instance.
used by your DB
instance.

Nondefault Your DB parameter Settings that diverge too much Working with
custom group sets memory from the default values can cause DB parameter
memory parameters that poor performance and errors. We groups (p. 234)
parameters diverge too much recommend setting custom memory
from the default parameters to their default values in
values. the DB parameter group used by the
DB instance.

Change Your DB parameter Change buffering allows a MySQL Best practices

buffering group has change DB instance to defer some writes for configuring
enabled for buffering enabled. necessary to maintain secondary parameters for
a MySQL DB indexes. This configuration can Amazon RDS for
instance improve performance slightly, but MySQL, part 1:
it can create a large delay in crash Parameters related to
recovery. During crash recovery, the performance on the
secondary index must be brought up AWS Database Blog
to date. So, the benefits of change
buffering are outweighed by the
potentially very long crash recovery
events. We recommend disabling
change buffering.

Query cache Your DB parameter The query cache can cause the DB Best practices
enabled for group has query instance to appear to stall when for configuring
a MySQL DB cache parameter changes require the cache to be parameters for
instance enabled. purged. Most workloads don't benefit Amazon RDS for
from a query cache. The query cache MySQL, part 1:
was removed from MySQL version 8.0. Parameters related to
We recommend that you disable the performance on the
query cache parameter. AWS Database Blog

Logging to Your DB parameter Setting logging output to TABLE MySQL database log
table group sets logging uses more storage than setting this files (p. 525)
output to TABLE. parameter to FILE. To avoid reaching
the storage limit, we recommend
setting the logging output parameter
to FILE.

Amazon RDS generates recommendations for a resource when the resource is created or modified.
Amazon RDS also periodically scans your resources and generates recommendations.

414
 Amazon Relational Database Service User Guide
Responding to recommendations

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.

415
 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.
• Scheduled – Shows the recommendations that are scheduled but not yet applied. These
recommendations will be applied in the next scheduled maintenance window.
• Applied – Shows the recommendations that are currently applied.

From any list of recommendations, you can open a section to view the recommendations in that
section.

To configure preferences for displaying recommendations in each section, choose the Preferences
icon.

416
 Amazon Relational Database Service User Guide
Responding to recommendations

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.
4. Manage your active recommendations:

a. Choose Active and open one or more sections to view the recommendations in them.
b. Choose one or more recommendations and choose Apply now (to apply them immediately),
Schedule (to apply them 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 then
apply the recommendation.

If the Apply now 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 (p. 256).
Note
When you choose Apply now, a brief DB instance outage might result.

417
 Amazon Relational Database Service User Guide
Using Performance Insights

Using Performance Insights on Amazon RDS

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.

Topics
• Overview of Performance Insights (p. 418)
• Enabling and disabling Performance Insights (p. 421)
• Accessing Performance Insights (p. 425)
• Monitoring with the Performance Insights dashboard (p. 427)
• Customizing the Performance Insights dashboard (p. 450)
• Retrieving data with the Performance Insights API (p. 460)
• Performance Insights metrics published to Amazon CloudWatch (p. 473)
• Logging Performance Insights calls by using AWS CloudTrail (p. 474)

Overview of Performance Insights

By default, Performance Insights is enabled in the console create wizard for Amazon RDS engines. If you
have more than one database on a DB instance, Performance Insights aggregates performance data.

Topics
• DB load (p. 418)
• Maximum CPU (p. 420)
• Supported DB engines for Performance Insights (p. 420)

DB load
The central metric for Performance Insights is DB Load. The DB Load metric is collected every second.

Active Sessions
An active session is a connection that has submitted work to the DB engine and is waiting for a response.
The DB load represents the average active sessions (AAS) for the DB engine. For example, if you submit a
SQL query to the DB engine, the database session is active while the engine is processing the query.

To obtain the AAS, Performance Insights samples the number of sessions concurrently running a query.
The AAS is the total number of sessions divided by the total number of samples. The following table
shows 5 consecutive samples of a running query.

Sample Number of sessions running AAS Calculation

query

1 2 2 2 sessions / 1 sample

2 0 1 2 sessions / 2 samples

3 4 2 6 sessions / 3 samples

4 0 1.5 6 sessions / 4 samples

418
 Amazon Relational Database Service User Guide
Overview

Sample Number of sessions running AAS Calculation

query

5 4 2 10 sessions / 5 samples

Related to AAS is the average active executions (AAE) per second. To calculate the AAE, Performance
Insights divides the total execution time of a query by the time interval. The following table shows the
AAE calculation for the same query in the preceding table.

Elapsed time (s) Total execution time (s) AAE Calculation

60 120 2 120 execution seconds /

60 elapsed seconds

120 120 1 120 execution seconds /

120 elapsed seconds

180 380 2.11 360 execution seconds /

180 elapsed seconds

240 380 1.58 360 execution seconds /

240 elapsed seconds

300 600 2 600 execution seconds /

300 elapsed seconds

In most cases, the AAS and AAE for a query are approximately the same. However, because the inputs to
the calculations are different data sources, the calculations often vary slightly.

Dimensions
The DB Load metric has subcomponents called dimensions. You can think of dimensions as categories
for the different characteristics of the DB Load metric. When you are diagnosing performance issues, the
most useful dimensions are wait events and top SQL.

Wait events
A wait event causes a SQL statement to wait for a specific event to happen before it can continue
running. For example, a SQL statement might wait until a locked resource is unlocked. By combining
DB Load with wait events, you can get a complete picture of the session state. Wait events vary by DB
engine:

• For information about all MariaDB and 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.
• For information about all SQL Server wait events, see Types of Waits in the SQL Server
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 concatenated with a

419
 Amazon Relational Database Service User Guide
Overview

colon and the wait class associated with that background process. Types of background process
include LGWR, ARC0, PMON, and so on.
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 also missing, and
Performance Insights only reports the wait class, for example :System I/O.

Top SQL
Whereas wait events show bottlenecks, top SQL shows which queries are contributing the most to DB
load. For example, many queries might be currently running on the database, but a single query might
consume 99% of the DB load. In this case, the high load might indicate a problem with the query.

By default, the Performance Insights console displays top SQL queries that are contributing to the
database load. The console also shows relevant statistics for each statement. To diagnose performance
problems for a specific statement, you can examine its execution plan.

Maximum CPU
In the dashboard, the Database load chart collects, aggregates, and displays session information. To see
whether active sessions are exceeding the maximum CPU, look at their relationship to the Max vCPU line.
The Max vCPU value is determined by the number of vCPU (virtual CPU) cores for your DB instance.

If the load is often above the Max vCPU 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 to resolve. This can be true even if
the load doesn't cross the Max vCPU line.

You can find an overview of Performance Insights in the following video.

Using Performance Insights to Analyze Performance of Amazon Aurora PostgreSQL

Supported DB engines for Performance Insights

Following, you can find the DB engines that support Performance Insights.

DB Engine Supported DB Engine Versions

Amazon Aurora MySQL- 2.04.2 and higher 2.x versions (compatible with MySQL 5.7), and 1.17.3
Compatible Edition and higher 1.x versions (compatible with MySQL 5.6).

Not supported on db.t2 or db.t3 DB instance classes. For DB clusters

enabled for parallel query, the minimum Aurora MySQL versions are
2.09.0 and 1.23.0.

Amazon Aurora PostgreSQL- All versions.

Compatible Edition

Amazon RDS for MariaDB All 10.5 versions, all 10.4 versions, 10.3.13 and higher 10.3 versions,
and 10.2.21 and higher 10.2 versions.

Not supported for MariaDB version 10.0 or 10.1. Not supported for
MariaDB version 10.3.13 DB instances in the Europe (Frankfurt) and
Europe (Stockholm) AWS Regions. Not supported on the following DB
instance classes: db.t2.micro, db.t2.small, db.t3.micro, and db.t3.small.

Amazon RDS for MySQL 8.0.17 and higher 8.0 versions, version 5.7.22 and higher 5.7 versions,
and version 5.6.41 and higher 5.6 versions.

420
 Amazon Relational Database Service User Guide
Enabling and Disabling Performance Insights

DB Engine Supported DB Engine Versions

Not supported for version 5.5. Not supported on the following DB
instance classes: db.t2.micro, db.t2.small, db.t3.micro, and db.t3.small.

Amazon RDS for Microsoft All versions except SQL Server 2008.
SQL Server

Amazon RDS for PostgreSQL Versions 10, 11, 12, and 13.

Amazon RDS for Oracle All versions.

Note
Amazon RDS Performance Insights isn't supported in the Middle East (Bahrain) Region, Africa
(Cape Town) Region, or in AWS GovCloud (US) Regions.
Important
This guide describes using Amazon RDS Performance Insights with non-Aurora DB engines. For
information about using Amazon RDS Performance Insights with Amazon Aurora, see the Using
Amazon RDS Performance Insights in the Amazon Aurora User Guide.

Enabling and disabling Performance Insights

To use Performance Insights, enable it on your DB instance. If needed, you can disable it later. Enabling
and disabling Performance Insights doesn't cause downtime, a reboot, or a failover.

The Performance Insights agent consumes limited CPU and memory on the DB host. When the DB load is
high, the agent limits the performance impact by collecting data less frequently.

Console
In the console, you can enable or disable Performance Insights when you create or modify a new DB
instance.

Enabling or disabling Performance Insights when creating an instance

When you create a new DB instance, enable Performance Insights by choosing Enable Performance
Insights in the Performance Insights section. Or choose Disable Performance Insights.

To create a DB instance, follow the instructions for your DB engine in Creating an Amazon RDS DB
instance (p. 147).

The following screenshot shows the Performance Insights section.

421
 Amazon Relational Database Service User Guide
Enabling and Disabling Performance Insights

If you choose Enable Performance Insights, you have the following options:

• 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) customer master key (CMK).
Performance Insights encrypts all potentially sensitive data using your AWS KMS CMK. Data is
encrypted in flight and at rest. For more information, see Encrypting Amazon RDS resources (p. 1620).

Enabling or disabling Performance Insights when modifying an instance

In the console, you can modify a DB instance to enable or disable Performance Insights using the
console.

To enable or disable 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 Databases.
3. Choose a DB instance, and choose Modify.
4. In the Performance Insights section, choose either Enable Performance Insights or Disable
Performance Insights.

If you choose Enable Performance Insights, you have the following options:

• 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) customer master key
(CMK). Performance Insights encrypts all potentially sensitive data using your AWS KMS CMK.
Data is encrypted in flight and at rest. For more information, see Encrypting Amazon RDS
resources (p. 1620).
5. Choose Continue.
6. For Scheduling of Modifications, choose one of the following:

422
 Amazon Relational Database Service User Guide
Enabling and Disabling Performance Insights

• Apply during the next scheduled maintenance window – Wait to apply the Performance
Insights modification until the next maintenance window.
• Apply immediately – Apply the Performance Insights modification as soon as possible.
7. Choose Modify instance.

AWS CLI
When you use the create-db-instance AWS CLI command, enable Performance Insights by specifying
--enable-performance-insights. Or disable Performance Insights by specifying --no-enable-
performance-insights.

You can also specify these values 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 or disable Performance Insights for a DB instance using
the AWS CLI.

To enable or disable 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 to enable or --no-enable-performance-insights to
disable

The following example enables Performance Insights for sample-db-instance.

For Linux, macOS, 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, macOS, or Unix:

aws rds modify-db-instance \

423
 Amazon Relational Database Service User Guide
Enabling and Disabling Performance Insights

--db-instance-identifier sample-db-instance \
--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

RDS API
When you create a new DB instance using the CreateDBInstance operation Amazon RDS API operation,
enable Performance Insights by setting EnablePerformanceInsights to True. To disable
Performance Insights, set EnablePerformanceInsights to False.

You can also specify the EnablePerformanceInsights value using the following API operations:

• 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 the Performance Schema for Performance Insights on

Amazon RDS for MariaDB or MySQL
When the Performance Schema feature is enabled for Amazon RDS for MariaDB or MySQL, Performance
Insights provides more detailed information. For example, Performance Insights displays DB load
categorized by detailed wait events. Without the Performance Schema enabled, Performance Insights
displays DB load categorized by the list state of the MySQL process.

Performance Schema is enabled automatically when you create an Amazon RDS for MariaDB or MySQL
DB instance with Performance Insights enabled. In this case, Performance Insights automatically
manages the parameters in the following table.

Parameter Name Parameter Value

performance_schema 1 (the Source column has the value

engine-default)

performance-schema-consumer-events-waits- ON
current

performance-schema-instrument wait/%=ON

performance-schema-consumer-global- ON
instrumentation

performance-schema-consumer-thread- ON
instrumentation

424
 Amazon Relational Database Service User Guide
Accessing Performance Insights

Important
When Performance Schema is enabled automatically, Performance Insights changes schema-
related parameters on the DB instance. These changes aren't visible in the parameter group
associated with the DB instance.

For more information, see Performance Schema Command Options and Performance Schema Option
and Variable Reference in the MySQL documentation.

Enabling the Performance Schema manually

Performance Schema is not enabled when both the following conditions are true:

• The performance_schema parameter is set to 0 or 1.

• The Source column for the performance_schema parameter is set to user.

To enable the Performance Schema manually

1. Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.
2. Choose Parameter groups.
3. Select the name of the parameter group for your DB instance.
4. Choose Edit parameters.
5. Enter perf in the search bar.
6. Select the performance_schema parameter.

7. Choose Reset.
8. Choose Reset parameters.
9. Restart the DB instance.

For more information about modifying instance parameters, see Modifying parameters in a DB
parameter group (p. 238). For more information about the dashboard, see Monitoring with the
Performance Insights dashboard (p. 427). For more information about the MySQL performance
schema, see MySQL 8.0 Reference Manual.

Accessing 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
operations. 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. along
with other console features.

425
 Amazon Relational Database Service User Guide
Accessing Performance Insights

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.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "pi:*",
"Resource": "arn:aws:pi:*:*:metrics/rds/*"
}
]
}

6. Choose Review policy.

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.

To attach the policy to an IAM user

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. In the navigation pane, choose Users.
3. Choose an existing user from the list.
Important
To use Performance Insights, make sure that you 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 Managing access using
policies (p. 1636).
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.

426
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

6. Choose your policy, and then choose Next: Review.

7. Choose Add permissions.

Monitoring with 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.

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/.

2. In the navigation pane, choose Performance Insights.
3. 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.

427
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

The following screenshot shows the dashboard for a DB instance. By default, the Performance
Insights dashboard shows data for the last hour.

4. (Optional) Choose a different time interval by selecting a button in the upper right. For example, to
change the interval to 5 hours, select 5h.

In the following screenshot, the DB load interval is 5 hours.

428
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

5. (Optional) To refresh your data automatically, enable Auto refresh.

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 refreshes every minute.
• 5 hours refreshes every minute.
• 24 hours refreshes every 5 minutes.
• 1 week refreshes every hour.

Performance Insights dashboard components

The dashboard is divided into three parts:

1. Counter Metrics – Shows data for specific performance counter metrics.

2. DB Load Chart – Shows how the DB load compares to DB instance capacity as represented by the Max
vCPU line.
3. Top items – Shows the top waits, SQL, hosts, and users contributing to DB load.

Counter Metrics chart

The Counter Metrics chart displays data for performance counters. The default metrics depend on the
DB engine.

• MySQL and MariaDB – db.SQL.Innodb_rows_read.avg

• Oracle – db.User.user calls.avg
• Microsoft SQL Server – db.Databases.Active Transactions(_Total).avg
• PostgreSQL – db.Transactions.xact_commit.avg

429
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

Change the performance counters by choosing Manage Metrics. You can select multiple OS metrics or
Database metrics, as shown in the following screenshot. To see details for any metric, hover over the
metric name.

For more information, see Customizing the Performance Insights dashboard (p. 450).

Average Active Sessions chart

The Database Load chart shows how the database load compares to DB instance capacity as represented
by the Max vCPU line. By default, load is shown as active sessions grouped by wait states in a bar graph.

430
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

You can choose to display load as active sessions grouped by waits, SQL, users, or hosts. You can also
choose a line graph.

To see details about a DB load item such as a SQL statement, hover over the item name.

431
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

To see details for any item for the selected time period in the legend, hover over that item.

432
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

Top load table

The Top load table shows the top items contributing to database load. You can choose any of the
following dimension tabs:

• Top SQL – The SQL statements that are currently running

• Top waits – The event for which the database backend is waiting
• Top hosts – The host name of the connected client
• Top users – The user logged in to the database
• Top databases – The name of the database to which the client is connected (PostgreSQL, MySQL, and
MariaDB only)
• Top applications (PostgreSQL only) – The name of the application that is connected to the database
• Top session types (PostgreSQL only) – The type of the current session

By default, the console displays top SQL queries that are contributing to the database load. Every line in
the table shows relevant statistics for the SQL statement:

To see the components of a query, select the query, and then choose the +. A SQL digest is a composite
of multiple actual queries that are structurally similar but that possibly have different literal values. In
the following screenshot, the selected query is a digest. The digest replaces hardcoded values with a
question mark.

433
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

Note
A SQL digest groups similar SQL statements, but does not redact sensitive information.

In Top sql, the Load by waits (AAS) column illustrates the percentage of the database load associated
with each top load item. This column reflects the load for that item by whatever grouping is currently
selected in the DB Load Chart. For example, you might group the DB Load Chart chart by wait states.
You examine 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 which wait states are affecting the selected query.

In the Top sql table, you can open a statement to view its information. The information appears in the
bottom pane.

434
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

In the Top sql tab, you can view the following types of identifiers (IDs) that are associated with SQL
statements:

• Support SQL ID – A hash value of the SQL ID. This value is only for referencing a SQL ID when you are
working with AWS Support. AWS Support doesn't have access to your actual SQL IDs and SQL text.
• Support Digest ID – A hash value of the digest ID. This value is only for referencing a digest ID when
you are working with AWS Support. AWS Support doesn't have access to your actual digest IDs and
SQL text.

You can control the statistics displayed in the Top sql tab by choosing the Preferences icon.

435
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

When you choose the Preferences icon, the Preferences window opens.

Enable the statistics that you want to have visible in the Top sql tab, use your mouse to scroll to the
bottom of the window, and then choose Continue.

436
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

Analyzing DB 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.
This combination 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.

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, log file sync waits account for most of the DB load. The LGWR
all worker groups wait is also high. The Top sql chart shows what is causing the log file sync waits:
frequent COMMIT statements. In this case, committing less frequently will reduce DB load.

437
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

Analyzing statistics for running queries

In Amazon RDS Performance Insights, you can find statistics on running queries in the Top SQL section.
Performance Insights collects statistics only for the most common queries. Typically, these match the top
queries by load shown in the Performance Insights dashboard.

Topics
• Statistics for MariaDB and MySQL (p. 438)
• Statistics for Oracle (p. 441)
• Statistics for PostgreSQL (p. 444)

Statistics for MariaDB and MySQL

Performance Insights collects SQL digest statistics from the
events_statements_summary_by_digest table. This table is managed by the database and doesn't
have an eviction policy. If the table becomes full, new SQL queries aren't tracked. To address this issue,
Performance Insights automatically truncates the table when it's nearly full.

Performance Insights automatically truncates the table 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 Performance Insights to truncate the table automatically, then reset 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. The following message is shown in the AWS Management Console when the table is full:

Performance Insights is unable to collect SQL Digest statistics on new queries because the
table events_statements_summary_by_digest is full.
Please truncate events_statements_summary_by_digest table to clear the issue. Check the
User Guide for more details.

The following SQL statistics are available for MariaDB and MySQL DB instances.

Metric Unit

db.sql_tokenized.stats.count_star_per_sec Calls per second

db.sql_tokenized.stats.sum_timer_wait_per_sec Average active executions per second (AAE)

db.sql_tokenized.stats.sum_select_full_join_per_sec Select full join per second

db.sql_tokenized.stats.sum_select_range_check_per_sec
Select range check per second

db.sql_tokenized.stats.sum_select_scan_per_sec Select scan per second

db.sql_tokenized.stats.sum_sort_merge_passes_per_sec
Sort merge passes per second

db.sql_tokenized.stats.sum_sort_scan_per_sec Sort scans per second

db.sql_tokenized.stats.sum_sort_range_per_sec Sort ranges per second

db.sql_tokenized.stats.sum_sort_rows_per_sec Sort rows per second

db.sql_tokenized.stats.sum_rows_affected_per_sec Rows affected per second

db.sql_tokenized.stats.sum_rows_examined_per_sec Rows examined per second

438
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

Metric Unit

db.sql_tokenized.stats.sum_rows_sent_per_sec Rows sent per second

db.sql_tokenized.stats.sum_created_tmp_disk_tables_per_sec
Created temporary disk tables per second

db.sql_tokenized.stats.sum_created_tmp_tables_per_sec
Created temporary tables per second

db.sql_tokenized.stats.sum_lock_time_per_sec Lock time per second (in ms)

The following metrics provide per call statistics for a SQL statement.

Metric Unit

db.sql_tokenized.stats.sum_timer_wait_per_call Average latency per call (in ms)

db.sql_tokenized.stats.sum_select_full_join_per_call Select full joins per call

db.sql_tokenized.stats.sum_select_range_check_per_call
Select range check per call

db.sql_tokenized.stats.sum_select_scan_per_call Select scans per call

db.sql_tokenized.stats.sum_sort_merge_passes_per_call
Sort merge passes per call

db.sql_tokenized.stats.sum_sort_scan_per_call Sort scans per call

db.sql_tokenized.stats.sum_sort_range_per_call Sort ranges per call

db.sql_tokenized.stats.sum_sort_rows_per_call Sort rows per call

db.sql_tokenized.stats.sum_rows_affected_per_call Rows affected per call

db.sql_tokenized.stats.sum_rows_examined_per_callRows examined per call

db.sql_tokenized.stats.sum_rows_sent_per_call Rows sent per call

db.sql_tokenized.stats.sum_created_tmp_disk_tables_per_call
Created temporary disk tables per call

db.sql_tokenized.stats.sum_created_tmp_tables_per_call
Created temporary tables per call

db.sql_tokenized.stats.sum_lock_time_per_call Lock time per call (in ms)

Analyzing MariaDB and MySQL Metrics for running SQL statements

Using the AWS Management Console, you can view the metrics for a running SQL query by choosing the
SQL tab and expanding the query.

439
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

Choose which statistics to display by choosing the gear icon in the upper-right corner of the chart.

The following screenshot shows the preferences for MariaDB and MySQL DB instances.

440
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

Statistics for Oracle

The following SQL statistics are available for Oracle DB instances.

Metric Unit

db.sql.stats.executions_per_sec Number of executions per second

db.sql.stats.elapsed_time_per_sec Average active executions (AAE)

db.sql.stats.rows_processed_per_sec Rows processed per second

db.sql.stats.buffer_gets_per_sec Buffer gets per second

db.sql.stats.physical_read_requests_per_sec Physical reads per second

db.sql.stats.physical_write_requests_per_sec Physical writes per second

db.sql.stats.total_sharable_mem_per_sec Total shareable memory per second (in bytes)

db.sql.stats.cpu_time_per_sec CPU time per second (in ms)

The following metrics provide per call statistics for a SQL statement.

Metric Unit

db.sql.stats.elapsed_time_per_exec Elapsed time per executions (in ms)

441
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

Metric Unit

db.sql.stats.rows_processed_per_exec Rows processed per execution

db.sql.stats.buffer_gets_per_exec Buffer gets per execution

db.sql.stats.physical_read_requests_per_exec Physical reads per execution

db.sql.stats.physical_write_requests_per_exec Physical writes per execution

db.sql.stats.total_sharable_mem_per_exec Total shareable memory per execution (in bytes)

db.sql.stats.cpu_time_per_exec CPU time per execution (in ms)

Analyzing Oracle metrics for running SQL statements

Using the AWS Management Console, you can view the metrics for a running SQL query by choosing the
SQL tab and expanding the query.

Choose which statistics to display by choosing the gear icon in the upper-right corner of the chart.

The following screenshot shows the preferences for Oracle DB instances.

442
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

The following screenshot shows the statistics for a SQL statement.

443
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

Statistics for PostgreSQL

To view SQL Digest statistics, the pg_stat_statements library must be loaded. For PostgreSQL
DB instances that are compatible with PostgreSQL 11 or later, this library is loaded by default. For
PostgreSQL DB instances that are compatible with PostgreSQL 10 or earlier, you enable this library
manually. To enable it manually, add pg_stat_statements to shared_preload_libraries in
the DB parameter group associated with the DB instance. Then reboot your DB instance. For more
information, see Working with DB parameter groups (p. 234).
Note
Performance Insights can only collect statistics for queries in pg_stat_activity that aren't
truncated. By default, PostgreSQL databases truncate queries longer than 1,024 bytes. To
increase the query size, change the track_activity_query_size parameter in the DB
parameter group associated with your DB instance. When you change this parameter, a DB
instance reboot is required.

The following SQL Digest statistics are available for PostgreSQL DB instances.

Metric Unit

db.sql_tokenized.stats.calls_per_sec Calls per second

db.sql_tokenized.stats.rows_per_sec Rows per second

db.sql_tokenized.stats.total_time_per_sec Average active executions per second (AAE)

db.sql_tokenized.stats.shared_blks_hit_per_sec Block hits per second

db.sql_tokenized.stats.shared_blks_read_per_sec Block reads per second

db.sql_tokenized.stats.shared_blks_dirtied_per_sec Blocks dirtied per second

db.sql_tokenized.stats.shared_blks_written_per_sec Block writes per second

db.sql_tokenized.stats.local_blks_hit_per_sec Local block hits per second

db.sql_tokenized.stats.local_blks_read_per_sec Local block reads per second

db.sql_tokenized.stats.local_blks_dirtied_per_sec Local block dirty per second

db.sql_tokenized.stats.local_blks_written_per_sec Local block writes per second

db.sql_tokenized.stats.temp_blks_written_per_sec Temporary writes per second

db.sql_tokenized.stats.temp_blks_read_per_sec Temporary reads per second

db.sql_tokenized.stats.blk_read_time_per_sec Average concurrent reads per second

db.sql_tokenized.stats.blk_write_time_per_sec Average concurrent writes per second

The following metrics provide per call statistics for a SQL statement.

Metric Unit

db.sql_tokenized.stats.rows_per_call Rows per call

db.sql_tokenized.stats.avg_latency_per_call Average latency per call (in ms)

db.sql_tokenized.stats.shared_blks_hit_per_call Block hits per call

444
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

Metric Unit

db.sql_tokenized.stats.shared_blks_read_per_call Block reads per call

db.sql_tokenized.stats.shared_blks_written_per_call Block writes per call

db.sql_tokenized.stats.shared_blks_dirtied_per_call Blocks dirtied per call

db.sql_tokenized.stats.local_blks_hit_per_call Local block hits per call

db.sql_tokenized.stats.local_blks_read_per_call Local block reads per call

db.sql_tokenized.stats.local_blks_dirtied_per_call Local block dirty per call

db.sql_tokenized.stats.local_blks_written_per_call Local block writes per call

db.sql_tokenized.stats.temp_blks_written_per_call Temporary block writes per call

db.sql_tokenized.stats.temp_blks_read_per_call Temporary block reads per call

db.sql_tokenized.stats.blk_read_time_per_call Read time per call (in ms)

db.sql_tokenized.stats.blk_write_time_per_call Write time per call (in ms)

For more information about these metrics, see pg_stat_statements in the PostgreSQL documentation.

Analyzing PostgreSQL metrics for running SQL statements

Using the AWS Management Console, you can view the metrics for a running SQL query by choosing the
SQL tab.

445
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

Choose which statistics to display by choosing the gear icon in the upper-right corner of the chart.

The following screenshot shows the preferences for PostgreSQL.

446
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

Viewing more SQL text in the Performance Insights dashboard

By default, each row in the Top sql table shows 500 bytes of SQL text for each SQL statement. When
a SQL statement is larger than 500 bytes, you can view more of the SQL statement by opening the
statement in the Performance Insights dashboard. The dashboard displays text up to the following per-
engine limits:

• Amazon RDS for Microsoft SQL Server – 4,096 characters

• Amazon RDS for MySQL and MariaDB – 1,024 bytes
• Amazon RDS for Oracle – 1,000 bytes

You can copy the text that is displayed on the dashboard, or choose Download.

Amazon RDS for PostgreSQL handles text differently. Using the Performance Insights dashboard, you
can view and download up to 500 bytes. To access more than 500 bytes, set the size limit with the DB
instance parameter track_activity_query_size. The maximum value is 102,400 bytes. To view
or download text over 500 bytes, use the AWS Management Console, not the Performance Insights

447
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

CLI or API. For more information, see Setting the SQL text limit for Amazon RDS for PostgreSQL DB
instances (p. 448).

To view more SQL text in the Performance Insights dashboard

1. Open the Amazon RDS console at https://console.aws.amazon.com/rds/.

2. In the navigation pane, choose Performance Insights.
3. Choose a DB instance. The Performance Insights dashboard is displayed for that DB instance.

SQL statements with text larger than 500 bytes look similar to the following image.

4. Examine the SQL information section to view more of the SQL text.

The Performance Insights dashboard can display up to 4,096 bytes for each SQL statement.
5. (Optional) Choose Copy to copy the displayed SQL statement, or choose Download to download the
SQL statement to view the SQL text up to the DB engine limit.
Note
To copy or download the SQL statement, disable pop-up blockers.

Setting the SQL text limit for Amazon RDS for PostgreSQL DB instances
For Amazon RDS for PostgreSQL DB instances, you can control the limit for the SQL text that can be
shown on the Performance Insights dashboard.

To do so, modify the track_activity_query_size DB instance parameter. The default setting for the
track_activity_query_size parameter is 1,024 bytes.

448
 Amazon Relational Database Service User Guide
Monitoring with the Performance Insights dashboard

You can increase the number of bytes to increase the SQL text size visible in the Performance
Insights dashboard. The limit for the parameter is 102,400 bytes. For more information about the
track_activity_query_size DB instance parameter, see Run-time Statistics in the PostgreSQL
documentation.

To modify the parameter, change the parameter setting in the parameter group that is associated with
the Amazon RDS for PostgreSQL DB instance.

If the Amazon RDS for PostgreSQL DB instance is using the default parameter group, complete the
following steps:

1. Create a new DB instance parameter group for the appropriate DB engine and DB engine version.
2. Set the parameter in the new parameter group.
3. Associate the new parameter group with the DB instance.

For information about setting a DB instance parameter, see Modifying parameters in a DB parameter
group (p. 238).

Zooming In on the DB Load chart

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 AWS Region, and the Top items table is recalculated.

449
 Amazon Relational Database Service User Guide
Customizing the Performance Insights dashboard

Customizing the Performance Insights dashboard

With counter metrics, you can customize the Performance Insights dashboard to include up to 10
additional graphs. These graphs that show a selection of dozens of operating system and database
performance metrics. This information can be correlated with database load to help identify and analyze
performance problems.

Topics
• Performance Insights operating system counters (p. 450)
• Performance Insights counters for Amazon RDS for MariaDB and MySQL (p. 453)
• Performance Insights counters for Amazon RDS for Microsoft SQL Server (p. 456)
• Performance Insights counters for Amazon RDS for Oracle (p. 457)
• Performance Insights counters for Amazon RDS for PostgreSQL (p. 458)

Performance Insights operating system counters

The following operating system counters are available with Performance Insights for Aurora PostgreSQL.
You can find definitions for these metrics in Viewing Enhanced Monitoring by using CloudWatch
Logs (p. 484).

450
 Amazon Relational Database Service User Guide
Customizing the Performance Insights dashboard

Counter Type Metric

active memory os.memory.active

buffers memory os.memory.buffers

cached memory os.memory.cached

dirty memory os.memory.dirty

free memory os.memory.free

hugePagesFree memory os.memory.hugePagesFree

hugePagesRsvd memory os.memory.hugePagesRsvd

hugePagesSize memory os.memory.hugePagesSize

hugePagesSurp memory os.memory.hugePagesSurp

hugePagesTotal memory os.memory.hugePagesTotal

inactive memory os.memory.inactive

mapped memory os.memory.mapped

pageTables memory os.memory.pageTables

slab memory os.memory.slab

total memory os.memory.total

writeback memory os.memory.writeback

guest cpuUtilization os.cpuUtilization.guest

idle cpuUtilization os.cpuUtilization.idle

irq cpuUtilization os.cpuUtilization.irq

nice cpuUtilization os.cpuUtilization.nice

steal cpuUtilization os.cpuUtilization.steal

system cpuUtilization os.cpuUtilization.system

total cpuUtilization os.cpuUtilization.total

user cpuUtilization os.cpuUtilization.user

wait cpuUtilization os.cpuUtilization.wait

avgQueueLen diskIO os.diskIO.avgQueueLen

avgReqSz diskIO os.diskIO.avgReqSz

await diskIO os.diskIO.await

readIOsPS diskIO os.diskIO.readIOsPS

readKb diskIO os.diskIO.readKb

readKbPS diskIO os.diskIO.readKbPS

451
 Amazon Relational Database Service User Guide
Customizing the Performance Insights dashboard

Counter Type Metric

rrqmPS diskIO os.diskIO.rrqmPS

tps diskIO os.diskIO.tps

util diskIO os.diskIO.util

writeIOsPS diskIO os.diskIO.writeIOsPS

writeKb diskIO os.diskIO.writeKb

writeKbPS diskIO os.diskIO.writeKbPS

wrqmPS diskIO os.diskIO.wrqmPS

blocked tasks os.tasks.blocked

running tasks os.tasks.running

sleeping tasks os.tasks.sleeping

stopped tasks os.tasks.stopped

total tasks os.tasks.total

zombie tasks os.tasks.zombie

one loadAverageMinute os.loadAverageMinute.one

fifteen loadAverageMinute os.loadAverageMinute.fifteen

five loadAverageMinute os.loadAverageMinute.five

cached swap os.swap.cached

free swap os.swap.free

in swap os.swap.in

out swap os.swap.out

total swap os.swap.total

maxFiles fileSys os.fileSys.maxFiles

usedFiles fileSys os.fileSys.usedFiles

usedFilePercent fileSys os.fileSys.usedFilePercent

usedPercent fileSys os.fileSys.usedPercent

used fileSys os.fileSys.used

total fileSys os.fileSys.total

rx network os.network.rx

tx network os.network.tx

numVCPUs general os.general.numVCPUs

452
 Amazon Relational Database Service User Guide
Customizing the Performance Insights dashboard

Performance Insights counters for Amazon RDS for MariaDB and

MySQL
The following database counters are available with Performance Insights for Amazon RDS for MariaDB
and MySQL.

Topics
• Native counters for RDS for MariaDB and RDS for MySQL (p. 453)
• Non-native counters for Amazon RDS for MariaDB and MySQL (p. 454)

Native counters for RDS for MariaDB and RDS for MySQL
For definitions of these native metrics, see Server Status Variables in the MySQL documentation.

Counter Type Unit Metric

Com_analyze SQL Queries per second db.SQL.Com_analyze

Com_optimize SQL Queries per second db.SQL.Com_optimize

Com_select SQL Queries per second db.SQL.Com_select

Connections SQL The number of db.SQL.Connections

connection attempts
per minute (successful
or not) to the MySQL
server

Innodb_rows_deleted SQL Rows per second db.SQL.Innodb_rows_deleted

Innodb_rows_inserted SQL Rows per second db.SQL.Innodb_rows_inserted

Innodb_rows_read SQL Rows per second db.SQL.Innodb_rows_read

Innodb_rows_updated SQL Rows per second db.SQL.Innodb_rows_updated

Select_full_join SQL Queries per second db.SQL.Select_full_join

Select_full_range_join SQL Queries per second db.SQL.Select_full_range_join

Select_range SQL Queries per second db.SQL.Select_range

Select_range_check SQL Queries per second db.SQL.Select_range_check

Select_scan SQL Queries per second db.SQL.Select_scan

Slow_queries SQL Queries per second db.SQL.Slow_queries

Sort_merge_passes SQL Queries per second db.SQL.Sort_merge_passes

Sort_range SQL Queries per second db.SQL.Sort_range

Sort_rows SQL Queries per second db.SQL.Sort_rows

Sort_scan SQL Queries per second db.SQL.Sort_scan

Questions SQL Queries per second db.SQL.Questions

Innodb_row_lock_time Locks Milliseconds (average) db.Locks.Innodb_row_lock_time

453
 Amazon Relational Database Service User Guide
Customizing the Performance Insights dashboard

Counter Type Unit Metric

Table_locks_immediate Locks Requests per second db.Locks.Table_locks_immediate

Table_locks_waited Locks Requests per second db.Locks.Table_locks_waited

Aborted_clients Users Connections db.Users.Aborted_clients

Aborted_connects Users Connections db.Users.Aborted_connects

Threads_created Users Connections db.Users.Threads_created

Threads_running Users Connections db.Users.Threads_running

Innodb_data_writes I/O Operations per second db.IO.Innodb_data_writes

Innodb_dblwr_writes I/O Operations per second db.IO.Innodb_dblwr_writes

Innodb_log_write_requestsI/O Operations per second db.IO.Innodb_log_write_requests

Innodb_log_writes I/O Operations per second db.IO.Innodb_log_writes

Innodb_pages_written I/O Pages per second db.IO.Innodb_pages_written

Created_tmp_disk_tables Temp Tables per second db.Temp.Created_tmp_disk_tables

Created_tmp_tables Temp Tables per second db.Temp.Created_tmp_tables

Innodb_buffer_pool_pages_data
Cache Pages db.Cache.Innodb_buffer_pool_pages_d

Innodb_buffer_pool_pages_total
Cache Pages db.Cache.Innodb_buffer_pool_pages_t

Innodb_buffer_pool_read_requests
Cache Pages per second db.Cache.Innodb_buffer_pool_read_req

Innodb_buffer_pool_readsCache Pages per second db.Cache.Innodb_buffer_pool_reads

Opened_tables Cache Tables db.Cache.Opened_tables

Opened_table_definitions Cache Tables db.Cache.Opened_table_definitions

Qcache_hits Cache Queries db.Cache.Qcache_hits

Non-native counters for Amazon RDS for MariaDB and MySQL

Non-native counter metrics are counters defined by Amazon RDS. A non-native metric can be a metric
that you get with a specific query. A non-native metric also can be a derived metric, where two or more
native counters are used in calculations for ratios, hit rates, or latencies.

Counter Type Metric Description Definition

innodb_buffer_pool_hits
Cache db.Cache.innodb_buffer_pool_hits
The number of reads that innodb_buffer_pool_read_requests
InnoDB could satisfy from -
the buffer pool. innodb_buffer_pool_reads

innodb_buffer_pool_hit_rate
Cache db.Cache.innodb_buffer_pool_hit_rate
The percentage of reads 100 *
that InnoDB could satisfy innodb_buffer_pool_read_requests
from the buffer pool. (innodb_buffer_pool_read_request
+
innodb_buffer_pool_reads)

454
 Amazon Relational Database Service User Guide
Customizing the Performance Insights dashboard

Counter Type Metric Description Definition

innodb_buffer_pool_usage
Cache db.Cache.innodb_buffer_pool_usage
The percentage of the Innodb_buffer_pool_pages_data /
InnoDB buffer pool that Innodb_buffer_pool_pages_total
contains data (pages). * 100.0
Note
When using
compressed tables,
this value can
vary. For more
information,
see the
information about
Innodb_buffer_pool_pages_data
and
Innodb_buffer_pool_pages_total
in Server Status
Variables in
the MySQL
documentation.

query_cache_hit_rate
Cache db.Cache.query_cache_hit_rate
MySQL result set cache Qcache_hits /
(query cache) hit ratio. (QCache_hits +
Com_select) * 100

innodb_datafile_writes_to_disk
I/O db.IO.innodb_datafile_writes_to_disk
The number of InnoDB data Innodb_data_writes -
file writes to disk, excluding Innodb_log_writes -
double write and redo Innodb_dblwr_writes
logging write operations.

innodb_rows_changed
SQL db.SQL.innodb_rows_changed
The total InnoDB row db.SQL.Innodb_rows_inserted
operations. +
db.SQL.Innodb_rows_deleted
+
db.SQL.Innodb_rows_updated

active_transactions
Transactions db.Transactions.active_transactions
The total active SELECT COUNT(1) AS
transactions. active_transactions
FROM
INFORMATION_SCHEMA.INNODB_TRX

innodb_deadlocks
Locks db.Locks.innodb_deadlocks
The total number of SELECT COUNT AS
deadlocks. innodb_deadlocks FROM
INFORMATION_SCHEMA.INNODB_METRIC
WHERE
NAME='lock_deadlocks'

innodb_lock_timeouts
Locks db.Locks.innodb_lock_timeouts
The total number of locks SELECT COUNT AS
that timed out. innodb_lock_timeouts
FROM
INFORMATION_SCHEMA.INNODB_METRIC
WHERE
NAME='lock_timeouts'

455
 Amazon Relational Database Service User Guide
Customizing the Performance Insights dashboard

Counter Type Metric Description Definition

innodb_row_lock_waits
Locks db.Locks.innodb_row_lock_waits
The total number of row SELECT COUNT AS
locks that resulted in a innodb_row_lock_waits
wait. FROM
INFORMATION_SCHEMA.INNODB_METRIC
WHERE
NAME='lock_row_lock_waits'

Performance Insights counters for Amazon RDS for Microsoft

SQL Server
The following database counters are available with Performance Insights for RDS for Microsoft SQL
Server.

Native counters for RDS for Microsoft SQL Server

You can find definitions for these native metrics in Use SQL Server Objects in the Microsoft SQL Server
documentation.

Counter Type Unit Metric

Forwarded Records Access Methods Records per second db.Access

Methods.Forwarded
Records

Page Splits Access Methods Splits per second db.Access

Methods.Page Splits

Buffer cache hit ratio Buffer Manager Ratio db.Buffer

Manager.Buffer cache
hit ratio

Page life expectancy Buffer Manager Expectancy in seconds db.Buffer Manager.Page

life expectancy

Page lookups Buffer Manager Lookups per second db.Buffer Manager.Page

lookups

Page reads Buffer Manager Reads per second db.Buffer Manager.Page

reads

Page writes Buffer Manager Writes per second db.Buffer Manager.Page

writes

Active Transactions Databases Transactions db.Databases.Active

Transactions (_Total)

Log Bytes Flushed Databases Bytes flushed per db.Databases.Log Bytes

second Flushed (_Total)

Log Flush Waits Databases Waits per second db.Databases.Log Flush

Waits (_Total)

Log Flushes Databases Flushes per second db.Databases.Log

Flushes (_Total)

456
 Amazon Relational Database Service User Guide
Customizing the Performance Insights dashboard

Counter Type Unit Metric

Write Transactions Databases Transactions per second db.Databases.Write

Transactions (_Total)

Processes blocked General Statistics Processes blocked db.General

Statistics.Processes
blocked

User Connections General Statistics Connections db.General

Statistics.User
Connections

Latch Waits Latches Waits per second db.Latches.Latch Waits

Number of Deadlocks Locks Deadlocks per second db.Locks.Number of

Deadlocks (_Total)

Memory Grants Memory Manager Memory grants db.Memory

Pending Manager.Memory
Grants Pending

Batch Requests SQL Statistics Requests per second db.SQL Statistics.Batch

Requests

SQL Compilations SQL Statistics Compilations per db.SQL Statistics.SQL

second Compilations

SQL Re-Compilations SQL Statistics Re-compilations per db.SQL Statistics.SQL

second Re-Compilations

Performance Insights counters for Amazon RDS for Oracle

The following database counters are available with Performance Insights for RDS for Oracle.

Native counters for RDS for Oracle

You can find definitions for these native metrics in Statistics Descriptions in the Oracle documentation.
Note
For the CPU used by this session counter metric, the unit has been transformed from the
native centiseconds to active sessions to make the value easier to use. For example, CPU send
in the DB Load chart represents the demand for CPU. The counter metric CPU used by this
session represents the amount of CPU used by Oracle sessions. You can compare CPU send to
the CPU used by this session counter metric. When demand for CPU is higher than CPU
used, sessions are waiting for CPU time.

Counter Type Unit Metric

CPU used by this User Active sessions db.User.CPU used by

session this session

SQL*Net roundtrips to/ User Roundtrips per second db.User.SQL*Net

from client roundtrips to/from
client

Bytes received via User Bytes per second db.User.bytes received

SQL*Net from client via SQL*Net from client

457
 Amazon Relational Database Service User Guide
Customizing the Performance Insights dashboard

Counter Type Unit Metric

User commits User Commits per second db.User.user commits

Logons cumulative User Logons per second db.User.logons

cumulative

User calls User Calls per second db.User.user calls

Bytes sent via SQL*Net User Bytes per second db.User.bytes sent via
to client SQL*Net to client

User rollbacks User Rollbacks per second db.User.user rollbacks

Redo size Redo Bytes per second db.Redo.redo size

Parse count (total) SQL Parses per second db.SQL.parse count

(total)

Parse count (hard) SQL Parses per second db.SQL.parse count

(hard)

Table scan rows gotten SQL Rows per second db.SQL.table scan rows
gotten

Sorts (memory) SQL Sorts per second db.SQL.sorts (memory)

Sorts (disk) SQL Sorts per second db.SQL.sorts (disk)

Sorts (rows) SQL Sorts per second db.SQL.sorts (rows)

Physical read bytes Cache Bytes per second db.Cache.physical read

bytes

DB block gets Cache Blocks per second db.Cache.db block gets

DBWR checkpoints Cache Checkpoints per minute db.Cache.DBWR

checkpoints

Physical reads Cache Reads per second db.Cache.physical reads

Consistent gets from Cache Gets per second db.Cache.consistent

cache gets from cache

DB block gets from Cache Gets per second db.Cache.db block gets
cache from cache

Consistent gets Cache Gets per second db.Cache.consistent

gets

Performance Insights counters for Amazon RDS for PostgreSQL

The following database counters are available with Performance Insights for Amazon RDS for
PostgreSQL.

Topics
• Native counters for Amazon RDS for PostgreSQL (p. 459)
• Non-native counters for Amazon RDS for PostgreSQL (p. 460)

458
 Amazon Relational Database Service User Guide
Customizing the Performance Insights dashboard

Native counters for Amazon RDS for PostgreSQL

You can find definitions for these native metrics in Viewing Statistics in the PostgreSQL documentation.

Counter Type Unit Metric

blks_hit Cache Blocks per second db.Cache.blks_hit

buffers_alloc Cache Blocks per second db.Cache.buffers_alloc

buffers_checkpoint Checkpoint Blocks per second db.Checkpoint.buffers_checkpoint

checkpoint_sync_time Checkpoint Milliseconds per db.Checkpoint.checkpoint_sync_time

checkpoint

checkpoint_write_time Checkpoint Milliseconds per db.Checkpoint.checkpoint_write_time

checkpoint

checkpoints_req Checkpoint Checkpoints per minute db.Checkpoint.checkpoints_req

checkpoints_timed Checkpoint Checkpoints per minute db.Checkpoint.checkpoints_timed

maxwritten_clean Checkpoint Bgwriter clean stops per db.Checkpoint.maxwritten_clean

minute

deadlocks Concurrency Deadlocks per minute db.Concurrency.deadlocks

blk_read_time I/O Milliseconds db.IO.blk_read_time

blks_read I/O Blocks per second db.IO.blks_read

buffers_backend I/O Blocks per second db.IO.buffers_backend

buffers_backend_fsync I/O Blocks per second db.IO.buffers_backend_fsync

buffers_clean I/O Blocks per second db.IO.buffers_clean

tup_deleted SQL Tuples per second db.SQL.tup_deleted

tup_fetched SQL Tuples per second db.SQL.tup_fetched

tup_inserted SQL Tuples per second db.SQL.tup_inserted

tup_returned SQL Tuples per second db.SQL.tup_returned

tup_updated SQL Tuples per second db.SQL.tup_updated

temp_bytes Temp Bytes per second db.Temp.temp_bytes

temp_files Temp Files per minute db.Temp.temp_files

active_transactions Transactions Transactions db.Transactions.active_transactions

blocked_transactions Transactions Transactions db.Transactions.blocked_transactions

max_used_xact_ids Transactions Transactions db.Transactions.max_used_xact_ids

xact_commit Transactions Commits per second db.Transactions.xact_commit

xact_rollback Transactions Rollbacks per second db.Transactions.xact_rollback

numbackends User Connections db.User.numbackends

459
 Amazon Relational Database Service User Guide
Retrieving data with the Performance Insights API

Counter Type Unit Metric

archived_count Write-ahead log (WAL) Files per minute db.WAL.archived_count

archive_failed_count WAL Files per minute db.WAL.archive_failed_count

Non-native counters for Amazon RDS for PostgreSQL

Non-native counter metrics are counters defined by Amazon RDS. A non-native metric can be a metric
that you get with a specific query. A non-native metric also can be a derived metric, where two or more
native counters are used in calculations for ratios, hit rates, or latencies.

Counter Type Metric Description Definition

checkpoint_sync_latency
Checkpoint db.Checkpoint.checkpoint_sync_latency
The total amount of time checkpoint_sync_time /
that has been spent in (checkpoints_timed +
the portion of checkpoint checkpoints_req)
processing where files are
synchronized to disk.

checkpoint_write_latency
Checkpoint db.Checkpoint.checkpoint_write_latency
The total amount of time checkpoint_write_time /
that has been spent in (checkpoints_timed +
the portion of checkpoint checkpoints_req)
processing where files are
written to disk.

read_latency I/O db.IO.read_latency

The time spent reading blk_read_time /
data file blocks by blks_read
backends in this instance.

Retrieving data with the Performance Insights API

When Performance Insights is enabled for supported engine types, the API provides visibility into
instance performance. 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 (AAS). This metric appears to API consumers as a two-dimensional time-series dataset. The time
dimension of the data provides DB 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.

Amazon RDS Performance Insights monitors your Amazon RDS DB instance so that you can analyze
and troubleshoot database performance. One way to view Performance Insights data is in the AWS
Management Console. Performance Insights also provides a public API so that you can query your
own data. You can use the API to offload data into a database, add Performance Insights data to
existing monitoring dashboards, or to build monitoring tools. To use the Performance Insights API,
enable Performance Insights on one of your Amazon RDS DB instances. For information about enabling
Performance Insights, see Enabling and disabling Performance Insights (p. 421).

The Performance Insights API provides the following operations.

460
 Amazon Relational Database Service User Guide
Retrieving data with the Performance Insights API

Performance Insights Operation AWS CLI Command Description

DescribeDimensionKeys aws pi describe-dimension- Retrieves the top N dimension

keys keys for a metric for a specific time
period.

GetResourceMetrics aws pi get-resource-metrics Retrieves Performance Insights

metrics for a set of data sources,
over a time period. You can
provide specific dimension groups
and dimensions, and provide
aggregation and filtering criteria for
each group.

For more information about the Performance Insights API, see the Amazon RDS Performance Insights
API Reference.

AWS CLI for Performance Insights

You can view Performance Insights data using the AWS CLI. You can view help for the AWS CLI
commands for Performance Insights by entering the following on the command line.

aws pi help

If you don't have the AWS CLI installed, see Installing the AWS Command Line Interface in the AWS CLI
User Guide for information about installing it.

Retrieving time-series metrics

The GetResourceMetrics operation retrieves one or more time-series metrics from the Performance
Insights data. GetResourceMetrics requires a metric and time period, and returns a response with a
list of data points.

For example, the AWS Management Console uses GetResourceMetrics in two places in the
Performance Insights dashboard. GetResourceMetrics is used to populate the Counter Metrics chart
and in the Database Load chart, as seen in the following image.

461
 Amazon Relational Database Service User Guide
Retrieving data with the Performance Insights API

All the metrics returned by GetResourceMetrics are standard time-series metrics with one exception.
The exception is db.load, which is the core metric in Performance Insights. This metric is displayed in
the Database Load chart. The db.load metric is different from the other time-series metrics because
you can break it into subcomponents called dimensions. In the previous image, db.load is broken down
and grouped by the waits states that make up the db.load.
Note
GetResourceMetrics can also return the db.sampleload metric, but the db.load metric is
appropriate in most cases.

For information about the counter metrics returned by GetResourceMetrics, see Customizing the
Performance Insights dashboard (p. 450).

The following calculations are supported for the metrics:

• Average – The average value for the metric over a period of time. Append .avg to the metric name.
• Minimum – The minimum value for the metric over a period of time. Append .min to the metric name.
• Maximum – The maximum value for the metric over a period of time. Append .max to the metric
name.
• Sum – The sum of the metric values over a period of time. Append .sum to the metric name.
• Sample count – The number of times the metric was collected over a period of time. Append
.sample_count to the metric name.

For example, assume that a metric is collected for 300 seconds (5 minutes), and that the metric is
collected one time each minute. The values for each minute are 1, 2, 3, 4, and 5. In this case, the
following calculations are returned:

• Average – 3
• Minimum – 1
• Maximum – 5
• Sum – 15
• Sample count – 5

462
 Amazon Relational Database Service User Guide
Retrieving data with the Performance Insights API

For information about using the get-resource-metrics AWS CLI command, see get-resource-
metrics.

For the --metric-queries option, specify one or more queries that you want to get results for. Each
query consists of a mandatory Metric and optional GroupBy and Filter parameters. The following is
an example of a --metric-queries option specification.

{
"Metric": "string",
"GroupBy": {
"Group": "string",
"Dimensions": ["string", ...],
"Limit": integer
},
"Filter": {"string": "string"
...}
}

AWS CLI examples for Performance Insights

The following are several examples that use the AWS CLI for Performance Insights.

Topics
• Retrieving counter metrics (p. 463)
• Retrieving the DB load average for top wait events (p. 466)
• Retrieving the DB load average for top SQL (p. 468)
• Retrieving the DB Load Average Filtered by SQL (p. 470)

Retrieving counter metrics

The following screenshot shows two counter metrics charts in the AWS Management Console.

The following example shows how to gather the same data that the AWS Management Console uses to
generate the two counter metric charts.

For Linux, macOS, or Unix:

463
 Amazon Relational Database Service User Guide
Retrieving data with the Performance Insights API

aws pi get-resource-metrics \
--service-type RDS \
--identifier db-ID \
--start-time 2018-10-30T00:00:00Z \
--end-time 2018-10-30T01:00:00Z \
--period-in-seconds 60 \
--metric-queries '[{"Metric": "os.cpuUtilization.user.avg" },
{"Metric": "os.cpuUtilization.idle.avg"}]'

For Windows:

aws pi get-resource-metrics ^
--service-type RDS ^
--identifier db-ID ^
--start-time 2018-10-30T00:00:00Z ^
--end-time 2018-10-30T01:00:00Z ^
--period-in-seconds 60 ^
--metric-queries '[{"Metric": "os.cpuUtilization.user.avg" },
{"Metric": "os.cpuUtilization.idle.avg"}]'

You can also make a command easier to read by specifying a file for the --metrics-query option. The
following example uses a file called query.json for the option. The file has the following contents.

[
{
"Metric": "os.cpuUtilization.user.avg"
},
{
"Metric": "os.cpuUtilization.idle.avg"
}
]

Run the following command to use the file.

For Linux, macOS, or Unix:

aws pi get-resource-metrics \
--service-type RDS \
--identifier db-ID \
--start-time 2018-10-30T00:00:00Z \
--end-time 2018-10-30T01:00:00Z \
--period-in-seconds 60 \
--metric-queries file://query.json

For Windows:

aws pi get-resource-metrics ^
--service-type RDS ^
--identifier db-ID ^
--start-time 2018-10-30T00:00:00Z ^
--end-time 2018-10-30T01:00:00Z ^

464
 Amazon Relational Database Service User Guide
Retrieving data with the Performance Insights API

--period-in-seconds 60 ^
--metric-queries file://query.json

The preceding example specifies the following values for the options:

• --service-type – RDS for Amazon RDS

• --identifier – The resource ID for the DB instance
• --start-time and --end-time – The ISO 8601 DateTime values for the period to query, with
multiple supported formats

It queries for a one-hour time range:

• --period-in-seconds – 60 for a per-minute query

• --metric-queries – An array of two queries, each just for one metric.

The metric name uses dots to classify the metric in a useful category, with the final element being
a function. In the example, the function is avg for each query. As with Amazon CloudWatch, the
supported functions are min, max, total, and avg.

The response looks similar to the following.

{
"Identifier": "db-XXX",
"AlignedStartTime": 1540857600.0,
"AlignedEndTime": 1540861200.0,
"MetricList": [
{ //A list of key/datapoints
"Key": {
"Metric": "os.cpuUtilization.user.avg" //Metric1
},
"DataPoints": [
//Each list of datapoints has the same timestamps and same number of items
{
"Timestamp": 1540857660.0, //Minute1
"Value": 4.0
},
{
"Timestamp": 1540857720.0, //Minute2
"Value": 4.0
},
{
"Timestamp": 1540857780.0, //Minute 3
"Value": 10.0
}
//... 60 datapoints for the os.cpuUtilization.user.avg metric
]
},
{
"Key": {
"Metric": "os.cpuUtilization.idle.avg" //Metric2
},
"DataPoints": [
{
"Timestamp": 1540857660.0, //Minute1
"Value": 12.0
},
{
"Timestamp": 1540857720.0, //Minute2

465
 Amazon Relational Database Service User Guide
Retrieving data with the Performance Insights API

"Value": 13.5
},
//... 60 datapoints for the os.cpuUtilization.idle.avg metric
]
}
] //end of MetricList
} //end of response

The response has an Identifier, AlignedStartTime, and AlignedEndTime. B the --period-in-

seconds value was 60, the start and end times have been aligned to the minute. If the --period-in-
seconds was 3600, the start and end times would have been aligned to the hour.

The MetricList in the response has a number of entries, each with a Key and a DataPoints entry.
Each DataPoint has a Timestamp and a Value. Each Datapoints list has 60 data points because the
queries are for per-minute data over an hour, with Timestamp1/Minute1, Timestamp2/Minute2, and
so on, up to Timestamp60/Minute60.

Because the query is for two different counter metrics, there are two elements in the response
MetricList.

Retrieving the DB load average for top wait events

The following example is the same query that the AWS Management Console uses to generate a
stacked area line graph. This example retrieves the db.load.avg for the last hour with load divided
according to the top seven wait events. The command is the same as the command in Retrieving counter
metrics (p. 463). However, the query.json file has the following contents.

[
{
"Metric": "db.load.avg",
"GroupBy": { "Group": "db.wait_event", "Limit": 7 }
}
]

Run the following command.

For Linux, macOS, or Unix:

aws pi get-resource-metrics \
--service-type RDS \
--identifier db-ID \
--start-time 2018-10-30T00:00:00Z \
--end-time 2018-10-30T01:00:00Z \
--period-in-seconds 60 \
--metric-queries file://query.json

For Windows:

aws pi get-resource-metrics ^
--service-type RDS ^
--identifier db-ID ^
--start-time 2018-10-30T00:00:00Z ^
--end-time 2018-10-30T01:00:00Z ^
--period-in-seconds 60 ^
--metric-queries file://query.json

466
 Amazon Relational Database Service User Guide
Retrieving data with the Performance Insights API

The example specifies the metric of db.load.avg and a GroupBy of the top seven wait events.
For details about valid values for this example, see DimensionGroup in the Performance Insights API
Reference.

The response looks similar to the following.

{
"Identifier": "db-XXX",
"AlignedStartTime": 1540857600.0,
"AlignedEndTime": 1540861200.0,
"MetricList": [
{ //A list of key/datapoints
"Key": {
//A Metric with no dimensions. This is the total db.load.avg
"Metric": "db.load.avg"
},
"DataPoints": [
//Each list of datapoints has the same timestamps and same number of items
{
"Timestamp": 1540857660.0, //Minute1
"Value": 0.5166666666666667
},
{
"Timestamp": 1540857720.0, //Minute2
"Value": 0.38333333333333336
},
{
"Timestamp": 1540857780.0, //Minute 3
"Value": 0.26666666666666666
}
//... 60 datapoints for the total db.load.avg key
]
},
{
"Key": {
//Another key. This is db.load.avg broken down by CPU
"Metric": "db.load.avg",
"Dimensions": {
"db.wait_event.name": "CPU",
"db.wait_event.type": "CPU"
}
},
"DataPoints": [
{
"Timestamp": 1540857660.0, //Minute1
"Value": 0.35
},
{
"Timestamp": 1540857720.0, //Minute2
"Value": 0.15
},
//... 60 datapoints for the CPU key
]
},
//... In total we have 8 key/datapoints entries, 1) total, 2-8) Top Wait Events
] //end of MetricList
} //end of response

In this response, there are eight entries in the MetricList. There is one entry for the total
db.load.avg, and seven entries each for the db.load.avg divided according to one of the top seven
wait events. Unlike in the first example, because there was a grouping dimension, there must be one
key for each grouping of the metric. There can't be only one key for each metric, as in the basic counter
metric use case.

467
 Amazon Relational Database Service User Guide
Retrieving data with the Performance Insights API

Retrieving the DB load average for top SQL

The following example groups db.wait_events by the top 10 SQL statements. There are two different
groups for SQL statements:

• db.sql – The full SQL statement, such as select * from customers where customer_id =
123
• db.sql_tokenized – The tokenized SQL statement, such as select * from customers where
customer_id = ?

When analyzing database performance, it can be useful to consider SQL statements that only differ
by their parameters as one logic item. So, you can use db.sql_tokenized when querying. However,
especially when you are interested in explain plans, sometimes it's more useful to examine full SQL
statements with parameters, and query grouping by db.sql. There is a parent-child relationship
between tokenized and full SQL, with multiple full SQL (children) grouped under the same tokenized
SQL (parent).

The command in this example is the similar to the command in Retrieving the DB load average for top
wait events (p. 466). However, the query.json file has the following contents.

[
{
"Metric": "db.load.avg",
"GroupBy": { "Group": "db.sql_tokenized", "Limit": 10 }
}
]

The following example uses db.sql_tokenized.

For Linux, macOS, or Unix:

aws pi get-resource-metrics \
--service-type RDS \
--identifier db-ID \
--start-time 2018-10-29T00:00:00Z \
--end-time 2018-10-30T00:00:00Z \
--period-in-seconds 3600 \
--metric-queries file://query.json

For Windows:

aws pi get-resource-metrics ^
--service-type RDS ^
--identifier db-ID ^
--start-time 2018-10-29T00:00:00Z ^
--end-time 2018-10-30T00:00:00Z ^
--period-in-seconds 3600 ^
--metric-queries file://query.json

This example queries over 24 hours, with a one hour period-in-seconds.

The example specifies the metric of db.load.avg and a GroupBy of the top seven wait events.
For details about valid values for this example, see DimensionGroup in the Performance Insights API
Reference.

The response looks similar to the following.

468
 Amazon Relational Database Service User Guide
Retrieving data with the Performance Insights API

{
"AlignedStartTime": 1540771200.0,
"AlignedEndTime": 1540857600.0,
"Identifier": "db-XXX",

"MetricList": [ //11 entries in the MetricList

{
"Key": { //First key is total
"Metric": "db.load.avg"
}
"DataPoints": [ //Each DataPoints list has 24 per-hour Timestamps and a value
{
"Value": 1.6964980544747081,
"Timestamp": 1540774800.0
},
//... 24 datapoints
]
},
{
"Key": { //Next key is the top tokenized SQL
"Dimensions": {
"db.sql_tokenized.statement": "INSERT INTO authors (id,name,email)
VALUES\n( nextval(?) ,?,?)",
"db.sql_tokenized.db_id": "pi-2372568224",
"db.sql_tokenized.id": "AKIAIOSFODNN7EXAMPLE"
},
"Metric": "db.load.avg"
},
"DataPoints": [ //... 24 datapoints
]
},
// In total 11 entries, 10 Keys of top tokenized SQL, 1 total key
] //End of MetricList
} //End of response

This response has 11 entries in the MetricList (1 total, 10 top tokenized SQL), with each entry having
24 per-hour DataPoints.

For tokenized SQL, there are three entries in each dimensions list:

• db.sql_tokenized.statement – The tokenized SQL statement.

• db.sql_tokenized.db_id – Either the native database ID used to refer to the SQL, or a synthetic
ID that Performance Insights generates for you if the native database ID isn't available. This example
returns the pi-2372568224 synthetic ID.
• db.sql_tokenized.id – The ID of the query inside Performance Insights.

In the AWS Management Console, this ID is called the Support ID. It's named this because the ID is
data that AWS Support can examine to help you troubleshoot an issue with your database. AWS takes
the security and privacy of your data extremely seriously, and almost all data is stored encrypted with
your AWS KMS customer master key (CMK). Therefore, nobody inside AWS can look at this data. In
the example preceding, both the tokenized.statement and the tokenized.db_id are stored
encrypted. If you have an issue with your database, AWS Support can help you by referencing the
Support ID.

When querying, it might be convenient to specify a Group in GroupBy. However, for finer-grained
control over the data that's returned, specify the list of dimensions. For example, if all that is needed is
the db.sql_tokenized.statement, then a Dimensions attribute can be added to the query.json file.

[
{

469
 Amazon Relational Database Service User Guide
Retrieving data with the Performance Insights API

"Metric": "db.load.avg",
"GroupBy": {
"Group": "db.sql_tokenized",
"Dimensions":["db.sql_tokenized.statement"],
"Limit": 10
}
}
]

Retrieving the DB Load Average Filtered by SQL

The preceding image shows that a particular query is selected, and the top average active sessions
stacked area line graph is scoped to that query. Although the query is still for the top seven overall wait
events, the value of the response is filtered. The filter causes it to take into account only sessions that are
a match for the particular filter.

The corresponding API query in this example is similar to the command in Retrieving the DB load average
for top SQL (p. 468). However, the query.json file has the following contents.

[
{
"Metric": "db.load.avg",
"GroupBy": { "Group": "db.wait_event", "Limit": 5 },
"Filter": { "db.sql_tokenized.id": "AKIAIOSFODNN7EXAMPLE" }
}
]

For Linux, macOS, or Unix:

aws pi get-resource-metrics \
--service-type RDS \
--identifier db-ID \
--start-time 2018-10-30T00:00:00Z \
--end-time 2018-10-30T01:00:00Z \
--period-in-seconds 60 \
--metric-queries file://query.json

470
 Amazon Relational Database Service User Guide
Retrieving data with the Performance Insights API

For Windows:

aws pi get-resource-metrics ^
--service-type RDS ^
--identifier db-ID ^
--start-time 2018-10-30T00:00:00Z ^
--end-time 2018-10-30T01:00:00Z ^
--period-in-seconds 60 ^
--metric-queries file://query.json

The response looks similar to the following.

{
"Identifier": "db-XXX",
"AlignedStartTime": 1556215200.0,
"MetricList": [
{
"Key": {
"Metric": "db.load.avg"
},
"DataPoints": [
{
"Timestamp": 1556218800.0,
"Value": 1.4878117913832196
},
{
"Timestamp": 1556222400.0,
"Value": 1.192823803967328
}
]
},
{
"Key": {
"Metric": "db.load.avg",
"Dimensions": {
"db.wait_event.type": "io",
"db.wait_event.name": "wait/io/aurora_redo_log_flush"
}
},
"DataPoints": [
{
"Timestamp": 1556218800.0,
"Value": 1.1360544217687074
},
{
"Timestamp": 1556222400.0,
"Value": 1.058051341890315
}
]
},
{
"Key": {
"Metric": "db.load.avg",
"Dimensions": {
"db.wait_event.type": "io",
"db.wait_event.name": "wait/io/table/sql/handler"
}
},
"DataPoints": [
{
"Timestamp": 1556218800.0,
"Value": 0.16241496598639457
},
{

471
 Amazon Relational Database Service User Guide
Retrieving data with the Performance Insights API

"Timestamp": 1556222400.0,
"Value": 0.05163360560093349
}
]
},
{
"Key": {
"Metric": "db.load.avg",
"Dimensions": {
"db.wait_event.type": "synch",
"db.wait_event.name": "wait/synch/mutex/innodb/
aurora_lock_thread_slot_futex"
}
},
"DataPoints": [
{
"Timestamp": 1556218800.0,
"Value": 0.11479591836734694
},
{
"Timestamp": 1556222400.0,
"Value": 0.013127187864644107
}
]
},
{
"Key": {
"Metric": "db.load.avg",
"Dimensions": {
"db.wait_event.type": "CPU",
"db.wait_event.name": "CPU"
}
},
"DataPoints": [
{
"Timestamp": 1556218800.0,
"Value": 0.05215419501133787
},
{
"Timestamp": 1556222400.0,
"Value": 0.05805134189031505
}
]
},
{
"Key": {
"Metric": "db.load.avg",
"Dimensions": {
"db.wait_event.type": "synch",
"db.wait_event.name": "wait/synch/mutex/innodb/lock_wait_mutex"
}
},
"DataPoints": [
{
"Timestamp": 1556218800.0,
"Value": 0.017573696145124718
},
{
"Timestamp": 1556222400.0,
"Value": 0.002333722287047841
}
]
}
],
"AlignedEndTime": 1556222400.0
} //end of response

472
 Amazon Relational Database Service User Guide
Metrics published to CloudWatch

In this response, all values are filtered according to the contribution of tokenized SQL
AKIAIOSFODNN7EXAMPLE specified in the query.json file. The keys also might follow a different order
than a query without a filter, because it's the top five wait events that affected the filtered SQL.

Performance Insights metrics published to Amazon

CloudWatch
Performance Insights automatically publishes metrics to Amazon CloudWatch. The same data can
be queried from Performance Insights, but having the metrics in CloudWatch makes it easy to add
CloudWatch alarms. It also makes it easy to add the metrics to existing CloudWatch Dashboards.

Metric Description

DBLoad The number of active sessions for the DB engine.

Typically, you want the data for the average
number of active sessions. In Performance
Insights, this data is queried as db.load.avg.

DBLoadCPU The number of active sessions where the wait

event type is CPU. In Performance Insights, this
data is queried as db.load.avg, filtered by the
wait event type CPU.

DBLoadNonCPU The number of active sessions where the wait

event type is not CPU.

Note
These metrics are published to CloudWatch only if there is load on the DB instance.

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 Average \
--start-time 1532035185 \
--end-time 1532036185 \
--dimensions Name=DBInstanceIdentifier,Value=db-loadtest-0

This example generates output similar to the following.

{
"Datapoints": [
{
"Timestamp": "2018-07-19T21:30:00Z",
"Unit": "None",
"Average": 2.1
},

473
 Amazon Relational Database Service User Guide
Logging Performance Insights
calls by using AWS CloudTrail

{
"Timestamp": "2018-07-19T21:34:00Z",
"Unit": "None",
"Average": 1.7
},
{
"Timestamp": "2018-07-19T21:35:00Z",
"Unit": "None",
"Average": 2.8
},
{
"Timestamp": "2018-07-19T21:31:00Z",
"Unit": "None",
"Average": 1.5
},
{
"Timestamp": "2018-07-19T21:32:00Z",
"Unit": "None",
"Average": 1.8
},
{
"Timestamp": "2018-07-19T21:29:00Z",
"Unit": "None",
"Average": 3.0
},
{
"Timestamp": "2018-07-19T21:33:00Z",
"Unit": "None",
"Average": 2.4
}
],
"Label": "DBLoad"
}

For more information about CloudWatch, see What is Amazon CloudWatch? in the Amazon CloudWatch
User Guide.

Logging Performance Insights calls by using AWS

CloudTrail
Performance Insights runs with AWS CloudTrail, a service that provides a record of actions taken by a
user, role, or an AWS service in Performance Insights. CloudTrail captures all API calls for Performance
Insights as events. This capture includes calls from the Amazon RDS console and from code calls to the
Performance Insights API operations.

If you create a trail, you can enable continuous delivery of CloudTrail events to an Amazon S3 bucket,
including events for Performance Insights. If you don't configure a trail, you can still view the most
recent events in the CloudTrail console in Event history. Using the data collected by CloudTrail, you can
determine certain information. This information includes the request that was made to Performance
Insights, the IP address the request was made from, who made the request, and when it was made. It
also includes additional details.

To learn more about CloudTrail, see the AWS CloudTrail User Guide.

Working with Performance Insights information in CloudTrail

CloudTrail is enabled on your AWS account when you create the account. When activity occurs in
Performance Insights, that activity is recorded in a CloudTrail event along with other AWS service events
in the CloudTrail console in Event history. You can view, search, and download recent events in your AWS

474
 Amazon Relational Database Service User Guide
Logging Performance Insights
calls by using AWS CloudTrail

account. For more information, see Viewing Events with CloudTrail Event History in AWS CloudTrail User
Guide.

For an ongoing record of events in your AWS account, including events for Performance Insights, 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 AWS Regions. The trail logs events from all AWS 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 the following topics in AWS CloudTrail User Guide:

• 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 Performance Insights operations are logged by CloudTrail and are documented in the Performance
Insights API Reference. For example, calls to the DescribeDimensionKeys and GetResourceMetrics
operations 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.

Performance Insights 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. Each event includes information about the requested operation, the date and time of the
operation, request parameters, and so on. CloudTrail log files aren't an ordered stack trace of the public
API calls, so they don't appear in any specific order.

The following example shows a CloudTrail log entry that demonstrates the GetResourceMetrics
operation.

{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "AKIAIOSFODNN7EXAMPLE",
"arn": "arn:aws:iam::123456789012:user/johndoe",
"accountId": "123456789012",
"accessKeyId": "AKIAI44QH8DHBEXAMPLE",
"userName": "johndoe"
},
"eventTime": "2019-12-18T19:28:46Z",
"eventSource": "pi.amazonaws.com",
"eventName": "GetResourceMetrics",
"awsRegion": "us-east-1",
"sourceIPAddress": "72.21.198.67",
"userAgent": "aws-cli/1.16.240 Python/3.7.4 Darwin/18.7.0 botocore/1.12.230",
"requestParameters": {

475
 Amazon Relational Database Service User Guide
Logging Performance Insights
calls by using AWS CloudTrail

"identifier": "db-YTDU5J5V66X7CXSCVDFD2V3SZM",
"metricQueries": [
{
"metric": "os.cpuUtilization.user.avg"
},
{
"metric": "os.cpuUtilization.idle.avg"
}
],
"startTime": "Dec 18, 2019 5:28:46 PM",
"periodInSeconds": 60,
"endTime": "Dec 18, 2019 7:28:46 PM",
"serviceType": "RDS"
},
"responseElements": null,
"requestID": "9ffbe15c-96b5-4fe6-bed9-9fccff1a0525",
"eventID": "08908de0-2431-4e2e-ba7b-f5424f908433",
"eventType": "AwsApiCall",
"recipientAccountId": "123456789012"
}

476
 Amazon Relational Database Service User Guide
Using Enhanced Monitoring

Using 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. Also, you can consume the Enhanced
Monitoring JSON output from Amazon CloudWatch Logs in a monitoring system of your choice.

By default, Enhanced Monitoring metrics are stored for 30 days in the CloudWatch Logs, which are
different from typical CloudWatch metrics. To modify the amount of time the metrics are stored in the
CloudWatch Logs, change the retention for the RDSOSMetrics log group in the CloudWatch console.
For more information, see Change log data retention in CloudWatch logs in the Amazon CloudWatch Logs
User Guide.

Because Enhanced Monitoring metrics are stored in the CloudWatch logs instead of in Cloudwatch
metrics, the cost of Enhanced Monitoring 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 the db.m1.small instance class.

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 and enabling Enhanced Monitoring

To use Enhanced Monitoring, you must create an IAM role, and then enable Enhanced Monitoring.

477
 Amazon Relational Database Service User Guide
Setting up and enabling Enhanced Monitoring

Creating an IAM role for Enhanced Monitoring

Enhanced Monitoring requires permission to act on your behalf to send OS metric information to
CloudWatch Logs. You grant Enhanced Monitoring permissions using an AWS Identity and Access
Management (IAM) role.

Creating the IAM role when you enable Enhanced Monitoring

When you enable Enhanced Monitoring in the RDS console, Amazon RDS can create the required IAM role
for you. The role is named rds-monitoring-role. RDS uses this role for the specified DB instance or
read replica.

To create the IAM role when enabling Enhanced Monitoring

1. Follow the steps in Enabling and disabling Enhanced Monitoring (p. 478).
2. Set Monitoring Role to Default in the step where you choose a role.

Creating the IAM role before you enable Enhanced Monitoring

You can create the required role before you enable Enhanced Monitoring. When you enable Enhanced
Monitoring, specify your new role's name. You must create this required role if you enable Enhanced
Monitoring using the AWS CLI or the RDS API.

The user that enables Enhanced Monitoring must be granted the PassRole permission. For more
information, see Example 2 in Granting a user permissions to pass a role to an AWS service in the IAM
User Guide.

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. Ensure that the Attached permissions policy page shows AmazonRDSEnhancedMonitoringRole,
and then choose Next: Tags.
7. On the Add tags page, choose Next: Review.
8. For Role Name, enter a name for your role. For example, enter emaccess.

The trusted entity for your role is the AWS service monitoring.rds.amazonaws.com.
9. Choose Create role.

Enabling and disabling Enhanced Monitoring

You can enable and disable Enhanced Monitoring using the AWS Management Console, AWS CLI, or RDS
API.

Console

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 don't need to reboot
your DB instance for the change to take effect.

478
 Amazon Relational Database Service User Guide
Setting up and enabling Enhanced Monitoring

You can enable Enhanced Monitoring in the RDS console when you do one of the following actions:

• Create a DB instance – You can enable Enhanced Monitoring in the Monitoring section under
Additional configuration.
• Create a read replica – You can enable Enhanced Monitoring in the Monitoring section.
• Modify a DB instance – You can enable Enhanced Monitoring in the Monitoring section.

To enable Enhanced Monitoring by using the RDS console

1. Scroll to the Monitoring section.

2. Choose Enable enhanced monitoring for your DB instance or read replica. To disable Enhanced
Monitoring, choose Disable enhanced monitoring.

3. 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.
4. 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.

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.

AWS CLI

To enable Enhanced Monitoring using the AWS CLI, in the following commands, set the --monitoring-
interval option to a value other than 0 and set the --monitoring-role-arn option to the role you
created in Creating an IAM role for Enhanced Monitoring (p. 478).

• create-db-instance
• create-db-instance-read-replica
• modify-db-instance

479
 Amazon Relational Database Service User Guide
Viewing Enhanced Monitoring

The --monitoring-interval option specifies the interval, in seconds, between points when Enhanced
Monitoring metrics are collected. Valid values for the option are 0, 1, 5, 10, 15, 30, and 60.

To disable Enhanced Monitoring using the AWS CLI, set the --monitoring-interval option to 0 in
the these commands.

Example

The following example enables Enhanced Monitoring for a DB instance:

For Linux, macOS, or Unix:

aws rds modify-db-instance \

--db-instance-identifier mydbinstance \
--monitoring-interval 30 \
--monitoring-role-arn arn:aws:iam::123456789012:role/emaccess

For Windows:

aws rds modify-db-instance ^

--db-instance-identifier mydbinstance ^
--monitoring-interval 30 ^
--monitoring-role-arn arn:aws:iam::123456789012:role/emaccess

RDS API

To enable Enhanced Monitoring using the RDS API, set the MonitoringInterval parameter to a value
other than 0 and set the MonitoringRoleArn parameter to the role you created in Creating an IAM role
for Enhanced Monitoring (p. 478). Set these parameters in the following actions:

• CreateDBInstance
• CreateDBInstanceReadReplica
• ModifyDBInstance

The MonitoringInterval parameter specifies the interval, in seconds, between points when Enhanced
Monitoring metrics are collected. Valid values are 0, 1, 5, 10, 15, 30, and 60.

To disable Enhanced Monitoring using the RDS API, set MonitoringInterval to 0.

Viewing Enhanced Monitoring

You can view OS metrics reported by Enhanced Monitoring in the RDS console by choosing Enhanced
monitoring for Monitoring.

The Enhanced Monitoring page is shown following.

480
 Amazon Relational Database Service User Guide
Viewing Enhanced Monitoring

Some DB instances use more than one disk for the DB instance's data storage volume. On those
DB instances, the Physical Devices graphs show metrics for each one of the disks. For example, the
following graph shows metrics for four disks.

Note
Currently, Physical Devices graphs are not available for Microsoft SQL Server DB instances.

When you are viewing aggregated Disk I/O and File system graphs, the rdsdev device relates to the /
rdsdbdata file system, where all database files and logs are stored. The filesystem device relates to the
/ file system (also known as root), where files related to the operating system are stored.

481
 Amazon Relational Database Service User Guide
Viewing Enhanced Monitoring

If the DB instance is a Multi-AZ deployment, you can view the OS metrics for the primary DB instance
and its Multi-AZ standby replica. In the Enhanced monitoring view, choose primary to view the OS
metrics for the primary DB instance, or choose secondary to view the OS metrics for the standby replica.

For more information about Multi-AZ deployments, see High availability (Multi-AZ) for Amazon
RDS (p. 53).
Note
Currently, viewing OS metrics for a Multi-AZ standby replica is not supported for MariaDB or
Microsoft SQL Server DB instances.

If you want to see details for the processes running on your DB instance, choose OS process list for
Monitoring.

The Process List view is shown following.

482
 Amazon Relational Database Service User Guide
Viewing Enhanced Monitoring

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 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 total CPU bandwidth being used by the process.
• MEM% – Displays the percentage of the total memory being used 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. 484).

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.

483
 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. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

2. If necessary, choose the region that your DB instance is in. For more information, see Regions and
endpoints in the Amazon Web Services General Reference.
3. Choose Logs in the navigation pane.
4. Choose RDSOSMetrics from the list of log groups.

In a Multi-AZ deployment, log files with -secondary appended to the name are for the Multi-AZ
standby replica.

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 Metric Console Description

name

General engine Not The database engine for the DB instance.

applicable

instanceID Not The DB instance identifier.

applicable

Not
instanceResourceID An immutable identifier for the DB instance that is unique
applicable to an AWS Region, also used as the log stream identifier.

numVCPUs Not The number of virtual CPUs for the DB instance.

applicable

484
 Amazon Relational Database Service User Guide
Viewing Enhanced Monitoring by using CloudWatch Logs

Group Metric Console Description

name

timestamp Not The time at which the metrics were taken.

applicable

uptime Not The amount of time that the DB instance has been active.
applicable

version Not The version of the OS metrics' stream JSON format.

applicable

cpuUtilization
guest CPU Guest The percentage of CPU in use by guest programs.

idle CPU Idle The percentage of CPU that is idle.

irq CPU IRQ The percentage of CPU in use by software interrupts.

nice CPU Nice The percentage of CPU in use by programs running at

lowest priority.

steal CPU Steal The percentage of CPU in use by other virtual machines.

system CPU System The percentage of CPU in use by the kernel.

total CPU Total The total percentage of the CPU in use. This value
includes the nice value.

user CPU User The percentage of CPU in use by user programs.

wait CPU Wait The percentage of CPU unused while waiting for I/O
access.

diskIO avgQueueLen Avg Queue The number of requests waiting in the I/O device's queue.
Size

avgReqSz Ave Request The average request size, in kilobytes.

Size

await Disk I/O The number of milliseconds required to respond to

Await requests, including queue time and service time.

device Not The identifier of the disk device in use.

applicable

readIOsPS Read IO/s The number of read operations per second.

readKb Read Total The total number of kilobytes read.

readKbPS Read Kb/s The number of kilobytes read per second.

readLatency Read The elapsed time between the submission of a read I/O
Latency request and its completion, in milliseconds.

This metric is only available for Amazon Aurora.

Read
readThroughput The amount of network throughput used by requests to
Throughput the DB cluster, in bytes per second.

This metric is only available for Amazon Aurora.

rrqmPS Rrqms The number of merged read requests queued per second.

485
 Amazon Relational Database Service User Guide
Viewing Enhanced Monitoring by using CloudWatch Logs

Group Metric Console Description

name

tps TPS The number of I/O transactions per second.

util Disk I/O The percentage of CPU time during which requests were
Util issued.

writeIOsPS Write IO/s The number of write operations per second.

writeKb Write Total The total number of kilobytes written.

writeKbPS Write Kb/s The number of kilobytes written per second.

writeLatencyWrite The average elapsed time between the submission of a

Latency write I/O request and its completion, in milliseconds.

This metric is only available for Amazon Aurora.

Write
writeThroughput The amount of network throughput used by responses
Throughput from the DB cluster, in bytes per second.

This metric is only available for Amazon Aurora.

wrqmPS Wrqms The number of merged write requests queued per second.

avgQueueLen Physical
physicalDeviceIO The number of requests waiting in the I/O device's queue.
Devices Avg
Queue Size

avgReqSz Physical The average request size, in kilobytes.

Devices Ave
Request
Size

await Physical The number of milliseconds required to respond to

Devices Disk requests, including queue time and service time.
I/O Await

device Not The identifier of the disk device in use.

applicable

readIOsPS Physical The number of read operations per second.

Devices
Read IO/s

readKb Physical The total number of kilobytes read.

Devices
Read Total

readKbPS Physical The number of kilobytes read per second.

Devices
Read Kb/s

rrqmPS Physical The number of merged read requests queued per second.
Devices
Rrqms

tps Physical The number of I/O transactions per second.

Devices TPS

486
 Amazon Relational Database Service User Guide
Viewing Enhanced Monitoring by using CloudWatch Logs

Group Metric Console Description

name

util Physical The percentage of CPU time during which requests were
Devices Disk issued.
I/O Util

writeIOsPS Physical The number of write operations per second.

Devices
Write IO/s

writeKb Physical The total number of kilobytes written.

Devices
Write Total

writeKbPS Physical The number of kilobytes written per second.

Devices
Write Kb/s

wrqmPS Physical The number of merged write requests queued per second.
Devices
Wrqms

fileSys maxFiles Max Inodes The maximum number of files that can be created for the
file system.

mountPoint Not The path to the file system.

applicable

name Not The name of the file system.

applicable

total Total The total number of disk space available for the file
Filesystem system, in kilobytes.

used Used The amount of disk space used by files in the file system,
Filesystem in kilobytes.

Used %
usedFilePercent The percentage of available files in use.

usedFiles Used Inodes The number of files in the file system.

usedPercent Used Inodes The percentage of the file-system disk space in use.
%

loadAverageMinute
fifteen Load Avg 15 The number of processes requesting CPU time over the
min last 15 minutes.

five Load Avg 5 The number of processes requesting CPU time over the
min last 5 minutes.

one Load Avg 1 The number of processes requesting CPU time over the
min last minute.

memory active Active The amount of assigned memory, in kilobytes.

Memory

buffers Buffered The amount of memory used for buffering I/O requests
Memory prior to writing to the storage device, in kilobytes.

487
 Amazon Relational Database Service User Guide
Viewing Enhanced Monitoring by using CloudWatch Logs

Group Metric Console Description

name

cached Cached The amount of memory used for caching file system–
Memory based I/O.

dirty Dirty The amount of memory pages in RAM that have been
Memory modified but not written to their related data block in
storage, in kilobytes.

free Free The amount of unassigned memory, in kilobytes.

Memory

Huge Pages
hugePagesFree The number of free huge pages. Huge pages are a feature
Free of the Linux kernel.

Huge Pages
hugePagesRsvd The number of committed huge pages.
Rsvd

Huge Pages
hugePagesSize The size for each huge pages unit, in kilobytes.
Size

Huge Pages
hugePagesSurp The number of available surplus huge pages over the
Surp total.

Huge Pages
hugePagesTotal The total number of huge pages.
Total

inactive Inactive The amount of least-frequently used memory pages, in

Memory kilobytes.

mapped Mapped The total amount of file-system contents that is memory

Memory mapped inside a process address space, in kilobytes.

pageTables Page Tables The amount of memory used by page tables, in kilobytes.

slab Slab The amount of reusable kernel data structures, in

Memory kilobytes.

total Total The total amount of memory, in kilobytes.

Memory

writeback Writeback The amount of dirty pages in RAM that are still being
Memory written to the backing storage, in kilobytes.

network interface Not The identifier for the network interface being used for the
applicable DB instance.

rx RX The number of bytes received per second.

tx TX The number of bytes uploaded per second.

processList cpuUsedPc CPU % The percentage of CPU used by the process.

id Not The identifier of the process.

applicable

memoryUsedPcMEM% The percentage of memory used by the process.

name Not The name of the process.

applicable

488
 Amazon Relational Database Service User Guide
Viewing Enhanced Monitoring by using CloudWatch Logs

Group Metric Console Description

name

parentID Not The process identifier for the parent process of the
applicable process.

rss RES The amount of RAM allocated to the process, in kilobytes.

tgid Not The thread group identifier, which is a number

applicable representing the process ID to which a thread belongs.
This identifier is used to group threads from the same
process.

vss VIRT The amount of virtual memory allocated to the process,

in kilobytes.

swap swap Swap The amount of swap memory available, in kilobytes.

swap in Swaps in The amount of memory, in kilobytes, swapped in from

disk.

swap out Swaps out The amount of memory, in kilobytes, swapped out to
disk.

free Free Swap The amount of swap memory free, in kilobytes.

committed Committed The amount of swap memory, in kilobytes, used as cache

Swap memory.

tasks blocked Tasks The number of tasks that are blocked.

Blocked

running Tasks The number of tasks that are running.

Running

sleeping Tasks The number of tasks that are sleeping.

Sleeping

stopped Tasks The number of tasks that are stopped.

Stopped

total Tasks Total The total number of tasks.

zombie Tasks The number of child tasks that are inactive with an active
Zombie parent task.

Metrics for Microsoft SQL Server DB instances

Group Metric Console name Description

General engine Not applicable The database engine for the DB instance.

instanceID Not applicable The DB instance identifier.

Not applicable
instanceResourceID An immutable identifier for the DB instance that
is unique to an AWS Region, also used as the log
stream identifier.

numVCPUs Not applicable The number of virtual CPUs for the DB instance.

489
 Amazon Relational Database Service User Guide
Viewing Enhanced Monitoring by using CloudWatch Logs

Group Metric Console name Description

timestamp Not applicable The time at which the metrics were taken.

uptime Not applicable The amount of time that the DB instance has been
active.

version Not applicable The version of the OS metrics' stream JSON

format.

cpuUtilizationidle CPU Idle The percentage of CPU that is idle.

kern CPU Kernel The percentage of CPU in use by the kernel.

user CPU User The percentage of CPU in use by user programs.

disks name Not applicable The identifier for the disk.

totalKb Total Disk The total space of the disk, in kilobytes.

Space

usedKb Used Disk The amount of space used on the disk, in

Space kilobytes.

usedPc Used Disk The percentage of space used on the disk.

Space %

availKb Available Disk The space available on the disk, in kilobytes.

Space

availPc Available Disk The percentage of space available on the disk.

Space %

rdCountPS Reads/s The number of read operations per second

rdBytesPS Read Kb/s The number of bytes read per second.

wrCountPS Write IO/s The number of write operations per second.

wrBytesPS Write Kb/s The amount of bytes written per second.

memory commitTotKb Commit Total 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 Maximum The maximum possible value for the

Commit 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 nonpageable areas.

commitPeakKb Commit Peak The largest value of the commitTotKb metric

since the operating system was last started.

kernTotKb Total Kernel The sum of the memory in the paged and
Memory nonpaged kernel pools, in kilobytes.

kernPagedKb Paged Kernel The amount of memory in the paged kernel pool,
Memory in kilobytes.

490
 Amazon Relational Database Service User Guide
Viewing Enhanced Monitoring by using CloudWatch Logs

Group Metric Console name Description

kernNonpagedKbNonpaged The amount of memory in the nonpaged kernel

Kerenel pool, in kilobytes.
Memory

pageSize Page Size The size of a page, in bytes.

physTotKb Total Memory The amount of physical memory, in kilobytes.

physAvailKb Available The amount of available physical memory, in

Memory kilobytes.

sqlServerTotKbSQL Server The amount of memory committed to SQL Server,

Total Memory in kilobytes.

sysCacheKb System Cache The amount of system cache memory, in

kilobytes.

network interface Not applicable The identifier for the network interface being
used for the DB instance.

rdBytesPS Network Read The number of bytes received per second.

Kb/s

wrBytesPS Network Write The number of bytes sent per second.

Kb/s

processList cpuUsedPc Used % The percentage of CPU used by the process.

memUsedPc MEM% The percentage of total memory used by the

process.

name Not applicable The name of the process.

pid Not applicable The identifier of the process. This value is not
present for processes that are owned by Amazon
RDS.

ppid Not applicable The process identifier for the parent of this
process. This value is only present for child
processes.

tid Not applicable The thread identifier. This value is only present for
threads. The owning process can be identified by
using the pid value.

workingSetKb Not applicable 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.

Not applicable
workingSetPrivKb The amount of memory that is in use by a process,
but can't be shared with other processes, in
kilobytes.

Not applicable
workingSetShareableKb The amount of memory that is in use by a process
and can be shared with other processes, in
kilobytes.

491
 Amazon Relational Database Service User Guide
Viewing Enhanced Monitoring by using CloudWatch Logs

Group Metric Console name Description

virtKb Not applicable The amount of virtual address space the process
is using, in kilobytes. Use of virtual address space
doesn't necessarily imply corresponding use of
either disk or main memory pages.

system handles Handles The number of handles that the system is using.

processes Processes The number of processes running on the system.

threads Threads The number of threads running on the system.

492
 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. 494)
• Subscribing to Amazon RDS event notification (p. 500)
• Listing Amazon RDS event notification subscriptions (p. 502)
• Modifying an Amazon RDS event notification subscription (p. 503)
• Adding a source identifier to an Amazon RDS event notification subscription (p. 505)
• Removing a source identifier from an Amazon RDS event notification subscription (p. 506)
• Listing the Amazon RDS event notification categories (p. 507)
• Deleting an Amazon RDS event notification subscription (p. 508)

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 are 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 are
notified when the DB security group is changed. You also receive notification when an event notification
subscription changes.

Event notifications are sent to the addresses that you provide when you create the subscription. You
might 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 choosing No for Enabled in the
Amazon RDS console or by setting the Enabled parameter to false using the AWS CLI or Amazon RDS
API.
Important
Amazon RDS doesn't guarantee the order of events sent in an event stream. The event order is
subject to change.
Note
For more information on using text messages with SNS, see Mobile text messaging (SMS) in the
Amazon Simple Notification Service Developer Guide.

Amazon RDS uses the ARN of an Amazon SNS topic to identify each subscription. The Amazon RDS
console creates the ARN for you when you create the subscription. If you use the CLI or API, you 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 then begin to receive event notifications.

493
 Amazon Relational Database Service User Guide
Amazon RDS event categories and event messages

Note
When Amazon SNS sends a notification to a subscribed HTTP or HTTPS endpoint, the POST
message sent to the endpoint has a message body that contains a JSON document. For more
information, see Amazon SNS message and JSON formats in the Amazon Simple Notification
Service Developer Guide.
You can use AWS Lambda to process event notifications from a DB instance. For more
information, see Using AWS Lambda with Amazon RDS in the AWS Lambda Developer Guide.

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 one of
the following:

• DB instance
• DB security group
• DB parameter group

The following table shows the event category and a list of events when a DB instance is the source type.

Category Amazon RDS event ID Description

availability RDS-EVENT-0006 The DB instance restarted.

availability RDS-EVENT-0004 DB instance shutdown.

availability RDS-EVENT-0022 An error has occurred while restarting MySQL or

MariaDB.

backup RDS-EVENT-0001 Backing up DB instance.

backup RDS-EVENT-0002 Finished DB Instance backup.

configuration RDS-EVENT-0009 The DB instance has been added to a security group.

change

configuration RDS-EVENT-0024 The DB instance is being converted to a Multi-AZ DB

change instance.

configuration RDS-EVENT-0030 The DB instance is being converted to a Single-AZ DB

change instance.

configuration RDS-EVENT-0012 Applying modification to database instance class.

change

configuration RDS-EVENT-0018 The current storage settings for this DB instance are
change being changed.

configuration RDS-EVENT-0011 A parameter group for this DB instance has changed.

change

configuration RDS-EVENT-0092 A parameter group for this DB instance has finished

change updating.

494
 Amazon Relational Database Service User Guide
Amazon RDS event categories and event messages

Category Amazon RDS event ID Description

configuration RDS-EVENT-0028 Automatic backups for this DB instance have been

change disabled.

configuration RDS-EVENT-0032 Automatic backups for this DB instance have been

change enabled.

configuration RDS-EVENT-0033 There are [count] users that match the master user
change name. Users not tied to a specific host have been
reset.

configuration RDS-EVENT-0025 The DB instance has been converted to a Multi-AZ DB

change instance.

configuration RDS-EVENT-0029 The DB instance has been converted to a Single-AZ

change DB instance.

configuration RDS-EVENT-0014 The DB instance class for this DB instance has

change changed.

configuration RDS-EVENT-0017 The storage settings for this DB instance have

change changed.

configuration RDS-EVENT-0010 The DB instance has been removed from a security

change group.

configuration RDS-EVENT-0016 The master password for the DB instance has been
change reset.

configuration RDS-EVENT-0067 An attempt to reset the master password for the DB

change instance has failed.

configuration RDS-EVENT-0078 The Enhanced Monitoring configuration has been

change changed.

creation RDS-EVENT-0005 DB instance created.

deletion RDS-EVENT-0003 The DB instance has been 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.

495
 Amazon Relational Database Service User Guide
Amazon RDS event categories and event messages

Category Amazon RDS event ID Description

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.

failure RDS-EVENT-0035 The DB instance has invalid parameters. For example,

if the DB instance could not start because a memory-
related parameter is set too high for this instance
class, 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. 478).

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. 478).

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. 679).

failure RDS-EVENT-0188 Amazon RDS was unable to upgrade a MySQL DB

instance from version 5.7 to version 8.0 because of
incompatibilities related to the data dictionary. The
DB instance was rolled back to MySQL version 5.7.
For more information, see Rollback after failure to
upgrade from MySQL 5.7 to 8.0 (p. 861).

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. 555).

low storage RDS-EVENT-0007 The allocated storage for the DB instance has been
consumed. To resolve this issue, 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. 555).

496
 Amazon Relational Database Service User Guide
Amazon RDS event categories and event messages

Category Amazon RDS event ID Description

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.

maintenance RDS-EVENT-0047 Patching of the DB instance has completed.

maintenance RDS-EVENT-0155 The DB instance has a DB engine minor version

upgrade available.

notification RDS-EVENT-0044 Operator-issued notification. For more information,

see the event message.

notification RDS-EVENT-0048 Patching of the DB instance has been delayed.

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. 134).

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. 134).

notification RDS-EVENT-0064 The TDE key has been rotated. For information about
recommended best practices, see Amazon RDS basic
operational guidelines (p. 134).

notification RDS-EVENT-0084 You attempted to convert a DB instance to Multi-

AZ, 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. 705).

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.

497
 Amazon Relational Database Service User Guide
Amazon RDS event categories and event messages

Category Amazon RDS event ID Description

notification RDS-EVENT-0157 RDS can't modify the DB instance class because

the target instance class can't support the number
of databases that exist on the source DB instance.
The error message appears as: "The instance has N
databases, but after conversion it would only support
N".

For more information, see Limits for Microsoft SQL

Server DB instances (p. 639).

notification RDS-EVENT-0158 DB instance is in a state that can't be upgraded.

read replica RDS-EVENT-0045 An error has occurred in the read replication process.
For more information, see the event message.

In addition, see the troubleshooting section for read

replicas for your DB engine.

• Troubleshooting a MariaDB read replica

problem (p. 619)
• Troubleshooting a SQL Server read replica
problem (p. 704)
• Troubleshooting a MySQL read replica
problem (p. 912)
• Troubleshooting Oracle replicas (p. 1127)
• Troubleshooting a PostgreSQL read replica
problem (p. 1482)

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.

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.

498
 Amazon Relational Database Service User Guide
Amazon RDS event categories and event messages

Category Amazon RDS event ID Description

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.
(<dbname>: <recovery model found>[,...])"

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-in-

time backup.

The following table shows the event category and a list of events when a DB parameter group is the
source type.

Category RDS event ID Description

configuration RDS-EVENT-0037 The parameter group was modified.

change

The following table shows the event category and a list of events when a DB security group is the source
type.

Category RDS event ID Description

configuration RDS-EVENT-0038 The security group has been modified.

change

failure RDS-EVENT-0039 The 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.

Category RDS event ID Description

creation RDS-EVENT-0040 A manual DB snapshot is being created.

creation RDS-EVENT-0042 A manual DB snapshot has been created.

creation RDS-EVENT-0090 An automated DB snapshot is being created.

creation RDS-EVENT-0091 An automated DB snapshot has been created.

deletion RDS-EVENT-0041 A DB snapshot has been deleted.

notification RDS-EVENT-0059 Started copy of snapshot [DB snapshot name] from

region [region name].

499
 Amazon Relational Database Service User Guide
Subscribing to Amazon RDS event notification

Category RDS event ID Description

notification RDS-EVENT-0060 Finished copy of snapshot [DB snapshot name] from

region [region name] in [time] minutes.

notification RDS-EVENT-0061 Canceled snapshot copy request of [DB snapshot

name] from region %[region name].

notification RDS-EVENT-0159 DB snapshot export task failed.

notification RDS-EVENT-0160 DB snapshot export task canceled.

notification RDS-EVENT-0161 DB snapshot export task completed.

restoration RDS-EVENT-0043 A DB instance is being restored from a DB snapshot.

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 operations.
For information on creating an SNS topic and subscribing to it, see Getting started with Amazon SNS in
the Amazon Simple Notification Service Developer Guide.

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 receive all the DB
instance events for the specified source. If you specify a SourceType but don't specify a SourceIdentifier,
you receive notice of the events for that source type for all your Amazon RDS sources. If you don't specify
either the SourceType or the SourceIdentifier, you are 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.
Amazon RDS event notification is only available for unencrypted SNS topics. If you specify an
encrypted SNS topic, event notifications aren't sent for the topic.

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. For Name, enter a name for the event notification subscription.

b. For Send notifications to, choose an existing Amazon SNS 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.

500
 Amazon Relational Database Service User Guide
Subscribing to Amazon RDS event notification

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.

AWS 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, macOS, 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
To subscribe to Amazon RDS event notification, call the Amazon RDS API function
CreateEventSubscription. Include the following required parameters:

• SubscriptionName
• SnsTopicArn

501
 Amazon Relational Database Service User Guide
Listing Amazon RDS event notification subscriptions

Listing Amazon RDS event notification subscriptions

You can list your current Amazon RDS event notification subscriptions.

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.

AWS CLI
To list your current Amazon RDS event notification subscriptions, use the AWS CLI describe-event-
subscriptions 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.

502
 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.

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 section.
5. Choose Edit. The Amazon RDS console indicates that the subscription is being modified.

AWS CLI
To modify an Amazon RDS event notification subscription, use the AWS CLI modify-event-
subscription command. Include the following required parameter:

• --subscription-name

Example

The following code enables myeventsubscription.

For Linux, macOS, 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 operation ModifyEventSubscription.
Include the following required parameter:

503
 Amazon Relational Database Service User Guide
Modifying an Amazon RDS event notification subscription

• SubscriptionName

504
 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.

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. 503).

AWS CLI
To add a source identifier to an Amazon RDS event notification subscription, use the AWS CLI add-
source-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, macOS, 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

505
 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.

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. 503).

AWS 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, macOS, 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

506
 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.

Console
When you create or modify an event notification subscription, the event categories are displayed in
the Amazon RDS console. For more information, see Modifying an Amazon RDS event notification
subscription (p. 503).

AWS 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.

507
 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.

Console
To delete 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 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.

AWS CLI
To delete an Amazon RDS event notification subscription, use the AWS CLI delete-event-
subscription command. Include the following required parameter:

• --subscription-name

Example

The following example deletes the subscription myrdssubscription.

aws rds 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

508
 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 describe-
events AWS CLI command, or the DescribeEvents RDS API operation. If you use the AWS CLI or the RDS
API to view events, you can retrieve events for up to the past 14 days.
Note
If you need to store events for longer periods of time, you can send Amazon RDS events
to CloudWatch Events. For more information, see Getting CloudWatch Events and Amazon
EventBridge events for Amazon RDS (p. 558)

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
characters stopped.

AWS CLI
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
You can view all Amazon RDS instance events for the past 14 days by calling the DescribeEvents RDS API
operation and setting the Duration parameter to 20160.

509
 Amazon Relational Database Service User Guide
Accessing database logs

Accessing Amazon RDS database log files

You can view, download, and watch database logs using the AWS Management Console, the AWS
Command Line Interface (AWS CLI), or the Amazon RDS API. Viewing, downloading, or watching
transaction logs isn't supported.

For engine-specific information, see the following:

• MariaDB database log files (p. 514)

• Microsoft SQL Server database log files (p. 522)
• MySQL database log files (p. 525)
• Oracle database log files (p. 533)
• PostgreSQL database log files (p. 540)

Viewing and listing database log files

You can view database log files for your DB engine by using the AWS Management 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.

Console
To view a database log file

1. Open the Amazon RDS console at https://console.aws.amazon.com/rds/.

2. In the navigation pane, choose Databases.
3. Choose the name of the DB instance that has the log file that you want to view.
4. Choose the Logs & events tab.
5. Scroll down to the Logs section.
6. In the Logs section, choose the log that you want 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

RDS 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 AWS Management Console, AWS CLI or API to download a database log file.

510
 Amazon Relational Database Service User Guide
Downloading a database log file

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 Databases.
3. Choose the name of the DB instance that has the log file that you want to view.
4. Choose the Logs & events tab.
5. Scroll down to the Logs section.
6. In the Logs section, choose the button next to the log that you want to download, and then choose
Download.
7. Open the context (right-click) menu for the link provided, and then choose Save Link As. Enter 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 downloads 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, macOS, 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.

511
 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 AWS Management Console.

Console
To watch a database log file

1. Open the Amazon RDS console at https://console.aws.amazon.com/rds/.

2. In the navigation pane, choose Databases.
3. Choose the name of the DB instance that has the log file that you want to view.
4. Choose the Logs & events tab.
5. In the Logs section, 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. With CloudWatch Logs, you can 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 Amazon CloudWatch Logs” (p. 515)
• the section called “Publishing MySQL logs to Amazon CloudWatch Logs” (p. 527)
• the section called “Publishing Oracle logs to Amazon CloudWatch Logs” (p. 535)
• the section called “Publishing PostgreSQL logs to Amazon CloudWatch Logs” (p. 543)
• the section called “Publishing SQL Server logs to Amazon CloudWatch Logs” (p. 522)

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.

512
 Amazon Relational Database Service User Guide
Reading log file contents using REST

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

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)

513
 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 Accessing
Amazon RDS database log files (p. 510).

Accessing MariaDB error logs

The MariaDB error log is written to the <host-name>.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 <host-name>.err file is flushed every 5 minutes, and its contents are appended to mysql-error-
running.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. 234). 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 run 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 run 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
run 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.

514
 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 Amazon CloudWatch Logs

You can configure your 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.

515
 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.

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 Databases, and then choose the DB instance that you want to
modify.
3. Choose Modify.
4. 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

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

Note
A change to the --cloudwatch-logs-export-configuration option is always applied
to the DB instance immediately. Therefore, the --apply-immediately and --no-apply-
immediately options have no effect.

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

516
 Amazon Relational Database Service User Guide
MariaDB database log files

• --enable-cloudwatch-logs-exports
• --db-instance-class
• --engine

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, macOS, or Unix:

aws rds modify-db-instance \

--db-instance-identifier mydbinstance \
--cloudwatch-logs-export-configuration '{"EnableLogTypes":
["audit","error","general","slowquery"]}'

For Windows:

aws rds modify-db-instance ^

--db-instance-identifier mydbinstance ^
--cloudwatch-logs-export-configuration '{"EnableLogTypes":
["audit","error","general","slowquery"]}'

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, macOS, 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 operation with the
following parameters:

517
 Amazon Relational Database Service User Guide
MariaDB database log files

• DBInstanceIdentifier
• CloudwatchLogsExportConfiguration

Note
A change to the CloudwatchLogsExportConfiguration parameter is always applied to the
DB instance immediately. Therefore, the ApplyImmediately parameter has no effect.

You can also publish MariaDB logs by calling the following RDS API operations:

• CreateDBInstance
• RestoreDBInstanceFromDBSnapshot
• RestoreDBInstanceFromS3
• RestoreDBInstanceToPointInTime

Run one of these RDS API operations 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;

518
 Amazon Relational Database Service User Guide
MariaDB database log files

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.

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 that is used by the DB instance that 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. 234).
4. For 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.

519
 Amazon Relational Database Service User Guide
MariaDB database log files

For more information about mysqlbinlog options, go to mysqlbinlog options in the MariaDB
documentation.

The following is an example:

For Linux, macOS, or Unix:

mysqlbinlog \
--read-from-remote-server \
--host=mariadbinstance1.1234abcd.region.rds.amazonaws.com \
--port=3306 \
--user ReplUser \
--password <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 <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;

520
 Amazon Relational Database Service User Guide
MariaDB database log files

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:

BEGIN
/*!*/;
# at 1163
# at 1209
#150922 7:55:57 server id 1855786460 end_log_pos 1209 Table_map: `test`.`square`
mapped to number 76
#150922 7:55:57 server id 1855786460 end_log_pos 1247 Write_rows: table id 76
flags: STMT_END_F
### INSERT INTO `test`.`square`
### SET
### @1=5
### @2=25
# at 1247
#150922 7:56:01 server id 1855786460 end_log_pos 1274 Xid = 62
COMMIT/*!*/;

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 end_log_pos 483 Annotate_rows:
#Q> INSERT INTO square(x, y) VALUES(5, 5 * 5)
#150922 8:04:24 server id 1855786460 end_log_pos 529 Table_map: `test`.`square` mapped
to number 76
#150922 8:04:24 server id 1855786460 end_log_pos 567 Write_rows: table id 76 flags:
STMT_END_F
### INSERT INTO `test`.`square`
### SET
### @1=5
### @2=25
# at 567
#150922 8:04:26 server id 1855786460 end_log_pos 594 Xid = 88
COMMIT/*!*/;

521
 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, AWS CLI, or RDS API. For more information about viewing, downloading, and
watching file-based database logs, see Accessing Amazon RDS database log files (p. 510).

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 might delete error
logs older than 7 days.

Agent logs A maximum of 10 agent logs are retained. Amazon RDS might 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. 828).

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. 828).

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 Viewing error and agent logs (p. 828).

Publishing SQL Server logs to Amazon CloudWatch Logs

With Amazon RDS for SQL Server, you can publish error and agent log events directly to Amazon
CloudWatch Logs. Analyze the log data with CloudWatch Logs, then use CloudWatch to create alarms
and view metrics.

With CloudWatch Logs, you can do the following:

• Store logs in highly durable storage space with a retention period that you define.
• Search and filter log data.
• Share log data between accounts.
• Export logs to Amazon S3.
• Stream data to Amazon Elasticsearch Service.
• Process log data in real time with Amazon Kinesis Data Streams.

Amazon RDS publishes each SQL Server database log as a separate database stream in the log group.
For example, if you publish error logs, error data is stored in an error log stream in the /aws/rds/
instance/my_instance/error log group.

522
 Amazon Relational Database Service User Guide
Microsoft SQL Server database log files

Note
Publishing SQL Server logs to CloudWatch Logs isn't enabled by default. Publishing trace and
dump files isn't supported. Publishing SQL Server logs to CloudWatch Logs is supported in all
regions, except for Asia Pacific (Hong Kong).

Console

To publish SQL Server DB logs to CloudWatch Logs from the AWS Management Console

1. Open the Amazon RDS console at https://console.aws.amazon.com/rds/.

2. In the navigation pane, choose Databases, and then choose the DB instance that you want to
modify.
3. Choose Modify.
4. In the Log exports section, choose the logs that you want to start publishing to CloudWatch Logs.

You can choose Agent log, Error log, or both.

5. Choose Continue, and then choose Modify DB Instance on the summary page.

AWS CLI

To publish SQL Server logs, you can use the modify-db-instance command with the following
parameters:

• --db-instance-identifier
• --cloudwatch-logs-export-configuration

Note
A change to the --cloudwatch-logs-export-configuration option is always applied
to the DB instance immediately. Therefore, the --apply-immediately and --no-apply-
immediately options have no effect.

You can also publish SQL Server logs using the following commands:

• create-db-instance
• restore-db-instance-from-db-snapshot
• restore-db-instance-to-point-in-time

Example

The following example creates an SQL Server DB instance with CloudWatch Logs publishing enabled.
The --enable-cloudwatch-logs-exports value is a JSON array of strings that can include error,
agent, or both.

For Linux, macOS, or Unix:

aws rds create-db-instance \

--db-instance-identifier mydbinstance \
--enable-cloudwatch-logs-exports '["error","agent"]' \
--db-instance-class db.m4.large \
--engine sqlserver-se

For Windows:

aws rds create-db-instance ^

523
 Amazon Relational Database Service User Guide
Microsoft SQL Server database log files

--db-instance-identifier mydbinstance ^
--enable-cloudwatch-logs-exports "[\"error\",\"agent\"]" ^
--db-instance-class db.m4.large ^
--engine sqlserver-se

Note
When using the Windows command prompt, you must escape double quotes (") in JSON code by
prefixing them with a backslash (\).

Example

The following example modifies an existing SQL Server 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 that can include error, agent, or both.

For Linux, macOS, or Unix:

aws rds modify-db-instance \

--db-instance-identifier mydbinstance \
--cloudwatch-logs-export-configuration '{"EnableLogTypes":["error","agent"]}'

For Windows:

aws rds modify-db-instance ^

--db-instance-identifier mydbinstance ^
--cloudwatch-logs-export-configuration "{\"EnableLogTypes\":[\"error\",\"agent\"]}"

Note
When using the Windows command prompt, you must escape double quotes (") in JSON code by
prefixing them with a backslash (\).

Example

The following example modifies an existing SQL Server DB instance to disable publishing agent 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 that can include error,
agent, or both.

For Linux, macOS, or Unix:

aws rds modify-db-instance \

--db-instance-identifier mydbinstance \
--cloudwatch-logs-export-configuration '{"DisableLogTypes":["agent"]}'

For Windows:

aws rds modify-db-instance ^

--db-instance-identifier mydbinstance ^
--cloudwatch-logs-export-configuration "{\"DisableLogTypes\":[\"agent\"]}"

Note
When using the Windows command prompt, you must escape double quotes (") in JSON code by
prefixing them with a backslash (\).

524
 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 Accessing
Amazon RDS database log files (p. 510).

Topics
• Accessing MySQL error logs (p. 525)
• Accessing the MySQL slow query and general logs (p. 525)
• Accessing the MySQL audit log (p. 527)
• Publishing MySQL logs to Amazon CloudWatch Logs (p. 527)
• Log file size (p. 529)
• Managing table-based MySQL logs (p. 530)
• Binary logging format (p. 530)
• Accessing MySQL binary logs (p. 531)

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-error-
running.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. 234). 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.

525
 Amazon Relational Database Service User Guide
MySQL database log files

• long_query_time: To prevent fast-running queries from being logged in the slow query log, specify
a value for the shortest query run 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 run 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 run 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.
• 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. 493).

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

526
 Amazon Relational Database Service User Guide
MySQL database log files

Accessing the MySQL audit log

To access the audit log, the DB instance must use a custom option group with the
MARIADB_AUDIT_PLUGIN option. For more information, see MariaDB Audit Plugin support (p. 930).

Publishing MySQL logs to Amazon CloudWatch Logs

You can configure your 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.

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.

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 Databases, and then choose the DB instance that you want to
modify.
3. Choose Modify.
4. 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
You can publish MySQL logs with the AWS CLI. You can call the modify-db-instance command with
the following parameters:

527
 Amazon Relational Database Service User Guide
MySQL database log files

• --db-instance-identifier
• --cloudwatch-logs-export-configuration

Note
A change to the --cloudwatch-logs-export-configuration option is always applied
to the DB instance immediately. Therefore, the --apply-immediately and --no-apply-
immediately options have no effect.

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
• --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, macOS, or Unix:

aws rds modify-db-instance \

--db-instance-identifier mydbinstance \
--cloudwatch-logs-export-configuration '{"EnableLogTypes":
["audit","error","general","slowquery"]}'

For Windows:

aws rds modify-db-instance ^

--db-instance-identifier mydbinstance ^
--cloudwatch-logs-export-configuration '{"EnableLogTypes":
["audit","error","general","slowquery"]}'

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, macOS, or Unix:

528
 Amazon Relational Database Service User Guide
MySQL database log files

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:

• DBInstanceIdentifier
• CloudwatchLogsExportConfiguration

Note
A change to the CloudwatchLogsExportConfiguration parameter is always applied to the
DB instance immediately. Therefore, the ApplyImmediately parameter has no effect.

You can also publish MySQL logs by calling the following RDS API operations:

• CreateDBInstance
• RestoreDBInstanceFromDBSnapshot
• RestoreDBInstanceFromS3
• RestoreDBInstanceToPointInTime

Run one of these RDS API operations 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

529
 Amazon Relational Database Service User Guide
MySQL database log files

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. 234). 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;

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. 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.

530
 Amazon Relational Database Service User Guide
MySQL database log files

For more information on parameter groups, see Working with DB parameter groups (p. 234).
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.

Important
Changing a DB parameter group affects all DB instances that use that parameter group. If you
want to specify different binary logging formats for different MySQL DB instances in an AWS
Region, the DB instances must use different DB parameter groups. These parameter groups
identify different logging formats. Assign the appropriate DB parameter group to the each DB
instance.

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:

• 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, macOS, 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:

531
 Amazon Relational Database Service User Guide
MySQL database log files

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.

call mysql.rds_show_configuration;

532
 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 Accessing
Amazon RDS database log files (p. 510).

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 operation that lists the Oracle log files that are available for a
DB instance ignores the MaxRecords parameter and returns up to 1,000 records. The call returns
LastWritten as a POSIX date in milliseconds.

Retention schedule
The Oracle database engine might rotate log files if they get very large. To retain audit or trace files,
download them. If you store the files locally, you reduce your Amazon RDS storage costs and make more
space available for your data.

The following table shows 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 au