Engines, Versions, and Instance Creation

This page covers exactly what Portside launches, how instance creation works, and how versioned instances coexist.

Engine catalog

Portside launches official engine images as Docker containers. Versions map to Docker tags (the live catalog is src/catalog.json in the repo):

Engine	Versions
MySQL	8.4, 9.7, 26.7
MariaDB	11.4, 11.8, 12.3
Postgres	16, 17
Redis	7, 8
Valkey	8

Multiple versions of the same engine run side by side on different ports. A Postgres 16 and a Postgres 17 container can be active simultaneously; they are separate containers, separate volumes, and separate entries in the instance list.

Instance creation flow

Pick Create instance and set:

1. Engine and version from the catalog above.
2. Port - leave blank for auto-assignment, or pin a fixed port if your tooling expects one.
3. Password - optional. Defaults are portside for SQL engines and empty for Redis/Valkey. The password is applied at container creation and cannot be changed later: to change it, create a new instance (or wipe and recreate).

That is the whole form. Portside generates the container, wires the data volume, tracks the instance in its metadata store, and shows it in the sidebar with its state.

Which port did I get?

Auto-assigned ports come from the container runtime; the instance detail view shows the mapped host port, and Copy connect bakes it into the connect string for you. Pinning a port is useful when an agent's config expects a stable value, but a pinned port blocks instance creation if anything else already holds it.

Connect strings

Two copy buttons appear per instance:

• Copy connect - the localhost socket string using the instance's mapped port, ready to paste into .env, DATABASE_URL, docker-compose overrides, test fixtures, or an agent's config.
• Copy LAN - the laptop-facing string using this machine's LAN IP. Only available for instances with LAN (TLS) enabled; see networking and TLS.

Multiple versions side by side

Because each instance is an independent container plus its own portside-{id}-data volume, upgrade testing is just: create a 16 instance, create a 17 instance, load the same dump into both, compare. There is no shared state between instances and no global "current version" to fight over.

Postgres 17  -> container + portside-pg17-data  -> port 5433
Postgres 16  -> container + portside-pg16-data  -> port 5434
MySQL 8.4    -> container + portside-mysql-data -> port 3306
Redis 8      -> container + portside-redis-data -> port 6379

Instance metadata

Instance metadata (engine, version, port, state, timestamps) lives in SQLite at %LOCALAPPDATA%\portside\portside.db. The actual database data lives in Docker volumes named portside-{id}-data.

The split matters: deleting the metadata store does not delete your data (it lives in Docker volumes), and wiping an instance only removes the volume pair you confirm. The full lifecycle contract is on the data and lifecycle page.

Tail logs

Instance detail includes log tailing, so an agent that "cannot connect" gets diagnosed in one view instead of a docker logs detour.