Section 29: Database Access and Transaction Semantics¶

TECHSPEC-29 — Section 29 · Version 0.1 · Status: Initial Draft

Status: draft. This section is an Initial Draft (Section 57 is a Working Register). It describes intended or proposed behavior, not a finalized, implemented language rule. Do not treat examples here as normative.

1. Database Philosophy¶

Database operations must be explicit, permission-controlled, and transaction-aware.

The language must prevent accidental data modification, unhandled database failures, and false claims that a change was permanently committed.

A successful query, an executed statement, and a committed transaction are distinct events.

2. Database Effects¶

Database operations must declare their effects.

Supported effects include:

• DATABASE.CONNECT: Establish a database connection.
• DATABASE.READ: Retrieve stored data.
• DATABASE.CREATE: Insert records.
• DATABASE.MODIFY: Update records.
• DATABASE.DELETE: Remove records.
• DATABASE.SCHEMA: Modify database structure.
• DATABASE.TRANSACTION: Begin, commit, or roll back transactions.

Effects must propagate through the call graph.

3. Explicit Database Access¶

Database access must use documented standard-library APIs or explicitly imported database drivers.

Example:

FUNCTION findAccount(
    accountId: Integer
) -> Result<Optional<Account>, DatabaseError>

    REQUIRES: accountId > 0
    EFFECTS: DATABASE.READ

    LET result = Database.query<Account>(
        "SELECT * FROM accounts WHERE id = ?",
        [accountId]
    )

    RETURN result

END FUNCTION

This example illustrates the intended contract. The final query API and parameter-binding syntax remain to be defined.

Rules: - Database access must be explicit. - Queries must use parameterized values rather than unsafe string concatenation. - Query results must have declared destination types. - Missing records must be distinguishable from query failures. - Database permissions must be declared. - Database access must not occur through hidden side effects.

4. Transactions¶

A transaction groups database operations under defined commit and rollback behavior.

Example:

TRANSACTION:
    INSERT account
    INSERT initial_transaction
    COMMIT

Rules: - Transaction boundaries must be explicit. - A transaction must have a defined completion outcome. - Successful commit and successful rollback must be distinguishable. - Failed operations must not be reported as committed. - Uncommitted transactions must not silently remain open. - Nested transaction behavior must be explicitly defined. - Transaction cleanup must occur when execution exits unexpectedly, subject to the database driver's capabilities.

5. Transaction Guarantees¶

The language must expose the guarantees provided by the underlying database.

Where supported, transactions should document ACID properties:

• Atomicity: The transaction's operations are committed together or rolled back together.
• Consistency: Database constraints remain satisfied.
• Isolation: Concurrent transactions interact according to the selected isolation level.
• Durability: A confirmed commit satisfies the database's documented persistence guarantees.

Rules: - The language must not claim stronger guarantees than the database provides. - Isolation levels must be explicit or use a documented default. - Serialization conflicts and deadlocks must produce identifiable failures. - A commit acknowledgment must not be confused with guarantees beyond the database's documented durability behavior.

6. Schema and Type Mapping¶

Database values must be mapped to language types through explicit conversion rules.

Rules: - Column types must be compatible with destination types. - Null database values must map to Optional<T> or another explicitly defined representation. - Numeric precision must be preserved where supported. - Invalid conversions must produce explicit errors. - Database constraints must not be assumed to replace application-level validation. - Schema changes must be tracked and versioned.

7. Database Security¶

Database access must follow least-privilege principles.

Rules: - Credentials must not be embedded in source code. - Database permissions must be declared. - Read and write permissions must be distinguishable. - Schema modification requires separate authorization. - Query parameters must be bound safely. - Sensitive records and credentials must not appear in ordinary logs. - Untrusted input must never be treated as trusted query syntax. - Dependencies must not automatically inherit database permissions.

8. Concurrent Access¶

Concurrent database operations must have defined behavior.

Rules: - Shared connections must follow documented concurrency restrictions. - Transaction ownership must be explicit. - Concurrent modifications must respect database isolation guarantees. - Deadlocks and serialization conflicts must be observable. - Retries must account for whether the previous transaction may already have committed. - The language must not assume that an unsuccessful client response proves a transaction was rolled back.

9. Error Handling¶

Database failures must use structured error types.

Possible failures include: - Connection failure. - Authentication failure. - Permission denied. - Query syntax error. - Constraint violation. - Record not found. - Type conversion failure. - Transaction conflict. - Deadlock. - Timeout. - Transaction rollback. - Commit outcome uncertain. - Resource exhaustion.

Errors must preserve useful underlying causes without exposing credentials or sensitive data.

10. Compiler and Runtime Responsibilities¶

The compiler and runtime must: - Enforce declared database effects. - Enforce database permissions. - Validate query parameter and result types where possible. - Track transaction ownership and completion. - Require explicit handling of transaction failures. - Prevent unsafe query construction through supported APIs. - Preserve database error information. - Distinguish query execution from transaction commitment. - Report uncertain transaction outcomes honestly.

11. Verification Limitations¶

The language cannot independently guarantee that a database is available, correctly configured, or internally reliable.

Database guarantees depend on the database engine, configuration, storage system, and network.

Verification reports must distinguish: - Database permission declared. - Permission granted. - Connection established. - Query executed. - Transaction committed. - Commit durability established according to the database's documented guarantees. - Transaction outcome uncertain.

12. Design Goal¶

An AI agent must be able to identify every database operation, its permissions, its transaction boundaries, and the actual guarantees established by its completion.

Executing a database statement must never be confused with successfully committing the intended data change.

Source and related sections¶

Source file: TECHSPEC-29.md (preserved in source-original/LANG/). See the specification index, the glossary, and the cross-reference index.