@axinom/mosaic-db-common 0.10.0 → 0.11.0-rc.0

package/bin/mosaic-db.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../dist/cli').run();

package/dist/cli/commands/generate-vscode-sql-snippets.d.ts

@@ -0,0 +1,14 @@
+import { CommandModule } from 'yargs';
+/**
+ * CLI command options object.
+ */
+interface GenerateSnippetsOptions {
+    includeMultitenancySnippets: boolean;
+    snippetsFileNameWithoutExtension: string;
+}
+/**
+ * Yargs command module definition for `generate-vscode-sql-snippets` CLI script.
+ */
+export declare const generateVscodeSqlSnippets: CommandModule<unknown, GenerateSnippetsOptions>;
+export {};
+//# sourceMappingURL=generate-vscode-sql-snippets.d.ts.map

package/dist/cli/commands/generate-vscode-sql-snippets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-vscode-sql-snippets.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/generate-vscode-sql-snippets.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAEtC;;GAEG;AACH,UAAU,uBAAuB;IAC/B,2BAA2B,EAAE,OAAO,CAAC;IACrC,gCAAgC,EAAE,MAAM,CAAC;CAC1C;AAqMD;;GAEG;AACH,eAAO,MAAM,yBAAyB,EAAE,aAAa,CACnD,OAAO,EACP,uBAAuB,CAsBxB,CAAC"}

package/dist/cli/commands/generate-vscode-sql-snippets.js

