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/dotnetcore/FreeSql 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 2w ago
• 16 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 59% 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 dotnetcore/FreeSql repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/dotnetcore/FreeSql.

What it runs against: a local clone of dotnetcore/FreeSql — 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 dotnetcore/FreeSql | 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 ≤ 44 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of dotnetcore/FreeSql. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/dotnetcore/FreeSql.git
#   cd FreeSql
#
# 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 dotnetcore/FreeSql and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "dotnetcore/FreeSql(\\.git)?\\b" \\
  && ok "origin remote is dotnetcore/FreeSql" \\
  || miss "origin remote is not dotnetcore/FreeSql (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 "Examples/dbcontext_01/DbContexts/SongContext.cs" \\
  && ok "Examples/dbcontext_01/DbContexts/SongContext.cs" \\
  || miss "missing critical file: Examples/dbcontext_01/DbContexts/SongContext.cs"
test -f "Examples/base_entity/Entities/User.cs" \\
  && ok "Examples/base_entity/Entities/User.cs" \\
  || miss "missing critical file: Examples/base_entity/Entities/User.cs"
test -f "Examples/repository_01/Entitys/Song.cs" \\
  && ok "Examples/repository_01/Entitys/Song.cs" \\
  || miss "missing critical file: Examples/repository_01/Entitys/Song.cs"
test -f "Directory.Build.props" \\
  && ok "Directory.Build.props" \\
  || miss "missing critical file: Directory.Build.props"
test -f "Examples/aspnetcore_transaction/TransactionalAttribute.cs" \\
  && ok "Examples/aspnetcore_transaction/TransactionalAttribute.cs" \\
  || miss "missing critical file: Examples/aspnetcore_transaction/TransactionalAttribute.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 44 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~14d)"
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/dotnetcore/FreeSql"
  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).

FreeSql is an AOT-compatible ORM for .NET that supports 20+ database backends (MySQL, PostgreSQL, SQL Server, Oracle, SQLite, Firebird, ClickHouse, DuckDB, Chinese databases like 达梦/金仓/南大通用, and others). It provides CodeFirst migrations, DbFirst entity generation, advanced type mapping (e.g., PostgreSQL arrays), expression-to-SQL compilation, and relationship loading (one-to-many, many-to-many with lazy loading). Monorepo with Examples/ containing runnable ASP.NET Core demos (aspnetcore_transaction/, base_entity/) showing transactional patterns and entity mapping. Core ORM logic resides in the main assembly (inferred from lack of separate packages/core folder), with a Directory.Build.props centralizing project configuration. Test coverage approach unclear from file listing.

.NET developers building data access layers who need to target diverse databases (especially Chinese commercial databases) or require AOT compilation for deployment scenarios where reflection is restricted. Used by teams standardizing on a single ORM across heterogeneous database environments.

Production-ready. The project shows 21.7MB of C# code, comprehensive GitHub Actions CI (docfx, gitee-mirror workflows), structured Examples directory with working ASP.NET Core samples, and covers an unusually wide database range. Active maintenance is evident from multiple examples, migration support, and repository pattern implementations.

Moderate risk: Chinese domestic database support (达梦, 金仓, etc.) has smaller community testing pools than MySQL/PostgreSQL, and the wide database matrix means surface area for bugs. Single maintainer (2881099) visible in wiki links suggests centralization risk. No obvious breaking-change policy or changelog visible in file list.

Cannot determine from static file list alone—no recent commit dates, PR list, or milestones visible. However, presence of Examples/aspnetcore_transaction with TransactionalAttribute.cs and FodyWeavers integration suggests active work on AOP-based transaction handling and IL-weaving patterns.

git clone https://github.com/dotnetcore/FreeSql.git
cd FreeSql
dotnet build
dotnet test  # if test project exists
cd Examples/base_entity && dotnet run

Daily commands:

cd Examples/aspnetcore_transaction
dotnet run
# Launches ASP.NET Core app; uses 123.db (SQLite) by default
# Or:
cd Examples/base_entity
dotnet run

• Examples/dbcontext_01/DbContexts/SongContext.cs — Demonstrates the core DbContext pattern that FreeSql uses—essential for understanding how the ORM integrates with applications.
• Examples/base_entity/Entities/User.cs — Shows the base entity model structure and attribute-based configuration patterns FreeSql relies on for code-first mapping.
• Examples/repository_01/Entitys/Song.cs — Illustrates entity definition conventions and how FreeSql infers schema from C# classes for multiple database backends.
• Directory.Build.props — Central build configuration affecting the entire multi-database, multi-runtime (AOT) support strategy across 600+ files.
• Examples/aspnetcore_transaction/TransactionalAttribute.cs — Core transaction management pattern showing how FreeSql handles ACID guarantees—critical for production usage.
• Examples/efcore_to_freesql/FreeSqlExtensions/CodeFirstExtensions.cs — Extension methods for code-first migrations and schema creation—key abstraction for DbFirst vs CodeFirst workflows.
• Examples/dbcontext_01/Program.cs — Dependency injection and ORM initialization—shows how FreeSql integrates into ASP.NET Core startup pipeline.

