> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Funções de Data e Hora do MySQL

> Guia de referência das funções de data e hora do MySQL: NOW, CURDATE, DATE_FORMAT, DATEDIFF, DATE_ADD, EXTRACT, STR_TO_DATE, UNIX_TIMESTAMP e padrões comuns de manipulação de datas.

> [card] [VillageSQL is a drop-in replacement for MySQL with extensions.](https://villagesql.com/docs/en/8.4/stable/install-server.md)
>
> All examples on this page work on VillageSQL. Install Now →

O MySQL oferece um conjunto completo de funções de data e hora. Os principais tipos com que você vai trabalhar são `DATE` (apenas data), `TIME` (apenas hora), `DATETIME` (data + hora, sem fuso horário) e `TIMESTAMP` (data + hora, armazenado em UTC, exibido no fuso horário da sessão). Consulte [Timestamps e Fusos Horários no MySQL](https://villagesql.com/docs/pt-BR/guides/timestamps-timezones.md) para detalhes sobre o tratamento de fusos horários.

## Obtendo a Data e a Hora Atuais

```sql theme={null}
SELECT NOW();            -- '2024-06-15 14:30:00'  (DATETIME, session timezone)
SELECT SYSDATE();        -- same, but evaluated at call time, not statement start
SELECT CURRENT_TIMESTAMP; -- synonym for NOW()

SELECT CURDATE();        -- '2024-06-15'  (DATE only)
SELECT CURTIME();        -- '14:30:00'    (TIME only)
SELECT UTC_TIMESTAMP();  -- '2024-06-15 21:30:00'  (UTC)
```

`NOW()` é avaliado uma vez no início de uma instrução — todas as linhas do mesmo INSERT recebem o mesmo timestamp. `SYSDATE()` é avaliado a cada vez que é chamado.

## Formatando Datas

`DATE_FORMAT` converte uma data ou datetime em uma string usando uma string de formato:

```sql theme={null}
SELECT DATE_FORMAT(NOW(), '%Y-%m-%d');          -- '2024-06-15'
SELECT DATE_FORMAT(NOW(), '%d/%m/%Y');          -- '15/06/2024'
SELECT DATE_FORMAT(NOW(), '%M %d, %Y');         -- 'June 15, 2024'
SELECT DATE_FORMAT(NOW(), '%Y-%m-%d %H:%i:%s'); -- '2024-06-15 14:30:00'
```

Especificadores de formato comuns:

| Especificador | Significado | Exemplo |
| :- | :- | :- |
| `%Y` | Ano com 4 dígitos | `2024` |
| `%y` | Ano com 2 dígitos | `24` |
| `%m` | Mês (01–12) | `06` |
| `%M` | Nome do mês | `June` |
| `%d` | Dia (01–31) | `15` |
| `%H` | Hora (00–23) | `14` |
| `%i` | Minuto (00–59) | `30` |
| `%s` | Segundo (00–59) | `00` |
| `%W` | Nome do dia da semana | `Saturday` |
| `%w` | Dia da semana (0=domingo) | `6` |
| `%j` | Dia do ano (001–366) | `167` |
| `%U` | Número da semana (0–53, semana começa no domingo) | `24` |

## Convertendo Strings em Datas

`STR_TO_DATE` converte uma string em uma data usando os mesmos especificadores de formato:

```sql theme={null}
SELECT STR_TO_DATE('15/06/2024', '%d/%m/%Y');         -- '2024-06-15'
SELECT STR_TO_DATE('June 15, 2024', '%M %d, %Y');     -- '2024-06-15'
SELECT STR_TO_DATE('2024-06-15 14:30:00', '%Y-%m-%d %H:%i:%s');  -- DATETIME
```

Retorna NULL se a string não corresponder ao formato.

## Aritmética de Datas

**DATE\_ADD / DATE\_SUB** — somam ou subtraem um intervalo:

```sql theme={null}
SELECT DATE_ADD(NOW(), INTERVAL 7 DAY);        -- 7 days from now
SELECT DATE_ADD(NOW(), INTERVAL 3 MONTH);      -- 3 months from now
SELECT DATE_SUB(NOW(), INTERVAL 1 YEAR);       -- 1 year ago
SELECT DATE_ADD('2024-01-31', INTERVAL 1 MONTH); -- '2024-02-29' (end of Feb)
```

Unidades de intervalo: `SECOND`, `MINUTE`, `HOUR`, `DAY`, `WEEK`, `MONTH`, `QUARTER`, `YEAR`.

Forma abreviada com os operadores `+` e `-`:

```sql theme={null}
SELECT NOW() + INTERVAL 1 DAY;
SELECT '2024-06-15' - INTERVAL 1 MONTH;
```

**DATEDIFF** — dias entre duas datas:

```sql theme={null}
SELECT DATEDIFF('2024-12-31', '2024-06-15');  -- 199
SELECT DATEDIFF(NOW(), created_at) AS days_old FROM orders;
```

`DATEDIFF` conta apenas dias, não a hora. Para diferenças que consideram a hora, use `TIMESTAMPDIFF`:

```sql theme={null}
SELECT TIMESTAMPDIFF(HOUR, '2024-06-15 08:00', '2024-06-15 14:30');  -- 6
SELECT TIMESTAMPDIFF(MINUTE, created_at, NOW()) AS minutes_ago FROM events;
```

`TIMESTAMPDIFF(unit, from, to)` — observe que `from` vem antes de `to`.

## Extraindo Partes da Data

**EXTRACT / YEAR / MONTH / DAY**:

```sql theme={null}
SELECT YEAR(NOW());     -- 2024
SELECT MONTH(NOW());    -- 6
SELECT DAY(NOW());      -- 15 (same as DAYOFMONTH)
SELECT HOUR(NOW());     -- 14
SELECT MINUTE(NOW());   -- 30

-- EXTRACT uses interval unit names
SELECT EXTRACT(YEAR FROM NOW());        -- 2024
SELECT EXTRACT(HOUR FROM NOW());        -- 14
SELECT EXTRACT(YEAR_MONTH FROM NOW());  -- 202406
```

**DAYOFWEEK / DAYOFYEAR / WEEK**:

```sql theme={null}
SELECT DAYOFWEEK(NOW());   -- 7  (1=Sunday, 7=Saturday)
SELECT WEEKDAY(NOW());     -- 5  (0=Monday, 6=Sunday)
SELECT DAYOFYEAR(NOW());   -- 167
SELECT WEEK(NOW());        -- 23  (default mode 0: week 0–53, Sunday-based; mode 1 gives 24)
SELECT YEARWEEK(NOW());    -- 202423  (default mode)
```

## Truncando para um Período

Para agrupar dados por mês, semana ou dia, trunque o datetime para o limite do período:

```sql theme={null}
-- Group orders by month
SELECT DATE_FORMAT(created_at, '%Y-%m') AS month, COUNT(*) AS orders
FROM orders
GROUP BY month
ORDER BY month;

-- Group by week
SELECT YEARWEEK(created_at) AS week, COUNT(*) AS orders
FROM orders
GROUP BY week;

-- Truncate to start of month
SELECT DATE_FORMAT(NOW(), '%Y-%m-01');  -- '2024-06-01'
```

## Timestamps Unix

```sql theme={null}
SELECT UNIX_TIMESTAMP();                          -- seconds since epoch (session timezone)
SELECT UNIX_TIMESTAMP('2024-06-15 14:30:00');     -- datetime to epoch (session timezone)
SELECT FROM_UNIXTIME(1718451000);                 -- epoch to DATETIME
SELECT FROM_UNIXTIME(1718451000, '%Y-%m-%d');     -- epoch to formatted string
```

## Padrões Comuns

Registros dos últimos 30 dias:

```sql theme={null}
SELECT * FROM orders WHERE created_at >= NOW() - INTERVAL 30 DAY;
```

Registros do mês atual:

```sql theme={null}
SELECT * FROM orders
WHERE created_at >= DATE_FORMAT(NOW(), '%Y-%m-01')
  AND created_at <  DATE_FORMAT(NOW() + INTERVAL 1 MONTH, '%Y-%m-01');
```

Idade a partir de uma data de nascimento:

```sql theme={null}
SELECT TIMESTAMPDIFF(YEAR, birthdate, CURDATE()) AS age FROM users;
```

## Perguntas Frequentes

#### Qual é a diferença entre NOW() e SYSDATE()?

`NOW()` retorna o timestamp de quando a instrução começou a executar — todas as linhas de um único INSERT ou UPDATE recebem o mesmo valor. `SYSDATE()` retorna a hora real do relógio no momento em que é chamado, então linhas inseridas em um loop recebem valores diferentes. Para timestamps de auditoria em que a consistência dentro de uma transação importa, `NOW()` é quase sempre a escolha certa.

#### Por que DATE\_ADD com INTERVAL 1 MONTH se comporta de forma estranha no fim do mês?

O MySQL ajusta para o último dia válido. `DATE_ADD('2024-01-31', INTERVAL 1 MONTH)` retorna `2024-02-29` (ano bissexto) ou `2024-02-28`. Esse é o comportamento esperado — não existe "31 de fevereiro". Se você precisa de aritmética de meses previsível, trunque primeiro para o início do mês.

## Solução de Problemas

| Problema | Solução |
| :- | :- |
| `STR_TO_DATE` retorna NULL | A string de formato não corresponde à entrada — verifique se cada especificador de formato corresponde ao caractere de entrada correspondente |
| `DATEDIFF` retorna 0 para timestamps na mesma data | `DATEDIFF` ignora o componente de hora — duas linhas na mesma data do calendário retornam 0 |
| A comparação de datas deixa de fora linhas do fim do dia | `WHERE created_at <= '2024-06-15'` para à meia-noite — use `< '2024-06-16'` para incluir o dia inteiro |
| `TIMESTAMPDIFF` retorna um valor negativo inesperado | Os argumentos estão na ordem errada — `TIMESTAMPDIFF(unit, from, to)`, não `(unit, to, from)` |
| `WEEK()` retorna números diferentes do esperado | O modo de numeração de semanas importa (início no domingo ou na segunda) — use `YEARWEEK(date, 3)` para números de semana ISO 8601 |

## Veja também

* [Timestamps e Fusos Horários no MySQL](https://villagesql.com/docs/pt-BR/guides/timestamps-timezones.md) — os tipos de armazenamento sobre os quais as funções de data operam
* [MySQL BETWEEN](https://villagesql.com/docs/pt-BR/tutorial/between.md) — por que um intervalo de datas é mais seguro escrito com `>=` e `<`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.