hostCapacity

Correlate memory and parallelism settings with the capacity of the machine PostgreSQL runs on.

read-onlyany connectionsweeps replication groupsweeps group

Synopsis

hostCapacity([ram_mb], [storage], [vcpus])

Description

Correlate memory and parallelism settings with the capacity of the machine PostgreSQL runs on. Host RAM and vCPU count exist outside the catalog, so they must be injected: pass them as arguments, set host_ram_mb/host_vcpus in the connection's section of the connections file, or export PG_LICHT_HOST_RAM_MB/PG_LICHT_HOST_VCPUS. Returns the host facts with the source they came from, every memory-related setting resolved to bytes, and derived ratios (shared_buffers and effective_cache_size as a percentage of RAM, work_mem times max_connections, maintenance_work_mem times autovacuum_max_workers, parallel workers per vCPU).

Ratios are null when no RAM figure was supplied; nothing is ever guessed. IMPORTANT: 'settings' is what pg_settings reports for THIS session, so an ALTER ROLE ... SET or ALTER DATABASE ... SET made for another role is not in it. 'overrides' carries those from pg_db_role_setting, collapsed by (scope, name, value): two roles with different values stay separate rows, while N roles sharing one value become a single row with 'count' and up to five example names ('names_truncated' says when the rest were dropped).

On a multi-tenant cluster the same search_path on every tenant is otherwise one row per tenant and swamps the three overrides that matter. committed_worst_case uses the largest work_mem any role is configured with rather than this session's -- work_mem_is_overridden says when the two differ. That layer is invisible to pg_settings and is the usual explanation for a statement that is slow only from the application.

Parameters

ram_mb optionalinteger: total host memory in megabytes, overriding any configured value
storage optionalstring: free-text description of the storage, e.g. "local nvme" or "gp3 3000 iops"; echoed back, never interpreted
vcpus optionalinteger: number of vCPUs or cores available to the host, overriding any configured value

Also accepts connection, replication_group, group, role, described once under arguments every tool takes.

Output

Memory and parallelism settings against the host. An absent extension or a missing grant is reported as {error, hint} instead.

Field	Type
derived	object \| null
host	object \| null
server	object \| null
settings	object \| null

Scope

This reading is instance-wide -- every database on the same postmaster returns it identically, so asking each of them in turn repeats one answer. The counters here are each server's own, so members of a replication group legitimately disagree and the answer is their sum, not the primary's copy.

Example mocked data

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostCapacity",
    "arguments": {
      "connection": "shop_prod"
    }
  }
}

Result

{
  "host": {
    "ram_mb": 65536,
    "ram_bytes": 68719476736,
    "vcpus": 16,
    "source": "config file"
  },
  "server": {
    "version": "18.6",
    "database": "shop"
  },
  "settings": {
    "shared_buffers": {
      "setting": "2097152",
      "unit": "8kB",
      "bytes": 17179869184
    },
    "work_mem": {
      "setting": "32768",
      "unit": "kB",
      "bytes": 33554432
    },
    "max_connections": {
      "setting": "300"
    }
  },
  "derived": {
    "shared_buffers_percent_of_ram": 25.0,
    "work_mem_times_max_connections_percent_of_ram": 14.6,
    "max_parallel_workers_per_vcpu": 0.5
  }
}

Invented values on a fictional shop database, shaped by and checked against this tool's output schema. Real output is returned as structuredContent to clients that negotiate MCP 2025-06-18 or later.