How to Manage Databases in App Platform

Validated on 14 Jan 2022 • Last edited on 23 May 2024 database | doctl | service

App Platform is a Platform-as-a-Service (PaaS) offering that allows developers to publish code directly to DigitalOcean servers without worrying about the underlying infrastructure.

You can add a dev database or an existing DigitalOcean database to your app at any time. Dev databases only support PostgreSQL at this time.

Dev databases are located in the same region as your app and cannot be migrated to another region. If you migrate your app to a different region, the app won’t be able to access the associated dev database anymore. If you need to migrate your app and dev database, we recommend either backing up the contents of the database and restoring it after the app’s migration, or using a DigitalOcean Managed Database instead. You can migrate managed databases independently of apps to different regions as needed.

Create a Database

You can create a database for your app using the DigitalOcean Control Panel or by defining the database in your app’s spec file and then submitting the new spec using either the API, CLI, DigitalOcean Control Panel, or the app’s source repo.

Add a Database to an App Using Automation

You can add a database to an app using the CLI’s app update command or the API’s app update endpoint. To add a database, update the app’s spec with the database’s specifications and submit the spec using the following command or endpoint.

How to add a database to an app using the DigitalOcean CLI

To add a database to an app via the command-line, follow these steps:

  1. Install doctl, the DigitalOcean command-line tool.

  2. Create a personal access token, and save it for use with doctl.

  3. Use the token to grant doctl access to your DigitalOcean account.

                  doctl auth init

  4. Finally, add a database to an app with doctl apps update. The basic usage looks like this, but you'll want to read the usage docs for more details:

                  doctl apps update <app id> [flags]

    The following example updates an app with the ID f81d4fae-7dec-11d0-a765-00a0c91e6bf6 using an app spec located in a directory called /src/your-app.yaml. Additionally, the command returns the updated app’s ID, ingress information, and creation date

                       doctl apps update f81d4fae-7dec-11d0-a765-00a0c91e6bf6 --spec src/your-app.yaml --format ID,DefaultIngress,Created
How to add a database to an app using the DigitalOcean API

To add a database to an app using the DigitalOcean API, follow these steps:

  1. Create a personal access token, and save it for use with the API.

  2. Send a PUT request to https://api.digitalocean.com/v2/apps/{id}

    cURL

    To add a database to an app with cURL, call:

    
                curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{id}"

    Python

    
                import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
req = {
"spec": {
    "name": "web-app-01",
    "region": "nyc",
    "domains": [
        {
            "domain": "app.example.com",
            "type": "DEFAULT",
            "wildcard": True,
            "zone": "example.com",
            "minimum_tls_version": "1.3",
        }
    ],
    "services": [],
    "static_sites": [
        {
            "cors": {
                "allow_origins": [
                    {"exact": "https://www.example.com"},
                    {"regex": "^.*example.com"},
                ],
                "allow_methods": [
                    "GET",
                    "OPTIONS",
                    "POST",
                    "PUT",
                    "PATCH",
                    "DELETE",
                ],
                "allow_headers": ["Content-Type", "X-Custom-Header"],
                "expose_headers": ["Content-Encoding", "X-Custom-Header"],
                "max_age": "5h30m",
                "allow_credentials": False,
            },
            "routes": [{"path": "/api", "preserve_path_prefix": True}],
        }
    ],
    "jobs": [
        {
            "name": "api",
            "gitlab": {
                "branch": "main",
                "deploy_on_push": True,
                "repo": "digitalocean/sample-golang",
            },
            "image": {
                "registry": "registry.hub.docker.com",
                "registry_type": "DOCR",
                "repository": "origin/master",
                "tag": "latest",
            },
            "dockerfile_path": "path/to/Dockerfile",
            "build_command": "npm run build",
            "run_command": "bin/api",
            "source_dir": "path/to/dir",
            "envs": [
                {
                    "key": "BASE_URL",
                    "scope": "BUILD_TIME",
                    "type": "GENERAL",
                    "value": "http://example.com",
                }
            ],
            "environment_slug": "node-js",
            "log_destinations": {
                "name": "my_log_destination",
                "papertrail": {
                    "endpoint": "https://mypapertrailendpoint.com"
                },
                "datadog": {
                    "endpoint": "https://mydatadogendpoint.com",
                    "api_key": "abcdefghijklmnopqrstuvwxyz0123456789",
                },
                "logtail": {
                    "token": "abcdefghijklmnopqrstuvwxyz0123456789"
                },
            },
            "instance_count": 2,
            "instance_size_slug": "apps-s-1vcpu-0.5gb",
            "kind": "PRE_DEPLOY",
        }
    ],
    "workers": [
        {
            "name": "api",
            "gitlab": {
                "branch": "main",
                "deploy_on_push": True,
                "repo": "digitalocean/sample-golang",
            },
            "image": {
                "registry": "registry.hub.docker.com",
                "registry_type": "DOCR",
                "repository": "origin/master",
                "tag": "latest",
            },
            "dockerfile_path": "path/to/Dockerfile",
            "build_command": "npm run build",
            "run_command": "bin/api",
            "source_dir": "path/to/dir",
            "envs": [
                {
                    "key": "BASE_URL",
                    "scope": "BUILD_TIME",
                    "type": "GENERAL",
                    "value": "http://example.com",
                }
            ],
            "environment_slug": "node-js",
            "log_destinations": {
                "name": "my_log_destination",
                "papertrail": {
                    "endpoint": "https://mypapertrailendpoint.com"
                },
                "datadog": {
                    "endpoint": "https://mydatadogendpoint.com",
                    "api_key": "abcdefghijklmnopqrstuvwxyz0123456789",
                },
                "logtail": {
                    "token": "abcdefghijklmnopqrstuvwxyz0123456789"
                },
            },
            "instance_count": 2,
            "instance_size_slug": "apps-s-1vcpu-0.5gb",
        }
    ],
    "functions": [
        {
            "cors": {
                "allow_origins": [
                    {"exact": "https://www.example.com"},
                    {"regex": "^.*example.com"},
                ],
                "allow_methods": [
                    "GET",
                    "OPTIONS",
                    "POST",
                    "PUT",
                    "PATCH",
                    "DELETE",
                ],
                "allow_headers": ["Content-Type", "X-Custom-Header"],
                "expose_headers": ["Content-Encoding", "X-Custom-Header"],
                "max_age": "5h30m",
                "allow_credentials": False,
            },
            "routes": [{"path": "/api", "preserve_path_prefix": True}],
            "name": "api",
            "source_dir": "path/to/dir",
            "alerts": [
                {
                    "rule": "CPU_UTILIZATION",
                    "disabled": False,
                    "operator": "GREATER_THAN",
                    "value": 2.32,
                    "window": "FIVE_MINUTES",
                }
            ],
            "envs": [
                {
                    "key": "BASE_URL",
                    "scope": "BUILD_TIME",
                    "type": "GENERAL",
                    "value": "http://example.com",
                }
            ],
            "gitlab": {
                "branch": "main",
                "deploy_on_push": True,
                "repo": "digitalocean/sample-golang",
            },
            "log_destinations": {
                "name": "my_log_destination",
                "papertrail": {
                    "endpoint": "https://mypapertrailendpoint.com"
                },
                "datadog": {
                    "endpoint": "https://mydatadogendpoint.com",
                    "api_key": "abcdefghijklmnopqrstuvwxyz0123456789",
                },
                "logtail": {
                    "token": "abcdefghijklmnopqrstuvwxyz0123456789"
                },
            },
        }
    ],
    "databases": [
        {
            "cluster_name": "cluster_name",
            "db_name": "my_db",
            "db_user": "superuser",
            "engine": "PG",
            "name": "prod-db",
            "production": True,
            "version": "12",
        }
    ],
}
}
update_resp = client.apps.update(id="bb245ba", body=req)

