--------------------
pysqlite usage guide
--------------------

| (c) 2004-2005 David Rushby
| (c) 2005-2007 Gerhard Häring

Last updated for pysqlite 2.4.0

Table Of Contents
=================

| `0. Introduction`_
| `1. Python Database API 2.0 Compliance`_
|   `1.1 Incompatibilities`_
|   `1.2 Unsupported Optional Features`_
|   `1.3 Nominally Supported Optional Features`_
|   `1.4 Extensions and Caveats`_
| `2. Brief Tutorial`_
|   `2.1 Connecting to a Database`_
|   `2.2 Executing SQL statements`_
| `3. Native Database Engine Features and Extensions Beyond the Python DB API`_
|   `3.1 Creating user-defined functions`_
|   `3.2 Creating user-defined aggregates`_
|   `3.3 Creating and using collations`_
|   `3.4 Checking for complete statements`_
|   `3.5 Enabling SQLite's shared cache`_
|   `3.6 Setting an authorizer callback`_
|   `3.7 Setting a progress handler`_
|   `3.8 Using the connection as a context manager`_
| `4. SQLite and Python types`_
|   `4.1 Introduction`_
|   `4.2 Using adapters to store additional Python types in SQLite databases`_
|     `4.2.1 Letting your object adapt itself`_
|     `4.2.2 Registering an adapter callable`_
|   `4.3 Converting SQLite values to custom Python types`_
|   `4.4 Default pysqlite adapters and converters`_
| `5. Controlling Transactions`_
| `6. Using pysqlite efficiently`_
|   `6.1 Using shortcut methods`_
|   `6.2 Accessing columns by name instead of by index`_
| `7. Combining APSW and pysqlite`_

0. Introduction
===============

This Usage Guide is not a tutorial on Python, SQL, or SQLite; rather, it is a
topical presentation of pysqlite's feature set, with example code to
demonstrate basic usage patterns. This guide is meant to be consumed in
conjunction with the Python Database API Specification and the SQLite
documentation.

It was originally written by David Rushby for kinterbasdb. He kindly gave the
permission to adapt it for pysqlite.

1. Python Database API 2.0 Compliance
=====================================

1.1 Incompatibilities
---------------------

* No type information in cursor.description

  *cursor.description* has a tuple with the fields (*name*, *type_code*,
  *display_size*, *internal_size*, *precision*, *scale*, *null_ok*) for each
  column that a query returns. The DB-API spec requires that at least *name*
  and *type_code* are filled, but at the time cursor.description is built,
  pysqlite cannot determine any types, yet. So, the only field of
  *cursor.description* that pysqlite fills is *name*. All other fields are set to
  None.

* No type objects

  Consequently, there are also no type objects STRING, BINARY, NUMBER,
  DATETIME, ROWID at module-level. They would be useless.

1.2 Unsupported Optional Features
---------------------------------

* **Cursor** class

  * **nextset** method

    This method is not implemented because the database engine does not
    support opening multiple result sets simultaneously with a single
    cursor.

1.3 Nominally Supported Optional Features
-----------------------------------------

* **Cursor** class

  * **arraysize** attribute

    As required by the spec, the value of this attribute is observed
    with respect to the fetchmany method. However, changing the value
    of this attribute does not make any difference in fetch efficiency
    because the database engine only supports fetching a single row at
    a time.

  * **setinputsizes** method

    Although this method is present, it does nothing, as allowed by the
    spec.

  * **setoutputsize** method

    Although this method is present, it does nothing, as allowed by the
    spec.

1.4 Extensions and Caveats
--------------------------

pysqlite offers a large feature set beyond the minimal requirements of the
Python DB API. Most of these extensions are documented in the section of this
document entitled Native Database Engine Features and Extensions Beyond the
Python DB API.

* **connect** function

  The parameter *database* refers to the database file for the SQLite
  database. It's a normal filesystem path and you can use absolute or
  relative path names.

  The connect function supports the following optional keyword arguments
  in addition to those required by the spec:

  * **timeout** - When a database is accessed by multiple connections, and

    one of the processes modifies the database, the SQLite database is
    locked until that transaction is committed. The timeout parameter
    specifies how long the connection should wait for the lock to go away
    until raising an exception. The default for the timeout parameter is
    5.0 (five seconds).

    Example:
     .. code-block:: Python

      sqlite.connect(database="mydb", timeout=10.0)


  * **isolation_level** - pysqlite will by default open transactions with a
    "BEGIN" statement, when it encounters a DML statement like
    INSERT/UPDATE/DELETE/REPLACE. Some users don't want pysqlite to implicitly
    open transactions for them - they want an autocommit mode. Other users want
    pysqlite to open different kinds of transactions, like with "BEGIN
    IMMEDIATE". See `5. Controlling Transactions`_  for a more detailed
    explanation.

    Note that you can also switch to a different isolation level by setting the
    **isolation_level** property of connections.

    Example:
     .. code-block:: Python

      # Turn on autocommit mode
      con = sqlite.connect("mydb", isolation_level=None)

      # Set isolation_level to "IMMEDIATE"
      con.isolation_level = "IMMEDIATE"

  * **detect_types** - SQLite natively supports only the types TEXT,
    INTEGER, FLOAT, BLOB and NULL. If you want to use other types, like you
    have to add support for them yourself.  The *detect_types* parameter and
    using custom *converters* registered with the module-level
    *register_converter* function allow you to easily do that.

    *detect_types* defaults to 0 (i. e. off, no type detection), you can
    set it to any combination of *PARSE_DECLTYPES* and *PARSE_COLNAMES* to turn
    type detection on.

    Consult the section `4. SQLite and Python types`_ of this manual for
    details.

    * **sqlite.PARSE_DECLTYPES** - This makes pysqlite parse the declared
      type for each column it returns. It will parse out the first word of the
      declared type, i. e. for "integer primary key", it will parse out
      "integer". Then for that column, it will look into pysqlite's converters
      dictionary and use the converter function registered for that type there.

    * **sqlite.PARSE_COLNAMES** - This makes pysqlite parse the column name
      for each column it returns. It will look for a string formed
      [mytype] in there, and then decide that 'mytype' is the type of
      the column. It will try to find an entry of 'mytype' in the
      converters dictionary and then use the converter function found
      there to return the value. The column name found in
      cursor.description is only the first word of the column name, i.
      e. if you use something like 'as "x [datetime]"' in your SQL,
      then pysqlite will parse out everything until the first blank for
      the column name: the column name would simply be "x".

      The following example uses the column name *timestamp*, which is already
      registered by default in the converters dictionary with an appropriate
      converter!

      Example:

      .. code-block::
       :language: Python
       :source-file: includes/sqlite3/parse_colnames.py

  * **check_same_thread** - SQLite connections/cursors can only safely be
    used in the same thread they were created in. pysqlite checks for
    this each time it would do a call to the SQLite engine. If you are
    confident that you are ensuring safety otherwise, you can disable
    that checks by setting check_same_thread to False.

  * **factory** - By default, pysqlite uses the Connection class for the
    connect call. You can, however, subclass the Connection class and
    make .connect() use your class instead by providing your class for
    the factory parameter.

    Example:

    .. code-block::
     :language: Python
     :source-file: includes/sqlite3/countcursors.py

  * **cached_statements** - pysqlite internally uses a statement cache to avoid
    SQL parsing overhead. If you want to explicitly set the number of
    statements that are cached for the connection, you can set this parameter.
    The currently implemented default is to cache 100 statements.

  |
  |

* **register_converter** function - ``register_converter(typename, callable)``
  registers a callable to convert a bytestring from the database into a custom
  Python type. The converter will be invoked for all database values that are
  of the type ``typename``. Confer the parameter **detect_types** of the
  **connect** method for how the type detection works.

* **register_adapter** function - ``register_adapter(type, callable)``
  registers a callable to convert the custom Python **type** into one of
  SQLite's supported types. The callable accepts as single parameter the Python
  value, and must return a value of the following types: int, long, float, str
  (UTF-8 encoded), unicode or buffer.

