MANUAL.md

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