ATTACH DATABASE en SQLite: consultar varios archivos

Una sola conexión, varios archivos

Una conexión de SQLite no está atada a un único archivo. Con ATTACH DATABASE puedes abrir archivos .db adicionales junto al que ya tenías abierto y consultarlos como si fueran esquemas dentro de una misma base de datos. Es lo más parecido que ofrece SQLite a tener "varias bases de datos en un mismo servidor".

La sintaxis básica es la siguiente:

ATTACH DATABASE 'archive.db' AS archive;

CREATE TABLE archive.old_orders (
    id INTEGER PRIMARY KEY,
    customer TEXT,
    total REAL
);

INSERT INTO archive.old_orders VALUES (1, 'Rosa', 49.99);

SELECT * FROM archive.old_orders;

El archivo archive.db se crea si no existe, igual que ocurre con la base de datos principal. A partir de aquí, dentro de esta sesión, todo lo que lleve el prefijo archive. vive en ese segundo archivo, y todo lo que lleve main. (o vaya sin prefijo) sigue viviendo en el original.

Tu conexión siempre arrastra dos esquemas implícitos: main (el archivo que abriste primero) y temp (un espacio temporal para tablas auxiliares). Al adjuntar una base de datos, sumas más esquemas a esa lista.

Sintaxis de ATTACH DATABASE y para qué sirve el alias

ATTACH DATABASE 'ruta/al/archivo.db' AS nombre_alias;

El alias es el nombre de esquema que vas a usar para calificar las tablas. Es local a la conexión actual: otra conexión que adjunte el mismo archivo puede elegir un alias distinto. Conviene que sea corto y descriptivo (archive, analytics, cache), porque lo vas a escribir muchas veces.

Un par de cosas que vale la pena tener en cuenta:

• La ruta es relativa al directorio de trabajo del proceso, salvo que sea absoluta.
• La cadena ':memory:' adjunta una base de datos en memoria nueva bajo ese alias.
• El alias no puede chocar con main ni temp, ni repetirse entre adjuntos.

Hacer JOIN entre bases SQLite

Esta es la razón por la que la mayoría recurre a ATTACH DATABASE. En cuanto tienes dos archivos dentro de la misma conexión, puedes hacer un join entre sus tablas en una sola consulta:

ATTACH DATABASE ':memory:' AS archive;

CREATE TABLE main.customers (id INTEGER PRIMARY KEY, name TEXT);
CREATE TABLE archive.orders (id INTEGER, customer_id INTEGER, total REAL);

INSERT INTO main.customers VALUES (1, 'Rosa'), (2, 'Boris');
INSERT INTO archive.orders VALUES (101, 1, 49.99), (102, 2, 12.50);

SELECT c.name, o.total
FROM main.customers AS c
JOIN archive.orders AS o ON o.customer_id = c.id;

El planificador de consultas trata ambos esquemas igual que las tablas de main. Los índices de las tablas adjuntas se aprovechan sin problema. EXPLAIN QUERY PLAN funciona entre ellas. No hay ida y vuelta por red: los dos archivos están abiertos en el mismo proceso.

Esto resulta realmente útil para separar datos calientes de archivos históricos, aislar archivos por tenant o extraer datos de referencia desde una base de solo lectura.

Adjuntar bases en solo lectura y en memoria

Si la segunda base es algo que quieres leer pero nunca modificar —por ejemplo, un dataset de referencia que distribuyes con tu aplicación—, adjúntala en modo solo lectura usando una URI:

ATTACH DATABASE 'file:reference.db?mode=ro' AS ref;

La forma URI requiere que la biblioteca SQLite tenga habilitado SQLITE_OPEN_URI (viene activado en la CLI y en la mayoría de bindings de cada lenguaje). Con esto, cualquier INSERT, UPDATE o DELETE sobre ref.* lanzará un error antes siquiera de tocar el archivo.

Adjuntar una base de datos en memoria resulta igual de útil para preparar datos temporales:

ATTACH DATABASE ':memory:' AS scratch;

CREATE TABLE scratch.tmp_results AS
SELECT customer_id, SUM(total) AS spend
FROM main.orders
GROUP BY customer_id;

SELECT * FROM scratch.tmp_results ORDER BY spend DESC LIMIT 5;

scratch desaparece al cerrar la conexión. Funciona como temp, pero el ciclo de vida lo controlas tú.

