Metadata-Version: 2.4
Name: Products.FirebirdDA
Version: 0.8.0
Summary: Firebird database adapter for Zope 5
Home-page: https://github.com/nakagami/Products.FirebirdDA
Author: Hajime Nakagami
Author-email: nakagami@gmail.com
License: ZPL
Keywords: Firebird
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Framework :: Zope :: 5
Classifier: License :: OSI Approved :: Zope Public License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/x-rst
Requires-Dist: firebirdsql
Requires-Dist: Products.ZSQLMethods
Provides-Extra: firebird-driver
Requires-Dist: firebird-driver>=1.4.0; extra == "firebird-driver"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

FirebirdDA
==============

FirebirdDA https://github.com/nakagami/Products.FirebirdDA is Zope database
adapter for Interbase/Firebird.

Requirements
------------

- Python >= 3.11
- Zope 5

Installation
-----------------

buildout.cfg::

   eggs =
       ...
       Products.FirebirdDA

Driver Configuration
--------------------

FirebirdDA supports two Firebird Python drivers:

- ``firebirdsql`` (default, auto-detected)
- ``firebird-driver``

Set the ``FIREBIRDDA_DRIVER`` environment variable to select a driver
explicitly.  In a Zope deployment this is typically done in ``zope.conf``::

   <environment>
     FIREBIRDDA_DRIVER firebird-driver
   </environment>

If the variable is not set, FirebirdDA auto-detects: it tries to import
``firebirdsql`` first and falls back to ``firebird-driver``.

To use ``firebird-driver``, install it as an extra::

   pip install Products.FirebirdDA[firebird-driver]

Connection String
-----------------

The connection string uses space-separated ``key=value`` pairs::

   dsn=host:/path/to/database.fdb user=sysdba password=masterkey

The ``dsn``, ``user`` and ``password`` keys are passed directly to the
driver's ``connect()`` function.  When using ``firebird-driver``, the
DSN is automatically converted from ``firebirdsql`` format
(``host:/path``) to ``firebird-driver`` format (``host:path``).

Driver Differences
------------------

The two drivers differ in how they return fixed-length ``CHAR(n)``
values:

- ``firebirdsql`` strips trailing spaces from ``CHAR`` columns
  automatically (``xsqlvar.py``: ``SQL_TYPE_TEXT`` → ``rstrip()``).
- ``firebird-driver`` returns ``CHAR`` values padded to the declared
  column width, as delivered by the Firebird wire protocol.

When switching from ``firebirdsql`` to ``firebird-driver``, code that
compares or displays ``CHAR`` values may need explicit ``rstrip()``
calls, or the column can be migrated from ``CHAR(n)`` to
``VARCHAR(n)``.

Test Tab
--------

The ZMI Test tab supports ISQL-style meta commands (requires the
Test Database Connections permission):

- ``show tables`` — list all user tables
- ``show table NAME`` — show columns of a table
- ``show views`` — list all user views
- ``show view NAME`` — show the view source
- ``show procedures`` — list all stored procedures
- ``show procedure NAME`` — show the procedure source
- ``show functions`` — list all user functions
- ``show function NAME`` — show the function source (Firebird 3+)
- ``show triggers`` — list all user triggers
- ``show trigger NAME`` — show the trigger source
- ``show generators`` — list all generators (sequences)
- ``show domains`` — list all user domains
- ``show exceptions`` — list all user exceptions
- ``show version`` — show Firebird engine version
- ``show database`` — show database name, engine version and current user



Changelog
=========

Unreleased
----------

Python 3.11+ modernisation
~~~~~~~~~~~~~~~~~~~~~~~~~~
- Require Python 3.11 or newer; target Zope 5.
- Code style: f-strings, ``contextlib.suppress``, proper exception
  chaining, remove unused imports and dead code.
- Unify docstring/comment style across the codebase.
- Extract ISQL meta command translation into a dedicated ``isql_meta``
  module.

Driver support
~~~~~~~~~~~~~~
- Add support for ``firebird-driver`` as alternative to ``firebirdsql``.
- Automatic DSN format conversion between drivers.
- Fail fast on an unsupported ``FIREBIRDDA_DRIVER`` value.

Reliability
~~~~~~~~~~~
- Simplify connection retry logic and improve error resilience.
- Raise ``OperationalError`` when retries are exhausted instead of
  silently failing.
- Guarantee cursor cleanup by splitting ``query()`` per driver.

Error reporting
~~~~~~~~~~~~~~~
- Format ``firebird-driver`` error messages for HTML display.
- HTML-escape error text and the SQL snippet so the Test tab cannot
  break on markup or Zope ``TaintedString`` input.

ZMI enhancements
~~~~~~~~~~~~~~~~
- Add ISQL ``show`` meta commands in the Test tab: object lists
  (tables, views, procedures, functions, triggers, generators, domains,
  exceptions), ``show table NAME`` (columns),
  ``show procedure/view/trigger/function NAME`` (object source, rendered
  with whitespace preserved so it copies cleanly), plus ``show version``
  and ``show database``.
- Show connection status in the object listing.
- Include SQL snippet in error messages for Manager callers.

Security
~~~~~~~~
- Remove unused connection cache that held plaintext credentials.
- Restrict SQL snippets in error messages to Manager callers.
- Gate ISQL meta commands via the Test tab's ``Test Database
  Connections`` permission instead of a Manager-role check, translating
  in the Connection's ``manage_test`` (DA layer) rather than the shared
  ``query()`` path -- so Z SQL Methods are never affected.

0.7.1 (2024-01-04)
------------------
- Reopen connection on "too many handles" errors and fix
  ``OperationalError`` output. [044144c]
- Add connection retries in ``query()`` method. [8cd2b8b]

0.7.0 (2020-06-20)
------------------
- Port to Zope 4 and Python 3. [1e2033f]
- Refactoring of forms, classifiers and imports. [9c7af69, 0984739, c2f8eda,
  1e080d7]

0.6.x (2014)
------------
- Disable connection pool (do not reuse connections across requests).
  [3fefc46]
- Enable ``set_autocommit(True)``. [a2e57f5]
- Declare ``Products`` namespace package. [3ebe2f8]
- Add trove classifiers. [0c61502]

0.5.0 (2012-01)
---------------
- Initial release by Hajime Nakagami, forked from ``ZKinterbasdbDA 0.5.0``
  and switched to the ``firebirdsql`` driver. [77e9b51, d7f6336]
