There is a version of a feature toggle that looks wonderfully simple in a pull request:
Then newThing turns out to be a data pipeline, a shipping promise, or a screen people have already started using. Now the switch has an owner, a scope, a failure mode, and a date when we ought to remove it. The if statement is the least interesting part.
I want to work through three concrete examples. The first moves a flat-file order feed through Databricks, then cuts a tenant over to normalized PostgreSQL behind a data API. The second turns on expedited shipping, with the same decision implemented in TypeScript and Go. The third releases a saved-filters interface in React and SwiftUI. Each is a different kind of switch, and each can surprise you if you treat it as a Boolean sprinkled through the codebase.
The examples are deliberately small enough to read, but the boundaries are real: immutable inputs, idempotency, tenant scoping, stable rollout decisions, and the difference between hiding a button and actually controlling a capability. Let’s get into it.
1. The order feed: Databricks today, PostgreSQL data API tomorrow
Imagine a partner dropping one immutable CSV file per batch into object storage. Each row is an item on an order:
The existing path loads the file into a Databricks Delta bronze table, then produces a current-order table for queries. The proposed path reads that same object, validates it, and sends a complete batch to a private data API. The API writes three normalized PostgreSQL tables: customers, orders, and order_items.
The switch is a tenant route, not a random choice made separately for each row. For a given batch, resolve the route once and put it in the batch log. Changing the route while a file is half processed would create an impressively confusing incident.
The route and the file contract
I keep the control-plane data separate from the pipeline code. In this example the configuration is a checked, versioned snapshot supplied to the worker; in production it might come from a flag service. The important bit is that the worker receives one decision and uses it for the whole operation.
The file key is a basename by design. The worker constructs the object path from a fixed bucket and tenant prefix. That keeps a caller from turning a batch submission into “please read whatever URL I hand you.” The SHA-256 is about replay identity: batch-42 with new bytes is an error, not a cute way to overwrite history.
The existing Databricks path
Here is the setup on the lakehouse side. The external location and warehouse already have access to the bucket. I’m showing Databricks SQL because COPY INTO is a good fit for an incremental feed of files, and the loaded-file tracking makes retries tractable. If your feed is millions of files, Databricks points you toward Auto Loader instead.
The TypeScript adapter submits a SQL statement to a warehouse and waits for completion. For this example every query returns either no rows or a small lookup result; large query results need the API’s external-links disposition and a separate paging design.
type StatementResult = {
statement_id?: string;
status: { state: string; error?: { message: string } };
result?: { data_array?: string[][] };
};
export class DatabricksSql {
constructor(
private readonly host: string,
private readonly token: string,
private readonly warehouseId: string,
) {}
private async request(path: string, init?: RequestInit): Promise<StatementResult> {
const response = await fetch(`${this.host}${path}`, {
...init,
headers: {
Authorization: `Bearer ${this.token}`,
"Content-Type": "application/json",
...init?.headers,
},
});
if (!response.ok) throw new Error(`Databricks HTTP ${response.status}`);
return response.json() as Promise<StatementResult>;
}
async execute(statement: string, parameters: { name: string; value: string }[] = []) {
let result = await this.request("/api/2.0/sql/statements", {
method: "POST",
body: JSON.stringify({
warehouse_id: this.warehouseId,
statement,
parameters,
wait_timeout: "10s",
disposition: "INLINE",
format: "JSON_ARRAY",
}),
});
const deadline = Date.now() + 120_000;
while (result.status.state === "PENDING" || result.status.state === "RUNNING") {
if (!result.statement_id || Date.now() > deadline) {
throw new Error("Databricks statement exceeded worker deadline");
}
await new Promise(resolve => setTimeout(resolve, 1_000));
result = await this.request(`/api/2.0/sql/statements/${result.statement_id}`);
}
if (result.status.state !== "SUCCEEDED") {
throw new Error(result.status.error?.message ?? `Statement ${result.status.state}`);
}
return result.result?.data_array ?? [];
}
}
export async function loadDatabricksBatch(
sql: DatabricksSql,
batch: BatchRef,
): Promise<void> {
checkBatchRef(batch);
const prefix = `s3://example-order-feed/${batch.tenantId}/`;
await sql.execute(`
COPY INTO main.orders.order_rows_bronze
FROM '${prefix}'
FILEFORMAT = CSV
FILES = ('${batch.fileName}')
FORMAT_OPTIONS ('header' = 'true')
`);
await sql.execute(`
MERGE INTO main.orders.order_rows_current AS target
USING (
SELECT order_id, customer_id, customer_name, sku,
CAST(quantity AS INT) AS quantity,
CAST(event_at AS TIMESTAMP) AS event_at
FROM main.orders.order_rows_bronze
QUALIFY ROW_NUMBER() OVER (
PARTITION BY order_id, sku ORDER BY CAST(event_at AS TIMESTAMP) DESC
) = 1
) AS source
ON target.order_id = source.order_id AND target.sku = source.sku
WHEN MATCHED AND source.event_at >= target.event_at THEN UPDATE SET
customer_id = source.customer_id,
customer_name = source.customer_name,
quantity = source.quantity,
event_at = source.event_at
WHEN NOT MATCHED THEN INSERT
(order_id, customer_id, customer_name, sku, quantity, event_at)
VALUES (source.order_id, source.customer_id, source.customer_name,
source.sku, source.quantity, source.event_at)
`);
}
There is a deliberate simplification here: the merge scans bronze and models upserts, not item deletion. If a later snapshot can remove an item, the source contract needs tombstones or a replace-whole-order operation. No toggle solves an undefined deletion contract. Also, in a real lakehouse I would key these tables by tenant, or put each tenant in its own governed schema; the sample’s order_id must be globally unique for the shown merge.
The PostgreSQL path and its data API
On the new path, the database is an implementation detail of the data API. The worker never gets a PostgreSQL connection string. A private, authenticated service receives a complete batch; the service owns validation, idempotency, and the transaction.
The flat file repeats customer names and order IDs. The relational model stores each customer and order once, then each item under that order. This normalization is useful for operational queries and constraints; it is not a claim that PostgreSQL is automatically the better analytics engine. The switch is about the workload we actually need to serve.
The worker downloads the immutable object and parses it. This uses @aws-sdk/client-s3 and csv-parse/sync. I cap the file at 10,000 rows here so the data API can handle one transaction; larger feeds should use bounded chunks with a manifest and a stronger commit protocol.
The API side is where the transaction belongs. zod checks the wire shape; PostgreSQL constraints still carry the final integrity guarantee. The gateway authenticates the service token and supplies the tenant identity; it must verify that the tenant in the request body matches that identity. I’m leaving gateway wiring out of this excerpt, but I would not expose this route to the public internet as an unauthenticated import endpoint.
import Fastify from "fastify";
import pg from "pg";
import { z } from "zod";
const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
const app = Fastify();
const rowSchema = z.object({
order_id: z.string().min(1).max(100),
customer_id: z.string().min(1).max(100),
customer_name: z.string().min(1).max(200),
sku: z.string().min(1).max(100),
quantity: z.number().int().positive(),
event_at: z.string().datetime({ offset: true }),
});
const batchSchema = z.object({
tenantId: z.string().regex(/^[a-z0-9-]{1,64}$/),
batchId: z.string().min(1).max(100),
fileName: z.string().endsWith(".csv"),
sha256: z.string().regex(/^[a-f0-9]{64}$/),
rows: z.array(rowSchema).min(1).max(10_000),
});
app.post("/v1/batches", async (request, reply) => {
const parsed = batchSchema.safeParse(request.body);
if (!parsed.success) {
return reply.code(400).send({ error: "Invalid batch payload" });
}
const input = parsed.data;
const byOrder = new Map<string, typeof input.rows>();
for (const row of input.rows) {
const group = byOrder.get(row.order_id) ?? [];
group.push(row);
byOrder.set(row.order_id, group);
}
for (const rows of byOrder.values()) {
const first = rows[0];
const skus = new Set<string>();
for (const row of rows) {
if (row.customer_id !== first.customer_id ||
row.customer_name !== first.customer_name ||
row.event_at !== first.event_at || skus.has(row.sku)) {
return reply.code(400).send({ error: "Inconsistent order snapshot" });
}
skus.add(row.sku);
}
}
const client = await pool.connect();
try {
await client.query("BEGIN");
const inserted = await client.query(
`INSERT INTO ingestion_batches (tenant_id, batch_id, sha256)
VALUES ($1, $2, $3) ON CONFLICT DO NOTHING RETURNING batch_id`,
[input.tenantId, input.batchId, input.sha256],
);
if (inserted.rowCount === 0) {
const existing = await client.query(
`SELECT sha256 FROM ingestion_batches
WHERE tenant_id = $1 AND batch_id = $2`,
[input.tenantId, input.batchId],
);
await client.query("COMMIT");
if (existing.rows[0]?.sha256 !== input.sha256) {
return reply.code(409).send({ error: "Batch ID reused with new bytes" });
}
return reply.send({ status: "already-committed" });
}
for (const [orderId, rows] of byOrder) {
const first = rows[0];
await client.query(
`INSERT INTO customers (tenant_id, customer_id, customer_name)
VALUES ($1, $2, $3)
ON CONFLICT (tenant_id, customer_id)
DO UPDATE SET customer_name = EXCLUDED.customer_name`,
[input.tenantId, first.customer_id, first.customer_name],
);
await client.query(
`INSERT INTO orders (tenant_id, order_id, customer_id, event_at)
VALUES ($1, $2, $3, $4)
ON CONFLICT (tenant_id, order_id) DO UPDATE SET
customer_id = EXCLUDED.customer_id,
event_at = EXCLUDED.event_at
WHERE orders.event_at <= EXCLUDED.event_at`,
[input.tenantId, orderId, first.customer_id, first.event_at],
);
const current = await client.query(
`SELECT event_at FROM orders WHERE tenant_id = $1 AND order_id = $2
FOR UPDATE`,
[input.tenantId, orderId],
);
if (new Date(current.rows[0].event_at).toISOString() !==
new Date(first.event_at).toISOString()) continue;
await client.query(
`DELETE FROM order_items WHERE tenant_id = $1 AND order_id = $2`,
[input.tenantId, orderId],
);
for (const row of rows) {
await client.query(
`INSERT INTO order_items (tenant_id, order_id, sku, quantity)
VALUES ($1, $2, $3, $4)`,
[input.tenantId, orderId, row.sku, row.quantity],
);
}
}
await client.query("COMMIT");
return reply.send({ status: "committed", orders: byOrder.size });
} catch (error) {
await client.query("ROLLBACK");
throw error;
} finally {
client.release();
}
});
Notice the batch marker is inserted inside the same transaction as the rows. If the transaction fails, the marker disappears too. Retrying the file then does useful work instead of being mistaken for a success. The FOR UPDATE also serializes replacement of one order’s items. For exact ties in event_at, the upstream contract should supply a monotonically increasing revision; timestamps alone cannot tell which different snapshot wins.
The read half of the data API keeps PostgreSQL behind the boundary too:
That x-verified-tenant-id header is only safe if a trusted gateway strips any client-supplied copy and injects its own value. In a direct deployment, put authentication and tenant extraction in a Fastify hook instead. The point is to show where tenant ownership is enforced, because “the new API is private” is not an authorization strategy.
The consumer needs the same route decision. Here the Databricks query uses a named parameter and the PostgreSQL side uses the data API. The adapter presents one order shape to its caller. This example assumes the order ID is globally unique in Databricks; if it is only unique per tenant, add tenant_id to the Delta tables and both predicates.
Finally, the worker uses its pinned route. Read traffic should use the tenant route only after the PostgreSQL side has been backfilled and checked.
My cutover order would be: add the new API and schema, backfill it from immutable files, compare order counts and sampled contents, run both paths in a controlled shadow period, then route one tenant’s writes and reads to PostgreSQL. Measure lag, API errors, rejected rows, and mismatches by tenant. Keep the original feed while rollback is needed. If writes have happened only on the new path, flipping the read switch back to Databricks can show stale data; rollback needs replay to the old path or a freeze until it catches up. That’s the part the tidy if statement never tells you.
2. Expedited shipping: a feature flag with a bill attached
Here’s a second example: turn on an expedited-shipping offer for a percentage of accounts. The new path does not merely paint a badge. It changes the checkout quote, so we need one stable decision per order and a record of the rule that produced the price.
The rule is: the account is included in the rollout, the destination is in the supported region, the cart subtotal is at least 7,500 cents, and the feature has not been killed globally. I use a stable FNV-1a hash of accountId for the rollout. It is small and portable across TypeScript and Go; it is not a security primitive. A production flag service can own the assignment instead, provided both stacks read the same assignment.
TypeScript implementation
This is where teams often reach for Math.random() and accidentally give the same customer a different offer on every refresh. The bucket makes the rollout stable. The saved decision makes an in-progress checkout stable even if the operator moves from 10% to 20% while a customer is entering their card details.
The same boundary in Go
If another service computes a quote in Go, it must agree on byte encoding, hash, threshold, region names, and cents. This uses only the standard library.
I would put a shared set of fixture inputs in both test suites: account IDs with ASCII and non-ASCII characters, rollout at 0 and 100, subtotal at 7,499 and 7,500 cents, each region, and the kill switch. The tests should assert that TypeScript and Go assign the same account to the same bucket. This is one of those boring cross-language details that becomes a very exciting checkout bug if you skip it.
The rollout sequence is straightforward: ship both implementations dark, compare decisions against fixtures, enable internal accounts, then 1%, 10%, and onward while watching quote errors, conversion, fulfillment capacity, and customer support reports. The kill switch stops new offers. Existing orders retain their stored price and promise; changing those would be a different business operation. When the feature is permanent, remove the rollout branch and leave the eligibility rule as normal checkout code.
3. Saved filters: the interface switch and the user’s own toggle
The third example is a saved-filters panel for an order list. There are two switches here that people tend to conflate. The feature flag says whether this account has access to saved filters. The user preference says whether the available panel is currently shown. If the feature flag is off, the preference cannot manufacture access.
The server returns a capability document after authentication:
The endpoint that creates or lists saved filters must evaluate the account’s capability again. A React component that omits a button is a nicer screen, not an access control check. The same applies on iOS.
TypeScript and React
The browser fetches the capability, treats unknown as off, and lets the person hide or show the panel with a visible toggle. The preference is local to the browser in this version; if we want it to follow a user across devices, that becomes a server-side preference with its own API and migration.
The button passes a filter ID, not arbitrary SQL from storage. The order list asks its own API to apply that ID under the current account. If the flag goes off while this page is open, a fresh capability fetch on navigation or a short-lived cache will remove the panel; the API check shuts off server access immediately.
The same feature in SwiftUI
On iOS, @AppStorage is the user preference. The capability still comes from the server. A small model loads it and, only when allowed and opened, loads the filters.
The app’s authenticated URLSession would carry the user’s credentials; the sample leaves that wiring to the host app. When someone taps a filter, the host sends the ID to the order-list API rather than trusting the locally decoded query. I would test both clients with the same capability responses: on, off, failed request, and revocation after the screen has loaded. I would also test the API endpoint directly with the feature disabled. The server is the actual gate.
The switch has a lifecycle
Across these examples, I would keep a little record for every flag: owner, default, scope, rollout plan, telemetry, rollback behavior, and removal date. The pipeline route is scoped to a tenant and batch. The shipping offer is scoped to a stable account cohort and then frozen into an order quote. The interface flag is scoped to an authenticated account, while the visible on/off control is a separate user preference.
That distinction is the useful mental model. A toggle switch is an operational decision point, and the rest of the system has to agree on what was decided. Give it one boundary, persist decisions when they affect money or durable data, measure the new path, and remove the temporary branch after the migration is over. Otherwise the switch becomes one more permanent mystery in the codebase, which is a lousy reward for trying to ship safely.
References
You must be logged in to post a comment.