Creating Connections

Professional+

A connection links a configured source to your data warehouse and defines how data flows between them — which streams to sync, what sync mode to use, and when syncs run. This guide walks through the full setup from adding a source to scheduling your first sync.

Step 1 — Add a Source

Navigate to Calabi Connect → Sources → New Source.

Filling in the Source Form

1. Select connector — Search by name (e.g., "Salesforce") from the connector catalog.
2. Name your source — Use a descriptive label such as Salesforce Production or MySQL Staging.
3. Configure credentials — Each connector has its own credential fields:

Credential Type	Example Connectors	What to Provide
OAuth 2.0	Salesforce, HubSpot, Google Analytics	Click Authenticate — browser redirect handles token exchange
API Key	Stripe, Mailchimp, Mixpanel	Paste key from the source platform's developer settings
Basic Auth	PostgreSQL, MySQL, MongoDB	Host, port, database name, username, password
Service Account	BigQuery (as source), Google Sheets	Upload JSON key file

4. Set optional parameters — Some connectors expose start date, lookback window, or object filters. These limit data volume on first sync.

Testing the Connection

Click Test Connection before saving. The test performs a lightweight handshake to verify:

• Credentials are valid and not expired
• Network connectivity from Calabi's infrastructure to the source
• Required permissions are present (e.g., read access to selected objects)

OAuth tokens auto-refresh

For OAuth-based sources, Calabi handles token refresh automatically. You will not need to re-authenticate unless the source revokes access.

Firewall requirements

If your source is a self-hosted database, ensure Calabi's egress IP range is allowlisted in your firewall. Contact your administrator for the current IP list.

A green Connection Successful badge confirms the source is ready. Click Save Source.

---

Step 2 — Add a Destination

Calabi Connect writes all synced data to your organization's pre-configured data warehouse. In most deployments, a default destination is already set up and shared across all connections.

To verify or add a destination, navigate to Calabi Connect → Destinations.

Field	Description
Destination Name	Descriptive label (e.g., Snowflake Production)
Warehouse Type	Snowflake, BigQuery, Redshift, PostgreSQL
Host / Account	Warehouse endpoint or account identifier
Database	Target database name
Schema	Typically raw — raw ingested data lands here
Auth	Username/password or key-pair (Snowflake), service account (BigQuery)

One destination per workspace

Most Calabi workspaces are configured with a single shared destination. Contact your admin before adding a new destination to avoid duplicate data.

---

Step 3 — Create a Connection

With a source and destination available, go to Calabi Connect → Connections → New Connection.

1. Select Source — Pick from your saved sources.
2. Select Destination — Pick from your saved destinations.
3. Name the connection — Defaults to Source → Destination; rename to something meaningful like Salesforce → Snowflake.

---

Step 4 — Select Streams and Sync Modes

After selecting source and destination, Calabi Connect fetches the available streams (tables or objects) from the source.

Stream Selection

Toggle individual streams on or off. For large sources like Salesforce, consider starting with only the streams you need.

Sync Mode per Stream

Each stream can have an independent sync mode:

Mode	How It Works	When to Use
Full Refresh — Overwrite	Truncates and rewrites destination table on every sync	Small reference tables (e.g., currency_codes)
Full Refresh — Append	Appends all source records without deduplication	Audit log use cases
Incremental — Append	Syncs only new rows based on a cursor column (e.g., updated_at)	Large tables where history is cumulative
Incremental — Append + Deduped	Syncs new rows, then deduplicates by primary key	Recommended for most operational tables

Default recommendation

Use Incremental — Append + Deduped for CRM objects (contacts, accounts, deals) and transactional tables. Reserve Full Refresh for small lookup tables under 50K rows.

Cursor Fields and Primary Keys

For incremental modes, select:

• Cursor field — The column used to detect new/updated rows (usually updated_at or modified_date)
• Primary key — Used for deduplication in Append+Deduped mode (usually id)

Most connectors pre-populate sensible defaults — review before saving.

---

Step 5 — Set a Schedule

Schedule Type	Options	Best For
Manual	Triggered on demand only	Development, one-off loads
Every X Hours	1, 2, 3, 6, 8, 12, 24 hours	Near-real-time operational data
Daily (cron)	Specify hour + minute in UTC	Overnight batch loads
Weekly (cron)	Specify day, hour, minute in UTC	Low-frequency reference data
Custom Cron	Full cron expression (e.g., 0 6 * * 1-5)	Complex schedules

All schedules run in UTC

Calabi schedules are always expressed in UTC. Convert your local business hours accordingly (e.g., 6 AM EST = 0 11 * * *).

---

Step 6 — Enable the Connection

Click Save & Enable. The first sync (full historical load) triggers immediately. Subsequent syncs follow the schedule.

Disabling a Connection

To pause syncs without deleting configuration:

1. Navigate to the connection detail page.
2. Toggle the Enabled switch to off.
3. The connection retains all configuration — re-enable at any time.

Deleting a Connection

Deleting a connection removes the sync schedule and job history but does not delete already-synced data in your warehouse.

Deletion is permanent

There is no undo for connection deletion. If in doubt, disable rather than delete.

---

Next Steps

• Monitoring Sync Jobs →
• Available Connectors →