Repository: beekeeper-studio/beekeeper-studio

Stars: 22585

CLAUDE.md Copy Chapter

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview Copy Chapter

Beekeeper Studio is a cross-platform SQL editor and database manager built with Electron, Vue.js 2, and TypeScript. It supports 15+ databases and offers both community (GPLv3) and paid editions.

Architecture Copy Chapter

Monorepo Structure Copy Section

Technology Stack Copy Section

Key Entry Points Copy Section

Core Interfaces Copy Section

Development Commands Copy Chapter

Package Manager: This project uses Yarn (not npm).

Root-level Commands (from project root) Copy Section

Development

yarn bks:dev              # Start development server (builds lib + starts electron)
yarn electron:serve       # Alias for bks:dev
Building

yarn bks:build            # Build complete app (lib + electron)
yarn electron:build       # Alias for bks:build
yarn lib:build            # Build UI kit library only
yarn lib:dev              # Start UI kit in development/watch mode
Testing

yarn test:unit            # Unit tests with Jest
yarn test:integration     # Integration tests
yarn test:e2e             # End-to-end tests with Playwright
yarn test:ci              # CI-specific test configuration
yarn test:codemirror      # CodeMirror-specific tests
Linting

yarn all:lint             # Lint all workspaces

Studio App Commands (from apps/studio/) Copy Section

Development

yarn electron:serve       # Start development with hot reload
yarn dev:esbuild          # Watch main process (ESBuild)
yarn dev:vite             # Watch renderer process (Vite)
Building

yarn build                # Build both main and renderer processes
yarn build:esbuild        # Build main process only
yarn build:vite           # Build renderer process only
yarn electron:build       # Full production build with electron-builder
Test Build (Agents - use this to test the build, also good for CI)

yarn run electron:build --linux AppImage  # Create Linux AppImage for testing
Testing

yarn test:unit            # Unit tests
yarn test:integration     # Integration tests
yarn test:e2e             # E2E tests
yarn lint                 # ESLint

Code Architecture Copy Chapter

Source Structure (apps/studio/src/) Copy Section

components/          # Vue components organized by feature
├── common/         # Shared/reusable components
├── connection/     # Database connection forms
├── editor/         # Query editor components
├── export/         # Data export functionality
├── sidebar/        # Sidebar navigation components
└── ...
lib/                # Core business logic
├── db/            # Database clients and connection logic
├── editor/        # Text editor functionality (CodeMirror)
├── export/        # Data export functionality
├── cloud/         # Cloud/workspace features
└── ...
background/         # Electron main process code
common/            # Shared utilities and models
store/             # Vuex store modules
migration/         # Database migration scripts
assets/            # Styles, fonts, images

Database Client Architecture Copy Section

License Model Copy Section

Plugin System Copy Section

Key Configuration Files Copy Chapter

- ESBuild: apps/studio/esbuild.mjs (main process build)
- Vite: apps/studio/vite.config.mjs (renderer process build)
- TypeScript: apps/studio/tsconfig.json
- Jest: apps/studio/jest.config.js (plus specialized configs)
- Electron Builder: apps/studio/electron-builder-config.js

Running Tests Copy Chapter

Always run tests from the appropriate directory:
- From root: yarn test:unit, yarn test:integration, yarn test:e2e
- From apps/studio: yarn test:unit, yarn test:integration, yarn test:e2e

Test files are organized in apps/studio/tests/:
- unit/ - Unit tests
- integration/ - Integration tests
- e2e/ - End-to-end tests with Playwright

Development Workflow Copy Chapter

1. Setup: yarn install from root
2. Start development: yarn bks:dev (from root) or yarn electron:serve (from apps/studio)
3. Run tests: yarn test:unit before committing
4. Build: yarn bks:build for production build

Path Aliases (Vite/TypeScript) Copy Chapter

"@" -> "./src"
"@commercial" -> "./src-commercial"
"@shared" -> "./src/shared"
"assets" -> "./src/assets"
"@bksLogger" -> "./src/lib/log/rendererLogger"

