annotate README.txt @ 126:d0e071e19c26

1.4.7
author catherine@localhost
date Wed, 30 Jul 2008 12:41:26 -0400
parents 4aa28dffe658
children
rev   line source
85
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
1 SQLPython is an open-source command-line environment for interacting with an
91
51e1fe3adf0e to version 1.4.4
catherine@cordelia
parents: 90
diff changeset
2 Oracle database. It is designed as an alternative to Oracle's SQL\*Plus.
85
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
3
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
4 Installing
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
5 ----------
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
6
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
7 Debian/Ubuntu::
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
8
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
9 $ sudo apt-get install python python-dev python-setuptools
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
10 $ sudo easy_install cx_Oracle
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
11 $ sudo easy_install -UZ sqlpython
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
12
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
13 Windows:
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
14 Download and run executable installers from::
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
15
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
16 http://www.python.org (Python language)
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
17 http://cx-oracle.sourceforge.net/ (cx_Oracle)
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
18 http://pypi.python.org/pypi/sqlpython (sqlpython)
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
19
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
20 Other:
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
21 Python is typically already installed. You'll need its
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
22 development package (python-dev); then easy_install
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
23 cx_Oracle and sqlpython as per Debian.
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
24
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
25 Using
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
26 -----
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
27
91
51e1fe3adf0e to version 1.4.4
catherine@cordelia
parents: 90
diff changeset
28 Use sqlpython more or less as you would use SQL\*Plus.
85
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
29
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
30 Read the help. Experiment with UNIX-style and postgresql-style
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
31 commands.
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
32
103
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
33 Special output (inspired by YASQL)
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
34 ----------------------------------
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
35
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
36 An integer following a command terminator limits output to that number of rows, like SQL's LIMIT keyword::
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
37
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
38 hr@xe> SELECT * FROM jobs;2
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
39
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
40 If `;` is replaced by one of these special characters, the output will be formatted as such::
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
41
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
42 ---------- ----------------------
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
43 terminator format
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
44 ---------- ----------------------
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
45 ; standard Oracle format
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
46 \c CSV (with headings)
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
47 \C CSV (no headings)
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
48 \g list
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
49 \G aligned list
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
50 \h HTML table
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
51 \i INSERT statements
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
52 \s CSV (with headings)
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
53 \S CSV (no headings)
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
54 \t transposed
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
55 \x XML
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
56 ---------- ----------------------
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
57
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
58 Special terminators can also be combined with row limits::
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
59
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
60 hr@xe> SELECT * FROM jobs\h5
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
61
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
62 Redirecting output
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
63 ------------------
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
64
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
65 `>` and `>>` write or append the output of a command. If a
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
66 filename is given, that will be the destination of the output.
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
67
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
68 If no filename is given, the output will go into the paste buffer and
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
69 can immediately pasted to any program. This requires `xclip` (*nix) or
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
70 `pywin32` (Windows) to be installed on the operating system.
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
71
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
72 Connecting
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
73 ----------
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
74
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
75 sqlpython supports every version of connecting that SQL*Plus does, including EZCONNECT::
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
76
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
77 $ > sqlpython
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
78 $ > sqlpython hr/hr@xe
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
79 $ > sqlpython hr (uses ORACLE_SID, prompts for password)
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
80 $ > sqlpython hr/hr@hostmachine.somewhere.com/xe
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
81 $ > sqlpython hr/hr@hostmachine.somewhere.com:1521/xe
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
82 $ > sqlpython sys@xe as sysdba
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
83
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
84 You may also supply commands that will be run immediately after connection::
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
85
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
86 $ > sqlpython hr/hr@xe @myscript.sql @another_script.sql quit
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
87
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
88 Multi-word commands must be enclosed in double-quotes::
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
89
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
90 $ > sqlpython hr/hr@xe "cat jobs" "select * from employees;"
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
91
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
92 Combining special output terminators with redirectors and command-line arguments
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
93 can produce powerful one-line programs. For instance, this generates an HTML
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
94 report and exits::
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
95
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
96 $ > sqlpython hr/hr@xe "select * from jobs\h > jobs.html" quit
4aa28dffe658 command-line args working well
catherine@localhost
parents: 91
diff changeset
97
85
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
98 Modifying
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
99 ---------
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
100
90
5c73ebfdb24c tweaking readme
catherine@cordelia
parents: 85
diff changeset
101 Modify mysqlpy.py; add `do_mycommand(self, arg)`
5c73ebfdb24c tweaking readme
catherine@cordelia
parents: 85
diff changeset
102 methods to the mysqlpy class to add your own commands.
5c73ebfdb24c tweaking readme
catherine@cordelia
parents: 85
diff changeset
103
5c73ebfdb24c tweaking readme
catherine@cordelia
parents: 85
diff changeset
104 Use `self.stdout.write(txt)` in place of `print txt`
5c73ebfdb24c tweaking readme
catherine@cordelia
parents: 85
diff changeset
105 to make sure your output can be redirected into text
5c73ebfdb24c tweaking readme
catherine@cordelia
parents: 85
diff changeset
106 files or the paste buffer with `>` and `>>`.
85
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
107
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
108 Contributing
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
109 ------------
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
110
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
111 Development trunk is available from::
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
112
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
113 http://www.assembla.com/wiki/show/sqlpython
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
114
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
115 Bugs and suggestions can be filed at::
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
116
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
117 http://www.assembla.com/spaces/sqlpython/tickets
b336d049cac7 bugs found during gcoug talk prep
catherine@localhost
parents:
diff changeset
118