The scope includes query-first modeling, partition key design, Storage-Attached Indexes (SAI), consistency levels, lightweight transactions (LWT) and Accord, tombstones, compaction, drivers, security, repair, backups, monitoring and upgrades. Every rule comes with the reason behind it, so you can judge when it fits your workload and when it does not.

Many popular guides still carry pre-5.0 advice. This guide adds what they often miss: the limits of SAI, UCS versus the STCS default, repair tied to gc_grace_seconds, driver settings, security and restore testing. It is written for engineers, architects and DBAs who run Cassandra in production.

For the version baseline, Apache Cassandra 5.0 is the latest GA series (5.0.9, released 2026-08-07), and 4.1 is the previous stable line (4.1.12). The 3.x series is end-of-life. Cassandra 6.0 is still pre-GA (6.0-alpha3) and is not for production.

Version note: This guide targets Apache Cassandra 5.0.9 (latest GA) and 4.1.12 (previous stable line), and treats 6.0-alpha3 as pre-GA only.

 

In this guide

 

• Cassandra Best Practices at a Glance
• Cassandra Data Modeling Best Practices and Partition Key Design
• Indexing in Cassandra 5.0: SAI, Secondary Indexes or More Tables
• Consistency Levels and Replication Factor: Choosing LOCAL_QUORUM
• Transactions and Lightweight Transactions: Paxos v2 and Accord in Cassandra 6.0
• Tombstones, TTL and gc_grace_seconds: Deleting Data Safely
• Choosing a Compaction Strategy: STCS, LCS, TWCS or UCS
• Drivers, Connection Management and Security
• Repair, Backup and Restore Best Practices
• Operations, Monitoring and Upgrades
• Common Cassandra Anti-Patterns
• Cassandra Production Readiness Checklist
• Key takeaways
• FAQ

Cassandra Best Practices at a Glance

Apache Cassandra is a distributed, wide-column database built for high write throughput and availability across nodes and datacenters. Today in this guide, we will see Cassandra data modeling best practices, consistency, indexing, repair, backups and upgrades in one place.

Note: A partition is like one drawer in a filing cabinet. Every row with the same partition key goes into the same drawer, and that drawer lives on specific nodes. Unlike a real cabinet, each drawer is copied to several nodes, so one failure doesn’t lose it.

Best Practices Summary Table

The table below lists the main areas, what to do and what to avoid. Each row is explained in its own section later.

Which Cassandra Version Does This Guide Assume?

This guide uses the versions below as its baseline.

• 5.0.9: the latest GA release, and the preferred target.
• 4.1.12: the latest on the previous stable line.
• 6.0-alpha3: pre-GA and not for production.
• Java: Java 11 and 17 are used with Cassandra 5.0.x.

Cassandra Data Modeling Best Practices and Partition Key Design

Design your tables from your queries, not from your entities. A good Cassandra model has three goals: spread data evenly with a high-cardinality partition key, bound partition size, and read as few partitions as possible, ideally one per query.

Why should a query read only one partition?

A single-partition read goes to the replicas that own that partition. A multi-partition read makes the coordinator (the node handling the request) contact several nodes and wait for the slowest one. That adds latency variance, so the occasional slow response hurts your tail latency.

How do you choose the partition key and clustering columns?

The partition key decides which nodes hold the data. Clustering columns decide the sort order of rows inside that partition. Pick the partition key from the column your query always filters by with equality, and pick clustering columns from the sort or range you need.

Example: a retail app shows “my orders, newest first”. The table below shows how the choice maps.

How big should a partition be?

Keep partitions under about 100 MB and under about 100,000 items. The hard practical limit is 2 billion cells per partition, but you should never plan to get near it.

Oversized partitions hurt in several ways:

• Heavy reads: the node must scan and merge more data for each request.
• Compaction and repair pressure: large partitions take longer to merge and to compare between replicas.
• Hot nodes: one partition lives on only a few replicas, so one big partition loads those nodes unevenly.

How does bucketing keep partitions bounded?

Bucketing means adding a column, such as a day or hour, to the partition key so a busy key stops growing forever. One IoT sensor writing every second would otherwise build a single unbounded partition.

In plain English: Think of a ledger where you start a new page every day. You never end up with one endless page, and you can still find any day quickly. The catch is that a question spanning ten days means opening ten pages.

Here is a simplified sensor table with a day bucket in the partition key, followed by a single-partition read:

CQL

CREATE TABLE iot.sensor_readings (
    sensor_id    text,
    day_bucket   date,
    reading_time timestamp,
    temperature  double,
    PRIMARY KEY ((sensor_id, day_bucket), reading_time)
) WITH CLUSTERING ORDER BY (reading_time DESC);

SELECT reading_time, temperature
FROM iot.sensor_readings
WHERE sensor_id = 'sensor-1001'
  AND day_bucket = '2026-10-20'
LIMIT 100;

✅ One partition, newest readings first, and each partition holds at most one day of data per sensor.

The trade-off: a query over several days now touches several partitions. The application must list the buckets and query each one explicitly (e.g. seven queries for a week). Choose a bucket size so a partition stays within the limits above at your peak write rate.

What are hot partitions and how do you avoid them?

A hot partition is one that receives a disproportionate share of traffic. Low-cardinality keys such as country or status create them, because millions of rows share a few key values and land on a few nodes. Use a key with many distinct values, and add a bucket if one value is still very busy.

Is denormalization normal in Cassandra?

Yes. Cassandra has no joins, so you store the same data in several tables, one per query (e.g. orders_by_customer and orders_by_date). One write to several tables is cheaper than a read that must gather data from many partitions.

Use a logged batch only to keep those denormalized tables in sync, because it guarantees all writes eventually apply. Don’t use it for speed. A batch across many partitions adds work on the coordinator.

Why avoid ALLOW FILTERING and full scans?

ALLOW FILTERING lets a query run without a full partition key, so Cassandra reads many partitions and discards rows that don’t match. Cost grows with table size, and latency becomes unpredictable. Keep it out of application paths. If you need the query often, create a table for it instead.

Indexing in Cassandra 5.0: SAI, Secondary Indexes or More Tables

Use denormalized tables for hot, latency-critical queries. Use Storage-Attached Indexes (SAI), new in Cassandra 5.0, for secondary lookups where a partition-key query is not possible. Avoid legacy secondary indexes (2i) in new designs.

What is SAI in Cassandra 5.0?

SAI is an index attached to the SSTables of a table. It lets you filter on non-key columns without creating a separate table. The 5.0 feature list also includes a vector data type with similarity functions, which builds on SAI.

In plain English: A denormalized table is a second filing cabinet sorted the way you search. SAI is a small index card stapled to each existing drawer, so you can look things up by another field. The cards help, but you still have to know which drawers to open.

Denormalized table, SAI or legacy index?

The table below compares the three options across cost and limits.

What are the limits of SAI?

An SAI query with no partition key may fan out across nodes, so it adds latency variance. SAI does not remove the need for Cassandra data modeling best practices. Test every SAI query on production-size data before you rely on it, because small test sets hide fan-out cost.

When should you pick which?

• Primary query: “orders by customer” is the main read path, so build it as a table keyed by customer.
• Secondary filter: “find orders by status in this customer’s partition” is fine with SAI plus a partition restriction (e.g. a retail support screen).
• Cross-partition search: Use SAI only if the latency variance is acceptable. Otherwise add another table.

Here is a simplified example that indexes the status column and queries it inside one customer partition:

CQL

CREATE TABLE IF NOT EXISTS shop.orders_by_customer (
  customer_id uuid,
  order_id timeuuid,
  status text,
  total decimal,
  PRIMARY KEY ((customer_id), order_id)
) WITH CLUSTERING ORDER BY (order_id DESC);

CREATE INDEX IF NOT EXISTS orders_status_sai
  ON shop.orders_by_customer (status) USING 'sai';

SELECT order_id, status, total
FROM shop.orders_by_customer
WHERE customer_id = 7b1f3c52-8a6e-4c1d-9d0e-3f2a5b6c7d88
  AND status = 'SHIPPED';

The query returns only the shipped orders for that one customer. The partition key restriction keeps it on the replicas of a single partition, and SAI handles the status filter.

Consistency Levels and Replication Factor: Choosing LOCAL_QUORUM

For most multi-datacenter production workloads, use RF=3 per datacenter with LOCAL_QUORUM for both reads and writes. RF=3 lets a quorum form from two agreeing replicas, tolerates one node failure and allows rolling restarts without downtime.

What is a consistency level?

A consistency level is the number of replicas that must confirm a read or write before Cassandra reports success to the client. You choose it per request, so different queries can make different trade-offs.

Note : Three people hold a copy of the same record. A consistency level decides how many of them must say “done” before you accept the answer, like a committee that needs a majority vote. The analogy stops fitting in one place: Cassandra still sends the write to all copy-holders, it only waits for some of them.

How do QUORUM and LOCAL_QUORUM differ?

QUORUM needs RF/2 + 1 replicas (integer division) across all datacenters. LOCAL_QUORUM needs a majority only in the coordinator’s datacenter, which is 2 of 3 with RF=3.

With two datacenters at RF=3, there are six replicas in total, so QUORUM needs four. That forces at least one cross-datacenter acknowledgment. LOCAL_QUORUM avoids that WAN latency and keeps working if the other datacenter is completely down. The animated diagram below shows a LOCAL_QUORUM write, including the case where DC2 is unavailable.

Which consistency level fits which use case?

The table assumes two datacenters with RF=3 each (six replicas in total).

When do you get strong consistency?

You get strong consistency when read replicas plus write replicas is greater than RF. With RF=3, LOCAL_QUORUM on both sides gives 2 + 2 = 4, which is more than 3, so every read overlaps at least one replica that saw the latest write. This gives read-your-writes within that datacenter.

Know the trade-offs. ALL fails as soon as one replica is down, so one node restart becomes an outage. ONE is fast but can return stale data. Use lower levels only where staleness is acceptable, such as video view counters on a media site. Use LOCAL_QUORUM for order and payment data in a retail system.

How do you set replication correctly?

Use NetworkTopologyStrategy with an explicit RF per datacenter, and make sure the snitch reports correct datacenter and rack names. Do not use SimpleStrategy in production multi-datacenter clusters, because it ignores topology and can place all replicas in one rack or datacenter.

The example below creates a keyspace with RF=3 in each datacenter, then sets the session consistency in cqlsh:

CQL

CREATE KEYSPACE retail
  WITH replication = {
    'class': 'NetworkTopologyStrategy',
    'dc1': 3,
    'dc2': 3
  };

CONSISTENCY LOCAL_QUORUM;

Each datacenter keeps three replicas, and every later read or write in this cqlsh session waits for two local replicas. The names dc1 and dc2 must match the datacenter names your snitch reports.

Transactions and Lightweight Transactions: Paxos v2 and Accord in Cassandra 6.0

Cassandra gives you atomicity and isolation per partition. For compare-and-set on a single partition it offers lightweight transactions (LWT, written as IF conditions). It is not a general ACID database today.

When should you use a lightweight transaction?

Use LWT only where two writers must not both succeed, such as a unique username or an inventory reservation. Paxos, the consensus protocol behind LWT, needs several round trips between replicas, so it costs far more than a normal write. Don’t make it your default write path.

In plain English: A normal write is like dropping a note in a mailbox. An LWT is like getting every committee member to agree out loud before the note is filed. It is safer, but it takes much longer.

Example: a bank checks that an email is unused before opening an account. The check and the insert must happen as one step, as shown below.

CQL

CREATE TABLE IF NOT EXISTS bank.users_by_email (
  email text PRIMARY KEY,
  user_id uuid,
  created_at timestamp
);

SERIAL CONSISTENCY LOCAL_SERIAL;

INSERT INTO bank.users_by_email (email, user_id, created_at)
VALUES ('asha@example.com', uuid(), toTimestamp(now()))
IF NOT EXISTS;

The result has an [applied] column. True means the row was inserted. False means the email already exists, and the existing row is returned. Always check this column in your application code. LOCAL_SERIAL limits the Paxos phase to the local datacenter, and SERIAL spans all datacenters.

Which Paxos settings should you set in production?

Set paxos_variant to v2 together with paxos_state_purging set to repaired. The two settings are independent, so set both deliberately. Test the change in staging and follow the official upgrade notes for your exact version.

What does Accord in Cassandra 6.0 add?

Accord adds multi-partition, strict-serializable transactions through BEGIN TRANSACTION. Cassandra 6.0 is still pre-GA (6.0-alpha3), and Accord is beta and off by default. It requires Transactional Cluster Metadata and doesn’t support counter tables. It also rejects LOCAL_QUORUM, TWO and THREE for Accord operations. Don’t plan production designs on it yet, because 5.0.9 remains the current GA release.

Plain writes, logged batch, LWT or Accord: how do they compare?

This table compares the four options by scope, isolation, cost and status.

Tombstones, TTL and gc_grace_seconds: Deleting Data Safely

A delete in Cassandra writes a tombstone, a marker saying the data is deleted, instead of removing it right away. Tombstones are purged only after gc_grace_seconds (default 864000 seconds, 10 days) has passed and only when compaction runs. Until then, reads must scan them, so heavy deletes slow reads.

In plain English: A tombstone is a crossed-out line in a ledger. The old line stays on the page, and the crossing-out is only cleaned up when the ledger is rewritten. Unlike a ledger, Cassandra keeps copies on several nodes, and every copy must see the crossing-out.

Why must repair finish within gc_grace_seconds?

If a replica misses a delete and the other replicas purge their tombstones, that replica becomes the only holder of the row. The next read or repair copies the old value back, and the deleted row returns as zombie data. Repair inside the grace window prevents this.

The animated diagram below shows a delete across three replicas, with the healthy path and the zombie failure path side by side.

What creates tombstones?

These patterns produce most tombstone problems in production:

• Queue-style tables: rows are inserted, read and deleted in the same partition, so reads scan many dead entries.
• Frequent deletes: every delete adds a marker that stays for at least the grace period.
• Partial deletes in wide partitions: row or range deletes inside a large partition leave many markers next to live data.
• Null writes: explicitly inserting null writes a tombstone. Leave the column out of the statement, or pass the driver’s unset value (e.g. UNSET_VALUE in the Python driver).

How do you delete data safely?

1. Use TTL instead of DELETE: let data expire on its own schedule. Cassandra 5.0 also extends the maximum TTL, which helps for long retention.
2. Bucket by time: put a day or hour bucket in the partition key so old data sits in partitions you stop reading.
3. Avoid large range deletes: they leave wide tombstones that every read must check.
4. Use TWCS for TTL-heavy data: when data is time-windowed and not updated out of order, whole expired SSTables can be dropped.

Example: a retail site keeps cart-activity events for seven days. TTL plus TWCS removes them without any application delete.

CQL

CREATE TABLE shop.cart_events (
    user_id    uuid,
    day_bucket date,
    event_time timestamp,
    event_type text,
    PRIMARY KEY ((user_id, day_bucket), event_time)
) WITH CLUSTERING ORDER BY (event_time DESC)
  AND default_time_to_live = 604800
  AND compaction = {
    'class': 'TimeWindowCompactionStrategy',
    'compaction_window_unit': 'DAYS',
    'compaction_window_size': 1
  };

INSERT INTO shop.cart_events (user_id, day_bucket, event_time, event_type)
VALUES (uuid(), '2026-10-20', toTimestamp(now()), 'add_to_cart')
USING TTL 86400;

The table default expires rows after seven days, and the insert overrides it with a one-day TTL. Each daily window becomes its own SSTable group that can be dropped as a whole.

How do you catch tombstone problems early?

Set the tombstone warn and failure thresholds in cassandra.yaml and review the guardrails available in your version. Check nodetool tablestats for average and maximum tombstones per slice, and watch the logs for tombstone warnings.

Warning: Don’t lower gc_grace_seconds just to purge faster. A shorter value frees space sooner, but it raises the risk of zombie data unless repair completes more often than the new value. Lower it only after your repair schedule is proven to beat it.

Choosing a Compaction Strategy: STCS, LCS, TWCS or UCS

STCS is still the default in Cassandra 5.0, but the UCS documentation recommends the Unified Compaction Strategy (UCS) for most workloads. UCS can also be configured to behave like the older strategies. If you stay on classic strategies, use TWCS for TTL-heavy time-series data.

What does compaction do?

Compaction is the background process that merges SSTables (the immutable data files on disk) to drop overwritten data and expired tombstones. The strategy you pick decides which files get merged and when.

In plain English: Think of many small notebooks piling up on a desk. Compaction copies the latest notes into fewer, cleaner notebooks and throws the old ones away. The strategy is the rule for which notebooks you tidy together, and how often.

How do the four strategies compare?

The animated diagram below walks through the decision for one table, and the table after it compares the strategies in qualitative terms.

Why do the strategies behave differently?

• LCS: keeps data in small sorted levels, so a read touches few files. You pay with more write I/O.
• STCS: favors writes by merging files of similar size. Large merges need free disk space while they run.
• TWCS: groups data into time windows and drops a whole SSTable once everything in it has expired. This only works if data isn’t updated or deleted out of order.

How do you migrate a table to UCS?

1. Test first: try the change on a non-production cluster with realistic data.
2. Change per table: use ALTER TABLE, one table at a time.
3. Mimic your current strategy: start with settings that behave like STCS or LCS, then tune.
4. Watch the switch: track pending compactions and disk use while it runs.

Parameter names and defaults can change between versions, so confirm them in the official UCS documentation for your release. The T4 value below is the STCS-like setting from the 5.0 docs.

CQL

-- UCS, configured to behave like STCS
ALTER TABLE shop.orders_by_customer
WITH compaction = {
  'class': 'UnifiedCompactionStrategy',
  'scaling_parameters': 'T4'
};

-- TWCS for TTL-heavy time-series data
ALTER TABLE iot.sensor_readings
WITH compaction = {
  'class': 'TimeWindowCompactionStrategy',
  'compaction_window_unit': 'DAYS',
  'compaction_window_size': 1
};

