DbGate documentation :: DbGate

Installation

Mon, 01 Jan 0001 00:00:00 +0000

DbGate is available for various platforms, installation process is dependend on platform. Windows Windows supports msi installer and portable ZIP installation. Autoupdater is supported for MSI installer. Linux Linux supports snap packages and AppImage distribution. Both supports autoupdate (SNAP supports it natively) Mac For Mac, DMG installer is available. There are 3 packages available: Apple (arm64) for new Apple M1, M2, M3, M4 processor Intel (x86) - for old x86 processors Apple+Intel - both packages in onw installer Docker For Team Premium edition, please follow instructions on Team Premium on Docker

Connection

Mon, 01 Jan 0001 00:00:00 +0000

Connecting to your database from DbGate is easy. You can connect to a database in a few different ways: Menu File/Add Connection or icon in CONNECTIONS widget Menu File/New SQLite database - creates new SQLite database Menu File/Open - you could open existing SQLite database Connection screen Fields in connection screen highly depends on Connection type. Several common fields:

Data filtering

Mon, 01 Jan 0001 00:00:00 +0000

DbGate has powerful data filtering engine, allowing both very easy data filtering or complex conditions. Data filters can used in many places in DbGate, but the most common place is filtering data grid. Filters are filled with background: Green background - filter is correct and is applied Red background - there is error in filter expression, filter is ignored You have several options, how to create filter:

Export & import

Mon, 01 Jan 0001 00:00:00 +0000

DbGate has flexible export/import system allowing both simple one-click exports or complex custom setup. Simple one-click export If you don’t need any configuration, you just need to export data to file, you could use simple export. There are several ways, how to invoke simple export: Table/view/collection context menu, Export Table data, “Export” context menu or button. Filters are applied also to exported data Query result, “Export” context menu or button In desktop application, you could directly save exported file.

DbGate Cloud

Mon, 01 Jan 0001 00:00:00 +0000

DbGate cloud is online storage for your connections, SQL scripts and other objects. Also it offers public knowledge base for useful SQL scripts. Sign in To use DbGate cloud, it is neccessary to sign in. Use icon in left panel. Your cloud storage is always associated with your e-mail address. You could choose one of following authentization providers: GMail GitHub E-mail - one-time sign-in magic link will be sent to your email DbGate servers don’t store your password.

Advanced data tools

Mon, 01 Jan 0001 00:00:00 +0000

DbGate offers several advanced data tools suitable for specific scenarios: Data archives - table data stored in folders (on NDJSON format) on your local computer. You could browse and edit this data in the similar way as browsing tables in database Data deployer - visually compare and synchronize data between data archive and real database Data replicator - replicate your data from data archive to database, suitable for run from DbGate app or from command line

Environment variables

Mon, 01 Jan 0001 00:00:00 +0000

Configuration via environment variables could be used in docker containers, also when using npm package. NPM package supports .env files. dbgate-serve - NPM package for Community edition dbgate-serve-premium - NPM package for Premium edition dbgate/dbgate - Docker image for Community edition dbgate/dbgate-premium - Docker image for Premium edition Premium vs Team Community edition Community (FOSS) edition uses only configuration from environment variables listed below. Team Premium edition uses database storage for settings with administration UI, only few basic settings are configured with env variables.

Database deploy

Mon, 01 Jan 0001 00:00:00 +0000

Deploy functionality will be significantly changed in incoming release, this documentation is related to lastest BETA version DbGate offers mechanism for automatic database deploy. While traditional way to achieve this uses migration SQL scripts, DbGate uses different way by default (migration scripts are also support). You define DB model with YAML files describing table structure and list data, and SQL files describing views, stored procedures and functions. This model is deployed to database, comparing current structure with structure in model, create missing columns and tables abnd update view and procedure definitions. No destructive actions (which could lead to data loss) are performed, so when you remove column or table from model, it remains in database. If you rename column in model, new column with new name is created and old column remains in in database.

Custom themes

Mon, 01 Jan 0001 00:00:00 +0000

DbGate has flexible theming support. You could create your own theme, changing colors of various UI elements. Themes are created as JSON files. The simplest way to create custom theme is to use theme AI assistant. Theme AI Assistant For invoking theme AI assistant, open Settings/Themes, then click “Customize with AI assistant” button. Theme AI assistent will customize your theme according to your instructions. You could specify, which colors you want to change, and how. For example, you could say “Make primary color green, and background color dark gray”.

Maps

Mon, 01 Jan 0001 00:00:00 +0000

DbGate supports showing geographic data in maps. Supported map sources MySQL: All spatial columns MSSQL: GEOGRAPHY columns PostGIS: GEOGRAPHY columns All data sources: coordinates stored in latitude/longitude columns Invoking map view Map view is invoked from data grid. At first, select cells with desired geographic data. The simplest way is to select GEOGRAPHY or GEOMETRY cell. You could also select multiple rows. Then, click to Cell data widget. You should see map in cell data widget.

Charts

Mon, 01 Jan 0001 00:00:00 +0000

