SQLite Data Studio: rutine

Nazaj: SQLite Data Studio

Rutina je poimenovana delovna enota SQL: manifest s parametri in obliko rezultata, poleg tega pa poizvedba sama ali klic izvorne procedure.

[Live]

$routines = plugin_load('helper', 'wksqliteds');
 
// nad obstoječim PDO:
$affected = $routines->execute($pdo, 'close_inspection', ['id' => 123, 'user' => 'wolfgang']);
 
// nad poimenovano povezavo:
$rows = $routines->execute('reporting', 'reports:monthly', ['month' => '2026-07']);
 
// prek storitve wkcore:
$svc = ServiceHub::fromDokuWiki()->service('sql.routines');
$svc?->execute($pdo, 'close_inspection', ['id' => 123, 'user' => 'wolfgang']);

execute($connection, $routine, $params):

• $connection: \PDO, objekt z metodo getPdo(), ime povezave ali null (uporabi se možnost default_connection).
• $routine: „ime“ (privzeti nabor) ali „nabor:ime“; pripeta končnica .json se dopušča.
• $params: ['ime' => vrednost, ...].
• Rezultat po polju returns v manifestu, sicer se vrže RoutineException.

Manifest je datoteka <ime>.json v podmapi svoje vrste, npr. sql/Functions/close_inspection.json. Datoteka SQL, ki jo navaja, je v isti podmapi.

Ploščati (ena izvedba – prvotna specifikacija, še vedno podprta):

{
  "name": "close_inspection",
  "type": "nonquery",
  "file": "close_inspection.sql",
  "transaction": true,
  "parameters": { "id": "integer", "user": "string" },
  "returns": "rows_affected"
}

Za več zaledij (izvedbe za posamezne gonilnike):

{
  "name": "close_inspection",
  "parameters": { "id": "integer", "user": "string" },
  "returns": "rows_affected",
  "implementations": {
    "default": { "type": "sql",       "file": "close_inspection.sql",       "transaction": true },
    "mysql":   { "type": "procedure", "call": "close_inspection",           "transaction": true },
    "pgsql":   { "type": "sql",       "file": "close_inspection.pgsql.sql", "transaction": true }
  }
}

Razreševanje: ključ za konkreten gonilnik ima prednost, sicer velja default.

Datoteka type:sql sme vsebovati več stavkov; wksqliteds jih loči sam (pravila spodaj). Vsaka nadomestna oznaka :ime se prepiše v pozicijski ? in se veže (nikoli stakne) – enako za vsa zaledja, vključno z ODBC/Access. Stavek veže samo oznake, ki se v njem dejansko pojavijo (brez napake PDO HY093).

Pravila ločevanja: stavki se ločijo pri ; – vendar ne znotraj nizov ('…' z ubežnim zapisom ''), komentarjev (-- tudi za kodo v isti vrstici, /* … */) in identifikatorjev v narekovajih ("…", krativci, […]). Tudi ; znotraj bloka BEGIN … END ali CASE … END stavka ne loči: telo prožilca ali procedure ostane en stavek. Nezaključen blokovni komentar izvajanje prekine z RoutineException, namesto da bi pogoltnil preostanek datoteke.

• Seznami IN: parameter deklarirajte kot integer[]/string[] in podajte polje → (?, ?, …). Prazno polje → (NULL). V besedilu SQL stoji oznaka brez lastnih oklepajev (WHERE id IN :ids, ne IN (:ids) – sicer po razširitvi seznama nastane neveljavni IN ((?, ?))).
• Dinamični identifikatorji / vdelani PHP: datoteka rutine sme vsebovati PHP; v obsegu sta $params in $ctx. $ctx->ident('stolpec') vrne preverjen identifikator v narekovajih, kot jih zahteva pogon (edina varna pot za dinamična imena tabel in stolpcev). Vrednosti vedno ostanejo oznake :ime.

Vdelani PHP teče s polnimi pravicami aplikacije (eval, kot pri wksnippet). Zato je zavarovan večkrat:

