Conectar bases de datos

Un datasource es una base de datos registrada en una app: una conexión con nombre, tipo y credenciales, que queda disponible para todo lo que en esa app necesita datos reales — los pasos SQL de las APIs, los scripts, el modelo de datos (y, a través de él, la API GraphQL y las pantallas). La conexión se registra una vez; a partir de ahí toda la app se refiere a ella por el nombre.

En la app de ejemplo Gestión de Clientes, el datasource se llama crm — una base PostgreSQL con las tablas de cuentas, contactos y oportunidades. Es el que vas a ver en todas las figuras de este capítulo.

#Dónde encuentras los datasources

Hay dos puertas de entrada, y vas a usar las dos:

• El panel Datos — en la barra lateral del espacio de trabajo de la app, pestaña Datos, sección Fuentes de datos. Es el sitio del día a día: cada datasource se expande en un árbol con las tablas, vistas y programación de la base de datos, y el menú de cada uno da acceso a todas las acciones.
• La página Datasources — la lista completa de la app, con el tipo y la fecha de creación de cada conexión («Bases de datos accesibles para las APIs y los scripts de esta app»). También hacia aquí apuntan los atajos de la plataforma — por ejemplo el enlace Añade el primero que aparece en un paso SQL cuando la app aún no tiene datasources. En pantallas pequeñas, la navegación de la app muestra Datasources directamente.

#Crear un datasource

Vas a necesitar los datos de conexión de la base de datos: dirección del servidor, puerto, nombre de la base, usuario y contraseña — los campos exactos varían con el tipo (la página Tipos soportados detalla cada uno).

#Interno o externo

El modal de creación tiene dos pestañas, y la elección decide lo que se te pide:

Pestaña	Para qué	Lo que rellenas
Interno	Una base de datos creada y guardada por la plataforma para esta app.	Solo el Nombre interno y el motor: PostgreSQL (una base nueva en el servidor de la instalación, con credenciales propias) o SQLite (un archivo guardado con la app, con importación opcional de un archivo existente).
Externo	Una base de datos que ya existe, tuya o de otro sistema.	El tipo (PostgreSQL, MySQL, MariaDB, SQL Server u Oracle) y los datos de conexión; el botón Probar conexión confirma antes de guardar.

En una base interna nunca ves ni escribes datos de conexión: la plataforma la crea, guarda las credenciales cifradas y se conecta por ti. Si la opción PostgreSQL de la pestaña Interno aparece desactivada, el servidor PostgreSQL de la instalación aún no está configurado; pídelo al administrador de la instalación.

#Desde el panel Datos

1. Abre la pestaña Datos de la barra lateral.
2. En la sección Fuentes de datos, pulsa el botón + (Nuevo datasource). Se abre un modal — «Conecta una base de datos a esta app. Todo se cifra en reposo.»
3. Rellena el Nombre interno y elige el Tipo.
4. Rellena los campos de conexión del tipo elegido.
5. Pulsa Probar conexión y espera el «Conexión OK.» — la página Probar la conexión y seguridad explica qué hace la prueba y cómo leer los errores.
6. Pulsa Guardar. El árbol pasa a mostrar el datasource, y su pantalla Modelo se abre a continuación — lista para que importes tablas.

#Desde la página Datasources

1. Abre la página Datasources y pulsa Añadir datasource.
2. Se abre la página Nuevo datasource — «Registra las credenciales y prueba la conexión antes de guardar. Todo se cifra en reposo.» El formulario tiene dos secciones: Identificación (Nombre interno y tipo de base de datos) y Conexión (credenciales y parámetros de conexión).
3. Rellena, prueba con Probar conexión, y pulsa Crear.
4. Vuelves a la lista, con la confirmación «Datasource creado.».

#El nombre interno es la identidad

El Nombre interno (ej.: warehouse-prod, o crm en nuestro ejemplo) no es un rótulo decorativo — es el identificador por el cual las APIs y los scripts llaman a la conexión:

