diff --git a/content/developer/howtos/upgrade_custom_db.rst b/content/developer/howtos/upgrade_custom_db.rst index 276c2a588..47db26402 100644 --- a/content/developer/howtos/upgrade_custom_db.rst +++ b/content/developer/howtos/upgrade_custom_db.rst @@ -187,10 +187,10 @@ To make sure the custom code is working flawlessly in the new version, follow th Migrate the data ---------------- -During the upgrade of the custom modules, you might have to use -:doc:`upgrade scripts <../reference/upgrade_scripts>` to reflect changes from the source code -to their corresponding data. Together with the upgrade scripts, you can also make use of the -:doc:`../reference/upgrade_utils` and its helper functions. +During the upgrade of the custom modules, you might have to use :doc:`upgrade scripts +<../reference/upgrades/upgrade_scripts>` to reflect changes from the source code to their +corresponding data. Together with the upgrade scripts, you can also make use of the +:doc:`../reference/upgrades/upgrade_utils` and its helper functions. - Any technical data that was renamed during the upgrade of the custom code (models, fields, external identifiers) should be renamed using upgrade scripts to avoid data loss during the @@ -220,7 +220,7 @@ to their corresponding data. Together with the upgrade scripts, you can also mak """ ) - Check the documentation for more information on :doc:`../reference/upgrade_scripts`. + Check the documentation for more information on :doc:`../reference/upgrades/upgrade_scripts`. Upgrade scripts can also be used to: diff --git a/content/developer/reference.rst b/content/developer/reference.rst index 48c56b2d8..1f459c729 100644 --- a/content/developer/reference.rst +++ b/content/developer/reference.rst @@ -12,7 +12,6 @@ Reference reference/user_interface reference/standard_modules reference/cli - reference/upgrade_scripts - reference/upgrade_utils + reference/upgrades reference/external_api reference/extract_api diff --git a/content/developer/reference/upgrade_utils.rst b/content/developer/reference/upgrade_utils.rst deleted file mode 100644 index 7c5da204f..000000000 --- a/content/developer/reference/upgrade_utils.rst +++ /dev/null @@ -1,279 +0,0 @@ -============= -Upgrade utils -============= - -`Upgrade utils `_ is a library that contains helper functions -to facilitate the writing of upgrade scripts. This library, used by Odoo for the upgrade scripts of -standard modules, provides reliability and helps speed up the upgrade process: - -- The helper functions help make sure the data is consistent in the database. -- It takes care of indirect references of the updated records. -- Allows calling functions and avoid writing code, saving time and reducing development risks. -- Helpers allow to focus on what is important for the upgrade and not think of details. - -Installation -============ - -Clone the `Upgrade utils repository `_ locally and start -``odoo`` with the ``src`` directory prepended to the ``--upgrade-path`` option. - -.. code-block:: console - - $ ./odoo-bin --upgrade-path=/path/to/upgrade-util/src,/path/to/other/upgrade/script/directory [...] - -On platforms where you do not manage Odoo yourself, you can install this library via `pip`: - -.. code-block:: console - - $ python3 -m pip install git+https://github.com/odoo/upgrade-util@master - -On `Odoo.sh `_ it is recommended to add it to the :file:`requirements.txt` of -the custom repository. For this, add the following line inside the file:: - - odoo_upgrade @ git+https://github.com/odoo/upgrade-util@master - -Using Upgrade utils -=================== - -Once installed, the following packages are available for the upgrade scripts: - -- :mod:`odoo.upgrade.util`: the helper itself. -- :mod:`odoo.upgrade.testing`: base TestCase classes. - -To use it in upgrade scripts, simply import it: - -.. code-block:: python - - from odoo.upgrade import util - - - def migrate(cr, version): - # Rest of the script - -Now, the helper functions are available to be called through ``util``. - -Util functions -============== - -Upgrade utils provides many useful functions to ease the upgrade process. Here, we describe some -of the most useful ones. Refer to the `util folder -`_ for the comprehensive declaration of -helper functions. - -.. note:: - - All util functions receive :attr:`cr` as a parameter. This refers to the database cursor. Pass - the one received as a parameter in :meth:`migrate`. - -Fields ------- - -.. `[source] `_ -.. method:: remove_field(cr, model, fieldname, cascade=False, drop_column=True, skip_inherit=()) - - Remove a field and its references from the database. - - :param str model: model name of the field to remove - :param str fieldname: name of the field to remove - :param bool cascade: whether the field's column and inheritance are removed in ``CASCADE`` - :param bool drop_column: whether the field's column is dropped - :param list(str) or str skip_inherit: list of models whose field's inheritance is skipped. - Use ``"*"`` to skip all inheritances - -.. `[source] `_ -.. method:: rename_field(cr, model, old, new, update_references=True, domain_adapter=None, skip_inherit=()) - - Rename a field and its references from ``old`` to ``new``. - - :param str model: model name of the field to rename - :param str old: current name od the field to rename - :param str new: new name od the field to rename - :param bool update_references: whether all references of field ``old`` to ``new`` are replaced - in: ``ir_filters``, ``ir_exports_line``, ``ir_act_server``, ``mail_alias``, - ``ir_ui_view_custom (dashboard)``, ``domains (using "domain_adapter")``, ``related fields`` - :param function domain_adapter: function that takes three arguments and returns a domain that - substitutes the original leaf: ``(leaf: Tuple[str,str,Any], in_or: bool, negated: bool)`` -> - ``List[Union[str,Tuple[str,str,Any]]]`` - :param list(str) or str skip_inherit: list of models whose field's inheritance is skipped. - Use ``"*"`` to skip all inheritances - -.. `[source] `_ -.. method:: move_field_to_module(cr, model, fieldname, old_module, new_module, skip_inherit=()) - - Move a field's reference in ``ir_model_data`` table from ``old_module`` to ``new_module``. - - :param str model: model name of the field to move - :param str fieldname: name of the field to move - :param str old_module: current module name of the field to move - :param str new_module: new module name of the field to move - :param list(str) or str skip_inherit: list of models whose field's inheritance is skipped. - Use ``"*"`` to skip all inheritances - -Models ------- - -.. `[source] `_ -.. method:: remove_model(cr, model, drop_table=True, ignore_m2m=()) - - Remove a model and its references from the database. - - :param str model: name of the model to remove - :param bool drop_table: whether the model's table is dropped - :param list(str) or str ignore_m2m: list of m2m tables ignored to remove. Use ``"*"`` to ignore - all m2m tables - -.. `[source] `_ -.. method:: rename_model(cr, old, new, rename_table=True) - - Rename a model and its references from ``old`` to ``new``. - - :param str old: current name of the model to rename - :param str new: new name of the model to rename - :param bool rename_table: whether the model's table is renamed - -.. `[source] `_ -.. method:: merge_model(cr, source, target, drop_table=True, fields_mapping=None, ignore_m2m=()) - - Merge the references from ``source`` model into ``target`` model and removes ``source`` model and - its references. By default, only the fields with the same name in both models are mapped. - - .. warning:: - This function does not move the records from ``source`` model to ``target`` model. - - :param str source: name of the source model of the merge - :param str target: name of the destination model of the merge - :param bool drop_table: whether the source model's table is dropped - :param dict fields_mapping: Dictionary ``{"source_model_field_1": "target_model_field_1", ...}`` - mapping fields with different names on both models - :param list(str) or str ignore_m2m: list of m2m tables ignored to remove from source model. - -Modules -------- - -.. `[source] `_ -.. method:: remove_module(cr, module) - - Uninstall and remove a module and its references from the database. - - :param str module: name of the module to remove - -.. `[source] `_ -.. method:: rename_module(cr, old, new) - - Rename a module and its references from ``old`` to ``new``. - - :param str old: current name of the module to rename - :param str new: new name of the module to rename - -.. `[source] `_ -.. method:: merge_module(cr, old, into, update_dependers=True) - - Move all references of module ``old`` into module ``into``. - - :param str old: name of the source module of the merge - :param str into: ame of the destination module of the merge - :param bool update_dependers: whether the dependencies of modules that depends on ``old`` are - updated - -ORM ---- - -.. `[source] `_ -.. method:: env(cr) - - Create a new environment from the cursor. - - .. warning:: - This function does NOT empty the cache maintained on the cursor for superuser with an empty - environment. A call to `invalidate_cache` will most probably be necessary every time you - directly modify something in database. - - :return: The new environment - :rtype: :class:`~odoo.api.Environment` - -.. `[source] `_ -.. method:: recompute_fields(cr, model, fields, ids=None, logger=_logger, chunk_size=256, strategy="auto") - - Recompute field values. Possible strategies to process the recomputation: - - - ``flush``: Flush the recomputation when it's finished - - ``commit``: Commit the recomputation when it's finished - - ``auto``: The function chooses the best alternative based on the number of records to recompute - and the fields traceability - - :param str model: model name of the field(s) to recompute - :param list(str) fields: list of field names to recompute - :param list(int) ids: list of record IDs to recompute - :param logger: Logger used to print the progress of the function - :type logger: :class:`logging.Logger` - :param int chunk_size: size of the chunk used to split the records for better processing - :param str strategy: strategy used to process the recomputation - -Records -------- - -.. `[source] `_ -.. method:: ref(cr, xmlid) - - Return the id corresponding to the given :term:`xml_id `. - - :param str xml_id: Record xml_id, under the format ```` - :return: Found record id, if any - :rtype: int or `None` - -.. `[source] `_ -.. method:: remove_record(cr, name) - - Remove a record and its references corresponding to the given - :term:`xml_id `. - - :param str name: record xml_id, under the format ```` - -.. `[source] `_ -.. method:: rename_xmlid(cr, old, new, noupdate=None, on_collision="fail") - - Rename the :term:`external Identifier` of a record. Possible actions to take if the external - Identifier already exists on the database: - - - ``fail``: raise ``MigrationError`` and prevent renaming - - ``merge``: renames the external Identifier and removes the old one - - :param str old: current xml_id of the record, under the format ```` - :param str new: new xml_id of the record, under the format ```` - :param bool noupdate: value to set on the ir_model_data record ``noupdate`` field - :param str on_collision: action to take if the xml_id already exists - -.. `[source] `_ -.. method:: ensure_xmlid_match_record(cr, xmlid, model, values) - - Match a record with an xmlid by creating or updating the external identifier. - - This function is useful when migrating in-database records into a custom module, to create the - record's xmlid before the module is updated and avoid duplication. - - :param str xmlid: record xml_id, under the format ```` - :param str model: model name of the record - :param dict values: Dictionary ``{"fieldname_1": "value_1", ...}`` mapping fields and values to - search for the record to update. For example: - - .. code-block:: python - - values = {"id": 123} - values = {"name": "INV/2024/0001", company_id: 1} - - :return: the :term:`xml_id ` of the record. - :rtype: str - -.. `[source] `_ -.. method:: update_record_from_xml(cr, xmlid, reset_write_metadata=True, force_create=True, from_module=None, reset_translations=()) - - Update a record based on its definition in the :doc:`/developer/reference/backend/data`. - - Useful to update ``noupdate`` records, in order to reset them for the upgraded version. - - :param str xmlid: record xml_id, under the format ```` - :param bool reset_write_metadata: whether the metadata before the record update is kept - :param bool force_create: whether the record is created if it does not exist - :param str from_module: name of the module from which to update the record. Useful when the - record is rewritten in another module. - :param set of str reset_translations: set of field names whose translations get reset diff --git a/content/developer/reference/upgrades.rst b/content/developer/reference/upgrades.rst new file mode 100644 index 000000000..bda807dcc --- /dev/null +++ b/content/developer/reference/upgrades.rst @@ -0,0 +1,11 @@ +:nosearch: + +======== +Upgrades +======== + +.. toctree:: + :titlesonly: + + upgrades/upgrade_scripts + upgrades/upgrade_utils diff --git a/content/developer/reference/upgrade_scripts.rst b/content/developer/reference/upgrades/upgrade_scripts.rst similarity index 92% rename from content/developer/reference/upgrade_scripts.rst rename to content/developer/reference/upgrades/upgrade_scripts.rst index 3dc6c3251..fc3df4042 100644 --- a/content/developer/reference/upgrade_scripts.rst +++ b/content/developer/reference/upgrades/upgrade_scripts.rst @@ -26,6 +26,11 @@ module (including Odoo's major version and the module's minor version) and `{pre the file that needs to be executed. The file's name will determine the :ref:`phase ` and order in which it is executed for that module and version. +.. note:: + From Odoo 13 the top-level directory for the upgrade scripts can also be named `upgrades`. This + naming is preferred since it has the correct meaning: *migrate* can be confused with *moving out + of Odoo*. Thus :file:`$module/upgrades/$version/` is also valid. + .. note:: Upgrade scripts are only executed when the module is being updated. Therefore, the module's minor version set in the `$version` directory needs to be higher than the module's diff --git a/content/developer/reference/upgrades/upgrade_utils.rst b/content/developer/reference/upgrades/upgrade_utils.rst new file mode 100644 index 000000000..b133abae9 --- /dev/null +++ b/content/developer/reference/upgrades/upgrade_utils.rst @@ -0,0 +1,113 @@ +============= +Upgrade utils +============= + +`Upgrade utils `_ is a library that contains helper functions +to facilitate the writing of upgrade scripts. This library, used by Odoo for the upgrade scripts of +standard modules, provides reliability and helps speed up the upgrade process: + +- The helper functions help make sure the data is consistent in the database. +- It takes care of indirect references of the updated records. +- Allows calling functions and avoid writing code, saving time and reducing development risks. +- Helpers allow to focus on what is important for the upgrade and not think of details. + +Installation +============ + +Clone the `Upgrade utils repository `_ locally and start +``odoo`` with the ``src`` directory prepended to the ``--upgrade-path`` option. + +.. code-block:: console + + $ ./odoo-bin --upgrade-path=/path/to/upgrade-util/src,/path/to/other/upgrade/script/directory [...] + +On platforms where you do not manage Odoo yourself, you can install this library via `pip`: + +.. code-block:: console + + $ python3 -m pip install git+https://github.com/odoo/upgrade-util@master + +On `Odoo.sh `_ it is recommended to add it to the :file:`requirements.txt` of +the custom repository. For this, add the following line inside the file:: + + odoo_upgrade @ git+https://github.com/odoo/upgrade-util@master + +Using upgrade utils +=================== + +Once installed, the following packages are available for the upgrade scripts: + +- :mod:`odoo.upgrade.util`: the helper itself. +- :mod:`odoo.upgrade.testing`: base TestCase classes. + +To use it in upgrade scripts, simply import it: + +.. code-block:: python + + from odoo.upgrade import util + + + def migrate(cr, version): + # Rest of the script + +Now, the helper functions are available to be called through ``util``. + +Util functions +============== + +Upgrade utils provides many useful functions to ease the upgrade process. Here, we describe some +of the most useful ones. Refer to the `util folder +`_ for the comprehensive declaration of +helper functions. + +.. note:: + + The :attr:`cr` parameter in util functions always refers to the database cursor. Pass the one + received as a parameter in :meth:`migrate`. Not all functions need this parameter. + +.. currentmodule:: odoo.upgrade.util + +Modules +------- + +.. automodule:: odoo.upgrade.util.modules + :members: + +Models +------ + +.. automodule:: odoo.upgrade.util.models + :members: + +Fields +------ + +.. automodule:: odoo.upgrade.util.fields + :members: + +Records +------- + +.. automodule:: odoo.upgrade.util.records + :members: + +ORM +--- + +.. automodule:: odoo.upgrade.util.orm + :members: + +.. automodule:: odoo.upgrade.util.domains + :members: + +SQL +--- + +.. automodule:: odoo.upgrade.util.pg + :members: + +Misc +---- + +.. automodule:: odoo.upgrade.util.misc + :members: