MANUAL.md

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