Each statement changes the strategy for one table only. Then check progress on each node:

bash

nodetool compactionstats

This shows pending tasks and running compactions. A pending count that keeps growing after the switch means the node can’t keep up.

Cassandra 5.0 also adds trie memtables and trie SSTables. They are separate storage features from compaction, and you can evaluate them on their own.

Drivers, Connection Management and Security

Use one long-lived session per application, prepared statements, token-aware and datacenter-aware load balancing, and an explicitly set local datacenter. Turn on authentication, authorization and TLS from day one, because adding them later means a risky rolling change on a live cluster.

How should you manage connections?

Create the Session once at startup and share it across all requests. Opening one per request wastes connections and adds handshake latency. A prepared statement is parsed once on the server, and it lets the driver work out which replicas own the partition.

In plain English: Token-aware routing is like a courier who knows which house holds the parcel and goes straight there, instead of leaving it at a front desk that must pass it on. The “front desk” is the coordinator, and skipping it saves one network hop.

Set the local datacenter explicitly so traffic never reaches a remote DC by accident. Enable retries and speculative execution (sending a second request when the first is slow) only for idempotent statements, meaning ones that are safe to run twice.

The table below lists the driver settings to check, with the value to use and the reason:

How do you configure the Python driver?

Here is a simplified example using ExecutionProfile, the current way to set policies and consistency:

Python

import os
import ssl
from cassandra import ConsistencyLevel
from cassandra.auth import PlainTextAuthProvider
from cassandra.cluster import Cluster, ExecutionProfile, EXEC_PROFILE_DEFAULT
from cassandra.policies import DCAwareRoundRobinPolicy, TokenAwarePolicy

profile = ExecutionProfile(
    load_balancing_policy=TokenAwarePolicy(DCAwareRoundRobinPolicy(local_dc="dc1")),
    consistency_level=ConsistencyLevel.LOCAL_QUORUM,
    request_timeout=5.0,
)

cluster = Cluster(
    ["10.0.0.1", "10.0.0.2"],
    auth_provider=PlainTextAuthProvider("app_user", os.environ["CASS_PASSWORD"]),
    ssl_context=ssl.create_default_context(cafile="ca.pem"),
    execution_profiles={EXEC_PROFILE_DEFAULT: profile},
)
session = cluster.connect("shop")  # create once, reuse everywhere

stmt = session.prepare("SELECT * FROM orders_by_customer WHERE customer_id = ?")
stmt.is_idempotent = True
rows = session.execute(stmt, [customer_id])

✅ One shared session, local DC set, LOCAL_QUORUM by default, TLS on, and a prepared read marked idempotent.

How do you configure the C# driver?

With the DataStax C# driver (CassandraCSharpDriver), build the Cluster once and register the session as a singleton:

C#

using Cassandra;

var cluster = Cluster.Builder()
    .AddContactPoints("10.0.0.1", "10.0.0.2")
    .WithLocalDatacenter("dc1")
    .WithCredentials("app_user", Environment.GetEnvironmentVariable("CASS_PASSWORD"))
    .WithSSL()
    .Build();

var session = await cluster.ConnectAsync("shop"); // singleton

var prepared = await session.PrepareAsync(
    "SELECT * FROM orders_by_customer WHERE customer_id = ?");

var bound = prepared.Bind(customerId)
    .SetConsistencyLevel(ConsistencyLevel.LocalQuorum)
    .SetIdempotence(true);

RowSet rows = await session.ExecuteAsync(bound);

The local DC is named, the statement is prepared and bound, and consistency is LocalQuorum.

How do you secure a Cassandra cluster?

Enable PasswordAuthenticator and CassandraAuthorizer in cassandra.yaml. Create your own superuser, then disable or drop the default cassandra role. Give each application a role with only the permissions it needs.

CQL

CREATE ROLE analyst WITH PASSWORD = 'use-a-strong-secret' AND LOGIN = true;
GRANT SELECT ON KEYSPACE clinic TO analyst;

• TLS: Enable client-to-node and node-to-node encryption. Use mutual TLS where you control the clients.
• Dynamic data masking (5.0): Hides sensitive column values from roles without unmask rights. Example: mask patient identifiers for analyst roles in a healthcare system.
• CIDR authorizer (5.0): Limits which networks a role can connect from.
• Guardrails: Added in 4.1 and extended in 5.0, they set warn and fail limits that stop risky operations, such as oversized partitions or too many tables.

Repair, Backup and Restore Best Practices

Run repair on every node within each gc_grace_seconds window. With the default of 864000 seconds that means at least once every 10 days, and in practice more often to leave a safety margin. Take scheduled snapshots with retention, enable commit log archiving for point-in-time restore, and test restores regularly.

What does Cassandra repair do?

Repair compares the replicas of the same data using Merkle trees (hash trees that summarize ranges of data) and streams any differences between nodes. It fixes data that a replica missed, for example while the node was down.

In plain English: Three people each keep a copy of the same notebook. Repair is the meeting where they compare page summaries, find pages that differ, and fill in the gaps. Unlike real people, the nodes compare hashes first, so they only copy the pages that really differ.

How should you schedule repair?

Run repair regularly in small pieces instead of rarely in one large job. Follow these rules:

• Prefer incremental repair: on versions that support it, it only checks data not yet repaired. Use full repair only when the release notes or a recovery task call for it.
• Use -pr on every node: the primary-range option repairs only the ranges a node owns first, so the same data isn’t compared three times.
• Go node by node: running repair on all nodes at once adds heavy streaming and compaction load.
• Automate it: open-source Cassandra has no NodeSync equivalent from DSE. Auto Repair (built-in scheduling) arrived in the 5.0.8+ backport and needs explicit opt-in. Otherwise use an external scheduler. Verify against the release notes for your exact version before enabling.
• Watch TTL-heavy tables: expired data becomes tombstones, and a replica that missed one can bring old values back after the purge. This is the same zombie-data risk described in the tombstones section.

Here is a simplified example of repairing the primary ranges of one keyspace on the current node:

BASH

nodetool repair -pr shop_ks

✅ Repairs only the ranges this node owns. Repeat on the next node when it finishes.

Which backup method should you use?

Use snapshots as the base and add commit log archiving if you need point-in-time recovery. The table compares the four common methods:

Take a named snapshot, then copy it off the node:

BASH

nodetool snapshot -t daily_2026-10-20 shop_ks

Creates a snapshot tagged daily_2026-10-20 for every table in shop_ks. Store it off the node, because a snapshot on the same disk does not survive disk loss.

How do you restore and test a backup?

Restore the schema first, then the data, then run repair. The animated diagram below shows the full restore flow, step by step.

A restore test loads schema, snapshot SSTables and archived commit logs into a fresh cluster, then repairs and validates row counts against the source.

1. Restore the schema: apply the saved CQL so tables exist.
2. Load the data: stream SSTables with sstableloader, or copy files into the table directory and run nodetool refresh.
3. Replay commit logs: stop at the target timestamp for point-in-time recovery.
4. Repair and validate: run repair, then compare row counts with the source.

BASH

sstableloader -d 10.0.1.11,10.0.1.12 /restore/shop_ks/orders_by_customer

Streams the SSTables in that directory to the live cluster. The path must end in keyspace/table.

A backup that was never restored is untested. Run the restore on a separate cluster on a schedule, and time it. For example, a retail team can check that last night’s order tables match production before trusting the backup for peak season.

Operations, Monitoring and Upgrades

Run a supported Java version, keep OS and disk settings aligned with Cassandra’s recommendations, watch partition size and pending compactions, and upgrade by rolling one node at a time to a supported release line. The sections below cover each of these.

Which Java, disk and OS settings should you check?

Cassandra 5.0.x runs on Java 11 and Java 17. Pick one of them and use it on every node.

• Disks: Put the commit log and data directories on separate disks where possible, so sequential commit log writes don’t compete with compaction and reads.
• Free space: Keep free disk for compaction. STCS in particular needs spare room when it merges large SSTables.
• Heap: Start from the JVM options files shipped with your version, not values copied from old blog posts. Those were tuned for other Java and Cassandra releases.
• Swap and limits: Disable swap and raise ulimits and file-descriptor limits as the Cassandra docs recommend.
• Clocks: Run NTP or chrony on every node. Cassandra resolves conflicting writes by timestamp, so a drifting clock can make an older write win.

What should you monitor?

Start with partition size and compaction backlog, then add latency and GC. The table shows each signal and what to do about it.

Use these commands to find oversized partitions:

Bash

# Partition size and cell count percentiles for one table
nodetool tablehistograms retail orders_by_customer

# Look for "Compacted partition maximum bytes" in the output
nodetool tablestats retail.orders_by_customer

The first command shows percentile distributions. The second gives the largest partition on that node.

How do you upgrade Cassandra safely?

Upgrade one node at a time, one major version at a time. Versions 3.0 and 3.11 reached end-of-life when 5.0 went GA on September 5, 2024, so plan to leave them. The 4.1 line is at 4.1.12, the 4.0 line is at 4.0.21, and 5.0.9 is the current GA. Don’t run 6.0-alpha3 in production.

In plain English: A rolling upgrade is like renovating a hotel one room at a time. Guests keep using the other rooms, so the hotel never closes. It only works if the other rooms are in good shape, which is why you repair first.

1. Read NEWS.txt: Check the target version for required steps and breaking changes.
2. Snapshot: Take a snapshot on every node.
3. Repair and check health: Finish a repair and confirm all nodes are up.
4. Freeze schema: Make no schema changes until every node is upgraded.
5. Roll each node: Drain, stop, upgrade, start, then check.
6. Rewrite SSTables if needed: Run upgradesstables only when the release notes ask for it.

This is the command sequence for one node:

Bash

nodetool snapshot -t pre_upgrade retail
nodetool drain                      # flush memtables, stop accepting writes
sudo systemctl stop cassandra
# install the new Cassandra package or binaries here
sudo systemctl start cassandra
nodetool status                     # wait for UN (Up/Normal) before the next node
nodetool upgradesstables            # only if the release notes require it

Streaming during node operations is faster since 4.0, because zero-copy streaming sends eligible whole SSTables without rewriting them.

Common Cassandra Anti-Patterns

These are the mistakes that most often cause slow reads, hot nodes and data resurrecting. Each row below names the symptom you will see and the fix, with a pointer to the section that explains the reason.

In plain English: An anti-pattern is a habit that looks fine on day one and hurts later. Think of a shop that stacks every receipt in one box: it works for a week, then finding anything takes all afternoon.

The table lists 15 Cassandra anti-patterns, the symptom of each, and the fix.

Which anti-patterns should you fix first?

Start with the ones that can lose or resurrect data: skipped repair and untested snapshots. Then fix partition design, because a bad partition key is the hardest thing to change once data exists. Driver settings and consistency defaults are cheap to correct and worth doing early.

Cassandra Production Readiness Checklist

Use this Cassandra production checklist as a go-live gate. Each item has a check you can run or verify, so you can mark it done or not done. Any item you can’t verify is a risk to note before launch.

Cluster and Driver Setup

These items confirm the cluster layout and how clients connect to it.

1. Supported version: every node runs a supported line, preferably 5.0.x (5.0.9 is the latest GA). No 3.x nodes and no 6.0-alpha builds.
2. Replication: DESCRIBE KEYSPACE shows NetworkTopologyStrategy with RF=3 in each datacenter.
3. Driver settings: the local datacenter is set explicitly and the default consistency is LOCAL_QUORUM. One long-lived session is shared by the application.
4. Host settings: the JVM is on Java 11 or 17, swap is off, ulimits are raised, and NTP or chrony reports synced clocks on every node.

Data Model and Storage

These items catch the design problems that are expensive to fix after launch.

5. Query shape: each application query reads one partition, and none uses ALLOW FILTERING.
6. Partition size: nodetool tablehistograms and tablestats show compacted partition maximum bytes under about 100 MB.
7. Bounded keys: no partition key grows forever. A time bucket is in the key wherever volume is unbounded.
8. Table settings: every table has a deliberate TTL and compaction strategy (UCS, or TWCS for TTL-heavy data).

Recovery and Upgrades

These items prove you can recover from failure and keep deleted data deleted.

9. Repair: the schedule covers every node within gc_grace_seconds (864000 seconds by default), with a safety margin.
10. Backups: snapshots run on a schedule with retention, are copied off the node, and commit log archiving is on.
11. Restore test: a restore into a separate cluster has been completed and timed, and the time is written down.
12. Upgrade runbook: a written rolling-upgrade procedure exists and has been rehearsed in staging.

Security and Monitoring

These items keep the cluster protected and give you early warning.

13. Access control: authentication, authorization and TLS (client-to-node and node-to-node) are enabled, and the default cassandra superuser is replaced.
14. Guardrails: warn and fail limits are configured, for example for partition size and table count.
15. Alerts: alerts fire on latency percentiles, pending compactions, disk usage and dropped messages, and each alert has a named owner.

Key takeaways

These are the points to remember from this guide before you take a Cassandra cluster to production:

• Model from queries: design one table per query, and accept denormalization. Cassandra has no joins, so one write to several query tables is cheaper than reads that need many partitions.
• Bound your partitions: keep each partition under about 100 MB and about 100,000 items. Add a time bucket (e.g. day or hour) to the partition key for busy keys, and check the real size with nodetool tablehistograms and tablestats.
• Use LOCAL_QUORUM with RF=3: set NetworkTopologyStrategy with RF=3 per datacenter, and use LOCAL_QUORUM for reads and writes. This gives read-your-writes inside the datacenter, tolerates one node down and avoids cross-DC latency.
• Prefer TTL over deletes: explicit deletes and null writes create tombstones that slow reads. Use TTL, time bucketing and TWCS for time-series data instead.
• Finish repair inside gc_grace_seconds: the default is 864000 seconds (10 days). If repair is late, a replica that missed a delete can bring the old data back. Schedule it with the opt-in Auto Repair (5.0.8+) or an external scheduler.
• Test your restores: schedule snapshots with retention, store them off the node, archive commit logs for point-in-time recovery, and restore into a separate cluster on a schedule. A backup that was never restored is untested.
• Pick compaction and indexes deliberately: STCS is still the 5.0 default, but UCS is recommended for most workloads, and TWCS suits TTL-heavy data. SAI helps with secondary lookups, but it does not replace query-first modeling. Test both on production-size data first.
• Stay on supported, GA releases: 5.0.9 is the current GA release, and 3.x is end-of-life. Treat Accord and Cassandra 6.0 (still 6.0-alpha3) as pre-GA, and keep them out of production designs.

That’s all! Happy coding!

Did this Cassandra best practices guide help you? Please share your questions and your own experience in the comments below.

Bookmark this page for your next production review, and share it with your team. Subscribe to TheCodeBuzz for more database best practices guides.

FAQ

What is the ideal partition size in Cassandra?

Keep each partition under about 100 MB and under about 100,000 items. The hard practical limit is 2 billion cells per partition, but you should stay far below it. Check real sizes with nodetool tablehistograms and nodetool tablestats (look at the compacted partition maximum bytes), and add a time bucket to the partition key if a partition keeps growing.

Which consistency level should I use in production, QUORUM or LOCAL_QUORUM?

Use LOCAL_QUORUM for multi-datacenter clusters, with RF=3 in each datacenter. It needs a majority (2 of 3) in the coordinator’s datacenter only, so it avoids cross-DC latency and keeps working if another datacenter is down. QUORUM counts replicas across all datacenters, and EACH_QUORUM is supported for writes only.

How often should I run nodetool repair, and why must it finish within gc_grace_seconds?

Run repair on every node at least once within each gc_grace_seconds window, which is 10 days (864000 seconds) by default. In practice, repair more often to leave a safety margin. If a replica missed a delete and the tombstone is purged on the other replicas, the old value can come back as zombie data. Cassandra 5.0.8 and later include Auto Repair, which needs explicit opt-in, so check the release notes for your exact version before enabling it.

Should I use Storage-Attached Indexes (SAI) or denormalize into more tables?

Denormalize into tables for your hot, latency-critical queries, and use SAI for secondary lookups where a partition-key query is not possible. Avoid legacy secondary indexes (2i) in new designs. An SAI query without a partition key restriction can fan out across nodes and add latency variance, so test it on production-size data.

Does Cassandra support ACID transactions, and what changes in Cassandra 6.0?

Not fully. Cassandra gives atomicity and isolation per partition, and lightweight transactions (IF conditions) give compare-and-set on a single partition. For Paxos-based LWT, the recommended production setup is paxos_variant v2 with paxos_state_purging set to repaired. Cassandra 6.0 adds Accord, which offers multi-partition, strict-serializable transactions through BEGIN TRANSACTION. Accord is beta and off by default, and 6.0 is still pre-GA (6.0-alpha3), so 5.0.9 remains the current GA release and you should not plan production designs on Accord yet.

Sources and further reading

• Apache Cassandra: Downloading Cassandra (Apache Cassandra project)
• Announcing Apache Cassandra® 5.0 (Apache Cassandra project)
• New Features in Apache Cassandra 5.0 (Apache Cassandra project)

The post Cassandra Best Practices: Data Modeling, Consistency, Operations first appeared on TheCodeBuzz.

Note- Version-specific facts are dated 2026-10-17.

The main principle is simple: use the smallest thing that works. A single call to an LLM with document lookup (retrieval) and a few examples is often enough. Agents trade latency and cost for flexibility. In simple terms, an LLM (large language model) is the text-generating AI behind chat assistants. In simple terms, an agentic workflow is a multi-step AI task in which a model uses tools and data while your code sets the steps, limits and checks. In simple terms, an agent is a system where the model itself decides the next step and which tool to use.

Next come the workflow-versus-agent choice, design patterns, the agent loop, durable execution, human approval, security with the OWASP Agentic Top 10, tracing, evaluation, and cost and latency.

