Schema & data lifecycle
Contribute collections, extend existing entities (including Builder-made ones), relate across the merged schema, and clean up safely on uninstall.
A plugin's schema contributions flow through the same unified merge pipeline as your app's own code-first schema and the Visual Schema Builder's schema. The host can read them without running your plugin, so the admin and codegen can reason about them.
Contribute new entities
import { defineCollection, text, select } from "nextly";
import { definePlugin } from "@nextlyhq/plugin-sdk";
const Redirects = defineCollection({
slug: "redirects",
fields: [
text({ name: "fromPath", required: true }),
text({ name: "toPath", required: true }),
select({
name: "type",
options: [
{ label: "301 (Permanent)", value: "permanent" },
{ label: "302 (Temporary)", value: "temporary" },
],
defaultValue: "permanent",
}),
],
});
definePlugin({
name: "@acme/nextly-plugin-redirects",
version: "1.0.0",
nextly: ">=0.0.2-alpha.63",
// ...
contributes: {
collections: [Redirects], // also: singles, fieldGroups
},
});CRUD permissions are auto-seeded per contributed collection/single. The collection is tagged with your plugin's provenance and locked from Builder editing (it's plugin-managed).
Extend existing entities
contributes.extend adds fields to an entity you don't own, by slug:
contributes: {
extend: [
{
target: "posts",
fields: [text({ name: "metaTitle" }), text({ name: "metaDescription" })],
},
// target can be an array to extend several at once
],
}extend may also target a Builder-made collection,
not just a code-first one — the extra fields materialize (a migration adds the columns)
and are present at runtime. The added fields are attributed to your plugin in provenance,
so they're cleaned up if your plugin is removed.
Extending an entity that doesn't exist in the merged schema is a fail-fast boot error — see the error reference.
Every content type, without naming them (@experimental)
A plugin that belongs on every page of a site, such as SEO, can't know the site's
collections when it is written. Give target a scope instead of slugs:
import { definePlugin, text } from "@nextlyhq/plugin-sdk";
export function seoPlugin(options: { exclude?: string[] } = {}) {
return definePlugin({
name: "@acme/nextly-plugin-seo",
version: "1.0.0",
nextly: ">=0.0.2-alpha.75",
contributes: {
extend: [
{
// Every collection and Single the site defines, except the ones
// the site lists in its own nextly.config.ts.
target: { every: ["collection", "single"], except: options.exclude },
fields: [text({ name: "metaTitle" })],
},
],
},
});
}A scope reaches:
- the collections and Singles in the site's configuration, and those made in the Schema Builder, including ones made after the plugin was installed (they get the field on the next start);
- never a plugin's own collections or Singles (yours included), Nextly's system
types such as
usersandmedia, or field groups, apart from a plugin's collection markedsiteContent: true(@experimental), one that holds the site's own content, such as Page Builder'spages; - never a type listed in
except.
A type that already has a field of the same name is left as it is and named in a warning at startup, instead of stopping the boot as a slug target does. The site keeps its own field; the plugin's field isn't added there.
Put except behind a plugin option, as above, so the site turns a type off in its
nextly.config.ts. Migrations read that file, so a type that's off before its first
migration never gets the column.
A type switched off later keeps its column and the values in it. The field stops
showing: the API, the admin and the outputs no longer have it, and a new entry saves
without it. Switch the type on again and the saved values are back. Dev push,
nextly migrate:create and nextly migrate:check all keep the column: none of them
plans a drop, and the migration records only that the type no longer has the field. A
field marked required is kept as optional while its type is off, so an entry saved
then needs no value for it. A type made in the Schema Builder takes the change when the
site next starts.
To let those values go, run nextly prune. It lists the kept columns with everything
else it would drop, and asks first; --accept-data-loss (or naming each
table.column) agrees without a prompt.
- A site without migration files (it applies its schema with dev push or
nextly db:sync): the prune drops the kept columns from the database. - A site with migration files: the prune writes a migration that drops them,
as
nextly migrate:createwould, and every environment drops them when it next runsnextly migrate. Dropping them from one database alone would leave its next migration refusing to run, since the migration history still lists the columns. The migration carries any other change your configuration has pending too, asmigrate:createdoes. A translated field's column in the type's translations table stays: a migration never drops a translations table's column, as for any field that leaves a type.
typesReachedBy(scope, types) gives the same answer to anything else that needs to
know which types a scope covers.
Which types got your field (@experimental)
A scope decides at start which types it reaches: the Schema Builder's are read then, and
a type that kept a field of its own by that name is left alone. typesExtendedBy(plugin, field) answers what the start actually did, from what it recorded, with no database read:
import { typesExtendedBy } from "@nextlyhq/plugin-sdk";
// [{ kind: "collection", slug: "posts" }, { kind: "single", slug: "homepage" }, …]
const types = typesExtendedBy("@acme/nextly-plugin-seo", "seo");A type made in the Schema Builder since the start is listed once the site starts again,
when it gets the field. An admin tab or panel section that edits the field takes
extendedWith: ["seo"], so the admin offers it on exactly those types (see the
API reference).
A plugin whose collection holds the site's own pages marks it so scopes reach it:
defineCollection({
slug: "pages",
siteContent: true,
fields: [
/* … */
],
});The plugin's other collections, such as form submissions or internal records, stay out of every scope.
Switching your fields off on a type (@experimental)
A plugin can let a person switch its fields off for one type without a schema change, from its
own settings. Contribute a service named EXTENSION_SWITCH_SERVICE that answers, for a field
your extend adds, the types it is off on now:
import { EXTENSION_SWITCH_SERVICE, type ExtensionSwitch } from "@nextlyhq/plugin-sdk";
contributes: {
services: {
[EXTENSION_SWITCH_SERVICE]: (ctx): ExtensionSwitch => ({
switchedOff: async field =>
field === "seo" ? await typesSwitchedOffInMySettings(ctx) : [],
}),
},
},The admin asks it each time it loads its workspace. On a type that is off, the field is drawn
nowhere in the type's editors (its list columns are a later step), and your contributions that carry extendedWith naming it are not
offered there. The column and every stored value stay, and the API still reads and writes them;
switch the type on again and everything is back. What the field means while it is off, in your
plugin's own outputs, is yours to decide. A switch that fails switches nothing off and is logged.
Change entities you don't own
contributes.transforms (@experimental) changes an entity another plugin or the app
declared, not only adds fields to it: an access rule, a hook list, a field's options.
Each transform receives a frozen copy of the entity and returns the new definition:
import { definePlugin } from "@nextlyhq/plugin-sdk";
export default definePlugin({
name: "@acme/nextly-plugin-public-posts",
version: "1.0.0",
nextly: ">=0.0.2-alpha.67",
dependsOn: { "@acme/nextly-plugin-blog": "^1" },
contributes: {
transforms: [
{
target: "posts", // a slug, or an array of slugs
transform: entity => ({ ...entity, access: { read: () => true } }),
},
],
},
});setup(config) cannot do this: it runs before plugins' collections, singles and
components are merged, so it never sees them. Transforms run after the merge and after
extend, in dependency order, so a plugin transforming a dependency's collection sees
it as the dependency left it. They target code-first entities, the app's and every
plugin's; a Schema Builder entity is stored data, so change it in the Builder and add
fields to it with extend. A transform naming a slug the config does not declare is
refused at boot.
A disabled plugin's transforms still run, so disabling it never changes a table, but contribute no behaviour: a hook, access rule, validator or function default they set is put back to what the entity had.
What a transform may not change
A transform hands back a whole definition, so Nextly records who put each part of an entity there and refuses, at boot, a change that isn't the transforming plugin's to make:
- Another plugin's entity needs that plugin in
dependsOn. A plugin that transforms a collection, Single or component another plugin declares must list that plugin independsOn(notoptionalDependsOn), so the owner can't be uninstalled while the change depends on it. The app's own entities need no dependency. - A plugin's entity keeps its slug and its tables. A transform can't rename it,
delete it, move it to another
dbName, or change itsstatusorlocalizedsetting, which add the status column and the translations table its owner's data sits in, or remove a unique compound index from itsindexes. While another plugin has added a field to an entity, not even its owner's transform, nor a transform of the app's entity, may change itsdbName,statusorlocalized: that plugin's stored values live there too. - A field keeps its storage unless its declarer changes it. Removing a field, or
changing how it's stored (its type, column, size, whether it's
requiredorunique, whether it holds one value or a list (hasMany, a field group'srepeatable), its relation target, whether it's translated, or, for a field stored as JSON such as a group or repeater, or apasswordfield, its type), is refused for a field another plugin declared: the owner's own fields, and fields a third plugin added withextendor its own transform, whatever the transforming plugin depends on. A field inside a group or repeater is protected the same way. Labels, descriptions, select options, a plainindexand the like may change. The app's own fields stay open to plugins that reshape them. - A third plugin's access rules, hooks, admin settings and functions stay, a
validator, a function default or a function nested in a setting such as
preview.urlamong them. The owner's may be replaced by any plugin allowed to transform the entity; one a third plugin contributed, to the entity or to a field, only by a plugin that lists that third plugin independsOn. That includes moving or repeating its hooks, since each hook is handed what the one before it returned. - The result passes the entity's own validation. A transform can't set what
defineCollection,defineSingleordefineFieldGroupwould refuse, such asdb: { idType: "serial" }. The refusal names the plugin.
The refusals are listed in the error reference.
Migrations & databases
A plugin doesn't write SQL or manage tables itself — it declares schema through
contributes, and the host materializes it through the normal Nextly migration workflow:
nextly migrate # generate + apply migrations for the merged schema (incl. plugins)When a consuming app adds your plugin (or you change your contributed schema) and runs
nextly migrate, the plugin's collections and extend fields are folded into the merged
schema and turned into migrations alongside the app's own. The same plugin works across
Nextly's supported databases (PostgreSQL, MySQL, SQLite) because it goes through the
managed pipeline rather than dialect-specific SQL — but SQLite doesn't enforce some
constraints that Postgres/MySQL do, so test against a real database too (see
Testing).
Schema changes are applied on
migrate, not silently at boot — first boot only creates missing tables; it never alters an existing one. Ship schema changes as migrations so existing installs pick them up.
Relate across the merged schema
A plugin relationship (relationship(...)) may target any slug in the merged schema
— core (users, media), another plugin's collection, an app collection, or a
Builder-made one. Targets are validated at boot; an unknown relationTo fails
fast.
Reference your own slugs via ctx.self
Never hardcode your own collection slugs in init/handlers — an integrator can rename
them with plugin.rename({...}). Read the resolved slug from ctx.self:
const slug = ctx.self.collections.redirects; // resolved, post-rename
await ctx.services.collections.listEntries(slug, {}, { as: "system" });
declare const ctx: PluginContext;
import type { PluginContext } from "@nextlyhq/plugin-sdk";Provenance
Every schema entity carries a source: "code", "ui" (Builder), "built-in", or
"plugin:<name>". This is what makes uninstall safe — Nextly knows which tables, fields,
and permissions belong to which plugin, and never touches the user's own (code/ui)
data.
Uninstalling & data cleanup
When you remove a plugin from defineConfig({ plugins }), its contributed tables become
orphans — present in the database, but no longer claimed by any registered plugin.
Nextly does not auto-drop them (your data is never deleted behind your back). Use the
prune CLI to review and remove them:
nextly prune # dry run — lists orphaned plugin:* tables/columns/permissions
nextly prune --accept-data-loss # actually drops them (and their data + seeded permissions)prune only ever targets plugin:<name> provenance. Code-first (code) and
Builder (ui) entities are always retained — they're yours, not the plugin's. This
is why declaring everything through contributes (rather than creating tables yourself
with raw SQL through ctx.db.raw) matters: it's what lets uninstall be clean and reversible.
Tip for plugin authors: anything you create through
contributes/ctx.servicesis provenance-tagged and pruned automatically.ctx.dbitself runs no DDL: it reads and writes declared tables, and creates none. Anything you create with raw SQL throughctx.db.raw(DDL, side tables), which needscapabilities.db.rawSqland the app'sdb.rawSqlPluginslisting, is not tracked and will be left behind on uninstall — document it, or avoid it.
Tables declared with defineTable
Tables a plugin declares with defineTable and ships migration modules for are
installed and removed with two commands, run while the plugin is in your config:
nextly plugins install <name> # apply its pending modules, then onInstall
nextly plugins install --all # the same for every enabled plugin, dependencies first
nextly plugins uninstall <name> --accept-data-loss # onUninstall, then every module's DOWN
nextly plugins uninstall <name> --keep-data # onUninstall only; the tables stay, orphanedA production boot refuses an enabled plugin until the install command has run on
that database (PLUGIN_NOT_INSTALLED); a disabled one boots without it. nextly migrate applies a plugin's modules but does not install it. Install refuses while a plugin it depends on is not installed
(PLUGIN_DEPENDENCY_NOT_INSTALLED). Uninstall refuses while another enabled plugin
depends on it (PLUGIN_HAS_DEPENDENTS) or when a module has no DOWN
(PLUGIN_UNINSTALL_IRREVERSIBLE), and asks before dropping anything: at a terminal it
asks once, and without one it needs --accept-data-loss, alone or naming each table it
drops (PLUGIN_UNINSTALL_UNCONFIRMED; --yes does not consent to deleting data). A full uninstall also refuses (PLUGIN_UNINSTALL_WOULD_DROP_OTHERS) while
another owner has built on the plugin's schema: a column, index, foreign key or check the
app or another plugin added to one of its tables, a key or a relationship field elsewhere
pointing into them, or an index or key using or referencing a column the plugin added to
someone else's table. A relationship field the plugin itself added elsewhere, by extend or a
transform and at any depth inside another owner's groups or repeaters, goes with it and does
not count. Dropping any of it would delete another owner's data, so no consent covers it. The
refusal names each one and its owner. Remove them in their owner's code and migrate, or
uninstall with --keep-data, which drops nothing. A full uninstall also deletes the
plugin's settings (secrets included), its owner records and its migration history, so a
later install starts from nothing. It forgets them only once its DOWNs have removed
everything it added to other owners' tables; if one is left, it keeps them and refuses
(PLUGIN_UNINSTALL_IRREVERSIBLE), and before anything runs when no applied module is left to remove it: drop what it names and run the uninstall again. Every other refusal comes before anything runs. After an
uninstall, with or without --keep-data, the boot refuses the plugin while it is
still listed (PLUGIN_SCHEMA_UNINSTALLED): remove it from the config, or install it
again. An uninstall that stopped part way is finished by running it again
(PLUGIN_UNINSTALL_UNFINISHED until then); one run again after it finished
reports it done and changes nothing, without running onUninstall again. See
Installing and
Uninstalling for the rules.
See also: Data access · Testing.
Tables of your own
A collection gives you REST routes, admin screens, validation and access control. Sometimes you want none of that — a join table, a cache, a log a user never sees — and a collection is the wrong shape for it.
Declare a table instead:
import { definePlugin } from "@nextlyhq/plugin-sdk";
import { col, defineTable } from "@nextlyhq/plugin-sdk/schema";
const identities = defineTable(
"identities",
{
id: col.id(),
provider: col.shortText(),
providerAccountId: col.shortText(),
userId: col.ref("users"),
lastSeenAt: col.timestamp({ nullable: true }),
...col.timestamps(),
},
{
indexes: [
{ columns: ["provider", "providerAccountId"], unique: true },
{ columns: ["userId"] },
],
}
);
definePlugin({
name: "@acme/nextly-plugin-auth",
version: "1.0.0",
nextly: ">=0.0.2-alpha.67",
contributes: {
schema: { prefix: "auth", tables: [identities] },
},
});That table is created as auth__identities. The prefix is yours; declare it,
or let it default to your plugin's admin slug.
For a whole plugin built this way, see the
reading-lists fixture
in the Nextly repository: two tables with a foreign key and a relation, their
generated migration module, a hidden column on a collection, an idempotent
onInstall, and a test that installs, uses and uninstalls it with the real
commands on PostgreSQL, MySQL and SQLite.
The column kinds
- Text:
text,shortText,longText,varchar(n),char(n),uuid, andenum([...]), a text column whose values a check constraint holds to the list. - Numbers:
smallint,integer,bigint(read as a JavaScript number, exact up to 2^53),real,doubleanddecimal(p, s). - Others:
boolean,timestamp,json<T>()andbytes. - Keys and conveniences:
col.id()(avarchar(36)primary key for a UUIDv7),col.serial()(a primary key the database numbers, in place ofcol.id()),col.ref(table)(a recorded reference, with a relation) andcol.timestamps()(created_atandupdated_at).
Every kind here renders on PostgreSQL, MySQL and SQLite, so a table you declare works on all three — what cannot be expressed cannot drift between them. Coming from Payload says how each one is stored.
Reading and writing
The declaration creates and migrates the table under its SQL name
(auth__identities above). Plugin code queries it through ctx.db, the typed,
owner-checked surface (see When to drop to
ctx.db), or through
ctx.db.raw, the Drizzle builder, with a Drizzle table object that names the
same table and columns.
col.id() has no database default. ctx.db.insert fills a UUIDv7 when the
row leaves id out; code writing the table through ctx.db.raw supplies its
id, and InferInsert requires it. Any UUID fits the varchar(36)
column; a UUIDv7 (the uuid package's v7(), for example) keeps new rows in
key order. col.timestamps() gives created_at and updated_at a database
default of the current time, so an insert may leave both out, but nothing
refreshes updated_at afterwards: set it in every update your code makes.
A column you contribute to a Nextly collection's table is different, because
Nextly writes those rows: an updatedAt from col.timestamps() contributed
there is refreshed on each update Nextly makes to the entry.
Hooks, when a declaration is not enough
contributes.schema.extend runs after every plugin before you in dependency
order, so you can react to what they declared:
contributes: {
schema: {
extend: [
({ schema }) => {
// Absent when your own migration modules are generated: see below.
if (!schema.getTable("dc_posts")) return;
schema.extendTable("dc_posts", {
indexes: [{ columns: ["authorId", "publishedAt"] }],
});
},
],
},
}The declarative tables form is sugar for a hook calling addTable. They
produce identical output.
nextly migrate:create --plugin compiles your migration modules from your plugin
and its dependsOn alone, never from a site's collections, Singles and field
groups, which differ per installation. A hook that extends one of those tables
must skip it there, by checking schema.getTable(name) first as above, or
generation stops with PLUGIN_EXTENDS_OUTSIDE_ITS_SCHEMA. The site's own
nextly migrate:create compiles it with every table present, and writes your
addition into the site's migration.
What you may change
| Target | Columns | Indexes | Foreign keys, checks, relations |
|---|---|---|---|
| Your own tables | yes | yes | yes |
A plugin you name in dependsOn / optionalDependsOn | yes, hidden | yes | yes |
| Any other plugin's tables | no | no | no |
Entity tables (dc_*, single_*, comp_*) | yes, hidden | yes | no |
Extendable core tables (users, media, nextly_jobs, audit_log, activity_log) | yes, hidden | yes | no |
| Every other core table | no | no | no |
The app may add columns, indexes, foreign keys, checks and relations to any plugin's table, under the same rules. See Keys, checks and relations on a table you do not own.
Which migrations carry what you add depends on the table. On your own tables
and on a dependency's, your plugin's own migration modules carry it. On an
entity table or an extendable core table — whether a plugin or the app added
it — the APP's migrations carry it: nextly migrate:create in the app writes
the statement, so it reaches a database with the app's next migration.
A column added to a table you do not own is hidden: it exists on the table,
so migrations and dev push keep it, and on an entity table it is stripped
from every REST response, Direct API read, version snapshot and webhook
payload, and a value sent for it through the entry API is dropped. A where
naming it is refused, including under a component field's path for a column
on a component's table; a group key naming it is refused, and a sort by it is
ignored. The column
must be nullable or have a default, since the table may already have rows.
You read and write a column you added to an entity or core table through
ctx.db.contributed(table, columns), keyed by row id — see
Columns on a table you do not own.
It reaches only your own contributed columns and the row's id; the table's
other columns, other plugins' contributions, inserts and deletes are refused.
A hidden column is storage for your plugin's own bookkeeping, not a field. To
give a collection a field that editors and API callers see, with validation and
access control, use contributes.extend.
What is deliberately unsupported
Views, native enums, and partial indexes: an index with a where predicate is
refused on every dialect, because declarations are checked against all three
and MySQL has none. Checks, foreign keys, and expression indexes ARE
supported: declare them on defineTable and they travel through
dev push, plugin migrations and drift checks on every dialect — inline in the
table's CREATE TABLE on its first migration, and through the table rebuild
where a dialect cannot add one in place. An expression index key must compute a
value: DESC, ASC, NULLS FIRST/LAST, COLLATE and operator classes such as
text_pattern_ops are refused at defineTable, because no dialect reports them
back and the index would be planned again on every push. col.ref() alone records a reference
for documentation and validation; a constraint comes from the foreignKeys
option. A foreign key may not use onDelete or onUpdate: "set default",
which MySQL cannot create.
Your tables hold exactly what you declare: a check or foreign key added to one any other way is dropped by the next development push. See What is not supported.
Production
A plugin that declares tables ships migration modules
(contributes.schema.migrations) and a schemaVersion. Generate them with
nextly migrate:create --plugin ./src/index.ts, bumping schemaVersion each
time; nextly migrate applies them in dependency order under the migrate lock,
before any plugin initialises. The ledger records them under qualified names
(plugin:<name>/<file>), an app rollback never touches them, and a production
boot refuses a plugin whose declared version the database has not applied
(PLUGIN_SCHEMA_BEHIND).
Generation never drops a table or column an earlier module created. The
generator cannot tell a rename from a drop and an add, and either loses the
rows, so it refuses (PLUGIN_MIGRATION_DROPS_CREATED_SCHEMA) and names what
it would have dropped; write the rename, or the deliberate drop, by hand in a
module from --blank (below). With no schema changes it writes nothing and
exits with code 0, whatever schemaVersion says.
A column added to a table an earlier module created has to give the rows
already in it a value, so generation refuses one that is NOT NULL with no
default (PLUGIN_MIGRATION_ADDS_UNFILLABLE_COLUMN) on every dialect: SQLite
and PostgreSQL would refuse it on a table with rows, and MySQL would fill the
rows with 0 or '' without saying so. Give it a default, or add it nullable,
fill the rows and make it NOT NULL yourself in a module from --blank. A
column with a current-time default, such as col.timestamps(), is added on
SQLite by rebuilding the table, because SQLite's ADD COLUMN refuses that
default once the table has rows; each existing row takes the time of the
migration.
Some changes a dialect cannot make in place: a column's type or nullability on
SQLite, and its nullability on MySQL. Generation still writes the module, with
that dialect's up and down empty for you to fill and the change recorded
on both sides, so once you write the SQL (on SQLite, a rebuild of the table)
the next generation starts from the changed shape. The command names the
dialects left to you, and nextly migrate refuses to run a module that
changes the schema on a dialect whose up is still empty
(PLUGIN_MIGRATION_SQL_MISSING).
Each module runs in one transaction. A module that needs a statement a
transaction refuses, such as PostgreSQL's CREATE INDEX CONCURRENTLY, sets
transaction: false, and its UP and DOWN then run statement by statement. If
one fails, the statements before it stay applied and are not undone, so keep
such a module to the statements that need it. The field is part of the
module's checksum only when it is false, so existing modules keep their
checksums. See
Running a file outside a transaction.
Writing a module by hand
A generated module carries its checksum as a literal, and any edit to it is
refused (MIGRATION_CHECKSUM_MISMATCH). A module you write or edit yourself
is sealed by migrationChecksum from @nextlyhq/plugin-sdk/schema instead,
computed over the module without its checksum when the module loads:
import {
migrationChecksum,
type PluginMigration,
} from "@nextlyhq/plugin-sdk/schema";
const content = {
name: "20261007_120000_000_index_notes",
schemaVersion: 3,
transaction: false,
dialects: {
postgresql: {
up: [
"CREATE INDEX CONCURRENTLY IF NOT EXISTS notes_label_idx ON acme__notes (label)",
],
down: ["DROP INDEX CONCURRENTLY IF EXISTS notes_label_idx"],
},
mysql: { up: [], down: [] },
sqlite: { up: [], down: [] },
},
// The tables before and after it, carried from the previous module: an
// index built outside a transaction changes no declared table.
snapshot: {
postgresql: { tables: [] },
mysql: { tables: [] },
sqlite: { tables: [] },
},
before: {
postgresql: { tables: [] },
mysql: { tables: [] },
sqlite: { tables: [] },
},
} satisfies Omit<PluginMigration, "checksum">;
export default {
...content,
checksum: migrationChecksum(content),
} satisfies PluginMigration;You rarely write one from nothing. nextly migrate:create writes it in this
form:
nextly migrate:create --plugin ./src/index.ts --blankwrites a module with no statements for SQL you add. It records the change from the previous module's schema to the plugin's declared one, so it serves both kinds of hand-written work. With the declared schema unchanged, both sides are the previous module's, for SQL that changes no declared table, such as a backfill or aVACUUM, and itsschemaVersionmay equal the previous module's. With a change declared, such as a renamed column, it records that change for your SQL to make, and itsschemaVersionmust move past the previous module's. Add--no-transactionfor a module withtransaction: false.nextly migrate:create --plugin ./src/index.ts --no-transactiongenerates the next module from the plugin's schema, as usual, withtransaction: false, so you can turn itsCREATE INDEXintoCREATE INDEX CONCURRENTLY. A statement that builds the same index leaves the module's snapshot correct.
Either way the module is written to src/migrations/ and added to its barrel.
A hand-sealed module gives up one check: that its SQL is the SQL that was
generated. The ledger still refuses a module that changed after it was
applied, so finish editing it before it ships.
These rules hold for every module, and a plugin that breaks one is refused when the configuration loads, before anything runs:
- Its
namecannot contain/. The ledger records it asplugin:<plugin>/<name>, and a slash in the name would file it under another plugin. - Its
schemaVersionis a positive integer, as the plugin's own is, whether or not the plugin declares one. - Modules run in name order — compared character by character, ignoring
case, the same on every machine whatever its locale, so
10_moreruns before1_init: zero-pad a numbered name. When the plugin declares aschemaVersion, each module's is no lower than the one before it. The version the database ends at is the last module's, so it is the one that must equal the plugin'sschemaVersion.
And when it runs, a module may drop or rename only what the owner registry
says is the plugin's: its own tables, and the indexes and constraints on
them; the columns, indexes, foreign keys and checks it contributed to other
owners' tables; and tables the module itself creates. A table no record
claims, such as an app table from before the registry, is refused
(DROP_OF_FOREIGN_TABLE), and so is a drop of another owner's index or
constraint — including an index named on its own (DROP INDEX name), whose
table is read from the database.
A database development push already brought to a plugin's latest shape is
adopted: nextly migrate records the modules it stands past, or whose result
it already holds, as applied without running them, since the tables already
say they ran. That proof holds
only for what a schema shows. A module that only changes data — a seed or a
backfill, or one creating a trigger or function — runs where it stands
instead, against the tables as they are, and so does any module whose schema
does not change, such as one written with --blank, whatever its SQL. Such a
module therefore has to hold against every later shape of the plugin's tables;
one that fails there is refused with the recovery. A module that both changes
the schema and does such work, such as one creating a table with
CREATE TABLE … AS SELECT or filling a new table and renaming it into place,
whose rows no schema shows, can be neither, and is refused with the recovery;
keep data statements in modules of their own. A statement the runner cannot
read counts as such work, so it is never recorded unrun. The exception is the
recovery for an attempt that stopped part-way: once you finish its statements
by hand and clear the attempt (nextly migrate:resolve --failed-cleanup),
nextly migrate records the module where the database stands past its start.
The entry --plugin points at may export the plugin as its default export or
as a named one (export const myPlugin = definePlugin(...)), beside the tables
it declares; a file exporting two plugins is refused, naming both.
A database that dev push has already given the plugin's tables can be migrated
as it is. Dev push creates the tables as the plugin defines them now, which is
the result of its latest module, so nextly migrate records every module up to
the one whose result the database matches as applied, without running them,
and runs any after it. A database matching no point in the plugin's history is
refused, with the recovery for a plugin's tables.
Moving data from one place to another
A migration module changes the schema before the new release serves, but the old release keeps serving for a while during every deploy (see Upgrades while old instances still run). Its code still reads and writes your plugin's data where it used to. So a release that moves data from one place to another (a collection to a table of your own, one table to another, a column to a new shape) moves it in steps, over more than one release:
- Add the new place, keep the old. The module only creates. The old collection or table stays declared, so the old release goes on working against it.
- Move at start, and keep the old place's shape. Copy the rows in your
plugin's
onReady, once, under a note that says the move is done, in one transaction with the copy. In the same transaction, keep something that changes whenever the old release writes the old place, whether it adds, updates or deletes a row. A row count and the newest update time are a shortcut that is only safe where every write sets that time from one clock and nothing is changed in the same second as the look: an old instance can update a row without moving the count, a slower clock can stamp a later write as older, and a delete and an insert can leave the count where it was. For other data, keep a durable record of what you took in (the ids of the rows, or a note on each row once it is moved) and compare against that, rather than trusting a count and a time. Take the time at which you read the old place, not the time you finished. A move made in a SQL module cannot know the old place's name on a site that renamed your collection (rename), and runs before any plugin code, so the move belongs in code. - Take in what the old release wrote afterwards. At each start, compare
the old place's shape with the one you kept. When it changed, an old
instance wrote there after your move: take those writes in (or, where your
data can be worked out again from something else, rebuild it), then keep the
new shape. A start where nothing changed should cost a read or two and
write nothing. A long-running server may not start again until the next
deploy, so look once more a while after start, with a timer that does not
keep the process alive (
unref()), cleared indestroy. - Record when the old place is drained, and what it looked like then. Write a durable marker in your own tables once the old place's writes are taken in, never a flag in memory, and keep in it the change signal you read when you took them in. A marker on its own goes stale the moment an old instance writes again; the signal beside it is what tells a later release whether it still holds.
- Remove the old place much later, behind the marker and its signal. At
least two releases after the move ships, a release may stop declaring the
old place and delete the move code. That release checks at start whether
the old place still exists (
ctx.services.collections.holdCollectionInTransactionanswers whether a collection's registry row is there). If it does, it reads the old place's change signal again and compares it with the one kept in the marker. When the marker is absent, or the signal moved since it was kept, something was written that was never taken in: the release refuses to start with aNextlyErrornaming the release to install (and start once) first, rather than leave that write to be dropped. It drops nothing itself: the old place becomes an orphan the site owner removes withnextly prune.
The SEO plugin's move of its address record (from the nx_seo_addresses
collection to seo__addresses and seo__notes) follows these steps, and is a
worked example in this repository.
Two things are deliberately not built yet:
- A fence. Core does not yet let a module declare that older code must stop writing a plugin's data once the module is applied. That would make the old instances refuse the writes during the overlap rather than leave them to be repaired. It will be added, opt-in per module, when a data move needs it; until then, step 3 is how a move stays correct.
- Retiring the SEO plugin's old collections. They stay declared until at least two releases after the moves ship, and then go only behind their drained markers and the start check in step 5.
Admin UI
Contribute admin menu items, pages, settings, and collection-view overrides from a plugin — and control where they appear in the sidebar.
Unique public addresses
How a plugin that keeps a record of page addresses takes part in keeping every public address to one page, through ctx.publicAddresses.