DEV Community: Navas Herbert

I Taught SQL to Complete Beginners: Here's What Actually Happened

Navas Herbert — Sat, 16 May 2026 10:49:20 +0000

Let me set the scene.

A room full of people who had never written a single line of SQL in their lives. Some came from accounting. Some from operations. One person told me they still used Excel to track hospital records manually. And they were all looking at me like I was about to teach them magic.

Honestly? I kind of was.

This is my retrospective on our SQL journey - what we covered, what broke people's brains (in a good way), and the moments I realised teaching this stuff is genuinely one of the most fun things I do.

Where We Started: "What Even Is a Database?"

Before I could show anyone a SELECT statement, I had to answer the most fundamental question first: why does this exist?

My go-to analogy: a database is like a very organised filing cabinet. Each drawer is a table. Each folder inside the drawer is a row. Each label on the folder is a column. SQL is just the language you use to ask the filing cabinet questions.

Once that clicked, the first query felt almost anticlimactic - in a good way.

SELECT first_name, last_name
FROM students
WHERE grade = 'A';

"Wait… that's it?" Yes. That's it. The magic is in building from there.

Week 1: The Foundation (And the First Confused Faces)

We started with the basics - SELECT, WHERE, ORDER BY, GROUP BY, HAVING. We used a school dataset called Nairobi Academy (fictional Nairobi school - felt very local and relatable) and a hospital dataset called City Hospital.

The moment that got everyone: understanding the difference between WHERE and HAVING.

-- WHERE filters rows BEFORE grouping
SELECT department, COUNT(*) AS total_staff
FROM employees
WHERE status = 'Active'
GROUP BY department;

-- HAVING filters AFTER grouping
SELECT department, COUNT(*) AS total_staff
FROM employees
GROUP BY department
HAVING COUNT(*) > 5;

I used the analogy of a matatu route: WHERE is the conductor deciding who even boards the matatu. HAVING is checking at the destination who actually made it the whole way. That one landed really well.

The Thing That Broke Everyone (In the Best Way): JOINs

I won't lie - JOINs are where beginner SQL classes either soar or crash. I've seen it go both ways.

We covered:

INNER JOIN - only rows that match in both tables
LEFT JOIN - all rows from the left, matched where possible
RIGHT JOIN - all rows from the right
SELF JOIN - a table joining itself (yes, this is a thing)
LEFT JOIN + IS NULL - finding orphaned records

The self-join is always the one that causes dramatic pauses.

-- "Who is each employee's manager?" - same table, different roles
SELECT 
    e.first_name AS employee,
    m.first_name AS manager
FROM employees e
LEFT JOIN employees m ON e.manager_id = m.employee_id;

"Wait… it's joining to itself?"

Yes. Yes it is. Welcome to SQL.

Window Functions: When SQL Starts Feeling Like a Superpower

This is the week I could see people's eyes light up.

Window functions let you do calculations across rows without collapsing them into a group. We covered ROW_NUMBER, RANK, DENSE_RANK, NTILE, running averages with AVG OVER, and time-travel queries with LAG and LEAD.

-- Rank students by score within each class
SELECT 
    student_name,
    class,
    score,
    RANK() OVER (PARTITION BY class ORDER BY score DESC) AS class_rank
FROM results;

And LAG - the one that made the data analysts in the room go quiet for a moment before saying "oh wow":

-- Compare this month's sales to last month's
SELECT 
    month,
    total_sales,
    LAG(total_sales) OVER (ORDER BY month) AS previous_month,
    total_sales - LAG(total_sales) OVER (ORDER BY month) AS difference
FROM monthly_sales;

No subquery. No join. Just clean, readable SQL. This is the moment people stop thinking of SQL as "just for pulling data" and start seeing it as an analytical tool.

CTEs: Writing SQL Like a Human Being

Before CTEs, students were writing nested subqueries that looked like abstract art. Beautiful in theory, impossible to read three days later.

Common Table Expressions (WITH ... AS) changed everything.

-- Find students who scored above the class average
WITH class_averages AS (
    SELECT class, AVG(score) AS avg_score
    FROM results
    GROUP BY class
)
SELECT r.student_name, r.class, r.score
FROM results r
JOIN class_averages ca ON r.class = ca.class
WHERE r.score > ca.avg_score;

The rule I drilled in: write your CTEs like you're telling a story. First set up your averages, then filter against them. Each CTE is a chapter.

Data Cleaning: Where Reality Hits

Every SQL class eventually gets to the uncomfortable truth: real data is messy. Dirty, inconsistent, full of rogue spaces and names typed in ALL CAPS at 4pm on a Friday.

We built a dedicated dirty dataset and went to town with:

-- Standardise names that arrived inconsistently
UPDATE employees
SET 
    first_name = INITCAP(TRIM(first_name)),
    last_name = INITCAP(TRIM(last_name));

-- Strip non-numeric characters from phone numbers
UPDATE contacts
SET phone = REGEXP_REPLACE(phone, '[^0-9]', '', 'g');

-- Fill in missing values rather than leaving NULLs
SELECT 
    COALESCE(department, 'Unassigned') AS department
FROM employees;

Golden rule we repeated every cleaning session: always run a SELECT first before an UPDATE or DELETE. See exactly what you're about to change. Only then pull the trigger.

The Capstone: Tembo Hotel

The final project was set in Tembo Hotel - a fictional Nairobi hotel with ~285 rows of genuinely messy booking data. Students worked in groups to clean it, analyse it, and answer real business questions:

Which room types generate the most revenue?
Which months have the highest no-show rates?
Who are our repeat guests?

Watching groups go from "this data is a disaster" to producing clean queries with CTEs and window functions across a few sessions was something else.

What I Learned Teaching This