* **enable_callback_tracebacks** function - ``enable_callback_tracebacks(flag)``
  Can be used to enable displaying tracebacks of exceptions in user-defined functions, aggregates and other callbacks being printed to stderr.
  methods should never raise any exception. This feature is off by default.

* **Connection** class

  * **isolation_level** attribute (read-write)

    Get or set the current *isolation level*: None for autocommit mode or one
    of "DEFERRED", "IMMEDIATE" or "EXLUSIVE". See `5. Controlling
    Transactions`_ for a more detailed explanation.

  * **cursor method** - The cursor method accepts a single optional parameter:
    a custom cursor class extending pysqlite's *Cursor* class that you can
    adapt to your needs. Note that it is required that your custom cursor class
    extends pysqlite's *Cursor* class.

  * **execute method** - Nonstandard - this works as a shortcut for not having
    to create a cursor object and is implemented like this:

     .. code-block:: Python

      class Connection:
        def execute(self, *args):
          cur = self.cursor()
          cur.execute(*args)
          return cur

  * **executemany method** - Nonstandard - The same shortcut as the nonstandard
    ``execute`` method.

  * **executesript method** - Nonstandard - The same shortcut as the nonstandard
    ``execute`` method.

  * **row_factory** attribute (read-write)

    You can change this attribute to a callable that accepts the cursor and
    the original row as tuple and will return the real result row.  This
    way, you can implement more advanced ways of returning results, like
    ones that can also access columns by name.

    Example:

    .. code-block::
     :language: Python
     :source-file: includes/sqlite3/row_factory.py

    If the standard tuple types don't suffice for you, and you want name-based
    access to columns, you should consider setting ``row_factory`` to the
    highly-optimized ``pysqlite2.dbapi2.Row`` type. It provides both
    index-based and case-insensitive name-based access to columns with almost
    no memory overhead. Much better than your own custom dictionary-based
    approach or even a ``db_row`` based solution.

  * **text_factory** attribute (read-write)

    Using this attribute you can control what objects pysqlite returns for the
    TEXT data type. By default, this attribute is set to ``unicode`` and
    pysqlite will return Unicode objects for TEXT. If you want to return
    bytestrings instead, you can set it to ``str``.

    For efficiency reasons, there's also a way to return Unicode objects only
    for non-ASCII data, and bytestrings otherwise. To activate it, set this
    attribute to ``pysqlite2.dbapi2.OptimizedUnicode``.

    You can also set it to any other callable that accepts a single bytestring
    parameter and returns the result object.

    See the following example code for illustration:

     .. code-block::
      :language: Python
      :source-file: includes/sqlite3/text_factory.py

  * **total_changes** attribute (read-only)

    Returns the total number of database rows that have be modified, inserted,
    or deleted since the database connection was opened.

  |