Version note: As of 2026-10-17, this guide targets LangGraph 1.2.16, OpenAI Agents SDK 0.23.1, Microsoft Agent Framework 1.0, MCP specification revision 2026-07-28 and the OWASP Top 10 for Agentic Applications 2026.

 

In this guide

• In Plain English: What Is an Agentic Workflow?
• Agentic Workflow Best Practices at a Glance
• Agentic AI Workflow Architecture: Where It Fits in the Pipeline
• Agent Workflow vs Autonomous Agent: Choosing Patterns
• Build the Agent Loop: State, Limits, Durability and Approvals
• Secure Agentic Workflows with OWASP Agentic Top 10 Controls
• Observe, Evaluate and Tune Agents: Tracing, Evals, Cost and Latency
• Common Anti-Patterns in Agentic Workflows
• Production Readiness Checklist for AI Agents
• Glossary in Plain English
• Key Takeaways
• FAQ

What Is an Agentic Workflow?

Tip: what is an agentic workflow? Think of a capable assistant working through a to-do list. The assistant can look things up, use tools and check their own work, while a manager sets a time limit and a budget.

Tip: A human assistant who gets stuck usually notices. Here the “assistant” is software that writes likely-sounding answers, so it can be confidently wrong. That is why it needs checks a human assistant would not.

The assistant repeats one loop: think, do one thing, look at the result, then decide whether to continue, stop or ask a person. The animated diagram below shows this loop, including the step limit and the hand-off to a person.

These are the four terms you need for the rest of the article:

• Agentic workflow: In simple terms, a task where an AI repeats the think, act, check loop until the job is done.
• Agent: In simple terms, the AI part that chooses its own next step.
• LLM: In simple terms, a large language model, the program that reads and writes text.
• Tool call: In simple terms, the AI asking your code to run an action, such as a search or a database lookup.

Why it matters: without limits, state and checks, an agent can loop forever, spend money, or take a wrong action nobody notices.

Workflow or Agent: Who Decides the Steps?

The difference is who picks the path. In a workflow, your code decides the steps and the model fills them in. In an agent, the model decides the steps and the tools to use. This difference drives the agent workflow vs autonomous agent choice covered later.

Agentic Workflow Best Practices at a Glance

The rules below run in order from architecture decisions to day-to-day operations, so you can read the table top to bottom as a design sequence.

Four terms appear in the table. In simple terms, an idempotent call gives the same result when repeated. Least agency means giving an agent only the autonomy and permissions its task needs. Model tiering means using a small, cheap model for easy steps and a larger one for hard steps. A trajectory is the full sequence of steps and tool calls in one run.

Tip: an idempotent action is like a light switch marked “set to ON”. Pressing it twice leaves the light on. A toggle switch is not idempotent, because pressing it twice undoes the first press. This is why a retry is safe for one and risky for the other.

This table shows what to do and what to avoid in each area of an agentic workflow:

Each row is explained with its trade-off in the sections below.

Agentic AI Workflow Architecture: Where It Fits in the Pipeline

The agentic layer sits between retrieval and the user. It calls the knowledge built during ingestion, the tools and the LLM, while evaluation and operations wrap around the whole thing. The animated diagram below shows a document flowing into storage, then a user question driving the agent.

What does each pipeline stage do for the agent?

Each stage prepares something the agent uses at run time. Weak work early in the pipeline shows up later as poor agent decisions.

• Ingestion: loads and cleans source documents.
• Chunking: splits documents into pieces. In simple terms, a chunk is one small passage cut from a longer document.
• Embeddings: turn each chunk into numbers. In simple terms, an embedding is a list of numbers that places a text on a map of meaning.
• Vector store: keeps those embeddings searchable. In simple terms, a vector store is a database that finds texts by meaning instead of exact words.
• Retrieval: fetches the best-matching chunks for a question. In simple terms, retrieval is looking up the most relevant passages before answering.
• LLM: reads the prompt and writes text or picks a tool. It can only use what fits in its context window. In simple terms, the context window is the amount of text the model can read at once.
• Agent or workflow control: decides the next step, enforces limits and stores state.
• Evaluation and operations: record traces, budgets and alerts, and test behaviour.

Retrieval is one tool the agent can call, next to APIs and databases. If it returns the wrong chunks, every later step reasons from bad evidence.

Tip: Think of a research assistant with a library built in advance. The pipeline stocks and indexes the shelves. The agent decides when to visit them, which other tools to use, and when to stop. The analogy stops at one point: the assistant is a language model, so it can misread a good source with confidence.

Which orchestration approach should you choose?

Choose by failure semantics first: what happens on a crash, a timeout or bad tool output. Framework style comes second. The table below compares the four kinds of tooling, with facts dated 2026-10-17.

Pick the least autonomous architecture that meets the task. A short fixed chain does not need a framework. Pin exact versions in production, because LangGraph ships frequent patch releases and the OpenAI SDK is pre-1.0.

Agent Workflow vs Autonomous Agent: Choosing Patterns

Start with a single LLM call plus retrieval and examples. Move to a fixed workflow if that is not enough. Use an autonomous agent only when the steps cannot be known in advance.

Agentic systems usually trade latency and cost for better task performance, so each step up must earn its place. A study of production agents found that 16 of 20 case studies (80%) used predefined structured workflows, chosen for controllability and human oversight.

Tip: A workflow is a recipe card: the steps are written down and the cook follows them. An agent is a chef who decides the next step after tasting the dish. The analogy stops there: the chef here is a language model, so it can be confidently wrong and needs limits and checks.

Which design should you choose?

Apply these decision rules in order:

1. Steps known: use a fixed workflow, where your code decides the order.
2. Path depends on what the model finds: use an agent, but only if the task value justifies the extra cost and latency.
3. Mistake is costly or irreversible: add human approval gates before the risky action.

The animated diagram below walks a new task through these questions.

Which agentic workflow design patterns exist?

In simple terms, an orchestrator is a coordinator that splits a task and hands the parts to workers. This table compares the common agentic workflow design patterns.

When should you split into multiple agents?

Split only when roles need different tools, permissions or context. More agents multiply cost, latency and failure points, because every handoff is another place for a call to fail or for context to be lost. In multi-agent orchestration patterns, one agent with well-scoped tools is the default to beat.

Use Case: A retail returns-triage workflow routes each request to refund, exchange or fraud review. The categories are known, so a router plus fixed branches is enough, and refunds above a set amount wait for human approval.

Use Case: A finance research task uses orchestrator-workers. The orchestrator picks which filings and news to read based on the question, workers summarise each source, and an analyst reviews the draft before it is shared.

Build the Agent Loop: State, Limits, Durability and Approvals

An operable agent loop has an explicit state object (plan, observations, remaining budget), typed tool schemas, a retry policy, a loop limit, a per-step timeout, a cost budget and clear termination outcomes: succeeded, gave up or escalated. The CoreWeave production guide lists these as the minimum for knowing what an agent did and why it stopped. The same pieces are the base of production AI agents checklist items such as limits, retries and approvals.

Tip: Think of a contractor with a work order: a task list, a spending cap, a deadline and a rule to phone the client before any big purchase. The analogy stops at trust. A language model can be confidently wrong, so your code enforces the cap, the deadline and the phone call. It does not rely on the model to respect them.

The animated diagram below shows one pass of the loop, the state card that changes on every pass, and the three ways the loop can end.

Which terms does the loop use?

• Agent state: In simple terms, it is the notebook the agent carries between steps: the goal, the plan, what it has seen and how much budget is left.
• Token: In simple terms, it is a small piece of text (a word or part of a word) that models read and write. Cost is usually counted in tokens.
• Temperature: In simple terms, it is a setting for how adventurous the model’s word choices are. Set it low for tool selection, because you want the same situation to give the same tool and well-formed arguments, not creative variation.
• Idempotency: In simple terms, doing the same action twice has the same effect as doing it once. Reading an order is idempotent. Charging a card is not, unless you send an idempotency key the payment service can recognise.
• Checkpoint: In simple terms, it is a saved copy of the state after a step, like a game save, so a crash resumes instead of restarting.
• Superstep: In simple terms, it is one round of a graph-based framework in which the ready steps run and the state is saved. LangGraph uses this term.

How do you set loop limits and budgets?

The research gives no universal numbers for step limits, timeouts or cost caps, so treat every default as a placeholder to be tuned. Replay a set of real tasks and record the step-count distribution and the cost per successful run. Set the loop limit slightly above a high percentile of successful runs, then review every run that hits it. Those runs show whether the limit is too tight or the agent is genuinely stuck.

How do you make the loop survive failures?

Checkpoint after every step. Retry only idempotent calls, or writes that carry an idempotency key. Classify each error before deciding what to do:

Send exhausted tasks, with their saved state, to a dead-letter queue. In simple terms, that is a holding tray for jobs that failed, kept so a person can inspect and replay them. LangGraph’s graceful shutdown stops a run after the current superstep and saves a resumable checkpoint. Its checkpoint backends are in-memory or SQLite for development and PostgreSQL for production.

How do you add human approval?

For human-in-the-loop AI agents, interrupt before risky tools such as payments, deletes and outbound emails. Show the proposed arguments, then resume on approve or edit. Gate by risk level only, because approval fatigue is real: reviewers who see every action start approving without reading.

Python example: a bounded agent loop

Here’s a simplified example using the standard library and pydantic v2. The call_llm function is a stub you replace, and you can add custom logic for planning, logging and storage.

Python

import time
import uuid
from dataclasses import dataclass, field
from enum import Enum
from typing import Any, Callable

from pydantic import BaseModel, Field, ValidationError


class Outcome(Enum):
    SUCCEEDED = "succeeded"
    GAVE_UP = "gave_up"
    ESCALATED = "escalated"


@dataclass
class AgentState:
    goal: str
    run_id: str = field(default_factory=lambda: uuid.uuid4().hex)
    plan: list[str] = field(default_factory=list)
    observations: list[str] = field(default_factory=list)
    step: int = 0
    tokens_used: int = 0
    cost_usd: float = 0.0
    answer: str | None = None


class Decision(BaseModel):
    action: str  # "tool" or "finish"
    tool: str | None = None
    args: dict[str, Any] = Field(default_factory=dict)
    answer: str | None = None
    tokens: int = 0
    cost_usd: float = 0.0


class RefundArgs(BaseModel):
    order_id: str = Field(pattern=r"^ORD-\d{6}$")
    amount: float = Field(gt=0, le=500)


def issue_refund(args: RefundArgs, idempotency_key: str) -> str:
    # Replace: send idempotency_key to the payment API so a retry cannot pay twice.
    return f"refund of {args.amount} queued for {args.order_id}"


@dataclass
class Tool:
    args_model: type[BaseModel]
    func: Callable[[Any, str], str]
    risky: bool = False
    idempotent: bool = False  # True = read-only, or a write that uses the key


RETRYABLE = (TimeoutError, ConnectionError)


def call_llm(state: AgentState) -> Decision:
    # Stub: call your model here (low temperature) and return a Decision.
    raise NotImplementedError


def call_tool(tool: Tool, args: BaseModel, key: str, retries: int, deadline: float) -> str:
    attempts = retries + 1 if tool.idempotent else 1
    for attempt in range(attempts):
        try:
            return tool.func(args, key)
        except RETRYABLE:
            if attempt == attempts - 1 or time.monotonic() >= deadline:
                raise
            time.sleep(min(0.5 * 2**attempt, 5))
    raise RuntimeError("unreachable")


def run_agent(
    state: AgentState,
    tools: dict[str, Tool],
    approve: Callable[[str, BaseModel], BaseModel | None],
    save_checkpoint: Callable[[AgentState], None],
    *,
    max_steps: int = 8,         # placeholders: tune from replayed real tasks
    max_cost_usd: float = 0.50,
    timeout_s: float = 60.0,
    max_retries: int = 2,
) -> Outcome:
    deadline = time.monotonic() + timeout_s
    while (state.step < max_steps and state.cost_usd < max_cost_usd
           and time.monotonic() < deadline):
        decision = call_llm(state)
        state.step += 1
        state.tokens_used += decision.tokens
        state.cost_usd += decision.cost_usd

        if decision.action == "finish":
            state.answer = decision.answer
            save_checkpoint(state)
            return Outcome.SUCCEEDED

        tool = tools.get(decision.tool or "")
        if tool is None:
            state.observations.append(f"unknown tool: {decision.tool}")
        else:
            try:
                args = tool.args_model.model_validate(decision.args)
            except ValidationError as exc:
                state.observations.append(f"invalid arguments: {exc}")
            else:
                if tool.risky:
                    args = approve(decision.tool, args)  # approve, edit or decline
                    if args is None:
                        save_checkpoint(state)
                        return Outcome.ESCALATED
                key = f"{state.run_id}-{state.step}"  # stable across retries
                try:
                    state.observations.append(
                        call_tool(tool, args, key, max_retries, deadline))
                except PermissionError:
                    save_checkpoint(state)
                    return Outcome.ESCALATED
                except Exception as exc:  # fatal or retries exhausted
                    state.observations.append(f"tool failed: {exc}")
                    save_checkpoint(state)
                    return Outcome.GAVE_UP
        save_checkpoint(state)  # checkpoint after every step

    save_checkpoint(state)  # caller pushes this state to the dead-letter queue
    return Outcome.GAVE_UP

run_agent returns an Outcome (SUCCEEDED, GAVE_UP or ESCALATED) and saves the state before every return, so a person or a replay job can pick up from the last step.

One limit to know: the loop checks the deadline between steps, so each tool function must enforce its own per-step timeout.

How does this map to agent frameworks?

The same loop appears in LangGraph, the OpenAI Agents SDK and Microsoft Agent Framework under different names. Your state object becomes the framework’s state or session, the checkpoint function becomes its persistence layer, and the approval callback becomes an interrupt or approval hook. Check each framework’s documentation for exact signatures. Pin versions, because the OpenAI SDK is still 0.x (0.23.1 on Oct 2, 2026) and LangGraph ships frequent patch releases (1.2.16 on Oct 16, 2026).

Secure Agentic Workflows with OWASP Agentic Top 10 Controls

Apply least agency. An agent gets only the autonomy, tools and credentials the task needs, and it earns more only after evaluation. Use the OWASP Top 10 for Agentic Applications 2026 (released Dec 9, 2025, ASI01 to ASI10) as your review checklist.

Tip: Think of a temp worker given a key card that opens only the rooms needed today, and that stops working tonight. Unlike a human temp, an agent can be tricked by a sentence hidden in a document it reads. So the key card limits matter even more.

Which OWASP agentic risks should you check?

Here are the ten risks in their published order, each with a typical symptom and a control.

In simple terms, a sandbox is a locked room where code can run without touching your real systems.

How do MCP tool servers change the security picture?

As of 2026-10-17, the current MCP revision is 2026-07-28 (the previous final one is 2025-11-25). In simple terms, MCP (Model Context Protocol) is a standard way for agents to discover and call tools on a server.

The new revision is stateless. The initialize handshake and the Mcp-Session-Id header are gone. Each request now carries its protocol version, client identity and capabilities in _meta. The revision also adds Multi Round-Trip Requests, header-based routing, cacheable list results, hardened authorization and an extensions framework.

• Scale freely: servers can sit behind a load balancer without sticky sessions.
• Keep state out of the server: hold per-session data in your agent state, where you can checkpoint and audit it.
• Test before migrating: the C# SDK v2.0 implements this spec, but the Python, TypeScript, Go and C# SDKs are in beta.

Use Case: A healthcare scheduling agent gets a read-only calendar tool to find open slots. A separate booking tool sits behind human approval, which shows the patient, slot and clinician. Its credential is valid only for that task. Every call lands in the audit log.

Observe, Evaluate and Tune Agents: Tracing, Evals, Cost and Latency

Trace every run as one tree, evaluate whole trajectories (the full sequence of steps, not just the final answer), and set your limits and model tiers from that data. This is the core of AI agent observability and guardrails.

How do you trace an agent run?

Record each run as one trace with a span per step. In simple terms, a span is a timed record of one action, and a trace is the tree of spans for one run. OpenTelemetry is an open standard for producing and exporting this data. Its GenAI conventions put an invoke_agent span at the top, with chat spans for model calls and execute_tool spans for tool calls beneath it.

Tip: A trace is like a receipt that lists every task the assistant did, in order, with the time each took. Unlike a receipt, it can also show which step failed and why.

The animated diagram below builds this tree step by step for a refund agent and sends the finished trace to the eval suite and alerts.

Per step, record tokens, cost, latency, retry count and the final termination outcome. Prompt and response content is opt-in, because it can contain personal data. The spec is still marked Development, so attribute names can change. Keep them in one helper.

C#

using System.Diagnostics;

// Simplified helper. Attribute names may change while the GenAI spec is in Development.
public static class AgentTrace
{
    private static readonly ActivitySource Source = new("TheCodeBuzz.Agents");

    public static Task<T> AgentAsync<T>(string agent, Func<Task<T>> body) =>
        Run($"invoke_agent {agent}", "invoke_agent", "gen_ai.agent.name", agent, body);

    public static Task<T> ChatAsync<T>(string model, Func<Task<T>> body) =>
        Run($"chat {model}", "chat", "gen_ai.request.model", model, body);

    public static Task<T> ToolAsync<T>(string tool, Func<Task<T>> body) =>
        Run($"execute_tool {tool}", "execute_tool", "gen_ai.tool.name", tool, body);

    public static void RecordUsage(int inputTokens, int outputTokens)
    {
        Activity.Current?.SetTag("gen_ai.usage.input_tokens", inputTokens);
        Activity.Current?.SetTag("gen_ai.usage.output_tokens", outputTokens);
    }

    private static async Task<T> Run<T>(string name, string operation,
        string key, string value, Func<Task<T>> body)
    {
        using var activity = Source.StartActivity(name);
        activity?.SetTag("gen_ai.operation.name", operation);
        activity?.SetTag(key, value);
        try
        {
            return await body();
        }
        catch (Exception ex)
        {
            activity?.SetStatus(ActivityStatusCode.Error, ex.Message);
            activity?.SetTag("error.type", ex.GetType().FullName);
            throw;
        }
    }
}

