PgArachne

Acerca de y Arquitectura

PgArachne sirve como un servidor web ligero y de alto rendimiento que se sitúa entre tus clientes HTTP y la base de datos PostgreSQL. Elimina la necesidad de lenguajes backend tradicionales (como Python, Node.js o PHP) al mapear las peticiones HTTP directamente a funciones de la base de datos.

Capacidades Técnicas Principales

Pasarela JSON-RPC 2.0: Todas las interacciones de la API siguen la estricta especificación JSON-RPC 2.0. No hay endpoints REST que diseñar; simplemente llamas a funciones SQL por su nombre mediante peticiones POST.
Autenticación Nativa de BD: Sin tablas de usuarios separadas. Los usuarios inician sesión con sus credenciales reales de PostgreSQL para recibir un JWT. Alternativamente, las cuentas de servicio pueden usar Tokens de API persistentes.
Enmascaramiento de Roles: PgArachne se conecta como un usuario proxy pero ejecuta cada petición usando SET LOCAL ROLE para cambiar a la identidad del usuario autenticado. La seguridad a nivel de fila (Row-Level Security - RLS) funciona automáticamente.
Servidor de Archivos Estáticos: PgArachne puede servir activos estáticos (HTML, JS, CSS), permitiéndote alojar Single Page Applications (SPAs) o la herramienta Explorer directamente.

Esta arquitectura simplifica drásticamente el stack: Base de Datos ↔ PgArachne ↔ Frontend.

Formato del Endpoint de API: Todas las funciones de la base de datos están expuestas en:

POST http://{servidor}:{puerto}
/api
/{nombre_base_datos}
/{nombre_esquema}.{nombre_funcion}

Instalación

Opción A: Descargar Binarios

Descarga la última versión precompilada para tu sistema operativo:

Linux

x64/Intel/AMD ARM64/Aarch64

macOS

ARM64/Apple Silicon x64/Intel

Windows

x64/Intel/AMD ARM64

Opción B: Compilar desde el Código Fuente

git clone https://github.com/heptau/pgarachne.git
cd pgarachne
go build -o pgarachne cmd/pgarachne/main.go

Configuración de la Base de Datos

Inicializa el esquema pgarachne requerido para los tokens de API.

psql -d my_database -f sql/schema.sql

Configuración

PgArachne carga la configuración desde variables de entorno o un archivo.

Nota de Seguridad: PgArachne no maneja contraseñas de base de datos en el archivo de configuración. Confía en el mecanismo estándar de archivo .pgpass de PostgreSQL (o la variable del sistema PGPASSWORD) para la autenticación.

Orden de Búsqueda: Si no se especifica ningún archivo de configuración a través de CLI, busca en:

Directorio actual: ./pgarachne.env (Todos los SO)
Configuración de usuario:
- Linux / macOS: ~/.config/pgarachne/pgarachne.env
- Windows: %USERPROFILE%\.config\pgarachne\pgarachne.env
Configuración del sistema: /etc/pgarachne/pgarachne.env (Solo Linux / macOS)

Variable	Requerido	Descripción
Conexión a Base de Datos
`DB_HOST`	Sí	Dirección del servidor PostgreSQL (ej. `localhost`).
`DB_PORT`	No	Puerto de la base de datos. Por defecto: `5432`.
`DB_USER`	Sí	El usuario de base de datos con el que se conecta PgArachne.
Servidor HTTP
`HTTP_PORT`	No	Puerto para escuchar. Por defecto: `8080`.
`ALLOWED_ORIGINS`	No	Configuración de CORS. Lista separada por comas de dominios permitidos (ej. `https://miapp.com`). Por defecto: `*`.
`STATIC_FILES_PATH`	No	Ruta absoluta para servir archivos estáticos (Explorer/Frontend).
Seguridad (JWT)
`JWT_SECRET`	Sí	Una cadena larga y aleatoria utilizada para firmar tokens de sesión.
`JWT_EXPIRY_HOURS`	No	Validez de la sesión en horas. Por defecto: `8`.
Logging
`LOG_LEVEL`	No	Verbosidad: `DEBUG`, `INFO`, `WARN`, `ERROR`. Por defecto: `INFO`.
`LOG_OUTPUT`	No	Dónde escribir los logs: `stdout` o ruta del archivo.

