From 1921aafe9ab2180f7e8e066b82b6201232b34075 Mon Sep 17 00:00:00 2001
From: 81reap <prayag.bhakar@gmail.com>
Date: Wed, 23 Sep 2026 22:18:29 -0400
Subject: [PATCH] feat(nix) :: add a development shell

Adds an optional dev shell with all of the tools needed to build SQLPage at the same versions the CI uses.

If you have nix installed or use NixOS you can now run ::
(1) `nix develop` :: assumes the dev shell
(2) `nix fmt` :: runs rustfmt, biome, and nixfmt
(3) `nix run .#test-rust`
(4) `nix run .#test-browser`
(5) `nix run .#test-examples`
(6) `nix flake check`
---
 .envrc          |   1 +
 .gitignore      |   2 +
 CONTRIBUTING.md |  16 +++
 flake.lock      |  48 +++++++++
 flake.nix       | 251 ++++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 318 insertions(+)
 create mode 100755 .envrc
 create mode 100755 flake.lock
 create mode 100644 flake.nix

diff --git a/.envrc b/.envrc
new file mode 100755
index 00000000..3550a30f
--- /dev/null
+++ b/.envrc
@@ -0,0 +1 @@
+use flake
diff --git a/.gitignore b/.gitignore
index 1a2971ca..ba180f3f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,3 +15,5 @@ sqlpage/sqlpage.db
 tests_uploads/
 /test-results/
 /playwright-report/
