tarantool: Bibliothek zur Arbeit mit Tarantool von NGINX mit dem eingebetteten Lua-Modul oder mit nginx-module-lua
Installation
Wenn Sie das RPM-Repository-Abonnement noch nicht eingerichtet haben, melden Sie sich an. Danach können Sie mit den folgenden Schritten fortfahren.
CentOS/RHEL 7 oder Amazon Linux 2
yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install lua-resty-tarantool
CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install lua5.1-resty-tarantool
Um diese Lua-Bibliothek mit NGINX zu verwenden, stellen Sie sicher, dass nginx-module-lua installiert ist.
Dieses Dokument beschreibt lua-resty-tarantool v0.3, das am 21. Oktober 2015 veröffentlicht wurde.
Einführung
Dies ist eine Bibliothek zur Verbindung mit der tarantool NoSQL-Datenbank. Diese Datenbank hat sehr interessante Funktionen, die sie zu einer Art Brücke zwischen einer traditionellen SQL-basierten Datenbank und dokumentenorientierten Speichern wie CouchDB machen.
Es ist ein Fork eines anderen Projekts, mit dem ich unzufrieden war. Es ist reichlich dokumentiert und wird bezüglich der Tarantool-API aktualisiert. Besonders hervorzuheben ist die Unterstützung des upsert Befehls.
Ein weiterer Punkt, den man im Hinterkopf behalten sollte, ist, dass die Bibliothek versucht, konsistent zu sein zwischen der Art und Weise, wie die update und upsert Befehle in der Konsole unter Verwendung von Lua ausgegeben werden, und der Funktionsweise der API. Besonders die Feldnummern. In der Konsole berücksichtigt eine Feldnummer das Vorhandensein eines Primärindex als erstes Feld. Daher hat jedes Feld, das danach kommt, eine Position, die dies berücksichtigt. Insbesondere beim Festlegen der Operatoren, die für die update oder upsert Operationen verwendet werden.
Verwendung
Erstellen einer Verbindung
local tar = require 'resty.tarantool'
local tar, err = tnt:new({
host = '127.0.0.1',
port = 3301,
user = 'luser',
password = 'some password',
socket_timeout = 2000,
})
luser mit dem Passwort some password. Siehe das Tarantool-Handbuch zur Authentifizierung für Details zur Einrichtung von Benutzern und zur Zuweisung von Berechtigungen.
Der Socket-Timeout (Empfang und Sendung) beträgt 2 Sekunden (2000 ms).
set_timeout
settimeout(<Verbindungsobjekt>, <Timeout in ms>)
Setzt sowohl die Sende- als auch die Empfangs-Timeouts in Millisekunden für einen bestimmten Socket.
tnt:set_timeout(5000) -- 5s Timeout für Sende-/Empfangsoperationen
Die Funktion gibt true zurück, wenn die Einstellung erfolgreich ist, nil, wenn nicht. Beachten Sie, dass diese Funktion vor dem Herstellen der Verbindung, d.h. vor dem Aufruf der connect Funktion, aufgerufen werden muss, damit der Timeout wirksam wird. Alternativ kann der Timeout auch beim Erstellen des Verbindungsobjekts (Cosocket) angegeben werden.
connect
connect(<Verbindungsobjekt>)
Stellt die oben erstellte Socket-Verbindung zu dem beim Erstellen des Verbindungsobjekts angegebenen Port und der Adresse her.
tar:connect()
nil, wenn nicht.
set_keepalive
set_keepalive(<Verbindungsobjekt>)
Lässt die erstellte Verbindung in einen Verbindungs-Pool verschieben, sodass die Verbindung über mehrere Anfragen hinweg aktiv bleibt.
tar:set_keepalive()
Die Funktion gibt true zurück, wenn der Socket erfolgreich in den Verbindungs-Pool verschoben wurde (set keepalive). nil, wenn nicht.
disconnect
disconnect(<Verbindungsobjekt>)
Schließt eine Verbindung zu einem bestimmten Tarantool-Server, der an einer bestimmten Adresse und einem bestimmten Port läuft.
tar:disconnect()
Die Funktion gibt true zurück, wenn die Verbindung erfolgreich geschlossen wurde. nil, wenn nicht.
ping
Der Ping-Befehl ist nützlich, um den Tarantool-Server zu überwachen, um zu sehen, ob er verfügbar ist. Wenn er für Abfragen verfügbar ist, gibt er den String PONG zurück.
tar:ping()
-- gibt PONG zurück
select
Die Select-Operation fragt eine bestimmte Datenbank (Space) ab, um Datensätze abzurufen.
select(<Verbindungsobjekt>, <Space-Name>, <Index>, <Key>, <Optionen>)
wobei <Optionen> ein optionales Argument ist, das aus einer Tabelle bestehen kann, die die folgenden Schlüssel haben kann:
offset: Anzahl der Datensätze, die bei der Abfrage übersprungen werden sollen.limit: die maximale Anzahl von Datensätzen, die zurückgegeben werden sollen.iterator: eine Zahl, die den zu verwendenden Iterator angibt. Festgelegt durch die Tabelle:
local iterator_keys = {
EQ = 0, -- Gleichheit
REQ = 1, -- umgekehrte Gleichheit
ALL = 2, -- alle Tupel in einem Index
LT = 3, -- kleiner als
LE = 4, -- kleiner oder gleich
GE = 5, -- größer oder gleich
GT = 6, -- größer als
BITSET_ALL_SET = 7, -- Bits in der Bitmaske sind alle gesetzt
BITSET_ANY_SET = 8, -- eines der Bits in der Bitmaske ist gesetzt
BITSET_ALL_NOT_SET = 9, -- keines der Bits in der Bitmaske ist gesetzt
}
select Beispiele
Abfrage des _space Space (DB), um die Space-ID des _index Space zu erhalten.
local res, err = tar:select('_space', 'name', '_index')
-- Antwort:
[2881,"_index","memtx",0,"",
[{"name":"id","type":"num"},
{"name":"iid","type":"num"},
{"name":"name","type":"str"},
{"name":"type","type":"str"},
{"name":"opts","type":"array"},
{"name":"parts","type":"array"}]]]
box.space._space.index.name:select{ '_index' }
Abfrage des Space 'activities' nach Aktivitäten mit einem price von weniger als 300
-- N.B. price ist ein Index des activities Space.
local res, err = tar:select('activities', 'price', 300, { iterator = 'LT' })
box.space.activities.index.price:select({ 300 }, { iterator = 'LT' })
insert
insert(<Verbindungsobjekt>, <Space-Name>, <Tupel>)
wobei <Tupel> das Tupel ist, das in <Space> eingefügt werden soll, während der Primärindex, der eindeutig ist, auf den im Tupel angegebenen Wert gesetzt wird.
Die Funktion gibt den eingefügten Datensatz zurück, wenn die Operation erfolgreich ist.
insert Beispiele
local res, err = tar:insert('activities', { 16, 120, { activity = 'surf', price = 121 } })
-- Antwort:
[[16,120,{"activity":"surf","price":121}]]
box.space.activities:insert({16, 120, { activity = 'surf', price = 121 }})
replace
replace(<Verbindungsobjekt>, <Space-Name>, <Tupel>)
Der Replace-Befehl ist in der Aufrufweise und Signatur ähnlich dem Insert-Befehl. Aber jetzt suchen wir nach dem Ersetzen eines bereits vorhandenen Datensatzes, anstatt einen neuen einzufügen. Wir benötigen erneut den Wert eines primären eindeutigen Index. Aber jetzt muss der Wert vorhanden sein, damit die Operation erfolgreich ist. Wenn die Operation erfolgreich ist, wird der Datensatz mit den ersetzten Werten zurückgegeben.
replace Beispiele
local res, err = tar:replace('activities', { 16, 120, { activity = 'surf', price = 120 } })
-- Antwort:
[[16,120,{"activity":"surf","price":120}]]
Die obige Anfrage entspricht der Konsolenanfrage:
box.space.activities:update({ 16, 120, { activity = 'surf', price = 120 }})
update
update(<Verbindungsobjekt>, <Space-Name>, <Index>, <Key>, <Operatorenliste>)
wobei <Operatorenliste> die Liste der Operatoren ist, wie im Tarantool-Handbuch angegeben. Das Paar (<Key> ist ein Wert des primären (eindeutigen) <Index>.
<Operatorenliste> ist eine Tabelle der Form:
{ <Operator>, <Feldposition>, <Wert> }
+zum Hinzufügen zu einem numerischen Feld.-zum Subtrahieren von einem numerischen Feld.&für eine bitweise UND-Operation zwischen zwei unsigned Integers.|für eine bitweise ODER-Operation zwischen zwei unsigned Integers.^für eine bitweise XOR-Operation zwischen zwei unsigned Integers.:für das Verketten von Strings.!für das Einfügen eines Feldes.#für das Löschen eines Feldes.=für die Zuweisung eines bestimmten Wertes an ein Feld.
Es gibt den aktualisierten Datensatz zurück, wenn die Operation erfolgreich ist.
update Beispiele
local res, err = tar:update('activities', 'primary', 16, { { '=', 2, 341 }, { '=', 3, { activity = 'kitesurfing', price = 341 }}} )
-- Antwort:
[16,341,{"activity":"kitesurfing","price":341}]]
primary Index 16, den wir oben eingefügt haben, wurde aktualisiert.
Die obige Anfrage entspricht der Konsolenanfrage:
box.space.activities.index.primary({ 16 }, { { '=', 2, 341 }, { '=', 3, { activity = 'kitesurfing', price = 341 }}})
upsert
upsert(<Verbindungsobjekt>, <Space-Name>, <Key>, <Operatorenliste>, <neues Tupel>)
Abgesehen vom <neuen Tupel> Argument ist die Funktionssignatur ähnlich wie bei update. Tatsächlich ist upsert zwei Befehle in einem. Update, wenn der Datensatz, der durch das Paar (<neue Tupel> ist das Tupel, das eingefügt werden soll, wenn der <Key>-Wert nicht im <Index> existiert. Es gibt eine leere Tabelle {} zurück, wenn die Operation erfolgreich ist. Wenn die Operation nicht erfolgreich ist, gibt sie nil zurück.
upsert Beispiele
Ein Insert.
local res, err = tar:upsert('activities', 17, { { '=', 2, 450 }, { '=', 3, { activity = 'submarine tour 8', price = 450 }}}, { 17, 450, { activity = 'waterski', price = 365 }})
-- Antwort:
{}
{ 18, 450, { activity = 'waterski', price = 365 }}
box.space.activities:upsert({ 17 }, { { '=', 2, 450 }, { '=', 3, { activity = 'submarine tour 8', price = 450 }}}, { 17, 450, { activity = 'waterski', price = 365 }})
local res, err = tar:upsert('activities', 17, { { '=', 2, 450 }, { '=', 3, { activity = 'submarine tour 8', price = 450 }}}, { 18, 285, { activity = 'kitesurfing', price = 285 }})
-- Antwort:
{}
primary Index (eindeutig) identifiziert wird.
delete
delete(<Verbindungsobjekt>, <Space>, <Key>)
löscht den Datensatz, der eindeutig durch <Key> aus <Space> spezifiziert ist. Beachten Sie, dass <Key> zu einem primären (eindeutigen) Index gehören muss. Es gibt den gelöschten Datensatz zurück, wenn die Operation erfolgreich ist.
delete Beispiele
local response, err = tar:delete('activities', 17)
-- Antwort:
[17,450,{"activity":"waterski","price":365}]]
Die obige Anfrage entspricht der Konsolenanfrage:
box.space.activities:delete({ 17 })
call
call(<Verbindungsobjekt>, <proc>, <args>)
Ruft eine Stored Procedure (Lua-Funktion) im Tarantool-Server auf, mit dem wir verbunden sind. Es gibt die Ergebnisse des Aufrufs zurück.
call Beispiele
Da die Tarantool-Konsole ein Lua REPL ist, kann jede Funktion aufgerufen werden, solange sie in der Umgebung verfügbar ist.
local res, err = tar:call('table.concat', { {'hello', ' ', 'world' } })
-- Antwort:
[["hello world"]]
table.concat Funktion aus der Tabellenbibliothek aufgerufen, um die Tabelle zu verketten:
{'hello', ' ', 'world' }
table.concat({'hello', ' ', 'world' })
Für viele Beispiele von Tarantool Stored Procedures siehe das Repository; https://github.com/mailru/tarlua
hide_version_header
hide_version_header(<Verbindungsobjekt>)
Standardmäßig sendet jede Antwort einen benutzerdefinierten HTTP-Header X-Tarantool-Version mit der Version des Tarantool-Servers.
X-Tarantool-Version: 1.6.6-191-g82d1bc3
Der Aufruf von hide_version_header entfernt den Header.
tar:hide_version_header()
Es gibt keine Werte zurück.
GitHub
Sie finden zusätzliche Konfigurationstipps und Dokumentationen für dieses Modul im GitHub-Repository für nginx-module-tarantool.