From 3f8bc3b53d726c0f0105536519def692beac388c Mon Sep 17 00:00:00 2001 From: David Shrewsbury Date: Tue, 23 Sep 2014 13:19:43 -0400 Subject: [PATCH] Add documentation for ironic-dbsync command This adds a new documentation section for the ironic commands. The ironic-dbsync command is the first to be documented. Change-Id: I166a00005092fb7e87b856e7ceca2b88b6eae322 --- doc/source/cmds/ironic-dbsync.rst | 211 ++++++++++++++++++++++++++++++ doc/source/index.rst | 10 +- 2 files changed, 220 insertions(+), 1 deletion(-) create mode 100644 doc/source/cmds/ironic-dbsync.rst diff --git a/doc/source/cmds/ironic-dbsync.rst b/doc/source/cmds/ironic-dbsync.rst new file mode 100644 index 0000000000..8d2892a503 --- /dev/null +++ b/doc/source/cmds/ironic-dbsync.rst @@ -0,0 +1,211 @@ +============= +ironic-dbsync +============= + +The :command:`ironic-dbsync` utility is used to create the database schema +tables that the ironic services will use for storage. It can also be used to +upgrade (or downgrade) existing database tables when migrating between +different versions of ironic. + +The `Alembic library `_ is used to perform +the database migrations. + +Options +======= + +This is a partial list of the most useful options. To see the full list, +run the following:: + + ironic-dbsync --help + +.. program:: ironic-dbsync + +.. option:: -h, --help + + Show help message and exit. + +.. option:: --config-dir + + Path to a config directory with configuration files. + +.. option:: --config-file + + Path to a configuration file to use. + +.. option:: -d, --debug + + Print debugging output. + +.. option:: -v, --verbose + + Print more verbose output. + +.. option:: --version + + Show the program's version number and exit. + +.. option:: upgrade, downgrade, stamp, revision, version, create_schema + + The :ref:`command ` to run. + +Usage +===== + +Options for the various :ref:`commands ` for +:command:`ironic-dbsync` are listed when the :option:`-h` or :option:`--help` +option is used after the command. + +For example:: + + ironic-dbsync create_schema --help + +Information about the database is read from the ironic configuration file +used by the API server and conductor services. This file must be specified +with the :option:`--config-file` option:: + + ironic-dbsync --config-file /path/to/ironic.conf create_schema + +The configuration file defines the database backend to use with the +*connection* database option:: + + [database] + connection=mysql://root@localhost/ironic + +If no configuration file is specified with the :option:`--config-file` option, +:command:`ironic-dbsync` assumes an SQLite database. + +.. _dbsync_cmds: + +Command Options +=============== + +:command:`ironic-dbsync` is given a command that tells the utility what actions +to perform. These commands can take arguments. Several commands are available: + +.. _create_schema: + +create_schema +------------- + +.. program:: create_schema + +.. option:: -h, --help + + Show help for create_schema and exit. + +This command will create database tables based on the most current version. +It assumes that there are no existing tables. + +An example of creating database tables with the most recent version:: + + ironic-dbsync --config-file=/etc/ironic/ironic.conf create_schema + +downgrade +--------- + +.. program:: downgrade + +.. option:: -h, --help + + Show help for downgrade and exit. + +.. option:: --revision + + The revision number you want to downgrade to. + +This command will revert existing database tables to a previous version. +The version can be specified with the :option:`--revision` option. + +An example of downgrading to table versions at revision 2581ebaf0cb2:: + + ironic-dbsync --config-file=/etc/ironic/ironic.conf downgrade --revision 2581ebaf0cb2 + +revision +-------- + +.. program:: revision + +.. option:: -h, --help + + Show help for revision and exit. + +.. option:: -m , --message + + The message to use with the revision file. + +.. option:: --autogenerate + + Compares table metadata in the application with the status of the database + and generates migrations based on this comparison. + +This command will create a new revision file. You can use the +:option:`--message` option to comment the revision. + +This is really only useful for ironic developers making changes that require +database changes. This revision file is used during database migration and +will specify the changes that need to be made to the database tables. Further +discussion is beyond the scope of this document. + +stamp +----- + +.. program:: stamp + +.. option:: -h, --help + + Show help for stamp and exit. + +.. option:: --revision + + The revision number. + +This command will 'stamp' the revision table with the version specified with +the :option:`--revision` option. It will not run any migrations. + +upgrade +------- + +.. program:: upgrade + +.. option:: -h, --help + + Show help for upgrade and exit. + +.. option:: --revision + + The revision number to upgrade to. + +This command will upgrade existing database tables to the most recent version, +or to the version specified with the :option:`--revision` option. + +If there are no existing tables, then new tables are created, beginning +with the oldest known version, and successively upgraded using all of the +database migration files, until they are at the specified version. Note +that this behavior is different from the :ref:`create_schema` command +that creates the tables based on the most recent version. + +An example of upgrading to the most recent table versions:: + + ironic-dbsync --config-file=/etc/ironic/ironic.conf upgrade + +.. note:: + + This command is the default if no command is given to + :command:`ironic-dbsync`. + +.. warning:: + + The upgrade command is not compatible with SQLite databases since it uses + ALTER TABLE commands to upgrade the database tables. SQLite supports only + a limited subset of ALTER TABLE. + +version +------- + +.. program:: version + +.. option:: -h, --help + + Show help for version and exit. + +This command will output the current database version. diff --git a/doc/source/index.rst b/doc/source/index.rst index b2ab02a060..38a1698fb8 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -55,7 +55,7 @@ Admin Guide =========== Overview ----------- +-------- .. toctree:: :maxdepth: 1 @@ -64,6 +64,14 @@ Overview deploy/install-guide deploy/drivers +Commands +-------- + +.. toctree:: + :maxdepth: 1 + + cmds/ironic-dbsync + Indices and tables ==================