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

# Insert Data

This page has instructions for getting data into CockroachDB with various programming languages, using the [`INSERT`](https://docs.cockroachlabs.com/docs/v24.1/insert) SQL statement.

## Before you begin

Before reading this page, do the following:

* [Create a CockroachDB Standard cluster](https://docs.cockroachlabs.com/docs/cockroachcloud/quickstart.md) or [start a local cluster](https://docs.cockroachlabs.com/docs/cockroachcloud/quickstart.md?filters=local).
* [Install a Driver or ORM Framework](https://docs.cockroachlabs.com/docs/v24.1/install-client-drivers.md).
* [Connect to the database](https://docs.cockroachlabs.com/docs/v24.1/connect-to-the-database.md).

> [!NOTE]
>
> When running under the default [`SERIALIZABLE`](https://docs.cockroachlabs.com/docs/v24.1/demo-serializable) isolation level, your application should [use a retry loop to handle transaction retry errors](https://docs.cockroachlabs.com/docs/v24.1/query-behavior-troubleshooting.md#transaction-retry-errors) that can occur under [contention](https://docs.cockroachlabs.com/docs/v24.1/performance-best-practices-overview.md#understanding-and-avoiding-transaction-contention).

## Insert rows

When inserting multiple rows, a single [multi-row insert statement](https://docs.cockroachlabs.com/docs/v24.1/insert.md#insert-multiple-rows-into-an-existing-table) is faster than multiple single-row statements.

> [tab] SQL
>
> ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> CREATE TABLE IF NOT EXISTS accounts (id INT PRIMARY KEY, balance INT);
> INSERT INTO accounts (id, balance) VALUES (1, 1000), (2, 250);
> ```
>
> For more information about how to use the built-in SQL client, see the [`cockroach sql`](https://docs.cockroachlabs.com/docs/v24.1/cockroach-sql) reference docs.

> [tab] Go
>
> ```go theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> // 'db' is an open database connection
>
> // Insert two rows into the "accounts" table.
> if _, err := db.Exec(
>     "INSERT INTO accounts (id, balance) VALUES (1, 1000), (2, 250)"); err != nil {
>     log.Fatal(err)
> }
> ```
>
> For complete examples, see:
>
> * [Build a Go App with CockroachDB](https://docs.cockroachlabs.com/docs/v24.1/build-a-go-app-with-cockroachdb.md) (pgx)
> * [Build a Go App with CockroachDB and GORM](https://docs.cockroachlabs.com/docs/v24.1/build-a-go-app-with-cockroachdb.md)

> [tab] Java
>
> ```java theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> // ds is an org.postgresql.ds.PGSimpleDataSource
>
> try (Connection connection = ds.getConnection()) {
>     connection.setAutoCommit(false);
>     PreparedStatement pstmt = connection.prepareStatement("INSERT INTO accounts (id, balance) VALUES (?, ?)");
>
>     pstmt.setInt(1, 1);
>     pstmt.setInt(2, 1000);
>     pstmt.addBatch();
>
>     pstmt.executeBatch();
>     connection.commit();
> } catch (SQLException e) {
>     System.out.printf("sql state = [%s]\ncause = [%s]\nmessage = [%s]\n",
>                       e.getSQLState(), e.getCause(), e.getMessage());
> }
> ```
>
> For complete examples, see:
>
> * [Build a Java App with CockroachDB](https://docs.cockroachlabs.com/docs/v24.1/build-a-java-app-with-cockroachdb.md) (JDBC)
> * [Build a Java App with CockroachDB and Hibernate](https://docs.cockroachlabs.com/docs/v24.1/build-a-java-app-with-cockroachdb-hibernate.md)

> [tab] Python
>
> ```python theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> # conn is a psycopg2 connection
>
> with conn.cursor() as cur:
>     cur.execute('INSERT INTO accounts (id, balance) VALUES (1, 1000), (2, 250)')
>
> conn.commit()
> ```
>
> For complete examples, see:
>
> * [Build a Python App with CockroachDB](https://docs.cockroachlabs.com/docs/v24.1/build-a-python-app-with-cockroachdb-psycopg3.md) (psycopg3)
> * [Build a Python App with CockroachDB and SQLAlchemy](https://docs.cockroachlabs.com/docs/v24.1/build-a-python-app-with-cockroachdb-sqlalchemy.md)
> * [Build a Python App with CockroachDB and Django](https://docs.cockroachlabs.com/docs/v24.1/build-a-python-app-with-cockroachdb-django.md)
> * [Build a Python App with CockroachDB and asyncpg](https://docs.cockroachlabs.com/docs/v24.1/build-a-python-app-with-cockroachdb-asyncpg.md)

## Limit the size of rows

To help you avoid failures arising from misbehaving applications that bloat the size of rows, you can specify the behavior when a row or individual [column family](https://docs.cockroachlabs.com/docs/v24.1/column-families.md) larger than a specified size is written to the database. Use the [cluster settings](https://docs.cockroachlabs.com/docs/v24.1/cluster-settings.md) `sql.guardrails.max_row_size_log` to discover large rows and `sql.guardrails.max_row_size_err` to reject large rows.

When you write a row that exceeds `sql.guardrails.max_row_size_log`:

* `INSERT`, `UPSERT`, `UPDATE`, `CREATE TABLE AS`, `CREATE INDEX`, `ALTER TABLE`, `ALTER INDEX`, `IMPORT`, or `RESTORE` statements will log a `LargeRow` to the [`SQL_PERF`](https://docs.cockroachlabs.com/docs/v24.1/logging#sql_perf) channel.
* `SELECT`, `DELETE`, `TRUNCATE`, and `DROP` are not affected.

When you write a row that exceeds `sql.guardrails.max_row_size_err`:

* `INSERT`, `UPSERT`, and `UPDATE` statements will fail with a code `54000 (program_limit_exceeded)` error.
* `CREATE TABLE AS`, `CREATE INDEX`, `ALTER TABLE`, `ALTER INDEX`, `IMPORT`, and `RESTORE` statements will log a `LargeRowInternal` event to the [`SQL_INTERNAL_PERF`](https://docs.cockroachlabs.com/docs/v24.1/logging#sql_internal_perf) channel.
* `SELECT`, `DELETE`, `TRUNCATE`, and `DROP` are not affected.

You **cannot** update existing rows that violate the limit unless the update shrinks the size of the row below the limit. You **can** select, delete, alter, back up, and restore such rows. We recommend using the accompanying setting `sql.guardrails.max_row_size_log` in conjunction with `SELECT pg_column_size()` queries to detect and fix any existing large rows before lowering `sql.guardrails.max_row_size_err`.

## See also

Reference information related to this task:

* [Migration Overview](https://docs.cockroachlabs.com/docs/molt/migration-overview.md)
* [`INSERT`](https://docs.cockroachlabs.com/docs/v24.1/insert)
* [`UPSERT`](https://docs.cockroachlabs.com/docs/v24.1/upsert)
* [Transaction Contention](https://docs.cockroachlabs.com/docs/v24.1/performance-best-practices-overview.md#transaction-contention)
* [Multi-row DML best practices](https://docs.cockroachlabs.com/docs/v24.1/performance-best-practices-overview.md#dml-best-practices)
* [Insert Multiple Rows](https://docs.cockroachlabs.com/docs/v24.1/insert.md#insert-multiple-rows-into-an-existing-table)

Other common tasks:

* [Connect to the Database](https://docs.cockroachlabs.com/docs/v24.1/connect-to-the-database.md)
* [Query Data](https://docs.cockroachlabs.com/docs/v24.1/query-data.md)
* [Update Data](https://docs.cockroachlabs.com/docs/v24.1/update-data.md)
* [Delete Data](https://docs.cockroachlabs.com/docs/v24.1/delete-data.md)
* [Run Multi-Statement Transactions](https://docs.cockroachlabs.com/docs/v24.1/run-multi-statement-transactions)
* [Troubleshoot SQL Statements](https://docs.cockroachlabs.com/docs/v24.1/query-behavior-troubleshooting.md)
* [Optimize Statement Performance](https://docs.cockroachlabs.com/docs/v24.1/make-queries-fast.md)
* [Example Apps](https://docs.cockroachlabs.com/docs/v24.1/example-apps)
