> ## 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.

# Extensão vsql_uuid para MySQL

> A extensão vsql_uuid adiciona ao MySQL um tipo de coluna uuid nativo de 16 bytes e gera UUIDs das versões 1, 3, 4, 5, 6 e 7 em SQL.

O MySQL armazena um UUID como texto ou como um `BINARY(16)` que você converte à
mão. O `vsql_uuid` adiciona um tipo de coluna `uuid` real que guarda 16 bytes,
é exibido na forma familiar de 36 caracteres e é ordenado pela sua própria
regra de comparação. Ele também gera as versões 1, 3, 4, 5, 6 e 7, enquanto o
`UUID()` do próprio MySQL produz somente a versão 1.

| | |
| - | - |
| **Mantenedor** | VillageSQL |
| **Código-fonte e documentação completa** | [villagesql/vsql-uuid](https://github.com/villagesql/vsql-uuid) |
| **Licença** | GPL-2.0 |

## Instalar

O `vsql_uuid.veb` já está no diretório `lib/veb/` do servidor se você instalou
o VillageSQL com o script de instalação, a imagem Docker ou um tarball de
release. Instale-o no servidor com uma única instrução:

```sql theme={null}
INSTALL EXTENSION vsql_uuid;
```

Confirme que ele está lá:

```sql theme={null}
SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_uuid';
```

```
+----------------+
| EXTENSION_NAME |
+----------------+
| vsql_uuid      |
+----------------+
```

Para compilá-lo você mesmo, siga as instruções de compilação no
[repositório](https://github.com/villagesql/vsql-uuid).

## O que ela adiciona

### O tipo uuid

Declare a coluna como `uuid`. Ela ocupa 16 bytes e funciona como chave primária.

```sql theme={null}
CREATE TABLE orders (
    id     uuid PRIMARY KEY,
    placed DATETIME,
    total  DECIMAL(8,2)
);
```

### Funções

| Função | Retorna | O que faz |
| - | - | - |
| `UUID_V1()` | `uuid` | Baseado em tempo, usando o endereço MAC do host |
| `UUID_V1MC()` | `uuid` | Baseado em tempo, usando um endereço multicast aleatório em vez do MAC |
| `UUID_V3(namespace, name)` | `uuid` | Baseado em nome, MD5 |
| `UUID_V4()` | `uuid` | Aleatório |
| `UUID_V5(namespace, name)` | `uuid` | Baseado em nome, SHA-1 |
| `UUID_V6()` | `uuid` | Ordenado por tempo, monotônico dentro de uma conexão |
| `UUID_V7()` | `uuid` | Ordenado por tempo em um timestamp Unix em milissegundos |
| `UUID_NIL()`, `UUID_MAX()` | `uuid` | Os valores todo zero e todo um |
| `UUID_NS_DNS()`, `UUID_NS_URL()`, `UUID_NS_OID()`, `UUID_NS_X500()` | texto | As constantes de namespace da RFC 9562, para `UUID_V3` e `UUID_V5` |
| `UUID_IS_VALID(s)` | int | 1 quando uma string seria aceita por uma coluna `uuid`, 0 quando não seria |
| `UUID_VERSION(u)` | int | O nibble de versão |
| `UUID_TIMESTAMP(u)` | texto | O tempo embutido como `'YYYY-MM-DD HH:MM:SS'` em UTC, NULL para versões que não carregam tempo |
| `UUID_EPOCH(u)` | int | O mesmo tempo em segundos Unix |
| `UUID_COMPARE(a, b)` | int | -1, 0 ou 1 |

## Exemplo

Use um identificador versão 7 como chave primária, de modo que as linhas
gravadas depois sejam ordenadas após as linhas gravadas antes, e depois leia a
versão de volta:

```sql theme={null}
INSERT INTO orders VALUES (UUID_V7(), NOW(), 42.50);
DO SLEEP(0.01);
INSERT INTO orders VALUES (UUID_V7(), NOW(), 19.99);

SELECT UUID_VERSION(id) AS version, total FROM orders ORDER BY id;
```

```
+---------+-------+
| version | total |
+---------+-------+
|       7 | 42.50 |
|       7 | 19.99 |
+---------+-------+
```

Derive um identificador estável a partir de um nome:

```sql theme={null}
SELECT UUID_V5(UUID_NS_DNS(), 'villagesql.com') AS dns_uuid;
```

```
+--------------------------------------+
| dns_uuid                             |
+--------------------------------------+
| fc51a94b-5261-5a4c-a5ec-48199b58d67b |
+--------------------------------------+
```

> [!NOTE]
>
> A ordenação acima vale somente entre milissegundos. A versão 7 coloca um
> timestamp em milissegundos na frente e preenche o resto aleatoriamente, sem
> contador, então dois valores gerados no mesmo milissegundo são ordenados em
> ordem aleatória um em relação ao outro. É por isso que o exemplo insere as
> duas linhas em instruções separadas. Use `UUID_V6()` quando você precisa de
> uma ordenação mais fina que essa.

> [!NOTE]
>
> Uma coluna `uuid` aceita um literal de string, mas não uma expressão de
> string. Assim,
> `INSERT INTO orders VALUES ('550e8400-e29b-41d4-a716-446655440000', ...)`
> funciona, enquanto `INSERT INTO orders VALUES (UUID(), ...)` falha com
> `ERROR 3219 (HY000): Incorrect uuid value: cannot implicitly cast string
>     expression. Use explicit conversion for column 'id' at row 1`. Em vez disso,
> gere o valor com uma das funções acima.

## Veja também

* [UUIDs no MySQL](https://villagesql.com/docs/en/guides/uuids.md) — para que serve cada versão e qual escolher
* [Estratégias de chave primária](https://villagesql.com/docs/en/guides/primary-key-strategies.md) — onde uma chave UUID ajuda e onde ela custa
* [Instalar extensões](https://villagesql.com/docs/pt-BR/extensions/install.md) — como o `INSTALL EXTENSION` funciona e onde o servidor procura um bundle
* [Extensões disponíveis](https://villagesql.com/docs/pt-BR/extensions/catalog) — o catálogo completo
* [villagesql/vsql-uuid](https://github.com/villagesql/vsql-uuid) — código-fonte, instruções de compilação e as limitações conhecidas


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