Add a New Entity Model with Code-First Mapping

1. Create a new C# class in Examples/base_entity/Entities/ or Examples/repository_01/Entitys/ following the pattern: public class [EntityName] { public int Id { get; set; } /* properties */ } (Examples/base_entity/Entities/User.cs)
2. Apply FreeSql attributes (if needed): [Table(Name="table_name")] on class, [Column(DbType="int")] on properties for custom mappings across Mysql/PostgreSQL/SqlServer/Oracle (Examples/repository_01/Entitys/Song.cs)
3. Register entity in DbContext by adding: builder.Entity<YourEntity>() in SongContext.OnModelCreating() method (Examples/dbcontext_01/DbContexts/SongContext.cs)
4. Run migrations using CodeFirstExtensions.SyncStructure() in Program.cs or use the Generation Tool if DbFirst import is needed (Examples/efcore_to_freesql/FreeSqlExtensions/CodeFirstExtensions.cs)

Add a New Repository with CRUD Operations

1. Create repository class in domain folder inheriting from base repository pattern, injecting FreeSql context (IFreeSql) (Examples/aspnetcore_transaction/Domain/SongRepository.cs)
2. Implement CRUD methods using context.Select<T>(), context.Insert<T>(), context.Update<T>(), context.Delete<T>() following TransactionalAttribute pattern for multi-step operations (Examples/aspnetcore_transaction/Services/SongService.cs)
3. Register repository in dependency injection (Program.cs or Startup.cs) as: services.AddScoped<ISongRepository, SongRepository>() (Examples/dbcontext_01/Program.cs)

Implement Transaction Boundaries Across Multiple Databases

1. Decorate service methods with [Transactional] attribute or wrap logic in context.BeginTransaction() blocks in Examples/aspnetcore_transaction/Services/ (Examples/aspnetcore_transaction/TransactionalAttribute.cs)
2. Use context.WithTransaction(transaction) to coordinate multiple repositories within one logical unit of work, supporting Mysql, PostgreSQL, SqlServer, Oracle, Sqlite simultaneously (Examples/aspnetcore_transaction/Domain/SongRepository.cs)
3. Verify AOT compatibility in Directory.Build.props settings if deploying to native image targets (Windows/Linux/macOS) (Directory.Build.props)

Support Multiple Database Providers (Mysql, PostgreSQL, SqlServer, Oracle, Sqlite, etc.)

1. Install the provider NuGet: FreeSql.Provider.MySql, FreeSql.Provider.PostgreSQL, FreeSql.Provider.SqlServer, FreeSql.Provider.Oracle, FreeSql.Provider.Sqlite, etc. (Examples/dbcontext_01/dbcontext_01.csproj)
2. Configure connection string in appsettings.json and instantiate FSql with the correct DataType: new FreeSqlBuilder().UseConnectionString(DataType.MySql, connectionString) (Examples/dbcontext_01/appsettings.json)
3. Entity attributes like [Column(DbType="jsonb")] (PostgreSQL) and advanced type mappings are handled automatically by FreeSql's provider layer (Examples/repository_01/Entitys/Song.cs)

• .NET Core 2.1+, .NET Framework 4.0+, Xamarin, AOT — FreeSql targets maximum platform coverage from legacy frameworks to modern AOT compilation for native binary deployments, reducing memory footprint on edge devices
• Multi-Database Support (Mysql, PostgreSQL, SqlServer, Oracle, Sqlite, Firebird, ClickHouse, DuckDB, etc.) — Plugin-based provider architecture decouples dialect-specific SQL generation, allowing single codebase to target 10+ backends without recompilation
• Attribute-Based Mapping ([Table], [Column], [ForeignKey]) — Avoids heavy fluent API chains; enables code-first development with minimal boilerplate while supporting advanced mappings (PostgreSQL arrays, JSON types)
• Expression Trees & LINQ Translation — Type-safe query building allows C# lambda expressions to translate to native SQL per provider, catching errors at compile time rather than runtime
• Repository & Service Patterns with DI — Layered architecture enables testability, separation of concerns, and easy swapping of persistence implementations

• Single codebase for 10+ databases vs. database-specific optimizations

  • Why: Broad platform support is prioritized over bespoke tuning; each provider handles dialect translation
  • Consequence: Some database-specific performance features (e.g., PostgreSQL window functions) require custom SQL fallbacks

