insta 0.0.28 → 0.0.29

package/dist/commands/db.js

@@ -120,6 +120,65 @@ export async function dbLimits(opts) {
 // Render the instance's volume from a database/instance read. Pure, exported for tests. Reads the
 // CANONICAL volume* names only — storageSize/storageGiB are deprecated aliases the platform drops
 // next release, so depending on them here would be a scheduled breakage.
+// Bytes → human units, one decimal above KiB. Local because the metrics payload is the only
+// bytes-denominated read in this file (fmtMib serves the MiB-denominated resize path).
+export function fmtBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    const units = ['KiB', 'MiB', 'GiB', 'TiB'];
+    let v = n / 1024;
+    let i = 0;
+    while (v >= 1024 && i < units.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    return `${v.toFixed(1)} ${units[i]}`;
+}
+// Human-readable stats lines from GET /database/metrics. Pure seam for tests. "—" for anything
+// unmeasured (old platform, suspended instance, no cache traffic yet) — never a fake 0: the
+// platform omits cacheHitRatio and sends max 0 in exactly those cases.
+export function dbStatsLines(group, body) {
+    const c = body?.connections ?? {};
+    const max = typeof c.max === 'number' && c.max > 0 ? c.max : null;
+    const total = typeof c.total === 'number' ? c.total : null;
+    const conn = total === null ? '—'
+        : (max === null ? String(total) : `${total} / ${max}`)
+            + (typeof c.active === 'number' && max !== null ? ` (${c.active} active)` : '');
+    const ratio = body?.cacheHitRatio;
+    const cache = typeof ratio === 'number' ? `${(ratio * 100).toFixed(1)}%` : '—';
+    const size = typeof body?.dbSizeBytes === 'number' ? fmtBytes(body.dbSizeBytes) : '—';
+    const bits = [
+        typeof body?.state === 'string' ? body.state : null,
+        typeof body?.serverVersion === 'string' && body.serverVersion ? `PG ${body.serverVersion}` : null,
+    ].filter(Boolean);
+    const state = bits.length ? ` (${bits.join(' · ')})` : '';
+    return [
+        `postgres ${group}${state}`,
+        `  connections  ${conn}`,
+        `  cache hit    ${cache}`,
+        `  size         ${size}`,
+    ];
+}
+// Point-in-time stats snapshot for a postgres service: connections vs the server's ceiling, cache
+// hit rate, database size. Read-only. insta-db-backed: a suspended instance answers from the
+// provider's control plane (shown as "(suspended)" with structural zeros), never dialed.
+// Neon-backed: the platform reads over a direct SQL connection, so a one-shot call may wake a
+// suspended endpoint — acceptable for an explicit command, which is why nothing here polls.
+export async function dbStats(opts) {
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const qs = new URLSearchParams();
+    const branch = opts.branch ?? p.branch;
+    if (branch)
+        qs.set('branch', branch);
+    if (opts.group)
+        qs.set('group', opts.group);
+    const res = await api.rawRequest('GET', `/projects/${p.projectId}/database/metrics${qs.toString() ? `?${qs}` : ''}`);
+    if (opts.json)
+        return printJson(res.body);
+    for (const line of dbStatsLines(opts.group ?? 'default', res.body))
+        info(line);
+}
 export function dbVolumeLines(group, body) {
     const gib = typeof body?.volumeGib === 'number' ? `${body.volumeGib}Gi` : (typeof body?.volumeSize === 'string' ? body.volumeSize : undefined);
     if (gib === undefined)

package/dist/commands/metrics.js

@@ -8,6 +8,58 @@ function qs(params) {
     const s = u.toString();
     return s ? `?${s}` : '';
 }
+// One printed series line. Pure seam so the formatting is testable without a backend.
+//
+// Byte-rate series (compute's egress/ingress) arrive as raw bytes per second, which is unreadable at
+// real traffic volumes — 20480031 bytes/s is 20 MB/s. Percent and vCPU units are already
+// human-sized, so only bytes and byte rates get scaled.
+export function metricLine(s) {
+    const last = s.points?.[s.points.length - 1];
+    const value = last ? formatMetricValue(last[1], s.unit) : 'n/a';
+    const unit = s.unit && !isScaled(s.unit) ? ` (${s.unit})` : '';
+    return `${s.name}${unit}: ${value}  [${s.points?.length ?? 0} points]`;
+}
+// The platform's unit strings are the contract here (`bytes` for memory/storage, `bytes/s` for
+// egress/ingress — src/adapters/fly.ts and insta-db.ts). Matching them loosely is deliberate: an
+// unrecognised unit fails SILENTLY back to the raw 8-digit number this scaling exists to fix, so a
+// casing or spacing change on the platform side must not be enough to regress it.
+function scaleOf(unit) {
+    const u = unit?.trim().toLowerCase();
+    if (u === 'bytes' || u === 'byte' || u === 'b')
+        return 'bytes';
+    if (u === 'bytes/s' || u === 'byte/s' || u === 'b/s' || u === 'bytes/sec')
+        return 'bytes/s';
+    return undefined;
+}
+function isScaled(unit) {
+    return scaleOf(unit) !== undefined;
+}
+function formatMetricValue(v, unit) {
+    if (!Number.isFinite(v))
+        return 'n/a';
+    const scale = scaleOf(unit);
+    // Traffic scales by 1000 because egress is BILLED per decimal GB (`bytes / 1e9`, platform
+    // src/adapters/fly.ts) — a 1024-based "GB/s" would sit ~7% off the invoice. Memory and storage
+    // stay binary: those ceilings are provisioned in GiB. Same split as the console.
+    if (scale === 'bytes')
+        return humanBytes(v, 1024);
+    if (scale === 'bytes/s')
+        return `${humanBytes(v, 1000)}/s`;
+    return String(v);
+}
+function humanBytes(v, base) {
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let value = v;
+    let i = 0;
+    while (Math.abs(value) >= base && i < units.length - 1) {
+        value /= base;
+        i += 1;
+    }
+    // Sub-KB values keep their integer form (`512 B`, not `512.0 B`), but a RATE is fractional —
+    // PromQL rate() of a byte counter yields things like 342.857142, which must not print in full.
+    const shown = i === 0 && Number.isInteger(value) ? String(value) : value.toFixed(1);
+    return `${shown} ${units[i]}`;
+}
 // insta metrics <db|compute> [group]
 export async function metrics(component, group, opts) {
     const api = await ApiClient.load();
@@ -19,10 +71,8 @@ export async function metrics(component, group, opts) {
         info(`note: ${res.note}`);
     if (!res.series?.length)
         return info('(no series)');
-    for (const s of res.series) {
-        const last = s.points?.[s.points.length - 1];
-        info(`${s.name}${s.unit ? ` (${s.unit})` : ''}: ${last ? last[1] : 'n/a'}  [${s.points?.length ?? 0} points]`);
-    }
+    for (const s of res.series)
+        info(metricLine(s));
 }
 // Customer-facing name for each internal billing dimension (the platform stores RAM as `ram`).
 const DIMENSION_LABEL = { ram: 'memory' };

package/dist/index.js

@@ -180,6 +180,9 @@ db.command('limits').description("Show or set a postgres service's resource ceil
     .option('--cpu <n>', "vCPU ceiling, e.g. 2 or 2500m").option('--memory <size>', "memory ceiling, e.g. 4Gi")
     .option('--json').option('--branch <branch>', 'branch (default: current)').option('--group <g>', 'postgres service name (default: the sole/default one)')
     .action(guard((o) => dbCmd.dbLimits(o)));
+db.command('stats').description("Postgres stats snapshot: connections vs the server's max (active count), cache hit rate, database size. insta-db-backed services answer without waking a suspended instance")
+    .option('--json').option('--branch <branch>', 'branch (default: current)').option('--group <g>', 'postgres service name (default: the sole/default one)')
+    .action(guard((o) => dbCmd.dbStats(o)));
 db.command('always-on <mode>').description('Set a postgres service always-on (mode: on|off). on = instance stays warm, no cold starts; off = default scale-to-zero (idle instance suspends; first connection cold-starts). insta-db-backed services only')
     .option('--json').option('--branch <branch>', 'branch (default: current)').option('--group <g>', 'postgres service name (default: the sole/default one)')
     .action(guard((mode, o) => dbCmd.dbAlwaysOn(mode, o)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "insta",
-  "version": "0.0.28",
+  "version": "0.0.29",
   "type": "module",
   "description": "InstaCloud CLI — a thin client of the platform control-plane API.",
   "keywords": [