`sqlite3` — DB-API 2.0 interfaz para bases de datos SQLite¶

Código fuente: Lib/sqlite3/

SQLite es una biblioteca de C que provee una base de datos ligera basada en disco que no requiere un proceso de servidor separado y permite acceder a la base de datos usando una variación no estándar del lenguaje de consulta SQL. Algunas aplicaciones pueden usar SQLite para almacenamiento interno. También es posible prototipar una aplicación usando SQLite y luego transferir el código a una base de datos más grande como PostgreSQL u Oracle.

The sqlite3 module was written by Gerhard Häring. It provides an SQL interface compliant with the DB-API 2.0 specification described by PEP 249.

To use the module, start by creating a Connection object that represents the database. Here the data will be stored in the example.db file:

import sqlite3
con = sqlite3.connect('example.db')

The special path name :memory: can be provided to create a temporary database in RAM.

Once a Connection has been established, create a Cursor object and call its execute() method to perform SQL commands:

cur = con.cursor()

# Create table
cur.execute('''CREATE TABLE stocks
               (date text, trans text, symbol text, qty real, price real)''')

# Insert a row of data
cur.execute("INSERT INTO stocks VALUES ('2006-01-05','BUY','RHAT',100,35.14)")

# Save (commit) the changes
con.commit()

# We can also close the connection if we are done with it.
# Just be sure any changes have been committed or they will be lost.
con.close()

The saved data is persistent: it can be reloaded in a subsequent session even after restarting the Python interpreter:

import sqlite3
con = sqlite3.connect('example.db')
cur = con.cursor()

To retrieve data after executing a SELECT statement, either treat the cursor as an iterator, call the cursor’s fetchone() method to retrieve a single matching row, or call fetchall() to get a list of the matching rows.

Este ejemplo usa la forma con el iterador:

>>> for row in cur.execute('SELECT * FROM stocks ORDER BY price'):
        print(row)

('2006-01-05', 'BUY', 'RHAT', 100, 35.14)
('2006-03-28', 'BUY', 'IBM', 1000, 45.0)
('2006-04-06', 'SELL', 'IBM', 500, 53.0)
('2006-04-05', 'BUY', 'MSFT', 1000, 72.0)

SQL operations usually need to use values from Python variables. However, beware of using Python’s string operations to assemble queries, as they are vulnerable to SQL injection attacks (see the xkcd webcomic for a humorous example of what can go wrong):

# Never do this -- insecure!
symbol = 'RHAT'
cur.execute("SELECT * FROM stocks WHERE symbol = '%s'" % symbol)

Instead, use the DB-API’s parameter substitution. To insert a variable into a query string, use a placeholder in the string, and substitute the actual values into the query by providing them as a tuple of values to the second argument of the cursor’s execute() method. An SQL statement may use one of two kinds of placeholders: question marks (qmark style) or named placeholders (named style). For the qmark style, parameters must be a sequence. For the named style, it can be either a sequence or dict instance. The length of the sequence must match the number of placeholders, or a ProgrammingError is raised. If a dict is given, it must contain keys for all named parameters. Any extra items are ignored. Here’s an example of both styles:

import sqlite3

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.execute("create table lang (name, first_appeared)")

# This is the qmark style:
cur.execute("insert into lang values (?, ?)", ("C", 1972))

# The qmark style used with executemany():
lang_list = [
    ("Fortran", 1957),
    ("Python", 1991),
    ("Go", 2009),
]
cur.executemany("insert into lang values (?, ?)", lang_list)

# And this is the named style:
cur.execute("select * from lang where first_appeared=:year", {"year": 1972})
print(cur.fetchall())

con.close()

Ver también

https://www.sqlite.org: La página web SQLite; la documentación describe la sintaxis y los tipos de datos disponibles para el lenguaje SQL soportado.
https://www.w3schools.com/sql/: Tutorial, referencia y ejemplos para aprender sintaxis SQL.
PEP 249 - Especificación de la API 2.0 de base de datos: PEP escrito por Marc-André Lemburg.

Funciones y constantes del módulo¶

sqlite3.apilevel¶: String constant stating the supported DB-API level. Required by the DB-API. Hard-coded to "2.0".

sqlite3.paramstyle¶: String constant stating the type of parameter marker formatting expected by the sqlite3 module. Required by the DB-API. Hard-coded to "qmark".

Nota

The sqlite3 module supports both qmark and numeric DB-API parameter styles, because that is what the underlying SQLite library supports. However, the DB-API does not allow multiple values for the paramstyle attribute.

sqlite3.version¶: El número de versión de este módulo, como una cadena de caracteres. Este no es la versión de la librería SQLite.

sqlite3.version_info¶: El número de versión de este módulo, como una tupla de enteros. Este no es la versión de la librería SQLite.

sqlite3.sqlite_version¶: El número de versión de la librería SQLite en tiempo de ejecución, como una cadena de caracteres.

sqlite3.sqlite_version_info¶: El número de versión de la librería SQLite en tiempo de ejecución, como una tupla de enteros.

sqlite3.threadsafety¶

Integer constant required by the DB-API, stating the level of thread safety the sqlite3 module supports. Currently hard-coded to 1, meaning «Threads may share the module, but not connections.» However, this may not always be true. You can check the underlying SQLite library’s compile-time threaded mode using the following query:

import sqlite3
con = sqlite3.connect(":memory:")
con.execute("""
    select * from pragma_compile_options
    where compile_options like 'THREADSAFE=%'
""").fetchall()

Note that the SQLITE_THREADSAFE levels do not match the DB-API 2.0 threadsafety levels.

sqlite3.PARSE_DECLTYPES¶

Esta constante se usa con el parámetro detect_types de la función connect().

Configurarla hace que el módulo sqlite3 analice el tipo declarado para cada columna que retorna. Este convertirá la primera palabra del tipo declarado, i. e. para «integer primary key», será convertido a «integer», o para «number(10)» será convertido a «number». Entonces para esa columna, revisará el diccionario de conversiones y usará la función de conversión registrada para ese tipo.

