GitHub Swift Weekly Trending Repositories

Lakr233/vphone-cli

🇰🇷한국어 | 🇯🇵日本語 | 🇨🇳中文 | 🇬🇧English

vphone-cli

Boot a virtual iPhone via Apple's Virtualization.framework using PCC research VM infrastructure.

Prerequisites

Host:

Apple Silicon
macOS 15+ (Sequoia)
SIP/AMFI relaxation to allow private PV=3 entitlements with unsigned-binary

Dependencies:

brew install python@3.13 aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone cmake libusb ipsw zstd

Install

brew install zqxwce/tap/vphone-cli

Build

git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git

./scripts/setup_tools.sh      # install deps, build toolchain submodules, create the Python venv
./scripts/build.sh            # build + sign vphone-cli, bundle the .app, cross-compile vphoned

cd .build/vphone-cli.app/Contents/MacOS/
vphone-cli --help

Quick Start

One command creates a VM end-to-end (download → patch → DFU restore → CFW install → first boot):

vphone-cli vm create myphone -V jb        # -V / --variant

vphone-cli vm launch myphone

Commands

vphone-cli vm create runs the whole pipeline; the individual steps below let you drive it manually or re-run one stage.

Manage

vphone-cli vm list                         # list VMs (--json for scripting)
vphone-cli vm info myphone                  # show one VM
vphone-cli vm new myphone                   # create an empty bundle (cpu/mem/disk options)
vphone-cli vm config myphone --cpu 8 --memory 8192
vphone-cli vm clone myphone myphone-2       # fast APFS clone, fresh device identity
vphone-cli vm export myphone --out myphone.tar.xz   # xz -9; skips restore dir + staging files
vphone-cli vm import --in myphone.tar.xz --name restored
vphone-cli vm rename myphone iphone16
vphone-cli vm delete iphone16

Build a VM manually (what `vm create` automates)

vphone-cli vm new myphone                              # 1. empty bundle
vphone-cli fw prepare myphone --iphone-version 26.1     # 2. download + merge IPSWs
vphone-cli fw patch myphone --variant jb                # 3. patch the boot chain

vphone-cli vm launch myphone --dfu &                    # 4. boot into DFU (background)
vphone-cli restore myphone --get-shsh                   #    fetch SHSH
vphone-cli restore myphone                              #    DFU restore
vphone-cli vm stop myphone                              #    stop the DFU boot

vphone-cli cfw install myphone --variant jb             # 5. install CFW (host-mount; asks for sudo)
vphone-cli vm launch myphone                            # 6. first boot

Update to a newer iOS by pointing fw prepare at an IPSW: --iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw.

Firmware Variants

Five patch variants with increasing security bypass — pass one to --variant:

Variant	Boot Chain	CFW	Notes
`less`	4 patches	2 phases	Patchless — keeps iOS mitigations enabled
`regular`	42 patches	10 phases	AMFI/SSV/Img4/TXM bypass
`dev`	53 patches	12 phases	+ TXM entitlement/debug bypass
`jb`	113 patches	14 phases	+ full jailbreak (Sileo, TrollStore auto-install on first boot)
`exp`	141 patches	18 phases	JB superset + anti-VM-detection research patches

See research/0_binary_patch_comparison.md for the per-component breakdown.

Running & Connecting

SSH (jailbreak): ssh -p 22222 mobile@<vm-ip> (password alpine)
SSH (regular/dev): ssh -p 22222 root@<vm-ip>
VNC: vnc://<vm-ip>:5901

Locations

Everything vphone-cli creates lives under ~/.vphone/ — kept outside the repo and the .app so the signed bundle stays portable:

Path	Contents
`~/.vphone/VMs/`	VM bundles — one directory per VM. This is the library; override with `$VPHONE_LIBRARY_ROOT`.
`~/.vphone/ipsws/`	Downloaded iPhone + cloudOS IPSWs, cached and reused across VMs.
`~/.vphone/tools/`	Cached APFS seal-volume artifacts (`apfs_sealvolume_<version>`) fetched during `fw prepare`.
`~/.vphone/debs/`	Cached `.deb` packages the `jb`/`exp` CFW install lays into the guest (Sileo, apt, …).
`~/.vphone/venv/`	Auto-provisioned Python environment (see Python runtime; override with `$VPHONE_VENV_DIR`).

SIP/AMFI Relaxation

Option A — fully disable SIP, then disable AMFI via boot-arg (most permissive).

In Recovery (long-press power → Terminal):

csrutil disable
csrutil allow-research-guests enable

Then reboot into macOS and set the AMFI boot-arg (needs SIP fully off to take effect):

sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"   # reboot after

Option B — keep SIP on (debug-only relaxed), then allowlist the binary with amfidont (leaves AMFI enabled system-wide).

In Recovery:

csrutil enable --without debug
csrutil allow-research-guests enable

Then reboot into macOS and:

vphone-amfidont         # .build/vphone-cli.app/Contents/Resources/vphone-amfidont for local builds

Tested Environments

Host	iPhone	CloudOS
Mac16,11 27.0b2	`17,3_18.6.2_22G100`	`26.1-23B85`
Mac16,8 26.5.1	`17,3_26.0_23A341`	`26.1-23B85`
Mac16,8 26.5.1	`17,3_26.0.1_23A355`	`26.1-23B85`
Mac16,12 26.3	`17,3_26.1_23B85`	`26.1-23B85`
Mac16,12 26.3	`17,3_26.3_23D127`	`26.1-23B85`
Mac16,12 26.3	`17,3_26.3_23D127`	`26.3-23D128`
Mac16,12 26.3	`17,3_26.3.1_23D8133`	`26.3-23D128`
Mac16,11 26.2	`17,3_26.4_23E246`	`26.4-23E5207q`
Mac16,11 26.2	`17,3_26.5_23F77`	`26.4-23E5207q`
Mac16,11 27.0b2	`17,3_26.5.2_23F84`	`26.4-23E5207q`
Mac16,6 25.4.1	`17,3_26.6_23G71`	`26.4-23E5207q`
Mac16,11 27.0b2	`17,3_27.0_24A5380h`	`26.4-23E5207q`
Mac16,6 25.4.1	`17,3_27.0_24A5390f`	`26.4-23E5207q`

FAQ

zsh: killed ./vphone-cli — AMFI/debug restrictions aren't bypassed; see Prerequisites (amfi_get_out_of_my_way=1 or amfidont).

Virtualization is not available on this hardware — your Mac is itself a VM; PV=3 guest boot can't nest. Use a non-nested macOS 15+ host.

Stuck on "Press home to continue" — connect via VNC and right-click (two-finger click) to simulate the home button.

