---
title: "Get Channel Postgres"
method: GET
path: "/apps/{app_id}/channels/{channel_id}/postgres"
---

# Get Channel Postgres

`GET /apps/{app_id}/channels/{channel_id}/postgres`

## Request

- Base URL: `https://api.xhostd.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.xhostd.com/apps/{app_id}/channels/{channel_id}/postgres`
- Auth: none declared

Report the Postgres state of one channel the caller can reach.

The route only reads, so it runs on ``run_read_in_thread``. An owner
costs four round trips to the control DB: the access check, the
``channel_schemas`` row with the profile of the instance that holds
it, which sets the displayed limit, and the two reads of the
channel's restore (``postgres/api.py::channel_restore``), a third
when the channel has one, and three more for its queue state while
the restore is ``received`` (:func:`_restore_response`). A member
reads the owner name too, for the
external database name. The connection count and the size come from
the tenant Postgres, not from the control DB.

## Path parameters

- `app_id` string, uuid, required
- `channel_id` string, uuid, required

## Headers

- `authorization` string, nullable

## Response `200`

Successful Response

- ChannelPostgresStatus
  - `db_name` string, required
  - `role_name` string, required
  - `status` 'provisioning' | 'ready' | 'failed', required
  - `last_error` string, nullable, required
  - `connection_count` integer, required
  - `connection_limit` integer, required
  - `password_set` boolean, required
  - `storage_bytes` integer, required
  - `external_enabled` boolean, required
  - `external_host` string, required
  - `external_database` string, required
  - `restore` RestoreStatusResponse, required: One restore of a channel's database. ``status`` is ``queued``, ``extracting``, ``loading``, ``swapping``, ``succeeded``, or ``failed``. ``queued`` also covers a restore that has started and puts the read-only hold on, so a surface shows ``activity`` and ``waiting`` rather than the word "queued". ``during_restore`` is the mode the request chose, ``read_only``, ``maintenance``, or ``live``, and ``maintenance_channel_id`` the static channel a ``maintenance`` restore's page shows, null for the platform's page. While the restore is active, ``waiting`` names why it waits, ``queue_ahead`` counts the restores before a ``received`` one on its database server, and ``activity`` says in one plain sentence what it does now (``postgres/api.py::restore_queue_state``); each is null when it does not apply. ``error_code`` is set on a failed restore, and ``message`` says why in plain words. ``notice`` is the mode's sentence from :data:`RESTORE_MODE_NOTICES`.
    - `restore_id` string, uuid, required
    - `app_id` string, uuid, required
    - `channel_id` string, uuid, required
    - `snapshot_id` string, uuid, required
    - `during_restore` 'read_only' | 'maintenance' | 'live', required: What the channel's app can do with its database while the restore runs, from the claim to the swap. ``read_only``: the ``hold`` step makes every new transaction of ``r_<ch32>`` in ``ch_<ch32>`` read-only, so a write fails with SQLSTATE 25006 rather than vanish at the swap. ``maintenance``: the same hold, and the edge serves a page in place of the app (``proxy/maintenance.py``), the restore's ``maintenance_channel_id`` parameter naming a static channel for the page or ``None`` for the platform's own. ``live``: the app keeps writing, and the swap discards those writes.
    - `maintenance_channel_id` string, uuid, nullable, required
    - `status` 'queued' | 'extracting' | 'loading' | 'swapping' | 'succeeded' | 'failed', required
    - `waiting` string, nullable, required
    - `queue_ahead` integer, nullable, required
    - `activity` string, nullable, required
    - `progress` RestoreProgress, required: How far a restore's current step got. While the restore extracts, ``phase`` names the extract's phase: ``fetch``, ``refetch``, ``replay``, or ``dump``. ``bytes`` counts the bytes the database server has fetched from the backup, or written to the snapshot's dump, so far, and ``segments`` counts the log files the ``replay`` phase has replayed. ``waiting`` names why the extract waits for the database server, such as ``extraction_busy``. ``items_done`` of ``items_total`` counts the snapshot's entries loaded. A field the step does not report is null.
      - `phase` string, nullable, required
      - `bytes` integer, nullable, required
      - `segments` integer, nullable, required
      - `waiting` string, nullable, required
      - `items_done` integer, nullable, required
      - `items_total` integer, nullable, required
    - `error_code` string, nullable, required
    - `message` string, nullable, required
    - `notice` string, required
    - `submitted_at` string, date-time, required
    - `started_at` string, date-time, nullable, required
    - `updated_at` string, date-time, required
    - `finished_at` string, date-time, nullable, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/xhostd/apis/xhostd-public.md) · [All operations](https://skmtc.dev/xhostd/apis/xhostd-public/llms.txt) · [OpenAPI document](https://skmtc.dev/xhostd/apis/xhostd-public/revisions/bf439c4d1789?raw)