Nested calls become child spans automatically, because Activity.Current flows through async code. Register the source with AddSource("TheCodeBuzz.Agents") in OpenTelemetry for .NET, otherwise StartActivity returns null and nothing is exported.

How do you evaluate an agent?

Build a regression suite from real tasks and score the trajectory, not only the answer. A trajectory evaluation checks the path the agent took. A regression suite is a fixed set of tests you rerun after every change.

• Trajectory checks: right tool, right arguments, no forbidden calls, step count and cost.
• Answer quality: score the final output separately.
• Rerun on any change: prompt, tool schema or model, because they interact.
• Adversarial cases: include prompt injection hidden in tool output.
• Two environments: keep offline evals apart from sampled production evals.

How do you control cost and latency?

Pick the controls below and check each against your eval suite. Every one trades something for speed or savings.

To tune tiers, plot cost per successful task against success rate for each tier. Choose the knee of the curve, where extra spend stops buying much accuracy.

Which alerts should you set?

Alert on loop-limit hits, escalation rate, cost per run and tool error rate. Review every run that hits a limit, since that shows whether the limit or the task design is wrong. These signals also belong on any production AI agents checklist.

Common Anti-Patterns in Agentic Workflows

Most failures in production AI agents come from a small set of repeated design mistakes. The table below lists nine of them with the symptom you will see and the fix.

Tip: An anti-pattern is a habit that looks sensible at first and causes trouble later, like a manager who gives a new assistant the master key, no deadline and no instructions to report back. The analogy stops at one point: a human assistant would usually push back, while a language model will keep going.

Which Agentic Workflow Mistakes Should You Avoid?

Use this table as a review list for agentic AI workflow architecture and for any production AI agents checklist.

For multi-agent orchestration patterns, human-in-the-loop AI agents and AI agent observability and guardrails, see the sections that cover each in detail.

Production Readiness Checklist for AI Agents

Use this production AI agents checklist before you release an agent to real users. It runs from design to operations. Every item can be verified with a test, a config value or a dashboard.

Tip: Think of the pre-flight checklist a pilot runs before takeoff. Each line is a quick, checkable fact, not an opinion. The analogy stops in one place: an agent’s checklist must be run again whenever the prompt, a tool or the model changes.

Work through these items in order:

1. Architecture choice: Write down why a single LLM call or fixed workflow is not enough. If you can’t, don’t build an agent.
2. Outcomes: Define succeeded, gave up and escalated, plus the conditions that end a run.
3. Tools: Give every tool a typed schema. Validate arguments before the tool runs.
4. State: Keep an explicit state object and checkpoint after every step.
5. Limits: Set step, time and cost limits from replayed eval data, not guesses.
6. Retries: Retry only idempotent calls. Send exhausted tasks to a dead-letter queue with their saved state.
7. Approvals: Add human-in-the-loop AI agent gates on payments, deletes and outbound messages.
8. Least agency: Use short-lived, task-scoped credentials and sandboxed code, mapped to each OWASP agentic risk.
9. Tracing: Trace each run as one tree. Keep prompt and response capture off by default.
10. Regression suite: Run trajectory evals in CI on every prompt, schema or model change, including prompt injection cases that arrive through tool output.
11. Versions: Pin dependencies and record the MCP spec version you tested against.
12. Operations: Set alerts for loop-limit hits, escalation rate, cost per run and tool errors. Rehearse the kill switch and the rollback plan before you need them.

Glossary in Plain English

This glossary lists the terms used in this article on agentic AI workflow architecture, grouped by topic. Each analogy comes with a note where it stops being accurate.

In plain English: Treat the analogies as a phrasebook, not a specification. They help you picture an idea, and the third column says where each picture stops matching the real thing.

Models and Cost Terms

These terms describe the model and what it costs to run.

Knowledge and Retrieval Terms

These terms cover how knowledge gets to the agent.

Loop and Reliability Terms

These terms describe how the loop keeps running and recovers from failure.

Security and Observability Terms

These terms cover protection, monitoring and testing.

Key Takeaways

These are the points to keep from the article, ordered from design decisions to operations.

• Start with the simplest design: try a single LLM call with retrieval and examples first, then a fixed workflow. Use an autonomous agent only when the steps cannot be known in advance, because agents usually cost more in latency and money.
• Workflows dominate production: in the study cited earlier, 16 of 20 case studies (80%) used predefined structured workflows for control and human oversight. If code can decide the steps, let code decide them.
• Make the loop explicit and bounded: keep an explicit state object, typed and validated tool schemas, and limits for steps, time and cost. Return a clear outcome (succeeded, gave up or escalated). Set the limits from replayed real tasks, not from a universal number.
• Design for crashes and retries: checkpoint after every step, retry only idempotent calls (or use idempotency keys for writes), and send exhausted tasks to a dead-letter queue with the saved state. Choose tooling by failure semantics before framework style.
• Apply least agency and the OWASP list: give agents short-lived, task-scoped credentials and scoped tools. Treat retrieved content and tool output as untrusted data, sandbox code execution, and gate risky actions by risk level. Keep a kill switch and audit logs.
• Trace and evaluate trajectories: record each run as one trace tree and score the tools, arguments, step count and cost, not only the final answer. Re-run the regression suite whenever the prompt, tool schema or model changes.
• Pin versions and re-check dated facts: LangGraph patch releases are frequent, the OpenAI Agents SDK is still 0.x, and the OpenTelemetry GenAI conventions are still in Development. Record the MCP spec revision you target, and re-verify the version facts dated 2026-10-17 before you rely on them.

That’s all! Happy coding!

Did this solve your problem? Please share your questions or experience in the comments below. Bookmark this page or share it with your team, and subscribe to TheCodeBuzz for more AI engineering best practices.

FAQ

What is an agentic workflow and how is it different from an AI agent?

An agentic workflow is a process where code sets the steps and a language model does the work inside them (e.g. classify, look up, draft). An AI agent is different because the model itself decides which step or tool comes next. Most production systems use workflows for this reason, since a fixed path is easier to test, limit and audit. Many real systems mix both, with a fixed outer flow and one agent loop for a single open-ended step.

When should I use a fixed workflow instead of an autonomous agent?

Use a fixed workflow whenever you can write down the steps before the task starts. Start with a single model call plus retrieval and examples, move to a workflow if that is not enough, and use an agent only when the path depends on what the model finds along the way. Agents usually cost more and respond more slowly, so the task value must justify that. If a wrong action is expensive, add an approval gate whichever design you pick.

How do I control cost and latency in an agent loop?

Set hard limits first: a maximum step count, a per-step timeout, a deadline and a token or cost budget per run. Then reduce spend with model tiering (a small model for routing and extraction, a larger one for hard planning), caching of stable prompt prefixes, summarising old steps, and parallel calls for independent tools. Summarising can drop detail, so check it against your regression suite. Tune the numbers from real traces by comparing cost per successful task with success rate for each tier.

How do I add human-in-the-loop approval to an agent?

Pause the loop before any risky tool call, such as a payment, a delete or an outbound email, and show the reviewer the exact proposed arguments. Save the agent state at that point so the run can resume after the person approves, edits or rejects the action. Frameworks such as LangGraph offer interrupts for this, and the same idea works in plain code with an approval callback. Gate by risk level only, because asking for approval on every step leads to reviewers clicking through without reading.

What are the biggest security risks for agentic applications, and how do I reduce them?

The OWASP Top 10 for Agentic Applications 2026 is the best checklist, and its risks include agent goal hijack, tool misuse, identity and privilege abuse, and memory and context poisoning. The guiding rule is least agency: give the agent only the autonomy and access it has earned. In practice, use short-lived credentials scoped to the task, validate tool parameters, run generated code in a sandbox, and treat retrieved content and tool output as untrusted data, never as instructions. Add approval for sensitive actions, audit logs and a kill switch.

Sources and further reading

• Building Effective AI Agents (Anthropic Engineering)
• Measuring Agents in Production (arXiv)
• Agentic workflows in production: Mechanisms, costs and trade-offs (CoreWeave)
• OWASP Top 10 for Agentic Applications – The Benchmark for Agentic Security in the Age of Autonomous AI (OWASP Gen AI Security Project)
• Lessons from OWASP Top 10 for Agentic Applications (Auth0)
• langgraph · PyPI (PyPI)
• LangGraph 1.0 and 1.2 in 2026: Why Durable State Has Changed Everything for Python Agent Developers (JBI Training)
• Releases · openai/openai-agents-python (GitHub (OpenAI))
• Changelog (OpenAI)
• Microsoft Ships Production-Ready Agent Framework 1.0 for .NET and Python (Visual Studio Magazine)

Please share this article with your friends and Subscribe to the blog to get a notification on freshly published best practices of software development.

The post Agentic Workflow Best Practices: Architecture and Checklist first appeared on TheCodeBuzz.

It is different from the existing post, SQL Server Best Practices for Developers and DBAs (2026 Guide). This one is organised by production concern: configuration, indexing and queries, transactions, drivers, security, backups, monitoring and upgrades. Each rule explains the why, states the trade-off and gives a command to verify the result. The guide ends with an anti-patterns table and a production readiness checklist.

Before you start, you need sysadmin access on a test instance and SSMS or sqlcmd. The .NET examples use Microsoft.Data.SqlClient and the Python examples use pyodbc. Support dates, build numbers and default behaviours are correct as of October 2026. Always test every change on a non-production copy first.

Version note: This guide targets SQL Server 2022 (latest CU27, 16.0.4295.3) and SQL Server 2025 (latest CU9, 17.0.5005.3), with Microsoft.Data.SqlClient v7.0.1.

 

In this guide

• SQL Server Best Practices at a Glance
• SQL Server Configuration Best Practices: Memory, MAXDOP, Cost Threshold and tempdb
• Data Modeling and Indexing Best Practices
• Query Optimization and SQL Server Performance Tuning Best Practices
• Transactions, Isolation Levels and Optimized Locking
• Connection Management and Microsoft.Data.SqlClient Best Practices
• SQL Server Security Best Practices: Least Privilege, Injection and Encryption
• SQL Server Backup Best Practices, High Availability and Restore Testing
• Monitoring SQL Server: Wait Stats, Extended Events and Performance Counters
• Patching and Upgrading to SQL Server 2025: What to Check First
• Common Anti-Patterns and SQL Server DBA Production Readiness Checklist
• Key takeaways
• FAQ

SQL Server Best Practices at a Glance

This guide covers production best practices for SQL Server 2022 and SQL Server 2025, from instance configuration and indexing to security, backups, monitoring and upgrades.

The table below is a quick reference for developers, architects and DBAs. Each rule points to the section that explains the reason, so you can jump to the detail when you need it.

Quick Reference Table

How to Read This Guide

Treat every rule as a default, not a law. Where a rule does not apply, the section states the trade-off and the case where you should do something different.

Test each change on a non-production copy and measure before and after.

SQL Server Configuration Best Practices: Memory, MAXDOP, Cost Threshold and tempdb

These instance-level settings decide how SQL Server uses memory, CPU and temporary storage. Most of them ship with defaults that suit a demo machine, not a production server, so review them on every new install, on 2022 and on 2025.

SQL Server Max Server Memory Setting

Cap max server memory on every version. The default is about 2 TB, which means SQL Server will take whatever it can and leave the OS and other processes to fight for the rest.

Current Microsoft docs suggest a starting point of about 75% of the available memory not used by other processes, including other instances on the same host. Leave min server memory at 0. Setup on Windows has suggested a value since SQL Server 2019, so check what it picked.

The older advice was to leave 4-6 GB, or 10-15%, for the OS. A percentage of what is actually available is a better baseline because it already subtracts a second instance, an SSIS service, antivirus or a monitoring agent. A fixed reserve ignores all of them.

If Lock Pages in Memory (LPIM) is granted to the service account, set a specific value. LPIM stops Windows from trimming SQL Server’s memory, so a wrong cap can starve the OS.

MAXDOP: Why OLTP Does Not Automatically Mean MAXDOP

MAXDOP (maximum degree of parallelism) is the number of CPUs one query can use. Some teams say “OLTP means MAXDOP 1”, while Microsoft publishes a NUMA-based rule. They conflict because the first is a workaround for parallelism waits and the second is a general default.

Start from the Microsoft guidance. A NUMA node (Non-Uniform Memory Access node) is a group of processors that share local memory. Keeping a query inside one node avoids slower cross-node memory access. The table below shows the starting values.

For example, a server with two NUMA nodes of 24 logical processors each would start at 12. A server with two nodes of 40 logical processors each would start at 16, because half of 40 is 20 and the cap is 16.

• Mixed workloads: Use ALTER DATABASE SCOPED CONFIGURATION SET MAXDOP so each database gets its own limit.
• One workload that needs a different limit: Create a Resource Governor workload group with its own MAX_DOP.
• MAXDOP 1 server-wide: Avoid it. Parallel index builds and reporting queries lose parallelism, and maintenance windows get longer.

Cost Threshold for Parallelism and Optimize for Ad Hoc Workloads

The default cost threshold for parallelism is 5, which is too low for modern hardware. Small queries go parallel and waste threads on coordination.

Raise it based on observed plan costs. A value in the 25 to 50 range is a reasonable test value, not a rule. After the change, compare CXPACKET and CXCONSUMER waits before and after, and check that your important queries did not slow down.

Enable optimize for ad hoc workloads when the plan cache fills with single-use plans, e.g. an ORM that sends unparameterized text. On first run SQL Server stores only a small plan stub, and the full plan is cached on the second run. The trade-off is one extra compile for queries that do repeat.

tempdb Configuration

Use several data files of equal size, pre-sized, with a fixed growth increment, on fast storage. Autogrow should be an emergency only, not the sizing method.

Many sessions create temporary objects at once, and they all compete for the allocation pages (PFS, GAM, SGAM) in a single file. That shows up as PAGELATCH waits. More files spread the allocations. SQL Server fills files in proportion to free space, so unequal sizes send most of the work to one file.

Use this rule for the file count, which follows Microsoft guidance:

1. If the server has 8 or fewer logical processors, create one data file per logical processor (e.g. 4 logical processors, 4 files).
2. If the server has more than 8 logical processors, start with 8 data files.
3. If PAGELATCH contention on tempdb allocation pages continues with 8 files, add files in multiples of 4, and stop when the contention goes away.

More files than needed do not help and add some overhead, so do not match the core count on a large server.

SQL Server 2025 Additions

• tempdb space governance: Resource Governor can limit tempdb space per workload group. A workload that exceeds its limit is stopped with an error.
• Accelerated Database Recovery in tempdb: Now supported.
• Resource Governor in Standard edition: It has the same functionality as Enterprise. Standard 2025 is limited to the lesser of 4 sockets or 32 cores, and 256 GB of buffer pool per instance.

Storage and OS Settings

Separate data, log and tempdb volumes where your storage design allows it. Put the log on fast storage or RAID 10, because log writes are sequential and every commit waits for them (WRITELOG).

Enable instant file initialization (IFI) by granting the “Perform volume maintenance tasks” privilege to the SQL Server service account. With IFI, data file growth and restores skip zeroing the new space, so they finish much faster.

Log files are different, and the behavior depends on the version. In SQL Server 2019 and earlier, log files are always zero-initialized. In SQL Server 2022 and later, transaction log growth events of up to 64 MB can also use IFI. Larger log growths, and the initial creation of a log file, are still zeroed.

For the versions this guide targets, set the log autogrowth increment to 64 MB or less so that emergency growths are fast. Still pre-size the log to its working size, because a log that grows often creates many virtual log files and slows recovery.

Sample Configuration Script

The example below assumes one instance on a 32 GB server, so 75% is 24576 MB. It also assumes a single NUMA node with 16 logical processors. By the Microsoft rule, a single node with more than 8 logical processors gets MAXDOP 8, and the same layout gives 8 tempdb data files. Adjust all values for your own hardware.

T-SQL

EXEC sp_configure 'show advanced options', 1;
RECONFIGURE;

EXEC sp_configure 'max server memory (MB)', 24576;
EXEC sp_configure 'cost threshold for parallelism', 50;
EXEC sp_configure 'optimize for ad hoc workloads', 1;
RECONFIGURE;

-- Run in the user database that needs its own limit.
-- 8 = single NUMA node with 16 logical processors (more than 8, so cap at 8).
ALTER DATABASE SCOPED CONFIGURATION SET MAXDOP = 8;

-- Verify the instance settings
SELECT name, value, value_in_use
FROM sys.configurations
WHERE name IN ('max server memory (MB)',
               'min server memory (MB)',
               'cost threshold for parallelism',
               'optimize for ad hoc workloads');

-- Check the NUMA layout and logical processor count used for MAXDOP and tempdb sizing
SELECT cpu_count FROM sys.dm_os_sys_info;

SELECT node_id, online_scheduler_count
FROM sys.dm_os_nodes
WHERE node_state_desc = N'ONLINE';

-- Check tempdb file layout (expect 8 data files on this 16-processor server)
SELECT name, physical_name,
       size * 8 / 1024 AS size_mb,
       growth, is_percent_growth
FROM sys.master_files
WHERE database_id = 2;

Run the NUMA queries first and change MAXDOP if your layout differs. The last query should show equal size_mb values, a fixed growth in MB and is_percent_growth set to 0 for every data file.

Data Modeling and Indexing Best Practices

Good SQL Server performance starts with the table design, not the server settings. Model the data cleanly, choose small data types, and add only the indexes your queries use. These rules apply to both SQL Server 2022 and 2025.

Model to Third Normal Form First

Start with third normal form (3NF), where each non-key column depends only on the key. Denormalize only when a measured query problem justifies it.

Normalized tables avoid update anomalies, because a customer address lives in one row and not in every order. Rows stay smaller, so more rows fit on a page. Updates touch fewer rows, which means fewer locks.

