From 5160242b859a0edc239fc8fb017aa22616e01690 Mon Sep 17 00:00:00 2001 From: vincent Date: Tue, 8 Sep 2026 15:58:09 -0400 Subject: [PATCH 1/2] mpg: document the Managed Postgres API MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Managed Postgres API (part of the Machines API — cluster CRUD, attachments, backups, databases, extensions, fork/restore, users) has been live for a while but was never linked from the docs site or announced. Add a landing page under mpg/api/ following the same pattern as machines/api/, link it from the MPG overview page and nav. Co-Authored-By: Claude Sonnet 5 --- mpg/api/index.html.md | 59 ++++++++++++++++++++++++++++++++++++++ mpg/index.html.md | 1 + partials/_mpg_nav.html.erb | 3 +- 3 files changed, 62 insertions(+), 1 deletion(-) create mode 100644 mpg/api/index.html.md diff --git a/mpg/api/index.html.md b/mpg/api/index.html.md new file mode 100644 index 0000000000..7307a27247 --- /dev/null +++ b/mpg/api/index.html.md @@ -0,0 +1,59 @@ +--- +title: "Managed Postgres API" +layout: docs +nav: mpg +toc: false +--- + +The Managed Postgres API is part of the [Fly Machines API](/docs/machines/api/), Fly.io's REST API for provisioning and managing resources. Use it to create and manage Managed Postgres clusters, databases, users, backups, and app attachments programmatically, without going through flyctl or the dashboard. + +If you're not already familiar with the Machines API, start with [Working with the Machines API](/docs/machines/api/working-with-machines-api/) to get authenticated and set up. + +## Endpoints + +Cluster management: + +- `GET /v1/postgres` - List Managed Postgres clusters for an organization. +- `POST /v1/postgres` - Create a Managed Postgres cluster. +- `GET /v1/postgres/{postgres_cluster_id}` - Get details of a specific cluster. +- `DELETE /v1/postgres/{postgres_cluster_id}` - Delete a cluster. + +Attachments: + +- `POST /v1/postgres/{postgres_cluster_id}/attachments` - Attach a cluster to a Fly App. +- `DELETE /v1/postgres/{postgres_cluster_id}/attachments/{app_name}` - Detach a cluster from a Fly App. + +Backups: + +- `GET /v1/postgres/{postgres_cluster_id}/backups` - List backups for a cluster. +- `POST /v1/postgres/{postgres_cluster_id}/backups` - Create a backup. + +Databases: + +- `GET /v1/postgres/{postgres_cluster_id}/databases` - List databases within a cluster. +- `POST /v1/postgres/{postgres_cluster_id}/databases` - Create a database. +- `DELETE /v1/postgres/{postgres_cluster_id}/databases/{database_name}` - Delete a database. + +Extensions: + +- `GET /v1/postgres/{postgres_cluster_id}/databases/{database_name}/extensions` - List extensions available within a database. +- `POST /v1/postgres/{postgres_cluster_id}/databases/{database_name}/extensions` - Enable an extension. +- `DELETE /v1/postgres/{postgres_cluster_id}/databases/{database_name}/extensions/{extension_name}` - Disable an extension. + +Fork and restore: + +- `POST /v1/postgres/{postgres_cluster_id}/fork` - Fork a ready cluster into a new cluster. +- `POST /v1/postgres/{postgres_cluster_id}/restore` - Restore a backup, or a point-in-time, into a new cluster. + +Users: + +- `GET /v1/postgres/{postgres_cluster_id}/users` - List Postgres users within a cluster. +- `POST /v1/postgres/{postgres_cluster_id}/users` - Create a Postgres user. +- `PATCH /v1/postgres/{postgres_cluster_id}/users/{username}` - Update a user's role. +- `DELETE /v1/postgres/{postgres_cluster_id}/users/{username}` - Delete a user. +- `GET /v1/postgres/{postgres_cluster_id}/users/{username}/credentials` - Get connection credentials for a user. +- `POST /v1/postgres/{postgres_cluster_id}/users/{username}/rotate_password` - Rotate a user's password. + +## OpenAPI spec + +See the full [OpenAPI 3.0 specification](https://docs.machines.dev/+external) for request and response schemas. diff --git a/mpg/index.html.md b/mpg/index.html.md index f39a1755be..48cc03fc57 100644 --- a/mpg/index.html.md +++ b/mpg/index.html.md @@ -27,6 +27,7 @@ You'll be able to access: - A highly-available Postgres cluster within your Fly.io organization's [private network](/docs/networking/private-networking/) - Multiple databases and schemas on that cluster +- Programmatic access via the [Managed Postgres API](/docs/mpg/api/), part of the Fly Machines API - Fly.io Support Portal to log tickets and get help - Any trusted extensions included in the [default Postgres 16 distribution](https://www.postgresql.org/docs/16/contrib.html) - The third party `pgvector` extension for vector similarity search diff --git a/partials/_mpg_nav.html.erb b/partials/_mpg_nav.html.erb index dcba7a0c5a..61c2576232 100644 --- a/partials/_mpg_nav.html.erb +++ b/partials/_mpg_nav.html.erb @@ -32,7 +32,8 @@ links: [ { text: "Monitoring and Metrics", path: "/docs/mpg/metrics/" }, { text: "Import data from another postgres cluster", path: "/docs/mpg/import/" }, - { text: "Supported Postgres Extensions", path: "/docs/mpg/extensions/" } + { text: "Supported Postgres Extensions", path: "/docs/mpg/extensions/" }, + { text: "Managed Postgres API", path: "/docs/mpg/api/" } ] } ] From 5d3449d1a5221dcfb9f17796a292dbf749c3074f Mon Sep 17 00:00:00 2001 From: vincent Date: Tue, 8 Sep 2026 16:06:56 -0400 Subject: [PATCH 2/2] mpg: note the required org_slug param on the list endpoint Confirmed against the live OpenAPI spec while testing this page's claims: GET /v1/postgres requires an org_slug query parameter to scope the list, otherwise it 404s with "Organization not found". Co-Authored-By: Claude Sonnet 5 --- mpg/api/index.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mpg/api/index.html.md b/mpg/api/index.html.md index 7307a27247..35107b4b1c 100644 --- a/mpg/api/index.html.md +++ b/mpg/api/index.html.md @@ -13,7 +13,7 @@ If you're not already familiar with the Machines API, start with [Working with t Cluster management: -- `GET /v1/postgres` - List Managed Postgres clusters for an organization. +- `GET /v1/postgres` - List Managed Postgres clusters for an organization. Requires an `org_slug` query parameter. - `POST /v1/postgres` - Create a Managed Postgres cluster. - `GET /v1/postgres/{postgres_cluster_id}` - Get details of a specific cluster. - `DELETE /v1/postgres/{postgres_cluster_id}` - Delete a cluster.