Connect a data source

Connect your warehouse once, then add the databases each pack needs. Snowflake and Postgres are supported. A pack can answer from a source only after the source is enriched. Enrichment learns what the columns mean and how the tables join.

Recommended: connect in the app

Connect the source in the edisyl app. Open the pack and click Connect a source. After that, use MCP or the CLI to steer the pack and make updates. See Snowflake for the app steps.

This page shows the CLI steps. Connections and data sources are not available over MCP.

CLI only

Before you connect

• A read-only service user. edisyl runs queries with the login you connect. Give that login read access only: the warehouse or server, the database and schemas, and SELECT on the tables the pack should see. On Postgres, use a role with SELECT grants and default_transaction_read_only = on. On Snowflake, use a dedicated user whose only role has USAGE on the warehouse, database, and schema and SELECT on the tables. Turn off the user’s secondary roles (ALTER USER <user> SET DEFAULT_SECONDARY_ROLES = ()).
• Secure sign-in. On Snowflake, use key-pair auth. Snowflake is retiring passwords for service users. On Postgres, use a password over SSL.
• Keep keys away from your agent. You write the config file. Your agent passes only the file path. The CLI reads the file. Keys and passwords never enter the conversation.
• Teach your documents first. Enrichment reads the pack’s documents to describe each table in your organization’s terms. Data dictionaries, policies, and runbooks taught before enrichment make the semantic layer more accurate. A pack with no documents can still be enriched. See Teach & ask.

The config file

Use one file per connection. The database is not in the file. You pass it with the --database flag. This lets one set of credentials serve several databases.

sf.json (Snowflake)

{
  "authMethod": "keypair",
  "account": "xy12345.us-east-1",
  "username": "SVC_EDISYL",
  "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
  "warehouse": "COMPUTE_WH",
  "role": "EDISYL_READER"
}

db.json (Postgres)

{
  "host": "db.example.com",
  "port": 5432,
  "username": "edisyl_reader",
  "password": "...",
  "sslMode": "require"
}

See Snowflake and PostgreSQL for every field.

Connect, then add

1. Connect your warehouse. This tests the credentials and saves them once. One connection can feed many packs.

   edisyl connections create --name "Snowflake prod" --provider snowflake --config-file sf.json

   Ask your agent: Connect our warehouse using sf.json.

   To check credentials without saving anything, run edisyl data-sources test-connection --type snowflake --config-file sf.json. If the test fails, the error states the actual problem.

2. Add a database to the pack. Choose the database and, optionally, a schema. Pass --pack-id to add the source to that pack. Without it, edisyl creates a new pack with the same name as the source.

   edisyl data-sources create --name "Analytics" --connection-id <connection-id> \
     --database PROD --schema ANALYTICS --pack-id <pack-id>

   Ask your agent: Add the PROD database’s ANALYTICS schema to the Supplier risk pack.

   This finds the tables and imports them by name. It doesn’t learn what they mean yet.

3. Enrich it. This learns what the columns mean and how the tables join. It does not run automatically. It can take up to an hour. Until it finishes, questions about the data are declined.

   edisyl data-sources enrich <data-source-id>
   edisyl action watch <action-id>

   Ask your agent: Enrich the new data source and tell me when it’s done.

   You don’t need to watch it. Your agent tells you when it’s done. Run enrich again when a schema change adds tables that were never studied.

   To focus the study of specific tables on what matters to you, study them with guidance in plain language:

   edisyl study <pack> <data-source-id> prod.analytics.dim_users \
     --guidance "the churn columns are what we report on"

To connect and add in one command, run edisyl data-sources create --name "<name>" --type snowflake --config-file sf.json --database PROD. It saves the credentials and adds the database in one step. Use a separate connection when the same account serves more than one database. See Reusable connections.

Choose what comes in

To	Use
Add a whole database or schema	--database <DB> --schema <SCHEMA>
Add only some tables	--admit ORDERS,ORDER_LINES. The other tables in the scope stay pending.
Hold new tables for approval	--no-auto-add-tables
Review and add held tables	edisyl data-sources pending <id>, then edisyl data-sources admit <id> <db.schema.table>
Take a table back out	edisyl data-sources withdraw <id> <db.schema.table>

A source covers its database or schema, including tables created later. The daily refresh adds and enriches new tables automatically. If you turned auto-add off, it holds them as pending instead. Held tables stay pending until you add them. They do not expire. Admitting a table studies it. See Adding tables to a connected source.

When it goes wrong

Symptom	Cause
No tables found after introspection	The database or schema you passed is empty. The credentials are fine. Check --database and --schema, and run edisyl connections databases <connection-id> to see what the connection can reach.
An error that mentions a config field	A typo in the config file. Check the field names against the template. Check the key or certificate format.
403 or “not found”	Your role or pack access doesn’t allow it. Ask your edisyl admin.
Questions about the data are declined	enrich hasn’t run yet, or is still running.

Next: Teach & ask.