Documentation

DDL to Data API Guide

Name: DDL to Data
Author: DDL to Data

Everything you need to generate realistic test data from your SQL schemas

Generate Test Data in Under 2 Minutes

No signup required for your first request

Paste your SQL schema, get realistic data back. Try it right now:

Send your schema (30 seconds)

curl -X POST "https://api.ddltodata.com/schemas" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "users",
    "ddl": "CREATE TABLE users (
      id SERIAL PRIMARY KEY,
      first_name VARCHAR(50),
      last_name VARCHAR(50),
      email VARCHAR(100),
      created_at TIMESTAMP
    );"
  }'

Generate data

curl "https://api.ddltodata.com/generate/users?rows=3"

Get realistic data

[
  {
    "id": 1,
    "first_name": "Sarah",
    "last_name": "Chen",
    "email": "sarah.chen@techstartup.io",
    "created_at": "2024-03-15T09:23:41"
  },
  {
    "id": 2,
    "first_name": "Marcus",
    "last_name": "Johnson",
    "email": "m.johnson@company.com",
    "created_at": "2024-03-14T14:52:18"
  },
  {
    "id": 3,
    "first_name": "Emily",
    "last_name": "Rodriguez",
    "email": "emily.r@startup.co",
    "created_at": "2024-03-13T11:05:33"
  }
]

What just happened?

DDL to Data automatically inferred realistic values from your column names:

first_name→Real first names
email→Valid email format with realistic domains
created_at→Recent timestamps

See all 40+ Smart Data Types →

Next Steps

Save your schema

Get a free API key to persist schemas

Auth →

Add relationships

Link tables with foreign keys

Foreign Keys →

Story-driven dataDEVELOPER

Generate coherent narratives

Story Mode →

Smart Data Types

DDL to Data automatically infers realistic data from your column names. No configuration needed.

Example: Employee Schema

Input:

CREATE TABLE employees (
  id SERIAL PRIMARY KEY,
  first_name VARCHAR(50),
  last_name VARCHAR(50),
  email VARCHAR(100),
  phone VARCHAR(20),
  title VARCHAR(100),
  salary DECIMAL(10,2),
  hired_at DATE
);

Output:

{
  "id": 1,
  "first_name": "Sarah",
  "last_name": "Chen",
  "email": "sarah.chen@company.io",
  "phone": "+1-555-234-5678",
  "title": "Senior Engineer",
  "salary": 145000.00,
  "hired_at": "2023-06-15"
}

Every column was inferred automatically from its name. No configuration required.

Column Pattern	Generated Data	Example
first_name, *_name	Person first names	"Sarah", "Marcus", "Emily"
last_name, surname	Family names	"Chen", "Johnson", "Rodriguez"
email	Valid email addresses	"sarah.chen@company.io"
phone, mobile	Phone numbers	"+1-555-123-4567"
address, street	Street addresses	"123 Main Street"
city	City names	"San Francisco"
state	State/province names	"California"
zip, postal	Postal codes	"94102"
country	Country names	"United States"
url, website	URLs	"https://example.com"
_at, _date, timestamp	ISO timestamps	"2024-03-15T09:23:41"
price, amount, *_cost	Decimal numbers	29.99, 149.00
status	Status values	"active", "pending", "completed"
*_count, quantity	Integer counts	1-100 range
description, bio, text	Lorem ipsum text	Realistic paragraphs
title	Job titles	"Senior Engineer", "Product Manager"
company, company_name	Company names	"Acme Corp", "TechStart Inc"
id, *_id	Sequential integers	1, 2, 3...
uuid	UUID v4	"550e8400-e29b-41d4-..."
is_, has_	Boolean values	true, false

Authentication

All API requests require authentication via the X-API-Key header.

curl -H "X-API-Key: your_api_key_here" \
  https://api.ddltodata.com/schemas

Keep Your Key Secret

Your API key grants access to your account. Never expose it in client-side code or public repositories.

Get Free API Key

API Endpoints

GET/schemas

Retrieve a list of all your registered schema names.

Example Request

