@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. It is queried via the querySalesforce tool, not executeSQL — Salesforce is intentionally a deliberate exception to the generic createFromConfig datasource bridge (ADR-0014).

How Salesforce connects

• OAuth (canonical) — In a running Atlas deployment, connect Salesforce from Admin → Connections via OAuth. Tokens are stored encrypted in integration_credentials, the connection is built on demand per workspace, and refresh/reconnect are handled automatically. This is the recommended path; the operator wires SALESFORCE_CLIENT_ID / SALESFORCE_CLIENT_SECRET. See the Salesforce datasource docs.
• Static config (self-host) — Alternatively, wire a single org with a connection URL in atlas.config.ts (below). Useful for self-hosted, env-driven deployments.

Install

bun add @useatlas/salesforce jsforce

Usage (static config — self-host)

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