Merge remote-tracking branch 'origin/main' into feat/visualize-jobs

docs/admin/overview.mdx

@@ -86,20 +86,21 @@ const config = buildConfig({
 
 The following options are available:
 
-| Option        | Description                                                                                                                                                           |
-|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **`avatar`**      | Set account profile picture. Options: `gravatar`, `default` or a custom React component.                                                                              |
-| **`autoLogin`**   | Used to automate log-in for dev and demonstration convenience. [More details](../authentication/overview).                                                            |
-| **`buildPath`**   | Specify an absolute path for where to store the built Admin bundle used in production. Defaults to `path.resolve(process.cwd(), 'build')`.                            |
-| **`components`**  | Component overrides that affect the entirety of the Admin Panel. [More details](./components).                                                                        |
-| **`custom`**      | Any custom properties you wish to pass to the Admin Panel.                                                                                                            |
-| **`dateFormat`**  | The date format that will be used for all dates within the Admin Panel. Any valid [date-fns](https://date-fns.org/) format pattern can be used.                       |
-| **`disable`**     | If set to `true`, the entire Admin Panel will be disabled.                                                                                                            |
-| **`livePreview`** | Enable real-time editing for instant visual feedback of your front-end application. [More details](../live-preview/overview).                                         |
-| **`meta`**        | Base metadata to use for the Admin Panel. [More details](./metadata). |
-| **`routes`**      | Replace built-in Admin Panel routes with your own custom routes. [More details](#customizing-routes).                                                                 |
-| **`theme`**       | Restrict the Admin Panel theme to use only one of your choice. Default is `all`.
-| **`user`**        | The `slug` of the Collection that you want to allow to login to the Admin Panel. [More details](#the-admin-user-collection).                                          |
+| Option                         | Description                                                                                                                                                           |
+|--------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **`avatar`**                   | Set account profile picture. Options: `gravatar`, `default` or a custom React component.                                                                              |
+| **`autoLogin`**                | Used to automate log-in for dev and demonstration convenience. [More details](../authentication/overview).                                                            |
+| **`buildPath`**                | Specify an absolute path for where to store the built Admin bundle used in production. Defaults to `path.resolve(process.cwd(), 'build')`.                            |
+| **`components`**               | Component overrides that affect the entirety of the Admin Panel. [More details](./components).                                                                        |
+| **`custom`**                   | Any custom properties you wish to pass to the Admin Panel.                                                                                                            |
+| **`dateFormat`**               | The date format that will be used for all dates within the Admin Panel. Any valid [date-fns](https://date-fns.org/) format pattern can be used.                       |
+| **`disable`**                  | If set to `true`, the entire Admin Panel will be disabled.                                                                                                            |
+| **`livePreview`**              | Enable real-time editing for instant visual feedback of your front-end application. [More details](../live-preview/overview).                                         |
+| **`meta`**                     | Base metadata to use for the Admin Panel. [More details](./metadata).                                                                                                 |
+| **`routes`**                   | Replace built-in Admin Panel routes with your own custom routes. [More details](#customizing-routes).                                                                 |
+| **`suppressHydrationWarning`** | If set to `true`, suppresses React hydration mismatch warnings during the hydration of the root <html> tag. Defaults to `false`.                                      |
+| **`theme`**                    | Restrict the Admin Panel theme to use only one of your choice. Default is `all`.                                                                                      |
+| **`user`**                     | The `slug` of the Collection that you want to allow to login to the Admin Panel. [More details](#the-admin-user-collection).                                          |
 
 <Banner type="success">
   <strong>Reminder:</strong>

docs/database/migrations.mdx

@@ -57,6 +57,38 @@ you need to do is pass the `req` object to any [local API](/docs/local-api/overv
 after your `up` or `down` function runs. If the migration errors at any point or fails to commit, it is caught and the
 transaction gets aborted. This way no change is made to the database if the migration fails.
 
+### Using database directly with the transaction
+
+Additionally, you can bypass Payload's layer entirely and perform operations directly on your underlying database within the active transaction:
+
+### MongoDB:
+```ts
+import { type MigrateUpArgs } from '@payloadcms/db-mongodb'
+
+export async function up({ session, payload, req }: MigrateUpArgs): Promise<void> {
+  const posts = await payload.db.collections.posts.collection.find({ session }).toArray()
+}
+```
+
+### Postgres:
+```ts
+import { type MigrateUpArgs, sql } from '@payloadcms/db-postgres'
+
+export async function up({ db, payload, req }: MigrateUpArgs): Promise<void> {
+  const { rows: posts } = await db.execute(sql`SELECT * from posts`)
+}
+```
+
+### SQLite:
+In SQLite, transactions are disabled by default. [More](./transactions).
+```ts
+import { type MigrateUpArgs, sql } from '@payloadcms/db-sqlite'
+
+export async function up({ db, payload, req }: MigrateUpArgs): Promise<void> {
+  const { rows: posts } = await db.run(sql`SELECT * from posts`)
+}
+```
+
 ## Migrations Directory
 
 Each DB adapter has an optional property `migrationDir` where you can override where you want your migrations to be

docs/database/transactions.mdx

@@ -16,6 +16,12 @@ By default, Payload will use transactions for all data changing operations, as l
   MongoDB requires a connection to a replicaset in order to make use of transactions.
 </Banner>
 
+<Banner type="info">
+  <strong>Note:</strong>
+  <br />
+  Transactions in SQLite are disabled by default. You need to pass `transactionOptions: {}` to enable them.
+</Banner>
+
 The initial request made to Payload will begin a new transaction and attach it to the `req.transactionID`. If you have a `hook` that interacts with the database, you can opt in to using the same transaction by passing the `req` in the arguments. For example:
 
 ```ts

docs/local-api/overview.mdx

@@ -131,6 +131,9 @@ const post = await payload.create({
   // Alternatively, you can directly pass a File,
   // if file is provided, filePath will be omitted
   file: uploadedFile,
+
+  // If you want to create a document that is a duplicate of another document
+  duplicateFromID: 'document-id-to-duplicate',
 })
 ```
 

packages/db-mongodb/src/createMigration.ts

@@ -10,11 +10,11 @@ const migrationTemplate = ({ downSQL, imports, upSQL }: MigrationTemplateArgs):
   MigrateUpArgs,
 } from '@payloadcms/db-mongodb'
 ${imports ?? ''}
-export async function up({ payload, req }: MigrateUpArgs): Promise<void> {
+export async function up({ payload, req, session }: MigrateUpArgs): Promise<void> {
 ${upSQL ?? `  // Migration code`}
 }
 
-export async function down({ payload, req }: MigrateDownArgs): Promise<void> {
+export async function down({ payload, req, session }: MigrateDownArgs): Promise<void> {
 ${downSQL ?? `  // Migration code`}
 }
 `

packages/db-mongodb/src/types.ts

@@ -1,3 +1,4 @@
+import type { ClientSession } from 'mongodb'
 import type {
   AggregatePaginateModel,
   IndexDefinition,
@@ -110,5 +111,65 @@ export type FieldToSchemaMap<TSchema> = {
   upload: FieldGeneratorFunction<TSchema, UploadField>
 }
 
-export type MigrateUpArgs = { payload: Payload; req: PayloadRequest }
-export type MigrateDownArgs = { payload: Payload; req: PayloadRequest }
+export type MigrateUpArgs = {
+  /**
+   * The Payload instance that you can use to execute Local API methods
+   * To use the current transaction you must pass `req` to arguments
+   * @example
+   * ```ts
+   *  import { type MigrateUpArgs } from '@payloadcms/db-mongodb'
+   *
+   * export async function up({ session, payload, req }: MigrateUpArgs): Promise<void> {
+   *   const posts = await payload.find({ collection: 'posts', req })
+   * }
+   * ```
+   */
+  payload: Payload
+  /**
+   * The `PayloadRequest` object that contains the current transaction
+   */
+  req: PayloadRequest
+  /**
+   * The MongoDB client session that you can use to execute MongoDB methods directly within the current transaction.
+   * @example
+   * ```ts
+   * import { type MigrateUpArgs } from '@payloadcms/db-mongodb'
+   *
+   * export async function up({ session, payload, req }: MigrateUpArgs): Promise<void> {
+   *   const { rows: posts } = await payload.db.collections.posts.collection.find({ session }).toArray()
+   * }
+   * ```
+   */
+  session?: ClientSession
+}
+export type MigrateDownArgs = {
+  /**
+   * The Payload instance that you can use to execute Local API methods
+   * To use the current transaction you must pass `req` to arguments
+   * @example
+   * ```ts
+   * import { type MigrateDownArgs } from '@payloadcms/db-mongodb'
+   *
+   * export async function down({ session, payload, req }: MigrateDownArgs): Promise<void> {
+   *   const posts = await payload.find({ collection: 'posts', req })
+   * }
+   * ```
+   */
+  payload: Payload
+  /**
+   * The `PayloadRequest` object that contains the current transaction
+   */
+  req: PayloadRequest
+  /**
+   * The MongoDB client session that you can use to execute MongoDB methods directly within the current transaction.
+   * @example
+   * ```ts
+   * import { type MigrateDownArgs } from '@payloadcms/db-mongodb'
+   *
+   * export async function down({ session, payload, req }: MigrateDownArgs): Promise<void> {
+   *   const { rows: posts } = await payload.db.collections.posts.collection.find({ session }).toArray()
+   * }
+   * ```
+   */
+  session?: ClientSession
+}

packages/db-postgres/src/exports/migration-utils.ts

@@ -1 +1 @@
-export { migratePostgresV2toV3 } from '../predefinedMigrations/v2-v3/index.js'
+export { migratePostgresV2toV3 } from '@payloadcms/drizzle/postgres'

packages/db-postgres/src/index.ts

@@ -2,6 +2,7 @@ import type { DatabaseAdapterObj, Payload } from 'payload'
 
 import {
   beginTransaction,
+  buildCreateMigration,
   commitTransaction,
   count,
   countGlobalVersions,
@@ -39,18 +40,15 @@ import {
   createDatabase,
   createExtensions,
   createJSONQuery,
-  createMigration,
   defaultDrizzleSnapshot,
   deleteWhere,
   dropDatabase,
   execute,
-  getMigrationTemplate,
   init,
   insert,
   requireDrizzleKit,
 } from '@payloadcms/drizzle/postgres'
 import { pgEnum, pgSchema, pgTable } from 'drizzle-orm/pg-core'
-import path from 'path'
 import { createDatabaseAdapter, defaultBeginTransaction } from 'payload'
 import { fileURLToPath } from 'url'
 
@@ -59,7 +57,6 @@ import type { Args, PostgresAdapter } from './types.js'
 import { connect } from './connect.js'
 
 const filename = fileURLToPath(import.meta.url)
-const dirname = path.dirname(filename)
 
 export function postgresAdapter(args: Args): DatabaseAdapterObj<PostgresAdapter> {
   const postgresIDType = args.idType || 'serial'
@@ -93,9 +90,13 @@ export function postgresAdapter(args: Args): DatabaseAdapterObj<PostgresAdapter>
       beforeSchemaInit: args.beforeSchemaInit ?? [],
       createDatabase,
       createExtensions,
-      createMigration(args) {
-        return createMigration.bind(this)({ ...args, dirname })
-      },
+      createMigration: buildCreateMigration({
+        executeMethod: 'execute',
+        filename,
+        sanitizeStatements({ sqlExecute, statements }) {
+          return `${sqlExecute}\n ${statements.join('\n')}\`)`
+        },
+      }),
       defaultDrizzleSnapshot,
       disableCreateDatabase: args.disableCreateDatabase ?? false,
       drizzle: undefined,
@@ -105,7 +106,6 @@ export function postgresAdapter(args: Args): DatabaseAdapterObj<PostgresAdapter>
         json: true,
       },
       fieldConstraints: {},
-      getMigrationTemplate,
       idType: postgresIDType,
       initializing,
       localesSuffix: args.localesSuffix || '_locales',