🐘 PGlite HTTP Server for Railway

> PostgreSQL in WebAssembly with a full HTTP API. Run a complete Postgres database in your Railway app without needing a separate database service!

⚡ What is PGlite?

PGlite is PostgreSQL compiled to WebAssembly - a real Postgres database that runs anywhere JavaScript runs. This template wraps it with a REST API so you can use it like any other database service.

🎯 Why Use This?

• Zero Configuration: No connection strings, no external database setup
• 100% PostgreSQL Compatible: Full SQL support, transactions, indexes
• Persistent Storage: Data survives restarts using Railway volumes
• Cost Effective: No separate database charges
• Perfect For: Prototypes, side projects, demos, development

🚀 Quick Start

Deploy to Railway

1. Click the "Deploy on Railway" button above
2. Wait for deployment to complete
3. Your PGlite database is ready!

Environment Variables

Railway Volume Setup (IMPORTANT!)

To persist your database:

1. Go to your Railway project
2. Click on your service → Settings → Volumes
3. Click Add Volume
4. Mount path: /app/data
5. Redeploy your service

Without a volume, your database will be reset on each deployment!

Deploy and Host

This section provides comprehensive guidance on deploying and hosting the PGlite HTTP Server, including options for Railway and local environments.

About Hosting

Hosting the PGlite HTTP Server means running a Node.js-based application that embeds a WebAssembly-compiled PostgreSQL database (PGlite) and exposes it through a RESTful HTTP API. This setup allows for seamless integration into web applications or services without requiring a traditional database server. On platforms like Railway, hosting is handled via containerized deployment, where the app runs in a managed environment with automatic scaling, networking, and storage options. Data persistence is achieved through mounted volumes, ensuring your database remains intact across restarts or redeploys. This approach is serverless-friendly, portable, and eliminates the overhead of managing separate database instances.

Why Deploy

Deploying the PGlite HTTP Server simplifies database management by providing a lightweight, embedded PostgreSQL solution that runs directly within your application stack. It reduces operational complexity, as there's no need for external database provisioning, connection pooling, or compatibility worries—everything is self-contained and 100% PostgreSQL-compatible. Deployment on Railway is particularly advantageous due to its one-click setup, built-in CI/CD, and cost savings (no extra fees for database services). It's ideal for rapid iteration in development, testing edge cases without infrastructure costs, or running small-scale production apps where high availability isn't critical. Overall, it empowers developers to focus on building features rather than managing databases.

Common Use Cases

• Rapid prototyping of applications requiring a relational database without setup overhead.
• Development and staging environments where a real PostgreSQL instance is needed but full-scale hosting is overkill.
• Educational tools or demos for learning SQL and database concepts in a browser or app context.
• Single-tenant apps or MVPs with low data volumes (e.g., <100MB).
• Integration with AI agents or edge computing where a lightweight DB is essential.
• Backup for traditional databases in hybrid setups for offline or local testing.

Dependencies for

This project relies on a minimal set of dependencies to keep it lightweight and easy to maintain. It uses Node.js as the runtime environment and includes packages for the PGlite core, HTTP server, and basic utilities.

• Runtime Dependencies: Node.js (v18 or higher), npm or yarn for package management.
• Core Packages:
  • @electric-sql/pglite: The WebAssembly PostgreSQL library.
  • express: For handling HTTP requests and routing the API.
  • body-parser: To parse JSON request bodies for queries and transactions.
• Development Dependencies: Tools like nodemon for local development, typescript if using TS, and testing libraries (e.g., jest).
• No External Services: Unlike traditional setups, no additional databases, caches, or queues are required.

Deployment Dependencies

For successful deployment, especially on Railway:

• Platform Requirements: A Railway account (free tier sufficient for starters), with support for Node.js runtimes.
• Build Tools: Railway automatically handles npm install and build steps via package.json scripts.
• Storage: A mounted volume (as detailed in Quick Start) for persistent data storage.
• Networking: Railway's public or private networking; optional custom domain for production.
• Security Add-ons: Environment variables for API keys (e.g., API_KEY), rate-limiting middleware if added.
• No Heavy Dependencies: Ensure your app stays within Railway's memory limits (e.g., 512MB for hobby plans); PGlite's small footprint helps here.

📚 API Reference

Health Check

GET /health

Response:

{
  "status": "healthy",
  "database": "connected",
  "dataDir": "/app/data",
  "timestamp": "2025-01-15T10:00:00.000Z"
}

Execute SQL Query

POST /query
Content-Type: application/json
{
  "query": "SELECT * FROM users WHERE id = $1",
  "params": [1]
}

Response:

{
  "success": true,
  "rows": [
    { "id": 1, "name": "John", "email": "[email protected]" }
  ],
  "rowCount": 1,
  "fields": [
    { "name": "id", "dataTypeID": 23 },
    { "name": "name", "dataTypeID": 25 }
  ]
}

Execute Transaction

POST /transaction
Content-Type: application/json
{
  "queries": [
    {
      "query": "INSERT INTO users (name, email) VALUES ($1, $2)",
      "params": ["Alice", "[email protected]"]
    },
    {
      "query": "UPDATE users SET name = $1 WHERE email = $2",
      "params": ["Bob", "[email protected]"]
    }
  ]
}

List All Tables

GET /tables

Response:

{
  "success": true,
  "tables": ["users", "posts", "comments"]
}

Get Table Schema

GET /tables/users/schema

Response:

{
  "success": true,
  "tableName": "users",
  "columns": [
    {
      "column_name": "id",
      "data_type": "integer",
      "is_nullable": "NO",
      "column_default": "nextval('users_id_seq'::regclass)"
    }
  ]
}

Export Database

GET /export

Downloads SQL dump file of entire database.

Import SQL

POST /import
Content-Type: application/json
{
  "sql": "CREATE TABLE products (id SERIAL, name TEXT);"
}

Database Statistics

GET /stats

Response:

{
  "success": true,
  "database_size": "8192 bytes",
  "tables": [
    {
      "schemaname": "public",
      "tablename": "users",
      "size": "16 kB"
    }
  ]
}

🛡️ Security Considerations

⚠️ IMPORTANT: This template has NO authentication by default. Anyone with your URL can access your database!

2. Use Railway's Private Networking
3. Implement Rate Limiting
4. Whitelist SQL commands (block DROP, DELETE, etc. if needed)

📊 Limitations

• Single Instance Only: PGlite doesn't support horizontal scaling
• Memory Constraints: Keep database size under Railway's memory limits
• Not for Production: Use for development, prototypes, or small apps

🎯 Use Cases

Perfect for:

• ✅ Side projects and MVPs
• ✅ Development/staging environments
• ✅ Prototypes and demos
• ✅ Learning PostgreSQL
• ✅ Apps with < 100MB data
• ✅ Single-tenant applications

Not recommended for:

• ❌ High-traffic production apps
• ❌ Multi-gigabyte databases
• ❌ Apps requiring high availability
• ❌ Complex replication setups

🔗 Links

• PGlite Documentation
• Railway Documentation
• PostgreSQL Documentation

Made with ❤️ for the Railway community