From 4b3f577cff03bb0ac45775a47eaa0b2fb7980296 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 4 Sep 2023 15:39:03 +0900 Subject: [PATCH 1/8] docs: add empty lines --- user_guide_src/source/dbmgmt/migration.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/user_guide_src/source/dbmgmt/migration.rst b/user_guide_src/source/dbmgmt/migration.rst index 874d276632e1..93dacf93529e 100644 --- a/user_guide_src/source/dbmgmt/migration.rst +++ b/user_guide_src/source/dbmgmt/migration.rst @@ -67,9 +67,13 @@ Database Groups A migration will only be run against a single database group. If you have multiple groups defined in **app/Config/Database.php**, then it will run against the ``$defaultGroup`` as specified -in that same configuration file. There may be times when you need different schemas for different +in that same configuration file. + +There may be times when you need different schemas for different database groups. Perhaps you have one database that is used for all general site information, while -another database is used for mission critical data. You can ensure that migrations are run only +another database is used for mission critical data. + +You can ensure that migrations are run only against the proper group by setting the ``$DBGroup`` property on your migration. This name must match the name of the database group exactly: From 2c59aa9782af7e4df224edd2780c0f58d6faad66 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 4 Sep 2023 15:39:39 +0900 Subject: [PATCH 2/8] docs: fix text decration --- user_guide_src/source/dbmgmt/migration.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/user_guide_src/source/dbmgmt/migration.rst b/user_guide_src/source/dbmgmt/migration.rst index 93dacf93529e..5f90d41815cf 100644 --- a/user_guide_src/source/dbmgmt/migration.rst +++ b/user_guide_src/source/dbmgmt/migration.rst @@ -120,7 +120,7 @@ Migrates a database group with all available migrations: You can use (migrate) with the following options: - ``-g`` - to chose database group, otherwise default database group will be used. -- ``-n`` - to choose namespace, otherwise (App) namespace will be used. +- ``-n`` - to choose namespace, otherwise ``App`` namespace will be used. - ``--all`` - to migrate all namespaces to the latest migration. This example will migrate ``Acme\Blog`` namespace with any new migrations on the test database group: @@ -168,7 +168,7 @@ Refreshes the database state by first rolling back all migrations, and then migr You can use (refresh) with the following options: - ``-g`` - to choose database group, otherwise default database group will be used. -- ``-n`` - to choose namespace, otherwise (App) namespace will be used. +- ``-n`` - to choose namespace, otherwise ``App`` namespace will be used. - ``--all`` - to refresh all namespaces. - ``-f`` - to force a bypass confirmation question, it is only asked in a production environment. From 6cc94db4fa8c677babc405eda1faaaff9c92b58a Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 4 Sep 2023 15:40:12 +0900 Subject: [PATCH 3/8] docs: fix descripton for -g option in `spark migrate` --- user_guide_src/source/dbmgmt/migration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user_guide_src/source/dbmgmt/migration.rst b/user_guide_src/source/dbmgmt/migration.rst index 5f90d41815cf..70f4f4cbe4ea 100644 --- a/user_guide_src/source/dbmgmt/migration.rst +++ b/user_guide_src/source/dbmgmt/migration.rst @@ -119,7 +119,7 @@ Migrates a database group with all available migrations: You can use (migrate) with the following options: -- ``-g`` - to chose database group, otherwise default database group will be used. +- ``-g`` - to specify database group. If specified, only migrations for the specified database group will be run. If not specified, all migrations will be run. - ``-n`` - to choose namespace, otherwise ``App`` namespace will be used. - ``--all`` - to migrate all namespaces to the latest migration. From 710649f57f3f46ae68ce3e4274d87bfad01a62cb Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 4 Sep 2023 16:00:25 +0900 Subject: [PATCH 4/8] fix: remove `-g` option in `migrate:rollback` Rollback specifies a batch number and returns the database to that state. It is not possible to specify a specific group to return to a state. --- system/Commands/Database/MigrateRollback.php | 6 ------ system/Database/MigrationRunner.php | 10 +++------- user_guide_src/source/dbmgmt/migration.rst | 3 +-- 3 files changed, 4 insertions(+), 15 deletions(-) diff --git a/system/Commands/Database/MigrateRollback.php b/system/Commands/Database/MigrateRollback.php index c29ce84be443..c104a81fd9fa 100644 --- a/system/Commands/Database/MigrateRollback.php +++ b/system/Commands/Database/MigrateRollback.php @@ -58,7 +58,6 @@ class MigrateRollback extends BaseCommand */ protected $options = [ '-b' => 'Specify a batch to roll back to; e.g. "3" to return to batch #3', - '-g' => 'Set database group', '-f' => 'Force command - this option allows you to bypass the confirmation question when running this command in a production environment', ]; @@ -79,11 +78,6 @@ public function run(array $params) } $runner = Services::migrations(); - $group = $params['g'] ?? CLI::getOption('g'); - - if (is_string($group)) { - $runner->setGroup($group); - } try { $batch = $params['b'] ?? CLI::getOption('b') ?? $runner->getLastBatch() - 1; diff --git a/system/Database/MigrationRunner.php b/system/Database/MigrationRunner.php index eda6bb582e80..241a9e6da5fa 100644 --- a/system/Database/MigrationRunner.php +++ b/system/Database/MigrationRunner.php @@ -220,9 +220,10 @@ public function latest(?string $group = null) * * Calls each migration step required to get to the provided batch * - * @param int $targetBatch Target batch number, or negative for a relative batch, 0 for all + * @param int $targetBatch Target batch number, or negative for a relative batch, 0 for all + * @param string|null $group Deprecated. The designation has no effect. * - * @return mixed Current batch number on success, FALSE on failure or no migrations are found + * @return bool True on success, FALSE on failure or no migrations are found * * @throws ConfigException * @throws RuntimeException @@ -233,11 +234,6 @@ public function regress(int $targetBatch = 0, ?string $group = null) throw ConfigException::forDisabledMigrations(); } - // Set database group if not null - if ($group !== null) { - $this->setGroup($group); - } - $this->ensureTable(); $batches = $this->getBatches(); diff --git a/user_guide_src/source/dbmgmt/migration.rst b/user_guide_src/source/dbmgmt/migration.rst index 70f4f4cbe4ea..10492b94d7ce 100644 --- a/user_guide_src/source/dbmgmt/migration.rst +++ b/user_guide_src/source/dbmgmt/migration.rst @@ -144,7 +144,7 @@ to minimize any potential conflicts between the main application and any modules rollback ======== -Rolls back all migrations, taking the database group to a blank slate, effectively migration 0: +Rolls back all migrations to a blank slate, effectively migration 0: .. code-block:: console @@ -152,7 +152,6 @@ Rolls back all migrations, taking the database group to a blank slate, effective You can use (rollback) with the following options: -- ``-g`` - to choose database group, otherwise default database group will be used. - ``-b`` - to choose a batch: natural numbers specify the batch. - ``-f`` - to force a bypass confirmation question, it is only asked in a production environment. From ec9d7531a5a4eee8020bd12a278e442c1e1b4603 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 4 Sep 2023 16:06:16 +0900 Subject: [PATCH 5/8] docs: fix descriptions for `-g` option --- user_guide_src/source/dbmgmt/migration.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/user_guide_src/source/dbmgmt/migration.rst b/user_guide_src/source/dbmgmt/migration.rst index 10492b94d7ce..175c85fe9da0 100644 --- a/user_guide_src/source/dbmgmt/migration.rst +++ b/user_guide_src/source/dbmgmt/migration.rst @@ -166,7 +166,7 @@ Refreshes the database state by first rolling back all migrations, and then migr You can use (refresh) with the following options: -- ``-g`` - to choose database group, otherwise default database group will be used. +- ``-g`` - to specify database group. If specified, only migrations for the specified database group will be run. If not specified, all migrations will be run. - ``-n`` - to choose namespace, otherwise ``App`` namespace will be used. - ``--all`` - to refresh all namespaces. - ``-f`` - to force a bypass confirmation question, it is only asked in a production environment. @@ -192,7 +192,7 @@ Displays a list of all migrations and the date and time they ran, or '--' if the You can use (status) with the following options: -- ``-g`` - to choose database group, otherwise default database group will be used. +- ``-g`` - to specify database group. If specified, only migrations for the specified database group will be checked. If not specified, all migrations will be checked. make:migration ============== From 6d94e2ec143cedb03bb09545b83ea5d7338704f4 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 4 Sep 2023 16:28:56 +0900 Subject: [PATCH 6/8] docs: fix out-of-dated explanation --- app/Config/Migrations.php | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/app/Config/Migrations.php b/app/Config/Migrations.php index 3c825667cf69..1dec8b9b3a40 100644 --- a/app/Config/Migrations.php +++ b/app/Config/Migrations.php @@ -25,9 +25,7 @@ class Migrations extends BaseConfig * * This is the name of the table that will store the current migrations state. * When migrations runs it will store in a database table which migration - * level the system is at. It then compares the migration level in this - * table to the $config['migration_version'] if they are not the same it - * will migrate up. This must be set. + * files have already been run. */ public string $table = 'migrations'; From f4c831537e3346895ee1a8bd076bdaf134e5f4b9 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 4 Sep 2023 16:33:12 +0900 Subject: [PATCH 7/8] docs: add description for migration table --- user_guide_src/source/dbmgmt/migration.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/user_guide_src/source/dbmgmt/migration.rst b/user_guide_src/source/dbmgmt/migration.rst index 175c85fe9da0..4af207164b73 100644 --- a/user_guide_src/source/dbmgmt/migration.rst +++ b/user_guide_src/source/dbmgmt/migration.rst @@ -223,13 +223,15 @@ Migration Preferences The following is a table of all the config options for migrations, available in **app/Config/Migrations.php**. -========================== ====================== ========================== ============================================================= -Preference Default Options Description -========================== ====================== ========================== ============================================================= -**enabled** true true / false Enable or disable migrations. -**table** migrations None The table name for storing the schema version number. -**timestampFormat** Y-m-d-His\_ The format to use for timestamps when creating a migration. -========================== ====================== ========================== ============================================================= +==================== ============ ============= ============================================================= +Preference Default Options Description +==================== ============ ============= ============================================================= +**enabled** true true / false Enable or disable migrations. +**table** migrations None The table name for storing the schema version number. This + table is always created in the default database group + (``$defaultGroup``). +**timestampFormat** Y-m-d-His\_ The format to use for timestamps when creating a migration. +==================== ============ ============= ============================================================= *************** Class Reference From a58258f73b34bec4d66e7cd521384465b9918d5e Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 5 Sep 2023 10:30:17 +0900 Subject: [PATCH 8/8] doc: add changelog --- user_guide_src/source/changelogs/v4.4.2.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/user_guide_src/source/changelogs/v4.4.2.rst b/user_guide_src/source/changelogs/v4.4.2.rst index dae668909711..3866a7664ee6 100644 --- a/user_guide_src/source/changelogs/v4.4.2.rst +++ b/user_guide_src/source/changelogs/v4.4.2.rst @@ -18,6 +18,11 @@ Message Changes Changes ******* +- **Database Migrations:** The ``-g`` option for the ``spark migrate:rollback`` + command was removed. It did not work from the beginning. Also, the rollback + command returns the database(s) state to a specified batch number and cannot + specify only a specific database group. + Deprecations ************