• Attribute-driven configuration over fluent API

  • Why: Minimizes boilerplate and enables AOT-friendly reflection-free configuration in many scenarios
  • Consequence: Complex mappings require attributes on entities; less discoverable than fluent API, harder to factor into base configurations

• Eager loading, lazy loading, and include() support vs. query optimization control

  • Why: Developer convenience for navigating relationships
  • Consequence: N+

AOT constraints: Support for AOT does NOT mean full reflection-free operation on all databases—verify specific backends in release notes. Fody dependency: Projects using TransactionalAttribute require FodyWeavers.xml and Fody NuGet package; misconfiguration silently disables weaving. Database-specific type mapping: PostgreSQL arrays, Oracle hierarchies, etc. require explicit provider configuration—defaults may not be safe for migration. Chinese DB licensing: 达梦, 金仓, 神通 are commercial; licensing and driver availability not documented in visible files.

• Expression Tree Compilation to SQL — FreeSql translates LINQ expressions directly to database-specific SQL dialects; understanding this prevents performance cliffs and database-specific bugs
• AOT (Ahead-of-Time) Compilation — FreeSql's defining feature; avoids JIT reflection overhead but forbids dynamic type creation—shapes how entities and mappings must be defined
• IL Weaving (Fody) — FodyWeavers.xml enables compile-time bytecode injection for TransactionalAttribute behavior; bypasses runtime AOP proxies and works with AOT
• Repository and Unit of Work Patterns — FreeSql explicitly implements these DDD patterns (Domain/SongRepository.cs); required for clean separation of data access from business logic
• Global Filters and Query Interception — FreeSql's filter mechanism automatically applies WHERE clauses (e.g., soft deletes, tenant isolation) without explicit per-query code; critical for data isolation
• Optimistic vs. Pessimistic Locking — FreeSql supports both strategies; choice impacts concurrency performance and data consistency guarantees—must align with domain requirements
• Read/Write Separation and Splitting Table/Database — FreeSql routes SELECTs to replicas and writes to primary; table sharding requires custom logic—essential for scaling high-throughput systems

• dotnetcore/SqlSugar — Primary competitor ORM in the .NET ecosystem; also supports many Chinese databases and offers comparison for feature parity decisions
• dotnet/efcore — Microsoft's official Entity Framework Core; FreeSql differentiates by broader DB support and AOT focus; study for compatibility/migration patterns
• dotnetcore/Util — Companion .NET Core utility library from the same organization; likely used for DI, logging, and validation in FreeSql ecosystem
• dotnetcore/FreeIM — Another NCC member project; demonstrates patterns for repository/UnitOfWork and transaction management in the FreeSql context
• aspnet/AspNetCore — FreeSql's Examples/aspnetcore_transaction depends on ASP.NET Core DI and middleware patterns; reference for integration best practices

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 unit tests for multi-database dialect support

FreeSql supports 15+ database providers (MySQL, PostgreSQL, SqlServer, Oracle, SQLite, Firebird, ClickHouse, DuckDB, TDengine, QuestDB, MsAccess, and Chinese domestic databases). The repo lacks dedicated test projects for each dialect. Adding parameterized test suites would ensure cross-database compatibility and prevent regressions when updating dialect-specific code.

• [ ] Create test/FreeSql.Tests.Dialects directory with subdirectories for each major provider
• [ ] Add MySqlDialectTests.cs, PostgreSqlDialectTests.cs, SqlServerDialectTests.cs, etc. with parameterized test methods
• [ ] Test CRUD operations, query generation, migration, and type mapping for each dialect
• [ ] Integrate into GitHub Actions CI/CD workflow to run against real database instances (using Docker containers)
• [ ] Reference existing Examples/base_entity tests as baseline for entity mapping scenarios

Create AOT compatibility test suite and documentation

FreeSql advertises AOT (.NET Native) support as a key differentiator ('The First AOT ORM'), but there's no dedicated AOT test project or CI workflow validating this claim. Add a test project that builds and validates AOT compilation, plus document any reflection-free APIs or native AOT limitations.

• [ ] Create Examples/aot_compilation or test/FreeSql.Tests.Aot project with native AOT publish profile
• [ ] Add .github/workflows/aot-build.yml to verify AOT compilation on each commit
• [ ] Document AOT-compatible APIs in README.md and add AOT-specific examples
• [ ] Test with <PublishAot>true</PublishAot> in csproj and verify no System.Reflection issues arise
• [ ] Add trimmer configuration files (TrimmerRootAssembly.xml) if needed

Enhance DbFirst code generation with comprehensive test coverage

The repo mentions DbFirst import capability and links to a Generation Tool, but Examples/dbcontext_01 and Examples/efcore_to_freesql lack complete end-to-end test coverage for schema introspection and entity generation. Add tests validating that generated entities match database schema accurately across all supported databases.

• [ ] Create test/FreeSql.Tests.DbFirst with test databases for each dialect (via Docker)
• [ ] Add SchemaIntrospectionTests.cs verifying table, column, key, and constraint detection
• [ ] Add EntityGenerationTests.cs validating generated C# entity code matches schema definitions
• [ ] Test edge cases: reserved keywords, complex types, computed columns, inherited tables
• [ ] Update .github/workflows/docfx.yml or create dedicated workflow to validate DbFirst output quality

• Add unit tests for Examples/base_entity/ModAsTableImpl.cs dynamic table operations—currently only shown in code without test coverage.
• Document database-specific type mapping examples (PostgreSQL array, Oracle hierarchies) in Examples/ with runnable samples and README—currently referenced in README but no concrete code examples.
• Create a Chinese-database-specific example (e.g., Examples/dameng_migration/) showing CodeFirst migration against 达梦, since these backends have less community documentation.

FreeSql is an established ORM framework with medium security posture. The main concerns are: (1) potential SQL injection risks inherent to dynamic SQL construction without visible evidence of comprehensive parameterization patterns, (2) example projects containing hardcoded credentials and database files in version control, (3) missing security header configurations in ASP.NET Core examples, and (4) lack of visible automated security scanning in CI/CD workflows. The codebase should implement stricter input validation, move credentials to secure configuration management, remove sensitive example data from version control, and add automated security scanning to the build pipeline. The core ORM library itself requires thorough review of SQL generation and parameterization mechanisms.

• Medium · Potential SQL Injection Risk in ORM Implementation — Core FreeSql ORM components (not visible in provided structure). FreeSql is an ORM that handles raw SQL queries and dynamic SQL construction. Without visible input validation and parameterization patterns in the file structure, there is a risk of SQL injection vulnerabilities if user input is not properly sanitized before being passed to database queries. Fix: Ensure all user inputs are validated and parameterized. Use prepared statements and parameterized queries exclusively. Implement input validation and output encoding for all database operations.
• Medium · Hardcoded Database Credentials in Example Files — Examples/dbcontext_01/appsettings.json, Examples/dbcontext_01/appsettings.Development.json, and similar configuration files in example projects. The codebase contains example projects with configuration files (appsettings.json, launchSettings.json) that may contain hardcoded database connection strings or credentials, which could be inadvertently exposed if committed to version control. Fix: Move all sensitive credentials to secure configuration management systems. Use Azure Key Vault, AWS Secrets Manager, or .NET User Secrets. Ensure appsettings files contain only non-sensitive default values. Add appsettings.*.json to .gitignore.
• Low · Example Projects Contain Database Files — Examples/aspnetcore_transaction/123.db, Examples/base_entity/AspNetRoleClaims/ids_api.db. SQLite database files (.db) are checked into version control within example projects, which could contain test data and may expose schema information or example data patterns. Fix: Remove .db files from version control. Add *.db to .gitignore. Provide database initialization scripts or seeding code instead for examples.
• Low · Missing Security Headers Configuration — Examples/aspnetcore_transaction/Program.cs, Examples/aspnetcore_transaction/Startup.cs, Examples/dbcontext_01/Program.cs, Examples/dbcontext_01/Startup.cs. ASP.NET Core example projects (aspnetcore_transaction, dbcontext_01) do not show explicit security header configuration in the provided file structure, which could leave applications vulnerable to common web attacks. Fix: Configure security headers in Startup.cs or Program.cs including Content-Security-Policy, X-Content-Type-Options, X-Frame-Options, Strict-Transport-Security, and others. Use middleware like HSTS, helmet, or equivalent .NET libraries.
• Low · Insufficient Input Validation in Controllers — Examples/dbcontext_01/Controllers/ValuesController.cs, Examples/aspnetcore_transaction/Controllers/HomeController.cs. The ValuesController and HomeController in example projects may not demonstrate proper input validation patterns, which could lead to injection attacks or unexpected behavior. Fix: Implement comprehensive input validation using data annotations, FluentValidation, or custom validators. Validate all user-supplied data for type, length, format, and range. Implement output encoding for all user-controlled data.
• Low · No Visible Dependency Vulnerability Scanning — .github/workflows (no security scanning workflows visible). The repository structure does not show evidence of automated dependency vulnerability scanning (e.g., dependabot configuration, security.yml workflow), which could allow outdated or vulnerable dependencies to go undetected. Fix: Enable GitHub Dependabot for automated dependency updates. Implement OWASP dependency-check or Snyk in CI/CD pipeline. Regularly audit NuGet package vulnerabilities using dotnet list package --vulnerable.

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.