From b182a95a918ff5414e6084264964270b89c44694 Mon Sep 17 00:00:00 2001 From: brandonphelps1212 Date: Thu, 19 Nov 2026 19:15:19 -0500 Subject: [PATCH 1/2] add the planetscale plugin Watches the PlanetScale API spec (schemas/openapi.yaml in planetscale/terraform-provider-planetscale, a copy of planetscale.com/docs/openapi.yaml), pinned to the commit that last changed it, version = commit date. Deprecations are read from the start of the operation's description ("Deprecated. Use ... instead."); keep rule is deprecationsOnly. A fetched file with no paths is refused. Co-Authored-By: Claude Opus 5.5 Signed-off-by: brandonphelps1212 --- README.md | 2 +- adapter/planetscale.go | 113 + adapter/planetscale_test.go | 93 + docs/plugins.json | 12 +- docs/plugins.md | 1 + plugins/openapi/openapi.go | 6 +- plugins/openapi/planetscale.go | 49 + plugins/openapi/planetscale_test.go | 175 ++ plugins/openapi/registered_test.go | 2 +- plugins/openapi/testdata/README.md | 4 + .../openapi/testdata/golden/planetscale.json | 107 + .../testdata/planetscale-b49c3540.yaml | 1745 ++++++++++++++++ .../testdata/planetscale-e631095a.yaml | 1452 +++++++++++++ .../testdata/planetscale-f6d6ad4d.yaml | 1828 +++++++++++++++++ .../testdata/planetscale-fc13e09d.yaml | 825 ++++++++ providers/README.md | 1 + providers/planetscale.md | 52 + 17 files changed, 6463 insertions(+), 4 deletions(-) create mode 100644 adapter/planetscale.go create mode 100644 adapter/planetscale_test.go create mode 100644 plugins/openapi/planetscale.go create mode 100644 plugins/openapi/planetscale_test.go create mode 100644 plugins/openapi/testdata/golden/planetscale.json create mode 100644 plugins/openapi/testdata/planetscale-b49c3540.yaml create mode 100644 plugins/openapi/testdata/planetscale-e631095a.yaml create mode 100644 plugins/openapi/testdata/planetscale-f6d6ad4d.yaml create mode 100644 plugins/openapi/testdata/planetscale-fc13e09d.yaml create mode 100644 providers/planetscale.md diff --git a/README.md b/README.md index 2bd82bf..b25e164 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ [![Go Reference](https://pkg.go.dev/badge/github.com/patch-it-dev/patch-it-plugins.svg)](https://pkg.go.dev/github.com/patch-it-dev/patch-it-plugins) [![Go version](https://img.shields.io/github/go-mod/go-version/patch-it-dev/patch-it-plugins)](go.mod) [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-3f5bf0)](LICENSE) -[![Plugins](https://img.shields.io/badge/plugins-24-3f5bf0)](docs/plugins.md) +[![Plugins](https://img.shields.io/badge/plugins-25-3f5bf0)](docs/plugins.md) [![Docs](https://img.shields.io/badge/docs-docs.patch--it.dev-3f5bf0)](https://docs.patch-it.dev) [![Discussions](https://img.shields.io/github/discussions/patch-it-dev/patch-it-plugins)](https://github.com/patch-it-dev/patch-it-plugins/discussions) diff --git a/adapter/planetscale.go b/adapter/planetscale.go new file mode 100644 index 0000000..f2fa6c3 --- /dev/null +++ b/adapter/planetscale.go @@ -0,0 +1,113 @@ +package adapter + +import ( + "cmp" + "context" + "encoding/json" + "fmt" + "time" + + "github.com/patch-it-dev/patch-it-plugins/fetch" + "gopkg.in/yaml.v3" +) + +const ( + // planetscaleRepo is PlanetScale's Terraform provider, which keeps a copy + // of the PlanetScale API spec at planetscaleSpecPath. + planetscaleRepo = "planetscale/terraform-provider-planetscale" + // planetscaleSpecPath is the spec in that repo: a copy of + // https://planetscale.com/docs/openapi.yaml, which has no versions, + // committed when it changes. + planetscaleSpecPath = "schemas/openapi.yaml" +) + +// PlanetScale adapts the PlanetScale API spec for the openapi plugin. The +// repo tags no spec releases, so a tag here is the commit that last changed +// the spec, as for Supabase. +// +// The zero value reads GitHub. The fields point it at another server, for +// tests. +type PlanetScale struct { + APIBase string // GitHub's REST API; "" is https://api.github.com + RawBase string // files at a commit; "" is https://raw.githubusercontent.com +} + +var _ Adapter = PlanetScale{} + +func (PlanetScale) API() string { return "planetscale" } + +func (p PlanetScale) api(path string) string { + return cmp.Or(p.APIBase, "https://api.github.com") + "/repos/" + planetscaleRepo + path +} + +// LatestTag is the SHA of the newest commit that changed the spec. +func (p PlanetScale) LatestTag(ctx context.Context) (string, error) { + body, err := fetch.Get(ctx, p.api("/commits?path="+planetscaleSpecPath+"&per_page=1"), githubHeaders()) + if err != nil { + return "", fmt.Errorf("looking up planetscale's latest spec commit: %w", err) + } + var commits []struct { + SHA string `json:"sha"` + } + if err := json.Unmarshal(body, &commits); err != nil { + return "", fmt.Errorf("parsing github commits response: %w", err) + } + if len(commits) == 0 || commits[0].SHA == "" { + return "", fmt.Errorf("github lists no commit that changed the planetscale spec") + } + return commits[0].SHA, nil +} + +// Fetch downloads the spec at commit sha and converts it from YAML to JSON, +// which is what diff.Parse reads (as for Algolia). +// +// Version is the commit's date (YYYY-MM-DD): the API has no version of its +// own (`info.version` is a fixed "v1", checked 2026-11-19), so the date the +// spec changed is the closest thing to "the API version the change arrived +// in". +// +// A file that isn't a spec is an error, not an empty API: diffed against the +// last one, it would read as every operation removed. The commits that +// changed the file include one that deleted it (f33a0c3b35, 2025-12-04; +// it came back the same day), where the raw URL answers 404: fetch.Get's +// error. A file served 200 that has no paths (emptied, or a stub page like +// "404: Not Found", which YAML reads as a one-key mapping) is refused here. +func (p PlanetScale) Fetch(ctx context.Context, sha string) (Spec, error) { + meta, err := fetch.Get(ctx, p.api("/commits/"+sha), githubHeaders()) + if err != nil { + return Spec{}, fmt.Errorf("looking up planetscale spec commit %s: %w", sha, err) + } + var commit struct { + SHA string `json:"sha"` + Commit struct { + Committer struct { + Date time.Time `json:"date"` + } `json:"committer"` + } `json:"commit"` + } + if err := json.Unmarshal(meta, &commit); err != nil { + return Spec{}, fmt.Errorf("parsing github commit %s: %w", sha, err) + } + if commit.SHA == "" || commit.Commit.Committer.Date.IsZero() { + return Spec{}, fmt.Errorf("github commit %s has no sha or date", sha) + } + // Pin to the full SHA even when given a short one: the citation must + // name exactly one document. + url := cmp.Or(p.RawBase, "https://raw.githubusercontent.com") + "/" + planetscaleRepo + "/" + commit.SHA + "/" + planetscaleSpecPath + body, err := fetch.Get(ctx, url, nil) // raw.githubusercontent.com needs no auth + if err != nil { + return Spec{}, fmt.Errorf("fetching planetscale spec %s: %w", sha, err) + } + var doc map[string]any + if err := yaml.Unmarshal(body, &doc); err != nil { + return Spec{}, fmt.Errorf("parsing planetscale spec %s as yaml: %w", sha, err) + } + if paths, _ := doc["paths"].(map[string]any); len(paths) == 0 { + return Spec{}, fmt.Errorf("planetscale spec %s has no paths: not a spec", sha) + } + content, err := json.Marshal(doc) + if err != nil { + return Spec{}, fmt.Errorf("converting planetscale spec %s to json: %w", sha, err) + } + return Spec{Content: content, Version: commit.Commit.Committer.Date.UTC().Format("2006-01-02"), SourceURL: url}, nil +} diff --git a/adapter/planetscale_test.go b/adapter/planetscale_test.go new file mode 100644 index 0000000..9750d8f --- /dev/null +++ b/adapter/planetscale_test.go @@ -0,0 +1,93 @@ +package adapter + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "strings" + "testing" +) + +const planetscaleSHA = "fc13e09d0c18b893aabd3e02d175d13957bba677" + +// fakePlanetScaleGitHub serves the commits list, one commit by any prefix of +// planetscaleSHA, and the spec at planetscaleSHA (404 when spec is ""). +func fakePlanetScaleGitHub(t *testing.T, commitsJSON, spec string) PlanetScale { + t.Helper() + const repo = "/api/repos/planetscale/terraform-provider-planetscale" + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + switch p := r.URL.Path; { + case p == repo+"/commits" && r.URL.Query().Get("path") == "schemas/openapi.yaml": + w.Write([]byte(commitsJSON)) + case strings.HasPrefix(p, repo+"/commits/") && strings.HasPrefix(planetscaleSHA, strings.TrimPrefix(p, repo+"/commits/")): + w.Write([]byte(`{"sha":"` + planetscaleSHA + `","commit":{"committer":{"date":"2026-11-09T09:16:32Z"}}}`)) + case p == "/raw/planetscale/terraform-provider-planetscale/"+planetscaleSHA+"/schemas/openapi.yaml" && spec != "": + w.Write([]byte(spec)) + default: + http.Error(w, "404: Not Found", http.StatusNotFound) + } + })) + t.Cleanup(srv.Close) + return PlanetScale{APIBase: srv.URL + "/api", RawBase: srv.URL + "/raw"} +} + +func TestPlanetScaleLatestTagIsTheNewestSpecCommit(t *testing.T) { + p := fakePlanetScaleGitHub(t, `[{"sha":"`+planetscaleSHA+`"},{"sha":"older"}]`, "") + tag, err := p.LatestTag(context.Background()) + if err != nil || tag != planetscaleSHA { + t.Errorf("got %q, %v; want %s", tag, err, planetscaleSHA) + } + p = fakePlanetScaleGitHub(t, `[]`, "") + if _, err := p.LatestTag(context.Background()); err == nil { + t.Error("no commit: want an error") + } +} + +// The version is the commit's date, since the API has none (info.version is +// a fixed v1); the source is pinned to the full SHA even when a short one is +// asked for; the YAML becomes JSON with its values unchanged. +func TestPlanetScaleFetchPinsTheFullSHAAndDatesByCommit(t *testing.T) { + const spec = "openapi: 3.0.1\ninfo:\n version: v1\npaths:\n /organizations:\n get:\n description: |-\n Deprecated. Use x instead.\n responses:\n \"200\":\n description: OK\n" + p := fakePlanetScaleGitHub(t, "", spec) + got, err := p.Fetch(context.Background(), "fc13e09d") + if err != nil { + t.Fatal(err) + } + if want := p.RawBase + "/planetscale/terraform-provider-planetscale/" + planetscaleSHA + "/schemas/openapi.yaml"; got.Version != "2026-11-09" || got.SourceURL != want { + t.Errorf("got version %q, url %s", got.Version, got.SourceURL) + } + var doc struct { + Paths map[string]map[string]struct { + Description string `json:"description"` + } `json:"paths"` + } + if err := json.Unmarshal(got.Content, &doc); err != nil || doc.Paths["/organizations"]["get"].Description != "Deprecated. Use x instead." { + t.Errorf("content %s (%v)", got.Content, err) + } +} + +// A file that isn't a spec fails the fetch: diffed, it would read as every +// operation removed. The commit that deleted the file (f33a0c3b35) answers +// 404; a stub served 200 has no paths. +func TestPlanetScaleFetchRefusesWhatIsntASpec(t *testing.T) { + for name, body := range map[string]string{ + "deleted (404)": "", + "404 stub": "404: Not Found", + "no paths": "openapi: 3.0.1\ninfo:\n version: v1\n", + "empty paths": "openapi: 3.0.1\npaths: {}\n", + "not yaml": "openapi: [3.0.1\n", + "a yaml scalar": "Not Found", + "html error": "Not Found", + "paths a string": "openapi: 3.0.1\npaths: none\n", + } { + p := fakePlanetScaleGitHub(t, "", body) + if _, err := p.Fetch(context.Background(), planetscaleSHA); err == nil { + t.Errorf("%s: want an error", name) + } + } + p := fakePlanetScaleGitHub(t, "", "openapi: 3.0.1\npaths:\n /x:\n get: {}\n") + if _, err := p.Fetch(context.Background(), "0000000"); err == nil { + t.Error("unknown commit: want an error") + } +} diff --git a/docs/plugins.json b/docs/plugins.json index a54ff56..2d05a54 100644 --- a/docs/plugins.json +++ b/docs/plugins.json @@ -1,7 +1,7 @@ { "_comment": "Generated from the plugin registry and docs/plugins.md by `make plugins-json` (go run ./cmd/list-plugins). Don't edit by hand.", "$schema": "./plugins.schema.json", - "count": 24, + "count": 25, "plugins": [ { "id": "algolia-ingestion", @@ -153,6 +153,16 @@ "status": "live", "provider_page": "providers/openai-models.md" }, + { + "id": "planetscale", + "provider": "PlanetScale", + "layer": "api", + "watches": "API operations deprecated, and deprecated operations removed, between commits of the spec, said in the operation's description", + "format": "openapi", + "source_url": "https://github.com/planetscale/terraform-provider-planetscale", + "status": "live", + "provider_page": "providers/planetscale.md" + }, { "id": "posthog", "provider": "PostHog", diff --git a/docs/plugins.md b/docs/plugins.md index 5797161..baee347 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -20,6 +20,7 @@ The table between the `plugins:start` and `plugins:end` markers is also publishe | [`algolia-recommend`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/algolia.md) | Algolia | API | Recommend API operations deprecated, and deprecated operations removed, between releases of the spec | `openapi` | [algolia/api-clients-automation](https://github.com/algolia/api-clients-automation) (`specs/bundled/recommend.yml`) | live | | [`elasticsearch`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/elasticsearch.md) | Elastic | API | Elasticsearch REST API operations deprecated, and deprecated operations removed, between released minor versions of the spec | `openapi` | [elastic/elasticsearch-specification](https://github.com/elastic/elasticsearch-specification) (`output/openapi/elasticsearch-openapi.json`) | live | | [`sentry`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/sentry.md) | Sentry | API | REST API operations deprecated between releases of the spec, most of them in the operation's description | `openapi` | [getsentry/sentry releases](https://github.com/getsentry/sentry/releases) (`openapi-derefed.json` on each `api@` release) | live | +| [`planetscale`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/planetscale.md) | PlanetScale | API | API operations deprecated, and deprecated operations removed, between commits of the spec, said in the operation's description | `openapi` | [planetscale/terraform-provider-planetscale](https://github.com/planetscale/terraform-provider-planetscale) (`schemas/openapi.yaml`) | live | | [`mongodb-atlas`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/mongodb-atlas.md) | MongoDB | API | Atlas Administration API versions deprecated and removed at their sunset date, per endpoint, from MongoDB's own API changelog | `apichangelog` | [mongodb/openapi `changelog/changelog.json`](https://github.com/mongodb/openapi/blob/main/changelog/changelog.json) | live | | [`openai-models`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/openai-models.md) | OpenAI | AI models | Model deprecations and shutdown dates (Chat Completions and Responses text models) | `retirements` | [OpenAI deprecations](https://developers.openai.com/api/docs/deprecations) | live | | [`anthropic-models`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/anthropic-models.md) | Anthropic | AI models | Model deprecations and retirement dates (Messages API models) | `retirements` | [Anthropic model deprecations](https://platform.claude.com/docs/en/about-claude/model-deprecations) | live | diff --git a/plugins/openapi/openapi.go b/plugins/openapi/openapi.go index 2ff5f48..3f8bfb6 100644 --- a/plugins/openapi/openapi.go +++ b/plugins/openapi/openapi.go @@ -1,6 +1,6 @@ // Package openapi is the source plugin for an API that publishes an OpenAPI // spec per release (Stripe, Datadog, GitLab, GitHub, Vercel, Supabase, -// Algolia, Elasticsearch, Sentry): fetch the newest spec, diff it against the +// Algolia, Elasticsearch, Sentry, PlanetScale): fetch the newest spec, diff it against the // last one seen, normalize the changes into events, and attach migration // hints from the API's changelog when it has one. It can also replay two // given releases. @@ -49,6 +49,10 @@ func init() { // Operation deprecations only, most said in the description: see // sentry.go. plugin.Register(Plugin{Adapter: adapter.Sentry{}, Diff: sentryDiff, Keep: sentryKeep}) + // No Hints: PlanetScale's changelog is product news, not keyed by + // operation. Operation deprecations only, said in the description: see + // planetscale.go. + plugin.Register(Plugin{Adapter: adapter.PlanetScale{}, Diff: planetscaleDiff, Keep: planetscaleKeep}) } // requestSide keeps the changes to what callers send. GitLab's response diff --git a/plugins/openapi/planetscale.go b/plugins/openapi/planetscale.go new file mode 100644 index 0000000..a922223 --- /dev/null +++ b/plugins/openapi/planetscale.go @@ -0,0 +1,49 @@ +package openapi + +import ( + "regexp" + + "github.com/patch-it-dev/patch-it-plugins/diff" +) + +// planetscaleDiff is how the PlanetScale API spec says what it says: +// +// - Deprecations are only in the description's first words, "Deprecated. +// Use GET /organizations/:organization/databases/:database/branches/:branch/change-requests +// instead.": the spec has never set the `deprecated` flag (none in any +// of the 32 versions of schemas/openapi.yaml in +// planetscale/terraform-provider-planetscale, 2025-11-11 to 2026-11-09, +// nor in the live https://planetscale.com/docs/openapi.yaml on +// 2026-11-19). If it ever does, the operation is quoted whole, so the +// words come with it. +// - Path parameters get renamed, and that isn't a change for callers. +var planetscaleDiff = diff.Options{PathTemplates: true, QuoteDeprecatedOperation: true, DeprecatedDescription: planetscaleDeprecatedDescription} + +// planetscaleDeprecatedWords is the way every deprecation in the history is +// written: the description starts "Deprecated." (the others start with what +// the operation does, or with an empty line, then "### Authorization"). Only +// at the start, +// so not a description that mentions deprecation further on; and with the +// period or a colon, so not "Deprecated, storage shrinking is part of +// storage autoscaling.", which the spec writes on properties. +var planetscaleDeprecatedWords = regexp.MustCompile(`(?i)^\s*deprecated[.:]`) + +func planetscaleDeprecatedDescription(description string) bool { + return planetscaleDeprecatedWords.MatchString(description) +} + +// planetscaleKeep keeps operation deprecations, and removals of operations +// the old spec had marked deprecated. Over the 31 consecutive pairs of the +// spec's history that's 5 events, all on 2026-11-09 (fc13e09d): GET and +// DELETE .../bouncers/{bouncer}/resizes, GET .../neki-changes, GET and +// DELETE .../neki-changes/{id}. Everything else is dropped: +// +// - 41 operations left the spec, none deprecated first. 6 of them, on +// 2026-10-03, were the read-only replica operations renamed to +// dedicated read replicas, and planetscale/planetscale-go still sends +// the old paths ("the deprecated read-only-replicas path", main on +// 2026-11-19): left the spec isn't stopped working. +// - Property changes and new operations, as for vercel: 226 type changes +// on 2025-12-06 alone, when the spec switched whole numbers to +// `integer`. +var planetscaleKeep = deprecationsOnly(planetscaleDiff) diff --git a/plugins/openapi/planetscale_test.go b/plugins/openapi/planetscale_test.go new file mode 100644 index 0000000..fd7bfbd --- /dev/null +++ b/plugins/openapi/planetscale_test.go @@ -0,0 +1,175 @@ +package openapi + +import ( + "context" + "encoding/json" + "fmt" + "net/http" + "net/http/httptest" + "strings" + "testing" + + "github.com/patch-it-dev/patch-it-plugins/adapter" + "github.com/patch-it-dev/patch-it-plugins/diff" + "github.com/patch-it-dev/patch-it-plugins/event" + "github.com/patch-it-dev/patch-it-plugins/kit/kittest" +) + +// planetscaleCommits are the planetscale/terraform-provider-planetscale +// commits whose schemas/openapi.yaml is saved under testdata/ (trimmed to the +// paths involved, every line unchanged; checked 2026-11-19), with their +// committer dates. +var planetscaleCommits = map[string]string{ + "b49c354080667638b79781801f0517ae07bc55b8": "2026-09-10T14:52:36Z", + "f6d6ad4d3929f6c1ef021eb13c1541ba31f72107": "2026-10-03T00:53:38Z", + "e631095aa649a6797578a1d51d861b91e0568aa1": "2026-10-23T08:19:59Z", + "fc13e09d0c18b893aabd3e02d175d13957bba677": "2026-11-09T09:16:32Z", +} + +const planetscaleRaw = "https://raw.githubusercontent.com/planetscale/terraform-provider-planetscale" + +func planetscaleFile(sha string) string { return "testdata/planetscale-" + sha[:8] + ".yaml" } + +// planetscalePlugin is the plugin as registered, its adapter reading GitHub's +// answers and the saved copies from a local server. It returns the base the +// spec URLs start with in place of planetscaleRaw. +func planetscalePlugin(t *testing.T) (Plugin, string) { + t.Helper() + const repo = "/planetscale/terraform-provider-planetscale" + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + p := r.URL.Path + if sha, ok := strings.CutPrefix(p, "/api/repos"+repo+"/commits/"); ok && planetscaleCommits[sha] != "" { + fmt.Fprintf(w, `{"sha":%q,"commit":{"committer":{"date":%q}}}`, sha, planetscaleCommits[sha]) + return + } + if rest, ok := strings.CutPrefix(p, "/raw"+repo+"/"); ok { + sha, file, _ := strings.Cut(rest, "/") + if planetscaleCommits[sha] != "" && file == "schemas/openapi.yaml" { + http.ServeFile(w, r, planetscaleFile(sha)) + return + } + } + http.NotFound(w, r) + })) + t.Cleanup(srv.Close) + a := adapter.PlanetScale{APIBase: srv.URL + "/api", RawBase: srv.URL + "/raw"} + return Plugin{Adapter: a, Diff: planetscaleDiff, Keep: planetscaleKeep}, srv.URL + "/raw" + repo +} + +func replayPlanetScale(t *testing.T, p Plugin, from, to string) []event.EventV2 { + t.Helper() + s := openStore(t) + if rejected, err := kittest.Replay(context.Background(), vercelEnv(s), s, p, from, to); err != nil || rejected { + t.Fatalf("replay %s -> %s: rejected=%v err=%v", from, to, rejected, err) + } + return kittest.Stored(t, s) +} + +// The golden test: the only deprecations in the spec's history. On +// 2026-11-09 (fc13e09d) five operations' descriptions gained a first line +// "Deprecated. Use ... instead.", pointing at the change-requests +// endpoints: GET and DELETE .../bouncers/{bouncer}/resizes, GET +// .../neki-changes, GET and DELETE .../neki-changes/{id}. The flag was never +// set, so each event cites the description. +func TestPlanetScaleGolden(t *testing.T) { + p, base := planetscalePlugin(t) + const from, to = "e631095aa649a6797578a1d51d861b91e0568aa1", "fc13e09d0c18b893aabd3e02d175d13957bba677" + events := replayPlanetScale(t, p, from, to) + const branch = "/organizations/{organization}/databases/{database}/branches/{branch}" + want := map[string]bool{ + "GET " + branch + "/bouncers/{bouncer}/resizes": true, + "DELETE " + branch + "/bouncers/{bouncer}/resizes": true, + "GET " + branch + "/neki-changes": true, + "GET " + branch + "/neki-changes/{id}": true, + "DELETE " + branch + "/neki-changes/{id}": true, + } + if len(events) != len(want) { + for _, e := range events { + t.Logf("got: %s", e.Description) + } + t.Fatalf("%d events, want %d", len(events), len(want)) + } + for _, e := range events { + if !want[e.Subject.Operation] { + t.Errorf("unexpected event %s", e.Subject.Operation) + } + if e.ChangeType != event.ChangeTypeDeprecation || e.Version != "2026-11-09" || !strings.HasSuffix(e.SourcePointer, "/description") { + t.Errorf("%s: %s %s citing %s", e.Subject.Operation, e.ChangeType, e.Version, e.SourcePointer) + } + if url := base + "/" + to + "/schemas/openapi.yaml"; e.SourceURL != url { + t.Errorf("%s: source_url %s, want %s", e.Subject.Operation, e.SourceURL, url) + } + if node := yamlNodeJSON(t, planetscaleFile(to), e.SourcePointer); node != e.SourceExcerpt && !truncated(e.SourceExcerpt, node) { + t.Errorf("%s: excerpt doesn't match %s#%s", e.Subject.Operation, planetscaleFile(to), e.SourcePointer) + } + var description string + if err := json.Unmarshal([]byte(e.SourceExcerpt), &description); err != nil { + description = strings.TrimPrefix(e.SourceExcerpt, `"`) + } + if !strings.HasPrefix(description, "Deprecated. Use ") { + t.Errorf("%s: the excerpt doesn't start with PlanetScale's words: %.80s", e.Subject.Operation, e.SourceExcerpt) + } + } + // The golden file cites GitHub, where the local server stood in for it. + for i := range events { + events[i].SourceURL = strings.Replace(events[i].SourceURL, base, planetscaleRaw, 1) + } + kittest.Golden(t, "testdata/golden/planetscale.json", events) +} + +// The pinned drop test. On 2026-10-03 (f6d6ad4d) the read-only replica +// operations left the spec, without being deprecated first, as dedicated +// read replica operations arrived at new paths; PATCH +// .../configuration-profiles/{configuration_profile}/extensions/{extension} +// left too. planetscale/planetscale-go still sends .../read-only-replicas +// (main, 2026-11-19), so leaving the spec isn't a shutdown: no event. The +// same pair unfiltered reports the 7 removals. +func TestPlanetScaleDropsRemovalsThatWerentDeprecated(t *testing.T) { + p, _ := planetscalePlugin(t) + const from, to = "b49c354080667638b79781801f0517ae07bc55b8", "f6d6ad4d3929f6c1ef021eb13c1541ba31f72107" + if events := replayPlanetScale(t, p, from, to); len(events) != 0 { + t.Fatalf("%d events, want none: %s", len(events), events[0].Description) + } + p.Keep = nil + var removed []string + for _, e := range replayPlanetScale(t, p, from, to) { + if e.Breaking && e.Subject.Kind == event.AffectedKindOperation && strings.HasSuffix(e.Description, " removed.") { + removed = append(removed, e.Subject.Operation) + } + } + var replicas int + for _, op := range removed { + if strings.Contains(op, "/read-only-replica") { + replicas++ + } + } + if len(removed) != 7 || replicas != 6 { + t.Errorf("unfiltered: removed %v, want the 6 read-only replica operations and PATCH .../extensions/{extension}", removed) + } +} + +// The words, against the ways the spec writes "deprecated". +func TestPlanetScaleDeprecatedWords(t *testing.T) { + for desc, want := range map[string]bool{ + "Deprecated. Use GET /organizations/:organization/databases/:database/branches/:branch/change-requests instead.\n### Authorization": true, + "\nDeprecated: use the change-requests endpoints.": true, + "\n### Authorization\nA service token or OAuth token must have at least one of the following access or scopes": false, + // How the spec describes a deprecated property, not an operation. + "Deprecated, storage shrinking is part of storage autoscaling.": false, + "Returns deprecated branches too.": false, + "Lists changes.\n\nDeprecated. Use the change-requests endpoints.": false, + } { + if got := planetscaleDeprecatedDescription(desc); got != want { + t.Errorf("%.60q: got %v, want %v", desc, got, want) + } + } + if !planetscaleDiff.OperationDeprecated(map[string]any{"description": "Deprecated. Use x instead."}) { + t.Error("planetscaleDiff doesn't read the description") + } + // A removal is kept only of an operation marked deprecated first. + marked := diff.Change{Kind: diff.OperationRemoved, Node: map[string]any{"description": "Deprecated. Use x instead."}} + unmarked := diff.Change{Kind: diff.OperationRemoved, Node: map[string]any{"description": "\n### Authorization"}} + if !planetscaleKeep(marked) || planetscaleKeep(unmarked) { + t.Error("planetscaleKeep: want the marked removal only") + } +} diff --git a/plugins/openapi/registered_test.go b/plugins/openapi/registered_test.go index 107e8fc..1b137b1 100644 --- a/plugins/openapi/registered_test.go +++ b/plugins/openapi/registered_test.go @@ -8,7 +8,7 @@ import ( ) func TestRegistersItself(t *testing.T) { - for _, a := range []adapter.Adapter{adapter.Stripe{}, adapter.Datadog{}, adapter.GitLab{}, adapter.GitHub{}, adapter.Vercel{}, adapter.Supabase{}, adapter.Algolia{Spec: "search"}, adapter.Algolia{Spec: "ingestion"}, adapter.Algolia{Spec: "recommend"}, adapter.Elasticsearch{}, adapter.Sentry{}} { + for _, a := range []adapter.Adapter{adapter.Stripe{}, adapter.Datadog{}, adapter.GitLab{}, adapter.GitHub{}, adapter.Vercel{}, adapter.Supabase{}, adapter.Algolia{Spec: "search"}, adapter.Algolia{Spec: "ingestion"}, adapter.Algolia{Spec: "recommend"}, adapter.Elasticsearch{}, adapter.Sentry{}, adapter.PlanetScale{}} { kittest.Registered(t, Plugin{Adapter: a}) } } diff --git a/plugins/openapi/testdata/README.md b/plugins/openapi/testdata/README.md index 64df17c..167a8fa 100644 --- a/plugins/openapi/testdata/README.md +++ b/plugins/openapi/testdata/README.md @@ -28,6 +28,8 @@ Each pair is a real breaking change between two releases of a provider's own spe | `sentry-2.0.1.json`, `sentry-2.1.0.json` | https://raw.githubusercontent.com/getsentry/sentry-api-schema/2.0.1/openapi-derefed.json (and `2.1.0`) | 2026-11-19 | FSL-1.1-Apache-2.0 (getsentry/sentry-api-schema; the spec's own `info.license` says Apache 2.0) | `"url": "https://{region}.sentry.io"` and `"/api/0/organizations/": {` (in `2.0.1`), `"url": "https://{region}.sentry.io/api/0"` and `"/organizations/": {` (in `2.1.0`): the drop test | | `sentry-94bc6e59.json`, `sentry-d15557ff.json` | https://raw.githubusercontent.com/getsentry/sentry-api-schema/94bc6e593eaf8a3800341abd429d2949895926fd/openapi-derefed.json (and `d15557ff7472748887043ab8a72687b20214a9bd`) | 2026-11-19 | Apache 2.0 (the spec's own `info.license`; getsentry/sentry-api-schema had no license file before 2026-02-10) | "**Eventsv2 Deprecation Note**: Users who may be using the `eventsv2` endpoint should update their requests to the `events` endpoint" (`GET .../events/`, new in `d15557ff`; not a deprecation of it) | | `sentry-e8ec23b4.json`, `sentry-1ef7f21a.json` | https://raw.githubusercontent.com/getsentry/sentry-api-schema/e8ec23b4c9601dea2d51205983ec1d7b89550b85/openapi-derefed.json (and `1ef7f21a0501fae9490d69e3ae29f0d5acbfb61c`) | 2026-11-19 | FSL-1.1-Apache-2.0 (getsentry/sentry-api-schema; the spec's own `info.license` says Apache 2.0) | "a brief description, examples, and deprecation details." (`GET .../trace-items/attributes/`, new in `1ef7f21a`; not a deprecation) | +| `planetscale-e631095a.yaml`, `planetscale-fc13e09d.yaml` | https://raw.githubusercontent.com/planetscale/terraform-provider-planetscale/e631095aa649a6797578a1d51d861b91e0568aa1/schemas/openapi.yaml (and `fc13e09d0c18b893aabd3e02d175d13957bba677`) | 2026-11-19 | none stated for the file (its `info` says "© 2026 PlanetScale, Inc."); the repo, planetscale/terraform-provider-planetscale, is Apache-2.0. Excerpt for testing; © PlanetScale | "Deprecated. Use GET /organizations/:organization/databases/:database/branches/:branch/change-requests instead." (`GET .../neki-changes`, new in `fc13e09d`) | +| `planetscale-b49c3540.yaml`, `planetscale-f6d6ad4d.yaml` | https://raw.githubusercontent.com/planetscale/terraform-provider-planetscale/b49c354080667638b79781801f0517ae07bc55b8/schemas/openapi.yaml (and `f6d6ad4d3929f6c1ef021eb13c1541ba31f72107`) | 2026-11-19 | none stated for the file (its `info` says "© 2026 PlanetScale, Inc."); the repo, planetscale/terraform-provider-planetscale, is Apache-2.0. Excerpt for testing; © PlanetScale | `/organizations/{organization}/databases/{database}/branches/{branch}/read-only-replicas:` (in `b49c3540`, never deprecated, gone in `f6d6ad4d`, where `.../dedicated-read-replicas:` is): the drop test | The Elasticsearch copies keep `openapi`, `info` and the paths involved, every line unchanged; the 9.2 copy's paths are all gone in 9.2, so its `"paths": {}` is the one line that isn't in the original. @@ -37,4 +39,6 @@ The Supabase copies keep each value unchanged but are re-indented: the source is The Sentry copies keep `openapi`, `info`, `servers` and the path items involved, whole, in their original order except that `servers` comes before `paths`, every line copied unchanged (bar the trailing comma after a path item that's now last); `components` and `tags` left out. Each pair gives the same events as the full files, with the filter and with the variants the tests use (flag only, "deprecat" anywhere). The tests serve them as GitHub would, with each commit's date and each tag's release date. +The PlanetScale copies are trimmed by lines: everything before `paths:` (`openapi`, `info`), then the path items involved, whole, every line copied unchanged; the other paths, `servers` and `components` left out. The file states no license, so only what the tests need is kept. The golden pair gives the full files' 5 deprecations (their only ones), the drop-test pair their 7 removals (their only ones). The tests serve them as GitHub would, with each commit's date. + Stripe's spec isn't saved here: its tests use small specs written inline. diff --git a/plugins/openapi/testdata/golden/planetscale.json b/plugins/openapi/testdata/golden/planetscale.json new file mode 100644 index 0000000..1a01e66 --- /dev/null +++ b/plugins/openapi/testdata/golden/planetscale.json @@ -0,0 +1,107 @@ +[ + { + "id": 1, + "fingerprint": "sha256:bb73b6dc4cc2b725576e42b174f0b4026ad3db2db5931c6c924a7e034b2af6fd", + "api": "planetscale", + "version": "2026-11-09", + "previous_version": "2026-10-23", + "change_type": "deprecation", + "breaking": false, + "subject": { + "type": "api_operation", + "kind": "operation", + "side": "request", + "operation": "DELETE /organizations/{organization}/databases/{database}/branches/{branch}/bouncers/{bouncer}/resizes" + }, + "description": "Operation DELETE /organizations/{organization}/databases/{database}/branches/{branch}/bouncers/{bouncer}/resizes marked deprecated.", + "source_url": "https://raw.githubusercontent.com/planetscale/terraform-provider-planetscale/fc13e09d0c18b893aabd3e02d175d13957bba677/schemas/openapi.yaml", + "source_pointer": "/paths/~1organizations~1{organization}~1databases~1{database}~1branches~1{branch}~1bouncers~1{bouncer}~1resizes/delete/description", + "source_excerpt": "\"Deprecated. Use DELETE /organizations/:organization/databases/:database/branches/:branch/change-requests/:id to cancel individual change requests instead.\\n### Authorization\\nA service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:\\n\\n**Service Token Accesses**\\n `write_database`\\n\\n**OAuth Scopes**\\n\\n | Resource | Scopes |\\n| :------- | :---------- |\\n| Organization | `write_databases` |\\n| Database | `write_database` |\"", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 2, + "fingerprint": "sha256:c3f56d94e9021c1551e70ebf19a3b79cee197ff14e6cc698956c616df9e70fa9", + "api": "planetscale", + "version": "2026-11-09", + "previous_version": "2026-10-23", + "change_type": "deprecation", + "breaking": false, + "subject": { + "type": "api_operation", + "kind": "operation", + "side": "request", + "operation": "GET /organizations/{organization}/databases/{database}/branches/{branch}/bouncers/{bouncer}/resizes" + }, + "description": "Operation GET /organizations/{organization}/databases/{database}/branches/{branch}/bouncers/{bouncer}/resizes marked deprecated.", + "source_url": "https://raw.githubusercontent.com/planetscale/terraform-provider-planetscale/fc13e09d0c18b893aabd3e02d175d13957bba677/schemas/openapi.yaml", + "source_pointer": "/paths/~1organizations~1{organization}~1databases~1{database}~1branches~1{branch}~1bouncers~1{bouncer}~1resizes/get/description", + "source_excerpt": "\"Deprecated. Use GET /organizations/:organization/databases/:database/branches/:branch/change-requests with target_types[]=PostgresBouncer and target_id set to the bouncer ID instead.\\n### Authorization\\nA service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:\\n\\n**Service Token Accesses**\\n `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`\\n\\n**OAuth Scopes**\\n\\n | Resource | Scopes |\\n| :------- | :---------- |\\n| Organization | `read_branches` |\\n| Database | `read_branches` |\\n| Branch | `read_branch` |\"", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 3, + "fingerprint": "sha256:47eeb436d218d1d807fff05931826ac1f7e299bd2f55bde2affa1a92a296845e", + "api": "planetscale", + "version": "2026-11-09", + "previous_version": "2026-10-23", + "change_type": "deprecation", + "breaking": false, + "subject": { + "type": "api_operation", + "kind": "operation", + "side": "request", + "operation": "GET /organizations/{organization}/databases/{database}/branches/{branch}/neki-changes" + }, + "description": "Operation GET /organizations/{organization}/databases/{database}/branches/{branch}/neki-changes marked deprecated.", + "source_url": "https://raw.githubusercontent.com/planetscale/terraform-provider-planetscale/fc13e09d0c18b893aabd3e02d175d13957bba677/schemas/openapi.yaml", + "source_pointer": "/paths/~1organizations~1{organization}~1databases~1{database}~1branches~1{branch}~1neki-changes/get/description", + "source_excerpt": "\"Deprecated. Use GET /organizations/:organization/databases/:database/branches/:branch/change-requests instead.\\n### Authorization\\nA service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:\\n\\n**Service Token Accesses**\\n `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`\\n\\n**OAuth Scopes**\\n\\n | Resource | Scopes |\\n| :------- | :---------- |\\n| Organization | `read_branches` |\\n| Database | `read_branches` |\\n| Branch | `read_branch` |\"", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 4, + "fingerprint": "sha256:b3379ec5a0f3643259c8d5837a1db84f1d6c25b8eefa6c1e5cff162699a2b034", + "api": "planetscale", + "version": "2026-11-09", + "previous_version": "2026-10-23", + "change_type": "deprecation", + "breaking": false, + "subject": { + "type": "api_operation", + "kind": "operation", + "side": "request", + "operation": "DELETE /organizations/{organization}/databases/{database}/branches/{branch}/neki-changes/{id}" + }, + "description": "Operation DELETE /organizations/{organization}/databases/{database}/branches/{branch}/neki-changes/{id} marked deprecated.", + "source_url": "https://raw.githubusercontent.com/planetscale/terraform-provider-planetscale/fc13e09d0c18b893aabd3e02d175d13957bba677/schemas/openapi.yaml", + "source_pointer": "/paths/~1organizations~1{organization}~1databases~1{database}~1branches~1{branch}~1neki-changes~1{id}/delete/description", + "source_excerpt": "\"Deprecated. Use DELETE /organizations/:organization/databases/:database/branches/:branch/change-requests/:id instead.\\n### Authorization\\nA service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:\\n\\n**Service Token Accesses**\\n `write_database`\\n\\n**OAuth Scopes**\\n\\n | Resource | Scopes |\\n| :------- | :---------- |\\n| Organization | `write_databases` |\\n| Database | `write_database` |\"", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 5, + "fingerprint": "sha256:37f00e6877570c39686695e667ed1f5259da9424df9d48610b093149caa56a38", + "api": "planetscale", + "version": "2026-11-09", + "previous_version": "2026-10-23", + "change_type": "deprecation", + "breaking": false, + "subject": { + "type": "api_operation", + "kind": "operation", + "side": "request", + "operation": "GET /organizations/{organization}/databases/{database}/branches/{branch}/neki-changes/{id}" + }, + "description": "Operation GET /organizations/{organization}/databases/{database}/branches/{branch}/neki-changes/{id} marked deprecated.", + "source_url": "https://raw.githubusercontent.com/planetscale/terraform-provider-planetscale/fc13e09d0c18b893aabd3e02d175d13957bba677/schemas/openapi.yaml", + "source_pointer": "/paths/~1organizations~1{organization}~1databases~1{database}~1branches~1{branch}~1neki-changes~1{id}/get/description", + "source_excerpt": "\"Deprecated. Use GET /organizations/:organization/databases/:database/branches/:branch/change-requests/:id instead.\\n### Authorization\\nA service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:\\n\\n**Service Token Accesses**\\n `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`\\n\\n**OAuth Scopes**\\n\\n | Resource | Scopes |\\n| :------- | :---------- |\\n| Organization | `read_branches` |\\n| Database | `read_branches` |\\n| Branch | `read_branch` |\"", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + } +] diff --git a/plugins/openapi/testdata/planetscale-b49c3540.yaml b/plugins/openapi/testdata/planetscale-b49c3540.yaml new file mode 100644 index 0000000..6c2015c --- /dev/null +++ b/plugins/openapi/testdata/planetscale-b49c3540.yaml @@ -0,0 +1,1745 @@ +openapi: 3.0.1 +info: + title: PlanetScale API + description: |- + +

