A slug is the readable part of a URL: in /posts/creme-brulee, the slug is creme-brulee. It’s made from another column (usually the title): lower case, accents removed, words joined with dashes.
In Strutvane you declare the slug once in the migration, and the ORM fills it in every time a row is created and keeps it unique.
Declaring a slug
Section titled “Declaring a slug”import { migration } from '@strutvane/framework/schema'
export default migration({ up(schema) { schema.create('posts', (t) => { t.id() t.string('title', 200) t.slug('slug').from('title') t.timestamps() }) }, down(schema) { schema.dropIfExists('posts') },})t.slug('slug') creates a unique text column called slug (255 characters unless you pass a length: t.slug('slug', 120)), and .from('title') says where its value comes from. Then:
- Run
node strut migrate. The slug column and its unique index (posts_slug_unique) are created. - Leave the model as it is: it needs nothing extra.
- Create rows without a slug; the ORM fills it in.
The smallest example
Section titled “The smallest example”const post = await Post.create({ title: 'Crème Brûlée: 100% Better!' })console.log(post.slug)What you’ll see:
creme-brulee-100-betterHow a slug is made
Section titled “How a slug is made”- Accents are removed (
é→e) and everything is lower-cased. - Every run of characters that isn’t a letter or digit becomes one
-. - Dashes at the start and end are trimmed.
- It’s shortened to fit the column, leaving room for a suffix.
- If nothing is left (a title made only of symbols, or in a script without Latin letters), the slug is
item.
| Title | Slug |
|---|---|
Hello world |
hello-world |
Crème Brûlée — 100% better |
creme-brulee-100-better |
a_b |
a-b |
!!! |
item |
When the slug is taken
Section titled “When the slug is taken”const first = await Post.create({ title: 'Launch' })const second = await Post.create({ title: 'Launch' })console.log(first.slug, second.slug)What you’ll see:
launch launch-2A third post titled “Launch” gets launch-3, and so on: Strutvane takes the next free number, so the suffix is friendly and predictable.
Behind the scenes:
- Characters like
%and_in titles are plain characters: looking for taken slugs never treats them as wildcards, soa_bandaxbdon’t block each other. - Two requests at the same moment may pick the same slug. The database’s unique index refuses the second one, and Strutvane retries it with the next number. Inside a transaction, the retry uses a savepoint, so your surrounding transaction survives.
- Soft-deleted rows keep their slug, so restoring them never clashes (a new “Launch” next to a deleted one gets
launch-2).
Unique per team
Section titled “Unique per team”On a tenant table (one with a tenant_id column, see Tenancy), slugs are unique within each tenant. Another team’s slugs are invisible and never change yours:
const a = await runWithTenant(teamA, () => Project.create({ name: 'Launch' }))const b = await runWithTenant(teamB, () => Project.create({ name: 'Launch' }))console.log(a.slug, b.slug)// → launch launch (each team gets its own "launch")When tenancy is on, t.slug() creates the unique index on (tenant_id, slug) instead of (slug), so the database agrees that two teams may both have launch. The ORM looks for taken slugs, and counts suffixes, only inside the active tenant: another team’s launch never makes yours launch-2.
Choosing a slug yourself
Section titled “Choosing a slug yourself”If you set a slug, it’s kept as you wrote it; only empty slugs are generated:
const post = Post.make()post.fill({ title: 'Our 2027 roadmap' })post.slug = 'roadmap' // your own code: kept as isawait post.save()console.log(post.slug) // → 'roadmap'To let users type a slug in a form, list slug in fillable and validate its format in your form request (lower-case letters, digits and single dashes).
Slugs stay stable
Section titled “Slugs stay stable”The slug is set when the row is created and doesn’t follow later title changes:
post.title = 'Our 2028 roadmap'await post.save()console.log(post.slug) // → still 'roadmap'Shared links, bookmarks and search results keep working. Change the slug on purpose by assigning a new value.
Finding a row by its slug
Section titled “Finding a row by its slug”const post = await Post.query().where('slug', 'creme-brulee-100-better').firstOrFail()In routes, {post:slug} does this for you and answers 404 when nothing matches (see Routing).
Common mistakes
Section titled “Common mistakes”.from() on a column that isn’t a slug
Section titled “.from() on a column that isn’t a slug”t.string('title').from('name') // compile error: only slugs have .from()Fix: declare the column with t.slug('slug').from('title').
Using the slug’s number as a count
Section titled “Using the slug’s number as a count”Why: launch-3 doesn’t mean “the third launch”: numbers are taken by deleted rows too, and a renamed post keeps its old slug.
Fix: don’t parse suffixes. If you need a stable, readable name, set the slug yourself.
The slug didn’t change when I edited the title
Section titled “The slug didn’t change when I edited the title”Why: slugs are stable on purpose, so links keep working.
Fix: assign the new slug yourself (post.slug = 'new-name'), and expect old links to break.
A user-chosen slug collides
Section titled “A user-chosen slug collides”409 ConflictWhy: a slug you set yourself is kept as is, so if it’s already taken the unique index refuses it, and the generated API answers 409.
Fix: check first with Post.query().where('slug', value).exists(), or let Strutvane generate the slug.
Next steps
Section titled “Next steps”- Search, Filters & Sorting: slugs in the generated API.
- Soft Deletes: why deleted rows keep their slug.
- Tenancy: slugs unique per team.