From 979f58f71aee558e46e7a6d968656c204818f344 Mon Sep 17 00:00:00 2001 From: Rishikesh Balaji Date: Tue, 8 Sep 2026 08:56:35 -0700 Subject: [PATCH 1/5] fix: correct PostgreSQL write tool documentation --- plugins/shared/skills/resources_postgresql/SKILL.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/plugins/shared/skills/resources_postgresql/SKILL.md b/plugins/shared/skills/resources_postgresql/SKILL.md index dcc1124..298f18f 100644 --- a/plugins/shared/skills/resources_postgresql/SKILL.md +++ b/plugins/shared/skills/resources_postgresql/SKILL.md @@ -27,7 +27,7 @@ description: Implements PostgreSQL connections, SQL queries, and migration patte ## MCP Tools - `mcp__resources__postgresql_psql` — Execute read-only SQL queries and psql backslash commands (`\dt`, `\d`, `\di`, `\df`, etc.). Args: `resourceId`, `command`, `timeoutMs?` -- `mcp__resources__postgresql_run_migration` — Run DDL/DML migrations on **managed databases only** (`isManaged=true`). Runs in a transaction; rolls back on failure. Args: `resourceId`, `migration`, `description?` +- `mcp__resources__postgresql_invoke` — Execute write SQL against managed or external PostgreSQL resources. Args: `resourceId`, `sql`, `params?`, `timeoutMs?`, `description` ## TypeScript Client @@ -48,7 +48,8 @@ if (result.ok) { ## Tips - Use parameterized queries (`$1`, `$2`, ...) — never interpolate values into SQL strings -- `psql` tool is read-only; use `run_migration` for writes (managed DBs) or the TypeScript client for writes (external DBs) +- `psql` is read-only; use `postgresql_invoke` for writes against managed or external PostgreSQL resources +- App-building sessions also have a separate, app-scoped `run_migration` orchestrator tool for tracked managed-database schema migrations. It is not a resource tool and must not be called as `mcp__resources__postgresql_run_migration`. - The TypeScript client supports full read/write operations regardless of managed status - Use `psql` exclusively for read-only tasks. Never use invoke for read only. From 2b4e1a75d731594ff1cb7a3f90d6dcff652f3347 Mon Sep 17 00:00:00 2001 From: Rishikesh Balaji Date: Tue, 8 Sep 2026 10:43:44 -0700 Subject: [PATCH 2/5] docs: keep PostgreSQL write guidance focused --- plugins/shared/skills/resources_postgresql/SKILL.md | 1 - 1 file changed, 1 deletion(-) diff --git a/plugins/shared/skills/resources_postgresql/SKILL.md b/plugins/shared/skills/resources_postgresql/SKILL.md index 298f18f..0e81640 100644 --- a/plugins/shared/skills/resources_postgresql/SKILL.md +++ b/plugins/shared/skills/resources_postgresql/SKILL.md @@ -49,7 +49,6 @@ if (result.ok) { - Use parameterized queries (`$1`, `$2`, ...) — never interpolate values into SQL strings - `psql` is read-only; use `postgresql_invoke` for writes against managed or external PostgreSQL resources -- App-building sessions also have a separate, app-scoped `run_migration` orchestrator tool for tracked managed-database schema migrations. It is not a resource tool and must not be called as `mcp__resources__postgresql_run_migration`. - The TypeScript client supports full read/write operations regardless of managed status - Use `psql` exclusively for read-only tasks. Never use invoke for read only. From 6960b1e125fb6d18522783778457939c97b7766c Mon Sep 17 00:00:00 2001 From: Rishikesh Balaji Date: Tue, 8 Sep 2026 10:47:45 -0700 Subject: [PATCH 3/5] docs: distinguish PostgreSQL writes from migrations --- plugins/shared/skills/resources_postgresql/SKILL.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/plugins/shared/skills/resources_postgresql/SKILL.md b/plugins/shared/skills/resources_postgresql/SKILL.md index 0e81640..c75b618 100644 --- a/plugins/shared/skills/resources_postgresql/SKILL.md +++ b/plugins/shared/skills/resources_postgresql/SKILL.md @@ -28,6 +28,7 @@ description: Implements PostgreSQL connections, SQL queries, and migration patte - `mcp__resources__postgresql_psql` — Execute read-only SQL queries and psql backslash commands (`\dt`, `\d`, `\di`, `\df`, etc.). Args: `resourceId`, `command`, `timeoutMs?` - `mcp__resources__postgresql_invoke` — Execute write SQL against managed or external PostgreSQL resources. Args: `resourceId`, `sql`, `params?`, `timeoutMs?`, `description` +- `mcp__orchestrator-platform__run_migration` — Run tracked migrations on an application's managed database in app-building/orchestrator sessions. Args: `applicationId`, `migration`, `description` ## TypeScript Client @@ -48,7 +49,8 @@ if (result.ok) { ## Tips - Use parameterized queries (`$1`, `$2`, ...) — never interpolate values into SQL strings -- `psql` is read-only; use `postgresql_invoke` for writes against managed or external PostgreSQL resources +- `psql` is read-only; use `postgresql_invoke` for data modifications against managed or external PostgreSQL resources +- Use `run_migration` for tracked schema migrations on an application's managed database when the orchestrator tool is available - The TypeScript client supports full read/write operations regardless of managed status - Use `psql` exclusively for read-only tasks. Never use invoke for read only. From f8c7f80ee4b5dd157cef4f4969b62ba1c6bdf362 Mon Sep 17 00:00:00 2001 From: Rishikesh Balaji Date: Tue, 8 Sep 2026 10:57:25 -0700 Subject: [PATCH 4/5] docs: avoid hosted MCP server prefix --- plugins/shared/skills/resources_postgresql/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/shared/skills/resources_postgresql/SKILL.md b/plugins/shared/skills/resources_postgresql/SKILL.md index c75b618..823471f 100644 --- a/plugins/shared/skills/resources_postgresql/SKILL.md +++ b/plugins/shared/skills/resources_postgresql/SKILL.md @@ -28,7 +28,7 @@ description: Implements PostgreSQL connections, SQL queries, and migration patte - `mcp__resources__postgresql_psql` — Execute read-only SQL queries and psql backslash commands (`\dt`, `\d`, `\di`, `\df`, etc.). Args: `resourceId`, `command`, `timeoutMs?` - `mcp__resources__postgresql_invoke` — Execute write SQL against managed or external PostgreSQL resources. Args: `resourceId`, `sql`, `params?`, `timeoutMs?`, `description` -- `mcp__orchestrator-platform__run_migration` — Run tracked migrations on an application's managed database in app-building/orchestrator sessions. Args: `applicationId`, `migration`, `description` +- `run_migration` on the platform MCP server — Run tracked migrations on an application's managed database in app-building/orchestrator sessions. Args: `applicationId`, `migration`, `description` ## TypeScript Client From 71a13fdf26671df1dae51df1e3e5e02795895318 Mon Sep 17 00:00:00 2001 From: Rishikesh Balaji Date: Tue, 8 Sep 2026 17:41:42 -0700 Subject: [PATCH 5/5] docs: clarify managed migration guidance --- plugins/shared/skills/resources_postgresql/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/shared/skills/resources_postgresql/SKILL.md b/plugins/shared/skills/resources_postgresql/SKILL.md index 823471f..9cfbc09 100644 --- a/plugins/shared/skills/resources_postgresql/SKILL.md +++ b/plugins/shared/skills/resources_postgresql/SKILL.md @@ -50,7 +50,7 @@ if (result.ok) { - Use parameterized queries (`$1`, `$2`, ...) — never interpolate values into SQL strings - `psql` is read-only; use `postgresql_invoke` for data modifications against managed or external PostgreSQL resources -- Use `run_migration` for tracked schema migrations on an application's managed database when the orchestrator tool is available +- Use `run_migration` for tracked schema migrations on an application's managed database - The TypeScript client supports full read/write operations regardless of managed status - Use `psql` exclusively for read-only tasks. Never use invoke for read only.