FlameRobin 0.7.6 ALPHA Manual

Nando Dessena

Milan Babuskov


1. About this manual
2. About the ALPHA test program
3. What FlameRobin is
4. What FlameRobin is NOT
5. Who we are
6. License
7. What's new?
8. Installation
8.1. General information
8.2. Windows (Win32)
8.3. Linux
8.4. MacOS X
9. Getting started / basic features
9.1. Adding a server
9.2. Adding an existing database
9.3. Creating a new database
9.4. Connecting to a registered database
9.5. Browsing metadata
9.6. Editing objects
9.7. Browsing data
9.8. Running SQL statements and scripts
9.9. Backup and restore
10. Advanced features
10.1. DDL extraction
10.2. Rebuild View functionality
10.3. Connected users
10.4. Event monitoring
10.5. User management
10.6. Grant and revoke privileges
10.7. Server and client version
10.8. Advanced metadata search
10.9. Logging
11. Configuration
11.1. General
11.1.1. Center dialogs on their parent window
11.1.2. Remember window positions and sizes
11.2. Main Tree View
11.2.1. Order server entries alphabetically
11.2.2. Order database entries alphabetically
11.2.3. Show columns and parameters in tree
11.2.4. Show system tables in tree
11.2.5. Allow drag and drop query building
11.3. SQL Editor
11.3.1. Automatically commit DDL statements
11.4. Data Grid
11.4.1. Date format
11.4.2. Time format
11.4.3. Grid header font
11.4.4. Grid cell font
11.4.5. Re-format float and double precision numbers
11.4.6. Maximize data grid after execution of SELECT statement
11.5. Property Pages
11.5.1. Show default column values
11.5.2. Show column descriptions
11.6. Object names
11.6.1. Quote names only when needed
11.6.2. Treat quote characters like other characters
11.7. Fields
11.7.1. When a column has a user-defined domain
11.7.2. When a table column is computed
11.8. Logging
11.8.1. Log DML statements
12. Database configuration
12.1. Main Tree View
12.1.1. Show system tables in tree
12.2. Connection
12.2.1. Warn when connection charset is different from database charset
12.3. Logging
13. The FlameRobin environment
14. Advanced topics
14.1. Encrypted password storage
14.1.1. Defense from "known plain-text" attack

1. About this manual

Currently this manual is incomplete, and it will probably stay incomplete until FlameRobin reaches version 1.0. Nonetheless, we try to make sure that the information included here is accurate also for ALPHA releases.

2. About the ALPHA test program

Welcome to the FlameRobin Alpha test! We thank you for evaluating this software and encourage you to send comments, bug reports and feature requests back to us so we can make a better product. We remind you that this is Alpha quality software so you shouldn't expect it to work flawlessly (although we've been using it for daily work for a long time now). The main purpose of this early release is finding bugs and tune the user interface, for which we need feedback from the prospect users.

3. What FlameRobin is

FlameRobin is a GUI administration and data manipulation tool for Firebird databases. It is designed to be small, simple and cross-platform, yet offer all the basic features needed to administer Firebird servers and create/maintain databases. FlameRobin is Open Source software and binaries are currently available for Windows, several GNU/Linux and BSD flavours and MacOS X. Ports to other platforms are possible, subject to the availability of maintainers for those platforms.

4. What FlameRobin is NOT

Currently FlameRobin is not a full-featured administration tool, as there are plenty available for Firebird from several different parties. Our first goal with FlameRobin is to provide people not used to the command line with a GUI tool to get started with Firebird. Our longer-term goal is to develop a richer tool mainly for the Linux platform; while there are several rich and mature GUI tools under Windows, some of them available for free or for a modest price, there isn't any for Linux. Another goal of the project is for a "lite" edition of FlameRobin to be bundled with the Firebird server to serve as a starting kit for new users. This bundle may be distributed by the Firebird Project itself or by some third party.

5. Who we are

The home page of the FlameRobin project is located at http://www.flamerobin.org. The project itself is hosted on SourceForge. Please use our mailing list (flamerobin-devel) to contact the developers. Details and archives available here. You are also encouraged to use our bugs and feature requests trackers to report back to us the results of your alpha testing. If you are a developer interested in joining the FlameRobin project, let us know. We always welcome contributors.

6. License

FlameRobin is released under the Expat License. You can find the complete license text in the file fr_license.html, or here.

