ovsdb: Fix memory leak in transaction.
[openvswitch] / ovsdb / ovsdb-tool.1.in
1 .\" -*- nroff -*-
2 .de IQ
3 .  br
4 .  ns
5 .  IP "\\$1"
6 ..
7 .\" -*- nroff -*-
8 .TH ovsdb\-tool 1 "November 2009" "Open vSwitch" "Open vSwitch Manual"
9 .ds PN ovsdb\-tool
10 .
11 .SH NAME
12 ovsdb\-tool \- Open vSwitch database management utility
13 .
14 .SH SYNOPSIS
15 \fBovsdb\-tool \fR[\fIoptions\fR] \fBcreate\fI db schema\fR
16 .br
17 \fBovsdb\-tool \fR[\fIoptions\fR] \fBcompact \fIdb \fR[\fItarget\fR]
18 .br
19 \fBovsdb\-tool \fR[\fIoptions\fR] \fBconvert\fI db schema
20 \fR[\fItarget\fR]
21 .br
22 \fBovsdb\-tool \fR[\fIoptions\fR] \fBneeds\-conversion\fI db schema\fR
23 .br
24 \fBovsdb\-tool \fR[\fIoptions\fR] \fBdb\-version\fI db\fR
25 .br
26 \fBovsdb\-tool \fR[\fIoptions\fR] \fBschema\-version\fI schema\fR
27 .br
28 \fBovsdb\-tool \fR[\fIoptions\fR] \fBdb\-cksum\fI db\fR
29 .br
30 \fBovsdb\-tool \fR[\fIoptions\fR] \fBschema\-cksum\fI schema\fR
31 .br
32 \fBovsdb\-tool \fR[\fIoptions\fR] \fBquery\fI db transaction\fR
33 .br
34 \fBovsdb\-tool \fR[\fIoptions\fR] \fBtransact\fI db transaction\fR
35 .br
36 \fBovsdb\-tool \fR[\fIoptions\fR] [\fB\-m\fR | \fB\-\-more\fR]... \fBshow\-log\fI db\fR
37 .br
38 \fBovsdb\-tool help\fR
39 .so lib/vlog-syn.man
40 .so lib/common-syn.man
41 .
42 .SH DESCRIPTION
43 The \fBovsdb\-tool\fR program is a command-line tool for managing Open
44 vSwitch database (OVSDB) files.  It does not interact directly with
45 running Open vSwitch database servers (instead, use
46 \fBovsdb\-client\fR).
47 .
48 .SS "Basic Commands"
49 .IP "\fBcreate\fI db schema\fR"
50 Reads an OVSDB schema from the file named \fIschema\fR and creates a
51 new OVSDB database file named \fIdb\fR using that schema.  The new
52 database is initially empty.  This command will not overwrite an
53 existing \fIdb\fR.
54 .IP
55 \fIschema\fR must contain an OVSDB schema in JSON format.  Refer to
56 the OVSDB specification for details.
57 .
58 .IP "\fBcompact\fI db \fR[\fItarget\fR]"
59 Reads \fIdb\fR and writes a compacted version.  If \fItarget\fR is
60 specified, the compacted version is written as a new file named
61 \fItarget\fR, which must not already exist.  If \fItarget\fR is
62 omitted, then the compacted version of the database replaces \fIdb\fR
63 in-place.
64 .
65 .IP "\fBconvert\fI db schema \fR[\fItarget\fR]"
66 Reads \fIdb\fR, translating it into to the schema specified in
67 \fIschema\fR, and writes out the new interpretation.  If \fItarget\fR
68 is specified, the translated version is written as a new file named
69 \fItarget\fR, which must not already exist.  If \fItarget\fR is
70 omitted, then the translated version of the database replaces \fIdb\fR
71 in-place.
72 .IP
73 This command can do simple ``upgrades'' and ``downgrades'' on a
74 database's schema.  The data in \fIdb\fR must be valid when
75 interpreted under \fIschema\fR, with only one exception: data in
76 \fIdb\fR for tables and columns that do not exist in \fIschema\fR are
77 ignored.  Columns that exist in \fIschema\fR but not in \fIdb\fR are
78 set to their default values.  All of \fIschema\fR's constraints apply
79 in full.
80 .
81 .IP "\fBneeds\-conversion\fI db schema\fR"
82 Reads the schema embedded in \fIdb\fR and the standalone schema in
83 \fIschema\fR and compares them.  If the schemas are the same, prints
84 \fBno\fR on stdout; if they differ, print \fByes\fR.
85 .
86 .IP "\fBdb\-version\fI db\fR"
87 .IQ "\fBschema\-version\fI schema\fR"
88 Prints the version number in the schema embedded within the database
89 \fIdb\fR or in the standalone schema \fIschema\fR on stdout.  A schema
90 version number has the form \fIx\fB.\fIy\fB.\fIz\fR.  See
91 \fBovs\-vswitchd.conf.db\fR(5) for details.
92 .IP
93 Schema version numbers and Open vSwitch version numbers are
94 independent.
95 .IP
96 If \fIschema\fR or \fIdb\fR was created before schema versioning was
97 introduced, then it will not have a version number and this command
98 will print a blank line.
99 .
100 .IP "\fBdb\-cksum\fI db\fR"
101 .IQ "\fBschema\-cksum\fI schema\fR"
102 Prints the checksum in the schema embedded within the database
103 \fIdb\fR or of the standalone schema \fIschema\fR on stdout.
104 .IP
105 If \fIschema\fR or \fIdb\fR was created before schema checksums were
106 introduced, then it will not have a checksum and this command
107 will print a blank line.
108 .
109 .IP "\fBquery\fI db transaction\fR"
110 Opens \fIdb\fR, executes \fItransaction\fR on it, and prints the
111 results.  The \fItransaction\fR must be a JSON array in the format of
112 the \fBparams\fR array for the JSON-RPC \fBtransact\fR method, as
113 described in the OVSDB specification.
114 .IP
115 The \fIdb\fR is opened for read-only access, so this command may
116 safely run concurrently with other database activity, including
117 \fBovsdb\-server\fR and other database writers.  The \fItransaction\fR
118 may specify database modifications, but these will have no effect on
119 \fIdb\fR.
120 .
121 .IP "\fBtransact\fI db transaction\fR"
122 Opens \fIdb\fR, executes \fItransaction\fR on it, prints the results,
123 and commits any changes to \fIdb\fR.  The \fItransaction\fR must be a
124 JSON array in the format of the \fBparams\fR array for the JSON-RPC
125 \fBtransact\fR method, as described in the OVSDB specification.
126 .IP
127 The \fIdb\fR is opened and locked for read/write access, so this
128 command will fail if the database is opened for writing by any other
129 process, including \fBovsdb\-server\fR(1).  Use \fBovsdb\-client\fR(1),
130 instead, to write to a database that is served by
131 \fBovsdb\-server\fR(1).
132 .
133 .IP "\fBshow\-log\fI db\fR"
134 Prints a summary of the records in \fBdb\fR's log, including the time
135 and date at which each database change occurred and any associated
136 comment.  This may be useful for debugging.
137 .PP
138 To increase the verbosity of output, add \fB\-m\fR (or \fB\-\-more\fR)
139 one or more times to the command line.  With one \fB\-m\fR,
140 \fBshow\-log\fR prints a summary of the records added, deleted, or
141 modified by each transaction.  With two \fB\-m\fRs, \fBshow\-log\fR
142 also prints the values of the columns modified by each change to a
143 record.
144 .
145 .SH OPTIONS
146 .SS "Logging Options"
147 .so lib/vlog.man
148 .SS "Other Options"
149 .so lib/common.man
150 .SH "SEE ALSO"
151 .
152 \fBovsdb\-server\fR(1),
153 \fBovsdb\-client\fR(1),
154 and the OVSDB specification.