bulk-upsert
Insert or update multiple records from CSV or JSON files using a unique key to manage database changes efficiently.
Instructions
Bulk insert or update data from CSV or JSON file. Supports upsert operations with a unique key.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| apiKey | No | API key for authentication (optional if provided via --api_key) | |
| filePath | Yes | Path to CSV or JSON file containing data to import | |
| table | Yes | ||
| upsertKey | No |
Implementation Reference
- src/shared/tools.ts:602-672 (registration)MCP server registration of the 'bulk-upsert' tool, including tool name, description, Zod input schema (apiKey, table, upsertKey from bulkUpsertRequestSchema, filePath), and the handler function.server.tool( 'bulk-upsert', 'Bulk insert or update data from CSV or JSON file. Supports upsert operations with a unique key.', { apiKey: z .string() .optional() .describe('API key for authentication (optional if provided via --api_key)'), ...bulkUpsertRequestSchema.shape, filePath: z.string().describe('Path to CSV or JSON file containing data to import'), }, withUsageTracking('bulk-upsert', async ({ apiKey, table, filePath, upsertKey }) => { try { const actualApiKey = getApiKey(apiKey); // Read the file const fileBuffer = await fs.readFile(filePath); const fileName = filePath.split('/').pop() || 'data.csv'; // Create form data for multipart upload const formData = new FormData(); formData.append('file', fileBuffer, fileName); formData.append('table', table); if (upsertKey) { formData.append('upsertKey', upsertKey); } const response = await fetch(`${API_BASE_URL}/api/database/advance/bulk-upsert`, { method: 'POST', headers: { 'x-api-key': actualApiKey, ...formData.getHeaders(), }, body: formData, }); const result = await handleApiResponse(response); // Format the result message const message = result.success ? `Successfully processed ${result.rowsAffected} of ${result.totalRecords} records into table "${result.table}"` : result.message || 'Bulk upsert operation completed'; return await addBackgroundContext({ content: [ { type: 'text', text: formatSuccessMessage('Bulk upsert completed', { message, table: result.table, rowsAffected: result.rowsAffected, totalRecords: result.totalRecords, errors: result.errors, }), }, ], }); } catch (error) { const errMsg = error instanceof Error ? error.message : 'Unknown error occurred'; return { content: [ { type: 'text', text: `Error performing bulk upsert: ${errMsg}`, }, ], isError: true, }; } }) );
- src/shared/tools.ts:613-671 (handler)Core handler logic for the bulk-upsert tool: reads the local file, constructs multipart form data, sends POST request to backend API /api/database/advance/bulk-upsert, processes response, formats output with success/error messages.withUsageTracking('bulk-upsert', async ({ apiKey, table, filePath, upsertKey }) => { try { const actualApiKey = getApiKey(apiKey); // Read the file const fileBuffer = await fs.readFile(filePath); const fileName = filePath.split('/').pop() || 'data.csv'; // Create form data for multipart upload const formData = new FormData(); formData.append('file', fileBuffer, fileName); formData.append('table', table); if (upsertKey) { formData.append('upsertKey', upsertKey); } const response = await fetch(`${API_BASE_URL}/api/database/advance/bulk-upsert`, { method: 'POST', headers: { 'x-api-key': actualApiKey, ...formData.getHeaders(), }, body: formData, }); const result = await handleApiResponse(response); // Format the result message const message = result.success ? `Successfully processed ${result.rowsAffected} of ${result.totalRecords} records into table "${result.table}"` : result.message || 'Bulk upsert operation completed'; return await addBackgroundContext({ content: [ { type: 'text', text: formatSuccessMessage('Bulk upsert completed', { message, table: result.table, rowsAffected: result.rowsAffected, totalRecords: result.totalRecords, errors: result.errors, }), }, ], }); } catch (error) { const errMsg = error instanceof Error ? error.message : 'Unknown error occurred'; return { content: [ { type: 'text', text: `Error performing bulk upsert: ${errMsg}`, }, ], isError: true, }; } })
- src/shared/tools.ts:605-612 (schema)Zod input schema definition for the tool parameters: apiKey (optional), spreads bulkUpsertRequestSchema.shape (includes table and upsertKey), and required filePath.{ apiKey: z .string() .optional() .describe('API key for authentication (optional if provided via --api_key)'), ...bulkUpsertRequestSchema.shape, filePath: z.string().describe('Path to CSV or JSON file containing data to import'), },