Those who want to use the open source Firebird database server with Python using SQLAlchemy need to provide a dialect that SQLAlchemy can use to communicate to the database, because Firebird is not among the included dialects.
This package provides a Firebird dialect for SQLAlchemy using the Python Database API 2.0 compliant support provided from either firebird-driver or fdb.
Installation
The pip command to install the sqlalchemy-firebird package is:
pip install sqlalchemy-firebird
If you are using Python 3.8+, installing sqlalchemy-firebird will automatically install SQLAlchemy 2.0+ and firebird-driver. This configuration can be used to access Firebird server versions 3 and up. If you need to access a Firebird version 2.5 server, just install fdb using pip:
pip install fdb
If you are using a version of Python less than 3.8, SQLAlchemy 1.4+ and fdb are automatically installed, which can only be used for Firebird server versions 2.5.9 and 3.0+.
Getting Started
The first thing you need when connecting your application to the database using SQLAlchemy is an engine object, obtained by calling create_engine with the appropriate parameters. This can be a connection string (also known as a database uniform resource identifier/locator, dburi or dburl for short), or the URL object returned by calling create from sqlalchemy.engine.URL.
The following information is needed to make the connection string:
- <driver_name> - which driver to use; 'firebird' to use firebird-driver, or 'fdb' to use the fdb driver
- <username> - Firebird default is 'sysdba'
- <password> - Firebird default is 'masterkey'
- <host> - the location of the database server
- <port> - Firebird default is '3050'
- <database_path> - location of the database file
- <charset> - character set used by the database file, Firebird default is UTF8
- <client_library_path> - path to the firebird client library file. Linux needs 'libfbclient.so', Windows uses fblient.dll. This is only needed when using the embedded server or a remotely installed server.
Connection Strings
A typical connection string for SQLAlchemy is dialect+driver://username:password@host:port/database.
The template for a Firebird connection string looks like this (using the information listed above):
firebird+<driver_name>://<username>:<password>@<host>:<port>/<database_path>[?charset=UTF8&key=value&key=value...]
Note the only differences between the Linux and Windows versions of the following example configuration strings is that the Linux paths begin with '//home/testuser' while the Windows paths begin with 'c:/':
- The simplest configuration string is for the Firebird server installed locally using the default port.
[Linux] # Use the fdb driver (Python 3.6/3.7, or Firebird server 2.5.9) firebird+fdb://sysdba:masterkey@localhost///home/testuser/projects/databases/my_project.fdb # Use the firebird-driver driver (Python 3.8+, Firebird server 3.0 or greater) firebird+firebird://sysdba:masterkey@localhost///home/testuser/projects/databases/my_project.fdb [Windows] # Use the fdb driver (Python 3.6/3.7, or Firebird server 2.5.9) firebird+fdb://sysdba:masterkey@localhost/c:/projects/databases/my_project.fdb # Use the firebird-driver driver (Python 3.8+, Firebird server 3.0 or greater) firebird+firebird://sysdba:masterkey@localhost/c:/projects/databases/my_project.fdb
- Firebird server installed remotely using port 3040 and specifying the character set to use
[Linux] # Use the fdb driver (Python 3.6/3.7, or Firebird server 2.5.9) firebird+fdb://sysdba:masterkey@localhost:3040///home/testuser/databases/my_project.fdb?charset=UTF8&fb_library_name=//home/testuser/dbclient/lib/libfbclient.so # Use the firebird-driver driver (Python 3.8+) firebird+firebird://sysdba:masterkey@localhost:3040///home/testuser/databases/my_project.fdb?charset=UTF8&fb_client_library=//home/testuser/dbclient/lib/libfbclient.so [Windows] # Use the fdb driver (Python 3.6/3.7, or Firebird server 2.5.9) firebird+fdb://sysdba:masterkey@localhost:3040/c:/projects/databases/my_project.fdb?charset=UTF8&fb_library_name=c:/projects/dbclient/fbclient.dll # Use the firebird-driver driver (Python 3.8+) firebird+firebird://sysdba:masterkey@localhost:3040/c:/projects/databases/my_project.fdb?charset=UTF8&fb_client_library=c:/projects/dbclient/fbclient.dll
- Firebird embedded server specifying the character set to use
[Linux] # Use the fdb driver (Python 3.6/3.7, or Firebird server 2.5.9) firebird+fdb://sysdba@///home/testuser/databases/my_project.fdb?charset=UTF8&fb_library_name=//home/testuser/dbserver/lib/libfbclient.so # Use the firebird-driver driver (Python 3.8+) firebird+firebird://sysdba@///home/testuser/databases/my_project.fdb?charset=UTF8&fb_client_library=//home/testuser/dbserver/lib/libfbclient.so [Windows] # Use the fdb driver (Python 3.6/3.7, or Firebird server 2.5.9) firebird+fdb://sysdba@/c:/projects/databases/my_project.fdb?charset=UTF8&fb_library_name=c:/projects/dbserver/fbclient.dll # Use the firebird-driver driver (Python 3.8+) firebird+firebird://sysdba@/c:/projects/databases/my_project.fdb?charset=UTF8&fb_client_library=c:/projects/dbserver/fbclient.dll
How to use
For example, to connect to an embedded Firebird server using firebird-driver on Windows:
db_uri = "firebird+firebird://sysdba@/c:/projects/databases/my_project.fdb?charset=UTF8&fb_client_library=c:/projects/databases/fb40_svr/fbclient.dll"
from sqlalchemy import create_engine
engine = create_engine(db_uri, echo=True)
# force the engine to connect, revealing any problems with the connection string
with engine.begin():
pass
Connecting to different types of Firebird servers, databases, or drivers is done simply by changing the db_uri string used in the call to create_engine.
Code of Conduct
As with SQLAlchemy, sqlalchemy-firebird places great emphasis on polite, thoughtful, and constructive communication between users and developers. We use the SQLAlchemy Code of Conduct.
License
sqlalchemy-firebird is distributed under the MIT license.
