Skip to content

Commit 9e7cff5

Browse files
authored
feat(cli): add janitor --target and inspection-only --as preview (#898)
janitor --target NAME cleans up a configured target with that target's connection, namespace and state, like build --target. janitor --as NAME previews the janitor plan for another target's namespace through the active target's connection without dropping, archiving, writing state or prompting, reusing the plan --as target validation.
1 parent ef9404d commit 9e7cff5

16 files changed

Lines changed: 606 additions & 44 deletions

File tree

‎src/sqlbuild/.agents/skills/sqlbuild/references/docs/cli/janitor.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ Online: https://sqlbuild.com/docs/cli/janitor/
1010

1111
- Usage
1212
- Flags
13+
- Targets
1314
- Lifecycle
1415
- Compatibility views
1516
- Pending migration origins
@@ -33,11 +34,34 @@ sqb --project-dir <path> janitor [flags]
3334

3435
| Flag | Description |
3536
|------|-------------|
37+
| `--target <name>` | Clean up a configured target instead of the active/default target, using that target's connection, schemas and state |
38+
| `--as <name>` | Preview the janitor plan for another configured target's schemas through the active target's connection. Inspection only: nothing is archived, dropped or pruned, and there is no prompt. Cannot be combined with `--auto-approve` |
3639
| `--auto-approve` | Skip the confirmation prompt and run the planned actions immediately |
3740
| `--retention-days` | Override the configured retention period (days) before a stale relation is archived |
3841
| `--direct-state-history-versions` | Override how many state-history versions are kept per identity |
3942
| `--drop-old-name-view <name>` | Drop the [compatibility view](../concepts/models/migrations.md#old-names) at a renamed model's old name before it expires. Repeat for several views. Fails with `C503` if no compatibility view is recorded at the name |
4043

44+
## Targets
45+
46+
By default the janitor cleans up the active target. `--target <name>` selects another configured target, exactly like `sqb build --target`: the janitor connects with that target's connection and inspects and cleans that target's schemas and state tables. Other targets are never touched.
47+
48+
`--as <name>` previews what the janitor would do in another target without changing anything, like [`sqb plan --as`](plan.md). The project compiles for that target, and its schemas are inspected through the active target's connection, which can be the default target or the one given with `--target`. The janitor lists every relation it would archive, every archive it would delete, every compatibility view it would drop and every state table it would prune, then exits. It drops nothing, writes no audit or state rows, prunes nothing and does not prompt. `--drop-old-name-view` is allowed with `--as` and only previews the drop.
49+
50+
```
51+
Previewing janitor as target 'prod' through the connection of target 'dev' (inspection only).
52+
...
53+
Relations to archive
54+
prod.customers -> prod._sqb_archive__20261001t101500z__customers age unknown, delete after 2026-10-15 10:15:00 UTC
55+
56+
Archives to delete
57+
prod._sqb_archive__20200101t000000z__old_products archived 2020-01-01 00:00:00 UTC, age 2465d, expired 2020-01-15 00:00:00 UTC
58+
59+
Previewed janitor as target 'prod' through the connection of target 'dev'. Nothing was changed.
60+
Rerun with `--target prod` instead of `--as prod` to apply it.
61+
```
62+
63+
An unknown target name fails before anything connects. A preview exits with `0`, or with `1` when a schema is blocked, as a normal run would.
64+
4165
## Lifecycle
4266

4367
The janitor never drops a live relation directly. Each stale relation goes through two stages:
@@ -134,6 +158,12 @@ sqb janitor --auto-approve
134158

135159
# Override retention to 7 days
136160
sqb janitor --retention-days 7
161+
162+
# Preview the prod cleanup through the current connection, changing nothing
163+
sqb janitor --as prod
164+
165+
# Clean up the prod target
166+
sqb janitor --target prod
137167
```
138168

139169
## State history pruning

‎src/sqlbuild/cli/commands/_helpers/entry/dispatch.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -406,6 +406,8 @@ def dispatch_cli_command(*, args: CliNamespace, handlers: CliEntrypointHandlers)
406406
retention_days=args.retention_days,
407407
direct_state_history_versions=args.direct_state_history_versions,
408408
drop_old_name_views=tuple(args.drop_old_name_views),
409+
selected_target=args.target,
410+
as_target=args.as_target,
409411
)
410412
)
411413
return _dispatch_local_command(

‎src/sqlbuild/cli/commands/_helpers/entry/parser.py‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -630,6 +630,16 @@ def _add_maintenance_parsers(
630630
metavar="NAME",
631631
dest="drop_old_name_views",
632632
)
633+
janitor_parser.add_argument("--target", default=None)
634+
janitor_parser.add_argument(
635+
"--as",
636+
dest="as_target",
637+
default=None,
638+
help=(
639+
"Preview the janitor plan as another configured target through the active "
640+
"target's connection; inspection only"
641+
),
642+
)
633643

634644

635645
def _add_workspace_parsers(

‎src/sqlbuild/cli/commands/_helpers/entry/parsing.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,10 @@ def parse_cli_invocation(
129129
_validate_scope_args(args=args, parser=parser)
130130
if args.command == CliCommand.TEST:
131131
_validate_test_args(args=args, parser=parser)
132+
if args.command == CliCommand.JANITOR and args.as_target is not None and args.auto_approve:
133+
parser.error(
134+
"janitor --as is inspection only and cannot be combined with --auto-approve"
135+
)
132136
except SystemExit as error:
133137
exit_code: int = error.code if isinstance(error.code, int) else 1
134138
return ParsedCliInvocation(args=None, exit_code=exit_code)

‎src/sqlbuild/cli/commands/_helpers/janitor_output/outputs.py‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,39 @@ def write_janitor_disabled(*, invocation: JanitorInvocation) -> None:
2626
write_disabled(stream=sys.stdout, use_color=invocation.use_color)
2727

2828

29+
def write_janitor_preview_start(*, invocation: JanitorInvocation) -> None:
30+
"""Announce an inspection-only ``--as`` janitor preview before any work starts."""
31+
32+
sys.stdout.write(
33+
f"Previewing janitor as target '{invocation.as_target}' through "
34+
f"{_active_connection_label(invocation=invocation)} (inspection only).\n"
35+
)
36+
sys.stdout.flush()
37+
38+
39+
def write_janitor_preview_complete(*, invocation: JanitorInvocation) -> None:
40+
"""Close an ``--as`` janitor preview with an unambiguous nothing-changed state."""
41+
42+
style: CliStyle = CliStyle(use_color=invocation.use_color)
43+
sys.stdout.write(
44+
style.success(
45+
f"Previewed janitor as target '{invocation.as_target}' through "
46+
f"{_active_connection_label(invocation=invocation)}. Nothing was changed."
47+
)
48+
+ "\n"
49+
)
50+
sys.stdout.write(
51+
f"Rerun with `--target {invocation.as_target}` instead of "
52+
f"`--as {invocation.as_target}` to apply it.\n"
53+
)
54+
55+
56+
def _active_connection_label(*, invocation: JanitorInvocation) -> str:
57+
if invocation.active_target_name is None:
58+
return "the active connection"
59+
return f"the connection of target '{invocation.active_target_name}'"
60+
61+
2962
def write_janitor_plan(
3063
*, invocation: JanitorInvocation, planning_result: JanitorPlanningResult
3164
) -> None:

‎src/sqlbuild/cli/commands/_helpers/janitor_runtime/compilation.py‎

Lines changed: 20 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -5,32 +5,28 @@
55
import sys
66
import time
77

8-
from sqlbuild.adapter.contract.classes.base_adapter import BaseAdapter
9-
from sqlbuild.cli.commands._helpers.runtime.adapters import resolve_adapter
10-
from sqlbuild.cli.commands._helpers.runtime.connection import resolve_connection_config
8+
from sqlbuild.cli.commands._helpers.runtime.adapter_context import (
9+
resolve_adapter_connection_context,
10+
)
1111
from sqlbuild.cli.commands.models import (
12+
AdapterConnectionContext,
1213
JanitorCompileContext,
1314
JanitorInvocation,
1415
)
1516
from sqlbuild.cli.progress.classes.planning_progress_reporter import PlanningProgressReporter
1617
from sqlbuild.compiler.compile.models import CompiledProject
1718
from sqlbuild.compiler.pipeline.main.project import compile_project
1819
from sqlbuild.runtime.observability.classes.operation_lifecycle import OperationLifecycle
19-
from sqlbuild.spec.contracts.main.resolve_effective_adapter_name import (
20-
resolve_effective_adapter_name,
21-
)
2220

2321

2422
def compile_janitor_project(*, invocation: JanitorInvocation) -> JanitorCompileContext:
25-
"""Resolve adapter, compile project, and prepare connection config."""
23+
"""Compile for the janitor or ``--as`` target and resolve the active target connection."""
2624

27-
adapter_name: str = resolve_effective_adapter_name(
28-
project_config=invocation.discovered_inputs.project_config,
29-
local_config=invocation.discovered_inputs.local_config,
30-
)
31-
adapter: BaseAdapter = resolve_adapter(
32-
adapter_name=adapter_name,
33-
project_dir=invocation.effective_project_dir,
25+
adapter_context: AdapterConnectionContext = resolve_adapter_connection_context(
26+
discovered_inputs=invocation.discovered_inputs,
27+
effective_project_dir=invocation.effective_project_dir,
28+
selected_target=invocation.selected_target,
29+
cli_vars=None,
3430
)
3531
compile_start: float = time.perf_counter()
3632
status: PlanningProgressReporter = PlanningProgressReporter(
@@ -41,17 +37,18 @@ def compile_janitor_project(*, invocation: JanitorInvocation) -> JanitorCompileC
4137
status.on_progress("Compiling project...")
4238
project: CompiledProject = compile_project(
4339
discovered_inputs=invocation.discovered_inputs,
44-
adapter=adapter,
40+
adapter=adapter_context.adapter,
41+
selected_target=(
42+
invocation.as_target
43+
if invocation.as_target is not None
44+
else invocation.selected_target
45+
),
46+
resolved_connection=adapter_context.connection_config,
4547
)
4648
status.on_progress(f"Compiled project. ({time.perf_counter() - compile_start:.2f}s)")
47-
connection_config: dict[str, object] = resolve_connection_config(
48-
raw_config=project.effective_connection,
49-
project_dir=invocation.effective_project_dir,
50-
adapter_name=adapter_name,
51-
)
5249
return JanitorCompileContext(
53-
adapter_name=adapter_name,
54-
adapter=adapter,
50+
adapter_name=adapter_context.adapter_name,
51+
adapter=adapter_context.adapter,
5552
project=project,
56-
connection_config=connection_config,
53+
connection_config=adapter_context.connection_config,
5754
)

‎src/sqlbuild/cli/commands/_helpers/janitor_runtime/invocation.py‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44

55
from pathlib import Path
66

7+
from sqlbuild.cli.commands._helpers.runtime.preview_target import validate_preview_target
78
from sqlbuild.cli.commands.exceptions import CliUserError
89
from sqlbuild.cli.commands.models import (
910
JanitorCommandRequest,
@@ -14,6 +15,7 @@
1415
from sqlbuild.compiler.discovery.models import DiscoveredProjectInputs
1516
from sqlbuild.executor.janitor.main.resolve_retention_days import resolve_janitor_retention_days
1617
from sqlbuild.presentation.main.supports_color import supports_color
18+
from sqlbuild.spec.contracts.main.resolve_target_name import resolve_target_name
1719

1820

1921
def resolve_janitor_invocation(*, request: JanitorCommandRequest) -> JanitorInvocation:
@@ -25,10 +27,21 @@ def resolve_janitor_invocation(*, request: JanitorCommandRequest) -> JanitorInvo
2527
discovered_inputs: DiscoveredProjectInputs = discover_project_inputs(
2628
project_dir=effective_project_dir
2729
)
30+
validate_preview_target(
31+
discovered_inputs=discovered_inputs, as_target=request.as_target, command_name="janitor"
32+
)
33+
active_target_name: str | None = resolve_target_name(
34+
project_config=discovered_inputs.project_config,
35+
local_config=discovered_inputs.local_config,
36+
selected_target=request.selected_target,
37+
)
2838
return JanitorInvocation(
2939
effective_project_dir=effective_project_dir,
3040
discovered_inputs=discovered_inputs,
3141
use_color=not request.no_color and supports_color(),
42+
selected_target=request.selected_target,
43+
active_target_name=active_target_name,
44+
as_target=request.as_target,
3245
)
3346

3447

‎src/sqlbuild/cli/commands/_helpers/plan/invocation.py‎

Lines changed: 4 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
from sqlbuild.cli.commands._helpers.runtime.adapter_context import (
1010
resolve_adapter_connection_context,
1111
)
12-
from sqlbuild.cli.commands.exceptions import CliUserError
12+
from sqlbuild.cli.commands._helpers.runtime.preview_target import validate_preview_target
1313
from sqlbuild.cli.commands.models import (
1414
AdapterConnectionContext,
1515
PlanCommandRequest,
@@ -34,7 +34,9 @@ def resolve_plan_invocation(*, request: PlanCommandRequest) -> PlanInvocation:
3434
discovered_inputs: DiscoveredProjectInputs = discover_project_inputs(
3535
project_dir=effective_project_dir, extract_output_column_locations=False
3636
)
37-
_validate_preview_target(discovered_inputs=discovered_inputs, as_target=request.as_target)
37+
validate_preview_target(
38+
discovered_inputs=discovered_inputs, as_target=request.as_target, command_name="plan"
39+
)
3840
adapter_context: AdapterConnectionContext = resolve_adapter_connection_context(
3941
discovered_inputs=discovered_inputs,
4042
effective_project_dir=effective_project_dir,
@@ -64,18 +66,3 @@ def resolve_plan_invocation(*, request: PlanCommandRequest) -> PlanInvocation:
6466
planning_progress=reporters.planning,
6567
should_load_sources=should_load_sources,
6668
)
67-
68-
69-
def _validate_preview_target(
70-
*, discovered_inputs: DiscoveredProjectInputs, as_target: str | None
71-
) -> None:
72-
if as_target is None:
73-
return
74-
configured: set[str] = set(discovered_inputs.project_config.targets) | set(
75-
discovered_inputs.local_config.targets
76-
)
77-
if as_target not in configured:
78-
raise CliUserError(
79-
f"unknown target '{as_target}' for plan --as",
80-
help=f"Configured targets: {', '.join(sorted(configured)) or 'none'}.",
81-
)
Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
"""Shared validation for inspection-only ``--as`` target previews."""
2+
3+
from __future__ import annotations
4+
5+
from sqlbuild.cli.commands.exceptions import CliUserError
6+
from sqlbuild.compiler.discovery.models import DiscoveredProjectInputs
7+
8+
9+
def validate_preview_target(
10+
*, discovered_inputs: DiscoveredProjectInputs, as_target: str | None, command_name: str
11+
) -> None:
12+
"""Fail clearly when ``--as`` names a target that is not configured."""
13+
14+
if as_target is None:
15+
return
16+
configured: set[str] = set(discovered_inputs.project_config.targets) | set(
17+
discovered_inputs.local_config.targets
18+
)
19+
if as_target not in configured:
20+
raise CliUserError(
21+
f"unknown target '{as_target}' for {command_name} --as",
22+
help=f"Configured targets: {', '.join(sorted(configured)) or 'none'}.",
23+
)

‎src/sqlbuild/cli/commands/main/state/_janitor.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@
99
write_janitor_completion,
1010
write_janitor_disabled,
1111
write_janitor_plan,
12+
write_janitor_preview_complete,
13+
write_janitor_preview_start,
1214
)
1315
from sqlbuild.cli.commands._helpers.janitor_runtime.compilation import compile_janitor_project
1416
from sqlbuild.cli.commands._helpers.janitor_runtime.connections import (
@@ -42,6 +44,8 @@ def run_janitor(request: JanitorCommandRequest) -> int:
4244
write_janitor_disabled(invocation=invocation)
4345
return 0
4446
settings: JanitorSettings = resolve_janitor_settings(request=request, invocation=invocation)
47+
if invocation.as_target is not None:
48+
write_janitor_preview_start(invocation=invocation)
4549
compile_context: JanitorCompileContext = compile_janitor_project(invocation=invocation)
4650
connection_context: JanitorConnectionContext = connect_janitor_warehouse(
4751
invocation=invocation,
@@ -55,6 +59,9 @@ def run_janitor(request: JanitorCommandRequest) -> int:
5559
connection_context=connection_context,
5660
)
5761
write_janitor_plan(invocation=invocation, planning_result=planning_result)
62+
if invocation.as_target is not None:
63+
write_janitor_preview_complete(invocation=invocation)
64+
return 1 if planning_result.plan.blocked_schemas else 0
5865
if planning_result.plan.blocked_schemas:
5966
return 1
6067
if not janitor_plan_has_work(planning_result):

0 commit comments

Comments
 (0)