Tuning without code

4 / 11 · overrides in the full document · PDF

The SQL of any query of a view can be replaced by a file a DBA writes, with no change to the application. Because rows are decoded by alias, an override only has to select the aliases the view decodes and take the keys of the rows above. When the registry is built, every query — generated or overridden — is prepared on the database, without running, and its columns and parameters are compared with the view, so a wrong override stops the application at startup rather than corrupting a result later.

Three columns. A DBA writes SQL: an overrides/TaskView.toml file replacing the notes query with a join to note_visible, taking ANY(:keys), with shadow = true; notes below: one file per view, any query by its path, the aliases the view decodes, the keys of the rows above. Build checks every query: the builder registers the view and builds, every query is prepared without running, and compared with the view; the diagnostics M0100 to M0105 and M0301 are listed; errors stop the build with Error::Invalid, or on_invalid(UseGenerated) runs the generated query instead. Loads run the registry: an immutable registry; shadow mode runs both queries and logs differences; reload swaps checked files in atomically; nested arguments wrap an override as a subquery; writes never use overrides. Along the bottom, the command line tool without a Rust toolchain: Builder::manifest(), mabat check, mabat explain, mabat scaffold.

Files, by view and by query. A registry, Mabat::builder().register::<T>()…build(&mut conn), runs views with override SQL for any of their queries, from files or strings MPA-OVR-1. A view has at most one file, TaskView.toml or TaskView.sql MPA-OVR-2. An override must select the aliases the view decodes MPA-OVR-3, and a child query must take the keys of the rows above, as :keys on any database or $1 on PostgreSQL MPA-OVR-4. A stored procedure or a view in the database is as good as any other SQL, as long as it returns those aliases.

Checked at startup. check and build prepare every query on the database without running it and compare its columns and parameters with the view MPA-OVR-5. Problems are diagnostics with the view, the query, the file and the line: M0100 to M0104 and M0301 are errors; M0105, an optional path never selected, is a warning. build fails with Error::Invalid, unless on_invalid(OnInvalid::UseGenerated) runs the generated queries in place of invalid overrides. A filter or order column that a root override does not select is Error::ColumnNotSelected MPA-LOAD-7.

Changing them safely. A shadow override runs together with the generated query and logs a warning when their rows differ, with counts in shadow_stats MPA-OVR-6. reload reads the files again, checks them, and swaps them in atomically; invalid files leave the running overrides as they are MPA-OVR-7. The mabat tool checks, explains and scaffolds override files against a manifest the application writes, with no Rust toolchain MPA-OVR-8. Writes never use overrides MPA-NOT-5.