Las transacciones abarcan todas las bases adjuntas

Un único BEGIN/COMMIT cubre las escrituras tanto en main como en cualquier esquema adjunto. O se confirma todo, o se revierte todo: la atomicidad se mantiene aunque haya varios archivos de por medio.

ATTACH DATABASE ':memory:' AS archive;

CREATE TABLE main.orders (id INTEGER PRIMARY KEY, total REAL);
CREATE TABLE archive.orders (id INTEGER PRIMARY KEY, total REAL);

BEGIN;
    INSERT INTO archive.orders SELECT * FROM main.orders WHERE id < 100;
    DELETE FROM main.orders WHERE id < 100;
COMMIT;

Mover filas de una tabla viva a un archivo de archivado histórico es justo el caso donde te interesa esta garantía. Sin atomicidad entre archivos, una caída a mitad de la operación te dejaría con duplicados o, peor aún, con filas perdidas.

Un detalle a tener en cuenta: cuando una misma transacción escribe en más de una base adjunta, SQLite recurre a un protocolo de commit más prudente que necesita un journal temporal. Es más lento que un commit sobre un único archivo, pero igual de seguro.

Desadjuntar una base de datos

Cuando ya no necesites una base adjunta, suéltala:

DETACH DATABASE archive;

El archivo sigue intacto en el disco — DETACH simplemente cierra el handle en la conexión actual. Dos restricciones que conviene recordar:

• No puedes desadjuntar main ni temp.
• No puedes desadjuntar una base de datos que esté dentro de una transacción o tenga sentencias abiertas contra ella.

Y si se te olvida hacer detach, tampoco pasa nada grave: al cerrar la conexión se limpia todo automáticamente.

Límites y errores frecuentes

Hay algunos límites prácticos que vale la pena tener presentes:

• El tope por defecto es de 10 bases de datos adjuntas por conexión (sin contar main y temp). El máximo en tiempo de compilación es 125. Si te pasas, verás el mensaje too many attached databases - max 10.
• Cada archivo adjunto consume su propia caché de páginas. Adjuntar una docena de bases grandes no sale gratis — la RAM sube.
• ATTACH no se puede ejecutar dentro de una transacción. Hazlo antes del BEGIN, o después del COMMIT.

Estos son algunos de los errores con los que te vas a topar:

-- El archivo no existe y el directorio no permite escritura:
Error: unable to open database: 'missing/path.db'

-- Intentaste escribir en un adjunto de solo lectura:
Error: attempt to write a readonly database

-- Usaste el mismo alias dos veces:
Error: database archive is already in use

La mayoría de estos errores se entienden a la primera. El que más despista es el de "alias ya en uso": ATTACH no reemplaza un alias existente, así que toca hacer DETACH antes.

Un patrón realista: separación hot/cold

Vamos a juntar todo lo visto en un mini flujo de archivado que mueve los pedidos con más de un año de antigüedad fuera de la base de datos principal:

ATTACH DATABASE ':memory:' AS archive;

CREATE TABLE main.orders (
    id INTEGER PRIMARY KEY,
    placed_at TEXT,
    total REAL
);
CREATE TABLE archive.orders AS SELECT * FROM main.orders WHERE 0;

INSERT INTO main.orders VALUES
    (1, '2022-06-01', 19.99),
    (2, '2024-11-15', 49.50),
    (3, '2025-08-22', 12.00);

BEGIN;
    INSERT INTO archive.orders
        SELECT * FROM main.orders WHERE placed_at < date('now', '-1 year');
    DELETE FROM main.orders WHERE placed_at < date('now', '-1 year');
COMMIT;

SELECT 'main' AS db, COUNT(*) FROM main.orders
UNION ALL
SELECT 'archive', COUNT(*) FROM archive.orders;

Las filas antiguas se mueven a archive.orders y las recientes se quedan en main. Los reportes que necesitan histórico pueden hacer join entre ambas, mientras que las consultas del día a día contra main.orders siguen siendo rápidas porque la tabla es más pequeña. Una sola conexión, dos archivos, una transacción.

Lo que viene: sentencias preparadas

ATTACH se trata de darle a una misma conexión acceso a más datos. El siguiente bloque de temas va por otro lado: cómo las aplicaciones se comunican con SQLite de forma segura y eficiente. Arrancamos con las sentencias preparadas, la base del binding de parámetros y de las consultas a prueba de inyección SQL.