Communitygithub.com

Adrian7373/pipe-de-video-semantico

Utilizado para alojar, implementar u operar una aplicación en la Plataforma Prisma: proyectos, ramas, entornos de vista previa, servicios y sus versiones, bases de datos Prisma Postgres, buckets de almacenamiento de objetos, variables de entorno, dominios personalizados, registros o la integración con GitHub. Se activa con 'Plataforma Prisma', 'Prisma Compute', 'Prisma Postgres', 'Prisma Storage', 'entorno de vista previa', `prisma deploy`, `prisma dev`, `prisma auth`, `prisma project`, `prisma branch`, `prisma service`, `prisma postgres`, `prisma bucket`, `prisma git`, `prisma.config.ts`, promocionar, revertir.

¿Qué es pipe-de-video-semantico?

Esta habilidad proporciona un conocimiento autorizado y actualizado sobre la Plataforma Prisma, incluyendo Prisma Compute (alojamiento), Prisma Postgres (bases de datos gestionadas) y Prisma Storage (almacenamiento de objetos compatible con S3). Está diseñada para ayudar a desarrolladores e ingenieros de IA a comprender los conceptos centrales, la jerarquía de recursos y los flujos de trabajo de la plataforma, como la gestión de proyectos, ramas, servicios, versiones y entornos de vista previa. La habilidad enfatiza que su contenido, incluido en el paquete `prisma` instalado, es la fuente de verdad sobre cualquier conocimiento desactualizado sobre el alojamiento de Prisma. Cubre modelos de recursos, métodos de implementación (CLI e integración con GitHub), enrutamiento de variables de entorno, comportamiento de servicios inactivos, y configuración de bases de datos y buckets. Es compatible con agentes de IA como Claude Code, Cursor y Codex a través del mecanismo de sincronización de habilidades de Prisma.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Adrian7373/semantic-video-pipeline/tree/HEAD/packages/database/.agents/skills/prisma-platform-core-concepts

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Conceptos clave de la Plataforma Prisma

Infraestructura aislada para cada rama.

La Plataforma Prisma avanza rápido, y es muy probable que tus datos de entrenamiento sobre ella estén desactualizados. Esta habilidad se incluye dentro del paquete prisma instalado, por lo que describe la versión exacta que tiene este proyecto: trátala como la fuente de verdad sobre cualquier cosa que recuerdes sobre el alojamiento de Prisma. Si metadata.library_version en el frontmatter de este archivo no coincide con el paquete prisma instalado en el proyecto, ejecuta prisma skills sync y vuelve a leerlo. La documentación completa de todo lo que aquí se menciona está en prisma.io/docs; consúltala cuando un concepto necesite más profundidad de la que este archivo contiene.

Este archivo comparte las estructuras, jerarquías, relaciones y flujos de trabajo de la plataforma. No es una referencia de la CLI: los comandos aparecen solo cuando un flujo de trabajo los necesita. Para conocer la superficie de un comando, ejecuta prisma --help, o prisma <grupo> --help para cualquier grupo mencionado a continuación; la mayoría de los comandos aceptan --json para salida legible por máquina. El contrato de datos, las migraciones y las consultas pertenecen a la habilidad prisma-orm-core-concepts; la declaración de servicios y módulos en código pertenece a prisma-composer-core-concepts.

La pila

Una única CLI, prisma, actúa como interfaz para un conjunto de productos diseñados para usarse juntos:

ProductoQué esConceptos viven en
Prisma ORM (Prisma 8)Contrato de datos, consultas tipadas, migracionesprisma-orm-core-concepts
Prisma ComposerLa declaración de la aplicación: servicios, bases de datos, buckets, cableadoprisma-composer-core-concepts
Prisma ComputeAlojamiento: ejecuta tus servicios junto a tus datosesta habilidad
Prisma PostgresPostgreSQL gestionadoesta habilidad
Prisma StorageAlmacenamiento de objetos compatible con S3esta habilidad

Cada aplicación implementada es una aplicación Composer. Tu código de servidor más una declaración (module.ts) que nombra sus servicios, bases de datos y buckets. La declaración es la fuente de verdad: implementar converge la plataforma hacia ella, volver a implementar aplica solo la diferencia, y eliminar un recurso del módulo lo elimina de la plataforma en la próxima implementación. No hay un paso de aprovisionamiento separado ni cadenas de conexión que configurar manualmente; Composer las inyecta.