@@ -0,0 +1,206 @@
+"use strict";
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateVscodeSqlSnippets = void 0;
+/* eslint-disable no-console */
+const fs_1 = require("fs");
+const path_1 = require("path");
+const readdir = require("readdirp");
+/**
+ * Colors the CLI text in green.
+ */
+const green = (text) => `\u001b[32m${text}\u001b[39m`;
+/**
+ * Colors the CLI text in red.
+ */
+const red = (text) => `\u001b[31m${text}\u001b[39m`;
+/**
+ * Returns a readable timestamp in current locale time, e.g. `[2021-05-13 13:02:12.685]`
+ */
+const getTimestamp = () => {
+    const offset = new Date().getTimezoneOffset() * 60000; //offset in milliseconds
+    const localISOTime = new Date(Date.now() - offset)
+        .toISOString()
+        .slice(0, -1)
+        .replace('T', ' ');
+    return `[${localISOTime}]`;
+};
+/**
+ * Writes generated snippets object to .vscode folder. Creates a folder if it does not exist.
+ * Returns a success message.
+ */
+const writeSourceFile = (snippetsFileName, contents) => {
+    const outDir = path_1.join(process.env.PROJECT_CWD || process.cwd(), '.vscode');
+    if (!fs_1.existsSync(outDir)) {
+        fs_1.mkdirSync(outDir, { recursive: true });
+    }
+    const filePath = path_1.join(outDir, `${snippetsFileName}.code-snippets`);
+    fs_1.writeFileSync(filePath, JSON.stringify(contents, null, 2), 'utf-8');
+    return `Success! Snippets file path: ${filePath}`;
+};
+/**
+ * Counter for potential unnamed snippets to generate temporary unique names.
+ */
+let unparsedSnippetIndex = 1;
+/**
+ * Extracts snippet name and prefix from a line that defines a function.
+ * In case it's impossible to extract - placeholder values are used and logged (which is expected to be fixed).
+ * @example `CREATE OR REPLACE FUNCTION ax_utils.raise_error(` -> `{"prefix": "ax-raise-error", "snippetName": "Raise Error (Ax Utils)"}
+ */
+const parseFunctionName = (line, snippetJson) => {
+    var _a;
+    const match = (_a = new RegExp(/CREATE OR REPLACE FUNCTION (.*)\(/i).exec(line)) === null || _a === void 0 ? void 0 : _a[1];
+    let prefix = `unnamed-snippet-${unparsedSnippetIndex}`;
+    let snippetName = `Unnamed Snippet ${unparsedSnippetIndex}`;
+    if (!match) {
+        console.log(red(`Unable to parse the name for the following snippet. Naming the snippet ${prefix} instead.`));
+        console.log(snippetJson);
+        unparsedSnippetIndex++;
+    }
+    else {
+        prefix = match;
+        const [schemaName, functionName] = match.split('.');
+        const format = (text) => text
+            .replace(/_/g, ' ')
+            .replace(/(^\w{1})|(\s+\w{1})/g, (letter) => letter.toUpperCase());
+        snippetName = `${format(functionName)} (${format(schemaName)})`;
+        prefix = `ax-${functionName.replace(/_/g, '-')}`;
+    }
+    return { prefix, snippetName };
+};
+/**
+ * Reads a file to memory as an array, where each element is a new line.
+ * Goes through the array and generates sql snippet objects based on file contents.
+ * Depends on comment conventions to work properly.
+ */
+const populateSnippets = async (filePath, snippetsObject) => {
+    const contents = fs_1.readFileSync(filePath, 'utf-8').split('\n').filter(Boolean);
+    const startTag = '/*-snippet';
+    const endTag = 'snippet-*/';
+    const funcLine = 'create or replace function';
+    let readingSnippet = false;
+    let snippetStringContents = '';
+    let snippetJson = undefined;
+    for (const line of contents) {
+        if (line.startsWith(startTag)) {
+            readingSnippet = true;
+            continue;
+        }
+        if (line.startsWith(endTag)) {
+            snippetJson = JSON.parse(snippetStringContents);
+            snippetStringContents = '';
+            readingSnippet = false;
+            continue;
+        }
+        if (snippetJson && line.toLowerCase().startsWith(funcLine)) {
+            const { prefix, snippetName } = parseFunctionName(line, snippetJson);
+            snippetJson = Object.assign({ prefix }, snippetJson); // Adds a property to the first position
+            snippetJson['scope'] = 'sql';
+            snippetsObject[snippetName] = snippetJson;
+            snippetJson = undefined;
+            continue;
+        }
+        if (readingSnippet) {
+            snippetStringContents += line;
+        }
+    }
+    return snippetsObject;
+};
+/**
+ * Reads all `.sql` files in `migrations` folder (and sub-folders), extracts snippet json objects from them, and returns a combined object with all snippets.
+ */
+const getParsedSnippets = async (dirPath, includeMultitenancySnippets) => {
+    var e_1, _a;
+    const parsedSnippets = {};
+    try {
+        for (var _b = __asyncValues(readdir(dirPath, {
+            fileFilter: '*.sql',
+        })), _c; _c = await _b.next(), !_c.done;) {
+            const { fullPath, path } = _c.value;
+            if (!includeMultitenancySnippets && path.includes('multitenancy')) {
+                continue;
+            }
+            console.log(getTimestamp(), `Parsing ${path}`);
+            await populateSnippets(fullPath, parsedSnippets);
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) await _a.call(_b);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    return parsedSnippets;
+};
+/**
+ * Reads all `.code-snippets` files in `migrations` folder (and sub-folders) and returns a combined object with all snippets.
+ * These files contain custom snippets that are not tied to any one utils or define sql function.
+ */
+const getCustomSnippets = async (dirPath, includeMultitenancySnippets) => {
+    var e_2, _a;
+    let customSnippets = {};
+    try {
+        for (var _b = __asyncValues(readdir(dirPath, {
+            fileFilter: '*.code-snippets',
+        })), _c; _c = await _b.next(), !_c.done;) {
+            const { fullPath, path } = _c.value;
+            if (!includeMultitenancySnippets && path.includes('multitenancy')) {
+                continue;
+            }
+            console.log(getTimestamp(), `Reading ${path}`);
+            const fileContents = JSON.parse(fs_1.readFileSync(fullPath, 'utf-8'));
+            customSnippets = Object.assign(Object.assign({}, customSnippets), fileContents);
+        }
+    }
+    catch (e_2_1) { e_2 = { error: e_2_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) await _a.call(_b);
+        }
+        finally { if (e_2) throw e_2.error; }
+    }
+    return customSnippets;
+};
+/**
+ * Iterates over all .sql files inside of the `migrations` folder.
+ * Parses each file based on comments and function definition conventions.
+ * Reads all .code-snippets files inside of the `migrations` folder and adds these snippets to parsed snippets.
+ * Generates or updates a VScode snippets file.
+ */
+const generate = async ({ includeMultitenancySnippets, snippetsFileNameWithoutExtension, }) => {
+    console.log(getTimestamp(), green(`Starting snippets generation!`));
+    const dirPath = path_1.resolve(__dirname, '../../../migrations');
+    const parsedSnippets = await getParsedSnippets(dirPath, includeMultitenancySnippets);
+    const customSnippets = await getCustomSnippets(dirPath, includeMultitenancySnippets);
+    const writeResult = writeSourceFile(snippetsFileNameWithoutExtension, Object.assign(Object.assign({}, parsedSnippets), customSnippets));
+    console.log(getTimestamp(), green(writeResult));
+};
+/**
+ * Yargs command module definition for `generate-vscode-sql-snippets` CLI script.
+ */
+exports.generateVscodeSqlSnippets = {
+    command: 'generate-vscode-sql-snippets',
+    describe: 'Creates or updates a mosaic sql snippets file, providing an easier way to generate database migrations.',
+    builder: (yargs) => yargs
+        .option('includeMultitenancySnippets', {
+        alias: 'm',
+        describe: 'If set to true, would also include snippets for multitenancy define functions.',
+        default: false,
+        boolean: true,
+    })
+        .option('snippetsFileNameWithoutExtension', {
+        alias: 'f',
+        describe: 'Overrides default snippets file name with a custom value. Extension `code-snippets` will be attached to this value.',
+        default: 'mosaic-sql-migrations',
+        string: true,
+    }),
+    handler: generate,
+};
+//# sourceMappingURL=generate-vscode-sql-snippets.js.map

package/dist/cli/commands/generate-vscode-sql-snippets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-vscode-sql-snippets.js","sourceRoot":"","sources":["../../../src/cli/commands/generate-vscode-sql-snippets.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/index.d.ts

@@ -0,0 +1,2 @@
+export * from './generate-vscode-sql-snippets';
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/commands/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/index.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAC"}

package/dist/cli/commands/index.js

@@ -0,0 +1,14 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./generate-vscode-sql-snippets"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cli/commands/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/commands/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,iEAA+C"}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+export declare const run: () => void;
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,GAAG,QAAO,IAOtB,CAAC"}

