Storage implementations should support explicit initialize() method instead of less-clear upgrade() method

(bkc):Some storage implementations (impl_dir for example) require the user to call the upgrade() method on the connection before using it.

The documentation for upgrade() indicates that it's purpose is to allow a storage connection to "Migrate the persistence backend to the most recent version". In the case of impl_dir, the upgrade() method doesn't actually do this. Instead the upgrade() method prepares the storage connection for use.

The name 'upgrade()' and the documentation implies that this method only needs to be called if the user expects or desires the backend 'schema' to be upgraded. However in the case of impl_dir (and perhaps others), the connection does not work unless upgrade() is called.

It seems clearer for connections to support an explicit initialize() method, typically called by the engine .prepare() method, instead of supporting a connection.upgrade() method.

A connection initialize() method can be used to:

a. prepare/setup the connection for use, as in the case of impl_dir

b. optionally migrate the persisted data to the most recent version

Although the connection initialize() method will typically be called by engine.prepare() from within a thread lock, the connection initialize() method (like other methods) should be thread safe.

Schema/version upgrading can be done by connection.initialize(), but should be controlled/limited by backend configuration arguments. Consider multiple conductors with long-running jobs being upgraded with newer versions of persistence modules. It may be desirable to disallow automatic upgrading of schemas until all conductor deployments have been upgraded to the latest software version.

To complete the migration from upgrade() to initialize() method:

1. add a initialize() method to persistence implementations.

2. for each implementation, move existing code from upgrade() method to the initialize() method

3. change upgrade() to call the initialize() method

4. change engines and utility methods to call initialize() instead of upgrade()

5. deprecate the upgrade() method

6. eventually delete the upgrade() method

Gerrit topic: https://review.openstack.org/#q,topic:bp/storage-initialize-instead-of-upgrade,n,z

Addressed by: https://review.openstack.org/180351
    Deprecate upgrade (that now is moved to initialize)