For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

OpenSearch vector database clusters use the same managed OpenSearch engine as DigitalOcean Managed Databases. OpenSearch includes the k-NN, ML Commons, and Hybrid Search plugins, so you can create vector indexes and run similarity queries after the cluster is active.

Create a Database Cluster Using Automation

You can create a vector database cluster using the DigitalOcean CLI (doctl) or the API.

Create a Database Cluster via CLI

To create a vector database cluster using doctl, you need to provide values for the --engine, --region, and --size flags. Use the doctl databases options engines, doctl databases options regions, and doctl databases options slugs commands, respectively, to get a list of available values.

The --wait flag waits until the cluster is online and prints the connection string.

After the cluster is online, add a trusted source so clients can connect to it:

To view the cluster’s connection details, use:

For the full command reference, see doctl databases.

Create a Database Cluster via API

To create a vector database cluster using the API, you need to provide values for the engine, region, and size fields, which specify the database’s engine, its datacenter, and its configuration, including the number of CPUs, amount of RAM, and disk size. Use the /v2/databases/options endpoint to get a list of available values.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"name": "backend", "engine": "pg", "version": "14", "region": "nyc3", "size": "db-s-2vcpu-4gb", "num_nodes": 2, "storage_size_mib": 61440, "tags": ["production"], "do_settings": {"service_cnames": ["db.example.com", "database.myapp.io"]}}' \
  "https://api.digitalocean.com/v2/databases"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    createRequest := &godo.DatabaseCreateRequest{
        Name:       "backend",
        EngineSlug: "pg",
        Version:    "14",
        Region:     "nyc3",
        SizeSlug:   "db-s-2vcpu-4gb",
        NumNodes:   2,
        StorageSizeMiB : 61440,
        DOSettings: &godo.DOSettings{
            ServiceCnames: []string{"db.example.com", "database.myapp.io"},
        },
    }

    cluster, _, err := client.Databases.Create(ctx, createRequest)
}

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

create_req = {
  "name": "backend",
  "engine": "pg",
  "version": "14",
  "region": "nyc3",
  "size": "db-s-2vcpu-4gb",
  "num_nodes": 2,
  "storage_size_mib": 61440,
  "tags": [
    "production"
  ],
  "do_settings": {
    "service_cnames": [
      "db.example.com",
      "database.myapp.io"
    ]
  }
}

create_resp = client.databases.create_cluster(body=create_req)

The response includes the cluster ID, connection details, and a status field. Send a GET request to check the cluster status until it changes from creating to online.

After the cluster is online, add a trusted source so clients can connect to the cluster.

To add a trusted source, use the database firewall endpoint and provide the cluster ID and the trusted source type, such as an IP address, Droplet, Kubernetes cluster, App Platform app, or tag:

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"rules": [{"type": "ip_addr","value": "192.168.1.1"},{"type": "droplet","value": "163973392"},{"type": "k8s","value": "ff2a6c52-5a44-4b63-b99c-0e98e7a63d61"},{"type": "tag","value": "backend"}]}' \
  "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/firewall"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    req := godo.DatabaseUpdateFirewallRulesRequest{
      Rules: []*godo.DatabaseFirewallRule{
        {
         Type:  "ip_addr",
         Value: "192.168.1.1",
         Description: "a development IP address",
       },
        {
         Type:  "droplet",
         Value: "163973392",
       },
        {
         Type:  "k8s",
         Value: "ff2a6c52-5a44-4b63-b99c-0e98e7a63d61",
        },
      },
    }
    _, err := client.Databases.UpdateFirewallRules(ctx, dbID, &req)
}

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "rules": [
    {
      "type": "ip_addr",
      "value": "192.168.1.1",
      "description": "a development IP address",
    },
    {
      "type": "k8s",
      "value": "ff2a6c52-5a44-4b63-b99c-0e98e7a63d61"
    },
    {
      "type": "droplet",
      "value": "163973392"
    },
    {
      "type": "tag",
      "value": "backend"
    }
  ]
}
update_resp = client.databases.update_firewall_rules(database_cluster_uuid="a7a8bas", body=req)

To retrieve the cluster’s connection details, send a GET request:

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    cluster, _, err := client.Databases.Get(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30")
}

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

get_resp = client.databases.get_cluster(database_cluster_uuid="a7a89a")

The response includes connection information such as the host, port, username, and password.

For all supported parameters, see the Databases API reference.

Create a Vector Database Cluster Using the Control Panel

To create an OpenSearch vector database cluster, go to the Vector Databases page and click Create Vector Database. Or click Create at the top of any page and choose Vector Database from the Data Services section of the menu.

Choose a Database Engine

On the Create a Vector Database page, in the Choose a database engine section, select OpenSearch. The database engine can’t be changed after creation.

