feat: added simple variant of typeid that uses text type (#181)

## Summary
This creates a simple variant of typeid sql generation that generates
text type, rather than a combined type of varchar + uuid.

The reason it was done because a few database tools like SQLC were
failing to correctly recognize the type from database during generation,
plus it will make it easier for user to just copy the id's from the
table and won't have to parse them again.

## How was it tested?
I added this in Postgres Docker, and tested it there.

Author: spa5k

README.md

@@ -25,29 +25,41 @@ implementation to work – simply use the Postgres instance of your choice.
 Once you've installed the TypeID types and functions in your Postgres instance,
 you can use it as follows.
 
-To define a new type of typeid with a specific prefix use the `typeid_check` function:
+To define a new type of typeid with a specific prefix use the `typeid_
 ```sql
--- Define a `user_id` type, which is a typeid with type prefix "user".
--- Using `user_id` throughout our schema, gives us type safety by guaranteeing
--- that the type prefix is always "user".
-CREATE DOMAIN user_id AS typeid CHECK (typeid_check(value, 'user'));
+-- Define a `users` table that uses `user_id` as its primary key.
+-- We use the `typeid_generate` function to randomly generate a new typeid of the
+-- correct type for each user.
+CREATE TABLE users (
+    "id" user_id not null default typeid_generate('user'),
+    "name" text,
+    "email" text
+);
+
+-- Now we can insert new uses and have the `id` column automatically generated.
+INSERT INTO users ("name", "email") VALUES ('Alice P. Hacker', 'alice@hacker.net');
 ```
 
-You can now use the newly defined type in your tables. The `typeid_generate` function
-makes it possible to automatically a new random typeid for each row:
+Or
+
+You can use the typeid_generate_text function to generate a new typeid as a string, and not use the typeid type
 
 ```sql
 -- Define a `users` table that uses `user_id` as its primary key.
--- We use the `typeid_generate` function to randomly generate a new typeid of the
+-- We use the `typeid_generate_text` function to randomly generate a new typeid of the
 -- correct type for each user.
+-- You will need to manually add the check constraint to the column
 CREATE TABLE users (
-    "id" user_id not null default typeid_generate('user'),
+    "id" text not null default typeid_generate_text('user') CHECK (typeid_check_text(id, 'user')), 
     "name" text,
     "email" text
 );
 
 -- Now we can insert new uses and have the `id` column automatically generated.
 INSERT INTO users ("name", "email") VALUES ('Alice P. Hacker', 'alice@hacker.net');
+SELECT id FROM users;
+-- Result:
+-- "user_01hfs6amkdfem8sb6b1xmg7tq7"
 ```
 
 Note that the database internally encodes typeids as a `(prefix, uuid)` tuple. Because
@@ -68,6 +80,21 @@ SELECT typeid_print(id) AS id, "name", "email" FROM users
 WHERE id = typeid_parse('user_01h455vb4pex5vsknk084sn02q');
 ```
 
+or for the text variant
+
+```sql
+-- Insert a user with a specific typeid that might have been generated elsewhere:
+INSERT INTO users ("id", "name", "email")
+VALUES ('user_01h455vb4pex5vsknk084sn02q', 'Ben Bitdiddle', 'ben@bitdiddle.com');
+
+-- To retrieve the ids as encoded strings, just use the column:
+SELECT id AS id, "name", "email" FROM users;
+
+-- You can also use filter in a WHERE clause to filter by typeid:
+SELECT typeid_print(id) AS id, "name", "email" FROM users
+WHERE id = 'user_01h455vb4pex5vsknk084sn02q';
+```
+
 ## (Optional) Operator overload
 If you'd like to be able to do the following:
 

sql/03_typeid.sql

@@ -23,6 +23,20 @@ $$
 language plpgsql
 volatile;
 
+-- Function that generates a type_id of given type, and returns the parsed typeid as text.
+create or replace function typeid_generate_text(prefix text)
+returns text
+as $$
+begin
+  if (prefix is null) or not (prefix ~ '^[a-z]{0,63}$') then
+    raise exception 'typeid prefix must match the regular expression [a-z]{0,63}';
+  end if;
+  return typeid_print((prefix, uuid_generate_v7())::typeid);
+end
+$$
+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.
@@ -46,6 +60,29 @@ $$
 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)
