A fast recap of what problem QLDB was built to solve, framed for someone past the introductory pitch.

QLDB is a purpose-built ledger database: every change to every document is appended to an immutable, cryptographically chained journal, and the “tables” you query with PartiQL are really just a materialized, indexed view over that journal’s history. The pitch that matters at the intermediate level isn’t “immutable data” by itself — plenty of databases can be made append-only with discipline. It’s that QLDB gives you a built-in, mathematically verifiable proof that a document’s history has not been altered, without you having to build and operate that proof system yourself.

This distinguishes QLDB from two adjacent categories: general-purpose relational databases with manual audit tables (where nothing stops a privileged user from editing the audit log itself), and blockchain frameworks (which add decentralized consensus overhead that most single-organization systems don’t actually need).

The vocabulary intermediate QLDB work depends on — journal, revisions, and the document model.

Journal — the append-only, sequential log that is the actual source of truth for a QLDB ledger. Every insert, update, and delete is recorded here first, permanently, in the order it was committed.

Document Revision — QLDB never overwrites a document in place. An “update” creates a new revision of the document with an incremented version number and a pointer back to its predecessor, so the full history of every document is always retrievable.

Amazon Ion — QLDB’s underlying data format, a superset of JSON that adds richer types (timestamps, precise decimals, binary blobs) while remaining structurally JSON-compatible; every document you store is, at the storage layer, an Ion value.

PartiQL — the SQL-compatible query language QLDB exposes over its document-oriented storage. It supports familiar SELECT, INSERT, UPDATE, and DELETE syntax while operating over semi-structured, nested Ion documents rather than fixed relational rows.

Tables — logical, named partitions of the journal that behave like relational tables for query purposes, but are really just filtered, indexed views over the subset of journal entries tagged to that table.

How the journal, indexed storage, and streams layer fit together.

• Journal Storage — the durable, append-only, replicated log; the authoritative record every other component derives from.
• Indexed Storage — a queryable, materialized representation of the current and historical document state, built from the journal, that PartiQL actually executes against for performance.
• QLDB Streams — a continuous, near-real-time export of journal changes to an Amazon Kinesis Data Stream, letting other systems react to every committed revision as it happens.
• Ledger Permissions Mode — STANDARD mode enforces IAM-based, table- and PartiQL-statement-level permissions; the older ALLOW_ALL mode grants any authenticated principal full access and is generally discouraged for new ledgers.

