pglite-socket

A socket implementation for PGlite enabling remote connections. This package is a simple wrapper around the net module to allow PGlite to be used as a PostgreSQL server.

There are two main components to this package:

• PGLiteSocketServer - A TCP server that allows PostgreSQL clients to connect to a PGlite database instance.
• PGLiteSocketHandler - A low-level handler for a single socket connection to PGlite. This class handles the raw protocol communication between a socket and PGlite, and can be used to create a custom server.

The package also includes a CLI for quickly starting a PGlite socket server.

Note: As PGlite is a single-connection database, it is not possible to have multiple simultaneous connections open. This means that the socket server will only support a single client connection at a time. While a PGLiteSocketServer or PGLiteSocketHandler are attached to a PGlite instance they hold an exclusive lock preventing any other connections, or queries on the PGlite instance.

Installation

1npm install @electric-sql/pglite-socket
2# or
3yarn add @electric-sql/pglite-socket
4# or
5pnpm add @electric-sql/pglite-socket

Usage

1import { PGlite } from '@electric-sql/pglite'
2import { PGLiteSocketServer } from '@electric-sql/pglite-socket'
3
4// Create a PGlite instance
5const db = await PGlite.create()
6
7// Create and start a socket server
8const server = new PGLiteSocketServer({
9  db,
10  port: 5432,
11  host: '127.0.0.1',
12})
13
14await server.start()
15console.log('Server started on 127.0.0.1:5432')
16
17// Handle graceful shutdown
18process.on('SIGINT', async () => {
19  await server.stop()
20  await db.close()
21  console.log('Server stopped and database closed')
22  process.exit(0)
23})

API

PGLiteSocketServer

Creates a TCP server that allows PostgreSQL clients to connect to a PGlite database instance.

Options

• db: PGlite - The PGlite database instance
• port?: number - The port to listen on (default: 5432)
• host?: string - The host to bind to (default: 127.0.0.1)
• path?: string - Unix socket path to bind to (takes precedence over host:port)
• inspect?: boolean - Print the incoming and outgoing data to the console (default: false)

Methods

• start(): Promise<void> - Start the socket server
• stop(): Promise<void> - Stop the socket server

Events

• listening - Emitted when the server starts listening
• connection - Emitted when a client connects
• error - Emitted when an error occurs
• close - Emitted when the server is closed

PGLiteSocketHandler

Low-level handler for a single socket connection to PGlite. This class handles the raw protocol communication between a socket and PGlite.

Options

• db: PGlite - The PGlite database instance
• closeOnDetach?: boolean - Whether to close the socket when detached (default: false)
• inspect?: boolean - Print the incoming and outgoing data to the console in hex and ascii (default: false)

Methods

• attach(socket: Socket): Promise<PGLiteSocketHandler> - Attach a socket to this handler
• detach(close?: boolean): PGLiteSocketHandler - Detach the current socket from this handler
• isAttached: boolean - Check if a socket is currently attached

Events

• data - Emitted when data is processed through the handler
• error - Emitted when an error occurs
• close - Emitted when the socket is closed

Example

1import { PGlite } from '@electric-sql/pglite'
2import { PGLiteSocketHandler } from '@electric-sql/pglite-socket'
3import { createServer, Socket } from 'net'
4
5// Create a PGlite instance
6const db = await PGlite.create()
7
8// Create a handler
9const handler = new PGLiteSocketHandler({
10  db,
11  closeOnDetach: true,
12  inspect: false,
13})
14
15// Create a server that uses the handler
16const server = createServer(async (socket: Socket) => {
17  try {
18    await handler.attach(socket)
19    console.log('Client connected')
20  } catch (err) {
21    console.error('Error attaching socket', err)
22    socket.end()
23  }
24})
25
26server.listen(5432, '127.0.0.1')

Examples

See the examples directory for more usage examples.

CLI Usage

This package provides a command-line interface for quickly starting a PGlite socket server.

