The Database Management API provides endpoints for managing databases within your CockroachDB clusters. These endpoints are part of the Cluster API v2, which runs on your cluster nodes.
API Base URL The Cluster API is hosted by all nodes in your cluster on the same port as the DB Console (default port 8080):
http://localhost:8080/api/v2
You can configure the port using --http-addr={server}:{port} when starting nodes.
Authentication All database endpoints (except /health and /login) require authentication using a session token.
Obtaining a Session Token curl --request POST \ --url https://localhost:8080/api/v2/login/ \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data 'username={username}&password={password}'
Requirements:
A SQL role that is a member of the admin role
Login permissions and a password
Response: { "session" : "CIGAiPis4fj3CBIQ3u0rRQJ3tD8yIqee4hipow==" }
Use this session token in subsequent requests:
curl --request GET \ --url https://localhost:8080/api/v2/databases \ --header 'X-Cockroach-API-Session: CIGAiPis4fj3CBIQ3u0rRQJ3tD8yIqee4hipow=='
List Databases Retrieve all databases in the cluster.
curl --request GET \ --url https://localhost:8080/api/v2/databases \ --header 'X-Cockroach-API-Session: {session_token}'
Response Array of database names Total size of the database in bytes
Number of tables in the database
{ "databases" : [ { "name" : "defaultdb" , "id" : "52" }, { "name" : "postgres" , "id" : "53" }, { "name" : "production" , "id" : "54" } ] }
Get Database Details Get the descriptor ID and metadata for a specific database.
GET /api/v2/databases/{database}
curl --request GET \ --url https://localhost:8080/api/v2/databases/{database} \ --header 'X-Cockroach-API-Session: {session_token}'
Path Parameters Response { "database_name" : "production" , "descriptor_id" : "54" , "size_bytes" : 1073741824 , "table_count" : 15 , "store_ids" : [ 1 , 2 , 3 ] }
Unique descriptor ID for the database
Total size of all data in the database
Number of tables in the database
List Database Grants List all privileges granted to users for a specific database.
GET /api/v2/databases/{database}/grants
curl --request GET \ --url https://localhost:8080/api/v2/databases/{database}/grants \ --header 'X-Cockroach-API-Session: {session_token}'
Path Parameters Response { "grants" : [ { "user" : "admin" , "privileges" : [ "ALL" ] }, { "user" : "app_user" , "privileges" : [ "SELECT" , "INSERT" , "UPDATE" ] }, { "user" : "readonly" , "privileges" : [ "SELECT" ] } ] }
Array of grant objects Array of privilege strings:
ALL: All privilegesSELECT: Read accessINSERT: Insert new rowsUPDATE: Modify existing rowsDELETE: Delete rowsCREATE: Create tables and schemasDROP: Drop objectsGRANT: Grant privileges to other users List Database Tables List all tables in a specific database.
GET /api/v2/databases/{database}/tables
curl --request GET \ --url https://localhost:8080/api/v2/databases/{database}/tables \ --header 'X-Cockroach-API-Session: {session_token}'
Path Parameters Response { "tables" : [ { "name" : "users" , "schema_name" : "public" , "table_id" : "55" , "size_bytes" : 524288000 }, { "name" : "orders" , "schema_name" : "public" , "table_id" : "56" , "size_bytes" : 1048576000 } ] }
Array of table objects Schema containing the table (usually “public”)
Unique table descriptor ID
Total size of the table in bytes
Get Table Details Get detailed information about a specific table.
GET /api/v2/databases/{database}/tables/{table}
curl --request GET \ --url https://localhost:8080/api/v2/databases/{database}/tables/{table} \ --header 'X-Cockroach-API-Session: {session_token}'
Path Parameters Response { "table_name" : "users" , "table_id" : "55" , "database_name" : "production" , "schema_name" : "public" , "columns" : [ { "name" : "id" , "type" : "UUID" , "nullable" : false }, { "name" : "email" , "type" : "STRING" , "nullable" : false } ], "indexes" : [ { "name" : "primary" , "columns" : [ "id" ], "unique" : true }, { "name" : "users_email_idx" , "columns" : [ "email" ], "unique" : true } ], "grants" : [ { "user" : "admin" , "privileges" : [ "ALL" ] } ], "range_count" : 12 , "size_bytes" : 524288000 }
Unique table descriptor ID
Array of column definitions
Array of index definitions
Privileges granted on this table
Number of ranges storing this table’s data
Total size of the table in bytes
Logout Invalidate your session token.
curl --request POST \ --url https://localhost:8080/api/v2/logout/ \ --header 'X-Cockroach-API-Session: {session_token}'
Support Policy Endpoint Stability /databasesStable /databases/{database}Stable /databases/{database}/grantsStable /databases/{database}/tablesStable /databases/{database}/tables/{table}Stable
Stable endpoints are supported and will maintain backward compatibility within the v2 API version.Common Use Cases
Use /databases and /databases/{database} endpoints to track database and table sizes over time for capacity planning. curl -X GET https://localhost:8080/api/v2/databases/production \ -H 'X-Cockroach-API-Session: {token}' | jq '.size_bytes'
Audit Database Permissions
Use /databases/{database}/grants to audit which users have access to sensitive databases. curl -X GET https://localhost:8080/api/v2/databases/production/grants \ -H 'X-Cockroach-API-Session: {token}'
Use /databases/{database}/tables to generate an inventory of all tables and schemas. curl -X GET https://localhost:8080/api/v2/databases/production/tables \ -H 'X-Cockroach-API-Session: {token}'
Error Responses 401 Unauthorized Occurs when the session token is missing, invalid, or expired.
{ "error" : "unauthorized" , "message" : "valid session required" }
404 Not Found Occurs when the specified database or table doesn’t exist.
{ "error" : "not found" , "message" : "database \" nonexistent \" does not exist" }