If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/praeclarum/sqlite-net shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2d ago
• 18 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 53% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live praeclarum/sqlite-net repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/praeclarum/sqlite-net.

What it runs against: a local clone of praeclarum/sqlite-net — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in praeclarum/sqlite-net | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of praeclarum/sqlite-net. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/praeclarum/sqlite-net.git
#   cd sqlite-net
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of praeclarum/sqlite-net and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "praeclarum/sqlite-net(\\.git)?\\b" \\
  && ok "origin remote is praeclarum/sqlite-net" \\
  || miss "origin remote is not praeclarum/sqlite-net (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/SQLite.cs" \\
  && ok "src/SQLite.cs" \\
  || miss "missing critical file: src/SQLite.cs"
test -f "src/SQLiteAsync.cs" \\
  && ok "src/SQLiteAsync.cs" \\
  || miss "missing critical file: src/SQLiteAsync.cs"
test -f "src/AssemblyInfo.cs" \\
  && ok "src/AssemblyInfo.cs" \\
  || miss "missing critical file: src/AssemblyInfo.cs"
test -f "Directory.Build.props" \\
  && ok "Directory.Build.props" \\
  || miss "missing critical file: Directory.Build.props"
test -f "tests/SQLite.Tests/TestDb.cs" \\
  && ok "tests/SQLite.Tests/TestDb.cs" \\
  || miss "missing critical file: tests/SQLite.Tests/TestDb.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/praeclarum/sqlite-net"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

sqlite-net is a lightweight ORM and SQLite client library for .NET that wraps SQLite 3 into a single-file (SQLite.cs) or dual-file (+ SQLiteAsync.cs) implementation. It provides strongly-typed CRUD operations, LINQ-like querying, and automatic table generation from C# classes without requiring changes to your data models. Monolithic source layout: src/SQLite.cs contains the synchronous ORM engine (~10K lines), src/SQLiteAsync.cs wraps it with Task-based async. Four NuGet package variants in nuget/ directory (base, pcl, sqlcipher, static) that bundle different SQLitePCLRaw providers. Tests organized by feature in tests/SQLite.Tests/ (e.g., AsyncTests.cs, CreateTableTest.cs, EnumTest.cs). No separate client/server; entirely embedded database.

.NET/Xamarin developers (desktop, mobile, UWP, .NET Core) who need a simple embedded database layer without the complexity of Entity Framework, particularly those building cross-platform apps on Xamarin.iOS, Xamarin.Android, UWP, or Azure.

Production-ready and actively maintained. The repo has comprehensive test coverage across 40+ test files (tests/SQLite.Tests/), GitHub Actions CI/CD pipeline (build.yml), and multiple NuGet package variants (sqlite-net-pcl, sqlite-net-sqlcipher, sqlite-net-static) with varying download metrics. Single-maintainer project (praeclarum) with steady updates.

Low risk for core functionality but single-maintainer dependency. The library is self-contained (minimal external deps via SQLitePCLRaw abstraction in different packages), but upstream SQLite3 updates require manual integration. No recent commit date visible in provided data, so currency should be verified. API stability is good, but check GitHub Issues for any open blockers.

Unable to determine from provided file list (no recent commit log visible). Check GitHub Actions build.yml and recent PR/Issue activity on https://github.com/praeclarum/sqlite-net to see current work.

git clone https://github.com/praeclarum/sqlite-net.git && cd sqlite-net && dotnet build SQLite.sln

Daily commands: make (see Makefile) or dotnet build SQLite.sln && dotnet test tests/SQLite.Tests/SQLite.Tests.csproj

• src/SQLite.cs — Core ORM implementation containing SQLiteConnection, query execution, LINQ support, and all synchronous database operations—the heart of the library.
• src/SQLiteAsync.cs — Async-only wrapper around SQLiteConnection providing async/await-based API for all database operations without blocking threads.
• src/AssemblyInfo.cs — Assembly metadata and version information shared across all NuGet packages; changes affect all consumers.
• Directory.Build.props — Central build configuration for the entire solution; controls package versioning, target frameworks, and compiler settings.
• tests/SQLite.Tests/TestDb.cs — Test database initialization and shared test fixtures; establishes conventions for how all test suites verify functionality.
• nuget/SQLite-net-std/SQLite-net-std.csproj — Primary NuGet package definition for the standard .NET library; defines dependencies, targets, and how the library is distributed.

Add a new column attribute for custom SQL constraints

