@byline/db-mysql 4.8.0 → 4.10.0

package/README.md

@@ -1,27 +1,15 @@
 # @byline/db-mysql
 
-> **Status: preliminary.** This adapter is published so it can be evaluated and
-> exercised, not because MySQL is a fully supported Byline backend yet. The
-> storage layer is complete and proven — it passes the entire shared
-> `@byline/db-conformance` behavioural suite, the same suite `@byline/db-postgres`
-> passes, with identical results. What is missing is the surrounding ecosystem:
+> **Status: generally available.** The storage adapter passes the same
+> `@byline/db-conformance` suite as `@byline/db-postgres`,
+> `@byline/search-mysql` supplies the matching search provider, and
+> `@byline/cli` can provision and scaffold a MySQL installation.
 >
-> - **No search provider.** `@byline/search-postgres` has no MySQL counterpart, and
->   this is not merely a missing feature — `initBylineCore()` **throws at boot** if
->   any collection declares `search` and no provider is registered. See
->   [Search on MySQL](#search-on-mysql) below for the one-step workaround you will
->   need. Tracked in
->   [#52](https://github.com/Byline-CMS/bylinecms.dev/issues/52).
-> - **No CLI support.** `byline init` scaffolds a Postgres installation; wiring
->   MySQL is a manual edit to your `server.config.ts`.
-> - **Narrower CI coverage than Postgres.** Continuous integration pins MySQL 8.0
->   — the engine floor — so nothing yet exercises 9.x automatically, and no leg
->   runs under a non-UTC timezone. Tracked in
->   [#55](https://github.com/Byline-CMS/bylinecms.dev/issues/55).
->
-> Treat it as suitable for evaluation, prototypes, and installations that do not
-> need search. The criteria for general availability are tracked in
-> [#58](https://github.com/Byline-CMS/bylinecms.dev/issues/58).
+> Continuous integration pins MySQL 8.0 to exercise the supported engine floor.
+> Both adapter conformance suites also run under a non-UTC timezone
+> (`Asia/Kathmandu`) so calendar-date handling cannot silently depend on the
+> host timezone. MySQL 9.x remains covered by local development with
+> `mysql/docker-compose.yml`, which runs `mysql:latest`.
 
 MySQL adapter for Byline CMS — Drizzle schema, migrations, and the storage /
 queries / commands implementation behind `IDbAdapter`. It is Byline's second
@@ -42,6 +30,20 @@ workflow, and content translation as first-class concerns.
 
 ## Install
 
+For a new Byline installation, let the CLI select the package, environment
+variable, baseline, and server configuration together:
+
+```sh
+npx @byline/cli@latest init --database mysql
+```
+
+The generated application uses `@byline/db-mysql`,
+`@byline/db-mysql/admin`, and
+`BYLINE_DB_MYSQL_CONNECTION_STRING`. If you include the example collections,
+it also installs and registers `@byline/search-mysql`.
+
+For a hand-wired application:
+
 ```sh
 pnpm add @byline/db-mysql
 ```
@@ -82,10 +84,9 @@ const core = await initBylineCore({
 })
 ```
 
-This mirrors how `apps/webapp/byline/server.config.ts` wires `@byline/db-postgres` today —
-swap `pgAdapter` / `@byline/db-postgres/admin` for `mysqlAdapter` /
-`@byline/db-mysql/admin` and the rest of an existing Byline server config is unchanged,
-because both adapters implement the same `IDbAdapter` and `AdminStore` contracts.
+This is the wiring generated by `byline init --database mysql`. Both database
+adapters implement the same `IDbAdapter` and `AdminStore` contracts, so the
+rest of the server configuration is adapter-independent.
 
 `connectionString` is the **only** connection input `mysqlAdapter` takes, and
 it must be a `mysql://` URL — mysql2 parses connection URLs natively (`uri`
@@ -198,12 +199,10 @@ databases, and a few divergences are real rather than papered over.
   are meaning-bearing in some scripts (a Thai tone mark, a Devanagari
   anusvara, Hebrew niqqud) are never silently folded together the way
   `ai_ci` would fold them.
-- **No search provider yet.** `@byline/search-postgres` has no MySQL
-  counterpart today — a collection's `search` config
-  (`CollectionDefinition.search`) requires a registered `SearchProvider`,
-  and none ships for MySQL yet. Track
-  [the `@byline/search-mysql` follow-up issue](https://github.com/Byline-CMS/bylinecms.dev/issues/52)
-  for status.
+- **Search uses a dialect-specific provider.** Register
+  `@byline/search-mysql` with this adapter. It implements the same portable
+  lexical and weighting contract as `@byline/search-postgres`, while owning its
+  own MySQL `FULLTEXT` schema and migrations.
 - **The connection string is the only connection input.** See "Usage"
   above — this is called out here too because it is the most common way
   this adapter is misconfigured by a reader coming from the Postgres
@@ -218,60 +217,32 @@ databases, and a few divergences are real rather than papered over.
 
 ## Search on MySQL
 
-There is no MySQL search provider yet, and the absence is load-bearing rather
-than cosmetic: `validateSearchConfig` runs inside `initBylineCore()` and
-**throws** when any collection declares a `search` block but no provider is
-registered. Byline's own reference application opts five collections into
-search, so a MySQL installation that copies it fails at boot with an error that
-does not mention MySQL at all.
-
-Until `@byline/search-mysql` exists, register a no-op provider. It satisfies
-validation, and indexing and querying become silent no-ops rather than errors —
-the admin Reindex action and any search page return nothing, which is the honest
-answer on this adapter today:
+Register `@byline/search-mysql` with the adapter's existing promise pool. Apply
+the provider's independent migration stream before serving traffic:
 
 ```ts
-const noopSearch = {
-  capabilities: {
-    facets: false,
-    typoTolerance: false,
-    semantic: false,
-    bm25: false,
-    weighting: false,
-    highlights: false,
-  },
-  async upsert() {},
-  async remove() {},
-  async search() {
-    return { hits: [], total: 0 }
-  },
-}
+import { migrate, mysqlSearch } from '@byline/search-mysql'
+
+await migrate(db.pool)
 
 await initBylineCore({
   // …
   db,
-  search: noopSearch,
+  search: mysqlSearch({ pool: db.pool, defaultLocale }),
 })
 ```
 
-The alternative — removing the `search` block from every collection definition —
-also works, but it discards configuration you will want back when a provider
-lands. The no-op keeps your collections declarative and confines the workaround
-to one place.
-
-## Not yet shipped
-
-- **`@byline/search-mysql`** — see [Search on MySQL](#search-on-mysql) above.
-  Tracked in [issue #52](https://github.com/Byline-CMS/bylinecms.dev/issues/52).
-- **CLI support.** `byline init` scaffolds a Postgres installation. Adding MySQL
-  to an existing project is a manual edit to `byline/server.config.ts` — swap
-  `pgAdapter` for `mysqlAdapter`, swap the `@byline/db-postgres/admin` import for
-  `@byline/db-mysql/admin`, drop the `@byline/search-postgres` migrate call, and
-  register the no-op search provider above.
-- **A MySQL storage-benchmark target.** The design spec flags view
-  materialisation (the `ROW_NUMBER()` window inside a derived table, used
-  by both current-version views) as a question to answer before this
-  adapter's GA — Postgres's own benchmark sweep
+Search rows are a disposable projection of published versions. The provider
+uses parser-safe portable terms, weighted MySQL `FULLTEXT` indexes, and analyzer
+fingerprints. Its package README documents migrations, capabilities, and the
+clear-and-rebuild procedure.
+
+## Current boundaries
+
+- **A MySQL storage-benchmark target (non-blocking).** The design spec flags
+  view materialisation (the `ROW_NUMBER()` window inside a derived table,
+  used by both current-version views) as useful performance-characterisation
+  work. It is not a release gate. PostgreSQL's own benchmark sweep
   ([`docs/03-architecture/01-document-storage.md`](https://github.com/Byline-CMS/bylinecms.dev/blob/develop/docs/03-architecture/01-document-storage.md#indicative-benchmarks))
   has no MySQL counterpart yet. Tracked in
   [issue #53](https://github.com/Byline-CMS/bylinecms.dev/issues/53).

package/dist/database/schema/auth.js

@@ -20,7 +20,7 @@
  *     to 1; bumped by write paths when needed).
  *   - snake_case column names matching the rest of the Byline schema.
  *
- * See docs/06-auth-and-security/01-authn-authz.md for the full data model and present-state
+ * See docs/07-auth-and-security/01-authn-authz.md for the full data model and present-state
  * reference.
  */
 import { relations, sql } from 'drizzle-orm';

package/dist/database/schema/common.js

@@ -86,7 +86,7 @@ export const varcharCaseSensitive = customType({
  * same tick and receive an *identical* `CURRENT_TIMESTAMP(3)` value, which
  * is a real correctness gap for anything that orders or windows by these
  * columns (found via `packages/db-conformance`'s audit activity-feed
- * fixture — see docs/09-testing.md and the Task 11 report for the
+ * fixture — see docs/10-testing.md and the Task 11 report for the
  * live-server evidence: four rapid statements produced 2 distinct values at
  * fsp 3 versus 4 distinct values at fsp 6). Matching pg's precision closes
  * that gap at the source instead of asking every fixture/consumer to work

package/dist/database/schema/index.js

@@ -168,7 +168,7 @@ export const documentPaths = mysqlTable('byline_document_paths', {
 // carries forward across edits and survives restore. Surfaced on reads as
 // `availableLocales`; the public advertised set is the intersection with the
 // ledger's `_availableVersionLocales`. Replaced wholesale on write (the lifecycle
-// deletes then re-inserts the set), never appended. See docs/07-internationalization/index.md.
+// deletes then re-inserts the set), never appended. See docs/08-internationalization/index.md.
 export const documentAvailableLocales = mysqlTable('byline_document_available_locales', {
     document_id: uuidChar('document_id').notNull(),
     locale: varchar('locale', { length: 10 }).notNull(),
@@ -198,7 +198,7 @@ export const documentAvailableLocales = mysqlTable('byline_document_available_lo
 // identically in any locale). Computed status-blind at write time and frozen
 // on the immutable version, so restore / point-in-time reads stay consistent.
 // Drives `localeFallback: 'strict'` reads via an indexed EXISTS gate without
-// scanning the store_* tables. See docs/07-internationalization/index.md.
+// scanning the store_* tables. See docs/08-internationalization/index.md.
 export const documentVersionLocales = mysqlTable('byline_document_version_locales', {
     document_version_id: uuidChar('document_version_id').notNull(),
     locale: varchar('locale', { length: 10 }).notNull(),
@@ -300,7 +300,7 @@ export const currentDocumentsView = mysqlView('byline_current_documents').as((qb
         // read paths (`buildLocaleChain` / `pathProjection` / field-fallback)
         // re-base onto the per-document source rather than the mutable global
         // default — a primary-key join, already present for `order_key`.
-        // See docs/07-internationalization/index.md.
+        // See docs/08-internationalization/index.md.
         source_locale: documents.source_locale,
     })
         .from(sq)
@@ -407,7 +407,7 @@ export const textStore = mysqlTable('byline_store_text', {
     // no query code references this index name — and Byline's actual
     // full-text search is a separate, pluggable `SearchProvider` seam
     // (`@byline/core`), not built on this table's indexes. See
-    // docs/05-reading-and-delivery/07-search.md.
+    // docs/06-search/index.md.
     index('idx_text_locale_value').on(table.locale, sql `${table.value}(191)`),
     index('idx_text_path_value').on(table.field_path, sql `${table.value}(191)`),
     // Unique constraints for unique fields
@@ -860,7 +860,7 @@ export const jsonStoreRelations = relations(jsonStore, ({ one }) => ({
 // fit without a second migration. Append-only and deliberately **FK-free**: an
 // audit row is an immutable historical fact that must outlive the document,
 // collection, or actor it references — a `document.deleted` row cannot be
-// allowed to cascade-delete itself. See docs/06-auth-and-security/02-auditability.md — Workstream 2.
+// allowed to cascade-delete itself. See docs/07-auth-and-security/02-auditability.md — Workstream 2.
 export const auditLog = mysqlTable('byline_audit_log', {
     id: uuidChar('id').primaryKey(), // UUIDv7 — time-ordered, so id ordering ≈ time ordering
     document_id: uuidChar('document_id'), // NULL for admin-realm (non-document) events; no FK

package/dist/index.d.ts

@@ -36,7 +36,7 @@ export declare const mysqlAdapter: ({ connectionString, collections, defaultCont
      * for documents whose `source_locale` is not yet backfilled. Per-document
      * reads and writes otherwise re-base onto each document's own `source_locale`
      * (carried on the current-documents views), so changing this value does not
-     * re-interpret existing data. See docs/07-internationalization/index.md.
+     * re-interpret existing data. See docs/08-internationalization/index.md.
      */
     defaultContentLocale: string;
     /**

package/dist/lib/boot-check.js

@@ -11,6 +11,9 @@
  * `initBylineCore()` boot rather than surfacing as an obscure SQL error the
  * first time the storage layer emits a LATERAL join (Task 10+).
  */
+// Keep this adapter floor synchronized with the pre-install check in
+// `packages/cli/src/lib/database/mysql.ts`; the CLI contract test compares
+// the two constants without adding a runtime dependency on this package.
 const MIN = { major: 8, minor: 0, patch: 14 };
 const unsupportedEngineError = (reported) => new Error(`@byline/db-mysql requires MySQL ${MIN.major}.${MIN.minor}.${MIN.patch}+ (LATERAL joins); server reports ${reported}. MariaDB is not supported.`);
 /**

package/dist/modules/audit/audit-commands.d.ts

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 /**
- * Append-only audit-log writes (docs/06-auth-and-security/02-auditability.md — Workstream 2). A deliberately
+ * Append-only audit-log writes (docs/07-auth-and-security/02-auditability.md — Workstream 2). A deliberately
  * dumb command: it inserts one row and knows nothing about *which* changes
  * warrant an audit entry — that policy lives in the lifecycle services, which
  * wrap the mutation + this append in `withTransaction` so they commit

package/dist/modules/audit/audit-queries.d.ts

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 /**
- * Audit-log reads (docs/06-auth-and-security/02-auditability.md — Workstreams 3 & 4). Reads run on the pool
+ * Audit-log reads (docs/07-auth-and-security/02-auditability.md — Workstreams 3 & 4). Reads run on the pool
  * directly — they never need to join an audit write's transaction — so this
  * takes the raw `db` (drizzle over the pool) rather than the `DBManager`.
  * Access scoping is the caller's responsibility (the document's own read

package/dist/modules/storage/storage-commands.d.ts

@@ -205,7 +205,7 @@ export declare class DocumentCommands implements IDocumentCommands {
      * clause *after* `INSERT INTO <table>` and immediately before the `SELECT`
      * it modifies (confirmed against a live MySQL 9.7.1 server) — so the two
      * clauses are transposed relative to the pg original. See
-     * docs/07-internationalization/index.md.
+     * docs/08-internationalization/index.md.
      */
     private writeVersionLocaleLedger;
     /**
@@ -268,7 +268,7 @@ export declare class DocumentCommands implements IDocumentCommands {
      * **without** minting a new document version or touching workflow status. The
      * change is immediate and applies across every version of the document; the
      * public advertised set remains the intersection with the resolved version's
-     * completeness ledger. See docs/07-internationalization/index.md.
+     * completeness ledger. See docs/08-internationalization/index.md.
      */
     setDocumentAvailableLocales(params: {
         documentId: string;

package/dist/modules/storage/storage-commands.js

@@ -192,7 +192,7 @@ export class DocumentCommands {
             // source locale rather than the mutable global default. NULL (a row not
             // yet touched by `backfillSourceLocales`) falls back to the configured
             // default — the value it was implicitly authored against.
-            // See docs/07-internationalization/index.md.
+            // See docs/08-internationalization/index.md.
             let sourceLocale;
             if (documentId == null) {
                 documentId = uuidv7();
@@ -345,7 +345,7 @@ export class DocumentCommands {
             // accounts for the per-locale carry-forward in step 5 — not just the
             // freshly-flattened locale. A version with no localized content at all
             // records a single `'all'` sentinel (it renders identically in any
-            // locale). Status-blind by design — see docs/07-internationalization/index.md.
+            // locale). Status-blind by design — see docs/08-internationalization/index.md.
             await this.writeVersionLocaleLedger(tx, documentVersion.id, sourceLocale);
             return {
                 document: documentVersion,
@@ -446,7 +446,7 @@ export class DocumentCommands {
      * clause *after* `INSERT INTO <table>` and immediately before the `SELECT`
      * it modifies (confirmed against a live MySQL 9.7.1 server) — so the two
      * clauses are transposed relative to the pg original. See
-     * docs/07-internationalization/index.md.
+     * docs/08-internationalization/index.md.
      */
     async writeVersionLocaleLedger(tx, versionId, sourceLocale) {
         await tx.execute(sql `
@@ -558,7 +558,7 @@ export class DocumentCommands {
      * **without** minting a new document version or touching workflow status. The
      * change is immediate and applies across every version of the document; the
      * public advertised set remains the intersection with the resolved version's
-     * completeness ledger. See docs/07-internationalization/index.md.
+     * completeness ledger. See docs/08-internationalization/index.md.
      */
     async setDocumentAvailableLocales(params) {
         await this.db.transaction(async (tx) => {

package/dist/modules/storage/storage-queries.d.ts

@@ -128,7 +128,7 @@ export declare class DocumentQueries implements IDocumentQueries {
      * document, or any document read after the global default is switched, falls
      * back to the locale it was actually authored in) — otherwise the configured
      * global default, which is correct for not-yet-anchored rows and for
-     * row-less lookups (findByPath). See docs/07-internationalization/index.md.
+     * row-less lookups (findByPath). See docs/08-internationalization/index.md.
      */
     private buildLocaleChain;
     /**

package/dist/modules/storage/storage-queries.js

@@ -161,7 +161,7 @@ export class DocumentQueries {
      * document, or any document read after the global default is switched, falls
      * back to the locale it was actually authored in) — otherwise the configured
      * global default, which is correct for not-yet-anchored rows and for
-     * row-less lookups (findByPath). See docs/07-internationalization/index.md.
+     * row-less lookups (findByPath). See docs/08-internationalization/index.md.
      */
     buildLocaleChain(requestedLocale, sourceLocale) {
         const floor = sourceLocale ?? this.defaultContentLocale;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/db-mysql",
   "private": false,
   "license": "MPL-2.0",
-  "version": "4.8.0",
+  "version": "4.10.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -50,8 +50,8 @@
     "drizzle-orm": "^0.45.2",
     "mysql2": "^3.23.1",
     "uuid": "^14.0.1",
-    "@byline/admin": "4.8.0",
-    "@byline/core": "4.8.0"
+    "@byline/admin": "4.10.0",
+    "@byline/core": "4.10.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.4",
@@ -65,9 +65,9 @@
     "tsx": "^4.23.1",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10",
-    "@byline/auth": "4.8.0",
-    "@byline/db-conformance": "0.0.2",
-    "@byline/client": "4.8.0"
+    "@byline/auth": "4.10.0",
+    "@byline/db-conformance": "0.0.4",
+    "@byline/client": "4.10.0"
   },
   "publishConfig": {
     "access": "public",