sqlite3 — DB-API 2.

0 interface for SQLite databases

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.

First, we need to create a new database and open a database connection to allow sqlite3 to work with it. Call
sqlite3.connect() to create a connection to the database tutorial.db in the current working directory,
implicitly creating it if it does not exist:

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.

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
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:

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
>>> res = cur.execute("SELECT score FROM movie") >>>
>>> res.fetchall()
[(8.2,), (7.5,)]

El resultado es una list de dos tuple s, 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
>>> new_con.close()

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

Ver también:

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 Guías prácticas para lecturas de interés:
Cómo usar marcadores de posición para vincular valores en consultas SQL
Cómo adaptar tipos de Python personalizados a valores de SQLite
Como convertir valores SQLite a tipos de Python personalizados
Como usar la conexión con un administrador de contexto
How to create and use row factories
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, *, autocommit=sqlite3.LEGACY_TRANSACTION_CONTROL)
Abre una conexión con una base de datos SQLite.

Parámetros: database (path-like object) – The path to the database file to be opened. You
can pass ":memory:" to create an SQLite database existing only in
memory, and open a connection to it.
timeout (float) – How many seconds the connection should wait before
raising an OperationalError when a table is locked. If another connection
opens a transaction to modify a table, that table will be locked until the
transaction is committed. Default five seconds.
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) – Control legacy transaction handling behaviour.
See Connection.isolation_level and Transaction control via the
isolation_level attribute for more information. Can be "DEFERRED" (default),
"EXCLUSIVE" or "IMMEDIATE" ; or None to disable opening transactions
implicitly. Has no effect unless Connection.autocommit is set to
LEGACY_TRANSACTION_CONTROL (the default).
check_same_thread (bool) – If True (default), ProgrammingError will be
raised if the database connection is used by a thread other than the one that
created it. If False , the connection may be accessed in multiple threads;

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 write operations may need to be serialized by the user to avoid data
corruption. See threadsafety for more information.
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.
autocommit (bool) – Control PEP 249 transaction handling behaviour. See
Connection.autocommit and Transaction control via the autocommit
attribute for more information. autocommit currently defaults to
LEGACY_TRANSACTION_CONTROL . The default will change to False in a
future Python release.
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 .

Distinto en la versión 3.4: Added the uri parameter.

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

Distinto en la versión 3.10: Added the sqlite3.connect/handle auditing event.

Distinto en la versión 3.12: Added the autocommit parameter.

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

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 See runsource() in Lib/sqlite3/__main__.py for real-world use.

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.

Nota: Errors in user-defined function callbacks are logged as unraisable exceptions. Use an
unraisable hook handler for introspection of the failed callback.

sqlite3.register_adapter(type, adapter, /)
Register an adapter callable to adapt the Python type type into an SQLite type. The adapter is called with a
Python object of type type as its sole argument, and must return a value of a type that SQLite natively
understands.

sqlite3.register_converter(typename, converter, /)
Register the converter callable to convert SQLite objects of type typename into a Python object of a specific
type. The converter is invoked for all SQLite values of type typename; it is passed a bytes object and
should return an object of the desired Python type. Consult the parameter detect_types of connect() for
information regarding how type detection works.

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.LEGACY_TRANSACTION_CONTROL
Set autocommit to this constant to select old style (pre-Python 3.12) transaction control behaviour. See
Transaction control via the isolation_level attribute for more information.

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"

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 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 that should be returned by the authorizer_callback callable passed to
Connection.set_authorizer() , to indicate whether:

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: The named DB-API parameter style is also supported.

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:

1. 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.
2. 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.
3. 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:

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 Modo de
threadsafety SQLITE_THREADSAFE Significado de DB-API 2.0
subprocesamiento SQLite

Hilos no pueden compartir el

single-thread 0 0
módulo

Hilos pueden compartir el

multi-thread 1 2
módulo, pero no conexiones

Hilos pueden compartir el

serialized 3 1
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.

