Debugger

[Adriano dos Santos Fernandes]

Today, troubleshooting of Firebird PSQL code is a real challenge. Users
need to modify their code to collect information to understand the code
problems (or to understand a code written by other). Due to things as
transaction control, many times this even requires creation of new
tables (external, or used in autonomous transaction) to not lose the
debug data together with exceptions. If we talk about shared test
databases, these problems are even worse. The problem is so real that
third party tools exist, implemented with hacks and lagging to Firebird
releases.

With the AI advent and it's fast evolution, a debug tool attached to a
MCP is going to make developer's life much more productive and is going
to be more and more needed.

Here I propose a debugger protocol, that together with a debugger cli
tool (also to be implemented) will allow Firebird users to debug its
code, without the need to modify it.

I'd first like to list common debugger features, but I'm not going yet
to go deep on them:
- Session management (attach, detach)
- Breakpoint management (add, remove, clear, list)
- Conditional breakpoints
- Exception breakpoints
- Stack trace dump of paused code
- Frame dump of a paused routine
- Continue execution
- Step over
- Step into
- Step out
- Pause current execution
- Evaluate expressions and statements
- Change variables and parameters

The debugger is going to be used as an additional connection to a
database, managing another connection to be debugged.

Also, the builtin cli tool or third party ones should be easily created
in regard to the protocol. So, another wire protocol is out of question.

We already have a similar mechanism: the profiler. Its interface to
client applications is a Firebird package.

While I propose such mechanism for the debugger, it should be clear that
ISQL is not the target debugger application, but a specific tool should
be made.

There will be SYSTEM.RDB$DEBUGGER package, with procedures and functions
related to the needed operations, for example:

-- breakpoint id will be returned
select system.rdb$debugger.new_function_breakpoint(<schema>,
<package or null>, <name>, <optional line>)
from rdb$database;

When engine found a pause-point, it will post an event RDB$DEBUGGER and
will wait for a debugger command (continue, step, get/set things, etc).

The debugger application listen for RDB$DEBUGGER events and will known
when it needs to ask things (stack trace of the pause) to the engine.

And it will ask with another RDB$DEBUGGER function, like this:

select * from system.rdb$debugger.get_stack_trace;

Some commands like breakpoint management will work asynchronously, even
when Firebird is executing user's code.

Others, like get_stack_trace, will work only when the engine is paused
waiting for a debugger command.

Complementing RDB$DEBUGGER package, the debugger could normally use MON$
tables to get information about the debugged connection.


Adriano

[Alex Peshkoff]

Just to make sure - does it mean that all interaction with debugger is
done using SQL, nothing like new interface is needed?

> While I propose such mechanism for the debugger, it should be clear that
> ISQL is not the target debugger application, but a specific tool should
> be made.

In that case I'm not 100% sure that use of SQL as base level for
debugger protocol is ideal choice. I doubt debugging is somehow related
with for example transactions in an additional connection used for
debugging.

As an alternative special interface in Attachment can be used. Or for
example new service - this way is successfully used by trace, as
additional '+' better abilities to debug cross-database calls.

[Pavel Cisar]

Dne 16. 10. 25 v 15:55 Alex Peshkoff napsal(a):

>
> As an alternative special interface in Attachment can be used. Or for
> example new service - this way is successfully used by trace, as
> additional '+' better abilities to debug cross-database calls.

+1 to API extension. I doubt that anybody would use SQL interface
directly, as this functionality calls for specific tool. And for those
who will implement debuggers, calling API functions is more convenient
than using SQL machinery. Most debugger protocol commands are function
calls anyway, and most do not return complex data that would benefit
from SQL tabular output. Using SQL made sense for profiler, but I think
that debugger would be better as direct API extension.

regards
Pavel

[Attila Molnár]

Also nice to have debugger features:

- data breakpont: stop when a given variable value changes, or its value is in a given set

- assert: boolean expression only evaluated ad debug mode. When false, it throws an assertation exception

- uptodate performance metrics in MON$ (non snapshot behaviour)

- write current debug state (callstack, frames, etc...) to permamnent tables on exception or a utility procedure call

- server side log file read and write

- not a debugger feature, but related : code coverage report