sqlite3.PARSE_COLNAMES¶

Esta constante se usa con el parámetro detect_types de la función connect().

Setting this makes the SQLite interface 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 does not include the type, i. e. if you use something like 'as "Expiration date [datetime]"' in your SQL, then we will parse out everything until the first '[' for the column name and strip the preceding space: the column name would simply be «Expiration date».

sqlite3.connect(database[, timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements, uri])¶

Abre una conexión al archivo de base de datos SQLite database. Por defecto retorna un objeto Connection, a menos que se indique un factory personalizado.

database es un path-like object indicando el nombre de ruta (absoluta o relativa al directorio de trabajo actual) del archivo de base de datos abierto. Se puede usar ":memory:" para abrir una conexión de base de datos a una base de datos que reside en memoria RAM en lugar que disco.

Cuando una base de datos es accedida por múltiples conexiones, y uno de los procesos modifica la base de datos, la base de datos SQLite se bloquea hasta que la transacción se confirme. El parámetro timeout especifica que tanto debe esperar la conexión para que el bloqueo desaparezca antes de lanzar una excepción. Por defecto el parámetro timeout es de 5.0 (cinco segundos).

Para el parámetro isolation_level, por favor ver la propiedad isolation_level del objeto Connection.

De forma nativa SQLite soporta solo los tipos TEXT, INTEGER,*REAL*,*BLOB* y NULL. Si se quiere usar otros tipos, debe soportarlos usted mismo. El parámetro detect_types y el uso de converters personalizados registrados con la función a nivel del módulo register_converter() permite hacerlo fácilmente.

detect_types por defecto es 0 (es decir, desactivado, sin detección de tipo), puede configurarlo en cualquier combinación de PARSE_DECLTYPES y PARSE_COLNAMES para activar la detección de tipo. Debido al comportamiento de SQLite, los tipos no se pueden detectar para los campos generados (por ejemplo, max(data)), incluso cuando se establece el parámetro detect_types. En tal caso, el tipo devuelto es str.

Por defecto, check_same_thread es True y únicamente el hilo creado puede utilizar la conexión. Si se configura False, la conexión retornada podrá ser compartida con múltiples hilos. Cuando se utilizan múltiples hilos con la misma conexión, las operaciones de escritura deberán ser serializadas por el usuario para evitar corrupción de datos.

Por defecto el módulo sqlite3 utiliza su propia clase Connection para la llamada de conexión. Sin embargo se puede crear una subclase de Connection y hacer que connect() use su clase en lugar de proveer la suya en el parámetro factory.

Consulte la sección SQLite y tipos de Python de este manual para más detalles.

El módulo sqlite3 internamente usa cache de declaraciones para evitar un análisis SQL costoso. Si se desea especificar el número de sentencias que estarán en memoria caché para la conexión, se puede configurar el parámetro cached_statements. Por defecto están configurado para 100 sentencias en memoria caché.

If uri is True, database is interpreted as a URI with a file path and an optional query string. The scheme part must be "file:". The path can be a relative or absolute file path. The query string allows us to pass parameters to SQLite. Some useful URI tricks include:

# Open a database in read-only mode.
con = sqlite3.connect("file:template.db?mode=ro", uri=True)

# Don't implicitly create a new database file if it does not already exist.
# Will raise sqlite3.OperationalError if unable to open a database file.
con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)

# Create a shared named in-memory database.
con1 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True)
con2 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True)
con1.executescript("create table t(t); insert into t values(28);")
rows = con2.execute("select * from t").fetchall()

More information about this feature, including a list of recognized parameters, can be found in the SQLite URI documentation.

Lanza un evento de auditoría sqlite3.connect con argumento database.

Distinto en la versión 3.4: Agregado el parámetro uri.

Distinto en la versión 3.7: database ahora también puede ser un path-like object, no solo una cadena de caracteres.

sqlite3.register_converter(typename, callable)¶: Registra un invocable para convertir un bytestring de la base de datos en un tipo Python personalizado. El invocable será invocado por todos los valores de la base de datos que son del tipo typename. Conceder el parámetro detect_types de la función connect() para el funcionamiento de la detección de tipo. Se debe notar que typename y el nombre del tipo en la consulta son comparados insensiblemente a mayúsculas y minúsculas.

sqlite3.register_adapter(type, callable)¶: Registra un invocable para convertir el tipo Python personalizado type a uno de los tipos soportados por SQLite’s. El invocable callable acepta un único parámetro de valor Python, y debe retornar un valor de los siguientes tipos: int, float, str or bytes.

sqlite3.complete_statement(sql)¶

Retorna True si la cadena sql contiene una o más sentencias SQL completas terminadas con punto y coma. No se verifica que la sentencia SQL sea sintácticamente correcta, solo que no existan literales de cadenas no cerradas y que la sentencia termine por un punto y coma.

Esto puede ser usado para construir un shell para SQLite, como en el siguiente ejemplo:

# A minimal SQLite shell for experiments

import sqlite3

con = sqlite3.connect(":memory:")
con.isolation_level = None
cur = con.cursor()

buffer = ""

print("Enter your SQL commands to execute in sqlite3.")
print("Enter a blank line to exit.")

while True:
    line = input()
    if line == "":
        break
    buffer += line
    if sqlite3.complete_statement(buffer):
        try:
            buffer = buffer.strip()
            cur.execute(buffer)

            if buffer.lstrip().upper().startswith("SELECT"):
                print(cur.fetchall())
        except sqlite3.Error as e:
            print("An error occurred:", e.args[0])
        buffer = ""

con.close()

sqlite3.enable_callback_tracebacks(flag)¶: Por defecto no se obtendrá ningún tracebacks en funciones definidas por el usuario, agregaciones, converters, autorizador de callbacks etc. si se quiere depurarlas, se puede llamar esta función con flag configurado a True. Después se obtendrán tracebacks de los callbacks en sys.stderr. Usar False para deshabilitar la característica de nuevo.