Obsoleto desde la versión 3.12, se eliminará en la versión 3.14: This constant used to reflect the
version number of the pysqlite package, a third-party library which used to upstream changes to
sqlite3 . Today, it carries no meaning or practical value.

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.

Obsoleto desde la versión 3.12, se eliminará en la versión 3.14: This constant used to reflect the
version number of the pysqlite package, a third-party library which used to upstream changes to
sqlite3 . Today, it carries no meaning or practical value.

sqlite3.SQLITE_DBCONFIG_DEFENSIVE
sqlite3.SQLITE_DBCONFIG_DQS_DDL
sqlite3.SQLITE_DBCONFIG_DQS_DML
sqlite3.SQLITE_DBCONFIG_ENABLE_FKEY
sqlite3.SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER
sqlite3.SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION
sqlite3.SQLITE_DBCONFIG_ENABLE_QPSG
sqlite3.SQLITE_DBCONFIG_ENABLE_TRIGGER
sqlite3.SQLITE_DBCONFIG_ENABLE_VIEW
sqlite3.SQLITE_DBCONFIG_LEGACY_ALTER_TABLE
sqlite3.SQLITE_DBCONFIG_LEGACY_FILE_FORMAT
sqlite3.SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE
sqlite3.SQLITE_DBCONFIG_RESET_DATABASE
sqlite3.SQLITE_DBCONFIG_TRIGGER_EQP
sqlite3.SQLITE_DBCONFIG_TRUSTED_SCHEMA
sqlite3.SQLITE_DBCONFIG_WRITABLE_SCHEMA
These constants are used for the Connection.setconfig() and getconfig() methods.

The availability of these constants varies depending on the version of SQLite Python was compiled with.

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 Added in version 3.12.

Ver también:

https://www.sqlite.org/c3ref/c_dbconfig_defensive.html
SQLite docs: Database Connection Configuration Options

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)
Create and return a Cursor object. The cursor method accepts a single optional parameter factory. If
supplied, this must be a callable returning an instance of Cursor or its subclasses.

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.

Added in version 3.11.

commit()

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 Commit any pending transaction to the database. If autocommit is True , or there is no open
transaction, this method does nothing. If autocommit is False , a new transaction is implicitly opened
if a pending transaction was committed by this method.

rollback()
Roll back to the start of any pending transaction. If autocommit is True , or there is no open
transaction, this method does nothing. If autocommit is False , a new transaction is implicitly opened
if a pending transaction was rolled back by this method.

close()
Close the database connection. If autocommit is False , any pending transaction is implicitly rolled
back. If autocommit is True or LEGACY_TRANSACTION_CONTROL , no implicit transaction control is
executed. Make sure to commit() before closing to avoid losing pending changes.

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) – A callable that is called when the SQL function is invoked.
The callable must return a type natively supported by SQLite. Set to None to remove
an existing SQL function.
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.

Distinto en la versión 3.8: Added the deterministic parameter.

Ejemplo:

>>> import hashlib >>>

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

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 >>> con = sqlite3.connect(":memory:")
>>> con.create_function("md5", 1, md5sum)
>>> for row in con.execute("SELECT md5(?)", (b"foo",)):
... print(row)
('acbd18db4cc2f85cedef654fccc4a4d8',)
>>> con.close()

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

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 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.

Added in version 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())
con.close()

create_collation(name, callable, /)

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 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()
Call this method from a different thread to abort any queries that might be executing on the connection.
Aborted queries will raise an OperationalError .

set_authorizer(authorizer_callback)
Register callable authorizer_callback to be invoked for each attempt to access a column of a table in
the database. The callback should return one of SQLITE_OK , SQLITE_DENY , or SQLITE_IGNORE to
signal how access to the column should be handled by the underlying SQLite library.

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 .

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 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)
Register callable progress_handler to be invoked for every n instructions of the SQLite virtual machine.
This is useful if you want to get called from SQLite during long-running operations, for example to
update a GUI.

Si se desea limpiar cualquier progress_handler instalado anteriormente, llame el método con None
para progress_handler.

Returning a non-zero value from the handler function will terminate the currently executing query and
cause it to raise a DatabaseError exception.