1. Define a new public attribute class inheriting from Attribute (e.g., [CheckConstraint]) in src/SQLite.cs near existing attributes like [PrimaryKey], [Unique] (src/SQLite.cs)
2. Update the GetColumnInfo() method to read your new attribute and append SQL (e.g., 'CHECK (value > 0)') during CREATE TABLE generation (src/SQLite.cs)
3. Create a test class (e.g., tests/SQLite.Tests/CheckConstraintTest.cs) that defines a model with your attribute, creates the table, and verifies the constraint is enforced (tests/SQLite.Tests/CheckConstraintTest.cs)

Add support for a new scalar data type (e.g., JSON serialization for custom objects)

1. Locate the Read<T>() and WriteValue() methods in src/SQLite.cs that handle type conversions; add a new type case checking obj.GetType() and using custom serialization (src/SQLite.cs)
2. Create a test in tests/SQLite.Tests/ (e.g., CustomTypeTest.cs) that inserts and queries objects of your type, verifying round-trip serialization (tests/SQLite.Tests/CustomTypeTest.cs)

Add a new async-only helper method to the async API

1. In src/SQLiteAsync.cs, add your public async Task-returning method to SQLiteAsyncConnection or TableAsync<T>, using _async.ExecuteAsync() or _queryAsync() internally (src/SQLiteAsync.cs)
2. Write a corresponding test in tests/SQLite.Tests/AsyncTests.cs that calls your method with await and verifies correctness (tests/SQLite.Tests/AsyncTests.cs)

Add a new NuGet package variant for a platform

1. Create a new directory under nuget/ (e.g., nuget/SQLite-net-myruntimeid/) and copy an existing .csproj as a template (nuget/SQLite-net-std/SQLite-net-std.csproj)
2. Update the new .csproj's <TargetFramework>, <RuntimeIdentifier>, and <PackageId> properties; adjust SQLitePCLRaw dependency as needed (nuget/SQLite-net-myruntimeid/SQLite-net-myruntimeid.csproj)
3. Add a build step in .github/workflows/build.yml to pack your new variant and push to NuGet (.github/workflows/build.yml)

• C# / .NET Standard 2.0 — Cross-platform compatibility; single codebase runs on .NET Framework, .NET Core, Xamarin, and modern .NET 5+
• SQLitePCLRaw — Abstracts platform-specific sqlite3 native library bindings; enables single library to work on iOS, Android, Windows, macOS, Linux
• Reflection + Expression Trees for LINQ — Converts .NET LINQ queries to SQL without external parsing; enables compile-time safety and IntelliSense
• Attribute-based ORM — Minimal configuration; developers decorate properties to define schema, no separate mapping DSL needed

• Synchronous + async APIs in same library

  • Why: Two APIs required: older sync-only code needs SQLiteConnection; modern async code uses SQLiteAsyncConnection
  • Consequence: Code duplication; async wrapper is thin layer, not independent re-implementation. Adds surface area for bugs.

• LINQ provider implemented as custom expression visitor (not using DbContext/EF Core patterns)

  • Why: Lighter weight, fewer dependencies, simpler mental model for simple ORM use cases
  • Consequence: Advanced EF Core features (includes, navigation properties, change tracking) not available. Limited to basic projections and filters.

• All schema generation and reflection happens at runtime (no code generation)

  • Why: No build step required; simpler onboarding
  • Consequence: Schema discovery is slower on first table access; no compile-time schema validation.

• Single monolithic SQLite.cs file (~2500 lines)

  • Why: Historical design; easier to maintain as single unit without circular dependencies
  • Consequence: File is unwieldy to navigate; difficult to isolate concerns (mapping, query building, execution in one file).

• Multiple NuGet package variants (pcl, sqlcipher, static, base)

  • Why: Customers have different needs: some want encryption, some want specific sqlite3 version, some want no external deps
  • Consequence: Maintenance burden; changes must be validated across 4 package configurations.

• Entity Framework Core compatibility—does not implement DbContext, DbSet, or IQueryable navigation properties
• Real-time synchronization—no built-in sync protocol for multi-device data sync
• Schema versioning/migrations beyond simple user-written upgrade functions (no automatic schema diffing)
• Hierarchical/nested queries or GraphQL—focused on relational SQL only
• In-memory database—targets SQLite which is file-based
• NoSQL or document-oriented features—SQL-only

1. SQLite.cs and SQLiteAsync.cs are large single files; navigation requires searching within them or using IDE outline. 2. Multiple NuGet package variants (pcl, static, sqlcipher, base) solve different binding scenarios; choosing wrong one may cause linker/runtime errors. 3. Reflection-driven ORM means attribute placement on class properties is mandatory ([Table], [Column], [PrimaryKey]) for schema generation; silent failures if misconfigured. 4. Async version (SQLiteAsync.cs) wraps sync methods with Task.Run; not true async I/O on all platforms. 5. Test projects include iOS-specific variant (SQLite.Tests.iOS) requiring macOS/Xcode; most contributors likely use .Tests only.

