fbdb 1.8.1

A Firebird SQL database access library for Dart and Flutter.

1.8.1

• Fixed an instance of IMessage not being released upon closing an FbBatch instance (causing a memleak).
• Fixed the index of the errorneous parameter set propagation in FbBatch.addAll, for some classes of errors.
• Fixed two places in the programmer's guide where chunkSize parameter of the FbQuery.rows() method should have been passed as a named parameter, and not a positional one.

Thanks to vkruglik for pointing out the mistakes in the commens of issue #18.

1.8.0

• This release focuses mainly on performance improvements, as suggested by vkruglik in issue #18.
• FbBatch API has been extended with addAll method, addressing performance bottlenecks signaled in issue #18. FbBatch.addAll allows a collection of batch parameter sets to be added to the batch with a single call (and a single message will be sent from the main isolate to the worker isolate).
• FbQuery's methods: fetchAll, fetchAllAsMaps, fetchAllAsLists, as well as the rows and rowValues streams now accept an optional chunkSize parameter (with the default value of 10), which defines the number of rows fetched from the worker isolate in a single message sent from the worker to the main isolate. The higher chunksSize is, the less messages will be exchanged between the isolates, but each message will contain a larger buffer, temporarily increasing memory consumption. Adjust chunkSize only if you experience performance bottlenecks caused by the inter-isolate communication and measure the impact afterwards.
• FbQuery.fetch, FbQuery.fetchAsMaps and FbQuery.fetchAsLists (all of which accept a rowCount parameter) now use a single message exchange between the main and worker isolates to fetch the requested number of rows. Previously rows were fetched one by one, each row requiring an exchange of messages between the isolates.

1.7.2