Choose a Database Configuration

In the Choose a database configuration section, choose a configuration based on your expected vector count, vector dimensions, metadata size, and query load:

• Basic - Shared CPU: CPU processing power is shared among neighboring Droplets on the same host. Best for low-traffic, testing, or development workloads.

• General Purpose - Dedicated CPU: Provides the full processing power of a single vCPU at all times. Use for small-to-medium vector workloads that need predictable CPU performance, such as staging or production workloads with moderate query volume.

• Memory-Optimized - Dedicated CPU: Provides the full processing power of a single vCPU at all times. Use for larger vector datasets, higher-dimensional vectors, or high-query-volume workloads where the HNSW graph needs more memory.

Choose CPU Options

Under CPU options, select an option:

• Regular (Disk: SSD): Use for standard workloads that don’t require NVMe-backed disk performance.
• Premium AMD (Disk: NVMe): Use for workloads that benefit from faster local disk performance and higher network throughput. This option is only available for Basic - Shared CPU configurations.
• Premium Intel (Disk: NVMe): Use for workloads that benefit from faster local disk performance, higher network throughput, and predictable CPU performance.

Changing the CPU option can change the available plan sizes, prices, and datacenter regions.

Select a Plan

Under Select a plan, choose a plan size for the cluster. The plan determines the cluster’s vCPUs, RAM, and minimum storage. Each option shows its combined monthly cost and included resources.

Choose a plan with enough RAM for vector indexes, HNSW graph overhead, JVM heap, operating system cache, and workload growth.

Vector workloads are often memory-bound. OpenSearch stores the HNSW graph in memory outside the JVM heap, so query latency can increase sharply when the graph no longer fits in RAM.

Each vector uses four bytes per dimension. The HNSW graph adds memory for each vector’s graph connections. With up to 16 connections per vector, the graph adds about 128 bytes per vector.

Add a 20-30% safety margin for JVM heap, operating system page cache, metadata, source documents, Lucene segments, and future growth.

If you expect your vector dataset to grow significantly, choose a larger plan before indexing large volumes of data. Resizing later may require reindexing or additional migration work, depending on your index design and workload.

After creation, you can increase your cluster’s compute size (number or size of nodes) at any time.

Choose the Number of Nodes

If you select any of the Dedicated CPU plans, the Number of Nodes selector displays below the Select a plan section. Select 1 Node, 3 Nodes, 6 Nodes, 9 Nodes, or 15 Nodes.

Most Basic - Shared CPU plans support 1 Node or 3 Nodes. The 1 vCPU / 2 GB plans are fixed at 1 Node.

For specific workloads:

• Use a single-node cluster for development or small production workloads that don’t require high availability.
• Use at least three nodes for production workloads that need automated failover. OpenSearch replicates primary shards across nodes to tolerate a node failure without data loss.

Choose a Storage Size

Under Choose a storage size, you can increase storage in 10 GiB increments, up to the maximum in the Storage range (the storage range depends on the selected compute plan). Additional storage costs $0.21 per GiB per month.

Storage must be large enough for source documents, metadata, Lucene segments, OpenSearch system indexes, and future growth.

You can increase or decrease storage at any time, but you cannot reduce it below the amount currently in use, or below what’s required for backups and growth.

Enable Storage Autoscaling

Under Autoscale storage, select Enable Storage Autoscaling to automatically increase storage when disk utilization on any node in the cluster reaches the specified threshold. The threshold is based on the worst-performing node in the cluster, not the average across nodes.

Click Customize to set a custom Threshold and Storage Increment. For performance and stability, autoscaling can increase storage only up to the maximum allowed by your current plan.

Autoscaling takes several minutes depending on the cluster size. It runs without downtime and you do not need to take any action. When autoscaling occurs, the system bills the added capacity as additional storage.

Choose a Datacenter Region

The Choose a datacenter region section shows the datacenters where you currently have the most resources, with the number of resources shown to the right as X resources. Hover over this text to see the specific resources in the datacenter.

For best performance, choose a datacenter close to the resources that connect to the cluster. Resources in the same datacenter share a VPC network, which reduces latency and keeps traffic off the public internet. Cross-region latency can increase vector query time.

Available regions depend on the CPU option and plan you select. For available regions, see Regional Availability.

After creation, you can relocate your cluster to another datacenter.

Finalize and Create

In the Finalize and Create section, enter a unique name for the cluster and select a project to add it to. After creation, you can move the cluster to another project, but its name can’t be changed.

Review the monthly and hourly cost for the cluster. When finished, click Create Database Cluster.

Clusters typically take five minutes or more to provision. You can complete important configuration tasks such as restricting inbound connections while you wait.

Add a Trusted Source Using Automation

