{"id":20202888,"url":"https://github.com/carderne/upid","last_synced_at":"2026-03-09T22:04:27.272Z","repository":{"id":247725820,"uuid":"824997201","full_name":"carderne/upid","owner":"carderne","description":"Unique IDs with a built-in prefix","archived":false,"fork":false,"pushed_at":"2025-05-21T11:29:17.000Z","size":75,"stargazers_count":64,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-07T14:41:37.223Z","etag":null,"topics":["database","id","uuid"],"latest_commit_sha":null,"homepage":"https://upid.rdrn.me/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/carderne.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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":"2024-07-06T13:36:31.000Z","updated_at":"2025-10-17T13:45:35.000Z","dependencies_parsed_at":"2025-01-28T15:10:35.289Z","dependency_job_id":"07eb40e8-6546-4e15-bf50-a837fc0f5cb3","html_url":"https://github.com/carderne/upid","commit_stats":null,"previous_names":["carderne/upid"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/carderne/upid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carderne%2Fupid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carderne%2Fupid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carderne%2Fupid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carderne%2Fupid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carderne","download_url":"https://codeload.github.com/carderne/upid/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carderne%2Fupid/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30314434,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T20:05:46.299Z","status":"ssl_error","status_checked_at":"2026-03-09T19:57:04.425Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["database","id","uuid"],"created_at":"2024-11-14T04:58:41.362Z","updated_at":"2026-03-09T22:04:27.266Z","avatar_url":"https://github.com/carderne.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# UPID\n\npronounced YOO-pid\n\n**aka Universally Unique Prefixed Lexicographically Sortable Identifier**\n\nThis is the spec and Python and Rust implementations for UPID. The Typescript implementation is [here](https://github.com/carderne/upid-ts).\n\nUPID is based on [ULID](https://github.com/ulid/spec) but with some modifications, inspired by [this article](https://brandur.org/nanoglyphs/026-ids) and [Stripe IDs](https://dev.to/stripe/designing-apis-for-humans-object-ids-3o5a).\n\nThe core idea is that a **meaningful prefix** is specified that is stored in a 128-bit UUID-shaped slot.\nThus a UPID is **human-readable** (like a Stripe ID), but still efficient to store, sort and index.\n\nUPID allows a prefix of up to **4 characters** (will be right-padded if shorter than 4), includes a non-wrapping timestamp with about 250 millisecond precision, and 64 bits of entropy.\n\nThis is a UPID in Python:\n```python\nupid(\"user\")            # user_2accvpp5guht4dts56je5a\n```\n\nAnd in Rust:\n```rust\nUPID::new(\"user\")      // user_2accvpp5guht4dts56je5a\n```\n\nAnd in Postgres too:\n```sql\nCREATE TABLE users (id upid NOT NULL DEFAULT gen_upid('user') PRIMARY KEY);\nINSERT INTO users DEFAULT VALUES;\nSELECT id FROM users;  -- user_2accvpp5guht4dts56je5a\n\n-- this also works\nSELECT id FROM users WHERE id = 'user_2accvpp5guht4dts56je5a';\n```\n\nPlays nice with your server code, no extra work needed:\n```python\nwith psycopg.connect(\"postgresql://...\") as conn:\n    res = conn.execute(\"SELECT id FROM users\").fetchone()\n    print(res)          # user_2accvpp5guht4dts56je5a\n```\n\n## Examples\nYou can try out the Python and Rust examples in this repository.\nThey both involve spinning up a Postgres DB and inserting a UPID as itself, as a UUID and as text.\n- [./examples/python](./examples/python)\n- [./examples/rust](./examples/rust)\n\nThere are also TypeScript examples for browser and Node (with Postgres) in the [upid-ts](https://github.com/carderne/upid-ts) repo.\n\n## Demo\nYou can give it a spin at [upid.rdrn.me](https://upid.rdrn.me/).\n\n## Benefits\n- **Context**: You'll never forget what kind of ID you're staring at. Is it a `user_` or a `prod_` or maybe a `role_`?\nYour product team will thank you, as will your API users.\n- **Compatible**: Under the hood it's just 128 bits, so you can pass it to Postgres or anything else and pretend it's a UUID.\nBut you'll know your prefix is safely waiting to remind you what it is.\n- **K-Sortable**: UPID has 256 millisecond timestamp precision.\nThis ensures data locality and while not leaking too much information about timing and ordering.\n- **Pretty**: The encoding is short, easily copy-pastable and URL-safe.\nIt uses lower-case letters, which are prettier than upper-case ones.\n\n## Implementations\n\nIf you don't have time for ASCII art, you can skip to the good stuff:\n| Language   | Link                                                    |\n| --------   | ------------------------------------------------------- |\n| Python     | [in this repo (scroll down)](#python-implementation)    |\n| Postgres   | [in this repo (scroll down)](#postgres-extension)  |\n| Rust       | [in this repo (scroll down)](#rust-implementation)      |\n| TypeScript | [carderne/upid-ts](https://github.com/carderne/upid-ts) |\n\n## Specification\nKey changes relative to ULID:\n1. Uses a modified form of [Crockford's base32](https://www.crockford.com/base32.html) that uses lower-case and includes the full alphabet (for prefix flexibility).\n2. Does not permit upper-case/lower-case to be decoded interchangeably.\n3. The text encoding is still 5 bits per base32 character.\n4. 20 bits assigned to the prefix\n5. 40 bits (down from 48) assigned to the timestamp, placed first in binary for sorting\n6. 64 bits (down from 80) for randomness\n7. 4 bits as a version specifier\n\n```elm\n    user       2accvpp5      guht4dts56je5       a\n   └────┘     └────────┘    └─────────────┘   └─────┘\n   prefix       time            random        version     total\n   4 chars      8 chars         13 chars      1 char      26 chars\n       └────────│────────────────│───────────┐  │\n                │                │           │  │\n                │                │           │  │\n             40 bits            64 bits      24 bits     128 bits\n             5 bytes            8 bytes      3 bytes      16 bytes\n             time               random       prefix+version\n```\n\n### Binary layout\n```\n 0                   1                   2                   3\n 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|                            time_high                          |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|    time_low   |                     random                    |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|                             random                            |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|     random    |                  prefix_and_version           |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n```\n\n### Collision\nRelative to ULID, the time precision is reduced from 48 to 40 bits (keeping the most significant bits, so overflow still won't occur until 10,889 AD), and the randomness reduced from 80 to 64 bits.\n\nThe timestamp precision at 40 bits is around 250 milliseconds. In order to have a 50% probability of collision with 64 bits of randomness, you would need to generate around **4 billion items per 250 millisecond window**.\n\n## Python implementation\nThis aims to be maximally simple to convey the core working of the spec.\nThe current Python implementation is entirely based on [mdomke/python-ulid](https://github.com/mdomke/python-ulid).\n\n#### Installation\n```bash\npip install upid\n```\n\n#### Usage\nRun from the CLI:\n```bash\npython -m upid user\n```\n\nUse in a program:\n```python\nfrom upid import upid\nupid(\"user\")\n```\n\nOr more explicitly:\n```python\nfrom upid import UPID\nUPID.from_prefix(\"user\")\n```\n\nOr specifying your own timestamp or datetime\n```python\nimport time, datetime\nUPID.from_prefix_and_milliseconds(\"user\", milliseconds)\nUPID.from_prefix_and_datetime(\"user\", datetime.datetime.now())\n```\n\nFrom and to a string:\n```python\nu = UPID.from_str(\"user_2accvpp5guht4dts56je5a\")\nu.to_str()        # user_2a...\n```\n\nGet stuff out:\n```python\nu.prefix     # user\nu.datetime   # 2024-07-07 ...\n```\n\nConvert to other formats:\n```python\nint(u)       # 2079795568564925668398930358940603766\nu.hex        # 01908dd6a3669b912738191ea3d61576\nu.to_uuid()  # UUID('01908dd6-a366-9b91-2738-191ea3d61576')\n```\n\n#### Development\nCode and tests are in the [py/](./py/) directory.\nUsing [Rye](https://rye.astral.sh/) for development (installation instructions at the link).\n\n```bash\n# can be run from the repo root\nrye sync\nrye run all  # or fmt/lint/check/test\n```\n\nIf you just want to have a look around, pip should also work:\n```bash\npip install -e .\n```\n\nPlease open a PR if you spot a bug or improvement!\n\n## Rust implementation\nThe current Rust implementation is based on [dylanhart/ulid-rs](https://github.com/dylanhart/ulid-rs), but using the same lookup base32 lookup method as the Python implementation.\n\n#### Installation\n```bash\ncargo add upid\n```\n\n#### Usage\n```rust\nuse upid::Upid;\nUpid::new(\"user\");\n```\n\nOr specifying your own timestamp or datetime:\n```rust\nuse std::time::SystemTime;\nUpid::from_prefix_and_milliseconds(\"user\", 1720366572288);\nUpid::from_prefix_and_datetime(\"user\", SystemTime::now());\n```\n\nFrom and to a string:\n```rust\nlet u = Upid::from_string(\"user_2accvpp5guht4dts56je5a\");\nu.to_string();\n```\n\nGet stuff out:\n```rust\nu.prefix();       // user\nu.datetime();     // 2024-07-07 ...\nu.milliseconds(); // 17203...\n```\n\nConvert to other formats:\n```rust\nu.to_bytes();\n```\n\n#### Development\nCode and tests are in the [upid_rs/](./upid_rs/) directory.\n\n```bash\ncd upid_rs\ncargo check  # or fmt/clippy/build/test/run\n```\n\nPlease open a PR if you spot a bug or improvement!\n\n## Postgres extension\nThere is also a Postgres extension built on the Rust implementation, using [pgrx](https://github.com/pgcentralfoundation/pgrx) and based on the very similar extension [pksunkara/pgx_ulid](https://github.com/pksunkara/pgx_ulid).\n\n#### Installation\nThe easiest would be to try out the Docker image [carderne/postgres-upid:16](https://hub.docker.com/r/carderne/postgres-upid), currently built for arm64 and amd64 but only for Postgres 16:\n```bash\ndocker run -e POSTGRES_HOST_AUTH_METHOD=trust -p 5432:5432 carderne/postgres-upid:16\n```\n\nYou can also grab a Linux `.deb` from the [Releases](https://github.com/carderne/upid/releases) page. This is built for Postgres 16 and amd64 only.\n\nMore architectures and versions will follow once it is out of alpha.\n\n#### Usage\n```sql\nCREATE EXTENSION upid_pg;\n\nCREATE TABLE users (\n    id   upid NOT NULL DEFAULT gen_upid('user') PRIMARY KEY,\n    name text NOT NULL\n);\n\nINSERT INTO users (name) VALUES('Bob');\n\nSELECT * FROM users;\n--              id              | name\n-- -----------------------------+------\n--  user_2accvpp5guht4dts56je5a | Bob\n```\n\nYou can get the raw `bytea` data, or the prefix or timestamp:\n```sql\nSELECT upid_to_bytea(id) FROM users;\n-- \\x019...\n\nSELECT upid_to_prefix(id) FROM users;\n-- 'user'\n\nSELECT upid_to_timestamp(id) FROM users;\n-- 2024-07-07 ...\n```\n\nYou can convert a `UPID` to a regular Postgres `UUID`:\n```sql\nSELECT upid_to_uuid(gen_upid('user'));\n```\n\nOr the reverse (although the prefix and timestamp will no longer make sense):\n```sql\nselect upid_from_uuid(gen_random_uuid());\n```\n\n#### Development\nIf you want to install it into another Postgres, you'll install pgrx and follow its [installation instructions](https://github.com/pgcentralfoundation/pgrx/blob/develop/cargo-pgrx/README.md).\nSomething like this:\n```bash\ncd upid_pg\ncargo install --locked cargo-pgrx\ncargo pgrx init\ncargo pgrx install\n```\n\nSome `cargo` commands work as normal:\n```bash\ncargo check  # or fmt/clippy\n```\n\nBut building, testing and running must be done via pgrx.\nThis will compile it into a Postgres installation, and allow an interactive session and tests there.\n\n```bash\ncargo pgrx test pg16\n# or       run\n# or       install\n```\n\n## Related work\n- [ULID](https://github.com/ulid/spec): like UPID, but without the prefix\n- [UUIDv7](https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-04.html#name-uuid-version-7): like ULID, but an IETF standard and using standard hexadecimal UUID-style (long) string encoding\n- [TypeID](https://github.com/jetify-com/typeid): a UUID with a prefix, except the prefix is separate from the 128-bit binary so must be added/stripped at some boundary (or everything stored as text)\n- [cuid2](https://github.com/paralleldrive/cuid2): only text (can't store binary), not K-Sortable (deliberately), slower (deliberately) and more random\n- [Nano ID](https://github.com/ai/nanoid): only text (can't store binary), only random, bigger alphabet (shorter string)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarderne%2Fupid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarderne%2Fupid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarderne%2Fupid/lists"}