Add snapshot methods to query Builder/Model #267

matthewjumpsoffbuildings · 2025-03-02T04:35:54Z

This PR resolves #231 and adds the ability to specify snapshot() when writing Eloquent queries on Models, or when using Builder directly

It can be used like so:

// snapshot from a model
User::snapshot()->all();

// snapshot from a builder
DB::table('users')
    ->where('foo', 'bar')
    ->snapshot()
    ->get();

Summary by CodeRabbit

New Features
- Introduced enhanced snapshot read capabilities, allowing for time-bound query execution to improve data consistency.
Documentation
- Added a new section in the README detailing how to perform explicit snapshot reads with examples for various instances.
Tests
- Implemented new tests to validate the behavior of snapshot reads and ensure expected functionality.

coderabbitai · 2025-03-02T04:36:00Z

Walkthrough

The pull request introduces snapshot functionality across the application. In the Connection class, a conditional check is added to handle snapshot-enabled queries by validating the provided timestamp bound. The Builder class is updated to incorporate snapshot options, and a new UsesSnapshots trait is introduced for managing snapshot timestamp data. Additionally, the documentation is enhanced with a "Snapshot reads" section, and tests are added to verify the correct behavior of snapshot query execution.

Changes

File(s)	Change Summary
`src/Connection.php`	Introduced a conditional check in `executeQuery` to handle snapshot-enabled queries and added an import for `TimestampBoundInterface`.
`src/Query/Builder.php`, `src/Query/Concerns/UsesSnapshots.php`	Integrated snapshot functionality by adding the `UsesSnapshots` trait to the `Builder` class and updating `runSelect` to include snapshot options, alongside defining the trait with snapshot management methods and property.
`README.md`	Added a new "Snapshot reads" section with examples demonstrating how to perform snapshot reads using various instances such as `Connection`, `Model`, and `Builder`.
`tests/Query/BuilderTest.php`	Added the `test_snapshot` method to validate the snapshot query behavior, verifying that snapshot functionality is correctly enabled and executed.

Possibly related PRs

feat: Support snapshot queries #215: Addresses similar modifications in the executeQuery method focusing on snapshot functionality, providing a code-level connection to this PR.

Suggested labels

enhancement, waiting for review

Suggested reviewers

halnique
Uyan712

Tip

⚡🧪 Multi-step agentic review comment chat (experimental)

We're introducing multi-step agentic chat in review comments. This experimental feature enhances review discussions with the CodeRabbit agentic chat by enabling advanced interactions, including the ability to create pull requests directly from comments.
- To enable this feature, set early_access to true under in the settings.

📜 Recent review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f9bc494 and c2d118e.

📒 Files selected for processing (1)

tests/Query/BuilderTest.php (2 hunks)

⏰ Context from checks skipped due to timeout of 90000ms (1)

GitHub Check: Run-PHPUnit

🔇 Additional comments (2)

tests/Query/BuilderTest.php (2)

28-28: Good addition of the StrongRead import.

This import is required for the new test method test_snapshot() which tests both ExactStaleness and StrongRead timestamp bounds.

1079-1105: Well-structured test for snapshot functionality.

The test covers important scenarios for snapshot functionality:

Verifies that connections aren't in snapshot state before and after transactions

Tests snapshot with ExactStaleness (5 seconds)

Tests snapshot with StrongRead

Verifies snapshot state is properly tracked through method calls

The assertions are comprehensive, checking the enabled status, timestamp bound type, and the actual data retrieved, which ensures the snapshot functionality works correctly as intended.

✨ Finishing Touches

📝 Generate Docstrings

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Generate unit testing code for this file.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
- @coderabbitai generate unit testing code for this file.
- @coderabbitai modularize this function.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read src/utils.ts and generate unit testing code.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
- @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

@coderabbitai pause to pause the reviews on a PR.
@coderabbitai resume to resume the paused reviews.
@coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
@coderabbitai full review to do a full review from scratch and review all the files again.
@coderabbitai summary to regenerate the summary of the PR.
@coderabbitai generate docstrings to generate docstrings for this PR.
@coderabbitai resolve resolve all the CodeRabbit review comments.
@coderabbitai configuration to show the current CodeRabbit configuration for the repository.
@coderabbitai help to get help.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (1)

src/Query/Concerns/UsesSnapshots.php (1)
29-37: Fix PHPDoc comment to match implementation.

The PHPDoc comment references a parameter $toggle that doesn't exist in the implementation. Also, the return type in the comment is $this but the method returns static.
-     * @param bool $toggle
+     * @param TimestampBoundInterface $timestamp
      * @return $this

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 03dbf66 and 0ed695f.

📒 Files selected for processing (3)