Objetos de conexión¶

class sqlite3.Connection¶

An SQLite database connection has the following attributes and methods:

isolation_level¶: Obtener o configurar el actual nivel de insolación. None para modo autocommit o uno de «DEFERRED», «IMMEDIATE» o «EXCLUSIVO». Ver sección Controlando Transacciones para una explicación detallada.

in_transaction¶: True si una transacción está activa (existen cambios uncommitted), False en sentido contrario. Atributo de solo lectura.

Nuevo en la versión 3.2.

cursor(factory=Cursor)¶: El método cursor acepta un único parámetro opcional factory. Si es agregado, éste debe ser un invocable que retorna una instancia de Cursor o sus subclases.

commit()¶: Este método asigna la transacción actual. Si no se llama este método, cualquier cosa hecha desde la última llamada de commit() no es visible para otras conexiones de bases de datos. Si se pregunta el porqué no se ven los datos que escribiste, por favor verifica que no olvidaste llamar este método.

rollback()¶: Este método retrocede cualquier cambio en la base de datos desde la llamada del último commit().

close()¶: Este método cierra la conexión a la base de datos. Nótese que éste no llama automáticamente commit(). Si se cierra la conexión a la base de datos sin llamar primero commit(), los cambios se perderán!

execute(sql[, parameters])¶: Create a new Cursor object and call execute() on it with the given sql and parameters. Return the new cursor object.

executemany(sql[, parameters])¶: Create a new Cursor object and call executemany() on it with the given sql and parameters. Return the new cursor object.

executescript(sql_script)¶: Create a new Cursor object and call executescript() on it with the given sql_script. Return the new cursor object.

create_function(name, num_params, func, *, deterministic=False)¶

Crea un función definida de usuario que se puede usar después desde declaraciones SQL con el nombre de función name. num_params es el número de parámetros que la función acepta (si num_params is -1, la función puede tomar cualquier número de argumentos), y func es un invocable de Python que es llamado como la función SQL. Si deterministic es verdadero, la función creada es marcada como deterministic, lo cual permite a SQLite hacer optimizaciones adicionales. Esta marca es soportada por SQLite 3.8.3 o superior, será lanzado NotSupportedError si se usa con versiones antiguas.

La función puede retornar cualquier tipo soportado por SQLite: bytes, str, int, float y None.

Distinto en la versión 3.8: El parámetro deterministic fue agregado.

Ejemplo:

import sqlite3
import hashlib

def md5sum(t):
    return hashlib.md5(t).hexdigest()

con = sqlite3.connect(":memory:")
con.create_function("md5", 1, md5sum)
cur = con.cursor()
cur.execute("select md5(?)", (b"foo",))
print(cur.fetchone()[0])

con.close()

create_aggregate(name, num_params, aggregate_class)¶

Crea una función agregada definida por el usuario.

La clase agregada debe implementar un método step, el cual acepta el número de parámetros num_params (si num_params es -1, la función puede tomar cualquier número de argumentos), y un método finalize el cual retornará el resultado final del agregado.

El método finalize puede retornar cualquiera de los tipos soportados por SQLite: bytes, str, int, float and None.

Ejemplo:

import sqlite3

class MySum:
    def __init__(self):
        self.count = 0

    def step(self, value):
        self.count += value

    def finalize(self):
        return self.count

con = sqlite3.connect(":memory:")
con.create_aggregate("mysum", 1, MySum)
cur = con.cursor()
cur.execute("create table test(i)")
cur.execute("insert into test(i) values (1)")
cur.execute("insert into test(i) values (2)")
cur.execute("select mysum(i) from test")
print(cur.fetchone()[0])

con.close()

create_collation(name, callable)¶

Crea una collation con el name y callable especificado. El invocable será pasado con dos cadenas de texto como argumentos. Se retornará -1 si el primero esta ordenado menor que el segundo, 0 si están ordenados igual y 1 si el primero está ordenado mayor que el segundo. Nótese que esto controla la ordenación (ORDER BY en SQL) por lo tanto sus comparaciones no afectan otras comparaciones SQL.

Note que el invocable obtiene sus parámetros como Python bytestrings, lo cual normalmente será codificado en UTF-8.

El siguiente ejemplo muestra una collation personalizada que ordena «La forma incorrecta»:

import sqlite3

def collate_reverse(string1, string2):
    if string1 == string2:
        return 0
    elif string1 < string2:
        return 1
    else:
        return -1

con = sqlite3.connect(":memory:")
con.create_collation("reverse", collate_reverse)

cur = con.cursor()
cur.execute("create table test(x)")
cur.executemany("insert into test(x) values (?)", [("a",), ("b",)])
cur.execute("select x from test order by x collate reverse")
for row in cur:
    print(row)
con.close()

Para remover una collation, llama create_collation con None como invocable:

con.create_collation("reverse", None)

interrupt()¶: Se puede llamar este método desde un hilo diferente para abortar cualquier consulta que pueda estar ejecutándose en la conexión. La consulta será abortada y quien realiza la llamada obtendrá una excepción.

set_authorizer(authorizer_callback)¶

Esta rutina registra un callback. El callback es invocado para cada intento de acceso a un columna de una tabla en la base de datos. El callback deberá retornar SQLITE_OK si el acceso esta permitido, SQLITE_DENY si la completa declaración SQL deberá ser abortada con un error y SQLITE_IGNORE si la columna deberá ser tratada como un valor NULL. Estas constantes están disponibles en el módulo sqlite3.

El primer argumento del callback significa que tipo de operación será autorizada. El segundo y tercer argumento serán argumentos o None dependiendo del primer argumento. El cuarto argumento es el nombre de la base de datos («main», «temp», etc.) si aplica. El quinto argumento es el nombre del disparador más interno o vista que es responsable por los intentos de acceso o None si este intento de acceso es directo desde el código SQL de entrada.

