Warn against using db_utils for ForeignKey creation

[Matt Riedemann]

The openstack.common.db.sqlalchemy.utils.get_table method shouldn't be using for creating ForeignKeys in db migration scripts because it creates the MetaData object per table but FKs need the metadata to store information for all tables in a given FK otherwise you'll get a cryptic error from sqlalchemy like this:

http://paste.openstack.org/show/75213/

That is super confusing when you know the tables and columns exist in your database, but it turns out you loaded up the metadata/tables from sqlalchemy incorrectly.

We should just have a warning in the docstring for the get_table method to warn against using it for FK creation so others don't fall into that trap.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/85722

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/85722
Committed: https://git.openstack.org/cgit/openstack/oslo-incubator/commit/?id=f0e50edb05520b9af52371116bd8ac08362b03e3
Submitter: Jenkins
Branch: master

commit f0e50edb05520b9af52371116bd8ac08362b03e3
Author: Matt Riedemann <email address hidden>
Date: Mon Apr 7 07:18:04 2014 -0700

    Add a warning to not use get_table for working with ForeignKeys

    The get_table utility loads a single table with a unique MetaData object
    each time it's called but sqlalchemy needs the MetaData object to hold
    information about both tables in the ForeignKey constraint so it
    shouldn't be used when creating those types of constraints. This patch
    adds a warning to the method's docstring against it's usage in that
    case.

    Closes-Bug: #1303824

    Change-Id: I7b038d668f08f166700300fd787a8cf3cab73a17