Função MySQL DATE_ADD()

Resumo : neste tutorial, você aprenderá como usar DATE_ADD()a função MySQL para adicionar um valor de tempo a um valor DATEou DATETIME.

Introdução à função MySQL DATE_ADD

A DATE_ADDfunção adiciona um intervalo a um valor DATEou DATETIME.

O seguinte ilustra a sintaxe da DATE_ADDfunção:

DATE_ADD(start_date, INTERVAL expr unit);Linguagem de código:  SQL (linguagem de consulta estruturada)  ( sql )

A DATE_ADDfunção leva dois argumentos:

• start_dateé um ponto de partida DATEou DATETIMEvalor.
• INTERVAL expr unité um valor de intervalo a ser adicionado ao valor da data inicial.

A DATE_ADD()função pode retornar um DATETIMEvalor ou uma string, dependendo dos argumentos:

• DATETIMEse o primeiro argumento for um DATETIMEvalor ou se o valor do intervalo tiver um elemento de tempo como hora, minuto, segundo, etc.
• String de outra forma.

Exemplos de funções MySQL DATE_ADD

Vamos dar uma olhada em alguns exemplos para entender como DATE_ADD()funciona a função.

A instrução a seguir usa a DATE_ADD()função para adicionar um segundo a 1999-12-31 23:59:59:

SELECT 
    DATE_ADD('1999-12-31 23:59:59',
        INTERVAL 1 SECOND) result;Linguagem de código:  SQL (linguagem de consulta estruturada)  ( sql )

Saída:

+---------------------+
| result              |
+---------------------+
| 2000-01-01 00:00:00 |
+---------------------+
1 row in set (0.00 sec)Linguagem de código:  JavaScript  ( javascript )

O exemplo a seguir usa a DATE_ADD()função para adicionar um dia a 1999-12-31 00:00:01:

SELECT 
    DATE_ADD('1999-12-31 00:00:01',
        INTERVAL 1 DAY) result;    Linguagem de código:  SQL (linguagem de consulta estruturada)  ( sql )

Saída:

+---------------------+
| result              |
+---------------------+
| 2000-01-01 00:00:01 |
+---------------------+
1 row in set (0.00 sec)Linguagem de código:  JavaScript  ( javascript )

O exemplo a seguir usa a DATE_ADD()função para adicionar 1 minuto e 1 segundo a 1999-12-31 23:59:59:

SELECT 
    DATE_ADD('1999-12-31 23:59:59',
        INTERVAL '1:1' MINUTE_SECOND) result;Linguagem de código:  SQL (linguagem de consulta estruturada)  ( sql )

Saída:

+---------------------+
| result              |
+---------------------+
| 2000-01-01 00:01:00 |
+---------------------+
1 row in set (0.00 sec)Linguagem de código:  JavaScript  ( javascript )

O exemplo a seguir adiciona -1 dia e 5 horas a 2000-01-01 00:00:00.

SELECT DATE_ADD('2000-01-01 00:00:00',
     INTERVAL '-1 5' DAY_HOUR) result;Linguagem de código:  SQL (linguagem de consulta estruturada)  ( sql )

Saída:

+---------------------+
| result              |
+---------------------+
| 1999-12-30 19:00:00 |
+---------------------+
1 row in set (0.00 sec)Linguagem de código:  JavaScript  ( javascript )

O exemplo a seguir adiciona 1 segundo e 999999 microssegundos a 1999-12-31 23:59:59.000002:

SELECT 
    DATE_ADD('1999-12-31 23:59:59.000002',
        INTERVAL '1.999999' SECOND_MICROSECOND) result;
Linguagem de código:  SQL (linguagem de consulta estruturada)  ( sql )

Saída:

+----------------------------+
| result                     |
+----------------------------+
| 2000-01-01 00:00:01.000001 |
+----------------------------+
1 row in set (0.00 sec)Linguagem de código:  JavaScript  ( javascript )

Notas de uso da função MySQL DATE_ADD

Tratamento de intervalo

No intervalo:

INTERVAL expr unitLinguagem de código:  SQL (linguagem de consulta estruturada)  ( sql )

O expré tratado como uma string, portanto, você deve ter cuidado ao usar um valor que não seja de string para o expr.