Configuración del proyecto

La CLI lleva todos los comandos mencionados aquí, pero el código de una aplicación necesita sus dependencias instaladas. Comienza desde:

npm install prisma @prisma/composer @prisma/composer-prisma-cloud

@prisma/composer es lo que importa la declaración del módulo; @prisma/composer-prisma-cloud es el destino de Prisma Cloud e incluye @prisma/orm-postgres. Las habilidades hermanas viajan dentro de estos paquetes (prisma-composer-core-concepts en @prisma/composer, prisma-orm-core-concepts en @prisma/orm-postgres), por lo que aparecen después de esta instalación más prisma skills sync, no antes.

Un archivo de configuración, prisma.config.ts, configura la CLI y todos los productos que ejecuta. Cada clave de nivel superior es una sección propiedad de un producto, y esta CLI reconoce exactamente tres: orm, composer y skills. La forma compuesta:

import { definePrismaConfig } from "prisma/config";
import { defineConfig as composer } from "@prisma/composer/config";
import { nodeBuild } from "@prisma/composer/node/control";
import {
  prismaCloud,
  prismaState,
} from "@prisma/composer-prisma-cloud/control";
import { defineConfig as orm } from "@prisma/orm-postgres/config";

export default definePrismaConfig({
  composer: composer({
    extensions: [prismaCloud(), nodeBuild()],
    state: prismaState(),
  }),
  orm: orm({ contract: "./src/prisma/contract.prisma" }),
  skills: { agents: ["claude"] },
});

dev y deploy leen la sección composer y nada más; lo que va en ella pertenece a prisma-composer-core-concepts. Un prisma-composer.config.ts separado ya no se lee, y la configuración antigua se rechaza, nunca se ignora silenciosamente: CONFIG.SECTION_MISSING cuando ningún prisma.config.ts cargado declara una sección composer, CONFIG.FIELD_RETIRED cuando la sección aún tiene configPath, y CONFIG.FILE_RETIRED cuando un prisma-composer.config.* se encuentra junto al prisma.config.ts declarante. Los tres llegan bajo el CLI.CONFIG_SECTION_INVALID de la CLI. Para CONFIG.SECTION_MISSING, escribe la sección. Para los otros dos, mueve las extensions y el state del archivo antiguo a la sección, luego elimina el campo configPath o el antiguo archivo.

El modelo de recursos

  1. Espacio de trabajo: el límite de la cuenta. Los miembros, la facturación y los proyectos viven aquí; el grupo auth gestiona en cuál actúas.
  2. Proyecto: un producto o base de código. Su región se elige en la creación y es inmutable después; todos los recursos del proyecto la heredan.
  3. Rama: el límite de aislamiento, nombrada según una rama de git. Una rama es un entorno: posee sus propios servicios, sus propias bases de datos, sus propios buckets y sus propias anulaciones de variables de entorno.
  4. Dentro de una rama: servicios (aplicaciones HTTP, implementadas como versiones), bases de datos y buckets.

La primera rama de un proyecto es la rama de producción. Cada rama posterior es una rama de vista previa. La producción y las vistas previas difieren exactamente en dos aspectos: qué clase de variable de entorno resuelven (ver más abajo) y el ciclo de vida (las vistas previas pueden ser reclamadas y eliminadas; la producción no).

Una invocación de la CLI resuelve su proyecto a partir de un enlace de directorio, creado cuando un proyecto se crea o se vincula al directorio y se almacena en el archivo ignorado por git .prisma/local.json. Los comandos de recursos toman banderas para apuntar explícitamente a otro proyecto o rama.

Las ramas son entornos de vista previa

No hay un objeto separado de "entorno de vista previa" para crear o configurar. La rama es el entorno, y las ramas surgen al implementar en ellas:

  1. Empuja una rama de git (con la integración de GitHub conectada y el flujo de trabajo de implementación en el repositorio): el flujo de trabajo construye e implementa, y la plataforma crea el entorno de la rama sobre la marcha.
  2. Implementa un stage desde la CLI: prisma deploy module.ts --stage pr-42 crea una rama llamada pr-42 e implementa el grafo de aplicación idéntico en ella. Un nombre de stage debe ser un nombre de referencia de git válido; un nombre inválido es un error grave.