Por favor consulte la documentación de SQLite sobre los posibles valores para el primer argumento y el significado del segundo y tercer argumento dependiendo del primero. Todas las constantes necesarias están disponibles en el módulo sqlite3.

set_progress_handler(handler, n)¶

Esta rutina registra un callback. El callback es invocado para cada n instrucciones de la máquina virtual SQLite. Esto es útil si se quiere tener llamado a SQLite durante operaciones de larga duración, por ejemplo para actualizar una GUI.

Si se desea limpiar cualquier progress handler instalado previamente, llame el método con None para handler.

Retornando un valor diferente a 0 de la función gestora terminará la actual consulta en ejecución y causará lanzar una excepción OperationalError.

set_trace_callback(trace_callback)¶

Registra trace_callback para ser llamado por cada sentencia SQL que realmente se ejecute por el backend de SQLite.

The only argument passed to the callback is the statement (as str) that is being executed. The return value of the callback is ignored. Note that the backend does not only run statements passed to the Cursor.execute() methods. Other sources include the transaction management of the sqlite3 module and the execution of triggers defined in the current database.

Pasando None como trace_callback deshabilitara el trace callback.

Nota

Exceptions raised in the trace callback are not propagated. As a development and debugging aid, use enable_callback_tracebacks() to enable printing tracebacks from exceptions raised in the trace callback.

Nuevo en la versión 3.3.

enable_load_extension(enabled)¶

Esta rutina habilita/deshabilita el motor de SQLite para cargar extensiones SQLite desde bibliotecas compartidas. Las extensiones SQLite pueden definir nuevas funciones, agregaciones o una completa nueva implementación de tablas virtuales. Una bien conocida extensión es fulltext-search distribuida con SQLite.

Las extensiones cargables están deshabilitadas por defecto. Ver 1.

Nuevo en la versión 3.2.

import sqlite3

con = sqlite3.connect(":memory:")

# enable extension loading
con.enable_load_extension(True)

# Load the fulltext search extension
con.execute("select load_extension('./fts3.so')")

# alternatively you can load the extension using an API call:
# con.load_extension("./fts3.so")

# disable extension loading again
con.enable_load_extension(False)

# example from SQLite wiki
con.execute("create virtual table recipe using fts3(name, ingredients)")
con.executescript("""
    insert into recipe (name, ingredients) values ('broccoli stew', 'broccoli peppers cheese tomatoes');
    insert into recipe (name, ingredients) values ('pumpkin stew', 'pumpkin onions garlic celery');
    insert into recipe (name, ingredients) values ('broccoli pie', 'broccoli cheese onions flour');
    insert into recipe (name, ingredients) values ('pumpkin pie', 'pumpkin sugar flour butter');
    """)
for row in con.execute("select rowid, name, ingredients from recipe where name match 'pie'"):
    print(row)

con.close()

load_extension(path)¶

This routine loads an SQLite extension from a shared library. You have to enable extension loading with enable_load_extension() before you can use this routine.

Las extensiones cargables están deshabilitadas por defecto. Ver 1.

Nuevo en la versión 3.2.

row_factory¶

Se puede cambiar este atributo a un invocable que acepta el cursor y la fila original como una tupla y retornará la fila con el resultado real. De esta forma, se puede implementar más avanzadas formas de retornar resultados, tales como retornar un objeto que puede también acceder a las columnas por su nombre.

Ejemplo:

import sqlite3

def dict_factory(cursor, row):
    d = {}
    for idx, col in enumerate(cursor.description):
        d[col[0]] = row[idx]
    return d

con = sqlite3.connect(":memory:")
con.row_factory = dict_factory
cur = con.cursor()
cur.execute("select 1 as a")
print(cur.fetchone()["a"])

con.close()

Si retornado una tupla no es suficiente y se quiere acceder a las columnas basadas en nombre, se debe considerar configurar row_factory a la altamente optimizada tipo sqlite3.Row. Row provee ambos accesos a columnas basada en índice y tipado insensible con casi nada de sobrecoste de memoria. Será probablemente mejor que tú propio enfoque de basado en diccionario personalizado o incluso mejor que una solución basada en db_row.

text_factory¶

Using this attribute you can control what objects are returned for the TEXT data type. By default, this attribute is set to str and the sqlite3 module will return str objects for TEXT. If you want to return bytes instead, you can set it to bytes.

También se puede configurar a cualquier otro callable que acepte un único parámetro bytestring y retorne el objeto resultante.

Ver el siguiente ejemplo de código para ilustración:

import sqlite3

con = sqlite3.connect(":memory:")
cur = con.cursor()

AUSTRIA = "Österreich"

# by default, rows are returned as str
cur.execute("select ?", (AUSTRIA,))
row = cur.fetchone()
assert row[0] == AUSTRIA

# but we can make sqlite3 always return bytestrings ...
con.text_factory = bytes
cur.execute("select ?", (AUSTRIA,))
row = cur.fetchone()
assert type(row[0]) is bytes
# the bytestrings will be encoded in UTF-8, unless you stored garbage in the
# database ...
assert row[0] == AUSTRIA.encode("utf-8")

# we can also implement a custom text_factory ...
# here we implement one that appends "foo" to all strings
con.text_factory = lambda x: x.decode("utf-8") + "foo"
cur.execute("select ?", ("bar",))
row = cur.fetchone()
assert row[0] == "barfoo"

con.close()

total_changes¶: Regresa el número total de filas de la base de datos que han sido modificadas, insertadas o borradas desde que la conexión a la base de datos fue abierta.

iterdump()¶

Regresa un iterador para volcar la base de datos en un texto de formato SQL. Es útil cuando guardamos una base de datos en memoria para posterior restauración. Esta función provee las mismas capacidades que el comando dump en el shell sqlite3.

Ejemplo:

# Convert file existing_db.db to SQL dump file dump.sql
import sqlite3

con = sqlite3.connect('existing_db.db')
with open('dump.sql', 'w') as f:
    for line in con.iterdump():
        f.write('%s\n' % line)
