Explorar o código

add optimistic row locks for FOR UPDATE and SKIP LOCKED

Locking reads create per-row locks and re-read the row under the lock.
Ordinary writes do not acquire row locks; their durable batch checks the
lock table and fails with 40001 when another transaction holds a written
row. A commit/acquire gate closes the window between the check and
publication.

Supports FOR UPDATE and FOR SHARE on one base table, NOWAIT (55P03), and
SKIP LOCKED. Locking scans do not record table/predicate generations, so
queue workers claiming different rows do not abort each other. Autocommit
locking SELECTs release at statement end; explicit transactions hold until
COMMIT/ROLLBACK. No gap locks or MVCC.
Danilo Fragoso hai 1 semana
pai
achega
679842798f

+ 27 - 0
README.md

@@ -553,6 +553,33 @@ windows, subquery projections, or explicit-transaction overlay validation keep
 the full execution path. Equality predicates inside `AND` can use a primary or
 single-column index lookup; the original predicate is still checked on candidates.
 
+**Row locks:**
+```sql
+BEGIN;
+SELECT id FROM jobs
+ WHERE status = 'pending'
+ ORDER BY id
+ LIMIT 1
+ FOR UPDATE SKIP LOCKED;
+UPDATE jobs SET status = 'processing' WHERE id = ...;
+COMMIT;
+```
+
+`FOR UPDATE` and `FOR SHARE` are supported on one base table, with `NOWAIT`
+(SQLSTATE `55P03`) and `SKIP LOCKED`. Locks are held until `COMMIT`/`ROLLBACK`;
+an autocommit locking SELECT releases at statement end. A locking read re-reads
+each row after acquiring its lock, so it sees a concurrent commit instead of a
+stale image, and a `WHERE` predicate is re-checked after a wait.
+
+Writers do not block on these locks in the current optimistic model: a commit
+that touches a row locked by another transaction fails with `40001` and must be
+retried. The lock holder itself is protected; another worker can never commit
+over the row while the lock is held. There are no gap or predicate locks, so a
+concurrent INSERT that would match a locked range is not blocked. Locks are
+in-process and are not a substitute for MVCC or repeatable-read snapshots.
+`ROLLBACK TO SAVEPOINT` does not release locks acquired after the savepoint;
+they remain held until the transaction ends (stricter than PostgreSQL).
+
 **Indexes:**
 ```sql
 CREATE INDEX idx_users_email ON users(email);

+ 3 - 1
pkg/capabilities/capabilities.go

@@ -217,7 +217,7 @@ func Current() *Document {
 			Model:             "optimistic compare-batch commit; no MVCC or snapshots",
 			Isolation:         "serializable-equivalent for single-row compare-batch commits; write skew is possible across independent rows",
 			SerializationCode: "40001",
-			RowLocks:          Feature{Supported: false, Status: "rejected", SQLState: "0A000", Notes: "SELECT ... FOR UPDATE/SHARE and NOWAIT/SKIP LOCKED are rejected"},
+			RowLocks:          Feature{Supported: true, Status: "optimistic", SQLState: "55P03", Notes: "SELECT ... FOR UPDATE and FOR SHARE on one base table; NOWAIT returns 55P03 and SKIP LOCKED skips contended rows; locks are held until COMMIT/ROLLBACK and released at statement end in autocommit; a concurrent writer that does not hold the lock fails its commit with 40001 instead of blocking; row locks are in-process, and there are no gap or predicate locks, so a concurrent INSERT that would match a locked range is not blocked"},
 			Savepoints:        Feature{Supported: true, Status: "enforced"},
 			RetryRecommended:  true,
 		},
@@ -292,6 +292,8 @@ func Current() *Document {
 			"23503": "foreign_key_violation",
 			"23514": "check_violation",
 			"40001": "serialization_failure",
+			"40P01": "deadlock_detected",
+			"55P03": "lock_not_available",
 			"0A000": "feature_not_supported",
 			"22023": "invalid_parameter_value",
 			"42501": "insufficient_privilege (managed proxy)",

+ 147 - 9
pkg/executor/executor.go

@@ -520,6 +520,15 @@ func (e *Executor) executeSelect(stmt *parser.SelectStmt) (*Result, error) {
 	if e.lockedScanDepth > 0 && !e.fromResolvesToCatalogRelations(stmt.From) {
 		return nil, pgerror.Unsupported("a correlated subquery cannot be evaluated inside a locked table scan; its predicate must not read the row being written")
 	}
+	if stmt.Locking != nil {
+		if err := e.validateLockingSelect(stmt); err != nil {
+			return nil, err
+		}
+		e.session.BeginLockStatement()
+		e.session.BeginLockingRead(stmt.From[0].Name)
+		defer e.session.EndLockingRead()
+		defer e.session.EndLockStatement()
+	}
 	// This SELECT may be a view or CTE body that the statement-level prime never
 	// saw, and its WHERE is pushed into the scan below, so resolve the catalog
 	// snapshot before the scan starts.
@@ -748,7 +757,11 @@ func (e *Executor) executeSelect(stmt *parser.SelectStmt) (*Result, error) {
 			colName, colValue, isEquality := e.extractSelectLookupCondition(condition, stmt.From[0])
 			if isEquality {
 				if schema.IsSingleColumnPrimaryKey() && strings.EqualFold(schema.PrimaryKey, colName) && safePrimaryKeyLiteral(colValue) {
-					row, getErr := e.session.GetByPK(tableName, fmt.Sprintf("%v", colValue))
+					lookup := e.session.GetByPK
+					if stmt.Locking != nil {
+						lookup = e.session.GetByPKNoRead
+					}
+					row, getErr := lookup(tableName, fmt.Sprintf("%v", colValue))
 					if getErr == nil {
 						normalizeRowBySchema(row, schema)
 						rows = []storage.Row{row}
@@ -799,7 +812,7 @@ func (e *Executor) executeSelect(stmt *parser.SelectStmt) (*Result, error) {
 				return toBool(val)
 			}
 		}
-		if limit, bounded := scanLimit(stmt); bounded && (effectiveWhere == nil || canFilterInScan) {
+		if limit, bounded := scanLimit(stmt); stmt.Locking == nil && bounded && (effectiveWhere == nil || canFilterInScan) {
 			rows, err = e.session.SelectLimited(tableName, filter, limit)
 		} else {
 			rows, err = e.session.Select(tableName, filter)
@@ -1458,8 +1471,19 @@ func (e *Executor) executeSelect(stmt *parser.SelectStmt) (*Result, error) {
 		return e.executeAggregateSelect(stmt, rows, schema)
 	}
 
-	// Apply ORDER BY, LIMIT, and OFFSET.
-	rows = e.orderAndLimitRows(rows, stmt.OrderBy, stmt.Limit, stmt.Offset, stmt.Columns)
+	// Apply ORDER BY, LIMIT, and OFFSET. A locking SELECT sorts first, then
+	// locks rows in that order until it has enough candidates, so SKIP LOCKED
+	// can continue past contended rows and LIMIT counts only locked rows.
+	if stmt.Locking != nil {
+		rows = e.orderAndLimitRows(rows, stmt.OrderBy, nil, nil, stmt.Columns)
+		rows, err = e.applyRowLocks(stmt, tableName, schema, effectiveWhere, rows, e.lockingRowLimit(stmt))
+		if err != nil {
+			return nil, err
+		}
+		rows = e.orderAndLimitRows(rows, nil, stmt.Limit, stmt.Offset, stmt.Columns)
+	} else {
+		rows = e.orderAndLimitRows(rows, stmt.OrderBy, stmt.Limit, stmt.Offset, stmt.Columns)
+	}
 
 	// Build result
 	result := NewResult("SELECT")
@@ -5204,6 +5228,17 @@ func (e *Executor) RollbackActive() error {
 
 // extractIndexableCondition extracts column name and value from a simple equality condition.
 // Returns (column, value, true) if the expression is column = literal.
+// parameterLiteral returns the literal inside a bound-parameter marker. The
+// marker is an identity function in the executor, but index and point-update
+// planning must see the value as a constant.
+func parameterLiteral(expr parser.Expr) (*parser.LiteralExpr, bool) {
+	if fn, ok := expr.(*parser.FunctionCall); ok && strings.EqualFold(fn.Name, "PIZZASQL_PARAM") && len(fn.Args) == 1 {
+		return parameterLiteral(fn.Args[0])
+	}
+	lit, ok := expr.(*parser.LiteralExpr)
+	return lit, ok
+}
+
 func (e *Executor) extractIndexableCondition(expr parser.Expr) (string, interface{}, bool) {
 	binExpr, ok := expr.(*parser.BinaryExpr)
 	if !ok {
@@ -5215,27 +5250,130 @@ func (e *Executor) extractIndexableCondition(expr parser.Expr) (string, interfac
 		return "", nil, false
 	}
 
-	// Check for column = literal pattern
+	// Check for column = literal pattern. Bound parameters are inlined as
+	// pizzasql_param(<literal>), so unwrap that marker before deciding whether
+	// this equality can use the primary-key point update.
 	colRef, leftIsCol := binExpr.Left.(*parser.ColumnRef)
-	litExpr, rightIsLit := binExpr.Right.(*parser.LiteralExpr)
-
+	litExpr, rightIsLit := parameterLiteral(binExpr.Right)
 	if leftIsCol && rightIsLit && colRef.Table == "" {
 		val, _ := e.evalLiteral(litExpr)
 		return colRef.Column, val, true
 	}
 
 	// Check for literal = column pattern
-	litExpr, leftIsLit := binExpr.Left.(*parser.LiteralExpr)
+	leftLitExpr, leftIsLit := parameterLiteral(binExpr.Left)
 	colRef, rightIsCol := binExpr.Right.(*parser.ColumnRef)
 
 	if leftIsLit && rightIsCol && colRef.Table == "" {
-		val, _ := e.evalLiteral(litExpr)
+		val, _ := e.evalLiteral(leftLitExpr)
 		return colRef.Column, val, true
 	}
 
 	return "", nil, false
 }
 
+// validateLockingSelect rejects shapes whose row identity is ambiguous. A
+// locking clause is only meaningful for a single base table today; derived
+// tables, joins, set operations, and grouped results would otherwise need a
+// rule for which underlying rows to lock.
+func (e *Executor) validateLockingSelect(stmt *parser.SelectStmt) error {
+	if len(stmt.From) != 1 || stmt.From[0].Subquery != nil || stmt.From[0].Function != nil || stmt.From[0].Join != nil {
+		return pgerror.Unsupported("row locking requires exactly one base table in FROM")
+	}
+	if len(stmt.With) > 0 || stmt.Compound != nil {
+		return pgerror.Unsupported("row locking is not supported on a CTE or compound SELECT")
+	}
+	if stmt.Distinct || len(stmt.GroupBy) > 0 || stmt.Having != nil || e.hasAggregates(stmt.Columns) {
+		return pgerror.Unsupported("row locking is not supported with DISTINCT, GROUP BY, HAVING, or aggregates")
+	}
+	return nil
+}
+
+// lockingRowLimit bounds how many candidates applyRowLocks must acquire before
+// the final OFFSET/LIMIT is applied. A negative result means no limit.
+func (e *Executor) lockingRowLimit(stmt *parser.SelectStmt) int {
+	if stmt.Limit == nil {
+		return -1
+	}
+	limit := e.evalIntExpr(stmt.Limit)
+	if limit < 0 {
+		return -1
+	}
+	offset := 0
+	if stmt.Offset != nil {
+		offset = e.evalIntExpr(stmt.Offset)
+		if offset < 0 {
+			offset = 0
+		}
+	}
+	return offset + limit
+}
+
+// applyRowLocks acquires the requested lock for each candidate, re-reads the row
+// under the lock, and re-checks the predicate. SKIP LOCKED drops contended rows;
+// NOWAIT reports 55P03; blocking modes wait with deadlock detection.
+func (e *Executor) applyRowLocks(stmt *parser.SelectStmt, table string, schema *storage.Schema, where parser.Expr, rows []storage.Row, maxRows int) ([]storage.Row, error) {
+	mode := storage.LockUpdate
+	if stmt.Locking.Strength == parser.LockShare {
+		mode = storage.LockShare
+	}
+	wait := storage.LockWaitBlock
+	switch stmt.Locking.Wait {
+	case parser.LockWaitNoWait:
+		wait = storage.LockWaitNoWait
+	case parser.LockWaitSkipLocked:
+		wait = storage.LockWaitSkip
+	}
+	if maxRows == 0 {
+		return []storage.Row{}, nil
+	}
+	alias := stmt.From[0].Alias
+	locked := make([]storage.Row, 0, len(rows))
+	for _, row := range rows {
+		pk, err := schema.PrimaryKeyForRow(row)
+		if err != nil {
+			return nil, pgerror.Unsupported("row locking requires a table with a primary key")
+		}
+		if err := e.session.AcquireRowLock(table, pk, mode, wait); err != nil {
+			switch {
+			case err == storage.ErrRowLocked && wait == storage.LockWaitSkip:
+				continue
+			case err == storage.ErrLockNotAvailable:
+				return nil, pgerror.LockNotAvailable("could not obtain lock on row")
+			case err == storage.ErrDeadlockDetected:
+				return nil, pgerror.DeadlockDetected("deadlock detected while waiting for a row lock")
+			default:
+				return nil, err
+			}
+		}
+		fresh, err := e.session.GetByPK(table, pk)
+		if err == storage.ErrKeyNotFound {
+			continue
+		}
+		if err != nil {
+			return nil, err
+		}
+		checkRow := fresh
+		if alias != "" {
+			checkRow = e.addTableAlias(fresh, alias)
+		}
+		if where != nil {
+			val, err := e.evalExpr(where, checkRow)
+			if err != nil {
+				return nil, err
+			}
+			if !toBool(val) {
+				continue
+			}
+		}
+		locked = append(locked, checkRow)
+		if maxRows >= 0 && len(locked) >= maxRows {
+			break
+		}
+	}
+	return locked, nil
+}
+
 // Bound only simple scans. Final OFFSET/LIMIT is still applied once by the
 // normal result path; transactions conservatively retain their full read set.
 func scanLimit(stmt *parser.SelectStmt) (int, bool) {

+ 14 - 0
pkg/httpserver/handler.go

@@ -529,6 +529,20 @@ func sqlStateHTTPError(err error) *HTTPError {
 			Message: message,
 		}
 	}
+	if errors.Is(err, pgerror.ErrLockNotAvailable) {
+		return &HTTPError{
+			Status:  http.StatusConflict,
+			Code:    pgerror.CodeLockNotAvailable,
+			Message: message,
+		}
+	}
+	if errors.Is(err, pgerror.ErrDeadlockDetected) {
+		return &HTTPError{
+			Status:  http.StatusConflict,
+			Code:    pgerror.CodeDeadlockDetected,
+			Message: message,
+		}
+	}
 	if strings.Contains(message, "feature not supported:") {
 		return &HTTPError{
 			Status:  http.StatusBadRequest,

+ 25 - 0
pkg/parser/ast.go

@@ -45,6 +45,29 @@ type CompoundSelect struct {
 func (c *CompoundSelect) node()     {}
 func (c *CompoundSelect) stmtNode() {}
 
+// LockStrength is the row-lock mode of a SELECT locking clause.
+type LockStrength int
+
+const (
+	LockUpdate LockStrength = iota
+	LockShare
+)
+
+// LockWait is the contention policy of a SELECT locking clause.
+type LockWait int
+
+const (
+	LockWaitBlock LockWait = iota
+	LockWaitNoWait
+	LockWaitSkipLocked
+)
+
+// LockingClause is the trailing FOR UPDATE/SHARE clause of a SELECT.
+type LockingClause struct {
+	Strength LockStrength
+	Wait     LockWait
+}
+
 // SelectStmt represents a SELECT statement.
 type SelectStmt struct {
 	Distinct bool
@@ -62,6 +85,8 @@ type SelectStmt struct {
 	// SELECT runs. Non-recursive CTEs are desugared by the parser instead; this
 	// list carries recursive CTEs (and the CTEs that depend on them).
 	With []*CTE
+	// Locking is the trailing row-locking clause, or nil.
+	Locking *LockingClause
 }
 
 // CTE is a common table expression from a WITH clause.

+ 38 - 6
pkg/parser/locking_test.go

@@ -8,13 +8,45 @@ import (
 	"github.com/danfragoso/pizzasql-next/pkg/pgerror"
 )
 
-func TestSelectLockingClauseRejected(t *testing.T) {
+func TestSelectLockingClauseParses(t *testing.T) {
+	cases := []struct {
+		sql      string
+		strength LockStrength
+		wait     LockWait
+	}{
+		{"SELECT * FROM t FOR UPDATE", LockUpdate, LockWaitBlock},
+		{"SELECT * FROM t WHERE id = 1 FOR UPDATE NOWAIT", LockUpdate, LockWaitNoWait},
+		{"SELECT * FROM t FOR SHARE", LockShare, LockWaitBlock},
+		{"SELECT id FROM t ORDER BY id LIMIT 10 FOR UPDATE SKIP LOCKED", LockUpdate, LockWaitSkipLocked},
+		{"SELECT * FROM t FOR UPDATE OF t SKIP LOCKED", 0, 0},
+	}
+	for i, tc := range cases {
+		t.Run(tc.sql, func(t *testing.T) {
+			stmt, err := New(lexer.New(tc.sql)).Parse()
+			if i == 4 {
+				if !errors.Is(err, pgerror.ErrFeatureNotSupported) {
+					t.Fatalf("error = %v, want ErrFeatureNotSupported", err)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatal(err)
+			}
+			sel, ok := stmt.(*SelectStmt)
+			if !ok || sel.Locking == nil {
+				t.Fatalf("locking clause missing: %#v", stmt)
+			}
+			if sel.Locking.Strength != tc.strength || sel.Locking.Wait != tc.wait {
+				t.Fatalf("locking = %#v, want %v/%v", sel.Locking, tc.strength, tc.wait)
+			}
+		})
+	}
+}
+
+func TestSelectLockingUnsupportedForms(t *testing.T) {
 	for _, sql := range []string{
-		"SELECT * FROM t FOR UPDATE",
-		"SELECT * FROM t WHERE id = 1 FOR UPDATE NOWAIT",
-		"SELECT * FROM t FOR SHARE",
-		"SELECT * FROM t FOR NO KEY UPDATE SKIP LOCKED",
-		"SELECT id FROM t ORDER BY id LIMIT 10 FOR UPDATE",
+		"SELECT * FROM t FOR NO KEY UPDATE",
+		"SELECT * FROM t FOR KEY SHARE",
 		"SELECT id FROM t UNION SELECT id FROM u FOR UPDATE",
 	} {
 		t.Run(sql, func(t *testing.T) {

+ 44 - 18
pkg/parser/parser.go

@@ -304,9 +304,11 @@ func (p *Parser) parseSelect() (*SelectStmt, error) {
 		stmt.Offset = offset
 	}
 
-	if err := p.rejectLockingClause(); err != nil {
+	locking, err := p.parseLockingClause()
+	if err != nil {
 		return nil, err
 	}
+	stmt.Locking = locking
 
 	return stmt, nil
 }
@@ -443,8 +445,8 @@ func (p *Parser) parseCompoundChain(first *SelectStmt) (*CompoundSelect, error)
 		}
 		compound.Offset = offset
 	}
-	if err := p.rejectLockingClause(); err != nil {
-		return nil, err
+	if p.isLockingClauseStart() {
+		return nil, pgerror.Unsupported("row locking is not supported on a compound SELECT")
 	}
 
 	return compound, nil
@@ -735,24 +737,48 @@ func (p *Parser) isLockingClauseStart() bool {
 	return p.curTokenIs(lexer.TokenIdent) && strings.EqualFold(p.curToken.Literal, "FOR")
 }
 
-// rejectLockingClause rejects SELECT ... FOR UPDATE/SHARE and its NOWAIT / SKIP
-// LOCKED variants. The engine has no row locks; claiming support by parsing the
-// clause would silently provide weaker isolation than PostgreSQL.
-func (p *Parser) rejectLockingClause() error {
+// parseLockingClause parses SELECT ... FOR UPDATE/SHARE [NOWAIT | SKIP LOCKED].
+// FOR is not a reserved keyword in this lexer, so the caller already used
+// isLockingClauseStart to avoid treating it as a table alias.
+func (p *Parser) parseLockingClause() (*LockingClause, error) {
 	if !p.isLockingClauseStart() {
-		return nil
+		return nil, nil
 	}
-	locking := p.peekTokenIs(lexer.TokenUPDATE) ||
-		(p.peekTokenIs(lexer.TokenIdent) &&
-			(strings.EqualFold(p.peekToken.Literal, "SHARE") ||
-				strings.EqualFold(p.peekToken.Literal, "NO") ||
-				strings.EqualFold(p.peekToken.Literal, "KEY")))
-	if !locking {
-		return nil
+	p.nextToken() // consume FOR
+
+	clause := &LockingClause{Strength: LockUpdate}
+	switch {
+	case p.curTokenIs(lexer.TokenUPDATE):
+		p.nextToken()
+	case p.curTokenIs(lexer.TokenIdent) && strings.EqualFold(p.curToken.Literal, "SHARE"):
+		clause.Strength = LockShare
+		p.nextToken()
+	case p.curTokenIs(lexer.TokenIdent) && strings.EqualFold(p.curToken.Literal, "NO"):
+		return nil, pgerror.Unsupported("FOR NO KEY UPDATE is not supported; use FOR UPDATE")
+	case p.curTokenIs(lexer.TokenKEY):
+		return nil, pgerror.Unsupported("FOR KEY SHARE is not supported; use FOR SHARE")
+	default:
+		return nil, p.curError("expected UPDATE or SHARE after FOR")
 	}
-	return pgerror.Unsupported(
-		"SELECT ... FOR UPDATE/SHARE row locking (including NOWAIT and SKIP LOCKED) is not supported; use the documented optimistic transaction model with SQLSTATE 40001 retries instead",
-	)
+
+	if p.curTokenIs(lexer.TokenIdent) && strings.EqualFold(p.curToken.Literal, "OF") {
+		return nil, pgerror.Unsupported("SELECT ... FOR UPDATE OF table is not supported")
+	}
+	if p.curTokenIs(lexer.TokenIdent) {
+		switch {
+		case strings.EqualFold(p.curToken.Literal, "NOWAIT"):
+			clause.Wait = LockWaitNoWait
+			p.nextToken()
+		case strings.EqualFold(p.curToken.Literal, "SKIP"):
+			p.nextToken()
+			if !p.curTokenIs(lexer.TokenIdent) || !strings.EqualFold(p.curToken.Literal, "LOCKED") {
+				return nil, p.curError("expected LOCKED after SKIP")
+			}
+			clause.Wait = LockWaitSkipLocked
+			p.nextToken()
+		}
+	}
+	return clause, nil
 }
 
 func (p *Parser) parseJoin() (*JoinClause, error) {

+ 20 - 0
pkg/pgerror/pgerror.go

@@ -17,6 +17,8 @@ const (
 	CodeForeignKeyViolation    = "23503"
 	CodeCheckViolation         = "23514"
 	CodeSerializationFailure   = "40001"
+	CodeLockNotAvailable       = "55P03"
+	CodeDeadlockDetected       = "40P01"
 	CodeSyntaxError            = "42601"
 	CodeUndefinedTable         = "42P01"
 	CodeInvalidColumnReference = "42P10"
@@ -34,6 +36,24 @@ func UndefinedTable(format string, args ...interface{}) error {
 	return fmt.Errorf("%w: %s", ErrUndefinedTable, fmt.Sprintf(format, args...))
 }
 
+// ErrLockNotAvailable marks a NOWAIT locking read whose row is held by another
+// transaction. Protocol layers map it to SQLSTATE 55P03 (lock_not_available).
+var ErrLockNotAvailable = errors.New("lock not available")
+
+// LockNotAvailable returns a 55P03 error for a contended NOWAIT lock.
+func LockNotAvailable(format string, args ...interface{}) error {
+	return fmt.Errorf("%w: %s", ErrLockNotAvailable, fmt.Sprintf(format, args...))
+}
+
+// ErrDeadlockDetected marks a row-lock wait cycle. Protocol layers map it to
+// SQLSTATE 40P01 (deadlock_detected).
+var ErrDeadlockDetected = errors.New("deadlock detected")
+
+// DeadlockDetected returns a 40P01 error for a wait cycle.
+func DeadlockDetected(format string, args ...interface{}) error {
+	return fmt.Errorf("%w: %s", ErrDeadlockDetected, fmt.Sprintf(format, args...))
+}
+
 // ErrFeatureNotSupported marks SQL that PizzaSQL intentionally rejects instead
 // of accepting with different semantics. Protocol layers map it to SQLSTATE
 // 0A000 (feature_not_supported) rather than a generic syntax or internal error.

+ 2 - 1
pkg/pgserver/compat_suite_test.go

@@ -134,7 +134,8 @@ func TestCompatibilitySuite(t *testing.T) {
 	expectOK("ddl.parenthesized_defaults_insert", `INSERT INTO paren_defaults (id) VALUES (1)`)
 	expectRows("ddl.parenthesized_defaults_applied", `SELECT count(*) FROM paren_defaults WHERE a IS NOT NULL AND b IS NOT NULL`, "1")
 	expectCode("ddl.nonconstant_default_0A000", `CREATE TABLE bad_default (id INTEGER PRIMARY KEY, token TEXT DEFAULT lower('x'))`, "0A000")
-	expectCode("locking.for_update_0A000", `SELECT * FROM accounts FOR UPDATE`, "0A000")
+	expectOK("locking.for_update", `SELECT id FROM accounts FOR UPDATE SKIP LOCKED`)
+	expectCode("locking.for_update_join_0A000", `SELECT accounts.id FROM accounts a JOIN accounts b ON a.id = b.id FOR UPDATE`, "0A000")
 
 	// Array types, array literals, ANY/ALL, and array parameters.
 	expectOK("arrays.ddl", `CREATE TABLE array_values (id INTEGER PRIMARY KEY, tags TEXT[], nums INTEGER[])`)

+ 20 - 0
pkg/pgserver/connection.go

@@ -451,6 +451,16 @@ func (c *Connection) handleQuery(msg *Message) error {
 			if errors.Is(err, storage.ErrSerialization) {
 				code = ErrCodeSerializationFailure
 				c.txStatus = TxStatusIdle
+			} else if errors.Is(err, pgerror.ErrLockNotAvailable) {
+				code = ErrCodeLockNotAvailable
+				if c.txStatus == TxStatusInBlock {
+					c.txStatus = TxStatusFailed
+				}
+			} else if errors.Is(err, pgerror.ErrDeadlockDetected) {
+				code = ErrCodeDeadlockDetected
+				if c.txStatus == TxStatusInBlock {
+					c.txStatus = TxStatusFailed
+				}
 			} else if errors.Is(err, pgerror.ErrInvalidText) {
 				code = ErrCodeInvalidText
 				if c.txStatus == TxStatusInBlock {
@@ -798,6 +808,16 @@ func (c *Connection) classifyExecuteError(stmt parser.Statement, err error) *exe
 	if errors.Is(err, storage.ErrSerialization) {
 		code = ErrCodeSerializationFailure
 		c.txStatus = TxStatusIdle
+	} else if errors.Is(err, pgerror.ErrLockNotAvailable) {
+		code = ErrCodeLockNotAvailable
+		if c.txStatus == TxStatusInBlock {
+			c.txStatus = TxStatusFailed
+		}
+	} else if errors.Is(err, pgerror.ErrDeadlockDetected) {
+		code = ErrCodeDeadlockDetected
+		if c.txStatus == TxStatusInBlock {
+			c.txStatus = TxStatusFailed
+		}
 	} else if errors.Is(err, pgerror.ErrInvalidText) {
 		code = ErrCodeInvalidText
 		if c.txStatus == TxStatusInBlock {

+ 2 - 0
pkg/pgserver/protocol.go

@@ -102,6 +102,8 @@ const (
 	ErrCodeUndefinedCursor        = "34000"
 	ErrCodeTransactionAborted     = "25P02"
 	ErrCodeSerializationFailure   = "40001"
+	ErrCodeLockNotAvailable       = "55P03"
+	ErrCodeDeadlockDetected       = "40P01"
 	ErrCodeUniqueViolation        = "23505"
 	ErrCodeForeignKeyViolation    = "23503"
 	ErrCodeCheckViolation         = "23514"

+ 571 - 0
pkg/pgserver/row_locks_test.go

@@ -0,0 +1,571 @@
+package pgserver
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+
+	"github.com/danfragoso/pizzasql-next/pkg/storage"
+	"github.com/danfragoso/pizzasql-next/pkg/testkv"
+)
+
+// connectPGXPair starts one wire server and returns two independent client
+// connections to the same database so row-lock contention can be exercised.
+func connectPGXPair(t *testing.T) (*pgx.Conn, *pgx.Conn) {
+	t.Helper()
+	conns := connectPGXMany(t, 2)
+	return conns[0], conns[1]
+}
+
+func connectPGXMany(t *testing.T, n int) []*pgx.Conn {
+	t.Helper()
+	kv := testkv.New(t)
+	pool := kv.Pool(8)
+	t.Cleanup(func() { pool.Close() })
+	dbManager := storage.NewDatabaseManager(pool, &storage.DatabaseManagerConfig{
+		DefaultDatabase: "rowlocks",
+		AutoCreate:      true,
+	})
+
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { listener.Close() })
+	var wg sync.WaitGroup
+	t.Cleanup(wg.Wait)
+	go func() {
+		for {
+			server, err := listener.Accept()
+			if err != nil {
+				return
+			}
+			wg.Add(1)
+			go func() {
+				defer wg.Done()
+				_ = NewConnection(server, dbManager, true).Handle()
+			}()
+		}
+	}()
+
+	dsn := "postgres://tester@" + listener.Addr().String() + "/rowlocks?sslmode=disable"
+	connect := func() *pgx.Conn {
+		ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cancel()
+		conn, err := pgx.Connect(ctx, dsn)
+		if err != nil {
+			t.Fatalf("pgx connect: %v", err)
+		}
+		t.Cleanup(func() { _ = conn.Close(context.Background()) })
+		return conn
+	}
+	conns := make([]*pgx.Conn, 0, n)
+	for i := 0; i < n; i++ {
+		conns = append(conns, connect())
+	}
+	return conns
+}
+
+func TestRowLockSkipLockedClaimsOneRowPerTransaction(t *testing.T) {
+	a, b := connectPGXPair(t)
+	ctx := context.Background()
+	for conn, statements := range map[*pgx.Conn][]string{
+		a: {
+			`CREATE TABLE jobs (id INTEGER PRIMARY KEY, status TEXT, owner TEXT)`,
+			`INSERT INTO jobs VALUES (1, 'pending', NULL), (2, 'pending', NULL), (3, 'pending', NULL)`,
+		},
+	} {
+		for _, sql := range statements {
+			if _, err := conn.Exec(ctx, sql); err != nil {
+				t.Fatalf("%s: %v", sql, err)
+			}
+		}
+	}
+
+	claim := func(conn *pgx.Conn, owner string) int32 {
+		tx, err := conn.Begin(ctx)
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer tx.Rollback(ctx)
+		var id int32
+		if err := tx.QueryRow(ctx, `SELECT id FROM jobs WHERE status = 'pending' ORDER BY id LIMIT 1 FOR UPDATE SKIP LOCKED`).Scan(&id); err != nil {
+			t.Fatalf("%s claim: %v", owner, err)
+		}
+		if _, err := tx.Exec(ctx, `UPDATE jobs SET status = 'taken', owner = $1 WHERE id = $2`, owner, id); err != nil {
+			t.Fatalf("%s update: %v", owner, err)
+		}
+		if err := tx.Commit(ctx); err != nil {
+			t.Fatalf("%s commit: %v", owner, err)
+		}
+		return id
+	}
+
+	// The first transaction keeps its lock open while the second claims.
+	tx, err := a.Begin(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer tx.Rollback(ctx)
+	var first int32
+	if err := tx.QueryRow(ctx, `SELECT id FROM jobs WHERE status = 'pending' ORDER BY id LIMIT 1 FOR UPDATE SKIP LOCKED`).Scan(&first); err != nil {
+		t.Fatalf("first claim: %v", err)
+	}
+	if first != 1 {
+		t.Fatalf("first claim = %d, want 1", first)
+	}
+
+	second := claim(b, "b")
+	if second == first {
+		t.Fatalf("both transactions claimed row %d", first)
+	}
+	if _, err := tx.Exec(ctx, `UPDATE jobs SET status = 'taken', owner = 'a' WHERE id = $1`, first); err != nil {
+		t.Fatalf("first update: %v", err)
+	}
+	if err := tx.Commit(ctx); err != nil {
+		t.Fatalf("first commit: %v", err)
+	}
+
+	rows, err := a.Query(ctx, `SELECT id, status, owner FROM jobs ORDER BY id`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer rows.Close()
+	count := 0
+	taken := 0
+	for rows.Next() {
+		var id int32
+		var status string
+		var owner *string
+		if err := rows.Scan(&id, &status, &owner); err != nil {
+			t.Fatal(err)
+		}
+		if status == "taken" {
+			if owner == nil {
+				t.Fatalf("row %d is taken without an owner", id)
+			}
+			taken++
+		} else if id != 3 || status != "pending" {
+			t.Fatalf("row %d = %s/%v, want pending or taken", id, status, owner)
+		}
+		count++
+	}
+	if count != 3 || taken != 2 {
+		t.Fatalf("rows/taken = %d/%d, want 3/2", count, taken)
+	}
+}
+
+func TestRowLockNowaitAndWriterConflict(t *testing.T) {
+	a, b := connectPGXPair(t)
+	ctx := context.Background()
+	if _, err := a.Exec(ctx, `CREATE TABLE jobs (id INTEGER PRIMARY KEY, status TEXT)`); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := a.Exec(ctx, `INSERT INTO jobs VALUES (1, 'pending'), (2, 'pending')`); err != nil {
+		t.Fatal(err)
+	}
+
+	tx, err := a.Begin(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer tx.Rollback(ctx)
+	if _, err := tx.Exec(ctx, `SELECT id FROM jobs WHERE id = 1 FOR UPDATE`); err != nil {
+		t.Fatalf("lock: %v", err)
+	}
+
+	_, err = b.Exec(ctx, `SELECT id FROM jobs WHERE id = 1 FOR UPDATE NOWAIT`)
+	if err == nil || !strings.Contains(err.Error(), "55P03") {
+		t.Fatalf("NOWAIT error = %v, want SQLSTATE 55P03", err)
+	}
+
+	// A writer that does not use a locking clause must not commit over the
+	// lock; it gets the optimistic serialization failure.
+	_, err = b.Exec(ctx, `UPDATE jobs SET status = 'stolen' WHERE id = 1`)
+	if err == nil || !strings.Contains(err.Error(), "40001") {
+		t.Fatalf("writer error = %v, want SQLSTATE 40001", err)
+	}
+}
+
+func TestRowLockBlockingWaitsForCommit(t *testing.T) {
+	a, b := connectPGXPair(t)
+	ctx := context.Background()
+	if _, err := a.Exec(ctx, `CREATE TABLE jobs (id INTEGER PRIMARY KEY, status TEXT)`); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := a.Exec(ctx, `INSERT INTO jobs VALUES (1, 'pending')`); err != nil {
+		t.Fatal(err)
+	}
+
+	tx, err := a.Begin(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := tx.Exec(ctx, `SELECT id FROM jobs WHERE id = 1 FOR UPDATE`); err != nil {
+		t.Fatal(err)
+	}
+
+	done := make(chan error, 1)
+	go func() {
+		var id int32
+		err := b.QueryRow(ctx, `SELECT id FROM jobs WHERE id = 1 FOR UPDATE`).Scan(&id)
+		done <- err
+	}()
+	select {
+	case err := <-done:
+		t.Fatalf("blocking FOR UPDATE returned before commit: %v", err)
+	case <-time.After(150 * time.Millisecond):
+	}
+	if err := tx.Commit(ctx); err != nil {
+		t.Fatal(err)
+	}
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatalf("blocking FOR UPDATE: %v", err)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("blocking FOR UPDATE did not resume")
+	}
+}
+
+func TestRowLockDeadlockDetected(t *testing.T) {
+	a, b := connectPGXPair(t)
+	ctx := context.Background()
+	if _, err := a.Exec(ctx, `CREATE TABLE jobs (id INTEGER PRIMARY KEY)`); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := a.Exec(ctx, `INSERT INTO jobs VALUES (1), (2)`); err != nil {
+		t.Fatal(err)
+	}
+
+	ta, err := a.Begin(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer ta.Rollback(ctx)
+	tb, err := b.Begin(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer tb.Rollback(ctx)
+	if _, err := ta.Exec(ctx, `SELECT id FROM jobs WHERE id = 1 FOR UPDATE`); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := tb.Exec(ctx, `SELECT id FROM jobs WHERE id = 2 FOR UPDATE`); err != nil {
+		t.Fatal(err)
+	}
+
+	blocked := make(chan error, 1)
+	go func() {
+		_, err := ta.Exec(ctx, `SELECT id FROM jobs WHERE id = 2 FOR UPDATE`)
+		blocked <- err
+	}()
+	time.Sleep(100 * time.Millisecond)
+
+	_, err = tb.Exec(ctx, `SELECT id FROM jobs WHERE id = 1 FOR UPDATE`)
+	if err == nil || !strings.Contains(err.Error(), "40P01") {
+		t.Fatalf("deadlock error = %v, want SQLSTATE 40P01", err)
+	}
+	if err := tb.Rollback(ctx); err != nil {
+		t.Fatal(err)
+	}
+	select {
+	case err := <-blocked:
+		if err != nil {
+			t.Fatalf("waiting transaction after deadlock peer rollback: %v", err)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("waiting transaction did not resume")
+	}
+}
+
+func TestRowLockShareAllowsReadersAndBlocksWriter(t *testing.T) {
+	a, b := connectPGXPair(t)
+	ctx := context.Background()
+	if _, err := a.Exec(ctx, `CREATE TABLE jobs (id INTEGER PRIMARY KEY, status TEXT)`); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := a.Exec(ctx, `INSERT INTO jobs VALUES (1, 'pending')`); err != nil {
+		t.Fatal(err)
+	}
+
+	ta, err := a.Begin(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer ta.Rollback(ctx)
+	tb, err := b.Begin(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer tb.Rollback(ctx)
+
+	if _, err := ta.Exec(ctx, `SELECT id FROM jobs WHERE id = 1 FOR SHARE`); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := tb.Exec(ctx, `SELECT id FROM jobs WHERE id = 1 FOR SHARE`); err != nil {
+		t.Fatalf("second FOR SHARE: %v", err)
+	}
+	if _, err := tb.Exec(ctx, `UPDATE jobs SET status = 'taken' WHERE id = 1`); err != nil {
+		t.Fatalf("staging writer: %v", err)
+	}
+	err = tb.Commit(ctx)
+	if err == nil || !strings.Contains(err.Error(), "40001") {
+		t.Fatalf("writer with share lock held error = %v, want 40001", err)
+	}
+}
+
+func TestRowLockAutocommitReleasesImmediately(t *testing.T) {
+	a, b := connectPGXPair(t)
+	ctx := context.Background()
+	if _, err := a.Exec(ctx, `CREATE TABLE jobs (id INTEGER PRIMARY KEY, status TEXT)`); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := a.Exec(ctx, `INSERT INTO jobs VALUES (1, 'pending')`); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := a.Exec(ctx, `SELECT id FROM jobs WHERE id = 1 FOR UPDATE`); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := b.Exec(ctx, `UPDATE jobs SET status = 'taken' WHERE id = 1`); err != nil {
+		t.Fatalf("autocommit lock was not released: %v", err)
+	}
+}
+
+func TestRowLockQueueWorkersDoNotDoubleClaim(t *testing.T) {
+	const workers = 4
+	const jobs = 40
+	conns := connectPGXMany(t, workers)
+	ctx := context.Background()
+	if _, err := conns[0].Exec(ctx, `CREATE TABLE jobs (id INTEGER PRIMARY KEY, status TEXT, owner TEXT)`); err != nil {
+		t.Fatal(err)
+	}
+	var insert strings.Builder
+	insert.WriteString(`INSERT INTO jobs VALUES `)
+	for i := 1; i <= jobs; i++ {
+		if i > 1 {
+			insert.WriteString(", ")
+		}
+		fmt.Fprintf(&insert, "(%d, 'pending', NULL)", i)
+	}
+	if _, err := conns[0].Exec(ctx, insert.String()); err != nil {
+		t.Fatal(err)
+	}
+
+	var wg sync.WaitGroup
+	errs := make(chan error, workers)
+	for w, conn := range conns {
+		wg.Add(1)
+		go func(w int, conn *pgx.Conn) {
+			defer wg.Done()
+			owner := fmt.Sprintf("worker-%d", w)
+			for {
+				tx, err := conn.Begin(ctx)
+				if err != nil {
+					errs <- err
+					return
+				}
+				var id int32
+				err = tx.QueryRow(ctx, `SELECT id FROM jobs WHERE status = 'pending' ORDER BY id LIMIT 1 FOR UPDATE SKIP LOCKED`).Scan(&id)
+				if err != nil {
+					_ = tx.Rollback(ctx)
+					if err == pgx.ErrNoRows {
+						return
+					}
+					errs <- err
+					return
+				}
+				if _, err := tx.Exec(ctx, `UPDATE jobs SET status = 'taken', owner = $1 WHERE id = $2`, owner, id); err != nil {
+					_ = tx.Rollback(ctx)
+					errs <- err
+					return
+				}
+				if err := tx.Commit(ctx); err != nil {
+					errs <- err
+					return
+				}
+			}
+		}(w, conn)
+	}
+	wg.Wait()
+	close(errs)
+	for err := range errs {
+		t.Fatalf("worker error: %v", err)
+	}
+
+	var taken, pending int
+	if err := conns[0].QueryRow(ctx, `SELECT COUNT(*) FROM jobs WHERE status = 'taken'`).Scan(&taken); err != nil {
+		t.Fatal(err)
+	}
+	if err := conns[0].QueryRow(ctx, `SELECT COUNT(*) FROM jobs WHERE status = 'pending'`).Scan(&pending); err != nil {
+		t.Fatal(err)
+	}
+	if taken != jobs || pending != 0 {
+		t.Fatalf("taken/pending = %d/%d, want %d/0", taken, pending, jobs)
+	}
+	var distinctOwners int
+	if err := conns[0].QueryRow(ctx, `SELECT COUNT(DISTINCT id) FROM jobs`).Scan(&distinctOwners); err != nil {
+		t.Fatal(err)
+	}
+	if distinctOwners != jobs {
+		t.Fatalf("distinct ids = %d, want %d", distinctOwners, jobs)
+	}
+}
+
+func TestRowLockAliasedTableAndEmptySkip(t *testing.T) {
+	a, b := connectPGXPair(t)
+	ctx := context.Background()
+	if _, err := a.Exec(ctx, `CREATE TABLE jobs (id INTEGER PRIMARY KEY, status TEXT)`); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := a.Exec(ctx, `INSERT INTO jobs VALUES (1, 'pending'), (2, 'pending')`); err != nil {
+		t.Fatal(err)
+	}
+
+	tx, err := a.Begin(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer tx.Rollback(ctx)
+	var id int32
+	if err := tx.QueryRow(ctx, `SELECT j.id FROM jobs AS j WHERE j.id = 1 FOR UPDATE`).Scan(&id); err != nil {
+		t.Fatalf("aliased locking select: %v", err)
+	}
+	if id != 1 {
+		t.Fatalf("aliased id = %d", id)
+	}
+	if err := tx.Commit(ctx); err != nil {
+		t.Fatal(err)
+	}
+
+	// Hold both rows, then confirm SKIP LOCKED reports no candidate.
+	ta, err := a.Begin(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer ta.Rollback(ctx)
+	if _, err := ta.Exec(ctx, `SELECT id FROM jobs FOR UPDATE`); err != nil {
+		t.Fatal(err)
+	}
+	tb, err := b.Begin(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer tb.Rollback(ctx)
+	var n int32
+	if err := tb.QueryRow(ctx, `SELECT id FROM jobs WHERE status = 'pending' LIMIT 1 FOR UPDATE SKIP LOCKED`).Scan(&n); err != pgx.ErrNoRows {
+		t.Fatalf("all-locked SKIP LOCKED = %v, want ErrNoRows", err)
+	}
+}
+
+func TestRowLockRollbackReleases(t *testing.T) {
+	a, b := connectPGXPair(t)
+	ctx := context.Background()
+	if _, err := a.Exec(ctx, `CREATE TABLE jobs (id INTEGER PRIMARY KEY, status TEXT)`); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := a.Exec(ctx, `INSERT INTO jobs VALUES (1, 'pending')`); err != nil {
+		t.Fatal(err)
+	}
+	tx, err := a.Begin(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := tx.Exec(ctx, `SELECT id FROM jobs WHERE id = 1 FOR UPDATE`); err != nil {
+		t.Fatal(err)
+	}
+	if err := tx.Rollback(ctx); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := b.Exec(ctx, `UPDATE jobs SET status = 'taken' WHERE id = 1`); err != nil {
+		t.Fatalf("rollback did not release lock: %v", err)
+	}
+}
+
+func TestRowLockBlocksAutocommitDDL(t *testing.T) {
+	a, b := connectPGXPair(t)
+	ctx := context.Background()
+	if _, err := a.Exec(ctx, `CREATE TABLE jobs (id INTEGER PRIMARY KEY, status TEXT)`); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := a.Exec(ctx, `INSERT INTO jobs VALUES (1, 'pending')`); err != nil {
+		t.Fatal(err)
+	}
+	tx, err := a.Begin(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer tx.Rollback(ctx)
+	if _, err := tx.Exec(ctx, `SELECT id FROM jobs FOR UPDATE`); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := b.Exec(ctx, `ALTER TABLE jobs ADD COLUMN note TEXT`); err == nil || !strings.Contains(err.Error(), "40001") {
+		t.Fatalf("DDL with row lock held error = %v, want 40001", err)
+	}
+}
+
+func TestRowLockSyntheticRowIDTable(t *testing.T) {
+	a, _ := connectPGXPair(t)
+	ctx := context.Background()
+	if _, err := a.Exec(ctx, `CREATE TABLE notes (body TEXT)`); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := a.Exec(ctx, `INSERT INTO notes VALUES ('hello')`); err != nil {
+		t.Fatal(err)
+	}
+	var body string
+	if err := a.QueryRow(ctx, `SELECT body FROM notes FOR UPDATE`).Scan(&body); err != nil {
+		t.Fatalf("locking synthetic-rowid table: %v", err)
+	}
+	if body != "hello" {
+		t.Fatalf("body = %q", body)
+	}
+}
+
+func TestRowLockSkippedPrimaryKeyDoesNotPoisonCommit(t *testing.T) {
+	a, b := connectPGXPair(t)
+	ctx := context.Background()
+	if _, err := a.Exec(ctx, `CREATE TABLE jobs (id INTEGER PRIMARY KEY, status TEXT)`); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := a.Exec(ctx, `INSERT INTO jobs VALUES (1, 'pending'), (2, 'pending')`); err != nil {
+		t.Fatal(err)
+	}
+
+	ta, err := a.Begin(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := ta.Exec(ctx, `SELECT id FROM jobs WHERE id = 1 FOR UPDATE`); err != nil {
+		t.Fatal(err)
+	}
+
+	tb, err := b.Begin(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var id int32
+	if err := tb.QueryRow(ctx, `SELECT id FROM jobs WHERE id = 1 FOR UPDATE SKIP LOCKED`).Scan(&id); err != pgx.ErrNoRows {
+		t.Fatalf("skipped primary key = %v, want ErrNoRows", err)
+	}
+	if _, err := tb.Exec(ctx, `UPDATE jobs SET status = 'b' WHERE id = 2`); err != nil {
+		t.Fatal(err)
+	}
+
+	if _, err := ta.Exec(ctx, `UPDATE jobs SET status = 'a' WHERE id = 1`); err != nil {
+		t.Fatal(err)
+	}
+	if err := ta.Commit(ctx); err != nil {
+		t.Fatal(err)
+	}
+	if err := tb.Commit(ctx); err != nil {
+		t.Fatalf("skipped read poisoned commit: %v", err)
+	}
+}

+ 23 - 5
pkg/pgserver/unsupported_locking_test.go

@@ -31,15 +31,33 @@ func errorField(t *testing.T, msg *Message, want byte) string {
 	return ""
 }
 
-func TestLockingClauseRejectedOverSimpleQuery(t *testing.T) {
+func TestLockingClauseSupportedShapeOverSimpleQuery(t *testing.T) {
 	c, client := newDataConnection(t)
 	runQuery(t, c, client, &Message{Type: MsgQuery, Data: append([]byte("CREATE TABLE t (id INTEGER PRIMARY KEY)"), 0)})
 
 	msgs := runQuery(t, c, client, &Message{Type: MsgQuery, Data: append([]byte("SELECT * FROM t FOR UPDATE"), 0)})
-	if code := errorCode(msgs[0]); code != ErrCodeFeatureNotSupported {
-		t.Fatalf("error code = %q, want %q", code, ErrCodeFeatureNotSupported)
+	if code := errorCode(msgs[0]); code != "" {
+		t.Fatalf("locking query error = %q", code)
 	}
-	if message := errorField(t, msgs[0], ErrorFieldMessage); !bytes.Contains([]byte(message), []byte("row locking")) {
-		t.Fatalf("error message = %q, want a row-locking explanation", message)
+}
+
+func TestLockingClauseRejectsUnsupportedShapes(t *testing.T) {
+	c, client := newDataConnection(t)
+	for _, sql := range []string{
+		"CREATE TABLE t (id INTEGER PRIMARY KEY)",
+		"CREATE TABLE u (id INTEGER PRIMARY KEY)",
+	} {
+		runQuery(t, c, client, &Message{Type: MsgQuery, Data: append([]byte(sql), 0)})
+	}
+	for _, sql := range []string{
+		"SELECT * FROM t a JOIN u b ON a.id = b.id FOR UPDATE",
+		"SELECT COUNT(*) FROM t FOR UPDATE",
+		"SELECT DISTINCT id FROM t FOR UPDATE",
+		"SELECT id FROM t UNION SELECT id FROM u FOR UPDATE",
+	} {
+		msgs := runQuery(t, c, client, &Message{Type: MsgQuery, Data: append([]byte(sql), 0)})
+		if code := errorCode(msgs[0]); code != ErrCodeFeatureNotSupported {
+			t.Fatalf("%s: error code = %q, want %q", sql, code, ErrCodeFeatureNotSupported)
+		}
 	}
 }

+ 368 - 0
pkg/storage/rowlock.go

@@ -0,0 +1,368 @@
+package storage
+
+import (
+	"errors"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+)
+
+// Row-lock contention outcomes. ErrRowLocked is intentionally reported to the
+// client as a serialization failure (40001): the optimistic commit model makes
+// a conflicting writer retry rather than block.
+var (
+	ErrRowLocked        = errors.New("row is locked by another transaction")
+	ErrLockNotAvailable = errors.New("row lock is not available")
+	ErrDeadlockDetected = errors.New("deadlock detected")
+)
+
+// LockMode is the strength of a locking read.
+type LockMode uint8
+
+const (
+	LockUpdate LockMode = iota
+	LockShare
+)
+
+// LockWait is the contention policy of a locking read.
+type LockWait uint8
+
+const (
+	LockWaitBlock LockWait = iota
+	LockWaitNoWait
+	LockWaitSkip
+)
+
+type rowLockEntry struct {
+	mu     sync.Mutex
+	closed bool
+	owners map[*Session]LockMode
+	// waiters are signalled when an owner releases. A waiter retries the
+	// acquisition instead of receiving ownership directly: a release can wake
+	// several compatible readers.
+	waiters map[chan struct{}]struct{}
+}
+
+func (e *rowLockEntry) ownerList() []*Session {
+	owners := make([]*Session, 0, len(e.owners))
+	for owner := range e.owners {
+		owners = append(owners, owner)
+	}
+	return owners
+}
+
+// RowLockManager holds in-process row locks. Locking reads create entries;
+// ordinary writes do not. A write checks the entries at its durable batch
+// boundary and fails with ErrSerialization if another transaction holds one.
+//
+// gate is a reader/writer gate around lock insertion checks and the write-side
+// check. A write holds it for reading from the check through publication, so a
+// lock cannot be inserted in the window between "no lock seen" and "committed".
+// Waiting for a row lock never holds gate.
+type RowLockManager struct {
+	gate    sync.RWMutex
+	entries sync.Map // string (data key) -> *rowLockEntry
+	active  atomic.Int64
+
+	waitMu sync.Mutex
+	waits  map[*Session]*Session
+}
+
+func NewRowLockManager() *RowLockManager {
+	return &RowLockManager{waits: make(map[*Session]*Session)}
+}
+
+// Active reports whether any row locks are currently held. Callers use it to
+// skip the map scan on the normal, lock-free path.
+func (l *RowLockManager) Active() bool {
+	l.gate.RLock()
+	defer l.gate.RUnlock()
+	return l.active.Load() > 0
+}
+
+func (l *RowLockManager) entry(key string) (*rowLockEntry, bool) {
+	value, ok := l.entries.Load(key)
+	if !ok {
+		return nil, false
+	}
+	return value.(*rowLockEntry), true
+}
+
+// tryLock acquires key if it is free or compatible. The caller must hold gate.
+func (l *RowLockManager) tryLock(owner *Session, key string, mode LockMode) (bool, *Session) {
+	e, ok := l.entry(key)
+	if !ok {
+		e = &rowLockEntry{owners: make(map[*Session]LockMode), waiters: make(map[chan struct{}]struct{})}
+		e.owners[owner] = mode
+		l.entries.Store(key, e)
+		l.active.Add(1)
+		return true, nil
+	}
+	e.mu.Lock()
+	if e.closed {
+		// A concurrent Release deleted this entry after we loaded it. We hold
+		// gate for writing, so it is safe to replace it with a fresh entry.
+		e.mu.Unlock()
+		e = &rowLockEntry{owners: make(map[*Session]LockMode), waiters: make(map[chan struct{}]struct{})}
+		e.owners[owner] = mode
+		l.entries.Store(key, e)
+		l.active.Add(1)
+		return true, nil
+	}
+	defer e.mu.Unlock()
+	if current, held := e.owners[owner]; held {
+		if current == LockUpdate || mode == LockShare {
+			return true, nil
+		}
+		// Upgrade FOR SHARE to FOR UPDATE only when no other reader holds one.
+		if len(e.owners) == 1 {
+			e.owners[owner] = LockUpdate
+			return true, nil
+		}
+		for other := range e.owners {
+			return false, other
+		}
+	}
+	if len(e.owners) == 0 {
+		e.owners[owner] = mode
+		return true, nil
+	}
+	if mode == LockShare {
+		compatible := true
+		var other *Session
+		for holder, held := range e.owners {
+			if held == LockUpdate {
+				compatible = false
+				other = holder
+				break
+			}
+		}
+		if compatible {
+			e.owners[owner] = LockShare
+			return true, nil
+		}
+		return false, other
+	}
+	for other := range e.owners {
+		return false, other
+	}
+	return false, nil
+}
+
+// Acquire obtains a row lock. Skip and NoWait return immediately when the row is
+// contended; Block waits until it is free and reports a deadlock as
+// ErrDeadlockDetected.
+func (l *RowLockManager) Acquire(owner *Session, key string, mode LockMode, wait LockWait) error {
+	for {
+		l.gate.Lock()
+		ok, other := l.tryLock(owner, key, mode)
+		l.gate.Unlock()
+		if ok {
+			return nil
+		}
+		switch wait {
+		case LockWaitNoWait:
+			return ErrLockNotAvailable
+		case LockWaitSkip:
+			return ErrRowLocked
+		}
+		if err := l.waitFor(owner, key, other); err != nil {
+			return err
+		}
+	}
+}
+
+func (l *RowLockManager) waitFor(owner *Session, key string, other *Session) error {
+	e, ok := l.entry(key)
+	if !ok {
+		return nil
+	}
+	ch := make(chan struct{})
+	e.mu.Lock()
+	// The owner may have released and removed the entry after tryLock returned
+	// but before we enqueued. Re-check under the entry lock so we never sleep on
+	// a detached entry.
+	current, present := l.entry(key)
+	if !present || current != e || len(e.owners) == 0 {
+		e.mu.Unlock()
+		return nil
+	}
+	e.waiters[ch] = struct{}{}
+	e.mu.Unlock()
+
+	l.waitMu.Lock()
+	l.waits[owner] = other
+	deadlock := l.hasCycleLocked(owner)
+	if deadlock {
+		delete(l.waits, owner)
+	} else {
+		l.waits[owner] = other
+	}
+	l.waitMu.Unlock()
+	if deadlock {
+		e.mu.Lock()
+		delete(e.waiters, ch)
+		e.mu.Unlock()
+		return ErrDeadlockDetected
+	}
+	defer func() {
+		l.waitMu.Lock()
+		if l.waits[owner] == other {
+			delete(l.waits, owner)
+		}
+		l.waitMu.Unlock()
+	}()
+
+	select {
+	case <-ch:
+		return nil
+	// A genuine cycle is detected by the wait-for graph immediately; this is a
+	// last-resort guard against a lost wake-up, not a lock timeout.
+	case <-time.After(5 * time.Minute):
+		e.mu.Lock()
+		delete(e.waiters, ch)
+		e.mu.Unlock()
+		return ErrDeadlockDetected
+	}
+}
+
+func (l *RowLockManager) hasCycleLocked(start *Session) bool {
+	seen := map[*Session]bool{}
+	cur := start
+	for cur != nil {
+		if seen[cur] {
+			return cur == start
+		}
+		seen[cur] = true
+		cur = l.waits[cur]
+	}
+	return false
+}
+
+// Release drops one owner's hold on key and wakes waiters.
+func (l *RowLockManager) Release(owner *Session, key string) {
+	e, ok := l.entry(key)
+	if !ok {
+		return
+	}
+	e.mu.Lock()
+	delete(e.owners, owner)
+	empty := len(e.owners) == 0
+	waiters := make([]chan struct{}, 0, len(e.waiters))
+	if empty || len(e.owners) == 0 {
+		for ch := range e.waiters {
+			waiters = append(waiters, ch)
+		}
+		e.waiters = make(map[chan struct{}]struct{})
+	}
+	if empty {
+		e.closed = true
+		l.entries.Delete(key)
+		l.active.Add(-1)
+	}
+	e.mu.Unlock()
+	for _, ch := range waiters {
+		close(ch)
+	}
+}
+
+// ReleaseAll drops every lock held by owner. It is used at transaction end,
+// rollback, and failed commit. It intentionally does not take gate: releasing a
+// lock can never invalidate an in-flight commit, and resetLocked may call it
+// while a commit still holds gate for reading.
+func (l *RowLockManager) ReleaseAll(owner *Session) {
+	l.entries.Range(func(key, value interface{}) bool {
+		e := value.(*rowLockEntry)
+		e.mu.Lock()
+		delete(e.owners, owner)
+		empty := len(e.owners) == 0
+		var waiters []chan struct{}
+		if empty {
+			e.closed = true
+			waiters = make([]chan struct{}, 0, len(e.waiters))
+			for ch := range e.waiters {
+				waiters = append(waiters, ch)
+			}
+			e.waiters = make(map[chan struct{}]struct{})
+			l.entries.Delete(key)
+			l.active.Add(-1)
+		}
+		e.mu.Unlock()
+		for _, ch := range waiters {
+			close(ch)
+		}
+		return true
+	})
+	l.waitMu.Lock()
+	delete(l.waits, owner)
+	l.waitMu.Unlock()
+}
+
+// BeginWrite holds the commit gate for reading and verifies that no other
+// transaction holds any of keys. The returned function must be called after the
+// durable batch is published. Holding gate across publication is what makes a
+// lock acquisition and a write mutually exclusive.
+func (l *RowLockManager) BeginWrite(owner *Session, keys, tablePrefixes []string) (func(), error) {
+	l.gate.RLock()
+	if l.active.Load() == 0 {
+		return l.gate.RUnlock, nil
+	}
+	for _, key := range keys {
+		e, ok := l.entry(key)
+		if !ok {
+			continue
+		}
+		e.mu.Lock()
+		conflict := false
+		for holder := range e.owners {
+			if holder != owner {
+				conflict = true
+				break
+			}
+		}
+		e.mu.Unlock()
+		if conflict {
+			l.gate.RUnlock()
+			return nil, ErrRowLocked
+		}
+	}
+	if len(tablePrefixes) > 0 {
+		conflict := false
+		l.entries.Range(func(key, value interface{}) bool {
+			k := key.(string)
+			matched := false
+			for _, prefix := range tablePrefixes {
+				if strings.HasPrefix(k, prefix) {
+					matched = true
+					break
+				}
+			}
+			if !matched {
+				return true
+			}
+			e := value.(*rowLockEntry)
+			e.mu.Lock()
+			for holder := range e.owners {
+				if holder != owner {
+					conflict = true
+					break
+				}
+			}
+			e.mu.Unlock()
+			return !conflict
+		})
+		if conflict {
+			l.gate.RUnlock()
+			return nil, ErrRowLocked
+		}
+	}
+	return l.gate.RUnlock, nil
+}
+
+// BeginTableWrite is the coarse check used by autocommit bulk/DDL operations
+// whose exact row keys are not known before the scan. It rejects the write if
+// any other transaction holds a row lock in the table.
+func (l *RowLockManager) BeginTableWrite(owner *Session, prefix string) (func(), error) {
+	return l.BeginWrite(owner, nil, []string{prefix})
+}

+ 76 - 0
pkg/storage/rowlock_test.go

@@ -0,0 +1,76 @@
+package storage
+
+import (
+	"errors"
+	"testing"
+	"time"
+)
+
+func TestRowLocksModesAndWriteGuard(t *testing.T) {
+	m := NewRowLockManager()
+	a, b, c := &Session{}, &Session{}, &Session{}
+	key := "db:_data:t:1"
+
+	if err := m.Acquire(a, key, LockUpdate, LockWaitBlock); err != nil {
+		t.Fatal(err)
+	}
+	if err := m.Acquire(b, key, LockShare, LockWaitSkip); !errors.Is(err, ErrRowLocked) {
+		t.Fatalf("contended share = %v, want ErrRowLocked", err)
+	}
+	if err := m.Acquire(b, key, LockShare, LockWaitNoWait); !errors.Is(err, ErrLockNotAvailable) {
+		t.Fatalf("contended nowait = %v, want ErrLockNotAvailable", err)
+	}
+	if _, err := m.BeginWrite(b, []string{key}, nil); !errors.Is(err, ErrRowLocked) {
+		t.Fatalf("write with another owner's lock = %v, want ErrRowLocked", err)
+	}
+	release, err := m.BeginWrite(a, []string{key}, nil)
+	if err != nil {
+		t.Fatalf("owner write guard: %v", err)
+	}
+	release()
+	m.Release(a, key)
+
+	if err := m.Acquire(a, key, LockShare, LockWaitBlock); err != nil {
+		t.Fatal(err)
+	}
+	if err := m.Acquire(b, key, LockShare, LockWaitBlock); err != nil {
+		t.Fatalf("compatible share: %v", err)
+	}
+	if err := m.Acquire(c, key, LockUpdate, LockWaitNoWait); !errors.Is(err, ErrLockNotAvailable) {
+		t.Fatalf("update over shares = %v, want ErrLockNotAvailable", err)
+	}
+	m.ReleaseAll(a)
+	if err := m.Acquire(c, key, LockUpdate, LockWaitNoWait); !errors.Is(err, ErrLockNotAvailable) {
+		t.Fatalf("update with one share left = %v, want ErrLockNotAvailable", err)
+	}
+	m.ReleaseAll(b)
+	if m.Active() {
+		t.Fatal("locks remain active after ReleaseAll")
+	}
+}
+
+func TestRowLockBlockingReleaseWakesWaiter(t *testing.T) {
+	m := NewRowLockManager()
+	a, b := &Session{}, &Session{}
+	key := "db:_data:t:2"
+	if err := m.Acquire(a, key, LockUpdate, LockWaitBlock); err != nil {
+		t.Fatal(err)
+	}
+	done := make(chan error, 1)
+	go func() { done <- m.Acquire(b, key, LockUpdate, LockWaitBlock) }()
+	select {
+	case err := <-done:
+		t.Fatalf("waiter returned before release: %v", err)
+	case <-time.After(50 * time.Millisecond):
+	}
+	m.ReleaseAll(a)
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatal(err)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("waiter did not wake")
+	}
+	m.ReleaseAll(b)
+}

+ 11 - 9
pkg/storage/schema_tx.go

@@ -1373,7 +1373,7 @@ func (s *Session) DropTable(name string) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	if s.schemaTx == nil {
-		return s.schema.DropTable(name)
+		return s.guardTable(name, func() error { return s.schema.DropTable(name) })
 	}
 	return s.stageDDL(func(tx *SchemaTx) error { return tx.dropTable(name) })
 }
@@ -1386,10 +1386,12 @@ func (s *Session) CreateIndex(index *Index) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	if s.schemaTx == nil {
-		if index.Unique {
-			return s.table.CreateUniqueIndex(index)
-		}
-		return s.schema.CreateIndex(index)
+		return s.guardTable(index.Table, func() error {
+			if index.Unique {
+				return s.table.CreateUniqueIndex(index)
+			}
+			return s.schema.CreateIndex(index)
+		})
 	}
 	return s.stageDDL(func(tx *SchemaTx) error {
 		if err := tx.createIndex(index); err != nil {
@@ -1443,7 +1445,7 @@ func (s *Session) AddColumn(table string, column Column, checks []CheckConstrain
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	if s.schemaTx == nil {
-		return s.schema.AddColumn(table, column, checks, unique)
+		return s.guardTable(table, func() error { return s.schema.AddColumn(table, column, checks, unique) })
 	}
 	return s.stageDDL(func(tx *SchemaTx) error { return tx.addColumn(table, column, checks, unique) })
 }
@@ -1454,7 +1456,7 @@ func (s *Session) DropColumn(table, columnName string) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	if s.schemaTx == nil {
-		return s.schema.DropColumn(table, columnName)
+		return s.guardTable(table, func() error { return s.schema.DropColumn(table, columnName) })
 	}
 	return s.stageDDL(func(tx *SchemaTx) error { return tx.dropColumn(table, columnName) })
 }
@@ -1465,7 +1467,7 @@ func (s *Session) RenameTable(oldName, newName string) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	if s.schemaTx == nil {
-		return s.schema.RenameTable(oldName, newName)
+		return s.guardTable(oldName, func() error { return s.schema.RenameTable(oldName, newName) })
 	}
 	return s.stageDDL(func(tx *SchemaTx) error { return tx.renameTable(oldName, newName) })
 }
@@ -1476,7 +1478,7 @@ func (s *Session) RenameColumn(table, oldName, newName string) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	if s.schemaTx == nil {
-		return s.schema.RenameColumn(table, oldName, newName)
+		return s.guardTable(table, func() error { return s.schema.RenameColumn(table, oldName, newName) })
 	}
 	return s.stageDDL(func(tx *SchemaTx) error { return tx.renameColumn(table, oldName, newName) })
 }

+ 8 - 0
pkg/storage/table.go

@@ -67,6 +67,10 @@ type TableManager struct {
 	generations          map[string]uint64
 	predicateGenerations map[string]uint64
 
+	// rowLocks holds optimistic row locks created by SELECT ... FOR UPDATE.
+	// Ordinary writes only consult it at their commit/batch boundary.
+	rowLocks *RowLockManager
+
 	// exprMu guards exprEval, the pluggable evaluator for expression-index
 	// columns. It is set by the SQL executor so storage stays independent of
 	// the SQL front end.
@@ -111,9 +115,13 @@ func NewTableManager(pool *KVPool, schema *SchemaManager, database string) *Tabl
 		countGeneration:      make(map[string]time.Time),
 		generations:          make(map[string]uint64),
 		predicateGenerations: make(map[string]uint64),
+		rowLocks:             NewRowLockManager(),
 	}
 }
 
+// RowLocks returns the manager for locking reads on this table set.
+func (m *TableManager) RowLocks() *RowLockManager { return m.rowLocks }
+
 func (m *TableManager) tableLock(key string) *sync.RWMutex {
 	return m.schema.tableLock(key)
 }

+ 193 - 22
pkg/storage/tx.go

@@ -26,6 +26,17 @@ type Session struct {
 	inTx    bool
 	aborted bool
 
+	// autoLocks is true while a locking SELECT without an explicit transaction
+	// holds its statement-scoped row locks.
+	autoLocks bool
+
+	// lockingRead suppresses table/predicate generation tracking while a
+	// locking SELECT scans. A row lock plus the per-row LSN is the conflict
+	// boundary for that read; recording a whole-table generation would abort
+	// every queue worker whenever another worker claimed a different row.
+	lockingRead  bool
+	lockingTable string
+
 	// overlay holds staged writes keyed by lowercased table then data key.
 	overlay map[string]map[string]*overlayEntry
 
@@ -103,6 +114,80 @@ func (s *Session) Begin() error {
 	return nil
 }
 
+// BeginLockStatement starts the statement-scoped lock lifetime used by an
+// autocommit SELECT ... FOR UPDATE. Inside an explicit transaction the locks
+// already live until COMMIT/ROLLBACK, so this is a no-op.
+func (s *Session) BeginLockStatement() {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if !s.inTx {
+		s.autoLocks = true
+	}
+}
+
+// EndLockStatement releases statement-scoped row locks after an autocommit
+// locking SELECT.
+func (s *Session) EndLockStatement() {
+	s.mu.Lock()
+	release := !s.inTx && s.autoLocks
+	s.autoLocks = false
+	s.mu.Unlock()
+	if release {
+		s.table.rowLocks.ReleaseAll(s)
+	}
+}
+
+// RowLockKey returns the durable row key used by the row-lock manager.
+func (s *Session) RowLockKey(table, pk string) string {
+	return s.table.dataKey(table, pk)
+}
+
+// AcquireRowLock takes a row lock for a locking SELECT. The caller must hold the
+// row lock before returning the row to the client and must re-read the row after
+// acquisition, because another transaction may have committed in between.
+func (s *Session) AcquireRowLock(table, pk string, mode LockMode, wait LockWait) error {
+	return s.table.rowLocks.Acquire(s, s.RowLockKey(table, pk), mode, wait)
+}
+
+// guardKeys holds the row-lock commit gate while fn publishes a durable write,
+// and rejects the write if another transaction holds one of keys.
+func (s *Session) guardKeys(keys []string, fn func() error) error {
+	release, err := s.table.rowLocks.BeginWrite(s, keys, nil)
+	if err != nil {
+		return fmt.Errorf("%w: %v", ErrSerialization, err)
+	}
+	defer release()
+	return fn()
+}
+
+// guardTable is the coarse guard for autocommit bulk writes whose exact keys
+// are not known before the scan.
+func (s *Session) guardTable(table string, fn func() error) error {
+	release, err := s.table.rowLocks.BeginTableWrite(s, s.table.dataPrefix(table))
+	if err != nil {
+		return fmt.Errorf("%w: %v", ErrSerialization, err)
+	}
+	defer release()
+	return fn()
+}
+
+// BeginLockingRead marks scans of table as row-locking reads. Reads of other
+// tables in subqueries keep normal phantom tracking.
+func (s *Session) BeginLockingRead(table string) {
+	s.mu.Lock()
+	s.lockingRead = true
+	s.lockingTable = table
+	s.mu.Unlock()
+}
+
+// EndLockingRead restores normal phantom tracking.
+func (s *Session) EndLockingRead() {
+	s.mu.Lock()
+	s.lockingRead = false
+	s.lockingTable = ""
+	s.mu.Unlock()
+}
+
 // InTx reports whether a transaction is in progress.
 func (s *Session) InTx() bool {
 	s.mu.Lock()
@@ -276,6 +361,29 @@ func (s *Session) CommitWithLSN() (uint64, error) {
 	// removes their durable rows.
 	hasDDL := s.schemaTx != nil && s.schemaTx.hasDDL()
 
+	// Row locks are optimistic: a write that touches a row locked by another
+	// transaction fails with 40001 instead of waiting. Hold the lock-manager
+	// read gate from this check through publication so a locking SELECT cannot
+	// insert a lock in the window between the check and the durable batch.
+	writeKeys := make([]string, 0)
+	for _, entries := range s.overlay {
+		for key := range entries {
+			writeKeys = append(writeKeys, key)
+		}
+	}
+	var ddlPrefixes []string
+	if hasDDL {
+		for _, table := range s.schemaTx.touchedTables() {
+			ddlPrefixes = append(ddlPrefixes, s.table.dataPrefix(table))
+		}
+	}
+	releaseRowLocks, lockErr := s.table.rowLocks.BeginWrite(s, writeKeys, ddlPrefixes)
+	if lockErr != nil {
+		s.resetLocked()
+		return 0, fmt.Errorf("%w: %v", ErrSerialization, lockErr)
+	}
+	defer releaseRowLocks()
+
 	// Lock order for every path that touches both a table and the catalog is
 	// session lock -> foreign-key write gate -> table gates (sorted by name) ->
 	// schema catalog mutex. Table gates are plain sync.RWMutex values and are
@@ -779,6 +887,12 @@ func (s *Session) hasUniqueIndexLocked(table string) (bool, error) {
 	return false, nil
 }
 
+// lockingTableIs reports whether table is the main table of the active
+// locking SELECT, whose rows are covered by explicit row locks.
+func (s *Session) lockingTableIs(table string) bool {
+	return s.lockingRead && strings.EqualFold(table, s.lockingTable)
+}
+
 func (s *Session) resetLocked() {
 	s.inTx = false
 	s.aborted = false
@@ -790,6 +904,10 @@ func (s *Session) resetLocked() {
 	s.schemaTx = nil
 	s.fkCatalog = nil
 	s.fkVersion = 0
+	s.autoLocks = false
+	s.lockingRead = false
+	s.lockingTable = ""
+	s.table.rowLocks.ReleaseAll(s)
 }
 
 func (s *Session) stagePut(table, key string, row Row) {
@@ -821,6 +939,17 @@ func (s *Session) stageDelete(table, key string, row Row) {
 // GetByPK retrieves a row by primary key, observing the staged overlay in a
 // transaction and recording the observed LSN for validation.
 func (s *Session) GetByPK(table, pk string) (Row, error) {
+	return s.getByPK(table, pk, true)
+}
+
+// GetByPKNoRead is GetByPK without recording the durable LSN. A locking SELECT
+// uses it for the pre-lock candidate lookup: the read is only part of the
+// transaction's conflict set once the row lock has actually been acquired.
+func (s *Session) GetByPKNoRead(table, pk string) (Row, error) {
+	return s.getByPK(table, pk, false)
+}
+
+func (s *Session) getByPK(table, pk string, recordRead bool) (Row, error) {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	if !s.inTx {
@@ -838,12 +967,16 @@ func (s *Session) GetByPK(table, pk string) (Row, error) {
 	row, lsn, err := s.table.getKeyWithLSN(durableKey)
 	if err != nil {
 		if err == ErrKeyNotFound {
-			s.reads[durableKey] = 0
+			if recordRead {
+				s.reads[durableKey] = 0
+			}
 			return nil, ErrKeyNotFound
 		}
 		return nil, err
 	}
-	s.reads[durableKey] = lsn
+	if recordRead {
+		s.reads[durableKey] = lsn
+	}
 	if err := s.applyStagedRewritesLocked(table, row); err != nil {
 		return nil, err
 	}
@@ -920,13 +1053,15 @@ func (s *Session) selectLocked(table string, filter func(Row) bool) ([]Row, erro
 	tableLock := s.table.tableLock(tl)
 	tableLock.RLock()
 	defer tableLock.RUnlock()
-	if _, ok := s.scanGens[tl]; !ok {
-		s.scanGens[tl] = s.table.generation(tl)
+	if !s.lockingTableIs(table) {
+		if _, ok := s.scanGens[tl]; !ok {
+			s.scanGens[tl] = s.table.generation(tl)
+		}
 	}
 	overlay := s.overlay[tl]
 	source := s.durableSourceLocked(table)
 	sourceLower := strings.ToLower(source)
-	if sourceLower != tl {
+	if sourceLower != tl && !s.lockingTableIs(table) {
 		// A concurrent write to the committed name must invalidate the commit
 		// just like a write to the staged name.
 		if _, ok := s.scanGens[sourceLower]; !ok {
@@ -943,7 +1078,9 @@ func (s *Session) selectLocked(table string, filter func(Row) bool) ([]Row, erro
 		if _, ok := overlay[s.table.dataKey(table, pk)]; ok {
 			return false, nil
 		}
-		s.reads[durableKey] = lsn
+		if !s.lockingTableIs(table) {
+			s.reads[durableKey] = lsn
+		}
 		if err := s.applyStagedRewritesLocked(table, row); err != nil {
 			return true, err
 		}
@@ -1008,11 +1145,13 @@ func (s *Session) SelectByIndex(table, indexName string, colValue interface{}) (
 	if err != nil {
 		return nil, err
 	}
-	if _, ok := s.predicateGens[predicate.valueKey]; !ok {
-		s.predicateGens[predicate.valueKey] = predicateRead{table: tableKey, gen: predicate.valueGen}
-	}
-	if _, ok := s.predicateGens[predicate.wildcardKey]; !ok {
-		s.predicateGens[predicate.wildcardKey] = predicateRead{table: tableKey, gen: predicate.wildcardGen}
+	if !s.lockingTableIs(table) {
+		if _, ok := s.predicateGens[predicate.valueKey]; !ok {
+			s.predicateGens[predicate.valueKey] = predicateRead{table: tableKey, gen: predicate.valueGen}
+		}
+		if _, ok := s.predicateGens[predicate.wildcardKey]; !ok {
+			s.predicateGens[predicate.wildcardKey] = predicateRead{table: tableKey, gen: predicate.wildcardGen}
+		}
 	}
 	overlay := s.overlay[tableKey]
 	rows := make([]Row, 0, len(versions)+len(overlay))
@@ -1020,7 +1159,9 @@ func (s *Session) SelectByIndex(table, indexName string, colValue interface{}) (
 		if _, staged := overlay[version.key]; staged {
 			continue
 		}
-		s.reads[version.key] = version.lsn
+		if !s.lockingTableIs(table) {
+			s.reads[version.key] = version.lsn
+		}
 		if err := s.applyStagedRewritesLocked(table, version.row); err != nil {
 			return nil, err
 		}
@@ -1061,11 +1202,13 @@ func (s *Session) SelectByIndexKey(table string, idx *Index, valueKey string) ([
 	if err != nil {
 		return nil, err
 	}
-	if _, ok := s.predicateGens[predicate.valueKey]; !ok {
-		s.predicateGens[predicate.valueKey] = predicateRead{table: tableKey, gen: predicate.valueGen}
-	}
-	if _, ok := s.predicateGens[predicate.wildcardKey]; !ok {
-		s.predicateGens[predicate.wildcardKey] = predicateRead{table: tableKey, gen: predicate.wildcardGen}
+	if !s.lockingTableIs(table) {
+		if _, ok := s.predicateGens[predicate.valueKey]; !ok {
+			s.predicateGens[predicate.valueKey] = predicateRead{table: tableKey, gen: predicate.valueGen}
+		}
+		if _, ok := s.predicateGens[predicate.wildcardKey]; !ok {
+			s.predicateGens[predicate.wildcardKey] = predicateRead{table: tableKey, gen: predicate.wildcardGen}
+		}
 	}
 	overlay := s.overlay[tableKey]
 	rows := make([]Row, 0, len(versions)+len(overlay))
@@ -1073,7 +1216,9 @@ func (s *Session) SelectByIndexKey(table string, idx *Index, valueKey string) ([
 		if _, staged := overlay[version.key]; staged {
 			continue
 		}
-		s.reads[version.key] = version.lsn
+		if !s.lockingTableIs(table) {
+			s.reads[version.key] = version.lsn
+		}
 		if err := s.applyStagedRewritesLocked(table, version.row); err != nil {
 			return nil, err
 		}
@@ -1242,7 +1387,14 @@ func (s *Session) UpdateByPK(table, pk string, updateFn func(Row) (Row, error))
 			return nil, false, err
 		}
 		if !cascading {
-			return s.table.UpdateByPK(table, pk, updateFn)
+			var row Row
+			var updated bool
+			err := s.guardKeys([]string{s.RowLockKey(table, pk)}, func() error {
+				var err error
+				row, updated, err = s.table.UpdateByPK(table, pk, updateFn)
+				return err
+			})
+			return row, updated, err
 		}
 		oldRow, updated, err := s.updateByPKStaged(table, pk, updateFn)
 		unlockFK()
@@ -1329,7 +1481,14 @@ func (s *Session) DeleteByPK(table, pk string) (Row, bool, error) {
 			return nil, false, err
 		}
 		if !cascading {
-			return s.table.DeleteByPK(table, pk)
+			var row Row
+			var deleted bool
+			err := s.guardKeys([]string{s.RowLockKey(table, pk)}, func() error {
+				var err error
+				row, deleted, err = s.table.DeleteByPK(table, pk)
+				return err
+			})
+			return row, deleted, err
 		}
 		row, deleted, err := s.deleteByPKStaged(table, pk)
 		unlockFK()
@@ -1405,7 +1564,13 @@ func (s *Session) UpdateFunc(table string, updateFn func(Row) (Row, error), filt
 	s.mu.Lock()
 	if !s.inTx {
 		s.mu.Unlock()
-		return s.table.UpdateFunc(table, updateFn, filter)
+		var count int
+		err := s.guardTable(table, func() error {
+			var err error
+			count, err = s.table.UpdateFunc(table, updateFn, filter)
+			return err
+		})
+		return count, err
 	}
 	defer s.mu.Unlock()
 
@@ -1453,7 +1618,13 @@ func (s *Session) Delete(table string, filter func(Row) bool) (int, error) {
 	s.mu.Lock()
 	if !s.inTx {
 		s.mu.Unlock()
-		return s.table.Delete(table, filter)
+		var count int
+		err := s.guardTable(table, func() error {
+			var err error
+			count, err = s.table.Delete(table, filter)
+			return err
+		})
+		return count, err
 	}
 	defer s.mu.Unlock()