1# Install globally
2npm install -g @electric-sql/pglite-socket
3
4# Start a server with default settings (in-memory database, port 5432)
5pglite-server
6
7# Start a server with custom options
8pglite-server --db=/path/to/database --port=5433 --host=0.0.0.0 --debug=1
9
10# Using short options
11pglite-server -d /path/to/database -p 5433 -h 0.0.0.0 -v 1
12
13# Show help
14pglite-server --help

CLI Options

• -d, --db=PATH - Database path (default: memory://)
• -p, --port=PORT - Port to listen on (default: 5432)
• -h, --host=HOST - Host to bind to (default: 127.0.0.1)
• -u, --path=UNIX - Unix socket to bind to (takes precedence over host:port)
• -v, --debug=LEVEL - Debug level 0-5 (default: 0)
• -r, --run=COMMAND - Command to run after server starts
• --include-database-url - Include DATABASE_URL in subprocess environment
• --shutdown-timeout=MS - Timeout for graceful subprocess shutdown in ms (default: 5000)

Development Server Integration

The --run option is particularly useful for development workflows where you want to use PGlite as a drop-in replacement for PostgreSQL. This allows you to wrap your development server and automatically provide it with a DATABASE_URL pointing to your PGlite instance.

1# Start your Next.js dev server with PGlite
2pglite-server --run "npm run dev" --include-database-url
3
4# Start a Node.js app with PGlite
5pglite-server --db=./dev-db --run "node server.js" --include-database-url
6
7# Start multiple services (using a process manager like concurrently)
8pglite-server --run "npx concurrently 'npm run dev' 'npm run worker'" --include-database-url

When using --run with --include-database-url, the subprocess will receive a DATABASE_URL environment variable with the correct connection string for your PGlite server. This enables seamless integration with applications that expect a PostgreSQL connection string.

Using in npm scripts

You can add the CLI to your package.json scripts for convenient execution:

1{
2  "scripts": {
3    "db:start": "pglite-server --db=./data/mydb --port=5433",
4    "db:dev": "pglite-server --db=memory:// --debug=1",
5    "dev": "pglite-server --db=./dev-db --run 'npm run start:dev' --include-database-url",
6    "dev:clean": "pglite-server --run 'npm run start:dev' --include-database-url"
7  }
8}

Then run with:

1npm run dev          # Start with persistent database
2npm run dev:clean    # Start with in-memory database

Unix Socket Support

For better performance in local development, you can use Unix sockets instead of TCP:

1# Start server on a Unix socket
2pglite-server --path=/tmp/pglite.sock --run "npm run dev" --include-database-url
3
4# The DATABASE_URL will be: postgresql://postgres:postgres@/postgres?host=/tmp

Connecting to the server

Once the server is running, you can connect to it using any PostgreSQL client:

Using psql

1PGSSLMODE=disable psql -h localhost -p 5432 -d template1

Using Node.js clients

1// Using node-postgres
2import pg from 'pg'
3const client = new pg.Client({
4  host: 'localhost',
5  port: 5432,
6  database: 'template1'
7})
8await client.connect()
9
10// Using postgres.js
11import postgres from 'postgres'
12const sql = postgres({
13  host: 'localhost',
14  port: 5432,
15  database: 'template1'
16})
17
18// Using environment variable (when using --include-database-url)
19const sql = postgres(process.env.DATABASE_URL)

Limitations and Tips

• Remember that PGlite only supports one connection at a time. If you're unable to connect, make sure no other client is currently connected.
• For development purposes, using an in-memory database (--db=memory://) is fastest but data won't persist after the server is stopped.
• For persistent storage, specify a file path for the database (e.g., --db=./data/mydb).
• When using debug mode (--debug=1 or higher), additional protocol information will be displayed in the console.
• To allow connections from other machines, set the host to 0.0.0.0 with --host=0.0.0.0.
• SSL connections are NOT supported. For psql, set env var PGSSLMODE=disable.
• When using --run, the server will automatically shut down if the subprocess exits with a non-zero code.
• Use --shutdown-timeout to adjust how long to wait for graceful subprocess termination (default: 5 seconds).

License

Apache 2.0