Docs ejecutables de SQLite: INSERT

Q: ¿Cómo se inserta una fila en SQLite?

Con INSERT INTO tabla (col1, col2) VALUES (val1, val2);. Listar las columnas es opcional, pero muy recomendable: así la sentencia sigue funcionando aunque más adelante añadas una columna a la tabla. Si no indicas la lista de columnas, tienes que pasar un valor por cada columna y en el orden exacto en que se declararon.

Q: ¿Cómo inserto varias filas a la vez en SQLite?

Pones varias tuplas entre paréntesis después de VALUES, separadas por comas: INSERT INTO t (a, b) VALUES (1, 2), (3, 4), (5, 6);. Para cargas grandes de verdad (miles de filas), envuelve los inserts en una única transacción con BEGIN y COMMIT: ahí está la mejora de rendimiento, no en la sintaxis multi-fila en sí.

Q: ¿Qué hace INSERT OR IGNORE en SQLite?

INSERT OR IGNORE se salta las filas que violarían una restricción UNIQUE, PRIMARY KEY o NOT NULL en lugar de lanzar un error. La fila conflictiva se descarta silenciosamente y el resto de la sentencia sigue adelante. Es ideal cuando quieres un comportamiento tipo 'inserta si todavía no existe' sin tener que hacer una consulta previa de existencia.

INSERT: añadir filas a una tabla en SQLite

INSERT es la sentencia que usamos para insertar filas en SQLite. Su forma es corta y predecible:

CREATE TABLE books (
    id     INTEGER PRIMARY KEY,
    title  TEXT NOT NULL,
    author TEXT,
    year   INTEGER
);

INSERT INTO books (title, author, year)
VALUES ('La mano izquierda de la oscuridad', 'Ursula K. Le Guin', 1969);

SELECT * FROM books;

Tres partes a las que prestar atención:

INSERT INTO books: la tabla de destino.
(title, author, year): las columnas para las que estás aportando valores.
VALUES (...): los valores, en el mismo orden que la lista de columnas.

Fíjate en que id no aparece en la lista de columnas, así que SQLite lo asigna automáticamente (es un INTEGER PRIMARY KEY, que recibe el rowid). Cualquier columna que omitas toma su valor por defecto, o NULL si no tiene uno definido.

Lista siempre tus columnas

Puedes omitir la lista de columnas y proporcionar valores para todas ellas en el orden en que se declararon:

-- Funciona, pero es frágil:
INSERT INTO books VALUES (NULL, 'Dune', 'Frank Herbert', 1965);

No lo hagas. En el momento en que alguien añada una columna a books, cualquier sentencia escrita así se rompe o empieza a meter valores en la columna equivocada. Indica las columnas de forma explícita:

CREATE TABLE books (
    id     INTEGER PRIMARY KEY,
    title  TEXT NOT NULL,
    author TEXT,
    year   INTEGER
);

INSERT INTO books (title, author, year)
VALUES ('Dune', 'Frank Herbert', 1965);

SELECT id, title, year FROM books;

Las listas explícitas de columnas son una forma de documentación: hacen que la sentencia se entienda por sí sola, sin tener que ir a buscar la definición de la tabla.

Insertar varias filas en SQLite

Puedes insertar varias filas en una sola sentencia añadiendo más tuplas de valores:

CREATE TABLE books (
    id     INTEGER PRIMARY KEY,
    title  TEXT NOT NULL,
    author TEXT,
    year   INTEGER
);

INSERT INTO books (title, author, year) VALUES
    ('Dune', 'Frank Herbert', 1965),
    ('Neuromancer', 'William Gibson', 1984),
    ('Hyperion', 'Dan Simmons', 1989);

SELECT count(*) AS total FROM books;

Esto queda más limpio que escribir tres INSERT por separado, y SQLite lo procesa como una sola sentencia. Eso sí, la verdadera ganancia de rendimiento al insertar varias filas en SQLite viene de envolver los INSERT dentro de una transacción — lo vemos a continuación.

