OSDN Git Service

Upgrade to 4.2.0-beta2-test
[stew/Stew4.git] / MANUAL.md
1 % Stew4 User Manual
2 %
3 % version 4.2
4
5
6 ## What Is Stew ?
7
8 Stew is the database (SQL) tool with JDBC.
9
10 For details, see "README.md".
11
12
13 ## PRECAUTIONS
14
15 ### Password Management
16
17 By defaults, passwords are not encrypted.
18 Setting "Encryption" in the connector will encrypt the password.
19
20 For details, see [How To Use - Configuration Of "Connector"](#configuration-of-connector).
21
22
23 ### Rollback Does Not Work When The Connection Is Disconnecting
24
25 By defaults, Rollback does not work automatically on disconnect.
26 You have to care that some of DBMSs commit on disconnect.
27
28 Setting "Auto Rollback" in the connector will rollback automatically on disconnect.
29
30 For details, see [How To Use - Configuration Of "Connector"](#configuration-of-connector).
31
32
33 ### Other
34
35 For more information, see the project site.
36
37 - <http://stew.sourceforge.jp/>
38 - <http://argius.github.io/Stew4/>
39
40
41 ## Installation
42
43 Just extract the package archive file.
44
45
46 ## Running App
47
48 If you want to use GUI mode, execute the following command:
49
50     > java -jar stew.jar --gui
51
52 If you want to use CUI mode, execute the following command:
53
54     > java -jar stew.jar --cui
55
56 At first time, a system directory ".stew" created. It is used by some configurations.
57 By default, ".stew" creates at the current directory.
58
59
60 ## Uninstallation
61
62 Remove all of installed files and ".stew" directory.
63
64
65 ----------------------------------------------------------------------------------------------------
66
67 ## Usage
68
69 To access database with Stew, you need DBMS that supports JDBC and its JDBC driver.
70 For details, see the manual of DBMS.
71
72
73 ### Configuration Of "Connector"
74
75 In Stew, an asset of JDBC Connection called it "Connector".
76
77 In CUI mode, to start edit tool, specifies --edit option.
78
79     # command line
80     $ stew --edit
81
82     # running stew
83     > --edit
84
85 In GUI mode, executes "Edit Connectors" to start edit dialog.
86
87
88 Connector has the following properties:
89
90 Connector ID
91 :   ID for connector command. Allows only ASCII letters (A-Za-z0-9).
92
93 Connector Name
94 :   The name to display at Prompt.
95
96 Classpath
97 :   Specifies classpath of JDBC driver. This form is same with -CLASSPATH option.
98
99 Driver
100 :   Specifies the driver class that implements java.sql.Driver.
101     (In GUI mode, you can use the "search Driver" button.)
102
103 URL to connect
104 :   Specifies JDBC URL (same as url at DriverManager.getConnection(url)).
105
106 User
107 :   Specifies the user ID.
108
109 Password
110 :   Specifies the password of its user ID.
111
112 Encryption
113 :   Specifies the type to save password into file.
114     See the next section.
115
116 Readonly
117 :   Is set to READONLY the connection, so that you can not run the commands that update.
118  (., Which according to ReadOnly the command side)
119
120 Auto Rollback
121 :   If it was set, the transaction will be rollbacked automatically when disconnect.
122
123
124
125 ### About Password Management
126
127 How to save the password, you can select the encryption process.
128
129 PlainTextPassword
130 :   Saves as plain text. (default)
131
132 PbePassword
133 :   You can store your password by using the PBE encryption.
134
135
136 ### Anonymous Connector
137 ### Interactive Mode
138 ### Non-interactive Mode
139 ### Alias
140 ## Commands
141 ### connect - Connects to database (built-in)
142
143     > connect <connector-id>
144     > -c <connector-id>
145
146 This command connects to database with prepared Connector.
147
148 In interactive mode, connection is kept until disconnect.
149 If already connected, disconnect it first, then connect.
150
151
152 ### disconnect - Disconnects from database (built-in)
153
154     > disconnect
155     > -d
156
157 This command disconnects from database.
158
159 If auto-rollback was available, try to rollback before disconnecting.
160
161
162 ### commit - Commits current transaction (built-in)
163
164 This command commits current transaction.
165
166 ** caution: Commit cannot cancel. Please use carefully. **
167
168
169 ### rollback - Rollbacks current transaction (built-in)
170
171 This command rollbacks a current transaction.
172
173
174 ### -e - Evaluates multiple commands (built-in)
175
176     > -e <command> -e <command> ...
177
178 For example, you can execute two export command continuously,
179  or can execute as batch in non-interactive mode.
180
181
182 ### -f - Executes file content as command (built-in)
183
184     > -f <file>
185
186 ...
187
188
189 ### -s - Executes file content as script (built-in) \<improved feature in version 4.1\>
190
191     > -s . | <SCRIPT FILE> | <SCRIPT-NAME> <SCRIPT-CODE>
192
193  1. If the first argument is ".", the Script Context is reset.
194  2. If the first argument is a filename with extension, the script language is identified by the extension, and the file is run as the script language's script.
195  3. Otherwise, the first argument is recognized as the name of a script language, and the rest of arguments are executed as the script language's script.
196
197 (Only the built-in JavaScript by file is supported in version 4.0.)
198
199 To use script languages except the built-in script language (JavaScript), it requires each script engine of script languages such as jruby, jython and groovy.
200
201 The Script Context keeps global scope bindings, and following scripts can reuse the bindings.
202 If you want to reset Script Context, input " -s . " above.
203
204
205 The following variables will be available in the script (global scope):
206
207  * the reference of current connection: connection, conn
208  * the reference of Parameter: parameter, p
209  * the reference of OutputProcessor: outputProcessor, op
210
211
212 ### cd - Changes current directory (built-in)
213
214     > cd <directory>
215
216 Changes current directory to specified one.
217 (This current directory is not OS's, but internal Stew.)
218
219
220 ### @ - Displays directories (built-in)
221
222     > @
223
224 Displays the paths of current directory and system directory.
225
226
227 ### ? - Displays System Properties (built-in)
228
229     > ? [<property-name> [<property-name-2> ... <property-name-n>]]
230
231 Display System Properties. (System.getProperty)
232
233 By defauts, it displays JRE, OS and Locale.
234
235     > ?
236     JRE : ...
237     OS : ...
238     Locale : en_UK
239     > ? java.version user.timezone zzz
240     java.version=[1.6.0_##]
241     user.timezone=[Europe/London]
242     zzz=undefined
243
244
245 ### alias - Registers alias (built-in)
246
247     > alias [<name> [<command>]]
248
249 Registers the alias of command.
250 When called with an argument, display the alias and its command.
251 When called without arguments, display all aliases.
252
253 Before registering or displaying, refreshes cached info in memory.
254 If modified aliases in another process, includes you directly edit the config file,
255 run this command.
256
257 (implementation details:
258  for the infinite loop suppression of circular references,
259  the depth of the expansion up to 100.)
260
261     > alias
262     No aliases.
263     > alias search select * from
264     > alias count select count(*) from
265     > alias search
266     alias search=[select * from]
267     > search table1
268     >> select * from table1
269     (diplays the results of "select * from table1")
270     >
271
272
273 ### unalias - Removes alias (built-in)
274
275     > unalias <alias>
276
277 If the specified alias does not exist, does nothing.
278 Whether the target exists or not, refreshes cached info in memory.
279
280
281 ### exit - Exits application (built-in)
282
283     > exit
284
285 This command exits Stew without confirmation.
286
287 All connections will be disconnected automatically.
288 Rollback will do only the connector set auto-rollback option.
289 For automatic rollback, see [Usage - Configuration Of "Connector"](#configuration-of-connector).
290
291
292 ### load - Executes file content as SQL
293
294     > load [<SQL-file> | <data-file> <table-name> [ HEADER ]]
295
296 This command executes the SQL read from specified file.
297
298 When If a parameter is specified, executes file content as SQL,
299 otherwise, two or more parameters, imports the file as data file.
300 The file format is automatically selected by file extension.
301
302  * .csv : CSV format
303  * .xml : XML format (definition: src/net/argius/stew/io/stew-table.dtd)
304  * otherwise: TSV format
305
306 (implementation detail: this is basically same as import command,
307                         executes as not batch but executes by record)
308
309
310 ### import - Imports from file
311
312     import <data-file> <table-name> [ HEADER ]
313
314 This command imports from file as data file.
315 The file format is automatically selected by file extension.
316
317  * .csv : CSV format
318  * .xml : XML format (definition: src/net/argius/stew/io/stew-table.dtd)
319  * otherwise: TSV format
320
321 (implementation detail: this is basically same as load command,
322                         but uses Statement#addBatch.)
323
324
325 ### export - Exports to file
326
327 This command exports result of command to the specified file.
328 The file format is automatically selected by file extension.
329
330  * .htm,html : HTML format
331  * .csv : CSV format
332  * .xml : XML format (definition: src/net/argius/stew/io/stew-table.dtd)
333  * others: TSV format
334
335
336 ### time - Measures time to execute SQL
337
338     > time [<count>] <SQL>
339
340 This command executes specified SQL and measures its execution time.
341
342 If specified count, executes SQL by count continuously
343  and summaries "Total", "Ave(average)", "Max" and "Min".
344 Otherwise, executes once and measure its execution time.
345
346     > time select * from EMPLOYEE
347     execution time: 0.093 seconds
348     > time 100 select * from EMPLOYEE
349     Total: 0.484 seconds
350       Ave: 0.005 seconds
351       Max: 0.094 seconds
352       Min: 0.000 seconds
353     >
354
355
356 ### find - Finds table names
357
358     > find <table-name-pattern> [<table-type-pattern> [<schema-pattern> [<catalog-pattern> [ FULL ]]]]
359
360 This command displays list of tables allowed to show.
361 The parameter including "pattern" in its name can be specified wildcard (#,?).
362
363
364 ### report - Reports database info
365
366     > report - | <table-name> [ FULL | PK | INDEX ]
367
368 This command displays the info about current connection and connecting database.
369
370 If specifies - (hyphen), displays the name and version of database and JDBC driver,
371  user and JDBC address.
372
373 If only specifies table name, displays the column info about specified table.
374
375 If specifies table name and option,
376 displays the primary key or index info about specified table.
377
378
379 ### download - Downloads a column as file
380
381     > download <root-dir> SELECT <data-column> [, file-path...] FROM ...
382
383 This command downloads a column data by rows and saves to file.
384
385 For any data type.
386 It is useful for downloading large text data or large objects (BLOB, CLOB) all at once.
387
388 In order to be able to download multiple files,
389 generates file name using column data.
390
391 The file name will be generated by concatenate second column and after as string.
392 This supporses to specify primary keys and file extension.
393
394     > download emp select FULL_NAME, JOB_COUNTRY, '/', EMP_NO, '.txt' from EMPLOYEE
395     The dir[./emp/USA] was created.
396     Downloaded. (size=14bytes, file=./emp/USA/2.txt)
397     Downloaded. (size=12bytes, file=./emp/USA/4.txt)
398      .
399      .
400      .
401     Downloaded. (size=12bytes, file=./emp/USA/24.txt)
402     The dir[./emp/England] was created.
403     Downloaded. (size=11bytes, file=./emp/England/28.txt)
404      .
405      .
406      .
407     Downloaded. (size=18bytes, file=./emp/USA/145.txt)
408     Selected 42 records.
409
410 When data exist a record, specified &lt;data-column&gt;,
411 saves file to &lt;root-dir&gt; as file name.
412
413 Saving file already exists or no permission to write file,
414 the process will abort immediately.
415
416
417 ### upload - Uploads file data to a column
418
419     > upload <file> <SQL(UPDATE|INSERT)>
420
421 This command registers a data file to the column that specified by place-holder.
422
423
424 ### wait - Waits for specified interval
425
426     > wait seconds
427
428 This command waits for the interval that specified number (mixed decimal) of seconds.
429 It may be useful for executing multiple commands.
430
431
432
433 ## The GUI Mode
434
435 ### Common Behaviors
436
437 Standard commands, "undo", "redo", "cut", "copy", "paste", and "select all", can use in all text components via context menu or shortcut key.
438
439
440 ### Main Window
441
442 A window has "Input/Output Area", "Result Set Table", "Database Info Tree", "Main Menu", "Status Bar" and "Find Pane".
443 By default, the database info tree, the status bar and the find pane" are hidden.
444
445
446 ### Input/Output Area
447
448 The I/O area is similar to CUI interface.
449
450 ... When cursor is at the end of textarea, executes command which is string from prompt to the end of textarea.
451 ... Otherwise, move cursor to the end of textarea.
452 ... The part before prompt can't edit.
453
454
455 ... Context menus for this component has the standard commands.
456
457
458 ### Result Set Table
459
460 The result set table displays command results, usually query results from database.
461
462 The row header (the leftmost of the table) displays the row number.
463 ... display "+" sign instead of the row number in the row header.
464
465 Automatic column width adjustment ...
466
467
468 The context menu for this component are listed below:
469
470
471 Sorts clicked column
472 :   This command sorts clicked column, not a selected one.
473     The same column is sorted continuously, ... reverse.
474
475 Copy (Ctrl-C)
476 :   This command copies selected cell values as text into the clipboard.
477
478 Copy With Escape (Ctrl+Shift-C)
479 :   This command copies selected cell values as quoted strings into the clipboard.
480
481 Paste (Ctrl-V)
482 :   This command pastes values into selected cells from the clipboard.
483     Type conversion from the text to column types of the cells depends on each JDBC driver implementation.
484
485 Select All (Ctrl-A)
486 :   This command selects all cells in the table.
487
488 Clear Selected Cell Value
489 :   This command clears selected cell values (actually sets NULL).
490
491 Set Current Time Value
492 :   This command sets current time (Timestamp) into selected cells.
493
494 Copy Column Names
495 :   This command copies the table header as text into the clipboard.
496
497 Find Column Name
498 :   This command shows the find pane and sets find target ...
499
500 Add New (Empty) Row
501 :   This command adds a new empty row into the table.
502
503 Insert From Clipboard
504 :   This command ... imports data from the clipboard and inserts the data into the linking table.
505
506 Duplicate Rows
507 :   This command adds duplicate rows ... selected cells.
508
509 Link Rows Into Database
510 :   This command make unlink  ...
511
512 Delete Rows
513 :   This command deletes selected rows.
514     The deleted rows are also deleted from database.
515
516
517
518 ### Database Info Tree
519
520 The database info tree is a tree view of hierarchical structure, which consists
521  catalogs, schemas, tables, table type and columns as a tree.
522 Not connected: blank ...
523 just connected: connector as a root node and sub nodes ...
524 Each node expands ...
525
526
527 An "Auto-expansion" is a function to automatically expands nodes in the database info tree when connecting a database.
528 If you use it, create a TSV file named "autoexpansion.tsv" in the system directory (.stew) and write node name lists as TSV into this file.
529
530
531 The context menu for this component are listed below:
532
533
534 Copy
535 :   This command copies displayed strings of selected nodes as text into the clipboard.
536
537 Copy Simple Name
538 :   This command copies the simple name of selected nodes as text into the clipboard.
539
540 Copy Full Name
541 :   This command copies the full qualified name of selected nodes as text into the clipboard.
542
543 Refresh
544 :   This command ...
545
546 Generate WHERE Phrase
547 :   This command generates a WHERE phrase consisting selected tables and columns ...
548     selected same name, generate ...
549
550 Generate SELECT Statement (with WHERE)
551 :   This command generates a SELECT statement with "WHERE" keyword.
552
553 Generate UPDATE Statement (with WHERE)
554 :   This command ...
555
556 Generate INSERT Statement
557 :   This command ...
558
559 Jump To Column By Name
560 :   This command ... the name of selected node. Jump to the column which has the same name in current result table if found it.
561     Double-clicking the node is the same as this command.
562
563 Toggle Show Column Number
564 :   This command provides the toggle between showing and hiding the column number of all columns nodes.
565
566
567 ### Main Menu
568
569 See Menus ...
570
571
572 ### Status Bar
573
574 ... Display last command and its execution time.
575 ...This time is not query but command.
576
577
578 ### Saving Configuration
579
580 ...
581
582
583 ### Key Binding
584
585 ...
586 It is not able to change key bind after opening new window.
587 ... For the keywords, see https://github.com/argius/Stew4/blob/master/src/net/argius/stew/ui/window/Menu.u8p
588
589
590 ## Menus in the GUI Mode
591
592 ### File - New Window (N) Ctrl-N
593
594 This command opens a new window.
595 Current connections are independent of each window.
596
597
598 ### File - Close Window (C) Ctrl-W
599
600 This command closes current window.
601 If connected, show confirm dialog.
602
603 If current window is only a window, processes as Quit(Q).
604
605
606 ### File - Quit (Q) Ctrl-Q
607
608 This command quits this application.
609 When executed, shows confirm dialog. Click "Yes" to quit.
610
611
612 ### Edit - Cut (T) Ctrl-X
613
614 This command cuts the selection to the clipboard.
615
616
617 ### Edit - Copy (C) Ctrl-C
618
619 This command copies the selection to the clipboard.
620
621
622 ### Edit - Paste (P) Ctrl-V
623
624 This command pastes the selection to the clipboard.
625
626
627 ### Edit - Select All (A) Ctrl-A
628
629 This command selects all text or all elements.
630
631
632 ### Edit - Find (F) Ctrl-F
633
634 This command finds out a specific string from selected component.
635
636 ...
637
638
639 ### Edit - Toggle focus (G) Ctrl-G \<improved feature in version 4.2\>
640
641 This command toggles focus between the database info tree, the the result set table and the input/output area in a current window.
642
643 ### Edit - Clear Message (M)
644
645 This command clears input/output area in a current window.
646
647
648 ### View - Show Status Bar (S)
649
650 This command toggles the visibility of status bar in a current window.
651
652
653 ### View - Show Column Number (C)
654
655 This command toggles the visibility of column number in the result set table of a current window.
656
657
658 ### View - Show Info Tree (I)
659
660 This command toggles the visibility of database info tree in a current window.
661
662
663 ### View - Always On Top (T)
664
665 This command toggles the state that always stays on top of a current window.
666
667
668 ### View - Refresh (R) F5
669
670 This command ...
671
672
673 ### View - Widen Column Width (W) Ctrl-.(period)
674
675 This command widens all column widths in the result set table of a current window.
676
677
678 ### View - Narrow Column Width (N) Ctrl-,(comma)
679
680 This command narrows all column widths in the result set table of a current window.
681
682
683 ### View - Adjust Column Width (A) Ctrl-/(slash)
684
685 This command adjusts all column widths in the result set table of a current window.
686 For about adjust mode, see the next item.
687
688
689 ### View - Auto Adjust Mode (M)
690
691 This command selects auto-adjusting mode to use when shows result.
692
693 There are following modes:
694
695  * None(N): does nothing.
696  * Header(H): adjusts column width based on each header string.
697  * Value(V): adjusts based on the longest string in column values.
698  * Header And Value(A): adjusts based on the longest string in column values and column header string.
699
700
701 ### Command - Execute (X) Ctrl-M
702
703 This command executes command.
704 This is same as pressing enter key in the end of the I/O area. (... same behavior)
705
706
707 ### Command - BREAK (B) Ctrl-Pause(Break)
708
709 This command cancels executing command.
710 The process on the server is not canceled.
711
712
713 ### Command - History Back (P) Ctrl-Up
714
715 This command rotates command histories backward.
716
717
718 ### Command - History Next (N) Ctrl-Down
719
720 This command rotates command histories forward.
721
722
723 ### Command - Show All Histories(A) \<new feature in version 4.2\>
724
725 This command shows all command histories and paste a choosen commmand.
726
727
728 ### Command - Rollback (R)
729
730 This command displays confirm dialog and click "OK" to rollback.
731
732
733 ### Command - Commit (M)
734
735 This command displays confirm dialog and click "OK" to commit.
736
737
738 ### Command - Connect (C) Ctrl-E
739
740 This command shows the list of connectors.
741 Select connector name you want to connect to, and click "OK" to executes connect command.
742
743
744 ### Command - Disconnect (D) Ctrl-D
745
746 This command disconnects current connection.
747 This is the same as disconnect command.
748
749
750 ### Command - Post-Proccess (0)
751
752 This command specifies the configuration of a "Post-Proccess" mode.
753
754 The "Post-Proccess" is an action to notify that command finished.
755 When the window which command is running, is not active, "Post-Proccess" is invoked.
756
757 There are following modes:
758
759  * None(N): Does nothing.
760  * Focus(F): Focuses window.
761  * Shake(S): Shakes window.
762  * Blink(B): Blinks window.
763
764
765 ### Command - Encryption Key (K)
766
767 This command shows the dialog to input an encryption key.
768
769
770 ### Command - Edit Connectors (E)
771
772 This command shows the dialog to edit connectors.
773
774
775 ### Data - Sort (S) Alt-S
776
777 This command sorts records by selected column.
778
779
780 ### Data - Import File (I)
781
782 This command imports from file into the table of current result.
783
784
785 ### Data - Export File (E) Ctrl-Shift-S
786
787 This command exports results into file.
788
789
790 ### Help - Show Help
791
792 This command shows this help file by default browser.
793
794
795 ### Help - About Stew
796
797 This command shows version dialog about Stew.
798
799
800
801 ## Properties
802
803 You can set these system properties into java -D option or stew.properties file.
804
805
806 ### net.argius.stew.properties - Location Of Properties File
807
808 Property Value: a file path or a directory path
809
810 This property specifies the location of "stew.properties" file.
811 This properties file is used as system properties and searched in the following steps:
812
813 +If it specifies a file path, the file will be used as system properties.
814 +If it specifies a directory path, the file will be searched a "stew.properties" file in the directory.
815 +Search a file in the classpath.
816 +Search a file in the system directory.
817
818 The first file found is used.
819 If a file is not found, ... (ignore it).
820
821
822 ### net.argius.stew.directory - Working Directory
823
824 Property Value: a directory path (default: current directory)
825
826 This property specifies the current directory as a internal state at the start, but it is not a platform one.
827
828
829 ### net.argius.stew.query.timeout - Query Timeout
830
831 Property Value: integer seconds (default: 0)
832
833 This property specifies the query timeout which is used in commands.
834
835 If it is under 0, the property was not set.
836
837 (implementation detail: for java.sql.Statement#setQueryTimeout)
838
839
840 ### net.argius.stew.rowcount.limit - Limit Of Display Result Row Count
841
842 Property Value: maximum number of rows (default: Integer.MAX_VALUE, about 2,147,000,000)
843
844 This property specifies the maximum number of rows which show in the result set table.
845 It is not used to output files, such as the export command.
846
847
848 ### net.argius.stew.command.Import.batch.limit - Limit Of Import Command Using Batch
849
850 Property Value: limit number of rows (default: 10000)
851
852 This property is used by the Import command.
853 It is not used to output files, such as the export command.
854
855
856 ### net.argius.stew.ui.window.resident - Regident
857
858 Property Value: integer minutes
859
860 This is an experimental feature.
861
862 The app redraws continuously at the specified interval to prevent swap-out.
863
864
865 ### Logger Configurations
866
867 Use logging.properties in this package.
868