FlameRobin 0.4.0 ALPHA Manual

Nando Dessena


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
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. Advanced tools
10. Configuration
10.1. General
10.1.1. Center dialogs on their parent window
10.1.2. Remember window positions and sizes
10.1.3. Confirm quit
10.2. Main Tree View
10.2.1. Order server entries alphabetically
10.2.2. Order database entries alphabetically
10.2.3. When a column has a user-defined domain
10.2.4. Show columns and parameters in tree
10.3. SQL Editor
10.3.1. When text is selected in editor
10.4. Data Grid
10.4.1. Date format
10.4.2. Time format
10.4.3. Grid header font
10.4.4. Grid cell font
10.4.5. Re-format float and double precision numbers
10.4.6. Maximize data grid after execution of SELECT statement
10.5. Logging
10.5.1. Log DML statements

1. About this manual

Currently this manual is incomplete, and it will probably stay incomplete until FlameRobin 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 use it for daily work already). 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 market; 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 for the "lite" edition of FlameRobin is 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 Initial Developer's Public 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 CVS. 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, 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.

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 to have 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

For the time being, unpacking the supplied archive into a directory of your choice will do. We are working on installation packages for the various Linux distributions.

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

Upon first startup, FlameRobin will present a "Firebird Servers" tree containing only the local server (localhost), and will invite you to create new servers and databases as required. Here is a brief how-to for getting started with FlameRobin.

9.1. Adding a server

You can add a server by righ-clicking in "Firebird Servers" and choosing "Register server...". You will have to specify a display name, the host name and optionally the TCP port number (default 3050) on which the Firebird server listens. 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).

9.4. Connecting to a registered database

Just double click on the database name in the tree, or right click it and choose "Connect". 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.

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. 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 f. ex. 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 of us have been using FlameRobin in their everyday Firebird development for months without a problem.

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 lower grid. 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.

9.8. Running SQL statements and scripts

Of course you can use the SQL editor window to execute arbitrary SQL statements. 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), and a data export tool: to activate it, right click on the data grid. The data export tool is currently able to copy the data to the clipboard, generate SQL INSERT 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.

9.9. Advanced tools

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), or "Restore backup into new database..." 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.

10. 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..." menu command in the local menu of the tree's root node. 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.

10.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.

Set this option to 1 to enable storing size and position of each window (frame) on closing. Set it to 0 to disable the feature.

Note

The object properties frame's storage option can be further customized, see MetadataFrameStorageGranularity.

10.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.

10.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.

10.1.3. Confirm quit

Set this option to have FlameRobin ask you for quit confirmation.

10.2. Main Tree View

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

10.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.

10.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.

10.2.3. When a column has a user-defined domain

In this case you can choose to see only the domain, only the datatype or both domain and datatype in the tree item's caption.

Note

This option only applies when columns are displayed in the tree (see the following option).

10.2.4. 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.

10.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.

10.3.1. When text is selected in editor

This options turns on and off a useful feature of the SQL Editor: you can type in or paste several SQL statements and execute just one of them by selecting it before hitting the Execute button. If for some reason you'd like to always execute the content of the whole editor buffer, then disable this option.

10.3.1.1. 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 this option is disabled, 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 statement with SET TERM. This way, you can select and execute the statement, and you don't need SET TERM at all.

10.3.1.2. 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.

10.3.1.3. 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.

10.3.1.4. SQL Code Completion

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

10.3.1.4.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 (default 5), and choose to disable code completion when a call-tip is displayed as it would close the call-tip.

10.3.1.4.2. Manually invoke auto-complete list on

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

10.3.1.4.3. Allow auto-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 Tab key for that.

10.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.

10.4.1. Date format

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

10.4.2. Time format

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

10.4.3. Grid header font

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

10.4.4. Grid cell font

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

10.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.

10.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.

10.5. Logging

The SQL Editor can log all executed statements to a text file (and, in a future release, to a database table). Here you set the options to tune this feature.

10.5.1. Log DML statements

When logging is enabled, by default only DDL (data definition) statements are logged. Turn this option on to enable logging of DML (data manipulation) statements as well.

10.5.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 wish 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 zeroes.