package/dist/cli/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = void 0;
+const yargs = require("yargs");
+const commands_1 = require("./commands");
+const run = () => {
+    yargs
+        .scriptName('mosaic-db')
+        .command(commands_1.generateVscodeSqlSnippets)
+        .demandCommand()
+        .help()
+        .epilog(`For more information, visit https://portal.axinom.com.`).argv;
+};
+exports.run = run;
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";;;AAAA,+BAA+B;AAC/B,yCAAuD;AAEhD,MAAM,GAAG,GAAG,GAAS,EAAE;IAC5B,KAAK;SACF,UAAU,CAAC,WAAW,CAAC;SACvB,OAAO,CAAC,oCAAyB,CAAC;SAClC,aAAa,EAAE;SACf,IAAI,EAAE;SACN,MAAM,CAAC,wDAAwD,CAAC,CAAC,IAAI,CAAC;AAC3E,CAAC,CAAC;AAPW,QAAA,GAAG,OAOd"}

package/migrations/README.md

@@ -43,3 +43,233 @@ They reside in their own SQL schema to which the GraphQL role does not have
 access.
 
 The define SQL functions depend on the `ax_utils` functions.
+
+## VSCode Snippets, Documentation, and Maintainability
+
+Both Utility and Define SQL functions are there to simplify creation of database
+migrations. But because they are provided as part of the library and there is no
+intellisense support in sql files - we need to also make these functions
+discoverable and provide documentation and examples to make it easier to use
+them.
+
+To help with that - we provide a way to generate a file that contains VSCode
+snippets for all relevant functions, which adds a possibility to scaffold code
+pieces in migration files and easily fill them with relevant data. There are 2
+perspectives that should be kept in mind to make this work: Library Consumer and
+Library Maintainer.
+
+For more info on custom VSCode snippets - check here:
+https://code.visualstudio.com/docs/editor/userdefinedsnippets
+
+### Library Consumer Perspective
+
+From this perspective, the following steps can be performed by the developer:
+
+- install or update `@axinom/mosaic-db-common`
+- run the cli command: `yarn mosaic-db generate-vscode-sql-snippets`
+  - if it's a multitenant service - run
+    `yarn mosaic-db generate-vscode-sql-snippets -m` to include multitenancy
+    snippets
+- This generates or updates a `.vscode/mosaic-sql-migrations.code-snippets`
+  file, which contains all sql migration code snippets that are supported by the
+  currently installed `@axinom/mosaic-db-common` version.
+  - This file shall be kept under source control.
+  - There is no need to look into the contents of this file unless you are just
+    interested.
+- go to `migrations/current.sql` or any other `.sql` file.
+- Start typing `ax-` and intellisense will show a dropdown of all available
+  snippets.
+  - Use the Arrow Up and Down keys to select different options.
+  - Documentation window will be visible with text explanation and preview of
+    generated code.
+    - If this window is not able to be viewed fully and some content are
+      hidden - its size can be changed by dragging the right-bottom corner of
+      the window.
+  - typing after `ax-` would narrow down the selection. e.g. `ax-auth` would
+    find multiple authentication-related snippets, e.g.
+    `ax-define-authentication`
+  - When fitting snippet is selected - clicking `Enter` would expand it into the
+    actual migration code and highlight properties for easier editing
+    - It is recommended to edit highlighted values and clicking `Tab` to switch
+      to the next highlighted value. Some snippets are constructed in a way to
+      modify multiple values at once in such a way, making creating the
+      resulting migrations code easier.
+
+With this, user is provided with an option to browse available snippets,
+familiarize with them using IDE intellisense capabilities, and simplify the
+process of writing migrations.
+
+### Library Maintainer Perspective
+
+To provide the user experience from the section above - files in this
+`migrations` folder must be maintained in a certain way and it's good to know
+how things work.
+
+The resulting `.vscode/mosaic-sql-migrations.code-snippets` file is generated
+based on 2 different sources (combining contents of both):
+
+- from all `.sql` files inside of the `migrations` folders and sub-folders
+  (including `before-migration` and `define`)
+- from all `.code-snippets` files inside of the `migrations` folders and
+  sub-folders, which contains ready-to-use snippets that are not related to any
+  single `ax_utils` or `ax_define` sql function. (can be related to no functions
+  or to multiple functions)
+
+To be able to generate SQL snippets from sql files - certain conventions must be
+followed when creating/modifying sql functions.
+
+In it's simplified form, the function example can look like this:
+
+```SQL
+/*-snippet
+{
+  "body": [
+    "SELECT ax_define.function_name('${1:column_name}');"
+  ],
+  "description": [
+    "Description of function that will be visible in SQL snippet"
+  ]
+}
+snippet-*/
+CREATE OR REPLACE FUNCTION ax_define.function_name(column_name text)
+  RETURNS void LANGUAGE plpgsql AS $$
+BEGIN
+  -- Function logic which is not important in this particular case
+END;
+$$;
+```
+
+The logic that generates the SQL snippet performs the following steps:
+
+- Parses the SQL file into memory and read it line by line
+- if line starts with `/*-snippet` - starts recording of lines after it
+- if line starts with `snippet-*/` - recording of lines is stopped.
+  - Content that is recorder is passed to `JSON.Parse` and converted from string
+    to json object
+- Reading of lines continues, until a line is found that starts with
+  `CREATE OR REPLACE FUNCTION`
+  - Logic reads the function schema and name and generates a json object name
+    and snippet name. For the example above, it would be
+    `Function Name (Ax Define)` and `ax-function-name`
+  - Because it's theoretically possible to have a function with same name in
+    multiple database schemas, (and we can potentially have
+    `ax_utils.function_name` - we preserve schema name in form of `(Ax Define)`
+    suffix, since json function name is the one that must be unique, snippet
+    names can have duplicates)
+- Once these steps are performed - a json snippet object is saved for this
+  function and parsing continues anew. The resulting snippet would look like
+  this:
+  - scope is always `sql` and is attached at the end of the object
+
+```JSON
+"Function Name (Ax Define)": {
+    "prefix": "ax-function-name",
+    "body": [
+      "SELECT ax_define.function_name('${1:column_name}');"
+    ],
+    "description": [
+      "Description of function that will be visible in SQL snippet"
+    ],
+    "scope": "sql"
+  },
+```
+
+As for `migrations/snippets` files - objects like the one above must be defined
+there and files are read as is and merged into resulting
+`.vscode/mosaic-sql-migrations.code-snippets` file.
+
+### Development Tips
+
+The way to develop and test the snippets code would look like this:
+
+- If you modify typescript parts of `db-common` - run `yarn dev` for continuous
+  updates that will trigger on changes.
+  - If only sql or code-snippets files are modified - no need to keep the lib
+    running.
+- Once adjustments are made - save them and run
+  `yarn mosaic-db generate-vscode-sql-snippets -m` in some backend service in
+  Navy repository (that has `@axinom/mosaic-db-common` dependency) or from Navy
+  repository root.
+- `.vscode/mosaic-sql-migrations.code-snippets` will be updated
+- go to any `.sql` file in monorepo (preferably `migrations/current.sql` in one
+  of the backend services) and test the added/updated snippet there.
+
+When maintaining comment snippet sections of sql functions, it's good to keep in
+mind, that they are fed into `JSON.Parse` as is, and therefore must be valid
+json objects. This means that if
+`yarn mosaic-db generate-vscode-sql-snippets -m` fails - chances are - json
+object is not valid.
+
+For example:
+
+- `SyntaxError: Unexpected token ] in JSON at position 1035` might signify that
+  there is an extra `,` added at the end of the last string of the array which
+  must be removed.
+- Similar error with other token value could signify that some character, for
+  example `"` must be escaped like `\"`.
+- You might have a regex inside of the snippet that end with `*/`, which will be
+  recognized as a closing tag for the comment.
+  - In such situation - either modify the regex or move the whole snippet into
+    one of the `migrations/snippets` files.
+
+Another thing to keep in mind, is that since `ax_utils` are updated on the fly
+in projects whenever a new migration is applied - extra care must be done when
+doing changes in `before-migration` files.
+
+- Do not rename parameters of `ax_utils` functions, even if function name stays
+  the same. PostgreSQL recognizes that as a breaking change.
+  - Acceptable is to rename the column and to add something like
+    `DROP FUNCTION IF EXISTS ax_utils.function_name(TEXT, TEXT, TEXT);` before
+    definition of affected function. This way, old function will be dropped and
+    new property name would be applied. (but keep the number and order of
+    parameters the same)
+- Do not just delete `ax_utils` functions. Because they can already be used by
+  some projects, they must stay, even if they are not used.
+  - Removing the snippet comment would make it harder to discover them, so that
+    might be a valid option.
+  - But modifying the snippet to indicate that ax_utils function is
+    deprecated/obsolete is a better option.
+  - The only exception to this is early stages of development, where we do not
+    have non-axinom projects and are 100% that `ax_utils` function is not used
+    in any project.
+    - And even in this case, if dropped function was already released - an
+      explicit drop statement must be added, e.g.
+
+```SQL
+-- TODO: Remove these after 01.01.2023
+DROP FUNCTION IF EXISTS ax_utils.function_name(TEXT, TEXT, TEXT);
+```
+
+The TODO comment is added to signify when this drop statement can be removed.
+Assumption is that one year is enough for for a library to be updated at least
+once for this statement to be executed in consuming services.
+
+Worse case scenario:
+
+- Someone uses the function that will be dropped in the future.
+- That someone updates the library to the latest version where this function no
+  longer exists and drop statement is present.
+- A bug is introduced and (hopefully) reported to us.
+- We provide the code version of dropped function, which can be be explicitly
+  added as a script to run before each migration is applied in affected project.
+  - example -
+    `services/video/service/migrations/after-reset/initial-define-functions.sql`,
+    but instead - use it before migrations.
+
+Also, some notes about the contents of snippets comment section:
+
+- Both body and description are string arrays to make it possible to expand both
+  sections with more text, while keeping it all on the screen.
+  - If text contents are short - both can be changed from arrays of strings to
+    just strings.
+- Snippets will be displayed differently depending on existance of `\n` inside
+  of the `description`.
+  - If it exists - line break will be added, but it is possible that text might
+    not be visible, curring it at the border of the window with `...`. In this
+    case - window must be manually resized for contents to be fully read.
+  - If `\n` is not specified - intellisense window will try to wrap the text no
+    matter the size and always keep it readable, but it might not look very
+    good.
+- Formatting capabilities of snippets documentation window is quite limited, so
+  it makes sense to always preview it after changes to make sure it is
+  acceptable. (perhaps adding a few `\n` line breaks would make it better)

