Guia general
Introducción
SugaQL es un gateway analítico de solo lectura. Te conectás con cualquier cliente compatible con PostgreSQL — psql, DBeaver, TablePlus, pgAdmin o un driver en tu propio código — y ejecutás consultas SELECT sobre tus propios datos.
El modelo es simple y seguro:
Te conectás con tus credenciales y escribís consultas. SugaQL solo lee, y solo te muestra tus propios datos.
Dos garantías están siempre activas:
- Solo lectura. Únicamente se permiten SELECT (y utilidades de lectura como SHOW / DESCRIBE). INSERT, UPDATE, DELETE y cualquier cambio de estructura se rechazan.
- Aislamiento automático por cuenta. Cada consulta queda acotada de forma transparente a tu cuenta. Nunca ves datos de otra cuenta y nunca escribís vos los filtros de aislamiento — SugaQL los agrega por vos.
Cómo funciona
sequenceDiagram
participant C as Tu cliente (psql / herramienta BI / driver)
participant S as SugaQL
C->>S: conectar (TLS + credenciales)
S-->>C: identidad verificada — espacio aislado abierto
C->>S: SELECT ... FROM tu_tabla
S-->>C: solo tus datos (solo lectura, auto-acotado)Escribís consultas SELECT de SQL común. No agregás ningún filtro de propietario / cuenta / entidad — ese acotamiento es automático. Simplemente escribís la consulta de negocio que te interesa.
Antes de empezar
Todo lo que necesitás está disponible desde tu consola (la pantalla de configuración de SugaQL). Desde ahí la conexión se aprovisiona automáticamente y podés copiar los datos de conexión y descargar los archivos de seguridad.
Necesitás | Dónde obtenerlo |
|---|---|
Datos de conexión — host, puerto, nombre de base, usuario | En la pantalla de configuración de SugaQL en tu consola |
Certificado CA (ca.crt) | Botón de descarga en la pantalla de configuración |
Un certificado de cliente (client.crt + client.key) o una contraseña | Ver Conectarse de forma segura — la consola firma tu certificado y te permite resetear la contraseña |
Tu IP habilitada (si hay lista de permitidos) | Agregá tu IP/rango en la pantalla de configuración |
El nombre de tu base tiene la forma SDB-… y tu usuario es fijo por cuenta — ambos figuran en la consola. Usalos exactamente como se muestran.
Conectarse de forma segura (TLS)
Las conexiones a SugaQL están siempre cifradas, y el servidor siempre verifica al cliente. Te autenticás de una de estas formas:
Opción A — Certificado de cliente (recomendada)
Generás un par de claves localmente (tu clave privada nunca sale de tu máquina), la consola lo firma, y te conectás con el certificado resultante.
El certificado no es uno genérico — debe crearse con un tipo de clave específico, o será rechazado. La consola te muestra los comandos exactos, con tu usuario ya completado. Se ven así:
Pegá (o subí) el client.csr resultante en la consola, que te devuelve tu client.crt firmado. Junto con el ca.crt que descargaste, ya tenés los tres archivos que necesita un cliente: ca.crt, client.crt, client.key.
Opción B — Contraseña
También podés autenticarte con una contraseña por el mismo canal cifrado. Establecela o reseteala desde la consola. Igual necesitás el ca.crt (y, según tu configuración, un certificado de cliente) para establecer la conexión segura.
Conectarse con psql
Usá sslmode=verify-full (el más estricto — verifica la identidad del servidor). En clientes gráficos (DBeaver, TablePlus, pgAdmin) poné el modo SSL en Full Verification y cargá los mismos tres archivos (ca.crt, client.crt, client.key) en la pestaña SSL.
Escribir consultas
SugaQL acepta SELECT de SQL estándar. Unas pocas reglas mantienen las consultas correctas y seguras:
- Solo lectura. SELECT, WITH, SHOW, DESCRIBE. Todo lo que escriba o cambie estructura se rechaza.
- Sin filtros de cuenta. El aislamiento es automático — no agregues condiciones de owner / cuenta / entidad para acotar. Escribí solo la consulta de negocio.
- Citá los identificadores tal cual. Los nombres de columnas y tablas son sensibles a mayúsculas (camelCase). Citalos exactamente como aparecen: SELECT "createdAt" FROM "coupons".
- Algunas tablas son solo-JOIN. Unas pocas tablas solo pueden usarse dentro de un JOIN, nunca como única tabla de la consulta. El listado de tu esquema las marca.
- Se aplica un LIMIT por defecto cuando lo omitís, para que una consulta abierta nunca devuelva un resultado ilimitado. Agregá tu propio LIMIT para controlarlo.
Dialecto SQL (funciones)
SugaQL acepta un dialecto SQL específico para funciones y aritmética de fechas. Si venís de otra variante de SQL, usá las formas de la derecha:
En lugar de | Usá |
|---|---|
TOP n | LIMIT n |
GETDATE() / SYSDATE / NOW() (otros dialectos) | now() |
CURDATE() | today() |
DATEADD(unit, n, d) | addDays(d, n) / addMonths(d, n) / addHours(d, n) |
DATEDIFF(unit, a, b) | dateDiff('unit', a, b) |
NVL(x, d) / ISNULL(x, d) | ifNull(x, d) |
IIF(c, a, b) | if(c, a, b) o multiIf(...) |
LEN(x) | length(x) |
CHARINDEX(needle, hay) | position(hay, needle) |
GROUP_CONCAT(x) | arrayStringConcat(groupArray(x), ',') |
COUNT(*) | COUNT() |
CAST(x AS INT) | toInt32(x) / toInt64(x) |
CAST(x AS VARCHAR) | toString(x) |
Bloques útiles:
- Fechas/horas: today(), now(), toStartOfDay(x), toStartOfMonth(x), toDate(x), toDateTime(x).
- Ventanas de tiempo: created >= today() - 7 o created >= now() - INTERVAL 1 DAY.
- Agregados: COUNT(), sum(), avg(), min(), max(), uniq(x), quantile(0.95)(x); condicionales: countIf(cond), sumIf(expr, cond).
- Preferí listas de columnas explícitas antes que SELECT *.
Descubrir tu esquema
Solo ves las tablas y columnas que tenés permitido consultar. Para explorar:
- SHOW TABLES — lista tus tablas visibles.
- DESCRIBE <tabla> (o el explorador de tablas de tu cliente) — lista columnas + tipos.
- El Workbench de Consultas en tu consola — un editor en el navegador con explorador de tablas, un asistente, y descarga del esquema en un click (Docs, ERD, llms.txt, JSON) para referencia o para alimentar tus propias herramientas.
Los nombres de columnas ya reflejan cualquier renombre, y las columnas ocultas simplemente no aparecen — lo que ves es exactamente lo que podés consultar.
Límites y reglas
- Solo lectura: sin INSERT / UPDATE / DELETE / DDL.
- Modo de consulta simple: usá la ejecución de consultas estándar (simple). Las sentencias preparadas / parametrizadas del lado del servidor (el protocolo extendido) no están soportadas — la mayoría de los drivers funcionan tal cual; si el tuyo usa sentencias preparadas por defecto, pasalo a modo de consulta simple.
- Sin transacciones / sin cursores: las consultas corren de a una y se devuelven en una sola respuesta.
- Un solo esquema: todas tus tablas viven bajo public.
- Lista de IPs permitidas: si está habilitada para tu cuenta, solo las IPs/rangos que registres pueden conectarse.
Ejemplo de punta a punta
Resolución de problemas
Síntoma | Causa probable y solución |
|---|---|
Conexión rechazada / falla el handshake TLS | Certificado de cliente faltante/inválido, o tu IP no está en la lista. Revisá los tres archivos y agregá tu IP en la consola. |
"CSR key must be EC P-256…" al firmar | Tu solicitud de certificado usó el tipo de clave equivocado. Regenerala con el comando EC P-256 que muestra la consola (Opción A). |
Falla de autenticación | Usuario/contraseña incorrectos, o un token de sesión vencido. Reseteá la contraseña en la consola; confirmá que el usuario coincida exactamente. |
"only SELECT is supported" | Enviaste una sentencia de escritura o DDL. SugaQL es solo lectura — reformulala como SELECT. |
Errores que mencionan Parse/Bind o sentencias preparadas | Tu driver está usando el protocolo extendido. Pasalo a modo de consulta simple. |
Lista de tablas vacía o inesperada | Solo ves las tablas que podés consultar; algunas son solo-JOIN. Usá SHOW TABLES / el workbench de la consola para confirmar. |
Soporte
Contactá a tu referente de integración con tu usuario y el texto exacto del error (y la consulta, si hubo). Nunca compartas tu clave privada (client.key) ni tu contraseña — soporte nunca las necesita.