Перейти к содержимому
Поиск
Разработка

PGlite: PostgreSQL в браузере и Node.js — мастерская и 10 примеров

Настоящий PostgreSQL рядом с интерфейсом: 10 сценариев с CRM-данными, JOIN, JSONB, ошибками, транзакциями, живыми показателями и сохранением. Исходники и Windows/Linux.

Александр Некрасов
PGlite: PostgreSQL в браузере и Node.js — мастерская и 10 примеров — обложка

PGlite: настоящий PostgreSQL прямо в приложении

Иногда интерфейсу нужна небольшая, но полноценная база: сохранить черновик, исследовать выгрузку, показать работающий прототип CRM, проверить сложный запрос или дать ученику практику SQL. Поднимать отдельный сервер ради каждой такой задачи неудобно. Массивы JavaScript тоже быстро перестают быть удобными, когда появляются связи, ограничения, группировки и несколько связанных изменений.

PGlite позволяет выполнить PostgreSQL внутри JavaScript через WebAssembly. В браузере база работает на устройстве посетителя, а в Node.js может хранить данные в отдельном каталоге. В этой статье вы попробуете десять сценариев: заявки и клиенты, параметры, JOIN, JSONB, транзакции, ограничения, индексы, живые показатели и перенос данных. Запросы выполняются настоящим движком, результаты можно менять и выгружать.

На выходе получится небольшой понятный проект, из которого можно взять отдельную функцию или всю мастерскую. Здесь есть полный код, закреплённые версии, команды для Windows и Linux, размещение статической страницы на VPS и объяснение границ подхода. Сервер сайта не превращается в общедоступную SQL-консоль: база создаётся в браузере посетителя.

Где это полезно: от кабинета до учебного инструмента

Первый сценарий — прототип интерфейса. Заказчик открывает кабинет, фильтрует заявки, добавляет запись и видит изменение показателей. Разработчик проверяет реальные отношения между таблицами, а не поддерживает несколько несвязанных массивов для разных экранов. Когда появится API, интерфейс уже будет опираться на понятную модель данных.

Второй сценарий — локальная работа: черновики, временная подборка документов, исследование разрешённой выгрузки. Данные можно обработать рядом с интерфейсом и отправить серверу только результат после отдельного подтверждения. Однако сам факт локального выполнения не делает исходные данные публичными: решение о том, что разрешено загружать в браузер, принимается на стороне приложения.

Третий сценарий — документация и обучение. Читатель не просто видит SELECT, а меняет условие, получает настоящую ошибку FOREIGN KEY и наблюдает откат. Такой опыт помогает понять, зачем нужны ограничения и транзакции. Для большого общего сервиса, где несколько пользователей одновременно меняют доверенные данные, понадобится серверная архитектура с авторизацией, резервированием и управлением доступом.

Что выполняется на странице, а что остаётся на сервере

У мастерской три части: интерфейс, отдельный Worker и PostgreSQL WASM. Интерфейс отправляет небольшое сообщение с действием. Worker вызывает код базы и возвращает строки либо ошибку. Таблица результата строится из этих строк; JSON рядом позволяет увидеть ответ без дополнительного оформления. Карточки статистики обновляются по настоящей подписке live.query.

Все файлы движка лежат рядом со страницей: JavaScript, pglite.wasm, initdb.wasm и pglite.data. Внешний CDN не нужен. Первая загрузка требует примерно шестнадцати мегабайт файлов движка, поэтому запуск оставлен явной кнопкой. На медленном соединении нужно дождаться сообщения о готовности, а не повторно нажимать несколько разных действий.

SQL и учебные таблицы не отправляются на сервер сайта. Сервер отдаёт статические файлы и архив. Это описание именно данной реализации: если вы добавите телеметрию, синхронизацию или API, потоки данных изменятся. Отдельный Worker сохраняет отзывчивость страницы и позволяет прервать долгий опыт, но сам по себе не означает отсутствие затрат памяти и процессора.

Мини-мастерская: десять сценариев и собственные запросы

Начните с временной памяти. После запуска вы получите шесть вымышленных клиентов и восемнадцать заявок. Выберите сценарий и нажмите выполнение: над результатом объяснено, какую задачу решает пример и что стоит изменить. Список сценариев не ограничивает исследование: ниже находится редактируемый SELECT с отдельными параметрами.

Форма создаёт заявку, пример транзакции меняет статус и журнал, а раздел переноса позволяет выгрузить данные и восстановить их. При изменении SQL старый результат очищается: нельзя случайно скачать ответ, относящийся к предыдущему условию. Длинная таблица прокручивается внутри своей области; при необходимости мастерская открывается в отдельной вкладке.

Не используйте в опытах реальные пароли, клиентские документы и персональные сведения. Набор данных специально вымышленный. Для первого маршрута достаточно пройти фильтр, JOIN, добавление, откат и экспорт. Затем включите IndexedDB, чтобы отдельно проверить сохранение после закрытия. Режимы памяти и IndexedDB имеют разные базы, поэтому переключение не переносит записи автоматически.

Версии и устройство исходного проекта

В проекте закреплены PGlite 0.5.16, Bootstrap 5.3.9 и esbuild 0.28.2. Сам движок в проверенном выполнении сообщает PostgreSQL 18.6. Используйте npm ci и приложенный package-lock.json, чтобы повторить именно этот набор. Обновление библиотеки выполняйте отдельно, с повторением тестов транзакций, хранения и восстановления.

