Database

Fetch the connection details of your project’s managed PostgreSQL, MongoDB and Valkey databases, and read their live metrics.

import { Ghayma } from "@ghayma/sdk";
const ghayma = new Ghayma({ apiKey: process.env.GHAYMA_API_KEY });

Your app does not query its database through this SDK. It connects with DATABASE_URL, MONGODB_URI or REDIS_URL and its own driver or ORM — pg, Prisma, mongoose, ioredis — exactly as it would anywhere else. The SDK only fetches the connection details, for the cases where reading them at runtime beats baking them into an environment variable.

Get Connection

Returns a ready-to-use connection string, plus its parts.

const conn = await ghayma.database.getConnection("db-id");
console.log(conn.url); // Full connection string

You always get the in-cluster URL, host and port — the ones a deployed app uses. Reaching the database from outside is a separate identity with a hostname of its own: see External Access.

PostgreSQL

import { Pool } from "pg";
const conn = await ghayma.database.getConnection("db-id");
const pool = new Pool({ connectionString: conn.url });
 
const result = await pool.query("SELECT NOW()");

With Prisma — set DATABASE_URL in your .env:

DATABASE_URL=postgresql://c_14bb37f4:pass@host:5432/db_mydb

That user is the app’s own per-connection role, never the database’s own login; ghayma env pull writes the real value for you.

MongoDB

import mongoose from "mongoose";
const conn = await ghayma.database.getConnection("db-id");
await mongoose.connect(conn.url);

Valkey

import Redis from "ioredis";
const conn = await ghayma.database.getConnection("db-id");
const redis = new Redis(conn.url);

conn.url is the redis:// URL the app’s REDIS_URL carries, with the app’s own user. See Connecting an app.

Returns: ConnectionConfig

Get Credentials

Get the raw credentials, including the internal URL.

const creds = await ghayma.database.getCredentials("db-id");
console.log(creds.host, creds.port, creds.username, creds.password);
console.log(creds.internal_url);
console.log(creds.level);       // "connect" or "read-only"
console.log(creds.credential);  // always "connection"

They are the site’s own, as above. level is the connection’s level, and credential is always "connection"; both need @ghayma/sdk 1.8.0 or later. A database body has no username any more: the database’s own login is never handed out.

List Databases

const databases = await ghayma.database.list();
 
for (const db of databases) {
  console.log(db.name, db.engine, db.status);
}

With a project API key this lists the key’s own project’s databases.

Get Database

const db = await ghayma.database.get("db-id");

Metrics

const metrics = await ghayma.database.getMetrics("db-id");
console.log(metrics.active_connections);  // Active connections
console.log(metrics.size_readable);       // Storage used, e.g. "12.4 MB"

Only status is set when the database isn’t running. Engine-specific counters arrive in extra — table_count, cache_hit_ratio and friends on postgres, collections, objects and friends on mongodb, and keys, maxmemory_bytes, evicted_keys, keyspace_hits, keyspace_misses and mode on valkey. On valkey, size_readable is the memory the data uses.