From d93c7dbfec3d21afe3d77d0b44c979481813c8c7 Mon Sep 17 00:00:00 2001 From: Johannes Riemenschneider Date: Wed, 10 Dec 2025 10:59:33 +0100 Subject: [PATCH 1/3] wip enum documentation --- content/references/datatypes/enums.md | 86 +++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 content/references/datatypes/enums.md diff --git a/content/references/datatypes/enums.md b/content/references/datatypes/enums.md new file mode 100644 index 0000000..0272cb9 --- /dev/null +++ b/content/references/datatypes/enums.md @@ -0,0 +1,86 @@ +# Enum types + +Just like in many programming languages, an enum type consist of a static, ordered set of labels defined by the user. +Just like in many programming languages, enum types consist of a static, ordered set of labels defined by the user. +They can be utilized to + +## Creation of Enum types + +Enum types can be created via the Create Type command. + +```sql +create type enum_name as enum (['label' [,...]]); +``` + +An example usage could look like this: + +```sql +create type importance as enum ('minor', 'major', 'critical'); +``` + +## Usage of Enum types + +```sql +create table tasks (id int, priority importance); +insert into tasks values (1, 'major'), (2, 'minor'), (3, 'critical'), (4, 'major'); +``` + +The enum labels are case sensitive, whereas the enum names are not. + +```sql +select 'mInOr'::importance; +``` +``` +ERROR: invalid input value for enum importance: "mInOr" +``` +```sql +select 'minor'::iMpOrTaNcE; +``` +``` +enum importance +--------------- +minor +``` + +## Comparison of Enum types + +Values of the same enum type are comparable. Their ordering corresponds the order in which they were listed at creation time. Values of different enum types are incomparable. Similarly, an enum cannot be compared with a builin type. + +```sql +select 'critical'::importance > 'major'::importance; +``` +``` +?column? +------- +t +``` + +```sql +select id from tasks where priority >= 'major'; +``` + +``` +id +---- +1 +3 +4 +``` + +## Deletion of Enum types + +Enum types can be removed via the Drop Type command. + +```sql +drop type [ if exists ] name; +``` +The deletion of an enum type is not possible, when any other object still depends on it. + +```sql +drop type importance; +``` + +``` +ERROR: cannot drop enum importance because other objects depend on it +``` + From 0f490c43752b6395ef257e135f8f58fba4b717d9 Mon Sep 17 00:00:00 2001 From: Johannes Riemenschneider Date: Wed, 10 Dec 2025 12:06:28 +0100 Subject: [PATCH 2/3] wip more doc --- content/references/datatypes/enums.md | 49 +++++++++++++++++++++++++-- 1 file changed, 46 insertions(+), 3 deletions(-) diff --git a/content/references/datatypes/enums.md b/content/references/datatypes/enums.md index 0272cb9..6dd8544 100644 --- a/content/references/datatypes/enums.md +++ b/content/references/datatypes/enums.md @@ -1,8 +1,7 @@ # Enum types Just like in many programming languages, an enum type consist of a static, ordered set of labels defined by the user. -Just like in many programming languages, enum types consist of a static, ordered set of labels defined by the user. -They can be utilized to +They combine the clarity of text with the compactness of numerics, when the inherent meaning of a value is more than should be encoded by a single number, but the number of possible values is relatively small. ## Creation of Enum types @@ -20,6 +19,8 @@ create type importance as enum ('minor', 'major', 'critical'); ## Usage of Enum types +Enums can be used just like any other type inside of tables, views, queries, etc. . + ```sql create table tasks (id int, priority importance); insert into tasks values (1, 'major'), (2, 'minor'), (3, 'critical'), (4, 'major'); @@ -27,12 +28,15 @@ insert into tasks values (1, 'major'), (2, 'minor'), (3, 'critical'), (4, 'major The enum labels are case sensitive, whereas the enum names are not. +This does not work: ```sql select 'mInOr'::importance; ``` ``` ERROR: invalid input value for enum importance: "mInOr" ``` + +This works: ```sql select 'minor'::iMpOrTaNcE; ``` @@ -67,12 +71,27 @@ id 4 ``` +```sql +select id from tasks where priority > 1; +``` +``` +ERROR: cannot compare enum importance and integer +``` + +```sql +create type work_status as enum ('sick', 'vacation', 'remote', 'in_office'); +select 'sick'::work_status = 'minor'::importance; +``` + +``` +ERROR: cannot compare enum work_status and enum importance +``` ## Deletion of Enum types Enum types can be removed via the Drop Type command. ```sql -drop type [ if exists ] name; +drop type [if exists] name; ``` The deletion of an enum type is not possible, when any other object still depends on it. @@ -84,3 +103,27 @@ drop type importance; ERROR: cannot drop enum importance because other objects depend on it ``` +## Alter Enum types + + These features do not exist yet, but would probably be nice to have + +### Alter Name of Enum type +The name of a type can be altered using +```sql +alter type enum_name rename to new_enum_name; +``` +[comment]: <> (For example +```sql +alter type importance to task_importance; +```) + +### Add label to Enum type +A new label can be added to an existing enum via +```sql +alter type enum_name [if not exists] add value added_enum_label; +``` + +The newly inserted enum label is the new maximum in this enum type. +If the label is already present, the insertion fails with an error. Specifying "if not exists" suppresses this error. +Unlike in postgres, inserting a new enum label between two existing labels is not possible, besides dropping the type and creating a new type with the same name. + From 38add69f5b6c97de24f7c5bac4ca681874786aca Mon Sep 17 00:00:00 2001 From: Johannes Riemenschneider Date: Wed, 10 Dec 2025 18:18:06 +0100 Subject: [PATCH 3/3] adapted enum doc --- content/references/datatypes/enums.md | 23 ++--------------------- 1 file changed, 2 insertions(+), 21 deletions(-) diff --git a/content/references/datatypes/enums.md b/content/references/datatypes/enums.md index 6dd8544..d01c4dd 100644 --- a/content/references/datatypes/enums.md +++ b/content/references/datatypes/enums.md @@ -50,14 +50,6 @@ minor Values of the same enum type are comparable. Their ordering corresponds the order in which they were listed at creation time. Values of different enum types are incomparable. Similarly, an enum cannot be compared with a builin type. -```sql -select 'critical'::importance > 'major'::importance; -``` -``` -?column? -------- -t -``` ```sql select id from tasks where priority >= 'major'; @@ -77,15 +69,6 @@ select id from tasks where priority > 1; ``` ERROR: cannot compare enum importance and integer ``` - -```sql -create type work_status as enum ('sick', 'vacation', 'remote', 'in_office'); -select 'sick'::work_status = 'minor'::importance; -``` - -``` -ERROR: cannot compare enum work_status and enum importance -``` ## Deletion of Enum types Enum types can be removed via the Drop Type command. @@ -120,10 +103,8 @@ alter type importance to task_importance; ### Add label to Enum type A new label can be added to an existing enum via ```sql -alter type enum_name [if not exists] add value added_enum_label; +alter type enum_name add value [if not exists] added_enum_label [{before|after} existing_enum_lavel]; ``` - -The newly inserted enum label is the new maximum in this enum type. +Unless a position within the sortorder is specified, the newly inserted enum label is the new maximum in this enum type. If the label is already present, the insertion fails with an error. Specifying "if not exists" suppresses this error. -Unlike in postgres, inserting a new enum label between two existing labels is not possible, besides dropping the type and creating a new type with the same name.