Managing PostgreSQL Connections on Scalingo

The "Connection Refused" Deployment Gap

You've attached the managed PostgreSQL add-on to your Scalingo app and pushed your code, but the logs show connection errors. This usually happens because the application is looking for a local database or a hardcoded config file, rather than the environment variables Scalingo injects during the deployment process.

Automating Database Access via Environment Injection

Scalingo simplifies database provisioning by automatically injecting credentials into your application container at deploy time. Instead of managing a config/database.yml or .env file manually, the platform provides two primary variables: DATABASE_URL and PGHOST.

These variables contain the endpoint, port, database name, and credentials required to reach the managed instance. Because this happens at the platform level, your code remains portable; you simply reference the environment variable regardless of whether you are in staging or production.

Scaling and Connection Management

As your traffic grows, you can scale your database resources using the dashboard or the CLI via scalingo addons:upgrade. While read workloads typically remain uninterrupted during plan upgrades, write workloads or major PostgreSQL engine version bumps may require planned outages or application restarts.

A critical architectural detail is that Scalingo does not provide a built-in connection proxy. Connection pooling—the process of keeping a cache of database connections to avoid the overhead of creating a new one for every request—must be handled by your application. Depending on your runtime (Node.js, Python, Go, etc.), you will need to configure your ORM or a tool like PgBouncer to manage throughput effectively.

Worked Example: Verifying and Connecting in Node.js

To ensure your app is correctly receiving credentials and handling the connection, follow these verification steps.

# Run on local terminal with authenticated Scalingo CLI
# Permissions: App owner or collaborator
scalingo apps:info <app_name>

Check the ADDON_SERVICES field in the output to confirm the PostgreSQL add-on is attached.

# SSH into the container to verify runtime environment
ssh <app_name>.scalingo.io "printenv | grep DATABASE"

Expected result: DATABASE_URL and PGHOST should be printed with their current values. If empty, the add-on is not correctly linked to the app.

Once verified, implement the connection in your code using a pooling library to avoid exhausting database connections:

const { Pool } = require('pg');

// Use the injected DATABASE_URL and enable SSL for managed instances
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  ssl: { rejectUnauthorized: false }
});

Risk: Avoid logging process.env.DATABASE_URL to your application logs, as this exposes your database credentials in plain text.

Trade-offs and Security Limitations

While environment variable injection is convenient, it has a security trade-off: credentials are visible to any process that can read the environment or view container logs. For high-security workloads, use Scalingo's encrypted secret store to manage sensitive data rather than relying solely on standard environment variables.

Verification Checklist

• Confirm ADDON_SERVICES lists postgresql via scalingo apps:info.
• Verify DATABASE_URL is present via SSH printenv.
• Ensure your database driver is configured for SSL, as managed instances typically require it.
• Implement application-level connection pooling to prevent "too many clients" errors during traffic spikes.