System apps won't install — during iOS setup, don't pick Japan or the EU as your region (extra regulatory checks the VM can't satisfy); pick e.g. United States.

App crashes on launch with EXC_GUARD / GUARD_TYPE_MACH_PORT — re-patch with vphone-cli fw patch <name> --variant <v> --force-exc-guard, then re-restore/install (#291). Always on for iOS 18 bases.

Install a .ipa/.tipa — use the running VM's Install menu (drag-drop or file picker).

Automation

vphone-cli exposes a host control socket (<bundle>/vphone.sock) for programmatic control — screenshots, touch, swipes, hardware keys, clipboard — each action returning an inline screenshot for AI-driven E2E testing. See vphone-mcp for an MCP server wrapping it.

Acknowledgements

wh1te4ever/super-tart-vphone-writeup

utmapp/UTM

Virtual machines for iOS and macOS

UTM

It is possible to invent a single machine which can be used to compute any computable sequence.

-- Alan Turing, 1936

UTM is a full featured system emulator and virtual machine host for iOS and macOS. It is based off of QEMU. In short, it allows you to run Windows, Linux, and more on your Mac, iPhone, and iPad. More information at https://getutm.app/ and https://mac.getutm.app/

Features

Full system emulation (MMU, devices, etc) using QEMU
30+ processors supported including x86_64, ARM64, and RISC-V
VGA graphics mode using SPICE and QXL
Text terminal mode
USB devices
JIT based acceleration using QEMU TCG
Frontend designed from scratch for macOS 11 and iOS 11+ using the latest and greatest APIs
Create, manage, run VMs directly from your device

Additional macOS Features

Hardware accelerated virtualization using Hypervisor.framework and QEMU
Boot macOS guests with Virtualization.framework on macOS 12+

UTM SE

UTM/QEMU requires dynamic code generation (JIT) for maximum performance. JIT on iOS devices require either a jailbroken device, or one of the various workarounds found for specific versions of iOS (see "Install" for more details).

UTM SE ("slow edition") uses a threaded interpreter which performs better than a traditional interpreter but still slower than JIT. This technique is similar to what iSH does for dynamic execution. As a result, UTM SE does not require jailbreaking or any JIT workarounds and can be sideloaded as a regular app.

To optimize for size and build times, only the following architectures are included in UTM SE: ARM, PPC, RISC-V, and x86 (all with both 32-bit and 64-bit variants).

Install

UTM (SE) for iOS: https://getutm.app/install/

UTM is also available for macOS: https://mac.getutm.app/

Development

macOS Development

iOS Development

iSH: emulates a usermode Linux terminal interface for running x86 Linux applications on iOS
a-shell: packages common Unix commands and utilities built natively for iOS and accessible through a terminal interface

License

UTM is distributed under the permissive Apache 2.0 license. However, it uses several (L)GPL components. Most are dynamically linked but the gstreamer plugins are statically linked and parts of the code are taken from qemu. Please be aware of this if you intend on redistributing this application.

Some icons made by Freepik from www.flaticon.com.

Additionally, UTM frontend depends on the following MIT/BSD License components:

Continuous integration hosting is provided by MacStadium

BarutSRB/OmniWM

MacOS Niri and Hyprland inspired tiling window manager that's developer signed and notorized (safe for managed enterprise environments). Aiming for parity and extra innovation.

Demo Video

Contributors

Thank you to everyone who contributed to OmniWM. Your ideas and code made a real difference.

🏢 By Employer

Bitkey
_{━━━━━━━━}

Naoki Ikeguchi
_@siketyan

EPAM
_{━━━━━━━━}

Aleksei Gurianov
_@Guria

Finanzguru
_{━━━━━━━━}

Janek Thomaschewski
_{@jthomaschewski}

GitHub
_{━━━━━━━━}

Ryan Hecht
_@RyanHecht

Google
_{━━━━━━━━}

muhammadkh
_@MuhammadKh

Luxor Labs
_{━━━━━━━━}

Albert Ilagan
_{@albertilagan}

ReactSquad
_{━━━━━━━━}

Jan Hesters
_@janhesters

Spotify
_{━━━━━━━━}

Alexander Dergachev
_@Cy6erBr4in

vhf
_{━━━━━━━━}

Lukas Gerlinski
_@lgerlinski

Viber
_{━━━━━━━━}

Yuri Chukhlib
_@YuriNachos

🎓 By Education

Assumption University of Thailand
_{━━━━━━━━}

Panuphong Burakitphachai
_@t1dotdev

Linnaeus University
_{━━━━━━━━}

Balazs Hevesi
_{@balazshevesi}

NTU Singapore
_{━━━━━━━━}

Nawat Suangburanakul
_@holmns

SUSTech
_{━━━━━━━━}

Yang-Yiming
_@Yang-Yiming

✨ All Contributors

Real quake/sticky terminal using ghostty's libghostty
macOS native tab support
IPC/CLI
Scrathpad/Sticky windows for any app
Niri Overview
Unified command palette for windows and app menus
App menu anywhere
Niri tabbed columns and Dwindle tile groups
Niri and Dwindle layout
Hide/unhide status bar icons (Similar to Ice Bar)
Keep awake (Similar to Caffeine)
Interactive workspace/app icon bar
A lot more features not show in the video.

Known Limitations

Dwindle group restore - Group membership and tab order are runtime layout state and are not restored after OmniWM restarts.

Performance & Trust

OmniWM is built for high responsiveness and smooth, crisp animations.

Private APIs - OmniWM leverages Apple's private APIs where ever technically possible in order to reduce latency and improve window management responsiveness.
Refresh rate aware animations - OmniWM targets true display refresh pacing (for example 60/120/144Hz) for animations.
No SIP disable required - OmniWM does not require System Integrity Protection (SIP) to be disabled and never will.
Always notarized official releases - Official OmniWM release builds are developer signed and notarized by Apple and will stay that way.
Forever free, no limitations - OmniWM is and will remain free to use forever, with no subscriptions, feature paywalls, trial limits, or usage caps.

Requirements

macOS 26+ (Tahoe) on Apple Silicon
Accessibility permissions (prompted on launch)
Input Monitoring permission when using a System Hyper Trigger
Displays have separate spaces ON (the macOS default; OmniWM pauses window management until it is enabled)

Installation

Homebrew

brew tap BarutSRB/tap
brew install omniwm

Nix

OmniWM supports both community-maintained Nix packages below. They install official OmniWM release artifacts, while their Nix expressions are maintained by DoomHammer and DavSanchez respectively.

Package	Best for	Packaging difference
DoomHammer NUR package	Fast release tracking	Its current `unzip` extraction does not preserve the release's valid Developer ID signature, and it installs the app bundle without exposing `omniwmctl` on `PATH`.
DavSanchez package and Home Manager module	Signature-preserving, declarative integration	It may trail the latest release, but its `bsdtar` extraction preserves code signing and it provides `omniwmctl`, Home Manager settings, and launchd integration.

Install the fast-tracking DoomHammer package directly:

nix profile install github:DoomHammer/nur-packages#omniwm

Existing NUR configurations can use nur.repos.doomhammer.omniwm.

Install the signature-preserving DavSanchez package directly:

nix profile install github:DavSanchez/nix-dotfiles#omniwm

For a declarative setup, use DavSanchez's exported homeModules.omniwm and overlays.additions. After either installation, complete the macOS setup in steps 3-6 below.

GitHub Releases

Download the latest OmniWM.zip from Releases
Extract and move OmniWM.app to /Applications
In System Settings > Desktop & Dock > Mission Control, turn ON Displays have separate Spaces
Log out of macOS and log back in for that change to take effect unless you had it on already
Launch OmniWM and grant Accessibility permissions when prompted
To use a System Hyper Trigger, grant Input Monitoring from Settings > Hotkeys

Updates

OmniWM checks for updates by default.

On launch, OmniWM polls the latest GitHub release at most once per day.
Updates stay manual. OmniWM does not auto-download or auto-install a new release.
When a newer release is available, OmniWM shows a centered popup with release notes and actions for Open Release Page, Copy brew upgrade omniwm, Skip This Version, and Not Now.
You can control this from Settings > General > Updates or trigger a manual check from the status bar menu with Check for Updates....

Documentation

The documentation hub lives in docs/index.md.

IPC and CLI

OmniWM ships with a bundled CLI, omniwmctl, for automation and scripting.

IPC is disabled by default. Enable Enable IPC from the menu bar before using the CLI or any automation.

For setup, installation options, commands, queries, rules, subscriptions, and security details, see docs/IPC-CLI.md.

Quick Start

Launch OmniWM from your Applications folder
In System Settings > Desktop & Dock > Mission Control, turn ON Displays have separate Spaces
Log out of macOS and log back in for that change to take effect unless you had it on already
Grant Accessibility permissions in System Settings > Privacy & Security > Accessibility
Windows will automatically tile in columns
Keep one macOS Space per display and navigate with OmniWM workspaces; extra native Spaces are tolerated (their windows are left to macOS, not tiled)
Use the default shortcuts in Keyboard Shortcuts to navigate between windows
Click the menu bar icon to access Settings, including Settings > General > Updates
Use Check for Updates... from the status bar menu whenever you want to run a manual update check
In case you freak out and don't see all your status bar icons, relax, OmniWM hides the menu-bar icons you selected in Settings > Hidden Bar. Right-click OmniWM's status bar icon to open the Hidden Icons Bar and click any icon to use it.

User Guide

Multi-Monitor Setup

OmniWM uses two display maps for different jobs:

Open System Settings > Displays > Arrange. Put the physically largest or widest display at the bottom. Place the next smaller display above and to its right so its bottom-left corner touches the lower display's top-right corner. Continue the same staircase for every additional display. This macOS map is a technical arrangement used for actual window placement; it does not need to look like your desk.
Open OmniWM Settings > Monitors and arrange the OmniWM routing map to match where the displays really sit on your desk. Keep every display connected by a left, right, up, or down edge; diagonal-only displays cannot exchange directional focus, window moves, or mouse warp.
Leave Mouse Warp turned on for the recommended experience. It lets the pointer cross between displays according to the real-desk OmniWM map even though macOS uses the staircase.

The setup assistant opens automatically when OmniWM first sees multiple displays. To review or redo it later, choose Run Monitor Setup… in Settings > Monitors. The assistant's Show Numbers on Screens action helps match each physical display to its tile.

Layout Modes

OmniWM offers two layout engines that you can switch between per workspace:

Niri (Scrolling Columns) - Windows arranged in vertical columns that scroll horizontally. Each column can have multiple stacked windows or be "tabbed" (multiple windows, one visible at a time). Best for wide monitors with many windows.

Hyprland Dwindle (BSP) - Binary space partition layout that recursively divides screen space. Each new window splits the space in half, and a tile can group multiple windows as tabs. Best for traditional tiling with predictable layouts.

Use the Toggle Workspace Layout shortcut below to switch layouts per workspace or configure them in GUI settings.

Keyboard Shortcuts

All shortcuts are customizable in Settings > Hotkeys. Hyper is the literal Control + Option + Shift + Command chord by default; which modifiers make up Hyper is configurable in Settings > Hotkeys (for example, exclude Shift to keep Hyper + Shift + … free for extra bindings). Changing the combination retargets every shortcut that currently resolves to Hyper onto the new one, so the shortcut list updates in place as you toggle the modifiers. Optionally pick a System Hyper Trigger — a single key (Caps Lock, F13–F20, or a left- or right-side modifier) or an extra mouse button that acts as Hyper while held (this needs Input Monitoring permission). Leave the trigger as None if you already produce Hyper another way, such as a Karabiner Elements remap. The tables below list all the default hotkeys:

Layout legend:

Shared works in any active layout.
Niri works only when the active workspace uses the Niri layout.
Dwindle works only when the active workspace uses the Dwindle layout.

Workspace

Action	Default Shortcut	Layout
Switch to Workspace 1-9	`Option + 1-9`	`Shared`
Move Window to Workspace 1-9	`Option + Shift + 1-9`	`Shared`
Switch to Previous Workspace (Back and Forth)	`Control + Option + Tab`	`Shared`
Switch to Next Workspace	`Unassigned`	`Shared`
Switch to Previous Workspace (Sequential)	`Unassigned`	`Shared`
Move Window to Workspace Up	`Control + Option + Shift + Up Arrow`	`Shared`
Move Window to Workspace Down	`Control + Option + Shift + Down Arrow`	`Shared`
Move Column to Workspace 1-9	`Unassigned`	`Niri`
Move Column to Workspace Up	`Control + Option + Shift + Page Up`	`Niri`
Move Column to Workspace Down	`Control + Option + Shift + Page Down`	`Niri`

Focus

Action	Default Shortcut	Layout
Focus Left / Right / Up / Down	`Option + Arrow Keys`	`Shared`
Focus Down or Top / Up or Bottom	`Unassigned`	`Shared`
Focus Previous Window	`Option + Tab`	`Niri`
Traverse Backward	`Unassigned`	`Niri`
Traverse Forward	`Unassigned`	`Niri`
Focus First Column	`Option + Home`	`Niri`
Focus Last Column	`Option + End`	`Niri`
Focus Column 1-9	`Control + Option + 1-9`	`Niri`
Toggle Command Palette	`Control + Option + Space`	`Shared`
Open Menu Anywhere	`Control + Option + M`	`Shared`
Toggle Workspace Bar	`Unassigned`	`Shared`
Toggle Hidden Icons Bar	`Unassigned`	`Shared`
Toggle Quake Terminal	Option + `	`Shared`
Toggle Overview	`Option + Shift + O`	`Shared`

Move Window

Action	Default Shortcut	Layout
Move Left / Right / Up / Down	`Option + Shift + Arrow Keys`	`Shared`
Reorder Window Up / Down	`Unassigned`	`Shared`

Monitor

Action	Default Shortcut	Layout
Focus Next Monitor	`Control + Command + Tab`	`Shared`
Focus Previous Monitor	`Unassigned`	`Shared`
Focus Last Monitor	Control + Command + `	`Shared`
Move Workspace to Left / Right / Up / Down Monitor	`Unassigned`	`Shared`
Move Window to Left / Right / Up / Down Monitor	`Unassigned`	`Shared`

The workspace-to-monitor actions target the active workspace and intentionally use the same temporary runtime override as omniwmctl workspace move-to-monitor --force. They do not rewrite the workspace's Home Monitor or swap workspaces, and unsafe fullscreen, hidden-app, scratchpad, or focus states still block the move.

The window-to-monitor actions send the focused window directly to the current workspace on the adjacent routed display, independently of Move Window Across Monitor at Edge. They do not wrap when no monitor exists in that direction. Follow Window to Monitor controls whether focus follows the window; when it is off, you remain in the source workspace.

Layout

Action	Default Shortcut	Layout
Toggle Fullscreen	`Option + Return`	`Shared`
Toggle Native Fullscreen	`Unassigned`	`Shared`
Balance Sizes	`Option + Shift + B`	`Shared`
Cycle Size Forward	`Option + .`	`Shared`
Cycle Size Backward	`Option + ,`	`Shared`
Move to Root	`Unassigned`	`Dwindle`
Toggle Split	`Unassigned`	`Dwindle`
Swap Split	`Unassigned`	`Dwindle`
Grow Horizontally / Vertically	`Unassigned`	`Dwindle`
Shrink Horizontally / Vertically	`Unassigned`	`Dwindle`
Grow / Shrink Focused Window	`Unassigned`	`Dwindle`
Preselect Left / Right / Up / Down	`Unassigned`	`Dwindle`
Clear Preselection	`Unassigned`	`Dwindle`
Raise All Floating Windows	`Option + Shift + R`	`Shared`
Toggle Focused Window Floating	`Unassigned`	`Shared`
Assign Focused Window to Scratchpad	`Unassigned`	`Shared`
Toggle Scratchpad Window	`Unassigned`	`Shared`
Toggle Workspace Layout	`Option + Shift + L`	`Shared`

Container and Column

Action	Default Shortcut	Layout
Move Container Left / Right	`Control + Option + Shift + Left / Right Arrow`	`Shared`
Move Container Up / Down	`Unassigned`	`Dwindle`
Toggle Column Tabbed	`Option + T`	`Niri`
Toggle Container Full Primary Span	`Option + Shift + F`	`Niri`

The daily Focus and Move shortcuts adapt to the active layout. In Niri, Move Left / Right expels the focused window from a multi-window column or consumes a single-window column into its neighbor, while Move Up / Down reorders within the column.

Dwindle Groups

Dwindle groups use the existing Focus and Move bindings, so there are no separate group shortcuts to memorize. Only the active member occupies the tile; the other members stay hidden and the clickable tab rail shows their order.

Goal	Default Shortcut	Behavior
Focus another tile	`Option + Arrow Keys`	Left / Right are always spatial. Up / Down are spatial for a singleton tile.
Select the next / previous tab	`Option + Down / Up Arrow`	Within a group, Down advances and Up goes back. At the group edge OmniWM tries a spatial tile, then the configured monitor transition, and wraps locally only when neither exit succeeds.
Join a singleton into a tile or group	`Option + Shift + Arrow Keys`	Joins the focused singleton with the touching tile in that direction.
Extract the active tab	`Option + Shift + Arrow Keys`	When the focused tile is grouped, extracts only its active tab onto the requested side.
Move the complete tile or group	`Control + Option + Shift + Left / Right Arrow`	`Move Container` swaps the whole structure. Up / Down are advanced, unassigned Dwindle actions.
Select an exact tab	Click its tab rail item	Reveals and focuses that member without changing the group order.

Moving a tab directly from one existing group into another is intentionally a two-step operation: extract it first, then move the resulting singleton toward the destination group. A singleton at a genuine workspace edge can still use the normal cross-monitor Move behavior; a rejected group mutation does not fall through to tile swapping or monitor movement.

The unassigned advanced actions are available in Settings > Hotkeys. Focus Down or Top / Up or Bottom always wraps within the active Niri column or Dwindle group. Reorder Window Up / Down changes the active member's position by one without wrapping. Move Container is the whole-structure escape hatch and never transfers to another monitor at a workspace edge. Dwindle join/extract and Move Container operations are intentionally unavailable while Overview is open; leave Overview before changing a Dwindle tree.

Quake Terminal (Inside Terminal)

Action	Shortcut
New Tab	`Cmd + T`
Close Tab	`Cmd + W`
Next Tab	`Cmd + Shift + ]`
Previous Tab	`Cmd + Shift + [`
Next Tab (Alt)	`Ctrl + Tab`
Previous Tab (Alt)	`Ctrl + Shift + Tab`
Select Tab 1-9	`Cmd + 1-9`
Split Pane (Horizontal)	`Cmd + D`
Split Pane (Vertical)	`Cmd + Shift + D`
Close Pane	`Cmd + Shift + W`
Equalize Splits	`Cmd + Shift + =`
Navigate Pane	`Cmd + Option + Arrow Keys`

Features

Quake Terminal

A true quake/sticky terminal (powered by Ghostty's libghostty) that slides in from the screen edge and:

Toggle it from the global shortcut shown in Keyboard Shortcuts
Supports multiple tabs and splits within tabs
Tab and pane shortcuts are listed in Quake Terminal (Inside Terminal)
Mouse resize by dragging edges; Option + drag to move (remembers size/position per monitor)
Configure position (top/bottom/left/right/center), size, opacity, and background effect in Settings
Choose Standard Blur with an adjustable radius or native Regular Glass/Clear Glass; switching effects preserves the saved Standard Blur radius
Auto-hides on focus loss (optional)

Command Palette

Quickly search windows, app menus, or clipboard history from one shared palette:

Open it from the global shortcut shown in Keyboard Shortcuts
Use Tab / Shift + Tab to cycle forward or backward through the available modes
Use Cmd + 1 for Windows, Cmd + 2 for Menu, and Cmd + 3 for Clipboard
Type to fuzzy-search by window title, app name, menu item, or clipboard content
Menu results always show keyboard shortcuts when available
Up / Down move the selection
Enter activates the selected result
Shift + Enter summons the selected window to the right when available
Escape dismisses the palette

Menu Anywhere

Access any application's menu from your keyboard:

Shows the native menu at the cursor from a global shortcut

Overview Mode

See all windows at once with thumbnails:

Open it from the global shortcut shown in Keyboard Shortcuts
Configure the 50–150% baseline zoom plus backdrop and window-border colors in Settings → Overview
Click a window to focus it
Type to filter/search windows; Backspace deletes search text
Alt (Option) + Shift + Mouse Scroll temporarily zooms the current overview; the next opening starts from the configured baseline
Arrow Keys navigate the selection; Tab / Shift + Tab move horizontally, and keyboard navigation automatically scrolls the selected thumbnail into view
Assigned structural move, reorder, consume/expel, and workspace-transfer shortcuts operate on the selected thumbnail while Overview is open
In Niri workspaces, reorder windows and columns, consume or expel windows, move windows into or out of columns, move windows across workspaces and monitors, and move whole columns between Niri workspaces
Adjacent-workspace fallback actions can create the next compatible unused numeric workspace when moving past the current workspace edge
In Dwindle workspaces, Overview supports moving windows across workspaces and closing them without adding Overview-only tree placement controls
A successful move keeps the moved window selected and activates its destination workspace and monitor behind Overview
Option + drag a thumbnail onto a workspace, an exact window position, or a Niri column gap; layouts without an exact placement equivalent fall back to moving it to the destination workspace
Command + W closes the selected window once per press and keeps Overview open; selection advances only after the window has closed
Enter, Escape, the configured Overview shortcut, and clicking the backdrop dismiss Overview and focus the current selection; Escape does not clear search first
If another application takes focus, Overview dismisses without stealing focus back

Workspace Bar

A visual indicator showing your workspaces:

Displays open apps per workspace
Click to switch workspaces or jump to that app
If dedupe option is on click the app icon to get a popup with list of all its windows to jump to
Configure position, height, and appearance in Settings
Exclude individual apps or choose alternate app icons across all monitors in Settings

Workspace-bar icon overrides can also be configured in settings.toml. Quote bundle IDs so TOML treats each dotted identifier as one key:

[workspaceBar.iconOverrides]
"com.example.App" = "icons/custom.icns"
"com.cmuxterm.app" = "bundle-resource:AppIconDark"

bundle-resource: loads a named image packaged inside the selected app. The Settings picker discovers likely app-icon resources on demand; runtime-generated or downloaded Dock icons may not be available. Absolute paths are used as written, ~ expands to your home directory, and relative paths are resolved from the directory containing settings.toml. Overrides affect only the workspace bar. A valid override takes precedence over the app's standard icon; an unavailable or invalid image falls back to the standard icon, then the dashed placeholder when no app icon is available. OmniWM does not watch image files; use Replace to reload a file changed in place.

Hidden Bar

Conceal selected menu-bar icons and reach them from a panel:

Concealment requires macOS 27 or later; the rest of OmniWM continues to support macOS 26
Pick the apps to hide in Settings > Hidden Bar
Right-click (or Option-click) the OmniWM menu bar icon to open the Hidden Icons Bar; click an icon to reveal and use it
Revealed icons re-hide automatically after a configurable interval
An optional global hotkey is available and starts unassigned

Tips

Workspaces - Create named workspaces in Settings to organize by project or context (You can use emojis 🥳)
App Rules - Exclude problematic apps from tiling or assign them to specific workspaces
Mouse - On the Niri desktop, hold the configured mouse-move modifier and drag to swap tiled windows; add Shift to insert into a column. The modifier defaults to Option and can be changed or disabled in Settings → Mouse & Trackpad. In Overview, Option + drag targets a workspace, window position, or Niri column gap
Mouse Resize - Hold Option and right-drag a tiled window to resize (Niri)
Scroll Gestures (Mouse) - Hold Option + Shift + Mouse Scroll Wheel (default, configurable) and scroll through columns horizontally
Trackpad Gestures - Use horizontal gestures with 2/3/4 fingers (configurable); direction can be inverted (local hardware validation is limited)
Workspace Swipe (Trackpad) - Opt-in in Settings → Mouse & Trackpad: swipe with a configurable finger count (2/3/4) and axis (horizontal/vertical) to switch to the next/previous workspace on the monitor under the cursor, one switch per swipe; sharing the column-scroll finger count locks the axis to vertical. For vertical swipes with three or four fingers, first turn off Mission Control in  → System Settings → Trackpad → More Gestures so macOS does not intercept the gesture.

Configuration

Access settings by clicking OmniWM's status bar icon and selecting Settings or App Rules. Mouse and gesture settings live in Settings under Mouse & Trackpad.

OmniWM stores its editable config at ${XDG_CONFIG_HOME:-$HOME/.config}/omniwm/settings.toml; that file is the canonical settings source and is live-reloaded when saved from an editor.

Reveal Settings File and Edit Settings File open the canonical TOML file and recreate it from the running settings if it was deleted.
updateChecksEnabled is part of the persisted settings model, so it round-trips through settings.toml.
Clipboard history, last-check timestamps, skipped-release state, and the persisted window restore catalog live in ${XDG_STATE_HOME:-$HOME/.local/state}/omniwm and stay out of dotfile-oriented config storage.

App Rules

Configure per-application behavior in Settings > App Rules:

Always Float - Force specific apps to always float (e.g., calculators, preferences windows)
Assign to Workspace - Use a valid workspace assignment as the initial default whenever the matching app currently has no tracked windows. Additional windows open on the workspace active when creation began. Automatic rule reevaluation leaves managed windows in place, while explicit rule application can move them. Readmission, structural replacements, tracked transient children, and unique persisted boot-restore matches preserve their existing placement continuity.
Initial Container Primary Span (Niri) - Start matching resizable windows at 5–100% when they create or claim a new container; the container remains freely resizable afterward
Minimum Size - Prevent the layout engine from sizing windows below a threshold

Initial container primary span is a one-time seed. It controls width in horizontal orientation and height in vertical orientation. Niri's Single Window Fit still takes visual precedence for a lone window, and physical minimum-size constraints can clamp the resolved pixel size without changing the stored initial proportion.

The equivalent TOML rule uses a proportion:

[[appRules]]
bundleId = "net.kovidgoyal.kitty"
initialContainerPrimarySpan = 0.5

Building from Source

Requirements:

SwiftPM with Swift 6.4+
macOS 26.0+
Ghostty's arm64 archive (build Ghostty and copy it to Frameworks/GhosttyKit.xcframework/macos-arm64/libghostty-internal-fat.a)

Use the bundled Debug launch for day-to-day development:

make run

make run builds, packages, development-signs, and opens dist/OmniWM.app through LaunchServices. This is the canonical development launch because it gives OmniWM its normal app identity. OmniWM uses its native status bar item while Hidden Bar concealment is inactive. While concealment is active, it uses a separate fallback icon next to the workspace bar because macOS can conceal the app-owned status item with the other restricted items. This behavior applies to both bundled and raw swift run OmniWM launches and is not specific to Debug builds.

Related Forks

Nehir is an endorsed OmniWM fork focused on a narrower, more opinionated Niri-style scrolling-column workflow. It may be friendlier for beginners who want guided defaults and a smaller feature surface, while OmniWM remains the broader upstream project with multiple layout modes and the full feature set.
choru-k/OmniWM is an interesting personal OmniWM fork experimenting with opt-in workflow layers on top of upstream OmniWM, including zone anchors for the Niri strip, a configurable F13-F20 leader-key chord menu, tabbed-column keyboard cycling, and trackpad-friendly modifier resizing. It is best read as a power-user workflow branch rather than a replacement for the main OmniWM release.

Support

If you find OmniWM useful, consider supporting development:

Reporting Bugs

The best way to report a bug is from inside OmniWM: open the status-bar menu and choose Report a Bug…. It records an optional diagnostics trace, creates and reveals a diagnostics bundle for you to attach, and opens a pre-filled GitHub issue — OmniWM never sees your GitHub login.

Prefer the web? The GitHub issue form works too; please include your OmniWM and macOS versions there.

Contributing

Issues and pull requests are welcome on GitHub.

Start with CONTRIBUTING.md for the actual project guidelines, expectations, and preferred direction.

For deeper technical context, the docs pages that back the documentation site are here:

License

Every source file carries an SPDX license header. Forks and redistributions must retain these notices and the LICENSE file, and remain GPL-2.0 with source available.

nikitabobko/AeroSpace

AeroSpace is an i3-like tiling window manager for macOS

AeroSpace Beta

AeroSpace is an i3-like tiling window manager for macOS

Videos:

Docs:

Key features

Tiling window manager based on a tree paradigm
i3 inspired
Fast workspaces switching without animations and without the necessity to disable SIP
AeroSpace employs its own emulation of virtual workspaces instead of relying on native macOS Spaces due to their considerable limitations
Plain text configuration (dotfiles friendly). See: default-config.toml
CLI first (manpages and shell completion included)
Doesn't require disabling SIP (System Integrity Protection)
Proper multi-monitor support (i3-like paradigm)

Installation

Install via Homebrew to get autoupdates (Preferred)

brew install --cask nikitabobko/tap/aerospace

In multi-monitor setup please make sure that monitors are properly arranged.

Other installation options: https://nikitabobko.github.io/AeroSpace/guide#installation

Note

By using AeroSpace, you acknowledge that it's not notarized.

Notarization is a "security" feature by Apple. You send binaries to Apple, and they either approve them or not. In reality, notarization is about building binaries the way Apple likes it.

I don't have anything against notarization as a concept. I specifically don't like the way Apple does notarization. I don't have time to deal with Apple.

Homebrew installation script is configured to automatically delete com.apple.quarantine attribute, that's why the app should work out of the box, without any warnings that "Apple cannot check AeroSpace for malicious software"

Community, discussions, issues

AeroSpace project doesn't accept Issues directly - we ask you to create a Discussion first. Please read CONTRIBUTING.md for more details.

Community discussions happen at GitHub Discussions. There you can discuss bugs, propose new features, ask your questions, show off your setup, or just chat.

There are 7 channels:

#all. RSS. Feed with all discussions.
#announcements. RSS. Only maintainers can post here. Highly moderated traffic.
#announcements-releases. RSS. Announcements about non-patch releases. Only maintainers can post here.
#feature-ideas. RSS.
#general. RSS.
#potential-bugs. RSS. If you think that you have encountered a bug, you can discuss your bugs here.
#questions-and-answers. RSS. Everyone is welcome to ask questions. Everyone is encouraged to answer other people's questions.

Project status

Public Beta. AeroSpace can be used as a daily driver, but expect breaking changes until 1.0 is reached.

What stops us from 1.0 release:

https://github.com/nikitabobko/AeroSpace/issues/131 Performance. Implement thread-per-application to circumvent macOS blocking AX API.
https://github.com/nikitabobko/AeroSpace/issues/1215 Big refactoring. Rewrite mutable double-linked core tree data structure to immutable single-linked persistent tree. Important for: stability and potential performance
- https://github.com/nikitabobko/AeroSpace/issues/1216 The big refactoring will help us to fix stability issue that windows may randomly jump to the focused workspace
- https://github.com/nikitabobko/AeroSpace/issues/68 The big refactoring will help us to support macOS native tabs
https://github.com/nikitabobko/AeroSpace/issues/278 Implement shell-like combinators. Ignore a lot of crazy fuss in the issue, We are most probably going with the minimal approach to only introduce common shell-combinators: ||, &&, ; and eval command to send multiple commands in one go.
https://github.com/nikitabobko/AeroSpace/issues/1012 Investigate a possibility to use CGEvent.tapCreate API for global hotkeys
- https://github.com/nikitabobko/AeroSpace/issues/28 Maybe it will allow to distinguish left and right modifiers. Maybe not

Big and important issues which will go after 1.0 release:

https://github.com/nikitabobko/AeroSpace/issues/2 sticky windows
https://github.com/nikitabobko/AeroSpace/issues/260 Dynamic TWM

Development

A notes on how to setup the project, build it, how to run the tests, etc. can be found here: dev-docs/development.md

Project values

Values

AeroSpace is targeted at advanced users and developers
Keyboard centric
Breaking changes (configuration files, CLI, behavior) are avoided as much as possible, but it must not let the software stagnate. Thus breaking changes can happen, but with careful considerations and helpful message. Semver major version is bumped in case of a breaking change (It's all guaranteed once AeroSpace reaches 1.0 version, until then breaking changes just happen)
AeroSpace doesn't use GUI, unless necessarily
- AeroSpace will never provide a GUI for configuration. For advanced users, it's easier to edit a configuration file in text editor rather than navigating through checkboxes in GUI.
- Status menu icon is ok, because visual feedback is needed
Provide practical features. Fancy appearance features are not practical (e.g. window borders, transparency, animations, etc.)
"dark magic" (aka "private APIs", "code injections", etc.) must be avoided as much as possible
- Right now, AeroSpace uses only a single private API to get window ID of accessibility object _AXUIElementGetWindow. Everything else is macOS public accessibility API.
- AeroSpace will never require you to disable SIP (System Integrity Protection).
- The goal is to make AeroSpace easily maintainable, and resistant to macOS updates.

Non Values

Play nicely with existing macOS features. If limitations are imposed then AeroSpace won't play nicely with existing macOS features (For example, AeroSpace doesn't acknowledge the existence of macOS Spaces, and it uses emulation of its own workspaces)
Ricing. AeroSpace provides only a very minimal support for ricing - gaps and a few callbacks for integrations with bars. The current maintainer doesn't care about ricing. Ricing issues are not a priority, and they are mostly ignored. The ricing stance can change only with the appearance of more maintainers.

macOS compatibility table

AeroSpace binary runs on: macOS 13+
AeroSpace debug build from sources is supported on: macOS 14+
AeroSpace release build from sources is supported on: macOS 15+ (Requires Xcode 26+)

Sponsorship

AeroSpace is developed and maintained in my free time. If you find it useful, consider sponsoring.

People who have write access

In alphabetical order:

Tip of the day

defaults write -g NSWindowShouldDragOnGesture -bool true

Now, you can move windows by holding ctrl+cmd and dragging any part of the window (not necessarily the window title)

Source: reddit

Related projects

Amethyst - tiling window manager à la xmonad
InstantSpaceSwitcher - Instant space switching by synthesizing trackpad gesture with an artificially high velocity
yabai - a tiling window manager for macOS based on binary space partitioning

realm/SwiftLint

A tool to enforce Swift style and conventions.

SwiftLint

A tool to enforce Swift style and conventions, loosely based on the now archived GitHub Swift Style Guide. SwiftLint enforces the style guide rules that are generally accepted by the Swift community. These rules are well described in popular style guides like Kodeco's Swift Style Guide.

SwiftLint rules are predominantly based on SwiftSyntax. Some rules still hook into Clang and SourceKit to access type information.

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

Switch Language: 中文, 한국어

Video Introduction

To get a high-level overview of SwiftLint, we encourage you to watch this presentation recorded January 9th, 2017 by JP Simard (transcript provided):

Installation

Swift Package Manager

SwiftLint can be used as a command plugin or a build tool plugin.

Add

.package(url: "https://github.com/SimplyDanny/SwiftLintPlugins", from: "<version>")

to your Package.swift file to consume the latest release of SwiftLint automatically or pin the dependency to a specific version:

.package(url: "https://github.com/SimplyDanny/SwiftLintPlugins", exact: "<version>")

Therein, replace <version> with the desired minimum or exact version.

Note

Consuming the plugins directly from the SwiftLint repository comes with several drawbacks. To avoid them and reduce the overhead imposed, it's highly recommended to consume the plugins from the dedicated SwiftLintPlugins repository, even though plugins from the SwiftLint repository are also absolutely functional. If the plugins from SwiftLint are preferred, just use the URL https://github.com/realm/SwiftLint in the package declarations above.

However, SwiftLintPlugins facilitates plugin adoption massively. It lists some of the reasons that drive the plugins as provided by SwiftLint itself very troublesome. Since the plugin code and the releases are kept in sync, there is no difference in functionality between the two, but you spare yourself a lot of time and trouble using the dedicated plugins repository.

This document assumes you're relying on SwiftLintPlugins.

Xcode Package Dependency

Use the following link to add SwiftLint as a Package Dependency to an Xcode project:

https://github.com/SimplyDanny/SwiftLintPlugins

Homebrew

brew install swiftlint

CocoaPods

Add the following to your Podfile:

pod 'SwiftLint'

This will download the SwiftLint binaries and dependencies in Pods/ during your next pod install execution and will allow you to invoke it via ${PODS_ROOT}/SwiftLint/swiftlint in your Script Build Phases.

Installing via Cocoapods also enables pinning to a specific version of SwiftLint rather than simply the latest (which is the case with Homebrew).

Note that this will add the SwiftLint binaries, its dependencies' binaries, and the Swift binary library distribution to the Pods/ directory, so checking in this directory to SCM such as Git is discouraged.

Mint

mint install realm/SwiftLint

Bazel

Put this in your MODULE.bazel:

bazel_dep(name = "swiftlint", version = "0.52.4", repo_name = "SwiftLint")

Or put this in your WORKSPACE:

WORKSPACE

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
    name = "build_bazel_rules_apple",
    sha256 = "390841dd5f8a85fc25776684f4793d56e21b098dfd7243cd145b9831e6ef8be6",
    url = "https://github.com/bazelbuild/rules_apple/releases/download/2.4.1/rules_apple.2.4.1.tar.gz",
)

load(
    "@build_bazel_rules_apple//apple:repositories.bzl",
    "apple_rules_dependencies",
)

apple_rules_dependencies()

load(
    "@build_bazel_rules_swift//swift:repositories.bzl",
    "swift_rules_dependencies",
)

swift_rules_dependencies()

load(
    "@build_bazel_rules_swift//swift:extras.bzl",
    "swift_rules_extra_dependencies",
)

swift_rules_extra_dependencies()

http_archive(
    name = "SwiftLint",
    sha256 = "c6ea58b9c72082cdc1ada4a2d48273ecc355896ed72204cedcc586b6ccb8aca6",
    url = "https://github.com/realm/SwiftLint/releases/download/0.52.4/bazel.tar.gz",
)

load("@SwiftLint//bazel:repos.bzl", "swiftlint_repos")

swiftlint_repos()

load("@SwiftLint//bazel:deps.bzl", "swiftlint_deps")

swiftlint_deps()

Then you can run SwiftLint in the current directory with this command:

bazel run -c opt @SwiftLint//:swiftlint

Pre-Built Package

Download SwiftLint.pkg from the latest GitHub release and run it.

From Source

Make sure the build tool Bazel and a recent Swift toolchain are installed and all tools are discoverable in your PATH.

To build SwiftLint, clone this repository and run make install.

Setup

Important

While it may seem intuitive to run SwiftLint before compiling Swift source files to exit a build early when there are lint violations, it is important to understand that SwiftLint is designed to analyze valid source code that is compilable. Non-compiling code can very easily lead to unexpected and confusing results, especially when executing with --fix/--autocorrect command line arguments.

Build Tool Plugins

SwiftLint can be used as a build tool plugin for both Swift Package projects and Xcode projects.

The build tool plugin determines the SwiftLint working directory by locating the topmost config file within the package/project directory. If a config file is not found therein, the package/project directory is used as the working directory.

The plugin throws an error when it is unable to resolve the SwiftLint working directory. For example, this will occur in Xcode projects where the target's Swift files are not located within the project directory.

To maximize compatibility with the plugin, avoid project structures that require the use of the --config option.

Swift Package Projects

Note

Requires installing via Swift Package Manager.

Build tool plugins run when building each target. When a project has multiple targets, the plugin must be added to the desired targets individually.

To do this, add the plugin to the target(s) to be linted as follows:

.target(
    ...
    plugins: [.plugin(name: "SwiftLintBuildToolPlugin", package: "SwiftLintPlugins")]
),

Swift Package Command Plugin

Note

Requires installing via Swift Package Manager.

The command plugin enables running SwiftLint from the command line as follows:

swift package plugin swiftlint

Xcode Projects

Note

Requires installing via Xcode Package Dependency.

Build tool plugins run as a build phase of each target. When a project has multiple targets, the plugin must be added to the desired targets individually.

To do this, add the SwiftLintBuildToolPlugin to the Run Build Tool Plug-ins phase of the Build Phases for the target(s) to be linted.

Tip

When using the plugin for the first time, be sure to trust and enable it when prompted. If a macros build warning exists, select it to trust and enable the macros as well.

For unattended use (e.g. on CI), package plugin and macro validations can be disabled with either of the following:

Using xcodebuild options:

-skipPackagePluginValidation
-skipMacroValidation

Setting Xcode defaults:

defaults write com.apple.dt.Xcode IDESkipPackagePluginFingerprintValidatation -bool YES
defaults write com.apple.dt.Xcode IDESkipMacroFingerprintValidation -bool YES

Important

The unattended use options bypass Xcode's validation dialogs and implicitly trust all plugins and macros, which has security implications.

Unexpected Xcode Project Structures

Project structures where SwiftLint's configuration file is located outside of the package/project directory are not directly supported by the build tool plugin. This is because it isn't possible to pass arguments to build tool plugins (e.g., passing the config file path).

If your project structure doesn't work directly with the build tool plugin, please consider one of the following options:

To use a config file located outside the package/project directory, a config file may be added to that directory specifying a parent config path to the other config file, e.g., parent_config: path/to/.swiftlint.yml.
You can also consider the use of a Run Script Build Phase in place of the build tool plugin.

Xcode Run Script Build Phase

Note

Based upon the installation method used, the shell command syntax in the Run Script Build Phase may be different or additional configuration could be required. Refer to the installation instructions for more information.

If the build tool plugin does not work for your project setup or when additional custom setup is required, SwiftLint can be added as a Run Script Build Phase. This is useful when a project setup relies on the --config SwiftLint option; or to lint all targets together in a single swiftlint invocation. File inclusions and exclusions can be configured in the .swiftlint.yml configuration.

To do this, add a custom script to a Run Script phase of the Build Phases of the primary app target, after the Compile Sources phase. Use the following script implementation:

if command -v swiftlint >/dev/null 2>&1
then
    swiftlint
else
    echo "warning: `swiftlint` command not found - See https://github.com/realm/SwiftLint#installation for installation instructions."
fi

If you're using the SwiftLintPlugin in a Swift package, you may refer to the swiftlint executable in the following way:

SWIFT_PACKAGE_DIR="${SWIFT_PACKAGE_DIR:-${BUILD_DIR%Build/*}SourcePackages}"
SWIFTLINT_CMD="$SWIFT_PACKAGE_DIR/artifacts/swiftlintplugins/SwiftLintBinary/SwiftLintBinary.artifactbundle/macos/swiftlint"

if test -f "$SWIFTLINT_CMD" 2>&1
then
    "$SWIFTLINT_CMD"
else
    echo "warning: `swiftlint` command not found - See https://github.com/realm/SwiftLint#xcode-run-script-build-phase for installation instructions."
fi

Note

The SWIFTLINT_CMD path uses the default Xcode configuration and has been tested on Xcode 15/16. In case of another configuration (e.g. a custom Swift package path), please adapt the values accordingly. If you run xcodebuild with -clonedSourcePackagesDirPath, set SWIFT_PACKAGE_DIR to <that path> before running the script.

Tip

Uncheck Based on dependency analysis to run swiftlint on all incremental builds, suppressing the unspecified outputs warning.

Consideration for Xcode 15.0

Xcode 15 made a significant change by setting the default value of the ENABLE_USER_SCRIPT_SANDBOXING build setting from NO to YES. As a result, SwiftLint encounters an error related to missing file permissions, which typically manifests as error: Sandbox: swiftlint(19427) deny(1) file-read-data.

To resolve this issue, it is necessary to manually set the ENABLE_USER_SCRIPT_SANDBOXING setting to NO for the specific target that SwiftLint is being configured for.

Consideration for Apple Silicon

If you installed SwiftLint via Homebrew on Apple Silicon, you might experience this warning:

warning: SwiftLint not installed, download from https://github.com/realm/SwiftLint

That is because Homebrew on Apple Silicon installs the binaries into the /opt/homebrew/bin folder by default. To instruct Xcode where to find SwiftLint, you can either add /opt/homebrew/bin to the PATH environment variable in your build phase:

if [[ "$(uname -m)" == arm64 ]]
then
    export PATH="/opt/homebrew/bin:$PATH"
fi

if command -v swiftlint >/dev/null 2>&1
then
    swiftlint
else
    echo "warning: `swiftlint` command not found - See https://github.com/realm/SwiftLint#installation for installation instructions."
fi

or you can create a symbolic link in /usr/local/bin pointing to the actual binary:

ln -s /opt/homebrew/bin/swiftlint /usr/local/bin/swiftlint

Additional Considerations

If you wish to fix violations as well, your script could run swiftlint --fix && swiftlint instead of just swiftlint. This will mean that all correctable violations are fixed while ensuring warnings show up in your project for remaining violations.

If you've installed SwiftLint via CocoaPods the script should look like this:

"${PODS_ROOT}/SwiftLint/swiftlint"

Visual Studio Code

To integrate SwiftLint with Visual Studio Code, install the vscode-swiftlint extension from the marketplace.

Fastlane

You can use the official swiftlint fastlane action to run SwiftLint as part of your fastlane process.

swiftlint(
    mode: :lint,                            # SwiftLint mode: :lint (default) or :autocorrect
    executable: "Pods/SwiftLint/swiftlint", # The SwiftLint binary path (optional). Important if you've installed it via CocoaPods
    path: "/path/to/lint",                  # Specify path to lint (optional)
    output_file: "swiftlint.result.json",   # The path of the output file (optional)
    reporter: "json",                       # The custom reporter to use (optional)
    config_file: ".swiftlint-ci.yml",       # The path of the configuration file (optional)
    files: [                                # List of files to process (optional)
        "AppDelegate.swift",
        "path/to/project/Model.swift"
    ],
    ignore_exit_status: true,               # Allow fastlane to continue even if SwiftLint returns a non-zero exit status (Default: false)
    quiet: true,                            # Don't print status logs like 'Linting ' & 'Done linting' (Default: false)
    strict: true                            # Fail on warnings? (Default: false)
)

Docker

SwiftLint is also available as a Docker image using Ubuntu. So just the first time you need to pull the docker image using the next command:

docker pull ghcr.io/realm/swiftlint:latest

Then following times, you just run swiftlint inside of the docker like:

docker run -it -v `pwd`:`pwd` -w `pwd` ghcr.io/realm/swiftlint:latest

This will execute swiftlint in the folder where you are right now (pwd), showing an output like:

$ docker run -it -v `pwd`:`pwd` -w `pwd` ghcr.io/realm/swiftlint:latest
Linting Swift files in current working directory
Linting 'RuleDocumentation.swift' (1/490)
...
Linting 'YamlSwiftLintTests.swift' (490/490)
Done linting! Found 0 violations, 0 serious in 490 files.

Here you have more documentation about the usage of Docker Images.

MegaLinter

SwiftLint is also embedded in MegaLinter, an open-source aggregator of linters for CI. See its SwiftLint documentation for setup instructions.

Command Line Usage

$ swiftlint help
OVERVIEW: A tool to enforce Swift style and conventions.

USAGE: swiftlint <subcommand>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  analyze                 Run analysis rules
  docs                    Open SwiftLint documentation website in the default web browser
  generate-docs           Generates markdown documentation for selected group of rules
  lint (default)          Print lint warnings and errors
  baseline                Operations on existing baselines
  reporters               Display the list of reporters and their identifiers
  rules                   Display the list of rules and their identifiers
  version                 Display the current version of SwiftLint

  See 'swiftlint help <subcommand>' for detailed help.

Run swiftlint in the directory containing the Swift files to lint. Directories will be searched recursively.

To specify a list of files when using lint or analyze (like the list of files modified by Xcode specified by the ExtraBuildPhase Xcode plugin, or modified files in the working tree based on git ls-files -m), you can do so by passing the option --use-script-input-files and setting the following instance variables: SCRIPT_INPUT_FILE_COUNT and SCRIPT_INPUT_FILE_0, SCRIPT_INPUT_FILE_1, ..., SCRIPT_INPUT_FILE_{SCRIPT_INPUT_FILE_COUNT - 1}. Similarly, files can be read from file lists by passing the option --use-script-input-file-lists and setting the following instance variables: SCRIPT_INPUT_FILE_LIST_COUNT and SCRIPT_INPUT_FILE_LIST_0, SCRIPT_INPUT_FILE_LIST_1, ..., SCRIPT_INPUT_FILE_LIST_{SCRIPT_INPUT_FILE_LIST_COUNT - 1}.

These are same environment variables set for input files to custom Xcode script phases.

Working With Multiple Swift Versions

SwiftLint hooks into SourceKit so it continues working even as Swift evolves!

This also keeps SwiftLint lean, as it doesn't need to ship with a full Swift compiler, it just communicates with the official one you already have installed on your machine.

You should always run SwiftLint with the same toolchain you use to compile your code.

You may want to override SwiftLint's default Swift toolchain if you have multiple toolchains or Xcodes installed.

Here's the order in which SwiftLint determines which Swift toolchain to use:

$XCODE_DEFAULT_TOOLCHAIN_OVERRIDE
$TOOLCHAIN_DIR or $TOOLCHAINS
xcrun -find swift
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain
/Applications/Xcode-beta.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain
~/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain
~/Applications/Xcode-beta.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain

sourcekitd.framework is expected to be found in the usr/lib/ subdirectory of the value passed in the paths above.

You may also set the TOOLCHAINS environment variable to the reverse-DNS notation that identifies a Swift toolchain version:

TOOLCHAINS=com.apple.dt.toolchain.Swift_2_3 swiftlint --fix

On Linux, SourceKit is expected to be located in /usr/lib/libsourcekitdInProc.so or specified by the LINUX_SOURCEKIT_LIB_PATH environment variable.

Git `pre-commit` Hook

SwiftLint can be run as a pre-commit hook. Once installed, add this to the .pre-commit-config.yaml in the root of your repository:

repos:
  - repo: https://github.com/realm/SwiftLint
    rev: 0.57.1
    hooks:
      - id: swiftlint

Adjust rev to the SwiftLint version of your choice. pre-commit autoupdate can be used to update to the current version.

SwiftLint can be configured using entry to apply fixes and fail on errors:

- repo: https://github.com/realm/SwiftLint
  rev: 0.57.1
  hooks:
    - id: swiftlint
      entry: swiftlint --fix --strict

Rules

Over 200 rules are included in SwiftLint and the Swift community (that's you!) continues to contribute more over time. Pull requests are encouraged.

You can find an updated list of rules and more information about them in the Rule Directory.

You can also check the Source/SwiftLintBuiltInRules/Rules directory to see their implementation.

Opt-In Rules

opt_in_rules are disabled by default (i.e., you have to explicitly enable them in your configuration file).

Guidelines on when to mark a rule as opt-in:

A rule that can have many false positives (e.g. empty_count)
A rule that is too slow
A rule that is not general consensus or is only useful in some cases (e.g. force_unwrapping)

Disable rules in code

Rules can be disabled with a comment inside a source file with the following format:

// swiftlint:disable <rule1> [<rule2> <rule3>...]

The rules will be disabled until the end of the file or until the linter sees a matching enable comment:

// swiftlint:enable <rule1> [<rule2> <rule3>...]

For example:

// swiftlint:disable colon
let noWarning :String = "" // No warning about colons immediately after variable names.
// swiftlint:enable colon
let hasWarning :String = "" // Warning generated about colons immediately after variable names.

Including the all keyword will disable all rules until the linter sees a matching enable comment:

// swiftlint:disable all // swiftlint:enable all

For example:

// swiftlint:disable all
let noWarning :String = "" // No warning about colons immediately after variable names.
let i = "" // Also no warning about short identifier names.
// swiftlint:enable all
let hasWarning :String = "" // Warning generated about colons immediately after variable names.
let y = "" // Warning generated about short identifier names.

It's also possible to modify a disable or enable command by appending :previous, :this or :next for only applying the command to the previous, this (current) or next line respectively.

For example:

// swiftlint:disable:next force_cast
let noWarning = NSNumber() as! Int
let hasWarning = NSNumber() as! Int
let noWarning2 = NSNumber() as! Int // swiftlint:disable:this force_cast
let noWarning3 = NSNumber() as! Int
// swiftlint:disable:previous force_cast

Run swiftlint rules to print a list of all available rules and their identifiers.

Configuration

Configure SwiftLint by adding a .swiftlint.yml file from the directory you'll run SwiftLint from. The following parameters can be configured:

Rule inclusion:

disabled_rules: Disable rules from the default enabled set.
opt_in_rules: Enable rules that are not part of the default set. The special all identifier will enable all opt in linter rules, except the ones listed in disabled_rules.
only_rules: Only the rules specified in this list will be enabled. Cannot be specified alongside disabled_rules or opt_in_rules.
analyzer_rules: This is an entirely separate list of rules that are only run by the analyze command. All analyzer rules are opt-in, so this is the only configurable rule list, there are no equivalents for disabled_rules and only_rules. The special all identifier can also be used here to enable all analyzer rules, except the ones listed in disabled_rules.

# By default, SwiftLint uses a set of sensible default rules you can adjust. Find all the available rules
# by running `swiftlint rules` or visiting https://realm.github.io/SwiftLint/rule-directory.html.

# Rules turned on by default can be disabled.
disabled_rules:
  - colon
  - comma
  - control_statement
  
# Rules turned off by default can be enabled.
opt_in_rules:
  - empty_count

# Alternatively, specify all rules explicitly by uncommenting this option and removing the above two.
# only_rules:
#   - empty_parameters
#   - vertical_whitespace

# Rules only run by `swiftlint analyze`. These are all opt-in.
analyzer_rules:
  - explicit_self

# Case-sensitive paths to include during linting. Directory paths supplied on the
# command line will be ignored. Wildcards are supported.
included: 
  - Sources

# Case-sensitive paths to ignore during linting. Takes precedence over `included`. Wildcards
# are supported.
excluded: 
  - Carthage
  - Pods
  - Sources/ExcludedFolder
  - Sources/ExcludedFile.swift
  - Sources/*/ExcludedFile.swift

# If true, SwiftLint will not fail if no lintable files are found.
allow_zero_lintable_files: false

# If true, SwiftLint will treat all warnings as errors.
strict: false

# If true, SwiftLint will treat all errors as warnings.
lenient: false

# The path to a baseline file, which will be used to filter out detected violations.
baseline: Baseline.json

# The path to save detected violations to as a new baseline.
write_baseline: Baseline.json

# If true, SwiftLint will check for updates after linting or analyzing.
check_for_updates: true

# Configurable rules can be customized. All rules support setting their severity level.
force_cast: warning # implicitly
force_try:
  severity: warning # explicitly
  
# Rules that have both warning and error levels can set just the warning level implicitly.
line_length: 110

# To set both levels implicitly, use an array.
type_body_length:
  - 300 # warning
  - 400 # error

# To set both levels explicitly, use a dictionary.
file_length:
  warning: 500
  error: 1200
  
# Naming rules can set warnings/errors for `min_length` and `max_length`. Additionally, they can
# set excluded names and allowed symbols.
type_name:
  min_length: 4 # warning
  max_length: # warning and error
    warning: 40
    error: 50
  excluded: i(Phone|Pad|Pod) # regex pattern
  allowed_symbols: ["_"]
identifier_name:
  min_length:
    error: 4 # only error
  excluded: # excluded via string array
    - id
    - URL
    - GlobalAPIKey
    
# The default reporter (SwiftLint's output format) can be configured as `checkstyle`, `codeclimate`, `csv`,
# `emoji`, `github-actions-logging`, `gitlab`, `html`, `json`, `junit`, `markdown`, `relative-path`, `sarif`,
# `sonarqube`, `summary`, or `xcode` (default).
reporter: "xcode"

You can also use environment variables in your configuration file, by using ${SOME_VARIABLE} in a string.

Defining Custom Rules

In addition to the rules that the main SwiftLint project ships with, SwiftLint can also run two types of custom rules that you can define yourself in your own projects:

1. Swift Custom Rules

These rules are written the same way as the Swift-based rules that ship with SwiftLint so they're fast, accurate, can leverage SwiftSyntax, can be unit tested, and more.

Using these requires building SwiftLint with Bazel as described in this video or its associated code in github.com/jpsim/swiftlint-bazel-example.

2. Regex Custom Rules

You can define custom regex-based rules in your configuration file using the following syntax:

custom_rules:
  # Rule identifier.
  pirates_beat_ninjas:
    # Optional regex that defines paths to include during linting.
    included:
      - ".*\\.swift"
    # Optional regex that defines paths to exclude during linting.
    excluded:
      - ".*Test\\.swift"
    # Optional rule name.
    name: "Pirates Beat Ninjas"
    # Matching pattern.
    regex: "([nN]inja)"
    # Number of regex capture group to highlight the rule violation at. Optional, defaults to 0 (the whole match).
    capture_group: 0
    # SyntaxKinds to match. optional.
    match_kinds:
      - comment
      - identifier
    # Optional violation message.
    message: "Pirates are better than ninjas."
    # Optional violation severity.
    severity: error
  no_hiding_in_strings:
    regex: "([nN]inja)"
    # Syntax kinds to match. optional.
    match_kinds: string

This is what the output would look like:

It is important to note that the regular expression pattern is used with the flags s and m enabled, that is . matches newlines and ^/$ match the start and end of lines, respectively. If you do not want to have . match newlines, for example, the regex can be prepended by (?-s).

You can filter the matches by providing one or more match_kinds, which will reject matches that include syntax kinds that are not present in this list. Here are all the possible syntax kinds:

argument
attribute.builtin
attribute.id
buildconfig.id
buildconfig.keyword
comment
comment.mark
comment.url
doccomment
doccomment.field
identifier
keyword
number
objectliteral
parameter
placeholder
string
string_interpolation_anchor
typeidentifier

All syntax kinds used in a snippet of Swift code can be extracted asking SourceKitten. For example, sourcekitten syntax --text "struct S {}" delivers

source.lang.swift.syntaxtype.keyword for the struct keyword and
source.lang.swift.syntaxtype.identifier for its name S

which match to keyword and identifier in the above list.

If using custom rules in combination with only_rules, you must include the literal string custom_rules in the only_rules list:

only_rules:
  - custom_rules

custom_rules:
  no_hiding_in_strings:
    regex: "([nN]inja)"
    match_kinds: string

Unlike Swift custom rules, you can use official SwiftLint builds (e.g. from Homebrew) to run regex custom rules.

Auto-correct

SwiftLint can automatically correct certain violations. Files on disk are overwritten with a corrected version.

Please make sure to have backups of these files before running swiftlint --fix, otherwise important data may be lost.

Standard linting is disabled while correcting because of the high likelihood of violations (or their offsets) being incorrect after modifying a file while applying corrections.

Analyze

The swiftlint analyze command can lint Swift files using the full type-checked AST. The compiler log path containing the clean swiftc build command invocation (incremental builds will fail) must be passed to analyze via the --compiler-log-path flag. e.g. --compiler-log-path /path/to/xcodebuild.log

This can be obtained by

Cleaning DerivedData (incremental builds won't work with analyze)
Running xcodebuild -workspace {WORKSPACE}.xcworkspace -scheme {SCHEME} > xcodebuild.log
Running swiftlint analyze --compiler-log-path xcodebuild.log

Analyzer rules tend to be considerably slower than lint rules.

Using Multiple Configuration Files

SwiftLint offers a variety of ways to include multiple configuration files. Multiple configuration files get merged into one single configuration that is then applied just as a single configuration file would get applied.

There are quite a lot of use cases where using multiple configuration files could be helpful:

For instance, one could use a team-wide shared SwiftLint configuration while allowing overrides in each project via a child configuration file.

Team-Wide Configuration:

disabled_rules:
  - force_cast

Project-Specific Configuration:

opt_in_rules:
  - force_cast

Child/Parent Configs (Locally)

You can specify a child_config and/or a parent_config reference within a configuration file. These references should be local paths relative to the folder of the configuration file they are specified in. This even works recursively, as long as there are no cycles and no ambiguities.

A child config is treated as a refinement and thus has a higher priority, while a parent config is considered a base with lower priority in case of conflicts.

Here's an example, assuming you have the following file structure:

ProjectRoot
    |_ .swiftlint.yml
    |_ .swiftlint_refinement.yml
    |_ Base
        |_ .swiftlint_base.yml

To include both the refinement and the base file, your .swiftlint.yml should look like this:

child_config: .swiftlint_refinement.yml
parent_config: Base/.swiftlint_base.yml

When merging parent and child configs, included and excluded configurations are processed carefully to account for differences in the directory location of the containing configuration files.

Path merging follows these rules:

included/excluded entries from each config are resolved relative to that config file's directory.
Child entries override conflicting parent entries.
The merged path lists are computed as:

merged.included = (parent.included - child.excluded) + child.included
merged.excluded = (parent.excluded - child.included) + child.excluded

This means a child config can re-include a path excluded by its parent and can exclude a path included by its parent.

Child/Parent Configs (Remote)

Just as you can provide local child_config/parent_config references, instead of referencing local paths, you can just put urls that lead to configuration files. In order for SwiftLint to detect these remote references, they must start with http:// or https://.

The referenced remote configuration files may even recursively reference other remote configuration files, but aren't allowed to include local references.

Using a remote reference, your .swiftlint.yml could look like this:

parent_config: https://myteamserver.com/our-base-swiftlint-config.yml

Every time you run SwiftLint and have an Internet connection, SwiftLint tries to get a new version of every remote configuration that is referenced. If this request times out, a cached version is used if available. If there is no cached version available, SwiftLint fails – but no worries, a cached version should be there once SwiftLint has run successfully at least once.

If needed, the timeouts for the remote configuration fetching can be specified manually via the configuration file(s) using the remote_timeout/remote_timeout_if_cached specifiers. These values default to 2 seconds or 1 second, respectively.

Command Line

Instead of just providing one configuration file when running SwiftLint via the command line, you can also pass a hierarchy, where the first configuration is treated as a parent, while the last one is treated as the highest-priority child.

A simple example including just two configuration files looks like this:

swiftlint --config .swiftlint.yml --config .swiftlint_child.yml

Nested Configurations

In addition to a main configuration (the .swiftlint.yml file in the root folder), you can put other configuration files named .swiftlint.yml into the directory structure. For a given file, SwiftLint walks up from that file's directory towards the root configuration and uses the first nested .swiftlint.yml it finds as a child config.

That nested config applies only to files in its directory subtree. Files in other subtrees continue using the main config (or their own nearest nested config).

Because SwiftLint stops at the first match while walking up the directory tree, at most one nested configuration is merged per file (in addition to the main configuration).

.swiftlint.yml files are only considered as a nested configuration if they have not been used to build the main configuration already (e. g. by having been referenced via something like child_config: Folder/.swiftlint.yml). Also, parent_config/child_config specifications of nested configurations are getting ignored because there's no sense to that.

If one (or more) SwiftLint file(s) are explicitly specified via the --config parameter, that configuration will be treated as an override, no matter whether there exist other .swiftlint.yml files somewhere within the directory. So if you want to use nested configurations, you can't use the --config parameter.

License

MIT licensed.

About

SwiftLint is utterly maintained by volunteers contributing to its success entirely in their free time. As such, SwiftLint isn't a commercial product in any way.

Be kind to the people maintaining SwiftLint as a hobby and accept that their time is limited. Support them by contributing to the project, reporting issues, and helping others in the community.

Special thanks go to MacStadium for providing physical Mac mini machines to run our performance tests.

We also thank Realm (now MongoDB) for their initial contributions and setup of the project.

h3nock/remux

A native iOS client for remote tmux workspaces, designed to feel natural on iPhone.

Remux

A native iOS client for remote tmux workspaces.

https://github.com/user-attachments/assets/e7482322-15f8-4f7d-aca4-83368fddd07c

Join the beta on TestFlight

About

Remux is a native iOS client for remote tmux workspaces, built on Ghostty. It brings tmux's session, window, and pane model into a mobile-first interface. It previews files and running dev servers straight from the terminal, and uploads photos and files, with markup for images.

Features

tmux sessions: Attach to running sessions or start new ones.
Windows and panes: Swipe between windows, pick panes from a bottom sheet with live previews, and split, zoom, or close them.
Shortcut palette: Run saved commands with a tap. Starter sets cover shell, Claude Code, and Codex, and you can add your own commands and groups.
Voice dictation: Dictate text in the composer using on-device speech recognition.
Attachments: Upload photos and files to the server, with markup for images. The remote path is typed at the prompt.
File preview: Long-press a path in terminal output to preview it: code, images, PDFs, or HTML pages.
Localhost preview: Long-press a localhost URL to open the dev server running on the remote machine, hot reload and WebSockets included.
Cursor control: Hold the space bar or long-press in the terminal, then drag to place the cursor.
Direct SSH: Remux connects straight to the server, with no relay and no account. Passwords and private keys are stored in the iOS Keychain, and trusted host keys are remembered.
Themes: Ghostty default, Catppuccin Mocha, and Catppuccin Latte, with adjustable font size.

Installation

Remux is available as a public beta on TestFlight: testflight.apple.com/join/fHqG1ruE. You can also build from source.

Building from Source

Requirements:

Xcode with iOS 18 SDK support
XcodeGen

Fetch the prebuilt GhosttyKit framework:

scripts/fetch_ghosttykit.sh

Generate the Xcode project and build:

xcodegen generate

xcodebuild build \
  -project Remux.xcodeproj \
  -scheme Remux \
  -destination 'generic/platform=iOS Simulator'

Run the tests:

xcodebuild test \
  -project Remux.xcodeproj \
  -scheme Remux \
  -destination 'platform=iOS Simulator,name=iPhone 17,OS=latest'

To build GhosttyKit yourself instead of fetching it, see remux-ghostty and scripts/build_release_ghosttykit.sh.

Acknowledgments

Remux is built on Ghostty's terminal core and uses Citadel for SSH.

Alamofire/Alamofire

Elegant HTTP Networking in Swift

Alamofire is an HTTP networking library written in Swift.

Features
Component Libraries
Requirements
Migration Guides
Communication
Installation
Contributing
Usage
- Introduction - Making Requests, Response Handling, Response Validation, Response Caching
- HTTP - HTTP Methods, Parameters and Parameter Encoder, HTTP Headers, Authentication
- Large Data - Downloading Data to a File, Uploading Data to a Server
- Tools - Statistical Metrics, cURL Command Output
Advanced Usage
- URL Session - Session Manager, Session Delegate, Request
- Routing - Routing Requests, Adapting and Retrying Requests
- Model Objects - Custom Response Handlers
- Advanced Concurrency - Swift Concurrency and Combine
- Connection - Security, Network Reachability
Open Radars
FAQ
Credits
Donations
License

Features

Write Requests Fast!

Alamofire's compact syntax and extensive feature set allow requests with powerful features like automatic retry to be written in just a few lines of code.

// Automatic String to URL conversion, Swift concurrency support, and automatic retry.
let response = await AF.request("https://httpbin.org/get", interceptor: .retryPolicy)
                       // Automatic HTTP Basic Auth.
                       .authenticate(username: "user", password: "pass")
                       // Caching customization.
                       .cacheResponse(using: .cache)
                       // Redirect customization.
                       .redirect(using: .follow)
                       // Validate response code and Content-Type.
                       .validate()
                       // Produce a cURL command for the request.
                       .cURLDescription { description in
                         print(description)
                       }
                       // Automatic Decodable support with background parsing.
                       .serializingDecodable(DecodableType.self)
                       // Await the full response with metrics and a parsed body.
                       .response
// Detailed response description for easy debugging.
debugPrint(response)

Component Libraries

In order to keep Alamofire focused specifically on core networking implementations, additional component libraries have been created by the Alamofire Software Foundation to bring additional functionality to the Alamofire ecosystem.

AlamofireImage - An image library including image response serializers, UIImage and UIImageView extensions, custom image filters, an auto-purging in-memory cache, and a priority-based image downloading system.
AlamofireNetworkActivityIndicator - Controls the visibility of the network activity indicator on iOS using Alamofire. It contains configurable delay timers to help mitigate flicker and can support URLSession instances not managed by Alamofire.

Requirements

Platform	Minimum Swift Version	Installation	Status
iOS 10.0+ / macOS 10.12+ / tvOS 10.0+ / watchOS 3.0+	6.0 / Xcode 16.0	CocoaPods, Carthage, Swift Package Manager, Manual	Fully Tested
Linux	Latest Only	Swift Package Manager	Building But Unsupported
Windows	Latest Only	Swift Package Manager	Building But Unsupported
Android	Latest Only	Swift Package Manager	Building But Unsupported

Known Issues on Linux and Windows

Alamofire builds on Linux, Windows, and Android but there are missing features and many issues in the underlying swift-corelibs-foundation that prevent full functionality and may cause crashes. These include:

ServerTrustManager and associated certificate functionality is unavailable, so there is no certificate pinning and no client certificate support.
Various methods of HTTP authentication may crash, including HTTP Basic and HTTP Digest. Crashes may occur if responses contain server challenges.
Cache control through CachedResponseHandler and associated APIs is unavailable, as the underlying delegate methods aren't called.
URLSessionTaskMetrics are never gathered.
WebSocketRequest is not available.

Due to these issues, Alamofire is unsupported on Linux, Windows, and Android. Please report any crashes to the Swift bug reporter.

Migration Guides

Communication

If you need help with making network requests using Alamofire, use Stack Overflow and tag alamofire.
If you need to find or understand an API, check our documentation or Apple's documentation for URLSession, on top of which Alamofire is built.
If you need help with an Alamofire feature, use our forum on swift.org.
If you'd like to discuss Alamofire best practices, use our forum on swift.org.
If you'd like to discuss a feature request, use our forum on swift.org.
If you found a bug, open an issue here on GitHub and follow the guide. The more detail the better!

Installation

Swift Package Manager

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler.

Once you have your Swift package set up, adding Alamofire as a dependency is as easy as adding it to the dependencies value of your Package.swift or the Package list in Xcode.

dependencies: [
    .package(url: "https://github.com/Alamofire/Alamofire.git", .upToNextMajor(from: "5.11.0"))
]

Normally you'll want to depend on the Alamofire target:

.product(name: "Alamofire", package: "Alamofire")

But if you want to force Alamofire to be dynamically linked (do not do this unless you're sure you need it), you can depend on the AlamofireDynamic target:

.product(name: "AlamofireDynamic", package: "Alamofire")

CocoaPods

CocoaPods is a dependency manager for Cocoa projects. For usage and installation instructions, visit their website. To integrate Alamofire into your Xcode project using CocoaPods, specify it in your Podfile:

pod 'Alamofire'

Carthage

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. To integrate Alamofire into your Xcode project using Carthage, specify it in your Cartfile:

github "Alamofire/Alamofire"

Manually

If you prefer not to use any of the aforementioned dependency managers, you can integrate Alamofire into your project manually.

Embedded Framework

Open up Terminal, cd into your top-level project directory, and run the following command "if" your project is not initialized as a git repository:
```
$ git init
```

Add Alamofire as a git submodule by running the following command:

$ git submodule add https://github.com/Alamofire/Alamofire.git

Open the new Alamofire folder, and drag the Alamofire.xcodeproj into the Project Navigator of your application's Xcode project.

It should appear nested underneath your application's blue project icon. Whether it is above or below all the other Xcode groups does not matter.
Select the Alamofire.xcodeproj in the Project Navigator and verify the deployment target matches that of your application target.
Next, select your application project in the Project Navigator (blue project icon) to navigate to the target configuration window and select the application target under the "Targets" heading in the sidebar.
In the tab bar at the top of that window, open the "General" panel.
Click on the + button under the "Embedded Binaries" section.
You will see two different Alamofire.xcodeproj folders each with two different versions of the Alamofire.framework nested inside a Products folder.

It does not matter which Products folder you choose from, but it does matter whether you choose the top or bottom Alamofire.framework.
Select the top Alamofire.framework for iOS and the bottom one for macOS.

You can verify which one you selected by inspecting the build log for your project. The build target for Alamofire will be listed as Alamofire iOS, Alamofire macOS, Alamofire tvOS, or Alamofire watchOS.
And that's it!

The Alamofire.framework is automagically added as a target dependency, linked framework and embedded framework in a copy files build phase which is all you need to build on the simulator and a device.

Contributing

Before contributing to Alamofire, please read the instructions detailed in our contribution guide.

Open Radars

The following radars have some effect on the current implementation of Alamofire.

rdar://21349340 - Compiler throwing warning due to toll-free bridging issue in the test case
rdar://26870455 - Background URL Session Configurations do not work in the simulator
rdar://26849668 - Some URLProtocol APIs do not properly handle URLRequest

Resolved Radars

The following radars have been resolved over time after being filed against the Alamofire project.

rdar://26761490 - Swift string interpolation causing memory leak with common usage.
- (Resolved): 9/1/17 in Xcode 9 beta 6.
rdar://36082113 - URLSessionTaskMetrics failing to link on watchOS 3.0+
- (Resolved): Just add CFNetwork to your linked frameworks.
FB7624529 - urlSession(_:task:didFinishCollecting:) never called on watchOS
- (Resolved): Metrics now collected on watchOS 7+.

FAQ

What's the origin of the name Alamofire?

Alamofire is named after the Alamo Fire flower, a hybrid variant of the Bluebonnet, the official state flower of Texas.

Credits

Alamofire is owned and maintained by the Alamofire Software Foundation. You can follow them on Twitter at @AlamofireSF for project updates and releases.

Security Disclosure

If you believe you have identified a security vulnerability with Alamofire, you should report it as soon as possible via email to security@alamofire.org. Please do not post it to a public issue tracker.

Sponsorship

The ASF is looking to raise money to officially stay registered as a federal non-profit organization. Registering will allow Foundation members to gain some legal protections and also allow us to put donations to use, tax-free. Sponsoring the ASF will enable us to:

Pay our yearly legal fees to keep the non-profit in good status
Pay for our mail servers to help us stay on top of all questions and security issues
Potentially fund test servers to make it easier for us to test the edge cases
Potentially fund developers to work on one of our projects full-time

The community adoption of the ASF libraries has been amazing. We are greatly humbled by your enthusiasm around the projects and want to continue to do everything we can to move the needle forward. With your continued support, the ASF will be able to improve its reach and also provide better legal safety for the core members. If you use any of our libraries for work, see if your employers would be interested in donating. Any amount you can donate, whether once or monthly, to help us reach our goal would be greatly appreciated.

Sponsor Alamofire

Supporters

MacStadium provides Alamofire with a free, hosted Mac mini.

License

Alamofire is released under the MIT license. See LICENSE for details.

Ranchero-Software/NetNewsWire

RSS reader for macOS and iOS.

NetNewsWire

NetNewsWire is a free and open-source feed reader for macOS and iOS.

It supports RSS, Atom, JSON Feed, and RSS-in-JSON formats.

More info: https://netnewswire.com/

You can report bugs and make feature requests here on GitHub. You can also read change notes for current and previous releases.

Here’s How to Support NetNewsWire. Spoiler: don’t send money. 😃

(NetNewsWire’s Help menu has these links, so you don’t have to remember to come back to this page.)

Community

Join the forum to talk with other NetNewsWire users — and to help out, if you’d like to, by testing, coding, writing, providing feedback, or just helping us think things through. Everybody is welcome and encouraged to join.

Every community member is expected to abide by the code of conduct which is included in the Contributing page.

Pull Requests

See the Contributing page for our process. They key thing is to ask before doing a PR (before even starting work). The Contributing page goes into more detail as to why it’s important to ask first.

Building

You can build and test NetNewsWire without a paid developer account.

git clone https://github.com/Ranchero-Software/NetNewsWire.git

You can locally override the Xcode settings for code signing by creating a DeveloperSettings.xcconfig file locally at the appropriate path. This allows for a pristine project with code signing set up with the appropriate developer ID and certificates, and for developer to be able to have local settings without needing to check in anything into source control.

You can do this in one of two ways: using the included setup.sh script or by creating the folder structure and file manually.

Using `setup.sh`

Open Terminal and cd into the NetNewsWire directory.
Run this command to ensure you have execution rights for the script: chmod +x setup.sh
Execute the script with the following command: ./setup.sh and complete the answers.

Manually

Make a directory SharedXcodeSettings next to where you have this repository.

The directory structure is:

directory/
  SharedXcodeSettings/
    DeveloperSettings.xcconfig
  NetNewsWire/
    NetNewsWire.xcodeproj

Example:

If your NetNewsWire Xcode project file is at: /Users/name/projects/NetNewsWire/NetNewsWire.xcodeproj

Create your DeveloperSettings.xcconfig file at /Users/name/projects/SharedXcodeSettings/DeveloperSettings.xcconfig

Then create a plain text file in it: SharedXcodeSettings/DeveloperSettings.xcconfig and give it the contents:

CODE_SIGN_IDENTITY = Mac Developer
DEVELOPMENT_TEAM = <Your Team ID>
CODE_SIGN_STYLE = Automatic
ORGANIZATION_IDENTIFIER = <Your Domain Name Reversed>
DEVELOPER_ENTITLEMENTS = -dev
PROVISIONING_PROFILE_SPECIFIER =

Set DEVELOPMENT_TEAM to your Apple supplied development team. You can use Keychain Access to find your development team ID. Set ORGANIZATION_IDENTIFIER to a reversed domain name that you control or have made up. Note that PROVISIONING_PROFILE_SPECIFIER should not have a value associated with it.

You can now open the NetNewsWire.xcodeproj in Xcode.

Now you should be able to build without code signing errors and without modifying the NetNewsWire Xcode project. This is a special build of NetNewsWire with some functionality disabled. This is because we have API keys that can't be stored in the repository or shared between developers. Certain account types, like iCloud and Feedly, aren't enabled and the Reader View isn't enabled because of this.

If you have any problems, we will help you out in the forum (see above).

LiveContainer/LiveContainer

Run iOS apps without actually installing them!

LiveContainer

An app launcher that runs iOS apps without actually installing them!

Crowdin Project: | Documentation:liveconainer.github.io

LiveContainer

LiveContainer is an app launcher (not emulator or hypervisor) that allows you to run iOS apps inside it.
Allows you to install unlimited apps (3 app/10 app id free developer account limit does not apply here) with only one app & app id. You can also have multiple versions of an app installed with multiple data containers.
(Below iOS 26) When JIT is available, codesign is entirely bypassed, no need to sign your apps before installing. Otherwise, your app will be signed with the same certificate used by LiveContainer.

Caution

Important Notice Regarding Third-Party Builds of LiveContainer

We have recently noticed the appearance of certain closed-source third-party builds of LiveContainer. Please be aware that all your apps are installed within LiveContainer, which means these third-party builds have full access to your data, including sensitive information such as keychain items and login credentials.

Furthermore, please note that we do not provide any support for issues of these third-party builds.

Installation

LiveContainer comes with a standalone version and a version with built-in SideStore. Please read the install guide here

If you encounter any issue please read our FAQ here

Standalone

Stable
Nightly

LiveContainer+SideStore

Stable	Nightly

Requirements

iOS/iPadOS 15+
- Multitasking requires iOS/iPadOS 16.0+
AltStore 2.0+ / SideStore 0.6.0+

Features & Guides

Installing Apps

Open LiveContainer, tap the plus icon in the upper right hand corner and select IPA files to install.
Choose the app you want to open in the next launch.
You can long-press the app to manage it.

Add Apps to Home Screen

Multiple LiveContainers

Using multiple LiveContainers allows you to run multiples different apps simultaneously, with almost seamless data transfer between the LiveContainers.

Multitasking

You can now launch multiple apps simultaneously in in-app virtual windows. These windows can be resized, scaled, and even displayed using the native Picture-in-Picture (PiP) feature. On iPads, apps can run in native window mode, displaying each app in a separate system window. And if you wish, you can choose to run apps in multitasking mode by default in settings.

To use multitasking, hold its banner and tap "Multitask". You can also make Multitask the default launch mode in settings.

Note

To use multitasking, ensure you select "Keep App Extensions" when installing via SideStore/AltStore.
If you want to enable JIT for multitasked apps, you’ll need a JIT enabler that supports attaching by PID. (StikDebug)

JIT Support

Installing external tweaks

Multiple Containers/External Containers

Hiding Apps

Fix File Picker & Local Notification

Some apps may experience issues with their file pickers or not be able to apply for notification permission in LiveContainer. To resolve this, enable "Fix File Picker" & "Fix Local Notifications" accordingly in the app-specific settings.

"Open In App" Support

You can simply share a URL or a file to app simply by using iOS's native share sheet. In share sheet, select LiveContainer, and LiveContainer will ask you which app you'd like to open that URL/file in.
What's more, you also can tap the link icon in the top-right corner of the "Apps" tab and input the URL. LiveContainer will detect the appropriate app and ask if you want to launch it.

Compatibility

Unfortunately, not all apps work in LiveContainer, so we have a compatibility list to tell if there is apps that have issues. If they aren't on this list, then it's likely going run. However, if it doesn't work, please make an issue about it.

Building

Open Xcode, edit DEVELOPMENT_TEAM[config=Debug] in xcconfigs/Global.xcconfig to your team id and compile.

Project structure

Main executable

Core of LiveContainer
Contains the logic of setting up guest environment and loading guest app.
If no app is selected, it loads LiveContainerSwiftUI.

LiveContainerSwiftUI

SwiftUI rewrite of LiveContainerUI (by @hugeBlack)
Language file Localizable.xcstrings is in here for multilingual support. To help us translate LiveContainer, please visit our crowdin project

MultitaskSupport

Contains the implementation of multitasking feature.
Based on FrontBoardAppLauncher

SideStore

Supporting code for SideStore's app refreshing integration

TweakLoader

A simple tweak injector, which loads CydiaSubstrate and loads tweaks.
Injected to every app you install in LiveContainer.

ZSign

The app signer shipped with LiveContainer.
Originally made by zhlynn.
LiveContainer uses Feather's version of ZSign modified by khcrysalis.
Changes are made to meet LiveContainer's needs.

How does it work?

Patching guest executable

Patch __PAGEZERO segment:
- Change vmaddr to 0xFFFFC000 (0x100000000 - 0x4000)
- Change vmsize to 0x4000
Change MH_EXECUTE to MH_DYLIB.
Inject a load command to load TweakLoader.dylib

Patching `@executable_path`

Hook dyld4::APIs::_NSGetExecutablePath
Call _NSGetExecutablePath
Replace config.process.mainExecutablePath
- Calculate address of config.process.mainExecutablePath using dyld4::APIs instance (passed as first parameter)
- Use builtin_vm_protect or TPRO unlock to make it writable
- Replace the address with one we have control of
Put the original dyld4::APIs::_NSGetExecutablePath back

Old Method

Call _NSGetExecutablePath with an invalid buffer pointer input -> SIGSEGV

Do some magic stuff to overwrite the contents of executable_path.

Patching `NSBundle.mainBundle`

This property is overwritten with the guest app's bundle.

Bypassing Library Validation

JIT is optional to bypass codesigning. In JIT-less mode, all executables are signed so this does not apply.
Derived from Restoring Dyld Memory Loading

dlopening the executable

Call dlopen with the guest app's executable
TweakLoader loads all tweaks in the selected folder
Find the entry point
Jump to the entry point
The guest app's entry point calls UIApplicationMain and start up like any other iOS apps.

Multi-Account support & Keychain Semi-Separation

128 keychain access groups are created and LiveContainer allocates them randomly to each container of the same app. So you can create 128 container with different keychain access groups.

Limitations

Entitlements from the guest app are not applied to the host app. This isn't a big deal since sideloaded apps requires only basic entitlements.
App Permissions are globally applied.
Guest app containers are not sandboxed. This means one guest app can access other guest apps' data.
App extensions aren't supported. they cannot be registered because: LiveContainer is sandboxed, SpringBoard doesn't know what apps are installed in LiveContainer, and they take up App ID.
Multitasking can be achieved by using multiple LiveContainer and the multitasking feature. However, while we were able to fix physical keyboard input issue on iPadOS (https://github.com/LiveContainer/LiveContainer/issues/524), iPhone Mirroring uses different checks which still broke it (https://github.com/LiveContainer/LiveContainer/issues/793).
Remote push notification will not work
Querying custom URL schemes might not work(?)

TODO

Use ChOma instead of custom MachO parser

License

GNU Affero General Public License v3.0

Credits

xpn's blogpost: Restoring Dyld Memory Loading
LinusHenze's CFastFind: MIT license
litehook: MIT license
@haxi0 & @m1337v for icon
@Vishram1123 for the initial shortcut implementation.
@hugeBlack for SwiftUI contribution
@Staubgeborener for automatic AltStore/SideStore source updater
@fkunn1326 for improved app hiding
@slds1 for dynamic color feature
@Vishram1123 for iOS 26+ JIT Script Support
@StephenDev0 for AltStore source support

linearmouse/linearmouse

The mouse and trackpad utility for Mac.

LinearMouse

The mouse and trackpad utility for Mac.

Get started

Please visit https://linearmouse.app.

Contribute

Please read the contributing guide before making a pull request.

Help translate

Please sign up for Crowdin and join our Crowdin project to translate LinearMouse into supported languages. It is recommended to sign in Crowdin using GitHub, so that I can add you as a co-author when I merge the pull request.

If you want to add a new language, please create a new issue and I will be happy to enable that language for you to translate.

I'm not a native English speaker, so if you find any English localization issues, feel free to correct me by creating a pull request.

Credits

Mac Mouse Fix - The way to modify the pointer speed (sensitivity) is inspired by Mac Mouse Fix.

swiftlang/swift

The Swift Programming Language

Swift Programming Language

Welcome to Swift

Swift is a high-performance system programming language. It has a clean and modern syntax, offers seamless access to existing C and Objective-C code and frameworks, and is memory-safe by default.

Although inspired by Objective-C and many other languages, Swift is not itself a C-derived language. As a complete and independent language, Swift packages core features like flow control, data structures, and functions, with high-level constructs like objects, protocols, closures, and generics. Swift embraces modules, eliminating the need for headers and the code duplication they entail.

To learn more about using the language, visit swift.org. To learn more about the compiler's internal design, see the documentation index.

Contributing to Swift

Contributions to Swift are welcomed and encouraged! Please see the Contributing to Swift guide.

Before submitting the pull request, please make sure you have tested your changes and that they follow the Swift project guidelines for contributing code.

To be a truly great community, Swift.org needs to welcome developers from all walks of life, with different backgrounds, and with a wide range of experience. A diverse and friendly community will have more great ideas, more unique perspectives, and produce more great code. We will work diligently to make the Swift community welcoming to everyone.

To give clarity of what is expected of our members, Swift has adopted the code of conduct defined by the Contributor Covenant. This document is used across many open source communities, and we think it articulates our values well. For more, see the Code of Conduct.

Getting Started

If you are interested in:

Contributing fixes and features to the compiler: See our How to Submit Your First Pull Request guide.
Building the compiler as a one-off: See our Getting Started guide.
Building a toolchain as a one-off: Follow the Getting Started guide up until the "Building the project" section. After that, follow the instructions in the Swift Toolchains section below.

We also have an FAQ that answers common questions.

Swift Toolchains

Building

Swift toolchains are created using the script build-toolchain. This script is used by swift.org's CI to produce snapshots and can allow for one to locally reproduce such builds for development or distribution purposes. A typical invocation looks like the following:

  $ ./swift/utils/build-toolchain $BUNDLE_PREFIX

where $BUNDLE_PREFIX is a string that will be prepended to the build date to give the bundle identifier of the toolchain's Info.plist. For instance, if $BUNDLE_PREFIX was com.example, the toolchain produced will have the bundle identifier com.example.YYYYMMDD. It will be created in the directory you run the script with a filename of the form: swift-LOCAL-YYYY-MM-DD-a-osx.tar.gz.

Beyond building the toolchain, build-toolchain also supports the following (non-exhaustive) set of useful options:

--dry-run: Perform a dry run build. This is off by default.
--test: Test the toolchain after it has been compiled. This is off by default.
--distcc: Use distcc to speed up the build by distributing the C++ part of the swift build. This is off by default.
--sccache: Use sccache to speed up subsequent builds of the compiler by caching more C++ build artifacts. This is off by default.

More options may be added over time. Please pass --help to build-toolchain to see the full set of options.

Installing into Xcode

On macOS if one wants to install such a toolchain into Xcode:

Untar and copy the toolchain to one of /Library/Developer/Toolchains/ or ~/Library/Developer/Toolchains/. E.g.:

  $ sudo tar -xzf swift-LOCAL-YYYY-MM-DD-a-osx.tar.gz -C /
  $ tar -xzf swift-LOCAL-YYYY-MM-DD-a-osx.tar.gz -C ~/

The script also generates an archive containing debug symbols which can be installed over the main archive allowing symbolication of any compiler crashes.

  $ sudo tar -xzf swift-LOCAL-YYYY-MM-DD-a-osx-symbols.tar.gz -C /
  $ tar -xzf swift-LOCAL-YYYY-MM-DD-a-osx-symbols.tar.gz -C ~/

Specify the local toolchain for Xcode's use via Xcode->Toolchains.

Build Failures

Try the suggestions in Troubleshooting build issues.

Make sure you are using the correct release of Xcode.

If you have changed Xcode versions but still encounter errors that appear to be related to the Xcode version, try passing --clean to build-script.

When a new version of Xcode is released, you can update your build without recompiling the entire project by passing --reconfigure to build-script.

groue/GRDB.swift

A toolkit for SQLite databases, with a focus on application development

A toolkit for SQLite databases, with a focus on application development
Proudly serving the community since 2015

Latest release: June 18, 2026 • version 7.11.1 • CHANGELOG • Migrating From GRDB 6 to GRDB 7

Requirements: iOS 13.0+ / macOS 10.15+ / tvOS 13.0+ / watchOS 7.0+ • SQLite 3.20.0+ • Swift 6.1+ / Xcode 16.3+

Contact:

Release announcements and usage tips: follow @groue@hachyderm.io on Mastodon.
Report bugs in a Github issue. Make sure you check the existing issues first.
A question? Looking for advice? Do you wonder how to contribute? Fancy a chat? Go to the GitHub discussions, or the GRDB forums.

What is GRDB?

Use this library to save your application’s permanent data into SQLite databases. It comes with built-in tools that address common needs:

SQL Generation

Enhance your application models with persistence and fetching methods, so that you don't have to deal with SQL and raw database rows when you don't want to.
Database Observation

Get notifications when database values are modified.
Robust Concurrency

Multi-threaded applications can efficiently use their databases, including WAL databases that support concurrent reads and writes.
Migrations

Evolve the schema of your database as you ship new versions of your application.
Leverage your SQLite skills

Not all developers need advanced SQLite features. But when you do, GRDB is as sharp as you want it to be. Come with your SQL and SQLite skills, or learn new ones as you go!

Usage • Documentation • Installation • FAQ

Usage

Start using the database in four steps

import GRDB

// 1. Open a database connection
let dbQueue = try DatabaseQueue(path: "/path/to/database.sqlite")

// 2. Define the database schema
try dbQueue.write { db in
    try db.create(table: "player") { t in
        t.primaryKey("id", .text)
        t.column("name", .text).notNull()
        t.column("score", .integer).notNull()
    }
}

// 3. Define a record type
struct Player: Codable, Identifiable, FetchableRecord, PersistableRecord {
    var id: String
    var name: String
    var score: Int
    
    enum Columns {
        static let name = Column(CodingKeys.name)
        static let score = Column(CodingKeys.score)
    }
}

// 4. Write and read in the database
try dbQueue.write { db in
    try Player(id: "1", name: "Arthur", score: 100).insert(db)
    try Player(id: "2", name: "Barbara", score: 1000).insert(db)
}

try dbQueue.read { db in
    let player = try Player.find(db, id: "1")
    
    let bestPlayers = try Player
        .order(\.score.desc)
        .limit(10)
        .fetchAll(db)
}

Access to raw SQL

try dbQueue.write { db in
    try db.execute(sql: """
        CREATE TABLE player (
          id TEXT PRIMARY KEY,
          name TEXT NOT NULL,
          score INT NOT NULL)
        """)
    
    try db.execute(sql: """
        INSERT INTO player (id, name, score)
        VALUES (?, ?, ?)
        """, arguments: ["1", "Arthur", 100])
    
    // Avoid SQL injection with SQL interpolation
    let id = "2"
    let name = "O'Brien"
    let score = 1000
    try db.execute(literal: """
        INSERT INTO player (id, name, score)
        VALUES (\(id), \(name), \(score))
        """)
}

See Executing Updates

Access to raw database rows and values

try dbQueue.read { db in
    // Fetch database rows
    let rows = try Row.fetchCursor(db, sql: "SELECT * FROM player")
    while let row = try rows.next() {
        let id: String = row["id"]
        let name: String = row["name"]
        let score: Int = row["score"]
    }
    
    // Fetch values
    let playerCount = try Int.fetchOne(db, sql: "SELECT COUNT(*) FROM player")! // Int
    let playerNames = try String.fetchAll(db, sql: "SELECT name FROM player") // [String]
}

let playerCount = try dbQueue.read { db in
    try Int.fetchOne(db, sql: "SELECT COUNT(*) FROM player")!
}

See Fetch Queries

Database model types aka "records"

struct Player: Codable, Identifiable, FetchableRecord, PersistableRecord {
    var id: String
    var name: String
    var score: Int
    
    enum Columns {
        static let name = Column(CodingKeys.name)
        static let score = Column(CodingKeys.score)
    }
}

try dbQueue.write { db in
    // Create database table
    try db.create(table: "player") { t in
        t.primaryKey("id", .text)
        t.column("name", .text).notNull()
        t.column("score", .integer).notNull()
    }
    
    // Insert a record
    var player = Player(id: "1", name: "Arthur", score: 100)
    try player.insert(db)
    
    // Update a record
    player.score += 10
    try player.update(db)
    
    try player.updateChanges { $0.score += 10 }
    
    // Delete a record
    try player.delete(db)
}

See Records

Query the database with the Swift query interface

try dbQueue.read { db in
    // Player
    let player = try Player.find(db, id: "1")
    
    // Player?
    let arthur = try Player.filter { $0.name == "Arthur" }.fetchOne(db)
    
    // [Player]
    let bestPlayers = try Player.order(\.score.desc).limit(10).fetchAll(db)
    
    // Int
    let playerCount = try Player.fetchCount(db)
    
    // SQL is always welcome
    let players = try Player.fetchAll(db, sql: "SELECT * FROM player")
}

See the Query Interface

Database changes notifications

// Define the observed value
let observation = ValueObservation.tracking { db in
    try Player.fetchAll(db)
}

// Start observation
let cancellable = observation.start(
    in: dbQueue,
    onError: { error in ... },
    onChange: { (players: [Player]) in print("Fresh players: \(players)") })

Ready-made support for Combine and RxSwift:

// Swift concurrency
for try await players in observation.values(in: dbQueue) {
    print("Fresh players: \(players)")
}

// Combine
let cancellable = observation.publisher(in: dbQueue).sink(
    receiveCompletion: { completion in ... },
    receiveValue: { (players: [Player]) in print("Fresh players: \(players)") })

// RxSwift
let disposable = observation.rx.observe(in: dbQueue).subscribe(
    onNext: { (players: [Player]) in print("Fresh players: \(players)") },
    onError: { error in ... })

See Database Observation, Combine Support, RxGRDB.

Documentation

GRDB runs on top of SQLite: you should get familiar with the SQLite FAQ. For general and detailed information, jump to the SQLite Documentation.

Demo Applications & Frequently Asked Questions

Records and the Query Interface

Records: Fetching and persistence methods for your custom structs and class hierarchies
Query Interface: A swift way to generate SQL • create tables, indexes, etc • requests • associations between record types

Application Tools

Migrations: Transform your database as your application evolves.
Full-Text Search: Perform efficient and customizable full-text searches.
Database Observation: Observe database changes and transactions.
Encryption: Encrypt your database with SQLCipher.
Backup: Dump the content of a database to another.
Interrupt a Database: Abort any pending database operation.
Sharing a Database: How to share an SQLite database between multiple processes - recommendations for App Group containers, App Extensions, App Sandbox, and file coordination.

Good to Know

Concurrency: How to access databases in a multi-threaded application.
Combine: Access and observe the database with Combine publishers.
Avoiding SQL Injection
Error Handling
Unicode
Memory Management
Data Protection
💡 Migrating From GRDB 6 to GRDB 7
💡 Why Adopt GRDB?
💡 Recommended Practices for Designing Record Types

Companion Libraries

GRDBQuery: Access and observe the database from your SwiftUI views.
GRDBSnapshotTesting: Test your database.

FAQ

Sample Code

Installation

The installation procedures below have GRDB use the version of SQLite that ships with the target operating system.

See Encryption for the installation procedure of GRDB with SQLCipher.

See Custom SQLite builds for the installation procedure of GRDB with a customized build of SQLite.

Swift Package Manager

The Swift Package Manager automates the distribution of Swift code. To use GRDB with SPM, add a dependency to https://github.com/groue/GRDB.swift.git

GRDB offers two libraries, GRDB and GRDB-dynamic. Pick only one. When in doubt, prefer GRDB. The GRDB-dynamic library can reveal useful if you are going to link it with multiple targets within your app and only wish to link to a shared, dynamic framework once. See How to link a Swift Package as dynamic for more information.

Note: Linux support is provided by contributors. It is not automatically tested, and not officially maintained. If you notice a build or runtime failure on Linux, please open a pull request with the necessary fix, thank you!

CocoaPods

CocoaPods is a dependency manager for Xcode projects. To use GRDB with CocoaPods (version 1.2 or higher), specify in your Podfile:

pod 'GRDB.swift'

GRDB can be installed as a framework, or a static library.

Important Note for CocoaPods installation

Due to an issue in CocoaPods, it is currently not possible to deploy new versions of GRDB to CocoaPods. The last version available on CocoaPods is 6.24.1. To install later versions of GRDB using CocoaPods, use one of the following workarounds:

Depend on the GRDB7 branch. This is more or less equivalent to what pod 'GRDB.swift', '~> 7.0' would normally do, if CocoaPods would accept new GRDB versions to be published:

# Can't use semantic versioning due to https://github.com/CocoaPods/CocoaPods/issues/11839
pod 'GRDB.swift', git: 'https://github.com/groue/GRDB.swift.git', branch: 'GRDB7'

Depend on a specific version explicitly (Replace the tag with the version you want to use):

# Can't use semantic versioning due to https://github.com/CocoaPods/CocoaPods/issues/11839
# Replace the tag with the tag that you want to use.
pod 'GRDB.swift', git: 'https://github.com/groue/GRDB.swift.git', tag: 'v6.29.0'

Carthage

Carthage is unsupported. For some context about this decision, see #433.

Manually

Download a copy of GRDB, or clone its repository and make sure you checkout the latest tagged version.
Embed the GRDB.xcodeproj project in your own project.
Add the GRDB target in the Target Dependencies section of the Build Phases tab of your application target (extension target for WatchOS).
Add the GRDB.framework to the Embedded Binaries section of the General tab of your application target (extension target for WatchOS).

Database Connections

GRDB provides two classes for accessing SQLite databases: DatabaseQueue and DatabasePool:

import GRDB

// Pick one:
let dbQueue = try DatabaseQueue(path: "/path/to/database.sqlite")
let dbPool = try DatabasePool(path: "/path/to/database.sqlite")

The differences are:

Database pools allow concurrent database accesses (this can improve the performance of multithreaded applications).
Database pools open your SQLite database in the WAL mode (unless read-only).
Database queues support in-memory databases.

If you are not sure, choose DatabaseQueue. You will always be able to switch to DatabasePool later.

For more information and tips when opening connections, see Database Connections.

SQLite API

In this section of the documentation, we will talk SQL. Jump to the query interface if SQL is not your cup of tea.

Executing Updates
Fetch Queries
Values
- Data
- Date and DateComponents
- NSNumber, NSDecimalNumber, and Decimal
- Swift enums
- DatabaseValueConvertible: the protocol for custom value types
Transactions and Savepoints
SQL Interpolation

Advanced topics:

Executing Updates

Once granted with a database connection, the execute(sql:arguments:) method executes the SQL statements that do not return any database row, such as CREATE TABLE, INSERT, DELETE, ALTER, etc.

For example:

try dbQueue.write { db in
    try db.execute(sql: """
        CREATE TABLE player (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            name TEXT NOT NULL,
            score INT)
        """)
    
    try db.execute(
        sql: "INSERT INTO player (name, score) VALUES (?, ?)",
        arguments: ["Barbara", 1000])
    
    try db.execute(
        sql: "UPDATE player SET score = :score WHERE id = :id",
        arguments: ["score": 1000, "id": 1])
    }
}

The ? and colon-prefixed keys like :score in the SQL query are the statements arguments. You pass arguments with arrays or dictionaries, as in the example above. See Values for more information on supported arguments types (Bool, Int, String, Date, Swift enums, etc.), and StatementArguments for a detailed documentation of SQLite arguments.

You can also embed query arguments right into your SQL queries, with execute(literal:), as in the example below. See SQL Interpolation for more details.

try dbQueue.write { db in
    let name = "O'Brien"
    let score = 550
    try db.execute(literal: """
        INSERT INTO player (name, score) VALUES (\(name), \(score))
        """)
}

Never ever embed values directly in your raw SQL strings. See Avoiding SQL Injection for more information:

// WRONG: don't embed values in raw SQL strings
let id = 123
let name = textField.text
try db.execute(
    sql: "UPDATE player SET name = '\(name)' WHERE id = \(id)")

// CORRECT: use arguments dictionary
try db.execute(
    sql: "UPDATE player SET name = :name WHERE id = :id",
    arguments: ["name": name, "id": id])

// CORRECT: use arguments array
try db.execute(
    sql: "UPDATE player SET name = ? WHERE id = ?",
    arguments: [name, id])

// CORRECT: use SQL Interpolation
try db.execute(
    literal: "UPDATE player SET name = \(name) WHERE id = \(id)")

Join multiple statements with a semicolon:

try db.execute(sql: """
    INSERT INTO player (name, score) VALUES (?, ?);
    INSERT INTO player (name, score) VALUES (?, ?);
    """, arguments: ["Arthur", 750, "Barbara", 1000])

try db.execute(literal: """
    INSERT INTO player (name, score) VALUES (\("Arthur"), \(750));
    INSERT INTO player (name, score) VALUES (\("Barbara"), \(1000));
    """)

When you want to make sure that a single statement is executed, use a prepared Statement.

After an INSERT statement, you can get the row ID of the inserted row with lastInsertedRowID:

try db.execute(
    sql: "INSERT INTO player (name, score) VALUES (?, ?)",
    arguments: ["Arthur", 1000])
let playerId = db.lastInsertedRowID

Don't miss Records, that provide classic persistence methods:

var player = Player(name: "Arthur", score: 1000)
try player.insert(db)
let playerId = player.id

Fetch Queries

Database connections let you fetch database rows, plain values, and custom models aka "records".

Rows are the raw results of SQL queries:

try dbQueue.read { db in
    if let row = try Row.fetchOne(db, sql: "SELECT * FROM wine WHERE id = ?", arguments: [1]) {
        let name: String = row["name"]
        let color: Color = row["color"]
        print(name, color)
    }
}

Values are the Bool, Int, String, Date, Swift enums, etc. stored in row columns:

try dbQueue.read { db in
    let urls = try URL.fetchCursor(db, sql: "SELECT url FROM wine")
    while let url = try urls.next() {
        print(url)
    }
}

Records are your application objects that can initialize themselves from rows:

let wines = try dbQueue.read { db in
    try Wine.fetchAll(db, sql: "SELECT * FROM wine")
}

Fetching Methods

Throughout GRDB, you can always fetch cursors, arrays, sets, or single values of any fetchable type (database row, simple value, or custom record):

try Row.fetchCursor(...) // A Cursor of Row
try Row.fetchAll(...)    // [Row]
try Row.fetchSet(...)    // Set<Row>
try Row.fetchOne(...)    // Row?

fetchCursor returns a cursor over fetched values:

let rows = try Row.fetchCursor(db, sql: "SELECT ...") // A Cursor of Row

fetchAll returns an array:

let players = try Player.fetchAll(db, sql: "SELECT ...") // [Player]

fetchSet returns a set:

let names = try String.fetchSet(db, sql: "SELECT ...") // Set<String>

fetchOne returns a single optional value, and consumes a single database row (if any).
```
let count = try Int.fetchOne(db, sql: "SELECT COUNT(*) ...") // Int?
```

All those fetching methods require an SQL string that contains a single SQL statement. When you want to fetch from multiple statements joined with a semicolon, iterate the multiple prepared statements found in the SQL string.

Cursors

📖 Cursor

Whenever you consume several rows from the database, you can fetch an Array, a Set, or a Cursor.

The fetchAll() and fetchSet() methods return regular Swift array and sets, that you iterate like all other arrays and sets:

try dbQueue.read { db in
    // [Player]
    let players = try Player.fetchAll(db, sql: "SELECT ...")
    for player in players {
        // use player
    }
}

Unlike arrays and sets, cursors returned by fetchCursor() load their results step after step:

try dbQueue.read { db in
    // Cursor of Player
    let players = try Player.fetchCursor(db, sql: "SELECT ...")
    while let player = try players.next() {
        // use player
    }
}

Cursors can not be used on any thread: you must consume a cursor on the dispatch queue it was created in. Particularly, don't extract a cursor out of a database access method:

// Wrong
let cursor = try dbQueue.read { db in
    try Player.fetchCursor(db, ...)
}
while let player = try cursor.next() { ... }

Conversely, arrays and sets may be consumed on any thread:

// OK
let array = try dbQueue.read { db in
    try Player.fetchAll(db, ...)
}
for player in array { ... }

Cursors can be iterated only one time. Arrays and sets can be iterated many times.
Cursors iterate database results in a lazy fashion, and don't consume much memory. Arrays and sets contain copies of database values, and may take a lot of memory when there are many fetched results.
Cursors are granted with direct access to SQLite, unlike arrays and sets that have to take the time to copy database values. If you look after extra performance, you may prefer cursors.
Cursors can feed Swift collections.

You will most of the time use fetchAll or fetchSet when you want an array or a set. For more specific needs, you may prefer one of the initializers below. All of them accept an extra optional minimumCapacity argument which helps optimizing your app when you have an idea of the number of elements in a cursor (the built-in fetchAll and fetchSet do not perform such an optimization).

Arrays and all types conforming to RangeReplaceableCollection:
```
// [String]
let cursor = try String.fetchCursor(db, ...)
let array = try Array(cursor)
```
Sets:
```
// Set<Int>
let cursor = try Int.fetchCursor(db, ...)
let set = try Set(cursor)
```
Dictionaries:
```
// [Int64: [Player]]
let cursor = try Player.fetchCursor(db)
let dictionary = try Dictionary(grouping: cursor, by: { $0.teamID })

// [Int64: Player]
let cursor = try Player.fetchCursor(db).map { ($0.id, $0) }
let dictionary = try Dictionary(uniqueKeysWithValues: cursor)
```

Cursors adopt the Cursor protocol, which looks a lot like standard lazy sequences of Swift. As such, cursors come with many convenience methods: compactMap, contains, dropFirst, dropLast, drop(while:), enumerated, filter, first, flatMap, forEach, joined, joined(separator:), max, max(by:), min, min(by:), map, prefix, prefix(while:), reduce, reduce(into:), suffix:

// Prints all Github links
try URL
    .fetchCursor(db, sql: "SELECT url FROM link")
    .filter { url in url.host == "github.com" }
    .forEach { url in print(url) }

// An efficient cursor of coordinates:
let locations = try Row.
    .fetchCursor(db, sql: "SELECT latitude, longitude FROM place")
    .map { row in
        CLLocationCoordinate2D(latitude: row[0], longitude: row[1])
    }

Cursors are not Swift sequences. That's because Swift sequences can't handle iteration errors, when reading SQLite results may fail at any time.
Cursors require a little care:
- Don't modify the results during a cursor iteration:
```
// Undefined behavior
while let player = try players.next() {
    try db.execute(sql: "DELETE ...")
}
```
- Don't turn a cursor of Row into an array or a set. You would not get the distinct rows you expect. To get a array of rows, use Row.fetchAll(...). To get a set of rows, use Row.fetchSet(...). Generally speaking, make sure you copy a row whenever you extract it from a cursor for later use: row.copy().

If you don't see, or don't care about the difference, use arrays. If you care about memory and performance, use cursors when appropriate.

Row Queries

Fetching Rows

Fetch cursors of rows, arrays, sets, or single rows (see fetching methods):

try dbQueue.read { db in
    try Row.fetchCursor(db, sql: "SELECT ...", arguments: ...) // A Cursor of Row
    try Row.fetchAll(db, sql: "SELECT ...", arguments: ...)    // [Row]
    try Row.fetchSet(db, sql: "SELECT ...", arguments: ...)    // Set<Row>
    try Row.fetchOne(db, sql: "SELECT ...", arguments: ...)    // Row?
    
    let rows = try Row.fetchCursor(db, sql: "SELECT * FROM wine")
    while let row = try rows.next() {
        let name: String = row["name"]
        let color: Color = row["color"]
        print(name, color)
    }
}

let rows = try dbQueue.read { db in
    try Row.fetchAll(db, sql: "SELECT * FROM player")
}

Arguments are optional arrays or dictionaries that fill the positional ? and colon-prefixed keys like :name in the query:

let rows = try Row.fetchAll(db,
    sql: "SELECT * FROM player WHERE name = ?",
    arguments: ["Arthur"])

let rows = try Row.fetchAll(db,
    sql: "SELECT * FROM player WHERE name = :name",
    arguments: ["name": "Arthur"])

See Values for more information on supported arguments types (Bool, Int, String, Date, Swift enums, etc.), and StatementArguments for a detailed documentation of SQLite arguments.

Unlike row arrays that contain copies of the database rows, row cursors are close to the SQLite metal, and require a little care:

Note: Don't turn a cursor of Row into an array or a set. You would not get the distinct rows you expect. To get a array of rows, use Row.fetchAll(...). To get a set of rows, use Row.fetchSet(...). Generally speaking, make sure you copy a row whenever you extract it from a cursor for later use: row.copy().

Column Values

Read column values by index or column name:

let name: String = row[0]      // 0 is the leftmost column
let name: String = row["name"] // Leftmost matching column - lookup is case-insensitive
let name: String = row[Column("name")] // Using query interface's Column

Make sure to ask for an optional when the value may be NULL:

let name: String? = row["name"]

The row[] subscript returns the type you ask for. See Values for more information on supported value types:

let bookCount: Int     = row["bookCount"]
let bookCount64: Int64 = row["bookCount"]
let hasBooks: Bool     = row["bookCount"] // false when 0

let string: String     = row["date"]      // "2015-09-11 18:14:15.123"
let date: Date         = row["date"]      // Date
self.date = row["date"] // Depends on the type of the property.

You can also use the as type casting operator:

row[...] as Int
row[...] as Int?

Throwing accessors exist as well. Their use is not encouraged, because a database decoding error is a programming error. If an application stores invalid data in the database file, that is a bug that needs to be fixed:

let name = try row.decode(String.self, atIndex: 0)
let bookCount = try row.decode(Int.self, forColumn: "bookCount")

Warning: avoid the as! and as? operators:

if let int = row[...] as? Int { ... } // BAD - doesn't work
if let int = row[...] as Int? { ... } // GOOD

Warning: avoid nil-coalescing row values, and prefer the coalesce method instead:
let name: String? = row["nickname"] ?? row["name"]     // BAD - doesn't work
let name: String? = row.coalesce(["nickname", "name"]) // GOOD

Generally speaking, you can extract the type you need, provided it can be converted from the underlying SQLite value:

Successful conversions include:
- All numeric SQLite values to all numeric Swift types, and Bool (zero is the only false boolean).
- Text SQLite values to Swift String.
- Blob SQLite values to Foundation Data.
See Values for more information on supported types (Bool, Int, String, Date, Swift enums, etc.)

NULL returns nil.

let row = try Row.fetchOne(db, sql: "SELECT NULL")!
row[0] as Int? // nil
row[0] as Int  // fatal error: could not convert NULL to Int.

There is one exception, though: the DatabaseValue type:

row[0] as DatabaseValue // DatabaseValue.null

Missing columns return nil.

let row = try Row.fetchOne(db, sql: "SELECT 'foo' AS foo")!
row["missing"] as String? // nil
row["missing"] as String  // fatal error: no such column: missing

You can explicitly check for a column presence with the hasColumn method.

Invalid conversions throw a fatal error.

let row = try Row.fetchOne(db, sql: "SELECT 'Mom’s birthday'")!
row[0] as String // "Mom’s birthday"
row[0] as Date?  // fatal error: could not convert "Mom’s birthday" to Date.
row[0] as Date   // fatal error: could not convert "Mom’s birthday" to Date.

let row = try Row.fetchOne(db, sql: "SELECT 256")!
row[0] as Int    // 256
row[0] as UInt8? // fatal error: could not convert 256 to UInt8.
row[0] as UInt8  // fatal error: could not convert 256 to UInt8.

Those conversion fatal errors can be avoided with the DatabaseValue type:

let row = try Row.fetchOne(db, sql: "SELECT 'Mom’s birthday'")!
let dbValue: DatabaseValue = row[0]
if dbValue.isNull {
    // Handle NULL
} else if let date = Date.fromDatabaseValue(dbValue) {
    // Handle valid date
} else {
    // Handle invalid date
}

This extra verbosity is the consequence of having to deal with an untrusted database: you may consider fixing the content of your database instead. See Fatal Errors for more information.

SQLite has a weak type system, and provides convenience conversions that can turn String to Int, Double to Blob, etc.

GRDB will sometimes let those conversions go through:
```
let rows = try Row.fetchCursor(db, sql: "SELECT '20 small cigars'")
while let row = try rows.next() {
    row[0] as Int   // 20
}
```
Don't freak out: those conversions did not prevent SQLite from becoming the immensely successful database engine you want to use. And GRDB adds safety checks described just above. You can also prevent those convenience conversions altogether by using the DatabaseValue type.

DatabaseValue

📖 DatabaseValue

DatabaseValue is an intermediate type between SQLite and your values, which gives information about the raw value stored in the database.

You get DatabaseValue just like other value types:

let dbValue: DatabaseValue = row[0]
let dbValue: DatabaseValue? = row["name"] // nil if and only if column does not exist

// Check for NULL:
dbValue.isNull // Bool

// The stored value:
dbValue.storage.value // Int64, Double, String, Data, or nil

// All the five storage classes supported by SQLite:
switch dbValue.storage {
case .null:                 print("NULL")
case .int64(let int64):     print("Int64: \(int64)")
case .double(let double):   print("Double: \(double)")
case .string(let string):   print("String: \(string)")
case .blob(let data):       print("Data: \(data)")
}

You can extract regular values (Bool, Int, String, Date, Swift enums, etc.) from DatabaseValue with the fromDatabaseValue() method:

let dbValue: DatabaseValue = row["bookCount"]
let bookCount   = Int.fromDatabaseValue(dbValue)   // Int?
let bookCount64 = Int64.fromDatabaseValue(dbValue) // Int64?
let hasBooks    = Bool.fromDatabaseValue(dbValue)  // Bool?, false when 0

let dbValue: DatabaseValue = row["date"]
let string = String.fromDatabaseValue(dbValue)     // "2015-09-11 18:14:15.123"
let date   = Date.fromDatabaseValue(dbValue)       // Date?

fromDatabaseValue returns nil for invalid conversions:

let row = try Row.fetchOne(db, sql: "SELECT 'Mom’s birthday'")!
let dbValue: DatabaseValue = row[0]
let string = String.fromDatabaseValue(dbValue) // "Mom’s birthday"
let int    = Int.fromDatabaseValue(dbValue)    // nil
let date   = Date.fromDatabaseValue(dbValue)   // nil

Rows as Dictionaries

Row adopts the standard RandomAccessCollection protocol, and can be seen as a dictionary of DatabaseValue:

// All the (columnName, dbValue) tuples, from left to right:
for (columnName, dbValue) in row {
    ...
}

You can build rows from dictionaries (standard Swift dictionaries and NSDictionary). See Values for more information on supported types:

let row: Row = ["name": "foo", "date": nil]
let row = Row(["name": "foo", "date": nil])
let row = Row(/* [AnyHashable: Any] */) // nil if invalid dictionary

Yet rows are not real dictionaries: they may contain duplicate columns:

let row = try Row.fetchOne(db, sql: "SELECT 1 AS foo, 2 AS foo")!
row.columnNames    // ["foo", "foo"]
row.databaseValues // [1, 2]
row["foo"]         // 1 (leftmost matching column)
for (columnName, dbValue) in row { ... } // ("foo", 1), ("foo", 2)

When you build a dictionary from a row, you have to disambiguate identical columns, and choose how to present database values. For example:

A [String: DatabaseValue] dictionary that keeps leftmost value in case of duplicated column name:
```
let dict = Dictionary(row, uniquingKeysWith: { (left, _) in left })
```
A [String: AnyObject] dictionary which keeps rightmost value in case of duplicated column name. This dictionary is identical to FMResultSet's resultDictionary from FMDB. It contains NSNull values for null columns, and can be shared with Objective-C:
```
let dict = Dictionary(
    row.map { (column, dbValue) in
        (column, dbValue.storage.value as AnyObject)
    },
    uniquingKeysWith: { (_, right) in right })
```

A [String: Any] dictionary that can feed, for example, JSONSerialization:

let dict = Dictionary(
    row.map { (column, dbValue) in
        (column, dbValue.storage.value)
    },
    uniquingKeysWith: { (left, _) in left })

See the documentation of Dictionary.init(_:uniquingKeysWith:) for more information.

Value Queries

📖 DatabaseValueConvertible

Instead of rows, you can directly fetch values. There are many supported value types (Bool, Int, String, Date, Swift enums, etc.).

Like rows, fetch values as cursors, arrays, sets, or single values (see fetching methods). Values are extracted from the leftmost column of the SQL queries:

try dbQueue.read { db in
    try Int.fetchCursor(db, sql: "SELECT ...", arguments: ...) // A Cursor of Int
    try Int.fetchAll(db, sql: "SELECT ...", arguments: ...)    // [Int]
    try Int.fetchSet(db, sql: "SELECT ...", arguments: ...)    // Set<Int>
    try Int.fetchOne(db, sql: "SELECT ...", arguments: ...)    // Int?
    
    let maxScore = try Int.fetchOne(db, sql: "SELECT MAX(score) FROM player") // Int?
    let names = try String.fetchAll(db, sql: "SELECT name FROM player")       // [String]
}

Int.fetchOne returns nil in two cases: either the SELECT statement yielded no row, or one row with a NULL value:

// No row:
try Int.fetchOne(db, sql: "SELECT 42 WHERE FALSE") // nil

// One row with a NULL value:
try Int.fetchOne(db, sql: "SELECT NULL")           // nil

// One row with a non-NULL value:
try Int.fetchOne(db, sql: "SELECT 42")             // 42

For requests which may contain NULL, fetch optionals:

try dbQueue.read { db in
    try Optional<Int>.fetchCursor(db, sql: "SELECT ...", arguments: ...) // A Cursor of Int?
    try Optional<Int>.fetchAll(db, sql: "SELECT ...", arguments: ...)    // [Int?]
    try Optional<Int>.fetchSet(db, sql: "SELECT ...", arguments: ...)    // Set<Int?>
}

💡 Tip: One advanced use case, when you fetch one value, is to distinguish the cases of a statement that yields no row, or one row with a NULL value. To do so, use Optional<Int>.fetchOne, which returns a double optional Int??:
// No row:
try Optional<Int>.fetchOne(db, sql: "SELECT 42 WHERE FALSE") // .none
// One row with a NULL value:
try Optional<Int>.fetchOne(db, sql: "SELECT NULL")           // .some(.none)
// One row with a non-NULL value:
try Optional<Int>.fetchOne(db, sql: "SELECT 42")             // .some(.some(42))

There are many supported value types (Bool, Int, String, Date, Swift enums, etc.). See Values for more information.

Values

GRDB ships with built-in support for the following value types:

Swift Standard Library: Bool, Double, Float, all signed and unsigned integer types, String, Swift enums.
Foundation: Data, Date, DateComponents, Decimal, NSNull, NSNumber, NSString, URL, UUID.
CoreGraphics: CGFloat.
DatabaseValue, the type which gives information about the raw value stored in the database.
Full-Text Patterns: FTS3Pattern and FTS5Pattern.
Generally speaking, all types that adopt the DatabaseValueConvertible protocol.

Values can be used as statement arguments:

let url: URL = ...
let verified: Bool = ...
try db.execute(
    sql: "INSERT INTO link (url, verified) VALUES (?, ?)",
    arguments: [url, verified])

Values can be extracted from rows:

let rows = try Row.fetchCursor(db, sql: "SELECT * FROM link")
while let row = try rows.next() {
    let url: URL = row["url"]
    let verified: Bool = row["verified"]
}

Values can be directly fetched:

let urls = try URL.fetchAll(db, sql: "SELECT url FROM link")  // [URL]

Use values in Records:

struct Link: FetchableRecord {
    var url: URL
    var isVerified: Bool
    
    init(row: Row) {
        url = row["url"]
        isVerified = row["verified"]
    }
}

Use values in the query interface:

let url: URL = ...
let link = try Link.filter { $0.url == url }.fetchOne(db)

Data (and Memory Savings)

Data suits the BLOB SQLite columns. It can be stored and fetched from the database just like other values:

let rows = try Row.fetchCursor(db, sql: "SELECT data, ...")
while let row = try rows.next() {
    let data: Data = row["data"]
}

At each step of the request iteration, the row[] subscript creates two copies of the database bytes: one fetched by SQLite, and another, stored in the Swift Data value.

You have the opportunity to save memory by not copying the data fetched by SQLite:

while let row = try rows.next() {
    try row.withUnsafeData(name: "data") { (data: Data?) in
        ...
    }
}

The non-copied data does not live longer than the iteration step: make sure that you do not use it past this point.

Date and DateComponents

Date and DateComponents can be stored and fetched from the database.

Here is how GRDB supports the various date formats supported by SQLite:

SQLite format	Date	DateComponents
YYYY-MM-DD	Read ¹	Read / Write
YYYY-MM-DD HH:MM	Read ¹ ²	Read ² / Write
YYYY-MM-DD HH:MM:SS	Read ¹ ²	Read ² / Write
YYYY-MM-DD HH:MM:SS.SSS	Read ¹ ² / Write ¹	Read ² / Write
YYYY-MM-DDTHH:MM	Read ¹ ²	Read ²
YYYY-MM-DDTHH:MM:SS	Read ¹ ²	Read ²
YYYY-MM-DDTHH:MM:SS.SSS	Read ¹ ²	Read ²
HH:MM		Read ² / Write
HH:MM:SS		Read ² / Write
HH:MM:SS.SSS		Read ² / Write
Timestamps since unix epoch	Read ³
`now`

¹ Missing components are assumed to be zero. Dates are stored and read in the UTC time zone, unless the format is followed by a timezone indicator ⁽²⁾.

² This format may be optionally followed by a timezone indicator of the form [+-]HH:MM or just Z.

³ GRDB 2+ interprets numerical values as timestamps that fuel Date(timeIntervalSince1970:). Previous GRDB versions used to interpret numbers as julian days. Julian days are still supported, with the Date(julianDay:) initializer.

Warning: the range of valid years in the SQLite date formats is 0000-9999. You will need to pick another date format when your application needs to process years outside of this range. See the following chapters.

Date

Date can be stored and fetched from the database just like other values:

try db.execute(
    sql: "INSERT INTO player (creationDate, ...) VALUES (?, ...)",
    arguments: [Date(), ...])

let row = try Row.fetchOne(db, ...)!
let creationDate: Date = row["creationDate"]

Dates are stored using the format "YYYY-MM-DD HH:MM:SS.SSS" in the UTC time zone. It is precise to the millisecond.

Note: this format was chosen because it is the only format that is:

Comparable (ORDER BY date works)

Comparable with the SQLite keyword CURRENT_TIMESTAMP (WHERE date > CURRENT_TIMESTAMP works)

Able to feed SQLite date & time functions

Precise enough

Warning: the range of valid years in the SQLite date format is 0000-9999. You will experience problems with years outside of this range, such as decoding errors, or invalid date computations with SQLite date & time functions.

Some applications may prefer another date format:

Some may prefer ISO-8601, with a T separator.
Some may prefer ISO-8601, with a time zone.
Some may need to store years beyond the 0000-9999 range.
Some may need sub-millisecond precision.
Some may need exact Date roundtrip.
Etc.

You should think twice before choosing a different date format:

ISO-8601 is about exchange and communication, when SQLite is about storage and data manipulation. Sharing the same representation in your database and in JSON files only provides a superficial convenience, and should be the least of your priorities. Don't store dates as ISO-8601 without understanding what you lose. For example, ISO-8601 time zones forbid database-level date comparison.
Sub-millisecond precision and exact Date roundtrip are not as obvious needs as it seems at first sight. Dates generally don't precisely roundtrip as soon as they leave your application anyway, because the other systems your app communicates with use their own date representation (the Android version of your app, the server your application is talking to, etc.) On top of that, Date comparison is at least as hard and nasty as floating point comparison.

The customization of date format is explicit. For example:

let date = Date()
let timeInterval = date.timeIntervalSinceReferenceDate
try db.execute(
    sql: "INSERT INTO player (creationDate, ...) VALUES (?, ...)",
    arguments: [timeInterval, ...])

if let row = try Row.fetchOne(db, ...) {
    let timeInterval: TimeInterval = row["creationDate"]
    let creationDate = Date(timeIntervalSinceReferenceDate: timeInterval)
}

See also Codable Records for more date customization options, and DatabaseValueConvertible if you want to define a Date-wrapping type with customized database representation.

DateComponents

DateComponents is indirectly supported, through the DatabaseDateComponents helper type.

DatabaseDateComponents reads date components from all date formats supported by SQLite, and stores them in the format of your choice, from HH:MM to YYYY-MM-DD HH:MM:SS.SSS.

Warning: the range of valid years is 0000-9999. You will experience problems with years outside of this range, such as decoding errors, or invalid date computations with SQLite date & time functions. See Date for more information.

DatabaseDateComponents can be stored and fetched from the database just like other values:

let components = DateComponents()
components.year = 1973
components.month = 9
components.day = 18

// Store "1973-09-18"
let dbComponents = DatabaseDateComponents(components, format: .YMD)
try db.execute(
    sql: "INSERT INTO player (birthDate, ...) VALUES (?, ...)",
    arguments: [dbComponents, ...])

// Read "1973-09-18"
let row = try Row.fetchOne(db, sql: "SELECT birthDate ...")!
let dbComponents: DatabaseDateComponents = row["birthDate"]
dbComponents.format         // .YMD (the actual format found in the database)
dbComponents.dateComponents // DateComponents

NSNumber, NSDecimalNumber, and Decimal

NSNumber and Decimal can be stored and fetched from the database just like other values.

Here is how GRDB supports the various data types supported by SQLite:

	Integer	Double	String
NSNumber	Read / Write	Read / Write	Read
NSDecimalNumber	Read / Write	Read / Write	Read
Decimal	Read	Read	Read / Write

All three types can decode database integers and doubles:

let number = try NSNumber.fetchOne(db, sql: "SELECT 10")            // NSNumber
let number = try NSDecimalNumber.fetchOne(db, sql: "SELECT 1.23")   // NSDecimalNumber
let number = try Decimal.fetchOne(db, sql: "SELECT -100")           // Decimal

All three types decode database strings as decimal numbers:

let number = try NSNumber.fetchOne(db, sql: "SELECT '10'")          // NSDecimalNumber (sic)
let number = try NSDecimalNumber.fetchOne(db, sql: "SELECT '1.23'") // NSDecimalNumber
let number = try Decimal.fetchOne(db, sql: "SELECT '-100'")         // Decimal

NSNumber and NSDecimalNumber send 64-bit signed integers and doubles in the database:

// INSERT INTO transfer VALUES (10)
try db.execute(sql: "INSERT INTO transfer VALUES (?)", arguments: [NSNumber(value: 10)])

// INSERT INTO transfer VALUES (10.0)
try db.execute(sql: "INSERT INTO transfer VALUES (?)", arguments: [NSNumber(value: 10.0)])

// INSERT INTO transfer VALUES (10)
try db.execute(sql: "INSERT INTO transfer VALUES (?)", arguments: [NSDecimalNumber(string: "10.0")])

// INSERT INTO transfer VALUES (10.5)
try db.execute(sql: "INSERT INTO transfer VALUES (?)", arguments: [NSDecimalNumber(string: "10.5")])

Warning: since SQLite does not support decimal numbers, sending a non-integer NSDecimalNumber can result in a loss of precision during the conversion to double.

Instead of sending non-integer NSDecimalNumber to the database, you may prefer:

Send Decimal instead (those store decimal strings in the database).

Send integers instead (for example, store amounts of cents instead of amounts of Euros).

Decimal sends decimal strings in the database:

// INSERT INTO transfer VALUES ('10')
try db.execute(sql: "INSERT INTO transfer VALUES (?)", arguments: [Decimal(10)])

// INSERT INTO transfer VALUES ('10.5')
try db.execute(sql: "INSERT INTO transfer VALUES (?)", arguments: [Decimal(string: "10.5")!])

UUID

UUID can be stored and fetched from the database just like other values.

GRDB stores uuids as 16-bytes data blobs, and decodes them from both 16-bytes data blobs and strings such as "E621E1F8-C36C-495A-93FC-0C247A3E6E5F".

Swift Enums

Swift enums and generally all types that adopt the RawRepresentable protocol can be stored and fetched from the database just like their raw values:

enum Color : Int {
    case red, white, rose
}

enum Grape : String {
    case chardonnay, merlot, riesling
}

// Declare empty DatabaseValueConvertible adoption
extension Color : DatabaseValueConvertible { }
extension Grape : DatabaseValueConvertible { }

// Store
try db.execute(
    sql: "INSERT INTO wine (grape, color) VALUES (?, ?)",
    arguments: [Grape.merlot, Color.red])

// Read
let rows = try Row.fetchCursor(db, sql: "SELECT * FROM wine")
while let row = try rows.next() {
    let grape: Grape = row["grape"]
    let color: Color = row["color"]
}

When a database value does not match any enum case, you get a fatal error. This fatal error can be avoided with the DatabaseValue type:

let row = try Row.fetchOne(db, sql: "SELECT 'syrah'")!

row[0] as String  // "syrah"
row[0] as Grape?  // fatal error: could not convert "syrah" to Grape.
row[0] as Grape   // fatal error: could not convert "syrah" to Grape.

let dbValue: DatabaseValue = row[0]
if dbValue.isNull {
    // Handle NULL
} else if let grape = Grape.fromDatabaseValue(dbValue) {
    // Handle valid grape
} else {
    // Handle unknown grape
}

Custom SQL Functions and Aggregates

SQLite lets you define SQL functions and aggregates.

A custom SQL function or aggregate extends SQLite:

SELECT reverse(name) FROM player;   -- custom function
SELECT maxLength(name) FROM player; -- custom aggregate

Custom SQL Functions

📖 DatabaseFunction

A function argument takes an array of DatabaseValue, and returns any valid value (Bool, Int, String, Date, Swift enums, etc.) The number of database values is guaranteed to be argumentCount.

SQLite has the opportunity to perform additional optimizations when functions are "pure", which means that their result only depends on their arguments. So make sure to set the pure argument to true when possible.

let reverse = DatabaseFunction("reverse", argumentCount: 1, pure: true) { (values: [DatabaseValue]) in
    // Extract string value, if any...
    guard let string = String.fromDatabaseValue(values[0]) else {
        return nil
    }
    // ... and return reversed string:
    return String(string.reversed())
}

You make a function available to a database connection through its configuration:

var config = Configuration()
config.prepareDatabase { db in
    db.add(function: reverse)
}
let dbQueue = try DatabaseQueue(path: dbPath, configuration: config)

try dbQueue.read { db in
    // "oof"
    try String.fetchOne(db, sql: "SELECT reverse('foo')")!
}

Functions can take a variable number of arguments:

When you don't provide any explicit argumentCount, the function can take any number of arguments:

let averageOf = DatabaseFunction("averageOf", pure: true) { (values: [DatabaseValue]) in
    let doubles = values.compactMap { Double.fromDatabaseValue($0) }
    return doubles.reduce(0, +) / Double(doubles.count)
}
db.add(function: averageOf)

// 2.0
try Double.fetchOne(db, sql: "SELECT averageOf(1, 2, 3)")!

Functions can throw:

let sqrt = DatabaseFunction("sqrt", argumentCount: 1, pure: true) { (values: [DatabaseValue]) in
    guard let double = Double.fromDatabaseValue(values[0]) else {
        return nil
    }
    guard double >= 0 else {
        throw DatabaseError(message: "invalid negative number")
    }
    return sqrt(double)
}
db.add(function: sqrt)

// SQLite error 1 with statement `SELECT sqrt(-1)`: invalid negative number
try Double.fetchOne(db, sql: "SELECT sqrt(-1)")!

Use custom functions in the query interface:

// SELECT reverseString("name") FROM player
Player.select { reverseString($0.name) }

GRDB ships with built-in SQL functions that perform unicode-aware string transformations. See Unicode.

Custom Aggregates

📖 DatabaseFunction, DatabaseAggregate

Before registering a custom aggregate, you need to define a type that adopts the DatabaseAggregate protocol:

protocol DatabaseAggregate {
    // Initializes an aggregate
    init()
    
    // Called at each step of the aggregation
    mutating func step(_ dbValues: [DatabaseValue]) throws
    
    // Returns the final result
    func finalize() throws -> DatabaseValueConvertible?
}

For example:

struct MaxLength : DatabaseAggregate {
    var maxLength: Int = 0
    
    mutating func step(_ dbValues: [DatabaseValue]) {
        // At each step, extract string value, if any...
        guard let string = String.fromDatabaseValue(dbValues[0]) else {
            return
        }
        // ... and update the result
        let length = string.count
        if length > maxLength {
            maxLength = length
        }
    }
    
    func finalize() -> DatabaseValueConvertible? {
        maxLength
    }
}

let maxLength = DatabaseFunction(
    "maxLength",
    argumentCount: 1,
    pure: true,
    aggregate: MaxLength.self)

Like custom SQL Functions, you make an aggregate function available to a database connection through its configuration:

var config = Configuration()
config.prepareDatabase { db in
    db.add(function: maxLength)
}
let dbQueue = try DatabaseQueue(path: dbPath, configuration: config)

try dbQueue.read { db in
    // Some Int
    try Int.fetchOne(db, sql: "SELECT maxLength(name) FROM player")!
}

The step method of the aggregate takes an array of DatabaseValue. This array contains as many values as the argumentCount parameter (or any number of values, when argumentCount is omitted).

The finalize method of the aggregate returns the final aggregated value (Bool, Int, String, Date, Swift enums, etc.).

SQLite has the opportunity to perform additional optimizations when aggregates are "pure", which means that their result only depends on their inputs. So make sure to set the pure argument to true when possible.

Use custom aggregates in the query interface:

// SELECT maxLength("name") FROM player
let request = Player.select { maxLength($0.name) }
try Int.fetchOne(db, request) // Int?

Raw SQLite Pointers

If not all SQLite APIs are exposed in GRDB, you can still use the SQLite C Interface and call SQLite C functions.

To access the C SQLite functions from SQLCipher or the system SQLite, you need to perform an extra import:

import SQLite3   // System SQLite
import SQLCipher // SQLCipher

let sqliteVersion = String(cString: sqlite3_libversion())

Raw pointers to database connections and statements are available through the Database.sqliteConnection and Statement.sqliteStatement properties:

try dbQueue.read { db in
    // The raw pointer to a database connection:
    let sqliteConnection = db.sqliteConnection

    // The raw pointer to a statement:
    let statement = try db.makeStatement(sql: "SELECT ...")
    let sqliteStatement = statement.sqliteStatement
}

Note

Those pointers are owned by GRDB: don't close connections or finalize statements created by GRDB.

GRDB opens SQLite connections in the "multi-thread mode", which (oddly) means that they are not thread-safe. Make sure you touch raw databases and statements inside their dedicated dispatch queues.

Use the raw SQLite C Interface at your own risk. GRDB won't prevent you from shooting yourself in the foot.

Records

On top of the SQLite API, GRDB provides protocols that help manipulating database rows as regular objects named "records":

try dbQueue.write { db in
    if var player = try Player.fetchOne(db, id: 1) {
        player.score += 10
        try player.update(db)
    }
}

Of course, you need to open a database connection, and create database tables first.

To define a record type, define a type and extend it with database protocols:

FetchableRecord makes it possible to fetch instances from the database.
PersistableRecord makes it possible to save instances into the database.
Codable (not mandatory) provides ready-made serialization to and from database rows.
Identifiable (not mandatory) provides extra convenience database methods.

To make it easier to customize database requests, also nest a Columns enum:

struct Player: Codable, Identifiable {
    var id: Int64
    var name: String
    var score: Int
    var team: String?
}

// Add database support
extension Player: FetchableRecord, PersistableRecord {
    enum Columns {
        static let name = Column(CodingKeys.name)
        static let score = Column(CodingKeys.score)
        static let team = Column(CodingKeys.team)
    }
}

See more examples of record definitions below.

Note: if you are familiar with Core Data's NSManagedObject or Realm's Object, you may experience a cultural shock: GRDB records are not uniqued, do not auto-update, and do not lazy-load. This is both a purpose, and a consequence of protocol-oriented programming.

Tip: The Recommended Practices for Designing Record Types guide provides general guidance..

Tip: See the Demo Applications for sample apps that uses records.

Overview

Protocols and the Record Class

Inserting Records

To insert a record in the database, call the insert method:

let player = Player(id: 1, name: "Arthur", score: 1000)
try player.insert(db)

👉 insert is available for types that adopt the PersistableRecord protocol.

Fetching Records

To fetch records from the database, call a fetching method:

let arthur = try Player.fetchOne(db,            // Player?
    sql: "SELECT * FROM players WHERE name = ?",
    arguments: ["Arthur"])

let bestPlayers = try Player                    // [Player]
    .order(\.score.desc)
    .limit(10)
    .fetchAll(db)
    
let spain = try Country.fetchOne(db, id: "ES")  // Country?
let italy = try Country.find(db, id: "IT")      // Country

👉 Fetching from raw SQL is available for types that adopt the FetchableRecord protocol.

👉 Fetching without SQL, using the query interface, is available for types that adopt both FetchableRecord and TableRecord protocol.

Updating Records

To update a record in the database, call the update method:

var player: Player = ...
player.score = 1000
try player.update(db)

It is possible to avoid useless updates:

// does not hit the database if score has not changed
try player.updateChanges(db) {
    $0.score = 1000
}

See the query interface for batch updates:

try Player
    .filter { $0.team == "red" }
    .updateAll(db) { $0.score += 1 }

👉 update methods are available for types that adopt the PersistableRecord protocol. Batch updates are available on the TableRecord protocol.

Deleting Records

To delete a record in the database, call the delete method:

let player: Player = ...
try player.delete(db)

You can also delete by primary key, unique key, or perform batch deletes (see Delete Requests):

try Player.deleteOne(db, id: 1)
try Player.deleteOne(db, key: ["email": "arthur@example.com"])
try Country.deleteAll(db, ids: ["FR", "US"])
try Player
    .filter { $0.email == nil }
    .deleteAll(db)

👉 delete methods are available for types that adopt the PersistableRecord protocol. Batch deletes are available on the TableRecord protocol.

Counting Records

To count records, call the fetchCount method:

let playerCount: Int = try Player.fetchCount(db)

let playerWithEmailCount: Int = try Player
    .filter { $0.email == nil }
    .fetchCount(db)

👉 fetchCount is available for types that adopt the TableRecord protocol.

Details follow:

Record Protocols Overview

GRDB ships with three record protocols. Your own types will adopt one or several of them, according to the abilities you want to extend your types with.

FetchableRecord is able to decode database rows.
```
struct Place: FetchableRecord { ... }

let places = try dbQueue.read { db in
    try Place.fetchAll(db, sql: "SELECT * FROM place")
}
```
💡 Tip: FetchableRecord can derive its implementation from the standard Decodable protocol. See Codable Records for more information.

FetchableRecord can decode database rows, but it is not able to build SQL requests for you. For that, you also need TableRecord:

TableRecord is able to generate SQL queries:

struct Place: TableRecord { ... }

let placeCount = try dbQueue.read { db in
    // Generates and runs `SELECT COUNT(*) FROM place`
    try Place.fetchCount(db)
}

When a type adopts both TableRecord and FetchableRecord, it can load from those requests:

struct Place: TableRecord, FetchableRecord { ... }

try dbQueue.read { db in
    let places = try Place.order(\.title).fetchAll(db)
    let paris = try Place.fetchOne(id: 1)
}

PersistableRecord is able to write: it can create, update, and delete rows in the database:
```
struct Place : PersistableRecord { ... }

try dbQueue.write { db in
    try Place.delete(db, id: 1)
    try Place(...).insert(db)
}
```
A persistable record can also compare itself against other records, and avoid useless database updates.

💡 Tip: PersistableRecord can derive its implementation from the standard Encodable protocol. See Codable Records for more information.

FetchableRecord Protocol

📖 FetchableRecord

The FetchableRecord protocol grants fetching methods to any type that can be built from a database row:

protocol FetchableRecord {
    /// Row initializer
    init(row: Row) throws
}

For example:

struct Place {
    var id: Int64?
    var title: String
    var coordinate: CLLocationCoordinate2D
}

extension Place: FetchableRecord {
    enum Columns {
        static let id = Column("id")
        static let title = Column("title")
        static let latitude = Column("latitude")
        static let longitude = Column("longitude")
    }
    
    init(row: Row) {
        id = row[Columns.id]
        title = row[Columns.title]
        coordinate = CLLocationCoordinate2D(
            latitude: row[Columns.latitude],
            longitude: row[Columns.longitude])
    }
}

See column values for more information about the row[] subscript.

When your record type adopts the standard Decodable protocol, you don't have to provide the implementation for init(row:). See Codable Records for more information:

// That's all
struct Player: Decodable, FetchableRecord {
    var id: Int64
    var name: String
    var score: Int
    
    enum Columns {
        static let id = Column(CodingKeys.id)
        static let name = Column(CodingKeys.name)
        static let score = Column(CodingKeys.score)
    }
}

FetchableRecord allows adopting types to be fetched from SQL queries:

try Place.fetchCursor(db, sql: "SELECT ...", arguments:...) // A Cursor of Place
try Place.fetchAll(db, sql: "SELECT ...", arguments:...)    // [Place]
try Place.fetchSet(db, sql: "SELECT ...", arguments:...)    // Set<Place>
try Place.fetchOne(db, sql: "SELECT ...", arguments:...)    // Place?

See fetching methods for information about the fetchCursor, fetchAll, fetchSet and fetchOne methods. See StatementArguments for more information about the query arguments.

Note: for performance reasons, the same row argument to init(row:) is reused during the iteration of a fetch query. If you want to keep the row for later use, make sure to store a copy: self.row = row.copy().

Note: The FetchableRecord.init(row:) initializer fits the needs of most applications. But some application are more demanding than others. When FetchableRecord does not exactly provide the support you need, have a look at the Beyond FetchableRecord chapter.

TableRecord Protocol

📖 TableRecord

The TableRecord protocol generates SQL for you:

protocol TableRecord {
    static var databaseTableName: String { get }
    static var databaseSelection: [any SQLSelectable] { get }
}

The databaseSelection type property is optional, and documented in the Columns Selected by a Request chapter.

The databaseTableName type property is the name of a database table. By default, it is derived from the type name:

struct Place: TableRecord { }

print(Place.databaseTableName) // prints "place"

For example:

Place: place
Country: country
PostalAddress: postalAddress
HTTPRequest: httpRequest
TOEFL: toefl

You can still provide a custom table name:

struct Place: TableRecord {
    static let databaseTableName = "location"
}

print(Place.databaseTableName) // prints "location"

When a type adopts both TableRecord and FetchableRecord, it can be fetched using the query interface:

// SELECT * FROM place WHERE name = 'Paris'
let paris = try Place.filter { $0.name == "Paris" }.fetchOne(db)

TableRecord can also fetch deal with primary and unique keys: see Fetching by Key and Testing for Record Existence.

PersistableRecord Protocol

📖 EncodableRecord, MutablePersistableRecord, PersistableRecord

GRDB record types can create, update, and delete rows in the database.

Those abilities are granted by three protocols:

// Defines how a record encodes itself into the database
protocol EncodableRecord {
    /// Defines the values persisted in the database
    func encode(to container: inout PersistenceContainer) throws
}

// Adds persistence methods
protocol MutablePersistableRecord: TableRecord, EncodableRecord {
    /// Optional method that lets your adopting type store its rowID upon
    /// successful insertion. Don't call it directly: it is called for you.
    mutating func didInsert(_ inserted: InsertionSuccess)
}

// Adds immutability
protocol PersistableRecord: MutablePersistableRecord {
    /// Non-mutating version of the optional didInsert(_:)
    func didInsert(_ inserted: InsertionSuccess)
}

Yes, three protocols instead of one. Here is how you pick one or the other:

If your type is a class, choose PersistableRecord. On top of that, implement didInsert(_:) if the database table has an auto-incremented primary key.
If your type is a struct, and the database table has an auto-incremented primary key, choose MutablePersistableRecord, and implement didInsert(_:).
Otherwise, choose PersistableRecord, and ignore didInsert(_:).

The encode(to:) method defines which values (Bool, Int, String, Date, Swift enums, etc.) are assigned to database columns.

The optional didInsert method lets the adopting type store its rowID after successful insertion, and is only useful for tables that have an auto-incremented primary key. It is called from a protected dispatch queue, and serialized with all database updates.

For example:

extension Place: MutablePersistableRecord {
    enum Columns {
        static let id = Column("id")
        static let title = Column("title")
        static let latitude = Column("latitude")
        static let longitude = Column("longitude")
    }
    
    /// The values persisted in the database
    func encode(to container: inout PersistenceContainer) {
        container[Columns.id] = id
        container[Columns.title] = title
        container[Columns.latitude] = coordinate.latitude
        container[Columns.longitude] = coordinate.longitude
    }
    
    // Update auto-incremented id upon successful insertion
    mutating func didInsert(_ inserted: InsertionSuccess) {
        id = inserted.rowID
    }
}

var paris = Place(
    id: nil,
    title: "Paris",
    coordinate: CLLocationCoordinate2D(latitude: 48.8534100, longitude: 2.3488000))

try paris.insert(db)
paris.id   // some value

When your record type adopts the standard Encodable protocol, you don't have to provide the implementation for encode(to:). See Codable Records for more information:

// That's all
struct Player: Encodable, MutablePersistableRecord {
    var id: Int64?
    var name: String
    var score: Int
    
    enum Columns {
        static let id = Column(CodingKeys.id)
        static let name = Column(CodingKeys.name)
        static let score = Column(CodingKeys.score)
    }
    
    // Update auto-incremented id upon successful insertion
    mutating func didInsert(_ inserted: InsertionSuccess) {
        id = inserted.rowID
    }
}

Persistence Methods

Types that adopt the PersistableRecord protocol are given methods that insert, update, and delete:

// INSERT
try place.insert(db)
let insertedPlace = try place.inserted(db) // non-mutating

// UPDATE
try place.update(db)
try place.update(db, columns: ["title"])

// Maybe UPDATE
try place.updateChanges(db, from: otherPlace)
try place.updateChanges(db) { $0.isFavorite = true }

// INSERT or UPDATE
try place.save(db)
let savedPlace = place.saved(db) // non-mutating

// UPSERT
try place.upsert(db)
let insertedPlace = place.upsertAndFetch(db)

// DELETE
try place.delete(db)

// EXISTENCE CHECK
let exists = try place.exists(db)

See Upsert below for more information about upserts.

The TableRecord protocol comes with batch operations:

// UPDATE
try Place.updateAll(db, ...)

// DELETE
try Place.deleteAll(db)
try Place.deleteAll(db, ids:...)
try Place.deleteAll(db, keys:...)
try Place.deleteOne(db, id:...)
try Place.deleteOne(db, key:...)

For more information about batch updates, see Update Requests.

All persistence methods can throw a DatabaseError.
update and updateChanges throw RecordError if the database does not contain any row for the primary key of the record.
save makes sure your values are stored in the database. It performs an UPDATE if the record has a non-null primary key, and then, if no row was modified, an INSERT. It directly performs an INSERT if the record has no primary key, or a null primary key.
delete and deleteOne returns whether a database row was deleted or not. deleteAll returns the number of deleted rows. updateAll returns the number of updated rows. updateChanges returns whether a database row was updated or not.

All primary keys are supported, including composite primary keys that span several columns, and the hidden rowid column.

To customize persistence methods, you provide Persistence Callbacks, described below. Do not attempt at overriding the ready-made persistence methods.

Upsert

UPSERT is an SQLite feature that causes an INSERT to behave as an UPDATE or a no-op if the INSERT would violate a uniqueness constraint (primary key or unique index).

Note: Upsert apis are available from SQLite 3.35.0+: iOS 15.0+, macOS 12.0+, tvOS 15.0+, watchOS 8.0+, or with a custom SQLite build or SQLCipher.

Note: With regard to persistence callbacks, an upsert behaves exactly like an insert. In particular: the aroundInsert(_:) and didInsert(_:) callbacks reports the rowid of the inserted or updated row; willUpdate, aroundUpdate, didUpdate are not called.

PersistableRecord provides three upsert methods:

upsert(_:)

Inserts or updates a record.

The upsert behavior is triggered by a violation of any uniqueness constraint on the table (primary key or unique index). In case of conflict, all columns but the primary key are overwritten with the inserted values:

struct Player: Encodable, PersistableRecord {
    var id: Int64
    var name: String
    var score: Int
}

// INSERT INTO player (id, name, score)
// VALUES (1, 'Arthur', 1000)
// ON CONFLICT DO UPDATE SET
//   name = excluded.name,
//   score = excluded.score
let player = Player(id: 1, name: "Arthur", score: 1000)
try player.upsert(db)

upsertAndFetch(_:onConflict:updating:doUpdate:) (requires FetchableRecord conformance)

Inserts or updates a record, and returns the upserted record.

The onConflict and doUpdate arguments let you further control the upsert behavior. Make sure you check the SQLite UPSERT documentation for detailed information.
- onConflict: the "conflict target" is the array of columns in the uniqueness constraint (primary key or unique index) that triggers the upsert.
  
  If empty (the default), all uniqueness constraint are considered.
- doUpdate: a closure that returns columns assignments to perform in case of conflict. Depending on the options parameter, other columns are overwritten with the inserted values, or not.
  
  By default, all inserted columns but the primary key and the conflict target are overwritten.
In the example below, we upsert the new vocabulary word "jovial". It is inserted if that word is not already in the dictionary. Otherwise, count is incremented, isTainted is not overwritten, and kind is overwritten:
```
// CREATE TABLE vocabulary(
//   word TEXT NOT NULL PRIMARY KEY,
//   kind TEXT NOT NULL,
//   isTainted BOOLEAN DEFAULT 0,
//   count INT DEFAULT 1))
struct Vocabulary: Encodable, PersistableRecord {
    var word: String
    var kind: String
    var isTainted: Bool
}

// INSERT INTO vocabulary(word, kind, isTainted)
// VALUES('jovial', 'adjective', 0)
// ON CONFLICT(word) DO UPDATE SET \
//   count = count + 1,   -- on conflict, count is incremented
//   kind = excluded.kind -- on conflict, kind is overwritten
// RETURNING *
let vocabulary = Vocabulary(word: "jovial", kind: "adjective", isTainted: false)
let upserted = try vocabulary.upsertAndFetch(
    db, onConflict: ["word"],
    doUpdate: { _ in
        [Column("count") += 1,            // on conflict, count is incremented
         Column("isTainted").noOverwrite] // on conflict, isTainted is NOT overwritten
    })
```
The doUpdate closure accepts an excluded TableAlias argument that refers to the inserted values that trigger the conflict. You can use it to specify an explicit overwrite, or to perform a computation. In the next example, the upsert keeps the maximum date in case of conflict:
```
// INSERT INTO message(id, text, date)
// VALUES(...)
// ON CONFLICT DO UPDATE SET \
//   text = excluded.text,
//   date = MAX(date, excluded.date)
// RETURNING *
let upserted = try message.upsertAndFetch(doUpdate: { excluded in
    // keep the maximum date in case of conflict
    [Column("date").set(to: max(Column("date"), excluded["date"]))]
})
```
upsertAndFetch(_:as:onConflict:updating:doUpdate:) (does not require FetchableRecord conformance)

This method is identical to upsertAndFetch(_:onConflict:updating:doUpdate:) described above, but you can provide a distinct FetchableRecord record type as a result, in order to specify the returned columns.

Persistence Methods and the `RETURNING` clause

SQLite is able to return values from a inserted, updated, or deleted row, with the RETURNING clause.

Note: Support for the RETURNING clause is available from SQLite 3.35.0+: iOS 15.0+, macOS 12.0+, tvOS 15.0+, watchOS 8.0+, or with a custom SQLite build or SQLCipher.

The RETURNING clause helps dealing with database features such as auto-incremented ids, default values, and generated columns. You can, for example, insert a few columns and fetch the default or generated ones in one step.

GRDB uses the RETURNING clause in all persistence methods that contain AndFetch in their name.

For example, given a database table with an auto-incremented primary key and a default score:

try dbQueue.write { db in
    try db.execute(sql: """
        CREATE TABLE player(
          id INTEGER PRIMARY KEY AUTOINCREMENT,
          name TEXT NOT NULL,
          score INTEGER NOT NULL DEFAULT 1000)
        """)
}

You can define a record type with full database information, and another partial record type that deals with a subset of columns:

// A player with full database information
struct Player: Codable, PersistableRecord, FetchableRecord {
    var id: Int64
    var name: String
    var score: Int
    
    enum Columns {
        static let id = Column(CodingKeys.id)
        static let name = Column(CodingKeys.name)
        static let score = Column(CodingKeys.score)
    }
}

// A partial player
struct PartialPlayer: Encodable, PersistableRecord {
    static let databaseTableName = "player"
    var name: String
    
    typealias Columns = Player.Columns
}

And now you can get a full player by inserting a partial one:

try dbQueue.write { db in
    let partialPlayer = PartialPlayer(name: "Alice")
    
    // INSERT INTO player (name) VALUES ('Alice') RETURNING *
    let player = try partialPlayer.insertAndFetch(db, as: Player.self)
    print(player.id)    // The inserted id
    print(player.name)  // The inserted name
    print(player.score) // The default score
}

For extra precision, you can select only the columns you need, and fetch the desired value from the provided prepared Statement:

try dbQueue.write { db in
    let partialPlayer = PartialPlayer(name: "Alice")
    
    // INSERT INTO player (name) VALUES ('Alice') RETURNING score
    let score = try partialPlayer.insertAndFetch(db) { statement in
        try Int.fetchOne(statement)
    } select: {
        [$0.score]
    }
    print(score) // Prints 1000, the default score
}

There are other similar persistence methods, such as upsertAndFetch, saveAndFetch, updateAndFetch, updateChangesAndFetch, etc. They all behave like upsert, save, update, updateChanges, except that they return saved values. For example:

// Save and return the saved player
let savedPlayer = try player.saveAndFetch(db)

See Persistence Methods, Upsert, and updateChanges methods for more information.

Batch operations can return updated or deleted values:

Warning: Make sure you check the documentation of the RETURNING clause, which describes important limitations and caveats for batch operations.

let request = Player.filter(...)...

// Fetch all deleted players
// DELETE FROM player RETURNING *
let deletedPlayers = try request.deleteAndFetchAll(db) // [Player]

// Fetch a selection of columns from the deleted rows
// DELETE FROM player RETURNING name
let statement = try request.deleteAndFetchStatement(db) { [$0.name] }
let deletedNames = try String.fetchSet(statement)

// Fetch all updated players
// UPDATE player SET score = score + 10 RETURNING *
let updatedPlayers = try request.updateAndFetchAll(db) { [$0.score += 10] } // [Player]

// Fetch a selection of columns from the updated rows
// UPDATE player SET score = score + 10 RETURNING score
let statement = try request.updateAndFetchStatement(db) {
    [$0.score += 10]
} select: {
    [$0.score]
}
let updatedScores = try Int.fetchAll(statement)

Persistence Callbacks

Your custom type may want to perform extra work when the persistence methods are invoked.

To this end, your record type can implement persistence callbacks. Callbacks are methods that get called at certain moments of a record's life cycle. With callbacks it is possible to write code that will run whenever an record is inserted, updated, or deleted.

In order to use a callback method, you need to provide its implementation. For example, a frequently used callback is didInsert, in the case of auto-incremented database ids:

struct Player: MutablePersistableRecord {
    var id: Int64?
    
    // Update auto-incremented id upon successful insertion
    mutating func didInsert(_ inserted: InsertionSuccess) {
        id = inserted.rowID
    }
}

try dbQueue.write { db in
    var player = Player(id: nil, ...)
    try player.insert(db)
    print(player.id) // didInsert was called: prints some non-nil id
}

Callbacks can also help implementing record validation:

struct Link: PersistableRecord {
    var url: URL
    
    func willSave(_ db: Database) throws {
        if url.host == nil {
            throw ValidationError("url must be absolute.")
        }
    }
}

try link.insert(db) // Calls the willSave callback
try link.update(db) // Calls the willSave callback
try link.save(db)   // Calls the willSave callback
try link.upsert(db) // Calls the willSave callback

Available Callbacks

Here is a list with all the available persistence callbacks, listed in the same order in which they will get called during the respective operations:

Inserting a record (all record.insert and record.upsert methods)
- willSave
- aroundSave
- willInsert
- aroundInsert
- didInsert
- didSave
Updating a record (all record.update methods)
- willSave
- aroundSave
- willUpdate
- aroundUpdate
- didUpdate
- didSave
Deleting a record (only the record.delete(_:) method)
- willDelete
- aroundDelete
- didDelete

For detailed information about each callback, check the reference.

In the MutablePersistableRecord protocol, willInsert and didInsert are mutating methods. In PersistableRecord, they are not mutating.

Note: The record.save(_:) method performs an UPDATE if the record has a non-null primary key, and then, if no row was modified, an INSERT. It directly performs an INSERT if the record has no primary key, or a null primary key. It triggers update and/or insert callbacks accordingly.

Warning: Callbacks are only invoked from persistence methods called on record instances. Callbacks are not invoked when you call a type method, perform a batch operations, or execute raw SQL.

Warning: When a did*** callback is invoked, do not assume that the change is actually persisted on disk, because the database may still be inside an uncommitted transaction. When you need to handle transaction completions, use the afterNextTransaction(onCommit:onRollback:). For example:
struct PictureFile: PersistableRecord {
    var path: String
    
    func willDelete(_ db: Database) {
        db.afterNextTransaction { _ in
            try? deleteFileOnDisk()
        }
    }
}

Identifiable Records

When a record type maps a table with a single-column primary key, it is recommended to have it adopt the standard Identifiable protocol.

struct Player: Identifiable, FetchableRecord, PersistableRecord {
    var id: Int64 // fulfills the Identifiable requirement
    var name: String
    var score: Int
}

When id has a database-compatible type (Int64, Int, String, UUID, ...), the Identifiable conformance unlocks type-safe record and request methods:

let player = try Player.find(db, id: 1)               // Player
let player = try Player.fetchOne(db, id: 1)           // Player?
let players = try Player.fetchAll(db, ids: [1, 2, 3]) // [Player]
let players = try Player.fetchSet(db, ids: [1, 2, 3]) // Set<Player>

let request = Player.filter(id: 1)
let request = Player.filter(ids: [1, 2, 3])

try Player.deleteOne(db, id: 1)
try Player.deleteAll(db, ids: [1, 2, 3])

Note: Not all record types can be made Identifiable, and not all tables have a single-column primary key. GRDB provides other methods that deal with primary and unique keys, but they won't check the type of their arguments:
// Available on non-Identifiable types
try Player.fetchOne(db, key: 1)
try Player.fetchOne(db, key: ["email": "arthur@example.com"])
try Country.fetchAll(db, keys: ["FR", "US"])
try Citizenship.fetchOne(db, key: ["citizenId": 1, "countryCode": "FR"])

let request = Player.filter(key: 1)
let request = Player.filter(keys: [1, 2, 3])

try Player.deleteOne(db, key: 1)
try Player.deleteAll(db, keys: [1, 2, 3])

Note: It is not recommended to use Identifiable on record types that use an auto-incremented primary key:

// AVOID declaring Identifiable conformance when key is auto-incremented
struct Player {
    var id: Int64? // Not an id suitable for Identifiable
    var name: String
    var score: Int
}

extension Player: FetchableRecord, MutablePersistableRecord {
    // Update auto-incremented id upon successful insertion
    mutating func didInsert(_ inserted: InsertionSuccess) {
        id = inserted.rowID
    }
}

For a detailed rationale, please see issue #1435.

Some database tables have a single-column primary key which is not called "id":

try db.create(table: "country") { t in
    t.primaryKey("isoCode", .text)
    t.column("name", .text).notNull()
    t.column("population", .integer).notNull()
}

In this case, Identifiable conformance can be achieved, for example, by returning the primary key column from the id property:

struct Country: Identifiable, FetchableRecord, PersistableRecord {
    var isoCode: String
    var name: String
    var population: Int
    
    // Fulfill the Identifiable requirement
    var id: String { isoCode }
}

let france = try dbQueue.read { db in
    try Country.fetchOne(db, id: "FR")
}

Codable Records

Record types that adopt an archival protocol (Codable, Encodable or Decodable) get free database support just by declaring conformance to the desired record protocols:

// Declare a record...
struct Player: Codable, FetchableRecord, PersistableRecord {
    var id: Int64
    var name: String
    var score: Int
    
    enum Columns {
        static let id = Column(CodingKeys.id)
        static let name = Column(CodingKeys.name)
        static let score = Column(CodingKeys.score)
    }
}

// ...and there you go:
try dbQueue.write { db in
    try Player(id: 1, name: "Arthur", score: 100).insert(db)
    let players = try Player.order(\.score.desc).fetchAll(db)
}

Codable records encode and decode their properties according to their own implementation of the Encodable and Decodable protocols. Yet databases have specific requirements:

Properties are always coded according to their preferred database representation, when they have one (all values that adopt the DatabaseValueConvertible protocol).
You can customize the encoding and decoding of dates and uuids.
Complex properties (arrays, dictionaries, nested structs, etc.) are stored as JSON.

For more information about Codable records, see:

💡 Tip: see the Demo Applications for sample code that uses Codable records.

JSON Columns

When a Codable record contains a property that is not a simple value (Bool, Int, String, Date, Swift enums, etc.), that value is encoded and decoded as a JSON string. For example:

enum AchievementColor: String, Codable {
    case bronze, silver, gold
}

struct Achievement: Codable {
    var name: String
    var color: AchievementColor
}

struct Player: Codable, FetchableRecord, PersistableRecord {
    var name: String
    var score: Int
    var achievements: [Achievement] // stored in a JSON column
}

try dbQueue.write { db in
    // INSERT INTO player (name, score, achievements)
    // VALUES (
    //   'Arthur',
    //   100,
    //   '[{"color":"gold","name":"Use Codable Records"}]')
    let achievement = Achievement(name: "Use Codable Records", color: .gold)
    let player = Player(name: "Arthur", score: 100, achievements: [achievement])
    try player.insert(db)
}

GRDB uses the standard JSONDecoder and JSONEncoder from Foundation. By default, Data values are handled with the .base64 strategy, Date with the .millisecondsSince1970 strategy, and non conforming floats with the .throw strategy.

You can customize the JSON format by implementing those methods:

protocol FetchableRecord {
    static func databaseJSONDecoder(for column: String) -> JSONDecoder
}

protocol EncodableRecord {
    static func databaseJSONEncoder(for column: String) -> JSONEncoder
}

💡 Tip: Make sure you set the JSONEncoder sortedKeys option. This option makes sure that the JSON output is stable. This stability is required for Record Comparison to work as expected, and database observation tools such as ValueObservation to accurately recognize changed records.

Column Names Coding Strategies

By default, Codable Records store their values into database columns that match their coding keys: the teamID property is stored into the teamID column.

This behavior can be overridden, so that you can, for example, store the teamID property into the team_id column:

protocol FetchableRecord {
    static var databaseColumnDecodingStrategy: DatabaseColumnDecodingStrategy { get }
}

protocol EncodableRecord {
    static var databaseColumnEncodingStrategy: DatabaseColumnEncodingStrategy { get }
}

See DatabaseColumnDecodingStrategy and DatabaseColumnEncodingStrategy to learn about all available strategies.

Data, Date, and UUID Coding Strategies

By default, Codable Records encode and decode their Data properties as blobs, and Date and UUID properties as described in the general Date and DateComponents and UUID chapters.

To sum up: dates encode themselves in the "YYYY-MM-DD HH:MM:SS.SSS" format, in the UTC time zone, and decode a variety of date formats and timestamps. UUIDs encode themselves as 16-bytes data blobs, and decode both 16-bytes data blobs and strings such as "E621E1F8-C36C-495A-93FC-0C247A3E6E5F".

Those behaviors can be overridden:

protocol FetchableRecord {
    static func databaseDataDecodingStrategy(for column: String) -> DatabaseDataDecodingStrategy
    static func databaseDateDecodingStrategy(for column: String) -> DatabaseDateDecodingStrategy
}

protocol EncodableRecord {
    static func databaseDataEncodingStrategy(for column: String) -> DatabaseDataEncodingStrategy
    static func databaseDateEncodingStrategy(for column: String) -> DatabaseDateEncodingStrategy
    static func databaseUUIDEncodingStrategy(for column: String) -> DatabaseUUIDEncodingStrategy
}

See DatabaseDataDecodingStrategy, DatabaseDateDecodingStrategy, DatabaseDataEncodingStrategy, DatabaseDateEncodingStrategy, and DatabaseUUIDEncodingStrategy to learn about all available strategies.

There is no customization of uuid decoding, because UUID can already decode all its encoded variants (16-bytes blobs and uuid strings, both uppercase and lowercase).

Customized coding strategies apply:

When encoding and decoding database rows to and from records (fetching and persistence methods).
In requests by single-column primary key: fetchOne(_🆔), filter(id:), deleteAll(_:keys:), etc.

They do not apply in other requests based on data, date, or uuid values.

So make sure that those are properly encoded in your requests. For example:

struct Player: Codable, FetchableRecord, PersistableRecord, Identifiable {
    // UUIDs are stored as strings
    static func databaseUUIDEncodingStrategy(for column: String) -> DatabaseUUIDEncodingStrategy {
        .uppercaseString
    }
    
    var id: UUID
    ...
}

try dbQueue.write { db in
    let uuid = UUID()
    let player = Player(id: uuid, ...)
    
    // OK: inserts a player in the database, with a string uuid
    try player.insert(db)
    
    // OK: performs a string-based query, finds the inserted player
    _ = try Player.filter(id: uuid).fetchOne(db)

    // NOT OK: performs a blob-based query, fails to find the inserted player
    _ = try Player.filter { $0.id == uuid }.fetchOne(db)
    
    // OK: performs a string-based query, finds the inserted player
    _ = try Player.filter { $0.id == uuid.uuidString }.fetchOne(db)
}

The userInfo Dictionary

Your Codable Records can be stored in the database, but they may also have other purposes. In this case, you may need to customize their implementations of Decodable.init(from:) and Encodable.encode(to:), depending on the context.

The standard way to provide such context is the userInfo dictionary. Implement those properties:

protocol FetchableRecord {
    static var databaseDecodingUserInfo: [CodingUserInfoKey: Any] { get }
}

protocol EncodableRecord {
    static var databaseEncodingUserInfo: [CodingUserInfoKey: Any] { get }
}

For example, here is a Player type that customizes its decoding:

// A key that holds a decoder's name
let decoderName = CodingUserInfoKey(rawValue: "decoderName")!

struct Player: FetchableRecord, Decodable {
    init(from decoder: Decoder) throws {
        // Print the decoder name
        let decoderName = decoder.userInfo[decoderName] as? String
        print("Decoded from \(decoderName ?? "unknown decoder")")
        ...
    }
}

You can have a specific decoding from JSON...

// prints "Decoded from JSON"
let decoder = JSONDecoder()
decoder.userInfo = [decoderName: "JSON"]
let player = try decoder.decode(Player.self, from: jsonData)

... and another one from database rows:

extension Player: FetchableRecord {
    static var databaseDecodingUserInfo: [CodingUserInfoKey: Any] {
        [decoderName: "database row"]
    }
}

// prints "Decoded from database row"
let player = try Player.fetchOne(db, ...)

Note: make sure the databaseDecodingUserInfo and databaseEncodingUserInfo properties are explicitly declared as [CodingUserInfoKey: Any]. If they are not, the Swift compiler may silently miss the protocol requirement, resulting in sticky empty userInfo.

Tip: Derive Columns from Coding Keys

Codable types are granted with a CodingKeys enum. You can use them to safely define database columns:

struct Player: Codable {
    var id: Int64
    var name: String
    var score: Int
}

extension Player: FetchableRecord, PersistableRecord {
    enum Columns {
        static let id = Column(CodingKeys.id)
        static let name = Column(CodingKeys.name)
        static let score = Column(CodingKeys.score)
    }
}

See the query interface and Recommended Practices for Designing Record Types for further information.

Record Comparison

Records that adopt the EncodableRecord protocol can compare against other records, or against previous versions of themselves.

This helps avoiding costly UPDATE statements when a record has not been edited.

The `updateChanges` Methods

The updateChanges methods perform a database update of the changed columns only (and does nothing if record has no change).

updateChanges(_:from:)

This method lets you compare two records:

if let oldPlayer = try Player.fetchOne(db, id: 42) {
    var newPlayer = oldPlayer
    newPlayer.score = 100
    if try newPlayer.updateChanges(db, from: oldPlayer) {
        print("player was modified, and updated in the database")
    } else {
        print("player was not modified, and database was not hit")
    }
}

updateChanges(_:modify:)

This method lets you update a record in place:

if var player = try Player.fetchOne(db, id: 42) {
    let modified = try player.updateChanges(db) {
        $0.score = 100
    }
    if modified {
        print("player was modified, and updated in the database")
    } else {
        print("player was not modified, and database was not hit")
    }
}

The `databaseEquals` Method

This method returns whether two records have the same database representation:

let oldPlayer: Player = ...
var newPlayer: Player = ...
if newPlayer.databaseEquals(oldPlayer) == false {
    try newPlayer.save(db)
}

Note: The comparison is performed on the database representation of records. As long as your record type adopts the EncodableRecord protocol, you don't need to care about Equatable.

The `databaseChanges` and `hasDatabaseChanges` Methods

databaseChanges(from:) returns a dictionary of differences between two records:

let oldPlayer = Player(id: 1, name: "Arthur", score: 100)
let newPlayer = Player(id: 1, name: "Arthur", score: 1000)
for (column, oldValue) in try newPlayer.databaseChanges(from: oldPlayer) {
    print("\(column) was \(oldValue)")
}
// prints "score was 100"

For an efficient algorithm which synchronizes the content of a database table with a JSON payload, check groue/SortedDifference.

Record Customization Options

GRDB records come with many default behaviors, that are designed to fit most situations. Many of those defaults can be customized for your specific needs:

Persistence Callbacks: define what happens when you call a persistence method such as player.insert(db)
Conflict Resolution: Run INSERT OR REPLACE queries, and generally define what happens when a persistence method violates a unique index.
Columns Selected by a Request: define which columns are selected by requests such as Player.fetchAll(db).
Beyond FetchableRecord: the FetchableRecord protocol is not the end of the story.

Codable Records have a few extra options:

JSON Columns: control the format of JSON columns.
Column Names Coding Strategies: control how coding keys are turned into column names
[Date and UUID Coding Strategies]: control the format of Date and UUID properties in your Codable records.
The userInfo Dictionary: adapt your Codable implementation for the database.

Conflict Resolution

Insertions and updates can create conflicts: for example, a query may attempt to insert a duplicate row that violates a unique index.

Those conflicts normally end with an error. Yet SQLite let you alter the default behavior, and handle conflicts with specific policies. For example, the INSERT OR REPLACE statement handles conflicts with the "replace" policy which replaces the conflicting row instead of throwing an error.

The five different policies are: abort (the default), replace, rollback, fail, and ignore.

SQLite let you specify conflict policies at two different places:

In the definition of the database table:

// CREATE TABLE player (
//     id INTEGER PRIMARY KEY AUTOINCREMENT,
//     email TEXT UNIQUE ON CONFLICT REPLACE
// )
try db.create(table: "player") { t in
    t.autoIncrementedPrimaryKey("id")
    t.column("email", .text).unique(onConflict: .replace) // <--
}

// Despite the unique index on email, both inserts succeed.
// The second insert replaces the first row:
try db.execute(sql: "INSERT INTO player (email) VALUES (?)", arguments: ["arthur@example.com"])
try db.execute(sql: "INSERT INTO player (email) VALUES (?)", arguments: ["arthur@example.com"])

In each modification query:

// CREATE TABLE player (
//     id INTEGER PRIMARY KEY AUTOINCREMENT,
//     email TEXT UNIQUE
// )
try db.create(table: "player") { t in
    t.autoIncrementedPrimaryKey("id")
    t.column("email", .text).unique()
}

// Again, despite the unique index on email, both inserts succeed.
try db.execute(sql: "INSERT OR REPLACE INTO player (email) VALUES (?)", arguments: ["arthur@example.com"])
try db.execute(sql: "INSERT OR REPLACE INTO player (email) VALUES (?)", arguments: ["arthur@example.com"])

When you want to handle conflicts at the query level, specify a custom persistenceConflictPolicy in your type that adopts the PersistableRecord protocol. It will alter the INSERT and UPDATE queries run by the insert, update and save persistence methods:

protocol MutablePersistableRecord {
    /// The policy that handles SQLite conflicts when records are
    /// inserted or updated.
    ///
    /// This property is optional: its default value uses the ABORT
    /// policy for both insertions and updates, so that GRDB generate
    /// regular INSERT and UPDATE queries.
    static var persistenceConflictPolicy: PersistenceConflictPolicy { get }
}

struct Player : MutablePersistableRecord {
    static let persistenceConflictPolicy = PersistenceConflictPolicy(
        insert: .replace,
        update: .replace)
}

// INSERT OR REPLACE INTO player (...) VALUES (...)
try player.insert(db)

Note: If you specify the ignore policy for inserts, the didInsert callback will be called with some random id in case of failed insert. You can detect failed insertions with insertAndFetch:
// How to detect failed `INSERT OR IGNORE`:
// INSERT OR IGNORE INTO player ... RETURNING *
do {
    let insertedPlayer = try player.insertAndFetch(db) {
    // Successful insertion
catch RecordError.recordNotFound {
    // Failed insertion due to IGNORE policy
}
Note: The replace policy may have to delete rows so that inserts and updates can succeed. Those deletions are not reported to transaction observers (this might change in a future release of SQLite).

Beyond FetchableRecord

Some GRDB users eventually discover that the FetchableRecord protocol does not fit all situations. Use cases that are not well handled by FetchableRecord include:

Your application needs polymorphic row decoding: it decodes some type or another, depending on the values contained in a database row.
Your application needs to decode rows with a context: each decoded value should be initialized with some extra value that does not come from the database.

Since those use cases are not well handled by FetchableRecord, don't try to implement them on top of this protocol: you'll just fight the framework.

Examples of Record Definitions

We will show below how to declare a record type for the following database table:

try dbQueue.write { db in
    try db.create(table: "place") { t in
        t.autoIncrementedPrimaryKey("id")
        t.column("title", .text).notNull()
        t.column("isFavorite", .boolean).notNull().defaults(to: false)
        t.column("longitude", .double).notNull()
        t.column("latitude", .double).notNull()
    }
}

Each one of the three examples below is correct. You will pick one or the other depending on your personal preferences and the requirements of your application:

Define a Codable struct, and adopt the record protocols you need

This is the shortest way to define a record type.

See the Record Protocols Overview, and Codable Records for more information.

struct Place: Codable {
    var id: Int64?
    var title: String
    var isFavorite: Bool
    private var latitude: CLLocationDegrees
    private var longitude: CLLocationDegrees
    
    var coordinate: CLLocationCoordinate2D {
        get {
            CLLocationCoordinate2D(
                latitude: latitude,
                longitude: longitude)
        }
        set {
            latitude = newValue.latitude
            longitude = newValue.longitude
        }
    }
}

// SQL generation
extension Place: TableRecord {
    /// The table columns
    enum Columns {
        static let id = Column(CodingKeys.id)
        static let title = Column(CodingKeys.title)
        static let isFavorite = Column(CodingKeys.isFavorite)
        static let latitude = Column(CodingKeys.latitude)
        static let longitude = Column(CodingKeys.longitude)
    }
}

// Fetching methods
extension Place: FetchableRecord { }

// Persistence methods
extension Place: MutablePersistableRecord {
    // Update auto-incremented id upon successful insertion
    mutating func didInsert(_ inserted: InsertionSuccess) {
        id = inserted.rowID
    }
}

Define a plain struct, and adopt the record protocols you need

See the Record Protocols Overview for more information.

struct Place {
    var id: Int64?
    var title: String
    var isFavorite: Bool
    var coordinate: CLLocationCoordinate2D
}

// SQL generation
extension Place: TableRecord {
    /// The table columns
    enum Columns {
        static let id = Column("id")
        static let title = Column("title")
        static let isFavorite = Column("isFavorite")
        static let latitude = Column("latitude")
        static let longitude = Column("longitude")
    }
}

// Fetching methods
extension Place: FetchableRecord {
    /// Creates a record from a database row
    init(row: Row) {
        id = row[Columns.id]
        title = row[Columns.title]
        isFavorite = row[Columns.isFavorite]
        coordinate = CLLocationCoordinate2D(
            latitude: row[Columns.latitude],
            longitude: row[Columns.longitude])
    }
}

// Persistence methods
extension Place: MutablePersistableRecord {
    /// The values persisted in the database
    func encode(to container: inout PersistenceContainer) {
        container[Columns.id] = id
        container[Columns.title] = title
        container[Columns.isFavorite] = isFavorite
        container[Columns.latitude] = coordinate.latitude
        container[Columns.longitude] = coordinate.longitude
    }
    
    // Update auto-incremented id upon successful insertion
    mutating func didInsert(_ inserted: InsertionSuccess) {
        id = inserted.rowID
    }
}

Define a plain struct optimized for fetching performance

This struct derives its persistence methods from the standard Encodable protocol (see Codable Records), but performs optimized row decoding by accessing database columns with numeric indexes.

See the Record Protocols Overview for more information.

struct Place: Encodable {
    var id: Int64?
    var title: String
    var isFavorite: Bool
    private var latitude: CLLocationDegrees
    private var longitude: CLLocationDegrees
    
    var coordinate: CLLocationCoordinate2D {
        get {
            CLLocationCoordinate2D(
                latitude: latitude,
                longitude: longitude)
        }
        set {
            latitude = newValue.latitude
            longitude = newValue.longitude
        }
    }
}

// SQL generation
extension Place: TableRecord {
    /// The table columns
    enum Columns {
        static let id = Column(CodingKeys.id)
        static let title = Column(CodingKeys.title)
        static let isFavorite = Column(CodingKeys.isFavorite)
        static let latitude = Column(CodingKeys.latitude)
        static let longitude = Column(CodingKeys.longitude)
    }
    
    /// Arrange the selected columns and lock their order
    static var databaseSelection: [any SQLSelectable] {
        [
            Columns.id,
            Columns.title,
            Columns.favorite,
            Columns.latitude,
            Columns.longitude,
        ]
    }
}

// Fetching methods
extension Place: FetchableRecord {
    /// Creates a record from a database row
    init(row: Row) {
        // For high performance, use numeric indexes that match the
        // order of Place.databaseSelection
        id = row[0]
        title = row[1]
        isFavorite = row[2]
        coordinate = CLLocationCoordinate2D(
            latitude: row[3],
            longitude: row[4])
    }
}

// Persistence methods
extension Place: MutablePersistableRecord {
    // Update auto-incremented id upon successful insertion
    mutating func didInsert(_ inserted: InsertionSuccess) {
        id = inserted.rowID
    }
}

The Query Interface

The query interface lets you write pure Swift instead of SQL:

try dbQueue.write { db in
    // Update database schema
    try db.create(table: "player") { t in ... }
    
    // Fetch records
    let bestPlayers = try Player
        .order(\.score.desc)
        .limit(10)
        .fetchAll(db)
    
    // Count
    let count = try Player
        .filter { $0.score >= 1000 }
        .fetchCount(db)
    
    // Batch update
    try Player
        .filter { $0.team == "Reds" }
        .updateAll(db) { $0.score += 100 }
    
    // Batch delete
    try Player
        .filter { $0.score == 0 }
        .deleteAll(db)
}

You need to open a database connection before you can query the database.

Please bear in mind that the query interface can not generate all possible SQL queries. You may also prefer writing SQL, and this is just OK. From little snippets to full queries, your SQL skills are welcome:

try dbQueue.write { db in
    // Update database schema (with SQL)
    try db.execute(sql: "CREATE TABLE player (...)")
    
    // Fetch records (with SQL)
    let bestPlayers = try Player.fetchAll(db, sql: """
        SELECT * FROM player ORDER BY score DESC LIMIT 10
        """)
    
    // Count (with an SQL snippet)
    let minScore = 1000
    let count = try Player
        .filter(sql: "score >= ?", arguments: [minScore])
        .fetchCount(db)
    
    // Update (with SQL)
    try db.execute(sql: "UPDATE player SET score = score + 100 WHERE team = 'Reds'")
    
    // Delete (with SQL)
    try db.execute(sql: "DELETE FROM player WHERE score = 0")
}

So don't miss the SQL API.

Note: the generated SQL may change between GRDB releases, without notice: don't have your application rely on any specific SQL output.

Requests

📖 QueryInterfaceRequest, Table

The query interface requests let you fetch values from the database:

let request = Player.filter { $0.email != nil }.order(\.name)
let players = try request.fetchAll(db)  // [Player]
let count = try request.fetchCount(db)  // Int

Query interface requests usually start from a type that adopts the TableRecord protocol:

struct Player: TableRecord { ... }

// The request for all players:
let request = Player.all()
let players = try request.fetchAll(db) // [Player]

When you can not use a record type, use Table:

// The request for all rows from the player table:
let table = Table("player")
let request = table.all()
let rows = try request.fetchAll(db)    // [Row]

// The request for all players from the player table:
let table = Table<Player>("player")
let request = table.all()
let players = try request.fetchAll(db) // [Player]

Note: all examples in the documentation below use a record type, but you can always substitute a Table instead.

Next, declare the table columns that you want to use for filtering, or sorting, in a nested type named Columns:

extension Player {
    enum Columns {
        static let id = Column("id")
        static let name = Column("name")
    }
}

When Player is Codable, you'll prefer defining columns from coding keys:

extension Player {
    enum Columns {
        static let id = Column(CodingKeys.id)
        static let name = Column(CodingKeys.name)
    }
}

You can now build requests with the following methods: all, none, select, distinct, filter, matching, group, having, order, reversed, limit, joining, including, with. All those methods return another request, which you can further refine by applying another method: Player.select(...).filter(...).order(...).

all(), none(): the requests for all rows, or no row.
```
// SELECT * FROM player
Player.all()
```
By default, all columns are selected. See Columns Selected by a Request.
select(...) and select(..., as:) define the selected columns. See Columns Selected by a Request.
```
// SELECT name FROM player
Player.select(\.name, as: String.self)
```

selectID() is available on Identifiable Records. It supports all tables that have a single-column primary key:

// SELECT id FROM player
Player.selectID()

// SELECT id FROM player WHERE name IS NOT NULL
Player.filter { $0.name != nil }.selectID()

annotated(with: expression...) extends the selection.

// SELECT *, (score + bonus) AS total FROM player
Player.annotated { ($0.score + $0.bonus).forKey("total") }

annotated(with: aggregate) extends the selection with association aggregates.

// SELECT team.*, COUNT(DISTINCT player.id) AS playerCount
// FROM team
// LEFT JOIN player ON player.teamId = team.id
// GROUP BY team.id
Team.annotated(with: Team.players.count)

annotated(withRequired: association) and annotated(withOptional: association) extends the selection with Associations.

// SELECT player.*, team.color
// FROM player
// JOIN team ON team.id = player.teamId
Player.annotated(withRequired: Player.team.select(\.color))

distinct() performs uniquing.

// SELECT DISTINCT name FROM player
Player.select(\.name, as: String.self).distinct()

filter(expression) applies conditions.

// SELECT * FROM player WHERE id IN (1, 2, 3)
Player.filter { [1,2,3].contains($0.id) }

// SELECT * FROM player WHERE (name IS NOT NULL) AND (height > 1.75)
Player.filter { $0.name != nil && $0.height > 1.75 }

filter(id:) and filter(ids:) are type-safe methods available on Identifiable Records:

// SELECT * FROM player WHERE id = 1
Player.filter(id: 1)

// SELECT * FROM country WHERE isoCode IN ('FR', 'US')
Country.filter(ids: ["FR", "US"])

filter(key:) and filter(keys:) apply conditions on primary and unique keys:

// SELECT * FROM player WHERE id = 1
Player.filter(key: 1)

// SELECT * FROM country WHERE isoCode IN ('FR', 'US')
Country.filter(keys: ["FR", "US"])

// SELECT * FROM citizenship WHERE citizenId = 1 AND countryCode = 'FR'
Citizenship.filter(key: ["citizenId": 1, "countryCode": "FR"])

// SELECT * FROM player WHERE email = 'arthur@example.com'
Player.filter(key: ["email": "arthur@example.com"])

matching(pattern) (FTS3, FTS5) performs full-text search.

// SELECT * FROM document WHERE document MATCH 'sqlite database'
let pattern = FTS3Pattern(matchingAllTokensIn: "SQLite database")
Document.matching(pattern)

When the pattern is nil, no row will match.

group(expression, ...) groups rows.

// SELECT name, MAX(score) FROM player GROUP BY name
Player
    .select { [$0.name, max($0.score)] }
    .group(\.name)

having(expression) applies conditions on grouped rows.

// SELECT team, MAX(score) FROM player GROUP BY team HAVING MIN(score) >= 1000
Player
    .select { [$0.team, max($0.score)] }
    .group(\.team)
    .having { min($0.score) >= 1000 }

having(aggregate) applies conditions on grouped rows, according to an association aggregate.

// SELECT team.*
// FROM team
// LEFT JOIN player ON player.teamId = team.id
// GROUP BY team.id
// HAVING COUNT(DISTINCT player.id) >= 5
Team.having(Team.players.count >= 5)

order(ordering, ...) sorts.

// SELECT * FROM player ORDER BY name
Player.order(\.name)

// SELECT * FROM player ORDER BY score DESC
Player.order(\.score.desc)

// SELECT * FROM player ORDER BY score DESC, name
Player.order { [$0.score.desc, $0.name] }

SQLite considers NULL values to be smaller than any other values for sorting purposes. Hence, NULLs naturally appear at the beginning of an ascending ordering and at the end of a descending ordering. With a custom SQLite build, this can be changed using .ascNullsLast and .descNullsFirst:

// SELECT * FROM player ORDER BY score ASC NULLS LAST
Player.order(\.name.ascNullsLast)

Each order call clears any previous ordering:

// SELECT * FROM player ORDER BY name
Player.order(\.score).order(\.name)

reversed() reverses the eventual orderings.

// SELECT * FROM player ORDER BY score ASC, name DESC
Player.order { [$0.score.desc, $0.name] }.reversed()

If no ordering was already specified, this method has no effect:

// SELECT * FROM player
Player.all().reversed()

limit(limit, offset: offset) limits and pages results.

// SELECT * FROM player LIMIT 5
Player.limit(5)

// SELECT * FROM player LIMIT 5 OFFSET 10
Player.limit(5, offset: 10)

joining(required:), joining(optional:), including(required:), including(optional:), and including(all:) fetch and join records through Associations.
```
// SELECT player.*, team.*
// FROM player
// JOIN team ON team.id = player.teamId
Player.including(required: Player.team)
```

with(cte) embeds a common table expression:

// WITH ... SELECT * FROM player
let cte = CommonTableExpression(...)
Player.with(cte)

Other requests that involve the primary key:

selectPrimaryKey(as:) selects the primary key.

// SELECT id FROM player
Player.selectPrimaryKey(as: Int64.self)    // QueryInterfaceRequest<Int64>

// SELECT code FROM country
Country.selectPrimaryKey(as: String.self)  // QueryInterfaceRequest<String>

// SELECT citizenId, countryCode FROM citizenship
Citizenship.selectPrimaryKey(as: Row.self) // QueryInterfaceRequest<Row>

orderByPrimaryKey() sorts by primary key.

// SELECT * FROM player ORDER BY id
Player.orderByPrimaryKey()

// SELECT * FROM country ORDER BY code
Country.orderByPrimaryKey()

// SELECT * FROM citizenship ORDER BY citizenId, countryCode
Citizenship.orderByPrimaryKey()

groupByPrimaryKey() groups rows by primary key.

You can refine requests by chaining those methods:

// SELECT * FROM player WHERE (email IS NOT NULL) ORDER BY name
Player.order(\.name).filter { $0.email != nil }

The select, order, group, and limit methods ignore and replace previously applied selection, orderings, grouping, and limits. On the opposite, filter, matching, and having methods extend the query:

Player                          // SELECT * FROM player
    .filter { $0.name != nil }  // WHERE (name IS NOT NULL)
    .filter { $0.email != nil } //        AND (email IS NOT NULL)
    .order(\.name)              // - ignored -
    .reversed()                 // - ignored -
    .order(\.score)             // ORDER BY score
    .limit(20, offset: 40)      // - ignored -
    .limit(10)                  // LIMIT 10

Raw SQL snippets are also accepted, with eventual arguments:

// SELECT DATE(creationDate), COUNT(*) FROM player WHERE name = 'Arthur' GROUP BY date(creationDate)
Player
    .select(sql: "DATE(creationDate), COUNT(*)")
    .filter(sql: "name = ?", arguments: ["Arthur"])
    .group(sql: "DATE(creationDate)")

Columns Selected by a Request

By default, query interface requests select all columns:

// SELECT * FROM player
struct Player: TableRecord { ... }
let request = Player.all()

// SELECT * FROM player
let table = Table("player")
let request = table.all()

The selection can be changed for each individual requests, or in the case of record-based requests, for all requests built from this record type.

The select(...) and select(..., as:) methods change the selection of a single request (see Fetching from Requests for detailed information):

let request = Player.select { max($0.score) }
let maxScore = try Int.fetchOne(db, request) // Int?

let request = Player.select({ max($0.score) }, as: Int.self)
let maxScore = try request.fetchOne(db)      // Int?

The default selection for a record type is controlled by the databaseSelection property. For example:

// Select a limited set of columns
struct RestrictedPlayer: TableRecord {
    static let databaseTableName = "player"
    
    enum Columns {
        static let id = Column("id")
        static let name = Column("name")
    }
    
    static var databaseSelection: [any SQLSelectable] {
        [Columns.id, Columns.name]
    }
}

// SELECT id, name FROM player
let request = RestrictedPlayer.all()

// Select all but a few columns
struct Player : TableRecord {
    static var databaseSelection: [any SQLSelectable] { 
        [.allColumns(excluding: ["generatedColumn"])]
    }
}

// SELECT id, name FROM player
let request = RestrictedPlayer.all()

// Select all columns and more
struct ExtendedPlayer : TableRecord {
    static let databaseTableName = "player"
    static var databaseSelection: [any SQLSelectable] {
        [.allColumns, .rowID]
    }
}

// SELECT *, rowid FROM player
let request = ExtendedPlayer.all()

Note: make sure the databaseSelection property is explicitly declared as [any SQLSelectable]. If it is not, the Swift compiler may silently miss the protocol requirement, resulting in sticky SELECT * requests. To verify your setup, see the How do I print a request as SQL? FAQ.

Expressions

Feed requests with SQL expressions built from your Swift code:

SQL Operators

📖 SQLSpecificExpressible

GRDB comes with a Swift version of many SQLite built-in operators, listed below. But not all: see Embedding SQL in Query Interface Requests for a way to add support for missing SQL operators.

=, <>, <, <=, >, >=, IS, IS NOT

Comparison operators are based on the Swift operators ==, !=, ===, !==, <, <=, >, >=:

// SELECT * FROM player WHERE (name = 'Arthur')
Player.filter { $0.name == "Arthur" }

// SELECT * FROM player WHERE (name IS NULL)
Player.filter { $0.name == nil }

// SELECT * FROM player WHERE (score IS 1000)
Player.filter { $0.score === 1000 }

// SELECT * FROM rectangle WHERE width < height
Rectangle.filter { $0.width < $0.height }

Subqueries are supported:

// SELECT * FROM player WHERE score = (SELECT max(score) FROM player)
let maximumScore = Player.select { max($0.score) }
Player.filter { $0.score == maximumScore }

// SELECT * FROM player WHERE score = (SELECT max(score) FROM player)
let maximumScore = SQLRequest("SELECT max(score) FROM player")
Player.filter { $0.score == maximumScore }

Note: SQLite string comparison, by default, is case-sensitive and not Unicode-aware. See string comparison if you need more control.

*, /, +, -

SQLite arithmetic operators are derived from their Swift equivalent:
```
// SELECT ((temperature * 1.8) + 32) AS fahrenheit FROM planet
Planet.select { ($0.temperature * 1.8 + 32).forKey("fahrenheit") }
```
Note: an expression like nameColumn + "rrr" will be interpreted by SQLite as a numerical addition (with funny results), not as a string concatenation. See the concat operator below.

When you want to join a sequence of expressions with the + or * operator, use joined(operator:):
```
// SELECT score + bonus + 1000 FROM player
Player.select {
    [$0.score, $0.bonus, 1000.databaseValue].joined(operator: .add)
}
```
Note in the example above how you concatenate raw values: 1000.databaseValue. A plain 1000 would not compile.

When the sequence is empty, joined(operator: .add) returns 0, and joined(operator: .multiply) returns 1.
&, |, ~, <<, >>

Bitwise operations (bitwise and, or, not, left shift, right shift) are derived from their Swift equivalent:
```
// SELECT mask & 2 AS isRocky FROM planet
Planet.select { ($0.mask & 2).forKey("isRocky") }
```
||

Concatenate several strings:
```
// SELECT firstName || ' ' || lastName FROM player
Player.select {
    [$0.firstName, " ".databaseValue, $0.lastName].joined(operator: .concat)
}
```
Note in the example above how you concatenate raw strings: " ".databaseValue. A plain " " would not compile.

When the sequence is empty, joined(operator: .concat) returns the empty string.

AND, OR, NOT

The SQL logical operators are derived from the Swift &&, || and !:

// SELECT * FROM player WHERE ((NOT isVerified) OR (score < 1000))
Player.filter { !$0.isVerified || $0.score < 1000 }

When you want to join a sequence of expressions with the AND or OR operator, use joined(operator:):

// SELECT * FROM player WHERE (isVerified AND (score >= 1000) AND (name IS NOT NULL))
Player.filter {
    [$0.isVerified, $0.score >= 1000, $0.name != nil].joined(operator: .and)
}

When the sequence is empty, joined(operator: .and) returns true, and joined(operator: .or) returns false:

BETWEEN, IN, NOT IN

To check inclusion in a Swift sequence (array, set, range…), call the contains method:

// SELECT * FROM player WHERE id IN (1, 2, 3)
Player.filter { [1, 2, 3].contains($0.id) }

// SELECT * FROM player WHERE id NOT IN (1, 2, 3)
Player.filter { ![1, 2, 3].contains($0.id) }

// SELECT * FROM player WHERE score BETWEEN 0 AND 1000
Player.filter { (0...1000).contains($0.score) }

// SELECT * FROM player WHERE (score >= 0) AND (score < 1000)
Player.filter { (0..<1000).contains($0.score) }

// SELECT * FROM player WHERE initial BETWEEN 'A' AND 'N'
Player.filter { ("A"..."N").contains($0.initial) }

// SELECT * FROM player WHERE (initial >= 'A') AND (initial < 'N')
Player.filter { ("A"..<"N").contains($0.initial) }

To check inclusion inside a subquery, call the contains method as well:

// SELECT * FROM player WHERE id IN (SELECT playerId FROM playerSelection)
let selectedPlayerIds = PlayerSelection.select(\.playerId)
Player.filter { selectedPlayerIds.contains($0.id) }

// SELECT * FROM player WHERE id IN (SELECT playerId FROM playerSelection)
let selectedPlayerIds = SQLRequest("SELECT playerId FROM playerSelection")
Player.filter { selectedPlayerIds.contains($0.id) }

To check inclusion inside a common table expression, call the contains method as well:

// WITH selectedName AS (...)
// SELECT * FROM player WHERE name IN selectedName
let cte = CommonTableExpression(named: "selectedName", ...)
Player
    .with(cte)
    .filter { cte.contains($0.name) }

Note: SQLite string comparison, by default, is case-sensitive and not Unicode-aware. See string comparison if you need more control.

EXISTS, NOT EXISTS

To check if a subquery would return rows, call the exists method:

// Teams that have at least one other player
//
//  SELECT * FROM team
//  WHERE EXISTS (SELECT * FROM player WHERE teamId = team.id)
let teamAlias = TableAlias<Team>()
let player = Player.filter { $0.teamId == teamAlias.id }
let teams = Team.aliased(teamAlias).filter(player.exists())

// Teams that have no player
//
//  SELECT * FROM team
//  WHERE NOT EXISTS (SELECT * FROM player WHERE teamId = team.id)
let teams = Team.aliased(teamAlias).filter(!player.exists())

In the above example, you use a TableAlias in order to let a subquery refer to a column from another table.

In the next example, which involves the same table twice, the table alias requires an explicit disambiguation with TableAlias(name:):

// Players who coach at least one other player
//
//  SELECT coach.* FROM player coach
//  WHERE EXISTS (SELECT * FROM player WHERE coachId = coach.id)
let coachAlias = TableAlias<Player>(name: "coach")
let coachedPlayer = Player.filter { $0.coachId == coachAlias.id }
let coaches = Player.aliased(coachAlias).filter(coachedPlayer.exists())

Finally, subqueries can also be expressed as SQL, with SQL Interpolation:

// SELECT coach.* FROM player coach
// WHERE EXISTS (SELECT * FROM player WHERE coachId = coach.id)
let coachedPlayer = SQLRequest("SELECT * FROM player WHERE coachId = \(coachAlias.id)")
let coaches = Player.aliased(coachAlias).filter(coachedPlayer.exists())

LIKE

The SQLite LIKE operator is available as the like method:

// SELECT * FROM player WHERE (email LIKE '%@example.com')
Player.filter { $0.email.like("%@example.com") }

// SELECT * FROM book WHERE (title LIKE '%10\%%' ESCAPE '\')
Player.filter { $0.email.like("%10\\%%", escape: "\\") }

Note: the SQLite LIKE operator is case-insensitive but not Unicode-aware. For example, the expression 'a' LIKE 'A' is true but 'æ' LIKE 'Æ' is false.

MATCH

The full-text MATCH operator is available through FTS3Pattern (for FTS3 and FTS4 tables) and FTS5Pattern (for FTS5):

FTS3 and FTS4:

let pattern = FTS3Pattern(matchingAllTokensIn: "SQLite database")

// SELECT * FROM document WHERE document MATCH 'sqlite database'
Document.matching(pattern)

// SELECT * FROM document WHERE content MATCH 'sqlite database'
Document.filter { $0.content.match(pattern) }

FTS5:

let pattern = FTS5Pattern(matchingAllTokensIn: "SQLite database")

// SELECT * FROM document WHERE document MATCH 'sqlite database'
Document.matching(pattern)

AS

To give an alias to an expression, use the forKey method:
```
// SELECT (score + bonus) AS total
// FROM player
Player.select { ($0.score + $0.bonus).forKey("total") }
```
If you need to refer to this aliased column in another place of the request, use a detached column:
```
// SELECT (score + bonus) AS total
// FROM player 
// ORDER BY total
Player
    .select { ($0.score + $0.bonus).forKey("total") }
    .order(Column("total").detached)
```
The detached column Column("total").detached is not considered as a part of the "player" table, so it is always rendered as total in the generated SQL, even when the request involves other tables via an association or a common table expression.

SQL Functions

📖 SQLSpecificExpressible

GRDB comes with a Swift version of many SQLite built-in functions, listed below. But not all: see Embedding SQL in Query Interface Requests for a way to add support for missing SQL functions.

ABS, AVG, COALESCE, COUNT, DATETIME, JULIANDAY, LENGTH, MAX, MIN, SUM, TOTAL:

Those are based on the abs, average, coalesce, count, dateTime, julianDay, length, max, min, sum, and total Swift functions:

// SELECT MIN(score), MAX(score) FROM player
Player.select { [min($0.score), max($0.score)] }

// SELECT COUNT(name) FROM player
Player.select { count($0.name) }

// SELECT COUNT(DISTINCT name) FROM player
Player.select { count(distinct: $0.name) }

// SELECT JULIANDAY(date, 'start of year') FROM game
Game.select { julianDay($0.date, .startOfYear) }

For more information about the functions dateTime and julianDay, see Date And Time Functions.

CAST

Use the cast Swift function:

// SELECT (CAST(wins AS REAL) / games) AS successRate FROM player
Player.select { (cast($0.wins, as: .real) / $0.games).forKey("successRate") }

See CAST expressions for more information about SQLite conversions.

IFNULL

Use the Swift ?? operator:

// SELECT IFNULL(name, 'Anonymous') FROM player
Player.select { $0.name ?? "Anonymous" }

// SELECT IFNULL(name, email) FROM player
Player.select { $0.name ?? $0.email }

LOWER, UPPER

The query interface does not give access to those SQLite functions. Nothing against them, but they are not unicode aware.

Instead, GRDB extends SQLite with SQL functions that call the Swift built-in string functions capitalized, lowercased, uppercased, localizedCapitalized, localizedLowercased and localizedUppercased:
```
Player.select { $0.name.uppercased() }
```
Note: When comparing strings, you'd rather use a collation:
```
let name: String = ...

// Not recommended
Player.filter { $0.name.uppercased() == name.uppercased() }

// Better
Player.filter { $0.name.collating(.caseInsensitiveCompare) == name }
```

Custom SQL functions and aggregates

You can apply your own custom SQL functions and aggregates:

let myFunction = DatabaseFunction("myFunction", ...)

// SELECT myFunction(name) FROM player
Player.select { myFunction($0.name) }

Embedding SQL in Query Interface Requests

You will sometimes want to extend your query interface requests with SQL snippets. This can happen because GRDB does not provide a Swift interface for some SQL function or operator, or because you want to use an SQLite construct that GRDB does not support.

Support for extensibility is large, but not unlimited. All the SQL queries built by the query interface request have the shape below. If you need something else, you'll have to use raw SQL requests.

WITH ...     -- 1
SELECT ...   -- 2
FROM ...     -- 3
JOIN ...     -- 4
WHERE ...    -- 5
GROUP BY ... -- 6
HAVING ...   -- 7
ORDER BY ... -- 8
LIMIT ...    -- 9

WITH ...: see Common Table Expressions.

SELECT ...

The selection can be provided as raw SQL:

// SELECT IFNULL(name, 'O''Brien'), score FROM player
let request = Player.select(sql: "IFNULL(name, 'O''Brien'), score")

// SELECT IFNULL(name, 'O''Brien'), score FROM player
let defaultName = "O'Brien"
let request = Player.select(sql: "IFNULL(name, ?), score", arguments: [suffix])

The selection can be provided with SQL Interpolation:

// SELECT IFNULL(name, 'O''Brien'), score FROM player
let defaultName = "O'Brien"
let request = Player.select(literal: "IFNULL(name, \(defaultName)), score")

The selection can be provided with a mix of Swift and SQL Interpolation:

// SELECT IFNULL(name, 'O''Brien') AS displayName, score FROM player
let defaultName = "O'Brien"
let request = Player.select {
    let displayName: SQL = "IFNULL(\($0.name), \(defaultName)) AS displayName"
    return [displayName, $0.score]
}

When the custom SQL snippet should behave as a full-fledged expression, with support for the + Swift operator, the forKey aliasing method, and all other SQL Operators, build an expression literal with the SQL.sqlExpression method:

// SELECT IFNULL(name, 'O''Brien') AS displayName, score FROM player
let defaultName = "O'Brien"
let request = Player.select {
    let displayName = SQL("IFNULL(\($0.name), \(defaultName))").sqlExpression
    return [displayName.forKey("displayName"), $0.score]
}

Such expression literals allow you to build a reusable support library of SQL functions or operators that are missing from the query interface. For example, you can define a Swift date function:

func date(_ value: some SQLSpecificExpressible) -> SQLExpression {
    SQL("DATE(\(value))").sqlExpression
}

// SELECT * FROM "player" WHERE DATE("createdAt") = '2020-01-23'
let request = Player.filter { date($0.createdAt) == "2020-01-23" }

See the Query Interface Organization for more information about SQLSpecificExpressible and SQLExpression.

FROM ...: only one table is supported here. You can not customize this SQL part.
JOIN ...: joins are fully controlled by Associations. You can not customize this SQL part.

WHERE ...

The WHERE clause can be provided as raw SQL:

// SELECT * FROM player WHERE score >= 1000
let request = Player.filter(sql: "score >= 1000")

// SELECT * FROM player WHERE score >= 1000
let minScore = 1000
let request = Player.filter(sql: "score >= ?", arguments: [minScore])

The WHERE clause can be provided with SQL Interpolation:

// SELECT * FROM player WHERE score >= 1000
let minScore = 1000
let request = Player.filter(literal: "score >= \(minScore)")

The WHERE clause can be provided with a mix of Swift and SQL Interpolation:

// SELECT * FROM player WHERE (score >= 1000) AND (team = 'red')
let minScore = 1000
let request = Player.filter { 
    let scoreCondition: SQL = "\($0.score) >= \(minScore)"
    return scoreCondition && $0.team == "red"
}

See SELECT ... above for more SQL Interpolation examples.

GROUP BY ...

The GROUP BY clause can be provided as raw SQL, SQL Interpolation, or a mix of Swift and SQL Interpolation, just as the selection and the WHERE clause (see above).
HAVING ...

The HAVING clause can be provided as raw SQL, SQL Interpolation, or a mix of Swift and SQL Interpolation, just as the selection and the WHERE clause (see above).
ORDER BY ...

The ORDER BY clause can be provided as raw SQL, SQL Interpolation, or a mix of Swift and SQL Interpolation, just as the selection and the WHERE clause (see above).

In order to support the desc and asc query interface operators, and the reversed() query interface method, you must provide your orderings as expression literals with the SQL.sqlExpression method:
```
// SELECT * FROM "player" 
// ORDER BY (score + bonus) ASC, name DESC
let request = Player
    .order {
        let total = SQL("(\($0.score) + \($0.bonus))").sqlExpression
        return [total.desc, $0.name]
    }
    .reversed()
```
LIMIT ...: use the limit(_:offset:) method. You can not customize this SQL part.

Fetching from Requests

Once you have a request, you can fetch the records at the origin of the request:

// Some request based on `Player`
let request = Player.filter { ... }... // QueryInterfaceRequest<Player>

// Fetch players:
try request.fetchCursor(db) // A Cursor of Player
try request.fetchAll(db)    // [Player]
try request.fetchSet(db)    // Set<Player>
try request.fetchOne(db)    // Player?

For example:

let allPlayers = try Player.fetchAll(db)                            // [Player]
let arthur = try Player.filter { $0.name == "Arthur" }.fetchOne(db) // Player?

See fetching methods for information about the fetchCursor, fetchAll, fetchSet and fetchOne methods.

You sometimes want to fetch other values.

The simplest way is to use the request as an argument to a fetching method of the desired type:

// Fetch an Int
let request = Player.select { max($0.score) }
let maxScore = try Int.fetchOne(db, request) // Int?

// Fetch a Row
let request = Player.select { [min($0.score), max($0.score)] }
let row = try Row.fetchOne(db, request)!     // Row
let minScore = row[0] as Int?
let maxScore = row[1] as Int?

You can also change the request so that it knows the type it has to fetch:

With asRequest(of:), useful when you use Associations:

struct BookInfo: FetchableRecord, Decodable {
    var book: Book
    var author: Author
}

// A request of BookInfo
let request = Book
    .including(required: Book.author)
    .asRequest(of: BookInfo.self)

let bookInfos = try dbQueue.read { db in
    try request.fetchAll(db) // [BookInfo]
}

With select(..., as:), which is handy when you change the selection:

// A request of Int
let request = Player.select({ max($0.score) }, as: Int.self)

let maxScore = try dbQueue.read { db in
    try request.fetchOne(db) // Int?
}

Fetching by Key

Fetching records according to their primary key is a common task.

Identifiable Records can use the type-safe methods find(_🆔), fetchOne(_🆔), fetchAll(_:ids:) and fetchSet(_:ids:):

try Player.find(db, id: 1)                   // Player
try Player.fetchOne(db, id: 1)               // Player?
try Country.fetchAll(db, ids: ["FR", "US"])  // [Countries]

All record types can use find(_🔑), fetchOne(_🔑), fetchAll(_:keys:) and fetchSet(_:keys:) that apply conditions on primary and unique keys:

try Player.find(db, key: 1)                  // Player
try Player.fetchOne(db, key: 1)              // Player?
try Country.fetchAll(db, keys: ["FR", "US"]) // [Country]
try Player.fetchOne(db, key: ["email": "arthur@example.com"])            // Player?
try Citizenship.fetchOne(db, key: ["citizenId": 1, "countryCode": "FR"]) // Citizenship?

When the table has no explicit primary key, GRDB uses the hidden rowid column:

// SELECT * FROM document WHERE rowid = 1
try Document.fetchOne(db, key: 1)            // Document?

When you want to build a request and plan to fetch from it later, use a filter method:

let request = Player.filter(id: 1)
let request = Country.filter(ids: ["FR", "US"])
let request = Player.filter(key: ["email": "arthur@example.com"])
let request = Citizenship.filter(key: ["citizenId": 1, "countryCode": "FR"])

Testing for Record Existence

You can check if a request has matching rows in the database.

// Some request based on `Player`
let request = Player.filter { ... }...

// Check for player existence:
let noSuchPlayer = try request.isEmpty(db) // Bool

You should check for emptiness instead of counting:

// Correct
let noSuchPlayer = try request.fetchCount(db) == 0
// Even better
let noSuchPlayer = try request.isEmpty(db)

You can also check if a given primary or unique key exists in the database.

Identifiable Records can use the type-safe method exists(_🆔):

try Player.exists(db, id: 1)
try Country.exists(db, id: "FR")

All record types can use exists(_🔑) that can check primary and unique keys:

try Player.exists(db, key: 1)
try Country.exists(db, key: "FR")
try Player.exists(db, key: ["email": "arthur@example.com"])
try Citizenship.exists(db, key: ["citizenId": 1, "countryCode": "FR"])

You should check for key existence instead of fetching a record and checking for nil:

// Correct
let playerExists = try Player.fetchOne(db, id: 1) != nil
// Even better
let playerExists = try Player.exists(db, id: 1)

Fetching Aggregated Values

Requests can count. The fetchCount() method returns the number of rows that would be returned by a fetch request:

// SELECT COUNT(*) FROM player
let count = try Player.fetchCount(db) // Int

// SELECT COUNT(*) FROM player WHERE email IS NOT NULL
let count = try Player.filter { $0.email != nil }.fetchCount(db)

// SELECT COUNT(DISTINCT name) FROM player
let count = try Player.select(\.name).distinct().fetchCount(db)

// SELECT COUNT(*) FROM (SELECT DISTINCT name, score FROM player)
let count = try Player.select { [$0.name, $0.score] }.distinct().fetchCount(db)

Other aggregated values can also be selected and fetched (see SQL Functions):

let request = Player.select { max($0.score) }
let maxScore = try Int.fetchOne(db, request) // Int?

let request = Player.select { [min($0.score), max($0.score)] }
let row = try Row.fetchOne(db, request)!     // Row
let minScore = row[0] as Int?
let maxScore = row[1] as Int?

Delete Requests

Requests can delete records, with the deleteAll() method:

// DELETE FROM player
try Player.deleteAll(db)

// DELETE FROM player WHERE team = 'Reds'
try Player
    .filter { $0.team == "Reds" }
    .deleteAll(db)

// DELETE FROM player ORDER BY score LIMIT 10
try Player
    .order(\.score)
    .limit(10)
    .deleteAll(db)

Note Deletion methods are available on types that adopt the TableRecord protocol, and Table:
struct Player: TableRecord { ... }
try Player.deleteAll(db)          // Fine
try Table("player").deleteAll(db) // Just as fine

Deleting records according to their primary key is a common task.

Identifiable Records can use the type-safe methods deleteOne(_🆔) and deleteAll(_:ids:):

try Player.deleteOne(db, id: 1)
try Country.deleteAll(db, ids: ["FR", "US"])

All record types can use deleteOne(_🔑) and deleteAll(_:keys:) that apply conditions on primary and unique keys:

try Player.deleteOne(db, key: 1)
try Country.deleteAll(db, keys: ["FR", "US"])
try Player.deleteOne(db, key: ["email": "arthur@example.com"])
try Citizenship.deleteOne(db, key: ["citizenId": 1, "countryCode": "FR"])

When the table has no explicit primary key, GRDB uses the hidden rowid column:

// DELETE FROM document WHERE rowid = 1
try Document.deleteOne(db, id: 1)             // Document?

Update Requests

Requests can batch update records. The updateAll() method accepts column assignments defined with the set(to:) method:

// UPDATE player SET score = 0, isHealthy = 1, bonus = NULL
try Player.updateAll(db) { [
    $0.score.set(to: 0), 
    $0.isHealthy.set(to: true), 
    $0.bonus.set(to: nil),
] }

// UPDATE player SET score = 0 WHERE team = 'Reds'
try Player
    .filter { $0.team == "Reds" }
    .updateAll(db) { $0.score.set(to: 0) }

// UPDATE player SET isGreat = 1 ORDER BY score DESC LIMIT 10
try Player
    .order(\.score.desc)
    .limit(10)
    .updateAll(db) { $0.isGreat.set(to: true) }

// UPDATE country SET population = 67848156 WHERE id = 'FR'
try Country
    .filter(id: "FR")
    .updateAll(db) { $0.population.set(to: 67_848_156) }

Column assignments accept any expression:

// UPDATE player SET score = score + (bonus * 2)
try Player.updateAll(db) {
    $0.score.set(to: $0.score + $0.bonus * 2)
}

As a convenience, you can also use the +=, -=, *=, or /= operators:

// UPDATE player SET score = score + (bonus * 2)
try Player.updateAll(db) { $0.score += $0.bonus * 2 }

Default Conflict Resolution rules apply, and you may also provide a specific one:

// UPDATE OR IGNORE player SET ...
try Player.updateAll(db, onConflict: .ignore) { /* assignments... */ }

Note The updateAll method is available on types that adopt the TableRecord protocol, and Table:
struct Player: TableRecord { ... }
try Player.updateAll(db, ...)          // Fine
try Table("player").updateAll(db, ...) // Just as fine

Custom Requests

Until now, we have seen requests created from any type that adopts the TableRecord protocol:

let request = Player.all()  // QueryInterfaceRequest<Player>

Those requests of type QueryInterfaceRequest can fetch and count:

try request.fetchCursor(db) // A Cursor of Player
try request.fetchAll(db)    // [Player]
try request.fetchSet(db)    // Set<Player>
try request.fetchOne(db)    // Player?
try request.fetchCount(db)  // Int

When the query interface can not generate the SQL you need, you can still fallback to raw SQL:

// Custom SQL is always welcome
try Player.fetchAll(db, sql: "SELECT ...")   // [Player]

But you may prefer to bring some elegance back in, and build custom requests:

// No custom SQL in sight
try Player.customRequest().fetchAll(db) // [Player]

To build custom requests, you can use one of the built-in requests or derive requests from other requests.

SQLRequest is a fetch request built from raw SQL. For example:

extension Player {
    static func filter(color: Color) -> SQLRequest<Player> {
        SQLRequest<Player>(
            sql: "SELECT * FROM player WHERE color = ?"
            arguments: [color])
    }
}

// [Player]
try Player.filter(color: .red).fetchAll(db)

SQLRequest supports SQL Interpolation:

extension Player {
    static func filter(color: Color) -> SQLRequest<Player> {
        "SELECT * FROM player WHERE color = \(color)"
    }
}

The asRequest(of:) method changes the type fetched by the request. It is useful, for example, when you use Associations:

struct BookInfo: FetchableRecord, Decodable {
    var book: Book
    var author: Author
}

let request = Book
    .including(required: Book.author)
    .asRequest(of: BookInfo.self)

// [BookInfo]
try request.fetchAll(db)

The adapted(_:) method eases the consumption of complex rows with row adapters. See RowAdapter and splittingRowAdapters(columnCounts:) for a sample code that uses adapted(_:).

Encryption

GRDB can encrypt your database with SQLCipher v3.4+.

To use SQLCipher with the Swift Package Manager, you must fork GRDB, and modify Package.swift. Instructions are in the file itself, in comments that contain "GRDB+SQLCipher".

To use SQLCipher with CocoaPods, specify in your Podfile:

# GRDB with SQLCipher 4
pod 'GRDB.swift/SQLCipher'
pod 'SQLCipher', '~> 4.0'

# GRDB with SQLCipher 3
pod 'GRDB.swift/SQLCipher'
pod 'SQLCipher', '~> 3.4'

Make sure you remove any existing pod 'GRDB.swift' from your Podfile. GRDB.swift/SQLCipher must be the only active GRDB pod in your whole project, or you will face linker or runtime errors, due to the conflicts between SQLCipher and the system SQLite.

Creating or Opening an Encrypted Database

You create and open an encrypted database by providing a passphrase to your database connection:

var config = Configuration()
config.prepareDatabase { db in
    try db.usePassphrase("secret")
}
let dbQueue = try DatabaseQueue(path: dbPath, configuration: config)

It is also in prepareDatabase that you perform other SQLCipher configuration steps that must happen early in the lifetime of a SQLCipher connection. For example:

var config = Configuration()
config.prepareDatabase { db in
    try db.usePassphrase("secret")
    try db.execute(sql: "PRAGMA cipher_page_size = ...")
    try db.execute(sql: "PRAGMA kdf_iter = ...")
}
let dbQueue = try DatabaseQueue(path: dbPath, configuration: config)

When you want to open an existing SQLCipher 3 database with SQLCipher 4, you may want to run the cipher_compatibility pragma:

// Open an SQLCipher 3 database with SQLCipher 4
var config = Configuration()
config.prepareDatabase { db in
    try db.usePassphrase("secret")
    try db.execute(sql: "PRAGMA cipher_compatibility = 3")
}
let dbQueue = try DatabaseQueue(path: dbPath, configuration: config)

See SQLCipher 4.0.0 Release and Upgrading to SQLCipher 4 for more information.

Changing the Passphrase of an Encrypted Database

You can change the passphrase of an already encrypted database.

When you use a database queue, open the database with the old passphrase, and then apply the new passphrase:

try dbQueue.write { db in
    try db.changePassphrase("newSecret")
}

When you use a database pool, make sure that no concurrent read can happen by changing the passphrase within the barrierWriteWithoutTransaction block. You must also ensure all future reads open a new database connection by calling the invalidateReadOnlyConnections method:

try dbPool.barrierWriteWithoutTransaction { db in
    try db.changePassphrase("newSecret")
    dbPool.invalidateReadOnlyConnections()
}

Note: When an application wants to keep on using a database queue or pool after the passphrase has changed, it is responsible for providing the correct passphrase to the usePassphrase method called in the database preparation function. Consider:
// WRONG: this won't work across a passphrase change
let passphrase = try getPassphrase()
var config = Configuration()
config.prepareDatabase { db in
    try db.usePassphrase(passphrase)
}

// CORRECT: get the latest passphrase when it is needed
var config = Configuration()
config.prepareDatabase { db in
    let passphrase = try getPassphrase()
    try db.usePassphrase(passphrase)
}

Note: The DatabasePool.barrierWriteWithoutTransaction method does not prevent database snapshots from accessing the database during the passphrase change, or after the new passphrase has been applied to the database. Those database accesses may throw errors. Applications should provide their own mechanism for invalidating open snapshots before the passphrase is changed.

Note: Instead of changing the passphrase "in place" as described here, you can also export the database in a new encrypted database that uses the new passphrase. See Exporting a Database to an Encrypted Database.

Exporting a Database to an Encrypted Database

Providing a passphrase won't encrypt a clear-text database that already exists, though. SQLCipher can't do that, and you will get an error instead: SQLite error 26: file is encrypted or is not a database.

Instead, create a new encrypted database, at a distinct location, and export the content of the existing database. This can both encrypt a clear-text database, or change the passphrase of an encrypted database.

The technique to do that is documented by SQLCipher.

With GRDB, it gives:

// The existing database
let existingDBQueue = try DatabaseQueue(path: "/path/to/existing.db")

// The new encrypted database, at some distinct location:
var config = Configuration()
config.prepareDatabase { db in
    try db.usePassphrase("secret")
}
let newDBQueue = try DatabaseQueue(path: "/path/to/new.db", configuration: config)

try existingDBQueue.inDatabase { db in
    try db.execute(
        sql: """
            ATTACH DATABASE ? AS encrypted KEY ?;
            SELECT sqlcipher_export('encrypted');
            DETACH DATABASE encrypted;
            """,
        arguments: [newDBQueue.path, "secret"])
}

// Now the export is completed, and the existing database can be deleted.

Security Considerations

Managing the lifetime of the passphrase string

It is recommended to avoid keeping the passphrase in memory longer than necessary. To do this, make sure you load the passphrase from the prepareDatabase method:

// NOT RECOMMENDED: this keeps the passphrase in memory longer than necessary
let passphrase = try getPassphrase()
var config = Configuration()
config.prepareDatabase { db in
    try db.usePassphrase(passphrase)
}

// RECOMMENDED: only load the passphrase when it is needed
var config = Configuration()
config.prepareDatabase { db in
    let passphrase = try getPassphrase()
    try db.usePassphrase(passphrase)
}

This technique helps manages the lifetime of the passphrase, although keep in mind that the content of a String may remain intact in memory long after the object has been released.

For even better control over the lifetime of the passphrase in memory, use a Data object which natively provides the resetBytes function.

// RECOMMENDED: only load the passphrase when it is needed and reset its content immediately after use
var config = Configuration()
config.prepareDatabase { db in
    var passphraseData = try getPassphraseData() // Data
    defer {
        passphraseData.resetBytes(in: 0..<passphraseData.count)
    }
    try db.usePassphrase(passphraseData)
}

Some demanding users will want to go further, and manage the lifetime of the raw passphrase bytes. See below.

Managing the lifetime of the passphrase bytes

GRDB offers convenience methods for providing the database passphrases as Swift strings: usePassphrase(_:) and changePassphrase(_:). Those methods don't keep the passphrase String in memory longer than necessary. But they are as secure as the standard String type: the lifetime of actual passphrase bytes in memory is not under control.

When you want to precisely manage the passphrase bytes, talk directly to SQLCipher, using its raw C functions.

For example:

var config = Configuration()
config.prepareDatabase { db in
    ... // Carefully load passphrase bytes
    let code = sqlite3_key(db.sqliteConnection, /* passphrase bytes */)
    ... // Carefully dispose passphrase bytes
    guard code == SQLITE_OK else {
        throw DatabaseError(
            resultCode: ResultCode(rawValue: code), 
            message: db.lastErrorMessage)
    }
}
let dbQueue = try DatabaseQueue(path: dbPath, configuration: config)

Passphrase availability vs. Database availability

When the passphrase is securely stored in the system keychain, your application can protect it using the kSecAttrAccessible attribute.

Such protection prevents GRDB from creating SQLite connections when the passphrase is not available:

var config = Configuration()
config.prepareDatabase { db in
    let passphrase = try loadPassphraseFromSystemKeychain()
    try db.usePassphrase(passphrase)
}

// Success if and only if the passphrase is available
let dbQueue = try DatabaseQueue(path: dbPath, configuration: config)

For the same reason, database pools, which open SQLite connections on demand, may fail at any time as soon as the passphrase becomes unavailable:

// Success if and only if the passphrase is available
let dbPool = try DatabasePool(path: dbPath, configuration: config)

// May fail if passphrase has turned unavailable
try dbPool.read { ... }

// May trigger value observation failure if passphrase has turned unavailable
try dbPool.write { ... }

Because DatabasePool maintains a pool of long-lived SQLite connections, some database accesses will use an existing connection, and succeed. And some other database accesses will fail, as soon as the pool wants to open a new connection. It is impossible to predict which accesses will succeed or fail.

For the same reason, a database queue, which also maintains a long-lived SQLite connection, will remain available even after the passphrase has turned unavailable.

Applications are thus responsible for protecting database accesses when the passphrase is unavailable. To this end, they can use Data Protection. They can also destroy their instances of database queue or pool when the passphrase becomes unavailable.

Backup

You can backup (copy) a database into another.

Backups can for example help you copying an in-memory database to and from a database file when you implement NSDocument subclasses.

let source: DatabaseQueue = ...      // or DatabasePool
let destination: DatabaseQueue = ... // or DatabasePool
try source.backup(to: destination)

The backup method blocks the current thread until the destination database contains the same contents as the source database.

When the source is a database pool, concurrent writes can happen during the backup. Those writes may, or may not, be reflected in the backup, but they won't trigger any error.

Database has an analogous backup method.

let source: DatabaseQueue = ...      // or DatabasePool
let destination: DatabaseQueue = ... // or DatabasePool
try source.write { sourceDb in
    try destination.barrierWriteWithoutTransaction { destDb in
        try sourceDb.backup(to: destDb)
    }
}

This method allows for the choice of source and destination Database handles with which to backup the database.

Backup Progress Reporting

The backup methods take optional pagesPerStep and progress parameters. Together these parameters can be used to track a database backup in progress and abort an incomplete backup.

When pagesPerStep is provided, the database backup is performed in steps. At each step, no more than pagesPerStep database pages are copied from the source to the destination. The backup proceeds one step at a time until all pages have been copied.

When a progress callback is provided, progress is called after every backup step, including the last. Even if a non-default pagesPerStep is specified or the backup is otherwise completed in a single step, the progress callback will be called.

try source.backup(
    to: destination,
    pagesPerStep: ...)
    { backupProgress in
       print("Database backup progress:", backupProgress)
    }

Aborting an Incomplete Backup

If a call to progress throws when backupProgress.isComplete == false, the backup will be aborted and the error rethrown. However, if a call to progress throws when backupProgress.isComplete == true, the backup is unaffected and the error is silently ignored.

Warning: Passing non-default values of pagesPerStep or progress to the backup methods is an advanced API intended to provide additional capabilities to expert users. GRDB's backup API provides a faithful, low-level wrapper to the underlying SQLite online backup API. GRDB's documentation is not a comprehensive substitute for the official SQLite documentation of their backup API.

Interrupt a Database

The interrupt() method causes any pending database operation to abort and return at its earliest opportunity.

It can be called from any thread.

dbQueue.interrupt()
dbPool.interrupt()

A call to interrupt() that occurs when there are no running SQL statements is a no-op and has no effect on SQL statements that are started after interrupt() returns.

A database operation that is interrupted will throw a DatabaseError with code SQLITE_INTERRUPT. If the interrupted SQL operation is an INSERT, UPDATE, or DELETE that is inside an explicit transaction, then the entire transaction will be rolled back automatically. If the rolled back transaction was started by a transaction-wrapping method such as DatabaseWriter.write or Database.inTransaction, then all database accesses will throw a DatabaseError with code SQLITE_ABORT until the wrapping method returns.

For example:

try dbQueue.write { db in
    try Player(...).insert(db)     // throws SQLITE_INTERRUPT
    try Player(...).insert(db)     // not executed
}                                  // throws SQLITE_INTERRUPT

try dbQueue.write { db in
    do {
        try Player(...).insert(db) // throws SQLITE_INTERRUPT
    } catch { }
}                                  // throws SQLITE_ABORT

try dbQueue.write { db in
    do {
        try Player(...).insert(db) // throws SQLITE_INTERRUPT
    } catch { }
    try Player(...).insert(db)     // throws SQLITE_ABORT
}                                  // throws SQLITE_ABORT

You can catch both SQLITE_INTERRUPT and SQLITE_ABORT errors:

do {
    try dbPool.write { db in ... }
} catch DatabaseError.SQLITE_INTERRUPT, DatabaseError.SQLITE_ABORT {
    // Oops, the database was interrupted.
}

For more information, see Interrupt A Long-Running Query.

Avoiding SQL Injection

SQL injection is a technique that lets an attacker nuke your database.

https://xkcd.com/327/

Here is an example of code that is vulnerable to SQL injection:

// BAD BAD BAD
let id = 1
let name = textField.text
try dbQueue.write { db in
    try db.execute(sql: "UPDATE students SET name = '\(name)' WHERE id = \(id)")
}

If the user enters a funny string like Robert'; DROP TABLE students; --, SQLite will see the following SQL, and drop your database table instead of updating a name as intended:

UPDATE students SET name = 'Robert';
DROP TABLE students;
--' WHERE id = 1

To avoid those problems, never embed raw values in your SQL queries. The only correct technique is to provide arguments to your raw SQL queries:

let name = textField.text
try dbQueue.write { db in
    // Good
    try db.execute(
        sql: "UPDATE students SET name = ? WHERE id = ?",
        arguments: [name, id])
    
    // Just as good
    try db.execute(
        sql: "UPDATE students SET name = :name WHERE id = :id",
        arguments: ["name": name, "id": id])
}

When you use records and the query interface, GRDB always prevents SQL injection for you:

let id = 1
let name = textField.text
try dbQueue.write { db in
    if var student = try Student.fetchOne(db, id: id) {
        student.name = name
        try student.update(db)
    }
}

Error Handling

GRDB can throw DatabaseError, RecordError, RowDecodingError, or crash your program with a fatal error.

Considering that a local database is not some JSON loaded from a remote server, GRDB focuses on trusted databases. Dealing with untrusted databases requires extra care.

DatabaseError

📖 DatabaseError

DatabaseError are thrown on SQLite errors:

do {
    try Pet(masterId: 1, name: "Bobby").insert(db)
} catch let error as DatabaseError {
    // The SQLite error code: 19 (SQLITE_CONSTRAINT)
    error.resultCode
    
    // The extended error code: 787 (SQLITE_CONSTRAINT_FOREIGNKEY)
    error.extendedResultCode
    
    // The eventual SQLite message: FOREIGN KEY constraint failed
    error.message
    
    // The eventual erroneous SQL query
    // "INSERT INTO pet (masterId, name) VALUES (?, ?)"
    error.sql
    
    // The eventual SQL arguments
    // [1, "Bobby"]
    error.arguments
    
    // Full error description
    // > SQLite error 19: FOREIGN KEY constraint failed -
    // > while executing `INSERT INTO pet (masterId, name) VALUES (?, ?)`
    error.description
}

If you want to see statement arguments in the error description, make statement arguments public.

SQLite uses results codes to distinguish between various errors.

You can catch a DatabaseError and match on result codes:

do {
    try ...
} catch let error as DatabaseError {
    switch error {
    case DatabaseError.SQLITE_CONSTRAINT_FOREIGNKEY:
        // foreign key constraint error
    case DatabaseError.SQLITE_CONSTRAINT:
        // any other constraint error
    default:
        // any other database error
    }
}

You can also directly match errors on result codes:

do {
    try ...
} catch DatabaseError.SQLITE_CONSTRAINT_FOREIGNKEY {
    // foreign key constraint error
} catch DatabaseError.SQLITE_CONSTRAINT {
    // any other constraint error
} catch {
    // any other database error
}

Each DatabaseError has two codes: an extendedResultCode (see extended result code), and a less precise resultCode (see primary result code). Extended result codes are refinements of primary result codes, as SQLITE_CONSTRAINT_FOREIGNKEY is to SQLITE_CONSTRAINT, for example.

Warning: SQLite has progressively introduced extended result codes across its versions. The SQLite release notes are unfortunately not quite clear about that: write your handling of extended result codes with care.

RecordError

📖 RecordError

RecordError is thrown by the PersistableRecord protocol when the update method could not find any row to update:

do {
    try player.update(db)
} catch let RecordError.recordNotFound(databaseTableName: table, key: key) {
    print("Key \(key) was not found in table \(table).")
}

RecordError is also thrown by the FetchableRecord protocol when the find method does not find any record:

do {
    let player = try Player.find(db, id: 42)
} catch let RecordError.recordNotFound(databaseTableName: table, key: key) {
    print("Key \(key) was not found in table \(table).")
}

RowDecodingError

📖 RowDecodingError

RowDecodingError is thrown when the application can not decode a value from a database row. For example:

let row = try Row.fetchOne(db, sql: "SELECT NULL AS name")!
// RowDecodingError: could not decode String from database value NULL.
let name = try row.decode(String.self, forColumn: "name")

Fatal Errors

Fatal errors notify that the program, or the database, has to be changed.

They uncover programmer errors, false assumptions, and prevent misuses. Here are a few examples:

The code asks for a non-optional value, when the database contains NULL:
```
// fatal error: could not convert NULL to String.
let name: String = row["name"]
```
Solution: fix the contents of the database, use NOT NULL constraints, or load an optional:
```
let name: String? = row["name"]
```

Conversion from database value to Swift type fails:

// fatal error: could not convert "Mom’s birthday" to Date.
let date: Date = row["date"]

// fatal error: could not convert "" to URL.
let url: URL = row["url"]

Solution: fix the contents of the database, or use DatabaseValue to handle all possible cases:

let dbValue: DatabaseValue = row["date"]
if dbValue.isNull {
    // Handle NULL
} else if let date = Date.fromDatabaseValue(dbValue) {
    // Handle valid date
} else {
    // Handle invalid date
}

The database can't guarantee that the code does what it says:

// fatal error: table player has no unique index on column email
try Player.deleteOne(db, key: ["email": "arthur@example.com"])

Solution: add a unique index to the player.email column, or use the deleteAll method to make it clear that you may delete more than one row:

try Player.filter { $0.email == "arthur@example.com" }.deleteAll(db)

Database connections are not reentrant:

// fatal error: Database methods are not reentrant.
dbQueue.write { db in
    dbQueue.write { db in
        ...
    }
}

Solution: avoid reentrancy, and instead pass a database connection along.

How to Deal with Untrusted Inputs

Let's consider the code below:

let sql = "SELECT ..."

// Some untrusted arguments for the query
let arguments: [String: Any] = ...
let rows = try Row.fetchCursor(db, sql: sql, arguments: StatementArguments(arguments))

while let row = try rows.next() {
    // Some untrusted database value:
    let date: Date? = row[0]
}

It has two opportunities to throw fatal errors:

Untrusted arguments: The dictionary may contain values that do not conform to the DatabaseValueConvertible protocol, or may miss keys required by the statement.
Untrusted database content: The row may contain a non-null value that can't be turned into a date.

In such a situation, you can still avoid fatal errors by exposing and handling each failure point, one level down in the GRDB API:

// Untrusted arguments
if let arguments = StatementArguments(arguments) {
    let statement = try db.makeStatement(sql: sql)
    try statement.setArguments(arguments)
    
    var cursor = try Row.fetchCursor(statement)
    while let row = try iterator.next() {
        // Untrusted database content
        let dbValue: DatabaseValue = row[0]
        if dbValue.isNull {
            // Handle NULL
        if let date = Date.fromDatabaseValue(dbValue) {
            // Handle valid date
        } else {
            // Handle invalid date
        }
    }
}

See Statement and DatabaseValue for more information.

Error Log

SQLite can be configured to invoke a callback function containing an error code and a terse error message whenever anomalies occur.

This global error callback must be configured early in the lifetime of your application:

Database.logError = { (resultCode, message) in
    NSLog("%@", "SQLite error \(resultCode): \(message)")
}

Warning: Database.logError must be set before any database connection is opened. This includes the connections that your application opens with GRDB, but also connections opened by other tools, such as third-party libraries. Setting it after a connection has been opened is an SQLite misuse, and has no effect.

See The Error And Warning Log for more information.

Unicode

SQLite lets you store unicode strings in the database.

However, SQLite does not provide any unicode-aware string transformations or comparisons.

Unicode functions

The UPPER and LOWER built-in SQLite functions are not unicode-aware:

// "JéRôME"
try String.fetchOne(db, sql: "SELECT UPPER('Jérôme')")

GRDB extends SQLite with SQL functions that call the Swift built-in string functions capitalized, lowercased, uppercased, localizedCapitalized, localizedLowercased and localizedUppercased:

// "JÉRÔME"
let uppercased = DatabaseFunction.uppercase
try String.fetchOne(db, sql: "SELECT \(uppercased.name)('Jérôme')")

Those unicode-aware string functions are also readily available in the query interface:

Player.select { $0.name.uppercased }

String Comparison

SQLite compares strings in many occasions: when you sort rows according to a string column, or when you use a comparison operator such as = and <=.

The comparison result comes from a collating function, or collation. SQLite comes with three built-in collations that do not support Unicode: binary, nocase, and rtrim.

GRDB comes with five extra collations that leverage unicode-aware comparisons based on the standard Swift String comparison functions and operators:

unicodeCompare (uses the built-in <= and == Swift operators)
caseInsensitiveCompare
localizedCaseInsensitiveCompare
localizedCompare
localizedStandardCompare

A collation can be applied to a table column. All comparisons involving this column will then automatically trigger the comparison function:

try db.create(table: "player") { t in
    // Guarantees case-insensitive email unicity
    t.column("email", .text).unique().collate(.nocase)
    
    // Sort names in a localized case insensitive way
    t.column("name", .text).collate(.localizedCaseInsensitiveCompare)
}

// Players are sorted in a localized case insensitive way:
let players = try Player.order(\.name).fetchAll(db)

Warning: SQLite requires host applications to provide the definition of any collation other than binary, nocase and rtrim. When a database file has to be shared or migrated to another SQLite library of platform (such as the Android version of your application), make sure you provide a compatible collation.

If you can't or don't want to define the comparison behavior of a column (see warning above), you can still use an explicit collation in SQL requests and in the query interface:

let collation = DatabaseCollation.localizedCaseInsensitiveCompare
let players = try Player.fetchAll(db,
    sql: "SELECT * FROM player ORDER BY name COLLATE \(collation.name))")
let players = try Player.order { $0.name.collating(collation) }.fetchAll(db)

You can also define your own collations:

let collation = DatabaseCollation("customCollation") { (lhs, rhs) -> NSComparisonResult in
    // return the comparison of lhs and rhs strings.
}

// Make the collation available to a database connection
var config = Configuration()
config.prepareDatabase { db in
    db.add(collation: collation)
}
let dbQueue = try DatabaseQueue(path: dbPath, configuration: config)

Memory Management

Both SQLite and GRDB use non-essential memory that help them perform better.

You can reclaim this memory with the releaseMemory method:

// Release as much memory as possible.
dbQueue.releaseMemory()
dbPool.releaseMemory()

This method blocks the current thread until all current database accesses are completed, and the memory collected.

Warning: If DatabasePool.releaseMemory() is called while a long read is performed concurrently, then no other read access will be possible until this long read has completed, and the memory has been released. If this does not suit your application needs, look for the asynchronous options below:

You can release memory in an asynchronous way as well:

// On a DatabaseQueue
dbQueue.asyncWriteWithoutTransaction { db in
    db.releaseMemory()
}

// On a DatabasePool
dbPool.releaseMemoryEventually()

DatabasePool.releaseMemoryEventually() does not block the current thread, and does not prevent concurrent database accesses. In exchange for this convenience, you don't know when memory has been freed.

Memory Management on iOS

The iOS operating system likes applications that do not consume much memory.

Database queues and pools automatically free non-essential memory when the application receives a memory warning, and when the application enters background.

You can opt out of this automatic memory management:

var config = Configuration()
config.automaticMemoryManagement = false
let dbQueue = try DatabaseQueue(path: dbPath, configuration: config) // or DatabasePool

FAQ

FAQ: Opening Connections

FAQ: SQL

How do I print a request as SQL?

FAQ: General

FAQ: Associations

FAQ: ValueObservation

Why is ValueObservation not publishing value changes?

FAQ: Errors

FAQ: Opening Connections

How do I create a database in my application?

First choose a proper location for the database file. Document-based applications will let the user pick a location. Apps that use the database as a global storage will prefer the Application Support directory.

The sample code below creates or opens a database file inside its dedicated directory (a recommended practice). On the first run, a new empty database file is created. On subsequent runs, the database file already exists, so it just opens a connection:

// HOW TO create an empty database, or open an existing database file

// Create the "Application Support/MyDatabase" directory
let fileManager = FileManager.default
let appSupportURL = try fileManager.url(
    for: .applicationSupportDirectory, in: .userDomainMask,
    appropriateFor: nil, create: true) 
let directoryURL = appSupportURL.appendingPathComponent("MyDatabase", isDirectory: true)
try fileManager.createDirectory(at: directoryURL, withIntermediateDirectories: true)

// Open or create the database
let databaseURL = directoryURL.appendingPathComponent("db.sqlite")
let dbQueue = try DatabaseQueue(path: databaseURL.path)

How do I open a database stored as a resource of my application?

Open a read-only connection to your resource:

// HOW TO open a read-only connection to a database resource

// Get the path to the database resource.
if let dbPath = Bundle.main.path(forResource: "db", ofType: "sqlite") {
    // If the resource exists, open a read-only connection.
    // Writes are disallowed because resources can not be modified. 
    var config = Configuration()
    config.readonly = true
    let dbQueue = try DatabaseQueue(path: dbPath, configuration: config)
} else {
    // The database resource can not be found.
    // Fix your setup, or report the problem to the user. 
}

How do I close a database connection?

Database connections are automatically closed when DatabaseQueue or DatabasePool instances are deinitialized.

If the correct execution of your program depends on precise database closing, perform an explicit call to close(). This method may fail and create zombie connections, so please check its detailed documentation.

FAQ: SQL

⬆️ FAQ
How do I print a request as SQL?

How do I print a request as SQL?

When you want to debug a request that does not deliver the expected results, you may want to print the SQL that is actually executed.

You can compile the request into a prepared Statement:

try dbQueue.read { db in
    let request = Player.filter { $0.email == "arthur@example.com" }
    let statement = try request.makePreparedRequest(db).statement
    print(statement) // SELECT * FROM player WHERE email = ?
    print(statement.arguments) // ["arthur@example.com"]
}

Another option is to setup a tracing function that prints out the executed SQL requests. For example, provide a tracing function when you connect to the database:

// Prints all SQL statements
var config = Configuration()
config.prepareDatabase { db in
    db.trace { print($0) }
}
let dbQueue = try DatabaseQueue(path: dbPath, configuration: config)

try dbQueue.read { db in
    // Prints "SELECT * FROM player WHERE email = ?"
    let players = try Player.filter { $0.email == "arthur@example.com" }.fetchAll(db)
}

If you want to see statement arguments such as 'arthur@example.com' in the logged statements, make statement arguments public.

Note: the generated SQL may change between GRDB releases, without notice: don't have your application rely on any specific SQL output.

FAQ: General

How do I monitor the duration of database statements execution?

Use the trace(options:_:) method, with the .profile option:

var config = Configuration()
config.prepareDatabase { db in
    db.trace(options: .profile) { event in
        // Prints all SQL statements with their duration
        print(event)
        
        // Access to detailed profiling information
        if case let .profile(statement, duration) = event, duration > 0.5 {
            print("Slow query: \(statement.sql)")
        }
    }
}
let dbQueue = try DatabaseQueue(path: dbPath, configuration: config)

try dbQueue.read { db in
    let players = try Player.filter { $0.email == "arthur@example.com" }.fetchAll(db)
    // Prints "0.003s SELECT * FROM player WHERE email = ?"
}

If you want to see statement arguments such as 'arthur@example.com' in the logged statements, make statement arguments public.

What Are Experimental Features?

Since GRDB 1.0, all backwards compatibility guarantees of semantic versioning apply: no breaking change will happen until the next major version of the library.

There is an exception, though: experimental features, marked with the "🔥 EXPERIMENTAL" badge. Those are advanced features that are too young, or lack user feedback. They are not stabilized yet.

Those experimental features are not protected by semantic versioning, and may break between two minor releases of the library. To help them becoming stable, your feedback is greatly appreciated.

Does GRDB support library evolution and ABI stability?

No, GRDB does not support library evolution and ABI stability. The only promise is API stability according to semantic versioning, with an exception for experimental features.

Yet, GRDB can be built with the "Build Libraries for Distribution" Xcode option (BUILD_LIBRARY_FOR_DISTRIBUTION), so that you can build binary frameworks at your convenience.

FAQ: Associations

How do I filter records and only keep those that are associated to another record?

Let's say you have two record types, Book and Author, and you want to only fetch books that have an author, and discard anonymous books.

We start by defining the association between books and authors:

struct Book: TableRecord {
    ...
    static let author = belongsTo(Author.self)
}

struct Author: TableRecord {
    ...
}

And then we can write our request and only fetch books that have an author, discarding anonymous ones:

let books: [Book] = try dbQueue.read { db in
    // SELECT book.* FROM book 
    // JOIN author ON author.id = book.authorID
    let request = Book.joining(required: Book.author)
    return try request.fetchAll(db)
}

Note how this request does not use the filter method. Indeed, we don't have any condition to express on any column. Instead, we just need to "require that a book can be joined to its author".

See How do I filter records and only keep those that are NOT associated to another record? below for the opposite question.

How do I filter records and only keep those that are NOT associated to another record?

Let's say you have two record types, Book and Author, and you want to only fetch anonymous books that do not have any author.

We start by defining the association between books and authors:

struct Book: TableRecord {
    ...
    static let author = belongsTo(Author.self)
}

struct Author: TableRecord {
    ...
}

And then we can write our request and only fetch anonymous books that don't have any author:

let books: [Book] = try dbQueue.read { db in
    // SELECT book.* FROM book
    // LEFT JOIN author ON author.id = book.authorID
    // WHERE author.id IS NULL
    let authorAlias = TableAlias<Author>()
    let request = Book
        .joining(optional: Book.author.aliased(authorAlias))
        .filter(!authorAlias.exists)
    return try request.fetchAll(db)
}

This request uses a TableAlias in order to be able to filter on the eventual associated author. We make sure that the Author.primaryKey is nil, which is another way to say it does not exist: the book has no author.

See How do I filter records and only keep those that are associated to another record? above for the opposite question.

How do I select only one column of an associated record?

Let's say you have two record types, Book and Author, and you want to fetch all books with their author name, but not the full associated author records.

We start by defining the association between books and authors:

struct Book: Decodable, TableRecord {
    ...
    static let author = belongsTo(Author.self)
}

struct Author: Decodable, TableRecord {
    ...
    enum Columns {
        static let name = Column(CodingKeys.name)
    }
}

And then we can write our request and the ad-hoc record that decodes it:

struct BookInfo: Decodable, FetchableRecord {
    var book: Book
    var authorName: String? // nil when the book is anonymous
    
    static func all() -> QueryInterfaceRequest<BookInfo> {
        // SELECT book.*, author.name AS authorName
        // FROM book
        // LEFT JOIN author ON author.id = book.authorID
        return Book
            .annotated(withOptional: Book.author.select { 
                $0.name.forKey(CodingKeys.authorName)
            })
            .asRequest(of: BookInfo.self)
    }
}

let bookInfos: [BookInfo] = try dbQueue.read { db in
    BookInfo.all().fetchAll(db)
}

By defining the request as a static method of BookInfo, you have access to the private CodingKeys.authorName, and a compiler-checked SQL column name.

By using the annotated(withOptional:) method, you append the author name to the top-level selection that can be decoded by the ad-hoc record.

By using asRequest(of:), you enhance the type-safety of your request.

FAQ: ValueObservation

Why is ValueObservation not publishing value changes?

Sometimes it looks that a ValueObservation does not notify the changes you expect.

There may be four possible reasons for this:

The expected changes were not committed into the database.
The expected changes were committed into the database, but were quickly overwritten.
The observation was stopped.
The observation does not track the expected database region.

To answer the first two questions, look at SQL statements executed by the database. This is done when you open the database connection:

// Prints all SQL statements
var config = Configuration()
config.prepareDatabase { db in
    db.trace { print("SQL: \($0)") }
}
let dbQueue = try DatabaseQueue(path: dbPath, configuration: config)

If, after that, you are convinced that the expected changes were committed into the database, and not overwritten soon after, trace observation events:

let observation = ValueObservation
    .tracking { db in ... }
    .print() // <- trace observation events
let cancellable = observation.start(...)

Look at the observation logs which start with cancel or failure: maybe the observation was cancelled by your app, or did fail with an error.

Look at the observation logs which start with value: make sure, again, that the expected value was not actually notified, then overwritten.

Finally, look at the observation logs which start with tracked region. Does the printed database region cover the expected changes?

For example:

empty: The empty region, which tracks nothing and never triggers the observation.
player(*): The full player table
player(id,name): The id and name columns of the player table
player(id,name)[1]: The id and name columns of the row with id 1 in the player table
player(*),team(*): Both the full player and team tables

If you happen to use the ValueObservation.trackingConstantRegion(_:) method and see a mismatch between the tracked region and your expectation, then change the definition of your observation by using tracking(_:). You should witness that the logs which start with tracked region now evolve in order to include the expected changes, and that you get the expected notifications.

If after all those steps (thanks you!), your observation is still failing you, please open an issue and provide a minimal reproducible example!

FAQ: Errors

Generic parameter 'T' could not be inferred

You may get this error when using the read and write methods of database queues and pools:

// Generic parameter 'T' could not be inferred
let string = try dbQueue.read { db in
    let result = try String.fetchOne(db, ...)
    return result
}

This is a limitation of the Swift compiler.

The general workaround is to explicitly declare the type of the closure result:

// General Workaround
let string = try dbQueue.read { db -> String? in
    let result = try String.fetchOne(db, ...)
    return result
}

You can also, when possible, write a single-line closure:

// Single-line closure workaround:
let string = try dbQueue.read { db in
    try String.fetchOne(db, ...)
}

Mutation of captured var in concurrently-executing code

The insert and save persistence methods can trigger a compiler error in async contexts:

var player = Player(id: nil, name: "Arthur")
try await dbWriter.write { db in
    // Error: Mutation of captured var 'player' in concurrently-executing code
    try player.insert(db)
}
print(player.id) // A non-nil id

When this happens, prefer the inserted and saved methods instead:

// OK
var player = Player(id: nil, name: "Arthur")
player = try await dbWriter.write { [player] db in
    return try player.inserted(db)
}
print(player.id) // A non-nil id

SQLite error 1 "no such column"

This error message is self-explanatory: do check for misspelled or non-existing column names.

However, sometimes this error only happens when an app runs on a recent operating system (iOS 14+, Big Sur+, etc.) The error does not happen with previous ones.

When this is the case, there are two possible explanations:

Maybe a column name is really misspelled or missing from the database schema.

To find it, check the SQL statement that comes with the DatabaseError.
Maybe the application is using the character " instead of the single quote ' as the delimiter for string literals in raw SQL queries. Recent versions of SQLite have learned to tell about this deviation from the SQL standard, and this is why you are seeing this error.

For example: this is not standard SQL: UPDATE player SET name = "Arthur".

The standard version is: UPDATE player SET name = 'Arthur'.

It just happens that old versions of SQLite used to accept the former, non-standard version. Newer versions are able to reject it with an error.

The fix is to change the SQL statements run by the application: replace " with ' in your string literals.

It may also be time to learn about statement arguments and SQL injection:
```
let name: String = ...

// NOT STANDARD (double quote)
try db.execute(sql: """
    UPDATE player SET name = "\(name)"
    """)

// STANDARD, BUT STILL NOT RECOMMENDED (single quote)
try db.execute(sql: "UPDATE player SET name = '\(name)'")

// STANDARD, AND RECOMMENDED (statement arguments)
try db.execute(sql: "UPDATE player SET name = ?", arguments: [name])

// STANDARD, AND RECOMMENDED (SQL interpolation)
try db.execute(literal: "UPDATE player SET name = \(name)")
```

For more information, see Double-quoted String Literals Are Accepted, and Configuration.acceptsDoubleQuotedStringLiterals.

SQLite error 10 "disk I/O error", SQLite error 23 "not authorized"

Those errors may be the sign that SQLite can't access the database due to data protection.

When your application should be able to run in the background on a locked device, it has to catch this error, and, for example, wait for UIApplicationDelegate.applicationProtectedDataDidBecomeAvailable(_😃 or UIApplicationProtectedDataDidBecomeAvailable notification and retry the failed database operation.

do {
    try ...
} catch DatabaseError.SQLITE_IOERR, DatabaseError.SQLITE_AUTH {
    // Handle possible data protection error
}

This error can also be prevented altogether by using a more relaxed file protection.

SQLite error 21 "wrong number of statement arguments" with LIKE queries

You may get the error "wrong number of statement arguments" when executing a LIKE query similar to:

let name = textField.text
let players = try dbQueue.read { db in
    try Player.fetchAll(db, sql: "SELECT * FROM player WHERE name LIKE '%?%'", arguments: [name])
}

The problem lies in the '%?%' pattern.

SQLite only interprets ? as a parameter when it is a placeholder for a whole value (int, double, string, blob, null). In this incorrect query, ? is just a character in the '%?%' string: it is not a query parameter, and is not processed in any way. See https://www.sqlite.org/lang_expr.html#varparam for more information about SQLite parameters.

To fix the error, you can feed the request with the pattern itself, instead of the name:

let name = textField.text
let players: [Player] = try dbQueue.read { db in
    let pattern = "%\(name)%"
    return try Player.fetchAll(db, sql: "SELECT * FROM player WHERE name LIKE ?", arguments: [pattern])
}

Sample Code

The Documentation is full of GRDB snippets.
Demo Applications
Open GRDB.xcworkspace: it contains GRDB-enabled playgrounds to play with.
groue/SortedDifference: How to synchronize a database table with a JSON payload

Thanks

Pierlis, where we write great software.
@alextrob, @alexwlchan, @bellebethcooper, @bfad, @cfilipov, @charlesmchen-signal, @Chiliec, @chrisballinger, @darrenclark, @davidkraus, @eburns-vmware, @felixscheinost, @fpillet, @gcox, @GetToSet, @gjeck, @guidedways, @gusrota, @haikusw, @hartbit, @holsety, @jroselightricks, @kdubb, @kluufger, @KyleLeneau, @layoutSubviews, @mallman, @MartinP7r, @Marus, @mattgallagher, @MaxDesiatov, @michaelkirk-signal, @mtancock, @pakko972, @peter-ss, @pierlo, @pocketpixels, @pp5x, @professordeng, @robcas3, @runhum, @sberrevoets, @schveiguy, @SD10, @sobri909, @sroddy, @steipete, @swiftlyfalling, @Timac, @tternes, @valexa, @wuyuehyang, @ZevEisenberg, and @zmeyc for their contributions, help, and feedback on GRDB.
@aymerick and @kali because SQL.
ccgus/fmdb for its excellency.

URIs don't change: people change them.

Adding support for missing SQL functions or operators

This chapter was renamed to Embedding SQL in Query Interface Requests.

Advanced DatabasePool

This chapter has moved.

After Commit Hook

This chapter has moved.

Asynchronous APIs

This chapter has moved.

Changes Tracking

This chapter has been renamed Record Comparison.

Concurrency

This chapter has moved.

Custom Value Types

Custom Value Types conform to the DatabaseValueConvertible protocol.

Customized Decoding of Database Rows

This chapter has been renamed Beyond FetchableRecord.

Customizing the Persistence Methods

This chapter was replaced with Persistence Callbacks.

Database Changes Observation

This chapter has moved.

Database Configuration

This chapter has moved.

Database Queues

This chapter has moved.

Database Pools

This chapter has moved.

Database Snapshots

This chapter has moved.

DatabaseWriter and DatabaseReader Protocols

This chapter was removed. See the references of DatabaseReader and DatabaseWriter.

Date and UUID Coding Strategies

This chapter has been renamed Data, Date, and UUID Coding Strategies.

Dealing with External Connections

This chapter has been superseded by the Sharing a Database guide.

Differences between Database Queues and Pools

This chapter has moved.

Enabling FTS5 Support

FTS5 is enabled by default since GRDB 6.7.0.

FetchedRecordsController

FetchedRecordsController has been removed in GRDB 5.

The Database Observation chapter describes the other ways to observe the database.

Full-Text Search

This chapter has moved.

Guarantees and Rules

This chapter has moved.

Joined Queries Support

This chapter was replaced with the documentation of splittingRowAdapters(columnCounts:).

List of Record Methods

See Records and the Query Interface.

Migrations

This chapter has moved.

NSNumber and NSDecimalNumber

This chapter has moved.

Persistable Protocol

This protocol has been renamed PersistableRecord in GRDB 3.0.

PersistenceError

This error was renamed to RecordError.

Prepared Statements

This chapter has moved.

Record Class

The Record class is a legacy GRDB type. Since GRDB 7, it is not recommended to define record types by subclassing the Record class.

Row Adapters

This chapter has moved.

RowConvertible Protocol

This protocol has been renamed FetchableRecord in GRDB 3.0.

TableMapping Protocol

This protocol has been renamed TableRecord in GRDB 3.0.

Transactions and Savepoints

This chapter has moved.

Transaction Hook

This chapter has moved.

TransactionObserver Protocol

This chapter has moved.

Unsafe Concurrency APIs

This chapter has moved.

ValueObservation

This chapter has moved.

ValueObservation and DatabaseRegionObservation

This chapter has been superseded by ValueObservation and DatabaseRegionObservation.

pluk-inc/markdown-preview

A simple Markdown viewer for reading .md files

Markdown Preview

A fast, native macOS app for reading Markdown files.

Drop a .md on the icon (or set Markdown Preview as your default handler) and get a clean, scrollable preview with a real document outline — no Electron, no browser tab.

Installation

Markdown Preview is available in the official Homebrew cask repository:

brew install --cask markdown-preview

Or grab the latest signed and notarized DMG from the Releases page.

Screenshots

Edit Markdown directly with a native formatting toolbar:

Quick Look preview — spacebar a .md in Finder:

Customize the toolbar — drag in Print, Copy, Zoom and the rest from View → Customize Toolbar…

Features

Native rendering — WKWebView pipeline backed by swift-markdown, with heading anchors and link handling.
Edit Mode — edit Markdown in place with a formatting toolbar for headings, emphasis, lists, quotes, code, and links. Toggle it from the toolbar or with ⌘E, then save with ⌘S.
Mermaid diagrams — fenced mermaid code blocks render as diagrams in both the app and Quick Look previews, using a bundled renderer so previews work offline without a CDN request.
Math equations — LaTeX inline ( $x_1 + x_2$ ), display ($$\int_0^1 x^2\,dx$$), and fenced math blocks render with a bundled KaTeX. Selecting a rendered formula and copying yields the original LaTeX source (via the official copy-tex extension).
Document outline — sidebar TOC that mirrors your headings; click to jump.
Inspector panel — toggleable side panel with file metadata.
In-document search — toolbar search field plus standard ⌘F / ⌘G / ⌘⇧G for next/previous match.
Open With — switch to your real editor (VS Code, Cursor, Zed, Sublime, BBEdit, Nova, CotEditor, TextMate, MacVim, Xcode, TextEdit) without leaving the preview. The list filters to apps that actually declare an editor role for Markdown, and remembers your pick.
Open in LLM — send the current Markdown file to Codex, Claude, or ChatGPT from the toolbar. Supported apps open with file or folder context where possible, with a copy-and-open fallback for longer prompts.
Text zoom — bump preview text up or down with trackpad pinch, the toolbar's A A control, or ⌘+ / ⌘− / ⌘0. Discrete Safari-style stops from 50% to 300%.
Customizable toolbar — drag in the items you actually use (Print, Copy, Zoom, Sidebar, Open With, Inspector, Share, Search) via View → Customize Toolbar… Standard AppKit affordance, your layout sticks across launches.
Share = copy the source — the share toolbar feeds the picker the Markdown text itself, so Copy writes the raw source to the clipboard (great for pasting into ChatGPT / Claude), and Mail, Messages, and Notes get the content in the body instead of a file URL.
Quick Look extension — system-wide .md previews from Finder spacebar, Spotlight, and Mail attachments without launching the app.
Command line tools — install mdp, md-preview, and markdown-preview from the app menu, then open files or folders from any shell with commands like mdp README.md or mdp ..
Default handler — offers to register itself as the default .md opener on first launch.

Supported file types

.md, .markdown, .mdown, .txt UTI: net.daringfireball.markdown

Requirements

macOS 15 or later
Apple Silicon or Intel

Building from source

git clone git@github.com:pluk-inc/markdown-preview.git
cd markdown-preview
open markdown-preview.xcodeproj

Build and run the markdown-preview scheme. Swift Package Manager will resolve Sparkle, Sentry, and swift-markdown on first build.

Crash reporting

Release builds submit native crash reports to the pluk-inc/markdown-preview Sentry project. The integration does not collect performance traces, session data, breadcrumbs, network requests, user information, document contents, or file paths. Users can turn reporting off directly from Markdown Preview > Send Anonymous Crash Reports; on later launches, the Sentry SDK will not initialize at all.

The committed DSN is a public client key. Release archives upload the app dSYM with sentry-cli; authenticate locally with sentry-cli login and keep that authentication token outside the repository.

Project layout

md-preview/         Main app target (AppKit, WKWebView)
quick-look/         Quick Look extension (.appex)
scripts/            Release & rollback automation
Version.xcconfig    Marketing & build version (single source of truth)
appcast.xml         Sparkle update feed

Releasing

Releases are driven by Amore — it handles building, code signing, notarization, DMG creation, S3 upload, and Sparkle appcast publishing in one shot.

Bump MARKETING_VERSION and CURRENT_PROJECT_VERSION in Version.xcconfig, then:

./scripts/release.sh

Use ./scripts/rollback-release.sh to revert the appcast pointer if a release misbehaves.

Contributing

Pull requests are welcome. For larger changes, please open an issue first to discuss what you'd like to change.

Fork the repo and create your branch from main.
Run the app and verify the change end-to-end (UI changes need a manual smoke test — there's no UI test suite yet).
Keep PRs focused; one logical change per PR.
Match the existing Swift style (no formatter is enforced; mirror nearby code).

Special Sponsor

Support

Markdown Preview is free and MIT-licensed. If it saved you a browser tab, you can buy us a coffee.

Acknowledgments

Amore — MacOS release automation (signing, notarization, DMG, hosting, appcast)
swift-markdown — Markdown parser (Apple, cmark-gfm-backed)
Mermaid — Bundled diagram renderer for mermaid fenced code blocks
KaTeX — Bundled math typesetter for inline $…$ , display $$…$$, and ```math blocks
Sparkle — Auto-update framework
Sentry — Privacy-filtered native crash reporting
LottieFiles — Animated README logo

License

MIT

alienator88/Pearcleaner

A free, source-available and fair-code licensed mac app cleaner

Pearcleaner

Website

The only legitimate website owned by me is https://itsalin.com. Anything else offering Pearcleaner downloads is either a scam or not affiliated with me. More details HERE.

Project Status: On Hold

As you may have noticed, development on the app has basically stopped since end of 2025, so I wanted to provide some context.

Between a new job, joining a friend who is building a SaaS company, and other life priorities, I no longer have the time needed to actively maintain or continue development on the project.

Another major reason is that I previously relied on my work MacBook for development. After changing jobs, I no longer have access to a Mac device that I can use for personal development work, which means I’m currently unable to build, test, or release updates for the app.

Because of that, issue responses, feature work, PR reviews, and new releases are effectively on hold indefinitely for now.

The project is not abandoned entirely, and I’d still like to return to it someday if circumstances change. For now though, I want to be transparent that active development is no longer possible on my end.

Thank you to everyone who has used the app, reported issues, submitted ideas, or contributed. I genuinely appreciate all of the support the project has received.

Status: On Hold
Version: 5.4.3
Download · Commits

A free, source-available and fair-code licensed Mac app cleaner inspired by Freemacsoft's AppCleaner and Sun Knudsen's Privacy Guides post on his app-cleaner script. This project was born out of wanting to learn more on how macOS deals with app installation/uninstallation and getting more Swift experience. If you have suggestions I'm open to hearing them, submit a feature request!

Features

Core

App Uninstall • Orphaned File Search • Development Environment Manager • File Search • Homebrew Manager • App Lipo • PKG Manager • Plugin Manager • Services Manager • Apps Updater
Drag/drop apps, CLI support, and deep link automation view
List or Grid view with badges for web/iOS apps
Finder Extension for right-click uninstall
Pearcleaner self-uninstall and other options

Utilities

Prune unused app translations, keeping only preferred languages
Strip unneeded architectures from universal apps without requirement of lipo binary from xcode tools
Sentinel Monitor: Automatic cleanup when apps hit Trash (~2MB RAM)
Export app bundles and file lists
Basic Steam games support

Customization

Theme system with custom colors
Include/exclude directories for searching
Adjustable search sensitivity

Screenshots

Issues

Warning

When submitting issues, please use the appropriate issue template corresponding with your problem HERE
Issues with no template will be closed
This is a personal/hobby app, therefore the project is fairly opinionated. Opinion-based requests (e.g., “the layout would look better this way”) will not be considered.

Requirements

Note

Full Disk permission to search for files
Privileged Helper to perform actions on system folders

macOS Version	Codename	Supported
13.x	Ventura	✅
14.x	Sonoma	✅
15.x	Sequoia	✅
26.x	Tahoe	✅
TBD	Beta	❌

Versions prior to macOS 13.0 are not supported due to missing Swift/SwiftUI APIs required by the app.

Getting Pearcleaner

Releases

Pre-compiled, always up-to-date versions are available from my releases page.

Homebrew

You can add the app via Homebrew:

brew install --cask pearcleaner

Translations

If you are able to contribute to translations for the app, please see this discussion: https://github.com/alienator88/Pearcleaner/discussions/137

License

Important

Pearcleaner is licensed under Apache 2.0 with Commons Clause. This means that you can do anything you'd like with the source, modify it, contribute to it, etc., but the license explicitly prohibits any form of monetization for Pearcleaner or any modified versions of it. See full license HERE

Thanks

Much appreciation to Freemacsoft's AppCleaner and Sun Knudsen's app-cleaner script for the inspiration
DharsanB for sponsoring my Apple Developer account

Some of my apps

Pearcleaner - An opensource app cleaner with privacy in mind

Sentinel - A GUI for controlling gatekeeper status on your Mac

Viz - Utility for extracting text from images, videos, qr/barcodes

PearHID - Remap your macOS keyboard with a simple SwiftUI frontend

ChartsOrg/Charts

Beautiful charts for iOS/tvOS/OSX! The Apple side of the crossplatform MPAndroidChart.

Version 4.0.0, synced to MPAndroidChart #f6a398b

Just a heads up: Charts 5.0 has some breaking changes. Charts has now been renamed DGCharts to prevent conflicts with Apple's new Swift Charts. Please read the release/migration notes.

One more heads up: As Swift evolves, if you are not using the latest Swift compiler, you shouldn't check out the master branch. Instead, you should go to the release page and pick up whatever suits you.

Xcode 14 / Swift 5.7 (master branch)
iOS >= 12.0 (Use as an Embedded Framework)
tvOS >= 12.0
macOS >= 10.13

Okay so there's this beautiful library called MPAndroidChart by Philipp Jahoda which has become very popular amongst Android developers, but there was no decent solution to create charts for iOS.

I've chosen to write it in Swift as it can be highly optimized by the compiler, and can be used in both Swift and ObjC project. The demo project is written in ObjC to demonstrate how it works.

An amazing feature of this library now, for Android, iOS, tvOS and macOS, is the time it saves you when developing for both platforms, as the learning curve is singleton- it happens only once, and the code stays very similar so developers don't have to go around and re-invent the app to produce the same output with a different library. (And that's not even considering the fact that there's not really another good choice out there currently...)

Having trouble running the demo?

ChartsDemo/ChartsDemo.xcodeproj is the demo project for iOS/tvOS
ChartsDemo-OSX/ChartsDemo-OSX.xcodeproj is the demo project for macOS
Make sure you are running a supported version of Xcode.
- Usually it is specified here a few lines above.
- In most cases it will be the latest Xcode version.
Make sure that your project supports Swift 5.0
Optional: Run carthage checkout in the project folder, to fetch dependencies (i.e testing dependencies).
- If you don't have Carthage - you can get it here.

Usage

In order to correctly compile:

Drag the DGCharts.xcodeproj to your project
Go to your target's settings, hit the "+" under the "Frameworks, Libraries, and Embedded Content" section, and select the DGCharts.framework
@import DGCharts
When using Swift in an ObjC project:

You need to import your Bridging Header. Usually it is "YourProject-Swift.h", so in ChartsDemo it's "ChartsDemo-Swift.h". Do not try to actually include "ChartsDemo-Swift.h" in your project 😃
(Xcode 8.1 and earlier) Under "Build Options", mark "Embedded Content Contains Swift Code"
(Xcode 8.2+) Under "Build Options", mark "Always Embed Swift Standard Libraries"

When using Realm.io:
- Note that the Realm framework is not linked with Charts - it is only there for optional bindings. Which means that you need to have the framework in your project, and in a compatible version to whatever is compiled with DGCharts. We will do our best to always compile against the latest version.
- You'll need to add ChartsRealm as a dependency too.

3rd party tutorials

Video tutorials

Blog posts

Want your tutorial to show here? Create a PR!

Troubleshooting

Can't compile?

Please note the difference between installing a compiled framework from CocoaPods or Carthage, and copying the source code.
Please read the Usage section again.
Search in the issues
Try to politely ask in the issues section

CocoaPods Install

Add pod 'DGCharts' to your Podfile. "DGCharts" is the name of the library.
For Realm support, please add pod 'ChartsRealm' too.

Note: ~~pod 'ios-charts'~~ is not the correct library, and refers to a different project by someone else.

Carthage Install

DGCharts now include Carthage prebuilt binaries.

github "ChartsOrg/Charts" == 5.1.0
github "ChartsOrg/Charts" ~> 5.1.0

In order to build the binaries for a new release, use carthage build --no-skip-current && carthage archive Charts.

Swift Package Manager Install

Swift Package Manager

dependencies: [
    .package(url: "https://github.com/ChartsOrg/Charts.git", .upToNextMajor(from: "5.1.0"))
]

3rd party bindings

Xamarin (by @Flash3001): iOS - GitHub/NuGet. Android - GitHub/NuGet.

Help

If you like what you see here, and want to support the work being done in this repository, you could:

Contribute code, issues and pull requests
Let people know this library exists (🔥 spread the word 🔥)
(You can buy me a beer, or you can buy me dinner 😃

Note: The author of MPAndroidChart is the reason that this library exists, and is accepting donations on his page. He deserves them!

Questions & Issues

If you are having questions or problems, you should:

Make sure you are using the latest version of the library. Check the release-section.
Study the Android version's Documentation-Wiki
Search or open questions on stackoverflow with the ios-charts tag
Search known issues for your problem (open and closed)
Create new issues (please 🔥 search known issues before 🔥, do not create duplicate issues)∏

Features

Core features:

8 different chart types
Scaling on both axes (with touch-gesture, axes separately or pinch-zoom)
Dragging / Panning (with touch-gesture)
Combined-Charts (line-, bar-, scatter-, candle-stick-, bubble-)
Dual (separate) Axes
Customizable Axes (both x- and y-axis)
Highlighting values (with customizable popup-views)
Save chart to camera-roll / export to PNG/JPEG
Predefined color templates
Legends (generated automatically, customizable)
Animations (build up animations, on both x- and y-axis)
Limit lines (providing additional information, maximums, ...)
Fully customizable (paints, typefaces, legends, colors, background, gestures, dashed lines, ...)
Plotting data directly from Realm.io mobile database (here)

Chart types:

Screenshots are currently taken from the original repository, as they render exactly the same 😃

LineChart (with legend, simple design)
LineChart (with legend, simple design)
LineChart (cubic lines)
LineChart (gradient fill)
Combined-Chart (bar- and linechart in this case)
BarChart (with legend, simple design)

BarChart (grouped DataSets)

Horizontal-BarChart

PieChart (with selection, ...)

ScatterChart (with squares, triangles, circles, ... and more)

CandleStickChart (for financial data)

BubbleChart (area covered by bubbles indicates the value)

RadarChart (spider web chart)

Documentation

Currently there's no need for documentation for the iOS/tvOS/macOS version, as the API is 95% the same as on Android.
You can read the official MPAndroidChart documentation here: Wiki

Or you can see the Charts Demo project in both Objective-C and Swift (ChartsDemo-iOS, as well as macOS ChartsDemo-macOS) and learn the how-tos from it.

Special Thanks

Goes to @liuxuan30, @pmairoldi, @jjatie and @AlBirdie for new features, bugfixes, and lots and lots of involvement in our open-sourced community! You guys are a huge help to all of those coming here with questions and issues, and I couldn't respond to all of those without you.

Our amazing sponsors

Debricked: Use open source securely

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

zachlatta/freeflow

Free & fast alternative to Wispr Flow

FreeFlow

Free and open source alternative to Wispr Flow, Superwhisper, and Monologue.

⬇ Download FreeFlow.dmg
_{Works on all Macs (Apple Silicon + Intel)}

Thank you to @marcbodea for maintaining FreeFlow!

Overview

FreeFlow is a free Mac dictation app inspired by Wispr Flow, Superwhisper, and Monologue. It gives you fast AI transcription, context-aware cleanup, and voice-driven text editing without a monthly subscription.

Quick Start

Download the app from above or click here
Get a free Groq API key from groq.com
Hold Fn to talk, or tap Command-Fn to start and stop dictation, and have whatever you say pasted into the current text field

Features

Custom shortcuts: Customize both hold-to-talk and toggle dictation shortcuts. If your toggle shortcut extends your hold shortcut, you can start in hold mode and press the extra modifier keys to latch into tap mode without stopping the recording.
Context-aware cleanup: FreeFlow can read nearby app context so names, terms, and phrases are spelled correctly when you dictate into email, terminals, docs, and other apps.
Custom vocabulary: Add names, jargon, and project-specific words that FreeFlow should preserve during cleanup.
OpenAI-compatible providers: Use Groq by default, or configure a custom model and API URL in settings.

Edit Mode

Edit Mode lets you highlight existing text and transform it with a spoken instruction, like "make this shorter" or "turn this into bullets." Enable it in settings, then use your normal dictation shortcut on selected text, or choose Manual mode to require an extra modifier key.

Privacy

There is no FreeFlow server, so FreeFlow does not store or retain your data. The only information that leaves your computer are API calls to your configured transcription and LLM provider.

Custom Cleanup

If you'd rather keep cleanup more literal and less context-aware, you can paste this simpler prompt into the custom system prompt setting:

Simple post-processing prompt

You are a dictation post-processor. You receive raw speech-to-text output and return clean text ready to be typed into an application.

Your job:
- Remove filler words (um, uh, you know, like) unless they carry meaning.
- Fix spelling, grammar, and punctuation errors.
- When the transcript already contains a word that is a close misspelling of a name or term from the context or custom vocabulary, correct the spelling. Never insert names or terms from context that the speaker did not say.
- Preserve the speaker's intent, tone, and meaning exactly.

Output rules:
- Return ONLY the cleaned transcript text, nothing else. So NEVER output words like "Here is the cleaned transcript text:"
- If the transcription is empty, return exactly: EMPTY
- Do not add words, names, or content that are not in the transcription. The context is only for correcting spelling of words already spoken.
- Do not change the meaning of what was said.

Example:
RAW_TRANSCRIPTION: "hey um so i just wanted to like follow up on the meating from yesterday i think we should definately move the dedline to next friday becuz the desine team still needs more time to finish the mock ups and um yeah let me know if that works for you ok thanks"

Then your response would be ONLY the cleaned up text, so here your response is ONLY:
"Hey, I just wanted to follow up on the meeting from yesterday. I think we should definitely move the deadline to next Friday because the design team still needs more time to finish the mockups. Let me know if that works for you. Thanks."

Using a Local Model

FreeFlow can use OpenAI-compatible local or self-hosted providers instead of Groq. In settings, configure the API base URL and model IDs for your local LLM provider, such as Ollama, LM Studio, or another OpenAI-compatible server. If your transcription backend uses a different endpoint from your LLM backend, set the transcription API URL separately.

Local models are often slower than hosted providers, especially on cold start, long recordings, or busy hardware.

Configure longer timeouts for local models

FreeFlow keeps the default network timeout at 20 seconds, but you can extend it with macOS defaults:

defaults write com.zachlatta.freeflow transcription_timeout_seconds -float 120
defaults write com.zachlatta.freeflow post_processing_timeout_seconds -float 120
defaults write com.zachlatta.freeflow context_request_timeout_seconds -float 120

The timeout keys are:

transcription_timeout_seconds: audio transcription requests
post_processing_timeout_seconds: transcript cleanup and edit mode requests
context_request_timeout_seconds: nearby app context requests

Only positive values are used. Remove a custom timeout to return to the 20-second default:

defaults delete com.zachlatta.freeflow transcription_timeout_seconds
defaults delete com.zachlatta.freeflow post_processing_timeout_seconds
defaults delete com.zachlatta.freeflow context_request_timeout_seconds

License

Licensed under the MIT license.

GitHub Swift Weekly Trending Repositories

Lakr233/vphone-cli

vphone-cli

Prerequisites

Install

Build

Quick Start

Commands

Manage

Build a VM manually (what vm create automates)

Firmware Variants

Running & Connecting

Locations

SIP/AMFI Relaxation

Tested Environments

FAQ

Automation

Acknowledgements

utmapp/UTM

UTM

Features

Additional macOS Features

UTM SE

Install

Development

Related

License

BarutSRB/OmniWM

Demo Video

Contributors

🏢 By Employer

🎓 By Education

✨ All Contributors

Known Limitations

Performance & Trust

Requirements

Installation

Homebrew

Nix

GitHub Releases

Updates

Documentation

IPC and CLI

Quick Start

User Guide

Multi-Monitor Setup

Layout Modes

Keyboard Shortcuts

Workspace

Focus

Move Window

Monitor

Layout

Container and Column

Dwindle Groups

Quake Terminal (Inside Terminal)

Features

Quake Terminal

Command Palette

Menu Anywhere

Overview Mode

Workspace Bar

Hidden Bar

Tips

Configuration

App Rules

Building from Source

Related Forks

Support

Reporting Bugs

Contributing

License

nikitabobko/AeroSpace

AeroSpace Beta

Key features

Installation

Community, discussions, issues

Project status

Development

Project values

Build a VM manually (what `vm create` automates)

Git `pre-commit` Hook