Skip to Content
Desarrollo de apps IoTBackend de datos

Backend de datos

IronFlock aprovisiona una base de datos privada para cada proyecto, impulsada por TimescaleDB. Tu aplicación define el esquema de datos; IronFlock crea las tablas y comienza a recopilar datos en el momento en que se agrega un dispositivo a la aplicación.

Cómo funciona

  1. Define tu esquema de datos en .ironflock/data-template.yml.
  2. Usa el SDK de IronFlock para publicar datos desde tu código edge.
  3. IronFlock configura automáticamente las tablas de la base de datos en cada proyecto donde se instala la aplicación.
  4. Los datos fluyen desde los dispositivos a través del sistema de mensajería hacia la base de datos del proyecto.

Cada proyecto obtiene su propia base de datos física — no hay intercambio de datos entre proyectos.

El usuario tiene control total sobre los datos recopilados por tu aplicación en su proyecto. Como desarrollador, no tienes acceso a estos datos.

Definir el esquema de datos

Crea un archivo data-template.yml en el directorio .ironflock/:

data: tables: - tablename: sensordata columns: - id: tsp name: Timestamp description: Timestamp of measurement path: args[0].timestamp dataType: timestamp - id: temperature name: Temperature description: Temperature reading in Celsius path: args[0].temperature dataType: numeric - id: humidity name: Humidity description: Relative humidity percentage path: args[0].humidity dataType: numeric - id: device_id name: Device ID description: Source device identifier path: args[0].device_id dataType: string

Opciones de columna

CampoDescripción
idIdentificador interno de la columna (usa tsp para columnas de marca temporal)
nameNombre legible de la columna que se muestra en los paneles
descriptionDescripción opcional
pathRuta al valor en el objeto de datos publicado (por ejemplo, args[0].temperature)
dataTypeUno de: timestamp, numeric, string, boolean
secretCifra esta columna en reposo y nunca la devuelve en claro en una lectura normal — consulta Columnas secretas más abajo

Columnas secretas

Algunos valores hay que almacenarlos pero nunca deben mostrarse: un token de API, la contraseña de un dispositivo, una clave de licencia. Marca la columna con secret: true y el backend de datos la cifra al insertarla:

- tablename: credentials columns: - id: tsp dataType: timestamp - id: device_id dataType: string - id: api_token dataType: string secret: true

A partir de ese momento ninguna lectura ordinaria devuelve el texto en claro — ni siquiera a la app que lo escribió:

Ruta de lecturaLo que recibes
Lecturas de historial y filas en tiempo real: lo que reciben los boards, los widgets, el SDK y las demás apps que leen la tablael marcador de posición __secret__
SQL (la consola de consultas SQL, las exportaciones de datos y el inicio de sesión de Postgres de FleetDB Access) y las copias de seguridad de la base de datosel texto cifrado almacenado, ifsec:1:…
La función de revelado del SDKel valor descifrado

NULL sigue siendo NULL en todas partes, así que establecido pero oculto se sigue distinguiendo de nunca escrito.

Leer un secreto en claro solo es posible desde los propios contenedores de la app, a través del SDK — consulta Columnas secretas en la referencia del SDK. Los boards y las demás apps no pueden obtenerlo en absoluto, y eso es lo que hace que nunca se muestra en claro sea cierto y no meramente cosmético.

Actualizar una fila sin perder su secreto. En una tabla de entidades, un cliente que edita una fila nunca puede devolver el secreto real — las lecturas solo le dieron el marcador de posición. Por eso, al escribir, el backend de datos trata el marcador de posición __secret__ (y la máscara •••••••• que muestran los boards) como conservar el valor anterior, y una columna secreta omitida también lo conserva. Enviar un null explícito borra el secreto. Editar la descripción de una máquina en un formulario de un board, por tanto, nunca arrasa su código de acceso.

De ahí se derivan dos consecuencias: las cadenas literales __secret__ y •••••••• no pueden almacenarse a su vez como valores secretos (y el texto cifrado en bruto ifsec:… se rechaza como entrada), y en una tabla sin clave de entidad una escritura del marcador de posición se rechaza — no hay fila anterior que conservar.

