volumes

Creates, updates, deletes, gets or lists a volumes resource.

Overview

Name	volumes
Type	Resource
Id	digitalocean.compute.volumes

Fields

The following fields are returned by SELECT queries:

volumes_get

The response will be a JSON object with a key called volume. The value will be an object containing the standard attributes associated with a volume.

Name	Datatype	Description
id	string	The unique identifier for the block storage volume. (example: 506f78a4-e098-11e5-ad9f-000f53306ae1)
name	string	A human-readable name for the block storage volume. Must be lowercase and be composed only of numbers, letters and "-", up to a limit of 64 characters. The name must begin with a letter. (example: example)
created_at	string	A time value given in ISO8601 combined date and time format that represents when the block storage volume was created. (example: 2020-03-02T17:00:49Z)
description	string	An optional free-form text field to describe a block storage volume. (example: Block store for examples)
droplet_ids	array	An array containing the IDs of the Droplets the volume is attached to. Note that at this time, a volume can only be attached to a single Droplet.
filesystem_label	string	The label currently applied to the filesystem. (example: example)
filesystem_type	string	The type of filesystem currently in-use on the volume. (example: ext4)
region	object	The region that the block storage volume is located in. When setting a region, the value should be the slug identifier for the region. When you query a block storage volume, the entire region object will be returned.
size_gigabytes	integer	The size of the block storage volume in GiB (1024^3). This field does not apply when creating a volume from a snapshot.
tags	array	A flat array of tag names as strings applied to the resource. Requires tag:read scope.

volumes_list

The response will be a JSON object with a key called volumes. This will be set to an array of volume objects, each of which will contain the standard volume attributes.

Name	Datatype	Description
id	string	The unique identifier for the block storage volume. (example: 506f78a4-e098-11e5-ad9f-000f53306ae1)
name	string	A human-readable name for the block storage volume. Must be lowercase and be composed only of numbers, letters and "-", up to a limit of 64 characters. The name must begin with a letter. (example: example)
created_at	string	A time value given in ISO8601 combined date and time format that represents when the block storage volume was created. (example: 2020-03-02T17:00:49Z)
description	string	An optional free-form text field to describe a block storage volume. (example: Block store for examples)
droplet_ids	array	An array containing the IDs of the Droplets the volume is attached to. Note that at this time, a volume can only be attached to a single Droplet.
filesystem_label	string	The label currently applied to the filesystem. (example: example)
filesystem_type	string	The type of filesystem currently in-use on the volume. (example: ext4)
region	object	The region that the block storage volume is located in. When setting a region, the value should be the slug identifier for the region. When you query a block storage volume, the entire region object will be returned.
size_gigabytes	integer	The size of the block storage volume in GiB (1024^3). This field does not apply when creating a volume from a snapshot.
tags	array	A flat array of tag names as strings applied to the resource. Requires tag:read scope.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
volumes_get	select	volume_id		To show information about a block storage volume, send a GET request to /v2/volumes/$VOLUME_ID.
volumes_list	select		name, region, per_page, page	To list all of the block storage volumes available on your account, send a GET request to /v2/volumes. ## Filtering Results ### By Region The region may be provided as query parameter in order to restrict results to volumes available in a specific region. For example: /v2/volumes?region=nyc1 ### By Name It is also possible to list volumes on your account that match a specified name. To do so, send a GET request with the volume's name as a query parameter to /v2/volumes?name=$VOLUME_NAME. Note: You can only create one volume per region with the same name. ### By Name and Region It is also possible to retrieve information about a block storage volume by name. To do so, send a GET request with the volume's name and the region slug for the region it is located in as query parameters to /v2/volumes?name=$VOLUME_NAME&region=nyc1.
volumes_create	insert			To create a new volume, send a POST request to /v2/volumes. Optionally, a filesystem_type attribute may be provided in order to automatically format the volume's filesystem. Pre-formatted volumes are automatically mounted when attached to Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS Droplets created on or after April 26, 2018. Attaching pre-formatted volumes to Droplets without support for auto-mounting is not recommended.
volumes_delete	delete	volume_id		To delete a block storage volume, destroying all data and removing it from your account, send a DELETE request to /v2/volumes/$VOLUME_ID. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.
volumes_delete_by_name	delete		name, region	Block storage volumes may also be deleted by name by sending a DELETE request with the volume's name and the region slug for the region it is located in as query parameters to /v2/volumes?name=$VOLUME_NAME&region=nyc1. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.
volume_actions_post	exec		per_page, page	To initiate an action on a block storage volume by Name, send a POST request to ~/v2/volumes/actions. The body should contain the appropriate attributes for the respective action. ## Attach a Block Storage Volume to a Droplet | Attribute | Details | | ----------- | ------------------------------------------------------------------- | | type | This must be attach | | volume_name | The name of the block storage volume | | droplet_id | Set to the Droplet's ID | | region | Set to the slug representing the region where the volume is located | Each volume may only be attached to a single Droplet. However, up to fifteen volumes may be attached to a Droplet at a time. Pre-formatted volumes will be automatically mounted to Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS Droplets created on or after April 26, 2018 when attached. On older Droplets, additional configuration is required. ## Remove a Block Storage Volume from a Droplet | Attribute | Details | | ----------- | ------------------------------------------------------------------- | | type | This must be detach | | volume_name | The name of the block storage volume | | droplet_id | Set to the Droplet's ID | | region | Set to the slug representing the region where the volume is located |

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
volume_id	string (uuid)	The ID of the block storage volume. (example: 7724db7c-e098-11e5-b522-000f53304e51)
name	string	The block storage volume's name. (example: example)
page	integer	Which 'page' of paginated results to return. (example: 1)
per_page	integer	Number of items returned per page (example: 2)
region	string	The slug identifier for the region where the resource is available.

