Skip to main content

LINT.SHADOW.ORPHANS — what the shadow run did with throwaway databases an earlier run left behind

  • Category: safety
  • Level: 0
  • Stability: stable
  • Suites: lint

Shadow mode builds a throwaway database for every run and drops it afterwards. A run that is killed before its own cleanup (an out-of-memory kill, a pipeline timeout, a Ctrl-C) never drops it, so the next shadow run looks for such leftovers and removes the ones older than capture.shadow.orphan_after_seconds. It only ever considers databases named with the shadow prefix and the time they were made, which are databases SQLens created for itself.

Removing a database is something a lint run does on your server, so the run says so.

The two answers​

A pass when the run removed every leftover it found. The message names each database it dropped.

Undetermined (shadow_orphans_remain) when something is left: a database the run found and could not remove, most often because a connection was still open on it, or a server on which it could not list the shadow databases at all. Nothing about the migrations this run judged depends on it, and the next shadow run tries again.

A run that found no leftovers reports nothing here. Neither does a run that never reached the sweep: one the production guard blocked, which does not reach the server at all; one shadow mode refused before it provisioned anything, such as a run against a replica or through a transaction pooler; and one that stopped before it captured, because its connection could not be reached, the database has no migrations table, or no migration path holds a migration it judges. Each of those reports its own answer, and the next run that captures does the sweep. A run with nothing pending is not one of them: it captures an empty set, and it sweeps.

What to do​

Nothing, for a pass. It is a record of what the run removed.

For an undetermined, a database named in the message is still on the server. Let the next shadow run remove it, or drop it by hand once nothing is connected to it. If the sweep could not list the databases, check that the account shadow mode connects with can list the server's databases.