7. What's new?

Please refer to fr_whatsnew.html for a detailed history of all the changes since the previous ALPHA release.

8. Installation

If you want to build FlameRobin from sources, please find instructions on our web site or Subversion repository. In this section we talk about installing the pre-built version of FlameRobin under all currently supported platforms.

8.1. General information

If you have installed a previous ALPHA version of FlameRobin which is less than 0.4.0, it is recommended that you remove it before installing this version.

You won't be able to keep a config.ini file from an earlier version, because the name and file format have changed in version 0.4.0.

You might be able to keep your servers.xml file, provided that you rename it to fr_databases.conf and move it to your data folder. FlameRobin will tell you the exact path of this file (which changes with the platform) upon first startup, when it cannot find the file.

Here are the files used by FlameRobin to store configuration information:

  • fr_databases.conf is the list of Firebird servers and databases you work with; FlameRobin will create it (and automatically add the "localhost" server) when you run it for the first time; then you can register new servers and databases.

  • fr_settings.conf stores FlameRobin's configuration information, like the position and size of the main program window. You don't need to edit it by hand.

Note

The location of these files changes with the platform, and it's usually a directory owned by the current user. FlameRobin needs write access to that folder.

8.2. Windows (Win32)

To install FlameRobin under Windows you need the Firebird client (gds32.dll for Firebird 1.0, fbclient.dll for Firebird 1.5 and up) installed and available, then just run the automatic installer of FlameRobin which will copy all required files in a directory of your choice and optionally create desktop and start menu shortcuts.

If you need to uninstall FlameRobin you can do so from the start menu icon (unless you told the installation program not to create one) or from the Control Panel.

8.3. Linux

While some Linux distributions might provide installation packages suitable for specific versions of that distribuion, FlameRobin project provides generic compressed archives containing the executable and all needed files. There are two flavors, depending of your preferences. You can use Gtk1 version, which runs faster and has less dependencies. It is suitable for slower computers and should run out-of-the-box on most distributions. Gtk2 version uses Gtk2 toolkit, so it looks nicer on the screen and it also has Unicode support.

To install FlameRobin, just unpack the chosen .tar.bz2 archive, cd into that directory and type "make install" as root. This will install FlameRobin and all the needed files to appropriate locations. After that, any user can type "flamerobin" to run the program.

8.4. MacOS X

Installation on Mac OS X is an absolute no-brainer: just drag the icon from the installation package to the folder you want the application to live in. Unpacking is handled via double clicking the downloaded file.

9. Getting started / basic features

Upon first startup, FlameRobin will show a "Home" tree containing only the local server (localhost), and will invite you to create new servers and databases as required. You'll also see a menu bar at the top of the window, and a search bar and status bar at the bottom. Here is a brief how-to for getting started with FlameRobin.

9.1. Adding a server

