.env Secret & Syntax Checker · Prisma ORM / SQL

Prisma DATABASE_URL & .env Validator (Fix P1013 Special Character Errors)

Lint your Prisma ORM / SQL .env file locally in your browser to catch secret leaks, syntax truncation, and missing .env.example keys. Copy an auto-fixed .env or sanitized template below.

Written & verified by Chathura Prabashana · Updated November 2026

1. Paste .env or load a test scenario2. Inspect live diagnostics3. Copy cleaned config
Quick-Test Scenarios:

1. Source .env Input

.env.example Parity Diff2 matched key(s)
Missing Required Keys:
None (all template keys present)
Undocumented Keys:
SHADOW_DATABASE_URL
DATABASE_URL="postgresql://app:p%40ss%23word%3F2026@postgres:5432/app_db?schema=public"
DIRECT_URL=postgresql://app:admin%23secret@db.example.com:5432/app_db?sslmode=require
SHADOW_DATABASE_URL="postgresql://app:shadow@postgres:5432/shadow_db"
Critical
3
Warnings
0
Valid Keys
1
Missing Keys
0

Line-by-Line Diagnostics

Runs locally in your browser. Pasted .env values are never uploaded or saved to localStorage.

Typical Runtime Error (Prisma ORM / SQL .env Failure)

When syntax errors, unquoted special characters, missing keys, or public-prefix secret leaks slip into a Prisma ORM / SQL .env file, your runtime or audit pipeline surfaces an error like the output below:

Runtime Exception / Audit Output

Error: P1013: The provided database string is invalid. invalid port number in database URL — password contained unencoded "@" or "#" character.

How Prisma ORM / SQL Loads .env Files, Precedence & Security Boundaries

Prisma ORM parses DATABASE_URL and DIRECT_URL strictly according to RFC 3986 URI syntax. Whenever a randomly generated cloud database password (from Supabase, Neon, RDS, or Railway) contains reserved URL characters such as #, @, ?, or %, Prisma's Rust query engine fails immediately with Error P1013 ("The provided database string is invalid") or misparses the hostname and port.

An unencoded # inside a password is doubly destructive: first, an unquoted .env loader truncates the entire line at # as an inline comment; second, even inside double quotes, the URI parser interprets # as the start of a URL fragment; cutting off the @host:5432/db suffix completely. Similarly, an unencoded @ inside a password tricks the parser into thinking the second half of your password is the database hostname.

Serverless and connection-pooled Prisma stacks (such as Supabase Transaction Pooler / PgBouncer or Neon pooled endpoints) require two distinct connection URLs in .env: DATABASE_URL pointing at the pooled port (with ?pgbouncer=true) for runtime queries, and DIRECT_URL pointing directly at PostgreSQL port 5432 for prisma migrate deploy DDL commands.

