Menu
Amazon Relational Database Service
Command Line Interface Reference (API Version 2014-10-31)

Setting up the Command Line Tools

The Amazon RDS Command Line Interface (CLI) has been deprecated. Instead, use the AWS CLI for RDS.

For information on how to download and use the AWS CLI, go to AWS Command Line Interface User Guide. For a reference of the RDS commands available in the AWS CLI, go to AWS CLI Reference for Amazon RDS.

Note

The AWS CLI does not currently support the DownloadCompleteDBLogFile REST API. If you need to download an entire log file at once, rather than in portions using the download-db-log-file-portion command, then you can continue to use the last published version of the RDS CLI and the rds-download-db-logfile command.

This section describes the prerequisites for running the command line tools, where to get the command line tools, how to set up the tools and their environment, and includes a series of common examples of tool usage.

Prerequisites

This document assumes you can work in a Linux/UNIX or Windows environment. The Amazon RDS command line tools also work correctly on Mac OS X (which resembles the Linux and UNIX command environment), but no specific Mac OS X instructions are included in this guide.

As a convention, all command line text is prefixed with a generic PROMPT> command line prompt. The actual command line prompt on your machine is likely to be different. We also use $ to indicate a Linux/UNIX specific command and C:\> for a Windows specific command. The example output resulting from the command is shown immediately thereafter without any prefix.

The Java Runtime Environment

The command line tools used in this guide require Java version 5, 6, or later to run. Either a JRE or JDK installation is acceptable. To view and download JREs for a range of platforms, including Linux/UNIX and Windows, go to http://java.sun.com/j2se/1.5.0/.

Setting the Java Home Variable

The command line tools depend on an environment variable (JAVA_HOME) to locate the Java Runtime. This environment variable should be set to the full path of the directory that contains the Java Runtime. Inside this directory is a sub directory named bin, which contains the executable java (on Linux and UNIX) or java.exe (on Windows) executable. For example, on Windows this path could be C:\Program Files (x86)\Java\jre6.

To set the Java Home variable

  1. Set the Java Home variable.

    • On Linux and UNIX, using the following command:

      $ export JAVA_HOME=<PATH>
    • On Windows, using the following command:

      C:\> setx JAVA_HOME <PATH>
    • For Mac OS X versions from 10.5 and later, using the following command:

      >export JAVA_HOME="$(/usr/libexec/java_home)"
  2. Confirm the path setting by running $JAVA_HOME/bin/java -version and checking the output.

    • On Linux/UNIX, you will see output similar to the following:

      
      $ $JAVA_HOME/bin/java -version
      java version "1.5.0_09"
      Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_09-b03)
      Java HotSpot(TM) Client VM (build 1.5.0_09-b03, mixed mode, sharing)
      						
    • On Windows, you will see output similar to the following:

      
      C:\> %JAVA_HOME%\bin\java -version
      java version "1.5.0_09"
      Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_09-b03)
      Java HotSpot(TM) Client VM (build 1.5.0_09-b03, mixed mode, sharing)

Getting the Command Line Tools

The command line tools are available as a ZIP file on the Amazon RDS web site. These tools are written in Java, and include shell scripts for Windows 2000/XP/Vista, Linux/UNIX, and Mac OSX. The ZIP file is self-contained and no installation is required; simply download the zip file and unzip it to a directory on your local machine.

Setting Up the Tools

The command line tools depend on an environment variable (AWS_RDS_HOME) to locate supporting libraries. You need to set this environment variable before you can use the tools. Set it to the path of the directory you unzipped the command line tools into. This directory is named RDSCli-A.B.nnnn (A, B and n are version/release numbers), and contains sub-directories named bin and lib.

To set the AWS_RDS_HOME environment variable

  • Open a command line window and enter one of the following commands to set the AWS_RDS_HOME environment variable.

    • On Linux and UNIX, enter the following command:

      $ export AWS_RDS_HOME=<path-to-tools>
    • On Windows, enter the following command:

      C:\> setx AWS_RDS_HOME <path-to-tools>

To make the tools easier to use, we recommend you add the tools' BIN directory to your system PATH. The rest of this guide assumes the BIN directory is in your system path.

To add the tools' BIN directory to your system path

  • Enter the following commands to add the tools' BIN directory to your system PATH.

    • On Linux and UNIX, enter the following command:

      $ export PATH=$PATH:$AWS_RDS_HOME/bin
    • On Windows, enter the following command:

      C:\> setx PATH %PATH%;%AWS_RDS_HOME%\bin

