DEV Community: Nicolas Florez

Migrating a Single-Tenant SaaS to Multi-Tenant Workspaces with EF Core Global Query Filters

Nicolas Florez — Tue, 05 May 2026 18:18:37 +0000

TL;DR

We had a single-tenant Angular + .NET 10 SaaS where every row was scoped by UserId. To support firms (multiple lawyers sharing data), we needed multi-tenant workspaces — but rewriting every query was off the table.

EF Core's HasQueryFilter made it possible to flip 9 tables to multi-tenant in a single weekend, with zero query call sites changed. Here's the pattern.

Context

I'm building NeoJurídico, a court-process monitoring platform for Colombian lawyers. Plan Bufete users need to share monitored processes, alerts, and notifications across their team.

Originally, every tenanted entity had int UserId as the implicit tenant. Service code looked like:

var processes = await _db.ProcessSubscriptions
    .Where(p => p.UserId == userId)
    .ToListAsync();

If we kept this pattern but added WorkspaceId next to it, every controller had to be touched. That's 60+ files. No.

The plan

Add int WorkspaceId to every tenanted entity (9 tables).
Mark them with ITenantedEntity interface.
Use HasQueryFilter so EF auto-injects WHERE WorkspaceId = @currentWs on every read.
Service code stays the same — p => p.UserId == userId — but now scoped automatically by workspace.
Backfill workspace ID on every existing row before flipping the column to NOT NULL (atomic migration).

The interface

namespace NEO.Domain.Workspaces;

public interface ITenantedEntity
{
    int WorkspaceId { get; set; }
}

Implemented by 9 entities: ProcessSubscription, NameMonitoring, Notification, Message, DisciplinaryRecord, UserProcess, JuridicProcess, MonitoringProcessMatch, Workspace itself excluded.

(Notably, ProcessReport — anonymous AI-generated reports paid by visitors with no account — is NOT tenanted. It lives against an email, not a user. We almost broke this by tagging it as ITenantedEntity in the migration. Caught it when the NOT NULL alter failed.)

The query filter

In NeoDbContext.OnModelCreating:

modelBuilder.Entity<ProcessSubscription>()
    .HasQueryFilter(p => p.WorkspaceId == _workspaceContext.CurrentWorkspaceIdOrNull());

Where IWorkspaceContext has two implementations:

// HTTP requests: get from JWT claim
public class HttpWorkspaceContext : IWorkspaceContext {
    private readonly IHttpContextAccessor _http;
    public int? CurrentWorkspaceIdOrNull() {
        var claim = _http.HttpContext?.User
            .FindFirst("active_workspace_id")?.Value;
        return int.TryParse(claim, out var id) ? id : null;
    }
}

// Background workers: explicit context, no http
public class BackgroundWorkspaceContext : IWorkspaceContext {
    private int? _workspaceId;
    public int? CurrentWorkspaceIdOrNull() => _workspaceId;
    public IDisposable EnterScope(int workspaceId) { ... }
}

The filter runs on every query EF Core generates. No service code changed.

The atomic migration

This is the part that scared me. We needed to:

Backfill WorkspaceId on existing rows (every user gets a "Personal" workspace; their data assigned to it)
Add NOT NULL constraint
Fail rollback on any error

Single migration, single transaction:

