nixos/firefox-syncserver: add PostgreSQL backend support

Titaniumtown · Titaniumtown · commit e4d6d840a673 · 2026-03-21T08:42:59.000-04:00
diff --git a/nixos/doc/manual/release-notes/rl-2511.section.md b/nixos/doc/manual/release-notes/rl-2511.section.md
@@ -398,6 +398,8 @@
 
 - `prosody` gained a config check option named `services.prosody.checkConfig` which runs `prosodyctl check config` and is turned on by default.
 
+- [](#opt-services.firefox-syncserver.database.type) has been added to allow choosing between MySQL/MariaDB (default) and PostgreSQL as the database backend for the Firefox Sync server.
+
 - Revamp of the ACME certificate acquisition and renewal process to help scale systems with lots (100+) of certificates.
 
   Units and targets have been reshaped to better support more specific dependency propagation and avoid
diff --git a/nixos/modules/services/networking/firefox-syncserver.md b/nixos/modules/services/networking/firefox-syncserver.md
@@ -32,6 +32,29 @@ This configuration should never be used in production. It is not encrypted and
 stores its secrets in a world-readable location.
 :::
 
+## Database backends {#module-services-firefox-syncserver-database}
+
+The sync server supports MySQL/MariaDB (the default) and PostgreSQL as database
+backends. Set `database.type` to choose the backend:
+
+```nix
+{
+  services.firefox-syncserver = {
+    enable = true;
+    database.type = "postgresql";
+    secrets = "/run/secrets/firefox-syncserver";
+    singleNode = {
+      enable = true;
+      hostname = "localhost";
+      url = "http://localhost:5000";
+    };
+  };
+}
+```
+
+When `database.createLocally` is `true` (the default), the module will
+automatically enable and configure the corresponding database service.
+
 ## More detailed setup {#module-services-firefox-syncserver-configuration}
 
 The `firefox-syncserver` service provides a number of options to make setting up
diff --git a/nixos/modules/services/networking/firefox-syncserver.nix b/nixos/modules/services/networking/firefox-syncserver.nix
@@ -13,7 +13,21 @@ let
   defaultUser = "firefox-syncserver";
 
   dbIsLocal = cfg.database.host == "localhost";
-  dbURL = "mysql://${cfg.database.user}@${cfg.database.host}/${cfg.database.name}${lib.optionalString dbIsLocal "?socket=/run/mysqld/mysqld.sock"}";
+  dbIsMySQL = cfg.database.type == "mysql";
+  dbIsPostgreSQL = cfg.database.type == "postgresql";
+
+  dbURL =
+    if dbIsMySQL then
+      "mysql://${cfg.database.user}@${cfg.database.host}/${cfg.database.name}${lib.optionalString dbIsLocal "?socket=/run/mysqld/mysqld.sock"}"
+    else
+      "postgres://${cfg.database.user}@${cfg.database.host}/${cfg.database.name}${lib.optionalString dbIsLocal "?host=/run/postgresql"}";
+
+  # postgresql.target waits for postgresql-setup.service (which runs
+  # ensureDatabases / ensureUsers) to complete, avoiding race conditions
+  # where the syncserver starts before its database and role exist.
+  dbService = if dbIsMySQL then "mysql.service" else "postgresql.target";
+
+  syncserver = cfg.package.override { dbBackend = cfg.database.type; };
 
   format = pkgs.formats.toml { };
   settings = {
@@ -22,7 +36,7 @@ let
       database_url = dbURL;
     };
     tokenserver = {
-      node_type = "mysql";
+      node_type = if dbIsMySQL then "mysql" else "postgres";
       database_url = dbURL;
       fxa_email_domain = "api.accounts.firefox.com";
       fxa_oauth_server_url = "https://oauth.accounts.firefox.com/v1";
@@ -41,7 +55,8 @@ let
     };
   };
   configFile = format.generate "syncstorage.toml" (lib.recursiveUpdate settings cfg.settings);
-  setupScript = pkgs.writeShellScript "firefox-syncserver-setup" ''
+
+  mysqlSetupScript = pkgs.writeShellScript "firefox-syncserver-setup" ''
     set -euo pipefail
     shopt -s inherit_errexit
 
@@ -79,6 +94,47 @@ let
     echo "Single-node setup failed"
     exit 1
   '';