+/result
+.direnv/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 43487637..ce81efe0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -48,6 +48,22 @@ or depend on having one already installed on the system where it is running (dyn
 
 Windows comes with ODBC pre-installed; SQLPage cannot statically link to the unixODBC driver manager on windows.
 
+### (Optional) Nix Dev Shell
+
+If you have [Nix](https://nixos.org/download/) with flakes enabled, `nix develop` drops you into a dev shell with everything needed to build and test SQLPage.
+
+If you use [direnv](https://direnv.net/), `direnv allow` is a one time command to auto assume the shell when you enter the dir.
+
+| Command | What it runs |
+| --- | --- |
+| `nix fmt` | rustfmt, Biome, and nixfmt |
+| `nix flake check` | the formats all files |
+| `nix run .#lint-rust` | `cargo fmt --check` and `cargo clippy` |
+| `nix run .#test-rust` | the Rust test suites |
+| `nix run .#test-browser` | the Playwright suites |
+| `nix run .#test-examples` | the Hurl suite |
+| `nix build .#odbc-drivers` | builds an `odbcinst.ini`; point `ODBCSYSINI` at it to run the ODBC tests |
+
 ## Code Style and Linting
 
 ### Rust
diff --git a/flake.lock b/flake.lock
new file mode 100755
index 00000000..1cdfb70f
--- /dev/null
+++ b/flake.lock
@@ -0,0 +1,48 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1790046670,
+        "narHash": "sha256-MYiI+CzL0tuWgRPjGsKCDHqYs2T3OzMlMQWOYWG0qso=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "6774f7bc253789b113a4f39285dc0fa100abeacc",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs",
+        "rust-overlay": "rust-overlay"
+      }
+    },
+    "rust-overlay": {
+      "inputs": {
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1790149037,
+        "narHash": "sha256-01WcSplVEmQt13QUZLfWez27JO+2lyYWX+yTitvkF3g=",
+        "owner": "oxalica",
+        "repo": "rust-overlay",
+        "rev": "fb058ecf6d14837ea152a3d5225ce7f88ee5cde1",
+        "type": "github"
+      },
+      "original": {
+        "owner": "oxalica",
+        "repo": "rust-overlay",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}
diff --git a/flake.nix b/flake.nix
new file mode 100644
index 00000000..def67e21
--- /dev/null
+++ b/flake.nix
@@ -0,0 +1,251 @@
+{
+  description = "Optional development environment for SQLPage";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    # Ships the official rustup binaries, so the toolchain in this shell is
+    # the same build CI and the release use, down to the bundled LLVM.
+    rust-overlay.url = "github:oxalica/rust-overlay";
+    rust-overlay.inputs.nixpkgs.follows = "nixpkgs";
+  };
+
+  outputs =
+    {
+      self,
+      nixpkgs,
+      rust-overlay,
+    }:
+    let
+      inherit (nixpkgs) lib;
+
+      systems = [
+        "aarch64-darwin"
+        "aarch64-linux"
+        "x86_64-linux"
+      ];
+
+      # Oracle governs its own client library by licence, so nixpkgs marks it
+      # unfree. Naming it here keeps every other package in this flake free.
+      unfreePackages = [ "oracle-instantclient" ];
+
+      forEachSystem =
+        build:
+        lib.genAttrs systems (
+          system:
+          build (
+            import nixpkgs {
+              inherit system;
+              config.allowUnfreePredicate = package: builtins.elem (lib.getName package) unfreePackages;
+              overlays = [ rust-overlay.overlays.default ];
+            }
+          )
+        );
+
+      cargoEdition = (lib.importTOML ./Cargo.toml).package.edition;
+
+      lockedPlaywrightVersion =
+        (lib.importJSON ./package-lock.json).packages."node_modules/playwright-core".version;
+
+      formatterFor =
+        pkgs:
+        pkgs.treefmt.withConfig {
+          runtimeInputs = [
+            pkgs.biome
+            pkgs.nixfmt
+            pkgs.rustfmt
+          ];
+          settings = {
+            on-unmatched = "info";
+            formatter = {
+              nixfmt = {
+                command = "nixfmt";
+                includes = [ "*.nix" ];
+              };
+              rustfmt = {
+                command = "rustfmt";
+                options = [
+                  "--edition"
+                  cargoEdition
+                ];
+                includes = [ "*.rs" ];
+              };
+              biome = {
+                command = "biome";
+                options = [
+                  "format"
+                  "--write"
+                  "--no-errors-on-unmatched"
+                ];
+                includes = [
+                  "*.css"
+                  "*.js"
+                  "*.json"
+                  "*.jsonc"
+                  "*.mjs"
+                  "*.ts"
+                ];
+              };
+            };
+          };
+        };
+
+      rustToolchainFor = pkgs: pkgs.rust-bin.fromRustupToolchainFile ./rust-toolchain.toml;
+
+      # odbc-sys links against a driver manager, and the C sources vendored by
+      # aws-lc-sys, libsqlite3-sys and zstd-sys need a compiler. Nothing here
+      # reaches for OpenSSL: SQLPage speaks TLS through rustls.
+      cargoRuntime = pkgs: [
+        (rustToolchainFor pkgs)
+        pkgs.stdenv.cc
+        pkgs.unixodbc
+      ];
+      # The database matrix runs prebuilt test binaries that link the unixODBC
+      # driver manager statically. It still reads ODBCSYSINI at run time and
+      # dlopens whatever absolute path this file names, so pointing that one
+      # variable at the store replaces every driver install step.
+      odbcDriversFor =
+        pkgs:
+        pkgs.runCommand "sqlpage-odbc-drivers" { } ''
+          mkdir -p "$out"
+          oracleDriver=(${lib.getLib pkgs.oracle-instantclient}/lib/libsqora.so.*)
+          cat > "$out/odbcinst.ini" <<INI
+          [PostgreSQL Unicode]
+          Driver = ${pkgs.unixodbcDrivers.psql}/${pkgs.unixodbcDrivers.psql.driver}
+
+          [Oracle 21 ODBC driver]
+          Driver = ''${oracleDriver[0]}
+          INI
+        '';
+
+      cargoEnv = pkgs: {
+        LIBRARY_PATH = "${pkgs.unixodbc}/lib";
+      };
+
+      # Playwright is installed via npm, we we need to set the browser paths.
+      playwrightEnv = pkgs: {
+        PLAYWRIGHT_BROWSERS_PATH = "${pkgs.playwright-driver.browsers}";
+        PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD = "1";
+        PLAYWRIGHT_SKIP_VALIDATE_HOST_REQUIREMENTS = "true";
+      };
+
+      gatesFor =
+        pkgs:
+        lib.mapAttrs
+          (
+            name:
+            {
+              description,
+              packages ? [ ],
+              env ? { },
+              script,
+            }:
+            pkgs.writeShellApplication {
+              inherit name;
+              runtimeInputs = [ pkgs.git ] ++ packages;
+              runtimeEnv = env;
+              meta = { inherit description; };
+              text = ''
+                cd "$(git rev-parse --show-toplevel)"
+              ''
+              + script;
+            }
+          )
+          {
+            lint-rust = {
+              description = "Check Rust formatting and deny every clippy warning";
+              packages = cargoRuntime pkgs;
+              env = cargoEnv pkgs;
+              script = ''
+                cargo fmt --all -- --check
+                cargo clippy --all-targets --all-features -- -D warnings
+              '';
+            };
+
+            test-rust = {
+              description = "Run the Rust test suites against DATABASE_URL, or SQLite when it is unset";
+              packages = cargoRuntime pkgs;
+              env = cargoEnv pkgs;
+              script = ''
+                cargo test "$@"
+              '';
+            };
+
+            test-browser = {
+              description = "Drive the components in a browser with Playwright";
+              packages = [ pkgs.nodejs_26 ] ++ cargoRuntime pkgs;
+              env = cargoEnv pkgs // playwrightEnv pkgs;
+              script = ''
+                npm ci --ignore-scripts
+                npm run build
+                cd tests/end-to-end
+                npx playwright test "$@"
+              '';
+            };
+
+            test-examples = {
+              description = "Run the Hurl suite of an example against its own containers";
+              packages = [ pkgs.hurl ];
+              script = ''
+                scripts/test-examples-hurl.sh "$@"
+              '';
+            };
+          };
+    in
+    {
+      packages = forEachSystem (pkgs: {
+        odbc-drivers = odbcDriversFor pkgs;
+      });
+
+      formatter = forEachSystem formatterFor;
+
+      checks = forEachSystem (pkgs: {
+        formatting = (formatterFor pkgs).check self;
+      });
+
+      apps = forEachSystem (
+        pkgs:
+        lib.mapAttrs (_: gate: {
+          type = "app";
+          program = lib.getExe gate;
+          inherit (gate) meta;
+        }) (gatesFor pkgs)
+      );
+
+      devShells = forEachSystem (
+        pkgs:
+        assert lib.assertMsg (lockedPlaywrightVersion == pkgs.playwright-driver.version)
+          "package-lock.json pins Playwright ${lockedPlaywrightVersion}, but nixpkgs ships ${pkgs.playwright-driver.version}. Playwright only drives the browsers its own release shipped with, so run `nix flake update` or realign package-lock.json.";
+        {
+          default = pkgs.mkShell {
+            name = "sqlpage";
+
+            packages =
+              (with pkgs; [
+                biome
+                hurl
+                nodejs_26
+                pkg-config
+                sqlite
+              ])
+              ++ cargoRuntime pkgs
+              ++ [ (formatterFor pkgs) ]
+              ++ lib.attrValues (gatesFor pkgs);
+
+            buildInputs = with pkgs; [
+              unixodbc
+              zstd
+            ];
+
+            # DATABASE_URL and LISTEN_ON stay unset on purpose. SQLPage reads
+            # both from the environment, so exporting them here would override
+            # every example and test fixture that ships its own configuration.
+            env = {
+              RUST_SRC_PATH = "${rustToolchainFor pkgs}/lib/rustlib/src/rust/library";
+              ZSTD_SYS_USE_PKG_CONFIG = "1";
+            }
+            // playwrightEnv pkgs;
+          };
+        }
+      );
+    };
+}