Por exemplo, com um intervalo de HOUR_MINUTE, 5/2é avaliado como 2.5000(não 2.5) e é tratado como 2 horas e 5.000 minutos, como na seguinte instrução:

SELECT 
    DATE_ADD('2000-01-01',
        INTERVAL 5 / 2 HOUR_MINUTE) result;Linguagem de código:  SQL (linguagem de consulta estruturada)  ( sql )

Saída:

+---------------------+
| result              |
+---------------------+
| 2000-01-04 13:20:00 |
+---------------------+
1 row in set (0.00 sec)Linguagem de código:  JavaScript  ( javascript )

Para garantir a interpretação correta de um valor de intervalo sem string, você deve usar a CASTfunção da seguinte maneira:

SELECT 
    DATE_ADD('2000-01-01',
        INTERVAL CAST(6/4 AS DECIMAL(3,1)) HOUR_MINUTE) result;Linguagem de código:  SQL (linguagem de consulta estruturada)  ( sql )

Saída:

+---------------------+
| result              |
+---------------------+
| 2000-01-01 01:05:00 |
+---------------------+
1 row in set (0.00 sec)
Linguagem de código:  JavaScript  ( javascript )

Conversão automática de DATETIME

Se você adicionar um valor de tempo a um valor de data, o resultado será um DATETIMEvalor conforme mostrado no exemplo a seguir:

SELECT 
    DATE_ADD('2000-01-01', INTERVAL 12 HOUR) result;Linguagem de código:  SQL (linguagem de consulta estruturada)  ( sql )

Saída:

+---------------------+
| result              |
+---------------------+
| 2000-01-01 12:00:00 |
+---------------------+
1 row in set (0.00 sec)Linguagem de código:  JavaScript  ( javascript )

Data de início inválida

A DATE_ADDfunção retorna NULLse você usar uma data inválida para o primeiro argumento, por exemplo:

 SELECT DATE_ADD('2000-02-30', 
            INTERVAL 1 DAY) result;Linguagem de código:  SQL (linguagem de consulta estruturada)  ( sql )

Saída:

+--------+
| result |
+--------+
| NULL   |
+--------+
1 row in set, 1 warning (0.00 sec)Linguagem de código:  JavaScript  ( javascript )

Se você quiser ver o aviso em detalhes, use a SHOW WARNINGSinstrução:

SHOW WARNINGS;Linguagem de código:  SQL (linguagem de consulta estruturada)  ( sql )

Saída:

+---------+------+----------------------------------------+
| Level   | Code | Message                                |
+---------+------+----------------------------------------+
| Warning | 1292 | Incorrect datetime value: '2000-02-30' |
+---------+------+----------------------------------------+
1 row in set (0.00 sec)Linguagem de código:  JavaScript  ( javascript )

Dia, mês ou ano ajustado

Se você adicionar um intervalo de MONTH, YEAR, ou YEAR_MONTHa uma data que resulte em uma data que tenha um dia maior que o dia máximo do novo mês, o dia será ajustado para o dia máximo do novo mês.

Considere o seguinte exemplo:

SELECT 
    DATE_ADD('2010-01-30', 
              INTERVAL 1 MONTH) result;Linguagem de código:  SQL (linguagem de consulta estruturada)  ( sql )

Saída:

+------------+
| result     |
+------------+
| 2010-02-28 |
+------------+
1 row in set (0.00 sec)Linguagem de código:  JavaScript  ( javascript )

Neste exemplo, adicionamos 1 mês ao January 30th 2010que resulta em February 28th 2010. O dia foi ajustado para o dia máximo em February 2010.

No ano em que fevereiro tiver 29 dias, a data também será ajustada para o dia 29 conforme abaixo:

SELECT 
    DATE_ADD('2012-01-30', 
            INTERVAL 1 MONTH) result;Linguagem de código:  SQL (linguagem de consulta estruturada)  ( sql )

Saída:

+------------+
| result     |
+------------+
| 2012-02-29 |
+------------+
1 row in set (0.00 sec)Linguagem de código:  JavaScript  ( javascript )

Resumo

• Use a função MySQL DATE_ADDpara adicionar um intervalo a um valor DATEou DATETIME.