Note

The Windows environment variables are reset when you close the command window. You might want to set them permanently. Consult the documentation for your version of Windows for more information.

Note

Paths that contain a space must be wrapped in double quotes, for example:

"C:\Program Files\Java"

Overriding the Default Region

By default, Amazon RDS uses the us-east-1 region when you create DB instances and other Amazon RDS objects. To temporarily specify a different region when entering an Amazon RDS command, you can use the --url or --region common command line options. For more information about common command line options, see the Common Options for API Tools.

To avoid having to pass the URL or region with each command, you can set the EC2_REGION environment variable to the appropriate region for your use.

To override the default region

  • The following example shows how to set the default region to us-west-1.

    • On Linux and UNIX, enter the following command:

      $ export EC2_REGION=us-west-1
    • On Windows, enter the following command:

      C:\> setx EC2_REGION us-west-1

Providing Credentials for the Tools

The command line tools need the AWS Access Key and Secret Access Key provided with your AWS account. You can get them using the command line or by using the Amazon RDS console to view your account information.

The following procedure shows how to obtain your AWS access key and secret access key:

To get your access key ID and secret access key

Access keys consist of an access key ID and secret access key, which are used to sign programmatic requests that you make to AWS. If you don't have access keys, you can create them by using the AWS Management Console. We recommend that you use IAM access keys instead of AWS root account access keys. IAM lets you securely control access to AWS services and resources in your AWS account.

Note

To create access keys, you must have permissions to perform the required IAM actions. For more information, see Granting IAM User Permission to Manage Password Policy and Credentials in the IAM User Guide.

  1. Open the IAM console.

  2. In the navigation pane, choose Users.

  3. Choose your IAM user name (not the check box).

  4. Choose the Security Credentials tab and then choose Create Access Key.

  5. To see your access key, choose Show User Security Credentials. Your credentials will look something like this:

    • Access Key ID: AKIAIOSFODNN7EXAMPLE

    • Secret Access Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

  6. Choose Download Credentials, and store the keys in a secure location.

    Your secret key will no longer be available through the AWS Management Console; you will have the only copy. Keep it confidential in order to protect your account, and never email it. Do not share it outside your organization, even if an inquiry appears to come from AWS or Amazon.com. No one who legitimately represents Amazon will ever ask you for your secret key.

Related topics

The deployment includes a template file ${AWS_RDS_HOME}/credential-file-path.template that you need to edit with your information. Following are the contents of the template file:


AWSAccessKeyId=<Write your AWS access ID>
AWSSecretKey=<Write your AWS secret key>			
		

Important

On UNIX, limit permissions to the owner of the credential file:

$ chmod 600 <the file created above>

With the credentials file setup, you'll need to set the AWS_CREDENTIAL_FILE environment variable so that the Amazon RDS tools can find your information.

To set the AWS_CREDENTIAL_FILE environment variable

  1. Set the environment variable

    • On Linux and UNIX, update the variable using the following command:

      $ export AWS_CREDENTIAL_FILE=<the file created above>
    • On Windows, set the variable using the following command:

      C:\> setx AWS_CREDENTIAL_FILE <the file created above>
  2. Check that your setup works properly, run the following command:

    rds --help

    You should see the usage page for all Amazon RDS commands.

Updating to a new version of the Tools

The Amazon RDS command line tools are updated with each release of RDS. Older versions of the command line tools will no longer work with the new version of RDS. If you have a version of the command line tools that is older than the current release of RDS, you can follow these steps to install the latest version of the command line tools.

  1. Download the latest version of the command line tools from the Amazon RDS web site. The download is a self-contained ZIP and no installation is required; simply download the zip file and unzip it to a directory on your local machine.

  2. Copy the credentials file from your previous installation of the command line tools to the new installation directory. Update the AWS_CREDENTIAL_FILE environment variable so that the Amazon RDS tools can find your information.

    Set the environment variable

    • On Linux and UNIX, update the variable using the following command:

      $ export AWS_CREDENTIAL_FILE=<the new file location>
    • On Windows, set the variable using the following command:

      C:\> setx AWS_CREDENTIAL_FILE <the new file location>

  3. Set the AWS_RDS_HOME environment variable to the folder for the new installation directory.

    • On Linux and UNIX, enter the following command:

      $ export AWS_RDS_HOME=<new-path-to-tools>
    • On Windows, enter the following command:

      C:\> setx AWS_RDS_HOME <new-path-to-tools>