* **Cursor** class

  * **execute** method

    pysqlite uses *paramstyle = "qmark"*. That means if you use parametrized
    statements, you use the question mark as placeholder.

    This is a basic example showing the use of question marks as placeholders
    and a parameter tuple:

    .. code-block::
     :language: Python
     :source-file: includes/sqlite3/execute_1.py

    pysqlite also supports *paramstyle = "named"*. That means you can use named
    placeholders in the format ":name", i. e. a colon followed by the parameter
    name. As parameters, you then supply a mapping instead of a sequence. In
    the simplest case, a dictionary instead of a tuple.

    .. code-block::
     :language: Python
     :source-file: includes/sqlite3/execute_2.py

    The following example shows a shortcut that you can often use when using
    named parameters. It exploits the fact that locals() is a dictionary, too.
    So you can also use it as parameter for *execute*:

    .. code-block::
     :language: Python
     :source-file: includes/sqlite3/execute_3.py

    *execute* will only execute a single SQL statement. If you try to execute
    more than one statement with it, it will raise a Warning. Use
    *executescript* if want to execute multiple SQL statements with one call.


  * **executemany** method

    The DB-API specifies the executemany method like this:

    .. code-block:: Python

      .executemany(operation, seq_of_parameters)

    pysqlite, however, extends *executemany* so it can be used more efficiently
    for inserting bulk data. The second parameter to *executemany* can be a
    *sequence of parameters*, but it can also be an *iterator* returning
    parameters.

    Example:

    .. code-block::
     :language: Python
     :source-file: includes/sqlite3/executemany_1.py

    As generators are iterators, too, here's a much simpler, equivalent example
    using a generator:

    .. code-block::
     :language: Python
     :source-file: includes/sqlite3/executemany_2.py

    *executemany* will only execute a single SQL statement. If you try to
    execute more than one statement with it, it will raise a Warning. Use
    *executescript* if want to execute multiple SQL statements with one call.

  * **executescript** method

    .. code-block:: Python

        .executemany(sqlscript)

    This is a nonstandard convenience method for executing multiple SQL
    statements at once. It issues a COMMIT statement before, then executes the
    SQL script it gets as a parameter.

    The SQL script ``sqlscript`` can be a bytestring or a Unicode string.

    Example:

    .. code-block::
     :language: Python
     :source-file: includes/sqlite3/executescript.py

  * **interrupt** method

    This method has no arguments. You can call it from a different thread to
    abort any queries that are currently executing on the connection. This can
    be used to let the user abort runaway queries, for example.

  * **rowcount** attribute

    Although pysqlite's Cursors implement this attribute, the database
    engine's own support for the determination of "rows affected"/"rows
    selected" is quirky.

    For ``SELECT`` statements, *rowcount* is always -1 because pysqlite
    cannot determine the number of rows a query produced until all rows
    were fetched.

    For ``DELETE`` statements, SQLite reports *rowcount* as 0 if you make a
    ``DELETE FROM table`` without any condition.

    For *executemany* statements, pysqlite sums up the number of
    modifications into *rowcount*.

    As required by the Python DB API Spec, the *rowcount* attribute "is -1
    in case no executeXX() has been performed on the cursor or the rowcount
    of the last operation is not determinable by the interface".

|

----

|

2. Brief Tutorial
=================

This brief tutorial aims to get the reader started by demonstrating elementary
usage of pysqlite. It is not a comprehensive Python Database API tutorial, nor
is it comprehensive in its coverage of anything else.

2.1 Connecting to a Database
----------------------------

    **Example 1**

    Connecting to a database file *mydb*:

    .. code-block::
     :language: Python
     :source-file: includes/sqlite3/connect_db_1.py


    **Example 2**

    Creating an in-memory database:

    .. code-block::
     :language: Python
     :source-file: includes/sqlite3/connect_db_2.py


2.2 Executing SQL statements
----------------------------

For this section, we have a database *mydb* defined and populated by the
following SQL code:

  .. code-block:: SQL

    create table people
    (
      name_last      varchar(20),
      age            integer
    );

    insert into people (name_last, age) values ('Yeltsin',   72);
    insert into people (name_last, age) values ('Putin',     51);

*Example 1*

This example shows the simplest way to print the entire contents of the ``people`` table:

.. code-block::
 :language: Python
 :source-file: includes/sqlite3/execsql_printall_1.py

Sample output::

  [(u'Putin', 51), (u'Yeltsin', 72)]

*Example 2*

Here's another trivial example that demonstrates various ways of fetching a
single row at a time from a SELECT-cursor:

.. code-block::
 :language: Python
 :source-file: includes/sqlite3/execsql_fetchonerow.py

Sample output::

  Putin is 51 years old.
  Yeltsin is 72 years old.
  Putin is 51 years old.
  Yeltsin is 72 years old.

*Example 3*

The following program is a simplistic table printer (applied in this example to
people)

.. code-block::
 :language: Python
 :source-file: includes/sqlite3/simple_tableprinter.py

Sample output::

  name_last            age
  ------------------------------------------------------------------------------
  Putin                51
  Yeltsin              72

*Example 4*

Let's insert more people into the people table: 

.. code-block::
 :language: Python
 :source-file: includes/sqlite3/insert_more_people.py

Note the use of a parameterized SQL statement above. When dealing with
repetitive statements, this is much faster and less error-prone than assembling
each SQL statement manually.

It's also worth noting that in the example above, the code: 

It's also worth noting that in the example above, the code:

.. code-block:: Python

  for person in newPeople:
      cur.execute("insert into people (name_last, age) values (?, ?)", person)

could be rewritten as:

.. code-block:: Python

  cur.executemany("insert into people (name_last, age) values (?, ?)", newPeople)

After running Example 4, the table printer from Example 3 would print::

  name_last            age
  ------------------------------------------------------------------------------
  Putin                51
  Lebed                53
  Zhirinovsky          57
  Yeltsin              72

|

----

|

3. Native Database Engine Features and Extensions Beyond the Python DB API
==========================================================================

3.1 Creating user-defined functions
-----------------------------------

SQLite supports user-defined functions.  Using pysqlite, you can create new
functions with the connection's **create_function** method:

  .. code-block:: Python

    def create_function(self, name, numparams, func)

  *name*
    the name of your function in SQL
  *numparams*
    the number of parameters your function accepts, -1 if it accepts any
    number of parameters
  *func*
    the Python function

  The function can return any of pysqlite's supported SQLite types: unicode,
  str, int, long, float, buffer and None.  Any exception in the user-defined
  function leads to the SQL statement executed being aborted.

  Example:

  .. code-block::
   :language: Python
   :source-file: includes/sqlite3/md5func.py

3.2 Creating user-defined aggregates
------------------------------------

SQLite supports user-defined aggregate functions. Using pysqlite, you can
create new aggregate functions with the connection's *create_aggregate* method.

  .. code-block:: Python

    def create_aggregate(self, name, numparams, aggregate_class)

  The aggregate class must implement a *step* method, which accepts the
  number of parameters defined in *create_aggregate*, and a *finalize*
  method which will return the final result of the aggregate.

  The *finalize* method can return any of pysqlite's supported SQLite types:
  unicode, str, int, long, float, buffer and None. Any exception in the
  aggregate's *__init__*, *step* or *finalize* methods lead to the SQL
  statement executed being aborted.

  Example:

  .. code-block::
   :language: Python
   :source-file: includes/sqlite3/mysumaggr.py

3.3 Creating and using collations
---------------------------------

  .. code-block:: Python

    def create_collation(name, callable)

Creates a collation with the specified name and callable. The callable will be
passed two string arguments. It should return -1 if the first is less than the
second, 0 if they are equal and 1 and if the first is greater than the second.
Note that this controls sorting (ORDER BY in SQL) so your comparisons don't
affect other SQL operations. Read more about SQLite's handling of collations.
(This calls sqlite3_create_collation.) If there is an error in your Python code
then 0 (ie items are equal) is returned.

Note that the callable will get its parameters as Python bytestrings, which
will normally be encoded in UTF-8.

The following example shows a custom collation that sorts "the wrong way":

  .. code-block::
   :language: Python
   :source-file: includes/sqlite3/collation_reverse.py

To remove a collation, call `create_collation` with None as callable:

  .. code-block:: Python

    con.create_collation("reverse", None)

3.4 Checking for complete statements
------------------------------------

The module-level function *complete_statement(sql)* can be used to check if a
string contains a complete SQL statement or is still incomplete. The given
string could still contain invalid SQL, but be parsable as a "complete"
statement!

This can be used to build a shell for SQLite, like in the following example:

  .. code-block::
   :language: Python
   :source-file: includes/sqlite3/complete_statement.py

3.5 Enabling SQLite's shared cache
----------------------------------

To enable SQLite's shared cache for the calling thread, call the function
*enable_shared_cache*.

  .. code-block::
   :language: Python
   :source-file: includes/sqlite3/shared_cache.py

3.6 Setting an authorizer callback
----------------------------------

You can set an authorizer callback if you want to restrict what your users can
do with the database. This is mostly useful if you accept arbitrary SQL from
users and want to execute it safely. See the relevant section in the SQL
documentation for details:
http://sqlite.org/capi3ref.html#sqlite3_set_authorizer

All necessary constants like SQLITE_OK, SQLITE_DENY, SQLITE_IGNORE,
SQLITE_SELECT, SQLITE_CREATE_INDEX and all other authorizer-related constants
are available through the dbapi2 module.

