From fde822fefe350238910d6f6bea51d188d240e0a1 Mon Sep 17 00:00:00 2001 From: Florian Brucker Date: Mon, 13 Jun 2016 16:33:18 +0200 Subject: [PATCH] Docs: Extensions should not automatically alter the database structure. See https://github.com/ckan/ideas-and-roadmap/issues/164. --- doc/extensions/best-practices.rst | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/doc/extensions/best-practices.rst b/doc/extensions/best-practices.rst index 078fbc84588..422dc50bec2 100644 --- a/doc/extensions/best-practices.rst +++ b/doc/extensions/best-practices.rst @@ -67,12 +67,28 @@ adding them to ``setup.py``, they should be added to ``requirements.txt``, which can be installed with:: pip install -r requirements.txt - + To prevent accidental breakage of your extension through backwards-incompatible behaviour of newer versions of your dependencies, their versions should be pinned, such as:: requests==2.7.0 - + On the flip side, be mindful that this could also create version conflicts with requirements of considerably newer or older extensions. + + +-------------------------------------------------- +Do not automatically modify the database structure +-------------------------------------------------- + +If your extension uses custom database tables then it needs to modify the +database structure, for example to add the tables after its installation or to +migrate them after an update. These modifications should not be performed +automatically when the extension is loaded, since this can lead to `dead-locks +and other problems`_. + +Instead, create a :doc:`paster command ` which can be run separately. + +.. _dead-locks and other problems: https://github.com/ckan/ideas-and-roadmap/issues/164 +