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

# CREATE DATABASE

The `CREATE DATABASE` [statement](/docs/stable/sql-statements.md) creates a new CockroachDB database.

> [!NOTE]
>
> The `CREATE DATABASE` statement performs a schema change. For more information about how online schema changes work in CockroachDB, see [Online Schema Changes](/docs/stable/online-schema-changes.md).

## Required privileges

To create a database, the user must be a member of the `admin` role or must have the [`CREATEDB`](/docs/stable/create-role#create-a-role-that-can-create-and-rename-databases) parameter set.

## Synopsis

![create\_database syntax diagram](https://mintcdn.com/cockroachlabs/UZNSFbmU2EwEm6G5/images/sql-diagrams/common/create_database.svg?fit=max\&auto=format\&n=UZNSFbmU2EwEm6G5\&q=85\&s=eb0c921d790cb016b7de0c767e955c65)

## Parameters

| Parameter | Description |
| - | - |
| `IF NOT EXISTS` | Create a new database only if a database of the same name does not already exist; if one does exist, do not return an error. |
| `name` | The name of the database to create, which [must be unique](#create-fails-name-already-in-use) and follow these [identifier rules](/docs/stable/keywords-and-identifiers.md#identifiers). Cockroach Labs recommends against starting your database name with the string `cluster:`. If your database name begins with this string, you must append the following to the URI connection string to [connect to the cluster](/docs/stable/connect-to-the-database.md): `&options=-ccluster=system` |
| `encoding` | The `CREATE DATABASE` statement accepts an optional `ENCODING` clause for compatibility with PostgreSQL, but `UTF-8` is the only supported encoding. The aliases `UTF8` and `UNICODE` are also accepted. Values should be enclosed in single quotes and are case-insensitive. Example: `CREATE DATABASE bank ENCODING = 'UTF-8'`. |
| `CONNECTION LIMIT` | Supported for compatibility with PostgreSQL. A value of `-1` indicates no connection limit. Values other than `-1` are currently not supported. By default, `CONNECTION LIMIT = -1`. ([\*](#connlimit-note)) |
| `PRIMARY REGION region_name` | Create a [multi-region database](/docs/stable/multiregion-overview.md) with `region_name` as [the primary region](/docs/stable/multiregion-overview.md#database-regions). Allowed values include any region returned by [`SHOW REGIONS FROM CLUSTER`](/docs/stable/show-regions). |
| `REGIONS region_name_list` | Create a [multi-region database](/docs/stable/multiregion-overview.md) with `region_name_list` as [database regions](/docs/stable/multiregion-overview.md#database-regions). Allowed values include any region returned by [`SHOW REGIONS FROM CLUSTER`](/docs/stable/show-regions). To set database regions at database creation, a primary region must be specified in the same `CREATE DATABASE` statement. |
| `SURVIVE ZONE FAILURE` (*Default*) `SURVIVE REGION FAILURE` | Create a [multi-region database](/docs/stable/multiregion-overview.md) with regional failure or zone failure [survival goals](/docs/stable/multiregion-overview.md#survival-goals). To set the regional failure survival goal, the database must have at least 3 [database regions](/docs/stable/multiregion-overview.md#database-regions). Surviving zone failures is the default setting for multi-region databases. |
| `SUPER REGION super_region_name VALUES region_name_list` | Create a [super region](/docs/stable/multiregion-overview.md#super-regions) when creating a multi-region database. Each super region member must also be specified in `REGIONS region_name_list`. The super region initially inherits the database survival goal. |

*

To control the maximum number of non-superuser ([`root`](/docs/stable/security-reference/authorization) user or other [`admin` role](/docs/stable/security-reference/authorization#admin-role)) connections a [gateway node](/docs/stable/architecture/sql-layer.md) can have open at one time, use the `server.max_connections_per_gateway` [cluster setting](/docs/stable/cluster-settings.md). If a new non-superuser connection would exceed this limit, the error message `"sorry, too many clients already"` is returned, along with error code `53300`. This setting may be useful until the `CONNECTION LIMIT` syntax is fully supported.

## Example

### Create a database

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> CREATE DATABASE bank;
```

```
CREATE DATABASE
```

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> SHOW DATABASES;
```

```
  database_name | owner | primary_region | regions | survival_goal
----------------+-------+----------------+---------+----------------
  bank          | demo  | NULL           | {}      | NULL
  defaultdb     | root  | NULL           | {}      | NULL
  postgres      | root  | NULL           | {}      | NULL
  system        | node  | NULL           | {}      | NULL
(4 rows)
```

### Create fails (name already in use)

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> CREATE DATABASE bank;
```

```
ERROR: database "bank" already exists
SQLSTATE: 42P04
```

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> CREATE DATABASE IF NOT EXISTS bank;
```

```
CREATE DATABASE
```

SQL does not generate an error, but instead responds `CREATE DATABASE` even though a new database wasn't created.

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> SHOW DATABASES;
```

```
  database_name | owner | primary_region | regions | survival_goal
----------------+-------+----------------+---------+----------------
  bank          | demo  | NULL           | {}      | NULL
  defaultdb     | root  | NULL           | {}      | NULL
  postgres      | root  | NULL           | {}      | NULL
  system        | node  | NULL           | {}      | NULL
(4 rows)
```

### Create a multi-region database

Suppose you start a cluster with region and zone [localities specified at startup](/docs/stable/cockroach-start.md#locality).

For this example, let's use a [demo cluster](/docs/stable/cockroach-demo.md), with the [`--demo-locality` flag](/docs/stable/cockroach-demo#general) to simulate a multi-region cluster:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
cockroach demo --nodes=6 --demo-locality=region=us-east1,zone=us-east1-a:region=us-east1,zone=us-east1-b:region=us-central1,zone=us-central1-a:region=us-central1,zone=us-central1-b:region=us-west1,zone=us-west1-a:region=us-west1,zone=us-west1-b --no-example-database
```

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> SHOW REGIONS;
```

```
    region    |             zones             | database_names | primary_region_of
--------------+-------------------------------+----------------+--------------------
  us-central1 | {us-central1-a,us-central1-b} | {}             | {}
  us-east1    | {us-east1-a,us-east1-b}       | {}             | {}
  us-west1    | {us-west1-a,us-west1-b}       | {}             | {}
(3 rows)
```

If regions are set at cluster start-up, you can create multi-region databases in the cluster that use the cluster regions.

Use the following command to specify regions and survival goals at database creation:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> CREATE DATABASE bank PRIMARY REGION "us-east1" REGIONS "us-east1", "us-central1", "us-west1" SURVIVE REGION FAILURE;
```

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> SHOW DATABASES;
```

```
  database_name | owner | primary_region |             regions             | survival_goal
----------------+-------+----------------+---------------------------------+----------------
  bank          | demo  | us-east1       | {us-central1,us-east1,us-west1} | region
  defaultdb     | root  | NULL           | {}                              | NULL
  postgres      | root  | NULL           | {}                              | NULL
  system        | node  | NULL           | {}                              | NULL
(4 rows)
```

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> SHOW REGIONS FROM DATABASE bank;
```

```
  database |   region    | primary |             zones
-----------+-------------+---------+--------------------------------
  bank     | us-east1    |  true   | {us-east1-a,us-east1-b}
  bank     | us-central1 |  false  | {us-central1-a,us-central1-b}
  bank     | us-west1    |  false  | {us-west1-a,us-west1-b}
(3 rows)
```

### Create a multi-region database with a super region

To create a multi-region database and define a [super region](/docs/stable/multiregion-overview.md#super-regions) in the same statement, use the `SUPER REGION` clause:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
CREATE DATABASE movr
    PRIMARY REGION "us-east1"
    REGIONS "us-east1", "us-central1", "us-west1"
    SURVIVE REGION FAILURE
    SUPER REGION "us" VALUES "us-east1", "us-central1", "us-west1";
```

The command returns:

```
CREATE DATABASE
```

Each super region member must be included in the database's region list. The super region inherits the database survival goal until you assign it an explicit goal with [`ALTER DATABASE ... ALTER SUPER REGION ... SURVIVE`](/docs/stable/alter-database#alter-super-region).

To inspect the super region and whether it has an explicit survival goal, use [`SHOW SUPER REGIONS`](/docs/stable/show-super-regions):

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
SHOW SUPER REGIONS FROM DATABASE movr;
```

```
  database_name | super_region_name |                 regions                  | survival_goal
----------------+-------------------+------------------------------------------+---------------
  movr          | us                | {us-central1,us-east1,us-west1}          | NULL
(1 row)
```

### Create a multi-region database with a secondary region

You can add a [secondary region](/docs/stable/multiregion-overview.md#database-regions) to a [multi-region database](/docs/stable/multiregion-overview.md) for failover purposes. If the [primary region](/docs/stable/alter-database.md#set-primary-region) fails, the secondary region becomes the new primary region.

To add a secondary region during database creation, use the following steps:

1. Start a `cockroach demo` cluster as described in the example [Create a multi-region database](#create-a-multi-region-database).

2. Issue a `CREATE DATABASE` statement like the following.  It is the same as in the [Create a multi-region database](#create-a-multi-region-database) example, except that it adds a `SECONDARY REGION {region}` clause:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
CREATE DATABASE bank PRIMARY REGION "us-east1" REGIONS "us-east1", "us-central1", "us-west1" SURVIVE REGION FAILURE SECONDARY REGION "us-west1";
```

```
CREATE DATABASE
```

For more information about secondary regions, see [Secondary regions](/docs/stable/multiregion-overview.md#secondary-regions).

[Secondary regions](/docs/stable/multiregion-overview.md#secondary-regions) are not compatible with databases containing [`REGIONAL BY ROW`](/docs/stable/table-localities#regional-by-row-tables) tables. CockroachDB does not prevent you from defining secondary regions on databases with regional by row tables, but the interaction of these features is not supported. Therefore, Cockroach Labs recommends that you avoid defining secondary regions on databases that use regional by row table configurations.

## See also

* [`SHOW DATABASES`](/docs/stable/show-databases)
* [`SHOW CREATE DATABASE`](/docs/stable/show-create)
* [`ALTER DATABASE ... RENAME TO`](/docs/stable/alter-database#rename-to)
* [`SET DATABASE`](/docs/stable/set-vars)
* [`DROP DATABASE`](/docs/stable/drop-database)
* [SQL Statements](/docs/stable/sql-statements.md)
* [Online Schema Changes](/docs/stable/online-schema-changes.md)
* [Multiregion overview](/docs/stable/multiregion-overview.md)
* [Secondary regions](/docs/stable/multiregion-overview.md#secondary-regions).
* [Super regions](/docs/stable/multiregion-overview.md#super-regions)
* [`SET SECONDARY REGION`](/docs/stable/alter-database#set-secondary-region)
* [`DROP SECONDARY REGION`](/docs/stable/alter-database#drop-secondary-region)