• Reflection-driven ORM — sqlite-net uses C# Reflection to inspect class properties and custom Attributes ([Table], [Column], [PrimaryKey]) to auto-generate DDL and map query results back to objects; understanding this pattern is essential for configuring models correctly
• SQLite3 Parameter Binding (Parameterized Queries) — sqlite-net uses SQLite's parameter binding API to safely embed variables in SQL statements, preventing injection; critical for security and understanding how CRUD operations work in src/SQLite.cs
• Provider Abstraction Pattern (SQLitePCLRaw) — sqlite-net decouples from a specific SQLite native binding via SQLitePCLRaw, allowing different backends (vcruntime, sqlcipher, platform-native); explains why four NuGet packages exist
• Async/Await Wrapping (Task.Run) — SQLiteAsync.cs wraps synchronous SQLite calls with Task.Run to provide async API without native async I/O; important for understanding concurrency limits and blocking behavior
• Custom Attribute-based Mapping — sqlite-net uses C# Attributes ([PrimaryKey], [AutoIncrement], [Indexed], [Collation], [Ignore]) to annotate classes with SQLite metadata; understanding these is mandatory for using the library correctly
• SQLite PRAGMA Statements — sqlite-net internally uses PRAGMA commands (e.g., PRAGMA table_info, PRAGMA foreign_keys) to inspect schema and enforce constraints; visible in src/SQLite.cs table introspection code
• Enum Type Mapping in SQL — sqlite-net provides special handling for C# Enums (stores as int or string), with separate tests (EnumTest.cs, EnumNullableTest.cs, EnumCacheTest.cs) showing non-trivial edge cases worth understanding

• aspnet/EntityFrameworkCore — Full-featured .NET ORM with SQLite provider; sqlite-net is lighter alternative for simpler scenarios
• sqlite/sqlite — Upstream SQLite C library; sqlite-net is a .NET wrapper around this
• ericsink/SQLitePCLRaw — Core dependency abstraction layer used by sqlite-net packages to bind different SQLite implementations (vcruntime, sqlcipher, platform-native)
• dapper-dot-net/Dapper — Micro-ORM alternative for .NET; lighter than EF but more query-focused than sqlite-net's attribute-driven approach
• Xamarin/Xamarin.Forms — Cross-platform mobile framework for which sqlite-net was originally designed (Xamarin.iOS, Xamarin.Android)

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for SQLiteAsync.cs async operations

SQLiteAsync.cs is a core async API but tests/SQLite.Tests/AsyncTests.cs likely has limited coverage for edge cases. The repo lacks dedicated tests for concurrent async operations, cancellation tokens, and transaction handling. This is critical since async correctness is non-trivial and affects all async consumers of the library.

• [ ] Review tests/SQLite.Tests/AsyncTests.cs to identify gaps in async/await patterns, CancellationToken handling, and deadlock scenarios
• [ ] Add tests for concurrent insert/update/query operations using Task.WhenAll
• [ ] Add tests for proper disposal and cleanup of async operations (using statements)
• [ ] Add tests for transaction rollback/commit in async contexts
• [ ] Reference src/SQLiteAsync.cs method signatures to ensure all public async methods are tested

Add GitHub Actions workflow for multi-platform NuGet package validation

The repo has 4 different NuGet packages (sqlite-net-pcl, sqlite-net-sqlcipher, sqlite-net-static, plus the base) but .github/workflows/build.yml likely doesn't validate all package variants. A new workflow should test that each package builds correctly, publishes with correct dependencies, and includes proper symbols.

• [ ] Examine .github/workflows/build.yml to see current coverage
• [ ] Create a new .github/workflows/nuget-packages.yml that builds each csproj in nuget/ directory (SQLite-net-base, SQLite-net-sqlcipher, SQLite-net-static, SQLite-net-std)
• [ ] Add package validation steps using nuget verify or dotnet pack --verify-match-prerelease
• [ ] Add a step to verify each package's .nupkg contents match expected files from src/
• [ ] Ensure workflow runs on PRs and validates against nuget schema

Add integration tests for database schema migration and versioning patterns

tests/SQLite.Tests/MigrationTest.cs exists but the repo lacks comprehensive documentation and test coverage for real-world migration scenarios. The library should provide clear patterns for version management, table alterations, and data transformations—critical for users managing schema changes across versions.