src/Connection.php (1 hunks)
src/Query/Builder.php (2 hunks)
src/Query/Concerns/UsesSnapshots.php (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms (1)

GitHub Check: Run-PHPUnit

🔇 Additional comments (4)

src/Query/Builder.php (2)

35-35: LGTM! Trait integration looks good.

The UsesSnapshots trait is properly added to the Builder class alongside other existing traits that provide similar functionality. This maintains code organization consistency.

246-249: Implementation for snapshot functionality looks correct.

The condition properly checks if snapshots are enabled and adds the necessary options to the query. The implementation follows the same pattern as existing features like data boost and timestampBound.

src/Connection.php (1)

628-630: Snapshot functionality implementation looks good.

The implementation correctly checks for the snapshotEnabled option and delegates to the appropriate method. The placement before the existing snapshot check is logical, as it allows for explicitly enabling snapshots through options, while maintaining compatibility with the existing inSnapshot() method.

src/Query/Concerns/UsesSnapshots.php (1)

1-54: Overall implementation of snapshot trait looks good.

The trait is well-structured and follows the existing patterns in the codebase:

Proper type hints and return types

Clear method names following convention

Straightforward implementation of the snapshot functionality

This implementation successfully addresses the PR objective to "introduce the capability to use the snapshot() method when executing Eloquent queries on Models, as well as when utilizing the Builder directly."

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (1)

README.md (1)

186-210: Great addition of snapshot reads documentation!

The snapshot reads section provides clear examples for all three usage patterns: Connection, Model, and Query Builder. This enhances the documentation by showing the flexibility of the new feature.

However, note that the heading style is inconsistent with other headings in the document. Consider using setext style (with underlines) instead of ATX style (with hash symbols) to match the document's style.

🧰 Tools

🪛 markdownlint-cli2 (0.17.2)

186-186: Heading style
Expected: setext; Actual: atx

(MD003, heading-style)

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7b9e87e and 660002b.

📒 Files selected for processing (3)

README.md (1 hunks)
src/Connection.php (2 hunks)
src/Query/Concerns/UsesSnapshots.php (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

src/Query/Concerns/UsesSnapshots.php

🧰 Additional context used

🪛 markdownlint-cli2 (0.17.2)

README.md

186-186: Heading style
Expected: setext; Actual: atx

(MD003, heading-style)

⏰ Context from checks skipped due to timeout of 90000ms (1)

GitHub Check: Run-PHPUnit

🔇 Additional comments (2)

src/Connection.php (2)

28-28: Appropriate import addition.

The TimestampBoundInterface import is needed for proper type checking in the new code path.

629-633: Well-implemented snapshot execution path.

The implementation correctly checks for the snapshot option and handles the execution within the appropriate context. Good use of type assertion to ensure the timestamp bound is of the correct interface type.

The code maintains a clear separation between the existing snapshot functionality and the new opt-in approach, allowing for better backward compatibility.

taka-oyama · 2025-03-13T00:45:17Z

tests/SnapshotTest.php

@@ -46,6 +46,23 @@ public function test_snapshot(): void
        $this->assertSame('ok', $result);
    }

+    public function test_builder_snapshot(): void


Please move this test to Query/BuilderTest.php

coderabbitai

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 4080fd6 and 1b88c6f.

📒 Files selected for processing (1)

tests/Query/BuilderTest.php (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms (1)

GitHub Check: Run-PHPUnit

🔇 Additional comments (1)

tests/Query/BuilderTest.php (1)

1078-1096: Overall test implementation looks good

This test correctly verifies the snapshot functionality by:

Confirming the connection is not in snapshot state before the operation

Running a transaction and inserting test data

Creating a snapshot query with ExactStaleness

Verifying the snapshot is properly configured

Checking that the query returns expected results

The test provides good coverage of the new snapshot capabilities mentioned in the PR objectives.

tests/Query/BuilderTest.php

matthewjumpsoffbuildings added 3 commits March 2, 2025 15:00

Update Builder.php

85b6234

Update Connection.php

cd4a4f5

Create UsesSnapshots.php

0ed695f

coderabbitai bot reviewed Mar 2, 2025

View reviewed changes

matthewjumpsoffbuildings added 8 commits March 2, 2025 15:13

Update UsesSnapshots.php

2af684f

Update SnapshotTest.php

d0451f8

Update SnapshotTest.php

7b9e87e

Update README.md

fb3e410

Update README.md

1ce2ef4

Update Connection.php

5359914

Update UsesSnapshots.php

28d0a2c

Update Connection.php

660002b

coderabbitai bot reviewed Mar 2, 2025

View reviewed changes

Update SnapshotTest.php

4080fd6

taka-oyama reviewed Mar 13, 2025

View reviewed changes

matthewjumpsoffbuildings added 2 commits March 13, 2025 13:26

Update SnapshotTest.php

43a0662

Update BuilderTest.php

1b88c6f

coderabbitai bot reviewed Mar 13, 2025

View reviewed changes

tests/Query/BuilderTest.php Outdated Show resolved Hide resolved

matthewjumpsoffbuildings added 2 commits March 13, 2025 13:57

Update BuilderTest.php

f9bc494

Update BuilderTest.php

c2d118e

taka-oyama merged commit e0a9618 into colopl:master Mar 13, 2025
1 check passed

taka-oyama pushed a commit that referenced this pull request Mar 17, 2025

feat: Add snapshot methods to query Builder/Model (#267)

faedc4a

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add snapshot methods to query Builder/Model #267

Add snapshot methods to query Builder/Model #267

Uh oh!

matthewjumpsoffbuildings commented Mar 2, 2025 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Mar 2, 2025 •

edited

Loading

Chat

CodeRabbit Commands (Invoked using PR comments)

Other keywords and placeholders

CodeRabbit Configuration File (`.coderabbit.yaml`)

Documentation and Community

Uh oh!

coderabbitai bot left a comment

Uh oh!

coderabbitai bot left a comment

Uh oh!

taka-oyama Mar 13, 2025

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Add snapshot methods to query Builder/Model #267

Add snapshot methods to query Builder/Model #267

Uh oh!

Conversation

matthewjumpsoffbuildings commented Mar 2, 2025 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Mar 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Possibly related PRs

Suggested labels

Suggested reviewers

Chat

CodeRabbit Commands (Invoked using PR comments)

Other keywords and placeholders

CodeRabbit Configuration File (.coderabbit.yaml)

Documentation and Community

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

taka-oyama Mar 13, 2025

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

matthewjumpsoffbuildings commented Mar 2, 2025 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Mar 2, 2025 •

edited

Loading

CodeRabbit Configuration File (`.coderabbit.yaml`)