1
# Copyright (c) 2009 Mitch Garnaat http://garnaat.org/
3
# Permission is hereby granted, free of charge, to any person obtaining a
4
# copy of this software and associated documentation files (the
5
# "Software"), to deal in the Software without restriction, including
6
# without limitation the rights to use, copy, modify, merge, publish, dis-
7
# tribute, sublicense, and/or sell copies of the Software, and to permit
8
# persons to whom the Software is furnished to do so, subject to the fol-
11
# The above copyright notice and this permission notice shall be included
12
# in all copies or substantial portions of the Software.
14
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
15
# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABIL-
16
# ITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
17
# SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
18
# WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
25
from boto.connection import AWSQueryConnection
26
from boto.rds.dbinstance import DBInstance
27
from boto.rds.dbsecuritygroup import DBSecurityGroup
28
from boto.rds.parametergroup import ParameterGroup
29
from boto.rds.dbsnapshot import DBSnapshot
30
from boto.rds.event import Event
32
#boto.set_stream_logger('rds')
34
class RDSConnection(AWSQueryConnection):
36
DefaultHost = 'rds.amazonaws.com'
37
APIVersion = '2009-10-16'
38
SignatureVersion = '2'
40
def __init__(self, aws_access_key_id=None, aws_secret_access_key=None,
41
is_secure=True, port=None, proxy=None, proxy_port=None,
42
proxy_user=None, proxy_pass=None, host=DefaultHost, debug=0,
43
https_connection_factory=None, path='/'):
44
AWSQueryConnection.__init__(self, aws_access_key_id, aws_secret_access_key,
45
is_secure, port, proxy, proxy_port, proxy_user,
46
proxy_pass, self.DefaultHost, debug,
47
https_connection_factory, path)
51
def get_all_dbinstances(self, instance_id=None, max_records=None,
54
Retrieve all the DBInstances in your account.
56
:type instance_id: str
57
:param instance_id: DB Instance identifier. If supplied, only information
58
this instance will be returned. Otherwise, info
59
about all DB Instances will be returned.
61
:type max_records: int
62
:param max_records: The maximum number of records to be returned.
63
If more results are available, a MoreToken will
64
be returned in the response that can be used to
65
retrieve additional records. Default is 100.
68
:param marker: The marker provided by a previous request.
71
:return: A list of :class:`boto.rds.dbinstance.DBInstance`
75
params['DBInstanceIdentifier'] = instance_id
77
params['MaxRecords'] = max_records
79
params['Marker'] = marker
80
return self.get_list('DescribeDBInstances', params, [('DBInstance', DBInstance)])
82
def create_dbinstance(self, id, allocated_storage, instance_class,
83
master_username, master_password, port=3306,
84
engine='MySQL5.1', db_name=None, param_group=None,
85
security_groups=None, availability_zone=None,
86
preferred_maintenance_window=None,
87
backup_retention_period=None,
88
preferred_backup_window=None):
90
Create a new DBInstance.
93
:param id: Unique identifier for the new instance.
94
Must contain 1-63 alphanumeric characters.
95
First character must be a letter.
96
May not end with a hyphen or contain two consecutive hyphens
98
:type allocated_storage: int
99
:param allocated_storage: Initially allocated storage size, in GBs.
100
Valid values are [5-1024]
102
:type instance_class: str
103
:param instance_class: The compute and memory capacity of the DBInstance.
105
db.m1.small | db.m1.large | db.m1.xlarge |
106
db.m2.2xlarge | db.m2.4xlarge
109
:param engine: Name of database engine. Must be MySQL5.1 for now.
111
:type master_username: str
112
:param master_username: Name of master user for the DBInstance.
113
Must be 1-15 alphanumeric characters, first must be
116
:type master_password: str
117
:param master_password: Password of master user for the DBInstance.
118
Must be 4-16 alphanumeric characters.
121
:param port: Port number on which database accepts connections.
122
Valid values [1115-65535]. Defaults to 3306.
125
:param db_name: Name of a database to create when the DBInstance
126
is created. Default is to create no databases.
128
:type param_group: str
129
:param param_group: Name of DBParameterGroup to associate with
130
this DBInstance. If no groups are specified
131
no parameter groups will be used.
133
:type security_groups: list of str or list of DBSecurityGroup objects
134
:param security_groups: List of names of DBSecurityGroup to authorize on
137
:type availability_zone: str
138
:param availability_zone: Name of the availability zone to place
141
:type preferred_maintenance_window: str
142
:param preferred_maintenance_window: The weekly time range (in UTC) during
143
which maintenance can occur.
144
Default is Sun:05:00-Sun:09:00
146
:type backup_retention_period: int
147
:param backup_retention_period: The number of days for which automated
148
backups are retained. Setting this to
149
zero disables automated backups.
151
:type preferred_backup_window: str
152
:param preferred_backup_window: The daily time range during which
153
automated backups are created (if
154
enabled). Must be in h24:mi-hh24:mi
157
:rtype: :class:`boto.rds.dbinstance.DBInstance`
158
:return: The new db instance.
160
params = {'DBInstanceIdentifier' : id,
161
'AllocatedStorage' : allocated_storage,
162
'DBInstanceClass' : instance_class,
164
'MasterUsername' : master_username,
165
'MasterUserPassword' : master_password}
167
params['Port'] = port
169
params['DBName'] = db_name
171
params['DBParameterGroup'] = param_group
174
for group in security_groups:
175
if isinstance(group, DBSecurityGroup):
179
self.build_list_params(params, l, 'DBSecurityGroups.member')
180
if availability_zone:
181
params['AvailabilityZone'] = availability_zone
182
if preferred_maintenance_window:
183
params['PreferredMaintenanceWindow'] = preferred_maintenance_window
184
if backup_retention_period:
185
params['BackupRetentionPeriod'] = backup_retention_period
186
if preferred_backup_window:
187
params['PreferredBackupWindow'] = preferred_backup_window
189
return self.get_object('CreateDBInstance', params, DBInstance)
191
def modify_dbinstance(self, id, param_group=None, security_groups=None,
192
preferred_maintenance_window=None,
193
master_password=None, allocated_storage=None,
195
backup_retention_period=None,
196
preferred_backup_window=None,
197
apply_immediately=False):
199
Modify an existing DBInstance.
202
:param id: Unique identifier for the new instance.
204
:type security_groups: list of str or list of DBSecurityGroup objects
205
:param security_groups: List of names of DBSecurityGroup to authorize on
208
:type preferred_maintenance_window: str
209
:param preferred_maintenance_window: The weekly time range (in UTC) during
210
which maintenance can occur.
211
Default is Sun:05:00-Sun:09:00
213
:type master_password: str
214
:param master_password: Password of master user for the DBInstance.
215
Must be 4-15 alphanumeric characters.
217
:type allocated_storage: int
218
:param allocated_storage: The new allocated storage size, in GBs.
219
Valid values are [5-1024]
221
:type instance_class: str
222
:param instance_class: The compute and memory capacity of the DBInstance.
223
Changes will be applied at next maintenance
224
window unless apply_immediately is True.
226
db.m1.small | db.m1.large | db.m1.xlarge |
227
db.m2.2xlarge | db.m2.4xlarge
229
:type apply_immediately: bool
230
:param apply_immediately: If true, the modifications will be applied
231
as soon as possible rather than waiting for
232
the next preferred maintenance window.
234
:type backup_retention_period: int
235
:param backup_retention_period: The number of days for which automated
236
backups are retained. Setting this to
237
zero disables automated backups.
239
:type preferred_backup_window: str
240
:param preferred_backup_window: The daily time range during which
241
automated backups are created (if
242
enabled). Must be in h24:mi-hh24:mi
245
:rtype: :class:`boto.rds.dbinstance.DBInstance`
246
:return: The modified db instance.
248
params = {'DBInstanceIdentifier' : id}
250
params['DBParameterGroupName'] = param_group
253
for group in security_groups:
254
if isinstance(group, DBSecurityGroup):
258
self.build_list_params(params, l, 'DBSecurityGroups.member')
259
if preferred_maintenance_window:
260
params['PreferredMaintenanceWindow'] = preferred_maintenance_window
262
params['MasterUserPassword'] = master_password
263
if allocated_storage:
264
params['AllocatedStorage'] = allocated_storage
266
params['DBInstanceClass'] = instance_class
267
if backup_retention_period:
268
params['BackupRetentionPeriod'] = backup_retention_period
269
if preferred_backup_window:
270
params['PreferredBackupWindow'] = preferred_backup_window
271
if apply_immediately:
272
params['ApplyImmediately'] = 'true'
274
return self.get_object('ModifyDBInstance', params, DBInstance)
276
def delete_dbinstance(self, id, skip_final_snapshot=False,
277
final_snapshot_id=''):
279
Delete an existing DBInstance.
282
:param id: Unique identifier for the new instance.
284
:type skip_final_snapshot: bool
285
:param skip_final_snapshot: This parameter determines whether a final
286
db snapshot is created before the instance
287
is deleted. If True, no snapshot is created.
288
If False, a snapshot is created before
289
deleting the instance.
291
:type final_snapshot_id: str
292
:param final_snapshot_id: If a final snapshot is requested, this
293
is the identifier used for that snapshot.
295
:rtype: :class:`boto.rds.dbinstance.DBInstance`
296
:return: The deleted db instance.
298
params = {'DBInstanceIdentifier' : id}
299
if skip_final_snapshot:
300
params['SkipFinalSnapshot'] = 'true'
302
params['SkipFinalSnapshot'] = 'false'
303
params['FinalDBSnapshotIdentifier'] = final_snapshot_id
304
return self.get_object('DeleteDBInstance', params, DBInstance)
306
# DBParameterGroup methods
308
def get_all_dbparameter_groups(self, groupname=None, max_records=None,
311
Get all parameter groups associated with your account in a region.
314
:param groupname: The name of the DBParameter group to retrieve.
315
If not provided, all DBParameter groups will be returned.
317
:type max_records: int
318
:param max_records: The maximum number of records to be returned.
319
If more results are available, a MoreToken will
320
be returned in the response that can be used to
321
retrieve additional records. Default is 100.
324
:param marker: The marker provided by a previous request.
327
:return: A list of :class:`boto.ec2.parametergroup.ParameterGroup`
331
params['DBParameterGroupName'] = groupname
333
params['MaxRecords'] = max_records
335
params['Marker'] = marker
336
return self.get_list('DescribeDBParameterGroups', params,
337
[('DBParameterGroup', ParameterGroup)])
339
def get_all_dbparameters(self, groupname, source=None,
340
max_records=None, marker=None):
342
Get all parameters associated with a ParameterGroup
345
:param groupname: The name of the DBParameter group to retrieve.
348
:param source: Specifies which parameters to return.
349
If not specified, all parameters will be returned.
350
Valid values are: user|system|engine-default
352
:type max_records: int
353
:param max_records: The maximum number of records to be returned.
354
If more results are available, a MoreToken will
355
be returned in the response that can be used to
356
retrieve additional records. Default is 100.
359
:param marker: The marker provided by a previous request.
361
:rtype: :class:`boto.ec2.parametergroup.ParameterGroup`
362
:return: The ParameterGroup
364
params = {'DBParameterGroupName' : groupname}
366
params['Source'] = source
368
params['MaxRecords'] = max_records
370
params['Marker'] = marker
371
pg = self.get_object('DescribeDBParameters', params, ParameterGroup)
375
def create_parameter_group(self, name, engine='MySQL5.1', description=''):
377
Create a new dbparameter group for your account.
380
:param name: The name of the new dbparameter group
383
:param engine: Name of database engine. Must be MySQL5.1 for now.
385
:type description: string
386
:param description: The description of the new security group
388
:rtype: :class:`boto.rds.dbsecuritygroup.DBSecurityGroup`
389
:return: The newly created DBSecurityGroup
391
params = {'DBParameterGroupName': name,
393
'Description' : description}
394
return self.get_object('CreateDBParameterGroup', params, ParameterGroup)
396
def modify_parameter_group(self, name, parameters=None):
398
Modify a parameter group for your account.
401
:param name: The name of the new parameter group
403
:type parameters: list of :class:`boto.rds.parametergroup.Parameter`
404
:param parameters: The new parameters
406
:rtype: :class:`boto.rds.parametergroup.ParameterGroup`
407
:return: The newly created ParameterGroup
409
params = {'DBParameterGroupName': name}
410
for i in range(0, len(parameters)):
411
parameter = parameters[i]
412
parameter.merge(params, i+1)
413
return self.get_list('ModifyDBParameterGroup', params, ParameterGroup)
415
def reset_parameter_group(self, name, reset_all_params=False, parameters=None):
417
Resets some or all of the parameters of a ParameterGroup to the
420
:type key_name: string
421
:param key_name: The name of the ParameterGroup to reset
423
:type parameters: list of :class:`boto.rds.parametergroup.Parameter`
424
:param parameters: The parameters to reset. If not supplied, all parameters
427
params = {'DBParameterGroupName':name}
429
params['ResetAllParameters'] = 'true'
431
params['ResetAllParameters'] = 'false'
432
for i in range(0, len(parameters)):
433
parameter = parameters[i]
434
parameter.merge(params, i+1)
435
return self.get_status('ResetDBParameterGroup', params)
437
def delete_parameter_group(self, name):
439
Delete a DBSecurityGroup from your account.
441
:type key_name: string
442
:param key_name: The name of the DBSecurityGroup to delete
444
params = {'DBParameterGroupName':name}
445
return self.get_status('DeleteDBParameterGroup', params)
447
# DBSecurityGroup methods
449
def get_all_dbsecurity_groups(self, groupname=None, max_records=None,
452
Get all security groups associated with your account in a region.
454
:type groupnames: list
455
:param groupnames: A list of the names of security groups to retrieve.
456
If not provided, all security groups will be returned.
458
:type max_records: int
459
:param max_records: The maximum number of records to be returned.
460
If more results are available, a MoreToken will
461
be returned in the response that can be used to
462
retrieve additional records. Default is 100.
465
:param marker: The marker provided by a previous request.
468
:return: A list of :class:`boto.rds.dbsecuritygroup.DBSecurityGroup`
472
params['DBSecurityGroupName'] = groupname
474
params['MaxRecords'] = max_records
476
params['Marker'] = marker
477
return self.get_list('DescribeDBSecurityGroups', params,
478
[('DBSecurityGroup', DBSecurityGroup)])
480
def create_dbsecurity_group(self, name, description=None):
482
Create a new security group for your account.
483
This will create the security group within the region you
484
are currently connected to.
487
:param name: The name of the new security group
489
:type description: string
490
:param description: The description of the new security group
492
:rtype: :class:`boto.rds.dbsecuritygroup.DBSecurityGroup`
493
:return: The newly created DBSecurityGroup
495
params = {'DBSecurityGroupName':name}
497
params['DBSecurityGroupDescription'] = description
498
group = self.get_object('CreateDBSecurityGroup', params, DBSecurityGroup)
500
group.description = description
503
def delete_dbsecurity_group(self, name):
505
Delete a DBSecurityGroup from your account.
507
:type key_name: string
508
:param key_name: The name of the DBSecurityGroup to delete
510
params = {'DBSecurityGroupName':name}
511
return self.get_status('DeleteDBSecurityGroup', params)
513
def authorize_dbsecurity_group(self, group_name, cidr_ip=None,
514
ec2_security_group_name=None,
515
ec2_security_group_owner_id=None):
517
Add a new rule to an existing security group.
518
You need to pass in either src_security_group_name and
519
src_security_group_owner_id OR a CIDR block but not both.
521
:type group_name: string
522
:param group_name: The name of the security group you are adding
525
:type ec2_security_group_name: string
526
:param ec2_security_group_name: The name of the EC2 security group you are
529
:type ec2_security_group_owner_id: string
530
:param ec2_security_group_owner_id: The ID of the owner of the EC2 security
531
group you are granting access to.
533
:type cidr_ip: string
534
:param cidr_ip: The CIDR block you are providing access to.
535
See http://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing
538
:return: True if successful.
540
params = {'DBSecurityGroupName':group_name}
541
if ec2_security_group_name:
542
params['EC2SecurityGroupName'] = ec2_security_group_name
543
if ec2_security_group_owner_id:
544
params['EC2SecurityGroupOwnerId'] = ec2_security_group_owner_id
546
params['CIDRIP'] = urllib.quote(cidr_ip)
547
return self.get_object('AuthorizeDBSecurityGroupIngress', params, DBSecurityGroup)
549
def revoke_security_group(self, group_name, ec2_security_group_name=None,
550
ec2_security_group_owner_id=None, cidr_ip=None):
552
Remove an existing rule from an existing security group.
553
You need to pass in either ec2_security_group_name and
554
ec2_security_group_owner_id OR a CIDR block.
556
:type group_name: string
557
:param group_name: The name of the security group you are removing
560
:type ec2_security_group_name: string
561
:param ec2_security_group_name: The name of the EC2 security group you are
564
:type ec2_security_group_owner_id: string
565
:param ec2_security_group_owner_id: The ID of the owner of the EC2 security
566
group you are granting access to.
568
:type cidr_ip: string
569
:param cidr_ip: The CIDR block you are providing access to.
570
See http://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing
573
:return: True if successful.
575
params = {'DBSecurityGroupName':group_name}
576
if ec2_security_group_name:
577
params['EC2SecurityGroupName'] = ec2_security_group_name
578
if ec2_security_group_owner_id:
579
params['EC2SecurityGroupOwnerId'] = ec2_security_group_owner_id
581
params['CIDRIP'] = cidr_ip
582
return self.get_object('RevokeDBSecurityGroupIngress', params, DBSecurityGroup)
586
def get_all_dbsnapshots(self, snapshot_id=None, instance_id=None,
587
max_records=None, marker=None):
589
Get information about DB Snapshots.
591
:type snapshot_id: str
592
:param snapshot_id: The unique identifier of an RDS snapshot.
593
If not provided, all RDS snapshots will be returned.
595
:type instance_id: str
596
:param instance_id: The identifier of a DBInstance. If provided,
597
only the DBSnapshots related to that instance will
599
If not provided, all RDS snapshots will be returned.
601
:type max_records: int
602
:param max_records: The maximum number of records to be returned.
603
If more results are available, a MoreToken will
604
be returned in the response that can be used to
605
retrieve additional records. Default is 100.
608
:param marker: The marker provided by a previous request.
611
:return: A list of :class:`boto.rds.dbsnapshot.DBSnapshot`
615
params['DBSnapshotIdentifier'] = snapshot_id
617
params['DBInstanceIdentifier'] = instance_id
619
params['MaxRecords'] = max_records
621
params['Marker'] = marker
622
return self.get_list('DescribeDBSnapshots', params,
623
[('DBSnapshot', DBSnapshot)])
625
def create_dbsnapshot(self, snapshot_id, dbinstance_id):
627
Create a new DB snapshot.
629
:type snapshot_id: string
630
:param snapshot_id: The identifier for the DBSnapshot
632
:type dbinstance_id: string
633
:param dbinstance_id: The source identifier for the RDS instance from
634
which the snapshot is created.
636
:rtype: :class:`boto.rds.dbsnapshot.DBSnapshot`
637
:return: The newly created DBSnapshot
639
params = {'DBSnapshotIdentifier' : snapshot_id,
640
'DBInstanceIdentifier' : dbinstance_id}
641
return self.get_object('CreateDBSnapshot', params, DBSnapshot)
643
def delete_dbsnapshot(self, identifier):
647
:type identifier: string
648
:param identifier: The identifier of the DBSnapshot to delete
650
params = {'DBSnapshotIdentifier' : identifier}
651
return self.get_object('DeleteDBSnapshot', params, DBSnapshot)
653
def restore_dbinstance_from_dbsnapshot(self, identifier, instance_id,
654
instance_class, port=None,
655
availability_zone=None):
658
Create a new DBInstance from a DB snapshot.
660
:type identifier: string
661
:param identifier: The identifier for the DBSnapshot
663
:type instance_id: string
664
:param instance_id: The source identifier for the RDS instance from
665
which the snapshot is created.
667
:type instance_class: str
668
:param instance_class: The compute and memory capacity of the DBInstance.
670
db.m1.small | db.m1.large | db.m1.xlarge |
671
db.m2.2xlarge | db.m2.4xlarge
674
:param port: Port number on which database accepts connections.
675
Valid values [1115-65535]. Defaults to 3306.
677
:type availability_zone: str
678
:param availability_zone: Name of the availability zone to place
681
:rtype: :class:`boto.rds.dbinstance.DBInstance`
682
:return: The newly created DBInstance
684
params = {'DBSnapshotIdentifier' : identifier,
685
'DBInstanceIdentifier' : instance_id,
686
'DBInstanceClass' : instance_class}
688
params['Port'] = port
689
if availability_zone:
690
params['AvailabilityZone'] = availability_zone
691
return self.get_object('RestoreDBInstanceFromDBSnapshot',
694
def restore_dbinstance_from_point_in_time(self, source_instance_id,
698
dbinstance_class=None,
700
availability_zone=None):
703
Create a new DBInstance from a point in time.
705
:type source_instance_id: string
706
:param source_instance_id: The identifier for the source DBInstance.
708
:type target_instance_id: string
709
:param target_instance_id: The identifier of the new DBInstance.
711
:type use_latest: bool
712
:param use_latest: If True, the latest snapshot availabile will
715
:type restore_time: datetime
716
:param restore_time: The date and time to restore from. Only
717
used if use_latest is False.
719
:type instance_class: str
720
:param instance_class: The compute and memory capacity of the DBInstance.
722
db.m1.small | db.m1.large | db.m1.xlarge |
723
db.m2.2xlarge | db.m2.4xlarge
726
:param port: Port number on which database accepts connections.
727
Valid values [1115-65535]. Defaults to 3306.
729
:type availability_zone: str
730
:param availability_zone: Name of the availability zone to place
733
:rtype: :class:`boto.rds.dbinstance.DBInstance`
734
:return: The newly created DBInstance
736
params = {'SourceDBInstanceIdentifier' : source_instance_id,
737
'TargetDBInstanceIdentifier' : target_instance_id}
739
params['UseLatestRestorableTime'] = 'true'
741
params['RestoreTime'] = restore_time.isoformat()
743
params['DBInstanceClass'] = dbinstance_class
745
params['Port'] = port
746
if availability_zone:
747
params['AvailabilityZone'] = availability_zone
748
return self.get_object('RestoreDBInstanceToPointInTime',
753
def get_all_events(self, source_identifier=None, source_type=None,
754
start_time=None, end_time=None,
755
max_records=None, marker=None):
757
Get information about events related to your DBInstances,
758
DBSecurityGroups and DBParameterGroups.
760
:type source_identifier: str
761
:param source_identifier: If supplied, the events returned will be
762
limited to those that apply to the identified
763
source. The value of this parameter depends
764
on the value of source_type. If neither
765
parameter is specified, all events in the time
766
span will be returned.
768
:type source_type: str
769
:param source_type: Specifies how the source_identifier should
770
be interpreted. Valid values are:
771
b-instance | db-security-group |
772
db-parameter-group | db-snapshot
774
:type start_time: datetime
775
:param start_time: The beginning of the time interval for events.
776
If not supplied, all available events will
779
:type end_time: datetime
780
:param end_time: The ending of the time interval for events.
781
If not supplied, all available events will
784
:type max_records: int
785
:param max_records: The maximum number of records to be returned.
786
If more results are available, a MoreToken will
787
be returned in the response that can be used to
788
retrieve additional records. Default is 100.
791
:param marker: The marker provided by a previous request.
794
:return: A list of class:`boto.rds.event.Event`
797
if source_identifier and source_type:
798
params['SourceIdentifier'] = source_identifier
799
params['SourceType'] = source_type
801
params['StartTime'] = start_time.isoformat()
803
params['EndTime'] = end_time.isoformat()
805
params['MaxRecords'] = max_records
807
params['Marker'] = marker
808
return self.get_list('DescribeEvents', params, [('Event', Event)])