Configure your environment

Before you can define, test, or verify Git-managed data contracts, you need to install the Soda CLI and configure your environment.

This setup gives you full control over your contracts, letting you version them in Git, execute them locally or remotely, and integrate them into your CI/CD pipelines.

1. Install the Soda Core Python Package

If you haven't already, follow the Soda Core installation flow to set up your environment, set your credentials, and install the necessary Soda extensions.

2. [Optional] Connect to Soda Cloud

If you want to interact with Soda Cloud to publish contracts and view verification results, or to use Soda Agent, you’ll need to connect the CLI to your Soda Cloud account.

Don’t have an account? Book a demo to get started.

Create the config file

Run the following command:

soda cloud create -f sc_config.yml

This generates a basic Soda Cloud configuration file:

sc_config.yml

soda_cloud:
  host: cloud.soda.io        ##change to cloud.us.soda.io, depending on your Soda region
  api_key_id: ${SODA_CLOUD_API_KEY_ID}
  api_key_secret: ${SODA_CLOUD_API_KEY_SECRET}

Add your API keys

To add your API keys, you can do one of the following:

• Set environment credentials, as directed in the Private PyPi installation flow, or

• Open sc_config.yml and fill in your API key and organization details.

Learn more about how to generate API keys.

Test the connection

Run the following command:

soda cloud test -sc sc_config.yml

This ensures the CLI can authenticate and communicate with Soda Cloud. A successful connection will return:

  __|  _ \|  \   \\
\__ \ (   |   | _ \\
____/\___/___/_/  _\\ CLI v4.0.4b24
Testing soda cloud file sc_config.yml
✅ Success! Tested Soda Cloud credentials in 'sc_config.yml'

3. Configure your data source

To verify a contract, Soda needs to know how to connect to your data source. You have two options:

Connect with Soda Core

If you prefer to define your own connection locally (or aren’t using a Soda Agent), you can create a data source config file for Soda Core.

Install the required package for your data source. For example, for PostgreSQL:

pip install -i https://pypi.cloud.soda.io/simple --pre -U "soda-postgres>4"

See the Data source reference for Soda Core for supported packages and configurations.

Create the config file

soda data-source create -f ds_config.yml

Open ds_config.yml and provide the necessary credentials.

For example, with PostgreSQL:

ds_config.yml

type: postgres
name: postgres
connection:
  host: host_name
  port: 5432
  user: user_name
  password: ${env.SODA_DEMO_POSTGRES_PW}
  database: db_name

Refer to the Data source reference for Soda Core for the configurations of each data source type.

Avoid hardcoding secrets. Use environment variables or a secrets manager where possible.

Test the connection:

soda data-source test -ds ds_config.yml

Use an existing Data Source via Soda Agent

If your data source is already connected to Soda Cloud using a Soda Agent (hosted or self-hosted), you can reuse that connection without managing credentials or configs locally.

You just need to ensure you have set up the connection with Soda Cloud.

---

Choose the method that best fits your setup:

• Soda Agent for a centralized, cloud-managed connection.

• Local configuration if you want full control within your environment.

---

You are not logged in to Soda and are viewing the default public documentation. Learn more about Documentation access & licensing.