public partial class BackfillAndRequireWorkspaceId : Migration {
    protected override void Up(MigrationBuilder mb) {
        // Step 1: create personal workspace per user
        mb.Sql(@"
            INSERT INTO neo.workspaces (Name, OwnerUserId, Type, ...)
            SELECT COALESCE(NULLIF(TRIM(CONCAT(FirstName,' ',LastName)),''), 'Personal'),
                   Id, 'Personal', ...
            FROM neo.users u
            WHERE NOT EXISTS (
              SELECT 1 FROM neo.workspaces w
              WHERE w.OwnerUserId = u.Id AND w.Type = 'Personal'
            );
        ");

        // Step 2: insert Owner row in workspace_members
        mb.Sql(@"
            INSERT INTO neo.workspace_members (...)
            SELECT w.Id, w.OwnerUserId, 'Owner', 'Active', ...
            FROM neo.workspaces w
            WHERE w.Type = 'Personal'
              AND NOT EXISTS (...);
        ");

        // Step 3: backfill WorkspaceId in 9 tenanted tables
        mb.Sql(@"
            UPDATE neo.process_subscriptions t
            SET WorkspaceId = w.Id
            FROM neo.workspaces w
            WHERE w.OwnerUserId = t.UserId AND w.Type = 'Personal';
        ");
        // ... repeat for 8 more tables

        // Step 4: ALTER NOT NULL — runs in same transaction
        mb.AlterColumn<int>(name: "WorkspaceId", nullable: false, ...);
        // ... repeat for 8 more tables
    }
}

The key is keeping data backfill + NOT NULL alter in a single migration. If any step fails, the entire transaction rolls back. We won't end up with half-migrated tables.

Tested on QAS first. The migration ran in 2.3 seconds against ~5000 production rows.

The trap I almost fell into

HasQueryFilter with a captured DbContext field can throw a NullReferenceException in tests if the context isn't fully initialized:

// Don't do this:
.HasQueryFilter(p => p.WorkspaceId == _workspaceContext.CurrentWorkspaceId)
//                                                       ^^^ throws if null

// Do this instead:
.HasQueryFilter(p => p.WorkspaceId == _workspaceContext.CurrentWorkspaceIdOrNull())
//                                                       ^^^ returns int? — EF generates NULL-safe SQL

Returning nullable from the helper method makes EF generate IS NULL checks instead of crashing.

JWT claim for active workspace

The JWT now includes active_workspace_id. When a user switches workspace via the workspace switcher UI, the backend issues a fresh token:

[HttpPost("switch")]
public async Task<IActionResult> Switch(int workspaceId) {
    // Validate user is member with Active status
    var membership = await _db.WorkspaceMembers
        .FirstOrDefaultAsync(m => m.UserId == userId
                                && m.WorkspaceId == workspaceId
                                && m.Status == "Active");
    if (membership == null) return NotFound();

    // Issue new tokens with active_workspace_id claim
    return Ok(await _tokenService.IssueTokensAsync(userId, workspaceId));
}

Frontend stores the new token, all subsequent requests carry the new workspace context, EF query filter does the rest.

Plan-based feature gating

Plan Bufete unlocks multi-user. When user upgrades/downgrades, a MembershipReconciler runs:

Plan upgrade to Bufete: existing dormant members → Active
Plan downgrade from Bufete: members beyond MaxUsers → Dormant (data preserved)
All transitions emit emails so the firm owner is informed

public async Task ReconcileAsync(int userId, int newPlanId) {
    var newPlan = await _db.SubscriptionPlans
        .FirstAsync(p => p.Id == newPlanId);
    if (!newPlan.MultiUser) {
        // Downgrade: deactivate excess members
        var members = await _db.WorkspaceMembers
            .Where(m => m.WorkspaceId == ownedWsId && m.Status == "Active")
            .OrderByDescending(m => m.JoinedAt)
            .Skip(1) // keep owner
            .ToListAsync();
        foreach (var m in members) m.Status = "Dormant";
    } else {
        // Upgrade: re-activate dormant
        var dormant = await _db.WorkspaceMembers
            .Where(m => m.WorkspaceId == ownedWsId && m.Status == "Dormant")
            .Take(newPlan.MaxUsers - 1).ToListAsync();
        foreach (var m in dormant) m.Status = "Active";
    }
}

This gracefully handles the "you exceeded your seat limit" case without ever deleting member data.

Takeaways

EF Core HasQueryFilter is the cleanest path to retrofit multi-tenancy onto an existing single-tenant schema. Zero service-code touches.
One migration, one transaction: backfill + NOT NULL alter together. Half-migrated state is the worst state.
Make ITenantedEntity opt-in by interface, not "every entity." We caught ProcessReport (anonymous payments) only because we had to explicitly add it.
Cache invalidation on workspace switch matters. Token issuance + frontend WorkspaceContextService → BehaviorSubject → re-fetch dashboard. Don't keep stale workspace data in app state.
JWT-claim-based context is testable, statelessly auditable, and survives horizontal scaling. No sticky sessions needed.

Migration shipped. 0 incidents. 0 query rewrites. Multi-tenant just worked.

I'm a solo founder building NeoJurídico for the Colombian legal market. If you're shipping multi-tenant features in EF Core or wrestling with audit + tenant isolation in .NET, happy to compare notes.

How a Free Trial Without Upfront Card Killed Our SaaS Conversion Rate

Nicolas Florez — Tue, 05 May 2026 18:17:17 +0000

TL;DR

We had 11 free-trial users on a paid Colombian legaltech plan over 30 days. Trial→paid conversion: 0%. Spoiler: it wasn't a PMF problem. It was a billing-architecture bug.

If your trial doesn't tokenize a card upfront, your cron job has nothing to charge when the trial ends. The user silently downgrades to free, and your "trial conversion rate" is mathematically impossible.

Here's how we found it, and the .NET 10 + EF Core fix.

Context

I'm building NeoJurídico, a court-process monitoring platform for Colombian lawyers. The Litigante plan ships with a 14-day free trial activated via UTM-tagged Google Ads campaigns. Tech stack: .NET 10, EF Core 10, PostgreSQL, MercadoPago for billing, Angular 21 on the frontend.

The 0% trial→paid mystery

We were spending real money on Ads and getting 11 trials/month. Zero ever converted. So we audited the funnel:

Step	Count
Ads → click	119/30d
Click → signup	8 (CTR 6.7%)
Signup → activated trial	11/30d (some pre-Ads)
First process created (Aha moment)	5/8 (62.5%)
Trial → paid	0

Activation looked healthy. Engagement existed. So why zero conversions?

Reading the SQL

SELECT us."Id", us."UserId", us."Status",
       us."MpPreapprovalId" IS NOT NULL AS has_card
FROM neo.user_subscriptions us
WHERE us."CampaignId" IS NOT NULL
ORDER BY us."CreatedAt" DESC LIMIT 11;

 Id  | UserId | Status | has_card
-----+--------+--------+----------
 146 |   3    | Open   | f
 145 |  44    | Open   | f
 144 |  43    | Open   | f
 ... (all 11 rows: has_card = f)

Zero of eleven trials had a payment method attached. That's the root cause.

Tracing the code

In our SubscriptionsService:

bool needsMpSubscription = isPaidPlan && !hasTrial && !hasCampaign;

If the user came in via campaign + trial, we skipped MercadoPago entirely. The trial activated as Status="Open" with TrialEndDate=now+15d, but with no preapproval ID.

Then the TrialExpirationHandler runs every 6 hours:

foreach (var userId in expiredCampaignSubscriptions) {
    await enrollmentService.RestoreOriginalSubscriptionIfNeededAsync(userId, ct);
}

"Restore" means "downgrade silently to the free plan." There's no path to charge — there was never a card.

We were running a free 15-day trial with structurally zero conversion potential.

The fix: card upfront, deferred first charge

MercadoPago's preapproval API supports start_date for deferring the first recurring charge:

// In SubscriptionsService.ActivateSubscriptionAsync
bool isTrialAwaitingCheckout = hasCampaign && hasTrial && isPaidPlan;
if (isTrialAwaitingCheckout) {
    status = "Pending";
    statusReason = "AwaitingTrialCheckout";
    trialEndDate = now.AddDays(trialDays!.Value);
}

Now signup creates a Pending subscription. The frontend (Angular) detects it on /app/dashboard and redirects:

if (response.entity.status === 'Pending'
    && response.entity.statusReason === 'AwaitingTrialCheckout') {
  this.router.navigate(['/app/suscripcion/checkout', planId],
                       { queryParams: { trial: 'true' } });
}

The user sees a checkout: "14 días gratis. No se cobra hoy. Primera carga: [date+14]." When they submit, we tokenize the card and create the MP preapproval with startDate = trialEndDate:

var preapprovalId = await _mpSubscriptionService.CreateAuthorizedSubscriptionAsync(
    plan.Name, plan.Price, user.Email, request.CardTokenId,
    backUrl, ct, externalReference: $"neo-sub-{sub.Id}",
    startDate: deferredStart  // = TrialEndDate
);

MP holds the card today, charges in 14 days. Trial→paid is now automatic instead of impossible.

For users who refuse to give a card, an explicit "skip to free plan (1 process limit)" button calls POST /skip-trial-to-free which closes the Pending and activates Plan Semilla. They self-segment.

The hidden lesson: zero conversions ≠ zero PMF

I almost made an expensive pivot decision based on the 0% number. The temptation was:

"Cut trials, force payments upfront on everyone"
"Limit free plan to 1 process to push conversion"
"Maybe the product isn't ready"

The data didn't support any of that. The bottleneck was a billing-flow architecture choice that made conversion mathematically impossible — not a value problem.

If you're seeing 0% on a critical funnel metric, before pivoting your business model, run this query against your billing data:

SELECT COUNT(*) FILTER (WHERE has_payment_method) AS chargeable,
       COUNT(*) AS total
FROM your_trial_subscriptions
WHERE created_at > NOW() - INTERVAL '30 days';

If chargeable / total is 0, you can't possibly convert anything. Fix that before changing anything else.

Server-side event tracking matters too

We also had GA4 emitting subscription_activated from the frontend card-checkout component. But trials never reached that component (no card flow). So GA4 showed 0 activations while our DB showed 11.

Solution: server-side GA4 via Measurement Protocol when status transitions to Open in the SubscriptionsService. Now event tracking matches reality regardless of which path the user takes.

if (_ga4 != null && s.Status == "Open" && hasCampaign && hasTrial) {
    var expectedValue = Math.Round(plan.Price * 0.36m, 0);
    await _ga4.TrackTrialStartedAsync(
        userId, plan.Name, expectedValue, "COP", trialDays.Value, ct);
}

(Using expected_value = MRR × 0.36 as the proxy for Smart Bidding. Trials aren't revenue — don't pass nominal price as conversion value or Google will optimize for trials, not paying customers.)

Takeaways

If trial lifecycle doesn't include "tokenize a payment method," you have zero ability to convert. No amount of UX or pricing changes fixes architecture.
Validate metric anomalies (0% conversion) by reading your DB schema, not by changing pricing.
Server-side analytics for revenue events is non-negotiable. Frontend gtag dies in 30% of sessions due to ad-blockers.
Self-segment users at the checkout: "card or downgrade to free." Don't force, don't trick — let them choose, then measure.

The plumbing is now in production. We'll see the trial→paid conversion rate on the next cohort. I'll write a follow-up in 30 days with real numbers.

I work on NeoJurídico, a court-process monitoring platform for Colombian lawyers. Always interested in connecting with other LATAM SaaS founders or LegalTech builders. Reach out if your country has equally cursed government APIs.