Метод fromSQL

Метод DateTime.fromSQL в библиотеке Luxon используется для преобразования строкового представления даты и времени в формате SQL (или близком к нему) в объект DateTime. Основное назначение — работа с датами, полученными из SQL-баз данных, где стандартом являются форматы YYYY-MM-DD и YYYY-MM-DD HH:mm:ss, иногда с указанием часового пояса.

Метод обеспечивает строгий и предсказуемый парсинг, минимизируя неоднозначности, характерные для встроенного Date.parse.

Сигнатура метода

DateTime.fromSQL(text, options)

text — строка в SQL-формате options — необязательный объект конфигурации

Поддерживаемые форматы SQL

Метод корректно обрабатывает несколько распространённых вариантов:

  • YYYY-MM-DD
  • YYYY-MM-DD HH:mm
  • YYYY-MM-DD HH:mm:ss
  • YYYY-MM-DD HH:mm:ss.SSS
  • YYYY-MM-DDTHH:mm:ss (частично совместимый ISO-вариант)
  • Форматы с временной зоной: YYYY-MM-DD HH:mm:ss Z или YYYY-MM-DD HH:mm:ss±HH:mm

Поведение парсинга

При разборе строки Luxon:

  • интерпретирует дату как локальную, если не указана зона
  • корректно извлекает время, если оно присутствует
  • поддерживает миллисекунды с произвольной точностью (усечение до 3 знаков)
  • при наличии временной зоны применяет её к результату

Если строка не соответствует SQL-подобному формату, возвращается Invalid DateTime.

Использование без параметров

import { DateTime } from "luxon";

const dt = DateTime.fromSQL("2026-05-23 14:30:00");

Результат:

  • дата: 23 мая 2026
  • время: 14:30:00
  • зона: локальная (если не указано иное)

Разбор даты без времени

const dt = DateTime.fromSQL("2026-05-23");

В этом случае время устанавливается в 00:00:00.

Такая форма часто используется при работе с колонками типа DATE в SQL.

Разбор с миллисекундами

const dt = DateTime.fromSQL("2026-05-23 14:30:00.125");

Миллисекунды сохраняются и доступны через:

dt.millisecond

Работа с временными зонами

SQL-строки могут содержать смещение:

const dt = DateTime.fromSQL("2026-05-23 14:30:00+03:00");

В этом случае Luxon:

  • распознаёт смещение +03:00
  • корректно нормализует момент времени
  • позволяет конвертировать в другие зоны

Пример конвертации:

dt.setZone("UTC").toString();

Использование объекта опций

Метод поддерживает дополнительную конфигурацию:

DateTime.fromSQL(text, {
  zone,
  setZone,
  locale
})

zone

Позволяет задать временную зону вручную:

DateTime.fromSQL("2026-05-23 14:30:00", {
  zone: "Europe/Paris"
});

Если строка не содержит зоны, используется указанная.

setZone

Определяет, следует ли сохранять исходную зону строки:

DateTime.fromSQL("2026-05-23 14:30:00+02:00", {
  setZone: true
});
  • true — сохраняет зону из строки
  • false — преобразует к зоне по умолчанию

locale

Позволяет задать локаль объекта:

DateTime.fromSQL("2026-05-23 14:30:00", {
  locale: "ru"
});

Локаль влияет на форматирование, но не на сам процесс парсинга.

Отличие от fromISO

fromSQL и fromISO часто используются в схожих задачах, но имеют разные ожидания:

  • fromSQL ориентирован на пробельные разделители и классические SQL-форматы
  • fromISO требует строгого ISO 8601 с T

Примеры различий:

DateTime.fromSQL("2026-05-23 14:30:00"); // корректно
DateTime.fromISO("2026-05-23 14:30:00"); // может быть некорректно
DateTime.fromISO("2026-05-23T14:30:00"); // корректно
DateTime.fromSQL("2026-05-23T14:30:00");  // тоже корректно, но менее строго

Работа с базами данных

SQL-форматы часто возвращаются из:

  • PostgreSQL
  • MySQL
  • SQLite
  • MSSQL

Пример результата запроса:

SEL ECT created_at FR OM users;
-- "2026-05-23 14:30:00"

В Jav * aScript:

const createdAt = DateTime.fromSQL(row.created_at);

Проблемы с часовыми поясами в БД

Частая ситуация — база хранит время без зоны:

2026-05-23 14:30:00

Luxon в этом случае интерпретирует значение как локальное. Это может приводить к смещениям при работе в распределённых системах.

Решение:

DateTime.fromSQL(value, {
  zone: "UTC"
});

Обработка некорректных строк

Если строка не соответствует SQL-формату:

const dt = DateTime.fromSQL("invalid date");

Результат:

dt.isValid === false

Проверка валидности обязательна при работе с внешними источниками данных.

Нормализация входных данных

В реальных системах часто встречаются вариации:

  • лишние пробелы
  • отсутствие секунд
  • смешанные разделители

Пример устойчивой обработки:

const dt = DateTime.fromSQL(rawValue.trim());

Особенности парсинга времени без секунд

DateTime.fromSQL("2026-05-23 14:30");

Luxon автоматически интерпретирует:

14:30:00

Влияние локали на результат

Локаль не влияет на разбор строки, но влияет на вывод:

const dt = DateTime.fromSQL("2026-05-23 14:30:00", {
  locale: "fr"
});

dt.toLocaleString(DateTime.DATETIME_FULL);

Преобразование результата

После создания объекта доступны стандартные операции Luxon:

dt.toISO();
dt.toSQL();
dt.toMillis();
dt.toFormat("dd.MM.yyyy HH:mm");

Сравнение с ручным парсингом Date

Использование стандартного Date:

new Date("2026-05-23 14:30:00");

имеет неоднозначное поведение в разных окружениях.

Luxon через fromSQL:

  • не зависит от реализации движка
  • стабильно интерпретирует формат
  • явно управляет зоной и локалью

Обработка даты с неполной информацией

Если строка содержит только дату:

DateTime.fromSQL("2026-05-23");

все временные поля устанавливаются в ноль:

  • часы: 0
  • минуты: 0
  • секунды: 0
  • миллисекунды: 0

Внутренняя логика интерпретации

Метод выполняет последовательность шагов:

  1. Проверка соответствия SQL-паттерну
  2. Разделение даты и времени
  3. Извлечение компонентов (год, месяц, день, часы и т.д.)
  4. Обработка зоны, если она присутствует
  5. Применение локали и настроек окружения
  6. Создание экземпляра DateTime

Использование в серверных приложениях

При обработке API-ответов:

app.get("/users", (req, res) => {
  const users = data.map(u => ({
    ...u,
    createdAt: DateTime.fromSQL(u.created_at)
  }));
});

Использование в ORM слоях

При интеграции с ORM:

class User {
  constructor(row) {
    this.createdAt = DateTime.fromSQL(row.created_at);
  }
}

Такой подход позволяет унифицировать работу с датами на уровне модели данных.

Потенциальные ошибки интерпретации

Основные источники проблем:

  • отсутствие временной зоны в строке
  • разные форматы между таблицами
  • неконсистентные строки (например, смешение ISO и SQL)

Пример проблемной строки:

2026/05/23 14:30:00

Она не будет распознана корректно без предварительной нормализации.

Стратегии защиты данных

При работе с неизвестными источниками:

const dt = DateTime.fromSQL(value);

if (!dt.isValid) {
  // fallback логика
}

Производительность

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

Оглавление