{"id":20695438,"url":"https://github.com/jetify-com/typeid-sql","last_synced_at":"2025-10-07T07:33:13.852Z","repository":{"id":177160606,"uuid":"650813153","full_name":"jetify-com/typeid-sql","owner":"jetify-com","description":"SQL implementation TypeIDs: type-safe, K-sortable, and globally unique identifiers inspired by Stripe IDs","archived":false,"fork":false,"pushed_at":"2025-03-05T23:20:09.000Z","size":56,"stargazers_count":88,"open_issues_count":4,"forks_count":6,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-03-30T17:08:52.748Z","etag":null,"topics":["guid","postgresql","sql","typeid","uuid","uuidv7"],"latest_commit_sha":null,"homepage":"","language":"PLpgSQL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jetify-com.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-07T21:37:22.000Z","updated_at":"2025-03-24T23:34:00.000Z","dependencies_parsed_at":"2024-04-09T23:51:35.771Z","dependency_job_id":"c62b7906-c958-41b1-817b-144a13f80cc3","html_url":"https://github.com/jetify-com/typeid-sql","commit_stats":{"total_commits":17,"total_committers":7,"mean_commits":"2.4285714285714284","dds":"0.47058823529411764","last_synced_commit":"728d1fd2c9f3761ebdba588e7f08894b0b6dee11"},"previous_names":["jetpack-io/typeid-sql","jetify-com/typeid-sql"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jetify-com%2Ftypeid-sql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jetify-com%2Ftypeid-sql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jetify-com%2Ftypeid-sql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jetify-com%2Ftypeid-sql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jetify-com","download_url":"https://codeload.github.com/jetify-com/typeid-sql/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247526767,"owners_count":20953143,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["guid","postgresql","sql","typeid","uuid","uuidv7"],"created_at":"2024-11-17T00:09:26.618Z","updated_at":"2025-10-07T07:33:13.833Z","avatar_url":"https://github.com/jetify-com.png","language":"PLpgSQL","readme":"# TypeID SQL\n\n### A SQL implementation of [TypeID](https://github.com/jetify-com/typeid) using PostgreSQL.\n\n![License: Apache 2.0](https://img.shields.io/github/license/jetify-com/typeid-sql)\n\nTypeIDs are a modern, **type-safe**, globally unique identifier based on the upcoming\nUUIDv7 standard. They provide a ton of nice properties that make them a great choice\nas the primary identifiers for your data in a database, APIs, and distributed systems.\nRead more about TypeIDs in their [spec](https://github.com/jetify-com/typeid).\n\nThis particular implementation demonstrates how to use TypeIDs in a postgres database.\n\n## Installation\n\nTo use typeids in your Postgres instance, you'll need define all the\nappropriate types and functions by running the SQL scripts in this repo.\n\nWe recommend copying the SQL scripts into your migrations directory and using the\nmigration tool of your choice. For example, [Flyway](https://flywaydb.org/), or\n[Liquibase](https://www.liquibase.org/).\n\nNote that this repo is using Supabase as a way to easily start a Postgres instance\nfor development and testing, but you do **not** need to use Supabase for this\nimplementation to work – simply use the Postgres instance of your choice.\n\n## Usage\nOnce you've installed the TypeID types and functions in your Postgres instance,\nyou have two options on how to encode TypeIDs in your database.\n\n### 1. Text-based encoding\nThis encoding is more inefficient than the alternative, but it's very straight-forward\nto understand, it's easy to debug by simply inspecting the contents of your tables, and\nit works well with other tools you might be using to inspect your database.\n\nTo use it:\n+ Declare your `id` column using the `text` type.\n+ Use the `typeid_generate_text` function to generate new default values.\n+ Use the `typeid_check_text` to enforce all strings in the column are valid typeids.\n\nExample:\n\n```sql\n-- Define a `users` table that uses `user_id` as its primary key.\n-- We use the `typeid_generate_text` function to randomly generate a new typeid of the\n-- correct type for each user.\n-- We also recommend adding the check constraint to the column\nCREATE TABLE users (\n    \"id\" text not null default typeid_generate_text('user') CHECK (typeid_check_text(id, 'user')),\n    \"name\" text,\n    \"email\" text\n);\n\n-- Now we can insert new users and have the `id` column automatically generated.\nINSERT INTO users (\"name\", \"email\") VALUES ('Alice P. Hacker', 'alice@hacker.net');\nSELECT id FROM users;\n-- Result:\n-- \"user_01hfs6amkdfem8sb6b1xmg7tq7\"\n\n-- Insert a user with a specific typeid that might have been generated elsewhere:\nINSERT INTO users (\"id\", \"name\", \"email\")\nVALUES ('user_01h455vb4pex5vsknk084sn02q', 'Ben Bitdiddle', 'ben@bitdiddle.com');\n\n-- To retrieve the ids as encoded strings, just use the column:\nSELECT id AS id, \"name\", \"email\" FROM users;\n\n-- You can also use filter in a WHERE clause to filter by typeid:\nSELECT typeid_print(id) AS id, \"name\", \"email\" FROM users\nWHERE id = 'user_01h455vb4pex5vsknk084sn02q';\n```\n\n### 2. UUID-based encoding using compound types\nIn this approach, we internally encode typeids as a `(prefix, uuid)` tuple. The\nsql files in this library provide a predefined `typeid` type to represent\nsaid tuples.\n\nThe advantage of this approach is that it is a more efficient encoding because we\nstore the uuid portion of the typeid using the native `uuid` type.\n\nThe disadvanage is that it is harder to work with and debug.\n\nIf performance is a primary concern of yours, also consider using the native\n[postgres extension](https://github.com/blitss/typeid-postgres) for typeid,\nwhich exposes typeids as a \"built-in\" type.\n\nTo define a new typeid using this encoding, you can use the `typeid_check` function:\n```sql\n-- Define a `user_id` type, which is a typeid with type prefix \"user\".\n-- Using `user_id` throughout our schema, gives us type safety by guaranteeing\n-- that the type prefix is always \"user\".\nCREATE DOMAIN user_id AS typeid CHECK (typeid_check(value, 'user'));\n```\n\nYou can now use the newly defined type in your tables. The `typeid_generate` function\nmakes it possible to automatically a new random typeid for each row:\n\n```sql\n-- Define a `users` table that uses `user_id` as its primary key.\n-- We use the `typeid_generate` function to randomly generate a new typeid of the\n-- correct type for each user.\nCREATE TABLE users (\n    \"id\" user_id not null default typeid_generate('user'),\n    \"name\" text,\n    \"email\" text\n);\n\n-- Now we can insert new users and have the `id` column automatically generated.\nINSERT INTO users (\"name\", \"email\") VALUES ('Alice P. Hacker', 'alice@hacker.net');\n```\n#### Querying\nTo make it easy to query typeid tuples using the standard string representation, we\nprovide two convenience functions: `typeid_parse` and `typeid_print`, which convert\nto and from the standard string representation.\n\nExample:\n\n```sql\n-- Insert a user with a specific typeid that might have been generated elsewhere:\nINSERT INTO users (\"id\", \"name\", \"email\")\nVALUES (typeid_parse('user_01h455vb4pex5vsknk084sn02q'), 'Ben Bitdiddle', 'ben@bitdiddle.com');\n\n-- To retrieve the ids as encoded strings, use the `typeid_print` function:\nSELECT typeid_print(id) AS id, \"name\", \"email\" FROM users;\n\n-- You can also use `typeid_parse` in a WHERE clause to filter by typeid:\nSELECT typeid_print(id) AS id, \"name\", \"email\" FROM users\nWHERE id = typeid_parse('user_01h455vb4pex5vsknk084sn02q');\n```\n\n#### (Optional) Operator overload\n\nIf you'd like to be able to do the following:\n\n```sql\n-- Query directly from the DB with a serialized typeid\nSELECT * FROM users u WHERE u.id = 'user_01h455vb4pex5vsknk084sn02q';\n\n-- Result:\n-- \"(user,018962e7-3a6d-7290-b088-5c4e3bdf918c)\",Ben Bitdiddle,ben@bitdiddle.com\n```\n\nThen you can add in [the operator overload functions for typeid](https://github.com/jetify-com/typeid-sql/blob/main/sql/04_operator.sql).\n\nSome users have reported issues with the above operator when using Rails and ActiveRecord – we\nrecommend removing `COMMUTATOR` from the operator definition if you encounter issues.\n\n## Tests\n\nThe tests in [`supabase/tests/`](./supabase/tests/) are using [pgTAP](https://supabase.com/docs/guides/database/extensions/pgtap) as test runner.\n\nYou need to install the development dependencies:\n```sh\nyarn install\n```\n\nAfterwards you can run the tests with the command:\n```sh\nyarn test\n```\n\nIf you need to reset the database after changing the migrations in [`sql/`](./sql/), you can do so with the following command:\n```sh\nyarn test:reset\n```\n\nSee also [Testing Your Database](https://supabase.com/docs/guides/database/testing) for more details.\n\n## Future work (contributions welcome)\n\n-   Include examples not just for Postgres, but for other databases like MySQL as well.\n-   Consider rewriting this library as a postgres extension. It would make it possible to\n    use the standard typeid string representation without the need of extra functions.\n","funding_links":[],"categories":["PLpgSQL"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjetify-com%2Ftypeid-sql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjetify-com%2Ftypeid-sql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjetify-com%2Ftypeid-sql/lists"}