dFlow
Databases

Database troubleshooting

Fix common database deploy, connection, Expose, backup, and reference-variable issues in dFlow Applications.

Use this page when something goes wrong creating, deploying, connecting to, exposing, or backing up a managed database service in dFlow. Work through the section that matches what you see in the UI or logs.

Before you start: confirm you are in Applications → correct application → correct environment → correct database service.

General orientation: Databases overview. Connection concepts: Database credentials and connections.

Deploy never finishes or shows failed

Symptoms: Deploy spins for a long time, ends in failed, or credentials never appear on Overview.

What to check:

  1. Open Deployments on the database service and read the latest log. Copy error lines for support if needed.
  2. Open Logs for live server output during a retry.
  3. Confirm the environment’s compute (server or managed worker) is healthy and has enough disk and memory for the engine you chose.
  4. If you recently changed networking or firewall rules on the worker, confirm SSH and Dokku-related access still work for other services on the same node (self-hosted).

If the worker is out of disk or RAM: free space or resize before redeploying; the create form’s resource check is advisory but real failures often trace to resource exhaustion.

Overview shows no internal credentials

Symptoms: Service exists but Internal credentials are empty or still loading.

Cause: Provisioning has not completed successfully yet.

What to do:

  1. Click Deploy if it is still available and wait for success.
  2. If Deploy is hidden and credentials are still missing, open Deployments for the last success record; if there is none, treat the service as never provisioned—contact support or recreate the service after checking worker health.

App cannot connect: connection refused or timeout

Symptoms: Application logs show ECONNREFUSED, timeout, or ORM errors connecting to the database.

Checklist:

CheckAction
Same environment?App and database must live in the same environment for internal URLs.
Correct URL?Compare app env to Overview; no accidental spaces or quotes.
Using internal host from your laptop?Internal hostnames resolve inside the environment, not on your Mac or PC. Use Expose or a tunnel for local tools.
Database stopped?On Overview, Restart if you intentionally stopped it.
External database?See External database notes—verify security groups and TLS.

Reference variable not resolving or wrong value

Symptoms: App sees literal {{ ... }} text, empty string, or old credentials.

What to check:

  1. Syntax: Token must look like {{ service-name.POSTGRES_URI }} with the real service name and correct engine prefix (POSTGRES, MYSQL, MONGO, MARIADB, REDIS, CLICKHOUSE). Typos in the name break resolution.
  2. Deploy order: Database should reach successful deploy before you rely on its URI in production traffic.
  3. Redeploy app: Environment variable changes often need an app redeploy or restart to apply.
  4. Public fields: …_PUBLIC_URI only works after Expose; it stays disabled in the picker until then.

Details: Database credentials and connections.

Expose stuck on “Exposing” or public credentials missing

Symptoms: Expose never completes, or public fields stay empty.

What to do:

  1. Wait for the queued job; large stacks can take minutes.
  2. Read Deployments and Logs for errors (port conflicts, gateway issues).
  3. Unexpose and Expose again after fixing the underlying error only if support or your runbook says it is safe.

Stop is disabled or UI asks to Unexpose first

Expected behavior: You cannot Stop a database that is still exposed. Click Unexpose, wait for completion, then Stop.

Backup stuck in “in-progress” or restore failed

Symptoms: Backup row stays in-progress, or Restore errors.

What to check:

  1. Read Backups and restore for internal, external, and scheduled behavior.
  2. Confirm the service is linked to valid self-managed compute; some legacy project types block backup creation.
  3. For external backups, confirm Integrations → Backup Storage is verified and Save destination is set on the Backups tab.
  4. Rows in-progress longer than about two hours are marked failed automatically; if yours is newer, check server logs and backup storage credentials.

Remember: internal backups alone are not off-site disaster recovery; use external storage for copies off the server.

Still stuck?

Collect:

  • Application and environment name.
  • Database service name and engine.
  • Time (with timezone) of the failure.
  • Screenshots or text from the failing Deployment log.

Then use your workspace’s support channel or internal platform team.

External database notes

When your primary database lives outside dFlow (managed cloud, on-prem), how to connect apps with environment variables and networking.

Templates overview

What templates are, the three catalogue tabs, and how browse, deploy, create, and publish fit together in dFlow.

On this page

Database troubleshootingDeploy never finishes or shows failedOverview shows no internal credentialsApp cannot connect: connection refused or timeoutReference variable not resolving or wrong valueExpose stuck on “Exposing” or public credentials missingStop is disabled or UI asks to Unexpose firstBackup stuck in “in-progress” or restore failedStill stuck?Related