Migration timestamp guidance added to docs
n8n developers now have explicit instructions for naming database migrations correctly — use exact Unix millisecond timestamps, not rounded or fabricated values.
Database migrations at n8n follow a timestamp-based naming convention, but without documented guidance, developers sometimes created migration files with rounded or future timestamps. When those developers later added migrations with exact timestamps, the files appeared out of order — a subtle source of confusion.
A new section added to now spells out the rule: always use the exact Unix millisecond timestamp at creation time. Two quick methods are provided — running Date.now() in a Node REPL or using date +%s%3N in a shell — giving developers clear, copy-pasteable commands instead of guesswork.
This guidance lives alongside existing migration documentation in the @n8n/db package, where it can guide both human contributors and AI-assisted development.
View Original GitHub Description
Summary
I saw a migration on master use a rounded up "future" timestamp, which is mildly annoying if you add an exact timestamp one after and they seem out of order as a result
Adds a "Creating Migrations" section to packages/@n8n/db/AGENTS.md instructing developers and AI agents to use exact Unix millisecond timestamps (not rounded or fabricated values) when naming migration files.
Related Linear tickets, Github issues, and Community forum posts
N/A
Review / Merge checklist
- I have seen this code, I have run this code, and I take responsibility for this code.
- PR title and summary are descriptive. (conventions)
- Docs updated or follow-up ticket created.
- Tests included.
- PR Labeled with
Backport to Beta,Backport to Stable, orBackport to v1(if the PR is an urgent fix that needs to be backported)