Use the Narrowest Correct Data Type and Add Constraints

Pick the smallest type that safely holds the data. The clustered index key is carried into every nonclustered index as the row locator, so a wide clustered key makes every nonclustered index larger. Wide columns in any index key also add to index size, buffer pool memory and I/O.

• int vs bigint: Use int unless you expect more than about 2.1 billion rows.
• date vs datetime2: Use date when no time is needed, and datetime2(0) for second precision.
• Strings: Avoid nvarchar(max) for short values. Use a sized type such as nvarchar(100).

Declare primary key, foreign key, unique and check constraints. The optimizer uses them to build better plans, and they reject bad data at the source, before it reaches the application.

Choose a Narrow, Ever-Increasing Clustered Key

Give every table a clustered index on a narrow, unique, ever-increasing key, such as an int IDENTITY column. New rows are appended at the end of the table, and the small key is copied into each nonclustered index.

A random GUID from NEWID() inserts rows at random positions, which causes page splits and fragmentation. A GUID is also 16 bytes, which makes it a wide clustered key. If you need GUIDs, use NEWSEQUENTIALID() as a column default, or keep an identity column as the clustered key and the GUID as a separate unique column.

Design Nonclustered Indexes for Your Queries

Index the columns used in WHERE, JOIN and ORDER BY. Put equality columns first and the range column after them. Use INCLUDE for columns that are only selected, so the index covers the query without key lookups.

Example: a retail site lists one customer’s recent orders, filtering on CustomerId (equality) and OrderDate (range).

T-SQL

CREATE TABLE dbo.Orders
(
    OrderId     int IDENTITY(1,1) NOT NULL,
    CustomerId  int NOT NULL,
    OrderDate   datetime2(0) NOT NULL,
    Status      tinyint NOT NULL,
    TotalAmount decimal(10,2) NOT NULL,
    CONSTRAINT PK_Orders PRIMARY KEY CLUSTERED (OrderId),
    CONSTRAINT FK_Orders_Customers FOREIGN KEY (CustomerId)
        REFERENCES dbo.Customers (CustomerId),
    CONSTRAINT CK_Orders_TotalAmount CHECK (TotalAmount >= 0)
);

CREATE NONCLUSTERED INDEX IX_Orders_Customer_Date
ON dbo.Orders (CustomerId, OrderDate)
INCLUDE (Status, TotalAmount);

This creates a narrow clustered key, a foreign key, a check constraint and a covering index for the customer-orders query.

Remove Duplicate and Unused Indexes

Every index slows inserts, updates and deletes and uses storage. Check sys.dm_db_index_usage_stats to find indexes that are written to but never read.

T-SQL

SELECT OBJECT_SCHEMA_NAME(i.object_id) AS SchemaName,
       OBJECT_NAME(i.object_id)        AS TableName,
       i.name                          AS IndexName,
       ISNULL(s.user_seeks, 0)   AS UserSeeks,
       ISNULL(s.user_scans, 0)   AS UserScans,
       ISNULL(s.user_lookups, 0) AS UserLookups,
       ISNULL(s.user_updates, 0) AS UserUpdates
FROM sys.indexes AS i
LEFT JOIN sys.dm_db_index_usage_stats AS s
       ON s.object_id = i.object_id
      AND s.index_id = i.index_id
      AND s.database_id = DB_ID()
WHERE i.type_desc = 'NONCLUSTERED'
  AND i.is_primary_key = 0
  AND i.is_unique_constraint = 0
  AND OBJECTPROPERTY(i.object_id, 'IsUserTable') = 1
  AND ISNULL(s.user_seeks, 0) + ISNULL(s.user_scans, 0) + ISNULL(s.user_lookups, 0) = 0
ORDER BY UserUpdates DESC;

This lists nonclustered indexes with no reads, sorted by write cost. The usage counters reset when the instance restarts, so observe a full business cycle (e.g. a month-end close) before dropping anything.

Maintain Statistics First, Fragmentation Second

Update statistics regularly, because the optimizer chooses plans from them. Stale statistics cause bad row estimates and bad plans.

For fragmentation, act on a threshold and not on a blanket schedule. Measure it with sys.dm_db_index_physical_stats, then pick an action from the table below. These numbers are starting points only, so adjust them after you see how your own workload and storage respond.

Ignore small indexes, for example those under about 1,000 pages, because their fragmentation figures are not meaningful and rarely affect performance. Fragmentation matters less on SSD storage, but statistics matter just as much.

SQL Server 2025 Vector Data

The vector data type is generally available in SQL Server 2025. DiskANN vector indexes are still preview only, need the PREVIEW_FEATURES database scoped configuration, and are not recommended for production yet.

Query Optimization and SQL Server Performance Tuning Best Practices

Most SQL Server performance tuning comes down to a few habits: write predicates the optimizer can seek on, return only the data you need, reuse plans, and watch for plan regressions with Query Store.

Write SARGable Predicates

A SARGable predicate (Search ARGument able) lets the engine use an index seek. Wrapping an indexed column in a function forces a scan, because the function must run on every row.

SQL

-- Bad: function on the column, index on OrderDate cannot be used for a seek
SELECT OrderId, TotalAmount
FROM dbo.Orders
WHERE YEAR(OrderDate) = 2026;

-- Good: range on the bare column, index seek is possible
SELECT OrderId, TotalAmount
FROM dbo.Orders
WHERE OrderDate >= '20260101'
  AND OrderDate <  '20270101';

The rewritten query returns the same rows and reads only the matching index range.

Return Less Data, Use Fewer Round Trips

• Select only needed columns: Avoid SELECT *. It reads and sends extra data, and it stops narrow covering indexes from being used.
• SET NOCOUNT ON: Add it at the top of procedures to stop the “rows affected” message after every statement.
• Set-based code: Use one UPDATE ... JOIN instead of a cursor. A cursor processes one row at a time, which costs more CPU and more statements.

Example: a retail nightly job that updates stock for 200,000 products should run one set-based statement, not a loop that fires 200,000 updates.

Handle Parameter Sniffing

Parameterized queries and stored procedures let SQL Server reuse plans. Parameter sniffing means the plan is built for the first parameter value it sees, which can be a poor fit for later values.

On 2022 and later, PSP optimization is the first thing to try when you are on compatibility level 160. It lets one parameterized statement keep more than one plan for different parameter ranges. If it does not cover your query, move down the table.

Use Query Store

Query Store records queries, plans and runtime statistics inside the database. From SQL Server 2022, it is ON by default for new databases. The “enable it” step therefore mostly applies to databases that were upgraded or restored from an older instance, because they keep their earlier setting.

Check which databases still have it off, and turn it on for the ones you care about. Use QUERY_CAPTURE_MODE = AUTO so trivial queries do not fill the store.

SQL

SELECT name, is_query_store_on
FROM sys.databases
WHERE database_id > 4;

This lists user databases and shows whether Query Store is on for each one.

On readable secondary replicas, the defaults differ by version. In SQL Server 2025, Query Store on readable secondaries is on by default. In SQL Server 2022 it was off and needed trace flag 12606.

SQL

ALTER DATABASE SalesDb SET QUERY_STORE = ON
(
    OPERATION_MODE = READ_WRITE,
    QUERY_CAPTURE_MODE = AUTO,
    MAX_STORAGE_SIZE_MB = 1024,
    INTERVAL_LENGTH_MINUTES = 60,
    SIZE_BASED_CLEANUP_MODE = AUTO
);

The sizes above are example values. Adjust them to your workload.

SQL

SELECT TOP (10)
    q.query_id,
    LEFT(qt.query_sql_text, 200) AS query_text,
    SUM(rs.count_executions * rs.avg_duration) / 1000.0 AS total_duration_ms
FROM sys.query_store_query AS q
JOIN sys.query_store_query_text AS qt ON qt.query_text_id = q.query_text_id
JOIN sys.query_store_plan AS p ON p.query_id = q.query_id
JOIN sys.query_store_runtime_stats AS rs ON rs.plan_id = p.plan_id
GROUP BY q.query_id, qt.query_sql_text
ORDER BY total_duration_ms DESC;

This lists the ten queries that consumed the most total time. Durations are stored in microseconds, so the query divides by 1000.

SQL

EXEC sys.sp_query_store_force_plan @query_id = 42, @plan_id = 17;

-- Remove the forced plan when it is no longer needed
EXEC sys.sp_query_store_unforce_plan @query_id = 42, @plan_id = 17;

Replace the IDs with values from the previous query and the Query Store reports.

Test Feedback Features and Compatibility Levels

The optimizer can adjust some settings for a query after it has run, using what it saw on earlier executions. Two feedback features matter most, and each needs a minimum compatibility level.

• Memory grant feedback: Resizes the memory granted to a query when earlier runs got too much or too little, which reduces tempdb spills and wasted memory. Batch mode needs compatibility level 140 or higher. Row mode needs 150 or higher. In SQL Server 2022, the percentile and persisted versions of this feedback need Query Store to be on and in read-write mode.
• DOP feedback: Lowers the degree of parallelism (DOP, the number of threads a query uses) for parallel queries that do not benefit from it. It is available in SQL Server 2022 and later, needs compatibility level 160 or higher, and needs Query Store in read-write mode. In 2022, check that the DOP_FEEDBACK database scoped configuration is on for the database.

Raise the compatibility level on a copy of the database first, compare plans, and force the old plan where a regression appears. Check the Microsoft documentation for the exact compatibility level that matches your SQL Server version before you change it.

Read Execution Plans

1. Estimated vs actual rows: Large gaps usually mean stale statistics or a poor cardinality estimate.
2. Spills to tempdb: A sort or hash warning means the memory grant was too small.
3. Key lookups: Many lookups suggest the index needs an INCLUDE column.
4. Implicit conversions: A parameter type that differs from the column type (e.g. nvarchar against varchar) can block an index seek.

Transactions, Isolation Levels and Optimized Locking

Keep transactions short, touch tables in the same order everywhere, and use row versioning (Read Committed Snapshot Isolation, or RCSI) for read-heavy OLTP so readers don’t block writers. These habits are part of SQL Server performance tuning best practices because blocking often looks like a slow query.

Isolation Levels Compared

RCSI Trade-offs

RCSI makes a SELECT read the last committed version of a row instead of waiting for a lock. The cost is extra version storage, normally in tempdb. With Accelerated Database Recovery (ADR), the version store lives in the user database (the persistent version store, PVS).

Behaviour also changes. Code that relied on a blocking read to wait for a writer, such as a “read then update” pattern, now sees the old value. Test this in a copy of the database first.

Optimized Locking in SQL Server 2025

SQL Server 2025 adds optimized locking, which uses transaction ID (TID) locking and lock after qualification (LAQ). A TID lock replaces many row locks, and LAQ takes locks only on the rows that match the predicate. This reduces blocking and lock memory use, avoids lock escalation, and needs no application code change. It is a good reason to test 2025 with write-heavy workloads.

Optimized locking is not on by default for every database. It requires Accelerated Database Recovery (ADR) to be enabled on the database, so turn on ADR first and check the result in sys.databases. Confirm the exact database-level setting for optimized locking in the Microsoft documentation for your build.

T-SQL

-- Prerequisite for optimized locking: ADR on the database.
-- Test first and run in a quiet window.
ALTER DATABASE BankDb SET ACCELERATED_DATABASE_RECOVERY = ON;
GO

SELECT name, is_accelerated_database_recovery_on
FROM sys.databases
WHERE name = N'BankDb';

This enables ADR and confirms it with a check of is_accelerated_database_recovery_on.

RCSI and optimized locking address different parts of the blocking problem, so measure them with and without RCSI on your own workload instead of assuming the combination is better. The animated diagram below compares classic locking with optimized locking plus RCSI for two sessions on the same table.

Deadlocks and Retries

When SQL Server picks your session as a deadlock victim, it returns error 1205. Retry in application code with a bounded count (e.g. three attempts) and a short backoff. To see the cause, read the deadlock graph from the system_health Extended Events session.

Finance Transfer Example

Move money in one short transaction. Validate the inputs first, then update the two accounts with two separate statements, lowest ID first. Because every transfer takes the locks in the same order, two opposite transfers (A to B and B to A) can’t deadlock on these two rows.

The balance check sits inside the debit UPDATE‘s WHERE clause. The row is locked when the check runs, so it sees the current balance. A separate SELECT before the update could read an older row version under RCSI.

T-SQL

-- Enable RCSI (rolls back open transactions, so run in a quiet window)
ALTER DATABASE BankDb SET READ_COMMITTED_SNAPSHOT ON WITH ROLLBACK IMMEDIATE;
GO

CREATE OR ALTER PROCEDURE dbo.TransferFunds
    @FromId int, @ToId int, @Amount decimal(19,4)
AS
BEGIN
    SET NOCOUNT ON;
    SET XACT_ABORT ON;

    -- Validate inputs before opening a transaction
    IF @Amount IS NULL OR @Amount <= 0
        THROW 50001, 'Amount must be greater than zero.', 1;
    IF @FromId IS NULL OR @ToId IS NULL OR @FromId = @ToId
        THROW 50002, 'Source and target accounts must be different.', 1;

    -- Work out the lock order: lowest AccountId first
    DECLARE @LowId  int = CASE WHEN @FromId < @ToId THEN @FromId ELSE @ToId END;
    DECLARE @HighId int = CASE WHEN @FromId < @ToId THEN @ToId ELSE @FromId END;

    -- Signed change for each account: negative for the debit, positive for the credit
    DECLARE @LowDelta  decimal(19,4) = CASE WHEN @LowId  = @FromId THEN -@Amount ELSE @Amount END;
    DECLARE @HighDelta decimal(19,4) = CASE WHEN @HighId = @FromId THEN -@Amount ELSE @Amount END;

    BEGIN TRY
        BEGIN TRANSACTION;

        UPDATE dbo.Accounts
           SET Balance = Balance + @LowDelta
         WHERE AccountId = @LowId
           AND (@LowDelta > 0 OR Balance >= @Amount);
        IF @@ROWCOUNT = 0
            THROW 50003, 'Account not found or insufficient funds.', 1;

        UPDATE dbo.Accounts
           SET Balance = Balance + @HighDelta
         WHERE AccountId = @HighId
           AND (@HighDelta > 0 OR Balance >= @Amount);
        IF @@ROWCOUNT = 0
            THROW 50003, 'Account not found or insufficient funds.', 1;

        COMMIT TRANSACTION;
    END TRY
    BEGIN CATCH
        IF @@TRANCOUNT > 0 ROLLBACK TRANSACTION;
        THROW;
    END CATCH
END;

The procedure rejects zero, negative and NULL amounts, and it rejects a transfer from an account to itself. If either update finds no row to change, the transaction rolls back, so a failed debit never leaves a half-finished credit behind. XACT_ABORT ON also rolls back the whole transaction on any runtime error.

The fixed order only protects code that follows it. Any other procedure that updates the same accounts in a different order, or a trigger that touches other rows, can still deadlock with this one. Keep the retry logic for error 1205 in place.

Connection Management and Microsoft.Data.SqlClient Best Practices

Use Microsoft.Data.SqlClient (v7.0.1 is shown in the current API docs) and keep the defaults Encrypt=Mandatory and TrustServerCertificate=false. When an app starts failing with certificate errors after a driver upgrade, the driver is not broken. The client simply does not trust the server certificate. Fix the certificate chain or the host name instead of switching on TrustServerCertificate. This is one of the most useful SQL Server best practices for developers.

The animated diagram below shows how the client decides whether a connection succeeds and which fix to choose.

Encrypt Options Compared

Encrypt=Strict uses TDS 8.0 and cannot be bypassed with TrustServerCertificate. Use it when your server supports TDS 8.0. Avoid TrustServerCertificate=true in production, because it skips the server identity check.

Connection Pooling Rules

• Open late, close early: Use using or await using so the connection returns to the pool even when an exception occurs.
• One connection per thread: A SqlConnection is not thread-safe, so never share it.
• Keep connection strings identical: Each distinct string creates its own pool. Per-request values (e.g. a user name in the string) fragment the pool.
• Watch Max Pool Size: The default is 100. Pool exhaustion shows up as “timeout period elapsed prior to obtaining a connection from the pool”. The usual cause is a leaked connection, so look for missing disposal before raising the limit.

Availability Groups and Read-Only Routing

Connect to the availability group listener name, never a node name. Add MultiSubnetFailover=True when the listener spans subnets, so the client tries all IP addresses in parallel. Add ApplicationIntent=ReadOnly for reporting workloads that should use read-only routing.

C# Example: Strict Encryption and a Typed Parameter

Example: a retail app looks up orders for one customer. The parameter has an explicit type and size, which avoids implicit conversions and plan cache bloat.

C# (.NET)

using System.Data;
using Microsoft.Data.SqlClient;

var builder = new SqlConnectionStringBuilder
{
    DataSource = "orders-listener.contoso.com",
    InitialCatalog = "Sales",
    IntegratedSecurity = true,
    Encrypt = SqlConnectionEncryptOption.Strict,
    MultiSubnetFailover = true,
    ApplicationIntent = ApplicationIntent.ReadWrite,
    MaxPoolSize = 100
};

await using var connection = new SqlConnection(builder.ConnectionString);
await connection.OpenAsync();

await using var command = new SqlCommand(
    "SELECT OrderId, OrderDate FROM dbo.Orders WHERE CustomerRef = @CustomerRef;",
    connection);
command.Parameters.Add("@CustomerRef", SqlDbType.VarChar, 20).Value = "C-10045";

await using var reader = await command.ExecuteReaderAsync();
while (await reader.ReadAsync())
{
    Console.WriteLine($"{reader.GetInt32(0)} {reader.GetDateTime(1):d}");
}

This opens a strict, encrypted connection and returns it to the pool when the block ends.

