> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer Basics

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

Before you start using CockroachDB, you should understand the following important mechanics of the database:

* [How transactions work in CockroachDB](#how-transactions-work-in-cockroachdb), including [serializability](#serializability-and-transaction-contention) and [transaction retries](#transaction-retries)
* [How applications interact with CockroachDB](#how-applications-interact-with-cockroachdb)

Note that the sections that follow were written for the purposes of orienting application developers. For more detailed technical documentation on CockroachDB's architecture, see our <InternalLink path="architecture/overview">architecture documentation</InternalLink>.

### How transactions work in CockroachDB

CockroachDB is designed to make your data scalable and consistent. All stored records are replicated across a distributed deployment of database instances, and all database transactions committed in CockroachDB satisfy [ACID properties](https://en.wikipedia.org/wiki/ACID).

To guarantee that database operations are [atomic](https://wikipedia.org/wiki/Atomicity_\(database_systems\)) (the "A" of the [ACID properties](https://en.wikipedia.org/wiki/ACID)), CockroachDB executes all statements in the context of an atomic [database transaction](https://wikipedia.org/wiki/Database_transaction). If a transaction succeeds, all data mutations are applied together simultaneously from the perspective of operations outside of the transaction. If any part of a transaction fails, the entire transaction is aborted, and the database is left unchanged.

Managing transactions is an important part of CockroachDB application development. When creating your application's persistence layer, you must understand how CockroachDB interacts with your application framework's transaction management system. You should also have some knowledge of CockroachDB's <InternalLink path="transactions#syntax">transaction syntax</InternalLink>. We go into more detail about transaction management in <InternalLink path="transactions">Manage Transactions</InternalLink>.

#### Serializability and transaction contention

By default, CockroachDB uses <InternalLink path="demo-serializable">`SERIALIZABLE`</InternalLink> transaction [isolation](https://wikipedia.org/wiki/Isolation_\(database_systems\)) (the "I" of ACID semantics). If transactions are executed concurrently, the final state of the database will appear as if the transactions were executed serially. `SERIALIZABLE` isolation, the strictest level of isolation, provides the highest level of data consistency and protects against concurrency anomalies.

To guarantee data consistency, CockroachDB <InternalLink path="architecture/transaction-layer#concurrency-control">locks</InternalLink> the data targeted by an open transaction. If a separate transaction attempts to modify data that are locked by an open transaction, the newest transaction will not succeed, as committing it could result in incorrect data. This scenario is called *transaction contention*, and should be avoided when possible. For a more detailed explanation of transaction contention, and tips on how to avoid it, see <InternalLink path="performance-best-practices-overview#transaction-contention">Transaction contention</InternalLink>.

#### Transaction retries

In some cases, <InternalLink path="performance-best-practices-overview#transaction-contention">transaction contention</InternalLink> is unavoidable. If a transaction fails due to contention, CockroachDB will automatically retry the transaction. If the transaction is `SERIALIZABLE` and cannot automatically be retried without allowing <InternalLink path="demo-serializable">serialization</InternalLink> anomalies, CockroachDB will return a <InternalLink path="transaction-retry-error-reference">transaction retry error</InternalLink> to the client.

Most <InternalLink path="install-client-drivers">official CockroachDB client libraries</InternalLink> include a transaction-retrying wrapper function to make writing your persistence layer easier. If your framework's client library does not include a retry wrapper, you will need to write transaction retry logic in your application. We go into more detail about transaction retries later in the guide, in <InternalLink path="advanced-client-side-transaction-retries">Retry Transactions</InternalLink>.

#### Read Committed isolation

CockroachDB can be configured to execute transactions at <InternalLink path="read-committed">`READ COMMITTED`</InternalLink> instead of `SERIALIZABLE` isolation. `READ COMMITTED` permits some concurrency anomalies in exchange for minimizing transaction aborts and removing the need for client-side retries. Depending on your workload requirements, this may be desirable. For more information, see <InternalLink path="read-committed">Read Committed Transactions</InternalLink>.

### How applications interact with CockroachDB

CockroachDB supports the PostgreSQL wire protocol, and CockroachDB supports <InternalLink path="postgresql-compatibility">most PostgreSQL syntax and features</InternalLink>, making most PostgreSQL client libraries compatible with CockroachDB. Cockroach Labs also maintains official CockroachDB adapters for some of the most popular PostgreSQL drivers and ORMs. Using an official CockroachDB adapter can help simplify transaction management and performance optimization in your application. If an official CockroachDB adapter does not yet exist for your application's data framework, we recommend just using the PostgreSQL client library that works for your application.

A growing number of popular third-party database tools offer full support for CockroachDB. Because CockroachDB uses the PostgreSQL wire protocol and supports PostgreSQL syntax, most PostgreSQL-compatible third-party tools are also compatible with CockroachDB. For a list of libraries and tools that we have tested against CockroachDB, see <InternalLink path="third-party-database-tools">Third-party Database Tools</InternalLink>.