HSTORE docs fix

(original reporter: jonathan) The HSTORE docs are confusing:

For usage with the SQLAlchemy ORM, it may be desirable to combine the usage of HSTORE withMutableDict dictionary now part of the sqlalchemy.ext.mutable extension. This extension will allow in-place changes to dictionary values to be detected by the unit of work:

It's not really "desirable" -- it's pretty much required for most write operations. ;)

The wording states this is needed for "changes to dictionary values". That's misleading -- as it suggests a change to an existing key/value pair. The extension is required for any changes to the dictionary itself -- be updating a k/v pair or adding a k/v pair. You can only replace the entire attribute with a new dict in order to update without the MutableDict extension.

If you add a new k/v pair, inspecting the attribute shows a new value for the k/v, however the SQL is not emmitted unless the MutableDict extension is activated for the column.

It makes perfect sense what is going on and why. The docs should just be changed to something like...

- This extension will allow in-place changes to dictionary values to be detected by the unit of work:
+ This extension will allow changes to the attribute's dictionary to be detected by the unit of work:

or

- This extension will allow in-place changes to dictionary values to be detected by the unit of work:
+ This extension will allow changes to an existing dictionary ( such as adding a new key/value pair or updating an existing one) to be detected by the unit of work:

Comments (3)