Connecting to Your Database

Once your database is running, you can retrieve connection details from the database detail page.

Viewing Connection Information

1. Navigate to Databases in the sidebar
2. Click on your database name
3. The connection details are displayed in the Connection Information card

Connection Details

Each database provides the following connection information:

Field	Description
Connection String	Full URI for connecting to your database
Host	Database hostname
Port	Database port number
Username	Database user
Password	Database password
Database	Database name

Use the copy button next to each field to copy values to your clipboard.

Connection String Formats

PostgreSQL

postgresql://username:password@host:5432/database

Example:

postgresql://postgres:abc123@mydb.db.hostless.cloud:5432/mydb

MySQL

mysql://username:password@host:3306/database

Example:

mysql://mysql:abc123@mydb.db.hostless.cloud:3306/mydb

MongoDB

mongodb://username:password@host:27017/database

Example:

mongodb://root:abc123@mydb.db.hostless.cloud:27017/mydb

Redis

Redis uses the default user with a password. With TLS the format is:

rediss://default:password@host:6379

Example:

rediss://default:abc123@myredis.db.hostless.cloud:6379

TLS server name (ioredis / Redis Insight)
TLS requires the server name to match the host. Use the Host from the connection string as the TLS server name.

• ioredis (Node.js) – When using the URL directly, ioredis sets the host as the TLS server name. If you build options manually (e.g. from separate env vars), set tls.servername to the host:

const Redis = require('ioredis');

// Option 1: URL only (host is used as TLS server name automatically)
const redis = new Redis(process.env.REDIS_URL);

// Option 2: Explicit TLS server name (e.g. for custom options or when URL isn't used)
const redis = new Redis({
  host: process.env.REDIS_HOST,   // same as host in your connection string
  port: 6379,
  username: 'default',
  password: process.env.REDIS_PASSWORD,
  tls: {
    servername: process.env.REDIS_HOST,   // required for TLS; use the same host
    rejectUnauthorized: true,
  },
});

• Redis Insight / other GUIs – Use Host = host from the connection string (e.g. myredis.db.hostless.cloud), Port = 6379, Username = default, Password from the connection string, enable TLS, and set TLS Server Name (or equivalent) to the same host. Without the correct server name, you may see protocol errors (e.g. got "H" as reply type byte) because the connection can receive an HTTP response instead of Redis protocol.

Using Connection Strings in Your App

The recommended approach is to store the connection string in an environment variable. If you linked your database to an app during creation, this is done automatically.

Manual Configuration

1. Navigate to your app's Environment Variables settings
2. Add a new variable (e.g., DATABASE_URL)
3. Paste your connection string as the value
4. Save and redeploy your app

Framework Examples

Node.js (pg)

const { Pool } = require('pg');
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
});

Python (psycopg2)

import os
import psycopg2

conn = psycopg2.connect(os.environ['DATABASE_URL'])

Django

import dj_database_url

DATABASES = {
    'default': dj_database_url.config(default=os.environ['DATABASE_URL'])
}

TLS/SSL

All Hostless databases have TLS encryption enabled by default. Your connections are automatically secured without additional configuration.

Most database drivers will automatically use TLS when connecting to Hostless databases. If you need to explicitly enable SSL, refer to your driver's documentation.

Connection Pooling (PostgreSQL)

PostgreSQL databases include PgBouncer, a connection pooler that efficiently manages database connections. This is transparent to your application - simply connect using the provided connection string.

Benefits of connection pooling:

• Reduced connection overhead
• Better handling of many concurrent connections
• Improved performance for serverless workloads

Using Knex.js with Hostless PostgreSQL

If you use Knex.js and see KnexTimeoutError: Timeout acquiring a connection. The pool is probably full. Are you missing a .transacting(trx) call?, apply these fixes:

1. Use the transaction client for every query inside a transaction
   Inside a knex.transaction() callback, use the trx argument for all queries. Using knex instead of trx acquires extra connections and can exhaust the pool.

   // ✅ Correct: all queries use trx
   await knex.transaction(async (trx) => {
     await trx('users').insert({ name: 'Alice' });
     await trx('orders').insert({ user_id: 1 });
   });
   
   // ❌ Wrong: second query uses knex and acquires another connection
   await knex.transaction(async (trx) => {
     await trx('users').insert({ name: 'Alice' });
     await knex('orders').insert({ user_id: 1 }); // pool exhaustion
   });

2. Limit the Knex pool size
   PgBouncer has limited server connections. Keep Knex’s pool small so you don’t exhaust them:

   const knex = require('knex')({
     client: 'pg',
     connection: process.env.DATABASE_URL,
     pool: { min: 0, max: 10 },
     acquireConnectionTimeout: 10000,
   });

3. Ensure transactions complete or roll back
   Always resolve or reject the transaction callback (and avoid leaving it hanging) so the connection is released.

Troubleshooting

Connection Refused

• Verify your database status is RUNNING
• Check that you're using the correct host and port
• Ensure your connection string is properly URL-encoded

Authentication Failed

• Double-check your username and password
• Copy the credentials directly from the dashboard to avoid typos
• Ensure special characters in passwords are properly escaped

Database Not Found

• Verify you're connecting to the correct database name
• The database name matches your Hostless database name

Knex.js: "Timeout acquiring a connection" / "pool is probably full"

See Using Knex.js with Hostless PostgreSQL above. Use .transacting(trx) for every query inside a transaction and limit your Knex pool size (e.g. max: 10).