How ADD_MONTHS() Works in MariaDB

In MariaDB, ADD_MONTHS() is a built-in date and time function that adds a given number of months to a date, and returns the result.

The date can be a date, datetime, or timestamp value.

This function was introduced in MariaDB 10.6.1 to enhance Oracle compatibility. There are at least 6 other ways to add months to a date in MariaDB.

Syntax

The syntax goes like this:

ADD_MONTHS(date, months)

Where date is the date, and months is the number of months to add to it.

Example

Here’s an example:

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

Result:

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

Subtract Months

To subtract months from a date, use a negative value for the second argument.

Example:

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

Result:

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

Numeric Context

The date can be provided in numeric form if required:

SELECT ADD_MONTHS(20200101, 3);

Result:

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

Invalid Dates

If the date is invalid, ADD_MONTHS() returns null with a warning:

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

Result:

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

Let’s check the warning:

SHOW WARNINGS;

Result:

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

Null Arguments

ADD_MONTHS() returns null if any argument is null:

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

Result:

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

Invalid Number of Arguments

Passing an invalid number of arguments results in an error:

SELECT ADD_MONTHS(3);

Result:

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