ZEKTOR.IO Docs

Connecting to Your Database

How to connect to your Zektor.io database instances — connection strings, TLS encryption, client configuration, and connection resilience.

Overview

Once your database instance is provisioned, you can connect to it using standard database clients. All connections are encrypted with TLS by default.

Connection Details

Connection credentials are available in the Settings tab of your instance dashboard. You'll find:

  • Host — The hostname of your database instance
  • Port — The port number (PostgreSQL: 5432, Valkey: 6379)
  • Username — Your database user
  • Password — Your database password
  • Database name — The default database (PostgreSQL only)
  • Connection string — A ready-to-use URI

PostgreSQL Connections

Using psql

The fastest way to test your connection:

psql 'host=<your-host> port=5432 user=<username> password=<password> dbname=<database> sslmode=require'

Or using a connection string:

psql 'postgresql://<username>:<password>@<your-host>:5432/<database>?sslmode=require'

Using Connection String URI

Most ORMs and database libraries accept a PostgreSQL connection URI:

postgresql://<username>:<password>@<your-host>:5432/<database>?sslmode=require

Node.js (pg)

import pg from 'pg';

const pool = new pg.Pool({
  connectionString: 'postgresql://<username>:<password>@<your-host>:5432/<database>?sslmode=require'
});

const result = await pool.query('SELECT NOW()');
console.log(result.rows[0]);

Python (psycopg2)

import psycopg2

conn = psycopg2.connect(
    host="<your-host>",
    port=5432,
    user="<username>",
    password="<password>",
    dbname="<database>",
    sslmode="require"
)

Go (pgx)

import "github.com/jackc/pgx/v5/pgxpool"

pool, err := pgxpool.New(ctx,
    "postgresql://<username>:<password>@<your-host>:5432/<database>?sslmode=require")

Prisma

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

Set DATABASE_URL in your .env:

DATABASE_URL="postgresql://<username>:<password>@<your-host>:5432/<database>?sslmode=require"

Drizzle

import { drizzle } from 'drizzle-orm/node-postgres';
import pg from 'pg';

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

const db = drizzle(pool);

Django

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'HOST': '<your-host>',
        'PORT': '5432',
        'NAME': '<database>',
        'USER': '<username>',
        'PASSWORD': '<password>',
        'OPTIONS': {
            'sslmode': 'require',
        },
    }
}

Laravel

// .env
DB_CONNECTION=pgsql
DB_HOST=<your-host>
DB_PORT=5432
DB_DATABASE=<database>
DB_USERNAME=<username>
DB_PASSWORD=<password>
DB_SSLMODE=require

Ruby on Rails

# config/database.yml
production:
  adapter: postgresql
  host: <your-host>
  port: 5432
  database: <database>
  username: <username>
  password: <password>
  sslmode: require

Valkey (Redis-compatible) Connections

Using valkey-cli / redis-cli

valkey-cli -h <your-host> -p 6379 -a <password> --tls

Or with redis-cli:

redis-cli -h <your-host> -p 6379 -a <password> --tls

Using Connection String URI

rediss://<password>@<your-host>:6379

Note: rediss:// (with double s) indicates TLS/SSL connections.

Node.js (ioredis)

import Redis from 'ioredis';

const redis = new Redis({
  host: '<your-host>',
  port: 6379,
  password: '<password>',
  tls: {},
});

Python (redis-py)

import redis

r = redis.Redis(
    host='<your-host>',
    port=6379,
    password='<password>',
    ssl=True
)

Go (go-redis)

import "github.com/redis/go-redis/v9"

rdb := redis.NewClient(&redis.Options{
    Addr:     "<your-host>:6379",
    Password: "<password>",
    TLSConfig: &tls.Config{},
})

BullMQ (Node.js job queues)

import { Queue, Worker } from 'bullmq';

const connection = {
  host: '<your-host>',
  port: 6379,
  password: '<password>',
  tls: {},
};

