Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

improve db docs

  • Loading branch information...
commit bdeec7d1eb1ec6fef7cee6a0d18f98e0257d76b7 1 parent 1b35df9
@asldevi asldevi authored
Showing with 50 additions and 42 deletions.
  1. +50 −18 docs/db.rst
  2. +0 −24 docs/index.rst
View
68 docs/db.rst
@@ -4,7 +4,7 @@ Accessing the database
Web.py provides a simple and uniform interface to the database that you want to work with, whether it is PostgreSQL, MySQL, SQLite or any other. It doesn't try to build layers between you and your database. Rather, it tries to make it easy to perform common tasks, and get out of your way when you need to do more advanced things.
-Create a database object
+Create database object
------------------------
You could create a database object with `web.database()`. Make sure that you have appropriate database library installed.
@@ -61,14 +61,13 @@ Inserting
The first argument is the table name and the rest of them are set of named arguments which represent the fields in the table. If values are not given, the database may create default values or issue a warning.
-For bulk insertion rather than inserting record by record, use `multiple_insert` rather.
-
-Bulk Inserting
-``````````````
-
+For bulk insertion rather than inserting record by record, use `Multiple Inserts` rather.
Selecting
`````````
+
+The `select` method is used for selecting rows from the database. It returns a `web.iterbetter` object, which can be looped through.
+
To select `all` the rows from the `user` table, you would simply do
::
@@ -91,9 +90,35 @@ To prevent SQL injection attacks, you can use `$key` in where clause and pass th
<sql: "SELECT * FROM users WHERE name = 'Bob'">
+Updating
+````````
+The `update` method accepts same kind of arguments as Select. It returns the number of rows updated.
+
+::
+
+ num_updated = db.update('users', where="id = 10", firstname = "Foo")
+
+Deleting
+````````
+The `delete` method returns the number of rows deleted. It also accepts "using" and "vars" parameters. See ``Selecting`` for more details on `vars`.
+
+::
+
+ num_deleted = db.delete('users', where="id=10")
+
+Multiple Inserts
+````````````````
+The `multiple_insert` method on the `db` object allows you to do that. All that's needed is to prepare a list of dictionaries, one for each row to be inserted, each with the same set of keys and pass it to `multiple_insert` along with the table name. It returns the list of ids of the inserted rows.
+
+The value of `db.supports_multiple_insert` tells you if your database supports multiple inserts.
+::
+
+ values = [{"name": "foo", "email": "foo@example.com"}, {"name": "bar", "email": "bar@example.com"}]
+ db.multiple_insert('person', values=values)
+
+
Advanced querying
`````````````````
-
Many a times, there is more to do with the database, rather than the simple operations which can be done by `insert`, `select`, `delete` and `update` - Things like your favorite (or scary) joins, counts etc. All these are possible with `query` method, which also takes `vars`.
::
@@ -107,22 +132,29 @@ Joining tables
results = db.query("SELECT * FROM entries JOIN users WHERE entries.author_id = users.id")
-Updating
-````````
-The `update` method accepts same kind of arguments as Select. It returns the number of rows updated.
+Transactions
+````````````
+The database object has a method `transaction` which starts a new transaction and returns the transaction object. The transaction object can be used to commit or rollback that transaction. It is also possible to have nested transactions.
-::
-
- num_updated = db.update('users', where="id = 10", firstname = "Foo")
-
-Deleting
-````````
-The `delete` method returns the number of rows deleted. It also accepts "using" and "vars" parameters. See ``Selecting`` for more details on `vars`.
+From Python 2.5 onwards, which support `with` statements, you would do
::
- num_deleted = db.delete('users', where="id=10")
+ with db.transaction():
+ userid = db.insert('users', name='foo')
+ authorid = db.insert('authors', userid=$userid, vars={'userid': userid})
+For earlier versions of Python, you can do
+::
+ t = db.transaction()
+ try:
+ userid = db.insert('users', name='foo')
+ authorid = db.insert('authors', userid=$userid, vars={'userid': userid})
+ except:
+ t.rollback()
+ raise
+ else:
+ t.commit()
View
24 docs/index.rst
@@ -24,30 +24,6 @@ urls = (...)
regular expressions and grouping
-Taking Inputs
-=============
-
-web.input()
-web.input(page=0)
-reading GET and POST
-reading files
-
-Working with database
-=====================
-
-web.database()
-
-db.query
-db.select
-db.insert
-db.multiple_insert
-db.delete
-
-working with transactions
-
-with db.transaction():
- db.insert(..)
-
Indices and tables
==================

0 comments on commit bdeec7d

Please sign in to comment.
Something went wrong with that request. Please try again.