Quick Start

2 min read

Quick Start

Get a running JSON-RPC API from your PostgreSQL database in under a minute. Your database is your backend — no framework, no boilerplate.

1. Install

Download a binary

# macOS (Homebrew)
brew install heptau/tap/pgarachne

# or download the latest release for your OS:
#   https://github.com/heptau/pgarachne/releases/latest

2. Set Up Your Database

Create a database and load the PgArachne schema:

createdb my_database
psql -d my_database -f sql/schema.sql

3. Configure & Start

Create a pgarachne.env file (the server finds it in the current directory):

DB_HOST=localhost
DB_PORT=5432
DB_USER=pgarachne
JWT_SECRET=$(openssl rand -hex 32)

Start the server:

./pgarachne

4. Define a Function

In your database, create a role and a function. The function’s SQL comment documents it for LLMs.

CREATE ROLE demo_user WITH LOGIN PASSWORD 'user_password';
GRANT USAGE ON SCHEMA api TO demo_user;

CREATE OR REPLACE FUNCTION api.hello_world(payload jsonb)
RETURNS json LANGUAGE sql AS $$
    SELECT '"Hello World"'::json;
$$;
GRANT EXECUTE ON FUNCTION api.hello_world(jsonb) TO demo_user;

5. Call It

Your API endpoint is live:

curl -X POST http://localhost:8080/db/my_database/jsonrpc \
  -u demo_user:user_password \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"api.hello_world","params":{},"id":1}'
# → {"jsonrpc":"2.0","result":"Hello World","id":1}

6. Connect an AI Agent (MCP)

Expose the same functions to Claude Desktop or Cursor as tools via the MCP endpoint:

POST http://localhost:8080/db/my_database/mcp

See MCP (Model Context Protocol) for full connection instructions.

That’s it. Read the Hello World guide for the JWT authentication flow, or the comparison with PostgREST to understand where PgArachne fits.

Related Docs

← Comparison with PostgREST Installation →