GetDot Database

GetDot Database is a managed analytical database. PostgreSQL SQL with DuckDB extensions. Two interfaces: HTTPS API (for agents) and PostgreSQL wire protocol (for ecosystem tools).

Quick Start

curl -X POST https://db.getdot.ai/ \
  -H "X-GetDot-Key: $DOT_DB_TOKEN" \
  -d "SELECT 'hello from GetDot Database'"

No SDK, no driver, no connection pooling needed.

Authentication

Set the token in the DOT_DB_TOKEN environment variable. Three auth methods:

1. Header (recommended for agents):

   X-GetDot-Key: dot_<prefix>_<secret>

1. Basic auth (curl, HTTP clients):

   curl --user 'default:<token>' https://db.getdot.ai/ -d "SELECT 1"

1. PostgreSQL password (Tableau, psql, dbt):

   Host: db.getdot.ai  Port: 5432  User: default  Password: <token>  SSL: required

HTTP API

Send SQL in a POST body to https://db.getdot.ai/. The response format depends on the FORMAT clause:

# Default: TabSeparated (one row per line, tabs between columns)
curl -X POST https://db.getdot.ai/ \
  -H "X-GetDot-Key: $DOT_DB_TOKEN" \
  -d "SELECT count(*) FROM my_table"

# JSON: structured response with metadata
curl -X POST https://db.getdot.ai/ \
  -H "X-GetDot-Key: $DOT_DB_TOKEN" \
  -d "SELECT count(*) FROM my_table FORMAT JSON"

Response Formats

Always use FORMAT JSON when you need structured data. The meta array gives column names and types.

Data Loading

Import data from any URL with one line of SQL:

-- CSV from HTTP
CREATE TABLE events AS SELECT * FROM read_csv_auto('https://example.com/events.csv');

-- Parquet from S3
CREATE TABLE logs AS SELECT * FROM read_parquet('s3://bucket/logs/*.parquet');

-- JSON from API
CREATE TABLE api_data AS SELECT * FROM read_json_auto('https://api.example.com/data.json');

-- Append to existing table
INSERT INTO events SELECT * FROM read_csv_auto('https://example.com/more.csv');

For S3, set credentials first:

SET s3_region='us-east-1';
SET s3_access_key_id='AKIA...';
SET s3_secret_access_key='...';

Schema Discovery

All schema operations are standard SQL:

SHOW TABLES;                       -- list all tables
SHOW TABLES FROM schema_name;      -- list tables in a schema
DESCRIBE table_name;               -- show columns and types
SHOW SCHEMAS;                      -- list schemas
SHOW SNAPSHOTS;                    -- list data versions
SHOW HISTORY FOR table_name;       -- change log for a table

SQL Dialect

PostgreSQL SQL with DuckDB quality-of-life extensions:

• GROUP BY ALL -- automatically group by all non-aggregate columns
• SELECT * EXCLUDE (col1, col2) -- select all columns except specified
• QUALIFY -- filter window function results (like HAVING for aggregates)
• PIVOT / UNPIVOT -- reshape data
• unnest(), list_value(), array_agg() -- array operations
• struct_pack(), map {'key': 'val'} -- structured types
• read_csv_auto(), read_parquet(), read_json_auto() -- import from URLs
• approx_count_distinct(), quantile_cont(0.95) -- approximate aggregations

See references/sql-dialect.md for the full reference and Snowflake migration mappings.

Time Travel

Every write creates an immutable snapshot:

SELECT * FROM my_table AT (VERSION => 5);
SELECT * FROM my_table AT (TIMESTAMP => now() - INTERVAL '1 hour');
SHOW SNAPSHOTS;
SHOW HISTORY FOR my_table;

See references/time-travel.md for details.

PostgreSQL Wire Protocol

Same token, same SQL, same data -- on port 5432 with SSL:

psql "postgresql://default:<token>@db.getdot.ai:5432/db?sslmode=require"

Works with Tableau, Metabase, Grafana, dbt, DBeaver, and any PostgreSQL client.

For dbt, use dbt-postgres adapter with {{ config(materialized='table') }} (views are not supported).

Access Control (RBAC)

See references/rbac.md for users, roles, grants, and budgets.

Common Patterns

-- Create table from query
CREATE TABLE summary AS
  SELECT date_trunc('month', ts) AS month, count(*) AS events
  FROM raw_events
  GROUP BY ALL;

-- Insert data
INSERT INTO events (ts, event, user_id)
VALUES ('2026-04-01', 'signup', 42);

-- Parameterized queries (PG wire only)
SELECT * FROM events WHERE user_id = $1;

Error Codes

Links

• Endpoint: https://db.getdot.ai
• Full docs: https://db.getdot.ai/llms.txt
• Health: https://db.getdot.ai/health