Explorador de PgArachne

El Explorer es una potente interfaz web incluida en el directorio `tools/`. No es solo documentación; es una **aplicación de demostración** completamente funcional construida usando HTML/JS que se comunica con la base de datos exclusivamente a través de PgArachne.

¿Qué puede hacer?

Inspeccionar API: Lee la función `capabilities` para mostrar todos los endpoints disponibles y sus parámetros.
Pruebas en Vivo: Puedes ejecutar funciones directamente desde el navegador.
Autodocumentación: Renderiza los comentarios SQL (incluyendo metadatos `--- PARAMS ---`) en documentación legible.

Cómo habilitarlo: Establece la variable de entorno `STATIC_FILES_PATH` para que apunte a la carpeta `tools/pgarachne-explorer` en tu disco. Luego visita http://localhost:8080.

Seguridad y Autenticación

PgArachne se basa completamente en el sistema de permisos de PostgreSQL. No reinventa las Listas de Control de Acceso (ACLs). Todas las consultas se ejecutan bajo el rol de base de datos específico del usuario autenticado usando SET LOCAL ROLE.

1. Inicio de Sesión Interactivo (JWT)

Los usuarios se autentican usando su nombre de usuario y contraseña reales de PostgreSQL a través de la función de inicio de sesión. Si tiene éxito, reciben un JWT genérico. Cuando se usa este token, PgArachne cambia el rol activo a ese usuario durante la duración de la petición.

2. Cuentas de Servicio (Tokens de API)

Para sistemas automatizados o scripts, puedes usar claves API de larga duración.

Los tokens se almacenan en la tabla pgarachne.api_tokens.
Cada token se asigna a un usuario/rol de base de datos específico.
Envía el token a través del encabezado Authorization: Bearer <token>.

Configuración Crítica: Privilegios del Proxy

Dado que PgArachne se conecta como el usuario definido en DB_USER (ej. pgarachne) y cambia la identidad a otros usuarios, el usuario proxy debe ser miembro de esos roles objetivo.

Ejecuta este SQL para cada usuario/rol que necesite iniciar sesión:

-- Permitir a 'pgarachne' cambiar a 'app_user'
GRANT app_user TO pgarachne;

Despliegue y HTTPS

PgArachne está diseñado para realizar bien una sola tarea: API Gateway. Para SSL/TLS (HTTPS), seguridad de encabezados y enrutamiento público, deberías colocar un Proxy Inverso delante de él.

Opción A: Servidor Caddy

Mejor para: Despliegues de producción modernos, facilidad de uso.

