Como ADD_MONTHS() funciona no MariaDB

No MariaDB, ADD_MONTHS() é uma função de data e hora integrada que adiciona um determinado número de meses a uma data e retorna o resultado.

A data pode ser um valor de data, data e hora ou carimbo de data/hora.

Essa função foi introduzida no MariaDB 10.6.1 para aprimorar a compatibilidade do Oracle. Existem pelo menos 6 outras maneiras de adicionar meses a uma data no MariaDB.

Sintaxe

A sintaxe fica assim:

ADD_MONTHS(date, months)

Onde date é a data e months é o número de meses para adicionar a ele.

Exemplo

Aqui está um exemplo:

SELECT ADD_MONTHS('2020-01-01', 3);

Resultado:

+-----------------------------+
| ADD_MONTHS('2020-01-01', 3) |
+-----------------------------+
| 2020-04-01                  |
+-----------------------------+

Subtrair Meses

Para subtrair meses de uma data, use um valor negativo para o segundo argumento.

Exemplo:

SELECT ADD_MONTHS('2020-01-01', -3);

Resultado:

+------------------------------+
| ADD_MONTHS('2020-01-01', -3) |
+------------------------------+
| 2019-10-01                   |
+------------------------------+

Contexto Numérico

A data pode ser fornecida em formato numérico, se necessário:

SELECT ADD_MONTHS(20200101, 3);

Resultado:

+-------------------------+
| ADD_MONTHS(20200101, 3) |
+-------------------------+
| 2020-04-01              |
+-------------------------+

Datas inválidas

Se a data for inválida, ADD_MONTHS() retorna null com um aviso:

SELECT ADD_MONTHS('2020-01-51', 3);

Resultado:

+-----------------------------+
| ADD_MONTHS('2020-01-51', 3) |
+-----------------------------+
| NULL                        |
+-----------------------------+
1 row in set, 1 warning (0.003 sec)

Vamos verificar o aviso:

SHOW WARNINGS;

Resultado:

+---------+------+----------------------------------------+
| Level   | Code | Message                                |
+---------+------+----------------------------------------+
| Warning | 1292 | Incorrect datetime value: '2020-01-51' |
+---------+------+----------------------------------------+

Argumentos nulos

ADD_MONTHS() retorna null se algum argumento for null :

SELECT ADD_MONTHS('2020-01-01', null);

Resultado:

+--------------------------------+
| ADD_MONTHS('2020-01-01', null) |
+--------------------------------+
| NULL                           |
+--------------------------------+

Número inválido de argumentos

Passar um número inválido de argumentos resulta em um erro:

SELECT ADD_MONTHS(3);

Resultado:

ERROR 1064 (42000): You have an error in your SQL syntax; check the manual that corresponds to your MariaDB server version for the right syntax to use near ')' at line 1