For transient errors, the driver offers configurable retry logic (SqlRetryLogicOptions with SqlConfigurableRetryFactory). Assign a provider to the connection or command, and keep the retry count and delay bounded.

Python Equivalent with pyodbc

Use the ODBC Driver for SQL Server, set Encrypt=yes and TrustServerCertificate=no, and pass values through ? placeholders. Match the driver name to the one installed on your machine.

Python

import os
import pyodbc

conn_str = (
    "DRIVER={ODBC Driver 18 for SQL Server};"
    "SERVER=orders-listener.contoso.com;"
    "DATABASE=Sales;"
    f"UID={os.environ['SQL_USER']};PWD={os.environ['SQL_PASSWORD']};"
    "Encrypt=yes;TrustServerCertificate=no;"
    "MultiSubnetFailover=Yes;"
)

with pyodbc.connect(conn_str) as conn:
    cursor = conn.cursor()
    cursor.execute(
        "SELECT OrderId, OrderDate FROM dbo.Orders WHERE CustomerRef = ?",
        "C-10045",
    )
    for row in cursor.fetchall():
        print(row.OrderId, row.OrderDate)

This keeps the password out of the source code and sends the value as a parameter, not as part of the SQL text.

SQL Server Security Best Practices: Least Privilege, Injection and Encryption

Use Windows or Microsoft Entra authentication, give each application its own login with only the permissions it needs, and never connect an application as sa or as a member of db_owner. These SQL Server security best practices limit the damage if one credential or one query is compromised.

Apply the Least Privilege Pattern

Create a database role for the application, grant it EXECUTE on a schema, and give it no direct table access. Stored procedures and tables owned by the same principal use ownership chaining, so the procedure can read the tables even though the caller cannot.

T-SQL

CREATE LOGIN [CORP\svc-orders-app] FROM WINDOWS;
GO
USE OrdersDb;
GO
CREATE SCHEMA app AUTHORIZATION dbo;
GO
CREATE USER [CORP\svc-orders-app] FOR LOGIN [CORP\svc-orders-app];
CREATE ROLE app_orders_role;
GRANT EXECUTE ON SCHEMA::app TO app_orders_role;
ALTER ROLE app_orders_role ADD MEMBER [CORP\svc-orders-app];

This creates the login, the user, and a role that can only run procedures in the app schema.

Prevent SQL Injection in Dynamic SQL

Build dynamic SQL with parameters through sp_executesql and never concatenate user input into the query text. Microsoft guidance also says to review every piece of code that calls EXEC, EXECUTE or sp_executesql. Dynamic SQL also breaks ownership chaining, so the caller needs permissions on the underlying tables.

T-SQL

DECLARE @sql nvarchar(max) =
    N'SELECT OrderId, OrderDate, Total
      FROM dbo.Orders
      WHERE CustomerId = @CustomerId AND OrderDate >= @From;';

EXEC sys.sp_executesql
     @sql,
     N'@CustomerId int, @From date',
     @CustomerId = 42,
     @From = '2026-01-01';

-- Object names cannot be parameters, so quote them
DECLARE @table sysname = N'Orders';
SET @sql = N'SELECT COUNT(*) FROM dbo.' + QUOTENAME(@table) + N';';
EXEC sys.sp_executesql @sql;

Typed parameters also give you plan reuse. QUOTENAME is for object names only, and you should still check them against an allow-list.

Encrypt Data in Transit, at Rest and in Columns

• In transit: Use TLS with a valid server certificate. See the connection management section for Encrypt settings.
• At rest: Enable Transparent Data Encryption (TDE) to protect data files and backups from a stolen disk or file copy. TDE does not protect against a user who has permission to query the data.
• Sensitive columns: Use Always Encrypted when even DBAs should not read the values. The keys stay with the client.
• Backups: Encrypt them, and store the certificate or key separately. Without it, the backup cannot be restored.

Audit Activity and Reduce the Attack Surface

Use SQL Server Audit to write to a file or the Windows event log. Capture logins, permission changes and access to sensitive tables. Disable or rename sa if you don’t need it, and keep xp_cmdshell and other unused features turned off. This is a core item on any SQL Server DBA checklist.

Example: Patient Data in a Healthcare System

Give the reporting team a read-only role with column-level permissions, so identifying columns stay out of reach.

T-SQL

CREATE ROLE reporting_role;
GRANT SELECT ON dbo.Patient (PatientId, AdmissionDate, WardCode) TO reporting_role;
DENY  SELECT ON dbo.Patient (FullName, NationalId) TO reporting_role;

Dynamic data masking can hide values in query results, but it is a convenience and not a security boundary. A user who can filter or infer values can still work around it, so rely on permissions and encryption.

SQL Server Backup Best Practices, High Availability and Restore Testing

A backup is only proven when you have restored it. Match the recovery model to your recovery point objective (RPO, the amount of data loss you can accept), take full, differential and log backups, keep copies off the server, and test restores on a schedule. These are the core SQL Server backup best practices.

Choose a Backup Strategy That Matches Your RPO and RTO

The recovery model decides which backups are possible. RTO means recovery time objective, the time you can afford to be down.

In FULL recovery, SQL Server keeps log records until a log backup has captured them. With no log backups, the log cannot be reused, so it grows until the disk is full. Switch to SIMPLE if you do not need point-in-time recovery.

Example: a retail orders database takes a full backup nightly, a differential every four hours and a log backup every 10 minutes. That gives an example RPO of about 10 minutes. It is an illustration, not a recommendation, so set your own interval from business needs.

Use CHECKSUM, Compression and Encryption on Every Backup

CHECKSUM detects page corruption while the backup runs. Compression reduces size and I/O. Encryption protects the file once it leaves the server.

RESTORE VERIFYONLY is the minimum check. It confirms the backup is readable, but it does not prove the data is consistent. Only a real restore followed by DBCC CHECKDB on the restored copy does that.

ZSTD Compression and Secondary Backups in SQL Server 2025

ZSTD backup compression is GA in SQL Server 2025 but is not the default. Enable it per backup with COMPRESSION (ALGORITHM = ZSTD, LEVEL = LOW | MEDIUM | HIGH), or instance-wide by setting backup compression algorithm to 3 with sp_configure. Test CPU cost and backup time first, because HIGH can take much longer.

Full, differential and log backups can now run on availability group secondary replicas (GA), which takes load off the primary. Backups to immutable storage are also GA, which helps against ransomware.

The animated diagram below shows the full path from backup to a verified restore.

High Availability Is Not a Backup

An availability group replicates a bad DELETE or corruption to the secondary just as quickly. Use HA for uptime and backups for recovery.

Protect Copies, Credentials and Keys

Keep one copy on a local share for fast restores and one offsite or on immutable storage. Document the backup credential, certificate and private key, and store them separately from the backups. If you lose the certificate, encrypted backups cannot be read.

Backup and Restore Test Script

The script below backs up, restores to a test name with MOVE, and checks consistency. The test server needs the same certificate. Run RESTORE FILELISTONLY first to get the logical file names.

SQL (T-SQL)

-- Optional: make ZSTD the instance default (SQL Server 2025)
EXEC sp_configure 'backup compression algorithm', 3;
RECONFIGURE;

BACKUP DATABASE SalesDB
TO DISK = N'D:\Backup\SalesDB_full.bak'
WITH CHECKSUM,
     COMPRESSION (ALGORITHM = ZSTD, LEVEL = MEDIUM),
     ENCRYPTION (ALGORITHM = AES_256, SERVER CERTIFICATE = BackupCert),
     STATS = 10;

BACKUP LOG SalesDB
TO DISK = N'D:\Backup\SalesDB_log.trn'
WITH CHECKSUM,
     COMPRESSION (ALGORITHM = ZSTD, LEVEL = LOW),
     ENCRYPTION (ALGORITHM = AES_256, SERVER CERTIFICATE = BackupCert);

-- On the restore test server
RESTORE FILELISTONLY FROM DISK = N'D:\Backup\SalesDB_full.bak';

RESTORE DATABASE SalesDB_RestoreTest
FROM DISK = N'D:\Backup\SalesDB_full.bak'
WITH MOVE N'SalesDB'     TO N'E:\RestoreTest\SalesDB_RestoreTest.mdf',
     MOVE N'SalesDB_log' TO N'F:\RestoreTest\SalesDB_RestoreTest.ldf',
     CHECKSUM, RECOVERY, STATS = 10;

DBCC CHECKDB (SalesDB_RestoreTest) WITH NO_INFOMSGS, ALL_ERRORMSGS;

This restores the full backup under a new name and reports any corruption. Record how long the restore took, because that is your measured RTO.

For a point-in-time restore, restore the full backup (and the latest differential) with NORECOVERY. Then restore each log backup, and add STOPAT = '2026-10-13T09:55:00' to the last one with RECOVERY. This needs FULL recovery and an unbroken log chain.

Monitoring SQL Server: Wait Stats, Extended Events and Performance Counters

Start with wait statistics to see what the instance is waiting on. Then use Query Store and Extended Events to find the queries and events behind those waits. This order is the core of SQL Server performance tuning best practices, because it stops you from guessing.

Common Wait Types and What They Point To

A wait type is the reason a request had to pause. Treat it as a pointer, not a diagnosis. Confirm it with a query, a plan or a counter before you change anything.

T-SQL

SELECT TOP (10)
       wait_type,
       waiting_tasks_count,
       wait_time_ms,
       signal_wait_time_ms,
       CAST(100.0 * wait_time_ms / SUM(wait_time_ms) OVER () AS decimal(5,2)) AS pct_of_waits
FROM sys.dm_os_wait_stats
WHERE wait_time_ms > 0
  AND wait_type NOT IN (N'SLEEP_TASK', N'LAZYWRITER_SLEEP', N'XE_TIMER_EVENT',
      N'XE_DISPATCHER_WAIT', N'REQUEST_FOR_DEADLOCK_SEARCH', N'CHECKPOINT_QUEUE',
      N'DIRTY_PAGE_POLL', N'LOGMGR_QUEUE', N'SQLTRACE_INCREMENTAL_FLUSH_SLEEP',
      N'SP_SERVER_DIAGNOSTICS_SLEEP', N'BROKER_TO_FLUSH', N'BROKER_TASK_STOP',
      N'QDS_PERSIST_TASK_MAIN_LOOP_SLEEP', N'QDS_ASYNC_QUEUE', N'WAITFOR')
ORDER BY wait_time_ms DESC;

This returns the top waits since the last restart, minus a partial list of idle waits. Take two snapshots and compare them to see current behaviour.

Use Extended Events, Not Profiler

Extended Events is the lightweight tracing system, and SQL Trace and Profiler are deprecated. Keep the built-in system_health session running for deadlock graphs. Add a small session for slow statements.

T-SQL

CREATE EVENT SESSION [LongRunningStatements] ON SERVER
ADD EVENT sqlserver.sql_statement_completed
(
    ACTION (sqlserver.database_name, sqlserver.client_app_name, sqlserver.sql_text)
    WHERE duration > 1000000   -- microseconds, so 1 second
)
ADD TARGET package0.event_file
(
    SET filename = N'LongRunningStatements.xel', max_file_size = 50, max_rollover_files = 4
)
WITH (MAX_DISPATCH_LATENCY = 30 SECONDS, STARTUP_STATE = ON);

ALTER EVENT SESSION [LongRunningStatements] ON SERVER STATE = START;

The file target rolls over at a fixed size, so the session cannot fill the disk.

Counters and Alerts Worth Setting Up

• Page life expectancy: Watch the trend against your own baseline. A fixed number such as 300 does not fit every server.
• Batch requests per second: Use it to read load changes next to waits.
• Log file percent used: Alert before the log fills the volume.
• Free space: Check data, log and tempdb volumes separately.
• AG synchronization lag: Alert when secondaries fall behind.
• Errors and jobs: Alert on severity 17 to 25 errors and on job failures.

For backups, alert on the age of the last successful backup, not on whether the job ran. A job can finish without producing a usable backup. This also belongs on any SQL Server DBA checklist.

Patching and Upgrading to SQL Server 2025: What to Check First

Patch on a regular cadence, test the upgrade on a copy that has the same linked servers, certificates and jobs, and plan the outage window before you start. Most upgrade surprises come from things outside the database files.

Version, Support and Current Builds

A CU (cumulative update) carries fixes and features. A GDR (General Distribution Release) carries security-only fixes for servers that don’t apply CUs. Each instance sits on one of two tracks, and the rule is one-way.

1. GDR track: the instance has only had GDR updates and receives security fixes only (e.g., 17.0.1135.8 for SQL Server 2025).
2. CU track: the instance has had at least one CU. From here, security-only fixes arrive as a CU+GDR package built on the CU you already have (e.g., CU8+GDR 17.0.4085.5).
3. Moving from GDR to CU is allowed. Install a CU and the instance joins the CU track.
4. Moving from CU back to GDR is not allowed. Once a CU is installed, only CU and CU+GDR packages apply.

Decide the track before the first patch. If you may want bug fixes or features later, plan to move to the CU track once and stay there. If you only want security fixes, stay on GDR until you are ready to commit to CUs.

T-SQL

SELECT SERVERPROPERTY('ProductVersion') AS ProductVersion,
       SERVERPROPERTY('ProductLevel')   AS ProductLevel,
       SERVERPROPERTY('Edition')        AS Edition;

Compare the returned build number with the table above to see which track and update level the instance is on.

Is the Upgrade Worth It?

Yes for write-heavy or backup-heavy systems, after testing. The practical 2025 gains are:

• Optimized locking, which uses transaction ID (TID) locking and lock after qualification (LAQ) to reduce blocking and lock memory, and to avoid lock escalation, with no application code changes.
• Query Store on readable secondaries, on by default (in 2022 it was off by default and needed trace flag 12606).
• ZSTD backup compression and backups on AG secondaries.
• Resource Governor and higher limits in Standard edition.
• tempdb space governance.

The trade-off is testing effort. DiskANN vector indexes are preview only, so keep them out of production.

What Breaks: Linked Servers and TLS

A DBA report found that linked servers using SQLNCLI or MSOLEDBSQL can fail after an in-place upgrade to 2025, because of stricter TLS certificate validation. Setup can also restart the service up to three times, so the outage is longer than one restart. Fix the certificates or the provider settings before cutover, then test every linked server afterwards.

T-SQL

DECLARE @name sysname;
DECLARE ls CURSOR FAST_FORWARD FOR
    SELECT name FROM sys.servers WHERE is_linked = 1;
OPEN ls;
FETCH NEXT FROM ls INTO @name;
WHILE @@FETCH_STATUS = 0
BEGIN
    BEGIN TRY
        EXEC sp_testlinkedserver @name;
        PRINT @name + ': OK';
    END TRY
    BEGIN CATCH
        PRINT @name + ': FAILED - ' + ERROR_MESSAGE();
    END CATCH;
    FETCH NEXT FROM ls INTO @name;
END;
CLOSE ls;
DEALLOCATE ls;

The animated diagram below shows the safe order of steps, including the retry loop for failed linked server tests.

In-Place vs Side-by-Side Migration

Use side-by-side for critical systems. Use in-place only for small or non-critical instances where a longer window is acceptable.

After the Upgrade: Compatibility Level

Keep the old compatibility level until the application is tested. Let Query Store capture baseline plans, then raise the level and force back any plan that regressed.

The level used below, 170 for SQL Server 2025, is not in the verified research for this article. Confirm it in the Microsoft documentation article “ALTER DATABASE compatibility level (Transact-SQL)” before you run the statement, and use the highest level that article lists for your version.

T-SQL

-- Check the current level
SELECT name, compatibility_level FROM sys.databases WHERE name = N'SalesDb';

-- Raise it after testing. Replace 170 if the Microsoft docs list a different
-- level for your SQL Server 2025 build.
ALTER DATABASE SalesDb SET COMPATIBILITY_LEVEL = 170;

Common Anti-Patterns and SQL Server DBA Production Readiness Checklist

Most production incidents trace back to a small set of repeated mistakes. Use the table below to spot them, then run the checklist before a server goes live.

Common SQL Server Anti-Patterns

SQL Server Production Readiness Checklist

This SQL Server DBA checklist combines the configuration, security and backup rules from the sections above. Work through it in order.

1. Confirm the version and patch level, and choose the CU or GDR track on purpose.
2. Set the SQL Server max server memory setting to a specific value, with min server memory at 0.
3. Set MAXDOP and cost threshold for parallelism from the NUMA rule and measured plan costs.
4. Lay out tempdb with equally sized, pre-sized files on fast storage.
5. Separate data, log and tempdb volumes where the storage design allows.
6. Enable instant file initialization for data files.
7. Enable Query Store on user databases with a sensible size and capture mode.
8. Choose the isolation level deliberately, and test RCSI before turning it on.
9. Set connection strings with Encrypt, the listener name and MultiSubnetFailover=True where it applies.
10. Create least-privilege roles for each application, and disable or rename sa.
11. Enforce TLS in transit and enable TDE at rest.
12. Turn on SQL Server Audit for logins, permission changes and sensitive tables.
13. Schedule full, differential and log backups with CHECKSUM, compression and encryption.
14. Keep an offsite or immutable copy, and document backup keys and certificates.
15. Restore on a schedule and run DBCC CHECKDB on the restored copy.
16. Alert on wait trends, failed jobs, severity 17-25 errors and the age of the last good backup.
17. Write the upgrade plan, including linked server tests and the outage window.

These items also form a short SQL Server security best practices review (items 10 to 12) and a SQL Server backup best practices review (items 13 to 15).

Key takeaways