PlanetScale API

+ © 2026 PlanetScale, Inc. + version: v1 + x-copyright: "© 2026 PlanetScale, Inc." +paths: + /organizations/{organization}/databases/{database}/branches/{branch}/configuration-profiles/{configuration_profile}/extensions/{extension}: + patch: + tags: + - api-neki_shard_configuration_profile_extensions + operationId: update_shard_configuration_profile_extension + summary: Enable or disable an extension for a Neki shard configuration profile + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + - name: configuration_profile + in: path + required: true + description: Name from `list_shard_configuration_profiles`. + schema: + type: string + - name: extension + in: path + required: true + description: The name of the extension + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + enabled: + type: boolean + description: Whether the extension should be enabled + required: + - enabled + responses: + "200": + description: Returns the updated extension + headers: {} + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The name of the extension + can_enable: + type: boolean + description: Whether the extension can be enabled or disabled by the configuration profile + description: + type: string + description: The description of the extension + enabled: + type: boolean + description: Whether the extension is enabled by the configuration profile + nullable: true + internal: + type: boolean + description: The internal state of the extension + parameters: + type: array + items: + type: object + properties: + name: + type: string + description: The name of the parameter + display_name: + type: string + description: The display name of the parameter + namespace: + type: string + enum: + - pgconf + - router + - sidecar + - admin + - replicator + description: The namespace of the parameter + advanced: + type: boolean + description: Whether the parameter is advanced + category: + type: string + description: The category of the parameter + nullable: true + description: + type: string + description: The description of the parameter + parameter_type: + type: string + enum: + - array + - boolean + - bytes + - float + - integer + - select + - string + - time + description: The type of the parameter + default_value: + type: string + description: The default value of the parameter + value: + type: string + description: The configured value of the parameter + required: + type: boolean + description: Whether the parameter is required + created_at: + type: string + description: When the parameter was created + updated_at: + type: string + description: When the parameter was last updated + restart: + type: boolean + description: Whether processes require a server restart after the parameter changes + max: + type: number + description: The maximum value of the parameter + nullable: true + min: + type: number + description: The minimum value of the parameter + nullable: true + options: + items: + type: string + type: array + description: Valid options for the parameter value + nullable: true + units: + items: + type: string + type: array + description: The units of the parameter value + nullable: true + url: + type: string + description: The URL of the parameter + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + required: + - name + - display_name + - namespace + - advanced + - category + - description + - parameter_type + - default_value + - value + - required + - created_at + - updated_at + - restart + - url + - actor + url: + type: string + description: The URL of the extension + required: + - name + - can_enable + - description + - internal + - parameters + - url + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Shard configuration profile or extension not found + headers: {} + "422": + description: Extension cannot be enabled or disabled + "500": + description: Internal Server Error + description: |- + + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `write_database` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `write_databases` | + | Database | `write_database` | + /organizations/{organization}/databases/{database}/branches/{branch}/read-only-replica-changes: + get: + tags: + - api-read_only_replica_changes + operationId: list_read_only_replica_change_requests + summary: Get read-only replica change requests + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + - name: page + in: query + description: If provided, specifies the page offset of returned results + schema: + type: integer + default: 1 + - name: per_page + in: query + description: If provided, specifies the number of returned results + schema: + type: integer + default: 25 + - name: period + in: query + description: Filter change requests by named period + schema: + type: string + enum: + - 15m + - 1h + - 3h + - 6h + - 12h + - 1d + - 2d + - 7d + - 8d + - name: completed_at + in: query + description: Filter change requests completed between two ISO 8601 timestamps + schema: + type: string + responses: + "200": + description: Returns read-only replica change requests + headers: {} + content: + application/json: + schema: + type: object + properties: + type: + type: string + description: The response type. Always "list" for paginated responses. + current_page: + type: integer + description: The current page number + per_page: + type: integer + description: The maximum number of results per page + next_page: + type: integer + description: The next page number, or null when this is the last page + nullable: true + next_page_url: + type: string + description: The next page of results, or null when this is the last page + nullable: true + prev_page: + type: integer + description: The previous page number, or null when this is the first page + nullable: true + prev_page_url: + type: string + description: The previous page of results, or null when this is the first page + nullable: true + data: + type: array + items: + type: object + properties: + id: + type: string + description: The ID of the read-only replica change request + state: + type: string + enum: + - pending + - resizing + - canceled + - completed + description: The state of the change request + cluster_name: + type: string + description: The new cluster size SKU + cluster_display_name: + type: string + description: The new cluster size for display + cluster_rank: + type: integer + description: The new cluster size sort order + replicas: + type: integer + description: The new instance count + parameters: + type: object + additionalProperties: true + description: The new parameters + previous_cluster_name: + type: string + description: The previous cluster size SKU + previous_cluster_display_name: + type: string + description: The previous cluster size for display + previous_cluster_rank: + type: integer + description: The previous cluster size sort order + previous_replicas: + type: integer + description: The previous instance count + previous_parameters: + type: object + additionalProperties: true + description: The previous parameters + started_at: + type: string + description: When the change started + nullable: true + completed_at: + type: string + description: When the change completed + nullable: true + created_at: + type: string + description: When the change request was created + updated_at: + type: string + description: When the change request was last updated + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + replica: + type: object + properties: + id: + type: string + description: The ID for the resource + name: + type: string + description: The name for the resource + created_at: + type: string + description: When the resource was created + updated_at: + type: string + description: When the resource was last updated + deleted_at: + type: string + description: When the resource was deleted, if deleted + nullable: true + required: + - id + - name + - created_at + - updated_at + - deleted_at + required: + - id + - state + - cluster_name + - cluster_display_name + - cluster_rank + - replicas + - parameters + - previous_cluster_name + - previous_cluster_display_name + - previous_cluster_rank + - previous_replicas + - previous_parameters + - started_at + - completed_at + - created_at + - updated_at + - actor + - replica + required: + - type + - current_page + - per_page + - next_page + - next_page_url + - prev_page + - prev_page_url + - data + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Not Found + "500": + description: Internal Server Error + description: |- + + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `read_branches` | + | Database | `read_branches` | + | Branch | `read_branch` | + /organizations/{organization}/databases/{database}/branches/{branch}/read-only-replicas: + get: + tags: + - Read-only replicas + operationId: list_read_only_replicas + summary: List read-only replicas + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + responses: + "200": + description: Returns read-only replicas + headers: {} + content: + application/json: + schema: + type: array + items: + type: object + properties: + id: + type: string + description: The ID of the read-only replica + name: + type: string + description: The name of the read-only replica + state: + type: string + description: "The state of the read-only replica: pending, ready, or deleting" + replicas: + type: integer + description: The number of instances serving reads in this read-only replica + cluster_name: + type: string + description: The SKU representing the cluster size of the read-only replica + cluster_display_name: + type: string + description: The SKU representing the cluster size of the read-only replica, for display + access_host_url: + type: string + description: The database connection host for the read-only replica + private_access_host_url: + type: string + description: The private database connection host for the read-only replica + private_connection_service_name: + type: string + description: The service name to set up private connectivity for the read-only replica + nullable: true + created_at: + type: string + description: When the read-only replica was created + updated_at: + type: string + description: When the read-only replica was last updated + ready_at: + type: string + description: When the read-only replica was ready to serve queries + nullable: true + ready: + type: boolean + description: Whether or not the read-only replica is ready to serve queries + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + region: + type: object + properties: + id: + type: string + description: The ID of the region + provider: + type: string + description: Provider for the region (ex. AWS) + enabled: + type: boolean + description: Whether or not the region is currently active + public_ip_addresses: + items: + type: string + type: array + description: Public IP addresses for the region + display_name: + type: string + description: Name of the region + location: + type: string + description: Location of the region + slug: + type: string + description: The slug of the region + current_default: + type: boolean + description: True if the region is the default for new branch creation + mysql_supported: + type: boolean + description: Whether the region supports MySQL/Vitess databases + postgresql_supported: + type: boolean + description: Whether the region supports PostgreSQL databases + required: + - id + - provider + - enabled + - public_ip_addresses + - display_name + - location + - slug + - current_default + - mysql_supported + - postgresql_supported + parameters: + type: array + items: + type: object + properties: + id: + type: string + description: The ID of the parameter + namespace: + type: string + enum: + - pgconf + description: The namespace of the parameter + name: + type: string + description: The name of the parameter + display_name: + type: string + description: The display name of the parameter + category: + type: string + description: The category of the parameter + description: + type: string + description: The description of the parameter + immutable: + type: boolean + description: Whether the parameter can be changed + parameter_type: + type: string + enum: + - integer + - time + description: The type of the parameter + default_value: + type: string + description: The default value of the parameter, which is the primary's current value + disabled_reason: + type: string + description: Why the parameter cannot be changed + nullable: true + value: + type: string + description: The configured value of the parameter + required: + type: boolean + description: Whether the parameter is required + created_at: + type: string + description: When the parameter was created + nullable: true + updated_at: + type: string + description: When the parameter was last updated + nullable: true + restart: + type: boolean + description: True if processes require a server restart on change + max: + type: number + description: The maximum value of the parameter + min: + type: number + description: The minimum value of the parameter, floored at the primary's current value + url: + type: string + description: The URL of the parameter + options: + items: + type: string + type: array + description: Valid options for the parameter value + units: + items: + type: string + type: array + description: Display units for the parameter value + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + required: + - id + - namespace + - name + - display_name + - category + - description + - immutable + - parameter_type + - default_value + - value + - required + - created_at + - updated_at + - restart + - max + - min + - url + - options + - units + - actor + required: + - id + - name + - state + - replicas + - cluster_name + - cluster_display_name + - access_host_url + - private_access_host_url + - private_connection_service_name + - created_at + - updated_at + - ready_at + - ready + - actor + - region + - parameters + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Not Found + "500": + description: Internal Server Error + description: |- + + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `read_branches` | + | Database | `read_branches` | + | Branch | `read_branch` | + post: + tags: + - Read-only replicas + operationId: create_read_only_replica + summary: Create a read-only replica + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The read-only replica name + region: + type: string + description: The region slug for the read-only replica + replicas: + type: integer + description: The number of instances serving reads. Defaults to 1. + cluster_size: + type: string + description: The cluster size SKU name. Defaults to the primary cluster size. + required: + - name + - region + responses: + "200": + description: Returns the new read-only replica + headers: {} + content: + application/json: + schema: + type: object + properties: + id: + type: string + description: The ID of the read-only replica + name: + type: string + description: The name of the read-only replica + state: + type: string + description: "The state of the read-only replica: pending, ready, or deleting" + replicas: + type: integer + description: The number of instances serving reads in this read-only replica + cluster_name: + type: string + description: The SKU representing the cluster size of the read-only replica + cluster_display_name: + type: string + description: The SKU representing the cluster size of the read-only replica, for display + access_host_url: + type: string + description: The database connection host for the read-only replica + private_access_host_url: + type: string + description: The private database connection host for the read-only replica + private_connection_service_name: + type: string + description: The service name to set up private connectivity for the read-only replica + nullable: true + created_at: + type: string + description: When the read-only replica was created + updated_at: + type: string + description: When the read-only replica was last updated + ready_at: + type: string + description: When the read-only replica was ready to serve queries + nullable: true + ready: + type: boolean + description: Whether or not the read-only replica is ready to serve queries + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + region: + type: object + properties: + id: + type: string + description: The ID of the region + provider: + type: string + description: Provider for the region (ex. AWS) + enabled: + type: boolean + description: Whether or not the region is currently active + public_ip_addresses: + items: + type: string + type: array + description: Public IP addresses for the region + display_name: + type: string + description: Name of the region + location: + type: string + description: Location of the region + slug: + type: string + description: The slug of the region + current_default: + type: boolean + description: True if the region is the default for new branch creation + mysql_supported: + type: boolean + description: Whether the region supports MySQL/Vitess databases + postgresql_supported: + type: boolean + description: Whether the region supports PostgreSQL databases + required: + - id + - provider + - enabled + - public_ip_addresses + - display_name + - location + - slug + - current_default + - mysql_supported + - postgresql_supported + parameters: + type: array + items: + type: object + properties: + id: + type: string + description: The ID of the parameter + namespace: + type: string + enum: + - pgconf + description: The namespace of the parameter + name: + type: string + description: The name of the parameter + display_name: + type: string + description: The display name of the parameter + category: + type: string + description: The category of the parameter + description: + type: string + description: The description of the parameter + immutable: + type: boolean + description: Whether the parameter can be changed + parameter_type: + type: string + enum: + - integer + - time + description: The type of the parameter + default_value: + type: string + description: The default value of the parameter, which is the primary's current value + disabled_reason: + type: string + description: Why the parameter cannot be changed + nullable: true + value: + type: string + description: The configured value of the parameter + required: + type: boolean + description: Whether the parameter is required + created_at: + type: string + description: When the parameter was created + nullable: true + updated_at: + type: string + description: When the parameter was last updated + nullable: true + restart: + type: boolean + description: True if processes require a server restart on change + max: + type: number + description: The maximum value of the parameter + min: + type: number + description: The minimum value of the parameter, floored at the primary's current value + url: + type: string + description: The URL of the parameter + options: + items: + type: string + type: array + description: Valid options for the parameter value + units: + items: + type: string + type: array + description: Display units for the parameter value + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + required: + - id + - namespace + - name + - display_name + - category + - description + - immutable + - parameter_type + - default_value + - value + - required + - created_at + - updated_at + - restart + - max + - min + - url + - options + - units + - actor + required: + - id + - name + - state + - replicas + - cluster_name + - cluster_display_name + - access_host_url + - private_access_host_url + - private_connection_service_name + - created_at + - updated_at + - ready_at + - ready + - actor + - region + - parameters + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Not Found + "500": + description: Internal Server Error + description: |- + + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `write_database` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `write_databases` | + | Database | `write_database` | + /organizations/{organization}/databases/{database}/branches/{branch}/read-only-replicas/{read_only_replica}: + get: + tags: + - Read-only replicas + operationId: get_read_only_replica + summary: Get a read-only replica + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + - name: read_only_replica + in: path + required: true + description: The name of the read-only replica + schema: + type: string + responses: + "200": + description: Returns the read-only replica + headers: {} + content: + application/json: + schema: + type: object + properties: + id: + type: string + description: The ID of the read-only replica + name: + type: string + description: The name of the read-only replica + state: + type: string + description: "The state of the read-only replica: pending, ready, or deleting" + replicas: + type: integer + description: The number of instances serving reads in this read-only replica + cluster_name: + type: string + description: The SKU representing the cluster size of the read-only replica + cluster_display_name: + type: string + description: The SKU representing the cluster size of the read-only replica, for display + access_host_url: + type: string + description: The database connection host for the read-only replica + private_access_host_url: + type: string + description: The private database connection host for the read-only replica + private_connection_service_name: + type: string + description: The service name to set up private connectivity for the read-only replica + nullable: true + created_at: + type: string + description: When the read-only replica was created + updated_at: + type: string + description: When the read-only replica was last updated + ready_at: + type: string + description: When the read-only replica was ready to serve queries + nullable: true + ready: + type: boolean + description: Whether or not the read-only replica is ready to serve queries + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + region: + type: object + properties: + id: + type: string + description: The ID of the region + provider: + type: string + description: Provider for the region (ex. AWS) + enabled: + type: boolean + description: Whether or not the region is currently active + public_ip_addresses: + items: + type: string + type: array + description: Public IP addresses for the region + display_name: + type: string + description: Name of the region + location: + type: string + description: Location of the region + slug: + type: string + description: The slug of the region + current_default: + type: boolean + description: True if the region is the default for new branch creation + mysql_supported: + type: boolean + description: Whether the region supports MySQL/Vitess databases + postgresql_supported: + type: boolean + description: Whether the region supports PostgreSQL databases + required: + - id + - provider + - enabled + - public_ip_addresses + - display_name + - location + - slug + - current_default + - mysql_supported + - postgresql_supported + parameters: + type: array + items: + type: object + properties: + id: + type: string + description: The ID of the parameter + namespace: + type: string + enum: + - pgconf + description: The namespace of the parameter + name: + type: string + description: The name of the parameter + display_name: + type: string + description: The display name of the parameter + category: + type: string + description: The category of the parameter + description: + type: string + description: The description of the parameter + immutable: + type: boolean + description: Whether the parameter can be changed + parameter_type: + type: string + enum: + - integer + - time + description: The type of the parameter + default_value: + type: string + description: The default value of the parameter, which is the primary's current value + disabled_reason: + type: string + description: Why the parameter cannot be changed + nullable: true + value: + type: string + description: The configured value of the parameter + required: + type: boolean + description: Whether the parameter is required + created_at: + type: string + description: When the parameter was created + nullable: true + updated_at: + type: string + description: When the parameter was last updated + nullable: true + restart: + type: boolean + description: True if processes require a server restart on change + max: + type: number + description: The maximum value of the parameter + min: + type: number + description: The minimum value of the parameter, floored at the primary's current value + url: + type: string + description: The URL of the parameter + options: + items: + type: string + type: array + description: Valid options for the parameter value + units: + items: + type: string + type: array + description: Display units for the parameter value + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + required: + - id + - namespace + - name + - display_name + - category + - description + - immutable + - parameter_type + - default_value + - value + - required + - created_at + - updated_at + - restart + - max + - min + - url + - options + - units + - actor + required: + - id + - name + - state + - replicas + - cluster_name + - cluster_display_name + - access_host_url + - private_access_host_url + - private_connection_service_name + - created_at + - updated_at + - ready_at + - ready + - actor + - region + - parameters + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Not Found + "500": + description: Internal Server Error + description: |- + + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `read_branches` | + | Database | `read_branches` | + | Branch | `read_branch` | + patch: + tags: + - Read-only replicas + operationId: update_read_only_replica + summary: Update a read-only replica + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + - name: read_only_replica + in: path + required: true + description: The name of the read-only replica + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + replicas: + type: integer + description: The number of instances serving reads + cluster_size: + type: string + description: The cluster size SKU name + parameters: + type: object + additionalProperties: true + description: "Configuration parameters nested by namespace (e.g., {\"pgconf\": {\"max_connections\": \"300\"}}). Values must be greater than or equal to the primary's." + responses: + "200": + description: Returns the updated read-only replica + headers: {} + content: + application/json: + schema: + type: object + properties: + id: + type: string + description: The ID of the read-only replica + name: + type: string + description: The name of the read-only replica + state: + type: string + description: "The state of the read-only replica: pending, ready, or deleting" + replicas: + type: integer + description: The number of instances serving reads in this read-only replica + cluster_name: + type: string + description: The SKU representing the cluster size of the read-only replica + cluster_display_name: + type: string + description: The SKU representing the cluster size of the read-only replica, for display + access_host_url: + type: string + description: The database connection host for the read-only replica + private_access_host_url: + type: string + description: The private database connection host for the read-only replica + private_connection_service_name: + type: string + description: The service name to set up private connectivity for the read-only replica + nullable: true + created_at: + type: string + description: When the read-only replica was created + updated_at: + type: string + description: When the read-only replica was last updated + ready_at: + type: string + description: When the read-only replica was ready to serve queries + nullable: true + ready: + type: boolean + description: Whether or not the read-only replica is ready to serve queries + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + region: + type: object + properties: + id: + type: string + description: The ID of the region + provider: + type: string + description: Provider for the region (ex. AWS) + enabled: + type: boolean + description: Whether or not the region is currently active + public_ip_addresses: + items: + type: string + type: array + description: Public IP addresses for the region + display_name: + type: string + description: Name of the region + location: + type: string + description: Location of the region + slug: + type: string + description: The slug of the region + current_default: + type: boolean + description: True if the region is the default for new branch creation + mysql_supported: + type: boolean + description: Whether the region supports MySQL/Vitess databases + postgresql_supported: + type: boolean + description: Whether the region supports PostgreSQL databases + required: + - id + - provider + - enabled + - public_ip_addresses + - display_name + - location + - slug + - current_default + - mysql_supported + - postgresql_supported + parameters: + type: array + items: + type: object + properties: + id: + type: string + description: The ID of the parameter + namespace: + type: string + enum: + - pgconf + description: The namespace of the parameter + name: + type: string + description: The name of the parameter + display_name: + type: string + description: The display name of the parameter + category: + type: string + description: The category of the parameter + description: + type: string + description: The description of the parameter + immutable: + type: boolean + description: Whether the parameter can be changed + parameter_type: + type: string + enum: + - integer + - time + description: The type of the parameter + default_value: + type: string + description: The default value of the parameter, which is the primary's current value + disabled_reason: + type: string + description: Why the parameter cannot be changed + nullable: true + value: + type: string + description: The configured value of the parameter + required: + type: boolean + description: Whether the parameter is required + created_at: + type: string + description: When the parameter was created + nullable: true + updated_at: + type: string + description: When the parameter was last updated + nullable: true + restart: + type: boolean + description: True if processes require a server restart on change + max: + type: number + description: The maximum value of the parameter + min: + type: number + description: The minimum value of the parameter, floored at the primary's current value + url: + type: string + description: The URL of the parameter + options: + items: + type: string + type: array + description: Valid options for the parameter value + units: + items: + type: string + type: array + description: Display units for the parameter value + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + required: + - id + - namespace + - name + - display_name + - category + - description + - immutable + - parameter_type + - default_value + - value + - required + - created_at + - updated_at + - restart + - max + - min + - url + - options + - units + - actor + required: + - id + - name + - state + - replicas + - cluster_name + - cluster_display_name + - access_host_url + - private_access_host_url + - private_connection_service_name + - created_at + - updated_at + - ready_at + - ready + - actor + - region + - parameters + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Not Found + "500": + description: Internal Server Error + description: |- + + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `write_database` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `write_databases` | + | Database | `write_database` | + delete: + tags: + - Read-only replicas + operationId: delete_read_only_replica + summary: Delete a read-only replica + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + - name: read_only_replica + in: path + required: true + description: The name of the read-only replica + schema: + type: string + responses: + "204": + description: Deletes the read-only replica + headers: {} + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Not Found + "500": + description: Internal Server Error + description: |- + + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `write_database` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `write_databases` | + | Database | `write_database` | diff --git a/plugins/openapi/testdata/planetscale-e631095a.yaml b/plugins/openapi/testdata/planetscale-e631095a.yaml new file mode 100644 index 0000000..9e738d8 --- /dev/null +++ b/plugins/openapi/testdata/planetscale-e631095a.yaml @@ -0,0 +1,1452 @@ +openapi: 3.0.1 +info: + title: PlanetScale API + description: |- + +