I propose a new prefix for this: not RBB$, but DBG$ (or use MON$ ?).

[Роман Симаков]

I support SQL interface. At least any esisting driver is ready to write debug tool. This feature could be easely intergated to existing tools. But I doubt it's possible with specific extension which will require development on network layer of driver (read noone will do it)

 

----------------

Кому: firebir...@googlegroups.com (firebir...@googlegroups.com);

Тема: [firebird-devel] Debugger;

16.10.2025, 17:13, "Pavel Cisar" <pci...@gmail.com>:

--
Support the ongoing development of Firebird! Consider donating to the Firebird Foundation and help ensure its future. Every contribution makes a difference. Learn more and donate here:
https://www.firebirdsql.org/donate
---
You received this message because you are subscribed to the Google Groups "firebird-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email to firebird-deve...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/firebird-devel/3eb1340e-ed96-440a-9c04-bdba640fd0c3%40gmail.com.

[Dimitry Sibiryakov]

Attila Molnár wrote 16.10.2025 16:22:
> Also nice to have debugger features:
> - data breakpont: stop when a given variable value changes, or its value is in a
> given set

The same question as for breakpoints: stop for what? Inspect variables'
values, right? This functionality is more useful in trace: one can inspect logs
without hurry.

> - assert: boolean expression only evaluated ad debug mode. When false, it throws
> an assertation exception

Also better in trace.

> - uptodate performance metrics in MON$ (non snapshot behaviour)

It is task for a profiler.

> - write current debug state (callstack, frames, etc...) to permamnent tables on
> exception or a utility procedure call

Trace again.

--
WBR, SD.

[Denis Simonov]

I like the idea of ​​making this a system package. But I have some doubts about some of the capabilities. 

For example, how do I get the current values ​​of variables? All these variables are of different types, including BLOB variables.

I'd like to see the signatures of the procedures and functions in this package to understand what's possible and what isn't.

четверг, 16 октября 2025 г. в 17:38:52 UTC+3, Dimitry Sibiryakov:

[Adriano dos Santos Fernandes]

Just to make sure - does it mean that all interaction with debugger is
done using SQL, nothing like new interface is needed?

> While I propose such mechanism for the debugger, it should be clear that
> ISQL is not the target debugger application, but a specific tool should
> be made.

In that case I'm not 100% sure that use of SQL as base level for
debugger protocol is ideal choice. I doubt debugging is somehow related
with for example transactions in an additional connection used for
debugging.

When thinking about monitoring (for session to be debugged discovery and also to get its monitoring data), a connection is going to always be needed.

As an alternative special interface in Attachment can be used. Or for
example new service - this way is successfully used by trace, as
additional '+' better abilities to debug cross-database calls.

I'd not say alternative. I could agree with addition of interface from the attachment. It will be implemented in the client using SQL code (package, events, etc) as previously described.

Adriano

[Alex Peshkoff]

Please get me right - I do not insist on something and yes, for _some_
tasks like access to monitoring data or even backtraces SQL-based
interface appears OK. But how will be CONTINUE command processed - when
issued or on transaction commit? What if 2 different transactions start
to manage breakpoints in conflicting way? Sooner of all that's all
solvable - but appears not trivial at the first look and better be
decided in advance.

[Jim Starkey]

Having more than a little experience writing debuggers, may I suggest
that trying to force a debugger interface in SQL, designed for a
completely different problem set, is perhaps not the best solution.

My multi-node debugger consists of a debug agent using ptrace, ELF, and
DWARF, and a GUI (originally MFC now Java).  The protocol is
request/response exchanges between the client and the agent using XML. 
XML works particularly well as it is platform independent, infinitely
extensible, and allows either end to ignore things that it may not
understand.  Extensibility is exceptionally important.

There is nothing magic about Java other than it has a well defined an
portable GUI.

My multi-node debugger is pure point and click.  I has been my strong
option for about 45 years that CLI based debuggers suck.

--
Jim Starkey

[Adriano dos Santos Fernandes]

On 10/16/25 11:53, Denis Simonov wrote:
> I like the idea of ​​making this a system package. But I have some
> doubts about some of the capabilities. 
> For example, how do I get the current values ​​of variables? All these
> variables are of different types, including BLOB variables.
>

