Getting Started

Polecat integrates with the standard .NET IServiceCollection abstractions for IoC registration. Most features work without IoC, but the async daemon and schema management leverage the IHost model.

Installation

.NET CLI

dotnet add package Polecat

Powershell

PM> Install-Package Polecat

SQL Server 2025

Polecat requires SQL Server 2025 (v17) or later for its native JSON type support. For local development, the easiest approach is Docker:

# docker-compose.yml
services:
  sqlserver:
    image: mcr.microsoft.com/mssql/server:2025-CU1-ubuntu-24.04
    environment:
      ACCEPT_EULA: "Y"
      MSSQL_SA_PASSWORD: "YourStrong!Password"
    ports:
      - "1433:1433"

Registering Polecat

In your application startup, call AddPolecat() to register all services:

builder.Services.AddPolecat(options =>
{
    // Connection string to your SQL Server 2025 database
    options.Connection("Server=localhost;Database=myapp;User Id=sa;Password=YourStrong!Password;TrustServerCertificate=True");

    // Optionally change the default schema (default is "dbo")
    options.DatabaseSchemaName = "myschema";
});

See Bootstrapping Polecat for more options.

TIP

AddPolecat() registers IDocumentStore as a singleton, and IDocumentSession / IQuerySession as scoped services. In most cases you should inject a session directly.

Working with Documents

Define a simple document type:

public class User
{
    public Guid Id { get; set; }
    public required string FirstName { get; set; }
    public required string LastName { get; set; }
    public bool Internal { get; set; }
}

For more information on document identity, see identity.

Use IDocumentSession to store and query documents:

// Store a document
app.MapPost("/user", async (CreateUserRequest create, IDocumentSession session) =>
{
    var user = new User
    {
        FirstName = create.FirstName,
        LastName = create.LastName,
        Internal = create.Internal
    };
    session.Store(user);
    await session.SaveChangesAsync();
});

// Query with LINQ
app.MapGet("/users", async (bool internalOnly, IDocumentSession session, CancellationToken ct) =>
{
    return await session.Query<User>()
        .Where(x => x.Internal == internalOnly)
        .ToListAsync(ct);
});

// Load by ID
app.MapGet("/user/{id:guid}", async (Guid id, IQuerySession session, CancellationToken ct) =>
{
    return await session.LoadAsync<User>(id, ct);
});

For more information on querying, check document querying.

Working with Events

Please check the Event Store quick start.

Creating a Standalone Store

You can create a document store outside of the generic host infrastructure using DocumentStore.For:

var store = DocumentStore.For("Server=localhost;Database=myapp;User Id=sa;Password=YourStrong!Password;TrustServerCertificate=True");

Or with full configuration:

var store = DocumentStore.For(opts =>
{
    opts.Connection("Server=localhost;Database=myapp;User Id=sa;Password=YourStrong!Password;TrustServerCertificate=True");
    // Configure additional options...
});