+returns boolean
+as $$
+declare
+  prefix text;
+  tid typeid;
+  bytes bytea;
+  ver int;
+begin
+  tid = typeid_parse(type_id);
+  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');
+end
+$$
+language plpgsql
+immutable;
 
 -- Function that parses a string into a typeid.
 create or replace function typeid_parse(typeid_str text)

supabase/tests/03_typed_text_test.sql

@@ -0,0 +1,82 @@
+-- Start transaction and plan the tests.
+BEGIN;
+SELECT plan(7);
+
+create table tests (
+    "tid" text Check(typeid_check_text(tid, 'generated'))
+);
+-- -- Run tests for typeid_generate_text and typeid_check_text on tests table.
+
+-- - name: generate-text
+--   typeid: "generated_00000000000000000000000000"
+--   description: "Generate a typeid with a specific prefix using typeid_generate_text"
+INSERT INTO tests (tid) VALUES (typeid_generate_text('generated'));
+SELECT is(
+  typeid_check_text((SELECT tid FROM tests), 'generated'),
+  true,
+  'Generate typeid text with a specific prefix using typeid_generate_text'
+);
+
+-- - name: generate-text-invalid-prefix
+--   typeid: "12345_00000000000000000000000000"
+--   description: "Attempt to generate a typeid with an invalid prefix"
+SELECT throws_ok(
+  $$ INSERT INTO tests (tid) VALUES (typeid_generate_text('12345')); $$,
+  'typeid prefix must match the regular expression [a-z]{0,63}',
+  'Generate typeid text with an invalid prefix should throw an error'
+);
+
+-- - name: check-text-valid
+--   typeid: "generated_00000000000000000000000000"
+--   description: "Check if a generated typeid text is valid"
+INSERT INTO tests (tid) VALUES (typeid_generate_text('generated'));
+SELECT is(
+  typeid_check_text((SELECT tid FROM tests limit
+          1), 'generated'),
+  true,
+  'Check if a generated typeid text is valid using typeid_check_text'
+);
+
+-- - name: check-text-invalid-prefix
+--   typeid: "12345_00000000000000000000000000"
+--   description: "Check if a typeid text with an invalid prefix is invalid"
+-- INSERT INTO tests (tid) VALUES ('12345_00000000000000000000000000');
+SELECT throws_ok(
+  $$ INSERT into tests (tid) VALUES (typeid_parse('12345_00000000000000000000000000')); $$,
+  'typeid prefix must match the regular expression [a-z]{0,63}',
+  'Parse invalid: prefix-underscore'
+);
+
+-- - name: generate-text
+--   typeid: "generated_00000000000000000000000000"
+--   description: "Generate a typeid with a specific prefix using typeid_generate_text"
+INSERT INTO tests (tid) VALUES (typeid_generate_text('generated'));
+SELECT is(
+  typeid_check_text((SELECT tid FROM tests limit 1), 'generated'),
+  true,
+  'Generate typeid text with a specific prefix using typeid_generate_text'
+);
+
+-- - name: generate-text-invalid-prefix
+--   typeid: "12345_00000000000000000000000000"
+--   description: "Attempt to generate a typeid with an invalid prefix"
+SELECT throws_ok(
+  $$ INSERT INTO tests (tid) VALUES (typeid_generate_text('12345')); $$,
+  'typeid prefix must match the regular expression [a-z]{0,63}',
+  'Generate typeid text with an invalid prefix should throw an error'
+);
+
+-- - name: check-text-valid
+--   typeid: "generated_00000000000000000000000000"
+--   description: "Check if a generated typeid text is valid"
+INSERT INTO tests (tid) VALUES (typeid_generate_text('generated'));
+SELECT is(
+  typeid_check_text((SELECT tid FROM tests limit 1), 'generated'),
+  true,
+  'Check if a generated typeid text is valid using typeid_check_text'
+);
+
+
+-- Finish the tests and clean up.
+SELECT * FROM finish();
+ROLLBACK;