PREMIEREMENT: Utilisez le skill parent neon pour une vue d'ensemble de Neon, la prise en main, les bonnes pratiques de développement, etc.

Si le skill neon n'est pas installé, récupérez-le depuis https://neon.com/docs/ai/skills/neon/SKILL.md ou installez-le avec :

npx skills add neondatabase/agent-skills --skill neon

Neon Functions

Ceci est une fonctionnalité en bêta publique, actuellement disponible dans les régions us-east-2 et eu-central-1.

Les Neon Functions sont des gestionnaires HTTP Node.js longue durée déployés sur une branche Neon. Chaque fonction reçoit une URL HTTPS publique, s'exécute dans la même région que votre base de données et — si la branche dispose de Postgres — reçoit automatiquement la variable DATABASE_URL. Vous les déployez et gérez via le même CLI Neon, neon.ts et API que vous utilisez déjà.

Utilisez ce skill pour aider l'utilisateur à définir, exécuter localement, déployer et gérer des fonctions à côté de leur base de données. Livrez une fonction déployée avec son URL d'invocation, une boucle locale fonctionnelle neon dev, ou une réponse précise issue de la documentation officielle de Neon.

Quand Utiliser

Utilisez Neon Functions lorsque le workload est un gestionnaire requête/réponse qui bénéficie de rester actif et proche des données :

