Workspaces

Workspaces are development environments where you design your database schema. Each workspace operates in one of two modes:

tenant

Tenant Mode

Schema changes are captured as versioned blueprints. Deploy blueprints to create isolated tenant databases. This is the default mode.

control

Control Mode

A managed database with full DDL access. No blueprints, versioning, or tenants. Ideal for your application's control plane (users, billing, config).

GET /workspaces

List all workspaces. Each workspace includes a mode field (tenant or control).

Response

JSON

{
  "workspaces": [
    {
      "id": "ws_abc123",
      "name": "main",
      "mode": "tenant",
      "database": "postgresql",
      "created_at": "2025-01-15T10:30:00Z",
      "version": 3
    },
    {
      "id": "ws_def456",
      "name": "control-plane",
      "mode": "control",
      "database": "postgresql",
      "created_at": "2025-01-15T11:00:00Z"
    }
  ],
  "count": 2
}

The version field is only present for tenant mode workspaces.

POST /workspaces

Create a workspace. Automatically creates a linked blueprint (tenant mode only).

Request Body

Field	Type		Description
name	string	required	Workspace name. Cannot contain `__` (reserved separator).
database	string	required	PostgreSQL, MySQL, MongoDB, or Redis
mode	string	required	`tenant` or `control`. Tenant mode uses blueprints and deployments. Control mode creates a standalone managed database.

Response — Tenant Mode

HTTP 201

{
  "success": true,
  "http_status": 201,
  "code": "created",
  "id": "myapp",
  "mode": "tenant",
  "blueprint": "myapp",
  "database": "PostgreSQL",
  "connection": {
    "host": "pg.tenantsdb.com",
    "port": 5432,
    "database": "myapp_workspace",
    "user": "tdb_2abf90d3",
    "password": "tdb_d2bf66ed7898c448"
  },
  "connection_string": "postgresql://tdb_2abf90d3:[email protected]:5432/myapp_workspace?sslmode=require"
}

Response — Control Mode

Control mode workspaces omit the blueprint field. The workspace is a standalone managed database — no blueprints, versioning, or tenant deployment.

HTTP 201

{
  "success": true,
  "http_status": 201,
  "code": "created",
  "id": "controlplane",
  "mode": "control",
  "database": "PostgreSQL",
  "connection": {
    "host": "pg.tenantsdb.com",
    "port": 5432,
    "database": "controlplane_workspace",
    "user": "tdb_2abf90d3",
    "password": "tdb_d2bf66ed7898c448"
  },
  "connection_string": "postgresql://tdb_2abf90d3:[email protected]:5432/controlplane_workspace?sslmode=require"
}

Connection Strings by Database

TLS is enabled for all database types. The connection string format varies:

Database	TLS Parameter	Example
PostgreSQL	`?sslmode=require`	`postgresql://user:pass@host:5432/db?sslmode=require`
MySQL	TLS required	`mysql://user:pass@host:3306/db`
MongoDB	`?tls=true`	`mongodb://user:pass@host:27017/db?authMechanism=PLAIN&directConnection=true&tls=true`
Redis	`rediss://` scheme	`rediss://workspace:pass@host:6379/0`

All connections are encrypted via TLS. PostgreSQL uses sslmode=require, MySQL TLS is configured per driver (see Connections), MongoDB uses tls=true, and Redis uses the rediss:// URI scheme.

GET /workspaces/{id}

Get workspace details including schema and connection info.

Response

JSON

{
  "id": "ws_abc123",
  "name": "main",
  "mode": "tenant",
  "database": "postgresql",
  "schema": ["CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT NOT NULL)"],
  "schema_error": null,
  "undeployed_changes": 2,
  "connection": {
    "host": "proxy.tenantsdb.com",
    "port": 5432,
    "database": "ws_abc123",
    "username": "ws_abc123",
    "password": "••••••••"
  },
  "connection_string": "postgresql://ws_abc123:••••••••@proxy.tenantsdb.com:5432/ws_abc123?sslmode=require",
  "settings": {
    "query_timeout_ms": 30000,
    "max_rows_per_query": 1000,
    "max_connections": 10
  },
  "version": 3
}

undeployed_changes and version are only present for tenant mode workspaces.

DELETE /workspaces/{id}

Delete a workspace. For tenant mode, returns 409 Conflict if tenants are deployed to its blueprint. Control mode workspaces can always be deleted.

Response — success

JSON

{
  "message": "workspace deleted",
  "details": {
    "workspace": "main",
    "mode": "tenant",
    "versions_deleted": 3,
    "deletion_type": "full",
    "physical_db": true
  }
}

Response — 409 Conflict (tenants deployed)

JSON

