Comment 5 for bug 1352550

Brad Clements (bkc) wrote :


I did not run 'upgrade' on the backend. Is that documented as being required somewhere?

Searching the code base, I only see that it's called in some unit tests, it's not being explicitely called in any of the examples.

I have seen examples of using the backend as a context manager but that just makes me think "oh, that's a nice way to automatically call close() on the backend", so I must either do that or make sure I call close() myself.

The requirement to call upgrade() before using a backend doesn't seem obvious anywhere.

In fact, in the docs at

it says "if the schema is already up to date this is a no-op". Since I know I'm creating new logbooks, this implies there's no need to use the context manager in my case, and for it says "Migrate the persistence backend to the most recent version." which also indicates it's only needed if there are existing logbooks that might need to be upgraded

Also what if I pass a dictionary/persistence_conf for the backend parameter to engines.load instead of an actual backend. Will all the engines call upgrade() , or do they do so only as an artifact of using the backend through the context manager?

if I write my own backend, should I rely on all users always calling upgrade() before taking any other action with the backend connection, or might they only call it when there are existing logbooks that might need to have their schema upgraded?

It sounds like 'upgrade' is being used partly to prepare() in addition to doing a schema update. Should the prepare() functionality be broken out into it's own backend method? Or should upgrade() be renamed 'prepare_and_upgrade()' , or just update the documentation and examples?