Setup

You need:

• a GitHub account (sign up),
• git,
• Docker with Docker Compose, running,
• uv, the Python package manager that installs the CLIs,
• an editor, we recommend VS Code.

Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

downloading uv 0.12.19
installing to ~/.local/bin
  uv
  uvx
everything's installed!

Verify in a new terminal:

git --version
docker compose version
uv --version

git version 2.54.0
Docker Compose version v5.1.4
uv 0.12.19

Your version numbers may differ. If docker compose version fails, start Docker Desktop.

Open github.com/datacontract/learn.datacontract.com and click Fork, then Create fork. Your copy lives at github.com/<your-username>/learn.datacontract.com.

With the GitHub CLI, you can fork and clone in one go (then skip the next step):

gh repo fork datacontract/learn.datacontract.com --clone

✓ Created fork you/learn.datacontract.com
Cloning into 'learn.datacontract.com'...
✓ Cloned fork

Clone your fork (replace <your-username>) and change into the folder:

git clone https://github.com/<your-username>/learn.datacontract.com.git
cd learn.datacontract.com

Cloning into 'learn.datacontract.com'...
remote: Enumerating objects: 512, done.
Receiving objects: 100% (512/512), done.
Resolving deltas: 100% (231/231), done.

Run all commands in this tutorial from this folder, the repository root.

The install script uses uv to install the Data Contract CLI (datacontract), the Data Product CLI (dataproduct), and the Entropy Data CLI (entropy-data, only for Part D). It also pre-pulls the PostgreSQL image.

scripts/install.sh

Resolved 182 packages in 2.41s
…
Installed 1 executable: datacontract
…
Installed 1 executable: dataproduct
…
Installed 1 executable: entropy-data
1.2.2
0.2.0
…
Status: Downloaded newer image for postgres:17
docker.io/library/postgres:17

This takes a few minutes: the Data Contract CLI ships drivers for many databases.

Open a new terminal (to update your PATH), go to the repository root, and run:

datacontract --version
dataproduct --version

1.2.2
0.2.0

command not found? Run uv tool update-shell and open a new terminal.

The docker-compose.yml starts PostgreSQL 17 on port 5433 with e-commerce sample data:

docker compose up -d

 Network learndatacontractcom_default Creating
 Network learndatacontractcom_default Created
 Container odcs-odps-workshop-postgres Creating
 Container odcs-odps-workshop-postgres Created
 Container odcs-odps-workshop-postgres Starting
 Container odcs-odps-workshop-postgres Started

Run a quick query:

docker compose exec postgres psql -U workshop -d workshop -c "SELECT COUNT(*) FROM orders_v1.orders;"

 count
-------
  5000
(1 row)

Port already in use? Stop whatever runs on port 5433 and try again.

The database has two schemas, orders_v1 and orders_v2, each with an orders and a line_items table. To reset everything, run docker compose down, then docker compose up -d.

Open .env in the repository root. It holds the database credentials:

DATACONTRACT_POSTGRES_USERNAME=workshop
DATACONTRACT_POSTGRES_PASSWORD=workshop

Both CLIs read .env automatically when run from the repository root. Nothing to configure.

Open the repository folder in VS Code:

code .

Install the YAML extension by Red Hat (VS Code suggests it when you open the folder). The repository ships the official schemas in schemas/ and maps them in .vscode/settings.json, so you get autocompletion and validation for every *.odcs.yaml and *.odps.yaml file.

code: command not found? Use File → Open Folder… instead.