PlanetScale API

+ © 2026 PlanetScale, Inc. + version: v1 + x-copyright: "© 2026 PlanetScale, Inc." +paths: + /organizations/{organization}/databases/{database}/branches/{branch}/bouncers/{bouncer}/resizes: + get: + tags: + - Bouncer resizes + operationId: list_bouncer_resize_requests + summary: Get bouncer resize requests + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + - name: bouncer + in: path + required: true + description: The name of the bouncer + schema: + type: string + - name: page + in: query + description: If provided, specifies the page offset of returned results + schema: + type: integer + default: 1 + - name: per_page + in: query + description: If provided, specifies the number of returned results + schema: + type: integer + default: 25 + responses: + "200": + description: Returns bouncer resize requests + headers: {} + content: + application/json: + schema: + type: object + properties: + type: + type: string + description: The response type. Always "list" for paginated responses. + current_page: + type: integer + description: The current page number + per_page: + type: integer + description: The maximum number of results per page + next_page: + type: integer + description: The next page number, or null when this is the last page + nullable: true + next_page_url: + type: string + description: The next page of results, or null when this is the last page + nullable: true + prev_page: + type: integer + description: The previous page number, or null when this is the first page + nullable: true + prev_page_url: + type: string + description: The previous page of results, or null when this is the first page + nullable: true + data: + type: array + items: + type: object + properties: + id: + type: string + description: The ID of the bouncer resize + state: + type: string + enum: + - pending + - resizing + - canceled + - completed + description: The state of the bouncer resize + replicas_per_cell: + type: integer + description: The number of replicas per cell for the bouncer after the resize + target: + type: string + enum: + - primary + - replica + - replica_az_affinity + description: The backend target for the bouncer after the resize + parameters: + type: object + additionalProperties: true + description: The bouncer parameters + previous_replicas_per_cell: + type: integer + description: The number of replicas per cell for the bouncer before the resize + previous_target: + type: string + enum: + - primary + - replica + - replica_az_affinity + description: The backend target for the bouncer before the resize + previous_parameters: + type: object + additionalProperties: true + description: The previous bouncer parameters + started_at: + type: string + description: The time the bouncer resize started + nullable: true + completed_at: + type: string + description: The time the bouncer resize completed + nullable: true + created_at: + type: string + description: The time the bouncer resize was created + updated_at: + type: string + description: The time the bouncer resize was last updated + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + bouncer: + type: object + properties: + id: + type: string + description: The ID for the resource + name: + type: string + description: The name for the resource + created_at: + type: string + description: When the resource was created + updated_at: + type: string + description: When the resource was last updated + deleted_at: + type: string + description: When the resource was deleted, if deleted + nullable: true + required: + - id + - name + - created_at + - updated_at + - deleted_at + sku: + type: object + properties: + name: + type: string + description: The name of the Postgres bouncer SKU + display_name: + type: string + description: The display name + cpu: + type: string + description: The CPU allocation + ram: + type: integer + description: The amount of memory in bytes + sort_order: + type: integer + description: The sort order of the Postgres bouncer SKU + required: + - name + - display_name + - cpu + - ram + - sort_order + previous_sku: + type: object + properties: + name: + type: string + description: The name of the Postgres bouncer SKU + display_name: + type: string + description: The display name + cpu: + type: string + description: The CPU allocation + ram: + type: integer + description: The amount of memory in bytes + sort_order: + type: integer + description: The sort order of the Postgres bouncer SKU + required: + - name + - display_name + - cpu + - ram + - sort_order + required: + - id + - state + - replicas_per_cell + - target + - parameters + - previous_replicas_per_cell + - previous_target + - previous_parameters + - started_at + - completed_at + - created_at + - updated_at + - actor + - bouncer + - sku + - previous_sku + required: + - type + - current_page + - per_page + - next_page + - next_page_url + - prev_page + - prev_page_url + - data + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Not Found + "422": + description: Unprocessable Entity + "429": + description: Too Many Requests. Reduce the frequency of requests and try again soon. + "500": + description: Internal Server Error + description: |- + + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `read_branches` | + | Database | `read_branches` | + | Branch | `read_branch` | + patch: + tags: + - Bouncer resizes + operationId: update_bouncer_resize_request + summary: Upsert a bouncer resize request + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + - name: bouncer + in: path + required: true + description: The name of the bouncer + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + bouncer_size: + type: string + description: The bouncer size SKU name (e.g., 'PGB_5', 'PGB_10', 'PGB_20', 'PGB_40', 'PGB_80', 'PGB_160'). Defaults to 'PGB_5'. + replicas_per_cell: + type: integer + description: The number of PgBouncers per availability zone. Defaults to 1. + target: + type: string + description: The type of server the bouncer targets. + parameters: + type: object + additionalProperties: true + description: "Bouncer configuration parameters nested by namespace (e.g., {\"pgbouncer\": {\"default_pool_size\": \"100\"}}). Use the 'List cluster parameters' endpoint to retrieve available parameters. Only parameters with namespace 'pgbouncer' can be updated." + responses: + "200": + description: Returns bouncer resize request + headers: {} + content: + application/json: + schema: + type: object + properties: + id: + type: string + description: The ID of the bouncer resize + state: + type: string + enum: + - pending + - resizing + - canceled + - completed + description: The state of the bouncer resize + replicas_per_cell: + type: integer + description: The number of replicas per cell for the bouncer after the resize + target: + type: string + enum: + - primary + - replica + - replica_az_affinity + description: The backend target for the bouncer after the resize + parameters: + type: object + additionalProperties: true + description: The bouncer parameters + previous_replicas_per_cell: + type: integer + description: The number of replicas per cell for the bouncer before the resize + previous_target: + type: string + enum: + - primary + - replica + - replica_az_affinity + description: The backend target for the bouncer before the resize + previous_parameters: + type: object + additionalProperties: true + description: The previous bouncer parameters + started_at: + type: string + description: The time the bouncer resize started + nullable: true + completed_at: + type: string + description: The time the bouncer resize completed + nullable: true + created_at: + type: string + description: The time the bouncer resize was created + updated_at: + type: string + description: The time the bouncer resize was last updated + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + bouncer: + type: object + properties: + id: + type: string + description: The ID for the resource + name: + type: string + description: The name for the resource + created_at: + type: string + description: When the resource was created + updated_at: + type: string + description: When the resource was last updated + deleted_at: + type: string + description: When the resource was deleted, if deleted + nullable: true + required: + - id + - name + - created_at + - updated_at + - deleted_at + sku: + type: object + properties: + name: + type: string + description: The name of the Postgres bouncer SKU + display_name: + type: string + description: The display name + cpu: + type: string + description: The CPU allocation + ram: + type: integer + description: The amount of memory in bytes + sort_order: + type: integer + description: The sort order of the Postgres bouncer SKU + required: + - name + - display_name + - cpu + - ram + - sort_order + previous_sku: + type: object + properties: + name: + type: string + description: The name of the Postgres bouncer SKU + display_name: + type: string + description: The display name + cpu: + type: string + description: The CPU allocation + ram: + type: integer + description: The amount of memory in bytes + sort_order: + type: integer + description: The sort order of the Postgres bouncer SKU + required: + - name + - display_name + - cpu + - ram + - sort_order + required: + - id + - state + - replicas_per_cell + - target + - parameters + - previous_replicas_per_cell + - previous_target + - previous_parameters + - started_at + - completed_at + - created_at + - updated_at + - actor + - bouncer + - sku + - previous_sku + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Not Found + "422": + description: Invalid parameters + "429": + description: Too Many Requests. Reduce the frequency of requests and try again soon. + "500": + description: Internal Server Error + description: |- + + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `write_database` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `write_databases` | + | Database | `write_database` | + delete: + tags: + - Bouncer resizes + operationId: cancel_bouncer_resize_request + summary: Cancel a resize request + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + - name: bouncer + in: path + required: true + description: The name of the bouncer + schema: + type: string + responses: + "204": + description: Cancels a resize request + headers: {} + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Not Found + "422": + description: Unprocessable Entity + "429": + description: Too Many Requests. Reduce the frequency of requests and try again soon. + "500": + description: Internal Server Error + description: |- + + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `write_database` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `write_databases` | + | Database | `write_database` | + /organizations/{organization}/databases/{database}/branches/{branch}/neki-changes: + get: + tags: + - api-neki_changes + operationId: list_neki_change_requests + summary: List change requests for a Neki branch + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + - name: page + in: query + description: If provided, specifies the page offset of returned results + schema: + type: integer + default: 1 + - name: per_page + in: query + description: If provided, specifies the number of returned results + schema: + type: integer + default: 25 + - name: state + in: query + description: Filter change requests by state + style: form + explode: false + schema: + type: array + items: + type: string + - name: target_types + in: query + description: "Filter change requests by target type. Must contain one or more of: NekiAdmin, NekiCluster, NekiConfigurationProfile, NekiExternalShard, or NekiRouter" + style: form + explode: false + schema: + type: array + items: + type: string + - name: target_id + in: query + description: Filter change requests for one target. Requires exactly one target type + schema: + type: string + - name: period + in: query + description: Filter change requests by named period + schema: + type: string + enum: + - 15m + - 1h + - 3h + - 6h + - 12h + - 1d + - 2d + - 7d + - 8d + - name: completed_at + in: query + description: Filter change requests completed between two ISO 8601 timestamps + schema: + type: string + responses: + "200": + description: Returns Neki change requests + headers: {} + content: + application/json: + schema: + type: object + properties: + type: + type: string + description: The response type. Always "list" for paginated responses. + current_page: + type: integer + description: The current page number + per_page: + type: integer + description: The maximum number of results per page + next_page: + type: integer + description: The next page number, or null when this is the last page + nullable: true + next_page_url: + type: string + description: The next page of results, or null when this is the last page + nullable: true + prev_page: + type: integer + description: The previous page number, or null when this is the first page + nullable: true + prev_page_url: + type: string + description: The previous page of results, or null when this is the first page + nullable: true + data: + type: array + items: + type: object + properties: + type: + type: string + enum: + - NekiAdminChangeRequest + - NekiClusterChangeRequest + - NekiConfigurationProfileChangeRequest + - NekiExternalShardChangeRequest + - NekiRouterChangeRequest + description: The type of change request + id: + type: string + description: The ID of the change request + state: + type: string + enum: + - draft + - pending + - applying + - canceled + - completed + description: The state of the change request + can_delete: + type: boolean + description: Whether the change request can be deleted + started_at: + type: string + description: The time the change request started + nullable: true + completed_at: + type: string + description: The time the change request completed + nullable: true + created_at: + type: string + description: The time the change request was created + updated_at: + type: string + description: The time the change request was last updated + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + target_id: + type: string + description: The ID of the resource being changed + nullable: true + target_type: + type: string + enum: + - NekiAdmin + - NekiCluster + - NekiConfigurationProfile + - NekiExternalShard + - NekiRouter + description: The type of resource being changed + target_name: + type: string + description: The name of the resource being changed + admin_size: + type: string + description: The name of the admin size SKU + nullable: true + admin_size_display_name: + type: string + description: The display name of the admin size SKU + nullable: true + parameters: + type: object + additionalProperties: true + description: The parameters requested for the target resource + nullable: true + previous_admin_size: + type: string + description: The previous name of the admin size SKU + nullable: true + previous_admin_size_display_name: + type: string + description: The previous display name of the admin size SKU + nullable: true + previous_parameters: + type: object + additionalProperties: true + description: The target resource parameters before the change + nullable: true + replicas: + type: integer + description: The number of replicas + nullable: true + previous_replicas: + type: integer + description: The previous number of replicas + nullable: true + cluster_name: + type: string + description: The SKU representing the external sidecar size + nullable: true + cluster_display_name: + type: string + description: The display name of the cluster size SKU + nullable: true + previous_cluster_name: + type: string + description: The SKU representing the previous external sidecar size + nullable: true + previous_cluster_display_name: + type: string + description: The previous display name of the cluster size SKU + nullable: true + router_size: + type: string + description: The name of the router size SKU + nullable: true + router_size_display_name: + type: string + description: The display name of the router size SKU + nullable: true + replicas_per_cell: + type: integer + description: The number of replicas in each cell + nullable: true + autoscaling: + type: boolean + description: Whether the router scales horizontally within each cell + nullable: true + max_replicas_per_cell: + type: integer + description: The maximum number of replicas in each cell when autoscaling + nullable: true + target_cpu_utilization: + type: integer + description: The target average CPU utilization percentage when autoscaling, one of 40, 50, 60 or 70 + nullable: true + previous_router_size: + type: string + description: The previous name of the router size SKU + nullable: true + previous_router_size_display_name: + type: string + description: The previous display name of the router size SKU + nullable: true + previous_replicas_per_cell: + type: integer + description: The previous number of replicas in each cell + nullable: true + previous_autoscaling: + type: boolean + description: The previous autoscaling state of the router + nullable: true + previous_max_replicas_per_cell: + type: integer + description: The previous maximum number of replicas in each cell + nullable: true + previous_target_cpu_utilization: + type: integer + description: The previous target average CPU utilization percentage + nullable: true + name: + type: string + description: The name of the configuration profile + nullable: true + previous_name: + type: string + description: The previous name of the configuration profile + nullable: true + cluster_size: + type: string + description: The name of the cluster size SKU + nullable: true + metal: + type: boolean + description: Whether the cluster size SKU uses metal instances + nullable: true + cluster_rank: + type: integer + description: The display order of the cluster size SKU + nullable: true + shards: + type: integer + description: The number of shards + nullable: true + postgres_image_version: + type: string + description: The PostgreSQL image + nullable: true + storage: + type: object + properties: + minimum_storage_bytes: + type: integer + description: The minimum storage size in bytes + nullable: true + maximum_storage_bytes: + type: integer + description: The maximum storage size in bytes for autoscaling + nullable: true + storage_autoscaling: + type: boolean + description: Whether storage autoscaling is enabled + nullable: true + storage_iops: + type: integer + description: The storage IOPS + nullable: true + storage_throughput_mibs: + type: integer + description: The storage throughput in MiB/s + nullable: true + required: + - minimum_storage_bytes + - maximum_storage_bytes + - storage_autoscaling + - storage_iops + - storage_throughput_mibs + nullable: true + previous_cluster_size: + type: string + description: The previous name of the cluster size SKU + nullable: true + previous_metal: + type: boolean + description: Whether the previous cluster size SKU used metal instances + nullable: true + previous_cluster_rank: + type: integer + description: The previous display order of the cluster size SKU + nullable: true + previous_shards: + type: integer + description: The previous number of shards + nullable: true + previous_postgres_image_version: + type: string + description: The previous PostgreSQL image + nullable: true + previous_storage: + type: object + properties: + minimum_storage_bytes: + type: integer + description: The minimum storage size in bytes + nullable: true + maximum_storage_bytes: + type: integer + description: The maximum storage size in bytes for autoscaling + nullable: true + storage_autoscaling: + type: boolean + description: Whether storage autoscaling is enabled + nullable: true + storage_iops: + type: integer + description: The storage IOPS + nullable: true + storage_throughput_mibs: + type: integer + description: The storage throughput in MiB/s + nullable: true + required: + - minimum_storage_bytes + - maximum_storage_bytes + - storage_autoscaling + - storage_iops + - storage_throughput_mibs + nullable: true + required: + - type + - id + - state + - can_delete + - started_at + - completed_at + - created_at + - updated_at + - actor + - target_id + - target_type + - target_name + required: + - type + - current_page + - per_page + - next_page + - next_page_url + - prev_page + - prev_page_url + - data + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Not Found + "422": + description: Unprocessable Entity + "429": + description: Too Many Requests. Reduce the frequency of requests and try again soon. + "500": + description: Internal Server Error + description: |- + + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `read_branches` | + | Database | `read_branches` | + | Branch | `read_branch` | + /organizations/{organization}/databases/{database}/branches/{branch}/neki-changes/{id}: + get: + tags: + - api-neki_changes + operationId: get_neki_change_request + summary: Get a change request for a Neki branch + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + - name: id + in: path + required: true + description: The ID of the change request + schema: + type: string + responses: + "200": + description: Returns a Neki change request + headers: {} + content: + application/json: + schema: + type: object + properties: + type: + type: string + enum: + - NekiAdminChangeRequest + - NekiClusterChangeRequest + - NekiConfigurationProfileChangeRequest + - NekiExternalShardChangeRequest + - NekiRouterChangeRequest + description: The type of change request + id: + type: string + description: The ID of the change request + state: + type: string + enum: + - draft + - pending + - applying + - canceled + - completed + description: The state of the change request + can_delete: + type: boolean + description: Whether the change request can be deleted + started_at: + type: string + description: The time the change request started + nullable: true + completed_at: + type: string + description: The time the change request completed + nullable: true + created_at: + type: string + description: The time the change request was created + updated_at: + type: string + description: The time the change request was last updated + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + target_id: + type: string + description: The ID of the resource being changed + nullable: true + target_type: + type: string + enum: + - NekiAdmin + - NekiCluster + - NekiConfigurationProfile + - NekiExternalShard + - NekiRouter + description: The type of resource being changed + target_name: + type: string + description: The name of the resource being changed + admin_size: + type: string + description: The name of the admin size SKU + nullable: true + admin_size_display_name: + type: string + description: The display name of the admin size SKU + nullable: true + parameters: + type: object + additionalProperties: true + description: The parameters requested for the target resource + nullable: true + previous_admin_size: + type: string + description: The previous name of the admin size SKU + nullable: true + previous_admin_size_display_name: + type: string + description: The previous display name of the admin size SKU + nullable: true + previous_parameters: + type: object + additionalProperties: true + description: The target resource parameters before the change + nullable: true + replicas: + type: integer + description: The number of replicas + nullable: true + previous_replicas: + type: integer + description: The previous number of replicas + nullable: true + cluster_name: + type: string + description: The SKU representing the external sidecar size + nullable: true + cluster_display_name: + type: string + description: The display name of the cluster size SKU + nullable: true + previous_cluster_name: + type: string + description: The SKU representing the previous external sidecar size + nullable: true + previous_cluster_display_name: + type: string + description: The previous display name of the cluster size SKU + nullable: true + router_size: + type: string + description: The name of the router size SKU + nullable: true + router_size_display_name: + type: string + description: The display name of the router size SKU + nullable: true + replicas_per_cell: + type: integer + description: The number of replicas in each cell + nullable: true + autoscaling: + type: boolean + description: Whether the router scales horizontally within each cell + nullable: true + max_replicas_per_cell: + type: integer + description: The maximum number of replicas in each cell when autoscaling + nullable: true + target_cpu_utilization: + type: integer + description: The target average CPU utilization percentage when autoscaling, one of 40, 50, 60 or 70 + nullable: true + previous_router_size: + type: string + description: The previous name of the router size SKU + nullable: true + previous_router_size_display_name: + type: string + description: The previous display name of the router size SKU + nullable: true + previous_replicas_per_cell: + type: integer + description: The previous number of replicas in each cell + nullable: true + previous_autoscaling: + type: boolean + description: The previous autoscaling state of the router + nullable: true + previous_max_replicas_per_cell: + type: integer + description: The previous maximum number of replicas in each cell + nullable: true + previous_target_cpu_utilization: + type: integer + description: The previous target average CPU utilization percentage + nullable: true + name: + type: string + description: The name of the configuration profile + nullable: true + previous_name: + type: string + description: The previous name of the configuration profile + nullable: true + cluster_size: + type: string + description: The name of the cluster size SKU + nullable: true + metal: + type: boolean + description: Whether the cluster size SKU uses metal instances + nullable: true + cluster_rank: + type: integer + description: The display order of the cluster size SKU + nullable: true + shards: + type: integer + description: The number of shards + nullable: true + postgres_image_version: + type: string + description: The PostgreSQL image + nullable: true + storage: + type: object + properties: + minimum_storage_bytes: + type: integer + description: The minimum storage size in bytes + nullable: true + maximum_storage_bytes: + type: integer + description: The maximum storage size in bytes for autoscaling + nullable: true + storage_autoscaling: + type: boolean + description: Whether storage autoscaling is enabled + nullable: true + storage_iops: + type: integer + description: The storage IOPS + nullable: true + storage_throughput_mibs: + type: integer + description: The storage throughput in MiB/s + nullable: true + required: + - minimum_storage_bytes + - maximum_storage_bytes + - storage_autoscaling + - storage_iops + - storage_throughput_mibs + nullable: true + previous_cluster_size: + type: string + description: The previous name of the cluster size SKU + nullable: true + previous_metal: + type: boolean + description: Whether the previous cluster size SKU used metal instances + nullable: true + previous_cluster_rank: + type: integer + description: The previous display order of the cluster size SKU + nullable: true + previous_shards: + type: integer + description: The previous number of shards + nullable: true + previous_postgres_image_version: + type: string + description: The previous PostgreSQL image + nullable: true + previous_storage: + type: object + properties: + minimum_storage_bytes: + type: integer + description: The minimum storage size in bytes + nullable: true + maximum_storage_bytes: + type: integer + description: The maximum storage size in bytes for autoscaling + nullable: true + storage_autoscaling: + type: boolean + description: Whether storage autoscaling is enabled + nullable: true + storage_iops: + type: integer + description: The storage IOPS + nullable: true + storage_throughput_mibs: + type: integer + description: The storage throughput in MiB/s + nullable: true + required: + - minimum_storage_bytes + - maximum_storage_bytes + - storage_autoscaling + - storage_iops + - storage_throughput_mibs + nullable: true + required: + - type + - id + - state + - can_delete + - started_at + - completed_at + - created_at + - updated_at + - actor + - target_id + - target_type + - target_name + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Change request not found + headers: {} + "422": + description: Unprocessable Entity + "429": + description: Too Many Requests. Reduce the frequency of requests and try again soon. + "500": + description: Internal Server Error + description: |- + + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `read_branches` | + | Database | `read_branches` | + | Branch | `read_branch` | + delete: + tags: + - api-neki_changes + operationId: cancel_neki_change_request + summary: Cancel a change request for a Neki branch + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + - name: id + in: path + required: true + description: The ID of the change request + schema: + type: string + responses: + "204": + description: Change request canceled + headers: {} + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Change request not found + headers: {} + "422": + description: Change request cannot be canceled + "429": + description: Too Many Requests. Reduce the frequency of requests and try again soon. + "500": + description: Internal Server Error + description: |- + + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `write_database` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `write_databases` | + | Database | `write_database` | diff --git a/plugins/openapi/testdata/planetscale-f6d6ad4d.yaml b/plugins/openapi/testdata/planetscale-f6d6ad4d.yaml new file mode 100644 index 0000000..2d4ee76 --- /dev/null +++ b/plugins/openapi/testdata/planetscale-f6d6ad4d.yaml @@ -0,0 +1,1828 @@ +openapi: 3.0.1 +info: + title: PlanetScale API + description: |- + +

