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
Amazon EC2 and on-premises databases ............................................................................... 1
Amazon RDS and Amazon EC2 ............................................................................................ 2
Amazon RDS Custom for Oracle ........................................................................................... 3
DB instances .............................................................................................................................. 4
DB engines ........................................................................................................................ 4
DB instance classes ............................................................................................................ 4
DB instance storage ............................................................................................................ 4
Amazon Virtual Private Cloud (Amazon VPC) ......................................................................... 5
AWS Regions and Availability Zones ............................................................................................. 5
Security .................................................................................................................................... 5
Monitoring an Amazon RDS DB instance ....................................................................................... 6
How to work with Amazon RDS ................................................................................................... 6
AWS Management Console .................................................................................................. 6
Command line interface ...................................................................................................... 6
Programming with Amazon RDS .......................................................................................... 6
How you are charged for Amazon RDS ......................................................................................... 6
What's next? .............................................................................................................................. 6
Getting started .................................................................................................................. 7
Topics specific to database engines ...................................................................................... 7
DB instances .............................................................................................................................. 8
DB instance classes ................................................................................................................... 10
DB instance class types ..................................................................................................... 10
Supported DB engines ...................................................................................................... 11
Determining DB instance class support in AWS Regions ......................................................... 25
Changing your DB instance class ........................................................................................ 28
Configuring the processor ................................................................................................. 29
Hardware specifications ..................................................................................................... 41
DB instance storage .................................................................................................................. 48
Storage types .................................................................................................................. 48
General Purpose SSD storage ............................................................................................. 48
Provisioned IOPS storage .................................................................................................. 50
Magnetic storage .............................................................................................................. 51
Monitoring storage performance ........................................................................................ 52
Factors that affect storage performance .............................................................................. 52
Regions, Availability Zones, and Local Zones ................................................................................ 55
AWS Regions ................................................................................................................... 55
Availability Zones ............................................................................................................. 58
Local Zones ..................................................................................................................... 58
Multi-AZ deployments ............................................................................................................... 59
Multi-AZ DB instance deployments ..................................................................................... 60
Multi-AZ DB cluster deployments (preview) ......................................................................... 65
DB instance billing for Amazon RDS ......................................................................................... 101
On-Demand DB instances ................................................................................................ 102
Reserved DB instances .................................................................................................... 103
Setting up ..................................................................................................................................... 112
Sign up for AWS .................................................................................................................... 112
Create an IAM user ................................................................................................................. 112
Determine requirements .......................................................................................................... 114
Provide access to your DB instance ........................................................................................... 115
Getting started ............................................................................................................................... 118
Creating a MariaDB DB instance and connecting to a database ..................................................... 118
Creating a MariaDB DB instance ....................................................................................... 118

iii
 Amazon Relational Database Service User Guide

Connecting to a database on a DB instance running MariaDB ............................................... 122

Deleting a DB instance .................................................................................................... 125
Creating a SQL Server DB instance and connecting to it .............................................................. 126
Creating a sample SQL Server DB instance ........................................................................ 126
Connecting to your sample DB instance ............................................................................ 130
Exploring your sample DB instance ................................................................................... 133
Deleting your sample DB instance .................................................................................... 134
Creating a MySQL DB instance and connecting to a database ....................................................... 135
Creating a MySQL DB instance ......................................................................................... 135
Connecting to a database on a DB instance running MySQL ................................................. 139
Deleting a DB instance .................................................................................................... 142
Creating an Oracle DB instance and connecting to a database ...................................................... 143
Creating a sample Oracle DB instance ............................................................................... 143
Connecting to your sample DB instance ............................................................................ 147
Deleting your sample DB instance .................................................................................... 149
Creating a PostgreSQL DB instance and connecting to a database ................................................. 149
Creating a PostgreSQL DB instance ................................................................................... 150
Connecting to a PostgreSQL DB instance ........................................................................... 153
Deleting a DB instance .................................................................................................... 159
Tutorial: Create a web server and an Amazon RDS DB instance ..................................................... 160
Create a DB instance ....................................................................................................... 161
Create a web server ........................................................................................................ 166
Tutorials and sample code ............................................................................................................... 178
Tutorials in this guide ............................................................................................................. 178
Tutorials in other AWS guides .................................................................................................. 178
Tutorials and sample code in GitHub ......................................................................................... 179
Best practices for Amazon RDS ........................................................................................................ 180
Amazon RDS basic operational guidelines .................................................................................. 180
DB instance RAM recommendations .......................................................................................... 181
Using Enhanced Monitoring to identify operating system issues .................................................... 181
Using metrics to identify performance issues ............................................................................. 181
Viewing performance metrics ........................................................................................... 181
Evaluating performance metrics ....................................................................................... 184
Tuning queries ....................................................................................................................... 185
Best practices for working with MySQL ..................................................................................... 186
Table size ...................................................................................................................... 186
Number of tables ........................................................................................................... 186
Storage engine ............................................................................................................... 187
Best practices for working with MariaDB ................................................................................... 187
Table size ...................................................................................................................... 187
Number of tables ........................................................................................................... 188
Storage engine ............................................................................................................... 188
Best practices for working with Oracle ...................................................................................... 188
Best practices for working with PostgreSQL ............................................................................... 188
Loading data into a PostgreSQL DB instance ...................................................................... 189
Working with the PostgreSQL autovacuum feature ............................................................. 189
Amazon RDS for PostgreSQL best practices video ............................................................... 190
Best practices for working with SQL Server ................................................................................ 190
Amazon RDS for SQL Server best practices video ................................................................ 191
Working with DB parameter groups .......................................................................................... 191
Best practices for automating DB instance creation ..................................................................... 191
Amazon RDS new features and best practices presentation video .................................................. 192
Configuring a DB instance ............................................................................................................... 193
Creating a DB instance ............................................................................................................ 194
Available settings ........................................................................................................... 197
Original console example ................................................................................................ 209
Creating resources with AWS CloudFormation ............................................................................ 214

iv
 Amazon Relational Database Service User Guide

RDS and AWS CloudFormation templates .......................................................................... 214

Learn more about AWS CloudFormation ............................................................................ 214
Connecting to a DB instance .................................................................................................... 215
Finding the connection information .................................................................................. 215
Database authentication options ...................................................................................... 218
Encrypted connections .................................................................................................... 219
Scenarios for accessing a DB instance ................................................................................ 219
Connecting to a DB instance running a specific DB engine ................................................... 219
Managing connections with RDS Proxy .............................................................................. 220
Using RDS Proxy .................................................................................................................... 221
Supported engines and Region availability ......................................................................... 221
Quotas and limitations .................................................................................................... 222
Planning where to use RDS Proxy ..................................................................................... 223
RDS Proxy concepts and terminology ................................................................................ 224
Getting started with RDS Proxy ........................................................................................ 228
Managing an RDS Proxy .................................................................................................. 239
Working with RDS Proxy endpoints ................................................................................... 248
Monitoring RDS Proxy ..................................................................................................... 254
RDS Proxy examples ....................................................................................................... 259
Troubleshooting RDS Proxy .............................................................................................. 261
Using RDS Proxy with AWS CloudFormation ....................................................................... 266
Working with option groups .................................................................................................... 268
Option groups overview .................................................................................................. 268
Creating an option group ................................................................................................ 270
Copying an option group ................................................................................................. 271
Adding an option to an option group ................................................................................ 272
Listing the options and option settings for an option group ................................................. 276
Modifying an option setting ............................................................................................ 277
Removing an option from an option group ........................................................................ 280
Deleting an option group ................................................................................................ 281
Working with parameter groups ............................................................................................... 284
Creating a DB parameter group ........................................................................................ 285
Associating a DB parameter group with a DB instance ......................................................... 287
Modifying parameters in a DB parameter group ................................................................. 288
Resetting parameters in a DB parameter group .................................................................. 290
Copying a DB parameter group ........................................................................................ 292
Listing DB parameter groups ............................................................................................ 294
Viewing parameter values for a DB parameter group .......................................................... 295
Comparing DB parameter groups ...................................................................................... 296
Specifying DB parameters ................................................................................................ 296
Managing a DB instance .................................................................................................................. 301
Stopping a DB instance ........................................................................................................... 302
Benefits ......................................................................................................................... 302
Limitations ..................................................................................................................... 303
Option and parameter group considerations ...................................................................... 303
Public IP address ............................................................................................................ 303
Stopping a DB instance ................................................................................................... 303
Starting a DB instance ............................................................................................................ 305
Modifying a DB instance .......................................................................................................... 306
Apply Immediately setting ............................................................................................... 307
Available settings ........................................................................................................... 307
Maintaining a DB instance ....................................................................................................... 320
Applying updates ........................................................................................................... 322
Maintenance for Multi-AZ deployments ............................................................................. 323
The maintenance window ................................................................................................ 324
Adjusting the maintenance window for a DB instance .......................................................... 325
Working with mandatory operating system updates ............................................................ 326

v
 Amazon Relational Database Service User Guide

Upgrading the engine version .................................................................................................. 331

Manually upgrading the engine version ............................................................................. 331
Automatically upgrading the minor engine version ............................................................. 333
Renaming a DB instance .......................................................................................................... 334
Renaming to replace an existing DB instance ..................................................................... 334
Rebooting a DB instance ......................................................................................................... 336
Working with read replicas ...................................................................................................... 338
Overview ....................................................................................................................... 340
Creating a read replica .................................................................................................... 343
Promoting a read replica ................................................................................................. 345
Monitoring read replication .............................................................................................. 348
Creating a read replica in a different AWS Region ............................................................... 350
Tagging RDS resources ............................................................................................................ 359
Overview ....................................................................................................................... 359
Using tags for access control with IAM .............................................................................. 360
Using tags to produce detailed billing reports .................................................................... 360
Adding, listing, and removing tags .................................................................................... 360
Using the AWS Tag Editor ............................................................................................... 363
Copying tags to DB instance snapshots ............................................................................. 363
Tutorial: Use tags to specify which DB instances to stop ...................................................... 364
Enabling backups ........................................................................................................... 366
Working with ARNs ................................................................................................................. 369
Constructing an ARN ....................................................................................................... 369
Getting an existing ARN .................................................................................................. 372
Working with storage .............................................................................................................. 376
Increasing DB instance storage capacity ............................................................................ 376
Managing capacity automatically with storage autoscaling ................................................... 377
Modifying Provisioned IOPS ............................................................................................. 382
Deleting a DB instance ............................................................................................................ 384
Deletion protection ......................................................................................................... 384
Final snapshots and retained backups ............................................................................... 384
Deleting a DB instance .................................................................................................... 385
Backing up and restoring a DB instance ............................................................................................ 387
Working with backups ............................................................................................................. 388
Backup storage .............................................................................................................. 388
Backup window .............................................................................................................. 389
Backup retention period .................................................................................................. 390
Enabling automated backups ........................................................................................... 390
Retaining automated backups .......................................................................................... 392
Deleting retained automated backups ............................................................................... 393
Disabling automated backups .......................................................................................... 394
Using AWS Backup ......................................................................................................... 396
Unsupported MySQL storage engines ................................................................................ 396
Unsupported MariaDB storage engines .............................................................................. 397
Replicating automated backups to another Region ..................................................................... 398
AWS Region support ....................................................................................................... 398
Enabling cross-Region automated backups ........................................................................ 400
Finding information about replicated backups .................................................................... 402
Point-in-time recovery from a replicated backup ................................................................ 405
Stopping backup replication ............................................................................................ 406
Deleting replicated backups ............................................................................................. 407
Creating a DB snapshot ........................................................................................................... 409
Restoring from a DB snapshot ................................................................................................. 411
Parameter groups ........................................................................................................... 411
Security groups .............................................................................................................. 411
Option groups ................................................................................................................ 412
Microsoft SQL Server ...................................................................................................... 412

vi
 Amazon Relational Database Service User Guide

Oracle Database ............................................................................................................. 412

Restoring from a snapshot ............................................................................................... 412
Copying a snapshot ................................................................................................................ 414
Limitations ..................................................................................................................... 414
Snapshot retention ......................................................................................................... 414
Copying shared snapshots ............................................................................................... 414
Handling encryption ....................................................................................................... 415
Incremental snapshot copying .......................................................................................... 415
Cross-Region copying ...................................................................................................... 416
Option groups ................................................................................................................ 419
Parameter groups ........................................................................................................... 419
Copying a DB snapshot ................................................................................................... 420
Sharing a snapshot ................................................................................................................. 428
Sharing public snapshots ................................................................................................. 429
Sharing encrypted snapshots ........................................................................................... 430
Sharing a snapshot ......................................................................................................... 432
Exporting snapshot data to Amazon S3 ..................................................................................... 437
Limitations ..................................................................................................................... 438
Overview of exporting snapshot data ................................................................................ 438
Setting up access to an S3 bucket .................................................................................... 439
Using a cross-account KMS key ........................................................................................ 441
Exporting a snapshot to an S3 bucket ............................................................................... 442
Monitoring snapshot exports ........................................................................................... 445
Canceling a snapshot export ............................................................................................ 446
Failure messages ............................................................................................................ 447
Troubleshooting PostgreSQL permissions errors ................................................................. 448
File naming convention ................................................................................................... 448
Data conversion ............................................................................................................ 449
Point-in-time recovery ............................................................................................................. 455
Deleting a snapshot ................................................................................................................ 458
Deleting a DB snapshot ................................................................................................... 458
Tutorial: Restore a DB instance from a DB snapshot .................................................................... 460
Prerequisites for restoring a DB instance from a DB snapshot ............................................... 460
Restoring a DB instance from a DB snapshot ...................................................................... 461
Modifying a restored DB instance ..................................................................................... 462
Monitoring a DB instance ................................................................................................................ 465
Overview of monitoring .......................................................................................................... 466
Monitoring plan ............................................................................................................. 466
Performance baseline ...................................................................................................... 466
Performance guidelines ................................................................................................... 466
Monitoring tools ............................................................................................................. 467
Viewing key monitoring information ......................................................................................... 469
Viewing DB instance status .............................................................................................. 470
Viewing Amazon RDS recommendations ............................................................................ 473
Viewing DB instance metrics ............................................................................................ 477
Monitoring RDS with CloudWatch ............................................................................................. 480
Amazon RDS metrics ....................................................................................................... 481
Amazon RDS dimensions ................................................................................................. 484
Viewing metrics and dimensions ....................................................................................... 484
Creating alarms .............................................................................................................. 486
Monitoring with Performance Insights ....................................................................................... 487
Overview of Performance Insights .................................................................................... 487
Enabling and disabling Performance Insights ..................................................................... 490
Enabling the Performance Schema for MariaDB or MySQL ................................................... 493
Performance Insights policies ........................................................................................... 496
Analyzing metrics with the Performance Insights dashboard ................................................ 499
Adding counter metrics to the dashboard .......................................................................... 524

vii
 Amazon Relational Database Service User Guide

Retrieving metrics with the Performance Insights API .......................................................... 534

Metrics published to CloudWatch ..................................................................................... 547
Logging Performance Insights calls using AWS CloudTrail .................................................... 549
Monitoring OS metrics ............................................................................................................ 551
Overview of Enhanced Monitoring .................................................................................... 551
Setting up and enabling Enhanced Monitoring ................................................................... 560
Viewing OS metrics in the RDS console ............................................................................. 563
Viewing OS metrics using CloudWatch Logs ....................................................................... 566
Working with Amazon RDS events ............................................................................................ 567
Overview of events for Amazon RDS ................................................................................. 567
Viewing Amazon RDS events ............................................................................................ 570
Using Amazon RDS event notification ............................................................................... 571
Creating a rule that triggers on an Amazon RDS event ........................................................ 589
Working with database logs ..................................................................................................... 593
Viewing and listing database log files ............................................................................... 593
Downloading a database log file ...................................................................................... 594
Watching a database log file ............................................................................................ 595
Publishing to CloudWatch Logs ........................................................................................ 595
Reading log file contents using REST ................................................................................ 596
MariaDB database log files .............................................................................................. 598
Microsoft SQL Server database log files ............................................................................ 607
MySQL database log files ................................................................................................ 611
Oracle database log files ................................................................................................. 619
PostgreSQL database log files .......................................................................................... 626
Working with AWS CloudTrail and Amazon RDS ......................................................................... 632
CloudTrail integration with Amazon RDS ........................................................................... 632
Amazon RDS log file entries ............................................................................................ 632
Using Database Activity Streams .............................................................................................. 636
Overview ....................................................................................................................... 636
Configuring Oracle unified auditing .................................................................................. 639
Starting a database activity stream ................................................................................... 639
Getting activity stream status .......................................................................................... 641
Stopping a database activity stream ................................................................................. 642
Monitoring activity streams ............................................................................................. 643
Managing access to activity streams .................................................................................. 657
Working with Amazon RDS Custom .................................................................................................. 660
Database customization challenge ............................................................................................ 660
RDS Custom management model and benefits ........................................................................... 661
Shared responsibility model ............................................................................................. 661
Key benefits of RDS Custom ............................................................................................ 662
RDS Custom architecture ......................................................................................................... 663
RDS Custom for Oracle components ................................................................................. 663
RDS Custom workflow ..................................................................................................... 665
RDS Custom requirements and limitations ................................................................................. 666
General requirements ...................................................................................................... 666
DB instance class support ................................................................................................ 667
AWS Region support ....................................................................................................... 667
Network requirements ..................................................................................................... 667
Limitations ..................................................................................................................... 667
Setting up your RDS Custom for Oracle environment .................................................................. 669
Prerequisites for creating an RDS Custom for Oracle instance ............................................... 669
Make sure that you have a symmetric AWS KMS key ........................................................... 669
Download and install the AWS CLI .................................................................................... 670
Configure IAM and your VPC ............................................................................................ 670
Grant required permissions to your IAM user ...................................................................... 677
Working with CEVs for RDS Custom for Oracle ........................................................................... 679
Preparing to create a CEV ................................................................................................ 679

viii
 Amazon Relational Database Service User Guide

Creating a CEV ............................................................................................................... 684

Modifying CEV status ...................................................................................................... 687
Deleting a CEV ............................................................................................................... 688
Creating and connecting to an RDS Custom DB instance .............................................................. 690
Creating an RDS Custom DB instance ................................................................................ 690
RDS Custom service-linked role ........................................................................................ 693
Connecting to your RDS Custom DB instance using SSH ...................................................... 694
Connecting to your RDS Custom DB instance using AWS Systems Manager ............................. 696
Managing an RDS Custom DB instance ...................................................................................... 698
Working with high availability features for RDS Custom for Oracle ........................................ 698
Pausing and resuming RDS Custom automation ................................................................. 698
Working with storage for RDS Custom DB instances ............................................................ 702
Changing the time zone of an RDS Custom for Oracle DB instance ........................................ 703
Support for Transparent Data Encryption .......................................................................... 704
Tagging RDS Custom resources ........................................................................................ 704
Deleting an RDS Custom DB instance ................................................................................ 704
Working with read replicas for RDS Custom for Oracle ................................................................ 706
Network considerations ................................................................................................... 706
Considerations for the tnsnames.ora file ............................................................................ 706
Limitations ..................................................................................................................... 707
Backing up and restoring an RDS Custom DB instance ................................................................. 708
Creating an RDS Custom snapshot .................................................................................... 708
Restoring from an RDS Custom DB snapshot ...................................................................... 709
Point-in-time recovery ..................................................................................................... 710
Deleting an RDS Custom snapshot .................................................................................... 712
Deleting RDS Custom automated backups ......................................................................... 713
Upgrading a DB instance for RDS Custom for Oracle ................................................................... 715
Viewing valid RDS Custom for Oracle upgrade targets ......................................................... 715
Upgrading an RDS Custom DB instance ............................................................................. 716
Viewing pending upgrades ............................................................................................... 717
Upgrade failure .............................................................................................................. 717
Troubleshooting RDS Custom DB issues ..................................................................................... 719
Viewing RDS Custom events ............................................................................................ 719
Subscribing to event notifications ..................................................................................... 719
Troubleshooting CEV creation .......................................................................................... 720
Responding to an unsupported configuration ..................................................................... 720
How Amazon RDS Custom replaces an impaired host .......................................................... 725
Troubleshooting RDS Custom for Oracle upgrade issues ...................................................... 727
Working with RDS on AWS Outposts ................................................................................................. 729
Prerequisites .......................................................................................................................... 729
Support for Amazon RDS features ............................................................................................ 730
Supported DB instance classes ................................................................................................. 733
Customer-owned IP addresses .................................................................................................. 734
Creating DB instances ............................................................................................................. 736
Considerations for restoring DB instances .................................................................................. 742
MariaDB on Amazon RDS ................................................................................................................ 743
Common management tasks .................................................................................................... 743
MariaDB versions .................................................................................................................... 745
MariaDB feature support ......................................................................................................... 746
MariaDB 10.5 support ..................................................................................................... 746
MariaDB 10.4 support ..................................................................................................... 747
MariaDB 10.3 support ..................................................................................................... 747
MariaDB 10.2 support ..................................................................................................... 748
Features not supported ........................................................................................................... 748
Supported storage engines ...................................................................................................... 749
File size limits ........................................................................................................................ 749
MariaDB security .................................................................................................................... 750

ix
 Amazon Relational Database Service User Guide

SSL support ........................................................................................................................... 752

Cache warming ...................................................................................................................... 753
Dumping and loading the buffer pool on demand .............................................................. 753
Database parameters .............................................................................................................. 754
Common DBA tasks ................................................................................................................ 754
Local time zone ...................................................................................................................... 754
Deprecated MariaDB versions ................................................................................................... 756
Connecting to a DB instance running MariaDB ........................................................................... 756
Finding the connection information .................................................................................. 757
Connecting from the MySQL command-line client (unencrypted) .......................................... 759
Connecting from the MySQL command-line client with SSL (encrypted) ................................. 760
Troubleshooting ............................................................................................................. 760
Updating applications for new SSL/TLS certificates ..................................................................... 762
Determining whether a client requires certificate verification in order to connect ..................... 762
Updating your application trust store ................................................................................ 763
Example Java code for establishing SSL connections ........................................................... 764
Upgrading the MariaDB DB engine ........................................................................................... 766
Overview ....................................................................................................................... 766
Major version upgrades ................................................................................................... 767
Upgrading a MariaDB DB instance .................................................................................... 768
Automatic minor version upgrades ................................................................................... 768
Migrating data from a MySQL DB snapshot to a MariaDB DB instance ............................................ 771
Incompatibilities between MariaDB and MySQL .................................................................. 771
Performing the migration ................................................................................................ 771
Working with MariaDB replication ............................................................................................. 774
Working with MariaDB read replicas .................................................................................. 774
Configuring GTID-based replication ................................................................................... 782
Importing data into a MariaDB DB instance ............................................................................... 785
Options for MariaDB ............................................................................................................... 785
MariaDB Audit Plugin support .......................................................................................... 786
Parameters for MariaDB .......................................................................................................... 789
MariaDB on Amazon RDS SQL reference .................................................................................... 794
mysql.rds_replica_status .................................................................................................. 794
mysql.rds_set_external_master_gtid .................................................................................. 795
mysql.rds_kill_query_id .................................................................................................... 797
Microsoft SQL Server on Amazon RDS .............................................................................................. 799
Common management tasks .................................................................................................... 799
Limitations ............................................................................................................................. 801
DB instance class support ........................................................................................................ 803
Security ................................................................................................................................. 805
Compliance programs ............................................................................................................. 805
HIPAA ........................................................................................................................... 806
SSL support ........................................................................................................................... 806
Version support ...................................................................................................................... 807
Version management .............................................................................................................. 807
Database engine patches and versions .............................................................................. 808
Deprecation schedule ...................................................................................................... 808
Feature support ...................................................................................................................... 808
SQL Server 2019 features ................................................................................................ 808
SQL Server 2017 features ................................................................................................ 809
SQL Server 2016 features ................................................................................................ 809
SQL Server 2014 features ................................................................................................ 810
SQL Server 2012 features ................................................................................................ 810
SQL Server 2008 R2 deprecated on Amazon RDS ............................................................... 811
CDC support .......................................................................................................................... 811
Features not supported and features with limited support ........................................................... 811
Multi-AZ deployments ............................................................................................................. 812

x
 Amazon Relational Database Service User Guide

Using TDE ............................................................................................................................. 813

Functions and stored procedures .............................................................................................. 813
Local time zone ...................................................................................................................... 815
Supported time zones ..................................................................................................... 815
Licensing SQL Server on Amazon RDS ....................................................................................... 823
Restoring license-terminated DB instances ......................................................................... 823
SQL Server Developer Edition .......................................................................................... 823
Connecting to a DB instance running SQL Server ........................................................................ 824
Before you connect ......................................................................................................... 824
Finding the DB instance endpoint and port number ............................................................ 824
Connecting to your DB instance with SSMS ........................................................................ 825
Connecting to your DB instance with SQL Workbench/J ...................................................... 827
Security group considerations .......................................................................................... 829
Troubleshooting ............................................................................................................. 829
Updating applications for new SSL/TLS certificates ..................................................................... 831
Determining whether any applications are connecting to your Microsoft SQL Server DB
instance using SSL .......................................................................................................... 831
Determining whether a client requires certificate verification in order to connect ..................... 832
Updating your application trust store ................................................................................ 833
Upgrading the SQL Server DB engine ....................................................................................... 835
Overview ....................................................................................................................... 836
Major version upgrades ................................................................................................... 836
Multi-AZ and in-memory optimization considerations .......................................................... 837
Option group considerations ............................................................................................ 838
Parameter group considerations ....................................................................................... 838
Testing an upgrade ......................................................................................................... 838
Upgrading a SQL server DB instance ................................................................................. 839
Upgrading deprecated DB instances before support ends ..................................................... 839
Importing and exporting SQL Server databases .......................................................................... 840
Limitations and recommendations .................................................................................... 840
Setting up ..................................................................................................................... 841
Using native backup and restore ...................................................................................... 844
Compressing backup files ................................................................................................ 854
Troubleshooting ............................................................................................................. 854
.................................................................................................................................... 855
Importing and exporting SQL Server data using other methods ............................................ 856
Working with SQL Server read replicas ...................................................................................... 865
Configuring read replicas for SQL Server ........................................................................... 865
Read replica limitations with SQL Server ........................................................................... 865
Troubleshooting a SQL Server read replica problem ............................................................ 866
Multi-AZ for RDS for SQL Server .............................................................................................. 867
Adding Multi-AZ to a SQL Server DB instance .................................................................... 868
Limitations, notes, and recommendations .......................................................................... 868
Determining the location of the secondary ........................................................................ 870
Migrating to Always On AGs ............................................................................................ 871
Additional features for SQL Server ........................................................................................... 872
Using SSL with a SQL Server DB instance .......................................................................... 873
Configuring security protocols and ciphers ......................................................................... 876
Using Windows Authentication with a SQL Server DB instance .............................................. 881
Amazon S3 integration .................................................................................................... 891
Using Database Mail ....................................................................................................... 904
Instance store support for tempdb ................................................................................... 915
Using extended events .................................................................................................... 917
Options for SQL Server ........................................................................................................... 920
Listing the available options for SQL Server versions and editions ......................................... 921
Native backup and restore ............................................................................................... 922
Transparent Data Encryption ............................................................................................ 925

xi
 Amazon Relational Database Service User Guide

SQL Server Audit ............................................................................................................ 928

SQL Server Analysis Services ............................................................................................ 933
SQL Server Integration Services ....................................................................................... 944
SQL Server Reporting Services ......................................................................................... 958
Microsoft Distributed Transaction Coordinator .................................................................... 968
Common DBA tasks for SQL Server .......................................................................................... 980
Accessing the tempdb database ....................................................................................... 981
Analyzing database workload with Database Engine Tuning Advisor ...................................... 983
Collations and character sets ........................................................................................... 985
Creating a database user ................................................................................................. 988
Determining a recovery model ......................................................................................... 988
Determining the last failover time .................................................................................... 989
Disabling fast inserts ...................................................................................................... 990
Dropping a SQL Server database ...................................................................................... 990
Renaming a Multi-AZ database ......................................................................................... 990
Resetting the db_owner role password ............................................................................. 991
Restoring license-terminated DB instances ......................................................................... 991
Transitioning a database from OFFLINE to ONLINE ............................................................. 992
Using CDC ..................................................................................................................... 992
Using SQL Server Agent .................................................................................................. 994
Working with SQL Server logs .......................................................................................... 996
Working with trace and dump files ................................................................................... 996
MySQL on Amazon RDS .................................................................................................................. 998
Common management tasks .................................................................................................... 998
MySQL versions .................................................................................................................... 1000
Deprecation of MySQL version 5.6 .................................................................................. 1002
MySQL features not supported by Amazon RDS ........................................................................ 1003
Supported storage engines .................................................................................................... 1003
Storage-full behavior ............................................................................................................ 1004
MySQL security .................................................................................................................... 1004
Password Validation Plugin .................................................................................................... 1006
SSL support ......................................................................................................................... 1006
Using memcached and other options with MySQL ..................................................................... 1008
InnoDB cache warming .......................................................................................................... 1008
Dumping and loading the buffer pool on demand ............................................................. 1009
Local time zone .................................................................................................................... 1009
Known issues and limitations ................................................................................................. 1011
Deprecated MySQL versions ................................................................................................... 1011
Connecting to a DB instance running MySQL ............................................................................ 1012
Finding the connection information ................................................................................ 1013
Connecting from the MySQL command-line client (unencrypted) ........................................ 1015
Connecting from the MySQL command-line client with SSL (encrypted) ............................... 1016
Connecting from MySQL Workbench ............................................................................... 1017
Troubleshooting ............................................................................................................ 1018
Updating applications for new SSL/TLS certificates ................................................................... 1020
Determining whether any applications are connecting to your MySQL DB instance using SSL ... 1021
Determining whether a client requires certificate verification to connect .............................. 1021
Updating your application trust store .............................................................................. 1022
Example Java code for establishing SSL connections ......................................................... 1023
Upgrading the MySQL DB engine ........................................................................................... 1025
Overview ..................................................................................................................... 1025
Major version upgrades ................................................................................................. 1026
Testing an upgrade ....................................................................................................... 1030
Upgrading a MySQL DB instance .................................................................................... 1030
Automatic minor version upgrades .................................................................................. 1031
Upgrading with reduced downtime ................................................................................. 1032
Upgrading a MySQL DB snapshot ........................................................................................... 1035

xii
 Amazon Relational Database Service User Guide

Importing data into a MySQL DB instance ............................................................................... 1037

Overview ..................................................................................................................... 1037
Importing data considerations ........................................................................................ 1038
Restoring a backup into an Amazon RDS MySQL DB instance .............................................. 1043
Importing data from a MySQL or MariaDB DB to a MySQL or MariaDB DB instance ................. 1051
Importing data to an Amazon RDS MySQL or MariaDB DB instance with reduced downtime ..... 1053
Importing data from any source to a MySQL or MariaDB DB instance ................................... 1067
Working with MySQL replication ............................................................................................. 1072
Working with MySQL read replicas .................................................................................. 1072
Using GTID-based replication ......................................................................................... 1083
Replication with a MySQL or MariaDB instance running external to Amazon RDS ................... 1088
Exporting data from a MySQL DB instance ............................................................................... 1095
Prepare an external MySQL database .............................................................................. 1095
Prepare the source MySQL DB instance ........................................................................... 1096
Copy the database ........................................................................................................ 1097
Complete the export ..................................................................................................... 1098
Options for MySQL ............................................................................................................... 1100
MariaDB Audit Plugin .................................................................................................... 1101
memcached .................................................................................................................. 1104
Common DBA tasks for MySQL .............................................................................................. 1108
Ending a session or query .............................................................................................. 1108
Skipping the current replication error .............................................................................. 1108
Working with InnoDB tablespaces to improve crash recovery times ...................................... 1109
Managing the global status history ................................................................................. 1111
Using Kerberos authentication for MySQL ................................................................................ 1113
Setting up Kerberos authentication for MySQL DB instances ............................................... 1114
Managing a DB instance in a domain .............................................................................. 1120
Connecting to MySQL with Kerberos authentication .......................................................... 1121
Restoring a MySQL DB instance and adding it to a domain ................................................. 1122
Kerberos authentication MySQL limitations ...................................................................... 1122
Known issues and limitations ................................................................................................. 1123
Inconsistent InnoDB buffer pool size ............................................................................... 1123
Index merge optimization returns wrong results ............................................................... 1123
Log file size ................................................................................................................. 1124
MySQL parameter exceptions for Amazon RDS DB instances ............................................... 1124
MySQL file size limits in Amazon RDS ............................................................................. 1125
MySQL Keyring Plugin not supported .............................................................................. 1126
MySQL on Amazon RDS SQL reference .................................................................................... 1127
Overview ..................................................................................................................... 1127
SQL reference conventions ............................................................................................. 1128
mysql.rds_set_master_auto_position ................................................................................ 1128
mysql.rds_set_external_master ....................................................................................... 1129
mysql.rds_set_external_master_with_delay ....................................................................... 1131
mysql.rds_set_external_master_with_auto_position ........................................................... 1134
mysql.rds_reset_external_master ..................................................................................... 1136
mysql.rds_import_binlog_ssl_material ............................................................................. 1137
mysql.rds_remove_binlog_ssl_material ............................................................................. 1139
mysql.rds_set_source_delay ............................................................................................ 1139
mysql.rds_start_replication ............................................................................................. 1140
mysql.rds_start_replication_until ..................................................................................... 1140
mysql.rds_start_replication_until_gtid .............................................................................. 1141
mysql.rds_stop_replication ............................................................................................. 1142
mysql.rds_skip_transaction_with_gtid .............................................................................. 1143
mysql.rds_skip_repl_error ............................................................................................... 1144
mysql.rds_next_master_log ............................................................................................ 1145
mysql.rds_innodb_buffer_pool_dump_now ....................................................................... 1146
mysql.rds_innodb_buffer_pool_load_now ......................................................................... 1147

xiii
 Amazon Relational Database Service User Guide

mysql.rds_innodb_buffer_pool_load_abort ....................................................................... 1147

mysql.rds_set_configuration ........................................................................................... 1147
mysql.rds_show_configuration ........................................................................................ 1149
mysql.rds_kill ............................................................................................................... 1150
mysql.rds_kill_query ...................................................................................................... 1150
mysql.rds_rotate_general_log ......................................................................................... 1151
mysql.rds_rotate_slow_log ............................................................................................. 1151
mysql.rds_enable_gsh_collector ...................................................................................... 1151
mysql.rds_set_gsh_collector ........................................................................................... 1152
mysql.rds_disable_gsh_collector ...................................................................................... 1152
mysql.rds_collect_global_status_history ........................................................................... 1152
mysql.rds_enable_gsh_rotation ....................................................................................... 1152
mysql.rds_set_gsh_rotation ............................................................................................ 1153
mysql.rds_disable_gsh_rotation ...................................................................................... 1153
mysql.rds_rotate_global_status_history ............................................................................ 1153
Oracle on Amazon RDS ................................................................................................................. 1154
Oracle overview .................................................................................................................... 1155
Oracle features ............................................................................................................. 1155
Oracle versions ............................................................................................................. 1157
Oracle licensing ............................................................................................................ 1167
Oracle instance classes .................................................................................................. 1170
Oracle architecture ....................................................................................................... 1173
Oracle parameters ........................................................................................................ 1174
Oracle character sets ..................................................................................................... 1174
Oracle limitations ......................................................................................................... 1177
Connecting to an Oracle instance ........................................................................................... 1180
Finding the endpoint ..................................................................................................... 1180
SQL developer .............................................................................................................. 1182
SQL*Plus ...................................................................................................................... 1184
Security group considerations ......................................................................................... 1185
Dedicated and shared server processes ............................................................................ 1185
Troubleshooting ............................................................................................................ 1185
Modifying Oracle sqlnet.ora parameters .......................................................................... 1186
Securing Oracle connections .................................................................................................. 1189
Encrypting with SSL ...................................................................................................... 1189
Using new SSL/TLS certificates ...................................................................................... 1190
Configuring Kerberos authentication ............................................................................... 1193
Configuring outbound network access ............................................................................. 1204
Administering your Oracle DB ................................................................................................ 1207
System tasks ................................................................................................................ 1215
Database tasks ............................................................................................................. 1228
Log tasks ..................................................................................................................... 1241
RMAN tasks ................................................................................................................. 1249
Oracle Scheduler tasks .................................................................................................. 1265
Diagnostic tasks ............................................................................................................ 1270
Other tasks .................................................................................................................. 1277
Importing data into Oracle .................................................................................................... 1287
Importing using Oracle SQL Developer ............................................................................ 1287
Importing using Oracle Data Pump ................................................................................. 1288
Oracle Export/Import utilities ......................................................................................... 1297
Oracle SQL*Loader ........................................................................................................ 1297
Oracle materialized views .............................................................................................. 1298
Working with Oracle replicas .................................................................................................. 1300
Overview of Oracle replicas ........................................................................................... 1300
Replica requirements for Oracle ...................................................................................... 1301
Preparing to create an Oracle replica .............................................................................. 1303
Creating an Oracle replica in mounted mode .................................................................... 1304

xiv
 Amazon Relational Database Service User Guide

Modifying the Oracle replica mode ................................................................................. 1305

Troubleshooting Oracle replicas ...................................................................................... 1306
Options for Oracle ................................................................................................................ 1307
Overview of Oracle DB options ...................................................................................... 1307
Amazon S3 integration .................................................................................................. 1309
Application Express (APEX) ............................................................................................. 1322
Enterprise Manager ....................................................................................................... 1332
Java virtual machine (JVM) ............................................................................................ 1347
Label security ............................................................................................................... 1350
Locator ........................................................................................................................ 1353
Multimedia ................................................................................................................... 1356
Native network encryption (NNE) .................................................................................... 1359
OLAP .......................................................................................................................... 1365
Secure Sockets Layer (SSL) ............................................................................................. 1367
Spatial ......................................................................................................................... 1374
SQLT ........................................................................................................................... 1377
Statspack ..................................................................................................................... 1382
Time zone .................................................................................................................... 1385
Time zone file autoupgrade ........................................................................................... 1388
Transparent Data Encryption (TDE) ................................................................................. 1392
UTL_MAIL .................................................................................................................... 1395
XML DB ....................................................................................................................... 1397
Upgrading the Oracle DB engine ............................................................................................ 1398
Overview of Oracle upgrades ......................................................................................... 1398
Major version upgrades ................................................................................................. 1400
Minor version upgrades ................................................................................................. 1401
SE2 upgrade paths ........................................................................................................ 1401
Upgrade considerations ................................................................................................. 1402
Testing an upgrade ....................................................................................................... 1403
Upgrading an Oracle DB instance ................................................................................... 1404
Upgrading an Oracle DB snapshot .......................................................................................... 1405
Console ....................................................................................................................... 1405
AWS CLI ...................................................................................................................... 1406
RDS API ....................................................................................................................... 1406
Tools and third-party software for Oracle ................................................................................ 1407
Setting up ................................................................................................................... 1407
Using Oracle GoldenGate ............................................................................................... 1413
Using the Oracle Repository Creation Utility .................................................................... 1425
Installing a Siebel database on Oracle on Amazon RDS ...................................................... 1430
Oracle database engine release notes ...................................................................................... 1433
Oracle Database 19c (19.0.0) and Oracle Database 12c Release 2 (12.2.0.1) .......................... 1433
Oracle versions 12.1.0.2 and 11.2.0.4 .............................................................................. 1434
Database engine: 19.0.0.0 .............................................................................................. 1435
Database engine: 18.0.0.0 .............................................................................................. 1506
Database engine: 12.2.0.1 .............................................................................................. 1538
Database engine: 12.1.0.2 .............................................................................................. 1587
Database engine: 11.2.0.4 .............................................................................................. 1647
PostgreSQL on Amazon RDS .......................................................................................................... 1690
Common management tasks .................................................................................................. 1691
The database preview environment ........................................................................................ 1694
Features not supported in the preview environment .......................................................... 1694
PostgreSQL version 14 RC 1 available ............................................................................. 1694
Creating a new DB instance in the preview environment .................................................... 1694
PostgreSQL limitations .......................................................................................................... 1695
PostgreSQL versions .............................................................................................................. 1696
PostgreSQL 13 versions ................................................................................................. 1696
PostgreSQL 12 versions ................................................................................................. 1698

