Cloudflare D1 para la Biblioteca

ADR — D1 para la Biblioteca

Contexto

CreaRackSL corre íntegramente en Cloudflare Pages + Workers. La Biblioteca es el sistema de grafo de conocimiento que mapea código fuente (endpoints, modelos, servicios, docs) a metadatos navegables y permite a agentes MCP responder preguntas sobre arquitectura del workspace.

Para que los Workers puedan consultar la Biblioteca en runtime — sin latencia de red adicional y sin salir del perímetro de Cloudflare — la BD debe estar disponible como binding nativo en el entorno Workers. Los agentes MCP que exponen bib_search_nodes, bib_get_node, bib_call_graph necesitan acceso síncrono y baja latencia a las 8 tablas del grafo (bib_nodes, bib_edges, bib_docs, bib_endpoints, bib_agents, bib_index_runs, bib_change_log, bib_federation).

Opciones evaluadas

1. Postgres de CreaRack (instancia compartida): la Postgres existente almacena datos de negocio (tareas, racks, facturación). Añadir tablas bib_* técnicamente posible, pero requeriría conexión TCP desde Workers via Hyperdrive o proxy externo. Introduce latencia variable, punto de fallo adicional, acoplamiento entre infra de negocio y de conocimiento.

2. Cloudflare D1 dedicada: SQLite gestionado por Cloudflare, accesible como binding directo en Workers (env.DB). No requiere red TCP: queries se ejecutan localmente en el mismo PoP. Schema compatible con SQLite por diseño (tipos TEXT, INTEGER, REAL; fechas como TEXT ISO8601; JSON como TEXT).

3. SQLite embebido en bundle del Worker: técnicamente viable para datos de solo lectura, inviable para grafo que se reindexa continuamente. No soporta escrituras concurrentes desde múltiples Workers.

Decisión

Cloudflare D1 con binding DB apuntando a base de datos crearacksl-workspace-db (ID e1e10da6-4f6e-4ccd-9afb-b5deebd61c25), declarado en wrangler.toml. Schema completo aplicado via migración 0008_create_biblioteca.sql que crea las 8 tablas e índices. Schema canónico en claude-method/biblioteca/schema.sql documenta Target: Cloudflare D1 (SQLite compatible), confirmando que el modelo se diseñó desde el inicio para este motor.

Consecuencias

Positivas:

• Latencia mínima desde Workers: mismo PoP, sin round-trip TCP.
• Binding declarativo en wrangler.toml; sin credenciales que gestionar.
• Compatibilidad total con SQLite: AUTOINCREMENT, ON DELETE CASCADE, datetime('now'), índices compuestos únicos.
• Aislamiento limpio: datos de negocio (Postgres) vs datos de conocimiento (D1).

Negativas/limitaciones:

• Límite 100 bind params por query. Inserciones masivas en bib_nodes/bib_edges deben fragmentarse en lotes (aprendido como footgun el 21-04-2026: el handler devolvía 200 con errors: ["too many SQL variables"] sin insertar nada).
• Tamaño máximo BD 2 GB (Workers Paid). Grafos muy grandes pueden requerir federación via bib_federation.
• Sin soporte RETURNING en versiones antiguas; código de indexación hace SELECT last_insert_rowid() separado si necesita ID generado.

Status

Accepted. Decisión vigente desde febrero 2026. Sin planes de migración a Postgres mientras el grafo permanezca bajo límite de tamaño de D1.

Véase también

• [[concept—biblioteca—supercontexto]]
• [[incident—20260421—d1-bind-overflow-silent]] — incidente que materializó el footgun de los 100 binds