Databases verbinden

Een datasource is een database die in een app geregistreerd is: een verbinding met een naam, een type en inloggegevens, die beschikbaar komt voor alles wat in die app echte gegevens nodig heeft — de SQL-stappen van de API's, de scripts, het gegevensmodel (en, daardoorheen, de GraphQL-API en de schermen). De verbinding registreert u één keer; vanaf dat moment verwijst de hele app ernaar bij naam.

In de voorbeeld-app Klantenbeheer heet de datasource crm — een PostgreSQL-database met de tabellen van accounts, contactpersonen en kansen. Dat is de datasource die u in alle figuren van dit hoofdstuk terugziet.

#Waar u de datasources vindt

Er zijn twee ingangen, en u gaat ze allebei gebruiken:

• Het paneel Data — in de zijbalk van de werkruimte van de app, tabblad Data, sectie Datasources. Dat is de plek voor het dagelijkse werk: elke datasource klapt uit tot een boom met de tabellen, views en programmering van de database, en het menu van elk geeft toegang tot alle acties.
• De pagina Datasources — de volledige lijst van de app, met het type en de aanmaakdatum van elke verbinding ("Databases die toegankelijk zijn voor de API's en de scripts van deze app"). Ook de snelkoppelingen van het platform wijzen hierheen — bijvoorbeeld de link Voeg de eerste toe die in een SQL-stap verschijnt wanneer de app nog geen datasources heeft. Op kleine schermen toont de navigatie van de app Datasources rechtstreeks.

#Een datasource aanmaken

U hebt de verbindingsgegevens van de database nodig: adres van de server, poort, naam van de database, gebruiker en wachtwoord — de precieze velden verschillen per type (de pagina Ondersteunde types beschrijft ze stuk voor stuk).

#Vanuit het paneel Data

1. Open het tabblad Data van de zijbalk.
2. Klik in de sectie Datasources op de knop + (Nieuwe datasource). Er opent een modaal venster — "Verbind een database met deze app. Alles wordt versleuteld opgeslagen."
3. Vul de Interne naam in en kies het Type.
4. Vul de verbindingsvelden van het gekozen type in.
5. Klik op Verbinding testen en wacht op "Verbinding OK." — de pagina De verbinding testen en beveiliging legt uit wat de test doet en hoe u de fouten leest.
6. Klik op Opslaan. De boom toont voortaan de datasource, en het scherm Model ervan gaat meteen open — klaar om tabellen te importeren.

#Vanuit de pagina Datasources

1. Open de pagina Datasources en klik op Datasource toevoegen.
2. De pagina Nieuwe datasource gaat open — "Leg de inloggegevens vast en test de verbinding voordat u opslaat. Alles wordt versleuteld opgeslagen." Het formulier heeft twee secties: Identificatie (Interne naam en type database) en Verbinding (inloggegevens en verbindingsparameters).
3. Vul in, test met Verbinding testen, en klik op Aanmaken.
4. U keert terug naar de lijst, met de bevestiging "Datasource aangemaakt.".

#De interne naam is de identiteit

De Interne naam (bijv. warehouse-prod, of crm in ons voorbeeld) is geen decoratief etiket — het is de identificatie waarmee de API's en de scripts de verbinding aanroepen:

• In een Python-script: db("crm").query("select * from contas").
• In een SQL-stap van een API: het veld Datasource van de stap somt de geregistreerde namen op.

Daarom:

Regel	Wat er gebeurt als het misgaat
Uniek binnen de app	"Er bestaat in dit project al een datasource met de naam …"
Geen botsingen met een andere datasource	"De naam … botst met de datasource …"
Stabiel — wijzig hem alleen met opzet	Zie "Een datasource hernoemen" hieronder

#De verbinding bewerken

De database is van server veranderd, van wachtwoord, of u wilt SSL inschakelen:

1. Open in het paneel Data het menu ⋯ van de datasource en kies Verbinding bewerken.
2. Het modale venster gaat open met alles ingevuld behalve het wachtwoord — het veld heet dan Wachtwoord (leeg = behouden). Laat het leeg om het huidige wachtwoord te behouden; typ om het te vervangen.
3. Wijzig wat u nodig hebt, klik op Verbinding testen om het te bevestigen, en daarna op Opslaan. De bevestiging is "Verbinding opgeslagen.".

#Een datasource hernoemen

Dubbelklik op de naam van de datasource in de boom van het paneel Data en typ de nieuwe naam (of wijzig de Interne naam in Verbinding bewerken). De tabellen die al in het model geïmporteerd zijn, volgen de nieuwe naam automatisch.

#Een datasource verwijderen

1. Klik op de pagina Datasources op het prullenbakpictogram in de regel van de datasource — of open in het paneel Data het menu ⋯ en kies Datasource verwijderen.
2. Lees de bevestiging aandachtig: "De API's en de scripts die deze datasource gebruiken, kunnen niet meer worden uitgevoerd. Deze actie is definitief." In de boom voegt de waarschuwing eraan toe dat het bijbehorende model eveneens verdwijnt.
3. Bevestig met Datasource verwijderen.

Wat het verwijderen weghaalt — en wat het niet aanraakt:

Verdwijnt	Blijft
De geregistreerde verbinding (naam, type, inloggegevens)	De database zelf — er wordt niets gewist op de bronserver
De tabellen van die datasource in het model van de app	De API's en scripts die haar gebruikten (die blijven falen tot ze naar een andere datasource wijzen)

#Waar de verbinding gebruikt wordt

De datasource registreren is de eerste stap; de waarde zit in wat hij ontsluit:

• De objectenboom — klap de datasource in het paneel Data uit om Tabellen, Views en Programmering (functies, procedures en triggers) te zien. Elke tabel heeft Gegevens bekijken (opent de console met een select klaar) en Naar model importeren.

• Het gegevensmodel — de geïmporteerde tabellen worden entiteiten van het model, met relaties en weergavenamen. Het is het model dat de GraphQL-API van de app en de blokken Tabel van de API's voedt. Het hoofdstuk over het gegevensmodel behandelt dit grondig.

• De API's — kies in een SQL-stap de database in het veld Datasource en schrijf de SQL-query. De argumenten van de API komen binnen als :naamVanHetArg en het resultaat van de vorige stap als :prev — "De waarden gaan altijd geparameteriseerd mee — nooit aaneengeschakeld." Er is een schakelaar Alleen de eerste rij teruggeven voor query's op één record.

• De scripts — importeer in Python de toegang en bevraag op naam:

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

  De parametermarkeringen ($1, ?, :1, …) verschillen per engine — de tabel staat op de pagina Ondersteunde types.

#Waarom zie ik niet…?

• …de knop Datasource toevoegen? Datasources aanmaken, bewerken en verwijderen is voorbehouden aan wie het profiel van beheerder in de app heeft. Met het profiel van developer raadpleegt u de lijst en gebruikt u de datasources, maar komt u niet aan de verbinding.
• …datasources in de SQL-stap van mijn API? De app heeft er nog geen — de stap toont "Deze app heeft geen datasources." met de link Voeg de eerste toe.
• …tabellen in het blok Tabel van de API? Het blok Tabel leest uit het model, niet rechtstreeks uit de datasource: "Importeer eerst tabellen op het tabblad "Model" van een datasource."