Интерактивные SQL-примеры на JavaScript

Читать про SQL хорошо, но пробовать запросы вживую еще лучше! Поэтому я разработал виджеты, которые помогут вам превратить статичные SQL-запросы в статьях в интерактивные примеры.

Вот рабочий пример, попробуйте его:

select * from employees
limit 5;

А вот четыре шага, которые помогут настроить интерактивные примеры в ваших статьях или документации:

1. Подключите зависимости

Вам понадобится три JavaScript-файла:

• sqlite3.js — SQLite, скомпилированная для браузера.
• sqlime-db.js — веб-компонент базы данных.
• sqlime-examples.js — веб-компонент интерактивных примеров.

Подключите их через CDN или (предпочтительно) скачайте и разместите локально:

<script src="https://unpkg.com/@antonz/sqlite@3.40.0/dist/sqlite3.js"></script>
<script src="https://unpkg.com/sqlime@0.1.2/dist/sqlime-db.js"></script>
<script src="https://unpkg.com/sqlime@0.1.2/dist/sqlime-examples.js"></script>

Если выбрали локальный вариант, придется еще скачать WebAssembly-файл SQLite:

https://unpkg.com/@antonz/sqlite@3.40.0/dist/sqlite3.wasm

sqlite3.wasm неявно используется скриптом sqlite3.js, так что разместите их в одном каталоге.

Я советую держать SQLite локально, потому что она весит ≈1Мб, а CDN часто подвисают на таких больших файлах.

Все файлы можно установить через npm:

npm install @antonz/sqlite
npm install sqlime

Примечание. @antonz/sqlite — это копия официальной сборки SQLite Wasm. Я завернул ее в npm-пакет для удобства, но если хотите — используйте оригинальную сборку с сайта SQLite.

2. Напишите статью, как делаете это обычно

Допустим, вы пишете небольшую заметку о ранжировании данных в SQL:

<p>Для ранжирования данных в SQL
используют оконную функцию <code>rank()<code>:</p>

<pre class="example">select
  rank() over w as "rank",
  name, department, salary
from employees
window w as (order by salary desc)
order by "rank", id;</pre>

<p>статья продолжается...</p>

Отображается как обычный HTML:

select
  rank() over w as "rank",
  name, department, salary
from employees
window w as (order by salary desc)
order by "rank", id;

3. Загрузите базу данных

Вы можете создать базу из бинарного файла БД SQLite или SQL-скрипта. Я выбрал второй вариант и использую employees.sql, который создает таблицу employees и заполняет ее данными.

Загрузите базу с помощью компонента sqlime-db:

<sqlime-db name="employees" path="./employees.sql"></sqlime-db>

• name — название базы, по которому будем обращаться к ней в дальнейшем.
• path — URL, по которому доступен SQL-скрипт (или бинарный файл) базы.

4. Активируйте примеры

Осталось только превратить SQL-запросы из обычных элементов pre в интерактивные примеры. За это отвечает компонент sqlime-examples:

<sqlime-examples db="employees" selector="pre.example" editable></sqlime-examples>

• db — название базы, которую мы загрузили раньше.
• selector — CSS-селектор для элементов, которые содержат SQL.
• editable — разрешает редактировать код примеров (если убрать, можно будет только запускать).

Готово!

select
  rank() over w as "rank",
  name, department, salary
from employees
window w as (order by salary desc)
order by "rank", id;

sqlime-examples преобразует все элементы с указанным селектором, так что достаточно добавить его на страницу только один раз (кроме случаев, когда у вас несколько групп примеров, которые работают с разными базами данных).

Итого

Интерактивные SQL-примеры отлично подходят для любой документации:

• более информативные, чем статические запросы;
• лучше вовлекают читателя и поощряют эксперименты;
• легко настраиваются и не требуют сервера.

Попробуйте добавить интерактива своим статьям, или задайте вопрос на гитхабе, если что-то непонятно.

──

P.S. Хотите освоить современный SQL? Обратите внимание на Оконные функции