Quiq::Database::Connection - Verbindung zu einer Relationalen Datenbank
Quiq::Hash
Ein Objekt der Klasse repräsentiert eine Verbindung zu einer Relationalen Datenbank.
$db = $class->new(@opt); $db = $class->new($udl,@opt); $db = $class->new($udlObj,@opt); $db2 = $db->new(@opt);
connect()
In diesem Verzeichnis werden Ergebnismengen gecacht, wenn dies bei Selektionen angefordert wird.
Bereits aufgebaute Low-Level Datenbankverbindung zuweisen.
Logging von SQL-Statements.
Logdatei. Wenn nicht angegeben oder '-' wird auf STDOUT gelogged.
Name der Sql-Klasse zur Statementgenerierung.
Aktiviere oder deaktiviere automatische Fehlerbehandlung.
Definiere das clientseitige Character Encoding als UTF-8.
Instantiiere eine Datenbankverbindung und liefere eine Referenz auf dieses Objekt zurück.
Ist $udl nicht angegeben, wird der Wert der Environment-Variable $UDL verwendet.
Wird die Methode als Objektmethode einer bestehenden Datenbankverbindung gerufen, wird eine weitere Verbindung zur selben Datenbank aufgebaut. Dies ist nützlich, wenn eine parallele Transaktion benötigt wird.
$db = $class->newFromSbit($db,@opt);
$db->disconnect; $db->disconnect($commit);
destroy()
Schließe Datenbankverbindung. Ist $commit "wahr", committe die Daten vor dem Schließen der Verbindung. Die Methode liefert keinen Wert zurück.
Die Objektreferenz $db ist nach Aufruf der Methode ungültig und kann nicht mehr verwendet werden.
$bool = $class->dbExists($udl);
Prüfe, ob Verbindung zur Datenbank $udl möglich ist. Liefere "wahr", wenn dies der Fall ist, andernfalls "falsch".
$n = $db->maxBlobSize; $n = $db->maxBlobSize($n);
Liefere/Setze die maximale Größe eines BLOB/TEXT-Werts auf $n Bytes. Defaulteinstellung ist 1024*1024 Bytes (1MB).
Dieser Wert ist nur für Oracle relevant und wird bei der Selektion von BLOB/TEXT-Kolumnen benötigt. Ist der Wert einer BLOB/TEXT-Kolumne größer als die angegebene Anzahl an Bytes wird eine Exception ausgelöst.
Bei anderen DBMSen als Oracle hat das Setzen keinen Effekt und der Returnwert der Methode ist immer 0.
$bool = $db->strict; $bool = $db->strict($bool);
Bei eingeschaltetem Strict-Modus wird im Falle eines Datenbankfehlers eine Exception geworfen.
my $db = Quiq::Database::Connection->new('dbi#mysql', -handle => $main::dbh, ); ... $db->strict(1); # bei Datenbank-Fehler wird Exception geworfen $db->strict(0) # bei Datenbank-Fehler wird keine Exception geworfen
$sqlObj = $db->stmt;
sqlEngine()
gen()
Liefere das Sql-Objekt der Datenbankverbindung. Mit dem Sql-Objekt lassen sich SQL-Statements generieren, z.B.
$stmt = $db->stmt->dropTable($table);
$udlObj = $db->udl;
Liefere das Udl-Objekt der Datenbankverbindung. Das Udl-Objekt hält Information über die Datenbankverbindung, z.B.
$user = $db->udl->user;
$time = $cur->startTime;
$time = $cur->time;
Die folgenden Methoden testen auf das DBMS. Sie werden angewendet, wenn DBMS-spezifische Unterscheidungen vorgenommen werden müssen.
$dbms = $db->dbms;
($oracle,$postgresql,$sqlite,$mysql,$access,$mssql,$jdbc) = $db->dbmsTestVector;
$bool = $db->isOracle;
Liefere "wahr", wenn die Datenbank eine Oracle-Datenbank ist, sonst "falsch".
$bool = $db->isPostgreSQL;
Liefere "wahr", wenn die Datenbank eine PostgreSQL-Datenbank ist, sonst "falsch".
$bool = $db->isSQLite;
Liefere "wahr", wenn die Datenbank eine SQLite-Datenbank ist, sonst "falsch".
$bool = $db->isMySQL;
Liefere "wahr", wenn die Datenbank eine MySQL-Datenbank ist, sonst "falsch".
$bool = $db->isAccess;
Liefere "wahr", wenn die Datenbank eine Access-Datenbank ist, sonst "falsch".
$bool = $db->isMSSQL;
Liefere "wahr", wenn die Datenbank eine MSSQL-Datenbank ist, sonst "falsch".
$bool = $db->isJDBC;
Liefere "wahr", wenn die Datenbank eine JDBC-Datenbank ist, sonst "falsch".
$dbh = $db->handle;
$rowClass = $this->defaultRowClass($raw);
Liefere den Namen der Default-Rowklasse:
Quiq::Database::Row::Object ($raw ist "falsch") Quiq::Database::Row::Array ($raw ist "wahr")
Auf die Default-Rowklasse werden Datensätze instantiiert, für die bei einer Datenbank-Selektion oder einer Instantiierung einer Table-Klasse keine Row-Klasse explizit angegeben wurde.
Alle Statements einer Session oder ein gewisser Abschnitt kann gelogged werden.
Für die gesamte Session:
$db = Quiq::Database::Connection->new($udl,-log=>1);
Innerhalb eines Abschnitts:
$db->openLog; ... $db->closeLog;
Testen, ob Db-Logging eingeschaltet ist:
$db->isLog;
Schreiben eigener Meldungen ins Log:
$db->printLog($msg);
Scheiben von Fortschrittsmeldungen ins Log:
$db->startProgressLog($n); while (...) { $db->printProgressLog($msg); } $db->endProgressLog;
$bool = $db->isLog;
$db->openLog;
$db->writeLog(@str);
Schreibe Argumente @str ins geöffnete SQL-Log. Ist das SQL-Log nicht geöffnet, wird nichts geschrieben. Die Methode liefert keinen Wert zurück.
$db->msgToLog($msg);
printLog()
Schreibe Meldung $msg ins SQL-Log. Die Methode liefert keinen Wert zurück.
Der Logfileeintrag hat folgenden Aufbau:
<LogMsgSeparator> <LogMsgPrefix> <msg>
Mit Defaultwerten:
--- # <msg>
Ist die Meldung mehrzeilig, wird der LogMsgPrefix jeder Zeile vorangestellt.
$db->stmtToLog($stmt);
Schreibe SQL Statement $stmt ins SQL-Log. Die Methode liefert keinen Wert zurück.
<LogMsgSeparator> <stmt>
=== <stmt>
$db->timeToLog($time);
Schreibe Ausführungszeit $time ins SQL-Log. Die Methode liefert keinen Wert zurück.
Der Logfileeintrag hat per Default folgenden Aufbau:
/* <time> */
$db->closeLog;
$db->startProgressLog($n);
$db->printProgressLog($msg);
Schreibe Fortschrittsmeldung $msg ins SQL-Log. Die Methode liefert keinen Wert zurück.
<LogMsgPrefix> <msg>
# <msg>
Ist die Meldung mehrzeilig, wird sie einzeilig gemacht, indem NEWLINE durch SPACE ersetzt wird.
$db->endProgressLog($msg);
$db->exportTable($table,$file);
Exportiere die Daten der Tabelle $table in Datei $file.
$db->importTable($table,$file);
Importiere die Daten aus Datei $file in Tabelle $table.
$db->lockTable($table);
$cur = $db->sql($stmt,@opt);
Cache die Datensätze, die das Statement $stmt liefert, für $n Sekunden. D.h. hole die Datensätze innerhalb dieser Zeitspanne nicht erneut von der Datenbank, sondern lies sie aus dem Cache. Ist $n 0, werden die Datensätze unbegrenzt lange gecacht.
Fetche Datensätze in Chunks von $n Sätzen. Diese Option hat aktuell nur bei PostgreSQL und -fetchMode 1 oder 2 eine Bedeutung.
Der Parameter hat nur im Falle PostgreSQL eine Auswirkung. Siehe auch Abschnitt "SELECT mit PostgreSQL".
Normaler DBI::Pg-Fetchmodus, d.h. die gesamte Ergebnismenge wird zum Client transferiert, bevor dieser den ersten Datensatz erhält. Dieser Modus ist für große Datenmengen schlecht geeignet.
Die Datensätze werden in Chunks von -chunkSize Sätzen gefetcht. Dies ist der Default-Modus.
Wie 1, wobei zusätzlich eine eigene Connection für die Selektion geöffnet wird. Dies ist notwendig, wenn während der Datensatz-Verarbeitung COMMITs oder ROLLBACKs ausgeführt werden sollen. Eine Cursor-basierte Selektion wird bei PostgreSQL ohne eigene Connection wird mit dem ersten COMMIT oder ROLLBACK ungültig.
Forciere die Ausführung des Statement. Dies kann bei Oracle PL/SQL Code notwendig sein, wenn Konstrukte enthalten sind, die von DBI/DBD irrtümlich als Bind-Variablen interpretiert werden. Z.B. bei folgender Trigger-Definition das ":new":
CREATE OR REPLACE TRIGGER x_before_insert BEFORE INSERT ON x FOR EACH ROW BEGIN :new.create_date := sysdate; END;
Ohne -forceExec=>1 würde das Statement lediglich präpariert, nicht ausgeführt.
Schreibe SQL-Statement und Ausführungszeit nach STDOUT.
Fetche die Datensätze als einfache Arrays statt als komplexe Row-Objekte. Als Default-Rowklasse verwende Quiq::Database::Row::Array statt Quiq::Database::Row::Object (der Parameter -rowClass überschreibt diesen Default).
Name der Datensatzklasse, auf die die Datensätze der Ergebnismenge geblesst werden.
Name der Tabellenklasse, die die Ergebnismenge speichert. Bei Raw-Datensätzen ist Quiq::Database::ResultSet::Array der Default, ansonsten Quiq::Database::ResultSet::Object.
Referenz auf Cursor-Objekt (Quiq::Database::Cursor)
Führe SQL-Statement $stmt über Datenbankverbindung $db aus, instantiiere ein Resultat-Objekt (Cursor), und liefere eine Referenz auf dieses Objekt zurück.
SELECT mit PostgreSQL
Bei PostgreSQL (DBD::Pg) holt ein SELECT erst die gesamte Ergebnismenge zum Client. Das ist für große Ergebnismengen fatal.
Um die Datensätze in Chunks zu holen, muss ein CURSOR verwendet werden:
DECLARE <cursor> CURSOR FOR <stmt>; FETCH <n> FROM <cursor>; ... CLOSE <cursor>;
Hierbei ist:
<cursor> der Name des Cursors <stmt> das SELECT-Statement <n> die Anzahl der zu fetchenden Datensätze
Die Methode $db->sql() implementiert im Falle von PostgreSQL SELECTs durch obige Anweisungsfolge, wenn die Option -fetchMode gesetzt ist.
-fetchMode=>0|1|2 (Default: 0) 0=Defaultverhalten, 1=dekl. Cursor, 2=dekl. Cursor + extra Session -chunkSize=>$n (Default: 500) Fetche Datensätze in Chunks von $n Stück
$cur = $db->sqlAtomic($stmt,@opt);
Führe DDL-Statement $stmt aus, instantiiere ein Resultat-Objekt (Cursor), und liefere eine Referenz auf dieses Objekt zurück.
Das Statement wird atomar ausgeführt, d.h. ist das Statement erfolgreich, wird anschließend ein COMMIT ausgeführt, schlägt das Statement fehl, wird ein ROLLBACK ausgeführt.
Dieses Verhalten ist insbesondere im Falle von PostgreSQL wichtig, da bei PostgreSQL praktisch alles einer Transaktionskontrolle unterliegt. Z.B. können erzeugte Objekte nicht zugriffen werden, solange ihre Erzeugung nicht abgeschlossen ist, d.h. der Zugriff auf die erzeugten Objekte wird blockiert. Oder das Setzen von Session-Einstellungen verfällt mit einem ROLLBACK. usw.
$str = $db->execute($stmt,@opt);
SQL-Statement.
Alle Optionen der Methode $db->sql() plus
Zeige das Resultat der Statement-Ausführung farbig an.
Begrenze die Anzahl der gefetchten Datensätze auf $n.
Ausführungsergebnis (String)
Führe DDL-Statement $stmt aus und liefere das Ergebnis der Ausführung in Form eines Textes zurück. Im Falle einer Selektion werden die selektierten Datensätze in einer ASCII-Tabelle dargestellt. Die maximale Anzahl der selektierten Datensätze ist per Default auf 10 begrenzt (siehe Option -limit).
Die Methode ist nützlich für die Programmierung von einfachen Terminal-Clients für Ad-Hoc-Abfragen.
$n = $db->applyPatches($patchClass);
(String) Klasse, die die Patchmethoden enthält.
(Integer) Anzahl der angewandten Patch-Methoden.
Wende alle offenen Patches auf die Datenbank an. Die Patches sind als Methoden in der Klasse $patchClass implementiert. Die Patch-Methoden haben das Namensmuster
patchNNN
Hierbei ist NNN der Patchlevel, den die Methode implementiert. Der aktuelle Patchlevel der Datnbank ist der maximale Wert der Kolumne PAT_LEVEL in Tabelle PATCH. Es werden alle Patch-Methoden angewandt, deren Patchlevel größer ist als der aktuelle Patchlevel. Existiert die Tabelle PATCH nicht, wird sie angelegt.
$patchLevel = $this->maxPatchLevel($patchClass);
Name der Klasse, die die Patchmethoden enthält.
(Integer) Maximaler Patchlevel.
Ermittele den maximalen Patchlevel, also die höchste Nummer unter allen Patch-Methoden, die in der Klasse $patchClass implementiert sind, und liefere diesen zurück.
$patchLevel = $db->patchLevel;
(Integer) Patchlevel der Datenbank.
Ermittele den aktuellen Patchlevel der Datenbank und liefere diesen zurück. Existiert die Tabelle PATCH auf der Datenbank nicht oder hat sie keinen Eintrag, liefert die Methode 0.
@patchMethods | $patchMehodA = $this->patchMethods($patchClass);
(Array of Pairs) Liste der Patch-Methoden der Klasse $patchClass. Im Skalarkontext eine Referenz auf die Liste.
Ermittele die Liste der Patch-Mehoden der Klasse $patchClass und liefere diese zurück. Ein Element der Liste ist ein Paar, bestehend aus dem Methoden-Namen und einer Glob-Referenz, über die die Patch-Methode aufgerufen werden kann. Die Liste ist aufsteigend nach Methodenname sortiert.
$report = $db->patchReport($patchClass);
(String) Patch-Bericht
Erzeuge einen Bericht über den Stand der Patches auf der Datenbank und liefere diesen zurück. Der Bericht hat den Aufbau:
NAME001() - DESCRIPTION001 (STATUS001) NAME002() - DESCRIPTION002 (STATUS002) ...
NAMEXXX - Name der Patchmethode des Patch XXX DESCRIPTIONXXX - Beschreibung des Patch XXX STATUSXXX - Status des Patch XXX ('applied' oder 'new')
$cur = $db->setSchema($schema);
Setze das Default-Schema der Session und liefere das Resultat der Ausführung zurück.
Das Datenbank-Objekt merkt sich das Default-Schema. Von mehreren Aufrufen hintereinander mit dem selben Schema, wird nur der erste Aufruf gegenüber dem DBMS ausgeführt, die anderen sind Null-Operationen.
$cur = $db->setEncoding($charset);
$cur = $db->setDateFormat;
$cur = $db->setNumberFormat;
$cur = $db->setSearchPath(@schemas);
Setze den Schema-Suchpfad und liefere einen Cursor mit dem Ergebnis der Statementausführung zurück.
PostgreSQL / Greenplum
Der Schema-Suchpfad wird von PostgreSQL genutzt, um Datenbank-Objekte zu finden, die nicht mit einem Schema-Präfix qualifiziert sind. Das erste Schema der Liste ist gleichzeitig das Default-Schema, in dem Datenbank-Objekte erzeugt werden (unabhängig davon, ob sie sich in einem anderen Schema des Suchpfads befinden).
$n = $db->runCount;
Liefere die Anzahl der in der aktuellen Transaktion ausgeführten Statements. Diese Information kann z.B. genutzt werden, um zu entscheiden, ob ein COMMIT oder ROLLBACK ausgeführt werden müsste.
$cur = $db->begin;
Beginne Transaktion und liefere das Resultat der Ausführung zurück.
$cur = $db->commit; $cur = $db->commit($commit);
Bestätige alle auf der Datenbank durchgeführten Änderungen und liefere das Resultat der Ausführung zurück.
Wird die Methode mit Argument aufgerufen, entscheidet dessen Wahrheitswert, ob ein COMMIT oder ein ROLLBACK ausgeführt wird. Im Falle von "wahr" wird ein COMMIT ausgeführt, im Falle von "falsch" ein ROLLBACK.
$cur = $db->rollback;
Verwirf alle auf der Datenbank durchgeführten Datenänderungen.
$cur = $db->save($table,$row,@where);
Aktualisiert den Datensatz $row gemäß seines Status auf der Datenbank $db und liefere das Resultat der Statement-Ausführung zurück.
Welche Datenbankoperation konkret ausgeführt wird, ergibt sich aus dem Status des Datensatzes.
Statuswerte
Es wird keine Datenbankoperation ausgeführt.
Es wird eine Update-Operation auf der Datenbank ausgeführt, d.h. es wird die Methode $row->update() gerufen.
Es wird eine Insert-Operation auf der Datenbank ausgeführt, d.h. es wird die Methode $row->insert() gerufen.
Es wird eine Delete-Operation auf der Datenbank ausgeführt, d.h. es wird die Methode $row->delete() gerufen.
$titleA|@titles = $db->titles(@select);
Ermittele die Liste der Kolumentitel zum Statement @select und liefere diese zurück. In skalaren Kontext liefere eine Referenz auf die Liste.
Anmerkung: Die Titelliste wird gecacht. Je Statement wird die Datenbank nur einmal befragt. Alle weiteren Aufrufe werden aus dem Cache befriedigt.
$title = $db->primaryKey($table);
Liefere die Primärschlüsselkolumne der Tabelle $table.
Die Primärschlüsselkolumne ist per Definition die erste Kolumne der Tabelle. Datenmodelle mit zusammengesetzten Primärschlüsseln werden nicht unterstützt.
$tab|@rows|$cur|$stmt = $db->select(@select,@opt);
Siehe Quiq::Database::Connection/sql().
Führe das Statement nicht aus, sondern liefere das SQL-Statemement zurück.
$tab|@rows|$cur = $db->selectWith($stmt,@select,@opt);
SELECT-Statement, das in eine WITH Klausel eingebettet wird.
Siehe select()
Bette SELECT-Statement $stmt in eine WITH-Klausel ein und führe die Selektion über dieser WITH-Klausel aus. Die WITH-Klausel hat den Vorteil, dass die Bedingungen der WHERE-Klausel über den Kolumnennamen der SELECT-Liste formuliert werden können.
Eine Selektion über dem Statement
SELECT fun.oid AS fun_oid , usr.usename AS fun_owner , nsp.nspname AS fun_schema , fun.proname AS fun_name , pg_get_function_identity_arguments(fun.oid) AS fun_arguments , fun.proname || '(' || COALESCE(pg_get_function_identity_arguments(fun.oid), '') || ')' AS fun_signature , pg_get_functiondef(fun.oid) AS fun_source FROM pg_proc AS fun JOIN pg_namespace AS nsp ON fun.pronamespace = nsp.oid JOIN pg_user usr ON fun.proowner = usr.usesysid
liefert zwar Datensätze mit den eigens vergebenen Kolumnennamen fun_oid, fun_owner usw. Diese Namen können jedoch nicht bei der Formulierung der WHERE-Klausel verwendet werden. Stattdessen müssen die Namen der zugrundeliegenden Tabellen verwendet werden. Diese Assymetrie, die eine wirkliche Kapselung verhindert, lässt sich vermeiden, wenn das Statement in eine WITH-Klausel eingebettet und über dieser die Selektion formuliert wird. In dem Fall können (und müssen) die Namen des eingebetteten SELECT verwendet werden. Hier eine Suche via fun_name ($stmt ist obiges Statement):
$stmt = $sql->selectWith($stmt, -select => 'fun_schema','fun_signature', -where => fun_name => 'check_bigint', fun_arguments => 'text, boolean, text, text', -orderBy => 'fun_schema', );
liefert
WITH qry AS ( SELECT fun.oid AS fun_oid , usr.usename AS fun_owner , nsp.nspname AS fun_schema , fun.proname AS fun_name , pg_get_function_identity_arguments(fun.oid) AS fun_arguments , fun.proname || '(' || COALESCE(pg_get_function_identity_arguments(fun.oid), '') || ')' AS fun_signature , pg_get_functiondef(fun.oid) AS fun_source FROM pg_proc AS fun JOIN pg_namespace AS nsp ON fun.pronamespace = nsp.oid JOIN pg_user usr ON fun.proowner = usr.usesysid ) SELECT fun_schema , fun_signature FROM qry WHERE fun_name = 'check_bigint' AND fun_arguments = 'text, boolean, text, text' ORDER BY fun_schema
$tab|@rows|$cur = $db->selectFrom($stmt,@select,@opt);
Bette SELECT-Statement $stmt inline in eine FROM-Klausel ein und führe die Selektion aus. Die Inline-Einbettung hat den Vorteil, dass die Bedingungen der WHERE-Klausel über den Kolumnennamen der SELECT-Liste formuliert werden können:
... FROM ( STMT ) AS query
Analog zu selectWith().
$row|@vals = $db->lookup(@select,@opt);
Liefere einen leeren Neu-Datensatz, wenn der Datensatz nicht gefunden wird.
Liefere Datensatz in Array-Repräsentation
Default Datensatz-Klasse. Im Falle von -raw=>1 ist 'Quiq::Database::Row::Array' der Default.
Es muss genau ein Datensatz getroffen werden.
Es darf 0 oder 1 Datensatz getroffen werden.
Es muss mindestens ein Datensatz getroffen werden.
Es dürfen beliebig viele Datensätze getroffen werden.
Wird kein Datensatz getroffen und ist dies erlaubt, wird undef geliefert. Wird mehr als ein Datensatz getroffen und ist dies erlaubt, wird der erste geliefert.
$row = $db->loadRow($table,@keyVal);
Lade Datensatz mit WHERE-Bedingung @keyVal. Ist @keyVal leer oder einer der Werte leer, liefere einen Null-Datensatz.
Diese Methode ist nützlich, um ein Formular mit einem neuen oder existierenden Datensatz zu versorgen.
$row = $db->nullRow(@select,@opt);
Liefere Null-Datensatz zu Select-Statement @select und der spezifizierten Klasse.
Anmerkung: Die Row-Instantiierung wird gecacht. Je Statement und Klasse wird beim ersten Aufruf eine Row instantiiert. Bei allen weiteren Aufrufen wird diese Row kopiert.
Null-Datensatz einer Tabelle instantiieren
$per = Quiq::Database::Connection->nullRow('person');
@keyVal|%hash|$arr = $db->values(@select); $hash = $db->values(@select,-hash=>1);
Liefere Hashreferenz.
Selektiere Kolumnenwerte und liefere sie als Liste oder Hash zurück. Im Skalarkontext liefere eine Referenz auf die Liste bzw. den Hash.
Die Select-Liste kann aus ein oder mehreren Kolumnen bestehen. Bei einer Kolumne wird die Liste der Werte der Kolumne geliefert. bei mehreren Kolumnen werden die Werte zu einer flachen Liste vereinigt. Bei zwei, vier, ... Kolumnen, kann das Resultat an einen Hash zugewiesen werden.
Soll die Liste nicht alle, sondern nur verschiedene Werte enthalten, wird DISTINCT selektiert.
DISTINCT
Sollen NULL-Werte nicht berücksichtigt werden, wird der WHERE-Klausel eine entsprechende IS NOT NULL-Bedingung hinzugefügt.
NULL
IS NOT NULL
Sollen die Werte sortiert geliefert werden, wird dem Statement eine ORDER BY Klausel hinzugefügt.
ORDER BY
Im Skalarkontext wird ein Objekt der Klasse Quiq::Array oder der Klasse Quiq::Hash geliefert. Letzteres, wenn Option -hash=>1 angegeben ist.
Quiq::Array
-hash=>1
Alle Werte einer Kolumne (sortiert):
@arr = $db->values( -select => 'per_nachname', -from => 'person', -orderBy => 1, );
Nur verschiedene Werte (sortiert):
@arr = $db->values( -select => 'per_nachname', -distinct => 1, -from => 'person', -orderBy => 1, );
Abbildung von Id auf Nachname:
%hash = $db->values( -select => 'per_id','per_nachname', -from => 'person', );
Dasselbe, nur dass eine Referenz (Hash-Objekt) geliefert wird:
$hash = $db->values( -select => 'per_id','per_nachname', -from => 'person', -hash => 1, );
Lookup-Hash für Nachname:
$hash = $db->values( -select => 'per_nachname',1, -from => 'person', -hash => 1, );
Array mit Paaren:
@arr = $db->values( -select => 'per_id','per_nachname', -from => 'person', );
Dasselbe, nur dass eine Referenz (Array-Objekt) geliefert wird:
$arr = $db->values( -select => 'per_id','per_nachname', -from => 'person', );
Array mit Abfolge von Tripeln:
@arr = $db->values( -select => 'per_id','per_nachname','per_vorname', -from => 'person', );
$val = $db->value(@select,@opt);
Wirf keine Exception, wenn die Ergebnismenge leer ist, sondern undef.
undef
Wenn auf einen Wert ungleich undef gesetzt, wirf keine Exception, wenn die Ergebnismenge leer ist, sondern $val.
Lies den ersten Datensatz der Ergebnismenge und liefere den Wert der ersten Kolumne zurück.
Anmerkungen
Die Select-Liste des Statements sollte sinnvollerweise aus einer Kolumne bestehen. Mehr als eine Kolumne ist zulässig, allerdings ist dies eine Verschwendung von Platz und Zeit, denn auch wenn mehrere Kolumnen angegeben sind, wird nur der Wert der ersten geliefert.
Ist die Ergebnismenge leer, wird eine Exception ausgelöst.
Es ist kein Fehler, wenn mehr als ein Datensatz getroffen wird. Es wird allerdings nur der erste Datensatz geliefert.
$cur = $db->insert($table,@opt,$row); $cur = $db->insert($table,@opt,@keyVal); $cur = $db->insert($table,@opt,\@keys,\@values);
Ignoriere Doubletten-Fehler.
Füge Datensatz zu Tabelle $table hinzu und liefere das Resultat der Ausführung zurück.
$cur = $db->insertRows($table,\@keys, [@vals1], [@vals2], ... ); $cur = $db->insertRows($table,\@keys, @vals1, @vals2, ... );
Füge mehrere Datensätze zu Tabelle $table hinzu. Die Datensätze haben die Kolumnen @keys und die Werte @vals. Die Methode liefert das Resultat der Ausführung (Cursor) zurück
Datensätze als Arrays
$db->insertRows('person', [qw/per_id per_vorname per_nachname per_geburtstag/], [qw/1 Frank Seitz 31.1.1961/], [qw/2 Hanno Seitz 7.4.2000/], [qw/3 Linus Seitz 11.11.2002/], );
Datensätze als Abfolge von Werten
$db->insertRows('person', [qw/per_id per_vorname per_nachname per_geburtstag/], qw/1 Frank Seitz 31.1.1961/, qw/2 Hanno Seitz 7.4.2000/, qw/3 Linus Seitz 11.11.2002/, );
$cur = $db->insertMulti($table,\@keys,[ [@vals1], [@vals2], ... ] );
Füge mehrere Datensätze zu Tabelle $table hinzu. Die Datensätze haben die Kolumnen @keys und die Werte @valsI. Die Methode liefert das Resultat der Ausführung (Cursor) zurück. Im Unterschied zur Methode $db->insertRows() führt diese Methode ein einziges INSERT-Statement mit allen Daten aus, à la
INSERT INTO person (per_id, per_vorname, per_nachname, per_geburtstag) VALUES ('1', 'Linus', 'Seitz', '2002-11-11'), ('2', 'Hanno', 'Seitz', '2000-04-07') ('3', 'Emily', 'Philippi', '1997-05-05') ...
$db->insertMulti('person', [qw/per_id per_vorname per_nachname per_geburtstag/],[ [qw/1 Linus Seitz 2002-11-11/], [qw/2 Hanno Seitz 2000-04-07/], [qw/3 Emily Philippi 1997-05-05/], ] );
$cur = $db->insertResultSet($table,$tab);
$cur = $db->update($table,$row); [1] $cur = $db->update($table,$row,@where); [2] $cur = $db->update($table,@keyVal,-where,@where); # [3]
[1] Aktualisiere Datensatz $row und liefere das Resultat der Ausführung zurück. Als Where-Bedingung wird der Name/Wert der ersten Kolumne von Tabelle $table genommen.
[2] Wie [1], nur dass die Where-Bedingung explizit angegeben ist.
[2] Aktualisiere 0, einen oder mehrere Datensatze in Tabelle $table und liefere das Resultat der Ausführung zurück.
$cur = $db->delete($table,$row,@where); $cur = $db->delete($table,@where);
Lösche Datensatz bzw. Datensätze aus Tabelle $table und liefere das Resultat der Ausführung zurück.
$bool = $db->schemaExists($schema);
Liefere wahr, wenn Schema $schema existiert, sonst falsch.
@schemas | $schemaA = $db->schemas(@opt); %schemas | $schemaH = $db->schemas(-hash=>1,@opt);
Cache die Liste.
Liefere einen Hash mit den Schemanamen als Schlüssel und 1 als Wert.
Liste der Schemanamen (Liste von Strings) oder eine Referenz auf die Liste.
Hash der Schemanamen oder eine Referenz auf den Hash. Der Hashwert ist 1.
Ermittele die Schemata der Datenbank und liefere die Liste oder den Hash der Namen zurück.
$cur = $db->createTable($table, [$colName,@colOpts], ... @opt, );
Erzeuge Tabelle neu, falls sie bereits existiert.
Erzeuge Tabelle nicht, falls sie bereits existiert.
Erzeuge Tabelle $table auf der Datenbank.
$cur = $db->recreateTable($table, [$colName,@colOpts], ... @opt, );
(String) Name der Tabelle, die neu erzeugt wird.
Abbildung zwischen den Kolumnennamen der alten und der neuen Tabelle. Der Schlüssel des Hash ist der alte Name, der Wert des Hash der neue Name. Es müssen nur die Kolumennamen angegeben werden, die nicht übereinstimmen.
(Object) Cursor des INSERT-Statements, das die Daten von der alten in die neue Tabelle kopiert hat.
Erzeuge die auf der Datenbank bereits existierende Tabelle $table neu.
Ablauf:
Erzeuge die Tabelle $table unter dem Namen <TABLE>_new
Kopiere die Daten aus der originalen in die neue Tabelle (unter Berücksichtigung geänderter Kolumnennamen, siehe Option -mapColumns. Kolumen, nicht mehr existieren, entfallen.)
-mapColumns
Lösche die Orignaltabelle
Benenne die neue Tabelle in die Originaltabelle $table um
$n = $destDb->copyData($srcDb,$table,%options);
Verbindung zur Quelldatenbank
(String) Name der Zieltabelle
Kopiere die Datensätze in Chunks der Größe $n.
Name der Tabelle in der Quelldatenbank, wenn er vom Namen der Zieltabelle abweicht.
Abbildung zwischen den Kolumnennamen der Quell- und der Zieltabelle. Der Schlüssel des Hash ist der Name in der Quelltabelle, der Wert des Hash der Name in der Zieltabelle. Es müssen nur die Kolumennamen angegeben werden, die nicht übereinstimmen.
(Integer) Anzahl der kopierten Datensätze.
Kopiere die Daten der Tabelle $table aus der Quelldatenbank $srcDb in die Zieldatenbank $destDb. Weicht der Tabellenname ab, kann diese Abweichung mit der Option -srcTable behandelt werden. Weichen Kolumnennamen ab, kann dies mit der Option -mapColumns behandelt werden.
$cur = $db->dropTable($table);
Lösche die Tabelle $table (name mit oder ohne Schemaanteil) von der Datenbank $db und liefere das Resultat-Objekt der Statementausführung zurück.
Es wird vorab geprüft, ob die Tabelle existiert. Ist dies nicht der Fall, wird keine Löschung versucht und ein Null-Cursor zurückgeliefert.
Wird die Tabelle erfolgreich gedroppt, führt die Methode ein COMMIT durch. Schlägt dies fehl, führt sie ein ROLLBACK durch. Dies ist für PostgreSQL und SQLite notwendig.
$bool = $db->tableExists($table);
Prüfe, ob Tabelle $table existiert. Wenn ja, liefere "wahr", sonst "falsch".
$cur = $sql->renameTable($oldName,$newName);
$db->analyzeTable($table);
Analysiere Tabelle $table und liefere einen Cursor zurück.
$cur = $db->addCheckConstraint($tableName,$expr,@opt);
Siehe Quiq::Sql::addCheckConstraint()
$cur = $db->addForeignKeyConstraint($tableName,\@tableCols, $refTableName,@opt);
Siehe Quiq::Sql::addForeignKeyConstraint()
$n = $db->countRows($tableName);
$tab = $db->tableDiff($table1,$table2,@opt);
Tabellenname, mit oder ohne Schema-Präfix.
Im folgenden ist @titles ein Array von Kolumnennamen und $titles eine kommaseparierte Liste von Kolumnennamen.
Kolumnen, die verglichen werden.
Kolumnen, die ignoriert werden. Diese Option ist nützlich, wenn alle Kolumnen verglichen werden sollen, bis auf die mit dieser Option genannten.
Begrenze die Größe der beiden Differenzmengen (s.u.) auf jeweils N Zeilen. D.h. es werden maximal 2 * N Zeilen geliefert. Darüber hinausgehende Differenzen werden nicht berücksichtigt. Limit 0 bedeutet, es gibt keine Begrenzung.
Kolumnen, nach denen die Gesamt-Differenzliste sortiert wird.
Die Methode untersucht zwei strukturell identische Tabellen hinsichtlich etwaig vorhandener Daten-Differenzen. Sie tut dies mittels SQL und kann dadurch auch große Datenmengen bewältigen. Der Vergleich geschieht durch Bildung zweier Differenzmengen:
-- Alle Zeilen in Tabelle 1, die nicht in Tabelle 2 vorkommen SELECT <COLUMNS1> FROM <TABLE1> EXCEPT SELECT <COLUMNS2> FROM <TABLE2> ORDER BY <COLUMNS1>
und
-- Alle Zeilen in Tabelle 2, die nicht in Tabelle 1 vorkommen SELECT <COLUMNS2> FROM <TABLE2> EXCEPT SELECT <COLUMNS1> FROM <TABLE1> ORDER BY <COLUMNS2>
Sind beide Differenzmengen leer, sind die Tabellen identisch.
Die beiden Differenzmengen werden in einer Ergebnismenge zusammengefasst und als ResultSet-Objekt zurückgeliefert. Die Herkunft einer Row wird durch das Zeilenattribut sourceTable angezeigt. Tabelle 1 wird mit 'A' bezeichnet, Tabelle 2 mit 'B'.
Vergleich der Tabelle q68t999 in den Schemata xv882js und xv882js_test_01 über das Programm quiq-db-table-diff, das ein Frontend zur Methode tableDiff() darstellt:
$ quiq-db-table-diff dbi#postgresql:dsstest%xv882js:*@tdca.ruv.de:5432 xv882js.q68t999 xv882js_test_01.q68t999 1 sourceTable 2 pgmname 3 tabname 4 jobname 5 anz_ins 6 anz_upd 7 anz_del 8 upd_dat 9 status 10 runtime 1 2 3 4 5 6 7 8 9 10 | A | xv882js_160538 | q68t340 | | 37806420 | 0 | -1 | 2019-04-25 09:30:12.034297 | | 2019-04-25 09:29:51 | | B | xv882js_2285224 | q68t340 | | 37806420 | 0 | -1 | 2019-04-25 09:33:33.987502 | | 2019-04-25 09:33:11 | 2 rows
$tab = $db->doublets($table,@opt);
Kolumnen, die auf Dubletten hin untersucht werden.
Kolumnen, die ignoriert werden. Diese Option ist nützlich, wenn alle Kolumnen betrachtet werden sollen, bis auf die mit dieser Option genannten.
Begrenze die Anzahl der gemeldeten Dubletten.
Ergebnismengen-Objekt (Quiq::ResultSet::Object)
Suche Dubletten in der Tabelle $table und liefere ein Ergebnisobjekt mit den Treffern zurück.
$ perl -MQuiq::Database::Connection -E 'print Quiq::Database::Connection\ ->new("dbi#postgresql:dsstest%xv882js:*\@tdca.ruv.de:5432")\ ->doublets("dss_meta.cpm_load_objects",-columns=>"load_object,\ target_object",-limit=>10)->asTable'
$cur = $db->columnExists($table,$column);
Prüfe, ob Kolumne existiert. Wenn ja, liefere "wahr", sonst "falsch".
$cur = $db->addColumn($table,$column,@colDef,@opt);
Wirf keine Exception, wenn die Kolumne bereits existiert, sondern liefere undef.
$cur = $db->addColumn('person','mag_eis', type => 'STRING(1)', notNull => 1, default => 1, );
$cur = $db->dropColumn($table,$column);
Entferne Kolumne $column aus Tabelle $table und liefere das Resultat der Statement-Ausführung zurück.
Es ist kein Fehler, wenn die Kolumne nicht existiert. In dem Fall wird undef geliefert.
$cur = $db->modifyColumn($table,$column,$property=>$value);
Modifiziere Kolumne $column in Tabelle $table und liefere das Resultat der Statement-Ausführung zurück.
$cur = $db->renameColumn($table,$oldName,$newName;
Benenne Tabelle $table die Kolumne $oldName in $newName um und liefere das Resultat der Statement-Ausführung zurück.
$n = $db->distinctValues($table,$column);
$val = $db->minValue($table,$column);
$val = $db->maxValue($table,$column);
($count,$distinctCount,$min,$max) = $db->countDistinctMinMax($table,$column);
Die Methode liefert Information über den Inhalt einer Tabellenkolumne. Sie ist für das Reverse Engineering einer unbekannte Datenbanktabelle nützlich.
$bool = $db->indexExists($table,\@colNames);
Prüfe, ob Index existiert. Wenn ja, liefere "wahr", sonst "falsch".
$cur = $db->createIndex($table,\@colNames,@opt);
Name des Index.
Erzeuge Index neu, falls er bereits existiert.
Name des Tablespace, in dem der Index erzeugt wird (Oracle und PostgreSQL).
Statement für Unique Index.
Erzeuge Index für Tabelle $table und Kolumnen @colNames auf der Datenbank.
$cur = $db->createUniqueIndex($table,\@colNames,@opt);
Siehe $db->createIndex()
Erzeuge Unique Index für Tabelle $table und Kolumnen @colNames auf der Datenbank.
$cur = $db->dropIndex($table,\@colNames);
$db->createSequence($name,@opt);
Droppe Sequenz, falls sie bereits existiert.
Die Sequenz beginnt mit Startwert $n.
Erzeuge Sequenz $name auf Datenbank $db. Die Methode liefert keinen Wert zurück.
Unter Oracle und PostgreSQL, die das Konzept der Sequenz haben, wird eine normale Sequenz auf der Datenbank erzeugt.
Unter MySQL und SQLite, die das Konzept der Sequenz nicht haben, wird eine Tabelle mit Autoinkrement-Kolumne zur Simulation einer Sequenz erzeugt.
$cur = $db->dropSequence($name);
Droppe Sequenz $name und liefere das Resultat der Statementausführung zurück.
$db->setSequence($sequence,$n);
Setze Sequenz $sequence auf Wert $n. Die Methode liefert keinen Wert zurück.
$n = $db->nextValue($sequence);
Ermittele den nächsten Sequenzwert der Sequenz $sequence und liefere diesen zurück.
Unter Oracle und PostgreSQL wird die betreffende Sequenz befragt.
Unter MySQL und SQLite wird ein leerer Datensatz in die Sequenz-Tabelle eingefügt und dessen automatisch generierter Primärschlüsselwert ermittelt. Um die Sequenz-Tabelle nicht beliebig anwachsen zu lassen, wird die Tabelle alle 100 Werte (d.h. wenn $n % 100 == 0) bereinigt: alle Datensätze mit einem kleineren Wert als $n werden gelöscht.
$cur = $db->createView($viewName,$selectStmt,@opt);
Erzeuge View neu, falls sie bereits existiert.
$cur = $db->dropView($viewName);
Lösche die View $viewName von der Datenbank $db und liefere das Resultat-Objekt der Statementausführung zurück.
Es wird vorab geprüft, ob die View existiert. Ist dies nicht der Fall, wird nicht zu löschen versucht und ein Null-Cursor zurückgeliefert.
Wird die View erfolgreich gedroppt, führt die Methode ein COMMIT durch. Schlägt dies fehl, führt sie ein ROLLBACK durch. Dies ist für PostgreSQL und SQLite notwendig.
$bool = $db->viewExists($viewName);
Prüfe, ob View existiert. Wenn ja, liefere "wahr", sonst "falsch".
$cur = $db->createTrigger($table,$name,$when,$event,$level,$body,@opt); $cur = $db->createTrigger($table,$name,$when,$event,$level, $dbms => $body, ..., @opt );
Ersetze den Trigger, falls ein solcher existiert.
Cursor
Erzeuge einen Trigger mit Name $name für Tabelle $table und Zeitpunkt $when (BEFORE oder AFTER), der bei Ereignis $event (INSERT, UPDATE oder DELETE) auf Ebene $level (ROW oder STATEMENT) feuert und die Rumpf/Anweisungsfolge $body ausführt.
Es kann ein einzelner Rumpf angegeben werden, wenn die Applikation auf einem bestimmten RDBMS läuft. Oder es können, um portabel programmieren zu können, unterschiedliche Prozedur-Rümpfe für verschiedene RDBMSe definiert werden:
... Oracle => " <oracle_body> ", PostgreSQL => " <postgresql_body> ", ...
Die Methode wählt dann die zur Datenbank $db passende Rumpf-Definition aus.
Erzeuge unterschiedlichen Triggercode für Oracle und PostgreSQL:
$db->createTrigger('mytab','mytrig','before','insert|update','row', Oracle => " BEGIN :new.c := 'a'; END ", PostgreSQL => " BEGIN NEW.c = 'a'; RETURN NEW; END; ", );
Für Oracle wird ein Trigger mit Rumpf erzeugt:
CREATE TRIGGER mytrig BEFORE INSERT OR UPDATE ON mytab FOR EACH ROW BEGIN :new.c := 'a'; END;
Für PostgreSQL wird zunächst eine Funktion set_c_proc (Triggername plus "_proc") erzeugt, welche die Triggerfunktionalität implementiert:
set_c_proc
CREATE FUNCTION mytrig_proc() RETURNS trigger AS $SQL$ BEGIN NEW.c = 'a'; RETURN NEW; END; $SQL$ LANGUAGE plpgsql
Dann wird der Trigger definiert, der diese Funktion aufruft:
CREATE TRIGGER set_c BEFORE INSERT OR UPDATE ON mytab FOR EACH ROW EXECUTE PROCEDURE mytrig_proc()
$cur = $db->dropTrigger($name);
$bool = $db->triggerExists($name);
$tab|@rows|$cur = $db->diff(@args);
Wie $db->select()
$db->updateNToM($masterId,\@values1,\@values2, a => $a, b => $b, b_pk => $b_pk, b_col => $b_col, a_b => $a_b, a_b_fk_a => $a_b_fk_a, a_b_fk_b => $a_b_fk_b, );
Primärschlüssel-Wert des Master-Datensatzes.
Liste der dem Master-Datensatz zugeordneten B-Werte vor der Änderung.
Dito. nach der Änderung.
Name der Master-Tabelle.
Name der Slave-Tabelle.
Name der Primärschlüsselkolumne der Slave-Tabelle.
Name der Wert-Kolumne der Slave-Tabelle.
Name der Relations-Tabelle.
Name der Fremdschlüsselkolumne in der Relationstabelle auf die Master-Tabelle.
Name der Fremdschlüsselkolumne in der Relationstabelle auf die Slave-Tabelle.
Folgendes Datenmodell:
A <-- A_B --> B
Beispiel: A = Tabelle mit Texten, B = Tabelle mit Schlagworten, A_B = Relationstabelle für die Zuordnung von Schlagworten zu Texten.
Die Methode sorgt dafür, daß für einen Datensatz in A mit der Id $masterId eine Änderung der Schlagwortliste von @values1 nach @values2 die Relationsdatensätze in A_B gemäß dieser Änderung aktualisiert werden. Neue Schlagworte in @values2 werden zu B hinzugefügt, Schlagworte, die wegfallen und nicht von anderen Texten referenziert werden, werden entfernt.
Siehe KnowledgeBase::System->edit()
Im Zuge der Ausführung eines SQL-Statement werden drei Zeiten ermittelt:
Der Startzeitpunkt der Ausführung (Aufruf von sql)
Die Dauer der Statementausführung
Die Zeit, die seit Start des Statements vergangen ist
Diese Zeiten können vom Cursor abgefragt werden mittels:
$cur->startTime; $cur->execTime; $cur->time;
Eine parallele Verbindung zur gleichen Datenbank unter dem gleichen User kann mittels
$db2 = $db->new;
aufgebaut werden. Dies kann nützlich sein, um einen nebenläufigen Transkationsrahmen zu eröffnen.
Wird ein Cursor benötigt, ohne dass ein Statement ausgeführt werden soll, kann ein Null-Cursor erzeugt werden:
$cur = $db->sql;
Die Methode sql() liefert das SQL-Objekt der Datenbankverbindung. Dies ist ein Objekt der Klasse Quiq::Sql, das beim Verbindungsaufbau passend zum DBMS instantiiert wurde.
Alle SQL-Generierungsmethoden der Klasse Quiq::Sql können über diese Methode aufgerufen werden, zum Beispiel:
$stmt = $db->stmt->createTable('person', ['per_id',type=>'INTEGER',primaryKey=>1], ['per_vorname',type=>'STRING(20)'], ['per_nachname',type=>'STRING(20)'], );
Die meisten Statements der Klasse Quiq::Sql können auch direkt ausgeführt werden, ohne dass das Statement zuvor generiert werden muss, zum Beispiel:
$db->createTable('person', ['per_id',type=>'INTEGER',primaryKey=>1], ['per_vorname',type=>'STRING(20)'], ['per_nachname',type=>'STRING(20)'], );
Die direkte Ausführung ist einer getrennten Generierung und Ausführung vorzuziehen, da die Quiq::Database::Connection-Methoden bei der Ausführung teilweise DBMS-abhängige Sonderbehandlungen vornehmen.
Anstelle der Default Sql-Klasse Quiq::Sql kann beim Verbindungsaufbau eine anwendungspezifische Klasse vereinbart werden:
package MyApp::Sql; use base qw/Quiq::Sql/; ... package main; $db = Quiq::Database::Connection->new(...,-sqlClass=>'MyApp::Sql');
DML-Statements (SELECT, INSERT, UPDATE, DELETE) können mit Platzhaltern versehen werden. Das Statement wird dann nicht ausgeführt, sondern ein Bind-Cursor geliefert.
my $bindCur = $db->insert('person', per_id => \'?', per_vorname => \'?', per_nachname => \'?', ); $bindCur->bind( 1,'Rudi','Ratlos', 2,'Elli','Pirelli', 3,'Erika','Mustermann', );
my $bindCur = $db->select( -from => 'person', -where => 'per_nachname = ?', ); my $cur = $bindCur->bind('Mustermann'); while (my $row = $cur->fetch) { print $row->asString,"\n"; } $cur->close;
$row = $db->lookup('person',-where,per_id=>4711);
Es ist ein Fehler, wenn
kein Datensatz existiert
mehr als ein Datensatz existiert
Soll die Methode undef liefern, wenn kein Datensatz existiert, wird -sloppy=>1 angegeben:
$row = $db->lookup('person',-sloppy=>1,-where,per_id=>4711);
Soll ein leerer Datensatz geliefert werden, der gesuchte Datensatz nicht gefunden wird, wird -new=>1 angegeben:
$row = $db->lookup('person',-new=>1,-where,per_id=>4711);
Der Aufruf liefert also immer einen Datensatz. Mit der Methode rowStatus() kann geprüft werden, ob der Datensatz selektiert oder neu erzeugt wurde:
if ($row->rowStatus eq 'I') { # initialisieren $row->set( per_id => $db->nextValue('id'); per_vorname => 'Erika', per_namchname => 'Mustermann', ); # speichern $db->insert('person',$row); }
my $per_id = $db->nextValue('id'); $db->insert('person', per_id => $per_id, per_vorname => 'Rudi', per_nachname => 'Ratlos', ); my $per = $db->lookup('person',-where,per_id=>$per_id);
Der Datensatz wird durch Aufzählung der Kolumnen/Wert-Paare zur Tabelle hinzugefügt. Um das Objekt im Programm zu haben, muss der Datensatz selektiert werden.
my $per = $db->nullRow('person'); $per->set( per_id => $db->nextValue('id'), per_vorname => 'Rudi', per_nachname => 'Ratlos', ); $db->insert('person',$row);
my $per = Person->new($db, per_id => $db->nextValue('id'), per_vorname => 'Rudi', per_nachname => 'Ratlos', ); $per->insert($db);
Per UDL kann ein Default-Schema definiert werden:
dbi#DBMS:DB%USER:PASSW;schema=SCHEMA
Namen von Datenbank-Objekten, die ohne Schema-Präfix angegeben werden, werden auf dieses Schema bezogen. Auf diese Weise ist es leicht möglich, eine Anwendung auf verschiedenen Schemata der gleichen Datenbank laufen zu lassen. Dies ist vor allem bei Oracle nützlich, dessen Instanzen einen großen Overhead haben.
Bei SQLite ist die Semantik eine leicht andere: Hier ist es nicht das Default-Schema, sondern es darf der Schema-Präfix SCHEMA verwendet werden.
Die maximale Größe eines BLOB/TEXT-Werts muss im Falle von Oracle eingestellt werden. Dies geschieht durch Aufruf von maxBlobSize():
$db->maxBlobSize(500*1024); # 0,5 MB
Der Defaultwert ist 1024*1024 Bytes (1MB).
$db->createTable('person', ['per_id',type=>'INTEGER',primaryKey=>1], ['per_vorname',type=>'STRING(20)'], ['per_nachname',type=>'STRING(20)'], ['per_foto',type=>'BLOB'], );
$cur = $db->insert('person', per_id => \'?', per_vorname => \'?', per_nachname => \'?', per_foto => \'?', ); # BLOB-Kolumne bekannt machen, damit die Schnittstelle # die notwendigen Sonderbehandlungen für diesen Datentyp # durchführen kann. Dies ist im Falle von Oracle und PostgreSQL # nötig, da diese die Daten speziell kodieren. Bei SQLite und MySQL # ist das nicht erforderlich. Der Aufruf von bindTypes() sollte aus # Portabilitätsgründen aber immer gemacht werden. $cur->bindTypes(undef,undef,undef,'BLOB'); my $foto = Quiq::Path->read('/home/pirelli/Picture/elli.jpg'); $cur->bind(1,'Elli','Pirelli',$foto);
$per = $db->lookup('person',-where,per_id=>1);
Wie BLOB-Datentyp, aber als Bind-Typ TXET angeben:
$cur->bindTypes(undef,undef,undef,'TEXT');
Auch hier ist dies wegen Oracle erforderlich.
Beim Verbindungsaufbau kann angegeben werden, ob das Perl-Programm UTF-8 Encoding verwendet:
$db = Quiq::Database::Connection->new($udl,-utf8=>1);
Die Option sorgt dafür, dass Zeichenketten-Daten (STRING, TEXT) als UTF-8 Zeichenketten auf der Datenbank gespeichert werden und umgekehrt als UTF-8 Zeichenketten geliefert werden.
Existiert eine Lowlevel-Handle bereits, kann sie mit der Option -handle in das Datenbankobjekt eingesetzt werden.
Beispiel: Eine DBI MySQL-Handle $dbh wird als Lowlevel-Handle verwendet,
UDL braucht nur die $db = Quiq::Database::Connection->new('dbi#mysql',-handle=>$dbh);
Unter Unix/Linux ist ein lesender Zugriff auf MS Access Datenbanken mittels des freien Open Source Package mtools möglich. Es enthält neben verschiedenen Programme auch einen ODBC-Treiber, der genutzt werden kann, um von Perl aus auf eine Access-Datenbank zuzugreifen.
mtools: http://mdbtools.sourceforge.net/
# yum install mdbtools
unixODBC: http://http://www.unixodbc.org/
# yum install unixODBC
DBD::ODBC: https://metacpan.org/pod/DBD::ODBC
# cpanm DBD::ODBC
ODBC-Treiber (aus den mtools) definieren:
# vi /etc/odbcinst.ini [MDBTools] Description = MDB Tools ODBC Driver = libmdbodbc.so FileUsage = 1
Datenquelle definieren:
# vi /etc/odbc.ini [test] Description = Access Test-Datenbank Driver = MDB Tools ODBC Database = /path/to/file.mdb
Von Perl aus auf die Access-Datenbank zugreifen:
my $udl = 'dbi#access:test'; my $db = Quiq::Database::Connection->new($udl,-utf8=>1); my $stmt = 'select * from tdruckdaten'; my $tab = $db->select($stmt); print $tab->asTable;
1.208
Frank Seitz, http://fseitz.de/
Copyright (C) 2023 Frank Seitz
This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Quiq, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Quiq
CPAN shell
perl -MCPAN -e shell install Quiq
For more information on module installation, please visit the detailed CPAN module installation guide.