con.close()

backup(target, *, pages=-1, progress=None, name="main", sleep=0.250)¶

This method makes a backup of an SQLite database even while it’s being accessed by other clients, or concurrently by the same connection. The copy will be written into the mandatory argument target, that must be another Connection instance.

Por defecto, o cuando pages es 0 o un entero negativo, la base de datos completa es copiada en un solo paso; de otra forma el método realiza un bucle copiando hasta el número de pages a la vez.

Si progress es especificado, deberá ser None o un objeto callable que será ejecutado en cada iteración con los tres argumentos enteros, respectivamente el estado status de la última iteración, el restante remaining numero de páginas presentes para ser copiadas y el número total total de páginas.

El argumento name especifica el nombre de la base de datos que será copiada: deberá ser una cadena de texto que contenga el por defecto "main", que indica la base de datos principal, "temp" que indica la base de datos temporal o el nombre especificado después de la palabra clave AS en una sentencia ATTACH DATABASE para una base de datos adjunta.

El argumento sleep especifica el número de segundos a dormir entre sucesivos intentos de respaldar páginas restantes, puede ser especificado como un entero o un valor de punto flotante.

Ejemplo 1, copiar una base de datos existente en otra:

import sqlite3

def progress(status, remaining, total):
    print(f'Copied {total-remaining} of {total} pages...')

con = sqlite3.connect('existing_db.db')
bck = sqlite3.connect('backup.db')
with bck:
    con.backup(bck, pages=1, progress=progress)
bck.close()
con.close()

Ejemplo 2: copiar una base de datos existente en una copia transitoria:

import sqlite3

source = sqlite3.connect('existing_db.db')
dest = sqlite3.connect(':memory:')
source.backup(dest)

Disponibilidad: SQLite 3.6.11 o superior

Nuevo en la versión 3.7.

Objetos Cursor¶

class sqlite3.Cursor¶

Una instancia de Cursor tiene los siguientes atributos y métodos.

execute(sql[, parameters])¶

Executes an SQL statement. Values may be bound to the statement using placeholders.

execute() solo ejecutará una única sentencia SQL. Si se trata de ejecutar más de una sentencia con el, lanzará un Warning. Usar executescript() si se quiere ejecutar múltiples sentencias SQL con una llamada.

executemany(sql, seq_of_parameters)¶

Executes a parameterized SQL command against all parameter sequences or mappings found in the sequence seq_of_parameters. The sqlite3 module also allows using an iterator yielding parameters instead of a sequence.

import sqlite3

class IterChars:
    def __init__(self):
        self.count = ord('a')

    def __iter__(self):
        return self

    def __next__(self):
        if self.count > ord('z'):
            raise StopIteration
        self.count += 1
        return (chr(self.count - 1),) # this is a 1-tuple

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.execute("create table characters(c)")

theIter = IterChars()
cur.executemany("insert into characters(c) values (?)", theIter)

cur.execute("select c from characters")
print(cur.fetchall())

con.close()

Acá un corto ejemplo usando un generator:

import sqlite3
import string

def char_generator():
    for c in string.ascii_lowercase:
        yield (c,)

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.execute("create table characters(c)")

cur.executemany("insert into characters(c) values (?)", char_generator())

cur.execute("select c from characters")
print(cur.fetchall())

con.close()

executescript(sql_script)¶

This is a nonstandard convenience method for executing multiple SQL statements at once. It issues a COMMIT statement first, then executes the SQL script it gets as a parameter. This method disregards isolation_level; any transaction control must be added to sql_script.

sql_script puede ser una instancia de str.

Ejemplo:

import sqlite3

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.executescript("""
    create table person(
        firstname,
        lastname,
        age
    );

    create table book(
        title,
        author,
        published
    );

    insert into book(title, author, published)
    values (
        'Dirk Gently''s Holistic Detective Agency',
        'Douglas Adams',
        1987
    );
    """)
con.close()

fetchone()¶: Obtiene la siguiente fila de un conjunto resultado, retorna una única secuencia, o None cuando no hay más datos disponibles.

fetchmany(size=cursor.arraysize)¶

Obtiene el siguiente conjunto de filas del resultado de una consulta, retornando una lista. Una lista vacía es retornada cuando no hay más filas disponibles.

El número de filas a obtener por llamado es especificado por el parámetro size. Si no es suministrado, el arraysize del cursor determina el número de filas a obtener. El método debería intentar obtener tantas filas como las indicadas por el parámetro size. Si esto no es posible debido a que el número especificado de filas no está disponible, entonces menos filas deberán ser retornadas.

Nótese que hay consideraciones de desempeño involucradas con el parámetro size. Para un optimo desempeño, es usualmente mejor usar el atributo arraysize. Si el parámetro size es usado, entonces es mejor retener el mismo valor de una llamada fetchmany() a la siguiente.

fetchall()¶: Obtiene todas las filas (restantes) del resultado de una consulta. Nótese que el atributo arraysize del cursor puede afectar el desempeño de esta operación. Una lista vacía será retornada cuando no hay filas disponibles.

close()¶

Cierra el cursor ahora (en lugar que cuando __del__ es llamado)

El cursor no será usable de este punto en adelante; una excepción ProgrammingError será lanzada si se intenta cualquier operación con el cursor.

setinputsizes(sizes)¶: Required by the DB-API. Does nothing in sqlite3.

setoutputsize(size[, column])¶: Required by the DB-API. Does nothing in sqlite3.

rowcount¶

A pesar de que la clase Cursor del módulo sqlite3 implementa este atributo, el propio soporte del motor de base de datos para la determinación de «filas afectadas»/»filas seleccionadas» es raro.

Para sentencias executemany(), el número de modificaciones se resumen en rowcount.

Cómo lo requiere la especificación Python DB API, el atributo rowcount «es -1 en caso de que executeXX() no haya sido ejecutada en el cursor o en el rowcount de la última operación no haya sido determinada por la interface». Esto incluye sentencias SELECT porque no podemos determinar el número de filas que una consulta produce hasta que todas las filas sean obtenidas.