Основные операции находятся в src/core.mjs. Этот модуль используют и браузерный Worker, и Node.js-тесты: примеры не расходятся в двух независимых реализациях. src/scenarios.mjs содержит пояснения и начальные запросы. src/app.mjs отвечает за состояние интерфейса, сообщения, вывод таблицы и скачивание. В tools находятся сборка, локальный сервер и самостоятельный пример Node.js.

В public уже лежит готовая сборка. Просмотрщик исходников использует точные тексты файлов, а build-info.json содержит их SHA-256. Собственный код распространяется под MIT, лицензии зависимостей сохранены отдельно. Перед переносом в рабочую систему прочитайте README и VPS.md: там перечислены ограничения хранения, формата экспорта и режима нескольких вкладок.

Файл: package.json

{"name":"aen-pglite-workshop","version":"1.0.0","private":true,"type":"module","license":"MIT","engines":{"node":">=22"},"scripts":{"build":"node tools/build.mjs","test":"node --test --test-concurrency=1 tests/*.test.mjs","capture":"node tools/capture.mjs","serve":"node tools/serve.mjs","example":"node tools/example.mjs"},"dependencies":{"@electric-sql/pglite":"0.5.16","bootstrap":"5.3.9"},"devDependencies":{"esbuild":"0.28.2"}}

Пример 1. Модель CRM: клиенты, заявки и журнал

В таблице clients хранятся клиенты, в tickets — заявки, в audit — события изменения. Связь заявки с клиентом задаётся внешним ключом. Код заявки уникален, статус выбирается из трёх допустимых значений, сумма не может быть отрицательной. Эти правила принадлежат данным и проверяются базой независимо от конкретной формы.

Тестовый набор создаётся один раз для версии схемы. Повторный запуск не добавляет ещё восемнадцать одинаковых строк. Отдельная таблица app_meta хранит версию; неизвестная версия приводит к понятной остановке. Это маленькая учебная основа миграций, а не полноценный инструмент управления историей схемы.

Для рабочего проекта разделите создание схемы, заполнение демонстрационных записей и изменение существующих данных. Иначе обновление страницы может неожиданно стереть пользовательский черновик. В мастерской полное восстановление начального набора находится за отдельным подтверждением и затрагивает только её известные таблицы. Команда общего удаления всех браузерных баз не используется.

CREATE TABLE tickets (
  id integer GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
  ref text NOT NULL UNIQUE,
  client_id integer NOT NULL REFERENCES clients(id),
  title text NOT NULL CHECK (length(title) BETWEEN 1 AND 120),
  status text NOT NULL CHECK (status IN ('new','doing','done')),
  amount_cents integer NOT NULL CHECK (amount_cents BETWEEN 0 AND 100000000),
  created_on date NOT NULL,
  meta jsonb NOT NULL DEFAULT '{}'::jsonb
);

Пример 2. Фильтры и параметры вместо склейки SQL

В кабинете оператору нужны новые заявки дороже выбранной суммы. SQL задаёт структуру запроса, а статус и минимальная сумма передаются отдельным массивом. Плейсхолдеры $1 и $2 связываются со значениями по порядку. Если пользователь введёт апостроф или текст, похожий на SQL, он останется значением параметра.

В мастерской замените new на doing. Затем измените минимальную сумму, помня, что она хранится в копейках. В исходном наборе фильтр new и 500000 возвращает пять конкретных заявок. Такой наблюдаемый результат удобнее проверки «ошибки не было»: можно сопоставить строки с условием и сортировкой.

Параметры предназначены для значений, а не для произвольных имён колонок. Если пользователь выбирает поле сортировки, сопоставляйте разрешённые варианты с заранее известными SQL-фрагментами. Не подставляйте непроверенное имя таблицы в строку. В данном проекте таблицы фиксированы, а форма передаёт только ограниченные значения.

const result = await db.query(
  `SELECT ref, title, amount_cents FROM tickets
   WHERE status = $1 AND amount_cents >= $2
   ORDER BY amount_cents DESC`,
  ['new', 500000]
);
console.table(result.rows);

Пример 3. JOIN и сводка для менеджера

Список заявок отвечает на вопрос о конкретной работе, а менеджеру нужна сводка по клиентам. LEFT JOIN соединяет клиентов с заявками и сохраняет строку клиента даже при отсутствии заявок. GROUP BY собирает одну строку на клиента, COUNT считает связанные заявки, SUM суммирует стоимость.

Обратите внимание на count(t.id): при LEFT JOIN он считает существующие заявки. count(*) учитывал бы и строку клиента без заявки, что дало бы неверное количество для пустой группы. COALESCE заменяет отсутствующую сумму нулём. Эти небольшие детали непосредственно влияют на цифры в карточках и отчётах.

В исходном наборе у каждого клиента по три заявки, общая сумма составляет 213750 рублей. Добавьте запись через форму и снова выполните JOIN: итог выбранного клиента изменится. Такой пример легко переносится на заказы магазина, обращения поддержки, документы организации или задачи исполнителей. Сначала определите уровень группировки, затем выбирайте нужные связи.

