Implementation Complete - Persistence Documentation (PR 3)

✅ All Requirements Met

New Documentation Created:

• guides/persistence/sql-server.md (472 lines) - Complete SQL Server setup guide

  • ✅ NuGet packages and installation
  • ✅ Configuration with UseWorkflowManagement/UseWorkflowRuntime
  • ✅ Connection strings (SQL auth, Windows auth, pooling)
  • ✅ Migration options (automatic vs manual)
  • ✅ Troubleshooting and production considerations
  • ✅ Migration from SQLite guidance
  • Addresses: Issues [DOC] How to use SQLServer instead of SqlLite in Els3.0? #2, Configuring Persistence Providers for Workflow Runtime and Management #11

• guides/persistence/ef-migrations.md (661 lines) - Complete EF Core migrations guide

  • ✅ Elsa's DbContext architecture explained (ManagementElsaDbContext, RuntimeElsaDbContext)
  • ✅ Adding custom entities with full code examples
  • ✅ Migration commands reference (dotnet ef)
  • ✅ Three migration strategies (single DB, separate DBs, split management/runtime)
  • ✅ Version upgrade guidance and rollback procedures
  • ✅ Troubleshooting section
  • Addresses: Issue Generating Custom EF Core Migrations #74, references elsa-core #6355

Navigation & Cross-linking:

• Updated SUMMARY.md with new guide links
• Enhanced guides/persistence/README.md with links to new guides
• Added cross-references in getting-started/database-configuration.md
• Added "See Also" section in persistent-database.md
• Added persistence links in docker-quickstart.md

Quality Validation:

• All code snippets validated against Elsa v3 APIs
• Markdown style consistent with existing documentation
• All internal links verified to exist
• Code review feedback addressed
• Security issues resolved (TrustServerCertificate → Encrypt, missing using directives)

Issues Addressed:

• ✅ [DOC] How to use SQLServer instead of SqlLite in Els3.0? #2 (SQL Server instead of SQLite)
• ✅ Configuring Persistence Providers for Workflow Runtime and Management #11 (configuring persistence providers)
• ✅ Generating Custom EF Core Migrations #74 (custom EF Core migrations)
• ✅ elsa-core #6355 (EF migrations documentation)

This pull request was created as a result of the following prompt from Copilot chat.

Implement "PR 3" from our prior planning for elsa-workflows/elsa-gitbook.

Goal: Introduce a clear, user-focused persistence documentation set covering supported providers (SQL Server, PostgreSQL, MongoDB, etc.) and how to configure EF Core migrations for Elsa. This should directly address:

• Configuring Persistence Providers for Workflow Runtime and Management #11 (configuring persistence providers for Workflow Runtime and Management)
• [DOC] How to use SQLServer instead of SqlLite in Els3.0? #2 (using SQL Server instead of SQLite in Elsa 3.0)
• Generating Custom EF Core Migrations #74 (generating custom EF Core migrations)
• and partially tie into Significant Onboarding Gaps #6 and k8s deployment issue #75 (by setting a clear foundation for persistence docs).

Repository: elsa-workflows/elsa-gitbook
Base branch: main

Requirements:

1. Add a persistence providers overview

   • New file: guides/persistence/README.md.
   • Content:
     • Explain what Elsa persists (workflow definitions, workflow instances, bookmarks, logs/metadata) in general terms.
     • List the supported persistence providers at a high level (based on elsa-core and elsa-extensions):
       • EF Core with relational databases (SQL Server, PostgreSQL, etc.).
       • MongoDB, if supported for v3 (verify in elsa-core/elsa-extensions).
       • Any other major providers that are clearly available.
     • Describe how Workflow Runtime and Workflow Management modules each use persistence and that they must be configured consistently.
     • Provide links (within this guide) to provider-specific sub-guides (e.g., sql-server.md, postgresql.md, mongo.md) and the EF migrations guide.