Con versiones de SQLite anteriores a 3.6.5, rowcount es configurado a 0 si se hace un DELETE FROM table sin ninguna condición.

lastrowid¶: This read-only attribute provides the row id of the last inserted row. It is only updated after successful INSERT or REPLACE statements using the execute() method. For other statements, after executemany() or executescript(), or if the insertion failed, the value of lastrowid is left unchanged. The initial value of lastrowid is None.

Nota

Inserts into WITHOUT ROWID tables are not recorded.

Distinto en la versión 3.6: Se agregó soporte para sentencias REPLACE.

arraysize¶: Atributo de lectura/escritura que controla el número de filas retornadas por fetchmany(). El valor por defecto es 1, lo cual significa que una única fila será obtenida por llamada.

description¶

Este atributo de solo lectura provee el nombre de las columnas de la última consulta. Para ser compatible con Python DB API, retorna una 7-tupla para cada columna en donde los últimos seis ítems de cada tupla son None.

También es configurado para sentencias SELECT sin ninguna fila coincidente.

connection¶

Este atributo de solo lectura provee la Connection de la base de datos SQLite usada por el objeto Cursor. Un objeto Cursor creado por la llamada de con.cursor() tendrá un atributo connection que se refiere a con:

>>> con = sqlite3.connect(":memory:")
>>> cur = con.cursor()
>>> cur.connection == con
True

Objetos Fila (Row)¶

class sqlite3.Row¶

Una instancia Row sirve como una altamente optimizada row_factory para objetos Connection. Esta trata de imitar una tupla en su mayoría de características.

Soporta acceso mapeado por nombre de columna e índice, iteración, representación, pruebas de igualdad y len().

Si dos objetos Row tienen exactamente las mismas columnas y sus miembros son iguales, entonces se comparan a igual.

keys()¶: Este método retorna una lista con los nombre de columnas. Inmediatamente después de una consulta, es el primer miembro de cada tupla en Cursor.description.

Distinto en la versión 3.5: Agrega soporte de segmentación.

Vamos a asumir que se inicializa una tabla como en el ejemplo dado:

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.execute('''create table stocks
(date text, trans text, symbol text,
 qty real, price real)''')
cur.execute("""insert into stocks
            values ('2006-01-05','BUY','RHAT',100,35.14)""")
con.commit()
cur.close()

Ahora conectamos Row en:

>>> con.row_factory = sqlite3.Row
>>> cur = con.cursor()
>>> cur.execute('select * from stocks')
<sqlite3.Cursor object at 0x7f4e7dd8fa80>
>>> r = cur.fetchone()
>>> type(r)
<class 'sqlite3.Row'>
>>> tuple(r)
('2006-01-05', 'BUY', 'RHAT', 100.0, 35.14)
>>> len(r)
5
>>> r[2]
'RHAT'
>>> r.keys()
['date', 'trans', 'symbol', 'qty', 'price']
>>> r['qty']
100.0
>>> for member in r:
...     print(member)
...
2006-01-05
BUY
RHAT
100.0
35.14

Excepciones¶

exception sqlite3.Warning¶: Una subclase de Exception.

exception sqlite3.Error¶: La clase base de otras excepciones en este módulo. Es una subclase de Exception.

exception sqlite3.DatabaseError¶: Excepción lanzada para errores que están relacionados con la base de datos.

exception sqlite3.IntegrityError¶: Excepción lanzada cuando la integridad de la base de datos es afectada, por ejemplo la comprobación de una llave foránea falla. Es una subclase de DatabaseError.

exception sqlite3.ProgrammingError¶: Excepción lanzada por errores de programación, e.g. tabla no encontrada o ya existente, error de sintaxis en la sentencia SQL, número equivocado de parámetros especificados, etc. Es una subclase de DatabaseError.

exception sqlite3.OperationalError¶: Excepción lanzada por errores relacionados por la operación de la base de datos y no necesariamente bajo el control del programador, por ejemplo ocurre una desconexión inesperada, el nombre de la fuente de datos no es encontrado, una transacción no pudo ser procesada, etc. Es una subclase de DatabaseError.

exception sqlite3.NotSupportedError¶: Excepción lanzada en caso de que un método o API de base de datos fuera usada en una base de datos que no la soporta, e.g. llamando el método rollback() en una conexión que no soporta la transacción o tiene deshabilitada las transacciones. Es una subclase de DatabaseError.

SQLite y tipos de Python¶

Introducción¶

SQLite soporta de forma nativa los siguientes tipos: NULL, INTEGER, REAL, TEXT, BLOB.

Los siguientes tipos de Python se pueden enviar a SQLite sin problema alguno:

Tipo de Python	Tipo de SQLite
`None`	`NULL`
`int`	`INTEGER`
`float`	`REAL`
`str`	`TEXT`
`bytes`	`BLOB`

De esta forma es como los tipos de SQLite son convertidos a tipos de Python por defecto:

Tipo de SQLite	Tipo de Python
`NULL`	`None`
`INTEGER`	`int`
`REAL`	`float`
`TEXT`	depende de `text_factory`, `str` por defecto
`BLOB`	`bytes`

The type system of the sqlite3 module is extensible in two ways: you can store additional Python types in an SQLite database via object adaptation, and you can let the sqlite3 module convert SQLite types to different Python types via converters.

Usando adaptadores para almacenar tipos adicionales de Python en bases de datos SQLite¶

Como se describió anteriormente, SQLite soporta solamente un conjunto limitado de tipos de forma nativa. Para usar otros tipos de Python con SQLite, se deben adaptar a uno de los tipos de datos soportados por el módulo sqlite3 para SQLite: uno de NoneType, int, float, str, bytes.

Hay dos formas de habilitar el módulo sqlite3 para adaptar un tipo personalizado de Python a alguno de los admitidos.

Permitiéndole al objeto auto adaptarse¶