curl -H "X-API-Key: YOUR_KEY" \
  https://api.ddltodata.com/schemas

Response

{
  "tables": [
    {"name": "users", "display_name": "users"},
    {"name": "orders", "display_name": "orders"},
    {"name": "products", "display_name": "products"}
  ]
}

POST/schemas

Parameters

namestringrequired

Unique table name

ddlstringrequired

SQL CREATE TABLE statement

Request Body

{
  "name": "users",
  "ddl": "CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    first_name VARCHAR(50),
    last_name VARCHAR(50),
    email VARCHAR(100) UNIQUE,
    created_at TIMESTAMP
  );"
}

Example Request

curl -X POST https://api.ddltodata.com/schemas \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"users","ddl":"CREATE TABLE users (id INT, name VARCHAR(50), email VARCHAR(100));"}'

Response

{
  "message": "Schema 'users' registered successfully."
}

GET/generate/{table_name}

Generate synthetic data for the specified table. Supports JSON, CSV, SQL, Parquet, and Excel output formats.

Parameters

table_namestringrequired

Name of the schema to generate data for

rowsinteger

Number of rows to generate (default: 10, max: 10000)

formatstring

Output format: json (default), csv, sql, parquet, xlsx

Example Request

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.ddltodata.com/generate/users?rows=100"

Response

[
  {
    "id": 1,
    "first_name": "Sarah",
    "last_name": "Johnson",
    "email": "sarah.johnson@gmail.com",
    "created_at": "2024-03-15T09:23:41"
  },
  {
    "id": 2,
    "first_name": "Michael",
    "last_name": "Chen",
    "email": "m.chen@outlook.com",
    "created_at": "2024-03-14T14:56:12"
  },
  {
    "id": 3,
    "first_name": "Emily",
    "last_name": "Rodriguez",
    "email": "emily.r@company.io",
    "created_at": "2024-03-13T11:05:33"
  }
]

Output Formats

Use the format parameter to get data in different formats:

Format	Parameter	Description
JSON	format=json	Default. Array of objects.
CSV	format=csv	Comma-separated values with header row.
SQL	format=sql	INSERT statements ready to execute.
Parquet	format=parquet	Columnar format for analytics.
Excel	format=xlsx	Excel spreadsheet.

CSV Example

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.ddltodata.com/generate/users?rows=3&format=csv"

# Response:
id,first_name,last_name,email,created_at
1,Sarah,Johnson,sarah.johnson@gmail.com,2024-03-15T09:23:41
2,Michael,Chen,m.chen@outlook.com,2024-03-14T14:56:12
3,Emily,Rodriguez,emily.r@company.io,2024-03-13T11:05:33

SQL INSERT Statements

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.ddltodata.com/generate/users?rows=3&format=sql"

# Response:
INSERT INTO users (id, first_name, last_name, email, created_at) VALUES (1, 'Sarah', 'Johnson', 'sarah.johnson@gmail.com', '2024-03-15T09:23:41');
INSERT INTO users (id, first_name, last_name, email, created_at) VALUES (2, 'Michael', 'Chen', 'm.chen@outlook.com', '2024-03-14T14:56:12');
INSERT INTO users (id, first_name, last_name, email, created_at) VALUES (3, 'Emily', 'Rodriguez', 'emily.r@company.io', '2024-03-13T11:05:33');

DELETE/schemas/{table_name}

Delete an existing schema and remove it from your account.

Parameters

table_namestringrequired

Name of the schema to delete

Example Request

curl -X DELETE https://api.ddltodata.com/schemas/users \
  -H "X-API-Key: YOUR_KEY"

Response

{
  "message": "Schema 'users' deleted successfully."
}

GET/me

Get information about your account, including plan details and usage statistics.

Example Request

curl -H "X-API-Key: YOUR_KEY" \
  https://api.ddltodata.com/me

Response

{
  "email": "you@example.com",
  "plan": "developer",
  "calls_month": 45,
  "rows_month": 2500,
  "quota_calls_month": 500,
  "quota_rows_month": 50000
}

Foreign Keys & Relationships