Database Support Copy Chapter

The app supports 15+ databases including PostgreSQL, MySQL, SQLite, SQL Server, Oracle, BigQuery, MongoDB, and more. Database-specific connection logic is in src/components/connection/ with corresponding client implementations in src/lib/db/.

Documentation Translation Guidelines Copy Chapter

The documentation site (docs/) uses MkDocs Material with the mkdocs-static-i18n plugin for multi-language support. See mkdocs.yml for the list of 10 target languages.

File Structure Copy Section

Translations use suffix-based naming:
- English (default): filename.md
- Spanish: filename.es.md
- Portuguese (Brazil): filename.pt-BR.md
- Other languages: filename.{locale}.md

Translation files live alongside the original English files in the same directory.

Creating Translations Copy Section

1. Copy the English file as a starting point
2. Keep the same frontmatter structure (title, summary, icons, etc.) but translate the values
3. Translate all content including:
- Frontmatter title and summary
- All body text and headings
- Alt text for images
- Admonition titles (e.g., !!! note "Translated Title")
4. Do NOT translate:
- File paths and URLs
- Code blocks (unless comments need translation)
- Technical terms that are commonly used in English (e.g., "plugin", "SQL")
- Brand names (e.g., "Beekeeper Studio", "GitHub")

Navigation Translations Copy Section

Add nav_translations in mkdocs.yml under each language locale to translate menu items:

- locale: es
  name: Espanol
  nav_translations:
    Introduction: Introduccion
    Features: Caracteristicas

Adding a New Language Copy Section

1. Add the locale to mkdocs.yml under plugins > i18n > languages
2. Include site_name, site_description, and nav_translations
3. Create .{locale}.md files for each page in docs/
4. Test with mkdocs serve from the studio/ directory

Finding Files to Translate Copy Section

English is the primary language. To find all files needing translation for a new language:

1. Scan docs/ recursively for all .md files
2. Exclude files that already have a locale suffix (e.g., .es.md, .de.md)
3. For each English file found, create the corresponding .{locale}.md translation

Example: If you find docs/user_guide/security.md, create docs/user_guide/security.es.md for Spanish.

README Translations Copy Section

The main README.md has translations in the repo root using the pattern README-{locale}.md or README.{locale}.md:
- README.md - English (primary)
- README-es.md - Spanish
- README.pt-br.md - Portuguese (Brazil)

When adding a new README translation:
1. Create README-{locale}.md in the repo root
2. Add a link to it in the translation line at the top of README.md

The first line of README.md links to all translations using the format:

🌐 ES | PT-BR

README.md Copy Chapter

<!-- Target languages: ["en", "pt-BR", "es", "de", "fr", "el", "ja", "it", "ko", "id"] -->
🌐 ES | PT-BR | DE | FR | EL | JA | IT | KO | ID

Beekeeper Studio

Beekeeper Studio is a cross-platform SQL editor and database manager available for Linux, Mac, and Windows.

Download Beekeeper Studio

We publish binaries for MacOS, Windows, and Linux.


Beekeeper Studio is free to download and provides a lot of features for free, no sign-up, registration, or credit card required. The app provides some premium features for a reasonable cost license fee. Learn more here

Most of the code in this repo is open source under the GPLv3 license. Paid features are also in this repository under a commercial source-available license.

We welcome community contributions!

Supported Databases Copy Chapter

<!-- Don't edit this, it gets built automatically from docs/includes/supported_databases.md -->
<!-- SUPPORT_BEGIN -->

