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