Migration Attributes

[ArtificialOwl]

tasks

• generate metadata from core+available apps (apps are temporary enabled during the process if needed)
• download file from dl.nc.c
• extract data and compare with already applied Migrations
• emulate a generic entry in case a new Attribute is implemented in a future version
• display data using the occ command
• making endpoint to display result on the webclient (not done yet, but easily doable as code is now out of Command file)
• commenting and polishing the code

new occ commands

• running ./occ migrations:generate-metadata to create a JSON file
• running ./occ migrations:preview <version> to display migration that will be executed if an upgrade to version is initiated

details

When adding some attributes to a migration:

#[DropTable(table: 'old_table')]
#[CreateTable(table: 'new_table', description: 'Table is used to store things, but also to get more things', notes: ['this is a notice', 'and another one, if really needed'])]
#[AddColumn(table: 'my_table')]
#[AddColumn(table: 'my_table', name: 'another_field')]
#[AddColumn(table: 'other_table', name: 'last_one', type: ColumnType::DATE)]
#[AddIndex(table: 'my_table')]
#[AddIndex(table: 'my_table', type: IndexType::PRIMARY)]
#[DropColumn(table: 'other_table')]
#[DropColumn(table: 'other_table', name: 'old_column', description: 'field is not used anymore and replaced by \'last_one\'')]
#[DropIndex(table: 'other_table')]
#[ModifyColumn(table: 'other_table')]
#[ModifyColumn(table: 'other_table', name: 'this_field')]
#[ModifyColumn(table: 'other_table', name: 'this_field', type: ColumnType::BIGINT)]
class Version30000Date20240102030405 extends SimpleMigrationStep {

will display some details when running the preview occ command:

steps to execute implemented new commands:

when using an install made from repository (with apps/testing/ available):

generate metadata from current install:

./occ migrations:generate-metadata > /tmp/nc.metadata

enable testing app:

./occ app:enable testing

delete migration from db:

DELETE FROM oc_migrations WHERE `oc_migrations`.`app` = 'testing' AND `oc_migrations`.`version` = '30000Date20240102030405'

preview future migrations:

./occ migrations:preview /tmp/nc.metadata 

result:

Checklist

• Code is properly formatted
• Sign-off message is added to all commits
• Tests (unit, integration, api and/or acceptance) are included
• Screenshots before/after for front-end changes
• Documentation (manuals or wiki) migration attributes documentation#12074
• Backports requested where applicable (ex: critical bugfixes)

[ChristophWurst]

• TableCreation

• TableDeletion

• FieldAdd

• FieldChange

• FieldRemove

• IndexAdd

• IndexRemove

Ease the naming and avoid ambiguity by using standard sql terms

• CreateTable
• DeleteTable
• AddColumn
• ModifyColumn (consider more specific attributes for type change, rename, etc)
• DropColumn
• AddIndex
• DropIndex

[ChristophWurst]

@AndyScherzinger this does not close #45943. It's the first of five changes

[ChristophWurst]

• All new classes, their methods and properties require @since 30.0.0
• All new classes require unit test coverage

[ArtificialOwl]

psalm error not related: #46846

[ArtificialOwl]

when using an install made from repository (with apps/testing/ available):

generate metadata from current install:

./occ migrations:generate-metadata > /tmp/nc.metadata

enable testing app:

./occ app:enable testing

delete migration from db:

DELETE FROM oc_migrations WHERE `oc_migrations`.`app` = 'testing' AND `oc_migrations`.`version` = '30000Date20240102030405'

preview future migrations:

./occ migrations:preview /tmp/nc.metadata 

result:

[ChristophWurst]

Attributes look good

[ArtificialOwl]

/backport to stable29

[DaphneMuller]

@ArtificialOwl please eventually document how to use this command in a portal article, perhaps at the top of https://portal.nextcloud.com/article/Frequently-Asked-Questions/How-to-prepare-for-upgrades#content-database-migrations-between-major-versions

[ChristophWurst]

Developer docs were updated but admin docs are still missing