CREATE PACKAGE

CREATE PACKAGE — создать пакет

Синтаксис

CREATE [ OR REPLACE ] PACKAGE имя_пакета элемент_пакета [ ... ]

Описание

CREATE PACKAGE создаёт новый пакет в текущей базе данных.

Пакет — это по сути схема, которая помогает организовать взаимосвязанные именованные объекты, поэтому его также можно создать командой CREATE SCHEMA, и с ним можно выполнять те же действия, что и с обычной схемой. Однако пакет может содержать только функции, процедуры и составные типы.

CREATE OR REPLACE PACKAGE либо создаст новый пакет, либо заменит существующее определение. Вы можете заменить существующий пакет, если он содержит только функции и типы, другие объекты должны быть предварительно удалены. Если при замене пакета не меняются сигнатуры содержащихся в нём функций, их содержимое заменяется, а зависимые объекты остаются. Если же сигнатура функции меняется, фактически создаётся отдельная функция. Новая функция будет создана успешно только при отсутствии объектов, зависящих от предыдущей, в противном случае CREATE OR REPLACE PACKAGE завершается ошибкой. То же ограничение действует при замене типов. При замене пакетов убедитесь, что никакие другие сеансы не используют их (другими словами, перед заменой пакетов остановите использующее их приложение).

Параметры

имя_пакета

Имя создаваемого пакета. Имя пакета должно отличаться от имени любого существующего пакета или схемы в текущей базе данных. Имя не может начинаться с pg_, так как такие имена зарезервированы для системных схем.

элемент_пакета

Оператор SQL, определяющий объект, который будет создан в пакете. В настоящее время внутри CREATE PACKAGE допускаются только операторы CREATE FUNCTION, CREATE TYPE и CREATE PROCEDURE. Подкоманды обрабатываются по существу так же, как и отдельные команды, выполняемые после создания пакета. По умолчанию все переменные, объявленные в функции инициализации пакета, а также функции и процедуры пакета являются публичными, поэтому с помощью записи с точкой к ним могут обращаться функции, процедуры и анонимные блоки, импортирующие пакет. Модификатор #private определяет функции и процедуры как внутренние, а модификатор #export определяет, какие переменные пакета являются публичными. Более подробно функции и модификаторы пакетов описаны в Разделе 44.11.

Замечания

Чтобы создать пакет, пользователь должен быть суперпользователем или иметь право CREATE для текущей базы данных.

Примеры

Создание пакета counter с функциями:

CREATE PACKAGE counter
    CREATE FUNCTION __init__() RETURNS void AS $$ -- инициализация пакета
    #export on
    DECLARE
        n int := 1; -- публичная пакетная переменная n
        k int := 3; -- публичная пакетная переменная k
    BEGIN
        FOR i IN 1..10 LOOP
            n := n + n;
        END LOOP;
    END;
    $$

    CREATE FUNCTION inc() RETURNS int AS $$ -- публичная пакетная функция inc()
    BEGIN
        n := n + 1;
        RETURN n;
    END;
    $$
;

Заметьте, что отдельные подкоманды не заканчиваются точкой с запятой, так же как в CREATE SCHEMA, и при создании функций не указывается язык.

Если в функции инициализации пакета указан модификатор #export on, все объявленные переменные являются публичными, то есть они доступны снаружи пакета. Отсутствие в пакете модификатора #export (значение по умолчанию) приводит к тому же результату. Функция inc() по умолчанию является публичной и доступна снаружи пакета, как и любая другая функция или процедура пакета.

Следующий пример показывает как можно использовать описанный выше пакет.

DO $$
#import counter
BEGIN
    RAISE NOTICE '%', counter.n;
    RAISE NOTICE '%', counter.inc();
END;
$$;

NOTICE:  1024
NOTICE:  1025

Другой вариант предыдущего примера:

CREATE PACKAGE foo
  CREATE TYPE footype AS (a int, b int)

  CREATE FUNCTION __init__() RETURNS void AS $$
  #export y
  DECLARE
    x int := 1; -- внутренняя пакетная переменная x
    y int := 5; -- публичная пакетная переменная y
  BEGIN
    RAISE NOTICE 'foo initialized';
  END;
  $$

  CREATE FUNCTION get_x() RETURNS int AS $$ -- публичная пакетная функция get_x()
  BEGIN
    RETURN x;
  END;
  $$

  CREATE PROCEDURE set_x(val int) AS $$ -- публичная пакетная процедура set_x()
  BEGIN
    x := val;
    CALL foo.check_x();
  END;
  $$

  CREATE PROCEDURE check_x() AS $$ -- внутренняя пакетная процедура check_x()
  #private
  BEGIN
    IF x <= 0 THEN
      RAISE INFO 'now x is not natural number';
    ELSE
      RAISE INFO 'now x is natural number';
    END IF;
  END;
  $$
;

В этом примере переменная y, функция get_x() и процедура set_x(int) из пакета foo являются публичными.

Другой вариант предыдущего примера:

DO $$
#import foo
BEGIN
  RAISE INFO 'y = %', foo.y;
  RAISE INFO 'x = %', foo.get_x();
  CALL foo.set_x(25);
  RAISE INFO 'x = %', foo.get_x();
END;
$$;

INFO:  y = 5
INFO:  x = 1
INFO:  x set to natural value
INFO:  x = 25

Ниже показано, как можно добиться того же результата командой CREATE SCHEMA:

CREATE SCHEMA foo;
CREATE TYPE foo.footype AS (a int, b int);

CREATE FUNCTION foo.__init__() RETURNS void AS $$
#export y
DECLARE
  x int := 1; -- внутренняя пакетная переменная x
  y int := 5; -- публичная пакетная переменная y
BEGIN
  RAISE NOTICE 'foo initialized';
END;
$$ LANGUAGE plpgsql;

CREATE FUNCTION foo.get_x() RETURNS int AS $$ -- публичная пакетная функция get_x()
#package
BEGIN
  RETURN x;
END;
$$ LANGUAGE plpgsql;

CREATE PROCEDURE foo.set_x(val int) AS $$ -- публичная пакетная процедура set_x()
#package
BEGIN
  x := val;
  CALL foo.check_x();
END;
$$ LANGUAGE plpgsql;

CREATE PROCEDURE foo.check_x() AS $$ -- внутренняя пакетная процедура check_x()
#package
#private
BEGIN
  IF x <= 0 THEN
    RAISE INFO 'x set to not natural value';
  ELSE
    RAISE INFO 'x set to natural value';
  END IF;
END;
$$ LANGUAGE plpgsql;

Обратите внимание, что в этом случае вы должны использовать модификаторы #package.

См. также

DROP PACKAGE

CREATE PACKAGE

CREATE PACKAGE — define a new package

Synopsis

CREATE [ OR REPLACE ] PACKAGE package_name package_element [ ... ]

Description

CREATE PACKAGE enters a new package into the current database.

A package is essentially a schema that helps to organize the named objects with a related purpose so it can be also created using CREATE SCHEMA and is subject to the same actions as a schema. A package should contain only functions, procedures and composite types.

CREATE OR REPLACE PACKAGE will either create a new package, or replace an existing definition. You can replace the existing package if it contains only functions and types, other objects must be previously dropped. If you replace the package without changing the function signature, its body is replaced, while dependent objects still remain. If the function signature changes, you would actually be creating a new, distinct function. The latter would only work when there are no dependent objects, otherwise the CREATE OR REPLACE PACKAGE is forced to fail. The same restriction applies to replacing types. When replacing packages, make sure that no other sessions use them (which can be done by stopping the application before replacing the packages).

Parameters

package_name

The name of a package to be created. The package name must be distinct from the name of any existing package or schema in the current database. The name cannot begin with pg_, as such names are reserved for system schemas.

package_element

An SQL statement defining an object to be created within the package. Currently, only CREATE FUNCTION, CREATE TYPE, and CREATE PROCEDURE are accepted as clauses within CREATE PACKAGE. The subcommands are treated essentially the same as separate commands issued after creating the package. By default, all the variables declared in the package initialization function, package functions and package procedures are public, so they can be called using dot notation from outside the package by other functions, procedures and anonymous blocks that import the package. The #private modifier defines functions and procedures as private, and the #export modifier defines which package variables are public. For more information on package functions and modifiers, see Section 44.11.

