Funktionsreferenz für Trusted Language Extensions für PostgreSQL

Sehen Sie sich die folgende Referenzdokumentation zu den Funktionen an, die in Trusted Language Extensions für PostgreSQL verfügbar sind. Verwenden Sie diese Funktionen, um Ihre TLE-Erweiterungen, d. h. die PostgreSQL-Erweiterungen, die Sie mit dem Trusted Language Extensions Development Kit entwickeln, zu installieren, zu registrieren, zu aktualisieren und zu verwalten.

pgtle.available_extensions

Die pgtle.available_extensions-Funktion ist eine Mengenrückgabefunktion. Sie gibt alle verfügbaren TLE-Erweiterungen in der Datenbank zurück. Jede zurückgegebene Zeile enthält Informationen zu einer einzelnen TLE-Erweiterung.

Funktionsprototyp

pgtle.available_extensions()

Rolle

Keine.

Argumente

Keine.

Output

Verwendungsbeispiel

SELECT * FROM pgtle.available_extensions();

pgtle.available_extension_versions

Die available_extension_versions-Funktion ist eine Mengenrückgabefunktion. Sie gibt eine Liste aller verfügbaren TLE-Erweiterungen und deren Versionen zurück. Jede Zeile enthält Informationen zu einer bestimmten Version der angegebenen TLE-Erweiterung, einschließlich der Frage, ob für sie eine bestimmte Rolle erforderlich ist.

Funktionsprototyp

pgtle.available_extension_versions()

Rolle

Keine.

Argumente

Keine.

Output

Weitere Informationen zu Ausgabewerten finden Sie unter Packaging Related Objects into an Extension > Extension Files in der PostgreSQL-Dokumentation.

Verwendungsbeispiel

SELECT * FROM pgtle.available_extension_versions();

pgtle.extension_update_paths

Die extension_update_paths-Funktion ist eine Mengenrückgabefunktion. Sie gibt eine Liste aller möglichen Aktualisierungspfade für eine TLE-Erweiterung zurück. Jede Zeile enthält die verfügbaren Upgrades oder Downgrades für diese TLE-Erweiterung.

Funktionsprototyp

pgtle.extension_update_paths(name)

Rolle

Keine.

Argumente

name – Der Name der TLE-Erweiterung, von der die Upgrade-Pfade abgerufen werden sollen.

Output

Verwendungsbeispiel

SELECT * FROM pgtle.extension_update_paths('your-TLE');

pgtle.install_extension

Mit dieser install_extension-Funktion können Sie die Artefakte, aus denen Ihre TLE-Erweiterung besteht, in der Datenbank installieren. Anschließend können sie mit dem CREATE EXTENSION-Befehl erstellt werden.

Funktionsprototyp

pgtle.install_extension(name text, version text, description text, ext text, requires text[] DEFAULT NULL::text[])

Rolle

Keine.

Argumente

Viele dieser Argumente entsprechen denen, die in einer Erweiterungskontrolldatei für die Installation einer PostgreSQL-Erweiterung im Dateisystem einer PostgreSQL-Instance enthalten sind. Weitere Informationen finden Sie unter Extension Files in Packaging Related Objects in a Extension in der PostgreSQL-Dokumentation.

Output

Diese Funktion gibt bei Erfolg OK und bei Fehler NULL zurück.

Verwendungsbeispiel

SELECT pgtle.install_extension(
 'pg_tle_test',
 '0.1',
 'My first pg_tle extension',
$_pgtle_$
  CREATE FUNCTION my_test()
  RETURNS INT
  AS $$
    SELECT 42;
  $$ LANGUAGE SQL IMMUTABLE;
$_pgtle_$
);

pgtle.install_update_path

Die install_update_path-Funktion stellt einen Aktualisierungspfad zwischen zwei verschiedenen Versionen einer TLE-Erweiterung bereit. Mit dieser Funktion können Benutzer Ihrer TLE-Erweiterung ihre Version mithilfe der ALTER EXTENSION ... UPDATE-Syntax aktualisieren.

Funktionsprototyp

pgtle.install_update_path(name text, fromvers text, tovers text, ext text)

Rolle

pgtle_admin

Argumente

Output

Keine.

Verwendungsbeispiel

SELECT pgtle.install_update_path('pg_tle_test', '0.1', '0.2',
  $_pgtle_$
    CREATE OR REPLACE FUNCTION my_test()
    RETURNS INT
    AS $$
      SELECT 21;
    $$ LANGUAGE SQL IMMUTABLE;
  $_pgtle_$
);