You can add a server by right-clicking on "Home" and choosing "Register server..." (alternatively, use the "Register server..." command from the "Server" menu). You will have to specify a display name and optionally the host name and TCP port number on which the Firebird server listens. Leave the display name empty to have FlameRobin build one automatically from the host name and port values (if you don't have a host name, because yours is a local or embedded Firebird server, you will be required to type in a display name manually). Once you have added a server, you can register databases under its node.

9.2. Adding an existing database

To access an existing database from FlameRobin you have to register it. Registration will make FlameRobin remember the database connection properties so you don't have to re-enter them every time. Locate the correct server in the tree, right click it and choose "Register existing database...". You will have to enter a display name, the database path (or alias name), the user name and password (note: the password is stored as plain text in fr_databases.conf. For security reasons, we recommend you to NOT specify it in this dialog: FlameRobin will then prompt you for the password each time you connect to the database). You can also optionally specify a connection charset and role.

9.3. Creating a new database

To create a new, empty database, locate the desired server in the tree, right click it and choose "Create new database...". You will then need to input the database file or alias name, the user name and password for the owner of the new database (use SYSDBA as the user name and masterkey if you don't know what to put in these fields), the character set, the role, the page size (the default value of 4096 is just fine) and the SQL dialect (leave it set at 3 if you don't know what a SQL dialect is). The new database will be created and registered (which means it is available in FlameRobin).

You can also drop an existing registered database, optionally keeping the FlameRobin registration information. Use the "Drop" menu command to do that.

9.4. Connecting to a registered database

Just double click on the database name in the tree, or right click it and choose "Connect" or "Connect as...". Choose "Disconnect" to close the connection to the database.

9.5. Browsing metadata

Upon connection, the sub-tree under the database name is populated with a description of the database structure (metadata). Browse the tree to explore the metadata. You can also use the quick search feature to locate a particular object in the tree. Just type the name of the object you are looking for (use the "*" wildcard character for a partial match) in the search box at the bottom of FlameRobin's main window and the first object in the tree whose name matches your search string will be highlighted. Now you can hit Enter to focus the tree and add the object name (or search string) to the search box's drop-down list. For your convenience, FlameRobin will remember your search strings for further use. Click the arrow buttons next to the search box to move to the next and previous matches.

There is also an advanced metadata search feature, which is described later.

9.6. Editing objects

You can view and/or change the properties of every object you see in the tree by choosing the "Properties..." option from the object's context menu or from the "Object" menu. Please note that currently not all object types are supported, but you'll find almost all of them. Trying to show the property page for an object of an unsupported type will result in an error message. The property page is a HTML window with a summary of the object's properties and links which open other pages or specific editors. Some of the options are not yet available, but you can edit almost all aspects of the most common objects (tables, views, stored procedures, and so on). Please have a look at fr_whatsnew.html to see, well, what's new.

Note

Although we try to test the features as much as we can, this is ALPHA software and you should only use it to work on backup copies of your databases, or perform backup copies before using FlameRobin on them. Having said that, we have to add that many users (including us) have been using FlameRobin in their everyday Firebird development for more than a year now without problems.

9.7. Browsing data

After connecting to a database, locate a table, view or selectable stored procedure of your interest in the tree and right-click it. Choosing either "Select ... from ..." option will open the SQL editor with the table/view data shown in the grid at the bottom. In the case of selectable stored procedures with parameters, just the select statement appears in the SQL editor, so you should fill the parameter values (if you have any) and click the Execute button to see the data.

FlameRobin's data grid fetches data from the server in small chunks, so that you don't have to wait for the fetch to complete if you only look at the first few pages of rows. You can have the grid fetch all data (in background) through the Fetch all records command in the grid's context menu. Fetching a very large result set might take some time, so if you change your mind you can use the Stop fetching all records command.

9.8. Running SQL statements and scripts

Of course you can use the SQL editor window to create and execute arbitrary SQL statements. FlameRobin provides a rather advanced and sophisticated, yet simple to use SQL editor. You can open a SQL editor window by right clicking on a database node and choosing "Run a query". The SQL editor tool offers script execution capabilities (including SET AUTODDL and SET TERM support), load/save buttons, auto-completion and call-tip features, commit/rollback, some execution statistics (including but not limited to the query PLAN), a data export tool and more.

To execute a script (meaning a sequence of more than one SQL statements), just load it (or type it in) and run it. To execute a single statement when more statements are present in the editor, select it before clicking the Run button.

Auto-completion can be invoked automatically or manually (see the rich set of configuration options about it), and supports table and column names, procedure and function parameters, and so on.

To activate the data export tool, right click on the data grid. The data export tool is currently able to copy the data to the clipboard, generate SQL INSERT or UPDATE statements or export the data to a HTML file. All options work on the whole grid contents or just the selected parts. You can also multiple-select several different grid "islands" and have the tool export them. This is particularly handy when generating INSERT or UPDATE statements.

For SELECT statements, you can also drag and drop objects from the tree view to visually build queries (provided the appropriate configuration option is enabled). Dragging and dropping tables will automatically create JOIN conditions (based on existing foreign key definitions) in the statement you are building.

9.9. Backup and restore

You can perform a database backup by right clicking on a database and choosing "Backup database...". Choose "Restore database..." to restore a backup file over the current database (you will have to disconnect first). Choose "Restore backup into new database..." (this time on the server node) to create a new database from a backup file. Note: it is usually considered bad practice to restore a backup file over an existing database. The Backup and Restore tools work in background, so you are allowed to continue working with FlameRobin while they proceed. You can work on a database while it is being backed up, but you can't work on a database while you are restoring it.

10. Advanced features

This section illustrates features in FlameRobin that you won't likely use every day, but often enough to make them useful to know.

10.1. DDL extraction

You can generate DDL (Data Definition Language) creation scripts for any object you have in the database, or even for the whole database. Just open the DDL subpage of an object's property page to see the DDL code that creates the object.

Extracting DDL scripts is useful if you want to replicate an object's structure in a different database, or create a slightly different object in the same database.

10.2. Rebuild View functionality

Firebird doesn't have an ALTER VIEW DDL command, which means that if you want to modify a view definition you need to DROP and CREATE it back. But dropping an object in Firebird requires dropping all objects that depend on it, and so on recursively. Doing this by hand is very hard, especially if the database structure is complex. A unique feature in FlameRobin, which you activate by righ-clicking a View object and selecting the "Alter..." menu command (or selecting the "Alter..." command from the "Object" menu after selecting a View), will generate a script that drops all the objects that depend on the view (in the correct order), drops and recreates the view, then recreates all the objects (again, in the correct order). The script is pasted into the SQL editor window so you can modify it and recreate everything with a single click.

10.3. Connected users

Select "Show connected users" at the database level (or in the "Database" menu) to see a list of users connected to that database. This only works reliably with the SuperServer variant of Firebird. If you are using Firebird Classic you will see at most one user connection there, which is yours.

10.4. Event monitoring

FlameRobin allows you to listen for Firebird events interactively. Just select the "Monitor events" command at the database level (or in the "Database" menu) to open the Event Monitor window (you will need to connect to the database first). This window allows you to monitor one or more events, save the received events to a text file and load them back. Events are posted from the database when the POST_EVENT statement is called (and the transaction is committed).

10.5. User management

Current versions of Firebird use a central server-wide user repository. FlameRobin allows you to add, modify and delete user accounts (but it will not allow you to delete the SYSDBA predefined user) by means of the "Manage users..." option in the Server menu (or the server's context menu item, or the Object menu item with the same caption). It is Firebird's security policy that you need to be SYSDBA to use this feature.

Note

The proper way to change the SYSDBA password on LInux is to run the changeDBAPassword.sh script in Firebird's bin directory. Otherwise Firebird's startup and shutdown scripts won't be updated.

10.6. Grant and revoke privileges

Every object in the database has a list of privileges that identify the users and roles that can work with that object. On an object's property page (in the "Privileges" subpage) you can view the privleges associated with that object, and if you hover the mouse over icons, you can see who granted them in the status bar. Clicking on the "Grant and revoke privileges" link will open a dialog box that will help granting and revoke privileges to that object (which you'll find pre-selected in the dialog box) and/or other objects as well. The dialog box allows you to build a list of grant/revoke SQL statements by clicking on appropriate controls and then on the "Add To List" button. When satisfied, click the "Execute All" button to run all the statements in the SQL editor (which will also log them for future use, as with any SQL statement executed in FlameRobin, if logging is enabled).

10.7. Server and client version

Select "Retrieve server version" from the "Server" menu (or from a server's context menu) to see a dialog box with the server's version string. A server's version string reveals the exact build number of your Firebird server and the platform it is running on. For example, a version string equal to "WI-V1.5.2.4731 Firebird 1.5" means Firebird 1.5.2, build 4731, on Windows.

Note

Currently FlameRobin doesn't show the version string of the Firebird client it is using, for these reasons:

  • Not all versions of Firebird support this feature, and FlameRobin needs to stay compatible with all Firebird versions.

  • At some point in the future FlameRobin will be able to load different client libraries for different databases (at least on platforms that support it). We will probably add the client version display feature then.

You can also look at the version string of the Firebird client FlameRobin is using, in the About box (Help/About).

10.8. Advanced metadata search

This feature, which you can fire through the lens button in FleameRobin's main window, allows you to perform more advanced search operations in your database's metadata (or in more databases at the same time). You can search with wildcards, search on object names and descriptions, in the DDL definition (which includes the source code for triggers and stored procedures), and do other, more specialized, search operations. Just add all criteria you need through the Add buttons, and then click the Start search button. The criteria will be concatenated with an "and" boolean operator, that is all of them must be satisfied for an object to be included in the SEARCH RESULTS pane.

This feature is provided on an experimental basis, as we're currently looking for suggestions about how to improve both the user interface and the capabilities. We already have some ideas that will radically change the appearance of this dialog box, but we thought users might want to try it out so they can give us some good tips.

10.9. Logging

The SQL Editor can log all executed statements to a text file, a set of text files or a database table. This gives you the ability to work visually and produce scripts to easily replicate sequences of operations on other databases. For database logging, in a future release, FlameRobin will also provide a visual interface to the log table, so that you can view a list of modifications to an object.

Look here for the options you use to configure this feature globally, and here for database-level logging options.

11. Configuration

This section documents the options you can set to tune FlameRobin's behaviour to your liking. You can set the options by means of the Preferences dialog, which is invoked through the "Preferences..." command in the "View" menu. The Preferences are organized in categories; here is a description of each category. Please read the tooltip that appears when you move the mouse cursor over each option to know more about it.

Note

Since new options are added to FlameRobin daily, this section of the documentation will likely be out-of-date. Please refer to the tooltips for fresh descriptions of all the available options.

11.1. General

Here you can find options to tune the visual appearance and behaviour of FlameRobin. You can choose whether FlameRobin will remember the size and position of opened windows between sessions or not, whether FlameRobin will ask for quit confirmation or not, and other such things.

11.1.1. Center dialogs on their parent window

Set this option to always have dialogs displayed at the center of their parent window. Otherwise dialogs are displayed at a system-defined position.

11.1.2. Remember window positions and sizes

If you enable this option, FlameRobin will remember the position and size of each window you open and will open the same window at the same position and with the same time the next time. You can also choose the granularity of this option for property pages and backup/restore dialogs:

  • Choose "Same settings for all objects" to store a single set of values; this means that whenever an Object Properties dialog is opened it will have the position and size of the last Object Properties dialog used.

  • Select "Same settings for all objects of same type" to store a set of values for each object type. This means that a Table Properties dialog will have different settings than a Trigger Properties dialog, but two Table Properties dialog will share the same set of values.

  • The third option, "Separate settings for individual objects", will make it so that every object's property page will have a set of options of its own. This mode is the most flexible, but consumes more disk space and memory.

11.2. Main Tree View

Here you can tune the appearance and behaviour of FlameRobin's metadata navigation tool, the main tree.

11.2.1. Order server entries alphabetically

Set this option to have your servers displayed in alphabetical order, otherwise they are displayed in the order they appear in servers.xml.

11.2.2. Order database entries alphabetically

Set this option to have your databases displayed in alphabetical order, otherwise they are displayed in the order they appear in servers.xml.

11.2.3. Show columns and parameters in tree

Enable this option to have table/view columns and procedure parameters displayed as tree nodes; otherwise, the tree stops at the table/view or procedure level. In case you choose to have columns and parameters displayed as tree nodes, you can also indicate whether you wish that a double click on a table/view or procedure node opens the relevant property page or expands the subtree.

11.2.4. Show system tables in tree

The metadata for a Firebird database is stored in the database itself, in a set of tables whose names start with RDB$, called the system tables. There is usually no point in working with Firebird's system tables directly, as FlameRobin already queries them and translates the information in friendlier form for you: the tree view, object property pages and various dialogs all display information coming from the system tables. FlameRobin also allows to change the database metadata in a safe way (that is, keeping the database structure's integrity), something which is not guaranteed if you try to edit the system tables directly.

For the rare cases in which a direct look at the system tables is required, and you know exactly where and how to look, you can enable this option, which will add all system tables for a database to the tree. This will impose a slight performance penalty upon connection.

You can override this setting at the database level.

11.2.5. Allow drag and drop query building

The SQL editor allows you to drag and drop objects from the tree view to visually build queries (see the relevant section). This feature may occasionally hang FlameRobin on Linux, so we are proving this option to switch it off until the problem is corrected in the wxWidgets library. Plus, you might want to disable the feature, if you don't use it, in order to avoid spurious start-drag operations when working with the mouse on the tree view.

11.3. SQL Editor

Use these options to customize the behaviour of the SQL Editor, which is used in FlameRobin to execute any kind of system-generated or user-supplied query.

11.3.1. Automatically commit DDL statements

Enable this option to have FlameRobin automatically "click" the Commit button on your part each time it detects a DDL (Data Definition Language) statements. DDL statements are those that modify the database structure (as opposed to DML, or Data Manipulation Language statements, which modify the data). Firebird does support transactional DDL, yet it is common practice to auto-commit these statements to avoid unexpected behaviours (for example, adding a column to an existing table and populate it through an UPDATE statement in the same transaction can lead to unexpected results with current versions of Firebird). This option sets a default state that you can change with the script commands SET AUTODDL ON and SET AUTODDL OFF.

11.3.1.1. When text is selected in editor

Leave this option to "Execute the entire buffer" if you don't want to take advantage of FlameRobin's advanced selection handling. If you set it to "Execute only the selection" you will be able to type (or load) entire scripts in the SQL editor and only execute single parts of them by selecting them and clicking the "Execute" button. If you don't select anything, FlameRobin will execute the whole text in the editor.

11.3.1.2. Treat selected text as a single statement

If you only ever select a single statement at a time, then you can save FlameRobin's parser some work by enabling this option. When you disable it, instead, FlameRobin will parse the selected text before executing it, break it into several statements if necessary and send them to Firebird one at a time; this is necessary since Firebird does not support executing more than one statement (i.e. a script) at a time. It can also be used if you have CREATE PROCEDURE or CREATE TRIGGER (or similar) statements with SET TERM. This way, you can select and execute the CREATE statement, and you don't need SET TERM at all.

11.3.1.3. Clear the messages when executing new statements

The SQL Editor has a message pane that shows information about each executed statement. By default this pane is cleared automatically only when you end transaction. Set this option to have FlameRobin clear it before executing a statement.

11.3.1.4. Enable call-tips for procedures and functions

When this option is enabled, then each time you type an open round bracket after a stored procedure or UDF name in the SQL Editor, a floating tooltip (called a call-tip) will appear reminding you what the input and output parameters of the stored procedure or UDF are.

11.3.1.5. Show long line marker

Activate this option to have the editor display a vertical line that visually marks the place where a line break would occur if lines couldn't be longer than a certain amount of characters. The marker is only a visual indicator, as FlameRobin will not enforce any limit to the length of text lines. You can also customize the column at which the marker will appear.

11.3.1.6. Tab size

Here you can set the number of space characters the SQL Editor will render for each TAB.

11.3.1.7. Code Completion

This page contains options to customize FlameRobin's code completion feature.

11.3.1.7.1. Enable automatic invocation of completion list

This is the general switch to turn automatic code completion in the SQL Editor on or off. Disable it if you don't like code completion windows that pop up while you write SQL code. If you keep it enabled, then you can set a certain number of characters you'll have to type before code completion kicks in, and choose to disable code completion when a call-tip is displayed (as it would close the call-tip window) or inside quoted text.

11.3.1.7.2. Manually invoke completion list on

Code completion may also be invoked manually. Here you select how (Ctrl+Space or Tab key).

11.3.1.7.3. Confirm completion with Enter

Set this option to have the currently selected item in the code completion window copied to the text buffer when you hit Enter. Otherwise you can use the Tab key for that.

11.3.1.7.4. Load columns when required for completion

FlameRobin only loads column definition data when requested to do so (for example, when you double click a table name in the tree view). Set this option to let FlameRobin load missing column information automatically when needed to show an auto-complete list.

11.3.1.8. Statement History

FlameRobin can remember the statements you execute and allow you to retrieve and re-execute past statements. This page allows you to customize the feature.

11.3.1.8.1. Share SQL statement history

You can have a single statement history list for all the databases you work with ("Between all databases") or a separate history list for each of them ("Don't share"). Additionally, you can make it so that all databases with the same display name (typically copies of the same database, or databases with the same structures, on different servers) share a history list.

11.3.1.8.2. Limit history item size

By default, each history list item is allowed to grow without bounds. If you are concerned about the size of your statement history lists, you can set an upper limit in Kilobytes for each statement in the history list. Statements bigger than the specified amount will not be added to the history list. This is useful if you execute entire database-creation scripts often.

11.3.1.8.3. Remember unsuccessfully executed buffers

By default, only statements that are executed without errors are added to the history list. Set this option to have FlameRobin remember also statements that caused errors.

11.3.1.8.4. Remember statements generated by FlameRobin

FlameRobin translates as much visual operations as possible to SQL statements. Uncheck this option to prevent this kind of statements from being added to the history lists.

11.4. Data Grid

When you issue a SQL SELECT statement in the SQL Editor, then the Data Grid comes into play to show the results. Here you customize its appearance and behaviour.

11.4.1. Date format

Choose the format you'd like for showing date and timestamp values in the grid.

11.4.2. Time format

Choose the format you'd like for showing time and timestamp values in the grid.

11.4.3. Grid header font

Choose a character font for the grid header (the column names).

11.4.4. Grid cell font

Choose a character font for the grid cells (the data).

11.4.5. Re-format float and double precision numbers

If unchecked, decimal numbers are displayed as returned from server; otherwise, they are formatted according to the specified number of decimal digits.

11.4.6. Maximize data grid after execution of SELECT statement

Here you can turn off an useful feature that will enlarge the data grid to the maximum available size when a SQL SELECT statement returns more than a specified number of rows.

11.5. Property Pages

This section contains customization options for FlameRobin-s property pages.

11.5.1. Show default column values

Set this option to display the "Default" column in a table's property page.

11.5.2. Show column descriptions

Set this option to display the "Description" column in a table's property page.

11.6. Object names

This page offers options to customize the way FlameRobin deals with object names in general, and quoted identifiers in particular. If you don't know how quoted identifiers work in Firebird, you should leave these settings to their default values.

11.6.1. Quote names only when needed

Uncheck this option to have FlameRobin always quote object names with " in dialect 3 databases. Leave it checked to let FlameRobin detect on its own when it is needed to quote identifiers. The setting "Quote names in mixed case" is only used for names entered by the user (for example, when you add a new field to a table, you type in its name).

If "Quote names only when needed" is checked and "Quote names in mixed case" is not, FlameRobin will leave the name entered by the user as it is, even if it is written in mixed case (unless the name is a reserved word or contains non-ASCII characters, in which case it is quoted).

Here are two use cases to better explain how these settings interact with each other:

Table 1. Case 1: "Quote names only when needed" = on; "Quote names in mixed case" = off

User entersTurns into
FIELD1FIELD1
Field1Field1
Date"Date"


Table 2. Case 2: "Quote names only when needed" = on; "Quote names in mixed case" = on

User entersTurns into
FIELD1FIELD1
Field1"Field1"
Date"Date"


The rationale behind all this is that if you write a name in mixed case, then you probably want it quoted (since you bothered to mix the case). Some users, however, find this rule awkward and unpredictable, and need a way to disable it.

11.6.2. Treat quote characters like other characters

This setting determines what happens if you type the quote character (") as a part of some name. Again, it only affects user-entered names. One option (unchecked) is to ignore it, other is to treat it like any other character (checked). Quotes are special cases, since they need to be escaped (by doubling them). When this setting is off, user can force quoting even when it is not required, by writing the name quoted in the text box.

11.7. Fields

Here you can customize the appearance of field types in the tree and property windows.

11.7.1. When a column has a user-defined domain

In this case you can choose to see after the column name the domain name, the data type, or both.

11.7.2. When a table column is computed

For computed columns, you can choose to see after the name the data type or the computation expression, or both.

11.8. Logging

The SQL Editor can log all executed statements to a text file, a set of text files or a database table. Here you set the relevant options for file-based logging, while logging to a database table is decided on a per-database basis.

11.8.1. Log DML statements

When logging is enabled, by default only DDL (CREATE, ALTER, DROP...) statements are logged. Turn this option on to enable logging of DML (SELECT, INSERT, UPDATE, DELETE) statements as well.

11.8.1.1. Enable logging to file

Here you choose whether you want to log statements or not, select the log file name(s), and choose if you want to output for each statement also a comment with the version of FlameRobin, database and user name, and execution date and time. Each statement can go into separate file, and it uses incremental numbers for filenames. You can format your own filenames by using %d as a placeholder for number. If you want numbers with fixed number of digits, like 0003 instead of 3, then use %04d as placeholder, where 4 means four digits, and 0 means that it should be padded with zeros.

There are also options to add a comment header to each logged statement, and to add SET TERM statements if required.

12. Database configuration

There is a set of options in FlameRobin that you can set on a per-database basis. You access the database configuration window by right clicking on a database and selecting the "Database preferences..." command, or selecting the same command from the "Database" menu. Like global preferences, database preferences are organized in categories; here is a description of each category. Please read the tooltip that appears when you move the mouse cursor over each option to know more about it.

12.1. Main Tree View

12.1.1. Show system tables in tree

This is a database-level override of the global option with the same name described here.

12.2. Connection

This page holds options that apply to database connection and database registration info.

12.2.1. Warn when connection charset is different from database charset

In Firebird it is quite an usual situation to have a single character set for an entire database, and use that character set for connecting to the database, otherwise string transliteration won't work correctly. For this reason, FlameRobin will warn you on connection if the two charsets don't match. There are cases, though, in which you might want to connect to a database with a different character set (for example when you use different charsets for different tables or even columns, something Firebird allows), so here you can turn off the warning for that particular database

12.3. Logging

Please see the section about global logging configuration. The options are the same here, but they apply to the current database only. There is an additional option to turn off logging for a particular database only, while leaving it active for all the other databases.

There are also additional options to enable logging to a database table. The table is called FLAMEROBIN$LOG and it is created automatically the first time it's needed. Each record written to this table gets an ID fetched by executing a SELECT statement that you can customize. By default, FlameRobin fetches the values from a generator called FLAMEROBIN$LOG_GEN, which is created on demand as well. You might want to set a custom SELECT statement if you want to use the ID as some kind of metadata version number for your database, in which case you define the logic to follow when generating new IDs. For example, you could write a stored procedure and have FlameRobin call it.

13. The FlameRobin environment

FlameRobin needs, or creates, some external files. This section documents what these files contain, and where they are found. While FlameRobin is installed with usable default settings, it is possible to fine-tune the installation for special uses or multiple users. The information provided here is valuable in this regard.

FlameRobin uses the following files and folders:

  • fr_settings.conf; a file containing all settings you see in the Preferences dialog box and other global settings of FlameRobin, like position and size of open windows. FlameRobin needs write access privileges to this file.

  • fr_databases.conf; a file containing all the servers and databases defined in FlameRobin's Home tree. FlameRobin needs write access privileges to this file.

  • the html-templates and conf-defs folders, which contain metadata used to render some of FlameRobin's windows, and the docs folder, containing documentation files that can be opened through FlameRobin's main menu. FlameRobin only needs read access to the files in these folders.

Locations:

  • $frhome is FlameRobin's home path. FlameRobin will find html-templates, conf-defs and docs (which are immutable and integral part of the FlameRobin distribution) in its home path. The home path is usually the application folder (on Windows) and an otherwise fixed folder on POSIX platforms.

    Note

    Defining the environment variable FR_HOME will override this path.

    Note

    Passing -h <path> on FlameRobin's command line will override this path and the environment variable as well.

  • $fruserhome is FlameRobin's user home path. FlameRobin will find the conf files in its user home path. This path has to be writable and may be common to all users on the machine or different for each user. The user home path defaults to the user local data directory, which varies with the platform.

    Note

    Defining the environment variable FR_USER_HOME will override this path.

    Note

    Passing -uh <path> on FlameRobin's command line will override this path and the environment variable as well.

Additionally, the <path> specification in the command line parameters -h and -uh, or the value of the environment variables FR_HOME and FR_USER_HOME may be "$app", which translates to the common data folder (the application folder on Windows and an otherwise fixed folder on POSIX platforms), or "$user", which translates to the user local data directory. Otherwise, it has to be a path (without the trailing path delimiter).

FlameRobin will only ever write to files in $fruserhome. If FlameRobin is configured so that these files are shared by several users (or concurrent instances of FlameRobin), then no precaution is taken to avoid overwriting other users' changes.

14. Advanced topics

This section will document some advanced topics about how FlameRobin works. The topics are not necessarily related, and are grouped here only for convenience.

14.1. Encrypted password storage

FlameRobin can use strong encryption to safely store your passwords in the configuration file (fr_databases.conf). Here's how it works in detail:

  • all passwords (PW) are encrypted with a master password (MPW)

  • the MPW alone is never saved into any file, it is only known by the user

  • PW + MPW comprise the Cipher (which is stored in the .conf file)

  • whenever a PW needs to be decrypted, the user is prompted for the MPW

  • Cipher + MPW yield the PW

14.1.1. Defense from "known plain-text" attack

If an attacker gets hold of FlameRobin's .conf file, and he knows one of the PWs, he would be able to compute the MPW (as Cipher + PW yield the MPW). In order to prevent this, FlameRobin uses the following scheme:

  • the string composed by MPW + username + database connection string is used as a seed for some irreversible random number generator (RNG) like ISAAC

  • the PW is encrypted with the numbers produced by the RNG

  • since numbers are unique for each username + database connection string, and RNG is not reversible, the attacker cannot get MPW, and he also cannot decrypt any other password

For more information on ISAAC see: http://en.wikipedia.org/wiki/ISAAC http://www.burtleburtle.net/bob/rand/isaacafa.html