2. Add a SQL Server-specific guide (explicitly addressing [DOC] How to use SQLServer instead of SqlLite in Els3.0? #2)

   • New file: guides/persistence/sql-server.md.
   • Content:
     • Requirements:
       • Which NuGet packages are needed (e.g., Microsoft.EntityFrameworkCore.SqlServer).
       • Which Elsa modules rely on EF Core (runtime & management) and need config.
     • Concrete configuration example:
       • Show a Program.cs snippet using the current Elsa v3 API to switch from SQLite to SQL Server, including both Workflow Runtime and Workflow Management modules.
       • Example should use UseEntityFrameworkCore and UseSqlServer (or equivalent) in the right places.
       • Pull exact method names and patterns from the current elsa-core repo (e.g., from the main server sample and/or module extensions).
     • Clarify how connection strings are typically provided (e.g., configuration.GetConnectionString("Elsa")).
     • Briefly note migration behavior: that Elsa ships with default EF migrations, but that users can also add custom migrations (and link to the EF migrations guide from requirement 3).

3. Add an EF Core migrations guide (addresses Generating Custom EF Core Migrations #74)

   • New file: guides/persistence/ef-migrations.md.
   • Content:
     • Explain how Elsa uses EF Core migrations by default (what tables it creates, at a high level; no full schema needed).
     • Show how to:
       • Reference Elsa's DbContexts from a host project (identify the context types from elsa-core and show how to point dotnet ef at them).
       • Add your own entities into the same database and generate combined migrations.
       • Run dotnet ef migrations add and dotnet ef database update against the host project.
     • Discuss strategies:
       • Single database shared with app vs dedicated Elsa persistence database.
       • Keeping Elsa migrations separate from custom migrations (e.g., separate contexts/projects) if desired.
     • Include concrete commands and a minimal csproj/Program.cs example that will work with the current Elsa 3.x setup in elsa-core.
     • Reference elsa-core issue 6355 in a short "For maintainers" note so the history is visible.

4. Wire these guides into navigation

   • Update SUMMARY.md to add a new "Persistence" section under an appropriate place (e.g., after Core Concepts or Setup/Guides):
     • Link to:
       • guides/persistence/README.md (e.g., "Persistence Providers")
       • guides/persistence/sql-server.md (e.g., "SQL Server")
       • guides/persistence/ef-migrations.md (e.g., "EF Core migrations")
   • Ensure the section title and ordering are consistent with the existing structure.

5. Cross-link from related pages

   • On any existing getting-started or storage/setup page that currently mentions SQLite or persistence in passing (for example, the basic server setup guide), add a short "See also" link pointing to the persistence overview (guides/persistence/README.md).
   • If the quick SQL Server pointer added in PR 1 exists (e.g., a small subsection in a setup doc), refactor it to:
     • Either delegate to guides/persistence/sql-server.md to avoid duplication, or
     • Be consistent with the new guide (same API names and snippet style).

6. Consistency and scope

   • Match the existing Markdown style in elsa-gitbook (headings, admonitions, code fences, etc.).
   • Do not attempt to fully solve k8s deployment or onboarding gaps here; limit this PR to persistence configuration and migrations.
   • Validate all code snippets against the latest elsa-core APIs (especially the AddElsa configuration for runtime and management modules).

Deliverables:

• A new branch off main (e.g., docs/add-persistence-guides).
• New files:
  • guides/persistence/README.md
  • guides/persistence/sql-server.md
  • guides/persistence/ef-migrations.md
• Updates to:
  • SUMMARY.md
  • Any existing setup/storage page where a "See also" link to persistence is helpful.
• A pull request back to main with a description summarizing:
  • The new persistence overview, SQL Server guide, and EF migrations guide.
  • Which issues are addressed (Configuring Persistence Providers for Workflow Runtime and Management #11, [DOC] How to use SQLServer instead of SqlLite in Els3.0? #2, Generating Custom EF Core Migrations #74) and how.
  • Any cross-links or refactors performed.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.