Document which settings can be changed at runtime

[NicoEchaniz]

The current documentation about settings states that they shouldn't be changed at runtime. But there are deployment scenarios - eg. multi-tenancy implementation - where this is necessary.

A bit of IRC chat with jackob k.m. regarding this issue is quoted below:

[15:22:58] <jacobkm> nicoechaniz: I keep meaning to actually run through all of them and put together some documentation on which can and can't be modified at run time.
[15:23:09] <nicoechaniz> jacobkm: yeah, we have been banging our heads with that precise issue : )
[15:23:27] <nicoechaniz> jacobkm: that would really be great
[15:23:29] <jacobkm> nicoechaniz: yup, me too. It's tricky, and we've done a bad job internally being clear about which settings are which.

The problem with settings is that some of them are used only on project initialization and others are actually used throughout the process lifetime. The second kind could be changed at runtime, but there's no way to know which setting falls into which group without going through a lot of trial and error.

[Jacob]

I'd like to put together a document that breaks settings down into three categories:

• Things you can change at run-time (e.g. a middleware) without breaking anything.
• Things you can change at run-time as long as you're careful and trigger re-loading, clear a cache, or dance through some other hoop. It's OK if this requires reading the source.
• Things you should absolutely never change at runtime.

This might also involve code fixes to ensure that settings can actually fit into these categories.

[Gabriel Hurley]

Does this belong in its own document, or should it be worked into the existing settings reference?

My inclination would be to make it part of the settings reference (with perhaps a brief explanation in the docs/topics/settings) but I feel like the settings reference as a whole is starting to get cluttered and could perhaps use some nicer formatting. I played around with it a bit this evening, but haven't come up with something perfect yet.

It's also worth noting that this is loosely related to ​this thread on Django Developers regarding the right way to modify settings during testing (essentially at runtime).

[Carl Meyer]

If we document any settings as "safe to change at runtime", we'd better also document that changing settings at runtime (even the otherwise "safe" ones) is not safe in a multi-threaded hosting environment (or concurrent requests can easily get the wrong setting value).

Given the number of people hosting in such an environment who may not even realize it, I'm not sure we should be documenting anything that encourages changing settings at runtime, until we (pie in the sky) fix settings so they aren't a global.

[NicoEchaniz]

I do not agree with your assessment on this matter. Documenting this information would be very useful for anyone working on multi-tenancy for django projects. There are in fact certain scenarios where multi-tenancy is a valid - if not the only - deployment option.

For reference, I'll add a link to the ​full log of the chat session that inspired the creation of this ticket.

Documentation should state very clearly that runtime-modification of settings is something you should avoid unless you fully understand the consecuences.
If there were consensus on the proper way to handle the threading issue, I think it should be documented too, but an enfatic warning would suffice for the time being to discourage people from fiddling with this lightly.

I'd also like to add that this is just a documentation proposal on current existing features and as such I don't see how this could be of any harm unless it's done carelessly, which I find hard to expect knowing the general quality of django documentation.

[Ramiro Morales]

Replying to NicoEchaniz:

Documentation should state very clearly that runtime-modification of settings is something you should avoid unless you fully understand the consecuences.
If there were consensus on the proper way to handle the threading issue, I think it should be documented too, but an enfatic warning would suffice for the time being to discourage people from fiddling with this lightly.

Nico, I agree with the general intent of this ticket. But just wanted to point that what you ask for in this particular paragraph is already present in the documentation: ​http://docs.djangoproject.com/en/1.0/topics/settings/#altering-settings-at-runtime

[NicoEchaniz]

Ramiro, that portion of the documentation is exactly what jacob was refering to during the chat session that spawned this ticket and it would need some modification if this ticket were to be solved.
It should clearly keep the general warning tone, that's what I meant with my previous comment where I just tried to clarify the fact that adding this information to the documentation does not necessarily mean encouraging people to change settings at runtime.

The mentioned paragraph, instead of saying:
"You shouldn't alter settings in your applications at runtime.

Could read:
"You shouldn't alter settings in your applications at runtime unless you know exactly what you are doing and know how to handle the related issues (eg. threading problems)."

And then refer to the distinction between the different types of setting that jacob describes in ​comment:1.

This would be clear enough for everyone and useful for those with the particular needs this ticket initends to address.

[Danny W. Adair <danny.adair@…>]

I think that once it's documented which settings can be changed at runtime, it would be nice to directly support such runtime changes, maybe even in conjunction with the sites framework (speaking of "optional").

Having one central place for settings is great, and it would be good if runtime changes would not necessitate using another app and therefore different import - see also my question on SO ​http://stackoverflow.com/questions/6528723/changing-django-settings-at-runtime

[Carlton Gibson]

So 10 years later, I'm going to close this as wontfix. ​The docs are clear that this isn't supported:

You shouldn’t alter settings in your applications at runtime.

Maybe it's possible, for some settings, but short of a patch actually showing how we can document this safely and simply, this isn't a foot-gun we should be in the market of enabling.