Skip to main content
Build your agent on Neon and provision backends you fully control. See how Ideavo does it
/Functions/Environment variables

Neon Functions environment variables

Neon-injected variables and how to set your own secrets.

View as Markdown

Neon-injected variables

Neon injects connection strings, credentials, and service URLs automatically at runtime. You don't declare these in neon.ts or pass them at deploy time. They're resolved from the branch the function is deployed to. This is why a function doesn't configure Postgres, the AI Gateway, or Object Storage itself: enable the service, and its credentials are there in process.env.

Each variable is present only when its service is enabled on the branch. DATABASE_URL and DATABASE_URL_UNPOOLED, for example, are undefined on a functions-only branch with no Postgres database.

VariableServiceDescription
DATABASE_URLPostgresPooled connection string. Use this for most queries.
DATABASE_URL_UNPOOLEDPostgresDirect connection string. Use for migrations, LISTEN/NOTIFY, and multi-round-trip transactions.
NEON_BRANCHCoreBranch name (e.g. main, preview/foo). Present on all branches.
NEON_BRANCH_IDCoreBranch ID (e.g. br-cool-darkness-123456). Present on all branches.
NEON_FUNCTION_HOST_SUFFIXFunctionsHostname suffix shared by the branch's functions, e.g. .compute.c-2.us-east-2.aws.neon.tech.
NEON_AUTH_BASE_URLManaged Better AuthBase URL for Managed Better Auth.
NEON_AUTH_JWKS_URLManaged Better AuthJWKS endpoint for verifying Managed Better Auth JWTs. See Authentication.
NEON_DATA_API_URLData APIBase URL for the Neon Data API (PostgREST). Present when the Data API is provisioned on the branch.
NEON_AI_GATEWAY_TOKENAI GatewayGateway bearer token.
NEON_AI_GATEWAY_BASE_URLAI GatewayGateway host root. Append a dialect route, e.g. /v1 for Chat Completions or /openai/v1 for the OpenAI Responses API.
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEYObject StorageS3-compatible credentials for the branch's buckets.
AWS_ENDPOINT_URL_S3, AWS_REGIONObject StorageS3 endpoint and region. The AWS_* names mean the AWS SDKs work with no setup.

These variables are branch-scoped: each branch injects its own values. A function deployed to a preview branch connects to that branch's database, not the default branch's.

Two AI Gateway endpoints

NEON_AI_GATEWAY_BASE_URL is the bare gateway host: append a dialect path yourself. Use /openai/v1 for the OpenAI Responses API and /v1 for Chat Completions (see Chat completions). The @neon/ai-sdk-provider handles this routing for you.

Local pull vs. deployed runtime

