Mercurial > sqlpython

annotate docs/source/intro.rst @ 517:c36e0aa695a4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
column autocomplete working
author Catherine Devlin <catherine.devlin@gmail.com>
date Wed, 03 Nov 2010 07:47:17 -0400
parents 920a45f244e8
children 69997c324eb9
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
517
c36e0aa695a4 column autocomplete working
Catherine Devlin <catherine.devlin@gmail.com>
parents: 477
diff changeset
61 or
c36e0aa695a4 column autocomplete working
Catherine Devlin <catherine.devlin@gmail.com>
parents: 477
diff changeset
62
c36e0aa695a4 column autocomplete working
Catherine Devlin <catherine.devlin@gmail.com>
parents: 477
diff changeset
63 sqlpython [--postgres|mysql] database-name username
c36e0aa695a4 column autocomplete working
Catherine Devlin <catherine.devlin@gmail.com>
parents: 477
diff changeset
64
329
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
65 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
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@SID
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 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
70
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
71 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
72
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
73 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
74
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
75 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
76 information.
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 Bugs
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
477
920a45f244e8 setuptools optional
catherine@dellzilla
parents: 464
diff changeset
81 Please report bugs at http://www.assembla.com/spaces/sqlpython/tickets or to catherine.devlin@gmail.com.
329
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
82
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
83 Origins
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
84 -------
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
85
283
80484bc60bdd still needs refs
catherine@dellzilla
parents: 247
diff changeset
86 SQLPython is based on the Python standard library's
80484bc60bdd still needs refs
catherine@dellzilla
parents: 247
diff changeset
87 `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
88 to it called `cmd2 <http://pypi.python.org/pypi/cmd2>`_. SQLPython also draws considerable
80484bc60bdd still needs refs
catherine@dellzilla
parents: 247
diff changeset
89 inspiration from two Perl-based open-source SQL clients,
80484bc60bdd still needs refs
catherine@dellzilla
parents: 247
diff changeset
90 `Senora <http://senora.sourceforge.net/>`_ and `YASQL <http://sourceforge.net/projects/yasql>`_.
247
f0f293d83337 begin docs
catherine@dellzilla
parents:
diff changeset
91
329
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
92 Non-Oracle RDBMS
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
93 ----------------
3efffbf7481f fixed bug in assigning 0, null to bind vars
Catherine Devlin <catherine.devlin@gmail.com>
parents: 313
diff changeset
94
464
26f60d5910a0 doubledashcomment moved into sqlpyPlus to define parser after local comment definition
catherine@Drou
parents: 329
diff changeset
95 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
96 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
97 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
98 will be available as soon as those databases are added to the Gerald project, and volunteers
517
c36e0aa695a4 column autocomplete working
Catherine Devlin <catherine.devlin@gmail.com>
parents: 477
diff changeset
99 for Gerald will benefit sqlpython as well.