Vite dev-only plugin that bootstraps and runs a local PostgreSQL server for your app.
npm install vite-postgresVite dev-only plugin that bootstraps and runs a local PostgreSQL server for your app.
- Runs on vite dev only (apply: 'serve')
- Uses your system Postgres binaries (initdb, postgres, createdb, pg_isready)
- Picks a free port automatically and injects Postgres env vars for your app
``sh`
pnpm add -D vite-postgres
vite.config.ts
`ts
import { defineConfig } from 'vite'
import postgres from 'vite-postgres'
export default defineConfig({
plugins: [
postgres({
// dbPath: '.postgres', // persist in-repo (optional)
// dbName: 'myapp', // defaults to Vite root folder name
// user: { name: 'dev', password: 'devpass' }, // optional superuser credentials
// seedModule: 'src/seed.ts' // optional, runs after DB is ready
// verbose: true, // optional, inherit Postgres logs in Vite output
// logFile: 'postgres.log', // optional, relative to Vite root (ignored if verbose)
}),
],
})
`
Then start Vite. Your app can connect using the injected env:
- PGHOST=127.0.0.1PGPORT=
- PGDATABASE=
- PGDATA=
- PGUSER=
- PGPASSWORD=
-
Example connection strings:
`sh`
psql "host=$PGHOST port=$PGPORT dbname=$PGDATABASE"or (common default)
psql "postgresql://127.0.0.1:$PGPORT/$PGDATABASE"
`ts`
export interface VitePostgresOptions {
dbPath?: string
dbName?: string
user?: { name: string; password: string }
seedModule?: string
strictPort?: number
verbose?: boolean
logFile?: string
}
- dbPath: Postgres data directory. Default: ${os.tmpdir()}/vite-postgres/dbName
- : Database name. Default: Vite root folder nameuser
- : Superuser credentials to create and expose via env vars. If unset, env vars default to OS username + "postgres" and no superuser is created.seedModule
- : Module path (relative to Vite root) to execute after the DB is readystrictPort
- : Force Postgres to bind to this port and wait if it's unavailable.verbose
- : Inherit Postgres stdout/stderr in the Vite process. Default: false (logs go to a file)logFile
- : Where to write Postgres logs (relative to Vite root). Default: ${PGDATA}/postgres.log (ignored if verbose)
If seedModule is set, it’s loaded via server.ssrLoadModule(...) after:
1. initdb (only if PG_VERSION missing)postgres
2. startedpg_isready
3. succeedscreatedb
4. attempted (ignored if it already exists)
The module can be TS/ESM and can run whatever you want (migrations, seed data, etc).
- Auth is initialized with --auth=trust (no password). This is for local dev.user
- A passworded superuser role is created (or updated) only when is provided.${PGDATA}/postgres.log
- Logs go to to keep Vite output clean (unless verbose is enabled).
- The Postgres process is terminated when Vite exits (SIGINT for fast shutdown).
- PostgreSQL installed and on your PATH (initdb, postgres, createdb, pg_isready)
- Node compatible with Vite 7+
- Failed to initialize DB. Ensure "initdb" is in your PATH.: install Postgres (or add its bin/ directory to PATH).process.env.PGPORT
- Port conflicts: the plugin chooses a free port each run; read from your app instead of hard-coding 5432`.