Enforcing Consistent SQL Style Across Teams with SQL Developer Formatter Profiles

The Problem: Inconsistent SQL Formatting Slows Reviews

Every team has that one pull request where the diff is 90% whitespace changes because someone formatted their PL/SQL package differently. SQL Developer ships with a capable formatter, but most developers never move past the default Oracle SQL*Plus style. The result: fragmented conventions, noisy diffs, and wasted review cycles.

SQL Developer's SQL Formatter supports custom profiles saved as portable XML files. You can define indentation, keyword casing, comma placement, and line-wrapping rules once, share the profile across the team, and apply it with a keystroke or from CI. This post walks through creating a team profile, exporting it, and automating formatting in a pipeline.

Understanding the Default Formatter

Open Preferences → Database → SQL Formatter. The active profile dropdown shows Oracle Default out of the box. Click the pencil icon to inspect rules: indentation uses 3 spaces, keywords are uppercase, commas lead lines, and line wrapping triggers at 80 characters. Press Ctrl+Shift+F (Windows/Linux) or Cmd+Shift+F (macOS) in any worksheet to apply the active profile instantly.

The formatter respects PL/SQL blocks, anonymous blocks, and SQL*Plus commands (SET, SPOOL, DESCRIBE). Comments and string literals remain untouched; only whitespace and case change.

Building a Team Profile

Suppose your team agrees on: 4-space indentation, lowercase keywords, trailing commas, and 120-column wrapping. In the formatter preferences, duplicate Oracle Default (click the plus icon), name it Team_Standard, and adjust:

• Indentation: 4 spaces, uncheck "Use tabs"
• Case: Keywords → lowercase, Identifiers → unchanged
• Commas: Trailing (after column/expression)
• Line Wrapping: 120 characters, wrap long IN lists

Click OK to save. The profile now appears in the dropdown and applies to every worksheet where it's selected.

Worked Example: Formatting a Messy Query

Paste this unformatted snippet into a worksheet:

select  EMPLOYEE_ID,FIRST_NAME,LAST_NAME,HIRE_DATE,SALARY from EMPLOYEES where DEPARTMENT_ID in (10,20,30,40,50,60,70,80,90,100) and SALARY > 5000 order by HIRE_DATE desc;

With Team_Standard active, press Ctrl+Shift+F. The output becomes:

select
    employee_id,
    first_name,
    last_name,
    hire_date,
    salary
from employees
where department_id in (
    10,
    20,
    30,
    40,
    50,
    60,
    70,
    80,
    90,
    100
)
and salary > 5000
order by hire_date desc;

Keywords are lowercase, each column sits on its own line with trailing commas, the IN list wraps, and indentation uses 4 spaces. No logic changed—only layout.

Sharing the Profile Across the Team

In the formatter preferences, select Team_Standard and click Export. Save Team_Standard.xml to your repo (for example, .sqldev/formatter/Team_Standard.xml). Teammates import it via Import in the same dialog. Once imported, the profile appears in their dropdown and behaves identically.

For CI enforcement, use the command-line formatter introduced in SQL Developer 21.2. On a build agent with SQL Developer installed, run:

sqldeveloper -nosplash \
  -J-Dide.conf.user.home=/opt/sqldev/config \
  sdcli format \
  -profile /workspace/.sqldev/formatter/Team_Standard.xml \
  -input /workspace/src/sql \
  -output /workspace/build/formatted_sql

Run this on the CI agent with permissions to read the workspace and write the output directory. Replace the paths with your own. This formats every .sql file under src/sql and writes results to build/formatted_sql. Add a diff step comparing the formatted output against the committed source to fail the build when files are not formatted to the team profile. Exact sdcli format flags can vary by release, so confirm the supported options with sdcli format -help on your installed version before wiring it into a pipeline.

Trade-offs and Limitations

• Semantics unchanged: The formatter never rewrites logic. A missing join condition or wrong alias remains wrong—testing and compilation are still required.
• Large scripts: Files over roughly 10 MB can spike memory and temporarily freeze the UI. Split monolithic scripts or increase the IDE heap via ide.conf (AddVMOption -Xmx2048M).
• SQL*Plus commands: Some obscure SET options may not wrap as expected; verify output for scripts heavy on SQL*Plus directives.
• Version coupling: Profiles exported from newer versions may not import cleanly into older releases. Keep the team on a similar SQL Developer version (21.2 or later for CLI use).

Actionable Next Steps

1. Open Preferences → Database → SQL Formatter and duplicate the default profile.
2. Adjust rules to match your team's style guide; name it descriptively.
3. Export the XML to version control under a shared path.
4. Document the import steps in your onboarding guide.
5. Add the sdcli format step to your CI pipeline and gate merges on a clean diff.

Run a quick verification today: format a representative package with the new profile, diff against the current version, and confirm only whitespace and case changed. That single check proves the profile works before you roll it out.