The Complete Production SOP: How to Deploy and Run Bun Native HTTP Server & High-Speed Embedded SQLite in Autonomous AI Agents

---
name: "bun-native-http-server-sqlite"
description: "Run high-throughput HTTP servers and embedded SQLite queries with Bun native APIs."
metadata:
  author: "Jarred Sumner"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "use bun.serve"
  - "query bun:sqlite database"
  - "run bun native websockets"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# Bun Native HTTP Server & High-Speed Embedded SQLite

Develops applications using Bun: Bun.serve({ fetch, port }), WebSockets with per-socket data, Bun's built-in bun:sqlite database with prepared statements, and environment variable loading.

## When to Invoke
Invoke this skill whenever you need to:
- use bun.serve
- query bun:sqlite database
- run bun native websockets

## Execution SOP & Rules
1. Start server: Bun.serve({ port: 3000, fetch(req, server) {
   const url = new URL(req.url);
   if (url.pathname === '/ws') {
     if (server.upgrade(req)) return;
     return new Response('Upgrade failed', { status: 400 });
   }
   return new Response('Hello Bun!');
 } }).
2. Connect SQLite: import { Database } from 'bun:sqlite'; const db = new Database('app.db', { create: true }); db.exec('PRAGMA journal_mode = WAL;');
3. Execute prepared statement: const query = db.query('SELECT * FROM users WHERE id = ?'); query.get(1);
4. Enable WebSockets: pass websocket: { message(ws, msg) { ws.send('Echo: ' + msg); } } to Bun.serve.

## Verification Checklist
- Run local linting, syntax validation, and type-checks before reporting completion.
- Ensure all created or modified files adhere to workspace boundaries and avoid uncommitted secrets.
- Verify tests or build commands exit cleanly with return code 0.

import { Database } from 'bun:sqlite';

export interface UserRecord {
  id: number;
  username: string;
  created_at: string;
}

// Initialize database file within workspace boundaries
export const db = new Database('app.db', { create: true });

// Enforce production WAL pragma for concurrent reader/writer safety
db.exec(`
  PRAGMA journal_mode = WAL;
  PRAGMA synchronous = NORMAL;
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    username TEXT NOT NULL UNIQUE,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
  );
`);

// Prepared statements cached for high-frequency operations
export const insertUserStmt = db.prepare('INSERT INTO users (username) VALUES (?) RETURNING id, username, created_at');
export const getUserByIdStmt = db.query('SELECT id, username, created_at FROM users WHERE id = ?');

import { db, insertUserStmt, getUserByIdStmt, type UserRecord } from './db';

interface SocketData {
  sessionId: string;
  connectedAt: number;
}

export const server = Bun.serve<SocketData>({
  port: Number(process.env.PORT) || 3000,
  fetch(req, server) {
    const url = new URL(req.url);

    // Handle WebSocket Upgrade
    if (url.pathname === '/ws') {
      const sessionId = crypto.randomUUID();
      const upgraded = server.upgrade(req, {
        data: { sessionId, connectedAt: Date.now() }
      });
      return upgraded
        ? undefined
        : new Response('WebSocket upgrade failed', { status: 400 });
    }

    // REST: Fetch User
    if (url.pathname.startsWith('/users/') && req.method === 'GET') {
      const id = url.pathname.split('/')[2];
      const user = getUserByIdStmt.get(Number(id)) as UserRecord | null;
      if (!user) return new Response(JSON.stringify({ error: 'User not found' }), { status: 404 });
      return Response.json(user);
    }

    // REST: Create User
    if (url.pathname === '/users' && req.method === 'POST') {
      return req.json().then((body: { username?: string }) => {
        if (!body.username) return new Response('Missing username', { status: 400 });
        const created = insertUserStmt.get(body.username) as UserRecord;
        return Response.json(created, { status: 201 });
      });
    }

    return new Response('Not Found', { status: 404 });
  },
  websocket: {
    open(ws) {
      ws.subscribe('system-alerts');
      ws.send(JSON.stringify({ event: 'connected', sessionId: ws.data.sessionId }));
    },
    message(ws, message) {
      ws.publish('system-alerts', `Broadcast from ${ws.data.sessionId}: ${message}`);
    },
    close(ws) {
      ws.unsubscribe('system-alerts');
    }
  }
});

console.log(`Server listening on ${server.url}`);

import { describe, expect, it } from 'bun:test';
import { server } from './server';

describe('Bun Native Service Gate', () => {
  it('creates and fetches users via SQLite', async () => {
    const createRes = await server.fetch(new Request('http://localhost:3000/users', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ username: 'agent_user_1' })
    }));
    expect(createRes.status).toBe(201);
    const created = await createRes.json();

    const fetchRes = await server.fetch(new Request(`http://localhost:3000/users/${created.id}`));
    expect(fetchRes.status).toBe(200);
    const fetched = await fetchRes.json();
    expect(fetched.username).toBe('agent_user_1');
  });
});