Collegare database

Un datasource è un database registrato in un'app: una connessione con nome, tipo e credenziali, che resta disponibile per tutto ciò che in quell'app ha bisogno di dati reali — i passaggi SQL delle API, gli script, il modello dati (e, attraverso di esso, l'API GraphQL e le schermate). La connessione si registra una volta; da lì in poi tutta l'app vi si riferisce per nome.

Nell'app di esempio Gestione Clienti, il datasource si chiama crm — un database PostgreSQL con le tabelle di account, contatti e opportunità. È lui che vedrai in tutte le figure di questo capitolo.

#Dove trovi i datasource

Ci sono due porte d'ingresso, e le userai entrambe:

• Il pannello Dati — nella barra laterale dello spazio di lavoro dell'app, scheda Dati, sezione Origini dati. È il posto di tutti i giorni: ogni datasource si espande in un albero con le tabelle, le viste e la programmazione del database, e il menu di ognuno dà accesso a tutte le azioni.
• La pagina Datasource — l'elenco completo dell'app, con il tipo e la data di creazione di ogni connessione ("Database accessibili alle API e agli script di questa app."). È anche qui che puntano le scorciatoie della piattaforma — per esempio il link Aggiungi il primo che appare in un passaggio SQL quando l' app non ha ancora datasource. Su schermi piccoli, la navigazione dell'app mostra Datasource direttamente.

#Creare un datasource

Ti serviranno i dati di connessione del database: indirizzo del server, porta, nome del database, utente e password — i campi esatti variano con il tipo (la pagina Tipi supportati li dettaglia uno per uno).

#Dal pannello Dati

1. Apri la scheda Dati della barra laterale.
2. Nella sezione Origini dati, premi il pulsante + (Nuovo datasource). Si apre un modale — "Collega un database a questa app. Tutto è cifrato a riposo."
3. Compila il Nome interno e scegli il Tipo.
4. Compila i campi di connessione del tipo scelto.
5. Premi Prova connessione e aspetta il "Connessione OK." — la pagina Provare la connessione e la sicurezza spiega che cosa fa il test e come leggere gli errori.
6. Premi Salva. L'albero comincia a mostrare il datasource, e la schermata Modello di quel datasource si apre subito dopo — pronta per importare tabelle.

#Dalla pagina Datasource

1. Apri la pagina Datasource e premi Aggiungi datasource.
2. Si apre la pagina Nuovo datasource — "Registra le credenziali e prova la connessione prima di salvare. Tutto è cifrato a riposo." Il modulo ha due sezioni: Identificazione (Nome interno e tipo di database) e Connessione (credenziali e parametri di connessione).
3. Compila, prova con Prova connessione, e premi Crea.
4. Torni all'elenco, con la conferma "Datasource creato.".

#Il nome interno è l'identità

Il Nome interno (es.: warehouse-prod, oppure crm nel nostro esempio) non è un'etichetta decorativa — è l'identificatore con cui le API e gli script chiamano la connessione:

• In uno script Python: db("crm").query("select * from contas").
• In un passaggio SQL di un'API: il campo Datasource del passaggio elenca i nomi registrati.

Perciò:

Regola	Che cosa succede se fallisce
Unico dentro l'app	"Esiste già un datasource con il nome … in questo progetto."
Senza collisioni con un altro datasource	"Il nome … va in collisione con il datasource …"
Stabile — cambialo solo con intenzione	Vedi "Rinominare un datasource" qui sotto

#Modificare la connessione

Il database ha cambiato server, password, oppure vuoi attivare l'SSL:

1. Nel pannello Dati, apri il menu ⋯ del datasource e scegli Modifica connessione.
2. Il modale si apre con tutto compilato tranne la password — il campo si chiama ora Password (vuoto = mantieni). Lascialo in bianco per mantenere la password attuale; scrivi per sostituirla.
3. Cambia ciò che ti serve, premi Prova connessione per confermare, e poi Salva. La conferma è "Connessione salvata.".

#Rinominare un datasource

Fai doppio clic sul nome del datasource nell'albero del pannello Dati e scrivi il nuovo nome (oppure cambia il Nome interno in Modifica connessione). Le tabelle già importate nel modello seguono il nuovo nome automaticamente.

#Eliminare un datasource

1. Nella pagina Datasource, premi l'icona del cestino sulla riga del datasource — oppure, nel pannello Dati, apri il menu ⋯ e scegli Elimina datasource.
2. Leggi la conferma con attenzione: "Le API e gli script che usano questo datasource non potranno più essere eseguiti. Questa azione è permanente." Nell' albero, l'avviso aggiunge che se ne va anche il modello associato.
3. Conferma con Elimina datasource.

Che cosa l'eliminazione rimuove — e che cosa non tocca:

Se ne va	Resta
La connessione registrata (nome, tipo, credenziali)	Il database in sé — nel server di origine non viene cancellato nulla
Le tabelle di quel datasource nel modello dell'app	Le API e gli script che lo usavano (restano a fallire finché non puntano a un altro datasource)

#Dove viene usata la connessione

Registrare il datasource è il primo passo; il valore sta in ciò che sblocca:

• L'albero degli oggetti — espandi il datasource nel pannello Dati per vedere Tabelle, Viste e Programmazione (funzioni, procedure e trigger). Ogni tabella ha Visualizza dati (apre la console con un select pronto) e Importa nel modello.

• Il modello dati — le tabelle importate diventano entità del modello, con relazioni e nomi descrittivi. È il modello ad alimentare l'API GraphQL dell' app e i blocchi Tabella delle API. Il capitolo del modello dati tratta questo a fondo.

• Le API — in un passaggio SQL, scegli il database nel campo Datasource e scrivi la Query SQL. Gli argomenti dell'API entrano come :nomeDoArg e il risultato del passaggio precedente come :prev — "I valori sono sempre parametrizzati — mai concatenati." C'è un interruttore Restituisci solo la prima riga per le query a record singolo.

• Gli script — in Python, importa l'accesso e interroga per nome:

  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)}
  

  I segnaposto dei parametri ($1, ?, :1, …) variano con il motore — la tabella è nella pagina Tipi supportati.

#Perché non vedo…?

• …il pulsante Aggiungi datasource? Creare, modificare ed eliminare datasource è riservato a chi ha profilo di amministratore nell'app. Con profilo di developer consulti l'elenco e usi i datasource, ma non tocchi la connessione.
• …i datasource nel passaggio SQL della mia API? L'app non ne ha ancora nessuno — il passaggio mostra "Questa app non ha datasource." con il link Aggiungi il primo.
• …le tabelle nel blocco Tabella dell'API? Il blocco Tabella legge dal modello, non dal datasource direttamente: "Importa prima le tabelle nella scheda "Modello" di un datasource."