feat: splice SQL fragments into a statement's sentinel comments

.devcontainer/devcontainer.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://raw.githubusercontent.com/devcontainers/spec/refs/heads/main/schemas/devContainer.base.schema.json",
+  "name": "sqlx-query",
+  "service": "workspace",
+  "dockerComposeFile": "docker-compose.yml",
+  "workspaceFolder": "/home/vscode/workspace",
+  "features": {
+    "ghcr.io/devcontainers/features/nix:1": {
+      // Single-user install. The feature defaults to multiUser, which runs
+      // post-install steps through the nix-daemon — but a Docker build layer
+      // has no init system to start one, so those steps fail with
+      // "opening lock file /nix/var/nix/db/big-lock: Permission denied".
+      // A single-user store owned by vscode needs no daemon, and is what the
+      // /nix volume and the postStartCommand chown below already assume.
+      "multiUser": false,
+      "extraNixConfig": "experimental-features = nix-command flakes"
+    }
+  },
+  // The single definition of the test database. Inside the container this
+  // resolves over the compose network; on the host, `devcontainer-env export`
+  // rewrites it to the port Docker assigned. `containerEnv` rather than
+  // `remoteEnv` because only the former applies to every process, which is
+  // what devcontainer-env reads.
+  "containerEnv": {
+    "DATABASE_URL": "postgres://vscode@postgres:5432/sqlx_query_test?sslmode=disable"
+  },
+  "mounts": [
+    "source=${localWorkspaceFolderBasename}-nix,target=/nix,type=volume",
+    "source=${localWorkspaceFolderBasename}-cache,target=/home/vscode/.cache,type=volume",
+    "source=${localWorkspaceFolderBasename}-cargo,target=/home/vscode/.cargo,type=volume"
+  ],
+  // Every volume stays *outside* the workspace. Mounting one at
+  // workspace/target would create that directory inside the bind mount, owned
+  // by the container's uid -- and CI runs cargo on the runner itself, where
+  // that is a different uid and `target/` becomes unwritable.
+  "postStartCommand": "sudo chown vscode:vscode /nix /home/vscode/.cache /home/vscode/.cargo",
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "terminal.integrated.defaultProfile.linux": "default",
+        "terminal.integrated.profiles.linux": {
+          "default": {
+            "path": "nix",
+            "args": ["develop"]
+          }
+        }
+      }
+    }
+  }
+}

.devcontainer/docker-compose.yml

@@ -0,0 +1,27 @@
+services:
+  workspace:
+    image: mcr.microsoft.com/devcontainers/base:bookworm
+    command: sleep infinity
+    volumes:
+      - ..:/home/vscode/workspace:cached
+
+  # What tests/postgres.rs runs against. `trust` auth is safe only because this
+  # is never reachable off the machine -- see the port note below.
+  postgres:
+    image: postgres:18-bookworm
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: vscode
+      POSTGRES_DB: sqlx_query_test
+      POSTGRES_HOST_AUTH_METHOD: trust
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready"]
+      interval: 1s
+      timeout: 5s
+      retries: 10
+    # Bare `5432`, not "5432:5432": Docker assigns a random host port, so two
+    # projects can run at once without colliding. `devcontainer-env export`
+    # finds the assigned port and rewrites DATABASE_URL to match, which is what
+    # lets the flake and CI share one definition of it.
+    ports:
+      - 5432

.github/config/release-please-config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "packages": {
+    ".": {
+      "release-type": "rust",
+      "include-v-in-tag": true,
+      "include-v-in-release-name": true,
+      "include-component-in-tag": false
+    }
+  }
+}

.github/config/release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.0.0"
+}

.github/dependabot.yml

@@ -0,0 +1,30 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    groups:
+      all-github-actions:
+        patterns: ["*"]
+    labels:
+      - "dependencies"
+      - "auto-merge"
+    commit-message:
+      prefix: "chore"
+      include: "scope"
+  - package-ecosystem: "cargo"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    groups:
+      all-cargo:
+        patterns: ["*"]
+    labels:
+      - "dependencies"
+      - "auto-merge"
+    commit-message:
+      prefix: "chore"
+      include: "scope"

.github/workflows/ci.yml