With DbGate, you could use chart for visualization of your SQL queries. Simply execute query, in chart is auto-detected, the tab “Chart 1” will appear. If you have more query results, there could be more charts. If no chart is autodetected, but you would like to create some chart from your query results, right click on your query result data and choose “Open chart”.

API Connections

Mon, 01 Jan 0001 00:00:00 +0000

DbGate supports connections to REST APIs, GraphQL services, and OData endpoints. These API connections use the same interface patterns as database connections, allowing you to work with APIs and databases in a unified environment. API connection support is available in DbGate Premium. GraphQL GraphQL connections allow you to interact with GraphQL APIs. DbGate provides schema introspection and query execution capabilities. Creating a GraphQL connection To create a GraphQL connection, use the New Connection dialog and select GraphQL as the connection type. Enter the GraphQL endpoint URL and configure authentication if required.

Perspectives

Mon, 01 Jan 0001 00:00:00 +0000

Perspective is readonly view of complex nested data. It resembles reports, but perspectives are created simply by adding data to view. You could use perspective desigher, which allows you to join data following other relations than foreign keys. Perspectives can easily join data together, and show groups. Create perspective Perspectives could be created from SQL tables and views (MongoDB collections are not yet supported, but this support is planned). Use context menu of table/view, “Open perspective”.

Plugin development

Mon, 01 Jan 0001 00:00:00 +0000

DbGate supports creating plugins. Thanks plugin to wizard, it is really simple to create masic plugin. DbGate plugins are NPM (JavaScript) packages, they can have dependencies. (but not native dependencies) Now there are 3 types of plugins: Theme plugin File format plugin Database driver plugin Install prerequisites You need node.js installed. Also you will need Yeoman and yeoman DbGate plugin generator: npm install -g yo npm install -g generator-dbgate Create plugin Run following command in console:

Web app config samples

Mon, 01 Jan 0001 00:00:00 +0000

There are lot of configuration layouts, which could be achieved with environment variables configuration. In this topic, sample configurations web app will be shown. Use storage database and administration for settings (Premium) This configuration layout uses administration for configure database connections and users. All settings are stored into database configured with env variables. Please use Premium docker container for this to work. STORAGE_SERVER: mariadb STORAGE_USER: root STORAGE_PASSWORD: STORAGE_PORT: 3306 STORAGE_DATABASE: dbgate STORAGE_ENGINE: mysql@dbgate-plugin-mysql ADMIN_PASSWORD:

Adminstration

Mon, 01 Jan 0001 00:00:00 +0000

Administration tool is available only on Team Premium edition. In Community edition, please use configuration using environment variables All configuration from administration is saved into database, use STORAGE_xxx environment variables for configure this. Administrator access Administration page is available on URL https://your_dbgate_instance/admin.html . Root adminstrator should have password defined. You could set environment variable ADMIN_PASSWORD. If this variable is not defined, DbGate asks for admin password at first. You could then add administration permission to different user with different authentication method, but at first, you have to open this admin page.

Backup & restore

Mon, 01 Jan 0001 00:00:00 +0000

DbGate uses native tools for backup and restore your databases. This functionality is exclusive for Premium editions. Supported tools: PostgreSQL pg_dump and psql MySQL+MariaDB mysqldump and mysql How to install these tools You don’t have to solve this, if you use Team Premium edition - Docker, AWS or Azure versions. These packages have already bundled all tools needed. The easiest way is to install the whole database engine to your desktop. However, for most platforms and databases, there is posibility to install only clients:

Scripting

Mon, 01 Jan 0001 00:00:00 +0000

DbGate consists of several NPM packages, which could be used in nodejs scripts Typically you will need these packages: dbgate-api - implements utility functions dbgate-plugin-engine - set of connector plugins, implements connection to database and operations specific to given database engine dbgate-plugin-fileformat - if you use export to CSV or XML, these format providers are implemented as external plugins Documentation of API Generating script from DbGate Lot of DbGate features are internally implemented with scripting interface. So when you are using some export-like operation, there is somewhere “Generate Shell script” button, which generates nodejs script for you.

SQL Front Matter

Mon, 01 Jan 0001 00:00:00 +0000

SQL front matter is metadata in YAML format at the beginning of SQL file. This concept is inspired by gohugo and Jekyll, which introduced front matter for markdown files. (Front matter in Hugo) SQL front matter starts immediately at the SQL file start file mark -- >>> and ends with line containing only -- <<<. Every line of YAML content is prefixed with -- prefix, so that the whole file remains valid SQL.

API documentation

Mon, 01 Jan 0001 00:00:00 +0000

Functions copyStream(input, output, options) ⇒ Promise Copies reader to writer. Used for import, export tables and transfer data between tables deployDb(options) Deploys database model stored in modelFolder (table as yamls) to database dropAllDbObjects(options) ⇒ Promise Drops all database objects executeQuery(options) Executes SQL query generateDeploySql(options) Generates query for deploying model into database jsonLinesReader(options) ⇒ Promise. Reader function, which reads JSNOL file or URL. JSONL format - text file, every line is JSON encoded row.