• Cap max server memory: Start from about 75% of the memory that is available to SQL Server (after other processes and other instances), keep min server memory at 0, and always use a specific value if Lock Pages in Memory is granted.
• Tune MAXDOP and cost threshold by measurement: Begin with the Microsoft NUMA-based MAXDOP guidance, use database-scoped MAXDOP or Resource Governor for exceptions, and raise cost threshold for parallelism above the default of 5 after checking CXPACKET/CXCONSUMER waits.
• Use Strict or Mandatory encryption with a valid certificate: Fix the certificate chain or host name when connections fail after a driver upgrade. Avoid TrustServerCertificate=true in production.
• Give applications least privilege: Use a dedicated login and a role with EXECUTE on a schema, never sa or db_owner, and pass every value through typed parameters.
• Enable Query Store: Turn it on for every database you care about, so you can find regressions, force a known good plan, and keep baseline plans before a compatibility level change.
• Test restores, not just backups: Take backups with CHECKSUM, keep an offsite or immutable copy, and restore to a test name regularly, then run DBCC CHECKDB on the restored copy.
• Test the SQL Server 2025 upgrade on a copy first: Include linked servers, certificates and jobs, and run sp_testlinkedserver afterwards because stricter TLS validation can break them. Evaluate optimized locking with RCSI for write-heavy workloads, and keep DiskANN vector indexes out of production while they are preview only.

That’s all! Happy coding!

Did this guide help you to set up and tune SQL Server for production? Please share your questions or experience in the comments below.

Bookmark this page for your next production review and share it with your team. Subscribe to TheCodeBuzz to get new database best-practice guides in your inbox.

FAQ

What should I set max server memory to in SQL Server?

Start with about 75% of the memory that is available to the instance, meaning the total minus what the OS, other instances and other processes use, and leave min server memory at 0. The default is about 2 TB, which is effectively unlimited, so you should cap it on every version. If Lock Pages in Memory is granted to the service account, you must set a specific value, not the default. Set it with sp_configure 'max server memory (MB)' followed by RECONFIGURE, and check the result in sys.configurations.

What is the best MAXDOP and cost threshold for parallelism setting?

There is no single best value. Start from Microsoft’s NUMA-based MAXDOP guidance, set it per database with ALTER DATABASE SCOPED CONFIGURATION SET MAXDOP for mixed workloads, and use Resource Governor workload groups where one workload needs a different limit. Avoid MAXDOP 1 server-wide, because it breaks parallel index builds and slows reporting queries. The cost threshold for parallelism defaults to 5, which is too low for modern hardware, so raise it based on observed plan costs and check the effect on CXPACKET and CXCONSUMER waits.

How many tempdb files should I have, and how should I size them?

Start with a small number of equally sized data files, up to the number of cores as Microsoft guidance suggests, and add more only if monitoring shows allocation contention. Pre-size the files and use a fixed growth increment, so autogrow stays an emergency measure and not a routine event. Equal sizes matter because SQL Server spreads allocations across files, and uneven files lead to uneven use. On SQL Server 2025 you can also use Resource Governor tempdb space governance, which stops a workload with an error when it exceeds its limit.

Why does my app fail to connect after upgrading Microsoft.Data.SqlClient, with certificate errors?

The driver now defaults to Encrypt=Mandatory and TrustServerCertificate=false, so it rejects a server certificate that the client does not trust. This is not a driver bug. Fix the certificate chain or make sure the host name in the connection string matches the certificate, instead of switching on TrustServerCertificate=true, which skips server identity checks. Use Encrypt=Strict where the server supports TDS 8.0, because Strict cannot be bypassed with TrustServerCertificate.

Should I enable Query Store, optimized locking or Read Committed Snapshot Isolation?

Yes to Query Store on every user database you care about, because it helps you find regressions and force a known good plan. Enable Read Committed Snapshot Isolation (RCSI) after testing, since it adds version storage and changes behavior for code that relied on blocking reads. Optimized locking comes with SQL Server 2025 and needs no application code changes. It works best together with RCSI, so it is a good reason to test 2025 for heavy write workloads.

Sources and further reading

• What’s New in SQL Server 2025 – SQL Server (Microsoft Learn)
• Latest Updates and Version History for SQL Server (Microsoft Learn)
• Server Memory Configuration Options – SQL Server (Microsoft Learn)
• Memory Management Architecture Guide – SQL Server (Microsoft Learn)
• Resource Governor – SQL Server (Microsoft Learn)
• SQL Server Security Best Practices – SQL Server (Microsoft Learn)
• Encryption and Certificate Validation in Microsoft.Data.SqlClient (Microsoft Learn)
• Whats new in the Backup/Restore area in SQL Server 2025 (Microsoft Tech Community)
• SQL Server 2025 New Features and Enhancements (MSSQLTips)
• SQL Server 2025 Backup Compression Algorithm (SQLServerCentral)

Diagrams are original illustrations created by and for TheCodeBuzz.

The post SQL Server Best Practices and Guidelines-2026 first appeared on TheCodeBuzz.

Most PostgreSQL outages and security incidents come from clusters that were never patched or never upgraded, not from exotic bugs. This guide is for engineers, architects and DBAs who run PostgreSQL in production. It is a compact reference you can bookmark and check a cluster against.

Here is where things stand in October 2026. PostgreSQL 18 is the current stable major, and 18.6, dated 2026-08-13, is its latest minor. PostgreSQL 14 receives its last fixes on 2026-11-12, so anyone still on it has a deadline measured in weeks. I cover patching and upgrades first, because that is where most production risk sits.

After that come the PostgreSQL 18 features that change how you design schemas and indexes, with the reasoning behind each rule so you can judge where it applies to your workload. These PostgreSQL best practices start with a summary table and end with a checklist and FAQ.

Version note: this guide targets PostgreSQL 18 (18.6), and also covers 17.11, 16.15, 15.19 and 14.24 for patching and upgrade planning, with PostgreSQL 19 Beta 4 mentioned only for testing.

 

PostgreSQL best practices at a glance

Minor releases contain only bug and security fixes, which is why they are low-risk to apply. Low-risk is not no-risk: read the release notes, test against your workload and schedule the restart. The CVE examples above show why you should not defer them for long.

Key order matters because a B-tree keeps neighbouring values on neighbouring pages. Time-ordered keys append to the right edge of the index, while random keys touch pages all over it, which hurts cache hit rates on large tables.

Skip scan changes the column-order trade-off but does not remove it. PostgreSQL has to probe the index once for each distinct value of the omitted leading column. With a handful of values that is cheap.

With millions of values it is not, and an index that leads with the column you actually filter on is still the better choice. Check the plan before you change any existing index.

Example: uuidv7 key, temporal constraint and a skip scan candidate

SQL

CREATE EXTENSION IF NOT EXISTS btree_gist;

CREATE TABLE room_booking (
    booking_id uuid NOT NULL DEFAULT uuidv7() PRIMARY KEY,
    tenant_id  integer NOT NULL,
    room_id    integer NOT NULL,
    status     text NOT NULL,   -- few distinct values, for example 'confirmed' or 'cancelled'
    during     tstzrange NOT NULL,
    CONSTRAINT no_double_booking
        UNIQUE (room_id, during WITHOUT OVERLAPS)
);

-- Leading column has few distinct values; queries may filter on tenant_id alone.
CREATE INDEX room_booking_status_tenant_idx
    ON room_booking (status, tenant_id);

The scalar room_id in the temporal key needs btree_gist. The range column during is what the constraint checks for overlap. The index behind that constraint also starts with room_id, so lookups by room already have an index and you do not need to add another.

The (status, tenant_id) index is the skip scan candidate. The query below has an equality condition on tenant_id but none on the leading column status. Before PostgreSQL 18, this index could not serve it efficiently. Run it against representative data after an ANALYZE. On a tiny table the planner may prefer a sequential scan, so the SET LOCAL line is for testing only and shows whether the index is usable at all.

SQL

ANALYZE room_booking;

BEGIN;
SET LOCAL enable_seqscan = off;   -- test only: see whether the index can serve the query

EXPLAIN (ANALYZE, BUFFERS)
SELECT booking_id
FROM room_booking
WHERE tenant_id = 42;

ROLLBACK;

In the plan, look for a scan on room_booking_status_tenant_idx with tenant_id = 42 as the index condition, even though the query never mentions status.

PostgreSQL 18 also reports the number of index searches in EXPLAIN ANALYZE. A skip scan shows roughly one search per distinct status value.

Then rerun the query without the SET LOCAL line and compare timing and buffer counts with the plan the planner picks on its own. If the planner chooses a sequential scan or another index and is faster, keep that plan. If status has many distinct values in your data, a separate index on (tenant_id) is the better design.

Plan upgrades and the production readiness checklist

Support lifecycle

PostgreSQL ships a major version about once a year and supports each for five years. PostgreSQL 18 was first released on 2025-09-25, and its final release is due 2030-11-14. PostgreSQL 14 stops receiving fixes on 2026-11-12, so schedule that move now. Since version 10, minors increment the second number (18.5 to 18.6).

Minor releases carry only bug and security fixes, so they are low-risk to apply, but not zero-risk. Test them in staging and keep a rollback plan. Apply them promptly. Release 18.1 fixed CVE-2025-12817, where CREATE STATISTICS skipped a schema CREATE privilege check.

Release 18.4 fixed CVE-2026-6575 in pg_restore_attribute_stats along with more than 60 bugs. As of early October 2026 the newest minors are 18.6, 17.11, 16.15, 15.19 and 14.24, all dated 2026-08-13.

PostgreSQL 19 is in beta (Beta 4 was announced on 2026-09-24). Do not run it in production, but do test your own workloads against it so you find regressions early.

Upgrading with pg_upgrade

PostgreSQL 18 keeps planner statistics across the upgrade, runs checks in parallel with --jobs, and adds --swap, which swaps directories instead of copying, cloning or linking. The animated diagram below walks through this path.

Four rules govern the new cluster and the run itself:

• Compatible encoding and locale. Initialise the new cluster with an encoding and locale that match the old one. pg_upgrade refuses to proceed if they differ. Read the old values first and pass them to initdb explicitly rather than relying on the environment.
• Matching checksum settings. initdb in PostgreSQL 18 enables data checksums by default, and pg_upgrade requires both clusters to agree. If the old cluster has none, create the new one with --no-data-checksums. You can enable checksums later, offline, with pg_checksums --enable while the cluster is cleanly shut down. It rewrites every data file, so plan the window.
• Run as the postgres user. Run initdb and pg_upgrade as the operating-system user that owns the data directories, normally postgres. Running as root, or as a different user, causes permission failures or leaves files with the wrong owner.
• --swap leaves the old cluster unusable. It reuses the old cluster’s files instead of copying them, so you cannot start the old cluster afterwards. Your rollback is the backup you took before the upgrade, so confirm it restores before you begin.

SQL

-- Run on the OLD cluster: encoding and locale to reuse for initdb
SELECT datname,
       pg_encoding_to_char(encoding) AS encoding,
       datcollate,
       datctype
FROM pg_database
WHERE datname NOT IN ('template0', 'template1');

Bash/shell

# Run everything as the postgres user
sudo -iu postgres

# Does the old cluster use checksums?
pg_controldata -D /var/lib/postgresql/14/main | grep -i checksum

# New cluster: match encoding and locale from the query above.
# Add --no-data-checksums ONLY if the old cluster has no checksums.
/usr/lib/postgresql/18/bin/initdb \
  --encoding=UTF8 --locale=en_US.UTF-8 \
  --no-data-checksums \
  -D /var/lib/postgresql/18/main

# Dry run: checks only, changes nothing
/usr/lib/postgresql/18/bin/pg_upgrade --check --jobs=4 \
  -b /usr/lib/postgresql/14/bin -B /usr/lib/postgresql/18/bin \
  -d /var/lib/postgresql/14/main -D /var/lib/postgresql/18/main

# Real run, after a verified backup. The old cluster is unusable afterwards.
/usr/lib/postgresql/18/bin/pg_upgrade --jobs=4 --swap \
  -b /usr/lib/postgresql/14/bin -B /usr/lib/postgresql/18/bin \
  -d /var/lib/postgresql/14/main -D /var/lib/postgresql/18/main

# Optional, later, with the cluster cleanly shut down:
# pg_checksums --enable -D /var/lib/postgresql/18/main

After the upgrade

Do not reopen the application to traffic until you have checked three things.

1. Start the new cluster and confirm the version with SELECT version();.
2. Check statistics. PostgreSQL 18 carries planner statistics across, which shortens the slow period after an upgrade, but verify rather than assume. Find tables that have rows but no statistics, then run ANALYZE.
3. Run your application’s test suite and a representative query set against the new cluster. Compare the plans and timings of your slowest queries with a pre-upgrade baseline.

SQL

-- Tables that have rows but no planner statistics
SELECT c.oid::regclass AS table_name, c.reltuples::bigint AS est_rows
FROM pg_class c
JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE c.relkind IN ('r', 'm')
  AND n.nspname NOT IN ('pg_catalog', 'information_schema', 'pg_toast')
  AND c.reltuples > 0
  AND NOT EXISTS (
    SELECT 1 FROM pg_stats s
    WHERE s.schemaname = n.nspname AND s.tablename = c.relname
  );

Bash/shell

# Refresh statistics in every database
vacuumdb --all --analyze-only --jobs=4

Low-downtime alternative: logical replication

If you cannot afford the downtime of pg_upgrade, build a new cluster on the target major version and keep it in sync with logical replication. Then switch applications over in a short window. PostgreSQL 17 improved logical replication for high-availability setups and major-version upgrades, so this path is better supported on recent versions. It also gives you a rollback: the old cluster stays intact until you decide to retire it.

The cost is more moving parts. Logical replication does not copy schema changes, so you must create the schema on the target and freeze DDL during the migration.

Sequence values need to be synchronised before cutover.

Tables need suitable replica identities, usually a primary key. Rehearse the whole procedure on a copy of production first.

Production readiness checklist

Each item names something you can check. If you cannot show the evidence, treat the item as not done.

1. Latest minor applied. SHOW server_version; matches the newest minor of your major (18.6, 17.11, 16.15, 15.19 or 14.24 as of this writing).
2. Supported major with a dated plan. You are not on a version past its end-of-fix date. If you run PostgreSQL 14, the upgrade must finish before 2026-11-12.
3. WAL archiving works. archive_mode = on with a working archive command or library. pg_stat_archiver shows a recent last_archived_time and a failed_count that is not growing. Alert when archiving fails, because unarchived WAL piles up on the primary’s disk.
4. A restore has been tested. You have restored a base backup plus archived WAL to a separate host, reached a chosen point in time, and run application queries against it. Record the date and how long it took, and repeat on a schedule.
5. pg_stat_statements is enabled. It is in shared_preload_libraries (this needs a restart), and CREATE EXTENSION pg_stat_statements; has been run in the database you query. A dashboard or a regular review uses it to find the slowest and most frequent statements.
6. Autovacuum is monitored. You alert on dead tuples and time since the last autovacuum for large tables, on long-running transactions and stale replication slots that hold back cleanup, and on transaction ID age (age(datfrozenxid)) approaching the freeze limits.
7. TLS is required. ssl = on with a valid certificate, and pg_hba.conf uses hostssl entries rather than plain host for network clients. Clients connect with sslmode=verify-full where possible.
8. Passwords use scram-sha-256. password_encryption = scram-sha-256, and no line in pg_hba.conf uses md5 or trust for network access. Existing md5 hashes cannot be converted, so reset those passwords after changing the setting.
9. Least-privilege roles. Applications do not connect as a superuser or as the schema owner. Check with \du and by reviewing grants.
10. Replication lag has thresholds. Derive them from your recovery point objective: one warning level and one paging level, measured on pg_stat_replication (replay_lag or byte lag) and on standbys. Alert also when a standby disconnects entirely, since a missing row looks like zero lag.
11. Failover has been exercised. You have promoted a standby on purpose and confirmed that applications reconnect.
12. Data checksums are on, or the plan is written down. New PostgreSQL 18 clusters have them by default. For older clusters, schedule an offline pg_checksums --enable.
13. Disk and connection headroom are alerted. You get a warning before the data, WAL or archive volumes fill, and before connection counts approach max_connections.

Text

# pg_hba.conf: TLS required, SCRAM only, no trust/md5 for network clients
# TYPE     DATABASE  USER  ADDRESS        METHOD
local      all       postgres              peer
hostssl    all       all   10.0.0.0/16    scram-sha-256
hostnossl  all       all   0.0.0.0/0      reject

SQL

-- WAL archiving: failures should be zero and last_archived_time recent
SELECT archived_count, failed_count, last_archived_time, last_failed_time
FROM pg_stat_archiver;

-- Replication lag per standby (run on the primary)
SELECT application_name, state, replay_lag,
       pg_wal_lsn_diff(pg_current_wal_lsn(), replay_lsn) AS replay_lag_bytes
FROM pg_stat_replication;

-- Autovacuum: tables with the most dead tuples
SELECT relname, n_dead_tup, last_autovacuum
FROM pg_stat_user_tables
ORDER BY n_dead_tup DESC
LIMIT 10;

-- Transaction ID age per database
SELECT datname, age(datfrozenxid) AS xid_age
FROM pg_database
ORDER BY xid_age DESC;

-- Auth and TLS settings
SHOW password_encryption;
SHOW ssl;

Key takeaways

• Patch minors promptly. Run the latest minor of your major version. Minors carry only bug and security fixes, so they are low-risk, but still roll them out through staging first.
• Retire PostgreSQL 14 now. Set an upgrade date before its final fixes arrive in November 2026, and prefer PostgreSQL 18 as the target.
• Use uuidv7() for UUID primary keys. Timestamp-ordered values keep inserts localized in the index.
• Recheck composite index column order. Skip scan in PostgreSQL 18 may make some indexes redundant, so confirm with query plans.
• Enforce integrity in the database. Use temporal constraints instead of application-side overlap checks, and keep data checksums enabled.
• Rehearse pg_upgrade. Run pg_upgrade --check first and take a backup before using --swap.
• Prefer OAuth over shared static passwords, and benchmark io_method yourself. Inspect pg_aios on your own storage before changing the default.
• Keep PostgreSQL 19 beta out of production. Use it in test environments to try your own workloads.

FAQ

Should I upgrade to PostgreSQL 18 or 17?

