Connect a data source

Creating a data source auto-creates a pack from the source name. The CLI’s --type flag selects the connector; edisyl data-sources create --help lists the ones available. Every connector follows the same test-connection → create flow — its config is connector-specific JSON validated server-side (see below), so a test-connection call with a placeholder config is the fastest way to see exactly which fields a connector wants.

1. Validate your credentials first. The config is connector-specific JSON, passed with --config-file <path> or --config-json '<inline>', never both.

   edisyl data-sources test-connection --type postgres --config-file db.json

   db.json

   {
     "host": "db.example.com",
     "username": "readonly",
     "password": "..."
   }

   The database itself is set separately, via --database on the create call below — not a config field. Other connectors take a different config shape (for example an authMethod choice between a password and a key pair, plus account and warehouse fields); a failed test-connection names the fields it wants.

   A success returns { success: true, durationMs }. A failure returns success: false with a human-readable message: read it, it names the actual problem. The CLI only checks that the JSON is non-empty; the shape itself is validated server-side by the connector.

2. Create the data source, and with it, the pack.

   DS=$(edisyl data-sources create --name "My Warehouse" --type postgres \
          --config-file db.json --database ANALYTICS -j | jq -r '.id')

   Two things fire automatically on a successful create:

   • introspect: refreshes the table list so it’s immediately available.
   • import: brings the tables in as models and, by default, studies each one. The study is what learns what columns mean and how tables join.

   Studies land as learning candidates that a separate review step applies a little later, typically minutes. Until then the models show placeholder descriptions and questions about them are declined. After it, the source is answerable.

3. Find your new pack.

   edisyl pack list

4. Confirm the models are ready, then move on.

   edisyl data-sources models "$DS"

   Once the placeholder descriptions have been replaced with real ones, the source can answer. Head to Teach & ask. You don’t need enrich for initial setup; it re-studies every model and is for later schema changes.

Scoping the import

By default, create imports every table the connector discovers. --selection-rule narrows it; repeat the flag per rule, format scope=identifier where scope is table, schema, or database:

edisyl data-sources create --name "Warehouse prod" --type snowflake \
  --config-file sf.json --database PROD \
  --selection-rule schema=ANALYTICS \
  --selection-rule table=ANALYTICS.PUBLIC.TRANSFERS

edisyl data-sources enrich <id> re-runs the modeling step over every imported model; do that when nothing has been studied yet. --selection-rule is accepted only on create, so a narrow rule can’t be widened later without recreating the source. Prefer schema-level rules. For tables added after the source exists, see Adding tables to a connected source.

One account, several databases

A single data source is one database. If this account has more than one you’ll want to mount, or the provider isn’t SQL at all (an API provider attaches straight to a pack, no database involved), store the credentials once as a connection instead — see Reusable connections.

Next: Teach & ask.