DOCSEARCHbyAlgolia
Submit Docs

LiteDB Documentation

repository·dev·Indexed 27 days ago

https://github.com/litedb-org/litedb

LiteDB is a lightweight, serverless, and embedded NoSQL document store for .NET. It provides an ACID-compliant, thread-safe database stored in a single file. This documentation includes guides for the Vector Search Demo CLI using Google Gemini embeddings and the ReproRunner CLI for discovering, validating, and executing reproduction projects to demonstrate LiteDB issues.

Tokens
8.7K
Snippets
26
Records
59
Agent score
94%

What's inside LiteDB

  1. Ingest documents for Vector Search

    dev

    Use the ingest command to process a folder of .txt or .md files. The tool embeds the text using Google Gemini embeddings and persists the metadata and vectors into a LiteDB database.

    You must provide Gemini credentials using one of these methods:

    • An API key via the --api-key flag, or the GOOGLE_VERTEX_API_KEY or GOOGLE_API_KEY environment variables.
    • Service account credentials via GOOGLE_APPLICATION_CREDENTIALS (using default GoogleCredential providers).

    If using Vertex AI with a service account, you can optionally specify GOOGLE_PROJECT_ID and GOOGLE_VERTEX_LOCATION (defaults to us-central1).

    Model selection is controlled via --model or the GOOGLE_VERTEX_EMBEDDING_MODEL environment variable (defaults to gemini-embedding-001).

    dotnet run --project LiteDB.Demo.Tools.VectorSearch.csproj -- ingest --source ./docs --database vector.db --api-key "$env:GOOGLE_VERTEX_API_KEY"

  3. Configure LiteDB version for the ReproRunner

    dev

    When running reproduction projects via the ReproRunner CLI, you can control which version of LiteDB is used:

    • Pin a specific NuGet package version: Use the -p:LiteDBPackageVersion=<version> flag.
    • Use in-repo source code: Use the -p:UseProjectReference=true flag.

    By default, the project references the NuGet package (defaulting to version 5.0.20).

  4. Mark a LiteDB repro as fixed

    dev

    To mark a reproduction case as fixed while preventing regressions:

    1. Update the state in the manifest to green.
    2. Adjust the repro's README.
    3. Ensure the expectedOutcomes.latest entry (or the implicit default) expects noRepro.

    Note: Hard-fail overrides for the package build can remain in place to ensure the issue does not return.

  5. Build LiteDB locally with GitVersion

    dev
    Standard build commands automatically consume GitVersion-generated values without extra parameters. If you need to bypass GitVersion temporarily for experiments, set the GitVersion_NoFetch property to false during the build command.

  6. Run the SharedMutexHarness stress test

    dev

    The SharedMutexHarness is a console application used to stress-test LiteDB's SharedMutexFactory across different processes and Windows sessions. By default, the parent process acquires a shared mutex, spawns a child process that is designed to time out, releases the mutex, and then spawns a second child process that should succeed in acquiring it.

    dotnet run --project SharedMutexHarness/SharedMutexHarness.csproj

  7. Dry-run LiteDB versions locally

    dev

    You can inspect the semantic version that will be applied to a build by using the provided GitVersion helper scripts. First, ensure the tool is restored by running dotnet tool restore. The scripts resolve the git ref to a SHA and echo key fields like FullSemVer, NuGetVersion, InformationalVersion, and BranchName.

    # PowerShell (Windows, macOS, Linux)
./scripts/gitver/gitversion.ps1            # show version for HEAD
./scripts/gitver/gitversion.ps1 dev~3      # inspect an arbitrary commit
./scripts/gitver/gitversion.ps1 -Json      # emit raw JSON
    # Bash (macOS, Linux, Git Bash on Windows)
./scripts/gitver/gitversion.sh             # show version for HEAD
./scripts/gitver/gitversion.sh dev~3       # inspect an arbitrary commit
./scripts/gitver/gitversion.sh --json      # emit raw JSON

  8. Run the TransactionMonitor finalizer crash reproduction

    dev

    This reproduction project demonstrates the LiteException caused by the TransactionMonitor finalizer executing on the GC finalizer thread. This violates the expectation that the transaction belongs to the current thread, resulting in the error: current thread must contains transaction parameter.

    To run the reproduction, use the following command. You can pin a specific LiteDB NuGet package version or use the in-repo source code via project references.

    dotnet run --project LiteDB.ReproRunner/Repros/Issue_2561_TransactionMonitor/Issue_2561_TransactionMonitor.csproj -c Release -p:UseProjectReference=true

  9. Run reproduction projects locally

    dev

    You can execute reproduction projects on your local machine by mirroring the CI workflow.

    List repros with a filter

    To see a filtered list of available repros in JSON format:

    dotnet run --project LiteDB.ReproRunner/LiteDB.ReproRunner.Cli -- list --json --filter Fast

    Execute a specific repro

    To run a specific repro using CI settings (e.g., simulating a specific Windows runner):

    dotnet run --project LiteDB.ReproRunner/LiteDB.ReproRunner.Cli -- \
  run <repro_name> --ci --target-os <runner_label>

    Example: dotnet run --project LiteDB.ReproRunner/LiteDB.ReproRunner.Cli -- run Issue_2561_TransactionMonitor --ci --target-os windows-2022

    Locating Artifacts

    Local artifacts are generated in: LiteDB.ReproRunner/LiteDB.ReproRunner.Cli/bin/<tfm>/<configuration>/runs/...

    # List repros (optionally filtered):
dotnet run --project LiteDB.ReproRunner/LiteDB.ReproRunner.Cli -- list --json --filter Fast

# Execute a repro under CI settings (for example, on Windows):
dotnet run --project LiteDB.ReproRunner/LiteDB.ReproRunner.Cli -- \
  run Issue_2561_TransactionMonitor --ci --target-os windows-2022

  10. Write a new LiteDB reproduction project

    dev

    To add a new reproduction scenario to the repository, follow these steps:

    1. Create a folder in LiteDB.ReproRunner/Repros/ named after your identifier (e.g., Issue_1234_MyScenario/).
    2. Scaffold a .NET 8 console project using a .csproj that can toggle between the NuGet package and the in-repo source via the UseProjectReference property.
    3. Implement Program.cs: The logic must exit with code 0 if the expected (buggy) behavior is observed, and non-zero if it cannot trigger the behavior. It should also read orchestration environment variables for parallel runs.
    4. Create repro.json: A manifest containing required metadata (see Manifest Schema).
    5. Add a README.md: Document the scenario, issue links, and expected outcomes.
    6. Update CI: If the repro is intended for the smoke suite.
    <Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <UseProjectReference Condition="'$(UseProjectReference)' == ''">false</UseProjectReference>
    <LiteDBPackageVersion Condition="'$(LiteDBPackageVersion)' == ''">5.0.20</LiteDBPackageVersion>
  </PropertyGroup>

  <ItemGroup Condition="'$(UseProjectReference)' == 'true'">
    <ProjectReference Include="..\..\..\LiteDB\LiteDB.csproj" />
  </ItemGroup>

  <ItemGroup Condition="'$(UseProjectReference)' != 'true'">
    <PackageReference Include="LiteDB" Version="$(LiteDBPackageVersion)" />
  </ItemGroup>
</Project>