package/migrations/before-migration/002-error-functions.sql

@@ -1,6 +1,24 @@
+/*-snippet
+{
+  "body": [
+    "PERFORM ax_utils.raise_error('${1:Enter your error message here.}', '${2:UNDEF}');"
+  ],
+  "description": [
+    "Raises an error with specified message, code, and optional placeholder parameter(s) for the message.",
+    "Code must be an exactly 5-character value (letters or numbers), as per PostgreSQL convention.",
+    "If you want to use custom code values, consult PostgreSQL documentation for a list of existing error codes to prevent collisions:",
+    "https://www.postgresql.org/docs/13/errcodes-appendix.html\n",
+    "'PERFORM' is used because usually, you would want to throw an error inside of the function or condition block.",
+    "If you just want to throw an error in the migration file (e.g. to test this snippet) - replace 'PERFORM' with 'SELECT'.\n",
+    "Examples:",
+    "ax_utils.raise_error('Sample error message without parameters', 'NPERR');",
+    "ax_utils.raise_error('Sample error %s with one parameters', 'OPERR', 'message');",
+    "ax_utils.raise_error('Sample error %s with %s parameters', 'TPERR', 'message', 'two');"
+   ]
+}
+snippet-*/
 CREATE OR REPLACE FUNCTION ax_utils.raise_error(
   error_message text,
-  -- error code must be exact 5 characters long (letters or numbers)
   error_code text,
   VARIADIC placeholder_values text[] DEFAULT '{}'
 ) RETURNS void