NLQueries GitHub

Blog  / 

Build vs. Adopt an NL2SQL Engine: Engineering Cost, Maintenance, and Licensing

Published . Written for nlqueries-core 0.4.

build-vs-adopt licensing cost

The prototype took an afternoon. A small backend team wired up a prompt that sends the database schema and a user's question to a model, then runs whatever SQL comes back. Someone asked, "For tenant A, what were paid-order revenue and paid-order count in October 2026?" and the right numbers came back. Now the team lead has to budget a production quarter, and the obvious question is whether to keep growing that wrapper or adopt a packaged natural-language-to-SQL (NL2SQL) engine.

Here's the short answer: you can't compare the two until both plans meet the same definition of "production." Once they do, the decision usually depends less on the first working query and more on who owns authorization, regression testing, upgrades and licensing for the next two years. This post walks through how to estimate that honestly, using NLQueries Core 0.4.1 (commit 2fbf276) as the "adopt" example and general frameworks like LangChain and LlamaIndex as the reference for a serious "build." It's a documentary review of documentation and source at pinned commits. The worksheet arithmetic and the fixture's reference answer below were checked, but nothing here measures any team's engineering hours, so you won't find a savings figure, only a way to calculate your own.

The demo is the cheap part

A prompt wrapper reaches a first demo quickly because it leaves out almost everything that makes the demo safe to keep running. It doesn't notice when a column gets renamed. It doesn't know which user is asking or which rows they're allowed to see. It has no plan for a provider timeout, a malformed statement or a dialect that handles dates differently. None of that shows up in a demo, and all of it shows up in production.

