Database support and version requirements

Nextly supports PostgreSQL, MySQL, and SQLite through dedicated adapter packages. Each connect() call queries the database for its version string and validates it against the minimum Nextly requires. Real PostgreSQL / MySQL / SQLite below minimum hard-fails with an upgrade pointer; recognized MySQL-compatible variants warn and proceed; completely unparseable strings hard-fail at boot rather than silently letting you hit cryptic errors mid-apply.

Minimum versions

If your database reports a version below the minimum, the adapter's connect() throws UnsupportedDialectVersionError with a message that links back to this page.

Cloud-provider compatibility

PostgreSQL — supported

MySQL — supported with warnings for variants

Nextly is regression-tested against real MySQL 8.0+ only. MySQL-protocol-compatible variants are recognized at connect, log a one-time warning through the adapter's logger, and proceed:

The warning text routes through your adapter's configured logger and looks like:

Detected mariadb ('10.11.5-MariaDB-...'). Nextly is regression-tested
against real MySQL 8.0+ only; this MySQL-compatible variant is not
officially supported in v1 but most operations should work. See
https://nextlyhq.com/docs/database/support.

If a MySQL response is completely unparseable -- no version number AND no variant token detected -- Nextly hard-fails at boot.

If you hit a variant-specific bug, please file an issue with your variant + version. v2 will add opt-in regression coverage for individual variants.

SQLite — supported

Production-migrations rules

• Forward-only. No migrate:rollback or migrate:down exists. To undo a deployed change, write a NEW migration that reverses it.
• Schema lives in your repo. nextly migrate:create --name=... scaffolds an empty migration; you commit it; CI applies it before deploy.
• The deployed app never touches the schema. migrate:fresh is destructive and CLI-only -- it is rejected if imported from runtime code.

For platform-specific deploy patterns (Vercel + GitHub Actions, Vercel build step, "other platforms"), see production migrations.

Upgrade guidance

PostgreSQL

If you are on PG 12 / 13 / 14: most managed providers offer in-place major-version upgrades. Run SELECT version() to confirm; consult your provider's docs for the upgrade procedure. For self-hosted, follow the standard pg_upgrade workflow.

MySQL

If you are on MySQL 5.7: upstream support ended in October 2023. Your provider almost certainly offers a managed upgrade to 8.0. Test the upgrade in staging first -- some 5.7 SQL is incompatible with 8.0 reserved-word changes.

SQLite

Bundled with better-sqlite3. Upgrade by bumping that package. If you maintain your own SQLite linkage, install at least 3.38 from your distribution's package manager.

Why the policy is hybrid

Nextly draws three different lines at connect time:

1. Real PG / MySQL / SQLite below minimum -> hard-fail. Schema migrations rely on dialect features at the minimum-version threshold (RENAME COLUMN, transactional DDL, MERGE, strict tables). A real MySQL 5.7 user who proceeded would hit confusing mid-apply errors during their first schema change.
2. Recognized variant (MariaDB, TiDB, Aurora MySQL, PlanetScale, Vitess) -> warn and proceed. These are real cloud databases millions of developers run. Hard-failing them on first install would lock out legitimate users from a CMS that mostly works on their stack. The warning makes the trade-off explicit.
3. Completely unparseable string -> hard-fail. If we cannot find a version number AND cannot detect a variant token, we surface the issue immediately rather than silently proceeding into cryptic errors.

The error and warning paths both link to this page so users know the upgrade lever or, for variants, that they are running on best-effort support.

When the version check runs

checkDialectVersion() runs inside each adapter's connect(), after the connection is verified alive but before the adapter marks itself ready. PostgreSQL retries transient network failures (Neon cold starts, EAI_AGAIN) without re-running the version query in a tight loop; only confirmed version mismatches throw UnsupportedDialectVersionError.

Catching the error

The error implements adapter-drizzle's DatabaseError interface, so existing isDatabaseError() type guards continue to work. You can also branch on the kind field directly:

import { UnsupportedDialectVersionError } from "@nextlyhq/adapter-drizzle/version-check";

try {
  await adapter.connect();
} catch (error) {
  if (error instanceof UnsupportedDialectVersionError) {
    console.error(
      `Detected ${error.detectedVersion}, required ${error.requiredVersion}`,
    );
    process.exit(1);
  }
  throw error;
}

Next steps

• Database overview -- feature comparison across dialects
• PostgreSQL setup -- recommended for production
• MySQL setup -- supported with caveats
• SQLite setup -- local demo only
• Production migrations -- forward-only deploy patterns