• [ ] Review tests/SQLite.Tests/MigrationTest.cs current test cases
• [ ] Add tests for AddColumn operations with default values and nullable handling
• [ ] Add tests for renaming columns (SQLite limitations) and workaround patterns
• [ ] Add tests for index/constraint migrations
• [ ] Add tests for data transformation during migrations (e.g., splitting/merging columns)
• [ ] Document patterns in README.md with code examples from the tests

• Add missing test coverage for edge cases in src/SQLite.cs type conversion (e.g., nullable enum mapping, custom collation ordering). Check tests/SQLite.Tests/CollateTest.cs and EnumNullableTest.cs for patterns.
• Document NuGet package selection guide in README.md: add decision tree explaining when to use sqlite-net-pcl vs sqlite-net-static vs sqlite-net-sqlcipher, with platform-specific recommendations (currently README is sparse on this).
• Add async test coverage for ConcurrencyTest.cs patterns in SQLiteAsync.cs (e.g., concurrent inserts, transaction rollback under async load). Tests exist for sync but async variants are thin.

The sqlite-net codebase shows reasonable structure as a database library but has several security gaps requiring attention. The primary concern is potential SQL injection risks if parameterized queries aren't enforced throughout. Cryptographic features are optional rather than default, which may lead to unencrypted data at rest for some users. Dependency management practices cannot be fully assessed without package file contents. The project lacks formal security documentation and policies. Overall, while the core library appears reasonably designed, users must exercise care in implementation and security configuration.

• High · Potential SQL Injection via Raw SQL Queries — src/SQLite.cs, src/SQLiteAsync.cs, tests/SQLite.Tests/StringQueryTest.cs. The codebase contains SQLite client functionality that may construct and execute SQL queries. Without visible parameterized query enforcement throughout the codebase, there is risk of SQL injection attacks if user input is concatenated into SQL strings. The presence of 'StringQueryTest.cs' suggests raw string queries are supported. Fix: Ensure all database queries use parameterized queries/prepared statements with bound parameters. Implement input validation and sanitization. Audit all query construction methods to enforce parameter binding over string concatenation.
• High · No Visible Dependency Pinning in Package Management — nuget/*.csproj files, package dependencies. The dependency file content was not provided, making it impossible to verify that package versions are pinned and up-to-date. SQLite-net depends on platform-specific SQLite libraries which may have security vulnerabilities in older versions. Fix: Implement strict version pinning in all .csproj files. Regularly audit and update SQLite native library dependencies. Use lock files (packages.lock.json) to ensure reproducible builds and track transitive dependencies.
• Medium · Cross-Platform SQLite Binary Management — nuget/SQLite-net-static/, nuget/SQLite-net-sqlcipher/. The project supports multiple SQLite implementations (base, sqlcipher, static P/Invoke). Different platforms may use different SQLite binaries from various sources, creating potential supply chain risks if binaries are not properly verified. Fix: Document and verify the source of all SQLite binaries. Implement integrity checks (hash verification) for native libraries. Consider using official SQLite builds or well-maintained community sources with strong security track records.
• Medium · Encryption Support Not Default (SQLCipher Optional) — nuget/SQLite-net-sqlcipher/. SQLCipher encryption is available as an optional package, not bundled by default. Users may unknowingly use the unencrypted package variant when handling sensitive data, leaving databases unencrypted on disk. Fix: Clearly document encryption requirements in README and package descriptions. Consider providing security-by-default options. Add warnings in non-encrypted variants about data at rest protection. Implement compile-time or runtime checks to alert developers about encryption status.
• Medium · Limited Visibility into Cryptographic Implementation — src/SQLite.cs, nuget/SQLite-net-sqlcipher/. The SQLCipher variant delegates to external cryptographic libraries. Without reviewing the actual implementation in SQLite.cs, it's unclear if cryptographic best practices are followed (key derivation, algorithm selection, etc.). Fix: Review cryptographic code paths thoroughly. Ensure use of PBKDF2 or scrypt for key derivation. Verify SQLCipher version is current and patched. Document all cryptographic decisions with rationale.
• Low · Test Database Security Configuration — tests/SQLite.Tests/TestDb.cs, various test files. Test files reference database creation but without visibility into test database setup, there may be insecure defaults used (e.g., in-memory databases, world-readable test files, hardcoded test credentials). Fix: Ensure test databases use in-memory or temporary isolated storage. Never store real credentials in test files. Use test fixtures and mocks for sensitive operations. Clean up test data after execution.
• Low · Missing Security Documentation — Repository root. No visible SECURITY.md or security policy file found. Users cannot easily report security vulnerabilities or understand the project's security posture. Fix: Create a SECURITY.md file with responsible disclosure guidelines. Include security contact information. Document known security considerations and best practices for library users.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.