• En un script Python: db("crm").query("select * from contas").
• En un paso SQL de una API: el campo Datasource del paso lista los nombres registrados.

Por eso:

Regla	Qué pasa si falla
Único dentro de la app	«Ya existe un datasource con el nombre … en este proyecto.»
Sin colisiones con otro datasource	«El nombre … colisiona con el datasource …»
Estable — cámbialo solo con intención	Ver «Renombrar un datasource» abajo

#Editar la conexión

La base de datos cambió de servidor, de contraseña, o quieres activar el SSL:

1. En el panel Datos, abre el menú ⋯ del datasource y elige Editar conexión.
2. El modal se abre con todo relleno excepto la contraseña — el campo pasa a llamarse Contraseña (vacío = mantener). Déjalo en blanco para mantener la contraseña actual; escribe para sustituirla.
3. Cambia lo que necesites, pulsa Probar conexión para confirmar, y después Guardar. La confirmación es «Conexión guardada.».

#Renombrar un datasource

Haz doble clic en el nombre del datasource en el árbol del panel Datos y escribe el nuevo nombre (o cambia el Nombre interno en Editar conexión). Las tablas ya importadas al modelo siguen el nuevo nombre automáticamente.

#Eliminar un datasource

1. En la página Datasources, pulsa el icono de la papelera en la fila del datasource — o, en el panel Datos, abre el menú ⋯ y elige Eliminar datasource.
2. Lee la confirmación con atención: «Las APIs y los scripts que usan este datasource dejan de poder ejecutarse. Esta acción es permanente.» En el árbol, el aviso añade que el modelo asociado sale también.
3. Confirma en Eliminar datasource.

Lo que la eliminación quita — y lo que no toca:

Sale	Queda
La conexión registrada (nombre, tipo, credenciales)	La base de datos en sí — nada se elimina en el servidor de origen
Las tablas de ese datasource en el modelo de la app	Las APIs y scripts que lo usaban (quedan fallando hasta apuntar a otro datasource)

#Dónde se usa la conexión

Registrar el datasource es el primer paso; el valor está en lo que desbloquea:

• El árbol de objetos — expande el datasource en el panel Datos para ver Tablas, Vistas y Programación (funciones, procedimientos y triggers). Cada tabla tiene Ver datos (abre la consola con un select listo) e Importar al modelo.

• El modelo de datos — las tablas importadas se convierten en entidades del modelo, con relaciones y nombres amigables. Es el modelo el que alimenta la API GraphQL de la app y los bloques Tabla de las APIs. El capítulo del modelo de datos trata esto a fondo.

• Las APIs — en un paso SQL, elige la base en el campo Datasource y escribe la Query SQL. Los argumentos de la API entran como :nombreDelArg y el resultado del paso anterior como :prev — «Los valores van siempre parametrizados — nunca concatenados.» Hay un interruptor Devolver solo la primera fila para consultas de registro único.

• Los scripts — en Python, importa el acceso y consulta por el nombre:

  from api_manager import db
  
  def main(input):
      contas = db("crm").query(
          "select id, nome from contas where cidade = $1", ["Lisboa"]
      )
      return {"total": len(contas)}
  

  Los marcadores de parámetros ($1, ?, :1, …) varían con el motor — la tabla está en la página Tipos soportados.

#¿Por qué no veo…?

• …el botón Añadir datasource? Crear, editar y eliminar datasources está reservado a quien tiene perfil de administrador en la app. Con perfil de developer consultas la lista y usas los datasources, pero no tocas la conexión.
• …datasources en el paso SQL de mi API? La app aún no tiene ninguno — el paso muestra «Esta app no tiene datasources.» con el enlace Añade el primero.
• …tablas en el bloque Tabla de la API? El bloque Tabla lee del modelo, no del datasource directamente: «Importa tablas en la pestaña "Modelo" de un datasource primero.»