Introduction

Well-formatted SQL is easier to read, debug, and maintain. Poor formatting makes queries hard to understand and increases the chance of errors. This guide explains why SQL formatting matters and how to do it right.

Why Format SQL?

Problems with Poor Formatting

-- ❌ Hard to read
SELECT u.id,u.name,u.email,o.id as order_id,o.total FROM users u JOIN orders o ON u.id=o.user_id WHERE u.status='active' AND o.created_at>'2024-01-01' ORDER BY o.total DESC;

-- ✅ Easy to read
SELECT
  u.id,
  u.name,
  u.email,
  o.id AS order_id,
  o.total
FROM users u
JOIN orders o ON u.id = o.user_id
WHERE u.status = 'active'
  AND o.created_at > '2024-01-01'
ORDER BY o.total DESC;

Benefits:

  • ✅ Easier to debug
  • ✅ Better code reviews
  • ✅ Reduced errors
  • ✅ Faster onboarding

Formatting Standards

Keywords

Capitalize SQL keywords:

SELECT id, name FROM users WHERE status = 'active';

Indentation

Indent JOINs and subqueries:

SELECT u.name, o.total
FROM users u
  JOIN orders o ON u.id = o.user_id
  JOIN products p ON o.product_id = p.id
WHERE u.status = 'active';

Line Breaks

Break long queries:

SELECT
  u.id,
  u.name,
  u.email,
  COUNT(o.id) AS order_count,
  SUM(o.total) AS total_spent
FROM users u
  LEFT JOIN orders o ON u.id = o.user_id
WHERE u.created_at > '2024-01-01'
GROUP BY u.id, u.name, u.email
HAVING COUNT(o.id) > 5
ORDER BY total_spent DESC
LIMIT 10;

Common Patterns

SELECT Statements

SELECT
  column1,
  column2,
  column3
FROM table_name
WHERE condition1
  AND condition2
ORDER BY column1;

JOINs

SELECT
  u.name,
  o.total
FROM users u
  INNER JOIN orders o ON u.id = o.user_id
  LEFT JOIN payments p ON o.id = p.order_id
WHERE u.status = 'active';

Subqueries

SELECT name
FROM users
WHERE id IN (
  SELECT user_id
  FROM orders
  WHERE total > 100
);

CASE Statements

SELECT
  name,
  CASE
    WHEN age < 18 THEN 'Minor'
    WHEN age < 65 THEN 'Adult'
    ELSE 'Senior'
  END AS age_group
FROM users;

Best Practices

✅ Do This

1. Consistent formatting

-- Use same style throughout
SELECT id, name FROM users;
SELECT product_id, price FROM products;

2. Align columns

SELECT
  id          AS user_id,
  name        AS user_name,
  email       AS user_email,
  created_at  AS registration_date
FROM users;

3. Comment complex logic

-- Calculate total revenue per customer
SELECT
  u.id,
  SUM(o.total) AS total_revenue
FROM users u
  JOIN orders o ON u.id = o.user_id
WHERE o.status = 'completed'  -- Only count completed orders
GROUP BY u.id;

❌ Don’t Do This

1. Don’t use inconsistent capitalization

-- ❌ Mixed case
select ID, Name from USERS;
Select id, name From users;

-- ✅ Consistent
SELECT id, name FROM users;

2. Don’t put everything on one line

-- ❌ Hard to read
SELECT u.id,u.name,o.total FROM users u JOIN orders o ON u.id=o.user_id WHERE u.active=1;

-- ✅ Formatted
SELECT
  u.id,
  u.name,
  o.total
FROM users u
  JOIN orders o ON u.id = o.user_id
WHERE u.active = 1;

Tools

Use our tools:

Other tools:

  • Prettier (SQL plugin)
  • sqlformat (Python)
  • pgFormatter (PostgreSQL)

Conclusion

SQL formatting improves:

Benefits:

  • Readability
  • Maintainability
  • Code reviews
  • Debugging speed
  • Team collaboration

Key principles:

  • Consistent style
  • Proper indentation
  • Clear structure
  • Helpful comments

Next Steps