SELECT c.name, c.region,
       count(t.id)::int AS tickets,
       COALESCE(sum(t.amount_cents),0)::float8 AS amount_cents
FROM clients c
LEFT JOIN tickets t ON t.client_id=c.id
GROUP BY c.id
ORDER BY amount_cents DESC;

Пример 4. JSONB для дополнительных атрибутов

Не каждое свойство заявки удобно превращать в отдельную колонку. Источник, приоритет и набор меток в примере находятся в JSONB. При этом клиент, статус и сумма остаются обычными колонками: по ним строятся связи, ограничения и основные отчёты. Такое разделение делает схему понятнее, чем один огромный JSON со всеми данными.

Оператор ->> извлекает текстовое значение, а @> проверяет содержание указанного JSON-фрагмента. В сценарии выбираются заявки с высоким приоритетом. В параметрах лежит строка JSON, потому что SQL явно преобразует её через ::jsonb. Замените фрагмент на channel: phone и сравните результат.

JSONB не отменяет проектирование структуры. Если поле обязательно для бизнес-операции, проверьте его контракт и решите, где должна находиться гарантия. Случайная опечатка priority вместо другого ключа может дать пустой результат без ошибки синтаксиса. Для крупных наборов также потребуется отдельный анализ индексов и типичных условий поиска.

await db.query(
  `SELECT ref, meta->>'priority' AS priority
   FROM tickets WHERE meta @> $1::jsonb ORDER BY id`,
  [JSON.stringify({priority:'high'})]
);

Пример 5. Форма, INSERT и RETURNING

Форма заявки показывает обычный путь интерфейса: проверить ввод, отправить действие Worker, выполнить параметризованный INSERT и показать результат. RETURNING возвращает созданный идентификатор и поля записи сразу после вставки. Не нужно отдельно искать «последнюю заявку» и надеяться, что это именно нужная строка.

Попробуйте название с апострофом, например O’Reilly. Затем повторите тот же код заявки. Первый ввод сохраняется как текст, второй получает ошибку уникальности. Состояние формы остаётся доступным для исправления, а предыдущая успешная таблица очищается, чтобы её нельзя было принять за результат неудачной операции.

В учебной форме максимум сто заявок. Это прикладной предел демонстрации, а не ограничение PostgreSQL. В сервисе вместо такого числа появятся требования продукта: квота, размер пакета, права пользователя, допустимые статусы. Клиентская валидация улучшает удобство, но серверные операции должны повторно проверять доверенные правила независимо от браузера.

Файл: src/core.mjs

export async function addTicket(db,input) {
  const x=validateTicket(input);
  const count=(await db.query('SELECT count(*)::int AS n FROM tickets')).rows[0].n;
  if(count>=100)throw Error('В учебной базе максимум 100 заявок. Экспортируйте данные и сбросьте примеры.');
  return db.query("INSERT INTO tickets(ref,client_id,title,status,amount_cents,created_on,meta) VALUES($1,$2,$3,'new',$4,'2026-11-18','{\"priority\":\"normal\",\"channel\":\"workshop\"}') RETURNING id,ref,title,status,amount_cents",[x.ref,x.client_id,x.title,x.amount_cents]);
}

Пример 6. Транзакция: статус и аудит вместе

Закрытие заявки меняет две вещи: сам статус и журнал событий. Если первая запись прошла, а вторая завершилась ошибкой, интерфейс не должен показывать половину бизнес-операции. Транзакция объединяет изменения: они подтверждаются вместе либо откатываются вместе. В примере после обеих записей намеренно вызывается исключение.

Нажмите выполнение сценария и сравните before с after, audit_before с audit_after. Значения должны совпасть. Затем используйте отдельную кнопку успешного подтверждения: статус станет done, а журнал получит запись. Это настоящий откат движка, а не ручное восстановление прежнего JavaScript-объекта.

Внутри callback используйте переданный tx, чтобы все обращения относились к одной транзакции. Не держите транзакцию открытой во время долгого пользовательского выбора или стороннего сетевого запроса. Сначала подготовьте необходимые данные, затем выполните короткий согласованный блок. Ошибку нельзя молча проглотить до того, как определено, какой результат должен увидеть вызывающий код.

await db.transaction(async tx => {
  await tx.query("UPDATE tickets SET status='done' WHERE id=$1", [1]);
  await tx.query('INSERT INTO audit(ticket_id,note) VALUES($1,$2)',
    [1, 'Закрытие заявки']);
  throw new Error('Учебный сбой: обе записи будут отменены');
});

Пример 7. UNIQUE, FOREIGN KEY и CHECK

Сценарий ограничений намеренно делает три неправильные операции: дублирует email, ссылается на отсутствующего клиента и записывает отрицательную сумму. PostgreSQL возвращает коды 23505, 23503 и 23514. Каждая попытка выполняется отдельно, поэтому ошибка одной проверки не мешает показать остальные.

Коды полезнее разбора английского текста сообщения. В рабочем интерфейсе 23505 можно сопоставить с понятным объяснением дубликата, а 23503 — с предложением заново выбрать доступную сущность. При этом учитывайте имя конкретного ограничения: в большой таблице уникальных правил может быть несколько, и подсветка произвольного поля только запутает пользователя.

