Skip to content
This repository
Browse code

Proof and modify first few tutorial sections.

While at it, remove the period from "No changes deployed" when running
`verify`, so that it's the same as for `status`.
  • Loading branch information...
commit bb9a7bf11abe254771d3cff2c5dad0419b73f9dd 1 parent efeb29d
David E. Wheeler authored
2  lib/App/Sqitch/Engine.pm
@@ -266,7 +266,7 @@ sub verify {
266 266
     if (!@changes) {
267 267
         # Probably expected, but exit 1 anyway.
268 268
         my $msg = $plan->count
269  
-            ? __ 'No changes deployed.'
  269
+            ? __ 'No changes deployed'
270 270
             : __ 'Nothing to verify (no planned or deployed changes)';
271 271
         hurl {
272 272
             ident   => 'verify',
100  lib/sqitchtutorial.pod
Source Rendered
@@ -78,7 +78,7 @@ settings. But it will also read F<~/.sqitch/sqitch.conf> for global settings.
78 78
 Since PostgreSQL's C<psql> client is not in the path on my system, let's go
79 79
 ahead an tell it globally where to find the client:
80 80
 
81  
-  > sqitch config --user core.pg.client /usr/local/pgsql/bin/psql
  81
+  > sqitch config --user core.pg.client /opt/local/pgsql/bin/psql
82 82
 
83 83
 And let's also tell it who we are, since this data will be used in all
84 84
 of our projects:
@@ -89,7 +89,7 @@ of our projects:
89 89
 Have a look at F<~/.sqitch/sqitch.conf> and you'll see this:
90 90
 
91 91
   [core "pg"]
92  
-  	client = /usr/local/pgsql/bin/psql
  92
+  	client = /opt/local/pgsql/bin/psql
93 93
   [user]
94 94
   	name = Marge N. O’Vera
95 95
   	email = marge@example.com
@@ -104,10 +104,10 @@ Back to the repository. Have a look at the plan file, F<sqitch.plan>:
104 104
   %uri=https://github.com/theory/sqitch-intro/
105 105
   
106 106
 
107  
-Note that it has picked up on the name and URI of the app we're building. This
108  
-data will be used in the future to allow for cross-project dependency
109  
-specification. The C<%syntax-version> pragma is always set by Sqitch, so that
110  
-it always knows how to parse the plan, even if the format changes in the future.
  107
+Note that it has picked up on the name and URI of the app we're building.
  108
+Sqitch uses this data to manage cross-project dependencies. The
  109
+C<%syntax-version> pragma is always set by Sqitch, so that it always knows how
  110
+to parse the plan, even if the format changes in the future.
111 111
 
112 112
 Let's commit these changes and start creating the database changes.
113 113
 
@@ -136,7 +136,7 @@ F<deploy/appschema.sql>:
136 136
 
137 137
   CREATE SCHEMA flipr;
138 138
 
139  
-And the C<revert> script's job is to precisely revert the change to the deploy
  139
+The C<revert> script's job is to precisely revert the change to the deploy
140 140
 script, so we add this to F<revert/appschema.sql>:
141 141
 
142 142
   DROP SCHEMA flipr;
@@ -164,12 +164,14 @@ see the schema:
164 164
   -------+-------
165 165
    flipr | marge
166 166
 
  167
+=head2 Trust, But Verify
  168
+
167 169
 But that's too much work. do you really want to do something like that after
168 170
 every deploy?
169 171
 
170 172
 Here's where the C<verify> script comes in. Its job is to test that the deploy
171 173
 did was it was supposed to. It should do so without regard to any data that
172  
-might be in the database, and should throw an error if the deloy was not
  174
+might be in the database, and should throw an error if the deploy was not
173 175
 successful. In PostgreSQL, the simplest way to do so for non-queryable objects
174 176
 such as schemas is to take advantage the
175 177
 L<access privilege inquiry functions|http://www.postgresql.org/docs/current/static/functions-info.html#FUNCTIONS-INFO-ACCESS-TABLE>.
@@ -180,7 +182,15 @@ F<verify/appschema.sql>:
180 182
 
181 183
   SELECT pg_catalog.has_schema_privilege('flipr', 'usage');
182 184
 
183  
-We can run the C<verify> script with the C<verify> command:
  185
+Such functionality may not be available to other databases, but you can use
  186
+I<any> query that will throw an exception if the schema doesn't exist. One
  187
+handy way to do that is to divide by zero if an object doesn't exist. So for
  188
+other databases, to throw an error when the C<flipr> schema does not exist,
  189
+you could do something like this:
  190
+
  191
+  SELECT 1/COUNT(*) FROM information_schema.schemata WHERE schema_name = 'flipr';
  192
+
  193
+Either way, run the C<verify> script with the C<verify> command:
184 194
 
185 195
   > sqitch --db-name flipr_test verify
186 196
   Verifying flipr_test
@@ -191,13 +201,13 @@ Looks good! If you want to make sure that the verify script correctly dies if
191 201
 the schema doesn't exist, temporarily change the schema name in the script to
192 202
 something that doesn't exist, something like:
193 203
 
194  
-  SELECT pg_catalog.has_schema_privilege('nonexistent', 'usage');
  204
+  SELECT pg_catalog.has_schema_privilege('nonesuch', 'usage');
195 205
 
196 206
 Then C<verify> again:
197 207
 
198 208
   > sqitch --db-name flipr_test verify
199 209
   Verifying flipr_test
200  
-    * appschema .. psql:verify/appschema.sql:5: ERROR:  schema "nonexistent" does not exist
  210
+    * appschema .. psql:verify/appschema.sql:5: ERROR:  schema "nonesuch" does not exist
201 211
   # Verify script "verify/appschema.sql" failed.
202 212
   not ok
203 213
   
@@ -207,8 +217,35 @@ Then C<verify> again:
207 217
   Errors:  1
208 218
   Verify failed
209 219
 
210  
-It's even nice enough to tell us what the problem is. Don't forget to change
211  
-it back before continuing!
  220
+It's even nice enough to tell us what the problem is. Or, for the
  221
+divide-by-zero example, change the schema name:
  222
+
  223
+  SELECT 1/COUNT(*) FROM information_schema.schemata WHERE schema_name = 'nonesuch';
  224
+
  225
+Then the verify will look something like:
  226
+
  227
+  > sqitch --db-name flipr_test verify
  228
+  Verifying flipr_test
  229
+    * appschema .. psql:verify/appschema.sql:5: ERROR:  division by zero
  230
+  # Verify script "verify/appschema.sql" failed.
  231
+  not ok
  232
+  Undeployed changes:
  233
+    * users
  234
+    * insert_user
  235
+    * change_pass
  236
+
  237
+  Verify Summary Report
  238
+  ---------------------
  239
+  Changes: 1
  240
+  Errors:  1
  241
+  Verify failed
  242
+
  243
+Less useful error output, but enough to alert us that something has gone
  244
+wrong.
  245
+
  246
+Don't forget to change the schema name back before continuing!
  247
+
  248
+=head2 Status, Revert, Log, Repeat
212 249
 
213 250
 For purely informational purposes, we can always see how a deployment was
214 251
 recorded via the C<status> command, which reads the metadata tables from the
@@ -232,9 +269,9 @@ Let's make sure that we can revert the change:
232 269
 
233 270
 The C<revert> command first prompts to make sure that we really do want to
234 271
 revert. This is to prevent unnecessary accidents. You can pass the C<-y>
235  
-option to disable the prompt. Also, notice the C<-> in the output, which
236  
-reinforces that the change is being removed from the database. And now the
237  
-schema should be gone:
  272
+option to disable the prompt. Also, notice the C<-> before the change name in
  273
+the output, which reinforces that the change is being removed from the
  274
+database. And now the schema should be gone:
238 275
 
239 276
   > psql -d flipr_test -c '\dn flipr'
240 277
               List of roles
@@ -252,7 +289,7 @@ Of course, since nothing is deployed, the C<verify> command has nothing to
252 289
 verify:
253 290
 
254 291
   > sqitch -d flipr_test verify
255  
-  # On database flipr_test
  292
+  # Verifying flipr_test
256 293
   No changes deployed
257 294
 
258 295
 However, we still have a record that the change happened, visible via the
@@ -336,7 +373,7 @@ in, e.g.:
336 373
   Nothing to deploy (up-to-date)
337 374
 
338 375
 Yay, that allows things to be a little more concise. Let's also make sure that
339  
-changes are verified after dploying them:
  376
+changes are verified after deploying them:
340 377
 
341 378
   > sqitch config --bool deploy.verify true
342 379
   > sqitch config --bool rebase.verify true
@@ -384,8 +421,8 @@ this:
384 421
 
385 422
 A few things to notice here. On the second line, the dependence on the
386 423
 C<appschema> change has been listed. This doesn't do anything, but the default
387  
-templates lists it here for your reference while editing the file. Useful,
388  
-right?
  424
+C<deploy> template lists it here for your reference while editing the file.
  425
+Useful, right?
389 426
 
390 427
 Notice that all of the SQL code is wrapped in a transaction. This is handy for
391 428
 PostgreSQL deployments, because PostgreSQL DDLs are transactional. The upshot
@@ -415,7 +452,7 @@ Couldn't be much simpler, right? Let's deploy this bad boy:
415 452
     + users .. ok
416 453
 
417 454
 We know, since verification is enabled, that the table must have been created.
418  
-But for the purposes of visilibity, let's have a quick look:
  455
+But for the purposes of visibility, let's have a quick look:
419 456
 
420 457
   > psql -d flipr_test -c '\d flipr.users'
421 458
                         Table "flipr.users"
@@ -427,7 +464,7 @@ But for the purposes of visilibity, let's have a quick look:
427 464
   Indexes:
428 465
       "users_pkey" PRIMARY KEY, btree (nickname)
429 466
 
430  
-We can also verify all currenty deployed changes with the C<verify> command:
  467
+We can also verify all currently deployed changes with the C<verify> command:
431 468
 
432 469
   > sqitch verify
433 470
   Verifying flipr_test
@@ -449,7 +486,7 @@ Now have a look at the status:
449 486
 
450 487
 Success! Let's make sure we can revert the change, as well:
451 488
 
452  
-  > sqitch revert -y --to @HEAD^
  489
+  > sqitch revert --to @HEAD^ -y
453 490
   Reverting changes to appschema from flipr_test
454 491
     - users .. ok
455 492
 
@@ -490,9 +527,9 @@ As does the C<verify> command:
490 527
     * users
491 528
   Verify successful
492 529
 
493  
-Note that the verify is succesful, because all currently-deployed chagnes are
494  
-verfired. The list of undeployed changes is just a reminder about the current
495  
-state.
  530
+Note that the verify is successful, because all currently-deployed changes are
  531
+verified. The list of undeployed changes (just "users" here) reminds us about
  532
+the current state.
496 533
 
497 534
 Okay, let's commit and deploy again:
498 535
 
@@ -634,7 +671,8 @@ Try em out!
634 671
     + insert_user .. ok
635 672
     + change_pass .. ok
636 673
 
637  
-Do we have the functions? Of course we do, they were verified. Still, have a look:
  674
+Do we have the functions? Of course we do, they were verified. Still, have a
  675
+look:
638 676
 
639 677
   > psql -d flipr_test -c '\df flipr.*'
640 678
                                       List of functions
@@ -694,6 +732,14 @@ the last deployed change. Looks good. Let's do the commit and re-deploy dance:
694 732
   # By:       Marge N. O’Vera <marge@example.com>
695 733
   # 
696 734
   Nothing to deploy (up-to-date)
  735
+  
  736
+  > sqitch verify
  737
+  Verifying flipr_test
  738
+    * appschema .... ok
  739
+    * users ........ ok
  740
+    * insert_user .. ok
  741
+    * change_pass .. ok
  742
+  Verify successful
697 743
 
698 744
 Great, we're fully up-to-date!
699 745
 
2  t/engine.t
@@ -2158,7 +2158,7 @@ throws_ok { $engine->verify } 'App::Sqitch::X',
2158 2158
     'Should get error for no deployed changes';
2159 2159
 is $@->ident, 'verify', 'No deployed changes ident should be "verify"';
2160 2160
 is $@->exitval, 1, 'No deployed changes exitval should be 1';
2161  
-is $@->message, __ 'No changes deployed.',
  2161
+is $@->message, __ 'No changes deployed',
2162 2162
     'No deployed changes message should be correct';
2163 2163
 is_deeply +MockOutput->get_info, [
2164 2164
     [__x 'Verifying {destination}', destination => $engine->destination],
1  xt/release/pod-spelling.t
@@ -63,3 +63,4 @@ lowercased
63 63
 unlocalized
64 64
 flipr
65 65
 change's
  66
+queryable

0 notes on commit bb9a7bf

Please sign in to comment.
Something went wrong with that request. Please try again.