DDL to Data automatically maintains referential integrity across related tables. This is what separates DDL to Data from prompting an LLM — guaranteed consistency.

Example: Companies and Employees

Input schemas:

CREATE TABLE companies (
  id SERIAL PRIMARY KEY,
  name VARCHAR(100),
  industry VARCHAR(50)
);

CREATE TABLE employees (
  id SERIAL PRIMARY KEY,
  company_id INT REFERENCES companies(id),
  name VARCHAR(100),
  email VARCHAR(100),
  role VARCHAR(50)
);

companies output:

[
  {"id": 1, "name": "Acme Corp", "industry": "Technology"},
  {"id": 2, "name": "TechStart Inc", "industry": "Software"}
]

employees output:

[
  {"id": 1, "company_id": 1, "name": "Sarah Chen", "email": "sarah.chen@acmecorp.io", "role": "Engineer"},
  {"id": 2, "company_id": 1, "name": "Marcus Johnson", "email": "m.johnson@acmecorp.io", "role": "Manager"},
  {"id": 3, "company_id": 2, "name": "Emily Rodriguez", "email": "emily.r@techstart.co", "role": "Designer"}
]

Notice:

• company_id values reference valid company IDs
• Email domains match company names
• Data is consistent across tables

Story Mode

DEVELOPER

Generate data that tells a coherent story instead of random values. Perfect for demos, presentations, and realistic testing scenarios.

Example prompt: "A growing B2B SaaS with enterprise clients and some churned accounts"

[
  {
    "id": 1,
    "email": "sarah.chen@enterprise.com",
    "plan": "enterprise",
    "status": "active",
    "mrr": 299,
    "signed_up": "2023-01-15"
  },
  {
    "id": 2,
    "email": "mike@startup.io",
    "plan": "developer",
    "status": "churned",
    "mrr": 0,
    "signed_up": "2023-06-01"
  }
]

Use Cases

• Demo environments that look real
• Realistic testing scenarios
• Presentations and screenshots
• QA testing with edge cases

Example Request

curl -X POST "https://api.ddltodata.com/story/users" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": 20,
    "custom_prompt": "A growing B2B SaaS with steady month-over-month growth. Mix of starter, pro, and enterprise customers."
  }'

Plan Limits

Free: Not available
Developer ($9/mo): 10 story generations/month
Team ($29/mo): 50 story generations/month
Scale ($79/mo): 100 story generations/month
Enterprise: Unlimited

Note: Story Mode takes 2-5 seconds (vs milliseconds for standard generation).

Compare plans →

Direct Database Seeding

TEAM

Skip the file exports. Connect DDL to Data directly to your PostgreSQL database and populate tables in one API call. No CSV downloads. No manual imports.

One call, seeded database:

curl -X POST "https://api.ddltodata.com/generate/users/seed" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": 1000,
    "connection": {
      "host": "your-db.amazonaws.com",
      "port": 5432,
      "database": "myapp_dev",
      "username": "dev_user",
      "password": "your_password",
      "ssl_enabled": true
    }
  }'

Response:

{
  "success": true,
  "rows_inserted": 1000,
  "table": "users",
  "duration_ms": 2340
}

How It Works

Provide your database connection details
We test the connection and list available tables
Select tables and row counts
Data is generated and inserted directly

Security

• Connection credentials are never stored on our servers
• All connections use SSL
• Your database must allow connections from our IP range

Plan Requirements

Free / Developer: Not available
Team ($29/mo): Available
Scale ($79/mo): Available
Enterprise: Available with dedicated IP allowlisting

Compare plans →

Code Examples

Complete examples for popular languages. Click a tab to switch — your preference is saved.

# pip install requests psycopg2-binary
import requests
import psycopg2

API_KEY = "your_api_key"
DB_URL = "postgresql://user:pass@localhost/mydb"

DDL = """
CREATE TABLE IF NOT EXISTS users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100),
    email VARCHAR(255),
    created_at TIMESTAMP
)
"""