В мастерской технический текст оставлен для обучения. В обычном кабинете не стоит выводить пользователю всю внутреннюю структуру SQL или содержимое служебных данных. Подробности отправляются в разрешённый журнал диагностики, а человеку показывается действие для исправления. Само ограничение остаётся последней проверкой согласованности независимо от оформления сообщения.

PostgreSQL: ограничения таблиц

Почему идентификаторы могут иметь пропуски

После неудачной вставки следующий id может оказаться больше ожидаемого. Это нормальная особенность последовательностей PostgreSQL: получение значения последовательности не обязано откатываться вместе с неуспешной бизнес-операцией. Поэтому ряд идентификаторов не является достоверным счётчиком созданных заявок.

В тестах каждый независимый опыт начинается с собственного восстановленного набора. Это позволяет проверять конкретные строки, не связывая результат теста с тем, сколько ошибок выполнил предыдущий пример. В самой мастерской ошибки можно запускать многократно, поэтому номер новой заявки не обещается заранее.

Если бизнесу нужна особая последовательная нумерация документов, проектируйте её отдельным правилом, учитывая параллельность, отмены и требования к учёту. Не пытайтесь скрыть пропуски простым вычислением max(id)+1: при нескольких исполнителях это создаёт гонки. Технический первичный ключ служит идентификации строки, а номер документа может иметь другую семантику.

SELECT count(*) AS actual_rows, max(id) AS highest_id FROM tickets;

Пример 8. Индекс и EXPLAIN без мифов о скорости

В схеме есть индекс по статусу. Сценарий EXPLAIN показывает реальный план выбора заявок. На восемнадцати строках PostgreSQL может предпочесть последовательное чтение: прочитать маленькую таблицу целиком дешевле, чем обращаться к индексу. Поэтому наличие индекса и его использование в конкретном плане — разные факты.

Начинайте оптимизацию с наблюдаемой задачи: какие запросы выполняются часто, сколько строк просматривается, какие поля участвуют в фильтре и сортировке. Индекс занимает место и обслуживается при изменении данных. Добавлять индекс на каждую колонку без измерений обычно означает дополнительные затраты без понятной пользы.

Мастерская показывает структуру плана, но не обещает серверную производительность на основании браузерного опыта. Скорость зависит от устройства, размера базы и режима хранения. Для рабочего сервера повторите измерение на характерном объёме и реальном окружении. EXPLAIN ANALYZE действительно выполняет запрос, поэтому применяйте его осознанно, особенно для изменяющих операций.

EXPLAIN (FORMAT JSON) SELECT ref FROM tickets WHERE status='new';
SELECT indexname,indexdef FROM pg_indexes
WHERE schemaname='public' AND tablename='tickets';

Пример 9. live.query и живые показатели кабинета

Верхние карточки показывают количество заявок, новые, завершённые и общую сумму. Они подписаны на результат SQL через расширение live. После добавления заявки или подтверждённого изменения таблицы приходит новый результат, а Worker пересылает его интерфейсу. Отдельный счётчик делает события подписки видимыми.

Это удобно для локального кабинета, где одна форма меняет данные, а несколько виджетов должны отразить новое состояние. Не нужно вручную увеличивать каждый счётчик и помнить, какой фильтр действует у соседней карточки. SQL остаётся источником вычисления показателей, а интерфейс получает готовые строки.

Подписку необходимо закрывать при завершении работы. В мастерской сначала вызывается unsubscribe, затем закрывается база. Не создавайте новую подписку на каждое нажатие без удаления прежней: так появятся дублирующие обновления и лишняя работа. live.query здесь реагирует на локальную базу; изменения удалённого сервера сами по себе в неё не попадут.

import {PGlite} from '@electric-sql/pglite';
import {live} from '@electric-sql/pglite/live';
const db = await PGlite.create({extensions:{live}});
const subscription = await db.live.query(
  'SELECT count(*)::int AS n FROM tickets', [],
  result => console.log(result.rows)
);
// Когда подписка больше не нужна:
await subscription.unsubscribe();

PGlite: live queries

Пример 10. Память, IndexedDB и повторное открытие

Режим памяти подходит для первого знакомства: перезапуск создаёт чистый набор. IndexedDB сохраняет базу в браузере текущего origin. Включите этот режим перед запуском, добавьте заявку, остановите базу и снова откройте её. Если хранилище доступно, запись останется. Это отдельный опыт, который нельзя заменить проверкой памяти в Node.js.

Сохранение зависит от браузера, профиля и политики очистки. Приватный режим, удаление данных сайта, смена домена или исчерпание квоты меняют условия. Локальная база не является единственной надёжной копией важных документов. Предусмотрите понятный экспорт либо отдельную серверную синхронизацию с явными правилами конфликтов.

Мастерская использует фиксированное имя собственной базы и синхронное ожидание сохранения, без relaxedDurability. Кнопка остановки корректно закрывает соединение. Принудительное завершение Worker оставлено для зависшего опыта; после него сохранённое состояние следует повторно открыть и проверить. Обещание «всё точно сохранено» появляется только после подтверждённой успешной операции.

const temporary = await PGlite.create({dataDir:'memory://'});
const persistent = await PGlite.create({
  dataDir:'idb://my-application-v1', relaxedDurability:false
});
// Это отдельные базы. Закрывайте каждую после работы:
await temporary.close();
await persistent.close();