+
+  postgresqlSetupScript = pkgs.writeShellScript "firefox-syncserver-setup" ''
+    set -euo pipefail
+    shopt -s inherit_errexit
+
+    schema_configured() {
+      psql -d ${cfg.database.name} -tAc "SELECT EXISTS (SELECT FROM information_schema.tables WHERE table_name = 'services')" | grep -q t
+    }
+
+    update_config() {
+      psql -d ${cfg.database.name} <<'EOF'
+        BEGIN;
+
+        INSERT INTO services (id, service, pattern)
+          VALUES (1, 'sync-1.5', '{node}/1.5/{uid}')
+          ON CONFLICT (id) DO UPDATE SET service = 'sync-1.5', pattern = '{node}/1.5/{uid}';
+        INSERT INTO nodes (id, service, node, available, current_load,
+                           capacity, downed, backoff)
+          VALUES (1, 1, '${cfg.singleNode.url}', ${toString cfg.singleNode.capacity},
+          0, ${toString cfg.singleNode.capacity}, 0, 0)
+          ON CONFLICT (id) DO UPDATE SET node = '${cfg.singleNode.url}', capacity = ${toString cfg.singleNode.capacity};
+
+        COMMIT;
+    EOF
+    }
+
+
+    for (( try = 0; try < 60; try++ )); do
+      if ! schema_configured; then
+        sleep 2
+      else
+        update_config
+        exit 0
+      fi
+    done
+
+    echo "Single-node setup failed"
+    exit 1
+  '';
+
+  setupScript = if dbIsMySQL then mysqlSetupScript else postgresqlSetupScript;
 in
 
 {
@@ -88,25 +144,26 @@ in
         the Firefox Sync storage service.
 
         Out of the box this will not be very useful unless you also configure at least
-        one service and one nodes by inserting them into the mysql database manually, e.g.
-        by running
-
-        ```
-          INSERT INTO `services` (`id`, `service`, `pattern`) VALUES ('1', 'sync-1.5', '{node}/1.5/{uid}');
-          INSERT INTO `nodes` (`id`, `service`, `node`, `available`, `current_load`,
-              `capacity`, `downed`, `backoff`)
-            VALUES ('1', '1', 'https://mydomain.tld', '1', '0', '10', '0', '0');
-        ```
+        one service and one nodes by inserting them into the database manually, e.g.
+        by running the equivalent SQL for your database backend.
 
         {option}`${opt.singleNode.enable}` does this automatically when enabled
       '';
 
       package = lib.mkPackageOption pkgs "syncstorage-rs" { };
 
+      database.type = lib.mkOption {
+        type = lib.types.enum [
+          "mysql"
+          "postgresql"
+        ];
+        default = "mysql";
+        description = ''
+          Which database backend to use for storage.
+        '';
+      };
+
       database.name = lib.mkOption {
-        # the mysql module does not allow `-quoting without resorting to shell
-        # escaping, so we restrict db names for forward compaitiblity should this
-        # behavior ever change.
         type = lib.types.strMatching "[a-z_][a-z0-9_]*";
         default = defaultDatabase;
         description = ''
@@ -117,9 +174,15 @@ in
 
       database.user = lib.mkOption {
         type = lib.types.str;
-        default = defaultUser;
+        default = if dbIsPostgreSQL then defaultDatabase else defaultUser;
+        defaultText = lib.literalExpression ''
+          if database.type == "postgresql" then "${defaultDatabase}" else "${defaultUser}"
+        '';
         description = ''
-          Username for database connections.
+          Username for database connections.  When using PostgreSQL with
+          `createLocally`, this defaults to the database name so that
+          `ensureDBOwnership` works (it requires user and database names
+          to match).
         '';
       };
 
@@ -137,7 +200,8 @@ in
         default = true;
         description = ''
           Whether to create database and user on the local machine if they do not exist.
-          This includes enabling unix domain socket authentication for the configured user.
+          This includes enabling the configured database service and setting up
+          authentication for the configured user.
         '';
       };
 
@@ -237,7 +301,7 @@ in
   };
 
   config = lib.mkIf cfg.enable {
-    services.mysql = lib.mkIf cfg.database.createLocally {
+    services.mysql = lib.mkIf (cfg.database.createLocally && dbIsMySQL) {
       enable = true;
       ensureDatabases = [ cfg.database.name ];
       ensureUsers = [
@@ -250,16 +314,27 @@ in
       ];
     };
 
+    services.postgresql = lib.mkIf (cfg.database.createLocally && dbIsPostgreSQL) {
+      enable = true;
+      ensureDatabases = [ cfg.database.name ];
+      ensureUsers = [
+        {
+          name = cfg.database.user;
+          ensureDBOwnership = true;
+        }
+      ];
+    };
+
     systemd.services.firefox-syncserver = {
       wantedBy = [ "multi-user.target" ];
-      requires = lib.mkIf dbIsLocal [ "mysql.service" ];
-      after = lib.mkIf dbIsLocal [ "mysql.service" ];
+      requires = lib.mkIf dbIsLocal [ dbService ];
+      after = lib.mkIf dbIsLocal [ dbService ];
       restartTriggers = lib.optional cfg.singleNode.enable setupScript;
       environment.RUST_LOG = cfg.logLevel;
       serviceConfig = {
-        User = defaultUser;
-        Group = defaultUser;
-        ExecStart = "${cfg.package}/bin/syncserver --config ${configFile}";
+        User = cfg.database.user;
+        Group = cfg.database.user;
+        ExecStart = "${syncserver}/bin/syncserver --config ${configFile}";
         EnvironmentFile = lib.mkIf (cfg.secrets != null) "${cfg.secrets}";
 
         # hardening
@@ -303,10 +378,19 @@ in
 
     systemd.services.firefox-syncserver-setup = lib.mkIf cfg.singleNode.enable {
       wantedBy = [ "firefox-syncserver.service" ];
-      requires = [ "firefox-syncserver.service" ] ++ lib.optional dbIsLocal "mysql.service";
-      after = [ "firefox-syncserver.service" ] ++ lib.optional dbIsLocal "mysql.service";
-      path = [ config.services.mysql.package ];
-      serviceConfig.ExecStart = [ "${setupScript}" ];
+      requires = [ "firefox-syncserver.service" ] ++ lib.optional dbIsLocal dbService;
+      after = [ "firefox-syncserver.service" ] ++ lib.optional dbIsLocal dbService;
+      path =
+        if dbIsMySQL then [ config.services.mysql.package ] else [ config.services.postgresql.package ];
+      serviceConfig = {
+        ExecStart = [ "${setupScript}" ];
+      }
+      // lib.optionalAttrs dbIsPostgreSQL {
+        # PostgreSQL peer authentication requires the system user to match the
+        # database user. Run as the superuser so we can access all databases.
+        User = "postgres";
+        Group = "postgres";
+      };
     };
 
     services.nginx.virtualHosts = lib.mkIf cfg.singleNode.enableNginx {
diff --git a/nixos/tests/all-tests.nix b/nixos/tests/all-tests.nix
@@ -584,7 +584,7 @@ in
     imports = [ ./firefox.nix ];
     _module.args.firefoxPackage = pkgs.firefox-esr-140;
   };
-  firefox-syncserver = runTest ./firefox-syncserver.nix;
+  firefox-syncserver = discoverTests (import ./firefox-syncserver.nix);
   firefox_decrypt = runTest ./firefox_decrypt.nix;
   firefoxpwa = runTest ./firefoxpwa.nix;
   firejail = runTest ./firejail.nix;
diff --git a/nixos/tests/firefox-syncserver.nix b/nixos/tests/firefox-syncserver.nix
@@ -1,32 +1,54 @@
-{
-  pkgs,
-  ...
-}:
+let
+  makeFirefoxSyncserverTest =
+    name:
+    {
+      backend ? name,
+    }:
+    import ./make-test-python.nix (
+      { lib, pkgs, ... }:
+      {
+        name = "firefox-syncserver-${name}";
 
-{
-  name = "firefox-syncserver";
-  nodes.machine = {
-    services.mysql = {
-      enable = true;
-      package = pkgs.mariadb;
-    };
+        nodes.machine =
+          { pkgs, ... }:
+          lib.mkMerge [
+            {
+              mysql = {
+                services.mysql = {
+                  enable = true;
+                  package = pkgs.mariadb;
+                };
+              };
+              postgresql = { };
+            }
+            .${backend}
 
-    services.firefox-syncserver = {
-      enable = true;
-      secrets = pkgs.writeText "secret" "this-is-a-test";
-      singleNode = {
-        enable = true;
-        hostname = "firefox-syncserver.local";
-        capacity = 1;
-      };
-    };
-  };
+            {
+              services.firefox-syncserver = {
+                enable = true;
+                database.type = backend;
+                secrets = pkgs.writeText "sync-secrets" ''
+                  SYNC_MASTER_SECRET=a-]test-secret-that-is-not-real
+                '';
+                singleNode = {
+                  enable = true;
+                  hostname = "firefox-syncserver.local";
+                  capacity = 1;
+                };
+              };
+            }
+          ];
 
-  testScript = ''
-    machine.wait_for_unit("firefox-syncserver.service")
-    machine.wait_for_open_port(5000)
-
-    machine.wait_until_succeeds("curl --fail http://127.0.0.1:5000")
-
-  '';
+        testScript = ''
+          machine.wait_for_unit("multi-user.target")
+          machine.wait_until_succeeds("systemctl is-active firefox-syncserver.service", timeout=120)
+          machine.wait_for_open_port(5000)
+          machine.wait_until_succeeds("curl --fail http://127.0.0.1:5000")
+        '';
+      }
+    );
+in
+builtins.mapAttrs (k: v: makeFirefoxSyncserverTest k v) {
+  mysql = { };
+  postgresql = { };
 }
