SQL over HTTP & WebSocket

Some runtimes — serverless functions, edge workers, and other environments with short-lived execution or no raw TCP — aren't a great fit for a long-lived Postgres socket. For those, Silos exposes SQL over HTTP and WebSocket, so you can run queries with a plain fetch() and a token.

HTTP: one query, one request

Send a SQL statement to the HTTP SQL endpoint for your database:

POST /v1/sql/{db_id}

const res = await fetch(`https://api.silos.sh/v1/sql/${dbId}`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.SILOS_API_KEY}`,
  },
  body: JSON.stringify({
    query: 'SELECT id, email FROM users WHERE id = $1',
    params: [userId],
  }),
})

const { rows } = await res.json()

Use parameterized queries ($1, $2, …) with a params array — never build SQL by string concatenation. This is the same parameter binding the wire protocol uses, and it's your defense against SQL injection.

WebSocket: a session over a socket

When you need an interactive session — multiple round-trips, or a transaction that spans several statements — open a WebSocket:

WS /v1/sql/{db_id}/ws

const ws = new WebSocket(`wss://api.silos.sh/v1/sql/${dbId}/ws`)

ws.addEventListener('open', () => {
  ws.send(JSON.stringify({
    query: 'SELECT now()',
  }))
})

ws.addEventListener('message', (event) => {
  const result = JSON.parse(event.data)
  console.log(result.rows)
})

Authenticate the WebSocket the way your client supports — for example a bearer token in the upgrade request. Keep the socket open for the life of the session and close it when you're done.

Choosing a transport

Next steps