You can add trusted sources using the DigitalOcean CLI (doctl) or the API.

Add a Trusted Source via CLI

To add a trusted source using doctl, use doctl databases firewalls append with the database cluster ID and the trusted source type and value.

For list, remove, and other firewall commands, see doctl databases firewalls.

Add a Trusted Source via API

To add a trusted source using the API, send a PUT request to the database firewall endpoint with the cluster ID and the trusted source type and value.

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"rules": [{"type": "ip_addr","value": "192.168.1.1"},{"type": "droplet","value": "163973392"},{"type": "k8s","value": "ff2a6c52-5a44-4b63-b99c-0e98e7a63d61"},{"type": "tag","value": "backend"}]}' \
  "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/firewall"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    req := godo.DatabaseUpdateFirewallRulesRequest{
      Rules: []*godo.DatabaseFirewallRule{
        {
         Type:  "ip_addr",
         Value: "192.168.1.1",
         Description: "a development IP address",
       },
        {
         Type:  "droplet",
         Value: "163973392",
       },
        {
         Type:  "k8s",
         Value: "ff2a6c52-5a44-4b63-b99c-0e98e7a63d61",
        },
      },
    }
    _, err := client.Databases.UpdateFirewallRules(ctx, dbID, &req)
}

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "rules": [
    {
      "type": "ip_addr",
      "value": "192.168.1.1",
      "description": "a development IP address",
    },
    {
      "type": "k8s",
      "value": "ff2a6c52-5a44-4b63-b99c-0e98e7a63d61"
    },
    {
      "type": "droplet",
      "value": "163973392"
    },
    {
      "type": "tag",
      "value": "backend"
    }
  ]
}
update_resp = client.databases.update_firewall_rules(database_cluster_uuid="a7a8bas", body=req)

Make Bulk Updates to Trusted Sources Using Automation

Bulk updates replace the cluster’s full trusted sources list. Use them when you need to add, remove, or replace multiple trusted sources in one operation.

Make Bulk Updates to Trusted Sources via CLI

To make bulk updates using doctl, use doctl databases firewalls replace with the full list of trusted sources you want the cluster to keep.

Make Bulk Updates to Trusted Sources via API

To make bulk updates using the API, send a PUT request to the database firewall endpoint with the full list of trusted sources you want the cluster to keep.

Add a Trusted Source Using the Control Panel

To add trusted sources to restrict database access, go to the Databases page and select the cluster you want to add trusted sources to. Click the Network Access tab.

The Network Access page lists any trusted sources already added. An icon next to each trusted source indicates its resource type (for example, Droplet, App Platform app, tag, or Kubernetes cluster).

Click Add Trusted Sources. In the Add Trusted Sources window, choose one of the following options:

• Enter specific IP addresses or CIDR notations: Enter specific IP addresses or a CIDR range. Or click My current IP address to use the Quick Add option, which adds your machine’s current IP address.

• Quick select Droplets, Kubernetes clusters, Apps, and tags: Use the search to find a resource, or open the dropdown and select a resource from the list. The dropdown groups resources by type, such as Droplets, Applications, tags, and Kubernetes clusters.

When finished, click Add Trusted Sources.

Copy and Store Connection Details

To copy and store your OpenSearch vector database cluster’s connection details for later use, go to the Control Panel, in the left menu, click DATA SERVICES, click Vector Databases, and then select the cluster you want to view connection details for.

Then, in the Overview tab, in the CONNECTION DETAILS section, copy the connection parameters for Public network, username, password, host, and port, then store them securely for later use.

Set Environment Variables for a Trusted Source

To set environment variables for a trusted source, open a terminal session using the trusted source you set up:

export OPENSEARCH_HOST="<your-cluster-host>"
export OPENSEARCH_PORT="<your-cluster-port>"
export OPENSEARCH_USER="<your-cluster-username>"
export OPENSEARCH_PASSWORD="<your-cluster-password>"
export OS="https://$OPENSEARCH_USER:$OPENSEARCH_PASSWORD@$OPENSEARCH_HOST:$OPENSEARCH_PORT"

Replace <your-cluster-host>, <your-cluster-port>, <your-cluster-username>, and <your-cluster-password> with the values you saved from the cluster’s connection details.

If you added your current IP address as a trusted source, open the terminal from the same computer and network using that IP address.

If you added a DigitalOcean resource, such as a Droplet, as a trusted source, open a terminal session from that resource.

Lastly, verify the connection:

curl -sS "$OS/" | jq '.version.number'

If successful, the command returns the OpenSearch version number.

After you store your connection details securely and set your environment variables, you can start indexing and running queries:

• Create a k-NN Index
• Run Hybrid Searches
• Register a Remote Embedding Model