set_trace_callback(trace_callback)
Register callable trace_callback to be invoked for each SQL statement that is actually executed by the
SQLite backend.

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.

Added in version 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 .

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 Added in version 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 pe
INSERT INTO recipe (name, ingredients) VALUES('pumpkin stew', 'pumpkin onio
INSERT INTO recipe (name, ingredients) VALUES('broccoli pie', 'broccoli che
INSERT INTO recipe (name, ingredients) VALUES('pumpkin pie', 'pumpkin sugar
""")
for row in con.execute("SELECT rowid, name, ingredients FROM recipe WHERE name
print(row)

load_extension(path, /, *, entrypoint=None)
Load an SQLite extension from a shared library. Enable extension loading with
enable_load_extension() before calling this method.

Parámetros: path (str) – The path to the SQLite extension.

entrypoint (str | None) – Entry point name. If None (the default), SQLite will come
up with an entry point name of its own; see the SQLite docs Loading an Extension
for details.

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

Added in version 3.2.

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

Distinto en la versión 3.12: Added the entrypoint parameter.

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:

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 # 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()

Ver también: How to handle non-UTF-8 text encodings

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) – If set to a callable, it is invoked with three integer
arguments for every backup iteration: the status of the last iteration, the remaining
number of pages still to be copied, and the total number of pages. Defaults to 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)
dst.close()
src.close()

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 Added in version 3.7.

Ver también: How to handle non-UTF-8 text encodings

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

Added in version 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

Added in version 3.11.

getconfig(op, /)
Query a boolean connection configuration option.

Parámetros: op (int) – A SQLITE_DBCONFIG code.

Tipo del valor devuelto: bool

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 Added in version 3.12.

setconfig(op, enable=True, /)
Set a boolean connection configuration option.

Parámetros: op (int) – A SQLITE_DBCONFIG code.

enable (bool) – True if the configuration option should be enabled (default); False
if it should be disabled.

Added in version 3.12.

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.

Added in version 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.

Added in version 3.11.

autocommit

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 This attribute controls PEP 249-compliant transaction behaviour. autocommit has three allowed
values:

False : Select PEP 249-compliant transaction behaviour, implying that sqlite3 ensures a
transaction is always open. Use commit() and rollback() to close transactions.

This is the recommended value of autocommit .

True : Use SQLite’s autocommit mode. commit() and rollback() have no effect in this mode.

LEGACY_TRANSACTION_CONTROL : Pre-Python 3.12 (non-PEP 249-compliant) transaction control.

See isolation_level for more details.

This is currently the default value of autocommit .

Changing autocommit to False will open a new transaction, and changing it to True will commit any
pending transaction.

See Transaction control via the autocommit attribute for more details.

Nota: The isolation_level attribute has no effect unless autocommit is

LEGACY_TRANSACTION_CONTROL .

Added in version 3.12.

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.

Added in version 3.2.

isolation_level
Controls the legacy transaction handling mode of sqlite3 . If set to None , transactions are never
implicitly opened. If set to one of "DEFERRED" , "IMMEDIATE" , or "EXCLUSIVE" , corresponding to the
underlying SQLite transaction behaviour, implicit transaction management is performed.

Si no se sobreescribe por el parámetro isolation_level de connect() , el valor predeterminado es "" ,

que es un alias para "DEFERRED" .

Nota: Using autocommit to control transaction handling is recommended over using

isolation_level . isolation_level has no effect unless autocommit is set to
LEGACY_TRANSACTION_CONTROL (the default).

row_factory
The initial row_factory for Cursor objects created from this connection. Assigning to this attribute
does not affect the row_factory of existing cursors belonging to this connection, only new ones. Is

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 None by default, meaning each row is returned as a tuple .

See How to create and use row factories for more details.

text_factory
A callable that accepts a bytes parameter and returns a text representation of it. The callable is
invoked for SQLite values with the TEXT data type. By default, this attribute is set to str .

See How to handle non-UTF-8 text encodings for more details.

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=(), /)
Execute a single SQL statement, optionally binding Python values using placeholders.

Parámetros: sql (str) – A single SQL statement.

parameters ( dict | sequence) – Python values to bind to placeholders in sql. A
dict if named placeholders are used. A sequence if unnamed placeholders are
used. See Cómo usar marcadores de posición para vincular valores en consultas
SQL.
Muestra: ProgrammingError – If sql contains more than one SQL statement.

If autocommit is LEGACY_TRANSACTION_CONTROL , isolation_level is not None , sql is an

INSERT , UPDATE , DELETE , or REPLACE statement, and there is no open transaction, a transaction is
implicitly opened before executing sql.

Obsoleto desde la versión 3.12, se eliminará en la versión 3.14: DeprecationWarning is

emitted if named placeholders are used and parameters is a sequence instead of a dict .
Starting with Python 3.14, ProgrammingError will be raised instead.

Use executescript() to execute multiple SQL statements.

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 executemany(sql, parameters, /)
For every item in parameters, repeatedly execute the parameterized DML SQL statement sql.

Uses the same implicit transaction handling as execute() .

Parámetros: sql (str) – A single SQL DML statement.

parameters (iterable) – An iterable of parameters to bind with the placeholders in
sql. See Cómo usar marcadores de posición para vincular valores en consultas
SQL.
Muestra: ProgrammingError – If sql contains more than one SQL statement, or is not a DML
statement.

Ejemplo:

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

Nota: Any resulting rows are discarded, including DML statements with RETURNING clauses.

Obsoleto desde la versión 3.12, se eliminará en la versión 3.14: DeprecationWarning is

emitted if named placeholders are used and the items in parameters are sequences instead of
dict s. Starting with Python 3.14, ProgrammingError will be raised instead.

executescript(sql_script, /)
Execute the SQL statements in sql_script. If the autocommit is LEGACY_TRANSACTION_CONTROL and
there is a pending transaction, an implicit COMMIT statement is executed first. No other implicit
transaction control is performed; any transaction control must be added to 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()
If row_factory is None , return the next row query result set as a tuple . Else, pass it to the row
factory and return its result. Return None if no more data is available.

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 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
>>> con.close()

description

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 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
Read-only attribute that provides the number of modified rows for INSERT , UPDATE , DELETE , and
REPLACE statements; is -1 for other statements, including CTE queries. It is only updated by the
execute() and executemany() methods, after the statement has run to completion. This means that
any resulting rows must be fetched in order for rowcount to be updated.

row_factory
Control how a row fetched from this Cursor is represented. If None , a row is represented as a tuple .
Can be set to the included sqlite3.Row ; or a callable that accepts two arguments, a Cursor object
and the tuple of row values, and returns a custom object representing an SQLite row.

Defaults to what Connection.row_factory was set to when the Cursor was created. Assigning to
this attribute does not affect Connection.row_factory of the parent connection.

See How to create and use row factories for more details.
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.

Two Row objects compare equal if they have identical column names and values.

See How to create and use row factories for more details.

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 .

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 Distinto en la versión 3.5: Agrega soporte para segmentación.
Objetos fila (Row)

class sqlite3.Blob

Added in version 3.11.

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!'"

con.close()

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.

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 seek(offset, origin=os.SEEK_SET, /)
Set the current access position of the blob to offset. The origin argument defaults to os.SEEK_SET
(absolute blob positioning). Other values for origin are os.SEEK_CUR (seek relative to the current
position) and os.SEEK_END (seek relative to the blob’s end).
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

Added in version 3.11.

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

Added in version 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

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 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:

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 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.
Default adapters and converters (deprecated)

Nota: The default adapters and converters are deprecated as of Python 3.12. Instead, use the Ejemplos
para adaptadores y convertidores and tailor them to your needs.

The deprecated default adapters and converters consist of:

An adapter for datetime.date objects to strings in ISO 8601 format.

An adapter for datetime.datetime objects to strings in ISO 8601 format.
A converter for declared «date» types to datetime.date objects.
A converter for declared «timestamp» types to datetime.datetime objects. Fractional parts will be
truncated to 6 digits (microsecond precision).

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

Obsoleto desde la versión 3.12.

Command-line interface

The sqlite3 module can be invoked as a script, using the interpreter’s -m switch, in order to provide a simple
SQLite shell. The argument signature is as follows:

python -m sqlite3 [-h] [-v] [filename] [sql]

Type .quit or CTRL-D to exit the shell.

-h, --help
Print CLI help.

-v, --version

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 Print underlying SQLite library version.

Added in version 3.12.

Guías prácticas
Cómo usar marcadores de posición para vincular valores en consultas SQL

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. For example, an attacker can
simply close the single quote and inject OR TRUE to select all rows:

>>> # Never do this -- insecure! >>>

>>> symbol = input()
' OR TRUE; --
>>> sql = "SELECT * FROM stocks WHERE symbol = '%s'" % symbol
>>> print(sql)
SELECT * FROM stocks WHERE symbol = '' OR TRUE; --'
>>> cur.execute(sql)

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 whose length must match the
number of placeholders, or a ProgrammingError is raised. For the named style, parameters must be an
instance of a dict (or a subclass), which must contain keys for all named parameters; any extra items are
ignored. Here’s an example of both styles:

con = sqlite3.connect(":memory:")
cur = con.execute("CREATE TABLE lang(name, first_appeared)")

# This is the named style used with executemany():

data = (
{"name": "C", "year": 1972},
{"name": "Fortran", "year": 1957},
{"name": "Python", "year": 1991},
{"name": "Go", "year": 2009},
)
cur.executemany("INSERT INTO lang VALUES(:name, :year)", data)

# This is the qmark style used in a SELECT query:

params = (1972,)
cur.execute("SELECT * FROM lang WHERE first_appeared = ?", params)
print(cur.fetchall())
con.close()

Nota: PEP 249 numeric placeholders are not supported. If used, they will be interpreted as named
placeholders.

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

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
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])
con.close()

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])
con.close()

Como convertir valores SQLite a tipos de Python personalizados

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
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}"

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

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
# 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])
cur.close()
con.close()

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

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

def convert_timestamp(val):
"""Convert Unix epoch timestamp to datetime.datetime object."""
return datetime.datetime.fromtimestamp(int(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 .

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
# 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

A Connection object can be used as a context manager that automatically commits or rolls back open
transactions when leaving the body of the context manager. If the body of the with statement finishes without
exceptions, the transaction is committed. If this commit fails, or if the body of the with statement raises an
uncaught exception, the transaction is rolled back. If autocommit is False , a new transaction is implicitly
opened after committing or rolling back.

If there is no open transaction upon leaving the body of the with statement, or if autocommit is True , the
context manager does nothing.

Nota: The context manager neither implicitly opens a new transaction nor closes the connection. If you need
a closing context manager, consider using contextlib.closing() .

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:

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 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,)

con1.close()
con2.close()

Más información sobre esta característica, incluyendo una lista de opciones reconocidas, pueden encontrarse en
SQLite URI documentation.
How to create and use row factories

By default, sqlite3 represents each row as a tuple . If a tuple does not suit your needs, you can use the
sqlite3.Row class or a custom row_factory .

While row_factory exists as an attribute both on the Cursor and the Connection , it is recommended to set
Connection.row_factory , so all cursors created from the connection will use the same row factory.

Row provides indexed and case-insensitive named access to columns, with minimal memory overhead and
performance impact over a tuple . To use Row as a row factory, assign it to the row_factory attribute:

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

>>> con.row_factory = sqlite3.Row

Queries now return Row objects:

>>> res = con.execute("SELECT 'Earth' AS name, 6378 AS radius") >>>

>>> row = res.fetchone()
>>> row.keys()
['name', 'radius']
>>> row[0] # Access by index.
'Earth'
>>> row["name"] # Access by name.
'Earth'

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
>>> row["RADIUS"] # Column names are case-insensitive.
6378
>>> con.close()

Nota: The FROM clause can be omitted in the SELECT statement, as in the above example. In such cases,
SQLite returns a single row with columns defined by expressions, e.g. literals, with the given aliases expr AS
alias .

You can create a custom row_factory that returns each row as a dict , with column names mapped to values:

def dict_factory(cursor, row):

fields = [column[0] for column in cursor.description]
return {key: value for key, value in zip(fields, row)}

Using it, queries now return a dict instead of a tuple :

>>> 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}
>>> con.close()

The following row factory returns a named tuple:

from collections import namedtuple

def namedtuple_factory(cursor, row):

fields = [column[0] for column in cursor.description]
cls = namedtuple("Row", fields)
return cls._make(row)

namedtuple_factory() can be used as follows:

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

>>> con.row_factory = namedtuple_factory
>>> cur = con.execute("SELECT 1 AS a, 2 AS b")
>>> row = cur.fetchone()
>>> row
Row(a=1, b=2)
>>> row[0] # Indexed access.
1
>>> row.b # Attribute access.
2
>>> con.close()

With some adjustments, the above recipe can be adapted to use a dataclass , or any other custom class,
instead of a namedtuple .
How to handle non-UTF-8 text encodings

By default, sqlite3 uses str to adapt SQLite values with the TEXT data type. This works well for UTF-8
encoded text, but it might fail for other encodings and invalid UTF-8. You can use a custom text_factory to
handle such cases.

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
Because of SQLite’s flexible typing, it is not uncommon to encounter table columns with the TEXT data type
containing non-UTF-8 encodings, or even arbitrary data. To demonstrate, let’s assume we have a database with
ISO-8859-2 (Latin-2) encoded text, for example a table of Czech-English dictionary entries. Assuming we now
have a Connection instance con connected to this database, we can decode the Latin-2 encoded text using
this text_factory :

con.text_factory = lambda data: str(data, encoding="latin2")

For invalid UTF-8 or arbitrary data in stored in TEXT table columns, you can use the following technique,
borrowed from the CÓMO (HOWTO) Unicode:

con.text_factory = lambda data: str(data, errors="surrogateescape")

Nota: The sqlite3 module API does not support strings containing surrogates.

Ver también: CÓMO (HOWTO) Unicode

Explicación
Control transaccional

sqlite3 offers multiple methods of controlling whether, when and how database transactions are opened and
closed. Transaction control via the autocommit attribute is recommended, while Transaction control via the
isolation_level attribute retains the pre-Python 3.12 behaviour.

Transaction control via the autocommit attribute

The recommended way of controlling transaction behaviour is through the Connection.autocommit attribute,
which should preferably be set using the autocommit parameter of connect() .

It is suggested to set autocommit to False , which implies PEP 249-compliant transaction control. This means:

sqlite3 ensures that a transaction is always open, so connect() , Connection.commit() , and

Connection.rollback() will implicitly open a new transaction (immediately after closing the pending one,
for the latter two). sqlite3 uses BEGIN DEFERRED statements when opening transactions.
Transactions should be committed explicitly using commit() .
Transactions should be rolled back explicitly using rollback() .
An implicit rollback is performed if the database is close() -ed with pending changes.

Set autocommit to True to enable SQLite’s autocommit mode. In this mode, Connection.commit() and
Connection.rollback() have no effect. Note that SQLite’s autocommit mode is distinct from the PEP 249-
compliant Connection.autocommit attribute; use Connection.in_transaction to query the low-level
SQLite autocommit mode.

Set autocommit to LEGACY_TRANSACTION_CONTROL to leave transaction control behaviour to the

Connection.isolation_level attribute. See Transaction control via the isolation_level attribute for more
information.

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
Transaction control via the isolation_level attribute

Nota: The recommended way of controlling transactions is via the autocommit attribute. See Transaction
control via the autocommit attribute.

If Connection.autocommit is set to LEGACY_TRANSACTION_CONTROL (the default), transaction behaviour is

controlled using the Connection.isolation_level attribute. Otherwise, isolation_level has no effect.

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.

Distinto en la versión 3.12: The recommended way of controlling transactions is now via the autocommit
attribute.

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF