> ## 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.2/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.2/install-client-drivers).
* [Connect to the database](https://docs.cockroachlabs.com/docs/v24.2/connect-to-the-database).

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

## Insert rows

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

```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.2/cockroach-sql) reference docs.

```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.2/build-a-go-app-with-cockroachdb) (pgx)
* [Build a Go App with CockroachDB and GORM](https://docs.cockroachlabs.com/docs/v24.2/build-a-go-app-with-cockroachdb)

```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.2/build-a-java-app-with-cockroachdb) (JDBC)
* [Build a Java App with CockroachDB and Hibernate](https://docs.cockroachlabs.com/docs/v24.2/build-a-java-app-with-cockroachdb-hibernate)

```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.2/build-a-python-app-with-cockroachdb-psycopg3) (psycopg3)
* [Build a Python App with CockroachDB and SQLAlchemy](https://docs.cockroachlabs.com/docs/v24.2/build-a-python-app-with-cockroachdb-sqlalchemy)
* [Build a Python App with CockroachDB and Django](https://docs.cockroachlabs.com/docs/v24.2/build-a-python-app-with-cockroachdb-django)
* [Build a Python App with CockroachDB and asyncpg](https://docs.cockroachlabs.com/docs/v24.2/build-a-python-app-with-cockroachdb-asyncpg)

## 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.2/column-families) larger than a specified size is written to the database. Use the [cluster settings](https://docs.cockroachlabs.com/docs/v24.2/cluster-settings) `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.2/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.2/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.2/insert)
* [`UPSERT`](https://docs.cockroachlabs.com/docs/v24.2/upsert)
* [Transaction Contention](https://docs.cockroachlabs.com/docs/v24.2/performance-best-practices-overview#transaction-contention)
* [Multi-row DML best practices](https://docs.cockroachlabs.com/docs/v24.2/performance-best-practices-overview#dml-best-practices)
* [Insert Multiple Rows](https://docs.cockroachlabs.com/docs/v24.2/insert#insert-multiple-rows-into-an-existing-table)

Other common tasks:

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

[manual]: https://docs.cockroachlabs.com/docs/v24.2/manual-deployment

[orchestrated]: orchestration.html

[local_secure]: https://docs.cockroachlabs.com/docs/v24.2/secure-a-cluster

[connection_params]: https://docs.cockroachlabs.com/docs/v24.2/connection-parameters