Introduction#

This guide gets you from zero to running a workload in under a minute.

Try expressions (no database needed)#

After installing edg, you can evaluate expressions directly from the command line:

edg "gen('email')"
# naomiroberts@robinson.net

edg "uuid_v4()"
# c8952841-6f5b-4743-a6de-2200415c2f03

edg "regex('[A-Z]{3}-[0-9]{4}')"
# QVM-8314

Or start an interactive REPL session:

edg repl

>> uniform(0, 100)
73.37

>> set_rand(['credit_card', 'debit_card', 'paypal'], [])
debit_card

>> template('ORD-%05d', seq(1, 1))
ORD-00001

Run a workload#

Create a workload config file:

edg-lang

let users = 10000
let batch_size = 1000
let fetch_limit = batch_size

up {
  create_users `CREATE TABLE IF NOT EXISTS users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email STRING NOT NULL
  )`
}

seed {
  populate_users(count: users, size: batch_size)
    `INSERT INTO users (email) __values__` (gen('email'))
}

init {
  fetch_users `SELECT id, email FROM users LIMIT $1` (fetch_limit)
}

run {
  get_user `SELECT * FROM users WHERE id = $1::UUID` (ref_rand('fetch_users').id)

  update_email `UPDATE users SET email = $2 WHERE id = $1::UUID` (
    ref_rand('fetch_users').id,
    gen('email')
  )
}

deseed {
  truncate_users `TRUNCATE TABLE users CASCADE`
}

down {
  drop_users `DROP TABLE IF EXISTS users`
}

YAML

globals:
  users: 10000
  batch_size: 1000
  fetch_limit: batch_size

up:
  - name: create_users
    query: |-
      CREATE TABLE IF NOT EXISTS users (
        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
        email STRING NOT NULL
      )

seed:
  - name: populate_users
    type: exec_batch
    count: users
    size: batch_size
    args:
      - gen('email')
    query: INSERT INTO users (email) __values__

init:
  - name: fetch_users
    args:
      - fetch_limit
    query: SELECT id, email FROM users LIMIT $1

run:
  - name: get_user
    args:
      - ref_rand('fetch_users').id
    query: SELECT * FROM users WHERE id = $1::UUID

  - name: update_email
    args:
      - ref_rand('fetch_users').id
      - gen('email')
    query: UPDATE users SET email = $2 WHERE id = $1::UUID

deseed:
  - name: truncate_users
    type: exec
    query: TRUNCATE TABLE users CASCADE

down:
  - name: drop_users
    type: exec
    query: DROP TABLE IF EXISTS users

Run the full lifecycle with a single command:

edg all \
  --driver pgx \
  --config workload.edg \
  --url "postgres://root@localhost:26257?sslmode=disable" \
  -w 10 \
  -d 30s

This creates the table, seeds 10,000 users, runs random lookups with 10 concurrent workers for 30 seconds, then cleans up.

What next?#

Configuration - full config reference (YAML and edg-lang)
Expressions - every built-in function and the expr-lang feature set
CLI Reference - all commands and flags
Example Workloads - TPC-C, e-commerce, IoT, and more
Testing - integration testing and breakpoint testing for databases