pg_client_mobile

Android-first Flutter PostgreSQL mobile GUI client.

Screenshots

Click any thumbnail to open full size.

Open full screenshot gallery (14 images)

Project Overview

This app lets you connect directly to PostgreSQL over private network/VPN using native TCP/SSL.
There is no backend proxy or middleware. Credentials are stored securely on device.

Core stack:

• Flutter / Dart
• postgres
• flutter_riverpod + codegen
• go_router
• flutter_secure_storage
• sqflite
• local_auth
• re_highlight
• share_plus

What The App Does

• Biometric app lock on open (degrades gracefully if biometrics unavailable).
• Save multiple DB connection profiles securely.
• Browse databases/schemas and objects (tables/views/materialized views).
• Internal pg_* schemas hidden by default (toggle to show).
• Searchable schema picker.
• SQL editor with syntax highlight and query tabs.
• SQL editor supports EXPLAIN / EXPLAIN ANALYZE with option toggles.
• SQL editor supports canceling a running query.
• Session timeout controls in SQL editor (statement_timeout, lock_timeout).
• Ctrl+Enter / Cmd+Enter runs SQL through the same safety-guarded flow as Run menu.
• SQL editor action confirmations for:
  • BEGIN, COMMIT, ROLLBACK
  • Clear SQL
  • Apply session timeouts
• SQL editor menu clearly distinguishes:
  • History (saved SQL)
  • Execution Logs (run trace)
• Single active DB session at a time (prevents stale connection/state drift).
• Transaction controls: BEGIN, COMMIT, ROLLBACK.
• Query history stored locally (supports transaction/tab-scoped history view).
• SQL execution logs stored locally (success/failure, duration, row count, error).
• Application event logs stored locally (session/safety/transaction events).
• Query result table with pagination + CSV export.
• EXPLAIN results rendered in a formatted plan view (tree + key metrics).
• Data tab UX for tables:
  • compact 1-row filter bar
  • quick "Open in SQL Editor" action with prefilled table query
  • sort options via bottom sheet
  • row details sheet for full values + edit action
• DDL tab:
  • one-tap Copy DDL button (table/view/materialized view)

Safety Model

• Active connection banner always shows current target and mode.
• Banner quick actions on Databases/Objects:
  • toggle read-only
  • open SQL editor
  • disconnect and return to Connections
• Production-like targets are detected (default keywords + custom allow/deny rules).
• Production sessions default to read-only.
• Turning off read-only on production requires typing PROD.
• SQL execution guards:
  • Write SQL (INSERT, UPDATE, DELETE, etc.) requires confirmation.
  • Dangerous SQL (TRUNCATE, DROP TABLE, DROP DATABASE, ALTER) requires hard typed confirmation.
• Strict policy setting:
  • block_dangerous_sql_on_production (default: true)
  • If enabled, dangerous SQL is blocked on production targets and user is prompted to change Safety Settings first.
• App Logs screen:
  • filter by INFO / WARN / ERROR
  • copy visible logs
  • clear local app logs
  • accessible from Connections -> Settings -> App Logs

User Flow

flowchart TD
  A["Splash"] --> B["Biometric Lock"]
  B --> C["Connection List"]
  C --> D["Add Connection"]
  C --> E["Database List"]
  E --> F["Table List (search)"]
  F --> G["Table Structure"]
  F --> H["SQL Editor (tabs + tx controls)"]
  H --> I["Query Result (paginated + CSV export)"]
  H --> J["History Sheet (tx/tab scoped)"]

Loading

Repository Structure

• lib/app/: app bootstrap, theme, routing.
• lib/features/connection/: secure connection models/repository/providers/screens.
• lib/features/database/: database + table listing providers/screens.
• lib/features/schema/: schema inspection providers/screens.
• lib/features/query/: query session engine, SQL execution, history, results.
• lib/shared/: reusable widgets + utility helpers.
• test/: unit/widget coverage for core safety/formatting/config behavior.
• CODEX.md: evolving project memory + status.
• AGENTS.md: agent working rules for this repo.

Setup

Prerequisites:

• Flutter >=3.29.0
• Dart >=3.7.0
• Android SDK

Install and generate code:

flutter pub get
flutter pub run build_runner build --delete-conflicting-outputs

Quality checks:

flutter test
flutter analyze

Run on Android device/emulator:

flutter run -d <android-device-id>

Run Android emulator:

flutter emulators
flutter emulators --launch  <android-emulator-id>

Build debug APK:

flutter build apk --debug

Output:

• build/app/outputs/flutter-apk/app-debug.apk

Build release APK:

flutter build apk --release

Output:

• build/app/outputs/flutter-apk/app-release.apk

Install APK on a connected phone:

adb install -r build/app/outputs/flutter-apk/app-debug.apk
# or release
adb install -r build/app/outputs/flutter-apk/app-release.apk

Install to a specific device (if multiple devices connected):

adb -s <device-id> install -r build/app/outputs/flutter-apk/app-debug.apk

Android Notes

• minSdk = 23 is configured in android/app/build.gradle.kts.
• MainActivity uses FlutterFragmentActivity for local_auth compatibility.
• Android app label is PG Client Mobile.
• Launcher icon uses assets/images/app_logo.png and is applied to Android mipmap resources.
• First flutter run may auto-upgrade Android Gradle files; review those diffs before committing.

Author Notes

• Keep secrets out of git (.gitignore is hardened for env/keys/dumps).
• Use Safety Settings to tune production detection rules.
• If you see build_runner analyzer language-version warnings, they are non-blocking if flutter test and flutter analyze are clean.

License

This project is licensed under the MIT License. See LICENSE.