A few honest takeaways from being on the teaching side:

1. Analogies are not optional. Every concept needs a real-world anchor before any code appears. If you skip the analogy and go straight to syntax, you lose half the room.

2. Local context matters more than I expected. Using Nairobi names, M-Pesa examples, matatu analogies - students were visibly more engaged when the data felt like their world.

3. PostgreSQL is the right call for beginners. Clean syntax, no shortcuts, no backtick weirdness. If you learn PostgreSQL first, everything else makes sense later.

4. The moment someone writes their first CTE that actually works, they look different. Slightly smug. Entirely justified.

What's Next?

SQL was the foundation. Now we've moved into Python - same students, same energy, new language. We're building toward a full data programme where they'll split into Data Science and Data Engineering tracks.

I'll be writing about that journey too. Follow along if you're building something similar, learning from scratch yourself, or just enjoy watching beginners turn into dangerous analysts one query at a time.

See you next week.

I'm a data engineer in Nairobi. I write weekly about what I'm teaching, what's working, and what surprised me in the classroom. If you're a fellow trainer or a self-taught analyst, let's talk in the comments.

Making Africa Energy Data Accessible to LLMs - a Practical Guide

Navas Herbert — Sat, 16 May 2026 09:57:57 +0000

Introduction

As an AI enthusiast and trainer, I believe high-quality open data is essential for building useful language models and agents. This project - the "Africa Energy Data MCP" - wraps a public Africa Energy Data API and exposes it as MCP tools so LLMs (Claude, Cursor, etc.) can call them directly.

In this short guide you'll find a clear, step-by-step walkthrough for:

Setting up the project locally
Understanding the architecture
Connecting an MCP client (Claude / Cursor)
Running and testing the tools
Publishing options (brief)

Special thanks to my friend Denzel (dkkinyua) who developed the underlying API powering this project - check out his work here: https://github.com/dkkinyua/AfricaEnergyDataAPI/tree/main

Why this matters

LLMs become far more useful when they can call tools that fetch real data. This project makes historical electricity, energy and economic indicators for 54 African countries (2000–2022) trivially available to agents, with caching, retries and validation built in.

Quick highlights

Tools: get_electricity_data, get_energy_data, get_economic_data, check_api_health, list_countries
Tech: Python 3.11, httpx, mcp server, simple in-memory cache, structured logging
Containerization: Dockerfile + GitHub Actions example included

Step 1 - Get the code

Clone the repo and enter the project directory:

git clone https://github.com/Navashub/africa_energy_mcp.git
cd africa_energy_mcp

Step 2 - Install dependencies

Create a virtualenv and install requirements:

python -m venv venv
# Windows
venv\Scripts\activate
# macOS / Linux
source venv/bin/activate
pip install -r requirements.txt

Step 3 - Add your API key

Copy the example env file and paste your RapidAPI key from the API provider (Denzel's API or the RapidAPI listing):

cp .env.example .env
# edit .env and replace AFRICA_ENERGY_API_KEY with your key

Important: never commit .env or your API key to GitHub. The repo includes a .gitignore already.

Step 4 - Run the MCP server

Start the server locally:

py server.py

You should see structured logs on stderr indicating the MCP server initialized and registered tools. Leave this running — it listens on stdio for MCP clients.

Step 5 - Connect an MCP client (Claude / Cursor)

For local testing, point your MCP-capable client at the server.py process. Examples:

Claude Desktop (Windows) — edit %APPDATA%\Claude\claude_desktop_config.json and add:

{
  "mcpServers": {
    "africa-energy": {
      "command": "py",
      "args": ["D:\\mcp_projects\\africa_energy_mcp\\server.py"]
    }
  }
}

Cursor — add the equivalent mcp.servers entry in Cursor settings pointing to your local server.py.

Step 6 - Test useful queries

Start with discovery commands so you confirm connectivity:

"What countries are supported by the Africa Energy Data tool?" — should return the 54-country list (tool list_countries).
"Is the Africa Energy Data API online?" — check_api_health tool should return a health JSON.
Example: "Get electricity data for Kenya in 2022." — will call get_electricity_data and return JSON results.

If an endpoint returns a 500, that indicates the remote API backend failed — the error is on the API provider side. The MCP server will surface a clear error message in that case.

Architecture (brief)

server.py - MCP server that declares tools and routes calls
handlers.py - Input validation and mapping of tool arguments to API calls
api_client.py - httpx.AsyncClient wrapper with retries, 30s timeout, and a 10-minute in-memory cache
tools.py - Schemas for each MCP tool
config.py - Environment and constants (including the hardcoded list of 54 countries)

Containerization & CI

If you want remote hosting, the repo includes a Dockerfile and an example GitHub Actions workflow that builds and pushes a container to GHCR. Publishing requires a registry token — we added a workflow that prefers a GHCR_TOKEN secret or falls back to the repo GITHUB_TOKEN when allowed.

Acknowledgements

Huge thanks to Denzel (dkkinyua) for building the underlying Africa Energy Data API — please check his repository: https://github.com/dkkinyua/AfricaEnergyDataAPI/tree/main

Shout-out: This project was adapted and wrapped into an MCP server by an AI enthusiast and trainer (that’s me — Navashub) to make the data accessible to LLMs for education, research and production usage.

Best practices & tips

Keep your API keys secret - use .env locally and repository secrets for CI.
Test with list_countries and check_api_health before running large queries.
Increase REQUEST_TIMEOUT in config.py only if you know the backend requires more time.
For production hosting, use the Docker image and provide secrets through the host or the platform's secret mechanism.

Conclusion

Making structured, historical energy data available to LLMs unlocks better automated analysis, answers, and decision support. This project is a small but practical bridge - thanks to Denzel for the API and to you for exploring it.