UUID & integer keys

Choose UUID or integer authentication IDs while preserving the account and session records your Rails app already owns.

Choose the schema you need

Native UUID coverage is for PostgreSQL. The normal integer path retains SQLite and PostgreSQL support. All authentication models must use the same connection pool. Arbitrary string keys, composite keys and automatic conversion of existing tables are outside this profile.

Configure a new PostgreSQL app

Inside your application class in config/application.rb, set Rails’ generator preference before running the Rails authentication generator or AddAuth feature generators:

config.generators do |g|
  g.orm :active_record, primary_key_type: :uuid
end

Continue with the normal RubyGems installation and Rails authentication setup using AddAuth 0.5.0 or later. AddAuth honors the same setting for its email proofs, passkey credentials and ceremonies, security events, account proofs and address claims, external identities and transactions, and mobile handoffs.

Leave the setting unset for bigint IDs, or choose :bigint or :integer explicitly. This is a Rails generator option, not a setting inside AddAuth.configure. It does not enable a feature or change authentication policy.

Keep an existing app’s IDs

Follow the package upgrade procedure to add support without converting any tables. Existing UUID-user/integer-session apps can keep that schema. You may choose UUIDs for later AddAuth tables while leaving already-created tables unchanged.

Every generated migration records the chosen primary-key type as a literal. Changing Rails configuration afterward does not change that file, recreate a table or convert existing rows. Foreign keys inspect the referenced table when the migration runs; a reference to an integer session stays integer even when the new table itself has a UUID primary key.

If you generated a migration before choosing the desired type and have not applied it anywhere, review or regenerate that pending migration in your normal development workflow. Keep applied migrations intact. Do not rerun Rails’ authentication generator over customized account models.

Inspect the actual database types

After migrating your rehearsal app, open bin/rails console and run this read-only inspection:

connection = ActiveRecord::Base.connection
tables = %w[users sessions] + connection.tables.grep(/\Aadd_auth_/)
tables.sort.each do |table|
  key = connection.primary_key(table)
  column = connection.columns(table).find { |entry| entry.name == key }
  puts "#{table}.#{key}: #{column.sql_type}"
end

A new all-UUID installation reports uuid for each table. An existing app may correctly report a mixture of uuid, bigint and integer. Confirm that each user/session reference matches the referenced column, then run bin/rails add_auth:doctor and the persisted authentication journeys.

Session pages use creation time with an ID tie breaker. Pass next_cursor back unchanged as before; do not convert it to a number or depend on its contents. UUID IDs are identifiers, not session secrets. Browser and mobile authentication continue to use separate random bearer values.

If you also want to convert existing integer IDs

A gem upgrade does not require this conversion. AddAuth does not provide a generic ID-conversion command: accounts can be referenced by the rest of your application, integrations and client storage.

Handle conversion as a separate application migration. Inventory primary keys and every database, queued-job and client reference; create a stable old-to-new mapping and backfill new columns; validate ownership, uniqueness and foreign keys; then coordinate the reader/writer switch. Keep credential versions, consumed proofs and revocation state intact. Plan explicitly whether existing sessions and in-flight authentication transactions can be preserved or must be invalidated for fresh sign-in.

Rehearse the conversion and its rollback on representative data before changing production keys. Do not cast integers into UUIDs, remove constraints to bypass a mismatch, or restore an old authentication snapshot as a shortcut. Old AddAuth packages cannot safely manage UUID sessions; use a compatible reader or a forward correction after that schema change.

Resolve key and upgrade errors

Next, follow the upgrade steps or return to configuration reference.