SELECT examples

volumes_get

To show information about a block storage volume, send a GET request to /v2/volumes/$VOLUME_ID.

SELECT
id,
name,
created_at,
description,
droplet_ids,
filesystem_label,
filesystem_type,
region,
size_gigabytes,
tags
FROM digitalocean.compute.volumes
WHERE volume_id = '{{ volume_id }}' -- required;

volumes_list

To list all of the block storage volumes available on your account, send a GET request to /v2/volumes.
## Filtering Results
### By Region
The region may be provided as query parameter in order to restrict results to volumes available in a specific region. For example: /v2/volumes?region=nyc1
### By Name
It is also possible to list volumes on your account that match a specified name. To do so, send a GET request with the volume's name as a query parameter to /v2/volumes?name=$VOLUME_NAME.
Note: You can only create one volume per region with the same name.
### By Name and Region
It is also possible to retrieve information about a block storage volume by name. To do so, send a GET request with the volume's name and the region slug for the region it is located in as query parameters to /v2/volumes?name=$VOLUME_NAME&region=nyc1.

SELECT
id,
name,
created_at,
description,
droplet_ids,
filesystem_label,
filesystem_type,
region,
size_gigabytes,
tags
FROM digitalocean.compute.volumes
WHERE name = '{{ name }}'
AND region = '{{ region }}'
AND per_page = '{{ per_page }}'
AND page = '{{ page }}';

INSERT examples

volumes_create

To create a new volume, send a POST request to /v2/volumes. Optionally, a filesystem_type attribute may be provided in order to automatically format the volume's filesystem. Pre-formatted volumes are automatically mounted when attached to Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS Droplets created on or after April 26, 2018. Attaching pre-formatted volumes to Droplets without support for auto-mounting is not recommended.

INSERT INTO digitalocean.compute.volumes (

)
SELECT 

RETURNING
volume
;

Manifest

# Description fields are for documentation purposes
- name: volumes
  props:

DELETE examples

volumes_delete

To delete a block storage volume, destroying all data and removing it from your account, send a DELETE request to /v2/volumes/$VOLUME_ID.
No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

DELETE FROM digitalocean.compute.volumes
WHERE volume_id = '{{ volume_id }}' --required;

volumes_delete_by_name

Block storage volumes may also be deleted by name by sending a DELETE request with the volume's name and the region slug for the region it is located in as query parameters to /v2/volumes?name=$VOLUME_NAME&region=nyc1.
No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

DELETE FROM digitalocean.compute.volumes
WHERE name = '{{ name }}'
AND region = '{{ region }}';

Lifecycle Methods

volume_actions_post

To initiate an action on a block storage volume by Name, send a POST request to
~/v2/volumes/actions. The body should contain the appropriate
attributes for the respective action.

## Attach a Block Storage Volume to a Droplet

| Attribute | Details |
| ----------- | ------------------------------------------------------------------- |
| type | This must be attach |
| volume_name | The name of the block storage volume |
| droplet_id | Set to the Droplet's ID |
| region | Set to the slug representing the region where the volume is located |

Each volume may only be attached to a single Droplet. However, up to fifteen
volumes may be attached to a Droplet at a time. Pre-formatted volumes will be
automatically mounted to Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS
Droplets created on or after April 26, 2018 when attached. On older Droplets,
additional configuration
is required.

## Remove a Block Storage Volume from a Droplet

| Attribute | Details |
| ----------- | ------------------------------------------------------------------- |
| type | This must be detach |
| volume_name | The name of the block storage volume |
| droplet_id | Set to the Droplet's ID |
| region | Set to the slug representing the region where the volume is located |

EXEC digitalocean.compute.volumes.volume_actions_post 
@per_page='{{ per_page }}', 
@page='{{ page }}';