xv
 Amazon Relational Database Service User Guide

PostgreSQL 11 versions ................................................................................................. 1700

PostgreSQL 10 versions ................................................................................................. 1704
PostgreSQL 9.6 versions ................................................................................................ 1709
PostgreSQL 9.5 versions ................................................................................................ 1715
PostgreSQL extensions .......................................................................................................... 1721
Restricting installation of PostgreSQL extensions .............................................................. 1721
PostgreSQL version 13 extensions supported on Amazon RDS ............................................ 1722
PostgreSQL version 12 extensions supported on Amazon RDS ............................................ 1725
PostgreSQL version 11.x extensions supported on Amazon RDS .......................................... 1728
PostgreSQL version 10.x extensions supported on Amazon RDS .......................................... 1731
PostgreSQL version 9.6.x extensions supported on Amazon RDS ......................................... 1733
PostgreSQL version 9.5.x extensions supported on Amazon RDS ......................................... 1736
PostgreSQL features .............................................................................................................. 1739
Amazon RDS for PostgreSQL log_fdw extension ............................................................... 1739
Upgrading plv8 ............................................................................................................ 1740
Logical replication for PostgreSQL on Amazon RDS ........................................................... 1742
Event triggers for PostgreSQL on Amazon RDS ................................................................. 1744
Huge pages for Amazon RDS for PostgreSQL ................................................................... 1745
Tablespaces for PostgreSQL on Amazon RDS ................................................................... 1745
Autovacuum for PostgreSQL on Amazon RDS .................................................................. 1746
RAM disk for the stats_temp_directory ............................................................................ 1746
ALTER ENUM for PostgreSQL ......................................................................................... 1746
Connecting to a PostgreSQL instance ...................................................................................... 1748
Using pgAdmin to connect to a RDS for PostgreSQL DB instance ........................................ 1750
Using psql to connect to your RDS for PostgreSQL DB instance ........................................... 1752
Troubleshooting connections to your RDS for PostgreSQL instance ...................................... 1752
Security with RDS for PostgreSQL ........................................................................................... 1754
Using SSL with a PostgreSQL DB instance ........................................................................ 1754
Using new SSL/TLS certificates in applications ................................................................. 1757
Using Kerberos authentication ........................................................................................ 1761
Upgrading the PostgreSQL DB engine ..................................................................................... 1774
Overview of upgrading .................................................................................................. 1775
PostgreSQL version numbers .......................................................................................... 1776
Choosing a major version upgrade .................................................................................. 1776
How to perform a major version upgrade ........................................................................ 1778
Automatic minor version upgrades .................................................................................. 1782
Upgrading PostgreSQL extensions .................................................................................. 1783
Upgrading a PostgreSQL DB snapshot engine version ................................................................ 1785
Working with PostgreSQL read replicas ................................................................................... 1787
Read replica configuration with PostgreSQL ..................................................................... 1787
Monitoring PostgreSQL read replicas ............................................................................... 1788
Read replica limitations with PostgreSQL ......................................................................... 1788
Replication interruptions with PostgreSQL read replicas ..................................................... 1788
Troubleshooting a PostgreSQL read replica problem .......................................................... 1789
Importing data into PostgreSQL ............................................................................................. 1791
Importing a PostgreSQL database from an Amazon EC2 instance ........................................ 1792
Using the \copy command to import data to a table on a PostgreSQL DB instance ................. 1794
Importing S3 data into RDS for PostgreSQL ..................................................................... 1795
Transporting PostgreSQL databases between DB instances ................................................. 1806
Exporting PostgreSQL data to Amazon S3 ............................................................................... 1812
Overview of exporting to S3 .......................................................................................... 1812
Verify that your RDS for PostgreSQL version supports exports ............................................ 1813
Specifying the Amazon S3 file path to export to ............................................................... 1813
Setting up access to an Amazon S3 bucket ...................................................................... 1814
Exporting query data using the aws_s3.query_export_to_s3 function ................................... 1817
Troubleshooting access to Amazon S3 ............................................................................. 1819
Function reference ........................................................................................................ 1819

xvi
 Amazon Relational Database Service User Guide

Common DBA tasks for PostgreSQL ........................................................................................ 1823

Creating roles ............................................................................................................... 1823
Managing PostgreSQL database access ............................................................................ 1824
Working with PostgreSQL parameters ............................................................................. 1824
Audit logging for a PostgreSQL DB instance ..................................................................... 1833
Working with the pgaudit extension ................................................................................ 1833
Working with the pg_repack extension ............................................................................ 1835
Using pgBadger for log analysis with PostgreSQL ............................................................. 1836
Viewing the contents of pg_config .................................................................................. 1836
Working with the orafce extension .................................................................................. 1837
Accessing external data with the postgres_fdw extension ................................................... 1837
Accessing external data with the oracle_fdw extension ...................................................... 1838
Restricting password management .................................................................................. 1841
Working with PostgreSQL autovacuum ............................................................................ 1842
Working with the PostGIS extension ................................................................................ 1850
Using a custom DNS server for outbound network access ................................................... 1854
Scheduling maintenance with the pg_cron extension ......................................................... 1856
Managing partitions with the pg_partman extension ......................................................... 1863
Invoking a Lambda function from RDS for PostgreSQL ...................................................... 1867
Security ....................................................................................................................................... 1876
Database authentication ........................................................................................................ 1877
Password authentication ................................................................................................ 1877
IAM database authentication .......................................................................................... 1878
Kerberos authentication ................................................................................................. 1878
Data protection .................................................................................................................... 1878
Data encryption ............................................................................................................ 1879
Internetwork traffic privacy ............................................................................................ 1892
Identity and access management ............................................................................................ 1893
Audience ...................................................................................................................... 1893
Authenticating with identities ......................................................................................... 1893
Managing access using policies ....................................................................................... 1895
How Amazon RDS works with IAM .................................................................................. 1896
Identity-based policy examples ....................................................................................... 1899
IAM database authentication for MySQL and PostgreSQL ................................................... 1909
Troubleshooting ............................................................................................................ 1938
Logging and monitoring ........................................................................................................ 1940
Compliance validation ........................................................................................................... 1942
Resilience ............................................................................................................................. 1943
Backup and restore ....................................................................................................... 1943
Replication ................................................................................................................... 1943
Failover ....................................................................................................................... 1943
Infrastructure security ........................................................................................................... 1944
Security groups ............................................................................................................ 1944
Public accessibility ........................................................................................................ 1944
VPC endpoints (AWS PrivateLink) ............................................................................................ 1945
Considerations .............................................................................................................. 1945
Availability ................................................................................................................... 1945
Creating an interface VPC endpoint ................................................................................ 1946
Creating a VPC endpoint policy ...................................................................................... 1946
Security best practices ........................................................................................................... 1947
Controlling access with security groups ................................................................................... 1948
VPC security groups ...................................................................................................... 1948
DB security groups ........................................................................................................ 1948
DB security groups vs. VPC security groups ...................................................................... 1949
Security group scenario ................................................................................................. 1949
Creating a VPC security group ........................................................................................ 1950
Associating with a DB instance ....................................................................................... 1950

xvii
 Amazon Relational Database Service User Guide

Deleting DB VPC security groups .................................................................................... 1950

DB security groups on EC2-Classic .................................................................................. 1953
Master user account privileges ................................................................................................ 1961
Service-linked roles ............................................................................................................... 1963
Service-linked role permissions for Amazon RDS ............................................................... 1963
Service-linked role permissions for Amazon RDS Custom ................................................... 1966
Using Amazon RDS with Amazon VPC ..................................................................................... 1975
Working with a DB instance in a VPC .............................................................................. 1975
Updating the VPC for a DB instance ................................................................................ 1982
Scenarios for accessing a DB instance in a VPC ................................................................. 1982
Tutorial: Create an Amazon VPC for use with a DB instance ................................................ 1988
Working with a DB instance not in a VPC ......................................................................... 1994
Quotas and constraints .................................................................................................................. 2000
Quotas in Amazon RDS ......................................................................................................... 2000
Naming constraints in Amazon RDS ........................................................................................ 2002
Maximum number of database connections ............................................................................. 2002
File size limits in Amazon RDS ................................................................................................ 2003
Troubleshooting ............................................................................................................................ 2005
Can't connect to DB instance ................................................................................................. 2005
Testing the DB instance connection ................................................................................. 2006
Troubleshooting connection authentication ...................................................................... 2007
Security issues ...................................................................................................................... 2007
Error message "failed to retrieve account attributes, certain console functions may be
impaired." .................................................................................................................... 2007
Resetting the DB instance owner password .............................................................................. 2007
DB instance outage or reboot ................................................................................................. 2008
Parameter changes not taking effect ....................................................................................... 2008
DB instance out of storage .................................................................................................... 2009
Insufficient DB instance capacity ............................................................................................. 2010
MySQL and MariaDB issues .................................................................................................... 2010
Maximum MySQL and MariaDB connections ..................................................................... 2011
Diagnosing and resolving incompatible parameters status for a memory limit ....................... 2011
Diagnosing and resolving lag between read replicas .......................................................... 2012
Diagnosing and resolving a MySQL or MariaDB read replication failure ................................. 2014
Creating triggers with binary logging enabled requires SUPER privilege ............................... 2015
Diagnosing and resolving point-in-time restore failures ..................................................... 2016
Replication stopped error .............................................................................................. 2017
Read replica create fails or replication breaks with fatal error 1236 ..................................... 2017
Can't set backup retention period to 0 .................................................................................... 2017
Amazon RDS API reference ............................................................................................................ 2018
Using the Query API ............................................................................................................. 2018
Query parameters ......................................................................................................... 2018
Query request authentication ......................................................................................... 2018
Troubleshooting applications .................................................................................................. 2019
Retrieving errors ........................................................................................................... 2019
Troubleshooting tips ..................................................................................................... 2019
Document history ......................................................................................................................... 2020
Earlier updates ..................................................................................................................... 2064
AWS glossary ............................................................................................................................... 2084

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

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.

Overview of Amazon RDS

Why do you want to run a relational database in the AWS Cloud? Because AWS takes over many of the
difficult and tedious management tasks of a relational database.

Topics
• Amazon EC2 and on-premises databases (p. 1)
• Amazon RDS and Amazon EC2 (p. 2)
• Amazon RDS Custom for Oracle (p. 3)

Amazon EC2 and on-premises databases

Amazon Elastic Compute Cloud (Amazon EC2) provides scalable computing capacity in the AWS Cloud.
Amazon EC2 eliminates your need to invest in hardware up front, so you can develop and deploy
applications faster.

When you buy an on-premises server, you get CPU, memory, storage, and IOPS, all bundled together.
With Amazon EC2, 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.

For a relational database in an on-premises server, you assume full responsibility for the server,
operating system, and software. For a database on an Amazon EC2 instance, AWS manages the layers
below the operating system. In this way, Amazon EC2 eliminates some of the burden of managing an on-
premises database server.

In the following table, you can find a comparison of the management models for on-premises databases
and Amazon EC2.

1
 Amazon Relational Database Service User Guide
Amazon RDS and Amazon EC2

Feature On-premises management Amazon EC2 management

Application optimization Customer Customer

Scaling Customer Customer

High availability Customer Customer

Database backups Customer Customer

Database software patching Customer Customer

Database software install Customer Customer

Operating system (OS) patching Customer Customer

OS installation Customer Customer

Server maintenance Customer AWS

Hardware lifecycle Customer AWS

Power, network, and cooling Customer AWS

Amazon EC2 isn't a fully managed service. Thus, when you run a database on Amazon EC2, you're
more prone to user errors. For example, when you update the operating system or database software
manually, you might accidentally cause application downtime. You might spend hours checking every
change to identify and fix an issue.

Amazon RDS and Amazon EC2

Amazon RDS is a managed database service. It's responsible for most management tasks. By eliminating
tedious manual tasks, Amazon RDS frees you to focus on your application and your users. We
recommend Amazon RDS over Amazon EC2 as your default choice for most database deployments.

In the following table, you can find a comparison of the management models in Amazon EC2 and
Amazon RDS.

Feature Amazon EC2 management Amazon RDS management

Application optimization Customer Customer

Scaling Customer AWS

High availability Customer AWS

Database backups Customer AWS

Database software patching Customer AWS

Database software install Customer AWS

OS patching Customer AWS

OS installation Customer AWS

Server maintenance AWS AWS

Hardware lifecycle AWS AWS

2
 Amazon Relational Database Service User Guide
Amazon RDS Custom for Oracle

Feature Amazon EC2 management Amazon RDS management

Power, network, and cooling AWS AWS

Amazon RDS provides the following specific advantages over database deployments that aren't fully
managed:

• You can use the database products you are already familiar with: MySQL, MariaDB, PostgreSQL, Oracle,
Microsoft SQL Server.
• Amazon RDS manages backups, software patching, automatic failure detection, and recovery.
• You can turn on automated backups, or manually create your own backup snapshots. You can use
these backups to restore a database. The Amazon RDS restore process works reliably and efficiently.
• You can get high availability with a primary instance and a synchronous secondary instance that you
can fail over to when problems occur. You can also use 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 (VPC).

Amazon RDS Custom for Oracle

Amazon RDS Custom is an RDS management type that gives you full access to your database and
operating system.

You can use the control capabilities of RDS Custom to access and customize the database environment
and operating system for legacy and packaged business applications. Meanwhile, Amazon RDS
automates database administration tasks and operations.

In this deployment model, you can install applications and change configuration settings to suit your
applications. At the same time, you can offload database administration tasks such as provisioning,
scaling, upgrading, and backup to AWS. You can take advantage of the database management benefits
of Amazon RDS, with more control and flexibility.

For Oracle Database, RDS Custom combines the automation of Amazon RDS with the flexibility of
Amazon EC2.

Shared responsibility model for RDS Custom

Feature Amazon RDS management RDS Custom management

Application optimization Customer Customer

Scaling AWS Shared

High availability AWS Shared

Database backups AWS Shared

Database software patching AWS Shared

Database software install AWS Shared

OS patching AWS Shared

OS installation AWS Shared

Server maintenance AWS AWS

3
 Amazon Relational Database Service User Guide
DB instances

Feature Amazon RDS management RDS Custom management

Hardware lifecycle AWS AWS

Power, network, and cooling AWS AWS

With the shared responsibility model of RDS Custom, you get more control than in Amazon RDS, but also
more responsibility. To meet your application and business requirements, you manage everything at or
above the OS layer yourself.

For more information on RDS Custom, see Working with Amazon RDS Custom (p. 660).

DB instances
A DB instance is an isolated database environment in the AWS Cloud. The basic building block of Amazon
RDS is the DB instance.

Your DB instance can contain one or more user-created databases. You can access your DB instance by
using the same tools and applications that you use with a standalone 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.

DB engines
A DB engine is the specific relational database software that runs on your DB instance. Amazon RDS
currently supports the following engines:

• MySQL
• MariaDB
• PostgreSQL
• Oracle
• Microsoft SQL Server

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.

DB instance classes
A DB instance class determines the computation and memory capacity of a DB instance. Each instance
type offers different compute, memory, and storage capabilities. For example, db.m6g is a general-
purpose DB instance classes powered by AWS Graviton2 processors.

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. 10).
Note
For pricing information on DB instance classes, see the Pricing section of the Amazon RDS
product page.

DB instance storage
Amazon EBS provides durable, block-level storage volumes that you can attach to a running instance. DB
instance storage comes in the following types:

4
 Amazon Relational Database Service User Guide
Amazon Virtual Private Cloud (Amazon VPC)

• General Purpose (SSD)

• Provisioned IOPS (PIOPS)
• Magnetic

The storage types differ in performance characteristics and price. You can 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. 48).

Amazon Virtual Private Cloud (Amazon VPC)

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

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

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 Multi-AZ deployments for high availability (p. 59).

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.

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

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

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

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

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

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?

6
 Amazon Relational Database Service User Guide
Getting started

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

Topics specific to database engines

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

• MariaDB on Amazon RDS (p. 743)

• Microsoft SQL Server on Amazon RDS (p. 799)
• MySQL on Amazon RDS (p. 998)
• Oracle on Amazon RDS (p. 1154)
• PostgreSQL on Amazon RDS (p. 1690)

7
 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 AWS CLI, Amazon RDS API operations, or the

8
 Amazon Relational Database Service User Guide
DB instances

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.

9
 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. 10)
• Supported DB engines for DB instance classes (p. 11)
• Determining DB instance class support in AWS Regions (p. 25)
• Changing your DB instance class (p. 28)
• Configuring the processor for a DB instance class (p. 29)
• Hardware specifications for DB instance classes (p. 41)

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

The following are the memory optimized DB instance classes available:

• db.x2g – Instance classes optimized for memory-intensive applications and powered by AWS
Graviton2 processors. These offer low cost per GiB of memory.

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

10
 Amazon Relational Database Service User Guide
Supported DB engines

• 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.
• 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.r3 – Instance classes that provide memory optimization.

The following are the burstable performance DB instance classes available:

• db.t4g – Newest-generation general-purpose instance classes powered by Arm-based AWS Graviton2

processors. These deliver better price performance than previous-generation burstable performance
DB instance classes for a broad set of burstable 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 with any other DB instance modification.
• 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. 41).

Supported DB engines for DB instance classes

The following are DB engine–specific considerations for DB instance classes:

Microsoft SQL Server

DB 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. 803).
Oracle

DB instance class support varies according to the Oracle Database version and edition. RDS for
Oracle supports additional memory-optimized instance classes. These classes have names of the
form db.r5.instance_size.tpcthreads_per_core.memratio. For the vCPU count and memory
allocation for each optimized class, see Supported Oracle DB instance classes (p. 1170).

11
 Amazon Relational Database Service User Guide
Supported DB engines

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 All

10.5 versions & higher PostgreSQL
and MariaDB 13 versions
version and
10.4.13 & PostgreSQL
higher 10.4 12.3 & higher
versions 12 versions

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

10.5 versions & higher PostgreSQL
and MariaDB 13 versions
version and
10.4.13 & PostgreSQL
higher 10.4 12.3 & higher
versions 12 versions

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

10.5 versions & higher PostgreSQL
and MariaDB 13 versions
version and
10.4.13 & PostgreSQL
higher 10.4 12.3 & higher
versions 12 versions

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

10.5 versions & higher PostgreSQL
and MariaDB 13 versions
version and
10.4.13 & PostgreSQL
higher 10.4 12.3 & higher
versions 12 versions

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

10.5 versions & higher PostgreSQL
and MariaDB 13 versions
version and
10.4.13 & PostgreSQL
higher 10.4 12.3 & higher
versions 12 versions

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

10.5 versions & higher PostgreSQL
and MariaDB 13 versions
version and
10.4.13 & PostgreSQL
higher 10.4 12.3 & higher
versions 12 versions

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

10.5 versions & higher PostgreSQL

12
 Amazon Relational Database Service User Guide
Supported DB engines

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL Server
and MariaDB 13 versions
version and
10.4.13 & PostgreSQL
higher 10.4 12.3 & higher
versions 12 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 All

PostgreSQL
13, 12, and
11 versions,
10.4 & higher
versions, and
9.6.9 & higher
versions

db.m5.16xlarge Yes Yes Yes Yes All

PostgreSQL
13, 12, and
11 versions,
10.4 & higher
versions, and
9.6.9 & higher
versions

db.m5.12xlarge Yes Yes Yes Yes All

PostgreSQL
13, 12, and
11 versions,
10.4 & higher
versions, and
9.6.9 & higher
versions

13
 Amazon Relational Database Service User Guide
Supported DB engines

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL Server

db.m5.8xlarge Yes Yes Yes Yes All

PostgreSQL
13, 12, and
11 versions,
10.4 & higher
versions, and
9.6.9 & higher
versions

db.m5.4xlarge Yes Yes Yes Yes All

PostgreSQL
13, 12, and
11 versions,
10.4 & higher
versions, and
9.6.9 & higher
versions

db.m5.2xlarge Yes Yes Yes Yes All

PostgreSQL
13, 12, and
11 versions,
10.4 & higher
versions, and
9.6.9 & higher
versions

db.m5.xlarge Yes Yes Yes Yes All

PostgreSQL
13, 12, and
11 versions,
10.4 & higher
versions, and
9.6.9 & higher
versions

db.m5.large Yes Yes Yes Yes All

PostgreSQL
13, 12, and
11 versions,
10.4 & higher
versions, and
9.6.9 & higher
versions

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

14
 Amazon Relational Database Service User Guide
Supported DB engines

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL Server

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

db.m3.medium No Yes Yes Deprecated Lower than

PostgreSQL
13

db.x2g – memory-optimized instance classes powered by AWS Graviton2 processors

db.x2g.16xlarge MariaDB No MySQL 8.0.25 No All

version 10.5.9 & higher PostgreSQL
& higher 13 versions
10.5 versions and
and MariaDB PostgreSQL
version 12.5 & higher
10.4.18 & 12 versions
higher 10.4
versions

db.x2g.12xlarge MariaDB No MySQL 8.0.25 No All

version 10.5.9 & higher PostgreSQL
& higher 13 versions
10.5 versions and
and MariaDB PostgreSQL
version 12.5 & higher
10.4.18 & 12 versions
higher 10.4
versions

15
 Amazon Relational Database Service User Guide
Supported DB engines

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL Server

db.x2g.8xlarge MariaDB No MySQL 8.0.25 No All

version 10.5.9 & higher PostgreSQL
& higher 13 versions
10.5 versions and
and MariaDB PostgreSQL
version 12.5 & higher
10.4.18 & 12 versions
higher 10.4
versions

db.x2g.4xlarge MariaDB No MySQL 8.0.25 No All

version 10.5.9 & higher PostgreSQL
& higher 13 versions
10.5 versions and
and MariaDB PostgreSQL
version 12.5 & higher
10.4.18 & 12 versions
higher 10.4
versions

db.x2g.2xlarge MariaDB No MySQL 8.0.25 No All

version 10.5.9 & higher PostgreSQL
& higher 13 versions
10.5 versions and
and MariaDB PostgreSQL
version 12.5 & higher
10.4.18 & 12 versions
higher 10.4
versions

db.x2g.xlarge MariaDB No MySQL 8.0.25 No All

version 10.5.9 & higher PostgreSQL
& higher 13 versions
10.5 versions and
and MariaDB PostgreSQL
version 12.5 & higher
10.4.18 & 12 versions
higher 10.4
versions

db.x2g.large MariaDB No MySQL 8.0.25 No All

version 10.5.9 & higher PostgreSQL
& higher 13 versions
10.5 versions and
and MariaDB PostgreSQL
version 12.5 & higher
10.4.18 & 12 versions
higher 10.4
versions

db.z1d – memory-optimized instance classes

db.z1d.12xlarge No Yes No Yes No

db.z1d.6xlarge No Yes No Yes No

16
 Amazon Relational Database Service User Guide
Supported DB engines

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL Server

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 All

10.5 versions & higher PostgreSQL
and MariaDB 13 versions
version and
10.4.13 & PostgreSQL
higher 10.4 12.3 & higher
versions 12 versions

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

10.5 versions & higher PostgreSQL
and MariaDB 13 versions
version and
10.4.13 & PostgreSQL
higher 10.4 12.3 & higher
versions 12 versions

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

10.5 versions & higher PostgreSQL
and MariaDB 13 versions
version and
10.4.13 & PostgreSQL
higher 10.4 12.3 & higher
versions 12 versions

17
 Amazon Relational Database Service User Guide
Supported DB engines

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL Server

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

10.5 versions & higher PostgreSQL
and MariaDB 13 versions
version and
10.4.13 & PostgreSQL
higher 10.4 12.3 & higher
versions 12 versions

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

10.5 versions & higher PostgreSQL
and MariaDB 13 versions
version and
10.4.13 & PostgreSQL
higher 10.4 12.3 & higher
versions 12 versions

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

10.5 versions & higher PostgreSQL
and MariaDB 13 versions
version and
10.4.13 & PostgreSQL
higher 10.4 12.3 & higher
versions 12 versions

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

10.5 versions & higher PostgreSQL
and MariaDB 13 versions
version and
10.4.13 & PostgreSQL
higher 10.4 12.3 & higher
versions 12 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

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

18
 Amazon Relational Database Service User Guide
Supported DB engines

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL Server

db.r5b.24xlarge No Yes MySQL 8.0.25 Yes All

& higher PostgreSQL
13 versions
and
PostgreSQL
12.5 & higher
12 versions

db.r5b.16xlarge No Yes MySQL 8.0.25 Yes All

& higher PostgreSQL
13 versions
and
PostgreSQL
12.5 & higher
12 versions

db.r5b.12xlarge No Yes MySQL 8.0.25 Yes All

& higher PostgreSQL
13 versions
and
PostgreSQL
12.5 & higher
12 versions

db.r5b.8xlarge No Yes MySQL 8.0.25 Yes All

& higher PostgreSQL
13 versions
and
PostgreSQL
12.5 & higher
12 versions

db.r5b.4xlarge No Yes MySQL 8.0.25 Yes All

& higher PostgreSQL
13 versions
and
PostgreSQL
12.5 & higher
12 versions

db.r5b.2xlarge No Yes MySQL 8.0.25 Yes All

& higher PostgreSQL
13 versions
and
PostgreSQL
12.5 & higher
12 versions

db.r5b.xlarge No Yes MySQL 8.0.25 Yes All

& higher PostgreSQL
13 versions
and
PostgreSQL
12.5 & higher
12 versions

19
 Amazon Relational Database Service User Guide
Supported DB engines

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL Server

db.r5b.large No Yes MySQL 8.0.25 Yes All

& higher PostgreSQL
13 versions
and
PostgreSQL
12.5 & higher
12 versions

db.r5 – latest generation memory optimized instance classes preconfigured for high memory, storage, and I/O

db.r5.12xlarge.tpc2.mem2x No No No Yes No

db.r5.8xlarge.tpc2.mem3x No No No Yes No

db.r5.6xlarge.tpc2.mem4x No No No Yes No

db.r5.4xlarge.tpc2.mem4x No No No Yes No

db.r5.4xlarge.tpc2.mem3x No No No Yes No

db.r5.4xlarge.tpc2.mem2x No No No Yes No

db.r5.2xlarge.tpc2.mem8x No No No Yes No

db.r5.2xlarge.tpc2.mem4x No No No Yes No

db.r5.2xlarge.tpc1.mem2x No No No Yes No

db.r5.xlarge.tpc2.mem4x No No No Yes No

db.r5.xlarge.tpc2.mem2x No No No Yes No

db.r5.large.tpc1.mem2x No No No Yes No

db.r5 – latest generation memory optimized instance classes

db.r5.24xlarge Yes Yes Yes Yes All

PostgreSQL
13, 12, and
11 versions,
10.4 & higher
versions, and
9.6.9 & higher
versions

db.r5.16xlarge Yes Yes Yes Yes All

PostgreSQL
13, 12, and
11 versions,
10.4 & higher
versions, and
9.6.9 & higher
versions

20
 Amazon Relational Database Service User Guide
Supported DB engines

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL Server

db.r5.12xlarge Yes Yes Yes Yes All

PostgreSQL
13, 12, and
11 versions,
10.4 & higher
versions, and
9.6.9 & higher
versions

db.r5.8xlarge Yes Yes Yes Yes All

PostgreSQL
13, 12, and
11 versions,
10.4 & higher
versions, and
9.6.9 & higher
versions

db.r5.4xlarge Yes Yes Yes Yes All

PostgreSQL
13, 12, and
11 versions,
10.4 & higher
versions, and
9.6.9 & higher
versions

db.r5.2xlarge Yes Yes Yes Yes All

PostgreSQL
13, 12, and
11 versions,
10.4 & higher
versions, and
9.6.9 & higher
versions

db.r5.xlarge Yes Yes Yes Yes All

PostgreSQL
13, 12, and
11 versions,
10.4 & higher
versions, and
9.6.9 & higher
versions

db.r5.large Yes Yes Yes Yes All

PostgreSQL
13, 12, and
11 versions,
10.4 & higher
versions, and
9.6.9 & higher
versions

db.r4 – memory optimized instance classes

21
 Amazon Relational Database Service User Guide
Supported DB engines

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL Server

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

5.7, and 5.6 PostgreSQL
versions 13

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

5.7, and 5.6 PostgreSQL
versions 13

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

5.7, and 5.6 PostgreSQL
versions 13

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

5.7, and 5.6 PostgreSQL
versions 13

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

5.7, and 5.6 PostgreSQL
versions 13

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

5.7, and 5.6 PostgreSQL
versions 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

db.r3.xlarge Yes Yes Yes Deprecated Lower than

PostgreSQL
13

db.r3.large Yes Yes Yes Deprecated Lower than

PostgreSQL
13

db.m2 – previous generation 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.t4g – newest generation burstable performance instance classes

22
 Amazon Relational Database Service User Guide
Supported DB engines

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL Server

db.t4g.2xlarge MariaDB No MySQL 8.0.25 No All

version 10.5.9 & higher PostgreSQL
& higher 13 versions
10.5 versions and
and MariaDB PostgreSQL
version 12.5 & higher
10.4.18 & 12 versions
higher 10.4
versions

db.t4g.xlarge MariaDB No MySQL 8.0.25 No All

version 10.5.9 & higher PostgreSQL
& higher 13 versions
10.5 versions and
and MariaDB PostgreSQL
version 12.5 & higher
10.4.18 & 12 versions
higher 10.4
versions

db.t4g.large MariaDB No MySQL 8.0.25 No All

version 10.5.9 & higher PostgreSQL
& higher 13 versions
10.5 versions and
and MariaDB PostgreSQL
version 12.5 & higher
10.4.18 & 12 versions
higher 10.4
versions

db.t4g.medium MariaDB No MySQL 8.0.25 No All

version 10.5.9 & higher PostgreSQL
& higher 13 versions
10.5 versions and
and MariaDB PostgreSQL
version 12.5 & higher
10.4.18 & 12 versions
higher 10.4
versions

db.t4g.small MariaDB No MySQL 8.0.25 No All

version 10.5.9 & higher PostgreSQL
& higher 13 versions
10.5 versions and
and MariaDB PostgreSQL
version 12.5 & higher
10.4.18 & 12 versions
higher 10.4
versions

23
 Amazon Relational Database Service User Guide
Supported DB engines

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL Server

db.t4g.micro MariaDB No MySQL 8.0.25 No All

version 10.5.9 & higher PostgreSQL
& higher 13 versions
10.5 versions and
and MariaDB PostgreSQL
version 12.5 & higher
10.4.18 & 12 versions
higher 10.4
versions

db.t3 – latest generation burstable performance instance classes

db.t3.2xlarge Yes Yes Yes Yes All

PostgreSQL
13, 12, 11,
and 10
versions, and
PostgreSQL
9.6.9 & higher
versions

db.t3.xlarge Yes Yes Yes Yes All

PostgreSQL
13, 12, 11,
and 10
versions, and
PostgreSQL
9.6.9 & higher
versions

db.t3.large Yes Yes Yes Yes All

PostgreSQL
13, 12, 11,
and 10
versions, and
PostgreSQL
9.6.9 & higher
versions

db.t3.medium Yes Yes Yes Yes All

PostgreSQL
13, 12, 11,
and 10
versions, and
PostgreSQL
9.6.9 & higher
versions

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

Instance class MariaDB Microsoft MySQL Oracle PostgreSQL

SQL Server

db.t3.small Yes Yes Yes Yes All

PostgreSQL
13, 12, 11,
and 10
versions, and
PostgreSQL
9.6.9 & higher
versions

db.t3.micro Yes No Yes Yes All

PostgreSQL
13, 12, 11,
and 10
versions, and
PostgreSQL
9.6.9 & higher
versions

db.t2 – burstable performance instance classes

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

5.7, and 5.6 PostgreSQL
versions 13

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

5.7, and 5.6 PostgreSQL
versions 13

db.t2.large Yes Yes Yes Deprecated Lower than

PostgreSQL
13

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

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

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. 26)
• Using the AWS CLI to determine DB instance class support in AWS Regions (p. 26)
• Listing the DB instance classes that are supported by a specific DB engine version in an AWS
Region (p. 27)
• Listing the DB engine versions that support a specific DB instance class in an AWS
Region (p. 28)

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.

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

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

RDS (p. 807)
sqlserver-se

sqlserver-ex

sqlserver-web

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

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

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

Engine names Engine values in CLI More information about versions

commands
oracle-se2

oracle-se

PostgreSQL postgres Supported PostgreSQL database versions (p. 1696)

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

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. 27)
• Listing the DB engine versions that support a specific DB instance class in an AWS Region (p. 28)

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:

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

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:

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

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

For Windows:

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:

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:

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:

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:

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

28
 Amazon Relational Database Service User Guide
Configuring the processor

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

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 class. For example, a db.m4.xlarge DB instance class 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. 29)
• DB instance classes that support processor configuration (p. 29)
• Setting the CPU cores and threads per CPU core for a DB instance class (p. 34)

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.

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.

DB instance classes that support processor configuration

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

• You're 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. 1170).

29
 Amazon Relational Database Service User Guide
Configuring the processor

• Your instance is using the Bring Your Own License (BYOL) licensing option. For more information about
Oracle licensing options, see Oracle licensing options (p. 1167).
• Your instance isn't one of the db.r5 instance classes that have predefined
processor configurations. These instance classes have names of the form
db.r5.instance_size.tpcthreads_per_core.memratio. For example, db.r5.xlarge.tpc2.mem4x
is preconfigured with 2 threads per core (tpc2) and 4x as much memory as the standard db.r5.xlarge
instance class. You can't configure the processor features of these optimized instance classes. For more
information, see Supported Oracle DB instance classes (p. 1170).

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

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

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

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

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

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

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

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

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

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

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

• Modifying an Amazon RDS DB instance (p. 306)
• Restoring from a DB snapshot (p. 411)
• Restoring a DB instance to a specified time (p. 455)

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.

34
Amazon Relational Database Service User Guide
Configuring the processor

35
 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

36
 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. 37)
• Setting the number of CPU cores and disabling multiple threads for a DB instance (p. 37)
• Viewing the valid processor values for a DB instance class (p. 38)
• Returning to default processor settings for a DB instance (p. 39)
• Returning to the default number of CPU cores for a DB instance (p. 39)
• Returning to the default number of threads per core for a DB instance (p. 40)

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.

37
 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"
}
],

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

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

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

41
 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. 48).
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. 11).

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

42
 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.x2g – memory-optimized instance classes

db.x2g.16xlarge 64 — 1024 Yes Yes 19,000 25 Gbps

43
 Amazon Relational Database Service User Guide
Hardware specifications

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

db.x2g.12xlarge 48 — 768 Yes Yes 14,250 20 Gbps

db.x2g.8xlarge 32 — 512 Yes Yes 9,500 12 Gbps

db.x2g.4xlarge 16 — 256 Yes Yes 4,750 Up to 10

Gbps

db.x2g.2xlarge 8 — 128 Yes Yes Up to 4,750 Up to 10

Gbps

db.x2g.xlarge 4 — 64 Yes Yes Up to 4,750 Up to 10

Gbps

db.x2g.large 2 — 32 Yes Yes Up to 4,750 Up to 10

Gbps

db.z1d – memory-optimized instance classes

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

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

44
 Amazon Relational Database Service User Guide
Hardware specifications

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

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

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

45
 Amazon Relational Database Service User Guide
Hardware specifications

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

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

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

46
 Amazon Relational Database Service User Guide
Hardware specifications

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

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.t4g – newest generation burstable performance instance classes

db.t4g.2xlarge* 8 – 32 Yes Yes Up to 2,780 Up to 5 Gbps

db.t4g.xlarge* 4 – 16 Yes Yes Up to 2,780 Up to 5 Gbps

db.t4g.large* 2 – 8 Yes Yes Up to 2,780 Up to 5 Gbps

db.t4g.medium* 2 – 4 Yes Yes Up to 2,085 Up to 5 Gbps

db.t4g.small* 2 – 2 Yes Yes Up to 2,085 Up to 5 Gbps

db.t4g.micro* 2 – 1 Yes Yes Up to 2,085 Up to 5 Gbps

db.t3 – latest 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

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.

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

47
 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. 48).
• 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. 50).
• 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. 51).

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 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.
Maximum baseline performance for a gp2 volume (5.34 TiB and greater) is 16,000 IOPS.

48
 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.
Instance I/O credit balance determines burst performance. For more information about instance I/O
credits, see I/O credits and burst performance (p. 49).

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.

For gp2 volumes larger than 1 TiB, the baseline performance is greater than the burst performance. For
such volumes, burst is irrelevant because the baseline performance is better than the 3,000 IOPS burst
performance.
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. 376).

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)

49
 Amazon Relational Database Service User Guide
Provisioned IOPS storage

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

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 (1.0 on RDS for SQL Server) and not more than 50.
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.

Database engine Range of Provisioned Range of storage

IOPS

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

SQL Server 1,000–64,000 IOPS 20 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

The ratio of IOPS to allocated storage (in GiB) must be from 1–50 on RDS for SQL Server, and 0.5–50 on
other RDS DB engines.
Note
For SQL Server, the maximum 64,000 IOPS 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, you can provision the maximum 256,000 IOPS only on the r5b instance type.

50
 Amazon Relational Database Service User Guide
Magnetic storage

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

51
 Amazon Relational Database Service User Guide
Monitoring storage performance

Monitoring storage performance

Amazon RDS provides several metrics that you can use to determine how your DB instance is performing.
You can view the metrics on the summary page for your instance in Amazon RDS Management Console.
You can also use Amazon CloudWatch to monitor these metrics. For more information, see Viewing
DB instance metrics (p. 477). Enhanced Monitoring provides more detailed I/O metrics; for more
information, see Monitoring the OS by using Enhanced Monitoring (p. 551).

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 at 1-minute intervals. Typical values for latency are in milliseconds (ms).
• Throughput – The number of bytes each second that are transferred to or from disk. This metric is
reported as the average throughput for a given time interval. Amazon RDS reports read and write
throughput separately on 1-minute intervals using units of megabytes per second (MB/s). Typical
values for throughput range from zero to the I/O channel's maximum bandwidth.
• Queue Depth – The number of I/O requests in the queue waiting to be serviced. These are I/O
requests that have been submitted by the application but have not been sent to the device because
the device is busy servicing other I/O requests. Time spent waiting in the queue is a component of
latency and service time (not available as a metric). This metric is reported as the average queue depth
for a given time interval. Amazon RDS reports queue depth in 1-minute intervals. Typical values for
queue depth range from zero to several hundred.

