Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createServer
✓ import { createServer } from 'pglite-server';
✗ const { createServer } = require('pglite-server');
This package is ESM-first, CommonJS `require` syntax is not the recommended way.
LogLevel
✓ import { LogLevel } from 'pglite-server';
✗ const { LogLevel } = require('pglite-server');
Used for configuring server logging verbosity.
PGlite
✓ import { PGlite } from '@electric-sql/pglite';
This is the peer dependency that `pglite-server` connects to. It must be installed separately.
Client
✓ import { Client } from 'pg';
Used for connecting to the `pglite-server` instance from a standard Node.js PostgreSQL client like `node-postgres`.
Demonstrates how to set up a `pglite-server` instance, initialize a `PGlite` database, and connect to it using the `node-postgres` client, performing a simple query.
import { PGlite } from "@electric-sql/pglite";
import { Client } from "pg";
import { createServer } from "pglite-server";
// Define the port for the PostgreSQL server
const PORT = 5432;
async function runExample() {
// Initialize PGlite database
const db = new PGlite();
// Wait for the PGlite instance to be ready
await db.waitReady;
// Execute initial schema and data creation
await db.exec(`
create table if not exists test (id serial primary key, name text);
insert into test (name) values ('foo'), ('bar'), ('baz');
`);
// Create the pglite-server instance, passing the PGlite database
const pgServer = createServer(db);
// Start listening on the defined port
pgServer.listen(PORT, async () => {
console.log(`pglite-server bound to port ${PORT}`);
// Connect using node-postgres client
const client = new Client({
host: "localhost",
port: PORT,
database: "postgres", // Default database name
user: "postgres" // Default user
});
try {
await client.connect();
console.log("Connected to pglite-server via node-postgres client.");
const res = await client.query("select * from test");
console.log("Query result:", res.rows);
// Clean up the client connection
await client.end();
console.log("node-postgres client disconnected.");
// Stop the pglite-server
pgServer.close(() => {
console.log("pglite-server closed.");
});
} catch (error) {
console.error("Error during client connection or query:", error);
// Ensure server is closed even if client fails
pgServer.close(() => {
console.log("pglite-server closed due to error.");
});
}
});
}
runExample().catch(console.error);
Errors
Common errors & fixes
Error: connect ECONNREFUSED 127.0.0.1:5432
The `pglite-server` instance is either not running, not listening on the specified port, or another process is already using the port.
fixEnsure `pgServer.listen(PORT)` has been successfully called and the server is actively listening before attempting to connect. Check for port conflicts.
TypeError: Cannot read properties of undefined (reading 'exec')
The `PGlite` database instance was not fully initialized before attempting to perform operations.
fixAlways include `await db.waitReady;` immediately after `new PGlite()` to ensure the database is ready for queries.
Error: Cannot find module '@electric-sql/pglite' or its corresponding type declarations.
The required peer dependency `@electric-sql/pglite` is not installed in your project.
fixInstall the peer dependency: `npm install @electric-sql/pglite`.
Audit
Dependencies
@electric-sql/pgliterequiredRequired runtime database engine for the server to proxy requests to.