alt-mysql/docs/superpowers/specs/2026-07-05-native-port-takeover-design.md

# Design: Native MariaDB Port Takeover for alt-mariadb on Port 3306

Date: 2026-07-05
Status: Approved by user, ready for implementation planning

## Goal

Let `install_db.sh` install `alt-mariadb` on the standard MySQL/MariaDB port (3306) by
first moving DirectAdmin's existing CustomBuild-managed native MariaDB off that port, so
that any tool or script that assumes the default port can reach `alt-mariadb` without
custom port configuration.

## Background

`install_db.sh` currently requires `alt-mariadb`'s port as a mandatory CLI argument
(defaulting nowhere, e.g. `install_db.sh 10.11 33033`), and its own `validate_paths()`
explicitly rejects a port that matches DirectAdmin's native engine's port. Native MariaDB
(installed and managed by CustomBuild) occupies 3306 today.

Earlier in this project's design work, a different port-3306 proposal was considered and
rejected: pointing DirectAdmin's own `mysql.conf` *at* `alt-mariadb` itself. That failed
because DirectAdmin's legacy-code-base license enforces a hard MariaDB-version ceiling
(10.6) at login time, independent of CustomBuild settings, and `alt-mariadb` intentionally
runs newer versions.

This design is different and does not hit that problem: DirectAdmin keeps talking to the
*same* native engine, on the *same* version — only the TCP port that engine listens on
changes. The freed port 3306 then goes to `alt-mariadb`.

The user confirmed empirically, on the actual target server, that setting
`mysql_inst=no` in CustomBuild's `options.conf` and then changing the native port in
`/etc/my.cnf` survives a `./build rewrite_confs` run — i.e., once MySQL/MariaDB is marked
as externally-managed, CustomBuild's config-regeneration sweep no longer touches it. This
is the key fact that makes a manual, persistent port change safe here (CustomBuild's
per-service `rewrite_confs` logic is gated on it considering that service "managed").

## Scope

- Applies only to a **fresh `alt-mariadb` install** (`install_db.sh`'s normal use case) —
  not to migrating an already-running `alt-mariadb` instance to a new port. Native MariaDB
  is always already running at the time `install_db.sh` runs (DirectAdmin itself is
  already installed), so the "live service surgery" risk is entirely on the native side,
  never the `alt-mariadb` side.
- Runs only on **AlmaLinux 8 or 9**. CloudLinux, Rocky, CentOS, plain RHEL, and AlmaLinux
  outside 8/9 are explicitly refused before anything is touched — a stricter, separate
  check from `install_db.sh`'s own permissive `detect_os()`, because this script touches a
  live, DA-critical service rather than just installing an additional one.
- This is a materially one-way decision: `mysql_inst=no` has no clean, officially
  documented path back to CustomBuild-managed MySQL once other things start depending on
  the new arrangement. The design rolls back cleanly on failure *during the takeover
  itself*, but is not meant to be casually reversed afterward.

## CLI change to `install_db.sh`

`PORT` becomes optional. Usage becomes `install_db.sh <MARIADB_VERSION> [PORT]`:

- `install_db.sh 10.11` — `PORT` defaults to `3306`, triggering the native takeover.
- `install_db.sh 10.11 3306` — same as above; the trigger is the *resolved* port value,
  not whether it was typed explicitly.
- `install_db.sh 10.11 33033` — explicit non-3306 port, no takeover, today's behavior is
  unchanged.

`apply_cli_args` changes from requiring exactly 2 arguments to accepting 1 or 2 (still
requires at least `MARIADB_VERSION`). Usage text and examples must reflect the new
optional-port form.

## Architecture

A new, independent script, `scripts/setup/native_mariadb_port_takeover.sh`, holds all
logic for moving native MariaDB off 3306. `install_db.sh` calls it once, early in
`main()`, only when the resolved `PORT` is `3306` — before `load_da_credentials`, so that
by the time DA's credentials are read, `mysql.conf` already reflects the *new* native port
and the existing "alt port must differ from DA's port" check in `validate_paths()` passes
naturally with no changes needed there.

This mirrors how every other multi-step, risk-bearing operation in this plugin is
isolated into its own file (`da_restore_native_staging_to_alt_mysql.sh`,
`alt_mysql_native_backup_restore.sh`, `mysql_upgrade.sh`) rather than growing the already
large `install_db.sh` further, and keeps this logic independently testable with fake
command stubs.

## Configuration

Top-of-file variables in the new script, in the same "hand-editable config block"
convention already used by `install_db.sh` (e.g. `MARIADB_TARBALL_URL`):

- `NATIVE_MY_CNF` (default `/etc/my.cnf`)
- `NATIVE_MY_CNF_D` (default `/etc/my.cnf.d`)
- `NATIVE_MYSQL_CONF` (default `/usr/local/directadmin/conf/mysql.conf`)
- `NEW_NATIVE_PORT` (default `3307`)

## Sequencing

### Step 0: OS guard

Read `/etc/os-release`. Require `ID=almalinux` and `VERSION_ID` starting with `8` or `9`.
Anything else: `die()` immediately, before any other action.

### Step 1: Baseline check

Read DA's current native port/socket/credentials from `NATIVE_MYSQL_CONF` (reuse the
`mysql.conf` parsing convention already used elsewhere in this plugin). Confirm the native
engine is actually reachable right now using those credentials — abort before touching
anything if it isn't (this script must not appear to "fix" an unrelated pre-existing
problem). Also read the *current* `mysql_inst=` value from CustomBuild's `options.conf`
and record it (`mariadb` or `mysql`) — this is what rollback restores.

