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í \# 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=\<tu usuario>/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 psql "sslmode=verify full \\ sslrootcert=ca crt \\ sslcert=client crt \\ sslkey=client key \\ host=\<host> port=\<puerto> user=\<tu usuario> dbname=\<sdb >" 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 \# 1) conectar (archivos descargados/generados desde la consola) psql "sslmode=verify full sslrootcert=ca crt sslcert=client crt sslkey=client key \\ host=\<host> port=\<puerto> user=\<tu usuario> dbname=\<sdb >" # 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