Here's an example that demonstrates the usage of this function:

  .. code-block::
   :language: Python
   :source-file: includes/sqlite3/authorizer.py

3.7 Setting a progress handler
------------------------------

If you want to get called by SQLite during long-running operations, you can set
a progress handler. An example use for this is to keep a GUI updated during a
long-running query. 

  .. code-block:: Python

    def set_progress_handler(self, handler, n)

The progress handler will be called every n SQLite virtual machine opcodes. If
handler returns a nonzero value, the query is aborted with an OperationalError.

Here's an example that demonstrates the usage of this function:

  .. code-block::
   :language: Python
   :source-file: includes/sqlite3/progress.py

3.8 Using the connection as a context manager
---------------------------------------------

With Python 2.5 or higher, pysqlite's connection objects can be used as context
managers that automatically commit or rollback transactions.  In the event of
an exception, the transaction is rolled back; otherwise, the transaction is
committed:

  .. code-block::
    :language: Python
    :source-file: includes/sqlite3/ctx_manager.py

4. SQLite and Python types
==========================

4.1 Introduction
----------------

http://sqlite.org/datatype3.html

SQLite natively supports the following types: NULL, INTEGER, REAL, TEXT, BLOB.

The following Python types can thus be sent to SQLite without any problem:

======================  ===========
Python type             SQLite type
======================  ===========
NoneType                NULL
int                     INTEGER
long                    INTEGER
float                   REAL
str (utf-8 encoded)     TEXT
unicode                 TEXT
buffer                  BLOB
======================  ===========

This is how SQLite types are converted to Python types by default:

===========  ==============================
SQLite type  Python type
===========  ==============================
NULL         NoneType
INTEGER      int or long, depending on size
REAL         float
TEXT         unicode
BLOB         buffer
===========  ==============================

pysqlite's type system is extensible in both ways: you can store additional
Python types in a SQLite database via object adaptation, and you can let
pysqlite convert SQLite types to different Python types via pysqlite's
converters.

4.2 Using adapters to store additional Python types in SQLite databases
-----------------------------------------------------------------------

Like described before, SQLite supports only a limited set of types natively. To
use other Python types with SQLite, you must *adapt* them to one of pysqlite's
supported types for SQLite. So, one of NoneType, int, long, float, str,
unicode, buffer.

pysqlite uses the Python object adaptation, like described in PEP 246 for this.
The protocol to use is ``PrepareProtocol``.

There are two ways to enable pysqlite to adapt a custom Python type to one of
the supported ones.

4.2.1 Letting your object adapt itself
--------------------------------------

This is a good approach if you write the class yourself. Let's suppose you have
a class like this:

  .. code-block:: Python

    class Point(object):
        def __init__(self, x, y):
            self.x, self.y = x, y

Now you want to store the point in a single SQLite column. You'll have to
choose one of the supported types first that you use to represent the point in.
Let's just use str and separate the coordinates using a semicolon. Then you
need to give your class a method ``__conform__(self, protocol)`` which must
return the converted value. The parameter ``protocol`` will be
``PrepareProtocol``.

.. code-block::
 :language: Python
 :source-file: includes/sqlite3/adapter_point_1.py

4.2.2 Registering an adapter callable
-------------------------------------

The other possibility is to create a function that converts the type to the
string representation and register the function with ``register_adapter``.

.. code-block::
 :language: Python
 :source-file: includes/sqlite3/adapter_point_2.py

The type/class to adapt must be a new-style class, i. e. it must have
``object`` as one of its bases!!!

pysqlite has two default adapters for Python's builtin *date* and *datetime*
types. Now let's suppose we want to store *datetime* objects not in ISO
representation, but as Unix timestamp.

.. code-block::
 :language: Python
 :source-file: includes/sqlite3/adapter_datetime.py

4.3 Converting SQLite values to custom Python types
---------------------------------------------------

Now that's all nice and dandy that you can send custom Python types to SQLite.
But to make it really useful we need to make the Python to SQLite to Python
roundtrip work.

Enter pysqlite converters.

