Saltearse al contenido

Actualizaciones

Versionado

Las superficies publicadas siguen Semantic Versioning: los binarios del servidor y de la CLI, las superficies HTTP, Bolt y Cypher, el paquete de Python, las imágenes de contenedor y los formatos en disco. Un cambio incompatible sube la versión mayor y aparece bajo Incompatible en el changelog. Las versiones menores y de parche todavía pueden cambiar detalles en disco de forma compatible hacia adelante, lo que importa para volver a versiones anteriores (ver más abajo).

Las imágenes de contenedor se etiquetan como X.Y.Z, X.Y, X y latest. Fija X.Y.Z en producción y actualiza de forma deliberada.

Procedimiento

Un namespace tiene exactamente un writer, así que no ejecutes servidores viejos y nuevos sobre el mismo namespace a la vez: se bloquean entre sí.

  1. Lee las notas de versión entre tu versión y la de destino, en especial las entradas Incompatible y Nota de actualización.
  2. Haz backup de cada namespace que sirves (Backup y restore). Un backup tomado antes de actualizar es la única forma de volver atrás si la versión nueva reescribe archivos de datos en un formato que la anterior no puede leer.
  3. Detén el servidor viejo (SIGTERM; termina las peticiones en curso y sale).
  4. Inicia la versión nueva sobre el mismo store y con la misma configuración.
  5. Comprueba GET /v0/version, GET /v0/health (200, writer: "ok") y el log de arranque, y luego ejecuta algunas consultas representativas.
  6. Opcionalmente ejecuta POST /v0/admin/compact para pasar antes los archivos de datos viejos al formato nuevo; si no, la compactación lo hace a medida que reescribe los datos.

Para el cliente de Python, actualiza el wheel (pip install -U namidb==X.Y.Z) en cada proceso que abre el namespace; detén los writers antes de cambiar de versión, como arriba.

Si un orquestador reemplaza instancias con superposición, ejecuta todas las instancias con --fence-policy yield, para que un writer reemplazado deje de escribir y se reporte como degradado en lugar de reclamar el namespace.

Volver a una versión anterior

Volver atrás solo es seguro hacia una versión que pueda leer todo lo que escribió la más nueva. Ante la duda, restaura el backup previo a la actualización en la versión anterior.

DesdeHaciaRegla
3.1.x o posterior3.0.xHaz flush primero (POST /v0/admin/flush). 3.1 escribe el formato de WAL v2, que 3.0 rechaza.
3.x2.xNo es posible en el lugar una vez que 3.x escribió o compactó archivos de datos: 2.x falla al leerlos con errores corrupted artefact. Restaura un backup tomado antes de actualizar.

Notas por versión

3.3.0

  • Sin cambios de formato en disco. 3.3.0 y 3.2.x pueden reemplazarse entre sí en el mismo lugar. Los leases de retención que escribe 3.3.0 llevan un alcance; 3.2.x lee cada lease como un piso, lo que conserva más historial, nunca menos.
  • Los puntos de restauración vienen desactivados. Activarlos (--restore-point-retention) requiere --compaction-interval mayor que cero, o el servidor se niega a arrancar. Calcula antes el almacenamiento extra: aproximadamente lo que cada namespace escribe durante la ventana. La ventana empieza vacía y se llena a partir de ahí.
  • Los timeouts y la cancelación ahora detienen cualquier operador. Las sentencias que antes seguían más allá de --query-timeout (productos cartesianos, ordenamientos y agregaciones grandes sobre filas ya en memoria) ahora fallan en el deadline con 504 timeout. Si un proceso dependía de eso, sube su presupuesto o acota la consulta.

3.2.1

  • Presupuesto de memoria por consulta. Un servidor que define NAMIDB_MEMORY_MAX_BYTES ahora también limita cada sentencia en ejecución a la mitad de ese tope, y todas las sentencias en ejecución juntas al 75%. Una consulta que necesita más que su presupuesto falla con 413 query_memory_limit en lugar de crecer hasta que matan el proceso. Antes de actualizar, comprueba que tus consultas legítimas más grandes caben; dimensiona o desactiva el presupuesto con NAMIDB_QUERY_MEMORY_MAX_BYTES (0 lo desactiva). Los servidores sin tope no cambian. Ver Memoria.
  • El 503 de una sentencia rechazada en la admisión de memoria ahora tiene un cuerpo JSON con code: "memory_pressure", neo4j_code y gql_status; el texto de error no cambia.
  • No hay cambios de formato en disco: 3.2.1 y 3.2.0 pueden reemplazarse entre sí en el mismo lugar.

3.2.0

  • La allowlist de backups se aplica sobre URIs parseados. to (backup) y from (restore) deben usar el esquema y el bucket del prefijo, quedar en su ruta o por debajo, y repetir exactamente sus parámetros de consulta. Pon las opciones del store en --backup-target-uri (s3://bucket/backups?endpoint=…&region=…) y haz que los clientes las repitan; una petición que agrega o cambia alguna ahora se rechaza con 403.
  • Claves numéricas declaradas antes que los datos. Una restricción de unicidad o un índice declarado sobre un label vacío ahora toma el tipo del primer valor escrito, así que las claves numéricas obtienen su índice. Un namespace cuyo manifest de 3.1.0 ya confirmó esa declaración como string la conserva; vuelve a cargar ese label en un namespace nuevo para obtener el índice numérico.
  • Nuevo: POST /:namespace/v0/admin/restore en modo multi-tenant.

3.1.0

  • Los vectores, bytes y listas de números se escriben en el WAL en binario (formato de WAL v2). 3.0.0 no puede leer los segmentos nuevos; haz flush antes de volver atrás.

3.0.0

Cambios incompatibles:

  • Formato de archivos de datos. Los archivos de datos de nodos y sus side-cars de registros exactos usan una organización nueva que 2.x no puede leer. 3.0 lee los archivos de 2.x y los convierte a medida que la compactación los reescribe. Volver atrás requiere un backup anterior a la actualización.
  • CALL algo.* rechaza las opciones desconocidas en lugar de ignorarlas (algo.louvain({seed: 1}) ahora da error). Quita las claves sobrantes.
  • algo.shortest_path produce una cuarta columna, path. Las llamadas que hacen YIELD de columnas por nombre no se ven afectadas; los clientes que leen columnas por posición sí.
  • MATCH nunca vincula la misma relación dos veces en un patrón, y un OPTIONAL MATCH hace match con su patrón completo o con nada. Algunas consultas retornan menos filas (correctas).
  • Python: merge_nodes ahora fusiona en nodos existentes (el comportamiento anterior de reemplazo es put_nodes), y las filas de carga masiva toman el id del nodo de _id (las filas identificadas con id siguen funcionando y además conservan id como propiedad).

También nuevo en 3.0: clientes de Python de solo lectura, timeout_ms / max_rows, --fence-policy, NAMIDB_MAX_CONCURRENT_QUERIES_PER_NAMESPACE, y transacciones de lectura de Bolt que ya no toman el lock del writer.

Si vienes de 2.x

  • Desde 2.2.0 el servidor se niega a arrancar sin una fuente de autenticación; define un token o pasa --no-auth explícitamente.
  • Desde 2.2.0 la imagen oficial corre como uid 65532; los directorios de datos con bind mount necesitan chown -R 65532:65532.
  • Los códigos de error de Bolt para timeouts y límites de resultados cambiaron en 2.2.0 (Neo.ClientError.Transaction.TransactionTimedOut, Neo.ClientError.Statement.ResourceLimitExceeded).

El historial completo está en el changelog y en el CHANGELOG.md del motor.