Notes

To create a package, the invoking user must be a superuser or have the CREATE privilege for the current database.

Examples

Create a package named counter and create functions within it:

CREATE PACKAGE counter
    CREATE FUNCTION __init__() RETURNS void AS $$ -- package initialization
    #export on
    DECLARE
        n int := 1; -- public package variable n
        k int := 3; -- public package variable k
    BEGIN
        FOR i IN 1..10 LOOP
            n := n + n;
        END LOOP;
    END;
    $$

    CREATE FUNCTION inc() RETURNS int AS $$ -- public package function inc()
    BEGIN
        n := n + 1;
        RETURN n;
    END;
    $$
;

Notice that the individual subcommands do not end with semicolons, just as in CREATE SCHEMA, and no language is specified when creating functions.

The #export on modifier inside the package initialization function renders all the declared variables public, meaning they are available outside the package. The same result is achieved if the package does not contain the #export modifier (default). The inc() function is public by default and is available outside the package, as any other package function or procedure.

The example below shows how the above-described package can be used.

DO $$
#import counter
BEGIN
    RAISE NOTICE '%', counter.n;
    RAISE NOTICE '%', counter.inc();
END;
$$;

NOTICE:  1024
NOTICE:  1025

A variation of the previous example:

CREATE PACKAGE foo
  CREATE TYPE footype AS (a int, b int)

  CREATE FUNCTION __init__() RETURNS void AS $$
  #export y
  DECLARE
    x int := 1; -- private package variable x
    y int := 5; -- public package variable y
  BEGIN
    RAISE NOTICE 'foo initialized';
  END;
  $$

  CREATE FUNCTION get_x() RETURNS int AS $$ -- public package function get_x()
  BEGIN
    RETURN x;
  END;
  $$

  CREATE PROCEDURE set_x(val int) AS $$ -- public package procedure set_x()
  BEGIN
    x := val;
    CALL foo.check_x();
  END;
  $$

  CREATE PROCEDURE check_x() AS $$ -- private package procedure check_x()
  #private
  BEGIN
    IF x <= 0 THEN
      RAISE INFO 'now x is not natural number';
    ELSE
      RAISE INFO 'now x is natural number';
    END IF;
  END;
  $$
;

In this example, the y variable, the get_x() function and the set_x(int) procedure of the foo package are public.

A variation of the previous example:

DO $$
#import foo
BEGIN
  RAISE INFO 'y = %', foo.y;
  RAISE INFO 'x = %', foo.get_x();
  CALL foo.set_x(25);
  RAISE INFO 'x = %', foo.get_x();
END;
$$;

INFO:  y = 5
INFO:  x = 1
INFO:  x set to natural value
INFO:  x = 25

The following is an equivalent way of achieving the same result using the CREATE SCHEMA command:

CREATE SCHEMA foo;
CREATE TYPE foo.footype AS (a int, b int);

CREATE FUNCTION foo.__init__() RETURNS void AS $$
#export y
DECLARE
  x int := 1; -- private package variable x
  y int := 5; -- public package variable y
BEGIN
  RAISE NOTICE 'foo initialized';
END;
$$ LANGUAGE plpgsql;

CREATE FUNCTION foo.get_x() RETURNS int AS $$ -- public package function get_x()
#package
BEGIN
  RETURN x;
END;
$$ LANGUAGE plpgsql;

CREATE PROCEDURE foo.set_x(val int) AS $$ -- public package procedure set_x()
#package
BEGIN
  x := val;
  CALL foo.check_x();
END;
$$ LANGUAGE plpgsql;

CREATE PROCEDURE foo.check_x() AS $$ -- private package procedure check_x()
#package
#private
BEGIN
  IF x <= 0 THEN
    RAISE INFO 'x set to not natural value';
  ELSE
    RAISE INFO 'x set to natural value';
  END IF;
END;
$$ LANGUAGE plpgsql;

Note that in this case you must use #package modifiers.

See Also

DROP PACKAGE
FAQ