Create a database

curl --request POST \
  --url https://api.planetscale.com/v1/organizations/{organization}/databases \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "cluster_size": "<string>",
  "region": "<string>",
  "replicas": 123,
  "kind": "mysql",
  "major_version": "<string>"
}
'

{
  "id": "<string>",
  "url": "<string>",
  "branches_url": "<string>",
  "branches_count": 123,
  "open_schema_recommendations_count": 123,
  "development_branches_count": 123,
  "production_branches_count": 123,
  "issues_count": 123,
  "multiple_admins_required_for_deletion": true,
  "ready": true,
  "at_backup_restore_branches_limit": true,
  "at_development_branch_usage_limit": true,
  "data_import": {
    "state": "<string>",
    "import_check_errors": "<string>",
    "started_at": "<string>",
    "finished_at": "<string>",
    "data_source": {
      "hostname": "<string>",
      "port": 123,
      "database": "<string>"
    }
  },
  "region": {
    "id": "<string>",
    "provider": "<string>",
    "enabled": true,
    "public_ip_addresses": [
      "<string>"
    ],
    "display_name": "<string>",
    "location": "<string>",
    "slug": "<string>",
    "current_default": true
  },
  "html_url": "<string>",
  "name": "<string>",
  "state": "pending",
  "sharded": true,
  "default_branch_shard_count": 123,
  "default_branch_read_only_regions_count": 123,
  "default_branch_table_count": 123,
  "default_branch": "<string>",
  "require_approval_for_deploy": true,
  "resizing": true,
  "resize_queued": true,
  "allow_data_branching": true,
  "foreign_keys_enabled": true,
  "automatic_migrations": true,
  "restrict_branch_region": true,
  "insights_raw_queries": true,
  "plan": "<string>",
  "insights_enabled": true,
  "production_branch_web_console": true,
  "migration_table_name": "<string>",
  "migration_framework": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "schema_last_updated_at": "<string>",
  "kind": "mysql"
}

Databases

Create a database

Authorization

A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:

Service Token Accesses create_databases

OAuth Scopes

Resource	Scopes
Organization	`create_databases`

POST

organizations

{organization}

databases

Create a database

curl --request POST \
  --url https://api.planetscale.com/v1/organizations/{organization}/databases \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "cluster_size": "<string>",
  "region": "<string>",
  "replicas": 123,
  "kind": "mysql",
  "major_version": "<string>"
}
'

{
  "id": "<string>",
  "url": "<string>",
  "branches_url": "<string>",
  "branches_count": 123,
  "open_schema_recommendations_count": 123,
  "development_branches_count": 123,
  "production_branches_count": 123,
  "issues_count": 123,
  "multiple_admins_required_for_deletion": true,
  "ready": true,
  "at_backup_restore_branches_limit": true,
  "at_development_branch_usage_limit": true,
  "data_import": {
    "state": "<string>",
    "import_check_errors": "<string>",
    "started_at": "<string>",
    "finished_at": "<string>",
    "data_source": {
      "hostname": "<string>",
      "port": 123,
      "database": "<string>"
    }
  },
  "region": {
    "id": "<string>",
    "provider": "<string>",
    "enabled": true,
    "public_ip_addresses": [
      "<string>"
    ],
    "display_name": "<string>",
    "location": "<string>",
    "slug": "<string>",
    "current_default": true
  },
  "html_url": "<string>",
  "name": "<string>",
  "state": "pending",
  "sharded": true,
  "default_branch_shard_count": 123,
  "default_branch_read_only_regions_count": 123,
  "default_branch_table_count": 123,
  "default_branch": "<string>",
  "require_approval_for_deploy": true,
  "resizing": true,
  "resize_queued": true,
  "allow_data_branching": true,
  "foreign_keys_enabled": true,
  "automatic_migrations": true,
  "restrict_branch_region": true,
  "insights_raw_queries": true,
  "plan": "<string>",
  "insights_enabled": true,
  "production_branch_web_console": true,
  "migration_table_name": "<string>",
  "migration_framework": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "schema_last_updated_at": "<string>",
  "kind": "mysql"
}

Authorizations

Authorization

string

header

required

Path Parameters

organization

string

required

The name of the organization the database belongs to

Body

application/json

name

string

required

Name of the database

cluster_size

string

required

The database cluster size name (e.g., 'PS_10', 'PS_80'). Use the 'List available cluster sizes' endpoint to get available options for your organization. /v1/organizations/:organization/cluster-size-skus

region

string

The region the database will be deployed in. If left blank, defaults to the organization's default region.

replicas

integer

The number of replicas for the database. 0 for non-HA, 2+ for HA.

kind

enum<string>

The kind of database to create.

Available options:

mysql,

postgresql

major_version

string

For PostgreSQL databases, the PostgreSQL major version to use for the database. Defaults to the latest available major version.

Response

Returns the created database

string

required

The ID of the database

url

string

required

The URL to the database API endpoint

branches_url

string

required

The URL to retrieve this database's branches via the API

branches_count

integer

required

The total number of database branches

open_schema_recommendations_count

integer

required

The total number of schema recommendations

development_branches_count

integer

required

The total number of database development branches

production_branches_count

integer

required

The total number of database production branches

issues_count

integer

required

The total number of ongoing issues within a database

multiple_admins_required_for_deletion

boolean

required

If the database requires multiple admins for deletion

ready

boolean

required

If the database is ready to be used

at_backup_restore_branches_limit

boolean

required

If the database has reached its backup restored branch limit

at_development_branch_usage_limit

boolean

required

If the database has reached its development branch limit

data_import

object

required

Show child attributes

region

object

required

Show child attributes

html_url

string

required

The URL to see this database's branches in the web UI

name

string

required

Name of the database

state

enum<string>

required

State of the database

Available options:

pending,

importing,

sleep_in_progress,

sleeping,

awakening,

import_ready,

ready

sharded

boolean

required

If the database is sharded

default_branch_shard_count

integer

required

Number of shards in the default branch

default_branch_read_only_regions_count

integer

required

Number of read only regions in the default branch

default_branch_table_count

integer

required

Number of tables in the default branch schema

default_branch

string

required

The default branch for the database

require_approval_for_deploy

boolean

required

Whether an approval is required to deploy schema changes to this database

resizing

boolean

required

True if a branch is currently resizing

resize_queued

boolean

required

True if a branch has a queued resize request

allow_data_branching

boolean

required

Whether seeding branches with data is enabled for all branches

foreign_keys_enabled

boolean

required

Whether foreign key constraints are enabled

automatic_migrations

boolean

required

Whether to automatically manage Rails migrations during deploy requests

restrict_branch_region

boolean

required

Whether to restrict branch creation to one region

insights_raw_queries

boolean

required

Whether raw SQL queries are collected

plan

string

required

The database plan

insights_enabled

boolean

required

True if query insights is enabled for the database

production_branch_web_console

boolean

required

Whether web console is enabled for production branches

migration_table_name

string

required

Table name to use for copying schema migration data

migration_framework

string

required

Framework used for applying migrations

created_at

string

required

When the database was created

updated_at

string

required

When the database was last updated

schema_last_updated_at

string

required

When the default branch schema was last changed.

kind

enum<string>

required

The kind of database

Available options:

mysql,

postgresql

List databases

Get a database

⌘I

Introduction

Webhooks in PlanetScale

Authentication

General API endpoints

Postgres API endpoints

Vitess API endpoints

Create a database

Authorization

Authorizations

Path Parameters

Body

Response