From 710f72c3986e2a50766dbdf28d1058376e8820a1 Mon Sep 17 00:00:00 2001 From: Rishikesh Balaji Date: Tue, 4 Aug 2026 09:20:27 -0700 Subject: [PATCH 1/3] fix(skills): update PostgreSQL write guidance --- .../resources_managed-database/SKILL.md | 32 +++++++------------ .../skills/resources_postgresql/SKILL.md | 4 +-- 2 files changed, 13 insertions(+), 23 deletions(-) diff --git a/plugins/shared/skills/resources_managed-database/SKILL.md b/plugins/shared/skills/resources_managed-database/SKILL.md index a73bbc4..7a4014e 100644 --- a/plugins/shared/skills/resources_managed-database/SKILL.md +++ b/plugins/shared/skills/resources_managed-database/SKILL.md @@ -1,6 +1,6 @@ --- name: using-managed-database -description: Set up and use Major-managed PostgreSQL databases. Use when the user wants a database, needs to store data, mentions "managed database", or asks about database setup. +description: Understand and use Major-managed PostgreSQL databases. Use when the user wants a database, needs to store data, mentions "managed database", or asks about database setup. --- # Major Platform: Managed Databases @@ -13,29 +13,20 @@ A managed database is a Major-hosted PostgreSQL instance provisioned and managed There are two types of managed databases: -- **App-scoped** (created by this tool): Belongs to a single application. Permissions are automatically inherited from app roles — app admins and editors get `Resource:Admin` on the database. Other apps cannot access it. +- **App-scoped**: Belongs to a single application. Permissions are automatically inherited from app roles — app admins and editors get `Resource:Admin` on the database. Other apps cannot access it. - **Org-scoped**: Shared across all apps in the organization. Created by org admins through the dashboard. Visible to all apps with appropriate permissions. -The `setup_managed_database` MCP tool creates **app-scoped** databases only. +## Lifecycle and Migrations -## Setting Up a Managed Database - -Call `mcp__resources__setup_managed_database` — no arguments needed. The tool automatically provisions a database for the current application. - -**Behavior:** - -- **First call** (no database exists): Starts provisioning. Takes around 1 minute. -- **While provisioning**: Returns status. Wait ~1 minute and call again. -- **Once active**: Returns the resource ID. The database is ready to use. -- **If failed**: Returns failure status. Deprovision and try again. +Managed database lifecycle and migration tools have moved to orchestrator/build surfaces; they are not resource MCP tools. Do not invent or call a resource MCP setup, provisioning, deprovisioning, or migration tool. Use the lifecycle tools exposed by the current orchestrator/build context. Once a managed PostgreSQL resource is connected, use the resource MCP tools below for SQL. ## Using the Database Once Active -After setup completes and you have the resource ID: +After the database is connected and you have its resource ID: 1. **MCP tools** (direct SQL, no code needed): - - `mcp__resources__postgresql_psql` — Read-only SQL queries and psql commands (`\dt`, `\d`, etc.). Args: `resourceId`, `command` - - `mcp__resources__postgresql_run_migration` — DDL/DML migrations (managed databases only). Args: `resourceId`, `migration`, `description?` + - `mcp__resources__postgresql_psql` — Read-only SQL queries and psql commands (`\dt`, `\d`, etc.). Args: `resourceId`, `command`, `timeoutMs?` + - `mcp__resources__postgresql_invoke` — DDL/DML and other write queries. Args: `resourceId`, `sql`, `params?`, `timeoutMs?`. Use `$1`, `$2`, ... placeholders in `sql` and pass their values positionally in `params`. 2. **Generated TypeScript clients** (for app code): - Call `mcp__resource-tools__add-resource-client` with the `resourceId` to generate a typed PostgreSQL client @@ -48,18 +39,17 @@ In `mcp__resources__list_resources`, managed databases have `isManaged: true` an - `managedScope: "app"` — App-scoped, belongs to this application only - `managedScope: "org"` — Org-scoped, shared across all apps in the organization -The `postgresql_run_migration` tool only works on managed databases. Regular (external) PostgreSQL resources have `isManaged: false`. +Regular (external) PostgreSQL resources have `isManaged: false`. ## Choosing Between App and Org Databases If the user has both an app-scoped and an org-scoped managed database available, **ask the user which one they want to use** before proceeding. Do not assume. For example: "I see you have both an app database and an organization-wide database. Which one should I use for this task?" -If there is only an app-scoped database just use that one, don't ask. If there is only an org-scoped database, ask the user if they'd like to make a new app-scoped db. Generally, it's better to use an app DB unless there's a real -reason that data that should be shared for the entire org. +If there is only an app-scoped database, use it without asking. If there is only an org-scoped database, ask whether the user wants to use it or provision an app-scoped database through the available orchestrator/build workflow. Generally, prefer an app database unless the data should be shared across the organization. ## Tips - Use `postgresql_psql` for read-only exploration (schema inspection, SELECT queries) -- Use `postgresql_run_migration` for all schema changes and data modifications on managed databases +- Use `postgresql_invoke` for schema changes and data modifications on connected managed databases - Use parameterized queries (`$1`, `$2`, ...) — never interpolate values into SQL strings -- After creating tables with `run_migration`, generate a TypeScript client for the app to use in code +- After creating tables, generate a TypeScript client for the app to use in code diff --git a/plugins/shared/skills/resources_postgresql/SKILL.md b/plugins/shared/skills/resources_postgresql/SKILL.md index dcc1124..5a57e8f 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 DDL/DML and other write queries. Args: `resourceId`, `sql`, `params?`, `timeoutMs?`. Use `$1`, `$2`, ... placeholders in `sql` and pass their values positionally in `params`. ## TypeScript Client @@ -48,7 +48,7 @@ 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 through MCP - 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 7cd84fe28f26ca65ada1012864f47c71726adad1 Mon Sep 17 00:00:00 2001 From: Rishikesh Balaji Date: Tue, 4 Aug 2026 09:28:26 -0700 Subject: [PATCH 2/3] docs(skills): narrow PostgreSQL guidance fix --- .../resources_managed-database/SKILL.md | 32 ++++++++++++------- 1 file changed, 21 insertions(+), 11 deletions(-) diff --git a/plugins/shared/skills/resources_managed-database/SKILL.md b/plugins/shared/skills/resources_managed-database/SKILL.md index 7a4014e..8fbfc65 100644 --- a/plugins/shared/skills/resources_managed-database/SKILL.md +++ b/plugins/shared/skills/resources_managed-database/SKILL.md @@ -1,6 +1,6 @@ --- name: using-managed-database -description: Understand and use Major-managed PostgreSQL databases. Use when the user wants a database, needs to store data, mentions "managed database", or asks about database setup. +description: Set up and use Major-managed PostgreSQL databases. Use when the user wants a database, needs to store data, mentions "managed database", or asks about database setup. --- # Major Platform: Managed Databases @@ -13,20 +13,29 @@ A managed database is a Major-hosted PostgreSQL instance provisioned and managed There are two types of managed databases: -- **App-scoped**: Belongs to a single application. Permissions are automatically inherited from app roles — app admins and editors get `Resource:Admin` on the database. Other apps cannot access it. +- **App-scoped** (created by this tool): Belongs to a single application. Permissions are automatically inherited from app roles — app admins and editors get `Resource:Admin` on the database. Other apps cannot access it. - **Org-scoped**: Shared across all apps in the organization. Created by org admins through the dashboard. Visible to all apps with appropriate permissions. -## Lifecycle and Migrations +The `setup_managed_database` MCP tool creates **app-scoped** databases only. -Managed database lifecycle and migration tools have moved to orchestrator/build surfaces; they are not resource MCP tools. Do not invent or call a resource MCP setup, provisioning, deprovisioning, or migration tool. Use the lifecycle tools exposed by the current orchestrator/build context. Once a managed PostgreSQL resource is connected, use the resource MCP tools below for SQL. +## Setting Up a Managed Database + +Call `mcp__resources__setup_managed_database` — no arguments needed. The tool automatically provisions a database for the current application. + +**Behavior:** + +- **First call** (no database exists): Starts provisioning. Takes around 1 minute. +- **While provisioning**: Returns status. Wait ~1 minute and call again. +- **Once active**: Returns the resource ID. The database is ready to use. +- **If failed**: Returns failure status. Deprovision and try again. ## Using the Database Once Active -After the database is connected and you have its resource ID: +After setup completes and you have the resource ID: 1. **MCP tools** (direct SQL, no code needed): - - `mcp__resources__postgresql_psql` — Read-only SQL queries and psql commands (`\dt`, `\d`, etc.). Args: `resourceId`, `command`, `timeoutMs?` - - `mcp__resources__postgresql_invoke` — DDL/DML and other write queries. Args: `resourceId`, `sql`, `params?`, `timeoutMs?`. Use `$1`, `$2`, ... placeholders in `sql` and pass their values positionally in `params`. + - `mcp__resources__postgresql_psql` — Read-only SQL queries and psql commands (`\dt`, `\d`, etc.). Args: `resourceId`, `command` + - `mcp__resources__postgresql_invoke` — DDL/DML and other write queries on connected PostgreSQL databases. Args: `resourceId`, `sql`, `params?`, `timeoutMs?`. Use `$1`, `$2`, ... placeholders in `sql` and pass their values positionally in `params`. 2. **Generated TypeScript clients** (for app code): - Call `mcp__resource-tools__add-resource-client` with the `resourceId` to generate a typed PostgreSQL client @@ -39,17 +48,18 @@ In `mcp__resources__list_resources`, managed databases have `isManaged: true` an - `managedScope: "app"` — App-scoped, belongs to this application only - `managedScope: "org"` — Org-scoped, shared across all apps in the organization -Regular (external) PostgreSQL resources have `isManaged: false`. +The `postgresql_invoke` tool works with connected managed and external PostgreSQL resources. Regular (external) PostgreSQL resources have `isManaged: false`. ## Choosing Between App and Org Databases If the user has both an app-scoped and an org-scoped managed database available, **ask the user which one they want to use** before proceeding. Do not assume. For example: "I see you have both an app database and an organization-wide database. Which one should I use for this task?" -If there is only an app-scoped database, use it without asking. If there is only an org-scoped database, ask whether the user wants to use it or provision an app-scoped database through the available orchestrator/build workflow. Generally, prefer an app database unless the data should be shared across the organization. +If there is only an app-scoped database just use that one, don't ask. If there is only an org-scoped database, ask the user if they'd like to make a new app-scoped db. Generally, it's better to use an app DB unless there's a real +reason that data that should be shared for the entire org. ## Tips - Use `postgresql_psql` for read-only exploration (schema inspection, SELECT queries) -- Use `postgresql_invoke` for schema changes and data modifications on connected managed databases +- Use `postgresql_invoke` for schema changes and data modifications on connected PostgreSQL databases - Use parameterized queries (`$1`, `$2`, ...) — never interpolate values into SQL strings -- After creating tables, generate a TypeScript client for the app to use in code +- After creating tables with `postgresql_invoke`, generate a TypeScript client for the app to use in code From b981f0f9bcadeb0cf60b3453a8840b8e9802f4db Mon Sep 17 00:00:00 2001 From: Rishikesh Balaji Date: Tue, 4 Aug 2026 09:32:24 -0700 Subject: [PATCH 3/3] fix(skills): correct managed database migration tool --- plugins/shared/skills/resources_managed-database/SKILL.md | 8 ++++---- plugins/shared/skills/resources_postgresql/SKILL.md | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/plugins/shared/skills/resources_managed-database/SKILL.md b/plugins/shared/skills/resources_managed-database/SKILL.md index 8fbfc65..4bad4a3 100644 --- a/plugins/shared/skills/resources_managed-database/SKILL.md +++ b/plugins/shared/skills/resources_managed-database/SKILL.md @@ -35,7 +35,7 @@ After setup completes and you have the resource ID: 1. **MCP tools** (direct SQL, no code needed): - `mcp__resources__postgresql_psql` — Read-only SQL queries and psql commands (`\dt`, `\d`, etc.). Args: `resourceId`, `command` - - `mcp__resources__postgresql_invoke` — DDL/DML and other write queries on connected PostgreSQL databases. Args: `resourceId`, `sql`, `params?`, `timeoutMs?`. Use `$1`, `$2`, ... placeholders in `sql` and pass their values positionally in `params`. + - `mcp__orchestrator-platform__run_migration` — DDL/DML migrations on the application's managed database. Args: `migration`, `description`, plus `applicationId` in org-scoped sessions. 2. **Generated TypeScript clients** (for app code): - Call `mcp__resource-tools__add-resource-client` with the `resourceId` to generate a typed PostgreSQL client @@ -48,7 +48,7 @@ In `mcp__resources__list_resources`, managed databases have `isManaged: true` an - `managedScope: "app"` — App-scoped, belongs to this application only - `managedScope: "org"` — Org-scoped, shared across all apps in the organization -The `postgresql_invoke` tool works with connected managed and external PostgreSQL resources. Regular (external) PostgreSQL resources have `isManaged: false`. +The `mcp__orchestrator-platform__run_migration` tool only works on managed databases. Regular (external) PostgreSQL resources have `isManaged: false`. ## Choosing Between App and Org Databases @@ -60,6 +60,6 @@ reason that data that should be shared for the entire org. ## Tips - Use `postgresql_psql` for read-only exploration (schema inspection, SELECT queries) -- Use `postgresql_invoke` for schema changes and data modifications on connected PostgreSQL databases +- Use `mcp__orchestrator-platform__run_migration` for all schema changes and data modifications on managed databases - Use parameterized queries (`$1`, `$2`, ...) — never interpolate values into SQL strings -- After creating tables with `postgresql_invoke`, generate a TypeScript client for the app to use in code +- After creating tables with `mcp__orchestrator-platform__run_migration`, generate a TypeScript client for the app to use in code diff --git a/plugins/shared/skills/resources_postgresql/SKILL.md b/plugins/shared/skills/resources_postgresql/SKILL.md index 5a57e8f..dcc1124 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_invoke` — Execute DDL/DML and other write queries. Args: `resourceId`, `sql`, `params?`, `timeoutMs?`. Use `$1`, `$2`, ... placeholders in `sql` and pass their values positionally in `params`. +- `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?` ## TypeScript Client @@ -48,7 +48,7 @@ if (result.ok) { ## Tips - Use parameterized queries (`$1`, `$2`, ...) — never interpolate values into SQL strings -- `psql` is read-only; use `postgresql_invoke` for writes through MCP +- `psql` tool is read-only; use `run_migration` for writes (managed DBs) or the TypeScript client for writes (external DBs) - 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.