managed-db-services

Managed Database Services Skill

Configure DigitalOcean Managed MySQL, MongoDB, Valkey (Redis), Kafka, and OpenSearch for App Platform applications.

Quick Decision

Which database engine?
├── PostgreSQL    → Use the postgres skill instead
├── MySQL         → See reference/mysql.md
├── MongoDB       → See reference/mongodb.md
├── Valkey/Redis  → See reference/valkey.md
├── Kafka         → See reference/kafka.md (⚠️ trusted sources limitations)
└── OpenSearch    → See reference/opensearch.md

Tip: For complex multi-step deployments, use the planner skill. For an overview of all skills, see root SKILL.md.

---

Critical Constraints

Constraint	Impact
Dev databases	PostgreSQL only — MySQL/MongoDB/Kafka/OpenSearch require production: true
Build-time DB access	❌ Trusted sources block build phase — use PRE_DEPLOY job for migrations
Kafka trusted sources	IP-based only (ip_addr:); app-based (app:) NOT supported
OpenSearch logging	❌ NOT supported with trusted sources enabled
MongoDB db_name	Cannot contain capital letters in app spec

---

Trusted Sources Quick Reference

Network Mode	Rule Type	Supported Engines
Public	app:$APP_ID	MySQL, MongoDB, Valkey, OpenSearch
Public	app:$APP_ID	❌ Kafka (not supported)
VPC	ip_addr:<vpc-cidr>	All engines
VPC	app:$APP_ID	❌ None (app rules whitelist public IP only)

VPC deployments: Use VPC CIDR (ip_addr:10.126.0.0/20) — simpler than per-app IPs.

See networking skill - Trusted Sources for complete configuration.

---

Bindable Variables (All Engines)

databases:
  - name: db                      # Component name (used in ${db.VAR_NAME})
    engine: <ENGINE>              # MYSQL, MONGODB, REDIS, KAFKA, OPENSEARCH
    production: true              # REQUIRED for bindable variables
    cluster_name: my-cluster      # Must match existing cluster name
    db_name: myappdb              # Database within cluster (where applicable)
    db_user: myappuser            # User created via doctl

Variable	Description
${db.DATABASE_URL}	Full connection string (PUBLIC hostname only!)
${db.HOSTNAME}	Database host (PUBLIC hostname only!)
${db.PORT}	Database port
${db.USERNAME}	Database user
${db.PASSWORD}	Database password (auto-populated)
${db.DATABASE}	Database name
${db.CA_CERT}	CA certificate for TLS

VPC Note: Bindable variables return PUBLIC hostnames even with VPC enabled. For private endpoints, add separate *_PRIVATE_* environment variables with hardcoded private hostnames.

---

Engine Quick Reference

Engine	App Spec	Port	Protocol	Key Notes
MySQL	MYSQL	25060	mysql://...?ssl-mode=REQUIRED	Full guide
MongoDB	MONGODB	27017	mongodb+srv://...?tls=true&authSource=admin	Full guide
Valkey	REDIS	25061	rediss:// (with SSL)	Full guide
Kafka	KAFKA	9093	SASL/SCRAM-SHA-256	Full guide
OpenSearch	OPENSEARCH	25060	https:// with basic auth	Full guide

---

Quick Start: MySQL

# 1. Create cluster + user
doctl databases create my-mysql --engine mysql --region nyc3 --size db-s-1vcpu-2gb --version 8
CLUSTER_ID=$(doctl databases list --format ID,Name --no-header | grep my-mysql | awk '{print $1}')
doctl databases db create $CLUSTER_ID myappdb
doctl databases user create $CLUSTER_ID myappuser

# 2. Add to trusted sources
APP_ID=$(doctl apps list --format ID,Spec.Name --no-header | grep my-app | awk '{print $1}')
doctl databases firewalls append $CLUSTER_ID --rule app:$APP_ID

# 3. Reference in app spec

databases:
  - name: db
    engine: MYSQL
    production: true
    cluster_name: my-mysql
    db_name: myappdb
    db_user: myappuser

services:
  - name: api
    envs:
      - key: DATABASE_URL
        scope: RUN_TIME
        value: ${db.DATABASE_URL}

Full guide: See mysql.md

---

Quick Start: MongoDB

doctl databases create my-mongo --engine mongodb --region nyc3 --size db-s-1vcpu-2gb --version 7
CLUSTER_ID=$(doctl databases list --format ID,Name --no-header | grep my-mongo | awk '{print $1}')
doctl databases user create $CLUSTER_ID myappuser
doctl databases firewalls append $CLUSTER_ID --rule app:$APP_ID

databases:
  - name: db
    engine: MONGODB
    production: true
    cluster_name: my-mongo
    db_user: myappuser

services:
  - name: api
    envs:
      - key: MONGODB_URI
        scope: RUN_TIME
        value: ${db.DATABASE_URL}

