Что такое Unix time и эпоха
Unix time (он же Unix timestamp, "юникс-время", метка времени) хранит момент времени одним числом: количеством секунд, прошедших с 00:00:00 UTC 1 января 1970 года. Эта точка отсчёта называется эпохой Unix. Число 0 означает как раз эпоху, 946684800 это начало 2000 года, а 1700000000 это 14 ноября 2023 года, 22:13:20 по UTC.
Одно число удобно хранить в базах, передавать в API и сравнивать: чтобы узнать, какое из двух событий произошло раньше, достаточно сравнить два целых числа. Не нужны ни форматы дат, ни разбор строк. Поэтому метки времени есть в логах, токенах JWT, ответах REST API, заголовках кэша и полях баз данных.
Если вам нужно быстро перевести число в дату или наоборот, воспользуйтесь конвертером Unix time.
Конвертер Unix time
Секунды и миллисекунды
Классическая метка это секунды, и сегодня она состоит из 10 цифр. Но многие системы, в первую очередь JavaScript и Java, считают в миллисекундах, и тогда число содержит 13 цифр. Если вы получили метку 1700000000123 и подставили её как секунды, дата окажется в далёком будущем (около 55800 года). Обратная ошибка отправит вас в январь 1970 года.
| Единица | Пример | Цифр сейчас | Где встречается |
|---|---|---|---|
| Секунды | 1700000000 | 10 | Linux, Python time.time(), PHP time(), PostgreSQL, MySQL |
| Миллисекунды | 1700000000123 | 13 | JavaScript Date.now(), Java, Kotlin |
| Микросекунды | 1700000000123456 | 16 | Python datetime, некоторые базы данных |
| Наносекунды | 1700000000123456789 | 19 | Go, InfluxDB, логи трассировки |
Правило простое: считайте цифры. Десять это секунды, тринадцать это миллисекунды. Для перевода миллисекунд в секунды делите на 1000.
Unix time и часовые пояса
Метка времени не зависит от часового пояса. Она всегда отсчитывается от эпохи по UTC, и в любой точке мира в один и тот же момент у неё одно и то же значение. Часовой пояс появляется только при показе числа человеку: 1700000000 это 22:13:20 по UTC, 01:13:20 по Москве (UTC+3) и 17:13:20 в Нью-Йорке (UTC-5).
Из этого вытекает главное практическое правило: храните и передавайте время в UTC или в виде метки, а пояс применяйте только на экране пользователя. Тогда не придётся разбираться с летним временем и переездами пользователей.
Ещё одна особенность: в Unix time не учитываются високосные секунды. Каждый день в нём ровно 86400 секунд, поэтому разность двух меток всегда делится на сутки без остатка.
Перевод в Python
Для работы со временем в Python есть модули time, datetime и zoneinfo (последний входит в стандартную библиотеку начиная с Python 3.9). Если вы только начали изучать язык, пригодится статья про модуль datetime.
Сначала получим текущую метку и переведём известное число в дату с поясом UTC.
import time
from datetime import datetime, timezone
now = int(time.time()) # секунды, целое число
print(now)
ts = 1700000000
dt = datetime.fromtimestamp(ts, tz=timezone.utc)
print(dt) # 2023-11-14 22:13:20+00:00
Второй аргумент tz важен. Без него fromtimestamp вернёт наивное время в часовом поясе вашего компьютера, и на сервере в UTC результат будет другим, чем у вас на ноутбуке. Старую функцию utcfromtimestamp использовать не стоит: она объявлена устаревшей.
Чтобы показать время в нужном поясе, используйте ZoneInfo. На Windows для базы часовых поясов может понадобиться пакет tzdata: pip install tzdata. Об установке пакетов подробнее в статье про виртуальное окружение venv.
from datetime import datetime
from zoneinfo import ZoneInfo
dt = datetime.fromtimestamp(1700000000, tz=ZoneInfo("Europe/Moscow"))
print(dt) # 2023-11-15 01:13:20+03:00
print(dt.strftime("%d.%m.%Y %H:%M:%S")) # 15.11.2023 01:13:20
Обратное действие: из даты в метку. Дата обязательно должна быть с поясом, иначе Python сочтёт её местной.
from datetime import datetime, timezone
dt = datetime(2023, 11, 14, 22, 13, 20, tzinfo=timezone.utc)
print(int(dt.timestamp())) # 1700000000
# из строки в формате ISO 8601
dt = datetime.fromisoformat("2023-11-14T22:13:20+00:00")
print(int(dt.timestamp())) # 1700000000
# метка в миллисекундах делится на 1000
print(datetime.fromtimestamp(1700000000123 / 1000, tz=timezone.utc))
Частая ошибка: datetime.now().timestamp() и datetime(2023, 11, 14).timestamp() трактуют наивное время как местное. Для сравнения событий с разных серверов всегда создавайте дату с tzinfo или берите datetime.now(timezone.utc).
Перевод в JavaScript
В JavaScript объект Date работает с миллисекундами, поэтому секундную метку нужно умножить на 1000, а результат Date.now() поделить на 1000 для секунд.
// метка в секундах -> дата
const ts = 1700000000;
const d = new Date(ts * 1000);
console.log(d.toISOString()); // 2023-11-14T22:13:20.000Z
// дата -> метка в секундах
const sec = Math.floor(Date.now() / 1000);
console.log(sec);
// из строки ISO
console.log(Date.parse("2023-11-14T22:13:20Z") / 1000); // 1700000000
// в нужном поясе
console.log(d.toLocaleString("ru-RU", { timeZone: "Europe/Moscow" }));
// 15.11.2023, 01:13:20
Строки без указания пояса, например "2023-11-14T22:13:20", разбираются как местное время браузера, а строка только с датой "2023-11-14" как UTC. Эта разница ломает много интерфейсов, поэтому в строке всегда указывайте Z или смещение.
Перевод в SQL
Каждая СУБД умеет переводить метки в тип даты и обратно. Основы запросов описаны в статье про SQL запросы с примерами.
PostgreSQL
Функция to_timestamp принимает секунды и возвращает значение типа timestamptz. Обратно метку даёт extract(epoch from ...). Если вы только начинаете работать с этой СУБД, загляните в руководство по PostgreSQL.
-- метка -> дата и время
SELECT to_timestamp(1700000000);
-- 2023-11-14 22:13:20+00 (вид зависит от пояса сеанса)
-- то же в UTC без пояса
SELECT to_timestamp(1700000000) AT TIME ZONE 'UTC';
-- дата -> метка
SELECT extract(epoch FROM TIMESTAMPTZ '2023-11-14 22:13:20+00');
-- текущая метка
SELECT extract(epoch FROM now())::bigint;
MySQL
В MySQL используйте FROM_UNIXTIME и UNIX_TIMESTAMP. Обе функции работают с часовым поясом текущего сеанса, поэтому результат зависит от настройки time_zone.
-- метка -> дата и время в поясе сеанса
SELECT FROM_UNIXTIME(1700000000);
-- с форматом
SELECT FROM_UNIXTIME(1700000000, '%d.%m.%Y %H:%i:%s');
-- дата -> метка
SELECT UNIX_TIMESTAMP('2023-11-14 22:13:20');
-- текущая метка
SELECT UNIX_TIMESTAMP();
Чтобы результат не зависел от настроек сервера, выполните SET time_zone = '+00:00'; перед запросами. Учтите и то, что тип TIMESTAMP в MySQL заканчивается 19 января 2038 года, о чём речь ниже.
| Задача | PostgreSQL | MySQL |
|---|---|---|
| Метка в дату | to_timestamp(ts) | FROM_UNIXTIME(ts) |
| Дата в метку | extract(epoch from d) | UNIX_TIMESTAMP(d) |
| Текущая метка | extract(epoch from now()) | UNIX_TIMESTAMP() |
Перевод в терминале Linux
В Linux всё делает утилита date из GNU coreutils. Текущая метка получается через формат %s. Для перевода числа в дату перед ним ставят символ @. Основы работы в консоли разобраны в статье про команды Linux.
date +%s # текущая метка в секундах
date +%s%3N # в миллисекундах (GNU date)
date -d @1700000000 # в местном поясе
date -u -d @1700000000 # в UTC
# Tue Nov 14 22:13:20 UTC 2023
date -d "2023-11-14 22:13:20 UTC" +%s # дата -> метка
# 1700000000
TZ=Europe/Moscow date -d @1700000000 # в нужном поясе
На macOS и BSD утилита date устроена иначе: вместо -d @метка там пишут date -r 1700000000, а флаг -d означает другое.
Проблема 2038 года
Если метка времени хранится в знаковом 32-битном целом числе, наибольшее значение равно 2147483647. Оно соответствует 03:14:07 по UTC 19 января 2038 года. В следующую секунду число переполнится и станет отрицательным, а система решит, что наступил 1901 год.
Современные 64-битные системы хранят время в 64-битных числах, и их предел отстоит от нас на сотни миллиардов лет. Проблема остаётся в старых встроенных устройствах, в 32-битном ПО, в полях баз данных типа INT и в типе MySQL TIMESTAMP. Если вы проектируете таблицу, для меток времени выбирайте BIGINT или нативный тип даты с запасом: DATETIME в MySQL, timestamptz в PostgreSQL.
from datetime import datetime, timezone
print(datetime.fromtimestamp(2**31 - 1, tz=timezone.utc))
# 2038-01-19 03:14:07+00:00
Python на 64-битных системах эту границу спокойно переходит, а вот на некоторых платформах, например на Windows, fromtimestamp для отрицательных и очень больших значений может выдать OSError или OverflowError.
Частые ошибки при работе с метками времени
- Путаница секунд и миллисекунд: проверяйте число цифр, 10 или 13.
- Наивное время без пояса: считайте любые даты в базе и API временем в UTC и пишите это в документации.
- Хранение метки в строке или в типе FLOAT: теряется точность, лучше целое число.
- Переводы часов на летнее время при сложении "24 часов": прибавляйте секунды к метке, а календарные дни считайте в нужном поясе.
- Сравнение метки и даты в разных поясах: сначала приведите обе к UTC.
Метка времени в JWT-токенах (поля exp, iat) задаётся в секундах, а не в миллисекундах. Если вы подставили Date.now() без деления на 1000, токен "проживёт" десятки тысяч лет.
