--- title: Guia general slug: sugaql-guia-general docTags: createdAt: 2026-07-16T14:23:10.096Z --- # 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: :::BlockQuote **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: 1. **Solo lectura.** Únicamente se permiten SELECT (y utilidades de lectura como SHOW / DESCRIBE). INSERT, UPDATE, DELETE y cualquier cambio de estructura se rechazan. 2. **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 ```mermaid 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 | :::BlockQuote 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í: :::BlockQuote *# 1) Generar una clave privada (EC P-256 — obligatorio)* openssl ecparam -genkey -name prime256v1 -out client.key *# 2) Generar la solicitud de firma (el CN debe ser igual a tu usuario)* openssl req -new -key client.key -out client.csr -subj "/CN=\/O=SugaQL" ::: 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 :::BlockQuote psql "sslmode=verify-full \\ sslrootcert=ca.crt \\ sslcert=client.crt \\ sslkey=client.key \\ host=\ port=\ user=\ dbname=\" ::: 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: 1. **Solo lectura.** SELECT, WITH, SHOW, DESCRIBE. Todo lo que escriba o cambie estructura se rechaza. 2. **Sin filtros de cuenta.** El aislamiento es automático — **no** agregues condiciones de owner / cuenta / entidad para acotar. Escribí solo la consulta de negocio. 3. **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". 4. **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. 5. **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 \** (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 :::BlockQuote *# 1) Conectar (archivos descargados/generados desde la consola)* psql "sslmode=verify-full sslrootcert=ca.crt sslcert=client.crt sslkey=client.key \\ host=\ port=\ user=\ dbname=\" *# 2) Ver qué podés consultar* SHOW TABLES; *# 3) Una consulta de negocio simple — sin filtro de cuenta, aplica el LIMIT por defecto* SELECT "createdAt", "amount" FROM "coupons" ORDER BY "createdAt" DESC LIMIT 20; *# 4) Un agregado de los últimos 7 días* SELECT toStartOfDay("createdAt") AS day, COUNT() AS total FROM "coupons" WHERE "createdAt" >= today() - 7 GROUP BY day ORDER BY day; ::: # 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.