PGlite: варианты файловых систем

Несколько вкладок: явное ограничение этой мастерской

Две независимые копии базы не должны бесконтрольно менять одно браузерное хранилище. В текущем проекте выбран простой режим: одна активная IndexedDB-мастерская на origin. Exclusive Web Lock удерживается от открытия до закрытия. Если база занята другой вкладкой, интерфейс сообщает об этом и предлагает закрыть её или использовать память.

Web Locks требуют подходящего браузерного окружения и безопасного контекста: HTTPS либо localhost. Отсутствие API не скрывается автоматическим переходом к другому хранилищу. Это важно для ожиданий пользователя: он должен понимать, сохраняется ли работа или исчезнет после закрытия.

У PGlite есть официальный PGliteWorker для согласованной работы нескольких вкладок с выбором ведущего worker. В архиве добавлены отдельные справочные файлы shared-client и shared-worker для такой интеграции. Текущая мастерская их не запускает. Если вашему продукту нужны несколько вкладок, соберите этот вариант отдельно и проверьте переключение лидера, закрытие вкладок и доступность используемых расширений.

Файл: examples/shared-client.mjs

// Vite example: configure optimizeDeps.exclude and worker.format='es' as in official docs.
// This is a separate integration reference, not the tested workshop's runtime.
import {PGliteWorker} from '@electric-sql/pglite/worker';
const db=new PGliteWorker(new Worker(new URL('./shared-worker.mjs',import.meta.url),{type:'module'}),{id:'my-shared-app-v1',dataDir:'idb://my-shared-app-v1'});
await db.waitReady;
console.log(await db.query('SELECT 1 AS connected'));
// Close the client when the application no longer needs it:
await db.close();

Официальный PGliteWorker и несколько вкладок

Экспорт JSON: перенос конкретных прикладных данных

Экспорт мастерской содержит явные format и version, затем клиентов, заявки и аудит. Его можно скачать или подставить в поле восстановления. Даты сохраняются текстом, JSONB остаётся структурированным значением, идентификаторы сохраняют связи между таблицами. Такое устройство удобно для учебных наборов и небольших пользовательских черновиков.

Это собственный формат приложения, а не полный PostgreSQL dump. В нём нет произвольной схемы, ролей, расширений и настроек сервера. При развитии формата увеличивайте версию и описывайте миграцию. Не пытайтесь импортировать случайную выгрузку другого приложения лишь потому, что она тоже называется JSON.

Размер ограничен двумястами кибибайтами, количество заявок — ста, событий — двумястами. Эти пределы позволяют обработать импорт предсказуемо на телефоне. В обычном сервисе границы выбираются по реальным данным и времени обработки. Перед переносом важной информации полезно проверить не только скачивание, но и обратное восстановление полученного файла.

Файл: src/core.mjs

export async function snapshot(db) {
  return db.transaction(async tx=>({format:'aen-pglite-json',version:1,clients:(await tx.query('SELECT id,name,email,region FROM clients ORDER BY id')).rows,tickets:(await tx.query('SELECT id,ref,client_id,title,status,amount_cents,created_on::text,meta FROM tickets ORDER BY id')).rows,audit:(await tx.query('SELECT id,ticket_id,note FROM audit ORDER BY id')).rows}));
}

Восстановление: проверить, подтвердить, заменить атомарно

Восстановление начинается с проверки формата, версии, типов, размеров, идентификаторов и ссылок. После этого требуется явное подтверждение замены учебных данных. Удаление прежнего набора и вставка нового выполняются внутри одной транзакции. Если SQL отклоняет строку, прежние таблицы должны остаться целыми.

В тестах проверяется не только корректный импорт. В набор специально подставляется невозможная дата: ошибка возникает уже при вставке после начала замены. Сравнение полного снимка подтверждает откат ранее выполненных действий. Это существенно полезнее проверки одного сообщения «импорт не удался».

После вставки явных id обновляются последовательности. Иначе следующий INSERT мог бы попытаться использовать уже занятый номер. Имена таблиц в этом шаге берутся из жёстко заданного списка исходного кода, а не из загруженного JSON. Если вы расширяете формат новыми сущностями, обновите проверку, порядок внешних ключей, восстановление последовательностей и тесты вместе.

Файл: src/core.mjs

export async function restore(db,input) {
  const d=validateSnapshot(input);
  await db.transaction(async tx=>{
    await tx.exec('TRUNCATE audit,tickets,clients RESTART IDENTITY CASCADE');
    for(const c of d.clients)await tx.query('INSERT INTO clients(id,name,email,region) VALUES($1,$2,$3,$4)',[c.id,c.name,c.email,c.region]);
    for(const t of d.tickets)await tx.query('INSERT INTO tickets(id,ref,client_id,title,status,amount_cents,created_on,meta) VALUES($1,$2,$3,$4,$5,$6,$7,$8::jsonb)',[t.id,t.ref,t.client_id,t.title,t.status,t.amount_cents,t.created_on,JSON.stringify(t.meta)]);
    for(const a of d.audit)await tx.query('INSERT INTO audit(id,ticket_id,note) VALUES($1,$2,$3)',[a.id,a.ticket_id,a.note]);
    for(const table of ['clients','tickets','audit'])await tx.query(`SELECT setval(pg_get_serial_sequence('${table}','id'), COALESCE((SELECT max(id) FROM ${table}),1), EXISTS(SELECT 1 FROM ${table}))`);
  });
  return {rows:[{restored_tickets:d.tickets.length,restored_clients:d.clients.length,restored_audit:d.audit.length}]};
}

