pg_text_semver 0.1.5

This Release
pg_text_semver 0.1.5
Date
Status
Stable
Other Releases
Abstract
PostgreSQL semantic versioning extension, with comparison functions and operators.
Description
The pg_text_semver extension offers a "semver" DOMAIN type based on Postgres' built-in "text" type.
Released By
bigsmoke
License
PostgreSQL
Resources
Special Files
Tags

Extensions

pg_safer_settings 0.1.5

README


pg_extension_name: pg_text_semver pg_extension_version: 0.1.5 pg_readme_generated_at: 2023-11-28 17:55:08.968329+00

pg_readme_version: 0.6.5

PostgreSQL semantic versioning extension: pg_text_semver

PGXN version

The pg_text_semver extension offers a semver DOMAIN type based on Postgres' built-in text type that implements the Semantic Versioning 2.0.0 Specification.

See the test__pg_text_semver() procedure for examples of how to use the types, operators and functions provides by this extension.

Alternatives to pg_text_semver

An excellent pre-existing alternative to pg_text_semver is the semver extension. semver is written in C and therefore more efficient than pg_text_semver. But, as of March 2, 2023, it treats the parts of the semantic version as 32-bit integers, while the spec prescribes no limitations to the size of each number.

Besides semver (repo name pg-semver, with a dash), there is also the older PG SEMVER (repo name pg_semver, with an underscore). The pg_text_semver author only discovered PG SEMVER after releasing his own extension, and hasn't tried it; something left to do…

Object reference

Routines

Function: pg_text_semver_meta_pgxn()

Returns the JSON meta data that has to go into the META.json file needed for PGXN—PostgreSQL Extension Network—packages.

The Makefile includes a recipe to allow the developer to: make META.json to refresh the meta file with the function's current output, including the default_version.

And indeed, pg_safer_settings can be found on PGXN: https://pgxn.org/dist/pg_safer_settings/

Function return type: jsonb

Function attributes: STABLE

Function: pg_text_semver_readme()

This function utilizes the pg_readme extension to generate a thorough README for this extension, based on the pg_catalog and the COMMENT objects found therein.

Function return type: text

Function-local settings:

  • SET search_path TO public, pg_temp
  • SET pg_readme.include_view_definitions TO true
  • SET pg_readme.include_routine_definitions_like TO {test__%}

Function: semver_cmp (semver, semver)

Function arguments:

| Arg. # | Arg. mode | Argument name | Argument type | Default expression | | ------ | ---------- | ----------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------- | | $1 | IN | | semver | | | $2 | IN | | semver | |

Function return type: integer

Function attributes: IMMUTABLE, LEAKPROOF, PARALLEL SAFE

Function: semver_eq (semver, semver)

Function arguments:

| Arg. # | Arg. mode | Argument name | Argument type | Default expression | | ------ | ---------- | ----------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------- | | $1 | IN | | semver | | | $2 | IN | | semver | |

Function return type: boolean

Function attributes: IMMUTABLE, LEAKPROOF, PARALLEL SAFE

Function: semver_gt (semver, semver)

Function arguments:

| Arg. # | Arg. mode | Argument name | Argument type | Default expression | | ------ | ---------- | ----------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------- | | $1 | IN | | semver | | | $2 | IN | | semver | |

Function return type: boolean

Function attributes: IMMUTABLE, LEAKPROOF, PARALLEL SAFE

Function: semver_lt (semver, semver)

Function arguments:

| Arg. # | Arg. mode | Argument name | Argument type | Default expression | | ------ | ---------- | ----------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------- | | $1 | IN | | semver | | | $2 | IN | | semver | |

Function return type: boolean

Function attributes: IMMUTABLE, LEAKPROOF, PARALLEL SAFE

Function: semver_parsed (semver)

Function arguments:

| Arg. # | Arg. mode | Argument name | Argument type | Default expression | | ------ | ---------- | ----------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------- | | $1 | IN | | semver | |

Function return type: semver_parsed

Function attributes: IMMUTABLE, LEAKPROOF, PARALLEL SAFE

Function: semver_prerelease_cmp (semver_prerelease, semver_prerelease)

Function arguments:

| Arg. # | Arg. mode | Argument name | Argument type | Default expression | | ------ | ---------- | ----------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------- | | $1 | IN | | semver_prerelease | | | $2 | IN | | semver_prerelease | |

Function return type: integer

Function attributes: IMMUTABLE, LEAKPROOF, PARALLEL SAFE

Function: semver_regexp (boolean)

Returns a regular expression to match or parse a semantic version string.

The regular expression is based on the official regular expression from semver.or.

Function arguments:

| Arg. # | Arg. mode | Argument name | Argument type | Default expression | | ------ | ---------- | ----------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------- | | $1 | IN | with_capture_groups$ | boolean | false |

Function return type: text

Function attributes: IMMUTABLE, LEAKPROOF, PARALLEL SAFE

Procedure: test__pg_text_semver()

Procedure-local settings:

  • SET search_path TO pg_catalog
  • SET plpgsql.check_asserts TO true
  • SET pg_readme.include_this_routine_definition TO true

``sql CREATE OR REPLACE PROCEDURE public.test__pg_text_semver() LANGUAGE plpgsql SET search_path TO 'pg_catalog' SET "plpgsql.check_asserts" TO 'true' SET "pg_readme.include_this_routine_definition" TO 'true' AS $procedure$ begin -- Because this extension is relocatable, let's update the search_path to include the extensions current -- schema (which we couldn't have done bySET search_path TO CURRENT` in the extension setup script. perform set_config('search_path', e.extnamespace::regnamespace::text || ', pg_catalog', true) from pg_extension as e where e.extname = 'pg_text_semver' ;

-- First try some valid, isolated pre-release version.
perform '0.1.a.a1-.99-e'::semver_prerelease;
perform 'a1.99-e-'::semver_prerelease;

-- Let's compare some valid pre-release versions now.
assert semver_prerelease_cmp(null, 'beta') = 1;
assert semver_prerelease_cmp(null, null) = 0;
assert semver_prerelease_cmp('same', 'same') = 0;
assert semver_prerelease_cmp('alpha', null) = -1;
assert semver_prerelease_cmp('string.180', 'string.20') = 1;
assert semver_prerelease_cmp('has.3.identifiers', 'has.3.identifiers.plus-1') = -1;
assert semver_prerelease_cmp('0.1.2.3.4', '0.1.2.3.4') = 0;
assert semver_prerelease_cmp('0.1.2.3.4.5', '0.1.2.3.4') = 1;

assert semver_parsed('1.0.0') = row('1', '0', '0', null, null)::semver_parsed;
assert semver_parsed('8.4.7-alpha') = row('8', '4', '7', 'alpha', null)::semver_parsed;
assert semver_parsed('1.0.0+commit-x') = row('1', '0', '0', null, 'commit-x')::semver_parsed;
assert semver_parsed('1.0.0-a.1+commit-y') = row('1', '0', '0', 'a.1', 'commit-y')::semver_parsed;

assert '10.0.0'::semver > '2.9.9'::semver;
assert '1.0.0-alpha'::semver < '1.0.0'::semver;
assert '8.8.8+bla'::semver = '8.8.8'::semver;
assert '8.8.8+bla'::semver = '8.8.8+bah'::semver;

end; $procedure$ ```

Types

The following extra types have been defined besides the implicit composite types of the tables and views in this extension.

Domain: semver

sql CREATE DOMAIN semver AS text CHECK ((VALUE ~ semver_regexp(false)));

Domain: semver_prerelease

sql CREATE DOMAIN semver_prerelease AS text CHECK ((VALUE ~ '^(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*$'::text));

Composite type: semver_parsed

sql CREATE TYPE semver_parsed AS ( major text, minor text, patch text, prerelease text, build text );

Authors and contributors

Colophon

This README.md for the pg_text_semver extension was automatically generated using the pg_readme PostgreSQL extension.