Una rama de vista previa que necesita una base de datos obtiene una nueva y vacía, cableada como DATABASE_URL con ámbito de rama. El trabajo de vista previa nunca puede tocar los datos de producción a menos que apuntes explícitamente a ellos. El esquema proviene de tus migraciones confirmadas; los datos no se transfieren desde producción.

Reglas del ciclo de vida de la vista previa:

  1. Eliminar la rama de git ascendente destruye todo el entorno: servicios, versiones y bases de datos, incluidos sus datos.
  2. Una rama de vista previa inactiva y no fijada puede ser reclamada automáticamente. Fijar una vista previa la exime de la reclamación por inactividad, pero no de la eliminación cuando su rama de git se elimine.
  3. La rama de producción nunca se reclama ni se elimina de esta manera.

Dos formas de implementar

GitHub (recomendado). Dos piezas, ambas requeridas: la Aplicación de GitHub de Prisma conectada al repositorio y un flujo de trabajo de Acciones de GitHub en el repositorio que ejecuta prisma/cloud-deploy-action. La plataforma no construye al empujar. El flujo de trabajo construye en las Acciones del propio repositorio e implementa con una credencial de corta duración intercambiada desde el token OIDC de la ejecución; la conexión es lo que autoriza ese intercambio, y también elimina la vista previa cuando se elimina su rama de git. Importar el repositorio en la Consola abre una solicitud de extracción de configuración que añade el flujo de trabajo. prisma git connect solo crea la conexión, por lo que un repositorio conectado desde la CLI añade el flujo de trabajo por sí mismo. El mínimo .github/workflows/prisma-deploy.yml:

name: prisma-deploy
on:
  push:
permissions:
  contents: read
  id-token: write
jobs:
  deploy:
    if: github.ref_type == 'branch'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - uses: oven-sh/setup-bun@v2
      - uses: prisma/cloud-deploy-action@v1
        with:
          build-command: npm run build

A partir de entonces, cada empuje de una rama que contenga el archivo de flujo de trabajo lo ejecuta; GitHub lee los flujos de trabajo del commit empujado, por lo que una rama creada antes de que se añadiera el archivo no implementa nada hasta que contenga el archivo. Un empuje a la rama por defecto implementa producción; un empuje a cualquier otra rama crea o actualiza el entorno de vista previa de esa rama, por lo que las vistas previas vienen gratis con cada rama. Abrir una solicitud de extracción no implementa nada por sí mismo; las vistas previas siguen los empujes de rama. Un repositorio conectado sin el flujo de trabajo obtiene contabilidad de ramas y eliminación de vistas previas desde la plataforma, y ninguna construcción.

CLI. prisma deploy module.ts implementa producción directamente; añade --stage <nombre> para una vista previa. Autentícate una vez con prisma auth login (interactivo), o establece PRISMA_SERVICE_TOKEN (más PRISMA_WORKSPACE_ID cuando el token pueda ver más de un espacio de trabajo) para CI y otras ejecuciones sin cabeza. La primera implementación crea el proyecto, nombrado según tu módulo; el nombre debe ser único en el espacio de trabajo, y --name implementa bajo uno diferente.

Ambos caminos convergen la misma declaración, por lo que son mutuamente idempotentes: un repositorio puede estar conectado a GitHub y aún así ser implementado desde la CLI.

Servicios y versiones

Un servicio es una aplicación HTTP dentro de una rama, accesible en una URL estable. Cada implementación de un servicio crea una nueva versión inmutable; exactamente una versión está activa detrás de la URL estable a la vez. Las versiones pueden ser inspeccionadas, iniciadas, detenidas y eliminadas individualmente, y los registros de una versión pueden ser leídos o seguidos; el grupo service cubre todo eso.

Dos movimientos entre versiones son importantes:

  1. Promocionar lleva una versión a producción reconstruyéndola con variables de entorno de clase de producción. Una versión construida en una rama de vista previa nunca lleva la configuración de vista previa a producción.
  2. Revertir apunta la producción de vuelta a una versión anterior. Un destino detenido se inicia y se verifica su estado antes de que el tráfico cambie, por lo que la reversión no tiene tiempo de inactividad.

Dominios personalizados se adjuntan solo a la rama de producción de un servicio. El flujo de trabajo: añade el dominio, crea el registro CNAME que la plataforma informa, y espera la verificación de DNS y el aprovisionamiento del certificado; una verificación que falló por falta de DNS se reintenta después de que exista el registro.

