custom_id 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dd4f65f79f9628ea3ca56ab97b1dd5916e0efc2dd3a13d441ba3e263ebaedd7e
+  data.tar.gz: f1097107e8511f05d2a8b20f4f162a0e06c6c605a387a4d7c4213b8fefa9ec0a
+SHA512:
+  metadata.gz: 87183837c3630a4f66a9630e38683d0a91de7ff28c9a0b804a95c5314131274ab063a4715f844371011334cfa0842669a262ba93038d6427dff57644ed3fe7b9
+  data.tar.gz: cc1274ae3575c48ea41e103efed632da85bd7ca090968f1b7c81fab9bbbd532c8feb008f4e72585ca930ce61d64d128de3f0293d3245d85087bbb47d960f50a6

data/AGENTS.md

@@ -0,0 +1,143 @@
+# CustomId – Agent Guide
+
+> Concise reference for AI coding agents working **on** the `custom_id` gem or
+> **with** it inside a host Rails application.
+>
+> For end-user documentation see `README.md`.
+> For LLM-optimised usage patterns see `llms/usage.md`.
+> For architecture details see `llms/overview.md`.
+
+---
+
+## What this gem does
+
+`custom_id` generates unique, prefixed, Base58 string IDs for ActiveRecord
+models – e.g. `"usr_7xKmN2pQ…"` – via a single class-macro `cid`.
+
+---
+
+## Quick integration checklist (host app)
+
+```bash
+bundle add custom_id
+rails custom_id:install      # creates config/initializers/custom_id.rb
+```
+
+After that every model inherits the `cid` macro automatically.  No `include`
+needed.
+
+---
+
+## `cid` macro signature
+
+```ruby
+cid(prefix, size: 16, related: {}, name: :id)
+```
+
+| Parameter | Type | Default | Notes |
+|-----------|------|---------|-------|
+| `prefix` | `String \| Symbol` | required | Prepended before `_`. Stored verbatim in the ID. |
+| `size` | `Integer` | `16` | Length of the random Base58 portion **after** the `_` separator. |
+| `related` | `Hash{Symbol => Integer}` | `{}` | Single-entry: `{ association_name => chars_to_borrow }`. Borrows the first N characters from the parent's ID random portion. |
+| `name` | `Symbol` | `:id` | Column to populate. Use any string column, not just the primary key. |
+
+Generated ID format: `"#{prefix}_#{shared_chars}#{random_chars}"`
+where `shared_chars.length + random_chars.length == size`.
+
+---
+
+## Rules agents must follow
+
+### Always
+- Call `cid` **after** the `belongs_to` declaration when using `related:`.
+- Use `id: :string` in migrations for tables where `cid` manages the primary key.
+- Match the `related:` key to the exact `belongs_to` association name (`:user`,
+  not `:user_id`).
+- Ensure `size > chars_to_borrow` (otherwise an `ArgumentError` is raised at
+  record creation time).
+- **MySQL + DB trigger on string PK:** always declare `cid` on the model as
+  well. MySQL's `LAST_INSERT_ID()` returns `0` for non-`AUTO_INCREMENT` columns,
+  so ActiveRecord cannot read back the trigger-generated string PK. `cid`
+  generates the ID in Ruby before INSERT so Rails includes it in the column list.
+  The trigger then acts only as a safety net for raw SQL inserts.
+
+### Never
+- Set `default:` on the id column in migrations – the gem handles generation.
+- Call `cid` more than once per column on the same class (multiple `cid` calls
+  on a class are cumulative callbacks; only the first one that finds a nil value
+  will fire, but it is confusing).
+- On **PostgreSQL or SQLite**, mix `CustomId::Concern` with a DB trigger on the
+  same table/column – pick one approach. On **MySQL**, combining both is required
+  for correct ActiveRecord behaviour (see above).
+
+---
+
+## Gem internals (working on the gem itself)
+
+### Module map
+
+| File | Responsibility |
+|------|----------------|
+| `lib/custom_id/concern.rb` | `cid` class macro + private `before_create` helpers |
+| `lib/custom_id/installer.rb` | Creates/removes `config/initializers/custom_id.rb` |
+| `lib/custom_id/railtie.rb` | Registers all `custom_id:*` rake tasks |
+| `lib/custom_id/db_extension.rb` | PostgreSQL, MySQL, and SQLite trigger-based alternative |
+| `lib/tasks/custom_id.rake` | Rake task implementations (install/uninstall + db sub-namespace) |
+
+### Rake task reference
+
+All `custom_id:db:*` tasks accept an optional `DATABASE` positional argument
+that selects a named database from `database.yml` (multi-database Rails apps).
+Omit it to use the default connection.
+
+| Task | Args | Description |
+|------|------|-------------|
+| `custom_id:install` | — | Create `config/initializers/custom_id.rb` |
+| `custom_id:uninstall` | — | Remove `config/initializers/custom_id.rb` |
+| `custom_id:db:enable_pgcrypto` | `[DATABASE]` | Enable `pgcrypto` PG extension (required before PG triggers) |
+| `custom_id:db:install_function` | `[DATABASE]` | Install shared `custom_id_base58()` function (PG/MySQL) |
+| `custom_id:db:uninstall_function` | `[DATABASE]` | Remove the shared function (PG/MySQL) |
+| `custom_id:db:add_trigger` | `[table,prefix,column,size,DATABASE]` | Install BEFORE INSERT trigger; column defaults to `id`, size to `16` |
+| `custom_id:db:remove_trigger` | `[table,column,DATABASE]` | Remove BEFORE INSERT trigger from a table |
+
+The `custom_id:db:*` tasks require the `:environment` task (Rails app booted).
+
+### Test suite
+
+```bash
+bundle exec rake test     # Minitest with SQLite in-memory
+bundle exec rubocop       # RuboCop linting
+bundle exec rake          # Both (default task)
+```
+
+Tests live in `test/custom_id/`.  Each test class uses `setup`/`teardown` to
+create and drop SQLite tables so tests are fully isolated.
+
+### Adding a new test
+
+1. Extend `Minitest::Test` inside the `CustomId` module namespace.
+2. Name the file `test/custom_id/<feature>_test.rb` (picked up by Rakefile glob).
+3. Create tables in `setup`, drop them in `teardown`.
+
+### Dependency notes
+
+- `SecureRandom.base58` is provided by `active_support/core_ext/securerandom` –
+  already required by `concern.rb`.
+- `related:` resolution uses `ActiveRecord::Reflection` – works only on proper
+  AR models with `belongs_to` defined.
+
+---
+
+## Common pitfalls
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `NOT NULL constraint failed: table.id` | String PK table, `cid` not firing | Verify `before_create` callback is registered; check `name:` param |
+| ID generated without shared prefix | `belongs_to` missing or `account_id` is nil at create time | Ensure parent is persisted and passed before child is created |
+| `ArgumentError: size must be greater than shared chars` | `size <= chars_to_borrow` | Increase `size` or reduce borrowed chars |
+| `NoMethodError: undefined method 'base58'` | `active_support/core_ext/securerandom` not loaded | Ensure `require "custom_id"` – the gem requires it automatically |
+| `NotImplementedError: CustomId::DbExtension does not support …` | `custom_id:db:*` task run against an unsupported adapter | Supported adapters: PostgreSQL, MySQL, SQLite |
+| `PG::UndefinedFunction: function gen_random_bytes` | `pgcrypto` extension not enabled | Run `rails custom_id:db:enable_pgcrypto` or add `enable_extension "pgcrypto"` to a migration |
+| `id = "0"` after `Model.create` on MySQL | Trigger sets string PK but `LAST_INSERT_ID()` returns `0` | Add `cid "prefix"` to the model – generates ID in Ruby before INSERT |
+| Column stays `nil` after `Model.create` on MySQL (non-PK trigger) | Same root cause – AR never learns the trigger-set value | Add `cid "prefix", name: :col` to the model |
+| `ArgumentError: Anonymous class is not allowed` (Rails 7.2+) | Tried to call `establish_connection` on an unnamed class | Gem internally uses `CustomId::RakeDbProxy` – no action needed; update to latest gem version if seen |

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-02-27
+
+### Added
+
+- `CustomId::Concern` with the `cid` class macro for generating prefixed Base58 string IDs
+- Support for embedding shared characters from a related model's ID (`related:` option)
+- Support for targeting a non-primary-key column (`name:` option)
+- Configurable random-portion length (`size:` option)
+- `CustomId::Installer` for creating/removing the Rails initializer
+- `CustomId::Railtie` with `custom_id:install` and `custom_id:uninstall` rake tasks
+- `CustomId::DbExtension` – optional PostgreSQL trigger-based ID generation

