Skip to content

feat: read a SQLBuild-style project beside sqlquack.toml - #109

Closed
kvlonge wants to merge 2 commits into
mainfrom
feat/project-config
Closed

kvlonge wants to merge 2 commits into
mainfrom
feat/project-config

Conversation

@kvlonge

@kvlonge kvlonge commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Why

A SQLQuack project should be configured the way a SQLBuild project is: tables, functions and overrides found by convention beside the config file, with no flags inside a project. A SQLBuild project's sources and functions folders should work unchanged.

Changes

  • convert and census treat the folder holding sqlquack.toml (or --policy) as a project and read:
    • sources/*.yml in SQLBuild's source format (name, columns with name and type), names upper-cased as Snowflake folds them; inline-expression sources are not tables, and a source with an untyped column is left out with a warning naming the file, source and column.
    • functions/sql/*.sql (SQLBuild's FUNCTION ( ... ); header) and functions/python/*.py (@udf(...), imported from sqlbuild.functions or sqlquack), named after the file.
    • overrides/, as --overrides reads it.
  • sqlquack.toml gains [project] (folder paths only where they differ), [project.session] and [project.confirm] (python_runtime, utc_session, declared_offsets).
  • Flags apply on top for one run; --schema adds to the project, and a name declared twice is an error naming both files.
  • A refused Python function's help names the line to add under [project.confirm].
  • Python: ConvertOptions(project=...) and sqlquack.udf.
  • Docs: a Projects page, and the convert, schema, policy and Python pages and README.

Verification

  • CLI tests: discovery, flag precedence, the clash errors and the refusal text (15 cases, including the untyped-column warning).
  • Python API test: project folder and a session override, compared with the command line.
  • make check-ci passes locally. Lands after fix: translate common incremental-model timestamp idioms #96 through the merge gate.

convert and census read the folder holding the policy file as a project:
tables from sources/*.yml in SQLBuild's source format, functions from
functions/sql/*.sql (FUNCTION header) and functions/python/*.py (@udf
decorator from sqlbuild.functions or sqlquack), and overrides from
overrides/. [project.session] and [project.confirm] give session
parameters and confirmations; flags apply on top for one run, --schema
adds to the project's declarations, and a name declared twice is an
error naming both files. The Python API takes ConvertOptions(project=).

A refused Python function's help names the line to add under
[project.confirm]. Override headers share the project's header parser,
which now keeps commas and parentheses inside quoted descriptions.
The table is left out whole, so SELECT * never misses a column; convert
and census name the file, the source and the column on standard error,
and convert's report lists the same message under warnings.

kvlonge commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

Post-launch: this project-configuration feature isn't needed for launch, so it stays open and out of the current landing queue. It will be reviewed when the SQLBuild integration work starts, and will need main merged in and an auditor read then.

kvlonge commented Nov 8, 2026

Copy link
Copy Markdown
Contributor Author

Closing: SQLQuack lands through local-gate trains, not PR merges (D94), so open PRs only add clutter (D628/D630). The branch is kept. Any work here that isn't on main yet is tracked by the train owner and lands through a train.

@kvlonge kvlonge closed this Nov 8, 2026
@kvlonge
kvlonge deleted the feat/project-config branch November 9, 2026 21:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant