pg_psql
Run SQL queries to analyze, modify, or troubleshoot Heroku PostgreSQL databases. Execute commands or file-based queries with credential management for direct database access.
Instructions
Execute SQL queries against Heroku PostgreSQL databases. Use this tool when you need to: 1) Run SQL queries for database analysis, 2) Investigate database locks and performance, 3) Make schema modifications or updates, 4) Execute complex database operations. The tool provides direct SQL access with support for file-based queries and credential management.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| app | Yes | app to run command against | |
| command | No | SQL command to run; file is ignored if provided; must be single line; must supply either command or file | |
| credential | No | credential to use | |
| 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. | |
| file | No | SQL file to run; command is ignored if provided; must be an absolute path; must supply either command or file |
Implementation Reference
- src/tools/data.ts:161-174 (handler)The core handler function for the 'pg_psql' tool. It builds a Heroku CLI 'pg:psql' command using CommandBuilder based on input options, executes it via the HerokuREPL, and processes the output with handleCliOutput.async (options: PgPsqlOptions): Promise<McpToolResponse> => { const command = new CommandBuilder(TOOL_COMMAND_MAP.PG_PSQL) .addFlags({ app: options.app, command: `"${options.command?.replaceAll('\n', ' ') ?? ''}"`, file: options.file, credential: options.credential }) .addPositionalArguments({ database: options.database }) .build(); const output = await herokuRepl.executeCommand(command); return handleCliOutput(output); }
- src/tools/data.ts:13-24 (schema)Zod schema defining the input parameters for the pg_psql tool, including SQL command/file, app, database, and credential.export const pgPsqlOptionsSchema = z.object({ command: z.string().optional().describe('SQL command. Single line. Ignored if file provided'), file: z.string().optional().describe('SQL file path. Ignored if command provided'), credential: z.string().optional().describe('credential to use'), app: z.string().describe('app to run command against'), database: z .string() .optional() .describe( 'Database identifier: config var, name, ID, alias. Format: APP_NAME::DB for other apps. Default: DATABASE_URL' ) });
- src/tools/data.ts:156-176 (registration)The registration function for the pg_psql tool, which calls server.tool with the name, description, schema, and handler.export const registerPgPsqlTool = (server: McpServer, herokuRepl: HerokuREPL): void => { server.tool( 'pg_psql', 'Execute SQL queries: analyze, debug, modify schema, manage data', pgPsqlOptionsSchema.shape, async (options: PgPsqlOptions): Promise<McpToolResponse> => { const command = new CommandBuilder(TOOL_COMMAND_MAP.PG_PSQL) .addFlags({ app: options.app, command: `"${options.command?.replaceAll('\n', ' ') ?? ''}"`, file: options.file, credential: options.credential }) .addPositionalArguments({ database: options.database }) .build(); const output = await herokuRepl.executeCommand(command); return handleCliOutput(output); } ); };
- src/index.ts:76-76 (registration)Invocation of registerPgPsqlTool during server initialization to register the pg_psql tool.data.registerPgPsqlTool(server, herokuRepl);
- src/utils/tool-commands.ts:31-31 (helper)Constant mapping TOOL_COMMAND_MAP.PG_PSQL to the Heroku CLI command 'pg:psql', used in the handler.PG_PSQL: 'pg:psql',