Add a Database to an App Using the Control Panel

In the Apps section of the DigitalOcean Control Panel, click your app, then click the Create dropdown. Add a database resource by choosing the Create/Attach Database option.

Component screen

Select your database configuration, choosing from the available engines and plans. You can add a dev database or an existing managed database from your DigitalOcean account.

Database creation screen

All DigitalOcean database clusters support apps as trusted sources. Your app is added as a trusted source to the dev database. This creates a secure connection to the database and it accepts traffic only from the app. Similarly, if your existing managed database has trusted sources enabled, the app is automatically added as a trusted source. If trusted source is disabled for your managed database, select the Add app as a trusted source option to add the app as a trusted source.

Managed DB Enable Trusted

Alternatively, you can specify an app in the Trusted sources section in the Settings tab of the database in the cloud control panel. This starts an app redeployment that enables a connection restricted from that app to the database.

Note
Enabling an app as a trusted source blocks any other connections. You need to add other sources explicitly to the trusted sources list as described in the Managed Databases documentation.

When you are ready to proceed, click Create and Attach to confirm your choices.

Add a Database to an App Using the Control Panel

You can also add a database by specifying the database details directly in the app’s spec file and submitting the updated spec via the control panel or uploading it to your app’s source repo.

To add a database using the app’s spec, add the following object to root of the spec and update the values as necessary:

    
        
            
databases:
- engine: PG
  name: db-example
  version: "16"

Using the spec, you can specify the database’s name and version. You cannot specify the version the control panel. The currently available PostgreSQL versions are 14 and 16.

Connect to a Database

Go to https://cloud.digitalocean.com/apps, click on your app, and click on the Settings tab.

Click on your database to view its details. The connection information for your database is provided in the Connection Details section.

Database detail screen

The full connection string for your database is also be available as a runtime environment variable named DATABASE_URL which you can use in your application code. You should see this it in the details for your service resource, set to a value such as:

postgres://${db.USERNAME}:${db.PASSWORD}@${db.HOSTNAME}:${db.PORT}/${db.DATABASE}

DATABASE_URL wraps several environment variables that you can also access individually, such as db.USERNAME, db.PASSWORD, and so on.

Upgrade Dev Database to Managed Database

Go to https://cloud.digitalocean.com/apps, click on your app, and click on the Settings tab.

Click the dev database you would like to upgrade to a managed database and click the Upgrade to a Managed Database button. You can choose the size of the machines that run your database with the Node Plan drop-down, and add standby nodes that stay synchronized and provide failover during downtime with the Standby Nodes drop-down.

Click Upgrade Database to complete the process.

Disable Trusted Sources

Go to https://cloud.digitalocean.com/apps, click on your app, and click on the Settings tab.

Click on your database to view its details. The trusted sources information for your database is provided in the Trusted Sources section. To disable the setting, click Edit, uncheck the Add app as a trusted source checkbox, and click Save.

Trusted sources setting

Destroy a Database

Go to https://cloud.digitalocean.com/apps, click on your app, and click on the Settings tab.

Click on your database. The details screen for your database has a Destroy Database button on the bottom that will destroy your database after you confirm the action.

Control Panel Blog Pricing Careers Terms Privacy Status API Docs Tutorials Support