feat: Add retry mechanism on locked/busy mbtiles files

[sdemeesterde]

Fix #1591

Hello !
This is my first-ever PR to an open-source project.

Currently, martin crashes when trying to fetch the metadata of a busy mbtile file. It was proposed in the open issue: #1591 to be more lenient and perform retries when the file was locked.

Technical note:

The SQLITE_BUSY error is hardcoded as the sqlite wrapper used in martin (sqlx) doesn't offer an error enum match for specific sqlite error codes (unlike rusqlite).

Retry strategy:

The retrial strategy is an exponential backoff with the following delays: 50ms, 0.1s, 0.2s, 0.4s, 0.8s, 1.6s, 3.2s, and finally 6.4s.

I would happily take feedback on:

• Is limiting the retry behavior strictly to SQLITE_BUSY errors the intended approach ?
• Are the exponential backoff delays acceptable for this use case ?
• Is the warning message too verbose for the logs ?
• Is there anything else that I might have missed ? :)

Thanks !

[CommanderStorm]

The main feedback I have is to NEVER std::thread::sleep in an async context.
That is what tokio's sleep is for.
Since this is likely not avaliable under this feature already, you need to add this to Cargo.toml for the mbtiles feature.
Here is a resource that you might enjoy to learn more https://youtu.be/o2ob8zkeq2s

Also, could we use something like https://docs.rs/backon/1.6.0/backon/
This way we can have a simpler impl, but also a better impl (-> jitter+fibonacci).

[sdemeesterde]

Thanks for the precious feedback ! I really appreciate that as I'm eager to learn more !
I actually had saved this video on my watch list, will watch it sooner I guess :)

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	cargo/​backon@​1.6.0

View full report

[sdemeesterde]

Here is a version implementing your suggestion to use the backon crate.
Indeed, using Fibonacci with jitter is less aggressive while being robust !

(The "Decrusting the tokio crate" video was very interesting)

[CommanderStorm]

Thank you!

[Copilot]

Pull request overview

This PR adds a retry/backoff mechanism when reading MBTiles metadata so Martin can tolerate transient SQLite SQLITE_BUSY (“database is locked/busy”) errors instead of failing immediately during source initialization (Fixes #1591).

Changes:

• Add backon-based retry with Fibonacci backoff + jitter around mbt.get_metadata() for MBTiles sources.
• Detect SQLITE_BUSY from the underlying sqlx error code to conditionally enable retries.
• Add the backon dependency (workspace + martin-core feature wiring) and adjust Cargo.lock.

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 1 comment.

File	Description
martin-core/src/tiles/mbtiles/source.rs	Adds SQLITE_BUSY detection and retries around MBTiles metadata fetching with logging on retry.
martin-core/Cargo.toml	Enables backon (and tokio) under the mbtiles feature and adds optional dependency entry.
Cargo.toml	Adds backon to workspace dependencies.
Cargo.lock	Locks new transitive dependencies and updates some versions pulled in.

Comments suppressed due to low confidence (3)

martin-core/src/tiles/mbtiles/source.rs:61

• There are two consecutive comments saying "Attempt to fetch metadata" here. Please remove the duplicate so the retry block has a single clear header comment.

        // Attempt to fetch metadata with backoff
        let start_delay = Duration::from_millis(50);

martin-core/src/tiles/mbtiles/source.rs:69

• max_attempts is passed into FibonacciBuilder::with_max_times(...), which is easy to misread (times vs attempts). Consider renaming this variable to reflect what the backoff builder expects (e.g., max_times/max_retries) to avoid confusion when adjusting retry behavior later.

        let max_attempts = 10; // from 50ms to 2.75s
        let meta = (|| async { mbt.get_metadata().await })
            .retry(
                FibonacciBuilder::default()
                    .with_min_delay(start_delay)
                    .with_max_times(max_attempts)
                    .with_jitter(),
            )

martin-core/src/tiles/mbtiles/source.rs:77

• The log message formats path.display() using {:?}; elsewhere in the codebase paths are logged with {} (e.g., martin-core/src/resources/sprites/mod.rs:80). Using {} here avoids debug-style quoting and keeps log formatting consistent.

                    "Database file {:?} locked (SQLITE_BUSY). Retrying in {:.2}s...",
                    path.display(),
                    dur.as_secs_f64()
                );