KurrentDB projections tutorial

The companion project for the projections tutorial. You write a projection that counts items across shopping carts, run it locally with no database, then deploy it to a real KurrentDB.

Clone it and you are at the starting point, ready to follow the tutorial from the top:

git clone https://github.com/kurrent-io/projections-tutorial
cd projections-tutorial

Every step is also a branch, so you can jump straight to the one you care about - each branch is the project exactly as the tutorial leaves it at the end of that step.

git switch step-03-run

To see what a step changed, diff it against the one before:

git diff step-02-count step-03-run

Branch	What you end up with
main	The starting point: sample events, and a database waiting to be started
step-01-scaffold	A gaffer project with an empty projection
step-02-count	The projection counts Xbox One S consoles
step-03-run	The projection runs against the sample events, with no database
step-04-partition	A second projection counts the items in each cart
step-05-deploy	Both projections deployed to a local KurrentDB
step-06-diff	A local change, seen as a diff against what is deployed. The finished project

What you need

• gaffer on your PATH
• Docker, from step-05-deploy onwards

Nothing else - the seed script's dependencies install inside a container.

The sample events

fixtures/carts.json holds seven ItemAdded events across four shopping carts. Up to step-04-partition they are read straight from that file, so no database is involved. From step-05-deploy they are appended to a real KurrentDB by the seed service:

docker compose up -d
docker compose wait seed

The first command starts a single insecure node on localhost:2113 with projections enabled, alongside a one-shot service that appends the same events you have been running against locally. The second waits for that seeding to finish - without it you can reach the database before its events do.

Re-running is safe: the seed writes each stream only if it does not already exist.

To throw everything away and start again:

docker compose down -v

Which KurrentDB versions this works with

Any supported KurrentDB release. The projections here are engine_version = 1, the engine every release runs by default.

KurrentDB 26.1 also ships an experimental second engine, V2, which processes partitions in parallel but does not emit result streams. See Projections engine V2 if you want to try it.