Let's go back to the Point class. We stored the x and y coordinates separated
via semicolons as strings in SQLite.

Let's first define a converter function that accepts the string as a parameter and constructs a Point object from it.

!!! Note that converter functions *always* get called with a string, no matter
under which data type you sent the value to SQLite !!!

  .. code-block:: Python

    def convert_point(s):
        x, y = map(float, s.split(";"))
        return Point(x, y)

Now you need to make pysqlite know that what you select from the database is
actually a point. There are two ways of doing this:

 * Implicitly via the declared type
 * Explicitly via the column name

Both ways are described in section `1.4 Extensions and Caveats`_ in the
paragraphs describing the connect function, and specifically the meaning of the
*detect_types* parameter.

The following example illustrates both ways.

.. code-block::
 :language: Python
 :source-file: includes/sqlite3/converter_point.py

4.4 Default pysqlite adapters and converters
--------------------------------------------

pysqlite has default adapters for the date and datetime types in the datetime
module. They will be sent as ISO dates/ISO timestamps to SQLite.

pysqlite has default converters registered under the name "date" for
datetime.date and under the name "timestamp" for datetime.datetime.

This way, you can use date/timestamps from pysqlite without any additional
fiddling in most cases. The format of the adapters is also compatible with the
experimental SQLite date/time functions.

The following example demonstrates this.

.. code-block::
 :language: Python
 :source-file: includes/sqlite3/pysqlite_datetime.py

5. Controlling Transactions
---------------------------

By default, pysqlite opens transactions implicitly before a DML statement
(*INSERT/UPDATE/DELETE/REPLACE*), and commits transactions implicitly before a
non-DML, non-DQL statement (i. e. anything other than
*SELECT/INSERT/UPDATE/DELETE/REPLACE*).

So if you are within a transaction, and issue a command like ``CREATE TABLE
...``, ``VACUUM``, ``PRAGMA``, pysqlite will commit implicitly before executing
that command. There are two reasons for doing that. The first is that most of
these commands don't work within transactions. The other reason is that
pysqlite needs to keep track of the transaction state (if a transaction is
active or not).

You can control which kind of "BEGIN" statements pysqlite implicitly executes
(or none at all) via the **isolation_level** parameter to the *connect* call,
or via the **isolation_level** property of connections.

If you want *autocommit mode*, then set **isolation_level** to None.

Otherwise leave it at it's default, which will result in a plain "BEGIN"
statement, or set it to one of SQLite's supported isolation levels: DEFERRED,
IMMEDIATE or EXCLUSIVE.

6. Using pysqlite efficiently
-----------------------------

6.1 Using shortcut methods
--------------------------

Using the nonstandard ``execute()``, ``executemany()`` and ``executescript()``
methods of the Connection object, your code can be written more concisely,
because you don't have to create the - often superfluous Cursor objects
explicitly. Instead, the Cursor objects are created implicitly and
these shortcut methods return the cursor objects. This way, you can for
example execute a SELECT statement and iterate over it directly using
only a single call on the Connection object.

.. code-block::
 :language: Python
 :source-file: includes/sqlite3/shortcut_methods.py

6.2 Accessing columns by name instead of by index
-------------------------------------------------

A cool new feature of pysqlite 2.1.0 is the new builtin sqlite.Row class
designed to be used as a row factory.

Rows wrapped with this class can be accessed both by index (like tuples) and
case-insensitively by name:

.. code-block::
 :language: Python
 :source-file: includes/sqlite3/rowclass.py

7. Combining APSW and pysqlite
------------------------------

APSW is "Another Python SQLite Wrapper". Its goal is to directly wrap the
SQLite API for Python. If there's SQLite functionality that is only wrapped via
APSW, but not (yet) via pysqlite, then you can still use the APSW functionality
in pysqlite.

Just use the APSW Connection as a parameter to the connect function and reuse
an existing APSW connection like this.

.. code-block::
  :language: Python
  :source-file: includes/sqlite3/apsw_example.py

This feature only works if both APSW and pysqlite are dynamically linked
against the same SQLite shared library. I. e. it will *not* work on Windows
without a custom built pysqlite and APSW.

