Типы для даты и времени

Имя Формат Описание

Имя	Формат	Описание
`DATE`	`YYYY-MM-DD`	Даты
`TIME`	`[YYYY-MM-DD ]HH:MM[:SS][.MS]`	Время
`TIMESTAMP`	`YYYY-MM-DD hh:mm[:ss][.zzzzzz]`	Моменты времени
`TIMESTAMPTZ`	`YYYY-MM-DD hh:mm[:ss][.zzzzzz][+-TT[:tt] \| ZONE]`	Моменты времени с часовым поясом

DATE

YYYY-MM-DD

Даты

TIME

[YYYY-MM-DD ]HH:MM[:SS][.MS]

Время

TIMESTAMP

YYYY-MM-DD hh:mm[:ss][.zzzzzz]

Моменты времени

TIMESTAMPTZ

YYYY-MM-DD hh:mm[:ss][.zzzzzz][+-TT[:tt] | ZONE]

Моменты времени с часовым поясом

Даты

DATE

Тип DATE используется для хранения даты (сочетание года, месяца и дня). Даты считаются по Григорианскому календарю, даже для времени до его введения.

Данные для этого типа должны быть отформатированы в соответствии со стандартом ISO 8601:
YYYY-MM-DD.

Время

TIME

Тип TIME используется для хранения времени (часы, минуты, секунды и микросекунды внутри суток).

Данные для этого типа должны быть отформатированы в соответствии со стандартом ISO 8601:
[YYYY-MM-DD ]HH:MM:SS[.MS].

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

Моменты времени

TIMESTAMP
TIMESTAMPTZ

Типы TIMESTAMP и TIMESTAMPTZ используются для хранения временных меток — конкретных моментов времени. Они объединяют информацию о дате (тип DATE) и времени (тип TIME).

Для типа TIMESTAMP данные должны быть отформатированы в соответствии со стандартом ISO 8601:
YYYY-MM-DD hh:mm:ss[.zzzzzz].

Для типа TIMESTAMPTZ (TIMESTAMP TIME ZONE) данные должны быть отформатированы так же, но допускается добавление часового пояса:
YYYY-MM-DD hh:mm:ss[.zzzzzz][+-TT[:tt] | ZONE].

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

Часовые пояса могут задаваться либо через отступ в часах от указанного времени (+01, -01), либо через явное указание идентификатора из списка часовых поясов tz_database.

Примеры

Создадим таблицу dates со столбцами, имеющими типы DATE, TIME и TIMESTAMP и запишем в них различные валидные значения:

CREATE TABLE dates(
    date DATE,
    time TIME,
    timestamp TIMESTAMP);

INSERT INTO dates VALUES
    ('2025-01-02', '1:1', '2025-01-02 1:1:00'),
    ('2025-01-02', '1:01:11', '2025-01-02 1:1:11.111'),
    ('2025-01-02', '01:01:11.1234567', '2025-01-02 1:1:11.1234567');

SELECT * FROM dates;

+------------+-----------------+----------------------------+
|    date    |       time      |          timestamp         |
+------------+-----------------+----------------------------+
| 2025-01-02 | 01:01:00        | 2025-01-02 01:01:00        |
+------------+-----------------+----------------------------+
| 2025-01-02 | 01:01:11        | 2025-01-02 01:01:11.111000 |
+------------+-----------------+----------------------------+
| 2025-01-02 | 01:01:11.123456 | 2025-01-02 01:01:11.123456 |
+------------+-----------------+----------------------------+

Обратите внимание, что в программном выводе в столбце time время отображается в стандартном виде и с обязательным значением секунд (несмотря на различные способы ввода). В столбце timestamp время также отображается в стандартном виде. Микросекунды отображаются, только если они были заданы и с точностью в 6 знаков.

Создадим таблицу time_stamps со столбцами, имеющими типы TIMESTAMP и TIMESTAMPTZ и запишем в них одни и те же пары значений - с указанием часового пояса и без:

CREATE TABLE time_stamps(
    timestamp TIMESTAMP,
    timestamptz TIMESTAMPTZ);

INSERT INTO time_stamps VALUES
    ('2025-01-02 0:0:0',       '2025-01-02 0:0:0'),
    ('2025-01-02 0:0:0+01:00', '2025-01-02 0:0:0+01:00');

