You're reading docs for Nextly Alpha. APIs may change between releases.

Plugins

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 users and media, or field groups, apart from a plugin's collection marked siteContent: true (@experimental), one that holds the site's own content, such as Page Builder's pages;
  • 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:create would, and every environment drops them when it next runs nextly 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, as migrate:create does. 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 in dependsOn (not optionalDependsOn), 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 its status or localized setting, which add the status column and the translations table its owner's data sits in, or remove a unique compound index from its indexes. 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 its dbName, status or localized: 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 required or unique, whether it holds one value or a list (hasMany, a field group's repeatable), its relation target, whether it's translated, or, for a field stored as JSON such as a group or repeater, or a password field, its type), is refused for a field another plugin declared: the owner's own fields, and fields a third plugin added with extend or 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 plain index and 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.url among 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 in dependsOn. 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, defineSingle or defineFieldGroup would refuse, such as db: { 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.services is provenance-tagged and pruned automatically. ctx.db itself runs no DDL: it reads and writes declared tables, and creates none. Anything you create with raw SQL through ctx.db.raw (DDL, side tables), which needs capabilities.db.rawSql and the app's db.rawSqlPlugins listing, 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, orphaned

A 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, and enum([...]), 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, double and decimal(p, s).
  • Others: boolean, timestamp, json<T>() and bytes.
  • Keys and conveniences: col.id() (a varchar(36) primary key for a UUIDv7), col.serial() (a primary key the database numbers, in place of col.id()), col.ref(table) (a recorded reference, with a relation) and col.timestamps() (created_at and updated_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

TargetColumnsIndexesForeign keys, checks, relations
Your own tablesyesyesyes
A plugin you name in dependsOn / optionalDependsOnyes, hiddenyesyes
Any other plugin's tablesnonono
Entity tables (dc_*, single_*, comp_*)yes, hiddenyesno
Extendable core tables (users, media, nextly_jobs, audit_log, activity_log)yes, hiddenyesno
Every other core tablenonono

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 --blank writes 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 a VACUUM, and its schemaVersion may equal the previous module's. With a change declared, such as a renamed column, it records that change for your SQL to make, and its schemaVersion must move past the previous module's. Add --no-transaction for a module with transaction: false.
  • nextly migrate:create --plugin ./src/index.ts --no-transaction generates the next module from the plugin's schema, as usual, with transaction: false, so you can turn its CREATE INDEX into CREATE 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 name cannot contain /. The ledger records it as plugin:<plugin>/<name>, and a slash in the name would file it under another plugin.
  • Its schemaVersion is 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_more runs before 1_init: zero-pad a numbered name. When the plugin declares a schemaVersion, 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's schemaVersion.

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:

  1. 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.
  2. 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.
  3. 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 in destroy.
  4. 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.
  5. 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.holdCollectionInTransaction answers 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 a NextlyError naming 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 with nextly 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.