Nota

¡Ayúdanos a traducir la documentación oficial de Python al Español! Puedes encontrar más información en Como contribuir. Ayuda a acercar Python a más personas de habla hispana.

`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.

El módulo sqlite3 fue escrito por Gerhard Häring. Proporciona una interfaz SQL compatible con la especificación DB-API 2.0 descrita por PEP 249 y requiere SQLite 3.7.15 o posterior.

Esta documentación contiene cuatro secciones principales:

Tutorial enseña como usar el módulo sqlite3 module.
Referencia describe las clases y funciones que se definen en este módulo.
Guías prácticas detalla como manipular tareas específicas.
Explicación proporciona en profundidad información sobre el control transaccional.

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.

Tutorial¶

En este tutorial, será creada una base de datos de películas Monty Python usando funcionalidades básicas de sqlite3. Se asume un entendimiento fundamental de conceptos de bases de dados, como cursors y transactions.

Primero, necesitamos crear una nueva base de datos y abrir una conexión para que sqlite3 trabaje con ella. Llamando sqlite3.connect() se creará una conexión con la base de datos tutorial.db en el directorio actual, y de no existir, se creará automáticamente:

import sqlite3
con = sqlite3.connect("tutorial.db")

El retorno será un objecto de la clase Connection representado en con como una base de datos local.

Con el fin de ejecutar sentencias SQL y obtener resultados de consultas SQL, necesitaremos usar un cursor para la base de datos. Llamando con.cursor() se creará el Cursor:

cur = con.cursor()

Ahora que hemos configurado una conexión y un cursor, podemos crear una tabla movie con las columnas title, release year, y review score. Para simplificar, podemos solamente usar nombres de columnas en la declaración de la tabla – gracias al recurso de flexible typing SQLite, especificar los tipos de datos es opcional. Ejecuta la sentencia CREATE TABLE llamando cur.execute(...):

cur.execute("CREATE TABLE movie(title, year, score)")

Podemos verificar que una nueva tabla ha sido creada consultando la tabla sqlite_master incorporada en SQLite, la cual ahora debería contener una entrada para la tabla movie (consulte The Schema Table para más información). Ejecute esa consulta llamando a cur.execute(...), asigne el resultado a res y llame a res.fetchone() para obtener la fila resultante:

>>> res = cur.execute("SELECT name FROM sqlite_master")
>>> res.fetchone()
('movie',)

Podemos observar que la tabla ha sido creada, ya que la consulta retorna una tuple conteniendo los nombres de la tabla. Si consultamos sqlite_master para una tabla no existente spam, res.fetchone() retornará None:

>>> res = cur.execute("SELECT name FROM sqlite_master WHERE name='spam'")
>>> res.fetchone() is None
True

Ahora, agrega dos filas de datos proporcionados como SQL literales, ejecutando la sentencia INSERT, una vez más llamando a cur.execute(...):

cur.execute("""
    INSERT INTO movie VALUES
        ('Monty Python and the Holy Grail', 1975, 8.2),
        ('And Now for Something Completely Different', 1971, 7.5)
""")

La sentencia INSERT implícitamente abre una transacción, la cual necesita ser confirmada antes que los cambios sean guardados en la base de datos (consulte Control transaccional para más información). Llamando a con.commit() sobre el objeto de la conexión, se confirmará la transacción:

con.commit()

Podemos verificar que la información fue introducida correctamente ejecutando la consulta SELECT. Ejecute el ahora conocido cur.execute(...) para asignar el resultado a res, y luego llame a res.fetchall() para obtener todas las filas como resultado:

>>> res = cur.execute("SELECT score FROM movie")
>>> res.fetchall()
[(8.2,), (7.5,)]

El resultado es una list de dos tuples, una por fila, cada una conteniendo el valor del score de esa fila.

Ahora, introduzca tres filas más llamando cur.executemany(...):

data = [
    ("Monty Python Live at the Hollywood Bowl", 1982, 7.9),
    ("Monty Python's The Meaning of Life", 1983, 7.5),
    ("Monty Python's Life of Brian", 1979, 8.0),
]
cur.executemany("INSERT INTO movie VALUES(?, ?, ?)", data)
con.commit()  # Remember to commit the transaction after executing INSERT.

Note que los marcadores de posición ? son usados para enlazar data a la consulta. SIempre use marcadores de posición en lugar de string formatting para unir valores Python a sentencias SQL, y así evitará SQL injection attacks (consulte Cómo usar marcadores de posición para vincular valores en consultas SQL para más información).

Podemos verificar que las nuevas filas fueron introducidas ejecutando una consulta SELECT, esta vez iterando sobre los resultados de la consulta:

>>> for row in cur.execute("SELECT year, title FROM movie ORDER BY year"):
...     print(row)
(1971, 'And Now for Something Completely Different')
(1975, 'Monty Python and the Holy Grail')
(1979, "Monty Python's Life of Brian")
(1982, 'Monty Python Live at the Hollywood Bowl')
(1983, "Monty Python's The Meaning of Life")

Cada fila es una tuple de dos items con (year, title), donde las columnas seleccionadas coinciden con la consulta.

Finalmente, se puede verificar que la base de datos ha sido escrita en disco, llamando con.close() para cerrar la conexión existente, abriendo una nueva, creando un nuevo cursor y luego consultando la base de datos:

>>> con.close()
>>> new_con = sqlite3.connect("tutorial.db")
>>> new_cur = new_con.cursor()
>>> res = new_cur.execute("SELECT title, year FROM movie ORDER BY score DESC")
>>> title, year = res.fetchone()
>>> print(f'The highest scoring Monty Python movie is {title!r}, released in {year}')
The highest scoring Monty Python movie is 'Monty Python and the Holy Grail', released in 1975

Ahora ha creado una base de datos SQLite usando el módulo sqlite3, insertado datos y recuperado valores de varias maneras.

Ver también

Guías prácticas para lecturas de interés:
Explicación para obtener información detallada sobre el control de transacciones..

Referencia¶

Funciones del módulo¶

sqlite3.connect(database, timeout=5.0, detect_types=0, isolation_level='DEFERRED', check_same_thread=True, factory=sqlite3.Connection, cached_statements=128, uri=False)¶

Abre una conexión con una base de datos SQLite.

Parámetros

database (path-like object) – La ruta al archivo de la base de datos que se pretende abrir. Pasa ":memory:" para abrir la conexión con la base de datos en memoria RAM en lugar de el disco local.
timeout (float) – Cuántos segundos la conexión debe esperar antes de lanzar una excepción si la base de datos está bloqueada por otra conexión. Si otra conexión abre una transacción para alterar la base de datos, será bloqueada antes que la transacción sea confirmada. Por defecto son 5 segundos.
detect_types (int) – Controla si y cómo los tipos de datos no soportados de forma nativa po SQLite son buscados para ser convertidos en tipos Python, usando convertidores registrados con register_converter(). Se puede establecer para cualquier combinación (usando |, bit a bit or) de PARSE_DECLTYPES y PARSE_COLNAMES para habilitarlo. Los nombres de columnas tienen prioridad sobre los tipos declarados si se establecen ambos indicadores. Algunos tipos no pueden ser detectados por campos generados (por ejemplo max(data)), incluso cuando el parámetro detect_types es establecido; str será el retorno en su lugar. Por defecto (0), la detección de tipos está deshabilitada.
isolation_level (str | None) – El isolation_level de la conexión, controla si y cómo las transacciones son implícitamente abiertas. Puede ser "DEFERRED" (por defecto), "EXCLUSIVE" o "IMMEDIATE"; o None para deshabilitar transacciones abiertas implícitamente. Consulte Control transaccional para más información.
check_same_thread (bool) – Si es True (por defecto), sólo el hilo creador puede utilizar la conexión. Si es False, la conexión se puede compartir entre varios hilos; de ser así, las operaciones de escritura deben ser serializadas por el usuario para evitar daños en los datos.
factory (Connection) – Una subclase personalizada de Connection con la que crear la conexión, sino la Connection será la predeterminada.
cached_statements (int) – El número de instrucciones que sqlite3 debe almacenar internamente en caché para esta conexión, para evitar la sobrecarga de análisis. El valor predeterminada, son 128 instrucciones.
uri (bool) – Si se establece en True, database es interpretada como una URI con la ruta de un archivo y una consulta de cadena de caracteres de modo opcional. La parte del esquema debe ser "file:", y la ruta puede ser relativa o absoluta. La consulta permite pasar parámetros a SQLite, habilitando varias Como trabajar con URIs SQLite.

Tipo del valor devuelto

Connection

Lanza un auditing event sqlite3.connect con el argumento database.

Lanza un auditing event sqlite3.connect/handle con el argumento connection_handle.

Nuevo en la versión 3.4: 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.

Nuevo en la versión 3.10: El evento de auditoría sqlite3.connect/handle.

sqlite3.complete_statement(statement)¶

Retorna True si la cadena de caracteres statement pareciera contener uno o más sentencias SQL completas. No se realiza ninguna verificación o análisis sintáctico de ningún tipo, aparte de comprobar que no hay cadena de caracteres literales sin cerrar y que la sentencia se termine con un punto y coma.

Por ejemplo:

>>> sqlite3.complete_statement("SELECT foo FROM bar;")
True
>>> sqlite3.complete_statement("SELECT foo")
False

Esta función puede ser útil con entradas de línea de comando para determinar si los textos introducidos parecen formar una sentencia completa SQL, o si una entrada adicional se necesita antes de llamar a execute().

sqlite3.enable_callback_tracebacks(flag, /)¶

Habilita o deshabilita seguimiento de retrollamadas. Por defecto no se obtendrá ningún tracebacks en funciones aggregates, converters, autorizador de callbacks etc, definidas por el usuario. Si quieres depurarlas, se puede llamar esta función con flag establecida como True. Después se obtendrán tracebacks de los callbacks en sys.stderr. Usar False para deshabilitar la característica de nuevo.

Registra una unraisable hook handler para una experiencia de depuración mejorada:

>>> sqlite3.enable_callback_tracebacks(True)
>>> con = sqlite3.connect(":memory:")
>>> def evil_trace(stmt):
...     5/0
>>> con.set_trace_callback(evil_trace)
>>> def debug(unraisable):
...     print(f"{unraisable.exc_value!r} in callback {unraisable.object.__name__}")
...     print(f"Error message: {unraisable.err_msg}")
>>> import sys
>>> sys.unraisablehook = debug
>>> cur = con.execute("SELECT 1")
ZeroDivisionError('division by zero') in callback evil_trace
Error message: None

sqlite3.register_adapter(type, adapter, /)¶: Registra un adapter invocable para adaptar el tipo de Python type en un tipo SQLite. El adaptador se llama con un objeto python de tipo type como único argumento, y debe retornar un valor de un tipo que SQLite entiende de forma nativa.

sqlite3.register_converter(typename, converter, /)¶

Registra el converter invocable para convertir objetos SQLite de tipo typename en objetos Python de un tipo en específico. El converter se invoca por todos los valores SQLite que sean de tipo typename; es pasado un objeto de bytes y debería retornar un objeto Python del tipo deseado. Consulte el parámetro detect_types de connect() para más información en cuanto a cómo funciona la detección de tipos.

Nota: typename y el nombre del tipo en tu consulta coinciden sin distinción entre mayúsculas y minúsculas.

Constantes del módulo¶

sqlite3.PARSE_COLNAMES¶

Pasa este valor de flag como parámetro detect_types de la connect() para buscar una función converter usando el nombre del tipo, analizado del nombre de la columna consultada, como la llave de diccionario del conversor. El nombre del tipo debe estar entre corchetes ([]).

SELECT p as "p [point]" FROM test;  ! will look up converter "point"

Esta flag puede ser combinada con PARSE_DECLTYPES usando el operador | (bitwise or) .

sqlite3.PARSE_DECLTYPES¶

Pasa este valor de flag como parámetro detect_types de la connect() para buscar una función converter usando los tipos declarados para cada columna. Los tipos son declarados cuando la tabla de la base de datos se creó. sqlite3 buscará una función converter usando la primera palabra del tipo declarado como la llave del diccionario conversor. Por ejemplo:

CREATE TABLE test(
   i integer primary key,  ! will look up a converter named "integer"
   p point,                ! will look up a converter named "point"
   n number(10)            ! will look up a converter named "number"
 )

Esta puede ser combinada con PARSE_COLNAMES usando el operador | (bitwise or).

sqlite3.SQLITE_OK¶

sqlite3.SQLITE_DENY¶

sqlite3.SQLITE_IGNORE¶

Flags que deben ser retornadas por el invocable authorizer_callback que se le pasa a Connection.set_authorizer(), para indicar lo siguiente:

Acceso es permitido (SQLITE_OK),
La sentencia SQL debería ser abortada con un error (SQLITE_DENY)
La columna debería ser tratada como un valor NULL (SQLITE_IGNORE)

sqlite3.apilevel¶: Cadena de caracteres constante que indica el nivel DB-API soportado. Requerido por DB-API. Codificado de forma rígida en "2.0".

sqlite3.paramstyle¶: Cadena de caracteres que indica el tipo de formato del marcador de parámetros esperado por el módulo sqlite3. Requerido por DB-API. Codificado de forma rígida en "qmark".

Nota

El módulo sqlite3 soporta los parámetros de estilo DB-API qmark y numeric, porque eso es lo que admite la biblioteca. Sin embargo, la DB-API no permite varios valores para el atributo paramstyle.

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¶

Constante de tipo entero requerida por la DB-API 2.0, la cual indica el nivel de seguridad de subproceso que sqlite3 soporta. Este atributo se establece basándose en el modo de subprocesamiento por defecto con el que la biblioteca SQLite se compila. Los modos de subprocesamiento de SQLite son:

Single-thread: En este modo, todos los mutexes son deshabilitados y no es seguro usar SQLite en más de un solo hilo a la vez.

Multi-thread: En este modo, es seguro usar SQLite desde varios hilos dado que que ninguna conexión de base de datos sea usada simultáneamente en dos o más hilos.

Serialized: En el modo serializado, es seguro usar SQLite por varios hilos sin restricción.

Las asignaciones de los modos de subprocesos SQLite a los niveles de seguridad de subprocesos de DB-API 2.0 son las siguientes:

Modo de subprocesamiento SQLite	threadsafety	SQLITE_THREADSAFE	Significado de DB-API 2.0
single-thread	0	0	Hilos no pueden compartir el módulo
multi-thread	1	2	Hilos pueden compartir el módulo, pero no conexiones
serialized	3	1	Hilos pueden compartir el módulo, conexiones y cursores

Distinto en la versión 3.11: Establece threadsafety dinámicamente en vez de codificarlo rígidamente a 1.

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.

Objetos de conexión¶

class sqlite3.Connection¶

Cada base de datos SQLite abierta es representada por un objeto Connection, el cual se crea usando sqlite3.connect(). Su objetivo principal es crear objetos Cursor, y Control transaccional.

Ver también

Cómo utilizar los métodos de acceso directo de conexión
Como usar la conexión con un administrador de contexto

Una conexión a una base de datos SQLite tiene los siguientes atributos y métodos:

cursor(factory=Cursor)¶: Crea y retorna un objeto 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.

blobopen(table, column, row, /, \*, readonly=False, name="main")¶

Abre una Blob para manejar un BLOB existente.

Parámetros

table (str) – El nombre de la tabla donde el blob está ubicado.
column (str) – El nombre de la columna donde el blob está ubicado.
row (str) – El nombre de la fila donde el blob está ubicado.
readonly (bool) – Se define como True si el blob deberá ser abierto sin permisos de escritura. El valor por defecto es False.
name (str) – El nombre de la base de datos donde el blob está ubicado. El valor por defecto es "main".

Muestra

OperationalError – Cuando se intenta abrir un blob en una tabla WITHOUT ROWID.

Tipo del valor devuelto

Blob

Nota

El tamaño de un blob no puede ser cambiado usando la clase Blob. Usa la función de SQL zeroblob para crear un blob con un tamaño fijo.

Nuevo en la versión 3.11.

commit()¶: Guarda cualquier transacción pendiente en la base de datos. Si no hay transacciones abiertas, este método es un no-op.

rollback()¶: Restaura a su comienzo, cualquier transacción pendiente. Si no hay transacciones abiertas, este método es un no-op.

close()¶: Cierra la conexión con la base de datos, y si hay alguna transacción pendiente, esta no será guardada; asegúrese de commit() antes de cerrar la conexión, para evitar perder los cambios realizados.

execute(sql, parameters=(), /)¶: Crea un nuevo objeto Cursor y llama execute() con los parámetros y el SQL dados. Retorna el nuevo objeto cursor.

executemany(sql, parameters, /)¶: Crea una nueva Cursor object and call executemany() con los parámetros y el SQL dados. Retorna el nuevo objeto cursor.

executescript(sql_script, /)¶: Crea una nueva Cursor object and call executescript() con el sql_script dado. Retorna el nuevo objeto cursor.

create_function(name, narg, func, \*, deterministic=False)¶

Crea o elimina una función SQL definida por el usuario.

Parámetros

name (str) – El nombre de la función SQL.
narg (int) – El número de argumentos que la función SQL puede aceptar. Si es -1, podrá entonces recibir cualquier cantidad de argumentos.
func (callback | None) – Un invocable que es llamado cuando la función SQL se invoca. El invocable debe retornar una un tipo soportado de forma nativa por SQLite. Se establece como None para eliminar una función SQL existente.
deterministic (bool) – Si se establece True, la función SQL creada se marcará como determinista, lo cual permite a SQLite realizar optimizaciones adicionales.

Muestra

NotSupportedError – Si deterministic se usa con versiones anteriores a SQLite 3.8.3.

Nuevo en la versión 3.8: El parámetro deterministic.

Ejemplo:

>>> import hashlib
>>> def md5sum(t):
...     return hashlib.md5(t).hexdigest()
>>> con = sqlite3.connect(":memory:")
>>> con.create_function("md5", 1, md5sum)
>>> for row in con.execute("SELECT md5(?)", (b"foo",)):
...     print(row)
('acbd18db4cc2f85cedef654fccc4a4d8',)

create_aggregate(name, /, n_arg, aggregate_class)¶

Crea o elimina una función agregada SQL definida por el usuario.

Parámetros

name (str) – El nombre de la función agregada SQL.
n_arg (int) – El número de argumentos que la función agregada SQL puede aceptar. Si es -1, podrá entonces recibir cualquier cantidad de argumentos.
aggregate_class (class | None) – Una clase debe implementar los siguientes métodos: * step(): Adiciona una fila al aggregate. * finalize(): Retorna el resultado final del aggregate como un tipo soportado nativamente por SQLite. La cantidad de argumentos que el método step() puede aceptar, es controlado por n_arg. Establece None para eliminar una función agregada SQL existente.

Ejemplo:

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.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_window_function(name, num_params, aggregate_class, /)¶

Crea o elimina una función agregada de ventana definida por el usuario.

Parámetros

name (str) – El nombre de la función agregada de ventana a ser creada o eliminada.
num_params (int) – La cantidad de argumentos que la función agregada de ventana SQL acepta. Si es -1, podrá entonces recibir cualquier cantidad de argumentos.
aggregate_class (class | None) – Una clase debe implementar los siguientes métodos: * step(): Agrega una fila a la ventana actual. * value(): Retorna el valor actual del aggregate . * inverse(): Elimina una fila de la ventana actual. * finalize(): Retorna el resultado final del aggregate como una un tipo soportado nativamente por SQLite. La cantidad de argumentos que los métodos step() y value() pueden aceptar son controlados por num_params. Establece None para eliminar una función agregada de ventana SQL.

Muestra

NotSupportedError – Si es usado con una versión de SQLite inferior a 3.25.0, la cual no soporte funciones agregadas de ventana.

Nuevo en la versión 3.11.

Ejemplo:

# Example taken from https://www.sqlite.org/windowfunctions.html#udfwinfunc
class WindowSumInt:
    def __init__(self):
        self.count = 0

    def step(self, value):
        """Add a row to the current window."""
        self.count += value

    def value(self):
        """Return the current value of the aggregate."""
        return self.count

    def inverse(self, value):
        """Remove a row from the current window."""
        self.count -= value

    def finalize(self):
        """Return the final value of the aggregate.

        Any clean-up actions should be placed here.
        """
        return self.count


con = sqlite3.connect(":memory:")
cur = con.execute("CREATE TABLE test(x, y)")
values = [
    ("a", 4),
    ("b", 5),
    ("c", 3),
    ("d", 8),
    ("e", 1),
]
cur.executemany("INSERT INTO test VALUES(?, ?)", values)
con.create_window_function("sumint", 1, WindowSumInt)
cur.execute("""
    SELECT x, sumint(y) OVER (
        ORDER BY x ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING
    ) AS sum_y
    FROM test ORDER BY x
""")
print(cur.fetchall())

create_collation(name, callable)¶

Crea una colación nombrada name usando la función collating callable. A callable se le pasan dos argumentos string, y este debería retornar un entero:

1 si el primero es ordenado más alto que el segundo
-1 si el primero es ordenado más pequeño que el segundo
0 si están ordenados de manera igual

El siguiente ejemplo muestra una ordenación de colación inversa:

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.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()

Elimina una función de colación al establecer el callable como None.

Distinto en la versión 3.11: El nombre de la colación puede contener cualquier caracter Unicode. Anteriormente, solamente caracteres ASCII eran permitidos.

interrupt()¶: Se puede llamar este método desde un hilo diferente para abortar cualquier consulta que pueda estar ejecutándose en la conexión. Consultas abortadas lanzaran una excepción.

set_authorizer(authorizer_callback)¶

Registra un invocable authorizer_callback que será invocado por cada intento de acceso a la columna de la tabla en la base de datos. La retrollamada podría retornar una SQLITE_OK, SQLITE_DENY, o un SQLITE_IGNORE para indicar cómo el acceso a la columna deberá ser manipulado por las capas inferiores de la biblioteca SQLite.

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.

Pasando None como authorizer_callback deshabilitará el autorizador.

Distinto en la versión 3.11: Agregado soporte para deshabilitar el autorizador usando None.

set_progress_handler(progress_handler, n)¶

Registra un invocable progress_handler que será invocado por cada n instrucciones de la máquina virtual de SQLite. Esto es útil si quieres recibir llamados de SQLite durante una operación de larga duración, como por ejemplo la actualización de una GUI.

Si se desea limpiar cualquier progress_handler instalado anteriormente, llame el método con None para progress_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 un invocable trace_callback que será llamado por cada sentencia SQL que sea de hecho ejecutada por el backend de SQLite.

El único argumento pasado a la retrollamada es la declaración (como str) que se está ejecutando. El valor de retorno de la retrollamada es ignorado. Tenga en cuenta que el backend no solo ejecuta declaraciones pasadas a los métodos Cursor.execute(). Otras fuentes incluyen el transaction management del módulo sqlite3 y la ejecución de disparadores definidos en la base de datos actual.

Pasando None como trace_callback deshabilitará el trace callback.

Nota

Las excepciones que se producen en la llamada de retorno no se propagan. Como ayuda para el desarrollo y la depuración, utilice enable_callback_tracebacks() para habilitar la impresión de tracebacks de las excepciones que se producen en la llamada de retorno.

Nuevo en la versión 3.3.

enable_load_extension(enabled, /)¶

Habilita el motor de SQLite para cargar extensiones SQLite de bibliotecas compartidas si enabled se establece como True; sino deshabilitará la carga de extensiones SQLite. Las extensiones SQLite pueden definir implementaciones de nuevas funciones, agregaciones, o tablas virtuales enteras. Una extensión bien conocida es fulltext-search distribuida con SQLite.

Nota

El módulo sqlite3 no está construido con soporte de extensión cargable de forma predeterminada, porque algunas plataformas (especialmente macOS) tienen bibliotecas SQLite que se compilan sin esta función. Para obtener soporte para extensiones cargables, debe pasar la opción --enable-loadable-sqlite-extensions a configure.

Lanza un auditing event sqlite3.enable_load_extension con los argumentos connection, enabled.

Nuevo en la versión 3.2.

Distinto en la versión 3.10: Agregado el evento de auditoría sqlite3.enable_load_extension.

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, /)¶

Carga una extensión SQLite de una biblioteca compartida ubicada en path. Se debe habilitar la carga de extensiones con enable_load_extension() antes de llamar este método.

Lanza un auditing event sqlite3.load_extension con argumentos connection, path.

Nuevo en la versión 3.2.

Distinto en la versión 3.10: Agregado el evento de auditoría sqlite3.load_extension.

iterdump()¶

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

Ejemplo:

# Convert file example.db to SQL dump file dump.sql
con = sqlite3.connect('example.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)¶

Crea una copia de seguridad de la base de datos SQLite.

Funciona incluso si la base de datos está siendo accedida por otros clientes al mismo tiempo sobre la misma conexión.

Parámetros

target (Connection) – La conexión de la base de datos para guardar la copia de seguridad.
pages (int) – Cantidad de páginas que serán copiadas cada vez. Si es menor o igual a 0, toda la base de datos será copiada en un solo paso. El valor por defecto es -1.
progress (callback | None) – Si se establece un invocable, este será invocado con 3 argumentos enteros para cada iteración sobre la copia de seguridad: el status de la última iteración, el remaining, que indica el número de páginas pendientes a ser copiadas, y el total que indica le número total de páginas. El valor por defecto es None.
name (str) – El nombre de la base de datos a ser guardada. O bien sea "main" (valor por defecto) para la base de datos main, "temp" para la base de datos temporal, o el nombre de una base de datos personalizada adjuntada usando la sentencia ATTACH DATABASE.
sleep (float) – Número de segundos a dormir entre sucesivos intentos para respaldar páginas restantes.

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

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

src = sqlite3.connect('example.db')
dst = sqlite3.connect('backup.db')
with dst:
    src.backup(dst, pages=1, progress=progress)
dst.close()
src.close()

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

src = sqlite3.connect('example.db')
dst = sqlite3.connect(':memory:')
src.backup(dst)

Nuevo en la versión 3.7.

getlimit(category, /)¶

Obtiene el límite de tiempo de ejecución de una conexión.

Parámetros: category (int) – La SQLite limit category a ser consultada.
Tipo del valor devuelto: int
Muestra: ProgrammingError – Si category no se reconoce por las capas inferiores de la biblioteca SQLite.

Ejemplo, consulta el tamaño máximo de una sentencia SQL para la Connection con (el valor por defecto es 1000000000):

>>> con.getlimit(sqlite3.SQLITE_LIMIT_SQL_LENGTH)
1000000000

Nuevo en la versión 3.11.

setlimit(category, limit, /)¶

Set a connection runtime limit. Attempts to increase a limit above its hard upper bound are silently truncated to the hard upper bound. Regardless of whether or not the limit was changed, the prior value of the limit is returned.

Parámetros

category (int) – La SQLite limit category a ser establecido.
limit (int) – El valor del nuevo límite. Si es negativo, el límite actual no cambia.

Tipo del valor devuelto

int

Muestra

ProgrammingError – Si category no se reconoce por las capas inferiores de la biblioteca SQLite.

Por ejemplo, limite el número de bases de datos adjuntas a 1 para la Connection con (el valor por defecto es 10):

>>> con.setlimit(sqlite3.SQLITE_LIMIT_ATTACHED, 1)
10
>>> con.getlimit(sqlite3.SQLITE_LIMIT_ATTACHED)
1

Nuevo en la versión 3.11.

serialize(\*, name="main")¶

Serializa la base de datos en un objeto bytes. Para un archivo ordinario de base de datos en disco, la serialización es solo una copia del archivo de disco. Para el caso de una base de datos en memoria o una base de datos «temp», la serialización es la misma secuencia de bytes que se escribiría en el disco si se hiciera una copia de seguridad de esa base de datos en el disco.

Parámetros: name (str) – El nombre de la base de datos a ser serializada. El valor por defecto es "main".
Tipo del valor devuelto: bytes

Nota

Este método solo está disponible si las capas internas de la biblioteca SQLite tienen la API serialise.

Nuevo en la versión 3.11.

deserialize(data, /, \*, name="main")¶

Deserializa una base de datos serializsda en una clase Connection. Este método hace que la conexión de base de datos se desconecte de la base de datos name, y la abre nuevamente como una base de datos en memoria, basada en la serialización contenida en data.

Parámetros

data (bytes) – Una base de datos serializada.
name (str) – El nombre de la base de datos a ser deserializada. El valor por defecto es "main".

Muestra

OperationalError – Si la conexión con la base de datos está actualmente involucrada en una transacción de lectura o una operación de copia de seguridad.
DatabaseError – Si data no contiene una base de datos SQLite válida.
OverflowError – Si len(data) es más grande que 2**63 - 1.

Nota

Este método solo está disponible si las capas internas de la biblioteca SQLite tienen la API deserialize.

Nuevo en la versión 3.11.

in_transaction¶

Este atributo de solo lectura corresponde al autocommit mode de SQLite de bajo nivel.

True si una transacción está activa (existen cambios sin confirmar),``False`` en caso contrario.

Nuevo en la versión 3.2.

isolation_level¶

Este atributo controla la transaction handling realizado por sqlite3. Si se establece como None, las transacciones nunca se abrirán implícitamente. Si se establece "DEFERRED", "IMMEDIATE", o "EXCLUSIVE", correspondientes al SQLite transaction behaviour, de las capas inferiores, implícitamente se realiza transaction management.

Si no se sobreescribe por el parámetro isolation_level de connect(), el valor predeterminado es "", que es un alias para "DEFERRED".

row_factory¶

Un objeto invocable que acepta dos argumentos, un objeto Cursor y los resultados de la fila sin procesar como una tupla, y retorna un objeto personalizado que representa una fila SQLite.

Ejemplo:

>>> def dict_factory(cursor, row):
...     col_names = [col[0] for col in cursor.description]
...     return {key: value for key, value in zip(col_names, row)}
>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = dict_factory
>>> for row in con.execute("SELECT 1 AS a, 2 AS b"):
...     print(row)
{'a': 1, 'b': 2}

Si retorna una tupla no es suficiente y desea acceso basado en nombres a las columnas 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¶

A invocable que acepta una bytes`como parámetro y retorna una representación del texto de el. El invocable es llamado por valores SQLite con el tipo de datos ``TEXT`. Por defecto, este atributo se configura como una str. Si quieres retornar en su lugar, bytes, entonces se establece text_factory como bytes.

Ejemplo:

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¶: Retorna 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.

Objetos cursor¶

Un objeto Cursor representa un database cursor que se utiliza para ejecutar sentencias SQL y administrar el contexto de una operación de búsqueda. Los cursores son creados usando Connection.cursor(), o por usar alguno de los connection shortcut methods.

Los objetos cursores son iterators, lo que significa que si execute() una consulta SELECT, simplemente podrás iterar sobre el cursor para obtener las filas resultantes:
for row in cur.execute("SELECT t FROM data"):
    print(row)

class sqlite3.Cursor¶

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

execute(sql, parameters=(), /)¶

Ejecuta una sentencia SQL sql. Los valores pueden vincularse a la sentencia utilizando placeholders que mapea parameters sequence o dict .

execute() solamente ejecutará sentencias únicas SQL. Si intenta ejecutar más de una instrucción con él, se lanzará un ProgrammingError. Use executescript() si desea ejecutar varias instrucciones SQL con una sola llamada.

Si el isolation_level no es None, y sql es una sentencia INSERT, UPDATE, DELETE, o REPLACE, y no hay transacciones abierta, entonces una transacción se abre implícitamente antes de ejecutar el sql.

executemany(sql, parameters, /)¶

Ejecuta una sentencia SQL sql parameterized contra todas las secuencias de parámetros o asignaciones encontradas en la secuencia parameters. También es posible utilizar un iterator que produzca parámetros en lugar de una secuencia. Utiliza el mismo control de transacciones implícitas que execute().

Ejemplo:

rows = [
    ("row1",),
    ("row2",),
]
# cur is an sqlite3.Cursor object
cur.executemany("INSERT INTO data VALUES(?)", rows)

executescript(sql_script, /)¶

Ejecuta las sentencias SQL en sql_script. Si hay una transacción pendiente, primero se ejecuta una instrucción COMMIT implícitamente. No se realiza ningún otro control de transacción implícito; Cualquier control de transacción debe agregarse a sql_script.

sql_script debe ser una instancia de string.

Ejemplo:

# cur is an sqlite3.Cursor object
cur.executescript("""
    BEGIN;
    CREATE TABLE person(firstname, lastname, age);
    CREATE TABLE book(title, author, published);
    CREATE TABLE publisher(name, address);
    COMMIT;
""")

fetchone()¶: Si el row_factory es None, retorna el conjunto de resultados de la consulta de la siguiente fila como un tuple. De lo contrario, páselo a la fábrica de filas y retorne su resultado. Retorna None si no hay más datos disponibles.

fetchmany(size=cursor.arraysize)¶

Retorna el siguiente conjunto de filas del resultado de una consulta como una list. Una lista vacía será retornada cuando no hay más filas disponibles.

El número de filas que se van a obtener por llamada se especifica mediante el parámetro size. Si size no es informado, entonces arraysize determinará el número de filas que se van a recuperar. Si hay menos filas size disponibles, se retornan tantas filas como estén disponibles.

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()¶: Retorna todas las filas (restantes) de un resultado de consulta como list. Retorna una lista vacía si no hay filas disponibles. Tenga en cuenta que el atributo arraysize puede afectar al rendimiento de esta operación.

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, /)¶: Requerido por la DB-API. No hace nada en sqlite3.

setoutputsize(size, column=None, /)¶: Requerido por la DB-API. No hace nada en sqlite3.

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.

connection¶

Este atributo de solo lectura que provee la Connection de la base de datos SQLite pertenece al cursor. Un objeto Cursor creado llamando a con.cursor() tendrá un atributo connection que hace referencia a con:

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

description¶

Este atributo de solo lectura provee el nombre de las columnas de la última consulta. Para seguir siendo compatible con la API de base de datos de Python, retornará una tupla de 7 elementos para cada columna donde los últimos seis elementos de cada tupla son Ninguno.

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

lastrowid¶: Atributo de solo lectura que proporciona el identificador de fila de la última insertada. Solo se actualiza después de que las sentencias INSERT o REPLACE hayan sido exitosas usando el método execute(). Para otras instrucciones, después de executemany() o executescript(), o si se produjo un error en la inserción, el valor de lastrowid se deja sin cambios. El valor inicial de lastrowid es None.

Nota

Las inserciones en tablas WITHOUT ROWID no se registran.

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

rowcount¶: Atributo de solo lectura que proporciona el número de filas modificadas para las sentencias INSERT, UPDATE, DELETE y REPLACE; se usa -1 para otras sentencias, incluidas las consultas CTE. Sólo se actualiza mediante los métodos execute() y executemany().

Objetos fila (Row)¶

class sqlite3.Row¶

Una instancia de Row sirve como una instancia row_factory altamente optimizada para objetos Connection. Admite iteración, pruebas de igualdad, acceso a len() y mapping por nombre de columna e índice.

Dos objetos de fila comparan iguales si tienen columnas iguales y miembros iguales.

keys()¶: Este método retorna una list con los nombre de columnas como strings. 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 para segmentación.

Ejemplo:

>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = sqlite3.Row
>>> res = con.execute("SELECT 'Earth' AS name, 6378 AS radius")
>>> row = res.fetchone()
>>> row.keys()
['name', 'radius']
>>> row[0], row["name"]  # Access by index and name.
('Earth', 'Earth')
>>> row["RADIUS"]  # Column names are case-insensitive.
6378

Objetos fila (Row)¶

Nuevo en la versión 3.11.

class sqlite3.Blob¶

Una instancia Blob es un file-like object que puede leer y escribir datos en un SQLite BLOB. Llame a len(blob) para obtener el tamaño (número de bytes) del blob. Use índices y slices para obtener acceso directo a los datos del blob.

Use Blob como context manager para asegurarse de que el identificador de blob se cierra después de su uso.

con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE test(blob_col blob)")
con.execute("INSERT INTO test(blob_col) VALUES(zeroblob(13))")

# Write to our blob, using two write operations:
with con.blobopen("test", "blob_col", 1) as blob:
    blob.write(b"hello, ")
    blob.write(b"world.")
    # Modify the first and last bytes of our blob
    blob[0] = ord("H")
    blob[-1] = ord("!")

# Read the contents of our blob
with con.blobopen("test", "blob_col", 1) as blob:
    greeting = blob.read()

print(greeting)  # outputs "b'Hello, world!'"

close()¶

Cierra el blob.

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

read(length=- 1, /)¶: Leer bytes length de datos del blob en la posición de desplazamiento actual. Si se alcanza el final del blob, se devolverán los datos hasta EOF. Cuando length no se especifica, o es negativo, read() se leerá hasta el final del blob.

write(data, /)¶: Escriba data en el blob en el desplazamiento actual. Esta función no puede cambiar la longitud del blob. Escribir más allá del final del blob generará un ValueError.

tell()¶: Devolver la posición de acceso actual del blob.

seek(offset, origin=os.SEEK_SET, /)¶: Establezca la posición de acceso actual del blob en offset. El valor predeterminado del argumento origin es os. SEEK_SET (posicionamiento absoluto de blobs). Otros valores para origin son os. SEEK_CUR (busca en relación con la posición actual) y os. SEEK_END (buscar en relación con el final del blob).

Objetos PrepareProtocol¶

class sqlite3.PrepareProtocol¶: El único propósito del tipo PrepareProtocol es actuar como un protocolo de adaptación de estilo PEP 246 para objetos que pueden adapt themselves a native SQLite types.

Excepciones¶

La jerarquía de excepciones está definida por DB-API 2.0 (PEP 249).

exception sqlite3.Warning¶: Esta excepción no se genera actualmente en el módulo sqlite3, pero puede ser provocada por aplicaciones que usan :mod:!sqlite3`, por ejemplo, si una función definida por el usuario trunca datos durante la inserción. Warning es una subclase de Exception.