Conviene planificar teniendo en cuenta tres consecuencias, porque son límites estrictos y no meras recomendaciones:

  • Las columnas secretas solo admiten cadenas. El cifrado produce texto, así que las columnas numeric, boolean y timestamp no pueden ser secretas. La columna obligatoria tsp tampoco puede ser secreta.
  • No puedes filtrar, agrupar ni ordenar por una columna secreta. Cada fila se cifra con su propio valor aleatorio, así que dos filas que contienen el mismo secreto almacenan textos cifrados distintos. Los filtros de igualdad, GROUP BY, ORDER BY y DISTINCT sobre una columna secreta simplemente no pueden funcionar. Para responder a ¿coincide este valor?, usa la función de verificación del SDK, que compara dentro del backend de datos en lugar de devolver nada.
  • Una columna secreta no puede ser una clave de entidad. Como el texto cifrado difiere en cada fila, las lecturas de último estado por entidad tratarían cada fila como una entidad propia, así que nombrar una en maintainLatestFlagFor se rechaza de plano.

Las dos últimas restricciones se comprueban al validar tu plantilla de datos, así que una tabla que las incumple falla al publicarla en lugar de comportarse mal más adelante.

Opciones de tabla

Además de columns, una tabla admite algunas claves opcionales que controlan cómo se describe y cómo envejecen sus datos:

data: tables: - tablename: sensordata description: Lecturas ambientales de la planta chunkTimeInterval: 1 hour dropAfter: 30 days columns: # ...
CampoDescripción
tablenameNombre de la tabla
descriptionDescripción opcional, mostrada en la interfaz y usada por los agentes de IA para entender la tabla
chunkTimeIntervalTamaño de las particiones temporales en que se divide la tabla. Por defecto 7 days
dropAfterVentana de retención — las particiones más antiguas se eliminan automáticamente
downsampleMantener una copia preagregada para gráficos rápidos de ventana larga — consulta Submuestreo continuo más abajo
maintainLatestFlagForColumnas que identifican una entidad única — consulta Seguimiento del último estado de una entidad más abajo
privateOcultar esta tabla a las demás apps — consulta Compartir datos con otras apps más abajo

chunkTimeInterval controla cómo se particionan en disco los datos de series temporales. Elígelo de modo que una partición se corresponda aproximadamente con lo que consultas de una vez: los datos de alta frecuencia recogidos cada segundo se benefician de chunks pequeños (de minutos a horas), y los datos que cambian despacio, de chunks grandes (semanas). Esto es solo el valor por defecto de la app — el propietario del proyecto puede ajustarlo después en su propio data backend.

dropAfter convierte la tabla en una ventana deslizante. Se eliminan particiones enteras más antiguas que el intervalo indicado, lo que resulta mucho más económico que borrar filas una a una. La tarea de limpieza se ejecuta con una frecuencia de dropAfter / 4, así que un registro puede sobrevivir a su caducidad hasta un cuarto del intervalo antes de que desaparezca su partición. Omite dropAfter para conservar los datos indefinidamente.

Ambos aceptan cadenas de intervalo de PostgreSQL — 30 minutes, 1 hour, 7 days, 6 months.

Submuestreo continuo

Los dashboards pueden pedir a la base de datos que agregue los datos — promedios horarios, totales diarios, recuentos por máquina. Calcularlos a partir de los registros en bruto está bien para un día y sale caro para un año. Añade downsample a una tabla y la plataforma mantiene una copia preagregada de ella, actualizada de forma continua, y responde desde esa copia las consultas de ventana larga:

data: tables: - tablename: sensordata dropAfter: 30 days downsample: bucket: 1 minute keepFor: 2 years paths: - payload.temperature columns: # ...
CampoDescripción
bucketGranularidad de la copia preagregada. Por defecto 1 minute
keepForCuánto tiempo se conserva el historial submuestreado. Omítelo para conservarlo indefinidamente
pathsRutas de campos JSON a incluir, en la misma notación que usan los dashboards

bucket es la resolución más fina desde la que se puede servir un gráfico — un gráfico que pida intervalos mucho más finos que este lee la tabla en bruto en su lugar. Acepta intervalos de anchura fija desde 1 second hasta 1 day que dividan el día de forma exacta (1 minute, 5 minutes, 1 hour). El valor por defecto de 1 minute sirve para prácticamente cualquier dashboard; un intervalo más grueso cuesta menos almacenamiento y menos rendimiento de escritura.

