pg_ps
Monitor active database queries and processes on Heroku apps to identify long-running queries, track progress, debug performance issues, and view resource usage in real-time.
Instructions
Monitor active database queries and processes. Use this tool when you need to: 1) View currently executing queries, 2) Track query progress and resource usage, 3) Identify long-running or blocked queries, 4) Debug performance issues in real-time. The tool provides detailed visibility into database activity with optional verbose output.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| app | Yes | The name of the Heroku app whose database processes to view. | |
| database | No | Config var containing the connection string, unique name, ID, or alias of the database. To access another app's database, prepend the app name to the config var or alias with `APP_NAME::`. If omitted, DATABASE_URL is used. | |
| verbose | No | When true, shows additional query details including query plan and memory usage. |
Implementation Reference
- src/tools/data.ts:214-225 (handler)Executes the pg:ps Heroku CLI command to monitor active queries. Builds the command using CommandBuilder with app, verbose flag, and database argument. Executes via HerokuREPL and processes output with handleCliOutput.async (options: PgPsOptions): Promise<McpToolResponse> => { const command = new CommandBuilder(TOOL_COMMAND_MAP.PG_PS) .addFlags({ app: options.app, verbose: options.verbose }) .addPositionalArguments({ database: options.database }) .build(); const output = await herokuRepl.executeCommand(command); return handleCliOutput(output); }
- src/tools/data.ts:44-53 (schema)Zod schema for pg_ps tool input options: app (string, required), verbose (boolean, optional), database (string, optional).export const pgPsOptionsSchema = z.object({ app: z.string().describe('Target app name'), verbose: z.boolean().optional().describe('Show query plan and memory usage'), database: z .string() .optional() .describe('Database identifier. Format: APP_NAME::DB for other apps. Default: DATABASE_URL') }); export type PgPsOptions = z.infer<typeof pgPsOptionsSchema>;
- src/index.ts:78-78 (registration)Registers the pg_ps tool on the MCP server by invoking registerPgPsTool.data.registerPgPsTool(server, herokuRepl);
- src/utils/tool-commands.ts:33-33 (helper)TOOL_COMMAND_MAP constant defining PG_PS as the 'pg:ps' Heroku CLI command used by the handler.PG_PS: 'pg:ps',