SQLite bulk insert: agrúpalos en una transacción

Por defecto, cada INSERT es su propia transacción. SQLite hace un fsync al terminar cada una, y eso es justo lo que vuelve lentos los bucles ingenuos — no los inserts en sí.

Agrúpalos así:

CREATE TABLE numbers (n INTEGER);

BEGIN;
INSERT INTO numbers (n) VALUES (1);
INSERT INTO numbers (n) VALUES (2);
INSERT INTO numbers (n) VALUES (3);
INSERT INTO numbers (n) VALUES (4);
INSERT INTO numbers (n) VALUES (5);
COMMIT;

SELECT count(*) AS total, sum(n) AS total_sum FROM numbers;

Un único fsync en lugar de cinco. Cuando hablamos de miles de filas, la diferencia puede ser de dos o tres órdenes de magnitud. Y si algo falla por el camino, ROLLBACK deshace el lote completo.

Este patrón es la receta clásica para hacer bulk insert en SQLite. Da igual si estás llamando a SQLite desde Python, Node o Rust: envuelve tu bucle entre BEGIN y COMMIT y listo.

INSERT ... SELECT: copiar datos desde otra tabla

Puedes poblar una tabla a partir de una consulta en vez de usar valores literales:

CREATE TABLE books (
    id     INTEGER PRIMARY KEY,
    title  TEXT NOT NULL,
    year   INTEGER
);
INSERT INTO books (title, year) VALUES
    ('Dune', 1965), ('Neuromancer', 1984), ('Hyperion', 1989);

CREATE TABLE classics (title TEXT, year INTEGER);

INSERT INTO classics (title, year)
SELECT title, year FROM books WHERE year < 1980;

SELECT * FROM classics;

Las columnas del SELECT se emparejan por posición con la lista de columnas del INSERT. Los nombres no tienen que coincidir, pero el orden sí. Esta es la forma habitual de archivar filas, armar tablas de reportes o copiar un subconjunto de datos durante una migración.

DEFAULT VALUES y columnas omitidas

Si una columna tiene una cláusula DEFAULT, puedes omitirla de la lista de columnas y SQLite se encarga de rellenar el valor por defecto:

CREATE TABLE events (
    id         INTEGER PRIMARY KEY,
    name       TEXT NOT NULL,
    created_at TEXT DEFAULT (datetime('now'))
);

INSERT INTO events (name) VALUES ('registro');
INSERT INTO events (name) VALUES ('inicio_sesion');

SELECT * FROM events;

created_at toma la marca de tiempo actual porque no le pasamos ninguna. Si quieres crear una fila usando solo valores por defecto —algo útil para insertar filas de relleno en SQLite—, usa la variante DEFAULT VALUES:

CREATE TABLE counters (
    id    INTEGER PRIMARY KEY,
    value INTEGER DEFAULT 0
);

INSERT INTO counters DEFAULT VALUES;
INSERT INTO counters DEFAULT VALUES;

SELECT * FROM counters;

Dos filas nuevas, ambas con value = 0 e ids autoasignados.

INSERT OR IGNORE: cómo insertar si no existe en SQLite

Cuando una fila viola una restricción UNIQUE o PRIMARY KEY, el comportamiento por defecto es abortar la sentencia con un error:

Error: UNIQUE constraint failed: users.email

INSERT OR IGNORE lo cambia por "ignora la fila conflictiva sin avisar":

Human Created Furniture Marketplace

DreamShop24

Hello, dear visitor!

Promo banner image Categories Up to 70% Off Sale 0% Loading...

CREATE TABLE users (
    id    INTEGER PRIMARY KEY,
    email TEXT UNIQUE NOT NULL
);

INSERT INTO users (email) VALUES ('ada@example.com');

INSERT OR IGNORE INTO users (email) VALUES
    ('ada@example.com'),    -- duplicado, omitido
    ('boris@example.com'),  -- insertado
    ('rosa@example.com');   -- insertado

SELECT * FROM users;