keepFor es lo que hace posibles los historiales largos. Los registros en bruto desaparecen con dropAfter, pero la copia submuestreada tiene su propia retención: conserva los datos en bruto 30 días y los submuestreados 2 años, y un board podrá seguir mostrando dos años de promedios horarios con una fracción del almacenamiento. Configúralo más largo que dropAfter — la plataforma rechaza lo contrario como una configuración errónea.

paths extiende el submuestreo a valores dentro de columnas JSON. Las columnas numéricas se incluyen automáticamente; los campos JSON hay que nombrarlos explícitamente, ya que una columna JSON no tiene un conjunto fijo de claves. Los campos no declarados siguen funcionando en los dashboards — simplemente se calculan a partir de la tabla en bruto.

Todo lo demás es automático. Cada columna numérica mantiene sus estadísticas (promedio, suma, mínimo, máximo, primer valor, último valor y un recuento de registros), agrupadas por la clave de entidad de la tabla (maintainLatestFlagFor, o el dispositivo que publica). Los dashboards no necesitan configuración alguna ni saber nada de esto: un widget consulta como siempre, y la plataforma decide en cada consulta si la copia preagregada puede responderla — recurriendo de forma transparente a la tabla en bruto cuando no puede, por ejemplo cuando un filtro hace referencia a una columna por la que la copia no agrupa.

Los cambios de esquema reconstruyen la copia. Añadir, eliminar o cambiar el tipo de una columna de una tabla submuestreada — o editar el propio bloque downsample — reconstruye la copia preagregada a partir de la tabla en bruto. Todo lo más antiguo que dropAfter no se puede reconstruir y se pierde. Configura el bloque junto con la tabla siempre que puedas, y trata los cambios de esquema posteriores en tablas de larga vida como una decisión deliberada.

Publicar datos desde el código edge

Usa el SDK de IronFlock para enviar datos desde tu aplicación:

from ironflock import IronFlock flock = IronFlock() await flock.start() await flock.publish_to_table("sensordata", { "timestamp": "2025-01-15T10:30:00Z", "temperature": 23.5, "humidity": 62.1, "device_id": "sensor-001" })

Cada fila necesita un valor para la columna obligatoria tsp: el backend de datos rechaza una fila sin él. La escritura en tabla del SDK falla con un error; una fila que publica un board se descarta y solo deja una entrada en la tabla error-logs de la aplicación. La definición de sensordata de arriba asigna esa columna con path: args[0].timestamp, así que tsp sale del campo timestamp de la fila. Una columna sin path lee el campo de la fila con su mismo nombre (args[0].<id>): sin esa asignación, cada fila necesitaría su propio campo tsp.

Para datos de alta frecuencia, envía muchas filas en un solo mensaje en lugar de una ida y vuelta por fila usando publish_rows_to_table / publishRowsToTable / PublishRowsToTable o append_rows_to_table / appendRowsToTable / AppendRowsToTable — ambos son lo mismo e informan del resultado de la inserción. Cada lote se inserta de forma atómica — todo o nada. Consulta la referencia del SDK para más detalles.

Tablas de transformación

Puedes definir transformaciones SQL que agreguen o procesen automáticamente tus datos en bruto:

data: tables: - tablename: sensordata columns: # ... columnas de datos en bruto ... transforms: - tablename: hourly_averages materialize: true schedule: "0 * * * *" sql: > SELECT time_bucket('1 hour', tsp) AS hour, avg(temperature) AS avg_temp, avg(humidity) AS avg_humidity FROM sensordata GROUP BY hour columns: - id: hour name: Hour dataType: timestamp - id: avg_temp name: Average Temperature dataType: numeric - id: avg_humidity name: Average Humidity dataType: numeric
CampoDescripción
tablenameNombre de la tabla derivada
materializeSi es true, el resultado se almacena y se refresca según la planificación. Si es false, la transformación es una vista, calculada en cada lectura
scheduleExpresión cron para las ejecuciones de la transformación: cinco campos (minuto, hora, día del mes, mes, día de la semana), o seis con un campo inicial de segundos. */5 * * * * se ejecuta cada 5 minutos, */10 * * * * * cada 10 segundos. Cada ejecución refresca un resultado materializado y envía el resultado actual a los boards enlazados a la transformación. El código de la app también puede lanzar una ejecución así bajo demanda, consulta Refrescar bajo demanda
sqlConsulta SQL que calcula la transformación
columnsDefiniciones de columnas para la salida

