DDL→Data
Documentation

DDL to Data API Guide

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

Getting Started

DDL to Data lets you generate realistic test data from SQL CREATE TABLE statements in three simple steps:

1

Get API Key

Sign up for free to get your API key

2

Create Schema

POST your CREATE TABLE DDL

3

Generate Data

GET realistic JSON data

Get Free API Key

Authentication

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

curl -H "X-API-Key: your_api_key_here" \
  https://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.

API Endpoints

GET/schemas

Retrieve a list of all your registered schema names.

Response

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

Example

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

Register a new schema by providing a name and your CREATE TABLE DDL statement.

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
  );"
}

Response

{
  "message": "Schema 'users' created successfully"
}

Example

curl -X POST https://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));"}'
GET/api/generate/{table_name}

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

Parameters

table_namestringrequired- Name of the schema to generate data for
rowsintegerrequired- Number of rows to generate (default: 10, max: 10000)
formatstring- Output format: json (default), csv, or sql

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"
  }
]

Example

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

Output Formats

Use the format parameter to get data in different formats:

JSON (default)

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

CSV

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

# Output:
# 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

SQL INSERT Statements

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

# Output:
# 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');
DELETE/schemas/{table_name}

Delete an existing schema and remove it from your account.

Parameters

table_namestringrequired- Name of the schema to delete

Response

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

Example

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

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

Response

{
  "email": "you@example.com",
  "plan": "free",
  "calls_month": 45,
  "rows_month": 2500,
  "quota_calls_month": 100,
  "quota_rows_month": 5000
}

Example

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

Smart Data Types

DDL to Data automatically detects column types based on names and generates appropriate realistic values:

Column PatternGenerated DataExample
id, *_idSequential integers1, 2, 3...
emailValid email addressesjohn.doe@gmail.com
first_name, namePerson namesSarah, Michael
last_name, surnameFamily namesJohnson, Chen
phone, mobilePhone numbers+1-555-123-4567
address, streetStreet addresses123 Main St
cityCity namesNew York, London
countryCountry namesUnited States
zip, postalPostal codes10001, SW1A 1AA
price, amount, costDecimal numbers149.99
url, websiteURLshttps://example.com
*_at, date, timestampISO timestamps2024-03-15T09:23:41
description, bio, textLorem ipsum textLorem ipsum dolor...
is_*, has_*Boolean valuestrue, false
uuidUUID v4550e8400-e29b-41d4-...

Foreign Keys & Relationships

DDL to Data supports foreign key relationships, allowing you to generate consistent data across related tables.

Use the POST /relationships endpoint to define how tables relate:

curl -X POST https://ddltodata.com/relationships \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_table": "users",
    "parent_column": "id",
    "child_table": "orders",
    "child_column": "user_id"
  }'

Rate Limits & Plans

PlanAPI Calls/MonthRows/MonthPrice
Free1005,000$0
Starter50050,000$19/mo
ProUnlimited250,000$79/mo
EnterpriseCustomCustomContact us
View full pricing details →

Error Handling

The API returns standard HTTP status codes with JSON error details:

400
Bad Request - Invalid DDL syntax or missing required fields
401
Unauthorized - Missing or invalid API key
403
Forbidden - Rate limit exceeded or email not verified
404
Not Found - Schema or endpoint not found
429
Too Many Requests - Rate limit exceeded
500
Server Error - Internal server error

Error Response Format

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

Code Examples

# pip install requests psycopg2-binary
import requests
import psycopg2

API_KEY = "your_api_key"  # Replace with 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://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://ddltodata.com/api/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!")

Need Help?

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

Contact SupportGet Started Free
DDL to Data - Generate Realistic Fake Data from SQL Schemas | Test Data API