So before anyone estimates hours, write a shared acceptance contract that both plans have to satisfy. It should state the result requirements (correct answers on a fixed set of gold questions), the authorization requirements (who can see what, enforced where), the reliability requirements (what happens on failure and how it's reported) and the support requirements (who gets paged, and what they can see when they look). The rule that matters most is that a build estimate and an adopt estimate are only comparable when both meet that same contract. A hardened engine compared with a bare prompt wrapper will always look expensive. That's not a finding, it's a mismatched comparison.

It also helps to be fair about what "build" means. Building doesn't have to start from nothing. LangChain's SQL agent guide covers schema tools, a model-based query checker, retries, human-in-the-loop review and guidance on database permissions. LlamaIndex's text-to-SQL guide supports both fixed-table and retrieved-schema workflows through SQLDatabase and NLSQLTableQueryEngine. Neither guide claims to cover every production requirement, and both need explicit runtime configuration. But a realistic "build" lane assembles framework pieces like these instead of writing every line from scratch, and your estimate should reflect that.

Being fair cuts both ways, though. The LangChain guide is candid that its database tools are minimal wrappers for demonstration, not intended to be secure or used in production, and it tells you to scope database permissions narrowly and add application-specific validation before executing model-generated SQL. Its query checker is a model reviewing a model's output: useful advice, not enforcement. A build lane that meets the same contract as an adopted engine still has to budget for a deterministic statement policy the application owns.

Who owns each piece of the pipeline

The most useful artifact in this whole exercise is a work breakdown that names an owner for every component. For each one, you mark whether it's supplied by what you adopt, configured by you, or custom code you write and maintain. Here's how that looks for the three lanes worth considering: a full build, adopting Core, and a hybrid where you adopt the generation, policy and execution components while keeping your own authorization and user experience.

Component Build (framework-assisted) Adopt NLQueries Core Hybrid
Schema context and knowledge base Custom, on framework primitives Supplied, then configured (architecture) Supplied, then configured
Model calls and orchestration Custom or framework agent Supplied (sync_runner) Supplied
Generated-SQL policy checks Application-owned deterministic statement policy, plus database least privilege; an optional model checker is advisory Supplied (sql_policy.py) Supplied
Database permissions Yours Yours Yours
Application identity, per-user access Custom Custom Custom
Audit, telemetry, retention Custom Configured, retention operated by you (observability) Configured
Connectors and drivers Configure supplied framework/SQLAlchemy drivers; custom only for missing integrations Configured, per engine (connectors) Configured
UI, approval and routing flows Custom Custom Custom

The top half of that table is where adopting changes the picture. The NLQueries architecture document describes a request flow that routes between SQL and document answers and partitions cached context by agent. The Python entry points in sync_runner (run_query and run_query_sync) take an explicit execution parameter and return a structured AgentQueryResult rather than bare rows. The policy module makes accept-or-reject decisions and runs dialect and function checks on generated statements. That description comes from reading the source, not from attacking it, so treat the module as an inspected component rather than a proven boundary. These are the pieces a prompt wrapper usually doesn't have, so they're where the build lane's hours pile up.

Two rows are easy to fill in unfairly. The policy row asks the same thing of every lane: a deterministic check on each generated statement, backed by least-privilege database access. In the build lane the application owns that check; in the other two it's supplied, but the permissions underneath are still yours. Let a model-based checker stand in for the deterministic part and the columns stop describing the same control. The connectors row can skew the other way. LlamaIndex describes its SQLDatabase as a light wrapper around SQLAlchemy, so reaching a database that an existing driver already supports is configuration, not new code. Count custom connector work in the build lane only where an integration is genuinely missing.

The bottom half barely changes, and that's the part teams tend to underestimate. Core's own database hardening guide treats SQL policy and database permissions as separate safeguards, notes that what the connector can enforce depends on the engine, and recommends least-privilege access. In other words, adopting an engine doesn't hand you per-user data access. Your application identity, row-level permissions, durable operations and screens stay deployment-specific work in every lane. Some of that might come from an Enterprise edition under contract, but that's a different product with different terms, so price it separately rather than assuming Core covers it.

The observability docs make a similar distinction. Configuring execution audit events and per-answer provenance is not the same as operating a retained audit trail, and exporting OpenTelemetry data is not the same as someone watching it. Adoption gives you hooks; running them is still your job.

Putting numbers on it without inventing them

Once the breakdown is agreed, the cost model itself is simple. Over a horizon of H months:

cost = (initial hours × rate) + (recurring hours per month × H × rate) + license or support fees

Keep hosting costs out of this formula. They matter, but they behave differently and they'll muddy the engineering comparison. The hard part isn't the arithmetic; it's that every input is uncertain. So don't estimate single numbers. Give each work item a low, base and high figure, record where each number came from, and look at which assumptions move the answer most.

Here's a small worksheet in plain Python that does that. It isn't part of any NLQueries or framework API, just a helper you'd keep next to your estimate. The hours and rate in it are placeholders to show the mechanics, not estimates for any real team.

# effort_model.py — custom worksheet helper (Python 3.11, standard library only).
# All numbers below are PLACEHOLDERS. Replace them with your team's sourced estimates.
from dataclasses import dataclass

@dataclass
class Lane:
    name: str
    initial_hours: tuple[float, float, float]           # (low, base, high)
    recurring_hours_per_month: tuple[float, float, float]
    monthly_fees: float | None                          # None = rights/terms UNKNOWN

def lane_cost(lane: Lane, rate: float, months: int) -> dict[str, float] | str:
    if lane.monthly_fees is None:
        # Unknown rights are a gate, not a zero fee.
        return "BLOCKED: license or commercial terms unresolved"
    out = {}
    for label, i, r in zip(("low", "base", "high"),
                           lane.initial_hours, lane.recurring_hours_per_month):
        out[label] = i * rate + r * months * rate + lane.monthly_fees * months
    return out

RATE, MONTHS = 100.0, 24  # placeholder rate and horizon
lanes = [
    Lane("build",  (400, 600, 900), (30, 45, 70), 0.0),
    Lane("adopt",  (200, 300, 500), (20, 30, 50), None),  # terms not yet confirmed
    Lane("hybrid", (250, 380, 600), (25, 35, 55), None),
]
for lane in lanes:
    print(lane.name, lane_cost(lane, RATE, MONTHS))

Run with those placeholder inputs on Python 3.12.9, it prints the following (illustrative output from placeholder data, not a finding):

build {'low': 112000.0, 'base': 168000.0, 'high': 258000.0}
adopt BLOCKED: license or commercial terms unresolved
hybrid BLOCKED: license or commercial terms unresolved

Three design choices in that helper matter more than the code. First, an unknown license position returns a block instead of a number. Typing zero for fees you haven't confirmed is exactly how an adoption plan ends up looking cheaper than it is. That's also why hybrid is blocked: it runs the same Core generation, policy and execution components as adopt, so it inherits the same open rights question, even if the team expects to pay nothing. Confirm rights independently for every lane. A known fee, including zero, is not authorization.

Second, the helper folds that gate into the fee field to stay short, with None meaning "terms unknown." Your actual estimate should keep rights and fees as separate inputs. For each lane, write down which deployment rights it needs, who confirmed them and for which product design, and only then what it costs. The build lane's 0.0 is a placeholder fee, not a rights confirmation, and its components get the same check. A worksheet that prices only one lane isn't broken; it's telling you the comparison can't be made yet.

Third, recurring hours are multiplied by the horizon, which is why a 6-month and a 36-month view of the same plan can point in opposite directions. Run both.

On the one-time side, list everything in the acceptance contract: schema context setup, model integration, policy rules, executor and error handling, monitoring, gold tests and UI. On the recurring side, list what keeps happening: dependency updates, connector and driver changes, model or provider changes, policy maintenance and incident response. NLQueries documents dependency locking and an update process. The lock improves reproducibility for the base and development dependencies on its target platform; other extras, your own wrappers and provider behaviour need separate pins, and someone still has to refresh the locks, so the line item belongs in the adopt lane too. Its connectors page describes a generic SQLAlchemy path plus specific engines, and driver, history and dialect support each need checking for your database. Neither lane gets out of maintenance. The real question is which one gives you less of it.

Rehearse the changes that cause surprises

Recurring hours are the softest numbers in the model, and they're where most of the cost sits over a long horizon. The best way to firm them up is to actually rehearse a few changes rather than guess.

Start with a fixture small enough to reason about by hand. This one has two tenants, a cancelled order, a November order just outside the window, a paid order with a NULL amount, and an order with two line items that will double-count revenue if a query joins carelessly. It's synthetic sample data.

CREATE TABLE customers(id INTEGER PRIMARY KEY, tenant_id TEXT NOT NULL, region TEXT);
CREATE TABLE orders(id INTEGER PRIMARY KEY, customer_id INTEGER REFERENCES customers(id),
                    order_date TEXT, amount_cents INTEGER, status TEXT);
CREATE TABLE order_items(id INTEGER PRIMARY KEY, order_id INTEGER REFERENCES orders(id), sku TEXT);
INSERT INTO customers VALUES(1,'A','East'),(2,'A','West'),(3,'B','North');
INSERT INTO orders VALUES
(101,1,'2026-10-01',10000,'PAID'),(102,1,'2026-10-02',5000,'CANCELLED'),
(103,2,'2026-10-31',20000,'PAID'),(104,3,'2026-10-02',70000,'PAID'),
(105,1,'2026-11-01',40000,'PAID'),(106,2,'2026-10-15',NULL,'PAID');
INSERT INTO order_items VALUES(1,101,'a'),(2,101,'b'),(3,103,'c');

-- Reference answer for: tenant A, paid revenue and paid-order count, October 2026
SELECT SUM(o.amount_cents) AS revenue_cents, COUNT(*) AS paid_order_count
FROM orders AS o JOIN customers AS c ON c.id = o.customer_id
WHERE c.tenant_id = 'A' AND o.status = 'PAID'
  AND o.order_date >= '2026-10-01' AND o.order_date < '2026-11-01';

On SQLite 3.45.3 the reference query returns (30000, 3): the NULL amount is ignored by SUM but the order still counts. That check covers the fixture and the expected answer only. It says nothing about any NL2SQL product, and the tenant_id = 'A' predicate is answer math, not an authorization boundary. Real tenant isolation has to be enforced somewhere the model can't talk its way around, such as database roles.

With the fixture in place, run three changes separately against both the prototype and the adopted pipeline: rename a column, rotate a database credential, and upgrade one pinned dependency. After each, rerun the gold question, its variants (a missing date range, a column that doesn't exist, a table the user shouldn't see) and the expected denials, and write down how long it took to get back to green and what broke. When you compare results, compare row sets rather than SQL strings, and keep NULL, duplicate and integer-currency semantics intact.

Be careful with what you conclude. One rehearsal gives you an observed maintenance sample for your team and your schema. That's far better than a guess, but it isn't evidence that one approach is cheaper in general. Also keep the measures apart. Whether a statement parses, whether the policy accepts it, whether the answer is right and whether the refusal is useful are four different results. A statement that passes syntax and policy checks can still be the wrong answer, or one the user shouldn't be able to see.

Read the license before you count the savings

This is the step that can remove the adopt lane entirely, and the hybrid lane with it, so do it early rather than after the estimates are done.

NLQueries Core 0.4.1 is source-available under the Business Source License 1.1. The license lets you copy, modify, redistribute and make non-production use of the code. Its Additional Use Grant permits production use, provided that use doesn't include offering Core to third parties on a hosted or managed basis, where a third party remotely accesses its functionality as a service. The license also includes a Change Date: for this release it's June 4, 2030, or the fourth anniversary of the version's first public distribution under the license if that comes first, after which the code converts to the Apache License 2.0. The date applies per version and can differ between releases. That makes Core source-available, not Open Source before the applicable conversion. Being able to see the source doesn't give you the right to host it for others.

For the backend team in the running example, the deciding question is who the users are. If the assistant serves the company's own staff, the restriction may never come up. If the plan is to put database questions in front of paying customers, then whether that product design falls inside the grant is a question for your counsel or a commercial agreement, not for a blog post. The license itself says that a use which doesn't comply needs a commercial license from the licensor. Until that's answered, the adopt and hybrid lanes are blocked in the worksheet, not discounted. The future Apache conversion is real, but it doesn't change what applies today.

Exit costs belong in the same conversation. Whatever you adopt, keep the parts that would let you leave: your gold questions and expected answers, your schema descriptions and business definitions, and your denial tests. Those are valuable in either lane, and they turn a future migration from a rewrite into a re-run of a test suite you already trust.

Making the call

You won't get a universal verdict out of this, and anyone who gives you one hasn't seen your requirements. What you can produce is a defensible range for each lane, plus the two assumptions that move the answer most. In practice those are usually the recurring hours for connector and dependency upkeep, and the time horizon. If a plausible change to either one flips the ranking, say so in the proposal instead of hiding it in a single number.

A few things would change the answer outright. If your approval or routing requirements are unusual, the hybrid lane, where you adopt generation, policy and execution and build identity and UX around them, often matches the work breakdown best, but it has to clear the same licensing gate as adopt before it gets a price. If you're customer-facing and the license grant doesn't clearly cover you, building on a framework may be the only lane you can price today, once its own components' terms are confirmed. And if the prototype already meets most of the acceptance contract, which is rare but possible, the build lane's initial hours shrink.

For a concrete next step, take your current prototype and fill in the ownership table above with your team. Mark every row supplied, configured or custom, attach a low/base/high estimate with its source, and add a separate rights entry for each lane. Then pick the single change you're most worried about and rehearse it on the fixture this week. The hours that rehearsal actually takes will tell you more than any estimate in this post.

References

  1. NLQueries, "Architecture," Core 0.4.1, commit 2fbf276. https://github.com/nlqueries/nlqueries/blob/2fbf276bf299e0b019c41cb62c5e6969d4c33ff9/docs/architecture.md
  2. NLQueries, nlqueries/orchestrator/sync_runner.py, Core 0.4.1. https://github.com/nlqueries/nlqueries/blob/2fbf276bf299e0b019c41cb62c5e6969d4c33ff9/nlqueries/orchestrator/sync_runner.py
  3. NLQueries, nlqueries/sql_policy.py, Core 0.4.1. https://github.com/nlqueries/nlqueries/blob/2fbf276bf299e0b019c41cb62c5e6969d4c33ff9/nlqueries/sql_policy.py
  4. LangChain, "Build a SQL agent." https://docs.langchain.com/oss/python/langchain/sql-agent
  5. LlamaIndex, "Text-to-SQL Guide (Query Engine + Retriever)." https://developers.llamaindex.ai/python/examples/index_structs/struct_indices/sqlindexdemo/
  6. NLQueries, "Hardening the database NLQueries reads," Core 0.4.1. https://github.com/nlqueries/nlqueries/blob/2fbf276bf299e0b019c41cb62c5e6969d4c33ff9/docs/database-hardening.md
  7. NLQueries, "Observability," Core 0.4.1. https://github.com/nlqueries/nlqueries/blob/2fbf276bf299e0b019c41cb62c5e6969d4c33ff9/docs/observability.md
  8. NLQueries, "Dependency locking (SEC-11)," Core 0.4.1. https://github.com/nlqueries/nlqueries/blob/2fbf276bf299e0b019c41cb62c5e6969d4c33ff9/docs/dependency-locking.md
  9. NLQueries, "Connectors," Core 0.4.1. https://github.com/nlqueries/nlqueries/blob/2fbf276bf299e0b019c41cb62c5e6969d4c33ff9/docs/connectors.md
  10. NLQueries Core, Business Source License 1.1. https://github.com/nlqueries/nlqueries/blob/2fbf276bf299e0b019c41cb62c5e6969d4c33ff9/LICENSE
  11. NLQueries Documentation (version banner v0.4.1, docs 2fbf276, 2026-11-02). https://nlqueries.com/docs/

All posts · RSS feed · Documentation