Las tablas de transformación son accesibles en los paneles y a través del SDK, al igual que las tablas regulares.

Una transformación se lee exactamente como la devuelve su propio SQL: las ventanas de tiempo de los widgets, los filtros de calendario y el modo latest se aplican a las tablas y se ignoran en una transformación. De ahí se derivan tres reglas. Acota el rango temporal dentro de la consulta (WHERE tsp > now() - interval '7 days'), ordena una serie temporal de más nueva a más antigua (ORDER BY <columna de marca temporal> DESC) para que un límite de filas conserve las filas más nuevas, y selecciona todas las columnas que un panel deba graficar o por las que deba filtrar — una transformación no tiene columnas implícitas de marca temporal ni de dispositivo. Una sola lectura devuelve como máximo 3000 filas, así que agrega en la consulta.

Una transformación sirve para lo que una lectura de tabla no puede expresar: un join, un cociente, una agregación sobre las filas actuales de varias tablas. No es la forma de mostrar el estado actual de las entidades ni de ocultar los registros eliminados. Esos son modos de lectura de la propia tabla, el interruptor latest y un filtro sobre una columna deleted (ver más abajo), y funcionan en vivo: un widget enlazado a la tabla sigue cada fila nueva en menos de un segundo. Una transformación llega a un panel solo según su planificación (o cuando el código de la app la refresca tras sus propias escrituras, algo que un guardado desde un panel nunca provoca), así que una vista que elige la fila más reciente de cada entidad o descarta las filas eliminadas muestra el mismo resultado con retraso. Cuando una transformación sí necesita el estado actual de una tabla de entidades, por ejemplo para unirla con otra tabla, selecciónalo en su SQL con DISTINCT ON y aplica allí la comprobación de deleted, en el orden que se muestra en Eliminación lógica de registros.

Incluir una transformación con la app no es la única forma de obtener una: un miembro del proyecto con el privilegio de Acceso a datos puede guardar el mismo tipo de transformación desde la vista de datos del proyecto, sin ninguna app, y el asistente de IA también puede hacerlo. Consulta Transformaciones personalizadas.

Cuándo se refresca una transformación materializada

Una ejecución programada refresca una transformación materializada solo cuando se ha escrito en una tabla que lee desde su último refresco, y en cualquier caso al menos cada 10 minutos. Una ejecución sin nada nuevo que leer deja el resultado almacenado tal como está: una transformación programada cada minuto sobre una tabla que recibe una fila por hora se refresca después de esa fila y, el resto del tiempo, cada 10 minutos.

Una transformación materializada se refresca en cada ejecución cuando su resultado puede cambiar sin que haya una escritura:

  • su SQL usa la hora actual o valores aleatorios, como now(), CURRENT_DATE o random();
  • llama a una función que puede devolver un resultado distinto para la misma entrada: una función volátil, o una función estable que no viene integrada en PostgreSQL;
  • lee algo distinto de las tablas de la app y las transformaciones materializadas, por ejemplo una transformación no materializada, una copia submuestreada o una de las tablas propias de la plataforma.

Cuando muchas transformaciones vencen en el mismo momento, la plataforma refresca unas pocas a la vez y las demás esperan su turno, así que un refresco puede terminar más tarde de lo programado. Una ejecución que vence mientras el refresco anterior de la misma transformación sigue en curso o en espera se omite.

Refrescar bajo demanda

El propio código de la app puede lanzar la ejecución de una transformación sin esperar a su planificación: refresh_transform / refreshTransform / RefreshTransform del SDK refresca el resultado materializado (una vista simple solo se lee) y envía el resultado actual a los boards enlazados a la transformación, de modo que un board muestra de inmediato un lote que la app acaba de escribir. Se aplican las mismas reglas que a una ejecución programada: el refresco se omite — y se informa como omitido — cuando no se ha escrito en ninguna tabla que lee la transformación desde el último refresco, una llamada que llega mientras un refresco de la misma transformación está en curso espera al que está en cola detrás de él, y por transformación se inicia como máximo un refresco por segundo. Las escrituras en tablas del SDK están confirmadas cuando retornan, así que un refresco que sigue a una escritura nunca la pasa por alto. Solo los propios contenedores de la app pueden refrescar sus transformaciones; un board recibe las filas, y una app que consume los datos de otra app lee sus transformaciones pero no puede refrescarlas. Las transformaciones guardadas desde la vista de datos del proyecto no pertenecen a ninguna app y se ejecutan solo según su planificación. Consulta refreshTransform / refresh_transform / RefreshTransform.

