tchapi/davis v3.1.0

on GitHub

Warning
The previous 3.0.0 was yanked — you should switch to 3.1.0 (this release) directly

What's Changed

• We now use VARCHAR instead of VARBINARY for a bunch of columns
• [Feature] Make the DB driver an env var in #79

This change will also allow Davis to be used with a PostgreSQL database.

How to upgrade

Add the new env var

Specify DATABASE_DRIVER in your env file like so:

DATABASE_DRIVER=mysql

🚨 Breaking change — How to migrate your database

Warning
If you already use PostgreSQL (not supported), DO NOT FOLLOW THESE STEPS. See the "How to upgrade (PostgreSQL)" paragraph below for more information

This upgrade is a good time to enforce the use of migrations.

To do so, you will need to follow the necessary steps BEFORE UPGRADING:

0. Back up your database

This is a safety precaution in case you end up messing with a migration or the database in general. It's highly recommended, even if you know exactly what you're doing.

1. Update your env var to use the serverVersion and charset

This is highly recommended as various database engines will yield different migration plans. You only need to change your DATABASE_URL env var to reflect the actual version of your server, and its charset:

For MariaDB, for instance:

DATABASE_URL=mysql://davis:password@mysql:3306/davis?charset=utf8mb4&serverVersion=mariadb-10.6.10

For MySQL:

DATABASE_URL=mysql://davis:password@mysql:3306/davis?charset=utf8mb4&serverVersion=5.7

Use the correct version of your database of course

2. Check the status of the migrations you have on your db

bin/console doctrine:migrations:status

It should yield a table, like so (some rows have been cut for readability):

+----------------------+----------------------+------------------------------------------------------------------------+
| Versions             | Previous             | DoctrineMigrations\Version20210928132307                               |
|                      | Current              | DoctrineMigrations\Version20221106220411                               |
|                      | Next                 | DoctrineMigrations\Version20221106220412                               |
|                      | Latest               | DoctrineMigrations\Version20221106220412                               |
|----------------------------------------------------------------------------------------------------------------------|
| Migrations           | Executed             | 7                                                                      |
|                      | Executed Unavailable | 0                                                                      |
|                      | Available            | 8                                                                      |
|                      | New                  | 1                                                                      |
+----------------------+----------------------+------------------------------------------------------------------------+

The important bit is if you have ever executed the migration, ie. if Migrations | Executed is not 0

3. Sync the migrations if necessary

a. You have executed at least 1 migration

You don't need to do much more, just skip to 4.

b. You have executed 0 migration

It means that you haven't run any migration before and that the schema was created ad-hoc. To fix this and make sure your db is in sync, we're going to do two steps:

1. Force the update of the schema:

bin/console doctrine:schema:update --force

1. Mark all migrations as passed:

bin/console doctrine:migrations:sync-metadata-storage
bin/console doctrine:migrations:version 'DoctrineMigrations\Version20191030113307' --add --no-interaction
bin/console doctrine:migrations:version 'DoctrineMigrations\Version20191113170650' --add --no-interaction
bin/console doctrine:migrations:version 'DoctrineMigrations\Version20191125093508' --add --no-interaction
bin/console doctrine:migrations:version 'DoctrineMigrations\Version20191202091507' --add --no-interaction
bin/console doctrine:migrations:version 'DoctrineMigrations\Version20191203111729' --add --no-interaction
bin/console doctrine:migrations:version 'DoctrineMigrations\Version20210928132307' --add --no-interaction
bin/console doctrine:migrations:version 'DoctrineMigrations\Version20221106220411' --add --no-interaction

Note
If you have an error like so The metadata storage is not initialized, please run the sync-metadata-storage command to fix this issue., this means that you have not updated your DATABASE_URL env var to use the server version as indicated in point 1.

4. Update the code and migrate

You can now update the code (either directly or get the up to date container), and then run the remaining migrations with:

bin/console doctrine:migrations:migrate

Note
Some migrations are for PostgreSQL, some for MySQL, so it's perfectly normal if you always have a "New" migration that is skipped, and if you're not at the latest one.

[Unsupported] How to upgrade (PostgreSQL)

⚠️ if for some reason you are using a modified version of Davis with a PostgreSQL database, the latest migrations will likely not work as the data will not be converted when changing the column type.

In this case, you need to update manually the database structure and cast all necessary values accordingly (from bytea to varchar), and then mark the single PostgreSQL migration as run with:

bin/console doctrine:migrations:version 'DoctrineMigrations\Version20221106220412' --add

You can see all the columns that have been changed in the migrations\Version20221106220411.php file

Full Changelog: v2.1.0...v3.1.0