PlanetScale API

+ © 2026 PlanetScale, Inc. + version: v1 + x-copyright: "© 2026 PlanetScale, Inc." +paths: + /organizations/{organization}/databases/{database}/branches/{branch}/dedicated-read-replica-changes: + get: + tags: + - api-read_only_replica_changes + operationId: list_dedicated_read_replica_change_requests + summary: Get dedicated read replica change requests + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + - name: page + in: query + description: If provided, specifies the page offset of returned results + schema: + type: integer + default: 1 + - name: per_page + in: query + description: If provided, specifies the number of returned results + schema: + type: integer + default: 25 + - name: period + in: query + description: Filter change requests by named period + schema: + type: string + enum: + - 15m + - 1h + - 3h + - 6h + - 12h + - 1d + - 2d + - 7d + - 8d + - name: completed_at + in: query + description: Filter change requests completed between two ISO 8601 timestamps + schema: + type: string + responses: + "200": + description: Returns dedicated read replica change requests + headers: {} + content: + application/json: + schema: + type: object + properties: + type: + type: string + description: The response type. Always "list" for paginated responses. + current_page: + type: integer + description: The current page number + per_page: + type: integer + description: The maximum number of results per page + next_page: + type: integer + description: The next page number, or null when this is the last page + nullable: true + next_page_url: + type: string + description: The next page of results, or null when this is the last page + nullable: true + prev_page: + type: integer + description: The previous page number, or null when this is the first page + nullable: true + prev_page_url: + type: string + description: The previous page of results, or null when this is the first page + nullable: true + data: + type: array + items: + type: object + properties: + id: + type: string + description: The ID of the dedicated read replica change request + state: + type: string + enum: + - pending + - resizing + - canceled + - completed + description: The state of the change request + cluster_name: + type: string + description: The new cluster size SKU + cluster_display_name: + type: string + description: The new cluster size for display + cluster_rank: + type: integer + description: The new cluster size sort order + replicas: + type: integer + description: The new instance count + parameters: + type: object + additionalProperties: true + description: The new parameters + minimum_storage_bytes: + type: integer + description: The new minimum storage size in bytes + nullable: true + maximum_storage_bytes: + type: integer + description: The new maximum storage size in bytes + nullable: true + storage_autoscaling: + type: boolean + description: Whether storage autoscaling is enabled + nullable: true + storage_type: + type: string + enum: + - gp3 + - io2 + - pd_ssd + - hyperdisk_balanced + - premium_v2_lrs + description: The new storage type + nullable: true + storage_iops: + type: integer + description: The new storage IOPS + nullable: true + storage_throughput_mibs: + type: integer + description: The new storage throughput in MiB/s + nullable: true + previous_cluster_name: + type: string + description: The previous cluster size SKU + previous_cluster_display_name: + type: string + description: The previous cluster size for display + previous_cluster_rank: + type: integer + description: The previous cluster size sort order + previous_replicas: + type: integer + description: The previous instance count + previous_parameters: + type: object + additionalProperties: true + description: The previous parameters + previous_minimum_storage_bytes: + type: integer + description: The previous minimum storage size in bytes + nullable: true + previous_maximum_storage_bytes: + type: integer + description: The previous maximum storage size in bytes + nullable: true + previous_storage_autoscaling: + type: boolean + description: Whether storage autoscaling was previously enabled + nullable: true + previous_storage_type: + type: string + description: The previous storage type + nullable: true + previous_storage_iops: + type: integer + description: The previous storage IOPS + nullable: true + previous_storage_throughput_mibs: + type: integer + description: The previous storage throughput in MiB/s + nullable: true + started_at: + type: string + description: When the change started + nullable: true + completed_at: + type: string + description: When the change completed + nullable: true + created_at: + type: string + description: When the change request was created + updated_at: + type: string + description: When the change request was last updated + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + replica: + type: object + properties: + id: + type: string + description: The ID for the resource + name: + type: string + description: The name for the resource + created_at: + type: string + description: When the resource was created + updated_at: + type: string + description: When the resource was last updated + deleted_at: + type: string + description: When the resource was deleted, if deleted + nullable: true + required: + - id + - name + - created_at + - updated_at + - deleted_at + required: + - id + - state + - cluster_name + - cluster_display_name + - cluster_rank + - replicas + - parameters + - minimum_storage_bytes + - maximum_storage_bytes + - storage_autoscaling + - storage_type + - storage_iops + - storage_throughput_mibs + - previous_cluster_name + - previous_cluster_display_name + - previous_cluster_rank + - previous_replicas + - previous_parameters + - previous_minimum_storage_bytes + - previous_maximum_storage_bytes + - previous_storage_autoscaling + - previous_storage_type + - previous_storage_iops + - previous_storage_throughput_mibs + - started_at + - completed_at + - created_at + - updated_at + - actor + - replica + required: + - type + - current_page + - per_page + - next_page + - next_page_url + - prev_page + - prev_page_url + - data + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Not Found + "422": + description: Unprocessable Entity + "429": + description: Too Many Requests. Reduce the frequency of requests and try again soon. + "500": + description: Internal Server Error + description: |- + + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `read_branches` | + | Database | `read_branches` | + | Branch | `read_branch` | + /organizations/{organization}/databases/{database}/branches/{branch}/dedicated-read-replicas: + get: + tags: + - Dedicated read replicas + operationId: list_dedicated_read_replicas + summary: List dedicated read replicas + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + responses: + "200": + description: Returns dedicated read replicas + headers: {} + content: + application/json: + schema: + type: array + items: + type: object + properties: + id: + type: string + description: The ID of the dedicated read replica + name: + type: string + description: The name of the dedicated read replica + state: + type: string + description: "The state of the dedicated read replica: pending, ready, or deleting" + replicas: + type: integer + description: The number of instances serving reads in this dedicated read replica + cluster_name: + type: string + description: The SKU representing the cluster size of the dedicated read replica + cluster_display_name: + type: string + description: The SKU representing the cluster size of the dedicated read replica, for display + access_host_url: + type: string + description: The database connection host for the dedicated read replica + private_access_host_url: + type: string + description: The private database connection host for the dedicated read replica + private_connection_service_name: + type: string + description: The service name to set up private connectivity for the dedicated read replica + nullable: true + minimum_storage_bytes: + type: integer + description: The minimum storage size in bytes + nullable: true + maximum_storage_bytes: + type: integer + description: The maximum storage size in bytes + nullable: true + storage_autoscaling: + type: boolean + description: Whether storage autoscaling is enabled + nullable: true + storage_type: + type: string + enum: + - gp3 + - io2 + - pd_ssd + - hyperdisk_balanced + - premium_v2_lrs + description: The storage type + nullable: true + storage_iops: + type: integer + description: The storage IOPS + nullable: true + storage_throughput_mibs: + type: integer + description: The storage throughput in MiB/s + nullable: true + volume_modifications_blocked_until: + type: string + description: When volume modifications will be allowed again + nullable: true + created_at: + type: string + description: When the dedicated read replica was created + updated_at: + type: string + description: When the dedicated read replica was last updated + ready_at: + type: string + description: When the dedicated read replica was ready to serve queries + nullable: true + ready: + type: boolean + description: Whether or not the dedicated read replica is ready to serve queries + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + region: + type: object + properties: + id: + type: string + description: The ID of the region + provider: + type: string + description: Provider for the region (ex. AWS) + enabled: + type: boolean + description: Whether or not the region is currently active + public_ip_addresses: + items: + type: string + type: array + description: Public IP addresses for the region + display_name: + type: string + description: Name of the region + location: + type: string + description: Location of the region + slug: + type: string + description: The slug of the region + current_default: + type: boolean + description: True if the region is the default for new branch creation + mysql_supported: + type: boolean + description: Whether the region supports MySQL/Vitess databases + postgresql_supported: + type: boolean + description: Whether the region supports PostgreSQL databases + neki_supported: + type: boolean + description: Whether the region supports Neki databases + required: + - id + - provider + - enabled + - public_ip_addresses + - display_name + - location + - slug + - current_default + - mysql_supported + - postgresql_supported + - neki_supported + parameters: + type: array + items: + type: object + properties: + id: + type: string + description: The ID of the parameter + namespace: + type: string + enum: + - pgconf + description: The namespace of the parameter + name: + type: string + description: The name of the parameter + display_name: + type: string + description: The display name of the parameter + category: + type: string + description: The category of the parameter + description: + type: string + description: The description of the parameter + immutable: + type: boolean + description: Whether the parameter can be changed + parameter_type: + type: string + enum: + - integer + - time + description: The type of the parameter + default_value: + type: string + description: The default value of the parameter, which is the primary's current value + disabled_reason: + type: string + description: Why the parameter cannot be changed + nullable: true + value: + type: string + description: The configured value of the parameter + required: + type: boolean + description: Whether the parameter is required + created_at: + type: string + description: When the parameter was created + nullable: true + updated_at: + type: string + description: When the parameter was last updated + nullable: true + restart: + type: boolean + description: True if processes require a server restart on change + max: + type: number + description: The maximum value of the parameter + min: + type: number + description: The minimum value of the parameter, floored at the primary's current value + url: + type: string + description: The URL of the parameter + options: + items: + type: string + type: array + description: Valid options for the parameter value + units: + items: + type: string + type: array + description: Display units for the parameter value + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + required: + - id + - namespace + - name + - display_name + - category + - description + - immutable + - parameter_type + - default_value + - value + - required + - created_at + - updated_at + - restart + - max + - min + - url + - options + - units + - actor + required: + - id + - name + - state + - replicas + - cluster_name + - cluster_display_name + - access_host_url + - private_access_host_url + - private_connection_service_name + - minimum_storage_bytes + - maximum_storage_bytes + - storage_autoscaling + - storage_type + - storage_iops + - storage_throughput_mibs + - volume_modifications_blocked_until + - created_at + - updated_at + - ready_at + - ready + - actor + - region + - parameters + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Not Found + "422": + description: Unprocessable Entity + "429": + description: Too Many Requests. Reduce the frequency of requests and try again soon. + "500": + description: Internal Server Error + description: |- + + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `read_branches` | + | Database | `read_branches` | + | Branch | `read_branch` | + post: + tags: + - Dedicated read replicas + operationId: create_dedicated_read_replica + summary: Create a dedicated read replica + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The dedicated read replica name + region: + type: string + description: The region slug for the dedicated read replica + replicas: + type: integer + description: The number of instances serving reads. Defaults to 1. + cluster_size: + type: string + description: The cluster size SKU name. Defaults to the primary cluster size. + storage: + type: object + properties: + minimum_storage_bytes: + type: integer + description: The minimum storage size in bytes. + maximum_storage_bytes: + type: integer + description: The maximum storage size in bytes for autoscaling. + storage_autoscaling: + type: boolean + description: Whether storage autoscaling is enabled. + storage_iops: + type: integer + description: The storage IOPS. + storage_throughput_mibs: + type: integer + description: The storage throughput in MiB/s. + required: + - name + - region + responses: + "200": + description: Returns the new dedicated read replica + headers: {} + content: + application/json: + schema: + type: object + properties: + id: + type: string + description: The ID of the dedicated read replica + name: + type: string + description: The name of the dedicated read replica + state: + type: string + description: "The state of the dedicated read replica: pending, ready, or deleting" + replicas: + type: integer + description: The number of instances serving reads in this dedicated read replica + cluster_name: + type: string + description: The SKU representing the cluster size of the dedicated read replica + cluster_display_name: + type: string + description: The SKU representing the cluster size of the dedicated read replica, for display + access_host_url: + type: string + description: The database connection host for the dedicated read replica + private_access_host_url: + type: string + description: The private database connection host for the dedicated read replica + private_connection_service_name: + type: string + description: The service name to set up private connectivity for the dedicated read replica + nullable: true + minimum_storage_bytes: + type: integer + description: The minimum storage size in bytes + nullable: true + maximum_storage_bytes: + type: integer + description: The maximum storage size in bytes + nullable: true + storage_autoscaling: + type: boolean + description: Whether storage autoscaling is enabled + nullable: true + storage_type: + type: string + enum: + - gp3 + - io2 + - pd_ssd + - hyperdisk_balanced + - premium_v2_lrs + description: The storage type + nullable: true + storage_iops: + type: integer + description: The storage IOPS + nullable: true + storage_throughput_mibs: + type: integer + description: The storage throughput in MiB/s + nullable: true + volume_modifications_blocked_until: + type: string + description: When volume modifications will be allowed again + nullable: true + created_at: + type: string + description: When the dedicated read replica was created + updated_at: + type: string + description: When the dedicated read replica was last updated + ready_at: + type: string + description: When the dedicated read replica was ready to serve queries + nullable: true + ready: + type: boolean + description: Whether or not the dedicated read replica is ready to serve queries + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + region: + type: object + properties: + id: + type: string + description: The ID of the region + provider: + type: string + description: Provider for the region (ex. AWS) + enabled: + type: boolean + description: Whether or not the region is currently active + public_ip_addresses: + items: + type: string + type: array + description: Public IP addresses for the region + display_name: + type: string + description: Name of the region + location: + type: string + description: Location of the region + slug: + type: string + description: The slug of the region + current_default: + type: boolean + description: True if the region is the default for new branch creation + mysql_supported: + type: boolean + description: Whether the region supports MySQL/Vitess databases + postgresql_supported: + type: boolean + description: Whether the region supports PostgreSQL databases + neki_supported: + type: boolean + description: Whether the region supports Neki databases + required: + - id + - provider + - enabled + - public_ip_addresses + - display_name + - location + - slug + - current_default + - mysql_supported + - postgresql_supported + - neki_supported + parameters: + type: array + items: + type: object + properties: + id: + type: string + description: The ID of the parameter + namespace: + type: string + enum: + - pgconf + description: The namespace of the parameter + name: + type: string + description: The name of the parameter + display_name: + type: string + description: The display name of the parameter + category: + type: string + description: The category of the parameter + description: + type: string + description: The description of the parameter + immutable: + type: boolean + description: Whether the parameter can be changed + parameter_type: + type: string + enum: + - integer + - time + description: The type of the parameter + default_value: + type: string + description: The default value of the parameter, which is the primary's current value + disabled_reason: + type: string + description: Why the parameter cannot be changed + nullable: true + value: + type: string + description: The configured value of the parameter + required: + type: boolean + description: Whether the parameter is required + created_at: + type: string + description: When the parameter was created + nullable: true + updated_at: + type: string + description: When the parameter was last updated + nullable: true + restart: + type: boolean + description: True if processes require a server restart on change + max: + type: number + description: The maximum value of the parameter + min: + type: number + description: The minimum value of the parameter, floored at the primary's current value + url: + type: string + description: The URL of the parameter + options: + items: + type: string + type: array + description: Valid options for the parameter value + units: + items: + type: string + type: array + description: Display units for the parameter value + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + required: + - id + - namespace + - name + - display_name + - category + - description + - immutable + - parameter_type + - default_value + - value + - required + - created_at + - updated_at + - restart + - max + - min + - url + - options + - units + - actor + required: + - id + - name + - state + - replicas + - cluster_name + - cluster_display_name + - access_host_url + - private_access_host_url + - private_connection_service_name + - minimum_storage_bytes + - maximum_storage_bytes + - storage_autoscaling + - storage_type + - storage_iops + - storage_throughput_mibs + - volume_modifications_blocked_until + - created_at + - updated_at + - ready_at + - ready + - actor + - region + - parameters + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Not Found + "422": + description: Unprocessable Entity + "429": + description: Too Many Requests. Reduce the frequency of requests and try again soon. + "500": + description: Internal Server Error + description: |- + + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `write_database` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `write_databases` | + | Database | `write_database` | + /organizations/{organization}/databases/{database}/branches/{branch}/dedicated-read-replicas/{dedicated_read_replica}: + get: + tags: + - Dedicated read replicas + operationId: get_dedicated_read_replica + summary: Get a dedicated read replica + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + - name: dedicated_read_replica + in: path + required: true + description: The name of the dedicated read replica + schema: + type: string + responses: + "200": + description: Returns the dedicated read replica + headers: {} + content: + application/json: + schema: + type: object + properties: + id: + type: string + description: The ID of the dedicated read replica + name: + type: string + description: The name of the dedicated read replica + state: + type: string + description: "The state of the dedicated read replica: pending, ready, or deleting" + replicas: + type: integer + description: The number of instances serving reads in this dedicated read replica + cluster_name: + type: string + description: The SKU representing the cluster size of the dedicated read replica + cluster_display_name: + type: string + description: The SKU representing the cluster size of the dedicated read replica, for display + access_host_url: + type: string + description: The database connection host for the dedicated read replica + private_access_host_url: + type: string + description: The private database connection host for the dedicated read replica + private_connection_service_name: + type: string + description: The service name to set up private connectivity for the dedicated read replica + nullable: true + minimum_storage_bytes: + type: integer + description: The minimum storage size in bytes + nullable: true + maximum_storage_bytes: + type: integer + description: The maximum storage size in bytes + nullable: true + storage_autoscaling: + type: boolean + description: Whether storage autoscaling is enabled + nullable: true + storage_type: + type: string + enum: + - gp3 + - io2 + - pd_ssd + - hyperdisk_balanced + - premium_v2_lrs + description: The storage type + nullable: true + storage_iops: + type: integer + description: The storage IOPS + nullable: true + storage_throughput_mibs: + type: integer + description: The storage throughput in MiB/s + nullable: true + volume_modifications_blocked_until: + type: string + description: When volume modifications will be allowed again + nullable: true + created_at: + type: string + description: When the dedicated read replica was created + updated_at: + type: string + description: When the dedicated read replica was last updated + ready_at: + type: string + description: When the dedicated read replica was ready to serve queries + nullable: true + ready: + type: boolean + description: Whether or not the dedicated read replica is ready to serve queries + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + region: + type: object + properties: + id: + type: string + description: The ID of the region + provider: + type: string + description: Provider for the region (ex. AWS) + enabled: + type: boolean + description: Whether or not the region is currently active + public_ip_addresses: + items: + type: string + type: array + description: Public IP addresses for the region + display_name: + type: string + description: Name of the region + location: + type: string + description: Location of the region + slug: + type: string + description: The slug of the region + current_default: + type: boolean + description: True if the region is the default for new branch creation + mysql_supported: + type: boolean + description: Whether the region supports MySQL/Vitess databases + postgresql_supported: + type: boolean + description: Whether the region supports PostgreSQL databases + neki_supported: + type: boolean + description: Whether the region supports Neki databases + required: + - id + - provider + - enabled + - public_ip_addresses + - display_name + - location + - slug + - current_default + - mysql_supported + - postgresql_supported + - neki_supported + parameters: + type: array + items: + type: object + properties: + id: + type: string + description: The ID of the parameter + namespace: + type: string + enum: + - pgconf + description: The namespace of the parameter + name: + type: string + description: The name of the parameter + display_name: + type: string + description: The display name of the parameter + category: + type: string + description: The category of the parameter + description: + type: string + description: The description of the parameter + immutable: + type: boolean + description: Whether the parameter can be changed + parameter_type: + type: string + enum: + - integer + - time + description: The type of the parameter + default_value: + type: string + description: The default value of the parameter, which is the primary's current value + disabled_reason: + type: string + description: Why the parameter cannot be changed + nullable: true + value: + type: string + description: The configured value of the parameter + required: + type: boolean + description: Whether the parameter is required + created_at: + type: string + description: When the parameter was created + nullable: true + updated_at: + type: string + description: When the parameter was last updated + nullable: true + restart: + type: boolean + description: True if processes require a server restart on change + max: + type: number + description: The maximum value of the parameter + min: + type: number + description: The minimum value of the parameter, floored at the primary's current value + url: + type: string + description: The URL of the parameter + options: + items: + type: string + type: array + description: Valid options for the parameter value + units: + items: + type: string + type: array + description: Display units for the parameter value + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + required: + - id + - namespace + - name + - display_name + - category + - description + - immutable + - parameter_type + - default_value + - value + - required + - created_at + - updated_at + - restart + - max + - min + - url + - options + - units + - actor + required: + - id + - name + - state + - replicas + - cluster_name + - cluster_display_name + - access_host_url + - private_access_host_url + - private_connection_service_name + - minimum_storage_bytes + - maximum_storage_bytes + - storage_autoscaling + - storage_type + - storage_iops + - storage_throughput_mibs + - volume_modifications_blocked_until + - created_at + - updated_at + - ready_at + - ready + - actor + - region + - parameters + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Not Found + "422": + description: Unprocessable Entity + "429": + description: Too Many Requests. Reduce the frequency of requests and try again soon. + "500": + description: Internal Server Error + description: |- + + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `read_branches` | + | Database | `read_branches` | + | Branch | `read_branch` | + patch: + tags: + - Dedicated read replicas + operationId: update_dedicated_read_replica + summary: Update a dedicated read replica + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + - name: dedicated_read_replica + in: path + required: true + description: The name of the dedicated read replica + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + replicas: + type: integer + description: The number of instances serving reads + cluster_size: + type: string + description: The cluster size SKU name + parameters: + type: object + additionalProperties: true + description: "Configuration parameters nested by namespace (e.g., {\"pgconf\": {\"max_connections\": \"300\"}}). Values must be greater than or equal to the primary's." + storage: + type: object + properties: + minimum_storage_bytes: + type: integer + description: The minimum storage size in bytes. + maximum_storage_bytes: + type: integer + description: The maximum storage size in bytes for autoscaling. + storage_autoscaling: + type: boolean + description: Whether storage autoscaling is enabled. + storage_iops: + type: integer + description: The storage IOPS. + storage_throughput_mibs: + type: integer + description: The storage throughput in MiB/s. + responses: + "200": + description: Returns the updated dedicated read replica + headers: {} + content: + application/json: + schema: + type: object + properties: + id: + type: string + description: The ID of the dedicated read replica + name: + type: string + description: The name of the dedicated read replica + state: + type: string + description: "The state of the dedicated read replica: pending, ready, or deleting" + replicas: + type: integer + description: The number of instances serving reads in this dedicated read replica + cluster_name: + type: string + description: The SKU representing the cluster size of the dedicated read replica + cluster_display_name: + type: string + description: The SKU representing the cluster size of the dedicated read replica, for display + access_host_url: + type: string + description: The database connection host for the dedicated read replica + private_access_host_url: + type: string + description: The private database connection host for the dedicated read replica + private_connection_service_name: + type: string + description: The service name to set up private connectivity for the dedicated read replica + nullable: true + minimum_storage_bytes: + type: integer + description: The minimum storage size in bytes + nullable: true + maximum_storage_bytes: + type: integer + description: The maximum storage size in bytes + nullable: true + storage_autoscaling: + type: boolean + description: Whether storage autoscaling is enabled + nullable: true + storage_type: + type: string + enum: + - gp3 + - io2 + - pd_ssd + - hyperdisk_balanced + - premium_v2_lrs + description: The storage type + nullable: true + storage_iops: + type: integer + description: The storage IOPS + nullable: true + storage_throughput_mibs: + type: integer + description: The storage throughput in MiB/s + nullable: true + volume_modifications_blocked_until: + type: string + description: When volume modifications will be allowed again + nullable: true + created_at: + type: string + description: When the dedicated read replica was created + updated_at: + type: string + description: When the dedicated read replica was last updated + ready_at: + type: string + description: When the dedicated read replica was ready to serve queries + nullable: true + ready: + type: boolean + description: Whether or not the dedicated read replica is ready to serve queries + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + region: + type: object + properties: + id: + type: string + description: The ID of the region + provider: + type: string + description: Provider for the region (ex. AWS) + enabled: + type: boolean + description: Whether or not the region is currently active + public_ip_addresses: + items: + type: string + type: array + description: Public IP addresses for the region + display_name: + type: string + description: Name of the region + location: + type: string + description: Location of the region + slug: + type: string + description: The slug of the region + current_default: + type: boolean + description: True if the region is the default for new branch creation + mysql_supported: + type: boolean + description: Whether the region supports MySQL/Vitess databases + postgresql_supported: + type: boolean + description: Whether the region supports PostgreSQL databases + neki_supported: + type: boolean + description: Whether the region supports Neki databases + required: + - id + - provider + - enabled + - public_ip_addresses + - display_name + - location + - slug + - current_default + - mysql_supported + - postgresql_supported + - neki_supported + parameters: + type: array + items: + type: object + properties: + id: + type: string + description: The ID of the parameter + namespace: + type: string + enum: + - pgconf + description: The namespace of the parameter + name: + type: string + description: The name of the parameter + display_name: + type: string + description: The display name of the parameter + category: + type: string + description: The category of the parameter + description: + type: string + description: The description of the parameter + immutable: + type: boolean + description: Whether the parameter can be changed + parameter_type: + type: string + enum: + - integer + - time + description: The type of the parameter + default_value: + type: string + description: The default value of the parameter, which is the primary's current value + disabled_reason: + type: string + description: Why the parameter cannot be changed + nullable: true + value: + type: string + description: The configured value of the parameter + required: + type: boolean + description: Whether the parameter is required + created_at: + type: string + description: When the parameter was created + nullable: true + updated_at: + type: string + description: When the parameter was last updated + nullable: true + restart: + type: boolean + description: True if processes require a server restart on change + max: + type: number + description: The maximum value of the parameter + min: + type: number + description: The minimum value of the parameter, floored at the primary's current value + url: + type: string + description: The URL of the parameter + options: + items: + type: string + type: array + description: Valid options for the parameter value + units: + items: + type: string + type: array + description: Display units for the parameter value + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + required: + - id + - namespace + - name + - display_name + - category + - description + - immutable + - parameter_type + - default_value + - value + - required + - created_at + - updated_at + - restart + - max + - min + - url + - options + - units + - actor + required: + - id + - name + - state + - replicas + - cluster_name + - cluster_display_name + - access_host_url + - private_access_host_url + - private_connection_service_name + - minimum_storage_bytes + - maximum_storage_bytes + - storage_autoscaling + - storage_type + - storage_iops + - storage_throughput_mibs + - volume_modifications_blocked_until + - created_at + - updated_at + - ready_at + - ready + - actor + - region + - parameters + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Not Found + "422": + description: Invalid parameters + "429": + description: Too Many Requests. Reduce the frequency of requests and try again soon. + "500": + description: Internal Server Error + description: |- + + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `write_database` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `write_databases` | + | Database | `write_database` | + delete: + tags: + - Dedicated read replicas + operationId: delete_dedicated_read_replica + summary: Delete a dedicated read replica + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + - name: dedicated_read_replica + in: path + required: true + description: The name of the dedicated read replica + schema: + type: string + responses: + "204": + description: Deletes the dedicated read replica + headers: {} + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Not Found + "422": + description: Unprocessable Entity + "429": + description: Too Many Requests. Reduce the frequency of requests and try again soon. + "500": + description: Internal Server Error + description: |- + + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `write_database` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `write_databases` | + | Database | `write_database` | diff --git a/plugins/openapi/testdata/planetscale-fc13e09d.yaml b/plugins/openapi/testdata/planetscale-fc13e09d.yaml new file mode 100644 index 0000000..da7bb06 --- /dev/null +++ b/plugins/openapi/testdata/planetscale-fc13e09d.yaml @@ -0,0 +1,825 @@ +openapi: 3.0.1 +info: + title: PlanetScale API + description: |- + +