Seguimiento del último estado de una entidad

Para tablas que representan el estado actual de entidades del mundo real — máquinas, activos, órdenes de producción — IronFlock soporta un patrón llamado seguimiento del último estado.

En lugar de sobrescribir una fila cuando algo cambia, siempre agregas una nueva fila. Tú declaras qué columnas identifican una entidad única, e IronFlock deriva la fila más reciente de cada entidad cada vez que se lee la tabla. Esto te da un historial completo de cada cambio y al mismo tiempo facilita consultar solo el estado actual.

Habilítalo en una tabla con maintainLatestFlagFor:

- tablename: machineform maintainLatestFlagFor: ['machinename'] columns: - id: tsp dataType: timestamp - id: machinename dataType: string - id: machinetype dataType: string - id: active dataType: boolean - id: description dataType: string

maintainLatestFlagFor recibe una lista de columnas que juntas identifican una entidad única. No se escribe nada en la fila misma: IronFlock indexa la tabla por esa clave de entidad más la marca temporal, y elige la fila más reciente de cada entidad en el momento de la consulta. Por eso, una fila que llega tarde o fuera de orden nunca puede dejar tras de sí una marca obsoleta.

Una tabla de entidades contiene una fila por entidad y marca temporal. Una fila que repite tanto la clave de entidad como el tsp de una fila almacenada se rechaza, y también un lote en el que dos filas lo hacen: la escritura del SDK falla con URI_ENTITY_KEY_CONFLICT y la tabla error-logs de la app registra el rechazo. Da a cada versión de una entidad su propio tsp. Una fila cuya columna de clave de entidad está vacía (NULL) no pertenece a ninguna entidad: nunca se rechaza como repetición, y las lecturas de último estado la omiten.

Actualizar una entidad con una fila parcial

Una fila agregada a una tabla de entidades es una nueva versión de esa entidad — y no tiene por qué estar completa. Las columnas que la fila no aporta se heredan de la fila más reciente anterior de la entidad, así que actualizar un solo campo significa publicar únicamente la clave de entidad, una marca temporal y ese campo:

La columna en la nueva filaLa versión almacenada contiene
se proporciona (0, false y "" cuentan como proporcionados)el valor proporcionado
es explícitamente nullNULL — la columna se borra
está ausenteel valor de la fila más reciente anterior

