Added a basic RDS tutorial

docs/source/index.rst

@@ -28,7 +28,7 @@ Currently Supported Services
 
   * :doc:`SimpleDB <simpledb_tut>` -- (:doc:`API Reference <ref/sdb>`)
   * :doc:`DynamoDB <dynamodb_tut>` -- (:doc:`API Reference <ref/dynamodb>`)
-  * Relational Data Services (RDS) -- (:doc:`API Reference <ref/rds>`)
+  * :doc:`Relational Data Services (RDS) <rds_tut>` -- (:doc:`API Reference <ref/rds>`)
   * ElastiCache -- (:doc:`API Reference <ref/elasticache>`)
 
 * **Deployment and Management**

docs/source/rds_tut.rst

@@ -0,0 +1,108 @@
+.. _sqs_tut:
+
+=======================================
+An Introduction to boto's RDS interface
+=======================================
+
+This tutorial focuses on the boto interface to the Relational Database Service
+from Amazon Web Services.  This tutorial assumes that you have boto already
+downloaded and installed, and that you wish to setup a MySQL instance in RDS.
+
+Creating a Connection
+---------------------
+The first step in accessing RDS is to create a connection to the service.
+The recommended method of doing this is as follows::
+
+    >>> import boto.rds
+    >>> conn = boto.rds.connect_to_region(
+    ...     "us-east-1",
+    ...     aws_access_key_id='<aws access key'>,
+    ...     aws_secret_access_key='<aws secret key>')
+
+At this point the variable conn will point to an RDSConnection object in the
+US-EAST-1 region. Bear in mind that just as any other AWS service, RDS is
+region-specific. In this example, the AWS access key and AWS secret key are
+passed in to the method explicitely. Alternatively, you can set the environment
+variables:
+
+* ``AWS_ACCESS_KEY_ID`` - Your AWS Access Key ID
+* ``AWS_SECRET_ACCESS_KEY`` - Your AWS Secret Access Key
+
+and then simply call::
+
+    >>> import boto.rds
+    >>> conn = boto.rds.connect_to_region("us-east-1")
+
+In either case, conn will point to an RDSConnection object which we will
+use throughout the remainder of this tutorial.
+
+Starting an RDS Instance
+------------------------
+
+Creating a DB instance is easy. You can do so as follows::
+
+   >>> db = conn.create_dbinstance("db-master-1", 10, 'db.m1.small', 'root', 'hunter2')
+
+This example would create a DB identified as ``db-master-1`` with 10GB of
+storage. This instance would be running on ``db.m1.small`` type, with the login
+name being ``root``, and the password ``hunter2``.
+
+To check on the status of your RDS instance, you will have to query the RDS connection again::
+
+    >>> instances = conn.get_all_dbinstances("db-master-1")
+    >>> instances
+    [DBInstance:db-master-1]
+    >>> db = instances[0]
+    >>> db.status
+    u'available'
+    >>> db.endpoint
+    (u'db-master-1.aaaaaaaaaa.us-east-1.rds.amazonaws.com', 3306)
+
+Creating a Security Group
+-------------------------
+
+Before you can actually connect to this RDS service, you must first
+create a security group. You can add a CIDR range or an :py:class:`EC2 security
+group <boto.ec2.securitygroup.SecurityGroup>`  to your :py:class:`DB security
+group <boto.rds.dbsecuritygroup.DBSecurityGroup>` ::
+
+    >>> sg = conn.create_dbsecurity_group('web_servers', 'Web front-ends')
+    >>> sg.authorize(cidr_ip='10.3.2.45/32')
+    True
+
+You can then associate this security group with your RDS instance::
+
+    >>> db.modify(security_groups=[sg])
+
+
+Connecting to your New Database
+-------------------------------
+
+Once you have reached this step, you can connect to your RDS instance as you
+would with any other MySQL instance::
+
+    >>> db.endpoint
+    (u'db-master-1.aaaaaaaaaa.us-east-1.rds.amazonaws.com', 3306)
+
+    % mysql -h db-master-1.aaaaaaaaaa.us-east-1.rds.amazonaws.com -u root -phunter2
+    mysql> 
+
+
+Making a backup
+---------------
+
+You can also create snapshots of your database very easily::
+
+    >>> db.snapshot('db-master-1-2013-02-05')
+    DBSnapshot:db-master-1-2013-02-05
+
+
+Once this snapshot is complete, you can create a new database instance from
+it::
+
+    >>> db2 = conn.restore_dbinstance_from_dbsnapshot(
+    ...    'db-master-1-2013-02-05', 
+    ...    'db-restored-1',
+    ...    'db.m1.small',
+    ...    'us-east-1')
+