data/CLAUDE.md

@@ -0,0 +1,133 @@
+# CustomId – Claude Project Context
+
+> Project-level instructions and context for Claude Code when working inside
+> the `custom_id` gem repository.
+
+## Project overview
+
+`custom_id` is a Ruby gem that adds a `cid` class macro to ActiveRecord models
+for generating prefixed, Base58, Stripe-style string IDs (e.g. `"usr_7xKmN2pQ…"`).
+
+## Repository layout
+
+```
+lib/
+  custom_id.rb               # Entry point – require this in host apps
+  custom_id/
+    concern.rb               # Core: cid macro via ActiveSupport::Concern
+    installer.rb             # Manages config/initializers/custom_id.rb
+    railtie.rb               # Rails integration, exposes rake tasks
+    db_extension.rb          # Optional: PostgreSQL, MySQL, SQLite trigger-based alternative
+  tasks/
+    custom_id.rake           # rails custom_id:install / uninstall + custom_id:db:* tasks
+test/
+  test_helper.rb             # SQLite in-memory, ActiveSupport.on_load hook
+  custom_id/
+    concern_test.rb          # Tests for cid macro behaviour
+    installer_test.rb        # Tests for Installer class
+    sqlite_db_extension_test.rb  # Tests for DbExtension on SQLite
+llms/
+  overview.md                # Architecture overview for LLMs
+  usage.md                   # Usage patterns for LLMs
+AGENTS.md                    # Concise guide for AI coding agents
+CLAUDE.md                    # This file
+```
+
+## Development workflow
+
+```bash
+bundle install
+bundle exec rake test      # run Minitest suite (SQLite in-memory)
+bundle exec rubocop        # lint
+bundle exec rake           # tests + rubocop (default)
+bin/console                # IRB with gem loaded
+```
+
+## Rake tasks
+
+All `custom_id:db:*` tasks accept an optional `DATABASE` positional argument
+that selects a named database from `database.yml` (multi-database apps).
+
+| Task | Description |
+|------|-------------|
+| `rails custom_id:install` | Create `config/initializers/custom_id.rb` |
+| `rails custom_id:uninstall` | Remove `config/initializers/custom_id.rb` |
+| `rails custom_id:db:enable_pgcrypto [DATABASE]` | Enable the `pgcrypto` PG extension (required before PG triggers) |
+| `rails custom_id:db:install_function [DATABASE]` | Install `custom_id_base58()` PG/MySQL function |
+| `rails custom_id:db:uninstall_function [DATABASE]` | Remove the function |
+| `rails "custom_id:db:add_trigger[table,prefix,column,size,DATABASE]"` | Install BEFORE INSERT trigger on a table |
+| `rails "custom_id:db:remove_trigger[table,column,DATABASE]"` | Remove BEFORE INSERT trigger from a table |
+
+The `db:*` tasks require `:environment` (full Rails boot).
+
+## Code style
+
+- **Double quotes** throughout (enforced by RuboCop).
+- Frozen string literals on every file.
+- Nested module/class syntax (`module CustomId; class Concern`) preferred over
+  compact (`CustomId::Concern`).
+- Test files use `module CustomId; class XxxTest < Minitest::Test` nesting.
+- Metrics limits: `MethodLength: Max: 15`; test files are excluded from metrics.
+
+## Key design decisions
+
+1. **`cid` registers a `before_create` callback** on the calling class, not on
+   `ActiveRecord::Base`. Calling `cid` twice on the same class stacks two
+   callbacks – avoid this.
+
+2. **Collision loop**: generates a Base58 ID, checks `Model.exists?(col => id)`,
+   retries on collision. For `name: :id` this hits the PK index so it's fast;
+   for other columns an index is recommended.
+
+3. **`related:` option** resolves the association via `self.class.reflections`
+   at callback runtime (not at `cid` declaration time) – safe for STI.
+
+4. **`DbExtension`** is a pure class-method module; no AR callbacks involved.
+   It writes SQL directly via `connection.execute`. Supports **PostgreSQL**
+   (requires `pgcrypto`), **MySQL** 5.7+, and **SQLite** 3.0+.
+   The `custom_id:db:*` rake tasks are thin wrappers that delegate to its class
+   methods – they do no SQL themselves.
+
+   **MySQL + ActiveRecord string PK limitation:** MySQL's `LAST_INSERT_ID()`
+   returns `0` for non-`AUTO_INCREMENT` columns, so ActiveRecord cannot read
+   back a trigger-generated string PK. Always pair a MySQL trigger with `cid`
+   on the model. `cid` generates the ID in Ruby before INSERT (trigger fires
+   only for raw SQL). This limitation does not affect PostgreSQL or SQLite.
+
+   **Rails 7.2+ anonymous class restriction:** `establish_connection` rejects
+   classes with no name. The rake tasks use `CustomId::RakeDbProxy` (a named
+   abstract subclass created via `const_set`) to avoid this.
+
+5. **Installer is decoupled from Rails**: `CustomId::Installer` takes a
+   `Pathname` root and never references `Rails.root`, making it unit-testable
+   with a `Dir.mktmpdir`.
+
+6. **Multi-database support**: all `custom_id:db:*` rake tasks accept an
+   optional `DATABASE` positional argument. The `resolve_connection` lambda
+   uses `ActiveRecord::Base.configurations.find_db_config` to look up the
+   named config and establishes a connection via `CustomId::RakeDbProxy`
+   without replacing the global default connection.
+
+## When adding features
+
+- Add the `before_create` logic in `concern.rb` only.
+- New public class-level DSL methods belong inside `class_methods do`.
+- Private instance helpers used inside the callback belong in the `private`
+  section of `Concern` (they are mixed into the model instance).
+- Update `sig/custom_id.rbs` when adding or changing public method signatures.
+- Write Minitest tests in `test/custom_id/` before implementing (TDD).
+- Run `bundle exec rake` before committing – must be fully green.
+
+## Dependency notes
+
+- `SecureRandom.base58` comes from `active_support/core_ext/securerandom`.
+- `Array#second` and `String#first(n)` come from `activesupport`.
+- `Hash#present?` and `blank?` come from `activesupport`.
+- All three are already pulled in by the gem's declared dependencies.
+
+## Out of scope (do not add unless explicitly requested)
+
+- UUID or ULID generation – use Rails' built-in `uuid` column type for that.
+- Validation that the stored ID matches the expected pattern.
+- Automatic index creation – migrations are the developer's responsibility.
+- Support for non-ActiveRecord ORMs (Sequel, ROM, etc.).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Pawel Niemczyk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,240 @@
+# CustomId
+
+Generate unique, human-readable, prefixed string IDs for ActiveRecord models – inspired by Stripe-style identifiers like `usr_7xKmN2pQ…`.
+
+## Features
+
+* One-line `cid` macro – declare a prefix and the gem handles the rest
+* Collision-resistant loop with database uniqueness check
+* Embed shared characters from a parent model's ID for visual traceability
+* Target any string column, not just `id`. Ensure you set the column as a string primary key if using `id`.
+* Configurable random-portion length
+* Rails installer (`rails custom_id:install`) that auto-includes the concern
+* Optional **database trigger-based** alternative for DB-level enforcement (PostgreSQL, MySQL, SQLite)
+
+## Installation
+
+Add to your application's `Gemfile`:
+
+```ruby
+gem "custom_id"
+```
+
+Then run:
+
+```bash
+bundle install
+rails custom_id:install
+```
+
+The installer creates `config/initializers/custom_id.rb` which auto-includes `CustomId::Concern` into every ActiveRecord model via `ActiveSupport.on_load(:active_record)`.
+
+## Usage
+
+### Basic usage
+
+```ruby
+class User < ApplicationRecord
+  cid "usr"
+end
+
+User.create!(name: "Alice").id  # => "usr_7xKmN2pQaBcDeFgH"
+```
+
+The ID format is `<prefix>_<random>` where the random part is 16 Base58 characters by default.
+.cid by default use the `id` column as the target for generated IDs, so make sure to set it as a string primary key in your migration. Like this: `bin/rails g model Account id:string:primary_key`
+
+### Custom size
+
+```ruby
+class ApiKey < ApplicationRecord
+  cid "key", size: 32
+end
+
+ApiKey.create!.id  # => "key_Ab3xY7mN…" (32 random chars)
+```
+
+### Embed shared characters from a related model
+
+Pass `related: { association_name => chars_to_borrow }` to prefix the random portion with characters borrowed from the related model's ID. This creates visual traceability between parent and child IDs.
+
+```ruby
+class Document < ApplicationRecord
+  belongs_to :workspace
+  cid "doc", size: 24, related: { workspace: 6 }
+end
+
+# workspace.id => "wsp_ABCDEF…"
+# document.id  => "doc_ABCDEF<18 random chars>"
+```
+
+### Custom column
+
+Use `name:` to generate the ID into a non-primary-key column:
+
+```ruby
+class Article < ApplicationRecord
+  cid "art", name: :slug, size: 12
+end
+
+Article.create!(title: "Hello").slug  # => "art_aBcDeFgHiJkL"
+```
+
+The primary key is left untouched; set it as usual.
+
+### Manual include (without the Rails initializer)
+
+```ruby
+class MyModel
+  include CustomId::Concern
+  cid "my"
+end
+```
+
+## Database-side alternative (PostgreSQL, MySQL, SQLite)
+
+For applications that need IDs generated even when records are inserted via raw SQL (e.g., bulk imports, database-level ETL), `CustomId::DbExtension` installs database triggers that produce the same prefixed Base58 IDs.
+
+### Requirements
+
+* **PostgreSQL**: 9.6+ (requires `pgcrypto` extension)
+* **MySQL**: 5.7+ (uses `RANDOM_BYTES`)
+* **SQLite**: 3.0+ (uses `AFTER INSERT` trigger)
+
+### MySQL + ActiveRecord: always pair with `cid`
+
+MySQL's protocol does not expose a generated string PK back to the caller after INSERT (unlike PostgreSQL's `RETURNING`). When ActiveRecord inserts a row without an `id` value it reads `LAST_INSERT_ID()`, which returns `0` for non-`AUTO_INCREMENT` columns — so the in-memory record gets `id = "0"` even though the row in the database has the correct trigger-generated value.
+
+**Solution:** declare `cid` on the model alongside the trigger. `cid` generates the ID in Ruby *before* the INSERT, so Rails includes it in the column list and `LAST_INSERT_ID()` is never consulted. The trigger's `WHEN NEW.id IS NULL` guard makes it a no-op for AR inserts and a safety net for raw-SQL inserts.
+
+```ruby
+# model
+class Order < ApplicationRecord
+  cid "ord"   # generates id in Ruby; trigger fires only for raw SQL inserts
+end
+```
+
+```ruby
+# migration
+class CreateOrders < ActiveRecord::Migration[8.0]
+  def up
+    create_table :orders, id: :string do |t|
+      t.string :status, null: false
+      t.timestamps
+    end
+    CustomId::DbExtension.install_trigger!(connection, :orders, prefix: "ord")
+  end
+
+  def down
+    CustomId::DbExtension.uninstall_trigger!(connection, :orders)
+    drop_table :orders
+  end
+end
+```
+
+This limitation does **not** affect PostgreSQL or SQLite.
+
+### Migration example (PostgreSQL)
+
+```ruby
+class CreateUsers < ActiveRecord::Migration[7.0]
+  def up
+    enable_extension "pgcrypto"   # only needed once per database
+
+    create_table :users, id: :string do |t|
+      t.string :name, null: false
+      t.timestamps
+    end
+
+    CustomId::DbExtension.install_trigger!(connection, :users, prefix: "usr")
+  end
+
+  def down
+    CustomId::DbExtension.uninstall_trigger!(connection, :users)
+    drop_table :users
+  end
+end
+```
+
+### Trade-offs
+
+| Aspect                     | Ruby concern (`cid`)  | `DbExtension` trigger          |
+|----------------------------|-----------------------|--------------------------------|
+| Portability                | Any AR adapter        | PG, MySQL, SQLite only         |
+| Bulk / raw inserts         | IDs **not** generated | IDs **always** generated       |
+| Testability                | SQLite in-memory ok   | Needs a real DB connection     |
+| Related-model IDs          | Supported             | Not supported                  |
+| Migration needed           | No                    | Yes                            |
+| MySQL + AR id read-back    | ✅ Works              | ⚠️ Needs `cid` on model too    |
+
+## Rails installer tasks
+
+```bash
+rails custom_id:install    # create config/initializers/custom_id.rb
+rails custom_id:uninstall  # remove  config/initializers/custom_id.rb
+```
+
+## Database-side rake tasks
+
+The `custom_id:db:*` tasks manage `CustomId::DbExtension` objects from the command line without writing migration code. All tasks depend on the Rails `:environment` task.
+
+An optional `DATABASE` argument targets a specific database in a multi-database Rails app (matches the name from `database.yml`). Omit it to use the default connection.
+
+```bash
+# Enable the pgcrypto extension (PostgreSQL only – required before install_function / add_trigger)
+rails custom_id:db:enable_pgcrypto
+rails "custom_id:db:enable_pgcrypto[postgres]"       # multi-database
+
+# optional add migration
+
+```
+class EnablePgcrypto < ActiveRecord::Migration[8.1]
+  def up   = enable_extension "pgcrypto"
+  def down = disable_extension "pgcrypto"
+end
+```
+
+# Install the shared Base58 generator function (once per database)
+rails custom_id:db:install_function
+rails "custom_id:db:install_function[postgres]"       # multi-database
+
+# Remove the shared function
+rails custom_id:db:uninstall_function
+rails "custom_id:db:uninstall_function[postgres]"     # multi-database
+
+# Add a BEFORE INSERT trigger to a table (column defaults to id, size defaults to 16)
+rails "custom_id:db:add_trigger[users,usr]"
+rails "custom_id:db:add_trigger[reports,rpt,report_key,24]"
+rails "custom_id:db:add_trigger[users,usr,,,postgres]"        # multi-database, default column/size
+rails "custom_id:db:add_trigger[reports,rpt,report_key,24,postgres]"  # all options
+
+# Remove a BEFORE INSERT trigger from a table
+rails "custom_id:db:remove_trigger[users]"
+rails "custom_id:db:remove_trigger[reports,report_key]"
+rails "custom_id:db:remove_trigger[users,,postgres]"          # multi-database
+```
+
+`install_trigger!` is idempotent – it is safe to call again if the trigger already exists.
+
+> **PostgreSQL setup order:** `enable_pgcrypto` → `install_function` is handled automatically by `add_trigger`, but if you run them separately keep that order. If pgcrypto is missing you will see:
+> ```
+> error: The pgcrypto PostgreSQL extension is required but not enabled.
+>        Run: rails custom_id:db:enable_pgcrypto
+>        or add enable_extension "pgcrypto" to a migration.
+> ```
+
+## Development
+
+```bash
+bin/setup         # install dependencies
+bundle exec rake  # run tests + RuboCop
+bin/console       # interactive prompt
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/pniemczyk/custom_id.
+
+## License
+
+MIT – see [LICENSE.txt](LICENSE.txt).

data/lib/custom_id/concern.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/securerandom"
+
+module CustomId
+  # ActiveSupport::Concern that provides the +cid+ class macro for generating
+  # prefixed, collision-resistant custom string IDs for ActiveRecord models.
+  #
+  # @example Minimal usage – generate a custom primary key
+  #   class User < ApplicationRecord
+  #     include CustomId::Concern   # not needed when using the Rails initializer
+  #     cid "usr"
+  #   end
+  #
+  #   User.create!(name: "Alice").id  # => "usr_7xKmN2pQ..."
+  #
+  # @example Embedding shared characters from a related model's ID
+  #   class Document < ApplicationRecord
+  #     belongs_to :workspace
+  #     cid "doc", size: 24, related: { workspace: 6 }
+  #   end
+  #
+  #   # If workspace.id == "wsp_ABCDEF...", document.id starts with "doc_ABCDEF..."
+  #
+  # @example Using a non-primary-key column
+  #   class Article < ApplicationRecord
+  #     cid "art", name: :slug, size: 12
+  #   end
+  #
+  #   Article.create!(title: "Hello").slug  # => "art_aBcDeFgHiJkL"
+  module Concern
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Registers a +before_create+ callback that generates a prefixed Base58 ID.
+      #
+      # The generated value has the form:
+      #   "#{prefix}_#{shared_chars}#{random_chars}"
+      #
+      # where +shared_chars+ (optional) are copied from a related model's ID and
+      # +random_chars+ fills the remaining +size+ characters with Base58 noise.
+      #
+      # @param prefix  [String, Symbol]            Prefix to prepend (e.g. "usr", :doc).
+      # @param size    [Integer]                   Length of the generated portion after the
+      #                                            underscore separator (default: 16).
+      # @param related [Hash{Symbol => Integer}]   A single-entry hash of
+      #                                            { association_name => chars_to_borrow }.
+      #                                            The gem borrows the first +chars+
+      #                                            characters from the related model's ID.
+      # @param name    [Symbol]                    Attribute to assign the ID to (default: :id).
+      def cid(prefix, size: 16, related: {}, name: :id)
+        id_prefix = prefix.to_s
+
+        before_create do
+          next unless send(name).nil?
+
+          shared = resolve_shared_chars(related)
+          loop do
+            generated = build_id(id_prefix, shared, size)
+            send(:"#{name}=", generated)
+            break unless self.class.exists?(name => generated)
+          end
+        end
+      end
+    end
+
+    # ---------------------------------------------------------------------------
+    # Instance helpers (called from the before_create block)
+    # ---------------------------------------------------------------------------
+
+    private
+
+    # Returns the shared-character prefix borrowed from the related model's ID,
+    # or an empty string when +related+ is blank or the association is unset.
+    def resolve_shared_chars(related)
+      return "" unless related.present?
+
+      association_name, borrow_count = related.first
+      ref_id = related_model_id(association_name)
+      ref_id ? ref_id.split("_", 2).last.first(borrow_count) : ""
+    end
+
+    # Reads the foreign-key value for +association_name+.
+    def related_model_id(association_name)
+      reflection  = self.class.reflections[association_name.to_s]
+      foreign_key = reflection&.foreign_key.to_s
+      read_attribute(foreign_key) if foreign_key.present?
+    end
+
+    # Generates a single candidate ID from prefix, shared chars, and random noise.
+    def build_id(id_prefix, shared, size)
+      rand_size = size - shared.length
+      if rand_size < 1
+        raise ArgumentError,
+              "size (#{size}) must be greater than the number of " \
+              "shared characters (#{shared.length})"
+      end
+
+      "#{id_prefix}_#{shared}#{SecureRandom.base58(rand_size)}"
+    end
+  end
+end