@payloadcms/plugin-search 3.0.0-beta.39

v3.0.0-beta.39

on Node.js NPM

v3.0.0-beta.39 (2024-05-30)

Features

• db-postgres: relationship column (#6339) (edfa85b)

Bug Fixes

• next: ssr live preview was not dispatching document save events (#6572) (e603c83)

BREAKING CHANGES

• db-postgres: relationship column (#6339) (edfa85b)

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) 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:

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:
#4163

Contributors

• Elliot DeNolf (@denolfe)
• Dan Ribbens (@DanRibbens)
• Jacob Fletcher (@jacobsfletch)