flowchart TB
  App["Application
QLDB Driver"] --> API["QLDB Session API"]
  API --> Journal["Journal Storage
(append-only, replicated)"]
  Journal --> Indexed["Indexed Storage
(queryable tables)"]
  Journal --> Streams["QLDB Streams"]
  Streams --> Kinesis["Amazon Kinesis Data Stream"]
  Kinesis --> Consumers["Downstream Consumers
Lambda / Analytics / Search"]
  API --> Indexed
        

The cryptography behind “you can mathematically prove this data wasn’t tampered with.”

Every block of committed transactions in the journal is hashed, and those hashes are combined pairwise up through a Merkle tree until they produce a single root hash called a digest. Because each new block’s hash incorporates the hash of everything before it, changing even one byte of historical data would change every hash above it in the tree — making tampering mathematically detectable rather than merely policy-forbidden.

QLDB lets you request a digest of the ledger at any point in time, and separately request a proof for a specific document revision. Using the digest, the proof, and the revision’s own hash, you (or an independent auditor, with no access to the live system at all) can recompute the Merkle path and confirm the revision genuinely belongs to that verified history — this is the mechanism that makes QLDB’s “cryptographically verifiable” claim something you can actually check, not just something AWS asserts.

What happens between calling a write and it being durably, verifiably committed — and why conflicts are normal, not exceptional.

QLDB uses optimistic concurrency control (OCC) rather than locking. A transaction reads the documents it needs, computes its changes, and attempts to commit; QLDB checks whether any of the documents the transaction read have been modified by another transaction since it started. If so, the commit is rejected with an OccConflictException, and the application is expected to retry the transaction from the beginning.

sequenceDiagram
    participant App as Application
    participant QLDB as QLDB Session
    App->>QLDB: Begin transaction
    App->>QLDB: SELECT balance FROM Accounts WHERE id = 'A1'
    QLDB-->>App: balance = 500
    App->>QLDB: UPDATE Accounts SET balance = 400 WHERE id = 'A1'
    App->>QLDB: Commit
    alt No conflicting write since read
        QLDB-->>App: Commit succeeds, new revision appended
    else Another transaction modified A1 first
        QLDB-->>App: OccConflictException — retry transaction
    end
        

Turning the cryptographic theory from Chapter 4 into an operational habit.

A typical verification workflow looks like this: periodically request and securely store a ledger digest (for example, exporting it to a separate, access-controlled location outside the QLDB ledger itself). Later — during an audit, a dispute, or a compliance review — retrieve the specific document revision in question along with its proof, and independently recompute whether that revision’s hash resolves correctly against the previously stored digest.

The value of this workflow depends entirely on storing digests somewhere independent of the ledger’s own administrators. A digest that only ever lives inside the same AWS account with the same permissions as the ledger offers weaker guarantees than one exported to a separate trust boundary — the cryptography only protects you as well as your operational discipline around where the digest itself lives.

Turning an immutable journal into a live feed other systems can react to.

QLDB Streams delivers every committed revision to a Kinesis Data Stream in near real time, in the order it was committed. This is what lets QLDB act as a system of record while other systems stay in sync without polling: a Lambda function can react to every new revision, a search index can be updated incrementally, or an analytics pipeline can build a running materialized view without ever querying the ledger directly for bulk exports.

What actually limits throughput in a ledger database, and why it isn’t the same as a typical OLTP system.

Because every write is a serialized append to a single ledger’s journal, and OCC conflicts increase under high contention on the same documents, QLDB’s write scalability is bounded less by raw storage throughput and more by how much your write pattern contends over the same rows. A workload that spreads writes across many independent documents scales comfortably; a workload with many concurrent writers repeatedly updating the same few “hot” documents will see a rising rate of OCC retries under load.

Reads against indexed storage scale independently of write contention, since they’re served from the materialized, indexed view rather than replaying the journal — but query performance still depends heavily on whether you’ve created indexes on the fields your PartiQL queries filter on, exactly as with a conventional database.

What QLDB manages for you, and what durability guarantee that actually buys.

You may likeAWS IAM→

QLDB automatically replicates journal data across multiple Availability Zones within a Region, and as a fully managed service, AWS handles the underlying replication, scaling, and failure recovery without requiring you to provision or manage database instances, unlike a self-managed relational database on EC2.

Access control layered on top of an already-tamper-evident data model.

• IAM-based access control — in STANDARD permissions mode, IAM policies can restrict access down to specific PartiQL statement types and specific tables, rather than granting blanket ledger access.
• Encryption at rest — every ledger is encrypted using a KMS key, either AWS-owned by default or a customer-managed key for organizations needing direct control over key rotation and revocation.
• VPC endpoints — QLDB supports private connectivity via VPC endpoints, so traffic between your application and the ledger never needs to traverse the public internet.
• Encryption in transit — all API calls to QLDB are made over TLS by default through the standard AWS SDK/API request signing process.

The signals that tell you whether your ledger is healthy under load.

CloudTrail logs every QLDB API call for administrative auditing, complementing — but not replacing — the cryptographic, data-level verification the journal itself provides.

How QLDB is provisioned and reached from application and analytics tooling.

Ledgers, tables, and indexes are typically provisioned through Infrastructure as Code so that permissions mode, KMS key configuration, and table/index definitions stay consistent and auditable across environments — a natural fit given that consistency of configuration matters as much as consistency of data in a compliance-oriented system.

What ledger-style modeling looks like when done well — and the mistake that undermines the whole point.

You may likeAmazon Lightsail→

Event-sourced document design — modeling each meaningful business event (a payment, a status change, an approval) as its own document revision rather than mutating a single summary field repeatedly plays to QLDB’s strengths, since the full history of “what happened and when” becomes the natural query surface rather than something you have to reconstruct after the fact.

Narrow, single-purpose tables — keeping tables scoped to one well-defined entity type, with indexes on the fields you actually filter by, keeps both query performance and OCC contention predictable as write volume grows.

The categories of system where a verifiable ledger earns its complexity.