Keeping SQL Code Clean with SQL Developer’s Built‑in Formatter

The problem: inconsistent SQL makes reviews painful

When a team shares SQL scripts, variations in indentation, keyword casing, and line‑break style turn simple diffs into noisy battles. Developers waste time reformatting by hand, and automated checks often fail because the code does not match the agreed‑upon style.

Thesis: SQL Developer’s formatter can enforce a single style interactively, via menus, and from the command line, reducing manual rework while staying lightweight for most scripts.

How the formatter works in the SQL Worksheet

Open any .sql file in the SQL Worksheet. Select the text you want to format (or press Ctrl+A to select the whole file) and either right‑click → Format or hit the shortcut Ctrl+F7. SQL Developer applies the active formatter profile to the selection, adjusting keyword case, indentation, and line breaks according to the rules stored in that profile. Comments and existing whitespace that are not governed by the profile are left untouched.

Creating and tweaking a formatter profile

Profiles live under Preferences → Database → SQL Formatter. The dialog lists built‑in profiles (Oracle, Google, etc.) and any custom ones you have added. Clicking Edit opens the underlying XML file where you can change individual settings—for example, the maximum line width (LineWidth) or whether commas should appear at the start or end of a line (CommaPlacement). After saving the XML, return to the worksheet and re‑run Ctrl+F7 to see the new rules take effect immediately.

Batch formatting multiple files

When you need to enforce style across a whole repository, use the batch formatter:

1. Choose Tools → Format SQL from the main menu.
2. In the dialog, add the folder or individual .sql files you want to process.
3. Select the profile to apply and optionally specify an output directory.
4. Click OK; SQL Developer will read each file, format it, and write the result (or overwrite the original, depending on your choice).

For environments without the GUI, the installation includes a command‑line tool sdcli. A typical invocation looks like:

sdcli format -input /path/to/project -output /path/to/formatted -profile Oracle -recursive

This walks the input directory, formats every .sql file with the Oracle profile, and places the formatted copies in the output directory. You can then diff the original and formatted versions to verify consistency.

Trade‑off and limitation

The formatter’s grammar is tied to the SQL Developer release. New Oracle syntax introduced after a given version—such as JSON_TABLE or polymorphic table functions—may not be recognized, causing the tool to leave those constructs unchanged or to apply unexpected spacing. Upgrading SQL Developer or importing an updated profile XML resolves the issue, but teams must stay aware of version mismatches when sharing format files across different installations.

Very large scripts (hundreds of megabytes) can cause noticeable UI lag or temporary memory spikes during formatting. In those cases, splitting the file into logical units or increasing the JVM heap size for SQL Developer (via the ide.conf file) can mitigate the impact.

Actionable closing

Start by checking your current profile: open Preferences, note the active name, and run Ctrl+F7 on a sample script to see the result. If the style does not match your team’s guide, edit the XML to adjust line width, keyword case, or comma placement, then re‑apply. For repository‑wide enforcement, add the batch formatter step to your CI pipeline or run sdcli nightly against your source control. Periodically export the profile XML (Preferences → Database → SQL Formatter → Export) and back it up before upgrading SQL Developer to avoid losing custom rules.