| Database | Support | Community | Paid Editions | Beekeeper Links |
| :------------------------------------------------------- | :--------------------------- | :-------: | :------: | -----------------------------------------: |
| PostgreSQL | ⭐ Full Support | ✅ | ✅ | Features |
| MySQL | ⭐ Full Support | ✅ | ✅ | Features|
| SQLite | ⭐ Full Support | ✅ | ✅ | Features, Docs |
| SQL Server | ⭐ Full Support | ✅ | ✅ | Features |
| Amazon Redshift | ⭐ Full Support | ✅ | ✅ | Features |
| CockroachDB | ⭐ Full Support | ✅ | ✅ | Features, Docs |
| MariaDB | ⭐ Full Support | ✅ | ✅ | Features |
| TiDB | ⭐ Full Support | ✅ | ✅ | Features |
| Google BigQuery | ⭐ Full Support | ✅ | ✅ | Features, Docs |
| Redis | ⭐ Full Support | ✅ | ✅ | Features, Docs |
| Oracle Database | ⭐ Full Support | | ✅ | Features, Docs |
| Cassandra | ⭐ Full Support | | ✅ | Features |
| Firebird | ⭐ Full Support | | ✅ | Features, Docs |
| LibSQL | ⭐ Full Support | | ✅ | Features |
| ClickHouse | ⭐ Full Support | | ✅ | Features, Docs |
| DuckDB | ⭐ Full Support | | ✅ | Features, Docs |
| SQL Anywhere | ⭐ Full Support | | ✅ | Features |
| MongoDB | ⭐ Full Support | | ✅ | Features, Docs |
| Trino / Presto | ⭐ Full Support | | ✅ | Features, Docs |
| SurrealDB | ⭐ Full Support | | ✅ | Docs |
| Snowflake | ⏳ Coming Soon | | ✅ | -- |
| DynamoDB | 🗓️ Planned | | ✅ | -- |

<!-- SUPPORT_END -->

Editions of Beekeeper Studio Copy Chapter

Beekeeper Studio is a single download with in-app upgrades for premium features.

We'd love to make Beekeeper Studio totally free for everyone, but building good software is hard work and expensive. We think our paid editions are fairly priced, I hope you do too.

👉 Compare Beekeeper Studio Editions

Beekeeper Studio Features Copy Chapter

Top feature: It's smooth 🍫, fast 🏎, and you'll actually enjoy using it 🥰

- Truly cross-platform: Windows, MacOS, and Linux
- Autocomplete SQL query editor with syntax highlighting
- Tabbed interface, so you can multitask
- Sort and filter table data to find just what you need
- Sensible keyboard-shortcuts
- Save queries for later
- Query run-history, so you can find that one query you got working 3 days ago
- Great dark theme
- Import/export
- Backup/restore
- View data as JSON
- Loads more

Our approach to UX Copy Chapter

One of our frustrations with other open-source SQL editors and database managers is that they take a 'kitchen sink' approach to features, adding so many features that the UI becomes cluttered and hard to navigate. We wanted a good looking, open source SQL workbench that's powerful, but also easy to use. We couldn't find one, so we created Beekeeper Studio!

Generally our guiding star is to only build software that 'feels good' to use. That means at the very least we value Beekeeper being fast, straightforward to use, and modern. If a new feature compromises this vision, we kill it.

Supporting Beekeeper Studio Copy Chapter

We love working on Beekeeper Studio, and we'd love to keep growing and improving it forever. To do that I need your help.

The best way to support Beekeeper Studio is to purchase a paid license. Every purchase directly supports our work on Beekeeper Studio.

If you're at a business and using Beekeeper Studio for your job, you should probably get your boss to buy you a license.

If you can't afford a license, please use the free version, that's why we make a free version!

Thank you for your continued support!

Documentation Copy Chapter

Check out docs.beekeeperstudio.io for user guides, FAQs, troubleshooting tips, and more.

License Copy Chapter

Beekeeper Studio Community Edition (the code in this repository) is licensed under the GPLv3 license.

Beekeeper Studio Ultimate Edition contains extra features and is licensed under a commercial end user agreement (EULA).

Beekeeper Studio's trademarks (words marks and logos) are not open source. See our trademark guidelines for more information.

Trademark Guidelines Copy Chapter

Trademarks can be complicated with open source projects, so we have adapted a set of standard guidelines for using our trademarks that are common to many open source projects.

