Get started with databases on MSL

Databases run in an MSL distribution as they do on any Linux machine: install them with the distribution’s package manager and run them as systemd services. A database listening on localhost in the distribution is reachable on localhost on macOS, so tools on either side can connect.

This guide uses Ubuntu. Other distributions have the same databases under their own package names.

Prerequisites

• MSL with a distribution installed. See Install MSL.
• systemd enabled in the distribution, so databases run as services. Ubuntu’s WSL images enable it already. See Use systemd to manage services.

PostgreSQL

Install it:

$ sudo apt update
$ sudo apt install postgresql

The package starts PostgreSQL as a service, listening on 127.0.0.1:5432. Check it:

$ systemctl is-active postgresql
active
$ sudo -u postgres psql -c 'select version()'

Create a user and a database

$ sudo -u postgres createuser --pwprompt $USER
$ sudo -u postgres createdb --owner $USER myapp
$ psql -h localhost myapp

-h localhost connects over TCP with the password you set. Without it, psql uses the Unix socket and Ubuntu’s peer authentication, which works for the Linux user of the same name.

Connect from macOS

Port 5432 is forwarded to localhost on macOS while the distribution runs. Any PostgreSQL client or GUI tool on the Mac can connect to localhost:5432 with the user and password you created:

$ psql -h localhost -U <your Linux user> myapp        # on macOS, if you have psql there

If a PostgreSQL server already runs on macOS on port 5432, MSL can’t forward the port, and it logs that in ~/Library/Application Support/msl/msld.log. Stop one of them, or change port in the distribution’s postgresql.conf. See Networking considerations.

SQLite

SQLite is a library and a file, with no server to run:

$ sudo apt install sqlite3
$ sqlite3 ~/myapp.db 'create table notes (body text)'

Keep database files in the Linux home directory rather than under /mnt/macos, where file access is slower. See Working across file systems.

Other databases

MySQL, MariaDB, Redis and other servers packaged by your distribution install the same way: install the package, check its service with systemctl, and connect to its port on localhost from macOS. This guide was tested with PostgreSQL.

Keep a database running

A distribution stops 15 seconds after its last msl session ends: the last shell, msl -e command or VS Code window. A running database doesn’t keep it running, so closing your last terminal stops the database cleanly with the distribution. It starts again with the distribution.

To keep it running with no terminal open, turn off the idle stop in ~/.mslconfig on macOS:

[general]
instanceIdleTimeout = -1

Run msl --shutdown for the change to apply. The VM then keeps its memory until you run msl --shutdown. See Advanced settings configuration.

Back up a database

Use the database’s own dump tool, such as pg_dump, and copy the dump to macOS through /mnt/macos:

$ pg_dump myapp > /mnt/macos/Users/<you>/Backups/myapp.sql

To back up the whole distribution instead, use msl --export, or msl --export --vhd for a copy of its disk. See Import any Linux distribution.

Durability

A committed transaction is on the Mac’s SSD: the database’s fsync is flushed there, as on Linux. The exception is a distribution whose disk was added while another distribution was running (df / shows /dev/loop…): until the VM restarts, its fsync reaches only macOS’s file cache, so a macOS crash or power loss can lose recent commits. Run msl --shutdown to end that state, and keep dumps of data you can’t recreate. See Durability.