Mercurial > sqlpython

annotate docs/source/intro.rst @ 474:f29923ac1119

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
fix home finder to work with windows
author catherine@dellzilla
date Fri, 05 Mar 2010 15:35:01 -0500
parents 26f60d5910a0
children 920a45f244e8
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
464
26f60d5910a0 doubledashcomment moved into sqlpyPlus to define parser after local comment definition
catherine@Drou
parents: 329
diff changeset
10 SQLPython is a command-line interface to relational databases. It was created as an alternative to Oracle's
26f60d5910a0 doubledashcomment moved into sqlpyPlus to define parser after local comment definition
catherine@Drou
parents: 329
diff changeset
11 ``SQL\*Plus``, and can likewise be used instead of postgres' ``psql`` or mysql's ``mysql`` text clients.
26f60d5910a0 doubledashcomment moved into sqlpyPlus to define parser after local comment definition
catherine@Drou
parents: 329
diff changeset
12 For the most part, it can be used as any other text-based SQL interface would; this document focuses on
26f60d5910a0 doubledashcomment moved into sqlpyPlus to define parser after local comment definition
catherine@Drou
parents: 329
diff changeset
13 the extra capabilities
247
f0f293d83337 begin docs
catherine@dellzilla
parents:
diff changeset
14
329
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
15 License
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
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
18 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
19 `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
20
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
21 Authorship
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
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
24 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
25 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
26 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
27 `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
28
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
29 Installation
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
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
32 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
33 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
34
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
35 easy_install sqlpython
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
36
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
37 The development trunk
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
38 (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
39 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
40
313
22fc9a350eaa finally, ls working right
catherine@Elli.myhome.westell.com
parents: 312
diff changeset
41 hg clone http://hg.assembla.com/python-cmd2 cmd2
22fc9a350eaa finally, ls working right
catherine@Elli.myhome.westell.com
parents: 312
diff changeset
42 cd cmd2
22fc9a350eaa finally, ls working right
catherine@Elli.myhome.westell.com
parents: 312
diff changeset
43 python setup.py develop
22fc9a350eaa finally, ls working right
catherine@Elli.myhome.westell.com
parents: 312
diff changeset
44
329
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
45 cd ..
312
c6abd01fe3e1 added link to assembla to docs
catherine@Elli.myhome.westell.com
parents: 299
diff changeset
46 hg clone http://hg.assembla.com/sqlpython sqlpython
c6abd01fe3e1 added link to assembla to docs
catherine@Elli.myhome.westell.com
parents: 299
diff changeset
47 cd sqlpython
c6abd01fe3e1 added link to assembla to docs
catherine@Elli.myhome.westell.com
parents: 299
diff changeset
48 python setup.py develop
c6abd01fe3e1 added link to assembla to docs
catherine@Elli.myhome.westell.com
parents: 299
diff changeset
49
c6abd01fe3e1 added link to assembla to docs
catherine@Elli.myhome.westell.com
parents: 299
diff changeset
50 Using `hg pull`, `hg update` subsequently will update from the current trunk.
247
f0f293d83337 begin docs
catherine@dellzilla
parents:
diff changeset
51
329
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
52 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
53
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
54 easy_install
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
55
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
56 Running
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
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
59 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
60
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
61 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
62
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
63 oracle://username:password@SID
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
64
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
65 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
66
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
67 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
68
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
69 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
70
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
71 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
72 information.
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
73
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
74 Bugs
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
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
77 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
78
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
79 Origins
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
80 -------
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
81
283
80484bc60bdd still needs refs
catherine@dellzilla
parents: 247
diff changeset
82 SQLPython is based on the Python standard library's
80484bc60bdd still needs refs
catherine@dellzilla
parents: 247
diff changeset
83 `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
84 to it called `cmd2 <http://pypi.python.org/pypi/cmd2>`_. SQLPython also draws considerable
80484bc60bdd still needs refs
catherine@dellzilla
parents: 247
diff changeset
85 inspiration from two Perl-based open-source SQL clients,
80484bc60bdd still needs refs
catherine@dellzilla
parents: 247
diff changeset
86 `Senora <http://senora.sourceforge.net/>`_ and `YASQL <http://sourceforge.net/projects/yasql>`_.
247
f0f293d83337 begin docs
catherine@dellzilla
parents:
diff changeset
87
329
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
88 Non-Oracle RDBMS
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
464
26f60d5910a0 doubledashcomment moved into sqlpyPlus to define parser after local comment definition
catherine@Drou
parents: 329
diff changeset
91 Version 1.7.0 of sqlpython works against PostgreSQL and MySQL, though the testing against
26f60d5910a0 doubledashcomment moved into sqlpyPlus to define parser after local comment definition
catherine@Drou
parents: 329
diff changeset
92 those databases has been very slight thus far. Help in testing and improving sqlpython's
26f60d5910a0 doubledashcomment moved into sqlpyPlus to define parser after local comment definition
catherine@Drou
parents: 329
diff changeset
93 functions against those databases is welcome. Support for Microsoft SQL Server and sqlite
26f60d5910a0 doubledashcomment moved into sqlpyPlus to define parser after local comment definition
catherine@Drou
parents: 329
diff changeset
94 will be available as soon as those databases are added to the Gerald project, and volunteers
26f60d5910a0 doubledashcomment moved into sqlpyPlus to define parser after local comment definition
catherine@Drou
parents: 329
diff changeset
95 for Gerald will benefit sqlpython as well.
329
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
96
464
26f60d5910a0 doubledashcomment moved into sqlpyPlus to define parser after local comment definition
catherine@Drou
parents: 329
diff changeset
97 As of 1.7.0, sqlpython sessions can only "see" metadata within the named schema belonging
26f60d5910a0 doubledashcomment moved into sqlpyPlus to define parser after local comment definition
catherine@Drou
parents: 329
diff changeset
98 to the currently connected user. A fix for this is expected for 1.7.1.