GDQL - Grateful Dead Query Language

SQL for Deadheads. Query every show, setlist, and song from 30 years of the Grateful Dead. Because someone had to bring structure to the most beautifully unstructured band in history.

Documentation | Try it in the Sandbox | Releases

SHOWS FROM 77-80 WHERE "Scarlet Begonias" > "Fire on the Mountain";

SONGS WITH LYRICS("train", "road", "rose") WRITTEN 1968-1970;

SHOWS WHERE "Help on the Way" > "Slipknot!" > "Franklin's Tower";

PERFORMANCES OF "Dark Star" FROM 1972 WITH LENGTH > 20min;

Try: Scarlet→Fire · SONGS LYRICS · Help→Slip→Frank · Dark Star

What is this?

You know that argument about whether the 5/8/77 or 2/13/70 Dark Star is better? GDQL won't settle it, but it'll tell you every show where Dark Star appeared, what it segued into, and how long the jam lasted. It's a query language for people who think setlist.fm doesn't have enough operators.

• Segues - The > operator finds song transitions. "Scarlet Begonias" > "Fire on the Mountain" does what you think it does.
• Lyrics - Search the catalog by words. Find every song about trains, or roses, or whatever Garcia was thinking about.
• Eras - FROM EUROPE72 or FROM BRENT_ERA. Because the band in '69 and the band in '89 were basically different species.
• Venues - Every Fillmore, Winterland, and college gymnasium they ever played.
• Setlists - SETLIST FOR 5/8/77 gives you Cornell. You already knew that date by heart.

Quick Examples

-- Every Scarlet > Fire from the golden era
SHOWS FROM 77-79 WHERE "Scarlet Begonias" > "Fire on the Mountain";

-- Songs about trains (there are more than you'd think)
SONGS WITH LYRICS("train", "railroad", "engineer");

-- The longest Dark Stars — for the truly committed
PERFORMANCES OF "Dark Star" ORDER BY LENGTH DESC LIMIT 10;

-- What happened at the Fillmore in '69?
SHOWS AT "Fillmore West" FROM 1969;

-- The setlist everyone argues about
SETLIST FOR 5/8/77;

Try in Sandbox: Scarlet→Fire · SONGS LYRICS · Dark Star by length · Cornell setlist

Installation

Download a release (recommended)

1. Download gdql from Releases (gdql.exe on Windows)
2. Put it on your PATH
3. Run it

gdql "SHOWS FROM 1977 LIMIT 5"

The database is baked into the binary. No separate files to download.

Build from source (requires Go 1.24+)

git clone https://github.com/gdql/gdql
cd gdql
go build -o gdql ./cmd/gdql

Usage

gdql "SHOWS FROM 1977 LIMIT 5"
gdql -f query.gdql
echo ‘SHOWS FROM 1977;’ | gdql -

Use -db <path> to query a custom database instead of the embedded one.

PowerShell: queries with > or quotes can get mangled. Use -f query.gdql or wrap in single quotes:

gdql ‘SHOWS WHERE "Scarlet Begonias" > "Fire on the Mountain";’

• Backtick-escape the inner double quotes:
  .\gdql.exe "SHOWS WHERE \"Scarlet Begonias`" > `"Fire on the Mountain`""`

Planned: interactive REPL, -e flag.

Documentation

• docs/LANGUAGE.md — Language reference (living doc; we update it as we add features).
• docs/INSTALL_GO_WSL.md — How to install Go on WSL.
• DESIGN.md — Full language design and ideas.
• SPEC.md — Implementation spec and grammar.

Go API docs: From the repo root, run go doc ./... to see package and symbol docs. Add // Comment above exported types and functions to build those docs as you go.

Running tests

go test ./...                    # all tests
go test -v ./test/acceptance/    # example / docs-style E2E tests only
go test ./test/acceptance/ -run TestE2E_SetlistForDate   # one example test

The acceptance tests run the same kinds of queries as in the README and docs (e.g. SHOWS FROM 1977, Scarlet > Fire, SETLIST FOR 5/8/77, SONGS WITH LYRICS, PERFORMANCES OF "Dark Star") against a fixture DB.

Status

Fully functional. Parses, plans, and executes against SQLite. Supports SHOWS, SONGS, PERFORMANCES, SETLIST with date ranges, segue chains, position/played/guest conditions, and table/JSON/CSV output. The whole setlist database ships inside the binary — just run it.

Data sources

The embedded database is built from these sources:

• Deadlists (setlists.net) — show dates, venues, setlists with proper set/encore structure
• Relisten / archive.org — track durations from the Live Music Archive recordings
• Relisten — lyrics data

The > operator in queries means "next song in the setlist" — not necessarily a musical segue. Real segue data is hard to source at scale, so GDQL uses position as a proxy and marks a curated list of known segue pairs (Scarlet > Fire, China Cat > Rider, etc.).

If you spot missing or incorrect data, open an issue.

License

MIT

---

"Once in a while you get shown the light, in the strangest of places if you look at it right."