pgtle.register_feature

Die register_feature-Funktion fügt der pgtle.feature_info-Tabelle das angegebene interne PostgreSQL-Feature hinzu. PostgreSQL-Haken sind ein Beispiel für ein internes PostgreSQL-Feature. Das Trusted Language Extensions Development Kit unterstützt die Verwendung von PostgreSQL-Haken. Derzeit unterstützt diese Funktion das folgende Feature.

Funktionsprototyp

pgtle.register_feature(proc regproc, feature pg_tle_feature)

Rolle

pgtle_admin

Argumente

Output

Keine.

Verwendungsbeispiel

SELECT pgtle.register_feature('pw_hook', 'passcheck');

pgtle.register_feature_if_not_exists

Die pgtle.register_feature_if_not_exists-Funktion fügt der pgtle.feature_info-Tabelle das angegebene PostgreSQL-Feature hinzu und identifiziert die TLE-Erweiterung oder eine andere Prozedur oder Funktion, die das Feature verwendet. Weitere Informationen zu Haken und Trusted Language Extensions finden Sie unter Verwenden von PostgreSQL-Haken mit Ihren TLE-Erweiterungen.

Funktionsprototyp

pgtle.register_feature_if_not_exists(proc regproc, feature pg_tle_feature)

Rolle

pgtle_admin

Argumente

Output

Gibt true zurück, nachdem das Feature für die angegebene Erweiterung registriert wurde. Gibt false zurück, wenn das Feature bereits registriert ist.

Verwendungsbeispiel

SELECT pgtle.register_feature_if_not_exists('pw_hook', 'passcheck');

pgtle.set_default_version

Mit der set_default_version-Funktion können Sie eine default_version für Ihre TLE-Erweiterung angeben. Mit dieser Funktion können Sie einen Upgrade-Pfad definieren und die Version als Standard für Ihre TLE-Erweiterung festlegen. Wenn Datenbankbenutzer Ihre TLE-Erweiterung in den Befehlen CREATE EXTENSION und ALTER EXTENSION ... UPDATE angeben, wird diese Version Ihrer TLE-Erweiterung in der Datenbank für diesen Benutzer erstellt.

Diese Funktion gibt bei Erfolg true zurück. Wenn die im name-Argument angegebene TLE-Erweiterung nicht vorhanden ist, gibt die Funktion einen Fehler zurück. Entsprechend wird ein Fehler zurückgegeben, wenn die version der TLE-Erweiterung nicht existiert.

Funktionsprototyp

pgtle.set_default_version(name text, version text)

Rolle

pgtle_admin

Argumente

Output

Verwendungsbeispiel

SELECT * FROM pgtle.set_default_version('my-extension', '1.1');

pgtle.uninstall_extension(name)

Die uninstall_extension-Funktion entfernt alle Versionen einer TLE-Erweiterung aus einer Datenbank. Diese Funktion verhindert, dass die TLE-Erweiterung durch künftige Aufrufe von CREATE EXTENSION installiert wird. Wenn die TLE-Erweiterung in der Datenbank nicht existiert, wird ein Fehler ausgelöst.

Die uninstall_extension-Funktion löscht die TLE-Erweiterung jedoch nicht, wenn diese derzeit in der Datenbank aktiv ist. Zum Löschen einer TLE-Erweiterung, die derzeit aktiv ist, müssen Sie explizit DROP EXTENSION aufrufen, um sie zu entfernen.

Funktionsprototyp

pgtle.uninstall_extension(extname text)

Rolle

pgtle_admin

Argumente

Output

Keine.

Verwendungsbeispiel

SELECT * FROM pgtle.uninstall_extension('pg_tle_test');

pgtle.uninstall_extension(name, version)

Die uninstall_extension(name, version)-Funktion entfernt die angegebene Version der TLE-Erweiterung aus der Datenbank. Diese Funktion verhindert, dass CREATE EXTENSION und ALTER EXTENSION eine TLE-Erweiterung installieren oder auf die angegebene Version aktualisieren. Diese Funktion entfernt außerdem alle Aktualisierungspfade für die angegebene Version der TLE-Erweiterung. Diese Funktion deinstalliert die TLE-Erweiterung jedoch nicht, wenn diese derzeit in der Datenbank aktiv ist. Sie müssen explizit DROP EXTENSION aufrufen, um die TLE-Erweiterung zu entfernen. Informationen zur Deinstallation aller Versionen einer TLE-Erweiterung finden Sie unter pgtle.uninstall_extension(name).

Funktionsprototyp