exception sqlite3.Error¶

La clase base de las otras excepciones de este módulo. Use esto para detectar todos los errores con una sola instrucción except.``Error`` is una subclase de Exception.

Si la excepción se originó dentro de la biblioteca SQLite, se agregan los siguientes dos atributos a la excepción:

sqlite_errorcode¶: El código de error numérico de SQLite API

Nuevo en la versión 3.11.

sqlite_errorname¶: El nombre simbólico del código de error numérico de SQLite API

Nuevo en la versión 3.11.

exception sqlite3.InterfaceError¶: Excepción lanzada por el uso indebido de la API de SQLite C de bajo nivel. En otras palabras, si se lanza esta excepción, probablemente indica un error en el módulo sqlite3. InterfaceError es una subclase de Error.

exception sqlite3.DatabaseError¶: Excepción lanzada por errores relacionados con la base de datos. Esto sirve como excepción base para varios tipos de errores de base de datos. Solo se genera implícitamente a través de las subclases especializadas. DatabaseError es una subclase de Error.

exception sqlite3.DataError¶: Excepción lanzada por errores causados por problemas con los datos procesados, como valores numéricos fuera de rango y cadenas de caracteres demasiado largas. DataError es una subclase de DatabaseError.

exception sqlite3.OperationalError¶: Excepción lanzada por errores que están relacionados con el funcionamiento de la base de datos y no necesariamente bajo el control del programador. Por ejemplo, no se encuentra la ruta de la base de datos o no se pudo procesar una transacción. OperationalError es una subclase de DatabaseError.

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.InternalError¶: Se genera una excepción cuando SQLite encuentra un error interno. Si se genera esto, puede indicar que hay un problema con la biblioteca SQLite en tiempo de ejecución. InternalError es una subclase de DatabaseError.