@@ -0,0 +1,99 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      # Brings up .devcontainer/docker-compose.yml -- including the Postgres
+      # tests/postgres.rs runs against -- and tears it down in a post-step even
+      # if the job is cancelled. DATABASE_URL is not set here: the shell hook
+      # gets it from `devcontainer-env export`, so it is defined once, in
+      # devcontainer.json.
+      #
+      # Nix then runs on the runner itself rather than inside the container.
+      # Building the devcontainer anyway is what keeps its definition honest --
+      # a broken one fails CI instead of only failing the next contributor.
+      - name: Setup Devcontainer
+        uses: devcontainer-env/devcontainer-ci@v1
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@v22
+      - name: Setup Nix Cache
+        uses: DeterminateSystems/magic-nix-cache-action@v14
+        with:
+          use-flakehub: disabled
+          use-gha-cache: enabled
+      - name: Check Formatting
+        run: nix develop --command cargo fmt --check
+      - name: Lint
+        run: nix develop --command cargo clippy --all-targets
+      - name: Run Tests
+        run: nix develop --command cargo test
+      - name: Check Documentation
+        run: nix develop --command cargo doc --no-deps
+        env:
+          RUSTDOCFLAGS: -D warnings
+  release:
+    needs: test
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+    timeout-minutes: 15
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Create Release PR
+        id: release
+        uses: googleapis/release-please-action@v5
+        with:
+          manifest-file: .github/config/release-please-manifest.json
+          config-file: .github/config/release-please-config.json
+          target-branch: main
+  # No `build` job: this is a library crate with no binary, so there is nothing
+  # to `nix build` and no asset to attach to the release. The crate itself is
+  # the artifact, and it goes to crates.io below.
+  publish:
+    needs: release
+    if: ${{ needs.release.outputs.release_created }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@v22
+      - name: Setup Nix Cache
+        uses: DeterminateSystems/magic-nix-cache-action@v14
+        with:
+          use-flakehub: disabled
+          use-gha-cache: enabled
+      - name: Authenticate with Crates.io
+        uses: rust-lang/crates-io-auth-action@v1
+        id: auth
+      - name: Publish to Crates.io
+        run: nix develop --command cargo publish
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ steps.auth.outputs.token }}

.github/workflows/merge.yml

@@ -0,0 +1,26 @@
+name: Auto Merge
+
+on:
+  pull_request:
+    types: [opened, reopened, labeled, synchronize]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  merge:
+    if: contains(github.event.pull_request.labels.*.name, 'auto-merge')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    timeout-minutes: 5
+    steps:
+      - name: Enable auto-merge
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_URL: ${{ github.event.pull_request.html_url }}
+        run: |
+          gh pr review --approve "$PR_URL" || echo "PR approval skipped or failed."
+          gh pr merge --auto --squash "$PR_URL"

.github/workflows/update.yml

@@ -0,0 +1,37 @@
+name: Update Flake Locks
+on:
+  schedule:
+    - cron: "0 0 * * 1"
+  workflow_dispatch:
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Generate App token
+        id: app-token
+        uses: actions/create-github-app-token@v3
+        with:
+          client-id: ${{ vars.APP_CLIENT_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@v22
+      - name: Setup Nix Cache
+        uses: DeterminateSystems/magic-nix-cache-action@v13
+        with:
+          use-flakehub: disabled
+          use-gha-cache: enabled
+      - name: Update root flake.lock
+        uses: DeterminateSystems/update-flake-lock@v28
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          pr-title: "chore(flake): update flake.lock"
+          pr-labels: |
+            dependencies
+            auto-merge
+          commit-msg: "chore(flake): update flake.lock"

.gitignore

@@ -0,0 +1,10 @@
+/target
+Cargo.lock
+
+# Nix build outputs and direnv's cached shell. flake.lock IS committed.
+result
+result-*
+.direnv/
+
+# macOS
+.DS_Store

Cargo.toml

@@ -0,0 +1,40 @@
+[package]
+name = "sqlx-query"
+version = "0.0.0"
+edition = "2024"
+# Not a choice: sqlx 0.9 declares it, and the tests build against it. The
+# library itself would compile on far older, but a crate in this set that
+# claimed a lower MSRV than its siblings would be a promise nothing checks.
+rust-version = "1.94"
+license = "MIT"
+description = "Splices SQL fragments into the sentinel comments of a query, for sqlx."
+repository = "https://github.com/sqlx-contrib/sqlx-query"
+keywords = ["sql", "sqlx", "postgres", "query", "filter"]
+categories = ["database"]
+
+# Denied rather than warned, because several consumers in this ecosystem deny
+# pedantic at the workspace level: a lint this crate tolerates is a lint they
+# cannot.
+[lints.clippy]
+all = { level = "deny", priority = -1 }
+pedantic = { level = "deny", priority = -1 }
+
+# No dependencies, deliberately. This crate takes a `&str` and returns a
+# `String`; it does not need sqlx to do that, and a caller splicing into a
+# hand-written query should not acquire a database driver for the privilege.
+# The name says where it belongs, not what it links against.
+[dependencies]
+
+[dev-dependencies]
+# For tests/postgres.rs alone -- the round trip is the only thing here that
+# needs a database, and it is the only thing text assertions cannot stand in
+# for.
+sqlx = { version = "0.9", default-features = false, features = [
+  "postgres",
+  "runtime-tokio",
+] }
+tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sqlx-contrib
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.