AWS AmazonRDS documentation change
Summary
Removed 'streaming restore' from s3_prefix parameter description
Security assessment
Documentation clarification with no security impact. The change removes an outdated reference but doesn't relate to security features or vulnerabilities.
Diff
diff --git a/AmazonRDS/latest/UserGuide/db2-sp-managing-databases.md b/AmazonRDS/latest/UserGuide/db2-sp-managing-databases.md index 1cea0d43e..33835142b 100644 --- a//AmazonRDS/latest/UserGuide/db2-sp-managing-databases.md +++ b//AmazonRDS/latest/UserGuide/db2-sp-managing-databases.md @@ -5 +5 @@ -rdsadmin.create_databaserdsadmin.deactivate_databaserdsadmin.activate_databaserdsadmin.reactivate_databaserdsadmin.drop_databaserdsadmin.update_db_paramrdsadmin.set_configurationrdsadmin.show_configurationrdsadmin.restore_databaserdsadmin.rollforward_databaserdsadmin.rollforward_statusrdsadmin.complete_rollforwardrdsadmin.db2pd_commandrdsadmin.force_applicationrdsadmin.set_archive_log_retentionrdsadmin.show_archive_log_retentionrdsadmin.list_archive_log_information +rdsadmin.create_databaserdsadmin.deactivate_databaserdsadmin.activate_databaserdsadmin.reactivate_databaserdsadmin.drop_databaserdsadmin.update_db_paramrdsadmin.set_configurationrdsadmin.show_configurationrdsadmin.backup_databaserdsadmin.restore_databaserdsadmin.rollforward_databaserdsadmin.rollforward_statusrdsadmin.complete_rollforwardrdsadmin.db2pd_commandrdsadmin.force_applicationrdsadmin.set_archive_log_retentionrdsadmin.show_archive_log_retentionrdsadmin.list_archive_log_information @@ -47,0 +48,2 @@ Refer to the following built-in stored procedures for information about their sy + * rdsadmin.backup_database + @@ -100 +102 @@ The default page size of the database. Valid values: `4096`, `8192`, `16384`, `3 -Amazon RDS supports write atomicity for 4 KiB, 8 KiB, and 16 KiB pages. In contrast, 32 KiB pages risk _torn writes_ , or partial data being written to the desk. If you use 32 KiB pages, we recommend that you enable point-in-time recovery and automated backups. Otherwise, you run the risk of being unable to recover from torn pages. For more information, see [Introduction to backups](./USER_WorkingWithAutomatedBackups.html) and [Restoring a DB instance to a specified time for Amazon RDS](./USER_PIT.html). +Amazon RDS supports write atomicity for 4 KiB, 8 KiB, and 16 KiB pages. In contrast, 32 KiB pages risk _torn writes_ , or partial data being written to the disk. If you use 32 KiB pages, we recommend that you enable point-in-time recovery and automated backups. Otherwise, you run the risk of being unable to recover from torn pages. For more information, see [Introduction to backups](./USER_WorkingWithAutomatedBackups.html) and [Restoring a DB instance to a specified time for Amazon RDS](./USER_PIT.html). @@ -565,0 +568,214 @@ The following example returns information about the current `RESTORE_DATABASE_PA +## rdsadmin.backup_database + +Backs up a database from an RDS for Db2 DB instance to an Amazon S3 bucket. + +### Syntax + + + db2 "call rdsadmin.backup_database( + ?, + 'database_name', + 's3_bucket_name', + 's3_prefix', + 'backup_type', + 'compression_option', + 'util_impact_priority', + 'num_files', + 'parallelism', + 'num_buffers')" + +### Parameters + +The following output parameter is required: + +? + + +A parameter marker that outputs an error message. This parameter only accepts `?`. + +The following input parameters are required: + +`database_name` + + +The name of the target database on an RDS for Db2 DB instance to back up. The data type is `varchar`. + +The database must exist in the DB instance. You can't back up the `rdsadmin` database. + +`s3_bucket_name` + + +The name of the Amazon S3 bucket where you want your backup to reside. The data type is `varchar`. + +The S3 bucket must exist before calling `rdsadmin.backup_database`, be in the same AWS Region as the target database in the RDS for Db2 DB instance that you want to back up, and be accessible through the IAM role attached to the DB instance. + +`s3_prefix` + + +The prefix of the path to Amazon S3 where RDS for Db2 uploads the backup files. The data type is `varchar`. + +The prefix is limited to 1024 characters. It must not include a leading or trailing slash (/). Because of a limitation with IBM streaming to Amazon S3, we recommend that the prefix includes subdirectories. + +For better file management, RDS for Db2 creates extra directories after `s3_prefix`. RDS for Db2 uploads all backup files to `s3_prefix/dbi_resource_id/db_name`. If you set `num_files` higher than `1`, the `db_name` directory will contain more than one backup file. + +The following is an example Amazon S3 location for backup files. In the example, `backups/daily` is the value set for the `s3_prefix` parameter. + + + backups/daily/db-5N7FXOY4GDP7RG2NSH2ZTAI2W4/SAMPLEDB + +`backup_type` + + +The type of backup that determines if the database remains available during backup. The data type is `varchar`. + +Valid values: + + * `OFFLINE` – The database is unavailable during backup. This type is faster, but it causes downtime. + + * `ONLINE` – The database remains available during backup. By default, `ONLINE` is set to `INCLUDE LOGS`. + + + + +The following parameters are optional: + +`compression_option` + + +The type of compression algorithm used that impacts backup time, CPU usage, and storage costs. The data type is `varchar`. The default is `NONE`. + +Valid values: + + * `NONE` – The largest file size, the least CPU usage, and cheapest storage costs. + + * `STANDARD` – Standard Db2 compression. Uses `libdb2compr.so`. + + * `ZLIB` – Enhanced Db2 compression. Uses `libdb2zcompr.so`, but is more CPU-intensive and most expensive storage cost. + + + + +`util_impact_priority` + + +The setting that controls the impact of the backup on the system resources. The data type is `integer`. Valid values: `1`–`100` (from low to high). The default is `50`. + +Lower values reduce the impact of the backup on the system resources, but might increase the time it takes to back up the database. Higher values might complete the backup of the database faster, but could affect other operations. The actual impact depends on the overall system utilization and the `util_impact_lim` setting. You can view and modify the `util_impact_lim` setting in parameter groups. For more information, see [Amazon RDS for Db2 parameters](./db2-supported-parameters.html). + +`num_files` + + +The number of parallel upload streams to Amazon S3. The data type is `integer`. Valid values: `1`–`256`. + +We recommend that you only set this parameter after observing the backup performance at the default that Amazon RDS automatically calculates. Higher values could improve performance for large backups, especially with high-bandwidth connections, but at a certain point, higher values degrade performance. Also, make sure to take into account your available system resources and network capacity. + +`parallelism` + + +The number of tablespaces that the backup utility can read in parallel. The data type is `integer`. Valid values: `1`–`256`. + +We recommend that you only set this parameter after observing the backup performance at the default that the Db2 engine automatically calculates as the optimal value. If you set this parameter, Amazon RDS validates against the available processors and won't execute the backup request if processing power is insufficient. + +`num_buffers` + + +The number of buffers to use. The data type is `integer`. Valid values: `1`–`268435456`. + +We recommend that you only set this parameter after observing the backup performance at the default that Amazon RDS automatically calculates based on memory. If you set this parameter, Amazon RDS validates against the available memory and won't execute the backup request if available memory is insufficient. If you are backing up to multiple locations (`num_files` is set to more than `1`), then a higher number of buffers could improve performance. If you don't set `compression_option` to `NONE`, then you can improve performance by increasing `num_buffers` and `parallelism`. + +### Usage notes + +This stored procedure creates asynchronous backup tasks that stream the backup of your database directly to your Amazon S3 bucket by using the Amazon S3 integration. You can make backups both from your local server or from an RDS for Db2 DB instance, stream them to Amazon S3, and then restore them wherever you want. For information about restoring a database to an RDS for Db2 DB instance, see rdsadmin.restore_database. + +Before calling the stored procedure, review the following considerations: + + * You can only back up one database at a time. + + * You can't perform a backup and restore together on a DB instance. + + * Amazon S3 server-side encryption with AWS KMS (SSE-KMS) isn't supported. Even if the S3 bucket is set to SSE-KMS, the files uploaded to the S3 bucket won't use SSE-KMS encryption. + + * To stream the backup files to Amazon S3, you must have already configured the integration. For more information, see [Integrating an Amazon RDS for Db2 DB instance with Amazon S3](./db2-s3-integration.html). + + * For an RDS for Db2 DB instance to be able to interact with Amazon S3, you must have a VPC and an Amazon S3 gateway endpoint for private subnets to use. For more information, see [Step 1: Create a VPC gateway endpoint for Amazon S3](./db2-troubleshooting.html#db2-creating-endpoint) and [Step 2: Confirm that your VPC gateway endpoint for Amazon S3 exists](./db2-troubleshooting.html#db2-confirming-endpoint). + + + + +Before calling `rdsadmin.backup_database`, you must connect to the `rdsadmin` database. In the following example, replace `master_username` and `master_password` with your RDS for Db2 DB instance information: + + + db2 connect to rdsadmin user master_username using master_password + +After you back up your database, be sure to terminate the connection. + + + terminate + +For information about checking the status of backing up a database, see [rdsadmin.get_task_status](./db2-user-defined-functions.html#db2-udf-get-task-status). + +For error messages returned when calling `rdsadmin.backup_database`, see [Stored procedure errors](./db2-troubleshooting.html#db2-troubleshooting-stored-procedures). + +### Examples + +All the examples back up a database called `MYDB` to the Amazon S3 bucket called `amzn-s3-demo-bucket` and set the `s3_prefix` to `backups/daily`. + +**Example #1: Specifying database offline and unavailable with median utilization and a single upload stream** + +In the following example, the database is offline, which is faster but means that the database is unavailable during backup. The example performs no compression of the files, has median impact on system resources, and uses a single upload stream to Amazon S3. + + + db2 call "rdsadmin.backup_database( + ?, + 'MYDB', + 'amzn-s3-demo-bucket', + 'backups/daily', + 'OFFLINE', + 'NONE', + 50, + 1)" + +**Example #2: Specifying database online and available with enhanced compression, median utilization, and few parallel upload streams** + +In the following example, the database in online and available during backup. The example performs enhanced compression, which results in a small file size, but is CPU-intensive. It has a slightly higher than median impact on system resources and uses five upload streams to Amazon S3. + + + db2 call "rdsadmin.backup_database( + ?, + 'MYDB', + 'amzn-s3-demo-bucket', + 'backups/daily', + 'ONLINE', + 'ZLIB', + 60, + 5)" + +**Example #3: Specifying database offline and unavailable with defaults and system calculations**