Este es un buen enfoque si uno mismo escribe la clase. Vamos a suponer que se tiene una clase como esta:

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

Ahora desea almacenar el punto en una sola columna de SQLite. Primero tendrá que elegir uno de los tipos admitidos que se utilizará para representar el punto. Usemos str y separemos las coordenadas usando un punto y coma. Luego, debe darle a su clase un método __conform __(self, protocol) que debe retornar el valor convertido. El parámetro protocol será PrepareProtocol.

import sqlite3

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

    def __conform__(self, protocol):
        if protocol is sqlite3.PrepareProtocol:
            return "%f;%f" % (self.x, self.y)

con = sqlite3.connect(":memory:")
cur = con.cursor()

p = Point(4.0, -3.2)
cur.execute("select ?", (p,))
print(cur.fetchone()[0])

con.close()

Registrando un adaptador invocable¶

La otra posibilidad es crear una función que convierta el escrito a representación de cadena de texto y registrar la función con register_adapter().

import sqlite3

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

def adapt_point(point):
    return "%f;%f" % (point.x, point.y)

sqlite3.register_adapter(Point, adapt_point)

con = sqlite3.connect(":memory:")
cur = con.cursor()

p = Point(4.0, -3.2)
cur.execute("select ?", (p,))
print(cur.fetchone()[0])

con.close()

El módulo sqlite3 tiene dos adaptadores por defecto para las funciones integradas de Python datetime.date y tipos datetime.datetime. Ahora vamos a suponer que queremos almacenar objetos datetime.datetime no en representación ISO, sino como una marca de tiempo Unix.

import sqlite3
import datetime
import time

def adapt_datetime(ts):
    return time.mktime(ts.timetuple())

sqlite3.register_adapter(datetime.datetime, adapt_datetime)

con = sqlite3.connect(":memory:")
cur = con.cursor()

now = datetime.datetime.now()
cur.execute("select ?", (now,))
print(cur.fetchone()[0])

con.close()

Convertir valores SQLite a tipos de Python personalizados¶

Escribir un adaptador permite enviar escritos personalizados de Python a SQLite. Pero para hacer esto realmente útil, tenemos que hace el flujo Python a SQLite a Python.

Ingresar convertidores.

Regresemos a la clase Point. Se almacena las coordenadas x e y de forma separada por punto y coma como una cadena de texto en SQLite.

Primero, se define una función de conversión que acepta la cadena de texto como un parámetro y construye un objeto Point de ahí.

Nota

Las funciones de conversión siempre son llamadas con un objeto bytes, no importa bajo qué tipo de dato se envió el valor a SQLite.

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

Ahora se necesita hacer que el módulo sqlite3 conozca que lo que tu seleccionaste de la base de datos es de hecho un punto. Hay dos formas de hacer esto:

Implícitamente vía el tipo declarado
Explícitamente vía el nombre de la columna

Ambas formas están descritas en la sección Funciones y constantes del módulo, en las entradas para las constantes PARSE_DECLTYPES y PARSE_COLNAMES.

El siguiente ejemplo ilustra ambos enfoques.

import sqlite3

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

    def __repr__(self):
        return "(%f;%f)" % (self.x, self.y)

def adapt_point(point):
    return ("%f;%f" % (point.x, point.y)).encode('ascii')

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

# Register the adapter
sqlite3.register_adapter(Point, adapt_point)

# Register the converter
sqlite3.register_converter("point", convert_point)

p = Point(4.0, -3.2)

#########################
# 1) Using declared types
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES)
cur = con.cursor()
cur.execute("create table test(p point)")

cur.execute("insert into test(p) values (?)", (p,))
cur.execute("select p from test")
print("with declared types:", cur.fetchone()[0])
cur.close()
con.close()

#######################
# 1) Using column names
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)
cur = con.cursor()
cur.execute("create table test(p)")

cur.execute("insert into test(p) values (?)", (p,))
cur.execute('select p as "p [point]" from test')
print("with column names:", cur.fetchone()[0])
cur.close()
con.close()

Adaptadores y convertidores por defecto¶

Hay adaptadores por defecto para los tipos date y datetime en el módulo datetime. Éstos serán enviados como fechas/marcas de tiempo ISO a SQLite.

Los convertidores por defecto están registrados bajo el nombre «date» para datetime.date y bajo el mismo nombre para «timestamp» para datetime.datetime.

De esta forma, se puede usar date/timestamps para Python sin ajuste adicional en la mayoría de los casos. El formato de los adaptadores también es compatible con las funciones experimentales de SQLite date/time.

El siguiente ejemplo demuestra esto.

import sqlite3
import datetime

con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES|sqlite3.PARSE_COLNAMES)
cur = con.cursor()
cur.execute("create table test(d date, ts timestamp)")

today = datetime.date.today()
now = datetime.datetime.now()

cur.execute("insert into test(d, ts) values (?, ?)", (today, now))
cur.execute("select d, ts from test")
row = cur.fetchone()
print(today, "=>", row[0], type(row[0]))
print(now, "=>", row[1], type(row[1]))

cur.execute('select current_date as "d [date]", current_timestamp as "ts [timestamp]"')
row = cur.fetchone()
print("current_date", row[0], type(row[0]))
print("current_timestamp", row[1], type(row[1]))

con.close()

Si un timestamp almacenado en SQLite tiene una parte fraccional mayor a 6 números, este valor será truncado a precisión de microsegundos por el convertidor de timestamp.

Nota

The default «timestamp» converter ignores UTC offsets in the database and always returns a naive datetime.datetime object. To preserve UTC offsets in timestamps, either leave converters disabled, or register an offset-aware converter with register_converter().

Controlando Transacciones¶

La librería subyacente sqlite3 opera en modo autocommit por defecto, pero el módulo de Python sqlite3 no.

El modo autocommit significa que la sentencias que modifican la base de datos toman efecto de forma inmediata. Una sentencia BEGIN o SAVEPOINT deshabilitan el modo autocommit, y un COMMIT, un ROLLBACK, o un RELEASE que terminan la transacción más externa, habilitan de nuevo el modo autocommit.

