Skip to content

Commit 6c61825

Browse files
dereuromarkdereuromark
committed
Add migration guide.
1 parent deecb9d commit 6c61825

File tree

3 files changed

+159
-2
lines changed

3 files changed

+159
-2
lines changed

‎config/app.example.php‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,8 @@
66

77
return [
88
'Migrations' => [
9-
'unsigned_primary_keys' => null,
10-
'column_null_default' => null,
9+
'unsigned_primary_keys' => null, // Default false
10+
'unsigned_ints' => null, // Default false, make sure this is aligned with the above config
11+
'column_null_default' => null, // Default false
1112
],
1213
];

‎docs/en/index.rst‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,12 @@ your application in your **config/app.php** file as explained in the `Database
4343
Configuration section
4444
<https://book.cakephp.org/5/en/orm/database-basics.html#database-configuration>`__.
4545

46+
Upgrading from 4.x
47+
==================
48+
49+
If you are upgrading from Migrations 4.x, please see the :doc:`upgrading` guide
50+
for breaking changes and migration steps.
51+
4652
Overview
4753
========
4854

@@ -841,6 +847,7 @@ Feature Flags
841847
Migrations offers a few feature flags for compatibility. These features are disabled by default but can be enabled if required:
842848

843849
* ``unsigned_primary_keys``: Should Migrations create primary keys as unsigned integers? (default: ``false``)
850+
* ``unsigned_ints``: Should Migrations create all integer columns as unsigned? (default: ``false``)
844851
* ``column_null_default``: Should Migrations create columns as null by default? (default: ``false``)
845852
* ``add_timestamps_use_datetime``: Should Migrations use ``DATETIME`` type
846853
columns for the columns added by ``addTimestamps()``.
@@ -849,9 +856,18 @@ Set them via Configure to enable (e.g. in ``config/app.php``)::
849856

850857
'Migrations' => [
851858
'unsigned_primary_keys' => true,
859+
'unsigned_ints' => true,
852860
'column_null_default' => true,
853861
],
854862

863+
.. note::
864+
865+
The ``unsigned_primary_keys`` and ``unsigned_ints`` options only affect MySQL databases.
866+
When generating migrations with ``bake migration_snapshot`` or ``bake migration_diff``,
867+
the ``signed`` attribute will only be included in the output for unsigned columns
868+
(as ``'signed' => false``). Signed is the default for integer columns in MySQL, so
869+
``'signed' => true`` is never output.
870+
855871
Skipping the ``schema.lock`` file generation
856872
============================================
857873

