From ff0c7225fbde4cc65e13fd79f5282d1d73abe711 Mon Sep 17 00:00:00 2001 From: Oleksii Sholik Date: Fri, 29 Sep 2023 23:55:47 +0300 Subject: [PATCH] Add documentation comments to the catalogued SQL functions --- .../functions/create_active_migration.sql.eex | 5 +++++ .../postgres/extension/functions/electrify.sql.eex | 10 ++++++++++ .../functions/validate_table_column_defaults.sql.eex | 3 +++ .../functions/validate_table_column_types.sql.eex | 3 +++ .../electrify.sql.eex | 10 ---------- 5 files changed, 21 insertions(+), 10 deletions(-) diff --git a/components/electric/lib/electric/postgres/extension/functions/create_active_migration.sql.eex b/components/electric/lib/electric/postgres/extension/functions/create_active_migration.sql.eex index 6c5463140a..6bd6f95871 100644 --- a/components/electric/lib/electric/postgres/extension/functions/create_active_migration.sql.eex +++ b/components/electric/lib/electric/postgres/extension/functions/create_active_migration.sql.eex @@ -1,3 +1,8 @@ +-- This function captures the "CREATE TABLE" statement for the table +-- that's being electrified and stores it in the @ddl_table, in order for it +-- to be sent over the logical replication stream to Electric and be consumed +-- by the MigrationConsumer process there. + CREATE OR REPLACE FUNCTION <%= @schema %>.create_active_migration( _txid <%= @txid_type %>, _txts timestamptz, diff --git a/components/electric/lib/electric/postgres/extension/functions/electrify.sql.eex b/components/electric/lib/electric/postgres/extension/functions/electrify.sql.eex index 71e87c7d33..746e3fd989 100644 --- a/components/electric/lib/electric/postgres/extension/functions/electrify.sql.eex +++ b/components/electric/lib/electric/postgres/extension/functions/electrify.sql.eex @@ -1,3 +1,13 @@ +-- you can call electrify using one of these variants: +-- +-- 1. `CALL electric.electrify('my_table')` +-- 2. `CALL electric.electrify('my_schema', 'my_table')` +-- 3. `CALL electric.electrify('my_schema.my_table')` +-- +-- the first two formats also support special characters in the table/schema name: +-- +-- 4. `CALL electric.electrify('My Schema', 'My Table')` + CREATE OR REPLACE PROCEDURE <%= @schema %>.electrify( name1 text, name2 text DEFAULT NULL diff --git a/components/electric/lib/electric/postgres/extension/functions/validate_table_column_defaults.sql.eex b/components/electric/lib/electric/postgres/extension/functions/validate_table_column_defaults.sql.eex index 89c8a6e598..9795c723b4 100644 --- a/components/electric/lib/electric/postgres/extension/functions/validate_table_column_defaults.sql.eex +++ b/components/electric/lib/electric/postgres/extension/functions/validate_table_column_defaults.sql.eex @@ -1,3 +1,6 @@ +-- This function validates each column of the table that's being electrified +-- and aborts electrification if any column has DEFAULT expression. + CREATE OR REPLACE FUNCTION <%= @schema %>.__validate_table_column_defaults(table_name text) RETURNS VOID AS $function$ DECLARE diff --git a/components/electric/lib/electric/postgres/extension/functions/validate_table_column_types.sql.eex b/components/electric/lib/electric/postgres/extension/functions/validate_table_column_types.sql.eex index 1e5506bd52..2283dab68e 100644 --- a/components/electric/lib/electric/postgres/extension/functions/validate_table_column_types.sql.eex +++ b/components/electric/lib/electric/postgres/extension/functions/validate_table_column_types.sql.eex @@ -1,3 +1,6 @@ +-- This function validates the type of each column of the table that's being electrified, +-- to check if the type is supported by Electric. + <% valid_column_types = ~w[ diff --git a/components/electric/lib/electric/postgres/extension/migrations/20230605141256_electrify_function/electrify.sql.eex b/components/electric/lib/electric/postgres/extension/migrations/20230605141256_electrify_function/electrify.sql.eex index eeb001ea81..73c50490ac 100644 --- a/components/electric/lib/electric/postgres/extension/migrations/20230605141256_electrify_function/electrify.sql.eex +++ b/components/electric/lib/electric/postgres/extension/migrations/20230605141256_electrify_function/electrify.sql.eex @@ -1,14 +1,4 @@ -- vim: set shiftwidth=4:tabstop=4 --- --- you can call electrify using one of these variants: --- --- 1. `CALL electric.electrify('my_table')` --- 2. `CALL electric.electrify('my_schema', 'my_table')` --- 3. `CALL electric.electrify('my_schema.my_table')` --- --- the first two formats also support special characters in the table/schema name: --- --- 4. `CALL electric.electrify('My Schema', 'My Table')` CREATE OR REPLACE FUNCTION <%= schema %>.__pg_version() RETURNS integer AS $function$ SELECT setting::int FROM pg_settings WHERE name = 'server_version_num'