Full guide: See mongodb.md

---

Quick Start: Valkey

doctl databases create my-valkey --engine redis --region nyc3 --size db-s-1vcpu-2gb --version 7
CLUSTER_ID=$(doctl databases list --format ID,Name --no-header | grep my-valkey | awk '{print $1}')
doctl databases firewalls append $CLUSTER_ID --rule app:$APP_ID

databases:
  - name: cache
    engine: REDIS
    production: true
    cluster_name: my-valkey

services:
  - name: api
    envs:
      - key: REDIS_URL
        scope: RUN_TIME
        value: ${cache.DATABASE_URL}

Full guide: See valkey.md

---

Quick Start: Kafka

Warning: Kafka does NOT support app:$APP_ID trusted source rules. Use VPC + IP-based rules or disable trusted sources.

doctl databases create my-kafka --engine kafka --region nyc3 --size db-s-2vcpu-4gb --version 3.7
CLUSTER_ID=$(doctl databases list --format ID,Name --no-header | grep my-kafka | awk '{print $1}')
doctl databases topics create $CLUSTER_ID my-topic --partition-count 3 --replication-factor 2

databases:
  - name: kafka
    engine: KAFKA
    production: true
    cluster_name: my-kafka

services:
  - name: api
    envs:
      - key: KAFKA_BROKER
        scope: RUN_TIME
        value: ${kafka.HOSTNAME}:${kafka.PORT}
      - key: KAFKA_USERNAME
        scope: RUN_TIME
        value: ${kafka.USERNAME}
      - key: KAFKA_PASSWORD
        scope: RUN_TIME
        value: ${kafka.PASSWORD}
      - key: KAFKA_CA_CERT
        scope: RUN_TIME
        value: ${kafka.CA_CERT}

Full guide: See kafka.md

---

Quick Start: OpenSearch

Warning: Logging to OpenSearch requires trusted sources to be disabled.

doctl databases create my-opensearch --engine opensearch --region nyc3 --size db-s-2vcpu-4gb --version 2
CLUSTER_ID=$(doctl databases list --format ID,Name --no-header | grep my-opensearch | awk '{print $1}')
doctl databases user create $CLUSTER_ID myappuser
doctl databases firewalls append $CLUSTER_ID --rule app:$APP_ID

databases:
  - name: search
    engine: OPENSEARCH
    production: true
    cluster_name: my-opensearch
    db_user: myappuser

services:
  - name: api
    envs:
      - key: OPENSEARCH_URL
        scope: RUN_TIME
        value: https://${search.USERNAME}:${search.PASSWORD}@${search.HOSTNAME}:${search.PORT}

Full guide: See opensearch.md

---

Common doctl Commands

# List all database clusters
doctl databases list

# Get cluster details
doctl databases get <cluster-id>

# Create user (DO manages password)
doctl databases user create <cluster-id> <username>

# List users
doctl databases user list <cluster-id>

# Create database within cluster
doctl databases db create <cluster-id> <db-name>

# Get connection details
doctl databases connection <cluster-id>

# Trusted sources (firewall)
doctl databases firewalls append <cluster-id> --rule app:<app-id>
doctl databases firewalls list <cluster-id>

---

Quick Troubleshooting

Error	Cause	Fix
"Connection refused"	App not in trusted sources	doctl databases firewalls append <cluster-id> --rule app:<app-id>
"Access denied"	User permissions not set	Grant permissions via SQL or recreate user
Bindable vars empty	Missing production: true	Add production: true to database block
SSL required	Connection string missing SSL	Add ?ssl-mode=REQUIRED (MySQL), ?tls=true (MongoDB), use rediss:// (Valkey)
Kafka connection fails	Using app: rule	Kafka only supports ip_addr: rules — use VPC or disable TS

---

Reference Files

• mysql.md — Connection pools, user privileges, password encryption
• mongodb.md — User roles, authSource configuration
• valkey.md — Eviction policies, SSL protocol
• kafka.md — SASL auth, SSL cert handling, Schema Registry
• opensearch.md — ACLs, logging limitations

---

When to Use Postgres Skill Instead

Use the postgres skill for:

• Schema isolation (multi-tenant)
• Complex permission management
• Multiple apps sharing one cluster
• Connection pool configuration

This skill is for straightforward single-database setups with MySQL, MongoDB, Valkey, Kafka, or OpenSearch.

---

Integration with Other Skills

Skill	Integration
designer	Generates databases: block in app spec
deployment	No additional secrets needed — bindable vars handle credentials
networking	VPC + trusted sources configuration
troubleshooting	Debug container for connectivity testing

---

Documentation Links

• Managed Databases Overview
• MySQL
• MongoDB
• Redis/Valkey
• Kafka
• OpenSearch
• doctl databases reference