Connecting a Node.js Application to Scalingo PostgreSQL: A Task Guide

Desired Outcome

You have a Node.js application that needs a managed PostgreSQL database on Scalingo, but you cannot store credentials in source control or hardcode them into the container image. The practical goal is to provision the database through the platform, let Scalingo inject the connection details at runtime, and confirm the application can reach the database before you consider the deployment finished.

The useful takeaway: use the Scalingo CLI to add the PostgreSQL add-on, read the injected connection URL from the environment inside your Node.js process, push your code, and verify the handshake through application logs and a health endpoint.

Prerequisites

• A Scalingo account and the Scalingo CLI installed on your workstation. Authenticate by running scalingo login in your terminal.
• A Node.js project with a package.json file and a start script or entry file such as server.js.
• A local Git repository with a remote named scalingo pointing to your Scalingo application.
• Rough knowledge of your expected concurrent connection count so you can select an appropriate PostgreSQL plan.

Provision the PostgreSQL Add-On

From your terminal, run the following in your project directory or append --app <app-name> to target a specific application:

scalingo addons-add postgres --plan <plan-name>

Replace <plan-name> with the identifier for the plan you select in the Scalingo dashboard. When the add-on is created, Scalingo injects environment variables into your application containers. The primary variable is typically POSTGRES_URL, but the platform may also expose DATABASE_URL or other aliases depending on the add-on generation. Always confirm the exact variable names in the dashboard after provisioning.

Configure the Node.js Application

Read the connection string from the environment rather than embedding it in code. If you use the pg client, a minimal pool configuration looks like this:

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

const pool = new Pool({
  connectionString: process.env.POSTGRES_URL,
  max: 10
});

If your ORM or driver expects discrete host, port, and credential values, parse the URL or read the individual variables shown in the dashboard. Set the pool max value conservatively: every PostgreSQL plan enforces a ceiling on simultaneous connections, and exceeding it produces too many clients errors.

Add a Procfile and Deploy

Scalingo needs a Procfile to know which command starts your web process. Create one at the repository root:

web: node server.js

Commit the Procfile and your code changes. Then push to Scalingo:

git push scalingo <branch>

Replace <branch> with the branch configured for your application, commonly master or main. Scalingo builds a new slug, injects the add-on environment variables, and runs the start command defined in the Procfile.

Verify the Connection

After the push completes, inspect the runtime logs:

scalingo logs

Look for a message from your PostgreSQL client indicating a successful connection; the exact wording depends on the library you use. Next, exercise a health endpoint that performs a lightweight query such as SELECT 1. A request to GET /health should return HTTP 200 with a payload that includes a database-check flag.

To cross-check the credentials, open the Scalingo dashboard, go to Add-ons → PostgreSQL → View credentials, and compare the displayed URL with the value your application reports in its logs or process environment.

Recovery Options

If the deployment fails or the database connection breaks after a push, you have two recovery paths.

1. Roll back the release. List recent releases with scalingo releases, then run scalingo rollback <release-id>. Replace <release-id> with the identifier of the last known-good release. This immediately restores the previous container state without changing your Git history.
2. Revert the code change. If the fault is in your application code, revert the offending commit locally with git revert <commit-sha> and push again with git push scalingo <branch>. This corrects the source before the next deployment.

Use rollback for rapid recovery when the platform is serving traffic; use a Git revert when you need to fix the repository so future builds are correct.

Limitations and Practical Checks

• Connection ceilings. Plan limits are hard boundaries. If your pool size plus administrative connections exceed the plan maximum, PostgreSQL raises too many clients. Keep the application pool small and reuse connections.
• Variable naming drift. Environment variable names can differ between add-on versions or plans. Rely on the dashboard to confirm the exact name instead of assuming POSTGRES_URL is always present.
• Branch mismatches. Pushing to a branch that Scalingo is not configured to deploy causes the push to be rejected. Verify the expected branch name in your application settings.

A practical final check is to review scalingo logs after a successful deployment and confirm your database client initialized without errors, then call the health endpoint from an external client to ensure the response includes a positive database status.