This browser-side Prisma validator inspects both DATABASE_URL and DIRECT_URL, pinpoints exact unencoded reserved characters (#, @, ?, %) inside the password segment, and auto-generates a percent-encoded Auto-Fixed .env (%23, %40, %3F, %25) plus a credential-stripped .env.example without uploading your database credentials anywhere.

After encoding special characters in DATABASE_URL, run npx prisma validate and npx prisma migrate status locally or in staging to confirm Prisma parses both pooled and direct connections cleanly.

Because managed PostgreSQL and MySQL providers frequently auto-generate strong passwords containing #, @, ?, and % characters, verifying DATABASE_URL and DIRECT_URL encoding before running prisma migrate deploy saves teams from opaque P1013 parser failures in CI/CD. Standardize on double-quoted, percent-encoded connection strings, keep .env out of Git while documenting both DATABASE_URL and DIRECT_URL placeholders in .env.example, and test npx prisma validate as part of every pull request check.

Step-by-Step Prisma ORM / SQL .env Configuration & Hardening Guide

Apply these four concrete safeguards to eliminate silent dotenv truncation, prevent secret leaks, and keep local and production environments synchronized.

  1. 1Percent-Encode Reserved URI Characters in Password Segments

    .env

    Replace reserved URL delimiters inside the password segment (# -> %23, @ -> %40, ? -> %3F, % -> %25) while keeping the structural : and @ delimiters intact.

    .envdotenv
    # Raw password: p@ss#word?2026 -> Encoded: p%40ss%23word%3F2026
    DATABASE_URL="postgresql://app:p%40ss%23word%3F2026@postgres:5432/app_db?schema=public"
    DIRECT_URL="postgresql://app:admin%23secret@db.example.com:5432/app_db?sslmode=require"
  2. 2Wire Both url and directUrl in schema.prisma for Pooled Databases

    prisma/schema.prisma

    When deploying with PgBouncer or serverless connection poolers, configure directUrl so Prisma migrations bypass transaction pooling cleanly.

    prisma/schema.prismaprisma
    datasource db {
      provider  = "postgresql"
      url       = env("DATABASE_URL")
      directUrl = env("DIRECT_URL")
    }
  3. 3Encode Passwords Safely via Node.js encodeURIComponent()

    terminal

    Use JavaScript's built-in encodeURIComponent() on just the password string whenever rotating managed database credentials.

    terminalbash
    node -e "console.log(encodeURIComponent('p@ss#word?2026'))"
    # Output: p%40ss%23word%3F2026
  4. 4Verify Schema & Connection Parsing With Prisma CLI

    terminal

    Confirm Prisma accepts the encoded DATABASE_URL and can inspect migration history without P1013 or P1001 errors.

    terminalbash
    npx prisma validate
    npx prisma migrate status

Common Prisma ORM / SQL .env Pitfalls

Check these three framework-specific traps before deploying updated environment variables to staging or production.

Pitfall 1

Double-Encoding Already Percent-Encoded Passwords (%23 -> %2523)

Running encodeURIComponent() twice turns %23 into %2523, causing Prisma to send the literal characters "%23" as your password and fail authentication with P1000.

Pitfall 2

Forgetting That Prisma CLI Reads .env While Next.js Reads .env.local

In Next.js + Prisma projects, npx prisma migrate dev loads .env (NOT .env.local) by default. Putting DATABASE_URL exclusively inside .env.local causes Prisma CLI commands to complain that DATABASE_URL is missing.

Pitfall 3

Leaving Unescaped $ Inside DATABASE_URL Under Docker Compose

If your PostgreSQL password contains a $ sign and runs through Docker Compose interpolation, escape it as $$ in .env or percent-encode it as %24 so neither Compose nor Prisma breaks.

Related Tools

Pair Your Validated .env With Webhook HMAC, Docker Compose & CORS Tools

Now that your environment variables are syntax-clean and leak-free, verify webhook raw-body HMAC signatures, container healthchecks, and browser cross-origin rules:

Frequently Asked Questions

Why does Prisma throw P1013 "invalid port number in database URL"?
An unencoded @ or : inside your database password confused the URL parser into treating part of your password as the host:port segment. Percent-encode @ as %40 and : as %3A inside the password.
Which characters must be percent-encoded in a Prisma DATABASE_URL password?
Always percent-encode # (%23), @ (%40), ? (%3F), / (%2F), : (%3A), % (%25), and spaces (%20) inside the username or password segment of DATABASE_URL and DIRECT_URL.
Does Prisma require double quotes around DATABASE_URL in .env?
Wrapping DATABASE_URL in double quotes is strongly recommended because connection strings frequently include query parameters (?schema=public&sslmode=require) and special characters.
Why does Prisma CLI ignore my .env.local file in Next.js?
Prisma's built-in dotenv loader reads .env at the project root by default. Either keep DATABASE_URL in .env (gitignored) or run Prisma via dotenv-cli: npx dotenv -e .env.local -- prisma migrate dev.
Browse all 10 .env guides →