If you are just using the Beekeeper Studio app, and you are not forking or distributing Beekeeper Studio code in any way, these probably don't apply to you.

👉 Beekeeper Studio Trademark Guidelines

Contributing to Beekeeper Studio Copy Chapter

We love any community engagement. Even if you're complaining because you don't like something about the app!

Contributor Agreements Copy Section

- Building an inclusive and welcoming community is important to us, so please follow our code of conduct as you engage with the project.

- By contributing to the project you agree to the terms of our contributor guidelines.

Contribute without coding Copy Section

We have you covered, read our guide to contributing in 10 minutes without coding.

Compiling and Running Beekeeper Studio Locally Copy Section

Want to write some code and improve Beekeeper Studio? Getting set-up is easy on Mac, Linux, or Windows.

First: Install NodeJS 20, NPM, and Yarn

...
1. Fork the Beekeeper Studio Repo (click fork button at top right of this screen)

2. Check out your fork:

git clone [email protected]:<your-username>/beekeeper-studio.git beekeeper-studio
cd beekeeper-studio/
yarn install # installs dependencies

Now you can start the app:

yarn run electron:serve ## the app will now start

If you get error:03000086:digital envelope routines::initialization error, you'll have to update openssl.

- On Ubuntu/Debian:

sudo apt-get update
sudo apt-get upgrade openssl

- On CentOS/RHEL:

sudo yum update openssl

- On macOS (using Homebrew):

brew update
brew upgrade openssl

Where to make changes? Copy Section

This repo is now a monorepo, we have several places with code, but only really a couple of important entry points.

All app code lives in apps/studio, some shared code lives in shared/src. This is shared with other apps.

Beekeeper Studio has two entry points:
- background.js - this is the electron-side code that controls native things like showing windows.
- main.js - this is the entry point for the Vue.js app. You can follow the Vue component breadcrumbs from App.vue to find the screen you need.

Generally we have two 'screens':
- ConnectionInterface - connecting to a DB
- CoreInterface - interacting with a database

How to submit a change? Copy Section

- Push your changes to your repository and open a Pull Request from our github page (this page)
- Make sure to write some notes about what your change does! A gif is always welcome for visual changes.

Maintainer notes (casual readers can ignore this stuff) Copy Chapter

Upgrading Electron Gotchas Copy Section

This is always a total pain and will break the build 9/10.

Some things you need to consider when upgrading Electron:

1. Does it use a different node version. Eg Electron-18 uses node 14, 22 uses node 16. So everyone needs to upgrade
2. Does node-abi need to be upgraded to be able to understand the electron version? This is used in the build to fetch prebuilt packages. You need to upgrade this in root/package.json#resolutions
3. Were any APIs deprecated or removed? Make sure all features that interact with the Electron APIs still work, stuff like - selecting a file, maximizing a window, running a query, etc.

Release Process Copy Section

1. Up the version number in package.json
2. Replace build/release-notes.md with the latest release notes. Follow the format that is there.
- run git log <last-tag>..HEAD --oneline | grep 'Merge pull' to find PRs merged
2. Commit
3. Push to master
4. Create a tag git tag v<version>. It must start with a 'v'
5. git push origin <tagname>
- Now wait for the build/publish action to complete on Github
6. Push the new release live
- Go to the new 'draft' release on the releases tab of github, edit the notes, publish
- Log into snapcraft.io, drag the uploaded release into the 'stable' channel for each architecture.

This should also publish the latest docs

Post Release:
1. Copy release notes to a blog post, post on website
2. Tweet link
3. Share on LinkedIn
4. Send to mailing list on SendInBlue

Big Thanks Copy Chapter

Beekeeper Studio wouldn't exist without Sqlectron-core, the core database libraries from the Sqlectron project. Beekeeper Studio started as an experimental fork of that repository. A big thanks to @maxcnunes and the rest of the Sqlectron community.

The original license from sqlectron-core is included here:

Copyright (c) 2015 The SQLECTRON Team
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.