{
  "message": "cannot delete workspace with deployed tenants",
  "reason": "tenants_deployed",
  "deployed_to": ["acme", "globex"],
  "action_required": "Delete all tenants first or use a different workspace"
}

POST /workspaces/{id}/queries

Run a query in the workspace dev database. DDL statements (CREATE TABLE, ALTER TABLE, etc.) are allowed and automatically tracked as blueprint versions for deployment to tenants.

Request Body

Field	Type		Description
query	string	required	The SQL, MongoDB, or Redis query to execute.

Response

JSON

{
  "columns": ["id", "name", "email"],
  "rows": [
    [1, "Alice", "alice@example.com"]
  ],
  "row_count": 1,
  "execution_time": "8ms"
}

POST /workspaces/{id}/schema

Import schema from template, JSON, external database, or URL.

Request Body

Field	Type		Description
source	string	required	json, database, template, or url
template	string	optional	Template name: ecommerce, saas, blog, fintech
tables	array	optional	Table definitions (for JSON source, SQL databases)
collections	array	optional	Collection definitions (for JSON source, MongoDB)
connection	object	optional	Database connection (for database source)
url	string	optional	URL to JSON schema (for url source)

From Template

JSON

{
  "source": "template",
  "template": "fintech"
}

From Database

JSON

{
  "source": "database",
  "connection": {
    "type": "postgresql",
    "host": "db.example.com",
    "port": 5432,
    "database": "mydb",
    "user": "admin",
    "password": "secret"
  }
}

Response

HTTP 200

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "message": "Schema imported to workspace 'myapp'",
  "source": "template",
  "created": ["users", "accounts", "transactions"],
  "skipped": [],
  "errors": [],
  "details": {
    "workspace": "myapp",
    "database_type": "PostgreSQL",
    "statements_executed": 3,
    "statements_skipped": 0,
    "statements_failed": 0,
    "statements_total": 3
  }
}

GET /workspaces/{id}/schema

Get the current schema of a workspace (tables, columns, indexes).

Response

JSON

{
  "tables": [
    {
      "name": "users",
      "columns": [
        { "name": "id", "type": "SERIAL", "nullable": false },
        { "name": "name", "type": "TEXT", "nullable": false }
      ],
      "indexes": ["users_pkey"]
    }
  ]
}

GET /workspaces/{id}/diff

Get pending DDL changes ready for deployment.

Tenant mode only. Returns 400 Bad Request for control mode workspaces (no blueprint versioning).

DELETE /workspaces/{id}/diff/{ddl_id}

Remove a DDL change from the deploy queue. Returns 404 Not Found if the DDL does not exist or has already been deployed.

Response

HTTP 200

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "message": "DDL 42 removed from deploy queue"
}

POST /workspaces/{id}/diff/{ddl_id}/revert

Revert a DDL change in the workspace by executing the reverse statement. Only works for undeployed DDLs. Supports CREATE TABLE → DROP TABLE, CREATE INDEX → DROP INDEX, ALTER TABLE ADD COLUMN → DROP COLUMN, CREATE COLLECTION → DROP COLLECTION.

Response

HTTP 200

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "message": "Reverted: DROP TABLE IF EXISTS users;"
}

Cannot revert DDLs already deployed to tenants. Create a new migration instead.

GET /workspaces/{id}/settings

Get current settings for a workspace. Available fields depend on the database type.

Response

HTTP 200

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "database_type": "PostgreSQL",
  "settings": {
    "query_timeout_ms": 30000,
    "max_rows_per_query": 10000,
    "max_connections": 100
  },
  "available_fields": ["query_timeout_ms", "max_rows_per_query", "max_connections"]
}

PostgreSQL/MySQL/MongoDB: query_timeout_ms, max_rows_per_query, max_connections. Redis: default_ttl, max_keys, patterns.

POST /workspaces/{id}/settings

Update workspace settings. Supports partial updates — only provided fields are changed.

Request Body (PostgreSQL / MySQL / MongoDB)

JSON

{
  "query_timeout_ms": 30000,
  "max_rows_per_query": 10000,
  "max_connections": 100
}

Request Body (Redis)

JSON

{
  "default_ttl": 3600,
  "max_keys": 50000,
  "patterns": {
    "cache:*": { "ttl": 300 },
    "session:*": { "ttl": 86400 }
  }
}

Response

HTTP 200

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "settings": { ... },
  "message": "Settings saved. Deploy to apply to tenants.",
  "pending_deploy": true,
  "database_type": "PostgreSQL"
}

For tenant mode, the message is "Settings saved. Deploy to apply to tenants." with pending_deploy: true. For control mode, the message is "Settings saved." with no pending deploy.

Migrating from an existing database? The data import endpoints (import-data, import-data/analyze, import-full) are covered in the Onboarding Guide →