> ## 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 a couple important mechanics of the database:

* [How transactions work in CockroachDB](#how-transactions-work-in-cockroachdb)
  * [Serializability and transaction contention](#serializability-and-transaction-contention)
  * [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

CockroachDB guarantees [`SERIALIZABLE`](https://wikipedia.org/wiki/Serializability) 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-based attacks and bugs.

To guarantee `SERIALIZABLE` isolation, CockroachDB <InternalLink path="crdb-internal#cluster_locks">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 a violation of the `SERIALIZABLE` isolation level. 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">Understand and Avoid 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, or 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>.

### 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>.