Adding documentation
diff --git a/openstack/db/v1/databases/doc.go b/openstack/db/v1/databases/doc.go
index 18cbec7..15275fe 100644
--- a/openstack/db/v1/databases/doc.go
+++ b/openstack/db/v1/databases/doc.go
@@ -1 +1,6 @@
+// Package flavors provides information and interaction with the database API
+// resource in the OpenStack Database service.
+//
+// A database, when referred to here, refers to the database engine running on
+// an instance.
package databases
diff --git a/openstack/db/v1/databases/requests.go b/openstack/db/v1/databases/requests.go
index 4d10878..812b193 100644
--- a/openstack/db/v1/databases/requests.go
+++ b/openstack/db/v1/databases/requests.go
@@ -7,6 +7,7 @@
"github.com/rackspace/gophercloud/pagination"
)
+// CreateOptsBuilder builds create options
type CreateOptsBuilder interface {
ToDBCreateMap() (map[string]interface{}, error)
}
@@ -14,17 +15,28 @@
// DatabaseOpts is the struct responsible for configuring a database; often in
// the context of an instance.
type CreateOpts struct {
- // Specifies the name of the database. Optional.
+ // [REQUIRED] Specifies the name of the database. Valid names can be composed
+ // of the following characters: letters (either case); numbers; these
+ // characters '@', '?', '#', ' ' but NEVER beginning a name string; '_' is
+ // permitted anywhere. Prohibited characters that are forbidden include:
+ // single quotes, double quotes, back quotes, semicolons, commas, backslashes,
+ // and forward slashes.
Name string
- // Set of symbols and encodings. Optional; the default character set is utf8.
+ // [OPTIONAL] Set of symbols and encodings. The default character set is
+ // "utf8". See http://dev.mysql.com/doc/refman/5.1/en/charset-mysql.html for
+ // supported character sets.
CharSet string
- // Set of rules for comparing characters in a character set. Optional; the
- // default value for collate is utf8_general_ci.
+ // [OPTIONAL] Set of rules for comparing characters in a character set. The
+ // default value for collate is "utf8_general_ci". See
+ // http://dev.mysql.com/doc/refman/5.1/en/charset-mysql.html for supported
+ // collations.
Collate string
}
+// ToMap is a helper function to convert individual DB create opt structures
+// into sub-maps.
func (opts CreateOpts) ToMap() (map[string]string, error) {
if opts.Name == "" {
return nil, fmt.Errorf("Name is a required field")
@@ -44,8 +56,10 @@
return db, nil
}
+// BatchCreateOpts allows for multiple databases to created and modified.
type BatchCreateOpts []CreateOpts
+// ToDBCreateMap renders a JSON map for creating DBs.
func (opts BatchCreateOpts) ToDBCreateMap() (map[string]interface{}, error) {
var dbs []map[string]string
for _, db := range opts {
@@ -58,6 +72,8 @@
return map[string]interface{}{"databases": dbs}, nil
}
+// Create will create a new database within the specified instance. If the
+// specified instance does not exist, a 404 error will be returned.
func Create(client *gophercloud.ServiceClient, instanceID string, opts CreateOptsBuilder) CreateResult {
var res CreateResult
@@ -76,6 +92,9 @@
return res
}
+// List will list all of the databases for a specified instance. Note: this
+// operation will only return user-defined databases; it will exclude system
+// databases like "mysql", "information_schema", "lost+found" etc.
func List(client *gophercloud.ServiceClient, instanceID string) pagination.Pager {
createPageFn := func(r pagination.PageResult) pagination.Page {
return DBPage{pagination.LinkedPageBase{PageResult: r}}
@@ -84,6 +103,8 @@
return pagination.NewPager(client, baseURL(client, instanceID), createPageFn)
}
+// Delete will permanently delete the database within a specified instance.
+// All contained data inside the database will also be permanently deleted.
func Delete(client *gophercloud.ServiceClient, instanceID, dbName string) DeleteResult {
var res DeleteResult
diff --git a/openstack/db/v1/databases/results.go b/openstack/db/v1/databases/results.go
index 85e3363..7c967f5 100644
--- a/openstack/db/v1/databases/results.go
+++ b/openstack/db/v1/databases/results.go
@@ -6,8 +6,9 @@
"github.com/rackspace/gophercloud/pagination"
)
+// Database represents a Database API resource.
type Database struct {
- // Specifies the name of the MySQL DB.
+ // Specifies the name of the MySQL database.
Name string
// Set of symbols and encodings. The default character set is utf8.
@@ -18,10 +19,16 @@
Collate string
}
+// CreateResult represents the result of a Create operation.
type CreateResult struct {
gophercloud.Result
}
+// DeleteResult represents the result of a Delete operation.
+type DeleteResult struct {
+ gophercloud.ErrResult
+}
+
// DBPage represents a single page of a paginated DB collection.
type DBPage struct {
pagination.LinkedPageBase
@@ -63,7 +70,3 @@
err := mapstructure.Decode(casted, &response)
return response.Databases, err
}
-
-type DeleteResult struct {
- gophercloud.ErrResult
-}
diff --git a/openstack/db/v1/flavors/doc.go b/openstack/db/v1/flavors/doc.go
index 5822e1b..4d281d5 100644
--- a/openstack/db/v1/flavors/doc.go
+++ b/openstack/db/v1/flavors/doc.go
@@ -1,7 +1,7 @@
// Package flavors provides information and interaction with the flavor API
-// resource in the OpenStack Compute service.
+// resource in the OpenStack Database service.
//
-// A flavor is an available hardware configuration for a server. Each flavor
-// has a unique combination of disk space, memory capacity and priority for CPU
-// time.
+// A flavor is an available hardware configuration for a database instance.
+// Each flavor has a unique combination of disk space, memory capacity and
+// priority for CPU time.
package flavors
diff --git a/openstack/db/v1/flavors/fixtures.go b/openstack/db/v1/flavors/fixtures.go
index f0016bc..c7102e7 100644
--- a/openstack/db/v1/flavors/fixtures.go
+++ b/openstack/db/v1/flavors/fixtures.go
@@ -26,7 +26,7 @@
`
var (
- flavorID = "{flavorID}"
+ flavorID = 1
_baseURL = "/flavors"
resURL = "/flavors/" + flavorID
)
diff --git a/openstack/db/v1/flavors/requests.go b/openstack/db/v1/flavors/requests.go
index b67a07b..beeeddc 100644
--- a/openstack/db/v1/flavors/requests.go
+++ b/openstack/db/v1/flavors/requests.go
@@ -5,6 +5,9 @@
"github.com/rackspace/gophercloud/pagination"
)
+// List will list all available hardware flavors that an instance can use. The
+// operation is identical to the one supported by the Nova API, but without the
+// "disk" property.
func List(client *gophercloud.ServiceClient) pagination.Pager {
createPage := func(r pagination.PageResult) pagination.Page {
return FlavorPage{pagination.LinkedPageBase{PageResult: r}}
@@ -13,7 +16,8 @@
return pagination.NewPager(client, listURL(client), createPage)
}
-func Get(client *gophercloud.ServiceClient, id string) GetResult {
+// Get will retrieve information for a specified hardware flavor.
+func Get(client *gophercloud.ServiceClient, id int) GetResult {
var gr GetResult
_, gr.Err = client.Request("GET", getURL(client, id), gophercloud.RequestOpts{
diff --git a/openstack/db/v1/flavors/results.go b/openstack/db/v1/flavors/results.go
index 5aac5ce..d3f507e 100644
--- a/openstack/db/v1/flavors/results.go
+++ b/openstack/db/v1/flavors/results.go
@@ -1,16 +1,11 @@
package flavors
import (
- "errors"
-
"github.com/mitchellh/mapstructure"
"github.com/rackspace/gophercloud"
"github.com/rackspace/gophercloud/pagination"
)
-// ErrCannotInterpret is returned by an Extract call if the response body doesn't have the expected structure.
-var ErrCannotInterpet = errors.New("Unable to interpret a response body.")
-
// GetResult temporarily holds the response from a Get call.
type GetResult struct {
gophercloud.Result
@@ -32,15 +27,16 @@
// Flavor records represent (virtual) hardware configurations for server resources in a region.
type Flavor struct {
- // The Id field contains the flavor's unique identifier.
- // For example, this identifier will be useful when specifying which hardware configuration to use for a new server instance.
+ // The flavor's unique identifier.
ID int `mapstructure:"id"`
+ // The RAM capacity for the flavor.
RAM int `mapstructure:"ram"`
// The Name field provides a human-readable moniker for the flavor.
Name string `mapstructure:"name"`
+ // Links to access the flavor.
Links []gophercloud.Link
}
diff --git a/openstack/db/v1/instances/doc.go b/openstack/db/v1/instances/doc.go
index 98a1bb3..dc5c90f 100644
--- a/openstack/db/v1/instances/doc.go
+++ b/openstack/db/v1/instances/doc.go
@@ -1 +1,7 @@
+// Package instances provides information and interaction with the instance API
+// resource in the OpenStack Database service.
+//
+// A database instance is an isolated database environment with compute and
+// storage resources in a single tenant environment on a shared physical host
+// machine.
package instances
diff --git a/openstack/db/v1/instances/requests.go b/openstack/db/v1/instances/requests.go
index fc971fd..d87fdec 100644
--- a/openstack/db/v1/instances/requests.go
+++ b/openstack/db/v1/instances/requests.go
@@ -35,6 +35,7 @@
Users users.BatchCreateOpts
}
+// ToInstanceCreateMap will render a JSON map.
func (opts CreateOpts) ToInstanceCreateMap() (map[string]interface{}, error) {
if opts.Size > 300 || opts.Size < 1 {
return nil, fmt.Errorf("Size (GB) must be between 1-300")
diff --git a/openstack/db/v1/instances/results.go b/openstack/db/v1/instances/results.go
index ae3b9e0..f85db81 100644
--- a/openstack/db/v1/instances/results.go
+++ b/openstack/db/v1/instances/results.go
@@ -3,19 +3,11 @@
import (
"github.com/mitchellh/mapstructure"
"github.com/rackspace/gophercloud"
+ "github.com/rackspace/gophercloud/openstack/db/v1/flavors"
"github.com/rackspace/gophercloud/openstack/db/v1/users"
"github.com/rackspace/gophercloud/pagination"
)
-// Flavor represents information about a hardware flavor for a database instance.
-type Flavor struct {
- // The unique identifier for a flavor.
- ID string
-
- // Various links which allow a user to reference the flavor.
- Links []gophercloud.Link
-}
-
// Volume represents information about an attached volume for a database instance.
type Volume struct {
// The size in GB of the volume
@@ -33,7 +25,7 @@
Updated string //time.Time
// Indicates the hardware flavor the instance uses.
- Flavor Flavor
+ Flavor flavors.Flavor
// A DNS-resolvable hostname associated with the database instance (rather
// than an IPv4 address). Since the hostname always resolves to the correct
diff --git a/openstack/db/v1/users/doc.go b/openstack/db/v1/users/doc.go
index 82abcb9..cf07832 100644
--- a/openstack/db/v1/users/doc.go
+++ b/openstack/db/v1/users/doc.go
@@ -1 +1,3 @@
+// Package users provides information and interaction with the user API
+// resource in the OpenStack Database service.
package users
diff --git a/openstack/db/v1/users/requests.go b/openstack/db/v1/users/requests.go
index e596739..e0616db 100644
--- a/openstack/db/v1/users/requests.go
+++ b/openstack/db/v1/users/requests.go
@@ -1,11 +1,14 @@
package users
import (
+ "errors"
+
"github.com/rackspace/gophercloud"
db "github.com/rackspace/gophercloud/openstack/db/v1/databases"
"github.com/rackspace/gophercloud/pagination"
)
+// CreateOptsBuilder is the top-level interface for creating JSON maps.
type CreateOptsBuilder interface {
ToUserCreateMap() (map[string]interface{}, error)
}
@@ -13,31 +16,46 @@
// CreateOpts is the struct responsible for configuring a new user; often in the
// context of an instance.
type CreateOpts struct {
- // Specifies a name for the user.
+ // [REQUIRED] Specifies a name for the user. Valid names can be composed
+ // of the following characters: letters (either case); numbers; these
+ // characters '@', '?', '#', ' ' but NEVER beginning a name string; '_' is
+ // permitted anywhere. Prohibited characters that are forbidden include:
+ // single quotes, double quotes, back quotes, semicolons, commas, backslashes,
+ // and forward slashes. Spaces at the front or end of a user name are also
+ // not permitted.
Name string
- // Specifies a password for the user.
+ // [REQUIRED] Specifies a password for the user.
Password string
- // An array of databases that this user will connect to. The `name` field is
- // the only requirement for each option.
+ // [OPTIONAL] An array of databases that this user will connect to. The
+ // "name" field is the only requirement for each option.
Databases db.BatchCreateOpts
- // Specifies the host from which a user is allowed to connect to the database.
- // Possible values are a string containing an IPv4 address or "%" to allow
- // connecting from any host. Optional; the default is "%".
+ // [OPTIONAL] Specifies the host from which a user is allowed to connect to
+ // the database. Possible values are a string containing an IPv4 address or
+ // "%" to allow connecting from any host. Optional; the default is "%".
Host string
}
+// ToMap is a convenience function for creating sub-maps for individual users.
func (opts CreateOpts) ToMap() (map[string]interface{}, error) {
- user := map[string]interface{}{}
- if opts.Name != "" {
- user["name"] = opts.Name
+ if opts.Name == "root" {
+ return nil, errors.New("root is a reserved user name and cannot be used")
}
- if opts.Password != "" {
- user["password"] = opts.Password
+ if opts.Name == "" {
+ return nil, errors.New("Name is a required field")
}
+ if opts.Password == "" {
+ return nil, errors.New("Password is a required field")
+ }
+
+ user := map[string]interface{}{
+ "name": opts.Name,
+ "password": opts.Password,
+ }
+
if opts.Host != "" {
user["host"] = opts.Host
}
@@ -53,8 +71,10 @@
return user, nil
}
+// BatchCreateOpts allows multiple users to be created at once.
type BatchCreateOpts []CreateOpts
+// ToUserCreateMap will generate a JSON map.
func (opts BatchCreateOpts) ToUserCreateMap() (map[string]interface{}, error) {
var users []map[string]interface{}
for _, opt := range opts {
@@ -67,6 +87,10 @@
return map[string]interface{}{"users": users}, nil
}
+// Create asynchronously provisions a new user for the specified database
+// instance based on the configuration defined in CreateOpts. If databases are
+// assigned for a particular user, the user will be granted all privileges
+// for those specified databases. "root" is a reserved name and cannot be used.
func Create(client *gophercloud.ServiceClient, instanceID string, opts CreateOptsBuilder) CreateResult {
var res CreateResult
@@ -84,6 +108,9 @@
return res
}
+// List will list all the users associated with a specified database instance,
+// along with their associated databases. This operation will not return any
+// system users or administrators for a database.
func List(client *gophercloud.ServiceClient, instanceID string) pagination.Pager {
createPageFn := func(r pagination.PageResult) pagination.Page {
return UserPage{pagination.LinkedPageBase{PageResult: r}}
@@ -92,6 +119,7 @@
return pagination.NewPager(client, baseURL(client, instanceID), createPageFn)
}
+// Delete will permanently delete a user from a specified database instance.
func Delete(client *gophercloud.ServiceClient, instanceID, userName string) DeleteResult {
var res DeleteResult
diff --git a/openstack/db/v1/users/results.go b/openstack/db/v1/users/results.go
index ce07e76..217ddd8 100644
--- a/openstack/db/v1/users/results.go
+++ b/openstack/db/v1/users/results.go
@@ -19,10 +19,16 @@
Databases []db.Database
}
+// CreateResult represents the result of a create operation.
type CreateResult struct {
gophercloud.ErrResult
}
+// DeleteResult represents the result of a delete operation.
+type DeleteResult struct {
+ gophercloud.ErrResult
+}
+
// UserPage represents a single page of a paginated user collection.
type UserPage struct {
pagination.LinkedPageBase
@@ -65,7 +71,3 @@
return response.Users, err
}
-
-type DeleteResult struct {
- gophercloud.ErrResult
-}