### Step 2: Idempotency check

If the current native port (from Step 1) is already something other than 3306, log
"already done" and exit 0. Nothing further to do.

### Step 3: Preflight the new port

Confirm `NEW_NATIVE_PORT` is not already bound by anything (reuse `install_db.sh`'s
`port_is_listening` pattern). Refuse before making any change if it is.

### Step 4: Disable CustomBuild's MySQL management

Run `da build set mysql_inst no` — DirectAdmin's supported CLI, not a raw edit of
`options.conf`. Skip if Step 1 already found it set to `no` (idempotency).

### Step 5: Locate, back up, and rewrite the active `port=` directive(s)

Scan `NATIVE_MY_CNF` and every `NATIVE_MY_CNF_D/*.cnf` for a `port=` line inside a
`[mysqld]`/`[mariadb]`/`[server]` section (later-loaded `my.cnf.d` files override
`my.cnf`'s own value for the same directive — both must be checked, not just one). Back up
every file before editing it (timestamped copy, matching `install_db.sh`'s
`backup_existing_file` convention). If no explicit `port=` line exists anywhere (implicit
default), add one to `[mysqld]` in `NATIVE_MY_CNF`. If matches exist, rewrite each to
`NEW_NATIVE_PORT`.

### Step 6: Update `mysql.conf`

Rewrite only the `port=` field in `NATIVE_MYSQL_CONF` to `NEW_NATIVE_PORT`, via a targeted
line replacement — not full-file regeneration — so `user=`/`passwd=`/`host=`/`socket=` are
left untouched exactly as they were.

### Step 7: Restart native MariaDB

Restart the native MariaDB service (reuse `mysql_service_name()`-style detection). Verify
it is listening on `NEW_NATIVE_PORT` and specifically **not** on 3306.

### Step 8: Restart DirectAdmin

Restart the `directadmin` service so DA's core picks up the new port immediately, rather
than relying on an unconfirmed lazy-reload behavior. This causes a brief (seconds-long)
panel interruption — expected, not a failure.

### Step 9: Verify DA's own connectivity

Confirm DA's credentials (from the now-updated `mysql.conf`) can connect to the native
engine on `NEW_NATIVE_PORT`. This is the real pass/fail gate for the whole operation.

Only if Step 9 succeeds does `install_db.sh` continue installing `alt-mariadb`, now
targeting port 3306 (already free).

## Error handling and rollback

Any failure at Step 4 or later triggers rollback of everything done so far, in reverse
order, before the script aborts non-zero:

- Restore every file backed up in Step 5 from its timestamped copy.
- Run `da build set mysql_inst <original_value>` (the value captured in Step 1) to restore
  CustomBuild management.
- Attempt to restart native MariaDB back on 3306; verify it's reachable again via the
  *original* credentials/port.
- If DirectAdmin was already restarted (Step 8+), restart it again so it re-picks-up the
  reverted config, then verify reachability.

The script logs clearly what it reverted and always exits non-zero on any rollback path.
`install_db.sh` must not proceed to installing `alt-mariadb` if this script exits non-zero,
for any reason. One exception: if Step 9 fails only because DirectAdmin itself won't
restart cleanly (unrelated to the port change), the script should say so explicitly rather
than reporting it as a takeover failure.

## Testing

Matching this repo's established convention (plain bash test scripts under `tests/`, fake
command stubs via `PATH`/env-var injection, no external test framework): a new
`tests/native_mariadb_port_takeover_test.sh` fakes `da`, `systemctl`, and the
`mysql`/`mariadb` client binaries as stub scripts that log their invocations, plus fixture
copies of `/etc/my.cnf`, `/etc/my.cnf.d/*.cnf`, and `mysql.conf` under a temp directory (all
overridable via the script's own env vars, same pattern as `alt_mysql_native_backup_restore.sh`'s
tests). Scenarios:

- Happy path: native on 3306 → ends up on 3307, `mysql.conf` updated, exit 0.
- Idempotency: native already on 3307 → no-op, exit 0, no file changes.
- OS guard: non-AlmaLinux or AlmaLinux outside 8/9 → refuses immediately, no files touched.
- Preflight rejection: `NEW_NATIVE_PORT` already in use → refuses before any change.
- Rollback: simulate failure at each of Steps 5 through 9 in turn → confirm every backed-up
  file is restored and `da build set mysql_inst <original>` is called with the correct
  original value in each case.

## Out of scope

- Migrating an already-running `alt-mariadb` instance to a new port (not needed — this
  server has no `alt-mariadb` installed yet).
- Any OS other than AlmaLinux 8/9.
- A documented path back to CustomBuild-managed MySQL/MariaDB after this runs.
- Changing `/etc/services` or CSF/firewall rules (native MariaDB is not intended to be
  remotely reachable; out of scope unless that changes).

## Risks / open items for implementation planning

- The exact `[mysqld]`/`[mariadb]`/`[server]` section name in use on this server's
  `/etc/my.cnf.d/*.cnf` files should be confirmed empirically during implementation (grep
  the actual files) rather than assumed, since MariaDB accepts more than one section name
  for the same server-level directives.
- `da build set mysql_inst no` and its reverse are assumed to be synchronous, side-effect-free
  writes to `options.conf` with no network/build side effects; this should be confirmed
  empirically (e.g. by diffing `options.conf` before/after and confirming no other files
  change) during the first implementation task, consistent with how this project has
  handled other empirically-verified-not-documented DirectAdmin behaviors.