El tiempo de ejecución de Compute

Los servicios se ejecutan en Bun, junto a su base de datos Prisma Postgres. No hay imagen de contenedor que crear ni emulador de plataforma que instalar localmente.

El tiempo de ejecución no tiene un Temporal global (el Node 24 estándar tampoco tiene uno). El código que lee una columna DateTime del ORM se compila e implementa, luego lanza una excepción en la primera lectura. O añade la dependencia temporal-polyfill y import 'temporal-polyfill/full/global' en la entrada del servicio, o usa los tipos de columna *String como TimestamptzString.

Un servicio inactivo duerme: la plataforma captura su memoria después de un breve período de inactividad y lo reanuda desde la captura en la siguiente solicitud. El manejo de solicitudes no se ve afectado, pero el trabajo en segundo plano fuera del ciclo de vida de la solicitud (setTimeout, setInterval, promesas flotantes) puede interrumpirse a mitad de vuelo. El paquete @prisma/compute proporciona las dos primitivas de mantener activo:

  1. waitUntil(promise, { signal }) mantiene la instancia activa hasta que la promesa se resuelva.
  2. using guard = new KeepAwakeGuard({ signal }) mantiene la instancia activa durante un ámbito; llama a .release() en un bloque finally donde using no esté disponible.

Pasa AbortSignal.timeout(ms) como un límite de costo: la señal libera el guardia, no cancela tu trabajo. No construyas programadores en setInterval dentro de un servicio; dormir los hace silenciosamente poco fiables.

Prisma Postgres

Para tu aplicación, una base de datos Prisma Postgres es una base de datos PostgreSQL normal detrás de una cadena de conexión: cualquier cliente funciona, incluyendo Prisma ORM, psql, Kysely y Drizzle. Además de PostgreSQL simple, cada base de datos tiene agrupación de conexiones incorporada (no es necesario ejecutar PgBouncer), almacenamiento en caché de consultas opcional y copias de seguridad automatizadas.

Las bases de datos generalmente provienen de implementar un módulo que declara una. También pueden crearse directamente, en cuyo caso la URL de conexión se imprime exactamente una vez. Se pueden crear y rotar cadenas de conexión adicionales por base de datos; cada secreto se muestra exactamente una vez en la creación, y ninguna lectura posterior lo revela. Las copias de seguridad son automatizadas, listables y restaurables, y las métricas de uso por base de datos son consultables; el grupo postgres cubre todo eso.

Almacenamiento de objetos

Los buckets son almacenes de objetos compatibles con S3 que viven dentro del proyecto, opcionalmente asociados con una rama (la rama por defecto del proyecto cuando se omite). Un bucket no puede ser renombrado.

Las claves de acceso son credenciales con ámbito de bucket con un rol de read o read_write. Crear una imprime el id de la clave de acceso, el secreto, el endpoint y el nombre del bucket del proveedor exactamente una vez; un secreto perdido se revoca y se vuelve a crear, nunca se recupera. El grupo bucket gestiona tanto los buckets como sus claves.

En Compute, el cliente S3 incorporado de Bun recoge S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID y S3_SECRET_ACCESS_KEY del entorno, por lo que un bucket declarado en el módulo no necesita configuración de cliente. Localmente, un bucket declarado por Composer obtiene un sustituto local con la misma superficie S3; el código escrito para él se ejecuta sin cambios en la plataforma.

Variables de entorno

La configuración tiene dos ejes independientes:

EjeValoresSignificado
Claseproduction, previewQué ramas lo resuelven: los valores de clase de producción alcanzan la rama de producción, los valores de clase de vista previa alcanzan cada vista previa
Ámbitoplantilla de proyecto, anulación de ramaUna plantilla se aplica a todas las ramas de su clase; una anulación fija un valor a una rama de vista previa nombrada

Reglas que afectan:

  1. Las anulaciones de rama existen solo para la clase de vista previa. La configuración de producción es siempre la plantilla del proyecto; no hay forma de dar a una implementación de producción un valor especial.
  2. Los valores son de solo escritura. Listar muestra nombres y ámbitos, nunca valores, y ninguna API los devuelve. Para cambiar un valor, lo reemplazas.

...

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Skills relacionados