Sobreviven tres filas. El duplicado se descarta sin generar error. Esta es la forma idiomática en SQLite de expresar insertar si no existe para datos semilla simples: sin un SELECT previo para comprobar, sin manejo de excepciones.

INSERT OR REPLACE: sobrescribir duplicados

INSERT OR REPLACE elimina la fila en conflicto e inserta la nueva en su lugar:

CREATE TABLE settings (
    key   TEXT PRIMARY KEY,
    value TEXT
);

INSERT INTO settings (key, value) VALUES ('theme', 'light');

INSERT OR REPLACE INTO settings (key, value) VALUES ('theme', 'dark');

SELECT * FROM settings;

Cuidado con un detalle: REPLACE equivale a DELETE + INSERT, no a UPDATE. Si la fila eliminada tenía claves foráneas apuntando a ella con ON DELETE CASCADE, los hijos también se borran. Y cualquier columna que no incluyas en el nuevo INSERT vuelve a su valor por defecto: no conserva el valor anterior.

Para la mayoría de casos del tipo "actualiza si existe, inserta si no", lo que de verdad quieres es un upsert real con ON CONFLICT ... DO UPDATE. Eso lo vemos en su propia página.

Repaso rápido

INSERT INTO tabla (columnas) VALUES (...) — la forma básica. Lista siempre las columnas.
Para insertar varias filas en SQLite, usa tuplas separadas por comas después de VALUES.
Si vas a hacer un bulk insert de verdad, envuelve los INSERT entre BEGIN y COMMIT.
INSERT INTO ... SELECT ... copia filas a partir de una consulta.
DEFAULT VALUES crea una fila usando solo los valores por defecto; las columnas que omitas también caen a su valor por defecto.
INSERT OR IGNORE ignora las filas que provoquen conflicto; INSERT OR REPLACE las sobrescribe (mediante delete + insert).

Lo que viene: UPDATE

Insertar filas es solo la mitad de la historia. La otra mitad es modificar las que ya existen: incrementar un contador, corregir una errata, marcar un pedido como enviado. De eso se encarga UPDATE, y tiene sus propias mañas que conviene dominar (sobre todo la cláusula WHERE). Lo vemos a continuación.

Preguntas frecuentes

¿Cómo se inserta una fila en SQLite?

Con INSERT INTO tabla (col1, col2) VALUES (val1, val2);. Listar las columnas es opcional, pero muy recomendable: así la sentencia sigue funcionando aunque más adelante añadas una columna a la tabla. Si no indicas la lista de columnas, tienes que pasar un valor por cada columna y en el orden exacto en que se declararon.

¿Cómo inserto varias filas a la vez en SQLite?

Pones varias tuplas entre paréntesis después de VALUES, separadas por comas: INSERT INTO t (a, b) VALUES (1, 2), (3, 4), (5, 6);. Para cargas grandes de verdad (miles de filas), envuelve los inserts en una única transacción con BEGIN y COMMIT: ahí está la mejora de rendimiento, no en la sintaxis multi-fila en sí.

¿Qué hace INSERT OR IGNORE en SQLite?

INSERT OR IGNORE se salta las filas que violarían una restricción UNIQUE, PRIMARY KEY o NOT NULL en lugar de lanzar un error. La fila conflictiva se descarta silenciosamente y el resto de la sentencia sigue adelante. Es ideal cuando quieres un comportamiento tipo 'inserta si todavía no existe' sin tener que hacer una consulta previa de existencia.

¿Por qué me sale 'UNIQUE constraint failed' al hacer INSERT?

SQLite ha encontrado una fila ya existente con el mismo valor en una columna UNIQUE o PRIMARY KEY. O bien el valor está duplicado de verdad, o estás reejecutando un script de carga inicial. Cámbialo a INSERT OR IGNORE para ignorar duplicados, a INSERT OR REPLACE para sobrescribirlos, o usa ON CONFLICT ... DO UPDATE (upsert) si quieres un control más fino.

Conceptos relacionados

INSERT en SQLite: insertar filas, bulk insert y OR IGNORE