75 lines
3.5 KiB
XML
75 lines
3.5 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<section xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
|
xml:id="keystone-db_sync">
|
|
<title>Migrate the Identity Service database</title>
|
|
<para>Between revisions of the Identity Service project, you might
|
|
need to complete SQL migrations. The Identity Service project
|
|
uses SQLAlchemy-migrate (see <link
|
|
xlink:href="http://code.google.com/p/sqlalchemy-migrate/"
|
|
>http://code.google.com/p/sqlalchemy-migrate/</link>) to
|
|
migrate the SQL database between revisions. For core
|
|
components, the source code stores migrations in a central
|
|
repository under a
|
|
<filename>keystone/common/sql/migrate_repo</filename>
|
|
directory.</para>
|
|
<para>Extensions to the Identity Service might also require SQL
|
|
migrations. The directory
|
|
<filename>keystone/contrib/example</filename> in the
|
|
keystone repository contains a sample extension
|
|
migration.</para>
|
|
<procedure>
|
|
<title>To set up a migration for an extension</title>
|
|
<step>
|
|
<para>Create a directory structure where
|
|
<literal>my_extension</literal> is the name of the
|
|
extension, as follows:
|
|
<filename>keystone/contrib/my_extension/migrate_repo/versions/</filename>.</para>
|
|
</step>
|
|
<step>
|
|
<para>Create empty <filename>__init__.py</filename> files
|
|
in the <filename>migrate_repo</filename> and
|
|
<filename>versions</filename>
|
|
subdirectories.</para>
|
|
</step>
|
|
<step>
|
|
<para>Create a <filename>migrate.cfg</filename>
|
|
configuration file in the
|
|
<filename>migrate_repo</filename> subdirectory,
|
|
which conforms to a key/value <filename>.ini</filename> file format.</para>
|
|
<para>An example configuration file:</para>
|
|
<programlisting language="ini">[db_settings]
|
|
repository_id=my_extension
|
|
version_table=migrate_version
|
|
required_dbs=[]</programlisting>
|
|
</step>
|
|
</procedure>
|
|
<procedure>
|
|
<title>To test a migration for a specific extension</title>
|
|
<para>You can use the <command>keystone-manage</command>
|
|
command with the <parameter>--extension</parameter> parameter
|
|
for both the <command>db_sync</command> and
|
|
<command>db_version</command> commands. Ensure that the
|
|
required configuration files exist before completing these
|
|
steps.</para>
|
|
<step>
|
|
<para>Test your migrations with an <literal>example</literal>
|
|
extension:</para>
|
|
<screen><prompt>#</prompt> <userinput>bin/keystone-manage db_sync --extension example</userinput></screen>
|
|
</step>
|
|
<step>
|
|
<para>Migrate to version 1:</para>
|
|
<screen><prompt>#</prompt> <userinput>bin/keystone-manage db_sync --extension example 1</userinput></screen>
|
|
</step>
|
|
<step>
|
|
<para>Migrate back to version 0:</para>
|
|
<screen><prompt>#</prompt> <userinput>bin/keystone-manage db_sync --extension example 0</userinput></screen>
|
|
</step>
|
|
<step>
|
|
<para>Check the version:</para>
|
|
<screen><prompt>#</prompt> <userinput>bin/keystone-manage db_version --extension example</userinput></screen>
|
|
</step>
|
|
</procedure>
|
|
</section>
|