Skip to main content
The CREATE DATABASE statement creates a new CockroachDB database.

​
Required privileges

To create a database, you must be a member of the admin role or have the CREATEDB parameter set.

​
Syntax

CREATE DATABASE [IF NOT EXISTS] name
  [WITH OPTIONS]

​
Parameters

​
IF NOT EXISTS
keyword
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
identifier
The name of the database to create, which must be unique and follow identifier rules.Avoid starting your database name with cluster:. If your database name begins with this string, you must append &options=-ccluster=system to the URI connection string to connect to the cluster.
​
encoding
string
The ENCODING clause is accepted for PostgreSQL compatibility, 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
integer
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.
​
PRIMARY REGION
region_name
Create a multi-region database with region_name as the primary region.Allowed values include any region returned by SHOW REGIONS FROM CLUSTER.
​
REGIONS
region_name_list
Create a multi-region database with region_name_list as database regions.To set database regions at database creation, a primary region must be specified in the same CREATE DATABASE statement.
​
SURVIVE
survival_goal
Create a multi-region database with regional failure or zone failure survival goals.Options:
  • SURVIVE ZONE FAILURE (Default)
  • SURVIVE REGION FAILURE (requires at least 3 database regions)

​
Examples

​
Create a database

CREATE DATABASE bank;

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

​
Create a database with IF NOT EXISTS

CREATE DATABASE IF NOT EXISTS bank;
SQL does not generate an error even if the database already exists. Instead, it responds with CREATE DATABASE.

​
Create a multi-region database

First, check available regions: 
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}       | {}             | {}
Create a multi-region database with survival goals: 
CREATE DATABASE bank 
  PRIMARY REGION "us-east1" 
  REGIONS "us-east1", "us-central1", "us-west1" 
  SURVIVE REGION FAILURE;

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}

​
Create a multi-region database with secondary region

Add a secondary region for failover purposes: 
CREATE DATABASE bank 
  PRIMARY REGION "us-east1" 
  REGIONS "us-east1", "us-central1", "us-west1" 
  SURVIVE REGION FAILURE 
  SECONDARY REGION "us-west1";
If the primary region fails, the secondary region becomes the new primary region.

​
See also

  • SHOW DATABASES
  • SHOW CREATE DATABASE
  • ALTER DATABASE
  • SET DATABASE
  • DROP DATABASE

Build docs developers (and LLMs) love

Get started for freeTalk to us