Database

Start with the storage you can operate

SQLite needs no separate database service and is a practical starting point for a single instance. With no DSN, the server uses memos_prod.db in its data directory. PostgreSQL and MySQL require MEMOS_DRIVER and a matching MEMOS_DSN. Do not point a development or test instance at production data.

Connection and upgrade safety

Use a database account with the permissions the application needs for its own schema, protect network access, and configure TLS according to the database driver's supported options. Schema migrations run during startup. Changing the application version number does not reset database contents or mean the schema number should be changed. Back up before updating and test the intended restore path.

Moving between database engines

Changing MEMOS_DRIVER only changes the connection target; it does not transfer notes, users or attachment data. Plan an explicit data transfer and verify user ownership, timestamps, attachments and access rules before switching traffic. A memo archive export is not a complete database backup.

Select a driver with an explicit DSN

Prepare an empty application database and a dedicated account that can create and migrate its schema. The server supports PostgreSQL URL or keyword DSNs and MySQL URL or compatible tcp DSNs. These sanitized examples illustrate the URL form. Replace every placeholder, percent-encode reserved characters in credentials, and load the actual DSN through your secret mechanism rather than pasting it into a shared terminal or repository. PostgreSQL 17 and MySQL 8.4 are the repository’s network-database CI targets.

# PostgreSQL DSN format, not a real credential:
postgresql://memos:REPLACE_ME@db.example.com:5432/memos?sslmode=verify-full

# MySQL DSN format, not a real credential:
mysql://memos:REPLACE_ME@db.example.com:3306/memos?tls=true

Pass the DSN as a container secret file

For the local Docker image, prepare a file containing only the DSN. It must be readable by the application’s runtime UID/GID (10001 by default). Mount it read-only and set MEMOS_DSN_FILE; do not set MEMOS_DSN at the same time. This is an entrypoint feature, so a native binary needs MEMOS_DSN supplied by its service manager instead. Keep MEMOS_DATA mounted because local attachments still live outside a network database.

docker run -d --name memos-db-test \
  -p 127.0.0.1:5231:5230 \
  -e MEMOS_DRIVER=postgres \
  -e MEMOS_DSN_FILE=/run/secrets/memos-dsn \
  --mount type=bind,src="$PWD/secrets/memos-dsn",dst=/run/secrets/memos-dsn,readonly \
  -v memos-db-test-data:/var/opt/memos   memos:local

docker logs --tail 100 memos-db-test
curl --fail http://127.0.0.1:5231/healthz

Verify identity before adding data

The example uses a separate test container, port and volume. For MySQL change the driver to mysql and supply a MySQL DSN. A healthy process plus a saved-and-reloaded test memo confirms the basic connection path; check the intended database server separately so you do not accidentally validate a different instance. Certificate errors require the correct trust roots/hostname, authentication errors require account grants, and migration errors require the exact startup log. Do not weaken TLS or rewrite schema-version records as a shortcut.