Редактор SQL: ограничения результата и долгих операций

Редактор принимает один SELECT или WITH длиной до трёх тысяч символов, без комментариев и нескольких команд. Параметры задаются JSON-массивом простых значений. Запрос выполняется в read-only транзакции и оборачивается ограничением вывода. Если строк больше ста, показываются первые сто и отдельная отметка об усечении.

Ограничение строк не гарантирует дешёвое выполнение: агрегат или неудачный JOIN может сначала обработать большой объём. Внутри задаётся statement_timeout, а главный поток имеет собственный предел ожидания и возможность завершить Worker. Эти меры помогают ограничить учебный опыт; регулярное выражение не объявляется универсальным анализатором безопасности SQL.

Кнопка прерывания означает остановку движка, а не подтверждение операции. Память при этом теряется, сохранённую базу потребуется открыть снова. В рабочем интерфейсе лучше предлагать конкретные действия и разрешённые фильтры, чем выдавать произвольный SQL каждому пользователю. Здесь редактор нужен для обучения и работает только с локальным набором.

Файл: src/core.mjs

export async function boundedRead(db,sql,params=[]) {
  if(typeof sql!=='string'||sql.length>3000)throw Error('SQL: максимум 3000 символов.');
  sql=sql.trim().replace(/;$/,'');
  if(!/^(SELECT|WITH)\s/i.test(sql)||/[;]|--|\/\*/.test(sql))throw Error('Здесь разрешён один SELECT/WITH без комментариев. Изменения доступны через примеры и форму.');
  if(!Array.isArray(params)||params.length>10||params.some(x=>!(x===null||typeof x==='string'&&x.length<=1000||typeof x==='boolean'||typeof x==='number'&&Number.isFinite(x))))throw Error('Параметры: JSON-массив до 10 простых значений.');
  return db.transaction(async tx=>{
    await tx.exec("SET TRANSACTION READ ONLY; SET LOCAL statement_timeout='2000ms';");
    const res=await tx.query(`SELECT * FROM (${sql}) AS workshop_result LIMIT 101`,params);
    return {...res,rows:res.rows.slice(0,100),truncated:res.rows.length>100};
  });
}

Деньги, даты, NULL и типы на границе JavaScript

В примере деньги хранятся целыми копейками. Это позволяет складывать небольшие суммы без дробных ошибок JavaScript. Общий итог преобразуется в float8 только в пределах заранее ограниченного набора, где целое число остаётся точным. Такой приём не следует автоматически переносить на произвольно большие обороты и финансовые расчёты.

Для больших значений определите политику numeric, bigint и сериализации JSON. Строка с точным десятичным числом иногда честнее, чем Number, уже потерявший точность. Не преобразуйте все значения базы в число одной общей функцией: идентификаторы, деньги, даты и текст имеют разные требования.

Дата создания здесь календарная, без времени суток. Для реальных событий дополнительно определите часовой пояс и формат момента. NULL показывается явно, а не превращается в пустую строку, чтобы читатель видел отличие отсутствующего значения от текста. На границе SQL и интерфейса полезно проверять типы так же внимательно, как сам запрос.

SELECT ref, amount_cents, created_on::text AS calendar_date,
       meta->>'priority' AS priority
FROM tickets ORDER BY id LIMIT 5;

Почему Worker вынесен отдельно и как собраны WASM-файлы

Долгая работа движка не должна блокировать кнопки страницы. Поэтому все обращения к PGlite идут через dedicated Worker. Сообщения внутри worker обрабатываются последовательно. Интерфейс блокирует повторное действие на время текущей операции, показывает состояние и очищает старый результат при ошибке.

Сборка через esbuild не должна терять бинарные файлы движка. Скрипт явно копирует pglite.wasm, initdb.wasm и pglite.data в vendor, а worker загружает их по относительным адресам. Модули WebAssembly компилируются и передаются в PGlite.create вместе с fsBundle. Проверяется HTTP-статус каждого файла, чтобы ответ 404 не превратился в непонятную ошибку компиляции.

При переносе сохраняйте расположение worker.js и vendor. Обновляйте согласованный набор файлов, не смешивая старую WASM с новым JavaScript. Источник node:* в универсальной зависимости оставлен внешним для браузерной сборки; браузерная ветка его не исполняет. Для другой сборочной системы следуйте её правилам обработки assets и повторяйте настоящий запуск.

PGlite: подключение к сборщикам

Windows: первый запуск и воспроизводимые проверки

Распакуйте архив в отдельную папку и откройте там PowerShell. Понадобится поддерживаемая Node.js версии 22 или новее. npm ci устанавливает зависимости по lockfile, build собирает мастерскую, test выполняет SQL-проверки. Затем локальный сервер отдаёт public на адресе 127.0.0.1:8578.

