--- /dev/null
+### Аннотация
+
+#### Создание расширения PostgreSQL
+#### Первый шаг на пути к разработке ядра postgres.
+
+Популярность PostgreSQL обеспечивается не только ее производительностью и доступностью, но во многом своим открытым процессом разработки: исходный код СУБД доступен для изучения и модификации, и любой желающий может принять участие в разработке ядра проекта, предлагая свое улучшения и изменения.
+Программист для того чтобы стать ядра разработчиком ядра PostgreSQL должен пройти длинный путь, но практически каждый начинает свое движение с разработки расширения PostgreSQL.
+PostgreSQL предоставляет широкие возможности по расширению функциональности и модификации поведения ядра СУБД через механизм расширений.
+
+В этой лекции мы рассмотрим основы создания расширений: что это такое, из каких элементов оно состоит, и создадим первое учебное расширение.
--- /dev/null
+Extension is a set of PostgreSQL objects that can be `CREATE`ed.
+Like `CREATE FUNCTION`, `CREATE TYPE` or `CREATE OPERATOR`.
+This set is created, updated and deleted as a bundle.
+When you do `CREATE EXTENSION` you it will create all object included into extension.
+When you do `DROP EXTENSION` all that objects will be automatically removed.
+
+So extension is just a set of SQL commands to create or update extension schema.
+(You even do not need to delete it, `DROP EXTENSION` will delete them automatically)
+
+Functions may be written in `PL/pgSQL` or other `PL/*` or you can load binary function from shared `.so` library.
+.
+You can register a function as a hook handler to change behavior if PostgreSQL.
+
+
+
+See https://github.com/IshaanAdarsh/Postgres-extension-tutorial/blob/main/SGML/Main.md for more info
+
+```
+
+$ whoami
+nataraj
+
+$ sudo -u postgres createuser -s nataraj
+```
+
+Make sure that `-dev` files for postgres are installed. In Debian-based distributives it wil
+be like this
+
+```
+sudo apt-get install postgresql-server-dev-all
+
+```
+
+
+```
+$ mkdir my_first_extension
+
+$ cd my_first_extension
+```
+
+```
+touch my_first_extension.control
+```
+
+```
+# my_first_extension.control
+# Comment line to provide additional information about the extension
+comment = 'My Very First Extension'
+
+# Specifies the default version of the extension
+default_version = '0.0.1'
+```
+
+https://www.postgresql.org/docs/17/extend-extensions.html#EXTEND-EXTENSIONS-FILES
+
+
+---
+
+```
+touch my_first_extension--0.0.1.sql
+```
+
+```
+CREATE TABLE my_first_extension_table (
+ id SERIAL PRIMARY KEY,
+ my_string VARCHAR NOT NULL
+);
+
+INSERT INTO my_first_extension_table (my_string) VALUES('Hello, World');
+```
+
+---
+
+```
+touch Makefile
+```
+
+```
+EXTENSION = my_first_extension # Name of the extension
+DATA = my_first_extension--0.0.1.sql # SQL file containing extension objects and functions
+
+PG_CONFIG ?= pg_config # Path to the pg_config executable
+PGXS := $(shell $(PG_CONFIG) --pgxs) # Get the PostgreSQL Extension Makefile from pg_config
+include $(PGXS) # Include the PostgreSQL Extension Makefile
+```
+
+---
+
+```
+make
+sudo make install
+```
+
+```
+sudo -u postgres psql
+
+# CREATE EXTENSION my_first_extension;
+CREATE EXTENSION
+
+# SELECT * FROM my_first_extension_table;
+ id | my_string
+----+--------------
+ 1 | Hello, World
+(1 row)
+
+# DROP EXTENSION my_first_extension;
+DROP EXTENSION
+
+# SELECT * FROM my_first_extension_table;
+ERROR: relation "my_first_extension_table" does not exist
+СТРОКА 1: SELECT * FROM my_first_extension_table;
+ ^
+```
+
+------------
+
+# Add tests
+
+```
+mkdir sql
+```
+
+edit `sql/my_first_extension-main-test.sql`
+
+```
+CREATE EXTENSION my_first_extension;
+
+SELECT * FROM my_first_extension_table;
+
+DROP EXTENSION
+
+-- There should be no my_first_extension_table anymore
+SELECT * FROM my_first_extension_table;
+```
+
+----
+
+change Makefile
+
+```
+EXTENSION = my_first_extension # Name of the extension
+DATA = my_first_extension--0.0.1.sql # SQL file containing extension objects and functions
+REGRESS = my_first_extension-main-test
+
+
+PG_CONFIG ?= pg_config # Path to the pg_config executable
+PGXS := $(shell $(PG_CONFIG) --pgxs) # Get the PostgreSQL Extension Makefile from pg_config
+include $(PGXS) # Include the PostgreSQL Extension Makefile
+```
+
+run `make installcheck`
+
+
+and get an error: `my_first_extension/expected/my_first_extension-main-test.out: No such file or directory`
+
+and a `results` dir.
+
+----
+
+Check that `results/my_first_extension-main-test.out` is what you expect
+
+```
+$ cat results/my_first_extension-main-test.out
+CREATE EXTENSION my_first_extension;
+SELECT * FROM my_first_extension_table;
+ id | my_string
+----+--------------
+ 1 | Hello, World
+(1 row)
+
+DROP EXTENSION
+-- There should be no my_first_extension_table anymore
+SELECT * FROM my_first_extension_table;
+ERROR: syntax error at or near "SELECT"
+LINE 3: SELECT * FROM my_first_extension_table;
+ ^
+```
+
+----
+
+If everything as you expected copy `my_first_extension-main-test.out` from `results` dir to `expected`
+
+```
+mkdir expected
+cp results/my_first_extension-main-test.out expected
+```
+
+----
+
+Now tests should pass
+
+```
+n$ make installcheck
+echo "+++ regress install-check in +++" && /usr/lib/postgresql/15/lib/pgxs/src/makefiles/../../src/test/regress/pg_regress --inputdir=./ --bindir='/usr/lib/postgresql/15/bin' --dbname=contrib_regression my_first_extension-main-test
++++ regress install-check in +++
+(using postmaster on Unix socket, default port)
+============== dropping database "contrib_regression" ==============
+SET
+DROP DATABASE
+============== creating database "contrib_regression" ==============
+CREATE DATABASE
+ALTER DATABASE
+ALTER DATABASE
+ALTER DATABASE
+ALTER DATABASE
+ALTER DATABASE
+ALTER DATABASE
+============== running regression test queries ==============
+test my_first_extension-main-test ... ok 54 ms
+
+=====================
+ All 1 tests passed.
+=====================
+```
+
+-----
+
+Now let's create create a new version of extension, with a plpsql function in it
+
+* Change version from `0.0.1` to `0.0.2` in `my_first_extension.control`:
+
+```
+default_version = '0.0.2'
+```
+
+* rename schema creation file from `my_first_extension--0.0.1.sql` to `my_first_extension--0.0.2.sql`
+* create an schema update file `my_first_extension--0.0.1--0.0.2.sql`
+
+Add to both of them function creation code
+
+```
+CREATE FUNCTION my_one()
+returns int
+language plpgsql
+as
+$$
+begin
+ return 1;
+end;
+$$;
+
+```
+
+* Update `Makefile` adding new sql file names to `DATA` variable
+
+```
+DATA = my_first_extension--0.0.2.sql my_first_extension--0.0.1--0.0.2.sql
+```
+
+* install extension
+
+```
+sudo make install
+
+```
+
+* check everything works
+
+```
+$ sudo -u postgres psql
+
+=# CREATE EXTENSION my_first_extension;
+CREATE EXTENSION
+
+s=# SELECT my_one();
+ my_one
+--------
+ 1
+(1 row)
+```
+
+----
+
+Write test for `my_one` function yourself
+
+----
+
+https://www.highgo.ca/2020/01/10/how-to-create-test-and-debug-an-extension-written-in-c-for-postgresql/
+
+
+Creating C-function
+
+// Do not forget to install `postgresql-server-dev-all`
+
+create `my_first_extension.c` file
+
+```
+#include "postgres.h"
+#include "fmgr.h"
+
+PG_MODULE_MAGIC;
+
+PG_FUNCTION_INFO_V1(my_get_two);
+
+Datum
+my_get_two(PG_FUNCTION_ARGS)
+{
+ PG_RETURN_INT32(2);
+}
+```
+
+add following lines to `Makefile`
+
+```
+MODULE_big = my_first_extension
+OBJS = my_first_extension.o
+
+```
+and to the `my_first_extension.control`
+
+
+```
+module_pathname = '$libdir/my_first_extension'
+
+```
+
+
+Check everything works well by running
+
+```
+make
+```
+
+add to schema
+```
+CREATE FUNCTION my_two()
+RETURNS INT
+AS 'MODULE_PATHNAME', 'my_get_two'
+LANGUAGE C;
+```
+
+
+bump version in *.sql files, Makefile and control file
+
+
+```
+make
+sudo make install
+```
+
+Check everything works:
+
+```
+$ sudo -u postgres psql
+
+=# DROP EXTENSION my_first_extension;
+DROP EXTENSION
+
+=# CREATE EXTENSION my_first_extension;
+CREATE EXTENSION
+postgres=# SELECT my_two();
+ my_two
+--------
+ 2
+(1 row)
+
+```
+
+Do not forget to write tests!
+
+
--- /dev/null
+MODULE_big = my_first_extension
+EXTENSION = my_first_extension # Name of the extension
+DATA = my_first_extension--0.0.3.sql my_first_extension--0.0.1--0.0.2.sql my_first_extension--0.0.2--0.0.3.sql
+REGRESS = my_first_extension-main-test
+
+OBJS = my_first_extension.o
+
+
+PG_CONFIG ?= pg_config # Path to the pg_config executable
+PGXS := $(shell $(PG_CONFIG) --pgxs) # Get the PostgreSQL Extension Makefile from pg_config
+include $(PGXS) # Include the PostgreSQL Extension Makefile
+
+
--- /dev/null
+CREATE EXTENSION my_first_extension;
+SELECT * FROM my_first_extension_table;
+ id | my_string
+----+--------------
+ 1 | Hello, World
+(1 row)
+
+DROP EXTENSION my_first_extension;
+-- There should be no my_first_extension_table anymore
+SELECT * FROM my_first_extension_table;
+ERROR: relation "my_first_extension_table" does not exist
+LINE 1: SELECT * FROM my_first_extension_table;
+ ^
--- /dev/null
+CREATE FUNCTION my_one()
+returns int
+language plpgsql
+as
+$$
+begin
+ return 1;
+end;
+$$;
+
--- /dev/null
+CREATE FUNCTION my_two()
+RETURNS INT
+AS 'MODULE_PATHNAME', 'my_get_two'
+LANGUAGE C;
+
--- /dev/null
+CREATE TABLE my_first_extension_table (
+ id SERIAL PRIMARY KEY,
+ my_string VARCHAR NOT NULL
+);
+
+INSERT INTO my_first_extension_table (my_string) VALUES('Hello, World');
+
+
+CREATE FUNCTION my_one()
+returns int
+language plpgsql
+as
+$$
+begin
+ return 1;
+end;
+$$;
+
+
+CREATE FUNCTION my_two()
+RETURNS INT
+AS 'MODULE_PATHNAME', 'my_get_two'
+LANGUAGE C;
+
--- /dev/null
+#include "postgres.h"
+#include "fmgr.h"
+
+PG_MODULE_MAGIC;
+
+PG_FUNCTION_INFO_V1(my_get_two);
+
+Datum
+my_get_two(PG_FUNCTION_ARGS)
+{
+ PG_RETURN_INT32(2);
+}
--- /dev/null
+# my_first_extension.control
+# Comment line to provide additional information about the extension
+comment = 'My Very First Extension'
+
+# Specifies the default version of the extension
+default_version = '0.0.3'
+module_pathname = '$libdir/my_first_extension'
+
--- /dev/null
+CREATE EXTENSION my_first_extension;
+
+SELECT * FROM my_first_extension_table;
+
+DROP EXTENSION my_first_extension;
+
+-- There should be no my_first_extension_table anymore
+SELECT * FROM my_first_extension_table;
+
--- /dev/null
+MODULE_big = data_types_examples
+EXTENSION = data_types_examples # Name of the extension
+DATA = data_types_examples--0.0.1.sql
+# REGRESS = my_first_extension-main-test
+
+OBJS = data_types_examples.o warn_me.o my_factorial.o hello_world.o
+
+
+PG_CONFIG ?= pg_config # Path to the pg_config executable
+PGXS := $(shell $(PG_CONFIG) --pgxs) # Get the PostgreSQL Extension Makefile from pg_config
+include $(PGXS) # Include the PostgreSQL Extension Makefile
+
+
--- /dev/null
+
+
+CREATE FUNCTION warn_me(int) RETURNS int
+AS 'MODULE_PATHNAME', 'warn_me'
+LANGUAGE C;
+
+
+CREATE FUNCTION my_factorial(int) RETURNS int
+AS 'MODULE_PATHNAME', 'my_factorial'
+LANGUAGE C;
+
+
+CREATE FUNCTION hello_world()
+RETURNS TEXT
+AS 'MODULE_PATHNAME', 'hello_world'
+LANGUAGE C;
+
--- /dev/null
+#include "postgres.h"
+#include "fmgr.h"
+
+PG_MODULE_MAGIC;
+
+PG_FUNCTION_INFO_V1(my_inc);
+
+Datum
+my_inc(PG_FUNCTION_ARGS)
+{
+
+ PG_RETURN_INT32(2);
+}
--- /dev/null
+# my_first_extension.control
+# Comment line to provide additional information about the extension
+comment = 'Data Types Exampls'
+
+# Specifies the default version of the extension
+default_version = '0.0.1'
+module_pathname = '$libdir/data_types_examples'
+
--- /dev/null
+#include "postgres.h"
+#include "fmgr.h"
+#include "utils/builtins.h"
+
+PG_FUNCTION_INFO_V1(hello_world);
+
+Datum
+hello_world(PG_FUNCTION_ARGS)
+{
+ char message[] = "Hello, World!";
+ Datum datum;
+
+ datum = CStringGetTextDatum(message);
+
+ PG_RETURN_TEXT_P(datum);
+}
+
--- /dev/null
+#include "postgres.h"
+#include "fmgr.h"
+
+PG_FUNCTION_INFO_V1(my_factorial);
+
+Datum
+my_factorial(PG_FUNCTION_ARGS)
+{
+ int32 res, n = PG_GETARG_INT32(0);
+ Datum d;
+
+ if (n < 0)
+ elog(ERROR, "Так нельзя!");
+
+ if (n == 0)
+ PG_RETURN_INT32(1);
+
+ d = DirectFunctionCall1(my_factorial, Int32GetDatum(n - 1));
+
+ res = DatumGetInt32(d) * n;
+
+ PG_RETURN_INT32(res);
+}
+
--- /dev/null
+#include "postgres.h"
+#include "fmgr.h"
+
+PG_FUNCTION_INFO_V1(warn_me);
+
+Datum
+warn_me(PG_FUNCTION_ARGS)
+{
+ int32 n = PG_GETARG_INT32(0);
+ elog(WARNING, "Предупреждаю: %i", n);
+ PG_RETURN_INT32(n);
+}
+
--- /dev/null
+
+* Свободное ПО замечательно тем, что всегда можно самому посмтреть как и что устроено
+
+*Сеанс белой магии с разоблачениями*
+
+Не только знания о структуре, но и навыки работы с кодом
+
+
+## Стандартные арифметические типы
+
+Исторические причины:
+
+* Postgres95 моложе С99
+* Сколько байт займет `signed i;` ?
+
+Поэтому:
+
+```
+/* Historical names for types in <stdint.h>. */
+typedef int8_t int8;
+typedef int16_t int16;
+typedef int32_t int32;
+typedef int64_t int64;
+typedef uint8_t uint8;
+typedef uint16_t uint16;
+typedef uint32_t uint32;
+typedef uint64_t uint64;
+```
+`src/include/c.h`
+
+## Волшебные макросы pg-функций
+
+"С-Программист, помни! Макрос -- твой лучший друг!"
+
+Создание расширения начинается с вызова макроса
+
+```
+PG_MODULE_MAGIC;
+```
+
+На этом магия не заканчивается, а только начинается.
+
+// сам макрос создает функцию проверяющую совместимость подгружаемого расширения с ядрос PostgreSQL
+
+// текст макроса можно прочитать в `src/include/fmgr.h` но это для джедаев
+
+### Аргументы
+
+Вспоминаем функцию из предыдущей лекции
+
+```
+Datum
+my_get_two(PG_FUNCTION_ARGS)
+{
+ PG_RETURN_INT32(2);
+}
+```
+
+Макрос `PG_FUNCTION_ARGS` разворачивается в
+
+```
+/* Standard parameter list for fmgr-compatible functions */
+#define PG_FUNCTION_ARGS FunctionCallInfo fcinfo
+```
+см. `src/include/fmgr.h`
+
+---
+Структура `FunctionCallInfo` имеет развесистую структуру содержит информацию о параметрах переданных в pg-функцию, пользоваться ей напрямую затруднительно (если ты не джедай темной стороны силы)
+
+Но есть специальный набор макросов для удобной работы с аргументами pg-функции
+
+---
+
+Пример использования аргумента
+
+```
+#include "postgres.h"
+#include "fmgr.h"
+
+PG_FUNCTION_INFO_V1(warn_me);
+
+Datum
+warn_me(PG_FUNCTION_ARGS)
+{
+ int32 n = PG_GETARG_INT32(0);
+ elog(WARNING, "Предупреждаю: %i", n);
+ PG_RETURN_INT32(n);
+}
+```
+
+```
+CREATE FUNCTION warn_me(int) RETURNS int
+AS 'MODULE_PATHNAME', 'warn_me'
+LANGUAGE C;
+```
+
+Мы видим что макром `PG_GETARG_INT32` используется для получения первого аргумента.
+И этот аргумент сразу приводится к типу `int32`
+
+```
+# select warn_me(12);
+WARNING: Предупреждаю: 12
+ warn_me
+---------
+ 12
+(1 row)
+```
+
+---
+
+Посмотрим на реализацию `PG_GETARG_INT32` в `src/include/fmgr.h`:
+
+```
+/* Macros for fetching arguments of standard types */
+
+#define PG_GETARG_DATUM(n) (fcinfo->args[n].value)
+#define PG_GETARG_INT32(n) DatumGetInt32(PG_GETARG_DATUM(n))
+#define PG_GETARG_UINT32(n) DatumGetUInt32(PG_GETARG_DATUM(n))
+#define PG_GETARG_INT16(n) DatumGetInt16(PG_GETARG_DATUM(n))
+#define PG_GETARG_UINT16(n) DatumGetUInt16(PG_GETARG_DATUM(n))
+#define PG_GETARG_CHAR(n) DatumGetChar(PG_GETARG_DATUM(n))
+#define PG_GETARG_BOOL(n) DatumGetBool(PG_GETARG_DATUM(n))
+```
+
+Тут мы видим что как и все ее близницы братья `PG_GETARG_INT32` суммарно обращается к струкуре `fcinfo` о которой говорилось выше.
+
+Так же если мы проведем некоторое исследование мы узнаем что выражение `fcinfo->args[n].value` имеет тип `Datum`.
+
+И по всей видимости функция `DatumGetInt32` преобразует этот мифический пока для нас `Datum` к типу `int32`.
+
+К ним мы вернемся позже.
+
+(\*) задача со звездочкой: убедитесь самостоятельно что `fcinfo->args[n].value` имеет тип Datum
+
+---
+
+Если мы обратим свой взор к макросу `PG_RETURN_INT32` в том же `src/include/fmgr.h` то там увидем схожую картину
+
+```
+/* Macros for returning results of standard types */
+
+#define PG_RETURN_DATUM(x) return (x)
+#define PG_RETURN_INT32(x) return Int32GetDatum(x)
+#define PG_RETURN_UINT32(x) return UInt32GetDatum(x)
+#define PG_RETURN_INT16(x) return Int16GetDatum(x)
+#define PG_RETURN_UINT16(x) return UInt16GetDatum(x)
+#define PG_RETURN_CHAR(x) return CharGetDatum(x)
+#define PG_RETURN_BOOL(x) return BoolGetDatum(x)
+```
+
+Только тут направление преобразование другое `Int32GetDatum` из `int32` в `Datum`
+
+---
+
+Так что же такое Datum?
+
+`src/include/postgres.h`
+
+
+```
+/*
+ * A Datum contains either a value of a pass-by-value type or a pointer to a
+ * value of a pass-by-reference type. Therefore, we require:
+ *
+ * sizeof(Datum) == sizeof(void *) == 4 or 8
+ *
+ * The functions below and the analogous functions for other types should be used to
+ * convert between a Datum and the appropriate C type.
+ */
+
+typedef uintptr_t Datum;
+```
+
+`man uintptr_t`:
+
+`uintptr_t` is an unsigned integer type such that any valid (void *) value can be converted to this type and then converted back.
+
+Т.е. по сути это "машинное слово" определяемое разрядностью архитектуры.
+---
+
+В случае если размер данных позволяет, значение помещается в само "машинное слово".
+В случае если размеры данных выходят за рамки "машииного слова", данные размещаются в опертивной памяти а в переменную типа Datum помещается указатель на них.
+
+`src/include/postgres.h`
+
+```
+/*
+ * DatumGetInt32
+ * Returns 32-bit integer value of a datum.
+ */
+static inline int32
+DatumGetInt32(Datum X)
+{
+ return (int32) X;
+}
+```
+
+```
+/*
+ * Int32GetDatum
+ * Returns datum representation for a 32-bit integer.
+ */
+static inline Datum
+Int32GetDatum(int32 X)
+{
+ return (Datum) X;
+}
+```
+
+Т.е. тут мы просто явно приводим тип "машинного слова" к требуемому, ничего более
+
+(***) Задача с тремя звездочками: поразмышляйте, почему `DatumGetInt32` реализована как intine функция, а не как макрос
+
+---
+
+С хранением сложных типов данных в Datum мы будем резбираться на следующей лекции.
+
+А пока поиграем со стандартными типами
+
+```
+#include "postgres.h"
+#include "fmgr.h"
+
+PG_FUNCTION_INFO_V1(my_factorial);
+
+Datum
+my_factorial(PG_FUNCTION_ARGS)
+{
+ int32 res, n = PG_GETARG_INT32(0);
+ Datum d;
+
+ if (n < 0)
+ elog(ERROR, "Так нельзя!");
+
+ if (n == 0)
+ PG_RETURN_INT32(1);
+
+ d = DirectFunctionCall1(my_factorial, Int32GetDatum(n - 1));
+
+ res = DatumGetInt32(d) * n;
+
+ PG_RETURN_INT32(res);
+}
+```
+
+(*) Задача со звездочкой: Посмотрите на реализацию вызова `DirectFunctionCall1`, как она устроена внутри
+
--- /dev/null
+# Курс лекций "Как стать разработчиком PostgreSQL"
+
+Данный курс предназначен для начинающих разработчиков еще не погрузившихся в мир системного программирования в общем и не знакомых с внутреннем устройством PostgreSQL в частности.
+В рамках курса учащийся двигаясь от простого к сложному познакомится с кодом СУБД PostgreSQL, с основными структурами и абстракциями используемыми в коде, а так же с приемами программирования применяющимися при разработки ядра PostgreSQL.
+Курс предполагает решение большого количества простых учебных задач затрагивающих разные аспекты функционирования ядра PostgreSQL, с подробным изучением исходного кода ядра реализующего изучаемую функциональность.
+В идеале после завершения курса учащийся должен свободно ориентироваться в большей части кода ядра PostgreSQL или уметь самостоятельно разобраться с теми частями, которые затронуты не были.
+
+Данный курс не предполагает углубленного знакомства с техникой и алгоритмикой хранения поиска и обработки данных, но предполагает подробное знакомство с кодовой инфраструктурой в рамках которой эти алгоритмы практически реализованы.
+
+Курс находится на ранних этапах разработки.
+На данный момент готовы лекции:
+
+- Создание первого расширения PostgreSQL
+- Базовые структуры PostgreSQL: Регистровые типы данных
+
+В процессе создания находится лекция:
+
+- Базовые структуры PostgreSQL: Типы данных переменной длинны
+
+++ /dev/null
-### Аннотация
-
-#### Создание расширения PostgreSQL
-#### Первый шаг на пути к разработке ядра postgres.
-
-Популярность PostgreSQL обеспечивается не только ее производительностью и доступностью, но во многом своим открытым процессом разработки: исходный код СУБД доступен для изучения и модификации, и любой желающий может принять участие в разработке ядра проекта, предлагая свое улучшения и изменения.
-Программист для того чтобы стать ядра разработчиком ядра PostgreSQL должен пройти длинный путь, но практически каждый начинает свое движение с разработки расширения PostgreSQL.
-PostgreSQL предоставляет широкие возможности по расширению функциональности и модификации поведения ядра СУБД через механизм расширений.
-
-В этой лекции мы рассмотрим основы создания расширений: что это такое, из каких элементов оно состоит, и создадим первое учебное расширение.
+++ /dev/null
-Extension is a set of PostgreSQL objects that can be `CREATE`ed.
-Like `CREATE FUNCTION`, `CREATE TYPE` or `CREATE OPERATOR`.
-This set is created, updated and deleted as a bundle.
-When you do `CREATE EXTENSION` you it will create all object included into extension.
-When you do `DROP EXTENSION` all that objects will be automatically removed.
-
-So extension is just a set of SQL commands to create or update extension schema.
-(You even do not need to delete it, `DROP EXTENSION` will delete them automatically)
-
-Functions may be written in `PL/pgSQL` or other `PL/*` or you can load binary function from shared `.so` library.
-.
-You can register a function as a hook handler to change behavior if PostgreSQL.
-
-
-
-See https://github.com/IshaanAdarsh/Postgres-extension-tutorial/blob/main/SGML/Main.md for more info
-
-```
-
-$ whoami
-nataraj
-
-$ sudo -u postgres createuser -s nataraj
-```
-
-Make sure that `-dev` files for postgres are installed. In Debian-based distributives it wil
-be like this
-
-```
-sudo apt-get install postgresql-server-dev-all
-
-```
-
-
-```
-$ mkdir my_first_extension
-
-$ cd my_first_extension
-```
-
-```
-touch my_first_extension.control
-```
-
-```
-# my_first_extension.control
-# Comment line to provide additional information about the extension
-comment = 'My Very First Extension'
-
-# Specifies the default version of the extension
-default_version = '0.0.1'
-```
-
-https://www.postgresql.org/docs/17/extend-extensions.html#EXTEND-EXTENSIONS-FILES
-
-
----
-
-```
-touch my_first_extension--0.0.1.sql
-```
-
-```
-CREATE TABLE my_first_extension_table (
- id SERIAL PRIMARY KEY,
- my_string VARCHAR NOT NULL
-);
-
-INSERT INTO my_first_extension_table (my_string) VALUES('Hello, World');
-```
-
----
-
-```
-touch Makefile
-```
-
-```
-EXTENSION = my_first_extension # Name of the extension
-DATA = my_first_extension--0.0.1.sql # SQL file containing extension objects and functions
-
-PG_CONFIG ?= pg_config # Path to the pg_config executable
-PGXS := $(shell $(PG_CONFIG) --pgxs) # Get the PostgreSQL Extension Makefile from pg_config
-include $(PGXS) # Include the PostgreSQL Extension Makefile
-```
-
----
-
-```
-make
-sudo make install
-```
-
-```
-sudo -u postgres psql
-
-# CREATE EXTENSION my_first_extension;
-CREATE EXTENSION
-
-# SELECT * FROM my_first_extension_table;
- id | my_string
-----+--------------
- 1 | Hello, World
-(1 row)
-
-# DROP EXTENSION my_first_extension;
-DROP EXTENSION
-
-# SELECT * FROM my_first_extension_table;
-ERROR: relation "my_first_extension_table" does not exist
-СТРОКА 1: SELECT * FROM my_first_extension_table;
- ^
-```
-
-------------
-
-# Add tests
-
-```
-mkdir sql
-```
-
-edit `sql/my_first_extension-main-test.sql`
-
-```
-CREATE EXTENSION my_first_extension;
-
-SELECT * FROM my_first_extension_table;
-
-DROP EXTENSION
-
--- There should be no my_first_extension_table anymore
-SELECT * FROM my_first_extension_table;
-```
-
-----
-
-change Makefile
-
-```
-EXTENSION = my_first_extension # Name of the extension
-DATA = my_first_extension--0.0.1.sql # SQL file containing extension objects and functions
-REGRESS = my_first_extension-main-test
-
-
-PG_CONFIG ?= pg_config # Path to the pg_config executable
-PGXS := $(shell $(PG_CONFIG) --pgxs) # Get the PostgreSQL Extension Makefile from pg_config
-include $(PGXS) # Include the PostgreSQL Extension Makefile
-```
-
-run `make installcheck`
-
-
-and get an error: `my_first_extension/expected/my_first_extension-main-test.out: No such file or directory`
-
-and a `results` dir.
-
-----
-
-Check that `results/my_first_extension-main-test.out` is what you expect
-
-```
-$ cat results/my_first_extension-main-test.out
-CREATE EXTENSION my_first_extension;
-SELECT * FROM my_first_extension_table;
- id | my_string
-----+--------------
- 1 | Hello, World
-(1 row)
-
-DROP EXTENSION
--- There should be no my_first_extension_table anymore
-SELECT * FROM my_first_extension_table;
-ERROR: syntax error at or near "SELECT"
-LINE 3: SELECT * FROM my_first_extension_table;
- ^
-```
-
-----
-
-If everything as you expected copy `my_first_extension-main-test.out` from `results` dir to `expected`
-
-```
-mkdir expected
-cp results/my_first_extension-main-test.out expected
-```
-
-----
-
-Now tests should pass
-
-```
-n$ make installcheck
-echo "+++ regress install-check in +++" && /usr/lib/postgresql/15/lib/pgxs/src/makefiles/../../src/test/regress/pg_regress --inputdir=./ --bindir='/usr/lib/postgresql/15/bin' --dbname=contrib_regression my_first_extension-main-test
-+++ regress install-check in +++
-(using postmaster on Unix socket, default port)
-============== dropping database "contrib_regression" ==============
-SET
-DROP DATABASE
-============== creating database "contrib_regression" ==============
-CREATE DATABASE
-ALTER DATABASE
-ALTER DATABASE
-ALTER DATABASE
-ALTER DATABASE
-ALTER DATABASE
-ALTER DATABASE
-============== running regression test queries ==============
-test my_first_extension-main-test ... ok 54 ms
-
-=====================
- All 1 tests passed.
-=====================
-```
-
------
-
-Now let's create create a new version of extension, with a plpsql function in it
-
-* Change version from `0.0.1` to `0.0.2` in `my_first_extension.control`:
-
-```
-default_version = '0.0.2'
-```
-
-* rename schema creation file from `my_first_extension--0.0.1.sql` to `my_first_extension--0.0.2.sql`
-* create an schema update file `my_first_extension--0.0.1--0.0.2.sql`
-
-Add to both of them function creation code
-
-```
-CREATE FUNCTION my_one()
-returns int
-language plpgsql
-as
-$$
-begin
- return 1;
-end;
-$$;
-
-```
-
-* Update `Makefile` adding new sql file names to `DATA` variable
-
-```
-DATA = my_first_extension--0.0.2.sql my_first_extension--0.0.1--0.0.2.sql
-```
-
-* install extension
-
-```
-sudo make install
-
-```
-
-* check everything works
-
-```
-$ sudo -u postgres psql
-
-=# CREATE EXTENSION my_first_extension;
-CREATE EXTENSION
-
-s=# SELECT my_one();
- my_one
---------
- 1
-(1 row)
-```
-
-----
-
-Write test for `my_one` function yourself
-
-----
-
-https://www.highgo.ca/2020/01/10/how-to-create-test-and-debug-an-extension-written-in-c-for-postgresql/
-
-
-Creating C-function
-
-// Do not forget to install `postgresql-server-dev-all`
-
-create `my_first_extension.c` file
-
-```
-#include "postgres.h"
-#include "fmgr.h"
-
-PG_MODULE_MAGIC;
-
-PG_FUNCTION_INFO_V1(my_get_two);
-
-Datum
-my_get_two(PG_FUNCTION_ARGS)
-{
- PG_RETURN_INT32(2);
-}
-```
-
-add following lines to `Makefile`
-
-```
-MODULE_big = my_first_extension
-OBJS = my_first_extension.o
-
-```
-and to the `my_first_extension.control`
-
-
-```
-module_pathname = '$libdir/my_first_extension'
-
-```
-
-
-Check everything works well by running
-
-```
-make
-```
-
-add to schema
-```
-CREATE FUNCTION my_two()
-RETURNS INT
-AS 'MODULE_PATHNAME', 'my_get_two'
-LANGUAGE C;
-```
-
-
-bump version in *.sql files, Makefile and control file
-
-
-```
-make
-sudo make install
-```
-
-Check everything works:
-
-```
-$ sudo -u postgres psql
-
-=# DROP EXTENSION my_first_extension;
-DROP EXTENSION
-
-=# CREATE EXTENSION my_first_extension;
-CREATE EXTENSION
-postgres=# SELECT my_two();
- my_two
---------
- 2
-(1 row)
-
-```
-
-Do not forget to write tests!
-
-
+++ /dev/null
-MODULE_big = my_first_extension
-EXTENSION = my_first_extension # Name of the extension
-DATA = my_first_extension--0.0.3.sql my_first_extension--0.0.1--0.0.2.sql my_first_extension--0.0.2--0.0.3.sql
-REGRESS = my_first_extension-main-test
-
-OBJS = my_first_extension.o
-
-
-PG_CONFIG ?= pg_config # Path to the pg_config executable
-PGXS := $(shell $(PG_CONFIG) --pgxs) # Get the PostgreSQL Extension Makefile from pg_config
-include $(PGXS) # Include the PostgreSQL Extension Makefile
-
-
+++ /dev/null
-CREATE EXTENSION my_first_extension;
-SELECT * FROM my_first_extension_table;
- id | my_string
-----+--------------
- 1 | Hello, World
-(1 row)
-
-DROP EXTENSION my_first_extension;
--- There should be no my_first_extension_table anymore
-SELECT * FROM my_first_extension_table;
-ERROR: relation "my_first_extension_table" does not exist
-LINE 1: SELECT * FROM my_first_extension_table;
- ^
+++ /dev/null
-CREATE FUNCTION my_one()
-returns int
-language plpgsql
-as
-$$
-begin
- return 1;
-end;
-$$;
-
+++ /dev/null
-CREATE FUNCTION my_two()
-RETURNS INT
-AS 'MODULE_PATHNAME', 'my_get_two'
-LANGUAGE C;
-
+++ /dev/null
-CREATE TABLE my_first_extension_table (
- id SERIAL PRIMARY KEY,
- my_string VARCHAR NOT NULL
-);
-
-INSERT INTO my_first_extension_table (my_string) VALUES('Hello, World');
-
-
-CREATE FUNCTION my_one()
-returns int
-language plpgsql
-as
-$$
-begin
- return 1;
-end;
-$$;
-
-
-CREATE FUNCTION my_two()
-RETURNS INT
-AS 'MODULE_PATHNAME', 'my_get_two'
-LANGUAGE C;
-
+++ /dev/null
-#include "postgres.h"
-#include "fmgr.h"
-
-PG_MODULE_MAGIC;
-
-PG_FUNCTION_INFO_V1(my_get_two);
-
-Datum
-my_get_two(PG_FUNCTION_ARGS)
-{
- PG_RETURN_INT32(2);
-}
+++ /dev/null
-# my_first_extension.control
-# Comment line to provide additional information about the extension
-comment = 'My Very First Extension'
-
-# Specifies the default version of the extension
-default_version = '0.0.3'
-module_pathname = '$libdir/my_first_extension'
-
+++ /dev/null
-CREATE EXTENSION my_first_extension;
-
-SELECT * FROM my_first_extension_table;
-
-DROP EXTENSION my_first_extension;
-
--- There should be no my_first_extension_table anymore
-SELECT * FROM my_first_extension_table;
-
+++ /dev/null
-MODULE_big = data_types_examples
-EXTENSION = data_types_examples # Name of the extension
-DATA = data_types_examples--0.0.1.sql
-# REGRESS = my_first_extension-main-test
-
-OBJS = data_types_examples.o warn_me.o my_factorial.o hello_world.o
-
-
-PG_CONFIG ?= pg_config # Path to the pg_config executable
-PGXS := $(shell $(PG_CONFIG) --pgxs) # Get the PostgreSQL Extension Makefile from pg_config
-include $(PGXS) # Include the PostgreSQL Extension Makefile
-
-
+++ /dev/null
-
-
-CREATE FUNCTION warn_me(int) RETURNS int
-AS 'MODULE_PATHNAME', 'warn_me'
-LANGUAGE C;
-
-
-CREATE FUNCTION my_factorial(int) RETURNS int
-AS 'MODULE_PATHNAME', 'my_factorial'
-LANGUAGE C;
-
-
-CREATE FUNCTION hello_world()
-RETURNS TEXT
-AS 'MODULE_PATHNAME', 'hello_world'
-LANGUAGE C;
-
+++ /dev/null
-#include "postgres.h"
-#include "fmgr.h"
-
-PG_MODULE_MAGIC;
-
-PG_FUNCTION_INFO_V1(my_inc);
-
-Datum
-my_inc(PG_FUNCTION_ARGS)
-{
-
- PG_RETURN_INT32(2);
-}
+++ /dev/null
-# my_first_extension.control
-# Comment line to provide additional information about the extension
-comment = 'Data Types Exampls'
-
-# Specifies the default version of the extension
-default_version = '0.0.1'
-module_pathname = '$libdir/data_types_examples'
-
+++ /dev/null
-#include "postgres.h"
-#include "fmgr.h"
-#include "utils/builtins.h"
-
-PG_FUNCTION_INFO_V1(hello_world);
-
-Datum
-hello_world(PG_FUNCTION_ARGS)
-{
- char message[] = "Hello, World!";
- Datum datum;
-
- datum = CStringGetTextDatum(message);
-
- PG_RETURN_TEXT_P(datum);
-}
-
+++ /dev/null
-#include "postgres.h"
-#include "fmgr.h"
-
-PG_FUNCTION_INFO_V1(my_factorial);
-
-Datum
-my_factorial(PG_FUNCTION_ARGS)
-{
- int32 res, n = PG_GETARG_INT32(0);
- Datum d;
-
- if (n < 0)
- elog(ERROR, "Так нельзя!");
-
- if (n == 0)
- PG_RETURN_INT32(1);
-
- d = DirectFunctionCall1(my_factorial, Int32GetDatum(n - 1));
-
- res = DatumGetInt32(d) * n;
-
- PG_RETURN_INT32(res);
-}
-
+++ /dev/null
-#include "postgres.h"
-#include "fmgr.h"
-
-PG_FUNCTION_INFO_V1(warn_me);
-
-Datum
-warn_me(PG_FUNCTION_ARGS)
-{
- int32 n = PG_GETARG_INT32(0);
- elog(WARNING, "Предупреждаю: %i", n);
- PG_RETURN_INT32(n);
-}
-
+++ /dev/null
-
-* Свободное ПО замечательно тем, что всегда можно самому посмтреть как и что устроено
-
-*Сеанс белой магии с разоблачениями*
-
-Не только знания о структуре, но и навыки работы с кодом
-
-
-## Стандартные арифметические типы
-
-Исторические причины:
-
-* Postgres95 моложе С99
-* Сколько байт займет `signed i;` ?
-
-Поэтому:
-
-```
-/* Historical names for types in <stdint.h>. */
-typedef int8_t int8;
-typedef int16_t int16;
-typedef int32_t int32;
-typedef int64_t int64;
-typedef uint8_t uint8;
-typedef uint16_t uint16;
-typedef uint32_t uint32;
-typedef uint64_t uint64;
-```
-`src/include/c.h`
-
-## Волшебные макросы pg-функций
-
-"С-Программист, помни! Макрос -- твой лучший друг!"
-
-Создание расширения начинается с вызова макроса
-
-```
-PG_MODULE_MAGIC;
-```
-
-На этом магия не заканчивается, а только начинается.
-
-// сам макрос создает функцию проверяющую совместимость подгружаемого расширения с ядрос PostgreSQL
-
-// текст макроса можно прочитать в `src/include/fmgr.h` но это для джедаев
-
-### Аргументы
-
-Вспоминаем функцию из предыдущей лекции
-
-```
-Datum
-my_get_two(PG_FUNCTION_ARGS)
-{
- PG_RETURN_INT32(2);
-}
-```
-
-Макрос `PG_FUNCTION_ARGS` разворачивается в
-
-```
-/* Standard parameter list for fmgr-compatible functions */
-#define PG_FUNCTION_ARGS FunctionCallInfo fcinfo
-```
-см. `src/include/fmgr.h`
-
----
-Структура `FunctionCallInfo` имеет развесистую структуру содержит информацию о параметрах переданных в pg-функцию, пользоваться ей напрямую затруднительно (если ты не джедай темной стороны силы)
-
-Но есть специальный набор макросов для удобной работы с аргументами pg-функции
-
----
-
-Пример использования аргумента
-
-```
-#include "postgres.h"
-#include "fmgr.h"
-
-PG_FUNCTION_INFO_V1(warn_me);
-
-Datum
-warn_me(PG_FUNCTION_ARGS)
-{
- int32 n = PG_GETARG_INT32(0);
- elog(WARNING, "Предупреждаю: %i", n);
- PG_RETURN_INT32(n);
-}
-```
-
-```
-CREATE FUNCTION warn_me(int) RETURNS int
-AS 'MODULE_PATHNAME', 'warn_me'
-LANGUAGE C;
-```
-
-Мы видим что макром `PG_GETARG_INT32` используется для получения первого аргумента.
-И этот аргумент сразу приводится к типу `int32`
-
-```
-# select warn_me(12);
-WARNING: Предупреждаю: 12
- warn_me
----------
- 12
-(1 row)
-```
-
----
-
-Посмотрим на реализацию `PG_GETARG_INT32` в `src/include/fmgr.h`:
-
-```
-/* Macros for fetching arguments of standard types */
-
-#define PG_GETARG_DATUM(n) (fcinfo->args[n].value)
-#define PG_GETARG_INT32(n) DatumGetInt32(PG_GETARG_DATUM(n))
-#define PG_GETARG_UINT32(n) DatumGetUInt32(PG_GETARG_DATUM(n))
-#define PG_GETARG_INT16(n) DatumGetInt16(PG_GETARG_DATUM(n))
-#define PG_GETARG_UINT16(n) DatumGetUInt16(PG_GETARG_DATUM(n))
-#define PG_GETARG_CHAR(n) DatumGetChar(PG_GETARG_DATUM(n))
-#define PG_GETARG_BOOL(n) DatumGetBool(PG_GETARG_DATUM(n))
-```
-
-Тут мы видим что как и все ее близницы братья `PG_GETARG_INT32` суммарно обращается к струкуре `fcinfo` о которой говорилось выше.
-
-Так же если мы проведем некоторое исследование мы узнаем что выражение `fcinfo->args[n].value` имеет тип `Datum`.
-
-И по всей видимости функция `DatumGetInt32` преобразует этот мифический пока для нас `Datum` к типу `int32`.
-
-К ним мы вернемся позже.
-
-(\*) задача со звездочкой: убедитесь самостоятельно что `fcinfo->args[n].value` имеет тип Datum
-
----
-
-Если мы обратим свой взор к макросу `PG_RETURN_INT32` в том же `src/include/fmgr.h` то там увидем схожую картину
-
-```
-/* Macros for returning results of standard types */
-
-#define PG_RETURN_DATUM(x) return (x)
-#define PG_RETURN_INT32(x) return Int32GetDatum(x)
-#define PG_RETURN_UINT32(x) return UInt32GetDatum(x)
-#define PG_RETURN_INT16(x) return Int16GetDatum(x)
-#define PG_RETURN_UINT16(x) return UInt16GetDatum(x)
-#define PG_RETURN_CHAR(x) return CharGetDatum(x)
-#define PG_RETURN_BOOL(x) return BoolGetDatum(x)
-```
-
-Только тут направление преобразование другое `Int32GetDatum` из `int32` в `Datum`
-
----
-
-Так что же такое Datum?
-
-`src/include/postgres.h`
-
-
-```
-/*
- * A Datum contains either a value of a pass-by-value type or a pointer to a
- * value of a pass-by-reference type. Therefore, we require:
- *
- * sizeof(Datum) == sizeof(void *) == 4 or 8
- *
- * The functions below and the analogous functions for other types should be used to
- * convert between a Datum and the appropriate C type.
- */
-
-typedef uintptr_t Datum;
-```
-
-`man uintptr_t`:
-
-`uintptr_t` is an unsigned integer type such that any valid (void *) value can be converted to this type and then converted back.
-
-Т.е. по сути это "машинное слово" определяемое разрядностью архитектуры.
----
-
-В случае если размер данных позволяет, значение помещается в само "машинное слово".
-В случае если размеры данных выходят за рамки "машииного слова", данные размещаются в опертивной памяти а в переменную типа Datum помещается указатель на них.
-
-`src/include/postgres.h`
-
-```
-/*
- * DatumGetInt32
- * Returns 32-bit integer value of a datum.
- */
-static inline int32
-DatumGetInt32(Datum X)
-{
- return (int32) X;
-}
-```
-
-```
-/*
- * Int32GetDatum
- * Returns datum representation for a 32-bit integer.
- */
-static inline Datum
-Int32GetDatum(int32 X)
-{
- return (Datum) X;
-}
-```
-
-Т.е. тут мы просто явно приводим тип "машинного слова" к требуемому, ничего более
-
-(***) Задача с тремя звездочками: поразмышляйте, почему `DatumGetInt32` реализована как intine функция, а не как макрос
-
----
-
-С хранением сложных типов данных в Datum мы будем резбираться на следующей лекции.
-
-А пока поиграем со стандартными типами
-
-```
-#include "postgres.h"
-#include "fmgr.h"
-
-PG_FUNCTION_INFO_V1(my_factorial);
-
-Datum
-my_factorial(PG_FUNCTION_ARGS)
-{
- int32 res, n = PG_GETARG_INT32(0);
- Datum d;
-
- if (n < 0)
- elog(ERROR, "Так нельзя!");
-
- if (n == 0)
- PG_RETURN_INT32(1);
-
- d = DirectFunctionCall1(my_factorial, Int32GetDatum(n - 1));
-
- res = DatumGetInt32(d) * n;
-
- PG_RETURN_INT32(res);
-}
-```
-
-(*) Задача со звездочкой: Посмотрите на реализацию вызова `DirectFunctionCall1`, как она устроена внутри
-
projects / articles.git / commitdiff