• Potrebuje tako možnost paketa allowPhp kot globalno možnost $conf['phpok'] (dvojna vrata). Privzeto: izklopljeno. Če datoteka vsebuje PHP, vrata pa so zaprta, izvedba varno odpove (RoutineException).
• Od 2. stopnje modela pravic (podrobnosti): tudi ko so odprta obe vrata v nastavitvah, sme datoteko SQL rutine s PHP shraniti (sama zmožnost design ne zadošča) ali jo interaktivno sprožiti v studiu (sama zmožnost use ne zadošča) samo pravi superuporabnik – ne glede na to, kaj sicer dovoljuje matrika zmožnosti. Razlog: brez te dodatne vezave bi uporabnik, ki ni superuporabnik, z dovoljenjem design lahko shranil kodo PHP, ki bi pozneje tekla s polnimi pravicami aplikacije (ko bi jo sprožil sam, superuporabnik ali storitev sql.routines). Pot prek storitve sql.routines (programski klicatelji, kot je wkblog) te dodatne vezave nima – zaupa že shranjeni datoteki rutine, natanko kot pred 2. stopnjo.

// (a) z dogodkom
$controller->register_hook('WKSQLITEDS_REGISTER_ROUTINE_SETS', 'BEFORE', $this, 'sets');
public function sets(\dokuwiki\Extension\Event $event) {
    $event->data->register('reports', __DIR__ . '/sql');
}
 
// (b) programsko
plugin_load('helper', 'wksqliteds')->registerSet('reports', __DIR__ . '/sql');

Naslavljanje je nato reports:monthly. Celotna pogodba metod: referenca API. Dogodek iz časa pred preimenovanjem (WVDSDWMSQLITE_REGISTER_ROUTINE_SETS) se ne sproži več; prehodni most je bil odstranjen, ko so vsi znani paketi prešli na novo ime.

• CSRF: vsak zapis v skrbniškem delu prek checkSecurityToken().
• Avtorizacija: izvedba prek spleta (vmesnik studia) sledi matriki zmožnosti; nobena spletna končna točka ne izvede rutine samo na podlagi vnosov iz zahteve brez preverjanja.
• Prehod poti (CWE-22): imena so omejena na dovoljen nabor znakov; file je prek realpath zaprt v mapo nabora, končnica .sql.
• Vrivanje SQL (CWE-89): vrednosti so vedno vezane; identifikatorji samo prek $ctx→ident(); SQL se nikoli ne sestavlja iz vrednosti.
• Dostopni podatki: nikoli kot čisto besedilo v JSON in nikoli v sporočilih o napakah – podrobnosti: Povezave.
• XSS (CWE-79): vsi izpisi v skrbniškem delu gredo skozi hsc().
• Transakcije: transaction:true je atomaren (begin/commit oziroma SAVEPOINT pri gnezdenju), ob napaki povrnitev.

MS Access potrebuje gonilnik ODBC ACE/Jet »Microsoft Access Driver (*.mdb, *.accdb)« in pdo_odbc (Windows).

Simptom: PDOException »HY093« pri manifestu z več stavki.

Vzrok: stavek veže oznako, ki je deklarirana v drugem stavku datoteke, v tem stavku pa se ne uporablja.

Rešitev: v praksi odpade – izvajalec v vsakem stavku veže samo oznake, ki se v njem dejansko pojavijo. Če se napaka vseeno pojavi, je navadno v imenu oznake tipkarska napaka (velike in male črke se morajo ujemati).

Simptom: filter IN s parametrom seznama vrne skladenjsko napako SQL.

Vzrok: oznaka ima v besedilu SQL lastne oklepaje (IN (:ids)); po samodejni razširitvi seznama nastane neveljavni IN ((?, ?)).

Rešitev: oklepaje v besedilu SQL izpustite – IN :ids (glejte razdelek »Dinamični SQL«).

• Povezave – na katero povezavo se obrne execute()
• Pravice – preverjanje zmožnosti pri izvedbi iz studia
• Referenca API – celotna pogodba metod pomočnika
• Recepti – recept »Ustvarjanje rutine«