Measured IOPS values are independent of the size of the individual I/O operation. This means that when
you measure I/O performance, you should look at the throughput of the instance, not simply the number
of I/O operations.

Factors that affect storage performance

System activities, database workload, and DB instance class can affect storage performance.

System activities
The following system-related activities consume I/O capacity and might reduce DB 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 might 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.

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

• You experience query contention in the database even though some I/O capacity is unused.

In some cases, there isn't a system resource that is at or near a limit, and adding threads doesn't increase
the database transaction rate. In such cases, 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, seek the advice of a database performance tuning expert.

DB instance class
To get the most performance out of your Amazon RDS DB instance, choose a current generation instance
type with enough bandwidth to support your storage type. For example, you can choose Amazon 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 you can provision with RDS. 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 can also have lower maximum storage.

Some older 32-bit file systems might have lower storage capacities. To determine the storage capacity of
your DB instance, you can use the describe-valid-db-instance-modifications AWS CLI command.

The following list shows the maximum storage that most DB instance classes can scale to for each
database engine:

• MariaDB: 64 TiB
• Microsoft SQL Server: 16 TiB
• MySQL: 64 TiB
• Oracle: 64 TiB
• PostgreSQL: 64 TiB

The following table shows some exceptions. All RDS for Microsoft SQL Server DB instances have a
maximum storage of 16 TiB, so there are no entries for SQL Server.

Instance class MariaDB MySQL Oracle PostgreSQL

db.m3 – previous generation standard instance classes

db.m3.2xlarge N/A 6 N/A 6

db.m3.xlarge N/A 6 N/A 6

db.m3.large N/A 6 N/A 6

db.m3.medium N/A 32 N/A 32

db.t3 – latest generation burstable performance instance classes

db.t3.medium 16 16 32 32

db.t3.small 16 16 32 16

db.t3.micro 16 16 32 16

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

Instance class MariaDB MySQL Oracle PostgreSQL

db.t2 – current generation burstable performance instance classes

db.t2.medium 32 32 N/A 32

db.t2.small 16 16 N/A 16

db.t2.micro 16 16 N/A 16

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

54
 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 DB instances that are in the same location. If you host all your DB instances in a
single location that is affected by such a failure, none of your DB instances will be available.

It is important to remember that each AWS Region is completely independent. Any Amazon RDS activity
you initiate (for example, creating database instances or listing available database instances) runs only
in your current default AWS Region. The default AWS Region can be changed in the console, by setting
the 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.

55
 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

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

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

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

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)

56
 Amazon Relational Database Service User Guide
AWS Regions

Region Region Endpoint Protocol

Name

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

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

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.

57
 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 Multi-AZ deployments for high availability (p. 59).
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. 194) and Modifying an Amazon RDS DB instance (p. 306).

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

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

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.

58
 Amazon Relational Database Service User Guide
Multi-AZ deployments

Multi-AZ deployments for high availability

Multi-AZ deployments can have one standby or two standby DB instances. When the deployment
has one standby DB instance, it's called a Multi-AZ DB instance deployment. A Multi-AZ DB instance
deployment has one standby DB instance that provides failover support, but doesn't serve read traffic.
When the deployment has two standby DB instances, it's called a Multi-AZ DB cluster deployment. A
Multi-AZ DB cluster deployment has standby DB instances that provide failover support and can also
serve read traffic.

Topics
• Multi-AZ DB instance deployments (p. 60)
• Multi-AZ DB cluster deployments (preview) (p. 65)

Note
Multi-AZ DB clusters are in preview for RDS for MySQL and RDS for PostgreSQL and are subject
to change.

59
 Amazon Relational Database Service User Guide
Multi-AZ DB instance deployments

Multi-AZ DB instance deployments

Amazon RDS provides high availability and failover support for DB instances using Multi-AZ deployments
with a single standby DB instance. This type of deployment is called a Multi-AZ DB instance deployment.
Amazon RDS uses several different technologies to provide this failover support. Multi-AZ deployments
for MariaDB, MySQL, Oracle, and PostgreSQL DB instances use the Amazon failover technology.
Microsoft 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
Amazon RDS for Microsoft SQL Server (p. 867).

In a Multi-AZ DB instance 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 and minimize
latency spikes during system backups. Running a DB instance with high availability can enhance
availability during planned system maintenance. It can also 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. 55).
Note
The high availability option 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, use a Multi-AZ DB cluster or a
read replica instead. For more information about Multi-AZ DB clusters, see Multi-AZ DB cluster
deployments (preview) (p. 65). For more information about read replicas, see Working with
read replicas (p. 338).

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

60
 Amazon Relational Database Service User Guide
Multi-AZ DB instance deployments

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 DB instance deployments can have increased write and commit latency
compared to a Single-AZ deployment. This can happen because of 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 that you use Provisioned IOPS (input/output operations per second) for fast,
consistent performance. For more information about DB instance classes, see DB instance classes (p. 10).

Modifying a DB instance to be a Multi-AZ DB instance

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

For information about modifying a DB instance, see Modifying an Amazon RDS DB instance (p. 306).
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 workloads that are sensitive to write latency.
To turn on Multi-AZ for a DB instance, RDS takes a snapshot of the primary DB instance's
Amazon EBS volume and restores it on the newly created standby replica. RDS then
synchronizes both volumes. New volumes created from existing EBS snapshots load lazily in
the background. This capability lets large volumes be restored from a snapshot quickly, but
it can add latency during the modification and after it's 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. 571).

Failover process for Amazon RDS

If a planned or unplanned outage of your DB instance results from an infrastructure defect, Amazon RDS
automatically switches to a standby replica in another Availability Zone if you have turned on Multi-AZ.
The time that 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. 336).

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.

61
 Amazon Relational Database Service User Guide
Multi-AZ DB instance deployments

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

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

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

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. 571) and
Creating a rule that triggers on an Amazon RDS
event (p. 589).
• Evaluate your workload to determine whether
you're using the appropriate DB instance
class. For more information, see DB instance
classes (p. 10).
• Use Enhanced Monitoring for real-time
operating system metrics. For more
information, see Monitoring the OS by using
Enhanced Monitoring (p. 551).
• Use Performance Insights to help analyze
any issues that affect your DB instance's
performance. For more information, see
Monitoring DB load with Performance Insights
on Amazon RDS (p. 487).

For more information on these recommendations,

see Overview of monitoring Amazon
RDS (p. 466) and Best practices for Amazon
RDS (p. 180).

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

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

62
 Amazon Relational Database Service User Guide
Multi-AZ DB instance deployments

Failover reason Description

For more information, see Rebooting a DB
instance (p. 336).

To determine if your Multi-AZ DB cluster has failed over, you can do the following:

• Set up DB event subscriptions 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. 571).
• View your DB events by using the RDS console or API operations.
• View the current state of your Multi-AZ DB instance deployment by using the RDS console or 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. 180).

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 host name 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.

63
 Amazon Relational Database Service User Guide
Multi-AZ DB instance deployments

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

64
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

Multi-AZ DB cluster deployments (preview)

Multi-AZ DB clusters are in preview for RDS for MySQL and RDS for PostgreSQL and are subject to
change.

A Multi-AZ DB cluster deployment is a high availability deployment mode of Amazon RDS with two
readable standby DB instances. A Multi-AZ DB cluster has a writer DB instance and two reader DB
instances in three separate Availability Zones in the same AWS Region. Multi-AZ DB clusters provide high
availability, increased capacity for read workloads, and lower write latency when compared to Multi-AZ
DB instance deployments.

Topics
• Overview of Multi-AZ DB clusters (p. 65)
• Supported DB instance classes for Multi-AZ DB clusters (p. 66)
• Creating a Multi-AZ DB cluster (p. 67)
• Managing connections for Multi-AZ DB clusters (p. 78)
• Managing a Multi-AZ DB cluster with the AWS Management Console (p. 80)
• Modifying a Multi-AZ DB cluster (p. 82)
• Rebooting Multi-AZ DB clusters and reader DB instances (p. 90)
• Working with parameter groups for Multi-AZ DB clusters (p. 91)
• Failover process for Multi-AZ DB clusters (p. 91)
• Creating a Multi-AZ DB cluster snapshot (p. 93)
• Restoring from a snapshot to a Multi-AZ DB cluster (p. 94)
• Restoring a Multi-AZ DB cluster to a specified time (p. 96)
• Deleting a Multi-AZ DB cluster (p. 98)
• Limitations for Multi-AZ DB clusters (p. 99)

Important
Multi-AZ DB clusters aren't the same as Aurora DB clusters. For information about Aurora DB
clusters, see the Amazon Aurora User Guide.

Overview of Multi-AZ DB clusters

With a Multi-AZ DB cluster, Amazon RDS replicates data from the writer DB instance to both of the
reader DB instances using the DB engine's native replication capabilities. When a change is made on the
writer DB instance, it's sent to each reader DB instance. Acknowledgment from at least one reader DB
instance is required for a change to be committed and applied. Reader DB instances act as automatic
failover targets and also serve read traffic to increase application read throughput.

The following diagram shows a Multi-AZ DB cluster.

65
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

Multi-AZ DB clusters typically have lower write latency when compared to Multi-AZ DB instance
deployments. The RDS console shows the Availability Zone of the writer DB instance and the Availability
Zones of the reader DB instances. You can also use the describe-db-clusters CLI command or the
DescribeDBClusters API operation to find this information.

Supported DB instance classes for Multi-AZ DB clusters

Multi-AZ DB clusters support the following DB instance classes.

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

db.m6gd

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

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

db.m6gd.8xlarge 32 – 128 Yes Yes 9,000 12 Gbps

66
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

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

db.m6gd.4xlarge 16 – 64 Yes Yes 4,750 Up to 10

Gbps

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

Gbps

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

Gbps

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

Gbps

db.r6gd

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

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

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

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

Gbps

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

Gbps

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

Gbps

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

Gbps

Creating a Multi-AZ DB cluster

A Multi-AZ DB cluster has a writer DB instance and two reader DB instances in three separate Availability
Zones. Multi-AZ DB clusters provide high availability, increased capacity for read workloads, and lower
latency when compared to Multi-AZ deployments. For more information about Multi-AZ DB clusters, see
Multi-AZ DB cluster deployments (preview) (p. 65).
Note
Multi-AZ DB clusters are supported only for the MySQL and PostgreSQL DB engines.

In the following topic, you can find out how to create a Multi-AZ DB cluster. To get started, first see DB
cluster prerequisites (p. 67).

For instructions on connecting to your Multi-AZ DB cluster, see Connecting to an Amazon RDS DB
instance (p. 215).

DB cluster prerequisites
Before you create a Multi-AZ DB cluster, make sure to complete the tasks in Setting up for Amazon
RDS (p. 112). The following are additional prerequisites to creating a Multi-AZ DB cluster.

67
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

VPC prerequisites

You can only create a Multi-AZ DB cluster in a virtual private cloud (VPC) based on the Amazon VPC
service, in an AWS Region that has at least three Availability Zones. The DB subnet group that you choose
for the DB cluster must cover at least three Availability Zones. This configuration ensures that your DB
cluster always has at least two DB instance available for failover, in the unlikely event of an Availability
Zone failure.

If you are using the AWS Management Console to create your Multi-AZ DB cluster, you can have Amazon
RDS automatically create a VPC for you. Or you can use an existing VPC or create a new VPC for your
Multi-AZ DB cluster. Your VPC must have at least one subnet in each of at least three Availability Zones
for you to use it with a Multi-AZ DB cluster. For information on VPCs, see Amazon Virtual Private Cloud
VPCs and Amazon RDS (p. 1975).

If you don't have a default VPC or you haven't created a VPC, and you don't plan to use the console, do
the following:

• Create a VPC with at least one subnet in each of at least three of the Availability Zones in the AWS
Region where you want to deploy your DB cluster. For more information, see Working with a DB
instance in a VPC (p. 1976).
• Specify a VPC security group that authorizes connections to your DB cluster. For more information, see
Working with a DB instance in a VPC (p. 1976).
• Specify an RDS DB subnet group that defines at least three subnets in the VPC that can be used by the
Multi-AZ DB cluster. For more information, see Working with DB subnet groups (p. 1977).

Additional prerequisites

If you are connecting to AWS using AWS Identity and Access Management (IAM) credentials, your AWS
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. 1893).

If you are using IAM to access the Amazon RDS console, first sign on to the AWS Management Console
with your IAM user credentials. Then go to the Amazon RDS console at https://console.aws.amazon.com/
rds/.

If you want to tailor the configuration parameters for your DB cluster, specify a DB cluster parameter
group with the required parameter settings. For information about creating or modifying a DB cluster
parameter group, see Working with parameter groups for Multi-AZ DB clusters (p. 91).

Determine the TCP/IP port number to specify for your DB cluster. The firewalls at some companies block
connections to the default ports. If your company firewall blocks the default port, choose another port
for your DB cluster. All DB instances in a DB cluster use the same port.

Creating a DB cluster
You can create a Multi-AZ DB cluster using the AWS Management Console, the AWS CLI, or the RDS API.

Console

You can create a Multi-AZ DB cluster by choosing Multi-AZ DB cluster - preview in the Availability and
durability section.

To create a Multi-AZ DB cluster 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 upper-right corner of the AWS Management Console, choose the AWS Region in which you
want to create the DB cluster.

68
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

For preview, only the US East (N. Virginia), US West (Oregon), and Europe (Ireland) AWS Regions
support Multi-AZ DB clusters.
3. In the navigation pane, choose Databases.
4. Choose Create database.

To create a Multi-AZ DB cluster, make sure that Standard Create is selected and Easy Create isn't.
5. In Engine type, choose MySQL or PostgreSQL.
6. For Version, choose the DB engine version.

You can create a Multi-AZ DB cluster only with MySQL version 8.0.26 and PostgreSQL version 13.4.
7. In Templates, choose the appropriate template for your deployment.
8. In Availability and durability, choose Multi-AZ DB cluster - preview.

9. In DB cluster identifier, enter the identifier for your DB cluster.

10. In Master username, enter your master user name, or keep the default setting.
11. Enter your master password:

a. In the Settings section, open Credential Settings.

b. If you want to specify a password, clear the Auto generate a password box if it is selected.
c. (Optional) Change the Master username value.
d. Enter the same password in Master password and Confirm password.
12. In DB instance class, choose a DB instance class.
13. For the remaining sections, specify your DB cluster settings. For information about each setting, see
Settings for creating Multi-AZ DB clusters (p. 71).
14. 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 cluster, choose View credential details.

69
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

To connect to the DB cluster as the master user, use the user name and password that appear.
Important
You can't view the master user password again.
15. For Databases, choose the name of the new DB cluster.

On the RDS console, the details for the new DB cluster appear. The DB cluster has a status of Creating
until the DB cluster is created and ready for use. When the state changes to Available, you can connect
to the DB cluster. Depending on the DB cluster class and storage allocated, it can take several minutes
for the new DB cluster to be available.

AWS CLI
Before you create a Multi-AZ DB cluster using the AWS CLI, make sure to fulfill the required
prerequisites, such as creating a VPC and an RDS DB subnet group. For more information, see DB cluster
prerequisites (p. 67).

To create a Multi-AZ DB cluster by using the AWS CLI, call the create-db-cluster command. Specify the --
db-cluster-identifier. For the --engine option, specify either mysql or postgres.

For information about each option, see Settings for creating Multi-AZ DB clusters (p. 71).

The create-db-cluster command creates the writer DB instance for your DB cluster, and two reader
DB instances. Each DB instance is in a different Availability Zone.

For example, the following command creates a MySQL 8.0 Multi-AZ DB cluster named mysql-multi-
az-db-cluster.

Example
For Linux, macOS, or Unix:

aws rds create-db-cluster \

--db-cluster-identifier mysql-multi-az-db-cluster \
--engine mysql \
--engine-version 8.0.26 \
--master-user-password password \
--master-username admin \
--port 3306 \
--backup-retention-period 1 \
--db-subnet-group-name default \
--allocated-storage 4000 \
--storage-type io1 \
--iops 10000 \
--db-cluster-instance-class db.r6gd.xlarge

For Windows:

aws rds create-db-cluster ^

--db-cluster-identifier mysql-multi-az-db-cluster ^
--engine mysql ^
--engine-version 8.0.26 ^
--master-user-password password ^
--master-username admin ^
--port 3306 ^
--backup-retention-period 1 ^
--db-subnet-group-name default ^

70
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

--allocated-storage 4000 ^
--storage-type io1 ^
--iops 10000 ^
--db-cluster-instance-class db.r6gd.xlarge

The following command creates a PostgreSQL 13.4 Multi-AZ DB cluster named postgresql-multi-
az-db-cluster.

Example
For Linux, macOS, or Unix:

aws rds create-db-cluster \

--db-cluster-identifier postgresql-multi-az-db-cluster \
--engine postgres \
--engine-version 13.4 \
--master-user-password password \
--master-username postgres \
--port 5432 \
--backup-retention-period 1 \
--db-subnet-group-name default \
--allocated-storage 4000 \
--storage-type io1 \
--iops 10000 \
--db-cluster-instance-class db.r6gd.xlarge

For Windows:

aws rds create-db-cluster ^

--db-cluster-identifier postgresql-multi-az-db-cluster ^
--engine postgres ^
--engine-version 13.4 ^
--master-user-password password ^
--master-username postgres ^
--port 5432 ^
--backup-retention-period 1 ^
--db-subnet-group-name default ^
--allocated-storage 4000 ^
--storage-type io1 ^
--iops 10000 ^
--db-cluster-instance-class db.r6gd.xlarge

RDS API
Before you can create a Multi-AZ DB cluster using the RDS API, make sure to fulfill the required
prerequisites, such as creating a VPC and an RDS DB subnet group. For more information, see DB cluster
prerequisites (p. 67).

To create a Multi-AZ DB cluster by using the RDS API, call the CreateDBCluster operation. Specify the
DBClusterIdentifier. For the Engine parameter, specify either mysql or postgresql.

For information about each option, see Settings for creating Multi-AZ DB clusters (p. 71).

The CreateDBCluster operation creates the writer DB instance for your DB cluster, and two reader DB
instances. Each DB instance is in a different Availability Zone.

Settings for creating Multi-AZ DB clusters

For details about settings that you choose when you create a Multi-AZ DB cluster, see the following
table. For more information about the AWS CLI options, see create-db-cluster. For more information
about the RDS API parameters, see CreateDBCluster.

71
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

Console setting Setting description CLI option and RDS API parameter

Allocated storage The amount of storage to allocate for CLI option:

each DB instance in your DB cluster (in
gibibyte). --allocated-storage

For more information, see Amazon RDS API parameter:

DB instance storage (p. 48).
AllocatedStorage

Auto minor version Enable auto minor version upgrade to CLI option:
upgrade have your DB cluster receive preferred
minor DB engine version upgrades --auto-minor-version-upgrade
automatically when they become
available. Amazon RDS performs --no-auto-minor-version-upgrade
automatic minor version upgrades in the
API parameter:
maintenance window.
AutoMinorVersionUpgrade

Backup retention The number of days that you want CLI option:
period automatic backups of your DB cluster to
be retained. For a Multi-AZ DB cluster, this --backup-retention-period
value must be set to 1 or greater.
API parameter:
For more information, see Working with
backups (p. 388). BackupRetentionPeriod

Backup window The time period during which Amazon CLI option:
RDS automatically takes a backup of
your DB cluster. Unless you have a --preferred-backup-window
specific time that you want to have your
database backed up, use the default of No API parameter:
preference.
PreferredBackupWindow
For more information, see Working with
backups (p. 388).

Database For Multi-AZ DB clusters, only Password None because password authentication is the
authentication authentication is supported. default.

Database port The port that you want to access the DB CLI option:
cluster through. The default port is shown.
If you use a DB security group with your --port
DB cluster, this port value must be the
same one that you provided when creating RDS API parameter:
the DB security group.
Port
In the preview, the port can't be changed
after the DB cluster is created.

The firewalls at some companies block

connections to the default ports. If your
company firewall blocks the default port,
enter another port for your DB cluster.

DB cluster The name for your DB cluster. Name your CLI option:
identifier DB clusters in the same way that you
name your on-premises servers. Your --db-cluster-identifier
DB cluster identifier can contain up to

72
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

Console setting Setting description CLI option and RDS API parameter
63 alphanumeric characters, and must RDS API parameter:
be unique for your account in the AWS
Region you chose. DBClusterIdentifier

DB cluster instance The compute and memory capacity of CLI option:

class each DB instance in the Multi-AZ DB
cluster, for example db.r6gd.xlarge. --db-cluster-instance-class

If possible, choose a DB instance class RDS API parameter:

large enough that a typical query working
set can be held in memory. When working DBClusterInstanceClass
sets are held in memory the system can
avoid writing to disk, which improves
performance. For more information, see
Supported DB instance classes for Multi-
AZ DB clusters (p. 66).

DB cluster The DB cluster parameter group that you CLI option:

parameter group want associated with the DB cluster.
--db-cluster-parameter-group-name
For more information, see Working
with parameter groups for Multi-AZ DB RDS API parameter:
clusters (p. 91).
DBClusterParameterGroupName

DB engine version The version of database engine that you CLI option:
want to use.
--engine-version

RDS API parameter:

EngineVersion

DB parameter The DB instance parameter group that you Not applicable. Amazon RDS associates each
group want associated with the DB instances in DB instance with the appropriate default
the DB cluster. parameter group.

For more information, see Working

with parameter groups for Multi-AZ DB
clusters (p. 91).

Deletion protection Enable deletion protection to prevent CLI option:

your DB cluster from being deleted. If you
create a production DB cluster with the --deletion-protection
console, deletion protection is turned on
by default. --no-deletion-protection

For more information, see Deleting a DB RDS API parameter:

instance (p. 384).
DeletionProtection

73
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

Console setting Setting description CLI option and RDS API parameter

Encryption Enable Encryption to turn on encryption CLI options:

at rest for this DB cluster.
--kms-key-id
Encryption is turned on by default for
Multi-AZ DB clusters. --storage-encrypted

For more information, see Encrypting --no-storage-encrypted

Amazon RDS resources (p. 1879).
RDS API parameters:

KmsKeyId

StorageEncrypted

Enhanced Enable enhanced monitoring to turn CLI options:

Monitoring on metrics gathering in real time for the
operating system that your DB cluster runs --monitoring-interval
on.
--monitoring-role-arn
For more information, see Monitoring
the OS by using Enhanced RDS API parameters:
Monitoring (p. 551).
MonitoringInterval

MonitoringRoleArn

Initial database The name for the database on your DB CLI option:
name cluster. If you don't provide a name,
Amazon RDS doesn't create a database --database-name
on the DB cluster for MySQL, but it does
create a database on the DB cluster for RDS API parameter:
PostgreSQL. The name can't be a word
DatabaseName
reserved by the database engine, and has
other constraints depending on the DB
engine.

MySQL:

• It must contain 1–64 alphanumeric

characters.

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.

74
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

Console setting Setting description CLI option and RDS API parameter

Maintenance The 30-minute window in which pending CLI option:

window modifications to your DB cluster are
applied. If the time period doesn't matter, --preferred-maintenance-window
choose No preference.
RDS API parameter:
For more information, see The Amazon
RDS maintenance window (p. 324). PreferredMaintenanceWindow

Master password The password for your master user CLI option:
account.
--master-user-password

RDS API parameter:

MasterUserPassword

Master username The name that you use as the master user CLI option:
name to log on to your DB cluster with all
database privileges. --master-username

• It can contain 1–16 alphanumeric RDS API parameter:

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 Master
user account privileges (p. 1961).

Performance Enable Performance Insights to monitor CLI options:

Insights your DB cluster load so that you can
analyze and troubleshoot your database --enable-performance-insights
performance.
--no-enable-performance-insights
Choose a retention period to determine
how much rolling data history to keep. --performance-insights-retention-
The default of seven days is in the free period
tier. Long-term retention (two years) is
--performance-insights-kms-key-id
priced per vCPU per month.
RDS API parameters:
Choose a master key to use to protect the
key used to encrypt this database volume. EnablePerformanceInsights
Choose from the master keys in your
account, or enter the key from a different PerformanceInsightsRetentionPeriod
account.
PerformanceInsightsKMSKeyId
For more information, see Monitoring
DB load with Performance Insights on
Amazon RDS (p. 487).

75
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

Console setting Setting description CLI option and RDS API parameter

Provisioned IOPS The amount of Provisioned IOPS (input/ CLI option:

output operations per second) to be
initially allocated for the DB cluster. This --iops
setting is available only if Provisioned
IOPS (io1) is selected as the storage type. RDS API parameter:

For more information, see Provisioned Iops

IOPS SSD storage (p. 50).

Public access Publicly accessible to give the DB cluster CLI option:

a public IP address, meaning that it's
accessible outside the VPC. To be publicly --publicly-accessible
accessible, the DB cluster also has to be in
a public subnet in the VPC. --no-publicly-accessible

Not publicly accessible to make the DB RDS API parameter:

cluster accessible only from inside the
PubliclyAccessible
VPC.

For more information, see Hiding

a DB instance in a VPC from the
internet (p. 1977).

To connect to a DB cluster from outside

of its VPC, the DB cluster must be publicly
accessible. Also, access must be granted
using the inbound rules of the DB cluster's
security group, and other requirements
must be met. For more information,
see Can't connect to Amazon RDS DB
instance (p. 2005).

If your DB cluster 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. For more information, see
Internetwork traffic privacy (p. 1892).

Storage type The storage type for your DB cluster. CLI option:

For preview, only Provisioned IOPS (io1) --storage-type

storage is supported.
RDS API parameter:
For more information, see Amazon RDS
storage types (p. 48). StorageType

Subnet group A DB subnet group to associate with this CLI option:

DB cluster.
--db-subnet-group-name
For more information, see Working with
DB subnet groups (p. 1977). RDS API parameter:

DBSubnetGroupName

76
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

Console setting Setting description CLI option and RDS API parameter

Virtual Private A Amazon VPC to associate with this DB For the CLI and API, you specify the VPC
Cloud (VPC) cluster. security group IDs.

For more information, see Amazon

Virtual Private Cloud VPCs and Amazon
RDS (p. 1975).

VPC security The security groups to associate with the CLI option:
groups DB cluster.
--vpc-security-group-ids
For more information, see VPC security
groups (p. 1948). RDS API parameter:

VpcSecurityGroupIds

Settings that don't apply when creating Multi-AZ DB clusters

The following settings in the AWS CLI command create-db-cluster and the RDS API operation
CreateDBCluster don't apply to Multi-AZ DB clusters in the preview.

You also can't specify these settings for Multi-AZ DB clusters in the console.

AWS CLI setting RDS API setting

--availability-zones AvailabilityZones

--backtrack-window BacktrackWindow

--character-set-name CharacterSetName

--copy-tags-to-snapshot | --no-copy- CopyTagsToSnapshot

tags-to-snapshot

--domain Domain

--domain-iam-role-name DomainIAMRoleName

--enable-cloudwatch-logs-exports | -- EnableCloudwatchLogsExports
no-enable-cloudwatch-logs-exports

--enable-global-write-forwarding | -- EnableGlobalWriteForwarding
no-enable-global-write-forwarding

--enable-http-endpoint | --no-enable- EnableHttpEndpoint

http-endpoint

--enable-iam-database-authentication EnableIAMDatabaseAuthentication
| --no-enable-iam-database-
authentication

--global-cluster-identifier GlobalClusterIdentifier

--option-group-name OptionGroupName

--pre-signed-url PreSignedUrl

--replication-source-identifier ReplicationSourceIdentifier

77
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

AWS CLI setting RDS API setting

--scaling-configuration ScalingConfiguration

Managing connections for Multi-AZ DB clusters

A Multi-AZ DB cluster has three DB instances instead of a single DB instance. Each connection is handled
by a specific DB instance. When you connect to a Multi-AZ DB cluster, the host name and port that you
specify point to an intermediate handler called an endpoint. The Multi-AZ DB cluster uses the endpoint
mechanism to abstract these connections. Thus, you don't have to hardcode all the host names or write
your own logic for load-balancing and rerouting connections when some DB instances aren't available.

For certain tasks, different DB instances or groups of DB instances perform different roles. For example,
the writer DB instance handles all data definition language (DDL) and data manipulation language (DML)
statements.

Using endpoints, you can map each connection to the appropriate DB instance or group of DB instances
based on your use case. For example, to perform DDL and DML statements, you can connect to
whichever DB instance is the writer DB instance. To perform queries, you can connect to the reader
endpoint, with the Multi-AZ DB cluster automatically performing load-balancing among the reader DB
instances. For diagnosis or tuning, you can connect to a specific DB instance endpoint to examine details
about a specific DB instance.

For information about connecting to a DB instance, see Connecting to an Amazon RDS DB

instance (p. 215).

Topics
• Types of Multi-AZ DB cluster endpoints (p. 78)
• Viewing the endpoints for a Multi-AZ DB cluster (p. 79)
• Using the cluster endpoint (p. 79)
• Using the reader endpoint (p. 80)
• Using the instance endpoints (p. 80)
• How Multi-AZ DB endpoints work with high availability (p. 80)

Types of Multi-AZ DB cluster endpoints

An endpoint is represented by a unique identifier that contains a host address. The following types of
endpoints are available from a Multi-AZ DB cluster:

Cluster endpoint

A cluster endpoint (or writer endpoint) for a Multi-AZ DB cluster connects to the current writer DB
instance for that DB cluster. This endpoint is the only one that can perform write operations such as
DDL and DML statements. This endpoint can also perform read operations.

Each Multi-AZ DB cluster has one cluster endpoint and one writer DB instance.

You use the cluster endpoint for all write operations on the DB cluster, including inserts, updates,
deletes, and DDL changes. You can also use the cluster endpoint for read operations, such as queries.

The cluster endpoint provides failover support for read/write connections to the DB cluster. If the
current writer DB instance of a DB cluster fails, the Multi-AZ DB cluster automatically fails over to a
new writer DB instance. During a failover, the DB cluster continues to serve connection requests to
the cluster endpoint from the new writer DB instance, with minimal interruption of service.

The following example illustrates a cluster endpoint for a Multi-AZ DB cluster.

78
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

mydbcluster.cluster-123456789012.us-east-1.rds.amazonaws.com
Reader endpoint

A reader endpoint for a Multi-AZ DB cluster provides load-balancing support for read-only
connections to the DB cluster. Use the reader endpoint for read operations, such as queries. By
processing those statements on the reader DB instances, this endpoint reduces the overhead on the
writer DB instance. It also helps the cluster to scale the capacity to handle simultaneous SELECT
queries. Each Multi-AZ DB cluster has one reader endpoint.

The reader endpoint load-balances each connection request among the reader DB instances. When
you use the reader endpoint for a session, you can only perform read-only statements such as
SELECT in that session.

The following example illustrates a reader endpoint for a Multi-AZ DB cluster.

mydbcluster.cluster-ro-123456789012.us-east-1.rds.amazonaws.com
Instance endpoint

An instance endpoint connects to a specific DB instance within a Multi-AZ DB cluster. Each DB

instance in a DB cluster has its own unique instance endpoint. So there is one instance endpoint for
the current writer DB instance of the DB cluster, and there is one instance endpoint for each of the
reader DB instances in the DB cluster.

The instance endpoint provides direct control over connections to the DB cluster. This control can
help you address scenarios where using the cluster endpoint or reader endpoint might not be
appropriate. For example, your client application might require more fine-grained load balancing
based on workload type. In this case, you can configure multiple clients to connect to different
reader DB instances in a DB cluster to distribute read workloads.

The following example illustrates an instance endpoint for a DB instance in a Multi-AZ DB cluster.

mydbinstance.123456789012.us-east-1.rds.amazonaws.com

Viewing the endpoints for a Multi-AZ DB cluster

In the AWS Management Console, you see the cluster endpoint and the reader endpoint on the details
page for each Multi-AZ DB cluster. You see the instance endpoint in the details page for each DB
instance.

With the AWS CLI, you see the writer and reader endpoints in the output of the describe-db-clusters
command. For example, the following command shows the endpoint attributes for all clusters in your
current AWS Region.

aws rds describe-db-cluster-endpoints

With the Amazon RDS API, you retrieve the endpoints by calling the DescribeDBClusterEndpoints
function. The output also shows Amazon Aurora DB cluster endpoints, if any exist.

Using the cluster endpoint

Each Multi-AZ DB cluster has a single built-in cluster endpoint, whose name and other attributes are
managed by Amazon RDS. You can't create, delete, or modify this kind of endpoint.

You use the cluster endpoint when you administer your DB cluster, perform extract, transform, load (ETL)
operations, or develop and test applications. The cluster endpoint connects to the writer DB instance of
the cluster. The writer DB instance is the only DB instance where you can create tables and indexes, run
INSERT statements, and perform other DDL and DML operations.

79
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

The physical IP address pointed to by the cluster endpoint changes when the failover mechanism
promotes a new DB instance to be the writer DB instance for the cluster. If you use any form of
connection pooling or other multiplexing, be prepared to flush or reduce the time-to-live for any cached
DNS information. Doing so ensures that you don't try to establish a read/write connection to a DB
instance that became unavailable or is now read-only after a failover.

Using the reader endpoint

You use the reader endpoint for read-only connections to your Multi-AZ DB cluster. This endpoint uses a
load-balancing mechanism to help your cluster handle a query-intensive workload. The reader endpoint
is the endpoint that you supply to applications that do reporting or other read-only operations on the
cluster.

The reader endpoint load-balances connections to available reader DB instances in a Multi-AZ DB cluster.
It doesn't load-balance individual queries. If you want to load-balance each query to distribute the read
workload for a DB cluster, open a new connection to the reader endpoint for each query.

Each Multi-AZ cluster has a single built-in reader endpoint, whose name and other attributes are
managed by Amazon RDS. You can't create, delete, or modify this kind of endpoint.

Using the instance endpoints

Each DB instance in a Multi-AZ DB cluster has its own built-in instance endpoint, whose name and other
attributes are managed by Amazon RDS. You can't create, delete, or modify this kind of endpoint. With
a Multi-AZ DB cluster, you typically use the writer and reader endpoints more often than the instance
endpoints.

In day-to-day operations, the main way that you use instance endpoints is to diagnose capacity or
performance issues that affect one specific DB instance in a Multi-AZ DB cluster. While connected to a
specific DB instance, you can examine its status variables, metrics, and so on. Doing this can help you
determine what's happening for that DB instance that's different from what's happening for other DB
instances in the cluster.

How Multi-AZ DB endpoints work with high availability

For Multi-AZ DB clusters where high availability is important, use the writer endpoint for read/write or
general-purpose connections and the reader endpoint for read-only connections. The writer and reader
endpoints manage DB instance failover better than instance endpoints do. Unlike the instance endpoints,
the writer and reader endpoints automatically change which DB instance they connect to if a DB instance
in your cluster becomes unavailable.

If the writer DB instance of a DB cluster fails, Amazon RDS automatically fails over to a new writer DB
instance. It does so by promoting a reader DB instance to a new writer DB instance. If a failover occurs,
you can use the writer endpoint to reconnect to the newly promoted writer DB instance. Or you can
use the reader endpoint to reconnect to one of the reader DB instances in the DB cluster. During a
failover, the reader endpoint might direct connections to the new writer DB instance of a DB cluster for
a short time after a reader DB instance is promoted to the new writer DB instance. If you design your
own application logic to manage instance endpoint connections, you can manually or programmatically
discover the resulting set of available DB instances in the DB cluster.

Managing a Multi-AZ DB cluster with the AWS Management

Console
You can manage a Multi-AZ DB cluster with the console.

To manage a Multi-AZ DB cluster with the console

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

80
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

2. In the navigation pane, choose Databases, and then choose the Multi-AZ DB cluster that you want to
manage.

The following image shows a Multi-AZ DB cluster in the console.

The available actions in the Actions menu depend on whether the Multi-AZ DB cluster is selected or a DB
instance in the cluster is selected.

Choose the Multi-AZ DB cluster to view the cluster details and perform actions at the cluster level.

Choose a DB instance in a Multi-AZ DB cluster to view the DB instance details and perform actions at the
DB instance level.

81
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

Modifying a Multi-AZ DB cluster

A Multi-AZ DB cluster has a writer DB instance and two reader DB instances in three separate Availability
Zones. Multi-AZ DB clusters provide high availability, increased capacity for read workloads, and lower
latency when compared to Multi-AZ deployments. For more information about Multi-AZ DB clusters, see
Multi-AZ DB cluster deployments (preview) (p. 65).

You can modify a Multi-AZ DB cluster to change its settings. You can also perform operations on a Multi-
AZ DB cluster, such as taking a snapshot of it. However, you can't modify the DB instances in a Multi-AZ
DB cluster, and the only supported operation is rebooting a DB instance.
Note
Multi-AZ DB clusters are supported only for the MySQL and PostgreSQL DB engines.

You can modify a Multi-AZ DB cluster using the AWS Management Console, the AWS CLI, or the RDS API.

Console

To modify a Multi-AZ DB cluster

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 Multi-AZ DB cluster that you want to
modify.
3. Choose Modify. The Modify DB cluster page appears.
4. Change any of the settings that you want. For information about each setting, see Settings for
modifying Multi-AZ DB clusters (p. 83).
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 downtime in some cases. For more information, see Using the Apply Immediately
setting (p. 83).
7. On the confirmation page, review your changes. If they're correct, choose Modify DB cluster to save
your changes.

Or choose Back to edit your changes or Cancel to cancel your changes.

AWS CLI
To modify a Multi-AZ DB cluster by using the AWS CLI, call the modify-db-cluster command. Specify the
DB cluster identifier and the values for the options that you want to modify. For information about each
option, see Settings for modifying Multi-AZ DB clusters (p. 83).

Example
The following code modifies my-multi-az-dbcluster by setting the backup retention period to
1 week (7 days). The code turns on deletion protection by using --deletion-protection. To turn
off 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. 83).

For Linux, macOS, or Unix:

aws rds modify-db-cluster \

--db-instance-identifier my-multi-az-dbcluster \
--backup-retention-period 7 \
--deletion-protection \
--no-apply-immediately

82
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

For Windows:

aws rds modify-db-cluster ^

--db-instance-identifier my-multi-az-dbcluster ^
--backup-retention-period 7 ^
--deletion-protection ^
--no-apply-immediately

RDS API

To modify a Multi-AZ DB cluster by using the Amazon RDS API, call the ModifyDBCluster operation.
Specify the DB cluster identifier, and the parameters for the settings that you want to modify. For
information about each parameter, see Settings for modifying Multi-AZ DB clusters (p. 83).

Using the Apply Immediately setting

