OSDN Git Service

Upgrade to 4.2.0
[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 ( text 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 ### Paste Paths Into The Text Area Via DnD \<new feature in version 4.2\>
459
460 When you drag and drop from file manager into the text area, the paths of these files will be pasted to the text area.
461 It also allows plural files.
462
463
464 ### Result Set Table
465
466 The result set table displays command results, usually query results from database.
467
468 The row header (the leftmost of the table) displays the row number.
469 ... display "+" sign instead of the row number in the row header.
470
471 Automatic column width adjustment ...
472
473
474 The context menu for this component are listed below:
475
476
477 Sorts clicked column
478 :   This command sorts clicked column, not a selected one.
479     The same column is sorted continuously, ... reverse.
480
481 Copy (Ctrl-C)
482 :   This command copies selected cell values as text into the clipboard.
483
484 Copy With Escape (Ctrl+Shift-C)
485 :   This command copies selected cell values as quoted strings into the clipboard.
486
487 Paste (Ctrl-V)
488 :   This command pastes values into selected cells from the clipboard.
489     Type conversion from the text to column types of the cells depends on each JDBC driver implementation.
490
491 Select All (Ctrl-A)
492 :   This command selects all cells in the table.
493
494 Clear Selected Cell Value
495 :   This command clears selected cell values (actually sets NULL).
496
497 Set Current Time Value
498 :   This command sets current time (Timestamp) into selected cells.
499
500 Copy Column Names
501 :   This command copies the table header as text into the clipboard.
502
503 Find Column Name
504 :   This command shows the find pane and sets find target ...
505
506 Add New (Empty) Row
507 :   This command adds a new empty row into the table.
508
509 Insert From Clipboard
510 :   This command ... imports data from the clipboard and inserts the data into the linking table.
511
512 Duplicate Rows
513 :   This command adds duplicate rows ... selected cells.
514
515 Link Rows Into Database
516 :   This command make unlink  ...
517
518 Delete Rows
519 :   This command deletes selected rows.
520     The deleted rows are also deleted from database.
521
522
523
524 ### Database Info Tree
525
526 The database info tree is a tree view of hierarchical structure, which consists
527  catalogs, schemas, tables, table type and columns as a tree.
528 Not connected: blank ...
529 just connected: connector as a root node and sub nodes ...
530 Each node expands ...
531
532
533 An "Auto-expansion" is a function to automatically expands nodes in the database info tree when connecting a database.
534 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.
535
536
537 The context menu for this component are listed below:
538
539
540 Copy
541 :   This command copies displayed strings of selected nodes as text into the clipboard.
542
543 Copy Simple Name
544 :   This command copies the simple name of selected nodes as text into the clipboard.
545
546 Copy Full Name
547 :   This command copies the full qualified name of selected nodes as text into the clipboard.
548
549 Refresh
550 :   This command ...
551
552 Generate WHERE Phrase
553 :   This command generates a WHERE phrase consisting selected tables and columns ...
554     selected same name, generate ...
555
556 Generate SELECT Statement (with WHERE)
557 :   This command generates a SELECT statement with "WHERE" keyword.
558
559 Generate UPDATE Statement (with WHERE)
560 :   This command ...
561
562 Generate INSERT Statement
563 :   This command ...
564
565 Jump To Column By Name
566 :   This command ... the name of selected node. Jump to the column which has the same name in current result table if found it.
567     Double-clicking the node is the same as this command.
568
569 Toggle Show Column Number
570 :   This command provides the toggle between showing and hiding the column number of all columns nodes.
571
572
573 ### Main Menu
574
575 See Menus ...
576
577
578 ### Status Bar
579
580 ... Display last command and its execution time.
581 ...This time is not query but command.
582
583
584 ### Saving Configuration
585
586 ...
587
588
589 ### Key Binding
590
591 ...
592 It is not able to change key bind after opening new window.
593 ... For the keywords, see https://github.com/argius/Stew4/blob/master/src/net/argius/stew/ui/window/Menu.u8p
594
595
596 ## Menus in the GUI Mode
597
598 ### File - New Window (N) Ctrl-N
599
600 This command opens a new window.
601 Current connections are independent of each window.
602
603
604 ### File - Close Window (C) Ctrl-W
605
606 This command closes current window.
607 If connected, show confirm dialog.
608
609 If current window is only a window, processes as Quit(Q).
610
611
612 ### File - Quit (Q) Ctrl-Q
613
614 This command quits this application.
615 When executed, shows confirm dialog. Click "Yes" to quit.
616
617
618 ### Edit - Cut (T) Ctrl-X
619
620 This command cuts the selection to the clipboard.
621
622
623 ### Edit - Copy (C) Ctrl-C
624
625 This command copies the selection to the clipboard.
626
627
628 ### Edit - Paste (P) Ctrl-V
629
630 This command pastes the selection to the clipboard.
631
632
633 ### Edit - Select All (A) Ctrl-A
634
635 This command selects all text or all elements.
636
637
638 ### Edit - Find (F) Ctrl-F
639
640 This command finds out a specific string from selected component.
641
642 ...
643
644
645 ### Edit - Toggle focus (G) Ctrl-G \<improved feature in version 4.2\>
646
647 This command toggles focus between the database info tree, the the result set table and the input/output area in a current window.
648
649 ### Edit - Clear Message (M)
650
651 This command clears input/output area in a current window.
652
653
654 ### View - Show Status Bar (S)
655
656 This command toggles the visibility of status bar in a current window.
657
658
659 ### View - Show Column Number (C)
660
661 This command toggles the visibility of column number in the result set table of a current window.
662
663
664 ### View - Show Info Tree (I)
665
666 This command toggles the visibility of database info tree in a current window.
667
668
669 ### View - Always On Top (T)
670
671 This command toggles the state that always stays on top of a current window.
672
673
674 ### View - Refresh (R) F5
675
676 This command ...
677
678
679 ### View - Widen Column Width (W) Ctrl-.(period)
680
681 This command widens all column widths in the result set table of a current window.
682
683
684 ### View - Narrow Column Width (N) Ctrl-,(comma)
685
686 This command narrows all column widths in the result set table of a current window.
687
688
689 ### View - Adjust Column Width (A) Ctrl-/(slash)
690
691 This command adjusts all column widths in the result set table of a current window.
692 For about adjust mode, see the next item.
693
694
695 ### View - Auto Adjust Mode (M)
696
697 This command selects auto-adjusting mode to use when shows result.
698
699 There are following modes:
700
701  * None(N): does nothing.
702  * Header(H): adjusts column width based on each header string.
703  * Value(V): adjusts based on the longest string in column values.
704  * Header And Value(A): adjusts based on the longest string in column values and column header string.
705
706
707 ### Command - Execute (X) Ctrl-M
708
709 This command executes command.
710 This is same as pressing enter key in the end of the I/O area. (... same behavior)
711
712
713 ### Command - BREAK (B) Ctrl-Pause(Break)
714
715 This command cancels executing command.
716 The process on the server is not canceled.
717
718
719 ### Command - History Back (P) Ctrl-Up
720
721 This command rotates command histories backward.
722
723
724 ### Command - History Next (N) Ctrl-Down
725
726 This command rotates command histories forward.
727
728
729 ### Command - Show All Histories(A) \<new feature in version 4.2\>
730
731 This command shows all command histories and paste a choosen commmand.
732
733
734 ### Command - Rollback (R)
735
736 This command displays confirm dialog and click "OK" to rollback.
737
738
739 ### Command - Commit (M)
740
741 This command displays confirm dialog and click "OK" to commit.
742
743
744 ### Command - Connect (C) Ctrl-E
745
746 This command shows the list of connectors.
747 Select connector name you want to connect to, and click "OK" to executes connect command.
748
749
750 ### Command - Disconnect (D) Ctrl-D
751
752 This command disconnects current connection.
753 This is the same as disconnect command.
754
755
756 ### Command - Post-Proccess (0)
757
758 This command specifies the configuration of a "Post-Proccess" mode.
759
760 The "Post-Proccess" is an action to notify that command finished.
761 When the window which command is running, is not active, "Post-Proccess" is invoked.
762
763 There are following modes:
764
765  * None(N): Does nothing.
766  * Focus(F): Focuses window.
767  * Shake(S): Shakes window.
768  * Blink(B): Blinks window.
769
770
771 ### Command - Encryption Key (K)
772
773 This command shows the dialog to input an encryption key.
774
775
776 ### Command - Edit Connectors (E)
777
778 This command shows the dialog to edit connectors.
779
780
781 ### Data - Sort (S) Alt-S
782
783 This command sorts records by selected column.
784
785
786 ### Data - Import File (I)
787
788 This command imports from file into the table of current result.
789
790
791 ### Data - Export File (E) Ctrl-Shift-S
792
793 This command exports results into file.
794
795
796 ### Help - Show Help
797
798 This command shows this help file by default browser.
799
800
801 ### Help - About Stew
802
803 This command shows version dialog about Stew.
804
805
806
807 ## Properties
808
809 You can set these system properties into java -D option or stew.properties file.
810
811
812 ### net.argius.stew.properties - Location Of Properties File
813
814 Property Value: a file path or a directory path
815
816 This property specifies the location of "stew.properties" file.
817 This properties file is used as system properties and searched in the following steps:
818
819 +If it specifies a file path, the file will be used as system properties.
820 +If it specifies a directory path, the file will be searched a "stew.properties" file in the directory.
821 +Search a file in the classpath.
822 +Search a file in the system directory.
823
824 The first file found is used.
825 If a file is not found, ... (ignore it).
826
827
828 ### net.argius.stew.directory - Working Directory
829
830 Property Value: a directory path (default: current directory)
831
832 This property specifies the current directory as a internal state at the start, but it is not a platform one.
833
834
835 ### net.argius.stew.query.timeout - Query Timeout
836
837 Property Value: integer seconds (default: 0)
838
839 This property specifies the query timeout which is used in commands.
840
841 If it is under 0, the property was not set.
842
843 (implementation detail: for java.sql.Statement#setQueryTimeout)
844
845
846 ### net.argius.stew.rowcount.limit - Limit Of Display Result Row Count
847
848 Property Value: maximum number of rows (default: Integer.MAX_VALUE, about 2,147,000,000)
849
850 This property specifies the maximum number of rows which show in the result set table.
851 It is not used to output files, such as the export command.
852
853
854 ### net.argius.stew.command.Import.batch.limit - Limit Of Import Command Using Batch
855
856 Property Value: limit number of rows (default: 10000)
857
858 This property is used by the Import command.
859 It is not used to output files, such as the export command.
860
861
862 ### net.argius.stew.ui.window.resident - Regident
863
864 Property Value: integer minutes
865
866 This is an experimental feature.
867
868 The app redraws continuously at the specified interval to prevent swap-out.
869
870
871 ### Logger Configurations
872
873 Use logging.properties in this package.
874