Sie finden die Tests in mysql-test/t/*.test.

Ein Testfall besteht aus Anweisungen, die mit ; abgeschlossen werden, und ähnelt der Eingabe für den mysql-Kommandozeilen-Client. Eine Anweisung ist standardmäßig eine SQL-Anweisung, die an den MySQL Server gesandt wird, es sei denn, sie wird als interner Befehl erkannt (wie beispielsweise sleep).

Vor allen Anfragen, die Ergebnisse produzieren, wie beispielsweise SELECT, SHOW oder EXPLAIN, muss ein @/path/to/result/file stehen. Diese Datei muss die erwarteten Ergebnisse enthalten. Ein einfaches Mittel, um die Ergebnisdatei zu generieren, besteht darin, mysqltest -r < t/test-case-name.test im Verzeichnis mysql-test auszuführen und dann die generierten Ergebnisdateien wenn nötig zu bearbeiten, um sie an die erwartete Ausgabe anzupassen. In diesem Fall müssen Sie sehr genau darauf achten, keine unsichtbaren Zeichen zu löschen oder hinzuzufügen. Sie dürfen nur den Text ändern oder Zeilen löschen. Wenn Sie eine Zeile einfügen müssen, achten Sie darauf, dass die Felder durch einen Tabulator getrennt werden, und setzen Sie auch am Ende einen Tabulator. Mit od -c können Sie sich vergewissern, dass Ihr Editor bei der Bearbeitung keinen Unsinn gemacht hat. Wir hoffen, dass Sie niemals die Ausgabe von mysqltest -r bearbeiten müssen, da dies nur nötig wird, wenn Sie einen Fehler finden.

Um Ihr System wie unseres einzurichten, legen Sie die Ergebnisdateien in das Verzeichnis mysql-test/r und nennen sie test_name.result. Wenn der Test mehr als ein Ergebnis produziert, verwenden Sie die Namen test_name.a.result, test_name.b.result und so weiter.

Wenn eine Anweisung einen Fehler zurückgibt, sollten Sie diesen mit --error error-number auf der Zeile vor dieser Anweisung angeben. Die Fehlernummer kann auch eine kommagetrennte Liste von Fehlernummern sein.

Wenn Sie einen Replikationstestfall schreiben, setzen Sie in die erste Zeile der Testdatei den Text source include/master-slave.inc;. Mit connection master; und connection slave; schalten Sie zwischen Master und Slave um. Wenn Sie auf einer anderen Verbindung arbeiten müssen, können Sie für den Master connection master1; und für den Slave connection slave1; eingeben.

Falls Sie eine Schleifenverarbeitung ausführen müssen, können Sie Folgendes tun:

let $1=1000;
while ($1)
{
 # Hier Anfragen einfügen
 dec $1;
}

Mit sleep schläft das System zwischen zwei Anfragen. Da in diesem Befehl auch Sekundenbruchteile eingestellt werden können, bedeutet beispielsweise sleep 1.3;, dass das System 1,3 Sekunden schläft.

Um den Slave mit Zusatzoptionen für den Testfall auszuführen, setzen Sie die Optionen in einem Kommandozeilenformat in die Datei mysql-test/t/test_name-slave.opt bzw. für den Master in die Datei mysql-test/t/test_name-master.opt.

Wenn Sie Fragen zu der Testreihe haben oder selbst einen Test beisteuern möchten, schicken Sie eine E-Mail an die MySQL-Mailingliste internals (siehe Abschnitt 1.7.1, „Die MySQL-Mailinglisten“). Da diese Liste keine Anhänge akzeptiert, laden Sie alle relevanten Dateien per FTP auf folgende Adresse hoch: ftp://ftp.mysql.com/pub/mysql/upload/.

Senden Sie uns bitte erst dann einen Bugreport, wenn Sie so viel wie möglich über das Problem herausgefunden haben! Schauen Sie bitte auch in die Anleitungen unter Abschnitt 1.8, „Wie man Bugs oder Probleme meldet“.

Speichern Sie die Ausgabe von mysql-test-run sowie die Inhalte sämtlicher .reject-Dateien im Verzeichnis mysql-test/r.

Wenn ein Test in der Testreihe fehlschlägt, überprüfen Sie, ob der Test auch dann scheitert, wenn er isoliert ausgeführt wird:

cd mysql-test
mysql-test-run --local test-name

Wenn dies scheitert, sollten Sie MySQL mit der Option --with-debug konfigurieren und mysql-test-run mit der Option --debug ausführen. Wenn auch das fehlschlägt, senden Sie die Trace-Datei var/tmp/master.trace an ftp://ftp.mysql.com/pub/mysql/upload/, damit wir sie untersuchen können. Bitte senden Sie uns außerdem eine vollständige Beschreibung Ihres Systems, die Version Ihrer mysqld-Binary sowie Informationen, wie Sie sie kompiliert haben.

Lassen Sie mysql-test-run mit der --force-Option laufen, um zu erfahren, ob auch ein anderer Test scheitert.

Wenn Sie MySQL selbst kompiliert haben, schlagen Sie in unserem Handbuch nach, wie MySQL auf Ihrer Plattform kompiliert wird, oder – noch besser – verwenden Sie eine der Binaries, die wir für Sie bereits vokompiliert haben (siehe http://dev.mysql.com/downloads/). Alle unsere Standardbinaries dürften die Testreihe überstehen!

Wenn Sie eine Fehlermeldung wie Result length mismatch oder Result content mismatch bekommen, so bedeutet dies, dass die Testausgabe nicht mit der erwarteten Ausgabe übereinstimmt. Dies könnte ein Bug in MySQL sein oder aber daran liegen, dass Ihre mysqld-Version unter bestimmten Umständen abweichende Ergebnisse bringt.

Die Ergebnisse von gescheiterten Tests werden in eine Datei gespeichert, die genau wie die Ergebnisdatei heißt, aber die Erweiterung .reject hat. Wenn Ihr Testfall scheitert, lassen Sie einen Diff-Befehl auf den beiden Dateien laufen. Ist nicht zu erkennen, worin sie sich unterscheiden, so untersuchen Sie beide mit od -c und vergleichen auch ihre Längen.

Scheitert ein Test vollständig, suchen Sie in den Logdateien im Verzeichnis mysql-test/var/log nach Gründen.

Haben Sie MySQL mit Debugging kompiliert, so können Sie versuchen, mysql-test-run mit der Option --gdb und/oder --debug auszuführen. Siehe auch Abschnitt E.1.2, „Trace-Dateien erzeugen“.

Wurde MySQL nicht mit Debugging kompiliert, so sollten Sie dies nun nachholen. Dazu müssen Sie lediglich configure mit den --with-debug-Optionen ausführen. Siehe Abschnitt 2.8, „Installation der Quelldistribution“.

type

Der Plug-In-Typ. Dieser muss einer der Plug-In-Typwerte aus plugin.h sein. Für ein Volltext-Parser-Plug-In ist der type-Wert MYSQL_FTPARSER_PLUGIN.

info

Ein Zeiger auf den Deskriptor für das Plug-In. Anders als die allgemeine Plug-In-Deklarationsstruktur hängt die Struktur dieses Deskriptors von dem konkreten Plug-In-Typ ab. Jeder Deskriptor hat eine Versionsnummer, die auf die API-Version für diesen Plug-In-Typ verweist, sowie andere erforderliche Bestandteile. Der Deskriptor für Volltext-Plug-Ins ist in Abschnitt 26.2.5.2, „Typspezifische Plug-In-Strukturen und -Funktionen“, beschrieben.

name

Der Name des Plug-Ins. Dieser wird in der plugin-Tabelle aufgeführt und in SQL-Anweisungen wie INSTALL PLUGIN und UNINSTALL PLUGIN zur Benennung des Plug-Ins verwendet.

author

Der Autor des Plug-Ins. Kann alles sein, was Sie wollen.

desc

Eine allgemeine Beschreibung des Plug-Ins. Kann alles sein, was Sie wollen.

init

Eine nur einmalig benutzte Initialisierungsfunktion. Diese wird ausgeführt, wenn das Plug-In geladen wird, was bei INSTALL PLUGIN oder für Plug-Ins aus der plugin-Tabelle beim Serverstart geschieht. Diese Funktion hat keine Argumente und gibt bei Erfolg null und bei Misserfolg einen von null verschiedenen Wert zurück.

deinit

Eine nur einmalig benutzte Deinitialisierungsfunktion. Diese wird ausgeführt, wenn das Plug-In entladen wird, was bei UNINSTALL PLUGIN oder für Plug-Ins aus der plugin-Tabelle beim Server-Shutdown geschieht. Diese Funktion hat keine Argumente und gibt bei Erfolg null und bei Misserfolg einen von null verschiedenen Wert zurück

Zum Indizieren ruft der Server den Parser für jeden zu indizierenden Spaltenwert auf.

In Suchoperationen ruft der Server den Parser auf, um den Such-String zu parsen. Ebenso kann der Parser für Zeilen aufgerufen werden, die von der Anweisung verarbeitet werden. Im Modus für natürliche Sprache braucht der Server den Parser nicht aufzurufen. Ini Phrasensuchen im booleschen Modus oder Suchen in natürlicher Sprache mit Abfrageerweiterung (Query Expansion) wird der Parser eingesetzt, um in den Spaltenwerten Informationen zu parsen, die nicht im Index vorliegen. Wenn eine Suche nach einer Spalte mit FULLTEXT-Index im booleschen Modus durchgeführt wird, wird ebenfalls der eingebaute Parser aufgerufen. (Plug-Ins sind mit konkreten Indizes verbunden. Ist kein Index vorhanden, wird auch kein Plug-In verwendet.)

Für die Plug-In-Deklaration im Plug-In-Bibliotheksdeskriptor werden die Initialisierungs- und Deinitialisierungsfunktionen beim Laden und Entladen des Plug-Ins aufgerufen.

Für den Plug-In-Deskriptor werden die Initialisierungs- und Deinitialisierungsfunktionen für jede SQL-Anweisung aufgerufen, in der das Plug-In benutzt wird.

mysql_parse

Ein Zeiger auf eine Callback-Funktion, die den eingebauten Parser des Servers aufruft. Diesen Callback verwenden Sie, wenn das Plug-In als Frontend des eingebauten Parsers fungiert. Wenn also die Plug-In-Parsing-Funktion aufgerufen wird, soll sie die Eingabe verarbeiten, um den Inhalt zu extrahieren, und diesen dann an den mysql_parse-Callback übergeben.

Der erste Parameter dieser Callback-Funktion sollte der mysql_ftparam-Teil der Struktur des Parsing-Kontextes sein. Das heißt: Wenn param auf die Struktur verweist, wird der Callback folgendermaßen aufgerufen:

param->mysql_parse(param->mysql_ftparam, ...);

Ein Frontend-Plug-In kann Text extrahieren und komplett oder häppchenweise an den eingebauten Parser übergeben. Im zweiten Fall behandelt der eingebaute Parser die Textstücke, als befänden sich implizite Wortgrenzen zwischen ihnen.

mysql_add_word

Ein Zeiger auf eine Callback-Funktion, die einem Volltextindex oder der Liste der Suchbegriffe ein Wort hinzufügt. Diesen Callback verwenden Sie, wenn das Parser-Plug-In den eingebauten Parser ersetzen soll. Das bedeutet: Wenn die Parsing-Funktion des Plug-Ins aufgerufen wird, soll sie die Eingabe in Wörter parsen und für jedes Wort den mysql_add_word-Callback aufrufen.

Der erste Parameter dieser Callback-Funktion soll der mysql_ftparam-Teil der Struktur des Parsing-Kontexts sein. Das heißt: Wenn param auf die Struktur verweist, wird der Callback wie folgt aufgerufen:

param->mysql_add_word(param->mysql_ftparam, ...);

ftparser_state

Dies ist ein generischer Zeiger. Das Plug-In kann ihn auf die Informationen verweisen lassen, die es intern für seine eigenen Zwecke benutzt.

mysql_ftparam

Wird durch den Server eingestellt und als erstes Argument an den mysql_parse- oder mysql_add_word-Callback übergeben.

cs

Verweist auf den Zeichensatz für den Text, oder auf 0, wenn diese Information nicht zur Verfügung steht.

doc

Ein Zeiger auf den zu parsenden Text.

length

Die Länge des zu parsenden Texts in Bytes.

mode

Der Parsing-Modus. Dieser Wert ist eine der folgenden Konstanten:

type

Der Token-Typ. Dies sollte einer der Werte der folgenden Tabelle sein:

yesno

Gibt an, ob das Wort vorhanden sein muss, damit eine Übereinstimmung festgestellt wird. 0 bedeutet, dass das Wort optional ist, sein Vorhandensein jedoch die Relevanz der Übereinstimmung erhöht. Werte größer 0 bedeuten, dass das Wort obligatorisch ist, und Werte kleiner 0, dass es nicht vorhanden sein darf.

weight_adjust

Ein Gewichtsfaktor, der festlegt, wie viel eine Übereinstimmung für das Wort zählt. Indem man diesen Faktor herauf- oder heruntersetzt, beeinflusst man die Bedeutung, die dieses Wort in Relevanzberechnungen hat. Ist der Wert null, so erfolgt keine Anpassung der Gewichtung. Werte größer oder kleiner null bedeuten ein höheres oder geringeres Gewicht. Die Beispiele unter Abschnitt 12.7.1, „Boolesche Volltextsuche“, die <- und >-Operatoren verwenden, zeigen, wie Gewichtung funktioniert.

wasign

Das Vorzeichen des Gewichtungsfaktors. Ein negativer Wert verhält sich wie der boolesche Suchoperator ~, der dafür sorgt, dass das Wort in negativer Weise zur Relevanz beiträgt.

trunc

Zeigt an, ob der Abgleich in derselben Weise durchgeführt wird, als ob der Kappungsoperator * im booleschen Modus angegeben worden wäre.

Ein Plug-In-Bibliotheksdeskriptor mit der Versionsnummer der allgemeinen Plug-In-API der Bibliothek und einer allgemeinen Deklaration für jedes Plug-In in der Bibliothek.

Jede allgemeine Plug-In-Deklaration enthält Informationen, die allen Arten von Plug-Ins gemeinsam sind: einen Wert, der den Plug-In-Typ anzeigt, den Namen, den Autor und die Beschreibung des Plug-Ins sowie Zeiger auf die Initialisierungs- und die Deinitialisierungfunktionen, die der Server beim Laden und Entladen des Plug-Ins aufrufen muss.

Außerdem enthält die allgemeine Plug-In-Deklaration einen Zeiger auf einen typspezifischen Plug-In-Deskriptor. Die Struktur dieser Deskriptoren kann je nach Plug-In-Typ unterschiedlich sein, da jede Art von Plug-In ihre eigene API haben kann. Ein Plug-In-Deskriptor enthält eine typspezifische API-Versionsnummer und Zeiger auf die Funktionen, die zur Implementierung dieses Plug-In-Typs erforderlich sind. So hat beispielsweise ein Volltext-Parser-Plug-In Initialisierungs- und Deinitialisierungsfunktionen und eine Parsing-Hauptfunktion. Der Server ruft diese Funktionen auf, wenn er das Plug-In zum Parsen von Text einsetzt.

Die Plug-In-Bibliothek enthält die Schnittstellenfunktionen, auf die der Bibliotheksdeskriptor und die Plug-In-Deskriptoren verweisen.

my_bool maybe_null

xxx_init() sollte maybe_null auf 1 einstellen, wenn xxx() den Wert NULL zurückliefern kann. Der Standardwert ist 1, wenn irgendwelche Argumente als maybe_null deklariert sind.

unsigned int decimals

Die Anzahl der Dezimalstellen rechts vom Dezimalpunkt (also salopp ausgedrückt: die Nachkommastellen). Der Standardwert ist die Höchtzahl der Dezimalstellen in den an die Hauptfunktion übergebenen Argumenten. (Wenn beispielsweise 1.34, 1.345 und 1.3 an die Funktion übergeben werden, wäre der Standardwert 3, da 1.345 3 Nachkommastellen hat.

unsigned int max_length

Die Maximallänge des Ergebnisses. Der Standardwert max_length richtet sich nach dem Ergebnistyp der Funktion. Bei String-Funktionen ist er die Länge des längsten Arguments; bei Integer-Funktionen ist er 21 Ziffern. Bei Real-Funktionen ist der Standardwert 13 plus die Anzahl der durch initid->decimals vorgegebenen Dezimalstellen. (Bei numerischen Funktionen sind in der Länge auch Vorzeichen und Dezimalpunkt inbegriffen.)

Wenn Sie einen Blob-Wert zurückliefern möchten, können Sie max_length auf 65 Kbyte oder 16 Mbyte einstellen. Der Speicherplatz wird zwar nicht reserviert, aber anhand der Länge entscheidet das System, welcher Datentyp für eine eventuell erforderliche temporäre Speicherung der Daten verwendet wird.

char *ptr

Ein Zeiger, den die Funktion für ihre eigenen Zwecke verwenden kann. So können sich die Funktionen beispielsweise mit initid->ptr gegenseitig mitteilen, wie viel Speicher sie reservieren müssen. xxx_init() sollte den Speicher reservieren und diesem Zeiger zuweisen.

initid->ptr = allocated_memory;

In xxx() und xxx_deinit() verweisen Sie auf initid->ptr, um Speicher zu benutzen oder freizugeben.

my_bool const_item

xxx_init() sollte const_item auf 1 setzen, wenn xxx() immer denselben Wert zurückgibt, und auf 0, wenn das nicht der Fall ist.

xxx_reset()

Diese Funktion wird aufgerufen, wenn MySQL die erste Zeile einer neuen Gruppe findet. Sie sollte eventuell vorhandene interne Summenvariablen zurücksetzen und dann das gegebene UDF_ARGS-Argument als ersten Wert des neuen internen Summenwerts für diese Gruppe verwenden. xxx_reset() wird folgendermaßen deklariert:

char *xxx_reset(UDF_INIT *initid, UDF_ARGS *args,
                char *is_null, char *error);

xxx_reset() wird in MySQL 5.1 weder benötigt noch benutzt. Die UDF-Schnittstelle verwendet stattdessen xxx_clear(). Sie können jedoch xxx_reset() zusätzlich zu xxx_clear() definieren, wenn Ihre UDF auch mit älteren Serverversionen laufen soll. (Wenn Sie beide Funktionen einbeziehen möchten, können Sie xxx_reset() intern oft implementieren, indem Sie zunächst xxx_clear() alle Variablen zurücksetzen lassen und dann xxx_add() aufrufen, um das Argument UDF_ARGS als ersten Wert der Gruppe hinzuzufügen.)

xxx_clear()

Diese Funktion wird aufgerufen, wenn MySQL die Summenergebnisse zurücksetzen muss. Sie wird für jede neue Gruppe ganz am Anfang aufgerufen, kann aber auch verwendet werden, um die Werte für eine Anfrage zurückzusetzen, wenn keine übereinstimmenden Zeilen gefunden wurden. xxx_clear() wird folgendermaßen deklariert:

char *xxx_clear(UDF_INIT *initid, char *is_null, char *error);

is_null wird auf CHAR(0) eingestellt, bevor xxx_clear() aufgerufen wird.

Wenn etwas schief gegangen ist, können Sie einen Wert in der Variablen speichern, auf die das Argument error verweist. error zeigt auf eine Singlebyte-Variable, nicht auf einen String-Puffer.

xxx_clear() ist für MySQL 5.1 obligatorisch.

xxx_add()

Diese Funktion wird für alle Zeilen außer der ersten aufgerufen, die zu derselben Gruppe gehören. Mit ihr addieren Sie den Wert des Arguments UDF_ARGS zu Ihrer internen Summenvariablen.

char *xxx_add(UDF_INIT *initid, UDF_ARGS *args,
              char *is_null, char *error);

unsigned int arg_count

Die Anzahl der Argumente. Diesen Wert muss die Initialisierungsfunktion prüfen, wenn Ihre Funktion mit einer bestimmten Anzahl von Argumenten aufgerufen werden muss. Zum Beispiel:

if (args->arg_count != 2)
{
    strcpy(message,"XXX() requires two arguments");
    return 1;
}

enum Item_result *arg_type

Ein Zeiger auf ein Array, das die Argumenttypen enthält. Mögliche Typwerte sind STRING_RESULT, INT_RESULT und REAL_RESULT.

Um sicherzustellen, dass die Argumente einen bestimmten Typ haben, und um einen Fehler auszulösen, wenn der Typ nicht stimmt, muss die Initialisierungsfunktion das Array arg_type betrachten. Zum Beispiel:

if (args->arg_type[0] != STRING_RESULT ||
    args->arg_type[1] != INT_RESULT)
{
    strcpy(message,"XXX() requires a string and an integer");
    return 1;
}

Anstatt zu verlangen, dass die Funktionsargumente bestimmte Typen haben, können Sie auch mit der Initialisierungsfunktion die arg_type-Elemente auf die gewünschten Typen einstellen. Dies veranlasst MySQL, den Argumenten bei jedem Aufruf von xxx() die richtigen Typen aufzuzwingen. Um beispielsweise aus dem ersten Argument einen String und aus dem zweiten einen Integer zu machen, muss Ihre xxx_init()-Funktion Folgendes tun:

args->arg_type[0] = STRING_RESULT;
args->arg_type[1] = INT_RESULT;

char **args

args->args informiert die Initialisierungsfunktion über das Wesen der an Ihre Funktion übergebenen Argumente. Bei einem Konstantenargument i verweist args->args[i] auf den Argumentwert. (Wie Sie richtig auf diesen Wert zugreifen, erfahren Sie weiter unten.) Bei einem Nichtkonstantenargument ist args->args[i] gleich 0. Ein Konstantenargument ist ein Ausdruck, der nur Konstanten verwendet, wie beispielsweise 3 oder 4*7-2 oder SIN(3.14). Ein Nichtkonstantenargument ist ein Ausdruck, der auf Werte verweist, die sich von Zeile zu Zeile ändern können, wie etwa Spaltennamen oder Funktionen, die mit Nichtkonstantenargumenten aufgerufen werden.

Für jeden Aufruf der Hauptfunktion enthält args->args die Argumente, die tatsächlich an die in Bearbeitung befindliche Zeile übergeben werden.

Funktionen können folgendermaßen auf ein Argument i verweisen:

unsigned long *lengths

Für die Initialisierungsfunktion zeigt das Array lengths die maximale String-Länge für jedes Argument an. Diese sollten Sie nicht ändern. Für jeden Aufruf der Hauptfunktion enthält lengths die tatsächlichen Längen der String-Argumente, die an die in Bearbeitung befindliche Zeile übergeben werden. Für Argumente der Typen INT_RESULT oder REAL_RESULT enthält lengths immer noch die maximale Länge des Arguments (wie für die Initialisierungsfunktion).

Die Funktion metaphon() gibt einen Metaphon-String aus dem String-Argument zurück. Dieser ist so etwas wie ein Soundex-String, allerdings besser auf die englische Sprache zugeschnitten.

Die Funktion myfunc_double() gibt die Summe der ASCII-Werte der in ihren Argumenten enthaltenen Zeichen geteilt durch die Summe der Längen dieser Argumente zurück.

Die Funktion myfunc_int() gibt die Summe der Längen ihrer Argumente zurück.

Die Funktion sequence([const int]) gibt eine Sequenz zurück, die ab der gegebenen Zahl oder, wenn keine gegeben wurde, ab 1 beginnt.

Die Funktion lookup() gibt die IP-Nummer eines Hostnamens zurück.

Die Funktion reverse_lookup() gibt den Hostnamen zu einer IP-Nummer zurück. Diese Funktion kann entweder mit einem einzigen String-Argument der Form 'xxx.xxx.xxx.xxx' oder mit vier Zahlen aufgerufen werden.