Connecting to Your Database

Table of Contents

1. The database detail page
2. Two ways to connect
3. Connecting with psql
4. Connecting from Node.js
5. Beginner Pitfalls

1. The database detail page

Open Cloud → Database and click your instance. The page is laid out in three columns:

Left — the instance itself

• Database Name — the name you chose.
• Status — a green Running bar when healthy.
• Database Engine — DB Language (e.g. PostgreSQL) and Version.
• Resource — CPU, Memory, and Storage, as set by your plan.

Middle — connection details

• Cluster — how many clusters you subscribed to.
• RunApp Connection — Host Name, Port, and a Connection String.
• External Connection — a Command Line, a Port, and an Admin Link.

Right — IP Whitelist, with an Add + button (next chapter).

Every connection value has a copy icon, so you rarely type them. Below the columns, a Your Plan card shows the plan name, Start From, Payment Due Date, and Pricing, with a NEW PLAN button to change plans. The top-right EDIT button opens the same form you used at creation (whitelist, backup, and so on).

2. Two ways to connect

The page gives you two sets of details on purpose:

The mapping that matters: the app you deploy to Run App uses the RunApp Connection; you, working from your own machine, use the External Connection. If a connection fails, the first thing to check is that you copied from the right half.

The connection string looks like this, with your real password replacing <password>:

postgresql://root:<password>@<host>:5432/<database>

The Admin Link opens a DbGate dashboard for the instance — a web-based database GUI. Use it to browse tables and run queries from a browser, or to connect from an outside GUI client, without typing the command line.

3. Connecting with psql

Click the copy icon on Command Line. For PostgreSQL it looks like:

psql -U root -h <external-host> -p 6646

Paste it into a terminal, enter your password when prompted, and you should land at a postgres=> prompt. Try:

SELECT version();
CREATE TABLE hello (id serial PRIMARY KEY, msg text);
INSERT INTO hello (msg) VALUES ('hi from Cloud+');
SELECT * FROM hello;

If it hangs or is refused, your IP isn't allowed through the whitelist — see the next chapter.

4. Connecting from Node.js

Install the standard PostgreSQL client for Node:

npm install pg

Keep credentials in environment variables, never in source code:

// db-hello.js
const { Client } = require("pg");

const client = new Client({
  host: process.env.DB_HOST,
  port: Number(process.env.DB_PORT),
  user: process.env.DB_USER || "root",
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME || "postgres",
});

async function main() {
  await client.connect();
  const { rows } = await client.query("SELECT now() AS server_time");
  console.log(rows[0].server_time);
  await client.end();
}

main().catch((err) => {
  console.error("Connection failed:", err.message);
  process.exit(1);
});

Run it from your laptop with the External Connection values:

DB_HOST=<external-host> DB_PORT=6646 DB_PASSWORD='<password>' node db-hello.js

When you later deploy this app to Run App, set the same four variables as stack environment variables (see Getting Started with Run App) but with the RunApp Connection host and port. The code doesn't change — only the values do.

5. Beginner Pitfalls

• Using the RunApp host from your laptop (or the external one from a stack). Match the connection half to where the code runs.
• Pasting the connection string with <password> still in it. Replace the placeholder with your real password.
• Hardcoding the password in a file you commit. Use environment variables, and keep .env out of git.
• Assuming a timeout means the wrong password. A wrong password gets an error quickly; a silent hang usually means the whitelist is blocking you.