Не открывайте HTML двойным щелчком через file://. Worker, модули и загрузка WASM рассчитаны на HTTP. На localhost доступен необходимый безопасный контекст. Если PowerShell ограничивает запуск npm.ps1, команды npm.cmd обращаются к Windows-обёртке без изменения системной политики выполнения сценариев.

В данной работе SQL и файловое хранение действительно проверены в Windows с Node.js 24.19.0. Такая проверка подтверждает код базы и транзакций, но сама по себе не подтверждает IndexedDB или мобильную вёрстку. Для них нужен отдельный браузерный опыт. Локальный сервер завершается Ctrl+C и не устанавливается постоянной службой.

node --version
npm.cmd ci
npm.cmd run build
npm.cmd test
npm.cmd run serve
# Откройте http://127.0.0.1:8578
# Остановка сервера: Ctrl+C

Linux: тот же проект, отдельная проверка окружения

На Linux исходники и lockfile те же. Разница в оболочке появляется при задании переменных окружения и путей. Для обычного знакомства достаточно npm ci, сборки и локального HTTP-сервера. Для повторения всего runtime-маршрута в архиве есть shell-сценарий, который устанавливает зависимости, собирает проект, запускает тесты и пример.

Проверка этой версии выполнена в изолированном Linux-контейнере с Node.js 24.22.3. В обеих средах прошли восемнадцать тестов: параметры, JOIN, JSONB, ограничения, откат, live.query, экспорт, восстановление и повторное открытие файловой базы. Отдельно сохранены результаты десяти сценариев и контрольные снимки.

Контейнерная проверка не является установкой на ваш VPS. Права каталогов, HTTPS, MIME файлов и политика браузерного хранения проверяются уже в конкретном размещении. Docker нужен только для воспроизводимого контейнерного варианта; браузерной странице и обычному запуску Node.js он не требуется.

npm ci
npm run build
npm test
npm run serve
# Полная последовательность проверок:
sh tools/run-linux-check.sh
# Необязательный контейнерный пример:
docker build -t aen-pglite-example .
docker run --rm --name aen-pglite-example aen-pglite-example

Node.js: отдельная файловая база без браузера

Самостоятельный пример создаёт ту же схему, выводит версию PostgreSQL, общие показатели и сводку клиентов. По умолчанию используется память. Если задан DATA_DIR, PGlite сохраняет данные в указанной директории. После работы соединение закрывается в finally, поэтому нормальное завершение не оставляет базу открытой.

Повторите запуск дважды с одной отдельной директорией: начальный набор не удвоится. Для проверки сохранности тест создаёт собственную временную базу, добавляет запись, закрывает её, открывает снова и сравнивает значение. После проверки удаляется только созданная тестом временная папка.

Не направляйте несколько процессов на один файловый каталог. Не храните его внутри публичной папки сайта. Если данные нужны нескольким экземплярам сервиса, оцените обычный сервер PostgreSQL и соответствующий драйвер. Встроенная база удобна для локальных инструментов, изолированных процессов и испытаний; это не повод скрывать модель конкурентного доступа от разработчиков приложения.

Файл: tools/example.mjs

import {PGlite} from '@electric-sql/pglite';import {seed,queries} from '../src/core.mjs';
const db=await PGlite.create(process.env.DATA_DIR||'memory://');
try{await seed(db);console.log(JSON.stringify({version:(await db.query('SELECT version() AS v')).rows[0].v,summary:(await db.query(queries.summary)).rows[0],clients:(await db.query(queries.join)).rows},null,2));}finally{await db.close();}
$env:DATA_DIR = './runtime/my-database'
npm.cmd run example
Remove-Item Env:DATA_DIR
DATA_DIR=./runtime/my-database npm run example

Linux/VPS: раздать мастерскую через HTTPS

Для браузерного варианта VPS обслуживает статические файлы. Устанавливать PostgreSQL на сервер ради этой страницы не нужно. Соберите проект в рабочем каталоге, перенесите только содержимое public в отдельную директорию сайта и сохраните предыдущий релиз для отката. Не выкладывайте node_modules, локальную файловую базу и служебные отчёты.

В VPS.md приведены варианты Caddy и Nginx. Caddy-блок ниже рассчитан на свой домен с настроенным DNS и доступными портами. В существующую конфигурацию добавляется отдельный сайт, а не заменяется весь файл. Перед reload выполните проверку конфигурации и убедитесь, что worker.js и файлы vendor доступны по ожидаемым адресам.

WASM должен отдаваться с корректным MIME, JavaScript — как JavaScript. После выкладки повторите старт, вставку, live-обновление и сохранение IndexedDB. Факт успешного копирования файлов не доказывает работоспособность Worker в реальном origin. Для iframe на другом домене потребуется отдельная проверка правил хранения и доступа.

pglite.example.com {
    root * /var/www/pglite-demo
    encode zstd gzip
    header X-Content-Type-Options nosniff
    file_server
}
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -I https://pglite.example.com/vendor/pglite.wasm
curl -I https://pglite.example.com/worker.js

Nginx: отдельный путь и согласованное обновление файлов

Если на VPS уже работает Nginx с HTTPS, мастерскую можно разместить под отдельным путём /pglite/. В примере alias указывает на выделенную директорию, а include подключает таблицу MIME. Убедитесь, что в действующем mime.types присутствует application/wasm для расширения wasm. После изменения выполняются nginx -t и управляемый reload.