# 1. Create the table in PostgreSQL
conn = psycopg2.connect(DB_URL)
cursor = conn.cursor()
cursor.execute(DDL)
conn.commit()

# 2. Register schema with DDL to Data
requests.post(
    "https://api.ddltodata.com/schemas",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={"name": "users", "ddl": DDL}
)

# 3. Generate fake data via API
response = requests.get(
    "https://api.ddltodata.com/generate/users?rows=100&format=sql",
    headers={"X-API-Key": API_KEY}
)

# 4. Load into PostgreSQL
cursor.execute(response.text)
conn.commit()
conn.close()

print("Created table and loaded 100 rows!")

Common Recipes

# Generate SQL and pipe directly to psql
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.ddltodata.com/generate/users?rows=100&format=sql" \
  | psql postgresql://user:pass@localhost/mydb

Rate Limits & Plans

Plan	API Calls/Month	Rows/Month	Features	Price
Free FREE	500	50,000	Basic generation	$0
Developer DEVELOPER	2,500	250,000	+ Story Mode (10/mo)	$9/mo
Team TEAM	10,000	1,000,000	+ DB Seeding, Story (50/mo)	$29/mo
Scale SCALE	Unlimited	5,000,000	+ Story (100/mo)	$79/mo
Enterprise ENTERPRISE	Custom	Unlimited	+ Dedicated support, IP allowlisting	Contact us

View full pricing details →

Error Handling

The API returns standard HTTP status codes with JSON error details. Here's how to handle each:

400Bad Request

The schema couldn't be parsed or contains syntax errors.

Common causes:

Missing semicolon at end of CREATE TABLE statement
Unsupported SQL dialect syntax
Invalid data type

Resolution:

Validate your SQL syntax
Ensure you're using standard CREATE TABLE syntax
Check supported SQL dialects (PostgreSQL, MySQL, SQLite)

{
  "detail": "Parse error at line 3: Unexpected token"
}

401Unauthorized

Missing or invalid API key.

Common causes:

API key not included in request header
API key is expired or revoked
Typo in the API key

Resolution:

Ensure X-API-Key header is present
Verify your API key in the dashboard
Generate a new key if needed

{
  "detail": "Invalid or missing API key"
}

429Rate Limited

You've exceeded your plan's API call or row limit.

Current limits:

Plan	Calls/Month	Rows/Month
Free	500	50,000
Developer	2,500	250,000
Team	10,000	1,000,000
Scale	Unlimited	5,000,000

Resolution:

Check your usage with GET /me
Upgrade your plan for higher limits
Optimize requests (generate more rows per call)

{
  "detail": {
    "error": "call_limit",
    "message": "Monthly API call limit exceeded",
    "current_usage": 100,
    "limit": 100,
    "resets_at": "2024-02-01T00:00:00Z"
  }
}

404Not Found

The requested schema doesn't exist.

Resolution:

Check the schema name spelling
List your schemas with GET /schemas
Create the schema first with POST /schemas

{
  "detail": "Schema 'userss' not found"
}

500Internal Server Error

Something went wrong on our end.

Resolution:

Wait a moment and retry
Check our status page for outages
Contact support if issue persists

{
  "detail": "An unexpected error occurred",
  "request_id": "req_abc123"
}

Include request_id when contacting support.

Troubleshooting & FAQ

Why is my generated data not realistic?

DDL to Data infers data types from column names. Use descriptive names:

Instead of...	Use...
col1	email
field_a	first_name
val	price

Why am I getting a 403 error?

Email not verified: Check your inbox for verification email
Rate limit exceeded: Check your usage with GET /me
Plan limit reached: Upgrade your plan

Why is Story Mode slow?

Story Mode uses AI processing, which takes 2-5 seconds. Standard generation is instant (milliseconds). Use standard generation for CI/CD pipelines.

How do I reset my usage?

Usage resets automatically on your monthly billing date. Check your reset date with GET /me.

Can I use this in production?

DDL to Data is designed for development, testing, and demos. Don't use generated data in production databases with real users.

Need Help?

Can't find what you're looking for? We're here to help.

Contact Support Get Started Free