About the Project
Rowcraft is a desktop workspace for exploring databases, writing queries, and inspecting results. SQL databases, document stores, key-value stores, and HTTP APIs share a connection explorer, with consoles adapted to their query languages.
The desktop and command-line app share a Rust engine, so saved connections and database behavior stay consistent across both interfaces.
Features
- Database explorer: browse schemas, tables, views, columns, indexes, keys, and routines where the connector exposes them.
- Query consoles: SQL, MongoDB shell statements, Redis commands, CQL, PartiQL, SQL++, Cypher, and GraphQL, depending on the selected source.
- Results workspace: virtualized tables, JSON views, and charts for supported result shapes.
- Persistent sessions: switch between tabs without reconnecting or rerunning existing results. Consoles for the same source share its backend session and transaction state.
- Connection management: saved sources, connection testing, schema filters, custom drivers, and SSH tunnels.
- SQLite file import: open a local database or import a validated copy through the desktop UI.
- Optional AI assistance: query help through a configurable gateway, with optional local 9router integration.
- Headless CLI: run queries, export results, inspect catalogs, and manage sources without starting the desktop app.
The desktop uses the system webview. Database operations run in Rust, and production frontend assets are embedded in the application.
Project Status
Rowcraft is in early development. Connector coverage and validation vary by database; a driver appearing in the catalog does not mean every vendor, version, or feature has been tested. See the support table and connector boundaries before choosing a connection.
Rowcraft is an independently developed database workbench. Performance claims require measurements against equivalent workloads.
Database packages come directly from upstream suppliers and are kept in Rowcraft's own storage; the complete download list is maintained in the driver catalog.
Built With
| Layer | Technology |
|---|
| Database engine and CLI | Rust, Tokio, Clap |
| Desktop shell | Tauri 2 and the system webview |
| Interface | React, TypeScript, Vite, Tailwind CSS |
| Query editor | CodeMirror |
| Result grid | TanStack Virtual |
| Database connectivity | Rust drivers, HTTP APIs, compatible wire protocols, JDBC |
Getting Started
Prerequisites
For desktop development, install:
| Tool | Requirement |
|---|
| Rust | Stable toolchain; see rust-toolchain.toml |
| Node.js | 24, matching the installer workflow |
| pnpm | 11.6.0, pinned in the desktop package |
| Native build tools | Xcode command-line tools on macOS; Visual Studio C++ Build Tools and Windows SDK on Windows; WebKitGTK 4.1 and development libraries on Linux |
Follow the Tauri platform prerequisites for the complete native dependency list. Java 11+ and vendor driver JARs are needed only for JDBC connections. SQLite is bundled and needs no separate server.
Installation
-
Clone the repository:
git clone https://github.com/Sarfraz-droid/Rowcraft.git
cd Rowcraft
-
Install frontend dependencies and start the desktop app:
pnpm --dir apps/rowcraft-desktop install --frozen-lockfile
pnpm --dir apps/rowcraft-desktop tauri dev
On macOS and Linux, the Makefile provides the same workflow:
make gui-install
make run-gui
To produce a distributable application, follow Build Installers.
Usage
Connect and Query
- Select + Add and choose a database type.
- Enter connection details and use Test Connection.
- Save the source and select it in the explorer to connect.
- Open a console and run a statement with Cmd+Enter on macOS or Ctrl+Enter elsewhere. A selected statement runs instead of the whole editor.
The default result limit is 1,000 rows. Use explicit server-side limits when exploring large datasets.
Try SQLite without a server
With the sqlite3 command installed, this creates a small disposable database and opens the desktop app with a separate configuration:
make desktop-demo
Demo data lives under .dev/. Running the command again recreates its database and configuration.
To use your own file, choose + Add → SQLite → Upload SQLite file…. Rowcraft imports a copy into <config-dir>/sqlite-imports/; the upload limit is 256 MB. For larger files, enter the local database path directly.
Preview the interface in a browser
make web
Open http://localhost:1420. This development preview uses mock data. Real connections, SQLite imports, and database queries require the desktop app.
Command-line Interface
The CLI binary is named rowcraft. To build it:
cargo build --release -p rowcraft-cli
The executable is target/release/rowcraft on macOS/Linux and target/release/rowcraft.exe on Windows. The examples below use cargo run so no PATH setup is required.
Query a local SQLite database
cargo run -p rowcraft-cli -- ds add local-sqlite --dialect sqlite --database /absolute/path/to/example.sqlite
cargo run -p rowcraft-cli -- ds test local-sqlite
cargo run -p rowcraft-cli -- query -d local-sqlite "SELECT sqlite_version();"
cargo run -p rowcraft-cli -- introspect -d local-sqlite -f json
Connect to PostgreSQL
Set APP_PW in your shell to the database password, then save a reference to that environment variable:
cargo run -p rowcraft-cli -- ds add local-pg \
--host localhost --port 5432 --database app --user me --password-env APP_PW
cargo run -p rowcraft-cli -- ds test local-pg
cargo run -p rowcraft-cli -- query -d local-pg -f csv "SELECT * FROM people LIMIT 1000;" > people.csv
cargo run -p rowcraft-cli -- introspect -d local-pg -s public
The desktop app reads the same saved sources. When a source uses an environment-variable password, launch the desktop app from a shell where that variable is set.
Discover commands and drivers
cargo run -p rowcraft-cli -- --help
cargo run -p rowcraft-cli -- dialects
cargo run -p rowcraft-cli -- drivers
cargo run -p rowcraft-cli -- ds --help
cargo run -p rowcraft-cli -- query --help
Run SQL over HTTP
rowcraft serve starts a local HTTP API on 127.0.0.1:7878. Every saved data source gets its own endpoints, including sources added in the desktop app. Use it from curl, Postman, or test suites:
cargo run -p rowcraft-cli -- serve
curl -s http://127.0.0.1:7878/datasources
curl -s -X POST http://127.0.0.1:7878/datasources/local-pg/query --data-binary 'SELECT * FROM people LIMIT 10'
See the HTTP API for every endpoint, response shape, and security rule.
CLI exit codes are 0 for success, 1 for statement errors, 2 for connection/authentication errors, and 3 for usage/configuration errors.
Database Support
Rowcraft uses Rust drivers, HTTP connectors, compatible wire protocols, and a JDBC bridge. The table records the validation described in this repository; it is not a guarantee for every deployment.
| Database or family | Connection path | Validation / limitations |
|---|
| PostgreSQL, YugabyteDB | PostgreSQL driver | Live-server verification recorded |
| SQLite | Bundled SQLite | Local-file round trips verified |
| MySQL, MariaDB; Aurora MySQL, TiDB, SingleStore via MySQL | MySQL driver | MySQL 9.7 verified; other variants need live validation |
| Redshift, Greenplum, CockroachDB | PostgreSQL protocol | Greenplum path tested against PostgreSQL 14; vendor validation remains |
| Vertica | PostgreSQL protocol | No live verification; authentication support is limited |
| H2 | PostgreSQL server mode | Requires H2 PG server mode; no live verification |
| MongoDB, DocumentDB | MongoDB driver | MongoDB 7 verified; supported shell statements only |
| Redis | Redis driver | Live-server verification recorded |
| Cassandra | Scylla/Cassandra driver | Cassandra 5 verified |
| DynamoDB | PartiQL over HTTP | DynamoDB Local verified |
| Trino, Presto | HTTP statement protocol | Trino verified; Presto needs live validation |
| ClickHouse | HTTP | Request-format tests with a fake server |
| SQL Server, Azure SQL, Synapse | TDS driver | SQL authentication; unit tests only |
| Snowflake | REST API | Password authentication; unit tests only |
| Couchbase | Query service HTTP API | Unit tests only |
| Neo4j, GraphQL APIs | HTTP | Unit tests; live-server verification pending |
| Oracle, Db2, Derby, HSQLDB, Exasol, Hive, Spark, BigQuery, Athena, DuckDB, Databricks, Firebird, Informix, HANA, Teradata, and other catalog entries | JDBC | Java 11+, vendor JARs, and a reachable database required; coverage varies |
For native query languages, endpoint configuration, introspection behavior, and unsupported features, read database consoles and support boundaries. Connection options that are implemented versus only stored are documented in data source options.
JDBC and custom drivers
Create a driver under + Add → Drivers → + Custom driver. A JDBC driver needs its JARs, a driver class when auto-discovery is unavailable, and a URL template. Templates support {host}, {port}, {database}, and {user}.
For built-in JDBC entries, click Download driver in connection setup or the Drivers view to install the driver and its dependencies directly from Maven Central. No Python or Maven is needed for UI downloads; a standalone Java runtime is required for JDBC connections. You can also place JARs under <config-dir>/jdbc/<driver-id>/ or configure jdbc.jars, jdbc.class, and jdbc.url_template in Advanced. Downloads and pinned upstream coordinates are maintained in our driver catalog. See driver setup for vendor-only packages, Java setup, and terminal installation. The app never searches another application for drivers or Java.
Use ROWCRAFT_JAVA to select a Java executable or set JAVA_HOME. See JDBC setup for details.
Configuration and Credentials
Desktop and CLI sources share the same configuration directory:
| Platform | Default directory |
|---|
| macOS / Linux | ~/.config/rowcraft/ |
| Windows | %APPDATA%\rowcraft\ |
XDG_CONFIG_HOME overrides the default base directory when set. ROWCRAFT_CONFIG_DIR overrides the entire configuration path on every platform.
Sources live in datasources.toml, custom drivers in drivers.toml, and shared SSH configurations in ssh.toml. Database passwords can be resolved from environment variables; desktop credential storage also uses references to the operating system credential store.
TLS is enabled by default for non-loopback SQL connections through the default connection policy. Connector-specific rules apply: for example, MongoDB Auto follows MongoDB URI defaults. Use verified TLS and database-side permissions appropriate to your environment; see the connection options.
SSH tunnels support password, key-pair, and agent authentication through Rust, without requiring an external ssh command. Unknown hosts are refused by default; accept-new can explicitly trust new hosts, while changed host keys remain rejected.
Optional AI setup
Open Settings → AI to configure a gateway and model. The optional local 9router setup requires Node.js 22+ with npm and internet access on first start. The app can also connect to an existing compatible gateway.
AI requests can include conversation content, schema metadata, and sampled results when database tools are used. Choose a provider and data-access policy suitable for your database. Automatic query execution is restricted to supported read-only SQL backends; a supported console language does not automatically enable AI execution for that connector.
Build Installers
Build a release executable without packaging:
make gui
Build installers for your current operating system:
pnpm --dir apps/rowcraft-desktop installer
# Or, on macOS/Linux:
make installer
Builds run the frontend production build and embed its assets. Output goes under target/release/bundle/, or target/<triple>/release/bundle/ when a target is specified.
| Platform | Configured outputs |
|---|
| macOS Apple Silicon / Intel | .app, .dmg |
| Windows x64 | NSIS .exe |
| Linux x64 | .AppImage, .deb, .rpm |
The Desktop installers workflow builds all four OS/architecture combinations on a manual run. Pushing an v<VERSION> tag creates a draft GitHub release. macOS builds use ad-hoc signing unless distribution credentials are provided; Windows signing is not configured by default.
See installer builds and signing for native dependencies, versioning, signing secrets, and release steps. See package distribution for website downloads and package-manager publishing.
Development and Testing
| Command | Purpose |
|---|
make build | Build the Rust workspace excluding the desktop shell |
make run-gui | Run the desktop app with frontend hot reload |
make web | Run the mock browser preview |
make test | Run Rust tests excluding the desktop shell |
make lint | Run Clippy with warnings treated as errors |
make fmt | Format Rust source |
make test-desktop | Type-check the frontend, test UI helpers and services, and check the desktop shell |
make test-live | Start the disposable PostgreSQL instance and run live-enabled tests |
make test-ssh | Start the disposable SSH fixture and run tunnel tests |
make landing | Serve the static landing page on port 4321 |
make landing-check | Check landing-page JavaScript and run its tests |
The PostgreSQL fixture needs local PostgreSQL tools; the SSH fixture needs OpenSSH server tools. Both use .dev/. Live PostgreSQL tests are skipped unless ROWCRAFT_TEST_PG_PORT is configured; make test-live configures it for the fixture.
Direct commands are useful on Windows or when working on one part of the project:
cargo fmt --all -- --check
cargo clippy --workspace --exclude rowcraft-desktop --all-targets -- -D warnings
cargo test --workspace --exclude rowcraft-desktop
pnpm --dir apps/rowcraft-desktop typecheck
pnpm --dir apps/rowcraft-desktop test
cargo test -p rowcraft-ui-model
cargo check -p rowcraft-desktop
The CI workflow defines the checks run on pushes to main and pull requests.
Architecture
The desktop and CLI share the Rust database engine. The Tauri shell exposes commands to React through IPC; reusable workbench logic lives in rowcraft-ui-model. Database-specific behavior is implemented behind the rowcraft-dialect traits.
apps/rowcraft-desktop/src React, TypeScript, CodeMirror, result views
│ Tauri IPC
apps/rowcraft-desktop/src-tauri Desktop shell and command bridge
│
crates/rowcraft-ui-model Workbench services and validation
│
apps/rowcraft-cli ──────────────── Shared Rust engine and configuration
│
dialects/* → Drivers, HTTP APIs, JDBC, wire/*
| Path | Contents |
|---|
apps/rowcraft-desktop/ | Desktop frontend and Tauri shell |
apps/rowcraft-cli/ | The rowcraft command-line application |
apps/landing/ | Static product website and download configuration |
crates/ | Shared engine, configuration, catalog models, SQL helpers, I/O, and SSH |
dialects/ | Database connector implementations and shared protocol bases |
wire/ | Protocol implementations for connectors without an existing Rust driver |
docs/ | Architecture, database setup, and distribution guides |
Read the architecture guide for dependency rules and the design specification for project direction. Planned behavior in the specification should not be treated as an implemented feature.
Roadmap
The project specification describes the wider design. Current areas for follow-up include:
These are development goals, not release-date commitments. Use open issues to propose work and track discussions. Check the support table for what is available today.
Contributing
Contributions are welcome across connectors, desktop UX, testing, documentation, and packaging.
- For substantial changes, open an issue describing the problem and proposed scope before starting.
- Keep changes focused. Include a reproducible example for bug fixes and document any user-visible behavior changes.
- Follow the existing module boundaries. Shared engine code should remain independent of the UI; connector changes belong in the appropriate dialect crate.
- Run formatting, linting, and tests relevant to the change. Add meaningful coverage for new behavior and record which checks passed.
- Open a pull request explaining the problem, the change, and validation. For connector work, state the database/version tested and distinguish live-server tests from mocks.
When reporting a bug, include your OS and architecture, Rowcraft version or commit, database and driver versions, steps to reproduce, and redacted logs or error output. Remove passwords, tokens, connection strings containing credentials, and private data before sharing.
Pull Request Workflow
-
Fork the repository and clone your fork.
-
Create a branch for the change:
git switch -c feature/describe-your-change
-
Implement the change and run the relevant checks above.
-
Commit and push to your fork:
git add <changed-files>
git commit -m "Describe the change"
git push -u origin feature/describe-your-change
-
Open a pull request against Rowcraft and include your validation results.
Browse contributors or open pull requests to see ongoing work.
License
The Cargo workspace declares MIT OR Apache-2.0. Standalone license texts have not yet been added to this repository. Bundled fonts and other third-party assets retain their own license notices.
Contact
Maintainer: Sarfraz-droid
Project: Sarfraz-droid/Rowcraft
For bugs and feature ideas, open an issue. Include enough detail to reproduce the problem, and remove credentials and private data from reports.
Documentation
Acknowledgments
- Best-README-Template by othneildrew for this README's structure.
- The Rust, Tauri, React, and CodeMirror communities, and the maintainers of the database drivers used by Rowcraft.
- Shields.io for repository badges.
- The creators of bundled fonts and other assets; their license notices remain alongside those assets.