PlanetScale API

+ © 2026 PlanetScale, Inc. + version: v1 + x-copyright: "© 2026 PlanetScale, Inc." +paths: + /organizations/{organization}/databases/{database}/branches/{branch}/bouncers/{bouncer}/resizes: + get: + tags: + - Bouncer resizes + operationId: list_bouncer_resize_requests + summary: Get bouncer resize requests + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + - name: bouncer + in: path + required: true + description: The name of the bouncer + schema: + type: string + - name: page + in: query + description: If provided, specifies the page offset of returned results + schema: + type: integer + default: 1 + - name: per_page + in: query + description: If provided, specifies the number of returned results + schema: + type: integer + default: 25 + responses: + "200": + description: Returns bouncer resize requests + headers: {} + content: + application/json: + schema: + type: object + properties: + type: + type: string + description: The response type. Always "list" for paginated responses. + current_page: + type: integer + description: The current page number + per_page: + type: integer + description: The maximum number of results per page + next_page: + type: integer + description: The next page number, or null when this is the last page + nullable: true + next_page_url: + type: string + description: The next page of results, or null when this is the last page + nullable: true + prev_page: + type: integer + description: The previous page number, or null when this is the first page + nullable: true + prev_page_url: + type: string + description: The previous page of results, or null when this is the first page + nullable: true + data: + type: array + items: + type: object + properties: + id: + type: string + description: The ID of the bouncer resize + state: + type: string + enum: + - pending + - resizing + - canceled + - completed + description: The state of the bouncer resize + replicas_per_cell: + type: integer + description: The number of replicas per cell for the bouncer after the resize + target: + type: string + enum: + - primary + - replica + - replica_az_affinity + description: The backend target for the bouncer after the resize + parameters: + type: object + additionalProperties: true + description: The bouncer parameters + previous_replicas_per_cell: + type: integer + description: The number of replicas per cell for the bouncer before the resize + previous_target: + type: string + enum: + - primary + - replica + - replica_az_affinity + description: The backend target for the bouncer before the resize + previous_parameters: + type: object + additionalProperties: true + description: The previous bouncer parameters + started_at: + type: string + description: The time the bouncer resize started + nullable: true + completed_at: + type: string + description: The time the bouncer resize completed + nullable: true + created_at: + type: string + description: The time the bouncer resize was created + updated_at: + type: string + description: The time the bouncer resize was last updated + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + bouncer: + type: object + properties: + id: + type: string + description: The ID for the resource + name: + type: string + description: The name for the resource + created_at: + type: string + description: When the resource was created + updated_at: + type: string + description: When the resource was last updated + deleted_at: + type: string + description: When the resource was deleted, if deleted + nullable: true + required: + - id + - name + - created_at + - updated_at + - deleted_at + sku: + type: object + properties: + name: + type: string + description: The name of the Postgres bouncer SKU + display_name: + type: string + description: The display name + cpu: + type: string + description: The CPU allocation + ram: + type: integer + description: The amount of memory in bytes + sort_order: + type: integer + description: The sort order of the Postgres bouncer SKU + required: + - name + - display_name + - cpu + - ram + - sort_order + previous_sku: + type: object + properties: + name: + type: string + description: The name of the Postgres bouncer SKU + display_name: + type: string + description: The display name + cpu: + type: string + description: The CPU allocation + ram: + type: integer + description: The amount of memory in bytes + sort_order: + type: integer + description: The sort order of the Postgres bouncer SKU + required: + - name + - display_name + - cpu + - ram + - sort_order + required: + - id + - state + - replicas_per_cell + - target + - parameters + - previous_replicas_per_cell + - previous_target + - previous_parameters + - started_at + - completed_at + - created_at + - updated_at + - actor + - bouncer + - sku + - previous_sku + required: + - type + - current_page + - per_page + - next_page + - next_page_url + - prev_page + - prev_page_url + - data + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Not Found + "422": + description: Unprocessable Entity + "429": + description: Too Many Requests. Reduce the frequency of requests and try again soon. + "500": + description: Internal Server Error + description: |- + Deprecated. Use GET /organizations/:organization/databases/:database/branches/:branch/change-requests with target_types[]=PostgresBouncer and target_id set to the bouncer ID instead. + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `read_branches` | + | Database | `read_branches` | + | Branch | `read_branch` | + patch: + tags: + - Bouncer resizes + operationId: update_bouncer_resize_request + summary: Upsert a bouncer resize request + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + - name: bouncer + in: path + required: true + description: The name of the bouncer + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + bouncer_size: + type: string + description: The bouncer size SKU name (e.g., 'PGB_5', 'PGB_10', 'PGB_20', 'PGB_40', 'PGB_80', 'PGB_160'). Defaults to 'PGB_5'. + replicas_per_cell: + type: integer + description: The number of PgBouncers per availability zone. Defaults to 1. + target: + type: string + description: The type of server the bouncer targets. + parameters: + type: object + additionalProperties: true + description: "Bouncer configuration parameters nested by namespace (e.g., {\"pgbouncer\": {\"default_pool_size\": \"100\"}}). Use the 'List cluster parameters' endpoint to retrieve available parameters. Only parameters with namespace 'pgbouncer' can be updated." + responses: + "200": + description: Returns bouncer resize request + headers: {} + content: + application/json: + schema: + type: object + properties: + id: + type: string + description: The ID of the bouncer resize + state: + type: string + enum: + - pending + - resizing + - canceled + - completed + description: The state of the bouncer resize + replicas_per_cell: + type: integer + description: The number of replicas per cell for the bouncer after the resize + target: + type: string + enum: + - primary + - replica + - replica_az_affinity + description: The backend target for the bouncer after the resize + parameters: + type: object + additionalProperties: true + description: The bouncer parameters + previous_replicas_per_cell: + type: integer + description: The number of replicas per cell for the bouncer before the resize + previous_target: + type: string + enum: + - primary + - replica + - replica_az_affinity + description: The backend target for the bouncer before the resize + previous_parameters: + type: object + additionalProperties: true + description: The previous bouncer parameters + started_at: + type: string + description: The time the bouncer resize started + nullable: true + completed_at: + type: string + description: The time the bouncer resize completed + nullable: true + created_at: + type: string + description: The time the bouncer resize was created + updated_at: + type: string + description: The time the bouncer resize was last updated + actor: + type: object + properties: + id: + type: string + description: The ID of the actor + display_name: + type: string + description: The name of the actor + avatar_url: + type: string + description: The URL of the actor's avatar + required: + - id + - display_name + - avatar_url + bouncer: + type: object + properties: + id: + type: string + description: The ID for the resource + name: + type: string + description: The name for the resource + created_at: + type: string + description: When the resource was created + updated_at: + type: string + description: When the resource was last updated + deleted_at: + type: string + description: When the resource was deleted, if deleted + nullable: true + required: + - id + - name + - created_at + - updated_at + - deleted_at + sku: + type: object + properties: + name: + type: string + description: The name of the Postgres bouncer SKU + display_name: + type: string + description: The display name + cpu: + type: string + description: The CPU allocation + ram: + type: integer + description: The amount of memory in bytes + sort_order: + type: integer + description: The sort order of the Postgres bouncer SKU + required: + - name + - display_name + - cpu + - ram + - sort_order + previous_sku: + type: object + properties: + name: + type: string + description: The name of the Postgres bouncer SKU + display_name: + type: string + description: The display name + cpu: + type: string + description: The CPU allocation + ram: + type: integer + description: The amount of memory in bytes + sort_order: + type: integer + description: The sort order of the Postgres bouncer SKU + required: + - name + - display_name + - cpu + - ram + - sort_order + required: + - id + - state + - replicas_per_cell + - target + - parameters + - previous_replicas_per_cell + - previous_target + - previous_parameters + - started_at + - completed_at + - created_at + - updated_at + - actor + - bouncer + - sku + - previous_sku + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Not Found + "422": + description: Invalid parameters + "429": + description: Too Many Requests. Reduce the frequency of requests and try again soon. + "500": + description: Internal Server Error + description: |- + + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `write_database` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `write_databases` | + | Database | `write_database` | + delete: + tags: + - Bouncer resizes + operationId: cancel_bouncer_resize_request + summary: Cancel a resize request + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + - name: bouncer + in: path + required: true + description: The name of the bouncer + schema: + type: string + responses: + "204": + description: Cancels a resize request + headers: {} + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Not Found + "422": + description: Unprocessable Entity + "429": + description: Too Many Requests. Reduce the frequency of requests and try again soon. + "500": + description: Internal Server Error + description: |- + Deprecated. Use DELETE /organizations/:organization/databases/:database/branches/:branch/change-requests/:id to cancel individual change requests instead. + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `write_database` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `write_databases` | + | Database | `write_database` | + /organizations/{organization}/databases/{database}/branches/{branch}/neki-changes: + get: + tags: + - api-neki_change_requests + operationId: list_neki_change_requests + summary: List change requests for a Neki branch + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + - name: page + in: query + description: If provided, specifies the page offset of returned results + schema: + type: integer + default: 1 + - name: per_page + in: query + description: If provided, specifies the number of returned results + schema: + type: integer + default: 25 + - name: state + in: query + description: Filter change requests by state + style: form + explode: false + schema: + type: array + items: + type: string + - name: target_types + in: query + description: "Filter change requests by target type. Must contain one or more of: NekiAdmin, NekiCluster, NekiConfigurationProfile, NekiExternalShard, or NekiRouter" + style: form + explode: false + schema: + type: array + items: + type: string + - name: target_id + in: query + description: Filter change requests for one target. Requires exactly one target type + schema: + type: string + - name: period + in: query + description: Filter change requests by named period + schema: + type: string + enum: + - 15m + - 1h + - 3h + - 6h + - 12h + - 1d + - 2d + - 7d + - 8d + - name: completed_at + in: query + description: Filter change requests completed between two ISO 8601 timestamps + schema: + type: string + responses: + "308": + description: Redirects to the change requests endpoint + headers: {} + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Not Found + "422": + description: Unprocessable Entity + "429": + description: Too Many Requests. Reduce the frequency of requests and try again soon. + "500": + description: Internal Server Error + description: |- + Deprecated. Use GET /organizations/:organization/databases/:database/branches/:branch/change-requests instead. + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `read_branches` | + | Database | `read_branches` | + | Branch | `read_branch` | + /organizations/{organization}/databases/{database}/branches/{branch}/neki-changes/{id}: + get: + tags: + - api-neki_change_requests + operationId: get_neki_change_request + summary: Get a change request for a Neki branch + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + - name: id + in: path + required: true + description: The ID of the change request + schema: + type: string + responses: + "308": + description: Redirects to the change request endpoint + headers: {} + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Change request not found + headers: {} + "422": + description: Unprocessable Entity + "429": + description: Too Many Requests. Reduce the frequency of requests and try again soon. + "500": + description: Internal Server Error + description: |- + Deprecated. Use GET /organizations/:organization/databases/:database/branches/:branch/change-requests/:id instead. + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `read_branches` | + | Database | `read_branches` | + | Branch | `read_branch` | + delete: + tags: + - api-neki_change_requests + operationId: cancel_neki_change_request + summary: Cancel a change request for a Neki branch + parameters: + - name: organization + in: path + required: true + description: "Organization name slug from `list_organizations`. Example: `acme`." + schema: + type: string + - name: database + in: path + required: true + description: "Database name slug from `list_databases`. Example: `app-db`." + schema: + type: string + - name: branch + in: path + required: true + description: "Branch name from `list_branches`. Example: `main`." + schema: + type: string + - name: id + in: path + required: true + description: The ID of the change request + schema: + type: string + responses: + "308": + description: Redirects to the change request endpoint + headers: {} + "401": + description: Unauthorized + "403": + description: Forbidden + "404": + description: Change request not found + headers: {} + "422": + description: Unprocessable Entity + "429": + description: Too Many Requests. Reduce the frequency of requests and try again soon. + "500": + description: Internal Server Error + description: |- + Deprecated. Use DELETE /organizations/:organization/databases/:database/branches/:branch/change-requests/:id instead. + ### Authorization + A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: + + **Service Token Accesses** + `write_database` + + **OAuth Scopes** + + | Resource | Scopes | + | :------- | :---------- | + | Organization | `write_databases` | + | Database | `write_database` | diff --git a/providers/README.md b/providers/README.md index 9e5821f..a5c98a2 100644 --- a/providers/README.md +++ b/providers/README.md @@ -19,6 +19,7 @@ One page per plugin id: `providers/.md`. Start from [`_template.md`](_templ | [algolia.md](algolia.md) | `algolia-search`, `algolia-ingestion`, `algolia-recommend` | `openapi` | | [elasticsearch.md](elasticsearch.md) | `elasticsearch` | `openapi` | | [sentry.md](sentry.md) | `sentry` | `openapi` | +| [planetscale.md](planetscale.md) | `planetscale` | `openapi` | | [openai-models.md](openai-models.md) | `openai-models` | `retirements` | | [anthropic-models.md](anthropic-models.md) | `anthropic-models` | `retirements` | | [anthropic.md](anthropic.md) | `anthropic` | `migrationguide` | diff --git a/providers/planetscale.md b/providers/planetscale.md new file mode 100644 index 0000000..4b656a5 --- /dev/null +++ b/providers/planetscale.md @@ -0,0 +1,52 @@ +# PlanetScale (`planetscale`) + +## What it watches + +The PlanetScale API (`api.planetscale.com/v1`): operations PlanetScale marks deprecated, and removals of operations it had marked deprecated, between two versions of the API's OpenAPI spec. PlanetScale says it in the operation's description, never with the `deprecated` flag. + +Format plugin: `openapi` (`plugins/openapi`), with `adapter.PlanetScale`. + +## Why this source + +- **Source:** `schemas/openapi.yaml` in [planetscale/terraform-provider-planetscale](https://github.com/planetscale/terraform-provider-planetscale), pinned to the commit that last changed it (`https://raw.githubusercontent.com/planetscale/terraform-provider-planetscale//schemas/openapi.yaml`). The newest such commit comes from the GitHub commits API. Checked on 2026-11-19. +- **Why this one:** + - It's PlanetScale's own spec, in PlanetScale's own GitHub organization: the repo's `make download-openapi` copies it from `https://planetscale.com/docs/openapi.yaml`, the spec the API reference is built from. A workflow runs that every Monday and opens a pull request when the file changed, and a maintainer merges it. + - A commit can be cited and replayed. 33 commits changed the file from 2025-11-11 to 2026-11-09. One deleted it (`f33a0c3b35`, 2025-12-04) and it was back the same day, so there are 32 versions to compare. +- **Alternatives considered:** + - **`https://planetscale.com/docs/openapi.yaml`.** The same spec served live (3.1 MB), a few days to a few months ahead of the repo. It has no versions to pin, cite or replay (`info.version` is always `v1`), and the Wayback Machine has one snapshot of it (2026-05-21). + - **The [changelog](https://planetscale.com/changelog)** (Atom at `https://planetscale.com/changelog/feed.atom`). It holds only the newest 25 posts (2026-10-23 to 2026-11-19 on the day checked), and none of them says "deprecated". It's product news, not keyed by operation. + - **[planetscale/planetscale-go](https://github.com/planetscale/planetscale-go).** The Go API client. Its release notes are GitHub's generated list of merged pull requests, with no breaking-change section. + - **[planetscale/cli](https://github.com/planetscale/cli)** (`pscale`). It doesn't ship the spec. + - **[planetscale/docs](https://github.com/planetscale/docs).** Archived; its last push was 2024-11-12. + - **There's no deprecations page.** +- **Quote:** "Deprecated. Use GET /organizations/:organization/databases/:database/branches/:branch/change-requests instead." (`GET .../branches/{branch}/neki-changes`, deprecated in the spec on 2026-11-09) + +## How the provider announces changes + +- **No API version beyond `/v1`.** `info.version` is a fixed `v1`, so the event's `version` is the date of the spec commit, the closest thing to the API version a change arrived in. +- **The spec grows fast:** from 116 operations (2025-11-11) to 291 (2026-11-09) in the repo, and 298 live on 2026-11-19. +- **Deprecations are rare and said in words.** No version of the spec has ever set `deprecated: true`. The one deprecation in the history, five operations on 2026-11-09, put "Deprecated. Use ... instead." as the first line of each operation's description. +- **Operations leave without being marked.** 41 operations left the spec, none of them deprecated first. + +## What the plugin reads and ignores + +- **Reads:** the spec at the newest commit, converted from YAML to JSON with its values unchanged, and diffed against the last one. Two events come out of it: + - **Deprecations:** an operation whose description now starts with "Deprecated." or "Deprecated:" (any case, after any leading whitespace). The event cites the description, so PlanetScale's replacement is in the excerpt. A description that mentions deprecation further on isn't a deprecation, nor is "Deprecated, storage shrinking is part of storage autoscaling.", which the spec writes on properties. If PlanetScale ever sets the flag, the event quotes the whole operation. + - **Removals (breaking):** an operation that leaves the spec after the previous spec had marked it deprecated. None yet. +- **Matches operations by path template:** a renamed path parameter is the same URL to a caller. +- **Refuses a file that isn't a spec.** At the commit that deleted the file the raw URL answers `404`, and a file with no `paths` fails the fetch: diffed, it would read as every operation removed. +- **Ignores everything else:** + - **Removals of operations that were never deprecated.** 41 in the history: 1 on 2026-06-01, 7 on 2026-10-03, 17 on 2026-10-14, 7 on 2026-10-23, 9 on 2026-11-09. On 2026-10-03, 6 of them were the read-only replica operations, renamed to dedicated read replicas, and on 2026-11-19 planetscale-go's `main` still sends `.../read-only-replicas` ("the deprecated read-only-replicas path", in its own words). Leaving the spec isn't the same as stopping working. + - **Request and response property changes, and new operations.** The history has 216 new operations, and the property side is noisy: 226 type changes on 2025-12-06 alone, when whole numbers became `integer`. +- Over the 31 consecutive pairs this keeps 5 events, all deprecations on 2026-11-09 (`fc13e09d`): `GET` and `DELETE .../bouncers/{bouncer}/resizes`, `GET .../neki-changes`, `GET` and `DELETE .../neki-changes/{id}`. A pattern matching "deprecat" anywhere in the description finds the same 5. +- **Replays** a historical pair (`Replay`, from `e631095a` to `fc13e09d`) and recreates those 5. The drop test replays `b49c3540` to `f6d6ad4d` (the replica rename): no event, where the same pair unfiltered reports the 7 removals. + +## Known gaps + +- **Deprecations PlanetScale announces elsewhere aren't events.** The 12 `/organizations/{organization}/databases/{database}/workflows` operations left the spec on 2026-10-14 without ever being marked in it, and planetscale-go calls `read-only-replicas` deprecated while the spec never did. +- **Removals PlanetScale didn't mark first aren't events,** even if the endpoint really went away. +- **The repo lags the live spec.** A change arrives when the Monday pull request is merged, not when PlanetScale publishes it: on 2026-11-19 the live spec had 7 operations the repo's newest copy (2026-11-09) didn't, and the history has a three-month gap (2026-02-26 to 2026-06-01). The event's `version` is the commit date, not the day PlanetScale changed the API. +- **Some commits are hand edits** to the copy ("Fix type of `planetscale_organization` `invoice_budget_amount`", "Mark `parent_branch` as optional"), so a version can differ from what PlanetScale published. Only 13 of the 33 commits are the workflow's own. +- **Only the REST API is covered.** The SDKs and drivers aren't: `@planetscale/database` (database-js) 2.0.0 (2026-09-24) removed parameter interpolation, which this plugin can't see. +- **Two spec commits on one day share a `version`** (it happened on 2025-12-04, 2026-02-24, 2026-08-11 and 2026-09-10). The events stay distinct, because the operation is part of the fingerprint, but the second run's `previous_version` equals its `version`. +- **The patch-it client can't place these events yet.** Their `version` is a date (`2026-11-09`), because the API has no version. The client keeps a date-versioned API's events only if the API is in its list of date-versioned APIs, so `planetscale` needs an entry there. From 927f47fdf5b02d30ff2018a54b443a2070b908b7 Mon Sep 17 00:00:00 2001 From: brandonphelps1212 Date: Thu, 19 Nov 2026 19:38:27 -0500 Subject: [PATCH 2/2] openapi: one package doc, naming every provider Co-Authored-By: Claude Opus 5.5 Signed-off-by: brandonphelps1212 --- plugins/openapi/openapi.go | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/plugins/openapi/openapi.go b/plugins/openapi/openapi.go index a57c1b6..a0b3dee 100644 --- a/plugins/openapi/openapi.go +++ b/plugins/openapi/openapi.go @@ -1,13 +1,9 @@ // Package openapi is the source plugin for an API that publishes an OpenAPI // spec per release (Stripe, Datadog, GitLab, GitHub, Vercel, Supabase, -// Algolia, Elasticsearch, Sentry, Neon): fetch the newest spec, diff it -// against the last one seen, normalize the changes into events, and attach -// migration hints from the API's changelog when it has one. It can also replay -// two given releases. -// Algolia, Elasticsearch, Sentry, PlanetScale): fetch the newest spec, diff it against the -// last one seen, normalize the changes into events, and attach migration -// hints from the API's changelog when it has one. It can also replay two -// given releases. +// Algolia, Elasticsearch, Sentry, Neon, Convex, PlanetScale): fetch the newest +// spec, diff it against the last one seen, normalize the changes into events, +// and attach migration hints from the API's changelog when it has one. It can +// also replay two given releases. package openapi import (