Mercurial > sqlpython

annotate docs/source/intro.rst @ 461:c27cab20ec4a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
don't die when no connect arg
author cat@eee
date Wed, 24 Feb 2010 12:17:52 -0500
parents 3efffbf7481f
children 26f60d5910a0
rev   line source
247
f0f293d83337 begin docs
catherine@dellzilla
parents:
diff changeset
1 Introduction
f0f293d83337 begin docs
catherine@dellzilla
parents:
diff changeset
2 ============
f0f293d83337 begin docs
catherine@dellzilla
parents:
diff changeset
3
299
a8ac8c1b90cb adding links to docs
catherine@dellzilla
parents: 283
diff changeset
4 * Original project homepage: https://twiki.cern.ch/twiki/bin/view/PSSGroup/SqlPython
a8ac8c1b90cb adding links to docs
catherine@dellzilla
parents: 283
diff changeset
5 * PyPI: http://pypi.python.org/pypi/sqlpython
a8ac8c1b90cb adding links to docs
catherine@dellzilla
parents: 283
diff changeset
6 * News: http://catherinedevlin.blogspot.com/search/label/sqlpython
a8ac8c1b90cb adding links to docs
catherine@dellzilla
parents: 283
diff changeset
7 * Current docs: http://packages.python.org/sqlpython/
329
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
8 * Mailing list: http://groups.google.com/group/sqlpython
299
a8ac8c1b90cb adding links to docs
catherine@dellzilla
parents: 283
diff changeset
9
247
f0f293d83337 begin docs
catherine@dellzilla
parents:
diff changeset
10 SQLPython is a command-line interface to Oracle databases. It is intended as an alternative to Oracle's
f0f293d83337 begin docs
catherine@dellzilla
parents:
diff changeset
11 SQL\*Plus. For the most part, it can be used the same way SQL\*Plus would be used; this documentation
f0f293d83337 begin docs
catherine@dellzilla
parents:
diff changeset
12 focuses on the places where SQLPython differs.
f0f293d83337 begin docs
catherine@dellzilla
parents:
diff changeset
13
329
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
14 License
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
15 -------
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
16
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
17 sqlpython is free and open-source software. Its use is governed by the
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
18 `MIT License <http://www.opensource.org/licenses/mit-license.php>`_.
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
19
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
20 Authorship
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
21 ----------
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
22
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
23 SQLPython was created by `Luca Canali <http://canali.web.cern.ch/canali/>`_ at CERN. Most recent
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
24 development has been done by `Catherine Devlin <http://catherinedevlin.blogspot.com/>`_. A group
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
25 of additional sqlpython contributors has formed at
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
26 `Google Groups <http://groups.google.com/group/sqlpython>`_.
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
27
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
28 Installation
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
29 ------------
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
30
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
31 If `python-setuptools <http://pypi.python.org/pypi/setuptools>`_ is present on your machine, you
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
32 can easily install the latest release of sqlpython by issuing from a command prompt::
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
33
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
34 easy_install sqlpython
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
35
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
36 The development trunk
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
37 (very unstable) is at `assembla <https://www.assembla.com/wiki/show/sqlpython>`_;
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
38 you can install the trunk on your machine with::
312
c6abd01fe3e1 added link to assembla to docs
catherine@Elli.myhome.westell.com
parents: 299
diff changeset
39
313
22fc9a350eaa finally, ls working right
catherine@Elli.myhome.westell.com
parents: 312
diff changeset
40 hg clone http://hg.assembla.com/python-cmd2 cmd2
22fc9a350eaa finally, ls working right
catherine@Elli.myhome.westell.com
parents: 312
diff changeset
41 cd cmd2
22fc9a350eaa finally, ls working right
catherine@Elli.myhome.westell.com
parents: 312
diff changeset
42 python setup.py develop
22fc9a350eaa finally, ls working right
catherine@Elli.myhome.westell.com
parents: 312
diff changeset
43
329
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
44 cd ..
312
c6abd01fe3e1 added link to assembla to docs
catherine@Elli.myhome.westell.com
parents: 299
diff changeset
45 hg clone http://hg.assembla.com/sqlpython sqlpython
c6abd01fe3e1 added link to assembla to docs
catherine@Elli.myhome.westell.com
parents: 299
diff changeset
46 cd sqlpython
c6abd01fe3e1 added link to assembla to docs
catherine@Elli.myhome.westell.com
parents: 299
diff changeset
47 python setup.py develop
c6abd01fe3e1 added link to assembla to docs
catherine@Elli.myhome.westell.com
parents: 299
diff changeset
48
c6abd01fe3e1 added link to assembla to docs
catherine@Elli.myhome.westell.com
parents: 299
diff changeset
49 Using `hg pull`, `hg update` subsequently will update from the current trunk.
247
f0f293d83337 begin docs
catherine@dellzilla
parents:
diff changeset
50
329
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
51 You may also install from the trunk with easy_install::
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
52
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
53 easy_install
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
54
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
55 Running
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
56 -------
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
57
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
58 sqlpython [username[/password][@SID]] ["SQL command 1", "@script.sql", "SQL command 2..."]
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
59
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
60 Database connections can also be specified with URL syntax or with Oracle Easy Connect::
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
61
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
62 oracle://username:password@SID
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
63
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
64 oracle://username:password@hostname:port/dbname
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
65
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
66 oracle://username:password@hostname:port/dbname
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
67
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
68 SID represents an entry from the `tnsnames.ora` file.
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
69
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
70 Once connected, most familiar SQL\*Plus commands can be used. Type `help` for additional
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
71 information.
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
72
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
73 Bugs
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
74 ----
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
75
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
76 Please report bugs at http://trac-hg.assembla.com/sqlpython or to catherine.devlin@gmail.com.
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
77
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
78 Origins
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
79 -------
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
80
283
80484bc60bdd still needs refs
catherine@dellzilla
parents: 247
diff changeset
81 SQLPython is based on the Python standard library's
80484bc60bdd still needs refs
catherine@dellzilla
parents: 247
diff changeset
82 `cmd <http://docs.python.org/library/cmd.html#module-cmd>`_ module, and on an extension
80484bc60bdd still needs refs
catherine@dellzilla
parents: 247
diff changeset
83 to it called `cmd2 <http://pypi.python.org/pypi/cmd2>`_. SQLPython also draws considerable
80484bc60bdd still needs refs
catherine@dellzilla
parents: 247
diff changeset
84 inspiration from two Perl-based open-source SQL clients,
80484bc60bdd still needs refs
catherine@dellzilla
parents: 247
diff changeset
85 `Senora <http://senora.sourceforge.net/>`_ and `YASQL <http://sourceforge.net/projects/yasql>`_.
247
f0f293d83337 begin docs
catherine@dellzilla
parents:
diff changeset
86
329
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
87 Non-Oracle RDBMS
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
88 ----------------
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
89
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
90 As of sqlpython 1.6.4, preliminary work has begun to adapt sqlpython to non-Oracle databases.
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
91 You may use it to run queries against postgreSQL, MySQL, etc., but data-dictionary access
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
92 commands (`ls`, `grep`, `refs`, etc.) will generate errors. Connection to non-Oracle databases
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
93 is currently only possible via URL connection strings.
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
94