A deployed function gets credentials injected automatically for every service enabled on its branch, so you don't ship a .env. For local development, neon env pull writes the branch's core variables plus credentials for any services you declare in neon.ts, which can be a subset. Declare a service (auth: true, dataApi: true, aiGateway: true, buckets: { ... }) to pull its credentials locally and to get type-safe access. (Outside a neon.ts workflow, neon env pull still writes the branch's core variables — see the env command.)

For type-safe access, the @neon/env package ships parseEnv. It takes your neon.ts config and returns a typed env object validated against the services the config declares:

import { parseEnv } from '@neon/env';
import config from './neon';

const env = parseEnv(config);
env.postgres.databaseUrl;          // DATABASE_URL
env.postgres.databaseUrlUnpooled;  // DATABASE_URL_UNPOOLED
env.auth.baseUrl;                  // NEON_AUTH_BASE_URL (only when auth: true)
env.auth.jwksUrl;                  // NEON_AUTH_JWKS_URL (only when auth: true)

TypeScript narrows the shape based on your config: env.auth is only present when auth: true is set in neon.ts.

User-defined variables

Each deployment carries its own snapshot of user-defined variables. To change one, deploy again.

At deploy time

Pass --env KEY=VALUE to neon functions deploy. The flag is repeatable:

neon functions deploy hello --src functions/hello.ts --env RESEND_API_KEY=re_...

Neon injects variables like DATABASE_URL, NEON_AI_GATEWAY_*, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_ENDPOINT_URL_S3, and AWS_REGION when the matching service is enabled on the branch. These are defaults, not reserved names: if you define a variable with the same name, your value overrides the injected one.

A deploy doesn't wipe variables set by earlier deploys. The --env flags you pass are merged into the existing set:

  • --env KEY=value adds or updates KEY
  • --env KEY= (empty value) deletes KEY
  • Variables you don't mention carry over unchanged

In neon.ts

Declare variables under the function's env field. Values are resolved when neon deploy runs, so you can read from process.env to avoid hardcoding secrets. Declare each one with a required rule so neon deploy fails if it's unset. This form needs Neon CLI 9.2.0 or later and @neon/config 1.13.0 or later, plus @neon/env 2.1.0 or later if your function reads the variables with parseEnv:

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

export default defineConfig({
  functions: {
    hello: {
      name: "My first function",
      source: "./functions/hello.ts",
      env: {
        RESEND_API_KEY: { value: process.env.RESEND_API_KEY, required: true },
      },
    },
  },
});

Load a .env file before running neon deploy to make secrets available during config evaluation:

neon deploy --env .env.production

The file isn't forwarded to the function directly. Only variables declared in the env field are deployed; --env only controls what process.env contains when neon.ts is evaluated.

Unlike --env, a declared variable that's unset when you deploy is removed from the function, unless you declare it with onUndefined: "skip". required: true fails the deploy on every branch when the value is unset. Use required: "default-branch" for a variable only the default branch's deployment needs, or required: false for one that's optional everywhere. See Function env in the neon.ts reference for how unset values are removed or kept.

Pull variables locally

neon link and neon checkout pull the branch's Neon-injected variables into a local .env file automatically (pass --no-env-pull to skip). To re-pull at any time:

neon env pull

By default this writes to .env if it exists, otherwise .env.local. Use --file to write to any file:

neon env pull --file .env.preview

To pull from a different branch, switch with neon checkout; it pulls the new branch's variables as part of the switch.

env pull writes only the Neon-managed variables and preserves every other line in the file. That's the core variables DATABASE_URL, DATABASE_URL_UNPOOLED, NEON_BRANCH, and NEON_BRANCH_ID, plus the variables for any service you declare in neon.ts: the Managed Better Auth URLs, the Neon Data API URL, the AI Gateway credentials (NEON_AI_GATEWAY_TOKEN, NEON_AI_GATEWAY_BASE_URL), and the Object Storage credentials (AWS_*). It also writes NEON_FUNCTION_HOST_SUFFIX, which together with NEON_BRANCH_ID lets code running locally build the same function URLs as deployed code. See Call another function.

Call another function

Every function on a branch answers at https://<NEON_BRANCH_ID>-<slug><NEON_FUNCTION_HOST_SUFFIX>. Neon injects both variables into every deployed function. Locally, neon env pull writes them, and neon dev sets them for the functions it serves. functionBaseUrl from @neon/env 2.0.0 or later builds the URL for you, without a trailing slash:

import { functionBaseUrl } from '@neon/env';

const res = await fetch(`${functionBaseUrl('hello')}/greet`);

Under neon dev, functionBaseUrl returns http://localhost:<port> for each function that neon dev is serving and the deployed URL for any other slug. It throws a TypeError for an invalid slug, and a PlatformError when either variable is missing.

functionBaseUrl reads process.env by default. When the two variables come from somewhere else, pass them as the second argument:

functionBaseUrl('hello', { NEON_BRANCH_ID: branchId, NEON_FUNCTION_HOST_SUFFIX: hostSuffix });

Browser code can't read these variables. Build the URL on the server with functionBaseUrl and pass it to the client.

Neon CLI 9.0.0 and @neon/env 2.0.0 replaced the per-function NEON_FUNCTION_<SLUG>_BASE_URL variables, which deployed functions never received. If your code reads env.functions.<slug>.baseUrl, upgrade to @neon/env 2 and call functionBaseUrl('<slug>') instead.

Constraints

ConstraintValue
Max variables per deployment1,000
Max total size32 KiB

The total size counts every variable's name and value. A deploy that exceeds it fails with 400 invalid environment: total size <N> bytes exceeds the 32768-byte limit. To fix it, remove or shorten variables in the same deploy. Leave some headroom: the variables Neon injects at runtime, such as DATABASE_URL, also count toward the limit when your function runs.

Need help?

Join our Discord Server to ask questions or see what others are doing with Neon. For paid plan support options, see Support.

Last updated on

Was this page helpful?
Edit on GitHub