edfa85bcd5
BREAKING CHANGE: Moves `upload` field and `relationship` fields with `hasMany: false` & `relationTo: string` from the many-to-many `_rels` join table to simple columns. This only affects Postgres database users. ## TL;DR We have dramatically simplified the storage of simple relationships in relational databases to boost performance and align with more expected relational paradigms. If you are using the beta Postgres adapter, and you need to keep simple relationship data, you'll need to run a migration script that we provide you. ### Background For example, prior to this update, a collection of "posts" with a simple `hasMany: false` and `relationTo: 'categories'` field would have a `posts_rels` table where the category relations would be stored. This was somewhat unnecessary as simple relations like this can be expressed with a `category_id` column which is configured as a foreign key. This also introduced added complexity for dealing directly with the database if all you have are simple relations. ### Who needs to migrate You need to migrate if you are using the beta Postgres database adapter and any of the following applies to you. - If you have versions enabled on any collection / global - If you use the `upload` field - If you have relationship fields that are `hasMany: false` (default) and `relationTo` to a single category ([has one](https://payloadcms.com/docs/fields/relationship#has-one)) relations ### We have a migration for you Even though the Postgres adapter is in beta, we've prepared a predefined migration that will work out of the box for you to migrate from an earlier version of the adapter to the most recent version easily. It makes the schema changes in step with actually moving the data from the old locations to the new before adding any null constraints and dropping the old columns and tables. ### How to migrate The steps to preserve your data while making this update are as follows. These steps are the same whether you are moving from Payload v2 to v3 or a previous version of v3 beta to the most recent v3 beta. **Important: during these steps, don't start the dev server unless you have `push: false` set on your Postgres adapter.** #### Step 1 - backup Always back up your database before performing big changes, especially in production cases. #### Step 2 - create a pre-update migration Before updating to new Payload and Postgres adapter versions, run `payload migrate:create` without any other config changes to have a prior snapshot of the schema from the previous adapter version #### Step 3 - if you're migrating a dev DB, delete the dev `push` row from your `payload_migrations` table If you're migrating a dev database where you have the default setting to push database changes directly to your DB, and you need to preserve data in your development database, then you need to delete a `dev` migration record from your database. Connect directly to your database in any tool you'd like and delete the dev push record from the `payload_migrations` table using the following SQL statement: ```sql DELETE FROM payload_migrations where batch = -1` ``` #### Step 4 - update Payload and Postgres versions to most recent Update packages, making sure you have matching versions across all `@payloadcms/*` and `payload` packages (including `@payloadcms/db-postgres`) #### Step 5 - create the predefined migration Run the following command to create the predefined migration we've provided: ``` payload migrate:create --file @payloadcms/db-postgres/relationships-v2-v3 ``` #### Step 6 - migrate! Run migrations with the following command: ``` payload migrate ``` Assuming the migration worked, you can proceed to commit this change and distribute it to be run on all other environments. Note that if two servers connect to the same database, only one should be running migrations to avoid transaction conflicts. Related discussion: https://github.com/payloadcms/payload/discussions/4163 --------- Co-authored-by: James <james@trbl.design> Co-authored-by: PatrikKozak <patrik@payloadcms.com>
Payload Live Preview Example Front-End
This is a Next.js app using the App Router. It was made explicitly for Payload's Live Preview Example.
This example uses the App Router, the latest API of Next.js. If your app is using the legacy Pages Router, check out the official Pages Router Example.
IMPORTANT—This application runs on a different server as Payload and establishes a connection from another domain or port over HTTP. For an integrated setup that runs on a single server and uses the Local API, check out how to serve Payload alongside Next.js. To learn more about this, check out how Payload can be used in its various headless capacities.
Getting Started
Payload
First you'll need a running Payload app. There is one made explicitly for this example and can be found here. If you have not done so already, clone it down and follow the setup instructions there. This will provide all the necessary APIs that your Next.js app requires for live preview.
Next.js
- Clone this repo
cdinto this directory and runpnpm i --ignore-workspace*,yarn, ornpm install*If you are running using pnpm within the Payload Monorepo, the
--ignore-workspaceflag is needed so that pnpm generates a lockfile in this example's directory despite the fact that one exists in root.cp .env.example .envto copy the example environment variablespnpm dev,yarn dev, ornpm run devto start the serveropen http://localhost:3001to see the result
Once running you will find a couple seeded pages on your local environment with some basic instructions. You can also start editing the pages by modifying the documents within Payload. See the Live Preview Example for full details.
Learn More
To learn more about Payload and Next.js, take a look at the following resources:
- Payload Documentation - learn about Payload features and API.
- Next.js Documentation - learn about Next.js features and API.
- Learn Next.js - an interactive Next.js tutorial.
You can check out the Payload GitHub repository as well as the Next.js GitHub repository - your feedback and contributions are welcome!
Deployment
The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js. You could also combine this app into a single Express server and deploy in to Payload Cloud.
Check out our Payload deployment documentation or the Next.js deployment documentation for more details.