User Tools

Site Tools


wiki:manual

FlameRobin Manual

About this manual

We try to keep all the features in FlameRobin usable in an intuitive manner. However, there are things that you still need to know if you want to grasp the full power of the application, and this manual contains details about them. In this document, you will find an overview of the features, a description of all configuration parameters and advanced installation and customization notes.

Help Us Help You

Lots of people have been using FlameRobin in day-to-day work for a long time now. There are still features to be completed . Meanwhile, we thank you for evaluating and using this software and encourage you to send comments, bug reports and feature requests back to us so we can make it better. Code contributions and patches are better :)

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.

Who we are

The home page of the FlameRobin project is located at http://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.

License

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

What's new?

Please refer to fr_whatsnew.html, in FlameRobin's docs directory, for a detailed history of all the changes since the previous release.

Installation

If you want to build FlameRobin from sources, please find instructions on our web site or Subversion repository (see BUILD.txt). This section only talks about installing the pre-built version of FlameRobin under all currently supported platforms.

General information

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 an empty one (with only the “localhost” predefined 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 - and are encouraged not to - edit it by hand.
  • sys-templates (folder) stores code templates used internally by FlameRobin, which can be overridden by the user (this is an advanced topic - see below).
  • code-templates (folder) stores code templates that the user can run by means of the Generate code menu (this is an advanced topic - see below).
  • history stores (folder) the history of executed SQL statements.

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.

Windows

To install FlameRobin under Windows you need the Firebird client (fbclient.dll for Firebird 2.x 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. It will also copy user configuration files to your user “application data” folder (which changes depending on the Windows version you are using; an example under Windows 7: C:\Users\YourName\AppData\Local\flamerobin). 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.

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. The 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. If you need more detailed instructions, you can browsehere.

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.

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.

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.

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, type in or locate (or drag and drop) the database path (or alias name), the user name and password.

If you don't specify the password, FlameRobin will prompt for it every time you try to connect to the database, which is the most secure option. If you want to store the password, you can have FlameRobin optionally encrypt it with a master password stored in the configuration file. You can also use Firebird's trusted “user authentication mode”, which logs you in based on your OS user account. All these options are available through the “Authentication” combo box.

You can also optionally specify a connection charset and role.

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 as the password if you don't know what to put in these fields), the character set (like ASCII, ISO8859_1 for western europe, or UTF8 for unicode), the role, the page size (the default value of 4096 is just fine) and the SQL dialect (leave it set to 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 database” menu command to do that.

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…”. This loads essential metadata information from the database. FlameRobin tries to play well with slow network connections by delaying metadata retrieval as much as possible, yet connecting to a database still needs some data transfer beyond the connection itself.

Choose “Disconnect” to close the connection to the database.

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.

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. 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 options are not yet available, but you can edit almost all aspects of the most common objects (tables, views, stored procedures, and so on).

Browsing and editing data

After connecting to a database, locate a table, view or selectable stored procedure of your interest in the tree and right-click it. The “Browse data” command 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 input parameter values (if 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 (there is also a configuration option to make complete fetching the default behaviour, something we usually don't recommend). 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.

Once you have some data in the grid, you can re-sort the data by double clicking on column headers. The first double click will sort the data in ascending order, the next on in descending order, and so on.

You can change the data through direct editing in the grid, add new records by means of the “Insert” button (which opens a specialized dialog box) and delete the currently selected record(s) by clicking the “Delete” button. Confirm any changes by clicking the “Commit” button, or cancel them through the “Rollback” button. Deleted records are still displayed (on a red background) until you commit, just in case you change your mind.

Please note that emptying a cell that displays a string field will set the field's value to ''; if you want to set it to NULL, you need to delete all contents and then hit the DEL key once more.

Also note that you can type the strings 'NOW', 'DATE', 'TODAY', 'TOMORROW', 'YESTERDAY' in cells of type date or timestamp, and the strings 'NOW' and 'TIME' in cells of type time. They will be translated by FlameRobin to their respective meanings.

FlameRobin handles all interactive edit operations by generating corresponding SQL statements. By default they are all logged in the history, but you can turn logging off for an instance of the SQL editor through the “History/Enable logging” menu command. You can also turn logging off globally or for a particular database, through the “View/Preferences” in FlameRobin's main menu.

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 “Execute SQL statements”. 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, detailed execution statistics (including but not limited to the query PLAN and the number of records inserted, deleted, updated in each affected table), a data export tool and more.

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

You can use the drop-down menus or the context menu in the SQL editor as well as the buttons.

Auto-completion can be invoked automatically or manually (see the rich set of preferences about this feature), 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 or CSV 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 to generate customized INSERT or UPDATE statements. Please note that clicking on a column header will select all data cells of that column.

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.

FlameRobin will try to let you edit whatever result set your SELECT statement returns (provided it can find a way to uniquely identify records), or part of it. Fields that you cannot edit will be displayed in a special background colour in the grid.

Backup and restore

You can perform a database backup by right clicking on a database and choosing “Tools/Backup database”. Choose “Tools/Restore database” to restore a backup file over the current database (you will have to disconnect first). Please note that, while possible, it is considered bad practice to restore a backup file over an existing database.

To create a new database based on a backup file, right click on a server node and choose “Restore backup into new database”. A new database will be restored from a backup file.

All these options will open specific windows in which you can select backup and restore options. You can drag and drop files in these windows.

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.

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.

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.

Alter 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 again. 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 right-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 the view definition (the CREATE VIEW statement inside the generated script) and recreate everything with a single click.

Connected users

The database property page will show a list of all currently connected users (if you are SYSDBA and are connected to a SuperServer variant of Firebird - otherwise limitations in different Firebird flavours apply).

Event monitoring

FlameRobin allows you to listen for Firebird events interactively. Just select the “Tools/Monitor events” command at the database level (or in the “Database” menu) to open the Event Monitor window (you will be automatically connected to the database, if needed). 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).

User management

Firebird uses a central server-wide user repository, locate inside the security2.fdb system database. 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.

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

Starting from Firebird 2.5, you can also issue CREATE USER, ALTER USER and DROP USER SQL commands to manage users.

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 each object's property page (in the “Privileges” subpage) you can view the privileges associated with that object, and if you hover the mouse over icons, you can see who granted them in a tooltip. Clicking on the “Grant and revoke privileges” link will open a dialog box that allows you to grant 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 while logging is enabled).

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.

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.

This feature, which you can fire through the lens button in the lower right corner of FlameRobin's main window, allows you to perform more advanced search operations in your database's metadata (or in more than one database 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, which means that all of them must be satisfied for an object to be included in the SEARCH RESULTS pane.

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.

Test data generator

FlameRobin includes a test data generator which you can use to create test databases with dummy data values. You can launch it through the “Database/Tools/Test data generator” command in a database's context menu. In the resulting dialog box you can select the tables for which you want to generate data, how many records you want to generate for each table, and the data generation strategy on a per-colum basis. Among the available strategies you'll find sequential values, random values, values taken from other columns, values loaded from external files, and a customizable NULL ratio. Your settings can be saved to an XML file and reloaded later. When you're ready, hit Generate data and the database will be filled with test data.

Code generation

Each object's context menu may feature a “Generate code” submenu, that allows you to launch a code generator based on a code template (a text-file with special markup syntax). FlameRobin comes with a few predefined templates, which are both useful “per se” and as examples to follow when creting your own templates.

Code templates are stored in the code-templates directory of FlameRobin's home directory ($frhome). User templates are stored in the code-templates folder of FlameRobin's user directory ($fruserhome). Look here for details about locating these folders. FlameRobin will build the “Generate code” submenu by combining the list of files in these two directories. Any file in $fruserhome with the same name of a file in $frhome will override it. This allows you to customize provided templates on a per-user basis (in addition to adding your own templates).

Each template that needs to be called from the “Generate code” submenu is made up of two files (plus an optional third file if the template is an interactive one):

  • template_name.info contains information used to display the menu item, such as the caption, and information about which object(s) it should be attached to.
  • template_name.template contains the template code, which is processed by FlameRobin and whose output is then opened in the SQL editor.
  • template_name.confdef contains the definition of a set of parameters that the user will be required to fill in when the template is run. These parameters are then used to customize the template's behaviour. Not all templates need this file; only interactive ones, which contain the {%edit_conf%} template command.

Template info files

A template.info file is basically an INI file. Here is an example:

[templateInfo]
menuCaption=Update {%object_name%} set ... where ...
menuPosition=30
matchesType=^TABLE$
matchesWhen={%!:{%is_system%}%}

All options should be inside the [templateInfo] section. Allowed options:

  • menuCaption is used as the caption for the menu item. Please note that this can be dynamic, as it's itself a template. Look in the next section for template syntax.
  • menuPosition is used to determine the order of menu items. FlameRobin's predefined templates define a sequence with holes in it so that custom templates can be added everywhere.
  • matchesType is a regular expression that, if specified, must match an object's type name for the menu item to be created. If you don't specify matchesType, the templates is attached to objects of any type.
  • matchesWhen is a template that, if specified, should evaluate to “true”. In the example above, the template applies only to non-system objects.
  • matchesName is a regular expression that, if specified, must match an object's name (for objects of type DATABASE, the display name counts). If you don't specify matchesName, the templates is attached to objects regardless of their name.

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 this section of the documentation will likely be out-of-date. Please refer to the tooltips for fresh descriptions of all the available options.

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.

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.

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.

Main Tree View

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

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.

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.

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.

When table, view or stored procedure is activated

Here you choose what should happen when you double click on a table, view or stored procedure node in the tree. Available options include opening the property page, show columns as sub-nodes of the selected node or select from the table, view or stored procedure to see the data.

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.

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.

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.

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.

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.

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.

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.

Display detailed query statistics

Enable this option to have the SQL Editor show detailed statistic information for each query, in addition to the query PLAN. This includes number of fetches, marks, reads, writes; number of inserts, updates, deletes; number of indexed vs sequential reads; delta memory; execution time.

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.

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.

Tab size

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

Code Completion

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

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.

Manually invoke completion list on

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

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.

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.

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.

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.

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.

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.

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.

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.

Date format

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

Time format

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

Grid header font

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

Grid cell font

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

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.

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.

Automatically fetch all records in result set

Makes it so the grid will automatically fetch all records whenever a SELECT statement is executed, instead of doing it in batches.

Show BLOB data in the grid

Check this option if you want to see data fetched from BLOB fields in the grid. By default FlameRobin doesn't fetch BLOBs. You can also set a threshold, thus telling FlameRobin to fetch at most a specified amount of data for each BLOB. This allows you to see the first part of every BLOB field automatically without risking to download huge amounts of data for no gain. Check the “Show data for binary BLOBs” if you want the above settings applied to binary BLOBs as well (by default they are applied to text BLOBs only).

Property Pages

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

Show default column values

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

Show column descriptions

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

Sql Statement generation

This page offers options to customize the way FlameRobin generated SQL code, 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 the relevant settings to their default values.

Use UPPER CASE keywords

Uncheck this option if you prefer FlameRobin to use lowercase keywords in generated SQL code.

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 enters Turns into
FIELD1 FIELD1
Field1 Field1
Date “Date”


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

User enters Turns into
FIELD1 FIELD1
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.

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.

Fields

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

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.

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.

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.

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.

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.

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.

Main Tree View

Show system tables in tree

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

Connection

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

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

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.

Customizing 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. For example, you can change the icons, the HTML templates used as property pages for the objects in a database, or where FlameRobin stores and looks for its configuration files.

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.

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.

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

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_(cipher)

http://www.burtleburtle.net/bob/rand/isaacafa.html

wiki/manual.txt · Last modified: 2015/01/16 08:17 by mariuz