# LearnSQL for AI agents

LearnSQL (https://learnsql.cpetoday.com) is a free, read-only learning site by CPE Today with sample databases, a REST API, an MCP server and long guides on SQL, DAX and Power Query M. This file tells an AI agent how to use it. The same guides are available as plain Markdown (see "Guides").

## What you can do here

- **Run read-only SQL** against about 19 sample databases on SQL Server (primary) and MariaDB/MySQL.
- **Read guides** on SQL, DAX, Power Query M, Power Pivot, Power BI and the sample databases, as Markdown.
- **Look up functions.** One page per DAX and Power Query M function, with syntax, a worked finance example and the mistakes to avoid (see "Function reference").
- **Use free tools** in the browser, such as the tools at https://learnsql.cpetoday.com/tools (see "Tools").
- **Build practice files** (Excel workbooks, Power BI projects) through the MCP server.

Nothing here can change data. Every query is checked to be a single read-only `SELECT`.

## Connect

| Way | How |
|---|---|
| **MCP (best for agents)** | Server address: `https://learnsql.cpetoday.com/mcp`. Claude Code: `claude mcp add --transport http learnsql https://learnsql.cpetoday.com/mcp`. The user signs in once in the browser. Setup for other apps: https://learnsql.cpetoday.com/ai/connect |
| **REST API** | `GET https://learnsql.cpetoday.com/api/{engine}/{database}/{table}` with query parameters. Engines are `mssql` and `mysql`. Reference: https://learnsql.cpetoday.com/docs |
| **Catalog** | `GET https://learnsql.cpetoday.com/api/catalog` lists engines and databases. `GET https://learnsql.cpetoday.com/api/{engine}/{database}/schema-map` lists tables, columns, keys and foreign keys. |
| **Free-form SQL** | `POST https://learnsql.cpetoday.com/api/query` with JSON `{"engine":"mssql","database":"classicmodels","sql":"SELECT TOP 5 * FROM customers"}`. Read-only. |

### MCP tools

`list_databases`, `describe_database`, `describe_table`, `sample_rows`, `check_query`, `run_query`, `use_database` for the data.
`list_dax_topics`, `search_dax_knowledge`, `get_dax_guide`, `lint_dax` for the knowledge base (it covers DAX, SQL and Power Query M, not only DAX).
Start with `list_databases`, then `describe_database`, then write a query and `check_query` it before `run_query`.

## Rules for writing queries

1. **SQL Server (T-SQL) is the primary engine.** Use `SELECT TOP 10 ...`, `OFFSET ... FETCH`, `ISNULL`, `DATEADD`, `DATEDIFF`, `CONVERT`, `EOMONTH`. Square brackets quote names: `[Order Details]`.
2. **MariaDB uses `LIMIT`**, backticks for names, `IFNULL`, `DATE_ADD`, `DATEDIFF`. Do not mix the two dialects.
3. **Qualify names with the schema** on SQL Server (`classicmodels.customers` or the database's schema). Read the `schema` field from `schema-map` rather than guessing `dbo`.
4. **One `SELECT` per call.** No `INSERT`, `UPDATE`, `DELETE`, `DROP`, `EXEC`, temp tables or multiple statements.
5. **Limit rows** while exploring. Large tables hold millions of rows (`mfgorders.order_lines` has 25 million).
6. **Names with spaces** (Northwind: `Order Details`, `Country/Region`) must be quoted, and URL-encoded in REST paths.
7. **Dates move.** Transactional sample databases (classicmodels, northwind, dvdrental, xtreme, acme, adventureworks) have their dates shifted every day so the latest order is today. Never hard-code a date; use the data's own maximum.
8. **Use declared foreign keys.** `schema-map` returns them. Joining on a column that only looks like a key can silently multiply rows.

## Guides (Markdown)

The index of every guide is at `https://learnsql.cpetoday.com/llms.txt`; the whole set in one file is at `https://learnsql.cpetoday.com/llms-full.txt`. A single guide is at `https://learnsql.cpetoday.com/analyze/<slug>.md` (or `https://learnsql.cpetoday.com/analyze/<slug>/md`). Pages at `https://learnsql.cpetoday.com/analyze/<slug>` are the same text as HTML.

Use the slug in the address, for example `https://learnsql.cpetoday.com/analyze/calculate.md`. Pick by task:

| Task | Read (slug) |
|---|---|
| Write or fix SQL | `sql-essentials`, `sql-deep-end` |
| Write DAX measures | `fundamentals`, `calculate`, `patterns`, `functions` |
| Understand DAX performance and internals | `dax-deep-end`, `performance` |
| Time periods (year to date, prior year, fiscal calendars) | `time-intelligence` |
| Clean and reshape data with Power Query | `power-query-m-basics`, `power-query-m-tables`, `power-query-m-patterns`, `power-query-m-performance` |
| Model data (star schema, relationships) | `relationships`, `data-structures`, `learnsql-models` |
| Power Pivot and Power BI | `power-pivot`, `power-bi-desktop`, `report-recipes` |

Each guide page ends with a list of the functions its code uses, and links to each function's page. The page also links to the Markdown address of the guide (`Link: rel="alternate"` header).

## Function reference

Every DAX and Power Query M function has its own page: the syntax, a plain-English explanation, a worked example and the things that go wrong. Check the exact name, arguments and return value there before you write a formula.

| What you need | Address |
|---|---|
| Every DAX function, by category, with one-line summaries (Markdown) | `https://learnsql.cpetoday.com/functions/dax/md` |
| Every Power Query M function, by category, with one-line summaries (Markdown) | `https://learnsql.cpetoday.com/functions/m/md` |
| One function, as Markdown | `https://learnsql.cpetoday.com/functions/<lang>/<slug>.md`, for example `https://learnsql.cpetoday.com/functions/dax/sumx.md` or `https://learnsql.cpetoday.com/functions/m/text-trim.md` |
| The same index as JSON (name, slug, URL, category, summary) | `https://learnsql.cpetoday.com/functions/index.json` |

The `<lang>` is `dax` or `m`. A slug is the function name in lower case with each run of other characters turned into one dash (`Table.SelectRows` is `table-selectrows`). The HTML page for a function is the same address without `.md`.

## Tools

https://learnsql.cpetoday.com/tools lists the free interactive tools. They run in the browser, need no sign-in and read the same sample databases as the rest of the site. Each tool page explains what the tool does and links to the functions it uses.

## New and updated pages

https://learnsql.cpetoday.com/feed is an Atom feed of the 30 most recently updated guides, function pages and tools. https://learnsql.cpetoday.com/sitemap.xml lists every page with its last-modified date, and https://learnsql.cpetoday.com/sitemap is the same list for people.

## Answer well

- Show the SQL you ran and say which database and engine.
- State assumptions (which date, which currency, cancelled orders in or out).
- Check a join with a row count before and after.
- For a Power BI or Excel report, give the measure and the visual, not just the number.
- Say so when the data is sample data. It is for learning, not for decisions.

## About

LearnSQL is provided by CPE Today (Devmatics, LLC). Home: https://learnsql.cpetoday.com. Questions: support@cpetoday.com.
