document new uuid functions (#647)

Author: ephys

docs/_fragments/_js-default-caution.mdx

@@ -1,7 +1,7 @@
 :::caution
 
-The generation of values for `DataTypes.UUIDV1` and `DataTypes.UUIDV4`, `DataTypes.NOW` and other JavaScript functions are not handled by the Database,
-but by Sequelize itself. This means that they will only be used when using Model methods. They will not be used in [raw queries](../querying/raw-queries.md), 
+The generation of values for `DataTypes.NOW` and other JavaScript functions are not handled by the Database,
+but by Sequelize itself. This means that they will only be used when using Model methods. They will not be used in [raw queries](../querying/raw-queries.mdx),
 in [migrations](../models/migrations.md), and all other places where Sequelize does not have access to the Model.
 
 Read about SQL based alternatives in [Dynamic SQL default values](../models/defining-models.mdx#dynamic-sql-default-values).

docs/_fragments/_uuid-support-table.mdx

@@ -0,0 +1,10 @@
+import { DialectTableFilter } from '@site/src/components/dialect-table-filter.tsx';
+
+<DialectTableFilter>
+
+|          | PostgreSQL                                                                                                                                                                                                                | MariaDB                                   | MySQL                                                                                        | MSSQL                                                                                                     | SQLite | Snowflake | db2 | ibmi |
+|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|--------|-----------|-----|------|
+| `uuidV1` | [`uuid_generate_v1`](https://www.postgresql.org/docs/current/uuid-ossp.html) (requires `uuid-ossp`)                                                                                                                       | [`UUID`](https://mariadb.com/kb/en/uuid/) | [`UUID`](https://dev.mysql.com/doc/refman/8.0/en/miscellaneous-functions.html#function_uuid) | N/A                                                                                                       | N/A    | N/A       | N/A | N/A  |
+| `uuidV4` | __pg >= v13__: [`gen_random_uuid`](https://www.postgresql.org/docs/current/functions-uuid.html) <br/>__pg &lt; v13__: [`uuid_generate_v4`](https://www.postgresql.org/docs/current/uuid-ossp.html) (requires `uuid-ossp`) | N/A                                       | N/A                                                                                          | [`NEWID`](https://learn.microsoft.com/en-us/sql/t-sql/functions/newid-transact-sql?view=sql-server-ver16) | N/A    | N/A       | N/A | N/A  |
+
+</DialectTableFilter>

docs/models/data-types.mdx

@@ -6,6 +6,7 @@ title: Data Types
 import { DialectTableFilter } from '@site/src/components/dialect-table-filter.tsx';
 import { Deprecated } from '@site/src/components/deprecated.tsx';
 import JsDefaultCaution from '../_fragments/_js-default-caution.mdx';
+import UuidSupportTable from '../_fragments/_uuid-support-table.mdx';
 
 Sequelize provides [a lot of built-in data types](pathname:///api/v7/modules/_sequelize_core.index.DataTypes.html). To access a built-in data type, you must import `DataTypes`:
 
@@ -212,6 +213,9 @@ MyModel.init({
 
 For UUIDs, use `DataTypes.UUID`. It becomes the `UUID` data type for PostgreSQL and SQLite, and `CHAR(36)` for MySQL.
 
+You can also use `DataTypes.UUID.V4` and `DataTypes.UUID.V1`
+to limit which version of UUID is accepted by the attribute to v4 or v1 respectively.
+
 <DialectTableFilter>
 
 | Sequelize DataType | PostgreSQL                                                           | MariaDB           | MySQL             | MSSQL                                                                                                                            | SQLite | Snowflake     | db2                     | ibmi                    |
@@ -222,18 +226,36 @@ For UUIDs, use `DataTypes.UUID`. It becomes the `UUID` data type for PostgreSQL
 
 ### Built-in Default Values for UUID
 
-Sequelize can generate UUIDs automatically for these attributes, simply use `DataTypes.UUIDV1` or `DataTypes.UUIDV4` as the default value:
+Sequelize can generate UUIDs automatically for these attributes, simply use [`sql.uuidV1` or `sql.uuidV4`](../querying/raw-queries.mdx#sqluuidv4--sqluuidv1) as the default value:
 
 ```javascript
 MyModel.init({
   myUuid: {
-    type: DataTypes.UUID,
-    defaultValue: DataTypes.UUIDV4, // Or DataTypes.UUIDV1
+    type: DataTypes.UUID.V4,
+    defaultValue: sql.uuidV4, // Or sql.uuidV1
   },
 });
 ```
 
-<JsDefaultCaution />
+In supported dialects, Sequelize will set the default value to the appropriate function, as shown in the table below.
+These dialects can also use these two functions in migrations.
+
+In all other dialects, Sequelize will generate the UUID value itself, in JavaScript.
+This means that they cannot use these two functions in migrations.
+
+<UuidSupportTable />
+
+The postgres dialect requires the `uuid-ossp` extension to be enabled to be able to generate v1 UUIDs.
+If this extension is not available, you can force Sequelize to generate the UUIDs itself by using `sql.uuidV1.asJavaScript` instead.
+
+```javascript
+MyModel.init({
+  myUuid: {
+    type: DataTypes.UUID.V1,
+    defaultValue: sql.uuidV1.asJavaScript,
+  },
+});
+```
 
 ## BLOBs
 

docs/models/defining-models.mdx

@@ -235,13 +235,9 @@ class User extends Model {
 
 ### Dynamic JS default values
 
-Instead of a static value, you can also use a JavaScript function that sequelize will call every time a new instance is created. Sequelize provides 3 built-in functions that you can use, but a custom function can be used as well:
-
-- [`DataTypes.NOW`](./data-types.mdx#built-in-default-values-for-dates) for the current timestamp
-- [`DataTypes.UUIDV4`](./data-types.mdx#built-in-default-values-for-uuid) for a UUIDv4
-- [`DataTypes.UUIDV1`](./data-types.mdx#built-in-default-values-for-uuid) for a UUIDv1
-
-<JsDefaultCaution />
+Instead of a static value, you can also use a JavaScript function that sequelize will call every time a new instance is created.
+Sequelize provides the built-in [`DataTypes.NOW`](./data-types.mdx#built-in-default-values-for-dates) for the current timestamp,
+but a custom function can be used as well:
 
 <Tabs groupId="ts-js">
 <TabItem value="ts" label="TypeScript">
@@ -296,28 +292,27 @@ class User extends Model {
 </TabItem>
 </Tabs>
 
+<JsDefaultCaution />
+
 ### Dynamic SQL default values
 
-You can also use a SQL function as a default value using either [`fn`] or [`literal`].
-This has the advantage over [dynamic JS default values](#dynamic-js-default-values) that the function will always be called, since it is handled by the database, not by Sequelize.
+You can also use a SQL function as a default value using [raw SQL](../querying/raw-queries.mdx).
+This has the advantage over [dynamic JS default values](#dynamic-js-default-values) that the function will always be called,
+since it is handled by the database, not by Sequelize.
 
-For instance, if your dialect provides a built-in SQL function to generate UUIDs, you can use [`fn`] to set a default value on the SQL layer:
+For instance, you could use the [`sql.fn`](../querying/raw-queries.mdx#sqlfn) function to make the database generate a random number for you:
 
 <Tabs groupId="ts-js">
 <TabItem value="ts" label="TypeScript">
 
 ```ts
 import { DataTypes, Model, sql, InferAttributes, InferCreationAttributes, CreationOptional } from '@sequelize/core';
-import { Attribute, Default, PrimaryKey } from '@sequelize/core/decorators-legacy';
+import { Attribute, Default } from '@sequelize/core/decorators-legacy';
 
 class User extends Model<InferAttributes<User>, InferCreationAttributes<User>> {
-  @PrimaryKey
-  @Attribute(DataTypes.UUID)
-  // 'uuid_generate_v4' is only available in postgres + uuid-ossp
-  // other dialects may support this function under different names.
-  // highlight-next-line
-  @Default(sql.fn('uuid_generate_v4'))
-  declare id: CreationOptional<string>;
+  @Attribute(DataTypes.FLOAT)
+  @Default(sql.fn('random'))
+  declare randomNumber: CreationOptional<number>;
 }
 ```
 
@@ -326,22 +321,27 @@ class User extends Model<InferAttributes<User>, InferCreationAttributes<User>> {
 
 ```js
 import { DataTypes, Model, sql } from '@sequelize/core';
-import { Attribute, Default, PrimaryKey } from '@sequelize/core/decorators-legacy';
+import { Attribute, Default } from '@sequelize/core/decorators-legacy';
 
 class User extends Model {
-  @PrimaryKey
-  @Attribute(DataTypes.UUID)
-  // 'uuid_generate_v4' is only available in postgres + uuid-ossp
-  // other dialects may support this function under different names.
-  // highlight-next-line
-  @Default(sql.fn('uuid_generate_v4'))
-  id;
+  @Attribute(DataTypes.FLOAT)
+  @Default(sql.fn('random'))
+  randomNumber;
 }
 ```
 
 </TabItem>
 </Tabs>
 
+Sequelize also provides 2 built-in functions, [`sql.uuidV1` and `sql.uuidV4`](./data-types.mdx#built-in-default-values-for-uuid), that will
+generate a UUID in SQL if possible, and fallback to a JavaScript implementation otherwise.
+
+:::info
+
+In MySQL, it is only possible to use dynamic SQL default values starting with version [8.0.13](https://dev.mysql.com/doc/relnotes/mysql/8.0/en/news-8-0-13.html).
+
+:::
+
 ## Primary Keys
 
 Sequelize automatically adds an auto-incremented integer attribute called `id` as primary key if none is specified.

docs/other-topics/extending-data-types.md

@@ -102,8 +102,8 @@ export class MyDateType extends DataTypes.ABSTRACT<Date> {
 We also have 4 methods that can be implemented to define how the Data Type serializes & deserializes values when interacting with the database:
 
 - `parseDatabaseValue(value): unknown`: Transforms values retrieved from the database[^caveat-1].
-- `toBindableValue(value): unknown`: Transforms a value into a value accepted by the connector library when using [bind parameters](../querying/raw-queries.md#bind-parameters).
-- `escape(value): string`: Escapes a value for inlining inside of raw SQL, such as when using [replacements](../querying/raw-queries.md#replacements).  
+- `toBindableValue(value): unknown`: Transforms a value into a value accepted by the connector library when using [bind parameters](../querying/raw-queries.mdx#bind-parameters).
+- `escape(value): string`: Escapes a value for inlining inside of raw SQL, such as when using [replacements](../querying/raw-queries.mdx#replacements).  
   By default, if `toBindableValue` returns a string, this method will escape that string as a SQL string.
 
 ```typescript
@@ -171,4 +171,4 @@ When using `DataTypes.ENUM`, Sequelize will automatically create the enum type i
 If you need to create a custom type, you will need to create it manually in the database before you can use it in one of your models.
 
 [^caveat-1]: `parseDatabaseValue` is only called if a Sequelize Data Type is specified in the query. 
-This is the case when using model methods, but not when using [raw queries](../querying/raw-queries.md) or when not specifying the model in [`QueryInterface`](pathname:///api/v7/classes/_sequelize_core.index.AbstractQueryInterface.html) methods
+This is the case when using model methods, but not when using [raw queries](../querying/raw-queries.mdx) or when not specifying the model in [`QueryInterface`](pathname:///api/v7/classes/_sequelize_core.index.AbstractQueryInterface.html) methods

docs/other-topics/hooks.mdx

@@ -64,9 +64,9 @@ Instance Sequelize hooks can be registered in two ways:
 1. Using the `hooks` property of the `Sequelize` instance:
    ```typescript
    import { Sequelize } from '@sequelize/core';
-  
+
    const sequelize = new Sequelize(/* options */);
-  
+
    // highlight-next-line
    sequelize.hooks.addListener('beforeDefine', () => {
      console.log('A new Model is being initialized');
@@ -75,7 +75,7 @@ Instance Sequelize hooks can be registered in two ways:
 2. Through the `Sequelize` options:
    ```typescript
    import { Sequelize } from '@sequelize/core';
-  
+
    const sequelize = new Sequelize({
      // highlight-next-line
      hooks: {
@@ -115,13 +115,13 @@ Instance Sequelize hooks can be registered in three ways:
 1. Using the `hooks` property of the `Sequelize` instance:
    ```typescript
    import { Sequelize, DataTypes } from '@sequelize/core';
-    
+
    const sequelize = new Sequelize(/* options */);
-    
+
    const MyModel = sequelize.define('MyModel', {
      name: DataTypes.STRING,
    });
-   
+
    // highlight-next-line
    MyModel.hooks.addListener('beforeFind', () => {
      console.log('findAll has been called on MyModel');
@@ -150,7 +150,7 @@ Instance Sequelize hooks can be registered in three ways:
    ```typescript
    import { Sequelize, Model, Hook } from '@sequelize/core';
    import { BeforeFind } from '@sequelize/core/decorators-legacy';
-   
+
    export class MyModel extends Model {
      // highlight-next-line
      @BeforeFind
@@ -262,7 +262,7 @@ These include but are not limited to:
 
 - Instances being deleted by the database because of an `ON DELETE CASCADE` constraint, [except if the `hooks` option is true](#hooks-for-cascade-deletes).
 - Instances being updated by the database because of a `SET NULL` or `SET DEFAULT` constraint.
-- [Raw queries](../querying/raw-queries.md).
+- [Raw queries](../querying/raw-queries.mdx).
 - All QueryInterface methods.
 
 If you need to react to these events, consider using your database's native and notification system instead.
@@ -310,7 +310,7 @@ class Post extends Model {
 
 const sequelize = new Sequelize({
   /* options */
-  models: [User, Post], 
+  models: [User, Post],
 });
 
 await sequelize.sync({ force: true });
@@ -351,8 +351,8 @@ await sequelize.transaction(async transaction => {
 });
 ```
 
-If we had not included the transaction option in our call to `User.update` in the preceding code, 
-no change would have occurred, since our newly created user does not exist in the database until the pending transaction 
+If we had not included the transaction option in our call to `User.update` in the preceding code,
+no change would have occurred, since our newly created user does not exist in the database until the pending transaction
 has been committed.
 
 [^find-all]: **findAll**: Note that some methods, such as `Model.findOne`, `Model.findAndCountAll` and association getters will also call `Model.findAll` internally. This will cause the `beforeFind` hook to be called for these methods too.

docs/querying/json.mdx

@@ -27,7 +27,7 @@ import { SupportTable } from '@site/src/components/support-table';
 JSON columns are a great way to opt-in to a document approach to data storage while preserving the advantages of relational databases.
 
 Sequelize has first class support for querying JSON columns, including support for accessing nested properties.
-This is done thanks to the `.` syntax supported by [attributes](./raw-queries.md#sqlattribute):
+This is done thanks to the `.` syntax supported by [attributes](./raw-queries.mdx#sqlattribute):
 
 ```ts
 User.findAll({

docs/querying/operators.mdx

@@ -1187,8 +1187,8 @@ Post.findAll({
 
 ## Custom Operators
 
-Thanks to the [`sql`](./raw-queries.md) tag, it is very easy to create custom operators. We recommend reading
-the chapter on [raw queries](./raw-queries.md) to learn more.
+Thanks to the [`sql`](./raw-queries.mdx) tag, it is very easy to create custom operators. We recommend reading
+the chapter on [raw queries](./raw-queries.mdx) to learn more.
 
 Here is an example of a `LIKE` that supports escaping special LIKE characters:
 

docs/querying/raw-queries.md renamed to docs/querying/raw-queries.mdx

@@ -3,6 +3,8 @@ sidebar_position: 8
 title: Raw SQL (literals)
 ---
 
+import UuidSupportTable from '../_fragments/_uuid-support-table.mdx';
+
 We believe that ORMs are inherently leaky abstractions. They are a compromise between the flexibility of SQL and the convenience of an object-oriented programming language.
 As such, it does not make sense to try to provide a 100% complete abstraction over SQL (which could easily be more difficult to read than the SQL itself).
 
@@ -97,7 +99,7 @@ whereas bind parameters are sent to the database separately from the SQL query t
 
 A query can have both bind parameters and replacements.
 
-Each database uses a different syntax for bind parameters, but Sequelize provides its own unification layer.  
+Each database uses a different syntax for bind parameters, but Sequelize provides its own unification layer.
 
 Inconsequentially to which database you use, in Sequelize bind parameters are written following a postgres-like syntax. You can either:
 
@@ -201,7 +203,7 @@ $$;
 );
 ```
 
-The above query looks like code, has syntax coloring that makes it look like code, but is really a regular dollar-quoted string 
+The above query looks like code, has syntax coloring that makes it look like code, but is really a regular dollar-quoted string
 that will be interpreted as SQL by the `DO` clause (similarly to `eval` in JavaScript).
 
 Dollar-quoted strings end as soon as `$$` is encountered. If the user passes `$$` as the `id` parameter, the query will end early and will
@@ -359,7 +361,7 @@ SELECT * FROM "projects" WHERE '2012-01-01' BETWEEN "createdAt" AND "publishedAt
 
 ### `sql.attribute`
 
-The `sql.attribute` function can be used to reference the name of a Model attribute. It is similar to the [`sql.identifier`](#sqlidentifier) function, 
+The `sql.attribute` function can be used to reference the name of a Model attribute. It is similar to the [`sql.identifier`](#sqlidentifier) function,
 but the name of the attribute will be mapped to the name of the column, whereas `sql.identifier` escapes its value as-is:
 
 ```ts
@@ -483,11 +485,29 @@ Attributes support a shorthand syntax for casting. See [Casting syntax in `sql.a
 
 :::
 
+### `sql.uuidV4` & `sql.uuidV1`
+
+In supported dialects, using `sql.uuidV4` and `sql.uuidV1` will generate the dialect-specific function to generate a UUID.
+In unsupported dialects, using these functions, except as [the default value of an attribute](../models/data-types.mdx#built-in-default-values-for-uuid), will throw an error.
+
+```ts
+sequelize.query(sql`INSERT INTO users (id) VALUES (${sql.uuidV4()})`);
+```
+
+```sql
+-- postgres example
+INSERT INTO users (id) VALUES (gen_random_uuid())
+```
+
+These functions are supported by the following dialects:
+
+<UuidSupportTable />
+
 ### `sql.col`
 
 :::caution
 
-This function is available for backwards compatibility, and there are currently no plans to deprecate it, 
+This function is available for backwards compatibility, and there are currently no plans to deprecate it,
 but it is not recommended to use in new code. Prefer instead to use [`sql.attribute`](#sqlattribute), [`sql.identifier`](#sqlidentifier),
 and the `sql` template tag.