exception sqlite3.ProgrammingError¶: Excepción lanzada por errores de programación de la API de sqlite3, por ejemplo, proporcionar el número incorrecto de enlaces a una consulta, o intentar operar en una Connection cerrada. ProgrammingError es una subclase de DatabaseError.

exception sqlite3.NotSupportedError¶: Excepción lanzada en caso que la biblioteca SQLite subyacente no admita un método o una API de base de datos. Por ejemplo, establecer determinista como Verdadero en create_function(), si la biblioteca SQLite subyacente no admite funciones deterministic. NotSupportedError es una subclase de DatabaseError.

SQLite y tipos de Python¶

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`

El sistema de tipos del módulo sqlite3 es extensible en dos formas: se puede almacenar tipos de Python adicionales en una base de datos SQLite vía a objetos adaptadores, y se puede permitir que sqlite3 convierta tipos SQLite a diferentes tipos de Python vía converters.

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

El convertidor por defecto «timestamp» ignora las compensaciones UTC en la base de datos y siempre devuelve un objeto datetime.datetime naive. Para conservar las compensaciones UTC en las marcas de tiempo, deje los convertidores deshabilitados o registre un convertidor que reconozca la compensación con register_converter().

Guías prácticas¶

Cómo usar marcadores de posición para vincular valores en consultas SQL¶

Las operaciones de SQL generalmente necesitan usar valores de variables de Python. Sin embargo, tenga cuidado con el uso de las operaciones de cadena de caracteres de Python para ensamblar consultas, ya que son vulnerables a los SQL injection attacks (see the xkcd webcomic para ver un ejemplo gracioso de lo que puede ir mal):

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

En su lugar, utilice la sustitución de parámetros de la DB-API. Para insertar una variable en una consulta, use un marcador de posición en la consulta y sustituya los valores reales en la consulta como una tuple de valores al segundo argumento de execute(). Una sentencia SQL puede utilizar uno de dos tipos de marcadores de posición: signos de interrogación (estilo qmark) o marcadores de posición con nombre (estilo con nombre). Para el estilo qmark, parameters debe ser un sequence. Para el estilo nombrado, puede ser una instancia sequence o dict. La longitud de sequence debe coincidir con el número de marcadores de posición, o se lanzará un ProgrammingError. Si se proporciona un dict, debe contener claves para todos los parámetros nombrados. Cualquier item adicional se ignorará. Aquí un ejemplo de ambos estilos:

con = sqlite3.connect(":memory:")
cur = con.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())

Cómo adaptar tipos de Python personalizados a valores de SQLite¶

SQLite solo admite un conjunto limitado de tipos de datos de forma nativa. Para almacenar tipos personalizados de Python en bases de datos SQLite, adáptelos a uno de los tipos Python que SQLite entiende de forma nativa.

Hay dos formas de adaptar los objetos de Python a los tipos de SQLite: dejar que su objeto se adapte a sí mismo o usar un adapter callable. Este último prevalecerá sobre el primero. Para una biblioteca que exporta un tipo personalizado, puede tener sentido permitir que ese tipo se adapte. Como desarrollador de aplicaciones, puede tener más sentido tomar el control directo registrando funciones de adaptador personalizadas.

Cómo escribir objetos adaptables¶

Supongamos que tenemos una clase Point que representa un par de coordenadas, x e y, en un sistema de coordenadas cartesianas. El par de coordenadas se almacenará como una cadena de texto en la base de datos, utilizando un punto y coma para separar las coordenadas. Esto se puede implementar agregando un método __conform__(self, protocol) que retorna el valor adaptado. El objeto pasado a protocolo será de tipo PrepareProtocol.

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

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

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

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

Como registrar un adaptador invocable¶

La otra posibilidad es crear una función que convierta el objeto Python a un tipo compatible de SQLite. Esta función puede de esta forma ser registrada usando un register_adapter().

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

def adapt_point(point):
    return f"{point.x};{point.y}"

sqlite3.register_adapter(Point, adapt_point)

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

cur.execute("SELECT ?", (Point(1.0, 2.5),))
print(cur.fetchone()[0])

Como convertir valores SQLite a tipos de Python personalizados¶

Escribir un adaptador le permite convertir de tipos personalizados de Python a valores SQLite. Para poder convertir de valores SQLite a tipos personalizados de Python, usamos convertidores.

Regresemos a la clase Point. Almacenamos las coordenadas x y y separadas por punto y coma como una cadena de caracteres en SQLite.

Primero, se define una función de conversión que acepta la cadena de texto como un parámetro y construya 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 necesitamos decirle a sqlite3 cuando debería convertir un valor dado SQLite. Esto se hace cuando se conecta a una base de datos, utilizando el parámetro detect_types de connect(). Hay tres opciones:

Implícito: establece detect_types para que PARSE_DECLTYPES
Explícito: establece detect_types para que PARSE_COLNAMES
Ambos: establece detect_types para sqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMES. Los nombres de columna tienen prioridad sobre los tipos declarados.

El siguiente ejemplo ilustra ambos enfoques:

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

    def __repr__(self):
        return f"Point({self.x}, {self.y})"

def adapt_point(point):
    return f"{point.x};{point.y}".encode("utf-8")

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

# Register the adapter and converter
sqlite3.register_adapter(Point, adapt_point)
sqlite3.register_converter("point", convert_point)

# 1) Parse using declared types
p = Point(4.0, -3.2)
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES)
cur = con.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()

# 2) Parse using column names
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)
cur = con.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])

Ejemplos para adaptadores y convertidores¶

En esta sección se muestran ejemplos para adaptadores y convertidores comunes.

import datetime
import sqlite3

def adapt_date_iso(val):
    """Adapt datetime.date to ISO 8601 date."""
    return val.isoformat()

def adapt_datetime_iso(val):
    """Adapt datetime.datetime to timezone-naive ISO 8601 date."""
    return val.isoformat()

def adapt_datetime_epoch(val):
    """Adapt datetime.datetime to Unix timestamp."""
    return int(val.timestamp())

sqlite3.register_adapter(datetime.date, adapt_date_iso)
sqlite3.register_adapter(datetime.datetime, adapt_datetime_iso)
sqlite3.register_adapter(datetime.datetime, adapt_datetime_epoch)

def convert_date(val):
    """Convert ISO 8601 date to datetime.date object."""
    return datetime.date.fromisoformat(val)

def convert_datetime(val):
    """Convert ISO 8601 datetime to datetime.datetime object."""
    return datetime.datetime.fromisoformat(val)

def convert_timestamp(val):
    """Convert Unix epoch timestamp to datetime.datetime object."""
    return datetime.datetime.fromtimestamp(val)

sqlite3.register_converter("date", convert_date)
sqlite3.register_converter("datetime", convert_datetime)
sqlite3.register_converter("timestamp", convert_timestamp)

Cómo utilizar los métodos de acceso directo de conexión¶

Usando los métodos execute(), executemany(), y executescript() de la clase Connection, su código se puede escribir de manera más concisa porque no tiene que crear los (a menudo superfluo) objetos Cursor explícitamente. Por el contrario, los objetos Cursor son creados implícitamente y esos métodos de acceso directo retornarán objetos cursores. De esta forma, se puede ejecutar una sentencia SELECT e iterar sobre ella directamente usando un simple llamado sobre el objeto de clase Connection.

# Create and fill the table.
con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE lang(name, first_appeared)")
data = [
    ("C++", 1985),
    ("Objective-C", 1984),
]
con.executemany("INSERT INTO lang(name, first_appeared) VALUES(?, ?)", data)

# 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;
# the connection object should be closed manually
con.close()

Como usar la conexión con un administrador de contexto¶

Un objeto Connection se puede utilizar como un administrador de contexto que confirma o revierte automáticamente las transacciones abiertas al salir del administrador de contexto. Si el cuerpo de with termina con una excepción, la transacción es confirmada. Si la confirmación falla, o si el cuerpo del with lanza una excepción que no es capturada, la transacción se revierte.

Si no hay una transacción abierta al salir del cuerpo de la declaración with, el administrador de contexto no funciona.

Nota

El administrador de contexto no abre implícitamente una nueva transacción ni cierra la conexión.

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()

Como trabajar con URIs SQLite¶

Algunos trucos útiles de URI incluyen:

Abra una base de datos en modo de solo lectura:

>>> con = sqlite3.connect("file:tutorial.db?mode=ro", uri=True)
>>> con.execute("CREATE TABLE readonly(data)")
Traceback (most recent call last):
OperationalError: attempt to write a readonly database

No cree implícitamente un nuevo archivo de base de datos si aún no existe; esto lanzará un OperationalError si no puede crear un nuevo archivo:

>>> con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)
Traceback (most recent call last):
OperationalError: unable to open database file

Crea un nombre compartido sobre una base de datos en memoria:

db = "file:mem1?mode=memory&cache=shared"
con1 = sqlite3.connect(db, uri=True)
con2 = sqlite3.connect(db, uri=True)
with con1:
    con1.execute("CREATE TABLE shared(data)")
    con1.execute("INSERT INTO shared VALUES(28)")
res = con2.execute("SELECT data FROM shared")
assert res.fetchone() == (28,)

Más información sobre esta característica, incluyendo una lista de opciones reconocidas, pueden encontrarse en SQLite URI documentation.

Explicación¶

Control transaccional¶

El sqlite3 no cumple con el manejo de transacciones recomendado por PEP 249.

Si el atributo de conexión isolation_level no es None, las nuevas transacciones se abrirán implícitamente antes de execute() y executemany() ejecutará sentencias INSERT, UPDATE, DELETE o REPLACE; para otras sentencias, no se realiza ningún manejo de transacción implícito. Utilice los métodos commit() y rollback() para confirmar y deshacer respectivamente las transacciones pendientes. Puede elegir el SQLite transaction behaviour subyacente, es decir, si y qué tipo de declaraciones BEGIN sqlite3 se ejecutarán implícitamente, a través del atributo isolation_level.

Si isolation_level se establece como None, no se abre ninguna transacción implícitamente. Esto deja la biblioteca SQLite subyacente en autocommit mode, pero también permite que el usuario realice su propio manejo de transacciones usando declaraciones SQL explícitas. El modo de confirmación automática de la biblioteca SQLite subyacente se puede consultar mediante el atributo in_transaction.

El método executescript() guarda implícitamente cualquier transacción pendiente antes de la ejecución del script SQL dado, independientemente del valor de isolation_level.

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.

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

Tutorial¶

Referencia¶

Funciones del módulo¶

Constantes del módulo¶

Objetos de conexión¶

Objetos cursor¶

Objetos fila (Row)¶

Objetos fila (Row)¶

Objetos PrepareProtocol¶

Excepciones¶

SQLite y tipos de Python¶

Adaptadores y convertidores por defecto¶

Guías prácticas¶

Cómo usar marcadores de posición para vincular valores en consultas SQL¶

Cómo adaptar tipos de Python personalizados a valores de SQLite¶

Cómo escribir objetos adaptables¶

Como registrar un adaptador invocable¶

Como convertir valores SQLite a tipos de Python personalizados¶

Ejemplos para adaptadores y convertidores¶

Cómo utilizar los métodos de acceso directo de conexión¶

Como usar la conexión con un administrador de contexto¶

Como trabajar con URIs SQLite¶

Explicación¶

Control transaccional¶

Tabla de contenido

Tema anterior

Próximo tema

Esta página

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

Tutorial¶

Referencia¶

Funciones del módulo¶

Constantes del módulo¶

Objetos de conexión¶

Objetos cursor¶

Objetos fila (Row)¶

Objetos fila (Row)¶

Objetos PrepareProtocol¶

Excepciones¶

SQLite y tipos de Python¶

Adaptadores y convertidores por defecto¶

Guías prácticas¶

Cómo usar marcadores de posición para vincular valores en consultas SQL¶

Cómo adaptar tipos de Python personalizados a valores de SQLite¶

Cómo escribir objetos adaptables¶

Como registrar un adaptador invocable¶

Como convertir valores SQLite a tipos de Python personalizados¶

Ejemplos para adaptadores y convertidores¶

Cómo utilizar los métodos de acceso directo de conexión¶

Como usar la conexión con un administrador de contexto¶

Como trabajar con URIs SQLite¶

Explicación¶

Control transaccional¶

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