@useatlas/salesforce

Salesforce datasource plugin for Atlas. Wraps Salesforce SOQL access via jsforce, providing read-only querying of Salesforce objects through a dedicated querySalesforce tool.

Unlike SQL-based datasource plugins, this plugin uses SOQL (Salesforce Object Query Language) and includes its own validation pipeline.

Install

bun add @useatlas/salesforce jsforce

Usage

import { defineConfig } from "@atlas/api/lib/config";
import { salesforcePlugin } from "@useatlas/salesforce";

export default defineConfig({
  plugins: [
    salesforcePlugin({
      url: "salesforce://user:[email protected]?token=SECURITY_TOKEN",
    }),
  ],
});

Config

| Field | Type | Default | Description | |-------|------|---------|-------------| | url | string | — | Salesforce connection URL (must start with salesforce://) |

URL format

salesforce://username:[email protected]?token=SECURITY_TOKEN&clientId=ID&clientSecret=SECRET

| Component | Description | |-----------|-------------| | username | Salesforce username | | password | Salesforce password | | hostname | Login URL (required; use login.salesforce.com for production, test.salesforce.com for sandboxes) | | token | Security token (query param, optional) | | clientId | Connected App client ID (query param, optional) | | clientSecret | Connected App client secret (query param, optional) |

Environment variables

Set credentials via environment variables and reference them in your config:

salesforcePlugin({
  url: process.env.SALESFORCE_URL!,
})

SOQL notes

• SOQL is not SQL — it queries Salesforce objects, not database tables
• No JOIN — use relationship queries (e.g. SELECT Account.Name FROM Contact)
• No SELECT * — always list specific fields
• Date literals: TODAY, LAST_WEEK, LAST_N_DAYS:30, etc.
• The plugin registers a querySalesforce tool (use it instead of executeSQL)

Reference

• Plugin SDK docs
• Authoring guide