Caddy es el único servidor web que obtiene y renueva certificados SSL (Let's Encrypt) automáticamente por defecto. Requiere casi cero configuración.

# Caddyfile
example.com {
    reverse_proxy localhost:8080
}

Opción B: Nginx

Mejor para: Entornos empresariales, enrutamiento complejo.

Nginx es el estándar de la industria para balanceo de carga de alto rendimiento. Úsalo si ya tienes una infraestructura Nginx. Necesitarás gestionar Certbot manualmente.

server {
    server_name example.com;
    location / {
        proxy_pass http://localhost:8080;
    }
}

Opción C: Ngrok

Mejor para: Desarrollo local, Demos, pruebas de Webhook.

Ngrok crea un túnel seguro desde internet público directamente a tu portátil sin configurar firewalls. Ideal para mostrar tu trabajo a colegas al instante.

./ngrok http 8080

Códigos de Error

PgArachne devuelve objetos de error estándar JSON-RPC 2.0. A continuación se muestran los códigos específicos que puedes encontrar:

Código	Mensaje	Significado
`-32700`	Parse error	El servidor recibió un JSON inválido.
`-32601`	Method not found	La función no existe en el esquema.
`-32602`	Invalid params	Los argumentos no coinciden con la firma de la función.
`-32001`	Permission denied	El rol de usuario actual carece de privilegios para ejecutar la función (nivel DB).
`-32000`	Internal Error	Error genérico del servidor (revisar logs).

Apoya el Desarrollo

Desarrollar software de código abierto como PgArachne requiere mucho tiempo. Si esta herramienta te ahorra tiempo, por favor considera apoyar su mantenimiento.

☕ Hazte Miembro

Únete a la comunidad en Buy Me a Coffee. Obtén actualizaciones exclusivas, acceso anticipado a nuevas características y más.

Apoyar en Buy Me a Coffee

Transferencia Bancaria

Apoyo directo con 0% de comisiones.

🇺🇸 ACH (USA)

Nombre

Zbynek Vanzura

Número de Cuenta

827908168786406

Tipo de Cuenta

Deposit

Número de Ruta

084009519

Swift/BIC

TRWIUS35XXX

Dirección del Banco

Wise US Inc, 108 W 13th St, Wilmington, DE, 19801, United States

🇪🇺 SEPA (Euro)

Nombre

Zbynek Vanzura

IBAN

BE68905813473834

Swift/BIC

TRWIBEB1XXX

Dirección del Banco

Wise, Rue du Trône 100, 3rd floor, Brussels, 1050, Belgium

🇨🇿 CZK (Chequia)

Nombre

Zbynek Vanzura

Nº de Cuenta

2300354/2010

Criptomonedas

Apoyo mediante activos digitales.

Bitcoin (BTC)

Dirección BTC

bc1qw8swmnvk48lhcatyw55wz8g4gyjq3vkw0h78g6

USDT (TetherUS)

Dirección TRC20

TPemgxu8jxkjyiHpqrUJyc3dNEs3aPSb2T

Dirección ERC20

0xa689e1c6c8da09fcecca1b9733a22619f56288ff

Binance Pay

Donar vía Binance Pay

Revolut

La forma más rápida de donar. Soporta Apple Pay, tarjetas de débito o crédito.

Donar vía Revolut

PayPal

Pagos seguros y fáciles. Soporta tarjetas de débito o crédito.

Donar vía PayPal

Wise

Pagos seguros y fáciles.

Donar vía Wise

Licencia y Marca Registrada

El Código (Licencia MIT):
Puedes usar el código fuente gratis para cualquier proyecto personal o comercial. Puedes modificarlo, bifurcarlo (fork) y distribuirlo.

La Marca (Marca Registrada):
El nombre "PgArachne" y el Logo son marcas registradas de Zbyněk Vanžura. Si bifurcas el proyecto u ofreces un servicio comercial "PgArachne Gestionado", debes eliminar la marca y el logo originales a menos que hayas obtenido una licencia especial.

¿Es PgArachne adecuado para ti?

🚀 Prototipado Rápido

🏢 Listo para Producción

🧠 Amigable con IA y LLM

Acerca de y Arquitectura

Capacidades Técnicas Principales

Instalación

Opción A: Descargar Binarios

Linux

macOS

Windows

Opción B: Compilar desde el Código Fuente

Configuración de la Base de Datos

Configuración

Explorador de PgArachne

Seguridad y Autenticación

1. Inicio de Sesión Interactivo (JWT)

2. Cuentas de Servicio (Tokens de API)

Configuración Crítica: Privilegios del Proxy

Despliegue y HTTPS

Opción A: Servidor Caddy

Opción B: Nginx

Opción C: Ngrok

Códigos de Error

Apoya el Desarrollo

☕ Hazte Miembro

Transferencia Bancaria

Criptomonedas

Revolut

PayPal

Wise

Licencia y Marca Registrada