adding actor.usr_setting to production tables
[migration-tools.git] / mig
1 #!/usr/bin/perl -w
2 ###############################################################################
3 =pod
4
5 =head1 NAME
6
7 mig - git-like program for tracking and manipulating legacy data files for
8 migrations
9
10 =head1 SYNOPSIS
11
12 B<mig> <command> [argument] [...]
13
14 =head1 DESCRIPTION
15
16 B<mig> is used to track and manipulate CSV or CSV-like text files exported from
17 legacy systems for migration into Evergreen.  It can be a wrapper for some
18 other migration tools and tracks state using a PostgreSQL table in a given
19 migration schema.
20
21 It makes use of certain environment variables that may be set by the B<mig-env>
22 tool: PGHOST, PGPORT, PGUSER, PGDATABASE, MIGSCHEMA, and MIGWORKDIR
23
24 For most commands, if the current working directory falls outside of the
25 directory specified by MIGWORKDIR, then mig will assume that environment is
26 also incorrect and bail before doing any actual work.
27
28 ~/.pgpass should also be configured, as B<mig> will not prompt for a database
29 password.
30
31 Only the B<env> and B<help> commands work without the MIGSCHEMA environment
32 variable being set.
33
34 =head1 OVERVIEW
35
36 Using B<mig> should go something like this:
37
38 =over 15
39
40 =item mig env create m_foo # Sets up the environment
41
42 =item mig env use m_foo # Spawns a shell using the configured environment
43
44 =item mig init # creates the m_foo schema in the database if needed, and other tables
45
46 =item mig add patrons.tsv # tracks an incoming data file; repeat for additional files
47
48 =item mig iconv patrons.tsv # convert it to UTF8, creating patrons.tsv.utf8
49
50 =item mig clean patrons.tsv # cleans the file, creating patrons.tsv.utf8.clean
51
52 =item mig link patrons.tsv actor_usr # makes the soon-to-be staging table a child of m_foo.actor_usr
53
54 =item mig convert patrons.tsv # creates a .sql file for staging the data
55
56 =item mig stage patrons.tsv # load said .sql file
57
58 =item mig mapper patrons.tsv # interactive tool for analyzing/mapping the staging table
59
60 =item mig analysis patrons.tsv # writes a summary .tsv file of mapped/flagged fields from the staging table
61
62 =item mig map patrons.tsv # apply configured mappings
63
64 =item mig write_prod patrons.tsv # creates a .sql file for pushing the staging data into production
65
66 =back
67
68 =head1 COMMANDS
69
70 =over 15
71
72 =item B<help> [command]
73
74 Display this very same documentation, or specific documentation for one of the
75 commands listed here.
76
77 =item B<env> <create|use|show> <schema>
78
79 Invokes B<mig-env> with the same arguments.  I<mig-env> can set important
80 environment variables and spawn a shell with those variables, and it also does
81 some directory creation and symlinking.
82
83 =item B<init>
84
85 Create or re-create the PostgreSQL tracking table for the schema specified by
86 the MIGSCHEMA environment variable.  If needed, create the migration schema
87 itself and run migration_tools.init() and build() if the migration_tools schema
88 exists.
89
90 =item B<status> [file] [...]
91
92 Show status information for either the specified files or all tracked files if
93 no argument is given.
94
95 =item B<add> [--no-headers|--headers] <file> [file|--no-headers|--headers] [...]
96
97 Add the specified files to the migration tracker.  Until --no-headers is
98 specified, the tracker will assume the files have headers.
99
100 You can do crazy stuff like
101 B<mig add file1 --no-headers file2 file3 --headers file4>
102
103 =item B<remove> <file> [file] [...]
104
105 Remove the specified files from the migration tracker.
106
107 =item B<iconv> <file> [other arguments...]
108
109 Attempts to invoke B<iconv> on the specified tracked file, placing the output in
110 <file>.utf8
111
112 If given no other arguments, the invocation will lool like
113
114 =over 5
115
116 iconv -f ISO-8859-1 -t UTF-8 -o <file>.utf8 <file>
117
118 =back
119
120 otherwise, the arguments will be passed through like so
121
122 =over 5
123
124 iconv [other arguments...] -o <file>.utf8 <file>
125
126 =back
127
128 =item B<skip-iconv> <file>
129
130 If this is used instead of B<iconv>, then B<mig> will look for an existing
131 <file>.utf8 and use it instead of attempting to create one.
132
133 =item B<clean> <file> [other arguments...]
134
135 Attempts to invoke B<clean_csv> on the iconv-converted specified tracked file,
136 placing the output in <file>.utf8.clean
137
138 If given no other arguments, the invocation will lool like
139
140 =over 5
141
142 clean_csv --config scripts/clean.conf --fix --apply <--create-headers> <file>
143
144 =back
145
146 otherwise, the arguments will be passed through like so
147
148 =over 5
149
150 clean_csv [other arguments...] <file>
151
152 =back
153
154 =item B<skip-clean> <file>
155
156 If this is used instead of B<clean>, then B<mig> will look for an existing
157 <file>.utf8.clean and use it instead of attempting to create one.
158
159 =item B<link> <file> <parent table>
160
161 Associate the specified file with a parent table within the migration schema.
162
163 Linking multiple files to the same parent table is not allowed currently.
164
165 =item B<unlink> <file>
166
167 Removes any association between the specified file and a parent table within
168 the migration schema.
169
170 =item B<convert> <file>
171
172 Attempts to invoke B<csv2sql> on the .utf8.clean version of the specified
173 tracked file, creating either [file].utf8.clean.stage.sql or
174 <parent table>_stage.sql depending on whether the file has been linked to a
175 parent table within the migration schema or not.
176
177 If given no other arguments, the invocation will lool like
178
179 =over 5
180
181 csv2sql --config scripts/clean.conf --add-x-migrate --schema <MIGSCHEMA> [--parent <PARENT TABLE>] -o <[<file>.utf8.clean.stage.sql]|[parent_table_stage.sql]> <FILE>.utf8.clean
182
183 =back
184
185 otherwise, the arguments will be passed through like so
186
187 =over 5
188
189 csv2sql [other arguments...] -o <[<file>.utf8.clean.stage.sql]|[parent_table_stage.sql]> <file>.utf8.clean
190
191 =back
192
193 =item B<stage> <file> [other arguments...]
194
195 Load the SQL-converted version of the specified file into the migration schema.
196
197 Extra arguments are passed to the underlying call to psql
198
199 =item B<mapper> <file>
200
201 Interactive session for analyzing, flagging, and mapping legacy field data to
202 Evergreen fields.
203
204 Upon exit, generate either [file].clean.map.sql or <parent table>_map.sql. The
205 SQL generated will be UPDATE's for setting the Evergreen-specific columns for a
206 given file's staging tables, and TRUNCATE's and INSERT's for auxilary tables.
207 The files will have \include hooks for pulling in additional mapping files
208 (for example, end-user mappings for circ modifiers, etc.)
209
210 =item B<analysis> [file]
211
212 Writes a MIGSCHEMA.tsv file containing a break-down of mapped and flagged
213 fields from the specified file, or all staged files if no file is specified.
214
215 The main goal of the tsv file is to present end-user mappable data for circ
216 modifiers, shelving locations, patron profiles, etc.  We use spreadsheets for
217 this now but may move to a dedicated UI in the future.
218
219 =item B<map> [file]
220
221 Applies the mapping sql to the migration schema for the specified mapped file,
222 or for all mapped files if no file is specified.
223
224 =item B<write_prod> [file]
225
226 Generates <parent table>_prod.sql for the specified linked and mapped file, or
227 all such files if no file is specified.
228
229 =item B<sql> [arguments...]
230
231 A wrapper around the psql command.  At some point the plan is to shove mig-tracked variables into psql sessions.
232
233 =back
234
235 =cut
236
237 ###############################################################################
238
239 use strict;
240 use Switch;
241 use Env qw(
242     HOME PGHOST PGPORT PGUSER PGDATABASE MIGSCHEMA
243     MIGBASEWORKDIR MIGBASEGITDIR MIGGITDIR MIGWORKDIR
244 );
245 use Pod::Usage;
246 use FindBin;
247 my $mig_bin = "$FindBin::Bin/mig-bin/";
248 use lib "$FindBin::Bin/mig-bin";
249 use Mig;
250
251 pod2usage(-verbose => 2) if ! $ARGV[0];
252 switch($ARGV[0]) {
253     case "help" {
254         if (defined $ARGV[1]) {
255             my $cmd = $mig_bin . "mig-$ARGV[1]";
256             if (-e $cmd) {
257                 system( $mig_bin . "mig-$ARGV[1]", '--help' );
258             } else {
259                 pod2usage(-verbose => 2);
260             }
261         } else {
262             pod2usage(-verbose => 2);
263         }
264     }
265     case "env" {
266         standard_invocation(@ARGV);
267     }
268     case "init" {
269         Mig::die_if_no_env_migschema();
270         standard_invocation(@ARGV);
271     }
272     case "status" {
273         Mig::die_if_no_env_migschema();
274         standard_invocation(@ARGV);
275     }
276     case "add" {
277         Mig::die_if_no_env_migschema();
278         standard_invocation(@ARGV);
279     }
280     case "remove" {
281         Mig::die_if_no_env_migschema();
282         standard_invocation(@ARGV);
283     }
284     case "iconv" {
285         Mig::die_if_no_env_migschema();
286         standard_invocation(@ARGV);
287     }
288     case "skip-iconv" {
289         Mig::die_if_no_env_migschema();
290         standard_invocation(@ARGV);
291     }
292     case "clean" {
293         Mig::die_if_no_env_migschema();
294         standard_invocation(@ARGV);
295     }
296     case "skip-clean" {
297         Mig::die_if_no_env_migschema();
298         standard_invocation(@ARGV);
299     }
300     case "link" {
301         Mig::die_if_no_env_migschema();
302         standard_invocation(@ARGV);
303     }
304     case "unlink" {
305         Mig::die_if_no_env_migschema();
306         standard_invocation(@ARGV);
307     }
308     case "convert" {
309         Mig::die_if_no_env_migschema();
310         standard_invocation(@ARGV);
311     }
312     case "stage" {
313         Mig::die_if_no_env_migschema();
314         standard_invocation(@ARGV);
315     }
316     case "mapper" {
317         Mig::die_if_no_env_migschema();
318         standard_invocation(@ARGV);
319     }
320     case "quicksheet" {
321         Mig::die_if_no_env_migschema();
322         standard_invocation(@ARGV);
323     }
324     case "sql" {
325         Mig::die_if_no_env_migschema();
326         standard_invocation(@ARGV);
327     }
328     case "map" {
329         Mig::die_if_no_env_migschema();
330     }
331     case "load" {
332         Mig::die_if_no_env_migschema();
333     }
334     case "wdir" {
335         print "$MIGWORKDIR\n";
336     }
337     case "gdir" {
338         print "$MIGBASEGITDIR\n";
339     }
340     case "sdir" {
341         print "$MIGGITDIR\n";
342     }
343     else {
344         pod2usage(1);
345     }
346 }
347
348 sub standard_invocation {
349     my $cmd = shift;
350     system( $mig_bin . "mig-$cmd", @_ );
351 }
352
353