diff --git a/README.md b/README.md index 5a1a8e7..988b68d 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-26-3f5bf0)](docs/plugins.md) +[![Plugins](https://img.shields.io/badge/plugins-27-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..cb245ee --- /dev/null +++ b/adapter/planetscale.go @@ -0,0 +1,126 @@ +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) + } + // The server is "https://api.planetscale.com/v1" and the paths leave out + // /v1 (all 32 versions, checked 2026-11-19). Moved into the paths, an + // operation is named by the path a caller sends, and a spec that ever + // moved it (as Sentry's did) can't read as every deprecated operation + // removed. + if content, err = ServerBasePath(content); err != nil { + return Spec{}, fmt.Errorf("planetscale spec %s: %w", sha, err) + } + return Spec{Content: content, Version: commit.Commit.Committer.Date.UTC().Format("2006-01-02"), SourceURL: url}, nil +} + +// SourcePointer: see BasePathPointer. +func (PlanetScale) SourcePointer(content []byte) func(string) string { return BasePathPointer(content) } + +var _ Reshaper = PlanetScale{} 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 2095189..8350225 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": 26, + "count": 27, "plugins": [ { "id": "algolia-ingestion", @@ -173,6 +173,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 ec35d49..73e1fbf 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -22,6 +22,7 @@ The table between the `plugins:start` and `plugins:end` markers is also publishe | [`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 | | [`neon`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/neon.md) | Neon | API | Neon API operations deprecated, and deprecated operations removed, between commits of the spec | `openapi` | [neondatabase/neon-pkgs](https://github.com/neondatabase/neon-pkgs) (`packages/sdk/spec/neon-openapi.json`) | live | | [`convex`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/convex.md) | Convex | API | Deployment API operations deprecated, and deprecated operations removed, between commits of the spec | `openapi` | [get-convex/convex-backend](https://github.com/get-convex/convex-backend) (`npm-packages/@convex-dev/platform/deployment-openapi.json`) | 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 9275ee8..a0b3dee 100644 --- a/plugins/openapi/openapi.go +++ b/plugins/openapi/openapi.go @@ -1,9 +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, 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 ( @@ -55,6 +55,10 @@ func init() { // No Hints: Convex has no API changelog; its news feed is product news. // Only operation deprecations and removals: see convex.go. plugin.Register(Plugin{Adapter: adapter.Convex{}, Diff: convexDiff, Keep: convexKeep}) + // 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..5cf0b0f --- /dev/null +++ b/plugins/openapi/planetscale_test.go @@ -0,0 +1,220 @@ +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 = "/v1/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") + } +} + +// planetscaleKept is what the plugin's options and keep rule make of two +// inline specs. +func planetscaleKept(t *testing.T, oldJSON, newJSON string) []diff.Change { + t.Helper() + o, err := diff.Parse([]byte(oldJSON)) + if err != nil { + t.Fatal(err) + } + n, err := diff.Parse([]byte(newJSON)) + if err != nil { + t.Fatal(err) + } + var kept []diff.Change + for _, c := range diff.ChangesWith(o, n, planetscaleDiff) { + if planetscaleKeep(c) { + kept = append(kept, c) + } + } + return kept +} + +// PathTemplates: a deprecated operation whose path parameter is renamed is +// the same URL, not a removal. Without it, the keep rule would report the +// deprecated operation shut down. +func TestPlanetScaleParameterRenameIsNotARemoval(t *testing.T) { + const op = `"get":{"description":"Deprecated. Use GET /b instead.","parameters":[{"name":"%s","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}` + oldSpec := `{"openapi":"3.0.1","paths":{"/a/{id}":{` + strings.Replace(op, "%s", "id", 1) + `}}}` + newSpec := `{"openapi":"3.0.1","paths":{"/a/{name}":{` + strings.Replace(op, "%s", "name", 1) + `}}}` + if kept := planetscaleKept(t, oldSpec, newSpec); len(kept) != 0 { + t.Errorf("kept %v, want nothing", kept) + } +} + +// QuoteDeprecatedOperation: PlanetScale has never set the `deprecated` flag, +// but if it starts to, the event quotes the operation, with its "Use X +// instead", not a bare `true`. +func TestPlanetScaleFlagQuotesTheOperation(t *testing.T) { + oldSpec := `{"openapi":"3.0.1","paths":{"/a":{"get":{"description":"Lists a.","responses":{"200":{"description":"OK"}}}}}}` + newSpec := `{"openapi":"3.0.1","paths":{"/a":{"get":{"deprecated":true,"description":"Lists a. Use GET /b instead.","responses":{"200":{"description":"OK"}}}}}}` + kept := planetscaleKept(t, oldSpec, newSpec) + if len(kept) != 1 || kept[0].Kind != diff.OperationDeprecated || kept[0].Pointer != "/paths/~1a/get" { + t.Errorf("kept %+v, want one deprecation citing /paths/~1a/get", kept) + } +} diff --git a/plugins/openapi/registered_test.go b/plugins/openapi/registered_test.go index b5ba566..4f45987 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{}, adapter.Neon{}, adapter.Convex{}} { + 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.Neon{}, adapter.Convex{}, adapter.PlanetScale{}} { kittest.Registered(t, Plugin{Adapter: a}) } } diff --git a/plugins/openapi/testdata/README.md b/plugins/openapi/testdata/README.md index 42bd5d8..179f498 100644 --- a/plugins/openapi/testdata/README.md +++ b/plugins/openapi/testdata/README.md @@ -33,6 +33,8 @@ Each pair is a real breaking change between two releases of a provider's own spe | `neon-api-client-2.7.2.yaml`, `neon-api-client-2.7.3.yaml` | `public-v2-for-users.gen.yaml` in https://registry.npmjs.org/@neondatabase/api-client/-/api-client-2.7.2.tgz (and `api-client-2.7.3.tgz`) | 2026-11-19 | Excerpt for testing; © Neon. The package is MIT, but the spec's own `info.license` says "Proprietary" | "**Deprecated.** Use `GET /consumption_history/projects` (`getConsumptionHistoryPerProject`)" (`GET /consumption_history/account`, in 2.7.2, gone in 2.7.3) | | `convex-f35879bb.json`, `convex-5e5159cb.json` | https://raw.githubusercontent.com/get-convex/convex-backend/f35879bb396491942bf8ecbc8ef5e4280499f89f/npm-packages/@convex-dev/platform/deployment-openapi.json (and `5e5159cbea5188e9da5400febda1b031a233eea0`) | 2026-11-19 | FSL-1.1-Apache-2.0 (get-convex/convex-backend `LICENSE.md`; the spec's own `info.license` is `LicenseRef-FSL-1.1-Apache-2.0`): excerpt for testing, © Convex, Inc.; maintainers, please confirm | "Deprecated: use `GET /integrations` instead." (`GET /list_log_streams`, and five more log stream operations, new in `5e5159cb`) | | `convex-3f6edf7a.json`, `convex-3ead9091.json` | https://raw.githubusercontent.com/get-convex/convex-backend/3f6edf7ab8f3f98e027f317633246a19348eabcc/npm-packages/@convex-dev/platform/deployment-openapi.json (and `3ead909103b7f5897f529c031e80991ad174b07e`) | 2026-11-19 | FSL-1.1-Apache-2.0 (get-convex/convex-backend `LICENSE.md`; the spec's own `info.license` is `LicenseRef-FSL-1.1-Apache-2.0`): excerpt for testing, © Convex, Inc.; maintainers, please confirm | `"name": {` in `UsageLimitConfigRequest` and `UsageLimitConfigResponse` (in `3f6edf7a`, gone in `3ead9091` without being deprecated): the drop test | +| `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. @@ -44,5 +46,6 @@ The Sentry copies keep `openapi`, `info`, `servers` and the path items involved, The Neon copies are excerpts, not whole files: the spec says its license is "Proprietary" whatever the license of the repo or package that ships it. The JSON copies keep `openapi`, `servers`, `info` (without its `contact`) and the path items involved, whole and in their original order, every line copied unchanged (bar the trailing comma after a member that's now last); `components` left out. The YAML copies keep, by lines, `openapi`, `servers`, `info`'s `title`, `version` and `license`, and the path items involved; they're a different source from the plugin's (the npm package @neondatabase/api-client, succeeded by @neon/sdk and not released since 2.7.3), used only to check that the removal of an operation marked deprecated is kept. The Convex copies keep `openapi`, `info`, `servers` and the path items involved, whole and in their original order, every line copied unchanged (bar the trailing comma after a path item or schema that's now last); the usage-limit pair also keeps the component schemas those operations reach, the log stream pair none. The source is FSL-1.1-Apache-2.0 (each version becomes Apache-2.0 two years after it's published), which allows copying for a permitted purpose; these are short excerpts kept for testing, but a maintainer should confirm that before release. Each pair gives the same changes as the full files, with and without the filter. The management API spec (`management-openapi.json`, `info.license` `LicenseRef-Convex`, not defined anywhere in the repo) is neither read nor saved. +The PlanetScale copies are trimmed by lines: everything before `paths:` (`openapi`, `info`), then the path items involved, whole, and the two-line `servers` block (`https://api.planetscale.com/v1`, the same in every version), every line copied unchanged; the other paths, `tags`, `security`, `x-readme` 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..0d6f791 --- /dev/null +++ b/plugins/openapi/testdata/golden/planetscale.json @@ -0,0 +1,107 @@ +[ + { + "id": 1, + "fingerprint": "sha256:12edd932544ab7968b2ad2cd824f69cb0c14e258cbc923ac87feed5880eaaa78", + "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 /v1/organizations/{organization}/databases/{database}/branches/{branch}/bouncers/{bouncer}/resizes" + }, + "description": "Operation DELETE /v1/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:9d65c2b858a48c37c43fc2d4cdcf41b581ecab8ad3aa5f598ea4e85542d606b9", + "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 /v1/organizations/{organization}/databases/{database}/branches/{branch}/bouncers/{bouncer}/resizes" + }, + "description": "Operation GET /v1/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:51bee34c435105c87184ba87b0b57fae2195ff2212833d6630c41150b7d8d011", + "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 /v1/organizations/{organization}/databases/{database}/branches/{branch}/neki-changes" + }, + "description": "Operation GET /v1/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:414d4e35218966651f9ebb9baa9bef90d1a26dbb1722e53ec01b559ed6e1bd57", + "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 /v1/organizations/{organization}/databases/{database}/branches/{branch}/neki-changes/{id}" + }, + "description": "Operation DELETE /v1/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:542446b844dd8fc039e8148a9fbe9160f61e1b239e9889eb97227613d193f65c", + "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 /v1/organizations/{organization}/databases/{database}/branches/{branch}/neki-changes/{id}" + }, + "description": "Operation GET /v1/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..c693009 --- /dev/null +++ b/plugins/openapi/testdata/planetscale-b49c3540.yaml @@ -0,0 +1,1747 @@ +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` | +servers: + - url: https://api.planetscale.com/v1 diff --git a/plugins/openapi/testdata/planetscale-e631095a.yaml b/plugins/openapi/testdata/planetscale-e631095a.yaml new file mode 100644 index 0000000..ba68a69 --- /dev/null +++ b/plugins/openapi/testdata/planetscale-e631095a.yaml @@ -0,0 +1,1454 @@ +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` | +servers: + - url: https://api.planetscale.com/v1 diff --git a/plugins/openapi/testdata/planetscale-f6d6ad4d.yaml b/plugins/openapi/testdata/planetscale-f6d6ad4d.yaml new file mode 100644 index 0000000..07bc074 --- /dev/null +++ b/plugins/openapi/testdata/planetscale-f6d6ad4d.yaml @@ -0,0 +1,1830 @@ +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` | +servers: + - url: https://api.planetscale.com/v1 diff --git a/plugins/openapi/testdata/planetscale-fc13e09d.yaml b/plugins/openapi/testdata/planetscale-fc13e09d.yaml new file mode 100644 index 0000000..0c806bd --- /dev/null +++ b/plugins/openapi/testdata/planetscale-fc13e09d.yaml @@ -0,0 +1,827 @@ +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` | +servers: + - url: https://api.planetscale.com/v1 diff --git a/providers/README.md b/providers/README.md index 810da16..7bc5e53 100644 --- a/providers/README.md +++ b/providers/README.md @@ -21,6 +21,7 @@ One page per plugin id: `providers/.md`. Start from [`_template.md`](_templ | [sentry.md](sentry.md) | `sentry` | `openapi` | | [neon.md](neon.md) | `neon` | `openapi` | | [convex.md](convex.md) | `convex` | `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..4ff0a46 --- /dev/null +++ b/providers/planetscale.md @@ -0,0 +1,53 @@ +# 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. +- **Names operations by the path a caller sends,** `GET /v1/organizations/…`: the server is `https://api.planetscale.com/v1` (in all 32 versions) and the paths leave out `/v1`, so the adapter moves it into the paths (as Sentry's does with `/api/0`). Quotes cite the spec as published, and PlanetScale's own "Use GET /organizations/…" text leaves out `/v1`. If PlanetScale ever moves `/v1` between the server and the paths, the operations stay the same, rather than every deprecated one reading as removed. +- **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.