version: "1.0.1" 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.

Major Platform: Managed Databases

What is a Managed Database?

A managed database is a Major-hosted PostgreSQL instance provisioned and managed entirely by the platform. No credentials to manage, no connection strings to configure — everything is handled automatically. Once active, it appears as a regular PostgreSQL resource with isManaged: true.

App-Scoped vs Org-Scoped

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.
• 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.

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 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__orchestrator-platform__run_migration — DDL/DML migrations (managed databases only). Args: applicationId, migration, description

1. Generated TypeScript clients (for app code):

• Call mcp__resource-tools__add-resource-client with the resourceId to generate a typed PostgreSQL client
• Use the client for read/write operations in your application code

Identifying Managed Databases

In mcp__resources__list_resources, managed databases have isManaged: true and a managedScope field:

• managedScope: "app" — App-scoped, belongs to this application only
• managedScope: "org" — Org-scoped, shared across all apps in the organization

The run_migration tool only works on managed databases. 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.

Tips

• Use postgresql_psql for read-only exploration (schema inspection, SELECT queries)
• Use 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 run_migration, generate a TypeScript client for the app to use in code