• Fixed double release of the IBatch interface instance, possibly leading to undefined behavior (mentioned in issue #18). Added safeguards in IDisposable and IReferenceCounted interface bindings to deal with accitental multiple calls to release / dispose.

1.7.1

• Improved handling of multiple concurrent FbDb connections in a single application. Some internal refactorings were required (making all low-level interfaces specific to a worker istance, instead of being globally available for all workers). All changes in this point release impact only the private part of the library (the worker isolate), the public API remains intact. Specific tests in the test suite for multi-connection scenarios have also been added (the Multiple connections group in fbdb_connection_test.dart).

1.7.0

• Added high-level API support for Firebird batch execution, upon a user's request. See section 8 of the fbdb programmer's guide for details. The low-level IBatch interface was present from the very beginning, but in this release there's a dedicated, easy to use FbBatch object, abstracting the technical details away. It also fully supports blob inlining.

1.6.3

• Unloading of the fbclient native dynamic library (via calling DynamicLibrary.close()) is omitted on non-Windows systems. On Linux (and possibly other unix-based systems) the fbclient library doesn't handle unloading graciously (see issue #17), causing an unhandled exception in native C++ code, resulting in an artificial, ~1 minute delay in Dart code, followed by killing the whole process. Kudos to IgorGZd for detecting, diagnosing and reporting the issue.

1.6.2

• The FbServerException class has been enhanced with two attributes: messageValid and messageBytes. The firs one indicates whether the error message sent by the server is a valid UTF-8 and was successfully decoded, the second one contains the raw bytes of the error message, exactly as returned by IUtil.formatStatus. If the error message returned by the server contains invalid UTF-8 sequences, FbServerException.message will contain Unicode substitute characters (\u{FFFD}), and messageValid will be false. In this case the client code may wish to use messageBytes directy, with a custom decoder. If FbServerException.messageValid is true, the message was decoded from UTF-8 without problems. See issue #15 for more details.

1.6.1

• Fixed compatibility issues with recent Dart SDK (compilation errors regarding arithmetic operations in case statements). Fixed some stylistic code issues reported by the Dart analyzer (using null-aware markers instead of explicit null checks with collection ifs).

1.6.0

• Added the dbCollation parameter to FBOptions (this resolves issue #13), which allows to define the default collation of the database being created (it is relevant only when calling createDatabase, attach ignores it). Section 2.4 of the FbDb Programmer's Guide updated accordingly.

1.5.1

• Code reformatted accorting to the recent Dart formatting standards (dart format executed on all source files). No functional changes.

1.5.0

• Upgraded Dart SDK to 3.8.0 and all dependencies to their current versions.
• Added support for the TIME WITH TIME ZONE and TIMESTAMP WITH TIME ZONE Firebird data types. Please refer to the FbDb Programmer's Guide section 7 for more details.

1.4.0

• Implemented multiple concurrent transactions. The FbDb Programmer's Guide has been updated accordingly (section 5.4 added), a new example has also been added: examples/fbdb/ex_13_concurrent_transactions.dart.
• Added a section in FbDb Programmer's Guide on how to use fbdb with stored procedures (section 4.7).
• Added a section (section 4.8) in FbDb Programmer's Guide on how to process DML queries with the RETURNING clause (i.e. queries that modify and return data at the same time).
• Added some more information in FbDb Programmer's Guide (in section 6.2) about retrieving blobs in segments (inspired by issue #9).
• Changed the return type of FbDb.selectAll to be non-nullable (i.e. List<Map<String, dynamic>> instead of List<Map<String, dynamic>>?). Although it is not a breaking change (and therefore does not justify bumping the version number to 2.0.0), it may cause some linting hints about unneccessary null checks if the list returned by selectAll was explicitly checked against null in client code.
• Added some convenient aliases for FbQuery methods: fetch is an alias for fetchAsMaps, fetchOne is an alias for fetchOneAsMap, fetchAll is an alias for fetchAllAsMaps and getOutput is an alias for getOutputAsMap. Since getting data from queries as maps seems to be the most frequently used way, the aliases may make the client code more concise and elegant.

1.3.4

• No actual code changes. Version bumped to force re-analysis of the package at pub.dev (code analysis of 1.3.3 at pub.dev broke, resulting in "platforms unknown" and incomplete README at the landing page).

1.3.3

• Fixed a bug that sometimes prevented Firebird error messages from being passed from the worker isolate to the main isolate (which resulted in an FbServerException without the actual error message getting caught in the main isolate).

1.3.2

• Added an example showing how to use prepared queries and what efficiency gain they may give you in some scenarios. See examples/fbdb/ex_12_prepared_statements.dart.

1.3.1

• Added a more robust implementation of the fix to issue #7, based on runes rather than simple string length. Truncating a string in Dart to the given length truncates in fact UTF-16 code points, and not characters, which may result in too many actual characters being truncated (when the character codes exceed 0xFFFF and require two UTF-16 code points to encode a single character). Added specific test cases for selecting such character combinations as CHAR(N) values.

1.3.0

• Implemented prepared statements. Now you can prepare a query once, and then execute it multiple times, with different values passed as parameters each time (see section 4.6 of the FbDb Programmer's Guide for more details and an example).

1.2.2

• A better solution to issue #7 was implemented, taking into account the actual encoding of a particular text value returned as CHAR(N) by a query, and truncating the value only if the character set is other than NONE, ASCII or OCTETS. In case of those three no truncation is necessary (truncating might actually remove intentional spaces from the end of the text).

1.2.1

• Fixed issue #7, which is a regression caused by a way issue #5 was fixed. While truncating the returned text in a CHAR field to the reported byte length divided by 4 (maximum 4 bytes per Unicode character in UTF-8 encoding) works fine for databases encoded in UTF-8, it doesn't work for databases with character set NONE, ASCII or OCTETS. In this release, the truncating is restricted to trailing spaces only.

1.2.0

• Implemented FbDb.execute and FbDb.runInTransaction utility methods. Together with FbDb.selectOne and FbDb.selectAll they cover all common scenarios, allowing to interact with databases without explicit creation of query objects and handling transactions by hand.
• Fixed a subtle bug, causing an exception thrown by a failing query to be repeated as a result of the next query (even if the next query was in fact executed successfully), but only if both queries were executed in a single explicit transaction. The bug was not reported as a GitHub issue, it manifested itself by accident in some test code for the new FbDb.runInTransaction method.

1.1.3

• Updated dependencies, fixed some wording in README (roadmap section listed array types twice).

1.1.2

• Fixed issue #5 - CHAR fields right-padded with extra spaces due to 4-byte UTF-8 representation of each field character and the fact, that the Firebird client library reports the size of a returned CHAR field in bytes, not in characters. Detailed explanation can be found in this article at StackOverflow.

1.1.1

• Fixed issue #4: parameters being bound as VARCHAR could get truncated by 2 characters if they reach the maximum length reported by message metadata. This was due to the fact, that fbdb treated the 2-byte character count of a VARCHAR parameter as taking 2 bytes out of the reported parameter length (that's why exactly 2 characters were chopped off), while in fact the reported length mean just the maximum number of characters (and the 2-byte character count is not included). When the database used UTF-8 as field encoding, the issue was usually invisible, because in that case the actual number of bytes in the parameter buffer is 4 times the number of characters (and the extra 2-byte length almost always fit in the extra space).

1.1.0

• Added comatibility with the Firebird client libraries version 3.x (versions older than 3.0 don't work and will not work, as they don't expose interfaces-based API to the client code). Please note, that some functionality of the API, introduced in later versions of Firebird, will not be available when using client libraries from the previous versions (e.g. dec16, dec34 and time zones aren't supported when using client libraries from version 3). The appropriate Dart wrappers over native Firebird interfaces now use conditional method binding, throwing UnimplementedError when being invoked with an incompatible version of the client library. As a rule of thumb, it's always best to use the most recent officially available Firebird client library with fbdb.

• Verified compatibility with the Firebird libraries version 5.x in all currently supported Firebird client interfaces.

1.0.2

• Fixed a bug related to issue #3. The bug manifested itself when an error was reported by Firebird, but the actual error message could not be obtained by IUtil due to a malformed UTF-8 string (so there was an error while handling another error).

1.0.1

• Completed API documentation.

1.0.0

• The first published version.