resolute-macros 0.3.0

Compile-time-checked query! macro for resolute.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

# resolute-macros

Proc-macro crate that powers the compile-time checked query macros
re-exported from [`resolute`](../resolute). You usually won't depend
on this crate directly, only through `resolute`.

## What it provides

- **`query!`**: compile-time validated query returning a generated
  row struct. Column types and nullability come from the database.
- **`query_as!`**: same, but mapped into a struct that derives
  `FromRow`.
- **`query_scalar!`**: single-column, single-row convenience.
- **`query_file!` / `query_file_as!` / `query_file_scalar!`**: read
  the SQL from a file (resolved relative to `CARGO_MANIFEST_DIR`).
- **`query_unchecked!`**: escape hatch that skips the live-DB check
  when you need a macro-built query without a schema round-trip.

Named parameters (`:name`) are rewritten to `$N` positional params
at compile time, including in the file-based variants. The rewriter
is aware of `::` casts, string literals, comments, and dollar
quoting, so you won't get false positives from embedded tokens.

## How the compile-time check works

1. Hash the SQL string.
2. Look up the hash in `.resolute/` on disk. If present, use the cached
   metadata and skip the network round-trip.
3. Otherwise, connect to `DATABASE_URL`, send Parse + Describe,
   record the param OIDs and the column (name, OID, nullability)
   tuple, and write a cache file for future offline builds.

`nullable` defaults to `true` and is only flipped to `false` when
the column is pulled from a real table (`pg_attribute.attnotnull`).
Computed columns stay nullable, which means `query!` returns
`Option<T>` for literal projections.

## Environment

| var | meaning |
|---|---|
| `DATABASE_URL` | Required for live describes. `prepare`/`check` via the [`resolute-cli`](../resolute-cli) tool use the same variable. |
| `RESOLUTE_OFFLINE` | When `true`/`1`, never dial out. Fail the build if a query hash isn't in the cache. |

## Architecture

See [`ARCHITECTURE.md`](https://github.com/joshburgess/resolute/blob/main/resolute-macros/ARCHITECTURE.md) for the internals: the macro pipeline, the named-param rewriter (how it handles `::` casts, string literals, comments, and dollar quoting), live describe via pg-wired, nullability inference via `pg_attribute`, the `.resolute/` cache format, and the generated output shape.

## License

Dual licensed under [Apache 2.0](https://github.com/joshburgess/resolute/blob/main/LICENSE-APACHE) or [MIT](https://github.com/joshburgess/resolute/blob/main/LICENSE-MIT). See the [workspace root](https://github.com/joshburgess/resolute#readme) for the broader project.