Для учебной раздачи показан Cache-Control: no-cache: браузер должен перепроверять актуальность ресурса. Это не означает запрета хранения вообще. Для долгого производительного кеширования обычно используют имена файлов с хешами и переключают согласованный релиз целиком. Нельзя бесконтрольно закешировать worker навсегда и затем заменить только его бинарные зависимости.

Не добавляйте CORS со звёздочкой просто ради запуска. В этой мастерской все файлы доступны с одного origin, и такая настройка не нужна. Подробные материалы сайта про Caddy и Nginx помогут настроить общий контур сервера; конкретная PGlite-страница остаётся статической и не требует публичного SQL endpoint.

location /pglite/ {
    alias /var/www/pglite-demo/;
    index index.html;
    include /etc/nginx/mime.types;
    default_type application/octet-stream;
    add_header X-Content-Type-Options nosniff;
    add_header Cache-Control "no-cache";
}

Практика Caddy · Настройки и диагностика Nginx

PGlite, SQLite, DuckDB и обычный PostgreSQL

Выбирайте движок по задаче, а не по похожему синтаксису SELECT. PGlite полезен, когда нужен PostgreSQL рядом с JavaScript: его типы, JSONB, ограничения и поведение транзакций. SQLite удобен для множества встроенных сценариев и имеет собственные правила типов и расширений. DuckDB ориентирован на аналитическую обработку данных, включая файловые выгрузки.

Обычный PostgreSQL-сервер нужен там, где общие данные должны обслуживать несколько клиентов и процессов с серверными правилами доступа и эксплуатации. Наличие PostgreSQL внутри браузера не переносит туда автоматически всю серверную архитектуру. Синхронизация, авторизация и разрешение конфликтов остаются отдельными задачами приложения.

На сайте есть материалы по SQLite, DuckDB и Kysely. В большом PHP-мануале разделы SQL, PDO и SQLite полезны для повторения запросов, параметров и транзакций, но PHP-код оттуда не запускает PGlite в браузере. Сопоставляйте общие принципы, а различия конкретного движка проверяйте на исполняемом примере.

Как превратить пример в удобный интерфейс сервиса

Начните с пользовательской задачи. Для оператора это поиск заявки, изменение статуса и понятный результат сохранения. Для руководителя — сводка и переход к деталям. Для исследователя выгрузки — фильтры, таблица и экспорт. SQL-консоль оставьте учебным или административным инструментом, если обычному пользователю она не помогает выполнить работу.

Показывайте режим хранения рядом с действием, а не в скрытой справке. Человек должен понимать, исчезнет ли черновик после закрытия, где лежит сохранённая база и как сделать копию. Ошибка квоты или занятой вкладки требует конкретного следующего шага. Сообщение «что-то пошло не так» не объясняет, можно ли безопасно повторить операцию.

На телефоне основные действия должны оставаться доступны без горизонтальной прокрутки всей страницы. Прокрутка нужна только таблицам и длинному коду. Сохраняйте видимые подписи полей, состояние загрузки, клавиатурный фокус и обратную связь после сохранения. Удобство такого инструмента определяется не только успешным запросом, но и поведением при ошибке и закрытии.

Чего эта мастерская не обещает

В проекте нет автоматической синхронизации с сервером и разрешения конфликтов между устройствами. Запись на одном телефоне не появляется сама на другом. Нет service worker, поэтому уже загруженная база и гарантированная повторная загрузка всей страницы без сети — разные свойства. Для полноценного автономного приложения потребуется отдельная стратегия кеширования ресурсов.

Браузерная база не хранит секрет от владельца браузера. Пользователь может изучить код и изменить локальные данные. Не принимайте присланную сумму заказа или роль пользователя за доверенную только потому, что она вычислена SQL. Сервер должен заново проверить важную операцию по своим правилам и доступным полномочиям.

Размер учебного набора выбран для понятного опыта, а не для демонстрации предельной производительности. Возможности расширений и совместимость с конкретным приложением проверяются отдельно. Если ваш проект рассчитывает на необычное расширение PostgreSQL, большое число параллельных запросов или серверные инструменты обслуживания, начните с маленького проверяемого прототипа именно этих требований.

Проверки, исходники и официальная документация

Архив содержит готовую мастерскую, исходные модули, Node.js-пример, тесты, Dockerfile, Linux-сценарий и инструкции размещения. Можно открыть точный файл прямо на странице, скопировать его или скачать отдельно. После изменения схемы повторяйте тесты параметров, ограничений, транзакций и восстановления, затем проверяйте браузерный запуск с тем же набором assets.

Особенно полезны отрицательные проверки: неверный JSON, повтор кода, отсутствующий клиент, ошибка даты в середине восстановления, остановка Worker и занятая база в соседней вкладке. Они показывают, останутся ли данные согласованными и поймёт ли пользователь результат. Успешный первый SELECT проверяет лишь небольшую часть жизненного цикла.

Начните собственный проект с одной полезной задачи и ясного режима хранения. Затем добавляйте импорт, миграции и синхронизацию только вместе с проверяемыми правилами. Официальные материалы ниже описывают API и ограничения PGlite, а мастерская связывает их с полноценным набором данных и наблюдаемыми действиями интерфейса.