Skip to content
sandadocs
Console Start free trial

Add a connection

Connect a system to your warehouse. Choose the source, enter its details, name it and set a frequency, then choose what to sync and run the first sync.

For owners and admins

View as Markdown

A new connection takes four steps: define the source, connect it, name it and pick a frequency, then choose what to sync. Nothing moves until the last step is saved, so you can look at what a source offers before a single row lands.

Before you start

  • A warehouse that is ready. Every connection lands its rows in a warehouse. If none is ready, the first step shows A warehouse comes first with a Provision a warehouse button. See Provision your warehouse.
  • A way in to the source. For a database, a login that can read the tables you want. For a SaaS system, an API key or app credentials. The setup guide beside the form says what to create.
  • A clear network path, for a database you host. If the database sits behind a firewall, allow sanda's address first.

Add the connection

  1. Open Connections. Go to Data · Connections and press New connection. The steps run along the top: Define source, Connect, Configure, and Streams once you have entered the source's details.

  2. Define the source. Search the catalogue, or pick a card. The search box reads Search sources · Postgres, Xero, Stripe… and matches a connector's name. Popular sources are listed first under Popular, then everything else under All sources.

    Each card carries a badge for how the connector is supported, such as Certified. Concierge marks one a sanda engineer sets up with you, with no form to fill in. If the system you need is not listed, pick Something else.

    Got a one-off file instead? Load a CSV on this step goes straight to the CSV upload, with no connector and no schedule.

  3. Connect it. The form for the source is on the left, and its Setup guide is beside it, so you do not need another tab. Fill in the details, then press Continue.

    The form is different for every source, because each connector describes its own fields. See The connection form below. If you do not have the details to hand, press Skip for now and add them later from the connection's page.

  4. Name it and choose a frequency. The Configure the connection step asks for:

    • Connection name. What you will call it in sanda, for example Acme · Xero (AU). The name also decides where the rows land: the line below the fields shows raw.<name>__* as you type.
    • Sync frequency. Manual, Hourly, Daily or Weekly. A new connection starts on Manual, so nothing runs until you press Sync now or pick a schedule. See Sync schedules.
    • Destination warehouse. Shown when you have a warehouse ready. With one warehouse there is only one choice.

  5. Read the schema. Press Read schema. This is where sanda signs in to the source with your details and reads which tables it offers. It is the test: if a password is wrong or a firewall is closed, this step fails and says why. It can take a minute.

    If it fails, the connection is saved anyway. Fix the cause and press Retry connecting, or press Open connection and continue from its page. See Troubleshoot connections.

  6. Choose what to sync. sanda lists every table the source offers. Tick the ones you want, and pick how each one is read. Press the save button when you are done. It shows the count, for example Save 5 streams. See Choose what to sync.

    Saving is what turns the plan into a working pipeline. Until you save, the connection reads Needs streams.

  7. Run the first sync. Saving takes you to the connection's page, where the status reads Pending. Press Sync now, or leave it and let its schedule start the run. The Status tab shows the run as it happens. See Monitor syncs.

The connection form

The fields come from the connector, so a database asks for a host and a login while a SaaS system asks for a key or an app credential. A few rules hold for all of them.

  • Required fields come first. Optional ones are marked (optional).
  • Secrets are masked. Passwords, keys and tokens are shown as dots as you type.
  • Less common options wait under Advanced settings. They carry sensible defaults, and sanda sends those defaults whether or not you open the section. It opens itself if something in it still needs an answer.
  • A choice can open more fields. An authentication method or an update method changes which fields appear beneath it.
  • Pasted files go in as text. A field that wants a whole JSON document, such as a service-account key, takes it pasted in.
  • The button tells you what is missing. Continue stays disabled until every required field is filled, and Still needed lists the ones that are not.

For a database that offers an Update method, the form opens on the option that needs nothing configured at the source: a cursor you choose per table. Reading changes from the database's own change log needs setup on your database first (on PostgreSQL, a replication slot and a publication), so choose it only when that is in place.

Your details are sent straight to sanda's managed sync over TLS and are never written to sanda's database.

If you skip the details

Skip for now on the Connect step saves the connection without signing in to anything. The Configure step marks it credentials later, and it appears in the list as Setup incomplete. To finish it:

  1. Open the connection. Select it in Data · Connections.
  2. Enter the details. On the Status tab, press Enter connection details, fill in the form and press Connect.
  3. Choose what to sync. The Streams panel opens with Choose what to sync: saving here is what starts the pipeline. Tick tables and save.

Connectors marked Concierge work the same way, without the form: you create the connection with a name and a frequency, and sanda gets in touch to wire it up.

After the first sync

Rows land in raw.<connection>__<stream>, one table per stream. Nothing is added to your semantic map by itself. When rows have landed, the connection's page offers Learn from my data, which asks cherry to read the new tables and propose metrics, dimensions and relationships for you to accept. See Learn from your data.

Something unclear or out of date? Tell us, and we will fix the page.