When you modify a Multi-AZ DB cluster, 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 option 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 the DB cluster to be temporarily unavailable
(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
modifying Multi-AZ DB clusters (p. 83).

Settings for modifying Multi-AZ DB clusters

For details about settings that you can use to modify a Multi-AZ DB cluster, see the following table. For
more information about the AWS CLI options, see modify-db-cluster. For more information about the
RDS API parameters, see ModifyDBCluster.

Console Setting description CLI option and RDS API When the change Downtime notes
setting parameter occurs

Allocated The amount of CLI option: If you choose to apply Downtime doesn't occur
storage storage to allocate the change immediately, during this change.
for each DB instance --allocated- it occurs immediately.
in your DB cluster (in storage
gibibytes). If you don't choose
API parameter: to apply the change
For more information, immediately, it occurs
see Amazon AllocatedStorage during the next
RDS DB instance maintenance window.
storage (p. 48).

83
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

Console Setting description CLI option and RDS API When the change Downtime notes
setting parameter occurs

Auto Enable auto minor CLI option: The change occurs Downtime doesn't occur
minor version upgrade to immediately. This during this change.
version have your DB cluster --auto-minor- setting ignores the
upgrade receive preferred version-upgrade apply immediately
minor DB engine setting.
version upgrades --no-auto-minor-
automatically version-upgrade
when they become
API parameter:
available. Amazon
RDS performs AutoMinorVersionUpgrade
automatic minor
version upgrades
in the maintenance
window.

Backup The number of CLI option: If you choose to apply Downtime occurs if
retention days that you want the change immediately, you change from 0 to a
period automatic backups --backup- it occurs immediately. nonzero value, or from a
of your DB cluster to retention-period nonzero value to 0.
be retained. For any If you don't choose
nontrivial DB cluster, API parameter: to apply the change
set this value to 1 or immediately, and you
BackupRetentionPeriodchange the setting
greater.
from a nonzero value
For more information, to another nonzero
see Working with value, the change is
backups (p. 388). applied asynchronously,
as soon as possible.
Otherwise, the change
occurs during the next
maintenance window.

Backup The time period CLI option: The change is applied Downtime doesn't occur
window during which Amazon asynchronously, as soon during this change.
RDS automatically --preferred- as possible.
takes a backup of backup-window
your DB cluster.
Unless you have a API parameter:
specific time that you
PreferredBackupWindow
want to have your
database backed up,
use the default of No
preference.

For more information,

see Working with
backups (p. 388).

84
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

Console Setting description CLI option and RDS API When the change Downtime notes
setting parameter occurs

Database For Multi-AZ None because password If you choose to apply Downtime doesn't occur
authentication
DB clusters, authentication is the the change immediately, during this change.
only Password default. it occurs immediately.
authentication is
supported. If you don't choose
to apply the change
immediately, it occurs
during the next
maintenance window.

DB The compute and CLI option: If you choose to apply Downtime occurs during
cluster memory capacity the change immediately, this change.
instance of each DB instance --db-cluster- it occurs immediately.
class in the Multi-AZ DB instance-class
cluster, for example If you don't choose
db.r6gd.xlarge. RDS API parameter: to apply the change
immediately, it occurs
If possible, choose DBClusterInstanceClass
during the next
a DB instance class maintenance window.
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 Supported DB
instance classes
for Multi-AZ DB
clusters (p. 66).

DB The DB cluster CLI option: The parameter An outage doesn't occur

cluster parameter group that group change occurs during this change.
parameter you want associated --db-cluster- immediately. When you change
group with the DB cluster. parameter-group- the parameter group,
name changes to some
For more information, parameters are applied
see Working with RDS API parameter: to the DB instances in
parameter groups the Multi-AZ DB cluster
for Multi-AZ DB DBClusterParameterGroupName
immediately without
clusters (p. 91). a reboot. Changes
to other parameters
are applied only after
the DB instances are
rebooted.

85
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

Console Setting description CLI option and RDS API When the change Downtime notes
setting parameter occurs

DB The version of CLI option: If you choose to apply An outage occurs during
engine database engine that the change immediately, this change.
version you want to use. --engine-version it occurs immediately.
RDS API parameter: If you don't choose
to apply the change
EngineVersion immediately, it occurs
during the next
maintenance window.

Deletion Enable deletion CLI option: The change occurs An outage doesn't occur
protection protection to prevent immediately. This during this change.
your DB cluster from --deletion- setting ignores the
being deleted. protection apply immediately
setting.
For more information, --no-deletion-
see Deleting a DB protection
instance (p. 384).
RDS API parameter:

DeletionProtection

Maintenance
The 30-minute CLI option: The change occurs If there are one or
window window in immediately. This more pending actions
which pending --preferred- setting ignores the that cause downtime,
modifications to maintenance-window apply immediately and the maintenance
your DB cluster setting. window is changed to
are applied. If the RDS API parameter: include the current time,
time period doesn't those pending actions
PreferredMaintenanceWindow
matter, choose No are applied immediately
preference. and downtime occurs.

For more information,

see The Amazon
RDS maintenance
window (p. 324).

New The password for CLI option: The change is applied Downtime doesn't occur
master your master user asynchronously, as during this change.
password account. --master-user- soon as possible. This
password setting ignores the
apply immediately
RDS API parameter: setting.
MasterUserPassword

86
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

Console Setting description CLI option and RDS API When the change Downtime notes
setting parameter occurs

ProvisionedThe amount of CLI option: If you choose to apply Downtime doesn't occur
IOPS Provisioned IOPS the change immediately, during this change.
(input/output --iops it occurs immediately.
operations per
second) to be initially RDS API parameter: If you don't choose
allocated for the DB to apply the change
Iops immediately, it occurs
cluster. This setting
is available only if during the next
Provisioned IOPS maintenance window.
(io1) is selected as
the storage type.

For more information,

see Provisioned IOPS
SSD storage (p. 50).

87
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

Console Setting description CLI option and RDS API When the change Downtime notes
setting parameter occurs

Public Publicly accessible CLI option: The change occurs An outage doesn't occur
access to give the DB cluster immediately. This during this change.
a public IP address, --publicly- setting ignores the
meaning that it's accessible apply immediately
accessible outside its setting.
virtual private cloud --no-publicly-
(VPC). To be publicly accessible
accessible, the DB
RDS API parameter:
cluster also has to be
in a public subnet in PubliclyAccessible
the VPC.

Not publicly
accessible to make
the DB cluster
accessible only from
inside the VPC.

For more information,

see Hiding a
DB instance in
a VPC from the
internet (p. 1977).

To connect to a DB
cluster from outside
of its VPC, the DB
cluster must be
publicly accessible.
Also, access must
be granted using
the inbound rules
of the DB cluster's
security group, and
other requirements
must be met. For
more information,
see Can't connect
to Amazon RDS DB
instance (p. 2005).

If your DB cluster 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. For more
information, see
Internetwork traffic
privacy (p. 1892).

88
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

Console Setting description CLI option and RDS API When the change Downtime notes
setting parameter occurs

Storage The storage type for CLI option: For the preview, you For the preview, you
type your DB cluster. can't change the storage can't change the storage
--storage-type type. type.
For preview, only
Provisioned IOPS (io1) RDS API parameter:
storage is supported.
StorageType
For more information,
see Amazon RDS
storage types (p. 48).

VPC The security groups CLI option: The change is applied An outage doesn't occur
security to associate with the asynchronously, as during this change.
group DB cluster. --vpc-security- soon as possible. This
group-ids setting ignores the
For more information, apply immediately
see VPC security RDS API parameter: setting.
groups (p. 1948).
VpcSecurityGroupIds

Settings that don't apply when modifying Multi-AZ DB clusters

The following settings in the AWS CLI command modify-db-cluster and the RDS API operation
ModifyDBCluster don't apply to Multi-AZ DB clusters in the preview.

You also can't modify these settings for Multi-AZ DB clusters in the console.

AWS CLI setting RDS API setting

--allow-major-version-upgrade|--no- AllowMajorVersionUpgrade
allow-major-version-upgrade

--backtrack-window BacktrackWindow

--cloudwatch-logs-export-configuration CloudwatchLogsExportConfiguration

--copy-tags-to-snapshot | --no-copy- CopyTagsToSnapshot

tags-to-snapshot

--db-instance-parameter-group-name DBInstanceParameterGroupName

--domain Domain

--domain-iam-role-name DomainIAMRoleName

--enable-global-write-forwarding | -- EnableGlobalWriteForwarding
no-enable-global-write-forwarding

--enable-http-endpoint | --no-enable- EnableHttpEndpoint

http-endpoint

--enable-iam-database-authentication EnableIAMDatabaseAuthentication
| --no-enable-iam-database-
authentication

--new-db-cluster-identifier NewDBClusterIdentifier

89
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

AWS CLI setting RDS API setting

--option-group-name OptionGroupName

--port Port

--scaling-configuration ScalingConfiguration

Rebooting Multi-AZ DB clusters and reader DB instances

You might need to reboot your Multi-AZ DB cluster, usually for maintenance reasons. For example, if
you make certain modifications, or if you change the DB cluster parameter group associated with the DB
cluster, you reboot the DB cluster for the changes to take effect.

If a DB cluster isn't using the latest changes to its associated DB cluster parameter group, the AWS
Management Console shows the DB cluster 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 cluster, manually reboot the DB
cluster. For more information about parameter groups, see Working with parameter groups for Multi-AZ
DB clusters (p. 91).

Rebooting a DB cluster restarts the database engine service. Rebooting a DB cluster results in a
momentary outage, during which the DB cluster status is set to rebooting.

You can't reboot your DB cluster if it isn't 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.
Important
When you reboot the writer instance of a Multi-AZ DB cluster, it doesn't affect the reader DB
instances in that DB cluster, and no failover occurs. When you reboot a reader DB instance, no
failover occurs. To fail over a Multi-AZ DB cluster, choose Failover in the console, call the AWS
CLI command failover-db-cluster, or call the API operation FailoverDBCluster.

The time required to reboot your DB cluster depends on the crash recovery process, database activity
at the time of reboot, and the behavior of your specific DB cluster. 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.

Multi-AZ DB clusters don't support reboot with a failover.

Console

To reboot a DB cluster

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 Multi-AZ DB cluster that you want to
reboot.
3. For Actions, choose Reboot.

The Reboot DB cluster page appears.

4. Choose Reboot to reboot your DB cluster.

Or choose Cancel.

90
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

AWS CLI

To reboot a Multi-AZ DB cluster by using the AWS CLI, call the reboot-db-cluster command.

aws rds reboot-db-cluster --db-cluster-identifier mymultiazdbcluster

RDS API

To reboot a Multi-AZ DB cluster by using the Amazon RDS API, call the RebootDBCluster operation.

Working with parameter groups for Multi-AZ DB clusters

In a Multi-AZ DB cluster, a DB cluster parameter group acts as a container for engine configuration values
that are applied to every DB instance in the Multi-AZ DB cluster. The DB cluster parameter group also
includes default values for all the instance-level parameters.

In a Multi-AZ DB cluster, a DB parameter group is set to the default DB parameter group for the DB
engine and DB engine version. The settings in the DB cluster parameter group are used for all of the DB
instances in the cluster.

For information about parameter groups, see Working with DB parameter groups (p. 284).

Failover process for Multi-AZ DB clusters

If a planned or unplanned outage of your writer DB instance in a Multi-AZ DB cluster results from
an infrastructure defect, Amazon RDS automatically switches to a reader DB instance in another
Availability Zone. The time it takes for the failover to complete depends on the database activity and
other conditions when the writer DB instance became unavailable. Failover times are typically 20–40
seconds. Failover completes when both reader DB instances have applied outstanding transactions from
the failed writer. When the failover is complete, it can take additional time for the RDS console to reflect
the new Availability Zone.

Topics
• Automatic failovers (p. 91)
• Manually failing over a Multi-AZ DB cluster (p. 91)
• Determining whether a Multi-AZ DB cluster has failed over (p. 92)
• Setting the JVM TTL for DNS name lookups (p. 92)

Automatic failovers
Amazon RDS handles failovers automatically so you can resume database operations as quickly as
possible without administrative intervention. To fail over, the writer DB instance switches automatically
to a reader DB instance.

Manually failing over a Multi-AZ DB cluster

You can fail over a Multi-AZ DB cluster manually using the AWS Management Console, the AWS CLI, or
the RDS API.

Console

To fail over a Multi-AZ DB cluster manually

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

91
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

2. In the navigation pane, choose Databases.

3. Choose the Multi-AZ DB cluster that you want to fail over.
4. For Actions, choose Failover.

The Failover DB Cluster page appears.

5. Choose Failover to confirm the manual failover.

AWS CLI

To fail over a Multi-AZ DB cluster manually, use the AWS CLI command failover-db-cluster.

Example

aws rds failover-db-cluster --db-cluster-identifier mymultiazdbcluster

RDS API

To fail over a Multi-AZ DB cluster manually, call the Amazon RDS API FailoverDBCluster and specify the
DBClusterIdentifier.

Determining whether a Multi-AZ DB cluster has failed over

To determine if your Multi-AZ DB cluster has failed over, you can do the following:

• Set up DB event subscriptions 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. 571).
• View your DB events by using the Amazon RDS console or API operations.
• View the current state of your Multi-AZ DB cluster by using the Amazon RDS console, the AWS CLI, and
the RDS API.

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

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 reader 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 host name 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.

92
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

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");

Creating a Multi-AZ DB cluster snapshot

When you create a Multi-AZ DB cluster snapshot, make sure to identify which Multi-AZ DB cluster you are
going to back up, and then give your DB cluster snapshot a name so you can restore from it later.

You can create a Multi-AZ DB cluster snapshot using the AWS Management Console, the AWS CLI, or the
RDS API.

Console

To create a DB cluster 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, choose the Multi-AZ DB cluster for which you want to take a snapshot.
4. For Actions, choose Take snapshot.

The Take DB snapshot window appears.

5. For Snapshot name, enter the name of the snapshot.
6. Choose Take snapshot.

The Snapshots page appears, with the new Multi-AZ DB cluster snapshot's status shown as Creating.
After its status is Available, you can see its creation time.

AWS CLI

You can create a Multi-AZ DB cluster snapshot by using the AWS CLI create-db-cluster-snapshot
command with the following options:

• --db-cluster-identifier

93
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

• --db-cluster-snapshot-identifier

In this example, you create a Multi-AZ DB cluster snapshot called mymultiazdbclustersnapshot for a
DB cluster called mymultiazdbcluster.

Example

For Linux, macOS, or Unix:

aws rds create-db-cluster-snapshot \

--db-cluster-identifier mymultiazdbcluster \
--db-cluster-snapshot-identifier mymultiazdbclustersnapshot

For Windows:

aws rds create-db-cluster-snapshot ^

--db-cluster-identifier mymultiazdbcluster ^
--db-cluster snapshot-identifier mymultiazdbclustersnapshot

RDS API

You can create a Multi-AZ DB cluster snapshot by using the Amazon RDS API CreateDBClusterSnapshot
operation with the following parameters:

• DBClusterIdentifier
• DBClusterSnapshotIdentifier

Restoring from a snapshot to a Multi-AZ DB cluster

You can restore a snapshot to a Multi-AZ DB cluster using the AWS Management Console, the AWS CLI,
or the RDS API. You can restore each of these types of snapshots to a Multi-AZ DB cluster:

• A snapshot of a single-AZ deployment

• A snapshot of a Multi-AZ DB instance deployment with a single DB instance
• A snapshot of a Multi-AZ DB cluster

Tip
You can migrate a single-AZ deployment or a Multi-AZ DB instance deployment to a Multi-AZ
DB cluster deployment by restoring a snapshot.

Console

To restore a snapshot to a Multi-AZ DB cluster

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 snapshot that you want to restore from.
4. For Actions, choose Restore snapshot.
5. On the Restore snapshot page, in Availability and durability, choose Multi-AZ DB cluster -
preview.

94
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

6. In DB instance class, choose a DB instance class.

For more information, see Supported DB instance classes for Multi-AZ DB clusters (p. 66).
7. For DB cluster identifier, enter the name for your restored Multi-AZ DB cluster.
8. For the remaining sections, specify your DB cluster settings. For information about each setting, see
Settings for creating Multi-AZ DB clusters (p. 71).
9. Choose Restore DB instance.

AWS CLI

To restore a snapshot to a Multi-AZ DB cluster, use the AWS CLI command restore-db-cluster-from-
snapshot.

In this example, you restore from a previously created snapshot named mysnapshot. You restore to a
new Multi-AZ DB cluster named mynewmultiazdbcluster. You also specify the DB instance class used
by the DB instances in the Multi-AZ DB cluster. Specify either mysql or postgres for the DB engine.

Example

For Linux, macOS, or Unix:

aws rds restore-db-cluster-from-snapshot \

--db-cluster-identifier mynewmultiazdbcluster \
--snapshot-identifier mysnapshot \
--engine mysql|postgres \
--db-cluster-instance-class db.r6gd.xlarge

For Windows:

aws rds restore-db-cluster-from-snapshot ^

--db-cluster-identifier mynewmultiazdbcluster ^
--snapshot-identifier mysnapshot ^
--engine mysql|postgres ^

95
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

--db-cluster-instance-class db.r6gd.xlarge

After the DB cluster has been restored, make sure to add the Multi-AZ DB cluster to the security
group used by the DB cluster or DB instance used to create the snapshot. Doing so provides the same
functionality as that of the previous DB cluster or DB instance.

RDS API

To restore a snapshot to a Multi-AZ DB cluster, call the RDS API operation

RestoreDBClusterFromSnapshot with the following parameters:

• DBClusterIdentifier
• SnapshotIdentifier
• Engine

You can also specify other optional parameters.

After the DB cluster has been restored, make sure to add the Multi-AZ DB cluster to the security
group used by the DB cluster or DB instance used to create the snapshot. Doing so provides the same
functionality as that of the previous DB cluster or DB instance.

Restoring a Multi-AZ DB cluster to a specified time

When you restore a Multi-AZ DB cluster to a point in time, you can choose the default VPC security group
or apply a custom VPC security group to your Multi-AZ DB cluster.

Restored Multi-AZ DB clusters are automatically associated with the default DB cluster parameter group.
However, you can apply a customer DB cluster parameter group by specifying it during a restore.

RDS uploads transaction logs for Multi-AZ DB clusters to Amazon S3 continuously. To see the latest
restorable time for a Multi-AZ DB cluster, use the AWS CLI describe-db-clusters command. Look at the
value returned in the LatestRestorableTime field for the DB cluster.

You can restore to any point in time within your backup retention period. To see the earliest restorable
time for a Multi-AZ DB cluster, use the AWS CLI describe-db-clusters command. Look at the value
returned in the EarliestRestorableTime field for the DB cluster.
Note
We recommend that you restore to the same or similar Multi-AZ DB cluster size—and IOPS if
using Provisioned IOPS storage—as the source DB cluster. You might get an error if, for example,
you choose a DB cluster size with an incompatible IOPS value.

You can restore a Multi-AZ DB cluster to a point in time using the AWS Management Console, the AWS
CLI, or the RDS API.

Console

To restore a Multi-AZ DB cluster 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 Databases.
3. Choose the Multi-AZ DB cluster that you want to restore.
4. For Actions, choose Restore to point in time.

The Restore to point in time window appears.

96
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

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 Multi-AZ DB cluster.
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 cluster identifier, enter the name for your restored Multi-AZ DB cluster.
7. In Availability and durability, choose Multi-AZ DB cluster - preview.

8. In DB instance class, choose a DB instance class.

For more information, see Supported DB instance classes for Multi-AZ DB clusters (p. 66).
9. For the remaining sections, specify your DB cluster settings. For information about each setting, see
Settings for creating Multi-AZ DB clusters (p. 71).
10. Choose Restore to point in time.

AWS CLI

To restore a Multi-AZ DB cluster to a specified time, use the AWS CLI command restore-db-cluster-to-
point-in-time to create a new Multi-AZ DB cluster.

Example

For Linux, macOS, or Unix:

aws rds restore-db-cluster-to-point-in-time \

--source-db-cluster-identifier mysourcemultiazdbcluster \
--db-cluster-identifier mytargetmultiazdbcluster \
--restore-to-time 2021-08-14T23:45:00.000Z \
--db-cluster-instance-class db.r6gd.xlarge

For Windows:

97
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

aws rds restore-db-cluster-to-point-in-time ^

--source-db-cluster-identifier mysourcemultiazdbcluster ^
--db-cluster-identifier mytargetmultiazdbcluster ^
--restore-to-time 2021-08-14T23:45:00.000Z ^
--db-cluster-instance-class db.r6gd.xlarge

RDS API

To restore a DB cluster to a specified time, call the Amazon RDS API RestoreDBClusterToPointInTime
operation with the following parameters:

• SourceDBClusterIdentifier
• DBClusterIdentifier
• RestoreToTime

Deleting a Multi-AZ DB cluster

You can delete a DB Multi-AZ DB cluster using the AWS Management Console, the AWS CLI, or the RDS
API.

The time required to delete a Multi-AZ DB cluster 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.

You can't delete a Multi-AZ DB cluster when deletion protection is turned on for it. For more information,
see Deletion protection (p. 384). You can turn off deletion protection by modifying the Multi-AZ DB
cluster. For more information, see Modifying a Multi-AZ DB cluster (p. 82).

Console

To delete a Multi-AZ DB cluster

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 Multi-AZ DB cluster that you want to
delete.
3. For Actions, choose Delete.
4. Choose Create final snapshot? to create a final DB snapshot for the Multi-AZ DB cluster.

If you create a final snapshot, enter a name for Final snapshot name.
5. Choose Retain automated backups to retain automated backups.
6. Enter delete me in the box.
7. Choose Delete.

AWS CLI

To delete a Multi-AZ DB cluster by using the AWS CLI, call the delete-db-cluster command with the
following options:

• --db-cluster-identifier
• --final-db-snapshot-identifier or --skip-final-snapshot

Example With a final snapshot

For Linux, macOS, or Unix:

98
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

aws rds delete-db-cluster \

--db-cluster-identifier mymultiazdbcluster \
--final-db-snapshot-identifier mymultiazdbclusterfinalsnapshot

For Windows:

aws rds delete-db-instance ^

--db-cluster-identifier mymultiazdbcluster ^
--final-db-snapshot-identifier mymultiazdbclusterfinalsnapshot

Example With no final snapshot

For Linux, macOS, or Unix:

aws rds delete-db-instance \

--db-cluster-identifier mymultiazdbcluster \
--skip-final-snapshot

For Windows:

aws rds delete-db-instance ^

--db-cluster-identifier mymultiazdbcluster ^
--skip-final-snapshot

RDS API

To delete a Multi-AZ DB cluster by using the Amazon RDS API, call the DeleteDBCluster operation with
the following parameters:

• DBClusterIdentifier
• FinalDBSnapshotIdentifier or SkipFinalSnapshot

Limitations for Multi-AZ DB clusters

The following limitations apply to the Multi-AZ DB cluster preview:

• You can create a Multi-AZ DB cluster only with MySQL version 8.0.26 and PostgreSQL version 13.4.
• You can create Multi-AZ DB clusters only in the following AWS Regions:
• US East (N. Virginia)
• US West (Oregon)
• Europe (Ireland)
• Multi-AZ DB clusters must use Provisioned IOPS storage.
• You can't change a single-AZ DB instance deployment or Multi-AZ DB instance deployment into a
Multi-AZ DB cluster. However, you can restore a snapshot of a single-AZ DB instance deployment or
Multi-AZ DB instance deployment to a Multi-AZ DB cluster.
• You can't restore a Multi-AZ DB cluster snapshot to a Multi-AZ DB instance deployment or single-AZ
deployment.
• You can't stop, start, or rename a DB instance in a Multi-AZ DB cluster.
• You can't use tags with a Multi-AZ DB cluster or with the DB instances in a Multi-AZ DB cluster.
• You can't use option groups with a Multi-AZ DB cluster or with the DB instances in a Multi-AZ DB
cluster.
• You can't publish logs to CloudWatch Logs.

99
 Amazon Relational Database Service User Guide
Multi-AZ DB cluster deployments (preview)

• You can't create read replicas for a Multi-AZ DB cluster.

• You can't use IAM DB authentication with a Multi-AZ DB cluster.
• You can't use Kerberos authentication with a Multi-AZ DB cluster.
• You can't use AWS Backup with a Multi-AZ DB cluster.
• You can't modify the port used by a Multi-AZ DB cluster. However, you can restore a Multi-AZ DB
cluster to a point in time and specify a different port.
• Storage autoscaling by setting the maximum allocated storage isn't supported. However, you can scale
storage manually.
• You can't use reserved DB instances with a Multi-AZ DB cluster.
• You can't use Amazon RDS Proxy with a Multi-AZ DB cluster.
• You can't restore a Multi-AZ DB cluster snapshot from an Amazon S3 bucket.
• You can't export Multi-AZ DB cluster snapshot data to an Amazon S3 bucket.
• For RDS for MySQL Multi-AZ DB clusters, you can't change the MySQL system database.
• For RDS for MySQL Multi-AZ DB clusters, external replication isn't supported.
• For RDS for MySQL Multi-AZ DB clusters, you can't use the stored procedures described in MySQL on
Amazon RDS SQL reference (p. 1127).
• For RDS for PostgreSQL Multi-AZ DB clusters, you can't use PostgreSQL extensions or parameters
related to extensions.
• For RDS for PostgreSQL Multi-AZ DB clusters, you can't use a custom DNS server for outbound
network access.
• For RDS for PostgreSQL Multi-AZ DB clusters, you can't use logical replication.

100
 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. 10).
• 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 prorated. For more information,
see Amazon RDS DB instance storage (p. 48).
• 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. 387).
• 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. 102)
• Reserved DB instances for Amazon RDS (p. 103)

101
 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 Viewing DB instance status (p. 470).

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.

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

You can modify a reserved DB instance. If the modification is within the specifications of the reserved
DB instance, part or all of the discount still applies to the modified DB instance. If the modification is
outside the specifications, such as changing the instance class, the discount no longer applies. For more
information, see Size-flexible reserved DB instances (p. 104).

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.

103
 Amazon Relational Database Service User Guide
Reserved DB instances

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

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

104
 Amazon Relational Database Service User Guide
Reserved DB instances

Instance size Single-AZ normalized units Multi-AZ normalized units

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.

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)

105
 Amazon Relational Database Service User Guide
Reserved DB instances

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. You save a little over $11 per month by using the reserved DB instance.

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.

You're billed for the upfront costs regardless of whether you use the resources.

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.

106
 Amazon Relational Database Service User Guide
Reserved DB instances

To purchase a reserved DB instance

1. Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.
2. In the navigation pane, choose Reserved instances.
3. Choose Purchase Reserved DB Instance.
4. For Product description, choose the DB engine and licensing type.
5. For DB instance class, choose the DB instance class.
6. For Multi-AZ deployment, choose whether you want a Multi-AZ deployment.
7. For Term, choose the length of time you want the DB instance reserved.
8. For Offering type, choose the offering type.

After you choose the offering type, you can see the pricing information.

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.

107
 Amazon Relational Database Service User Guide
Reserved DB instances

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.

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.

108
 Amazon Relational Database Service User Guide
Reserved DB instances

AWS CLI
You can use the AWS CLI to work with reserved DB instances as shown in the following examples.

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

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

Viewing the billing for your reserved DB instances

You can view the billing for your reserved DB instances in the Billing Dashboard in the AWS Management
Console.

To view reserved DB instance billing

1. Sign in to the AWS Management Console.

2. From the account menu at the upper right, choose Billing Dashboard.
3. Choose Bill Details at the upper right of the dashboard.
4. Under AWS Service Charges, expand Relational Database Service.
5. Expand the AWS Region where your reserved DB instances are, for example US West (Oregon).

Your reserved DB instances and their hourly charges for the current month are shown under Amazon
Relational Database Service for Database Engine Reserved Instances.

110
 Amazon Relational Database Service User Guide
Reserved DB instances

The reserved DB instance in this example was purchased All Upfront, so there are no hourly charges.
6. Choose the Cost Explorer (bar graph) icon next to the Reserved Instances heading.

The Cost Explorer displays the Monthly EC2 running hours costs and usage graph.
7. Clear the Usage Type Group filter to the right of the graph.
8. Choose the time period and time unit for which you want to examine usage costs.

The following example shows usage costs for on-demand and reserved DB instances for the year to
date by month.

The reserved DB instance costs from January through June 2021 are monthly charges for a Partial
Upfront instance, while the cost in August 2021 is a one-time charge for an All Upfront instance.

The reserved instance discount for the Partial Upfront instance expired in June 2021, but the DB
instance wasn't deleted. After the expiration date, it was simply charged at the on-demand rate.

111
 Amazon Relational Database Service User Guide
Sign up for AWS

Setting up for Amazon RDS

Before you use Amazon Relational Database Service for the first time, complete the following tasks:

1. Sign up for AWS (p. 112)

2. Create an IAM user (p. 112)
3. Determine requirements (p. 114)
4. Provide access to your DB instance in your VPC by creating a security group (p. 115)

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 with Amazon RDS (p. 118).

Sign up for AWS

When you sign up for AWS, your AWS account is automatically signed up for all services in AWS,
including Amazon RDS. You are charged only for the services that you use.

With Amazon RDS, you pay only for the resources you use. The Amazon RDS DB instances that you
create are live (not running in a sandbox). You incur the standard Amazon RDS usage fees for each DB
instance until you terminate it. For more information about Amazon RDS usage rates, see the Amazon
RDS product page. If you are a new AWS customer, you can get started with Amazon RDS for free; for
more information, see AWS free tier.

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

If you don't have an AWS account, you can use the following procedure to create one.

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.

Note your AWS account number, because you'll need it for the next task.

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.

112
 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 that follows 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.

113
 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, updating, and uninstalling 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. 10).
• VPC, subnet, and security group – Your DB instance will most likely be 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 or in a user-
defined VPC.

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:
• Make sure to create a VPC security group that authorizes connections from the application or
service to the Amazon RDS DB instance. Use the Security Group option on the VPC console or
the AWS CLI to create VPC security groups. For information, see Step 4: Create a VPC security
group (p. 1982).
• 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. Use the Security Group option on the VPC console or
the AWS CLI to create VPC security groups. For information, see Step 4: Create a VPC security
group (p. 1982).
• 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. 1975).
• 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. 1976).

114
 Amazon Relational Database Service User Guide
Provide access to your DB instance

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
more information, see Determining whether you are using the EC2-VPC or EC2-Classic
platform (p. 1994).
• 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 Multi-AZ deployments for high availability (p. 59).
• 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. 1893).
• 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. For more information, see
Regions, Availability Zones, and Local Zones (p. 55).
• 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. 48).

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 DB 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 a security group that enable you
to connect. Use your network and configuration information to create rules to allow access to your DB
instance.

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.

115
 Amazon Relational Database Service User Guide
Provide access to your DB instance

For information about common scenarios for accessing a DB instance, see Scenarios for accessing a DB
instance in a VPC (p. 1982).

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.
Note
Make sure you are in the VPC console, not the RDS console.
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.

The Create security group page appears.

5. In Basic details, enter the Security group name and Description. For VPC, choose the VPC that you
want to create your DB instance in.
6. In Inbound rules, choose Add rule.

a. For Type, choose Custom TCP.

b. For Port range, enter 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 DB instance. If you choose My IP, this allows access to the DB instance from the
IP address detected in your browser.
7. If you need to add more IP addresses or different port ranges, choose Add rule and enter the
information for the rule.
8. (Optional) In Outbound rules, add rules for outbound traffic. By default, all outbound traffic is
allowed.
9. Choose Create security group.

You can use the VPC security group that you just created as the security group for your DB instance when
you create it.
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 create a DB instance using your requirements
and security group by following the instructions in Creating an Amazon RDS DB instance (p. 194).
For information about getting started by creating a DB instance that uses a specific DB engine, 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. 118)

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

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

instance (p. 135)

116
 Amazon Relational Database Service User Guide
Provide access to your DB instance

Database engine Documentation

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

DB instance (p. 143)

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

PostgreSQL DB instance (p. 149)

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

117
 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, make sure to complete the tasks in Setting
up for Amazon RDS (p. 112).

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. 118)
• Creating a Microsoft SQL Server DB instance and connecting to it (p. 126)
• Creating a MySQL DB instance and connecting to a database on a MySQL DB instance (p. 135)
• Creating an Oracle DB instance and connecting to a database on an Oracle DB instance (p. 143)
• Creating a PostgreSQL DB instance and connecting to a database on a PostgreSQL DB
instance (p. 149)
• Tutorial: Create a web server and an Amazon RDS DB instance (p. 160)

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 AWS Management Console. After you
create the DB instance, you can use command line tools such as mysql or 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, make sure to complete the tasks in Setting
up for Amazon RDS (p. 112).

Topics
• Creating a MariaDB DB instance (p. 118)
• Connecting to a database on a DB instance running the MariaDB database engine (p. 122)
• Deleting a DB instance (p. 125)

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.

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

You can use Easy create to create a DB instance running MariaDB with the AWS Management Console.
With Easy create, you specify only the DB engine type, DB instance size, and DB instance identifier. Easy
create uses the default settings for the other configuration options. When you use Standard create
instead of Easy create, 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 Standard create, see Creating an Amazon RDS
DB instance (p. 194).

To create a MariaDB 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 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.

119
 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 box is selected.

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

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

You can examine the default settings used with Easy create. The Editable after database is created
column shows which options you can change after database creation.

• To change settings with No in that column, use Standard create.

• To change settings with Yes in that column, either use Standard create, or modify the DB instance
after it is created to change the settings.

The following are important considerations for changing the default settings:

• In some cases, you might want your DB instance to use a specific virtual private cloud (VPC) based
on the Amazon VPC service. Or you might require a specific subnet group or security group. If so,
use Standard create to specify these resources. You might have created these resources when you
set up for Amazon RDS. For more information, see Provide access to your DB instance in your VPC
by creating a security group (p. 115).

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

• If you want to be able to access the DB instance from a client outside of its VPC, use Standard
create to set Public access to Yes.

If the DB instance should be private, leave Public access set to No.

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

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. 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. Install a SQL client that you can use to connect to the DB instance.

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

You can connect to an Amazon RDS for MariaDB DB instance by using tools like the mysql command-
line client. For more information on using the mysql command-line client, see mysql command-
line client in the MariaDB documentation. One GUI-based application that you can use to connect
is Heidi. For more information, see the Download HeidiSQL page. For information about installing
MySQL (including the mysql command-line client), see Installing and upgrading MySQL.
2. Make sure that your DB instance is associated with a security group that provides access to it.
For more information, see Provide access to your DB instance in your VPC by creating a security
group (p. 115).

If you didn't specify the appropriate security group when you created the DB instance, you can
modify the DB instance to change its security group. For more information, see Modifying an
Amazon RDS DB instance (p. 306).
3. 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.

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

4. 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>.
In addition, substitute the master user name that you used for <mymasteruser> and provide the
master password that 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 MariaDB monitor. Commands end with ; or \g.

Your MariaDB connection id is 31

124
 Amazon Relational Database Service User Guide
Deleting a DB instance

Server version: 10.5.8-MariaDB-log Source distribution

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MariaDB [(none)]>

For more information about connecting to a MariaDB DB instance, see Connecting to a DB instance
running the MariaDB database engine (p. 756). If you can't connect to your DB instance, see Can't
connect to Amazon RDS DB instance (p. 2005).

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.

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

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 use Easy create to create a DB instance running Microsoft SQL Server with the AWS
Management Console. With Easy create, you specify only the DB engine type, DB instance size, and DB
instance identifier. Easy create uses the default settings for the other configuration options. When you
use Standard create instead of Easy create, 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 Microsoft SQL Server database
engine 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. 194).

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 and make sure that Easy create is chosen.

5. From Engine type, choose Microsoft SQL Server.

6. For DB instance size, choose Free tier.
7. For DB instance identifier, enter sample-instance, or leave the default name.

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

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

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

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

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

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

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

You can examine the default settings used with Easy create. The Editable after database is created
column shows which options you can change after database creation.

• To change settings with No in that column, use Standard create.

• To change settings with Yes in that column, either use Standard create, or modify the DB instance
after it is created to change the settings.

The following are important considerations for changing the default settings:

• In some cases, you might want your DB instance to use a specific virtual private cloud (VPC) based
on the Amazon VPC service. Or you might require a specific subnet group or security group. If so,
use Standard create to specify these resources. You might have created these resources when you
set up for Amazon RDS. For more information, see Provide access to your DB instance in your VPC
by creating a security group (p. 115).

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

• If you want to be able to access the DB instance from a client outside of its VPC;, use Standard
create to set Public access to Yes.

If the DB instance should be private, leave Public access set to No.

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

Connecting to your sample SQL Server DB instance

In the following 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 shows Available. The status updates without requiring you to refresh the page.
This process can take up to 20 minutes.

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

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

To connect to a DB instance using SSMS

1. Make sure that your DB instance is associated with a security group that provides access to it.
For more information, see Provide access to your DB instance in your VPC by creating a security
group (p. 115).

If you didn't specify the appropriate security group when you created the DB instance, you can
modify the DB instance to change its security group. For more information, see Modifying an
Amazon RDS DB instance (p. 306).
2. 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.123456789012.us-east-2.rds.amazonaws.com.
Also, note the port number. The default port for SQL Server is 1433. If yours is different, write it
down.

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

3. Start SQL Server Management Studio.

The Connect to Server dialog box appears.

4. Provide the following 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.

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

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

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

For more information about connecting to a Microsoft SQL Server DB instance, see Connecting to a DB
instance running the Microsoft SQL Server database engine (p. 824). For information on connection
issues, see Can't connect to Amazon RDS DB instance (p. 2005).

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.

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

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

b. Enter the following SQL query.

select @@VERSION

c. Run the query. SSMS returns the SQL Server version of your Amazon RDS 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:

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

• Select 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.
• Enter "delete me" into the box To confirm deletion, type delete me into the field.
• Choose Delete. This action can't be undone.

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, make sure to complete the tasks in Setting
up for Amazon RDS (p. 112).

Topics
• Creating a MySQL DB instance (p. 135)
• Connecting to a database on a DB instance running the MySQL database engine (p. 139)
• Deleting a DB instance (p. 142)

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.

You can use Easy create to create a DB instance running MySQL with the AWS Management Console.
With Easy create, you specify only the DB engine type, DB instance size, and DB instance identifier. Easy
create uses the default settings for the other configuration options. When you use Standard create
instead of Easy create, 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 Standard create, see Creating an Amazon RDS
DB instance (p. 194).

To create a MySQL 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 and make sure that Easy create is chosen.

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

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

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

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

To enter your master password, clear the Auto generate a password 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 with Easy create. The Editable after database is created
column shows which options you can change after database creation.

• To change settings with No in that column, use Standard create.

• To change settings with Yes in that column, either use Standard create, or modify the DB instance
after it is created to change the settings.

The following are important considerations for changing the default settings:

• In some cases, you might want your DB instance to use a specific virtual private cloud (VPC) based
on the Amazon VPC service. Or you might require a specific subnet group or security group. If so,

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

use Standard create to specify these resources. You might have created these resources when you
set up for Amazon RDS. For more information, see Provide access to your DB instance in your VPC
by creating a security group (p. 115).
• If you want to be able to access the DB instance from a client outside of its VPC, use Standard
create to set Public access to Yes.

If the DB instance should be private, leave Public access set to No.

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.

You can use the user name and password that appears to connect to the DB instance as the master
user.
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. 306).
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 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.

To connect to a database on a DB instance using MySQL monitor

1. Install a SQL client that you can use to connect to the DB instance.

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

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, seemysql - the MySQL command-line client in
the MySQL documentation. One GUI-based application that you can use to connect is MySQL
Workbench. For more information, see the Download MySQL Workbench page.

For more information on using MySQL, see the MySQL documentation. For information about
installing MySQL (including the MySQL client), see Installing and upgrading MySQL.

If your DB instance is publicly accessible, you can install the SQL client outside of your VPC. If your
DB instance is private, you typically install the SQL client on a resource inside your VPC, such as an
Amazon EC2 instance.
2. Make sure that your DB instance is associated with a security group that provides access to it.
For more information, see Provide access to your DB instance in your VPC by creating a security
group (p. 115).