pgtle.uninstall_extension(extname text, version text)

Rolle

pgtle_admin

Argumente

Output

Keine.

Verwendungsbeispiel

SELECT * FROM pgtle.uninstall_extension('pg_tle_test', '0.2');

pgtle.uninstall_extension_if_exists

Die uninstall_extension_if_exists-Funktion entfernt alle Versionen einer TLE-Erweiterung aus einer bestimmten Datenbank. Wenn die TLE-Erweiterung nicht existiert, bleibt die Funktion im Hintergrund (es wird keine Fehlermeldung ausgegeben). Wenn die angegebene Erweiterung derzeit in einer Datenbank aktiv ist, wird sie von dieser Funktion nicht gelöscht. Sie müssen DROP EXTENSION explizit aufrufen, um die TLE-Erweiterung zu entfernen, bevor Sie diese Funktion verwenden, um ihre Artefakte zu deinstallieren.

Funktionsprototyp

pgtle.uninstall_extension_if_exists(extname text)

Rolle

pgtle_admin

Argumente

Output

Die uninstall_extension_if_exists-Funktion gibt true nach der Deinstallation der angegebenen Erweiterung zurück. Wenn die angegebene Erweiterung nicht vorhanden ist, gibt die Funktion false zurück.

Verwendungsbeispiel

SELECT * FROM pgtle.uninstall_extension_if_exists('pg_tle_test');

pgtle.uninstall_update_path

Die uninstall_update_path-Funktion entfernt den angegebenen Aktualisierungspfad einer TLE-Erweiterung. Dadurch wird verhindert, dass ALTER EXTENSION ... UPDATE TO diesen Pfad als Aktualisierungspfad verwendet.

Wenn die TLE-Erweiterung derzeit von einer der Versionen in diesem Aktualisierungspfad verwendet wird, verbleibt sie in der Datenbank.

Wenn der angegebene Aktualisierungspfad nicht vorhanden ist, gibt diese Funktion einen Fehler aus.

Funktionsprototyp

pgtle.uninstall_update_path(extname text, fromvers text, tovers text)

Rolle

pgtle_admin

Argumente

Output

Keine.

Verwendungsbeispiel

SELECT * FROM pgtle.uninstall_update_path('pg_tle_test', '0.1', '0.2');

pgtle.uninstall_update_path_if_exists

Die uninstall_update_path_if_exists-Funktion ähnelt uninstall_update_path insofern, als sie den angegebenen Aktualisierungspfad aus einer TLE-Erweiterung entfernt. Wenn der Aktualisierungspfad jedoch nicht existiert, löst diese Funktion keine Fehlermeldung aus. Stattdessen gibt die Funktion false zurück.

Funktionsprototyp

pgtle.uninstall_update_path_if_exists(extname text, fromvers text, tovers text)

Rolle

pgtle_admin

Argumente

Output

Verwendungsbeispiel

SELECT * FROM pgtle.uninstall_update_path_if_exists('pg_tle_test', '0.1', '0.2');

pgtle.unregister_feature

Die unregister_feature-Funktion bietet eine Möglichkeit, Funktionen zu entfernen, die für die Verwendung von pg_tle-Features wurden, wie z. B. Haken. Weitere Informationen zur Registrierung eines Features erhalten Sie unter pgtle.register_feature.

Funktionsprototyp

pgtle.unregister_feature(proc regproc, feature pg_tle_features)

Rolle

pgtle_admin

Argumente

Output

Keine.

Verwendungsbeispiel

SELECT * FROM pgtle.unregister_feature('pw_hook', 'passcheck');

pgtle.unregister_feature_if_exists

Die unregister_feature-Funktion bietet eine Möglichkeit, Funktionen zu entfernen, die für die Verwendung von pg_tle-Features wurden, wie z. B. Haken. Weitere Informationen finden Sie unter Verwenden von PostgreSQL-Haken mit Ihren TLE-Erweiterungen. Gibt true zurück, nachdem die Registrierung der Funktion erfolgreich aufgehoben wurde. Gibt false zurück, wenn das Feature nicht registriert wurde.

Informationen zur Registrierung von pg_tle-Features für Ihre TLE-Erweiterungen finden Sie unter pgtle.register_feature.

Funktionsprototyp

pgtle.unregister_feature_if_exists('proc regproc', 'feature pg_tle_features')

Rolle

pgtle_admin

Argumente

Output

Gibt true oder false wie folgt zurück.

Verwendungsbeispiel

SELECT * FROM pgtle.unregister_feature_if_exists('pw_hook', 'passcheck');