Flux requête/réponse longs qui dépassent les limites des fonctions lambda. Les agents qui effectuent plusieurs appels LLM et invocations d'outils par requête, ou la génération d'images/vidéos, dépassent régulièrement les limites d'exécution de ~10-60 secondes et les fenêtres de streaming courtes des fonctions serverless traditionnelles. Les Neon Functions sont longue durée : le gestionnaire doit seulement commencer à répondre sous 15 minutes, et un flux ouvert reste actif tant que des octets continuent de circuler. Cela offre suffisamment de marge pour les workloads d'agents réels.
Streaming avec état sans ajouter Redis. Comme une fonction reste active pendant toute une requête, elle peut héberger un point de terminaison SSE ou un serveur WebSocket et maintenir la connexion ouverte dans le processus — pas besoin de magasin d'état externe (Redis, etc.) pour garder un flux cohérent. L'état au niveau du module (un pool pg, un compteur en mémoire) persiste entre les requêtes sur le même isolate.
Calcul devant être proche de Postgres. La fonction s'exécute dans la même région que la base de données de la branche, donc il n'y a pas d'aller-retour entre régions pour chaque requête. DATABASE_URL est injectée automatiquement.
Un backend qui se branche avec vos données. Chaque branche exécute sa propre version de la fonction à sa propre URL, avec sa propre base de données isolée (et son stockage, et sa passerelle). Les déploiements de prévisualisation, CI et environnements de développement obtiennent chacun un backend autonome — déployer sur une branche enfant n'affecte jamais la branche parent.
Webhooks, bots et travail post-réponse. Les gestionnaires de webhook qui se répartissent en plusieurs écritures DB, les bots Discord/WebSocket, et les suivis "fire-and-forget" via waitUntil (analytiques, journaux d'audit) sont tous adaptés.
Travail HTTP récurrent. Un Déclencheur de Fonction envoie une requête POST à la fonction selon un cron (type: "schedule"). Même gestionnaire fetch, même limite de 15 minutes pour le premier octet. Voir Déclencheurs de Fonction.

Si le workload est un site statique pur, ou quelque chose qui doit s'exécuter en dehors des régions supportées (us-east-2, eu-central-1) aujourd'hui, ce n'est pas encore l'outil adapté (voir Limites de Temporisation et d'Exécution et Disponibilité).

Ce Qu'il Fait

Longue durée et serverless — Conçu pour les serveurs WebSocket (voir Serveurs WebSocket), les points de terminaison SSE (voir Server-Sent Events (SSE)), les longs flux HTTP d'agents, et les API. Se réduit à zéro lorsqu'il est inactif.
Gestionnaire standard du Web — Une fonction est n'importe quelle exportation par défaut avec une méthode fetch(request) retournant une Response (compatible Workers/WinterTC). Une application Hono exporte exactement cette forme, donc export default app fonctionne tel quel. S'exécute sur Node.js 24, donc toutes les API Node sont disponibles.
Proche de votre base de données — S'exécute dans la région de la branche ; DATABASE_URL est injectée automatiquement lorsque la branche dispose de Postgres.
Brancheable — Chaque branche exécute sa propre version de la fonction à sa propre URL avec son propre état isolé.
Même CLI/API — Déployez et gérez via neon, neon.ts, ou l'API Neon.
Déclencheurs de Fonction — Neon envoie une requête POST à la fonction selon un cron. Voir Déclencheurs de Fonction.

Disponibilité

Vérifiez cette condition préalable avant toute configuration : les Neon Functions sont une fonctionnalité en bêta publique actuellement disponible dans les régions us-east-2 et eu-central-1. Confirmez que le projet Neon de l'utilisateur se trouve dans l'une de ces régions. L'utilisation des fonctions n'est pas facturée pendant la bêta publique.

Architecture : Où les Fonctions S'Intègrent

Neon (y compris les Fonctions) est un ensemble de primitives backend, pas un hébergement d'application complète. Hébergez votre application sur Vercel (ou Netlify, ou un autre hébergeur frontend/application) ; les Fonctions sont la partie longue durée et avec état de votre backend qui vit près de vos données. Elles se composent avec cette plateforme de deux manières :

Ajoutez une Fonction à une application full-stack. Votre application Next.js / TanStack Start sur Vercel (ou Netlify) gère l'UI, l'authentification (ex.: Neon Auth), et communique directement avec Lakebase Postgres et Object Storage. Lorsqu'un workload dépasse les limites serverless courtes de l'hôte — un serveur WebSocket ou SSE, ou un agent longue durée qui expirerait — déplacez uniquement cette partie vers une Neon Function. (Voir Fonctions comme Backend d'Agent pour le motif client-direct.)
Exécutez tout le plan de contrôle backend sur les Fonctions. Surtout lorsque le frontend est uniquement client — TanStack Router, React Router en mode client, et autres SPA hébergées sur Vercel ou Netlify — le client appelle les Fonctions directement. Construisez des API REST et des agents requête/réponse, hébergez des serveurs MCP, et exécutez tout ce qui nécessite un état ou qui doit être proche de Postgres et Object Storage.

Dans les deux cas, sécurisez une Fonction comme n'importe quelle API REST autonome : vérifiez un JWT ou une clé API en haut du gestionnaire (voir l'AVERTISSEMENT sous Fonctions comme Backend d'Agent). Parce qu'une Fonction est simplement votre backend, vous pouvez déplacer des éléments entre votre hébergeur et Neon — relocalisez un agent ou un serveur WebSocket avec état sur une Fonction lorsqu'il a besoin de plus de temps d'exécution, et inversement si nécessaire.

Configuration

Les Fonctions sont déclarées dans neon.ts (voir le skill neon pour le workflow axé sur les branches et les bases de neon.ts). Ajoutez @neon/config et déclarez les fonctions sous preview.functions, avec un slug comme clé :

// neon.ts
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  preview: {
    functions: {
      todos: {
        // slug : ^[a-z0-9]{1,20}$ — lettres minuscules/chiffres, pas de traits d'union
        name: "todo api", // étiquette d'affichage uniquement
        source: "src/index.ts", // fichier d'entrée, relatif à neon.ts
      },
    },
  },
});

Le slug est l'identité permanente de la fonction (il apparaît dans l'URL d'invocation et les commandes CLI) et ne peut pas être modifié après le premier déploiement. Utilisez name pour une étiquette lisible par l'humain.

Une fonction minimale — une application Hono qui interroge le Postgres de la branche via la DATABASE_URL injectée :

// src/index.ts
import { Hono } from "hono";
import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
import { parseEnv } from "@neon/env";
import { attachDatabasePool } from "@neon/functions";
import config from "../neon";
import { todos } from "./db/schema";

const env = parseEnv(config);
const pool = new Pool({ connectionString: env.postgres.databaseUrl, max: 5 });
attachDatabasePool(pool);
const db = drizzle(pool);

const app = new Hono();
app.get("/", (c) => c.text("Neon + Hono + Drizzle"));
app.post("/todos", async (c) => {
  const { text } = await c.req.json<{ text: string }>();
  const [row] = await db.insert(todos).values({ text }).returning();
  return c.json(row, 201);
});
app.get("/todos", async (c) => c.json(await db.select().from(todos)));

export default app;

Créez le pool pg au niveau du module (réutilisé entre les requêtes sur le même isolate) et gardez max petit (ex. 5), car chaque isolate conserve son propre pool. Appelez attachDatabasePool(pool) pour qu'une déconnexion inactive ne soit pas une uncaughtException — voir Connexion à Postgres.

parseEnv(config) exige toutes les variables que la configuration implique. Une fonction qui ne communique qu'avec Postgres via l'URL poolée peut se limiter à cette seule clé — parseEnv valide alors et retourne uniquement ce qui a été demandé (les clés s'autocomplètent depuis votre neon.ts) :

const { postgres } = parseEnv(config, ["DATABASE_URL"]); // pas l'URL non poolée, auth, etc.
const pool = new Pool({ connectionString: postgres.databaseUrl, max: 5 });
attachDatabasePool(pool);

Développement Local et Déploiement

neon dev      # sert chaque fonction dans neon.ts avec rechargement à chaud ; injecte DATABASE_URL et autres
neon deploy --env <fichier>   # déploiement complet préféré depuis neon.ts ; --env est le fichier d'environnement de la Fonction

Gardez .env ou .env.local à jour avec chaque clé sous preview.functions.*.env. neon env pull écrit uniquement les variables gérées par Neon ; ajoutez les secrets de la Fonction à ce fichier, puis passez-le avec --env. neon deploy --env <fichier> charge ce fichier dans process.env à chaque fois, puis télécharge ces valeurs. Une valeur manquante est undefined et defineConfig lève une erreur. Omettez la clé de neon.ts si vous ne voulez pas l'écrire. Ne forcez jamais une valeur process.env manquante en une chaîne vide (cela télécharge "" et supprime la clé en ligne). Une affectation vide (KEY=) est aussi "". Utilisez process.env.X! quand TypeScript a besoin d'une assertion.

Pour déployer une seule fonction sans appliquer neon.ts : neon functions deploy <slug> --src src/index.ts (--src prend soit le fichier d'entrée, soit un répertoire contenant index.ts, index.mjs, ou index.js). Le --env de cette commande est KEY=VALUE (répétable), pas un chemin de fichier. Utilisez-le pour une mise à jour ciblée de l'environnement. Récupérez l'URL publique avec neon functions get <slug> (le champ invocation_url, de la forme https://<branch_id>-<slug>.compute.<cell>.us-east-2.aws.neon.tech). Gérez avec neon functions list|get|delete.

Quand neon checkout crée une nouvelle branche et qu'un neon.ts est présent, il applique la politique automatiquement. Cette création-application ne charge pas --env. Si l'environnement de la Fonction lit process.env, exécutez neon deploy --env <fichier> après le checkout (ajoutez --update-existing si le checkout a déjà créé la branche). Le checkout d'une branche existante ne redéploie pas ; exécutez neon deploy --env <fichier> explicitement.

Infrastructure en tant que Code Neon (`neon.ts`)

Le bloc preview.functions de la Configuration fait partie de neon.ts, le fichier d'infrastructure en tant que code de Neon — un seul fichier TypeScript déclare chaque fonction (son source, name d'affichage, et env) avec les autres services de la branche, dans le contrôle de version (voir le skill neon pour la référence complète). Traitez-le comme Terraform pour votre branche :

neon config status   # affiche la configuration en direct de la branche (fonctions déployées)
neon config plan     # simulation des différences que apply changerait
neon config apply --env <fichier>  # regroupe + déploie les fonctions déclarées (neon deploy est un alias ; passez --env quand l'environnement de la Fonction lit process.env)

Les fonctions sont limitées à la branche : chaque branche exécute son propre déploiement à sa propre URL. Lorsqu'un neon.ts est présent, neon checkout applique la politique lors de la création d'une branche. Cette création-application ne charge pas --env. Si l'environnement de la Fonction lit process.env, exécutez neon deploy --env <fichier> après le checkout. Le checkout d'une branche existante ne redéploie pas — exécutez neon deploy --env <fichier> pour appliquer les changements.

Le réglage du déploiement par branche (ex. runtime) se trouve dans la fermeture branch, avec le slug comme clé, afin qu'il puisse varier par branche sans modifier les fonctions existantes :

export default defineConfig({
  preview: {
    functions: { todos: { name: "todo api", source: "src/index.ts" } },
  },
  branch: (branch) => ({
    preview: { functions: { todos: { runtime: "nodejs24" } } },
  }),
});

Variables d'Environnement

Neon injecte les chaînes de connexion et les URL de service limitées à la branche au moment de l'exécution — vous ne les déclarez ni ne les passez au moment du déploiement :

Variable	Notes
`NEON_BRANCH`	Le nom de la branche (ex. `main`, `preview/foo`). Injecté sur chaque branche, y compris la branche par défaut.
`DATABASE_URL`	Chaîne de connexion poolée. Utilisez pour la plupart des requêtes. Présente uniquement si la branche dispose de Postgres.
`DATABASE_URL_UNPOOLED`	Connexion directe. Utilisez pour les migrations, `LISTEN`/`NOTIFY`, les transactions multi-aller-retour.
`NEON_AUTH_BASE_URL`	Présente lorsque Neon Auth est activé sur la branche.
`NEON_DATA_API_URL`	Présente lorsque l'API Données est activée sur la branche.

Les variables du stockage d'objets (AWS_*) et de la passerelle AI (NEON_AI_GATEWAY_*) sont également injectées lorsque ces services sont déclarés — voir les skills neon-object-storage et neon-ai-gateway.

neon env pull / neon-env run / neon dev émettent également NEON_BRANCH (et les chaînes de connexion) dans votre environnement de développement local, afin que les exécutions locales reflètent l'environnement d'exécution déployé.

Vos propres secrets sont par déploiement. Chemin préféré : déclarez-les dans neon.ts et exécutez neon deploy --env <fichier>. <fichier> est le fichier ignoré par git que env pull écrit déjà (.env si ce fichier existe, sinon .env.local). Env pull écrit uniquement les variables gérées par Neon ; ajoutez les secrets de la Fonction à ce fichier. Toutes les clés d'environnement de Fonction déclarées doivent être présentes. Omettez une clé de neon.ts si vous ne voulez pas l'écrire. undefined signifie que vous avez demandé à écrire la clé et que la valeur est manquante (defineConfig lève une erreur). Ne forcez jamais une valeur process.env manquante en une chaîne vide : cela télécharge "" et supprime la clé en ligne. Une affectation vide dans le fichier (KEY=) est aussi "". Si TypeScript a besoin d'une assertion, utilisez `process.env.

neondatabase/neon-functions

Qu'est-ce que neon-functions ?

Demander à votre IA préférée

Documentation