const queue = new Queue('my-queue', { connection });
const worker = new Worker('my-queue', async (job) => {
  // process job
}, { connection });

TLS / SSL Encryption

All Zektor.io connections use TLS encryption by default. This ensures that data in transit is always encrypted.

  • PostgreSQL: Use sslmode=require or sslmode=verify-full in your connection string
  • Valkey: Use --tls flag or rediss:// URI scheme

No additional certificates need to be installed — our TLS certificates are signed by trusted public certificate authorities.

Connection Limits

Connection limits depend on your cluster size:

Cluster SizePostgreSQL max_connectionsValkey max clients
Starter25128
Standard50256
Pro100512
Business2001024

If you need more connections, consider using a connection pooler like PgBouncer for PostgreSQL, or contact us for custom limits.

Connection Resilience

Follow these best practices to keep your application resilient to transient connection issues.

Use connection pooling

Always use a connection pool instead of creating individual connections. This reduces overhead and handles reconnection automatically.

// Node.js (pg) — pool handles reconnection
const pool = new pg.Pool({
  connectionString: process.env.DATABASE_URL,
  max: 20,               // max connections in pool
  idleTimeoutMillis: 30000,
  connectionTimeoutMillis: 5000,
});

Set timeouts

Prevent runaway queries from holding connections indefinitely:

-- Set per-session timeout (60 seconds)
SET statement_timeout = '60s';

-- Set idle transaction timeout (30 seconds)
SET idle_in_transaction_session_timeout = '30s';

Or in your connection string:

postgresql://...?sslmode=require&options=-c%20statement_timeout%3D60000

Keep transactions short

Long-running transactions hold connections and locks. Keep transactions as short as possible:

  • Move network calls (API requests, file uploads) outside of transactions
  • Batch large operations into smaller transactions
  • Aim for transactions under 5 seconds

Implement retry logic

Transient errors (network blips, brief maintenance) resolve themselves. Retry with backoff:

async function queryWithRetry(pool, sql, params, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await pool.query(sql, params);
    } catch (err) {
      const isTransient = err.code === 'ECONNREFUSED' ||
                          err.code === 'ECONNRESET' ||
                          err.code === '57P01'; // admin_shutdown
      if (!isTransient || attempt === maxRetries - 1) throw err;
      await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000));
    }
  }
}

Handle connection during scaling

When you resize your instance, there may be a brief connection interruption (typically seconds). Applications with connection pooling and retry logic will reconnect automatically.

Troubleshooting

Connection refused

  • Verify the host and port are correct
  • Ensure your instance is in Active status
  • Check that you're using TLS

Authentication failed

  • Double-check your username and password from the Settings tab
  • Ensure you're connecting to the correct database name

SSL/TLS errors

  • Make sure you're using sslmode=require (PostgreSQL) or --tls (Valkey)
  • Update your client library to the latest version for TLS 1.3 support

Next Steps

Getting Started

Create your first database instance on Zektor.io in under 60 seconds.

Migration Guide

How to migrate your existing PostgreSQL or Valkey database to Zektor.io — step-by-step instructions for common providers and tools.

On this page

OverviewConnection DetailsPostgreSQL ConnectionsUsing psqlUsing Connection String URIPopular Client LibrariesNode.js (pg)Python (psycopg2)Go (pgx)PrismaDrizzleDjangoLaravelRuby on RailsValkey (Redis-compatible) ConnectionsUsing valkey-cli / redis-cliUsing Connection String URIPopular Client LibrariesNode.js (ioredis)Python (redis-py)Go (go-redis)BullMQ (Node.js job queues)TLS / SSL EncryptionConnection LimitsConnection ResilienceUse connection poolingSet timeoutsKeep transactions shortImplement retry logicHandle connection during scalingTroubleshootingConnection refusedAuthentication failedSSL/TLS errorsNext Steps