‎docs/en/upgrading.rst‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
Upgrading from 4.x to 5.x
2+
#########################
3+
4+
Migrations 5.x includes significant changes from 4.x. This guide outlines
5+
the breaking changes and what you need to update when upgrading.
6+
7+
Requirements
8+
============
9+
10+
- **PHP 8.2+** is now required (was PHP 8.1+)
11+
- **CakePHP 5.3+** is now required
12+
- **Phinx has been removed** - The builtin backend is now the only supported backend
13+
14+
If you were already using the builtin backend in 4.x (introduced in 4.3, default in 4.4),
15+
the upgrade should be straightforward. See :doc:`upgrading-to-builtin-backend` for more
16+
details on API differences between the phinx and builtin backends.
17+
18+
Command Changes
19+
===============
20+
21+
The phinx wrapper commands have been removed. The new command structure is:
22+
23+
Migrations
24+
----------
25+
26+
The migration commands remain unchanged:
27+
28+
.. code-block:: bash
29+
30+
bin/cake migrations migrate
31+
bin/cake migrations rollback
32+
bin/cake migrations status
33+
bin/cake migrations mark_migrated
34+
bin/cake migrations dump
35+
36+
Seeds
37+
-----
38+
39+
Seed commands have changed:
40+
41+
.. code-block:: bash
42+
43+
# 4.x # 5.x
44+
bin/cake migrations seed bin/cake seeds run
45+
bin/cake migrations seed --seed X bin/cake seeds run X
46+
47+
The new seed commands are:
48+
49+
- ``bin/cake seeds run`` - Run seed classes
50+
- ``bin/cake seeds run SeedName`` - Run a specific seed
51+
- ``bin/cake seeds status`` - Show seed execution status
52+
- ``bin/cake seeds reset`` - Reset seed execution tracking
53+
54+
Maintaining Backward Compatibility
55+
----------------------------------
56+
57+
If you need to maintain the old ``migrations seed`` command for existing scripts or
58+
CI/CD pipelines, you can add command aliases in your ``src/Application.php``::
59+
60+
public function console(CommandCollection $commands): CommandCollection
61+
{
62+
$commands = $this->addConsoleCommands($commands);
63+
64+
// Add backward compatibility alias
65+
$commands->add('migrations seed', \Migrations\Command\SeedCommand::class);
66+
67+
return $commands;
68+
}
69+
70+
Removed Classes and Namespaces
71+
==============================
72+
73+
The following have been removed in 5.x:
74+
75+
- ``Migrations\Command\Phinx\*`` - All phinx wrapper commands
76+
- ``Migrations\Command\MigrationsCommand`` - Use ``bin/cake migrations`` entry point
77+
- ``Migrations\Command\MigrationsSeedCommand`` - Use ``bin/cake seeds run``
78+
- ``Migrations\Command\MigrationsCacheBuildCommand`` - Schema cache is managed differently
79+
- ``Migrations\Command\MigrationsCacheClearCommand`` - Schema cache is managed differently
80+
- ``Migrations\Command\MigrationsCreateCommand`` - Use ``bin/cake bake migration``
81+
82+
If you have code that directly references any of these classes, you will need to update it.
83+
84+
API Changes
85+
===========
86+
87+
Adapter Query Results
88+
---------------------
89+
90+
If your migrations use ``AdapterInterface::query()`` to fetch rows, the return type has
91+
changed from a phinx result to ``Cake\Database\StatementInterface``::
92+
93+
// 4.x (phinx)
94+
$stmt = $this->getAdapter()->query('SELECT * FROM articles');
95+
$rows = $stmt->fetchAll();
96+
$row = $stmt->fetch();
97+
98+
// 5.x (builtin)
99+
$stmt = $this->getAdapter()->query('SELECT * FROM articles');
100+
$rows = $stmt->fetchAll('assoc');
101+
$row = $stmt->fetch('assoc');
102+
103+
New Features in 5.x
104+
===================
105+
106+
5.x includes several new features:
107+
108+
Seed Tracking
109+
-------------
110+
111+
Seeds are now tracked in a ``cake_seeds`` table by default, preventing accidental re-runs.
112+
Use ``--force`` to run a seed again, or ``bin/cake seeds reset`` to clear tracking.
113+
See :doc:`seeding` for more details.
114+
115+
Check Constraints
116+
-----------------
117+
118+
Support for database check constraints via ``addCheckConstraint()``.
119+
See :doc:`writing-migrations` for usage details.
120+
121+
MySQL ALTER Options
122+
-------------------
123+
124+
Support for ``ALGORITHM`` and ``LOCK`` options on MySQL ALTER TABLE operations,
125+
allowing control over how MySQL performs schema changes.
126+
127+
insertOrSkip() for Seeds
128+
------------------------
129+
130+
New ``insertOrSkip()`` method for seeds to insert records only if they don't already exist,
131+
making seeds more idempotent.
132+
133+
Migration File Compatibility
134+
============================
135+
136+
Your existing migration files should work without changes in most cases. The builtin backend
137+
provides the same API as phinx for common operations.
138+
139+
If you encounter issues with existing migrations, please report them at
140+
https://github.com/cakephp/migrations/issues

0 commit comments

Comments
 (0)