It's common for debuggers to truncate long data in the screen, and that
would be fine for me. It would also not be a problem to get its string
representation together with its data type.

If any debugger has a feature to save some (large) value to temporary
location and later assign it to another variable, I *never* used it.


Adriano

[Adriano dos Santos Fernandes]

On 10/16/25 13:28, Alex Peshkoff wrote:
>
> Please get me right - I do not insist on something and yes, for _some_
> tasks like access to monitoring data or even backtraces SQL-based
> interface appears OK. But how will be CONTINUE command processed - when
> issued or on transaction commit? What if 2 different transactions start
> to manage breakpoints in conflicting way? Sooner of all that's all
> solvable - but appears not trivial at the first look and better be
> decided in advance.
>

The world do not became rollback-able because Firebird needs a
transaction to execute code. :)

If you call an UDR that sends a email, it will not be deferred to
commit-time nor the email will disappear from the destination if
transaction is rolled back.

It's the same with this package, transaction is not used for anything.


Adriano

[Alex Peshkoff]

On 10/16/25 23:35, Jim Starkey wrote:
> The protocol is request/response exchanges between the client and the
> agent using XML.  XML works particularly well as it is platform
> independent, infinitely extensible, and allows either end to ignore
> things that it may not understand.  Extensibility is exceptionally
> important.

Yes such request/response using XML appears to be the best choice.

[Dimitry Sibiryakov]

JSON is simpler, you don't have to care about attributes in nodes.

--
WBR, SD.

[Alex Peshkoff]

On 10/17/25 03:37, Adriano dos Santos Fernandes wrote:
> On 10/16/25 13:28, Alex Peshkoff wrote:
>> Please get me right - I do not insist on something and yes, for _some_
>> tasks like access to monitoring data or even backtraces SQL-based
>> interface appears OK. But how will be CONTINUE command processed - when
>> issued or on transaction commit? What if 2 different transactions start
>> to manage breakpoints in conflicting way? Sooner of all that's all
>> solvable - but appears not trivial at the first look and better be
>> decided in advance.
>>
> The world do not became rollback-able because Firebird needs a
> transaction to execute code. :)

I can agree that transactions should not affect debugger behavior.
That's why use of interface, requiring presence of correct transaction
handle to access debugger, appears not logical to me. Use of XML or JSON
in transactions unrelated interface looks much more logical.

> If you call an UDR that sends a email, it will not be deferred to
> commit-time nor the email will disappear from the destination if
> transaction is rolled back.

This may be a buggy behavior in some cases :-)

> It's the same with this package, transaction is not used for anything.

:-(

On the other hand I can agree with one serious argument, provided by
Roman - it greatly simplifies use of debugger with 3d-party tools.

[Adriano dos Santos Fernandes]

On 10/17/25 06:02, Alex Peshkoff wrote:
>
> On the other hand I can agree with one serious argument, provided by
> Roman - it greatly simplifies use of debugger with 3d-party tools.
>

Not only that, it's going to simplify development of the feature a lot.

Must say that in my initial investigations of the approach, I used JSON
exchange with a more generic packaged function. It's an approach too.
But specific functions is a "hard documentation" of the thing. Generic
JSON requires extra text documentation and extra understanding of the
user (debugger writer).


Adriano

[Mark Rotteveel]

Except things like schemas, schema *extension*, transformation (XSLT)
and other things are much better defined in XML than in JSON.

Besides, no one force you to use attributes in your design if you don't
want it (though to be honest, I think using attributes can be more
powerful and result in better designs compared to what JSON offer), and
it sounds like a rather spurious argument for choosing JSON over XML.

Mark
--
Mark Rotteveel

[Jim Starkey]

Either would do.  My XML parser is 206 lines exclusive of Lex, my JSON
parser is 140 lines also exclusive of Lex.  The XML parser, however,
handles XML declarations and comments, both of which are missing from
JSON.  I don't actually use XML declarations as UTF-8 is the only
character set used by Amorphous.

One could argue than JSON doesn't have a date format while XML does, but
in either case it's a convention rather than part of the grammar.

But if I had to do it all over again, I'd still use XML.

Jim Starkey