If you didn't specify the appropriate security group when you created the DB instance, you can
modify the DB instance to change its security group. For more information, see Modifying an
Amazon RDS DB instance (p. 306).
3. 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.

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

4. 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>. In addition,
substitute the master user name that you used for <mymasteruser>, and provide the master
password that 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.

141
 Amazon Relational Database Service User Guide
Deleting a DB instance

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>

For more information about connecting to a MySQL DB instance, see Connecting to a DB instance
running the MySQL database engine (p. 1012). If you can't connect to your DB instance, see Can't
connect to Amazon RDS DB instance (p. 2005).

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.

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

There's no charge for creating an AWS account. However, by completing this tutorial, you might incur
costs for the AWS resources that you use. You can delete these resources after you complete the tutorial
if they are no longer needed.

In this topic, you create a sample Oracle DB instance and connect to it. Finally, you delete the sample DB
instance.

Creating a sample Oracle DB instance

The DB instance is where you run your Oracle databases.
Note
RDS for Oracle supports a single-tenant architecture, where a pluggable database (PDB)
resides in a multitenant container database (CDB). For more information, see RDS for Oracle
architecture (p. 1173).

You can use Easy create to create a DB instance running Oracle with the AWS Management Console.
With Easy create, you specify only the DB engine type, DB instance size, and DB instance identifier. Easy
create uses the default settings for the other configuration options. When you use Standard create
instead of Easy create, 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 Oracle database engine with a
db.m4.large DB instance class.

For information about creating DB instances with Standard create, see Creating an Amazon RDS DB
instance (p. 194). If you want to use free tier, use Standard create.

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.

143
 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 of
database-1.
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.

144
 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 box is selected.

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

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

You can examine the default settings used with Easy create. The Editable after database is created
column shows which options you can change after database creation.

• To change settings with No in that column, use Standard create.

• To change settings with Yes in that column, either use Standard create, or modify the DB instance
after it is created to change the settings.

The following are important considerations for changing the default settings:

• In some cases, you might want your DB instance to use a specific virtual private cloud (VPC) based
on the Amazon VPC service. Or you might require a specific subnet group or security group. If so,
use Standard create to specify these resources. You might have created these resources when you
set up for Amazon RDS. For more information, see Provide access to your DB instance in your VPC
by creating a security group (p. 115).

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

• If you want to be able to access the DB instance from a client outside of its VPC, use Standard
create to set Public access to Yes.

If the DB instance should be private, leave Public access set to No.

• If you want to use free tier, use Standard create to set the Oracle version lower than version 12.2,
and then choose Free tier in Templates.
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. 306).
12. For Databases, choose the name of the new Oracle 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 standalone version of this utility, see SQL*Plus User's
Guide and Reference.

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

To connect to a DB instance using SQL*Plus

1. Make sure your DB instance is associated with a security group that provides access to it. For more
information, see Provide access to your DB instance in your VPC by creating a security group (p. 115).

If you didn't specify the appropriate security group when you created the DB instance, you can
modify the DB instance to change its security group. For more information, see Modifying an
Amazon RDS DB instance (p. 306).
2. 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.

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

• DB name (not the DB instance ID)

• Master user name

You need both the DB name and the master user name to connect to the DB instance.
3. 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.

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

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

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. 1180). For information on connection issues, see Can't connect to Amazon RDS DB
instance (p. 2005).

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 AWS Management 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.r6g.large DB instance class and 100 gibibytes (GiB) of storage.
Important
Before you can create or connect to a DB instance, make sure to complete the tasks in Setting
up for Amazon RDS (p. 112).

There's no charge for creating an AWS account. However, by completing this tutorial, you might incur
costs for the AWS resources that you use. You can delete these resources after you complete the tutorial
if they are no longer needed.

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

Contents
• Creating a PostgreSQL DB instance (p. 150)
• Connecting to a PostgreSQL DB instance (p. 153)
• Using pgAdmin to connect to a PostgreSQL DB instance (p. 154)
• Using psql to connect to a PostgreSQL DB instance (p. 159)
• Deleting a DB instance (p. 159)

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.

You can use Easy create to create a DB instance running PostgreSQL with the AWS Management
Console. With Easy create, you specify only the DB engine type, DB instance size, and DB instance
identifier. Easy create uses the default settings for the other configuration options. When you use
Standard create instead of Easy create, 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.r6g.large DB instance class.
Note
For information about creating DB instances with Standard create, see Creating an Amazon RDS
DB instance (p. 194). If you want to use free tier, use Standard create.

To create a PostgreSQL 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 and make sure that Easy create is chosen.

5. In Configuration, choose PostgreSQL.

6. For DB instance size, 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.

150
 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 box is selected.

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

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

You can examine the default settings used with Easy create. The Editable after database is created
column shows which options you can change after database creation.

• To change settings with No in that column, use Standard create.

• To change settings with Yes in that column, either use Standard create, or modify the DB instance
after it is created to change the settings.

The following are important considerations for changing the default settings:

• In some cases, you might want your DB instance to use a specific virtual private cloud (VPC) based
on the Amazon VPC service. Or you might require a specific subnet group or security group. If so,
use Standard create to specify these resources. You might have created these resources when you
set up for Amazon RDS. For more information, see Provide access to your DB instance in your VPC
by creating a security group (p. 115).

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

• If you want to be able to access the DB instance from a client outside of its VPC, use Standard
create to set Public access to Yes.

If the DB instance should be private, leave Public access set to No.

• If you want to use free tier, use Standard create to set the PostgreSQL version lower than version
13, and then choose Free tier in Templates.
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. 306).
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.

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. Following, you can find 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, make sure that you have PostgreSQL or the psql client installed on your client
computer.

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

Before you attempt to connect to the DB instance, make sure that the DB instance is associated with a
security group that provides access to it. For more information, see Provide access to your DB instance in
your VPC by creating a security group (p. 115).

In some cases, you might have difficulty connecting to the DB instance. If so, the problem is most often
with the access rules that you set up in the security group that you assigned to the DB instance. If you
didn't specify the appropriate security group when you created the DB instance, you can modify the
DB instance to change its security group. For more information, see Modifying an Amazon RDS DB
instance (p. 306).

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

Topics
• Using pgAdmin to connect to a PostgreSQL DB instance (p. 154)
• Using psql to connect to a PostgreSQL DB instance (p. 159)

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.

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

d. On the Configuration tab, note the DB name. You don't need this to connect using pgAdmin,
but you do need it to connect using psql.

155
 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.123456789012.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.

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

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

158
 Amazon Relational Database Service User Guide
Deleting a DB instance

Using psql to connect to a PostgreSQL DB instance

If your client computer has PostgreSQL installed, you can use a local instance of psql to connect
to a PostgreSQL DB instance. To connect to your PostgreSQL DB instance using psql, you provide
host information, port number, access credentials, and the database name. You can obtain these
details by following the first step in the procedure for Using pgAdmin to connect to a PostgreSQL DB
instance (p. 154)

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

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

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

b. Create additional subnets (p. 1989)
c. Create a VPC security group for a public web server (p. 1990)
d. Create a VPC security group for a private DB instance (p. 1991)
e. Create a DB subnet group (p. 1991)
2. Create a DB instance (p. 161)
3. Create an EC2 instance and install a web server (p. 166)

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

160
 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. 1988). Complete the steps in Create a VPC with private and public
subnets (p. 1988), Create additional subnets (p. 1989), Create a VPC security group for a public
web server (p. 1990), and Create a VPC security group for a private DB instance (p. 1991).

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.

161
 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 – Clear the check box.
• Master password – Choose a password.
• Confirm password – Retype the password.

162
 Amazon Relational Database Service User Guide
Create a DB instance

8. In the DB instance class section, enable Include previous generation classes, and set these values:

• Burstable classes (includes t classes)

• db.t2.micro

163
 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, 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. 1988)
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. 1991)
• Public access – No
• VPC security group – Choose existing
• 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. 1991).

Remove other security groups, such as the default security group, by choosing the X associated
with each.
• Availability Zone – No preference
• Open Additional configuration, and make sure Database port uses the default value 3306.

164
 Amazon Relational Database Service User Guide
Create a DB instance

11. In the Database authentication section, make sure Password authentication is selected.
12. Open the Additional configuration section, and enter sample for Initial database name. Keep the
default settings for the other options.
13. To create your MySQL DB instance, choose Create database.

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

165
 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.
16. Complete Create an EC2 instance and install a web server (p. 166).

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

Launch an EC2 instance

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

166
 Amazon Relational Database Service User Guide
Create a web server

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.

3. Choose the Amazon Linux 2 AMI.

167
 Amazon Relational Database Service User Guide
Create a web server

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

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. 1988).
• 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. 1990).
• Auto-assign Public IP: Choose Enable.

168
 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. 1990). Make sure that the security group that you
choose includes inbound rules for Secure Shell (SSH) and HTTP access.

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

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

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

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.

172
 Amazon Relational Database Service User Guide
Create a web server

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. 1988). 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 systemctl command.

sudo systemctl enable httpd

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.

173
 Amazon Relational Database Service User Guide
Create a web server

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.

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.

174
 Amazon Relational Database Service User Guide
Create a web server

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