SELECT * FROM time_stamps;

+---------------------+---------------------------+
|      timestamp      |        timestamptz        |
+---------------------+---------------------------+
| 2025-01-02 00:00:00 | 2025-01-02 00:00:00+00:00 |
+---------------------+---------------------------+
| 2025-01-01 23:00:00 | 2025-01-01 23:00:00+00:00 |
+---------------------+---------------------------+

Обратите внимание, что в обоих случаях указание на часовой пояс обрабатывается верно, но в случае TIMESTAMPTZ оно сохраняется в таблице, а в случае типа TIMESTAMP — нет.

Для демонстрации работы с часовыми поясами вставим в таблицу time_stamps значения времени с разными указаниями часового пояса. Для наглядности вставим одни и те значения в две колонки с типами VARCHAR и TIMESTAMPTZ:

CREATE TABLE time_stamps(
    timestampt_text VARCHAR,
    timestamptz TIMESTAMPTZ);

INSERT INTO time_stamps VALUES
    ('2025-01-01 0:0:0 UTC', '2025-01-01 0:0:0 UTC'),
    ('2025-01-01 0:0:0 CET', '2025-01-01 0:0:0 CET'),
    ('2025-01-01 0:0:0+01' , '2025-01-01 0:0:0+01' ),
    ('2025-01-01 0:0:0-01' , '2025-01-01 0:0:0-01' ),
    ('2025-01-01 0:0:0+25' , '2025-01-01 0:0:0+25' ),
    ('2025-01-01 0:0:0-25' , '2025-01-01 0:0:0-25' );

SELECT * FROM time_stamps;

+----------------------+---------------------------+
|    timestampt_text   |        timestamptz        |
+----------------------+---------------------------+
| 2025-01-01 0:0:0 UTC | 2025-01-01 00:00:00+00:00 |
+----------------------+---------------------------+
| 2025-01-01 0:0:0 CET | 2024-12-31 23:00:00+00:00 |
+----------------------+---------------------------+
| 2025-01-01 0:0:0+01  | 2024-12-31 23:00:00+00:00 |
+----------------------+---------------------------+
| 2025-01-01 0:0:0-01  | 2025-01-01 01:00:00+00:00 |
+----------------------+---------------------------+
| 2025-01-01 0:0:0+25  | 2024-12-30 23:00:00+00:00 |
+----------------------+---------------------------+
| 2025-01-01 0:0:0-25  | 2025-01-02 01:00:00+00:00 |
+----------------------+---------------------------+

Попробуем ввести в таблицу dates невалидные данные:

CREATE TABLE dates(
    date DATE);

INSERT INTO dates VALUES
    ('2025-12-13'),
    ('2025-13-13');

ERROR: ConversionException: Conversion Error: date field value out of range:
"2025-13-13"

Данные не могут быть введены, так как задан невалидный номер месяца — 13.

CREATE TABLE dates(
    time TIME);

INSERT INTO dates VALUES
    ('1:1'),
    ('24:1');

ERROR: ConversionException: Conversion Error: time field value out of range:
"24:1", expected format is ([YYYY-MM-DD ]HH:MM:SS[.MS])

Данные не могут быть введены, так как задано невалидное значение часа — 24.

CREATE TABLE dates(
    timestamp TIMESTAMP);

INSERT INTO dates VALUES
    ('2025-01-01 1');

ERROR: ConversionException: Conversion Error: invalid timestamp field format:
"2025-01-01 1", expected format is (YYYY-MM-DD HH:MM:SS[.US][±HH:MM| ZONE])

Данные не могут быть введены, так как задано невалидное значение времени — 1.

CREATE TABLE dates(
    timestamptz TIMESTAMPTZ);

INSERT INTO dates VALUES
    ('2025-01-01 0:0:0 Europe/Moscow'),
    ('2025-01-01 0:0:0 Asia/Srednekolymsk'),
    ('2025-01-01 0:0:0 MSK');

ERROR: NotImplementedException: Not implemented Error: Unknown TimeZone 'MSK'

Данные не могут быть введены, так как задано невалидное значение часового пояса MSK. Значения Europe/Moscow и Asia/Srednekolymsk при этом являются валидными, так как входят в список идентификаторов часовых поясов tz_database.