El módulo de Python sqlite3 emite por defecto una sentencia BEGIN implícita antes de una sentencia tipo Lenguaje Manipulación de Datos (DML) (es decir INSERT/UPDATE/DELETE/REPLACE).

Se puede controlar en qué tipo de sentencias BEGIN sqlite3 implícitamente ejecuta vía el parámetro insolation_level a la función de llamada connect(), o vía las propiedades de conexión isolation_level. Si no se especifica isolation_level, se usa un plano BEGIN, el cuál es equivalente a especificar DEFERRED. Otros posibles valores son IMMEDIATE and EXCLUSIVE.

Se puede deshabilitar la gestión implícita de transacciones del módulo sqlite3 con la configuración isolation_level a None. Esto dejará la subyacente biblioteca operando en modo autocommit. Se puede controlar completamente el estado de la transacción emitiendo explícitamente sentencias BEGIN, ROLLBACK, SAVEPOINT, y RELEASE en el código.

Note that executescript() disregards isolation_level; any transaction control must be added explicitly.

Distinto en la versión 3.6: sqlite3 solía realizar commit en transacciones implícitamente antes de sentencias DDL. Este ya no es el caso.

Usando `sqlite3` eficientemente¶

Usando métodos atajo¶

Usando los métodos no estándar execute(), executemany() y executescript() del objeto Connection, el código puede ser escrito más consistentemente porque no se tienen que crear explícitamente los (a menudo superfluos) objetos Cursor. En cambio, los objetos de Cursor son creados implícitamente y estos métodos atajo retornan los objetos cursor. De esta forma, se puede ejecutar una sentencia SELECT e iterar directamente sobre él, solamente usando una única llamada al objeto Connection.

import sqlite3

langs = [
    ("C++", 1985),
    ("Objective-C", 1984),
]

con = sqlite3.connect(":memory:")

# Create the table
con.execute("create table lang(name, first_appeared)")

# Fill the table
con.executemany("insert into lang(name, first_appeared) values (?, ?)", langs)

# Print the table contents
for row in con.execute("select name, first_appeared from lang"):
    print(row)

print("I just deleted", con.execute("delete from lang").rowcount, "rows")

# close is not a shortcut method and it's not called automatically,
# so the connection object should be closed manually
con.close()

Accediendo a las columnas por el nombre en lugar del índice¶

Una característica útil del módulo sqlite3 es la clase incluida sqlite3.Row diseñada para ser usada como una fábrica de filas.

Filas envueltas con esta clase pueden ser accedidas tanto por índice (al igual que tuplas) como por nombre insensible a mayúsculas o minúsculas:

import sqlite3

con = sqlite3.connect(":memory:")
con.row_factory = sqlite3.Row

cur = con.cursor()
cur.execute("select 'John' as name, 42 as age")
for row in cur:
    assert row[0] == row["name"]
    assert row["name"] == row["nAmE"]
    assert row[1] == row["age"]
    assert row[1] == row["AgE"]

con.close()

Usando la conexión como un administrador de contexto¶

Los objetos de conexión pueden ser usados como administradores de contexto que automáticamente transacciones commit o rollback. En el evento de una excepción, la transacción es retrocedida; de otra forma, la transacción es confirmada:

import sqlite3

con = sqlite3.connect(":memory:")
con.execute("create table lang (id integer primary key, name varchar unique)")

# Successful, con.commit() is called automatically afterwards
with con:
    con.execute("insert into lang(name) values (?)", ("Python",))

# con.rollback() is called after the with block finishes with an exception, the
# exception is still raised and must be caught
try:
    with con:
        con.execute("insert into lang(name) values (?)", ("Python",))
except sqlite3.IntegrityError:
    print("couldn't add Python twice")

# Connection object used as context manager only commits or rollbacks transactions,
# so the connection object should be closed manually
con.close()

Notas al pie

1(1,2): The sqlite3 module is not built with loadable extension support by default, because some platforms (notably macOS) have SQLite libraries which are compiled without this feature. To get loadable extension support, you must pass --enable-loadable-sqlite-extensions to configure.

`sqlite3` — DB-API 2.0 interfaz para bases de datos SQLite¶

Funciones y constantes del módulo¶

Objetos de conexión¶

Objetos Cursor¶

Objetos Fila (Row)¶

Excepciones¶

SQLite y tipos de Python¶

Introducción¶

Usando adaptadores para almacenar tipos adicionales de Python en bases de datos SQLite¶

Permitiéndole al objeto auto adaptarse¶

Registrando un adaptador invocable¶

Convertir valores SQLite a tipos de Python personalizados¶

Adaptadores y convertidores por defecto¶

Controlando Transacciones¶

Usando `sqlite3` eficientemente¶

Usando métodos atajo¶

Accediendo a las columnas por el nombre en lugar del índice¶

Usando la conexión como un administrador de contexto¶

Tabla de contenido

Tema anterior

Próximo tema

Esta página

sqlite3 — DB-API 2.0 interfaz para bases de datos SQLite¶

Funciones y constantes del módulo¶

Objetos de conexión¶

Objetos Cursor¶

Objetos Fila (Row)¶

Excepciones¶

SQLite y tipos de Python¶

Introducción¶

Usando adaptadores para almacenar tipos adicionales de Python en bases de datos SQLite¶

Permitiéndole al objeto auto adaptarse¶

Registrando un adaptador invocable¶

Convertir valores SQLite a tipos de Python personalizados¶

Adaptadores y convertidores por defecto¶

Controlando Transacciones¶

Usando sqlite3 eficientemente¶

Usando métodos atajo¶

Accediendo a las columnas por el nombre en lugar del índice¶

Usando la conexión como un administrador de contexto¶

`sqlite3` — DB-API 2.0 interfaz para bases de datos SQLite¶

Usando `sqlite3` eficientemente¶