Support UUID and Bigint model IDs in model_has_roles via string-based model_morph_key

[tikrack]

Support UUID and Bigint in spatie/laravel-permission model_id

🐛 Problem Overview

When using spatie/laravel-permission in projects with UUID-based primary keys (such as users.id being a uuid), a type mismatch error occurs due to the default database migration assuming model_id is an unsignedBigInteger.

❌ Example Error

SQLSTATE[22P02]: Invalid text representation: 7 ERROR: 
invalid input syntax for type bigint: "01984de3-23bb-7189-9ff3-c4a343bebb33"

This happens because the default migrations define model_id (via model_morph_key) as:

$table->unsignedBigInteger($columnNames['model_morph_key']);

This causes a fatal mismatch when UUIDs are used.

---

✅ Recommended Solution

Change the column type for model_morph_key (model_id) to string instead of unsignedBigInteger.

✅ Updated Migration Snippet

Replace:

$table->unsignedBigInteger($columnNames['model_morph_key']);

With:

$table->string($columnNames['model_morph_key']); // supports UUID & bigint

This allows UUIDs like 01984de3-23bb-7189-9ff3-c4a343bebb33 and also integer-based IDs like 1 or 42.

---

💡 Why This Matters

This allows spatie/laravel-permission to:

• Work seamlessly with models using UUIDs
• Maintain compatibility with bigint-based models
• Avoid needing multiple permission tables
• Support real polymorphism across model key types

---

🧩 Alternative Options

If you're using only UUIDs, you could define the column as uuid instead:

$table->uuid($columnNames['model_morph_key']);

However, this won't support bigint IDs, so string is the most flexible option.

---

🙏 Final Note

Thanks again for the amazing package. We hope this improvement can be considered to support more Laravel use cases out-of-the-box.

@tikrack

[tikrack]

If you're open to it, I'd be happy to help make this package more flexible to support both UUID and bigint-based models out-of-the-box.

Whether through a pull request or contributing on specific parts, feel free to reach out — I'd be glad to collaborate and ensure smooth support for both ID types in future versions.

[angeljqv]

Feel free to do the PR, it would be interesting to review the solution you propose.
Don't forget ->nullable(false)

laravel-permission/tests/TestCase.php

Lines 246 to 264 in a028147

	$migration = str_replace(
	[
	'(\'id\'); // permission id',
	'(\'id\'); // role id',
	'references(\'id\') // permission id',
	'references(\'id\') // role id',
	'bigIncrements',
	'unsignedBigInteger($pivotRole)',
	'unsignedBigInteger($pivotPermission)',
	],
	[
	'(\'permission_test_id\');',
	'(\'role_test_id\');',
	'references(\'permission_test_id\')',
	'references(\'role_test_id\')',
	'uuid',
	'uuid($pivotRole)->nullable(false)',
	'uuid($pivotPermission)->nullable(false)',
	],

[tikrack]

Thank you very much
Will there be any changes to the code or not? (Is this in the feature list?)
Can I do this too and make a pull request
Is it necessary? Do you want it?

[tikrack]

@drbyte

[drbyte]

I'd welcome a PR to review your proposed approach. It'd be easier to see the big picture with actual working code.

Presently it's pretty simple to flip to UUIDs with a few changes where noted in the documentation, and it's a one-time thing.

I'm a bit reluctant to use ->string as a default on a field that should be bigint, for performance reasons. But feel free to point me to references that confirm your suggestion.

[tikrack]

Thank you for the thoughtful response! 🙏

You're absolutely right — UUID support can already be implemented via custom migrations, as noted in the docs. However, this change aims to improve the out‑of‑the‑box developer experience, especially for projects using UUIDs by default (which are increasingly common with tools like Laravel Breeze, Jetstream, and Laravel Zero).

---

✅ Why ->string() Makes Sense as a Default

• It enables true polymorphism by supporting both UUIDs (as strings) and traditional bigint-based IDs.
• Maintains backward compatibility — integer IDs like 1 or 42 still work seamlessly with a string column.
• Simplifies setup and avoids the need for migration overrides in many modern Laravel projects.

---

⚠️ Performance Considerations: What the Evidence Shows

While using string (especially plain text) for IDs has some overhead compared to numeric types, in most real-world permission tables the impact is minimal:

• A postgraduate benchmark comparing text UUIDs vs. bigint showed insertion times of 410s for text UUIDs, ~290s for UUID v7, and ~290s for bigint — showing that ordered UUIDs (v7) can match bigint performance, particularly when native UUID types are used instead of strings.:contentReference[oaicite:1]{index=1}
• However, storing UUIDs as plain text (e.g. VARCHAR(36)) can lead to larger index size, slower string comparisons, and more index fragmentation, which can degrade performance.:contentReference[oaicite:2]{index=2}
• From StackExchange: a BIGINT uses 8 bytes, while a text field with the same numeric value may require ~18 bytes; integer comparison and indexing remain faster.:contentReference[oaicite:3]{index=3}

---

✅ What I'm Proposing in the PR

I'd be glad to submit a PR that includes:

• Full backward compatibility
• A configuration flag to choose the column type (uuid, bigint, or string)
• Optional, publishable migration stubs for flexibility

Please let me know whether you’d prefer this feature to be behind a config setting or as part of a breaking change in the next major version — I'm happy to align with your package roadmap.

Thanks again for the amazing package! 🚀

[drbyte]

Thanks for the detailed reply.

I'm very much in favor of UUID (I'd use ULID as my preferred choice) as a default, with backward compatibility to autoincrementing (where relevant) integers. So I do welcome this collaborative discussion.

Since switching between int/uuid involves both schema changes and model changes (ie: add uuid trait, etc), I'm reluctant to rely on a configuration flag which might be interpreted as all-inclusive.

I'm willing to explore the dual-use string approach on the pivot table, especially with ordered UUIDs/ULID, but reluctant on the models themselves. Worth exploring and benchmarking at scale though. At least it's possible for a developer to switch it to int if they really needed it for performance reasons.

[drbyte]

Also of interest is the idea of using autoincrementing bigInt for primary key but adding a unique uuid column for lookups and public-facing use, where we use the int internally, but for all json/browser/form data the uuid is what's giving/selectable/etc. But that's probably a much larger rearchitecting project which affects userland code in big ways. But if it were as simple as adding a uuid field(column) to the roles/perms models, instead of changing all the existing tables and pivots, that may be an even more performant solution in the end.

[drbyte]

First, I think I'd like to see us create an Install command which leverages Laravel Prompts, to walk the user through existing install steps. This could probably be incorporated in the current major version without having to bump.

And then once that's in place, iterate for this present discussion by adding the opportunity to select INT vs UUID during installation, and apply the relevant migration/model changes automatically.

[tikrack]

Hi! First of all, thanks for sharing your thoughts with me — it looks like we’re heading into an interesting and technical discussion.
The idea you suggested (adding an install command) is really great and honestly seems like the best direction to go.
But I think it’s something we need to think through carefully...

[tikrack]

we can create a command like this

php artisan permission:install --uuid