/* 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);
}
?>

175
 Amazon Relational Database Service User Guide
Create a web server

<!-- 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

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>");

176
 Amazon Relational Database Service User Guide
Create a web server

/* 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.

For information about installing the MySQL client and connecting to a DB instance, see Connecting to a
DB instance running the MySQL database engine (p. 1012).

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.

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

177
 Amazon Relational Database Service User Guide
Tutorials in this guide

Amazon RDS tutorials and sample

code
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. In addition,
you can access sample code in GitHub.
Note
You can find more tutorials at the AWS Database Blog. For information about training, see AWS
Training and Certification.

Topics
• Tutorials in this guide (p. 178)
• Tutorials in other AWS guides (p. 178)
• Tutorials and sample code in GitHub (p. 179)

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

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

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

Learn how to restore a DB instance from a DB snapshot.

• Tutorial: Use tags to specify which DB instances to stop (p. 364)

Learn how to use tags to specify which DB instances to stop.

• Tutorial: log the state of an Amazon RDS instance using EventBridge (p. 590)

Learn how to log a DB instance state 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.

178
 Amazon Relational Database Service User Guide
Tutorials and sample code in GitHub

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

Tutorials and sample code in GitHub

The following tutorials and sample code in GitHub show you how to perform common tasks with
Amazon RDS:

• Creating the Amazon Relational Database Service item tracker

Learn how to create an application that tracks and reports on work items using Amazon RDS, Amazon
Simple Email Service, Elastic Beanstalk, and SDK for Java 2.x.
• SDK for Go code samples for Amazon RDS

View a collection of SDK for Go code samples for Amazon RDS and Aurora.
• SDK for Java 2.x code samples for Amazon RDS

View a collection of SDK for Java 2.x code samples for Amazon RDS and Aurora.
• SDK for PHP code samples for Amazon RDS

View a collection of SDK for PHP code samples for Amazon RDS and Aurora.
• SDK for Ruby code samples for Amazon RDS

View a collection of SDK for Ruby code samples for Amazon RDS and Aurora.

179
 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. 180)
• DB instance RAM recommendations (p. 181)
• Using Enhanced Monitoring to identify operating system issues (p. 181)
• Using metrics to identify performance issues (p. 181)
• Tuning queries (p. 185)
• Best practices for working with MySQL (p. 186)
• Best practices for working with MariaDB (p. 187)
• Best practices for working with Oracle (p. 188)
• Best practices for working with PostgreSQL (p. 188)
• Best practices for working with SQL Server (p. 190)
• Working with DB parameter groups (p. 191)
• Best practices for automating DB instance creation (p. 191)
• Amazon RDS new features and best practices presentation video (p. 192)

Note
For common recommendations for Amazon RDS, see Viewing Amazon RDS
recommendations (p. 473).

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

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

180
 Amazon Relational Database Service User Guide
DB instance RAM recommendations

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

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 Monitoring the
OS by using Enhanced Monitoring (p. 551).

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

181
 Amazon Relational Database Service User Guide
Viewing performance metrics

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

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.

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

183
 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 bytes 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. 480).

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.

184
 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. 284).
• 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. 185).

If your queries are tuned and an issue persists, consider upgrading your Amazon RDS DB instance
classes (p. 10) 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. For information on improving
queries, use the following resources:

• MySQL – See Optimizing SELECT statements in the MySQL documentation. For additional query tuning
resources, see MySQL performance tuning and optimization resources.
• Oracle – See Database SQL Tuning Guide in the Oracle documentation.
• SQL Server – See Analyzing a query in the Microsoft documentation. You can also use the execution-,
index-, and I/O-related data management views (DMVs) described in System Dynamic Management
Views in the Microsoft documentation to troubleshoot SQL Server query issues.

A common aspect of query tuning is creating effective indexes. For potential index improvements
for your DB instance, see Database Engine Tuning Advisor in the Microsoft documentation. For
information on using Tuning Advisor on RDS for SQL Server, see Analyzing your database workload on
an Amazon RDS for SQL Server DB instance with Database Engine Tuning Advisor (p. 983).
• PostgreSQL – See 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.

For information about how to specify joins in your query for the best performance, see Controlling the
planner with explicit JOIN clauses.
• MariaDB – See Query optimizations in the MariaDB documentation.

185
 Amazon Relational Database Service User Guide
Best practices for working with MySQL

Best practices for working with MySQL

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

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.

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.

186
 Amazon Relational Database Service User Guide
Storage engine

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

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

187
 Amazon Relational Database Service User Guide
Number of 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 is the recommended and supported storage engine 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. 397) 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.

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.

188
 Amazon Relational Database Service User Guide
Loading data into a PostgreSQL DB instance

For information on how Amazon RDS implements other common PostgreSQL DBA tasks, see Common
DBA tasks for PostgreSQL (p. 1823).

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 max_wal_size and checkpoint_timeout parameters to reduce the
number of writes to the wal log.
• Disable the synchronous_commit parameter.
• 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 The Autovacuum Daemon.

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

189
 Amazon Relational Database Service User Guide
Amazon RDS for PostgreSQL best practices video

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.
Theautovacuum_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 Routine Vacuuming in 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)

Amazon RDS for PostgreSQL best practices video

The 2020 AWS re:Invent conference included a presentation on new features and best practices for
working with PostgreSQL on Amazon RDS. A video of the presentation is available here.

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

190
 Amazon Relational Database Service User Guide
Amazon RDS for SQL Server best practices video

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

Best practices for automating DB instance creation

It’s an Amazon RDS best practice to create a DB instance with the preferred minor version of the
database engine. You can use the AWS CLI, Amazon RDS API, or AWS CloudFormation to automate DB
instance creation. When you use these methods, you can specify only the major version and Amazon RDS
automatically creates the instance with the preferred minor version. For example, if PostgreSQL 12.5 is
the preferred minor version, and if you specify version 12 with create-db-instance, the DB instance
will be version 12.5.

To determine the preferred minor version, you can run the describe-db-engine-versions command
with the --default-only option as shown in the following example.

aws rds describe-db-engine-versions --default-only --engine postgres

{
"DBEngineVersions": [
{
"Engine": "postgres",
"EngineVersion": "12.5",
"DBParameterGroupFamily": "postgres12",
"DBEngineDescription": "PostgreSQL",
"DBEngineVersionDescription": "PostgreSQL 12.5-R1",
...some output truncated...
}
]
}

191
 Amazon Relational Database Service User Guide
Amazon RDS new features and
best practices presentation video

For information on creating DB instances programmatically, see the following resources:

• Using the AWS CLI – create-db-instance

• Using the Amazon RDS API – CreateDBInstance
• Using AWS CloudFormation – AWS::RDS::DBInstance

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.

192
 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. 194)
• Creating Amazon RDS resources with AWS CloudFormation (p. 214)
• Connecting to an Amazon RDS DB instance (p. 215)
• Using Amazon RDS Proxy (p. 221)
• Working with option groups (p. 268)
• Working with DB parameter groups (p. 284)

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

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. 118). For an example that
uses the original console to create a DB instance, see Original console example (p. 209).

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.

194
 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

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.

195
 Amazon Relational Database Service User Guide
Creating a DB instance

b. If you want to specify a password, clear the Auto generate a password check box if it is
selected.
c. (Optional) Change the Master username value.
d. Enter the same password in Master password and Confirm password.
11. For the remaining sections, specify your DB instance settings. For information about each setting,
see Settings for DB instances (p. 197).
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. 306).
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.

AWS CLI
To create a DB instance by using the AWS CLI, call the create-db-instance command with the following
parameters:

• --db-instance-identifier
• --db-instance-class
• --vpc-security-group-ids
• --db-subnet-group
• --engine

196
 Amazon Relational Database Service User Guide
Available settings

• --master-username
• --master-user-password
• --allocated-storage
• --backup-retention-period

For information about each setting, see Settings for DB instances (p. 197).

This example uses Microsoft SQL Server.

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.

For information about each setting, see Settings for DB instances (p. 197).

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.

197
 Amazon Relational Database Service User Guide
Available settings

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

Architecture The architecture of the database: CLI option: Oracle

settings single-tenant or non-multitenant.
This setting applies only to Oracle --engine oracle-ee-cdb
Database 19c.
--engine oracle-se2-cdb
If you choose Use multitenant
architecture, RDS for Oracle API parameter:
creates a container database (CDB).
Engine
This CDB contains one pluggable
database (PDB). If you don't choose
this option, RDS for Oracle creates
a non-CDB. A non-CDB uses the
traditional Oracle architecture.

For more information, see RDS for

Oracle architecture (p. 1173).

Auto minor Enable auto minor version upgrade CLI option: All
version upgrade to enable your DB instance to
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
For more information, see
Automatically upgrading the minor
engine version (p. 333).

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

AWS KMS key Only available if Encryption is set to CLI option: All
Enable encryption. Choose the AWS
KMS key to use for encrypting this --kms-key-id
DB instance. For more information,
API parameter:

198
 Amazon Relational Database Service User Guide
Available settings

Console setting Setting description CLI option and RDS API parameter Supported
DB engines
see Encrypting Amazon RDS KmsKeyId
resources (p. 1879).

Backup Choose Enable replication in 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 PostgreSQL
disaster recovery. or RDS API, see Enabling cross-Region
automated backups (p. 400). SQL Server
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. 388).

Backup target Choose AWS Cloud to store CLI option: MySQL,

automated backups and manual PostgreSQL,
snapshots in the parent AWS Region. --backup-target SQL Server
Choose Outposts (on-premises) to
store them locally on your Outpost. API parameter:

This option setting applies only BackupTarget

to RDS on Outposts. For more
information, see Creating DB
instances for Amazon RDS on AWS
Outposts (p. 736).

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

199
 Amazon Relational Database Service User Guide
Available settings

Console setting Setting description CLI option and RDS API parameter Supported
DB engines

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.

In a single-tenant configuration, a
non-default DB character set affects
only the PDB, not the CDB. For more
information, see RDS for Oracle
architecture (p. 1173).

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

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

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. 359).
RDS API parameter:

CopyTagsToSnapshot

200
 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. 1909). 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. 1113)
• Configuring Kerberos
authentication for Amazon RDS
for Oracle (p. 1193)
• Using Kerberos authentication
with Amazon RDS for
PostgreSQL (p. 1761)

Database Choose Amazon RDS if you For the CLI and API, you specify the Oracle
management don't need to customize your database engine type.
type environment.

Choose Amazon RDS Custom if you

want to customize the database,
OS, and infrastructure. For more
information, see Working with
Amazon RDS Custom (p. 660).

201
 Amazon Relational Database Service User Guide
Available settings

Console setting Setting description CLI option and RDS API parameter Supported
DB engines

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.

DB engine The version of database engine that CLI option: All

version you want to use.
--engine-version

RDS API parameter:

EngineVersion

DB instance The configuration for your DB CLI option: All

class instance. For example, a db.t3.small
DB instance class has 2 GiB memory, --db-instance-class
2 vCPUs, 1 virtual core, a variable
ECU, and a moderate I/O capacity. RDS API parameter:

If possible, choose a DB instance DBInstanceClass

class large enough that a typical
query working set can be held
in memory. When working sets
are held in memory, the system
can avoid writing to disk, which
improves performance. For more
information, see DB instance
classes (p. 10).

In RDS for Oracle, you can

select Include additional
memory configurations.
These configurations are
optimized for a high ratio of
memory to vCPU. For example,
db.r5.6xlarge.tpc2.mem4x is
a db.r5.8x DB instance that has
2 threads per core (tpc2) and
4x the memory of a standard
db.r5.6xlarge DB instance. For more
information, see RDS for Oracle
instance classes (p. 1170).

202
 Amazon Relational Database Service User Guide
Available settings

Console setting Setting description CLI option and RDS API parameter Supported
DB engines

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.

DB parameter A parameter group for your DB CLI option: All

group instance. You can choose the default
parameter group, or you can create --db-parameter-group-name
a custom parameter group.
RDS API parameter:
For more information, see
Working with DB parameter DBParameterGroupName
groups (p. 284).

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

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. 1879). 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
Monitoring the OS by using RDS API parameters:
Enhanced Monitoring (p. 551).
MonitoringInterval

MonitoringRoleArn

Engine type Choose the database engine to be CLI option: All

used for this DB instance.
--engine

RDS API parameter:

Engine

203
 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: Oracle

• Choose license-included for --license-model SQL Server

Microsoft SQL Server.
RDS API parameter:
• Choose license-included or bring-
your-own-license for Oracle. LicenseModel

Log exports The types of database log files to CLI option: All
publish to Amazon CloudWatch
Logs. --enable-cloudwatch-logs-
exports
For more information, see
Publishing database logs to Amazon RDS API parameter:
CloudWatch Logs (p. 595).
EnableCloudwatchLogsExports

204
 Amazon Relational Database Service User Guide
Available settings

Console setting Setting description CLI option and RDS API parameter Supported
DB engines

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

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 Master user account
privileges (p. 1961).

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

205
 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

Multi-AZ deployments for high
availability (p. 59).

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

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

206
 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 KMS key to use to protect
the key used to encrypt this EnablePerformanceInsights
database volume. Choose from the
KMS keys in your account, or enter PerformanceInsightsRetentionPeriod
the key from a different account.
PerformanceInsightsKMSKeyId
For more information, see
Monitoring DB load with
Performance Insights on Amazon
RDS (p. 487).

Provisioned The Provisioned IOPS (I/O CLI option: All

IOPS operations per second) value for the
DB instance. The setting is available --iops
only if Provisioned IOPS (SSD) is
chosen for Storage type. RDS API parameter:

For more information, Iops

see Provisioned IOPS SSD
storage (p. 50).

207
 Amazon Relational Database Service User Guide
Available settings

Console setting Setting description CLI option and RDS API parameter Supported
DB engines

Public access Yes to give the DB instance a CLI option: All

public IP address, meaning that it's
accessible outside the VPC. To be --publicly-accessible
publicly accessible, the DB instance
also has to be in a public subnet in --no-publicly-accessible
the VPC.
RDS API parameter:
No to make the DB instance
PubliclyAccessible
accessible only from inside the VPC.

For more information, see Hiding

a DB instance in a VPC from the
internet (p. 1977).

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

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

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

Storage type The storage type for your DB CLI option: All
instance.
--storage-type
For more information, see Amazon
RDS storage types (p. 48). RDS API parameter:

StorageType

208
 Amazon Relational Database Service User Guide
Original console example

Console setting Setting description CLI option and RDS API parameter Supported
DB engines

Subnet group A DB subnet group to associate with CLI option: All

this DB instance.
--db-subnet-group-name
For more information, see Working
with DB subnet groups (p. 1977). RDS API parameter:

DBSubnetGroupName

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

Virtual Private A Amazon VPC to associate with this For the CLI and API, you specify the VPC All
Cloud (VPC) DB instance. security group IDs.

For more information, see Amazon

Virtual Private Cloud VPCs and
Amazon RDS (p. 1975).

VPC security The security group to associate with CLI option: All
group the DB instance.
--vpc-security-group-ids
For more information, see VPC
security groups (p. 1948). RDS API parameter:

VpcSecurityGroupIds

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.

209
 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

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

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

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

212
Amazon Relational Database Service User Guide
Original console example

213
 Amazon Relational Database Service User Guide
Creating resources with AWS CloudFormation

Creating Amazon RDS resources with AWS

CloudFormation
Amazon RDS is integrated with AWS CloudFormation, a service that helps you to model and set up your
AWS resources so that you can spend less time creating and managing your resources and infrastructure.
You create a template that describes all the AWS resources that you want (such as DB instances and DB
parameter groups), and AWS CloudFormation provisions and configures those resources for you.

When you use AWS CloudFormation, you can reuse your template to set up your RDS resources
consistently and repeatedly. Describe your resources once, and then provision the same resources over
and over in multiple AWS accounts and Regions.

RDS and AWS CloudFormation templates

To provision and configure resources for RDS and related services, you must understand AWS
CloudFormation templates. Templates are formatted text files in JSON or YAML. These templates
describe the resources that you want to provision in your AWS CloudFormation stacks. If you're
unfamiliar with JSON or YAML, you can use AWS CloudFormation Designer to help you get started with
AWS CloudFormation templates. For more information, see What is AWS CloudFormation Designer? in
the AWS CloudFormation User Guide.

RDS supports creating resources in AWS CloudFormation. For more information, including examples
of JSON and YAML templates for these resources, see the RDS resource type reference in the AWS
CloudFormation User Guide.

Learn more about AWS CloudFormation

To learn more about AWS CloudFormation, see the following resources:

• AWS CloudFormation
• AWS CloudFormation User Guide
• AWS CloudFormation API Reference
• AWS CloudFormation Command Line Interface User Guide

214
 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. 194). 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. 215)
• Database authentication options (p. 218)
• Encrypted connections (p. 219)
• Scenarios for accessing a DB instance in a VPC (p. 219)
• Connecting to a DB instance that is running a specific DB engine (p. 219)
• Managing connections with RDS Proxy (p. 220)

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.

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

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

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

218
 Amazon Relational Database Service User Guide
Encrypted connections

For more information, see Database authentication with Amazon RDS (p. 1877).

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

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. 2005).
• 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. 1982).

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

219
 Amazon Relational Database Service User Guide
Managing connections with RDS Proxy

• Connecting to a DB instance running the Microsoft SQL Server database engine (p. 824)
• Connecting to a DB instance running the MySQL database engine (p. 1012)
• Connecting to your Oracle DB instance (p. 1180)
• Connecting to a DB instance running the PostgreSQL database engine (p. 1748)

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.

• Using Amazon RDS Proxy (p. 221)

220
 Amazon Relational Database Service User Guide
Using RDS Proxy

Using 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. By
using RDS Proxy, you can also 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
• Supported engines and Region availability for RDS Proxy (p. 221)
• Quotas and limitations for RDS Proxy (p. 222)
• Planning where to use RDS Proxy (p. 223)
• RDS Proxy concepts and terminology (p. 224)
• Getting started with RDS Proxy (p. 228)
• Managing an RDS Proxy (p. 239)
• Working with Amazon RDS Proxy endpoints (p. 248)
• Monitoring RDS Proxy using Amazon CloudWatch (p. 254)
• RDS Proxy command-line examples (p. 259)
• Troubleshooting for RDS Proxy (p. 261)
• Using RDS Proxy with AWS CloudFormation (p. 266)

Supported engines and Region availability for RDS

Proxy
RDS Proxy supports the following database engine versions:

• RDS for MySQL – MySQL 5.6, 5.7, and 8.0

• RDS for PostgreSQL – version 10.10 and higher minor versions, version 11.5 and higher minor versions,
and version 12.5 and higher minor versions

RDS Proxy is available in the following Regions:

• US East (Ohio)

221
 Amazon Relational Database Service User Guide
Quotas and limitations

• US East (N. Virginia)

• US West (N. California)
• US West (Oregon)
• Asia Pacific (Mumbai)
• Asia Pacific (Seoul)
• Asia Pacific (Singapore)
• Asia Pacific (Sydney)
• Asia Pacific (Tokyo)
• Canada (Central)
• Europe (Frankfurt)
• Europe (Ireland)
• Europe (London)

Quotas and limitations for RDS Proxy

The following quotas and limitations apply to 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. 248).

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.
• Using RDS Proxy with Aurora clusters that are part of an Aurora global database isn't currently
supported.
• Your RDS Proxy must be in the same virtual private cloud (VPC) as the database. The proxy can't be
publicly accessible, although the database can be.
Note
For Aurora DB clusters, you can turn on cross-VPC access. To do this, create an additional
endpoint for a proxy and specify a different VPC, subnets, and security groups with
that endpoint. For more information, see Accessing Aurora and RDS databases across
VPCs (p. 249).
• You can't use RDS Proxy with a VPC that has its tenancy set to dedicated.
• 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. 230) 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.

222
 Amazon Relational Database Service User Guide
Planning where to use RDS Proxy

The following RDS Proxy limitations apply to MySQL:

• RDS Proxy doesn't support the MySQL sha256_password and caching_sha2_password

authentication plugins. These plugins implement SHA-256 hashing for user account passwords.
• 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 self-managed MySQL databases in EC2 instances.
• You can't use RDS Proxy with an RDS for MySQL DB instance that has the read_only parameter in its
DB parameter group set to 1.
• 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. 245).

The following RDS Proxy limitations apply to PostgreSQL:

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

Planning where to use 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:

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

223
 Amazon Relational Database Service User Guide
RDS Proxy concepts and terminology

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

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.

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. 224)
• Connection pooling (p. 225)
• RDS Proxy security (p. 225)
• Failover (p. 227)
• Transactions (p. 227)

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 make up 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.

224
 Amazon Relational Database Service User Guide
RDS Proxy concepts and terminology

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

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.

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

225
 Amazon Relational Database Service User Guide
RDS Proxy concepts and terminology

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.

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.

226
 Amazon Relational Database Service User Guide
RDS Proxy concepts and terminology

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.

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.

227
 Amazon Relational Database Service User Guide
Getting started with RDS Proxy

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

Getting started with 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.

Topics
• Setting up network prerequisites (p. 228)
• Setting up database credentials in AWS Secrets Manager (p. 229)
• Setting up AWS Identity and Access Management (IAM) policies (p. 230)
• Creating an RDS Proxy (p. 233)
• Viewing an RDS Proxy (p. 236)
• Connecting to a database through RDS Proxy (p. 237)

Setting up network prerequisites

Using RDS Proxy requires you to have a common virtual private cloud (VPC) between your Aurora DB
cluster or RDS DB instance and RDS Proxy. This VPC should have a minimum of two subnets that are
in different Availability Zones. Your account can either own these subnets or share them with other
accounts. For information about VPC sharing, see Work with shared VPCs. Your client application
resources such as Amazon EC2, Lambda, or Amazon ECS can be in the same VPC or in a separate VPC
from the proxy. Note that 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.

228
 Amazon Relational Database Service User Guide
Getting started with RDS Proxy

$ # 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-identifier 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-identifier 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-identifier my_instance_id --query '*[].
[DBSubnetGroup]|[0]|[0].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
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.

229
 Amazon Relational Database Service User Guide
Getting started with RDS Proxy

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.

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

230
 Amazon Relational Database Service User Guide
Getting started with RDS Proxy

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
key or your own KMS key 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",
"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

231
 Amazon Relational Database Service User Guide
Getting started with RDS Proxy

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*",
"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":"*"
}
]
}
"""

232
 Amazon Relational Database Service User Guide
Getting started with RDS Proxy

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.

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. 194) . 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. 244).
• 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. 245).
• 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

233
 Amazon Relational Database Service User Guide
Getting started with RDS Proxy

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.
• Initialization query. (Optional) You can specify one or more SQL statements for the proxy to run
when opening each new database connection. The setting is typically used with SET statements
to make sure that each connection has identical settings such as time zone and character set. For
multiple statements, use semicolons as the separator. You can also include multiple variables in a
single SET statement, such as SET x=1, y=2. Initialization query is not currently supported for
PostgreSQL.

For Connectivity, provide information for the following:

• Secrets Manager secrets. 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.
When using a shared VPC, you can't use the default security group for the VPC, or one
that belongs to another account. Choose a security group that belongs to your account. If
one doesn't exist, create one. For more information about this limitation, see Work with
shared VPCs.

(Optional) Provide advanced configuration:

• Enable enhanced logging. You can enable this setting to troubleshoot proxy compatibility or
performance issues.

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.

234
 Amazon Relational Database Service User Guide
Getting started with RDS 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. 228) for examples of how to find the subnet IDs that you
can use.
Note
The 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.
When using a shared VPC, you can't use the default security group for the VPC, or one that
belongs to another account. Choose a security group that belongs to your account. If one
doesn't exist, create one. For more information about this limitation, see Work with shared VPCs.

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

235
 Amazon Relational Database Service User Guide
Getting started with RDS Proxy

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.

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.

236
 Amazon Relational Database Service User Guide
Getting started with RDS Proxy

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

Topics
• Connecting to a proxy using native authentication (p. 237)
• Connecting to a proxy using IAM authentication (p. 238)
• Considerations for connecting to a proxy with PostgreSQL (p. 238)

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"
},
{
"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.

237
 Amazon Relational Database Service User Guide
Getting started with RDS Proxy

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

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.

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.
• 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. 1916).
• In the direct database IAM authentication case, you selectively choose database users and configure
them to be identified with a special authentication plugin. You can then connect to those users using
IAM authentication.

In the proxy use case, you provide the proxy with Secrets that contain some user's user name and
password (native authentication). You then connect to the proxy using IAM authentication. Here, you
do this by generating an authentication token with the proxy endpoint, not the database endpoint.
You also use a user name that matches one of the user names for the secrets that you 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:

• user
• database
• replication

The startup message can also include the following additional runtime parameters:

238
 Amazon Relational Database Service User Guide
Managing an RDS Proxy

• 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. 245). 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. 239)
• Adding a new database user (p. 244)
• Changing the password for a database user (p. 244)
• Controlling connection limits and timeouts (p. 244)
• Managing and monitoring connection pooling (p. 244)
• Avoiding pinning (p. 245)
• Deleting an RDS Proxy (p. 247)

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.

239
 Amazon Relational Database Service User Guide
Managing an RDS Proxy

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 modify the following:

• Proxy identifier – Rename the proxy by entering a new identifier.

• Require Transport Layer Security – Turn the requirement for Transport layer Security (TLS) on or
off.
• Idle client connection timeout – Enter a time period for the idle client connection timeout.
• Secrets Manager secrets – Add or remove Secrets Manager secrets. These secrets correspond to
database user names and passwords.
• IAM role – Change the IAM role used to retrieve the secrets from Secrets Manager.
• IAM Authentication – Require or disallow IAM authentication for connections to the proxy.
• VPC security group – Add or remove VPC security groups for the proxy to use.
• Enable enhanced logging – 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:

• Database – Choose a different RDS DB instance or Aurora cluster.

• Connection pool maximum connections – Adjust what percentage of the maximum available
connections the proxy can use.
• Session pinning filters – (Optional) 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.
• Connection borrow timeout – 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.
• Initialization query – (Optional) Add an initialization query, or modify the current one. You can
specify one or more SQL statements for the proxy to run when opening each new database
connection. The setting is typically used with SET statements to make sure that each connection
has identical settings such as time zone and character set. For multiple statements, use semicolons

240
 Amazon Relational Database Service User Guide
Managing an RDS Proxy

as the separator. You can also include multiple variables in a single SET statement, such as SET
x=1, y=2. Initialization query is not currently supported for PostgreSQL.

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 }'

241
 Amazon Relational Database Service User Guide
Managing an 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,

242
 Amazon Relational Database Service User Guide
Managing an RDS Proxy

"RdsResourceId": "instance-4330"
}
]
}

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.

243
 Amazon Relational Database Service User Guide
Managing an 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. 229).
• 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. 284). 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. 225), connection pooling is an important RDS Proxy feature.
Following, you can learn how to make efficient use of connection pooling.

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 database connections used by the
connection pool. This setting is represented by the Connection pool maximum connections field in the
RDS Proxy console or the MaxConnectionsPercent parameter in the AWS CLI or API. 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. 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

244
 Amazon Relational Database Service User Guide
Managing an RDS Proxy

for connections that don't go through a proxy. In some cases, the proxy might keep 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 database connection to become available for use by your
application. This setting is represented by the Connection borrow timeout field in the RDS Proxy
console or the ConnectionBorrowTimeout parameter in the AWS CLI or API. 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 appropriate database instance is available to handle the
request because, for example, 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.

You can control how actively the proxy closes idle database connections in the connection pool. This
setting is represented by the MaxIdleConnectionsPercent parameter of the DBProxyTargetGroup
in the AWS CLI or API. With a high value, the proxy leaves a high percentage of idle database connections
open. With a low value, the proxy closes a high percentage of idle database connections. It's expressed as
a percentage of the max_connections setting for the RDS DB instance or Aurora DB cluster used by the
target group. The default value is 50 percent. To change the value of MaxIdleConnectionsPercent,
use the CLI command modify-db-proxy-target-group or the API operation ModifyDBProxyTargetGroup.
Note
RDS Proxy closes database connections some time after 24 hours when they are no longer in
use. The proxy performs this action regardless of the value of the maximum idle connections
setting.

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.

245
 Amazon Relational Database Service User Guide
Managing an RDS Proxy

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. 254).
• 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. 233).
• 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 also cause pinning:

246
 Amazon Relational Database Service User Guide
Managing an RDS Proxy

• 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

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

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.

247
 Amazon Relational Database Service User Guide
Working with RDS Proxy endpoints

Working with Amazon RDS Proxy endpoints

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. 248)
• Reader endpoints (p. 249)
• Accessing Aurora and RDS databases across VPCs (p. 249)
• Creating a proxy endpoint (p. 250)
• Viewing proxy endpoints (p. 251)
• Modifying a proxy endpoint (p. 252)
• Deleting a proxy endpoint (p. 253)
• Limits for proxy endpoints (p. 254)

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.

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.

For information about limits associated with proxy endpoints, see Limits for proxy endpoints (p. 254).

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

248
 Amazon Relational Database Service User Guide
Working with RDS Proxy endpoints

or read-only endpoints of a proxy. For more information, see Monitoring RDS Proxy using Amazon
CloudWatch (p. 254).

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 enable cross-VPC access, you create a new endpoint for the proxy. If you aren't familiar with creating
proxy endpoints, see Working with Amazon RDS Proxy endpoints (p. 248) 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. 118)
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. 233).
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. 250).
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 Secrets Manager 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.

249
 Amazon Relational Database Service User Guide
Working with RDS Proxy endpoints

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.
For more information about cross-VPC access, see Accessing Aurora and RDS databases across
VPCs (p. 249).
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.

250
 Amazon Relational Database Service User Guide
Working with RDS Proxy endpoints

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

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.

251
 Amazon Relational Database Service User Guide
Working with RDS Proxy endpoints

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

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.

252
 Amazon Relational Database Service User Guide
Working with RDS Proxy endpoints

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.

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.

253
 Amazon Relational Database Service User Guide
Monitoring RDS Proxy

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.

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.

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

254
 Amazon Relational Database Service User Guide
Monitoring RDS 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 Working with Amazon RDS Proxy
endpoints (p. 248).

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. 255)
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. 255), Dimension
This metric is reported set 2 (p. 255)
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. 255), Dimension
most useful statistic for set 2 (p. 255)
this metric is Sum.

The current number

ClientConnectionsNoTLS 1 minute and above Dimension set
of client connections 1 (p. 255), Dimension
without Transport set 2 (p. 255)
Layer Security (TLS).
This metric is reported
every minute. The most
useful statistic for this
metric is Sum.

The number of client

ClientConnectionsReceived 1 minute and above Dimension set
connection requests 1 (p. 255), Dimension
received. The most set 2 (p. 255)
useful statistic for this
metric is Sum.

255
 Amazon Relational Database Service User Guide
Monitoring RDS Proxy

Metric Description Valid period CloudWatch dimension

set

The number of
ClientConnectionsSetupFailedAuth 1 minute and above Dimension set
client connection 1 (p. 255), Dimension
attempts that failed set 2 (p. 255)
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. 255), Dimension
successfully established set 2 (p. 255)
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. 255), Dimension
with TLS. This metric set 2 (p. 255)
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. 255), Dimension
connection. The most set 3 (p. 255),
useful statistic for this Dimension set
metric is Sum. 4 (p. 255)

The number of requests

DatabaseConnectionRequestsWithTLS 1 minute and above Dimension set
to create a database 1 (p. 255), Dimension
connection with TLS. set 3 (p. 255),
The most useful Dimension set
statistic for this metric 4 (p. 255)
is Sum.

DatabaseConnections The current number of 1 minute Dimension set

database connections. 1 (p. 255), Dimension
This metric is reported set 3 (p. 255),
every minute. The most Dimension set
useful statistic for this 4 (p. 255)
metric is Sum.

The time in
DatabaseConnectionsBorrowLatency 1 minute and above Dimension set
microseconds that it 1 (p. 255), Dimension
takes for the proxy set 2 (p. 255)
being monitored
to get a database
connection. The most
useful statistic for this
metric is Average.

256
 Amazon Relational Database Service User Guide
Monitoring RDS Proxy

Metric Description Valid period CloudWatch dimension

set

The current number of

DatabaseConnectionsCurrentlyBorrowed 1 minute Dimension set
database connections 1 (p. 255), Dimension
in the borrow state. set 3 (p. 255),
This metric is reported Dimension set
every minute. The most 4 (p. 255)
useful statistic for this
metric is Sum.

The current number of

DatabaseConnectionsCurrentlyInTransaction 1 minute Dimension set
database connections 1 (p. 255), Dimension
in a transaction. This set 3 (p. 255),
metric is reported Dimension set
every minute. The most 4 (p. 255)
useful statistic for this
metric is Sum.

The current number of

DatabaseConnectionsCurrentlySessionPinned 1 minute Dimension set
database connections 1 (p. 255), Dimension
currently pinned set 3 (p. 255),
because of operations Dimension set
in client requests that 4 (p. 255)
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. 255), Dimension
requests that failed. set 3 (p. 255),
The most useful Dimension set
statistic for this metric 4 (p. 255)
is Sum.

The number of
DatabaseConnectionsSetupSucceeded 1 minute and above Dimension set
database connections 1 (p. 255), Dimension
successfully established set 3 (p. 255),
with or without TLS. Dimension set
The most useful 4 (p. 255)
statistic for this metric
is Sum.

The current number of

DatabaseConnectionsWithTLS 1 minute Dimension set
database connections 1 (p. 255), Dimension
with TLS. This metric set 3 (p. 255),
is reported every Dimension set
minute. The most 4 (p. 255)
useful statistic for this
metric is Sum.

257
 Amazon Relational Database Service User Guide
Monitoring RDS Proxy

Metric Description Valid period CloudWatch dimension

set

The maximum
MaxDatabaseConnectionsAllowed 1 minute Dimension set
number of database 1 (p. 255), Dimension
connections allowed. set 3 (p. 255),
This metric is reported Dimension set
every minute. The most 4 (p. 255)
useful statistic for this
metric is Sum.

The time in
QueryDatabaseResponseLatency 1 minute and above Dimension set
microseconds that 1 (p. 255), Dimension
the database took set 2 (p. 255),
to respond to the Dimension set
query. The most useful 3 (p. 255), Dimension
statistic for this metric set 4 (p. 255)
is Average.

QueryRequests The number of queries 1 minute and above Dimension set

received. A query 1 (p. 255), Dimension
including multiple set 2 (p. 255)
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. 255), Dimension
connections. A query set 2 (p. 255)
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. 255), Dimension
connections. A query set 2 (p. 255)
including multiple
statements is counted
as one query. The most
useful statistic for this
metric is Sum.

QueryResponseLatencyThe time in 1 minute and above Dimension set

microseconds between 1 (p. 255), Dimension
getting a query set 2 (p. 255)
request and the proxy
responding to it. The
most useful statistic for
this metric is Average.

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.

258
 Amazon Relational Database Service User Guide
RDS Proxy examples

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.

RDS Proxy command-line examples

To see how combinations of connection commands and SQL statements interact with RDS Proxy, look at
the following examples.

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-identifier 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>

259
 Amazon Relational Database Service User Guide
RDS Proxy examples

[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-identifier 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)
+---------------+---------------+
| 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:"

260
 Amazon Relational Database Service User Guide
Troubleshooting RDS Proxy

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
Working with Amazon RDS Proxy endpoints (p. 248).

Topics
• Verifying connectivity for a proxy (p. 261)
• Common issues and solutions (p. 262)

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.

261
 Amazon Relational Database Service User Guide
Troubleshooting RDS Proxy

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.

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
}

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.

262
 Amazon Relational Database Service User Guide
Troubleshooting RDS Proxy

Error Causes or workarounds

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

263
 Amazon Relational Database Service User Guide
Troubleshooting RDS 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.
• 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 psql CLI, use a

264
 Amazon Relational Database Service User Guide
Troubleshooting RDS Proxy

Error Cause Solution

PostgreSQL messaging version greater than or equal to
protocol. 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.

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 to

investigate the issue.

265
 Amazon Relational Database Service User Guide
Using RDS Proxy with AWS CloudFormation

Error Cause Solution

Timed-out waiting The proxy timed-out waiting to Possible solutions are the
to acquire database acquire a database connection. following:
connection. Some possible reasons include
the following: • Check the target of the RDS
DB instance or Aurora DB
• The proxy can't establish a cluster status to see if it's
database connection because unavailable.
the maximum connections • Check if there are long-
have been reached. running transactions and/or
• The proxy can't establish a queries being executed. They
database connection because can use database connections
the database is unavailable. from the connection pool for a
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.

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
DBInstanceIdentifiers:
- Fn::ImportValue: DBInstanceName

266
 Amazon Relational Database Service User Guide
Using RDS Proxy with AWS CloudFormation

DependsOn: DBProxy

For more information about the Amazon RDS and Aurora resources that you can create using AWS
CloudFormation, see RDS resource type reference.

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

Microsoft SQL Server Options for the Microsoft SQL Server database engine (p. 920)

MySQL Options for MySQL DB instances (p. 1100)

Oracle Adding options to Oracle DB instances (p. 1307)

PostgreSQL PostgreSQL does not use options and option groups. PostgreSQL
uses extensions and modules to provide additional features.
For more information, see PostgreSQL extensions supported on
Amazon RDS (p. 1721).

Option groups overview

Amazon RDS provides an empty default option group for each new DB instance. You can't modify or
delete 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. 306).

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.

268
 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. 1385) and
Oracle Label Security (p. 1350).

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. 1333) and Oracle Management Agent for Enterprise
Manager Cloud Control (p. 1337).
• Oracle native network encryption (p. 1359) and Oracle Secure Sockets Layer (p. 1367).

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

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

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 \

270
 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 \

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

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.

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

273
 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 \

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

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

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

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

277
 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

278
 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

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

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.

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

You can't delete a default option group. In addition, if you try to delete an option group that is
associated with an Amazon RDS resource, an error similar to the following is returned.

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

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

282
 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

283
 Amazon Relational Database Service User Guide
Working with parameter groups

Working with DB parameter groups

Database parameters specify how the database is configured. For example, database parameters can
specify the amount of resources, such as memory, to allocate to a database.

You manage your database configuration by associating your DB instances with parameter groups.
Amazon RDS defines parameter groups with default settings.
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. 306).
Note
Some DB engines offer additional features that you can add to your database as options in an
option group. For information about option groups, see Working with option groups (p. 268).

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:

• Database parameters are either static or dynamic. When you change a static parameter, a database
reboot is required take it into effect. 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 associate a new DB parameter group with a DB instance, the modified static and dynamic
parameters are applied only after the DB instance is rebooted. However, if you modify dynamic
parameters in the newly associated DB parameter group, these changes are applied immediately
without a reboot. For more information about changing the DB parameter group, see Modifying an
Amazon RDS DB instance (p. 306).

284
 Amazon Relational Database Service User Guide
Creating a DB parameter group

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

For some DB engines, 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;

For more information about changing the character set or collation values for a database, check the
documentation for your DB engine.
• 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. 295).

Topics
• Creating a DB parameter group (p. 285)
• Associating a DB parameter group with a DB instance (p. 287)
• Modifying parameters in a DB parameter group (p. 288)
• Resetting parameters in a DB parameter group to their default values (p. 290)
• Copying a DB parameter group (p. 292)
• Listing DB parameter groups (p. 294)
• Viewing parameter values for a DB parameter group (p. 295)
• Comparing DB parameter groups (p. 296)
• Specifying DB parameters (p. 296)

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.

285
 Amazon Relational Database Service User Guide
Creating a DB 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.

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.

286
 Amazon Relational Database Service User Guide
Associating a DB parameter group with a DB instance

Include the following required parameters:

• DBParameterGroupName
• DBParameterGroupFamily
• Description

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. 285).
For information about creating a DB instance, see Creating an Amazon RDS DB instance (p. 194). For
information about modifying a DB instance, see Modifying an Amazon RDS DB instance (p. 306).
Note
When you associate a new DB parameter group with a DB instance, the modified static and
dynamic parameters are applied only after the DB instance is rebooted. However, if you modify
dynamic parameters in the newly associated DB parameter group, these changes are applied
immediately without a reboot.

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

287
 Amazon Relational Database Service User Guide
Modifying parameters in a DB parameter group

immediately to apply the changes during the next maintenance window. For more information, see
Using the Apply Immediately setting (p. 307).

Example

For Linux, macOS, or Unix:

aws rds modify-db-instance \

--db-instance-identifier database-1 \
--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.

288
 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

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

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

291
 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

292
 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 ^

293
 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.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 \

--db-parameter-group-name mydbparamgroup1

294
 Amazon Relational Database Service User Guide
Viewing parameter values for a DB parameter group

For Windows:

aws rds describe-db-parameter-groups ^

--db-parameter-group-name mydbparamgroup1

The command returns a response like the following:

DBPARAMETERGROUP mydbparametergroup1 mysql5.6 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
DBPARAMETER binlog_cache_size 32768 system integer dynamic
true

295
 Amazon Relational Database Service User Guide
Comparing DB parameter groups

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

For the PostgreSQL engine, you can use an expression to specify a Boolean DB parameter. See Boolean
DB parameter expressions (p. 299).

Contents
• DB parameter formulas (p. 297)

296
 Amazon Relational Database Service User Guide
Specifying DB parameters

• DB parameter formula variables (p. 297)

• DB parameter formula operators (p. 297)
• DB parameter functions (p. 298)
• Boolean DB parameter expressions (p. 299)
• DB parameter log expressions (p. 300)
• DB parameter value examples (p. 300)

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

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

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.

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

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

300
 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. 302)
• Starting an Amazon RDS DB instance that was previously stopped (p. 305)
• Modifying an Amazon RDS DB instance (p. 306)
• Maintaining a DB instance (p. 320)
• Upgrading a DB instance engine version (p. 331)
• Renaming a DB instance (p. 334)
• Rebooting a DB instance (p. 336)
• Working with read replicas (p. 338)
• Tagging Amazon RDS resources (p. 359)
• Working with Amazon Resource Names (ARNs) in Amazon RDS (p. 369)
• Working with storage for Amazon RDS DB instances (p. 376)
• Deleting a DB instance (p. 384)

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

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

302
 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.
• In a Multi-AZ configuration, the primary and secondary Availability Zones might be switched after you
start the 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 change 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.

303
 Amazon Relational Database Service User Guide
Stopping a DB instance

AWS CLI
To stop a DB instance by using the AWS CLI, call the stop-db-instance command with the following
option:

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

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

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.

305
 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 downtime 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. 307).
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 downtime in some cases. For more information, see Using the Apply Immediately
setting (p. 307).
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. 307).

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

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

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 the DB instance to be temporarily unavailable
(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. 307).

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.

307
 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 Downtime 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. 48).

Auto minor version upgrade CLI option: The change occurs Downtime doesn't All DB
immediately. This occur during this engines
Yes to enable your DB instance --auto-minor- setting ignores the change.
to receive preferred minor version- apply immediately
DB engine version upgrades upgrade|--no- setting.
automatically when they auto-minor-
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. 333).

Backup replication Not available The change Downtime doesn't Oracle,

when modifying is applied occur during this PostgreSQL,
a DB instance. For change.

308
 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
Choose Enable replication to information on asynchronously, as SQL
another AWS Region to create enabling cross- soon as possible. Server
backups in an additional Region Region backups
for disaster recovery. using the AWS CLI
or RDS API, see
Then choose the Destination Enabling cross-
Region for the additional Region automated
backups. backups (p. 400).

Backup retention period CLI option: If you choose to Downtime occurs if All DB
apply the change you change from 0 engines
The number of days that --backup- immediately, it to a nonzero value,
automatic backups are retained. retention-period occurs immediately. or from a nonzero
To disable automatic backups, value to 0.
set the backup retention period RDS API parameter:If you don't choose
to 0. to apply the change This applies to both
BackupRetentionPeriod
immediately, Single-AZ and Multi-
For more information, see and you change AZ DB instances.
Working with backups (p. 388). the setting
Note from a nonzero
If you use AWS Backup value to another
to manage your nonzero value, the
backups, this option change is applied
doesn't appear. For asynchronously, as
information about AWS soon as possible.
Backup, see the AWS Otherwise, the
Backup Developer Guide. change occurs
during the next
maintenance
window.

Backup window CLI option: The change Downtime 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. 388).
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.

309
 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

Certificate authority CLI option: If you choose to Downtime 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. 1883). immediately, it
CACertificateIdentifier
occurs during the
next maintenance
window.

Copy tags to snapshots CLI option: The change occurs Downtime 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. 359).
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. 215).

DB engine version CLI option: If you choose to Downtime 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. 331).

310
 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 class CLI option: If you choose to Downtime 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. 10). to apply the change
DBInstanceClass immediately, it
occurs during the
next maintenance
window.

DB instance identifier CLI option: If you choose to Downtime 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. 334). next maintenance
window.

DB parameter group CLI option: The parameter Downtime doesn't All DB

group change occurs occur during this engines
The DB parameter group that --db-parameter- immediately. change.
you want associated with the DB group-name
instance. When you associate
RDS API parameter: a new DB parameter
For more information, see group with a DB
Working with DB parameter DBParameterGroupName instance, the
groups (p. 284). modified static and
dynamic parameters
are applied only
after the DB
instance is rebooted.
However, if you
modify dynamic
parameters in the
newly associated DB
parameter group,
these changes are
applied immediately
without a reboot.

For more
information, see
Working with
DB parameter
groups (p. 284) and
Rebooting a DB
instance (p. 336).

311
 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

Deletion protection CLI option: The change occurs Downtime 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. 384).
DeletionProtection

Enhanced Monitoring CLI option: The change occurs Downtime 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 RDS API parameter:

Monitoring the OS by using
Enhanced Monitoring (p. 551). MonitoringInterval
and
MonitoringRoleArn

IAM DB authentication CLI option: If you choose to Downtime 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. 1909). RDS API parameter: next maintenance
window.
EnableIAMDatabaseAuthentication

Kerberos authentication CLI option: If you choose to A brief downtime Only

apply the change occurs during this Microsoft
Choose the Active Directory to --domain and -- immediately, it change. 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. 1878).

312
 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

License model CLI option: If you choose to Downtime 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. 823) and Oracle
licensing options (p. 1167).

Log exports CLI option: The change occurs Downtime 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. 595).

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 downtime, 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 downtime
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. 324).

313
 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

Multi-AZ deployment CLI option: If you choose to Downtime 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
Multi-AZ deployments for high MultiAZ immediately, it
availability (p. 59). occurs during the
next maintenance
window.

New master password CLI option: The change Downtime 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 Downtime 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. 268). OptionGroupName immediately, it
occurs during the
next maintenance
window.

Performance Insights CLI option: The change occurs Downtime 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

Monitoring DB load with
Performance Insights on
Amazon RDS (p. 487).

314
 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 AWS KMS CLI option: The change occurs Downtime 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 AWS KMS key for encryption key-id setting.
of Performance Insights data.
The key identifier is the Amazon RDS API parameter:
Resource Name (ARN), AWS KMS
key identifier, or the key alias for PerformanceInsightsKMSKeyId
the KMS key.

For more information, see

Enabling and disabling
Performance Insights (p. 490).

Performance Insights Retention CLI option: The change occurs Downtime 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. 490).

Processor features CLI option: If you choose to Downtime 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. 29). features next maintenance
window.
RDS API parameter:

ProcessorFeatures
and
UseDefaultProcessorFeatures

315
 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

Provisioned IOPS CLI option: If you choose to Downtime 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. 50).

Public access CLI option: The change occurs Downtime 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. 1977).

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

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

316
 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

Security group CLI option: The change Downtime 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. 1948).

Storage autoscaling CLI option: The change occurs Downtime 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. 377).

317
 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 engines
The storage type that you want --storage-type immediately, it in a brief downtime
to use. occurs immediately. while the process
RDS API parameter: starts. After that,
After Amazon RDS begins to If you don't choose you can use your
modify your DB instance to StorageType to apply the change database normally
change the storage size or immediately, it while the change
type, you can't submit another occurs during the takes place.
request to change the storage next maintenance
size or type for six hours. window. • From General
Purpose (SSD) to
For more information, Magnetic.
see Amazon RDS storage
types (p. 48). • From General
Purpose (SSD)
to Provisioned
IOPS (SSD). The
downtime only
happens if the
DB instance is
Single-AZ and
you are using a
custom parameter
group. There is
no downtime 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
downtime only
happens if the
DB instance is
Single-AZ and
you are using a
custom parameter
group. There is
no downtime for
a Multi-AZ DB
instance.

318
 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 Downtime 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. 1975).

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

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.

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

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

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

323
 Amazon Relational Database Service User Guide
The maintenance window

3. Perform maintenance on the old primary, which becomes the new standby.

When you modify the database engine for your DB instance in a Multi-AZ deployment, then Amazon
RDS upgrades both the primary and secondary DB instances at the same time. In this case, the database
engine for the entire Multi-AZ deployment is shut down during the upgrade.

For more information on Multi-AZ deployments, see Multi-AZ deployments for high availability (p. 59).

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

324
 Amazon Relational Database Service User Guide
Adjusting the maintenance window for a DB instance

Region Name Region Time Block

China (Ningxia) cn-northwest-1 06:00–14:00 UTC

Europe (Frankfurt) eu-central-1 21:00–05: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 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.

325
 Amazon Relational Database Service User Guide
Working with mandatory operating system updates

6. To apply the changes to the maintenance window immediately, select Apply immediately.
7. Choose Modify DB Instance to save your changes.

Alternatively, choose Back to edit your changes, or choose Cancel to cancel your changes.

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

Working with mandatory operating system updates

RDS for MySQL and RDS for PostgreSQL DB instances occasionally require mandatory operating system
updates. In some cases, these updates provide critical security fixes for specific vulnerabilities (such as
CVEs) which should be patched quickly. In other cases, Amazon RDS wants to upgrade the operating
system to a newer release to improve customers’ overall security posture. The mandatory operating
system updates described in this section are for the latter reason. Typically, the updates take about 10
minutes. The updates don't affect how the DB instances function.

Whether a mandatory operating system update is required for a DB instance depends on its DB engine
version and DB instance class. In the following sections, you can find descriptions of the affected DB
engine versions and DB instance classes for RDS for MySQL and RDS for PostgreSQL.

Topics
• Mandatory operating system updates for RDS for MySQL (p. 327)
• Mandatory operating system updates for RDS for PostgreSQL (p. 328)
• Recommended actions for mandatory operating system updates (p. 329)

326
 Amazon Relational Database Service User Guide
Working with mandatory operating system updates

Mandatory operating system updates for RDS for MySQL

We plan to use the following schedule for operating system updates for RDS for MySQL. For each date in
the table, the start time is 00:00 Universal Coordinated Time (UTC).

Action or recommendation Date range

We recommend that you update the operating system Now–January 31, 2022
for your RDS for MySQL DB instances.

To update the operating system, follow the instructions

in Applying updates for a DB instance (p. 322).

Amazon RDS starts automatic upgrades of the January 31, 2022–March 30, 2022
operating system for your RDS for MySQL DB instances
to the latest version in a maintenance window.

Amazon RDS starts automatic upgrades of the After March 30, 2022
operating system for your RDS for MySQL DB instances
to the latest version regardless of whether they are in a
maintenance window.

Amazon RDS won't upgrade the DB engine version or modify the DB instance class of your DB instances
automatically. For this operating system update to be required, a DB instance must be running the
versions with "Yes" in the following table for each DB instance class.

Mandatory operating system updates by version and DB instance class for RDS for MySQL

RDS for db.t2 db.r4 db.m4 db.t3 db.r5 db.m5

MySQL
version

8.0.23 and Yes Yes Yes Yes Yes Yes

higher 8.0
versions

8.0.21 and No No No No No No
lower 8.0
versions

5.7.33 and Yes Yes Yes Yes Yes Yes

higher 5.7
versions

5.7.31 and No No No No No No
lower 5.7
versions

5.6.51 and Yes Yes Yes Yes Yes Yes

higher 5.6
versions

5.6.49 and No No No No No No
lower 5.6
versions

327
 Amazon Relational Database Service User Guide
Working with mandatory operating system updates

Mandatory operating system updates for RDS for PostgreSQL

We plan to use the following schedule for operating system updates for RDS for PostgreSQL. For each
date in the table, the start time is 00:00 Universal Coordinated Time (UTC).

Action or recommendation Date range

We recommend that you update the operating system Now–January 10, 2022
for your RDS for PostgreSQL DB instances.

To update the operating system, follow the instructions

in Applying updates for a DB instance (p. 322).

Amazon RDS starts automatic upgrades of the January 10, 2022–March 30, 2022
operating system for your RDS for PostgreSQL DB
instances to the latest version in a maintenance window.

Amazon RDS starts automatic upgrades of the After March 30, 2022
operating system for your RDS for PostgreSQL DB
instances to the latest version regardless of whether
they are in a maintenance window.

Amazon RDS won't upgrade the DB engine version or modify the DB instance class of your DB instances
automatically. For this operating system update to be required, a DB instance must be running the
versions with "Yes" in the following table for each DB instance class.

Mandatory operating system updates by version and DB instance class for RDS for
PostgreSQL

RDS for db.t2 db.r4 db.m4 db.t3 db.r5 db.m5

PostgreSQL
version

All 13 No No No Yes Yes Yes

versions

12.7 and Yes Yes Yes Yes Yes Yes

higher 12
versions

12.6 No No No Yes Yes Yes

12.5 and No No No No No No
lower 12
versions

11.12 and Yes Yes Yes Yes Yes Yes

higher 11
versions

11.11 No No No Yes Yes Yes

11.10 and No No No No No No
lower 11
versions

328
 Amazon Relational Database Service User Guide
Working with mandatory operating system updates

RDS for db.t2 db.r4 db.m4 db.t3 db.r5 db.m5

PostgreSQL
version

10.17 and Yes Yes Yes Yes Yes Yes

higher 10
versions

10.16 No No No Yes Yes Yes

10.15 and No No No No No No
lower 10
versions

9.6.22 and Yes Yes Yes Yes Yes Yes

higher 9.6
versions

9.6.21 No No No Yes Yes Yes

9.6.20 and No No No Yes Yes Yes

lower 9.6
versions

Recommended actions for mandatory operating system updates

Whether a mandatory operating system update is required for a DB instance depends on its DB engine
version and DB instance class. You can find the affected DB engine versions and DB instance classes
in Mandatory operating system updates by DB engine version and DB instance class for RDS for
MySQL (p. 327) and Mandatory operating system updates by DB engine version and DB instance class
for RDS for PostgreSQL (p. 328).

If an operating system update is required for your DB instance based on its DB engine version and DB
instance class, the required update appears in the AWS Management Console. In this case, update the
operating system by following the instructions in Applying updates for a DB instance (p. 322).

If you are unable to identify any mandatory operating system updates in the AWS Management Console,
we recommend the following actions:

• Your DB instance doesn't use a DB engine version that requires this operating system update. Your DB
instance uses an affected DB instance class.

Take the following recommended actions:

1. Upgrade your DB engine version to a version that requires this operating system update. For more
information, see Upgrading a DB instance engine version (p. 331).
2. Update the operating system by following the instructions in Applying updates for a DB
instance (p. 322).
• Your DB instance uses a DB engine version that requires this operating system update. Your DB
instance uses an older DB instance class in a DB instance class family that is affected by this update.

We recommend that you modify your DB instance to use a DB instance class that requires this
operating system update. For example, if your DB instance uses a db.r3 DB instance class, we
recommend that you modify your DB instance to use a db.r4 or db.r5 DB instance class. Similarly, if
your DB instance uses a db.m3 DB instance class, we recommend that you modify your DB instance to
use a db.m4 or db.m5 DB instance class. In this case, you don't need to update the operating system
because the DB instance class modification applies the operating system update. You can also modify
your DB instance to use a different DB instance class family, such as db.m6g or db.r6g.

329
 Amazon Relational Database Service User Guide
Working with mandatory operating system updates

If your DB instance already uses a DB instance class that isn't in a DB instance class family that is
affected by this operating system update, then you don't need to modify its DB instance class. For
example, if your DB instance uses a db.m6g, db.x2g, or db.z1d DB instance class, then you don't need
to modify its DB instance class.

For more information about DB instance classes, see DB instance classes (p. 10). For more information
about modifying a DB instance, see Modifying an Amazon RDS DB instance (p. 306).
• Your DB instance doesn't use a DB engine version that requires this operating system update. Your DB
instance uses an older DB instance class in a DB instance class family that is affected by this operating
system update.

Take the following recommended actions:

1. Upgrade your DB engine version to a version that requires this operating system update. For more
information, see Upgrading a DB instance engine version (p. 331).
2. Modify your DB instance to use a newer DB instance class to use newer DB instance in the same DB
instance class family in a different DB instance class family.

For example, if your DB instance uses a db.r3 DB instance class, we recommend that you modify
your DB instance to use a db.r4 or db.r5 DB instance class. Similarly, if your DB instance uses a
db.m3 DB instance class, we recommend that you modify your DB instance to use a db.m4 or db.m5
DB instance class. In this case, you don't need to update the operating system because the DB
instance class modification applies the operating system update. You can also modify your DB
instance to use a different DB instance class family, such as db.m6g or db.r6g.

For more information about DB instance classes, see DB instance classes (p. 10). For more
information about modifying a DB instance, see Modifying an Amazon RDS DB instance (p. 306).

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

• Upgrading the Microsoft SQL Server DB engine (p. 835)
• Upgrading the MySQL DB engine (p. 1025)
• Upgrading the Oracle DB engine (p. 1398)
• Upgrading the PostgreSQL DB engine for Amazon RDS (p. 1774)

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. 331)
• Automatically upgrading the minor engine version (p. 333)

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.

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

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

• Modifying a DB instance (p. 306)
• Creating a read replica (p. 343)
• Restoring a DB instance from a snapshot (p. 411)
• Restoring a DB instance to a specific time (p. 455)
• Importing a DB instance from Amazon S3 (p. 1043) (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. 320).
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.

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

334
 Amazon Relational Database Service User Guide
Renaming to replace an existing DB instance

Important
The DB instance is rebooted when it is renamed.

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

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

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 DB 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 Multi-AZ
deployments for high availability (p. 59).

On RDS for Microsoft SQL Server, reboot with failover reboots only the primary DB instance. After
the failover, the primary DB instance becomes the new secondary DB instance. Parameters might not
be updated for Multi-AZ instances. For reboot without failover, both the primary and secondary DB
instances reboot, and parameters are updated after the reboot. If the DB instance is unresponsive, we
recommend reboot without failover.
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 isn't 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.

336
 Amazon Relational Database Service User Guide
Rebooting a DB instance

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.

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.

337
 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

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

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

You can configure a read replica for a DB instance that also has a standby replica configured for high
availability in a Multi-AZ deployment. 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 Multi-AZ deployments for high
availability (p. 59).

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

• Working with read replicas for Microsoft SQL Server in Amazon RDS (p. 865)
• Working with MySQL read replicas (p. 1072)
• Working with Oracle replicas for Amazon RDS (p. 1300)
• Working with PostgreSQL read replicas in Amazon RDS (p. 1787)

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

340
 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. 384). For information about read replica promotion, see
Promoting a read replica to be a standalone DB instance (p. 345).

If you have cross-Region read replicas, see Cross-Region replication considerations (p. 355) for
information related to deleting the source DB instance 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

341
 Amazon Relational Database Service User Guide
Overview

Feature or MySQL and MariaDB Oracle PostgreSQL SQL Server

behavior
logs on the source the slowest
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. 1246).

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.

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

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. 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)
ranges can overlap between the replica and the RDS system. CIDR overlap makes the replica

343
 Amazon Relational Database Service User Guide
Creating a read 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. 1975).
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 AWS KMS key, choose the AWS KMS key identifier of the KMS key.

Note
The source DB instance must be encrypted. To learn more about encrypting the source DB
instance, see Encrypting Amazon RDS resources (p. 1879).
9. Choose other options, such as storage autoscaling.
10. Choose Create read replica.

After the read replica is created, you can see it on the Databases page in the RDS console. It shows
Replica in the Role column.

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:

344
 Amazon Relational Database Service User Guide
Promoting a read replica

aws rds create-db-instance-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.

345
 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

346
 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. 306) and Multi-AZ deployments for high availability (p. 59).

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

347
 Amazon Relational Database Service User Guide
Monitoring read replication

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.

348
 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. 1082).
• 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. 1140) 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. 1140) stored procedure and replication is stopped because the
stop point was reached.

You can see where a DB instance is being replicated and if so, check its replication status. On the
Databases page in the RDS console, it shows Primary in the Role column. Choose its DB instance name.
On its detail page, on the Connectivity & security tab, its replication status is under Replication.

Monitoring replication lag

You can monitor replication lag in Amazon CloudWatch by viewing the Amazon RDS ReplicaLag
metric.

For MariaDB and MySQL, the ReplicaLag metric reports the value of the Seconds_Behind_Master
field of the SHOW REPLICA 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.

Note
Previous versions of MariaDB and MySQL used SHOW SLAVE STATUS instead of SHOW REPLICA
STATUS. If you are using a MariaDB version before 10.5 or a MySQL version before 8.0.23, then
use SHOW SLAVE STATUS.

349
 Amazon Relational Database Service User Guide
Creating a read replica in a different AWS Region

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

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.

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

351
 Amazon Relational Database Service User Guide
Creating a read replica in a different AWS Region

4. For Actions, choose Create read replica.

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 AWS KMS key, choose the AWS KMS key identifier of the KMS key in 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. 1879).
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. 369).

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

352
 Amazon Relational Database Service User Guide
Creating a read replica in a different AWS Region

--region us-west-2 \
--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 of the KMS key 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

353
 Amazon Relational Database Service User Guide
Creating a read replica in a different AWS Region

create an encrypted read replica in another AWS Region, you must specify a value for PreSignedURL.
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. 369).

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=&region-arn;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>

354
 Amazon Relational Database Service User Guide
Creating a read replica in a different AWS Region

is the identifier of the source instance, and <timestamp> is the date and time the copy started.
For example, rds:mysourceinstance-2013-11-14-09-24 was created from the instance
mysourceinstance at 2013-11-14-09-24. During the creation of an automated DB snapshot,
the source DB instance status remains modifying, the read replica status remains creating, and the DB
snapshot status is creating. The progress column of the DB snapshot page in the console reports how
far the DB snapshot creation has progressed. When the DB snapshot is complete, the status of both
the DB snapshot and source DB instance are set to available.
4. Amazon RDS begins a cross-Region snapshot copy for the initial data transfer. The snapshot copy is
listed as an automated snapshot in the destination AWS Region with a status of creating. It has the
same name as the source DB snapshot. The progress column of the DB snapshot display indicates how
far the copy has progressed. When the copy is complete, the status of the DB snapshot copy is set to
available.
5. Amazon RDS then uses the copied DB snapshot for the initial data load on the read replica. During this
phase, the read replica is in the list of DB instances in the destination, with a status of creating. When
the load is complete, the read replica status is set to available, and the DB snapshot copy is deleted.
6. When the read replica reaches the available status, Amazon RDS starts by replicating the changes
made to the source instance since the start of the create read replica operation. During this phase, the
replication lag time for the read replica is greater than 0.

For information about replication lag time, see Monitoring read replication (p. 348).

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 higher.
• Oracle Enterprise Edition (EE) of Oracle Database 12c Release 1 (12.1) using 12.1.0.2.v10 and higher,
Oracle Database 12c Release 2 (12.2), and Oracle Database 19c.

An Active Data Guard license is required. For information about limitations for Oracle cross-Region
read replicas, see Replica requirements for Oracle (p. 1301).
• 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.
• 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 and DB option group for the specified DB
engine.
• The read replica uses the default security group.
• For MariaDB, MySQL, and Oracle DB instances, when the source DB instance for a cross-Region read
replica is deleted, the read replica is promoted.

355
 Amazon Relational Database Service User Guide
Creating a read replica in a different AWS Region

• For PostgreSQL DB instances, when the source DB instance 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.

You have to promote the read replica manually or delete it.

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

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

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

358
 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. 359)
• Using tags for access control with IAM (p. 360)
• Using tags to produce detailed billing reports (p. 360)
• Adding, listing, and removing tags (p. 360)
• Using the AWS Tag Editor (p. 363)
• Copying tags to DB instance snapshots (p. 363)
• Tutorial: Use tags to specify which DB instances to stop (p. 364)
• Using tags to enable backups in AWS Backup (p. 366)

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

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

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

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 Using Cost Allocation Tags in
the AWS Billing and Cost Management User Guide.
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.

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

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

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

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.

362
 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 aws: or rds:. 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 aws: or rds:.
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

363
 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-identifier 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 \

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

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

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

367
 Amazon Relational Database Service User Guide
Enabling backups

{
"TagList": [
{
"Key": "BackupPlan",
"Value": "Test"
}
]
}

368
 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

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

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

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

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)

369
 Amazon Relational Database Service User Guide
Constructing an ARN

Region Region Endpoint Protocol

Name

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)

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

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

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)

370
 Amazon Relational Database Service User Guide
Constructing an ARN

Region Region Endpoint Protocol

Name

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

GovCloud west-1
(US-West)

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:

371
 Amazon Relational Database Service User Guide
Getting an existing ARN

Resource type ARN format

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:

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.

372
 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

373
 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

374
 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

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

Topics
• Increasing DB instance storage capacity (p. 376)
• Managing capacity automatically with Amazon RDS storage autoscaling (p. 377)
• Modifying SSD storage settings for Provisioned IOPS (p. 382)

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

Scaling storage usually doesn't cause any outage or performance degradation of the DB instance. After
you modify the storage size for a DB instance, the status of the DB instance is storage-optimization.
Note
Storage optimization can take several hours. You can't make further storage modifications for
either six (6) hours or until storage optimization has completed on the instance, whichever is
longer.

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.
3. Choose the DB instance that you want to modify.

376
 Amazon Relational Database Service User Guide
Managing capacity automatically with storage autoscaling

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 apply the storage changes immediately.

Or use --no-apply-immediately (the default) to apply the 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. 48).

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 the storage changes immediately. Set
this option to False (the default) to apply the 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. 48).

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.

377
 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, or storage optimization has
completed on the instance, whichever is longer.

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.

Limitations
The following limitations apply to storage autoscaling:

• Autoscaling doesn't occur if the maximum storage threshold would be equaled or exceeded by the
storage increment.
• Autoscaling can't completely prevent storage-full situations for large data loads. This is because
further storage modifications can't be made for either six (6) hours or until storage optimization has
completed on the instance, whichever is longer.

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.

378
 Amazon Relational Database Service User Guide
Managing capacity automatically with storage autoscaling

• Autoscaling operations aren't logged by AWS CloudTrail. For more information on CloudTrail, see
Working with AWS CloudTrail and Amazon RDS (p. 632).

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.

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

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

Amazon RDS API

To enable storage autoscaling for a new DB instance, use the Amazon RDS API operation
CreateDBInstance. Set the following parameter:

379
 Amazon Relational Database Service User Guide
Managing capacity automatically with storage autoscaling

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

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

380
 Amazon Relational Database Service User Guide
Managing capacity automatically with storage autoscaling

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.

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

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

Amazon RDS API

To turn off storage autoscaling for a DB instance, use the Amazon RDS API operation
ModifyDBInstance. Set the following parameter:

381
 Amazon Relational Database Service User Guide
Modifying Provisioned IOPS

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

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.
Note
Storage optimization can take several hours. You can't make further storage modifications for
either six (6) hours or until storage optimization has completed on the instance, whichever is
longer.

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.

382
 Amazon Relational Database Service User Guide
Modifying Provisioned IOPS

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

383
 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 you delete a DB instance that has read replicas in the same AWS Region, each read replica is promoted
to a standalone DB instance. For more information, see Promoting a read replica to be a standalone
DB instance (p. 345). If your DB instance has read replicas in different AWS Regions, see Cross-Region
replication considerations (p. 355) for information related to deleting the source DB instance for a cross-
Region read replica.
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. 1883).

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
Viewing DB instance status (p. 470).
• 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.

384
 Amazon Relational Database Service User Guide
Deleting a 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. 398).
• You typically don't need to retain automated backups if you create a final DB snapshot.
• To delete a retained automated backup, follow the instructions in Deleting retained automated
backups (p. 393).

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

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. 384).
You can disable deletion protection by modifying the DB instance. For more information, see
Modifying an Amazon RDS DB instance (p. 306).

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

385
 Amazon Relational Database Service User Guide
Deleting a DB instance

• --final-db-snapshot-identifier or --skip-final-snapshot

Example With a final snapshot and no retained automated backups

For Linux, macOS, or Unix:

aws rds delete-db-instance \

--db-instance-identifier mydbinstance \
--final-db-snapshot-identifier mydbinstancefinalsnapshot \
--delete-automated-backups

For Windows:

aws rds delete-db-instance ^

--db-instance-identifier mydbinstance ^
--final-db-snapshot-identifier mydbinstancefinalsnapshot ^
--delete-automated-backups

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

386
 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. 388)
• Replicating automated backups to another AWS Region (p. 398)
• Creating a DB snapshot (p. 409)
• Restoring from a DB snapshot (p. 411)
• Copying a snapshot (p. 414)
• Sharing a DB snapshot (p. 428)
• Exporting DB snapshot data to Amazon S3 (p. 437)
• Restoring a DB instance to a specified time (p. 455)
• Deleting a snapshot (p. 458)
• Tutorial: Restore a DB instance from a DB snapshot (p. 460)

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

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. 414). For more information
about sharing a DB snapshot, see Sharing a DB snapshot (p. 428).

Topics
• Backup storage (p. 388)
• Backup window (p. 389)
• Backup retention period (p. 390)
• Enabling automated backups (p. 390)
• Retaining automated backups (p. 392)
• Deleting retained automated backups (p. 393)
• Disabling automated backups (p. 394)
• Using AWS Backup to manage automated backups (p. 396)
• Automated backups with unsupported MySQL storage engines (p. 396)
• Automated backups with unsupported MariaDB storage engines (p. 397)

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

388
 Amazon Relational Database Service User Guide
Backup window

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
taken from the standby. For SQL Server, I/O activity is suspended briefly during backup for Multi-AZ
deployments.

Automated backups might occasionally be skipped if the DB instance has a heavy workload at the time a
backup is supposed to start. If a backup is skipped, you can still do a point-in-time-recovery (PITR), and a
backup is still attempted during the next backup window. For more information on PITR, see Restoring a
DB instance to a specified time (p. 455).

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

389
 Amazon Relational Database Service User Guide
Backup retention period

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

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

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

390
 Amazon Relational Database Service User Guide
Enabling automated backups

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.

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

Viewing automated backups

To view your automated backups, choose Automated backups in the navigation pane. To view
individual snapshots associated with an automated backup, choose Snapshots in the navigation pane.

391
 Amazon Relational Database Service User Guide
Retaining automated backups

Alternatively, you can describe individual snapshots associated with an automated backup. From there,
you can restore a DB instance directly from one of those snapshots.

To describe the automated backups for your existing DB instances 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 the retained automated backups for your existing DB instances using the RDS API, call the
DescribeDBInstanceAutomatedBackups action with one of the following parameters:

• DBInstanceIdentifier
• DbiResourceId

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. 392)
• Viewing retained backups (p. 393)
• Restoration (p. 393)
• Retention costs (p. 393)
• Limitations and recommendations (p. 393)

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.

392
 Amazon Relational Database Service User Guide
Deleting retained automated backups

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, choose Automated backups in the navigation pane, then
choose Retained. To view individual snapshots associated with a retained automated backup, choose
Snapshots in the navigation pane. 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 the following command:

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 the DbiResourceId parameter.

Restoration
For information on restoring DB instances from automated backups, see Restoring a DB instance to a
specified time (p. 455).

Retention costs
The cost of a retained automated backup is the cost of total storage of the system snapshots that are
associated with it. There is no additional charge for transaction logs or instance metadata. All other
pricing rules for backups apply to restorable instances.

For example, suppose that your total allocated storage of running instances is 100 GB. Suppose also
that you have 50 GB of manual snapshots plus 75 GB of system snapshots associated with a retained
automated backup. In this case, you are charged only for the additional 25 GB of backup storage, like
this: (50 GB + 75 GB) – 100 GB = 25 GB.

Limitations and recommendations

The following limitations apply to retained automated backups:

• The maximum number of retained automated backups in one 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.

393
 Amazon Relational Database Service User Guide
Disabling automated backups

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 ^

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

394
 Amazon Relational Database Service User Guide
Disabling automated backups

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

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

395
 Amazon Relational Database Service User Guide
Using AWS Backup

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

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

396
 Amazon Relational Database Service User Guide
Unsupported MariaDB storage engines

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

Automated backups with unsupported MariaDB

storage engines
For the MariaDB DB engine, automated backups are only supported with the InnoDB storage engine.
Use of these features with other MariaDB storage engines, including Aria, might lead to unreliable
behavior while restoring from backups. Even though Aria is a crash-resistant alternative to MyISAM, your
tables can still be corrupted in the event of a crash. For this reason, we encourage you to use the XtraDB
storage engine.

• To convert existing Aria tables to InnoDB tables, you can use the ALTER TABLE command. For
example: ALTER TABLE table_name ENGINE=innodb, ALGORITHM=COPY;
• To convert existing Aria tables to XtraDB tables, you can use the ALTER TABLE command. For
example: ALTER TABLE table_name ENGINE=xtradb, ALGORITHM=COPY;
• If you choose to use Aria, you can attempt to manually repair tables that become damaged after a
crash by using the REPAIR TABLE command. For more information, see http://mariadb.com/kb/en/
mariadb/repair-table/.
• If you want to take a snapshot of your Aria tables before restoring, follow these steps:
1. Stop all activity to your Aria tables (that is, close all sessions).
2. Lock and flush each of your Aria tables.
3. Create a snapshot of your DB instance. When the snapshot has completed, release the locks and
resume activity on the Aria tables. These steps force Aria to flush data stored in memory to disk,
thereby ensuring a clean start when you restore from a DB snapshot.

397
 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 Database version 12.1.0.2.v10 and higher

• PostgreSQL version 9.6 and higher
• Microsoft SQL Server version 2012 and higher

Backup replication isn't supported for encrypted SQL Server DB instances.

For an example of using backup replication, see the AWS online tech talk Managed Disaster Recovery
with Amazon RDS for Oracle Cross-Region Automated Backups.

Topics
• AWS Region support (p. 398)
• Enabling cross-Region automated backups (p. 400)
• Finding information about replicated backups (p. 402)
• Restoring to a specified time from a replicated backup (p. 405)
• Stopping automated backup replication (p. 406)
• Deleting replicated backups (p. 407)

AWS Region support

Backup replication is supported between the following AWS Regions.

Source Region Destination Regions available

Asia Pacific (Mumbai) Asia Pacific (Singapore)

US East (N. Virginia), US East (Ohio), US West (Oregon)

Asia Pacific (Osaka) Asia Pacific (Tokyo)

Asia Pacific (Seoul) Asia Pacific (Singapore), Asia Pacific (Tokyo)

US East (N. Virginia), US East (Ohio), US West (Oregon)

Asia Pacific (Singapore) Asia Pacific (Mumbai), Asia Pacific (Seoul), Asia Pacific (Sydney), Asia Pacific
(Tokyo)

US East (N. Virginia), US East (Ohio), US West (Oregon)

Asia Pacific (Sydney) Asia Pacific (Singapore)

398
 Amazon Relational Database Service User Guide
AWS Region support

Source Region Destination Regions available

US East (N. Virginia), US West (N. California), US West (Oregon)

Asia Pacific (Tokyo) Asia Pacific (Osaka), Asia Pacific (Seoul), Asia Pacific (Singapore)

US East (N. Virginia), US East (Ohio), US West (Oregon)

Canada (Central) Europe (Ireland)

US East (N. Virginia), US East (Ohio), US West (N. California), US West (Oregon)

China (Beijing) China (Ningxia)

China (Ningxia) China (Beijing)

Europe (Frankfurt) Europe (Ireland), Europe (London), Europe (Paris), Europe (Stockholm)

US East (N. Virginia), US East (Ohio), US West (Oregon)

Europe (Ireland) Canada (Central)

Europe (Frankfurt), Europe (London), Europe (Paris), Europe (Stockholm)

US East (N. Virginia), US East (Ohio), US West (N. California), US West (Oregon)

Europe (London) Europe (Frankfurt), Europe (Ireland), Europe (Paris), Europe (Stockholm)

US East (N. Virginia)

Europe (Paris) Europe (Frankfurt), Europe (Ireland), Europe (London), Europe (Stockholm)

US East (N. Virginia)

Europe (Stockholm) Europe (Frankfurt), Europe (Ireland), Europe (London), Europe (Paris)

US East (N. Virginia)

South America (São Paulo) US East (N. Virginia), US East (Ohio)

AWS GovCloud (US-East) AWS GovCloud (US-West)

AWS GovCloud (US-West) AWS GovCloud (US-East)

US East (N. Virginia) Asia Pacific (Mumbai), Asia Pacific (Seoul), Asia Pacific (Singapore), Asia Pacific
(Sydney), Asia Pacific (Tokyo)

Canada (Central)

Europe (Frankfurt), Europe (Ireland), Europe (London), Europe (Paris), Europe

(Stockholm)

South America (São Paulo)

US East (Ohio), US West (N. California), US West (Oregon)

399
 Amazon Relational Database Service User Guide
Enabling cross-Region automated backups

Source Region Destination Regions available

US East (Ohio) Asia Pacific (Mumbai), Asia Pacific (Seoul), Asia Pacific (Singapore), Asia Pacific
(Tokyo)

Canada (Central)

Europe (Frankfurt), Europe (Ireland)

South America (São Paulo)

US East (N. Virginia), US West (N. California), US West (Oregon)

US West (N. California) Asia Pacific (Sydney)

Canada (Central)

Europe (Ireland)

US East (N. Virginia), US East (Ohio), US West (Oregon)

US West (Oregon) Asia Pacific (Mumbai), Asia Pacific (Seoul), Asia Pacific (Singapore), Asia Pacific
(Sydney), Asia Pacific (Tokyo)

Canada (Central)

Europe (Frankfurt), Europe (Ireland)

US East (N. Virginia), US East (Ohio), US West (N. California)

You can also use the describe-source-regions AWS CLI command to find out which AWS
Regions can replicate to each other. For more information, see Finding information about replicated
backups (p. 402).

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

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

400
 Amazon Relational Database Service User Guide
Enabling cross-Region 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. If you've enabled encryption on the source DB instance, choose the AWS KMS key for encrypting the
backups.
9. Choose Save.

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. It also encrypts the replicated backups, using an AWS KMS key
in the destination Region.
Note
If you encrypt the backups, you must also include the --source-region option. Specifying the
source AWS Region autogenerates a presigned URL that is a valid request for the operation that
can be executed in the source Region.
For more information on presigned URLs, see Authenticating Requests: Using Query Parameters
(AWS Signature Version 4) in the Amazon Simple Storage Service API Reference and Signature
Version 4 signing process in the AWS General Reference.

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" \
--kms-key-id "arn:aws:kms:us-east-1:123456789012:key/AKIAIOSFODNN7EXAMPLE" \
--source-region us-west-2 \
--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" ^
--kms-key-id "arn:aws:kms:us-east-1:123456789012:key/AKIAIOSFODNN7EXAMPLE" ^
--source-region us-west-2 ^
--backup-retention-period 7

401
 Amazon Relational Database Service User Guide
Finding information about replicated backups

RDS API
Enable backup replication by using the StartDBInstanceAutomatedBackupsReplication RDS API
operation with the following parameters:

• Region
• SourceDBInstanceArn
• BackupRetentionPeriod
• KmsKeyId (optional)
• PreSignedUrl (required if you use KmsKeyId)

Note
If you encrypt the backups, you must also include a presigned URL. For more information on
presigned URLs, see Authenticating Requests: Using Query Parameters (AWS Signature Version
4) in the Amazon Simple Storage Service API Reference and Signature Version 4 signing process in
the AWS General Reference.

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.

aws rds describe-source-regions --region us-west-2

The output shows that backups can be replicated from US East (N. Virginia), but not from US East (Ohio)
or US West (N. California), into US West (Oregon).

{
"SourceRegions": [
...
{
"RegionName": "us-east-1",
"Endpoint": "https://rds.us-east-1.amazonaws.com",
"Status": "available",
"SupportsDBInstanceAutomatedBackupsReplication": true
},
{
"RegionName": "us-east-2",
"Endpoint": "https://rds.us-east-2.amazonaws.com",
"Status": "available",
"SupportsDBInstanceAutomatedBackupsReplication": false
},
"RegionName": "us-west-1",
"Endpoint": "https://rds.us-west-1.amazonaws.com",

402
 Amazon Relational Database Service User Guide
Finding information about replicated backups

"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"}]
}
]
}

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

403
 Amazon Relational Database Service User Guide
Finding information about replicated backups

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 ^

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

404
 Amazon Relational Database Service User Guide
Point-in-time recovery from a replicated backup

"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. 455).
Note
On RDS for SQL Server, option groups aren't copied across AWS Regions when automated
backups are replicated. If you've associated a custom option group with your RDS for SQL Server
DB instance, you can re-create that option group in the destination Region. Then restore the
DB instance in the destination Region and associate the custom option group with it. For more
information, see Working with option groups (p. 268).

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

405
 Amazon Relational Database Service User Guide
Stopping backup replication

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

406
 Amazon Relational Database Service User Guide
Deleting replicated backups

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
DeleteDBInstanceAutomatedBackup RDS API operation.

Console
Delete replicated backups in the destination Region from the Automated backups page.

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.

407
 Amazon Relational Database Service User Guide
Deleting replicated backups

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

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.

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

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

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. Enter the name of the snapshot in the Snapshot name box.

6. Choose Take snapshot.

409
 Amazon Relational Database Service User Guide
Creating a DB snapshot

The Snapshots page appears, with the new DB snapshot's status shown as Creating. After its status is
Available, you can see its creation time.

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:

• DBInstanceIdentifier
• DBSnapshotIdentifier

410
 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 new DB instance by restoring from a DB snapshot.
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 use the restored DB instance as soon as its status is available. The DB instance continues to
load data in the background. This is known as lazy loading.

If you access data that hasn't been loaded yet, the DB instance immediately downloads the requested
data from Amazon S3, and then continues loading the rest of the data in the background. For more
information, see Amazon EBS snapshots.

To help mitigate the effects of lazy loading on tables to which you require quick access, you can perform
operations that involve full-table scans, such as SELECT *. This allows Amazon RDS to download all of
the backed-up table data from S3.

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.

You can use AWS CloudFormation to restore a DB instance from a DB instance snapshot. For more
information, see AWS::RDS::DBInstance in the AWS CloudFormation User Guide.
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. 414).

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

411
 Amazon Relational Database Service User Guide
Option groups

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

Option group considerations

When you restore a DB instance, the option group associated with the DB snapshot is associated with
the restored DB instance after it is created. For example, if the DB snapshot you are restoring from uses
Oracle Transparent Data Encryption, the restored DB instance will use the same option group.

When you assign an option group to a DB instance, the option group is also linked to the supported
platform the DB instance is on, either VPC or EC2-Classic (non-VPC). If a DB instance is in a VPC, the
option group associated with the DB instance is linked to that VPC. This means that you can't use the
option group assigned to a DB instance if you attempt to restore the instance into a different VPC or
onto a different platform. If you restore a DB instance into a different VPC or onto a different platform,
you must either assign the default option group to the instance, assign an option group that is linked
to that VPC or platform, or create a new option group and assign it to the DB instance. For persistent
or permanent options, when restoring a DB instance into a different VPC you must create a new option
group that includes the persistent or permanent option.

Microsoft SQL Server considerations

When you restore an RDS for 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 limitations apply 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 isn't supported by restoring a snapshot,
you can try using the native backup and restore feature. SQL Server verifies whether 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. 840).

Oracle Database 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, specify a parameter group that has a matching or
greater compatible value.

If you restore a snapshot of a CDB instance, you can change the PDB name. You can't change the CDB
name, which is always RDSCDB. This CDB name is the same for all RDS instances that use a single-tenant
architecture. For more information, see Snapshots in a single-tenant architecture (p. 1174).

Before you restore a DB snapshot, you can upgrade it to a later release. For more information, see
Upgrading an Oracle DB snapshot (p. 1405).

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.

412
 Amazon Relational Database Service User Guide
Restoring from a snapshot

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.

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

413
 Amazon Relational Database Service User Guide
Copying a snapshot

Copying a snapshot
With Amazon RDS, you can copy automated backups or manual DB snapshots. After you copy a
snapshot, the copy is a manual snapshot. You can make multiple copies of an automated backup or
manual snapshot, but each copy must have a unique identifier.

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 backups in several situations:

• At the end of their retention period.

• When you disable automated backups for a DB instance.
• When you delete a DB instance.

If you want to keep an automated backup 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 key 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 KMS key as the initial full snapshot. If you use a

414
 Amazon Relational Database Service User Guide
Handling encryption

different KMS key to encrypt subsequent snapshots when copying them, those shared snapshots
are full snapshots. For more information, see Incremental snapshot copying (p. 415).

Handling encryption
You can copy a snapshot that has been encrypted using a KMS key. 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 KMS key as the original snapshot. Or you can
specify a different KMS key. If you copy an encrypted snapshot across Regions, you can't use the same
KMS key for the copy as used for the source snapshot. This is because KMS keys are Region-specific.
Instead, you must specify a KMS key 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. 1881).

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 a KMS key 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:

• A different snapshot of the same source DB instance 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 KMS key.

The following examples illustrate the difference between full and incremental snapshots. They apply to
both shared and unshared snapshots.

Snapshot Encryption key Full or incremental

S1 K1 Full

S2 K1 Incremental of S1

415
 Amazon Relational Database Service User Guide
Cross-Region copying

Snapshot Encryption key Full or incremental

S3 K1 Incremental of S2

S4 K1 Incremental of S3

Copy of S1 (S1C) K2 Full

Copy of S2 (S2C) K3 Full

Copy of S3 (S3C) K3 Incremental of S2C

Copy of S4 (S4C) K3 Incremental of S3C

Copy 2 of S4 (S4C2) K4 Full

Note
In these examples, snapshots S2, S3, and S4 are incremental only if the previous snapshot still
exists.
The same applies to copies. Snapshot copies S3C and S4C are incremental only if the previous
copy still exists.

For information on copying incremental snapshots across AWS Regions, see Full and incremental
copies (p. 419).

Cross-Region snapshot copying

You can copy DB snapshots across AWS Regions. However, there are certain constraints and
considerations for cross-Region snapshot 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",

416
 Amazon Relational Database Service User Guide
Cross-Region copying

"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",
"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"
}
}

417
 Amazon Relational Database Service User Guide
Cross-Region copying

},
{
"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.

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

418
 Amazon Relational Database Service User Guide
Option groups

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

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 KMS key.

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.

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.

419
 Amazon Relational Database Service User Guide
Copying a DB snapshot

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

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.

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

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

You can make multiple copies of an automated backup or manual snapshot, but each copy must
have a unique identifier.
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. 419).
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 AWS KMS key, specify the 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.

422
 Amazon Relational Database Service User Guide
Copying a DB snapshot

If your source DB instance uses Transparent Data Encryption for Oracle or Microsoft SQL Server,
you must specify this option when copying across Regions. For more information, see Option group
considerations (p. 419).
• --kms-key-id – The KMS key identifier for an encrypted DB snapshot. The KMS key identifier is the
Amazon Resource Name (ARN), key identifier, or key alias for the KMS key.
• If you copy an encrypted DB snapshot from your AWS account, you can specify a value for this
parameter to encrypt the copy with a new KMS key. If you don't specify a value for this parameter,
then the copy of the DB snapshot is encrypted with the same KMS key as the source DB snapshot.
• If you copy an encrypted DB snapshot that is shared from another AWS account, then you must
specify a value for this parameter.
• If you specify this parameter when you copy an unencrypted snapshot, the copy is encrypted.
• If you copy an encrypted snapshot to a different AWS Region, then you must specify a KMS key for
the destination AWS Region. KMS keys are specific to the AWS Region that they are created in, and
you cannot use encryption keys from one AWS Region in another AWS Region.
• --source-region – The ID of the AWS Region of the source DB snapshot. If you copy an encrypted
snapshot to a different AWS Region, then you must specify this option.

Example from unencrypted, to 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 ^

423
 Amazon Relational Database Service User Guide
Copying a DB snapshot

--target-db-snapshot-identifier mydbsnapshotcopy

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

424
 Amazon Relational Database Service User Guide
Copying a DB snapshot

• KmsKeyId – The KMS key identifier for an encrypted DB snapshot. The KMS key identifier is the
Amazon Resource Name (ARN), key identifier, or key alias for the KMS key.
• If you copy an encrypted DB snapshot from your AWS account, you can specify a value for this
parameter to encrypt the copy with a new KMS key. If you don't specify a value for this parameter,
then the copy of the DB snapshot is encrypted with the same KMS key as the source DB snapshot.
• If you copy an encrypted DB snapshot that is shared from another AWS account, then you must
specify a value for this parameter.
• If you specify this parameter when you copy an unencrypted snapshot, the copy is encrypted.
• If you copy an encrypted snapshot to a different AWS Region, then you must specify a KMS key for
the destination AWS Region. KMS keys are specific to the AWS Region that they are created in, and
you cannot use encryption keys from one AWS Region in another AWS Region.
• PreSignedUrl – The URL that contains a Signature Version 4 signed request for the
CopyDBSnapshot API 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 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

425
 Amazon Relational Database Service User Guide
Copying a DB snapshot

&SourceDBSnapshotIdentifier=mysql-instance1-snapshot-20130805
&TargetDBSnapshotIdentifier=mydbsnapshotcopy
&Version=2013-09-09
&X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=AKIADQKE4SARGYLE/20140429/us-west-1/rds/aws4_request
&X-Amz-Date=20140429T175351Z
&X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date
&X-Amz-Signature=9164337efa99caf850e874a1cb7ef62f3cea29d0b448b9e0e7c53b288ddffed2

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

426
 Amazon Relational Database Service User Guide
Copying a DB snapshot

&X-Amz-Date=20161117T221704Z
&X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date
&X-Amz-Signature=da4f2da66739d2e722c85fcfd225dc27bba7e2b8dbea8d8612434378e52adccf

427
 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. 414). For more information on
restoring a DB instance from a DB snapshot, see Restoring from a DB snapshot (p. 411).

You can share a manual snapshot with up to 20 other AWS accounts.

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 can't 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 can't be removed from an option group. Option groups with persistent options
can't be removed from a DB instance once the option group has been assigned to the DB instance.

The following table lists permanent and persistent options and their related DB engines.

Option name Persistent Permanent DB engine

TDE Yes No Microsoft SQL Server Enterprise

Edition

TDE Yes Yes Oracle Enterprise Edition

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. 1385) and
Oracle Label Security (p. 1350).

428
 Amazon Relational Database Service User Guide
Sharing public snapshots

Sharing public snapshots

You can also share an unencrypted manual snapshot as public, which makes the snapshot available to
all AWS accounts. Make sure when sharing a snapshot as public that none of your private information is
included in the public snapshot.

When a snapshot is shared publicly, it gives all AWS accounts permission both to copy the snapshot and
to create DB instances from it.

You aren't billed for the backup storage of public snapshots owned by other accounts. You're billed only
for snapshots that you own.

If you copy a public snapshot, you own the copy. You're billed for the backup storage of your snapshot
copy. If you create a DB instance from a public snapshot, you're billed for that DB instance. For Amazon
RDS pricing information, see the Amazon RDS product page.

You can delete only the public snapshots that you own. To delete a shared or public snapshot, make sure
to log into the AWS account that owns the snapshot.

Viewing public snapshots owned by other AWS accounts

You can view public snapshots owned by other accounts in a particular AWS Region on the Public tab of
the Snapshots page in the Amazon RDS console. Your snapshots (those owned by your account) don't
appear on this tab.

To view public snapshots

1. Open the Amazon RDS console at https://console.aws.amazon.com/rds/.

2. In the navigation pane, choose Snapshots.
3. Choose the Public tab.

The public snapshots appear. You can see which account owns a public snapshot in the Owner
column.
Note
You might have to modify the page preferences, by selecting the gear icon at the upper
right of the Public snapshots list, to see this column.

Viewing your own public snapshots

You can use the following AWS CLI command (Unix only) to view the public snapshots owned by 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.

429
 Amazon Relational Database Service User Guide
Sharing encrypted snapshots

Sharing encrypted snapshots

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. 1879). To do this, take the following steps:

1. Share the AWS KMS key that was used to encrypt the snapshot with any accounts that you want to be
able to access the snapshot.

You can share KMS keys with another AWS account by adding the other account to the KMS key policy.
For details on updating a key policy, see Key policies in the AWS KMS Developer Guide. For an example
of creating a key policy, see Allowing access to an AWS KMS key (p. 430) 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 KMS key of the AWS account
that shared the snapshot.

Allowing access to an AWS KMS key

For another AWS account to copy an encrypted DB snapshot shared from your account, the account that
you share your snapshot with must have access to the AWS KMS key that encrypted the snapshot.

To allow another AWS account access to a KMS key, update the key policy for the KMS key. You update it
with the Amazon Resource Name (ARN) of the AWS account that you are sharing to as Principal in the
KMS key policy. Then you allow the kms:CreateGrant action.

After you have given an AWS account access to your KMS key, to copy your encrypted snapshot that AWS
account must create an AWS Identity and Access Management (IAM) role or user if it doesn't already have
one. In addition, that AWS account must also attach an IAM policy to that IAM role or user that allows
the role or user to copy an encrypted DB snapshot using your KMS key. The account must be an IAM user
and cannot be a root AWS account identity due to AWS KMS security restrictions.

In the following key policy example, user 111122223333 is the owner of the KMS key, and user
444455556666 is the account that the key is being shared with. This updated key policy gives the
AWS account access to the KMS key by including the ARN for the root AWS account identity for user
444455556666 as a Principal for the policy, and by allowing the kms:CreateGrant action.

{
"Id": "key-policy-1",
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Allow use of the key",
"Effect": "Allow",
"Principal": {"AWS": [
"arn:aws:iam::111122223333:user/KeyUser",
"arn:aws:iam::444455556666:root"
]},
"Action": [
"kms:CreateGrant",

430
 Amazon Relational Database Service User Guide
Sharing encrypted snapshots

"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 KMS key, the owner of that AWS account can create
a policy that allows an IAM user created for that account to copy an encrypted snapshot encrypted with
that KMS key.

The following example shows a policy that can be attached to an IAM user for AWS account
444455556666 that enables the IAM user to copy a shared snapshot from AWS account 111122223333
that has been encrypted with the KMS key c989c1dd-a3f2-4a5d-8d96-e793d082ab26 in the us-
west-2 region.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowUseOfTheKey",
"Effect": "Allow",
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:DescribeKey",
"kms:CreateGrant",
"kms:RetireGrant"
],
"Resource": ["arn:aws:kms:us-west-2:111122223333:key/c989c1dd-a3f2-4a5d-8d96-
e793d082ab26"]
},
{
"Sid": "AllowAttachmentOfPersistentResources",
"Effect": "Allow",
"Action": [
"kms:CreateGrant",
"kms:ListGrants",
"kms:RevokeGrant"

431
 Amazon Relational Database Service User Guide
Sharing a snapshot

],
"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.
• 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.

432
 Amazon Relational Database Service User Guide
Sharing a snapshot

7. After you have added identifiers for all of the AWS accounts that you want to permit to restore the
manual snapshot, choose Save to save your changes.

To stop sharing a manual DB snapshot with an AWS account

1. Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.
2. In the navigation pane, choose Snapshots.
3. Select the manual snapshot that you want to stop sharing.
4. Choose Actions, and then choose Share Snapshot.
5. To remove permission for an AWS account, choose Delete for the AWS account identifier for that
account from the list of authorized accounts.

433
 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

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

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

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

After the data is exported, you can analyze the exported data directly through tools like Amazon Athena
or Amazon Redshift Spectrum. For more information on using Athena to read Parquet data, see Parquet
SerDe in the Amazon Athena User Guide. For more information on using Redshift Spectrum to read
Parquet data, see COPY from columnar data formats in the Amazon Redshift Database Developer Guide.

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 All 12 and 13 versions

10.2.12 and higher 5.7.24 and higher 11.2 and higher

5.6.40 and higher 10.7 and higher

9.6.6–9.6.9, 9.6.12 and higher

For complete lists of engine versions supported by Amazon RDS, see the following:

• MariaDB on Amazon RDS versions (p. 745)

• MySQL on Amazon RDS versions (p. 1000)
• Supported PostgreSQL database versions (p. 1696)

Topics
• Limitations (p. 438)
• Overview of exporting snapshot data (p. 438)
• Setting up access to an Amazon S3 bucket (p. 439)
• Using a cross-account AWS KMS key for encrypting Amazon S3 exports (p. 441)
• Exporting a snapshot to an Amazon S3 bucket (p. 442)
• Monitoring snapshot exports (p. 445)
• Canceling a snapshot export task (p. 446)
• Failure messages for Amazon S3 export tasks (p. 447)

437
 Amazon Relational Database Service User Guide
Limitations

• Troubleshooting PostgreSQL permissions errors (p. 448)

• File naming convention (p. 448)
• Data conversion when exporting to an Amazon S3 bucket (p. 449)

Limitations
Exporting DB snapshot data to Amazon 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 large object such as a BLOB or CLOB, 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. 439).
b. 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. 439).
3. Create an AWS KMS key for the server-side encryption. The KMS key 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. 1879).

You can use a KMS key within your AWS account, or you can use a cross-account KMS key. For more
information, see Using a cross-account AWS KMS key for encrypting Amazon S3 exports (p. 441).
4. 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. 442).
5. To access your exported data in the Amazon S3 bucket, see Uploading, downloading, and managing
objects in the Amazon Simple Storage Service User Guide.

438
 Amazon Relational Database Service User Guide
Setting up access to an S3 bucket

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.

Topics
• Identifying the Amazon S3 bucket for export (p. 439)
• Providing access to an Amazon S3 bucket using an IAM role (p. 439)
• Using a cross-account Amazon S3 bucket (p. 441)

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

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

439
 Amazon Relational Database Service User Guide
Setting up access to an S3 bucket

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/*

For more information on creating an IAM policy for Amazon RDS, see Creating and using an IAM
policy for IAM database access (p. 1913). 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": [
{
"Sid": "ExportPolicy",
"Effect": "Allow",
"Action": [
"s3:PutObject*",
"s3:ListBucket",
"s3:GetObject*",
"s3:DeleteObject*",
"s3:GetBucketLocation"
],
"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.

440
 Amazon Relational Database Service User Guide
Using a cross-account KMS key

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

Using a cross-account Amazon S3 bucket

You can use Amazon S3 buckets across AWS accounts. To use a cross-account bucket, add a bucket policy
to allow access to the IAM role that you're using for the S3 exports. For more information, see Example 2:
Bucket owner granting cross-account bucket permissions.

• Attach a bucket policy to your bucket, as shown in the following example.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:role/Admin"
},
"Action": [
"s3:PutObject*",
"s3:ListBucket",
"s3:GetObject*",
"s3:DeleteObject*",
"s3:GetBucketLocation"
],
"Resource": [
"arn:aws:s3:::mycrossaccountbucket",
"arn:aws:s3:::mycrossaccountbucket/*"
]
}
]
}

Using a cross-account AWS KMS key for encrypting

Amazon S3 exports
You can use a cross-account AWS KMS key to encrypt Amazon S3 exports. First, you add a key policy to
the local account, then you add IAM policies in the external account. For more information, see Allowing
users in other accounts to use a KMS key.

To use a cross-account KMS key

1. Add a key policy to the local account.

The following example gives ExampleRole and ExampleUser in the external account
444455556666 permissions in the local account 123456789012.

{
"Sid": "Allow an external account to use this KMS key",
"Effect": "Allow",
"Principal": {

441
 Amazon Relational Database Service User Guide
Exporting a snapshot to an S3 bucket

"AWS": [
"arn:aws:iam::444455556666:role/ExampleRole",
"arn:aws:iam::444455556666:user/ExampleUser"
]
},
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:CreateGrant",
"kms:DescribeKey",
"kms:RetireGrant"
],
"Resource": "*"
}

2. Add IAM policies to the external account.

The following example IAM policy allows the principal to use the KMS key in account 123456789012
for cryptographic operations. To give this permission to ExampleRole and ExampleUser in
account 444455556666, attach the policy to them in that account.

{
"Sid": "Allow use of KMS key in account 123456789012",
"Effect": "Allow",
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:CreateGrant",
"kms:DescribeKey",
"kms:RetireGrant"
],
"Resource": "arn:aws:kms:us-
west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}

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 export the fastest.
Tables that don't contain a column suitable for partitioning and tables with only one index on
a string-based column take longer. This longer export time occurs 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.

442
 Amazon Relational Database Service User Guide
Exporting a snapshot to an S3 bucket

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 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 databases, schemas, or tables for Identifiers, separated by spaces.

Use the following format:

database[.schema][.table] database2[.schema2][.table2] ... databasen[.scheman]

[.tablen]

For example:

mydatabase mydatabase2.myschema1 mydatabase2.myschema2.mytable1

mydatabase2.myschema2.mytable2

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. 439), 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 AWS KMS key, enter the ARN for the key to use for encrypting the exported data.
11. Choose Export to Amazon S3.

443
 Amazon Relational Database Service User Guide
Exporting a snapshot to an S3 bucket

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 my-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 my-key

Sample output follows.

{
"Status": "STARTING",
"IamRoleArn": "iam-role",
"ExportTime": "2019-08-12T01:23:53.109Z",
"S3Bucket": "my-export-bucket",
"PercentProgress": 0,
"KmsKeyId": "my-key",
"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

444
 Amazon Relational Database Service User Guide
Monitoring snapshot exports

• 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",
"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",

445
 Amazon Relational Database Service User Guide
Canceling a snapshot export

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

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

446
 Amazon Relational Database Service User Guide
Failure messages

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.

Failure messages for Amazon S3 export tasks

The following table describes the messages that are returned when Amazon S3 export tasks fail.

Failure message Description

An unknown internal error occurred. The task has failed because of an unknown error,
exception, or failure.

An unknown internal error occurred The task has failed because of an unknown error,
writing the export task's metadata to the exception, or failure.
S3 bucket [bucket name].

The RDS export failed to write the export The export task assumes your IAM role to validate
task's metadata because it can't assume whether it is allowed to write metadata to your S3 bucket.
the IAM role [role ARN]. If the task can't assume your IAM role, it fails.

The RDS export failed to write the export One or more permissions are missing, so the export task
task's metadata to the S3 bucket [bucket can't access the S3 bucket. This failure message is raised
name] using the IAM role [role ARN] with when receiving one of the following:
the KMS key [key ID]. Error code: [error
code] • AWSSecurityTokenServiceException with the
error code AccessDenied
• AmazonS3Exception with the error
code NoSuchBucket, AccessDenied,
KMS.KMSInvalidStateException, 403 Forbidden,
or KMS.DisabledException

447
 Amazon Relational Database Service User Guide
Troubleshooting PostgreSQL permissions errors

Failure message Description

This means that there are settings misconfigured among
the IAM role, S3 bucket, or KMS key.

The IAM role [role ARN] isn't authorized to The IAM policy is misconfigured. Permission for the
call [S3 action] on the S3 bucket [bucket specific S3 action on the S3 bucket is missing. This causes
name]. Review your permissions and retry the export task to fail.
the export.

KMS key check failed. Check the The KMS key credential check failed.
credentials on your KMS key and try again.

S3 credential check failed. Check the The S3 credential check failed.

permissions on your S3 bucket and IAM
policy.

The S3 bucket [bucket name] isn't valid. The S3 bucket is invalid.

Either it isn't located in the current AWS
Region or it doesn't exist. Review your S3
bucket name and retry the export.

The S3 bucket [bucket name] isn't located The S3 bucket is in the wrong AWS Region.
in the current AWS Region. Review your S3
bucket name and retry the export.

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

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. The current convention is the following:

partition_index/part-00000-random_uuid.format-based_extension

For example:

448
 Amazon Relational Database Service User Guide
Data conversion

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 older convention is the following:

part-partition_index-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

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.

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. 450)
• PostgreSQL data type mapping to Parquet (p. 452)

449
 Amazon Relational Database Service User Guide
Data conversion

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  

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.

450
 Amazon Relational Database Service User Guide
Data conversion

Source data type Parquet primitive type Logical type Conversion notes
annotation
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

TEXT BYTE_ARRAY STRING

TINYBLOB BYTE_ARRAY  

TINYTEXT BYTE_ARRAY STRING

VARBINARY BYTE_ARRAY  

VARCHAR BYTE_ARRAY STRING

Date and time data types

451
 Amazon Relational Database Service User Guide
Data conversion

Source data type Parquet primitive type Logical type Conversion notes
annotation

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

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

452
 Amazon Relational Database Service User Guide
Data conversion

PostgreSQL data type Parquet primitive type Logical type Mapping notes
annotation
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

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  

453
 Amazon Relational Database Service User Guide
Data conversion

PostgreSQL data type Parquet primitive type Logical type Mapping notes
annotation

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

RANGE BYTE_ARRAY STRING

UUID BYTE_ARRAY STRING

454
 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, you can choose the default VPC security group or
apply a custom VPC security group to your DB instance.

Restored DB instances are automatically associated with the default DB 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
might not be possible to restore a SQL Server DB instance to a point in time if there is a break in the

455
 Amazon Relational Database Service User Guide
Point-in-time recovery

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. The name must be
unique.
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:

456
 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

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

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

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

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

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

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.

460
 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. 409).
• 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. 268).

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.

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

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

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

464
 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. 466)
• Viewing key monitoring information (p. 469)
• Monitoring Amazon RDS metrics with Amazon CloudWatch (p. 480)
• Monitoring DB load with Performance Insights on Amazon RDS (p. 487)
• Monitoring the OS by using Enhanced Monitoring (p. 551)
• Working with Amazon RDS events (p. 567)
• Working with Amazon RDS database log files (p. 593)
• Working with AWS CloudTrail and Amazon RDS (p. 632)
• Monitoring Amazon RDS for Oracle using Database Activity Streams (p. 636)

465
 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
user connections for your DB instance varies based on your instance class and the complexity of the

466
 Amazon Relational Database Service User Guide
Monitoring tools

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. 284).
• 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 Viewing
Amazon RDS recommendations (p. 473).
• Amazon RDS Performance Insights — Assess the load on your database, and determine when and
where to take action. For more information, see Monitoring DB load with Performance Insights on
Amazon RDS (p. 487).
• Amazon RDS Enhanced Monitoring — Look at metrics in real time for the operating system. For more
information, see Monitoring the OS by using Enhanced Monitoring (p. 551).
• 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. 571).
• 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 Working with Amazon RDS database log
files (p. 593).

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

467
 Amazon Relational Database Service User Guide
Monitoring tools

in CloudWatch. For more information, see Monitoring Amazon RDS metrics with Amazon
CloudWatch (p. 480).
• 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. 480).
• 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 Creating a rule that triggers on an Amazon RDS
event (p. 589).
• 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. 632).

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.

468
 Amazon Relational Database Service User Guide
Viewing key monitoring information

• Create and edit alarms to be notified of problems.

Viewing key monitoring information

The Amazon RDS console provides quick access to key monitoring features.

Topics
• Viewing DB instance status (p. 470)
• Viewing Amazon RDS recommendations (p. 473)
• Viewing DB instance metrics (p. 477)

469
 Amazon Relational Database Service User Guide
Viewing DB instance status

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

Find the possible status values for DB instances in the following table. This table also shows whether 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.

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 key used to encrypt or decrypt the DB instance can't
encryption-credentials billed 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.

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

470
 Amazon Relational Database Service User Guide
Viewing DB instance status

DB instance status Billed Description

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

stopping Billed The DB instance is being stopped.

for
storage

471
 Amazon Relational Database Service User Guide
Viewing DB instance status

DB instance status Billed Description

storage-full Billed The DB instance has reached its storage capacity allocation. This
is a critical status, and we recommend that you fix this issue
immediately. To do so, scale up your storage by modifying the DB
instance. To avoid this situation, set Amazon CloudWatch alarms
to warn you when storage space is getting low.

storage-optimization Billed Your DB instance is being modified to change the storage size
or type. The DB instance is fully operational. However, while the
status of your DB instance is storage-optimization, you can't
request any changes to the storage of your DB instance. The
storage optimization process is usually short, but can sometimes
take up to and even beyond 24 hours.

upgrading Billed The database engine version is being upgraded.

472
 Amazon Relational Database Service User Guide
Viewing Amazon RDS recommendations

Viewing 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. 331)
improvements.

Pending You have pending We recommend that you perform Maintaining a DB

maintenance maintenance the pending maintenance available instance (p. 320)
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. 388)
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. 48)
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. 1994)
other virtual networks in the AWS
Cloud.

Enhanced Your DB instance We recommend enabling Enhanced Monitoring the OS

Monitoring doesn't have Monitoring. Enhanced Monitoring by using Enhanced
disabled Enhanced Monitoring provides real-time operating Monitoring (p. 551)
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. 1879)
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. 10)

473
 Amazon Relational Database Service User Guide
Viewing 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. 1283)
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. 284)
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. 611)
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.

474
 Amazon Relational Database Service User Guide
Viewing Amazon RDS 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.

475
 Amazon Relational Database Service User Guide
Viewing Amazon RDS 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.

476
 Amazon Relational Database Service User Guide
Viewing DB instance metrics

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. 306).
Note
When you choose Apply now, a brief DB instance outage might result.

Viewing DB instance metrics

Amazon RDS provides metrics so that you can monitor the health of your DB instances. You can monitor
both DB instance metrics and operating system (OS) metrics.

Following, you can find details about how to view metrics for your DB instance using the RDS console
and CloudWatch. For information on monitoring metrics for your DB instance's operating system in real
time using CloudWatch Logs, see Monitoring the OS by using Enhanced Monitoring (p. 551).

477
 Amazon Relational Database Service User Guide
Viewing DB instance metrics

Viewing metrics by using the console

To view DB and OS metrics for a DB instance

1. Sign in to the AWS Management Console and open the Amazon RDS console at https://
console.aws.amazon.com/rds/.
2. In the navigation pane, choose Databases.
3. Choose the name of the DB instance that you need information about to show its details.
4. Choose the Monitoring tab.
5. For Monitoring, choose the option for how you want to view your metrics from these:

• CloudWatch – Shows a summary of DB instance metrics available from Amazon CloudWatch. Each
metric includes a graph showing the metric monitored over a specific time span.
• Enhanced monitoring – Shows a summary of OS metrics available for a DB instance with
Enhanced Monitoring enabled. Each metric includes a graph showing the metric monitored over a
specific time span.
• OS Process list – Shows details for each process running in the selected instance.
• Performance Insights – Opens the Amazon RDS Performance Insights console for your DB
instance.

Tip
To choose the time range of the metrics represented by the graphs, you can use the time
range list.

478
 Amazon Relational Database Service User Guide
Viewing DB instance metrics

To bring up a more detailed view, you can choose any graph. You can also apply metric-
specific filters to the data.

Viewing DB instance metrics with the CLI or API

Amazon RDS integrates with CloudWatch metrics to provide a variety of DB instance metrics. You can
view CloudWatch metrics using the RDS console, AWS CLI, or API.

For a complete list of Amazon RDS metrics, go to Amazon RDS dimensions and metrics in the Amazon
CloudWatch User Guide.

Viewing DB metrics by using the CloudWatch CLI

Note
The following CLI example requires the CloudWatch command line tools. For more information
on CloudWatch and to download the developer tools, see Amazon CloudWatch on the AWS
website. The StartTime and EndTime values supplied in this example are for illustration only.
Substitute appropriate start and end time values for your DB instance.

To view usage and performance statistics for a DB instance

• Use the CloudWatch command mon-get-stats with the following parameters.

PROMPT>mon-get-stats FreeStorageSpace --dimensions="DBInstanceIdentifier=mydbinstance"

--statistics= Average
--namespace="AWS/RDS" --start-time 2009-10-16T00:00:00 --end-time 2009-10-16T00:02:00

Viewing DB metrics by using the CloudWatch API

The StartTime and EndTime values supplied in this example are for illustration only. Substitute
appropriate start and end time values for your DB instance.

To view usage and performance statistics for a DB instance

• Call the CloudWatch API GetMetricStatistics with the following parameters:

• Statistics.member.1 = Average
• Namespace = AWS/RDS
• StartTime = 2009-10-16T00:00:00
• EndTime = 2009-10-16T00:02:00
• Period = 60
• MeasureName = FreeStorageSpace

479
 Amazon Relational Database Service User Guide
Monitoring RDS with CloudWatch

Monitoring Amazon RDS metrics with Amazon

CloudWatch
Amazon CloudWatch is a metrics repository. The repository collects and processes raw data from Amazon
RDS into readable, near real-time metrics.

By default, Amazon RDS automatically sends metric data to CloudWatch in 1-minute periods. Data
points with a period of 60 seconds (1 minute) are available for 15 days. This means that you can access
historical information and see how your web application or service is performing.

For more information about CloudWatch, see What is Amazon CloudWatch? in the Amazon CloudWatch
User Guide. For more information about CloudWatch metrics retention, see Metrics retention.
Note
If you are using Amazon RDS Performance Insights, additional metrics are available. For more
information, see Performance Insights metrics published to Amazon CloudWatch (p. 547).

480
 Amazon Relational Database Service User Guide
Amazon RDS metrics

Amazon RDS metrics

The AWS/RDS namespace includes the following metrics.
Note
The Amazon RDS console might display metrics in units that are different from the units sent
to Amazon CloudWatch. For example, the Amazon RDS console might display a metric in
megabytes (MB), while the metric is sent to Amazon CloudWatch in bytes.

Metric Console name Description Units

BinLogDiskUsage Binary Log Disk The amount of disk space occupied by Bytes
Usage (MB) binary logs. If autobackups are enabled
for MySQL and MariaDB instances,
including read replicas, binary logs are
created.

BurstBalance Burst Balance The percent of General Purpose SSD (gp2) Percent
(Percent) burst-bucket I/O credits available.

CPUUtilization CPU Utilization The percentage of CPU utilization. Percent

(Percent)

CPUCreditUsage CPU Credit Usage (T2 instances) The number of CPU credits Credits (vCPU-
(Count) spent by the instance for CPU utilization. minutes)
One CPU credit equals one vCPU running
at 100 percent utilization for one minute
or an equivalent combination of vCPUs,
utilization, and time. For example, you
might have one vCPU running at 50
percent utilization for two minutes or two
vCPUs running at 25 percent utilization
for two minutes.

CPU credit metrics are available at a five-

minute frequency only. If you specify
a period greater than five minutes, use
the Sum statistic instead of the Average
statistic.

CPUCreditBalanceCPU Credit (T2 instances) The number of earned Credits (vCPU-

Balance (Count) CPU credits that an instance has accrued minutes)
since it was launched or started. For T2
Standard, the CPUCreditBalance also
includes the number of launch credits that
have been accrued.

Credits are accrued in the credit balance

after they are earned, and removed from
the credit balance when they are spent.
The credit balance has a maximum limit,
determined by the instance size. After the
limit is reached, any new credits that are
earned are discarded. For T2 Standard,
launch credits don't count towards the
limit.

481
 Amazon Relational Database Service User Guide
Amazon RDS metrics

Metric Console name Description Units

The credits in the CPUCreditBalance
are available for the instance to spend to
burst beyond its baseline CPU utilization.

When an instance is running, credits

in the CPUCreditBalance don't
expire. When the instance stops, the
CPUCreditBalance does not persist,
and all accrued credits are lost.

CPU credit metrics are available at a five-

minute frequency only.

DB Connections
DatabaseConnections The number of database connections in Count
(Count) use.

The metric value might not include

broken database connections that haven't
been cleaned up by your database yet.
So, the number of database connections
recorded by your database might be
higher than the metric value.

DiskQueueDepth Queue Depth The number of outstanding I/Os (read/ Count

(Count) write requests) waiting to access the disk.

EBSByteBalance EBS Byte Balance The percentage of throughput credits Percent

% (percent) remaining in the burst bucket of your RDS
database. This metric is available for basic
monitoring only.

To find the instance sizes that support

this metric, see the instance sizes with
an asterisk (*) in the EBS optimized by
default table in Amazon EC2 User Guide
for Linux Instances. The Sum statistic is not
applicable to this metric.

EBSIOBalance% EBS IO Balance The percentage of I/O credits remaining Percent

(percent) in the burst bucket of your RDS database.
This metric is available for basic
monitoring only.

To find the instance sizes that support

this metric, see the instance sizes with
an asterisk (*) in the EBS optimized by
default table in Amazon EC2 User Guide
for Linux Instances. The Sum statistic is not
applicable to this metric.

This metric is different from

BurstBalance. To learn how to use
this metric, see Improving application
performance and reducing costs with
Amazon EBS-Optimized Instance burst
capability.

482
 Amazon Relational Database Service User Guide
Amazon RDS metrics

Metric Console name Description Units

Failed SQL
FailedSQLServerAgentJobsCount The number of failed Microsoft SQL Count/Minute
Server Agent Server Agent jobs during the last minute.
Jobs Count
(Count/Minute)

FreeableMemory Freeable Memory The amount of available random access Bytes

(MB) memory.

For MariaDB, MySQL, Oracle, and

PostgreSQL DB instances, this metric
reports the value of the MemAvailable
field of /proc/meminfo.

FreeStorageSpaceFree Storage The amount of available storage space. Bytes

Space (MB)

Maximum Used
MaximumUsedTransactionIDs The maximum transaction IDs that have Count
Transaction IDs been used. Applies to PostgreSQL.
(Count)

Network Receive
NetworkReceiveThroughput The incoming (receive) network traffic on Bytes/Second
Throughput the DB instance, including both customer
(MB/Second) database traffic and Amazon RDS traffic
used for monitoring and replication.

Network
NetworkTransmitThroughput The outgoing (transmit) network traffic on Bytes/Second
Transmit the DB instance, including both customer
Throughput database traffic and Amazon RDS traffic
(MB/Second) used for monitoring and replication.

Oldest
OldestReplicationSlotLag The lagging size of the replica lagging the Bytes
Replication Slot most in terms of write-ahead log (WAL)
Lag (MB) data received. Applies to PostgreSQL.

ReadIOPS Read IOPS The average number of disk read I/O Count/Second
(Count/Second) operations per second.

ReadLatency Read Latency The average amount of time taken per Seconds
(Milliseconds) disk I/O operation.

ReadThroughput Read Throughput The average number of bytes read from Bytes/Second
(MB/Second) disk per second.

ReplicaLag Replica Lag The amount of time a read replica DB Seconds

(Milliseconds) instance lags behind the source DB
instance. Applies to MySQL, MariaDB,
Oracle, PostgreSQL, and SQL Server read
replicas.

Replica Slot Disk

ReplicationSlotDiskUsage The disk space used by replication slot Bytes
Usage (MB) files. Applies to PostgreSQL.

SwapUsage Swap Usage (MB) The amount of swap space used on the Bytes
DB instance. This metric is not available
for SQL Server.

Transaction Logs
TransactionLogsDiskUsage The disk space used by transaction logs. Bytes
Disk Usage (MB) Applies to PostgreSQL.

483
 Amazon Relational Database Service User Guide
Amazon RDS dimensions

Metric Console name Description Units

Transaction Logs
TransactionLogsGeneration The size of transaction logs generated per Bytes/Second
Generation (MB/ second. Applies to PostgreSQL.
Second)

WriteIOPS Write IOPS The average number of disk write I/O Count/Second
(Count/Second) operations per second.

WriteLatency Write Latency The average amount of time taken per Seconds
(Milliseconds) disk I/O operation.

WriteThroughput Write The average number of bytes written to Bytes/Second

Throughput disk per second.
(MB/Second)

Amazon RDS dimensions

You can filter Amazon RDS metrics data by using any dimension in the following table.

Dimension Filters the requested data for . . .

DBInstanceIdentifier A specific DB instance.

DatabaseClass All instances in a database class. For example, you can aggregate
metrics for all instances that belong to the database class
db.r5.large.

EngineName The identified engine name only. For example, you can aggregate
metrics for all instances that have the engine name mysql.

SourceRegion The specified Region only. For example, you can aggregate metrics
for all DB instances in the us-east-1 Region.

Viewing Amazon RDS metrics and dimensions

When you use Amazon RDS resources, Amazon RDS sends metrics and dimensions to Amazon
CloudWatch every minute. You can use the following procedures to view the metrics for Amazon RDS.

To view metrics using the Amazon CloudWatch console

Metrics are grouped first by the service namespace, and then by the various dimension combinations
within each namespace.

1. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

2. If necessary, change the AWS Region. From the navigation bar, choose the AWS Region where your
AWS resources are. For more information, see Regions and endpoints.
3. In the navigation pane, choose Metrics. Choose the RDS metric namespace.

484
 Amazon Relational Database Service User Guide
Viewing metrics and dimensions

4. Choose a metric dimension, for example By Database Class.

5. To sort the metrics, use the column heading. To graph a metric, select the check box next to the
metric. To filter by resource, choose the resource ID, and then choose Add to search. To filter by
metric, choose the metric name, and then choose Add to search.

485
 Amazon Relational Database Service User Guide
Creating alarms

To view metrics using the AWS CLI

• At a command prompt, use the following command.

aws cloudwatch list-metrics --namespace AWS/RDS

Creating CloudWatch alarms to monitor Amazon RDS

You can create a CloudWatch alarm that sends an Amazon SNS message when the alarm changes state.
An alarm watches a single metric over a time period that you specify. The alarm can also perform one
or more actions based on the value of the metric relative to a given threshold over a number of time
periods. The action is a notification sent to an Amazon SNS topic or Amazon EC2 Auto Scaling policy.

Alarms invoke actions for sustained state changes only. CloudWatch alarms don't invoke actions simply
because they are in a particular state. The state must have changed and have been maintained for a
specified number of time periods. The following procedures show how to create alarms for Amazon RDS.

To set alarms using the CloudWatch console

1. Sign in to the AWS Management Console and open the CloudWatch console at https://
console.aws.amazon.com/cloudwatch/.
2. Choose Alarms and then choose Create Alarm. Doing this launches the Create Alarm Wizard.
3. Choose RDS Metrics and scroll through the Amazon RDS metrics to find the metric that you want
to place an alarm on. To display just Amazon RDS metrics, search for the identifier of your resource.
Choose the metric to create an alarm on and then choose Next.
4. Enter Name, Description, and Whenever values for the metric.
5. If you want CloudWatch to send you an email when the alarm state is reached, for Whenever this
alarm, choose State is ALARM. For Send notification to, choose an existing SNS topic. If you choose
Create topic, you can set the name and email addresses for a new email subscription list. This list is
saved and appears in the field for future alarms.
Note
If you use Create topic to create a new Amazon SNS topic, the email addresses must be
verified before they receive notifications. Emails are only sent when the alarm enters an
alarm state. If this alarm state change happens before the email addresses are verified, the
addresses don't receive a notification.
6. Preview the alarm that you're about to create in the Alarm Preview area, and then choose Create
Alarm.

To set an alarm using the AWS CLI

• Call put-metric-alarm. For more information, see AWS CLI Command Reference.

To set an alarm using the CloudWatch API

• Call PutMetricAlarm. For more information, see Amazon CloudWatch API Reference

486
 Amazon Relational Database Service User Guide
Monitoring with Performance Insights

Monitoring DB load with Performance Insights on

Amazon RDS
Performance Insights expands on existing Amazon RDS monitoring features to illustrate your database
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. 487)
• Enabling and disabling Performance Insights (p. 490)
• Enabling the Performance Schema for Performance Insights on Amazon RDS for MariaDB or
MySQL (p. 493)
• Configuring access policies for Performance Insights (p. 496)
• Analyzing metrics with the Performance Insights dashboard (p. 499)
• Adding counter metrics to the Performance Insights dashboard (p. 524)
• Retrieving metrics with the Performance Insights API (p. 534)
• Performance Insights metrics published to Amazon CloudWatch (p. 547)
• Logging Performance Insights calls using AWS CloudTrail (p. 549)

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.

You can find an overview of Performance Insights in the following video.

Using Performance Insights to Analyze Performance of Amazon Aurora PostgreSQL

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.

Topics
• Database load (p. 487)
• Maximum CPU (p. 489)
• Amazon RDS DB engine support for Performance Insights (p. 489)
• AWS Region support for Performance Insights (p. 490)

Database load
Database load (DB load) measures the level of activity in your database. The key metric in Performance
Insights is DBLoad, which is collected every second. The unit for the DBLoad metric is the average active
sessions (AAS) for the DB engine.

Topics
• Average active sessions (p. 488)
• Average active executions (p. 488)
• Dimensions (p. 488)

487
 Amazon Relational Database Service User Guide
Overview of Performance Insights

Average active sessions

An active session is a connection that has submitted work to the DB engine and is waiting for a response.
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 average active sessions, 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

5 4 2 10 sessions / 5 samples

In the preceding example, the DB load for the time interval is 2 AAS. An increase in DB load means that,
on average, more sessions are running on the database.

Average active executions

The average active executions (AAE) per second is related to AAS. 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 360 2 360 execution seconds /

180 elapsed seconds

240 360 1.5 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 is different from the other time-series metrics because you can break it into
subcomponents called dimensions. You can think of dimensions as categories or "group by" clauses for

488
 Amazon Relational Database Service User Guide
Overview of Performance Insights

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
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 DB load is often above the Max vCPU line, and the primary wait state is CPU, the CPU is
overloaded. In this case, 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 DB load doesn't cross the Max vCPU line.

Amazon RDS DB engine support for Performance Insights

Following, you can find the Amazon RDS DB engines that support Performance Insights.
Note
For Amazon Aurora, see Amazon Aurora DB engine support for Performance Insights in Amazon
Aurora User Guide.

489
 Amazon Relational Database Service User Guide
Enabling and disabling Performance Insights

Amazon RDS DB Supported engine versions Unsupported instance classes

engine

Amazon RDS for Performance Insights is supported for Performance Insights isn't supported
MariaDB the following engine versions: for the following instance classes:

• All 10.5 versions • db.t2.micro

• All 10.4 versions • db.t2.small
• 10.3.13* and higher 10.3 versions • db.t3.micro
• 10.2.21 and higher 10.2 versions • db.t3.small

* 10.3.13 isn't supported in the Europe

(Frankfurt) and Europe (Stockholm)
AWS Regions.

Amazon RDS for Performance Insights is supported for Performance Insights isn't supported
MySQL the following engine versions: for the following instance classes:

• 8.0.17 and higher 8 versions • db.t2.micro

• 5.7.22 and higher 5.7 versions • db.t2.small
• 5.6.41 and higher 5.6 versions • db.t3.micro
• db.t3.small

Amazon RDS for Performance Insights is supported for N/A

Microsoft SQL all engine versions except SQL Server
Server 2008.

Amazon RDS for Performance Insights is supported for N/A

PostgreSQL the following engine versions:

• All 13 versions
• All 12 versions
• All 11 versions
• All 10 versions

Amazon RDS for Performance Insights is supported for N/A

Oracle all engine versions.

Note
Aurora Serverless doesn't support Performance Insights.

AWS Region support for Performance Insights

Performance Insights for Amazon RDS is supported for all AWS Regions except the AWS GovCloud (US)
Region. The only exception is version 10.3.13 of Amazon RDS for MariaDB, which isn't supported in the
Europe (Frankfurt) and Europe (Stockholm) AWS Regions.

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.

490
 Amazon Relational Database Service User Guide
Enabling and disabling Performance Insights

Note
Performance Schema is an optional performance tool used by Amazon RDS for MariaDB or
MySQL. If you turn Performance Schema on or off, you need to reboot. If you turn Performance
Insights on or off, however, you don't need to reboot.

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

The following screenshot shows the Performance Insights section.

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.
• AWS KMS key – Specify your AWS KMS key. Performance Insights encrypts all potentially sensitive
data using your KMS key. Data is encrypted in flight and at rest. For more information, see Configuring
an AWS KMS policy for Performance Insights (p. 498).

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.

491
 Amazon Relational Database Service User Guide
Enabling and disabling Performance Insights

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. If you chose Long Term Retention (2 years) when you enable Performance
Insights, All displays 2 years of data. If you chose Default (7 days) instead, All displays only the
past week.
• AWS KMS key – Specify your KMS key. Performance Insights encrypts all potentially sensitive data
using your KMS key. Data is encrypted in flight and at rest. For more information, see Encrypting
Amazon RDS resources (p. 1879).
5. Choose Continue.
6. For Scheduling of Modifications, choose Apply immediately. If you choose Apply during the next
scheduled maintenance window, your instance ignores this setting and enables Performance Insights
immediately.
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 \

492
 Amazon Relational Database Service User Guide
Enabling the Performance Schema for MariaDB or MySQL

--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 \

--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
The Performance Schema is an optional feature for monitoring Amazon RDS for MariaDB or MySQL
runtime performance at a low level. You can use Performance insights with or without the Performance
Schema. The Performance Schema is designed to have minimal impact on database performance.

Topics

493
 Amazon Relational Database Service User Guide
Enabling the Performance Schema for MariaDB or MySQL

• Overview of the Performance Schema (p. 494)

• Options for enabling Performance Schema (p. 494)
• Configuring the Performance Schema for automatic management (p. 495)

Overview of the Performance Schema

The Performance Schema monitors server events. In this context, an event is a server action that
consumes time. Performance Schema events are distinct from binlog events and scheduler events.

The PERFORMANCE_SCHEMA storage engine collects event data using instrumentation in the database
source code. The engine stores collected events in tables in the performance_schema database. You
can query performance_schema just as you can query any other tables. For more information, see
MySQL Performance Schema in MySQL Reference Manual.

When the Performance Schema is enabled for Amazon RDS for MariaDB or MySQL, Performance
Insights uses it to provide more detailed information. For example, Performance Insights displays DB
load categorized by detailed wait events. You can use wait events to identify bottlenecks. Without the
Performance Schema, Performance Insights reports user states such as inserting and sending, which
don't help you identify bottlenecks.

Options for enabling Performance Schema

You have the following options for enabling the Performance Schema:

• Allow Performance Insights to manage required Performance Schema parameters automatically.

When you create an Amazon RDS for MariaDB or MySQL DB instance with Performance Insights
enabled, the Performance Schema is also enabled. In this case, Performance Insights automatically
manages your Performance Schema parameters.

For automatic management, the performance_schema must be set to 0 and the Source
must be set to a value other than 0. By default, Source is engine-default. If you change the
performance_schema value manually, and then later want to revert to automatic management, see
Configuring the Performance Schema for automatic management (p. 495).
Important
When Performance Insights enables the Performance Schema, it doesn't change the
parameter group values. However, the values are changed on the instances that are running.
The only way to see the changed values is to run the SHOW GLOBAL VARIABLES command.
• Set the required Performance Schema parameters yourself.

For Performance Insights to list wait events, set all Performance Schema parameters as shown 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

494
 Amazon Relational Database Service User Guide
Enabling the Performance Schema for MariaDB or MySQL

Parameter Name Parameter Value

performance-schema-consumer-thread- ON
instrumentation

Note
If you enable or disable the Performance Schema, you must reboot the database. If you enable
or disable Performance Insights, you don't need to reboot the database.

For more information, see Performance Schema Command Options and Performance Schema Option
and Variable Reference in the MySQL documentation.

Configuring the Performance Schema for automatic

management
The following table shows the difference in settings when Performance Insights is and isn't managing
the Performance Schema.

Performance Insights isn't managing the Performance Insights is managing the

Performance Schema Performance Schema

performance_schema is 0 or 1 performance_schema is 0

The Source column is set to user The Source column is set to system

To let Performance Insights manage the Performance Schema automatically

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. Enter performance_schema in the search bar.
5. Select the performance_schema parameter.

6. Check whether Source is system and Values is 0. If so, Performance Insights is managing the
Performance Schema automatically. If not, proceed to the next step.

7. Choose Edit parameters.

8. In Values, choose 0.
9. Select Reset. When you reset, Amazon RDS sets Source to system and Values to 0.

495
 Amazon Relational Database Service User Guide
Performance Insights policies

The Reset parameters in DB parameter group page appears.

10. Select Reset parameters.
11. Restart the DB instance.
Important
Whenever you enable or disable the Performance Schema, you must restart the DB
instance.

For more information about modifying instance parameters, see Modifying parameters in a DB
parameter group (p. 288). For more information about the dashboard, see Analyzing metrics with
the Performance Insights dashboard (p. 499). For more information about the MySQL performance
schema, see MySQL 8.0 Reference Manual.

Configuring access policies for Performance Insights

To access Performance Insights, you must have the appropriate permissions from AWS Identity and
Access Management (IAM). You have the following options for granting access:

• Attach the AmazonRDSFullAccess managed policy to an IAM user or role.

• Create a custom IAM policy and attach it to an IAM user or role.

Also, if you specified a customer managed key when you turned on Performance Insights, make sure that
users in your account have the kms:Decrypt and kms:GenerateDataKey permissions on the KMS key.

Attaching the AmazonRDSFullAccess policy to an IAM principal

AmazonRDSFullAccess is an AWS-managed policy that grants access to all of the Amazon RDS API
operations. This policy does the following:

• Grants access to related services used by the Amazon RDS console. For example, this policy grants
access to event notifications using Amazon SNS.
• Grants permissions needed for using Performance Insights.

If you attach AmazonRDSFullAccess to an IAM user or role, the recipient can use Performance Insights
with other console features.

Creating a custom IAM policy for Performance Insights

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 text, replacing us-east-1 with the name of your AWS Region and
111122223333 with your customer account number.

496
 Amazon Relational Database Service User Guide
Performance Insights policies

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "pi:*",
"Resource": "arn:aws:pi:us-east-1:111122223333:metrics/rds/*"
},
{
"Effect": "Allow",
"Action": "rds:DescribeDBInstances",
"Resource": "*"
}
]
}

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. 1895).
4. On the Summary page, choose Add permissions.
5. Choose Attach existing policies directly. For Search, type the first few characters of your policy
name, as shown following.

6. Choose your policy, and then choose Next: Review.

7. Choose Add permissions.

497
 Amazon Relational Database Service User Guide
Performance Insights policies

Configuring an AWS KMS policy for Performance Insights

Performance Insights uses an AWS KMS key to encrypt sensitive data. When you enable Performance
Insights through the API or the console, you have the following options:

• Choose the default AWS managed key.

Amazon RDS uses the AWS managed key for your new DB instance. Amazon RDS creates an AWS
managed key for your AWS account. Your AWS account has a different AWS managed key for Amazon
RDS for each AWS Region.
• Choose a customer managed key.

If you specify a customer managed key, users in your account that call the Performance Insights API
need the kms:Decrypt and kms:GenerateDataKey permissions on the KMS key. You can configure
these permissions through IAM policies. However, we recommend that you manage these permissions
through your KMS key policy. For more information, see Using key policies in AWS KMS.

Example

The following sample key policy shows how to add statements to your KMS key policy. These statements
allow access to Performance Insights. Depending on how you use the KMS key, you might want to
change some restrictions. Before adding statements to your policy, remove all comments.

{
"Version" : "2012-10-17",
"Id" : "your-policy",
"Statement" : [ {
//This represents a statement that currently exists in your policy.
}
....,
//Starting here, add new statement to your policy for Performance Insights.
//We recommend that you add one new statement for every RDS instance
{
"Sid" : "Allow viewing RDS Performance Insights",
"Effect": "Allow",
"Principal": {
"AWS": [
//One or more principals allowed to access Performance Insights
"arn:aws:iam::444455556666:role/Role1"
]
},
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey"
],
"Resource": "*",
"Condition" : {
"StringEquals" : {
//Restrict access to only RDS APIs (including Performance Insights).
//Replace region with your AWS Region.
//For example, specify us-west-2.
"kms:ViaService" : "rds.region.amazonaws.com"
},
"ForAnyValue:StringEquals": {
//Restrict access to only data encrypted by Performance Insights.
"kms:EncryptionContext:aws:pi:service": "rds",
"kms:EncryptionContext:service": "pi",

//Restrict access to a specific RDS instance.

//The value is a DbiResourceId.
"kms:EncryptionContext:aws:rds:db-id": "db-AAAAABBBBBCCCCDDDDDEEEEE"

498
 Amazon Relational Database Service User Guide
Analyzing metrics with the Performance Insights dashboard

}
}
}

Analyzing metrics 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.

Performance Insights dashboard

• Overview of the Performance Insights dashboard (p. 499)
• Opening the Performance Insights dashboard (p. 504)
• Analyzing DB load using the Performance Insights dashboard (p. 505)
• Analyzing running queries using the Performance Insights dashboard (p. 506)
• Viewing more SQL text in the Performance Insights dashboard (p. 521)
• Zooming In on the DB Load chart (p. 523)

Overview of the Performance Insights dashboard

The dashboard is the easiest way to interact with Performance Insights. The following example shows
the dashboard for a DB instance. By default, the Performance Insights dashboard shows data for the last
hour.

499
 Amazon Relational Database Service User Guide
Analyzing metrics with the Performance Insights dashboard

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.

Topics
• Counter metrics chart (p. 500)
• Database load chart (p. 502)
• Top dimensions table (p. 504)

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

500
 Amazon Relational Database Service User Guide
Analyzing metrics with the Performance Insights dashboard

• Microsoft SQL Server – db.Databases.Active Transactions(_Total).avg

• PostgreSQL – db.Transactions.xact_commit.avg

To change the performance counters, choose 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 Adding counter metrics to the Performance Insights dashboard (p. 524).

501
 Amazon Relational Database Service User Guide
Analyzing metrics with the Performance Insights dashboard

Database load chart

The Database load chart shows how the database activity compares to DB instance capacity as
represented by the Max vCPU line. By default, the stacked line chart represents DB load as average active
sessions per unit of time. The DB load is sliced (grouped) by wait states.

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.

502
 Amazon Relational Database Service User Guide
Analyzing metrics with the Performance Insights dashboard

To see details for any item for the selected time period in the legend, hover over that item.

503
 Amazon Relational Database Service User Guide
Analyzing metrics with the Performance Insights dashboard

Top dimensions table

The Top dimensions table slices DB load by different dimensions. A dimension is a category or "group
by" for different characteristics of DB load. If the dimension is SQL, Top SQL shows the SQL statements
that contribute the most to DB load. For example, 95% of active database sessions might run SELECT
SUM(order_total) FROM orders, making this a top SQL query.

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

To learn how to analyze queries by using the Top SQL tab, see Overview of the Top SQL tab (p. 507).

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

504
 Amazon Relational Database Service User Guide
Analyzing metrics with the Performance Insights dashboard

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.

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.

Analyzing DB load using the Performance Insights dashboard

If the Database load 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 Database load chart. Choose a particular item, like a SQL
query or a user, to drill down into that item and see details about it.

505
 Amazon Relational Database Service User Guide
Analyzing metrics with the Performance Insights dashboard

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 Database load chart and see if there are any incidents of database load exceeding the Max
CPU line.
2. If there is, look at the Database load 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.

Analyzing running queries using the Performance Insights

dashboard
In the Amazon RDS Performance Insights dashboard, you can find information about running queries in
the Top SQL tab in the Top dimensions table. You can use this information to tune your queries.
Note
RDS for SQL Server doesn't show SQL-level statistics.

506
 Amazon Relational Database Service User Guide
Analyzing metrics with the Performance Insights dashboard

Topics
• Overview of the Top SQL tab (p. 507)
• Analyzing running queries in MariaDB and MySQL (p. 511)
• Analyzing running queries in Oracle (p. 514)
• Analyzing running queries in PostgreSQL (p. 518)

Overview of the Top SQL tab

By default, the Top SQL tab shows the SQL queries that are contributing the most to DB load. To help
tune your queries, you can analyze information such as the query text, statistics, and Support SQL ID.
You can also choose the statistics that you want to appear in the Top SQL tab.

Topics
• SQL statistics (p. 507)
• Load by waits (AAS) (p. 508)
• SQL information (p. 508)
• Preferences (p. 509)

SQL statistics

SQL statistics are performance-related metrics about SQL queries. For example, Performance Insights
might show executions per second or rows processed per second. Performance Insights collects statistics
for only the most common queries. Typically, these match the top queries by load shown in the
Performance Insights dashboard.

A SQL digest is a composite of multiple actual queries that are structurally similar but might have
different literal values. The digest replaces hardcoded values with a question mark. For example, a
digest might be SELECT * FROM emp WHERE lname= ?. This digest might include the following child
queries:

SELECT * FROM emp WHERE lname = 'Miller'

SELECT * FROM emp WHERE lname = 'Olagappan'
SELECT * FROM emp WHERE lname = 'Wu'

Every line in the Top SQL table shows relevant statistics for the SQL statement or digest, as shown in the
following example.

To see the literal SQL statements in a digest, select the query, and then choose the plus symbol (+). In
the following screenshot, the selected query is a digest.

507
 Amazon Relational Database Service User Guide
Analyzing metrics with the Performance Insights dashboard

Note
A SQL digest groups similar SQL statements, but does not redact sensitive information.

Load by waits (AAS)

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

SQL information

In the Top SQL table, you can open a statement to view its information. The information appears in the
bottom pane.

508
 Amazon Relational Database Service User Guide
Analyzing metrics with the Performance Insights dashboard

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.

Preferences

You can control the statistics displayed in the Top SQL tab by choosing the Preferences icon.

509
 Amazon Relational Database Service User Guide
Analyzing metrics with the Performance Insights dashboard

When you choose the Preferences icon, the Preferences window opens.

To enable the statistics that you want to appear in the Top SQL tab, use your mouse to scroll to the
bottom of the window, and then choose Continue.

510
 Amazon Relational Database Service User Guide
Analyzing metrics with the Performance Insights dashboard

Analyzing running queries in MariaDB and MySQL

MariaDB and MySQL collect SQL statistics only at the digest level. No statistics are shown at the
statement level.

Topics
• Digest table in MariaDB and MySQL (p. 511)
• Per-second statistics for MariaDB and MySQL (p. 511)
• Per-call statistics for MariaDB and MySQL (p. 512)
• Viewing SQL statistics for MariaDB and MySQL (p. 512)

Digest table in MariaDB and MySQL

Performance Insights collects SQL digest statistics from the

events_statements_summary_by_digest table. The events_statements_summary_by_digest
table is managed by your database.

The digest table doesn't have an eviction policy. When the table is full, the AWS Management Console
shows the following message:

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.

In this situation, MariaDB and MySQL don't track SQL queries. To address this issue, Performance Insights
automatically truncates the digest table when both of the following conditions are met:

• The table is full.

• Performance Insights manages the Performance Schema automatically. For automatic management,
the performance_schema parameter must be set to 0 and the Source must not be set to user.

If Performance Insights isn't managing the Performance Schema automatically, see Enabling the
Performance Schema for Performance Insights on Amazon RDS for MariaDB or MySQL (p. 493).

In the AWS CLI, check the source of a parameter value by running the describe-db-parameters command.

Per-second statistics for MariaDB and MySQL

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

511
 Amazon Relational Database Service User Guide
Analyzing metrics with the Performance Insights dashboard

Metric Unit

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

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)

Per-call statistics for MariaDB and MySQL

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)

Viewing SQL statistics for MariaDB and MySQL

The statistics are available in the Top SQL tab of the Database load chart.

To view the SQL statistics

1. Open the Amazon RDS console at https://console.aws.amazon.com/rds/.

512
 Amazon Relational Database Service User Guide
Analyzing metrics with the Performance Insights dashboard

2. Go to the Performance Insights dashboard.

3. Choose the SQL tab and expand a query.

4.

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.

513
 Amazon Relational Database Service User Guide
Analyzing metrics with the Performance Insights dashboard

Analyzing running queries in Oracle

Amazon RDS for Oracle collects SQL statistics both at the statement and digest level. At the statement
level, the ID column represents the value of V$SQL.SQL_ID. At the digest level, the ID column shows the
value of V$SQL.FORCE_MATCHING_SIGNATURE.

If the ID is 0 at the digest level, Oracle Database has determined that this statement is not suitable for
reuse. In this case, the child SQL statements could belong to different digests. However, the statements
are grouped together under the digest_text for the first SQL collected.

Topics
• Per-second statistics for Oracle (p. 514)
• Per-call statistics for Oracle (p. 515)
• Viewing SQL statistics for Oracle (p. 516)

Per-second statistics for Oracle

The following metrics provide per-second statistics for an Oracle SQL query.

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

514
 Amazon Relational Database Service User Guide
Analyzing metrics with the Performance Insights dashboard

Metric Unit

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 an Oracle SQL digest query.

Metric Unit

db.sql_tokenized.stats.executions_per_sec Number of executions per second

db.sql_tokenized.stats.elapsed_time_per_sec Average active executions (AAE)

db.sql_tokenized.stats.rows_processed_per_sec Rows processed per second

db.sql_tokenized.stats.buffer_gets_per_sec Buffer gets per second

db.sql_tokenized.stats.physical_read_requests_per_sec
Physical reads per second

db.sql_tokenized.stats.physical_write_requests_per_sec
Physical writes per second

db.sql_tokenized.stats.total_sharable_mem_per_sec Total shareable memory per second (in bytes)

db.sql_tokenized.stats.cpu_time_per_sec CPU time per second (in ms)

Per-call statistics for Oracle

The following metrics provide per-call statistics for an Oracle SQL statement.

Metric Unit

db.sql.stats.elapsed_time_per_exec Elapsed time per executions (in ms)

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)

The following metrics provide per-call statistics for an Oracle SQL digest query.

Metric Unit

db.sql_tokenized.stats.elapsed_time_per_exec Elapsed time per executions (in ms)

515
 Amazon Relational Database Service User Guide
Analyzing metrics with the Performance Insights dashboard

Metric Unit

db.sql_tokenized.stats.rows_processed_per_exec Rows processed per execution

db.sql_tokenized.stats.buffer_gets_per_exec Buffer gets per execution

db.sql_tokenized.stats.physical_read_requests_per_exec
Physical reads per execution

db.sql_tokenized.stats.physical_write_requests_per_exec
Physical writes per execution

db.sql_tokenized.stats.total_sharable_mem_per_execTotal shareable memory per execution (in bytes)

db.sql_tokenized.stats.cpu_time_per_exec CPU time per execution (in ms)

Viewing SQL statistics for Oracle

The statistics are available in the Top SQL tab of the Database load chart.

To view the SQL statistics

1. Open the Amazon RDS console at https://console.aws.amazon.com/rds/.

2. Go to the Performance Insights dashboard.
3. Choose the Top SQL tab.
4. Choose a digest query or individual statement.

5. Choose which statistics to display by choosing the gear icon in the upper-right corner of the chart.

516
 Amazon Relational Database Service User Guide
Analyzing metrics with the Performance Insights dashboard

The following screenshot shows the preferences for Oracle DB instances.

The following screenshot shows the statistics for a SQL statement.

517
 Amazon Relational Database Service User Guide
Analyzing metrics with the Performance Insights dashboard

Analyzing running queries in PostgreSQL

PostgreSQL collects SQL statistics only at the digest level. No statistics are shown at the statement level.

Topics
• Digest statistics for RDS PostgreSQL (p. 518)
• Per-second digest statistics for PostgreSQL (p. 518)
• Per-call digest statistics for PostgreSQL (p. 519)
• Viewing SQL statistics for PostgreSQL (p. 519)

Digest statistics for RDS PostgreSQL

To view SQL digest statistics, PostgreSQL must load the pg_stat_statements library. For RDS
PostgreSQL DB instances that are compatible with PostgreSQL 11 or later, the database loads this library
by default. For PostgreSQL DB instances that are compatible with PostgreSQL 10 or earlier, 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. 284).
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.

Per-second digest statistics for PostgreSQL

The following SQL digest statistics are available for PostgreSQL DB instances.

Metric Unit

db.sql_tokenized.