Para vaciar una columna, envíala como null (None en Python, nil en Go, null en C#). Si la omites, se conserva el valor anterior. Ten cuidado con el código que omite un campo sin querer: una propiedad de JavaScript con valor undefined, por ejemplo, desaparece del payload. La referencia del SDK enumera estos casos por lenguaje.

Merece la pena conocer dos detalles:

  • Una fila que aporta todas las columnas se salta por completo la consulta de la fila anterior, así que las filas completas siguen siendo exactamente igual de baratas que siempre — sigue enviando filas completas en las rutas de alta frecuencia.
  • La herencia respeta el tiempo: una fila que llega con una marca temporal más antigua (una carga retroactiva) hereda solo de filas con tsp igual o anterior al suyo, nunca de filas más recientes.

Las tablas sin maintainLatestFlagFor conservan la semántica de inserción simple: una columna que la fila no aporta se almacena como NULL.

Para consultar solo los estados actuales de las máquinas:

SELECT DISTINCT ON (machinename) * FROM machineform ORDER BY machinename, tsp DESC

Para ver el historial completo de una máquina específica:

SELECT * FROM machineform WHERE machinename = 'Assembly-Line-01' ORDER BY tsp

Rara vez escribirás esa consulta a mano, y no deberías guardarla como transformación. Los widgets de un panel que se conectan a esta tabla tienen un interruptor latest en sus ajustes de filtro, de modo que los usuarios siempre ven los valores actuales sin trabajo adicional. El interruptor funciona en vivo: el widget recibe cada fila nueva de la tabla a medida que llega y sustituye con ella la fila anterior de la entidad, así que un cambio se ve menos de un segundo después de escribirse, mientras la tabla conserva todas las versiones. Nada se recalcula según una planificación, que es todo lo que añadiría una transformación. Desde el SDK, solicita el mismo modo añadiendo {"latest": true} a filterAnd — consulta getHistory.

Migración desde latest_flag: las versiones anteriores de IronFlock almacenaban una columna booleana física llamada latest_flag. Esa columna ya no existe — el estado actual se deriva en SQL, lo que lo mantiene correcto cuando las filas llegan fuera de orden. Los paneles y las llamadas del SDK existentes que filtran por latest_flag = true siguen funcionando: IronFlock los reconoce y aplica el modo de último estado. El código nuevo debería usar el interruptor latest o la entrada de filtro {"latest": true}.

Cambiar la clave de entidad

Una vez publicada una versión de la app, la clave de entidad de cada una de sus tablas queda fija. Actualizar estructura de datos en el panel lateral del IDE en la nube y la compilación de un nuevo release rechazan un data-template.yml que cambie la clave de entidad de una tabla que ya tiene el release más reciente de la app:

  • añadir una columna a maintainLatestFlagFor, quitar una, reemplazar una o cambiar su orden;
  • añadir maintainLatestFlagFor a una tabla que no lo tenía, o quitarlo.

Un cambio así alteraría sin aviso lo que devuelve la tabla en cada proyecto que ha instalado la app. Una columna nueva en la clave está vacía en todas las filas existentes, y las lecturas de último estado omiten las filas con una columna de clave vacía, así que todas las entidades existentes desaparecerían. Una columna eliminada de la clave puede fusionar entidades cuyas filas comparten una marca temporal, mientras que la tabla solo puede contener una fila por entidad y marca temporal.

Para usar otra clave de entidad, crea una tabla nueva con la nueva clave y traslada a ella los datos, por ejemplo desde el código de tu app. Trasladar los datos le corresponde a la app. Una tabla que todavía no está en ningún release puede seguir cambiando su clave de entidad mientras desarrollas. Una versión de la app publicada antes de que existiera esta regla todavía puede cambiar una clave de entidad: un proyecto que se actualiza a ella rechaza la actualización de la estructura de datos y conserva la anterior.

Filas que repiten una entidad y una marca temporal

Las tablas escritas antes de que IronFlock impusiera una fila por entidad y marca temporal todavía pueden contener repeticiones, y también una tabla de desarrollo cuya clave de entidad cambiaste. Cuando el servicio de datos prepara una tabla así, al arrancar o después de una actualización de la estructura de datos, traslada todas las filas de cada grupo repetido a una tabla llamada <table>__entitykey_dupes en el mismo backend de datos y devuelve a la tabla una fila de cada grupo. A partir de entonces, la tabla rechaza las repeticiones. Una entrada en la tabla error-logs de la app indica cuántas filas se trasladaron.

La nueva tabla conserva cada fila trasladada tal como estaba, más dos columnas: quarantined_at, el momento del traslado, y restored, que marca la fila que se devolvió. Qué fila se devuelve es arbitrario, como ya lo era para las lecturas de último estado. Consúltala en la consola de consultas de la vista de datos del proyecto como databackend_<key>.<table>__entitykey_dupes. Si la tabla original es privada, la nueva tabla también lo es. Si las filas no se pueden trasladar, la entrada de error-logs indica por qué, y el servicio de datos lo vuelve a intentar en su siguiente arranque.

Eliminación lógica de registros

El modelo de solo inserción de IronFlock significa que los registros nunca se eliminan físicamente. En su lugar, usa una columna booleana deleted para marcar un registro como eliminado. Esto preserva la pista de auditoría completa mientras oculta los registros eliminados de los dashboards.

Agrega una columna deleted a cualquier tabla de entidades:

- id: deleted name: Deleted dataType: boolean

Cuando un usuario elimina un registro (por ejemplo, a través de un formulario en el panel), tu aplicación publica una nueva fila para esa entidad con deleted: true. Combinado con maintainLatestFlagFor, esta nueva fila se convierte en el último estado. Las filas parciales posteriores heredan el marcador deleted como cualquier otra columna, así que una actualización que no menciona deleted ni resucita la entidad ni la oculta.

Para consultar solo los registros actuales activos (no eliminados):

SELECT * FROM ( SELECT DISTINCT ON (machinename) * FROM machineform ORDER BY machinename, tsp DESC ) latest WHERE deleted IS NULL OR deleted = false

La comprobación de deleted se ejecuta después de haber elegido la fila más reciente de cada máquina. Ese orden importa: filtrar primero las filas eliminadas haría que la fila anterior, no eliminada, reapareciera como el estado actual.

Los widgets del panel y el SDK aplican el mismo orden automáticamente — combina el interruptor latest (o {"latest": true}) con un filtro sobre deleted y obtendrás exactamente este comportamiento. Los registros eliminados desaparecen del dashboard inmediatamente después de enviar el formulario, pero permanecen en la base de datos para fines de historial y auditoría.

En el panel, un formulario de eliminación elimina un registro: un formulario cuyo botón de envío dice Eliminar y cuya casilla oculta escribe true en la columna deleted, junto a la clave del registro (consulta Eliminar datos). Los widgets que listan los registros filtran la propia tabla. No hace falta ninguna vista ni transformación para limpiar la lista, y una solo mostraría una eliminación en su siguiente ejecución programada.

Compartir datos con otras apps

Tu data backend es privado para tu app: ninguna otra app instalada en el proyecto puede ver tus tablas. Dos claves opcionales en data-template.yml cambian eso.

Para leer los datos de otra app, enumera las apps de las que quieres leer en una sección consumes: de nivel superior — junto a data:, no dentro de ella:

consumes: - app: machine-monitor reason: "Calcula el OEE a partir de los flujos de estado de máquina y contadores del monitor" data: tables: - tablename: oee_results columns: # ... las tablas propias de tu app, como siempre

app es el nombre técnico de la app proveedora, o "*" (las comillas son obligatorias) para todas las apps del proyecto. reason se muestra al usuario en el diálogo de consentimiento — la declaración por sí sola no concede nada hasta que él la aprueba.

Para reservarte tablas concretas, márcalas con private: true. Todo lo que definas es compartible por defecto; una tabla o transformación privada nunca aparece en el catálogo que ven las demás apps.

data: tables: - tablename: measurements # compartida (por defecto) columns: [ ... ] - tablename: calibration_state # interna — nunca visible para otras apps private: true columns: [ ... ]

El acceso es de solo lectura, lo concede el usuario por proyecto y es revocable en cualquier momento. Consulta Consumir datos de otras apps para el modelo completo y las llamadas del SDK que leen el historial y los flujos en vivo de una app proveedora.

Acceso privilegiado

Los contenedores de una app se ejecutan aislados del dispositivo, con los permisos predeterminados de Docker. Algunas apps necesitan más: un puerto serie o un adaptador USB, GPIO, una interfaz CAN o Bluetooth, la red del host. Eso es el acceso privilegiado. Una app con acceso privilegiado puede controlar todo el dispositivo, incluidas otras apps y sus datos, así que tu app tiene que solicitarlo y el usuario decide si lo obtiene.

Para solicitarlo, añade una sección privileged: de nivel superior con un reason — junto a data:, no dentro de ella:

privileged: reason: "Lee el PLC por el puerto serie /dev/ttyUSB0" data: tables: # ... las tablas propias de tu app, como siempre

reason es obligatorio. Se muestra al usuario en el diálogo de consentimiento, así que escríbelo para una persona que decide si confía en tu app.

Una app sin tablas escribe data: {} junto a privileged: un data-template.yml sin la clave data: no se puede publicar.

Lo que el usuario concede depende de cómo está construida la app:

  • Una app de una sola imagen (solo un Dockerfile) se ejecuta en modo privilegiado cuando el usuario lo concede: con todas las capacidades de Linux, el /dev del dispositivo y el D-Bus del host. Sin la declaración se ejecuta sin los dispositivos del host, sin capacidades adicionales y sin el D-Bus del host; la versión se publica igualmente, y su log de compilación lo advierte.
  • Una app de Docker Compose recibe exactamente los ajustes que pide su docker-compose.yml, y el diálogo de consentimiento los enumera. Si el archivo compose usa alguno de los ajustes de abajo, la app tiene que declarar privileged; si no, la publicación de la versión falla con un error que nombra el servicio y el ajuste. Declarar privileged cuando el archivo compose no usa ninguno de ellos también falla.

Estos ajustes de compose cuentan como privilegiados:

AjustePrivilegiado cuando
privilegedcualquier valor excepto false
cap_add, devices, device_cgroup_rulestiene alguna entrada
security_opttiene una entrada distinta de no-new-privileges
network_mode, pid, ipc, uts, userns_mode, cgroupvale host o container:…
cgroup_parenttiene un valor
volumes de un serviciomonta una ruta del host (/…, ~/…, C:\…), una ruta fuera de la carpeta de la app (../…) o una tubería con nombre. /etc/localtime y /etc/timezone de solo lectura están permitidos.
volumes_fromnombra container:…
volumes de nivel superiorun volumen tiene driver_opts, external o un name fijo
networks de nivel superioruna red define un driver distinto de bridge (como macvlan, ipvlan o host) o driver_opts, es external o tiene un name fijo
secrets, configs de nivel superioruna entrada lee un file fuera de la carpeta de la app

Los volúmenes con nombre, las redes con el driver predeterminado bridge, los bind mounts dentro de la carpeta de la app (./config:/config), los puertos publicados y las reservas de GPU (gpus, deploy.resources.reservations.devices) no son privilegiados.

Un marcador ${VAR} en uno de estos ajustes está permitido y cuenta como privilegiado, así que también necesita la declaración. Así un parámetro de la aplicación puede dejar que los usuarios elijan el puerto serie:

services: plc: build: . devices: - "${SERIAL_PORT}:/dev/ttyS0"

Un archivo compose que usa include, o extends con un file, no se puede publicar, con o sin la declaración: una versión solo lleva el docker-compose.yml. Integra los demás archivos en él.

No solicites más de lo que la app necesita. Si necesita un puerto serie, escribe un archivo compose con un único servicio y devices: [/dev/ttyUSB0] en lugar de una sola imagen o privileged: true. El usuario ve exactamente lo que recibe la app, y la app no puede hacer más que eso.

Consentimiento y revocación

  • Al instalar, el usuario ve tu reason y, en una app de compose, la lista de ajustes, y activa o desactiva el acceso privilegiado. Rechazarlo nunca bloquea la instalación.
  • En una actualización, si la nueva versión solicita acceso privilegiado y el proyecto no lo ha concedido, el diálogo de actualización pregunta. Aunque se rechace, la app se actualiza; la nueva versión se ejecuta entonces sin acceso privilegiado.
  • Después, el acceso privilegiado es un interruptor en la configuración de apps del proyecto, donde los usuarios pueden revocarlo o concederlo en cualquier momento. Los dispositivos en marcha reinician la app con el nuevo ajuste.

Una ejecución de desarrollo desde el IDE en la nube sigue la declaración y no tiene interruptor: la compilación de desarrollo se ejecuta en modo privilegiado cuando .ironflock/data-template.yml declara privileged, y sin acceso privilegiado cuando no lo declara. Si el archivo compose usa ajustes privilegiados sin la declaración, la compilación de desarrollo falla con el mismo error que una publicación.

Sin el permiso

La app arranca igualmente. Una app de una sola imagen se ejecuta con los valores predeterminados de Docker: sin /dev, sin capacidades adicionales, sin el D-Bus del host. En una app de compose, el agente del dispositivo elimina los ajustes privilegiados del archivo compose antes de arrancar la app, y escribe en el log de la app qué ajustes eliminó de qué servicio. Asegúrate de que tu código informe de lo que no puede alcanzar, como un puerto serie que no puede abrir, en lugar de fallar.

Versiones anteriores

Las versiones publicadas antes de que las apps tuvieran que declarar el acceso privilegiado cuentan como si lo solicitaran, y las instalaciones existentes lo conservan, así que esas apps funcionan como antes. Los usuarios pueden revocarlo en la configuración de apps del proyecto, como en cualquier otra app. A partir de tu próxima versión, declara privileged si la app lo necesita.

Last updated on