Improvements to typeid-sql (#203)

## Summary
Improvements to typeid-sql:
- Provide example files for both the text version and the compound
version of typeid
- Remove the UUIDv7 check, sometimes people want to store other UUIDs in
typeid format
- Rename the equality operator from `=` to `===` (and `!==`).
Unfortunately some libraries
give special meaning to `=`, and that breaks functionality like
`supabase db diff`

## How was it tested?
Ran supabase tests

Author: loreto

example/example.sql example/compound.sqlexample/example.sql renamed to example/compound.sql

@@ -1,4 +1,6 @@
--- Example of how to use typeids in your own tables.
+-- Example of how to use the compound version of typeids in your own tables.
+-- The compound version is a tuple of type (string, uuid)
+
 -- In this example we'll define a users table that uses typeids to identify users.
 
 -- Define a `user_id` type, which is a typeid with type prefix "user".

example/text.sql

@@ -0,0 +1,27 @@
+-- Example of how to use text version of typeids in your own tables.
+-- In this example we'll define a members table that uses typeids.
+
+-- Define a `member_id` type, which is a typeid with type prefix "member".
+-- Using `member_id` throughout our schema, gives us type safety by guaranteeing
+-- that the type prefix is always "member".
+create domain member_id AS text check (typeid_check_text(value, 'member'));
+
+-- Define a `members` table that uses `member_id` as its primary key.
+-- We use the `typeid_generate_text` function to randomly generate a new typeid of the
+-- correct type for each member.
+create table members (
+    "id" member_id not null default typeid_generate_text('member'),
+    "name" text,
+    "email" text
+);
+
+CREATE UNIQUE INDEX members_pkey ON members USING btree (id);
+alter table "members" add constraint "members_pkey" PRIMARY KEY using index "members_pkey";
+
+
+-- Now we can insert new uses and have the `id` column automatically generated.
+insert into members ("name", "email") values ('Alice P. Hacker', 'alice@hacker.net');
+
+-- Or you can specify the typeid yourself:
+insert into members ("id", "name", "email")
+values ('member_01h455vb4pex5vsknk084sn02q', 'Ben Bitdiddle', 'ben@bitdiddle.com');

sql/03_typeid.sql

@@ -5,7 +5,6 @@
 -- + Defines functions to generate and validate typeids in SQL.
 
 -- Create a `typeid` type.
--- Note that the "uuid" field should be a UUID v7.
 create type "typeid" as ("type" varchar(63), "uuid" uuid);
 
 -- Function that generates a random typeid of the given type.
@@ -38,47 +37,30 @@ language plpgsql
 volatile;
 
 -- Function that checks if a typeid is valid, for the given type prefix.
--- It also enforces that the UUID is a v7 UUID.
--- NOTE: we might want to make the version check optional.
 create or replace function typeid_check(tid typeid, expected_type text)
 returns boolean
 as $$
 declare
   prefix text;
-  bytes bytea;
-  ver int;
 begin
   prefix = (tid).type;
-  bytes = uuid_send((tid).uuid);
-  ver = (get_byte(bytes, 6) >> 4)::bit(4)::int;
-  -- Check that:
-  -- + The prefix matches the expected type
-  -- + The UUID version is 7 OR it's the special "nil" UUID
-  return prefix = expected_type AND (ver = 7 OR (tid).uuid = '00000000-0000-0000-0000-000000000000');
+  return prefix = expected_type;
 end
 $$
 language plpgsql
 immutable;
 
 -- Function that checks if a typeid is valid, for the given type_id in text format and type prefix, returns boolean.
--- It also enforces that the UUID is a v7 UUID.
-create or replace function typeid_check_text(type_id text, expected_type text)
+create or replace function typeid_check_text(typeid_str text, expected_type text)
 returns boolean
 as $$
 declare
   prefix text;
   tid typeid;
-  bytes bytea;
-  ver int;
 begin
-  tid = typeid_parse(type_id);
+  tid = typeid_parse(typeid_str);
   prefix = (tid).type;
-  bytes = uuid_send((tid).uuid);
-  ver = (get_byte(bytes, 6) >> 4)::bit(4)::int;
-  -- Check that:
-  -- + The prefix matches the expected type
-  -- + The UUID version is 7 OR it's the special "nil" UUID
-  return prefix = expected_type AND (ver = 7 OR (tid).uuid = '00000000-0000-0000-0000-000000000000');
+  return prefix = expected_type;
 end
 $$
 language plpgsql
@@ -138,39 +120,3 @@ end
 $$
 language plpgsql
 immutable;
-
--- Enables direct textual equality checks. This enables direct querying in pSQL without
--- having to have clients know about db column internals- e.g. using the users table
--- example in example.sql:
---
--- Query:
--- SELECT * FROM users u WHERE u.id = 'user_01h455vb4pex5vsknk084sn02q'
---
--- Result:
--- "(user,018962e7-3a6d-7290-b088-5c4e3bdf918c)",Ben Bitdiddle,ben@bitdiddle.com
---
--- Note: This also has the nice benefit of playing very well with generators
--- such as Hibernate/JPA/JDBC/r2dbc, as you'll be able to do direct equality checks
--- in repositories, such as for r2dbc:
---
--- @Query(value = "SELECT u.id, u.name, u.email FROM users u WHERE u.id = :id")
--- Mono<UserEntity> findByPassedInTypeId(@Param("id") Mono<String> typeId); // user_01h455vb4pex5vsknk084sn02q
---
--- Note: This function only has to ever be declared once, and will work for any domains that use
--- the original typeid type (e.g. this function gets called when querying for a user_id even though
--- we never explicitly override the quality operator for a user_id.
-CREATE OR REPLACE FUNCTION compare_type_id_equality(lhs_id typeid, rhs_id VARCHAR)
-    RETURNS BOOLEAN AS $$
-SELECT lhs_id = typeid_parse(rhs_id);
-$$ LANGUAGE SQL IMMUTABLE;
-
-CREATE OPERATOR = (
-    LEFTARG = typeid,
-    RIGHTARG = VARCHAR,
-    PROCEDURE = compare_type_id_equality,
-    COMMUTATOR = =,
-    NEGATOR = !=,
-    HASHES,
-    MERGES
-    );
-

sql/04_operator.sql

@@ -0,0 +1,38 @@
+
+-- Implementation of an equality operator that makes it easy to compare typeids stored
+-- as a compound tuple (prefix, uuid) against a typeid in text form.
+--
+-- This is useful so that clients can query using a textual representation of typeid.
+-- For example, using the users table in example.sql, you could write:
+--
+-- Query:
+-- SELECT * FROM users u WHERE u.id === 'user_01h455vb4pex5vsknk084sn02q'
+--
+-- Result:
+-- "(user,018962e7-3a6d-7290-b088-5c4e3bdf918c)",Ben Bitdiddle,ben@bitdiddle.com
+--
+-- Note: This also has the nice benefit of playing very well with generators
+-- such as Hibernate/JPA/JDBC/r2dbc, as you'll be able to do direct equality checks
+-- in repositories, such as for r2dbc:
+--
+-- @Query(value = "SELECT u.id, u.name, u.email FROM users u WHERE u.id === :id")
+-- Mono<UserEntity> findByPassedInTypeId(@Param("id") Mono<String> typeId); // user_01h455vb4pex5vsknk084sn02q
+--
+-- Note: This function only has to ever be declared once, and will work for any domains that use
+-- the original typeid type (e.g. this function gets called when querying for a user_id even though
+-- we never explicitly override the quality operator for a user_id.
+CREATE OR REPLACE FUNCTION typeid_eq_operator(lhs_id typeid, rhs_id VARCHAR)
+    RETURNS BOOLEAN AS $$
+SELECT lhs_id = typeid_parse(rhs_id);
+$$ LANGUAGE SQL IMMUTABLE;
+
+CREATE OPERATOR === (
+    LEFTARG = typeid,
+    RIGHTARG = VARCHAR,
+    FUNCTION = typeid_eq_operator,
+    COMMUTATOR = ===,
+    NEGATOR = !==,
+    HASHES,
+    MERGES
+    );
+

supabase/migrations/04_example.sql

@@ -0,0 +1 @@
+../../sql/04_operator.sql

supabase/migrations/04_operator.sql

@@ -0,0 +1 @@
+../../example/compound.sql

supabase/migrations/05_compound_example.sql

@@ -0,0 +1 @@
+../../example/text.sql

supabase/migrations/06_text_example.sql

@@ -3,7 +3,7 @@ BEGIN;
 SELECT plan(7);
 
 create table tests (
-    "tid" text Check(typeid_check_text(tid, 'generated'))
+    "tid" text CHECK(typeid_check_text(tid, 'generated'))
 );
 -- -- Run tests for typeid_generate_text and typeid_check_text on tests table.
 

supabase/tests/03_typed_text_test.sql supabase/tests/03_typed_text.test.sqlsupabase/tests/03_typed_text_test.sql renamed to supabase/tests/03_typed_text.test.sql

@@ -17,7 +17,7 @@ SELECT results_eq(
 );
 
 SELECT results_eq(
-  $$ SELECT typeid_print(tid) FROM tests where tid = 'test_01h455vb4pex5vsknk084sn02q' $$,
+  $$ SELECT typeid_print(tid) FROM tests where tid === 'test_01h455vb4pex5vsknk084sn02q' $$,
   ARRAY['test_01h455vb4pex5vsknk084sn02q'],
   'Can select without needing to call typeid_parse() thanks to operator overload'
 );