Changeset 1305

Timestamp:

11/20/05 11:33:40 (3 years ago)

Author:

adrian

Message:

Added 'Executing custom SQL' section to docs/model-api.txt

Files:

• django/trunk/docs/model-api.txt (modified) (2 diffs)

django/trunk/docs/model-api.txt

@@ -964 +964 @@
-Note that the scope of custom methods is modified to be the same as the module
-scope. These methods do NOT have access to globals within your model's module.
+Additionally, custom methods have access to a few commonly-used objects for
+convenience:
+
+    * The ``datetime`` module from Python's standard library.
+    * The ``db`` object from ``django.core.db``. This represents the database
+      connection, so you can do custom queries via a cursor object. See
+      "Executing custom SQL" below.
-
-See `Giving models custom methods`_ for a full example.
@@ -1056 +1063 @@
-            if int(field_data) in BAD_CUSTOMER_IDS:
-                raise validators.ValidationError, "We don't deliver to this customer."
+
+Executing custom SQL
+--------------------
+
+Feel free to write custom SQL statements in custom model methods and
+module-level methods. Each custom method automatically has access to the
+variable ``db``, which is the current database connection. To use it, call
+``db.cursor()`` to get a cursor object. Then, call ``cursor.execute(sql, [params])``
+to execute the SQL and ``cursor.fetchone()`` or ``cursor.fetchall()`` to return
+the resulting rows. Example::
+
+    def my_custom_sql(self):
+        cursor = db.cursor()
+        cursor.execute("SELECT foo FROM bar WHERE baz = %s", [self.baz])
+        row = cursor.fetchone()
+        return row
+
+Note that ``db`` and ``cursor`` simply use the standard `Python DB-API`_.
+
+If you're not familiar with the Python DB-API, note that the SQL statement in
+``cursor.execute()`` uses placeholders, ``"%s"``, rather than adding parameters
+directly within the SQL. If you use this technique, the underlying database
+library will automatically add quotes and escaping to your parameter(s) as
+necessary.
+
+.. _Python DB-API: http://www.python.org/peps/pep-0249.html
-
-Using models