1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
|
..
Except where otherwise noted, this document is licensed under Creative
Commons Attribution 3.0 License. You can view the license at:
https://creativecommons.org/licenses/by/3.0/
.. _watcher-db-manage:
=================
watcher-db-manage
=================
The :command:`watcher-db-manage` utility is used to create the database schema
tables that the watcher services will use for storage. It can also be used to
upgrade (or downgrade) existing database tables when migrating between
different versions of watcher.
The `Alembic library <http://alembic.readthedocs.org>`_ 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::
watcher-db-manage --help
.. program:: watcher-db-manage
.. option:: -h, --help
Show help message and exit.
.. option:: --config-dir <DIR>
Path to a config directory with configuration files.
.. option:: --config-file <PATH>
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, purge
The :ref:`command <db-manage_cmds>` to run.
Usage
=====
Options for the various :ref:`commands <db-manage_cmds>` for
:command:`watcher-db-manage` are listed when the :option:`-h` or
:option:`--help`
option is used after the command.
For example::
watcher-db-manage create_schema --help
Information about the database is read from the watcher configuration file
used by the API server and conductor services. This file must be specified
with the :option:`--config-file` option::
watcher-db-manage --config-file /path/to/watcher.conf create_schema
The configuration file defines the database backend to use with the
*connection* database option::
[database]
connection=mysql://root@localhost/watcher
If no configuration file is specified with the :option:`--config-file` option,
:command:`watcher-db-manage` assumes an SQLite database.
.. _db-manage_cmds:
Command Options
===============
:command:`watcher-db-manage` 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::
watcher-db-manage --config-file=/etc/watcher/watcher.conf create_schema
downgrade
---------
.. program:: downgrade
.. option:: -h, --help
Show help for downgrade and exit.
.. option:: --revision <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::
watcher-db-manage --config-file=/etc/watcher/watcher.conf downgrade --revision 2581ebaf0cb2
revision
--------
.. program:: revision
.. option:: -h, --help
Show help for revision and exit.
.. option:: -m <MESSAGE>, --message <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 watcher 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 <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 <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::
watcher-db-manage --config-file=/etc/watcher/watcher.conf upgrade
.. note::
This command is the default if no command is given to
:command:`watcher-db-manage`.
.. 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.
purge
-----
.. program:: purge
.. option:: -h, --help
Show help for purge and exit.
.. option:: -d, --age-in-days
The number of days (starting from today) before which we consider soft
deleted objects as expired and should hence be erased. By default, all
objects soft deleted are considered expired. This can be useful as removing
a significant amount of objects may cause a performance issues.
.. option:: -n, --max-number
The maximum number of database objects we expect to be deleted. If exceeded,
this will prevent any deletion.
.. option:: -t, --goal
Either the UUID or name of the goal to purge.
.. option:: -e, --exclude-orphans
This is a flag to indicate when we want to exclude orphan objects from
deletion.
.. option:: --dry-run
This is a flag to indicate when we want to perform a dry run. This will show
the objects that would be deleted instead of actually deleting them.
This command will purge the current database by removing both its soft deleted
and orphan objects.
|
