Finish DB docs for Rackspace
diff --git a/rackspace/db/v1/configurations/doc.go b/rackspace/db/v1/configurations/doc.go
index 48c51d6..45b9cfb 100644
--- a/rackspace/db/v1/configurations/doc.go
+++ b/rackspace/db/v1/configurations/doc.go
@@ -1 +1,11 @@
+// Package configurations provides information and interaction with the
+// configuration API resource in the Rackspace Database service.
+//
+// A configuration group is a collection of key/value pairs which define how a
+// particular database operates. These key/value pairs are specific to each
+// datastore type and serve like settings. Some directives are capable of being
+// applied dynamically, while other directives require a server restart to take
+// effect. The configuration group can be applied to an instance at creation or
+// applied to an existing instance to modify the behavior of the running
+// datastore on the instance.
package configurations
diff --git a/rackspace/db/v1/configurations/requests.go b/rackspace/db/v1/configurations/requests.go
index 726176a..088b7ca 100644
--- a/rackspace/db/v1/configurations/requests.go
+++ b/rackspace/db/v1/configurations/requests.go
@@ -8,6 +8,7 @@
"github.com/rackspace/gophercloud/pagination"
)
+// List will list all of the available configurations.
func List(client *gophercloud.ServiceClient) pagination.Pager {
pageFn := func(r pagination.PageResult) pagination.Page {
return ConfigPage{pagination.SinglePageBase(r)}
@@ -16,15 +17,22 @@
return pagination.NewPager(client, baseURL(client), pageFn)
}
+// CreateOptsBuilder is a top-level interface which renders a JSON map.
type CreateOptsBuilder interface {
ToConfigCreateMap() (map[string]interface{}, error)
}
+// DatastoreOpts is the primary options struct for creating and modifying
+// how configuration resources are associated with datastores.
type DatastoreOpts struct {
- Type string
+ // [OPTIONAL] The type of datastore. Defaults to "MySQL".
+ Type string
+
+ // [OPTIONAL] The specific version of a datastore. Defaults to "5.6".
Version string
}
+// ToMap renders a JSON map for a datastore setting.
func (opts DatastoreOpts) ToMap() (map[string]string, error) {
datastore := map[string]string{}
@@ -39,13 +47,24 @@
return datastore, nil
}
+// CreateOpts is the struct responsible for configuring new configurations.
type CreateOpts struct {
- Datastore *DatastoreOpts
+ // [REQUIRED] The configuration group name
+ Name string
+
+ // [REQUIRED] A map of user-defined configuration settings that will define
+ // how each associated datastore works. Each key/value pair is specific to a
+ // datastore type.
+ Values map[string]interface{}
+
+ // [OPTIONAL] Associates the configuration group with a particular datastore.
+ Datastore *DatastoreOpts
+
+ // [OPTIONAL] A human-readable explanation for the group.
Description string
- Name string
- Values map[string]interface{}
}
+// ToConfigCreateMap casts a CreateOpts struct into a JSON map.
func (opts CreateOpts) ToConfigCreateMap() (map[string]interface{}, error) {
if opts.Name == "" {
return nil, errors.New("Name is a required field")
@@ -74,6 +93,7 @@
return map[string]interface{}{"configuration": config}, nil
}
+// Create will create a new configuration group.
func Create(client *gophercloud.ServiceClient, opts CreateOptsBuilder) CreateResult {
var res CreateResult
@@ -92,6 +112,7 @@
return res
}
+// Get will retrieve the details for a specified configuration group.
func Get(client *gophercloud.ServiceClient, configID string) GetResult {
var res GetResult
@@ -103,17 +124,30 @@
return res
}
+// UpdateOptsBuilder is the top-level interface for casting update options into
+// JSON maps.
type UpdateOptsBuilder interface {
ToConfigUpdateMap() (map[string]interface{}, error)
}
+// UpdateOpts is the struct responsible for modifying existing configurations.
type UpdateOpts struct {
- Datastore *DatastoreOpts
+ // [OPTIONAL] The configuration group name
+ Name string
+
+ // [OPTIONAL] A map of user-defined configuration settings that will define
+ // how each associated datastore works. Each key/value pair is specific to a
+ // datastore type.
+ Values map[string]interface{}
+
+ // [OPTIONAL] Associates the configuration group with a particular datastore.
+ Datastore *DatastoreOpts
+
+ // [OPTIONAL] A human-readable explanation for the group.
Description string
- Name string
- Values map[string]interface{}
}
+// ToConfigUpdateMap will cast an UpdateOpts struct into a JSON map.
func (opts UpdateOpts) ToConfigUpdateMap() (map[string]interface{}, error) {
config := map[string]interface{}{}
@@ -140,6 +174,9 @@
return map[string]interface{}{"configuration": config}, nil
}
+// Update will modify an existing configuration group by performing a merge
+// between new and existing values. If the key already exists, the new value
+// will overwrite. All other keys will remain unaffected.
func Update(client *gophercloud.ServiceClient, configID string, opts UpdateOptsBuilder) UpdateResult {
var res UpdateResult
@@ -158,6 +195,9 @@
return res
}
+// Replace will modify an existing configuration group by overwriting the
+// entire parameter group with the new values provided. Any existing keys not
+// included in UpdateOptsBuilder will be deleted.
func Replace(client *gophercloud.ServiceClient, configID string, opts UpdateOptsBuilder) ReplaceResult {
var res ReplaceResult
@@ -176,6 +216,7 @@
return res
}
+// Delete will permanently delete a configuration group.
func Delete(client *gophercloud.ServiceClient, configID string) DeleteResult {
var res DeleteResult
@@ -186,6 +227,8 @@
return res
}
+// ListInstances will list all the instances associated with a particular
+// configuration group.
func ListInstances(client *gophercloud.ServiceClient, configID string) pagination.Pager {
pageFn := func(r pagination.PageResult) pagination.Page {
return instances.InstancePage{pagination.LinkedPageBase{PageResult: r}}
@@ -193,6 +236,11 @@
return pagination.NewPager(client, instancesURL(client, configID), pageFn)
}
+// ListDatastoreParams will list all the available and supported parameters
+// that can be used for a particular datastore ID and a particular version.
+// For example, if you are wondering how you can configure a MySQL 5.6 instance,
+// you can use this operation (you will need to retrieve the MySQL datastore ID
+// by using the datastores API).
func ListDatastoreParams(client *gophercloud.ServiceClient, datastoreID, versionID string) pagination.Pager {
pageFn := func(r pagination.PageResult) pagination.Page {
return ParamPage{pagination.SinglePageBase(r)}
@@ -200,6 +248,11 @@
return pagination.NewPager(client, listDSParamsURL(client, datastoreID, versionID), pageFn)
}
+// GetDatastoreParam will retrieve information about a specific configuration
+// parameter. For example, you can use this operation to understand more about
+// "innodb_file_per_table" configuration param for MySQL datastores. You will
+// need the param's ID first, which can be attained by using the ListDatastoreParams
+// operation.
func GetDatastoreParam(client *gophercloud.ServiceClient, datastoreID, versionID, paramID string) ParamResult {
var res ParamResult
@@ -211,6 +264,8 @@
return res
}
+// ListGlobalParams is similar to ListDatastoreParams but does not require a
+// DatastoreID.
func ListGlobalParams(client *gophercloud.ServiceClient, versionID string) pagination.Pager {
pageFn := func(r pagination.PageResult) pagination.Page {
return ParamPage{pagination.SinglePageBase(r)}
@@ -218,6 +273,8 @@
return pagination.NewPager(client, listGlobalParamsURL(client, versionID), pageFn)
}
+// GetGlobalParam is similar to GetDatastoreParam but does not require a
+// DatastoreID.
func GetGlobalParam(client *gophercloud.ServiceClient, versionID, paramID string) ParamResult {
var res ParamResult
diff --git a/rackspace/db/v1/configurations/results.go b/rackspace/db/v1/configurations/results.go
index 5c960b8..98ce25f 100644
--- a/rackspace/db/v1/configurations/results.go
+++ b/rackspace/db/v1/configurations/results.go
@@ -6,6 +6,7 @@
"github.com/rackspace/gophercloud/pagination"
)
+// Config represents a configuration group API resource.
type Config struct {
Created string
Updated string
@@ -18,10 +19,12 @@
Values map[string]interface{}
}
+// ConfigPage contains a page of Config resources in a paginated collection.
type ConfigPage struct {
pagination.SinglePageBase
}
+// IsEmpty indicates whether a ConfigPage is empty.
func (r ConfigPage) IsEmpty() (bool, error) {
is, err := ExtractConfigs(r)
if err != nil {
@@ -30,6 +33,7 @@
return len(is) == 0, nil
}
+// ExtractConfigs will retrieve a slice of Config structs from a page.
func ExtractConfigs(page pagination.Page) ([]Config, error) {
casted := page.(ConfigPage).Body
@@ -45,6 +49,7 @@
gophercloud.Result
}
+// Extract will retrieve a Config resource from an operation result.
func (r commonResult) Extract() (*Config, error) {
if r.Err != nil {
return nil, r.Err
@@ -58,26 +63,32 @@
return &response.Config, err
}
+// GetResult represents the result of a Get operation.
type GetResult struct {
commonResult
}
+// CreateResult represents the result of a Create operation.
type CreateResult struct {
commonResult
}
+// UpdateResult represents the result of an Update operation.
type UpdateResult struct {
gophercloud.ErrResult
}
+// ReplaceResult represents the result of a Replace operation.
type ReplaceResult struct {
gophercloud.ErrResult
}
+// DeleteResult represents the result of a Delete operation.
type DeleteResult struct {
gophercloud.ErrResult
}
+// Param represents a configuration parameter API resource.
type Param struct {
Max int
Min int
@@ -86,10 +97,12 @@
Type string
}
+// ParamPage contains a page of Param resources in a paginated collection.
type ParamPage struct {
pagination.SinglePageBase
}
+// IsEmpty indicates whether a ParamPage is empty.
func (r ParamPage) IsEmpty() (bool, error) {
is, err := ExtractParams(r)
if err != nil {
@@ -98,6 +111,7 @@
return len(is) == 0, nil
}
+// ExtractParams will retrieve a slice of Param structs from a page.
func ExtractParams(page pagination.Page) ([]Param, error) {
casted := page.(ParamPage).Body
@@ -109,10 +123,13 @@
return resp.Params, err
}
+// ParamResult represents the result of an operation which retrieves details
+// about a particular configuration param.
type ParamResult struct {
gophercloud.Result
}
+// Extract will retrieve a param from an operation result.
func (r ParamResult) Extract() (*Param, error) {
if r.Err != nil {
return nil, r.Err