[IMP] doc: improve organization of upgrades docs
* Add autodoc directives to generate documentation directly from upgrade-util repo. * Group all upgrades-related reference documentation into one group in the sidebar, instead of having two entries. * Mention `upgrades` vs `migrations` directory. It has been supported since a while but nothing was explicit in the documentation. Original commit:91a48bfe88closes odoo/documentation#8849 X-original-commit:ef4b5f87d5Signed-off-by: Victor Feyens (vfe) <vfe@odoo.com>
This commit is contained in:
Alvaro Fuentes
committed by
Victor Feyens
Victor Feyens
parent
16fd9dc828
commit
3bba491f57
@@ -0,0 +1,106 @@
|
||||
===============
|
||||
Upgrade scripts
|
||||
===============
|
||||
|
||||
An upgrade script is a Python file containing a function called :meth:`migrate`, which the upgrade
|
||||
process invokes during the update of a module.
|
||||
|
||||
.. method:: migrate(cr, version)
|
||||
|
||||
:param cr: current database cursor
|
||||
:type cr: :class:`~odoo.sql_db.Cursor`
|
||||
:param str version: installed version of the module
|
||||
|
||||
Typically, this function executes one or multiple SQL queries and can also access Odoo's ORM, as
|
||||
well as the :doc:`./upgrade_utils`.
|
||||
|
||||
Writing upgrade scripts
|
||||
=======================
|
||||
|
||||
Upgrade scripts follow a specific tree structure with a naming convention which determines when they
|
||||
are executed.
|
||||
|
||||
The structure of an upgrade script path is :file:`$module/migrations/$version/{pre,post,end}-*.py`,
|
||||
where `$module` is the module for which the script will run, `$version` is the full version of the
|
||||
module (including Odoo's major version and the module's minor version) and `{pre|post|end}-*.py` is
|
||||
the file that needs to be executed. The file's name will determine the :ref:`phase
|
||||
<upgrade-scripts/phases>` 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
|
||||
installed version and equal or lower to the updated version of the module.
|
||||
|
||||
.. example::
|
||||
|
||||
Directory structure of an upgrade script for a custom module named `awesome_partner` upgraded
|
||||
to version `2.0` on Odoo 17.
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
awesome_partner/
|
||||
|-- migrations/
|
||||
| |-- 17.0.2.0/
|
||||
| | |-- pre-exclamation.py
|
||||
|
||||
Two upgrade scripts examples with the content of the :file:`pre-exclamation.py`, file adding
|
||||
"!" at the end of partners' names:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import logging
|
||||
|
||||
_logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def migrate(cr, version):
|
||||
cr.execute("UPDATE res_partner SET name = name || '!'")
|
||||
_logger.info("Updated %s partners", cr.rowcount)
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import logging
|
||||
from odoo.upgrade import util
|
||||
|
||||
_logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def migrate(cr, version):
|
||||
env = util.env(cr)
|
||||
|
||||
partners = env["res.partner"].search([])
|
||||
for partner in partners:
|
||||
partner.name += "!"
|
||||
|
||||
_logger.info("Updated %s partners", len(partners))
|
||||
|
||||
Note that in the second example, the script takes advantage of the :doc:`./upgrade_utils` to
|
||||
access the ORM. Check the documentation to find out more about this library.
|
||||
|
||||
.. _upgrade-scripts/phases:
|
||||
|
||||
Phases of upgrade scripts
|
||||
=========================
|
||||
|
||||
The upgrade process consists of three phases for each version of each module:
|
||||
|
||||
#. The pre-phase, before the module is loaded.
|
||||
#. The post-phase, after the module and its dependencies are loaded and updated.
|
||||
#. The end-phase, after all modules have been loaded and updated for that version.
|
||||
|
||||
Upgrade scripts are grouped according to the first part of their filenames into the corresponding
|
||||
phase. Within each phase, the files are executed according to their lexical order.
|
||||
|
||||
.. admonition:: Execution order of example scripts for one module in one version
|
||||
|
||||
#. :file:`pre-10-do_something.py`
|
||||
#. :file:`pre-20-something_else.py`
|
||||
#. :file:`post-do_something.py`
|
||||
#. :file:`post-something.py`
|
||||
#. :file:`end-01-migrate.py`
|
||||
#. :file:`end-migrate.py`
|
||||
@@ -0,0 +1,113 @@
|
||||
=============
|
||||
Upgrade utils
|
||||
=============
|
||||
|
||||
`Upgrade utils <https://github.com/odoo/upgrade-util/>`_ 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 <https://github.com/odoo/upgrade-util/>`_ 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 <https://www.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
|
||||
<https://github.com/odoo/upgrade-util/tree/master/src/util>`_ 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:
|
||||
Reference in New Issue
Block a user