Choose 18 unless something concrete blocks it, such as an extension, driver or managed service that does not support it yet. PostgreSQL 18 was first released on 2025-09-25 and is scheduled for final fixes on 2030-11-14, so it gives you the longest support window. Upgrading to 17 means you will have to run another major upgrade sooner.

PostgreSQL 18 also makes the upgrade itself easier:

• Planner statistics carry over, so the new cluster reaches normal performance sooner.
• pg_upgrade runs its checks in parallel with --jobs.
• The new --swap flag swaps directories instead of copying, cloning or linking files, which helps most when a database has many objects.

PostgreSQL 17 is a reasonable stop if your dependencies force it. It reworked vacuum memory management, improved high-concurrency workloads and bulk loading, and improved logical replication for high availability and major upgrades. Do not pick 16 or 15 as a target for a new upgrade. They have less support time left and you would repeat the work soon.

Either way, restore a production backup into a staging cluster, run pg_upgrade there, and replay your real workload before you commit. If you are still on 14, its last fixes are due on 2026-11-12, so schedule this now.

Can I enable data checksums on an existing cluster?

Yes, but not online. initdb in PostgreSQL 18 enables checksums by default, which does nothing for clusters that already exist. First check your current state:

SQL

SHOW data_checksums;

If it returns off, the usual route is the pg_checksums tool. It requires a cleanly shut-down cluster and rewrites every data file to add checksums, so downtime grows with database size. Run it on a restored copy first to measure that time. If you cannot afford the downtime, build a new cluster with checksums enabled and move the data over with logical replication.

The setting matters for major upgrades because pg_upgrade requires the old and new clusters to match. If your old cluster has no checksums and you do not want to change that during the upgrade, initialize the new 18 cluster without them:

Bash

initdb --no-data-checksums -D /var/lib/postgresql/18/main
pg_upgrade \
  --old-bindir=/usr/lib/postgresql/16/bin \
  --new-bindir=/usr/lib/postgresql/18/bin \
  --old-datadir=/var/lib/postgresql/16/main \
  --new-datadir=/var/lib/postgresql/18/main \
  --jobs=4 --check

Dropping --check runs the real upgrade. I recommend treating the upgrade and the checksum change as two separate maintenance steps. If something goes wrong, you then know which change caused it. The trade-off is that checksums add a small CPU cost, but they let PostgreSQL detect storage-level corruption instead of silently reading bad pages.

Should I use uuidv7() on existing tables?

Use it as the default for new rows and leave existing keys alone. uuidv7() is new in PostgreSQL 18 and generates timestamp-ordered UUIDs. New values are inserted near the end of a primary key index, which suits indexes and caching better than random UUIDs. Changing the default does not rewrite or invalidate existing rows, because both kinds of value are ordinary uuid values:

SQL

ALTER TABLE orders
  ALTER COLUMN id SET DEFAULT uuidv7();

Do not rewrite existing primary keys just to get ordering. That would mean updating every foreign key and external reference, and the benefit applies only to new inserts. Two caveats apply:

• A UUIDv7 embeds its creation time, so do not use it where exposing creation time to clients is a problem.
• The function does not exist before PostgreSQL 18. If any replica or application environment still runs an older major, applying the default there will fail.

Apply the change after every node runs 18. uuidv4() is also new in 18 as an alias for gen_random_uuid(), if you want a name that states the version.

Do multicolumn indexes need to be redesigned for PostgreSQL 18?

Not immediately. PostgreSQL 18 adds skip scan on multicolumn B-tree indexes, so a query that omits an equality condition on one or more leading columns can still use the index. That can make some single-purpose indexes redundant, and it relaxes how strictly you must order columns in new composite indexes.

Do not drop indexes on this basis alone. Compare the plans and timings of your real queries after the upgrade, and only then retire an index you can show is unused or covered. Dropping an index in a hurry is harder to undo than keeping it.

Is it safe to apply PostgreSQL minor releases without a long test cycle?

Minor releases carry only bug and security fixes, which makes them low-risk, but not risk-free. Skipping them has a real cost: 18.1 fixed CVE-2025-12817, where CREATE STATISTICS skipped a schema CREATE privilege check, and 18.4 fixed CVE-2026-6575 in pg_restore_attribute_stats along with over 60 bugs.

Roll the update through staging first and confirm you have a backup you have actually restored. Then move production to the latest minor of your major: 18.6, 17.11, 16.15, 15.19 or 14.24. Since version 10, minor releases change the second number (for example 10.0 to 10.1), so 18.5 to 18.6 is a minor update.

Should I test PostgreSQL 19 now?

Yes, run your own workload against it in a non-production environment. Beta 4 was announced on 2026-09-24, and the project encourages this kind of testing, so problems can be reported before the final release. Do not run a beta in production. For production, use PostgreSQL 18.

Sources and further reading

• PostgreSQL: The world’s most advanced open source database (PostgreSQL Global Development Group)
• PostgreSQL: Versioning Policy (PostgreSQL Global Development Group)
• PostgreSQL: PostgreSQL 18 Released! (PostgreSQL Global Development Group)
• PostgreSQL 18.0 Release Notes (PostgreSQL Global Development Group)

Please share this article with your friends and Subscribe to the blog to get a notification on freshly published best practices of software development.

The post PostgreSQL – Best Practices for Production first appeared on TheCodeBuzz.

That is anecdote, not measured data. It still points to a lower-risk start: one deployable unit with strict internal modules. This article shows how to build one in .NET, how to keep its boundaries honest, and when to extract a service.

Why start with a monolith

• Unstable boundaries: a new domain keeps changing. Early splits create arbitrary seams in a distributed system.
• Operational load: microservices add service discovery, tracing, inter-service auth, gateways and orchestration. A monolith has one pipeline, one log destination and one process to debug.
•  

One 2026 vendor guide suggests a modular monolith under about 15 developers and microservices at 50 or more.

Those are heuristics, not rules. A 2014 article, “Don’t start with a monolith,” argued that a team that can’t build a well-structured monolith can’t build well-structured services. The real risk is poor modularity.

Build a modular monolith in .NET

Requires .NET 8+ (C# 12 primary constructors). Packages: Microsoft.EntityFrameworkCore.SqlServer, Microsoft.Extensions.Http.Resilience, xUnit. Each class library needs usings for Microsoft.EntityFrameworkCore, Microsoft.Extensions.DependencyInjection, Microsoft.Extensions.Hosting, Microsoft.Extensions.Logging, System.Text.Json and System.Net.Http.Json as needed.

src/
  Host/               # minimal API; references modules and contracts
  SharedKernel/       # IDomainEvent, IEventHandler, event bus
  Orders.Contracts/   # IOrdersApi, DTOs, OrderPlaced (public)
  Orders/             # internal DbContext, logic
  Billing/            # references Orders.Contracts only
tests/ArchitectureTests/

Modules talk through contracts or events.

Each module has its own DbContext and schema, so there is no automatic transaction across modules.

To avoid losing events, Orders writes the event to an outbox table in the same SaveChanges as the order.

A background dispatcher publishes it afterwards.

Delivery is at-least-once, so handlers must be idempotent. A broker will give you the same contract later.

// SharedKernel
public interface IDomainEvent { }
public interface IEventHandler<in T> where T : IDomainEvent
{
    Task HandleAsync(T e, CancellationToken ct);
}
public sealed class InProcessEventBus(IServiceProvider sp)
{
    public async Task PublishAsync<T>(T e, CancellationToken ct) where T : IDomainEvent
    {
        foreach (var h in sp.GetServices<IEventHandler<T>>())
            await h.HandleAsync(e, ct);
    }
}

// Orders.Contracts
public sealed record OrderDto(Guid Id, decimal Total, string Status);
public sealed record OrderPlaced(Guid OrderId, decimal Total) : IDomainEvent;
public interface IOrdersApi
{
    Task<OrderDto?> GetOrderAsync(Guid id, CancellationToken ct);
    Task<Guid> PlaceOrderAsync(decimal total, CancellationToken ct);
}

// Orders (internal)
internal sealed class OrderEntity
{
    public Guid Id { get; set; }
    public decimal Total { get; set; }
    public string Status { get; set; } = "Placed";
}
internal sealed class OutboxMessage
{
    public Guid Id { get; set; }
    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
    public string Payload { get; set; } = "";
    public DateTime? ProcessedAt { get; set; }
}
internal sealed class OrdersDbContext(DbContextOptions<OrdersDbContext> options) : DbContext(options)
{
    public DbSet<OrderEntity> Orders => Set<OrderEntity>();
    public DbSet<OutboxMessage> Outbox => Set<OutboxMessage>();
    protected override void OnModelCreating(ModelBuilder b) => b.HasDefaultSchema("orders");
}
internal sealed class OrdersApi(OrdersDbContext db) : IOrdersApi
{
    public Task<OrderDto?> GetOrderAsync(Guid id, CancellationToken ct) =>
        db.Orders.AsNoTracking().Where(o => o.Id == id)
            .Select(o => new OrderDto(o.Id, o.Total, o.Status))
            .FirstOrDefaultAsync(ct);

    public async Task<Guid> PlaceOrderAsync(decimal total, CancellationToken ct)
    {
        var order = new OrderEntity { Id = Guid.NewGuid(), Total = total };
        db.Orders.Add(order);
        db.Outbox.Add(new OutboxMessage
        {
            Id = Guid.NewGuid(),
            Payload = JsonSerializer.Serialize(new OrderPlaced(order.Id, total))
        });
        await db.SaveChangesAsync(ct); // order and event commit together
        return order.Id;
    }
}
internal sealed class OutboxDispatcher(IServiceScopeFactory scopes, ILogger<OutboxDispatcher> log) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        using var timer = new PeriodicTimer(TimeSpan.FromSeconds(2));
        while (await timer.WaitForNextTickAsync(ct))
        {
            using var scope = scopes.CreateScope();
            var db = scope.ServiceProvider.GetRequiredService<OrdersDbContext>();
            var bus = scope.ServiceProvider.GetRequiredService<InProcessEventBus>();
            var pending = await db.Outbox.Where(m => m.ProcessedAt == null)
                .OrderBy(m => m.CreatedAt).Take(20).ToListAsync(ct);
            foreach (var m in pending)
            {
                try
                {
                    await bus.PublishAsync(JsonSerializer.Deserialize<OrderPlaced>(m.Payload)!, ct);
                    m.ProcessedAt = DateTime.UtcNow;
                    await db.SaveChangesAsync(ct);
                }
                catch (Exception ex) when (ex is not OperationCanceledException)
                {
                    log.LogError(ex, "Outbox message {Id} failed; will retry", m.Id);
                }
            }
        }
    }
}
public static class OrdersModule
{
    public static IServiceCollection AddOrdersModule(this IServiceCollection s, string cs)
    {
        s.AddDbContext<OrdersDbContext>(o =>
            o.UseSqlServer(cs, sql => sql.MigrationsHistoryTable("__EFMigrationsHistory", "orders")));
        s.AddScoped<IOrdersApi, OrdersApi>();
        s.AddHostedService<OutboxDispatcher>();
        return s;
    }
}

Billing reacts to OrderPlaced and sees only Orders.Contracts:

// Billing (internal; references Orders.Contracts and SharedKernel)
internal sealed class Invoice { public Guid OrderId { get; set; } public decimal Amount { get; set; } }
internal sealed class BillingDbContext(DbContextOptions<BillingDbContext> options) : DbContext(options)
{
    public DbSet<Invoice> Invoices => Set<Invoice>();
    protected override void OnModelCreating(ModelBuilder b)
    {
        b.HasDefaultSchema("billing");
        b.Entity<Invoice>().HasKey(i => i.OrderId);
    }
}
internal sealed class CreateInvoiceOnOrderPlaced(BillingDbContext db) : IEventHandler<OrderPlaced>
{
    public async Task HandleAsync(OrderPlaced e, CancellationToken ct)
    {
        if (await db.Invoices.AnyAsync(i => i.OrderId == e.OrderId, ct)) return; // idempotent
        db.Invoices.Add(new Invoice { OrderId = e.OrderId, Amount = e.Total });
        await db.SaveChangesAsync(ct);
    }
}
public static class BillingModule
{
    public static IServiceCollection AddBillingModule(this IServiceCollection s, string cs)
    {
        s.AddDbContext<BillingDbContext>(o =>
            o.UseSqlServer(cs, sql => sql.MigrationsHistoryTable("__EFMigrationsHistory", "billing")));
        s.AddScoped<IEventHandler<OrderPlaced>, CreateInvoiceOnOrderPlaced>();
        return s;
    }
}

Wire it up in Host/Program.cs. Create migrations for each DbContext before running.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddScoped<InProcessEventBus>();
builder.Services
    .AddOrdersModule(builder.Configuration.GetConnectionString("Orders")!)
    .AddBillingModule(builder.Configuration.GetConnectionString("Billing")!);

var app = builder.Build();
app.MapGet("/orders/{id:guid}", async (Guid id, IOrdersApi api, CancellationToken ct) =>
    await api.GetOrderAsync(id, ct) is { } o ? Results.Ok(o) : Results.NotFound());
app.MapPost("/orders", async (PlaceOrderRequest req, IOrdersApi api, CancellationToken ct) =>
    Results.Ok(await api.PlaceOrderAsync(req.Total, ct)));
app.Run();

record PlaceOrderRequest(decimal Total);

Where boundaries really leak

Billing’s types are internal and in another project, so the compiler already blocks direct access to them. The real leaks are raw SQL against another schema, a shared DbContext, and a stray project reference or InternalsVisibleTo.

Block the SQL leak in the database. Give each module its own login, use one connection string per module, and run migrations with a separate admin account:

CREATE LOGIN orders_app WITH PASSWORD = '<secret>';
CREATE USER orders_app FOR LOGIN orders_app;
GRANT SELECT, INSERT, UPDATE, DELETE ON SCHEMA::orders TO orders_app;

Catch the reference leak in CI. The test project must reference every module assembly:

public class ModuleBoundaryTests
{
    static readonly Assembly[] Modules =
        [typeof(OrdersModule).Assembly, typeof(BillingModule).Assembly];

    [Fact]
    public void Module_assemblies_were_found()
    {
        // Guards against a vacuous pass if a module is renamed
        Assert.Equal(["Billing", "Orders"], Modules.Select(m => m.GetName().Name!).Order());
    }

    [Fact]
    public void Modules_do_not_reference_each_other()
    {
        var names = Modules.Select(m => m.GetName().Name!).ToHashSet();
        foreach (var module in Modules)
        {
            var leaked = module.GetReferencedAssemblies()
                .Select(a => a.Name!).Where(n => names.Contains(n) && n != module.GetName().Name);
            Assert.Empty(leaked);
        }
    }
}

This covers every module pair and passes only if they depend on each other’s .Contracts assemblies alone. Add a module to the array when you create it.

When to extract a service

Valid reasons are concrete: independent scaling, separate teams, different deployment cadences, a different tech stack, compliance isolation, or fault isolation with circuit breakers. Trends and résumé-driven design are not on the list. Before extracting, check that:

• the boundary has stayed stable for months,
• only this module owns its data, with no cross-module joins,
• you have measured the bottleneck,
• you have capacity for tracing, auth, deployment and on-call.

Then pick the cleanest module, put an HTTP client behind the existing interface, move its schema to its own database, and keep a rollback path.

internal sealed class HttpOrdersApi(HttpClient http) : IOrdersApi
{
    public async Task<OrderDto?> GetOrderAsync(Guid id, CancellationToken ct)
    {
        using var response = await http.GetAsync($"orders/{id}", ct);
        if (response.StatusCode == HttpStatusCode.NotFound) return null;
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadFromJsonAsync<OrderDto>(ct);
    }

    public async Task<Guid> PlaceOrderAsync(decimal total, CancellationToken ct)
    {
        using var response = await http.PostAsJsonAsync("orders", new { total }, ct);
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadFromJsonAsync<Guid>(ct);
    }
}

public static class OrdersClientExtensions
{
    public static IServiceCollection AddOrdersHttpClient(this IServiceCollection s, Uri baseAddress)
    {
        s.AddHttpClient<IOrdersApi, HttpOrdersApi>(c => c.BaseAddress = baseAddress)
         .AddStandardResilienceHandler(o => o.Retry.DisableForUnsafeHttpMethods());
        return s;
    }
}

The standard handler adds timeouts, retries and a circuit breaker. Disabling retries for POST avoids duplicate orders. Decide how callers see an open circuit or a 5xx.

The outbox dispatcher then has to publish to a broker instead of the in-process bus. Hosting prices and limits change often, so check the provider’s current documentation.

Key takeaways

• Start with one deployable unit and optimize for learning speed.
• Modularity matters more than the deployment model. Enforce it with contracts, per-schema DB permissions and tests.
• Cross-module consistency is not free. Use an outbox and idempotent handlers.
• Extract only for reasons you can name or measure.

FAQ

Can I use a single database and still call it modular?

Yes, if each module owns its schema and nothing else touches it. Enforce that with per-module database permissions, not just convention.

Is a modular monolith overkill for a two-person team?

This is judgement, not evidence. While you are still validating the idea, a plain monolith is fine. Contracts projects and one schema per module cost little, though, and make a later split easier.

Sources and further reading

• Martin Fowler’s Blog, page 34 (includes the MonolithFirst bliki entry, June 3, 2015) (Goodreads (mirror of Martin Fowler’s blog))
• Martin Fowler: Monolithic apps first, microservices later – SD Times (SD Times)
• Monolith First (Three Dots Labs Academy)
• Microservices vs Monolith for Startups: 2026 Architecture Guide (Technijian)
• Monolith vs Microservices in 2026: The Decision Framework Your Engineering Team Needs (DistantJob)
• tagged by: microservices (martinfowler.com)

Images: Image by Innovalabs from Pixabay; Image by This_is_Engineering from Pixabay.

The post Monolith First: Why Startups Should Skip Microservices first appeared on TheCodeBuzz.